Ethereum Improvement Proposals (EIPs & ERCs) describe standards for the Ethereum platform, such as core protocol changes and application-level standards. Zola 2026-04-25T12:06:20+00:00 https://wg-eips.ritovision.com/type/standards-track/atom.xml 2026-02-06T00:00:00+00:00 2026-02-11T14:49:27+00:00 Chris Matahttps://github.com/protocolwhisper https://wg-eips.ritovision.com/8149/

Verify multiple (z, y) evaluations against a single EIP-4844 blob commitment in one precompile call.

<h2 id="abstract">Abstract</h2> <p>Add a precompile that verifies multiple KZG openings <code>(z_i, y_i)</code> for a single <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> blob commitment, returning the same 64-byte output as the existing point-evaluation precompile.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> provides a point-evaluation precompile at <code>0x0A</code> costing 50,000 gas per opening. Contracts needing multiple blob values (e.g., fraud proofs) must pay this cost repeatedly. A batch interface verifies <em>k</em> openings in one call, reducing overhead.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="constants">Constants</h3> <table><thead><tr><th>Name</th><th>Value</th><th>Comment</th></tr></thead><tbody> <tr><td><code>MULTI_POINT_EVALUATION_PRECOMPILE_ADDRESS</code></td><td><code>TBD</code></td><td>precompile address</td></tr> <tr><td><code>MAX_MULTI_POINTS</code></td><td><code>128</code></td><td>maximum number of evaluation points</td></tr> <tr><td><code>MULTI_POINT_EVALUATION_BASE_GAS</code></td><td><code>TBD</code></td><td>base gas cost</td></tr> <tr><td><code>MULTI_POINT_EVALUATION_PER_POINT_GAS</code></td><td><code>TBD</code></td><td>gas cost per evaluation point</td></tr> </tbody></table> <p>We introduce a precompile to perform multi KZG point evaluation:</p> <p>It verifies multiple KZG openings <code>(z_i, y_i)</code> for a single EIP-4844 blob commitment in one call. The verification uses BLS12-381 pairing operations internally to check the multi-point opening proof. Gas cost is defined by <code>MULTI_POINT_EVALUATION_BASE_GAS + MULTI_POINT_EVALUATION_PER_POINT_GAS * n</code> where <code>n</code> is the number of evaluation points.</p> <h3 id="input">Input</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>versioned_hash : Bytes32</span></span> <span class="giallo-l"><span>commitment : Bytes48</span></span> <span class="giallo-l"><span>n : uint32 (big-endian)</span></span> <span class="giallo-l"><span>pairs : n × (z: Bytes32, y: Bytes32)</span></span> <span class="giallo-l"><span>proof : Bytes48</span></span></code></pre> <p>Total length: <code>132 + (n × 64)</code> bytes. All <code>z</code> and <code>y</code> MUST be strictly less than <code>BLS_MODULUS</code>.</p> <h3 id="output">Output</h3> <p>On success, return 64 bytes identical to <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>FIELD_ELEMENTS_PER_BLOB : uint256 (big-endian)</span></span> <span class="giallo-l"><span>BLS_MODULUS : uint256 (big-endian)</span></span></code></pre><h3 id="multi-point-evaluation-precompile">Multi-point evaluation precompile</h3> <p>Add a precompile at <code>MULTI_POINT_EVALUATION_PRECOMPILE_ADDRESS</code> that verifies multiple KZG openings <code>(z_i, y_i)</code> for a single EIP-4844 blob commitment.</p> <p>The precompile executes the following logic:</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"> multi_point_evaluation_precompile</span><span>(</span><span class="z-variable z-parameter z-function">input</span><span>:</span><span> Bytes</span><span>)</span><span> -&gt;</span><span> Bytes</span><span>:</span></span> <span class="giallo-l"><span> versioned_hash</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span>:</span><span class="z-constant">32</span><span>]</span></span> <span class="giallo-l"><span> commitment</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span class="z-constant">32</span><span>:</span><span class="z-constant">80</span><span>]</span></span> <span class="giallo-l"><span> n</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span class="z-support">input</span><span>[</span><span class="z-constant">80</span><span>:</span><span class="z-constant">84</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> </span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-constant"> 1</span><span class="z-keyword"> &lt;=</span><span> n</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> MAX_MULTI_POINTS</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span class="z-support">input</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 132</span><span class="z-keyword"> +</span><span> n</span><span class="z-keyword"> *</span><span class="z-constant"> 64</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> z_values</span><span>,</span><span> y_values</span><span class="z-keyword"> =</span><span> [</span><span>]</span><span>,</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span>n</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> offset</span><span class="z-keyword"> =</span><span class="z-constant"> 84</span><span class="z-keyword"> +</span><span> i</span><span class="z-keyword"> *</span><span class="z-constant"> 64</span></span> <span class="giallo-l"><span> z_i</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span class="z-support">input</span><span>[</span><span>offset</span><span>:</span><span>offset</span><span class="z-keyword">+</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> y_i</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span class="z-support">input</span><span>[</span><span>offset</span><span class="z-keyword">+</span><span class="z-constant">32</span><span>:</span><span>offset</span><span class="z-keyword">+</span><span class="z-constant">64</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 class="z-keyword"> assert</span><span> z_i</span><span class="z-keyword"> &lt;</span><span class="z-constant"> BLS_MODULUS</span><span class="z-keyword"> and</span><span> y_i</span><span class="z-keyword"> &lt;</span><span class="z-constant"> BLS_MODULUS</span></span> <span class="giallo-l"><span> z_values</span><span>.</span><span>append</span><span>(</span><span>z_i</span><span>)</span></span> <span class="giallo-l"><span> y_values</span><span>.</span><span>append</span><span>(</span><span>y_i</span><span>)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> proof</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span class="z-constant">84</span><span class="z-keyword"> +</span><span> n</span><span class="z-keyword">*</span><span class="z-constant">64</span><span> :</span><span class="z-constant"> 84</span><span class="z-keyword"> +</span><span> n</span><span class="z-keyword">*</span><span class="z-constant">64</span><span class="z-keyword"> +</span><span class="z-constant"> 48</span><span>]</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> kzg_to_versioned_hash</span><span>(</span><span>commitment</span><span>)</span><span class="z-keyword"> ==</span><span> versioned_hash</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> verify_kzg_proof_multi</span><span>(</span><span>commitment</span><span>,</span><span> z_values</span><span>,</span><span> y_values</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> U256</span><span>(</span><span class="z-constant">FIELD_ELEMENTS_PER_BLOB</span><span>)</span><span>.</span><span>to_be_bytes32</span><span>(</span><span>)</span><span class="z-keyword"> +</span><span> U256</span><span>(</span><span class="z-constant">BLS_MODULUS</span><span>)</span><span>.</span><span>to_be_bytes32</span><span>(</span><span>)</span></span></code></pre> <p>The <code>verify_kzg_proof_multi</code> function performs multi-point opening verification using the <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> trusted setup and BLS12-381 pairing operations. Implementations typically use Lagrange interpolation to construct a polynomial through all <code>(z_i, y_i)</code> pairs, which has O(n²) complexity. When evaluation points align with roots of unity, FFT-based methods reduce this to O(n log n). The final verification step uses a single pairing check to verify all openings simultaneously.</p> <h3 id="gas-cost">Gas Cost</h3> <p>The gas cost for multi point evaluation is:</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"> gas_cost</span><span>(</span><span class="z-variable z-parameter z-function">n</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"> return</span><span class="z-constant"> MULTI_POINT_EVALUATION_BASE_GAS</span><span class="z-keyword"> +</span><span class="z-constant"> MULTI_POINT_EVALUATION_PER_POINT_GAS</span><span class="z-keyword"> *</span><span> n</span></span></code></pre> <p>Gas constants SHOULD ensure batching is cheaper than <code>n</code> separate <code>0x0A</code> calls for <code>n &gt; 1</code>. The verification internally uses BLS12-381 pairing operations, which are computationally expensive but enable efficient batch verification of multiple openings.</p> <h2 id="rationale">Rationale</h2> <ul> <li>Preserves <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> versioned-hash model and return format.</li> <li>Adds a new precompile rather than modifying <code>0x0A</code> to avoid compatibility risks.</li> <li><code>MAX_MULTI_POINTS = 128</code> bounds input size while enabling meaningful savings.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No changes to <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> transactions, <code>BLOBHASH</code>, or the existing precompile at <code>0x0A</code>.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>Reject non-canonical field elements (<code>&gt;= BLS_MODULUS</code>).</li> <li>Implementations MUST use the same trusted setup and subgroup checks as <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>.</li> <li>Gas pricing MUST reflect actual computational cost.</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> 2026-02-05T00:00:00+00:00 2026-02-11T14:49:27+00:00 Dmitry Gusakovhttps://github.com/dgusakov Dmitry Chernukhinhttps://github.com/madlabman Greg Koumoutsoshttps://github.com/gkoumout https://wg-eips.ritovision.com/8148/

Allow setting custom balance thresholds for sweep withdrawals for validators with compounding withdrawal credentials (`0x02, 0x03`).

<h2 id="abstract">Abstract</h2> <p>This EIP proposes an optional mechanism to set custom balance thresholds for sweep withdrawals for compounding withdrawal credentials (<code>0x02, 0x03</code>) validators. This mechanism allows validators to specify above which balance they want their rewards to be swept to their withdrawal address, providing greater flexibility and control over their staking rewards.</p> <h2 id="motivation">Motivation</h2> <p>The current default sweep threshold (2,048 ETH) for validators using compounding withdrawal credentials (<code>0x02, 0x03</code>) may not meet the needs of all validators. Some validators may prefer to accumulate rewards on the validator balance, while others may want to sweep before reaching the current threshold of 2,048 ETH. By allowing optional custom sweep thresholds, validators can optimize their reward management according to their individual strategies and preferences.</p> <p>Since the introduction of the <code>0x02</code> compounding withdrawal credentials type, we have observed a very low rate of validators transitioning to <code>0x02</code>. One reason is that many validators do not want to wait until they accumulate 2048 ETH in rewards before being able to participate in the automatic sweep of withdrawals. While partial withdrawals were considered a viable method for manually withdrawing portions of the validator balance, this approach was not widely adopted by staking protocols, node operators, and solo stakers for several reasons. First, it requires a user-initiated transaction to perform a withdrawal. Second, partial withdrawals utilize the general exit queue, which makes the time between partial withdrawal initiation and fulfillment unpredictable and heavily dependent on network conditions (see the recent spike in exit queue size in October 2025). This EIP aims to address this issue by allowing validators to set a custom threshold for sweep withdrawals.</p> <p>A simple example illustrates the utility of this feature. Consider a validator who wishes to accumulate rewards on their validator balance until reaching 128 ETH, at which point they want to sweep the rewards to their withdrawal address. Without this feature, the validator would have to initiate partial withdrawals at certain intervals manually and wait in the partial withdrawals queue, which can be time-consuming and inconvenient. The first inconvenience is that if staking protocols widely adopt partial withdrawals at some point, the queue for these withdrawals might become long and unpredictable, similar to the exit queue. The second inconvenience is that the user must monitor the validator's balance and manually initiate partial withdrawals, which adds complexity and overhead to the staking process. The third inconvenience is the frequency with which the validator can request partial withdrawals. A 128-ETH validator will receive approximately 0.07 ETH in rewards each week. Initiating partial withdrawals TX, for such a low amount might be considered unreasonable. At the same time, the sweep cycle will likely drop to a weekly cycle relatively soon, allowing the validator to automatically receive these 0.07 ETH of rewards on their withdrawal credentials. In general, with this EIP, the validator can set their desired sweep threshold and automatically benefit from sweep withdrawals.</p> <p>The proposed mechanism is completely optional and does not change anything in the default registration / withdrawal / exit process for validators. It's just an additional feature that could be ignored if not interesting, but provides a useful feature for many validators incentivizing switching to compounding validators.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="constants">Constants</h3> <h4 id="execution-layer">Execution layer</h4> <table><thead><tr><th>Name</th><th>Value</th><th>Comment</th></tr></thead><tbody> <tr><td><code>SET_SWEEP_THRESHOLD_REQUEST_TYPE</code></td><td><code>0x03</code></td><td>The <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> type prefix for set sweep threshold request</td></tr> <tr><td><code>SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</code></td><td><code>TBD</code></td><td>Where to call and store relevant details about set sweep threshold request mechanism</td></tr> <tr><td><code>SYSTEM_ADDRESS</code></td><td><code>0xfffffffffffffffffffffffffffffffffffffffe</code></td><td>Address used to invoke system operation on contract</td></tr> <tr><td><code>EXCESS_SET_SWEEP_THRESHOLD_REQUESTS_STORAGE_SLOT</code></td><td><code>0</code></td><td></td></tr> <tr><td><code>SET_SWEEP_THRESHOLD_REQUEST_COUNT_STORAGE_SLOT</code></td><td><code>1</code></td><td></td></tr> <tr><td><code>SET_SWEEP_THRESHOLD_REQUEST_QUEUE_HEAD_STORAGE_SLOT</code></td><td><code>2</code></td><td>Pointer to the head of the set sweep threshold request message queue</td></tr> <tr><td><code>SET_SWEEP_THRESHOLD_REQUEST_QUEUE_TAIL_STORAGE_SLOT</code></td><td><code>3</code></td><td>Pointer to the tail of the set sweep threshold request message queue</td></tr> <tr><td><code>SET_SWEEP_THRESHOLD_REQUEST_QUEUE_STORAGE_OFFSET</code></td><td><code>4</code></td><td>The start storage slot of the in-state set sweep threshold request message queue</td></tr> <tr><td><code>MAX_SET_SWEEP_THRESHOLD_REQUESTS_PER_BLOCK</code></td><td><code>16</code></td><td>Maximum number of set sweep threshold requests that can be dequeued into a block</td></tr> <tr><td><code>TARGET_SET_SWEEP_THRESHOLD_REQUESTS_PER_BLOCK</code></td><td><code>2</code></td><td></td></tr> <tr><td><code>MIN_SET_SWEEP_THRESHOLD_REQUEST_FEE</code></td><td><code>1</code></td><td></td></tr> <tr><td><code>SET_SWEEP_THRESHOLD_REQUEST_FEE_UPDATE_FRACTION</code></td><td><code>17</code></td><td></td></tr> <tr><td><code>EXCESS_INHIBITOR</code></td><td><code>2**256-1</code></td><td>Excess value used to compute the fee before the first system call</td></tr> </tbody></table> <h4 id="consensus-layer">Consensus layer</h4> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><code>MIN_SWEEP_THRESHOLD</code></td><td><code>MIN_ACTIVATION_BALANCE + Gwei(1 * 10**9)</code> (33 ETH)</td></tr> </tbody></table> <h3 id="execution-layer-1">Execution layer</h3> <h4 id="definitions">Definitions</h4> <ul> <li><strong><code>FORK_BLOCK</code></strong> -- the first block in a blockchain after this EIP has been activated.</li> </ul> <h4 id="set-sweep-threshold-request">Set sweep threshold request</h4> <p>The new set sweep threshold request is an <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> request with type <code>SET_SWEEP_THRESHOLD_REQUEST_TYPE</code> consisting of the following fields:</p> <ol> <li><code>source_address</code>: <code>Bytes20</code></li> <li><code>validator_pubkey</code>: <code>Bytes48</code></li> <li><code>threshold</code>: <code>uint64</code></li> </ol> <p>The <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> encoding of a set sweep threshold request is computed as follows. Note that <code>threshold</code> is returned by the contract little-endian, and must be encoded as such.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>request_type</span><span class="z-keyword"> =</span><span class="z-constant"> SET_SWEEP_THRESHOLD_REQUEST_TYPE</span></span> <span class="giallo-l"><span>request_data</span><span class="z-keyword"> =</span><span> read_set_sweep_threshold_requests</span><span>(</span><span>)</span></span></code></pre><h4 id="set-sweep-threshold-request-contract">Set sweep threshold request contract</h4> <p>The contract has three different code paths, which can be summarized at a high level as follows:</p> <ol> <li>Add set sweep threshold request - requires a 56-byte input: validator public key concatenated with a big-endian <code>uint64</code> threshold value.</li> <li>Fee getter - if the input length is zero, return the current fee required to add a set sweep threshold request.</li> <li>System process - if called by the system address, pop off the set sweep threshold requests for the current block from the queue.</li> </ol> <h5 id="add-set-sweep-threshold-request">Add Set Sweep Threshold Request</h5> <p>If call data input to the contract is exactly <code>56</code> bytes, perform the following:</p> <ol> <li>Ensure enough ETH was sent to cover the current set sweep threshold request fee (<code>msg.value &gt;= get_fee()</code>).</li> <li>Increase set sweep threshold request count by 1 for the current block.</li> <li>Insert a set sweep threshold request into the queue for the source address, validator public key, and the threshold.</li> </ol> <p>Specifically, the functionality is defined in pseudocode as the function <code>add_set_sweep_threshold_request()</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"> add_set_sweep_threshold_request</span><span>(</span><span class="z-variable z-parameter z-function">validator_pubkey</span><span>:</span><span> Bytes48</span><span>,</span><span class="z-variable z-parameter z-function"> threshold</span><span>:</span><span> uint64</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"> Add a new request to the set sweep threshold request queue, provided a sufficient value to cover the fee was sent.</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify sufficient value was provided.</span></span> <span class="giallo-l"><span> fee</span><span class="z-keyword"> =</span><span> get_fee</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> require</span><span>(</span><span>msg</span><span>.</span><span>value</span><span class="z-keyword"> &gt;=</span><span> fee</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Insufficient value for fee</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-punctuation z-definition z-comment"> #</span><span class="z-comment"> Increment the request count.</span></span> <span class="giallo-l"><span> count</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> SET_SWEEP_THRESHOLD_REQUEST_COUNT_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> SET_SWEEP_THRESHOLD_REQUEST_COUNT_STORAGE_SLOT</span><span>,</span><span> count</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-punctuation z-definition z-comment"> #</span><span class="z-comment"> Insert into the queue.</span></span> <span class="giallo-l"><span> queue_tail_index</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> SET_SWEEP_THRESHOLD_REQUEST_QUEUE_TAIL_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> queue_storage_slot</span><span class="z-keyword"> =</span><span class="z-constant"> SET_SWEEP_THRESHOLD_REQUEST_QUEUE_STORAGE_OFFSET</span><span class="z-keyword"> +</span><span> queue_tail_index</span><span class="z-keyword"> *</span><span class="z-constant"> 3</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span>,</span><span> msg</span><span>.</span><span>sender</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>,</span><span> validator_pubkey</span><span>[</span><span class="z-constant"> 0</span><span>:</span><span class="z-constant">32</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span>,</span><span> validator_pubkey</span><span>[</span><span class="z-constant">32</span><span>:</span><span class="z-constant">48</span><span>]</span><span class="z-invalid z-illegal"> ++</span><span> threshold</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> SET_SWEEP_THRESHOLD_REQUEST_QUEUE_TAIL_STORAGE_SLOT</span><span>,</span><span> queue_tail_index</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span></span></code></pre><h6 id="fee-calculation">Fee calculation</h6> <p>The following pseudocode can compute the cost of an individual set sweep threshold request, given a certain number of excess set sweep threshold requests.</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_fee</span><span>(</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span></span> <span class="giallo-l"><span> excess</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> EXCESS_SET_SWEEP_THRESHOLD_REQUESTS_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> require</span><span>(</span><span>excess</span><span class="z-keyword"> !=</span><span class="z-constant"> EXCESS_INHIBITOR</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Inhibitor still active</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> fake_exponential</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> MIN_SET_SWEEP_THRESHOLD_REQUEST_FEE</span><span>,</span></span> <span class="giallo-l"><span> excess</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> SET_SWEEP_THRESHOLD_REQUEST_FEE_UPDATE_FRACTION</span></span> <span class="giallo-l"><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"> fake_exponential</span><span>(</span><span class="z-variable z-parameter z-function">factor</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> numerator</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> denominator</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> i</span><span class="z-keyword"> =</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> output</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> numerator_accum</span><span class="z-keyword"> =</span><span> factor</span><span class="z-keyword"> *</span><span> denominator</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> numerator_accum</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> output</span><span class="z-keyword"> +=</span><span> numerator_accum</span></span> <span class="giallo-l"><span> numerator_accum</span><span class="z-keyword"> =</span><span> (</span><span>numerator_accum</span><span class="z-keyword"> *</span><span> numerator</span><span>)</span><span class="z-keyword"> //</span><span> (</span><span>denominator</span><span class="z-keyword"> *</span><span> i</span><span>)</span></span> <span class="giallo-l"><span> i</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> output</span><span class="z-keyword"> //</span><span> denominator</span></span></code></pre><h5 id="fee-getter">Fee Getter</h5> <p>When the input to the contract has zero-length, interpret this as a get request for the current fee, i.e. the contract returns the result of <code>get_fee()</code>. The contract reverts if any value is sent to prevent loss of funds.</p> <h5 id="system-call">System Call</h5> <p>At the end of processing any execution block starting from the <code>FORK_BLOCK</code> (i.e. after processing all transactions), call <code>SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</code> as <code>SYSTEM_ADDRESS</code> with no calldata. The invocation triggers the following:</p> <ul> <li>The contract's queue is updated based on set sweep threshold requests dequeued and the set sweep threshold requests queue head/tail are reset if the queue has been cleared (<code>dequeue_set_sweep_threshold_requests()</code>)</li> <li>The contract's excess set sweep threshold requests are updated based on usage in the current block (<code>update_excess_set_sweep_threshold_requests()</code>)</li> <li>The contract's set sweep threshold requests count is reset to 0 (<code>reset_set_sweep_threshold_requests_count()</code>)</li> </ul> <p>In response to the system call, the contract returns an opaque byte array of concatenated SSZ-serialized dequeued requests. There's no specific reasoning behind it, except aligning with the existing behaviour of the similar EIP, see <a href="https://wg-eips.ritovision.com/7002/">EIP-7002</a>, and possible simplification of the processing flow for client teams. Each set sweep threshold request must appear in the EIP-7685 requests list in the exact order returned by <code>dequeue_set_sweep_threshold_requests()</code>.</p> <p>Additionally, the system call and the processing of that block must conform to the following:</p> <ul> <li>The call has a dedicated gas limit of <code>30_000_000</code> (<code>SYSTEM_TRANSACTION_GAS</code>) and is not subject to the transaction limit cap introduced in <a href="https://wg-eips.ritovision.com/7825/">EIP-7825</a>.</li> <li>Gas consumed by this call does not count against the block’s overall gas usage.</li> <li>Both the gas limit assigned to the call and the gas consumed are excluded from any checks against the block’s gas limit.</li> <li>The call does not follow <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fee burn semantics — no value should be transferred as part of this call.</li> <li>If there is no code at <code>SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</code>, the corresponding block <strong>MUST</strong> be marked invalid.</li> <li>If the call to the contract fails or returns an error, the block <strong>MUST</strong> be invalidated.</li> </ul> <p>The functionality triggered by the system call is defined in pseudocode as the function <code>read_set_sweep_threshold_requests()</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">##################</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Public function #</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> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> read_set_sweep_threshold_requests</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> reqs</span><span class="z-keyword"> =</span><span> dequeue_set_sweep_threshold_requests</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> update_excess_set_sweep_threshold_requests</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> reset_set_sweep_threshold_requests_count</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-punctuation z-definition z-string">&quot;</span><span>.</span><span>join</span><span>(</span><span>ssz</span><span>.</span><span>serialize</span><span>(</span><span>r</span><span>)</span><span class="z-keyword"> for</span><span> r</span><span class="z-keyword"> in</span><span> reqs</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"> Helpers #</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> <span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> ValidatorSetSweepThresholdRequest</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> source_address</span><span>:</span><span> Bytes20</span></span> <span class="giallo-l"><span> validator_pubkey</span><span>:</span><span> Bytes48</span></span> <span class="giallo-l"><span> threshold</span><span>:</span><span> uint64</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"> dequeue_set_sweep_threshold_requests</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> queue_head_index</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> SET_SWEEP_THRESHOLD_REQUEST_QUEUE_HEAD_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> queue_tail_index</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> SET_SWEEP_THRESHOLD_REQUEST_QUEUE_TAIL_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> num_in_queue</span><span class="z-keyword"> =</span><span> queue_tail_index</span><span class="z-keyword"> -</span><span> queue_head_index</span></span> <span class="giallo-l"><span> num_dequeued</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span>num_in_queue</span><span>,</span><span class="z-constant"> MAX_SET_SWEEP_THRESHOLD_REQUESTS_PER_BLOCK</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> reqs</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span>num_dequeued</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> queue_storage_slot</span><span class="z-keyword"> =</span><span class="z-constant"> SET_SWEEP_THRESHOLD_REQUEST_QUEUE_STORAGE_OFFSET</span><span class="z-keyword"> +</span><span> (</span><span>queue_head_index</span><span class="z-keyword"> +</span><span> i</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> 3</span></span> <span class="giallo-l"><span> source_address</span><span class="z-keyword"> =</span><span> address</span><span>(</span><span>sload</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span>)</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">20</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> validator_pubkey</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> sload</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">32</span><span>]</span><span class="z-keyword"> +</span></span> <span class="giallo-l"><span> sload</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span>)</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">16</span><span>]</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> threshold</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span>)</span><span>[</span><span class="z-constant">16</span><span>:</span><span class="z-constant">24</span><span>]</span></span> <span class="giallo-l"><span> req</span><span class="z-keyword"> =</span><span> ValidatorSetSweepThresholdRequest</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> source_address</span><span class="z-keyword">=</span><span>Bytes20</span><span>(</span><span>source_address</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> validator_pubkey</span><span class="z-keyword">=</span><span>Bytes48</span><span>(</span><span>validator_pubkey</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> threshold</span><span class="z-keyword">=</span><span>uint64</span><span>(</span><span>threshold</span><span>)</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> reqs</span><span>.</span><span>append</span><span>(</span><span>req</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> new_queue_head_index</span><span class="z-keyword"> =</span><span> queue_head_index</span><span class="z-keyword"> +</span><span> num_dequeued</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> new_queue_head_index</span><span class="z-keyword"> ==</span><span> queue_tail_index</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Queue is empty, reset queue pointers</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> SET_SWEEP_THRESHOLD_REQUEST_QUEUE_HEAD_STORAGE_SLOT</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> SET_SWEEP_THRESHOLD_REQUEST_QUEUE_TAIL_STORAGE_SLOT</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> sstore</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> SET_SWEEP_THRESHOLD_REQUEST_QUEUE_HEAD_STORAGE_SLOT</span><span>,</span><span> new_queue_head_index</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> reqs</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"> update_excess_set_sweep_threshold_requests</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> previous_excess</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> EXCESS_SET_SWEEP_THRESHOLD_REQUESTS_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> previous_excess</span><span class="z-keyword"> ==</span><span class="z-constant"> EXCESS_INHIBITOR</span><span>:</span></span> <span class="giallo-l"><span> previous_excess</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> count</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> SET_SWEEP_THRESHOLD_REQUEST_COUNT_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> new_excess</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> previous_excess</span><span class="z-keyword"> +</span><span> count</span><span class="z-keyword"> &gt;</span><span class="z-constant"> TARGET_SET_SWEEP_THRESHOLD_REQUESTS_PER_BLOCK</span><span>:</span></span> <span class="giallo-l"><span> new_excess</span><span class="z-keyword"> =</span><span> previous_excess</span><span class="z-keyword"> +</span><span> count</span><span class="z-keyword"> -</span><span class="z-constant"> TARGET_SET_SWEEP_THRESHOLD_REQUESTS_PER_BLOCK</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> EXCESS_SET_SWEEP_THRESHOLD_REQUESTS_STORAGE_SLOT</span><span>,</span><span> new_excess</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"> reset_set_sweep_threshold_requests_count</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">SET_SWEEP_THRESHOLD_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> SET_SWEEP_THRESHOLD_REQUEST_COUNT_STORAGE_SLOT</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span></code></pre><h5 id="bytecode">Bytecode</h5> <p>The following bytecode is produced by the geas compiler from the source code in the sys-asm repository.</p> <pre class="giallo z-code"><code data-lang="asm"><span class="giallo-l"><span>caller</span></span> <span class="giallo-l"><span>push20 </span><span class="z-constant">0xfffffffffffffffffffffffffffffffffffffffe</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0xcb</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x11</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push32 </span><span class="z-constant">0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01f4</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span>gt</span></span> <span class="giallo-l"><span>iszero</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x68</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>dup4</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>dup5</span></span> <span class="giallo-l"><span>dup4</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span class="z-keyword">div</span></span> <span class="giallo-l"><span>swap2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>swap2</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x4d</span></span> <span class="giallo-l"><span>jump</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>swap4</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span class="z-keyword">div</span></span> <span class="giallo-l"><span>swap3</span></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span>calldatasize</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x38</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x88</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>calldatasize</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01f4</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>callvalue</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01f4</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x20</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>callvalue</span></span> <span class="giallo-l"><span>lt</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01f4</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x04</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>caller</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>calldataload</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x20</span></span> <span class="giallo-l"><span>calldataload</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>caller</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x60</span></span> <span class="giallo-l"><span class="z-keyword">shl</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x38</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x14</span></span> <span class="giallo-l"><span>calldatacopy</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x4c</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>log0</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>stop</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span class="z-keyword">sub</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span>gt</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0xdf</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x0183</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x04</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x4c</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x60</span></span> <span class="giallo-l"><span class="z-keyword">shl</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x14</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x20</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push32 </span><span class="z-constant">0xffffffffffffffffffffffffffffffff00000000000000000000000000000000</span></span> <span class="giallo-l"><span class="z-keyword">and</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x10</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x40</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x38</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x07</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x30</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x06</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x28</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x05</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x20</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x04</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x18</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x10</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x08</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0xe1</span></span> <span class="giallo-l"><span>jump</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>swap2</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>swap3</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x0195</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01a0</span></span> <span class="giallo-l"><span>jump</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push32 </span><span class="z-constant">0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span>iszero</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01cd</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>gt</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01e2</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01e8</span></span> <span class="giallo-l"><span>jump</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span class="z-keyword">sub</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x4c</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>revert</span></span></code></pre><h5 id="deployment">Deployment</h5> <p>The set sweep threshold requests contract is deployed like any other smart contract. A special synthetic address is generated by working backwards from the desired deployment transaction:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>TBD</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Sender: TBD</span></span> <span class="giallo-l"><span>Address: TBD</span></span></code></pre><h3 id="consensus-layer-1">Consensus layer</h3> <p>The defining feature of this EIP is <em><strong>allowing validators to set custom sweep thresholds for their withdrawals when using compounding withdrawal credentials (<code>0x02, 0x03</code>)</strong></em>.</p> <p>The <a href="https://wg-eips.ritovision.com/8148/#rationale">Rationale</a> section contains an explanation for this proposed core feature. A sketch of the resulting changes to the consensus layer is included below.</p> <ol> <li>Update the <code>BeaconState</code> container to include a <code>validator_sweep_thresholds</code> mapping.</li> <li>Add <code>SetSweepThresholdRequest</code> container to represent the set sweep threshold requests dequeued from the execution layer contract.</li> <li>Update the <code>ExecutionRequests</code> container to include a list of <code>SetSweepThresholdRequest</code> items.</li> <li>Add <code>process_set_sweep_threshold_request</code> function to handle the processing of set sweep threshold requests from the execution layer.</li> <li>Modify the <code>process_execution_payload</code> function to include the processing of set sweep threshold requests.</li> <li>Modify the <code>is_partially_withdrawable_validator</code> predicate to take into account the custom sweep threshold.</li> <li>Add <code>get_effective_sweep_threshold</code> helper function to compute the effective sweep threshold for a validator.</li> <li>Modify the <code>get_expected_withdrawals</code> function to use the custom sweep threshold when determining partial withdrawals.</li> </ol> <p>By default, all validators will have their sweep thresholds set to the current default <code>MAX_EFFECTIVE_BALANCE</code>, both for existing validators and new ones. Validators can choose to set a custom threshold above their current balance by submitting a set sweep threshold request through the execution layer contract.</p> <h2 id="rationale">Rationale</h2> <h3 id="overview">Overview</h3> <p>Most of the considerations regarding the messaging format, queue, and rate-limiting are similar to those discussed in <a href="https://wg-eips.ritovision.com/7002/">EIP-7002</a> for withdrawal requests, and so we refer the reader to that EIP for more details.</p> <h3 id="custom-sweep-thresholds">Custom Sweep Thresholds</h3> <p>The primary motivation for this EIP is to allow validators to set custom sweep thresholds for their withdrawals when using compounding withdrawal credentials (<code>0x02, 0x03</code>). This feature provides greater flexibility and control over how and when validators can access their staking rewards.</p> <h3 id="validator-sweep-thresholds-mapping-in-beaconstate"><code>validator_sweep_thresholds</code> mapping in <code>BeaconState</code></h3> <p>To store the custom sweep thresholds for each validator, we introduce a new mapping in the <code>BeaconState</code> container called <code>validator_sweep_thresholds</code>. This mapping associates each validator index with its corresponding sweep threshold. This approach was chosen instead of adding a new field to the <code>Validator</code> container to avoid modification of this type, which had not been changed since phase-0. Modification of the <code>Validator</code> container would have required more extensive changes to the consensus layer and potentially affected existing implementations of the applications using this container. Also, this is the standard way of adding info about validators into the state (e.g., validator balance is stored in <code>balances</code> field of <code>BeaconState</code> and several other PoS-related info have their own lists where each item corresponds to validators' data)</p> <h3 id="only-allowing-threshold-to-be-set-above-current-balance">Only allowing threshold to be set above current balance</h3> <p>This design decision is made to prevent usage of the custom sweep threshold mechanism to trigger immediate withdrawals. By enforcing that the threshold must be set above the current balance, we ensure that validators cannot use this feature to bypass the standard withdrawal process. Should a validator wish to set sweep threshold below current balance, they can first withdraw down to the desired level using partial withdrawals, and then set the sweep threshold accordingly.</p> <h3 id="immediate-requests-processing-instead-of-queuing-on-consensus-layer">Immediate requests processing instead of queuing on consensus layer</h3> <p>Unlike partial withdrawal requests, which are queued on the consensus layer, set sweep threshold requests are processed immediately upon being dequeued from the execution layer contract. This design choice simplifies the implementation and reduces the complexity of managing a separate queue on the consensus layer.</p> <h3 id="min-sweep-threshold-of-33-eth"><code>MIN_SWEEP_THRESHOLD</code> of 33 ETH</h3> <p>To ensure that validators do not set sweep threshold equal to <code>MIN_ACTIVATION_BALANCE</code>, we introduce a minimum sweep threshold of <code>MIN_ACTIVATION_BALANCE + 1</code> ETH (33 ETH). This ensures that people will opt-in to compounding withdrawal credentials only if they really want to accumulate rewards on the validator balance.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces backwards incompatible changes to the block structure and block validation rule set. But neither of these changes break anything related to the current user activity and experience.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Most of the security considerations regarding fee overpayment, system call failure, and empty code failure are similar to those discussed in <a href="https://wg-eips.ritovision.com/7002/">EIP-7002</a> for withdrawal requests, and so we refer the reader to that EIP for more 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> 2026-01-29T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin lightclienthttps://github.com/lightclient Felix Langehttps://github.com/fjl 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/8141/

Add frame abstraction for transaction validation, execution, and gas payment

<h2 id="abstract">Abstract</h2> <p>Add a new transaction whose validity and gas payment can be defined abstractly. Instead of relying solely on a single ECDSA signature, accounts may freely define and interpret their signature scheme using any cryptographic system.</p> <h2 id="motivation">Motivation</h2> <p>This new transaction provides a native off-ramp from the elliptic curve based cryptographic system used to authenticate transactions today, to post-quantum (PQ) secure systems.</p> <p>In doing so, it realizes the original vision of account abstraction: unlinking accounts from a prescribed ECDSA key and support alternative fee payment schemes. The assumption of an account simply becomes an address with code. It leverages the EVM to support arbitrary <em>user-defined</em> definitions of validation and gas payment.</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>FRAME_TX_TYPE</code></td><td><code>0x06</code></td></tr> <tr><td><code>FRAME_TX_INTRINSIC_COST</code></td><td><code>15000</code></td></tr> <tr><td><code>ENTRY_POINT</code></td><td><code>address(0xaa)</code></td></tr> <tr><td><code>MAX_FRAMES</code></td><td><code>10^3</code></td></tr> </tbody></table> <h3 id="opcodes">Opcodes</h3> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><code>APPROVE</code></td><td><code>0xaa</code></td></tr> <tr><td><code>TXPARAMLOAD</code></td><td><code>0xb0</code></td></tr> <tr><td><code>TXPARAMSIZE</code></td><td><code>0xb1</code></td></tr> <tr><td><code>TXPARAMCOPY</code></td><td><code>0xb2</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>FRAME_TX_TYPE</code> is introduced. Transactions of this type are referred to as "Frame transactions".</p> <p>The payload is defined as the RLP serialization of the following:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[chain_id, nonce, sender, frames, max_priority_fee_per_gas, max_fee_per_gas, max_fee_per_blob_gas, blob_versioned_hashes]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>frames = [[mode, target, gas_limit, data], ...]</span></span></code></pre> <p>If no blobs are included, <code>blob_versioned_hashes</code> must be an empty list and <code>max_fee_per_blob_gas</code> must be <code>0</code>.</p> <h4 id="modes">Modes</h4> <p>There are three modes:</p> <table><thead><tr><th>Mode</th><th>Name</th><th>Summary</th></tr></thead><tbody> <tr><td>0</td><td><code>DEFAULT</code></td><td>Execute frame as <code>ENTRY_POINT</code></td></tr> <tr><td>1</td><td><code>VERIFY</code></td><td>Frame identifies as transaction validation</td></tr> <tr><td>2</td><td><code>SENDER</code></td><td>Execute frame as <code>sender</code></td></tr> </tbody></table> <h5 id="default-mode"><code>DEFAULT</code> Mode</h5> <p>Frame executes as regular call where the caller address is <code>ENTRY_POINT</code>.</p> <h5 id="verify-mode"><code>VERIFY</code> Mode</h5> <p>Identifies the frame as a validation frame. Its purpose is to <em>verify</em> that a sender and/or payer authorized the transaction. It must call <code>APPROVE</code> during execution. Failure to do so will result in the whole transaction being invalid.</p> <p>The execution behaves the same as <code>STATICCALL</code>, state cannot be modified.</p> <p>Frames in this mode will have their data elided from signature hash calculation and from introspection by other frames.</p> <h5 id="sender-mode"><code>SENDER</code> Mode</h5> <p>Frame executes as regular call where the caller address is <code>sender</code>. This mode effectively acts on behalf of the transaction sender and can only be used after explicitly approved.</p> <h4 id="constraints">Constraints</h4> <p>Some validity constraints can be determined statically. They are outlined below:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">assert</span><span> tx</span><span>.</span><span>chain_id</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">256</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> tx</span><span>.</span><span>nonce</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">64</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span class="z-support"> len</span><span>(</span><span>tx</span><span>.</span><span>frames</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span class="z-keyword"> and</span><span class="z-support"> len</span><span>(</span><span>tx</span><span>.</span><span>frames</span><span>)</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> MAX_FRAMES</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span class="z-support"> len</span><span>(</span><span>tx</span><span>.</span><span>sender</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 20</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> tx</span><span>.</span><span>frames</span><span>[</span><span>n</span><span>]</span><span>.</span><span>mode</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 3</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span class="z-support"> len</span><span>(</span><span>tx</span><span>.</span><span>frames</span><span>[</span><span>n</span><span>]</span><span>.</span><span>target</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 20</span><span class="z-keyword"> or</span><span> tx</span><span>.</span><span>frames</span><span>[</span><span>n</span><span>]</span><span>.</span><span>target</span><span class="z-keyword"> is</span><span class="z-constant"> None</span></span></code></pre><h4 id="receipt">Receipt</h4> <p>The <code>ReceiptPayload</code> is defined as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[cumulative_gas_used, payer, [frame_receipt, ...]]</span></span> <span class="giallo-l"><span>frame_receipt = [status, gas_used, logs]</span></span></code></pre> <p><code>payer</code> is the address of the account that paid the fees for the transaction. <code>status</code> is the return code of the top-level call.</p> <h4 id="signature-hash">Signature Hash</h4> <p>With the frame transaction, the signature may be at an arbitrary location in the frame list. In the canonical signature hash any frame with mode <code>VERIFY</code> will have its data elided:</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_sig_hash</span><span>(</span><span class="z-variable z-parameter z-function">tx</span><span>:</span><span> FrameTx</span><span>)</span><span> -&gt;</span><span> Hash</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span>,</span><span> frame</span><span class="z-keyword"> in</span><span class="z-support"> enumerate</span><span>(</span><span>tx</span><span>.</span><span>frames</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> frame</span><span>.</span><span>mode</span><span class="z-keyword"> ==</span><span class="z-constant"> VERIFY</span><span>:</span></span> <span class="giallo-l"><span> tx</span><span>.</span><span>frames</span><span>[</span><span>i</span><span>]</span><span>.</span><span>data</span><span class="z-keyword"> =</span><span> Bytes</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> keccak</span><span>(</span><span>rlp</span><span>(</span><span>tx</span><span>)</span><span>)</span></span></code></pre><h3 id="new-opcodes">New Opcodes</h3> <h4 id="approve-opcode-0xaa"><code>APPROVE</code> opcode (<code>0xaa</code>)</h4> <p>The <code>APPROVE</code> opcode is like <code>RETURN (0xf3)</code>. It exits the current context successfully and updates the transaction-scoped approval context based on the <code>scope</code> operand. It can only be called when <code>CALLER == frame.target</code>, otherwise it results in an exceptional halt.</p> <h5 id="stack">Stack</h5> <table><thead><tr><th>Stack</th><th>Value</th></tr></thead><tbody> <tr><td><code>top - 0</code></td><td><code>offset</code></td></tr> <tr><td><code>top - 1</code></td><td><code>length</code></td></tr> <tr><td><code>top - 2</code></td><td><code>scope</code></td></tr> </tbody></table> <h5 id="scope-operand">Scope Operand</h5> <p>The scope operand must be one of the following values:</p> <ol> <li><code>0x0</code>: Approval of execution - the sender contract approves future frames calling on its behalf. Only valid when <code>frame.target</code> equals <code>tx.sender</code>.</li> <li><code>0x1</code>: Approval of payment - the contract approves paying the total gas cost for the transaction.</li> <li><code>0x2</code>: Approval of execution and payment - combines both <code>0x0</code> and <code>0x1</code>.</li> </ol> <p>Any other value results in an exceptional halt.</p> <h5 id="behavior">Behavior</h5> <p>The behavior of <code>APPROVE</code> is defined as follows:</p> <ul> <li>If <code>APPROVE</code> is called when <code>CALLER != frame.target</code>, revert.</li> <li>For scopes <code>0</code>,<code>1</code>, and <code>2</code>, execute the following: <ul> <li><code>0x0</code>: Set <code>sender_approved = true</code>. <ul> <li>If <code>sender_approved</code> was already set, revert the frame.</li> <li>If <code>CALLER</code> != <code>tx.sender</code>, revert the frame.</li> </ul> </li> <li><code>0x1</code>: Increment the sender's nonce, collect the total gas cost of the transaction from the account, and set <code>payer_approved = true</code>. <ul> <li>If payer_approved` was already set, revert the frame.</li> <li>If <code>frame.target</code> has insufficient balance, revert the frame.</li> <li>If <code>sender_approved == false</code>, revert the frame.</li> </ul> </li> <li><code>0x2</code>: <code>sender_approved = true</code>, increment the sender's nonce, collect the total gas cost of the transaction from <code>frame.target</code>, and set <code>payer_approved = true</code>. <ul> <li>If <code>sender_approved</code> or <code>payer_approved</code> was already set, revert the frame.</li> <li>If <code>CALLER</code> != <code>tx.sender</code>, revert the frame.</li> <li>If <code>frame.target</code> has insufficient balance, revert the frame.</li> </ul> </li> </ul> </li> </ul> <h4 id="txparam-opcodes"><code>TXPARAM*</code> opcodes</h4> <p>The <code>TXPARAMLOAD</code> (<code>0xb0</code>), <code>TXPARAMSIZE</code> (<code>0xb1</code>), and <code>TXPARAMCOPY</code> (<code>0xb2</code>) opcodes follow the pattern of <code>CALLDATA*</code> / <code>RETURNDATA*</code> opcode families. Gas cost follows standard EVM memory expansion costs.</p> <p>Each <code>TXPARAM*</code> opcode takes two extra stack input values before the <code>CALLDATA*</code> equivalent inputs. The values of these inputs are as follows:</p> <table><thead><tr><th><code>in1</code></th><th><code>in2</code></th><th>Return value</th><th>Size</th></tr></thead><tbody> <tr><td>0x00</td><td>must be 0</td><td>current transaction type</td><td>32</td></tr> <tr><td>0x01</td><td>must be 0</td><td><code>nonce</code></td><td>32</td></tr> <tr><td>0x02</td><td>must be 0</td><td><code>sender</code></td><td>32</td></tr> <tr><td>0x03</td><td>must be 0</td><td><code>max_priority_fee_per_gas</code></td><td>32</td></tr> <tr><td>0x04</td><td>must be 0</td><td><code>max_fee_per_gas</code></td><td>32</td></tr> <tr><td>0x05</td><td>must be 0</td><td><code>max_fee_per_blob_gas</code></td><td>32</td></tr> <tr><td>0x06</td><td>must be 0</td><td>max cost (basefee=max, all gas used, includes blob cost and intrinsic cost)</td><td>32</td></tr> <tr><td>0x07</td><td>must be 0</td><td><code>len(blob_versioned_hashes)</code></td><td>32</td></tr> <tr><td>0x08</td><td>must be 0</td><td><code>compute_sig_hash(tx)</code></td><td>32</td></tr> <tr><td>0x09</td><td>must be 0</td><td><code>len(frames)</code></td><td>32</td></tr> <tr><td>0x10</td><td>must be 0</td><td>currently executing frame index</td><td>32</td></tr> <tr><td>0x11</td><td>frame index</td><td><code>target</code></td><td>32</td></tr> <tr><td>0x12</td><td>frame index</td><td><code>data</code></td><td>dynamic</td></tr> <tr><td>0x13</td><td>frame index</td><td><code>gas_limit</code></td><td>32</td></tr> <tr><td>0x14</td><td>frame index</td><td><code>mode</code></td><td>32</td></tr> <tr><td>0x15</td><td>frame index</td><td><code>status</code> (exceptional halt if current/future)</td><td>32</td></tr> </tbody></table> <p>Notes:</p> <ul> <li>0x03 and 0x04 have a possible future extension to allow indices for multidimensional gas.</li> <li>The <code>status</code> field (0x15) returns <code>0</code> for failure or <code>1</code> for success.</li> <li>Out-of-bounds access for frame index (<code>&gt;= len(frames)</code>) and blob index results in an exceptional halt.</li> <li>Invalid <code>in1</code> values (not defined in the table above) result in an exceptional halt.</li> <li>The <code>data</code> field (0x12) returns size 0 value when called on a frame with <code>VERIFY</code> set.</li> </ul> <h3 id="behavior-1">Behavior</h3> <p>When processing a frame transaction, perform the following steps.</p> <p>Perform stateful validation check:</p> <ul> <li>Ensure <code>tx.nonce == state[tx.sender].nonce</code></li> </ul> <p>Initialize with transaction-scoped variables:</p> <ul> <li><code>payer_approved = false</code></li> <li><code>sender_approved = false</code></li> </ul> <p>Then for each call frame:</p> <ol> <li>Execute a call with the specified <code>mode</code>, <code>target</code>, <code>gas_limit</code>, and <code>data</code>. <ul> <li>If <code>target</code> is null, set the call target to <code>tx.sender</code>.</li> <li>If mode is <code>SENDER</code>: <ul> <li><code>sender_approved</code> must be <code>true</code>. If not, the transaction is invalid.</li> <li>Set <code>caller</code> as <code>tx.sender</code>.</li> </ul> </li> <li>If mode is <code>DEFAULT</code> or <code>VERIFY</code>: <ul> <li>Set the <code>caller</code> to <code>ENTRY_POINT</code>.</li> </ul> </li> <li>The <code>ORIGIN</code> opcode returns frame <code>caller</code> throughout all call depths.</li> </ul> </li> <li>If frame has mode <code>VERIFY</code> and the frame did successfully call <code>APPROVE</code>, the transaction is invalid.</li> </ol> <p>After executing all frames, verify that <code>payer_approved == true</code>. If it is, refund any unpaid gas to the gas payer. If it is not, the whole transaction is invalid.</p> <p>Note: it is implied by the handling that the sender must approve the transaction <em>before</em> the payer and that once <code>sender_approved</code> or <code>payer_approved</code> become <code>true</code> they cannot be re-approved or reverted.</p> <h4 id="frame-interactions">Frame interactions</h4> <p>A few cross-frame interactions to note:</p> <ul> <li>For the purposes of gas accounting of warm / cold state status, the journal of such touches is shared across frames.</li> <li>Discard the <code>TSTORE</code> and <code>TLOAD</code> transient storage between frames.</li> </ul> <h4 id="gas-accounting">Gas Accounting</h4> <p>The total gas limit of the transaction is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>tx_gas_limit = FRAME_TX_INTRINSIC_COST + calldata_cost(rlp(tx.frames)) + sum(frame.gas_limit for all frames)</span></span></code></pre> <p>Where <code>calldata_cost</code> is calculated per standard EVM rules (4 gas per zero byte, 16 gas per non-zero byte).</p> <p>The total fee is defined as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>tx_fee = tx_gas_limit * effective_gas_price + blob_fees</span></span> <span class="giallo-l"><span>blob_fees = len(blob_versioned_hashes) * GAS_PER_BLOB * blob_base_fee</span></span></code></pre> <p>The <code>effective_gas_price</code> is calculated per EIP-1559 and <code>blob_fees</code> is calculated as per EIP-4844.</p> <p>Each frame has its own <code>gas_limit</code> allocation. Unused gas from a frame is <strong>not</strong> available to subsequent frames. After all frames execute, the gas refund is calculated as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>refund = sum(frame.gas_limit for all frames) - total_gas_used</span></span></code></pre> <p>This refund is returned to the gas payer (the <code>target</code> that called <code>APPROVE(0x1)</code> or <code>APPROVE(0x2)</code>) and added back to the block gas pool. <em>Note: This refund mechanism is separate from EIP-3529 storage refunds.</em></p> <h2 id="rationale">Rationale</h2> <h3 id="canonical-signature-hash">Canonical signature hash</h3> <p>The canonical signature hash is provided in <code>TXPARAMLOAD</code> to simplify the development of smart accounts.</p> <p>Computing the signature hash in EVM is complicated and expensive. While using the canonical signature hash is not mandatory, it is strongly recommended. Creating a bespoke signature requires precise commitment to the underlying transaction data. Without this, it's possible that some elements can be manipulated in-the-air while the transaction is pending and have unexpected effects. This is known as transaction malleability. Using the canonical signature hash avoids malleability of the frames other than <code>VERIFY</code>.</p> <p>The <code>frame.data</code> of <code>VERIFY</code> frames is elided from the signature hash. This is done for two reasons:</p> <ol> <li>It contains the signature so by definition it cannot be part of the signature hash.</li> <li>In the future it may be desired to aggregate the cryptographic operations for data and compute efficiency reasons. If the data was introspectable, it would not be possible to aggregate the verify frames in the future.</li> <li>For gas sponsoring workflows, we also recommend using a <code>VERIFY</code> frame to approve the gas payment. Here, the input data to the sponsor is intentionally left malleable so it can be added onto the transaction after the <code>sender</code> has made its signature. Notably, the <code>frame.target</code> of <code>VERIFY</code> frames is covered by the signature hash, i.e. the <code>sender</code> chooses the sponsor address explicitly.</li> </ol> <h3 id="approve-calling-convention"><code>APPROVE</code> calling convention</h3> <p>Originally <code>APPROVE</code> was meant to extend the space of return statuses from 0 and j 1 today to 0 to 4. However, this would mean smart accounts deployed today would not beable to modify their contract code to return with a different value at the top level. For this reason, we've chosen behavior above: <code>APPROVE</code> terminates the executing frame successfully like <code>RETURN</code>, but it actually updates the transaction scoped values <code>sender_approved</code> and <code>payer_approved</code> during execution. It is still required that only the sender can toggle the <code>sender_approved</code> to <code>true</code>. Only the <code>frame.target</code> can call <code>APPROVE</code> generally, because it can allow the transaction pool and other frames to better reason about <code>VERIFY</code> mode frames.</p> <h3 id="payer-in-receipt">Payer in receipt</h3> <p>The payer cannot be determined statically from a frame transaction and is relevant to users. The only way to provide this information safely and efficiently over the JSON-RPC is to record this data in the receipt object.</p> <h3 id="no-authorization-list">No authorization list</h3> <p>The EIP-7702 authorization list heavily relies on ECDSA cryptography to determine the authority of accounts to delegate code. While delegations could be used in other manners later, it does not satisfy the PQ goals of the frame transaction.</p> <h3 id="no-access-list">No access list</h3> <p>The access list was introduced to address a particular backwards compatibility issue that was caused by EIP-2929. The risk-reward of using an access list successfully is high. A single miss, paying to warm a storage slot that does not end up getting used, causes the overall transaction cost to be greater than had it not been included at all.</p> <p>Future optimizations based on pre-announcing state elements a transaction will touch will be covered by block level access lists.</p> <h3 id="no-value-in-frame">No value in frame</h3> <p>It is not required because the account code can send value.</p> <h3 id="examples">Examples</h3> <h4 id="example-1-simple-transaction">Example 1: Simple Transaction</h4> <table><thead><tr><th>Frame</th><th>Caller</th><th>Target</th><th>Data</th><th>Mode</th></tr></thead><tbody> <tr><td>0</td><td>ENTRY_POINT</td><td>Null (sender)</td><td>Signature</td><td>VERIFY</td></tr> <tr><td>1</td><td>Sender</td><td>Target</td><td>Call data</td><td>SENDER</td></tr> </tbody></table> <p>Frame 0 verifies the signature and calls <code>APPROVE(0x2)</code> to approve both execution and payment. Frame 1 executes and exits normally via <code>RETURN</code>.</p> <p>The mempool can process this transaction with the following static validation and call:</p> <ul> <li>Verify that the first frame is a <code>VERIFY</code> frame.</li> <li>Verify that the call of frame 0 succeeds, and does not violate the mempool rules (similar to <a href="https://wg-eips.ritovision.com/7562/">ERC-7562</a>).</li> </ul> <h4 id="example-1a-simple-eth-transfer">Example 1a: Simple ETH transfer</h4> <table><thead><tr><th>Frame</th><th>Caller</th><th>Target</th><th>Data</th><th>Mode</th></tr></thead><tbody> <tr><td>0</td><td>ENTRY_POINT</td><td>Null (sender)</td><td>Signature</td><td>VERIFY</td></tr> <tr><td>1</td><td>Sender</td><td>Null (sender)</td><td>Destination/Amount</td><td>SENDER</td></tr> </tbody></table> <p>A simple transfer is performed by instructing the account to send ETH to the destination account. This requires two frames for mempool compatibility, since the validation phase of the transaction has to be static.</p> <p>This is listed here to illustrate why the transaction type has no built-in value field.</p> <h4 id="example-1b-simple-account-deployment">Example 1b: Simple account deployment</h4> <table><thead><tr><th>Frame</th><th>Caller</th><th>Target</th><th>Data</th><th>Mode</th></tr></thead><tbody> <tr><td>0</td><td>ENTRY_POINT</td><td>Deployer</td><td>Initcode, Salt</td><td>DEFAULT</td></tr> <tr><td>1</td><td>ENTRY_POINT</td><td>Null (sender)</td><td>Signature</td><td>VERIFY</td></tr> <tr><td>2</td><td>Sender</td><td>Null (sender)</td><td>Destination/Amount</td><td>SENDER</td></tr> </tbody></table> <p>This example illustrates the initial deployment flow for a smart account at the <code>sender</code> address. Since the address needs to have code in order to validate the transaction, the transaction must deploy the code before verification.</p> <p>The first frame would call a deployer contract, like EIP-7997. The deployer determines the address in a deterministic way, such as by hashing the initcode and salt. However, since the transaction sender is not authenticated at this point, the user must choose an initcode which is safe to deploy by anyone.</p> <h4 id="example-2-sponsored-transaction-fee-payment-in-erc-20">Example 2: Sponsored Transaction (Fee Payment in ERC-20)</h4> <table><thead><tr><th>Frame</th><th>Caller</th><th>Target</th><th>Data</th><th>Mode</th></tr></thead><tbody> <tr><td>0</td><td>ENTRY_POINT</td><td>Null (sender)</td><td>Signature</td><td>VERIFY</td></tr> <tr><td>1</td><td>ENTRY_POINT</td><td>Sponsor</td><td>Sponsor data</td><td>VERIFY</td></tr> <tr><td>2</td><td>Sender</td><td>ERC-20</td><td>transfer(Sponsor,fees)</td><td>SENDER</td></tr> <tr><td>3</td><td>Sender</td><td>Target addr</td><td>Call data</td><td>SENDER</td></tr> <tr><td>4</td><td>ENTRY_POINT</td><td>Sponsor</td><td>Post op call</td><td>DEFAULT</td></tr> </tbody></table> <ul> <li>Frame 0: Verifies signature and calls <code>APPROVE(0x0)</code> to authorize execution from sender.</li> <li>Frame 1: Checks that the user has enough ERC-20 tokens, and that the next frame is an ERC-20 send of the right size to the sponsor. Calls <code>APPROVE(0x1)</code> to authorize payment.</li> <li>Frame 2: Sends tokens to sponsor.</li> <li>Frame 3: User's intended call.</li> <li>Frame 4 (optional): Check unpaid gas, refund tokens, possibly convert tokens to ETH on an AMM.</li> </ul> <h3 id="data-efficiency">Data Efficiency</h3> <p><strong>Basic transaction sending ETH from a smart account:</strong></p> <table><thead><tr><th>Field</th><th>Bytes</th></tr></thead><tbody> <tr><td>Tx wrapper</td><td>1</td></tr> <tr><td>Chain ID</td><td>1</td></tr> <tr><td>Nonce</td><td>2</td></tr> <tr><td>Sender</td><td>20</td></tr> <tr><td>Max priority fee</td><td>5</td></tr> <tr><td>Max fee</td><td>5</td></tr> <tr><td>Max fee per blob gas</td><td>1</td></tr> <tr><td>Blob versioned hashes (empty)</td><td>1</td></tr> <tr><td>Frames wrapper</td><td>1</td></tr> <tr><td>Sender validation frame: target</td><td>1</td></tr> <tr><td>Sender validation frame: gas</td><td>2</td></tr> <tr><td>Sender validation frame: data</td><td>65</td></tr> <tr><td>Sender validation frame: mode</td><td>1</td></tr> <tr><td>Execution frame: target</td><td>1</td></tr> <tr><td>Execution frame: gas</td><td>1</td></tr> <tr><td>Execution frame: data</td><td>20+5</td></tr> <tr><td>Execution frame: mode</td><td>1</td></tr> <tr><td><strong>Total</strong></td><td>134</td></tr> </tbody></table> <p>Notes: Nonce assumes &lt; 65536 prior sends. Fees assume &lt; 1099 gwei. Validation frame target is 1 byte because target is <code>tx.sender</code>. Validation gas assumes &lt;= 65,536 gas. Calldata is 65 bytes for ECDSA signature. Blob fields assume no blobs (empty list, zero max fee).</p> <p>This is not much larger than an EIP-1559 transaction; the extra overhead is the need to specify the sender and amount in calldata explicitly.</p> <p><strong>First transaction from an account (add deployment frame):</strong></p> <table><thead><tr><th>Field</th><th>Bytes</th></tr></thead><tbody> <tr><td>Deployment frame: target</td><td>20</td></tr> <tr><td>Deployment frame: gas</td><td>3</td></tr> <tr><td>Deployment frame: data</td><td>100</td></tr> <tr><td>Deployment frame: mode</td><td>1</td></tr> <tr><td><strong>Total additional</strong></td><td>124</td></tr> </tbody></table> <p>Notes: Gas assumes cost &lt; 2^24. Calldata assumes small proxy.</p> <p><strong>Trustless pay-with-ERC-20 sponsor (add these frames):</strong></p> <table><thead><tr><th>Field</th><th>Bytes</th></tr></thead><tbody> <tr><td>Sponsor validation frame: target</td><td>20</td></tr> <tr><td>Sponsor validation frame: gas</td><td>3</td></tr> <tr><td>Sponsor validation frame: calldata</td><td>0</td></tr> <tr><td>Sponsor validation frame: mode</td><td>1</td></tr> <tr><td>Send to sponsor frame: target</td><td>20</td></tr> <tr><td>Send to sponsor frame: gas</td><td>3</td></tr> <tr><td>Send to sponsor frame: calldata</td><td>68</td></tr> <tr><td>Send to sponsor frame: mode</td><td>1</td></tr> <tr><td>Sponsor post op frame: target</td><td>20</td></tr> <tr><td>Sponsor post op frame: gas</td><td>3</td></tr> <tr><td>Sponsor post op frame: calldata</td><td>0</td></tr> <tr><td>Sponsor post op frame: mode</td><td>1</td></tr> <tr><td><strong>Total additional</strong></td><td>140</td></tr> </tbody></table> <p>Notes: Sponsor can read info from other fields. ERC-20 transfer call is 68 bytes.</p> <p>There is some inefficiency in the sponsor case, because the same sponsor address must appear in three places (sponsor validation, send to sponsor inside ERC-20 calldata, post op frame), and the ABI is inefficient (~12 + 24 bytes wasted on zeroes). This is difficult to mitigate in a "clean" way, because one of the duplicates is inside the ERC-20 call, "opaque" to the protocol. However, it is much less inefficient than ERC-4337, because not all of the data takes the hit of the 32-byte-per-field ABI overhead.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The <code>ORIGIN</code> opcode behavior changes for frame transactions, returning the frame's caller rather than the traditional transaction origin. This is consistent with the precedent set by EIP-7702, which already modified <code>ORIGIN</code> semantics. Contracts that rely on <code>ORIGIN = CALLER</code> for security checks (a discouraged pattern) may behave differently under frame transactions.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="transaction-propagation">Transaction Propagation</h3> <p>Frame transactions introduce new denial-of-service vectors for transaction pools that node operators must mitigate. Because validation logic is arbitrary EVM code, attackers can craft transactions that appear valid during initial validation but become invalid later. Without any additional policies, an attacker could submit many transactions whose validity depends on some shared state, then submit one transaction that modifies that state, and cause all other transactions to become invalid simultaneously. This wastes the computational resources nodes spent validating and storing these transactions.</p> <h4 id="example-attack">Example Attack</h4> <p>A simple example is transactions that check <code>block.timestamp</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"> validateTransaction</span><span>(</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">block</span><span>.</span><span>timestamp </span><span class="z-keyword">&lt;</span><span> SOME_DEADLINE</span><span>,</span><span class="z-string"> &quot;expired&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ... rest of validation</span></span> <span class="giallo-l"><span class="z-entity z-name"> APPROVE</span><span>(</span><span class="z-constant">0x2</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Such transactions are valid when submitted but become invalid once the deadline passes, without any on-chain action required from the attacker.</p> <h5 id="mitigations">Mitigations</h5> <p>Node implementations should consider restricting which opcodes and storage slots validation frames can access, similar to ERC-7562. This isolates transactions from each other and limits mass invalidation vectors.</p> <p>It's recommended that to <em>validate</em> the transaction, a specific frame structure is enforced and the amount of gas that is expended executing the validation phase must be limited. Once the frame calls <code>APPROVE(0x2)</code>, it can be included in the mempool and propagated to peers safely.</p> <p>For deployment of the sender account in the first frame, the mempool must only allow specific and known deployer factory contracts to be used as <code>frame.target</code>, to ensure deployment is deterministic and independent of chain state.</p> <p>In general, it can be assumed that handling of frame transactions imposes similar restrictions as EIP-7702 on mempool relay, i.e. only a single transaction can be pending for an account that uses frame 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> 2026-01-29T00:00:00+00:00 2026-02-11T14:49:27+00:00 Kevaundray Wedderburnhttps://github.com/kevaundray Ignacio Hagopianhttps://github.com/jsign Jihoon Songjihoon.song@ethereum.org Francesco Risitanohttps://github.com/frisitano Thomas Thieryhttps://github.com/soispokethomas.thiery@ethereum.org Toni Wahrstätterhttps://github.com/nerolation https://wg-eips.ritovision.com/8142/

Ensures execution payload data availability via blobs

<h2 id="abstract">Abstract</h2> <p>zkEVMs allow validators to verify the correctness of an execution payload using a proof, without downloading or executing the payload itself. However, removing the requirement to download the execution payload, also removes the implicit data availability (DA) guarantee; a block producer can publish a valid proof and withhold the execution-payload data since attesters no longer need them for consensus.</p> <p>This EIP introduces Block-in-Blobs (BiB), a mechanism that requires the execution-payload data (transactions and BALs) to be published in blob data, in the same beacon block that carries the corresponding execution payload's header. This ensures that execution payloads and their associated data are always published even when validators no longer require them to verify the state transition function (STF).</p> <p>In short, BiB works by having the block producer encode the execution-payload data into blobs as part of the execution layer's STF, requiring the beacon block’s blob KZG commitments to commit to those payload-blobs.</p> <h2 id="motivation">Motivation</h2> <p><strong>Validation via re-execution</strong></p> <p>Today, validators verify execution payloads by:</p> <ol> <li>Downloading the execution payload</li> <li>Executing the payload locally</li> <li>Checking the resulting state root and other fields against the fields in the header</li> </ol> <p>Implicitly this guarantees execution payload availability because the payload cannot be verified unless the node downloads it.</p> <p><strong>Validation with zkEVMs</strong></p> <p>With zkEVMs, validators instead:</p> <ol> <li>Download a proof attesting to the correctness of the execution payload</li> <li>Download the execution payload header</li> <li>Verify the proof with respects to the payload header (and other commitments)</li> </ol> <p>In this model, validators no longer require access to the full execution payload data itself in order to verify its correctness.</p> <p><strong>The DA problem</strong></p> <p>Removing the re-execution requirement in consensus removes the implicit requirement that consensus clients download the execution payload.</p> <p>A malicious or rational builder could:</p> <ul> <li>Publish a valid proof for a valid execution payload</li> <li>Withhold the execution-payload data entirely</li> </ul> <p><em>Builders</em>: Since builders will always need to re-execute in order to build blocks, a malicious builder would not publish the execution payload ensuring that they are the only ones that can build on top of the current chain.</p> <p><em>RPC and indexers</em>: Many nodes such as RPC providers and indexers cannot solely rely on execution proofs and must re-execute the execution payload.</p> <p>BiB addresses this by making the execution payload available via blobs.</p> <h2 id="specification">Specification</h2> <h3 id="terminology">Terminology</h3> <p><strong>Type-3 transaction:</strong> Refers to EIP-4844 blob-carrying transactions (transaction type 0x03). These transactions include blob versioned hashes that commit to blobs carrying user data.</p> <h3 id="overview-and-invariants">Overview and Invariants</h3> <p>BiB ensures the proven payload is published:</p> <ul> <li>The beacon block references a list of blob KZG commitments (via 4844/PeerDas)</li> <li>A prefix of those commitments is reserved for the execution-payload data encoded into blobs</li> <li>A zkEVM proof for the block must bind the proven execution payload to those prefixed blob commitments.</li> </ul> <p><strong>Payload availability invariant:</strong> A valid block implies there exists an ordered list of blobs whose bytes decode to the canonical execution-payload data, and the KZG commitments for these blobs match the first <code>payload_blob_count</code> blob commitments referenced by the block. The existing DAS mechanism will ensure that those blobs are available.</p> <h3 id="parameters">Parameters</h3> <h4 id="referenced-parameters">Referenced Parameters</h4> <p>These parameters are defined in EIP-4844 and related specs:</p> <table><thead><tr><th>Name</th><th>Value</th><th>Source</th></tr></thead><tbody> <tr><td><code>FIELD_ELEMENTS_PER_BLOB</code></td><td><code>4096</code></td><td>EIP-4844</td></tr> <tr><td><code>BYTES_PER_FIELD_ELEMENT</code></td><td><code>32</code></td><td>EIP-4844</td></tr> <tr><td><code>GAS_PER_BLOB</code></td><td><code>2**17</code></td><td>EIP-4844</td></tr> <tr><td><code>MAX_BLOBS_PER_BLOCK</code></td><td>Network-specific</td><td>EIP-7892</td></tr> </tbody></table> <p><strong>Note on <code>MAX_BLOBS_PER_BLOCK</code>:</strong> This constant represents the maximum number of blobs (both payload-blobs and type-3 transaction blobs) that can be included in a block. Per EIP-7892, the execution layer's <code>blobSchedule.max</code> MUST equal the consensus layer's <code>MAX_BLOBS_PER_BLOCK</code> configuration value at any given time. This value may change across forks (e.g., initially 6 in EIP-4844, potentially increased in subsequent blob throughput increase proposals).</p> <h4 id="derived-constants">Derived Constants</h4> <table><thead><tr><th>Name</th><th>Value</th><th>Description</th></tr></thead><tbody> <tr><td><code>USABLE_BYTES_PER_FIELD_ELEMENT</code></td><td><code>BYTES_PER_FIELD_ELEMENT - 1</code> (31)</td><td>Usable bytes per field element (final byte must be zero to stay under BLS modulus)</td></tr> <tr><td><code>USABLE_BYTES_PER_BLOB</code></td><td><code>FIELD_ELEMENTS_PER_BLOB * USABLE_BYTES_PER_FIELD_ELEMENT</code></td><td>Total usable bytes per blob</td></tr> </tbody></table> <h3 id="execution-layer">Execution Layer</h3> <p><strong>Summary:</strong> The execution layer is modified in the following ways:</p> <ul> <li>The ExecutionPayloadHeader now has a <code>payload_blob_count</code> field to track how many blobs are used for the execution payload data, enabling verification of the correct number of payload-blobs at the Engine API boundary.</li> <li><code>engine_getPayload</code> computes the payload-blobs when building a block, sets <code>payload_blob_count</code> in the ExecutionPayloadHeader, and returns the payload blobs (with their commitments and proofs) alongside type-3 transaction blobs in the response.</li> <li><code>engine_newPayload</code> takes the ExecutionPayload and before passing it to the EL STF, it computes the payload-blobs, checks that the amount of blobs needed is equal to the <code>payload_blob_count</code> value in the ExecutionPayloadHeader and verifies that the expected version hashes match.</li> </ul> <h4 id="referenced-helpers">Referenced Helpers</h4> <p>The execution layer uses methods and classes defined in the corresponding consensus 4844/7594 specs.</p> <p>Specifically, we use the following methods from <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/46c1199d6b4584ba484dec807f03b8e6211dd725/specs/deneb/polynomial-commitments.md?#introduction">polynomial-commitments.md</a>:</p> <ul> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/46c1199d6b4584ba484dec807f03b8e6211dd725/specs/deneb/polynomial-commitments.md#L578">verify_blob_kzg_proof_batch</a></li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/86fb82b221474cc89387fa6436806507b3849d88/specs/deneb/polynomial-commitments.md#blob_to_kzg_commitment">blob_to_kzg_commitment</a></li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/86fb82b221474cc89387fa6436806507b3849d88/specs/deneb/polynomial-commitments.md#compute_blob_kzg_proof">compute_blob_kzg_proof</a></li> </ul> <p>And the following methods from <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/2938e1ad74cea54f1a24508a85704d5bd87837ad/specs/fulu/polynomial-commitments-sampling.md">polynomial-commitments-sampling.md</a>:</p> <ul> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/2938e1ad74cea54f1a24508a85704d5bd87837ad/specs/fulu/polynomial-commitments-sampling.md#compute_cells_and_kzg_proofs">compute_cells_and_kzg_proofs</a></li> </ul> <p>And the following methods from <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/86fb82b221474cc89387fa6436806507b3849d88/specs/deneb/beacon-chain.md#introduction">beacon-chain.md</a>:</p> <ul> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/86fb82b221474cc89387fa6436806507b3849d88/specs/deneb/beacon-chain.md#kzg_commitment_to_versioned_hash">kzg_commitment_to_versioned_hash</a></li> </ul> <h4 id="helpers">Helpers</h4> <h5 id="bytes-to-blobs">bytes_to_blobs</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"> bytes_to_blobs</span><span>(</span><span class="z-variable z-parameter z-function">data</span><span>:</span><span class="z-support"> bytes</span><span>)</span><span> -&gt;</span><span> List</span><span>[</span><span>Blob</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"> Pack arbitrary bytes into one or more blobs.</span></span> <span class="giallo-l"><span class="z-string"> Remaining space in final blob is zero-padded.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> blobs</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> offset</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> offset</span><span class="z-keyword"> &lt;</span><span class="z-support"> len</span><span>(</span><span>data</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> chunk</span><span class="z-keyword"> =</span><span> data</span><span>[</span><span>offset</span><span> :</span><span> offset</span><span class="z-keyword"> +</span><span class="z-constant"> USABLE_BYTES_PER_BLOB</span><span>]</span></span> <span class="giallo-l"><span> blob</span><span class="z-keyword"> =</span><span> chunk_to_blob</span><span>(</span><span>chunk</span><span>)</span></span> <span class="giallo-l"><span> blobs</span><span>.</span><span>append</span><span>(</span><span>blob</span><span>)</span></span> <span class="giallo-l"><span> offset</span><span class="z-keyword"> +=</span><span class="z-constant"> USABLE_BYTES_PER_BLOB</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> blobs</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"> chunk_to_blob</span><span>(</span><span class="z-variable z-parameter z-function">data</span><span>:</span><span class="z-support"> bytes</span><span>)</span><span> -&gt;</span><span> Blob</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"> Pack up to USABLE_BYTES_PER_BLOB bytes into a single blob.</span></span> <span class="giallo-l"><span class="z-string"> If data is shorter than USABLE_BYTES_PER_BLOB, it is zero-padded.</span></span> <span class="giallo-l"><span class="z-string"> Each 31-byte chunk is stored in bytes [0:31] of a field element,</span></span> <span class="giallo-l"><span class="z-string"> with byte [31] (the final byte) set to zero to ensure value &lt; BLS modulus.</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-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>data</span><span>)</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> USABLE_BYTES_PER_BLOB</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Pad to exactly USABLE_BYTES_PER_BLOB if needed</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>data</span><span>)</span><span class="z-keyword"> &lt;</span><span class="z-constant"> USABLE_BYTES_PER_BLOB</span><span>:</span></span> <span class="giallo-l"><span> data</span><span class="z-keyword"> =</span><span> data</span><span class="z-keyword"> +</span><span class="z-support"> bytes</span><span>(</span><span class="z-constant">USABLE_BYTES_PER_BLOB</span><span class="z-keyword"> -</span><span class="z-support"> len</span><span>(</span><span>data</span><span>)</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> blob</span><span class="z-keyword"> =</span><span class="z-support"> bytearray</span><span>(</span><span class="z-constant">FIELD_ELEMENTS_PER_BLOB</span><span class="z-keyword"> *</span><span class="z-constant"> BYTES_PER_FIELD_ELEMENT</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span class="z-constant">FIELD_ELEMENTS_PER_BLOB</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> chunk_start</span><span class="z-keyword"> =</span><span> i</span><span class="z-keyword"> *</span><span class="z-constant"> USABLE_BYTES_PER_FIELD_ELEMENT</span></span> <span class="giallo-l"><span> chunk</span><span class="z-keyword"> =</span><span> data</span><span>[</span><span>chunk_start</span><span> :</span><span> chunk_start</span><span class="z-keyword"> +</span><span class="z-constant"> USABLE_BYTES_PER_FIELD_ELEMENT</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"> Store 31 data bytes in [0:31], the final byte [31] stays zero</span></span> <span class="giallo-l"><span> blob</span><span>[</span><span>i</span><span class="z-keyword"> *</span><span class="z-constant"> BYTES_PER_FIELD_ELEMENT</span><span> :</span><span> i</span><span class="z-keyword"> *</span><span class="z-constant"> BYTES_PER_FIELD_ELEMENT</span><span class="z-keyword"> +</span><span class="z-constant"> USABLE_BYTES_PER_FIELD_ELEMENT</span><span>]</span><span class="z-keyword"> =</span><span> chunk</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> Blob</span><span>(</span><span>blob</span><span>)</span></span></code></pre><h5 id="blobs-to-bytes">blobs_to_bytes</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"> blobs_to_bytes</span><span>(</span><span class="z-variable z-parameter z-function">blobs</span><span>:</span><span> List</span><span>[</span><span>Blob</span><span>]</span><span>)</span><span> -&gt;</span><span class="z-support"> bytes</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"> Unpack blobs back to bytes.</span></span> <span class="giallo-l"><span class="z-string"> Returns all usable bytes from all blobs (including any padding).</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> raw</span><span class="z-keyword"> =</span><span class="z-support"> bytearray</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> blob</span><span class="z-keyword"> in</span><span> blobs</span><span>:</span></span> <span class="giallo-l"><span> raw</span><span>.</span><span>extend</span><span>(</span><span>blob_to_chunk</span><span>(</span><span>blob</span><span>)</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> bytes</span><span>(</span><span>raw</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"> blob_to_chunk</span><span>(</span><span class="z-variable z-parameter z-function">blob</span><span>:</span><span> Blob</span><span>)</span><span> -&gt;</span><span class="z-support"> bytes</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"> Extract the 31 usable bytes from each field element.</span></span> <span class="giallo-l"><span class="z-string"> Validates that the final byte is zero for each field element.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> result</span><span class="z-keyword"> =</span><span class="z-support"> bytearray</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span class="z-constant">FIELD_ELEMENTS_PER_BLOB</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Validate final byte is zero</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> blob</span><span>[</span><span>i</span><span class="z-keyword"> *</span><span class="z-constant"> BYTES_PER_FIELD_ELEMENT</span><span class="z-keyword"> +</span><span class="z-constant"> USABLE_BYTES_PER_FIELD_ELEMENT</span><span>]</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> 0x</span><span class="z-constant">00</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Invalid blob: final byte must be zero</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Extract usable data bytes</span></span> <span class="giallo-l"><span> result</span><span>.</span><span>extend</span><span>(</span><span>blob</span><span>[</span><span>i</span><span class="z-keyword"> *</span><span class="z-constant"> BYTES_PER_FIELD_ELEMENT</span><span> :</span><span> i</span><span class="z-keyword"> *</span><span class="z-constant"> BYTES_PER_FIELD_ELEMENT</span><span class="z-keyword"> +</span><span class="z-constant"> USABLE_BYTES_PER_FIELD_ELEMENT</span><span>]</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> bytes</span><span>(</span><span>result</span><span>)</span></span></code></pre><h5 id="get-execution-payload-data">get_execution_payload_data</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"> get_execution_payload_data</span><span>(</span><span class="z-variable z-parameter z-function">payload</span><span>:</span><span> ExecutionPayload</span><span>)</span><span> -&gt;</span><span> ExecutionPayloadData</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"> Extract the data from an ExecutionPayload that must be made available via blobs.</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-keyword"> return</span><span> ExecutionPayloadData</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> blockAccessList</span><span class="z-keyword">=</span><span>payload</span><span>.</span><span>blockAccessList</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> transactions</span><span class="z-keyword">=</span><span>payload</span><span>.</span><span>transactions</span><span>,</span></span> <span class="giallo-l"><span> )</span></span></code></pre><h5 id="execution-payload-data-to-blobs">execution_payload_data_to_blobs</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"> execution_payload_data_to_blobs</span><span>(</span><span class="z-variable z-parameter z-function">data</span><span>:</span><span> ExecutionPayloadData</span><span>)</span><span> -&gt;</span><span> List</span><span>[</span><span>Blob</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"> Canonically encode the execution-payload data into an ordered list of blobs.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-string"> Encoding steps:</span></span> <span class="giallo-l"><span class="z-string"> 1. bal_bytes = data.blockAccessList</span></span> <span class="giallo-l"><span class="z-string"> 2. transactions_bytes = RLP.encode(data.transactions)</span></span> <span class="giallo-l"><span class="z-string"> 3. Create 10-byte header: [2 bytes version][4 bytes BAL length][4 bytes tx length]</span></span> <span class="giallo-l"><span class="z-string"> 4. payload_bytes = header + bal_bytes + transactions_bytes</span></span> <span class="giallo-l"><span class="z-string"> 5. return bytes_to_blobs(payload_bytes)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-string"> The first blob will contain (in order):</span></span> <span class="giallo-l"><span class="z-string"> - [2 bytes] Payload encoding version (currently 0)</span></span> <span class="giallo-l"><span class="z-string"> - [4 bytes] BAL data length</span></span> <span class="giallo-l"><span class="z-string"> - [4 bytes] Transaction data length</span></span> <span class="giallo-l"><span class="z-string"> - [variable] BAL data (may span multiple blobs)</span></span> <span class="giallo-l"><span class="z-string"> - [variable] Transaction data (may span multiple blobs)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-string"> This allows extracting just the BAL data without transactions.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-string"> Note: blockAccessList is already RLP-encoded per EIP-7928. Transactions are RLP-encoded as a list.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> bal_bytes</span><span class="z-keyword"> =</span><span> data</span><span>.</span><span>blockAccessList</span></span> <span class="giallo-l"><span> transactions_bytes</span><span class="z-keyword"> =</span><span class="z-constant"> RLP</span><span>.</span><span>encode</span><span>(</span><span>data</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"> Create 10-byte header: [2 bytes version][4 bytes BAL length][4 bytes tx length]</span></span> <span class="giallo-l"><span> version</span><span class="z-keyword"> =</span><span> (</span><span class="z-constant">0</span><span>)</span><span>.</span><span>to_bytes</span><span>(</span><span class="z-constant">2</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> bal_length</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span>bal_bytes</span><span>)</span><span>.</span><span>to_bytes</span><span>(</span><span class="z-constant">4</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> txs_length</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span>transactions_bytes</span><span>)</span><span>.</span><span>to_bytes</span><span>(</span><span class="z-constant">4</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> header</span><span class="z-keyword"> =</span><span> version</span><span class="z-keyword"> +</span><span> bal_length</span><span class="z-keyword"> +</span><span> txs_length</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Combine header + data</span></span> <span class="giallo-l"><span> payload_bytes</span><span class="z-keyword"> =</span><span> header</span><span class="z-keyword"> +</span><span> bal_bytes</span><span class="z-keyword"> +</span><span> transactions_bytes</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> bytes_to_blobs</span><span>(</span><span>payload_bytes</span><span>)</span></span></code></pre><h5 id="blobs-to-execution-payload-data">blobs_to_execution_payload_data</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"> blobs_to_execution_payload_data</span><span>(</span><span class="z-variable z-parameter z-function">blobs</span><span>:</span><span> List</span><span>[</span><span>Blob</span><span>]</span><span>)</span><span> -&gt;</span><span> ExecutionPayloadData</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"> Canonically decode an ordered list of blobs into execution-payload data.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-string"> Decoding steps:</span></span> <span class="giallo-l"><span class="z-string"> 1. raw = blobs_to_bytes(blobs)</span></span> <span class="giallo-l"><span class="z-string"> 2. Read 10-byte header: [2 bytes version][4 bytes BAL length][4 bytes tx length]</span></span> <span class="giallo-l"><span class="z-string"> 3. Validate version is 0</span></span> <span class="giallo-l"><span class="z-string"> 4. Split into bal_bytes and transactions_bytes</span></span> <span class="giallo-l"><span class="z-string"> 5. return ExecutionPayloadData(blockAccessList, 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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Extract raw bytes from blobs</span></span> <span class="giallo-l"><span> raw</span><span class="z-keyword"> =</span><span> blobs_to_bytes</span><span>(</span><span>blobs</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"> Read 10-byte header</span></span> <span class="giallo-l"><span> version</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>raw</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">2</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 class="z-keyword"> assert</span><span> version</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>,</span><span class="z-storage z-type"> f</span><span class="z-string">&quot;</span><span class="z-string">Unsupported payload encoding version: </span><span class="z-constant">{</span><span>version</span><span class="z-constant">}</span><span class="z-string">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> bal_length</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>raw</span><span>[</span><span class="z-constant">2</span><span>:</span><span class="z-constant">6</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> txs_length</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>raw</span><span>[</span><span class="z-constant">6</span><span>:</span><span class="z-constant">10</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Extract data portions</span></span> <span class="giallo-l"><span> bal_bytes</span><span class="z-keyword"> =</span><span> raw</span><span>[</span><span class="z-constant">10</span><span> :</span><span class="z-constant"> 10</span><span class="z-keyword"> +</span><span> bal_length</span><span>]</span></span> <span class="giallo-l"><span> transactions_bytes</span><span class="z-keyword"> =</span><span> raw</span><span>[</span><span class="z-constant">10</span><span class="z-keyword"> +</span><span> bal_length</span><span> :</span><span class="z-constant"> 10</span><span class="z-keyword"> +</span><span> bal_length</span><span class="z-keyword"> +</span><span> txs_length</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> transactions</span><span class="z-keyword"> =</span><span class="z-constant"> RLP</span><span>.</span><span>decode</span><span>(</span><span>transactions_bytes</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> ExecutionPayloadData</span><span>(</span><span class="z-variable">blockAccessList</span><span class="z-keyword">=</span><span>bal_bytes</span><span>,</span><span class="z-variable"> transactions</span><span class="z-keyword">=</span><span>transactions</span><span>)</span></span></code></pre><h5 id="extract-data-from-type-3-tx">extract_data_from_type_3_tx</h5> <p>This method will be used to implement the modified logic in engine_getPayload.</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"> extract_data_from_type_3_tx</span><span>(</span><span class="z-variable z-parameter z-function">transactions</span><span>:</span><span> List</span><span>[</span><span>Transaction</span><span>]</span><span>)</span><span> -&gt;</span><span> Tuple</span><span>[</span><span>List</span><span>[</span><span>Blob</span><span>]</span><span>,</span><span> List</span><span>[</span><span>KZGCommitment</span><span>]</span><span>,</span><span> List</span><span>[</span><span>List</span><span>[</span><span>KZGProof</span><span>]</span><span>]</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"> Extract blobs, KZG commitments, and cell proofs from type-3 (blob) transactions.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-string"> Returns a tuple of (blobs, commitments, cell_proofs) in the order they appear</span></span> <span class="giallo-l"><span class="z-string"> in the transaction list.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-string"> Implementation note: This is not new logic - a function(s) like this should already be available in your existing getPayload/blob bundle implementation.</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-constant"> ...</span></span></code></pre> <p><strong>Invertibility invariant:</strong> <code>execution_payload_data_to_blobs</code> and <code>blobs_to_execution_payload_data</code> are mutual inverses on valid execution-payload data.</p> <h4 id="data-structures">Data structures</h4> <h5 id="executionpayloaddata">ExecutionPayloadData</h5> <p><strong>Execution-payload data</strong> refers to the subset of the ExecutionPayload that must be made available via blobs. This includes:</p> <ul> <li><code>bals</code> (Block Access List added in EIP-7928)</li> <li><code>transactions</code></li> </ul> <p>See <a href="https://wg-eips.ritovision.com/8142/#what-is-included-in-execution-payload-data">What is included in execution-payload data?</a> in the Rationale for details.</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"> ExecutionPayloadData</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"> Block Access List (BAL) from EIP-7928, RLP-encoded</span></span> <span class="giallo-l"><span> blockAccessList</span><span>:</span><span class="z-support"> bytes</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> List of transactions, each transaction is RLP-encoded</span></span> <span class="giallo-l"><span> transactions</span><span>:</span><span> List</span><span>[</span><span>Transaction</span><span>,</span><span class="z-constant"> MAX_TRANSACTIONS_PER_PAYLOAD</span><span>]</span></span></code></pre> <p><strong>Note:</strong> This is not an SSZ Container - fields are RLP-encoded as described in the encoding functions. The <code>MAX_TRANSACTIONS_PER_PAYLOAD</code> bound is inherited from the ExecutionPayload field limit defined in the consensus specification.</p> <h5 id="executionpayloadheader">ExecutionPayloadHeader</h5> <p>This EIP adds a new field to the <code>ExecutionPayloadHeader</code>:</p> <ul> <li>payload_blob_count : uint64</li> </ul> <p>Semantics:</p> <ul> <li>Let <code>blob_kzg_commitments</code> be the ordered list of kzg commitments referenced by the beacon block</li> <li>The first <code>payload_blob_count</code> entries of <code>blob_kzg_commitments</code> are the payload-blob commitments (i.e. commitments to the blobs that correspond to the payload data)</li> <li>The remaining entries (if any) are for type-3 blob transactions.</li> </ul> <h5 id="blobsbundle">BlobsBundle</h5> <p>For the zkEVM-optimized variant of <code>engine_getPayload</code>, this EIP extends <code>BlobsBundle</code> with an additional field:</p> <ul> <li><code>payload_kzg_proofs</code>: List[KZGProof]</li> </ul> <p>Semantics:</p> <ul> <li>Contains random point KZG proofs for payload blobs only (not type-3 transaction blobs)</li> <li>Used as private inputs to the zkEVM circuit for payload consistency verification via <code>verify_blob_kzg_proof_batch</code></li> <li>The length of this list equals <code>payload_blob_count</code></li> </ul> <h4 id="engine-api">Engine API</h4> <p>This section specifies two equivalent formulations of <code>new_payload</code>. Implementers choose one based on their execution context:</p> <ul> <li><strong>Native execution variant</strong>: Uses <code>blob_to_kzg_commitment</code> directly. Suitable for pre mandatory proofs implementations.</li> <li><strong>zkEVM-optimized variant</strong>: Uses polynomial openings via <code>verify_blob_kzg_proof_batch</code>. Avoids the multiscalar multiplication (MSM) which is expensive to prove in a zkEVM circuit.</li> </ul> <p>Both variants enforce identical validity conditions. A block valid under one is valid under the other.</p> <h5 id="engine-getpayload-native-variant">engine_getPayload - Native Variant</h5> <p>The builder must compute the payload blob count when constructing the block:</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_payload</span><span>(</span><span class="z-variable z-parameter z-function">payload_id</span><span>:</span><span> PayloadId</span><span>)</span><span> -&gt;</span><span> GetPayloadResponse</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 1. Build the block (select transactions, etc.)</span></span> <span class="giallo-l"><span> payload</span><span class="z-keyword"> =</span><span> build_execution_payload</span><span>(</span><span>payload_id</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"> 2. Compute payload blobs to determine count</span></span> <span class="giallo-l"><span> payload_data</span><span class="z-keyword"> =</span><span> get_execution_payload_data</span><span>(</span><span>payload</span><span>)</span></span> <span class="giallo-l"><span> payload_blobs</span><span class="z-keyword"> =</span><span> execution_payload_data_to_blobs</span><span>(</span><span>payload_data</span><span>)</span></span> <span class="giallo-l"><span> payload_blob_count</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span>payload_blobs</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"> 4. Set the count in the header</span></span> <span class="giallo-l"><span> payload</span><span>.</span><span>payload_blob_count</span><span class="z-keyword"> =</span><span> payload_blob_count</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 5. Compute blob commitments and cell proofs for payload blobs</span></span> <span class="giallo-l"><span> payload_commitments</span><span class="z-keyword"> =</span><span> [</span><span>blob_to_kzg_commitment</span><span>(</span><span>b</span><span>)</span><span class="z-keyword"> for</span><span> b</span><span class="z-keyword"> in</span><span> payload_blobs</span><span>]</span></span> <span class="giallo-l"><span> payload_versioned_hashes</span><span class="z-keyword"> =</span><span> [</span><span>kzg_commitment_to_versioned_hash</span><span>(</span><span>c</span><span>)</span><span class="z-keyword"> for</span><span> c</span><span class="z-keyword"> in</span><span> payload_commitments</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Compute cells and cell proofs</span></span> <span class="giallo-l"><span> payload_cells_and_proofs</span><span class="z-keyword"> =</span><span> [</span><span>compute_cells_and_kzg_proofs</span><span>(</span><span>b</span><span>)</span><span class="z-keyword"> for</span><span> b</span><span class="z-keyword"> in</span><span> payload_blobs</span><span>]</span></span> <span class="giallo-l"><span> payload_cell_proofs</span><span class="z-keyword"> =</span><span> [</span><span>proofs</span><span class="z-keyword"> for</span><span> _</span><span>,</span><span> proofs</span><span class="z-keyword"> in</span><span> payload_cells_and_proofs</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"> 6. Extract type-3 transaction blobs, commitments, and cell proofs</span></span> <span class="giallo-l"><span> type3_blobs</span><span>,</span><span> type3_commitments</span><span>,</span><span> type3_cell_proofs</span><span class="z-keyword"> =</span><span> extract_data_from_type_3_tx</span><span>(</span><span>payload</span><span>.</span><span>transactions</span><span>)</span></span> <span class="giallo-l"><span> type3_versioned_hashes</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> tx</span><span class="z-keyword"> in</span><span> payload</span><span>.</span><span>transactions</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> tx</span><span>.</span><span>type</span><span class="z-keyword"> ==</span><span class="z-constant"> BLOB_TX_TYPE</span><span>:</span></span> <span class="giallo-l"><span> type3_versioned_hashes</span><span>.</span><span>extend</span><span>(</span><span>tx</span><span>.</span><span>blob_versioned_hashes</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"> 7. Combine: payload blobs first, then type-3 blobs</span></span> <span class="giallo-l"><span> all_blobs</span><span class="z-keyword"> =</span><span> payload_blobs</span><span class="z-keyword"> +</span><span> type3_blobs</span></span> <span class="giallo-l"><span> all_commitments</span><span class="z-keyword"> =</span><span> payload_commitments</span><span class="z-keyword"> +</span><span> type3_commitments</span></span> <span class="giallo-l"><span> all_cell_proofs</span><span class="z-keyword"> =</span><span> payload_cell_proofs</span><span class="z-keyword"> +</span><span> type3_cell_proofs</span></span> <span class="giallo-l"><span> all_blob_versioned_hashes</span><span class="z-keyword"> =</span><span> payload_versioned_hashes</span><span class="z-keyword"> +</span><span> type3_versioned_hashes</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> GetPayloadResponse</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> execution_payload</span><span class="z-keyword">=</span><span>payload</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> blobs_bundle</span><span class="z-keyword">=</span><span>BlobsBundle</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> commitments</span><span class="z-keyword">=</span><span>all_commitments</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> blobs</span><span class="z-keyword">=</span><span>all_blobs</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> proofs</span><span class="z-keyword">=</span><span>all_cell_proofs</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> block_value</span><span class="z-keyword">=</span><span>calculate_block_value</span><span>(</span><span>payload</span><span>)</span></span> <span class="giallo-l"><span> )</span></span></code></pre> <p>Note: The builder must account for payload blob usage when selecting type-3 transactions to ensure the total blob count does not exceed <code>MAX_BLOBS_PER_BLOCK</code>.</p> <h5 id="engine-getpayload-zkevm-optimized-variant">engine_getPayload - zkEVM-Optimized Variant</h5> <p>For the zkEVM-optimized variant, the builder must additionally compute random point KZG proofs for the payload blobs, which will be used as private inputs in the zkEVM circuit for payload consistency verification.</p> <p>This variant extends <code>BlobsBundle</code> with an additional <code>payload_kzg_proofs</code> field containing random point KZG proofs for payload blobs.</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_payload_zk</span><span>(</span><span class="z-variable z-parameter z-function">payload_id</span><span>:</span><span> PayloadId</span><span>)</span><span> -&gt;</span><span> GetPayloadResponse</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 1. Build the block (select transactions, etc.)</span></span> <span class="giallo-l"><span> payload</span><span class="z-keyword"> =</span><span> build_execution_payload</span><span>(</span><span>payload_id</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"> 2. Compute payload blobs to determine count</span></span> <span class="giallo-l"><span> payload_data</span><span class="z-keyword"> =</span><span> get_execution_payload_data</span><span>(</span><span>payload</span><span>)</span></span> <span class="giallo-l"><span> payload_blobs</span><span class="z-keyword"> =</span><span> execution_payload_data_to_blobs</span><span>(</span><span>payload_data</span><span>)</span></span> <span class="giallo-l"><span> payload_blob_count</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span>payload_blobs</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"> 4. Set the count in the header</span></span> <span class="giallo-l"><span> payload</span><span>.</span><span>payload_blob_count</span><span class="z-keyword"> =</span><span> payload_blob_count</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 5. Compute commitments, cell proofs, and random point proofs for payload blobs</span></span> <span class="giallo-l"><span> payload_commitments</span><span class="z-keyword"> =</span><span> [</span><span>blob_to_kzg_commitment</span><span>(</span><span>b</span><span>)</span><span class="z-keyword"> for</span><span> b</span><span class="z-keyword"> in</span><span> payload_blobs</span><span>]</span></span> <span class="giallo-l"><span> payload_versioned_hashes</span><span class="z-keyword"> =</span><span> [</span><span>kzg_commitment_to_versioned_hash</span><span>(</span><span>c</span><span>)</span><span class="z-keyword"> for</span><span> c</span><span class="z-keyword"> in</span><span> payload_commitments</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Cell proofs</span></span> <span class="giallo-l"><span> payload_cells_and_proofs</span><span class="z-keyword"> =</span><span> [</span><span>compute_cells_and_kzg_proofs</span><span>(</span><span>b</span><span>)</span><span class="z-keyword"> for</span><span> b</span><span class="z-keyword"> in</span><span> payload_blobs</span><span>]</span></span> <span class="giallo-l"><span> payload_cell_proofs</span><span class="z-keyword"> =</span><span> [</span><span>proofs</span><span class="z-keyword"> for</span><span> _</span><span>,</span><span> proofs</span><span class="z-keyword"> in</span><span> payload_cells_and_proofs</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Random point proofs for payload consistency verification</span></span> <span class="giallo-l"><span> payload_random_point_proofs</span><span class="z-keyword"> =</span><span> [</span><span>compute_blob_kzg_proof</span><span>(</span><span>b</span><span>,</span><span> c</span><span>)</span><span class="z-keyword"> for</span><span> b</span><span>,</span><span> c</span><span class="z-keyword"> in</span><span class="z-support"> zip</span><span>(</span><span>payload_blobs</span><span>,</span><span> payload_commitments</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"> 6. Extract type-3 transaction blobs, commitments, and cell proofs</span></span> <span class="giallo-l"><span> type3_blobs</span><span>,</span><span> type3_commitments</span><span>,</span><span> type3_cell_proofs</span><span class="z-keyword"> =</span><span> extract_data_from_type_3_tx</span><span>(</span><span>payload</span><span>.</span><span>transactions</span><span>)</span></span> <span class="giallo-l"><span> type3_versioned_hashes</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> tx</span><span class="z-keyword"> in</span><span> payload</span><span>.</span><span>transactions</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> tx</span><span>.</span><span>type</span><span class="z-keyword"> ==</span><span class="z-constant"> BLOB_TX_TYPE</span><span>:</span></span> <span class="giallo-l"><span> type3_versioned_hashes</span><span>.</span><span>extend</span><span>(</span><span>tx</span><span>.</span><span>blob_versioned_hashes</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"> 7. Combine: payload blobs first, then type-3 blobs</span></span> <span class="giallo-l"><span> all_blobs</span><span class="z-keyword"> =</span><span> payload_blobs</span><span class="z-keyword"> +</span><span> type3_blobs</span></span> <span class="giallo-l"><span> all_commitments</span><span class="z-keyword"> =</span><span> payload_commitments</span><span class="z-keyword"> +</span><span> type3_commitments</span></span> <span class="giallo-l"><span> all_cell_proofs</span><span class="z-keyword"> =</span><span> payload_cell_proofs</span><span class="z-keyword"> +</span><span> type3_cell_proofs</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> GetPayloadResponse</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> execution_payload</span><span class="z-keyword">=</span><span>payload</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> blobs_bundle</span><span class="z-keyword">=</span><span>BlobsBundle</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> commitments</span><span class="z-keyword">=</span><span>all_commitments</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> blobs</span><span class="z-keyword">=</span><span>all_blobs</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> proofs</span><span class="z-keyword">=</span><span>all_cell_proofs</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> payload_kzg_proofs</span><span class="z-keyword">=</span><span>payload_random_point_proofs</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> block_value</span><span class="z-keyword">=</span><span>calculate_block_value</span><span>(</span><span>payload</span><span>)</span></span> <span class="giallo-l"><span> )</span></span></code></pre> <p><strong>Note for implementors:</strong></p> <ul> <li>The <code>payload_kzg_proofs</code> field contains KZG opening proofs for payload blobs only. It is used for payload consistency verification via <code>verify_blob_kzg_proof_batch</code>.</li> <li>The builder/prover should extract the first <code>payload_blob_count</code> commitments from <code>all_commitments</code> (i.e., <code>all_commitments[:payload_blob_count]</code>). This corresponds to the <code>payload_kzg_commitments</code> parameter in the zkEVM variant of <code>engine_newPayload</code>.</li> </ul> <h5 id="engine-newpayload-native-execution-variant">engine_newPayload - Native Execution Variant</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"> new_payload</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> payload</span><span>:</span><span> ExecutionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> expected_blob_versioned_hashes</span><span>:</span><span> List</span><span>[</span><span>VersionedHash</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span>)</span><span> -&gt;</span><span> PayloadStatus</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"> 1. Derive payload blobs and commitments</span></span> <span class="giallo-l"><span> payload_data</span><span class="z-keyword"> =</span><span> get_execution_payload_data</span><span>(</span><span>payload</span><span>)</span></span> <span class="giallo-l"><span> payload_blobs</span><span class="z-keyword"> =</span><span> execution_payload_data_to_blobs</span><span>(</span><span>payload_data</span><span>)</span></span> <span class="giallo-l"><span> payload_blob_count</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span>payload_blobs</span><span>)</span></span> <span class="giallo-l"><span> payload_commitments</span><span class="z-keyword"> =</span><span> [</span><span>blob_to_kzg_commitment</span><span>(</span><span>b</span><span>)</span><span class="z-keyword"> for</span><span> b</span><span class="z-keyword"> in</span><span> payload_blobs</span><span>]</span></span> <span class="giallo-l"><span> payload_versioned_hashes</span><span class="z-keyword"> =</span><span> [</span><span>kzg_commitment_to_versioned_hash</span><span>(</span><span>c</span><span>)</span><span class="z-keyword"> for</span><span> c</span><span class="z-keyword"> in</span><span> payload_commitments</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"> 2. Verify payload_blob_count matches header</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> payload_blob_count</span><span class="z-keyword"> ==</span><span> payload</span><span>.</span><span>payload_blob_count</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 3. Extract type-3 tx versioned hashes</span></span> <span class="giallo-l"><span> type3_versioned_hashes</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> tx</span><span class="z-keyword"> in</span><span> payload</span><span>.</span><span>transactions</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> tx</span><span>.</span><span>type</span><span class="z-keyword"> ==</span><span class="z-constant"> BLOB_TX_TYPE</span><span>:</span></span> <span class="giallo-l"><span> type3_versioned_hashes</span><span>.</span><span>extend</span><span>(</span><span>tx</span><span>.</span><span>blob_versioned_hashes</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"> 4. Verify versioned hashes: payload blobs first, then type-3</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> expected_blob_versioned_hashes</span><span class="z-keyword"> ==</span><span> payload_versioned_hashes</span><span class="z-keyword"> +</span><span> type3_versioned_hashes</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 5. Run EL STF</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> execute_payload</span><span>(</span><span>payload</span><span>)</span></span></code></pre><h5 id="engine-newpayload-zkevm-optimized-variant">engine_newPayload - zkEVM-Optimized Variant</h5> <p><strong>Note:</strong> Once zkEVM proofs are required for consensus, <code>newPayload</code> will be executed inside a zkEVM to generate a proof, rather than being executed natively by validators. This variant is designed to be cheaper in that context.</p> <p>This variant replaces the MSM in <code>blob_to_kzg_commitment</code> with polynomial opening proofs, which are cheaper to verify inside a zkEVM. The payload, commitments and KZG proofs are private inputs to the zkEVM circuit, while the corresponding versioned hashes (and payload header) are public inputs.</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"> new_payload</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> payload</span><span>:</span><span> ExecutionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> expected_blob_versioned_hashes</span><span>:</span><span> List</span><span>[</span><span>VersionedHash</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> public input</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> BiB additions: prefix metadata for payload blobs</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> payload_kzg_commitments</span><span>:</span><span> List</span><span>[</span><span>KZGCommitment</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> private input</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> payload_kzg_proofs</span><span>:</span><span> List</span><span>[</span><span>KZGProof</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> private input</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span>)</span><span> -&gt;</span><span> PayloadStatus</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"> 0. Declared payload blob count from the header</span></span> <span class="giallo-l"><span> n</span><span class="z-keyword"> =</span><span> payload</span><span>.</span><span>payload_blob_count</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>payload_kzg_commitments</span><span>)</span><span class="z-keyword"> ==</span><span> n</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>payload_kzg_proofs</span><span>)</span><span class="z-keyword"> ==</span><span> n</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 1. Construct payload blobs from execution-payload data</span></span> <span class="giallo-l"><span> payload_data</span><span class="z-keyword"> =</span><span> get_execution_payload_data</span><span>(</span><span>payload</span><span>)</span></span> <span class="giallo-l"><span> payload_blobs</span><span class="z-keyword"> =</span><span> execution_payload_data_to_blobs</span><span>(</span><span>payload_data</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>payload_blobs</span><span>)</span><span class="z-keyword"> ==</span><span> n</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 2. Check the commitments correspond to the expected versioned hash prefix</span></span> <span class="giallo-l"><span> payload_versioned_hashes</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span> kzg_commitment_to_versioned_hash</span><span>(</span><span>c</span><span>)</span><span class="z-keyword"> for</span><span> c</span><span class="z-keyword"> in</span><span> payload_kzg_commitments</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> expected_blob_versioned_hashes</span><span>[</span><span>:</span><span>n</span><span>]</span><span class="z-keyword"> ==</span><span> payload_versioned_hashes</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 3. Verify blob–commitment consistency using batch KZG proof verification</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> verify_blob_kzg_proof_batch</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> blobs</span><span class="z-keyword">=</span><span>payload_blobs</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> commitments</span><span class="z-keyword">=</span><span>payload_kzg_commitments</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> proofs</span><span class="z-keyword">=</span><span>payload_kzg_proofs</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"> 4. Proceed with standard EL payload validation / execution</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> execute_payload</span><span>(</span><span>payload</span><span>)</span></span></code></pre><h3 id="consensus-layer">Consensus Layer</h3> <h4 id="validation">Validation</h4> <p>The consensus layer does not introduce new blob specific validation rules for payload-blobs beyond what we have for EIP-4844/EIP-7594.</p> <p>The Consensus Layer relies on <code>payload_blob_count</code> in the ExecutionPayloadHeader to interpret the ordering of blob commitments, but otherwise treats payload blobs identically to other blobs for availability and networking.</p> <h3 id="networking">Networking</h3> <p>BiB reuses the existing blob networking mechanism.</p> <p>We note the following for consideration:</p> <ul> <li> <p>Once proofs are made mandatory, a mechanism will be needed for execution payload retrieval. <a href="https://wg-eips.ritovision.com/7732/">EIP-7732</a> introduces an <code>execution_payload</code> gossip topic that we can use for this purpose. However, in the context of mandatory proofs where a super majority of stake operates zk validators (which only listen to header topics), a malicious builder could publish only the payload in blobs and gossip the execution payload header without gossiping on the <code>execution_payload</code> topic. This would allow zk validators to attest, but other nodes depending on the full payload from the gossip topic would be unable to progress.</p> </li> <li> <p>To mitigate this, nodes can implement a fallback mechanism: if they don't receive the payload on the <code>execution_payload</code> topic, they reconstruct it from the first <code>payload_blob_count</code> blobs and then seed the <code>execution_payload</code> topic themselves. This creates a resilient system where every node acts as a "bridge node" when needed, similar to how rollups use L2 gossip as a fast path but fall back to L1 data availability.</p> </li> <li> <p>Unlike most type-3 blob transactions, payload-blobs will not have been propagated to the network before a block is built. Depending on the deadlines imposed by ePBS, this may imply higher bandwidth requirements from block builders.</p> </li> </ul> <h3 id="fee-accounting">Fee Accounting</h3> <p>BiB introduces protocol mandated blob usage, rather than user initiated via type-3 transactions. Fee accounting for payload-blobs differ in nature from transaction blob fees as a result.</p> <h4 id="who-pays">Who pays?</h4> <p>This EIP does not mandate that payload-blobs pay a per-blob fee like transaction blobs.</p> <p>Instead payload-blobs are treated as a protocol-accepted cost when constructing the block. In particular:</p> <ul> <li>Payload-blobs do not correspond to a user transaction and therefore do not naturally map to a user-paid blob fee.</li> <li>The cost of including payload-blobs, in terms of blob gas usage, is accepted by the protocol as a necessary cost for maintaining data availability.</li> </ul> <h4 id="do-payload-blobs-compete-with-transaction-blobs-for-capacity">Do payload-blobs compete with transaction blobs for capacity?</h4> <p>Because payload blobs consume blob gas, they directly influence blob congestion and the blob base fee.</p> <h4 id="can-a-builder-artificially-inflate-blob-gas-usage">Can a builder artificially inflate blob gas usage?</h4> <p>A potential concern is whether a malicious builder could create artificially large execution payloads to inflate blob gas usage.</p> <p>This attack is economically constrained: to increase the size of the execution payload, a builder must include additional transactions with calldata. Since calldata costs execution gas, the builder would need to pay for this additional data through the normal gas mechanism. The cost of including extra calldata makes it economically unfavorable to artificially inflate payload size solely to manipulate blob fees.</p> <h4 id="open-questions-and-future-considerations">Open questions and future considerations</h4> <!-- TODO --> <ul> <li>Networking related: Payload-blobs require higher bandwidth due to the fact that they will not have been in the public mempool</li> <li>Explicit protocol level pricing for payload blobs</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="what-is-included-in-execution-payload-data">What is included in execution-payload data?</h3> <p>Execution-payload data includes <code>bals</code> (Block Access Lists from EIP-7928) and <code>transactions</code>.</p> <p><strong>Why transactions?</strong> Transaction data is the only component of the execution payload that cannot be derived from other components and is not provided by the consensus layer.</p> <p><strong>Why BALs?</strong> While BALs are technically the output of executing transactions and could be recomputed, once zkEVM proofs become mandatory for consensus, validators no longer execute payloads. A malicious builder could publish a valid proof and withhold both the execution payload data and the BALs. This would prevent other builders from constructing subsequent blocks and prevent RPC providers from serving the full state. Including BALs in payload-blobs ensures they remain available.</p> <p><strong>Why not withdrawals?</strong> Withdrawals can be derived on the consensus layer.</p> <p><strong>Why not execution requests?</strong> Execution requests can be recomputed from transactions and do not suffer from the same withholding attack as BALs because they are required by the consensus layer for validation.</p> <p><strong>Why not the header?</strong> The header cannot be put into blobs because it contains <code>payload_blob_count</code>, which depends on the number of blobs; causing a circular dependency.</p> <p><strong>Encoding optimization:</strong> The encoding includes an 8-byte header: <code>[4 bytes BAL length] [4 bytes transaction length]</code>. This allows extracting just the tx data after fetching the first blob.</p> <!-- TODO --> <p>TODO: We could also put the number of blobs that the BAL occupies in the execution payload header.</p> <h3 id="builder-discretion-vs-reserving-k-blobs">Builder discretion vs reserving <code>k</code> blobs</h3> <p>This EIP specifies that the block builder choose <code>payload_blob_count</code>, subject to the constraint imposed by <code>MAX_BLOBS_PER_BLOCK</code>.</p> <p>An alternative would have been to always reserve <code>k</code> blobs, where <code>k</code> corresponds to the worst case execution payload size. While this provides better predictability, it reduces flexibility under blob congestion.</p> <h3 id="why-not-encode-execution-payload-data-inside-the-core-el-execution-logic">Why not encode execution-payload data inside the core EL execution logic?</h3> <p>Doing it in the EL STF would require payload-blob commitments or versioned hashes to be made visible inside the core execution logic, rather than being handled at the Engine API boundary.</p> <h3 id="when-zkevm-proofs-become-mandatory-why-can-t-zk-attestors-download-the-full-execution-payload">When zkEVM proofs become mandatory, why can't zk-attestors download the full execution payload?</h3> <p>The execution payload grows linearly with the gas limit. Requiring attesters to download the payload for DA would create an increasing bandwidth burden as the gas limit grows.</p> <h3 id="compression-algorithm-for-encoding-execution-payload-data">Compression algorithm for encoding execution-payload data</h3> <p>Compression can be used on the serialized execution-payload data. This (in theory) should allow the usage of less payload-blobs, depending on the compression ratio. The tradeoffs being:</p> <ul> <li>That we will use more CPU/proving cycles for decompression</li> <li>A breaking change since we want to decompress on the hot-path. What this means is that the transactions would need to be compressed in the payload, and then decompressed when we attempt to validate it.</li> </ul> <p>Whether we should use a compression algorithm and which one requires more investigation, in particular we need to investigate:</p> <ul> <li>The average compression ratios achieved</li> <li>The proving cycle overhead</li> <li>The invasiveness of now requiring consensus aware objects to be compressed when passed for validation.</li> </ul> <p>For now we recommend using no compression algorithm and operating on uncompressed data.</p> <h3 id="serialization-algorithm-for-encoding-execution-payload-data">Serialization algorithm for encoding execution-payload data</h3> <p>Serialization of the execution-payload data uses RLP. Since transactions in the ExecutionPayload are already RLP-encoded, we simply RLP-encode the list of transaction bytes without any additional transformation.</p> <p>While a more zk-friendly serialization algorithm could be beneficial in the future, this EIP uses RLP for simplicity. Once EIP-7807 (SSZ execution blocks) is implemented, the encoding can be updated to SSZ-serialize the list of SSZ-encoded transaction bytes.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This requires changes to the execution payload header and the EL STF; so requires a fork. Nodes that do not implement BiB will not be able to validate blocks after activation.</p> <h2 id="test-cases">Test Cases</h2> <!-- TODO --> <p>TODO</p> <h2 id="reference-implementation">Reference Implementation</h2> <!-- TODO --> <p>TODO</p> <h2 id="security-considerations">Security Considerations</h2> <p><strong>Interaction with blob congestion and denial-of-service</strong></p> <p>Payload-blobs consume blob gas and therefore are subject to the same congestion control mechanisms and blob limits as transaction blobs.</p> <p>As a byproduct, this ensures that a malicious block producer cannot make arbitrarily large execution payloads without accounting for blob gas limits. While a block producer could theoretically drive up the blob base fee by creating large payloads, this attack is economically constrained by calldata costs (see <a href="https://wg-eips.ritovision.com/8142/#fee-accounting">Fee Accounting</a> for details).</p> <p><strong>Data withholding</strong></p> <p>An attacker cannot withhold execution payload data without also withholding blob data, which would violate existing DAS guarantees and cause the block to be rejected by the consensus layer.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2026-01-14T00:00:00+00:00 2026-02-11T14:49:27+00:00 Wei Han Nghttps://github.com/weiihann https://wg-eips.ritovision.com/8125/

Adds bounded-lifetime contract storage via TMPLOAD/TMPSTORE opcodes that is automatically cleared on a fixed schedule.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces <em>temporary storage</em>: a new contract-accessible key-value store that persists across transactions and blocks, but is automatically cleared at a protocol-defined schedule. Two new opcodes are added:</p> <ul> <li><code>TMPSTORE(key, value)</code> to write temporary storage for the executing contract.</li> <li><code>TMPLOAD(key)</code> to read temporary storage for the executing contract.</li> </ul> <p>Temporary storage is intended for data that does not need indefinite retention, providing a safer alternative to using permanent state for ephemeral data and enabling bounded growth of this class of state.</p> <h2 id="motivation">Motivation</h2> <p><img src="https://wg-eips.ritovision.com/8125/./assets/1.png" alt="" /></p> <p><em>Figure 1: Over 60% of the storage slots are written once and never accessed again onchain.</em></p> <p>Permanent contract storage is costly because it increases long-term node resource requirements (disk, I/O, state maintenance). However, many applications write data that is only valuable for a bounded time window.</p> <p>This EIP provides:</p> <ul> <li><strong>Bounded lifetime semantics</strong> without requiring explicit deletes.</li> <li><strong>Predictable clearing</strong> that can be relied upon at the application layer.</li> <li><strong>A building block</strong> for reducing state growth created by ephemeral use cases.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="constants-and-parameters">Constants and parameters</h3> <table><thead><tr><th>Name</th><th style="text-align: center">Value</th><th>Description</th></tr></thead><tbody> <tr><td><code>FORK_BLOCK</code></td><td style="text-align: center">TBD</td><td>Activation block of this EIP</td></tr> <tr><td><code>TEMP_STORAGE_PERIOD</code></td><td style="text-align: center">TBD</td><td>The number of blocks that the temporary storage holds for a given period</td></tr> <tr><td><code>TEMP_STORAGE_SYSTEM_ADDRESS_0</code></td><td style="text-align: center">TBD</td><td>First reserved address used to store temporary storage</td></tr> <tr><td><code>TEMP_STORAGE_SYSTEM_ADDRESS_1</code></td><td style="text-align: center">TBD</td><td>Second reserved address used to store temporary storage</td></tr> <tr><td><code>TMPLOAD_GAS</code></td><td style="text-align: center">TBD</td><td>The gas cost of a warm read at temporary storage slot</td></tr> <tr><td><code>COLD_TMPLOAD_COST</code></td><td style="text-align: center">TBD</td><td>The gas cost surchage of a cold access at the temporary storage</td></tr> <tr><td><code>TMPSTORE_SET_GAS</code></td><td style="text-align: center">TBD</td><td>The gas cost of setting a slot from zero to non-zero at the temporary storage</td></tr> <tr><td><code>TMPSTORE_RESET_GAS</code></td><td style="text-align: center">TBD</td><td>The gas cost of changing a non-zero slot to another value at the temporary storage</td></tr> </tbody></table> <h3 id="temporary-storage-data-model">Temporary storage data model</h3> <p>Temporary storage is backed by <strong>two reserved system accounts</strong> at <code>TEMP_STORAGE_SYSTEM_ADDRESS_0</code> and <code>TEMP_STORAGE_SYSTEM_ADDRESS_1</code>.</p> <p>The temporary storage keyspace is a mapping of <code>(contract_address, key) -&gt; value</code>, where:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>derived_slot_key = keccak256(contract_address || key)</span></span></code></pre> <p>Temporary storage values are stored in the regular storage tries of the system accounts using <code>derived_slot_key</code> as the slot key.</p> <h3 id="periodic-rollover-storage-reset">Periodic rollover (storage reset)</h3> <p>Temporary storage is organized into periods, each of length <code>TEMP_STORAGE_PERIOD</code> blocks after activation.</p> <p>For blocks with <code>block.number &gt;= FORK_BLOCK</code>, define:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>period_index(block_number) = floor((block_number - FORK_BLOCK) / TEMP_STORAGE_PERIOD)</span></span></code></pre> <p>Define the current and previous system accounts for a block <code>B</code> (where <code>B.number &gt;= FORK_BLOCK</code>) as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>current_index = period_index(B.number) % 2</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>if current_index == 0:</span></span> <span class="giallo-l"><span> CURRENT_SYSADDR = TEMP_STORAGE_SYSTEM_ADDRESS_0</span></span> <span class="giallo-l"><span> PREVIOUS_SYSADDR = TEMP_STORAGE_SYSTEM_ADDRESS_1</span></span> <span class="giallo-l"><span>else if current_index == 1:</span></span> <span class="giallo-l"><span> CURRENT_SYSADDR = TEMP_STORAGE_SYSTEM_ADDRESS_1</span></span> <span class="giallo-l"><span> PREVIOUS_SYSADDR = TEMP_STORAGE_SYSTEM_ADDRESS_0</span></span></code></pre> <p>At the first block of each new period, the protocol MUST clear the storage of the system account that becomes the current.</p> <p>When processing a block <code>B</code> (with parent <code>P</code>) where both are <code>&gt;= FORK_BLOCK</code>, if <code>period_index(B.number) &gt; period_index(P.number)</code>, then before executing transactions in <code>B</code>, the protocol MUST perform:</p> <ul> <li><code>CURRENT_SYSADDR.storageRoot = EMPTY_TRIE_ROOT</code></li> </ul> <p>where <code>CURRENT_SYSADDR</code> is computed from <code>B.number</code> as specified above.</p> <p>No other accounts are modified by the rollover.</p> <p><strong>Effect:</strong> After rollover, entries written in the immediately previous period remain readable via <code>PREVIOUS_SYSADDR</code> for one additional period, while entries older than one period are removed.</p> <h3 id="new-opcodes">New opcodes</h3> <p>Add 2 new opcodes as follows:</p> <h4 id="tmpload-key"><code>TMPLOAD(key)</code></h4> <p>Compute <code>derived_slot_key</code> from <code>(contract_address, key)</code>. Then load <code>derived_slot_key</code> from <code>CURRENT_SYSADDR</code> first. If it doesn't exist (i.e. <code>value == 0</code> ), then load <code>derived_slot_key</code> from <code>PREV_SYSADDR</code>.</p> <h4 id="tmpstore-key-value"><code>TMPSTORE(key,value)</code></h4> <p>Compute <code>derived_slot_key</code> from <code>(contract_address, key)</code>. Then:</p> <ul> <li>If <code>value != 0</code>, store in the storage of <code>CURRENT_SYSADDR</code>.</li> <li>If <code>value == 0</code>, delete slot from both <code>CURRENT_SYSADDR</code> and <code>PREV_SYSADDR</code>.</li> </ul> <p><strong>Rationale:</strong> Because reads fall back from current to previous, clearing only the current store would allow an older previous-period value to be returned. Clearing both ensures <code>TMPSTORE(key,0)</code> makes subsequent <code>TMPLOAD(key)</code> return <code>0</code> (until a new non-zero is written).</p> <p>The call rules should follow <code>SSTORE</code> and <code>SLOAD</code>.</p> <p>The gas rules should follow the conventions in <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a> and <a href="https://wg-eips.ritovision.com/2200/">EIP-2200</a> referencing <code>SSTORE</code> and <code>SLOAD</code>, except that:</p> <ul> <li>The gas costs should be much lower than <code>SSTORE</code> and <code>SLOAD</code>, but higher than <code>TSLOAD</code> and <code>TSTORE</code></li> <li>No refunds are given for clearing temporary storage</li> <li><code>TMPLOAD</code> MAY perform up to 2 storage reads (current then previous). Gas MUST account for this behaviour.</li> <li>Deletion in <code>TMPSTORE</code> is more expensive than creation/modification as the storage root of both system accounts are updated. Gas MUST account for this behaviour.</li> </ul> <h3 id="activation-and-reserved-address">Activation and reserved address</h3> <p>At <code>FORK_BLOCK</code>, the chain MUST treat <code>TEMP_STORAGE_SYSTEM_ADDRESS_0</code> and <code>TEMP_STORAGE_SYSTEM_ADDRESS_1</code> as reserved addresses:</p> <ul> <li>If either does not exist in the state trie, it is created with: <ul> <li><code>nonce = 1</code></li> <li><code>balance = 0</code></li> <li><code>codeHash = EMPTY_CODE_HASH</code></li> <li><code>storageRoot = EMPTY_TRIE_ROOT</code></li> </ul> </li> </ul> <p>No contract code is deployed at this address.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-not-just-use-transient-storage-eip-1153">Why not just use transient storage (EIP-1153)?</h3> <p><a href="https://wg-eips.ritovision.com/1153/">EIP-1153</a> (transient storage) is discarded after every transaction, which is ideal for intra-tx operations. This EIP targets a different class of use cases where data must persist across multiple transactions/blocks, but does not need indefinite retention.</p> <h3 id="why-two-period-rollover">Why two-period rollover?</h3> <p>Two-period rollover provides a stronger usability guarantee:</p> <ul> <li>An entry is retained for <strong>at least</strong> one full <code>TEMP_STORAGE_PERIOD</code> after it is written (it will be readable in the next period via the previous-period system account).</li> <li>An entry is retained for <strong>at most</strong> two periods (once the current-period system account is cleared and reused).</li> </ul> <p>This provides a simple mental model for contract developers. That is, if an entry is stored in temporary storage, it will at least last for <code>TEMP_STORAGE_PERIOD</code>.</p> <p>In contrast, a single global rollover makes effective lifetime depend on when data is written within the period: a write near the end of a period could be cleared almost immediately, which may not be developer-friendly.</p> <h3 id="why-two-system-accounts">Why two system accounts?</h3> <p>Using two reserved system accounts allows constant-time rollover:</p> <ul> <li>At each period boundary, only the <strong>current-period</strong> system account is reset by setting a single <code>storageRoot = EMPTY_TRIE_ROOT</code>.</li> <li>The previous-period system account remains intact for one more period.</li> <li>Storage older than one period becomes unreachable and can be pruned.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a hard fork to implement.</p> <p>It does not change behavior of any existing opcodes. Therefore, it is backward compatible with all existing contract accounts.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li><strong>DoS surface</strong>: Temporary storage writes still create state that must be processed and stored for at least 1 period. Gas costs should be calibrated so that worst-case temp writes do not create new per-block disk I/O DoS attack vectors beyond existing storage writes.</li> <li><strong>Reorg safety</strong>: Clients should retain sufficient history to handle plausible reorg depths.</li> <li><strong>Application safety</strong>: Contracts MUST treat temp storage as ephemeral and handle the case where entries are unexpectedly missing.</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> 2026-01-11T00:00:00+00:00 2026-02-11T14:49:27+00:00 Paul Razvan Berghttps://github.com/PaulRBerg https://wg-eips.ritovision.com/8123/

Add an RPC method to query the EIP-7825 transaction gas limit cap

<h2 id="abstract">Abstract</h2> <p>This EIP specifies a new Ethereum JSON-RPC method, <code>eth_txGasLimitCap</code>, which returns the maximum transaction gas limit (<code>tx.gas</code>) that the node will accept under the current fork rules (and any stricter local policy). This enables wallets, SDKs, bundlers, and tooling to discover the effective per-transaction gas limit cap without simulation or out-of-band knowledge.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/7825/">EIP-7825</a> introduces a protocol-level per-transaction gas limit cap (e.g. <code>2^24 = 16,777,216</code> on Ethereum) to bound worst-case single-transaction work. However, it does not specify any way to query this cap.</p> <p>As a consequence, users and tools must:</p> <ul> <li>infer it from failed transaction submissions,</li> <li>hardcode network assumptions,</li> <li>read client source code,</li> <li>or rely on Internet documentation.</li> </ul> <p>This is brittle because:</p> <ul> <li>the cap may change in future upgrades,</li> <li>different chains intentionally set different cap values (e.g. Arbitrum and Polygon both use <code>32,000,000</code>),</li> <li>and there already are some proposals to make the transaction gas limit cap dynamic, rather than hardcoded, based on new fee calculation rules</li> </ul> <h2 id="specification">Specification</h2> <p>The key words “MUST", “MUST NOT", “SHOULD", and “MAY" are to be interpreted as described in RFC 2119.</p> <h3 id="new-method-eth-txgaslimitcap">New method: <code>eth_txGasLimitCap</code></h3> <h4 id="request">Request</h4> <ul> <li><strong>Method</strong>: <code>eth_txGasLimitCap</code></li> <li><strong>Params</strong>: <code>[]</code> (no parameters)</li> </ul> <h4 id="response">Response</h4> <ul> <li><strong>Result</strong>: <code>QUANTITY</code> or <code>null</code> <ul> <li>If the node enforces a finite transaction gas limit cap, it <strong>MUST</strong> return that cap as a <code>QUANTITY</code>.</li> <li>If the node does not enforce a finite cap, it <strong>MUST</strong> return <code>null</code>.</li> </ul> </li> </ul> <p>Returning <code>null</code> indicates that no finite per-transaction gas limit is enforced by the node.</p> <h4 id="semantics">Semantics</h4> <p>Let:</p> <ul> <li><code>protocolCap</code> be the maximum <code>tx.gas</code> permitted by the active protocol rules at the node's current head (e.g. from EIP-7825 when enabled).</li> <li><code>policyCap</code> be any stricter local cap applied by the node to transaction acceptance (e.g. txpool admission), if configured; otherwise, unbounded.</li> </ul> <p>Then the node <strong>MUST</strong> return:</p> <ul> <li><code>min(protocolCap, policyCap)</code> if finite, else <code>null</code>.</li> </ul> <p>A node <strong>MUST NOT</strong> return a value higher than the protocol cap when the protocol cap is finite.</p> <h4 id="example">Example</h4> <p>Ethereum (EIP-7825 cap = <code>2^24</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_txGasLimitCap</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>]</span><span> }</span></span></code></pre><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">0x1000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span></span></code></pre> <p>A chain with a <code>32,000,000</code> cap:</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">0x1e84800</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>A dedicated method is needed because there is currently no way to query the maximum allowed <code>tx.gas</code> without simulation or out-of-band knowledge.</p> <p>Returning the <em>effective</em> cap (<code>min(protocolCap, policyCap)</code>) matches what users need when constructing transactions to submit.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP adds a new JSON-RPC method and does not modify existing methods. Existing clients and applications remain compatible.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Pseudo code:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>if protocol has finite tx gas cap at head:</span></span> <span class="giallo-l"><span> protocolCap = that value</span></span> <span class="giallo-l"><span>else:</span></span> <span class="giallo-l"><span> protocolCap = +infinity</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>if protocol has policy cap:</span></span> <span class="giallo-l"><span> policyCap = that value</span></span> <span class="giallo-l"><span>else:</span></span> <span class="giallo-l"><span> policyCap = +infinity</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>cap = min(protocolCap, policyCap)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>if cap is finite:</span></span> <span class="giallo-l"><span> return cap</span></span> <span class="giallo-l"><span>else:</span></span> <span class="giallo-l"><span> return null</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>This EIP only exposes information that is already public or otherwise observable by probing. It does not expose secrets or user data.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via CC0.</p> 2026-01-07T00:00:00+00:00 2026-02-11T14:49:27+00:00 Helkominehttps://github.com/Helkomine https://wg-eips.ritovision.com/8120/

Adds EVM opcodes for efficient single-byte memory and calldata loads.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces new EVM opcodes that allow loading a single byte from memory or calldata in a single operation, reducing gas cost and bytecode size compared to existing patterns based on <code>MLOAD (0x51)</code> or <code>CALLDATALOAD (0x35)</code> followed by bit shifting.</p> <h2 id="motivation">Motivation</h2> <p>Currently, the only way to read a single byte from calldata or memory is to use <code>CALLDATALOAD</code> or <code>MLOAD</code> and then shift the loaded 32-byte word. For example, reading the byte at offset x from calldata requires:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH x</span></span> <span class="giallo-l"><span>CALLDATALOAD</span></span> <span class="giallo-l"><span>PUSH1 248</span></span> <span class="giallo-l"><span>SHR</span></span></code></pre> <p>This pattern increases runtime gas cost and adds three extra bytes to the deployed bytecode for each single-byte access. Contracts that frequently parse byte-oriented calldata or instruction streams incur unnecessary overhead. This EIP proposes two new opcodes that allow loading a single byte directly in one operation.</p> <h2 id="specification">Specification</h2> <h3 id="mload8-tbd">MLOAD8 (TBD)</h3> <!-- TODO: Replace TBD with assigned opcode value --> <ul> <li><strong>Stack input</strong>: <code>offset</code></li> <li><strong>Stack output</strong>: <code>value</code></li> </ul> <p>Reads one byte from memory at position offset and pushes it onto the stack as a 32-byte word, with the byte placed in the least significant position. Memory expansion occurs prior to the load, after which the loaded byte is read. If the accessed byte lies beyond the previously allocated memory, the returned value is 0 due to zero-initialization. Memory expansion rules apply in the same way as for <code>MSTORE8</code> (extending memory to at least <code>offset + 1</code> bytes).</p> <h3 id="calldataload8-tbd">CALLDATALOAD8 (TBD)</h3> <!-- TODO: Replace TBD with assigned opcode value --> <ul> <li><strong>Stack input</strong>: <code>offset</code></li> <li><strong>Stack output</strong>: <code>value</code></li> </ul> <p>Reads one byte from calldata at position offset and pushes it onto the stack as a 32-byte word, with the byte placed in the least significant position. If offset is greater than or equal to <code>CALLDATASIZE (0x36)</code>, the returned value is 0.</p> <h3 id="gas-cost">Gas Cost</h3> <ul> <li>Base cost: 3 gas</li> <li><code>MLOAD8</code> additionally incurs memory expansion cost as defined by existing memory access rules. The base gas cost matches <code>MLOAD</code>, <code>MSTORE8</code>, and <code>CALLDATALOAD</code>, ensuring consistency with existing EVM pricing.</li> </ul> <h3 id="exceptional-conditions">Exceptional Conditions</h3> <p>Execution results in an exceptional halt if:</p> <ul> <li>There is insufficient gas to execute the instruction</li> <li>There are insufficient stack items (stack underflow)</li> </ul> <p>In both cases, execution halts and the current call frame is reverted, consistent with existing EVM behavior.</p> <h2 id="rationale">Rationale</h2> <h3 id="opcode-symmetry">Opcode Symmetry</h3> <p><code>MLOAD8</code> serves as a natural counterpart to <code>MSTORE8 (0x53)</code>: one stores exactly one byte from the stack to memory, while the other loads exactly one byte from memory to the stack. This symmetry improves conceptual clarity and developer ergonomics.</p> <h3 id="efficiency-for-byte-oriented-contracts">Efficiency for Byte-Oriented Contracts</h3> <p>Instruction-based architectures that interpret calldata as a sequence of byte-level commands benefit from reduced gas usage and smaller bytecode size when parsing instruction streams. A common pattern for reading a single byte from calldata today consists of the following instruction sequence:</p> <ul> <li><code>CALLDATALOAD</code> (3 gas)</li> <li><code>PUSH1</code> (3 gas)</li> <li><code>SHR</code> (3 gas)</li> </ul> <p>This results in a total cost of 9 gas per byte read, excluding additional stack manipulation overhead, and increases deployed bytecode size due to the extra instructions. Replacing this sequence with a single <code>CALLDATALOAD8</code> instruction priced at 3 gas saves 6 gas per byte read and reduces deployed bytecode size by approximately 3 bytes per occurrence. These savings compound in contracts that repeatedly parse byte-oriented calldata or instruction streams.</p> <h3 id="opcode-assignment">Opcode Assignment</h3> <p>While the final opcode values are subject to allocation during review, this proposal suggests placing <code>MLOAD8</code> and <code>CALLDATALOAD8</code> in the <code>0x4X</code> opcode range. The <code>0x5X</code> range, which primarily contains stack, memory, storage, and control flow operations, is largely exhausted. Tentative values of <code>0x4e</code> for <code>MLOAD8</code> and <code>0x4f</code> for <code>CALLDATALOAD8</code> are suggested to group these instructions near existing data access operations while minimizing the risk of opcode collisions. These assignments are intended to facilitate early client prototyping and collision checking and may be adjusted during the standardization process.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces new opcodes and does not modify the semantics of existing instructions. No backwards compatibility issues are introduced beyond those inherent to any opcode-adding hard fork.</p> <h2 id="test-cases">Test Cases</h2> <p>Assume:</p> <ul> <li><code>calldata = 0x0123456789abcdef</code></li> <li><code>memory = 0xfedcba9876543210</code></li> </ul> <table><thead><tr><th>Bytecode</th><th>Description</th><th>Result</th></tr></thead><tbody> <tr><td><code>5f &lt;CALLDATALOAD8&gt;</code></td><td><code>PUSH0; CALLDATALOAD8</code></td><td>pushes <code>0x01</code></td></tr> <tr><td><code>6002 &lt;MLOAD8&gt;</code></td><td><code>PUSH1 0x02; MLOAD8</code></td><td>pushes <code>0xba</code></td></tr> <tr><td><code>&lt;CALLDATALOAD8&gt;</code></td><td>missing stack operand</td><td>exceptional halt</td></tr> <tr><td><code>&lt;MLOAD8&gt;</code></td><td>missing stack operand</td><td>exceptional halt</td></tr> </tbody></table> <h2 id="security-considerations">Security Considerations</h2> <p>No new security considerations are introduced beyond those already known for memory and calldata access.</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-12-30T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status Gajinder Singhhttps://github.com/g11tech https://wg-eips.ritovision.com/8115/

Delay all priority fee credits from transactions to end of block

<h2 id="abstract">Abstract</h2> <p>This EIP defines how to optimize processing of priority fees from <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fee market transactions.</p> <h2 id="motivation">Motivation</h2> <p>Priority fees are credited at the end of each transaction, leading to these complications:</p> <ol> <li> <p><strong>Limited parallelization:</strong> Each transaction writes to the fee recipient account balance.</p> </li> <li> <p><strong>Mempool complexities:</strong> A transaction sender may become solvent only after prior transactions in a block have been processed.</p> </li> <li> <p><strong>Accounting complexities:</strong> The fee recipient gets hundreds of micropayments for what could logically be a single credit.</p> </li> <li> <p><strong>Inaccurate logs:</strong> Proposals to emit logs on ETH transfers either have to omit priority fees, limiting their usefulness due to inaccuracies, or have to emit an extra entry for each individual fee, making them expensive.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="priority-fee-processing">Priority fee processing</h3> <p><a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> priority fees SHALL no longer be credited after each individual transaction. Instead, they SHALL be summed up and credited after all transactions of a block are processed but before <a href="https://wg-eips.ritovision.com/4895/">EIP-4895</a> withdrawals are processed.</p> <h2 id="rationale">Rationale</h2> <p>This EIP is one step towards fully accurate ETH balance logs. Batched crediting of priority fees improves parallel execution of transactions, as a transaction can no longer start with insufficient fees and only become eligible for execution after incremental priority fees have been credited.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The fee recipient now receives priority fees at the end of the block rather than incrementally after each transaction, making it only possible to spend them in the next block. This may require updates to block builder infrastructure and change liquidity requirements for MEV use cases.</p> <h2 id="security-considerations">Security Considerations</h2> <p>No security impact.</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-12-30T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status Gajinder Singhhttps://github.com/g11tech https://wg-eips.ritovision.com/8116/

Replace cumulativeGasUsed with gasUsed in on-chain receipt

<h2 id="abstract">Abstract</h2> <p>This EIP describes how to change the on-chain receipt data to track gas per transaction instead of cumulatively.</p> <h2 id="motivation">Motivation</h2> <p>Currently, on-chain receipts track a <code>cumulativeGasUsed</code> field which contains the running sum of all gas spent for all transactions in the block so far. This has a number of shortcomings:</p> <ol> <li> <p><strong>Inefficient verification:</strong> RPC clients that want to verify individual transaction <code>gasUsed</code> requires computation based on <code>cumulativeGasUsed</code> across consecutive receipts.</p> </li> <li> <p><strong>Limited parallelism:</strong> Receipt contents are stateful, even for transactions accessing mutually exclusive state.</p> </li> </ol> <p>The <code>logIndex</code> field exposed via JSON-RPC is currently also tracking an incremental block level index instead of a per-receipt index, with similar shortcomings.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="receipt-construction"><code>Receipt</code> construction</h3> <p>All receipts emitted after this EIP activates track the individual transaction's <code>gasUsed</code> instead of the incremental <code>cumulativeGasUsed</code> value.</p> <h3 id="json-rpc-api">JSON-RPC API</h3> <p>Within <code>logs</code>, the <code>logIndex</code> field is changed to indicate the log index position in the individual receipt, rather than in the entire block.</p> <h2 id="rationale">Rationale</h2> <p>This EIP is a step towards aligning on-chain data with the RPC data actually being consumed by client applications. Stateful components of receipts (<code>cumulativeGasUsed</code> / <code>logIndex</code>) are replaced with per-transaction equivalents.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Applications using verified <code>gasUsed</code> / <code>cumulativeGasUsed</code> values need to adapt to the new on-chain data semantics.</p> <p>Applications relying on the per block <code>logIndex</code> need adaptation, as <code>logIndex</code> now refers to an index per receipt. Note that this is solely an RPC change. Relative log ordering can be emulated by estimating <code>logIndex</code> as <code>transactionIndex * 4 + logIndex</code> (guaranteed to have same order as before, but absolute index values may be higher than before).</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> 2025-12-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv https://wg-eips.ritovision.com/8117/

A display format for abbreviating consecutive identical hex characters in EVM addresses using run-length encoding for UI and logging.

<h2 id="abstract">Abstract</h2> <p>This ERC proposes a standard presentation layer transformation for Ethereum addresses containing long sequences of identical hexadecimal digits. It defines two representation formats: a Unicode-based format using superscripts for graphical user interfaces (UI), and an ASCII-safe fallback format using bracket notation for logs and terminals. This standard aims to improve human readability and safety verification without altering the underlying address data.</p> <h2 id="motivation">Motivation</h2> <p>As the Ethereum ecosystem matures, addresses with long repeating sequences are becoming increasingly common due to several factors:</p> <p><strong>Vanity Addresses &amp; CREATE2:</strong> Factories and developers frequently generate "vanity" addresses with specific prefixes or suffixes for branding or identification.</p> <p><strong>Gas Optimization (<a href="https://wg-eips.ritovision.com/7939/">EIP-7939</a>):</strong> With proposals like EIP-7939 aiming to reduce gas costs for zero bytes in calldata, there is an economic incentive to deploy contracts at addresses containing large sequences of zeros to optimize cross-contract call costs.</p> <p><strong>Security Risks:</strong> The human eye struggles to distinguish between long sequences of identical characters (e.g., counting 10 zeros vs. 11 zeros). This creates a "homoglyph-like" vulnerability where users may skim over the middle of an address, missing subtle differences in a phishing scam.</p> <p>Current truncation methods (e.g., <code>0x1234...5678</code>) obscure the internal structure of the address. A standardized compression format allows users to verify the magnitude of the repeated sequence (e.g., "exactly 11 zeros") at a glance.</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 compression transformation applies only to the visual representation of the address.</p> <h3 id="1-trigger-condition">1. Trigger Condition</h3> <p>Compression SHOULD be applied if a sequence of identical hexadecimal nibbles has a length $L$, where $L \geq 6$.</p> <h3 id="2-formatting-rules">2. Formatting Rules</h3> <p>The standard defines two modes of display. Implementations must preserve the first character of the repeating sequence to indicate which character is being repeated, followed by a count of the total length of the sequence.</p> <h4 id="mode-a-unicode-display-ui-frontend">Mode A: Unicode Display (UI/Frontend)</h4> <p>Recommended for Wallets, Block Explorers, and Mobile Apps.</p> <p><strong>Syntax:</strong> <code>0x</code> + <code>[repeating_char]</code> + <code>[superscript_count]</code> + <code>[remainder]</code></p> <p><strong>Encoding:</strong> The count integer is converted to Unicode Superscript characters (U+2070 to U+2079).</p> <p><strong>Example:</strong></p> <ul> <li>Raw: <code>0x00000000000000000044...</code> (Eighteen 0s)</li> <li>Display: <code>0x0¹⁸44...</code></li> </ul> <h4 id="mode-b-ascii-fallback-cli-logs">Mode B: ASCII Fallback (CLI/Logs)</h4> <p>Recommended for Developer Consoles, Logs, and Copy-Paste operations.</p> <p><strong>Syntax:</strong> <code>0x</code> + <code>[repeating_char]</code> + <code>{</code> + <code>[count]</code> + <code>}</code> + <code>[remainder]</code></p> <p><strong>Example:</strong></p> <ul> <li>Raw: <code>0x00000000000000000044...</code></li> <li>Display: <code>0x0{18}44...</code></li> </ul> <h3 id="3-case-sensitivity-and-eip-55">3. Case Sensitivity and <a href="https://wg-eips.ritovision.com/55/">EIP-55</a></h3> <p>To preserve the checksum integrity defined in EIP-55 and <a href="https://wg-eips.ritovision.com/1191/">EIP-1191</a>:</p> <ul> <li>The compression MUST strictly match identical ASCII characters.</li> <li>The compression MUST NOT be applied to mixed-case sequences (e.g., <code>aAaA</code> cannot be compressed).</li> <li>All non-compressed characters MUST retain their original casing.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="industry-precedents-alignment">Industry Precedents &amp; Alignment</h3> <p><strong>Regex Alignment (ASCII Mode):</strong> We selected the curly brace syntax <code>Byte{n}</code> (e.g., <code>0{8}</code>) because it aligns with the universal Regular Expression standard for quantification. Developers intuitively understand <code>{n}</code> as "repeat n times."</p> <p><strong>Divergence from IPv6:</strong> Unlike IPv6, which uses <code>::</code> to represent "fill the gap with zeros," EVM vanity addresses rely on the specific count of characters for identity. Therefore, an explicit count (<code>{8}</code>) is safer than an implicit gap (<code>::</code>).</p> <h3 id="superscript-vs-subscript-ui-mode">Superscript vs. Subscript (UI Mode)</h3> <p>While subscript notation (e.g., $H_2O$) implies component count in chemistry, this ERC selects Superscript (<code>0⁸</code>) for the following reasons:</p> <p><strong>Legibility:</strong> Superscripts generally render more clearly on digital displays and do not conflict with text underlines (hyperlinks) or font baselines.</p> <p><strong>Metaphor:</strong> Superscripts serve as a visual metaphor for Scientific Notation, indicating the magnitude or length of the sequence, rather than a mathematical power operation.</p> <h3 id="gas-optimization-context">Gas Optimization Context</h3> <p>With the introduction of logic similar to EIP-7939 (scaling gas costs based on calldata zeros), the ecosystem will see a proliferation of addresses engineered to have maximum zero bytes. A display format that handles these specific addresses gracefully is a necessary proactive measure for user experience.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC is strictly a presentation layer standard.</p> <p><strong>Wallets:</strong> Must strip the compression formatting (convert back to full hex) before signing or broadcasting transactions.</p> <p><strong>Safety:</strong> The characters <code>{</code>, <code>}</code>, and Unicode superscripts are not valid hexadecimal characters. If a user blindly copies a compressed address into a legacy system, the system will reject the input as invalid rather than processing a wrong address. This acts as a fail-safe mechanism.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The following Python implementation demonstrates the logic for both Unicode and ASCII modes, covering full display and truncated variations.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">import</span><span> re</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"> AddressCompressor</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> SUPERSCRIPTS</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><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 class="z-punctuation z-definition z-string"> &#39;</span><span class="z-constant">\u2070</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">1</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-constant">\u00B9</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">2</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-constant">\u00B2</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">3</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-constant">\u00B3</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">4</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-constant">\u2074</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">5</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-constant">\u2075</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">6</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-constant">\u2076</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">7</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-constant">\u2077</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">8</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-constant">\u2078</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">9</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-constant">\u2079</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 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 class="z-variable z-parameter z-function"> address</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>full_address</span><span class="z-keyword"> =</span><span> address</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Remove 0x for processing</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>clean_address</span><span class="z-keyword"> =</span><span> address</span><span>[</span><span class="z-constant">2</span><span>:</span><span>]</span><span class="z-keyword"> if</span><span> address</span><span>.</span><span>startswith</span><span>(</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><span class="z-keyword"> else</span><span> address</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"> _to_superscript</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> number</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span><span class="z-string">Converts an integer to a string of unicode superscripts.</span><span class="z-punctuation z-definition z-string">&quot;&quot;&quot;</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-punctuation z-definition z-string">&quot;</span><span>.</span><span>join</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span class="z-constant">SUPERSCRIPTS</span><span>.</span><span>get</span><span>(</span><span>digit</span><span>,</span><span> digit</span><span>)</span><span class="z-keyword"> for</span><span> digit</span><span class="z-keyword"> in</span><span class="z-support"> str</span><span>(</span><span>number</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-support"> format</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> mode</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">unicode</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-variable z-parameter z-function"> truncate</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"> Modes: &#39;unicode&#39; (0⁸) or &#39;ascii&#39; (0{8})</span></span> <span class="giallo-l"><span class="z-string"> Truncate: If True, keeps start/end context only.</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 class="z-storage z-type"> def</span><span class="z-entity z-name"> replacer</span><span>(</span><span class="z-variable z-parameter z-function">match</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> seq</span><span class="z-keyword"> =</span><span> match</span><span>.</span><span>group</span><span>(</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"><span> length</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span>seq</span><span>)</span></span> <span class="giallo-l"><span> char</span><span class="z-keyword"> =</span><span> seq</span><span>[</span><span class="z-constant">0</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"> Trigger threshold &gt;= 6</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> length</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 6</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> seq</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> mode</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">unicode</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span></span> <span class="giallo-l"><span> count_str</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>_to_superscript</span><span>(</span><span>length</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-storage z-type"> f</span><span class="z-string">&quot;</span><span class="z-constant">{</span><span>char</span><span class="z-constant">}</span><span class="z-constant">{</span><span>count_str</span><span class="z-constant">}</span><span class="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"> f</span><span class="z-string">&quot;</span><span class="z-constant">{</span><span>char</span><span class="z-constant">}</span><span class="z-constant">{{</span><span class="z-constant">{</span><span>length</span><span class="z-constant">}</span><span class="z-constant">}}</span><span class="z-string">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Find sequences of identical characters</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> (?:(\w)\1+) matches a char followed by itself one or more times</span></span> <span class="giallo-l"><span> compressed_body</span><span class="z-keyword"> =</span><span> re</span><span>.</span><span>sub</span><span>(</span><span class="z-storage z-type">r</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-support">(</span><span class="z-support">.</span><span class="z-support">)</span><span class="z-entity z-name z-tag">\1</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> replacer</span><span>,</span><span class="z-variable z-language"> self</span><span>.</span><span>clean_address</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> prefix</span><span class="z-keyword"> =</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 class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> truncate</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-storage z-type"> f</span><span class="z-string">&quot;</span><span class="z-constant">{</span><span>prefix</span><span class="z-constant">}</span><span class="z-constant">{</span><span>compressed_body</span><span class="z-constant">}</span><span class="z-string">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Simple Logic for Truncation with Compression</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> If the compression happened at the start (common for vanity)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-variable z-language"> self</span><span>.</span><span>clean_address</span><span>.</span><span>startswith</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0000000</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-comment"> #</span><span class="z-comment"> Find where the first compression block ends in the visual string</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> This is a simplified example. Production logic needs to handle</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> multiple compression blocks carefully.</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-storage z-type"> f</span><span class="z-string">&quot;</span><span class="z-constant">{</span><span>prefix</span><span class="z-constant">}</span><span class="z-constant">{</span><span>compressed_body</span><span>[</span><span>:</span><span class="z-constant">5</span><span>]</span><span class="z-constant">}</span><span class="z-string">...</span><span class="z-constant">{</span><span>compressed_body</span><span>[</span><span class="z-keyword">-</span><span class="z-constant">4</span><span>:</span><span>]</span><span class="z-constant">}</span><span class="z-string">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-storage z-type"> f</span><span class="z-string">&quot;</span><span class="z-constant">{</span><span>prefix</span><span class="z-constant">}</span><span class="z-constant">{</span><span>compressed_body</span><span>[</span><span>:</span><span class="z-constant">6</span><span>]</span><span class="z-constant">}</span><span class="z-string">...</span><span class="z-constant">{</span><span>compressed_body</span><span>[</span><span class="z-keyword">-</span><span class="z-constant">4</span><span>:</span><span>]</span><span class="z-constant">}</span><span class="z-string">&quot;</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 Cases ---</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> 1. Standard Vanity (7 zeros)</span></span> <span class="giallo-l"><span>addr1</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000095a03eb9fa26c0d71136a8daa8ea239ce</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>c1</span><span class="z-keyword"> =</span><span> AddressCompressor</span><span>(</span><span>addr1</span><span>)</span></span> <span class="giallo-l"><span class="z-support">print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Unicode Full: </span><span class="z-constant">{</span><span>c1</span><span>.</span><span>format</span><span>(</span><span class="z-variable">mode</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">unicode</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Output: 0x0⁷95a03eb9fa26c0d71136a8daa8ea239ce</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support">print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">ASCII Full: </span><span class="z-constant">{</span><span>c1</span><span>.</span><span>format</span><span>(</span><span class="z-variable">mode</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">ascii</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Output: 0x0{7}95a03eb9fa26c0d71136a8daa8ea239ce</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> 2. Uniswap V4 Style (11 zeros)</span></span> <span class="giallo-l"><span>addr2</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000004444c5dc75cB358380D2e3dE08A90</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>c2</span><span class="z-keyword"> =</span><span> AddressCompressor</span><span>(</span><span>addr2</span><span>)</span></span> <span class="giallo-l"><span class="z-support">print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Unicode Smart: </span><span class="z-constant">{</span><span>c2</span><span>.</span><span>format</span><span>(</span><span class="z-variable">mode</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">unicode</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-variable"> truncate</span><span class="z-keyword">=</span><span class="z-constant">True</span><span>)</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Output: 0x0¹¹44...8A90</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support">print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">ASCII Smart: </span><span class="z-constant">{</span><span>c2</span><span>.</span><span>format</span><span>(</span><span class="z-variable">mode</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">ascii</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-variable"> truncate</span><span class="z-keyword">=</span><span class="z-constant">True</span><span>)</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Output: 0x0{11}44...8A90</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> 3. Precompile (39 zeros)</span></span> <span class="giallo-l"><span>addr3</span><span class="z-keyword"> =</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 class="giallo-l"><span>c3</span><span class="z-keyword"> =</span><span> AddressCompressor</span><span>(</span><span>addr3</span><span>)</span></span> <span class="giallo-l"><span class="z-support">print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Precompile UI: </span><span class="z-constant">{</span><span>c3</span><span>.</span><span>format</span><span>(</span><span class="z-variable">mode</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">unicode</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Output: 0x0³⁹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"> 4. Mixed Case (Safety Check - Should NOT compress)</span></span> <span class="giallo-l"><span>addr4</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000aAaAaAaA1234</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> aAaA... is mixed case</span></span> <span class="giallo-l"><span>c4</span><span class="z-keyword"> =</span><span> AddressCompressor</span><span>(</span><span>addr4</span><span>)</span></span> <span class="giallo-l"><span class="z-support">print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Safety Check: </span><span class="z-constant">{</span><span>c4</span><span>.</span><span>format</span><span>(</span><span class="z-variable">mode</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">ascii</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Output: 0x0{7}aAaAaAaA1234 (Only the zeros are compressed)</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p><strong>Homoglyph Attacks:</strong> While this standard aims to reduce visual confusion, developers must ensure that the font used for superscripts is distinct enough that <code>0⁷</code> is not misread as <code>07</code>.</p> <p><strong>Copy-Paste Validation:</strong> Applications accepting address input MUST prioritize standard hexadecimal parsing. If an input contains <code>{}</code> or superscripts, the application should strictly reject the input or explicitly offer to decompress it, rather than attempting to hash invalid characters.</p> <p><strong>Preservation of Entropy:</strong> This standard does not compress distinct characters. It only compresses low-entropy sequences (repeats), ensuring that the visually distinct part of the address (the high-entropy suffix) remains prominent.</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-12-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Yash Saraswathttps://github.com/0xpanicError https://wg-eips.ritovision.com/8113/

Series Accounting method for collecting performance fees in ERC-7540 type vaults.

<h2 id="abstract">Abstract</h2> <p>The following standard formalizes the Series Accounting Method for <a href="https://wg-eips.ritovision.com/7540/">ERC-7540</a> and <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> type vaults, enabling them to collect performance fees on yields without introducing the free-rider problem.</p> <p>It defines the necessary architectural specification for implementing Series Accounting by requiring an independent Series to track each batch of claimed deposit requests within the vault with its unique <code>totalAssets</code>, <code>totalShares</code>, <code>sharesOf</code> and <code>highwaterMark</code> values.</p> <h2 id="motivation">Motivation</h2> <p>Current vault implementations typically implement a Highwater Mark based on the highest recorded price-per-share (the ratio of total assets to total shares of the vault) to ensure performance fees are not collected for recovering losses. But relying on a single vault-wide highwater mark introduces the free-rider problem.</p> <p>A free-rider occurs when a user's deposit is claimed at a price-per-share below the vault's current highwater mark. When the vault later reaches a new highwater mark, the user doesn’t pay a performance fee on all yield accrued between their initial entry price and the new highwater mark, effectively diminishing returns for existing users.</p> <p>This standard implements the series accounting method where all batches of deposit requests are claimed in a series which maintains a unique highwater mark for those deposits. This allows for the protocol to accurately account for performance fees across all user deposits fairly. The “free-ride” problem is prevalent in vaults that derive their yields from RWAs. Reflecting performance from off-chain assets like hedge or liquid fund portfolios can vary drastically from each rebalancing/settlement cycle.</p> <p>This can cause large fluctuations in exchange rates (price-per-share) of a vault resulting in inaccurate performance fee collection from users. Series Accounting is a very common and standard method of accounting portfolios in traditional funds but lacks any formal implementation in DeFi.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <p>The general architecture of a vault remains the same. This standard can be used with both rebalancing type and async type vaults. For ERC-4626 type vaults which rebalances price-per-share periodically, all deposits made within a rebalancing period can be considered as a batch (all "settled" with same price-per-share). For ERC-7540 async type vaults, the user flows remain the same:</p> <ul> <li>users requiring to submit a request to enter or exit the vault</li> <li>vault implementing a method to move request from “pending” to “claimable” state</li> </ul> <p>However, the structure in which <code>assets</code> and <code>shares</code> are maintained in the vault is altered to accommodate for series accounting. Traditionally, the vault will store a global value for <code>totalAssets</code> and <code>totalShares</code>, but to follow this specification, the following state variables MUST be maintained individually for each series:</p> <ul> <li>total assets</li> <li>total shares</li> <li>shares of users</li> <li>list of users</li> <li>highwater mark</li> </ul> <h3 id="definitions">Definitions</h3> <ul> <li>series: a series is like a sub-vault where a set of all deposit requests that are claimed together are accounted for.</li> <li>price-per-share: ratio of total assets to total shares in a series.</li> <li>highwater mark: the highest price-per-share (also referred as exchange price) of a given series.</li> <li>oracle: the entity responsible for setting the price-per-share of the vault.</li> <li>settle: the act of rebalancing the vault or claiming the deposit requests performed by the oracle in a series id, determined by the logic specified in this standard.</li> <li>lead series: each vault has a default series called the lead series where the first set of deposit requests will be claimed.</li> <li>outstanding series: a series apart from the lead series which contains user shares.</li> <li>consolidation: the process where all user shares are transferred from outstanding series to the lead series.</li> <li>consolidated series: an empty series from which user shares were transferred during consolidation.</li> </ul> <h4 id="deposit-flow">Deposit Flow</h4> <p>For ERC-4626 type vaults, when the <code>oracle</code> provides the price-per-share for rebalancing, all deposits that will follow in that rebalancing period will be considered as a batch and MUST <code>settle</code> in the same series id. For ERC-7540 type vaults, when the <code>oracle</code> provides the price-per-share at which the deposits are to be claimed, all deposits MUST <code>settle</code> in the same series id. The standard defines in which series id the deposits SHOULD be <code>settled</code> as follows:</p> <ul> <li><strong>if the current highwater mark of the lead series is greater than the price-per-share of the lead series</strong> <ul> <li>MUST create a new series with a unique series ID.</li> <li>MUST settle all pending deposit requests in this new series.</li> </ul> </li> <li><strong>else (if the highwater mark is less than or equal to the price-per-share):</strong> <ul> <li>MUST settle all pending deposit requests in the lead series.</li> <li>If the number of outstanding series is greater than zero: <ul> <li>MUST consolidate all outstanding series into the lead series.</li> </ul> </li> </ul> </li> </ul> <h4 id="redeem-flow">Redeem Flow</h4> <p><a href="https://wg-eips.ritovision.com/8113/">ERC-8113</a> vaults MUST allow users to redeem (or request a redeem) by providing <code>assets</code> instead of <code>shares</code> as input.</p> <p>The vault is RECOMMENDED to store the proportion of total <code>assets</code> for that user in the redeem request.</p> <p>When the request is to be settled, the redemption MAY follow the FIFO method. At the time of settling a redeem request for a given price-per-share, the amount is to be redeemed from the lead series first. If the total user assets in lead series is not sufficient to fulfill the request, the remaining amount should be redeemed from the outstanding series with the lowest series Id. This process must be continued until the entire request is fulfilled. The portion of redemption that takes place in a given series is called a Redeem Slice.</p> <h2 id="rationale">Rationale</h2> <h3 id="using-assets-instead-of-shares-for-redemption">Using “assets” instead of “shares” for redemption</h3> <p>We cannot use <code>shares</code> to specify the amount a user wishes to redeem because shares are non-fungible across series. A user who can have assets across multiple series cannot specify a single share value in the request to represent all user assets.</p> <p>If requests are made for a given series, <code>shares</code> can be used but then:</p> <ul> <li>user must make multiple requests if they wish to redeem more than what they own in a given series</li> <li>if the series gets consolidated (in case of async vaults), the redemption may take place from lead series but price-per-share information must be stored which makes implementation very complicated and can introduce security risks</li> </ul> <p>The best solution presented to be users specifying <code>assets</code> instead of <code>shares</code> when making a redeem request. While processing the request, the implementation can store the proportion of total user assets across all series that they wish to redeem.</p> <p>This solves the issues of non-fungible shares and accounting across multiple series.</p> <h3 id="consolidating-series">Consolidating Series</h3> <p>Each new set of deposit requests may require its own series. This can cause the number of outstanding series to increase in number drastically if vault periodically has periods of poor performance.</p> <p>This can cause following problems:</p> <ul> <li>having many outstanding series may result in any implementation processing them to exceed the block gas limit eventually which can render the vault unusable.</li> <li>traditional fund managers that expect to fetch vault data for their accounting reports are not pleased with having bloated Net Asset Vaule (NAV)/Assets Under Management (AUM) sheets with multiple series.</li> </ul> <p>After the lead series reaches a new highwater mark, all subsequent outstanding series also reach new highwater marks. When this happens, each existing user has paid their fair share of performance and there no longer exists a need to maintain these deposits separately.</p> <p>Hence, consolidating all outstanding series during this point can help a vault never exceed block gas limit and also keeps accounting reports for traditional managers clean and concise.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Note that ERC-8113 is not backwards compatible with ERC-7540 or ERC-4626.</p> <p>The incompatibilties with ERC-4626 are as follows:</p> <ul> <li><code>totalAssets</code> would require additional input <code>seriesId</code></li> <li><code>convertToShares</code> would require additional input <code>seriesId</code></li> <li><code>convertToAssets</code> would require additional input <code>seriesId</code></li> <li><code>redeem</code> would need to replace input <code>shares</code> with <code>assets</code></li> </ul> <p>The incompatibilities with ERC-7540 are as follows:</p> <ul> <li><code>requestRedeem</code> would need to replace input <code>shares</code> with <code>assets</code></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>The fee calculation for yield bearing vaults can be complex as there can be multiple fixed and variable charges applied before performance fee. This can cause mismatch from expected and realised fee collections.</p> <p>Protocols must be careful and thoroughly analyze the accounting resulting from their implementations to ensure they match expectations, and should provide clear documentation of all fee calculations.</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-12-23T00:00:00+00:00 2026-02-11T14:48:25+00:00 William Morrisshttps://github.com/wjmelements https://wg-eips.ritovision.com/8111/

Binding y-parity compresses ECDSA signatures

<h2 id="abstract">Abstract</h2> <p>Recoverable ECDSA signatures can flip <code>s</code> and <code>v</code> while remaining valid, so they can be compressed to 64 bytes by restricting <code>v</code>.</p> <h2 id="motivation">Motivation</h2> <p>ECDSA signatures are often encoded with three parameters: <code>v</code>, <code>r</code>, and <code>s</code>. In the Solidity ABI encoding, this is 96 bytes. By eliminating the degree of freedom, <code>v</code>, the encoded size of a recoverable signature can be reduced to 64 bytes. Additionally, such signatures are not malleable.</p> <h2 id="specification">Specification</h2> <p>Smart contracts accepting bound signatures MUST supply <code>27</code> for <code>v</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">address</span><span> signer </span><span class="z-keyword">=</span><span class="z-support"> ecrecover</span><span>(</span><span>digest</span><span>,</span><span class="z-constant"> 27</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>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></code></pre> <p>ECDSA signatures MUST be bound before supplied to such contracts.</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"> SECP256K1_N</span><span class="z-keyword">:</span><span class="z-support"> bigint</span><span class="z-keyword"> =</span><span class="z-constant"> 0xfffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141</span><span class="z-storage z-type">n</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"> bind</span><span>(</span><span class="z-variable">sig</span><span class="z-keyword">:</span><span class="z-entity z-name"> Signature</span><span>,</span><span class="z-variable"> v</span><span class="z-keyword">:</span><span class="z-constant"> 27</span><span class="z-keyword"> |</span><span class="z-constant"> 28</span><span class="z-keyword"> =</span><span class="z-constant"> 27</span><span>)</span><span class="z-keyword">:</span><span class="z-entity z-name"> Signature</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-other">sig</span><span>.</span><span class="z-variable z-other">v</span><span class="z-keyword"> ===</span><span class="z-variable z-other"> v</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> sig</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"> s</span><span class="z-keyword"> =</span><span class="z-variable z-other z-constant"> SECP256K1_N</span><span class="z-keyword"> -</span><span class="z-variable z-other"> sig</span><span>.</span><span class="z-variable z-other">s</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-keyword"> new</span><span class="z-entity z-name"> Signature</span><span>(</span><span class="z-variable z-other">sig</span><span>.</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other"> s</span><span>,</span><span class="z-variable z-other"> v</span><span>)</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Another signature compression approach, <a href="https://wg-eips.ritovision.com/2098/">ERC-2098</a>, stores the y-parity bit in the most-significant bit of the low <code>s</code>. Bound signatures are preferable because they are valid inputs to the <code>ecrecover</code> precompile. They require less gas because they do not need to be unpacked by the smart contract.</p> <p><code>27</code> was chosen over <code>28</code> to make the y-parity falsy.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Bound signatures are compatible with <code>ecrecover</code> if 27 is supplied for the <code>v</code> parameter. They cannot be used for transaction signatures because they permit high <code>s</code>, in violation of <a href="https://wg-eips.ritovision.com/2/">EIP-2</a>.</p> <h2 id="test-cases">Test Cases</h2> <table><thead><tr><th>Signer</th><th>Digest</th><th><code>r</code></th><th><code>s</code></th></tr></thead><tbody> <tr><td><code>0x4a6f6B9fF1fc974096f9063a45Fd12bD5B928AD1</code></td><td><code>0xb0922c37cafd247fe3ada4eb1d1e3735b7d2837437c1178e9af120d535214270</code></td><td><code>0xdb7f75635124c807ec1f8b03e34cd76b633dc3a189e3c85fc5aee7e7d71df38c</code></td><td><code>0x5f1e6c6edf21cacfc2acba2815b253b9048b894eec5aaf70343389bb596c48bc</code></td></tr> <tr><td><code>0x4a6f6B9fF1fc974096f9063a45Fd12bD5B928AD1</code></td><td><code>0xd92ff06caae7253883627416a425414d79e9003b91d6208add30e73735ef13c3</code></td><td><code>0xaa40efd534ac7f96b85babd7df9228fa131e8523115ca1ebc025698c37f3867d</code></td><td><code>0xa4b8d3c650fe62e46a563aed681bfdd44d50452fa7712bd139f2bfba3aed59c9</code></td></tr> <tr><td><code>0x6B93E3bB9C0780C0f9042346Ffc379530a5882c1</code></td><td><code>0xfa75eba87f076cf22489da7c53a651bb3869473f78d09d4814afb7ab2d54ed45</code></td><td><code>0xaf4a877600ab6d14ebac626830cf1063d624487932b3cc73a7cd98ae7fbf337f</code></td><td><code>0xbc41d29acfcd3a1e7b5cb2dde1b85fe8882739312639b5f16d476a87584c040f</code></td></tr> </tbody></table> <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.30</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"> BoundSignatures</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> recover</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> digest</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"> 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 class="z-variable"> signer</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> signer </span><span class="z-keyword">=</span><span class="z-support"> ecrecover</span><span>(</span><span>digest</span><span>,</span><span class="z-constant"> 27</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>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> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Bound signatures are recoverable and not malleable.</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-12-21T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Mudgehttps://github.com/mudgen https://wg-eips.ritovision.com/8109/

A simplified diamond architecture for modular smart contract systems.

<h2 id="abstract">Abstract</h2> <p>A diamond is a proxy contract that <code>delegatecall</code>s to multiple implementation contracts called facets.</p> <p><img src="https://wg-eips.ritovision.com/8109/./assets/basic-diamond-diagram.svg" alt="Diagram showing how a diamond contract works" /></p> <p>Diamond contracts were originally standardized by <a href="https://wg-eips.ritovision.com/2535/">ERC-2535</a>. This standard refines that specification by simplifying terminology, reducing the implementation complexity of introspection functions, and standardizing specific events.</p> <p>This standard preserves the full capabilities of diamond contracts while reducing complexity. It also specifies an optional upgrade path for existing ERC-2535 diamonds.</p> <h2 id="motivation">Motivation</h2> <h3 id="motivation-for-diamond-contracts">Motivation for Diamond Contracts</h3> <p><img alt="Obligatory diamond" src="./assets/diamond.svg" width="17%" align="right">Through a single contract address, a diamond provides functionality from multiple implementation contracts (facets). Each facet is independent, yet facets can share internal functions and storage. This architecture allows large smart-contract systems to be composed from separate facets and presented as a single contract, simplifying deployment, testing, and integration with other contracts, off-chain software, and user interfaces.</p> <p>By decomposing large smart contracts into facets, diamonds can reduce complexity and make systems easier to reason about. Distinct areas of functionality can be isolated, organized, tested, and managed independently.</p> <p>Diamonds combine the single-address convenience of a monolithic contract with the modular flexibility of distinct, integrated contracts.</p> <p>This architecture is well suited to <strong>immutable</strong> smart-contract systems, where all functionality is composed from multiple facets at deployment time and permanently fixed thereafter.</p> <p>For upgradeable systems, diamonds enable incremental development: new functionality can be added, and existing functionality modified, without redeploying unaffected facets.</p> <p>Additional motivation and background for diamond-based smart-contract systems can be found in <a href="https://wg-eips.ritovision.com/1538/">ERC-1538</a> and <a href="https://wg-eips.ritovision.com/2535/">ERC-2535</a>.</p> <h3 id="motivation-for-this-standard">Motivation for this Standard</h3> <p>Unlike monolithic contracts, a diamond's external functions are commonly determined by runtime routing (selector → facet mapping) rather than being wholly represented in the diamond's source code or bytecode. To accurately determine or display the full set of functionality a diamond has, tooling must rely on standardized introspection functions and events.</p> <p>Block explorers, indexers, development tools, and user interfaces need a standard way to inspect which functions and facets a diamond possesses. Additionally, tooling can be built to reconstruct and display the full development or upgrade history of diamond contracts using event logs.</p> <p>ERC-2535 standardized introspection functions and events. <a href="https://wg-eips.ritovision.com/8109/">ERC-8109</a> re-standardizes these to make diamond contracts easier to implement and easier to understand.</p> <p>ERC-8109 improves upon ERC-2535 Diamonds in the following ways:</p> <ol> <li>Simplified terminology.</li> <li>Fewer and simpler to implement introspection functions.</li> <li>Replaces a single monolithic event, with per-function events. This makes it easier to implement a variety of functions that add, replace and remove functions in a diamond. It also makes it easier for tools to search for and process events.</li> </ol> <h2 id="specification">Specification</h2> <h3 id="terms">Terms</h3> <ol> <li>A <strong>diamond</strong> is a smart contract that routes external function calls to one or more implementation contracts, referred to as facets. A diamond is stateful: all persistent data is stored in the diamond’s contract storage. A diamond implements the requirements in the <a href="https://wg-eips.ritovision.com/8109/#implementation-requirements">Implementation Requirements</a> section.</li> <li>A <strong>facet</strong> is a smart contract that defines one or more external functions. A facet is deployed independently, and one or more of its functions are added to one or more diamonds. A facet’s functions are executed in the diamond’s context via <code>delegatecall</code>, so reads/writes affect the diamond’s storage. The term facet is derived from the diamond industry, referring to a flat surface of a diamond.</li> <li>An <strong>introspection function</strong> is a function that returns information about the facets and functions used by a diamond.</li> <li>For the purposes of this specification, a <strong>mapping</strong> refers to a conceptual association between two items and does not refer to a specific implementation.</li> </ol> <h3 id="diamond-diagram">Diamond Diagram</h3> <p>This diagram shows the structure of a diamond.</p> <p>It shows that a diamond has a mapping from function to facet and that facets can access the storage inside a diamond.</p> <p><img src="https://wg-eips.ritovision.com/8109/./assets/functionFacetMapping.svg" alt="Diagram showing structure of a diamond" /></p> <h3 id="fallback">Fallback</h3> <p>When an external function is called on a diamond, its fallback function is executed. The fallback function determines which facet to call based on the first four bytes of the calldata (known as the function selector) and executes the function from the facet using <code>delegatecall</code>.</p> <p>A diamond’s fallback function and <code>delegatecall</code> enable a diamond to execute a facet’s function as if it was implemented by the diamond itself. The <code>msg.sender</code> and <code>msg.value</code> values do not change and only the diamond’s storage is read and written to.</p> <p>Here is an example of how a diamond’s fallback function might be implemented:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> FunctionNotFound</span><span>(</span><span class="z-support">bytes4</span><span> _selector</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Executes function call on facet using `delegatecall`.</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Returns function call return data or revert data.</span></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-comment"> //</span><span class="z-comment"> Get facet address from function selector</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> facet </span><span class="z-keyword">=</span><span> selectorToFacet</span><span>[</span><span class="z-variable z-language">msg</span><span>.</span><span>sig</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>facet </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"> revert</span><span class="z-entity z-name"> FunctionNotFound</span><span>(</span><span class="z-variable z-language">msg</span><span>.</span><span>sig</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"> Execute external function on facet using `delegatecall` and return any value.</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Copy function selector and any arguments from calldata to memory.</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-comment"> //</span><span class="z-comment"> Execute function call using the facet.</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> facet</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-comment"> //</span><span class="z-comment"> Copy all return data from the previous call into memory.</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 class="z-comment"> //</span><span class="z-comment"> Return any return value or error back to the caller.</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 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></span> <span class="giallo-l"><span> default </span><span>{</span><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></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="function-not-found">Function Not Found</h4> <p>If the fallback function cannot find a facet for a function selector, and there is no default function or other mechanism to handle the call, the fallback MUST revert with the error <code>FunctionNotFound(bytes4 _selector)</code>.</p> <h3 id="events">Events</h3> <h4 id="adding-replacing-removing-functions">Adding/Replacing/Removing Functions</h4> <p>These events are REQUIRED.</p> <p>For each function selector that is added, replaced, or removed, the corresponding event MUST be emitted.</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"> Emitted when a function is added to a diamond.</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"> _selector</span><span class="z-comment"> The function selector being 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"> _facet</span><span class="z-comment"> The facet address that will handle calls to `_selector`.</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"> DiamondFunctionAdded</span><span>(</span><span class="z-support">bytes4</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _selector</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _facet</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 changing the facet that will handle calls to a function.</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"> _selector</span><span class="z-comment"> The function selector being affected.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _oldFacet</span><span class="z-comment"> The facet address previously responsible for `_selector`.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _newFacet</span><span class="z-comment"> The facet address that will now handle calls to `_selector`.</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"> DiamondFunctionReplaced</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"> _selector</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"> _oldFacet</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"> _newFacet</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 a function is removed from a diamond.</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"> _selector</span><span class="z-comment"> The function selector being 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"> _oldFacet</span><span class="z-comment"> The facet address that previously handled `_selector`.</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"> DiamondFunctionRemoved</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"> _selector</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"> _oldFacet</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h4 id="recording-non-fallback-delegatecalls">Recording Non-Fallback <code>delegatecall</code>s</h4> <p>This event is OPTIONAL.</p> <p>This event can be used to record <code>delegatecall</code>s made by a diamond.</p> <p>This event MUST NOT be emitted for <code>delegatecall</code>s made by a diamond’s fallback function when routing calls to facets. It is only intended for <code>delegatecall</code>s made by functions in facets or a diamond’s constructor.</p> <p>This event enables tracking of changes to a diamond’s contract storage caused by <code>delegatecall</code> execution.</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"> Emitted when a diamond&#39;s constructor function or function from a</span></span> <span class="giallo-l"><span class="z-comment">* facet makes a `delegatecall`. </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"> _delegate</span><span class="z-comment"> The contract that was the target of the `delegatecall`.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _delegateCalldata</span><span class="z-comment"> The function call, including function selector and </span></span> <span class="giallo-l"><span class="z-comment">* any arguments.</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"> DiamondDelegateCall</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">bytes</span><span class="z-variable"> _delegateCalldata</span><span>)</span><span>;</span></span></code></pre><h4 id="diamond-metadata">Diamond Metadata</h4> <p>This event is OPTIONAL.</p> <p>This event can be used to record versioning or other information about diamonds.</p> <p>It can be used to record information about diamond upgrades.</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"> Emitted to record information about a diamond.</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 records any arbitrary metadata. </span></span> <span class="giallo-l"><span class="z-comment">* The format of `_tag` and `_data` are not specified by the </span></span> <span class="giallo-l"><span class="z-comment">* 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-storage z-type">@param</span><span class="z-variable z-other"> _tag</span><span class="z-comment"> Arbitrary metadata, such as a release version.</span></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"> Arbitrary metadata.</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"> DiamondMetadata</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _tag</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> _data</span><span>)</span><span>;</span></span></code></pre><h3 id="inspecting-diamonds">Inspecting Diamonds</h3> <p>Diamond introspection functions return information about what functions and facets are used in a diamond.</p> <p>These functions MUST be implemented and are required by the standard:</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"> @notice</span><span class="z-comment"> Gets the facet that handles the given selector.</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"> If facet is not found return 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"> _functionSelector</span><span class="z-comment"> The function selector.</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"> facet address associated with the function selector.</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"> facetAddress</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable z-parameter z-function"> _functionSelector</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-storage z-type">struct</span><span class="z-entity z-name"> FunctionFacetPair</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> facet</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"> Returns an array of all function selectors and their </span></span> <span class="giallo-l"><span class="z-comment">* corresponding facet addresses.</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"> Iterates through the diamond&#39;s stored selectors and pairs</span></span> <span class="giallo-l"><span class="z-comment">* each with its facet.</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"> pairs</span><span class="z-comment"> An array of `FunctionFacetPair` structs, each containing</span></span> <span class="giallo-l"><span class="z-comment">* a selector and its facet 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"> functionFacetPairs</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-storage z-type">FunctionFacetPair</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> pairs</span><span>)</span><span>;</span></span></code></pre> <p>The essence of a diamond is its <code>function -&gt; facet</code> mapping. <code>functionFacetPairs()</code> returns that mapping as an array of <code>(selector, facet)</code> pairs.</p> <p>These functions were chosen because they provide all necessary facet and function data about a diamond. They are very simple to implement and are computationally efficient.</p> <p>Block explorers, GUIs, tests, and other tools may rely on their presence.</p> <p>A reference implementation exists for these introspection functions here: <a href="https://wg-eips.ritovision.com/8109/./assets/DiamondInspectFacet.sol">DiamondInspectFacet.sol</a></p> <p>Other introspection functions may be added to a diamond. The above two functions are the only ones required by this standard.</p> <h3 id="implementation-requirements">Implementation Requirements</h3> <p>A diamond MUST implement the following:</p> <ol> <li><strong>Diamond Structure</strong> <ul> <li>A diamond MUST implement a <code>fallback()</code> function.</li> </ul> </li> <li><strong>Function Association</strong> <ul> <li>A diamond MUST associate function selectors with facet addresses.</li> </ul> </li> <li><strong>Function Execution</strong> <ul> <li>When an external function is called on a diamond: <ul> <li>The diamond’s fallback function is executed.</li> <li>The fallback function MUST find the facet associated with the function selector.</li> <li>The fallback function MUST execute the function on the facet using <code>delegatecall</code>.</li> <li>If no facet is associated with the function selector, the diamond MAY execute a default function or apply another handling mechanism.</li> <li>If no facet, default function, or other handling mechanism exists, execution MUST revert with the error <code>FunctionNotFound(bytes4 _selector)</code>.</li> </ul> </li> </ul> </li> <li><strong>Events</strong> <ul> <li>The following events MUST be emitted: <ul> <li><code>DiamondFunctionAdded</code> — when a function is added to a diamond.</li> <li><code>DiamondFunctionReplaced</code> — when a function is replaced in a diamond.</li> <li><code>DiamondFunctionRemoved</code> — when a function is removed from a diamond.</li> </ul> </li> </ul> </li> <li><strong>Introspection</strong> <ul> <li>A diamond MUST implement the following introspection functions: <ul> <li><code>facetAddress(bytes4 _functionSelector)</code></li> <li><code>functionFacetPairs()</code></li> </ul> </li> </ul> </li> </ol> <h3 id="receive-function"><code>receive()</code> function</h3> <p>A diamond MAY have a <code>receive()</code> function.</p> <h3 id="immutable-functions">Immutable Functions</h3> <p>Definition:</p> <blockquote> <p>An immutable function is an external or public function defined directly in a diamond contract, not in a facet.<br /> This definition does not apply to a diamond's constructor or the special <code>fallback()</code> and <code>receive()</code> functions.</p> </blockquote> <p>A diamond can have zero or more immutable functions.</p> <p>A diamond with immutable functions has the following additional requirements that MUST be followed:</p> <ol> <li>The <code>DiamondFunctionAdded</code> event MUST be emitted for each immutable function.</li> <li>Immutable functions MUST be returned by the introspection functions <code>facetAddress(bytes4 _functionSelector)</code> and <code>functionFacetPairs()</code>, where the facet address is the diamond’s own address.</li> <li>Any upgrade function MUST revert on an attempt to replace or remove an immutable function.</li> </ol> <h2 id="rationale">Rationale</h2> <p>This standard provides standard events and introspection functions so that GUIs, block explorers, command line programs, and other tools and software can detect and interoperate with diamond contracts.</p> <p>Software can retrieve function selectors and facet addresses from a diamond in order to use and show what functions a diamond has. Function selectors and facet addresses, combined with contract ABIs and verified source code, provide sufficient information for tooling and user interfaces.</p> <h3 id="erc-8109-diamonds-vs-erc-2535-diamonds">ERC-8109 Diamonds vs ERC-2535 Diamonds</h3> <p>This standard is a simplification and refinement of ERC-2535 Diamonds.</p> <p>A diamond compliant with ERC-8109 is NOT required to implement ERC-2535.</p> <p>Here are changes in ERC-8109 Diamonds:</p> <ul> <li>Simplified terminology.</li> <li>Simplified introspection functions.</li> <li>Standardized events that are simpler to use and consume.</li> <li>Optional upgrade path for existing ERC-2535 diamonds.</li> </ul> <h3 id="diamond-upgrades">Diamond Upgrades</h3> <p>This standard does not specify an upgrade function.</p> <p>This means several things:</p> <h4 id="1-diamonds-can-be-immutable">1. Diamonds Can Be Immutable</h4> <p>A Diamond does not have to have an upgrade function.</p> <ul> <li> <p>A diamond can be fully constructed within its constructor function without adding any upgrade function, making it immutable upon deployment.</p> </li> <li> <p>A large immutable diamond can be built using well organized facets.</p> </li> <li> <p>A diamond can initially be upgradeable, and later made immutable by removing its upgrade function.</p> </li> </ul> <h4 id="2-other-standards-can-build-on-erc-8109">2. Other Standards Can Build on ERC-8109</h4> <p>Other standards can build on ERC-8109 by specifying an upgrade function(s), while remaining compliant with this standard.</p> <h4 id="3-you-can-create-your-own-upgrade-functions">3. You Can Create Your Own Upgrade Functions</h4> <p>You can design and create your own upgrade functions and remain compliant with this standard. All that is required is that you emit the appropriate add/replace/remove required events specified in the <a href="https://wg-eips.ritovision.com/8109/#events">events section</a>, and that the introspection functions defined in the <a href="https://wg-eips.ritovision.com/8109/#inspecting-diamonds">Inspecting Diamonds section</a> continue to accurately return function and facet information.</p> <h3 id="gas-considerations">Gas Considerations</h3> <p>Routing calls via <code>delegatecall</code> introduces a small amount of gas overhead. In practice, this cost is mitigated by several architectural and tooling advantages enabled by diamonds:</p> <ol> <li> <p><strong>Optional, gas-optimized functionality</strong><br /> By structuring functionality across multiple facets, diamonds make it straightforward to include specialized, gas-optimized features without increasing the complexity of core logic.<br /> For example, an <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> diamond may implement batch transfer functions in a dedicated facet, improving both gas efficiency and usability while keeping the base ERC-721 implementation simple and well-scoped.</p> </li> <li> <p><strong>Reduced external call overhead</strong><br /> Some contract architectures require multiple external calls within a single transaction. By consolidating related functionality behind a single diamond address, these interactions can execute internally with shared storage and shared authorization, reducing gas costs from external calls and repeated access-control checks.</p> </li> <li> <p><strong>Selective optimization per facet</strong><br /> Because facets are compiled and deployed independently, they may be built with different compiler optimizer settings. This allows gas-critical facets to use aggressive optimization configurations to reduce execution costs, without increasing bytecode size or compilation complexity for unrelated functionality.</p> </li> </ol> <h3 id="functionfacetpairs-gas-usage"><code>functionFacetPairs()</code> Gas Usage</h3> <p>The <code>functionFacetPairs()</code> function is meant to be called off-chain. At this time major RPC providers have a maximum gas limit of about 550 million gas. Gas benchmark tests show that the <code>functionFacetPairs()</code> function can return 60,000 <code>(selector, facet)</code> pairs using less gas than that.</p> <p>ERC-8109 implementations are free to add iteration or pagination-based introspection functions, but they are not required by this standard.</p> <h3 id="storage-layout">Storage Layout</h3> <p>Diamonds and facets need to use a storage layout organizational pattern because Solidity’s default storage layout doesn’t support proxy contracts or diamonds. The storage layout technique or pattern to use is not specified in this ERC. However, examples of storage layout patterns that work with diamonds are <a href="https://wg-eips.ritovision.com/8042/">ERC-8042 Diamond Storage</a> and <a href="https://wg-eips.ritovision.com/7201/">ERC-7201 Namespaced Storage Layout</a>.</p> <h3 id="facets-sharing-storage-functionality">Facets Sharing Storage &amp; Functionality</h3> <p>Facets are separately deployed, independent units, but can share state and functionality in the following ways:</p> <ul> <li>Facets can share state variables by using the same structs at the same storage positions.</li> <li>Facets can share internal functions by importing them or inheriting contracts.</li> </ul> <h3 id="on-chain-facets-can-be-reused-and-composed">On-chain Facets can be Reused and Composed</h3> <p>A deployed facet can be used by many diamonds.</p> <p>It is possible to create and deploy a set of facets that are reused by different diamonds.</p> <p>The ability to use the same deployed facets for many diamonds has the potential to reduce development time, increase reliability and security, and reduce deployment costs.</p> <p>It is possible to implement facets in a way that makes them usable/composable/compatible with other facets.</p> <h3 id="function-signature-limitation">Function Signature Limitation</h3> <p>A function signature is the name of a function and its parameter types. Example function signature: <code>myfunction(uint256)</code>. A limitation is that two external functions with the same function signature can’t be added to the same diamond at the same time because a diamond, or any contract, cannot have two external functions with the same function signature.</p> <h3 id="immutable-functions-considerations">Immutable Functions Considerations</h3> <p>Immutable functions offer minor gas savings by avoiding fallback logic and a <code>delegatecall</code>. However, they introduce a second implementation alongside facets, resulting in two ways to provide similar functionality. This increases implementation complexity and cognitive overhead.</p> <p>A diamond is simpler to implement and understand without immutable functions.</p> <p>In upgradeable diamonds, immutable functions reduce flexibility, as they cannot be replaced or removed. This limits the ability to evolve, fix, or improve functionality over time.</p> <p>Immutable functions that read from or write to storage are not isolated from upgrades. Other functions, including upgrade logic, may modify the same storage relied upon by immutable functions.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Existing, deployed ERC-2535 Diamonds implementations MAY upgrade to this standard by performing an upgrade that does the following:</p> <ol> <li>Removes the existing upgrade function and adds a new upgrade function that uses the new events.</li> <li>Adds the new <code>functionFacetPairs()</code> introspection function.</li> <li>Emits a <code>DiamondFunctionAdded</code> event for every function currently in the diamond, including the new upgrade function and the new <code>functionFacetPairs()</code> function.</li> </ol> <p>Any other upgrade details are implementation specific.</p> <p>After this upgrade, the diamond is considered compliant with this standard and SHOULD be indexed and treated as a diamond of this standard going forward.</p> <p>This upgrade acts as a 'state snapshot'. Indexers only interested in the current state of the diamond can start indexing from this transaction onwards, without needing to parse the legacy <code>DiamondCut</code> history.</p> <p>To reconstruct the complete upgrade history requires retrieving all the past <code>DiamondCut</code> events as well as all new events defined in this standard.</p> <h3 id="erc-2535-diamonds-with-immutable-functions">ERC-2535 Diamonds with Immutable Functions</h3> <p>An ERC-2535 diamond that upgrades to this standard and has immutable functions MUST comply with the <a href="https://wg-eips.ritovision.com/8109/#immutable-functions">Immutable Functions</a> section of the Specification.</p> <p>If the ERC-2535 diamond upgrade function is immutable, then it can't be removed. If possible, disable the upgrade function by making its authentication always fail.</p> <h2 id="reference-implementation">Reference Implementation</h2> <ul> <li>The reference implementation for the <code>facetAddress(bytes4 _functionSelector)</code> and <code>functionFacetPairs()</code> introspection functions is here: <a href="https://wg-eips.ritovision.com/8109/./assets/DiamondInspectFacet.sol">DiamondInspectFacet.sol</a></li> <li>An example implementation of an ERC-8109 diamond is here: <a href="https://wg-eips.ritovision.com/8109/./assets/DiamondExample.sol">DiamondExample.sol</a></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <h3 id="ownership-and-authentication">Ownership and Authentication</h3> <p>The design and implementation of diamond ownership/authentication is not part of this standard.</p> <p>It is possible to create many different authentication or ownership schemes with diamonds. Authentication schemes can be very simple or complex, fine grained or coarse. This proposal does not limit it in any way. For example ownership/authentication could be as simple as a single account address having the authority to add/replace/remove functions. Or a decentralized autonomous organization could have the authority to add/replace/remove certain functions.</p> <p>The development of standards and implementations of ownership, control and authentication of diamonds is encouraged.</p> <h3 id="transparency">Transparency</h3> <p>A diamond emits an event every time a function is added, replaced or removed. Source code can be verified. This enables people and software to monitor changes to a diamond.</p> <p>Security and domain experts can review a diamond's upgrade history.</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-12-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Hoanghttps://github.com/0x76agabond https://wg-eips.ritovision.com/8110/

An architectural pattern that organizes Diamond storage by domain using ERC-8042 identifiers.

<h2 id="abstract">Abstract</h2> <p>This standard introduces a <strong>domain-based architectural pattern</strong> for contracts implementing the Diamond execution model defined by <a href="https://wg-eips.ritovision.com/2535/">ERC-2535 (Diamond Standard)</a> or <a href="https://wg-eips.ritovision.com/8109/">ERC-8109 (Diamond, Simplified)</a>, together with the storage identifier mechanism defined by <a href="https://wg-eips.ritovision.com/8042/">ERC-8042 (Diamond Storage Identifier)</a>.</p> <p>It defines a domain-centric storage management architecture, providing consistent storage identifiers and a structured directory model that decouples storage ownership from facet logic.</p> <p>This pattern helps reduce storage collisions and human error while enabling better tooling for multi-facet systems.</p> <h2 id="motivation">Motivation</h2> <p>ERC-2535 provides a flexible foundation for modular smart contracts through facets, but it intentionally leaves storage organization and architectural conventions open to implementation.<br /> While this flexibility encourages creativity, it can sometimes lead to inconsistency.<br /> Each developer or team may structure storage differently, making it harder to design robust and easy-to-use tooling for storage management.</p> <p>Without a shared structural framework, storage identifiers may be inconsistently verified or reused across facets, which can result in unexpected collisions or subtle upgrade issues between facets sharing the same state.</p> <p>ERC-8042 introduced human-readable storage identifiers to improve clarity, but it does not define how those identifiers should be structured or grouped in larger projects.</p> <p>This EIP proposes a domain-centric architectural pattern that establishes a consistent framework for managing storage independently of facet implementation.</p> <p>By introducing clear domain boundaries and deterministic naming rules for storage identifiers, the pattern maintains the openness of the Diamond Standard while providing a shared foundation for collaboration, tooling support, and long-term upgrade safety across complex systems.</p> <h2 id="specification">Specification</h2> <h3 id="1-domain-definition">1. Domain Definition</h3> <ul> <li> <p>A <strong>domain</strong> represents the conceptual ownership of a storage space.</p> </li> <li> <p>Each <strong>domain</strong> corresponds to exactly one storage struct and one identifier.</p> </li> <li> <p>A <strong>domain</strong> has a one-to-many relationship with the group of function selectors that access it.</p> </li> <li> <p>A <strong>domain</strong> is independent of facets, multiple facets MAY read or modify the same domain.</p> </li> <li> <p><strong>Domains</strong> SHOULD be defined according to business or system responsibility, not by facet name.</p> </li> </ul> <h3 id="2-storage-identifier-naming-convention">2. Storage Identifier Naming Convention</h3> <p>A storage identifier is the human-readable string whose keccak256 hash defines a Diamond Storage position.</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"> constant</span><span> STORAGE_POSITION </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;meaningful.string&quot;</span><span>)</span><span>;</span></span></code></pre> <p>It represents the domain that owns and manages a specific storage layout.<br /> To ensure uniqueness and clarity, at a minimum, a storage identifier SHOULD include the following components:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> {project}.{domain-name}.{version}</span></span></code></pre> <p>To improve readability, namespace separation, and tooling support, additional contextual components MAY be included, resulting in the following extended format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> {org}.{project}.{domain-type}.{domain-name}.{version}</span></span></code></pre><h3 id="identifier-components">Identifier Components</h3> <ul> <li> <p><code>org</code><br /> Optional organization or author prefix (e.g., <code>eth</code>, <code>vag</code>, <code>safe</code>)</p> </li> <li> <p><code>project</code><br /> Project or protocol name</p> </li> <li> <p><code>domain-type</code><br /> Optional classification of the domain. If present, it SHOULD be one of:</p> <ul> <li> <p><code>diamond</code> — core Diamond protocol domains, such as upgrade, introspection, and ownership.</p> </li> <li> <p><code>system</code> — shared system-level domains providing cross-cutting functionality. (e.g., reentrancy, pause, access control)</p> </li> <li> <p><code>business</code> — application-specific domains. (tokens, guards, modules)</p> </li> </ul> </li> <li> <p><code>domain-name</code><br /> Lowercase keyword identifying the storage domain</p> </li> <li> <p><code>version</code><br /> Optional storage layout version identifier</p> <ul> <li> <p>The initial storage layout is conceptually treated as <code>v1</code>.</p> </li> <li> <p>If omitted, the identifier refers to this initial (<code>v1</code>) storage layout for backward compatibility.</p> </li> <li> <p><code>v2</code>, <code>v3</code>, … MUST be used for layout-breaking changes.</p> </li> <li> <p>The version MUST be incremented only when the storage layout is no longer append-only.</p> </li> </ul> </li> </ul> <p><strong>Each domain:</strong></p> <ul> <li> <p>MUST have <strong>one</strong> storage struct and <strong>one</strong> identifier.</p> </li> <li> <p>SHOULD be implemented in a dedicated directory named after the domain.</p> </li> <li> <p>If new fields are added to a storage struct, they MUST be added only at the end, and the struct MUST remain append-only.</p> </li> </ul> <h3 id="sub-domain-components">Sub-domain Components</h3> <p>A sub-domain represents a storage-isolated vertical extension of an existing domain.</p> <p>A sub-domain is used when new functionality belongs conceptually to an existing domain, but its required state can be cleanly isolated without modifying or appending to the original domain’s storage layout.</p> <p>If present, the sub-domain's identifier format becomes:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> {project}.{domain-name}.{version}.{sub-domain}</span></span></code></pre> <p>or, when using the extended format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> {org}.{project}.{domain-type}.{domain-name}.{version}.{sub-domain}</span></span></code></pre> <p>The version component indicates the domain version in which the sub-domain was introduced.<br /> It serves as a historical and organizational reference, not as an independent versioning lifecycle for the sub-domain.</p> <p><strong>Definition and Rules</strong></p> <p>A sub-domain:</p> <ul> <li> <p>MUST define its own ERC-8042 storage identifier.</p> </li> <li> <p>MUST define its own storage layout</p> </li> <li> <p>MUST NOT modify or append to the parent domain’s storage.</p> </li> <li> <p>MUST remain conceptually subordinate to the parent domain.</p> </li> <li> <p>MUST share the same version context as the parent domain.</p> </li> <li> <p>SHOULD be placed alongside the parent domain’s storage definitions.</p> </li> </ul> <p>Sub-domains exist as a safety-oriented design choice to isolate newly introduced state, while preserving the original domain layout unchanged.</p> <p>Choosing between evolving the existing domain storage or introducing a sub-domain depends on the project’s complexity, the team’s discipline, and long-term maintenance goals.</p> <h3 id="3-storage-declaration-requirements">3. Storage Declaration Requirements</h3> <p>To support reliable tooling and explicit storage ownership, each domain defined by this proposal MUST declare its storage location using the ERC-8042 NatSpec annotation.</p> <p>Specifically, the domain-owned storage struct MUST be annotated with:</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:storage</span><span class="z-comment">-location erc8042:&lt;NAMESPACE_ID&gt;</span></span></code></pre> <p>This proposal does not redefine the storage location formula, but requires the use of this annotation to ensure that domain storage is discoverable, unambiguous, and machine-readable.</p> <h3 id="example-identifiers">Example Identifiers</h3> <p>The extended identifier format is recommended for global uniqueness. It is especially useful when integrating shared libraries, predefined facets, or other standards, where namespace collisions are more likely.</p> <p>For application-specific systems, teams may choose a minimal identifier format to reduce naming complexity, as long as the identifier remains stable and unique within the project.</p> <p><strong>Equipment Identifier</strong></p> <p>Represents a business domain responsible for equipment state. This domain has undergone a layout-breaking change, therefore uses an explicit v2 identifier.</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:storage</span><span class="z-comment">-location erc8042:org.project.business.equipment.v2</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Minimal form: project.equipment.v2</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span> EQUIPMENT_STORAGE_POSITION </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;org.project.business.equipment.v2&quot;</span><span>)</span><span>;</span></span></code></pre> <p><strong>Character Identifier</strong></p> <p>Represents a business domain responsible for character state and progression. This example also demonstrates how a domain can be extended using a storage-isolated sub-domain.</p> <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:storage</span><span class="z-comment">-location erc8042:org.project.business.character.v1</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Minimal form: project.character.v1</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Main character domain.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span> CHARACTER_STORAGE_POSITION </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;org.project.business.character.v1&quot;</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"> @custom:storage</span><span class="z-comment">-location erc8042:org.project.business.character.v1.mounted</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Minimal form: project.character.v1.mounted</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Sub-domain for global character mounted state.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span> CHARACTER_MOUNTED_STORAGE_POSITION </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;org.project.business.character.v1.mounted&quot;</span><span>)</span><span>;</span></span></code></pre> <p><strong>Game Setting Identifier</strong></p> <p>Defines a system-level domain for game-wide configuration shared across multiple facets.</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:storage</span><span class="z-comment">-location erc8042:org.project.system.gamesettings</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Minimal form: project.gamesettings</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span> GAME_SETTING_STORAGE_POSITION </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;org.project.system.gamesettings&quot;</span><span>)</span><span>;</span></span></code></pre><h3 id="4-directory-convention">4. Directory Convention</h3> <p>In line with Domain-Driven Design principles, the directory layout SHOULD reflect domain ownership.</p> <ul> <li> <p><strong>Each domain defines a logical namespace for storage ownership</strong>.<br /> Directories are named after this namespace and serve as its physical representation in the codebase.</p> </li> <li> <p><strong>Facets act as logic containers and do not own storage</strong>.<br /> They MAY reside alongside domain directories or reference domain-owned logic.</p> </li> <li> <p><strong>Both directory names and storage identifiers SHOULD include domain information</strong>.<br /> This consistency allows tooling and precompilers to automatically associate selectors, domains, and storage layouts.</p> </li> <li> <p><strong>Each domain SHOULD be represented by a dedicated directory</strong>.<br /> Within this directory, domain-owned logic such as storage layout definitions, internal helper logic, and any facets primarily associated with the domain MAY be organized under subdirectories as needed.</p> </li> <li> <p><strong>This structure reduces the risk of storage collisions by design</strong>.<br /> The alignment of domain namespaces, directory layout, and storage identifiers allows file system constraints and static analysis tools to surface conflicts early and reason about upgrades proactively.</p> </li> </ul> <h3 id="example-directory">Example Directory</h3> <p><em>This directory structure is illustrative and does not mandate a specific naming convention.</em><br /> <em>Subdirectory names such as <code>storage/</code> are illustrative and may contain both storage layout definitions and internal domain logic.</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>contracts/</span></span> <span class="giallo-l"><span>├── diamond/</span></span> <span class="giallo-l"><span>│ └── Diamond.sol</span></span> <span class="giallo-l"><span>│</span></span> <span class="giallo-l"><span>├── character/</span></span> <span class="giallo-l"><span>│ ├── storage/</span></span> <span class="giallo-l"><span>│ │ └── CharacterStorage.sol</span></span> <span class="giallo-l"><span>│ └── facets/</span></span> <span class="giallo-l"><span>│ └── CharacterFacet.sol</span></span> <span class="giallo-l"><span>│</span></span> <span class="giallo-l"><span>├── equipment/</span></span> <span class="giallo-l"><span>│ ├── storage/</span></span> <span class="giallo-l"><span>│ │ └── EquipmentStorage.sol</span></span> <span class="giallo-l"><span>│ └── facets/</span></span> <span class="giallo-l"><span>│ └── EquipmentFacet.sol</span></span> <span class="giallo-l"><span>│</span></span> <span class="giallo-l"><span>└── gamesettings/</span></span> <span class="giallo-l"><span> ├── storage/</span></span> <span class="giallo-l"><span> │ └── GameSettingsStorage.sol</span></span> <span class="giallo-l"><span> └── facets/</span></span> <span class="giallo-l"><span> └── GameSettingsFacet.sol</span></span></code></pre><h3 id="5-upgrade-scenarios">5. Upgrade Scenarios</h3> <p>This architecture defines upgrade behavior based on <strong>the effect new selectors introduce to domains and storage</strong>, rather than on facets themselves.</p> <p>Upgrades fall into one of the following cases.</p> <p><strong>Case 1: No new storage required</strong></p> <p>If new selectors do not require any additional storage:</p> <ul> <li>The selectors MAY be added to existing facets or new facets</li> <li>The facet SHOULD be placed under an appropriate existing domain</li> <li>No storage changes are required</li> </ul> <p>This is the simplest and safest upgrade path, as it introduces no new state and does not affect existing storage layouts.</p> <p><strong>Case 2: New domain required (horizontal upgrade)</strong></p> <p>If new functionality introduces state that does not logically belong to any existing domain:</p> <ul> <li>A new domain MUST be defined</li> <li>A new ERC-8042 storage identifier MUST be introduced</li> <li>A new storage layout MUST be defined for that domain</li> <li>The facet implementing this functionality SHOULD be placed under the new domain</li> </ul> <p>This represents a horizontal expansion of the system, allowing new features to be introduced without impacting existing domains or storage layouts.</p> <p><strong>Case 3: New variables within an existing domain (vertical upgrade)</strong></p> <p>If new selectors require additional state that logically belongs to an existing domain, and the existing storage layout is not broken, this becomes a design trade-off.</p> <p>Two common approaches MAY be used:</p> <p><strong>Option A — Evolve the existing domain</strong></p> <ul> <li>Append new variables to the end of the existing storage layout</li> <li>Add new selectors to interact with the evolved domain</li> </ul> <p>This keeps the domain unified and works well for tightly coupled or complex business logic.<br /> It requires strict discipline when managing storage layout.</p> <p><strong>Option B — Introduce a sub-domain</strong></p> <ul> <li>Define a sub-domain under the existing domain</li> <li>Introduce a new storage identifier and layout for the new variables</li> <li>Leave the original domain storage unchanged</li> </ul> <p>This approach reduces risk and cognitive load by isolating newly introduced state, while keeping the original domain layout stable.</p> <p>The choice between these approaches depends on project complexity, team discipline, and long-term maintenance goals.</p> <p><strong>Case 4: Layout-breaking change</strong></p> <p>If new selectors require a change that breaks the existing storage layout of a domain<br /> (<em>for example, changing the inner structure of nested structs or struct arrays</em>)</p> <ul> <li>A new, versioned storage identifier MUST be introduced</li> <li>A new storage layout MUST be defined under that identifier</li> <li>Any required data migration MUST be handled explicitly by the project</li> </ul> <p>This architecture does not attempt to automate or abstract storage migration.<br /> The goal is to keep schema changes intentional, visible, and auditable.</p> <p>If the layout-breaking change is <strong>partial</strong>, and the newly required state can be cleanly isolated and defined independently, developers MAY also consider introducing a <strong>sub-domain</strong> instead of versioning the entire domain.</p> <h2 id="rationale">Rationale</h2> <p>From the beginning, the Diamond Standard (ERC-2535) was designed around the relationship between <strong>function selectors</strong> and <strong>storage positions</strong>, not around facets themselves.<br /> Facets are replaceable units of logic — the <code>diamondCut</code> operation only replaces, removes or adds code — but the <strong>storage layout persists</strong> and defines the actual state continuity of the contract.</p> <p>ERC-8109 itself only defines introspection mechanisms for querying the Diamond and deliberately leaves the upgrade mechanism to implementations or to other standards.<br /> This flexibility is achieved because both introspection facets and upgrade facets interact with the same underlying domain (<code>8109.diamond</code>).</p> <p>This demonstrates that <strong>storage belongs to the domain</strong>, not the facet, facets merely provide interfaces for logic to read or mutate that domain.</p> <p>Over time, many implementations have treated facets as the primary boundary of responsibility, grouping logic and storage together without recognizing that <strong>storage domains</strong> are the true architectural anchors.<br /> This misunderstanding leads to inconsistent storage management, overlapping identifiers and fragile upgrade paths where one facet unintentionally corrupts another’s state.</p> <p>The <strong>domain-centric approach</strong> restores the original intent of the Diamond:<br /> Selectors (facets) operate <em>through</em> domains, not <em>as</em> domains.<br /> Each domain defines its own persistent storage struct and identifier, while facets merely act as interfaces that execute logic against it.</p> <p>This shift decouples storage from logic when separation is desired, while still allowing tightly coupled designs when intentional.<br /> It enables:</p> <ul> <li>Independent evolution of business logic without rewriting storage.</li> <li>Clear separation between reusable system components and app-specific domains.</li> <li>A deterministic mapping between identifiers and state.</li> </ul> <p>By formalizing this pattern, Diamond Architecture becomes safer, more transparent and easier to extend — re-aligning practice with its original design philosophy.</p> <h3 id="special-case-domain-facet-overlap">Special Case: Domain–Facet Overlap</h3> <p>There is a special case within the separation principle where a domain (or sub-domain) and its facet are intentionally designed to represent the same logical entity.</p> <p>In this scenario, the facet implements all functions belonging to its domain. This reduces flexibility, but improves encapsulation and self-containment, making the facet behave like a reusable application module rather than a low-level primitive.</p> <p>A concrete example of this approach can be found in the <code>Compose project</code>.<br /> In Compose, a facet and its associated sub-domain are explicitly mapped into a single entity, enabling the creation of predefined, plug-and-play standard facets.</p> <p>This approach is suitable for systems that prioritize modular composition and standardized functionality, allowing developers to safely integrate common features with predictable behavior.<br /> However, when implementing custom or project-specific logic, domains and facets SHOULD still be treated as separate entities.</p> <p>Maintaining this separation preserves clarity of ownership, supports future upgrades, and supports the long-term evolution of application-level Diamond architectures.</p> <h3 id="sub-domains-and-layout-sensitive-state">Sub-domains and Layout-Sensitive State</h3> <p>Sub-domains can also serve as a practical way to isolate layout-sensitive state.</p> <p>Projects that need to move quickly may choose to place complex or layout-unstable data (such as mappings or dynamic arrays) in a primary domain, while isolating smaller or more compact state in sub-domains.</p> <p>As development progresses, additional state can either be appended to an existing domain or introduced via a sub-domain, depending on data shape and evolution needs.</p> <p>This allows projects to start with a simple structure while preserving flexibility to refine storage organization as the system scales.</p> <h3 id="isolated-domain">Isolated Domain</h3> <p>An isolated domain describes a conceptual separation between a domain and function- or facet-level logic.</p> <p>In this model, a domain defines its own storage access helpers. Facets and their functions interact with domain-owned state through these helpers, rather than accessing storage layouts directly.</p> <p>This approach makes data access logic explicit at the domain level, while allowing facets to focus on business logic and coordination.</p> <p>A domain may be fully isolated, partially isolated, or not isolated, depending on project needs.</p> <p>This concept is particularly useful when functions or facets need to coordinate state across multiple domains or sub-domains, as it helps keep cross-domain interactions consistent and easier to reason about.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backward-compatible with ERC-2535 (Diamond Standard), ERC-8042 (Diamond Storage Identifier) and ERC-8109 (Diamond, Simplified). It introduces no breaking changes, no new opcodes, and no modifications to existing protocol mechanics.</p> <p>It does not alter the execution model defined by ERC-2535 or ERC-8109. The relationships between facets, selectors, and shared storage remain unchanged and fully compatible across all three standards.</p> <p>Instead, this proposal defines an architectural convention that complements existing Diamond standards by:</p> <ul> <li>Reinforcing modularity and upgrade safety established by ERC-2535 and ERC-8109</li> <li>Extending the human-readable storage identifier design introduced by ERC-8042</li> <li>Providing a domain-based approach to storage ownership and organization</li> </ul> <p>This architecture may be applied to contracts implementing either ERC-2535 or ERC-8109, as both share the same fundamental facet and selector architecture.</p> <p>Developers are encouraged to continue following all applicable standards to maintain interoperability while benefiting from clearer state ownership, reduced storage collision risk, and lower architectural complexity.</p> <h3 id="adoption-for-deployed-systems">Adoption for Deployed Systems</h3> <p>For already deployed systems, adoption can be done incrementally.</p> <p>The Domain Architecture does not require projects to modify, rename, or refactor existing libraries or other standards in order to adopt it. If a library or standard already follows ERC-2535, ERC-8042, or uses its own established storage identifiers, that code SHOULD remain unchanged.</p> <p>Adoption MAY begin at the application layer, without touching shared libraries or standardized components. Existing storage identifiers MAY be treated conceptually as pre-v1 domains.</p> <p>In practice, projects typically start by:</p> <ul> <li>Defining clear domain boundaries</li> <li>Organizing directories around domain responsibility</li> <li>Grouping facets and their related storage by domain</li> <li>Explicitly declaring storage ownership using the ERC-8042 <code>@custom:storage-location</code> annotation</li> </ul> <p>Adopting the Domain Architecture does not require migrating existing state. It primarily affects how new storage is introduced and how future upgrades are structured.</p> <p>When a layout-breaking change is required, a new versioned storage identifier can be introduced explicitly, allowing existing storage layouts to remain untouched. Any data migration, if needed, MUST be handled explicitly by the project.</p> <p>The primary consideration during adoption is identifier uniqueness. New storage identifiers MUST NOT collide with existing identifiers from shared libraries or from within the project itself.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Minimal implementation examples demonstrating the convention:</p> <p><strong>Business Domain (Equipment)</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"> @custom:storage</span><span class="z-comment">-location erc8042:org.project.business.equipment.v2</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Minimal form: project.equipment.v2</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span> EQUIPMENT_STORAGE_POSITION </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;org.project.business.equipment.v2&quot;</span><span>)</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"> Equipment</span><span> </span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> itemType</span><span>;</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint16</span><span> power</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> rarity</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> effectOwner</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"> struct</span><span class="z-entity z-name"> EquipmentStorage</span><span> </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> Equipment</span><span>)</span><span> items</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> itemId =&gt; Equipment</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"> equipmentStorage</span><span>(</span><span>)</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">EquipmentStorage</span><span class="z-storage z-type"> storage</span><span class="z-variable"> s</span><span>)</span><span> </span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> position </span><span class="z-keyword">=</span><span> EQUIPMENT_STORAGE_POSITION</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> s</span><span>.</span><span>slot </span><span class="z-keyword">:=</span><span> position</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <p><strong>Business Domain (Character)</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"> @custom:storage</span><span class="z-comment">-location erc8042:org.project.business.character.v1</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Minimal form: project.character.v1</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Main character domain.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span> CHARACTER_STORAGE_POSITION </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;org.project.business.character.v1&quot;</span><span>)</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"> Character</span><span> </span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> level</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> hp</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> equipment slot =&gt; itemId</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> e.g. slot: head, chest, weapon, boots...</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint8</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint256</span><span>)</span><span> equippedItemId</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"> CharacterStorage</span><span> </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> Character</span><span>)</span><span> characters</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"> characterStorage</span><span>(</span><span>)</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">CharacterStorage</span><span class="z-storage z-type"> storage</span><span class="z-variable"> s</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> position </span><span class="z-keyword">=</span><span> CHARACTER_STORAGE_POSITION</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> s</span><span>.</span><span>slot </span><span class="z-keyword">:=</span><span> position</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-storage z-type"> @custom:storage</span><span class="z-comment">-location erc8042:org.project.business.character.v1.mounted</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Minimal form: project.character.v1.mounted</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Sub-domain for global character mounted state.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span> CHARACTER_MOUNTED_STORAGE_POSITION </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;org.project.business.character.v1.mounted&quot;</span><span>)</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"> CharacterMountedStorage</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Global character state, persists across character switches</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isMounted</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"> characterMountedStorage</span><span>(</span><span>)</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">CharacterMountedStorage</span><span class="z-storage z-type"> storage</span><span class="z-variable"> s</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> position </span><span class="z-keyword">=</span><span> CHARACTER_MOUNTED_STORAGE_POSITION</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> s</span><span>.</span><span>slot </span><span class="z-keyword">:=</span><span> position</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <p><strong>System Domain (Game Settings)</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"> @custom:storage</span><span class="z-comment">-location erc8042:org.project.system.gamesettings</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Minimal form: project.gamesettings</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span> GAME_SETTING_STORAGE_POSITION </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;org.project.system.gamesettings&quot;</span><span>)</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"> GameSettingStorage</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> balancePatchBlock</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> rulesetHash</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> gameVersion</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> seasonId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> tradingEnabled</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> craftingEnabled</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> pvpEnabled</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"> gameSettingsStorage</span><span>(</span><span>)</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">GameSettingStorage</span><span class="z-storage z-type"> storage</span><span class="z-variable"> s</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> position </span><span class="z-keyword">=</span><span> GAME_SETTING_STORAGE_POSITION</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> s</span><span>.</span><span>slot </span><span class="z-keyword">:=</span><span> position</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <p>Each domain defines and owns its storage independently. Facets interact with domain-owned storage definitions, supporting safe upgrades and avoiding unintended storage overlap.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This pattern strengthens the security model of Diamond-based systems by introducing explicit and deterministic storage identifiers.</p> <p>By separating domains and enforcing consistent naming rules, it reduces the risk of:</p> <ul> <li>Storage collisions between unrelated facets or upgrades.</li> <li>Human errors caused by inconsistent or reused identifiers.</li> <li>State corruption during upgrades or extensions.</li> </ul> <p>Each domain owns its ERC-8042 storage identifier. When combined with append-only storage layout upgrades, this allows storage evolution without interfering with existing state.</p> <p>This clarity also improves auditability and supports static analysis tooling when analyzing storage safety across upgrades.</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-12-17T00:00:00+00:00 2026-02-11T14:49:28+00:00 Greg Colvinhttps://github.com/gcolvin Martin Holst Swendehttps://github.com/holiman Brooklyn Zelenkahttps://github.com/expede John Max Skallerskaller@internode.on.net https://wg-eips.ritovision.com/7979/

Three new instructions to support calls and returns, with optional validated control flow.

<h2 id="abstract">Abstract</h2> <p>This is the smallest possible change to the EVM to support calls and returns.</p> <p>This proposal introduces three new control-flow instructions to the EVM:</p> <ul> <li><code>CALLSUB</code> transfers control to the <code>destination</code> on the <code>stack</code>.</li> <li><code>ENTERSUB</code> marks a <code>CALLSUB</code> destination.</li> <li><code>RETURNSUB</code> returns to the <code>PC</code> after the most recent <code>CALLSUB</code>.</li> </ul> <p>Code can also be prefixed with <code>MAGIC</code> bytes. The complete control flow of <code>MAGIC</code> code can be traversed in time and space linear in the size of the code, enabling tools for validation, static analysis, and AOT and JIT compilers. On-chain, <code>MAGIC</code> code is validated at <code>CREATE</code> time to ensure that it cannot execute invalid instructions, jump to invalid locations, underflow stack, or, in the absence of recursion, overflow stack.</p> <p>These changes are backwards-compatible: all instructions behave as specified whether or not they appear in <code>MAGIC</code> code.</p> <h2 id="motivation">Motivation</h2> <p>In 2016 the lead author set out to write a compiler from the EVM to code for virtual or real register machines. The design was simple -- traverse the EVM stack code in one pass, emitting register code for the target machine. I was immediately stymied by the presence of dynamic jumps, which demand, worst case, a quadratic number of passes. <em>Dynamic jumps must die.</em></p> <p>How to kill them? First, some history.</p> <h3 id="babbage-1833-jumps-and-conditional-jumps">Babbage, 1833: Jumps and conditional jumps</h3> <p>In 1833 Charles Babbage began the design of a steam-powered, mechanical, Turing-complete computer. Programs were to be encoded on punched cards which controlled a system of rods, gears and other machinery to implement storage, arithmetic, jumps, and conditional jumps. Jumps were supported by a mechanism for shuffling forwards or backwards through the cards. Its first published description was by L. F. Menabre, 1842<sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">1</a></sup>. The translator, Ada Augusta, Countess of Lovelace, made extensive notes. The notes include her famous program for recursively computing Bernoulli numbers — arguably the world's first complete computer program — which used conditional jumps to implement the required nested loops.</p> <h3 id="turing-1945-calls-and-returns">Turing, 1945: Calls and returns</h3> <p>In 1945 Turing proposed his Automatic Computing Engine<sup class="footnote-reference" id="fr-3-1"><a href="#fn-3">2</a></sup>, where he introduced the concept of calls and returns: <em>"To start on a subsidiary operation we need only make a note of where we left off the major operation and then apply the first instruction of the subsidiary. When the subsidiary is over we look up the note and continue with the major operation."</em></p> <p>The ACE supported calls directly with a stack of mercury-filled memory crystals holding return addresses. Turing's design was for a 32-bit RISC machine with vacuum tube integer hardware, floating point microcode, 32 registers, a 1024-entry return stack, and 32K of RAM on a 1 MHz bus. The smaller Pilot ACE was for a while the world's fastest computer.</p> <h4 id="lovelace-turing-an-aside-on-machine-intelligence">Lovelace &amp; Turing: An aside on machine intelligence</h4> <p>In Lady Lovelace's notes we find her prescient recognition of the Analytic Engine's power: "In enabling mechanism to combine together general symbols in successions of unlimited variety and extent, a uniting link is established between the operations of matter and the abstract mental processes of the most abstract branch of mathematical science."<sup class="footnote-reference" id="fr-1-2"><a href="#fn-1">1</a></sup> Here also we find her recognition of its limits: "It can do whatever we know how to order it to perform. It can follow analysis; but it has no power of anticipating any analytical relations or truths. Its province is to assist us in making available what we are already acquainted with."<sup class="footnote-reference" id="fr-1-3"><a href="#fn-1">1</a></sup></p> <p>In 1950 Alan Turing answered "Lady Lovelace's Objection" with a question of his own: "The majority of minds seem to be 'subcritical' ... an idea presented to such a mind will on average give rise to less than one idea in reply. A smallish proportion are supercritical. An idea presented to such a mind that may give rise to a whole 'theory' consisting of secondary, tertiary and more remote ideas... we ask, 'Can a machine be made to be supercritical?'"<sup class="footnote-reference" id="fr-2-1"><a href="#fn-2">3</a></sup></p> <h3 id="industry-practice-1945-2025">Industry practice: 1945 - 2025</h3> <p>Call and return facilities of various levels of complexity have proven their worth across a long line of important machines over the last 80 years: Burroughs' baroque ALGOL support, Intel's simple <code>CALL</code> and <code>RET</code>, RISC-V's subtly dynamic <code>JAL</code> and <code>JALR</code>, ARM's bare mimimum <code>BL</code>, and some such facility on most every other machine we have programmed or implemented: physical machines including the, CDC 7600, IBM 360, PDP-11, VAX, Motorola 68000, and others, as well as virtual machines for Scheme, Forth, Pascal, Java, Wasm, .NET and others.</p> <p>Especially relevant to the EVM's design are the Java, Wasm, and .NET VMs. They share some important features: their programs are all</p> <ul> <li>represented with a portable bytecode that</li> <li>can be directly interpreted and</li> <li>can be validated before runtime</li> <li>to have static control flow that</li> <li>can be compiled to machine code</li> <li>with a one-pass JIT.</li> </ul> <p>We propose that the EVM should share these features.</p> <h3 id="the-evm-control-flow-facility">The EVM control-flow facility</h3> <p>Unlike these machines, the Ethereum Virtual Machine <em>does not</em> provide facilities for calls and returns. Instead, they must be synthesized using the dynamic <code>JUMP</code> instruction, which takes its argument on the stack. Further, the EVM provides <em>only</em> this jump. The EVM's dynamic jump causes problems. First, the need to synthesize static jumps and calls with dynamic jumps wastes some space and gas. The much bigger problem is this: jumps that can dynamically branch to any destination in the program can cause quadratic "path explosions" when traversing the program's flow of control. We will give more detailed explanations in the Rationale.</p> <p>Dynamic jumps are common enough in physical machines, whose instruction sets are of course optimized for physical performance, but less so in virtual machines, whose code is often the source for JIT compilers and other downstream tools — a JIT compiler that can take quadratic time is less than useful. For this reason the Java, Wasm, and .NET VMs do not support dynamic jumps.</p> <h3 id="why-dynamic-jumps-must-die">Why dynamic jumps must die</h3> <p>For Ethereum, quadratic traversal times are a denial-of-service vulnerability for any online static analysis, including validating EVM bytecode and translating its virtual stack code to other representations such as virtual register code and machine code -- whether AOT at initialization time, or JIT at runtime.</p> <p>Even offline, dynamic jumps (and the lack of calls and returns) can cause static analyses of many contracts to become impractical, intractable or even impossible. The following are quotes from the abstracts for just a few recent papers on the problem:</p> <blockquote> <p>"Ethereum smart contracts are distributed programs running on top of the Ethereum blockchain. Since program flaws can cause significant monetary losses and can hardly be fixed due to the immutable nature of the blockchain, there is a strong need of automated analysis tools which provide formal security guarantees. Designing such analyzers, however, proved to be challenging and error-prone."<sup class="footnote-reference" id="fr-4-1"><a href="#fn-4">4</a></sup></p> <p>"The EVM language is a simple stack-based language ... with one significant difference between the EVM and other virtual machine languages (like Java Bytecode or CLI for .Net programs): the use of the stack for saving the jump addresses instead of having it explicit in the code of the jumping instructions. Static analyzers need the complete control-flow graph (CFG) of the EVM program in order to be able to represent all its execution paths."<sup class="footnote-reference" id="fr-5-1"><a href="#fn-5">5</a></sup></p> <p>"Static analysis approaches mostly face the challenge of analyzing compiled Ethereum bytecode... However, due to the intrinsic complexity of Ethereum bytecode (especially in jump resolution), static analysis encounters significant obstacles."<sup class="footnote-reference" id="fr-6-1"><a href="#fn-6">6</a></sup></p> <p>"Analyzing contract binaries is vital ... comprising function entry identification and detecting its boundaries... Unfortunately, it is challenging to identify functions ... due to the lack of internal function call statements."<sup class="footnote-reference" id="fr-7-1"><a href="#fn-7">7</a></sup></p> </blockquote> <p>There is an entire academic literature of complex, incomplete solutions to problems like these that this proposal, others before it, and the design of other VMs render trivial.</p> <p>With so much at stake on the blockchain -- currently valued at over 6000 metric tonnes of gold -- deploying correct contracts is imperative — there is no reason for the EVM to make that job any more difficult than necessary. Especially when it is so easy to fix.</p> <h3 id="taming-the-evm">Taming the EVM</h3> <p>To prevent control-flow traversal from "going quadratic" we must prevent the dynamic use of jumps. On-chain, most uses of <code>JUMP</code> and <code>JUMPI</code> are preceded by a <code>PUSH</code> — that is, they are effectively static. So not quite dead, but provably paralyzed. This proposal <em>requires</em> that in <code>valid</code> code <code>JUMP</code> and <code>JUMPI</code> are <em>always</em> used statically. Currently, the only places that jumps <em>must</em> be used dynamically are to support calls and returns. For that purpose we propose <code>CALLSUB</code> and <code>RETURNSUB</code> opcodes as replacements.</p> <h2 id="specification">Specification</h2> <blockquote> <p><em>The key words MUST and MUST NOT in this Specification are to be interpreted as described in RFC 2119 and RFC 8174.</em></p> </blockquote> <h3 id="callsub-0x"><code>CALLSUB (0x..)</code></h3> <p>Transfers control to a subsidiary operation.</p> <ol> <li>Pop the <code>destination</code> on top on the <code>stack</code>.</li> <li>Push the current <code>PC + 1</code> to the <code>return stack</code>.</li> <li>Set <code>PC</code> to <code>destination</code>.</li> </ol> <p>The gas cost is <em>mid</em> (<code>8</code>).</p> <h3 id="entersub-0x"><code>ENTERSUB (0x..)</code></h3> <p>The <code>destination</code> of every <code>CALLSUB</code> MUST be an <code>ENTERSUB</code>.</p> <h3 id="returnsub-0x"><code>RETURNSUB (0x..)</code></h3> <p>Returns control to the caller of a subsidiary operation.</p> <ol> <li>Pop the <code>return stack</code> to <code>PC</code>.</li> </ol> <p>The gas cost is <em>low</em> (<code>5</code>).</p> <h3 id="magic-0xef"><code>MAGIC (0xEF....)</code></h3> <p>After this EIP has been activated code beginning with the <code>MAGIC</code> bytes MUST be a <code>valid</code> program. Execution begins immediately after the <code>MAGIC</code> bytes.</p> <p><em>Notes:</em></p> <ul> <li><em>Values popped off the <code>return stack</code> do not need to be validated, since they are alterable only by <code>CALLSUB</code> and <code>RETURNSUB</code>.</em></li> <li><em>The description above lays out the semantics of these instructions in terms of a <code>return stack</code>. But the actual state of the <code>return stack</code> is not observable by EVM code or consensus-critical to the protocol. (For example, a node implementer may code <code>CALLSUB</code> to unobservably push <code>PC</code> on the <code>return stack</code> rather than <code>PC + 1</code>, which is allowed so long as <code>RETURNSUB</code> observably returns control to the <code>PC + 1</code> location.)</em></li> <li><em>Opcode and <code>MAGIC</code> values are still to be determined.</em></li> </ul> <h3 id="costs">Costs</h3> <p>A <em>mid</em> cost for <code>CALLSUB</code> is justified by it taking very little more work than the <em>mid</em> cost of <code>JUMP</code> — just pushing an integer to the <code>return stack</code></p> <p>A <em>jumpdest</em> cost for <code>ENTERSUB</code> is justified by it being, like <code>JUMPDEST</code>, a mere label.</p> <p>A <em>low</em> cost for <code>RETURNSUB</code> is justified by needing only to pop the <code>return stack</code> into the <code>PC</code> — less work than a jump.</p> <p>Benchmarking will be needed to tell if the costs are well-balanced.</p> <h3 id="validity">Validity</h3> <p>Execution is defined in the Yellow Paper as a sequence of changes to the EVM state. The conditions on <code>valid</code> 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 and cannot continue. The Yellow Paper defines six such states.</p> <ul> <li>State modification during a static call</li> <li>Insufficient gas</li> <li>More than 1024 stack items</li> <li>Insufficient stack items</li> <li>Invalid jump destination</li> <li>Invalid instruction</li> </ul> <p>We would like to consider EVM code <code>valid</code> iff no execution of the program can lead to an exceptional halting state. In practice, we must test at runtime for the first three conditions. We don't know whether we will be called statically. We don't know how much gas there will be, and we don't know how deep a recursion may go. (However, we can validate that non-recursive programs do not overflow stack.) All of the remaining conditions MUST be validated statically. To allow for efficient algorithms our validation does not consider the codes 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.</p> <h4 id="constraints-on-valid-code">Constraints on <code>valid</code> code</h4> <p>Code beginning with <code>MAGIC</code> MUST be <code>valid</code>. Constraints on <code>valid</code> code MUST be validated at <code>CREATE</code> time, in time and space linear in the size of the code. The constraints on <code>valid</code> code are as follows.</p> <ul> <li>All executable opcodes must be <code>valid</code>: <ul> <li>They MUST have been defined in the Yellow Paper or a deployed EIP and</li> <li>MUST NOT have been deprecated in a subsequent deployed EIP.</li> <li>The <code>INVALID</code> opcode is <code>valid</code>.</li> </ul> </li> <li>The <code>JUMP</code> and <code>JUMPI</code> instructions MUST be preceded by a <code>PUSH</code> instruction.</li> <li>The <code>JUMP</code> and <code>JUMPI</code> instructions MUST NOT address immediate data, and MUST address a <code>JUMPDEST</code>.</li> <li>The <code>CALLSUB</code> instruction MUST be preceded by a <code>PUSH</code> instruction.</li> <li>The <code>CALLSUB</code> instruction MUST NOT address immediate data, and MUST address an <code>ENTERSUB</code>.</li> <li>The number of items on the <code>data stack</code> MUST always be positive and less than or equal to 1024.</li> <li>The number of items on the <code>return stack</code> MUST always be positive and less than or equal to 1024.</li> <li>The <code>stack height</code> is the absolute difference between the current <code>stack pointer</code> and the <code>stack pointer</code> at the most recent <code>ENTERSUB</code>.</li> <li> <ul> <li>During execution the <code>stack height</code> MUST be <em>the same</em> for every <code>PC</code>.</li> </ul> </li> </ul> <p>The guarantee of constant stack height prevents stack underflow, breaks cycles in the control flow, ensures finite stack use for non-recursive programs, enables one-pass recovery of control-flow, and allows virtual stack code to be directly serialized into virtual register code for faster interpretation and compilation to machine code.</p> <p><em>Note: The JVM, Wasm and .NET VMs enforce similar constraints for similar reasons.</em></p> <h4 id="validation">Validation</h4> <p>The above is a purely semantic specification, placing no constraints on the syntax of bytecode beyond being an array of opcodes and immediate data. "Subsidiary operations" here are not contiguous sequences of bytecode: they are subgraphs of the bytecode's full control-flow graph. The EVM is a simple state machine, and the control-flow graph for a program represents every possible change of state. Each instruction simply advances the state machine one more step, and state has no syntactic structure. We only promise that <code>valid</code> code will not, as it were, jam up the gears of the machine.</p> <p>Rather than enforce semantic constraints via syntax — as is done by higher-level languages — this proposal enforces them via validation: <code>MAGIC</code> code is proven <code>valid</code> at <code>CREATE</code> time. The constraints above MUST be proven true in time and space linear in the size of the code. We provide a simple algorithm below for doing so -- there are better ones.</p> <p>With no syntactic constraints and minimal semantic constraints we maximize opportunities for optimizations, including tail call elimination, multiple-entry calls, efficient register allocation, and inter-procedural optimizations. Since we want to support online compilation of EVM code to native code it is crucial that the EVM code be as well optimized as possible by our HLL compilers — upfront and offline.</p> <h2 id="rationale">Rationale</h2> <h3 id="how-can-dynamic-jumps-cause-quadratic-control-flow">How can dynamic jumps cause quadratic control flow?</h3> <p>Static analysis amounts to most anything you can do with a program without actually running it. And traversing the flow of control — in a way that follows every possible path only once — is a fundamental first step for many static analyses, especially for recovering control-flow graphs. When all jumps are static the number of steps is linear in the number of instructions: a fixed number of paths must be explored for each jump. But with dynamic jumps every possible destination must be explored at every jump: at worst, the number of steps can be quadratic in the number of instructions.</p> <p>Consider these three programs. They make for nice exploits, especially as they get longer. It's not important that at runtime <code>gas</code> isn't random or that the <code>jump</code> will most often fail -- what matters is that it is impossible to know at static analysis time where the jumps go, so every destination must be explored.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"></span> <span class="giallo-l"><span> jumpdest jumpdest jumpdest</span></span> <span class="giallo-l"><span> gas gas gas</span></span> <span class="giallo-l"><span> jump jump jump</span></span> <span class="giallo-l"><span> jumpdest jumpdest jumpdest</span></span> <span class="giallo-l"><span> gas gas gas </span></span> <span class="giallo-l"><span> jump jump jump</span></span> <span class="giallo-l"><span> jumpdest jumpdest jumpdest</span></span> <span class="giallo-l"><span> stop gas gas</span></span> <span class="giallo-l"><span> jump jump</span></span> <span class="giallo-l"><span> jumpdest jumpdest</span></span> <span class="giallo-l"><span> stop gas</span></span> <span class="giallo-l"><span> jump</span></span> <span class="giallo-l"><span> jumpdest</span></span> <span class="giallo-l"><span> stop</span></span> <span class="giallo-l"></span></code></pre> <p>And consider the control-flow graphs for these programs. Each block of instructions in a graph is a sequence from the above programs with one entry (a <code>JUMPDEST</code>) and one exit (a <code>JUMP</code>), and each arc is a transfer of control. Arcs on the left are backwards branches, arcs on the right are forwards branches.</p> <p><img src="https://wg-eips.ritovision.com/7979/./assets/control-flow.png" alt="Control-Flow Graphs" /> <em>Graph may be outdated</em></p> <p>Note that the number of arcs in a graph is equal to the number of blocks minus one, squared. That is, the number of possible paths of control flow, and thus the time needed to traverse them all, is quadratic in the size of the program.</p> <h3 id="do-we-save-on-code-size-and-gas">Do we save on code size and gas?</h3> <p>The difference these instructions make can be seen in this very simple code for calling a routine that squares a number. The distinct opcodes make it easier for both people and tools to understand the code, and there are modest savings in code size and gas costs as well.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"></span> <span class="giallo-l"><span>SQUARE: | SQUARE:</span></span> <span class="giallo-l"><span> jumpdest ; 1 gas | entersub ; 1 gas</span></span> <span class="giallo-l"><span> dup ; 3 gas | dup : 5 gas</span></span> <span class="giallo-l"><span> mul ; 5 gas | mul ; 5 gas</span></span> <span class="giallo-l"><span> swap1 ; 3 gas | returnsub ; 5 gas</span></span> <span class="giallo-l"><span> jump ; 8 gas |</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span>CALL_SQUARE: | CALL_SQUARE:</span></span> <span class="giallo-l"><span> jumpdest ; 1 gas | entersub ; 1 gas</span></span> <span class="giallo-l"><span> push RTN_CALL ; 3 gas | push 2 ; 3 gas</span></span> <span class="giallo-l"><span> push 2 ; 3 gas | push SQUARE ; 3 gas</span></span> <span class="giallo-l"><span> push SQUARE ; 3 gas | callsub ; 8 gas</span></span> <span class="giallo-l"><span> jump ; 8 gas | returnsub ; 5 gas</span></span> <span class="giallo-l"><span>RTN_CALL: |</span></span> <span class="giallo-l"><span> swap1 ; 3 gas |</span></span> <span class="giallo-l"><span> jump ; 8 gas |</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span>Size in bytes: 18 | Size in bytes: 13</span></span> <span class="giallo-l"><span>Consumed gas: 49 | Consumed gas: 38</span></span> <span class="giallo-l"></span></code></pre> <p>That's 32% fewer bytes and 30% less gas using <code>CALLSUB</code> versus using <code>JUMP</code>. So we can see that these instructions provide a simpler, more efficient mechanism. As code becomes larger and better optimized the gains become smaller, but code using <code>CALLSUB</code> always takes less space and gas than equivalent code without it.</p> <h3 id="do-we-improve-real-time-performance">Do we improve real-time performance?</h3> <p>Some real-time interpreter performance gains will be had, as reflected in the lower gas costs. But large real-time gains will come from AOT and JIT compilers. Crucially, the constraint that stack depths be constant means that in <code>MAGIC</code> code a very fast streaming JIT can traverse the control flow of the EVM code in one pass -- as it is executed -- generating machine code as it goes. <em>(Note again: the Wasm, JVM and .NET VMs share that property.)</em> The EVM is a stack machine, but real machines are register machines. So generating virtual register code for a faster interpreter is a win, (I have seen 4X speedups on JVM code) and generating good machine code gives orders of magnitude gains. But for most transactions storage dominates execution time, and gas counting and other overhead always take their toll. So these gains would be most visible in contexts where this overhead is absent, such as for L1 precompiles, on some L2s, and on some EVM-compatible chains. Code can also be compiled to a better instruction set for on-chain ZK work, such as RISC-V.</p> <h3 id="why-no-immediate-arguments">Why no immediate arguments?</h3> <p>This would of course break the promise of "the smallest possible change." <a href="https://wg-eips.ritovision.com/8013/">EIP-8013: Static relative jumps and calls for the EVM</a> is available if we want its size and performance advantages. It proposes five new EVM jump instructions (<code>RJUMP</code>, <code>RJUMPI</code>, <code>RJUMPV</code>, <code>RJUMPSUB</code>, and <code>RJUMPSUBV</code>) which encode destinations as signed immediate values. These can be useful for almost all <code>JUMP</code> and <code>JUMPI</code> use cases and offer improvements in cost, performance, and static analysis.</p> <h3 id="why-no-code-sections">Why no code sections?</h3> <p>Again, this would break the promise of "the smallest possible change," and <a href="https://wg-eips.ritovision.com/3540/">EIP-3540: EOF - EVM Object Format</a> remains available. But note that restricting jumps to code sections impedes important optimizations, which EOF supported by adding special opcodes. So if we want restricted code sections this becomes a much bigger change, and we should consider <a href="https://wg-eips.ritovision.com/4750/">EOF - Functions</a> and related EIPs separately. This proposal uses the same return-stack mechanism and poses no forwards compatability issues with EOF.</p> <h3 id="why-the-return-stack-mechanism">Why the return-stack mechanism?</h3> <p>In our experience most stack machines have separate stacks for data and for returns from calls, whereas most register machines have one stack for both data and return addresses, registers for computation, and instructions to support returns from calls in coordination with registers and the stack. The EVM is of course a stack machine, not a register machine. As an industry and a team we have substantial experience with the return-stack mechanism proposed here. It has been effectively used in many machines over the last eight decades since Turing invented it, and has been implemented, tested, and even ready to ship in many of our clients over the last nine years.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>These changes are backwards compatible.</p> <ul> <li>There are <em>no changes</em> to the semantics of existing EVM code. <ul> <li>With the caveat that code with unspecified behavior might behave in different, unspecified ways. Such code was always broken.</li> </ul> </li> <li>Opcode semantics <em>are not</em> affected by whether the code begins with <code>MAGIC</code>. <ul> <li>What is affected is the <em>validity</em> of code. <code>valid</code> code MUST execute identically in any contracts, but in <code>MAGIC</code> contracts the code MUST be <code>valid</code>.</li> </ul> </li> <li>This proposal <em>does not</em> require maintaining two interpreters.</li> </ul> <p>These changes do not foreclose EOF, RISC-V, or other changes; new <code>MAGIC</code> numbers would mark future EVMs. Neither do these changes preclude running the EVM in zero knowledge; they would more likely help.</p> <h2 id="test-cases">Test Cases</h2> <p><em>(Note: these tests are known to be outdated and incorrect.)</em></p> <h3 id="simple-routine">Simple routine</h3> <p>This should jump into a subroutine, back out and stop.</p> <p>Bytecode: <code>0x60045e005c5d</code> (<code>PUSH1 0x04, CALLSUB, STOP, BEGINSUB, RETURNSUB</code>)</p> <table><thead><tr><th>Pc</th><th>Op</th><th>Cost</th><th>Stack</th><th>RStack</th></tr></thead><tbody> <tr><td>0</td><td>PUSH1</td><td>3</td><td>[]</td><td>[]</td></tr> <tr><td>2</td><td>CALLSUB</td><td>10</td><td>[4]</td><td>[]</td></tr> <tr><td>5</td><td>RETURNSUB</td><td>5</td><td>[]</td><td>[ 2]</td></tr> <tr><td>3</td><td>STOP</td><td>0</td><td>[]</td><td>[]</td></tr> </tbody></table> <p>Output: 0x Consumed gas: <code>18</code></p> <h3 id="two-levels-of-subroutines">Two levels of subroutines</h3> <p>This should execute fine, going into one two depths of subroutines</p> <p>Bytecode: <code>0x6800000000000000000c5e005c60115e5d5c5d</code> (<code>PUSH9 0x00000000000000000c, CALLSUB, STOP, BEGINSUB, PUSH1 0x11, CALLSUB, RETURNSUB, BEGINSUB, RETURNSUB</code>)</p> <table><thead><tr><th>Pc</th><th>Op</th><th>Cost</th><th>Stack</th><th>RStack</th></tr></thead><tbody> <tr><td>0</td><td>PUSH9</td><td>3</td><td>[]</td><td>[]</td></tr> <tr><td>10</td><td>CALLSUB</td><td>10</td><td>[12]</td><td>[]</td></tr> <tr><td>13</td><td>PUSH1</td><td>3</td><td>[]</td><td>[10]</td></tr> <tr><td>15</td><td>CALLSUB</td><td>10</td><td>[17]</td><td>[10]</td></tr> <tr><td>18</td><td>RETURNSUB</td><td>5</td><td>[]</td><td>[10,15]</td></tr> <tr><td>16</td><td>RETURNSUB</td><td>5</td><td>[]</td><td>[10]</td></tr> <tr><td>11</td><td>STOP</td><td>0</td><td>[]</td><td>[]</td></tr> </tbody></table> <p>Consumed gas: <code>36</code></p> <h3 id="failure-1-invalid-jump">Failure 1: invalid jump</h3> <p>This should fail, since the given location is outside of the code-range. The code is the same as previous example, except that the pushed location is <code>0x01000000000000000c</code> instead of <code>0x0c</code>.</p> <p>Bytecode: <code>0x6801000000000000000c5e005c60115e5d5c5d</code> (<code>PUSH9 0x01000000000000000c, CALLSUB, STOP, BEGINSUB, PUSH1 0x11, CALLSUB, RETURNSUB, BEGINSUB, RETURNSUB</code>)</p> <table><thead><tr><th>Pc</th><th>Op</th><th>Cost</th><th>Stack</th><th>RStack</th></tr></thead><tbody> <tr><td>0</td><td>PUSH9</td><td>3</td><td>[]</td><td>[]</td></tr> <tr><td>10</td><td>CALLSUB</td><td>10</td><td>[18446744073709551628]</td><td>[]</td></tr> </tbody></table> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Error: at pc=10, op=CALLSUB: invalid jump destination</span></span></code></pre><h3 id="failure-2-shallow-return-stack">Failure 2: shallow <code>return stack</code></h3> <p>This should fail at first opcode, due to shallow <code>return_stack</code></p> <p>Bytecode: <code>0x5d5858</code> (<code>RETURNSUB, PC, PC</code>)</p> <table><thead><tr><th>Pc</th><th>Op</th><th>Cost</th><th>Stack</th><th>RStack</th></tr></thead><tbody> <tr><td>0</td><td>RETURNSUB</td><td>5</td><td>[]</td><td>[]</td></tr> </tbody></table> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Error: at pc=0, op=RETURNSUB: invalid retsub</span></span></code></pre><h3 id="subroutine-at-end-of-code">Subroutine at end of code</h3> <p>In this example. the CALLSUB is on the last byte of code. When the subroutine returns, it should hit the 'virtual stop' <em>after</em> the bytecode, and not exit with error</p> <p>Bytecode: <code>0x6005565c5d5b60035e</code> (<code>PUSH1 0x05, JUMP, BEGINSUB, RETURNSUB, JUMPDEST, PUSH1 0x03, CALLSUB</code>)</p> <table><thead><tr><th>Pc</th><th>Op</th><th>Cost</th><th>Stack</th><th>RStack</th></tr></thead><tbody> <tr><td>0</td><td>PUSH1</td><td>3</td><td>[]</td><td>[]</td></tr> <tr><td>2</td><td>JUMP</td><td>8</td><td>[5]</td><td>[]</td></tr> <tr><td>5</td><td>JUMPDEST</td><td>1</td><td>[]</td><td>[]</td></tr> <tr><td>6</td><td>PUSH1</td><td>3</td><td>[]</td><td>[]</td></tr> <tr><td>8</td><td>CALLSUB</td><td>10</td><td>[3]</td><td>[]</td></tr> <tr><td>4</td><td>RETURNSUB</td><td>5</td><td>[]</td><td>[ 8]</td></tr> <tr><td>9</td><td>STOP</td><td>0</td><td>[]</td><td>[]</td></tr> </tbody></table> <p>Consumed gas: <code>30</code></p> <h2 id="reference-implementation">Reference Implementation</h2> <p><em>(Note: this implementation is known to be incomplete and incorrect.)</em></p> <p>The following is a pseudo-Python implementation of an algorithm for predicating code validity. An equivalent algorithm MUST be run at <code>CREATE</code> time in space and time linear in the size of the code. The following algorithm recursively traces the <em>code</em>, emulating its control flow and stack use and checking for violations of the rules above. It runs in time proportional to the size of the code, and the possible depth of recursion is proportional to the size of the code.</p> <h3 id="validation-function">Validation Function</h3> <p>We assume that instruction validation and destination analysis has been done, and that we have some constant-time helper functions:</p> <ul> <li><code>is_terminator(opcode) returns true iff opcode is a terminator.</code></li> <li><code>previous_data(pc) returns the immediate data for the instruction before pc (usually a PUSH.)</code></li> <li><code>immediate_size(opcode) returns the size of the immediate data for an opcode.</code></li> <li><code>removed_items(opcode) returns the number of items removed from the data_stack by the opcode.</code></li> <li><code>added_items(opcode) returns the number of items added to the data_stack by the opcode.</code></li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> # returns true iff code is valid</span></span> <span class="giallo-l"><span> int []stack_depths</span></span> <span class="giallo-l"><span> int []max_depths</span></span> <span class="giallo-l"><span> def validate_code(code: bytes, pc: int, sp: int, bp: int, max: int) -&gt; int, boolean:</span></span> <span class="giallo-l"><span> while pc &lt; len(code):</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # check stack height and return if we have been here before</span></span> <span class="giallo-l"><span> stack_depth = sp - bp</span></span> <span class="giallo-l"><span> max_depth = max + stack_depth</span></span> <span class="giallo-l"><span> if max_depth &gt; 1024</span></span> <span class="giallo-l"><span> return max_depth, false</span></span> <span class="giallo-l"><span> if stack_depths[pc] {</span></span> <span class="giallo-l"><span> if stack_depth != stack_depths[pc]:</span></span> <span class="giallo-l"><span> return 0, false</span></span> <span class="giallo-l"><span> if opcode == ENTERSUB:</span></span> <span class="giallo-l"><span> return max_depths[pc], true</span></span> <span class="giallo-l"><span> else</span></span> <span class="giallo-l"><span> return max_depth, true</span></span> <span class="giallo-l"><span> else:</span></span> <span class="giallo-l"><span> stack_depths[pc] = stack_depth</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if is_terminator(opcode):</span></span> <span class="giallo-l"><span> return max_depth, true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> elif opcode == CALLSUB:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # push return address and set pc to destination</span></span> <span class="giallo-l"><span> jumpdest = previous_data(pc)</span></span> <span class="giallo-l"><span> push(return_stack, pc)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # validate and track maximum height</span></span> <span class="giallo-l"><span> max_depth, valid = validate_code(jumpdest, 0, sp - bp, max)</span></span> <span class="giallo-l"><span> if !valid:</span></span> <span class="giallo-l"><span> return max_depth, false</span></span> <span class="giallo-l"><span> max_depths[jumpdest] = max_depth;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> elif opcode == RETURNSUB:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # pop return address and check for preceding call</span></span> <span class="giallo-l"><span> pc = pop(return_stack)</span></span> <span class="giallo-l"><span> max_depth = max + stack_depth</span></span> <span class="giallo-l"><span> return max_depth, true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if opcode == JUMP:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # set pc to destination of jump</span></span> <span class="giallo-l"><span> pc = previous_data(pc)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> elif opcode == JUMPI:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> jumpdest = previous_data(pc)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # recurse to validate true side of conditional</span></span> <span class="giallo-l"><span> max_depth, valid = validate_code(jumpdest, sp, bp)</span></span> <span class="giallo-l"><span> if !valid:</span></span> <span class="giallo-l"><span> return max_depth, false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # apply instructions to stack</span></span> <span class="giallo-l"><span> sp -= removed_items(opcode)</span></span> <span class="giallo-l"><span> if sp &lt; 0</span></span> <span class="giallo-l"><span> return so, false</span></span> <span class="giallo-l"><span> sp += added_items(opcode)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # Skip opcode and any immediate data</span></span> <span class="giallo-l"><span> pc += 1 + immediate_size(opcode)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> max_depth = max + stack_depth</span></span> <span class="giallo-l"><span> if (max_depth &gt; 1024)</span></span> <span class="giallo-l"><span> return max_depth, false</span></span> <span class="giallo-l"><span> return max_depth, true</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>These changes introduce new flow control instructions. They do not introduce any new security considerations. This EIP is intended to improve security by validating a higher level of safety for EVM code deployed on the blockchain. The validation algorithm must use time and space linear in the size of the code so as not be a denial of service vulnerability. The algorithm here makes one linear-time, recursive pass of the bytecode, whose depth cannot exceed the number of <code>CALLSUB</code> and <code>JUMPI</code> instructions in the code.</p> <h2 id="copyright">Copyright</h2> <!-- ``` csl-json { "type": "article", "id": 4, "author": [ { "family": "Schneidewind", "given": "Clara" } ], "DOI": "arXiv:2101.05735", "title": "The Good, the Bad and the Ugly: Pitfalls and Best Practices in Automated Sound Static Analysis of Ethereum Smart Contracts., "original-date": { "date-parts": [ [2021, 1, 14] ] }, "URL": "https://arxiv.org/abs/2101.05735" } ``` ``` csl-json { "type": "article", "id": 5, "author": [ { "family": "Albert", "given": "Elvira" } ], "DOI": "arXiv:2004.14437", "title": "Analyzing Smart Contracts: From EVM to a sound Control-Flow Graph., "original-date": { "date-parts": [ [2020, 4, 29] ] }, "URL": "https://arxiv.org/abs/2004.14437" } ``` ``` csl-json { "type": "article", "id": 6, "author": [ { "family": "Contro", "given": "Filippo" } ], "DOI": "arXiv:2103.09113", "title": "EtherSolve: Computing an Accurate Control-Flow Graph from Ethereum Bytecode.", "original-date": { "date-parts": [ [2021, 3, 16] ] }, "URL": "https://arxiv.org/abs/2103.09113" } ``` ``` csl-json { "type": "article", "id": 7, "author": [ { "family": "He", "given": "Jiahao" } ], "DOI": "arXiv:2301.12695", "title": "Neural-FEBI: Accurate Function Identification in Ethereum Virtual Machine Bytecode.", "original-date": { "date-parts": [ [2023, 1, 30] ] }, "URL": "https://arxiv.org/abs/2301.12695" } ``` --> <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>Menabre, L.F. Sketch of The Analytical Engine Invented by Charles Babbage. Bibliothque Universelle de Genve, No. 82, October 1842 <a href="#fr-1-1">↩</a> <a href="#fr-1-2">↩2</a> <a href="#fr-1-3">↩3</a></p> </li> <li id="fn-3"> <p>Carpenter, B.E. et al. The other Turing machine. The Computer Journal, Volume 20, Issue 3, January 1977 <a href="#fr-3-1">↩</a></p> </li> <li id="fn-2"> <p>Turing, A.M. Computing Machinery and Intelligence. Mind, Volume LIX, Issue 236, October 1950 <a href="#fr-2-1">↩</a></p> </li> <li id="fn-4"> <p>Schneidewind, Clara et al. The Good, the Bad and the Ugly: Pitfalls and Best Practices in Automated Sound Static Analysis of Ethereum Smart Contracts. DOI: 10.48550/arXiv.2101.05735 <a href="#fr-4-1">↩</a></p> </li> <li id="fn-5"> <p>Albert, Elvira et al. Analyzing Smart Contracts: From EVM to a sound Control-Flow Graph. DOI: 10.48550/arXiv.2004.14437 <a href="#fr-5-1">↩</a></p> </li> <li id="fn-6"> <p>Contro, Fillipo et al. EtherSolve: Computing an Accurate Control-Flow Graph from Ethereum Bytecode. DOI: 10.48550/arXiv.2103.09113 <a href="#fr-6-1">↩</a></p> </li> <li id="fn-7"> <p>He, Jiahao et al. Neural-FEBI: Accurate Function Identification in Ethereum Virtual Machine Bytecode. DOI: 10.48550/arxiv.2301.12695" <a href="#fr-7-1">↩</a></p> </li> </ol> </section> 2025-12-16T00:00:00+00:00 2026-02-11T14:48:25+00:00 Andrew Wanghttps://github.com/wz14zhuowangy2k@outlook.com Jack Yinhttps://github.com/0xjackey0xjackey@gmail.com https://wg-eips.ritovision.com/8106/

Event-driven compliance framework for Real World Asset tokens with entity classification and audit events

<h2 id="abstract">Abstract</h2> <p>This standard defines an event-based compliance framework for Real World Asset (RWA) tokens on <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, providing:</p> <ol> <li>A standardized entity classification system distinguishing between Compliance Entities (CE) and Decentralized Entities (DE)</li> <li>Event-driven compliance observation enabling auditability through standardized events and actual value flows, without enforcing hard transaction reverts</li> </ol> <p>This standard is intentionally minimal and does not prescribe business-specific RWA workflows, off-chain settlement mechanisms, minting policies, or specific transfer patterns.</p> <h2 id="motivation">Motivation</h2> <p>Real World Asset tokenization requires compliance observability that existing <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens do not provide:</p> <h3 id="missing-capabilities">Missing Capabilities</h3> <ol> <li><strong>Entity Classification</strong>: No standardized way to distinguish regulated corporate entities from decentralized participants</li> <li><strong>Compliance Observability</strong>: No uniform event semantics for tracking compliance-relevant transfers</li> <li><strong>Flexible Enforcement</strong>: Existing standards use hard reverts, making them incompatible with diverse regulatory frameworks</li> </ol> <h3 id="why-event-based">Why Event-Based?</h3> <p>This standard adopts an event-driven approach rather than enforcement through reverts:</p> <ul> <li><strong>Regulatory Flexibility</strong>: Different jurisdictions can interpret the same events differently</li> <li><strong>Adaptability</strong>: Compliance rules can evolve without contract upgrades</li> <li><strong>Lower Costs</strong>: Events are cheaper than state-based enforcement</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> <h3 id="definitions">Definitions</h3> <ul> <li><strong>Compliance Entity (CE)</strong>: An address representing a regulated legal entity (e.g., corporate treasury, custody account)</li> <li><strong>Decentralized Entity (DE)</strong>: An address representing a decentralized participant (e.g., end users, routers, settlement contracts)</li> <li><strong>BizID</strong>: A business correlation identifier (hash) linking related transfers to a single workflow</li> <li><strong>Soft Policy</strong>: Compliance policy expressed through event labeling, not transaction reversion</li> </ul> <h3 id="entity-registry">Entity Registry</h3> <p>Compliant implementations MUST provide an entity classification registry that assigns each address to one of three categories.</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"> IERC8106EntityRegistry</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> EntityType</span><span> {</span><span class="z-variable z-other z-enummember"> DECENTRALIZED_ENTITY</span><span>,</span><span class="z-variable z-other z-enummember"> COMPLIANCE_ENTITY</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"> EntityTypeUpdated</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"> entity</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> EntityType</span><span class="z-variable"> entityType</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"> reasonHash</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 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"> Returns the entity type of an address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST return DECENTRALIZED_ENTITY for addresses not explicitly registered as COMPLIANCE_ENTITY</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> entityTypeOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> entity</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">EntityType</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="registry-requirements">Registry Requirements</h4> <p>Implementations MUST satisfy the following requirements:</p> <ol> <li><strong>Default Classification</strong>: The <code>entityTypeOf</code> function MUST return <code>DECENTRALIZED_ENTITY</code> for any address not explicitly registered as <code>COMPLIANCE_ENTITY</code></li> <li><strong>Explicit Registration</strong>: Only addresses explicitly registered SHOULD return <code>COMPLIANCE_ENTITY</code></li> <li><strong>Update Events</strong>: Entity type changes MUST emit <code>EntityTypeUpdated</code> events</li> <li><strong>Reason Tracking</strong>: The <code>reasonHash</code> parameter MUST reference off-chain documentation (e.g., KYC records, legal entity registration)</li> <li><strong>Operator Accountability</strong>: The <code>operator</code> parameter MUST identify the address that authorized the update</li> </ol> <h4 id="implementation-note">Implementation Note</h4> <p>The registry MAY be:</p> <ul> <li>Embedded within the token contract itself</li> <li>Implemented as a separate contract referenced by the token</li> <li>Shared across multiple tokens within an ecosystem</li> </ul> <h3 id="compliance-events">Compliance Events</h3> <p>Compliant implementations MUST emit standardized events that capture compliance-relevant transfer information, including entity classifications, compliance flags, and business correlation identifiers.</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"> IERC8106ComplianceEvents</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC8106EntityRegistry</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> ComplianceFlag</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> OK</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> DIRECT_DE_TO_CE</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> DE -&gt; CE observed</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> DIRECT_CE_TO_DE</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> CE -&gt; DE observed</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> POLICY_CUSTOM</span><span class="z-comment"> //</span><span class="z-comment"> project-defined policy</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"> ComplianceObserved</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"> bizId</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"> token</span><span>, </span><span>// </span><span class="z-variable">the</span><span class="z-variable"> ERC</span><span>-</span><span class="z-variable">20</span><span class="z-variable"> token</span><span class="z-variable"> contract</span><span class="z-support"> address</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-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"> EntityType</span><span class="z-variable"> fromType</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> EntityType</span><span class="z-variable"> toType</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> ComplianceFlag</span><span class="z-variable"> flag</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> policyTag</span><span> // </span><span class="z-variable">project</span><span>-</span><span class="z-variable">defined</span><span class="z-variable"> categorization</span><span class="z-variable"> tag</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="event-requirements">Event Requirements</h4> <p>Implementations MUST satisfy the following requirements:</p> <ol> <li><strong>Complete Information</strong>: Each <code>ComplianceObserved</code> event MUST include all specified parameters</li> <li><strong>Accurate Classification</strong>: The <code>fromType</code> and <code>toType</code> MUST reflect the actual entity types at the time of the transfer</li> <li><strong>Consistent BizID</strong>: All legs of a multi-leg transfer MUST use the same <code>bizId</code> value</li> <li><strong>Token Identification</strong>: The <code>token</code> parameter MUST be the address of the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token contract</li> </ol> <h4 id="recommended-flagging-policy-non-normative">Recommended Flagging Policy (Non-normative)</h4> <p>Implementations SHOULD apply the following flagging heuristics:</p> <ul> <li><code>DIRECT_DE_TO_CE</code>: When <code>fromType == DECENTRALIZED_ENTITY</code> and <code>toType == COMPLIANCE_ENTITY</code></li> <li><code>DIRECT_CE_TO_DE</code>: When <code>fromType == COMPLIANCE_ENTITY</code> and <code>toType == DECENTRALIZED_ENTITY</code></li> <li><code>OK</code>: When transfer does not cross compliance boundaries (DE↔DE or CE↔CE)</li> <li><code>POLICY_CUSTOM</code>: For project-specific compliance scenarios</li> </ul> <h4 id="event-based-compliance">Event-Based Compliance</h4> <p>Implementations SHOULD NOT revert transactions solely based on compliance flags. This event-based approach enables:</p> <ul> <li>Off-chain compliance review and decision-making</li> <li>Flexible interpretation across different regulatory jurisdictions</li> <li>Time-delayed enforcement where appropriate (e.g., 24-hour review periods)</li> </ul> <p>Compliance actions (transaction reversals, account freezes, regulatory reporting) SHOULD be handled through separate mechanisms such as:</p> <ul> <li>Off-chain monitoring systems</li> <li>On-chain governance modules</li> <li>Dedicated compliance management contracts</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="event-driven-model">Event-Driven Model</h3> <p>Events rather than reverts because:</p> <ul> <li>Different jurisdictions can interpret events differently</li> <li>Cheaper than state-based enforcement (~2000 gas per event vs state writes)</li> <li>Enables time-delayed enforcement where appropriate</li> </ul> <h3 id="soft-policy-flags">Soft Policy Flags</h3> <p>Compliance flags are informational, not enforced:</p> <ul> <li>Projects decide whether to revert based on flags</li> <li>Off-chain systems can alert, review, or freeze post-transaction</li> <li>Supports evolving regulations without contract changes</li> </ul> <h3 id="auditability-design">Auditability Design</h3> <p>Auditors reconstruct transaction flows using:</p> <ol> <li><strong>Value Flows</strong>: Every <code>ComplianceObserved</code> event corresponds to a real <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> balance change</li> <li><strong>Standardized Events</strong>: Uniform event structure for machine-readable compliance data</li> <li><strong>BizID Correlation</strong>: Link multiple transfers to a single business transaction</li> </ol> <p>For a given <code>bizId</code>, auditors can query all <code>ComplianceObserved</code> events, build directed graphs from <code>from</code>/<code>to</code>/<code>amount</code> fields, check for direct CE/DE transfers using the <code>flag</code> field, and cross-reference <code>reasonHash</code> with off-chain KYC/AML systems.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="implementation-patterns">Implementation Patterns</h3> <p><strong>Embedded Registry</strong>: Store entity types in the token contract itself</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"> RWAToken</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC20</span><span>, </span><span class="z-entity z-name">IERC8106ComplianceEvents</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> _isComplianceEntity</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"> entityTypeOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> entity</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">EntityType</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _isComplianceEntity</span><span>[</span><span>entity</span><span>]</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> ?</span><span> EntityType</span><span>.</span><span>COMPLIANCE_ENTITY </span></span> <span class="giallo-l"><span class="z-keyword"> :</span><span> EntityType</span><span>.</span><span>DECENTRALIZED_ENTITY</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></span></code></pre> <p><strong>Separate Registry</strong>: Share registry across multiple tokens</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"> EntityRegistry</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC8106EntityRegistry</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> _isComplianceEntity</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"> entityTypeOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> entity</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">EntityType</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _isComplianceEntity</span><span>[</span><span>entity</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> ?</span><span> EntityType</span><span>.</span><span>COMPLIANCE_ENTITY</span></span> <span class="giallo-l"><span class="z-keyword"> :</span><span> EntityType</span><span>.</span><span>DECENTRALIZED_ENTITY</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"> registerComplianceEntity</span><span>(</span><span class="z-support">address</span><span class="z-variable"> entity</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> reasonHash</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> _isComplianceEntity</span><span>[</span><span>entity</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> EntityTypeUpdated</span><span>(</span><span>entity</span><span>,</span><span> EntityType</span><span>.</span><span>COMPLIANCE_ENTITY</span><span>,</span><span> reasonHash</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 class="z-comment"> //</span><span class="z-comment"> ...</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>Policy Tag Conventions</strong>: Use consistent hashes for interoperability</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"> constant</span><span> TAG_PAYMENT </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;PAYMENT&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span class="z-storage z-type"> constant</span><span> TAG_TREASURY </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;TREASURY&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span class="z-storage z-type"> constant</span><span> TAG_REFUND </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;REFUND&quot;</span><span>)</span><span>;</span></span></code></pre><h3 id="example-use-cases">Example Use Cases</h3> <p><strong>Compliance Monitoring:</strong> A regulated stablecoin tracks all CE↔DE flows for monthly regulatory reports without blocking transactions.</p> <p><strong>Atomic Multi-Leg Transfers:</strong> While not part of this standard, projects can build on these primitives to implement atomic multi-hop transfers:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> User pays → Treasury → Operational account (single transaction)</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> purchaseRWA</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> orderId</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 class="z-comment"> //</span><span class="z-comment"> Leg 1: DE → CE</span></span> <span class="giallo-l"><span> token</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> treasury</span><span>,</span><span> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ComplianceObserved</span><span>(</span><span>orderId</span><span>,</span><span> token</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span> treasury</span><span>,</span><span> amount</span><span>,</span><span> </span></span> <span class="giallo-l"><span> DE</span><span>,</span><span> CE</span><span>,</span><span> DIRECT_DE_TO_CE</span><span>,</span><span> TAG_PAYMENT</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"> Leg 2: CE → CE</span></span> <span class="giallo-l"><span> token</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span>treasury</span><span>,</span><span> operational</span><span>,</span><span> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ComplianceObserved</span><span>(</span><span>orderId</span><span>,</span><span> token</span><span>,</span><span> treasury</span><span>,</span><span> operational</span><span>,</span><span> amount</span><span>,</span></span> <span class="giallo-l"><span> CE</span><span>,</span><span> CE</span><span>,</span><span> OK</span><span>,</span><span> TAG_TREASURY</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This pattern enables single user-facing transactions, unified <code>bizId</code> for audit correlation, and per-leg compliance events.</p> <p><strong>Time-Delayed Enforcement:</strong> Detect suspicious patterns in events, then freeze accounts off-chain or via governance after review.</p> <h2 id="security-considerations">Security Considerations</h2> <p><strong>Event Integrity:</strong> Implementations MUST emit <code>ComplianceObserved</code> events only after actual <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> balance changes. Emitting events without value movement compromises auditability.</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-12-16T00:00:00+00:00 2026-02-11T14:48:25+00:00 Kwame Bryanhttps://github.com/KBryan https://wg-eips.ritovision.com/8107/

Web of trust validation using ENS names for ERC-8001 multi-party coordination

<h2 id="abstract">Abstract</h2> <p>This ERC defines a <strong>Trust Registry</strong> that enables agents to establish and query transitive trust relationships using ENS names as identifiers. Trust is expressed at four levels (Unknown, None, Marginal, Full) and propagates through signature chains following the GNU Privacy Guard (GnuPG) web of trust model.</p> <p>The registry serves as the <strong>trust and delegation module</strong> anticipated by <a href="https://wg-eips.ritovision.com/8001/">ERC-8001</a>, enabling coordinators to gate participation based on trust graph proximity. An agent is considered valid from a coordinator's perspective if sufficient trust paths exist between them.</p> <p>This standard specifies trust attestation structures, the path verification algorithm, ENS integration semantics, and <a href="https://wg-eips.ritovision.com/8001/">ERC-8001</a> coordination hooks.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/8001/">ERC-8001</a> defines minimal primitives for multi-party agent coordination but explicitly defers trust to modules:</p> <blockquote> <p>"Privacy, thresholds, bonding, and cross-chain are left to modules."</p> </blockquote> <p>And in Security Considerations:</p> <blockquote> <p>"Equivocation: A participant can sign conflicting intents. Mitigate with module-level slashing or reputation."</p> </blockquote> <p>This ERC provides that trust and delegation module. Before coordinating, agents need answers to:</p> <ol> <li><strong>"Should I include this agent in my coordination?"</strong> — Participant selection</li> <li><strong>"Can I trust this agent's judgment about other agents?"</strong> — Transitive trust</li> <li><strong>"How do I update trust based on coordination outcomes?"</strong> — Trust maintenance</li> </ol> <h3 id="why-web-of-trust">Why Web of Trust?</h3> <p>The web of trust model, proven over 25+ years in GnuPG, solves the bootstrap problem: how do you establish trust with unknown agents without a centralised registrar?</p> <table><thead><tr><th>GnuPG Concept</th><th>This Standard</th></tr></thead><tbody> <tr><td>Public key</td><td>ENS name</td></tr> <tr><td>Key signing</td><td>Trust attestation</td></tr> <tr><td>Owner trust levels</td><td><code>TrustLevel</code> enum</td></tr> <tr><td>Key validity</td><td>Agent validity for coordination</td></tr> <tr><td>Certification path</td><td>Trust chain through agents</td></tr> </tbody></table> <h3 id="why-ens">Why ENS?</h3> <p>ENS provides a battle-tested, finalized identity layer:</p> <ul> <li><strong>Stable identifiers</strong> that survive key rotation</li> <li><strong>Ownership semantics</strong> via <code>owner()</code> and <code>isApprovedForAll()</code></li> <li><strong>Human readable</strong> names (<code>alice.agents.eth</code> not <code>0x742d...</code>)</li> <li><strong>Subdomain delegation</strong> for protocol-issued agent identities</li> </ul> <p>Using ENS avoids dependency on draft identity standards while remaining compatible with future standards through adapter patterns.</p> <p><strong>Deployment note</strong>: This standard requires access to an ENS registry. On Ethereum mainnet, use the canonical ENS deployment. On other networks, use network-specific ENS deployments or bridges. CCIP-Read is a client-side mechanism and cannot be used for on-chain validation.</p> <h3 id="identity-continuity">Identity Continuity</h3> <p>ENS names are the identity. When an ENS name is transferred, the new owner inherits existing trust relationships where that name is the trustee. The new owner can manage trust where they are the trustor.</p> <p>Implementations SHOULD use short expiries (RECOMMENDED: 90 days maximum) for high-stakes scopes to limit exposure from name transfers. Agents SHOULD monitor <code>Transfer</code> events on ENS names they trust and re-evaluate trust accordingly.</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="overview">Overview</h3> <p>This ERC specifies:</p> <ul> <li>Trust levels and their semantics</li> <li>ENS-indexed trust attestation structures with scope as key</li> <li><a href="https://wg-eips.ritovision.com/712/">EIP-712</a> typed data for signing attestations</li> <li><a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a> support for contract controllers</li> <li>The <code>ITrustRegistry</code> interface</li> <li>Path verification algorithm</li> <li><a href="https://wg-eips.ritovision.com/8001/">ERC-8001</a> integration hooks</li> </ul> <h3 id="trust-levels">Trust Levels</h3> <p>Implementations MUST use the canonical enum:</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"> TrustLevel</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Unknown</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> 0: No trust relationship established</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> None</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> 1: Explicitly distrusted</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Marginal</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> 2: Partial trust — multiple required for validation</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Full</span><span class="z-comment"> //</span><span class="z-comment"> 3: Complete trust — single attestation sufficient</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>Semantic definitions:</strong></p> <table><thead><tr><th>Level</th><th>Meaning</th><th>Validation Contribution</th></tr></thead><tbody> <tr><td><code>Unknown</code></td><td>Default state; no data about agent</td><td>Cannot contribute to validation</td></tr> <tr><td><code>None</code></td><td>Agent known to behave improperly</td><td>Explicitly excluded; voids trust paths containing this agent</td></tr> <tr><td><code>Marginal</code></td><td>Agent generally trustworthy</td><td>Contributes to validation when <code>minEdgeTrust &lt;= Marginal</code></td></tr> <tr><td><code>Full</code></td><td>Agent's judgment equals own verification</td><td>Always contributes to validation</td></tr> </tbody></table> <p><strong>Level transitions:</strong></p> <ul> <li>Any level MAY transition to any other level via a valid attestation with a higher nonce</li> <li>Transitioning from <code>None</code> to <code>Marginal</code> or <code>Full</code> requires a new attestation (revocation is not permanent)</li> </ul> <h3 id="ens-integration">ENS Integration</h3> <p>The Trust Registry uses ENS namehashes as agent identifiers.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ENS namehash computation (per ERC-137)</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span> node </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> <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 class="z-support">bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;eth&quot;</span><span>)</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;alice&quot;</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> node = namehash(&quot;alice.eth&quot;)</span></span></code></pre><h3 id="signature-authority">Signature Authority</h3> <p>Trust attestations MUST be signed by an address with signing authority for the ENS name.</p> <p><strong>Signing authority</strong> is limited to:</p> <ul> <li>The ENS name owner (<code>ens.owner(node)</code>), OR</li> <li>For contract owners: any signer the contract validates via <a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a></li> </ul> <p><strong>Transaction submission</strong> (calling <code>setTrust</code>, <code>revokeTrust</code>, etc.) MAY be performed by:</p> <ul> <li>Any address holding a valid signature</li> <li>An approved operator (<code>ens.isApprovedForAll(owner, operator)</code>) for <code>revokeTrust</code> only</li> </ul> <p>This separation ensures:</p> <ul> <li>Attestations are cryptographically bound to the ENS owner/controller</li> <li>Transaction submission can be delegated (relayers, operators)</li> <li>Approvals cannot be used to forge signatures</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"> @dev</span><span class="z-comment"> Verify signature - signing authority is ENS owner only</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifySignature</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> node</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> digest</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"> signature</span></span> <span class="giallo-l"><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"> address</span><span> owner </span><span class="z-keyword">=</span><span> ens</span><span>.</span><span class="z-entity z-name">owner</span><span>(</span><span>node</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>owner </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 class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> EOA owner</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>owner</span><span>.</span><span>code</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> 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 class="z-keyword"> ==</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"> Contract owner - delegate to EIP-1271</span></span> <span class="giallo-l"><span class="z-keyword"> try</span><span class="z-entity z-name"> IERC1271</span><span>(</span><span>owner</span><span>)</span><span>.</span><span class="z-entity z-name">isValidSignature</span><span>(</span><span>digest</span><span>,</span><span> signature</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes4</span><span class="z-variable"> magic</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> magic </span><span class="z-keyword">==</span><span> IERC1271</span><span>.</span><span>isValidSignature</span><span>.</span><span>selector</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 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 class="z-storage z-type"> @dev</span><span class="z-comment"> Check if caller can submit revokeTrust transaction</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canSubmitRevocation</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"> caller</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"> address</span><span> owner </span><span class="z-keyword">=</span><span> ens</span><span>.</span><span class="z-entity z-name">owner</span><span>(</span><span>node</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> caller </span><span class="z-keyword">==</span><span> owner </span><span class="z-keyword">||</span><span> ens</span><span>.</span><span class="z-entity z-name">isApprovedForAll</span><span>(</span><span>owner</span><span>,</span><span> caller</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h3 id="eip-712-domain">EIP-712 Domain</h3> <p>Implementations MUST use the following <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> domain:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name">EIP712Domain</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> name</span><span class="z-keyword">:</span><span class="z-string"> &quot;TrustRegistry&quot;</span><span>,</span></span> <span class="giallo-l"><span> version</span><span class="z-keyword">:</span><span class="z-string"> &quot;1&quot;</span><span>,</span></span> <span class="giallo-l"><span> chainId</span><span class="z-keyword">:</span><span class="z-variable z-language"> block</span><span>.</span><span>chainid</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></span></code></pre> <p>Implementations SHOULD expose the domain via <a href="https://wg-eips.ritovision.com/5267/">EIP-5267</a>.</p> <h3 id="primary-types">Primary Types</h3> <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"> TrustAttestation</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> trustorNode</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> ENS namehash of trustor</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> trusteeNode</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> ENS namehash of trustee</span></span> <span class="giallo-l"><span> TrustLevel level</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Trust level assigned</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> scope</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Scope restriction; bytes32(0) = universal</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> expiry</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Unix timestamp; 0 = no expiry</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> nonce</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Per-trustor monotonic nonce</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"> ValidationParams</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> maxPathLength</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Maximum trust chain depth (1-10)</span></span> <span class="giallo-l"><span> TrustLevel minEdgeTrust</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Minimum trust level required on each edge</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> scope</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Required scope; bytes32(0) = any</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> enforceExpiry</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Check expiry on all chain elements</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span> requiredAnchors</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Path MUST traverse at least one anchor; empty = no requirement</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"> TrustPath</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span> nodes</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> [validator, ...intermediaries..., target]</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <p><strong>Path length definition</strong>: Path length is the number of edges (trust relationships) in the path. A direct trust relationship has path length 1. A path <code>[A, B, C]</code> has length 2.</p> <h4 id="default-validation-parameters">Default Validation Parameters</h4> <p>When not specified, implementations SHOULD use:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name">ValidationParams</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> maxPathLength</span><span class="z-keyword">:</span><span class="z-constant"> 5</span><span>,</span></span> <span class="giallo-l"><span> minEdgeTrust</span><span class="z-keyword">:</span><span> TrustLevel</span><span>.</span><span>Marginal</span><span>,</span></span> <span class="giallo-l"><span> scope</span><span class="z-keyword">:</span><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> enforceExpiry</span><span class="z-keyword">:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span> requiredAnchors</span><span class="z-keyword">:</span><span class="z-keyword"> new</span><span class="z-support"> bytes32</span><span>[](</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre><h4 id="validation-parameters-constraints">Validation Parameters Constraints</h4> <p>Implementations MUST reject <code>ValidationParams</code> where:</p> <ul> <li><code>maxPathLength == 0</code> or <code>maxPathLength &gt; 10</code></li> <li><code>minEdgeTrust == TrustLevel.Unknown</code> or <code>minEdgeTrust == TrustLevel.None</code></li> <li><code>requiredAnchors.length &gt; 10</code></li> </ul> <h3 id="typed-data-hashes">Typed Data Hashes</h3> <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"> constant</span><span> TRUST_ATTESTATION_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;TrustAttestation(bytes32 trustorNode,bytes32 trusteeNode,uint8 level,bytes32 scope,uint64 expiry,uint64 nonce)&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"> hashAttestation</span><span>(</span><span class="z-storage z-type">TrustAttestation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> att</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> <span class="giallo-l"><span> TRUST_ATTESTATION_TYPEHASH</span><span>,</span></span> <span class="giallo-l"><span> att</span><span>.</span><span>trustorNode</span><span>,</span></span> <span class="giallo-l"><span> att</span><span>.</span><span>trusteeNode</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span>(</span><span>att</span><span>.</span><span>level</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> att</span><span>.</span><span>scope</span><span>,</span></span> <span class="giallo-l"><span> att</span><span>.</span><span>expiry</span><span>,</span></span> <span class="giallo-l"><span> att</span><span>.</span><span>nonce</span></span> <span class="giallo-l"><span> )</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h3 id="interface">Interface</h3> <p>Implementations MUST expose 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"> ITrustRegistry</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"> //</span><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"> Emitted when trust is set or updated</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TrustSet</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"> trustorNode</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"> trusteeNode</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> TrustLevel</span><span class="z-variable"> level</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"> scope</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> expiry</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"> Emitted when trust is explicitly revoked</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TrustRevoked</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"> trustorNode</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"> trusteeNode</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"> scope</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> reasonCode</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"> Emitted when an identity gate is configured</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdentityGateSet</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"> coordinationType</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"> gatekeeperNode</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> maxPathLength</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> TrustLevel</span><span class="z-variable"> minEdgeTrust</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"> Emitted when an identity gate is removed</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdentityGateRemoved</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> coordinationType</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"> //</span><span class="z-comment"> Trust Management</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"> Set trust level for another agent in a specific scope</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Signature MUST be from ENS owner (EOA) or validate via EIP-1271 (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"> attestation</span><span class="z-comment"> The trust attestation</span></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"> EIP-712 signature from trustor&#39;s ENS owner</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setTrust</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> TrustAttestation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> attestation</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"> signature</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-storage z-type"> @notice</span><span class="z-comment"> Batch set multiple trust relationships</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> All attestations MUST share the same trustorNode</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> attestations</span><span class="z-comment"> Array of trust attestations</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> signatures</span><span class="z-comment"> Corresponding signatures</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setTrustBatch</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> TrustAttestation</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> attestations</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> signatures</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-storage z-type"> @notice</span><span class="z-comment"> Revoke trust (sets level to None)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Caller MUST be ENS owner or approved 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"> trustorNode</span><span class="z-comment"> The trustor&#39;s ENS namehash</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> trusteeNode</span><span class="z-comment"> The agent to revoke trust from</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> scope</span><span class="z-comment"> The scope to revoke trust in</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> reasonCode</span><span class="z-comment"> Reason code for revocation</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeTrust</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> trustorNode</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> trusteeNode</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> scope</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> reasonCode</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-storage z-type"> @notice</span><span class="z-comment"> Get trust record between two agents in a specific scope</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> trustorNode</span><span class="z-comment"> The trusting agent</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> trusteeNode</span><span class="z-comment"> The trusted agent</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> scope</span><span class="z-comment"> The trust scope (bytes32(0) for universal)</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"> level</span><span class="z-comment"> Current trust level</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"> expiry</span><span class="z-comment"> Expiration timestamp (0 = never)</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTrust</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> trustorNode</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> trusteeNode</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> scope</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-storage z-type">TrustLevel</span><span class="z-variable"> level</span><span>,</span><span class="z-support"> uint64</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-storage z-type"> @notice</span><span class="z-comment"> Get current nonce for a trustor</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> trustorNode</span><span class="z-comment"> The agent&#39;s ENS namehash</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"> Current</span><span class="z-comment"> nonce value</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getNonce</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> trustorNode</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-comment"> ═══════════════════════════════════════════════════════════════════</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Path Verification</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"> Verify a pre-computed trust path</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> path</span><span class="z-comment"> The trust path to verify</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> params</span><span class="z-comment"> Validation parameters</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"> valid</span><span class="z-comment"> Whether the path satisfies validation requirements</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"> anchorSatisfied</span><span class="z-comment"> Whether requiredAnchors constraint is met</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyPath</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> TrustPath</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> path</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> ValidationParams</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> params</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 class="z-variable"> valid</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> anchorSatisfied</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"> //</span><span class="z-comment"> ERC-8001 Integration</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"> Set identity gate for a coordination type</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> coordinationType</span><span class="z-comment"> The ERC-8001 coordination type</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> gatekeeperNode</span><span class="z-comment"> Agent whose trust graph gates entry</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> params</span><span class="z-comment"> Validation parameters for the gate</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setIdentityGate</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> coordinationType</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> gatekeeperNode</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> ValidationParams</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> params</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-storage z-type"> @notice</span><span class="z-comment"> Remove identity gate for a coordination type</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> coordinationType</span><span class="z-comment"> The ERC-8001 coordination type</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeIdentityGate</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> coordinationType</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 identity gate configuration</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> coordinationType</span><span class="z-comment"> The ERC-8001 coordination type</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"> gatekeeperNode</span><span class="z-comment"> The gatekeeper agent</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"> params</span><span class="z-comment"> Validation parameters</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"> enabled</span><span class="z-comment"> Whether the gate is active</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getIdentityGate</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> coordinationType</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"> bytes32</span><span class="z-variable"> gatekeeperNode</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> ValidationParams</span><span class="z-storage z-type"> memory</span><span class="z-variable"> params</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> enabled</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"> Validate participant using pre-computed path</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> coordinationType</span><span class="z-comment"> The ERC-8001 coordination type</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> path</span><span class="z-comment"> Pre-computed trust path from gatekeeper to 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"> isValid</span><span class="z-comment"> Whether participant passes the gate</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> validateParticipantWithPath</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> coordinationType</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> TrustPath</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> path</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 class="z-variable"> isValid</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="optional-interface-extensions">OPTIONAL Interface Extensions</h3> <p>The following functions are OPTIONAL. Implementations MAY include them but they are not required for compliance:</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"> ITrustRegistryExtended</span><span class="z-storage"> is</span><span class="z-entity z-name"> ITrustRegistry</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 agents trusted by a given agent (paginated)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> OPTIONAL - useful for indexing but not required</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTrustees</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> trustorNode</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> TrustLevel</span><span class="z-variable"> minLevel</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> scope</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> offset</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> limit</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">bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> trustees</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> total</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 agents that trust a given agent (paginated)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> OPTIONAL - useful for indexing but not required</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTrustors</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> trusteeNode</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> TrustLevel</span><span class="z-variable"> minLevel</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> scope</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> offset</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> limit</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">bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> trustors</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> total</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"> Validate an agent through on-chain graph traversal</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> OPTIONAL - expensive, prefer off-chain computation with verifyPath</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> validatorNode</span><span class="z-comment"> The validating agent&#39;s perspective</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> targetNode</span><span class="z-comment"> The agent 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"> params</span><span class="z-comment"> Validation parameters</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> marginalThreshold</span><span class="z-comment"> Number of marginal attestations required (for accumulation)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> fullThreshold</span><span class="z-comment"> Number of full attestations required</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> validateAgent</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> validatorNode</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> targetNode</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> ValidationParams</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> params</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> marginalThreshold</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> fullThreshold</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"> isValid</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> pathLength</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> marginalCount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> fullCount</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"> Check if any trust path exists</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> OPTIONAL - expensive, prefer off-chain computation</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> pathExists</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> fromNode</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> toNode</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> maxDepth</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 class="z-variable"> exists</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> depth</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"> Validate participant without pre-computed path</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> OPTIONAL - expensive, prefer validateParticipantWithPath</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> validateParticipant</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> coordinationType</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> participantNode</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> marginalThreshold</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> fullThreshold</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 class="z-variable"> isValid</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="semantics">Semantics</h3> <h4 id="settrust"><code>setTrust</code></h4> <p><code>setTrust</code> MUST revert if:</p> <ul> <li><code>attestation.trustorNode == attestation.trusteeNode</code> (self-trust prohibited)</li> <li><code>attestation.nonce &lt;= getNonce(attestation.trustorNode)</code></li> <li><code>attestation.expiry != 0 &amp;&amp; attestation.expiry &lt;= block.timestamp</code></li> <li>The signature does not verify per the Signature Authority section</li> <li>The ENS name for <code>trustorNode</code> does not exist (owner is zero address)</li> </ul> <p>If valid:</p> <ul> <li>The trust record MUST be stored, keyed by <code>(trustorNode, trusteeNode, scope)</code></li> <li><code>getNonce(trustorNode)</code> MUST return the attestation's nonce</li> <li><code>TrustSet</code> MUST be emitted</li> </ul> <h4 id="settrustbatch"><code>setTrustBatch</code></h4> <p><code>setTrustBatch</code> MUST revert if:</p> <ul> <li><code>attestations.length != signatures.length</code></li> <li>Any attestation has a different <code>trustorNode</code> than the first attestation</li> <li>Any individual attestation would fail <code>setTrust</code> validation</li> </ul> <p>Nonces within the batch MUST be strictly increasing.</p> <h4 id="revoketrust"><code>revokeTrust</code></h4> <p><code>revokeTrust</code> MUST revert if:</p> <ul> <li>Caller is not the ENS owner or an approved operator for <code>trustorNode</code></li> <li>No existing trust relationship exists for <code>(trustorNode, trusteeNode, scope)</code> (level is <code>Unknown</code>)</li> </ul> <p>If valid:</p> <ul> <li>Trust level MUST be set to <code>None</code></li> <li><code>TrustRevoked</code> MUST be emitted</li> <li>The relationship MUST remain in storage (not deleted) to preserve the explicit distrust</li> </ul> <h4 id="verifypath-path-verification-algorithm"><code>verifyPath</code> — Path Verification Algorithm</h4> <p><code>verifyPath</code> validates a pre-computed trust path.</p> <p><strong>Algorithm:</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"> verifyPath</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> TrustPath</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> path</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> ValidationParams</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> params</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 class="z-variable"> valid</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> anchorSatisfied</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Path must have at least 2 nodes (validator and target)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>path</span><span>.</span><span>nodes</span><span>.</span><span>length </span><span class="z-keyword">&lt;</span><span class="z-constant"> 2</span><span>)</span><span class="z-keyword"> return</span><span> (</span><span class="z-constant">false</span><span>,</span><span class="z-constant"> false</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Path length constraint (edges = nodes - 1)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>path</span><span>.</span><span>nodes</span><span>.</span><span>length </span><span class="z-keyword">-</span><span class="z-constant"> 1</span><span class="z-keyword"> &gt;</span><span> params</span><span>.</span><span>maxPathLength</span><span>)</span><span class="z-keyword"> return</span><span> (</span><span class="z-constant">false</span><span>,</span><span class="z-constant"> false</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Track anchor satisfaction</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> foundAnchor </span><span class="z-keyword">=</span><span> params</span><span>.</span><span>requiredAnchors</span><span>.</span><span>length </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"> Verify each edge</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> path</span><span>.</span><span>nodes</span><span>.</span><span>length </span><span class="z-keyword">-</span><span class="z-constant"> 1</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"> Try scoped trust first, fall back to universal</span></span> <span class="giallo-l"><span> (</span><span>TrustLevel level</span><span>,</span><span class="z-support"> uint64</span><span> expiry</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> getTrust</span><span>(</span></span> <span class="giallo-l"><span> path</span><span>.</span><span>nodes</span><span>[</span><span>i</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> path</span><span>.</span><span>nodes</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> params</span><span>.</span><span>scope</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"> Fall back to universal scope if scoped trust not found</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>level </span><span class="z-keyword">==</span><span> TrustLevel</span><span>.</span><span>Unknown </span><span class="z-keyword">&amp;&amp;</span><span> params</span><span>.</span><span>scope </span><span class="z-keyword">!=</span><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> (</span><span>level</span><span>,</span><span> expiry</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> getTrust</span><span>(</span></span> <span class="giallo-l"><span> path</span><span>.</span><span>nodes</span><span>[</span><span>i</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> path</span><span>.</span><span>nodes</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-support"> bytes32</span><span>(</span><span class="z-constant">0</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-comment"> //</span><span class="z-comment"> Edge must meet minimum trust level</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>level </span><span class="z-keyword">&lt;</span><span> params</span><span>.</span><span>minEdgeTrust</span><span>)</span><span class="z-keyword"> return</span><span> (</span><span class="z-constant">false</span><span>,</span><span> foundAnchor</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> None explicitly voids (even if minEdgeTrust is somehow None)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>level </span><span class="z-keyword">==</span><span> TrustLevel</span><span>.</span><span>None</span><span>)</span><span class="z-keyword"> return</span><span> (</span><span class="z-constant">false</span><span>,</span><span> foundAnchor</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Expiry check</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>params</span><span>.</span><span>enforceExpiry </span><span class="z-keyword">&amp;&amp;</span><span> expiry </span><span class="z-keyword">!=</span><span class="z-constant"> 0</span><span class="z-keyword"> &amp;&amp;</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></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-constant">false</span><span>,</span><span> foundAnchor</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"> Anchor check (intermediate nodes only, not first or last)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>foundAnchor </span><span class="z-keyword">&amp;&amp;</span><span> i </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"> for</span><span> (</span><span class="z-support">uint256</span><span> j </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> j </span><span class="z-keyword">&lt;</span><span> params</span><span>.</span><span>requiredAnchors</span><span>.</span><span>length</span><span>;</span><span> j</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>path</span><span>.</span><span>nodes</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> ==</span><span> params</span><span>.</span><span>requiredAnchors</span><span>[</span><span>j</span><span>]</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> foundAnchor </span><span class="z-keyword">=</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><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></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-constant">true</span><span>,</span><span> foundAnchor</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>Scope fallback semantics:</strong></p> <p>When validating an edge, implementations MUST:</p> <ol> <li>First check for trust at the specified <code>params.scope</code></li> <li>If not found and <code>params.scope != bytes32(0)</code>, check for trust at universal scope <code>bytes32(0)</code></li> <li>Universal trust applies to all scopes</li> </ol> <h4 id="validateparticipantwithpath"><code>validateParticipantWithPath</code></h4> <p>This function gates <a href="https://wg-eips.ritovision.com/8001/">ERC-8001</a> coordination participation.</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"> validateParticipantWithPath</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> coordinationType</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> TrustPath</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> path</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 class="z-variable"> isValid</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bytes32</span><span> gatekeeperNode</span><span>,</span><span> ValidationParams </span><span class="z-storage z-type">memory</span><span> params</span><span>,</span><span class="z-support"> bool</span><span> enabled</span><span>)</span><span class="z-keyword"> =</span></span> <span class="giallo-l"><span class="z-entity z-name"> getIdentityGate</span><span>(</span><span>coordinationType</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>enabled</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> No gate = open participation</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Verify path starts at gatekeeper and ends at participant</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>path</span><span>.</span><span>nodes</span><span>.</span><span>length </span><span class="z-keyword">&lt;</span><span class="z-constant"> 2</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>path</span><span>.</span><span>nodes</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> !=</span><span> gatekeeperNode</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> (</span><span class="z-support">bool</span><span> valid</span><span>,</span><span class="z-support"> bool</span><span> anchorOk</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> verifyPath</span><span>(</span><span>path</span><span>,</span><span> params</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> valid </span><span class="z-keyword">&amp;&amp;</span><span> anchorOk</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="errors">Errors</h3> <p>Implementations MUST revert with these errors:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> SelfTrustProhibited</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> NonceTooLow</span><span>(</span><span class="z-support">uint64</span><span> provided</span><span>,</span><span class="z-support"> uint64</span><span> required</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> AttestationExpired</span><span>(</span><span class="z-support">uint64</span><span> expiry</span><span>,</span><span class="z-support"> uint64</span><span> currentTime</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> InvalidSignature</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> NotAuthorized</span><span>(</span><span class="z-support">bytes32</span><span> node</span><span>,</span><span class="z-support"> address</span><span> actor</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ENSNameNotFound</span><span>(</span><span class="z-support">bytes32</span><span> node</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> TrustNotFound</span><span>(</span><span class="z-support">bytes32</span><span> trustorNode</span><span>,</span><span class="z-support"> bytes32</span><span> trusteeNode</span><span>,</span><span class="z-support"> bytes32</span><span> scope</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> GateNotFound</span><span>(</span><span class="z-support">bytes32</span><span> coordinationType</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> InvalidValidationParams</span><span>(</span><span class="z-support">string</span><span> reason</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> BatchTrustorMismatch</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> BatchNonceNotIncreasing</span><span>(</span><span>)</span><span>;</span></span></code></pre><h3 id="recommended-reason-codes">Recommended Reason Codes</h3> <p>For <code>TrustRevoked</code> events, the following reason codes are RECOMMENDED:</p> <table><thead><tr><th>Reason Code</th><th>Value</th><th>Meaning</th></tr></thead><tbody> <tr><td>Unspecified</td><td><code>bytes32(0)</code></td><td>No specific reason</td></tr> <tr><td>Misbehavior</td><td><code>keccak256("MISBEHAVIOR")</code></td><td>Agent acted improperly</td></tr> <tr><td>Compromised</td><td><code>keccak256("COMPROMISED")</code></td><td>Key or account compromised</td></tr> <tr><td>Inactive</td><td><code>keccak256("INACTIVE")</code></td><td>Agent no longer active</td></tr> <tr><td>Transfer</td><td><code>keccak256("TRANSFER")</code></td><td>ENS name transferred</td></tr> </tbody></table> <h3 id="recommended-scopes">Recommended Scopes</h3> <p>For interoperability, the following scope values are RECOMMENDED:</p> <table><thead><tr><th>Scope</th><th>Value</th><th>Use Case</th></tr></thead><tbody> <tr><td>Universal</td><td><code>bytes32(0)</code></td><td>Trust applies to all contexts</td></tr> <tr><td>DeFi</td><td><code>keccak256("DEFI")</code></td><td>DeFi coordination</td></tr> <tr><td>Gaming</td><td><code>keccak256("GAMING")</code></td><td>Gaming/metaverse</td></tr> <tr><td>MEV</td><td><code>keccak256("MEV")</code></td><td>MEV protection</td></tr> <tr><td>Commerce</td><td><code>keccak256("COMMERCE")</code></td><td>Agentic commerce</td></tr> </tbody></table> <h3 id="recommended-coordination-types">Recommended Coordination Types</h3> <p>For <a href="https://wg-eips.ritovision.com/8001/">ERC-8001</a> identity gates:</p> <table><thead><tr><th>Coordination Type</th><th>Value</th></tr></thead><tbody> <tr><td>MEV Coordination</td><td><code>keccak256("MEV_COORDINATION")</code></td></tr> <tr><td>DeFi Yield</td><td><code>keccak256("DEFI_YIELD")</code></td></tr> <tr><td>Gaming Match</td><td><code>keccak256("GAMING_MATCH")</code></td></tr> <tr><td>Commerce Escrow</td><td><code>keccak256("COMMERCE_ESCROW")</code></td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <h3 id="why-ens-instead-of-a-new-identity-system">Why ENS Instead of a New Identity System?</h3> <p>ENS is finalised <a href="https://wg-eips.ritovision.com/137/">EIP-137</a>, battle-tested, and widely adopted. Creating a new identity system would:</p> <ul> <li>Add dependency on draft standards</li> <li>Fragment the identity ecosystem</li> <li>Require new adoption efforts</li> </ul> <p>ENS provides everything needed: stable identifiers, ownership semantics, and extensibility.</p> <h3 id="why-scope-as-storage-key">Why Scope as Storage Key?</h3> <p>A trustor may have different trust levels for the same trustee in different contexts. For example:</p> <ul> <li>Trust <code>bob.eth</code> fully for DeFi coordination</li> <li>Trust <code>bob.eth</code> marginally for gaming</li> </ul> <p>Making scope part of the storage key <code>(trustorNode, trusteeNode, scope)</code> enables this naturally. Universal trust <code>bytes32(0)</code> serves as a fallback when scoped trust is not specified.</p> <h3 id="why-minedgetrust-instead-of-marginal-full-thresholds">Why minEdgeTrust Instead of Marginal/Full Thresholds?</h3> <p>The <code>marginalThreshold</code> and <code>fullThreshold</code> parameters were designed for on-chain graph traversal with marginal accumulation logic. Since on-chain traversal is OPTIONAL (expensive, DoS-prone), and the core primitive is <code>verifyPath</code>, we need only specify the minimum trust level each edge must have.</p> <p>This simplification:</p> <ul> <li>Reduces parameter complexity</li> <li>Makes path verification straightforward</li> <li>Leaves accumulation semantics to OPTIONAL extensions</li> </ul> <p>For use cases requiring marginal accumulation, the OPTIONAL <code>validateAgent</code> extension accepts threshold parameters.</p> <h3 id="why-separate-signing-authority-from-transaction-submission">Why Separate Signing Authority from Transaction Submission?</h3> <p>ENS approvals (<code>isApprovedForAll</code>) are designed for operators to manage names on behalf of owners. However, allowing approved operators to forge attestation signatures would break the cryptographic binding between attestations and ENS owners.</p> <p>By restricting signing authority to the ENS owner (or EIP-1271 for contract owners) while allowing operators to submit transactions like <code>revokeTrust</code>, we preserve:</p> <ul> <li>Cryptographic integrity of attestations</li> <li>Operational flexibility for name management</li> <li>Clear security boundaries</li> </ul> <h3 id="why-verifypath-only-no-on-chain-search">Why verifyPath Only (No On-Chain Search)?</h3> <p>On-chain graph traversal is expensive and creates DoS vectors:</p> <ul> <li>Branching factor can explode with user-controlled adjacency lists</li> <li>Gas costs are unpredictable</li> <li>Attackers can bloat trustee lists</li> </ul> <p>By requiring pre-computed paths, this standard:</p> <ul> <li>Keeps on-chain verification O(path length)</li> <li>Pushes search complexity to off-chain indexers where it belongs</li> <li>Enables predictable gas costs</li> </ul> <p>Implementations MAY add <code>validateAgent</code> and <code>pathExists</code> as OPTIONAL extensions, but these are not required for compliance.</p> <h3 id="why-four-trust-levels">Why Four Trust Levels?</h3> <p>The four-level model (Unknown, None, Marginal, Full) is proven by GnuPG's 25+ years of use. Finer granularity adds complexity without clear benefit; coarser granularity loses important distinctions.</p> <p>With <code>minEdgeTrust</code>, applications can choose their security posture:</p> <ul> <li><code>minEdgeTrust: Full</code> — Only fully trusted paths</li> <li><code>minEdgeTrust: Marginal</code> — Accept marginal trust (default)</li> </ul> <h3 id="why-required-anchors">Why Required Anchors?</h3> <p>Sybil attacks are the primary threat to web of trust systems. Required anchors force trust paths to traverse established community nodes (DAOs, protocols, auditors), transforming Sybil resistance from application-layer advice into protocol-level enforcement.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC introduces new functionality and does not modify existing standards.</p> <p><strong>ENS Compatibility</strong>: Uses standard ENS interfaces (<code>owner</code>, <code>isApprovedForAll</code>). Works with any ENS deployment. Does not rely on CCIP-Read or other off-chain mechanisms.</p> <p><strong>ERC-8001 Compatibility</strong>: Designed as a module. ERC-8001 coordinators can optionally integrate identity gates.</p> <p><strong>Wallet Compatibility</strong>: Uses <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> signatures, compatible with all major wallets. Supports <a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a> for contract wallets and smart accounts.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/8107/./assets/contracts/TrustRegistry.sol"><code>contracts/TrustRegistry.sol</code></a> for the complete implementation.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="sybil-attacks">Sybil Attacks</h3> <p>An attacker can create many ENS names and establish mutual trust between them.</p> <p><strong>Protocol-level mitigations:</strong></p> <ul> <li><strong>Required anchors</strong>: <code>ValidationParams.requiredAnchors</code> forces paths through established community nodes</li> <li><strong>Short path limits</strong>: <code>maxPathLength: 2</code> requires close proximity to validators</li> <li><strong>High trust requirement</strong>: <code>minEdgeTrust: Full</code> rejects marginal trust paths</li> </ul> <p><strong>Application-level mitigations:</strong></p> <ul> <li>Weight trust by ENS name age or registration cost</li> <li>Implement additional stake requirements</li> <li>Monitor trust graphs for anomalous patterns off-chain</li> </ul> <h3 id="trust-graph-manipulation">Trust Graph Manipulation</h3> <p>Attackers may attempt to position themselves in many trust paths.</p> <p><strong>Mitigations:</strong></p> <ul> <li>Monitor trust graphs for anomalous patterns off-chain</li> <li>Use <code>minEdgeTrust: Full</code> for high-value coordination</li> <li>Require multiple independent paths via OPTIONAL extensions</li> </ul> <h3 id="key-compromise">Key Compromise</h3> <p>If an ENS name's controller is compromised:</p> <p><strong>Mitigations:</strong></p> <ul> <li>Agents SHOULD monitor for unexpected trust changes via <code>TrustSet</code> events</li> <li>Use short expiries (90 days maximum recommended for high-stakes)</li> <li>ENS name owners can rotate controllers</li> <li>Affected agents can issue <code>TrustRevoked</code> to quarantine compromised nodes</li> </ul> <h3 id="ens-name-transfer">ENS Name Transfer</h3> <p>When an ENS name is transferred:</p> <ul> <li>New owner inherits trust where they are the trustee</li> <li>New owner can manage trust where they are the trustor</li> <li>Old attestations signed by old owner remain valid until expiry</li> </ul> <p><strong>Mitigations:</strong></p> <ul> <li>Use short expiries for high-stakes trust</li> <li>Monitor ENS <code>Transfer</code> events</li> <li>Re-evaluate trust after transfers</li> </ul> <h3 id="replay-protection">Replay Protection</h3> <p><a href="https://wg-eips.ritovision.com/712/">EIP-712</a> domain binding prevents cross-contract replay. Monotonic nonces prevent replay within the same contract. The <code>chainId</code> in the domain prevents cross-chain replay.</p> <h3 id="stale-trust">Stale Trust</h3> <p>Trust relationships may become stale if agents don't update them.</p> <p><strong>Mitigations:</strong></p> <ul> <li>Use <code>enforceExpiry: true</code> in validation parameters</li> <li>Set reasonable <code>expiry</code> values on attestations (RECOMMENDED: 90 days maximum for high-stakes)</li> <li>Monitor <code>TrustSet</code> event timestamps off-chain</li> </ul> <h3 id="off-chain-path-computation">Off-Chain Path Computation</h3> <p>This standard assumes off-chain indexers compute trust paths. Malicious indexers could:</p> <ul> <li>Return suboptimal paths</li> <li>Omit valid paths</li> <li>Return invalid paths (caught by <code>verifyPath</code>)</li> </ul> <p><strong>Mitigations:</strong></p> <ul> <li>Users can run their own indexers</li> <li>Multiple independent indexers provide redundancy</li> <li>Invalid paths are always rejected on-chain</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> 2025-12-12T00:00:00+00:00 2026-02-11T14:48:25+00:00 Prem Makeighttps://github.com/nxt3d https://wg-eips.ritovision.com/8121/

A specification for cross-chain function calls using hooks with ERC-7930 interoperable addresses.

<h2 id="abstract">Abstract</h2> <p>This ERC introduces hooks for cross-chain function calls. A hook fully specifies what function to call, with what parameters, on which contract, on which chain. Hooks require clients to use <a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a> to resolve, enabling cross-chain and off-chain verifiable data resolution. Hooks are particularly useful for redirecting metadata to known contracts with verifiable security properties, such as credential registries for Proof-of-Personhood (PoP) or Know-Your-Agent (KYA) for AI agent identity.</p> <h2 id="motivation">Motivation</h2> <p>There is a need to resolve data cross-chain, such as credentials like Proof-of-Personhood (PoP), for example from a dedicated identity chain. There is also a need to save these cross-chain function calls onchain, and there is currently no existing standard for saving this type of function call as a string or bytes value onchain, in a maximally human-readable way. It should also be possible for a hook to be included in plain text, for example a markdown file intended to be consumed by AI agents. Hooks allow for a specific function, contract, and chain to be specified in a human-readable way. One of the most important features of hooks is that it allows clients to evaluate whether or not they trust the target contract, for example to resolve a PoP or KYC credential, before calling the function.</p> <h3 id="use-cases">Use Cases</h3> <ul> <li><strong>Cross-Chain Metadata</strong>: Resolve metadata from contracts on other chains</li> <li><strong>Credential Resolution</strong>: Redirect a Proof-of-Person (PoP) or Know-Your-Customer (KYC) record to a trusted credential registry</li> <li><strong>Singleton Registries</strong>: Point to canonical registries with known security properties on any chain</li> <li><strong>Shared Metadata</strong>: Multiple contracts can reference the same metadata source across chains</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> <h3 id="overview">Overview</h3> <p>A hook is a fully specified function call containing an optional function selector, function signature with explicit types, human-readable function call with values, return type, and an <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> interoperable address specifying both the target contract and chain. The function selector acts as a checksum to verify the function signature, ensuring type safety and preventing ambiguity. This makes hooks completely self-describing - any client can resolve them without external documentation.</p> <h3 id="hook-function-signature">Hook Function Signature</h3> <p>Hooks can be encoded with or without an optional function selector. When the selector is omitted, <code>functionSignature</code> is the first parameter.</p> <p><strong>With optional function selector:</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"> hook</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-variable"> functionSelector</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"> functionSignature</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"> functionCall</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"> returnType</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"> target</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p><strong>Without function selector:</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"> hook</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"> functionSignature</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"> functionCall</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"> returnType</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"> target</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-support">bytes4</span><span class="z-storage z-type"> constant</span><span> HOOK_SELECTOR_WITH_SELECTOR </span><span class="z-keyword">=</span><span class="z-constant"> 0x037f43ed</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> When functionSelector is included</span></span> <span class="giallo-l"><span class="z-support">bytes4</span><span class="z-storage z-type"> constant</span><span> HOOK_SELECTOR_WITHOUT_SELECTOR </span><span class="z-keyword">=</span><span class="z-constant"> 0x6113bfa3</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> When functionSelector is omitted</span></span></code></pre><h4 id="parameters">Parameters</h4> <ul> <li><strong><code>functionSelector</code></strong>: (OPTIONAL) The 4-byte selector of the function to call. When provided, this acts as a checksum to verify the <code>functionSignature</code>. If omitted, the hook structure starts with <code>functionSignature</code> as the first parameter. Clients can always derive the selector from <code>functionSignature</code>.</li> <li><strong><code>functionSignature</code></strong>: The full function signature with explicit parameter types (e.g., <code>"getData((string,uint256))"</code>, <code>"getCredential(string)"</code>). This MUST match the function selector when hashed, if a selector is provided. When the selector is omitted, this is the first parameter in the hook structure.</li> <li><strong><code>functionCall</code></strong>: A string representation of the function to call with its parameter values (human-readable, e.g., <code>"getData(('alice', 42))"</code>, <code>"getCredential('kyc: 0x76F1Ff...123')"</code>)</li> <li><strong><code>returnType</code></strong>: The return type in Solidity tuple notation for ABI decoding (e.g., <code>(string)</code>, <code>(uint256, bytes32)</code>, <code>((string, uint256[], bytes32))</code>)</li> <li><strong><code>target</code></strong>: An <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> interoperable address specifying both the target contract and chain</li> </ul> <h3 id="function-call-format">Function Call Format</h3> <p>The <code>functionCall</code> parameter uses a Solidity-style syntax:</p> <ul> <li>String parameters are enclosed in single quotes: <code>'value'</code></li> <li>Bytes/hex parameters use the <code>0x</code> prefix: <code>0x1234abcd</code></li> <li>Numbers are written as literals: <code>42</code> or <code>1000000</code></li> <li>Arrays use square brackets: <code>[1, 2, 3]</code> or <code>['a', 'b', 'c']</code></li> <li>Structs/tuples use parentheses: <code>('alice', 42, true)</code></li> </ul> <p><strong>Examples:</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// Example with optional function selector (acts as checksum)</span></span> <span class="giallo-l"><span>hook(0xc41a360a, &quot;getOwner(uint256)&quot;, &quot;getOwner(42)&quot;, &quot;(address)&quot;, 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// Example with function selector omitted</span></span> <span class="giallo-l"><span>hook(&quot;getOwner(uint256)&quot;, &quot;getOwner(42)&quot;, &quot;(address)&quot;, 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span></code></pre><h3 id="hook-encoding">Hook Encoding</h3> <p>Hooks can be encoded in two formats depending on the storage type:</p> <h4 id="bytes-format">Bytes Format</h4> <p>For systems that store <code>bytes</code> values, hooks MUST be ABI-encoded. Use different hook selectors depending on whether the optional function selector is included:</p> <p><strong>With optional function selector:</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Hook selector: first 4 bytes of keccak256(&quot;hook(bytes4,string,string,string,bytes)&quot;)</span></span> <span class="giallo-l"><span class="z-support">bytes4</span><span class="z-storage z-type"> constant</span><span> HOOK_SELECTOR_WITH_SELECTOR </span><span class="z-keyword">=</span><span class="z-constant"> 0x037f43ed</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Function signature with explicit types</span></span> <span class="giallo-l"><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span> functionSignature </span><span class="z-keyword">=</span><span class="z-string"> &quot;getContractMetadata(string)&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Optional function selector as checksum (computed from signature)</span></span> <span class="giallo-l"><span class="z-support">bytes4</span><span> functionSelector </span><span class="z-keyword">=</span><span class="z-support"> bytes4</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span>functionSignature</span><span>)</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x1837de7f</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Function call with values</span></span> <span class="giallo-l"><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span> functionCall </span><span class="z-keyword">=</span><span class="z-string"> &quot;getContractMetadata(&#39;kyc&#39;)&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ERC-7930 address: Ethereum mainnet (chain 1) contract</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> target </span><span class="z-keyword">=</span><span> hex</span><span class="z-string">&quot;000100000101141234567890abcdef1234567890abcdef12345678&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> hookData </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span></span> <span class="giallo-l"><span> HOOK_SELECTOR_WITH_SELECTOR</span><span>,</span></span> <span class="giallo-l"><span> functionSelector</span><span>,</span></span> <span class="giallo-l"><span> functionSignature</span><span>,</span></span> <span class="giallo-l"><span> functionCall</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;(bytes)&quot;</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> return type</span></span> <span class="giallo-l"><span> target</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"> Store the hook as the value</span></span> <span class="giallo-l"><span>originatingContract</span><span>.</span><span class="z-entity z-name">setContractMetadata</span><span>(</span><span class="z-string">&quot;kyc&quot;</span><span>,</span><span> hookData</span><span>)</span><span>;</span></span></code></pre> <p><strong>Without function selector:</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Hook selector: first 4 bytes of keccak256(&quot;hook(string,string,string,bytes)&quot;)</span></span> <span class="giallo-l"><span class="z-support">bytes4</span><span class="z-storage z-type"> constant</span><span> HOOK_SELECTOR_WITHOUT_SELECTOR </span><span class="z-keyword">=</span><span class="z-constant"> 0x6113bfa3</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Function signature with explicit types</span></span> <span class="giallo-l"><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span> functionSignature </span><span class="z-keyword">=</span><span class="z-string"> &quot;getContractMetadata(string)&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Function call with values</span></span> <span class="giallo-l"><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span> functionCall </span><span class="z-keyword">=</span><span class="z-string"> &quot;getContractMetadata(&#39;kyc&#39;)&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ERC-7930 address: Ethereum mainnet (chain 1) contract</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> target </span><span class="z-keyword">=</span><span> hex</span><span class="z-string">&quot;000100000101141234567890abcdef1234567890abcdef12345678&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> hookData </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span></span> <span class="giallo-l"><span> HOOK_SELECTOR_WITHOUT_SELECTOR</span><span>,</span></span> <span class="giallo-l"><span> functionSignature</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> First parameter when selector is omitted</span></span> <span class="giallo-l"><span> functionCall</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;(bytes)&quot;</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> return type</span></span> <span class="giallo-l"><span> target</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"> Store the hook as the value</span></span> <span class="giallo-l"><span>originatingContract</span><span>.</span><span class="z-entity z-name">setContractMetadata</span><span>(</span><span class="z-string">&quot;kyc&quot;</span><span>,</span><span> hookData</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Target function: function getContractMetadata(string) external view returns (bytes memory)</span></span></code></pre><h4 id="string-format">String Format</h4> <p>For systems that store <code>string</code> values, hooks MUST be formatted as shown below. The target is an <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> interoperable address.</p> <p><strong>With optional function selector:</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>hook(0x9e574b14, &quot;getContractMetadata(string)&quot;, &quot;getContractMetadata(&#39;kyc&#39;)&quot;, &quot;(bytes)&quot;, 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span></code></pre> <p><strong>Without function selector:</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>hook(&quot;getContractMetadata(string)&quot;, &quot;getContractMetadata(&#39;kyc&#39;)&quot;, &quot;(bytes)&quot;, 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span></code></pre> <p>Parsers MUST detect the format by checking if the first parameter after <code>hook(</code> starts with <code>0x</code> followed by 8 hexadecimal characters (an optional function selector) or not.</p> <p><strong>Examples:</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"></span> <span class="giallo-l"><span>// Example 1: simple struct parameter</span></span> <span class="giallo-l"><span>hook(0xabcdef12, &quot;getData((string,uint256))&quot;, &quot;getData((&#39;alice&#39;, 42))&quot;, &quot;(bytes)&quot;, 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// Example 2: struct parameter returning struct</span></span> <span class="giallo-l"><span>hook(0x12345678, &quot;getCredential((string,uint256,bytes32))&quot;, &quot;getCredential((&#39;kyc&#39;, 12345, 0xabcd1234...))&quot;, &quot;((string,address,uint256))&quot;, 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// Example 3: nested struct (struct containing a struct)</span></span> <span class="giallo-l"><span>hook(0x9abcdef0, &quot;getAgent((string,uint256,(address,bool,string)))&quot;, &quot;getAgent((&#39;alice&#39;, 42, (0x1234..., true, &#39;verified&#39;)))&quot;, &quot;((string,uint256,(address,bool)))&quot;, 0x000100000101141234567890abcdef1234567890abcdef12345678)</span></span></code></pre><h3 id="detecting-hooks">Detecting Hooks</h3> <p>Clients SHOULD be aware in advance which metadata keys may contain hooks. It is intentional that hook-enabled keys are known by clients beforehand, similar to how clients know to look for keys like <code>"image"</code> or <code>"description"</code>.</p> <p>For bytes values, hooks can be detected by checking if the value starts with either hook selector <code>0x037f43ed</code> (with optional function selector) or <code>0x6113bfa3</code> (without function selector). For string values, hooks can be detected by checking if the value starts with <code>hook(</code>.</p> <h3 id="resolving-hooks-read-operations">Resolving Hooks (Read Operations)</h3> <p>When a client encounters a hook that it wants to use for a read operation:</p> <ol> <li><strong>Detect hook format</strong>: For bytes format, check if the value starts with <code>0x037f43ed</code> (with selector) or <code>0x6113bfa3</code> (without selector). For string format, parse the first parameter after <code>hook(</code> to determine if it's a selector (starts with <code>0x</code> + 8 hex chars) or not.</li> <li><strong>Parse the hook</strong>: Extract the <code>functionSelector</code> (if present), <code>functionSignature</code>, <code>functionCall</code>, <code>returnType</code>, and <code>target</code> (<a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> address). If the selector is omitted, <code>functionSignature</code> is the first parameter.</li> <li><strong>Verify the selector</strong> (if provided): If <code>functionSelector</code> is present, compute the expected selector from <code>functionSignature</code> as <code>bytes4(keccak256(functionSignature))</code> and verify it matches <code>functionSelector</code>. Reject the hook if they don't match. This verification ensures type safety and prevents ambiguity with structs or overloaded functions. If the selector is omitted, compute it from <code>functionSignature</code> for use in the function call.</li> <li><strong>Parse the target</strong>: Decode the <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> address to extract the chain and contract address</li> <li><strong>Verify the target</strong> (RECOMMENDED): Check that the target contract is known and trusted</li> <li><strong>Parse the function call</strong>: Extract the function name and parameter values from <code>functionCall</code>. Use <code>functionSignature</code> to determine the parameter types for ABI encoding.</li> <li><strong>Enable <a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a></strong>: Clients MUST enable <a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a> offchain data retrieval before calling the target</li> <li><strong>Call the target</strong>: Execute the function on the target contract and chain. Use the provided <code>functionSelector</code> if available, otherwise compute it from <code>functionSignature</code> as <code>bytes4(keccak256(functionSignature))</code>. ABI-encode the parameters according to <code>functionSignature</code>.</li> <li><strong>Get the result</strong>: Retrieve the return value from the function call.</li> </ol> <p>Clients MAY choose NOT to resolve hooks if the target contract is not known to be secure and trustworthy. Some clients have <a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a> disabled by default, but clients MUST enable it before resolving the hook.</p> <h3 id="write-operations">Write Operations</h3> <p>Write operations are also possible with hooks and follow the same flow as read operations, except that the transaction needs to be signed and submitted to the blockchain. The hook specifies the function to call, parameters, target contract, and chain, but instead of reading the result, the transaction is signed and broadcast to the network for inclusion in a block.</p> <h3 id="example-cross-chain-kyc-credential-resolution">Example: Cross-Chain KYC Credential Resolution</h3> <p>A contract on Optimism can redirect its <code>"kyc"</code> metadata key to a trusted KYC provider contract on Ethereum mainnet:</p> <p><strong>Step 1: Store the hook in the originating contract (on Optimism)</strong></p> <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"> constant</span><span> HOOK_SELECTOR_WITHOUT_SELECTOR </span><span class="z-keyword">=</span><span class="z-constant"> 0x6113bfa3</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Function signature with explicit types</span></span> <span class="giallo-l"><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span> functionSignature </span><span class="z-keyword">=</span><span class="z-string"> &quot;getCredential(string)&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Function call with values</span></span> <span class="giallo-l"><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span> functionCall </span><span class="z-keyword">=</span><span class="z-string"> &quot;getCredential(&#39;kyc: 0x76F1Ff0186DDb9461890bdb3094AF74A5F24a162&#39;)&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> KYCProvider on Ethereum mainnet (ERC-7930 format)</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Chain: Ethereum mainnet (chain 1), Address: 0x1234...5678</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> target </span><span class="z-keyword">=</span><span> hex</span><span class="z-string">&quot;000100000101141234567890abcdef1234567890abcdef12345678&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Create hook that calls getCredential(&#39;kyc: 0x76F1Ff...&#39;) on the KYC provider</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> hookData </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span></span> <span class="giallo-l"><span> HOOK_SELECTOR_WITHOUT_SELECTOR</span><span>,</span></span> <span class="giallo-l"><span> functionSignature</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> First parameter when selector is omitted</span></span> <span class="giallo-l"><span> functionCall</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;(string)&quot;</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> return type</span></span> <span class="giallo-l"><span> target</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"> Store the hook</span></span> <span class="giallo-l"><span>originatingContract</span><span>.</span><span class="z-entity z-name">setContractMetadata</span><span>(</span><span class="z-string">&quot;kyc&quot;</span><span>,</span><span> hookData</span><span>)</span><span>;</span></span></code></pre> <p><strong>Step 2: Client resolves the hook</strong></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"> Client reads metadata from originating contract (on Optimism)</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> value</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> originatingContract</span><span>.</span><span class="z-entity z-name">getContractMetadata</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">kyc</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"> Client detects this is a hook (starts with HOOK_SELECTOR)</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> hasSelector</span><span class="z-keyword"> =</span><span class="z-variable z-other"> value</span><span>.</span><span class="z-entity z-name">startsWith</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x037f43ed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">if</span><span> (</span><span class="z-variable z-other">value</span><span>.</span><span class="z-entity z-name">startsWith</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x037f43ed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword"> ||</span><span class="z-variable z-other"> value</span><span>.</span><span class="z-entity z-name">startsWith</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x6113bfa3</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-comment"> //</span><span class="z-comment"> Parse the hook (ABI decode after 4-byte selector)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> functionSelector</span><span>,</span><span class="z-variable z-other"> functionSignature</span><span>,</span><span class="z-variable z-other"> functionCall</span><span>,</span><span class="z-variable z-other"> returnType</span><span>,</span><span class="z-variable z-other"> target</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-other">hasSelector</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> (</span><span>{</span><span class="z-variable z-other"> functionSelector</span><span>,</span><span class="z-variable z-other"> functionSignature</span><span>,</span><span class="z-variable z-other"> functionCall</span><span>,</span><span class="z-variable z-other"> returnType</span><span>,</span><span class="z-variable z-other"> target</span><span> }</span><span class="z-keyword"> =</span><span class="z-entity z-name"> decodeHook</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-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span> (</span><span>{</span><span class="z-variable z-other"> functionSignature</span><span>,</span><span class="z-variable z-other"> functionCall</span><span>,</span><span class="z-variable z-other"> returnType</span><span>,</span><span class="z-variable z-other"> target</span><span> }</span><span class="z-keyword"> =</span><span class="z-entity z-name"> decodeHook</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-variable z-other"> functionSelector</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Verify selector matches the function signature (checksum verification, if provided)</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> computedSelector</span><span class="z-keyword"> =</span><span class="z-entity z-name"> keccak256</span><span>(</span><span class="z-variable z-other">functionSignature</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-constant"> 10</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-other">functionSelector</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-other">functionSelector</span><span class="z-keyword"> !==</span><span class="z-variable z-other"> computedSelector</span><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">&quot;</span><span class="z-string">Selector mismatch - function signature verification 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></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Use computed selector if not provided</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> selectorToUse</span><span class="z-keyword"> =</span><span class="z-variable z-other"> functionSelector</span><span class="z-keyword"> ||</span><span class="z-variable z-other"> computedSelector</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 ERC-7930 address to get chain and contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span> {</span><span class="z-variable z-other z-constant"> chainId</span><span>,</span><span class="z-variable z-other z-constant"> address</span><span> }</span><span class="z-keyword"> =</span><span class="z-entity z-name"> decodeERC7930</span><span>(</span><span class="z-variable z-other">target</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> chainId = 1 (Ethereum mainnet)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> address = 0x1234567890abcdef1234567890abcdef12345678</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 target is trusted (implementation-specific)</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">isTrustedResolver</span><span>(</span><span class="z-variable z-other">chainId</span><span>,</span><span class="z-variable z-other"> address</span><span>)</span><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">&quot;</span><span class="z-string">Untrusted resolver</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Parse the function call string to get function name and parameter values</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span> {</span><span class="z-variable z-other z-constant"> functionName</span><span>,</span><span class="z-variable z-other z-constant"> args</span><span> }</span><span class="z-keyword"> =</span><span class="z-entity z-name"> parseFunctionCall</span><span>(</span><span class="z-variable z-other">functionCall</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> functionName = &quot;getCredential&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> args = [&quot;kyc: 0x76F1Ff0186DDb9461890bdb3094AF74A5F24a162&quot;]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Use functionSignature to determine parameter types for ABI encoding</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> functionSignature = &quot;getCredential(string)&quot;</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 provider for target chain and enable ERC-3668 (CCIP-Read)</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> targetProvider</span><span class="z-keyword"> =</span><span class="z-entity z-name"> getProviderForChain</span><span>(</span><span class="z-variable z-other">chainId</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"> targetContract</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-variable z-other"> ethers</span><span>.</span><span class="z-entity z-name">Contract</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-punctuation z-definition z-string">`</span><span class="z-string">function </span><span class="z-string">${</span><span class="z-variable z-other">functionSignature</span><span class="z-string">}</span><span class="z-string"> view returns (bytes)</span><span class="z-punctuation z-definition z-string">`</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> targetProvider</span><span>.</span><span class="z-entity z-name">ccipReadEnabled</span><span>(</span><span class="z-constant">true</span><span>)</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Enable CCIP-Read</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"> Resolve from target contract on Ethereum mainnet</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ABI-encode parameters according to functionSignature</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> resultBytes</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> targetContract</span><span>[</span><span class="z-variable z-other">functionName</span><span>]</span><span>(</span><span class="z-keyword">...</span><span class="z-variable z-other">args</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"> ABI-decode using returnType: &quot;(string)&quot;</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> credential</span><span class="z-keyword"> =</span><span class="z-variable z-other"> ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-variable z-other">defaultAbiCoder</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>[</span><span class="z-variable z-other">returnType</span><span>]</span><span>,</span><span class="z-variable z-other"> resultBytes</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> credential = &quot;Maria Garcia /0x76F1Ff.../ ID: 146-DJH-6346-25294&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Hooks provide a complete specification for cross-chain function calls, including <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> interoperable address. This makes hooks entirely self-describing - any client can resolve them without external documentation or ABI files. For use cases including resolving credentials from known registries including PoP (Proof of Personhood) and KYC (Know Your Customer) credentials, the client needs to make sure the source of the credential is trustworthy and verified. Hooks allow clients to jump from a user's metadata record, for example, to a KYC credential from a known credential issuer.</p> <h3 id="why-include-both-function-selector-and-function-string">Why Include Both Function Selector and Function String?</h3> <p>Hooks include both an optional 4-byte function selector and a human-readable function call string. The selector provides type disambiguation (e.g., <code>getData(bytes32)</code> and <code>getData(bytes)</code> have different selectors, but <code>0x1234...</code> in the string is ambiguous), while the string provides human readability. Clients can verify the selector matches the function signature, rejecting mismatches as errors or tampering.</p> <h3 id="why-use-erc-7930-interoperable-addresses">Why Use ERC-7930 Interoperable Addresses?</h3> <p><a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> addresses include chain information, making hooks a complete cross-chain function call specification. A hook specifies exactly what function to call, with what parameters, on which contract, on which chain. This eliminates ambiguity and enables secure cross-chain reads when combined with <a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a>.</p> <h3 id="why-include-the-return-type">Why Include the Return Type?</h3> <p>The <code>returnType</code> parameter allows clients to predict the return values without consulting documentation. It is also possible to predict if the return data is compatible with intended metadata. For example, if a bytes value redirects using hooks, that return value may need to also be bytes, according to the specific metadata standard (not specified here). Applications can impose their own constraints (e.g., requiring <code>(string)</code> for metadata hooks), but hooks themselves support any return type.</p> <h3 id="why-mandate-erc-3668">Why Mandate <a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a>?</h3> <p><a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a> (CCIP-Read) is a powerful technology that enables both cross-chain and verified offchain resolution of metadata. However, because some clients disable <a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a> by default due to security considerations, hooks explicitly mandate <a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a> support. This gives clients the opportunity to enable <a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a> specifically for hook resolution without needing to have it enabled globally. By tying <a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a> to hooks, clients can make a deliberate choice to enable it when resolving from known, trusted contracts, while keeping it disabled for general use.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Hooks are backwards compatible; clients that are not aware of hooks will simply return the hook encoding as the raw value.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="target-trust">Target Trust</h3> <p>The primary use of hooks is to resolve data from known contracts with verifiable security properties. Clients SHOULD:</p> <ul> <li>Maintain a list of trusted target contract addresses or use a third-party registry</li> <li>Fail when resolving from untrusted targets</li> </ul> <h3 id="recursive-hooks">Recursive Hooks</h3> <p>Implementations SHOULD limit the depth of hook resolution to prevent infinite loops where a hook resolves to another hook. A reasonable limit is 3-5 levels of indirection.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-12-02T00:00:00+00:00 2026-02-11T14:49:27+00:00 Marcin Sobczakhttps://github.com/marcindsobczak Kamil Chodołahttps://github.com/kamilchodola Marek Moraczyńskihttps://github.com/MarekM25 https://wg-eips.ritovision.com/8096/

Increases cost of point evaluation precompile

<h2 id="abstract">Abstract</h2> <p>This EIP modifies the gas cost of <code>point evaluation</code> precompile introduced in <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>.</p> <h2 id="motivation">Motivation</h2> <p>Currently the <code>point evaluation</code> precompile is underpriced relative to its resource consumption. This EIP aims to address these discrepancies by adjusting the gas cost and making <code>point evaluation</code> precompile sufficiently efficient to enable potential further increases in the block gas limit.</p> <h2 id="specification">Specification</h2> <p>Upon activation of this EIP, the gas cost of calling the precompile at address <code>0x000000000000000000000000000000000000000A</code> will be doubled from <code>50_000</code> gas to <code>100_000</code> gas.</p> <h2 id="rationale">Rationale</h2> <p>Benchmarking the <code>point evaluation</code> precompile revealed that its gas cost is significantly underestimated. This modification aim to ensure that the <code>point evaluation</code> precompile's performance no longer impedes potential increases to the block gas limit.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces a backwards-incompatible change. However, similar gas repricings have occurred multiple times in the Ethereum ecosystem, and their effects are well understood.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP does not introduce any new functionality or make existing operations cheaper, therefore there are no direct security concerns related to new attack vectors or reduced cost.</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-11-29T00:00:00+00:00 2026-02-11T14:49:27+00:00 Csaba Kiralyhttps://github.com/cskiraly https://wg-eips.ritovision.com/8094/

Make mempool messaging vhash aware

<h2 id="abstract">Abstract</h2> <p>This EIP eliminates the need to redistribute blob content in the mempool if only the metadata (fees) of a transaction are updated, making RBF (replace-by-fee) more efficient and cheaper for the network. It achieves this modifying the devp2p ‘eth’ protocol to address blobs in type 3 transaction sidecars by content (vhash).</p> <h2 id="motivation">Motivation</h2> <p>In the current version of devp2p eth/69, when a transaction is replaced, it must be redistributed in the mempool like any new transaction. Even if the actual content is largely the same, protocol participants have no means to figure this out before getting the full content, making a replacement use the same amount of network resources as a new transaction would.</p> <p>What is especially problematic is that RBF is used most in periods of fee volatility, and a network overload is the typical case of such a situation. Thus, when there is already high demand, we make the situation worse by adding extra traffic redistributing blob content that was already distributed.</p> <h2 id="specification">Specification</h2> <h3 id="transactions-0x02-changes">Transactions (0x02) changes</h3> <p>Type 3 transaction should be sent without sidecar</p> <h3 id="pooledtransactions-0x0a-changes">PooledTransactions (0x0a) changes</h3> <p>Type 3 transaction should be sent without sidecar</p> <h3 id="getpooledblobs-msg-code-to-be-assigned-todo">GetPooledBlobs (msg code to be assigned &lt;-- TODO --&gt;)</h3> <p>[request-id: P, [vhash₁: B_32, vhash₂: B_32, ...]]</p> <p>This message requests blobs from the recipient's transaction pool by vhash.</p> <h3 id="pooledblobs-msg-code-to-be-assigned-todo">PooledBlobs (msg code to be assigned &lt;-- TODO --&gt;)</h3> <p>[request-id: P, [blob₁, blob₂...]]</p> <p>This is the response to GetPooledBlobs, returning the requested blobs. The items in the list are blobs in the format described in the main Ethereum specification.</p> <blockquote> <p>Note: optionally, we might prefix the blob format with the blob version number</p> <p>Note: optionally, we might decide to improve the blob format allowing nodes to reconstruct RS encoding instead of using extra bandwidth, by sending the following fields per blob:</p> <ul> <li>blob version</li> <li>blob content, <strong>excluding</strong> the erasure coding extension in case of version 1</li> <li>blob commitment</li> <li>blob proof(s), <strong>including</strong> cell proofs of the erasure coded piece in case of version 1</li> </ul> <p>It is important to include all cell proofs to keep reconstruction CPU-efficient.</p> </blockquote> <p>The blobs must be in the same order as in the request, but it is OK to skip blobs which are not available. Since the recipient have to check that transmitted blob hashes correspond to the requested vhashes anyway, we can avoid sending the list of vhashes as part of this message.</p> <blockquote> <p>Note: Optionally, we could extend this message with a bitmap of sent/unsent blobs from the request, or with the list of vhashes sent. This information is redundant, but it can simplify processing on the receiver side.</p> </blockquote> <h3 id="other-spec-changes">Other spec changes</h3> <p>EIP-4844 introduced the following:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Nodes MUST NOT automatically broadcast blob transactions to their peers. Instead, those transactions are only announced using NewPooledTransactionHashes messages, and can then be manually requested via GetPooledTransactions.</span></span></code></pre> <p>The above should be changed as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Nodes MUST send (broadcast or send in NewPooledTransactionHashes) blob transaction **without** sidecars to their peers. Peers can then request blob content using `GetPooledBlobs` messages. Nodes MUST NOT forward blob transactions before receiving and validating all blobs&quot;.</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>A typical blob transaction RBF changes the fees only, while the sidecar (blob content) remains the same. If a node that has the previous version would know this, it could avoid pulling the sidecar, largely reducing bandwidth consumption. However, this is not possible with the current messaging. To make this happen, we have to expose blob (or at least sidecar) identifiers in mempool messaging.</p> <h3 id="should-we-use-blob-identifiers-or-a-sidecar-identifier">Should we use blob identifiers or a sidecar identifier?</h3> <p>We can either use vhashes, or a sidecar level hash. The latter has the slight advantage of being a single element, thus simplifying message format, but it has several disadvantages:</p> <ul> <li>It would be a new identifier, while the blob level vhash is already well established (just not in devp2p)</li> <li>It would not allow restructuring the message, sending e.g. less blobs under a fee surge</li> </ul> <p>Thus, we use vhashes.</p> <h3 id="implementation-options">Implementation options</h3> <p>There are several options to bring vhashes to devp2p messaging:</p> <h4 id="option-1">Option 1</h4> <ul> <li>Extend announcements with vhashes</li> <li>Allow nodes to request transaction with/without sidecar content, or even selecting which parts are needed (bitmap or vhash list)</li> </ul> <h4 id="option-2">Option 2</h4> <ul> <li>Extend announcements with nonce (see EIP-8077)</li> <li>If hash differs from what we have, request with/without sidecar content based on whether we already have the sidecars for the same nonce, assuming this is a simple replacement</li> <li>Request again with sidecar if vhashes differ</li> </ul> <h4 id="option-3-selected">Option 3 (selected)</h4> <ul> <li>Push (or announce and then pull) type 3 transaction <strong>without sidecar</strong></li> <li>Allow to <strong>request sidecar separately</strong> (new message type)</li> </ul> <p>At first it might seem that Option 3 is slowing down distribution, adding one more RTT latency per hop. However, since most type 3 transactions are small without a sidecar, we could change the protocol behaviour to allow pushing these transactions without the sidecar, leaving it to the receiver of the push to ask for the blobs if needed. Forwarding of type 3 transactions without sidecar should be prohibited until sidecars are fetched and the content can be verified.</p> <p>After considering the above options, we chose to propose Option 3, introducing a new message type.</p> <h3 id="relation-to-other-eips-in-draft-state">Relation to other EIPs in draft state</h3> <ul> <li>EIP-8077 (announce source and nonce): the changes can be simply combined.</li> <li>EIP-8070 (Sparse blobpool): both EIPs change how blob transactions are propagated over the network. The goal of the two EIPs are different. EIP-8070 is about a proportional bandwidth reduction in the normal case without dealing with specifics of RBF. This EIP is about enabling RBF without using extra bandwidth. The two EIPs can be combined, but the combination depends on the order of introduction, hence we leave this for later &lt;-- TODO --&gt;.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP changes the eth protocol and requires rolling out a new version. Supporting multiple versions of a wire protocol is routine practice. Rolling out this new version does not break older clients, since they can keep using the previous protocol version.</p> <p>This EIP does not change consensus rules of the EVM and does not require a hard fork.</p> <h2 id="security-considerations">Security Considerations</h2> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via CC0.</p> 2025-11-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Steve Katzmanhttps://github.com/stevieraykatz Amie Corsohttps://github.com/amiecorso Stephan Cilliershttps://github.com/stephancill https://wg-eips.ritovision.com/8092/

A way to publicly associate two accounts with arbitrary contextual data

<h2 id="abstract">Abstract</h2> <p>This specification defines a standard for establishing and verifying associations between blockchain accounts. This allows addresses to publicly declare, prove and revoke a relationship with other addresses by sharing a standardized payload. For onchain applications, this payload may be signed by both parties for third-party authentication. This enables use cases like sub-account identity inheritance, authorization delegation, and reputation collation.</p> <h2 id="motivation">Motivation</h2> <p>A key motivation is the simplification of multi-address resolution, which is essential for managing complex digital identities across multiple platforms and accounts. This simplification aims to streamline the process of locating and verifying individuals or entities by efficiently handling multiple addresses linked by Associations. By providing a standard mechanism for signaling an association between two accounts, this standard unlocks the capability to link the activities or details of these accounts.</p> <p>The inclusion of arbitrary data into the specified payload ensures flexibility for various use cases such as delegation, hierarchical relationships, and authentication. By maintaining a flexible architecture that accepts an interface identifier paired with arbitrary data bytes, accounts that associate can do so with application-specific context.</p> <p>The system outlined in this document describes a way for two accounts to be linked by a specified data struct which describes the relationship between them. It offers the mechanism by which these parties can sign over the contents to prove validity. It focuses on the structure and process for generating, validating and revoking such records while maintaining an implementation agnostic approach.</p> <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="core-concepts">Core Concepts</h3> <p>Each Association between two accounts denotes the participating addresses as <code>initiator</code> and <code>approver</code>. These accounts can be on disparate chains with different architectures made possible by a combination of <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> Interoperable Addresses and an enumeration of signature key types. To accommodate non-EVM account types, addresses are recorded in the association as raw bytes.</p> <p>The specification outlines a nested structure for recording Associations:</p> <ol> <li>An underlying Associated Account Record (AAR) for storing accounts, timestamps and association context</li> <li>A wrapper Signed Association Record (SAR) structure for storing signature and validation data</li> </ol> <h3 id="associated-account-record">Associated Account Record</h3> <p>The following is a Solidity implementation of an <code>AssociatedAccountRecord</code> which contains the shared payload describing the association.</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"> @notice</span><span class="z-comment"> Represents an association between two accounts.</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> AssociatedAccountRecord</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"> The ERC-7930 binary representation of the initiating account&#39;s address.</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> initiator</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"> The ERC-7930 binary representation of the approving account&#39;s address.</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> approver</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"> The timestamp from which the association is valid.</span></span> <span class="giallo-l"><span class="z-support"> uint40</span><span> validAt</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"> The timestamp when the association expires.</span></span> <span class="giallo-l"><span class="z-support"> uint40</span><span> validUntil</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"> Optional 4-byte selector for interfacing with the `data` field.</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span> interfaceId</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"> Optional additional data.</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></code></pre> <p>Where the AssociatedAccountRecord contains:</p> <ul> <li><code>initiator</code> is the binary representation of an ERC-7930 address for the initiating account.</li> <li><code>approver</code> is the binary representation of an ERC-7930 address for the approving account.</li> <li><code>validAt</code> is the timestamp from which the association is valid.</li> <li><code>validUntil</code> is the timestamp at which the association expires (optional).</li> <li><code>interfaceId</code> is the 4-byte interface or method selector for the <code>data</code> field (optional).</li> <li><code>data</code> is the arbitrary context data payload (optional).</li> </ul> <h3 id="signed-association-record">Signed Association Record</h3> <p>When <code>AssociatedAccountRecord</code>s will be consumed in a trustless context, integrators SHOULD require that both parties sign over the <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> hash of the <code>AssociatedAccountRecord</code> (see Support for EIP-712 below). The resulting signatures MUST be included in a <code>SignedAssociationRecord</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"> @notice</span><span class="z-comment"> Complete payload containing a finalized association.</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> SignedAssociationRecord</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"> The timestamp the association was revoked.</span></span> <span class="giallo-l"><span class="z-support"> uint40</span><span> revokedAt</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"> The initiator key type specifier.</span></span> <span class="giallo-l"><span class="z-support"> bytes2</span><span> initiatorKeyType</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"> The approver key type specifier.</span></span> <span class="giallo-l"><span class="z-support"> bytes2</span><span> approverKeyType</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"> The signature of the initiator.</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> initiatorSignature</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"> The signature of the approver.</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> approverSignature</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"> The underlying AssociatedAccountRecord.</span></span> <span class="giallo-l"><span> AssociatedAccountRecord record</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <p>Where the SignedAssociationRecord contains:</p> <ul> <li><code>revokedAt</code> is the timestamp when the association was revoked, which is <code>0</code> unless the association has been revoked by either party.</li> <li><code>initiatorSignature</code> is the signature bytes generated by the <code>initiator</code> by signing the EIP-712 compliant hash of the AssociatedAccountRecord.</li> <li><code>initiatorKeyType</code> is the key type designator for the initiator's signature (see Key Types below).</li> <li><code>approverSignature</code> is the signature bytes generated by the <code>approver</code> by signing the EIP-712 compliant hash of the AssociatedAccountRecord.</li> <li><code>approverKeyType</code> is the key type designator for the approver's signature (see Key Types below).</li> <li><code>record</code> is the AssociatedAccountRecord that was signed by both parties.</li> </ul> <h3 id="key-types">Key Types</h3> <p>To accommodate known curves and signing protocols while providing future extensibility, this specification relies on the enumeration of cryptographic curves and signing protocols. Each signature MUST be paired with a valid "Key ID" designator.</p> <p>The Key IDs SHALL be identified as a 2-byte integer according to the following extensible table. We accommodate two types of keys:</p> <ol> <li>Applied cryptographic curves (i.e. secp256k1)</li> <li>Protocol integrations (i.e. WebAuthn, contract validation)</li> </ol> <p>To distinguish these key types, the most significant bit in the 2-byte identifier SHALL be used as a bit flag. As such, key type protocols are constructed by bitwise OR: <code>0x8000 | PROTOCOL_ID</code>.</p> <p>The resulting table enumerates the known keys and distinguishes between the two types:</p> <table><thead><tr><th>Key ID</th><th>Type</th><th>Curve/Standard</th></tr></thead><tbody> <tr><td>0x0000</td><td>Delegated</td><td>Delegated auth</td></tr> <tr><td>0x0001</td><td>K1</td><td>secp256k1</td></tr> <tr><td>0x0002</td><td>R1</td><td>secp256r1</td></tr> <tr><td>0x0003</td><td>BLS</td><td>BLS12-381</td></tr> <tr><td>0x0004</td><td>EdDSA</td><td>Ed25519</td></tr> <tr><td>0x8001</td><td>WebAuthn</td><td>WebAuthn/Passkey</td></tr> <tr><td>0x8002</td><td><a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a></td><td>Contract validation</td></tr> <tr><td>0x8003</td><td><a href="https://wg-eips.ritovision.com/6492/">ERC-6492</a></td><td>Predeploy contract validation</td></tr> </tbody></table> <h4 id="delegated-auth">Delegated Auth</h4> <p>In some contexts it might be ergonomic to delegate authorization to another account, access control mechanism, or external protocol. Implementers leveraging the <code>Delegated</code> key type MUST also publish how consumers can parse the application-specific delegation schema.</p> <h3 id="support-for-eip-712">Support for EIP-712</h3> <p>All signatures contained in this specification MUST comply with EIP-712 wherein the signature preimage can be generated from:</p> <pre class="giallo z-code"><code data-lang="solidity"><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;AssociatedAccountRecord(bytes initiator,bytes approver,uint40 validAt,uint40 validUntil,bytes4 interfaceId,bytes data)&quot;</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span>initiator</span><span>)</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span>approver</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> validAt</span><span>,</span></span> <span class="giallo-l"><span> validUntil</span><span>,</span></span> <span class="giallo-l"><span> interfaceId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span>data</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>)</span></span></code></pre> <p>Where <code>DOMAIN_SEPARATOR</code> is defined according to EIP-712. The <code>DOMAIN_SEPARATOR</code> for this ERC SHALL be defined as:</p> <pre class="giallo z-code"><code data-lang="solidity"><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;EIP712Domain(string name,string version)&quot;</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;AssociatedAccounts&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 class="giallo-l"><span>)</span><span>)</span></span></code></pre><h3 id="onchain-storage">Onchain Storage</h3> <p>If desired, a <code>SignedAssociationRecord</code> MAY be stored onchain in a context-specific storage contract.</p> <p>An onchain storage contract SHALL comply with the following steps:</p> <ol> <li>The SAR MUST be validated according to the steps detailed in the Validation section.</li> <li>The contract MUST emit the <code>AssociationCreated</code> event:</li> </ol> <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"> AssociationCreated</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"> hash</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> approver</span><span>, </span><span class="z-variable">SignedAssociationRecord</span><span class="z-variable"> sar</span></span> <span class="giallo-l"><span> )</span><span>;</span></span></code></pre> <p>where:</p> <ul> <li><code>hash</code> is the indexed hash for the SignedAssociationRecord, equivalent to the EIP-712 hash of the underlying AAR.</li> <li><code>initiator</code> is the keccak256 hash of the ERC-7930 address of the account that initiated the association.</li> <li><code>approver</code> is the keccak256 hash of the ERC-7930 address of the account that accepted and completed the association.</li> <li><code>sar</code> is the completed SignedAssociationRecord.</li> </ul> <p>If a SignedAssociationRecord is stored onchain, it MUST also be revokable onchain (see Revocation section below).</p> <h3 id="offchain-storage">Offchain Storage</h3> <p>In some contexts, it might be desirable for Signed Association Records to be stored in an offchain store. While the implementation will differ from application-to-application, the following considerations SHOULD be taken into account:</p> <ul> <li>Access to this data store MUST be made available to all expected consumers through publicly accessible endpoints</li> <li>The store MUST perform validation on incoming Associations before storage</li> <li>The location of this offchain store SHOULD be searchable by some standard fetching mechanism, e.g. a text record on an ENS name</li> </ul> <h3 id="validation">Validation</h3> <p>Clients or contracts determining whether a SignedAssociationRecord is valid at the time of consumption MUST check all of the following validation steps:</p> <ol> <li>The current timestamp MUST be greater than or equal to the <code>validAt</code> timestamp.</li> <li>If the <code>validUntil</code> timestamp is nonzero, the current timestamp MUST be less than the <code>validUntil</code> timestamp.</li> <li>If the <code>revokedAt</code> timestamp is nonzero, the current timestamp MUST be less than the <code>revokedAt</code> timestamp.</li> <li>If the <code>initiatorSignature</code> field is populated, the signature MUST be valid for the EIP-712 preimage of the underlying <code>AssociatedAccountRecord</code> using an appropriate <code>initiatorKeyType</code> validation mechanism.</li> <li>If the <code>approverSignature</code> field is populated, the signature MUST be valid for the EIP-712 preimage of the underlying <code>AssociatedAccountRecord</code> using an appropriate <code>approverKeyType</code> validation mechanism.</li> </ol> <p>Onchain validation is possible as long as there are sufficient validation mechanisms for the various key types used by the two accounts. In the case that validation occurs onchain, implementations MUST replace "current timestamp" with <code>block.timestamp</code>.</p> <h3 id="revocation">Revocation</h3> <p>Onchain Association stores MUST implement a revocation method. This method MUST allow either party of an Association to revoke a valid, active association by submitting a revocation request.</p> <p>In such contexts, storage contracts MUST update the <code>revokedAt</code> field of the SAR to <code>block.timestamp</code> OR the account-specified revocation timestamp, whichever is greater. Then the implementation contract MUST emit the following event upon accepting a valid revocation request:</p> <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"> AssociationRevoked</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> hash</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> revokedBy</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> revokedAt</span><span>)</span><span>;</span></span></code></pre> <p>where:</p> <ul> <li><code>hash</code> is the indexed unique identifier for the association, equivalent to the EIP-712 hash of the underlying AAR.</li> <li><code>revokedBy</code> is the indexed keccak256 hash of the ERC-7930 address of the revoking account.</li> <li><code>revokedAt</code> is the timestamp at which the association is revoked.</li> </ul> <p>Offchain stores MUST allow either account to revoke a stored association and MUST update the <code>revokedAt</code> timestamp accordingly.</p> <p>If a previously revoked association is revoked again with an earlier timestamp, the earlier timestamp MUST take precedence.</p> <h2 id="rationale">Rationale</h2> <h3 id="nested-structure-design">Nested Structure Design</h3> <p>The separation of <code>AssociatedAccountRecord</code> and <code>SignedAssociationRecord</code> into distinct structures serves a critical functional purpose. The inner <code>AssociatedAccountRecord</code> contains the immutable association payload that both parties must agree upon. This record can be shared, reviewed, and prepared while signatures are collected asynchronously from each party. The outer <code>SignedAssociationRecord</code> wrapper accumulates these signatures and metadata without modifying the underlying record.</p> <h3 id="lack-of-existing-standards">Lack of Existing Standards</h3> <p>Currently, no standardized mechanism exists for establishing verifiable associations between blockchain accounts. Existing approaches are either application-specific or rely on proprietary schemas that limit interoperability. This specification addresses that gap by providing a common format that can be adopted across applications, enabling portability and composability of identity relationships.</p> <h3 id="supporting-app-scoped-sub-accounts">Supporting App-Scoped Sub Accounts</h3> <p>Today's blockchain ecosystem enforces a rigid one-to-one relationship between onchain identities and addresses, limiting users to a single address per identity. This specification breaks that constraint by enabling users to maintain a unified identity across multiple addresses. Users benefit from maintaining separate accounts for different contexts or applications while preserving the ability to verifiably link them to a primary identity when desired. This standard provides the mechanism for establishing these connections, enabling app-scoped sub accounts that can be provably associated with a root identity without sacrificing the flexibility and security benefits of address separation.</p> <h3 id="storage-agnosticism">Storage Agnosticism</h3> <p>Different association types have varying requirements for accessibility, cost, and decentralization. High-value associations requiring maximum trust minimization may warrant onchain storage despite higher costs, while frequent or ephemeral associations may be better suited for offchain stores. By remaining agnostic to storage location and requiring only that validation rules be consistently applied, this specification allows implementers to choose the appropriate tradeoffs for their use case without fragmenting the standard itself.</p> <h2 id="security-considerations">Security Considerations</h2> <p>For onchain applications, the validation mechanisms for some key types might be gas-cost prohibitive or entirely unavailable. It is the responsibility of the integrator to ensure that unsupported key types are appropriately handled given these constraints.</p> <p>Offchain stores expose a trust vector to consumers. Integrators and consumers MUST take into account this centralization vector and expose the risk to users or offer mechanisms for minimizing the trust assumptions (i.e. storing some state onchain).</p> <p>Associations SHOULD have a canonical storage location given an application. However, in the event that the same Association data is stored both on and offchain, precedence SHOULD be given to the onchain data.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-11-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Luca Donnohttps://github.com/lucadonnohdonnoh@l2beat.com Justin Drakehttps://github.com/JustinDrakejustin@ethereum.org https://wg-eips.ritovision.com/8079/

Expose Ethereum's STF as a precompile for rollups to use

<h2 id="abstract">Abstract</h2> <p>Expose the state transition function to the execution layer via a new <code>EXECUTE</code> precompile.</p> <h2 id="motivation">Motivation</h2> <p>Today, EVM-equivalent rollups need to implement and maintain complex proof systems just to be able to replicate what Ethereum already provides on L1. Such complexity significantly increases the probability of encountering bugs and prevents projects from getting rid of security councils and from moving to Stage 2. EVM-equivalent projects are not similar enough and lack the proper incentives to benefit from each other efforts, significantly delaying multi-proof systems.</p> <p>Moreover, to maintain feature parity with Ethereum, rollups need to implement bespoke governance systems that can't be forced to follow Ethereum's governance decisions, and thus are free to arbitrarily diverge from it. Because of this, the best that an EVM-equivalent rollup can do is to provide long exit windows for their users, to protect them from its governance going rogue. No finite (and reasonable) exit window can protect all use-cases, especially those that rely on timelocks (governance, staking contracts, vesting contracts). Longer exit windows protect more use-cases, at the cost of increase un-equivalence time.</p> <p>This EIP provides a way for rollups to reuse Ethereum's state transition verification infrastructure, and as a consequence massively simplify their infrastructure and upgrade processes. This enables projects to better redirect resources towards user-facing features and products.</p> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <!-- TODO --> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>PROOF_TX_TYPE</code></td><td><code>Bytes1(TBD)</code></td></tr> <tr><td><code>EXECUTE_PRECOMPILE_ADDRESS</code></td><td><code>TBD</code></td></tr> <tr><td><code>ANCHOR_ADDRESS</code></td><td><code>TBD</code></td></tr> </tbody></table> <h3 id="execute-precompile"><code>EXECUTE</code> precompile</h3> <p>Add a precompile at <code>EXECUTE_PRECOMPILE_ADDRESS</code> that verifies a state transition function with the provided inputs.</p> <p>The precompile executes the following logic:</p> <!-- TODO --> <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"> execute</span><span>(</span><span class="z-variable z-parameter z-function">input</span><span>:</span><span> Bytes</span><span>)</span><span> -&gt;</span><span> Bytes</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"> Verify a `state_transition(chain: BlockChain, block: Block)`.</span></span> <span class="giallo-l"><span class="z-string"> Disable blob transactions and perform anchoring to enable L1-&gt;L2 messaging.</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> chain</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span class="z-constant">...</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> TBD</span></span> <span class="giallo-l"><span> block</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span class="z-constant">...</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> TBD</span></span> <span class="giallo-l"><span> anchor</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span class="z-constant">...</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> TBD</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> transactions</span><span class="z-keyword"> =</span><span> get_transactions</span><span>(</span><span>block</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"> Blob-carrying transactions are not supported</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> tx</span><span class="z-keyword"> in</span><span class="z-support"> map</span><span>(</span><span>decode_transaction</span><span>,</span><span> transactions</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> isinstance</span><span>(</span><span>tx</span><span>,</span><span> BlobTransaction</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> ExecuteError</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> block_env</span><span class="z-keyword"> =</span><span> get_block_env</span><span>(</span><span>chain</span><span>,</span><span> block</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"> Perform anchoring</span></span> <span class="giallo-l"><span> process_unchecked_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">ANCHOR_ADDRESS</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword"> =</span><span>anchor</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> state_transition</span><span>(</span><span>chain</span><span>,</span><span> block</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> Bytes</span><span>(</span><span class="z-constant">...</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> TBD</span></span></code></pre><h3 id="header-extension">Header extension</h3> <p>The current header encoding is extended with a new 64-bit unsigned integer field representing the total amount of native tokens burned in the current block as part of the base fee.</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>execution_payload_header_rlp = 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> burned_fees</span></span> <span class="giallo-l"><span>])</span></span></code></pre> <p>The cumulative value of <code>burned_fees</code> can be calculated as follows:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>burned_fees</span><span class="z-keyword"> =</span><span> effective_gas_fee</span><span class="z-keyword"> -</span><span> gas_refund_amount</span><span class="z-keyword"> -</span><span> transaction_fee</span><span class="z-keyword"> +</span><span> blob_gas_fee</span></span></code></pre> <p>By making the value available for L1, it is also automatically made available for native rollups too.</p> <h3 id="proof-carrying-transactions">Proof-carrying transactions</h3> <!-- TODO --> <p>TBD: heavily depends on the ZK L1 design.</p> <h2 id="rationale">Rationale</h2> <h3 id="programmable-consensus-layer">Programmable "consensus layer"</h3> <p>The <code>EXECUTE</code> precompile allows rollups to define their own inputs and constrained their behaviour through smart contract. For example, in contrast to Ethereum's own consensus layer, a rollup can decide to:</p> <ul> <li>Restrict the use of transactions that are sequenced by a permissioned entity, allowing for centralized sequencing and fast pre-confirmations, or leaving it open to everyone (based sequencing), or restrict it to a staked sequencer network;</li> <li>Fix the <code>coinbase</code> address to be a DAO-controlled treasury, independent from the proposer address;</li> <li>Tweak gas limits or prices based on specific needs;</li> </ul> <p>This allows projects to preserve most of their configurations they already benefits from.</p> <h3 id="gas-tokens">Gas tokens</h3> <p>Several rollups implement new transaction types to be able to mint the rollup gas token when depositing funds on L1. We decide not to introduce complexity and instead rely on general L1-&gt;L2 messaging to unlock pre-minted tokens, as other existing projects already do. As a consequence, projects are free to decide what type of L1 interaction triggers the release of the rollup gas token, trivially enabling custom gas tokens without the need to modify the EVM behaviour at all.</p> <h3 id="anchoring">Anchoring</h3> <p>To support L1-&gt;L2 messages, rollups need to be able to "anchor" information from L1 to the L2. Inspired by <a href="https://wg-eips.ritovision.com/4788/">EIP-4788</a> and existing implementations, we make use of a system transaction to inject a <code>bytes32 anchor</code> in the rollup state in a predeploy. This <code>anchor</code> can be used to relay L1's state root, a message root, or a rolling hash, or something completely different, based on design preferences.</p> <p>The trade-off of this approach, compared to some existing ones based on custom transaction types, is that the L2 side of an L1-&gt;L2 message cannot have the <code>msg.sender</code> derived from the sender on L1, and therefore L1 access control-based smart contracts need to be adapted when deployed on L2 and used with cross-chain permissions. We believe this trade-off to be acceptable as the same scenario already exists when supporting L2-&gt;L1 access controls, as Ethereum is already not natively aware of the L2 sender.</p> <h3 id="basefee-collection">Basefee collection</h3> <p>While Ethereum burns the base fee, most rollups collect it for themselves, which enables opinionated funding models that are not possible on L1. To enable this use-case, and to minimize the code changes, we simply expose the amount of fees burned through the <code>burned_fees</code> block header value. Projects can now decide to ignore the value, burning the L2 base fee too, or credit the amount to some address, allowing for base fee collection from the L1-&gt;L2 token escrow.</p> <h3 id="re-execution-vs-zk-proofs">Re-execution vs ZK proofs</h3> <!-- TODO --> <p>TBD</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Existing rollups can more or less easily migrate to being native based on their degree of equivalency, as native rollups do not support custom opcodes, custom precompiles or custom transaction types within the exposed state transition function.</p> <h2 id="test-cases">Test Cases</h2> <!-- TODO --> <p>TBD</p> <h2 id="reference-implementation">Reference Implementation</h2> <!-- TODO --> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <!-- TODO --> <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> 2025-11-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Francesco D'Amatohttps://github.com/fradamt https://wg-eips.ritovision.com/8080/

Allows exits to use consolidation queue, democratizing access to an unintended feature, improving liquidity while preserving security.

<h2 id="abstract">Abstract</h2> <p>This EIP allows exits to be routed through the consolidation queue when it is shorter than the exit queue, consuming churn that is allocated to consolidations. This democratizes access to a feature that is currently only available to validators with at least 2048 ETH through a loophole in the consolidation logic. The protocol then makes more efficient usage of the churn that its security parameters (weak subjectivity period) allow, and is able to process more exits without any security reduction.</p> <h2 id="motivation">Motivation</h2> <p>The existing design of consolidation mechanism allows validators with at least 2048 ETH to use the consolidation queue for exits through a loophole in the consolidation logic. When there is an imbalance between exit and consolidation queues favoring the latter, as has been the case since the introduction of the consolidation feature, this becomes an appealing way to speed up withdrawals. However, this feature is only available to a subset of validators, creating an unfair advantage.</p> <p>Rather than removing this unintended feature, this EIP democratizes it by making it available to all exits. This approach preserves fairness by ensuring equal access to this efficiency improvement, while also providing concrete benefits to the network. When consolidation activity is low, the consolidation churn would otherwise go unused. By allowing exits to use this churn, we ensure it is not wasted and can be put to productive use. This is particularly important given the current state of exit queue congestion, as the exit queue has been longer than forty days for an extended period of time. Long queues degrade user experience, slow operator response to market or operational events, and reduce the network's ability to reconfigure stake more quickly after adverse events. Besides, solo stakers are arguably the participants that suffer the most from a lack of liquidity today, as they do not have the ability to issue a liquid staking token or maintain liquidity reserves.</p> <p>By allowing exits to use consolidation churn when available, the maximum exit throughput increases significantly, without any security reduction since we are only reallocating churn that the protocol has already accounted for. In particular, the maximum exit churn that can be processed becomes <code>get_activation_exit_churn_limit(state) + 3 * get_consolidation_churn_limit(state) // 2</code>, where the <code>3 // 2</code> factor comes from the fact that one unit of exit churn corresponds to 2/3 of a unit of consolidation churn. With current parameters and with the current total stake approximately 35.7M ETH, this results in 256 (the capped exit churn) + (544 - 256) * 3/2 (the consolidation churn adjusted by the 3/2 factor) = 688 ETH per epoch, representing approximately a 2.5x increase over the current maximum exit churn of 256 ETH per epoch.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <p>Starting from the beginning of the epoch when this EIP is activated, Consensus Layer clients <strong>MUST</strong> use the modified <code>compute_exit_epoch_and_update_churn</code> function which routes exits through the consolidation queue when it is shorter than the exit queue.</p> <h3 id="modified-compute-exit-epoch-and-update-churn">Modified <code>compute_exit_epoch_and_update_churn</code></h3> <p>The only modification is this addition at the start of <code>compute_exit_epoch_and_update_churn</code>:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword"> if</span><span> state</span><span>.</span><span>earliest_exit_epoch</span><span class="z-keyword"> &gt;</span><span> state</span><span>.</span><span>earliest_consolidation_epoch</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> compute_consolidation_epoch_and_update_churn</span><span>(</span><span>state</span><span>,</span><span class="z-constant"> 2</span><span class="z-keyword"> *</span><span> exit_balance</span><span class="z-keyword"> //</span><span class="z-constant"> 3</span><span>)</span></span></code></pre> <p>In particular, we route exits through the consolidation queue whenever <code>state.earliest_exit_epoch &gt; state.earliest_consolidation_epoch</code>, by using <code>compute_consolidation_epoch_and_update_churn</code>. Note that the <code>exit_balance</code> passed to the latter is only <code>2 * exit_balance // 3</code>, because each unit of exit churn corresponds to 2/3 units of consolidation churn from a weak subjectivity perspective. This way, we keep the weak subjectivity impact of the consolidation queue the same regardless of whether it is used by consolidations or by exits, maximizing the amount of operations we can process while keeping the same security guarantees.</p> <p>The full function 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"> 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> activation_exit_epoch</span><span class="z-keyword"> =</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 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> activation_exit_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"> NEW in this EIP</span></span> <span class="giallo-l"><span> earliest_consolidation_epoch</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span>state</span><span>.</span><span>earliest_consolidation_epoch</span><span>,</span><span> activation_exit_epoch</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> earliest_exit_epoch</span><span class="z-keyword"> &gt;</span><span> earliest_consolidation_epoch</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> compute_consolidation_epoch_and_update_churn</span><span>(</span><span>state</span><span>,</span><span class="z-constant"> 2</span><span class="z-keyword"> *</span><span> exit_balance</span><span class="z-keyword"> //</span><span class="z-constant"> 3</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"> UNCHANGED FROM HERE</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-keyword"> return</span><span> state</span><span>.</span><span>earliest_exit_epoch</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The decision to democratize access to this unintended feature, rather than removing it or keeping it as is, is driven by:</p> <ol> <li><strong>Fairness</strong>: All validators gain equal access to this efficiency improvement, rather than it being restricted to those with at least 2048 ETH who can exploit the loophole.</li> <li><strong>Efficiency</strong>: When consolidation activity is low, the consolidation churn would otherwise go unused. By allowing exits to use this churn, we ensure it is not wasted and can be put to productive use, improving staking liquidity with unchanged security guarantees.</li> </ol> <p>To summarize, fairness is a strong motivation to either remove the feature or democratize it, and democratizing it is preferable to removing because we get a lot of efficiency benefits from it without any security cost.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces backwards-incompatible changes to the Consensus Layer and must be activated via scheduled network upgrade.</p> <h2 id="test-cases">Test Cases</h2> <p>&lt;-- TODO --&gt;</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="weak-subjectivity-period">Weak subjectivity period</h3> <p>This EIP does not impact the weak subjectivity period at all. The total churn remains the same, it is just allocated differently. In particular, the conversion factor (<code>exit_balance * 2 // 3</code>) preserves the same weak subjectivity impact regardless of whether consolidation churn is allocated to exits or to consolidations.</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-11-07T00:00:00+00:00 2026-02-11T14:49:27+00:00 Csaba Kiralyhttps://github.com/cskiraly https://wg-eips.ritovision.com/8077/

Adds source and nonce to transaction announcements

<h2 id="abstract">Abstract</h2> <p>This EIP improves mempool propagation, extending the devp2p 'eth' protocol's <code>NewPooledTransactionHashes</code> message to also announce each transaction's source address and nonce together with the already announced hash, type, and size.</p> <h2 id="motivation">Motivation</h2> <p>Transactions are propagated in the Mempool using the devp2p protocol in two modalities. Eager push is only used for small transactions, and only towards a few nodes, while the rest of nodes receive only announcements. For large transactions and for type 3 transactions, only announcements are sent. This announcement is made using the <code>NewPooledTransactionHashes</code> message, which only contains the hash, the type and the size of each transaction. As it is now, the receiver of the announcement does not have enough information to make intelligent scheduling choices. This crates several issues:</p> <ul> <li>the receiver of the announcement can only base its logic on the order of announcements, but if it schedules requests to different peers, it can easily end up pulling transactions that leave a nonce gap in it's own view of the mempool, making the pulled transaction non-includable,</li> <li>filling existing gaps is hard, since in the absence of sender/nonce information it can only be done with trial and error, requesting more transactions of missing hashes,</li> <li>to filter out old transaction announcements, the node has to keep a cache of all transaction hashes on chain, instead of simply checking the nonce against current chain state,</li> <li>receivers have no way to selectively request transactions with specific source addresses, which would be important UX and L2s.</li> </ul> <p>Moreover, as we are increasing the throughput of block building, it is more and more probable that we end up in a state where nodes can't fetch all transactions. This extension allows nodes to do selective fetching and gap filling while keeping a consistent state of their own view of the mempool without nonce gaps.</p> <h2 id="specification">Specification</h2> <h3 id="newpooledtransactionhashes-message-changes">NewPooledTransactionHashes message changes</h3> <p>Modify the NewPooledTransactionHashes (0x08) message as follows:</p> <p>(eth/69): [txtypes: B, [txsize₁: P, txsize₂: P, ...], [txhash₁: B_32, txhash₂: B_32, ...]]</p> <p>(eth/XX): [txtypes: B, [txsize₁: P, txsize₂: P, ...], [txhash₁: B_32, txhash₂: B_32, ...], [txsource₁: B_20, txsource₂: B_20, ...], [txnonce₁: P, txnonce₂: P, ...]]</p> <h3 id="changes-to-message-handling">Changes to message handling</h3> <p>Changes on the sender side of <code>NewPooledTransactionHashes</code> messages are trivial. Only the transmitted data changes. Since the size of announcements is increased, implementations MAY revisit the condition (typically transaction size) to select between eager push and announcement.</p> <p>At the receiver side of <code>NewPooledTransactionHashes</code> messages the extra information can be used to improve scheduling choices, however these are not mandated by the protocol and thus we leave it to implementations.</p> <h2 id="rationale">Rationale</h2> <p>To solve the transaction propagation issues mentioned in the Motivation section, nodes require more information about a transaction then its hash, size, and type. By adding the source and the nonce, the receiver has enough information to make better fetch decisions.</p> <h3 id="overhead">Overhead</h3> <p>The modification adds a significant overhead to announcements by adding a B_20 and a variable size filed to the current B_32, size, and type fields. We think this overhead is worth the additional gain in protocol efficiency. Details TBD &lt;-- TODO --&gt; .</p> <h3 id="alternatives">Alternatives</h3> <p>While the modification is relatively straightforward, there are several design variants to consider. First of all, small transactions are mostly propagating by the push mechanism, while announcement based pull is only used as recovery. We could choose to avoid the extra announcement overhead for these, however it would mean that filling nonce gaps remains difficult, only possible by trial-and-error.</p> <p>Another possibility similar to the previous one is to restrict the mechanism to blob transactions only. We choose not to restrict it in the proposal for the same reasons as in the previous point.</p> <p>If the traffic overhead from notifications is a concern, it is also worth considering how many nodes should announcements be sent to. While this is not mandated by the protocol, a typical implementation is to send announcements to all neighbors (except the ones that already signaled having it, and the ones to which the message is pushed). Should nodes send announcements to all peers, or only part of their peer set (e.g. proportional, or to a fixed number of peers)? The protocol allows to only part, and in case of bandwidth constraints it seems better to send more metadata (addresses and nonces) to fewer peers.</p> <p>Currently, for any given transaction, nodes receive announcements from many peers. About half of their peers, on average. Having the whole metadata (txhash, type, size, source, nonce) in all these is highly redundant. We could remove some of this overhead, e.g. by having a probabilistic choice between a simple announcement and a detailed announcement. The gain however seems marginal compared to the added complexity.</p> <p>Sending the source and the nonce opens up the possibility of a design variant where the transaction identifier in the announcements is based on these values, and not on the txhash. More specifically, a transaction could be identified by the source, the nonce, and an extra version number signaling the RBF (replace-by-fee) version in the given source/nonce scope. This variant would require deeper changes since the RBF version would need to be signed.</p> <p>As an alternative to the above, fee values can be used as a proxy for the RBF version. Since the RBF requirement is anyway fee based, and the fee is already signed, adding the fee information to the announcement allows the receiver to compare different versions and pull the newer one. Moreover, having the fee information already in the announcement also allows nodes to anticipate their transaction ordering decisions and avoid pulling transactions that would be dropped, providing further traffic reduction.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP changes the eth protocol and requires rolling out a new version. Supporting multiple versions of a wire protocol is routine practice. Rolling out this new version does not break older clients, since they can keep using the previous protocol version.</p> <p>This EIP does not change consensus rules of the EVM and does not require a hard fork.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The announced source address and nonce cannot be verified by the recipient until the transaction is actually fetched (or received through eager push). Therefore, it should not be handled as trusted information. This does not compromise the security of the protocol.</p> <p>A mismatch between the announced &lt;txhash,type,size,address,nonce&gt; tuple and a received transaction should be handled as a protocol violation. More in detail, after the verification of the transaction hash, it becomes clear that the sender of the announcement was either malicious, or it sent an announcement without verifying its content. Thus, the sender of the offending announcement can be treated as a node that violated the protocol.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via CC0.</p> 2025-10-31T00:00:00+00:00 2026-02-11T14:49:27+00:00 Łukasz Rozmejhttps://github.com/LukaszRozmej https://wg-eips.ritovision.com/8072/

Submit transactions and subscribe to transaction inclusion events using eth_subscribe

<h2 id="abstract">Abstract</h2> <p>This EIP extends the existing <code>eth_subscribe</code> JSON-RPC method with a new subscription type <code>transactionInclusion</code> that enables clients to receive real-time notifications when transactions are included in blocks. This subscription-based approach provides efficient transaction confirmation monitoring without blocking connections, supporting both combined transaction submission and monitoring in a single call, as well as monitoring of already-submitted transactions.</p> <h2 id="motivation">Motivation</h2> <p>Current transaction submission workflows require separate calls to <code>eth_sendRawTransaction</code> followed by repeated polling of <code>eth_getTransactionReceipt</code>, creating unnecessary latency and network overhead. While <a href="https://wg-eips.ritovision.com/7966/">EIP-7966</a> proposes <code>eth_sendRawTransactionSync</code> to address this through a synchronous blocking approach, blocking HTTP connections presents significant drawbacks:</p> <ul> <li><strong>Connection hogging</strong>: Each transaction blocks one HTTP connection until confirmation or timeout</li> <li><strong>Limited scalability</strong>: Cannot efficiently monitor multiple transactions over a single connection</li> <li><strong>Timeout complexity</strong>: Requires careful tuning of timeout parameters for different blockchain slot times</li> <li><strong>Resource inefficiency</strong>: Repeated polling consumes bandwidth and server resources</li> </ul> <p>The subscription-based approach leverages the battle-tested <code>eth_subscribe</code> mechanism already implemented across all major Ethereum clients, providing superior resource efficiency and scalability while maintaining feature parity with synchronous approaches.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="new-subscription-type">New Subscription Type</h3> <p>A new subscription type <code>transactionInclusion</code> is added to the <code>eth_subscribe</code> method.</p> <h3 id="subscription-request">Subscription Request</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">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"> 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">eth_subscribe</span><span class="z-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 class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">transactionInclusion</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">transaction</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">includeReorgs</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span> }</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Or for monitoring an already-submitted transaction:</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"> 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">eth_subscribe</span><span class="z-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 class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">transactionInclusion</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">hash</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">includeReorgs</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span> }</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="parameters">Parameters</h3> <p>The subscription parameters object accepts the following fields:</p> <ul> <li><code>transaction</code> (DATA, optional): Signed transaction data to submit and monitor. When provided, the node MUST immediately submit this transaction to the network.</li> <li><code>hash</code> (DATA, 32 bytes, optional): Transaction hash to monitor for already-submitted transactions.</li> <li><code>includeReorgs</code> (boolean, optional, default: <code>false</code>): Controls reorg monitoring behavior. <ul> <li>If <code>false</code>: Subscription auto-unsubscribes immediately after first inclusion notification. Reorgs are not monitored.</li> <li>If <code>true</code>: Subscription actively monitors for reorgs and sends notifications for reorgs, re-inclusions, and finalization.</li> </ul> </li> </ul> <p><strong>Exactly one</strong> of <code>transaction</code> or <code>hash</code> MUST be provided. If both or neither are provided, the node MUST return a JSON-RPC error with code <code>-32602</code> (Invalid params).</p> <h3 id="subscription-response">Subscription Response</h3> <p>Upon successful subscription, the node MUST return a subscription ID:</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"> 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">0x1234567890abcdef</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="notification-format">Notification Format</h3> <p>When the transaction status changes, the node MUST send a 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">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">subscription</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1234567890abcdef</span><span class="z-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">status</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">included</span><span class="z-punctuation z-definition z-string">&quot;</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 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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">blockNumber</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">transactionIndex</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">receipt</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">0x...</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">transactionIndex</span><span class="z-support">&quot;</span><span>:</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></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 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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">blockNumber</span><span class="z-support">&quot;</span><span>:</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></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">0x...</span><span class="z-punctuation z-definition z-string">&quot;</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">0x...</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">cumulativeGasUsed</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasUsed</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">contractAddress</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">logs</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">logsBloom</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">status</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> <p>The <code>status</code> field MAY be one of:</p> <ul> <li><code>"included"</code>: Transaction has been included in a block</li> <li><code>"finalized"</code>: Transaction's block has reached finality (only sent when <code>includeReorgs</code> is <code>true</code>)</li> <li><code>"reorged"</code>: Transaction was removed from the canonical chain (only sent if <code>includeReorgs</code> is <code>true</code>)</li> </ul> <p>The <code>receipt</code> field MUST contain the complete transaction receipt object as defined by <code>eth_getTransactionReceipt</code>.</p> <h3 id="behavior">Behavior</h3> <p>The node MUST implement the following behavior:</p> <ol> <li> <p><strong>When <code>transaction</code> is provided</strong>:</p> <ul> <li>The node MUST immediately submit the transaction to the network using the same semantics as <code>eth_sendRawTransaction</code></li> <li>The node MUST derive the transaction hash and begin monitoring for inclusion</li> <li>If submission fails, the node MUST return a JSON-RPC error and MUST NOT create the subscription</li> </ul> </li> <li> <p><strong>Transaction Already Included</strong>:</p> <ul> <li>If the monitored transaction is already included in a block at subscription time: <ul> <li>If <code>includeReorgs</code> is <code>false</code>: The node MUST immediately send an inclusion notification and automatically unsubscribe</li> <li>If <code>includeReorgs</code> is <code>true</code>: The node MUST immediately send an inclusion notification and continue monitoring until finalization</li> </ul> </li> </ul> </li> <li> <p><strong>Pending Transaction</strong>:</p> <ul> <li>The node MUST monitor the transaction pool and canonical chain</li> <li>When the transaction is included in a block, the node MUST send an inclusion notification</li> <li>If <code>includeReorgs</code> is <code>false</code>, the node MUST then automatically unsubscribe</li> <li>If <code>includeReorgs</code> is <code>true</code>, the node MUST continue monitoring</li> </ul> </li> <li> <p><strong>Reorg Monitoring</strong> (when <code>includeReorgs</code> is <code>true</code>):</p> <ul> <li>The node MUST continue monitoring the transaction after initial inclusion</li> <li>If the transaction is removed from the canonical chain due to a reorg, the node MUST send a notification with <code>"status": "reorged"</code></li> <li>If the transaction is re-included in a different block, the node MUST send a new inclusion notification with <code>"status": "included"</code></li> <li>When the block containing the transaction reaches finality, the node MUST send a finalization notification with <code>"status": "finalized"</code></li> <li>The node MUST automatically unsubscribe after sending the finalization notification</li> </ul> </li> <li> <p><strong>Auto-unsubscribe</strong>:</p> <ul> <li>If <code>includeReorgs</code> is <code>false</code>, the node MUST automatically unsubscribe after sending the first inclusion notification</li> <li>The node SHOULD send an <code>eth_subscription</code> unsubscribe confirmation</li> </ul> </li> <li> <p><strong>Transaction Not Found</strong>:</p> <ul> <li>If monitoring a transaction by <code>hash</code> that doesn't exist in the mempool or chain, the subscription remains active</li> <li>The node SHOULD monitor for the transaction appearing in the future</li> <li>Clients MAY manually unsubscribe if desired</li> </ul> </li> </ol> <h2 id="rationale">Rationale</h2> <h3 id="why-subscription-over-synchronous">Why Subscription Over Synchronous?</h3> <p>Subscriptions provide several advantages over the synchronous approach proposed in EIP-7966:</p> <ul> <li><strong>Non-blocking</strong>: Clients can perform other operations while waiting for confirmation</li> <li><strong>Multiplexing</strong>: Multiple transactions can be monitored over a single WebSocket connection</li> <li><strong>No timeout complexity</strong>: Subscriptions naturally handle varying confirmation times without timeout parameters</li> <li><strong>Proven infrastructure</strong>: Leverages existing <code>eth_subscribe</code> implementation present in all major clients</li> </ul> <p>The addition of the <code>transaction</code> parameter provides complete feature parity with <code>eth_sendRawTransactionSync</code> by enabling submission and monitoring in a single call.</p> <h3 id="why-extend-eth-subscribe">Why Extend <code>eth_subscribe</code>?</h3> <p>The <code>eth_subscribe</code> mechanism is battle-tested and already implemented across all major Ethereum clients. Extending it with a new subscription type requires minimal implementation effort compared to introducing entirely new RPC methods.</p> <h3 id="why-support-both-transaction-and-hash">Why Support Both <code>transaction</code> and <code>hash</code>?</h3> <p>Supporting both parameters provides maximum flexibility:</p> <ul> <li><code>transaction</code>: Optimal for new transactions, matching the convenience of synchronous methods</li> <li><code>hash</code>: Enables monitoring of transactions submitted through other means or by other parties</li> </ul> <h3 id="why-support-reorg-monitoring">Why Support Reorg Monitoring?</h3> <p>Applications requiring high confidence in transaction finality benefit from reorg notifications. This is particularly important on chains with faster block times where reorgs may be more common. The optional nature of this feature allows applications to choose the appropriate trade-off between functionality and resource usage.</p> <h3 id="resource-efficiency">Resource Efficiency</h3> <p>A single WebSocket connection can support unlimited concurrent transaction subscriptions, whereas synchronous approaches require one blocking HTTP connection per transaction. This represents a significant improvement in resource utilization for applications monitoring multiple transactions.</p> <h3 id="why-always-auto-unsubscribe">Why Always Auto-unsubscribe?</h3> <p>Both modes auto-unsubscribe to prevent unbounded subscription accumulation and provide clear lifecycle management:</p> <ul> <li><strong><code>includeReorgs: false</code></strong>: Unsubscribes immediately after first inclusion for fast feedback with minimal resource usage. Users accepting this mode understand the transaction may still be reorged and can manually monitor if needed.</li> <li><strong><code>includeReorgs: true</code></strong>: Unsubscribes after finalization when reorgs are no longer possible, providing complete transaction lifecycle monitoring.</li> </ul> <p>The key difference is the level of guarantee:</p> <ul> <li><code>includeReorgs: false</code>: Fast notification, transaction is included (may still reorg)</li> <li><code>includeReorgs: true</code>: Complete lifecycle tracking until finality (cannot reorg)</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible. It extends the existing <code>eth_subscribe</code> method with a new subscription type. Clients that have not implemented this feature will return a standard JSON-RPC error indicating the subscription type is not supported. Existing applications continue to function unchanged.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="test-case-1-submit-and-monitor">Test Case 1: Submit and Monitor</h3> <p><strong>Request:</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">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"> 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">eth_subscribe</span><span class="z-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 class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">transactionInclusion</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">transaction</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf86c098504a817c800825208943535353535353535353535353535353535353535880de0b6b3a76400008025a028ef61340bd939bc2195fe537567866003e1a15d3c71ff63e1590620aa636276a067cbe9d8997f761aecb703304b3800ccf555c9f3dc64214b297fb1966a3b6d83</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><strong>Expected Behavior:</strong></p> <ol> <li>Node submits transaction to network</li> <li>Node returns subscription ID</li> <li>When transaction is included, node sends notification with <code>"status": "included"</code> and receipt</li> <li>Subscription automatically closes immediately</li> </ol> <h3 id="test-case-2-monitor-existing-transaction">Test Case 2: Monitor Existing Transaction</h3> <p><strong>Request:</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">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"> 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">eth_subscribe</span><span class="z-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 class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">transactionInclusion</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">hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">includeReorgs</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span> }</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>Expected Behavior:</strong></p> <ol> <li>If transaction already included, immediately send notification with <code>"status": "included"</code></li> <li>If transaction pending, wait and send notification upon inclusion</li> <li>Subscription automatically closes immediately after notification</li> </ol> <h3 id="test-case-3-reorg-monitoring">Test Case 3: Reorg Monitoring</h3> <p><strong>Request:</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">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"> 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">eth_subscribe</span><span class="z-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 class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">transactionInclusion</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">hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">includeReorgs</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></span></code></pre> <p><strong>Expected Behavior:</strong></p> <ol> <li>Send inclusion notification when transaction is included (with <code>"status": "included"</code>)</li> <li>Continue monitoring for reorgs</li> <li>If reorg occurs, send reorg notification (with <code>"status": "reorged"</code>)</li> <li>If re-included, send new inclusion notification (with <code>"status": "included"</code>)</li> <li>When block is finalized, send finalization notification (with <code>"status": "finalized"</code>)</li> <li>Subscription automatically closes after finalization</li> </ol> <h3 id="test-case-4-invalid-parameters">Test Case 4: Invalid Parameters</h3> <p><strong>Request:</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">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"> 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">eth_subscribe</span><span class="z-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 class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">transactionInclusion</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">includeReorgs</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span> }</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>Expected Response:</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">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"> 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"> -32602</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 params: exactly one of transaction or hash must be provided</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="reference-implementation">Reference Implementation</h2> <p>A minimal reference implementation can be realized by:</p> <ol> <li>For <code>transaction</code> parameter: Call internal <code>eth_sendRawTransaction</code> logic and capture the transaction hash</li> <li>Register the transaction hash in a subscription manager</li> <li>Monitor the transaction pool and canonical chain for the transaction</li> <li>When the transaction is included in a block, query the receipt and send notification</li> <li>If <code>includeReorgs</code> is false, automatically unsubscribe after first inclusion</li> <li>If <code>includeReorgs</code> is true, continue monitoring for chain reorganizations</li> </ol> <p>Implementation pseudo-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"> handle_transaction_inclusion_subscription</span><span>(</span><span class="z-variable z-parameter z-function">params</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">transaction</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> in</span><span> params</span><span>:</span></span> <span class="giallo-l"><span> tx_hash</span><span class="z-keyword"> =</span><span> submit_transaction</span><span>(</span><span>params</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">transaction</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">hash</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> in</span><span> params</span><span>:</span></span> <span class="giallo-l"><span> tx_hash</span><span class="z-keyword"> =</span><span> params</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">hash</span><span class="z-punctuation z-definition z-string">&#39;</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"> raise</span><span> InvalidParamsError</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> include_reorgs</span><span class="z-keyword"> =</span><span> params</span><span>.</span><span>get</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">includeReorgs</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-constant"> False</span><span>)</span></span> <span class="giallo-l"><span> subscription_id</span><span class="z-keyword"> =</span><span> generate_subscription_id</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> register_subscription</span><span>(</span><span>subscription_id</span><span>,</span><span> tx_hash</span><span>,</span><span> include_reorgs</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> subscription_id</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"> on_block_added</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"> for</span><span> tx</span><span class="z-keyword"> in</span><span> block</span><span>.</span><span>transactions</span><span>:</span></span> <span class="giallo-l"><span> subscriptions</span><span class="z-keyword"> =</span><span> get_subscriptions_for_tx</span><span>(</span><span>tx</span><span>.</span><span>hash</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> sub</span><span class="z-keyword"> in</span><span> subscriptions</span><span>:</span></span> <span class="giallo-l"><span> receipt</span><span class="z-keyword"> =</span><span> get_transaction_receipt</span><span>(</span><span>tx</span><span>.</span><span>hash</span><span>)</span></span> <span class="giallo-l"><span> send_notification</span><span>(</span><span>sub</span><span>.</span><span>id</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">included</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> receipt</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> sub</span><span>.</span><span>include_reorgs</span><span>:</span></span> <span class="giallo-l"><span> unsubscribe</span><span>(</span><span>sub</span><span>.</span><span>id</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"> on_chain_reorg</span><span>(</span><span class="z-variable z-parameter z-function">old_blocks</span><span>,</span><span class="z-variable z-parameter z-function"> new_blocks</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> removed_txs</span><span class="z-keyword"> =</span><span> get_transactions_from_blocks</span><span>(</span><span>old_blocks</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> tx_hash</span><span class="z-keyword"> in</span><span> removed_txs</span><span>:</span></span> <span class="giallo-l"><span> subscriptions</span><span class="z-keyword"> =</span><span> get_subscriptions_for_tx</span><span>(</span><span>tx_hash</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> sub</span><span class="z-keyword"> in</span><span> subscriptions</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> sub</span><span>.</span><span>include_reorgs</span><span>:</span></span> <span class="giallo-l"><span> send_notification</span><span>(</span><span>sub</span><span>.</span><span>id</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">reorged</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-constant"> None</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"> on_block_finalized</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"> for</span><span> tx</span><span class="z-keyword"> in</span><span> block</span><span>.</span><span>transactions</span><span>:</span></span> <span class="giallo-l"><span> subscriptions</span><span class="z-keyword"> =</span><span> get_subscriptions_for_tx</span><span>(</span><span>tx</span><span>.</span><span>hash</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> sub</span><span class="z-keyword"> in</span><span> subscriptions</span><span>:</span></span> <span class="giallo-l"><span> receipt</span><span class="z-keyword"> =</span><span> get_transaction_receipt</span><span>(</span><span>tx</span><span>.</span><span>hash</span><span>)</span></span> <span class="giallo-l"><span> send_notification</span><span>(</span><span>sub</span><span>.</span><span>id</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">finalized</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> receipt</span><span>)</span></span> <span class="giallo-l"><span> unsubscribe</span><span>(</span><span>sub</span><span>.</span><span>id</span><span>)</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <h3 id="transaction-submission-validation">Transaction Submission Validation</h3> <p>When <code>transaction</code> is provided, nodes MUST perform the same validation as <code>eth_sendRawTransaction</code> before creating the subscription. Invalid transactions MUST result in an error response without creating a subscription.</p> <h3 id="privacy-considerations">Privacy Considerations</h3> <p>Monitoring transactions by hash does not introduce new privacy concerns beyond existing <code>eth_getTransactionReceipt</code> polling. However, applications should be aware that subscribing to transaction hashes reveals interest in those transactions to the node operator.</p> <h3 id="reorg-attack-considerations">Reorg Attack Considerations</h3> <p>Applications using <code>includeReorgs: true</code> should implement appropriate logic to handle reorg notifications, particularly on chains where reorgs may be used maliciously. The notification mechanism provides transparency but does not prevent reorg-based 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> 2025-10-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 Andrew Richardsonhttps://github.com/awrichar https://wg-eips.ritovision.com/8074/

Defines a convention for self-describing structured data in `bytes` parameters using 4-byte selectors derived from EIP-712 type strings.

<h2 id="abstract">Abstract</h2> <p>This ERC standardizes a convention for tagging ABI-encoded structures placed inside <code>bytes</code> parameters with a compact type selector derived from the <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> type string. It also defines a canonical multi-payload wrapper, allowing multiple typed payloads to be carried in a single <code>bytes</code> parameter.</p> <h2 id="motivation">Motivation</h2> <p>Many smart contract methods use a <code>bytes</code> parameter to support future extensibility—including common standards such as <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>. The convention of carrying extra data in a <code>bytes</code> parameter was also codified further in <a href="https://wg-eips.ritovision.com/5750/">ERC-5750</a>.</p> <p>In many practical cases, the <code>bytes</code> payload may encode a structured type that must be ABI-decoded before it can be processed. However:</p> <ul> <li>Different contracts use different, ad-hoc conventions for distinguishing among possible payloads.</li> <li>A single contract may need to support multiple encodings.</li> <li>In more complex workflows, a payload may be propagated across multiple contracts, each of which may need to parse it differently.</li> </ul> <p>Currently, there is no standardized convention for identifying the "type" of an encoded payload, nor for supporting multiple data items in a single bytes parameter. This ERC defines a minimal, interoperable convention for self-describing payloads that remain compatible with existing ABI tooling.</p> <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="terms">Terms</h3> <ul> <li><strong>Type string</strong> — the canonical EIP-712 type string, e.g. <code>TransferNote(bytes32 reference,string comment,uint256 deadline)</code></li> <li><strong>Type selector (<code>bytes4</code>)</strong> — <code>keccak256(typeString)[0:4]</code></li> <li><strong>Single-payload</strong> — a selector followed by <code>abi.encode</code> of that struct’s fields</li> <li><strong>Multi-payload wrapper</strong> — <code>DataList(bytes[] items)</code>; each <code>items[i]</code> is a valid single-payload</li> </ul> <h3 id="single-payload-encoding">Single-payload encoding</h3> <ul> <li>An ABI-encoded struct is prefixed with a 4-byte selector.</li> <li>The selector is defined as the first 4 bytes of the keccak256 hash of its EIP-712 type string.</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>typeSelector(T) = bytes4(keccak256(bytes(T)))</span></span> <span class="giallo-l"><span>encoding = typeSelector(T) ++ abi.encode(&lt;fields of T&gt;)</span></span></code></pre> <p>Example:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>T = &quot;TransferNote(bytes32 reference,string comment,uint256 deadline)&quot;</span></span> <span class="giallo-l"><span>keccak256(T) = 0xf91f3a243a886588394dfd70af07dce0ca18c55e402d76152d4cb300349c9e9d</span></span> <span class="giallo-l"><span>selector = 0xf91f3a24</span></span> <span class="giallo-l"><span>encoding = 0xf91f3a24 ++ abi.encode(reference, comment, deadline)</span></span></code></pre> <p>A consumer may look for a known selector before attempting to decode the data, and can easily distinguish between multiple different payloads that it knows how to accept.</p> <h3 id="multi-payload-wrapper">Multi-payload wrapper</h3> <ul> <li>Uses a canonical wrapper type <code>DataList(bytes[] items)</code> with selector <code>0xae74f986</code>.</li> <li>Each element in the items array is itself a single-struct payload (with its own selector).</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>DataList(bytes[] items)</span></span> <span class="giallo-l"><span>selector(DataList) = bytes4(keccak256(&quot;DataList(bytes[] items)&quot;)) = 0xae74f986</span></span> <span class="giallo-l"><span>encoding = 0xae74f986 ++ abi.encode(items)</span></span></code></pre> <p>Each <code>items[i]</code> MUST be a valid single-payload as above. Consumers can look for this well-known selector, and can then decode the list to be scanned recursively for recognized items.</p> <h3 id="decoding">Decoding</h3> <ul> <li>Read the first 4 bytes as the <strong>selector</strong>.</li> <li>If the selector is <code>0xae74f986</code>, decode the remainder as <code>(bytes[] items)</code> and parse each item recursively.</li> <li>If the selector is another recognized selector, the remainder should be parsed accordingly.</li> <li>Unknown selectors MUST be ignored.</li> <li>Order is not significant; producers SHOULD avoid duplicates.</li> </ul> <h2 id="rationale">Rationale</h2> <ul> <li><strong>EIP-712 reuse:</strong> avoids new schema syntax and aligns with the signing ecosystem.</li> <li><strong>4-byte selectors:</strong> mirror Solidity’s function selector convention for compactness.</li> <li><strong>Simple wrapper:</strong> <code>DataList</code> provides multiplexing without special parsing or new ABI rules.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Existing contracts that already accept arbitrary <code>bytes</code> remain compatible. Contracts unaware of this ERC can continue to treat the payload as opaque.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li><strong>Payload bounds:</strong> When parsing <code>DataList</code>, consumers should limit <code>items.length</code> and total payload size (for example ≤ 8 items and ≤ 8 KB).</li> <li><strong>Early exit:</strong> Consumers should stop scanning once all expected selectors are found.</li> <li><strong>Unknown data:</strong> Unrecognized items must be ignored safely.</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> 2025-10-29T00:00:00+00:00 2026-02-11T14:49:27+00:00 Raúl Kripalanihttps://github.com/raulk Bosul Munhttps://github.com/healthykim Francesco D'Amatohttps://github.com/fradamt Csaba Kiralyhttps://github.com/cskiraly Felix Langehttps://github.com/fjl Marios Ioannouhttps://github.com/mariosioannou-create Alex Stokeshttps://github.com/ralexstokes https://wg-eips.ritovision.com/8070/

Introduce custody-aligned sampling in the EL blobpool to vacate bandwidth

<h2 id="abstract">Abstract</h2> <p>This proposal introduces the sparse blobpool, a construction that brings cell-level, custody-aligned sampling in the Execution Layer (EL). For every new type 3 (blob-carrying) transaction, an EL node fetches full blob payloads only with probability p = 0.15, and otherwise it merely samples the blobs, using the same custody assignment as its Consensus Layer (CL) counterpart. For full nodes, this means downloading as little as 1/8 of the data (8 out of 128 cells), so that the average bandwidth consumption compared to the (current) full blobpool is 0.15 + 0.85/8 ~ 0.25, a ~4x reduction. The choice of p = 0.15 balances reducing bandwidth consumption with guaranteeing the full propagation of txs, by ensuring that for each blob tx there exists a large connected backbone of nodes that have the full blob payload. At an individual node level, p = 0.15 translates to 98.6% probability of least 3/50 neighbours holding the full blob payload, only 0.03% chance of total unavailability. The sampling performed with probability 1 - p = 0.85 enables streamlined data availability checks during block validation, as well as enhancing the availability of the data.</p> <h2 id="motivation">Motivation</h2> <p>As Blob Parameter Only (BPO) forks progressively increase throughput, the full-replication nature of today's EL blobpool will begin dominating bandwidth utilization, causing us to hit <a href="https://wg-eips.ritovision.com/7870/">EIP-7870</a> limits. Furthermore, this traffic will compete, and potentially starve, block and attestation propagation, risking instability and liveness issues. This behavior has already been observed in Fusaka devnets, where the average bandwidth consumption <em>of a full node</em> is dominated by the EL blobpool, since column propagation on the CL benefits from sampling.</p> <p><img src="https://wg-eips.ritovision.com/8070/./assets/bandwidth-breakdown-fusaka-devnets.png" alt="" /></p> <p><strong>Figure 1.</strong> <em>Breakdown of the average bandwidth consumption (download) of full nodes in Fusaka Devnet 5, for blob count target/max of 22/33 (left) and 48/72 (right). The average bandwidth consumption of the EL is ~4-5x that of the CL.</em></p> <p>While the average bandwidth consumption does not reflect that the load on the EL is spread out over time rather than concentrated in a small time window as it is in the CL, the gap between the EL and CL is quite large (~4-5x), and future upgrades will enable the CL to better spread out data propagation in the slot, leaving the EL blobpool as even more of a bottleneck.</p> <p>The sparse blobpool mechanism brings sampling to the EL as well, with an anticipated ~4x reduction in average bandwidth consumption for a given blobpool load. In doing so, it preserves the unstructured, stochastic nature of the current blobpool rather than introducing complex sharding architectures, prioritizing simplicity and resilience. Moreover, it preserves the CL's ability to satisfy its own sampling needs with the pre-propagated data in the EL blobpool (through the <code>getBlobs</code> Engine API). This is achieved by aligning the EL and CL sampling, in particular by having the EL fetch the cells corresponding to the CL custody set. This preserves a key feature of the blobpool, as it stretches the time window for blob data propagation, offloading this work from the critical path of block validation and leading to smoother and less bursty bandwidth utilization patterns over time.</p> <p>While the scalability gain may be more modest than with other solutions, we believe this design balances between simplicity, security, and scalability, in order to unlock the next tier of blob throughput without requiring user-facing changes, or deeper architectural redesigns.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="execution-clients-devp2p-changes">Execution clients :: devp2p changes</h3> <p>We introduce a new devp2p protocol version, <code>eth/71</code> extending the existing <code>eth/70</code> protocol (TODO: spec for eth/70 missing).</p> <p><strong>Modify <code>NewPooledTransactionHashes</code> (<code>0x08</code>) message.</strong> Add a new field <code>cell_mask</code> of type <code>B_16</code> (<code>uint128</code>). This field MUST be interpreted as a bitarray of length <code>CELLS_PER_EXT_BLOB</code>, carrying <code>1</code> in the indices of colums the announcer has available for <strong>all type 3 txs announced within the message</strong>. This field MUST be set to <code>nil</code> when no transactions of such type are announced. (TODO: this approach is not expressive enough if the node wants to offer randomly sampled columns, nor if it wants to announce transactions with full and partial availability in a single message).</p> <ul> <li>old schema (<code>eth/70</code>): <code>[types: B, [size_0: P, size_1: P, ...], [hash_0: B_32, hash_1: B_32, ...]]</code></li> <li>new schema (<code>eth/71</code>): <code>[types: B, [size_0: P, size_1: P, ...], [hash_0: B_32, hash_1: B_32, ...], cell_mask: B_16]</code></li> </ul> <p><strong>Modify <code>GetPooledTransactions</code> (<code>0x09</code>) / <code>PooledTransactions</code> (<code>0x10</code>) behaviour.</strong> Responses now elide blob payloads for type 3 transactions requested via this RPC. This is performed by setting an RLP <code>nil</code> literal in the list position corresponding to the transaction's blob data. Cell proofs and commitments are unaffected and continue to be sent.</p> <p><strong>New message type <code>GetCells</code> (<code>0x12</code>).</strong> Used to request cells for type 3 transactions. It specifies the transaction hashes being requested, along with a <code>cell_mask</code> specifying which cell indices are needed, with syntax identical as <code>cell_mask</code> in <code>NewPooledTransactionHashes</code>.</p> <ul> <li><code>eth/71</code>: <code>[[hash_0: B_32, hash_1: B_32, ...], cell_mask: B_16]</code></li> </ul> <p><strong>New message type <code>Cells</code> (<code>0x13</code>).</strong> Used to respond to a <code>GetCells</code> requests.</p> <ul> <li><code>eth/71</code>: <code>[[hash_0: B_32, hash_1: B_32, ...], cells: [[cell_0_0: B_2048, cell_0_1: B_2048, ...], [cell_1_0: B_2048, cell_1_1: B_2048, ...]], cell_mask: B_16]</code></li> </ul> <h3 id="execution-clients-blobpool-behavior">Execution clients :: Blobpool behavior</h3> <p><strong>New transaction hash.</strong> Upon receiving a <code>NewPooledTransactionHashes</code> announcement containing a previously unknown type 3 transaction hash, the node makes a probabilistic decision about fetching the blob payload: it decides to fetch the full blob payload with probability p = 0.15 (provider role), or simply sample otherwise (sampler role). This decision MAY be remembered for some period chosen by the implementer, in which case stateless heuristics are RECOMMENDED (e.g. calculating a hash by appending some time-bound value mixed in with stable transaction properties, and applying p to it).</p> <p><strong>Provider role.</strong> If the node is a provider, and the announcing peer signaled full availability, the node MUST request the signed transaction and full blob data from that peer via <code>GetPooledTransactions</code> and <code>GetCells</code> with an all-ones <code>cell_mask</code> bitmap. Upon successful retrieval and validation (as per <a href="https://wg-eips.ritovision.com/7594/">EIP-7594</a>), the node MUST in turn announce the transaction hash to its peers via <code>NewPooledTransactionHashes</code>, also with an all-ones <code>cell_mask</code>.</p> <p><strong>Sampler role.</strong> If the node is a sampler, the node MUST only request the transaction payload via <code>GetPooledTransactions</code>. It SHOULD await to observe at least 2 distinct provider announcements, and to successfully receive and validate the signed transaction, before acting further. It then MUST request custody-aligned cells from peers that announced overlapping availability, including providers. When fetching from a provider, the node MUST request <code>C_extra</code> random columns in addition to its custody set (see "Sampling noise" in Rationale). The node MUST request no more than <code>C_req</code> columns per request, at all times.</p> <p><strong>Ensuring fairness.</strong> Nodes MAY keep a record of the frequency of full payload fetches made by each peer, relative to their sampling requests. Nodes MAY elect to disconnect peers who exceed some locally-determined fairness heuristic. Such heuristics are not object of standardization.</p> <p><strong>Supernode behaviour.</strong> Supernodes (nodes intending to fetch every blob payload in full) MUST load balance requests across samplers and providers. Furthermore, supernodes SHOULD prioritize reconstructing blobs and proofs from 64 columns. Supernodes SHOULD maintain a larger peerset in order to satisfy their increased blob fetching needs without over-stressing a small set of neighbours and violating fairness.</p> <p><strong>Sampler eviction</strong> A sampler MAY drop a transaction if it has not observed sufficient network saturation (i.e., announcements from other peers for the same blob) within a defined period.</p> <p><strong>Continued sampling</strong> Tenured transactions MAY be subject to resampling in other to test for liveness and confirm confidence of continued network-wide availability.</p> <h3 id="execution-clients-local-block-builders">Execution clients :: Local block builders</h3> <blockquote> <p>TODO: config specification needed.</p> </blockquote> <p>Client implementations MUST provide configuration options for local block builders to specify a blob inclusion policy when proposing a block. Implementations SHOULD support at least these policies:</p> <ol> <li>Conservative: include only blob transactions for which all blob data is fully available locally (equivalent to today's behaviour).</li> <li>Optimistic: also include blob transactions that have been successfully sampled.</li> <li>Proactive: resample prior to blob proposal time in order to assess network-wide confidence of blobs potentially selected for inclusion. This requires an additional Engine API extension for the CL to notify the EL of upcoming proposer duty (TODO).</li> </ol> <h3 id="engine-api-extensions">Engine API extensions</h3> <blockquote> <p>TODO: This specification will be moved out to the Execution APIs repo and linked to from here.</p> </blockquote> <p><strong>Method <code>engine_blobCustodyUpdatedV1</code></strong></p> <p>Called by the Consensus layer client to inform the Execution layer of the indices of their current blob column custody set at startup, as well as subsequent changes during live operation.</p> <p>Request:</p> <ul> <li>method: <code>engine_blobCustodyUpdatedV1</code></li> <li>params: <ul> <li><code>indices_bitarray</code>: uint128, interpreted as a bitarray of length <code>CELLS_PER_EXT_BLOB</code> indicating which column indices form the custody set.</li> </ul> </li> <li>timeout: 150ms</li> </ul> <p>Response:</p> <ul> <li>result: no payload</li> <li>error: code and message set in case an error occurs during processing of the request.</li> </ul> <p>Specification:</p> <ol> <li>The Consensus client MUST call this method whenever its custody set changes. Additionally, it MUST call it on start, on restart, and when an Engine API interruption is detected.</li> <li>The Execution client MUST return an Ok response if the request is well-formed. All subsequent sampling requests MUST adopt the new custody set. Queued sampling requests MAY be patched to reflect the new custody set.</li> <li>For type 3 transactions pending in the blobpool: <ol> <li>If the custody set has expanded, the Execution client MUST issue new sampling requests for the delta. It SHOULD broadcast updated <code>NewPooledTransactionHashes</code> announcement with the new available set.</li> <li>If the custody set has contracted, the Execution client MAY prune dropped cells from local storage, but only AFTER it has broadcast an updated <code>NewPooledTransactionHashes</code> announcement with the reduced available set. This is to avoid peers from perceiving an availability fault if they happen to request those previously announced cells.</li> </ol> </li> <li>The Execution client MUST treat a request to update the custody set to the current value as a no-op operation returning an Ok.</li> </ol> <p><strong>Method <code>engine_getBlobsV4</code></strong></p> <p>Called by the Consensus layer client to retrieve blob cells from the Execution layer blobpool.</p> <p>Request:</p> <ul> <li>method: <code>engine_getBlobsV4</code></li> <li>params: <ul> <li><code>versioned_blob_hashes</code>: []bytes32, an array of blob versioned hashes.</li> <li><code>indices_bitarray</code>: uint128, a bitarray denoting the indices of the cells to retrieve.</li> </ul> </li> <li>timeout: 500ms</li> </ul> <p>Response:</p> <ul> <li>result: <code>[]BlobCellsAndProofsV1</code></li> <li>error: code and message set in case an error occurs during processing of the request.</li> </ul> <p><strong>Data structure <code>BlobCellsAndProofsV1</code></strong></p> <ul> <li><code>blob_cells</code>: a sequence of byte arrays <code>[]bytes</code> representing the partial matrix of the requested blobs, with <code>nil</code> entries for missing cells.</li> <li><code>proofs</code>: <code>Array of DATA</code> - Array of <code>KZGProof</code> as defined in <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>, 48 bytes each (<code>DATA</code>)</li> </ul> <h3 id="parameters">Parameters</h3> <ul> <li><strong>Fetching probability</strong>: p = 0.15</li> <li><strong>Mesh degree</strong>: D = 50 (default peerset size)</li> <li><strong>Sampling requirement</strong>: Minimum <code>SAMPLES_PER_SLOT = 8</code> columns per node as per PeerDAS specification</li> <li><strong>Reconstruction threshold</strong>: 64 cells required for Reed-Solomon decoding</li> <li><strong>Minimum providers to sample</strong>: minimum 2 providers should be observed before sampling</li> <li><strong>Extra random columns per request</strong>: <code>C_extra = 1</code></li> <li><strong>Maximum columns per request</strong>: <code>C_req = 8</code></li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="parameter-selection">Parameter selection</h3> <p>The choice of p = 0.15 balances bandwidth reduction with availability guarantees. Mathematical analysis for a mesh degree D = 50 shows:</p> <ul> <li><strong>Primary reliability</strong>: Probability of having at least 3 peers with complete blob payload is 98.6%</li> <li><strong>Secondary reliability</strong>: Via reconstruction from partial availability, recovery probability exceeds 80% when 6+ provider peers exist.</li> <li><strong>Total unavailability</strong>: Only 0.03% chance with these parameters.</li> </ul> <h3 id="reliability-framework">Reliability framework</h3> <p><strong>Primary reliability.</strong> Let $X$ be the number of direct peers with the full payload. With $X∼Binomial(D,p)$, the probability that at least $k$ honest peers hold the full blob payload for a type 3 tx is:</p> <p>$$ P(X \geq k) = 1 - \sum_{i=0}^{k-1} \binom{D}{i} p^i (1-p)^{D-i} $$</p> <p>Evaluating for sensible values of $p$ and $k$ yields, where $D=50$ (Geth's default mesh degree):</p> <table><thead><tr><th>$p$</th><th>$k = 6$</th><th>$k = 5$</th><th>$k = 4$</th><th>$k = 3$</th><th>$k = 2$</th><th>$k = 1$</th><th>$P(0)$</th></tr></thead><tbody> <tr><td>0.05</td><td>0.037776</td><td>0.103617</td><td>0.239592</td><td>0.459467</td><td>0.720568</td><td>0.923055</td><td>0.076945</td></tr> <tr><td>0.08</td><td>0.208126</td><td>0.371050</td><td>0.574704</td><td>0.774026</td><td>0.917288</td><td>0.984534</td><td>0.015466</td></tr> <tr><td>0.10</td><td>0.383877</td><td>0.568802</td><td>0.749706</td><td>0.888271</td><td>0.966214</td><td>0.994846</td><td>0.005154</td></tr> <tr><td>0.125</td><td>0.606513</td><td>0.765366</td><td>0.886232</td><td>0.958237</td><td>0.989739</td><td>0.998740</td><td>0.001260</td></tr> <tr><td><strong>0.15</strong></td><td><strong>0.780647</strong></td><td><strong>0.887895</strong></td><td><strong>0.953953</strong></td><td><strong>0.985811</strong></td><td><strong>0.997095</strong></td><td><strong>0.999704</strong></td><td><strong>0.000296</strong></td></tr> <tr><td>0.20</td><td>0.951973</td><td>0.981504</td><td>0.994344</td><td>0.998715</td><td>0.999807</td><td>0.999986</td><td>0.000014</td></tr> </tbody></table> <p><strong>Secondary reliability.</strong> Probability that a payload can be reconstructed from partial availability when primary reliability fails. Let $Y$ be the number of distinct columns available from sampler peers. Given $k$ provider peers that failed to serve the full payload, a node with $D - k$ sampler peers (each holding 8 random columns, assuming they're all minimal custody full nodes) can reconstruct with probability $P(Y \geq 64 \mid n = D - k)$. For the adversarial scenario where we attained $k = 3$, yet all failed to serve the blob data, with $D = 50$, secondary reliability exceeds 99.9% as samplers provide an expected 124 distinct columns from 47 peers.</p> <table><thead><tr><th>Providers ($k$)</th><th>Samplers ($n=D-k$)</th><th>$E[Distinct Columns]$</th><th>$P(Y ≥ 64)$</th></tr></thead><tbody> <tr><td>0</td><td>50</td><td>125.1</td><td>&gt;99.99%</td></tr> <tr><td>1</td><td>49</td><td>124.9</td><td>&gt;99.99%</td></tr> <tr><td>2</td><td>48</td><td>124.6</td><td>&gt;99.99%</td></tr> <tr><td>3</td><td>47</td><td>124.3</td><td>&gt;99.99%</td></tr> <tr><td>4</td><td>46</td><td>124.0</td><td>&gt;99.99%</td></tr> <tr><td>...</td><td>...</td><td>...</td><td>...</td></tr> <tr><td>~40</td><td>~10</td><td>~68</td><td>~80%</td></tr> </tbody></table> <p><strong>Minimum threshold</strong>: Approximately $n_{\min} \approx 10$ samplers needed for reasonable reconstruction probability (&gt;80%).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP changes the <code>eth</code> protocol and requires rolling out a new version, <code>eth/71</code>. Supporting multiple versions of a wire protocol is possible. Rolling out a new version does not break older clients immediately, since they can keep using protocol version <code>eth/70</code>.</p> <p>This EIP does not change consensus rules and does not strictly require a hard fork. We are assessing the gradual rollout possibilities. In the meantime, it is RECOMMENDED that this EIP be deployed within the context of a hard fork.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="attack-scenarios-and-threat-model">Attack scenarios and threat model</h3> <p><strong>DoS attacks.</strong> An important consideration in all mempool sharding mechanisms is the possibility of DoS attacks. This refers to the case where a malicious sender posts a transaction to the mempool disclosing only part of it, which makes the transaction impossible to be included in any future block, while still consuming mempool resources. In this system, such a sender can be detected by nodes that request the full payload of the transaction.</p> <p><strong>Selective withholding attacks.</strong> TODO</p> <p><strong>Eclipse attacks.</strong> TODO</p> <h3 id="peer-disconnection-policies">Peer disconnection policies</h3> <p>Nodes MAY keep a record of the frequency of full payload and column requests made by each peer. If a frequency exceeds some quota or the probabilistic expectation by some tolerance threshold, the node MAY decide to disconnect the offending peer alleging abuse as a reason. This prevents nodes from spending too much upload bandwidth on peers that fetch full payloads much more often that the expected p = 0.15.</p> <h3 id="the-need-for-sampling-noise">The need for sampling noise</h3> <p>Custody-aligned sampling generates in stable and predictable request patterns that attackers could game. For example, a malicious node may trick a victim by pretending to be a provider when in reality it only stores the few, predictable columns the victim is expected to sample. To defend against this, this EIP introduces the simple mechanism of "sampling noise."</p> <p>When a peer requests its custody columns from a provider, it must also request at least ONE randomly selected column. A failure to serve this extra column can be interpreted as a strong sign of misbehavior. The attacker could choose to timeout, but after a number of repetitions, the victim would likely disconnect anyway due to high failure rates.</p> <p>This simple mechanism reinforces key model assumptions (a provider is truly a provider) in exchange for negligible overhead per request (MAX_BLOBS_PER_TX x CELL_SIZE + proofs = ~12KiB).</p> <h3 id="no-normative-peer-scoring">No normative peer scoring</h3> <p>An earlier design considered a peer scoring system to grade peers by tracking their statistical ratio of requests to announcements (leechiness vs. helpfulness). After careful consideration, we deemed this approached brittle and dropped the feature. Our rationale was that such mechanism would strongly encode assumptions and confine the system to conform to some modellic behaviour, thus reducing flexibility and resilience in the face of environmental changes, shocks, or unexpected/improbable events (properties that are crucial in open and permissionless systems). Instead, we defer to implementations to define their own local heuristics for peer disconnection, if any.</p> <h3 id="devp2p-message-schema-choices">devp2p message schema choices</h3> <p>We note that <code>cell_mask</code> field in <code>NewPooledTransactionHashes</code> is not expressive enough to signal different local availability for type 3 txs announced within the same message. This limitation implies that (a) fully and partially available txs cannot be announced together, and (b) availability of randomly sampled columns cannot be signaled in practice (because indices vary per tx), only custody columns can be consistently announced (they're shared across all sampled transactions).</p> <p>Nevertheless, the sender can efficiently split and group announcements: fully-available txs can be bundled together, and partially-available txs can be announced in separate messages. Per-message dispatch overhead is minimal (one uint64 request_id and one uint8 message_type), and more expressive designs are likely to incur in higher overhead. Furthermore, from a protocol flow perspective, devp2p supports concurrent requests and unordered responses (via <code>request_id</code> correlation), so this approach is not affected by head-of-line blocking either (at least from a protocol perspective).</p> <p>We considered more expressive designs, ranging from simple arrays of <code>cell_mask</code>s (one per tx), to union types express full availability more compactly, to more complex schemes involving run-length encoding and compression. But we concluded that the added complexity was not justified at this time.</p> <h3 id="open-points">Open points</h3> <ul> <li>Further threat modelling and security hardening.</li> <li>RBF (replace-by-fee) impact.</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> 2025-10-29T00:00:00+00:00 2026-02-11T14:49:27+00:00 Mikhail Kalininhttps://github.com/mkalinin Francesco D'Amatohttps://github.com/fradamt https://wg-eips.ritovision.com/8071/

Cancels consolidation if the max effective balance of the target validator will be exceeded, preventing the withdrawal of the unused balance

<h2 id="abstract">Abstract</h2> <p>Cancels a consolidation request if the effective balance of the target validator would exceed the max effective balance after processing it, which would result in the excess balance being withdrawn. This is an unintended way to speed up withdrawals when the consolidation queue is faster than the exit queue.</p> <h2 id="motivation">Motivation</h2> <p>The existing design of consolidation mechanism leaves an opportunity to use consolidation queue for exits which becomes appealing to be abused when there is an imbalance between exit and consolidation queues favoring the latter.</p> <p>At the date of writing this EIP, the consolidation flaw is being heavily exploited. There are public write ups on how to speed up withdrawals by using this vulnerability.</p> <p>Even though this is a UX rather than security issue, consolidation queue was never meant to be used for withdrawals, which makes the fix introduced by this EIP an important modification.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <p>Starting from the beginning of the epoch when this EIP is activated, Consensus Layer client <strong>MUST</strong> use the modified <code>process_consolidation_request</code> function which code is outlined below.</p> <h3 id="new-get-pending-balance-to-consolidate">New <code>get_pending_balance_to_consolidate</code></h3> <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_pending_balance_to_consolidate</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"> target_index</span><span>:</span><span> ValidatorIndex</span><span>)</span><span> -&gt;</span><span> Gwei</span><span>:</span></span> <span class="giallo-l"><span> pending_balance_to_consolidate</span><span class="z-keyword"> =</span><span> Gwei</span><span>(</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> pending_consolidation</span><span class="z-keyword"> in</span><span> state</span><span>.</span><span>pending_consolidations</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> pending_consolidation</span><span>.</span><span>target_index</span><span class="z-keyword"> ==</span><span> target_index</span><span>:</span></span> <span class="giallo-l"><span> source_validator</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>validators</span><span>[</span><span>pending_consolidation</span><span>.</span><span>source_index</span><span>]</span></span> <span class="giallo-l"><span> pending_balance_to_consolidate</span><span class="z-keyword"> +=</span><span> source_validator</span><span>.</span><span>effective_balance</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> pending_balance_to_consolidate</span></span></code></pre><h3 id="modified-process-consolidation-request">Modified <code>process_consolidation_request</code></h3> <p><em>Note</em>: This function is extended with the check of the target's balance after consolidation and cancels consolidation request if the balance exceeds the max effective balance.</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_consolidation_request</span><span>(</span></span> <span class="giallo-l"><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"> consolidation_request</span><span>:</span><span> ConsolidationRequest</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-keyword"> if</span><span> is_valid_switch_to_compounding_request</span><span>(</span><span>state</span><span>,</span><span> consolidation_request</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> validator_pubkeys</span><span class="z-keyword"> =</span><span> [</span><span>v</span><span>.</span><span>pubkey</span><span class="z-keyword"> for</span><span> v</span><span class="z-keyword"> in</span><span> state</span><span>.</span><span>validators</span><span>]</span></span> <span class="giallo-l"><span> request_source_pubkey</span><span class="z-keyword"> =</span><span> consolidation_request</span><span>.</span><span>source_pubkey</span></span> <span class="giallo-l"><span> source_index</span><span class="z-keyword"> =</span><span> ValidatorIndex</span><span>(</span><span>validator_pubkeys</span><span>.</span><span>index</span><span>(</span><span>request_source_pubkey</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> switch_to_compounding_validator</span><span>(</span><span>state</span><span>,</span><span> source_index</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify that source != target, so a consolidation cannot be used as an exit</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> consolidation_request</span><span>.</span><span>source_pubkey</span><span class="z-keyword"> ==</span><span> consolidation_request</span><span>.</span><span>target_pubkey</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> If the pending consolidations queue is full, consolidation requests are ignored</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>state</span><span>.</span><span>pending_consolidations</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> PENDING_CONSOLIDATIONS_LIMIT</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> If there is too little available consolidation churn limit, consolidation requests are ignored</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> get_consolidation_churn_limit</span><span>(</span><span>state</span><span>)</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> MIN_ACTIVATION_BALANCE</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> validator_pubkeys</span><span class="z-keyword"> =</span><span> [</span><span>v</span><span>.</span><span>pubkey</span><span class="z-keyword"> for</span><span> v</span><span class="z-keyword"> in</span><span> state</span><span>.</span><span>validators</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify pubkeys exist</span></span> <span class="giallo-l"><span> request_source_pubkey</span><span class="z-keyword"> =</span><span> consolidation_request</span><span>.</span><span>source_pubkey</span></span> <span class="giallo-l"><span> request_target_pubkey</span><span class="z-keyword"> =</span><span> consolidation_request</span><span>.</span><span>target_pubkey</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> request_source_pubkey</span><span class="z-keyword"> not</span><span class="z-keyword"> in</span><span> validator_pubkeys</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> request_target_pubkey</span><span class="z-keyword"> not</span><span class="z-keyword"> in</span><span> validator_pubkeys</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span> source_index</span><span class="z-keyword"> =</span><span> ValidatorIndex</span><span>(</span><span>validator_pubkeys</span><span>.</span><span>index</span><span>(</span><span>request_source_pubkey</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> target_index</span><span class="z-keyword"> =</span><span> ValidatorIndex</span><span>(</span><span>validator_pubkeys</span><span>.</span><span>index</span><span>(</span><span>request_target_pubkey</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> source_validator</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>validators</span><span>[</span><span>source_index</span><span>]</span></span> <span class="giallo-l"><span> target_validator</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>validators</span><span>[</span><span>target_index</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"> Verify source withdrawal credentials</span></span> <span class="giallo-l"><span> has_correct_credential</span><span class="z-keyword"> =</span><span> has_execution_withdrawal_credential</span><span>(</span><span>source_validator</span><span>)</span></span> <span class="giallo-l"><span> is_correct_source_address</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> source_validator</span><span>.</span><span>withdrawal_credentials</span><span>[</span><span class="z-constant">12</span><span>:</span><span>]</span><span class="z-keyword"> ==</span><span> consolidation_request</span><span>.</span><span>source_address</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> (</span><span>has_correct_credential</span><span class="z-keyword"> and</span><span> is_correct_source_address</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify that target has compounding withdrawal credentials</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> has_compounding_withdrawal_credential</span><span>(</span><span>target_validator</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify the source and the target are active</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 class="z-keyword"> if</span><span class="z-keyword"> not</span><span> is_active_validator</span><span>(</span><span>source_validator</span><span>,</span><span> current_epoch</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> is_active_validator</span><span>(</span><span>target_validator</span><span>,</span><span> current_epoch</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify exits for source and target have not been initiated</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> source_validator</span><span>.</span><span>exit_epoch</span><span class="z-keyword"> !=</span><span class="z-constant"> FAR_FUTURE_EPOCH</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> target_validator</span><span>.</span><span>exit_epoch</span><span class="z-keyword"> !=</span><span class="z-constant"> FAR_FUTURE_EPOCH</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify the source has been active long enough</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> current_epoch</span><span class="z-keyword"> &lt;</span><span> source_validator</span><span>.</span><span>activation_epoch</span><span class="z-keyword"> +</span><span class="z-constant"> SHARD_COMMITTEE_PERIOD</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify the source has no pending withdrawals in the queue</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> get_pending_balance_to_withdraw</span><span>(</span><span>state</span><span>,</span><span> source_index</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> [New in EIPXXXX]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify that the consolidating balance will</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> end up as active balance, not as excess balance</span></span> <span class="giallo-l"><span> target_balance_after_consolidation</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> get_pending_balance_to_consolidate</span><span>(</span><span>state</span><span>,</span><span> target_index</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> source_validator</span><span>.</span><span>effective_balance</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> state</span><span>.</span><span>balances</span><span>[</span><span>target_index</span><span>]</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> target_balance_after_consolidation</span><span class="z-keyword"> &gt;</span><span> get_max_effective_balance</span><span>(</span><span>target_validator</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Initiate source validator exit and append pending consolidation</span></span> <span class="giallo-l"><span> source_validator</span><span>.</span><span>exit_epoch</span><span class="z-keyword"> =</span><span> compute_consolidation_epoch_and_update_churn</span><span>(</span></span> <span class="giallo-l"><span> state</span><span>,</span><span> source_validator</span><span>.</span><span>effective_balance</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> source_validator</span><span>.</span><span>withdrawable_epoch</span><span class="z-keyword"> =</span><span> Epoch</span><span>(</span></span> <span class="giallo-l"><span> source_validator</span><span>.</span><span>exit_epoch</span><span class="z-keyword"> +</span><span class="z-constant"> MIN_VALIDATOR_WITHDRAWABILITY_DELAY</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>pending_consolidations</span><span>.</span><span>append</span><span>(</span></span> <span class="giallo-l"><span> PendingConsolidation</span><span>(</span><span class="z-variable">source_index</span><span class="z-keyword">=</span><span>source_index</span><span>,</span><span class="z-variable"> target_index</span><span class="z-keyword">=</span><span>target_index</span><span>)</span></span> <span class="giallo-l"><span> )</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="iterating-over-pending-consolidations">Iterating over pending consolidations</h3> <p>The new design introduces an iteration over pending consolidations which increases complexity of consolidation processing.</p> <p>This is done to handle the case when there are multiple consolidations with the same target and each of them doesn't exceed the max effective balance while all of them together do.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces backwards-incompatible changes to the Consensus Layer and must be activated via scheduled network upgrade.</p> <h2 id="test-cases">Test Cases</h2> <ul> <li>test_single_consolidation_request_at_max_eb</li> <li>test_no_pending_consolidations_exceeding_max_eb</li> <li>test_single_pending_consolidation_exceeding_max_eb</li> <li>test_multiple_pending_consolidations_at_max_eb</li> <li>test_multiple_pending_consolidations_exceeding_max_eb</li> <li>test_exceeding_max_eb_with_the_target_balance_but_not_eb</li> <li>test_exceeding_max_eb_with_the_source_eb_but_not_the_balance</li> <li>test_multiple_pending_consolidations_exceeding_max_eb_with_the_source_eb_but_not_the_balance</li> </ul> <p>All of the above test cases are implemented <a href="https://wg-eips.ritovision.com/8071/./assets/test_process_consolidation_request.py">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>When consolidation request results in max effective balance exceeded, it is cancelled on the Consensus Layer, neither request fee nor transaction gas cost are refunded in this case.</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-10-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 Anders Elowssonhttps://github.com/anderselowsson Toni Wahrstätterhttps://github.com/nerolation Francesco D'Amatohttps://github.com/fradamt Ben Adamshttps://github.com/benaadams Maria Inês Silvahttps://github.com/misilva73 https://wg-eips.ritovision.com/8062/

Improve stake consolidation and fairness by imposing a "sweep" withdrawal fee for `0x01` validators set to 0.05% of the withdrawn amount.

<h2 id="abstract">Abstract</h2> <p>A fee is proposed on the partial "sweep" withdrawal of validators using <code>0x01</code> credentials, to improve stake consolidation and fairness. Ethereum's fast finality roadmap hinges on staking service providers migrating from <code>0x01</code> validators to <code>0x02</code> compounding validators. One roadblock is that <code>0x01</code> validators receive free-of-charge partial skimming withdrawals for balances exceeding 32 ETH, which consume protocol resources that are not accounted for. To address this, a 0.05% fee is imposed on the partial <code>0x01</code> sweep using a minimal modification to <code>process_withdrawals()</code>, applying the new constant <code>WITHDRAWAL_FEE_FRACTION = 2000</code>.</p> <h2 id="motivation">Motivation</h2> <p>The roadmap for fast finality hinges on stake consolidation, where staking service providers (SSPs) transition from running 32-ETH validators with <code>0x01</code> credentials to compounding validators with <code>0x02</code> credentials. A roadblock to this transition is that <code>0x01</code> validators have been designed with close-to-ideal capital efficiency and free-of-charge partial withdrawals for balances exceeding 32 ETH (the "sweep" function). When factoring in switching costs, the incentives do not favor stake consolidation. At the same time, sweep withdrawals take up resources on both the consensus layer (CL) and execution layer (EL) that are not paid for. It is unsuitable to give <code>0x01</code> validators an accounting advantage over <code>0x02</code> validators when Ethereum's roadmap hinges on stakers consolidating their stake in <code>0x02</code> validators.</p> <p>To improve consolidation while upholding fairness, this EIP accounts for the resource load of the <code>0x01</code> partial withdrawal sweep by imposing a small withdrawal fee for it. The proposed fee is 0.05% of the withdrawn amount, imposed via <code>WITHDRAWAL_FEE_FRACTION = 2000</code>. Since the average sweep withdrawal credits around 0.0235 ETH, the average expected fee per withdrawal is $0.0235;\mathrm{ETH} \times 0.0005 = 11,750;\mathrm{Gwei}$. The total expected fee over one year for a validator is 0.00048 ETH, corresponding to around $2 at the current ETH price. An SSP running 50,000 <code>0x01</code> validators (slightly below 5% of the stake) would thus need to pay around $100,000 per year in withdrawal fees.</p> <p>The fee approximates the EL workload imposed by the sweep, calibrated against the average base fee over the last year (4.53 gwei). The withdrawal incurs equivalent to around 2204 gas (not accounting for CL work), implying a fee of $2204 \times 4.53 = 9,984;\mathrm{Gwei}$ (albeit, the base fee has been lower in recent months).</p> <p>The fee is taken out on the CL as a percentage, since a fixed fee could produce extreme outcomes if the number of <code>0x01</code> validators were to be drastically reduced due to consolidation. In such a scenario, the sweep will hit validators more frequently, and the fee will thus be taken out more frequently. Since validators then would also withdraw a lower balance each time, a percentage fee on the withdrawal keeps the burden on stakers fixed. The existing logic is kept intact to minimize complexity. As a result, a validator's balance will dip just below 32 ETH after skimming (as also happens when receiving a penalty just after skimming).</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>WITHDRAWAL_FEE_FRACTION</code></td><td><code>2000</code></td></tr> </tbody></table> <h3 id="functions">Functions</h3> <p>In <code>process_withdrawals()</code>, take out a fee for skimmed <code>0x01</code> validators that did not perform a full exit, burning it on the CL:</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_withdrawals</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"> payload</span><span>:</span><span> ExecutionPayload</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> In this existing for-loop, calculate a fee before decreasing the balance</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> w</span><span class="z-keyword"> in</span><span> expected_withdrawals</span><span>:</span></span> <span class="giallo-l"><span> vi</span><span class="z-keyword"> =</span><span> w</span><span>.</span><span>validator_index</span></span> <span class="giallo-l"><span> fee</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> has_compounding_withdrawal_credential</span><span>(</span><span>state</span><span>.</span><span>validators</span><span>[</span><span>vi</span><span>]</span><span>)</span><span class="z-keyword"> and</span><span> w</span><span>.</span><span>amount</span><span class="z-keyword"> !=</span><span> state</span><span>.</span><span>balances</span><span>[</span><span>vi</span><span>]</span><span>:</span></span> <span class="giallo-l"><span> fee</span><span class="z-keyword"> =</span><span> w</span><span>.</span><span>amount</span><span class="z-keyword"> //</span><span class="z-constant"> WITHDRAWAL_FEE_FRACTION</span></span> <span class="giallo-l"><span> decrease_balance</span><span>(</span><span>state</span><span>,</span><span> vi</span><span>,</span><span> w</span><span>.</span><span>amount</span><span class="z-keyword"> +</span><span> fee</span><span>)</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="fast-finality">Fast finality</h3> <p>Fast finality is best realized through a reduction to the active validator set voting each round. Two paths have been envisioned. In one path referred to as Orbit SSF, the active set rotates in a weighted fashion, such that large consolidated validators always are active, and smaller validators are active less frequently. In another path, there is a fixed number of validator seats, with only the largest validators (e.g., the top 8,192) granted a seat. Both paths require consolidation to achieve a desirable stake weight and optimal performance.</p> <h3 id="level-of-the-proposed-fee">Level of the proposed fee</h3> <p>The cost per validator per year under 3% CL yield becomes $32 \times 0.03 / 2000 = 0.00048$ ETH, corresponding to around $2 at a price of $4,167 per ETH. Table 1 summarizes outcomes under different numbers of validators. A solo staker running one <code>0x01</code> is unlikely to consider the $2 fee enough to tip the scale either way. A staking service provider (SSP) running 50,000 <code>0x01</code> validators (slightly below 5% of the stake) has at least a moderate incentive since the cost then is $100,000. Under perfect competition, the SSP will not be able to pass on this cost to their customers. The outcome under a higher fee is outlined in the Alternative specifications section.</p> <table><thead><tr><th>Validators (stake %)</th><th style="text-align: right">Cost (ETH/year)</th><th style="text-align: right">Cost (USD/year)</th></tr></thead><tbody> <tr><td>1 (~0.0001%)</td><td style="text-align: right">0.00048</td><td style="text-align: right">$2</td></tr> <tr><td>100 (~0.01%)</td><td style="text-align: right">0.048</td><td style="text-align: right">$200</td></tr> <tr><td>10,000 (~1%)</td><td style="text-align: right">4.8</td><td style="text-align: right">$20,000</td></tr> <tr><td>50,000 (~5%)</td><td style="text-align: right">24</td><td style="text-align: right">$100,000</td></tr> <tr><td>100,000 (~10%)</td><td style="text-align: right">48</td><td style="text-align: right">$200,000</td></tr> </tbody></table> <p><strong>Table 1.</strong> Cost to stakers under the proposed withdrawal fee.</p> <p>The switching cost may still be greater than the yearly fee for an SSP. Some smart contracts requiring <code>0x01</code> credentials may be frozen and others may require a full exit and entry, with associated opportunity costs. However, once the recurring fee is in place and there is a commitment from the protocol to phase out <code>0x01</code> validators for SSPs—potentially even raising the fee until such an outcome has been realized—then the switch will have to be done <em>eventually</em>. Ignoring other potential benefits of <code>0x01</code> validators, a more accurate comparison is thus between the recurring fee and the capital cost for financing the switch, which of course is lower.</p> <h3 id="gas-accounting">Gas accounting</h3> <p>The gas cost accounting is as follows:</p> <ul> <li>500 gas – cold touch of an account known to have no code (as specified in <a href="https://wg-eips.ritovision.com/2780/">EIP-2780</a>),</li> <li>1000 gas – one account-leaf write in the account trie (as specified in <a href="https://wg-eips.ritovision.com/2780/">EIP-2780</a>),</li> <li>704 gas – an <a href="https://wg-eips.ritovision.com/4895/">EIP-4895</a> withdrawal {index: uint64, validator_index: uint64, address: bytes20, amount: uint64}, consisting of $8 + 8 + 20 + 8 = 44$ bytes, priced analogously to calldata at 16 gas/byte.</li> </ul> <p>It can be noted that we are not with this accounting charging for the CL work that <code>0x01</code> validators impose due to the sweep. We are neither charging <code>0x02</code> validators for the CL work of EL-triggered partial withdrawals via <a href="https://wg-eips.ritovision.com/7002/">EIP-7002</a>, but they are charged more extensively on the EL for triggering the withdrawal. Further note that <code>2048</code>-ETH validators are exempted in the specification from the sweep withdrawal fee, to avoid harming consolidation, and as an acknowledgement that <code>2048</code> ETH is the maximum stake that the protocol currently is designed to handle.</p> <h3 id="capital-efficiency-and-opportunity-cost">Capital efficiency and opportunity cost</h3> <p>Besides free withdrawals, another benefit of <code>0x01</code> validators is the capital efficiency. A compounding <code>0x02</code> validator will on average have 0.75 ETH sitting idle, not counting toward the effective balance (EB). This is due to the current hysteresis design, where a validator that gradually increases its balance will hold between 0.25 to 1.25 more ETH than their EB. A <code>0x01</code> validator will on average have just $0.0235/2 = 0.01175$ ETH idle, and are thus much more capital-efficient, particularly when the compounding <code>0x02</code> validator holds a moderate balance overall.</p> <p>Figure 1 illustrates the change in yield relative to a baseline with a neutral EB design, where, as the balance compounds, it is on average equal to the EB. The blue line is the yield of compounding <code>0x02</code> validators, which receive a lower yield due to the on average 0.75 ETH lower EB than the balance. The green circles are the yield that skimming 32-ETH and 2048-ETH validators receive. The orange line is the fee imposed on <code>0x01</code> validators proposed in the main specification. As evident, this fee does not fully offset the loss due to yield drag for <code>0x02</code> validators at validator balances below around 1,000 ETH.</p> <p><img src="https://wg-eips.ritovision.com/8062/./assets/1.png" alt="Figure 1" /></p> <p><strong>Figure 1.</strong> Relative change in staking yield due to differences in capital efficiency of different validator configurations. The proposed fee is shown in orange.</p> <p><a href="https://wg-eips.ritovision.com/8068/">EIP-8068</a> addresses differences in capital efficiency between <code>0x01</code> and <code>0x02</code> validators with a neutral EB design, where the hysteresis threshold raises the EB at +0.5. This effectively shifts the blue line, positioning all compounding validators at the black line.</p> <p>If EIP-8068 is not included in the same hardfork as this EIP, we could instead raise the withdrawal fee to compensate. The alternative specification below therefore outlines a higher fee. This will however not address the other concern addressed by EIP-8068: a <code>0x02</code> validator can leverage the hysteresis and make a partial withdrawal once having reached 33 ETH EB, such that they only need to hold 32.75 ETH while keeping 33 ETH EB. This concern can, on the other hand, also be addressed on its own for minimal complexity, as outlined in the alternative specification of EIP-8068.</p> <h3 id="alternative-specification">Alternative specification</h3> <p>If EIP-8068 is not included in the same hardfork as this EIP, it is reasonable to compensate for the lower capital efficiency of <code>0x02</code> validators by setting a higher withdrawal fee. This way, stakers will be less likely to remain on their <code>0x01</code> validators just for the better capital efficiency. Figure 2 shows three different alternative fees with red lines. The white squares illustrate equal capital efficiency between a <code>0x01</code> validator under the proposed fee and a <code>0x02</code> validator at some specific validator balance.</p> <p><img src="https://wg-eips.ritovision.com/8062/./assets/2.png" alt="Figure 2" /></p> <p><strong>Figure 2.</strong> Relative change in staking yield due to differences in capital efficiency of different validator configurations. The main proposed fee is shown in orange, and alternative fees are shown in red.</p> <p>The main option shown by the full red line is to raise the fee from 0.05% to 0.5%, setting <code>WITHDRAWAL_FEE_FRACTION = 200</code>. This means that a 32-ETH <code>0x01</code> validator will have approximately the same capital efficiency as a 128-ETH <code>0x02</code> validator. A stronger option is to impose a 1% fee as shown by the dashed red line, setting <code>WITHDRAWAL_FEE_FRACTION = 100</code>. Under this option, consolidating to a <code>0x02</code> validator will always at least be neutral, if the staker runs more than one <code>0x01</code> validator. A less forceful option is shown by the red dotted line, instead setting <code>WITHDRAWAL_FEE_FRACTION = 400</code>.</p> <p>Table 2 outlines the cost to stakers under the primary alternative specification with <code>WITHDRAWAL_FEE_FRACTION = 200</code>. Stakers then pay an additional $20 per validator. That means that an SSP running 5% of the stake would take a loss of around one million dollars per year, representing a much stronger incentive to consolidate.</p> <table><thead><tr><th>Validators (stake %)</th><th style="text-align: right">Cost (ETH/year)</th><th style="text-align: right">Cost (USD/year)</th></tr></thead><tbody> <tr><td>1 (~0.0001%)</td><td style="text-align: right">0.0048</td><td style="text-align: right">$20</td></tr> <tr><td>100 (~0.01%)</td><td style="text-align: right">0.48</td><td style="text-align: right">$2k</td></tr> <tr><td>10k (~1%)</td><td style="text-align: right">48</td><td style="text-align: right">$200k</td></tr> <tr><td>50k (~5%)</td><td style="text-align: right">240</td><td style="text-align: right">$1M</td></tr> <tr><td>100k (~10%)</td><td style="text-align: right">480</td><td style="text-align: right">$2M</td></tr> </tbody></table> <p><strong>Table 2.</strong> Cost to stakers under the alternative higher withdrawal fee of 0.5% (<code>WITHDRAWAL_FEE_FRACTION = 200</code>).</p> <h2 id="security-considerations">Security Considerations</h2> <p>To the best of the authors' knowledge, there are no security risks associated with the proposed fee.</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-10-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Cheng Qianhttps://github.com/jamesavechivessupport@deakee.com https://wg-eips.ritovision.com/8063/

ERC-20 tokens representing group membership with threshold-based access control.

<h2 id="abstract">Abstract</h2> <p>This proposal defines a "Group" as an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token where token balance represents membership level. Groups are standard ERC-20 tokens with the semantic interpretation that holding tokens means membership in the group. Unlike binary membership, this supports threshold-based membership: holding more tokens grants higher membership tiers or privileges. By being pure ERC-20, Groups inherit full compatibility with existing wallets, explorers, and tooling with no additional implementation burden.</p> <h2 id="motivation">Motivation</h2> <p>Many applications need addressable groups of accounts with controlled membership and tiered access:</p> <ul> <li><strong>DAOs</strong>: Voting power proportional to token holdings</li> <li><strong>Loyalty programs</strong>: Bronze/Silver/Gold tiers based on token balance</li> <li><strong>Access control</strong>: Different features unlocked at different balance thresholds</li> <li><strong>Partner networks</strong>: Minimum token requirements for partnership benefits</li> </ul> <p>The key insight is that <strong>any ERC-20 token can represent group membership</strong>:</p> <ul> <li><code>balanceOf(account) == 0</code> → Not a member</li> <li><code>balanceOf(account) &gt;= threshold</code> → Member at that tier</li> </ul> <p>This approach provides:</p> <ul> <li><strong>Zero implementation overhead</strong>: Any ERC-20 token can be a Group</li> <li><strong>Instant tooling compatibility</strong>: Wallets, explorers, DEXs work out of the box</li> <li><strong>Tiered membership</strong>: Different balance thresholds unlock different privileges</li> <li><strong>Transferable membership</strong>: Standard ERC-20 transfers allow membership trading/delegation</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> <h3 id="requirements">Requirements</h3> <p>A compliant Group contract:</p> <ol> <li><strong>MUST</strong> implement <a href="https://wg-eips.ritovision.com/20/">ERC-20</a></li> <li><strong>MUST</strong> implement <a href="https://wg-eips.ritovision.com/165/">ERC-165</a></li> <li><strong>SHOULD</strong> implement the optional interface defined below for membership introspection</li> </ol> <h3 id="membership-semantics">Membership Semantics</h3> <p>Token balance represents membership level:</p> <ul> <li><code>balanceOf(account) == 0</code> → Account is <strong>not</strong> a member</li> <li><code>balanceOf(account) &gt; 0</code> → Account <strong>is</strong> a member</li> <li><code>balanceOf(account) &gt;= threshold</code> → Account qualifies for that membership tier</li> </ul> <p>Applications define their own thresholds. For example:</p> <ul> <li>Basic membership: <code>balanceOf(account) &gt;= 1</code></li> <li>Silver tier: <code>balanceOf(account) &gt;= 100 * 10**decimals</code></li> <li>Gold tier: <code>balanceOf(account) &gt;= 500 * 10**decimals</code></li> <li>Platinum tier: <code>balanceOf(account) &gt;= 1000 * 10**decimals</code></li> </ul> <h3 id="interface-optional">Interface (Optional)</h3> <p>Implementations MAY expose a convenience interface for membership checks:</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.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"> @title</span><span class="z-comment"> IERC8063 — Optional membership introspection for ERC-20 tokens</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC8063</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 true if `account` holds at least `threshold` 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"> account</span><span class="z-comment"> The address to check</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> threshold</span><span class="z-comment"> Minimum balance required for membership at this tier</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isMember</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"> threshold</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>If implemented:</p> <ul> <li><code>isMember(account, threshold)</code> MUST return <code>true</code> if and only if <code>balanceOf(account) &gt;= threshold</code>.</li> <li><code>isMember(account, 0)</code> MUST return <code>true</code> for any account.</li> </ul> <h3 id="erc-165-introspection">ERC-165 Introspection</h3> <ul> <li><code>supportsInterface(0x36372b07)</code> (ERC-20) SHOULD return <code>true</code></li> <li>If the optional interface is implemented, <code>supportsInterface</code> for it SHOULD return <code>true</code></li> </ul> <h3 id="deployment-model">Deployment Model</h3> <p>Following the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> pattern, each group is its own contract deployment:</p> <ul> <li><strong>Group identity</strong>: A group is uniquely identified by its contract address.</li> <li><strong>Deployment</strong>: Deploy any ERC-20 token. The token IS the group.</li> <li><strong>Discovery</strong>: Applications can discover groups through Transfer events, registries, or direct address references.</li> <li><strong>Naming</strong>: <code>name()</code> and <code>symbol()</code> follow standard ERC-20 conventions.</li> </ul> <h3 id="minting-and-burning">Minting and Burning</h3> <p>Minting and burning are <strong>implementation-defined</strong>. Groups MAY implement minting/burning using any approach:</p> <ul> <li>Standard <code>mint(address, uint256)</code> function</li> <li><a href="https://wg-eips.ritovision.com/5679/">ERC-5679</a> compliant <code>mint(address, uint256, bytes)</code></li> <li>No minting after initial supply (fixed membership)</li> <li>Governance-controlled minting</li> <li>Open minting (anyone can join by minting)</li> </ul> <p>The standard does not mandate any specific minting/burning interface.</p> <h3 id="tiered-benefits-example">Tiered Benefits Example</h3> <p>Applications define membership tiers externally:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Example: Partner contract checking membership tiers</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> PartnerBenefits</span><span> {</span></span> <span class="giallo-l"><span> IERC20 </span><span class="z-storage z-type">public</span><span> membershipToken</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> BRONZE </span><span class="z-keyword">=</span><span class="z-constant"> 100</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 class="z-support"> uint256</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> SILVER </span><span class="z-keyword">=</span><span class="z-constant"> 500</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 class="z-support"> uint256</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> GOLD </span><span class="z-keyword">=</span><span class="z-constant"> 1000</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 class="z-storage z-type"> function</span><span class="z-entity z-name"> getDiscount</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 class="z-support"> uint256</span><span> balance </span><span class="z-keyword">=</span><span> membershipToken</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>(</span><span>user</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>balance </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> GOLD</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> 30</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 30% off</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>balance </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> SILVER</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> 20</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 20% off</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>balance </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> BRONZE</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> 10</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 10% off</span></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> <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"> isMember</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">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> membershipToken</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>(</span><span>user</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><h3 id="optional-extensions">Optional Extensions</h3> <h4 id="ownership-via-erc-173">Ownership (via <a href="https://wg-eips.ritovision.com/173/">ERC-173</a>)</h4> <p>Implementations that want a single-owner governance model MAY use <a href="https://wg-eips.ritovision.com/173/">ERC-173</a> or <a href="https://wg-eips.ritovision.com/8023/">ERC-8023</a> for standardized ownership.</p> <h4 id="capped-membership-balance-1">Capped Membership (Balance ≤ 1)</h4> <p>For use cases requiring binary membership (member/non-member with no tiers), implementations MAY enforce <code>balanceOf(account) &lt;= 1</code> for all accounts.</p> <h2 id="rationale">Rationale</h2> <ul> <li><strong>Pure ERC-20</strong>: A Group is simply an ERC-20 token with membership semantics. No new token standard needed.</li> <li><strong>No minting/burning mandate</strong>: Different use cases need different minting policies. The standard doesn't prescribe one.</li> <li><strong>Threshold-based membership</strong>: More flexible than binary membership; supports tiered access, loyalty programs, and proportional voting naturally.</li> <li><strong>Optional interface</strong>: The <code>isMember</code> function is a convenience; applications can directly call <code>balanceOf</code> if preferred.</li> <li><strong>Maximum compatibility</strong>: Any existing ERC-20 token can be interpreted as a Group by applications.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is fully backwards compatible with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. In fact, <strong>any existing ERC-20 token can be used as a Group</strong> — the standard simply defines how to interpret token balance as membership.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Reference contracts are provided in the <code>assets/</code> directory:</p> <ul> <li><a href="https://wg-eips.ritovision.com/8063/./assets/IERC8063.sol"><code>IERC8063.sol</code></a> — Interface definition</li> <li><a href="https://wg-eips.ritovision.com/8063/./assets/ERC8063.sol"><code>ERC8063.sol</code></a> — Reference implementation with membership helpers</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <ul> <li><strong>Token economics</strong>: Membership is tied to token balance. Consider the implications of token transfers, trading, and price volatility on membership.</li> <li><strong>Threshold manipulation</strong>: If thresholds are stored onchain, ensure they cannot be manipulated by unauthorized parties.</li> <li><strong>Transfer implications</strong>: Token transfers change membership. Consider whether this is desirable for your use case.</li> <li><strong>Approval risks</strong>: Standard ERC-20 approval risks apply. Approving another address grants them ability to transfer your membership tokens.</li> <li><strong>Decimal handling</strong>: Ensure thresholds account for the token's decimals.</li> <li><strong>Minting security</strong>: If minting is permitted, carefully control who can mint to prevent unauthorized membership grants.</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> 2025-10-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 Anders Elowssonhttps://github.com/anderselowsson https://wg-eips.ritovision.com/8068/

Make the effective balance calculation neutral so that 0x01 and 0x02 validators receive the same yield, thus facilitating consolidation.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a neutral effective balance (EB) design to ensure <code>0x01</code> (skimming) and <code>0x02</code> (compounding) validators receive equal yields. Currently, validators that compound their balance have poor capital efficiency and lower yields as their idle balance (not contributing to EB) is 0.75 ETH, significantly higher than that of skimming validators at near-zero. This disincentivizes stake consolidation critical to Ethereum's fast finality roadmap. Additionally, the current hysteresis rules allow <code>0x02</code> validators to game the hysteresis by keeping their balance below the EB. The increased profitability at lower balances could further harm consolidation. This proposal sets the EB hysteresis upward threshold to the neutral +0.5 and the downward threshold to +0.25. To prevent gaming after operations like partial withdrawals, the EB is reset to the floor of the balance, and a one-time <code>temporary_upward_threshold</code> set. This threshold is derived from an integral equation that ensures the average idle balance is zero as the validator's balance compounds up to the next integer.</p> <h2 id="motivation">Motivation</h2> <p>The roadmap for fast finality hinges on stake consolidation, where staking service providers (SSPs) transition from running 32-ETH validators with <code>0x01</code> credentials to compounding validators with <code>0x02</code> credentials. A roadblock to this transition is that <code>0x01</code> validators have close-to-ideal capital efficiency, whereas <code>0x02</code> validators have poor capital efficiency during compounding. Furthermore, the optimal configuration for a <code>0x02</code> validator is to reduce its balance to 32.75 ETH and prevent it from compounding further. These incentives may lead Ethereum's fast-finality roadmap to be delayed. To prevent this, a neutral effective balance calculation is proposed, that sees all validator configurations earn the same CL yield.</p> <p>A <code>0x02</code> validator that compounds its balance $b$ as intended will on average have 0.75 ETH of its balance not counting toward its effective balance (EB, or $E$ in equations). Specifically, with the current EB step bands, the idle remainder $r=b-E \in[0.25, 1.25)$ and $\bar{r}=(0.25+1.25)/2=0.75$. A <code>0x01</code> validator operating at 32 ETH has a much lower idle remainder, on average half the withdrawal sweep of $0.0235/2 = 0.01175$ ETH. A 32-ETH <code>0x01</code> validator will therefore earn around 2.3% more CL yield than a compounding <code>0x02</code> validator that grows from 32.25 ETH to 34.25 ETH over around two years.</p> <p>A separate issue is that <code>0x02</code> validators can make a partial withdrawal down to 32.75 ETH when having any EB &gt;33 ETH, leveraging the hysteresis to retain a 33 ETH EB. The surplus capital can then be deployed to increase the staking yield, running multiple 32.75-ETH validators. Assuming a 3% CL yield, recurring partial withdrawals deployed at 33 ETH to bring down the balance to 32.75 ETH, and ignoring the exit queue capital drag, the approach is more profitable than running skimming 2048-ETH validators under current base fees.</p> <p>To uphold fairness while not disrupting the current operation of <code>0x01</code> validators, the following changes are made:</p> <ul> <li>The upward EB step from $E$ to $E+1$ is imposed at $E + 0.5$. During regular upward compounding, the EB is thus set as the balance rounded to the nearest integer. This leads a compounding <code>0x02</code> validator to on average have a $E=b$, just like a 32-ETH <code>0x01</code> validator.</li> <li>The downward step to $E$ is imposed at $E+0.25$ ($E_{+1}-0.75$).</li> <li>Partial withdrawals are prevented from gaming the protocol. The EB calculation is designed such that each partial withdrawal is treated neutrally: $E=b$. To achieve this, the following takes place after every partial withdrawal at epoch boundaries: <ul> <li>The EB is initiated to the integer floor of the balance: $E = \text{EB}(b_0) = \lfloor b_0 \rfloor$.</li> <li>A new field <code>temporary_upward_threshold</code> ($t$) is stored in the beacon state.</li> <li>This threshold is computed as $t = E + \frac{1+(b_0-E)^2}{2}$, derived from the integral equation that stipulates that the validator will on average have $E=b$ when it smoothly grows its balance up until the next integer (see the Rationale).</li> <li>To increase the EB, the balance must satisfy both the regular upward threshold <em>and</em> the <code>temporary_upward_threshold</code>, after which <code>temporary_upward_threshold</code> is reset to <code>0</code>.</li> </ul> </li> </ul> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <p>Change two existing constants:</p> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>HYSTERESIS_DOWNWARD_MULTIPLIER</code></td><td><code>3</code></td></tr> <tr><td><code>HYSTERESIS_UPWARD_MULTIPLIER</code></td><td><code>2</code></td></tr> </tbody></table> <h3 id="containers">Containers</h3> <p>Two new fields are added to the state:</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> temporary_upward_threshold</span><span>:</span><span> List</span><span>[</span><span>Gwei</span><span>,</span><span class="z-constant"> VALIDATOR_REGISTRY_LIMIT</span><span>]</span></span> <span class="giallo-l"><span> reset_eb_flags</span><span>:</span><span> List</span><span>[</span><span>boolean</span><span>,</span><span class="z-constant"> VALIDATOR_REGISTRY_LIMIT</span><span>]</span></span></code></pre> <p>On upgrade, both lists are initialized to length <code>len(state.validators)</code> with <code>0</code> and <code>False</code> respectively.</p> <h3 id="functions">Functions</h3> <p>A new helper is added for re-initializing EB and the <code>temporary_upward_threshold</code> for validators that have been marked for EB reset; this helper is invoked during epoch processing.</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"> initiate_effective_balance_and_threshold</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"> index</span><span>:</span><span> ValidatorIndex</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> v</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>validators</span><span>[</span><span>index</span><span>]</span></span> <span class="giallo-l"><span> balance</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>balances</span><span>[</span><span>index</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> v</span><span>.</span><span>effective_balance</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span>balance</span><span class="z-keyword"> -</span><span> balance</span><span class="z-keyword"> %</span><span class="z-constant"> EFFECTIVE_BALANCE_INCREMENT</span><span>,</span><span> get_max_effective_balance</span><span>(</span><span>v</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> offset</span><span class="z-keyword"> =</span><span> (</span><span class="z-constant">EFFECTIVE_BALANCE_INCREMENT</span><span class="z-keyword"> +</span><span> (</span><span>balance</span><span class="z-keyword"> -</span><span> v</span><span>.</span><span>effective_balance</span><span>)</span><span class="z-keyword">**</span><span class="z-constant">2</span><span class="z-keyword"> //</span><span class="z-constant"> EFFECTIVE_BALANCE_INCREMENT</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> 2</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>temporary_upward_threshold</span><span>[</span><span>index</span><span>]</span><span class="z-keyword"> =</span><span> v</span><span>.</span><span>effective_balance</span><span class="z-keyword"> +</span><span> offset</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>reset_eb_flags</span><span>[</span><span>index</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> False</span></span></code></pre> <p>The existing <code>process_effective_balance_updates()</code> is modified to call the new helper before updating the EB, and so that the EB update accounts for the <code>temporary_upward_threshold</code>. We show here the whole function for completeness:</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_effective_balance_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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Update effective balances with hysteresis</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> index</span><span>,</span><span> validator</span><span class="z-keyword"> in</span><span class="z-support"> enumerate</span><span>(</span><span>state</span><span>.</span><span>validators</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> balance</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>balances</span><span>[</span><span>index</span><span>]</span></span> <span class="giallo-l"><span class="z-constant"> HYSTERESIS_INCREMENT</span><span class="z-keyword"> =</span><span> uint64</span><span>(</span><span class="z-constant">EFFECTIVE_BALANCE_INCREMENT</span><span class="z-keyword"> //</span><span class="z-constant"> HYSTERESIS_QUOTIENT</span><span>)</span></span> <span class="giallo-l"><span class="z-constant"> DOWNWARD_THRESHOLD</span><span class="z-keyword"> =</span><span class="z-constant"> HYSTERESIS_INCREMENT</span><span class="z-keyword"> *</span><span class="z-constant"> HYSTERESIS_DOWNWARD_MULTIPLIER</span></span> <span class="giallo-l"><span class="z-constant"> UPWARD_THRESHOLD</span><span class="z-keyword"> =</span><span class="z-constant"> HYSTERESIS_INCREMENT</span><span class="z-keyword"> *</span><span class="z-constant"> HYSTERESIS_UPWARD_MULTIPLIER</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> New</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> state</span><span>.</span><span>reset_eb_flags</span><span>[</span><span>index</span><span>]</span><span>:</span></span> <span class="giallo-l"><span> initiate_effective_balance_and_threshold</span><span>(</span><span>state</span><span>,</span><span> ValidatorIndex</span><span>(</span><span>index</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> continue</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Then, adjust the existing if-clause to account for the temporary_upward_threshold</span></span> <span class="giallo-l"><span> max_effective_balance</span><span class="z-keyword"> =</span><span> get_max_effective_balance</span><span>(</span><span>validator</span><span>)</span><span> </span></span> <span class="giallo-l"><span> balance_floor</span><span class="z-keyword"> =</span><span> balance</span><span class="z-keyword"> -</span><span> balance</span><span class="z-keyword"> %</span><span class="z-constant"> EFFECTIVE_BALANCE_INCREMENT</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> balance</span><span class="z-keyword"> +</span><span class="z-constant"> DOWNWARD_THRESHOLD</span><span class="z-keyword"> &lt;</span><span> validator</span><span>.</span><span>effective_balance</span><span>:</span></span> <span class="giallo-l"><span> validator</span><span>.</span><span>effective_balance</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span>balance_floor</span><span>,</span><span> max_effective_balance</span><span>)</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>temporary_upward_threshold</span><span>[</span><span>index</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> (</span><span>validator</span><span>.</span><span>effective_balance</span><span class="z-keyword"> +</span><span class="z-constant"> UPWARD_THRESHOLD</span><span class="z-keyword"> &lt;</span><span> balance</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> balance</span><span class="z-keyword"> &gt;=</span><span> state</span><span>.</span><span>temporary_upward_threshold</span><span>[</span><span>index</span><span>]</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> new_eb</span><span class="z-keyword"> =</span><span> balance_floor</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> balance</span><span class="z-keyword"> -</span><span> balance_floor</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> EFFECTIVE_BALANCE_INCREMENT</span><span class="z-keyword"> //</span><span class="z-constant"> 2</span><span>:</span></span> <span class="giallo-l"><span> new_eb</span><span class="z-keyword"> =</span><span> balance_floor</span><span class="z-keyword"> +</span><span class="z-constant"> EFFECTIVE_BALANCE_INCREMENT</span></span> <span class="giallo-l"><span> validator</span><span>.</span><span>effective_balance</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span>new_eb</span><span>,</span><span> max_effective_balance</span><span>)</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>temporary_upward_threshold</span><span>[</span><span>index</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span></code></pre> <p>When processing partial withdrawal, the flag for reseting the EB is set.</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_withdrawals</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"> payload</span><span>:</span><span> ExecutionPayload</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 class="z-keyword"> for</span><span> withdrawal</span><span class="z-keyword"> in</span><span> expected_withdrawals</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> After this existing line</span></span> <span class="giallo-l"><span> decrease_balance</span><span>(</span><span>state</span><span>,</span><span> withdrawal</span><span>.</span><span>validator_index</span><span>,</span><span> withdrawal</span><span>.</span><span>amount</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Add a new if-clause and append withdrawals for which we reset the EB</span></span> <span class="giallo-l"><span> v</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>validators</span><span>[</span><span>withdrawal</span><span>.</span><span>validator_index</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> v</span><span>.</span><span>exit_epoch</span><span class="z-keyword"> ==</span><span class="z-constant"> FAR_FUTURE_EPOCH</span><span class="z-keyword"> and</span><span> has_compounding_withdrawal_credential</span><span>(</span><span>v</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>reset_eb_flags</span><span>[</span><span>withdrawal</span><span>.</span><span>validator_index</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> True</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="relative-change-in-staking-yield">Relative change in staking yield</h3> <p>The figure shows the impact of the current EB bands and hysteresis design on validator yields for different validator configuations. The relative change in staking yield is plotted against a baseline 0 which corresponds to what compounding <code>0x02</code> validators would earn if $E=b$, as in the neutral effective balance design. Note that these are relative changes, so a validator at -0.01 under a CL yield of 3% would earn $0.99 \times 3 = 2.97$% in yield.</p> <p><img src="https://wg-eips.ritovision.com/8068/./assets/1.png" alt="Figure 1" /></p> <p>The blue line is compounding <code>0x02</code> validators, which on average will have 0.75 ETH not counting against their EB. A staker that runs a <code>0x02</code> validator instead of a <code>0x01</code> validator then earns $100\times0.75/b$% lower staking yield. For example, at 32.25 ETH, that difference works out to 2.33%.</p> <p>The red lines capture <code>0x02</code> validators that repeatedly withdraw down to the downward hysteresis threshold at $-0.25$ relative to an integer EB, thus achieving a surplus 0.25 EB relative to their actual balance. They let the balance grow until it is optimal to withdraw it, accounting for a partial withdrawal costing 84500 gas. So for example, starting at 32.75 ETH and with a 0.5 gwei base fee, that works out to making the withdrawal at around 32.80 ETH. The staker then earns 0.56% more staking yield than the baseline, factoring in a 4.5 days delay between when the withdrawn ETH stops earning yield and when it is available at the EL (dashed red line). This delay accounts for a 256 epoch withdrawal eligibility period and an average wait time until the sweep hits of 3.4 days (at a hypothetical future 770 000 active validators). Without the delay, that figure is 0.60%. When the base is 0 and there is a 4.5 days delay, the validator instead earns 0.72% more staking yield (full red line).</p> <p>The green circles are sweeped <code>0x01</code> validators. They earn slightly less than the baseline due to the accruing balance in excess of 32 ETH and 2048 ETH not counting toward the EB, and being delayed by around 3.4 days. (in this specific example where the delay )</p> <p>This comparison could be nuanced further by potentially accounting for a deposit delay, but the ETH does not necessarily need to be deposited directly into the staking contract to bring value to its holder. Another nuance is that a slashing is driven by EB and not validator balance.</p> <h3 id="equation-for-the-temporary-upward-threshold">Equation for the temporary upward threshold</h3> <p>To prevent gaming after a partial withdrawal, the EB is first reset to $E = \lfloor b_0 \rfloor$, where $b_0$ is the new balance. This creates an initial idle remainder $r_0 = b_0 - E$.</p> <p>A <code>temporary_upward_threshold</code> ($t$) is then set to ensure the <em>average</em> idle balance is zero as the validator's balance compounds from $b_0$ to the next integer, $E+1$.</p> <p>This threshold $t$ is calculated to solve the "zero-area" problem: the positive idle balance accumulated while $\text{EB}=E$ (from $b_0$ to $t$) must exactly cancel the negative idle balance accumulated while $\text{EB}=E+1$ (from $t$ to $E+1$). This is expressed by the integral equation:</p> <p>$\int_{b_0}^{t}(b-E) db + \int_{t}^{E+1}(b-(E+1)) db = 0.$</p> <p>Solving for $t$ yields the formula used in the specification:</p> <p>$t = E + \frac{1+r_0^2}{2},$</p> <p>where $r_0 = b_0 - E$.</p> <h3 id="alternative-specifications">Alternative specifications</h3> <h4 id="simple-fix-of-eb-gaming-under-current-bands">Simple fix of EB gaming under current bands</h4> <p>An alternative minimal specification is to only fix the gaming incentive, and instead compensate for the lower yield of <code>0x02</code> validators by increasing the withdrawal fee in <a href="https://wg-eips.ritovision.com/8062/">EIP-8062</a>. Only the partial withdrawal is adjusted. For this specification, only the <code>pending_eb_resets</code> need to be stored in the <code>BeaconState</code>:</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> pending_eb_resets</span><span>:</span><span> List</span><span>[</span><span>ValidatorIndex</span><span>,</span><span class="z-constant"> PENDING_PARTIAL_WITHDRAWALS_LIMIT</span><span>]</span></span></code></pre> <p>Append the validator index to <code>pending_eb_resets</code> in <code>process_withdrawals()</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"> process_withdrawals</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"> payload</span><span>:</span><span> ExecutionPayload</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 class="z-keyword"> for</span><span> withdrawal</span><span class="z-keyword"> in</span><span> expected_withdrawals</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> After this existing line</span></span> <span class="giallo-l"><span> decrease_balance</span><span>(</span><span>state</span><span>,</span><span> withdrawal</span><span>.</span><span>validator_index</span><span>,</span><span> withdrawal</span><span>.</span><span>amount</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Add a new if-clause and append withdrawals for which we reset the EB</span></span> <span class="giallo-l"><span> v</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>validators</span><span>[</span><span>withdrawal</span><span>.</span><span>validator_index</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> v</span><span>.</span><span>exit_epoch</span><span class="z-keyword"> ==</span><span class="z-constant"> FAR_FUTURE_EPOCH</span><span class="z-keyword"> and</span><span> has_compounding_withdrawal_credential</span><span>(</span><span>v</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>pending_eb_resets</span><span>.</span><span>append</span><span>(</span><span>withdrawal</span><span>.</span><span>validator_index</span><span>)</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre> <p>Modify <code>process_effective_balance_updates()</code> to reset the effective balance upon a partial withdrawal. The balance is never allowed to increase during the reset.</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_effective_balance_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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Apply EB resets for executed withdrawals</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span> state</span><span>.</span><span>pending_eb_resets</span><span>:</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>validators</span><span>[</span><span>i</span><span>]</span><span>.</span><span>effective_balance</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>balances</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> -</span><span> state</span><span>.</span><span>balances</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> %</span><span class="z-constant"> EFFECTIVE_BALANCE_INCREMENT</span><span>,</span></span> <span class="giallo-l"><span> get_max_effective_balance</span><span>(</span><span>state</span><span>.</span><span>validators</span><span>[</span><span>i</span><span>]</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>validators</span><span>[</span><span>i</span><span>]</span><span>.</span><span>effective_balance</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>pending_eb_resets</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>This EIP would trigger a mass upward change of EBs at the specific hardfork boundary. The effect of this should be analyzed furher.</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-10-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 Carlos Perezhttps://github.com/CPerezz Wei Han Nghttps://github.com/weiihann Guillaume Ballethttps://github.com/gballet https://wg-eips.ritovision.com/8058/

Reduces gas costs for deploying duplicate contract bytecode via access-list based mechanism

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a gas discount for contract deployments when the bytecode being deployed already exists in the state. By leveraging EIP-2930 access lists, any contract address included in the access list automatically contributes its code hash to a deduplication check. When the deployed bytecode matches an existing code hash from the access list, the deployment avoids paying <code>GAS_CODE_DEPOSIT * L</code> costs since clients already store the bytecode and only need to link the new account to the existing code hash.</p> <p>This EIP becomes particularly relevant with the adoption of EIP-8037, which increases <code>GAS_CODE_DEPOSIT</code> from 200 to 1,900 gas per byte. Under EIP-8037, deploying a 24kB contract would cost approximately 46.6M gas for code deposit alone, making the deduplication discount economically significant for applications that deploy identical bytecode multiple times.</p> <h2 id="motivation">Motivation</h2> <p>Currently, deploying duplicate bytecode costs the same as deploying new bytecode, even though execution clients don't store duplicated code in their databases. When the same bytecode is deployed multiple times, clients store only one copy and have multiple accounts point to the same code hash. Under EIP-8037's proposed gas costs, deploying a 24kB contract costs approximately 46.6M gas for code deposit alone (<code>1,900 × 24,576</code>). This charge is unfair for duplicate deployments where no additional storage is consumed.</p> <p>A naive "check if code exists in database" approach would break consensus because different nodes have different database contents due to mostly Sync-mode differences:</p> <ul> <li>Full-sync nodes: Retain all historical code, including from reverted/reorged transactions</li> <li>Snap-sync nodes: initially, only store code referenced in the pivot state tries, and those accumulated past the start of the sync</li> </ul> <p>Empirical analysis reveals that approximately 27,869 bytecodes existed in full-synced node databases with no live account pointing to them (as of the Cancun fork). A database lookup <code>CodeExists(hash)</code> would yield different results on different nodes, causing different gas costs and breaking consensus.</p> <p>This proposal solves the problem by making deduplication checks implicit and deterministic through access lists, ensuring all nodes compute identical gas costs regardless of their database state. (Notice here that even if fully-synced clients have more codes, there are no accounts whose codeHash actually is referencing them. Thus, users can't profit from such discounts which keeps consensus safe).</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="implicit-deduplication-via-access-lists">Implicit Deduplication via Access Lists</h3> <p>This proposal leverages the existing EIP-2930 access list structure without any modifications. No new fields or protocol changes are required.</p> <h3 id="codehash-access-set-construction">CodeHash Access-Set Construction</h3> <p>Before transaction execution begins, build a set <code>W</code> (the "CodeHash Access-Set") as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>W = { codeHash(a) | a ∈ accessList, a exists in state, a has code }</span></span></code></pre> <p>Where:</p> <ul> <li><code>W</code> is built from state at the <strong>start</strong> of transaction execution (before any state changes)</li> <li><strong>All</strong> addresses in the access list are checked - if they exist in state and have deployed code, their code hash is added to <code>W</code></li> <li>Empty accounts or accounts with no code do not contribute to <code>W</code></li> </ul> <h3 id="contract-creation-gas-accounting">Contract Creation Gas Accounting</h3> <p>When a contract creation transaction or opcode (<code>CREATE</code>/<code>CREATE2</code>) successfully completes and returns bytecode <code>B</code> of length <code>L</code>, compute <code>H = keccak256(B)</code> and apply the following gas charges:</p> <p><strong>Deduplication check:</strong></p> <ul> <li>If <code>H ∉ W</code>: Bytecode is new <ul> <li>Charge <code>GAS_CODE_DEPOSIT * L</code></li> <li>Persist bytecode <code>B</code> under hash <code>H</code></li> <li>Link the new account's <code>codeHash</code> to <code>H</code></li> </ul> </li> <li>Otherwise, link the new account's <code>codeHash</code> to the existing code hash <code>H</code></li> </ul> <p><strong>Gas costs:</strong></p> <ul> <li>The cost of reading <code>codeHash</code> for access-listed addresses is already covered by EIP-2929/2930 access costs (intrinsic access-list cost and cold→warm state access charges).</li> <li>No additional gas cost is introduced for the deduplication check itself.</li> </ul> <h3 id="implementation-pseudocode">Implementation Pseudocode</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"> Before transaction execution:</span></span> <span class="giallo-l"><span>W</span><span class="z-keyword"> =</span><span class="z-support"> set</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">for</span><span class="z-support"> tuple</span><span class="z-keyword"> in</span><span> tx</span><span>.</span><span>access_list</span><span>:</span></span> <span class="giallo-l"><span> warm</span><span>(</span><span class="z-support">tuple</span><span>.</span><span>address</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> per EIP-2930/EIP-2929 rules</span></span> <span class="giallo-l"><span> acc</span><span class="z-keyword"> =</span><span> load_account</span><span>(</span><span class="z-support">tuple</span><span>.</span><span>address</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> acc</span><span> exists</span><span class="z-keyword"> and</span><span> acc</span><span>.</span><span>code</span><span class="z-keyword"> is</span><span class="z-keyword"> not</span><span> empty</span><span>:</span></span> <span class="giallo-l"><span> W</span><span>.</span><span>add</span><span>(</span><span>acc</span><span>.</span><span>codeHash</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"> On successful CREATE/CREATE2:</span></span> <span class="giallo-l"><span>H</span><span class="z-keyword"> =</span><span> keccak256</span><span>(</span><span>B</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">if</span><span> H</span><span class="z-keyword"> in</span><span> W</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Duplicate: no deposit gas</span></span> <span class="giallo-l"><span> link_codehash</span><span>(</span><span>new_account</span><span>,</span><span> H</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"> New bytecode: charge and persist</span></span> <span class="giallo-l"><span> charge</span><span>(</span><span class="z-constant">GAS_CODE_DEPOSIT</span><span class="z-keyword"> *</span><span class="z-support"> len</span><span>(</span><span>B</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> persist_code</span><span>(</span><span>H</span><span>,</span><span> B</span><span>)</span></span> <span class="giallo-l"><span> link_codehash</span><span>(</span><span>new_account</span><span>,</span><span> H</span><span>)</span></span></code></pre><h3 id="same-block-deployments">Same-Block Deployments</h3> <p>Sequential transaction execution ensures that a deployment storing new code makes it visible to later transactions in the same block:</p> <ol> <li> <p>Transaction <code>T_A</code> deploys bytecode <code>B</code> at address <code>X</code></p> <ul> <li>Pays full <code>GAS_CODE_DEPOSIT * L</code> (no prior contract has this bytecode)</li> <li>Code is stored under hash <code>H = keccak256(B)</code></li> </ul> </li> <li> <p>Later transaction <code>T_B</code> in the same block deploys the same bytecode <code>B</code>:</p> <ul> <li><code>T_B</code> includes address <code>X</code> in its access list</li> <li>When <code>T_B</code> executes, <code>W</code> is built from the current state (including <code>T_A</code>'s changes)</li> <li>Since <code>X</code> now exists and is in the access list, <code>W</code> contains <code>H</code></li> <li><code>T_B</code>'s deployment gets the discount</li> </ul> </li> </ol> <blockquote> <p>While this only tries to formalize the behavior, it's important to remark that this kind of behavior is complex. As it requires control over tx ordering in order to abuse. Builders can't modify the access list as it is already signed with the transaction. Nevertheless, this could happen, thus is formalized here.</p> </blockquote> <h3 id="edge-case-simultaneous-new-deployments">Edge Case: Simultaneous New Deployments</h3> <p>If two transactions in the same block both deploy identical new bytecode and neither references an existing contract with that bytecode in their access lists, both will pay full <code>GAS_CODE_DEPOSIT * L</code>.</p> <p><strong>Example:</strong></p> <ul> <li>Transaction <code>T_A</code> deploys bytecode <code>B</code> producing code hash <code>0xCA</code> at address <code>X</code></li> <li>Transaction <code>T_B</code> (later in same block) also deploys bytecode <code>B</code> producing code hash <code>0xCA</code> at address <code>Y</code></li> <li>If <code>T_B</code>'s access list does NOT include address <code>X</code>, then <code>T_B</code> pays full deposit cost</li> <li>Deduplication only occurs when the deploying address is included in the access list</li> </ul> <p>This is acceptable because:</p> <ul> <li>The first deployment cannot be known at transaction construction time</li> <li>Deduplication requires implicit opt-in via access list</li> <li>This scenario is extremely rare in practice</li> <li>The complexity of special handling is not worth the minimal benefit</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="why-access-list-based-deduplication">Why Access-List Based Deduplication?</h3> <p>The access-list approach provides several critical properties:</p> <ol> <li> <p>Deterministic behavior: The result depends only on the transaction's access list and current state, not on local database contents. All nodes compute the same gas cost.</p> </li> <li> <p>No reverse index requirement: Unlike other approaches, this doesn't require maintaining a <code>codeHash → [accounts]</code> reverse index, which would add significant complexity and storage overhead.</p> </li> <li> <p>Leverages existing infrastructure: Builds on EIP-2930 access lists and EIP-2929 access costs, requiring minimal protocol changes.</p> </li> <li> <p>Implicit optimization: Any address included in the access list automatically contributes to deduplication. This provides automatic gas optimization without requiring explicit flags or special handling.</p> </li> <li> <p>Avoids chain split risks: Since no new transaction structure is introduced, there's no risk of nodes rejecting transactions with unknown fields. The same transaction format works before and after the fork, with only the gas accounting rules changing at fork activation.</p> </li> <li> <p>Forward compatibility: All nodes enforce identical behavior. Wallets can add addresses to access lists to optimize gas, but this doesn't change transaction validity.</p> </li> <li> <p>Avoid having a code-root for state: At this point, clients handle code storage on their own ways. They don't have any consensus on the deployed existing codes (besides that all of the ones referenced in account's codehash fields exist). Changing this seems a lot more complex and unnecessary.</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal requires a scheduled network upgrade but is designed to be forward-compatible with existing transactions.</p> <p><strong>Transaction compatibility:</strong></p> <ul> <li>No changes to transaction structure - uses existing EIP-2930 access lists</li> <li>Existing transactions with access lists automatically benefit from deduplication post-fork</li> <li>Transactions without access lists behave identically to current behavior (no deduplication discount)</li> </ul> <p><strong>Wallet and tooling updates:</strong></p> <ul> <li>RPC methods like <code>eth_estimateGas</code> SHOULD account for potential deduplication discounts when access lists are present</li> <li>Wallets MAY provide UI for users to add addresses to access lists for deduplication</li> <li>Transaction builders MAY automatically detect duplicate deployments and include relevant addresses in access lists</li> </ul> <p><strong>Node implementation:</strong></p> <ul> <li>No changes to state trie structure or database schema required</li> <li>No changes to transaction parsing or RLP encoding</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="example-transaction">Example Transaction</h3> <p>Deploying a contract with the same bytecode as the contract at <code>0x1234...5678</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">from</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xabcd...ef00</span><span class="z-punctuation z-definition z-string">&quot;</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-constant"> null</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">0x608060405234801561001...</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">accessList</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">0x1234567890123456789012345678901234567890</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">storageKeys</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></code></pre> <p>If the deployed bytecode hash matches <code>codeHash(0x1234...5678)</code> (which is automatically checked because the address is in the access list), the deployment receives the deduplication discount.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="gas-cost-accuracy">Gas Cost Accuracy</h3> <p>The deduplication mechanism ensures that gas costs accurately reflect actual resource consumption. Duplicate deployments don't consume additional storage, so they shouldn't pay storage costs.</p> <h3 id="denial-of-service">Denial of Service</h3> <p>The access-list mechanism prevents DoS attacks because:</p> <ul> <li>The cost of reading <code>codeHash</code> is already covered by EIP-2929/2930</li> <li>No additional state lookups or database queries are required</li> <li>The deduplication check is O(1) (set membership test)</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> 2025-10-22T00:00:00+00:00 2026-02-11T14:49:28+00:00 Maria Silvahttps://github.com/misilva73 https://wg-eips.ritovision.com/8059/

Gas parameters and variables are increased to a factor of `REBASE_FACTOR` to reduce rounding errors without major changes to the EVM

<h2 id="abstract">Abstract</h2> <p>This proposal rebases Ethereum’s gas unit to a factor of <code>REBASE_FACTOR</code> to enable high-precision metering without introducing fractional gas. All gas-related parameters and variables are increased to a factor of <code>REBASE_FACTOR</code>. This reduces rounding errors that arise when repricing EVM operations and future-proofs gas costs as hardware improves and state access remains costly, while avoiding major changes in the internal logic of the EVM.</p> <h2 id="motivation">Motivation</h2> <p>Currently, most EVM compute operations (<code>ADD</code>, <code>SUB</code>, <code>MUL</code>, etc.) are significantly underpriced when compared with state operations (<code>SSTORE</code>, <code>SLOAD</code>, <code>CREATE</code>, etc.). There are two factors contributing to this mismatch. On one hand, client optimizations and hardware improvements have made pure compute operations more efficient. On the other hand, with the growing size of the Ethereum state, the performance of I/O operations touching this larger state has been deteriorating. Both of these trends are expected to continue, further worsening this mismatch.</p> <p>There are a couple of proposals to reduce the cost of compute operations (<a href="https://wg-eips.ritovision.com/7904/">EIP-7904</a>) and increase the cost of state operations (<a href="https://wg-eips.ritovision.com/8032/">EIP-8032</a>, <a href="https://wg-eips.ritovision.com/8037/">EIP-8037</a>, and <a href="https://wg-eips.ritovision.com/8038/">EIP-8038</a>). However, given the current level of mismatch between these operations, there is an inherent trade-off in the anchor we use to reprice these operations.</p> <p>If we make compute operations cheaper, we will introduce rounding errors, with most compute operations costing 1, when they should cost a fraction of that. These rounding errors impact scalability because we can now fit fewer of these cheaper operations in any given block. However, if we price all operations so that the fastest opcode is assigned 1 gas, we would need to make all other operations significantly more expensive, including both compute and state operations. Such a level of price increases would severely reduce throughput at current block limits.</p> <p>To illustrate this point, let's focus on the pure compute operations. As compute operations impact only block execution time, the chosen anchor will induce a specific million gas per second rate on all compute opcodes. For instance, if we anchor on <code>EcRecover</code> at the current price (3000 gas units), this induces a rate of 175Mgas/s, based on the execution time estimated for this opcode on <a href="../07904/assets/gas-cost-estimator-report.pdf">EIP-7904's empirical analysis</a>. The following plot shows the average rounding errors of compute operations for different anchors, using the same execution time estimates from EIP-7904.</p> <p><img src="https://wg-eips.ritovision.com/8059/./assets/round_error_by_anchor.png" alt="round_error_by_anchor" /></p> <p>As we can see, with an anchor of 50Mgas/s (which would result in a gas limit of 100Mgas, assuming a 2-second block execution limit), we would get an average rounding error of 59.3%. This means that we could be 59.3% cheaper on average per opcode if we didn't have to round to integer gas units. Only after a 400Mgas/s anchor do we get to reasonably low rounding errors. Without fractional gas, which would introduce further complexity to the EVM gas calculation, this level of Mgas/s anchor requires a major rebase of the gas model, where all opcodes become significantly more expensive, and both the transaction-level and block-level gas limits increase by the same factor.</p> <h2 id="specification">Specification</h2> <table><thead><tr><th style="text-align: center"><strong>Parameter</strong></th><th style="text-align: center"><strong>Value</strong></th></tr></thead><tbody> <tr><td style="text-align: center"><code>REBASE_FACTOR</code></td><td style="text-align: center">1000</td></tr> </tbody></table> <p>This proposal introduces a gas rebase such that all gas-related parameters and variables are increased by a factor of <code>REBASE_FACTOR</code>.</p> <p>At fork boundary, <code>calculate_base_fee_per_gas</code> is updated so that both <code>parent_gas_used</code> and <code>parent_base_fee_per_gas</code> are also scaled by a factor of <code>REBASE_FACTOR</code>.</p> <h2 id="rationale">Rationale</h2> <p>A rebase factor of 1000 has two advantages:</p> <ol> <li>It is large enough to completely remove rounding errors for compute operations now and to be future-proof. As we can see from the motivation, an anchor of 400Mgas/s would be enough to reduce these errors. Assuming a 2-second block execution time, this results in a block limit of 800M gas units, which requires an increase of 22x over the current 36M block limit.</li> <li>It makes reasoning about the new gas unit simpler. Block limits and targets move from million units to billion units, while gas costs move from units to thousand units.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backwards incompatible gas repricing that requires a scheduled network upgrade.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Increasing the cost of state access operations could impact the usability of certain applications. More analysis is needed to understand the potential effects on various dApps and user behaviors.</p> <p>In addition, the increase in units in <code>gasLimit</code> and <code>gasUsed</code> will increase the size of the RLP representation the block header by 2 bytes. More analysis is needed to assess the bandwidth impacts.</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-10-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Chris Ridmannhttps://github.com/cridmannchris@superstate.co Daniel Gretzkehttps://github.com/gretzke Gilbert Shihchung.shih@robinhood.com Tino Martinez Molinahttps://github.com/tinom9 https://wg-eips.ritovision.com/8056/

Equity Token support for Stock Splits

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a standard extension to <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens that enables issuers to apply an updatable multiplier to the UI (user interface) amount of tokens. This allows for efficient representation of stock splits, without requiring actual token minting or transfers. The extension provides a cosmetic layer that modifies how token balances are displayed to users while maintaining the underlying token economics.</p> <h2 id="motivation">Motivation</h2> <p>Current ERC-20 implementations lack an efficient mechanism to handle real-world asset scenarios such as stock splits: When a company performs a 2-for-1 stock split, all shareholders should see their holdings double. Currently, this requires minting new tokens to all holders, which is gas-intensive and operationally complex. Moreover, the internal accounting in DeFi protocols would break from such a split.</p> <p>The inability to efficiently handle this scenario limits the adoption of tokenized real-world assets (RWAs) on Ethereum. This EIP addresses these limitations by introducing a multiplier mechanism that adjusts the displayed balance without altering the actual token supply.</p> <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="core-interface">Core Interface</h3> <p>Compliant contracts MUST implement the <code>IScaledUIAmount</code> 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"> IScaledUIAmount</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Emitted when the UI multiplier is updated</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UIMultiplierUpdated</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> oldMultiplier</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> newMultiplier</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> effectiveAtTimestamp</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: Emitted during a token transfer with the UI-adjusted amount</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferWithUIAmount</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"> amount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> uiAmount</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 current UI multiplier</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Multiplier is represented with 18 decimals (1e18 = 1.0)</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> uiMultiplier</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></span></code></pre> <p>Note: How the multiplier is updated is an implementation detail left to the token issuer. The reference implementation below shows one approach using a <code>setUIMultiplier</code> function with delayed effectiveness.</p> <h3 id="optional-extension-conversion">Optional Extension: Conversion</h3> <p>Contracts MAY implement the <code>IScaledUIAmountConversion</code> extension for on-chain conversion helpers:</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"> IScaledUIAmountConversion</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Converts a raw token amount to UI amount</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> toUIAmount</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> rawAmount</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-comment"> Converts a UI amount to raw token amount</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> fromUIAmount</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> uiAmount</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="optional-extension-balances">Optional Extension: Balances</h3> <p>Contracts MAY implement the <code>IScaledUIAmountBalances</code> extension for on-chain UI balance queries:</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"> IScaledUIAmountBalances</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Returns the UI-adjusted balance of an account</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOfUI</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 class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Returns the UI-adjusted total supply</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalSupplyUI</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></span></code></pre><h3 id="interface-detection">Interface Detection</h3> <p>Compliant contracts MUST implement <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> and return <code>true</code> when queried for the <code>IScaledUIAmount</code> interface ID.</p> <p>Contracts implementing optional extensions MUST also return <code>true</code> for their respective interface IDs.</p> <p>The interface identifiers are:</p> <ul> <li><code>IScaledUIAmount</code>: <code>0xa60bf13d</code></li> <li><code>IScaledUIAmountConversion</code>: <code>0xTBD</code></li> <li><code>IScaledUIAmountBalances</code>: <code>0xd890fd71</code></li> </ul> <h3 id="implementation-requirements">Implementation Requirements:</h3> <ol> <li> <p>ERC-165 Support: Compliant contracts MUST implement <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface detection.</p> </li> <li> <p>Multiplier Precision: The UI multiplier MUST use 18 decimal places for precision (1e18 represents a multiplier of 1.0).</p> </li> <li> <p>Backwards Compatibility: The standard ERC-20 functions (balanceOf, transfer, transferFrom, etc.) MUST continue to work with raw amounts.</p> </li> <li> <p>Event Emission: The UIMultiplierUpdated event MUST be emitted whenever the multiplier is changed.</p> </li> </ol> <h3 id="reference-implementation">Reference Implementation</h3> <p>The following implementation includes the core interface and all optional extensions:</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"> ScaledUIToken</span><span class="z-storage"> is</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC20</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC165</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> IScaledUIAmount</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> IScaledUIAmountConversion</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> IScaledUIAmountBalances</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> Ownable</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> MULTIPLIER_DECIMALS </span><span class="z-keyword">=</span><span class="z-constant"> 1e18</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> _uiMultiplier </span><span class="z-keyword">=</span><span> MULTIPLIER_DECIMALS</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Initially 1.0</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> public</span><span> _nextUiMultiplier </span><span class="z-keyword">=</span><span> MULTIPLIER_DECIMALS</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> public</span><span> _nextUiMultiplierEffectiveAt </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-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"> ERC20</span><span>(</span><span>name, symbol) </span><span>{</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ERC-165 interface detection</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"> 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> <span class="giallo-l"><span> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IScaledUIAmount</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>IScaledUIAmountConversion</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>IScaledUIAmountBalances</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-comment"> //</span><span class="z-comment"> ============ Core Interface ============</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"> uiMultiplier</span><span>(</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 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> currentTime </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-keyword"> if</span><span> (</span><span>currentTime </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> _nextUiMultiplierEffectiveAt</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _nextUiMultiplier</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> _uiMultiplier</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"> Implementation-specific: How the multiplier is updated</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setUIMultiplier</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> newMultiplier</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> effectiveAtTimestamp</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-keyword"> require</span><span>(</span><span>newMultiplier </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Multiplier must be positive&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> currentTime </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-keyword"> require</span><span>(</span><span>effectiveAtTimestamp </span><span class="z-keyword">&gt;</span><span> currentTime</span><span>,</span><span class="z-string"> &quot;Effective At must be in the future&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>currentTime </span><span class="z-keyword">&gt;</span><span> _nextUiMultiplierEffectiveAt</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> oldMultiplier </span><span class="z-keyword">=</span><span> _nextUiMultiplier</span><span>;</span></span> <span class="giallo-l"><span> _uiMultiplier </span><span class="z-keyword">=</span><span> oldMultiplier</span><span>;</span></span> <span class="giallo-l"><span> _nextUiMultiplier </span><span class="z-keyword">=</span><span> newMultiplier</span><span>;</span></span> <span class="giallo-l"><span> _nextUiMultiplierEffectiveAt </span><span class="z-keyword">=</span><span> effectiveAtTimestamp</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> UIMultiplierUpdated</span><span>(</span><span>oldMultiplier</span><span>,</span><span> newMultiplier</span><span>,</span><span> effectiveAtTimestamp</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-support"> uint256</span><span> oldMultiplier </span><span class="z-keyword">=</span><span> _uiMultiplier</span><span>;</span></span> <span class="giallo-l"><span> _nextUiMultiplier </span><span class="z-keyword">=</span><span> newMultiplier</span><span>;</span></span> <span class="giallo-l"><span> _nextUiMultiplierEffectiveAt </span><span class="z-keyword">=</span><span> effectiveAtTimestamp</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> UIMultiplierUpdated</span><span>(</span><span>oldMultiplier</span><span>,</span><span> newMultiplier</span><span>,</span><span> effectiveAtTimestamp</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 class="z-comment"> ============ Optional: Conversion Extension ============</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"> toUIAmount</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> rawAmount</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 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> currentTime </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-keyword"> if</span><span> (</span><span>currentTime </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> _nextUiMultiplierEffectiveAt</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>rawAmount </span><span class="z-keyword">*</span><span> _nextUiMultiplier</span><span>)</span><span class="z-keyword"> /</span><span> MULTIPLIER_DECIMALS</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>rawAmount </span><span class="z-keyword">*</span><span> _uiMultiplier</span><span>)</span><span class="z-keyword"> /</span><span> MULTIPLIER_DECIMALS</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"> fromUIAmount</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> uiAmount</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 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> currentTime </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-keyword"> if</span><span> (</span><span>currentTime </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> _nextUiMultiplierEffectiveAt</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>uiAmount </span><span class="z-keyword">*</span><span> MULTIPLIER_DECIMALS</span><span>)</span><span class="z-keyword"> /</span><span> _nextUiMultiplier</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>uiAmount </span><span class="z-keyword">*</span><span> MULTIPLIER_DECIMALS</span><span>)</span><span class="z-keyword"> /</span><span> _uiMultiplier</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"> ============ Optional: Balances Extension ============</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"> balanceOfUI</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-storage z-type"> override</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 class="z-entity z-name"> toUIAmount</span><span>(</span><span class="z-entity z-name">balanceOf</span><span>(</span><span>account</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"> totalSupplyUI</span><span>(</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 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 class="z-entity z-name"> toUIAmount</span><span>(</span><span class="z-entity z-name">totalSupply</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-comment"> //</span><span class="z-comment"> ============ Optional: TransferWithUIAmount Event ============</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">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"> 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-variable z-language"> super</span><span>.</span><span class="z-entity z-name">_update</span><span>(</span><span>from</span><span>,</span><span> to</span><span>,</span><span> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> uiAmount </span><span class="z-keyword">=</span><span class="z-entity z-name"> toUIAmount</span><span>(</span><span>amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> TransferWithUIAmount</span><span>(</span><span>from</span><span>,</span><span> to</span><span>,</span><span> amount</span><span>,</span><span> uiAmount</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>Design Decisions:</p> <ol> <li> <p>Separate UI Functions: Rather than modifying the core ERC-20 functions, we provide separate UI-specific functions. This ensures backward compatibility and allows integrators to opt-in to the UI scaling feature.</p> </li> <li> <p>18 Decimal Precision: Using 18 decimals for the multiplier provides sufficient precision for most use cases while aligning with Ethereum's standard decimal representation.</p> </li> <li> <p>No Automatic Updates: The multiplier must be explicitly set by authorized parties, giving issuers full control over when and how adjustments are made.</p> </li> <li> <p>Raw Amount Preservation: All actual token operations continue to use raw amounts, ensuring that the multiplier is purely a display feature and doesn't affect the underlying token economics.</p> </li> <li> <p>Optional Extensions: Following the pattern established by <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>, helper functions like <code>toUIAmount</code>, <code>fromUIAmount</code>, <code>balanceOfUI</code>, and <code>totalSupplyUI</code> are defined in separate optional interfaces. The <code>TransferWithUIAmount</code> event is defined in the core interface as optional since events do not affect interface IDs. This keeps the core interface minimal while allowing contracts to opt-in to additional on-chain functionality. Integrators can detect support for these extensions using <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface detection.</p> </li> </ol> <p>Alternative Approaches Considered:</p> <ol> <li> <p>Rebasing Tokens: While rebasing tokens adjust supply automatically, they create complexity for integrators and can break composability with DeFi protocols.</p> </li> <li> <p>Wrapper Tokens: Creating wrapper tokens for each adjustment event adds unnecessary complexity and gas costs.</p> </li> <li> <p>Index/Exchange Rate Tokens confer similar advantages to the proposed Scaled UI approach, but is ultimately less intuitive and requires more calculations on the UI layers.</p> </li> <li> <p>Off-chain Solutions: Purely off-chain solutions lack standardization and require trust in centralized providers.</p> </li> </ol> <p><img src="https://wg-eips.ritovision.com/8056/./assets/token_value_repr.jpeg" alt="Token Value Representation Approaches" /></p> <p><img src="https://wg-eips.ritovision.com/8056/./assets/token_arch_layers.jpeg" alt="Token Architecture Layers" /></p> <h3 id="backwards-compatibility">Backwards Compatibility</h3> <p>This EIP is fully backwards compatible with ERC-20. Existing ERC-20 functions continue to work as expected, and the UI scaling features are opt-in through additional functions.</p> <h3 id="test-cases">Test Cases</h3> <p>Example test scenarios:</p> <ol> <li>Initial Multiplier Test:</li> </ol> <ul> <li> <p>Verify that initial multiplier is 1.0 (1e18)</p> </li> <li> <p>Confirm balanceOf equals balanceOfUI initially</p> </li> </ul> <ol start="2"> <li>Stock Split Test:</li> </ol> <ul> <li> <p>Set multiplier to 2.0 (2e18) for 2-for-1 split</p> </li> <li> <p>Verify UI balance is double the raw balance</p> </li> <li> <p>Confirm conversion functions work correctly</p> </li> </ul> <h2 id="security-considerations">Security Considerations</h2> <ol> <li>Multiplier Manipulation</li> </ol> <ul> <li> <p>Unauthorized changes to the UI multiplier could mislead users about their holdings</p> </li> <li> <p>Implementations MUST use robust access control mechanisms</p> </li> <li> <p>The setUIMultiplier function MUST be restricted to authorized addresses (e.g., contract owner or a designated role).</p> </li> </ul> <ol start="2"> <li>Integer Overflow</li> </ol> <ul> <li> <p>Risk of overflow when applying the multiplier</p> </li> <li> <p>Use SafeMath or Solidity 0.8.0+ automatic overflow protection</p> </li> </ul> <ol start="3"> <li>User Confusion</li> </ol> <ul> <li> <p>Clear communication is essential when UI amounts differ from raw amounts</p> </li> <li> <p>Integrators MUST clearly indicate when displaying UI-adjusted balances</p> </li> </ul> <ol start="4"> <li>Oracle Dependency</li> </ol> <ul> <li> <p>For automated multiplier updates, the system may depend on oracles</p> </li> <li> <p>Oracle failures or manipulations could affect displayed balances</p> </li> </ul> <ol start="5"> <li>Overflow Protection: Implementations MUST handle potential overflow when applying the multiplier.</li> </ol> <h3 id="implementation-guide-for-integrators">Implementation Guide for Integrators</h3> <h4 id="wallet-integration">Wallet Integration</h4> <p>Wallets supporting this standard should:</p> <ol> <li> <p>Check if a token implements <code>IScaledUIAmount</code> interface using ERC-165</p> </li> <li> <p>Optionally check for <code>IScaledUIAmountBalances</code> extension for on-chain balance queries</p> </li> <li> <p>Display both raw and UI amounts, clearly labeled</p> </li> <li> <p>Compute UI balance off-chain using <code>balanceOf()</code> and <code>uiMultiplier()</code>, or use <code>balanceOfUI()</code> if the extension is supported</p> </li> <li> <p>Handle transfers using raw amounts (standard ERC-20 functions)</p> </li> </ol> <p><strong>Example JavaScript integration:</strong></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"> MULTIPLIER_DECIMALS</span><span class="z-keyword"> =</span><span class="z-entity z-name"> BigInt</span><span>(</span><span class="z-constant">1e18</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"> Interface IDs for ERC-165 detection</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> ISCALED_UI_AMOUNT_ID</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xa60bf13d</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> ISCALED_UI_BALANCES_ID</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd890fd71</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"> Off-chain conversion functions</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> toUIAmount</span><span>(</span><span class="z-variable">rawAmount</span><span>,</span><span class="z-variable"> multiplier</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-entity z-name">BigInt</span><span>(</span><span class="z-variable z-other">rawAmount</span><span>)</span><span class="z-keyword"> *</span><span class="z-entity z-name"> BigInt</span><span>(</span><span class="z-variable z-other">multiplier</span><span>)</span><span>)</span><span class="z-keyword"> /</span><span class="z-variable z-other z-constant"> MULTIPLIER_DECIMALS</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"> fromUIAmount</span><span>(</span><span class="z-variable">uiAmount</span><span>,</span><span class="z-variable"> multiplier</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-entity z-name">BigInt</span><span>(</span><span class="z-variable z-other">uiAmount</span><span>)</span><span class="z-keyword"> *</span><span class="z-variable z-other z-constant"> MULTIPLIER_DECIMALS</span><span>)</span><span class="z-keyword"> /</span><span class="z-entity z-name"> BigInt</span><span>(</span><span class="z-variable z-other">multiplier</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">async</span><span class="z-storage z-type"> function</span><span class="z-entity z-name"> displayBalance</span><span>(</span><span class="z-variable">tokenAddress</span><span>,</span><span class="z-variable"> userAddress</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"> token</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-variable z-other"> ethers</span><span>.</span><span class="z-entity z-name">Contract</span><span>(</span><span class="z-variable z-other">tokenAddress</span><span>,</span><span class="z-variable z-other"> ScaledUIAmountABI</span><span>,</span><span class="z-variable z-other"> provider</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 if core scaled UI is supported</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> supportsScaledUI</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">supportsInterface</span><span>(</span><span class="z-variable z-other z-constant">ISCALED_UI_AMOUNT_ID</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">supportsScaledUI</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Fall back to standard ERC-20</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> balance</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">balanceOf</span><span>(</span><span class="z-variable z-other">userAddress</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> {</span></span> <span class="giallo-l"><span> display</span><span>:</span><span class="z-entity z-name"> formatUnits</span><span>(</span><span class="z-variable z-other">balance</span><span>,</span><span class="z-variable z-other"> decimals</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> raw</span><span>:</span><span class="z-entity z-name"> formatUnits</span><span>(</span><span class="z-variable z-other">balance</span><span>,</span><span class="z-variable z-other"> decimals</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> multiplier</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 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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Check if optional balances extension is supported</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> supportsBalancesExt</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">supportsInterface</span><span>(</span><span class="z-variable z-other z-constant">ISCALED_UI_BALANCES_ID</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"> rawBalance</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">balanceOf</span><span>(</span><span class="z-variable z-other">userAddress</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"> multiplier</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">uiMultiplier</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"> Use on-chain balanceOfUI if available, otherwise compute off-chain</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> uiBalance</span><span class="z-keyword"> =</span><span class="z-variable z-other"> supportsBalancesExt</span></span> <span class="giallo-l"><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">balanceOfUI</span><span>(</span><span class="z-variable z-other">userAddress</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> :</span><span class="z-entity z-name"> toUIAmount</span><span>(</span><span class="z-variable z-other">rawBalance</span><span>,</span><span class="z-variable z-other"> multiplier</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> {</span></span> <span class="giallo-l"><span> display</span><span>:</span><span class="z-entity z-name"> formatUnits</span><span>(</span><span class="z-variable z-other">uiBalance</span><span>,</span><span class="z-variable z-other"> decimals</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> raw</span><span>:</span><span class="z-entity z-name"> formatUnits</span><span>(</span><span class="z-variable z-other">rawBalance</span><span>,</span><span class="z-variable z-other"> decimals</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> multiplier</span><span>:</span><span class="z-entity z-name"> formatUnits</span><span>(</span><span class="z-variable z-other">multiplier</span><span>,</span><span class="z-constant"> 18</span><span>)</span></span> <span class="giallo-l"><span> }</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="exchange-integration">Exchange Integration</h4> <p>Exchanges should:</p> <ol> <li> <p>Store and track the multiplier for each supported token</p> </li> <li> <p>Display UI amounts in user interfaces</p> </li> <li> <p>Use raw amounts for all internal accounting</p> </li> <li> <p>Provide clear documentation about the scaling mechanism</p> </li> </ol> <p>Example implementation:</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"> MULTIPLIER_DECIMALS</span><span class="z-keyword"> =</span><span class="z-entity z-name"> BigInt</span><span>(</span><span class="z-constant">1e18</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"> ScaledTokenHandler</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Off-chain conversion functions</span></span> <span class="giallo-l"><span class="z-entity z-name"> toUIAmount</span><span>(</span><span class="z-variable">rawAmount</span><span>,</span><span class="z-variable"> multiplier</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-entity z-name">BigInt</span><span>(</span><span class="z-variable z-other">rawAmount</span><span>)</span><span class="z-keyword"> *</span><span class="z-entity z-name"> BigInt</span><span>(</span><span class="z-variable z-other">multiplier</span><span>)</span><span>)</span><span class="z-keyword"> /</span><span class="z-variable z-other z-constant"> MULTIPLIER_DECIMALS</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"> fromUIAmount</span><span>(</span><span class="z-variable">uiAmount</span><span>,</span><span class="z-variable"> multiplier</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-entity z-name">BigInt</span><span>(</span><span class="z-variable z-other">uiAmount</span><span>)</span><span class="z-keyword"> *</span><span class="z-variable z-other z-constant"> MULTIPLIER_DECIMALS</span><span>)</span><span class="z-keyword"> /</span><span class="z-entity z-name"> BigInt</span><span>(</span><span class="z-variable z-other">multiplier</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"> async</span><span class="z-entity z-name"> processDeposit</span><span>(</span><span class="z-variable">tokenAddress</span><span>,</span><span class="z-variable"> amount</span><span>,</span><span class="z-variable"> isUIAmount</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"> token</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-variable z-other"> ethers</span><span>.</span><span class="z-entity z-name">Contract</span><span>(</span><span class="z-variable z-other">tokenAddress</span><span>,</span><span class="z-variable z-other"> ScaledUIAmountABI</span><span>,</span><span class="z-variable z-other"> provider</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> rawAmount</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-other">isUIAmount</span><span class="z-keyword"> &amp;&amp;</span><span class="z-keyword"> await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">supportsScaledUI</span><span>(</span><span class="z-variable z-other">tokenAddress</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"> multiplier</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">uiMultiplier</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> rawAmount</span><span class="z-keyword"> =</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">fromUIAmount</span><span>(</span><span class="z-variable z-other">amount</span><span>,</span><span class="z-variable z-other"> multiplier</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"> rawAmount</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 class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Process deposit with raw amount</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">recordDeposit</span><span>(</span><span class="z-variable z-other">tokenAddress</span><span>,</span><span class="z-variable z-other"> rawAmount</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"> async</span><span class="z-entity z-name"> getDisplayBalance</span><span>(</span><span class="z-variable">tokenAddress</span><span>,</span><span class="z-variable"> userAddress</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"> token</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-variable z-other"> ethers</span><span>.</span><span class="z-entity z-name">Contract</span><span>(</span><span class="z-variable z-other">tokenAddress</span><span>,</span><span class="z-variable z-other"> ScaledUIAmountABI</span><span>,</span><span class="z-variable z-other"> provider</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"> rawBalance</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">getInternalBalance</span><span>(</span><span class="z-variable z-other">userAddress</span><span>,</span><span class="z-variable z-other"> tokenAddress</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">await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">supportsScaledUI</span><span>(</span><span class="z-variable z-other">tokenAddress</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"> multiplier</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">uiMultiplier</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">toUIAmount</span><span>(</span><span class="z-variable z-other">rawBalance</span><span>,</span><span class="z-variable z-other"> multiplier</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"> rawBalance</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><h4 id="defi-protocol-integration">DeFi Protocol Integration</h4> <p>DeFi protocols should:</p> <ol> <li> <p>Continue using raw amounts for all protocol operations</p> </li> <li> <p>Provide UI helpers for displaying adjusted amounts</p> </li> <li> <p>Emit events with both raw and UI amounts where relevant</p> </li> <li> <p>Document clearly which amounts are used in calculations</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> 2025-10-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ben Adamshttps://github.com/benaadams Toni Wahrstätterhttps://github.com/nerolation Maria Inês Silvahttps://github.com/misilva73 Amirul Ashrafhttps://github.com/asdacap https://wg-eips.ritovision.com/8057/

Multi‑block temporal locality discounts for state and account access

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a deterministic, multi-block discount for the first access to accounts and storage keys in a transaction. The discount depends on how many blocks have passed since the item was last accessed, decaying smoothly to zero over a fixed recent window. Intra-block warming semantics are unchanged - there is no warming across transactions within a block.</p> <p>The mechanism builds on block-level access lists (<a href="https://wg-eips.ritovision.com/7928/">EIP-7928</a>), which are committed in prior blocks. This allows a newly synced node to correctly price the first block it validates without replaying historical execution.</p> <h2 id="motivation">Motivation</h2> <p>Current warm and cold access pricing correctly models client state costs in the <em>worst case</em> but leaves a predictable efficiency gap in the <em>common case</em>. Clients maintain short-lived in-memory caches of recently accessed accounts and storage slots to handle short reorgs and pipeline execution across blocks. These caches make accesses from recent blocks materially cheaper than fully cold loads, yet the gas model does not reflect this.</p> <p>As a result, Ethereum's gas schedule is conservative: it prices every "first access" as if it were completely cold, even though for most active contracts those lookups are served from hot caches or SSD pages still in memory. The gap between average and worst-case cost limits how far the block gas limit can safely rise-clients must size for the worst case even if most blocks are far cheaper in practice.</p> <p>We can adjust gas prices to surface this mechanical sympathy, rewarding patterns that align naturally with how hardware and clients already behave.</p> <p>This proposal narrows that gap in a deterministic and consensus-safe way. It introduces a smoothly decaying, per-item discount based solely on <em>publicly observable prior-block activity</em> recorded in block-level access lists (<a href="https://wg-eips.ritovision.com/7928/">EIP-7928</a>). That achieves three effects:</p> <ol> <li><strong>Predictability at submission time</strong> - Unlike same-block or cross-transaction warming, discounts depend only on past blocks, so users, builders, and wallets can compute exact costs deterministically from on-chain data.</li> <li><strong>Behavioural alignment</strong> - The mechanism encourages natural temporal locality: dapps and operators who reuse state within a few blocks save gas, reflecting the real cost profile of client caching.</li> <li><strong>Improved L1 scalability</strong> - By reducing the <em>average</em> gas cost of realistic workloads without changing the <em>worst case</em>, 8057 effectively raises real execution throughput per gas, helping move toward the "Scale L1" goal of larger blocks and better hardware utilisation.</li> </ol> <p>Empirically, traces show that most hot contracts are touched repeatedly within a few blocks. A 32-block (≈6-minute) window captures the majority of these recurrences. In this regime, total gas usage per block can fall by several percent in steady state, freeing execution capacity without altering consensus rules or transaction semantics.</p> <p>In short, 8057 aligns Ethereum's gas economics with real execution cost, using already-available data (BALs) to make temporal locality explicit, deterministic, and beneficial.</p> <p>As the saving depends only on publicly observable prior-block activity, it is knowable at submission time. Unlike same-block effects, it is therefore behaviour-shaping rather than incidental. It nudges workloads that naturally cluster accesses to keep doing so, matching how clients amortise repeated recent accesses.</p> <p>This proposal is intentionally scoped to per-transaction warming and does not apply intra-block warming across transactions.</p> <h2 id="specification">Specification</h2> <h3 id="terminology-and-constants">Terminology and constants</h3> <table><thead><tr><th>Name</th><th>Description</th><th>Default</th></tr></thead><tbody> <tr><td><code>WINDOW_SIZE_BLOCKS</code></td><td>Number of recent blocks over which a discount may apply.</td><td><code>32</code></td></tr> <tr><td><code>CURRENT_BLOCK_NUMBER</code></td><td>The block number of the transaction being executed.</td><td>-</td></tr> <tr><td><code>LAST_ACCESS_BLOCK_NUMBER(item)</code></td><td>The most recent block number strictly less than <code>CURRENT_BLOCK_NUMBER</code> in which <code>item</code> was accessed by an executed transaction. If unknown or older than <code>WINDOW_SIZE_BLOCKS</code>, it is treated as not found.</td><td>-</td></tr> <tr><td><code>BLOCK_DISTANCE_IN_BLOCKS(item)</code></td><td>Defined as <code>CURRENT_BLOCK_NUMBER - LAST_ACCESS_BLOCK_NUMBER(item)</code> when the latter is found, else a value greater than <code>WINDOW_SIZE_BLOCKS</code>.</td><td>-</td></tr> </tbody></table> <p>Gas constants from existing behaviour:</p> <table><thead><tr><th>Name</th><th style="text-align: right">Value</th></tr></thead><tbody> <tr><td><code>SLOAD_WARM_GAS_COST</code></td><td style="text-align: right"><code>100</code></td></tr> <tr><td><code>SLOAD_COLD_SURCHARGE_GAS</code></td><td style="text-align: right"><code>2100</code></td></tr> <tr><td><code>ACCOUNT_WARM_GAS_COST</code></td><td style="text-align: right"><code>100</code></td></tr> <tr><td><code>ACCOUNT_COLD_SURCHARGE_GAS</code></td><td style="text-align: right"><code>2600</code></td></tr> </tbody></table> <p>Discount caps (this EIP treats maximum as full cold surcharge, minimum as zero):</p> <table><thead><tr><th>Name</th><th style="text-align: right">Value</th></tr></thead><tbody> <tr><td><code>DISCOUNT_MAX_SLOAD</code></td><td style="text-align: right"><code>SLOAD_COLD_SURCHARGE_GAS</code></td></tr> <tr><td><code>DISCOUNT_MIN_SLOAD</code></td><td style="text-align: right"><code>0</code></td></tr> <tr><td><code>DISCOUNT_MAX_ACCOUNT</code></td><td style="text-align: right"><code>ACCOUNT_COLD_SURCHARGE_GAS</code></td></tr> <tr><td><code>DISCOUNT_MIN_ACCOUNT</code></td><td style="text-align: right"><code>0</code></td></tr> </tbody></table> <p>This means the closest prior-block usage allows the first access in a transaction to be charged at warm cost, and the far edge of the window trends to the normal cold-plus-warm cost.</p> <h3 id="scope-of-operations">Scope of operations</h3> <p>This EIP applies the discount to the <strong>first access in a transaction</strong> of:</p> <ul> <li>Storage keys accessed by <code>SLOAD</code> and by any operation that first reads a slot as part of its semantics (for example, <code>SSTORE</code>'s read step).</li> <li>Account touches that incur the cold account access surcharge under the current gas schedule, including but not limited to: <code>BALANCE</code>, <code>EXTCODEHASH</code>, <code>EXTCODESIZE</code>, <code>EXTCODECOPY</code>, and the target account of <code>CALL</code>, <code>CALLCODE</code>, <code>DELEGATECALL</code>, <code>STATICCALL</code>.</li> </ul> <p>Writes are affected <strong>only</strong> to the extent they perform an initial read or account touch that would have been charged as cold. Write-specific costs and any refund semantics are unchanged.</p> <p>Precompiles remain unchanged and are always warm. Because they do not pay a cold surcharge, no discount is applied to precompile calls.</p> <p>Access lists per <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> remain effective and, when present, pre-warm the listed addresses and storage keys at the start of the transaction. For items that are pre-warmed by an access list, this temporal discount does not apply.</p> <h3 id="discount-function">Discount function</h3> <p>The discount decays smoothly with block distance, using a <strong>reversed Hermite smoothstep</strong> interpolation over the discount window.</p> <p><img src="https://wg-eips.ritovision.com/8057/./assets/gas_discount_percentage.png" alt="Gas discount percentage graph" /></p> <p>Mathematically:</p> <p>$x = \mathrm{clamp}\left( \frac{D - 1}{W - 1}, 0, 1 \right)$</p> <p>$f(D, W) = d_{\text{min}} + (d_{\text{max}} - d_{\text{min}}) \cdot \left( 1 - \left( 3x^2 - 2x^3 \right) \right)$</p> <p>where:</p> <ul> <li>$D$ = block distance in blocks</li> <li>$W$ = window size in blocks</li> <li>$d_{\text{min}}$, $d_{\text{max}}$ = minimum and maximum discounts</li> </ul> <p>This form maps:</p> <ul> <li>$D = 1$ → full discount $(f = d_{\text{max}})$</li> <li>$D = W$ → no discount $(f = d_{\text{min}})$</li> </ul> <p>Programmatic form</p> <p>Reference smoothstep helper:</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"> smoothstep</span><span>(</span><span class="z-variable z-parameter z-function">edge0</span><span>:</span><span class="z-support"> float</span><span>,</span><span class="z-variable z-parameter z-function"> edge1</span><span>:</span><span class="z-support"> float</span><span>,</span><span class="z-variable z-parameter z-function"> x</span><span>:</span><span class="z-support"> float</span><span>)</span><span> -&gt;</span><span class="z-support"> float</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span><span class="z-string">Scale and clamp x to [0, 1], then apply cubic Hermite smoothstep.</span><span class="z-punctuation z-definition z-string">&quot;&quot;&quot;</span></span> <span class="giallo-l"><span> x</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span class="z-constant">0.0</span><span>,</span><span class="z-support"> min</span><span>(</span><span class="z-constant">1.0</span><span>,</span><span> (</span><span>x</span><span class="z-keyword"> -</span><span> edge0</span><span>)</span><span class="z-keyword"> /</span><span> (</span><span>edge1</span><span class="z-keyword"> -</span><span> edge0</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> x</span><span class="z-keyword"> *</span><span> x</span><span class="z-keyword"> *</span><span> (</span><span class="z-constant">3.0</span><span class="z-keyword"> -</span><span class="z-constant"> 2.0</span><span class="z-keyword"> *</span><span> x</span><span>)</span></span></code></pre> <p>Calculation steps:</p> <ul> <li><code>NORMALIZED_DISTANCE = (BLOCK_DISTANCE_IN_BLOCKS - 1) / (WINDOW_SIZE_BLOCKS - 1)</code> clamped to <code>[0, 1]</code>. This maps distance <code>1</code> → <code>0</code> and distance <code>WINDOW_SIZE_BLOCKS</code> → <code>1</code>.</li> <li><code>SMOOTHSTEP_VALUE = smoothstep(0.0, 1.0, NORMALIZED_DISTANCE)</code></li> <li><code>DISCOUNT_FACTOR = 1.0 - SMOOTHSTEP_VALUE</code> (equals <code>1.0</code> at distance <code>1</code>, and <code>0.0</code> at distance <code>WINDOW_SIZE_BLOCKS</code>)</li> </ul> <p>For a given opcode family with parameters <code>DISCOUNT_MAX</code> and <code>DISCOUNT_MIN</code>, the integer discount applied to the <strong>cold surcharge</strong> is:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">if</span><span class="z-constant"> BLOCK_DISTANCE_IN_BLOCKS</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 0</span><span class="z-keyword"> or</span><span class="z-constant"> BLOCK_DISTANCE_IN_BLOCKS</span><span class="z-keyword"> &gt;</span><span class="z-constant"> WINDOW_SIZE_BLOCKS</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> DISCOUNT_GAS</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-constant"> NORMALIZED_DISTANCE</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> 0.0</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> min</span><span>(</span><span class="z-constant">1.0</span><span>,</span><span> (</span><span class="z-constant">BLOCK_DISTANCE_IN_BLOCKS</span><span class="z-keyword"> -</span><span class="z-constant"> 1.0</span><span>)</span><span class="z-keyword"> /</span><span> (</span><span class="z-constant">WINDOW_SIZE_BLOCKS</span><span class="z-keyword"> -</span><span class="z-constant"> 1.0</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-constant"> SMOOTHSTEP_VALUE</span><span class="z-keyword"> =</span><span> smoothstep</span><span>(</span><span class="z-constant">0.0</span><span>,</span><span class="z-constant"> 1.0</span><span>,</span><span class="z-constant"> NORMALIZED_DISTANCE</span><span>)</span></span> <span class="giallo-l"><span class="z-constant"> DISCOUNT_FACTOR</span><span class="z-keyword"> =</span><span class="z-constant"> 1.0</span><span class="z-keyword"> -</span><span class="z-constant"> SMOOTHSTEP_VALUE</span></span> <span class="giallo-l"><span class="z-constant"> DISCOUNT_GAS</span><span class="z-keyword"> =</span><span class="z-constant"> DISCOUNT_MIN</span><span class="z-keyword"> +</span><span class="z-support"> round</span><span>(</span></span> <span class="giallo-l"><span> (</span><span class="z-constant">DISCOUNT_MAX</span><span class="z-keyword"> -</span><span class="z-constant"> DISCOUNT_MIN</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> DISCOUNT_FACTOR</span></span> <span class="giallo-l"><span> )</span></span></code></pre> <p>All arithmetic must be implemented in <strong>integer space</strong> in consensus-critical code; floating point is shown here only for clarity. <code>round()</code> follows <em>round half up</em> semantics; any deterministic rule is acceptable if consistently applied across clients.</p> <p>This mechanism is a <strong>discount</strong>, not a refund. It reduces gas charged upfront for a cold surcharge; it does not emit a rebate and does not affect refund accounting or receipts.</p> <h3 id="charging-rules-per-transaction">Charging rules (per transaction)</h3> <p>For the first access to an <code>ITEM</code> <strong>within a transaction</strong>:</p> <ol> <li> <p>If <code>ITEM</code> is already warm in this transaction due to same-transaction rules or pre-warmed via a transaction access list, charge the warm cost defined today. No temporal discount applies.</p> </li> <li> <p>Otherwise compute <code>BLOCK_DISTANCE_IN_BLOCKS(ITEM)</code>. If <code>1 &lt;= BLOCK_DISTANCE_IN_BLOCKS(ITEM) &lt;= WINDOW_SIZE_BLOCKS</code>, apply the discount to the cold surcharge:</p> <ul> <li> <p>Storage read first access cost:</p> <ul> <li><code>SLOAD_FIRST_ACCESS_COST = SLOAD_WARM_GAS_COST + max(0, SLOAD_COLD_SURCHARGE_GAS - DISCOUNT_SLOAD(BLOCK_DISTANCE_IN_BLOCKS))</code></li> </ul> </li> <li> <p>Account-touch first access cost:</p> <ul> <li><code>ACCOUNT_FIRST_ACCESS_COST = ACCOUNT_WARM_GAS_COST + max(0, ACCOUNT_COLD_SURCHARGE_GAS - DISCOUNT_ACCOUNT(BLOCK_DISTANCE_IN_BLOCKS))</code></li> </ul> </li> </ul> </li> <li> <p>If <code>BLOCK_DISTANCE_IN_BLOCKS(ITEM) &gt; WINDOW_SIZE_BLOCKS</code> or not found, charge the unmodified cold surcharge plus the warm component as today.</p> </li> </ol> <p>Subsequent accesses to the same <code>ITEM</code> within the <strong>same transaction</strong> are warm as per existing rules. This EIP does not introduce block-level warming across transactions.</p> <h3 id="initial-sync-and-pricing-with-block-level-access-lists">Initial sync and pricing with block-level access lists</h3> <p>This EIP requires block-level access lists in blocks. Each block carries commitments to the sets of accounts and storage keys accessed during that block.</p> <p>A newly synced node can price the very first block it validates as follows:</p> <ol> <li>For a block to validate at <code>CURRENT_BLOCK_NUMBER</code>, gather the BALs for the previous <code>WINDOW_SIZE_BLOCKS</code> blocks.</li> <li>For each of those blocks, obtain the committed sets of accessed accounts and storage keys from the block body.</li> <li>Build a local index mapping each seen <code>ITEM</code> to the most recent block number in which it appears within that window. This becomes <code>LAST_ACCESS_BLOCK_NUMBER(ITEM)</code>.</li> <li>When validating <code>CURRENT_BLOCK_NUMBER</code>, for each first access to <code>ITEM</code>, compute <code>BLOCK_DISTANCE_IN_BLOCKS(ITEM) = CURRENT_BLOCK_NUMBER - LAST_ACCESS_BLOCK_NUMBER(ITEM)</code> when present, else treat as out-of-window. Apply the discount rules above.</li> </ol> <p>Reorgs longer than <code>WINDOW_SIZE_BLOCKS</code> fall back to the same procedure as initial resync. Items not present in the new canonical window are treated as cold.</p> <p>No execution of historical transactions is required to compute the discount at validation time. Stateless verifiers can price gas using the current block plus compact proofs that an item appears in one of the previous <code>WINDOW_SIZE_BLOCKS</code> access lists.</p> <h3 id="wallet-gas-estimation-guidance">Wallet gas estimation guidance</h3> <p>Wallets and RPC endpoints should not assume that a temporal discount will apply at submission, because the exact landing block is uncertain. General-purpose estimators should price as if no temporal discount applies.</p> <p>Operators who can predict landing with high confidence - for example via priority fees and private order flow - may account for the exact discount, but this is an advanced path and not the default.</p> <p>Motivated operators who can reliably land transactions in a specific block - for example via private order flow and appropriately set priority fees - may account for the exact discount. This is an advanced use case and should not be the default behaviour for general-purpose wallets.</p> <h3 id="implementation-guidance">Implementation guidance</h3> <p>Clients are expected to maintain a rolling in-memory index to avoid rescanning prior blocks for each block:</p> <ul> <li>Keep a ring buffer of <code>WINDOW_SIZE_BLOCKS</code> buckets, one per recent block. Each bucket stores first-touched accounts and first-touched storage keys for that block.</li> <li>Maintain two maps, <code>LAST_SEEN_ACCOUNT</code> and <code>LAST_SEEN_STORAGE_KEY</code>, which track the most recent block index within the window where each item was present. On block advance, drop the oldest bucket and delete items that only appeared there, or mark them as out-of-window.</li> <li>During execution, when an opcode is about to charge a cold surcharge for an item not yet warm in the current transaction, look up <code>BLOCK_DISTANCE_IN_BLOCKS</code> from the <code>LAST_SEEN_*</code> map and charge using the rules above. Then record first touches for the current block in the current bucket and update the maps.</li> </ul> <p>This design keeps memory bounded by <code>WINDOW_SIZE_BLOCKS</code> multiplied by the number of distinct first touches per block, which is itself bounded by the block gas limit divided by the minimum per-item cost.</p> <p>This is one practical approach; clients may also implement this via existing caches or by embedding and pruning block-distance hints in their state trie.</p> <h3 id="test-cases">Test cases</h3> <h3 id="example-parameters-and-results">Example parameters and results</h3> <p>Assume the following defaults:</p> <table><thead><tr><th>Name</th><th style="text-align: right">Value</th></tr></thead><tbody> <tr><td><code>WINDOW_SIZE_BLOCKS</code></td><td style="text-align: right"><code>32</code></td></tr> <tr><td><code>SLOAD_WARM_GAS_COST</code></td><td style="text-align: right"><code>100</code></td></tr> <tr><td><code>SLOAD_COLD_SURCHARGE_GAS</code></td><td style="text-align: right"><code>2100</code></td></tr> <tr><td><code>ACCOUNT_WARM_GAS_COST</code></td><td style="text-align: right"><code>100</code></td></tr> <tr><td><code>ACCOUNT_COLD_SURCHARGE_GAS</code></td><td style="text-align: right"><code>2600</code></td></tr> <tr><td><code>DISCOUNT_MAX_SLOAD</code></td><td style="text-align: right"><code>2100</code></td></tr> <tr><td><code>DISCOUNT_MIN_SLOAD</code></td><td style="text-align: right"><code>0</code></td></tr> <tr><td><code>DISCOUNT_MAX_ACCOUNT</code></td><td style="text-align: right"><code>2600</code></td></tr> <tr><td><code>DISCOUNT_MIN_ACCOUNT</code></td><td style="text-align: right"><code>0</code></td></tr> </tbody></table> <h4 id="example-first-storage-read-in-a-transaction">Example: first storage read in a transaction</h4> <table><thead><tr><th><code>BLOCK_DISTANCE_IN_BLOCKS</code></th><th style="text-align: right">Discount</th><th style="text-align: right">Charge</th><th>Notes</th></tr></thead><tbody> <tr><td><code>1</code></td><td style="text-align: right"><code>2100</code></td><td style="text-align: right"><code>100</code></td><td>Equal to warm</td></tr> <tr><td><code>8</code></td><td style="text-align: right"><code>1827</code></td><td style="text-align: right"><code>373</code></td><td>-</td></tr> <tr><td><code>16</code></td><td style="text-align: right"><code>1101</code></td><td style="text-align: right"><code>1099</code></td><td>Mid-window</td></tr> <tr><td><code>24</code></td><td style="text-align: right"><code>347</code></td><td style="text-align: right"><code>1853</code></td><td>-</td></tr> <tr><td><code>32</code></td><td style="text-align: right"><code>0</code></td><td style="text-align: right"><code>2200</code></td><td>Window edge</td></tr> <tr><td><code>&gt;32</code></td><td style="text-align: right"><code>0</code></td><td style="text-align: right"><code>2200</code></td><td>Fully cold</td></tr> </tbody></table> <h4 id="example-first-account-touch-in-a-transaction">Example: first account touch in a transaction</h4> <table><thead><tr><th><code>BLOCK_DISTANCE_IN_BLOCKS</code></th><th style="text-align: right">Discount</th><th style="text-align: right">Charge</th><th>Notes</th></tr></thead><tbody> <tr><td><code>1</code></td><td style="text-align: right"><code>2600</code></td><td style="text-align: right"><code>100</code></td><td>Equal to warm</td></tr> <tr><td><code>8</code></td><td style="text-align: right"><code>2262</code></td><td style="text-align: right"><code>438</code></td><td>-</td></tr> <tr><td><code>16</code></td><td style="text-align: right"><code>1363</code></td><td style="text-align: right"><code>1337</code></td><td>Mid-window</td></tr> <tr><td><code>24</code></td><td style="text-align: right"><code>430</code></td><td style="text-align: right"><code>2270</code></td><td>-</td></tr> <tr><td><code>32</code></td><td style="text-align: right"><code>0</code></td><td style="text-align: right"><code>2700</code></td><td>Window edge</td></tr> <tr><td><code>&gt;32</code></td><td style="text-align: right"><code>0</code></td><td style="text-align: right"><code>2700</code></td><td>Fully cold</td></tr> </tbody></table> <p>Exact integer results are determined by the reference implementation's rounding rule (<code>round_to_nearest</code>, half-up).</p> <h3 id="reference-implementation-python-integer-only">Reference implementation (Python, integer only)</h3> <p>This implementation is normative for rounding and scaling. It uses a power-of-two fixed-point scale so divisions by the scale are exact shifts in low-level implementations. All intermediates fit below 2**53 so a JavaScript client can mirror these steps without a big number library.</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"> Gas constants</span></span> <span class="giallo-l"><span class="z-constant">SLOAD_WARM_GAS_COST</span><span class="z-keyword"> =</span><span class="z-constant"> 100</span></span> <span class="giallo-l"><span class="z-constant">SLOAD_COLD_SURCHARGE_GAS</span><span class="z-keyword"> =</span><span class="z-constant"> 2100</span></span> <span class="giallo-l"><span class="z-constant">ACCOUNT_WARM_GAS_COST</span><span class="z-keyword"> =</span><span class="z-constant"> 100</span></span> <span class="giallo-l"><span class="z-constant">ACCOUNT_COLD_SURCHARGE_GAS</span><span class="z-keyword"> =</span><span class="z-constant"> 2600</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Temporal discount parameters</span></span> <span class="giallo-l"><span class="z-constant">WINDOW_SIZE_BLOCKS</span><span class="z-keyword"> =</span><span class="z-constant"> 32</span></span> <span class="giallo-l"><span class="z-constant">DISCOUNT_MAX_SLOAD</span><span class="z-keyword"> =</span><span class="z-constant"> SLOAD_COLD_SURCHARGE_GAS</span></span> <span class="giallo-l"><span class="z-constant">DISCOUNT_MIN_SLOAD</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-constant">DISCOUNT_MAX_ACCOUNT</span><span class="z-keyword"> =</span><span class="z-constant"> ACCOUNT_COLD_SURCHARGE_GAS</span></span> <span class="giallo-l"><span class="z-constant">DISCOUNT_MIN_ACCOUNT</span><span class="z-keyword"> =</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"> Fixed-point scale (2^25 = 33,554,432)</span></span> <span class="giallo-l"><span class="z-constant">SCALE_FACTOR</span><span class="z-keyword"> =</span><span class="z-constant"> 1</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 25</span></span> <span class="giallo-l"><span class="z-constant">HALF_SCALE</span><span class="z-keyword"> =</span><span class="z-constant"> SCALE_FACTOR</span><span class="z-keyword"> &gt;&gt;</span><span class="z-constant"> 1</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"> smooth_factor_scaled</span><span>(</span><span class="z-variable z-parameter z-function">block_distance_in_blocks</span><span>:</span><span class="z-support"> int</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> window_blocks</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> WINDOW_SIZE_BLOCKS</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-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string"> Returns round_to_nearest(SCALE_FACTOR * DISCOUNT_FACTOR) where:</span></span> <span class="giallo-l"><span class="z-string"> normalized_distance = (block_distance_in_blocks - 1) / (window_blocks - 1),</span></span> <span class="giallo-l"><span class="z-string"> clamped to [0, 1]</span></span> <span class="giallo-l"><span class="z-string"> smoothstep_value = normalized_distance^2 * (3 - 2 * normalized_distance)</span></span> <span class="giallo-l"><span class="z-string"> discount_factor = 1 - smoothstep_value</span></span> <span class="giallo-l"><span class="z-string"> The result is in [0, SCALE_FACTOR].</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-keyword"> if</span><span> block_distance_in_blocks</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 0</span><span class="z-keyword"> or</span><span> block_distance_in_blocks</span><span class="z-keyword"> &gt;</span><span> window_blocks</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"> Use exact rational form to minimize scaling multiplications:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Let t = block_distance_in_blocks - 1, d = window_blocks - 1.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> discount_factor = (d^3 - 3*d*t^2 + 2*t^3) / d^3</span></span> <span class="giallo-l"><span> t</span><span class="z-keyword"> =</span><span> block_distance_in_blocks</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> d</span><span class="z-keyword"> =</span><span> window_blocks</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> d3</span><span class="z-keyword"> =</span><span> d</span><span class="z-keyword"> *</span><span> d</span><span class="z-keyword"> *</span><span> d</span></span> <span class="giallo-l"><span> t2</span><span class="z-keyword"> =</span><span> t</span><span class="z-keyword"> *</span><span> t</span></span> <span class="giallo-l"><span> t3</span><span class="z-keyword"> =</span><span> t2</span><span class="z-keyword"> *</span><span> t</span></span> <span class="giallo-l"><span> numerator</span><span class="z-keyword"> =</span><span> d3</span><span class="z-keyword"> -</span><span class="z-constant"> 3</span><span class="z-keyword"> *</span><span> d</span><span class="z-keyword"> *</span><span> t2</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span class="z-keyword"> *</span><span> t3</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Round half up</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-constant">SCALE_FACTOR</span><span class="z-keyword"> *</span><span> numerator</span><span class="z-keyword"> +</span><span> (</span><span>d3</span><span class="z-keyword"> //</span><span class="z-constant"> 2</span><span>)</span><span>)</span><span class="z-keyword"> //</span><span> d3</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"> discount_gas_units</span><span>(</span><span class="z-variable z-parameter z-function">block_distance_in_blocks</span><span>:</span><span class="z-support"> int</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> discount_max</span><span>:</span><span class="z-support"> int</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> discount_min</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-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string"> Integer discount within the window using the smooth falloff.</span></span> <span class="giallo-l"><span class="z-string"> Returns an integer number of gas units to subtract from the cold surcharge.</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-keyword"> if</span><span> block_distance_in_blocks</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 0</span><span class="z-keyword"> or</span><span> block_distance_in_blocks</span><span class="z-keyword"> &gt;</span><span class="z-constant"> WINDOW_SIZE_BLOCKS</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> factor_scaled</span><span class="z-keyword"> =</span><span> smooth_factor_scaled</span><span>(</span><span>block_distance_in_blocks</span><span>,</span><span class="z-constant"> WINDOW_SIZE_BLOCKS</span><span>)</span></span> <span class="giallo-l"><span> span</span><span class="z-keyword"> =</span><span> discount_max</span><span class="z-keyword"> -</span><span> discount_min</span></span> <span class="giallo-l"><span> scaled</span><span class="z-keyword"> =</span><span> (</span><span>span</span><span class="z-keyword"> *</span><span> factor_scaled</span><span class="z-keyword"> +</span><span class="z-constant"> HALF_SCALE</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> SCALE_FACTOR</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> discount_min</span><span class="z-keyword"> +</span><span> scaled</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"> sload_first_access_cost</span><span>(</span><span class="z-variable z-parameter z-function">block_distance_in_blocks</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> disc</span><span class="z-keyword"> =</span><span> discount_gas_units</span><span>(</span><span>block_distance_in_blocks</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> DISCOUNT_MAX_SLOAD</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> DISCOUNT_MIN_SLOAD</span><span>)</span></span> <span class="giallo-l"><span> cold_part</span><span class="z-keyword"> =</span><span class="z-constant"> SLOAD_COLD_SURCHARGE_GAS</span><span class="z-keyword"> -</span><span> disc</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> cold_part</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> cold_part</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> SLOAD_WARM_GAS_COST</span><span class="z-keyword"> +</span><span> cold_part</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"> account_first_access_cost</span><span>(</span><span class="z-variable z-parameter z-function">block_distance_in_blocks</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> disc</span><span class="z-keyword"> =</span><span> discount_gas_units</span><span>(</span><span>block_distance_in_blocks</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> DISCOUNT_MAX_ACCOUNT</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> DISCOUNT_MIN_ACCOUNT</span><span>)</span></span> <span class="giallo-l"><span> cold_part</span><span class="z-keyword"> =</span><span class="z-constant"> ACCOUNT_COLD_SURCHARGE_GAS</span><span class="z-keyword"> -</span><span> disc</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> cold_part</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> cold_part</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> ACCOUNT_WARM_GAS_COST</span><span class="z-keyword"> +</span><span> cold_part</span></span></code></pre> <p>Using lookup tables</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"> SLOAD first access cost per block distance (1-32)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> WINDOW_SIZE_BLOCKS = 32</span></span> <span class="giallo-l"><span class="z-constant">SLOAD_FIRST_ACCESS_COST_LUT</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span class="z-constant"> 100</span><span>,</span><span class="z-constant"> 106</span><span>,</span><span class="z-constant"> 125</span><span>,</span><span class="z-constant"> 155</span><span>,</span><span class="z-constant"> 196</span><span>,</span><span class="z-constant"> 246</span><span>,</span><span class="z-constant"> 306</span><span>,</span><span class="z-constant"> 373</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 447</span><span>,</span><span class="z-constant"> 528</span><span>,</span><span class="z-constant"> 615</span><span>,</span><span class="z-constant"> 706</span><span>,</span><span class="z-constant"> 800</span><span>,</span><span class="z-constant"> 898</span><span>,</span><span class="z-constant"> 998</span><span>,</span><span class="z-constant"> 1099</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 1201</span><span>,</span><span class="z-constant"> 1302</span><span>,</span><span class="z-constant"> 1402</span><span>,</span><span class="z-constant"> 1500</span><span>,</span><span class="z-constant"> 1594</span><span>,</span><span class="z-constant"> 1685</span><span>,</span><span class="z-constant"> 1772</span><span>,</span><span class="z-constant"> 1853</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 1927</span><span>,</span><span class="z-constant"> 1994</span><span>,</span><span class="z-constant"> 2054</span><span>,</span><span class="z-constant"> 2104</span><span>,</span><span class="z-constant"> 2145</span><span>,</span><span class="z-constant"> 2175</span><span>,</span><span class="z-constant"> 2194</span><span>,</span><span class="z-constant"> 2200</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"> Account first access cost per block distance (1-32)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> WINDOW_SIZE_BLOCKS = 32</span></span> <span class="giallo-l"><span class="z-constant">ACCOUNT_FIRST_ACCESS_COST_LUT</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span class="z-constant"> 100</span><span>,</span><span class="z-constant"> 108</span><span>,</span><span class="z-constant"> 131</span><span>,</span><span class="z-constant"> 168</span><span>,</span><span class="z-constant"> 219</span><span>,</span><span class="z-constant"> 281</span><span>,</span><span class="z-constant"> 354</span><span>,</span><span class="z-constant"> 438</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 530</span><span>,</span><span class="z-constant"> 630</span><span>,</span><span class="z-constant"> 737</span><span>,</span><span class="z-constant"> 850</span><span>,</span><span class="z-constant"> 967</span><span>,</span><span class="z-constant"> 1088</span><span>,</span><span class="z-constant"> 1212</span><span>,</span><span class="z-constant"> 1337</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 1463</span><span>,</span><span class="z-constant"> 1588</span><span>,</span><span class="z-constant"> 1712</span><span>,</span><span class="z-constant"> 1833</span><span>,</span><span class="z-constant"> 1950</span><span>,</span><span class="z-constant"> 2063</span><span>,</span><span class="z-constant"> 2170</span><span>,</span><span class="z-constant"> 2270</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 2362</span><span>,</span><span class="z-constant"> 2446</span><span>,</span><span class="z-constant"> 2519</span><span>,</span><span class="z-constant"> 2581</span><span>,</span><span class="z-constant"> 2632</span><span>,</span><span class="z-constant"> 2669</span><span>,</span><span class="z-constant"> 2692</span><span>,</span><span class="z-constant"> 2700</span></span> <span class="giallo-l"><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"> sload_first_access_cost</span><span>(</span><span class="z-variable z-parameter z-function">block_distance_in_blocks</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 class="z-constant"> 1</span><span class="z-keyword"> &lt;=</span><span> block_distance_in_blocks</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 32</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> SLOAD_FIRST_ACCESS_COST_LUT</span><span>[</span><span>block_distance_in_blocks</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"> 2200</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> fully cold</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"> account_first_access_cost</span><span>(</span><span class="z-variable z-parameter z-function">block_distance_in_blocks</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 class="z-constant"> 1</span><span class="z-keyword"> &lt;=</span><span> block_distance_in_blocks</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 32</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> ACCOUNT_FIRST_ACCESS_COST_LUT</span><span>[</span><span>block_distance_in_blocks</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"> 2700</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> fully cold</span></span></code></pre><h2 id="rationale">Rationale</h2> <ul> <li>Determinism: discounts depend only on prior blocks, so users can predict costs at submission time. The block-level access lists in headers remove bootstrap ambiguity for new nodes. Intra-block dependent savings are inherently unknowable and non-actionable at submission, so they do not change behaviour; prior-block based savings do.</li> <li>Smooth curve: the chosen polynomial keeps strong incentive for very recent history and eases toward zero, aligning with how caches deliver benefit for temporal locality. Linear ramps are simpler but produce harsher edges.</li> <li>Window of 32: this captures longer-lived temporal locality without turning the feature into a long-term subsidy, and keeps proof and index sizes small.</li> <li>Discount not refund: reduces upfront charge only; does not change refund semantics or receipts.</li> <li>No correlation: simple to implement and reason about. The model is explicitly about last-access distance, not frequency.</li> </ul> <p>Builder rotation and similar operational concerns are out of scope for this EIP.</p> <h3 id="behavioural-effects">Behavioural effects</h3> <p>The smoothstep curve over 32 blocks is gentle. Discount remains close to maximum for roughly the first 12 to 16 blocks and decays toward zero near the far edge of the window.</p> <h4 id="storage-slot-sload-first-access-pricing">Storage slot (SLOAD) first-access pricing</h4> <p>(warm = 100, cold surcharge = 2100, window = 32)</p> <table><thead><tr><th><code>BLOCK_DISTANCE_IN_BLOCKS</code></th><th style="text-align: right">Discount</th><th style="text-align: right">Charge</th><th>Notes</th></tr></thead><tbody> <tr><td><code>1</code></td><td style="text-align: right"><code>2100</code></td><td style="text-align: right"><code>100</code></td><td>fully warm equivalent</td></tr> <tr><td><code>4</code></td><td style="text-align: right"><code>2045</code></td><td style="text-align: right"><code>155</code></td><td>almost full discount</td></tr> <tr><td><code>8</code></td><td style="text-align: right"><code>1827</code></td><td style="text-align: right"><code>373</code></td><td></td></tr> <tr><td><code>12</code></td><td style="text-align: right"><code>1494</code></td><td style="text-align: right"><code>706</code></td><td></td></tr> <tr><td><code>16</code></td><td style="text-align: right"><code>1101</code></td><td style="text-align: right"><code>1099</code></td><td>midpoint of window</td></tr> <tr><td><code>18</code></td><td style="text-align: right"><code>898</code></td><td style="text-align: right"><code>1302</code></td><td></td></tr> <tr><td><code>20</code></td><td style="text-align: right"><code>700</code></td><td style="text-align: right"><code>1500</code></td><td></td></tr> <tr><td><code>24</code></td><td style="text-align: right"><code>347</code></td><td style="text-align: right"><code>1853</code></td><td></td></tr> <tr><td><code>28</code></td><td style="text-align: right"><code>96</code></td><td style="text-align: right"><code>2104</code></td><td>near-cold</td></tr> <tr><td><code>32</code></td><td style="text-align: right"><code>0</code></td><td style="text-align: right"><code>2200</code></td><td>window edge</td></tr> <tr><td><code>&gt;32</code></td><td style="text-align: right"><code>0</code></td><td style="text-align: right"><code>2200</code></td><td>fully cold access</td></tr> </tbody></table> <h4 id="account-access-first-access-pricing">Account access first-access pricing</h4> <p>(warm = 100, cold surcharge = 2600, window = 32)</p> <table><thead><tr><th><code>BLOCK_DISTANCE_IN_BLOCKS</code></th><th style="text-align: right">Discount</th><th style="text-align: right">Charge</th><th>Notes</th></tr></thead><tbody> <tr><td><code>1</code></td><td style="text-align: right"><code>2600</code></td><td style="text-align: right"><code>100</code></td><td>fully warm equivalent</td></tr> <tr><td><code>4</code></td><td style="text-align: right"><code>2532</code></td><td style="text-align: right"><code>168</code></td><td>almost full discount</td></tr> <tr><td><code>8</code></td><td style="text-align: right"><code>2262</code></td><td style="text-align: right"><code>438</code></td><td></td></tr> <tr><td><code>12</code></td><td style="text-align: right"><code>1850</code></td><td style="text-align: right"><code>850</code></td><td></td></tr> <tr><td><code>16</code></td><td style="text-align: right"><code>1363</code></td><td style="text-align: right"><code>1337</code></td><td>midpoint of window</td></tr> <tr><td><code>18</code></td><td style="text-align: right"><code>1112</code></td><td style="text-align: right"><code>1588</code></td><td></td></tr> <tr><td><code>20</code></td><td style="text-align: right"><code>867</code></td><td style="text-align: right"><code>1833</code></td><td></td></tr> <tr><td><code>24</code></td><td style="text-align: right"><code>430</code></td><td style="text-align: right"><code>2270</code></td><td></td></tr> <tr><td><code>28</code></td><td style="text-align: right"><code>119</code></td><td style="text-align: right"><code>2581</code></td><td>near-cold</td></tr> <tr><td><code>32</code></td><td style="text-align: right"><code>0</code></td><td style="text-align: right"><code>2700</code></td><td>window edge</td></tr> <tr><td><code>&gt;32</code></td><td style="text-align: right"><code>0</code></td><td style="text-align: right"><code>2700</code></td><td>fully cold access</td></tr> </tbody></table> <h4 id="observations">Observations</h4> <ul> <li>Accesses 1-6 blocks apart remain effectively warm, typically under 300-400 gas total.</li> <li>Around 16 blocks (≈3.2 minutes), costs reach roughly half the cold surcharge.</li> <li>By 28-32 blocks (≈5.5-6.4 minutes, one finalisation epoch), costs are nearly cold again.</li> <li>The transition is smooth and monotone; there are no cliffs or discontinuities to game.</li> <li>Both account and storage families charge exactly the warm rate for items accessed in the immediately preceding block.</li> </ul> <p>As the discount depends only on <strong>prior blocks</strong>, users and dapps can plan around it. Unlike same-block effects, these savings are predictable: they are visible before submission and can be incorporated into automation or fee-scheduling logic.</p> <p>If an operator wants to maintain most of the discount while sending as few transactions as possible, a practical cadence for items touched repeatedly is:</p> <ul> <li>Maintain about <strong>80 percent</strong> of the maximum discount by ensuring the item is touched again within <strong>8-9 blocks</strong> (around two minutes).</li> <li>Maintain about <strong>50 percent</strong> of the maximum discount by touching again within <strong>16 blocks</strong> (half an epoch).</li> <li>Beyond roughly <strong>28 blocks</strong>, the discount fades almost entirely; by <strong>32 blocks</strong>, the access is fully cold again.</li> </ul> <p>In short, a <strong>maintenance touch every 8-12 blocks</strong> is an efficient balance: high retained discount with modest transaction frequency. Applications seeking tighter control-such as bridges, keepers, or batching relayers-can choose shorter cadences, while ordinary usage patterns will keep frequently accessed state warm naturally.</p> <p>The <strong>smooth decay curve</strong> is important. It means missing the ideal block due to a temporary spike in gas prices or unexpected congestion doesn't abruptly forfeit the entire discount-costs rise gradually, not cliff-edge. This avoids brittle strategies that depend on exact timing and makes the mechanism more forgiving in volatile network conditions.</p> <p>From a UX standpoint, humans are unlikely to act precisely within these timeframes, but automated systems can. Many popular contract surfaces-AMM reserves, token balances, or oracle feeds-stay warm simply through organic activity, letting users benefit indirectly.</p> <p>Each account or storage key's discount remains <strong>independent</strong>. Repeated touches within the window only update the item's last-access block; they do not stack or correlate across different items.</p> <h4 id="coordinated-multi-eoa-warm-up-behaviour">Coordinated multi-EOA warm-up behaviour</h4> <p>Because the temporal discount depends only on <strong>prior-block access</strong>, a coordinated actor controlling multiple EOAs or contracts can sequence transactions to capture the maximum discount. For example, a lightweight "warm-up" transaction from one EOA in block <code>N</code> can touch a set of storage keys or accounts, allowing one or more follow-up transactions in block <code>N+1</code> to execute those same accesses at <strong>warm-equivalent cost</strong>.</p> <p>This <strong>inter-block pipelining</strong> remains predictable, verifiable, and legitimate. It does not distort consensus or introduce hidden state; it simply rewards actors who cluster related work in adjacent blocks. The discount gained is bounded by the cold surcharge itself, while the overhead of coordination, additional priority fees, and builder inclusion uncertainty all limit how aggressively this pattern can be used. In practice, it is most relevant for highly automated systems-keepers, rollup bridges, or arbitrage bundles-that already coordinate sequencing across blocks.</p> <p>With the <strong>32-block window</strong>, the value of pipelining falls off much faster. Missing a single block only slightly reduces the discount because of the smooth decay curve, but missing several in a row quickly erodes it. That makes warm-ups more predictable yet self-limiting: actors can't cheaply "bank" state heat far ahead, only maintain it across a short epoch-length horizon.</p> <p>Builders and MEV searchers may still find minor advantage in chaining related operations across consecutive blocks, but this behaviour is <strong>constructive</strong>: it improves temporal locality in state access and lowers aggregate load on clients. The overall effect is a gentle nudge toward efficient state reuse, not a new coordination game.</p> <p>If desired, protocol parameters could trim the incentive surface further-for example, by setting <code>DISCOUNT_MAX_*</code> slightly below the full cold surcharge so that even <code>D = 1</code> accesses remain marginally above the intra-transaction warm price. This specification treats that as optional tuning rather than a security necessity, accepting the small and predictable incentive as a reasonable trade-off for encouraging block-to-block efficiency.</p> <h3 id="relationship-to-block-level-warming-proposals">Relationship to block-level warming proposals</h3> <p>This EIP does not introduce intra-block warming across transactions. If a block-level warming proposal is active, its semantics are unchanged. The temporal discount defined here applies only to the first access to an item in a transaction based on prior-block history.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP changes gas charging and therefore requires a hard fork. It only decreases or equalises costs for affected opcodes and does not introduce new failure modes for existing contracts. Warm and cold cost upper bounds do not increase.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li> <p><strong>Determinism and consensus safety:</strong> All discounts are derived from <em>previously committed block data</em>. No client-local or probabilistic state (like caches or heuristics) affects consensus. Any node-stateless or fully synced-can price gas deterministically using the current block and the prior <code>WINDOW_SIZE_BLOCKS</code> access-list commitments. This preserves verifiability and supports stateless validation with compact proofs referencing recent blocks only.</p> </li> <li> <p><strong>Index growth and memory bounds:</strong> Clients must maintain a rolling index of recently accessed items. With a 32-block window, memory use scales with the number of distinct first-accessed items per block-bounded by the block gas limit divided by the minimum per-item cost. This fits comfortably within existing cache budgets, and entries naturally expire as blocks advance.</p> </li> <li> <p><strong>Reorg handling:</strong> Reorgs shorter than the window are cheap to recompute: nodes rebuild the index from the new canonical access lists. Longer reorgs fall back to initial resync behaviour. No historical transaction replay is required. Because discounts depend on committed data only, there is no ambiguity or consensus divergence across reorgs.</p> </li> <li> <p><strong>Abuse and incentive surface:</strong> The design intentionally makes "warm-up" transactions unprofitable. Since the maximum discount equals the cold surcharge, warming a slot in block <em>N</em> and using it in <em>N+1</em> costs slightly <em>more</em> than a single cold access (e.g. <code>2200 + 100 &gt; 2200</code>). Thus there is no economic gain from spamming to maintain heat. The smooth decay curve further discourages exact-block timing games: adjacent blocks differ by only a handful of gas units at small distances.</p> </li> <li> <p><strong>Economic neutrality:</strong> The mechanism reduces <em>average</em> per-access cost but leaves <em>worst-case</em> costs unchanged. Builders and block producers still target the same gas limit under EIP-1559, so total basefee burn and priority-fee dynamics remain stable. The network simply fits more real execution into the same gas target, improving efficiency without altering incentives for congestion or inclusion.</p> </li> <li> <p><strong>Stateless compatibility:</strong> Earlier multi-block warming ideas were considered incompatible with stateless validation because pricing depended on uncommitted or ephemeral state. By tying discounts to BAL commitments, this proposal makes the pricing rule provable and verifiable. Stateless verifiers need only one compact proof of inclusion in a recent BAL-no historical execution replay, no private cache dependency.</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> 2025-10-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jiahui Cuihttps://github.com/doublespending 0xZPLhttps://github.com/0xZPL https://wg-eips.ritovision.com/8065/

Enables any token to be wrapped, allowing secretly burnt tokens to be reminted — making privacy a native feature of every token.

<h2 id="abstract">Abstract</h2> <p>This ERC defines a standard for the Zero Knowledge Token Wrapper, a wrapper that adds privacy to tokens — including <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> and <a href="https://wg-eips.ritovision.com/6909/">ERC-6909</a> — while preserving all of the tokens' original properties, such as transferability, tradability, and composability. It specifies <a href="https://wg-eips.ritovision.com/7503/">EIP-7503</a>-style provable burn-and-remint flows, enabling users to break on-chain traceability and making privacy a native feature of all tokens on Ethereum.</p> <h2 id="motivation">Motivation</h2> <p>Most existing tokens lack native privacy due to regulatory, technical, and issuer-side neglect. Users seeking privacy must rely on dedicated privacy blockchains or privacy-focused dApps, which restrict token usability, reduce composability, limit supported token types, impose whitelists, and constrain privacy schemes.</p> <p>This ERC takes a different approach by introducing a zero knowledge token wrapper that preserves the underlying token’s properties while adding privacy. Its primary goals are:</p> <ul> <li>Pluggable privacy: the wrapper preserves all properties of the underlying token while adding privacy.</li> <li>Permissionless privacy: any user can wrap any token into a Zero Knowledge Wrapped Token (ZWToken).</li> <li>Broad token support: compatible with both fungible tokens (e.g., ETH, ERC-20) and non-fungible tokens (e.g., ERC-721).</li> <li>EIP-7503-style privacy: supports provable burn-and-remint flows to achieve high-level privacy.</li> <li>Compatibility with multiple EIP-7503 schemes: supports different provable burn address generation methods and commitment schemes (e.g., Ethereum-native MPT state tree or contract-managed commitments).</li> </ul> <h2 id="specification">Specification</h2> <p>The key words <strong>MUST</strong>, <strong>MUST NOT</strong>, <strong>SHOULD</strong>, <strong>SHOULD NOT</strong>, and <strong>MAY</strong> in this document are to be interpreted as described in RFC 2119 and RFC 8174.</p> <h3 id="overview">Overview</h3> <p>A Zero Knowledge Wrapped Token (ZWToken) is a wrapped token minted by a Zero Knowledge Token Wrapper. It adds a commitment-based privacy layer to existing tokens, including ERC-20, ERC-721, ERC-1155, ERC-6909. This privacy layer allows private transfers without modifying the underlying token standard, while preserving full composability with existing Ethereum infrastructure.</p> <p>The commitment mechanism underlying this privacy layer may be implemented using Merkle trees, cryptographic accumulators, or any other verifiable cryptographic structure.</p> <p>A Zero Knowledge Wrapped Token (ZWToken) provides the following core functionalities:</p> <p>The ZWToken recipient can be a provable burn address, from which the tokens can later be reminted.</p> <ul> <li>Deposit: Wraps an existing token and mints ZWToken to the specified recipient.</li> <li>Transfer: Transfers ZWToken to the specified recipient.</li> <li>Remint: Mints new ZWTokens to the specified recipient after verifying a zero-knowledge proof demonstrating ownership of previously burnt tokens, without revealing the link between them.</li> <li>Withdraw: Burns ZWTokens to redeem the underlying tokens to the specified recipient.</li> </ul> <h4 id="privacy-features-by-token-type">Privacy Features by Token Type</h4> <p>For fungible tokens (FTs), e.g., ERC-20:</p> <ul> <li>This ERC enables breaking the traceability of fund flows through the burn and remint processes.</li> <li>The use of provable burn addresses hides the true holder of fungible tokens until the holder performs a withdraw operation of ZWToken.</li> </ul> <p>For non-fungible tokens (NFTs), e.g., ERC-721:</p> <ul> <li>This ERC <strong>cannot</strong> break the traceability of fund flows through burn and remint, since each NFT is unique and cannot participate in coin-mixing.</li> <li>However, the use of provable burn addresses can still conceal the true holder of the NFT until the holder performs a withdraw operation of ZWToken.</li> </ul> <h4 id="zwtoken-aware-workflow">ZWToken-aware Workflow</h4> <p>In the ZWToken-aware workflow, both the user and the system explicitly recognize and interact with ZWToken. ZWToken inherits all functional properties of the underlying token.</p> <p><img src="https://wg-eips.ritovision.com/8065/./assets/flow1.svg" alt="" /></p> <p>For example, if the underlying token is ERC-20, ZWToken can be traded on DEXs, used for swaps, liquidity provision, or standard transfers. Similar to how holding WETH provides additional benefits over holding ETH directly, users may prefer to hold ZWToken rather than the underlying token.</p> <h4 id="zwtoken-unaware-workflow">ZWToken-unaware Workflow</h4> <p>This ERC also supports a ZWToken-unaware workflow. In this mode, all transfers are internally handled through ZWToken, but users remain unaware of its existence.</p> <p><img src="https://wg-eips.ritovision.com/8065/./assets/flow2.svg" alt="" /></p> <p>ZWToken functions transparently beneath the user interface, reducing the number of required contract interactions and improving overall user experience for those who prefer not to hold ZWToken directly.</p> <h4 id="alternative-workflows">Alternative Workflows</h4> <p>The two workflows described above represent only a subset of the interaction patterns supported by this ERC. Additional workflows are also possible, including:</p> <ul> <li> <p><strong>Reminting by the recipient:</strong> Alice may <code>transfer</code> (in the ZWToken-aware workflow) or <code>deposit</code> (in the ZWToken-unaware workflow) ZWToken to <strong>Bob’s provable burn address</strong> instead of her own. In this case, the <strong>remint operation is initiated and proven by Bob rather than Alice</strong>.</p> </li> <li> <p><strong>Recursive reminting:</strong><br /> A reminted ZWToken may also be sent to <strong>another provable burn address</strong> controlled by Bob instead of his public address, allowing the privacy state to persist across multiple remint cycles.</p> </li> </ul> <p>The 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"> IERC8065</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"> struct</span><span class="z-entity z-name"> RemintData</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> commitment</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span> nullifiers</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> proverData</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> relayerData</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> redeem</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-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"> CommitmentUpdated</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">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> commitment</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"> amount</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"> Deposited</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"> amount</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"> Withdrawn</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"> amount</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"> Reminted</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"> amount</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> redeem</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"> deposit</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"> 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>;</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"> id</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"> calldata</span><span class="z-variable"> data</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"> remint</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"> 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-storage z-type"> RemintData</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>;</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"> previewDeposit</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"> 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"> 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-comment"> Optional</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> previewWithdraw</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"> 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"> 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-comment"> Optional</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> previewRemint</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-storage z-type"> RemintData</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"> 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"> getLatestCommitment</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">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"> hasCommitment</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> commitment</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"> Optional</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getCommitLeafCount</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 class="z-comment"> Optional</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getCommitLeaves</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"> startIndex</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> length</span><span>)</span></span> <span class="giallo-l"><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 class="z-variable"> commitHashes</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"> recipients</span><span>,</span><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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getUnderlying</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="deposit-wrap">Deposit / Wrap</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Deposits a specified amount of the underlying asset and mints the corresponding amount of ZWToken to the given address.</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"> If the underlying asset is an ERC-20/ERC-721/ERC-1155/ERC-6909 token, the caller must approve this contract to transfer the specified `amount` beforehand.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> If the underlying asset is ETH, the caller should send the deposit value along with the transaction (`msg.value`), and `msg.value` MUST be equal to `amount`.</span></span> <span 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 ZWTokens.</span></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 identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set 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"> amount</span><span class="z-comment"> The amount of the underlying asset to deposit.</span></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 for extensibility, such as fee information, callback data, or metadata.</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"> 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"> 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>;</span></span></code></pre> <ul> <li> <p>Depositor SHOULD be <code>msg.sender</code>.</p> </li> <li> <p>The function MUST transfer the specified <code>amount</code> of the underlying asset from <code>depositor</code> to the ZWToken contract.</p> <ul> <li>If the underlying asset is an ERC-20, ERC-721, ERC-1155 or ERC-6909 token, the caller MUST approve this contract to transfer the specified <code>amount</code> beforehand.</li> <li>If the underlying asset is ETH, the caller MUST send the deposit value along with the transaction (<code>msg.value</code>), and <code>msg.value</code> MUST be equal to <code>amount</code>.</li> </ul> </li> <li> <p>The function SHOULD mint ZWToken to the recipient <code>to</code>. The amount minted MAY be reduced by fees as defined by the implementation.</p> </li> <li> <p>Commitment Update:</p> <ul> <li>For contract-level commitment schemes, since to may be a provable burn address, the implementation SHOULD update the corresponding commitment. <ul> <li>However, this MAY be optimized: if <code>to</code> == <code>depositor</code>, the implementation MAY skip updating the commitment, as <code>depositor</code> cannot be a provable burn address (otherwise the transaction could not be initiated).</li> </ul> </li> <li>For protocol-level commitment schemes (e.g., Ethereum’s native Merkle Patricia Trie), the commitment (e.g., state root or block hash) is automatically updated by the protocol.</li> </ul> </li> <li> <p>The function MUST emit a <code>Deposited(depositor, to, id, amount)</code> event upon successful deposit.</p> <ul> <li>The <code>amount</code> parameter in the <code>Deposited</code> event represents the net amount of ZWToken received by <code>to</code> after deducting applicable fees, rather than the amount of underlying tokens deposited.</li> </ul> </li> <li> <p>The <code>data</code> parameter is reserved for future extensibility and MAY be used to pass additional information such as fee configurations, callback data, or metadata. Implementations MAY ignore this parameter if not needed.</p> </li> </ul> <h3 id="withdraw-unwrap">Withdraw / Unwrap</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Withdraw underlying tokens by burning ZWToken</span></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 recipient address that will receive the underlying 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"> id</span><span class="z-comment"> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> <span 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"> The amount of ZWToken to burn and redeem for the underlying 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"> data</span><span class="z-comment"> Additional data for extensibility, such as fee information, callback data, or metadata.</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"> id</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"> calldata</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <ul> <li>Withdrawer SHOULD be <code>msg.sender</code>.</li> <li>The function MUST burn the specified <code>amount</code> of ZWToken from withdrawer.</li> <li>The function SHOULD transfer underlying token to the recipient <code>to</code>. The amount transferred MAY be reduced by fees as defined by the implementation.</li> <li>The function MUST emit a <code>Withdrawn(withdrawer, to, id, amount)</code> event upon successful withdrawal. <ul> <li>The <code>amount</code> parameter in the <code>Withdrawn</code> event represents the net amount of underlying tokens received by <code>to</code> after deducting applicable fees, rather than the amount of ZWToken burned.</li> </ul> </li> <li>The <code>data</code> parameter is reserved for future extensibility and MAY be used to pass additional information such as fee configurations, callback data, or metadata. Implementations MAY ignore this parameter if not needed.</li> </ul> <h3 id="transfer-and-update-commitment">Transfer and Update Commitment</h3> <ul> <li>The Zero Knowledge Wrapped Token (ZWToken) remains fully compatible with the underlying token’s transfer interface, while extending it to support privacy-preserving operations. <ul> <li>When a ZWToken is transferred to a provable burn address, those tokens MUST be eligible for reminting through the remint interface, effectively breaking the traceability of the fund flow.</li> <li>A provable burn address MAY take various forms (e.g., as defined in EIP-7503). Its essential properties are: <ul> <li>Such addresses MUST NOT be operable by any user and MUST be provably non-correspondent to any externally owned account (EOA) or smart contract.</li> <li>Only the entity that generates the burn address MAY derive it, for example, through a signature-derived or deterministic generation scheme.</li> </ul> </li> </ul> </li> <li>Commitment Update: <ul> <li>For commitment schemes maintained at the contract level: <ul> <li>If the recipient is identified as a provable burn address, the contract MUST update the commitment. <ul> <li>Example — a recipient that has previously sent any ZWToken MUST NOT be a provable burn address, since such addresses are incapable of initiating outgoing transfers. In this case, commitment update is not required.</li> </ul> </li> </ul> </li> <li>For protocol-level commitment schemes (e.g., Ethereum’s native MPT tree), the contract does not need to manage any commitment state, since the protocol layer already provides verifiable commitment structures.</li> </ul> </li> </ul> <h3 id="remint">Remint</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Encapsulates all data required for remint operations</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> commitment</span><span class="z-comment"> The commitment (Merkle root) corresponding to the provided 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"> nullifiers</span><span class="z-comment"> Array of unique nullifiers used to prevent double-remint</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> proverData</span><span class="z-comment"> Generic data for the prover. The meaning and encoding are implementation-specific (e.g., a circuit identifier/version).</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> relayerData</span><span class="z-comment"> Generic data for the relayer. The meaning and encoding are implementation-specific (e.g., fee information).</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> redeem</span><span class="z-comment"> If true, withdraws the equivalent underlying token instead of reminting ZWToken</span></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"> Zero-knowledge proof bytes verifying ownership of the provable burn address</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> RemintData</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> commitment</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span> nullifiers</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> proverData</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> relayerData</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> redeem</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-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Remint ZWToken using a zero-knowledge proof to unlink the source of 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"> to</span><span class="z-comment"> Recipient address that will receive the reminted ZWToken or the underlying 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"> id</span><span class="z-comment"> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> <span 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 ZWToken burned from the provable burn address for reminting</span></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"> Encapsulated remint data including commitment, nullifiers, redeem flag, proof, and relayer information</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> remint</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"> 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-storage z-type"> RemintData</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>;</span></span></code></pre> <ul> <li> <p>The function MUST verify the zero-knowledge proof proof against the provided commitment to ensure:</p> <ul> <li>Ownership of the provable burn address.</li> <li>Correctness parameters of <code>remint</code>, i.e., the zk proof public inputs.<pre class="giallo z-code"><code data-lang="solidity"><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> id</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> RemintData </span><span class="z-storage z-type">calldata</span><span> data </span><span class="z-comment">//</span><span class="z-comment"> All fields except data.proof are used as public inputs for zk proof verification</span></span></code></pre></li> </ul> </li> <li> <p>Reminter SHOULD be <code>msg.sender</code>.</p> </li> <li> <p>The function MUST validate the input <code>data.commitment</code> to ensure it exists.</p> </li> <li> <p>The function MUST ensure that none of the <code>data.nullifiers</code> have been used previously. Reuse of any nullifier MUST revert the transaction.</p> <ul> <li>This supports batch reminting in a single proof by allowing multiple nullifiers to be provided and consumed atomically.</li> </ul> </li> <li> <p>Upon successful verification:</p> <ul> <li>If <code>data.redeem</code> is false, the function MUST mint ZWToken to the recipient <code>to</code>. The amount minted MAY be reduced by fees as defined by the implementation. <ul> <li>In this case, the function MUST emit the <code>Reminted</code> event after a successful remint of ZWToken.</li> </ul> </li> <li>If <code>data.redeem</code> is true, the function MUST transfer underlying token to the recipient <code>to</code>. The amount transferred MAY be reduced by fees as defined by the implementation. <ul> <li>In this case, the function MUST emit the <code>Reminted</code> event after a successful withdrawal of the underlying token.</li> </ul> </li> <li>The net tokens received by the recipient <code>to</code> MAY be reduced by relayer fees if the relayer charges a fee (as specified in <code>data.relayerData</code>).</li> <li>The function MUST mark <strong>each</strong> nullifier in <code>data.nullifiers</code> as spent to prevent double-spending.</li> </ul> </li> <li> <p>The function MUST emit a <code>Reminted(reminter, to, id, amount, data.redeem)</code> event upon successful remint.</p> <ul> <li>The <code>amount</code> parameter in the <code>Reminted</code> event represents the net amount of underlying tokens or ZWToken received by <code>to</code> after all applicable fees have been deducted.</li> </ul> </li> </ul> <h3 id="preview-functions-optional">Preview Functions (Optional)</h3> <p>Since the actual token amounts received may differ from the input amounts due to implementation-specific factors (e.g., fees), users need a standardized way to determine the exact amounts they will receive. Following the design pattern established by <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a>, the preview functions allow users to simulate the effects of their operations at the current block, returning values as close to and no more than the exact amounts that would result from the corresponding mutable operations if called in the same transaction.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> OPTIONAL: Allows an on-chain or off-chain user to simulate the effects of their deposit at the current block.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST return as close to and no more than the exact amount of ZWToken that would be minted in a `deposit` call in the same transaction.</span></span> <span 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 ZWTokens.</span></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 identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set 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"> amount</span><span class="z-comment"> The amount of underlying tokens to deposit.</span></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 for extensibility, such as fee 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"> The</span><span class="z-comment"> amount of ZWToken that would be minted to the recipient after deducting applicable fees.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> previewDeposit</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"> 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"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span></code></pre> <ul> <li><code>previewDeposit(address to, uint256 id, uint256 amount, bytes calldata data)</code>: OPTIONAL. Returns the exact amount of ZWToken that would be minted for the specified amount of underlying tokens. <ul> <li>MUST be inclusive of deposit fees. Integrators SHOULD be aware of the existence of deposit fees.</li> <li>MUST NOT revert due to implementation-specific user/global limits.</li> <li>MAY revert due to other conditions that would also cause <code>deposit</code> to revert.</li> </ul> </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"> @notice</span><span class="z-comment"> OPTIONAL: Allows an on-chain or off-chain user to simulate the effects of their withdrawal at the current block.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST return as close to and no more than the exact amount of underlying tokens that would be received in a `withdraw` call in the same transaction.</span></span> <span 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 recipient address that will receive the underlying 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"> id</span><span class="z-comment"> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> <span 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"> The amount of ZWToken to burn.</span></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 for extensibility, such as fee 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"> The</span><span class="z-comment"> amount of underlying tokens that would be received by the recipient after deducting applicable fees.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> previewWithdraw</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"> 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"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span></code></pre> <ul> <li><code>previewWithdraw(address to, uint256 id, uint256 amount, bytes calldata data)</code>: OPTIONAL. Returns the exact amount of underlying tokens that would be received for burning the specified amount of ZWToken. <ul> <li>MUST be inclusive of withdrawal fees. Integrators SHOULD be aware of the existence of withdrawal fees.</li> <li>MUST NOT revert due to implementation-specific user/global limits.</li> <li>MAY revert due to other conditions that would also cause <code>withdraw</code> to revert.</li> </ul> </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"> @notice</span><span class="z-comment"> OPTIONAL: Allows an on-chain or off-chain user to simulate the effects of their remint at the current block.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST return as close to and no more than the exact amount of ZWToken or underlying tokens that would be received in a `remint` call in the same transaction.</span></span> <span 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"> Recipient address that will receive the reminted ZWToken or the underlying 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"> id</span><span class="z-comment"> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> <span 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"> The amount of ZWToken burned from the provable burn address for reminting.</span></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"> Encapsulated remint data including commitment, nullifiers, redeem flag, proof, and relayer 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"> The</span><span class="z-comment"> amount of ZWToken or underlying tokens that would be received by the recipient after all applicable fees have been deducted.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> previewRemint</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-storage z-type"> RemintData</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"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span></code></pre> <ul> <li><code>previewRemint(address to, uint256 id, uint256 amount, RemintData calldata data)</code>: OPTIONAL. Returns the exact amount of ZWToken (or underlying tokens if <code>data.redeem</code> is true) that would be received for a remint operation. <ul> <li>MUST be inclusive of all applicable fees, including remint fees and relayer fees (as specified in <code>data.relayerData</code>).</li> <li>MUST NOT revert due to implementation-specific user/global limits.</li> <li>MAY revert due to other conditions that would also cause <code>remint</code> to revert.</li> </ul> </li> </ul> <h3 id="query-interfaces">Query Interfaces</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the current top-level commitment representing the privacy state</span></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 identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</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"> latest root hash of the commitment tree</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getLatestCommitment</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">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"> Checks if a specific top-level commitment 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"> id</span><span class="z-comment"> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> commitment</span><span class="z-comment"> The root hash to verify</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 commitment exists, false otherwise</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> hasCommitment</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> commitment</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"> OPTIONAL: Returns the total number of commitment leaves stored</span></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 identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</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"> total count of commitment leaves</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getCommitLeafCount</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 class="z-storage z-type"> @notice</span><span class="z-comment"> OPTIONAL: Retrieves leaf-level commit data and their hashes</span></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 identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set 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"> startIndex</span><span class="z-comment"> Index of the first leaf to fetch</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> length</span><span class="z-comment"> Number of leaves to fetch</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"> commitHashes</span><span class="z-comment"> Hashes of the leaf data</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"> recipients</span><span class="z-comment"> Recipient addresses of each leaf</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"> amounts</span><span class="z-comment"> Token amounts of each leaf</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getCommitLeaves</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"> startIndex</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> length</span><span>)</span></span> <span class="giallo-l"><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 class="z-variable"> commitHashes</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"> recipients</span><span>,</span><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></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 address of the underlying token wrapped by this ZWToken</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"> underlying token contract address, or address(0) if the underlying asset is ETH.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getUnderlying</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></code></pre> <ul> <li> <p><code>getLatestCommitment(uint256 id)</code>: MUST return the most recent top-level commitment associated with the specified token identifier, representing the current state of the ZWToken system.</p> <ul> <li>For protocol-level commitments, the block number can be used as the commitment, as it can directly map to the block hash.</li> </ul> </li> <li> <p><code>hasCommitment(uint256 id, bytes32 commitment)</code>: MUST check whether a specific top-level commitment associated with the specified token identifier exists in the contract.</p> <ul> <li>For proving ownership of a provable burn address, it does not require the latest commitment.</li> <li>For protocol-level commitments, the block number can be used as the commitment, as it can directly map to the block hash.</li> </ul> </li> <li> <p><code>getCommitLeafCount(uint256 id)</code>: OPTIONAL. Returns the total number of leaf-level commitments, which helps <code>getCommitLeaves</code> retrieve the leaves. The returned value also represents the current size of the privacy pool.</p> </li> <li> <p><code>getCommitLeaves(uint256 id, uint256 startIndex, uint256 length)</code>: OPTIONAL. Retrieves leaf-level commitment data from the commitment tree associated with the specified token identifier.</p> <ul> <li>On-chain storage of commit data can be used to improve privacy and decentralization but will incur higher gas costs.</li> <li>Event-based reconstruction can be used as an alternative, though it introduces potential centralization risks.</li> </ul> </li> <li> <p><code>getUnderlying()</code>: MUST return the address of the underlying token that this ZWToken wraps.</p> <ul> <li>If the underlying asset is ETH, MUST return <code>address(0)</code>.</li> </ul> </li> </ul> <h3 id="erc-165-support"><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> Support</h3> <ul> <li>Implementations of this ERC MUST implement ERC-165 interface detection.</li> <li><code>supportsInterface(bytes4)</code> MUST return <code>true</code> for <code>type(IERC8065).interfaceId</code> (in addition to any other supported interfaces), allowing other contracts to reliably detect whether a token is a ZWToken wrapper.</li> </ul> <h3 id="events">Events</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Optional: Emitted when a contract-maintained commitment is updated</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> OPTIONAL event emitted when a commitment is updated 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"> id</span><span class="z-comment"> The token identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set to `0`.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> commitment</span><span class="z-comment"> The new top-level commitment hash</span></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 recipient address associated with the commitment</span></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"> The amount related to this commitment update</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> CommitmentUpdated</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">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> commitment</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"> 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"> @notice</span><span class="z-comment"> Emitted when underlying tokens are deposited and ZWToken is minted to the 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"> from</span><span class="z-comment"> The address sending the underlying 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 receiving the minted ZWToken (after fees)</span></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 identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set 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"> amount</span><span class="z-comment"> The net amount of ZWToken minted to `to` after deducting applicable fees</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Deposited</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"> 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"> @notice</span><span class="z-comment"> Emitted when ZWToken is burned to redeem underlying tokens to the 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"> from</span><span class="z-comment"> The address burning the ZWToken</span></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 receiving the redeemed underlying tokens (after fees)</span></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 identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set 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"> amount</span><span class="z-comment"> The net amount of underlying tokens received by `to` after deducting applicable fees</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Withdrawn</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"> 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"> @notice</span><span class="z-comment"> Emitted upon successful reminting of ZWToken or withdrawal of underlying tokens via a zero-knowledge 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"> from</span><span class="z-comment"> The address initiating the remint 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"> to</span><span class="z-comment"> The address receiving the reminted ZWToken or withdrawn underlying tokens (after fees)</span></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 identifier. For fungible tokens that do not have `id`, such as ERC-20, this value MUST be set 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"> amount</span><span class="z-comment"> The net amount of ZWToken or underlying tokens received by `to` after all applicable fees have been deducted</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> redeem</span><span class="z-comment"> If true, withdraws the equivalent underlying tokens instead of reminting ZWToken</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Reminted</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"> amount</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> redeem</span><span>)</span><span>;</span></span></code></pre> <ul> <li> <p><code>CommitmentUpdated(uint256 indexed id, bytes32 indexed commitment, address indexed to, uint256 amount)</code> is OPTIONAL and may be emitted when a contract-maintained commitment is updated, such as when ZWToken is sent to a potential provable burn address. It allows users to reconstruct commitments and generate zero-knowledge proofs, where <code>id</code> is the token identifier, <code>commitment</code> is the new commitment, <code>to</code> is the recipient, and <code>amount</code> is the committed token amount.</p> </li> <li> <p><code>Deposited(address indexed from, address indexed to, uint256 indexed id, uint256 amount)</code> signals that underlying tokens have been deposited and ZWToken minted to the recipient, where <code>from</code> is the sender, <code>to</code> is the recipient, <code>id</code> is the token identifier and <code>amount</code> is the net amount of ZWToken minted to <code>to</code> after deducting applicable fees.</p> </li> <li> <p><code>Withdrawn(address indexed from, address indexed to, uint256 indexed id, uint256 amount)</code> signals that ZWToken has been burned to redeem underlying tokens to the recipient, where <code>from</code> is the burner, <code>to</code> is the receiver, <code>id</code> is the token identifier and <code>amount</code> is the net amount of underlying tokens received by <code>to</code> after deducting applicable fees.</p> </li> <li> <p><code>Reminted(address indexed from, address indexed to, uint256 indexed id, uint256 amount, bool redeem)</code> MUST be emitted upon successful reminting of ZWToken or withdrawal of underlying tokens via a zero-knowledge proof, where <code>from</code> is the reminter, <code>to</code> is the recipient, <code>id</code> is the token identifier and <code>amount</code> is the net amount of ZWToken or underlying tokens received by <code>to</code> after all applicable fees have been deducted.</p> </li> </ul> <h2 id="rationale">Rationale</h2> <ul> <li> <p>Permissionless Wrapping: Launching a new zk-native token is unlikely to achieve sufficient liquidity or adoption, and major token issuers are unlikely to deploy zk variants due to regulatory and operational constraints. A permissionless wrapper makes privacy a native feature for existing tokens. ZWToken does not require issuer consent—any existing token can be wrapped, ensuring openness and equal accessibility regardless of issuer policies.</p> </li> <li> <p>Composable Privacy: Wrapped tokens remain fully compatible with their underlying token standards, preserving interoperability across the Ethereum ecosystem. Users and dApps can treat ZWToken as the underlying token when privacy is not required, making privacy an optional and composable extension rather than a separate system.</p> </li> <li> <p>Awareness of ZWToken: This ERC supports both ZWToken-aware and ZWToken-unaware workflows, each with distinct advantages. In the ZWToken-aware workflow, ZWToken inherits all functional properties of the underlying token and can interact seamlessly with existing DeFi protocols. In the ZWToken-unaware workflow, ZWToken operates transparently beneath the user interface, reducing the number of required contract interactions and improving user experience for those who prefer not to hold ZWToken directly.</p> </li> <li> <p>Multiple Token Standard Support: This ERC only depends on the transferability of the underlying token, enabling broad compatibility with token standards such as ERC-20, ERC-721, ERC-1155, and ERC-6909. Non-transferable tokens (e.g., Soulbound Tokens, SBTs) are out of scope. Implementations may require extra care for:</p> <ul> <li>Fee-on-transfer tokens.</li> <li>Rebasing tokens (consider wrapping an existing non-rebasing wrapper to avoid rebase-handling complexity).</li> </ul> </li> <li> <p>Fee Mechanisms: Fee structures are implementation-specific and not defined by this ERC. Implementations MAY apply fees during deposit, remint, or withdraw phases, and MAY support various fee models (e.g., fixed fees, percentage-based fees, or no fees).</p> </li> <li> <p>Relayer-Enabled Remint: This ERC supports relayer functionality, allowing third parties to submit remint transactions on behalf of users while receiving a fee. This design mitigates privacy leakage caused by revealing the original sender's address when paying gas fees.</p> </li> <li> <p>Data Extensibility:</p> <ul> <li>The meaning and encoding of <code>proverData</code> and <code>relayerData</code> are implementation-specific.</li> <li>Implementations MAY encode prover-specific metadata in <code>data.proverData</code> (e.g., a circuit identifier/version, a proving key identifier, or packed auxiliary public inputs).</li> <li>Implementations MAY encode relayer-specific metadata in <code>data.relayerData</code> (e.g., fee information, a fee token, or other fee model parameters).</li> <li>A single universal encoding is impractical because proving schemes and relayer compensation models can vary significantly.</li> <li>If cross-implementation interoperability is desired, a separate ERC (or profile) SHOULD standardize encoding(s) for <code>proverData</code> and/or <code>relayerData</code>.</li> </ul> </li> <li> <p>Commitment Generalization: The ERC adopts a generic commitment abstraction, supporting various schemes such as Merkle trees or other verifiable cryptographic accumulators. This flexibility enables developers to adapt the standard to different privacy or scalability trade-offs.</p> </li> <li> <p>Proof System Generalization: Proofs are passed as bytes calldata, allowing the use of SNARKs, STARKs, or any other zero-knowledge proof system, ensuring future-proof interoperability across cryptographic frameworks.</p> </li> <li> <p>Provable Burn Address Generalization: This ERC does not prescribe a specific method for generating Provable Burn Addresses, as long as the following conditions are met. One example is adopting zk-friendly hash functions such as Poseidon to replace keccak256 in the address generation algorithm.</p> <ul> <li>Such addresses MUST NOT be operable by any user and MUST be provably non-correspondent to any externally owned account (EOA) or smart contract.</li> <li>Only the entity that generates the burn address MAY derive it, for example through a signature-derived or deterministic generation scheme.</li> </ul> </li> <li> <p>Dual Commitment Options: The ERC supports both contract-maintained commitments and protocol-level commitments (using blockhash as the commitment).</p> <ul> <li>Contract-maintained commitments reduce proof complexity, allowing smaller ZK circuits and enabling proof generation directly in browsers or mobile devices, at the cost of higher gas consumption during transfers.</li> <li>Using blockhash as the commitment eliminates on-chain maintenance overhead but increases the complexity of off-chain proof generation.</li> </ul> </li> <li> <p>Preview Functions: Following the design pattern established by <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a>, this ERC includes optional preview functions (<code>previewDeposit</code>, <code>previewWithdraw</code>, <code>previewRemint</code>) that simulate the exact outcomes of their corresponding mutable operations.</p> <ul> <li>Since the actual token amounts received may differ from the input amounts due to implementation-specific factors (e.g., fees), users and integrators need a standardized way to determine the exact amounts.</li> <li>These functions provide a standardized interface for querying the net token amounts, enabling accurate UX displays and informed decision-making before executing transactions.</li> <li>Each preview function mirrors the parameters of its corresponding mutable operation to ensure accurate calculations that may depend on any of these parameters.</li> </ul> </li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC introduces no breaking changes. It extends the functionality of the underlying token without modifying or overriding its base interfaces.</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 class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.20</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">ERC20</span><span>}</span><span class="z-keyword"> from</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> {</span><span class="z-entity z-name">IERC20</span><span>}</span><span class="z-keyword"> from</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> {</span><span class="z-entity z-name">SafeERC20</span><span>}</span><span class="z-keyword"> from</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> {</span><span class="z-entity z-name">ERC165</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/introspection/ERC165.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IERC165</span><span>}</span><span class="z-keyword"> from</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"> IVerifier</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyProof</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"> proof</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"> input</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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ZWToken</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC8065</span><span>, </span><span class="z-entity z-name">ERC20</span><span>, </span><span class="z-entity z-name">ERC165</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> IERC20 </span><span class="z-storage z-type">public</span><span class="z-storage z-type"> immutable</span><span> underlying</span><span>;</span></span> <span class="giallo-l"><span> IVerifier </span><span class="z-storage z-type">public</span><span class="z-storage z-type"> immutable</span><span> verifier</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-support"> bool</span><span>)</span><span class="z-storage z-type"> public</span><span> usedNullifier</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"> Deposited</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"> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Withdrawn</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"> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Reminted</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"> amount</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> redeem</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> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> name_</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"> symbol_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> underlying_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> verifier_</span></span> <span class="giallo-l"><span> )</span><span class="z-entity z-name"> ERC20</span><span>(</span><span>name_, symbol_) </span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>underlying_ </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;Invalid underlying&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>verifier_ </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;Invalid verifier&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> underlying </span><span class="z-keyword">=</span><span class="z-entity z-name"> IERC20</span><span>(</span><span>underlying_</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> verifier </span><span class="z-keyword">=</span><span class="z-entity z-name"> IVerifier</span><span>(</span><span>verifier_</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"> deposit</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"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-comment"> /*</span><span class="z-comment">data</span><span class="z-comment">*/</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</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>amount </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;amount must &gt; 0&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>id </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;id must be 0 for ERC20&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> underlying</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> amount</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> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Deposited</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> to</span><span>,</span><span> id</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-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"> id</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"> calldata</span><span class="z-comment"> /*</span><span class="z-comment">data</span><span class="z-comment">*/</span><span>)</span><span class="z-storage z-type"> external</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>amount </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;amount must &gt; 0&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>id </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;id must be 0 for ERC20&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _burn</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> underlying</span><span>.</span><span class="z-entity z-name">safeTransfer</span><span>(</span><span>to</span><span>,</span><span> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Withdrawn</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> to</span><span>,</span><span> id</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-storage z-type"> function</span><span class="z-entity z-name"> remint</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"> 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-storage z-type"> IERC8065</span><span>.</span><span class="z-support z-variable">RemintData</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> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>id </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;id must be 0 for ERC20&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-keyword"> NOTE</span><span class="z-comment">: This reference implementation uses a verifier circuit that consumes a single nullifier as a public input.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The ERC-8065 specification allows `data.nullifiers` to contain multiple nullifiers so implementations can</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> support batch reminting (consuming multiple nullifiers atomically within one proof).</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>data</span><span>.</span><span>nullifiers</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 1</span><span>,</span><span class="z-string"> &quot;Only single nullifier supported&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> nullifier </span><span class="z-keyword">=</span><span> data</span><span>.</span><span>nullifiers</span><span>[</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 class="z-keyword">!</span><span>usedNullifier</span><span>[</span><span>nullifier</span><span>]</span><span>,</span><span class="z-string"> &quot;nullifier used&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> headerHash </span><span class="z-keyword">=</span><span class="z-variable z-language"> blockhash</span><span>(</span><span class="z-support">uint256</span><span>(</span><span>data</span><span>.</span><span>commitment</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>headerHash </span><span class="z-keyword">!=</span><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-string"> &quot;commitment not found&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"> Example encoding (implementation-specific):</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> if relayerData.length &gt;= 32, first 32 bytes are interpreted as relayerFee (uint256)</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> relayerFee </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>data</span><span>.</span><span>relayerData</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-constant"> 32</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> relayerFee </span><span class="z-keyword">:=</span><span class="z-entity z-name"> calldataload</span><span>(</span><span>data</span><span>.</span><span>relayerData</span><span>.</span><span>offset</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"> Replay protection by chain id and contract address is handled externally––</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> they MUST be included as parameters when generating the provable burn address and proof.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> (For example, the Poseidon hash that defines the burn address should incorporate these values.)</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> No contract-side enforcement is implemented here.</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> input </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> uint256</span><span>[](</span><span class="z-constant">7</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> input</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> =</span><span class="z-support"> uint256</span><span>(</span><span>headerHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> input</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> =</span><span class="z-support"> uint256</span><span>(</span><span>nullifier</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> input</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-keyword"> =</span><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint160</span><span>(</span><span>to</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> input</span><span>[</span><span class="z-constant">3</span><span>]</span><span class="z-keyword"> =</span><span class="z-support"> uint256</span><span>(</span><span>id</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> input</span><span>[</span><span class="z-constant">4</span><span>]</span><span class="z-keyword"> =</span><span class="z-support"> uint256</span><span>(</span><span>amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> input</span><span>[</span><span class="z-constant">5</span><span>]</span><span class="z-keyword"> =</span><span class="z-support"> uint256</span><span>(</span><span>data</span><span>.</span><span>redeem </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> <span class="giallo-l"><span> input</span><span>[</span><span class="z-constant">6</span><span>]</span><span class="z-keyword"> =</span><span class="z-support"> uint256</span><span>(</span><span>relayerFee</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>verifier</span><span>.</span><span class="z-entity z-name">verifyProof</span><span>(</span><span>data</span><span>.</span><span>proof</span><span>,</span><span> input</span><span>)</span><span>,</span><span class="z-string"> &quot;bad proof&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> usedNullifier</span><span>[</span><span>nullifier</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"> Fee handling is implementation-specific</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> This example implementation applies only relayer fees (parsed from relayerData above)</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> In this example, relayerFee is interpreted as a percentage with denominator 10000</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> remain </span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>relayerFee </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-support"> uint256</span><span> feeDenominator </span><span class="z-keyword">=</span><span class="z-constant"> 10000</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>relayerFee </span><span class="z-keyword">&lt;</span><span> feeDenominator</span><span>,</span><span class="z-string"> &quot;invalid relayer fee&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> remain </span><span class="z-keyword">=</span><span> amount </span><span class="z-keyword">-</span><span> amount </span><span class="z-keyword">*</span><span> relayerFee </span><span class="z-keyword">/</span><span> feeDenominator</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>remain </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;invalid remain&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-keyword"> if</span><span> (</span><span>data</span><span>.</span><span>redeem</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> underlying</span><span>.</span><span class="z-entity z-name">safeTransfer</span><span>(</span><span>to</span><span>,</span><span> remain</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>relayerFee </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> underlying</span><span>.</span><span class="z-entity z-name">safeTransfer</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> amount </span><span class="z-keyword">-</span><span> remain</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-entity z-name"> _mint</span><span>(</span><span>to</span><span>,</span><span> remain</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>relayerFee </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"> _mint</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> amount </span><span class="z-keyword">-</span><span> remain</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"> emit</span><span class="z-entity z-name"> Reminted</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> to</span><span>,</span><span> id</span><span>,</span><span> remain</span><span>,</span><span> data</span><span>.</span><span>redeem</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"> getLatestCommitment</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-storage z-type"> override</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>id </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;id must be 0 for ERC20&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> bytes32</span><span>(</span><span class="z-variable z-language">block</span><span>.</span><span>number</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"> hasCommitment</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> commitment</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"> 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>id </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;id must be 0 for ERC20&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> headerHash </span><span class="z-keyword">=</span><span class="z-variable z-language"> blockhash</span><span>(</span><span class="z-support">uint256</span><span>(</span><span>commitment</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> headerHash </span><span class="z-keyword">!=</span><span class="z-support"> bytes32</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"> getUnderlying</span><span>(</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"> 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"> return</span><span class="z-support"> address</span><span>(</span><span>underlying</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"> Optional preview functions</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> previewDeposit</span><span>(</span><span class="z-support">address</span><span class="z-comment"> /*</span><span class="z-comment">to</span><span class="z-comment">*/</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"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-comment"> /*</span><span class="z-comment">data</span><span class="z-comment">*/</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"> require</span><span>(</span><span>id </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;id must be 0 for ERC20&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> This example implementation has no deposit fees, so the output equals the input.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Implementations with fees SHOULD deduct them here.</span></span> <span class="giallo-l"><span class="z-keyword"> return</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"> previewWithdraw</span><span>(</span><span class="z-support">address</span><span class="z-comment"> /*</span><span class="z-comment">to</span><span class="z-comment">*/</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"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-comment"> /*</span><span class="z-comment">data</span><span class="z-comment">*/</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"> require</span><span>(</span><span>id </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;id must be 0 for ERC20&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> This example implementation has no withdrawal fees, so the output equals the input.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Implementations with fees SHOULD deduct them here.</span></span> <span class="giallo-l"><span class="z-keyword"> return</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"> previewRemint</span><span>(</span><span class="z-support">address</span><span class="z-comment"> /*</span><span class="z-comment">to</span><span class="z-comment">*/</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-storage z-type"> IERC8065</span><span>.</span><span class="z-support z-variable">RemintData</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"> 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"> require</span><span>(</span><span>id </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;id must be 0 for ERC20&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Example encoding (implementation-specific):</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Parse relayerFee from relayerData (if provided)</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> relayerFee </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>data</span><span>.</span><span>relayerData</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-constant"> 32</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> relayerFee </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>data</span><span>.</span><span>relayerData</span><span>[</span><span class="z-keyword">:</span><span class="z-constant">32</span><span>]</span><span>,</span><span> (</span><span class="z-support">uint256</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"> Apply relayer fee (percentage with denominator 10000)</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> remain </span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>relayerFee </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-support"> uint256</span><span> feeDenominator </span><span class="z-keyword">=</span><span class="z-constant"> 10000</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>relayerFee </span><span class="z-keyword">&lt;</span><span> feeDenominator</span><span>,</span><span class="z-string"> &quot;invalid relayer fee&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> remain </span><span class="z-keyword">=</span><span> amount </span><span class="z-keyword">-</span><span> amount </span><span class="z-keyword">*</span><span> relayerFee </span><span class="z-keyword">/</span><span> feeDenominator</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> remain</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><span class="z-entity z-name">ERC165</span><span>,</span><span class="z-entity z-name"> IERC165</span><span>)</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> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC8065</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> <ul> <li> <p>Double-Remint Prevention: Each remint operation MUST include one or more unique nullifiers (<code>data.nullifiers</code>) to prevent double-remint attacks.</p> <ul> <li>Reusing any nullifier MUST revert.</li> <li>On success, all provided nullifiers MUST be marked as spent.</li> </ul> </li> <li> <p>Over-Minting Protection: The total supply of ZWToken MAY temporarily exceed the supply of the underlying token. However, the surplus represents provably burnt tokens, which are permanently removed from circulation and cannot be redeemed.</p> </li> <li> <p>Local Proof Generation: Circuits SHOULD remain as small and efficient as possible to enable users to generate zero-knowledge proofs locally (e.g., within browsers or mobile devices). This minimizes reliance on third-party provers that may introduce privacy leakage risks.</p> </li> <li> <p>Provable Burn Address Security: Provable burn addresses MAY follow different generation schemes (e.g., as proposed in EIP-7503). The essential properties are:</p> <ul> <li>These addresses MUST be non-operable and provably non-correspondent to any externally owned account (EOA) or smart contract.</li> <li>Only the generator of the burn address MAY deterministically derive it, for instance, through a signature-derived scheme.</li> <li>Implementations SHOULD prefer zk-friendly hash functions (e.g., Poseidon) in place of keccak256 to improve proof efficiency and reduce circuit size.</li> </ul> </li> <li> <p>Burn and Remint Process Privacy:</p> <ul> <li>Burn amounts SHOULD appear indistinguishable from ordinary transfers to prevent correlation with remint amounts.</li> <li>Burn and remint events SHOULD be separated in time to reduce linkability.</li> <li>Each burn operation MUST use a unique Provable Burn Address that can be used only once.</li> </ul> </li> <li> <p>Fully On-Chain Operation: The protocol operates entirely on-chain and requires no trusted backend. It can be directly integrated into wallets or dApps without introducing custodial or centralized dependencies.</p> </li> <li> <p>Commit Data Privacy: When generating proofs, users SHOULD retrieve as much commitment data as possible to maximize anonymity. Relying on selective or limited data sources may allow inference of the specific commit path being proven, weakening privacy guarantees.</p> </li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-10-17T00:00:00+00:00 2026-02-11T14:49:27+00:00 Renaud Duboishttps://github.com/rdubois-crypto Simon Massonhttps://github.com/simonmasson Antonio Sansohttps://github.com/asanso Marius van der Wijdenhttps://github.com/mariusvanderwijden Kevaundray Wedderburnhttps://github.com/kevaundray Zhenfei Zhanghttps://github.com/zhenfeizhang Nicolas Consignyhttps://github.com/nconsigny https://wg-eips.ritovision.com/8052/

Proposal to add a precompiled contract that performs signature verifications using the Falcon signature scheme.

<h2 id="abstract">Abstract</h2> <p>This proposal creates a precompiled contract that performs signature verifications using the Falcon-512 signature scheme by given parameters of the message hash, signature, and public key. This allows any EVM chain -- principally Ethereum roll-ups -- to integrate this precompiled contract easily.</p> <p>The signature scheme can be instantiated in two version:</p> <ul> <li>Falcon, the standard signature scheme, fully compliant with the algorithm recommended by the NIST,</li> <li>An EVM-friendly version where the hash function is efficiently computed in the Ethereum Virtual Machine.</li> </ul> <p>Three precompiled contracts are specified (formerly called <code>ETH_HASH_TO_POINT</code> / <code>HASH_TO_POINT_ETH</code> in drafts):</p> <ul> <li><code>FALCON_HASH_TO_POINT_SHAKE256</code> — NIST-compliant Hash-to-Point using SHAKE256.</li> <li><code>FALCON_HASH_TO_POINT_KECCAKPRNG</code> — EVM-friendly Hash-to-Point using a Keccak-based XOF/PRNG.</li> <li><code>FALCON_CORE</code> — the core algorithm of Falcon, that verifies the signature from the obtained (HashToPoint) challenge.</li> </ul> <h2 id="motivation">Motivation</h2> <p>Quantum computers pose a long-term risk to classical cryptographic algorithms. In particular, signature algorithms based on the hardness of the Elliptic Curve Discrete Logarithm Problem (ECDLP) such as secp256k1, are widely used in Ethereum and threaten by quantum algorithms. This exposes potentially on-chain assets and critical infrastructure to quantum adversaries.</p> <p>Integrating post-quantum signature schemes is crucial to future-proof Ethereum and other EVM-based environments. It shall be noted that infrastructure for post-quantum signatures should be deployed <em>before</em> quantum adversaries are known to be practical because it takes on the order of years for existing applications to integrate.</p> <p>Falcon, a lattice-based scheme standardized by NIST, offers high security against both classical and quantum adversaries. Its compact signature size (666 bytes for Falcon-512) and its efficient verification algorithm make it well-suited for blockchain applications, where gas usage and transaction throughput are critical considerations.</p> <!-- When the public key is also stored together with the signature, it leads to 666 + 896 = 1562 bytes. Using the recovery mode, it can be reduced to 1292 + 32 = 1324 bytes. --> <!-- For Falcon, σ=666 (40 bytes of salt, ~626 bytes for s2) pk = 896, TOTAL=1562 For FalconRec, σ=1292 (40 bytes of salt, ~626 bytes for s1, ~626 bytes for s2), pk = 32, TOTAL=1324 --> <p>In the context of the Ethereum Virtual Machine, a precompile for Keccak256 hash function is already available, making Falcon verification much faster when instantiated with an extendable output function derived from Keccak than with SHAKE256, as specified in NIST submission. This EIP specifies a split of the signature verification into two sub procedures:</p> <ul> <li><code>FALCON_HASH_TO_POINT_SHAKE256</code> or <code>FALCON_HASH_TO_POINT_KECCAKPRNG</code>, instantiated with a different extendable Output Function: the first with SHAKE256 (as recommended by NIST), the second with Keccak-PRNG (a version that is more efficient when computed in the EVM). In the future, it is possible to define it for SNARK/STARK circuits. An appropriated hash function choice reduces drastically the circuit size and the proving time in the context of ZK applications.</li> <li><code>FALCON_CORE</code>, that does not require any hash computation. This sub-algorithm follows the NIST recommendation so that: <ul> <li>using the SHAKE256 <code>FALCON_HASH_TO_POINT_SHAKE256</code>, the signature is fully compliant with the NIST standard,</li> <li>using the KeccakPRNG <code>FALCON_HASH_TO_POINT_KECCAKPRNG</code>, the verification can be efficient even in the EVM.</li> </ul> </li> </ul> <p>Using this separation, two important features are provided: one version being fully compliant with the NIST specification, the other deviating from the standard in order to reduce the gas cost, and opening up to possible computations of Falcon signature ZK proofs.</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>Falcon can be instantiated with polynomials of degree $512$ or $1024$, leading to a different security level. Falcon-512 is chosen, leading to a security level equivalent to RSA2048. This setting leads to the following size for signatures and keys:</p> <table><thead><tr><th>Parameter</th><th>Falcon</th></tr></thead><tbody> <tr><td><strong>n</strong> (lattice dimension)</td><td><code>512</code></td></tr> <tr><td><strong>q</strong> (modulus)</td><td><code>12289</code></td></tr> <tr><td>Padded signature size</td><td><code>666</code> bytes</td></tr> <tr><td>Public Key size</td><td><code>896</code> bytes</td></tr> <tr><td>Private key size</td><td><code>1281</code> bytes</td></tr> </tbody></table> <p>From a high level, a signature verification can be decomposed in two steps:</p> <ul> <li>The <strong>challenge computation</strong>, that involves the message and the salt, and computes a challenge polynomial using a XOF (instantiated with SHAKE256 and a Keccak-base PRNG here),</li> <li>The <strong>core algorithm</strong>, that compute polynomial arithmetic (with the challenge, the public key and the signature), and finally verify the shortness of the full signature $(s_1,s_2)$.</li> </ul> <p>The following pseudo-code highlights how these two algorithms are involved in a Falcon verification, and how the modularity of the challenge computation opens up to two version of Falcon:</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"> falcon512_verify</span><span>(</span><span class="z-variable z-parameter z-function">message</span><span>:</span><span class="z-support"> bytes</span><span>,</span><span class="z-variable z-parameter z-function"> signature</span><span>:</span><span class="z-support"> bytes</span><span>,</span><span class="z-variable z-parameter z-function"> pubkey</span><span>:</span><span class="z-support"> bytes</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-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string"> Verify a Falcon Signature following NIST standard</span></span> <span class="giallo-l"><span class="z-string"> Args:</span></span> <span class="giallo-l"><span class="z-string"> message (bytes): The message to sign.</span></span> <span class="giallo-l"><span class="z-string"> signature (666 bytes): The signature containing 40 bytes of salt and 626 bytes of compressed signature.</span></span> <span class="giallo-l"><span class="z-string"> pubkey (bytes): The Falcon public key.</span></span> <span class="giallo-l"><span class="z-string"> Returns:</span></span> <span class="giallo-l"><span class="z-string"> bool: True if the signature is valid, False otherwise.</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 1. Compute the Hash To Point Challenge (see 3.1.)</span></span> <span class="giallo-l"><span> challenge</span><span class="z-keyword"> =</span><span> HASH_TO_POINT</span><span>(</span><span>message</span><span>,</span><span> signature</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"> 2. Verify Falcon Core Algorithm (see 3.2.)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> FALCON_CORE</span><span>(</span><span>signature</span><span>,</span><span> pubkey</span><span>,</span><span> challenge</span><span>)</span></span></code></pre><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"> ethfalcon512_verify</span><span>(</span><span class="z-variable z-parameter z-function">message</span><span>:</span><span class="z-support"> bytes</span><span>,</span><span class="z-variable z-parameter z-function"> signature</span><span>:</span><span class="z-support"> bytes</span><span>,</span><span class="z-variable z-parameter z-function"> pubkey</span><span>:</span><span class="z-support"> bytes</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-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string"> Verify a Falcon Signature (EVM-friendly mode)</span></span> <span class="giallo-l"><span class="z-string"> Args:</span></span> <span class="giallo-l"><span class="z-string"> message (bytes): The message to sign.</span></span> <span class="giallo-l"><span class="z-string"> signature (666 bytes): The signature containing 40 bytes of salt and 626 bytes of compressed signature.</span></span> <span class="giallo-l"><span class="z-string"> pubkey (bytes): The Falcon public key.</span></span> <span class="giallo-l"><span class="z-string"> Returns:</span></span> <span class="giallo-l"><span class="z-string"> bool: True if the signature is valid, False otherwise.</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 1. Compute the Hash To Point Challenge (see 3.1.)</span></span> <span class="giallo-l"><span> challenge</span><span class="z-keyword"> =</span><span> ETH_HASH_TO_POINT</span><span>(</span><span>message</span><span>,</span><span> signature</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"> 2. Verify Falcon Core Algorithm (see 3.2.)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> FALCON_CORE</span><span>(</span><span>signature</span><span>,</span><span> pubkey</span><span>,</span><span> challenge</span><span>)</span></span></code></pre> <p>The functions <code>falcon512_verify</code> and <code>ethfalcon512_verify</code> call the precompiles specified in the next sections: <code>FALCON_HASH_TO_POINT_SHAKE256</code>, <code>FALCON_HASH_TO_POINT_KECCAKPRNG</code> and <code>FALCON_CORE</code>.</p> <h3 id="hash-to-point-challenge-normative">Hash-to-Point challenge (normative)</h3> <ol> <li><strong>Parse Input Data:</strong> Check the byte sizes and then extract the message and the signature. The parsed signature is a tuple of values $(r, s_2)$. $r$ is denoted as the salt and contains bytes, and $s_2$ is denoted as the signature vector, a vector of elements mod $q$.</li> <li><strong>Verify Well-formedness:</strong> Verify that the signature contains a 40-byte salt $r$.</li> </ol> <!-- See the `Required Checks in Verification` section for more details. --> <ol start="3"> <li><strong>Compute the challenge $c$:</strong> the challenge is obtained from hash-to-point on the salt $r$ of the signature and the message. The output $c$ is a polynomial of degree 512, stored in 896 bytes. The hash-to-point function computes extendable Output from a hash Function (XOF). This EIP provides two instantiations of a XOF: <ul> <li> <p>SHAKE256 is the XOF provided in NIST submission, a sponge construction derived from SHA256. Extracting bytes using SHAKE256 calls the <code>Keccak_f</code> permutation:</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"> SHAKE256_init</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> create</span><span> an</span><span> empty</span><span> sponge</span><span> state</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"> SHAKE256_inject</span><span>(</span><span class="z-variable z-parameter z-function">data</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> absorb</span><span> into</span><span> Keccak</span><span> sponge</span><span> state</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"> SHAKE256_flip</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> pad</span><span class="z-support"> input</span><span class="z-keyword"> and</span><span> finalize</span><span> sponge</span></span> <span class="giallo-l"><span> (</span><span>no</span><span> fixed</span><span class="z-keyword">-</span><span>length</span><span> digest</span><span> yet</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"> SHAKE256_extract</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>,</span><span class="z-variable z-parameter z-function"> length</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> output</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> output</span><span>.</span><span>size</span><span class="z-keyword"> &lt;</span><span> length</span><span>:</span></span> <span class="giallo-l"><span> block</span><span class="z-keyword"> =</span><span> Keccak_f</span><span>(</span><span>state</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> apply permutation</span></span> <span class="giallo-l"><span> output</span><span>.</span><span>append</span><span>(</span><span>state_part</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> take r-bit &quot;rate&quot; portion</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> first</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">length</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-support"> bytes</span><span> of</span><span> output</span></span></code></pre> <p>While this construction is standardized, it is expensive when computed in the Ethereum Virtual Machine because <code>Keccak_f</code> has no EVM opcode.</p> </li> <li> <p>Keccak-PRNG is a XOF that is build from a counter-mode PRNG based on Keccak256. Generating new chunks of bytes requires an incrementing counter.</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"> KeccakPRNG_init</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> create</span><span> an</span><span> empty</span><span> buffer</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"> KeccakPRNG_inject</span><span>(</span><span class="z-variable z-parameter z-function">data</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> buffer</span><span>.</span><span>append</span><span>(</span><span>data</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"> KeccakPRNG_flip</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> state</span><span class="z-keyword"> =</span><span> Keccak256</span><span>(</span><span>buffer</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> fixed 32-byte state</span></span> <span class="giallo-l"><span> counter</span><span class="z-keyword"> =</span><span class="z-constant"> 0</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"> KeccakPRNG_extract</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>,</span><span class="z-variable z-parameter z-function"> length</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> output</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> counter</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> output</span><span>.</span><span>size</span><span class="z-keyword"> &lt;</span><span> length</span><span>:</span></span> <span class="giallo-l"><span> block</span><span class="z-keyword"> =</span><span> Keccak256</span><span>(</span><span>state</span><span class="z-invalid z-illegal"> ||</span><span> counter</span><span>)</span></span> <span class="giallo-l"><span> output</span><span>.</span><span>append</span><span>(</span><span>block</span><span>)</span></span> <span class="giallo-l"><span> counter</span><span class="z-keyword"> =</span><span> counter</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> first</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">length</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-support"> bytes</span><span> of</span><span> output</span></span></code></pre> <p>Precompile of <code>Keccak256</code> are available in the Ethereum Virtual Machine, making this XOF very efficient in the EVM.</p> </li> </ul> </li> </ol> <p>Using one of the XOFs above (SHAKE256 or Keccak-PRNG), it is possible to instantiate two (precompiles) algorithms for hashing into points:</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"> FALCON_HASH_TO_POINT_SHAKE256</span><span>(</span><span class="z-variable z-parameter z-function">message</span><span>:</span><span> bytes32</span><span>,</span><span class="z-variable z-parameter z-function"> signature</span><span>:</span><span class="z-support"> bytes</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-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string"> Compute the Hash To Point Falcon Challenge.</span></span> <span class="giallo-l"><span class="z-string"> Args:</span></span> <span class="giallo-l"><span class="z-string"> message (bytes32): The original message (hash).</span></span> <span class="giallo-l"><span class="z-string"> signature (666 bytes): containing:</span></span> <span class="giallo-l"><span class="z-string"> - r (40 bytes): The salt.</span></span> <span class="giallo-l"><span class="z-string"> - s (626 bytes): The compressed signature vector.</span></span> <span class="giallo-l"><span class="z-string"> Returns:</span></span> <span class="giallo-l"><span class="z-string"> c: The Hash To Point polynomial challenge as a vector.</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Constants</span></span> <span class="giallo-l"><span> q</span><span class="z-keyword"> =</span><span class="z-constant"> 12289</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Falcon modulus</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Step 1: Parse Input Data</span></span> <span class="giallo-l"><span> r</span><span>,</span><span> s2_compressed</span><span class="z-keyword"> =</span><span> signature</span><span>[</span><span>:</span><span class="z-constant">40</span><span>]</span><span>,</span><span> signature</span><span>[</span><span class="z-constant">40</span><span>:</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Extract salt and compressed signature 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"> Step 2: Verify Well-formedness</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> is_valid_signature_format</span><span>(</span><span>s2_compressed</span><span>,</span><span> pubkey</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Step 3: Compute the challenge vector HashToPoint(r || message)</span></span> <span class="giallo-l"><span> c</span><span class="z-keyword"> =</span><span> [</span><span class="z-constant">0</span><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span>n</span><span>)</span><span>]</span></span> <span class="giallo-l"><span> SHAKE256_init</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> SHAKE256_inject</span><span>(</span><span>r</span><span class="z-keyword">+</span><span>message</span><span>)</span></span> <span class="giallo-l"><span> i</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> i</span><span class="z-keyword"> &lt;</span><span> n</span><span> do</span></span> <span class="giallo-l"><span> t</span><span class="z-keyword"> =</span><span> SHAKE256_extract</span><span>(</span><span class="z-constant">2</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> t</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 61445</span><span> then</span></span> <span class="giallo-l"><span> c_i</span><span class="z-keyword"> =</span><span> t</span><span> mod</span><span> q</span></span> <span class="giallo-l"><span> i</span><span class="z-keyword"> =</span><span> i</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> c</span></span></code></pre><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"> FALCON_HASH_TO_POINT_KECCAKPRNG</span><span>(</span><span class="z-variable z-parameter z-function">message</span><span>:</span><span> bytes32</span><span>,</span><span class="z-variable z-parameter z-function"> signature</span><span>:</span><span class="z-support"> bytes</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-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string"> Compute the Hash To Point Falcon Challenge using Keccak-PRNG.</span></span> <span class="giallo-l"><span class="z-string"> Args:</span></span> <span class="giallo-l"><span class="z-string"> message (bytes32): The original message (hash).</span></span> <span class="giallo-l"><span class="z-string"> signature (666 bytes): containing:</span></span> <span class="giallo-l"><span class="z-string"> - r (40 bytes): The salt.</span></span> <span class="giallo-l"><span class="z-string"> - s (626 bytes): The compressed signature vector.</span></span> <span class="giallo-l"><span class="z-string"> Returns:</span></span> <span class="giallo-l"><span class="z-string"> c: The Hash To Point polynomial challenge as a vector.</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Constants</span></span> <span class="giallo-l"><span> q</span><span class="z-keyword"> =</span><span class="z-constant"> 12289</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Falcon modulus</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Step 1: Parse Input Data</span></span> <span class="giallo-l"><span> r</span><span>,</span><span> s2_compressed</span><span class="z-keyword"> =</span><span> signature</span><span>[</span><span>:</span><span class="z-constant">40</span><span>]</span><span>,</span><span> signature</span><span>[</span><span class="z-constant">40</span><span>:</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Extract salt and compressed signature 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"> Step 2: Verify Well-formedness</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> is_valid_signature_format</span><span>(</span><span>s2_compressed</span><span>,</span><span> pubkey</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Step 3: Compute the challenge vector HashToPoint(r || message)</span></span> <span class="giallo-l"><span> c</span><span class="z-keyword"> =</span><span> [</span><span class="z-constant">0</span><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span>n</span><span>)</span><span>]</span></span> <span class="giallo-l"><span> KeccakPRNG_init</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> KeccakPRNG_inject</span><span>(</span><span>r</span><span class="z-keyword">+</span><span>message</span><span>)</span></span> <span class="giallo-l"><span> i</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> i</span><span class="z-keyword"> &lt;</span><span> n</span><span> do</span></span> <span class="giallo-l"><span> t</span><span class="z-keyword"> =</span><span> KeccakPRNG_extract</span><span>(</span><span class="z-constant">2</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> t</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 61445</span><span> then</span></span> <span class="giallo-l"><span> c_i</span><span class="z-keyword"> =</span><span> t</span><span> mod</span><span> q</span></span> <span class="giallo-l"><span> i</span><span class="z-keyword"> =</span><span> i</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> c</span></span></code></pre><h4 id="encoding-of-the-challenge-polynomial-c-896-bytes-normative">Encoding of the challenge polynomial <code>c</code> (896 bytes, normative)</h4> <ul> <li>Domain: degree-512 polynomial with coefficients in <code>[0, q)</code>, <code>q = 12289</code>.</li> <li>Order: coefficients are serialized in index order <code>c[0], c[1], …, c[511]</code>.</li> <li>Bit-packing: each coefficient is a 14-bit <strong>big-endian</strong> unsigned integer. Concatenate all 512 encodings into a bitstring of exactly <strong>896 bytes</strong>. Consumers MUST reject encodings that are not exactly 896 bytes.</li> </ul> <h3 id="core-algorithm">Core algorithm</h3> <ol> <li><strong>Parse Input Data:</strong> Check the byte sizes and then extract the public key, the Hash To Point Challenge and the signature. <ul> <li>The parsed public key $h$, interpreted as a vector of elements mod $q$,</li> <li>The parsed signature $(r, s_2)$. $r$ is denoted as the salt and $s_2$ is denoted as the signature vector, made of elements mod $q$.</li> </ul> </li> <li><strong>Verify Well-formedness:</strong> Verify that the signature, Hash To Point Challenge and public key have the correct number of elements and is canonical.</li> </ol> <!-- See the `Required Checks in Verification` section for more details. --> <ol start="3"> <li> <p><strong>Compute $s_1$ from $s_2$ and $h$.</strong> $s_1 = c - h * s_2$ where:</p> <ul> <li>$c$ is the Hash To Point challenge,</li> <li>$h$ is the public key, represented in the ntt domain</li> <li>$s_2$ is the signature vector.</li> </ul> <blockquote> <p>Note: since $h$ and $s_2$ are polynomials, the operation $*$ is the polynomial multiplication and can be sped up using the Number Theoretic Transform (NTT).</p> </blockquote> </li> <li> <p><strong>Check $L^2$ norm Bound:</strong> Verify that the signature is <em>short</em> by checking the following equation: $$ ||(s_1, s_2) ||_2^2 &lt; \lfloor\beta^2\rfloor$$ where $\beta^2$ is the acceptance bound. For Falcon-512, it is $\lfloor\beta^2\rfloor = 34034726$.</p> </li> </ol> <p>The following code illustrates Falcon core algorithm:</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"> FALCON_CORE</span><span>(</span><span class="z-variable z-parameter z-function">signature</span><span>:</span><span class="z-support"> bytes</span><span>,</span><span class="z-variable z-parameter z-function"> h</span><span>:</span><span class="z-support"> bytes</span><span>,</span><span class="z-variable z-parameter z-function"> challenge</span><span>:</span><span class="z-support"> bytes</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-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string"> Verify Falcon Core Algorithm</span></span> <span class="giallo-l"><span class="z-string"> Args:</span></span> <span class="giallo-l"><span class="z-string"> - signature (666 bytes): containing:</span></span> <span class="giallo-l"><span class="z-string"> - r (40 bytes): The salt.</span></span> <span class="giallo-l"><span class="z-string"> - s (626 bytes): The compressed signature vector.</span></span> <span class="giallo-l"><span class="z-string"> - h (bytes): The Falcon public key in the ntt domain, computed as h=ntt(pubkey) externally.</span></span> <span class="giallo-l"><span class="z-string"> - challenge (bytes): The Falcon Hash To Point Challenge.</span></span> <span class="giallo-l"><span class="z-string"> Returns:</span></span> <span class="giallo-l"><span class="z-string"> bool: True if the signature is valid, False otherwise.</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Constants</span></span> <span class="giallo-l"><span> q</span><span class="z-keyword"> =</span><span class="z-constant"> 12289</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Falcon modulus</span></span> <span class="giallo-l"><span class="z-constant"> ACCEPTANCE_BOUND</span><span class="z-keyword"> =</span><span class="z-constant"> 34034726</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Falcon-512 acceptance bound</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Step 1: Parse Input Data</span></span> <span class="giallo-l"><span> r</span><span>,</span><span> s2_compressed</span><span class="z-keyword"> =</span><span> signature</span><span>[</span><span>:</span><span class="z-constant">40</span><span>]</span><span>,</span><span> signature</span><span>[</span><span class="z-constant">40</span><span>:</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Extract salt and compressed signature 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"> Step 2: Verify Well-formedness</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> is_valid_signature_format</span><span>(</span><span>s2_compressed</span><span>,</span><span> pubkey</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Step 3: Decompress Signature Vector</span></span> <span class="giallo-l"><span> s2</span><span class="z-keyword"> =</span><span> decompress</span><span>(</span><span>s2_compressed</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Convert compressed signature to full form</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> s2</span><span class="z-keyword"> is</span><span class="z-constant"> None</span><span>:</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Reject invalid encodings </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"> Step 4: Convert to Evaluation domain (NTT)</span></span> <span class="giallo-l"><span> s2_ntt</span><span class="z-keyword"> =</span><span> ntt</span><span>(</span><span>s2</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"> Step 5: Compute the Verification Equation</span></span> <span class="giallo-l"><span> tmp_ntt</span><span class="z-keyword"> =</span><span> hadamard_product</span><span>(</span><span>s2_ntt</span><span>,</span><span> h</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Element-wise product</span></span> <span class="giallo-l"><span> tmp</span><span class="z-keyword"> =</span><span> intt</span><span>(</span><span>tmp_ntt</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Convert back to coefficient form (INTT)</span></span> <span class="giallo-l"><span> s1</span><span class="z-keyword"> =</span><span> challenge</span><span class="z-keyword"> -</span><span> tmp</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Step 6: Normalize s1 coefficients to be in the range [-q/2, q/2]</span></span> <span class="giallo-l"><span> s1</span><span class="z-keyword"> =</span><span> normalize_coefficients</span><span>(</span><span>s1</span><span>,</span><span> q</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"> Step 7: Compute Norm Bound Check</span></span> <span class="giallo-l"><span> s1_squared</span><span class="z-keyword"> =</span><span> square_each_element</span><span>(</span><span>s1</span><span>)</span></span> <span class="giallo-l"><span> s2_squared</span><span class="z-keyword"> =</span><span> square_each_element</span><span>(</span><span>s2</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> total_norm</span><span class="z-keyword"> =</span><span class="z-support"> sum</span><span>(</span><span>s1_squared</span><span>)</span><span class="z-keyword"> +</span><span class="z-support"> sum</span><span>(</span><span>s2_squared</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"> Step 8: Compare with Acceptance Bound</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> To ensure signature is short</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> total_norm</span><span class="z-keyword"> &lt;</span><span class="z-constant"> ACCEPTANCE_BOUND</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Falcon-512: β² = 34,034,726</span></span></code></pre><h3 id="required-checks-in-falcon-verification">Required Checks in Falcon Verification</h3> <p>The following requirements MUST be checked by the precompiled contract to verify signature components are valid:</p> <p><strong>Raw Input data</strong></p> <ul> <li>Verify that the message is 32-bytes long,</li> <li>Verify that the public key is 896-bytes long,</li> <li>Verify that the signature is 666-bytes long.</li> </ul> <p><strong>Parsed Input data</strong></p> <ul> <li>Verify that the public key consists of 512 elements, where each element is between $[0, q-1]$,</li> <li>Verify that the signature vector in the signature consists of 512 elements, where each element is between $[0, q-1]$,</li> <li>Verify that the salt in the signature is 40-bytes long.</li> </ul> <p><strong>Gas burning on error</strong> if one of the above condition is not met then all the gas supplied along with a CALL or STATICCALL is burned. it shall also be burned if an error happens during decompression (incorrect encodings).</p> <h3 id="precompiled-contract-specification">Precompiled Contract Specification</h3> <p>The precompiled contracts are proposed with the following input and outputs, which are big-endian values:</p> <h4 id="falcon-hash-to-point-shake256"><code>FALCON_HASH_TO_POINT_SHAKE256</code></h4> <p><strong>Input</strong></p> <ul> <li>32 bytes: message hash <code>m</code>,</li> <li>666 bytes: salt <code>r</code> (40 bytes), Falcon-512 compressed signature <code>s2_compressed</code> (626 bytes) concatenated: <code>r || s2_compressed</code>.</li> </ul> <p><strong>Output</strong></p> <ul> <li>896 bytes: packed challenge polynomial <code>c</code> (see §3.1 encoding)</li> </ul> <h4 id="falcon-hash-to-point-keccakprng"><code>FALCON_HASH_TO_POINT_KECCAKPRNG</code></h4> <p>Same I/O as §4.1, but the XOF is Keccak-PRNG. The construction is normative and MUST define: state initialization, domain-separation (if any), counter width and endianness, and block concatenation order.</p> <h4 id="falcon-core"><code>FALCON_CORE</code></h4> <ul> <li><strong>Input data</strong> <ul> <li>666 bytes for Falcon-512 signature</li> <li>896 bytes for Falcon-512 public key</li> <li>896 bytes for the Hash To Point Challenge</li> </ul> </li> <li><strong>Output data</strong>: <ul> <li>If the core algorithm process succeeds, it returns 1 in 32 bytes format.</li> <li>If the core algorithm process fails, it does not return any output data.</li> </ul> </li> </ul> <h4 id="error-cases">Error Cases</h4> <ul> <li>Invalid input length (not compliant to described input)</li> <li>Invalid field element encoding (≥ q)</li> <li>Invalid signature decompression</li> </ul> <p>Note that a well-formed but invalid signature does not produce an error, but <code>FALCON_CORE</code> invalidates the signature (and it does not return any output data).</p> <h4 id="precompiled-contract-gas-usage">Precompiled Contract Gas Usage</h4> <p>The cost of the <strong>FALCON_HASH_TO_POINT_SHAKE256</strong> and <strong>FALCON_HASH_TO_POINT_KECCAKPRNG</strong> is set to 1000 gas.</p> <p>The cost of <strong>FALCON_CORE</strong> is set to 2000 gas.</p> <p>Thus, the total cost of the signature is 3000 gas.</p> <h2 id="rationale">Rationale</h2> <p>The Falcon signature scheme was selected as a NIST-standardized post-quantum cryptographic algorithm due to its strong security guarantees and efficiency.</p> <p>Falcon is a signature algorithm build from lattice-based cryptography. Specifically, its hardness relies on the Short Integer Solution (SIS) problem over NTRU lattices, which is believed to be hard for both classical and quantum computers.</p> <p>Falcon offers several advantages over traditional cryptographic signatures such as secp256k1 and secp256r1:</p> <ul> <li><strong>Efficiency</strong>: Falcon is highly optimized for constrained environments, offering small signature sizes (666 bytes for Falcon-512) and fast verification time. This makes it well-suited for Ethereum, where gas costs and computational efficiency are critical factors.</li> <li><strong>NIST Standardization</strong>: Falcon was selected as part of NIST Post-Quantum Cryptography Standardization process, ensuring that it meets rigorous security and performance criteria.</li> <li><strong>Enabling Future-Proof Smart Contracts</strong>: With the integration of Falcon, Ethereum roll-ups and smart contract applications can start adopting quantum-secure schemes that remain secure even when we have quantum computers.</li> <li><strong>Compatibility with Existing EVM Designs</strong>: While Falcon operates on fundamentally different cryptographic assumptions than elliptic curves, its verification process can be efficiently implemented as a precompiled contract with similar APIs to classical signature schemes like secp256r1.</li> </ul> <p>Given the increasing urgency of transitioning to quantum-resistant cryptographic primitives or even having them ready in the event that research into quantum computers speeds up.</p> <h3 id="gas-cost-explanations">Gas cost explanations</h3> <p>The cost of the <strong>HASH_TO_POINT</strong> and <strong>HASH_TO_POINT_ETH</strong> functions is dominated by the call to the underlying hash function. It represents in average 35 calls to the hash function. Taking linearly the cost of keccak256, and avoiding the context switching it represents 1000 gas.</p> <p>The cost of <strong>FALCON_CORE</strong> function is dominated by performing 2 NTTs and 1 inverse NTT. One of these NTTs is for the public key and can be precomputed so that the contract requires to perform only 1 NTT and 1 inverse NTT. An estimation of the cost is given by 2000 gas.</p> <p>The cost is interpolated using rule of thumb from SUPERCOPS signatures benchmark results.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>In compliance with <a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a>, the necessary parameters and structure for its integration are provided. <code>ALG_TYPE = 0xFA</code> uniquely identifies Falcon-512 transactions, set MAX_SIZE = 667 bytes to accommodate the fixed-length signature_info container (comprising a 1-byte version tag and a 666-byte Falcon signature), and recommend a <code>GAS_PENALTY</code> of approximately <code>3000</code> gas subject to benchmarking. The verification function follows the EIP-7932 model, parsing the signature_info, recovering the corresponding Falcon public key, verifying the signature against the transaction payload hash, and deriving the signer's Ethereum address as the last 20 bytes of keccak256(pubkey). This definition ensures that Falcon-512 can be cleanly adopted within the <code>AlgorithmicTransaction</code> container specified by EIP-7932.</p> <p>As per <a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a>, this EIP defines two Falcon algorithm types:</p> <ul> <li><code>ALG_TYPE = 0xFA</code> — Falcon-512 with SHAKE256 H2P</li> <li><code>ALG_TYPE = 0xFB</code> — Falcon-512 with Keccak-PRNG H2P</li> </ul> <p><strong>Container and sizes.</strong> The <code>signature_info</code> container omits any pubkey hash; the public key is recovered by <code>verify(...)</code> and the 7932 sig-recover precompile derives the address as <code>keccak(ALG_TYPE || pubkey)[12:]</code>. Therefore:</p> <ul> <li><code>MAX_SIZE = 667</code> bytes (1-byte <code>ALG_TYPE</code> + 666-byte Falcon compressed signature).</li> </ul> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>signature_info</span><span class="z-keyword"> =</span><span> Container</span><span>[</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 0xFA Falcon-512 (SHAKE H2P), 0xFB Falcon-512 (Keccak H2P)</span></span> <span class="giallo-l"><span> version</span><span>:</span><span> uint8</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Falcon-512 signature (compressed). If an implementation produces a shorter form, it MUST be left-padded to 666 bytes.</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span> ByteVector</span><span>[</span><span class="z-constant">666</span><span>]</span></span> <span class="giallo-l"><span>]</span></span></code></pre> <p>In the format of <a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a>:</p> <ul> <li> <p>For the NIST-compliant version:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>verify</span><span>(</span><span>signature_info</span><span>:</span><span class="z-support"> bytes</span><span>,</span><span> payload_hash</span><span>:</span><span> Hash32</span><span>)</span><span class="z-invalid z-illegal"> -&gt;</span><span> ExecutionAddress</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>signature_info</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 699</span></span> <span class="giallo-l"><span> version</span><span class="z-keyword"> =</span><span> signature_info</span><span>[</span><span class="z-constant">0</span><span>]</span></span> <span class="giallo-l"><span> signature</span><span class="z-keyword"> =</span><span> signature_info</span><span>[</span><span class="z-constant">1</span><span>:</span><span class="z-constant">667</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> version</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> 0x</span><span class="z-constant">FA</span></span> <span class="giallo-l"><span> pubkey</span><span class="z-keyword"> =</span><span> lookup_pubkey</span><span>(</span><span>pubkey_hash</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> falcon512_verify</span><span>(</span><span>pubkey</span><span>,</span><span> signature</span><span>,</span><span> payload_hash</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> ExecutionAddress</span><span>(</span><span>keccak256</span><span>(</span><span>pubkey</span><span>)</span><span>[</span><span class="z-constant">12</span><span>:</span><span>]</span><span>)</span></span></code></pre></li> <li> <p>For the EVM-friendly version:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>verify</span><span>(</span><span>signature_info</span><span>:</span><span class="z-support"> bytes</span><span>,</span><span> payload_hash</span><span>:</span><span> Hash32</span><span>)</span><span class="z-invalid z-illegal"> -&gt;</span><span> ExecutionAddress</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>signature_info</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 699</span></span> <span class="giallo-l"><span> version</span><span class="z-keyword"> =</span><span> signature_info</span><span>[</span><span class="z-constant">0</span><span>]</span></span> <span class="giallo-l"><span> signature</span><span class="z-keyword"> =</span><span> signature_info</span><span>[</span><span class="z-constant">1</span><span>:</span><span class="z-constant">667</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> version</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> 0x</span><span class="z-constant">FB</span></span> <span class="giallo-l"><span> pubkey</span><span class="z-keyword"> =</span><span> lookup_pubkey</span><span>(</span><span>pubkey_hash</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> ethfalcon512_verify</span><span>(</span><span>pubkey</span><span>,</span><span> signature</span><span>,</span><span> payload_hash</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> ExecutionAddress</span><span>(</span><span>keccak256</span><span>(</span><span>pubkey</span><span>)</span><span>[</span><span class="z-constant">12</span><span>:</span><span>]</span><span>)</span></span></code></pre></li> </ul> <h3 id="addresses">Addresses</h3> <!-- TODO: backward compatibility --> <p><strong>TBD by ACD.</strong> Final precompile addresses will be selected within the EIP-managed range of <a href="https://wg-eips.ritovision.com/1352/">EIP-1352</a>, explicitly <strong>avoiding <code>0x0100–0x01FF</code> reserved for RIPs</strong> by <a href="https://wg-eips.ritovision.com/7587/">EIP-7587</a>.</p> <h2 id="test-cases">Test Cases</h2> <p>A set of test vectors for verifying implementations is located in a separate file (to be provided for each opcode). For the NIST compliant version, KATs are reproduced for HashToPoint (with a provided salt <code>r</code>) as well as for the compressed signature vector s2 (with a provided <code>HashToPoint</code> input). Note that <code>s2</code> is not padded with zeroes, leading to a maximum size of 626 bytes.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>An implementation is provided by the NIST. An implementation of the EVM-friendly version ETHFALCON is provided by ZKNOX.</p> <p><strong>TODO: We can modify geth to include falcon-512 as a reference. (Similar to secp256r1 signature verification)</strong></p> <h2 id="security-considerations">Security Considerations</h2> <p>The derivation path to obtain the private key from the seed is (tbd). Hash-to-Point functions MUST follow the specified XOFs byte-for-byte; domain separation and padding are normative.</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-10-17T00:00:00+00:00 2026-02-11T14:49:28+00:00 Maria Silvahttps://github.com/misilva73 https://wg-eips.ritovision.com/8053/

Adds `milli-gas` as the EVM’s internal gas accounting unit, reducing rounding errors without impacting UX

<h2 id="abstract">Abstract</h2> <p>This proposal introduces the <code>milli-gas</code> counter as the EVM's internal gas accounting. Gas costs are defined in <code>milli_gas</code> and internal EVM gas accounting is entirely carried out in <code>milli_gas</code>. At the end of transaction execution, <code>milli_gas</code> is rounded up to <code>gas</code>. Gas limits and transaction fees are still computed and verified using the current <code>gas_used</code> counter. This new counter enables a more precise accounting of cheap compute without impacting UX.</p> <h2 id="motivation">Motivation</h2> <p>Currently, most EVM compute operations (<code>ADD</code>, <code>SUB</code>, <code>MUL</code>, etc.) are significantly underpriced when compared with state operations (<code>SSTORE</code>, <code>SLOAD</code>, <code>CREATE</code>, etc.). There are two factors contributing to this mismatch. On one hand, client optimizations and hardware improvements have made pure compute operations more efficient. On the other hand, with the growing size of the Ethereum state, the performance of I/O operations touching this larger state has been deteriorating. Both of these trends are expected to continue, further worsening this mismatch.</p> <p>There are a couple of proposals to reduce the cost of compute operations (<a href="https://wg-eips.ritovision.com/7904/">EIP-7904</a>) and increase the cost of state operations (<a href="https://wg-eips.ritovision.com/8032/">EIP-8032</a>, <a href="https://wg-eips.ritovision.com/8037/">EIP-8037</a>, and <a href="https://wg-eips.ritovision.com/8038/">EIP-8038</a>). However, given the current level of mismatch between these operations, there is an inherent trade-off in the anchor we use to reprice these operations.</p> <p>If we make compute operations cheaper, we will introduce rounding errors, with most compute operations costing 1, when they should cost a fraction of that. These rounding errors impact scalability because we can now fit fewer of these cheaper operations in any given block. However, if we price all operations so that the fastest opcode is assigned 1 gas, we would need to make all other operations significantly more expensive, including both compute and state operations. Making everything more expensive would require a rebase on the concept of gas units to users, thus impacting UX.</p> <p>To illustrate this point, let's focus on the pure compute operations. As compute operations impact only block execution time, the chosen anchor will induce a specific million gas per second rate on all compute opcodes. For instance, if we anchor on <code>EcRecover</code> at the current price (3000 gas units), this induces a rate of 175Mgas/s, based on the execution time estimated for this opcode on <a href="../07904/assets/gas-cost-estimator-report.pdf">EIP-7904's empirical analysis</a>. The following plot shows the average rounding errors of compute operations for different anchors, using the same execution time estimates from EIP-7904.</p> <p><img src="https://wg-eips.ritovision.com/8053/./assets/round_error_by_anchor.png" alt="round_error_by_anchor" /></p> <p>As we can see, with an anchor of 50Mgas/s (which would result in a gas limit of 100Mgas, assuming a 2-second block execution limit), we would get an average rounding error of 59.3%. This means that we could be 59.3% cheaper on average per opcode if we didn't have to round to integer gas units. Only after a 400Mgas/s anchor do we get to reasonably low rounding errors. However, this level of Mgas/s would require a major rebase of the gas model, where all opcodes become significantly more expensive, and both the transaction-level and block-level gas limits increase by a factor of 100.</p> <p>The way around this trade-off is to allow cheap opcodes to have fractional gas costs, thus avoiding both the scalability limits introduced by rounding errors and the significant UX change of increasing gas costs and limits 100x.</p> <p>A similar argument was made in <a href="https://wg-eips.ritovision.com/2045/">EIP-2045</a>, which served as inspiration to this proposal.</p> <h2 id="specification">Specification</h2> <p>This proposal introduces a new <code>Uint</code> counter to the EVM, <code>milli_gas_left</code>. Gas costs are defined in <code>milli_gas</code> and internal EVM gas accounting is entirely carried out in <code>milli_gas</code>.</p> <p>Transaction fees, transaction gas limits, and block gas limits are still computed and verified using the current <code>gas_used</code> counter. There are no changes to blob gas accounting, refunds, or call data gas accounting.</p> <h3 id="evm-environment">EVM environment</h3> <p>The current <code>gas_left</code> variable from the internal state of the EVM is replaced by <code>milli_gas_left</code>:</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"> Evm</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span><span class="z-string">The internal state of the virtual machine.</span><span class="z-punctuation z-definition z-string">&quot;&quot;&quot;</span></span> <span class="giallo-l"><span> pc</span><span>:</span><span> Uint</span></span> <span class="giallo-l"><span> stack</span><span>:</span><span> List</span><span>[</span><span>U256</span><span>]</span></span> <span class="giallo-l"><span> memory</span><span>:</span><span class="z-support"> bytearray</span></span> <span class="giallo-l"><span> code</span><span>:</span><span> Bytes</span></span> <span class="giallo-l"><span> milli_gas_left</span><span>:</span><span> Uint</span></span> <span class="giallo-l"><span> valid_jump_destinations</span><span>:</span><span> Set</span><span>[</span><span>Uint</span><span>]</span></span> <span class="giallo-l"><span> logs</span><span>:</span><span> Tuple</span><span>[</span><span>Log</span><span>,</span><span class="z-constant"> ...</span><span>]</span></span> <span class="giallo-l"><span> refund_counter</span><span>:</span><span class="z-support"> int</span></span> <span class="giallo-l"><span> running</span><span>:</span><span class="z-support"> bool</span></span> <span class="giallo-l"><span> message</span><span>:</span><span> Message</span></span> <span class="giallo-l"><span> output</span><span>:</span><span> Bytes</span></span> <span class="giallo-l"><span> accounts_to_delete</span><span>:</span><span> Set</span><span>[</span><span>Address</span><span>]</span></span> <span class="giallo-l"><span> return_data</span><span>:</span><span> Bytes</span></span> <span class="giallo-l"><span> error</span><span>:</span><span> Optional</span><span>[</span><span>EthereumException</span><span>]</span></span> <span class="giallo-l"><span> accessed_addresses</span><span>:</span><span> Set</span><span>[</span><span>Address</span><span>]</span></span> <span class="giallo-l"><span> accessed_storage_keys</span><span>:</span><span> Set</span><span>[</span><span>Tuple</span><span>[</span><span>Address</span><span>,</span><span> Bytes32</span><span>]</span><span>]</span></span></code></pre> <p>All references to <code>evm.gas_left</code> are replaced by <code>evm.milli_gas_left</code>.</p> <h3 id="end-of-transaction-conversion">End-of-transaction conversion</h3> <p>At the end of each transaction execution, the gas left in the transaction output is updated to</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>tx_output</span><span>.</span><span>gas_left</span><span class="z-keyword"> =</span><span> ceil</span><span>(</span><span>evm</span><span>.</span><span>milli_gas_left</span><span class="z-keyword"> /</span><span class="z-constant"> 1000</span><span>)</span></span></code></pre> <p>At the same time, after the transaction is executed, <code>evm.milli_gas_used</code> is rounded up to <code>evm.gas_used = ceil(evm.milli_gas_used / 1000)</code>.</p> <h3 id="opcode-costs">Opcode costs</h3> <p>Opcode gas parameters as defined in the <a rel="external" href="https://github.com/ethereum/execution-specs/blob/abd7612d2f4d6fcd9f628330f38884b300f0d89f/src/ethereum/forks/osaka/vm/gas.py">Ethereum Execution Client Specifications</a> that are not updated at the same time or after the introduction of this proposal, are increased by 1000x:</p> <p><code>GAS_PARAM = GAS_PARAM * 1000</code></p> <h3 id="gas-opcode"><code>GAS</code> opcode</h3> <p>The <code>GAS</code> opcode reports the available gas in <code>milli-gas</code> units.</p> <h3 id="call-opcodes"><code>*CALL</code> opcodes</h3> <p><code>*CALL</code> opcodes receive the amount of gas to send to the sub context to execute in <code>gas</code>. <code>gas</code> is converted to <code>milli-gas</code> at the start of the call's execution:</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"> STACK</span></span> <span class="giallo-l"><span>gas</span><span class="z-keyword"> =</span><span> Uint</span><span>(</span><span>pop</span><span>(</span><span>evm</span><span>.</span><span>stack</span><span>)</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> 1000</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="new-counter-vs-new-variable-type">New counter vs. new variable type</h3> <p>A possible approach to allow for fractional gas would be to change the variable type of all gas-related variables from an integer to a float or a base fractional. Although simple in concept, the implementation of such a change in the EVM is not trivial. In addition, introducing fractional variables would make moving to a zkEVM significantly more complex.</p> <p>Thus, introducing a new counter is the option that least disrupts the current EVM implementation, while allowing for expressive gas costs.</p> <h3 id="rounding-at-transaction-level">Rounding at transaction-level</h3> <p>With the introduction of a new counter, there are two levels at which we could convert <code>milli_gas</code> to <code>gas</code>: at the transaction level or the block level. Conversion at the block level results in the fewest rounding errors in block utilization. However, it requires a bigger change to implement, as <code>milli_gas</code> will need to be used when computing transaction fees and limits, and <code>milli_gas</code> will need to be incorporated in the block environment.</p> <p>The question is whether a conversion at the transaction level is sufficient to reduce rounding errors. To estimate this, we extracted the opcode counts per transaction for 1000 mainnet blocks and computed the new gas prices of all compute operations assuming an anchor of 50Mgas/s and the estimated execution times from <a href="../07904/assets/gas-cost-estimator-report.pdf">EIP-7904's empirical analysis</a>. With this repricing, the fastest opcode (<code>JUMPDEST</code>) would be priced at 90 milli-gas units (i.e., 0.09 gas units). We also assumed that the non-compute operations and precompiles would have the same price, and we excluded any other transaction costs, such as intrinsic costs and calldata.</p> <p>Then, we computed the rounding error of each transaction, assuming a conversion at both the transaction and opcode levels. The opcode-level conversion is equivalent to not using fractional gas and rounding all opcodes to an integer. The following plot shows the distribution for both errors. The x-axis is on a logarithmic scale.</p> <p><img src="https://wg-eips.ritovision.com/8053/./assets/round_err_tx.png" alt="round_error_by_anchor" /></p> <p>In this sample of 1000 blocks, a transaction-level conversion has already successfully reduced the rounding errors from an average of 4% to 0.05% per transaction.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backwards incompatible gas repricing that requires a scheduled network upgrade.</p> <p>Deployed bytecode that compares <code>gas_left</code> to constants or that uses explicit gas-limited calls will suddenly forward 1000× less gas, causing unexpected reverts or logic flip. Further analysis on how widespread this behavior is required.</p> <h2 id="security-considerations">Security Considerations</h2> <p>&lt;-- TODO --&gt;</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-10-17T00:00:00+00:00 2026-02-11T14:49:27+00:00 Francesco D'Amatohttps://github.com/fradamt Anders Elowssonhttps://github.com/anderselowsson https://wg-eips.ritovision.com/8061/

Increase the exit and consolidation churn and create a separate consolidation churn limit parameter.

<h2 id="abstract">Abstract</h2> <p>This EIP roughly doubles the consolidation churn, as well as quadrupling the exit churn and restoring its proportionality to total stake (though maintaining the existing cap on activations). The choice of parameters balances maintaining a sufficiently long weak subjectivity period (~7 days, roughly halving the current period) with achieving two goals: allowing for faster consolidation of the validator set, in turn accelerating the timeline to faster finality, and relieving exit queue congestion, improving staking liquidity.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/7514/">EIP-7514</a> introduced an activation cap of 8 validators per epoch (now 256 ETH per epoch) to prevent overly rapid validator set growth. <a href="https://wg-eips.ritovision.com/7251/">EIP-7251</a> extended this cap to exits, to make room for the newly introduced consolidation operations, without increasing the weak subjectivity period. However, the fixed cap prevents the exit churn limit from being proportional to total stake, which, all else being equal, leads to longer queues as stake grows. Moreover, the <code>CHURN_LIMIT_QUOTIENT</code> is set quite conservatively in the first place, requiring more than 3 months for 1/3 of the validator set to exit, a time which is now be more than doubled due to the cap. Recent episodes have stressed for more headroom to improve liquidity and staking user experience, as the exit queue has stretched beyond forty days as a consequence of the mass exit of Kiln validators. Long queues degrade user experience, and slow operator response to market or operational events. They also reduce the network’s ability to reconfigure stake more quickly after adverse events, for example to regain finality by having a large amount of stake exit (a double-edged sword, as preventing double finality is the reason these queues exist in the first place, as discussed in the security section). Finally, centralized forms of staking are those that (in relative terms) benefit the most from a lack of liquidity today, as they have the ability to issue a liquid staking token, maintain liquidity reserves or more generally build products that get around the limitations of the protocol.</p> <p>The conservative setting of the <code>CHURN_LIMIT_QUOTIENT</code> affects consolidations as well. Increasing the consolidation churn limit can shorten the path to a smaller validator set and, in turn, the path to a protocol with much faster finality. Under today’s parameters, even the best-case timelines are long: using only activations and exits, fully saturated around the clock, shrinking the roughly 32M ETH of 0x01 stake would take on the order of ~1.5 years; a fully saturated consolidation queue would still take ~1.3 years. Moreover, deposit capacity is also needed for new stake and is thus far from guaranteed to be available for consolidations, as evidenced by the recent inflow of &gt; 1M ETH, fully occupying the queue for ~20 days.</p> <p>The EIP proposes to address these issues by:</p> <ul> <li>removing the cap on exits, restoring the proportionality of exit churn limit to total stake</li> <li>increasing the churn limit on exits</li> <li>introducing a separate consolidation churn limit, since there is no more "excess churn" from having an exit cap, and increase it compared to the current (implicitly defined) one. This also lets us more independently adjust it in the future, for example to increase it if we want to allow for faster consolidation of the validator set or decrease it when this process has already run its course.</li> </ul> <p>The EIP does <em>not</em> propose to lift the cap on the deposit churn, as part of the motivation for introducing it in <a href="https://wg-eips.ritovision.com/7514/">EIP-7514</a> still holds today: though <em>active validator set</em> growth is mostly solved by <a href="https://wg-eips.ritovision.com/7251/">EIP-7251</a>, the <em>validator array in the BeaconState</em> (including inactive validators) is very large and still growing, and too rapid <em>stake</em> growth continues to be a concern as well.</p> <h2 id="specification">Specification</h2> <p>The <code>CHURN_LIMIT_QUOTIENT</code> is halved, from <code>2**16</code> to <code>2**15</code>, and fully dedicated to activations and exits. However, the cap on activations introduced in <a href="https://wg-eips.ritovision.com/7514/">EIP-7514</a> is maintained via <code>MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT</code>, while exits are freed from this cap. Consolidations now have their own dedicated churn, determined by <code>CONSOLIDATION_CHURN_LIMIT_QUOTIENT</code>. This is set here to <code>2**16</code>, so that consolidations are allocated half as much churn as activations and exits combined, and a third of the total churn. Finally, <code>compute_weak_subjectivity_period</code> is adjusted to account for the asymmetry between exit and activation churn: a unit of exit churn has twice the weak subjectivity effect ($\frac{4}{3}$) of a unit of activation churn $\frac{2}{3}$, and a unit of consolidation churn has an effect equivalent to the sum of the other two ($2$).</p> <h3 id="configuration">Configuration</h3> <p><code>MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT</code> replaces the existing <code>MAX_PER_EPOCH_ACTIVATION_EXIT_CHURN_LIMIT</code>, also <code>256</code>, as the cap now only applies to activations. We introduce the new <code>CONSOLIDATION_CHURN_LIMIT_QUOTIENT</code> and update the <code>CHURN_LIMIT_QUOTIENT</code>.</p> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><code>CHURN_LIMIT_QUOTIENT_GLOAS</code></td><td><code>uint64(2**15)</code> (= 32,768)</td></tr> <tr><td><code>CONSOLIDATION_CHURN_LIMIT_QUOTIENT</code></td><td><code>uint64(2**16)</code> (= 65,536)</td></tr> <tr><td><code>MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT</code></td><td><code>uint64(2**8)</code> (=256)</td></tr> </tbody></table> <h3 id="churn-computations">Churn computations</h3> <p>Due to the intended asymmetry in activation and exit churn, we replace <code>get_activation_exit_churn_limit</code> with <code>get_activation_churn_limit</code>, capped at <code>MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT</code>, and <code>get_exit_churn_limit</code>, uncapped. <code>get_consolidation_churn_limit</code> uses the new <code>CONSOLIDATION_CHURN_LIMIT_QUOTIENT</code>, without either a minimum or a maximum value.</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_activation_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 class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string"> Per-epoch churn limit for activations, rounded to EFFECTIVE_BALANCE_INCREMENT.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> churn</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> MIN_PER_EPOCH_CHURN_LIMIT_ELECTRA</span><span>,</span></span> <span class="giallo-l"><span> get_total_active_balance</span><span>(</span><span>state</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> CHURN_LIMIT_QUOTIENT_GLOAS</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> churn</span><span class="z-keyword"> =</span><span> churn</span><span class="z-keyword"> -</span><span> churn</span><span class="z-keyword"> %</span><span class="z-constant"> EFFECTIVE_BALANCE_INCREMENT</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> min</span><span>(</span><span class="z-constant">MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT</span><span>,</span><span> churn</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_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 class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string"> Per-epoch churn limit for activations, rounded to EFFECTIVE_BALANCE_INCREMENT.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> churn</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> MIN_PER_EPOCH_CHURN_LIMIT_ELECTRA</span><span>,</span></span> <span class="giallo-l"><span> get_total_active_balance</span><span>(</span><span>state</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> CHURN_LIMIT_QUOTIENT_GLOAS</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> churn</span><span class="z-keyword"> -</span><span> churn</span><span class="z-keyword"> %</span><span class="z-constant"> EFFECTIVE_BALANCE_INCREMENT</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_consolidation_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 class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string"> Per-epoch churn limit for consolidations (EIP-7521), rounded to EFFECTIVE_BALANCE_INCREMENT.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> churn</span><span class="z-keyword"> =</span><span> get_total_active_balance</span><span>(</span><span>state</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> CONSOLIDATION_CHURN_LIMIT_QUOTIENT</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> churn</span><span class="z-keyword"> -</span><span> churn</span><span class="z-keyword"> %</span><span class="z-constant"> EFFECTIVE_BALANCE_INCREMENT</span></span></code></pre> <p>In <code>compute_weak_subjectivity_period</code> we only replace <code>delta = get_balance_churn_limit(state)</code> with an explicit calculation taking into account the different weak subjectivity effect of each type of operation.</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_weak_subjectivity_period</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> BeaconState</span><span>)</span><span> -&gt;</span><span> uint64</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"> Returns the weak subjectivity period for the current ``state``.</span></span> <span class="giallo-l"><span class="z-string"> This computation takes into account the effect of validator set churn, </span></span> <span class="giallo-l"><span class="z-string"> bounded by the three churn_limit functions used below.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> t</span><span class="z-keyword"> =</span><span> get_total_active_balance</span><span>(</span><span>state</span><span>)</span></span> <span class="giallo-l"><span> delta</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span class="z-constant"> 2</span><span class="z-keyword"> *</span><span> get_exit_churn_limit</span><span>(</span><span>state</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> 3</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> effect of exit churn</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> get_activation_churn_limit</span><span>(</span><span>state</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> 3</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> effect of activation churn</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> get_consolidation_churn_limit</span><span>(</span><span>state</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> effect of consolidation churn</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> epochs_for_validator_set_churn</span><span class="z-keyword"> =</span><span class="z-constant"> SAFETY_DECAY</span><span class="z-keyword"> *</span><span> t</span><span class="z-keyword"> //</span><span> (</span><span class="z-constant">2</span><span class="z-keyword"> *</span><span> delta</span><span class="z-keyword"> *</span><span class="z-constant"> 100</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> MIN_VALIDATOR_WITHDRAWABILITY_DELAY</span><span class="z-keyword"> +</span><span> epochs_for_validator_set_churn</span></span></code></pre><h3 id="deposit-processing">Deposit processing</h3> <p>The only modification is replacing <code>get_activation_exit_churn_limit</code> with <code>get_activation_churn_limit</code>, maintaing the current cap on deposit churn respects, while removing the cap from exits. This reverts to the pre-Electra status quo, when activations were capped but exits were not.</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_pending_deposits</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> Epoch</span><span>(</span><span>get_current_epoch</span><span>(</span><span>state</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"> [Modified in Gloas:EIP-8061]</span></span> <span class="giallo-l"><span> available_for_processing</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>deposit_balance_to_consume</span><span class="z-keyword"> +</span><span> get_activation_churn_limit</span><span>(</span></span> <span class="giallo-l"><span> state</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> processed_amount</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> next_deposit_index</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> deposits_to_postpone</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> is_churn_limit_reached</span><span class="z-keyword"> =</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span> finalized_slot</span><span class="z-keyword"> =</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"> for</span><span> deposit</span><span class="z-keyword"> in</span><span> state</span><span>.</span><span>pending_deposits</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Do not process deposit requests if Eth1 bridge deposits are not yet applied.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Is deposit request</span></span> <span class="giallo-l"><span> deposit</span><span>.</span><span>slot</span><span class="z-keyword"> &gt;</span><span class="z-constant"> GENESIS_SLOT</span></span> <span class="giallo-l"><span class="z-keyword"> and</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> There are pending Eth1 bridge deposits</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>eth1_deposit_index</span><span class="z-keyword"> &lt;</span><span> state</span><span>.</span><span>deposit_requests_start_index</span></span> <span class="giallo-l"><span> )</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> break</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Check if deposit has been finalized, otherwise, stop processing.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> deposit</span><span>.</span><span>slot</span><span class="z-keyword"> &gt;</span><span> finalized_slot</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> break</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Check if number of processed deposits has not reached the limit, otherwise, stop processing.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> next_deposit_index</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> MAX_PENDING_DEPOSITS_PER_EPOCH</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> break</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Read validator state</span></span> <span class="giallo-l"><span> is_validator_exited</span><span class="z-keyword"> =</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span> is_validator_withdrawn</span><span class="z-keyword"> =</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span> validator_pubkeys</span><span class="z-keyword"> =</span><span> [</span><span>v</span><span>.</span><span>pubkey</span><span class="z-keyword"> for</span><span> v</span><span class="z-keyword"> in</span><span> state</span><span>.</span><span>validators</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> deposit</span><span>.</span><span>pubkey</span><span class="z-keyword"> in</span><span> validator_pubkeys</span><span>:</span></span> <span class="giallo-l"><span> validator</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>validators</span><span>[</span><span>ValidatorIndex</span><span>(</span><span>validator_pubkeys</span><span>.</span><span>index</span><span>(</span><span>deposit</span><span>.</span><span>pubkey</span><span>)</span><span>)</span><span>]</span></span> <span class="giallo-l"><span> is_validator_exited</span><span class="z-keyword"> =</span><span> validator</span><span>.</span><span>exit_epoch</span><span class="z-keyword"> &lt;</span><span class="z-constant"> FAR_FUTURE_EPOCH</span></span> <span class="giallo-l"><span> is_validator_withdrawn</span><span class="z-keyword"> =</span><span> validator</span><span>.</span><span>withdrawable_epoch</span><span class="z-keyword"> &lt;</span><span> next_epoch</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> is_validator_withdrawn</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Deposited balance will never become active. Increase balance but do not consume churn</span></span> <span class="giallo-l"><span> apply_pending_deposit</span><span>(</span><span>state</span><span>,</span><span> deposit</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> is_validator_exited</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Validator is exiting, postpone the deposit until after withdrawable epoch</span></span> <span class="giallo-l"><span> deposits_to_postpone</span><span>.</span><span>append</span><span>(</span><span>deposit</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"> Check if deposit fits in the churn, otherwise, do no more deposit processing in this epoch.</span></span> <span class="giallo-l"><span> is_churn_limit_reached</span><span class="z-keyword"> =</span><span> processed_amount</span><span class="z-keyword"> +</span><span> deposit</span><span>.</span><span>amount</span><span class="z-keyword"> &gt;</span><span> available_for_processing</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> is_churn_limit_reached</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> break</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Consume churn and apply deposit.</span></span> <span class="giallo-l"><span> processed_amount</span><span class="z-keyword"> +=</span><span> deposit</span><span>.</span><span>amount</span></span> <span class="giallo-l"><span> apply_pending_deposit</span><span>(</span><span>state</span><span>,</span><span> deposit</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Regardless of how the deposit was handled, we move on in the queue.</span></span> <span class="giallo-l"><span> next_deposit_index</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>pending_deposits</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>pending_deposits</span><span>[</span><span>next_deposit_index</span><span>:</span><span>]</span><span class="z-keyword"> +</span><span> deposits_to_postpone</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Accumulate churn only if the churn limit has been hit.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> is_churn_limit_reached</span><span>:</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>deposit_balance_to_consume</span><span class="z-keyword"> =</span><span> available_for_processing</span><span class="z-keyword"> -</span><span> processed_amount</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>deposit_balance_to_consume</span><span class="z-keyword"> =</span><span> Gwei</span><span>(</span><span class="z-constant">0</span><span>)</span></span></code></pre><h3 id="exit-processing">Exit processing</h3> <p>We replace <code>get_activation_exit_churn_limit</code> with <code>get_exit_churn_limit</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"> 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> <span class="giallo-l"><span> state</span><span>.</span><span>earliest_exit_epoch</span><span>,</span></span> <span class="giallo-l"><span> compute_activation_exit_epoch</span><span>(</span><span>get_current_epoch</span><span>(</span><span>state</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"> [Modified in Gloas:EIP-8061]</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-keyword"> return</span><span> state</span><span>.</span><span>earliest_exit_epoch</span></span></code></pre><h2 id="rationale">Rationale</h2> <ul> <li><strong>Independent parameters:</strong> a separate churn consolidation is easy to independently tune, in particular adjusted upward if we want to speed up the consolidation process further, and later downward, when the primary wave of validator set consolidation has already happened and the consolidation operation becomes less crucial.</li> <li><strong>Scaling with stake</strong>: the exit churn regains proportionality to the total stake, and the consolidation churn maintains it.</li> <li><strong>Preserving the activation cap</strong>: the activation churn limit maintains the cap from <a href="https://wg-eips.ritovision.com/7514/">EIP-7514</a></li> <li><strong>Balancing security and functionality</strong>: the exit churn limit is increased by ~4x compared to the current cap, and exactly 2x compared to previous uncapped version, while the consolidation churn limit is increased by ~2x. Activations remain capped at the existing limit. As we see later in more detail, accounting for the asymmetric impact of exits and activations on safety degradation, this results in a decrease of the weak subjectivity period from ~15.7 days to ~7 days (see detailed calculations below), or ~6 days if we were to later remove the activation cap, in either case still on the order of a week. Moreover, were consolidations to be removed later, the weak subjectivity period would go up to ~11 days, or ~8.4 days without the activation cap.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces a backwards-incompatible change to the consensus rules and MUST be activated as part of a scheduled network upgrade.</p> <h2 id="test-cases">Test Cases</h2> <p>TODO</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="weak-subjectivity-period">Weak subjectivity period</h3> <p>Let <code>MIN_VALIDATOR_WITHDRAWABILITY_DELAY = 256</code> epochs, and let $S$ denote the total stake, $E$ the exit churn per epoch, $A$ the activation churn per epoch, and $C$ the consolidation churn per epoch. Each unit of exit churn contributes to a safety degradation (measured in ETH, as the churn) of $\frac{4}{3}$, whereas the safety degradation from activations is only $\frac{2}{3}$ per unit. Finally, it is $2$ per unit for consolidations, as a consolidation is the equivalent of an exit and an activation.</p> <p>The formula to compute the weak subjectivity period (in epochs) for a 10% safety decay target (exactly corresponding to <code>compute_weak_subjectivity_period</code>) then is:</p> <p>$\text{WS}_{\text{epochs}} = 256 + \frac{0.1 \cdot S}{\frac{4}{3} \cdot E + \frac{2}{3} \cdot A + 2 \cdot C}$</p> <p>The churn limits of the current protocol, assuming a total stake $S = 36M$ ETH (approximately the stake at the time of writing) are:</p> <ul> <li>$A = E = \min(256, S/2^{16}) = 256$ ETH (capped)</li> <li>$C = S/2^{16} - A \approx 293$ ETH</li> </ul> <p>The weak subjectivity period is then:</p> <p>$\text{WS}_{\text{epochs}} \approx 3533$</p> <p>$\Rightarrow\ \textbf{WS} \approx \mathbf{15.7\ \text{days}}$</p> <p>In days, it is $\text{WS}_{\text{epochs}} / 225$.</p> <p>Under this EIP, and assuming a total stake $S = 36M$ ETH:</p> <ul> <li>$E = S/2^{15} \approx 1098$ ETH</li> <li>$A = \min(256, S/2^{15}) = 256$ ETH (capped)</li> <li>$C = S/2^{16} \approx 549$ ETH</li> </ul> <p>The weak subjectivity period is then:</p> <p>$\text{WS}_{\text{epochs}} \approx 1573$</p> <p>$\Rightarrow\ \textbf{WS} \approx \mathbf{7.0\ \text{days}}$</p> <p>Other possible future scenarios are:</p> <ul> <li>Activation cap removed: $\textbf{WS} \approx \mathbf{6.0\ \text{days}}$ ($\text{WS}_{\text{epochs}} \approx 1348$)</li> <li>Consolidations disabled: $\textbf{WS} \approx \mathbf{10.9\ \text{days}}$ ($\text{WS}_{\text{epochs}} \approx 2457$)</li> <li>Consolidations disabled and activation cap removed: $\textbf{WS} \approx \mathbf{8.4\ \text{days}}$ ($\text{WS}_{\text{epochs}} \approx 1894$)</li> </ul> <p>Note that removing the activation cap only reduces the weak subjectivity period by one day, and leaves it on the order of a week. The current parameters might then also be considered acceptable in a future where it is decided to remove the activation cap.</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-10-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Francesco D'Amatohttps://github.com/fradamt Barnabas Busahttps://github.com/barnabasbusa https://wg-eips.ritovision.com/8045/

Modify proposer selection to exclude slashed validators, improving network resilience and performance after mass slashings

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a modification to the beacon chain proposer selection process to exclude slashed validators from being selected as proposers.</p> <h2 id="motivation">Motivation</h2> <p>Currently, slashed validators can still be selected as proposers, though their blocks are considered invalid by the state transition function, resulting in missed slots. This is in particular problematic after a mass slashing event, at which point there can be a long period with degraded chain performance, until all slashed validators are exited. If mass slashing also comes with general network disruption, the missed slots can also significantly complicate the recovery process. This change filters out slashed validators during proposer selection, reducing disruption and increasing resilience in such scenarios.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <p>The <code>get_beacon_proposer_indices</code> function in the consensus specifications is modified to exclude slashed validators from the proposer selection process, effectively going from considering all active validators to all active and unslashed validators.</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_beacon_proposer_indices</span><span>(</span></span> <span class="giallo-l"><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"> epoch</span><span>:</span><span> Epoch</span></span> <span class="giallo-l"><span>)</span><span> -&gt;</span><span> Vector</span><span>[</span><span>ValidatorIndex</span><span>,</span><span class="z-constant"> SLOTS_PER_EPOCH</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"> Return the proposer indices for the given ``epoch``.</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"> Modified to exclude slashed validators</span></span> <span class="giallo-l"><span> indices</span><span class="z-keyword"> =</span><span> [</span><span>i</span><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span> get_active_validator_indices</span><span>(</span><span>state</span><span>,</span><span> epoch</span><span>)</span><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> state</span><span>.</span><span>validators</span><span>[</span><span>i</span><span>]</span><span>.</span><span>slashed</span><span>]</span></span> <span class="giallo-l"><span> seed</span><span class="z-keyword"> =</span><span> get_seed</span><span>(</span><span>state</span><span>,</span><span> epoch</span><span>,</span><span class="z-constant"> DOMAIN_BEACON_PROPOSER</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> compute_proposer_indices</span><span>(</span><span>state</span><span>,</span><span> epoch</span><span>,</span><span> seed</span><span>,</span><span> indices</span><span>)</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="why-exclude-slashed-validators">Why exclude slashed validators?</h3> <p>Slashed validators are already prevented from successfully proposing blocks through the state transition validation. The <code>process_block</code> function checks that the proposer is not slashed, and blocks from slashed proposers are considered invalid. Therefore, selecting slashed validators as proposers serves no purpose and only results in missed slots.</p> <h3 id="design-decision-upfront-filtering">Design decision: upfront filtering</h3> <p>The chosen approach is to simply filter out slashed validators from the candidate pool, before doing any shuffling computation. An alternative design would be to still use the whole active validator set as the candidate pool, and then only filter out slashed validators once their index has been selected by the shuffle. The exact selection is not identical, but it achieves the same goal, i.e., a balance-weighted selection from the set of active-and-unslashed validators. The complexity is low in either design.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces a backwards-incompatible change to the consensus rules and MUST be activated as part of a scheduled network upgrade.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases should verify that:</p> <ol> <li>Slashed validators are not selected as proposers</li> <li>A complete <code>proposer_lookahead</code> is generated even in the presence of slashed validators</li> <li>Slashings do not affect the existing <code>proposer_lookahead</code></li> </ol> <h2 id="security-considerations">Security Considerations</h2> <p>Slashed validators are already prevented from successfully proposing blocks through the state transition validation, for good reason, as they are considered to be unreliable participants (malicious or faulty). However, they have historically still been eligible to be selected as proposers in order to ensure stability of the proposer selection mechanism, because excluding them would have severely impacted the stability of the proposer selection mechanism. In fact, any slashing processed on chain would have caused the sequence of future proposers to completely change, even within the lookahead window. However, with <a href="https://wg-eips.ritovision.com/7917/">EIP-7917</a>, the proposer selection is fixed in advance by storing in the Beacon state, so it would not be affected by slashings processed after the fact.</p> <h3 id="impact-on-proposer-selection-distribution">Impact on proposer selection distribution</h3> <p>This change does not affect the randomness or fairness of proposer selection among non-slashed validators. The selection algorithm remains the same, with the only difference being that slashed validators are excluded from the candidate pool.</p> <h3 id="mass-slashing-scenarios">Mass slashing scenarios</h3> <p>During mass slashing events, this change is purely beneficial to the resilience of the network, as well as to general quality of service. Instead of having many slashed validators selected as proposers (resulting in many missed slots), the network will continue to operate normally with only non-slashed validators being selected.</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-10-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Anders Elowssonhttps://github.com/anderselowsson https://wg-eips.ritovision.com/8046/

Ensure IL transactions that offer a higher ranking fee than competing transactions are included in the block. Burn the marginal ranking fee.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a uniform price auction over inclusion lists (UPIL), which ranks transactions by their offered ranking fee per gas. When the block is full, no transaction is allowed to displace an inclusion-list (IL) transaction that passes regular inclusion criteria and offers a higher ranking fee per gas. All included transactions pay a uniform inclusion price, equal to the highest ranking fee offered by any valid IL transaction excluded from the block, and this fee is burned. UPIL achieves strong censorship resistance by not allowing builders to circumvent propagated ILs when the block is full. This is particularly valuable for time-sensitive transactions and promotes fairness while preventing cheap block-stuffing under a multidimensional fee market. UPIL is specified to run on top of FOCIL (<a href="https://wg-eips.ritovision.com/7805/">EIP-7805</a>), but can be deployed on top of any IL mechanism.</p> <h2 id="motivation">Motivation</h2> <p>Censorship resistance (CR) is a key property of decentralized blockchains. To ensure that transactions cannot be censored by the entity building the block (denoted "builder" in this EIP, which may sometimes be the proposer), a mechanism called fork-choice enforced inclusion lists (FOCIL) has been proposed in <a href="https://wg-eips.ritovision.com/7805/">EIP-7805</a>. A set of includers propagate inclusion lists (ILs), and the attesters uphold that the transactions in the ILs are included in the block via the fork-choice. There is no mechanism for ranking transactions in the ILs, and therefore not viable to uphold CR when the block is full. If IL transactions must be prioritized under full blocks, the builder could simply integrate with includers to propagate ILs containing the transactions it wishes to include in the block.</p> <p>To uphold CR also under full blocks, it is necessary to have a framework for which transactions to include and exclude. This EIP specifies a uniform price auction over inclusion lists (UPIL), which ranks transactions by their offered <code>ranking_fee_per_gas</code>, derived from their specified <code>max_ranking_fee_per_gas</code>. If a block is full, no transaction is allowed to displace an IL transaction with a higher <code>ranking_fee_per_gas</code>, as long as the displaced IL transaction passes regular inclusion criteria. All included transactions pay the "marginal" ranking fee, corresponding to the highest ranking fee offered by a valid IL transaction excluded from the block, and this fee is burned. If no IL transaction was excluded, the marginal ranking fee is <code>0</code>. In essence, the existing base fee prices inter-block contention, while UPIL is an auction mechanism that relies on ILs to impose a secondary base fee that prices intra-block contention.</p> <p>Ethereum is currently pursuing scaling by tracking gas consumption across separate resources, allowing each resource to be consumed at its maximum capacity. With a multidimensional approach, it can become cheaper to "stuff the block" such that it is full in any dimension by creating "dummy transactions" that only consume one specific resource. This degrades the CR of FOCIL, since builders can ignore ILs in full blocks. In the multidimensional <a href="https://wg-eips.ritovision.com/7706/">EIP-7706</a> and <a href="https://wg-eips.ritovision.com/7999/">EIP-7999</a>, the degradation of CR can become rather pronounced. Base fees are set individually per resource and may become very low, depending on whether reserve prices in the style of <a href="https://wg-eips.ritovision.com/7918/">EIP-7918</a> are adopted or not. Furthermore, if the builder varies which resource that is full across blocks, there is no longer an exponentially increasing cost to keep a transaction censored block after block.</p> <p>The strong CR of UPIL is particularly suitable under a multidimensional fee market, but can be beneficial under any fee market. Some transactions are time-sensitive: what matters is inclusion within a set time frame. Sometimes, that time frame consists of just a few or a single block. UPIL guarantees inclusion in the next block for a transaction offering a sufficient ranking fee, assuming includers and attesters do their duties. This puts includers and the builder on a more equal footing. Furthermore, the lack of ranking in FOCIL gives builders an incentive to amass private transactions to facilitate low-cost temporary censorship, which could negatively affect the public mempool. However, both FOCIL and UPIL also have properties that strengthen the public mempool.</p> <h2 id="specification">Specification</h2> <h3 id="new-transaction-format-and-ranking-fee">New transaction format and ranking fee</h3> <p>A new field <code>max_ranking_fee_per_gas</code> is added to a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction with <code>TransactionType</code> = <code>RANK_TX_TYPE</code>. The <code>TransactionPayload</code> for this transaction is:</p> <p>&lt;-- TODO --&gt;</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-keyword"> TODO</span><span class="z-comment">: To be defined after scheduling this EIP relative to EIP-7999 and EIP-8011, etc.</span></span></code></pre> <p>The ranking is performed on the <code>ranking_fee_per_gas</code>, corresponding to the maximum ranking fee that the transactor was willing to pay under the current base fee. Older transaction formats use their entire headroom for their offered ranking fee, whereas the new format can cap the ranking fee using the <code>max_ranking_fee_per_gas</code> field.</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_max_fee</span><span>(</span><span class="z-variable z-parameter z-function">tx</span><span>:</span><span> Transaction</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> is_legacy</span><span>(</span><span>tx</span><span>.</span><span>type</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> tx</span><span>.</span><span>gas_price</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> tx</span><span>.</span><span>max_fee_per_gas</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_ranking_fee</span><span>(</span><span class="z-variable z-parameter z-function">tx</span><span>:</span><span> Transaction</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-support"> int</span><span>:</span></span> <span class="giallo-l"><span> ranking_fee_per_gas</span><span class="z-keyword"> =</span><span> get_max_fee</span><span>(</span><span>tx</span><span>)</span><span class="z-keyword"> -</span><span> block</span><span>.</span><span>base_fee_per_gas</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 new RANK_TX_TYPE can set a cap to the offered ranking fee</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> tx</span><span>.</span><span>type</span><span class="z-keyword"> ==</span><span class="z-constant"> RANK_TX_TYPE</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> min</span><span>(</span><span>tx</span><span>.</span><span>max_ranking_fee_per_gas</span><span>,</span><span> ranking_fee_per_gas</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> ranking_fee_per_gas</span></span></code></pre> <p>The ranking fee does not impose ordering constraints within the block, and only governs inclusion. The alternative specifications section discusses the options that exist for computing the <code>ranking_fee_per_gas</code> in various transaction formats, including the option to not implement a new transaction format at all.</p> <h3 id="transaction-processing">Transaction processing</h3> <p>The builder specifies in the block body the <code>marginal_ranking_fee_per_gas</code> that all transactions must pay. The full <code>inclusion_fee_per_gas</code> corresponding to <code>base_fee_per_gas + marginal_ranking_fee_per_gas</code> is covered before the priority fee. A valid transaction must have <code>max_fee_per_gas &gt;= inclusion_fee_per_gas</code> and <code>RANK_TX_TYPE</code> transactions must also have <code>max_ranking_fee_per_gas &gt;= marginal_ranking_fee_per_gas</code>. Thus, under <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a>, transaction processing is changed as follows:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">for</span><span> unnormalized_transaction</span><span class="z-keyword"> in</span><span> transactions</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"> After this existing check...</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> transaction</span><span>.</span><span>max_fee_per_gas</span><span class="z-keyword"> &gt;=</span><span> transaction</span><span>.</span><span>max_priority_fee_per_gas</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"> ..check that the transactor is willing to pay the marginal ranking fee</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> transaction</span><span>.</span><span>type</span><span class="z-keyword"> ==</span><span class="z-constant"> RANK_TX_TYPE</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> block</span><span>.</span><span>marginal_ranking_fee_per_gas</span><span class="z-keyword"> &lt;=</span><span> transaction</span><span>.</span><span>max_ranking_fee_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"> ..derive the inclusion fee per gas and perform checks</span></span> <span class="giallo-l"><span> inclusion_fee_per_gas</span><span class="z-keyword"> =</span><span> block</span><span>.</span><span>base_fee_per_gas</span><span class="z-keyword"> +</span><span> block</span><span>.</span><span>marginal_ranking_fee_per_gas</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> transaction</span><span>.</span><span>max_fee_per_gas</span><span class="z-keyword"> &gt;=</span><span> inclusion_fee_per_gas</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"> ..cap the priority fee by the inclusion fee instead of the base fee</span></span> <span class="giallo-l"><span> priority_fee_per_gas</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span>transaction</span><span>.</span><span>max_priority_fee_per_gas</span><span>,</span><span> transaction</span><span>.</span><span>max_fee_per_gas</span><span class="z-keyword"> -</span><span> inclusion_fee_per_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"> ..and adjust the line calculating the effective gas price</span></span> <span class="giallo-l"><span> effective_gas_price</span><span class="z-keyword"> =</span><span> priority_fee_per_gas</span><span class="z-keyword"> +</span><span> inclusion_fee_per_gas</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre> <p>The inclusion fee is never distributed and thus burned. Note that legacy transactions are assigned <code>max_fee_per_gas = gas_price</code> and <code>max_priority_fee_per_gas = gas_price</code> as part of a prior normalization step. The existing assert statement</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">assert</span><span> transaction</span><span>.</span><span>max_fee_per_gas</span><span class="z-keyword"> &gt;=</span><span> block</span><span>.</span><span>base_fee_per_gas</span></span></code></pre> <p>is redundant and is removed.</p> <h3 id="altered-focil-post-execution-inclusion-check">Altered FOCIL post-execution inclusion check</h3> <p>The post-execution inclusion check of <a href="https://wg-eips.ritovision.com/7805/">EIP-7805</a> is altered as outlined in the figure. Orange squares represent the original FOCIL checks, where "No" always leads to jumping to the next transaction. Blue squares are the checks added in UPIL that account for ranking. The first black square of step (1) contains only peripheral modifications that do not alter the intended outcome of the inclusion check.</p> <p><img src="https://wg-eips.ritovision.com/8046/./assets/1.png" alt="Figure 1" /></p> <p>The <code>ranking_fee_per_gas</code> is first computed for each transaction <code>X</code> in the block via <code>get_ranking_fee(X, B)</code>. Then, for each transaction <code>T</code> in ILs, the check performs three steps.</p> <hr /> <p>The original step (1)</p> <blockquote> <p>(1) Check whether <code>T</code> is present in <code>B</code>. If <code>T</code> is present, then jump to the next transaction, else continue with next step.</p> </blockquote> <p>is replaced with the following:</p> <p>(1) If <code>T</code> is present in <code>B</code>, or <code>get_max_fee(T) &lt; block.base_fee_per_gas</code>, or <code>T</code> fails static validity, then skip <code>T</code> and jump to the next IL transaction, else continue to the next step.</p> <hr /> <p>The original step (2):</p> <blockquote> <p>(2) Check whether <code>B</code> has enough remaining gas to execute <code>T</code>. If <code>T.gas</code> &gt; <code>gas_left</code>, then jump to the next transaction, else continue with next step.</p> </blockquote> <p>is replaced with the following:</p> <p>(2a) Check whether <code>B</code> has enough remaining gas to execute <code>T</code>: <code>gas_left &gt;= T.gas_limit</code>. If so, continue to (3a); otherwise, continue to (2b) potentially followed by (3b).</p> <p>(2b) Check whether <code>B</code> would have had enough remaining gas to execute <code>T</code>, if <code>T</code> was included together with only higher-ranked transactions in <code>B</code>. First compute <code>T.ranking_fee_per_gas = get_ranking_fee(T, B)</code> and then compute <code>gas_ranked_left(T)</code> as the remaining gas after subtracting the <code>gas_used</code> of all transactions of the block with a higher <code>ranking_fee_per_gas</code> than <code>T</code> from <code>B.gas_limit</code>. For transactions with the same <code>ranking_fee_per_gas</code>, included transactions in <code>B</code> are considered higher-ranked than not-included IL transactions. If <code>gas_ranked_left(T) &gt;= T.gas_limit</code>, continue to (3b); otherwise jump to the next IL transaction.</p> <hr /> <p>The original step (3):</p> <blockquote> <p>(3) Validate <code>T</code> against <code>S</code> by checking the nonce and balance of <code>T.origin</code>.</p> </blockquote> <p>is replaced with the following:</p> <p>(3a) Validate <code>T</code> against <code>S</code> by checking the nonce and balance of <code>T.origin</code>.</p> <p>(3b) Validate <code>T</code> against <code>S</code> by checking the nonce of <code>T.origin</code>. Further validate <code>T</code> against the balance of the origin account by applying the standard pre-execution fundability check to a conservative balance that ignores all increases and counts all decreases to <code>T.origin</code> at the completion of each executed transaction of the block. Intermediate increases or decreases during the execution of a transaction are not tracked in isolation.</p> <p>Step (3a) and (3b) conclude as previously:</p> <blockquote> <p>If <code>T</code> is invalid, then continue to the next transaction.</p> <p>If <code>T</code> is valid, terminate process and return an <code>INCLUSION_LIST_UNSATISFIED</code> error.</p> </blockquote> <h3 id="check-on-the-marginal-ranking-fee">Check on the marginal ranking fee</h3> <p>Attesters review excluded IL transactions to confirm that the <code>marginal_ranking_fee_per_gas</code> was set correctly by the builder. If step (2b) indicates that the transaction was outranked, then, before continuing with the next transaction, the transaction is also checked against step (3b), as indicated by a dashed line in the figure. The highest <code>ranking_fee_per_gas</code> among outranked IL transactions from (2b) that pass the valid inclusion check of (3b) must equal <code>marginal_ranking_fee_per_gas</code>. If no outranked IL transaction passes (3b), the <code>marginal_ranking_fee_per_gas</code> must be <code>0</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="updated-inclusion-check">Updated inclusion check</h3> <h4 id="conservative-balance">Conservative balance</h4> <p>The reason for using a conservative balance in (3b) when validating <code>T</code> is to avoid the circular dependencies that can emerge when a transaction is made executable by a lower-ranked transaction. Consider three transactions <code>A</code>, <code>B</code>, and <code>C</code> ranked as <code>A&gt;B&gt;C</code>. Without a conservative balance, <code>A</code> might be funded only if <code>B</code> is included in the block. For example, transaction <code>B</code> might fund <code>A</code>, so without <code>B</code>, <code>A</code> cannot be included, and without <code>A</code>, <code>B</code> cannot be included due to having a lower ranking. There is not enough gas to include both <code>A</code> and <code>B</code>. Including neither and instead including <code>C</code> also fails because the left out <code>B</code> was higher ranked.</p> <p>It is not necessary that <code>B</code> directly funds <code>A</code>. It might very well be the case that <code>B</code> just changes the state such that a higher-ranked transaction <code>X</code> funds <code>A</code>, something that <code>X</code> would not do unless <code>B</code> was run beforehand.</p> <p>It should be noted in (3b) that the transactor is in control of decreases to its ETH balance. Within a block, ETH leaves <code>T.origin</code> only via the transactor’s own signed transactions (value transfers and gas payments) or contracts it has explicitly authorized; the builder cannot manufacture debits. If the transactor’s own debits make <code>T</code> unfundable, and these are included in the block—even if lower-ranked—exclusion is acceptable as a consequence of choices made. After all, the transactor controls the relative order of its own transactions via nonces. Thus, ranking is neither considered for debits nor for credits: debits count regardless of rank, and credits do not count at all.</p> <h4 id="retained-focil-check-in-non-full-blocks">Retained FOCIL check in non-full blocks</h4> <p>The regular FOCIL check is retained in non-full blocks to take advantage of its operational simplicity and since the conservative balance check of UPIL is unnecessarily lenient to the builder whenever an excluded IL transaction would have fit and is funded during processing of the prior transactions in the block. The circular dependencies from the previous subsection do not apply in FOCIL since there is no requirement for transactions in the IL to be included in the block if a transaction outside of the IL uses up the gas. Once (2a) confirms slack, the builder was clearly able to include any existing funding transaction in the block and still include <code>T</code>, so skipping <code>T</code> is an IL violation. UPIL could otherwise also be implemented completely without the old FOCIL checks, to reduce code surface. This corresponds to removing the orange boxes in the figure, retaining the blue boxes.</p> <h4 id="compute-requirements-for-2b-and-3b">Compute requirements for (2b) and (3b)</h4> <p>The new conditions can be checked efficiently by clients.</p> <p>In step (2b), validators can generate a list of the transactions in the block post-execution, sorted according to <code>ranking_fee_per_gas</code>, with an associated list of the cumulative gas consumption. The check for each transaction then only requires keying into the list and extracting the associated gas consumption.</p> <p>For step (3b), the preprocessing consists of tracking a limited set of account-balance-changes during transaction processing. Before processing the block, the client builds an observation set <code>E</code> of <code>T.origin</code> balances for excluded IL transactions. After processing each transaction, it updates <code>E</code>, accounting for all decreases to <code>T.origin</code> balances but ignoring increases. If a block-level access list (BAL) is available that tracks all balance changes, the overall task is further simplified.</p> <p>The check on the <code>marginal_ranking_fee_per_gas</code> (dashed line in the figure) is also trivial. For example, all outranked IL transactions that are otherwise validly includable can have their <code>ranking_fee_per_gas</code> added to an array. After all IL transactions have been reviewed, the maximum entry of this array must equal the specified <code>marginal_ranking_fee_per_gas</code>. If the array is empty, the <code>marginal_ranking_fee_per_gas</code> must instead be <code>0</code>.</p> <h3 id="auction-design">Auction design</h3> <p>The uniform price auction design allows transactors to signal intent (to overcome censorship if the block is full), without actually having to pay more than necessary. A transactor may not know beforehand if they will be censored, and may not wish to pay a very high fee for no reason. There are similarities to the current base fee model. Everyone specifies their willingness to pay, but pays the same minimum fee for inclusion, and this fee is burned. The combination of intents and fairness is attractive. A key difference is that the base fee is a clearing fee tracking contention for blockspace at the inter-block level, whereas the marginal ranking fee is a clearing fee tracking contention for blockspace at the intra-block level (locally for each block).</p> <p>In essence, Ethereum’s current fee mechanism combines a uniform-price base fee that clears congestion across blocks with a first-price priority fee allocating space within each block. What UPIL does is to expand the uniform-price component to the intra-block level by introducing a marginal ranking fee that all included transactions pay equally. Inclusion will thus be governed primarily by protocol-defined uniform clearing (assuming transactions are surfaced in ILs).</p> <p>The <code>max_ranking_fee_per_gas</code> is expected to be set rather low under normal circumstances. Most transactors will not be willing to pay excessively to be included in full blocks, and can instead wait for the next block. However, since the next block will have a 12.5% higher base fee, most transactors will at a minimum set <code>max_ranking_fee_per_gas</code> to 12.5% of the current base fee. The increase in burned fees extracted from transactors in full blocks will be offset by a decrease in priority fees, since the builder no longer controls which transactions that are included (furthermore, includers may also receive other fees, as discussed in the section on includer rewards). The ranking fee will also help with clearing in a fair manner under congestion during sudden spikes in transaction demand. All transactions included in the same block will pay the same ranking fee, with transactions willing to pay the most during a sudden spike included in the first available block. This is arguably an improvement to the UX for Ethereum's users.</p> <p>The reason for burning the marginal ranking fee instead of paying it out to includers is that includers otherwise could have an incentive to engineer artificial congestion in order to raise the fee. This is not trivial, requiring many separate entities to agree to withhold transaction inclusion for consecutive blocks. Various configurations for how to reward includers for their work are outlined in a subsequent section, including the option to distribute the marginal ranking fee to them.</p> <p>The builder may sometimes, via its private orderflow or late-arriving transactions, have some ability to raise the <code>marginal_ranking_fee_per_gas</code> by including transactions that outrank IL transactions. But a builder that raises the marginal ranking fee will also inadvertently reduce the priority-fee headroom for all transactions, since the inclusion fee is subtracted from the max fee before calculating the capped priority fee for all transactions in the block.</p> <h3 id="multidimensional-upil">Multidimensional UPIL</h3> <p>If there are multiple resources, <code>gas_ranked_left(T)</code> is a vector. Using the notation of <a href="https://wg-eips.ritovision.com/7999/">EIP-7999</a>, all <em>conditional</em> resources must then be checked against the corresponding gas limits specified by the analyzed transaction. Transactions that consume any <em>deconditional</em> resource are not subject to the UPIL post-execution check, and insufficient capacity in an <em>unconditional</em> resource is never a valid reason to exclude an IL transaction.</p> <p>Thus, under multidimensional UPIL, the transaction is checked against <code>gas_ranked_left(T)</code> over the conditional resources only, in both (2a) and (2b). However, given the strong CR of UPIL, it would be perfectly feasible to classify calldata as conditional instead of using the unconditional classification of <a href="https://wg-eips.ritovision.com/7999/">EIP-7999</a>.</p> <h3 id="censorship-resistance-under-focil-and-upil">Censorship resistance under FOCIL and UPIL</h3> <p>This subsection offers a comparison of the censorship resistance achieved under FOCIL and UPIL. The premise is a builder seeking to censor a transaction under different fee market designs. We begin by rudimentarily quantifying the cost $C_i$ of censoring a transaction in block $i$ ($i=0$ for the first censored block) as:</p> <p>$C_i = g_df_b (1+r)^i + g_df_r + m(i, f_r).$</p> <p>In this equation, $g_d$ is the gas that the builder must pay by creating so-called "dummy transactions" to fill the block, $f_b$ is the base fee for that gas, $r$ is the rate by which the base fee increases in full blocks (i.e., 12.5%), $f_r$ is the <code>ranking_fee_per_gas</code> of the censored transaction, and $m(i, f_r)$ is the MEV (including priority fees) forgone when forced to exclude pending transactions with a lower ranking than the censored transaction for block $i$ (the opportunity cost).</p> <h4 id="multidimensional-fee-market">Multidimensional fee market</h4> <p>Under a multidimensional fee market envisioned in <a href="https://wg-eips.ritovision.com/7706/">EIP-7706</a> and <a href="https://wg-eips.ritovision.com/7999/">EIP-7999</a>, the base fee is set individually per resource to maximize utilization of blockspace. As noted in <a href="https://wg-eips.ritovision.com/7999/">EIP-7999</a>, the base fee may therefore sometimes become very low for a resource, meaning that the cost of generating dummy transactions to fill the block also becomes very low. In a potential multidimensional FOCIL, it is then only necessary that one resource used by a transaction is filled to censor that transaction. Furthermore, while the base fee will increase for the resource that was filled with dummy transactions, the base fees of all other resources will not. These base fees will instead vary based on gas consumed by regular transactions included in the block. The builder can potentially vary which resource it fills the block for, to keep any base fee from exploding during prolonged censorship. Define $\mathbf{f_b}$ as the vector of base fees. The outcome for FOCIL and UPIL respectively is:</p> <p><strong>FOCIL:</strong> The cost of censorship for the first block is $C_0 = g_d\min(\mathbf{f_b})$, and thus $C_0 \to 0$ if $\min(\mathbf{f_b}) \to 0$. The cost can potentially be kept close to 0 even under continued censorship, depending on the distribution of the equilibrium base fees under no censorship and the fee elasticities of demand.</p> <ul> <li>There is no ranking fee (thus $g_df_r \to 0$) and there is no opportunity cost because the builder can always include lower-ranked transactions when it fills the block (thus $m(i, f_r) \to 0$).</li> <li>The builder can switch between resources it fills, thus potentially keeping its overall costs contained even under continued censorship. This depends on prevailing fee elasticities and equilibrium base fees under no censorship.</li> <li>If there is just one base fee that is low initially, then that base fee will rise (albeit from a low starting point), if the builder does not assume the opportunity cost $m(i, f_r)$ of excluding other transactions. Fee elasticities are relevant also in this case, because the rise in a single base fee should moderately reduce demand for all other resources as the transactor reviews the total cost.</li> </ul> <p><strong>UPIL:</strong> The cost of censorship for the first block is $C_0 = g_d\min(\mathbf{f_b}) + g_df_r + m(i, f_r)$, and thus $C_0 = g_df_r + m(i, f_r)$ if $\min(\mathbf{f_b}) \to 0$. This cost can be hundreds or thousands of times higher than whatever ranking fee the censored transaction specifies, and it rises with continued censorship due to the opportunity cost of keeping all pending transactions with a lower ranking fee that consume the filled resource out of the block.</p> <ul> <li>If the transactor specifies a ranking fee $f_r$ that exceeds the ranking fee of existing transactions in the mempool, the censoring builder will need to create dummy transactions up to the entire gas limit of the resource it is targeting. This can be specified as $g_d = g_l-g_r(T)$, where $g_r(T)$ is the gas already consumed by the censored transaction. Thus, the censoring builder must pay $f_r(g_l-g_r(T))$. To censor a transaction consuming 100k gas when the gas limit is 60M in the filled resource, the builder must pay $(60-0.1)/0.1 = 599$ times more than what the transactor was willing to pay for inclusion. As the gas limit expands, the relative cost of censorship increases. It should here be noted that the transactor will not need to pay its high offered ranking fee if it is indeed censored, and would after censorship concludes only pay according to the <code>marginal_ranking_fee_per_gas</code> of the subsequent block.</li> <li>The opportunity cost from censorship is also higher under UPIL than FOCIL, since no pending transaction with a ranking fee $f'_r&lt;f_r$ that consumes the filled resource can be included if the censored transaction is excluded.</li> </ul> <h4 id="current-fee-market">Current fee market</h4> <p>We now discuss the situation under the current fee market with a single base fee (ignoring the blob resource). In this case, the base fee term of the previous equation does not vanish. If the builder does not use the "slow transaction" strategies outlined in the next subsection, the outcome for FOCIL and UPIL respectively is:</p> <p><strong>FOCIL:</strong> The builder must cover the base fees: $g_df_b(1+r)^i$ of block $i$. The required amount of purchased gas $g_d$ will in the average case be $g_d=g_l/2$. However, there will be many instances where pending transactions in the public mempool or via private orderflow consume more than $g_l/2$. Censorship for one or two blocks can therefore be inexpensive even if pending transactions do not completely fill the block. The $(1+r)^i$ term grows by 12.5% per block, doubling in six blocks, and pending transactions are quickly depleted. Therefore, censorship becomes costly rather quickly: FOCIL ensures that transactions are included within a limited number of blocks if includers do their duties, but not in the first few blocks.</p> <p><strong>UPIL:</strong> The builder must cover the base fee, the ranking fee, and forego pending transactions, thus suffering a cost of $g_df_b(1+r)^i + g_df_r + m(i, f_r)$. The required gas $g_d$ is higher than in FOCIL, and—just as for the multidimensional fee market—potentially the full gas limit, because the builder cannot rely on pending transactions with a lower ranking fee for block stuffing. Due to the $g_df_r$ term, the cost for censoring a transaction for a single block can easily become a thousand times higher than whatever the transactor was willing to pay for inclusion, just as under the multidimensional fee market.</p> <h4 id="current-fee-market-with-slow-transactions">Current fee market with "slow transactions"</h4> <p>Note the importance of pending transactions for sidestepping the ILs in FOCIL: the cost for covering base fees when filling the block provides the CR. A strategy the builder could use to reduce the cost of censorship over a few blocks is to amass "slow transactions" through private orderflow—transactions that do not have to execute immediately. These are transactions for which the transactor is willing to substitute speed for some other benefit, predominantly rebated fees, but potentially also convenience or MEV protection. The builder (or realistically a MEV-protecting RPC endpoint) guarantees (trustfully) inclusion within some set time frame, and that the total cost for the transactor will be below the cost that would have been incurred given the base fee at the time that the tx is sent to the builder. The concept can be integrated as:</p> <p>$C_i = g_df_b ((1+r)^i-s) + g_df_r + m(i, f_r).$</p> <p>Here, $s$ represents the cost reduction factor relative to the initial base fee. This models a scenario where the builder has stored and promised to include blockspace-filling transactions at a fixed discount. If the rebate to transactors for slow transactions is 10%, then $s=0.9$, with the cost of censoring the first block in FOCIL reduced by 90%. Such a strategy can thus be useful for censoring a couple of blocks in a row. After around 5 blocks or less, $(1+r)^i - s &gt; 1$, meaning that the cost is the same as the cost of censoring the first block without slow transactions. Since the supply of slow transactions would likely be limited, the strategy cannot be applied too often.</p> <p>Slow transactions must be propagated privately to remain useful, and reach their full economic potential by contributing to censorship. When the value in sidestepping ILs exceeds the costs of facilitating slow transactions, the proportion of transactions propagated p2p may thus fall. On the other hand, the transactions that indeed are propagated p2p are upon IL listing guaranteed inclusion in non-full blocks, and therefore do not need to pay priority fees. The effect of FOCIL on the public mempool may therefore be negative or positive depending on the demand for censorship from builders. Alternatively, the protocol could facilitate "trustless slow transactions" by letting builders sponsor transactions offering a max fee below the prevailing base fee, for example by charging the base fee jointly for all transactions at the end of the block.</p> <p>Under UPIL, slow transactions do not contribute meaningfully to censorship due to the $g_df_r + m(i, f_r)$ terms, and there is furthermore no rationale for paying a priority fee upon listing, further strengthening the public mempool.</p> <h4 id="multidimensional-gas-metering">Multidimensional gas metering</h4> <p>Under multidimensional gas metering in <a href="https://wg-eips.ritovision.com/8011/">EIP-8011</a>, the situation is closer to the current fee market than the multidimensional fee market. There is still just one base fee, so the cost of censoring a transaction for a sustained period rises exponentially. Censorship may become slightly cheaper than currently, due to the equilibrium reduction in the base fee with a maintained slack in the block relative to the most consumed resource. On the other hand, utilization of slow transactions may become slightly less efficient.</p> <p>In the current fee market, half the gas limit $g_l/2$ is consumed in the average block. Transactors spend $f_bg_l/2$ on average and the cost of censoring a block via dummy transactions is also $f_bg_l/2$. Under multidimensional gas metering, $g_l/2$ is consumed on average individually for the most used resource. Transactors however consume the higher $xg_l/2$ amount of gas on average over all resources, while the gas required for censorship remains at $g_l/2$ (filling up the most consumed resource). Here $x$ corresponds to the scaling factor achieved when gas of different resources can be consumed in parallel, a scaling factor that might end up in the range 2-4. Keeping demand and $g_l$ fixed, the base fee $f_b$ will fall, reducing the cost $f_bg_l/2$ of censoring a block in the average case. Had we instead simply increased the gas limit, CR would have been affected differently, because then the cost of censorship would also have increased according to the increase in $g_l$, such that the censoring builder would have needed to purchase more dummy transactions in the average case.</p> <h4 id="transaction-inclusion-and-mev">Transaction inclusion and MEV</h4> <p>In FOCIL, including an existing transaction is always possible without raising the inclusion fee, regardless of whether this means that an IL transaction must be excluded or not. In UPIL, if the block is full, including an existing transaction over an IL transaction willing to pay more is treated as censorship. Ostensibly, MEV and censorship are not separate topics: in many scenarios, censorship is also MEV. To displace the IL transaction offering the lowest ranking fee among IL transactions in the block, the new transaction must pay at least the ranking fee offered by that IL transaction.</p> <p>Since the builder cannot freely decide which of the pending transactions to include in UPIL, it might not be able to extract all MEV from pending transactions that it could have in FOCIL. It lacks the ability to exclude IL transactions at will from full blocks. Once a transaction is in an IL, its inclusion is guaranteed if it is willing to pay at least the same as the smallest offer by other transactions that go into the block. This levels the playing field between includers and the builder, giving the includer the opportunity to offer real inclusion guarantees to transactors. In FOCIL, the <em>protocol</em> offers real inclusion guarantees, <em>eventually</em>. In UPIL, the <em>includer</em> offers real inclusion guarantees, <em>immediately</em>.</p> <p>Some includers might charge transactors for their services in FOCIL, but the value of the provided services is further strengthened in UPIL. MEV might thus shift from the builder to includers in the form of fees for listing the transaction. A transaction listed by an IL has no need to pay a priority fee for inclusion. Indeed, we may even see "IL-builders" that collate full ILs as a service both in FOCIL and UPIL. Some MEV will also shift to the protocol in the form of burned ranking fees. It is natural to then consider what options the builder has, to retain some power over transaction inclusion. It may of course try to bribe includers to not list transactions. A problem for a builder trying to stay competitive is that this requires bribing all includers, and that any includer remaining faithful to its duties can earn a greater reward from transactors when others take the bribe, particularly in UPIL.</p> <p>There are nuances to the design that need careful consideration before adoption. Something to be attentive to is the effect of burning the marginal ranking fee, given that avoiding the burn is not a zero-sum outcome for builders and includers. This is further discussed in the next section.</p> <h3 id="alternative-specifications-for-rewarding-includers">Alternative specifications for rewarding includers</h3> <p>Transactors might wish to reward includers in both FOCIL and UPIL for surfacing their transaction in an IL. They may recognize that the space in each IL is limited, meaning includers sometimes need to prioritize between available transactions. They might also fear that builders could bribe includers to not fulfill their duties, so that the builder can exclude unwanted transactions. As discussed previously, UPIL strengthens the position of includers, giving them in some sense equal power to the builder in deciding which transactions enter the block. For this reason, the case for rewarding includers is also stronger: an IL transaction does not require a priority fee to be included, even in full blocks—it must be included if it offers a higher ranking fee than competing transactions.</p> <h4 id="out-of-protocol-inclusion-fees">Out-of-protocol inclusion fees</h4> <p>If there is no in-protocol reward mechanism, individual staking service providers might start offering (trustfully) to list transactions in their next assigned IL slot, against a small fee. We might also see public orderflow of includable transactions offering a certain reward for inclusion, with includers and transactors coming to agreement via a third-party software. This can improve the UX, but also has the potential to become a centralization vector.</p> <h4 id="in-protocol-inclusion-fee-sources">In-protocol inclusion fee sources</h4> <p>It is possible that the protocol can be of direct assistance. Three fee sources will first be reviewed, and relevant distribution mechanisms then explored.</p> <p><strong>Includer fee:</strong> One example is to allow transactions to specify an includer fee via a new field <code>max_includer_fee_per_gas</code>. To split the <code>max_includer_fee_per_gas</code> and the <code>max_priority_fee_per_gas</code> when they are capped by the <code>max_fee_per_gas</code>, the "aggregate-cap-divide" method outlined in the "pay-as-you-bid" subsection is the recommended approach. Alternatively, it is possible to distribute only the includer fee or the priority fee, depending on if the transaction was listed in an IL or not, and never both. The builder must then specify whether each transaction originated from an IL or not (at the transaction or IL level), and attesters vote against the block if the builder fails to make such an assignment when they observed the transaction in a timely IL.</p> <p><strong>Priority fee:</strong> It is possible to instead let the includers receive the priority fee if they list a transaction. The builder will have no choice but to include a transaction once it is listed by an includer, and the priority fee then serves little purpose. From the transactor's perspective, giving a priority fee to the builder for an IL transaction is a wasteful expenditure. Once again, with this option the builder must specify whether each transaction originated from an IL or not.</p> <p><strong>Marginal ranking fee:</strong> The marginal ranking fee can be distributed to includers instead of being burned. As discussed previously, one potential downside of this is the increase in rewards for engineering contention—in collaboration with builders—by first withholding transactions, and then releasing all transactions in the same block.</p> <p>The question is whether includers will be able to engineer such contention, given the coordination problem at hand: withholding transactions over several slots, with several slots' includers working together, where anyone breaking the cartel could reap higher rewards from transactors paying includers for their services. Transactors might also end up setting lower ranking fees if such an approach becomes systematic, and most ranking fees will likely anyway be in the region of 12.5% of the base fee. Finally, we do not see builders coordinating to bring down the base fee in order to reap higher priority fees today (at the same time, the control over the priority fee is indirect, and they do not directly attain the base fee).</p> <p>A potential benefit of distributing the marginal ranking fee to includers is that if the builder wishes to bribe includers to avoid contention (in order to bring up priority fees), then includers taking such a bribe would miss out on rewards for that contention (in addition to any rewards they may already miss out on from includer priority fees).</p> <h4 id="mechanisms-for-distributing-inclusion-fees-in-protocol">Mechanisms for distributing inclusion fees in-protocol</h4> <p>Four options for how to distribute the fee from any of the three in-protocol inclusion fee sources listed in the previous section will now be reviewed:</p> <p><strong>(1) Keyed distribution:</strong> Let transactors set one or several keys, with each key linking to one includer (i.e., validator ID) or to many includers (e.g., enabling all validators of an SSP to associate one key to all its validators). The protocol can then ensure that the rewards are distributed only to validators represented by a key, if it listed the transaction. This means that transactions shared with an includer privately still can use an in-protocol fee distribution without risking dilution. Options (2)-(4) below can be applied when the transactor does not provide a key or when the keyed includer(s) failed to list the transaction.</p> <p><strong>(2) Individual distribution:</strong> Split the fee between all includers listing a transaction. All includers then have an incentive to list a transaction, with the incentive being stronger if other includers have ignored it. It may however lead to unnecessary duplicate listings, since there is an incentive to list transactions even after they have been observed in another IL. It may also lead includers to integrate with builders to propagate the optimal IL by leveraging the builder's last look.</p> <p><strong>(3) Seniority distribution:</strong> Use a "seniority waterfall" rule. The transaction hash is combined with includer validator IDs to assign an order of seniority by which each includer has the right to the full includer fee. If a transaction's senior includer lists it, there is no purpose for a less senior includer to also list it. The idea is to promote a broader coverage while maintaining fairness. The mechanism will however not remove all duplicates, as a more senior includer will still list a transaction already listed by a less senior includer. It is straightforward to combine (1) with (3), by giving keyed includers the highest seniority, with remaining includers assigned a seniority based on the transaction hash. This could also prevent transaction hash grinding in the case when some senior includers are more reliable than others. Under the priority fee redistribution rule, the builder is in essence appended to the waterfall, having the lowest seniority.</p> <p>To further reduce duplicates, a potential extension could allow includers to stagger their inclusion list so that they first broadcast transactions they are the most senior includer for, and then append the list with transactions they are less senior for or that arrive late. This can also increase the includer's expected value (EV) since an early broadcast increases margins and the late broadcast allows for better coverage. Another way to increase EV under this rule is to combine it with (4) below. Each partial list must have timeliness observed in isolation, and the rules for IL equivocation must be amended to allow append operations.</p> <p><strong>(4) Collective distribution:</strong> Distribute the includer fee collectively to all includers. There is then no need to keep track of who propagated which transaction in which IL. It also serves to promote independence of includers. Builders cannot help includers to extract a relatively higher proportion of the ranking fee by constructing an optimal IL for them from their last look. Includers are further encouraged to facilitate as broad coverage as possible, given that there are no incentives to propagate a (high-paying) transaction if one of the other includers already propagates it. This means that some includers can pivot to propagating their ILs early, while others observe and select late or missed transactions.</p> <p>A downside is that includers are not incentivized individually to do a good job, and gain individually only 1/<code>IL_COMMITTEE_SIZE</code> of any ranking fee of a transaction they uniquely include. The point however is that the collective distribution alters the meaning of "doing a good job", aligning protocol design goals with includer incentives.</p> <p>Builders may try to bribe includers to not include transactions. If an includer will receive 1/<code>IL_COMMITTEE_SIZE</code> of any collective rewards for <em>not</em> including a transaction that eventually is not surfaced by any IL, then they may elect to leave it out to preserve space for other transactions. However, the builder would then also forego a sum corresponding to the entire collective rewards by paying out such bribes to the includers. In the setup where the priority fee is distributed to includers if they surface a transaction, the builder would thus need to forego the entire priority fee it stands to receive.</p> <p>However, due to the gradual construction of the aggregate IL, the builder can offer higher bribes than 1/<code>IL_COMMITTEE_SIZE</code> to the last remaining includers, to keep some transactions not yet included out of the IL aggregate. The last remaining includer that spots a late transaction might be able to choose between including it to receive 1/<code>IL_COMMITTEE_SIZE</code> of the priority fee, or to receive 1/2 of a conditional priority fee as a bribe to not include it.</p> <h3 id="alternative-specifications-for-the-auction-and-transaction-format">Alternative specifications for the auction and transaction format</h3> <h4 id="omit-the-new-transaction-format-with-its-added-ranking-fee-field">Omit the new transaction format with its added ranking fee field</h4> <p>Existing transaction formats are ranked using <code>max_fee_per_gas</code>. This may be sufficiently expressive, with the new transaction type omitted. The benefit is that it simplifies the UX. Transactors may not care about how much they have to pay to specifically cover the <code>marginal_ranking_fee_per_gas</code>—they have already specified how much they are willing to pay for inclusion in total with the <code>max_fee_per_gas</code>. It also simplifies the developer experience, since we do not need to change the transaction format.</p> <p>A potential downside is that transactors cannot differentiate between how high contention fees they are willing to pay to cover the base fee and to cover the marginal ranking fee in full blocks. The builder has some control over the marginal ranking fee: if there are transactions outside of the ILs that are willing to pay a higher fee for inclusion than the IL transactions, then it may or may not elect to include those transactions. This influences the marginal ranking fee which is determined by the highest offered ranking fee of an excluded IL transaction. It is more difficult for the builder to control the base fee. Transactors wishing to limit their ranking fees, while at the same time giving ample room for the base fee to rise before inclusion, may therefore find that older transaction formats do not offer sufficient expressiveness.</p> <h4 id="pay-as-you-bid-auction">Pay-as-you-bid auction</h4> <p>Two alternative pay-as-you-bid auction designs will now be highlighted. The first is that transactors always pay their offered ranking fee upon inclusion. In this case, there is no risk that the includers or the builder engineer contention for blockspace to drive up the price, and the full ranking fee is distributed to includers instead of being burned, using the collective method previously described. The post-execution check stays the same as in the main specification, with the only difference that the check on outranked IL transactions concerning the <code>marginal_ranking_fee_per_gas</code> (dashed line in the figure) is removed.</p> <p>Transaction processing is altered to, e.g., facilitate payment to includers. The split between the specified <code>max_ranking_fee_per_gas</code> and <code>max_priority_fee_per_gas</code> can be done in two ways. Either the ranking fee takes precedence over the priority fee as previously, or the two are given equal precedence. In the first case, the same strategy as in the main specification can be used. In the second case, the two fees can first be summed into a single <code>max_payout_fee_per_gas</code>, and the capped <code>payout_fee_per_gas</code> then distributed proportionally to the size of the original max ranking/priority fees.</p> <p>Additionally, the builder is given the ability to set a <code>priority_fee_shift_per_gas</code> parameter for each transaction to allow transactions without a sufficient <code>ranking_fee_per_gas</code> to become eligible for inclusion in the block. We can envision a scenario where the builder otherwise integrates deeper with transactors to help them set the optimal ranking fee anyway. Such an integration could have detrimental effects on the builder competitive landscape, and it is therefore desirable to allow the builder—who has the last look when building blocks—to raise the ranking fee as it sees fit in a trustless manner. This means that many transactors will elect to just provide a priority fee, and that there is limited downside for transactors using older transaction types.</p> <p>If a transactor believes that the builder may leave their transactions out of the block, then it is still well served by providing a ranking fee and propagating the transaction publicly so that it can be surfaced by an IL. The builder needs to boost all transactions up to the ranking fee of the transaction it wishes to exclude from the block, and a modest ranking fee can therefore be sufficient to ensure inclusion. The spec shows the ranking fee taking precedence and omits some overflow checks:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">for</span><span> i</span><span>,</span><span> unnormalized_transaction</span><span class="z-keyword"> in</span><span class="z-support"> enumerate</span><span>(</span><span>transactions</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"> After this existing check...</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> transaction</span><span>.</span><span>max_fee_per_gas</span><span class="z-keyword"> &gt;=</span><span> transaction</span><span>.</span><span>max_priority_fee_per_gas</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"> ..Optionally shift a proportion of the priority fee over to the ranking fee</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> block</span><span>.</span><span>priority_fee_shift_per_gas</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> &lt;=</span><span> transaction</span><span>.</span><span>max_priority_fee_per_gas</span></span> <span class="giallo-l"><span> max_priority_fee_per_gas</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>max_priority_fee_per_gas</span><span class="z-keyword"> -</span><span> block</span><span>.</span><span>priority_fee_shift_per_gas</span><span>[</span><span>i</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"> ..then fill in order of: base fee, ranking fee, priority fee</span></span> <span class="giallo-l"><span> max_shifted_ranking_fee_per_gas</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>max_ranking_fee_per_gas</span><span class="z-keyword"> +</span><span> block</span><span>.</span><span>priority_fee_shift_per_gas</span><span>[</span><span>i</span><span>]</span></span> <span class="giallo-l"><span> ranking_fee_per_gas</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span>max_shifted_ranking_fee_per_gas</span><span>,</span><span> transaction</span><span>.</span><span>max_fee_per_gas</span><span class="z-keyword"> -</span><span> block</span><span>.</span><span>base_fee_per_gas</span><span>)</span></span> <span class="giallo-l"><span> inclusion_fee_per_gas</span><span class="z-keyword"> =</span><span> block</span><span>.</span><span>base_fee_per_gas</span><span class="z-keyword"> +</span><span> ranking_fee_per_gas</span></span> <span class="giallo-l"><span> priority_fee_per_gas</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span>max_priority_fee_per_gas</span><span>,</span><span> transaction</span><span>.</span><span>max_fee_per_gas</span><span class="z-keyword"> -</span><span> inclusion_fee_per_gas</span><span>)</span></span> <span class="giallo-l"><span> effective_gas_price</span><span class="z-keyword"> =</span><span> inclusion_fee_per_gas</span><span class="z-keyword"> +</span><span> priority_fee_per_gas</span></span> <span class="giallo-l"></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"> ..after refunding the transactor as normal, the includer fee is computed</span></span> <span class="giallo-l"><span> includer_fee</span><span class="z-keyword"> =</span><span> gas_used</span><span class="z-keyword"> *</span><span> ranking_fee_per_gas</span><span class="z-keyword"> //</span><span class="z-constant"> IL_COMMITTEE_SIZE</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> ..balances of the `IL_COMMITTEE_SIZE` includers increased</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> j</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span class="z-constant">IL_COMMITTEE_SIZE</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>account</span><span>(</span><span>block</span><span>.</span><span>includer</span><span>(</span><span>j</span><span>)</span><span>)</span><span>.</span><span>balance</span><span class="z-keyword"> +=</span><span> includer_fee</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> ..and the priority fee is distributed to the builder just as in EIP-1559</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>account</span><span>(</span><span>block</span><span>.</span><span>author</span><span>)</span><span>.</span><span>balance</span><span class="z-keyword"> +=</span><span> gas_used</span><span class="z-keyword"> *</span><span> priority_fee_per_gas</span></span></code></pre> <p>The consensus layer (CL) constructs a list of execution-layer (EL) payout addresses for the slot, ordered by IL committee index, and provides it to the EL via a new engine API call: <code>engine_setIncluderPayoutsV1</code>. For committee members with <code>0x00</code> credentials, the CL inserts the zero address <code>0x000...</code>, thus burning these rewards.</p> <h4 id="pay-as-you-bid-auction-using-only-priority-fee">Pay-as-you-bid auction using only priority fee</h4> <p>A second alternative is to let the priority fee act as a ranking fee in a pay-as-you-bid auction. The priority fee is distributed collectively to includers if it was surfaced by at least one inclusion list. Otherwise it is distributed to the builder. <em>Only</em> priority fees distributed to the includers count towards the transaction's ranking.</p> <p>The builder specifies whether an included transaction was surfaced by an IL via a bitfield <code>IL_transaction</code> in the payload body, of equal length to the number of transactions. For all transactions where <code>IL_transaction[i]=FALSE</code>, the attesters check that they are not in any observed timely ILs, and otherwise return <code>INCLUSION_LIST_UNSATISFIED</code>. For these transactions, the builder can also apply the <code>priority_fee_shift_per_gas</code> described in the previous subsection, which however here is the same for all transactions since none have an initial ranking fee. Under <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a>, transaction processing is changed as follows:</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-keyword">for</span><span> i</span><span>,</span><span> unnormalized_transaction</span><span class="z-keyword"> in</span><span class="z-support"> enumerate</span><span>(</span><span>transactions</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"> Processing begins after this existing line</span></span> <span class="giallo-l"><span> signer</span><span>.</span><span>balance</span><span class="z-keyword"> +=</span><span> gas_refund</span><span class="z-keyword"> *</span><span> effective_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"> Redistribute priority fee</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> block</span><span>.</span><span class="z-constant">IL_transaction</span><span>[</span><span>i</span><span>]</span><span class="z-keyword">==</span><span class="z-constant">TRUE</span><span>:</span></span> <span class="giallo-l"><span> ranking_fee_per_gas</span><span class="z-keyword"> =</span><span> priority_fee_per_gas</span></span> <span class="giallo-l"><span> priority_fee_per_gas</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-keyword"> assert</span><span> block</span><span>.</span><span>priority_fee_shift_per_gas</span><span class="z-keyword"> &lt;=</span><span> priority_fee_per_gas</span></span> <span class="giallo-l"><span> ranking_fee_per_gas</span><span class="z-keyword"> =</span><span> block</span><span>.</span><span>priority_fee_shift_per_gas</span></span> <span class="giallo-l"><span> priority_fee_per_gas</span><span class="z-keyword"> -=</span><span> block</span><span>.</span><span>priority_fee_shift_per_gas</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 fee given to each includer (small division remainder burned)</span></span> <span class="giallo-l"><span> includer_fee</span><span class="z-keyword"> =</span><span> gas_used</span><span class="z-keyword"> *</span><span> ranking_fee_per_gas</span><span class="z-keyword"> //</span><span class="z-constant"> IL_COMMITTEE_SIZE</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Increase the balances of the `IL_COMMITTEE_SIZE` includers </span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> j</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span class="z-constant">IL_COMMITTEE_SIZE</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>account</span><span>(</span><span>block</span><span>.</span><span>includer</span><span>(</span><span>j</span><span>)</span><span>)</span><span>.</span><span>balance</span><span class="z-keyword"> +=</span><span> includer_fee</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"> Proposer receives the priority fee</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>account</span><span>(</span><span>block</span><span>.</span><span>author</span><span>)</span><span>.</span><span>balance</span><span class="z-keyword"> +=</span><span> gas_used</span><span class="z-keyword"> *</span><span> priority_fee_per_gas</span></span></code></pre> <p>Payout to includers uses the same CL construction as in the previous subsection and the check on the <code>marginal_ranking_fee_per_gas</code> (dashed line in the figure) is once again removed.</p> <p>If the ranking was based on the priority fee paid to the builder, the builder could offer kickbacks, allowing transactors to achieve a high ranking for free. To prevent this, the ranking portion of the fee must be distributed to a wider set of validators or be burned. Any arbitrary fee split between the builder and includers when <code>IL_transaction[i]=FALSE</code> would likely prove suboptimal and encourage off-chain agreements and builder–includer integration to circumvent the intended mechanism.</p> <h4 id="allow-builder-to-shift-priority-fee-under-upil">Allow builder to shift priority fee under UPIL</h4> <p>The <code>priority_fee_shift_per_gas</code> could be used also in the main UPIL specification. The primary rationale is that transactions using older formats then also can be included when <code>marginal_ranking_fee_per_gas&gt;0</code>, by having the builder reallocate the priority fee. Another option is to simply charge all base fees and ranking fees jointly for all transactions at the end of the block, as previously discussed.</p> <h4 id="upil-batch-auctions">UPIL batch auctions</h4> <p>A more extensive modification of the protocol is to make use of the improved CR and pricing of intra-block contention to eliminate the slack in the block, targeting 100% of the gas limit to facilitate scaling. The base fee can in such an implementation either be removed entirely, or the price information obtained via the marginal ranking fee can be relied upon for appropriate increases to the base fee.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Transactions using the <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> or <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> transaction formats can with this change spend up to their entire <code>max_fee_per_gas</code> to cover the <code>marginal_ranking_fee_per_gas</code> in blocks with high contention. Previously, the <code>max_fee_per_gas</code> could only be consumed by the <code>base_fee_per_gas</code> (which grows slowly each block) or the <code>priority_fee_per_gas</code> (which can be explicitly capped). A user setting <code>max_fee_per_gas</code> to twice the current <code>base_fee_per_gas</code>, while using a negligible <code>priority_fee_per_gas</code>, may be surprised to see the entire <code>max_fee_per_gas</code> consumed directly in the next block. However, this also implies that contention was high, and that they may have needed to spend the entire <code>max_fee_per_gas</code> for inclusion a few blocks later anyway. Importantly, the total fee paid will never exceed the <code>max_fee_per_gas</code> the user originally authorized.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP does not allow the builder to control which transactions that go into the block, with implications on CR and MEV. To retain full control over the block's content, the builder would have to bribe includers to not surface unwanted transactions. A concern then is that the builder bribes includers to not surface transactions, such that it can build the most profitable block, by excluding unwanted transactions. However, even if all includers were to be willing to forgo their duty to uphold CR if there is a profit to be made, the profit from surfacing transactions in the IL against a fee would reasonably be higher than whatever bribe a competitive builder is able to pay; especially if some includers have already taken the bribe, making remaining IL space more valuable. The option otherwise remains to distribute the marginal ranking fee to includers.</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-10-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Renaud Duboishttps://github.com/rdubois-crypto Simon Massonhttps://github.com/simonmasson https://wg-eips.ritovision.com/8051/

Precompiled contracts for FIPS-204 ML-DSA signature verification and an EVM-optimized variant

<h2 id="abstract">Abstract</h2> <p>This proposal adds precompiled contracts that perform signature verifications using the NIST module-lattice signature scheme. Two instantiations are supported:</p> <ul> <li><strong>ML-DSA</strong> — NIST-compliant version using SHAKE256 (FIPS-204),</li> <li><strong>ML-DSA-ETH</strong> — EVM-optimized version for cheaper on-chain verification: <ul> <li>Uses Keccak-based PRNG instead of SHAKE256 (leverages native KECCAK256 precompile)</li> <li>Stores public-key polynomial <code>t1</code> in the NTT domain to skip one NTT during verification (convertible to regular encoding offline)</li> </ul> </li> </ul> <p>Two precompile contracts are specified:</p> <ul> <li><code>VERIFY_MLDSA</code> — verifies a ML-DSA signature compliant to FIPS-204.</li> <li><code>VERIFY_MLDSA_ETH</code> — verifies a ML-DSA-ETH signature replacing SHAKE256 with a more efficient hash function, deviating from FIPS-204.</li> </ul> <h2 id="motivation">Motivation</h2> <p>Quantum computers pose a long-term risk to classical cryptographic algorithms. In particular, signature algorithms based on the hardness of the Elliptic Curve Discrete Logarithm Problem (ECDLP) such as secp256k1, are widely used in Ethereum and threatened by quantum algorithms. This exposes potentially on-chain assets and critical infrastructure to quantum adversaries.</p> <p>Integrating post-quantum signature schemes is crucial to future-proof Ethereum and other EVM-based environments. It shall be noted that infrastructure for post-quantum signatures should be deployed before quantum adversaries are known to be practical because it takes on the order of years for existing applications to integrate.</p> <p>Dilithium, a lattice-based scheme standardized by NIST as FIPS-204, offers high security against both classical and quantum adversaries. As the main winner of the standardization, the scheme has been selected as the main alternative to elliptic curve signature algorithms, making it a serious option for Ethereum.</p> <p>While the signature size (2.4kB) and public key size (1.3kB) are larger than other post-quantum candidates such as Falcon FN-DSA, this scheme is more flexible in terms of parameters. It is thus possible to derive a zero-knowledge version of Dilithium, keeping the security of the scheme together with an efficient in-circuit verification. This EIP does not dig into the details of this instance.</p> <p>ML-DSA has a simpler signer algorithm than FN-DSA, making hardware implementation easier. Finally, ML-DSA is based on the same mathematical construction as Kyber, the Post-Quantum Key Exchange algorithm standardized by NIST as FIPS-203. All these properties make ML-DSA well-suited for blockchain applications.</p> <p>In the context of the Ethereum Virtual Machine, a precompile for Keccak256 hash function is already available, making ML-DSA verification much faster when instantiated with an extendable output function derived from Keccak than with SHAKE256, as specified in NIST submission. This EIP specifies two versions of ML-DSA enabling two important features: one version being fully compliant with the NIST specification, the other deviating in encodings to reduce the gas cost.</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 following specification provides two precompiled contracts:</p> <table><thead><tr><th><strong>Precompiled contract</strong></th><th><strong>1</strong></th><th><strong>2</strong></th></tr></thead><tbody> <tr><td><strong>Name</strong></td><td><code>VERIFY_MLDSA</code></td><td><code>VERIFY_MLDSA_ETH</code></td></tr> <tr><td><strong>Address</strong></td><td>0x12</td><td>0x13</td></tr> <tr><td><strong>Gas cost</strong></td><td>4500</td><td>4500</td></tr> </tbody></table> <p>While ML-DSA can be instantiated for three security levels: NIST level II, III and IV, this EIP only covers NIST level II, corresponding to 128 bits of security.</p> <p>For the two variants of ML-DSA of this EIP, the following parameters are fixed:</p> <ul> <li>Polynomial degree: <code>n = 256</code>,</li> <li>Field modulus: <code>q = 8380417</code>,</li> <li>Matrix dimensions: <code>k=4</code>, <code>l=4</code>,</li> <li>Bounds of rejection: <code>γ_1 = 2¹⁷</code>, <code>γ_2 = (q-1)/88</code>, <code>β = 78</code>,</li> <li>Additional parameters: <code>η = 2</code>, <code>τ = 39</code>, <code>d = 13</code>.</li> </ul> <p>These parameters strictly follow NIST. More precisely, <code>q</code>, <code>n</code>, <code>k</code>, <code>l</code> and <code>η</code> are chosen in order to ensure a hard MLWE related problem, and the remaining parameters are chosen for the hardness of MSIS as well as for the efficiency of the scheme. The parameter <code>β = τ * η = 78</code> is the norm bound used in the rejection condition <code>||z||_∞ &lt; γ_1 - β</code> for the ML-DSA-44 parameter set in FIPS-204.</p> <p>In terms of storage, ML-DSA public key can be derived by the verifier, making the overall public key of 1312 bytes. However, this increases the verifier cost, making the on-chain verification too expensive from a practical point of view. In this EIP, the verification algorithm takes the public key in raw format, meaning that the storage for the public key is:</p> <ul> <li>The full matrix <code>A_hat</code> of 16 384 bytes,</li> <li><code>tr</code> is stored in order to save one hash, with 32 bytes,</li> <li><code>t1</code> is stored in the NTT domain in order to save one NTT, with 4096 bytes.</li> </ul> <p>The overall storage for the <strong>public key</strong> is <strong>20512 bytes</strong>. The signature follows the same format as specified in FIPS-204: 32 bytes for <code>c_tilde</code>, 2304 bytes for the coefficients of <code>z</code>, and 84 bytes for <code>h</code>. In total, a <strong>signature</strong> requires <strong>2420 bytes</strong>.</p> <h3 id="sub-algorithms-of-ml-dsa">Sub-algorithms of ML-DSA</h3> <h4 id="number-theoretic-transform">Number Theoretic Transform</h4> <p>Polynomial arithmetic is computed efficiently using Number Theoretic Transform (NTT). Efficient polynomial multiplication can be implemented following the draft NTT EIP. NTT inverse cost is roughly the same as an NTT: $n\log(n)$ additions and $n/2 \log(n)$ multiplications over the field $\mathbb F_q$, where $q=8380417$ and $n=256$.</p> <h4 id="extendable-output-function">EXtendable Output Function</h4> <p>The verification algorithm requires an eXtendable Output Function (XOF) made from a hash function. This EIP provides two instantiations of a XOF:</p> <ul> <li>SHAKE256 is the XOF provided in NIST submission, a sponge construction derived from SHA256. Extracting bytes using SHAKE256 calls the <code>Keccak_f</code> permutation as described in Section 3.7 of FIPS-204. While this construction is standardized, it is expensive when computed in the Ethereum Virtual Machine because <code>Keccak_f</code> has no EVM opcode.</li> <li>Keccak-PRNG is a XOF that is build from a counter-mode PRNG based on Keccak256. Generating new chunks of bytes requires an incrementing counter, as described in NIST SP800-90A revision 1. This XOF has the same interface as SHAKE256, but requires a <code>flip()</code> function that initiate a counter to <code>0</code>. Then, the <code>squeeze</code> function outputs as many bytes as needed using a counter mode as specified in SP800-90A revision 1. A precompile of <code>Keccak256</code> is available in the Ethereum Virtual Machine, making this XOF very efficient in the EVM.</li> </ul> <h4 id="hints-in-ml-dsa">Hints in ML-DSA</h4> <p>ML-DSA requires some hint computation. More precisely, the function <code>use_hint</code> must be implemented following Algorithm 40 of FIPS-204. The output hint is a polynomial with coefficients in {0,1}. Another function <code>sum_hint</code> is required, and counts the number of non-zero values of the hint.</p> <h4 id="sample-in-ball-challenge">Sample In Ball Challenge</h4> <p>In ML-DSA, a challenge is computed using a XOF. This algorithm <code>sample_in_ball</code> outputs a polynomial with τ small coefficients (in {-1,1}). The values of the coefficients as well as the position in the coefficients list is obtained using the XOF, as specified in Algorithm 29 of FIPS-204.</p> <h3 id="ml-dsa-verification-algorithm">ML-DSA verification algorithm</h3> <p>Verifying a ML-DSA signature follows Algorithm 8 of FIPS-204, with <code>A_hat</code> of the public key stored in expanded format, and <code>t1</code> stored in the NTT domain.</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"> VERIFY_MLDSA</span><span>(</span><span class="z-variable z-parameter z-function">public_key</span><span>,</span><span class="z-variable z-parameter z-function"> message</span><span>,</span><span class="z-variable z-parameter z-function"> signature</span><span>)</span><span> -&gt;</span><span class="z-support"> bool</span><span>:</span></span> <span class="giallo-l"><span> A_hat</span><span>,</span><span> tr</span><span>,</span><span> t1</span><span> are</span><span> decoded</span><span class="z-keyword"> from</span><span> public_key</span></span> <span class="giallo-l"><span> c_tilde</span><span>,</span><span> z</span><span>,</span><span> h</span><span> are</span><span> decoded</span><span class="z-keyword"> from</span><span> signature</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> h</span><span class="z-keyword"> is</span><span class="z-keyword"> not</span><span> properly</span><span> encoded</span><span>,</span><span class="z-keyword"> return</span><span class="z-constant"> False</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> μ</span><span class="z-keyword"> =</span><span> shake_256</span><span>(</span><span>tr</span><span class="z-keyword">+</span><span>message</span><span>)</span><span>.</span><span>extract</span><span>(</span><span class="z-constant">64</span><span>)</span></span> <span class="giallo-l"><span> c</span><span class="z-keyword"> =</span><span> sample_in_ball</span><span>(</span><span>c_tilde</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"> computed in the NTT domain</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> three NTTs for c and z, and t1</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> one final inverse NTT.</span></span> <span class="giallo-l"><span> Az_minus_ct1</span><span class="z-keyword"> =</span><span> A_hat</span><span class="z-keyword"> *</span><span> z</span><span class="z-keyword"> -</span><span> c</span><span class="z-keyword"> *</span><span> (</span><span class="z-constant">2</span><span class="z-keyword">^</span><span>d</span><span class="z-keyword"> *</span><span> t1</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> w_prime</span><span class="z-keyword"> =</span><span> h</span><span>.</span><span>use_hint</span><span>(</span><span>Az_minus_ct1</span><span>,</span><span class="z-constant"> 2</span><span class="z-keyword">*</span><span>γ_2</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> check_norm_bound</span><span>(</span><span>z</span><span>,</span><span> γ_1</span><span class="z-keyword"> -</span><span> β</span><span>)</span><span class="z-keyword"> and</span><span> c_tilde</span><span class="z-keyword"> ==</span><span> shake_256</span><span>(</span><span>μ</span><span class="z-keyword"> +</span><span> w_prime</span><span>)</span><span>.</span><span>extract</span><span>(</span><span class="z-constant">32</span><span>)</span></span></code></pre><h3 id="ml-dsa-eth-verification-algorithm">ML-DSA-ETH verification algorithm</h3> <p>The verification of ML-DSA-ETH signatures follows the same algorithm with another hash function, with two differences:</p> <ul> <li><code>t1</code> from the public key is stored in the NTT domain in order to save one NTT. The multiplication by <code>2^d</code> is also precomputed. Note that this change can be seen as a change of representation.</li> <li>A variant of <code>sample_in_ball</code> is defined using KeccakPRNG. The only difference from Algorithm 29 of FIPS-204 is that it requires a <code>flip()</code> between lines 3 and 4 so that it initializes the counter to <code>0</code> before starting squeezing. Note that this can be implemented in <code>absorb()</code> and <code>squeeze()</code> so that the same interface can be used as in SHAKE256.</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"> VERIFY_MLDSA_ETH</span><span>(</span><span class="z-variable z-parameter z-function">public_key</span><span>,</span><span class="z-variable z-parameter z-function"> message</span><span>,</span><span class="z-variable z-parameter z-function"> signature</span><span>)</span><span> -&gt;</span><span class="z-support"> bool</span><span>:</span></span> <span class="giallo-l"><span> A_hat</span><span>,</span><span> tr</span><span>,</span><span> t1</span><span> are</span><span> decoded</span><span class="z-keyword"> from</span><span> public_key</span></span> <span class="giallo-l"><span> c_tilde</span><span>,</span><span> z</span><span>,</span><span> h</span><span> are</span><span> decoded</span><span class="z-keyword"> from</span><span> signature</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> h</span><span class="z-keyword"> is</span><span class="z-keyword"> not</span><span> properly</span><span> encoded</span><span>,</span><span class="z-keyword"> return</span><span class="z-constant"> False</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> μ</span><span class="z-keyword"> =</span><span> keccak_prng</span><span>(</span><span>tr</span><span class="z-keyword">+</span><span>message</span><span>)</span><span>.</span><span>extract</span><span>(</span><span class="z-constant">64</span><span>)</span></span> <span class="giallo-l"><span> c</span><span class="z-keyword"> =</span><span> sample_in_ball_keccak_prng</span><span>(</span><span>c_tilde</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"> computed in the NTT domain</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> two NTTs for c and z</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> one final inverse NTT.</span></span> <span class="giallo-l"><span> Az_minus_ct1</span><span class="z-keyword"> =</span><span> A_hat</span><span class="z-keyword"> *</span><span> z</span><span class="z-keyword"> -</span><span> c</span><span class="z-keyword"> *</span><span> t1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> w_prime</span><span class="z-keyword"> =</span><span> h</span><span>.</span><span>use_hint</span><span>(</span><span>Az_minus_ct1</span><span>,</span><span class="z-constant"> 2</span><span class="z-keyword">*</span><span>γ_2</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> check_norm_bound</span><span>(</span><span>z</span><span>,</span><span> γ_1</span><span class="z-keyword"> -</span><span> β</span><span>)</span><span class="z-keyword"> and</span><span> c_tilde</span><span class="z-keyword"> ==</span><span> keccak_prng</span><span>(</span><span>μ</span><span class="z-keyword"> +</span><span> w_prime</span><span>)</span><span>.</span><span>extract</span><span>(</span><span class="z-constant">32</span><span>)</span></span></code></pre><h3 id="required-checks-in-ml-dsa-eth-verification">Required checks in ML-DSA(-ETH) verification</h3> <ul> <li>The hint <code>h</code> needs to be properly encoded. The malformation of the hint is specified in Algorithm 21 of FIPS-204.</li> <li>The element <code>z</code> must have a norm satisfying <code>||z||_∞ &lt; γ_1 - β</code>. The norm <code>||.||_∞</code> is defined page 6 of FIPS-204.</li> <li>The final hash output must be equal to the signature bytes <code>c_tilde</code>.</li> </ul> <h3 id="precompiled-contract-specification">Precompiled contract specification</h3> <h3 id="ml-dsa-precompiled-contract">ML-DSA precompiled contract</h3> <p>The precompiled contract VERIFY_MLDSA is proposed with the following input and outputs, which are big-endian values:</p> <ul> <li><strong>Input data</strong> <ul> <li>32 bytes for the message</li> <li>2420 bytes for ML-DSA signature</li> <li>20512 bytes for the ML-DSA expanded public key</li> </ul> </li> <li><strong>Output data</strong>: <ul> <li>If the algorithm process succeeds, it returns 1 in 32 bytes format.</li> <li>If the algorithm process fails, it returns 0 in 32 bytes format.</li> </ul> </li> </ul> <h4 id="error-cases">Error Cases</h4> <ul> <li>Insufficient gas has been provided.</li> <li>Invalid input length (not compliant to described input)</li> <li>Invalid field element encoding (≥ q)</li> <li>Invalid norm bound</li> <li>Invalid hint check</li> <li>Signature verification failure</li> </ul> <h3 id="ml-dsa-eth-precompiled-contract">ML-DSA-ETH precompiled contract</h3> <p>The precompiled contract VERIFY_MLDSA_ETH is proposed with the following input and outputs, which are big-endian values:</p> <ul> <li><strong>Input data</strong> <ul> <li>32 bytes for the message</li> <li>2420 bytes for ML-DSA-ETH signature</li> <li>20512 bytes for the ML-DSA-ETH expanded public key</li> </ul> </li> <li><strong>Output data</strong>: <ul> <li>If the algorithm process succeeds, it returns 1 in 32 bytes format.</li> <li>If the algorithm process fails, it returns 0 in 32 bytes format.</li> </ul> </li> </ul> <h4 id="error-cases-1">Error Cases</h4> <ul> <li>Insufficient gas has been provided.</li> <li>Invalid input length (not compliant to described input)</li> <li>Invalid field element encoding (≥ q)</li> <li>Invalid norm bound</li> <li>Invalid hint check</li> <li>Signature verification failure</li> </ul> <h3 id="precompiled-contract-gas-usage">Precompiled contract gas usage</h3> <p>The cost of the <strong>VERIFY_MLDSA</strong> and <strong>VERIFY_MLDSA_ETH</strong> functions is dominated by the call to the NTTs, and the required hash calls for sampling in the ball (and for μ and the final check). It represents in average 5 calls to the hash function. Taking linearly the cost of keccak256, and avoiding the context switching it represents 4500 gas.</p> <h3 id="compliance-with-eip-7932">Compliance with EIP-7932</h3> <p>In compliance with <a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a>, the necessary parameters and structure for its integration are provided. <code>ALG_TYPE = 0xD1</code> uniquely identifies ML-DSA transactions, set MAX_SIZE = 2441 bytes to accommodate the fixed-length signature_info container, and recommend a <code>GAS_PENALTY</code> of approximately <code>3000</code> gas subject to benchmarking. The verification function follows the <a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a> model, parsing the signature_info, recovering the corresponding Dilithium public key, verifying the signature against the transaction payload hash, and deriving the signer's Ethereum address as the last 20 bytes of keccak256(pubkey). This definition ensures that ML-DSA can be cleanly adopted within the <code>AlgorithmicTransaction</code> container specified by <a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a>.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>signature_info</span><span class="z-keyword"> =</span><span> Container</span><span>[</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 0xD1 for ML-DSA (NIST-compliant version),</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 0xD2 for ML-DSA-ETH (EVM-friendly version),</span></span> <span class="giallo-l"><span> version</span><span>:</span><span> uint8</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> ML-DSA signature</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span> ByteVector</span><span>[</span><span class="z-constant">2420</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> keccak256(pubkey)[12:]</span></span> <span class="giallo-l"><span> pubkey_hash</span><span>:</span><span> ByteVector</span><span>[</span><span class="z-constant">20</span><span>]</span></span> <span class="giallo-l"><span>]</span></span></code></pre> <p>In the format of EIP-7932:</p> <ul> <li>For the NIST-compliant version:</li> </ul> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>verify</span><span>(</span><span>signature_info</span><span>:</span><span class="z-support"> bytes</span><span>,</span><span> payload_hash</span><span>:</span><span> Hash32</span><span>)</span><span class="z-invalid z-illegal"> -&gt;</span><span> Bytes</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>signature_info</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 2441</span></span> <span class="giallo-l"><span> version</span><span class="z-keyword"> =</span><span> signature_info</span><span>[</span><span class="z-constant">0</span><span>]</span></span> <span class="giallo-l"><span> signature</span><span class="z-keyword"> =</span><span> signature_info</span><span>[</span><span class="z-constant">1</span><span>:</span><span class="z-constant">2421</span><span>]</span></span> <span class="giallo-l"><span> pubkey_hash</span><span class="z-keyword"> =</span><span> signature_info</span><span>[</span><span class="z-constant">2421</span><span>:</span><span class="z-constant">2441</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> version</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> 0x</span><span class="z-constant">D1</span></span> <span class="giallo-l"><span> pubkey</span><span class="z-keyword"> =</span><span> lookup_pubkey</span><span>(</span><span>pubkey_hash</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> VERIFY_MLDSA</span><span>(</span><span>pubkey</span><span>,</span><span> payload_hash</span><span>,</span><span> signature</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> pubkey</span></span></code></pre> <ul> <li>For the EVM-friendly version:</li> </ul> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>verify</span><span>(</span><span>signature_info</span><span>:</span><span class="z-support"> bytes</span><span>,</span><span> payload_hash</span><span>:</span><span> Hash32</span><span>)</span><span class="z-invalid z-illegal"> -&gt;</span><span> Bytes</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>signature_info</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 2441</span></span> <span class="giallo-l"><span> version</span><span class="z-keyword"> =</span><span> signature_info</span><span>[</span><span class="z-constant">0</span><span>]</span></span> <span class="giallo-l"><span> signature</span><span class="z-keyword"> =</span><span> signature_info</span><span>[</span><span class="z-constant">1</span><span>:</span><span class="z-constant">2421</span><span>]</span></span> <span class="giallo-l"><span> pubkey_hash</span><span class="z-keyword"> =</span><span> signature_info</span><span>[</span><span class="z-constant">2421</span><span>:</span><span class="z-constant">2441</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> version</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> 0x</span><span class="z-constant">D2</span></span> <span class="giallo-l"><span> pubkey</span><span class="z-keyword"> =</span><span> lookup_pubkey</span><span>(</span><span>pubkey_hash</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> VERIFY_MLDSA_ETH</span><span>(</span><span>pubkey</span><span>,</span><span> payload_hash</span><span>,</span><span> signature</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> pubkey</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The ML-DSA scheme was selected as a NIST-standardized post-quantum cryptographic algorithm due to its strong security guarantees and efficiency.</p> <p>ML-DSA is a signature algorithm build from lattice-based cryptography. Specifically, its hardness relies on the Short Integer Solution (SIS) problem and the Learning With Errors (LWE) problem, which is believed to be hard for both classical and quantum computers.</p> <p>ML-DSA (based on CRYSTALS-Dilithium) offers a strong balance between security, efficiency, and practicality compared to classical ECC and other post-quantum schemes. Its signature and key sizes remain reasonably small, making it practical for real-world deployments such as Ethereum blockchain. As the main winner of the NIST PQC standardization process, it benefits from a broad community consensus on its security, which is not yet the case for many alternatives. Moreover, its lattice-based structure allows flexible parameter tuning, making it easier to adapt for specialized contexts like zero-knowledge proofs. Schemes like Falcon (FN-DSA, another signature scheme built on top of lattice-based assumptions) have a more rigid parameterization, making zero-knowledge circuits larger, and thus proof computation more expensive.</p> <p>Given the increasing urgency of transitioning to quantum-resistant cryptographic primitives or even having them ready in the event that research into quantum computers speeds up.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="test-cases">Test Cases</h2> <p>A set of test vectors for verifying implementations is located in a separate file (see explanations in <a href="https://wg-eips.ritovision.com/8051/assets/README/">this file</a>):</p> <ul> <li>The file <a href="https://wg-eips.ritovision.com/8051/./assets/mldsa_nist.rsp"><code>mldsa_nist.rsp</code></a> containing the NIST submission KAT file for security level II.</li> <li>The file <a href="https://wg-eips.ritovision.com/8051/./assets/mldsa_evm.rsp"><code>mldsa_evm.rsp</code></a> containing test vectors for the EVM-friendly version with the same format as NIST.</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation is the NIST submission code for ML-DSA. A reference implementation is provided by ZKNOX for the EVM-friendly version ML-DSA-ETH.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The derivation path to obtain the private key from the seed is (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> 2025-10-11T00:00:00+00:00 2026-02-11T14:48:26+00:00 Nick Mudgehttps://github.com/mudgen https://wg-eips.ritovision.com/8042/

Define storage locations for structs using human-readable, meaningful strings.

<h2 id="abstract">Abstract</h2> <p>This standard formalizes the diamond storage pattern originally introduced by <a href="https://wg-eips.ritovision.com/2535/">ERC-2535 Diamonds</a> and widely adopted across smart contracts.</p> <p>Though originally created for proxy contracts, diamond storage can be used to organize storage and data access within <em>any</em> smart contract.</p> <p>Diamond storage defines the location of structs in contract storage using the <code>keccak256</code> hash of human-readable identifiers.</p> <p><a href="https://wg-eips.ritovision.com/8042/">ERC-8042</a> standardizes this simple and production-proven approach, offering a lightweight alternative to <a href="https://wg-eips.ritovision.com/7201/">ERC-7201</a> for new and existing projects.</p> <h2 id="motivation">Motivation</h2> <p>On March 10, 2020, a change to the Solidity compiler introduced the ability to assign structs to any storage location. This enabled a new pattern for using separate areas of storage. The pattern became known as diamond storage, as it was first popularized by ERC-2535 Diamonds and has since been widely used.</p> <p>Later, on June 20, 2023, ERC-7201 was introduced to standardize this general storage pattern. However, the formula that ERC-7201 proposed for generating storage locations differed from the one already established and in active use by diamond storage.</p> <p>ERC-8042 standardizes diamond storage for new projects and validates past diamond storage implementations.</p> <p>While ERC-7201 defines a generalized mechanism for storage namespaces, ERC-8042 preserves the simplicity and backward compatibility of the diamond storage convention already deployed in production across many projects.</p> <p>Developers may prefer diamond storage for its simplicity, restricted ASCII identifiers, and direct hash-based computation of storage locations.</p> <p>This standard can be used by tools to find and access data within smart contract storage.</p> <h2 id="specification">Specification</h2> <p>Diamond storage defines where structs are located in contract storage.</p> <p>A diamond storage identifier is defined as a string containing only printable ASCII characters. That is characters <code>0x20</code> through <code>0x7E</code> inclusive.</p> <p>The location of a diamond storage struct is determined by the <code>keccak256</code> hash of a diamond storage identifier.</p> <h3 id="recommendations">Recommendations</h3> <ol> <li><h4 id="use-solidity-s-string-literals">Use Solidity's string literals</h4> <p>A string literal is an ASCII string type that is literally written between quotes, for example: <code>"this is a string literal"</code>.</p> <p>It is recommended to use Solidity's string literals to create diamond storage identifiers because the Solidity compiler enforces that they only contain printable ASCII characters, characters <code>0x20</code> through <code>0x7E</code> inclusive. Hex (<code>\xNN</code>) and Unicode (<code>\uNNNN</code>) escape sequences should <strong>NOT</strong> be used in diamond storage identifiers.</p> <p>It is recommended to use compile-time constant string literals. Here is an example:</p> <p><code>bytes32 constant STORAGE_POSITION = keccak256("myproject.erc721.registry");</code></p> </li> <li><h4 id="use-unique-human-readable-meaningful-strings">Use unique, human-readable, meaningful strings</h4> <p>A human-readable string is a string that humans can normally read and understand, like "Transaction successful".</p> <p>A meaningful string in this context is a string that appropriately names or describes a storage space, or uses a pattern to do so. For example, <code>"myproject.erc721.registry"</code> is a hierarchical pattern that specifies <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> related storage for a registry. The string <code>"car.fish.piano.run"</code> is not a meaningful string because it is random and does not appropriately name or describe something.</p> <p>Diamond storage identifiers should be unique, human-readable, meaningful strings.</p> </li> <li><h4 id="do-not-use-unicode-literals">Do NOT use Unicode literals</h4> <p>Unicode literals can contain invisible characters and other non-ASCII characters which violates the specification of this standard.</p> <p>Here is an example of a Unicode literal in Solidity: <code>string memory a = unicode"Hello 😃";</code>.</p> <p>Unicode literals should <strong>NOT</strong> be used to create diamond storage identifiers.</p> </li> <li><h4 id="do-not-use-the-space-0x20-character">Do not use the space <code>0x20</code> character</h4> <p>Including the space (<code>0x20</code>) character in diamond storage identifiers is not recommended, as it may interfere with tooling such as the NatSpec tag described next.</p> </li> </ol> <h3 id="erc-8042-natspec-tag">ERC-8042 NatSpec tag</h3> <p>ERC-7201 defines the NatSpec tag <code>@custom:storage-location &lt;FORMULA_ID&gt;:&lt;NAMESPACE_ID&gt;</code>, where <code>&lt;FORMULA_ID&gt;</code> identifies a formula used to compute the storage location of a struct based on the namespace id.</p> <p>The formula identified by <code>erc8042</code> is defined as <code>erc8042(id: string literal) = keccak256(id)</code>. In Solidity, this corresponds to the expression <code>keccak256(id)</code>. When using this formula the annotation becomes <code>@custom:storage-location erc8042:&lt;NAMESPACE_ID&gt;</code>. For example, <code>@custom:storage-location erc8042:myproject.erc721.registry</code> annotates diamond storage with id <code>"myproject.erc721.registry"</code> rooted at <code>erc8042("myproject.erc721.registry")</code>.</p> <h2 id="rationale">Rationale</h2> <p>Proxy contracts and contracts that use <code>DELEGATECALL</code> need a reliable and secure way to define, document, and manage separate areas of smart contract storage.</p> <p>In March 2020, diamond storage established a way to do this and has been in use since then. However, diamond storage wasn't formalized as a standard, which is important to clarify its mechanics, usage and precise specification.</p> <p>In June 2023, ERC-7201 Namespaced Storage Layout standardized the general pattern but has looser restrictions on namespace ids and a more complicated formula for calculating storage locations. Some people may prefer using ERC-7201, especially if they may auto-generate machine-readable or random strings for their namespace ids.</p> <p>Some people may prefer ERC-8042 Diamond Storage for its ASCII-enforced, human-readable, meaningful strings and simple calculation of storage locations.</p> <p>ERC-2535 Diamonds first introduced the pattern of distinct storage areas for smart contracts. ERC-7201 later standardized the idea. ERC-8042 standardizes the original, simpler diamond storage variant for new projects and legacy compatibility.</p> <p>Though originally created for proxy contracts, diamond storage can be used to organize storage and data access within <em>any</em> smart contract.</p> <h3 id="comparing-erc-8042-and-erc-7201">Comparing ERC-8042 and ERC-7201</h3> <h4 id="erc-7201">ERC-7201</h4> <p>ERC-7201 applies a formula to a namespace id to generate a storage location. Per the ERC-7201 specification a namespace id is a string that should not contain any whitespace characters. A namespace id has no other restrictions. So a namespace id could be something meaningful like <code>mycompany.projectA.erc721</code> or it could be a series of random bytes, characters or words, etc.</p> <p>ERC-7201 uses the following formula, given in Solidity, to generate a storage location: <code>keccak256(abi.encode(uint256(keccak256(bytes(namespace id))) - 1)) &amp; ~bytes32(uint256(0xff))</code>.</p> <ol> <li> <p>The first part of the ERC-7201 formula <code>keccak256(abi.encode(uint256(keccak256(bytes(namespace id))) - 1))</code> ensures that the input bytes to the second call to <code>keccak256</code> will not match any input bytes used by Solidity's types that also use <code>keccak256</code> to determine storage locations. This makes it possible to use any sequence of bytes for the namespace id.</p> </li> <li> <p>The last part of ERC-7201, <code>&amp; ~bytes32(uint256(0xff))</code> ensures that the final storage location is a multiple of 256 which may provide a gas optimization in the future.</p> </li> </ol> <h4 id="erc-8042">ERC-8042</h4> <p>ERC-8042 identifiers can only contain printable ASCII characters and recommends using Solidity's string literals which enforces this constraint.</p> <p>ERC-8042 recommends human-readable, meaningful strings for diamond storage identifiers.</p> <p>ERC-8042 uses the following formula, given in Solidity, to generate a storage location: <code>keccak256(string literal)</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Diamond storage as described by this standard has been in use for 5 years. This standard recognizes and standardizes all previous uses of diamond storage that conform to the specification.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>This is a simple example of a contract that uses diamond storage:</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"> ERC721Registry</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> A registry contract for tracking ERC721 contracts.</span></span> <span class="giallo-l"><span class="z-comment"> * Allows adding ERC721 contract addresses up to a configurable limit.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> EIP-8042 Diamond Storage is used to organize and manage access to storage.</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"> ERC721Registry</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"> Reverts when the registry reaches its configured capacity.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC721RegistryFull</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-storage z-type"> @notice</span><span class="z-comment"> Struct storage position defined by keccak256 hash </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> of diamond storage identifier.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span> STORAGE_POSITION </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;myproject.erc721.registry&quot;</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-storage z-type"> @notice</span><span class="z-comment"> Storage layout for the ERC721 registry, following EIP-8042. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> - `erc721Contracts`: Dynamic array of registered ERC721 contract addresses.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `registryLimit`: Maximum allowed entries.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @custom:storage</span><span class="z-comment">-location erc8042:myproject.erc721.registry</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> ERC721RegistryStorage</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span> erc721Contracts</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> registryLimit</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"> @notice</span><span class="z-comment"> Returns a pointer to the ERC721RegistryStorage struct in storage.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Uses inline assembly to access the storage slot defined by STORAGE_POSITION.</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"> s</span><span class="z-comment"> The ERC173Storage struct in storage.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getStorage</span><span>(</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-storage z-type">ERC721RegistryStorage</span><span class="z-storage z-type"> storage</span><span class="z-variable"> s</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> position </span><span class="z-keyword">=</span><span> STORAGE_POSITION</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> s</span><span>.</span><span>slot </span><span class="z-keyword">:=</span><span> position</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-storage z-type"> @notice</span><span class="z-comment"> Sets the maximum number of ERC721 contracts the registry can hold. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _newLimit</span><span class="z-comment"> New registry capacity limit.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setRegistryLimit</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _newLimit</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> getStorage</span><span>(</span><span>)</span><span>.</span><span>registryLimit </span><span class="z-keyword">=</span><span> _newLimit</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"> @notice</span><span class="z-comment"> Adds an ERC721 contract address to the registry.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Reverts with `ERC721RegistryFull` if the registry is full.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _erc721Contract</span><span class="z-comment"> Address of the ERC721 contract to register.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addERC721Contract</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _erc721Contract</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span><span> </span></span> <span class="giallo-l"><span> ERC721RegistryStorage </span><span class="z-storage z-type">storage</span><span> s </span><span class="z-keyword">=</span><span class="z-entity z-name"> getStorage</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>s</span><span>.</span><span>erc721Contracts</span><span>.</span><span>length </span><span class="z-keyword">==</span><span> s</span><span>.</span><span>registryLimit</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> ERC721RegistryFull</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> s</span><span>.</span><span>erc721Contracts</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>_erc721Contract</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-storage z-type"> @notice</span><span class="z-comment"> Returns a list of all registered ERC721 contract addresses.</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"> of registered ERC721 contract addresses.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getERC721Registry</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>[</span><span>]</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-entity z-name"> getStorage</span><span>(</span><span>)</span><span>.</span><span>erc721Contracts</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> <h3 id="uniqueness-of-identifiers">Uniqueness of identifiers</h3> <p>Two independent contracts or libraries using the same human-readable string will map to the same storage slot. Developers must ensure that diamond storage identifiers are unique within a contract system to prevent unintentional data overlap or corruption. A common practice is to prefix identifiers with a project, organization, or standard name (for example, <code>"myproject.erc721.registry"</code>).</p> <h3 id="ascii-input-restriction-to-prevent-storage-collisions">ASCII Input Restriction to Prevent Storage Collisions</h3> <p>To prevent storage collisions, diamond storage identifiers must consist only of printable ASCII characters, specifically the range <code>0x20</code> to <code>0x7E</code> inclusive. Identifiers must not include Unicode escape sequences (<code>\uNNNN</code>) or hexadecimal escape sequences (<code>\xNN</code>).</p> <p>Solidity’s storage slot encoding, as produced by <code>abi.encode(p)</code>, contains non-printable bytes, particularly null bytes (<code>0x00</code>), due to Solidity’s default storage layout and padding rules.</p> <p>Allowing identifiers to include such bytes could enable a malicious developer to craft an identifier like <code>"config\x00\x00..."</code>. The bytes of such an identifier could collide with the storage encoded input of mappings, dynamic arrays, strings and bytes which use <code>keccak256</code> to compute storage locations. Such collisions could result in overwrites, corruption of contract state, or security vulnerabilities.</p> <p>Restricting identifiers to printable ASCII removes this exploitable source of collision. While this restriction does not provide a mathematical guarantee that collisions are impossible — because, in theory, a sufficiently large storage layout position (<code>p</code>) could accidentally contain all printable ASCII bytes — the probability of this occurring is extremely small, and impractical.</p> <p>By using human-readable, meaningful strings for identifiers, the practical likelihood of any collision is virtually zero, providing strong protection for the integrity and safety of contract storage.</p> <h3 id="string-literals">String Literals</h3> <p>The specification recommends using string literals to create diamond storage identifiers because the Solidity compiler enforces that only printable ASCII characters are used. However, string literals should not use Unicode escape sequences (<code>\uNNNN</code> ) or hexadecimal escape sequences (<code>\xNN</code> ).</p> <h3 id="unicode-literals">Unicode Literals</h3> <p>Unicode literals (e.g. <code>unicode"Hello 😃"</code>) should not be used to create diamond storage identifiers because they can contain non-printable bytes and characters, and they can be used to obfuscate identifiers by using characters that look like other characters. For example, the Cyrillic character <code>а</code> (<code>\u0430</code>) looks identical to the ASCII character <code>a</code> (<code>\u0061</code>).” In addition Unicode has control characters that change the direction text is displayed.</p> <h3 id="keccak256-hash-collision-resistance"><code>keccak256</code> Hash Collision Resistance</h3> <p>The location of a diamond storage struct is determined by the output of the <code>keccak256</code> hash function. Some developers may wonder about the likelihood that a diamond storage struct lands at an address where it will accidentally overwrite existing storage data. The 256-bit address space of contract storage is so vast that the likelihood of data overlap is statistically improbable.</p> <p>Solidity mappings, dynamic arrays, strings and bytes also use <code>keccak256</code> to determine their location in contract 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> 2025-10-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Prem Makeighttps://github.com/nxt3d https://wg-eips.ritovision.com/8049/

Onchain metadata for arbitrary contracts with optional Diamond Storage for predictable data storage locations.

<h2 id="abstract">Abstract</h2> <p>This ERC defines a standard for storing contract-level metadata onchain. It extends <a href="https://wg-eips.ritovision.com/7572/">ERC-7572</a>'s contract-level metadata concept by providing onchain storage. Contracts MAY optionally use <a href="https://wg-eips.ritovision.com/8042/">ERC-8042</a>'s Diamond Storage pattern for predictable storage locations, enabling cross-chain compatibility and supporting upgradable contracts.</p> <h2 id="motivation">Motivation</h2> <p>Contract metadata today typically relies on offchain storage such as URLs or IPFS, creating trust and availability risks—servers go down, domains expire, and malicious actors can modify data without onchain record. Storing metadata onchain makes contract identity censorship-resistant and enables wallets and block explorers to display verifiable information without trusting external services.</p> <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="required-metadata-function-and-event">Required Metadata Function and Event</h3> <p>Contracts implementing this ERC 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"> IERC8049</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 contract metadata value for a key.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getContractMetadata</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> key</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> </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 contract metadata is updated.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ContractMetadataUpdated</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> indexedKey</span><span>, </span><span class="z-support">string</span><span class="z-variable"> key</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Contracts implementing this ERC MAY also expose a <code>setContractMetadata(string calldata key, bytes calldata value)</code> function to allow metadata updates, with write policy determined by the contract.</p> <p>Contracts implementing this ERC MUST emit the following event when metadata is set:</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"> ContractMetadataUpdated</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> indexedKey</span><span>, </span><span class="z-support">string</span><span class="z-variable"> key</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> value</span><span>)</span><span>;</span></span></code></pre><h3 id="key-value-pairs">Key/Value Pairs</h3> <p>This ERC specifies that the key is a string type and the value is bytes type. This provides flexibility for storing any type of data while maintaining an intuitive string-based key interface.</p> <h3 id="optional-key-parameters">Optional Key Parameters</h3> <p>Keys MAY include parameters to represent variations or instances of a metadata type, such as <code>"registration: 1"</code> or <code>"name: Maria"</code>; see <a href="https://wg-eips.ritovision.com/8119/">ERC-8119</a>: Key Parameters.</p> <h3 id="optional-diamond-storage">Optional Diamond Storage</h3> <p>Contracts implementing this ERC MAY use Diamond Storage pattern for predictable storage locations. If implemented, contracts MUST use the namespace ID <code>"erc8049.contract.metadata.storage"</code>.</p> <p>The Diamond Storage pattern provides predictable storage locations for data, which is useful for cross-chain applications using inclusion proofs and for upgradable contracts. For more details on Diamond Storage, see <a href="https://wg-eips.ritovision.com/8042/">ERC-8042</a>.</p> <h3 id="value-interpretation">Value Interpretation</h3> <p>If no standard is specified for a metadata value, clients MAY assume the value is a UTF-8 encoded string (bytes(string)) unless otherwise specified by the implementing contract or protocol.</p> <h3 id="examples">Examples</h3> <h4 id="example-basic-contract-information">Example: Basic Contract Information</h4> <p>A contract can store basic information about itself:</p> <ul> <li>Key: <code>"name"</code> → Value: <code>bytes("MyToken")</code></li> <li>Key: <code>"description"</code> → Value: <code>bytes("A decentralized exchange")</code></li> <li>Key: <code>"collaborators"</code> → Value: <code>bytes(abi.encodePacked(address1, address2, address3))</code></li> </ul> <h4 id="example-ens-name-for-contract">Example: ENS Name for Contract</h4> <p>A contract can specify its ENS name using this standard:</p> <ul> <li>Key: <code>"ens_name"</code> → Value: <code>bytes("mycontract.eth")</code></li> </ul> <p>This allows clients to discover the contract's ENS name and resolve it to get additional information about the contract.</p> <h3 id="optional-metadata-hooks">Optional Metadata Hooks</h3> <p>Contracts implementing this ERC MAY use hooks to redirect metadata resolution to a different contract. For the full specification, see <a href="https://wg-eips.ritovision.com/8121/">ERC-8121</a>. When using hooks with contract metadata, the target function MUST be <code>getContractMetadata(string)</code> returning <code>bytes</code>. The hook selector is <code>0x9e574b14</code>.</p> <h2 id="rationale">Rationale</h2> <p>This design prioritizes simplicity and flexibility by using a string-key, bytes-value store that provides an intuitive interface for any type of contract metadata. The minimal interface with a single <code>getContractMetadata</code> function provides all necessary functionality. The optional <code>setContractMetadata</code> function enables flexible access control for metadata updates. The required <code>ContractMetadataUpdated</code> event provides transparent audit trails with indexed key for efficient filtering. Contracts that need predictable storage locations can optionally use Diamond Storage pattern. This makes the standard suitable for diverse use cases including contract identification, collaboration tracking, and custom metadata storage.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <ul> <li>Fully compatible with existing smart contracts.</li> <li>Non-supporting clients can ignore the scheme.</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>The interface is defined in the Required Metadata Function and Event section above. Here are reference implementations:</p> <h3 id="basic-implementation">Basic Implementation</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.25</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC8049.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"> BasicContractMetadata</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC8049</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Simple mapping for contract-level metadata</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">string</span><span> key </span><span class="z-keyword">=&gt;</span><span class="z-support"> bytes</span><span> value</span><span>)</span><span class="z-storage z-type"> private</span><span> _metadata</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"> getContractMetadata</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> key</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"> override</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> _metadata</span><span>[</span><span>key</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"> setContractMetadata</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> key</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</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> _metadata</span><span>[</span><span>key</span><span>]</span><span class="z-keyword"> =</span><span> value</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ContractMetadataUpdated</span><span>(</span><span>key</span><span>,</span><span> key</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></code></pre><h3 id="diamond-storage-implementation">Diamond Storage Implementation</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.25</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC8049.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"> DiamondContractMetadata</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC8049</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> ContractMetadataStorage</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">string</span><span> key </span><span class="z-keyword">=&gt;</span><span class="z-support"> bytes</span><span> value</span><span>)</span><span> metadata</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"> keccak256(&quot;erc8049.contract.metadata.storage&quot;)</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> CONTRACT_METADATA_STORAGE_LOCATION </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;erc8049.contract.metadata.storage&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"> _getContractMetadataStorage</span><span>(</span><span>)</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">ContractMetadataStorage</span><span class="z-storage z-type"> storage</span><span> $</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> location </span><span class="z-keyword">=</span><span> CONTRACT_METADATA_STORAGE_LOCATION</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> $</span><span>.</span><span>slot </span><span class="z-keyword">:=</span><span> location</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"> getContractMetadata</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> key</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"> override</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> ContractMetadataStorage </span><span class="z-storage z-type">storage</span><span> $ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getContractMetadataStorage</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> $</span><span>.</span><span>metadata</span><span>[</span><span>key</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"> setContractMetadata</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> key</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</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> ContractMetadataStorage </span><span class="z-storage z-type">storage</span><span> $ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getContractMetadataStorage</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> $</span><span>.</span><span>metadata</span><span>[</span><span>key</span><span>]</span><span class="z-keyword"> =</span><span> value</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ContractMetadataUpdated</span><span>(</span><span>key</span><span>,</span><span> key</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></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>This ERC is designed to put metadata onchain, providing security benefits through onchain storage.</p> <p>Implementations that choose to use the optional Diamond Storage pattern should consider the security considerations of <a href="https://wg-eips.ritovision.com/8042/">ERC-8042</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> 2025-10-03T00:00:00+00:00 2026-02-11T14:49:27+00:00 Maria Silvahttps://github.com/misilva73 Wei Han Nghttps://github.com/weiihann Ansgar Dietrichshttps://github.com/adietrichs https://wg-eips.ritovision.com/8038/

Increases the gas cost of state-access operations to reflect Ethereum’s larger state

<h2 id="abstract">Abstract</h2> <p>This EIP updates the gas cost of state-access operations to reflect Ethereum's larger state and the consequent slowdown of these operations. It raises the base costs for <code>GAS_STORAGE_UPDATE</code>, <code>GAS_COLD_SLOAD</code>, and <code>GAS_COLD_ACCOUNT_ACCESS</code> and updates the access cost for <code>EXTCODESIZE</code> and <code>EXTCODECOPY</code>. The design coordinates with <a href="https://wg-eips.ritovision.com/8032/">EIP-8032</a>: before EIP-8032, parameters assume worst-case contract size; after EIP-8032, they assume worst-case up to <code>ACTIVATION_THRESHOLD</code>, with additional depth-based scaling beyond.</p> <h2 id="motivation">Motivation</h2> <p>The gas price of accessing state has not been updated for quite some time. <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a> was included in the Berlin fork in March 2021 and raised the costs of state-accessing opcodes. Yet, since then, Ethereum's state has grown significantly, thus deteriorating the performance of these operations. This proposal further raises state access costs to better align them with the current performance of state access operations, in relation to other operations.</p> <p>Additionally, <code>EXTCODESIZE</code> and <code>EXTCODECOPY</code> have the same access cost as <code>BALANCE</code> and <code>EXTCODEHASH</code>. However, <code>EXTCODESIZE</code> and <code>EXTCODECOPY</code> require two database reads - first to load the account object (which includes the <code>nonce</code>, <code>balance</code>, <code>codeHash</code> and <code>storageRoot</code>), and second to collect the required information (the code size and bytecode respectively). Therefore, the access cost of <code>EXTCODESIZE</code> and <code>EXTCODECOPY</code> should be higher when compared with the other account read operations.</p> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <p>Upon activation of this EIP, the following parameters of the gas model are renamed:</p> <table><thead><tr><th style="text-align: center"><strong>Parameter</strong></th><th style="text-align: center"><strong>New name</strong></th></tr></thead><tbody> <tr><td style="text-align: center"><code>GAS_STORAGE_UPDATE</code></td><td style="text-align: center"><code>GAS_COLD_STORAGE_WRITE</code></td></tr> <tr><td style="text-align: center"><code>GAS_COLD_SLOAD</code></td><td style="text-align: center"><code>GAS_COLD_STORAGE_ACCESS</code></td></tr> </tbody></table> <p>The following parameters of the gas model are updated:</p> <table><thead><tr><th style="text-align: center"><strong>Parameter</strong></th><th style="text-align: center"><strong>Current value</strong></th><th style="text-align: center"><strong>New value</strong></th><th style="text-align: center"><strong>Increase</strong></th><th style="text-align: center"><strong>Operations affected</strong></th></tr></thead><tbody> <tr><td style="text-align: center"><code>GAS_COLD_STORAGE_WRITE</code></td><td style="text-align: center">5,000</td><td style="text-align: center">TBD</td><td style="text-align: center">TBD</td><td style="text-align: center"><code>SSTORE</code></td></tr> <tr><td style="text-align: center"><code>GAS_COLD_STORAGE_ACCESS</code></td><td style="text-align: center">2,100</td><td style="text-align: center">TBD</td><td style="text-align: center">TBD</td><td style="text-align: center"><code>SSTORE</code> and <code>SLOAD</code></td></tr> <tr><td style="text-align: center"><code>GAS_COLD_ACCOUNT_ACCESS</code></td><td style="text-align: center">2,600</td><td style="text-align: center">TBD</td><td style="text-align: center">TBD</td><td style="text-align: center"><code>*CALL</code> opcodes, <code>BALANCE</code>, <code>SELFDESTRUCT</code> and <code>EXT*</code> opcodes</td></tr> <tr><td style="text-align: center"><code>GAS_WARM_ACCESS</code></td><td style="text-align: center">100</td><td style="text-align: center">TBD</td><td style="text-align: center">TBD</td><td style="text-align: center"><code>SSTORE</code>, <code>SLOAD</code>, <code>*CALL</code> opcodes, <code>BALANCE</code> and <code>EXT*</code> opcodes</td></tr> <tr><td style="text-align: center"><code>GAS_STORAGE_CLEAR_REFUND</code></td><td style="text-align: center">4,800</td><td style="text-align: center">TBD</td><td style="text-align: center">TBD</td><td style="text-align: center"><code>SSTORE</code></td></tr> <tr><td style="text-align: center"><code>ACCESS_LIST_STORAGE_KEY_COST</code></td><td style="text-align: center">1,900</td><td style="text-align: center">TBD</td><td style="text-align: center">TBD</td><td style="text-align: center"><code>SSTORE</code> and <code>SLOAD</code></td></tr> <tr><td style="text-align: center"><code>ACCESS_LIST_ADDRESS_COST</code></td><td style="text-align: center">2,400</td><td style="text-align: center">TBD</td><td style="text-align: center">TBD</td><td style="text-align: center"><code>*CALL</code> opcodes, <code>BALANCE</code>, <code>SELFDESTRUCT</code> and <code>EXT*</code> opcodes</td></tr> </tbody></table> <p>&lt;-- TODO --&gt;</p> <h3 id="ext-family-update"><code>EXT*</code> family update</h3> <p>Besides these parameter changes, the gas cost formula for <code>EXTCODESIZE</code> and <code>EXTCODECOPY</code> is updated to include an additional <code>GAS_WARM_ACCESS</code>:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">if</span><span> address</span><span class="z-keyword"> in</span><span> evm</span><span>.</span><span>accessed_addresses</span><span>:</span></span> <span class="giallo-l"><span> access_gas_cost</span><span class="z-keyword"> =</span><span class="z-constant"> GAS_WARM_ACCESS</span><span class="z-keyword">*</span><span class="z-constant">2</span></span> <span class="giallo-l"><span class="z-keyword">else</span><span>:</span></span> <span class="giallo-l"><span> evm</span><span>.</span><span>accessed_addresses</span><span>.</span><span>add</span><span>(</span><span>address</span><span>)</span></span> <span class="giallo-l"><span> access_gas_cost</span><span class="z-keyword"> =</span><span class="z-constant"> GAS_COLD_ACCOUNT_ACCESS</span><span class="z-keyword"> +</span><span class="z-constant"> GAS_WARM_ACCESS</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="benchmarking">Benchmarking</h3> <p>This proposal does not yet have finalized numbers. To achieve this, we require stateful benchmarks, which are currently in development. Once we collect that data, we will set the final numbers.</p> <p>&lt;-- TODO --&gt;</p> <h3 id="special-case-for-extcodesize-and-extcodecopy">Special case for <code>EXTCODESIZE</code> and <code>EXTCODECOPY</code></h3> <p>Differently from other account read operations, <code>EXTCODESIZE</code> and <code>EXTCODECOPY</code> make two reads to the database. The first read is the same, where the object of the target account is loaded. This object includes the account's <code>nonce</code>, <code>balance</code>, <code>codeHash</code> and <code>storageRoot</code>. Then, these operations do another read to collect either the code size or the bytecode of the account. This second read is to an already warmed account, and thus we propose to price it as <code>GAS_WARM_ACCESS</code> for consistency.</p> <h3 id="interaction-with-eip-8032">Interaction with <a href="https://wg-eips.ritovision.com/8032/">EIP-8032</a></h3> <p><a href="https://wg-eips.ritovision.com/8032/">EIP-8032</a> proposes modifying the <code>SSTORE</code> cost formula to account for the storage size of a contract. This is a more accurate method for pricing storage writes. It allows writes to smaller contracts to be cheaper than writes to large contracts, which helps with scaling and is fairer to users. However, <a href="https://wg-eips.ritovision.com/8032/">EIP-8032</a> is not yet scheduled for inclusion in a fork, and, as such, this proposal considers two cases for setting the values of <code>GAS_COLD_STORAGE_WRITE</code> and <code>GAS_COLD_STORAGE_ACCESS</code>:</p> <ol> <li>Before <a href="https://wg-eips.ritovision.com/8032/">EIP-8032</a>. In this case, we set the parameters assuming a worst-case contract size, which makes state-accessing operations more expensive, independently of the contract size.</li> <li>After <a href="https://wg-eips.ritovision.com/8032/">EIP-8032</a>. In this case, we set the parameters assuming the worst-case until <code>ACTIVATION_THRESHOLD</code>, which is the parameter in <a href="https://wg-eips.ritovision.com/8032/">EIP-8032</a> that triggers the depth-based cost. This means that contract sizes below the threshold have the same access costs, while contracts above the threshold get exponentially more expensive with increasing size.</li> </ol> <h3 id="interaction-with-eip-2926">Interaction with <a href="https://wg-eips.ritovision.com/2926/">EIP-2926</a></h3> <p><a href="https://wg-eips.ritovision.com/2926/">EIP-2926</a> proposes to change how code is store in the state trie. One of the changes of this proposal is to include the code size as a new field in the account object (<code>codeSize</code>). With this change, the code size can be directly accessed with a single read to the database and thus <code>EXTCODESIZE</code> should maintain its previous cost formula, without including the additional <code>GAS_WARM_ACCESS</code>.</p> <h3 id="interaction-with-eip-7928">Interaction with <a href="https://wg-eips.ritovision.com/7928/">EIP-7928</a></h3> <p><a href="https://wg-eips.ritovision.com/7928/">EIP-7928</a> introduces Block-Level Access Lists, which enable parallel disk reads, parallel transaction validation, and executionless state updates through client optimizations. The initial benchmarks won't take into consideration these optimizations.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backwards-incompatible gas repricing that requires a scheduled network upgrade.</p> <p>Wallet developers and node operators MUST update gas estimation handling to accommodate the new state access cost rules. Specifically:</p> <ul> <li>Wallets: Wallets using <code>eth_estimateGas</code> MUST be updated to ensure that they correctly account for the updated gas parameters. Failure to do so could result in underestimating gas, leading to failed transactions.</li> <li>Node Software: RPC methods such as <code>eth_estimateGas</code> MUST incorporate the updated formula for gas calculation with the new state access cost values.</li> </ul> <p>Users can maintain their usual workflows without modification, as wallet and RPC updates will handle these changes.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Changing the cost of state access operations could impact the usability of certain applications. More analysis is needed to understand the potential effects on various dApps and user behaviors.</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-10-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ruiqiang Lihttps://github.com/richard-620richard.620.research@gmail.com Qin Wangqin.wang@data61.csiro.au Shiping Chenshiping.chen@data61.csiro.au Saber Yuhttps://github.com/OniReimu Brian Yeciesbyecies@uow.edu.au John Lejohnle@uow.edu.au https://wg-eips.ritovision.com/8034/

A standalone royalty distribution for Referable NFTs, supporting multiple recipients, reference-based royalty distribution.

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

Track state bytes and target 250 MiB/day by dynamically adjusting the state gas cost. Exempt state from the gas limit to facilitate scaling.

<h2 id="abstract">Abstract</h2> <p>This EIP precisely caps state growth while at the same time facilitating between 50%-300% more non-state operations per block compared to when solely raising the state gas cost. The cap is achieved by tracking state creation and having a dedicated <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> style fee market mechanism set the cost, to target 250 MiB per day. To preserve the existing transaction format and EVM execution patterns, state is still priced in gas during transaction processing. The state creation gas cost is updated every block, adjusting slowly so that users can set reasonable gas limits. The byte-level harmonization of state creation operations provided by <a href="https://wg-eips.ritovision.com/8037/">EIP-8037</a> is then still applied. To facilitate scaling, state creation and regular gas have separate limits, but a normalized aggregate gas is used when calculating the base fee.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum is currently focused on scaling the layer 1, with a rapid expansion of the block gas limit foreseen in the near-term from compute and memory optimization, as well as via headliner proposals <a href="https://wg-eips.ritovision.com/7732/">EIP-7732</a> and <a href="https://wg-eips.ritovision.com/7928/">EIP-7928</a>. Unfortunately, if the gas cost for state creation is kept fixed, state would likely expand in line with an expanding gas limit. As client database sizes increase, degradation in performance is expected. <a href="https://wg-eips.ritovision.com/8037/">EIP-8037</a> addresses state growth by harmonizing current state creation costs according to how many bytes they add to the state. It also increases the gas cost of state creation significantly, by between 3x and 9.5x per operation.</p> <p>It can be assumed that increased gas costs will somewhat keep state from expanding in line with the increased gas limit. However, since the price-elasticity of demand for state creation is unknown, it is impossible to say exactly what the effect would be. Users may not be particularly sensitive to the increased state gas costs and still continue to purchase state relative to other resources similar to present usage patterns, given that the overall base fee may also fall from the increased gas limit. This would have two effects:</p> <ol> <li>State would continue to expand by a higher rate than desired.</li> <li>Under equilibrium, well over 50% of all consumed gas may be spent on state. As further analyzed in the Rationale, a possible equilibrium outcome is 78.5% under current usage pattern and 64.7% even if users only create half as many state bytes for every gas they spend on other operations, relative to today. This impedes scaling under the current one-dimensional fee market, because state gas crowds out gas that can be used for other resources such as compute.</li> </ol> <p>To confidently target some specific state growth, it is necessary to dynamically vary the price of state creation according to its usage. The <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> mechanism is then particularly suitable. This proposal tracks <code>state_bytes_created</code> and <code>state_bytes_cleared</code> each block and keep a running counter of <code>excess_state_bytes</code>. When <code>state_bytes_created - state_bytes_cleared</code> exceeds the target, <code>excess_state_bytes</code> increases, resulting in an increase to the gas charged per state byte. Users should not need to attach excessive margins to the transaction gas limit without risking transactions failure, and the gas charged per state byte is thus set to vary very moderately between blocks, at 0.1% at the very most.</p> <p>To not impede scaling when a higher gas is charged per state byte, it is necessary to exempt state gas from the block gas limit. This is achieved by tracking the <code>regular_gas</code> and <code>state_gas</code> separately, having a separate limit for each. To ensure that the base fee still prices usage across all resources, the base fee update still operates on a normalized aggregate of both. Thus, the smooth shift in the gas charged per state byte can be understood as a separate control mechanism for pricing state <em>relative</em> to all other operations, facilitating good load-balancing over time. It is however not a mechanism that prices state creation in isolation—the base fee still applies to all resources.</p> <h2 id="specification">Specification</h2> <p>The full specification is available <a rel="external" href="https://github.com/ethereum/execution-specs/commit/d64f82b18db8c0ae35f3c56e1762ace9d83ba578">here</a>.</p> <h3 id="parameters">Parameters</h3> <p>Four constants have a similar role as in EIP-4844.</p> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>STATE_GAS_UPDATE_FRACTION</code></td><td><code>36_418_000</code></td></tr> <tr><td><code>TARGET_STATE_BYTES_PER_BLOCK</code></td><td><code>36_400</code></td></tr> <tr><td><code>MAX_STATE_BYTES_PER_BLOCK</code></td><td><code>2 * TARGET_STATE_BYTES_PER_BLOCK</code></td></tr> <tr><td><code>MIN_STATE_GAS_PER_BYTE</code></td><td><code>380</code></td></tr> </tbody></table> <p>The <code>STATE_GAS_UPDATE_FRACTION</code> is chosen so that a block that uses <code>MAX_STATE_BYTES_PER_BLOCK</code> can increase state_gas_per_byte by at most 0.1%. It was computed as <code>(MAX_STATE_BYTES_PER_BLOCK - TARGET_STATE_BYTES_PER_BLOCK) / ln(1.001)</code>, rounded to the nearest thousand.</p> <p>The number of bytes assigned to each state operation follows EIP-8037.</p> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>CREATE_BYTES</code></td><td><code>112</code></td></tr> <tr><td><code>CODE_DEPOSIT_BYTES</code></td><td><code>1</code></td></tr> <tr><td><code>NEW_ACCOUNT_BYTES</code></td><td><code>112</code></td></tr> <tr><td><code>STORAGE_SET_BYTES</code></td><td><code>32</code></td></tr> <tr><td><code>PER_EMPTY_ACCOUNT_BYTES</code></td><td><code>112</code></td></tr> <tr><td><code>PER_AUTH_BASE_BYTES</code></td><td><code>23</code></td></tr> </tbody></table> <h3 id="header-extension">Header extension</h3> <p>The current header encoding is extended with three new 64-bit unsigned integer fields.</p> <ul> <li><code>state_bytes_created</code> is the number of state bytes that were created in the current block.</li> <li><code>state_bytes_cleared</code> is the number of state bytes that were cleared in the current block.</li> <li><code>excess_state_bytes</code> is a running total of state bytes created in excess of the target, prior to the block. Blocks with above-target state bytes creation increase this value, blocks with below-target state bytes creation decrease it (bounded at 0).</li> </ul> <p>The header sequence of the new fields is <code>[..., TBD, state_bytes_created, state_bytes_cleared, excess_state_bytes]</code>.</p> <p>We also rename the <code>gas_used</code> field to <code>regular_gas_used</code>:</p> <ul> <li><code>regular_gas_used</code> is the regular gas used in the block, ignoring gas spent on state creation.</li> </ul> <h3 id="evm-gas-accounting">EVM gas accounting</h3> <p>During processing, the protocol tracks <code>regular_gas</code> and <code>state_gas</code> separately, and returns the aggregate <code>gas_used</code> accounting for refunds, similar to today. Furthermore, <code>regular_gas_used</code> (without refunds to satisfy <a href="https://wg-eips.ritovision.com/7778/">EIP-7778</a>) is returned to count against the block limit. Finally, the protocol also tracks <code>state_bytes_created</code> and <code>state_bytes_cleared</code>, allowing for a more accurate tracking of the <code>excess_state_bytes</code>. These are returned in the list <code>state_bytes(created, cleared)</code>.</p> <h3 id="computing-the-state-gas-per-byte">Computing the state gas per byte</h3> <p>The protocol keeps track of <code>excess_state_bytes</code>, and computes the <code>state_gas_per_byte</code> from that variable (referred to as <code>cost_per_state_byte</code> in EIP-8037). The same update mechanism as in EIP-4844 is applied.</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_state_gas_per_byte</span><span>(</span><span class="z-variable z-parameter z-function">header</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> fake_exponential</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> MIN_STATE_GAS_PER_BYTE</span><span>,</span></span> <span class="giallo-l"><span> header</span><span>.</span><span>excess_state_bytes</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> STATE_GAS_UPDATE_FRACTION</span></span> <span class="giallo-l"><span> )</span></span></code></pre> <p>The <code>STATE_GAS_UPDATE_FRACTION</code> is set so that the maximum increase in <code>state_gas_per_byte</code> is 0.1%, when a block consumes <code>MAX_STATE_BYTES_PER_BLOCK</code>. The <code>state_gas_per_byte</code> has a floor of <code>MIN_STATE_GAS_PER_BYTE</code>, corresponding to EIP-8037 when scaled down to a 60M block gas limit. The <code>excess_state_bytes</code> are updated as in EIP-4844, but accounting for both created and cleared state bytes:</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_state_bytes</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> excess</span><span class="z-keyword"> =</span><span> parent</span><span>.</span><span>excess_state_bytes</span><span class="z-keyword"> +</span><span> parent</span><span>.</span><span>state_bytes_created</span></span> <span class="giallo-l"><span> deficit</span><span class="z-keyword"> =</span><span class="z-constant"> TARGET_STATE_BYTES_PER_BLOCK</span><span class="z-keyword"> +</span><span> parent</span><span>.</span><span>state_bytes_cleared</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> excess</span><span class="z-keyword"> &lt;</span><span> deficit</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> excess</span><span class="z-keyword"> -</span><span> deficit</span></span></code></pre><h3 id="updating-state-gas-costs-for-the-block">Updating state gas costs for the block</h3> <p>The block level gas cost for each state operation is computed as <code>GAS_STATE_OPERATION = STATE_OPERATION_BYTES * state_gas_per_byte</code>. For completeness, the function below specifies this for all operations:</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"> update_state_op_costs</span><span>(</span><span class="z-variable z-parameter z-function">state_gas_per_byte</span><span>:</span><span class="z-support"> int</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> GAS_CREATE</span><span class="z-keyword"> =</span><span> state_gas_per_byte</span><span class="z-keyword"> *</span><span class="z-constant"> CREATE_BYTES</span></span> <span class="giallo-l"><span class="z-constant"> GAS_CODE_DEPOSIT</span><span class="z-keyword"> =</span><span> state_gas_per_byte</span><span class="z-keyword"> *</span><span class="z-constant"> CODE_DEPOSIT_BYTES</span></span> <span class="giallo-l"><span class="z-constant"> GAS_NEW_ACCOUNT</span><span class="z-keyword"> =</span><span> state_gas_per_byte</span><span class="z-keyword"> *</span><span class="z-constant"> NEW_ACCOUNT_BYTES</span></span> <span class="giallo-l"><span class="z-constant"> GAS_STORAGE_SET</span><span class="z-keyword"> =</span><span> state_gas_per_byte</span><span class="z-keyword"> *</span><span class="z-constant"> STORAGE_SET_BYTES</span></span> <span class="giallo-l"><span class="z-constant"> PER_EMPTY_ACCOUNT_COST</span><span class="z-keyword"> =</span><span> state_gas_per_byte</span><span class="z-keyword"> *</span><span class="z-constant"> PER_EMPTY_ACCOUNT_BYTES</span></span> <span class="giallo-l"><span class="z-constant"> PER_AUTH_BASE_COST</span><span class="z-keyword"> =</span><span> state_gas_per_byte</span><span class="z-keyword"> *</span><span class="z-constant"> PER_AUTH_BASE_BYTES</span></span></code></pre><h3 id="base-fee-update-rule">Base fee update rule</h3> <p>The base fee is updated by aggregating the regular gas and "normalized state gas", where a net change of <code>MAX_STATE_BYTES_PER_BLOCK</code> corresponds to the block's gas limit, thus giving state gas the same range as regular gas. The change is still restricted to the range ±12.5%. When not conditioning against negative values, the <code>gas_used_delta</code> used in the base fee update can for the EIP-1559 mechanism thus be computed as:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span> normalized_state_gas_used</span><span class="z-keyword"> =</span><span> parent</span><span>.</span><span>gas_limit</span><span class="z-keyword"> *</span><span> (</span><span>parent</span><span>.</span><span>state_bytes_created</span><span class="z-keyword"> -</span><span> parent</span><span>.</span><span>state_bytes_cleared</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> MAX_STATE_BYTES_PER_BLOCK</span></span> <span class="giallo-l"><span> gas_used_delta</span><span class="z-keyword"> =</span><span> (</span><span>parent</span><span>.</span><span>regular_gas_used</span><span class="z-keyword"> +</span><span> normalized_state_gas_used</span><span class="z-keyword"> -</span><span> parent</span><span>.</span><span>gas_limit</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> 2</span></span></code></pre><h3 id="block-validation">Block validation</h3> <p>The transaction's <code>gas_used</code> is computed as the sum of <code>regular_gas</code> and <code>state_gas</code> and includes refunds, similar to how <code>gas_used</code> is applied today. The <code>regular_gas_used</code> is returned without refunds, which the <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> cumulative gas at the block level accounts for. We also keep track of the cumulative <code>state_bytes_created</code> and <code>state_bytes_cleared</code> in the vector <code>state_bytes</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"> Check that the excess state bytes 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>excess_state_bytes</span><span class="z-keyword"> ==</span><span> calc_excess_state_bytes</span><span>(</span><span>block</span><span>.</span><span>parent</span><span>.</span><span>header</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Compute the per-block state_gas_per_byte and update state-op gas costs</span></span> <span class="giallo-l"><span> state_gas_per_byte</span><span class="z-keyword"> =</span><span> get_state_gas_per_byte</span><span>(</span><span>block</span><span>.</span><span>header</span><span>)</span></span> <span class="giallo-l"><span> update_state_op_costs</span><span>(</span><span>state_gas_per_byte</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> state_bytes_created</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> state_bytes_cleared</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> tx</span><span class="z-keyword"> in</span><span> block</span><span>.</span><span>transactions</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"> Transaction execution returns a gas_used vector and refund_vector</span></span> <span class="giallo-l"><span> gas_used</span><span>,</span><span> regular_gas_used</span><span>,</span><span> state_bytes</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>execute_transaction</span><span>(</span><span>transaction</span><span>,</span><span> effective_gas_price</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> The gas refund stays the same, the transaction gas counter only counts regular gas without refunds</span></span> <span class="giallo-l"><span> gas_refund</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>gas_limit</span><span class="z-keyword"> -</span><span> gas_used</span></span> <span class="giallo-l"><span> cumulative_transaction_gas_used</span><span class="z-keyword"> +=</span><span> regular_gas_used</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Update the total state bytes created and cleared in the block</span></span> <span class="giallo-l"><span> state_bytes_created</span><span class="z-keyword"> +=</span><span> state_bytes</span><span>[</span><span class="z-constant">0</span><span>]</span></span> <span class="giallo-l"><span> state_bytes_cleared</span><span class="z-keyword"> +=</span><span> state_bytes</span><span>[</span><span class="z-constant">1</span><span>]</span></span> <span class="giallo-l"><span class="z-constant"> ...</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"> Ensure the net state bytes created are within the per-block limit</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> state_bytes_created</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> MAX_STATE_BYTES_PER_BLOCK</span><span class="z-keyword"> +</span><span> state_bytes_cleared</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Ensure state_bytes_created and state_bytes_cleared matches header</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> state_bytes_created</span><span class="z-keyword"> ==</span><span> block</span><span>.</span><span>header</span><span>.</span><span>state_bytes_created</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> state_bytes_cleared</span><span class="z-keyword"> ==</span><span> block</span><span>.</span><span>header</span><span>.</span><span>state_bytes_cleared</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="potential-concerns-with-current-eip-8037">Potential concerns with current EIP-8037</h3> <p>EIP-8037 sets a fixed price of 1900 gas per byte, which can lead to a range of outcomes, depending on, e.g., the price-elasticity of demand for state creation. A specific concern is that since EIP-8037 counts state gas against the regular block gas limit, it may impede scaling, when users consume relatively more state gas at the higher gas per byte charged after the change. EIP-8037 assumes that users will spend 30% of all gas on state gas, just as today, even if the state gas per state byte is increased close to tenfold. This assumption may not hold.</p> <p>Ideally, an increase in the gas cost for state creation will lead users and developers to reduce usage of these operations, relative to other operations. As an example, some may opt to use an existing ETH address instead of creating a new one for each CEX withdrawal. However, given that state creation is a rather fundamental part of interacting with a blockchain, it is reasonable to suspect that many other usage patterns remain as today. Furthermore, an increase in the gas limit as Ethereum scales is associated with a general drop in the base fee. Thus, even if state creation becomes relatively more expensive than other operations, the reduced base fee may mean that users do not take notice to the extent that is desired.</p> <p>Assume that 30% of all consumed gas is state gas at 60M gas limit, producing 102 GiB in state growth per year (286 MiB/day). Then scale the L1 by $5x$ up to a 300M gas limit and increase the gas cost for state creation by $8.5x$ (using account creation in EIP-8037 as a reference point), while usage patterns do not change. The equilibrium outcome is then that $100 \times 0.3 \times 8.5 / (0.3 \times 8.5 + 0.7) = 78.5%$ of all gas is spent on state. Even though Ethereum scaled the gas limit by $5x$, the real achieved scaling is only $5 \times (1 - 0.785) / 0.7 = 1.54x$, and state growth is 157 GiB per year (440 MiB/day).</p> <p>The first example assumes no change in usage behavior and illustrates a general effect that might take place, but somewhat less pronounced. Assume instead that usage patterns indeed change, and that users create half as many state bytes for every gas they spend on other operations, in comparison to how they interact with Ethereum today. In this case, the equilibrium outcome is that $100 \times (0.3 \times 8.5 \times 0.5) / (0.3 \times 8.5 \times 0.5 + 0.7) = 64.7%$ of all gas is spent on state. When scaling the gas limit by $5x$, the real achieved scaling is $5 \times (1 - 0.647) / 0.7 = 2.52x$, and state growth is 129 GiB per year (363 MiB/day).</p> <p>Exempting state from the gas limit applied to regular gas—as proposed in this EIP—would produce a $7.14x$ in scaling (for non-state operations). We would thus achieve close to three times as much throughput as achieved in the example where users halve their state purchases relative to other operations (because they would still spend 64.7% of all available gas on state creation).</p> <h3 id="alternative-specifications">Alternative specifications</h3> <p>Alternative solutions would ideally adhere to the principles outlined in this EIP, specifically:</p> <ol> <li>It is necessary to exempt state from the aggregated regular gas limit, and assign state its own limit. Otherwise, as the gas cost for state is increased, the reduction in gas remaining for other operations will impede scaling.</li> <li>It is not possible to guarantee some specific state expansion just by altering gas costs, given that the price-elasticity of demand is unknown. For this reason, it is desirable to set the cost of state independently and according to its usage. At the same time, a fixed increase in the state gas cost will always help in reducing state consumption to some extent, but there is then also always a risk of overshooting.</li> </ol> <h4 id="multidimensional-subfee-market">Multidimensional subfee market</h4> <p>One variant is to expand the transaction format, using a separate <code>regular_gas_limit</code> and <code>state_byte_limit</code> while removing the current <code>gas_limit</code>. At the beginning of processing a transaction, the protocol computes:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>gas_limit</span><span class="z-keyword"> =</span><span> regular_gas_limit</span><span class="z-keyword"> +</span><span> state_gas_per_byte</span><span class="z-keyword"> *</span><span> state_byte_limit</span></span></code></pre> <p>All further processing is applied as if the transaction had specified the computed <code>gas_limit</code> in the first place. This ensures that users do not need to risk having a transaction fail if the <code>state_gas_per_byte</code> drifts significantly between submission and execution, if they set a tight <code>gas_limit</code>. They simply specify how much regular gas they will use and how many state-bytes they will add, which then implies a certain <code>gas_limit</code> at execution time. The idea has certain similarities with the "aggregated gas" concept explored in <a href="https://wg-eips.ritovision.com/7999/">EIP-7999</a>, but the separate fee here influences how much gas that a resource consumes, hence the name "Multidimensional subfee market". A benefit of the approach is that it offers perfect control over state growth while there is no fee-drift that can make a transaction fail. A downside is that the transaction format must be updated. It would be possible to move to a multidimensional subfee market at a later stage, after first implementing this proposal.</p> <h4 id="multidimensional-gas-metering">Multidimensional gas metering</h4> <p>It is possible to try to achieve the stated goals with multidimensional gas metering of <a href="https://wg-eips.ritovision.com/8011/">EIP-8011</a>. The difference between the proposal and the EIP-8011 mechanism is that the latter would not have a separate price for state. It uses the <code>max</code> of the gas consumption among resources for the base fee update. The base fee update may thus for example be set either from the <code>regular_gas</code> or the <code>state_gas</code>, depending on which that is used the most in the block. This means that there is less control over state growth due to the interaction between resources. When another resource consumes the most gas, it will also set the price for state. When state is the most consumed resource, it might raise the price for other resources to a level where scaling is impeded. These types of interactions can be optimized by careful tuning of limits, targets and gas costs, although whatever setting that is decided on may never be fully satisfactory. The benefit is that the gas cost set for state can be fixed, while state still is "exempted" from the regular gas limit, since it only influences the base fee in parallel via the <code>max</code> operation. Thus scaling is mostly preserved.</p> <p>Finally, it is possible to use the <code>max</code> of the gas consumption among resources for the base fee update, while still retaining the separate EIP-4844 mechanism for the <code>state_gas_per_byte</code>. This just represents another way to update the base fee, instead of the aggregation proposed here.</p> <h4 id="multidimensional-fee-market-with-aggregate-gas">Multidimensional fee market with aggregate gas</h4> <p>The multidimensional fee market with aggregate gas specified in <a href="https://wg-eips.ritovision.com/7999/">EIP-7999</a> could be applied without changing the transaction format. The gas cost for state creation is fixed and users set a single <code>gas_limit</code>. The fee for the gas for state creation is however completely separate in <code>fee_per_state_gas</code>, instead of being folded into the gas cost through conversion. Users set a <code>max_fee_per_gas</code> as today and the total fee they are willing to pay is computed as <code>max_fee = max_fee_per_gas * gas_limit</code>. This fee is compared with the fee determined during execution: <code>fee_per_state_gas * state_gas + base_fee_per_gas * regular_gas</code>. The benefit is that the gas cost cannot drift between transaction submission and execution, while the transaction format still stays the same. The downside is that if a users sets a tight <code>max_fee_per_gas</code>, then the builder cannot be sure before execution whether the fee covers the cost of the transaction. The user would need to set a more permissive <code>max_fee_per_gas</code> that covers the higher of <code>base_fee_per_gas</code> and <code>fee_per_state_gas</code> to provide full guarantees.</p> <h3 id="combination-with-multidimensional-gas-metering">Combination with multidimensional gas metering</h3> <p>This EIP works well with a broader adoption of full multidimensional gas metering, as proposed in EIP-8011, if we at the same time also adopt the EIP-8011 mechanism for updating the base fee, as suggested previously. We would then expand the <code>gas_used_per_resource</code> vector to track also the other resources in separation. State would still be treated differently in that it has its own <code>state_gas_per_byte</code> cost derived from the <code>excess_state_bytes</code>, whereas other resources are priced directly via the base fee. The metering approach of EIP-8011 is then applied to set the base fee. Given that state is increasingly becoming the major resource contraint (and thus pricing constraint) as we try to limit its usage, it is particularly beneficial that this EIP would allow the EIP-8011 metering to only be applied to the remaining resources. This is likely to benefit scaling further. Note further that the special treatment of the <code>code_deposit_gas</code> proposed in <a href="https://wg-eips.ritovision.com/8037/">EIP-8037</a> would not be necessary with this proposal, because the constraint on state bytes per block is more moderate.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The gas consumed by state creation operations will slowly change so that state growth is maintained at a desirable level. The speed of that drift is tuned by adjusting the <code>STATE_GAS_UPDATE_FRACTION</code>. This constant must be set to a level where UX concerns are mitigated. Specifically, the main concern is that if a transaction sets a very tight <code>gas_limit</code> while consuming state bytes, then that <code>gas_limit</code> may be exceeded, if the <code>state_gas_per_byte</code> cost derived from the <code>excess_state_bytes</code> shifts between submission and execution. The transaction would thus fail. Wallets must first fetch the <code>excess_state_bytes</code> and compute <code>state_gas_per_byte</code>, just as for the <code>blob_base_fee</code> (and <code>base_fee</code>) today. They know how many <code>state_bytes</code> that are created from each op-code of the transaction via the constants inherited from EIP-8037, e.g., <code>NEW_ACCOUNT_BYTES = 112</code>. They then simply add a margin <code>m</code> when computing the <code>gas_limit</code> set for the transaction: <code>gas_limit = regular_gas_limit + state_bytes * state_gas_per_byte * m</code>. The margin is tuned to the variation in <code>state_gas_per_byte</code> that is expected before execution, at the upper limit. The wallet may of course add some margin to their estimate for the <code>regular_gas_limit</code> of other op-codes as well when computing the <code>gas_limit</code>. The difference to the alternative "Multidimensional subfee market" outlined previously is thus that the wallet does not send a <code>regular_gas_limit</code> and <code>state_bytes_limit</code> separately, and instead combine them in order to preserve the current transaction format.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Wallets must have a margin when they set the <code>gas_limit</code> so that the transaction does not fail.</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-10-01T00:00:00+00:00 2026-02-11T14:49:29+00:00 Maria Silvahttps://github.com/misilva73 Carlos Perezhttps://github.com/CPerezz Jochem Brouwerhttps://github.com/jochem-brouwer Ansgar Dietrichshttps://github.com/adietrichs Łukasz Rozmejhttps://github.com/LukaszRozmej Anders Elowssonhttps://github.com/anderselowsson Francesco D'Amatohttps://github.com/fradamt https://wg-eips.ritovision.com/8037/

Harmonization, increase and separate metering of state creation gas costs to mitigate state growth and unblock scaling

<h2 id="abstract">Abstract</h2> <p>This proposal increases the cost of state creation operations, thus avoiding excessive state growth under increased block gas limits. It dynamically sets the unit cost per new state byte at a given block gas limit, by targeting an average state growth of 100 GiB per year based on current network usage. It also introduces an independent metering for state creation costs, thus allowing for increased throughput and for larger contract deployments without being limited by the single transaction gas limit.</p> <h2 id="motivation">Motivation</h2> <p>State creation does not have a harmonized cost, with different methods incurring varied costs for creating the same size of new state. For instance, while contract deployment only costs 202 gas units per new byte created, new storage slots cost 625 gas units per new byte created. Also, deploying duplicated bytecode costs the same as deploying new bytecode, even though clients don't store duplicated code in the database. This proposal establishes a standard to harmonize all state creation operations.</p> <p>Additionally, state growth will become a bottleneck for scaling under higher block limits. As of May 2025, the current database size in a Geth node dedicated to state is ~340 GiB. After the increase in gas limit from 30M to 36M gas units, the median size of new state created each day doubled, from ~102 MiB to ~205 MiB. This results in an annual growth of ~73 GiB per year.</p> <p><img src="https://wg-eips.ritovision.com/8037/./assets/new_state_added.png" alt="new_state_added" /></p> <p>The relationship we are seeing in this example is not linear as expected. This is likely due to other factors impacting user behavior. However, all else being equal, we expect a proportional increase in the number of new states created as gas limits increase. At a 60M gas limit (and a proportional increase in new state per day of 1.7x), we would see a daily state growth of ~349 MiB and a yearly state growth of ~124 GiB. Similarly, at a 100M gas limit, the state would grow at a rate of ~553 MiB per day and 197 GiB per year. This level of state growth would give us less than 2.5 years until the size of the state database exceeds the threshold of 650 GiB, at which point nodes will begin experiencing a degradation in performance.</p> <h2 id="specification">Specification</h2> <h3 id="new-parameters">New parameters</h3> <table><thead><tr><th style="text-align: center"><strong>Parameter</strong></th><th style="text-align: center"><strong>Value</strong></th></tr></thead><tbody> <tr><td style="text-align: center"><code>TARGET_STATE_GROWTH_PER_YEAR</code></td><td style="text-align: center">100 × 1024^3 bytes</td></tr> <tr><td style="text-align: center"><code>CPSB_SIGNIFICANT_BITS</code></td><td style="text-align: center">5</td></tr> <tr><td style="text-align: center"><code>CPSB_OFFSET</code></td><td style="text-align: center">9578</td></tr> </tbody></table> <p>Besides these fixed parameters, this EIP introduces a dynamic variable that controls the cost per byte of state created for a given block gas limit. The variable is <code>cost_per_state_byte</code> and is calculated as follows:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>raw</span><span class="z-keyword"> =</span><span> ceil</span><span>(</span><span>(</span><span>gas_limit</span><span class="z-keyword"> *</span><span class="z-constant"> 2_628_000</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"> TARGET_STATE_GROWTH_PER_YEAR</span><span>)</span><span>)</span></span> <span class="giallo-l"><span>shifted</span><span class="z-keyword"> =</span><span> raw</span><span class="z-keyword"> +</span><span class="z-constant"> CPSB_OFFSET</span></span> <span class="giallo-l"><span>shift</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span>bit_length</span><span>(</span><span>shifted</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> CPSB_SIGNIFICANT_BITS</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span>cost_per_state_byte</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span>(</span><span>(</span><span>shifted</span><span class="z-keyword"> &gt;&gt;</span><span> shift</span><span>)</span><span class="z-keyword"> &lt;&lt;</span><span> shift</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> CPSB_OFFSET</span><span>,</span><span class="z-constant"> 1</span><span>)</span></span></code></pre> <p>The raw value is the unquantized cost derived from targeting <code>TARGET_STATE_GROWTH_PER_YEAR</code> at 50% average gas utilization (see <a href="https://wg-eips.ritovision.com/8037/#deriving-the-cost-per-byte">Deriving the cost per byte</a>). Quantization retains the top <code>CPSB_SIGNIFICANT_BITS</code> significant bits after applying <code>CPSB_OFFSET</code>, producing a stepped function that avoids frequent small changes as the gas limit fluctuates (see <a href="https://wg-eips.ritovision.com/8037/#quantization-of-cost-per-state-byte">Quantization</a>).</p> <h3 id="parameter-changes">Parameter changes</h3> <p>Upon activation of this EIP, the following parameters of the gas model are updated. The "New State Gas" column shows the state gas cost (charged to the <code>state_gas</code> dimension), while the "New Regular Gas" column shows additional regular gas costs that accompany the state gas charge.</p> <table><thead><tr><th><strong>Parameter</strong></th><th><strong>Current</strong></th><th><strong>New State Gas</strong></th><th><strong>New Regular Gas</strong></th><th><strong>Operations affected</strong></th></tr></thead><tbody> <tr><td><code>GAS_CREATE</code></td><td>32,000</td><td>112 × <code>cpsb</code></td><td>9,000 (assuming same as <code>GAS_CALL_VALUE</code>)</td><td><code>CREATE</code>, <code>CREATE2</code>, contract creation txs</td></tr> <tr><td><code>GAS_CODE_DEPOSIT</code></td><td>200/byte</td><td><code>cpsb</code> per byte</td><td><code>6 × ceil(len/32)</code> (hash cost)</td><td><code>CREATE</code>, <code>CREATE2</code>, contract creation txs</td></tr> <tr><td><code>GAS_NEW_ACCOUNT</code></td><td>25,000</td><td>112 × <code>cpsb</code></td><td>0 (already has <code>GAS_CALL_VALUE</code> 9,000)</td><td><code>CALL*</code></td></tr> <tr><td><code>GAS_STORAGE_SET</code></td><td>20,000</td><td>32 × <code>cpsb</code></td><td>2,900 (<code>GAS_STORAGE_UPDATE - GAS_COLD_SLOAD</code>)</td><td><code>SSTORE</code></td></tr> <tr><td><code>PER_EMPTY_ACCOUNT_COST</code></td><td>25,000</td><td>112 × <code>cpsb</code></td><td>0 (included in <code>PER_AUTH_BASE_COST</code>)</td><td>EOA delegation</td></tr> <tr><td><code>PER_AUTH_BASE_COST</code></td><td>12,500</td><td>23 × <code>cpsb</code></td><td>7,500</td><td>EOA delegation</td></tr> </tbody></table> <p>Where <code>cpsb</code> = <code>cost_per_state_byte</code>. The values assigned to regular gas will be updated based on <a href="https://wg-eips.ritovision.com/8038/">EIP-8038</a>.</p> <p>&lt;-TODO-&gt;</p> <p>The <code>PER_AUTH_BASE_COST</code> regular gas of 7,500 is derived from <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>'s cost analysis, excluding the code deployment cost (now charged as state gas):</p> <ul> <li>Calldata cost: ~1,616 (101 bytes × 16)</li> <li>Recovering authority address (ecrecover): 3,000</li> <li>Reading nonce and code of authority (cold access): 2,600</li> <li>Storing values in already warm account: 200</li> <li><del>Code deployment cost: 4,600 (200 × 23)</del> → now in state gas</li> </ul> <p>Total regular gas: 1,616 + 3,000 + 2,600 + 200 ≈ 7,500</p> <p>In addition, <code>GAS_SELF_DESTRUCT_NEW_ACCOUNT</code> is removed and replaced by <code>GAS_NEW_ACCOUNT</code>.</p> <h3 id="multidimensional-metering-for-state-creation-costs">Multidimensional metering for state creation costs</h3> <p>Besides the parameter changes, this proposal introduces an independent metering for state creation costs. The specification is derived from <a href="https://wg-eips.ritovision.com/8011/">EIP-8011</a>. However, it only requires two dimensions, namely, <code>regular_gas</code> and <code>state_gas</code>. For state creation operations, the "new state costs" are charged to <code>state_gas</code>, while the "new regular costs" are charged to <code>regular_gas</code>. The costs of all other operations are also charged to <code>regular_gas</code>.</p> <p>At transaction level, the user pays for both <code>regular_gas</code> and <code>state_gas</code>. The total gas cost of a transaction is the sum of both dimensions. In addition, the transaction gas limit set in <a href="https://wg-eips.ritovision.com/7825/">EIP-7825</a> only applies to <code>regular_gas</code>, while <code>state_gas</code> is only capped by <code>tx.gas</code>.</p> <p>At the block level, only the gas used in the bottleneck resource is considered when checking if the block is full and when updating the base fee for the next block. This gives a new meaning to the block’s gas limit and the block’s gas target, which now corresponds to the maximum gas that can be metered in the bottleneck resource.</p> <h4 id="transaction-validation">Transaction validation</h4> <p>Before transaction execution, <code>calculate_intrinsic_cost</code> returns three values: <code>intrinsic_regular_gas</code>, <code>intrinsic_state_gas</code>, and <code>calldata_floor_gas_cost</code>. State gas components of intrinsic cost (e.g., account creation for contract deployment transactions, <a href="https://wg-eips.ritovision.com/2780/">EIP-2780</a> charges, <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> authorization charges) are included in <code>intrinsic_state_gas</code>. All other intrinsic costs (base transaction cost, calldata, access lists, authorization base costs) are included in <code>intrinsic_regular_gas</code>.</p> <p><code>validate_transaction</code> rejects transactions where:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-support">max</span><span>(</span><span>intrinsic_regular_gas</span><span>,</span><span> calldata_floor_gas_cost</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> TX_MAX_GAS_LIMIT</span></span></code></pre> <p><code>validate_transaction</code> also returns <code>intrinsic_regular_gas</code>, <code>intrinsic_state_gas</code>, and <code>calldata_floor_gas_cost</code>.</p> <h4 id="transaction-level-gas-accounting-reservoir-model">Transaction-level gas accounting (reservoir model)</h4> <p>Since transactions have a single gas limit parameter (<code>tx.gas</code>), gas accounting is enforced through a <strong>reservoir model</strong>, in which <code>gas_left</code> and <code>state_gas_reservoir</code> are initialized as follows:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>intrinsic_gas</span><span class="z-keyword"> =</span><span> intrinsic_regular_gas</span><span class="z-keyword"> +</span><span> intrinsic_state_gas</span></span> <span class="giallo-l"><span>execution_gas</span><span class="z-keyword"> =</span><span> tx</span><span>.</span><span>gas</span><span class="z-keyword"> -</span><span> intrinsic_gas</span></span> <span class="giallo-l"><span>regular_gas_budget</span><span class="z-keyword"> =</span><span class="z-constant"> TX_MAX_GAS_LIMIT</span><span class="z-keyword"> -</span><span> intrinsic_regular_gas</span></span> <span class="giallo-l"><span>gas_left</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span>regular_gas_budget</span><span>,</span><span> execution_gas</span><span>)</span></span> <span class="giallo-l"><span>state_gas_reservoir</span><span class="z-keyword"> =</span><span> execution_gas</span><span class="z-keyword"> -</span><span> gas_left</span></span></code></pre> <p>The <code>state_gas_reservoir</code> holds gas that exceeds the <a href="https://wg-eips.ritovision.com/7825/">EIP-7825</a>'s budget. The two counters operate as follows:</p> <ul> <li><strong>Regular gas</strong> charges deduct from <code>gas_left</code> only.</li> <li><strong>State gas</strong> charges deduct from <code>state_gas_reservoir</code> first; when the reservoir is exhausted, from <code>gas_left</code>.</li> <li>The <code>GAS</code> opcode returns <code>gas_left</code> only (excluding the reservoir).</li> <li>The reservoir is passed <strong>in full</strong> to child frames (no 63/64 rule). Unused reservoir is returned to the parent on child completion.</li> <li>On <strong>exceptional halt</strong>, both <code>gas_left</code> and <code>state_gas_reservoir</code> are set to zero (all gas consumed), consistent with existing EVM out-of-gas semantics. This is not applied to system transactions.</li> </ul> <p>The two counters are returned by the transaction output. Besides the two counters, the EVM also keeps track of <code>execution_state_gas_used</code> and <code>execution_regular_gas_used</code> during transaction execution. <code>state_gas</code> costs are added to <code>execution_state_gas_used</code> while <code>regular_gas</code> costs are added to <code>execution_regular_gas_used</code>. These two counters are also returned by the transaction output.</p> <h4 id="transaction-gas-used">Transaction gas used</h4> <p>At the end of transaction execution, the gas used before and after refunds is defined as:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>tx_gas_used_before_refund</span><span class="z-keyword"> =</span><span> tx</span><span>.</span><span>gas</span><span class="z-keyword"> -</span><span> tx_output</span><span>.</span><span>gas_left</span><span class="z-keyword"> -</span><span> tx_output</span><span>.</span><span>state_gas_reservoir</span></span> <span class="giallo-l"><span>tx_gas_refund</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span>tx_gas_used</span><span class="z-keyword"> //</span><span class="z-constant"> 5</span><span>,</span><span> tx_output</span><span>.</span><span>refund_counter</span><span>)</span></span> <span class="giallo-l"><span>tx_gas_used_after_refund</span><span class="z-keyword"> =</span><span> tx_gas_used</span><span class="z-keyword"> -</span><span> tx_gas_refund</span></span></code></pre> <p>The refund cap remains at 20% of gas used.</p> <h4 id="block-level-gas-accounting">Block-level gas accounting</h4> <p>At block level, instead of tracking a single <code>gas_used</code> counter, we keep track of two counters, one for <code>state_gas</code> and one for <code>regular_gas</code>:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>tx_regular_gas</span><span class="z-keyword"> =</span><span> intrinsic_regular_gas</span><span class="z-keyword"> +</span><span> tx_output</span><span>.</span><span>execution_regular_gas_used</span></span> <span class="giallo-l"><span>tx_state_gas</span><span class="z-keyword"> =</span><span> intrinsic_state_gas</span><span class="z-keyword"> +</span><span> tx_output</span><span>.</span><span>execution_state_gas_used</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>block_output</span><span>.</span><span>block_regular_gas_used</span><span class="z-keyword"> +=</span><span class="z-support"> max</span><span>(</span><span>tx_regular_gas</span><span>,</span><span> calldata_floor_gas_cost</span><span>)</span></span> <span class="giallo-l"><span>block_output</span><span>.</span><span>block_state_gas_used</span><span class="z-keyword"> +=</span><span> tx_state_gas</span></span></code></pre> <p>The block header <code>gas_used</code> field is set to:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>gas_used</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span>block_output</span><span>.</span><span>block_regular_gas_used</span><span>,</span><span> block_output</span><span>.</span><span>block_state_gas_used</span><span>)</span></span></code></pre> <p>The block validity condition uses this value:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">assert</span><span> gas_used</span><span class="z-keyword"> &lt;=</span><span> block</span><span>.</span><span>gas_limit</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">invalid block: too much gas used</span><span class="z-punctuation z-definition z-string">&#39;</span></span></code></pre> <p>The base fee update rule is also modified accordingly:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>gas_used_delta</span><span class="z-keyword"> =</span><span> parent</span><span>.</span><span>gas_used</span><span class="z-keyword"> -</span><span> parent</span><span>.</span><span>gas_target</span></span></code></pre><h3 id="sstore-refund-for-slot-restoration"><code>SSTORE</code> refund for slot restoration</h3> <p>When a storage slot is set to a non-zero value and then restored to zero within the same transaction (0→X→0 pattern), the following are refunded via <code>refund_counter</code>:</p> <ul> <li>State gas: <code>32 × cost_per_state_byte</code> (the state creation charge)</li> <li>Regular gas: <code>GAS_STORAGE_UPDATE - GAS_COLD_SLOAD - GAS_WARM_ACCESS</code> (2,800)</li> </ul> <p>The net cost after refund is <code>GAS_WARM_ACCESS</code> (100), consistent with pre-<a href="https://wg-eips.ritovision.com/8037/">EIP-8037</a> <code>SSTORE</code> restoration behavior. Refunds use <code>refund_counter</code> rather than direct gas accounting decrements, so that reverted frames do not benefit from the refund.</p> <h3 id="revert-behavior-for-state-gas">Revert behavior for state gas</h3> <p>State gas charged for account creation (<code>CREATE</code>, <code>CALL</code> to new account, and EOA delegation) is consumed even if the frame reverts — state changes are rolled back but gas is not refunded. This is consistent with pre-<a href="https://wg-eips.ritovision.com/8037/">EIP-8037</a> behavior where <code>GAS_NEW_ACCOUNT</code> was consumed on revert.</p> <h4 id="eip-2780-authorizations"><a href="https://wg-eips.ritovision.com/2780/">EIP-2780</a> authorizations</h4> <p>For <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> authorizations, the intrinsic state gas assumes account creation for each authorization: <code>(112 + 23) × cost_per_state_byte</code> per authorization. When an authorization targets an existing account (no account creation needed), the <code>112 × cost_per_state_byte</code> portion is subtracted from <code>intrinsic_state_gas</code> during authorization processing, before state changes begin.</p> <h4 id="receipt-semantics">Receipt semantics</h4> <p>Receipt <code>cumulative_gas_used</code> tracks the cumulative sum of <code>tx_gas_used_after_refund</code> (post-refund, post-floor) across transactions, instead of the block's <code>gas_used</code>. This means <code>receipt[i].cumulative_gas_used - receipt[i-1].cumulative_gas_used</code> equals the gas paid by transaction <code>i</code>.</p> <h3 id="contract-deployment-cost-calculation">Contract deployment cost calculation</h3> <p>When a contract creation transaction or opcode (<code>CREATE</code>/<code>CREATE2</code>) is executed, gas is charged differently based on whether the deployment succeeds or fails. Given bytecode <code>B</code> (length <code>L</code>) returned by initcode and <code>H = keccak256(B)</code>:</p> <ol> <li><strong>When opcode execution starts:</strong> Always charge <code>GAS_CREATE</code></li> <li><strong>During initcode execution:</strong> Charge the actual gas consumed by the initcode execution</li> <li><strong>Success path</strong> (no error, not reverted, and <code>L ≤ MAX_CODE_SIZE</code>): <ul> <li>Charge <code>GAS_CODE_DEPOSIT * L</code> and persist <code>B</code> under <code>H</code>, then link <code>codeHash</code> to <code>H</code></li> <li>Charge <code>HASH_COST(L)</code> where <code>HASH_COST(L) = 6 × ceil(L / 32)</code> to compute <code>H</code></li> </ul> </li> <li><strong>Failure paths</strong> (REVERT, OOG/invalid during initcode, OOG during code deposit, or <code>L &gt; MAX_CODE_SIZE</code>): <ul> <li>Do NOT charge <code>GAS_CODE_DEPOSIT * L</code> or <code>HASH_COST(L)</code></li> <li>No code is stored; no <code>codeHash</code> is linked to the account</li> <li>The account remains unchanged or non-existent</li> </ul> </li> </ol> <p><strong>Important:</strong> The gas for code deposit (<code>GAS_CODE_DEPOSIT * L</code>) is checked before hash computation. This means that if a deployment runs out of gas, it will fail during the deposit gas check before the hash is computed. This maintains consistency with post-Homestead behavior where any deployment failure (including OOG) reverts all state changes - no account is created, and no gas is charged beyond <code>GAS_CREATE</code> and the actual initcode execution cost consumed.</p> <p><strong>Total gas formulas:</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>SUCCESS_PATH_TOTAL_GAS =</span></span> <span class="giallo-l"><span> GAS_CREATE</span></span> <span class="giallo-l"><span> + initcode_execution_cost</span></span> <span class="giallo-l"><span> + (GAS_NEW_ACCOUNT if account is new else 0)</span></span> <span class="giallo-l"><span> + GAS_CODE_DEPOSIT * L</span></span> <span class="giallo-l"><span> + HASH_COST(L)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>FAILURE_PATH_TOTAL_GAS =</span></span> <span class="giallo-l"><span> GAS_CREATE</span></span> <span class="giallo-l"><span> + initcode_execution_cost</span></span></code></pre><h3 id="create-vs-create2"><code>CREATE</code> vs <code>CREATE2</code></h3> <p><code>CREATE2</code> already charges for hashing the init code when deriving the address. That cost remains unchanged. The bytecode hash (<code>keccak256(B)</code>) must be computed on success to store the code, incurring <code>HASH_COST(L)</code> as specified above.</p> <h2 id="rationale">Rationale</h2> <h3 id="deriving-the-cost-per-byte">Deriving the cost per byte</h3> <p>The variable <code>cost_per_state_byte</code> is a dynamic parameter that depends on the block gas limit. The idea is to have a cost that scales as the block gas limit increases, thus avoiding excessive state growth. To compute this variable, we target a specific state growth per year, which we set to 100 GiB. Then, we assume this growth rate is achieved at an average gas utilization.</p> <p>With multidimensional metering, blocks can be filled up to 50% of the target for both regular gas and state gas. Thus, we consider that on average, blocks can use half of the entire available gas in the block for state creation. This leads to a total of <code>(gas_limit/2) * 7200 * 365</code> gas units used for state creation in a year. Dividing this by the target state growth per year gives us the cost per byte of state created.</p> <h3 id="quantization-of-cost-per-state-byte">Quantization of <code>cost_per_state_byte</code></h3> <p>Without quantization, <code>cost_per_state_byte</code> changes by 1 for every ~81,715 change in gas limit, which is 0.13% of the current block gas limit of 60M gas units. This creates unnecessary churn for tooling and gas estimation, since the cost can change almost every block even when the gas limit is relatively stable.</p> <p>The quantization scheme retains the top 5 significant bits of <code>(raw + CPSB_OFFSET)</code>, zeroes the remaining bits, then subtracts <code>CPSB_OFFSET</code>. This is equivalent to binary floating-point rounding: each power-of-2 band has exactly 16 distinct levels, and the step size doubles at each band boundary while remaining perfectly uniform within a band.</p> <p>The offset (<code>CPSB_OFFSET = 9578</code>) shifts quantization boundaries away from common gas limit targets. It was chosen by brute-force search over 0–10000 to maximize the minimum distance from any quantization boundary to gas limits from 100M to 1000M (in 50M increments). This prevents <code>cost_per_state_byte</code> from flipping between adjacent values due to small gas limit fluctuations near popular targets. The following table shows the resulting boundary distances:</p> <table><thead><tr><th style="text-align: center">Gas Limit</th><th style="text-align: center"><code>cost_per_state_byte</code></th><th style="text-align: center">Distance to boundary</th><th style="text-align: center">Blocks to boundary</th></tr></thead><tbody> <tr><td style="text-align: center">100M</td><td style="text-align: center">1,174</td><td style="text-align: center">4.15%</td><td style="text-align: center">42.5</td></tr> <tr><td style="text-align: center">150M</td><td style="text-align: center">1,686</td><td style="text-align: center">8.21%</td><td style="text-align: center">84.0</td></tr> <tr><td style="text-align: center">200M</td><td style="text-align: center">2,198</td><td style="text-align: center">10.24%</td><td style="text-align: center">104.8</td></tr> <tr><td style="text-align: center">250M</td><td style="text-align: center">2,710</td><td style="text-align: center">5.28%</td><td style="text-align: center">54.1</td></tr> <tr><td style="text-align: center">300M</td><td style="text-align: center">3,222</td><td style="text-align: center">1.68%</td><td style="text-align: center">17.2</td></tr> <tr><td style="text-align: center">350M</td><td style="text-align: center">4,246</td><td style="text-align: center">0.89%</td><td style="text-align: center">9.1</td></tr> <tr><td style="text-align: center">400M</td><td style="text-align: center">4,758</td><td style="text-align: center">2.82%</td><td style="text-align: center">28.9</td></tr> <tr><td style="text-align: center">450M</td><td style="text-align: center">5,270</td><td style="text-align: center">4.32%</td><td style="text-align: center">44.2</td></tr> <tr><td style="text-align: center">500M</td><td style="text-align: center">5,782</td><td style="text-align: center">2.85%</td><td style="text-align: center">29.2</td></tr> <tr><td style="text-align: center">550M</td><td style="text-align: center">6,294</td><td style="text-align: center">1.10%</td><td style="text-align: center">11.3</td></tr> <tr><td style="text-align: center">600M</td><td style="text-align: center">6,806</td><td style="text-align: center">6.63%</td><td style="text-align: center">67.8</td></tr> <tr><td style="text-align: center">650M</td><td style="text-align: center">7,830</td><td style="text-align: center">1.58%</td><td style="text-align: center">16.1</td></tr> <tr><td style="text-align: center">700M</td><td style="text-align: center">7,830</td><td style="text-align: center">3.35%</td><td style="text-align: center">34.3</td></tr> <tr><td style="text-align: center">750M</td><td style="text-align: center">8,854</td><td style="text-align: center">3.54%</td><td style="text-align: center">36.3</td></tr> <tr><td style="text-align: center">800M</td><td style="text-align: center">8,854</td><td style="text-align: center">0.89%</td><td style="text-align: center">9.1</td></tr> <tr><td style="text-align: center">850M</td><td style="text-align: center">9,878</td><td style="text-align: center">4.80%</td><td style="text-align: center">49.1</td></tr> <tr><td style="text-align: center">900M</td><td style="text-align: center">10,902</td><td style="text-align: center">1.02%</td><td style="text-align: center">10.5</td></tr> <tr><td style="text-align: center">950M</td><td style="text-align: center">10,902</td><td style="text-align: center">2.57%</td><td style="text-align: center">26.4</td></tr> <tr><td style="text-align: center">1000M</td><td style="text-align: center">11,926</td><td style="text-align: center">2.55%</td><td style="text-align: center">26.2</td></tr> </tbody></table> <p>The worst-case minimum distance is 0.89% of the gas limit (at 350M and 800M). Since the gas limit can deviate from its parent by at most 1/1024, <code>cost_per_state_byte</code> remains stable for at least ~9 consecutive blocks of same-direction gas limit changes at any gas limit in the 100M–1000M range (in 50M increments).</p> <h3 id="harmonization-across-state-creation">Harmonization across state creation</h3> <p>With the current pricing, the gas cost of creating 1 byte of state varies depending on the method used. The following table shows the various methods and their gas cost per byte. The calculation ignores the transaction intrinsic cost (21k gas units) and the costs of additional opcodes and scaffolding needed to execute such a transaction.</p> <table><thead><tr><th>Method</th><th>What is written</th><th>Intrinsic gas</th><th>Bytes → state</th><th>Gas / byte</th></tr></thead><tbody> <tr><td>Deploy 24kB contract (<a href="https://wg-eips.ritovision.com/170/">EIP-170</a> limit)</td><td>Runtime code + account trie node</td><td>32,000 CREATE + 200 × 24,576 code deposit = 4,947,200 gas</td><td>24,688 B</td><td>~200 gas</td></tr> <tr><td>Fund fresh EOA with 1 wei</td><td>Updated account leaf</td><td>25,000 new account</td><td>~112 B</td><td>~223 gas</td></tr> <tr><td>Add delegate flag to funded EOA (<a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>)</td><td>23 B (0xef0100‖address) + updated account leaf</td><td>25,000 PER_EMPTY_ACCOUNT + 12,500 PER_AUTH_BASE + 1,616 calldata - 7,823 refund = ~31,300 gas</td><td>~135 B</td><td>~232 gas</td></tr> <tr><td><a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> authorization to empty address</td><td>23 B (0xef0100‖address) + updated account leaf</td><td>25,000 PER_EMPTY_ACCOUNT + 12,500 PER_AUTH_BASE + 1,616 calldata = 39,116 gas</td><td>~135 B</td><td>~289 gas</td></tr> <tr><td>Fill new storage slots (SSTORE 0→x)</td><td>Slot in storage trie</td><td>20,000 gas/slot</td><td>32 B</td><td>625 gas</td></tr> </tbody></table> <p>To harmonize costs, we first set the gas cost of a single state byte, <code>cost_per_state_byte</code>, as explained above. This is a dynamic parameter that depends on the block gas limit. Now that we have a standardized cost per byte, we can derive the various costs parameters by multiplying the unit cost by the increase in bytes any given operation creates in the database (i.e., 32 bytes per slot, 112 bytes per account and 23 bytes per authorization).</p> <p>Note that the fixed cost <code>GAS_CREATE</code> for contract deployments assumes the same cost as a new account creation.</p> <h3 id="multidimensional-metering">Multidimensional metering</h3> <p>This proposal is consistent with <a href="https://wg-eips.ritovision.com/8011/">EIP-8011</a>. However, it only requires two dimensions, namely, <code>regular_gas</code> and <code>state_gas</code>. If <a href="https://wg-eips.ritovision.com/8011/">EIP-8011</a> is not implemented, a two-dimensional version of <a href="https://wg-eips.ritovision.com/8011/">EIP-8011</a> is still required.</p> <h4 id="eip-7825-limit-on-contract-size">EIP-7825 limit on contract size</h4> <p><a href="https://wg-eips.ritovision.com/7825/">EIP-7825</a> introduces <code>TX_MAX_GAS_LIMIT</code> (16.7M) as the maximum gas for a single transaction, in particular stipulating <code>tx.gas &lt; TX_MAX_GAS_LIMIT</code>as a validity condition. Were we to continue enforcing this validity condition, with a block limit of 100M gas units, this proposal would limit the maximum contract size that can be deployed to roughly 9.9kB ($\frac{16,777,216 - 21,000 - 5,000,000 - 112 \times 1174}{1174} = 9'902$). This maximum size would only decrease as we increase the gas limit and the <code>cost_per_state_byte</code>.</p> <p>To solve this issue, we only apply this gas limit to regular gas, not state gas. Doing so does not weaken the intended scaling effect of <a href="https://wg-eips.ritovision.com/7825/">EIP-7825</a>, because regular gas meters all resources that benefit from parallelization. In particular, state growth does not: growing the state always requires writing to disk, a parallelizable operation, but crucially this part of the cost of a state growth operation has to be metered in regular gas, not state gas. In other words, any operation that grows the state should consume both regular gas and state gas, and the regular gas should fully account for all costs other than the long term effect of growing the state.</p> <p>However, we cannot statically enforce a regular gas consumption of <code>TX_MAX_GAS_LIMIT</code>, while still allowing a higher state gas consumption, because transactions only have a single gas limit parameter, <code>tx.gas</code>. This is solved through a <strong>reservoir model</strong>: at transaction start, execution gas is split into <code>gas_left</code> (capped at <code>TX_MAX_GAS_LIMIT - intrinsic_regular_gas</code>) and a <code>state_gas_reservoir</code> (the overflow). State gas charges draw from the reservoir first, then from <code>gas_left</code> when the reservoir is empty. Regular gas charges draw from <code>gas_left</code> only. Exceeding the regular gas budget behaves identically to running out of gas — no special error is needed.</p> <h4 id="higher-throughput">Higher throughput</h4> <p>Another advantage of metering contract creation separately is that increasing the cost of state creation operation in line with the block limit will not affect the available gas for other operations. This allows for higher throughput, as explained in the original multidimensional gas metering introduced in <a href="https://wg-eips.ritovision.com/8011/">EIP-8011</a>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backwards-incompatible gas repricing that requires a scheduled network upgrade.</p> <p>Wallet developers and node operators MUST update gas estimation handling to accommodate the new calldata cost rules. Specifically:</p> <ul> <li>Wallets: Wallets using <code>eth_estimateGas</code> MUST be updated to ensure that they correctly account for the updated gas parameters. Failure to do so could result in underestimating gas, leading to failed transactions.</li> <li>Node Software: RPC methods such as <code>eth_estimateGas</code> MUST incorporate the updated formula for gas calculation with the new floor cost values.</li> </ul> <p>Users can maintain their usual workflows without modification, as wallet and RPC updates will handle these changes.</p> <h3 id="estimated-price-impacts-at-various-block-gas-limits">Estimated price impacts at various block gas limits</h3> <p>Users and dApp developers will experience an increase in transaction costs associated with creating a new state. The next table summarizes the state creation costs for common operations at different block gas limits.</p> <table><thead><tr><th style="text-align: center">Case</th><th style="text-align: center">cost_per_state_byte</th><th>Cost of a new account</th><th>Cost increase</th><th>Cost of a new slot</th><th>Cost increase</th><th>24kB contract deployment</th><th>Cost increase</th></tr></thead><tbody> <tr><td style="text-align: center">Current cost</td><td style="text-align: center">NA</td><td>25,000</td><td>NA</td><td>20,000</td><td>NA</td><td>4,947,200</td><td>NA</td></tr> <tr><td style="text-align: center">Proposed cost at 60M block limit</td><td style="text-align: center">662</td><td>74,144</td><td>3</td><td>24,084</td><td>1</td><td>16,357,064</td><td>3</td></tr> <tr><td style="text-align: center">Proposed cost at 100M block limit</td><td style="text-align: center">1,174</td><td>131,488</td><td>5</td><td>40,468</td><td>2</td><td>28,997,320</td><td>6</td></tr> <tr><td style="text-align: center">Proposed cost at 200M block limit</td><td style="text-align: center">2,198</td><td>246,176</td><td>10</td><td>73,236</td><td>4</td><td>54,277,832</td><td>11</td></tr> <tr><td style="text-align: center">Proposed cost at 300M block limit</td><td style="text-align: center">3,222</td><td>360,864</td><td>14</td><td>106,004</td><td>5</td><td>79,558,344</td><td>16</td></tr> </tbody></table> <p>We should note that as the block limit increases, the base fee is expected to reduce due to the higher capacity of the network. This reduction in base fee will offset, in part, the costs from state creation operations. Some analysis is needed to quantify this effect.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Increasing the cost of state creation operations could impact the usability of certain applications. More analysis is needed to understand the potential effects on various dApps and user behaviors.</p> <h3 id="mispricing-with-respect-to-eth-transfers">Mispricing with respect to ETH transfers</h3> <p>One potential concern is the cost of creating a new account (<code>112 × cost_per_state_byte</code> gas units, e.g., 131,488 at a 100M gas limit), compared to transferring ETH to a fresh account (21,000 gas units). With this mismatch, users wishing to create new account are incentivized to first send a normal transaction (costing 21k) to this account to create it, thus avoiding the <code>GAS_NEW_ACCOUNT</code> charge.</p> <p><a href="https://wg-eips.ritovision.com/2780/">EIP-2780</a> solves this mispricing by adding a new component to the intrinsic gas cost of transactions. If a non-create transaction has value &gt; 0 and targets a non-existent account, the <code>GAS_NEW_ACCOUNT</code> is added to intrinsic cost.</p> <h3 id="added-complexity-in-block-building">Added complexity in block building</h3> <p>Optimal block construction becomes more complex, since builders must now balance resource usage across multiple dimensions rather than a single gas metric. Sophisticated builders may gain an advantage by applying advanced optimization techniques, raising concerns about further builder centralization. However, practical heuristics (e.g., greedily filling blocks until one resource dimension saturates) remain effective for most use cases. These heuristics limit centralization pressure by keeping block construction feasible for local and less sophisticated builders.</p> <h3 id="testing-requirements-for-increasing-block-limits">Testing requirements for increasing block limits</h3> <p>With a dynamic cost per byte, every time the block gas limit is increased, clients and testing frameworks need to test for backward compatibility issues. This changes the testing framework for increasing the block limit. A way to mitigate this is to introduce a max cost per byte and do the analysis once on the impact of this max cost.</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-09-29T00:00:00+00:00 2026-02-11T14:49:28+00:00 Guillaume Ballethttps://github.com/gballet Carlos Perezhttps://github.com/CPerezz Matan Prasmahttps://github.com/KanExtension Wei Han Nghttps://github.com/weiihann https://wg-eips.ritovision.com/8032/

Makes `SSTORE` gas cost scale with a contract's storage size to discourage state bloat.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a mechanism to dynamically price SSTORE operations based on the storage size of a contract. A new optional <code>storage_count</code> field is added to the account RLP, which tracks the number of storage slots it owns. The gas cost for SSTORE will be augmented by a factor that grows exponentially with this <code>storage_count</code> field, but only after it crosses a predefined activation threshold. This change aims to align the cost of state growth with the long-term burden it places on the network, thereby disincentivizing state bloat.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum's state size is a growing concern, as it directly impacts node synchronization times, hardware requirements, and overall network health. The current gas model for storage operations does not fully account for the long-term cost of maintaining state indefinitely. As a result, it remains economically viable to deploy contracts with large storage footprints (“state bloat”), which can be exploited for low-cost data anchoring or spam. This imposes a negative externality on all network participants, who must store and process this data indefinitely.</p> <p>In practice, the computational and I/O costs of creating and updating storage slots scale with the number of storage slots a contract owns. However, the current gas pricing model does not meaningfully increase with storage size. This discrepancy underprices workloads for contracts with very large state and slows down state root computation.</p> <p>This proposal aims to address the state growth problem by creating a direct economic link between the size of a contract's storage and the cost to expand it further. By progressively increasing the price of SSTORE operations in proportion to how much storage a contract already owns, storage write costs become more aligned with the actual work clients perform. Contracts that contribute disproportionately to state growth will face rising costs for additional writes, while small and medium-sized contracts remain unaffected. This mechanism creates a market-based incentive for developers to use onchain storage efficiently, helping mitigate unsustainable state growth over time.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="constants-and-parameters">Constants and parameters</h3> <table><thead><tr><th>Name</th><th style="text-align: center">Value</th><th>Description</th></tr></thead><tbody> <tr><td><code>FORK_TIMESTAMP</code></td><td style="text-align: center">TBD</td><td>Fork activation timestamp</td></tr> <tr><td><code>LIN_FACTOR</code></td><td style="text-align: center">TBD</td><td>Linear gas cost factor</td></tr> <tr><td><code>ACTIVATION_THRESHOLD</code></td><td style="text-align: center">TBD</td><td>Activation threshold, chosen to be at ~8GB of data.</td></tr> <tr><td><code>TRANSITION_REGISTRY_ADDRESS</code></td><td style="text-align: center">TBD</td><td>The address of system contract that holds the information of account transition</td></tr> <tr><td><code>TRANSITION_SLOTS_PER_BLOCK</code></td><td style="text-align: center">TBD</td><td>The number of storage slots to iterate per block during the transition process</td></tr> <tr><td><code>TRANSITION_MAX_ACCOUNTS</code></td><td style="text-align: center">TBD</td><td>The number of accounts to iterate per block during the transition process</td></tr> </tbody></table> <p>&lt;-- TODO --&gt;</p> <h3 id="new-account-field">New account field</h3> <p>Account RLP descriptors receive an optional <code>storage_count</code> field, corresponding to the current number of storage slots it contains.</p> <h3 id="account-transition">Account transition</h3> <p>At <code>FORK_TIMESTAMP</code>, the transition is activated.</p> <p>The transition process involves reading all accounts and count the number of storage slots for accounts with non-empty storage root hashes, which in turn populates the <code>storage_count</code> field in the account.</p> <p>The progress of the transition is stored at system contract at <code>TRANSITION_REGISTRY_ADDRESS</code>.</p> <p>Storage layout at <code>TRANSITION_REGISTRY_ADDRESS</code>:</p> <ul> <li>slot <code>0x00</code>: <code>cursor_account_hash</code> (32-byte account hash)</li> <li>slot <code>0x01</code>: <code>cursor_slot_hash</code> (32-byte slot hash)</li> <li>slot <code>0x02</code>: <code>cursor_accum</code> (uint256 count of non-zero slots seen for the current account)</li> </ul> <p>At the <strong>end</strong> of each block, the client performs up to <code>TRANSITION_SLOTS_PER_BLOCK</code> storage slot iterations, possibly spanning one account or multiple accounts:</p> <ol> <li> <p><strong>Select account</strong><br /> If <code>cursor_account_hash == 0x00…00</code>, set it to the smallest account hash that is present in the state trie. Otherwise, continue with <code>cursor_account_hash</code>.</p> </li> <li> <p><strong>Iterate storage slots</strong><br /> If the current account at <code>cursor_account_hash</code> has a non-empty <code>storageRootHash</code>, visit storage slots of this account in ascending lexicographic order of <code>slot hash</code>, starting <strong>strictly after</strong> <code>cursor_slot_hash</code> (or from the beginning if <code>cursor_slot_hash == 0x00…00</code>).</p> <ul> <li>Increment <code>cursor_accum</code> slot for every slot hash seen</li> <li>Stop when either: <ul> <li><code>TRANSITION_SLOTS_PER_BLOCK</code> slots have been processed, or</li> <li>there are no more storage slots for the account.</li> </ul> </li> </ul> </li> <li> <p><strong>Finalize account (if exhausted)</strong><br /> If all storage slots for <code>cursor_account_hash</code> have been visited, set <code>storage_count(cursor_account)</code> to <code>cursor_accum</code> in the account object.</p> <p>If <code>TRANSITION_MAX_ACCOUNTS</code> accounts are iterated, then stop iterating.</p> <ul> <li>Else: <ul> <li>Advance to the next account:<br /> <code>cursor_account_hash</code> = next account hash that is present in the state trie</li> <li>Reset per-account cursors:<br /> <code>cursor_slot_hash = 0x00…00</code>, <code>cursor_accum = 0</code></li> </ul> </li> </ul> </li> <li> <p><strong>Persist</strong><br /> If either <code>TRANSITION_SLOTS_PER_BLOCK</code> or <code>TRANSITION_MAX_ACCOUNTS</code> is reached, write <code>cursor_account_hash</code>, <code>cursor_slot_hash</code>, and <code>cursor_accum</code> to the registry in the post-state of the block.</p> </li> <li> <p><strong>Completion</strong><br /> The transition is complete when there is no further account present in the trie, with an account hash that is lexicographically greater than the current <code>cursor_account_hash</code>.</p> </li> </ol> <p>The account hashes and slot hashes are iterated in ascending lexicographical order.</p> <p>Transition reference: <a href="https://wg-eips.ritovision.com/7612/">EIP-7612</a></p> <h4 id="reorg-semantics">Reorg semantics</h4> <p>Chain reorganizations require <strong>no special handling</strong> beyond normal block re-execution. The mechanism is reorg-safe.</p> <p><code>storage_count</code> updates and the transition cursors (<code>cursor_account_hash</code>, <code>cursor_slot_hash</code>, <code>cursor_accum</code>) are ordinary state writes committed in the post-state of each block at <code>TRANSITION_REGISTRY_ADDRESS</code>. On a reorg, these values revert to those of the new canonical ancestor and are re-derived by re-executing blocks.</p> <h3 id="account-update-rules">Account update rules</h3> <p>After executing all transactions in a block, clients MUST update <code>storage_count</code> for affected accounts as follows:</p> <ul> <li>Let <code>old := storage_count(A)</code> in the block-prestate (treat as <code>0</code> if absent).</li> <li>Let <code>new</code> be the true count of non-zero slots for <code>A</code> in the post-block state.</li> <li>Set <code>storage_count(A) := new</code>.</li> </ul> <p>To compute <code>new</code> efficiently without scanning all storage every block, clients MUST apply net deltas derived from slots whose values changed relative to the block-prestate:</p> <p>For each storage slot <code>k</code> of account <code>A</code> that was written at least once in the block:</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"> calculate_storage_delta</span><span>(</span><span class="z-variable z-parameter z-function">prestate_value</span><span>,</span><span class="z-variable z-parameter z-function"> poststate_value</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"> Calculate the storage slot delta based on pre-state and post-state values.</span></span> <span class="giallo-l"><span class="z-string"> </span></span> <span class="giallo-l"><span class="z-string"> Args:</span></span> <span class="giallo-l"><span class="z-string"> prestate_value: Pre-state value of the storage slot</span></span> <span class="giallo-l"><span class="z-string"> poststate_value: Post-state value of the storage slot</span></span> <span class="giallo-l"><span class="z-string"> </span></span> <span class="giallo-l"><span class="z-string"> Returns:</span></span> <span class="giallo-l"><span class="z-string"> int: Delta value (+1, -1, or 0)</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-keyword"> if</span><span> prestate_value</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span class="z-keyword"> and</span><span> poststate_value</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"> 1</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Slot created: empty to non-empty</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> prestate_value</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span class="z-keyword"> and</span><span> poststate_value</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-keyword"> -</span><span class="z-constant">1</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Slot deleted: non-empty to empty</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-constant"> 0</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> No change in slot occupancy</span></span></code></pre> <p>During a transition, the transition is advanced <em>first</em> before applying the storage deltas, but <em>after</em> executing all transactions, so the gas costs of a contract that is sweeped by the iterator in this block are only applied for the <em>next</em> block. Update semantics when a transition is occurring:</p> <ul> <li>For accounts that have been iterated (i.e. <code>cursor_account_hash</code> &gt; <code>acc_hash</code> ), all storage deltas are applied.</li> <li>For accounts that have not been iterated at all (i.e. <code>acc_hash</code> &gt; <code>cursor_account_hash</code>), none of the storage deltas are applied.</li> <li>For the account currently being iterated (i.e. <code>cursor_account_hash</code> == <code>acc_hash</code>), storage deltas are applied only to the slots that have already been accounted for (i.e. <code>cursor_slot_hash</code> &gt; <code>slot_hash</code>).</li> </ul> <h3 id="sstore-gas-cost-changes">SSTORE gas cost changes</h3> <p>For each contract account <code>A</code>, define <code>S_pre(A)</code> as the value of <code>storage_count(A)</code> in the parent state of the block being executed (pre-state).</p> <p>For all <code>SSTORE</code>s in the block, implementations MUST use <code>S_pre(A)</code> when computing the gas cost for <code>SSTORE</code>. This value MUST NOT change within the block, regardless of any writes to <code>A</code> during the block.</p> <p>If <code>storage_count(A)</code> is absent at block start, clients MUST treat <code>S_pre(A) = 0</code>.</p> <blockquote> <p>Rationale: holding <code>S_pre(A)</code> constant within the block keeps gas estimation stable and independent of transaction ordering.</p> </blockquote> <p>The gas cost of an <code>SSTORE</code> is computed as such:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>constant_sstore_gas</span><span>(</span><span>addr</span><span>,</span><span> slot</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> LIN_FACTOR</span><span class="z-keyword"> *</span><span> ceil_log16</span><span>(</span><span>S_pre</span><span>(</span><span>addr</span><span>)</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> ACTIVATION_THRESHOLD</span></span></code></pre><h3 id="impact-on-state-size">Impact on state size</h3> <p><code>storage_count</code> is RLP-encoded as a minimal-length big-endian byte string (no leading zeros). The per-account overhead is therefore small and not a fixed 32 byte number. The field is present only for accounts with a non-empty storage root hash. If <code>storage_count == 0</code>, the field may be omitted.</p> <p><strong>Per-account overhead</strong></p> <ul> <li>Payload length <code>L = bytes_required(storage_count)</code>: <ul> <li><code>L = 0</code> for <code>0</code> (field may be omitted entirely)</li> <li><code>L = 1</code> for <code>1 … 255</code></li> <li><code>L = 2</code> for <code>256 … 65,535</code></li> <li><code>L = 3</code> for <code>65,536 … 16,777,215</code></li> <li><code>L = 4</code> for <code>16,777,216 … 4,294,967,295</code> (≈ 4.29B)</li> </ul> </li> <li><strong>+1 byte</strong> RLP string prefix (since <code>L ≤ 55</code>)</li> <li><strong>+ up to 1 byte</strong> for the account-list prefix growth (only if the list’s total payload crosses a size boundary)</li> </ul> <p>For context, at block ~23,000,000 the largest contract has about <strong>80M</strong> storage slots. Even at that scale (<code>L = 4</code>), the per-account addition remains <strong>≤ 6 bytes</strong>.</p> <p>If we pessimistically assume <strong>23,000,000</strong> contract accounts each carry <code>storage_count</code> and each incurs the worst-case <strong>6 bytes</strong>, the upper bound is:</p> <ul> <li><code>23,000,000 × 6 = 138,000,000</code> bytes ≈ <strong>138 MB</strong></li> </ul> <p>This is a conservative upper bound. In practice, most contracts have far fewer slots (<code>L ≤ 1–3</code>), so a typical addition is 2–4 bytes per contract. Therefore, the net impact on state size is negligible.</p> <h2 id="rationale">Rationale</h2> <p>The intent is to create friction when growing the state size of a contract, thus limiting the number of such contracts. Going over the limit, some contract developers might want to use another contract to start fresh, which comes at the cost of paying for contract creation, and for any call into the previous instance of the contract.</p> <p><code>ACTIVATION_THRESHOLD</code> is chosen to not penalize the contracts that are large, but do provide useful value. The idea is to disincentivize spam contracts that grow larger than useful contracts, the latter being legitimately big due to the value they bring to their users and the wider ecosystem. This means that this constant could be increased as the state grows.</p> <p><code>TRANSITION_MAX_ACCOUNTS</code> bounds how many accounts may be finalized (i.e. have their <code>storage_count</code> written) per block during the transition. This prevents excessive write operations per block, reducing write amplification and avoiding large database compactions and associated performance degradation. It complements <code>TRANSITION_SLOTS_PER_BLOCK</code>, which limits how many <strong>storage slots</strong> are scanned per block in line with the minimal hardware recommendations. In short, <code>TRANSITION_SLOTS_PER_BLOCK</code> bounds read operations, while <code>TRANSITION_MAX_ACCOUNTS</code> bounds write operations.</p> <h3 id="comparison-with-depth-based-pricing">Comparison with depth-based pricing</h3> <p>The largest contract observed (XEN) sits around depth 9, meaning its relevant storage keys share a 9-nibble (~4.5 bytes) prefix along their MPT paths. Because the storage key into the trie is <code>keccak256(slot_key)</code>, an attacker can easily calculate the inputs offchain to find hashes and populate all contracts such that they pay the same cost as XEN.</p> <h3 id="why-is-a-transition-needed">Why is a transition needed?</h3> <p>If counting began only at <code>FORK_TIMESTAMP</code>, every existing contract would start with an implicit <code>storage_count = 0</code> and accrue counts only from <em>new</em> writes. While spammy contracts would quickly accumulate writes and thus incur penalties, this would still misprice the workloads we intend to regulate: large pre-fork contracts would continue paying unscaled base costs until they rewrote a substantial portion of their historical slots. During that period, gas pricing would understate their actual storage footprint.</p> <p>A deterministic, in-protocol transition avoids this. By iterating existing storage under consensus rules and progressively populating each account’s <code>storage_count</code> in the state, we ensure that storage-size-based pricing reflects reality for <em>all</em> contracts—regardless of whether they write again after the fork. Persisting cursor progress under the state root also makes the process reorg-safe and client-agnostic.</p> <p><strong>Alternative (pre-fork background counting by clients)</strong></p> <ul> <li><strong>Idea:</strong> Clients begin counting slots before <code>FORK_TIMESTAMP</code>. At activation, they only need to write the final counts into the state for a fixed number of accounts.</li> <li><strong>Pros:</strong> Reduces post-fork iteration work, much faster convergence at fork time since iterating all accounts is faster than all storage slots.</li> <li><strong>Cons:</strong> Late upgraders, snap-syncing nodes, or nodes that were offline cannot reconstruct pre-fork counts deterministically. This approach has to be coordinated so that all users upgrade their nodes and must finish counting prior to the fork activation. Reorgs have to be handled explicitly too.</li> </ul> <h3 id="compatibility-with-verkle-binary-unified-tree">Compatibility with Verkle/Binary unified tree</h3> <p>In the current two-layer MPT, a write to contract storage accesses an account path and then a storage path, and the cost a client pays in trie updates and database reads/writes correlates with how deep the storage trie becomes over time.</p> <p>Under a unified tree, the per-write computational and I/O cost of <code>SSTORE</code> no longer tracks an account’s total number of storage slots. The path length is set by the global tree’s branching factor and height, and by the overall distribution of state keys, not by a single account’s footprint. As a result, progressive pricing based on an account’s slot count can become misaligned with the actual work once a unified tree ships.</p> <h3 id="compatibility-with-eip-2926">Compatibility with EIP-2926</h3> <p>Because <a href="https://wg-eips.ritovision.com/2926/">EIP-2926</a> also requires an account transition to chunkify the bytecode and additional fields, scheduling both EIPs in the same fork enables a single, combined transition. This removes duplicated work, reduces client complexity and the number of tree transitions in the future.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found. Making the <code>storage_count</code> field optional ensures that the default count is 0, which means that contract will not be affected by the gas increase before they have been reached by the iterator sweep.</p> <p>This is a backwards incompatible gas repricing that requires a scheduled network upgrade.</p> <p>Node operators MUST update gas estimation handling to accommodate the new calldata cost rules. Specifically, RPC methods such as <code>eth_estimateGas</code> MUST incorporate the updated formula for gas calculation when encountering an <code>SSTORE</code>.</p> <p>Users and wallets can maintain their usual workflows without modification, as RPC updates will handle these changes.</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> 2025-09-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Rohan Parikhhttps://github.com/phiraml Jon Michael Rosshttps://github.com/jonmross https://wg-eips.ritovision.com/8033/

Multi-agent councils to resolve decentralized information queries

<h2 id="abstract">Abstract</h2> <p>This ERC defines a standard interface for oracle contracts that use multi-agent councils to resolve arbitrary information queries. It enables dApps to request resolutions, general information arbitration, and build consensus and validation in a trust-minimized way, with agents submitting answers to the queries on-chain. The ERC works by a requester opening a query to be resolved. The contract then emits the RequestCreated event with parameters specifying the query, number of infoAgents, commit deadline, and reward/bond amounts, specifications, and capabilities required. A commit phase is initiated where InfoAgents can participate by staking the required bond and submitting a hash of the answer to the query as a commit. After the quorum of infoAgents have committed, the reveal process is initiated where infoAgents post the key to the commit hash. A judgeAgent is then selected to review the committed hash and answers provided by the infoAgents. The judgeAgent then selects the infoAgents which answered the query correctly and the reward is divided among the winners. The infoAgents which answered incorrectly lose their bond. The interface supports permissionless participation, bond-based incentives, and optional extensions for reputation, disputes, and callbacks, making it suitable for applications like semantic data oracles and prediction markets.</p> <h2 id="motivation">Motivation</h2> <p>With AI agents advancing rapidly, we can build trust-minimized oracles that are cheaper, faster, and more scalable than traditional human or node-based systems. Traditional data oracles primarily provide quantitative feeds and are often centralized or expensive for arbitrary, one-off queries. With AI agents becoming reliable for factual resolutions from public sources, this EIP standardizes an interface for agent councils to handle query resolution via commit-reveal-judging flows, fostering interoperability across implementations. It is generalizable for discrete (defined options) or open-ended queries, with hooks for collusion deterrence and verification. Integration with reputation systems (such as that in <a href="https://wg-eips.ritovision.com/8004/">ERC-8004</a>) is recommended but optional to keep the core lightweight.</p> <p>This is generalizable for any resolvable information, making it useful for both qualitative and quantitative data. Existing examples we see this standard being useful for are, tracing information tasks (off-chain data processing with on-chain validation hooks), resolving prediction markets, and creating verified info feeds for DeFi platforms (aggregating real-time semantic data from multiple sources).</p> <p>We envision an information market evolving where agents compete to answer queries, exchanging data resolutions for tokenized incentives.</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 <code>IAgentCouncilOracle</code> interface, which defines methods and events for a council-based resolution flow. Implementations MUST support the core flow: request creation, agent commitment, reveal, judging/aggregation, and reward distribution. An OPTIONAL dispute resolution extension is also included. Off-chain processing (LLM inference and analysis) is handled by agents, with on-chain elements opened to coordination and verification of information.</p> <p>The council consists of two agent roles: Info Agents (who submit individual information) and Judge Agents (who aggregate and resolve consensus). We make this distinction to clarify how responsibilities from this standard are assigned.</p> <h3 id="main-types">Main Types</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Struct for query requests</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> AgentCapabilities</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span> capabilities</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> text, vision, audio etc</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span> domains</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Expertise areas</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"> Request</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> requester</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> rewardAmount</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Total reward (native token or ERC-20)</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> rewardToken</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> native or ERC-20 token</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> bondAmount</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Bond per agent (native token or ERC-20)</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> bondToken</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> native or ERC-20 token</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> numInfoAgents</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Target number of info agents</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> deadline</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Unix timestamp for commit phase end</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> query</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> The information query</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> specifications</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Additional miscellaneous instructions (optional in implementations)</span></span> <span class="giallo-l"><span> AgentCapabilities requiredCapabilities</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> For filtering agents (optional in implementations)</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"> IAgentCouncilOracle</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Events for transparency and monitoring</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RequestCreated</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> requestId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> requester</span><span>, </span><span class="z-support">string</span><span class="z-variable"> query</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> rewardAmount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> numInfoAgents</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> bondAmount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AgentCommitted</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> requestId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> agent</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> commitment</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AgentRevealed</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> requestId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> agent</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> answer</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Or bytes for flexibility</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> JudgeSelected</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> requestId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> judge</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ResolutionFinalized</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> requestId</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> finalAnswer</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Or bytes</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RewardsDistributed</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> requestId</span><span>, </span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-variable"> winners</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> amounts</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ResolutionFailed</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> requestId</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"> DisputeInitiated</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> requestId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> disputer</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"> DisputeWindowOpened</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> requestId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> endTimestamp</span><span>)</span><span>;</span></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">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> requestId</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> overturned</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> finalAnswer</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"> Core methods</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createRequest</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> query</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> numInfoAgents</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> rewardAmount</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> bondAmount</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> deadline</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> rewardToken</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> bondToken</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> specifications</span><span>,</span><span class="z-storage z-type"> AgentCapabilities</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> requiredCapabilities</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">uint256</span><span class="z-variable"> requestId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Commit: Permissionless, with bond</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> commit</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> requestId</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> commitment</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-comment"> //</span><span class="z-comment"> Reveal: Submit answer matching commitment</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> reveal</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> requestId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> answer</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> nonce</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"> Judge/Aggregate: Called by selected judge or automatic for discrete option queries</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> aggregate</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> requestId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> finalAnswer</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"> winners</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> reasoning</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Winners for reward classification</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Distribute: Auto or manual post-aggregation</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> distributeRewards</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> requestId</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 final resolution</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 class="z-support">uint256</span><span class="z-variable"> requestId</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"> finalAnswer</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> finalized</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 Dispute Methods</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> initiateDispute</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> requestId</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-storage z-type"> payable</span><span>;</span></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">uint256</span><span class="z-variable"> requestId</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> overturn</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> newAnswer</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"> newWinners</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"> Getters for oracle flow data</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getRequest</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> requestId</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">Request</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"> getCommits</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> requestId</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"> agents</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"> commitments</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getReveals</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> requestId</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"> agents</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"> answers</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>We do not enforce limits on the number or size of items in capabilities, domains, queries, or answers to maintain flexibility for evolving agent ecosystems and models. However, it is RECOMMENDED implementations impose reasonable limits on metrics such as the number of items (ex. max 64), bytes per item (ex. max 64), and/or total encoded bytes (ex. max 8192) to mitigate gas costs and DoS risks. Implementations MUST document any such limits in their code or README and MUST revert with descriptive errors (ex. CapListTooLong) if exceeded. For high-gas environments, implementations SHOULD use off-chain references (such as an IPFS hash on-chain or some external domain) for verbosity, storing only these references in the struct.</p> <h3 id="core-flow">Core Flow</h3> <p>Implementations MUST follow this sequence for interoperability:</p> <ol> <li> <p><strong>Request Creation</strong>: Requester calls <code>createRequest</code>, providing query, params (ex. <code>numInfoAgents</code>, <code>bondAmount</code>), and <code>rewardAmount</code> (with <code>msg.value</code> or <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> transfer). If <code>rewardToken == address(0)</code>, this is the native asset and createRequest MUST be payable and expect msg.value to fund the reward (and native bonds if used). If <code>rewardToken != address(0)</code>, it MUST be an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and implementations SHOULD pull funds via <code>transferFrom</code>. Emits <code>RequestCreated</code>. The bond is a slashable stake an agent put in, and be penalized if the submission turns out to be wrong, malicious etc. The amount and token for the bond (specified with <code>bondAmount</code> and <code>bondToken</code>) is implementation-specific and these MAY be different from the values used for the reward.</p> </li> <li> <p><strong>Commit Process</strong>: Permissionless Info Agents call <code>commit</code> with a hash (RECOMMENDED: <code>keccak256(abi.encode(answer, nonce))</code>) and bond. Caps at <code>numInfoAgents</code>. Phase ends at deadline or when all InfoAgents are committed. Emits <code>AgentCommitted</code>.</p> </li> <li> <p><strong>Reveal/Collection Process</strong>: Committed Info Agents call <code>reveal</code> to submit answers. MUST match commitment. Emits <code>AgentRevealed</code>. Proceed only if quorum (RECOMMENDED: &gt;50% reveals) otherwise emit <code>ResolutionFailed</code> and refund. This helps reduce coordination/collusion of submissions as they aren’t revealed early.</p> </li> <li> <p><strong>Judging Process</strong>: After reveals, select a Judge Agent (RECOMMENDED: randomly from a separate pool, distinct from Info Agents) and emit JudgeSelected. The Judge Agent calls aggregate to submit the final answer and classify winners (majority agents). For open-ended and discrete queries, the Judge MUST synthesize revealed submissions (semantic consensus via LLM) and provide reasoning as part of the submission. In ties, the Judge MAY provide a tie-breaker with reasoning. Emits ResolutionFinalized</p> </li> <li> <p><strong>Reward Distribution Process</strong>: Call <code>distributeRewards</code> to payout correct Info Agents / Judge Agent based on config (proportional or equal splits, with implementation specific params for ratios like Judge fee percentage). Refund bonds to correct Info Agents; forfeit others. Emits <code>RewardsDistributed</code>. Implementations MAY forfeit the Judge Agent’s bond and redistribute to correct Info Agents or proposer if the judge fails to resolve within the allotted window.</p> </li> </ol> <p>Off-chain storage (such as IPFS for reveals/reasoning) MAY be used, with on-chain hashes for verifiability.</p> <h3 id="optional-extensions">Optional Extensions</h3> <p><strong>Dispute Standard</strong>: Implementations MAY add a dispute mechanism post-finalization.</p> <p>Suggested flow: After finalization, open a dispute window. Any party MAY call <code>initiateDispute</code> with a <code>disputeBond</code> (ex. 1.5-2x original bond) and on-chain reason (such as a hash of detailed reasoning, optionally on IPFS), emitting <code>DisputeInitiated</code>. Re-select a Judge (randomly, with higher minReputation threshold). Judge reviews and calls <code>resolveDispute</code> to uphold or overturn, submitting new answers/winners if overturned. If upheld, the disputer’s bond is forfeited to the correct agents and arbitration creator. If overturned, return the disputer's bond, provide reimbursement (ex. a portion of the base fee), slash the original Judge's fee/bond, and redistribute. Dispute Judge receives reimbursement (ex. some fixed/percentage fee). Emits <code>DisputeResolved</code>.</p> <p>Configurable params: <code>disputeWindow</code> (duration), <code>disputeBond</code>, <code>minDisputeJudgeReputation</code> (higher than original), <code>disputerReimbursement</code>, <code>judgeReimbursement</code>. MAY integrate <a href="https://wg-eips.ritovision.com/8004/">ERC-8004</a> for re-runs/proofs with validation hooks; partial payouts/escrow during window for efficiency.</p> <p><strong>Reputation Hooks</strong>: MAY integrate with <a href="https://wg-eips.ritovision.com/8004/">ERC-8004</a> for filtering (min reputation for agents or judges) or proportional rewards. RECOMMENDED: Set a minimum reputation for Judge Agents, higher than for Info Agents, as they make a final decision. This creates an identifiable on-chain trail for accountability.</p> <p><strong>Callbacks</strong>: MAY add <code>callback(address target, uint256 requestId)</code> for notifying requester contracts.</p> <p><strong><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> Rewards</strong>: Extend with token transfers instead of the native token.</p> <p>Configs (such as phase durations, quorums, reward ratios) are implementation-specific parameters.</p> <h2 id="rationale">Rationale</h2> <p>This interface standardizes a council flow for AI-driven oracles, balancing minimal on-chain logic with off-chain flexibility. Commit-reveal prevents front-running and judging enables consensus on complex queries. Bonds and optional reputation help deter attacks.</p> <p>Reputation scores provide a rationale for enhanced security: they enable proportional reward distribution, gating participation to experienced agents, and reducing collusion risks by aligning incentives with proven performance. Without reputation, attack vectors may increase, but the core bond system offers baseline protection and we expect this baseline to allow for a self regulating rewards incentive market that drives agents to act in good faith.</p> <p>We considered a single-round, plaintext submission model. While simpler and cheaper, it is susceptible to (i) copying attacks where later agents replicate early submissions, (ii) MEV/front-running of plaintext answers, and (iii) coercion/censorship risks when answers must be revealed before full participation. Plain text answers are easily identified and may be delayed, susceptible to being reordered, or unfavorable answers may be censored compromising the integrity of the Info Agents answers. By contrast, a commit-reveal flow keeps content hidden during the commit phase: adversaries cannot cheaply target specific answers.</p> <p>Weighted voting (a common alternative in oracles like Universal Market Access) was evaluated as a potential replacement for distinct roles where agents could stake bonds or reputation to vote with proportional influence. This could reduce moving parts but weakens explainability and accountability for open-ended queries. Instead, a Judge allows for semantic interpretation of answers. Our role-based approach mitigates this by random Judge selection and optional reputation thresholds, promoting broader participation while maintaining checks (Judge Agents can tie-break with reasoning). <em>This also aligns better with AI agent ecosystems, where specialized agents mirror real-world councils or juries, fostering an "information market".</em> A lack of a Judge Agent would limit the ERC to only discrete information and make it unclear how non-discrete data is resolved. We standardize the Info/Judge split for the core flow (specialization + reasoning from the Judge), while <strong>leaving weighted aggregation as an OPTIONAL extension</strong> for discrete queries.</p> <p>Using a single agent reduces complexity but mixes retrieval/synthesis with adjudication. We determined that explicit role separation enables (a) different capability/reputation thresholds, (b) clearer slashing semantics for adjudication failures, and (c) better human-auditable reasoning trails. We intentionally separate roles for specialization and explainability.</p> <p>The commit-reveal process is more gas-intensive (requiring two transactions per Info Agent: commit and reveal) but provides increased security through ease of verifiability and reduced attack surfaces like front-running. The increased gas is offset by preventing costly disputes from copied or manipulated answers. Other existing commit-reveal mechanisms were considered but were too constrained for our resolution flow and would have increased complexity. For example, <a href="https://wg-eips.ritovision.com/5732/">ERC-5732</a> does not provide a built-in reveal mechanism. The reveal is a critical step in the agent council flow to ensure quorum and prevent collusion. The <a href="https://wg-eips.ritovision.com/162/">ERC-162</a> commit and reveal process was also considered but is not easily applicable to text fields and resolution flow here.</p> <p>Longer form responses written directly to the blockchain may be gas-prohibitive for complex queries so off-chain storage like IPFS for larger reveals/reasoning is recommended, with on-chain hashes for integrity. This trades some security (IPFS links are not permanent and could be censored) for cost savings, but implementations can mitigate this via decentralized pinning services or agent domains from <a href="https://wg-eips.ritovision.com/8004/">ERC-8004</a>. Creating different schemes for off-chain verifiability significantly increases complexity. To enhance usability, our core interface keeps methods lightweight, and optional extensions like disputes remain modular, allowing simple implementations for low-stakes queries while scaling to high-security ones.</p> <p>This ERC is meant to be complimentary to recent standards like <a href="https://wg-eips.ritovision.com/8004/">ERC-8004</a>, which provides a foundational step toward enabling agent-to-agent communication. Features like Identity, Reputation, and Validation can strengthen the verifiability and fidelity of answers from Info Agents and rulings from Judge Agents. For instance, implementations can filter participants via <a href="https://wg-eips.ritovision.com/8004/">ERC-8004</a>'s reputation scores (minReputation params for agents). They can also use validation hooks to verify off-chain computations cryptographically, reducing reliance on bonds alone. <strong>The framework for Agent Council Oracles differs significantly. It focuses on a standard mechanism for agents to reach consensus without human input, emphasizing on-chain coordination flows (commit-reveal-judge) for query resolution.</strong> While <a href="https://wg-eips.ritovision.com/8004/">ERC-8004</a> is geared toward trustless agent interoperability and off-chain logic, our EIP builds atop it by standardizing automated information arbitration. This can apply to specific use cases such as data oracles or prediction markets. The integration with <a href="https://wg-eips.ritovision.com/8004/">ERC-8004</a> is optional to keep the core lightweight, but recommended for high-stakes scenarios. Other differentiators unique to our standard include our bond incentives and dispute windows, which add economic security layers otherwise absent in multi-agent coordination layers.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No conflicts with existing standards.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>Collusion: Mitigated by bonds (refundable for honest participation, forfeited for failures), random judge selection, and optional reputation. Bonds disincentivize spam and non-reveals by redistributing to participants.</li> <li>Spam: Prevented by bonds and caps.</li> <li>Failures: Refunds for low participation or abandonment.</li> <li>Disputes: Optional for high-stakes, with higher stakes/thresholds.</li> <li>Fairness of random selection of Judge relies on the crypto strength of randomness Implementations should audit for reentrancy and use verifiable randomness.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-09-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 Lawliet Chanhttps://github.com/lawliet-chan https://wg-eips.ritovision.com/8099/

A protocol that prevents MEV attacks by constraining transaction ordering through blind sequencing and two-phase block execution.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces the MEVless protocol, a novel approach to prevent Maximum Extractable Value (MEV) attacks by implementing blind transaction sequencing. The core principle of MEVless is to prevent validators from seeing transaction content during the ordering phase, thereby eliminating the fundamental prerequisite for MEV attacks. The protocol separates block production into two phases: sequencing blocks that order transactions based on transaction hashes without revealing transaction content, and execution blocks that execute transactions in the predetermined order. This design eliminates the ability of miners and validators to perform MEV attacks such as sandwich attacks and front-running by removing their access to transaction content during the critical ordering phase.</p> <h2 id="motivation">Motivation</h2> <p>MEV attacks, particularly sandwich attacks and front-running, represent a significant threat to blockchain ecosystems, especially in DeFi applications. The fundamental prerequisite for MEV attacks is that validators can see transaction content before ordering, which allows them to:</p> <ol> <li><strong>Sandwich Attacks</strong>: Insert buy and sell transactions around user transactions to manipulate prices and extract value</li> <li><strong>Front-running</strong>: Execute similar transactions before users to capture arbitrage opportunities</li> <li><strong>Back-running</strong>: Execute transactions after users to benefit from price movements</li> </ol> <p>Unlike legitimate arbitrage activities that provide liquidity, these attacks are purely extractive and harmful to the ecosystem. They reduce user confidence, increase transaction costs, and can lead to significant financial losses for users.</p> <p>Current solutions have limitations:</p> <ul> <li><strong>Encrypted Mempools</strong>: High computational overhead for encryption/decryption</li> <li><strong>Private Mempools</strong>: Centralized and not fully decentralized, use trustful instead of trustless.</li> <li><strong>PBS (Proposer-Builder Separation)</strong>: Still allows builders to see transaction content and becoming more and more centralized.</li> </ul> <p>The MEVless protocol addresses these issues by fundamentally changing how transactions are ordered, making it impossible for miners to perform MEV attacks while maintaining decentralization and efficiency. By eliminating MEV attacks at the protocol level, DeFi developers can focus on building innovative financial products and user experiences without constantly worrying about MEV protection mechanisms, leading to faster development cycles and more robust applications.</p> <h2 id="specification">Specification</h2> <h3 id="protocol-overview">Protocol Overview</h3> <p>The MEVless protocol operates on a two-phase block system:</p> <ol> <li><strong>Sequencing Blocks</strong>: Order transactions based on transaction hashes and prepayment amounts without revealing transaction content. Sequencing blocks interval can be shorter than execution blocks.</li> <li><strong>Execution Blocks</strong>: Execute transactions in the predetermined order from sequencing blocks</li> </ol> <h3 id="block-types">Block Types</h3> <h4 id="sequencing-blocks">Sequencing Blocks</h4> <ul> <li><strong>Purpose</strong>: Order transactions and collect prepayments</li> <li><strong>Frequency</strong>: Every odd-numbered block height</li> <li><strong>Operations</strong>: <ul> <li>Receive transaction hashes from users</li> <li>Collect prepayments (gas fees + optional tips)</li> <li>Order transactions by prepayment amount (highest first)</li> <li>Publish ordered transaction sequence as commitment</li> <li>Store transaction hashes in block</li> </ul> </li> </ul> <h4 id="execution-blocks">Execution Blocks</h4> <ul> <li><strong>Purpose</strong>: Execute transactions in predetermined order</li> <li><strong>Frequency</strong>: Every even-numbered block height</li> <li><strong>Operations</strong>: <ul> <li>Receive transaction content from users</li> <li>Verify transaction content matches committed hashes</li> <li>Execute transactions in predetermined order</li> </ul> </li> </ul> <h3 id="transaction-flow">Transaction Flow</h3> <h4 id="phase-1-transaction-submission-and-sequencing">Phase 1: Transaction Submission and Sequencing</h4> <ol> <li>User creates transaction and calculates transaction hash</li> <li>User sends transaction hash to the network with prepayment: <ul> <li><strong>Base Gas Fee</strong>: Fixed fee for hash storage and sequencing computation</li> <li><strong>Optional Tip</strong>: Additional payment for priority in sequencing</li> </ul> </li> <li>Network validates user has sufficient balance for prepayment</li> <li>Network orders transaction hashes by total prepayment amount (descending)</li> <li>Network deducts prepayment from user account</li> <li>Network publishes ordered transaction sequence as commitment</li> <li>Network stores transaction hashes in sequencing block</li> </ol> <p><img src="https://wg-eips.ritovision.com/8099/./assets/MEVless.png" alt="MEVless Protocol Flow" /> <em>MEVless Protocol Transaction Flow</em></p> <h4 id="phase-2-transaction-content-submission-and-execution">Phase 2: Transaction Content Submission and Execution</h4> <ol> <li>User monitors network for their transaction hash commitment</li> <li>User submits actual transaction content(including the remaining gasfee) to network</li> <li>Network receives transaction content during execution block</li> <li>Network verifies transaction content matches committed hash</li> <li>Network executes transactions in predetermined order, deduct the remaining fee and 50% of the actual difference between gasUsed and gaslimit for tax ( prevent the gasLimit much more than gasUsed so that validators can entire the whole block to get MEV)</li> </ol> <h3 id="gas-economics">Gas Economics</h3> <h4 id="prepayment-structure">Prepayment Structure</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Total Prepayment = Base Gas Fee + Optional Tip</span></span></code></pre> <ul> <li><strong>Base Gas Fee</strong>: Fixed cost for hash storage and sequencing computation</li> <li><strong>Optional Tip</strong>: Variable amount for priority in transaction ordering</li> </ul> <h4 id="gas-cost-calculation">Gas Cost Calculation</h4> <ul> <li><strong>Sequencing Phase</strong>: Minimal gas cost for hash operations</li> <li><strong>Execution Phase</strong>: Standard gas cost for transaction execution</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="why-blind-sequencing">Why Blind Sequencing?</h3> <p>Blind sequencing eliminates the root cause of MEV attacks by preventing miners from seeing transaction content during the critical ordering phase. This approach is more efficient than encryption-based solutions and more decentralized than private mempool approaches.</p> <h3 id="why-two-phase-blocks">Why Two-Phase Blocks?</h3> <p>Separating sequencing and execution allows for:</p> <ul> <li><strong>Efficient Ordering</strong>: Hash-based ordering is computationally lightweight</li> <li><strong>Network Efficiency</strong>: Small hash data reduces bandwidth requirements</li> <li><strong>Commitment Mechanism</strong>: Public ordering commitment prevents manipulation</li> </ul> <h3 id="why-random-block-production-is-critical">Why Random Block Production is Critical?</h3> <p>Random block production is essential to prevent speculative MEV attacks. When block producers cannot predict when they will be selected to produce blocks, they cannot reliably perform speculative MEV attacks because:</p> <ul> <li><strong>Unpredictable Selection</strong>: Attackers cannot know if they will be the next block producer</li> <li><strong>Economic Risk</strong>: Speculative transactions require prepayments that are lost if the attacker is not selected</li> <li><strong>Decentralization Amplification</strong>: More validators mean lower individual selection probability, increasing attack costs exponentially</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This protocol will add some RPC methods to support the two-phase block system:</p> <ul> <li><strong>eth_sendTxHash</strong>: Users submit transaction hashes instead of full transactions</li> <li><strong>eth_getTxSequence</strong>: Returns the ordered transaction sequence that is committed</li> </ul> <h2 id="test-cases">Test Cases</h2> <h3 id="basic-transaction-flow">Basic Transaction Flow</h3> <ol> <li>User submits transaction hash with prepayment</li> <li>Network orders transaction by prepayment amount</li> <li>User submits transaction content</li> <li>Network executes transaction in predetermined order</li> </ol> <h3 id="mev-attack-prevention">MEV Attack Prevention</h3> <ol> <li>Attacker submits transaction hash for sandwich attack</li> <li>Network orders transaction without revealing content</li> <li>Attacker cannot see victim transaction content during ordering</li> <li>Attack fails due to lack of transaction visibility</li> </ol> <h2 id="security-considerations">Security Considerations</h2> <p>The MEVless protocol requires a consensus mechanism with unpredictable block production to prevent speculative MEV attacks. Without unpredictable block production, block producers can perform cost-free speculative MEV attacks by submitting transaction hashes and then deciding whether to submit their transaction content based on other users' transaction content, thus performing cost-free speculative MEV attacks. Since the prepayment ultimately goes to the block producer themselves, predictable block production allows them to recover their prepayment costs through block fees, making MEV attacks economically viable. Random block production forces attackers to pay prepayments for speculative transactions without knowing if they will be selected to produce the next block, making the prepayment cost real rather than recoverable through block fees, thus making such attacks economically unviable. The anti-MEV effectiveness increases exponentially with network decentralization - more validators mean lower individual selection probability, making attacks economically unviable.</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-09-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 James Kemptonhttps://github.com/SirSpudlington https://wg-eips.ritovision.com/8030/

Adds an EIP-7932 algorithm type for P256 support of type `0x0`

<h2 id="abstract">Abstract</h2> <p>This EIP adds a new <a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a> algorithm of type <code>0x0</code> for supporting P256 signatures.</p> <h2 id="motivation">Motivation</h2> <p>P256 (a.k.a secp256r1) is a widely-used NIST standardized algorithm that already has a presence within the Ethereum codebase. This makes it a great algorithm to write test cases against implementations of <a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a>.</p> <h2 id="specification">Specification</h2> <p>This EIP defines a new <a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a> algorithmic type with the following parameters:</p> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>ALG_TYPE</code></td><td><code>Bytes1(0x0)</code></td></tr> <tr><td><code>SIZE</code></td><td><code>129</code></td></tr> </tbody></table> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>N</span><span class="z-keyword"> =</span><span class="z-storage z-type"> 0x</span><span class="z-constant">ffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551</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_cost</span><span>(</span><span class="z-variable z-parameter z-function">signing_data</span><span>:</span><span> Bytes</span><span>)</span><span> -&gt;</span><span> Uint64</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> This is the precompile cost from [EIP-7951](./07951.md) with 3000 gas</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> subtracted (the cost of the secp256k1 precompile)</span></span> <span class="giallo-l"><span class="z-constant"> BASE_GAS</span><span class="z-keyword"> =</span><span> Uint64</span><span>(</span><span class="z-constant">3900</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 extra overhead for keccak256 hashing</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>signing_data</span><span>)</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 class="z-constant"> BASE_GAS</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> minimum_word_size</span><span class="z-keyword"> =</span><span> (</span><span class="z-support">len</span><span>(</span><span>signing_data</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"> 32</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> BASE_GAS</span><span class="z-keyword"> +</span><span> Uint64</span><span>(</span><span class="z-constant">30</span><span class="z-keyword"> +</span><span> (</span><span class="z-constant">6</span><span class="z-keyword"> *</span><span> minimum_word_size</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"> validate</span><span>(</span><span class="z-variable z-parameter z-function">signature</span><span>:</span><span> Bytes</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span class="z-keyword"> |</span><span> Error</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> This function is a noop as there is no</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> exposed function defined in [EIP-7951](./07951.md)</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"> verify</span><span>(</span><span class="z-variable z-parameter z-function">signature</span><span>:</span><span> Bytes</span><span>,</span><span class="z-variable z-parameter z-function"> signing_data</span><span>:</span><span> Bytes</span><span>)</span><span> -&gt;</span><span> Bytes</span><span class="z-keyword"> |</span><span> Error</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>signing_data</span><span>)</span><span class="z-keyword"> !=</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"> Hash if non-standard size</span></span> <span class="giallo-l"><span> signing_data</span><span class="z-keyword"> =</span><span> keccak256</span><span>(</span><span>signing_data</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"> Ignore initial alg_type byte</span></span> <span class="giallo-l"><span> signature</span><span class="z-keyword"> =</span><span> signature</span><span>[</span><span class="z-constant">1</span><span>:</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> (</span><span>r</span><span>,</span><span> s</span><span>,</span><span> x</span><span>,</span><span> y</span><span>)</span><span class="z-keyword"> =</span><span> (</span><span>signature</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">32</span><span>]</span><span>,</span><span> signature</span><span>[</span><span class="z-constant">32</span><span>:</span><span class="z-constant">64</span><span>]</span><span>,</span><span> signature</span><span>[</span><span class="z-constant">64</span><span>:</span><span class="z-constant">96</span><span>]</span><span>,</span><span> signature</span><span>[</span><span class="z-constant">96</span><span>:</span><span class="z-constant">128</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"> This is similar to [EIP-2](./00002.md)&#39;s malleability verification.</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span>s</span><span class="z-keyword"> &lt;=</span><span> N</span><span class="z-keyword">/</span><span class="z-constant">2</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 is defined in [P256Verify Function](#p256verify-function)</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span>P256Verify</span><span>(</span><span>signing_data</span><span>,</span><span> r</span><span>,</span><span> s</span><span>,</span><span> x</span><span>,</span><span> y</span><span>)</span><span class="z-keyword"> ==</span><span> Bytes</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0000000000000000000000000000000000000000000000000000000000000001</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-keyword"> return</span><span> x</span><span>.</span><span>to_bytes</span><span>(</span><span class="z-constant">32</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">big</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword"> +</span><span> y</span><span>.</span><span>to_bytes</span><span>(</span><span class="z-constant">32</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">big</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span></code></pre><h3 id="p256verify-function"><code>P256Verify</code> Function</h3> <p>The <code>P256Verify</code> function is the logic of the precompile defined in <a href="https://wg-eips.ritovision.com/7951/">EIP-7951</a>, the only exception is that this function MUST NOT charge any gas.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-p256">Why P256?</h3> <p>P256 or secp256r1, is used globally but (more importantly) has an existing implementation in all execution clients. This allows easy implementation of a known-safe algorithm, which is perfect for a test algorithm.</p> <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-09-17T00:00:00+00:00 2026-02-11T14:49:27+00:00 Kevaundray Wedderburnhttps://github.com/kevaundray Justin Drakehttps://github.com/JustinDrakejustin@ethereum.org https://wg-eips.ritovision.com/8025/

Introducing optional execution proofs on the consensus layer

<h2 id="abstract">Abstract</h2> <p>Optional execution proofs allow beacon nodes to verify the validity of the execution payload within a beacon block without running an execution layer client. The execution proofs are sent over the consensus layer's peer-to-peer network.</p> <h2 id="motivation">Motivation</h2> <p>Optional execution proofs reduce the hardware and bandwidth requirements that are needed for an attester to verify a beacon block. Moreover, the cost to verify to a block no longer grows with the gas limit.</p> <p>Since these are optional, protocol upgrades cannot be based on the improvements in this EIP. This EIP allows us to safely test execution proofs without making it explicitly consensus critical.</p> <h2 id="specification">Specification</h2> <p>This is a consensus layer change only.</p> <p>Validators will now be able to enable two new modes:</p> <ul> <li>zkEVM Proof generating</li> <li>Stateless validation</li> </ul> <p>When a proof generating node receives a beacon block, they will create the necessary proofs for the execution payload in the block and re-propagate them on the specified subnets.</p> <p>When a stateless validating node receives a beacon block, they will check to see if they have already received a valid execution proof for that execution payload from the specified subnet.</p> <p>The detailed specifications are in the consensus-specs repository.</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> <p>&lt;-- TODO --&gt;</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is backwards compatible and does not require a hardfork.</p> <h2 id="test-cases">Test Cases</h2> <p>&lt;-- TODO --&gt;</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>&lt;-- TODO --&gt;</p> <h2 id="security-considerations">Security Considerations</h2> <p>&lt;-- TODO --&gt;</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-09-16T00:00:00+00:00 2026-02-11T14:48:25+00:00 David Kimhttps://github.com/PowerStream3604 https://wg-eips.ritovision.com/8023/

Contract ownership management with multi-step ownership transfer mechanism for secure smart contract ownership

<h2 id="abstract">Abstract</h2> <p>We define a multi-stepped contract ownership interface for more secure contract ownership management. This makes the ownership transfer into 3 distinct steps. With the first 2 steps, performed by the original owner (initiate → confirm) and the remaining 1 step performed by the new owner (accept).</p> <p>We enforce an optional time window between the initiate and confirm stages to give additional room for review, and make ownership key compromise scenarios less fatal.</p> <h2 id="motivation">Motivation</h2> <p>Ownership management is crucial in on-chain security and a significant portion of the security assumptions of defi protocols, smart contract wallets and on-chain utilities rely on the contract ownership.</p> <p>The single-step <code>transferOwnership()</code> style ownership mechanism has been in the industry for a long time, (e.g.,<a href="https://wg-eips.ritovision.com/173/">ERC-173</a>), and has been used ubiquitously as an industry standard. As the industry evolves and attacks get more sophisticated there is a strong need for a multi-step, time gated ownership management process to enhance the ecosystem’s contract ownership to be more reviewable, stoppable, thorough and secure.</p> <p>The main objective of this standard is to make ownership more secure and handled in a multi-stepped approach that enables the operation to be conducted with more caution and lesser operational mistakes, while being immune to potential scam attacks.</p> <p>Key factors taken into consideration for the standard:</p> <ol> <li>Reduce probability of operational mistakes.</li> <li>Foster on-chain reviewal practice for ownership transfer.</li> <li>Ability to rollback ownership transfer, during the transfer process.</li> <li>Simplicity.</li> </ol> <p><strong>1. Reduce probability of operational mistakes:</strong> The standard makes the ownership transfer stage into 3 different clear steps. Initiation → Confirmation → Acceptance. The owner will have the enforced ability to review the newOwner address secured by the pre-set buffer time. Also to reduce any operational mistakes or possible scams (e.g., address poisoning) the address is required as the parameter in each Initiation &amp; Confirmation stage.</p> <p><strong>2. Foster on-chain reviewal practice for ownership transfer:</strong> We not only targets this as a contract interface and implementation methodology, but also hopes to foster an ecosystem-level awareness and security practice to thoroughly review, confirm the ownership transfer. The standard helps operators of Smart Contract to review newOwner address on-chain, and further confirm again if the address is indeed correct.</p> <p><strong>3. Ability to rollback ownership transfer, during the transfer process:</strong> Whether through an operational mistake or private key leak of owner account, or other reasons, the ability to rollback ownership transfer within the time buffer highly increases the security and operational burden.</p> <p>Even in the extreme case of owner private key leak, if the buffer time is set enough, the original owner can earn time to evacuate the funds from the protocol, and possibly prohibit ownership transfer through DoS of ownership (attack → initiate , original owner(defender) → re initiate. which will reset the time back to 0).</p> <p><strong>4. Simplicity:</strong> <code>MultistepOwnable</code> is targeted to be a simple contract given the diverse use cases and scenarios it could be applied. The process for ownership transfer is concise but thorough enough to allow owners review each step. This is the rationale behind making the ownership transfer time buffer and buffer time update capability optional.</p> <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> <p>A multi-step ownable contract 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-storage z-type"> @title</span><span class="z-comment"> Multistep Ownership Standard</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> MultiStepOwnable</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"> OwnershipTransferInitiated</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> prevOwner</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></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> OwnershipTransferConfirmed</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> prevOwner</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 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"> prevOwner</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"> @dev</span><span class="z-comment"> initiate the ownership transfer. First step of ownership transfer.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> moves the newOwner to the preConfirmed stage.</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"> ///</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-comment"> ///</span><span class="z-comment"> stored as preConfirmedOwner.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> initiateOwnershipTransfer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> 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 class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> confirm the ownership transfer. Second step of ownership transfer.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> confirmation can only be done after the transfer-buffer period from initiation.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> newOwner should match with the initiation step&#39;s newOwner.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> To initiate ownership transfer to a different newOwner, initiation step should be re-conducted.</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"> newOwner</span><span class="z-comment"> the address of the new owner of the contract.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> stored as pendingOwner.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> confirmOwnershipTransfer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> 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 class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> cancels the pending ownership transfer. Before the final step of ownership transfer (acceptOwnershipTransfer()).</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This function should wipe out the pendingOwner.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> By calling this function, ownership transfer process is canceled and should be reinitiated from initiateOwnershipTransfer().</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> cancelPendingOwnershipTransfer</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"> @dev</span><span class="z-comment"> accepts the ownership transfer. Final step of ownership transfer.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This function can only be called by the newOwner that was confirmed in step 2.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The contract should perform access control e.g.,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> msg.sender == pendingOwner()</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptOwnershipTransfer</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 class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> only the address returned by owner() has authority as the owner.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> pendingOwner() and preConfirmedOwner() should not possess any</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> authority/access/right.</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 owner of the contract</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 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"> @dev</span><span class="z-comment"> returns the pending owner of the account.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> pending owner should not have any authority/access/right.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> pendingOwner</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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> returns the pre-confirmed owner of the account.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> pre-confirmed owner should not have any authority/access/right.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> preConfirmedOwner</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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> returns the ownership transfer buffer time (in seconds).</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the buffer is enforced between initiation &lt;&gt; confirmation of ownership transfer. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the standard does not enforce the value range. it is highly recommended to be between 2 &lt;&gt; 14 days.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getOwnershipTransferBuffer</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></span></code></pre> <p>The <code>MultiStepOwnable</code> contract MAY implement the <code>UpdateableOwnershipTransferBuffer</code> interface to enable buffer period modification.</p> <p>The contract MUST update the buffer period with a 2 step approach of initiation (<code>initiateOwnershipBufferUpdate()</code>) and then confirmation (<code>confirmOwnershipBufferUpdate()</code>) after the existing buffer period. The buffer period should be enforced between these 2 function calls. If this behavior is not enforced, the security of <code>ownershipTransferBuffer</code> could break during owner key compromise scenario.</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"> UpdateableOwnershipTransferBuffer. Extension of MultiStepOwnable.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> UpdateableOwnershipTransferBuffer</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"> initiates the update of ownership transfer time buffer.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> initiateOwnershipBufferUpdate</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> newBuffer</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"> @dev</span><span class="z-comment"> confirms the update of ownership transfer time buffer.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> confirmation SHOULD revert if existing time buffer did not pass since</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> initiation of ownership transfer time buffer.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> confirmOwnershipBufferUpdate</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> newBuffer</span><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> <ol> <li> <p>A time buffer for ownership transfer is introduced to foster a process of reviewing the new owner address on-chain. However, this remains an optional behavior to allow flexibility in ownership management. Removing the optional time buffer would be similar to the implementation of <code>Ownable2Step</code> with an additional step for confirmation.</p> </li> <li> <p>Enforcing a time buffer to update the ownership transfer time buffer is crucial for maintaining the security of the <code>MultiStepOwnable</code> contract. When the owner key is compromised, this allows the original owner of the account to be able to DoS and prohibit the ownership transfer to the malicious entity when the ownership transfer buffer is sufficiently long enough.</p> </li> <li> <p>For compatibility with existing ownership mechanisms, the standard is designed to be compatible with the existing ownership mechanism for fetching the owner through <code>owner()</code>.</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>TBD <!-- TODO --></p> <h2 id="security-considerations">Security Considerations</h2> <ol> <li>Only owner should be available to call <code>initiateOwnershipTransfer()</code> &amp; <code>confirmOwnershipTransfer()</code> &amp; <code>cancelPendingOwnershipTransfer()</code>.</li> <li><code>OwnershipTransferBuffer</code> should be set together when owner is set. e.g., <code>constructor()</code>, <code>initialize()</code>.</li> <li>If <code>OwnershipTransferBuffer</code> is set, it should be strictly enforced between initiation and confirmation.</li> <li>Before the new owner performs <code>acceptOwnership()</code>, the original, existing owner should still hold all rights as the owner. Because the owner is still unchanged.</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> 2025-09-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ivo Georgievhttps://github.com/Ivshti Vijay Krishnavanshihttps://github.com/vijaykrishnavanshi https://wg-eips.ritovision.com/8019/

Defines a wallet-local allowlist for automatic signing of ERC-4361 messages when simple match rules succeed.

<h2 id="abstract">Abstract</h2> <p>Defines a wallet-local allowlist for automatic signing of <a href="https://wg-eips.ritovision.com/4361/">ERC-4361</a> messages when simple, deterministic match rules succeed. Policies are created and managed only by the wallet/user.</p> <h2 id="motivation">Motivation</h2> <p>Users repeatedly sign identical Sign-In With Ethereum (SIWE) messages for trusted apps. A small, explicit match policy enables zero-prompt login without involving apps.</p> <p>Users already get prompted by their wallets if they trust a certain app when they initially connect to it - this flow can also authorize auto-login if applicable.</p> <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 term “wallet” refers to wallet user interfaces, regardless of whether mobile, web-based or browser extensions.</p> <h3 id="overview">Overview</h3> <p>Each allow-policy is 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">domain</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">example.com</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"> exact match to SIWE domain</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uriPrefix</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">https://example.com/</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"> SIWE URI MUST start with this</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowedChains</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> [</span><span class="z-constant">1</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> list of allowed chainIds</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowedResources</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">https://example.com/login</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> exact set match</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">supportsEIP6492</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-constant">true</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> required for smooth UX when using hardware wallets</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">expiresAt</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-constant">1700000000000</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> UNIX timestamp when this policy expires, or 0 for no expiry</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="auto-sign-rule">Auto-sign rule</h3> <p>Given a parsed <a href="https://wg-eips.ritovision.com/4361/">ERC-4361</a> message <code>M</code>, the wallet <strong>MAY</strong> auto-sign <strong>if</strong>:</p> <ol> <li><code>M.domain == policy.domain</code></li> <li><code>M.uri</code> <strong>startsWith</strong> <code>policy.uriPrefix</code></li> <li>If M.chainId present: <code>M.chainId</code> is in <code>policy.allowedChains</code></li> <li>If policy.allowedResources non-empty: the set of <code>M.resources</code> is a subset of <code>policy.allowedResources</code> (order does not matter); otherwise no resources will be allowed at all</li> <li>If <code>policy.expiresAt</code> is non-zero, the current time is less than <code>policy.expiresAt</code></li> </ol> <p>All other SIWE validations (nonce uniqueness, time validity, signature domain binding) remain as per <a href="https://wg-eips.ritovision.com/4361/">ERC-4361</a> and MUST be enforced by the wallet.</p> <h3 id="management-of-policies">Management of policies</h3> <p>Policies are created, listed, updated, and deleted <strong>only</strong> within the wallet UI - wallets decide how much control they want to give to users over this.</p> <p>It’s recommended that each wallet:</p> <ul> <li>includes a default list of policies for popular apps</li> <li>automatically creates policies for apps that it considers safe, after the first SIWE signature, with user consent - this implies a different flow where, upon receiving the SIWE message sign request, the wallet will not go through the regular message signing flow, but prompt the user “App X wants to log-in with your account” with a checkbox to “Automatically sign into <app hostname> in the future”</li> </ul> <p>There’s no app-provided hints or headers that influence policy creation.</p> <h3 id="hardware-wallet-compatibility-and-erc-6492">Hardware wallet compatibility and <a href="https://wg-eips.ritovision.com/6492/">ERC-6492</a></h3> <p>Auto-signing is not viable with hardware wallet accounts, as the user will be prompted without context or expectation to sign the login message.</p> <p>This is why we include the <code>supportsEIP6492</code> property. If it is set to <code>false</code>, the wallet MUST not auto-login if the account's primary signer is a hardware wallet, as the app has no way of verifying a smart contract signature.</p> <p>However, if it's set to <code>true</code>, the wallet MAY perform auto-login as long as 1) it can enable <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> on the account OR the account is a smart account 2) it can authorize a limited-scope session key or delegation just for the auto-login. If said conditions are met, the wallet MAY generate a login signature without prompting the user on their hardware device. That said, enabling EIP-7702 and the session key/delegation will require prompting the user, so it's up to the wallet to walk the user through it. The exact mechanism of how wallets should manage the session key/delegation is out of scope of this ERC, but <a href="https://wg-eips.ritovision.com/7710/">ERC-7710</a> may be used.</p> <h3 id="rpc-method">RPC method</h3> <p>Wallets MAY implement an RPC method, <code>wallet_getCurrentAutoLoginPolicy</code>, which has no parameters and returns an object describing the current policy for the calling app.</p> <pre class="giallo z-code"><code data-lang="json"><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 object that describes the active policy, or null</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">activePolicy</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">domain</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">example.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">uriPrefix</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://example.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">allowedChains</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-constant">1</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">allowedResources</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">https://example.com/login</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">supportsEIP6492</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">expiresAt</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1700000000000</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The response of this method allows apps to determine whether they can self-initiate login requests without user interaction.</p> <p>If this ERC is disabled in the wallet, or there is no active policy for the calling app, the wallet MUST return <code>null</code> for <code>activePolicy</code>.</p> <p>It's recommended that the wallet returns <code>null</code> if the policy has expired or the app is connected on a non-allowed chain.</p> <h2 id="rationale">Rationale</h2> <ul> <li>This ERC is designed with minimal modifications to existing apps in mind</li> <li>From a security perspective, it's much easier to "outsource" the job of determining which apps to enable to this policy for to wallets - most wallets already maintain lists of "trusted" apps</li> <li><a href="https://wg-eips.ritovision.com/712/">EIP-712</a> (typed data) is out of scope due to SIWE deciding to build on plain text.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Backwards compatibility is one of the main goals of this ERC, and it requires no changes to existing apps, building upon <a href="https://wg-eips.ritovision.com/4361/">ERC-4361</a> as-is.</p> <p>To fully take advantage of this ERC, apps need to self-initiate the login request rather than expecting users to press a log-in button (using <code>wallet_getCurrentAutoLoginPolicy</code>).</p> <h2 id="reference-implementation">Reference Implementation</h2> <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"> shouldAutoSign</span><span>(</span><span class="z-variable">M</span><span>,</span><span class="z-variable"> P</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-other z-constant">M</span><span>.</span><span class="z-variable z-other">domain</span><span class="z-keyword"> !==</span><span class="z-variable z-other z-constant"> P</span><span>.</span><span class="z-variable z-other">domain</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> false</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 z-constant">M</span><span>.</span><span class="z-variable z-other">uri</span><span>.</span><span class="z-entity z-name">startsWith</span><span>(</span><span class="z-variable z-other z-constant">P</span><span>.</span><span class="z-variable z-other">uriPrefix</span><span>)</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> false</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 z-constant">P</span><span>.</span><span class="z-variable z-other">allowedChains</span><span>.</span><span class="z-entity z-name">includes</span><span>(</span><span class="z-variable z-other z-constant">M</span><span>.</span><span class="z-variable z-other">chainId</span><span>)</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-other z-constant">M</span><span>.</span><span class="z-variable z-other">resources</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"> allowList</span><span class="z-keyword"> =</span><span class="z-variable z-other z-constant"> P</span><span>.</span><span class="z-variable z-other">allowedResources</span><span class="z-keyword"> ||</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 z-constant">M</span><span>.</span><span class="z-variable z-other">resources</span><span>.</span><span class="z-entity z-name">every</span><span>(</span><span class="z-variable">resource</span><span class="z-storage z-type"> =&gt;</span><span class="z-variable z-other"> allowList</span><span>.</span><span class="z-entity z-name">includes</span><span>(</span><span class="z-variable z-other">resource</span><span>)</span><span>)</span><span>)</span><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-keyword"> if</span><span> (</span><span class="z-variable z-other z-constant">P</span><span>.</span><span class="z-variable z-other">expiresAt</span><span class="z-keyword"> !==</span><span class="z-constant"> 0</span><span class="z-keyword"> &amp;&amp;</span><span class="z-variable z-other"> Date</span><span>.</span><span class="z-entity z-name">now</span><span>(</span><span>)</span><span class="z-keyword"> &gt;=</span><span class="z-variable z-other z-constant"> P</span><span>.</span><span class="z-variable z-other">expiresAt</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Also enforce standard SIWE validations here.</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="security-considerations">Security Considerations</h2> <ul> <li>It’s recommended for Auto login to be OFF by default on wallets’ UIs so that users can explicitly toggle ON for websites they trust.</li> <li>Managing policies it out of scope of this ERC, as most wallets already manage trusted app lists - however, the recommended best practice is to: <ul> <li>Include a default list of policies for popular apps</li> <li>Auto-create policies for other apps if the user consents to it</li> </ul> </li> <li>Standard SIWE checks (fresh nonce, correct domain binding, time validity) should still be enforced.</li> <li><code>uriPrefix</code> should be kept specific (e.g., <code>/login</code>) to avoid over-broad matches.</li> <li>It's recommended to include a top-level setting in each wallet that can disable this ERC.</li> <li>Always match <code>M.domain</code> against the top-level origin of each app, to avoid auto-login working in iframes that are included in a malicious top-level origin.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-08-31T00:00:00+00:00 2026-02-11T14:48:25+00:00 Kyle Thorntonhttps://github.com/kylekyle@cowrie.io https://wg-eips.ritovision.com/8017/

Minimal ERC for a single-asset payout bucket that vends its entire balance for a fixed payment amount.

<h2 id="abstract">Abstract</h2> <p>This ERC specifies a small contract surface for a "payout race": a bucket that holds a single payout asset type and transfers the entire bucket to a recipient when a caller pays a fixed <strong>required payment</strong> in a configured desired payment asset. The desired payment asset can be ETH or one <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. The payout asset can be ETH or one ERC-20.</p> <p>This ERC is inspired by the Uniswap Foundation's <strong>Unistaker</strong> proposal, which introduced the term <strong>Payout Race</strong> and motivated this design.</p> <h2 id="motivation">Motivation</h2> <p>Many protocols need an ongoing way to convert a continuous stream of value into another asset at or near prevailing market prices. Typical cases include buying back a protocol token using protocol revenue, accumulating a reserve asset, funding incentive budgets, or rebalancing treasuries. Existing patterns have material drawbacks. Integrating an AMM couples outcomes to external liquidity, slippage, and fees, and requires retuning when pool conditions change. General on-chain auctions add operational complexity and higher gas, especially when run continuously.</p> <p>This ERC defines a deterministic, revenue-driven primitive that is analogous to a Dutch auction. Sources of value flow into this contract, filling a "bucket" of purchasable assets. The first caller that supplies the required payment in the desired payment asset receives the entire current balance of the payout token in the bucket. The interface is small, auditable, and easy to compose with upstream controllers that decide when the exchange is economically sound.</p> <h2 id="specification">Specification</h2> <p>The following interface and rules are normative. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.</p> <h3 id="definitions">Definitions</h3> <ul> <li> <p><strong>Conforming contract</strong>: Any smart contract that exposes this interface and claims compliance with this ERC. This includes proxies and clones. Requirements in this document apply to the observable runtime behavior of the deployed contract.</p> </li> <li> <p><strong>Payout asset</strong>: Asset dispensed from the bucket. <code>payoutAsset == address(0)</code> means ETH payout.</p> </li> <li> <p><strong>Desired payment asset</strong>: Asset the buyer must pay. Referred to as <code>desiredAsset</code> in the interface. <code>desiredAsset == address(0)</code> means ETH payment.</p> </li> <li> <p><strong>Required payment</strong>: Fixed amount of the desired payment asset (<code>desiredAsset</code>) or ETH that must be provided by the buyer to trigger the payout.</p> </li> </ul> <h3 id="interface">Interface</h3> <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.24</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"> IPayoutRace</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"> Payout asset. address(0) means ETH payout.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> payoutAsset</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"> @notice</span><span class="z-comment"> Desired payment asset. address(0) means ETH payment.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> desiredAsset</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"> @notice</span><span class="z-comment"> Fixed amount required to win the race, denominated in the desired payment asset.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> requiredPayment</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"> Destination that receives the buyer&#39;s payment.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> paymentSink</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"> @notice</span><span class="z-comment"> Pay the required amount and receive the entire current balance of the payout token to `to`.</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 the computed dispensed amount is zero. Must be safe against reentrancy.</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"> dispensed</span><span class="z-comment"> The amount of payout token transferred to `to`.</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">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 class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> dispensed</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Admin surface.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setRequiredPayment</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 class="z-storage z-type"> function</span><span class="z-entity z-name"> setPaymentSink</span><span>(</span><span class="z-support">address</span><span class="z-variable"> sink</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"> Events</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Purchased</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> buyer</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"> dispensed</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> paid</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> PaymentConfigUpdated</span><span>(</span><span class="z-support">address</span><span class="z-variable"> desiredAsset</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> requiredPayment</span><span>, </span><span class="z-support">address</span><span class="z-variable"> sink</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="required-behavior">Required Behavior</h3> <ol> <li> <p><strong>Exact required payment.</strong> Callers <strong>MUST</strong> provide exactly <code>requiredPayment()</code> in the configured <code>desiredAsset</code> or in ETH to call <code>purchase</code>.</p> </li> <li> <p><strong>Token pairing.</strong> <code>payoutAsset</code> and <code>desiredAsset</code> <strong>MUST NOT</strong> both be <code>address(0)</code>. ETH on both sides is disallowed.</p> </li> <li> <p><strong>Desired payment asset immutability.</strong> <code>desiredAsset</code> <strong>MUST NOT</strong> change after initialization. A conforming contract <strong>MUST NOT</strong> expose any callable setter that can change <code>desiredAsset</code>.</p> </li> <li> <p><strong>Payout asset immutability.</strong> <code>payoutAsset</code> <strong>MUST NOT</strong> change after initialization. A conforming contract <strong>MUST NOT</strong> expose any callable setter that can change <code>payoutAsset</code>.</p> </li> <li> <p><strong>All-or-nothing dispense.</strong> On <code>purchase</code>, a conforming contract MUST compute the amount to dispense as the live balance of the payout token captured at function entry, before any external calls. The contract MUST transfer exactly this amount to <code>to</code> in a single call and the call MUST revert if this amount is zero.</p> </li> <li> <p><strong>Payment collection.</strong></p> <ul> <li>If <code>desiredAsset == address(0)</code>, <code>purchase</code> <strong>MUST</strong> require <code>msg.value == requiredPayment()</code> and <strong>MUST</strong> forward that ETH to <code>paymentSink()</code>.</li> <li>If <code>desiredAsset != address(0)</code>, <code>purchase</code> <strong>MUST</strong> require <code>msg.value == 0</code> and <strong>MUST</strong> call <code>transferFrom(msg.sender, paymentSink(), requiredPayment())</code> on <code>desiredAsset</code>.</li> </ul> </li> <li> <p><strong>Admin changes.</strong> A conforming contract <strong>MUST</strong> restrict the admin setters to an authorized role and <strong>MUST</strong> emit <code>PaymentConfigUpdated</code> when <code>requiredPayment</code> or <code>paymentSink</code> change.</p> </li> </ol> <h3 id="optional-extensions">Optional Extensions</h3> <ul> <li><strong>Permit for payment</strong>: A conforming contract <strong>MAY</strong> expose <code>purchaseWithPermit(...)</code> that accepts <a href="https://wg-eips.ritovision.com/2612/">EIP-2612</a> permit parameters. If implemented, the function <strong>MUST</strong> require <code>desiredAsset != address(0)</code>, <strong>MUST</strong> call <code>permit</code> on <code>desiredAsset</code> with the supplied signature, and <strong>MUST</strong> collect <code>requiredPayment</code> via <code>transferFrom</code> in the same transaction. The call <strong>MUST</strong> revert if <code>desiredAsset</code> does not implement EIP-2612 or if the permit does not yield sufficient allowance.</li> <li><strong>Rescue for unintended assets</strong>: A conforming contract <strong>MAY</strong> implement an admin-only <code>rescue</code> function to recover assets that are not the <code>payoutAsset</code> (e.g., unsolicited ERC-20s or ETH sent when <code>payoutAsset</code> is an ERC-20). If provided, the function <strong>MUST NOT</strong> transfer the <code>payoutAsset</code>, <strong>MUST</strong> emit a <code>Rescued(address token, address to, uint256 amount)</code> event, and <strong>MUST</strong> be restricted to an authorized role.</li> </ul> <h2 id="rationale">Rationale</h2> <ul> <li>A single required payment pairs well with controllers that evaluate when the exchange is economically sound and trigger <code>purchase</code> only when conditions justify it. The onchain primitive then validates the payment and atomically transfers the entire bucket.</li> <li><code>paymentSink</code> reduces persistent balances in the contract and simplifies audits. Sinks can be treasuries, splitters, or burns.</li> <li>Using the live onchain balance as the source of truth automatically captures rebases and fee-on-transfer mechanics, and keeps the onchain tracking minimized. It also implies that unsolicited transfers to the contract will be included in the next payout, which purchasers may want to account for at the integration level.</li> </ul> <h3 id="admin-considerations">Admin Considerations</h3> <p>Access control for admin setters is intentionally unspecified; <a href="https://wg-eips.ritovision.com/173/">EIP-173</a> ownership or a role-based pattern is recommended.</p> <p>Some deployments may renounce or restrict admin rights for policy or compliance reasons (for example, renouncing ownership or disabling roles). This ERC does not prescribe any specific mechanism.</p> <p>The reference uses <a href="https://wg-eips.ritovision.com/173/">EIP-173</a> style ownership for illustration. Any access control that enforces the Required behavior is acceptable. Deployments may assign distinct roles per setter or make one or more parameters immutable. The specification is agnostic to the mechanism.</p> <h3 id="parameter-selection-and-degenerate-cases">Parameter Selection and Degenerate Cases</h3> <p>This mechanism works best when value accrues gradually. Large, lumpy deposits can overshoot the required payment threshold and leak value to the first successful caller. Operators should size <code>requiredPayment</code> relative to observed inflow volatility and adjust conservatively. If the payout asset appreciates against the desired payment asset, purchases may stall. If it depreciates, purchases may trigger so frequently that value is lost whenever a large trade pushes the bucket well above the threshold.</p> <p>Changing <code>requiredPayment</code> carries risks. Lowering it can leak value at the moment of change if accrued payout already exceeds the new threshold, since searchers can win a bargain. Raising it can disrupt or bankrupt naive searchers and MEV bots that provide rewards by arbitraging fee collection. Mitigations may include timelocked or scheduled parameter changes, announce windows, caps on per-block deposits, cooldowns after changes, and time-weighted average pricing (TWAP)-based or ratcheted adjustments to <code>requiredPayment</code>.</p> <h3 id="considered-alternatives-multi-asset-sweep">Considered Alternatives: Multi-Asset Sweep</h3> <p>This design could be extended to support multiple payout assets by maintaining an explicit allowlist and, on a successful <code>purchase</code>, sweeping each allowlisted token to the recipient using the same mechanics as the single-asset case.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Compatible with any <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. Wallets and dApps can integrate using standard allowance flows or optional <code>permit</code> helpers.</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"> ^0.8.24</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IERC20</span><span>}</span><span class="z-keyword"> from</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> {</span><span class="z-entity z-name">ReentrancyGuard</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/security/ReentrancyGuard.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"> PayoutRace</span><span class="z-storage"> is</span><span class="z-entity z-name"> ReentrancyGuard</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> immutable</span><span> payoutAsset</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> address(0) for ETH payout</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> immutable</span><span> desiredAsset</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> address(0) for ETH payment</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> public</span><span> requiredPayment</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> fixed amount owed by buyer</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> paymentSink</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> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Purchased</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> buyer</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"> dispensed</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> paid</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> PaymentConfigUpdated</span><span>(</span><span class="z-support">address</span><span class="z-variable"> desiredAsset</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> requiredPayment</span><span>, </span><span class="z-support">address</span><span class="z-variable"> sink</span><span>)</span><span>;</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"> oldOwner</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-storage z-type"> modifier</span><span class="z-entity z-name"> onlyOwner</span><span>(</span><span>)</span><span> {</span><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;not owner&quot;</span><span>)</span><span>;</span><span class="z-constant"> _</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-support">address</span><span class="z-variable z-parameter z-function"> _payoutAsset</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _desiredAsset</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _required</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _sink</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-keyword">!</span><span>(</span><span>_payoutAsset </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"> &amp;&amp;</span><span> _desiredAsset </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 class="z-string"> &quot;ETH-ETH disallowed&quot;</span><span>)</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> payoutAsset </span><span class="z-keyword">=</span><span> _payoutAsset</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> zero means ETH payout</span></span> <span class="giallo-l"><span> desiredAsset </span><span class="z-keyword">=</span><span> _desiredAsset</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> zero means ETH payment</span></span> <span class="giallo-l"><span> requiredPayment </span><span class="z-keyword">=</span><span> _required</span><span>;</span></span> <span class="giallo-l"><span> paymentSink </span><span class="z-keyword">=</span><span> _sink</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> OwnershipTransferred</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span> _owner</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> PaymentConfigUpdated</span><span>(</span><span>desiredAsset</span><span>,</span><span> requiredPayment</span><span>,</span><span> paymentSink</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"> owner</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-keyword"> return</span><span> _owner</span><span>;</span><span> }</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"> n</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyOwner</span><span> {</span><span> _owner </span><span class="z-keyword">=</span><span> n</span><span>;</span><span class="z-keyword"> emit</span><span class="z-entity z-name"> OwnershipTransferred</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> n</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"> Accept ETH only when this instance vends ETH</span></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-keyword"> require</span><span>(</span><span>payoutToken </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;ETH payout disabled&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-comment"> //</span><span class="z-comment"> desiredAsset is immutable in this reference; no setter is provided.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setRequiredPayment</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-entity z-name"> onlyOwner</span><span> {</span><span> requiredPayment </span><span class="z-keyword">=</span><span> amount</span><span>;</span><span class="z-keyword"> emit</span><span class="z-entity z-name"> PaymentConfigUpdated</span><span>(</span><span>desiredAsset</span><span>,</span><span> requiredPayment</span><span>,</span><span> paymentSink</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"> setPaymentSink</span><span>(</span><span class="z-support">address</span><span class="z-variable"> sink</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyOwner</span><span> {</span><span> paymentSink </span><span class="z-keyword">=</span><span> sink</span><span>;</span><span class="z-keyword"> emit</span><span class="z-entity z-name"> PaymentConfigUpdated</span><span>(</span><span>desiredAsset</span><span>,</span><span> requiredPayment</span><span>,</span><span> paymentSink</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"> purchase</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 class="z-entity z-name"> nonReentrant</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> dispensed</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> toDispense</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>payoutAsset </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"> capture live ETH balance</span></span> <span class="giallo-l"><span> toDispense </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>balance</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span> toDispense </span><span class="z-keyword">=</span><span class="z-entity z-name"> IERC20</span><span>(</span><span>payoutAsset</span><span>)</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> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>toDispense </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;empty&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"> collect payment</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>desiredAsset </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 class="z-variable z-language">msg</span><span>.</span><span>value </span><span class="z-keyword">==</span><span> requiredPayment</span><span>,</span><span class="z-string"> &quot;bad msg.value&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bool</span><span> ok</span><span>,</span><span> )</span><span class="z-keyword"> =</span><span> paymentSink</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span class="z-variable z-language"> msg</span><span>.</span><span>value</span><span>}</span><span>(</span><span class="z-string">&quot;&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>ok</span><span>,</span><span class="z-string"> &quot;sink transfer failed&quot;</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"> 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"> 0</span><span>,</span><span class="z-string"> &quot;unexpected ETH&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">IERC20</span><span>(</span><span>desiredAsset</span><span>)</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> paymentSink</span><span>,</span><span> requiredPayment</span><span>)</span><span>,</span><span class="z-string"> &quot;payment transfer failed&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-comment"> //</span><span class="z-comment"> payout</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>payoutAsset </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><span class="z-support">bool</span><span> ok2</span><span>,</span><span> )</span><span class="z-keyword"> =</span><span> to</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span> toDispense</span><span>}</span><span>(</span><span class="z-string">&quot;&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>ok2</span><span>,</span><span class="z-string"> &quot;ETH payout failed&quot;</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"> require</span><span>(</span><span class="z-entity z-name">IERC20</span><span>(</span><span>payoutAsset</span><span>)</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>to</span><span>,</span><span> toDispense</span><span>)</span><span>,</span><span class="z-string"> &quot;token payout failed&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-keyword"> emit</span><span class="z-entity z-name"> Purchased</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> to</span><span>,</span><span> toDispense</span><span>,</span><span> requiredPayment</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> toDispense</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> <ul> <li> <p><strong>Payout accounting.</strong> The dispensed amount is computed from the live onchain balance of the payout asset. Because ETH-to-ETH is disallowed, there is no ambiguity about subtracting <code>msg.value</code>. Capture the amount to dispense at function entry and use that value for the transfer.</p> </li> <li> <p><strong>Reentrancy and external calls.</strong> Use the Checks-Effects-Interactions pattern and a reentrancy guard. Avoid any external calls before you (a) capture the amount to dispense and (b) forward payment to <code>paymentSink</code>. Do not perform callbacks between collecting payment and completing the payout.</p> </li> <li> <p><strong>Receiver constraints.</strong> The recipient <code>to</code> must be able to receive the asset being dispensed. ETH payouts require a payable fallback; <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> payouts require that <code>to</code> is not a contract that reverts on <code>transfer</code>.</p> </li> <li> <p><strong>Payment sink constraints.</strong> The <code>paymentSink</code> must be able to receive the desired payment asset. For ETH payments, <code>paymentSink</code> must be payable. For <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> payments, <code>paymentSink</code> must not revert when credited via <code>transferFrom</code>. Using a burn address, splitter, or treasury is acceptable; the specification is agnostic to the mechanism.</p> </li> <li> <p><strong>Unsolicited transfers.</strong> The next payout will include any assets pushed to the contract (e.g., direct ETH sends or <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> transfers). Operators should account for this at the integration layer, or front the contract with filters if needed. An optional admin-only <code>rescue</code> for non-<code>payoutAsset</code> assets can mitigate mistakes without affecting conformance.</p> </li> <li> <p><strong>Approvals and permits.</strong> When using <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> payments, callers should consider allowance race conditions. If a <code>purchaseWithPermit</code> helper is implemented, verify domain separator, deadline, and nonce handling, and revert on insufficient post‑permit allowance.</p> </li> <li> <p><strong>Admin changes.</strong> Because setters can change <code>requiredPayment</code> or <code>paymentSink</code>, governance should protect these operations. Common mitigations include timelocks, scheduled changes with announcement windows, and immutability for parameters that should never change.</p> </li> <li> <p><strong>Proxies and clones.</strong> Constructors do not run per proxy or minimal clone. Implementations should set <code>payoutAsset</code> and <code>desiredAsset</code> once during initialization and ensure they cannot change afterward. Avoid exposing setters and protect initializers against re-entry or multiple calls.</p> </li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-08-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status Caymanhttps://github.com/wemeetagain https://wg-eips.ritovision.com/8016/

SSZ type for forward-compatible unions

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a new <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md">Simple Serialize (SSZ)</a> type to represent unions with forward-compatible Merkleization: A given field is always assigned the same stable <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/merkle-proofs.md#generalized-merkle-tree-index">generalized index (gindex)</a> across all type options.</p> <h2 id="motivation">Motivation</h2> <p>Certain types, e.g., transactions, allow multiple variants carving out slightly different feature sets. Merkleization equivalence is still desirable, as it allows verifiers to check common fields across variants. These types should still efficiently deserialize into one of their possible variants corresponding to its known tree shape. In programming languages, this is typically achieved by tagged unions.</p> <p>If multiple versions of an SSZ container coexist at the same time, for example to represent transaction types, the same field may be assigned to a different gindex in each version. This unnecessarily complicates verifiers and introduces a maintenance burden, as the verifier has to be kept up to date with version specific field to gindex map.</p> <p>Compatible unions allow only type options to be used that provide stable gindex assignment across all of them.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="compatibleunion-selector-type"><code>CompatibleUnion({selector: type})</code></h3> <p>A new <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md#composite-types">SSZ composite type</a> is defined:</p> <ul> <li><strong>compatible union</strong>: union type containing one of the given subtypes with compatible Merkleization <ul> <li>notation <code>CompatibleUnion({selector: type})</code>, e.g. <code>CompatibleUnion({1: Square, 2: Circle})</code></li> </ul> </li> </ul> <p>Compatible unions are always considered <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md#variable-size-and-fixed-size">"variable-size"</a>, even when all type options share the same fixed length.</p> <p>The <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md#default-values">default value</a> is defined as:</p> <table><thead><tr><th>Type</th><th>Default Value</th></tr></thead><tbody> <tr><td><code>CompatibleUnion({selector: type})</code></td><td>n/a (error)</td></tr> </tbody></table> <p>The following types are considered <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md#illegal-types">illegal</a>:</p> <ul> <li><code>CompatibleUnion({})</code> without any type options are illegal.</li> <li><code>CompatibleUnion({selector: type})</code> with a selector outside <code>uint8(1)</code> through <code>uint8(127)</code> are illegal.</li> <li><code>CompatibleUnion({selector: type})</code> with a type option that has incompatible Merkleization with another type option are illegal.</li> </ul> <h4 id="compatible-merkleization">Compatible Merkleization</h4> <ul> <li>Types are compatible with themselves.</li> <li><code>byte</code> is compatible with <code>uint8</code> and vice versa.</li> <li><code>Bitlist[N]</code> are compatible if they share the same capacity <code>N</code>.</li> <li><code>Bitvector[N]</code> are compatible if they share the same capacity <code>N</code>.</li> <li><code>List[type, N]</code> are compatible if <code>type</code> is compatible and they share the same capacity <code>N</code>.</li> <li><code>Vector[type, N]</code> are compatible if <code>type</code> is compatible and they share the same capacity <code>N</code>.</li> <li><a href="https://wg-eips.ritovision.com/7916/"><code>ProgressiveList[type]</code></a> are compatible if <code>type</code> is compatible.</li> <li><code>Container</code> are compatible if they share the same field names in the same order, and all field types are compatible.</li> <li><a href="https://wg-eips.ritovision.com/7495/"><code>ProgressiveContainer(active_fields)</code></a> are compatible if all <code>1</code> entries in both type's <code>active_fields</code> correspond to fields with shared names and compatible types, and no other field name is shared across both types.</li> <li><code>CompatibleUnion</code> are compatible with each other if all type options across both <code>CompatibleUnion</code> are compatible.</li> <li>All other types are incompatible.</li> </ul> <h4 id="serialization">Serialization</h4> <p>A <code>value</code> as <code>CompatibleUnion({selector: type})</code> has properties <code>value.data</code> with the contained value, and <code>value.selector</code> which indexes the selected type option.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">return</span><span> value</span><span>.</span><span>selector</span><span>.</span><span>to_bytes</span><span>(</span><span class="z-constant">1</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 class="z-keyword"> +</span><span> serialize</span><span>(</span><span>value</span><span>.</span><span>data</span><span>)</span></span></code></pre><h4 id="deserialization">Deserialization</h4> <p>The deserialization logic is updated:</p> <ul> <li>In the case of compatible unions, the first byte of the deserialization scope is deserialized as type selector, the remainder of the scope is deserialized as the selected type.</li> </ul> <p>The following invalid input needs to be hardened against:</p> <ul> <li>An out-of-bounds type selector in a <code>CompatibleUnion</code></li> <li>Incomplete data (less than 1 byte for selector)</li> <li>Corrupted or malformed serialized data</li> <li>Invalid serialization of inner types (delegated to inner type deserialization)</li> </ul> <h4 id="json-mapping">JSON mapping</h4> <p>The canonical <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md#json-mapping">JSON mapping</a> is updated:</p> <table><thead><tr><th>SSZ</th><th>JSON</th><th>Example</th></tr></thead><tbody> <tr><td><code>CompatibleUnion({selector: type})</code></td><td>selector-object</td><td><code>{ "selector": string, "data": type }</code></td></tr> </tbody></table> <p><code>CompatibleUnion</code> is encoded as an object with a <code>selector</code> and <code>data</code> field, where the contents of <code>data</code> change according to the selector.</p> <h4 id="merkleization">Merkleization</h4> <p>The <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md#merkleization">SSZ Merkleization specification</a> is extended with a helper function:</p> <ul> <li><code>mix_in_selector</code>: Given a Merkle root <code>root</code> and a type selector <code>selector</code> (<code>"uint8"</code> serialization) return <code>hash(root, selector)</code>.</li> </ul> <p>The Merkleization definitions are extended.</p> <ul> <li><code>mix_in_selector(hash_tree_root(value.data), value.selector)</code> if <code>value</code> is of compatible union type.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="why-are-compatibleunion-selectors-limited-to-1-127">Why are <code>CompatibleUnion</code> selectors limited to <code>1 ... 127</code>?</h3> <p>Reserving <code>0</code> prevents issues with incomplete initialization, and can possibly be used in a future EIP to denote optionality.</p> <p>Reserving selectors above <code>127</code> (i.e., highest bit is set) enables future backwards compatible extensions.</p> <p>The range <code>1 ... 127</code> is sufficient to satisfy current demand.</p> <h3 id="why-not-field-collections">Why not field collections?</h3> <p>An alternative design was explored where the <code>active_fields</code> bitvector was emitted. While that works in principle, it becomes very inefficient to parse when <code>ProgressiveContainer</code> are nested, as the parser cannot immediately determine the overall tree shape. Further, the bitvector makes every single nesting layer variable-length, adding a lot of overhead to the serialized format.</p> <p>With <code>CompatibleUnion</code>, a tag is emitted that tells the parser early on what to expect, including for nested fields.</p> <p>Note that wrapping a field in a <code>CompatibleUnion</code> is not a backwards compatible operation. However, new options can be introduced, and existing options dropped, without breaking verifiers. Therefore, <code>CompatibleUnion</code> has to be introduced early on wherever future design extensions are anticipated, even when only a single type option is used.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><code>CompatibleUnion({selector: type})</code> is an alternative to an <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md#composite-types">earlier union proposal</a>. However, it has only been used in <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/specs/_deprecated/sharding/beacon-chain.md">deprecated specifications</a>. Portal network also uses a union concept for network types, but does not use <code>hash_tree_root</code> on them, and could transition to the new compatible union proposal with a new networking version.</p> <h2 id="test-cases">Test Cases</h2> <ul> <li><code>ethereum/remerkleable</code> contains static tests in <code>test_impl.py</code> and <code>test_typing.py</code>.</li> <li><code>ethereum/consensus-specs</code> releases contain random tests in <code>tests/general/phase0/ssz_generic</code>, generated according to a format defined in <code>tests/format/ssz_generic</code>.</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <code>ethereum/remerkleable</code>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>For <code>CompatibleUnion({selector: type})</code>, the <code>selector</code> mix-in guarantees a unique <code>hash_tree_root</code> if multiple type options refer to the same Merkle tree shape, or also if multiple type options solely differ in the element type of a <code>List[type, N]</code> or <a href="https://wg-eips.ritovision.com/7916/"><code>ProgressiveList[type]</code></a> field (as the <code>hash_tree_root</code> of any empty list does not depend on the <code>type</code>). Without the <code>selector</code>, such cases would either have to be defined as illegal types, or handled by the application logic (e.g., by mixing it into the signing root, or by encoding the element type into a different field).</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-08-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 Maria Silvahttps://github.com/misilva73 Davide Crapishttps://github.com/dcrapis Anders Elowssonhttps://github.com/anderselowsson Toni Wahrstätterhttps://github.com/nerolation https://wg-eips.ritovision.com/8011/

Gas accounting by EVM resource, increasing throughput and improving resource usage controls, with minimal changes to the protocol and UX

<h2 id="abstract">Abstract</h2> <p>This proposal introduces multidimensional gas metering, changing the way we account for gas used at the block level. This enables Ethereum to increase throughput and better control excessive resource usage, with minimal changes to the protocol and the UX. During transaction execution, gas is metered for each resource dimension, such as compute and state. At the transaction level, everything remains unchanged. A transaction still pays fees according to the sum of gas used across all resources and still has a single gas limit imposed on this same sum. However, at the block level, only the gas used in the bottleneck resource is considered when checking if the block is full and when updating the base fee for the next block. This gives a new meaning to the block's gas limit and the block's gas target, which now corresponds to the maximum gas that can be metered in the bottleneck resource.</p> <h2 id="motivation">Motivation</h2> <p>This proposal separates <em>transaction pricing</em> (i.e., the way of measuring consumption of resources by transactions) from <em>block metering</em> (i.e., the way of controlling resource limits and ensure that blocks do not overload the network). More concretely, it introduces a multidimensional metering scheme that accounts for the different EVM resources while keeping the pricing model unchanged.</p> <p>There are four main benefits of the proposal:</p> <ol> <li>Throughput gains: By decoupling resource limits, blocks can carry transactions that stress distinct resources simultaneously, improving packing efficiency.</li> <li>Finer-grained control over excessive resource usage: metering gas costs independently for each resource allows us to tailor each operation's gas cost to the actual resource limits.</li> <li>Keeps UX identical: users still specify one <code>gas_limit</code> and see one <code>gas_used</code> value.</li> <li>Simplicity: This simpler metering change lays the groundwork for eventual multidimensional pricing (such as <a href="https://wg-eips.ritovision.com/7999/">EIP-7999</a>) without disrupting the current fee market and with minimal protocol changes.</li> </ol> <h2 id="specification">Specification</h2> <h3 id="operation-gas-costs">Operation gas costs</h3> <p>Under the multidimensional metering model, EVM operations are assigned a cost vector whose components correspond to their gas cost on each resource dimension. Each cost has 6 dimensions: <code>gas_cost_vector = (compute_cost, access_cost, size_cost, memory_cost, state_cost, history_cost)</code>.</p> <h4 id="pure-compute-operations">Pure compute operations</h4> <p>The operations listed in <a href="https://wg-eips.ritovision.com/8011/assets/compute_ops/">compute_ops</a> are assigned a <code>gas_cost_vector</code> equal to <code>(gas_cost, 0, 0, 0, 0, 0)</code>, where <code>gas_cost</code> is the operation's gas cost.</p> <h4 id="compute-and-memory-operations">Compute and memory operations</h4> <p>The operations listed in <a href="https://wg-eips.ritovision.com/8011/assets/compute_mem_ops/">compute_mem_ops</a> are assigned a <code>gas_cost_vector</code> equal to <code>(compute_cost, 0, 0, memory_cost, 0, 0)</code>, where <code>memory_cost</code> is the operation's memory expansion cost (as defined by the function <a rel="external" href="https://github.com/ethereum/execution-specs/blob/91824145ef62da61803edf9a764fd8f3662794c0/src/ethereum/osaka/vm/gas.py#L167"><code>calculate_gas_extend_memory</code></a>) and <code>compute_cost</code> is the operation's gas cost minus its memory expansion cost.</p> <h4 id="state-operations">State operations</h4> <p>The assignment of a <code>gas_cost_vector</code> to the operations listed in <a href="https://wg-eips.ritovision.com/8011/assets/state_ops/">state_ops</a> is TBD, pending benchmarks. &lt;-- TODO --&gt;</p> <h4 id="log-operations">LOG operations</h4> <p>The assignment of a <code>gas_cost_vector</code> to the operations listed in <a href="https://wg-eips.ritovision.com/8011/assets/log_ops/">log_ops</a> is TBD, pending benchmarks. &lt;-- TODO --&gt;</p> <h3 id="intrinsic-gas-costs">Intrinsic gas costs</h3> <p>Under the multidimensional metering model, each transaction's intrinsic cost (as defined by the function <a rel="external" href="https://github.com/ethereum/execution-specs/blob/91824145ef62da61803edf9a764fd8f3662794c0/src/ethereum/osaka/transactions.py#L571"><code>calculate_intrinsic_cost</code></a>) is also assigned 6-dimensional <code>gas_cost_vector</code>. The breakdown of cost by resource dimension is TBD, pending benchmarks.</p> <p>&lt;-- TODO --&gt;</p> <h3 id="gas-accounting">Gas accounting</h3> <p>Besides replacing the single gas cost with a 6-dimensional cost vector, the gas accounting during block execution also changes. Instead of keeping track of a single total of gas used, the EVM stores a 6-dimensional vector with how much gas units was spent on each resource until that point in the execution.</p> <p>After executing the ith EVM operation of a transaction, say <code>OP_i</code>, with a cost vector <code>gas_cost_vector_i = (compute_cost_i, access_cost_i, size_cost_i, memory_cost_i, state_cost_i, history_cost_i)</code>, the following variables are updated:</p> <ul> <li>Remaining available gas for the transaction: <ul> <li><code>gas = gas - sum(compute_cost_i, access_cost_i, size_cost_i, memory_cost_i, state_cost_i, history_cost_i)</code></li> </ul> </li> <li>Total used gas by the transaction so far: <ul> <li><code>gas_used = gas_used + sum(compute_cost_i, access_cost_i, size_cost_i, memory_cost_i, state_cost_i, history_cost_i)</code></li> </ul> </li> <li>Used gas vector by the transaction so far: <ul> <li><code>gas_used_vector = (compute_gas_used + compute_cost_i, access_gas_used + access_cost_i, size_gas_used + size_cost_i, memory_gas_used + memory_cost_i, state_gas_used + state_cost_i, history_gas_used + history_cost_i)</code></li> </ul> </li> </ul> <p>At the transaction level, everything remains the same. A transaction still has the same one-dimensional <code>gas_limit</code>. The transaction's out-of-gas condition is still defined as <code>gas_used &lt;= gas_limit</code>. Additionally, the transaction's fee is also computed with <code>gas_used</code>.</p> <p>The key change is the introduction of <code>gas_used_vector</code> as a new variable that tracks the gas used by each resource at the transaction level. This variable is returned by the <code>execute_transaction</code> function, in addition to <code>gas_used</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"> execute_transaction</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> transaction</span><span>:</span><span> NormalizedTransaction</span><span>,</span><span class="z-variable z-parameter z-function"> effective_gas_price</span><span>:</span><span class="z-support"> int</span><span>)</span><span> -&gt;</span><span> tuple</span><span>[</span><span class="z-support">int</span><span>,</span><span class="z-support"> list</span><span>]</span><span>:</span><span class="z-keyword"> pass</span></span></code></pre><h3 id="block-header-extension">Block header extension</h3> <p>The current header encoding is extended with a new 64-bit unsigned integer field named <code>max_gas_metered</code>. This integer corresponds to the total gas units used by the bottleneck resource, i.e., the resource with the largest used gas in the block. This variable is computed 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"> compute_block_max_gas_metered</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-support"> int</span><span>:</span></span> <span class="giallo-l"><span> transactions</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>transactions</span><span>(</span><span>block</span><span>)</span></span> <span class="giallo-l"><span> block_gas_used_vector</span><span class="z-keyword"> =</span><span> array</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 class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> transaction</span><span class="z-keyword"> in</span><span> transactions</span><span>:</span></span> <span class="giallo-l"><span> gas_used</span><span>,</span><span> gas_used_vector</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>execute_transaction</span><span>(</span><span>transaction</span><span>,</span><span> effective_gas_price</span><span>)</span></span> <span class="giallo-l"><span> block_gas_used_vector</span><span class="z-keyword"> +=</span><span> gas_used_vector</span></span> <span class="giallo-l"><span> max_gas_metered</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span>block_gas_used_vector</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> max_gas_metered</span></span></code></pre> <p>The header sequence with the new field is <code>[..., parent_beacon_block_root, requests_hash, max_gas_metered]</code>.</p> <h3 id="block-validity-condition">Block validity condition</h3> <p>The block validity conditions are modified to replace <code>block.gas_used</code> with <code>block.max_gas_metered</code>:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">assert</span><span> block</span><span>.</span><span>max_gas_metered</span><span class="z-keyword"> &lt;=</span><span> block</span><span>.</span><span>gas_limit</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">invalid block: too much gas used</span><span class="z-punctuation z-definition z-string">&#39;</span></span></code></pre><h3 id="base-fee-update-rule">Base fee update rule</h3> <p>The block validity conditions are modified to replace <code>parent.gas_used</code> with <code>parent.max_gas_metered</code>:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>gas_used_delta</span><span class="z-keyword"> =</span><span> parent</span><span>.</span><span>max_gas_metered</span><span class="z-keyword"> -</span><span> parent</span><span>.</span><span>gas_target</span></span></code></pre> <p>This change is compatible with the various transaction variants, such as <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a>, <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>, or <a href="https://wg-eips.ritovision.com/7999/">EIP-7999</a>.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-are-we-choosing-this-resource-split">Why are we choosing this resource split?</h3> <p>Ethereum’s slot-based structure introduces a strict temporal constraint: all attestations must be processed, aggregated, and propagated within a single slot. This fact makes time a fundamental resource. To maintain network health, validators must execute blocks, validate them, and gossip attestations quickly enough to avoid missed slots and penalties.</p> <p>Each type of resource contributes differently to this bottleneck:</p> <ul> <li>Execution time affects how quickly validators can process blocks and produce attestations.</li> <li>Data size influences how long it takes to propagate blocks and blobs across the peer-to-peer network.</li> <li>Memory usage determines how efficiently nodes can handle concurrent workloads without triggering garbage collection or cache eviction. It also affects the minimum hardware requirements that proposers and attesters must meet to fulfill their responsibilities.</li> <li>State growth impacts long-term scalability and database performance, especially for archival and full nodes.</li> </ul> <p>In addition, changes in the slot (e.g., Enshrined Proposer-Builder Separation) and changes in the execution model (e.g., Block-level Access Lists) will change how the different resources interact and how they impact the available slot time. Thus, we want to track as many relevant resources as possible in order to allow for future changes to the protocol that may impact resource contribution.</p> <p>For these reasons, the proposal splits the resources into the following broad categories:</p> <ol> <li><strong>Block Execution Time</strong>: Captures how long it takes to process a block on a single node. This includes: <ul> <li>Compute: CPU time spent on each operation.</li> <li>State Access: Time or count of disk I/O operations when accessing the trie (e.g., <code>SLOAD</code>/<code>SSTORE</code>).</li> </ul> </li> <li><strong>Block Upload/Download Time</strong>: Captures how data size affects network transmission: <ul> <li>Block size (call data + transaction &amp; block metadata)</li> </ul> </li> <li><strong>Short-term Memory</strong>: Reflects short-term memory allocation during execution, i.e., RAM usage</li> <li><strong>Long-term Storage</strong>: Tracks persistent changes to disk usage. There are two dimensions here: <ul> <li>State Growth: Delta in disk size of the state trie before and after execution.</li> <li>History Growth: Delta in disk space used for historical receipts, logs, etc.</li> </ul> </li> </ol> <p>Note that we are not considering the blob resource (which is part of the Block Upload/Download Time) as it is already priced independently.</p> <p>Based on previous empirical analysis, state growth represented a significant portion of the gas used in Ethereum blocks, accounting for 30.2% of all gas consumed between blocks 22000000 and 22005000. The second resource with the most gas used was compute (26.8%), followed by state access (21.9%). History growth and data had a less relevant contribution, accounting for 9.9% and 6.9% of all the gas used, respectively. Note that the data component in this analysis did not consider blobs.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is not backwards-compatible and requires a hard fork.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="worst-case-blocks-and-excessive-resource-usage">Worst-case blocks and excessive resource usage</h3> <p>A concern about metering resources independently is the potential of creating worst-case blocks that put too much pressure on EVM resources. Thus, the cost vectors of each EVM operation need to be carefully set up to avoid this scenario. To this end, we will perform comprehensive benchmarks to measure the resource utilization of each operation and set the gas cost vector accordingly.</p> <p>Additionally, state and history growth are not constrained at the block level, but over longer time frames. Increased aggregate gas usage from this proposal may be associated with increase state-growth, assuming that relative gas consumption across resources is not altered significantly under equilibrium. To keep the long-run consumption in check, the gas cost of operations contributing to state and history growth would thus need to be increased.</p> <h3 id="base-fee-manipulation">Base fee manipulation</h3> <p>Builders can manipulate the base fee by selectively including or excluding transactions to change the block's <code>max_gas_metered</code>. This behavior is already possible with EIP-1559. Yet, multidimensional gas metering compute the base fee on the bottleneck resource instead of the total gas consumed. This allows for blocks that yield the same total fees but with different <code>max_gas_metered</code> values. The extent of this concern is limited by the incentives to maximize fee revenue. While the expected gains of base fee manipulation are smaller than execution rewards, we won't observe these attacks.</p> <h3 id="added-complexity-in-block-building">Added complexity in block building</h3> <p>Optimal block construction becomes more complex, since builders must now balance resource usage across multiple dimensions rather than a single gas metric. Sophisticated builders may gain an advantage by applying advanced optimization techniques, raising concerns about further builder centralization. However, practical heuristics (e.g., greedily filling blocks until one resource dimension saturates) remain effective for most use cases. These heuristics limit centralization pressure by keeping block construction feasible for local and less sophisticated builders.</p> <h3 id="censorship-resistance">Censorship resistance</h3> <p>This EIP makes it cheaper to fill the block to censor transactions under FOCIL in <a href="https://wg-eips.ritovision.com/7805/">EIP-7805</a> (as also noted in <a href="https://wg-eips.ritovision.com/7999/">EIP-7999</a>). Specifically, it can be cheaper for a builder to create dummy transaction consuming only one resource to fill the block, taking advantage of the lower base fee under equilibrium. However, given that all resources have the same base fee in this proposal, and that the builder must still fill the block up to the gas limit for at least one resource, the degradation in censorship resistance is fairly moderate, and mainly related to the potentially reduced base fee under 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> 2025-08-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 Potuzhttps://github.com/potuz https://wg-eips.ritovision.com/8012/

Reutilizes the consolidation request contract to pass general messages from the EL to the CL.

<h2 id="abstract">Abstract</h2> <p>This EIP redefines the field <code>target_pubkey</code> from consolidations requests into a general array of 48 bytes that can be interpreted separately by the consensus layer.</p> <h2 id="motivation">Motivation</h2> <p>The current contract to send consolidation requests is not optimized in that the exact same contract, with the exact same calldata and engine API, can be used to transmit more general messages from the EL to the CL without changes on the EL side. In particular, avoiding any cross layer coordination in the event of an CL hard fork.</p> <p>As a possible application, we could use the same contract to allow any existing validator to become a builder as in <a href="https://wg-eips.ritovision.com/7732/">EIP-7732</a>.</p> <h2 id="specification">Specification</h2> <h3 id="constants">Constants</h3> <h4 id="consensus-layer">Consensus Layer</h4> <table><thead><tr><th>NAME</th><th>Value</th><th>Comment</th></tr></thead><tbody> <tr><td><code>MAGIC_PREFIX</code></td><td><code>0xEF0A11</code></td><td>3 byte prefix to all generalized consolidation requests</td></tr> </tbody></table> <h3 id="execution-layer">Execution Layer</h3> <p>No changes are expected</p> <h3 id="consensus-layer-1">Consensus Layer</h3> <p>This EIP does not establish any changes on the consensus layer, but rather standardizes how consolidation requests are to be treated in the future. When receiving a <code>ConsolidationRequest</code> type object on the consensus layer, the <code>target_pubkey</code> field is to be treated differently. If it coincides with the BLS publick key of an existing active validator in the beacon chain, then it is to be interpreted as such. Otherwise, the 48 bytes are to be interpreted as a concatenation of the following fields</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>|MAGIC_PREFIX | CALL_TYPE | ARG_NUMBER | ARG1 | ARG2 | ARG3 | ARG4 | ARG5 |</span></span></code></pre> <p>Where <code>MAGIC_PREFIX</code> is the 3 byte constant that prefixes all generalized consolidation requests. <code>CALL_TYPE</code> are 4 bytes to be interpretted as a little Endian <code>uint32</code> and identifies the function type. <code>ARG_NUMBER</code> is a 1 byte to be interpretted as a <code>uint8</code> that encodes the number of arguments that are being passed to the generalized consolidation request handler. And each <code>ARG1, ARG2, ARG3, ARG4, ARG5</code> are all interpretted as little Endian <code>uint64</code>.</p> <p>For each addition of a new <code>CALL_TYPE</code>, the consensus layer must add a handler appropriately called from within <code>process_consolidation_requests</code>.</p> <h3 id="engine-api">Engine API</h3> <p>No changes needed.</p> <h2 id="rationale">Rationale</h2> <p>The proposed reinterpretation of the existing contract enables new implementations in the consensus layer without requireing a hard fork in the execution layer.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible.</p> <h2 id="security-considerations">Security Considerations</h2> <p>No known security impacts.</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-08-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 Terencehttps://github.com/terencechain https://wg-eips.ritovision.com/8015/

Remove legacy `deposits` and `eth1_data` fields from `BeaconBlockBody` after EIP-6110 finalization

<h2 id="abstract">Abstract</h2> <p>This EIP removes the legacy <code>deposits</code> and <code>eth1_data</code> fields from the <code>BeaconBlockBody</code> structure after <a href="https://wg-eips.ritovision.com/6110/">EIP-6110</a> has been fully finalized. These fields become obsolete once all validators have transitioned to the new in-protocol deposit processing mechanism introduced in EIP-6110.</p> <h2 id="motivation">Motivation</h2> <p>EIP-6110 introduced in-protocol deposit processing by moving validator deposits to the execution layer as part of the EIP-7685 request framework. This change eliminated the need for the consensus layer's proposer voting mechanism for deposits. However, during the transition period, both the legacy deposit mechanism (using <code>deposits</code> and <code>eth1_data</code> fields) and the new mechanism coexist to ensure smooth migration.</p> <p>Once EIP-6110 has been fully finalized and the transition period is complete (when <code>state.eth1_deposit_index == state.deposit_requests_start_index</code>), the legacy deposit fields become permanently unused and can be safely removed. This cleanup provides several benefits:</p> <ul> <li><strong>Simplified validation</strong>: Removes deprecated validation logic and code paths</li> <li><strong>Improved maintainability</strong>: Eliminates technical debt from the transition period</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="consensus-layer">Consensus Layer</h3> <h4 id="activation-conditions">Activation Conditions</h4> <p>This EIP SHALL only be activated when both of the following conditions are met:</p> <ol> <li>EIP-6110 has been fully finalized: <code>state.eth1_deposit_index == state.deposit_requests_start_index</code></li> <li>EIP-7732 is in effect</li> </ol> <h4 id="beaconblockbody-modifications">BeaconBlockBody Modifications</h4> <p>The <code>BeaconBlockBody</code> container is modified to remove the following fields:</p> <p><strong>Removed fields:</strong></p> <ul> <li><code>deposits: List[Deposit, MAX_DEPOSITS]</code></li> <li><code>eth1_data: Eth1Data</code></li> </ul> <p>The updated <code>BeaconBlockBody</code> structure becomes:</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"> BeaconBlockBody</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> randao_reveal</span><span>:</span><span> BLSSignature</span></span> <span class="giallo-l"><span> graffiti</span><span>:</span><span> Bytes32</span></span> <span class="giallo-l"><span> proposer_slashings</span><span>:</span><span> List</span><span>[</span><span>ProposerSlashing</span><span>,</span><span class="z-constant"> MAX_PROPOSER_SLASHINGS</span><span>]</span></span> <span class="giallo-l"><span> attester_slashings</span><span>:</span><span> List</span><span>[</span><span>AttesterSlashing</span><span>,</span><span class="z-constant"> MAX_ATTESTER_SLASHINGS_ELECTRA</span><span>]</span></span> <span class="giallo-l"><span> attestations</span><span>:</span><span> List</span><span>[</span><span>Attestation</span><span>,</span><span class="z-constant"> MAX_ATTESTATIONS_ELECTRA</span><span>]</span></span> <span class="giallo-l"><span> voluntary_exits</span><span>:</span><span> List</span><span>[</span><span>SignedVoluntaryExit</span><span>,</span><span class="z-constant"> MAX_VOLUNTARY_EXITS</span><span>]</span></span> <span class="giallo-l"><span> sync_aggregate</span><span>:</span><span> SyncAggregate</span></span> <span class="giallo-l"><span> bls_to_execution_changes</span><span>:</span><span> List</span><span>[</span><span>SignedBLSToExecutionChange</span><span>,</span><span class="z-constant"> MAX_BLS_TO_EXECUTION_CHANGES</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> From EIP-7732</span></span> <span class="giallo-l"><span> signed_execution_payload_header</span><span>:</span><span> SignedExecutionPayloadHeader</span></span> <span class="giallo-l"><span> payload_attestations</span><span>:</span><span> List</span><span>[</span><span>PayloadAttestation</span><span>,</span><span class="z-constant"> MAX_PAYLOAD_ATTESTATIONS</span><span>]</span></span></code></pre><h4 id="validation-changes">Validation Changes</h4> <p><strong>Block processing modifications:</strong></p> <ol> <li>Remove <code>process_eth1_data()</code> function calls from block processing</li> <li>Remove <code>process_deposits()</code> function calls from block processing</li> <li>Remove eth1_data voting validation logic</li> <li>Remove legacy deposit validation logic</li> </ol> <p><strong>State transition modifications:</strong></p> <ol> <li>Remove eth1_data related fields from state transition functions</li> <li>Remove legacy deposit processing from <code>process_operations()</code></li> </ol> <h4 id="beaconstate-cleanup">BeaconState Cleanup</h4> <p>The following fields become unused after activation and MAY be removed in future updates:</p> <ul> <li><code>eth1_data: Eth1Data</code></li> <li><code>eth1_data_votes: List[Eth1Data, EPOCHS_PER_ETH1_VOTING_PERIOD * SLOTS_PER_EPOCH]</code></li> <li><code>eth1_deposit_index: uint64</code></li> </ul> <p>Note: These fields are kept for historical state root verification but are no longer actively used.</p> <h2 id="rationale">Rationale</h2> <h3 id="timing-of-removal">Timing of Removal</h3> <p>The fields are removed after EIP-6110 finalization to ensure:</p> <ul> <li>All pending deposits from the legacy system have been processed</li> <li>No validator can be affected by the removal</li> <li>The transition is complete and irreversible</li> <li>State consistency is maintained across all honest nodes</li> </ul> <h3 id="dependency-on-eip-7732">Dependency on EIP-7732</h3> <p>This EIP requires EIP-7732 because:</p> <ul> <li>EIP-7732 already modified the <code>BeaconBlockBody</code> structure significantly</li> <li>It provides the architectural foundation for simplified block bodies</li> <li>The timing aligns with the broader consensus layer improvements</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <h2 id="security-considerations">Security Considerations</h2> <p>The removal of legacy fields poses minimal security risk because:</p> <ul> <li>The fields are already unused after EIP-6110 finalization</li> <li>All deposits are processed through the new EIP-6110 mechanism</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> 2025-08-19T00:00:00+00:00 2026-02-11T14:49:27+00:00 Greg Colvinhttps://github.com/gcolvin Alex Beregszaszihttps://github.com/axic Andrei Maiborodahttps://github.com/gumb0 Paweł Bylicahttps://github.com/chfast https://wg-eips.ritovision.com/8013/

Relative jump and call instructions with a signed immediate encoding the jump destination

<h2 id="abstract">Abstract</h2> <p>Five new EVM jump instructions are introduced (<code>RJUMP</code>, <code>RJUMPI</code>, <code>RJUMPV</code>, <code>RJUMPSUB</code>, and <code>RJUMPSUBV</code>) which encode destinations as signed immediate values. These can be useful in almost all <code>JUMP</code> and <code>JUMPI</code> use cases and offer improvements in cost, performance, and static analysis.</p> <h2 id="motivation">Motivation</h2> <p>A recurring discussion topic is that the 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, often intractable, 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 -- a form of subroutine return</li> <li>A "switch-case" table with dynamic indexing</li> </ol> <p>This proposal introduces a minimal feature set - including the above - to allow compilers to use <code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPSUB</code> exclusively.</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. This functionality also does not preclude the use of legacy code.</p> <p>The main benefit of these instruction is reduced gas cost (both at deploy and execution time), better performance and better static analysis properties.</p> <h2 id="specification">Specification</h2> <p>We introduce five new instructions, each taking either a two-byte relative offset or else a table of offsets as immediate arguments.</p> <ol> <li>relative jump: <ul> <li><code>RJUMP (0xe0) relative_offset</code> <ul> <li>sets the <code>PC</code> to <code>PC_post_instruction + relative_offset</code>, where</li> <li><code>relative_offset</code> is encoded as a 16-bit <strong>signed</strong> (two's-complement) big-endian value.</li> </ul> </li> </ul> </li> <li>conditional relative jump: <ul> <li><code>RJUMPI (0xe1) relative_offset</code> <ul> <li>pops a value (<code>condition</code>) from the stack, and</li> <li>sets the <code>PC</code> to <code>PC_post_instruction + ((condition == 0) ? 0 : relative_offset)</code>.</li> </ul> </li> </ul> </li> <li>relative jump via jump table: <ul> <li><code>RJUMPV (0xe2) max_index relative_offset+</code> <ul> <li>pops a value (<code>case</code>) from the stack, and</li> <li>sets the <code>PC</code> to <code>PC_post_instruction + ((case &gt; max_index) ? 0 : relative_offset[case])</code>.</li> </ul> </li> </ul> </li> <li>relative jump to subroutine: <ul> <li><code>RJUMPSUB (0xe3) relative_offset</code> <ul> <li>pushes <code>PC_post_instruction</code> to the <code>return stack,</code> and</li> <li>sets the <code>PC</code> to <code>PC_post_instruction + relative_offset</code>, an <code>ENTERSUB</code>, as if with <code>CALLSUB</code>.</li> </ul> </li> </ul> </li> <li>relative jump to subroutine via jump table: <ul> <li>`RJUMPSUBV (0xe4) max_index relative_offset+ <ul> <li>pops a value (<code>case</code>) from the stack,</li> <li>pushes <code>PC_post_instruction</code> to the <code>return stack</code>, and</li> <li>sets the <code>PC</code> to <code>PC_post_instruction + ((case &gt; max_index) ? 0 : relative_offset[case])</code>, an <code>ENTERSUB</code>, as if with <code>CALLSUB</code>.</li> </ul> </li> </ul> </li> </ol> <p>Note that the destination of the <code>RJUMPSUB</code> and <code>RJUMPSUBV</code> opcodes MUST be an <code>ENTERSUB</code> and control is returned to a calling <code>RJUMPSUB</code> / <code>RJUMPSUBV</code> via <code>RETURNSUB</code> (See <a href="https://wg-eips.ritovision.com/7979/">EIP-7979</a>) -- these two forms of jump provide immediate access to the underlying "return-to-caller" mechanism of the <code>CALLSUB</code> instruction.</p> <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> and <code>RjUMPSUBV</code> are 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/7979/">EIP-7979</a> to verify that every <code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code>/<code>RJUMPSUB</code>/<code>RJUMPSUBV</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> and cannot point outside of code bounds. Further, <em>all and only</em> <code>RJUMPSUB</code> and <code>RJUMPSUBV</code> MUST have a <code>relative offset</code> pointing to an `ENTERSUB, whereas the others are allowed to point to a JUMPDEST, but are not required to.</p> <h3 id="costs">Costs</h3> <p>The immediate destinations are checked during jumpdest analysis and need not be checked again, so the cost of these instructions can be less than their dynamic counterparts. We recommend that</p> <ul> <li><code>RJUMP</code> should be 2,</li> <li><code>RJUMPI</code> and <code>RJUMPV</code> should be 4. and</li> <li><code>RJUMPSUB</code> and <code>RJUMPSUBV</code> should be 5.</li> </ul> <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, and we leave defining the semantics of existing <code>PUSHn JUMP</code> sequences to EIP-7979 and do not attempt to optimize their gas cost here.</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="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-and-rjumpsubv-fallback-cases"><code>RJUMPV</code> and <code>RJUMPSUBV</code> fallback cases</h3> <p>If no match is found (i.e. the <em>default</em> case) in the <code>RJUMPV</code> or <code>RJUMPSUBV</code> instructions 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.</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> / <code>RJUMPSUBV</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>RJUMPSUB</code> / <code>RJUMPSUBV</code> target not <code>ENTERSUB</code></li> <li><code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code> / <code>RJUMPSUB</code> / <code>RJUMPSUBV</code> target outside of code section bounds</li> <li><code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code> / <code>RJUMPSUB</code> / <code>RJUMPSUBV</code> target push data</li> <li><code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code> / <code>RJUMPSUB</code> / <code>RJUMPSUBV</code> target another <code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code> immediate argument</li> </ul> <h3 id="execution">Execution</h3> <ul> <li> <p><code>RJUMP</code></p> <ul> <li><code>relative_offset</code> is positive/negative/<code>0</code></li> </ul> </li> <li> <p><code>RJUMPI</code></p> <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> <p><code>RJUMPV 0 relative_offset</code></p> <ul> <li><code>case</code> equals <code>0</code></li> <li><code>case</code> does not equal <code>0</code></li> </ul> </li> <li> <p><code>RJUMPV</code> with table containing positive, negative, <code>0</code> offsets</p> <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> <li> <p><code>RJUMPSUB</code></p> <ul> <li><code>relative_offset</code> is positive/negative/<code>0</code></li> </ul> </li> <li> <p><code>RJUMPSUBV 0 relative_offset</code></p> <ul> <li><code>case</code> equals <code>0</code></li> <li><code>case</code> does not equal <code>0</code></li> </ul> </li> <li> <p><code>RJUMPSUBV</code> with table containing positive, negative, <code>0</code> offsets</p> <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 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>and <code>RJUMPSUBV</code> instruction relative offset tables can have up to 256 one-byte entries, so reading an offset cannot be a potential DoS 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> 2025-08-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Francisco Giordanohttps://github.com/frangio Charles Cooperhttps://github.com/charles-cooper Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/8024/

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> <ul> <li><code>DUPN</code> (<code>0xe6</code>)</li> <li><code>SWAPN</code> (<code>0xe7</code>)</li> <li><code>EXCHANGE</code> (<code>0xe8</code>)</li> </ul> <p>Each instruction carries one or two immediate operands. Informally, using 1-based indexing, the semantics are:</p> <ul> <li><code>DUPN n</code>: The <code>n</code>'th stack item is duplicated at the top of the stack.</li> <li><code>SWAPN n</code>: The <code>n + 1</code>'th stack item is swapped with the top of the stack.</li> <li><code>EXCHANGE n m</code>: The <code>n + 1</code>'th stack item is swapped with the <code>m + 1</code>'th stack item.</li> </ul> <p>Formally, when <code>code[pc]</code> is one of these opcodes, the VM executes as follows:</p> <ul> <li><code>DUPN</code>: <ol> <li>Charge 3 gas.</li> <li>Let <code>x = code[pc + 1]</code>.</li> <li>If <code>90 &lt; x &lt; 128</code>, halt with exceptional failure.</li> <li>Let <code>n = decode_single(x)</code>.</li> <li>If <code>n &gt; len(stack)</code>, halt with exceptional failure.</li> <li>Push <code>stack[top - n + 1]</code> on the stack.</li> <li>Set <code>pc = pc + 2</code>.</li> </ol> </li> <li><code>SWAPN</code>: <ol> <li>Charge 3 gas.</li> <li>Let <code>x = code[pc + 1]</code>.</li> <li>If <code>90 &lt; x &lt; 128</code>, halt with exceptional failure.</li> <li>Let <code>n = decode_single(x)</code>.</li> <li>If <code>n + 1 &gt; len(stack)</code>, halt with exceptional failure.</li> <li>Swap <code>stack[top - n]</code> and <code>stack[top]</code>.</li> <li>Set <code>pc = pc + 2</code>.</li> </ol> </li> <li><code>EXCHANGE</code>: <ol> <li>Charge 3 gas.</li> <li>Let <code>x = code[pc + 1]</code>.</li> <li>If <code>79 &lt; x &lt; 128</code>, halt with exceptional failure.</li> <li>Let <code>n, m = decode_pair(x)</code>.</li> <li>If <code>m + 1 &gt; len(stack)</code>, halt with exceptional failure.</li> <li>Swap <code>stack[top - n]</code> and <code>stack[top - m]</code>.</li> <li>Set <code>pc = pc + 2</code>.</li> </ol> </li> </ul> <p><code>code[pc + 1]</code> evaluates to <code>0</code> if beyond the end of the code, matching <code>PUSH</code> behavior.</p> <p><code>top</code> denotes the index of the value at the top of the stack.</p> <p><code>JUMPDEST</code> analysis is unchanged. In particular, if <code>code[i]</code> is at an instruction boundary and is one of these opcodes, and <code>code[i + 1]</code> is <code>0x5b</code> (<code>JUMPDEST</code>), then <code>code[i + 1]</code> is a valid jump target. Note that in this case the execution of <code>code[i]</code> would halt at step 2 above (because <code>x = code[i + 1] = 0x5b = 91</code>). Disassemblers must decode such <code>code[i]</code> as <code>INVALID</code> (or <code>INVALID_DUPN</code>, etc.) and <code>code[i + 1]</code> as <code>JUMPDEST</code>.</p> <p>The auxiliary functions <code>decode_single</code> and <code>decode_pair</code> are defined by the following Python 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"> decode_single</span><span>(</span><span class="z-variable z-parameter z-function">x</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"> assert</span><span class="z-constant"> 0</span><span class="z-keyword"> &lt;=</span><span> x</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 90</span><span class="z-keyword"> or</span><span class="z-constant"> 128</span><span class="z-keyword"> &lt;=</span><span> x</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 255</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> x</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 90</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> x</span><span class="z-keyword"> +</span><span class="z-constant"> 17</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> x</span><span class="z-keyword"> -</span><span class="z-constant"> 20</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"> decode_pair</span><span>(</span><span class="z-variable z-parameter z-function">x</span><span>:</span><span class="z-support"> int</span><span>)</span><span> -&gt;</span><span> tuple</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 class="z-keyword"> assert</span><span class="z-constant"> 0</span><span class="z-keyword"> &lt;=</span><span> x</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 79</span><span class="z-keyword"> or</span><span class="z-constant"> 128</span><span class="z-keyword"> &lt;=</span><span> x</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 255</span></span> <span class="giallo-l"><span> k</span><span class="z-keyword"> =</span><span> x</span><span class="z-keyword"> if</span><span> x</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 79</span><span class="z-keyword"> else</span><span> x</span><span class="z-keyword"> -</span><span class="z-constant"> 48</span></span> <span class="giallo-l"><span> q</span><span>,</span><span> r</span><span class="z-keyword"> =</span><span class="z-support"> divmod</span><span>(</span><span>k</span><span>,</span><span class="z-constant"> 16</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> q</span><span class="z-keyword"> &lt;</span><span> r</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> q</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>,</span><span> r</span><span class="z-keyword"> +</span><span class="z-constant"> 1</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> r</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 29</span><span class="z-keyword"> -</span><span> q</span></span></code></pre> <p>Assemblers and compilers must emit a 1-byte immediate after each of these opcodes that decodes to the required <code>n, m</code> operands. For reference, this can be done by <code>encode_single</code> and <code>encode_pair</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"> encode_single</span><span>(</span><span class="z-variable z-parameter z-function">n</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"> assert</span><span class="z-constant"> 17</span><span class="z-keyword"> &lt;=</span><span> n</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 235</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> n</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 107</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> n</span><span class="z-keyword"> -</span><span class="z-constant"> 17</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> n</span><span class="z-keyword"> +</span><span class="z-constant"> 20</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"> encode_pair</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"> m</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"> assert</span><span class="z-constant"> 1</span><span class="z-keyword"> &lt;=</span><span> n</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 13</span><span class="z-keyword"> and</span><span> n</span><span class="z-keyword"> &lt;</span><span> m</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 29</span><span class="z-keyword"> and</span><span> n</span><span class="z-keyword"> +</span><span> m</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 30</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> m</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 16</span><span>:</span></span> <span class="giallo-l"><span> q</span><span>,</span><span> r</span><span class="z-keyword"> =</span><span> n</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>,</span><span> m</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> q</span><span>,</span><span> r</span><span class="z-keyword"> =</span><span class="z-constant"> 29</span><span class="z-keyword"> -</span><span> m</span><span>,</span><span> n</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> k</span><span class="z-keyword"> =</span><span class="z-constant"> 16</span><span class="z-keyword"> *</span><span> q</span><span class="z-keyword"> +</span><span> r</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> k</span><span class="z-keyword"> if</span><span> k</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 79</span><span class="z-keyword"> else</span><span> k</span><span class="z-keyword"> +</span><span class="z-constant"> 48</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="use-of-an-immediate-operand">Use of an immediate operand</h3> <p>Allowing dynamic selection of the arguments to swap or dup 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 operand that is not dynamic in nature.</p> <h3 id="disallowed-immediate-range">Disallowed immediate range</h3> <p>A property the EVM has is that it's not possible to jump to the middle of an instruction. In order to guarantee this property, the immediate operands of <code>PUSH*</code> instructions are masked from jumpdest analysis so that the occurrence of <code>0x5b</code> in them is not mistaken for a <code>JUMPDEST</code> instruction, which should be considered a valid jump target elsewhere.</p> <p>The new instructions in this EIP preserve this property without changing jumpdest analysis by making it invalid for their immediates to contain <code>0x5b</code>, in addition to <code>0x60</code> to <code>0x7f</code> (<code>PUSH1</code> to <code>PUSH32</code>) since those would cause the subsequent instructions to be masked.</p> <p>The alternative, changing jumpdest analysis to introduce new masked opcodes, would create a backwards incompatibility if done without bytecode versioning (EOF). Consider the bytecode sequence <code>e6 5b</code> that decodes to <code>INVALID JUMPDEST</code> prior to this EIP, and thus contains a valid jump target. If an instruction <code>DUPN x</code> were introduced with encoding <code>e6 {x}</code> (opcode immediately followed by operand), and jumpdest analysis changed to mask the operand to <code>e6</code>, the same bytecode sequence <code>e6 5b</code> would then decode to <code>DUPN 0x5b</code>. As a result of the upgrade, <code>e6</code> would become an invalid jump target, breaking contracts that include this sequence. The opposite can happen with push opcodes, for example, <code>e6 60 5b</code> would transform from <code>INVALID PUSH1 0x5b</code> to <code>DUPN 0x60 JUMPDEST</code>, creating a new valid jump target. Furthermore, this may have a cascading effect on arbitrarily many subsequent instructions.</p> <p>Since the EVM doesn't offer a dedicated section for data, arbitrary data may be embedded in code and serve as immutable data storage accessed via <code>CODECOPY</code>. Therefore, we must assume that arbitrary byte sequences may be found in contracts that have been deployed or are included in transactions yet to be published on chain.</p> <p>This EIP is designed to uphold the following backwards compatibility guarantee: every possible execution trace on a given bytecode that does not attempt to execute an undefined opcode must continue to produce the same effect after the introduction of an instruction. No new <code>JUMPDEST</code>s must be created in a given bytecode by the introduction of an instruction and none may be removed.</p> <p>This encoding can be reused in future instructions with immediate operands, although it is not necessary if the range of the operand naturally does not include the bytes <code>0x5b</code> (<code>JUMPDEST</code>) or <code>0x60</code> (<code>PUSH1</code>) to <code>0x7f</code> (<code>PUSH32</code>), in which case masking is not necessary.</p> <h3 id="exchange-immediate"><code>EXCHANGE</code> immediate</h3> <p>A previous formulation of <code>EXCHANGE</code> allowed swapping stack elements only if they were within some distance. As a result, it would be possible to swap the elements at indices 30 and 29, but not possible to move an element from index 30 to 2 with a single instruction. The current formulation prioritizes the latter, on the assumption that it is more valuable to move elements closer to the top of the stack than it is to rearrange elements deeper in the stack.</p> <p>In addition, the exact formulation was chosen to make <code>decode_pair</code> a simple function using only basic arithmetic, bitwise operations (division by 16), and few branches. A small trade-off in the number of addressable pairs was made to reduce the number of necessary branches; this implies some of the immediate range is not allocated, and it could be used to add a dozen more addressable pairs at the cost of more decoding complexity, potentially in a future network upgrade.</p> <p>Finally, note that the operands in the assembly instruction <code>EXCHANGE n m</code> appear "off by one", i.e. it operates on the stack elements at depths <code>n + 1</code> and <code>m + 1</code>. These offsets were chosen to match the <code>SWAP</code> and <code>SWAPN</code> opcodes such that <code>EXCHANGE n m</code> has an effect equivalent to the sequence <code>SWAP{n} SWAP{m} SWAP{n}</code>.</p> <h3 id="size-of-immediate-operand">Size of immediate operand</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 30 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 and immediate decoding is negligible.</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 contracts that would never attempt to execute the opcodes allocated by this EIP. The jump targets of existing contracts are preserved.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="assembly-disassembly">Assembly/Disassembly</h3> <ul> <li><code>e600</code> is <code>[DUPN 17]</code></li> <li><code>e780</code> is <code>[SWAPN 108]</code></li> <li><code>e6005b</code> is <code>[DUPN 17, JUMPDEST]</code></li> <li><code>e75b</code> is <code>[INVALID_SWAPN, JUMPDEST]</code></li> <li><code>e6605b</code> is <code>[INVALID_DUPN, PUSH1 0x5b]</code></li> <li><code>e7610000</code> is <code>[INVALID_SWAPN, PUSH2 0x0000]</code></li> <li><code>e65f</code> is <code>[INVALID_DUPN, PUSH0]</code></li> <li><code>e812</code> is <code>[EXCHANGE 2 3]</code></li> <li><code>e8d0</code> is <code>[EXCHANGE 1 19]</code></li> <li><code>e850</code> is <code>[INVALID_EXCHANGE, POP]</code></li> </ul> <h3 id="execution">Execution</h3> <ul> <li><code>60016000808080808080808080808080808080e600</code> results in 18 stack items, the top of the stack valued 1, the bottom of the stack valued 1, the rest valued 0 <ul> <li><code>60016000808080808080808080808080808080e6</code> at the end of the code is equivalent to above</li> </ul> </li> <li><code>600160008080808080808080808080808080806002e700</code> results in 18 stack items, the top of the stack valued 1, the bottom of the stack valued 2, the rest valued 0 <ul> <li><code>600160008080808080808080808080808080806002e7</code> at the end of the code is equivalent to above</li> </ul> </li> <li><code>600060016002e801</code> results in 3 stack items, from top to bottom: [2, 0, 1]</li> <li><code>600060006000600060006000600060006000600060006000600060006000600060006000600060006000600060006000600060006000600060016002e8</code> results in 30 stack items, the top of the stack valued 2, the bottom of the stack valued 1, the rest valued 0</li> <li><code>e75b</code> reverts</li> <li><code>600456e65b</code> executes successfully (<code>PUSH 04 JUMP INVALID_DUPN JUMPDEST</code>)</li> <li><code>600060006000e80115</code> results in 3 stack items, the top of the stack valued 1, the rest valued 0</li> <li><code>6000808080808080808080808080808080e600</code> results in exceptional halt</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> 2025-08-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Marco De Rossihttps://github.com/MarcoMetaMask Davide Crapishttps://github.com/dcrapisdavide@ethereum.org Jordan Ellisjordanellis@google.com Erik Reppelerik.reppel@coinbase.com https://wg-eips.ritovision.com/8004/

Discover agents and establish trust through reputation and validation

<h2 id="abstract">Abstract</h2> <p>This protocol proposes to use blockchains to <strong>discover, choose, and interact with agents across organizational boundaries</strong> without pre-existing trust, thus <strong>enabling open-ended agent economies</strong>.</p> <p>Trust models are pluggable and tiered, with security proportional to value at risk, from low-stake tasks like ordering pizza to high-stake tasks like medical diagnosis. Developers can choose from different trust models: reputation systems using client feedback, validation via stake-secured re-execution, zero-knowledge machine learning (zkML) proofs, or trusted execution environment (TEE) oracles.</p> <h2 id="motivation">Motivation</h2> <p>Model context protocol <!-- TODO: double check that this is the correct abbreviation -->(MCP) allows servers to list and offer their capabilities (prompts, resources, tools, and completions), while Agent2Agent <!-- TODO: double check that this is the correct abbreviation -->(A2A) handles agent authentication, skills advertisement via AgentCards, direct messaging, and complete task-lifecycle orchestration. However, these agent communication protocols don't inherently cover agent discovery and trust.</p> <p>To foster an open, cross-organizational agent economy, we need mechanisms for discovering and trusting agents in untrusted settings. This ERC addresses this need through three lightweight registries, which can be deployed on any L2 or on Mainnet as per-chain singletons:</p> <p><strong>Identity Registry</strong> - A minimal on-chain handle based on <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> with URIStorage extension <!-- Editor's Note: where is URIStorage defined? Is it an OZ thing? If so, you should include the interface here, or make a separate ERC standardizing it. -->that resolves to an agent's registration file, providing every agent with a portable, censorship-resistant identifier.</p> <p><strong>Reputation Registry</strong> - A standard interface for posting and fetching feedback signals. Scoring and aggregation occur both on-chain (for composability) and off-chain (for sophisticated algorithms), enabling an ecosystem of specialized services for agent scoring, auditor networks, and insurance pools.</p> <p><strong>Validation Registry</strong> - Generic hooks for requesting and recording independent validators checks (e.g. stakers re-running the job, zkML verifiers, TEE oracles, trusted judges).</p> <p>Payments are orthogonal to this protocol and not covered here. However, examples are provided showing how <strong>x402 payments</strong> <!-- Editor's Note: This is a coinbase thing, right? If it isn't necessary to your standard, can you omit it? -->can enrich feedback signals.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="identity-registry">Identity Registry</h3> <p>The Identity Registry uses ERC-721 with the URIStorage extension for agent registration, making <strong>all agents immediately browsable and transferable with NFTs-compliant apps</strong>. Each agent is uniquely identified globally by:</p> <ul> <li><em>agentRegistry</em>: A colon-separated string <code>{namespace}:{chainId}:{identityRegistry}</code> (e.g., <code>eip155:1:0x742...</code>) where: <ul> <li><em>namespace</em>: The chain family identifier (<code>eip155</code> for EVM chains)</li> <li><em>chainId</em>: The blockchain network identifier</li> <li><em>identityRegistry</em>: The address where the ERC-721 registry contract is deployed</li> </ul> </li> <li><em>agentId</em>: The ERC-721 tokenId assigned incrementally by the registry</li> </ul> <p>Throughout this document, <em>tokenId</em> in ERC-721 is referred to as <em>agentId</em> and <em>tokenURI</em> in ERC-721 is referred to as <em>agentURI</em>. The owner of the ERC-721 token is the owner of the agent and can transfer ownership or delegate management (e.g., updating the registration file) to operators, as supported by <code>ERC721URIStorage</code>.</p> <h4 id="agent-uri-and-agent-registration-file">Agent URI and Agent Registration File</h4> <p>The <em>agentURI</em> MUST resolve to the agent registration file. It MAY use any URI scheme such as <code>ipfs://</code> (e.g., <code>ipfs://cid</code>), <code>https://</code> (e.g., <code>https://example.com/agent3.json</code>), or a base64-encoded <code>data:</code> URI (e.g., <code>data:application/json;base64,eyJ0eXBlIjoi...</code>) for fully on-chain metadata. When the registration uri changes, it can be updated with <em>setAgentURI()</em>.</p> <p>The registration file MUST have the following structure:</p> <pre class="giallo z-code"><code data-lang="jsonc"><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">https://eips.ethereum.org/EIPS/eip-8004#registration-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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">myAgentName</span><span class="z-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 natural language description of the Agent, which MAY include what it does, how it works, pricing, and interaction methods</span><span class="z-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://example.com/agentimage.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">services</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">web</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">endpoint</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://web.agentxyz.com/</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">A2A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">endpoint</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://agent.example/.well-known/agent-card.json</span><span class="z-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-punctuation z-definition z-string"> &quot;</span><span class="z-string">0.3.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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">MCP</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">endpoint</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://mcp.agent.eth/</span><span class="z-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-punctuation z-definition z-string"> &quot;</span><span class="z-string">2025-06-18</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">OASF</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">endpoint</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ipfs://{cid}</span><span class="z-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-punctuation z-definition z-string"> &quot;</span><span class="z-string">0.8</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"> https://github.com/agntcy/oasf/tree/v0.8.0</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">skills</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">domains</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span>]</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</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">ENS</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">endpoint</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">vitalik.eth</span><span class="z-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-punctuation z-definition z-string"> &quot;</span><span class="z-string">v1</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">DID</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">endpoint</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">did:method:foobar</span><span class="z-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-punctuation z-definition z-string"> &quot;</span><span class="z-string">v1</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">email</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">endpoint</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">mail@myagent.com</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">x402Support</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">active</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">registrations</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">agentId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 22</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">agentRegistry</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">{namespace}:{chainId}:{identityRegistry}</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> e.g. eip155:1:0x742...</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">supportedTrust</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">reputation</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">crypto-economic</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">tee-attestation</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 <em>type</em>, <em>name</em>, <em>description</em>, and <em>image</em> fields at the top SHOULD ensure compatibility with ERC-721 apps. The number and type of <em>endpoints</em> are fully customizable, allowing developers to add as many as they wish. The <em>version</em> field in endpoints is a SHOULD, not a MUST.</p> <p>Agents MAY advertise their endpoints, which point to an A2A agent card, an MCP endpoint, an ENS agent name, DIDs, or the agent's wallets on any chain (even chains where the agent is not registered).</p> <h4 id="endpoint-domain-verification-optional">Endpoint Domain Verification (Optional)</h4> <p>Since endpoints can point to domains not controlled by the agent owner, an agent MAY optionally prove control of an HTTPS endpoint-domain by publishing <code>https://{endpoint-domain}/.well-known/agent-registration.json</code> containing at least a <code>registrations</code> list (or the full agent registration file). Users MAY treat the endpoint-domain as verified if the file is reachable over HTTPS and includes a <code>registrations</code> entry whose <code>agentRegistry</code> and <code>agentId</code> match the on-chain agent; if the endpoint-domain is the same domain that serves the agent’s primary registration file referenced by <code>agentURI</code>, this additional check is not needed because domain control is already demonstrated there.</p> <p>Agents SHOULD have at least one registration (multiple are possible), and all fields in the registration are mandatory. The <em>supportedTrust</em> field is OPTIONAL. If absent or empty, this ERC is used only for discovery, not for trust.</p> <h4 id="on-chain-metadata">On-chain metadata</h4> <p>The registry extends ERC-721 by adding <code>getMetadata(uint256 agentId, string metadataKey)</code> and <code>setMetadata(uint256 agentId, string metadataKey, bytes metadataValue)</code> functions for optional extra on-chain agent metadata:</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"> getMetadata</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> agentId</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> metadataKey</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 class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> setMetadata</span><span>(</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> agentId</span><span>,</span><span class="z-entity z-name"> string</span><span class="z-storage z-type"> memory</span><span class="z-entity z-name"> metadataKey</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"> metadataValue</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>When metadata is set, the following event is 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"> MetadataSet</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> agentId</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> indexedMetadataKey</span><span>, </span><span class="z-support">string</span><span class="z-variable"> metadataKey</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> metadataValue</span><span>)</span></span></code></pre> <p>The key <code>agentWallet</code> is reserved and cannot be set via <code>setMetadata()</code> or during <code>register()</code> (including the metadata array overload). It represents the address where the agent receives payments and is initially set to the owner's address. To change it, the agent owner must prove control of the new wallet by providing a valid <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> signature for EOAs or <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> for smart contract wallets—by calling:</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"> setAgentWallet</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> agentId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> newWallet</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"> calldata</span><span class="z-variable"> signature</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>To read and clear the currently set wallet, the following functions are exposed:</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"> getAgentWallet</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> agentId</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 class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> unsetAgentWallet</span><span>(</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> agentId</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>When the agent is transferred, <code>agentWallet</code> is automatically cleared (effectively resetting it to the zero address) and must be re-verified by the new owner.</p> <h4 id="registration">Registration</h4> <p>New agents can be minted by calling one of these functions:</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"> MetadataEntry</span><span> {</span></span> <span class="giallo-l"><span class="z-support">string</span><span> metadataKey</span><span>;</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span> metadataValue</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"> register</span><span>(</span><span class="z-support">string</span><span class="z-variable"> agentURI</span><span>,</span><span class="z-storage z-type"> MetadataEntry</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> metadata</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"> agentId</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"> register</span><span>(</span><span class="z-entity z-name">string</span><span class="z-entity z-name"> agentURI</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"> agentId</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// </span><span class="z-entity z-name">agentURI</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> added</span><span class="z-entity z-name"> later</span><span class="z-entity z-name"> with</span><span class="z-entity z-name"> setAgentURI</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> register</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">uint256</span><span class="z-variable"> agentId</span><span>)</span></span></code></pre> <p>This emits one Transfer event, one MetadataSet event for the reserved <code>agentWallet</code> key, one MetadataSet event for each additional metadata entry (if any), and</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"> Registered</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> agentId</span><span>, </span><span class="z-support">string</span><span class="z-variable"> agentURI</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></code></pre><h4 id="update-agenturi">Update agentURI</h4> <p>The agentURI can be updated by calling the following function, which emits a URIUpdated event:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setAgentURI</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> agentId</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> newURI</span><span>)</span><span class="z-storage z-type"> external</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"> URIUpdated</span><span>(</span><span class="z-entity z-name">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-entity z-name"> agentId</span><span>,</span><span class="z-entity z-name"> string</span><span class="z-entity z-name"> newURI</span><span>,</span><span class="z-entity z-name"> address</span><span class="z-storage z-type"> indexed</span><span class="z-entity z-name"> updatedBy</span><span>)</span></span> <span class="giallo-l"></span></code></pre> <p>If the owner wants to store the entire registration file on-chain, the <em>agentURI</em> SHOULD use a base64-encoded data URI rather than a serialized JSON string:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>data:application/json;base64,eyJ0eXBlIjoi...</span></span></code></pre><h3 id="reputation-registry">Reputation Registry</h3> <p>When the Reputation Registry is deployed, the <em>identityRegistry</em> address is set via <code>initialize(address identityRegistry_)</code> and publicly visible by calling:</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"> getIdentityRegistry</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"> identityRegistry</span><span>)</span></span></code></pre> <p>The feedback given by a <em>clientAddress</em> to an agent consists of a signed fixed-point <em>value</em> (<code>int128</code>) and its <em>valueDecimals</em> (<code>uint8</code>, 0-18), plus optional <em>tag1</em> and <em>tag2</em> (left to developers' discretion to provide maximum on-chain composability and filtering), an <em>endpoint</em> URI, a file URI pointing to an off-chain JSON containing additional information, and its KECCAK-256 file hash to guarantee integrity. We suggest using IPFS or equivalent services to make feedback easily indexed by subgraphs or similar technologies. For IPFS URIs, the hash is not required. All fields except <em>value</em> and <em>valueDecimals</em> are OPTIONAL, so the off-chain file is not required and can be omitted.</p> <h4 id="giving-feedback">Giving Feedback</h4> <p>New feedback can be added by any <em>clientAddress</em> calling:</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"> giveFeedback</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> agentId</span><span>,</span><span class="z-support"> int128</span><span class="z-variable"> value</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> valueDecimals</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> tag1</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> tag2</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> endpoint</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> feedbackURI</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> feedbackHash</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>The <em>agentId</em> must be a validly registered agent. The <em>valueDecimals</em> MUST be between 0 and 18. The feedback submitter MUST NOT be the agent owner or an approved operator for <em>agentId</em>. <em>tag1</em>, <em>tag2</em>, <em>endpoint</em>, <em>feedbackURI</em>, and <em>feedbackHash</em> are OPTIONAL.</p> <p>Where provided, <em>feedbackHash</em> is the KECCAK-256 hash (<code>keccak256</code>) of the content referenced by <em>feedbackURI</em>, enabling verifiable integrity for non-content-addressed URIs. For IPFS (or other content-addressed URIs), <em>feedbackHash</em> is OPTIONAL and can be omitted (e.g., set to <code>bytes32(0)</code>).</p> <p>If the procedure succeeds, an event is 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"> NewFeedback</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> agentId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> clientAddress</span><span>, </span><span class="z-support">uint64</span><span class="z-variable"> feedbackIndex</span><span>, </span><span class="z-support">int128</span><span class="z-variable"> value</span><span>, </span><span class="z-support">uint8</span><span class="z-variable"> valueDecimals</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> indexedTag1</span><span>, </span><span class="z-support">string</span><span class="z-variable"> tag1</span><span>, </span><span class="z-support">string</span><span class="z-variable"> tag2</span><span>, </span><span class="z-support">string</span><span class="z-variable"> endpoint</span><span>, </span><span class="z-support">string</span><span class="z-variable"> feedbackURI</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> feedbackHash</span><span>)</span></span></code></pre> <p>The feedback fields <em>value</em>, <em>valueDecimals</em>, <em>tag1</em>, <em>tag2</em>, and <em>isRevoked</em> are stored in the contract storage along with the feedbackIndex (a 1-indexed counter of feedback submissions that <em>clientAddress</em> has given to <em>agentId</em>). The fields <em>endpoint</em>, <em>feedbackURI</em>, and <em>feedbackHash</em> are emitted but are not stored. This exposes reputation signals to any smart contract, enabling on-chain composability.</p> <p>When the feedback is given by an agent (i.e., the client is an agent), the agent SHOULD use the address set in the on-chain optional <code>agentWallet</code> metadata as the clientAddress, to facilitate reputation aggregation.</p> <h4 id="examples-of-value-valuedecimals">Examples of <code>value</code> / <code>valueDecimals</code></h4> <table><thead><tr><th>tag1</th><th>What it measures</th><th>Example human value</th><th><code>value</code></th><th><code>valueDecimals</code></th></tr></thead><tbody> <tr><td><code>starred</code></td><td>Quality rating (0-100)</td><td><code>87/100</code></td><td><code>87</code></td><td><code>0</code></td></tr> <tr><td><code>reachable</code></td><td>Endpoint reachable (binary)</td><td><code>true</code></td><td><code>1</code></td><td><code>0</code></td></tr> <tr><td><code>ownerVerified</code></td><td>Endpoint owned by agent owner (binary)</td><td><code>true</code></td><td><code>1</code></td><td><code>0</code></td></tr> <tr><td><code>uptime</code></td><td>Endpoint uptime (%)</td><td><code>99.77%</code></td><td><code>9977</code></td><td><code>2</code></td></tr> <tr><td><code>successRate</code></td><td>Endpoint success rate (%)</td><td><code>89%</code></td><td><code>89</code></td><td><code>0</code></td></tr> <tr><td><code>responseTime</code></td><td>Response time (ms)</td><td><code>560ms</code></td><td><code>560</code></td><td><code>0</code></td></tr> <tr><td><code>blocktimeFreshness</code></td><td>Avg block delay (blocks)</td><td><code>4 blocks</code></td><td><code>4</code></td><td><code>0</code></td></tr> <tr><td><code>revenues</code></td><td>Cumulative revenues (e.g., USD)</td><td><code>$560</code></td><td><code>560</code></td><td><code>0</code></td></tr> <tr><td><code>tradingYield</code> (<code>tag2</code> = <code>day, week, month, year</code>)</td><td>Yield</td><td><code>-3,2%</code></td><td><code>-32</code></td><td><code>1</code></td></tr> </tbody></table> <h4 id="off-chain-feedback-file-structure">Off-Chain Feedback File Structure</h4> <p>The OPTIONAL file at the URI could look like:</p> <pre class="giallo z-code"><code data-lang="jsonc"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> MUST FIELDS</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">agentRegistry</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eip155:1:{identityRegistry}</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">agentId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 22</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">clientAddress</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eip155:1:{clientAddress}</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">createdAt</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2025-09-23T12:00:00Z</span><span class="z-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-constant"> 100</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">valueDecimals</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 0</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"> ALL OPTIONAL FIELDS</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">tag1</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">foo</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">tag2</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">bar</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">endpoint</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://agent.example.com/GetPrice</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">mcp</span><span class="z-support">&quot;</span><span>:</span><span> {</span><span class="z-support"> &quot;</span><span class="z-support">tool</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ToolName</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> or: { &quot;prompt&quot;: &quot;PromptName&quot; } / { &quot;resource&quot;: &quot;ResourceName&quot; }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> A2A: see &quot;Context Identifier Semantics&quot; and Task model in the A2A specification.</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">a2a</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">skills</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">as-defined-by-A2A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> e.g., AgentSkill identifiers</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">contextId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">as-defined-by-A2A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">taskId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">as-defined-by-A2A</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">oasf</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">skills</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">as-defined-by-OASF</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">domains</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">as-defined-by-OASF</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> </span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">proofOfPayment</span><span class="z-support">&quot;</span><span>:</span><span> {</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> this can be used for x402 proof of payment</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">fromAddress</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">toAddress</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">chainId</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">txHash</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 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"> Other fields</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 class="z-support"> &quot;</span><span class="z-support"> ... </span><span class="z-support">&quot;</span><span> }</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> MAY</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="revoking-feedback">Revoking Feedback</h4> <p><em>clientAddress</em> can revoke feedback by calling:</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"> revokeFeedback</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> agentId</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> feedbackIndex</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>This emits:</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"> FeedbackRevoked</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> agentId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> clientAddress</span><span>, </span><span class="z-support">uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> feedbackIndex</span><span>)</span></span></code></pre><h4 id="appending-responses">Appending Responses</h4> <p>Anyone (e.g., the <em>agentId</em> showing a refund, any off-chain data intelligence aggregator tagging feedback as spam) can call:</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"> appendResponse</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> agentId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> clientAddress</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> feedbackIndex</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> responseURI</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> responseHash</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>Where <em>responseHash</em> is the KECCAK-256 file hash of the <em>responseURI</em> file content to guarantee integrity. This field is not required for IPFS URIs.</p> <p>This emits:</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"> ResponseAppended</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> agentId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> clientAddress</span><span>, </span><span class="z-support">uint64</span><span class="z-variable"> feedbackIndex</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> responder</span><span>, </span><span class="z-support">string</span><span class="z-variable"> responseURI</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> responseHash</span><span>)</span></span></code></pre><h4 id="read-functions">Read Functions</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"> getSummary</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> agentId</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"> clientAddresses</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> tag1</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> tag2</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 class="z-variable"> count</span><span>,</span><span class="z-support"> int128</span><span class="z-variable"> summaryValue</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> summaryValueDecimals</span><span>)</span></span> <span class="giallo-l"><span>// </span><span class="z-entity z-name">agentId</span><span class="z-entity z-name"> and</span><span class="z-entity z-name"> clientAddresses</span><span class="z-entity z-name"> are</span><span class="z-entity z-name"> mandatory</span><span>;</span><span> tag1 and tag2 are optional filters</span><span>.</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> clientAddresses MUST be provided (non-empty); results without filtering by clientAddresses are subject to Sybil/spam attacks. See Security Considerations for details</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> readFeedback</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> agentId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> clientAddress</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> feedbackIndex</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">int128</span><span class="z-variable"> value</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> valueDecimals</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> tag1</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> tag2</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> isRevoked</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"> readAllFeedback</span><span>(</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> agentId</span><span>,</span><span class="z-entity z-name"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-entity z-name"> clientAddresses</span><span>,</span><span class="z-entity z-name"> string</span><span class="z-entity z-name"> tag1</span><span>,</span><span class="z-entity z-name"> string</span><span class="z-entity z-name"> tag2</span><span>,</span><span class="z-entity z-name"> bool</span><span class="z-entity z-name"> includeRevoked</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"> clients</span><span>,</span><span class="z-support"> uint64</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> feedbackIndexes</span><span>,</span><span class="z-support"> int128</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> values</span><span>,</span><span class="z-support"> uint8</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> valueDecimals</span><span>,</span><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tag1s</span><span>,</span><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tag2s</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"> revokedStatuses</span><span>)</span></span> <span class="giallo-l"><span>// </span><span class="z-entity z-name">agentId</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> only</span><span class="z-entity z-name"> mandatory</span><span class="z-entity z-name"> parameter</span><span>;</span><span> others are optional filters</span><span>.</span><span> Revoked feedback are omitted by default</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"> getResponseCount</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> agentId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> clientAddress</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> feedbackIndex</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-variable"> responders</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 class="z-variable"> count</span><span>)</span></span> <span class="giallo-l"><span>// </span><span class="z-entity z-name">agentId</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> only</span><span class="z-entity z-name"> mandatory</span><span class="z-entity z-name"> parameter</span><span>;</span><span> others are optional filters</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"> getClients</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> agentId</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 class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> getLastIndex</span><span>(</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> agentId</span><span>,</span><span class="z-entity z-name"> address</span><span class="z-entity z-name"> clientAddress</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></code></pre> <p>We expect reputation systems around reviewers/clientAddresses to emerge. <strong>While simple filtering by reviewer (useful to mitigate spam) and by tag are enabled on-chain, more complex reputation aggregation will happen off-chain</strong>.</p> <h3 id="validation-registry">Validation Registry</h3> <p><strong>This registry enables agents to request verification of their work and allows validator smart contracts to provide responses that can be tracked on-chain</strong>. Validator smart contracts could use, for example, stake-secured inference re-execution, zkML verifiers or TEE oracles to validate or reject requests.</p> <p>When the Validation Registry is deployed, the <em>identityRegistry</em> address is set via <code>initialize(address identityRegistry_)</code> and is visible by calling <code>getIdentityRegistry()</code>, as described above.</p> <h4 id="validation-request">Validation Request</h4> <p>Agents request validation by calling:</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"> validationRequest</span><span>(</span><span class="z-support">address</span><span class="z-variable"> validatorAddress</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> agentId</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> requestURI</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> requestHash</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>This function MUST be called by the owner or operator of <em>agentId</em>. The <em>requestURI</em> points to off-chain data containing all information needed for the validator to validate, including inputs and outputs needed for the verification. The <em>requestHash</em> is a commitment to this data (<code>keccak256</code> of the request payload) and identifies the request. All other fields are mandatory.</p> <p>A ValidationRequest event is 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"> ValidationRequest</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> validatorAddress</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> agentId</span><span>, </span><span class="z-support">string</span><span class="z-variable"> requestURI</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> requestHash</span><span>)</span></span></code></pre><h4 id="validation-response">Validation Response</h4> <p>Validators respond by calling:</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"> validationResponse</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> requestHash</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> response</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> responseURI</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> responseHash</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> tag</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>Only <em>requestHash</em> and <em>response</em> are mandatory; <em>responseURI</em>, <em>responseHash</em> and <em>tag</em> are optional. This function MUST be called by the <em>validatorAddress</em> specified in the original request. The <em>response</em> is a value between 0 and 100, which can be used as binary (0 for failed, 100 for passed) or with intermediate values for validations with a spectrum of outcomes. The optional <em>responseURI</em> points to off-chain evidence or audit of the validation, <em>responseHash</em> is its commitment (in case the resource is not on IPFS), while <em>tag</em> allows for custom categorization or additional data.</p> <p>validationResponse() can be called multiple times for the same <em>requestHash</em>, enabling use cases like progressive validation states (e.g., “soft finality” and “hard finality” using <em>tag</em>) or updates to validation status.</p> <p>Upon successful execution, a <em>ValidationResponse</em> event is emitted with all function parameters:</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"> ValidationResponse</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> validatorAddress</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> agentId</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> requestHash</span><span>, </span><span class="z-support">uint8</span><span class="z-variable"> response</span><span>, </span><span class="z-support">string</span><span class="z-variable"> responseURI</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> responseHash</span><span>, </span><span class="z-support">string</span><span class="z-variable"> tag</span><span>)</span></span></code></pre> <p>The contract stores <em>requestHash</em>, <em>validatorAddress</em>, <em>agentId</em>, <em>response</em>, <em>responseHash</em>, <em>lastUpdate</em>, and <em>tag</em> for on-chain querying and composability.</p> <h4 id="read-functions-1">Read Functions</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"> getValidationStatus</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> requestHash</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"> validatorAddress</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> agentId</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> response</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> responseHash</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> tag</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> lastUpdate</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>//</span><span class="z-entity z-name">Returns</span><span class="z-entity z-name"> aggregated</span><span class="z-entity z-name"> validation</span><span class="z-entity z-name"> statistics</span><span class="z-keyword"> for</span><span class="z-entity z-name"> an</span><span class="z-entity z-name"> agent</span><span>.</span><span class="z-entity z-name"> agentId</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> only</span><span class="z-entity z-name"> mandatory</span><span class="z-entity z-name"> parameter</span><span>;</span><span> validatorAddresses and tag are optional filters</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getSummary</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> agentId</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"> validatorAddresses</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> tag</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 class="z-variable"> count</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> averageResponse</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"> getAgentValidations</span><span>(</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> agentId</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 class="z-variable"> requestHashes</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"> getValidatorRequests</span><span>(</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> validatorAddress</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 class="z-variable"> requestHashes</span><span>)</span></span></code></pre> <p>Incentives and slashing related to validation are managed by the specific validation protocol and are outside the scope of this registry.</p> <h2 id="rationale">Rationale</h2> <ul> <li><strong>Agent communication protocols</strong>: MCP and A2A are popular, and other protocols could emerge. For this reason, this protocol links from the blockchain to a flexible registration file including a list where endpoints can be added at will, combining AI primitives (MCP, A2A) and Web3 primitives such as wallet addresses, DIDs, and ENS names.</li> <li><strong>Feedback</strong>: The protocol combines the leverage of nomenclature already established by A2A (such as tasks and skills) and MCP (such as tools and prompts) with complete flexibility in the feedback signal structure.</li> <li><strong>Gas Sponsorship</strong>: Since clients don't need to be registered anymore, any application can implement frictionless feedback leveraging <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>.</li> <li><strong>Indexing</strong>: Since feedback data is saved on-chain and we suggest using IPFS for full data, it's easy to leverage subgraphs to create indexers and improve UX.</li> <li><strong>Deployment</strong>: We expect the registries to be deployed with singletons per chain. Note that an agent registered and receiving feedback on chain A can still operate and transact on other chains. Agents can also be registered on multiple chains if desired.</li> </ul> <!-- Editor's Note: The test cases section should be a list of input/output/state changes or automated test functions. Simply listing "what to test" is insufficient. --> <!-- ## Test Cases This protocol enables: * Crawling all agents starting from a logically centralized endpoint and discover agent information (name, image, services), capabilities, communication endpoints (MCP, A2A, others), ENS names, wallet addresses and which trust models they support (reputation, validation, TEE attestation) * Building agent explorers and marketplaces using any ERC-721 compatible application to browse, transfer, and manage agents * Building reputation systems with on-chain aggregation (average scores for smart contract composability) or sophisticated off-chain analysis. All reputation signals are public good. * Discovering which agents support stake-secured or zkML validation and how to request it through a standardized interface --> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>Sybil attacks are possible, inflating the reputation of fake agents. The protocol's contribution is to make signals public and use the same schema. We expect many players to build reputation systems, for example, trusting or giving reputation to reviewers (and therefore filtering by reviewer, as the protocol already enables).</li> <li>On-chain pointers and hashes cannot be deleted, ensuring audit trail integrity</li> <li>Validator incentives and slashing are managed by specific validation protocols</li> <li>While this ERC cryptographically ensures the registration file corresponds to the on-chain agent, it cannot cryptographically guarantee that advertised capabilities are functional and non-malicious. The three trust models (reputation, validation, and TEE attestation) are designed to support this verification need</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-08-07T00:00:00+00:00 2026-02-11T14:48:25+00:00 Artem Chystiakovhttps://github.com/arvolear Oleh Komendanthttps://github.com/Hrom131 https://wg-eips.ritovision.com/8002/

Trustless singleton contract for on-chain verification of Bitcoin transactions through block headers

<h2 id="abstract">Abstract</h2> <p>Introduce a singleton contract for on-chain verification of transactions that happened on Bitcoin. The contract is available at "0xTODO" <!-- TODO -->, acting as a trustless Simplified Payment Verification (SPV) gateway where anyone can submit Bitcoin block headers. The gateway maintains the mainchain of blocks and allows the existence of Bitcoin transactions to be verified via Merkle proofs.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum's long-term mission has always been to revolutionize the financial world through decentralization, trustlessness, and programmable value enabled by smart contracts. Many great use cases have been discovered so far, including the renaissance of Decentralized Finance (DeFi), emergence of Real-World Assets (RWA), and rise of privacy-preserving protocols.</p> <p>However, one gem has been unreachable to date -- Bitcoin. Due to its extremely constrained programmability, one can only hold and transfer bitcoins in a trustless manner. This EIP tries to expand its capabilities by laying a solid foundation for bitcoins to be also used in various EVM-based DeFi protocols, unlocking a whole new trillion-dollar market.</p> <p>The singleton SPV gateway contract defined in this proposal acts as a trustless one-way bridge between Bitcoin and Ethereum, already enabling use cases such as using <em>native</em> BTC as a lending collateral for stablecoin loans. Moreover, with the recent breakthroughs in the BitVM technology, the full-fledged, ownerless two-way bridge may soon become a reality, powering the permissionless and wrapless issuance of BTC on Ethereum.</p> <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="general">General</h3> <h4 id="bitcoin-block-header-structure">Bitcoin Block Header Structure</h4> <p>In Bitcoin, each block contains a header, which has a fixed size of 80 bytes and follows the following structure:</p> <table><thead><tr><th style="text-align: left">Field</th><th style="text-align: left">Size</th><th style="text-align: left">Format</th><th style="text-align: left">Description</th></tr></thead><tbody> <tr><td style="text-align: left">Version</td><td style="text-align: left">4 bytes</td><td style="text-align: left">little-endian</td><td style="text-align: left">The version number of the block.</td></tr> <tr><td style="text-align: left">Previous Block</td><td style="text-align: left">32 bytes</td><td style="text-align: left">natural byte order</td><td style="text-align: left">The block hash of a previous block this block is building on top of.</td></tr> <tr><td style="text-align: left">Merkle Root</td><td style="text-align: left">32 bytes</td><td style="text-align: left">natural byte order</td><td style="text-align: left">A fingerprint for all of the transactions included in the block.</td></tr> <tr><td style="text-align: left">Time</td><td style="text-align: left">4 bytes</td><td style="text-align: left">little-endian</td><td style="text-align: left">The current time as a Unix timestamp.</td></tr> <tr><td style="text-align: left">Bits</td><td style="text-align: left">4 bytes</td><td style="text-align: left">little-endian</td><td style="text-align: left">A compact representation of the current target (difficulty).</td></tr> <tr><td style="text-align: left">Nonce</td><td style="text-align: left">4 bytes</td><td style="text-align: left">little-endian</td><td style="text-align: left">A 32-bit number which miners compute to find a valid block hash.</td></tr> </tbody></table> <p>The fields within the block header are sequentially ordered as presented in the table above.</p> <h4 id="difficulty-adjustment-mechanism">Difficulty Adjustment Mechanism</h4> <p>Bitcoin's Proof-of-Work (PoW) consensus mechanism has a probabilistic finality, thus relying on a dynamic <strong>difficulty target</strong> adjustments. The target's initial value is set to <code>0x00000000ffff0000000000000000000000000000000000000000000000000000</code>, which also serves as the minimum difficulty threshold.</p> <p>The <code>target</code> is recalculated every 2016 blocks (approximately every two weeks), a period commonly referred to as a <strong>difficulty adjustment period</strong>.</p> <p>The expected duration for each adjustment period is 1,209,600 seconds (2016 blocks * 10 minutes/block). The new <code>target</code> value is derived by multiplying the current <code>target</code> by the ratio of the actual time taken to mine the preceding 2016 blocks to this expected duration.</p> <p>To prevent drastic difficulty fluctuations, the adjustment multiplier is capped at <code>4x</code> and <code>1/4x</code> respectively.</p> <h4 id="block-header-validation-rules">Block Header Validation Rules</h4> <p>For a Bitcoin block header to be considered valid and accepted into the chain, it MUST adhere to the following consensus rules:</p> <ol> <li> <p><strong>Chain Cohesion</strong>: The <code>Previous Block</code> hash field MUST reference the hash of a valid block that is present in the set of existing block headers.</p> </li> <li> <p><strong>Timestamp Rules</strong>:</p> <ul> <li>The <code>Time</code> field MUST be strictly greater than the <strong>Median Time Past (MTP)</strong> of the previous 11 blocks.</li> <li>The <code>Time</code> field MUST NOT be more than 2 hours in the future relative to the validating node's network-adjusted time.</li> </ul> </li> <li> <p><strong>PoW Constraint</strong>: When the block header is hashed twice using <code>SHA256</code>, the resulting hash MUST be less than or equal to the current <code>target</code> value, as derived from the difficulty adjustment mechanism.</p> </li> </ol> <h4 id="transaction-inclusion-structure">Transaction Inclusion Structure</h4> <p>Every Bitcoin block header has a field <code>Merkle Root</code> that corresponds to a Merkle root of the transactions tree included in this block.</p> <p>The transactions Merkle tree is built recursively performing double <code>SHA256</code> hash on each pair of sibling nodes, where the tree leaves are the double <code>SHA256</code> hash of the raw transaction bytes. In case the node has no siblings, the hashing is done over the node with itself.</p> <p>To verify the transaction inclusion into the block, one SHOULD build the Merkle root from the ground up and compare it with the <code>Merkle Root</code> stored in the selected block header. The corresponding Merkle path and hashing direction bits can be obtained and processed by querying a Bitcoin full node.</p> <h4 id="mainchain-definition">Mainchain Definition</h4> <p>Bitcoin's <strong>mainchain</strong> is determined not just by its length, but by the greatest <strong>cumulative PoW</strong> among all valid competing chains. This cumulative work represents the total computational effort expended to mine all blocks within a specific chain.</p> <p>The work contributed by a single block is inversely proportional to its <code>target</code> value. Specifically, the work of a block can be calculated as <code>(2**256 - 1) / (target + 1)</code>. The <code>target</code> value for a block is derived from its <code>Bits</code> field, where the first byte encodes the required left hand bit shift, and the other three bytes the actual target value.</p> <p>The total cumulative work of a chain is the sum of the work values of all blocks within that chain. A block is considered part of the mainchain if it extends the chain with the greatest cumulative PoW.</p> <h3 id="spv-gateway">SPV Gateway</h3> <p>The <code>SPVGateway</code> contract MUST provide a permissionless mechanism for its initialization. This mechanism MUST allow for the submission of a valid Bitcoin block header, its corresponding block height, and the cumulative PoW up to that block, without requiring special permissions.</p> <p>The <code>SPVGateway</code> MUST implement the following 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-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 for a Simplified Payment Verification Gateway 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"> ISPVGateway</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"> Represents the essential data contained within a Bitcoin block header</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> prevBlockHash</span><span class="z-comment"> The hash of the previous block</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> merkleRoot</span><span class="z-comment"> The Merkle root of the transactions in the block</span></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 block version number</span></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 block&#39;s 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"> nonce</span><span class="z-comment"> The nonce used for mining</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> bits</span><span class="z-comment"> The encoded difficulty target for the block</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"> BlockHeaderData</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> prevBlockHash</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> merkleRoot</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> version</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> time</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> nonce</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes4</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * MUST be emitted whenever the mainchain head </span><span class="z-keyword">changed</span><span class="z-comment"> (e.g. in the `addBlockHeader`, `addBlockHeaderBatch` functions)</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"> MainchainHeadUpdated</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> newMainchainHeight</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"> newMainchainHead</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"> * MUST be emitted whenever the new block header added to the SPV contract state</span></span> <span class="giallo-l"><span class="z-comment"> * (e.g. in the `addBlockHeader`, `addBlockHeaderBatch` functions)</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"> BlockHeaderAdded</span><span>(</span><span class="z-support">uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> blockHeight</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> blockHash</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"> Adds a single raw block header to the contract.</span></span> <span class="giallo-l"><span class="z-comment"> * The block header is validated before being 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"> blockHeaderRaw</span><span class="z-comment"> The raw block header bytes</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"> addBlockHeader</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> blockHeaderRaw</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"> OPTIONAL Function that adds a batch of the block headers to the contract.</span></span> <span class="giallo-l"><span class="z-comment"> * Each block header is validated and added sequentially</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> blockHeaderRawArray</span><span class="z-comment"> An array of raw block header bytes</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"> addBlockHeaderBatch</span><span>(</span><span class="z-support">bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> blockHeaderRawArray</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"> Checks that given txId is included in the specified block with a minimum number of confirmations.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> merkleProof</span><span class="z-comment"> The array of hashes used to build the Merkle root</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> blockHash</span><span class="z-comment"> The hash of the block in which to verify 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"> txId</span><span class="z-comment"> The transaction id to verify</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> txIndex</span><span class="z-comment"> The index of the transaction in the block&#39;s Merkle tree</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> minConfirmationsCount</span><span class="z-comment"> The minimum number of confirmations required for the 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"> True</span><span class="z-comment"> if the txId is present in the block&#39;s Merkle tree and the block has at least minConfirmationsCount confirmations, 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"> checkTxInclusion</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"> merkleProof</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> blockHash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> txId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> txIndex</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> minConfirmationsCount</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"> Returns the hash of the current mainchain head.</span></span> <span class="giallo-l"><span class="z-comment"> * This represents the highest block on the most accumulated work chain</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"> hash of the mainchain head</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"> getMainchainHead</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns the height of the current mainchain head.</span></span> <span class="giallo-l"><span class="z-comment"> * This represents the highest block number on the most accumulated work chain</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"> height of the mainchain head</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"> getMainchainHeight</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">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"> Returns the block header data for a given block hash.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> blockHash</span><span class="z-comment"> The hash of the 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"> block header data</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"> getBlockHeader</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> blockHash</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">BlockHeaderData</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns the current status of a given block</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> blockHash</span><span class="z-comment"> The hash of the block to check</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"> isInMainchain</span><span class="z-comment"> True if the block is in the mainchain, false otherwise</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"> confirmationsCount</span><span class="z-comment"> The number of blocks that have been mined on top of </span></span> <span class="giallo-l"><span class="z-comment"> * the given block if the block is in the mainchain</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"> getBlockStatus</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> blockHash</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"> 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"> Returns the Merkle root of a given block hash.</span></span> <span class="giallo-l"><span class="z-comment"> * This function retrieves the Merkle root from the stored block header 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"> blockHash</span><span class="z-comment"> The hash of the 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"> Merkle root of the block</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"> getBlockMerkleRoot</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> blockHash</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">@notice</span><span class="z-comment"> Returns the block height for a given block hash</span></span> <span class="giallo-l"><span class="z-comment"> * This function retrieves the height at which the block exists in the chain</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> blockHash</span><span class="z-comment"> The hash of the 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"> height of the block</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"> getBlockHeight</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> blockHash</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"> Returns the block hash for a given block height.</span></span> <span class="giallo-l"><span class="z-comment"> * This function retrieves the hash of the block from the mainchain at the specified height</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> blockHeight</span><span class="z-comment"> The height of the 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"> hash of the block</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"> getBlockHash</span><span>(</span><span class="z-support">uint64</span><span class="z-variable"> blockHeight</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">@notice</span><span class="z-comment"> Checks if a block exists in the contract&#39;s storage.</span></span> <span class="giallo-l"><span class="z-comment"> * This function verifies the presence of a block by its hash</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> blockHash</span><span class="z-comment"> The hash of the block to check</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 block exists, 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"> blockExists</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> blockHash</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>All fields within the <code>BlockHeaderData</code> struct MUST be converted to big-endian byte order for internal representation and processing within the smart contract.</p> <p>The <code>addBlockHeader</code> function MUST perform the following checks:</p> <ul> <li>Validate that the submitted raw block header has a fixed size of 80 bytes.</li> <li>Enforce all block header validation rules as specified in the "Block Header Validation Rules" section.</li> <li>Integrate the new block header into the known chain by calculating its cumulative PoW and managing potential chain reorganizations as defined in the "Mainchain Definition" section.</li> <li>Emit a <code>BlockHeaderAdded</code> event upon successful addition of the block header.</li> <li>Emit a <code>MainchainHeadUpdated</code> event if the mainchain was updated.</li> </ul> <p>The <code>checkTxInclusion</code> function MUST perform the following steps:</p> <ul> <li>Check whether the provided <code>blockHash</code> is part of the mainchain and ensure its number of confirmations is at least equal to the <code>minConfirmationsCount</code> parameter. If any of these checks fail, the function MUST return <code>false</code>.</li> <li>Using the provided <code>merkleProof</code>, <code>txId</code>, and <code>txIndex</code>, the function MUST compute the Merkle root.</li> <li>The computed Merkle root MUST be compared against the <code>Merkle Root</code> field stored within the block header identified by <code>blockHash</code>.</li> <li>If the computed Merkle root matches the stored <code>Merkle Root</code>, the function MUST return <code>true</code>. Otherwise, it MUST return <code>false</code>.</li> </ul> <h2 id="rationale">Rationale</h2> <p>During the design process of the <code>SPVGateway</code> contract, several decisions have been made that require clarification. The following initialization options of the smart contract were considered:</p> <ol> <li><strong>Hardcoding the Bitcoin genesis block:</strong> This approach is the simplest for contract deployment as it embeds the initial state directly in the code. While offering absolute trustlessness of the starting point, it limits availability, as the full sync of the gateway would cost around ~100 ETH at the gas price of 1 gwei.</li> <li><strong>Initialization from an arbitrary block height by trusting provided cumulative work and height:</strong> Currently, the gateway adopts this method as its initialization mechanism. While implying trust in the initial submitted values, it's a common practice for bootstrapping light clients and can be secured via off-chain mechanisms for initial validation (e.g., community-verified checkpoints).</li> <li><strong>Initialization with Zero-Knowledge Proof (ZKP) for historical correctness:</strong> This advanced method involves proving the entire history of Bitcoin up to a specific block using ZKP.</li> </ol> <p>Upon submitting the raw block header, the gateway expects the <code>BlockHeaderData</code> fields to be converted to big-endian byte order. This is required to maintain EVM's efficiency, which is contrary to Bitcoin's native little-endian integer serialization.</p> <p>There are no "finality" rules in the <code>SPVGateway</code> contract. The determination of such is left to consuming protocols, allowing individual definition to meet required security thresholds.</p> <p>The inclusion of an OPTIONAL <code>addBlockHeaderBatch</code> function offers significant gas optimizations. For batches exceeding 11 blocks, MTP can be calculated using timestamps from <code>calldata</code>, substantially reducing storage reads and transaction costs.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible.</p> <h3 id="deployment-method">Deployment Method</h3> <!-- TODO --> <p>TBD</p> <h2 id="test-cases">Test Cases</h2> <!-- TODO --> <p>TBD</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A reference implementation of the <code>SPVGateway</code> contract can be found <a href="https://wg-eips.ritovision.com/8002/./assets/contracts/SPVGateway.sol">here</a>.</p> <p><a href="https://wg-eips.ritovision.com/8002/./assets/contracts/libs/TargetsHelper.sol"><code>TargetsHelper</code></a> is a supporting library that provides utility functions for working with Bitcoin's difficulty targets. It includes methods to convert the <code>Bits</code> field from a block header to the corresponding <code>target</code> value and vice versa, as well as functions to calculate the new difficulty target during adjustment periods.</p> <blockquote> <p>Please note that the reference implementation depends on the <code>@openzeppelin/contracts v5.2.0</code>, <code>@solarity/solidity-lib v3.2.0</code> and <code>solady v0.1.23</code>.</p> </blockquote> <h2 id="security-considerations">Security Considerations</h2> <p>Among potential security issues, the following can be noted:</p> <p>The security of the <code>SPVGateway</code> is directly dependent on the security of Bitcoin's underlying PoW consensus. A successful 51% attack on the Bitcoin network would allow an attacker to submit fraudulent block headers that would be accepted by the contract, compromising its state.</p> <p>The block header validation rules require a Bitcoin node to check that the newly created block is not more than 2 hours ahead of the node's network-adjusted time. This check is impossible to implement on the <code>SPVGateway</code> smart contract, hence it is omitted.</p> <p>Unlike other blockchain systems with deterministic finality, Bitcoin's consensus is probabilistic. The <code>SPVGateway</code> contract SHOULD be designed to handle chain reorganizations of arbitrary depth, but it cannot prevent them. As a result, transactions included in a block may not be permanently final. All dApps and protocols relying on this contract MUST implement their own security policies to determine a sufficient number of block confirmations before a transaction is considered "final" for their specific use case.</p> <p>While the <code>addBlockHeader</code> function is permissionless and validates each new header cryptographically, the contract's initial state (its starting block header, height, and cumulative PoW) is a point of trust. The integrity of the entire chain history within the contract is built upon the correctness of this initial data. Although the EIP's design allows for flexible bootstrapping, the responsibility for verifying the initial state falls on the community and the dApps that choose to use a specific deployment of the <code>SPVGateway</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> 2025-08-04T00:00:00+00:00 2026-02-11T14:49:27+00:00 Anders Elowssonhttps://github.com/anderselowsson Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/7999/

Let transactions specify one aggregate `max_fee` budget for all resources, unify fee markets, normalize gas, and generalize EIP-7918.

<h2 id="abstract">Abstract</h2> <p>A unified multidimensional fee market is introduced, where each transaction specifies the maximum amount of ETH it is willing to pay for inclusion using a single <code>max_fee</code>. Upon inclusion, the protocol ensures that the transaction is able to pay the gas for all dimensions, treating the <code>max_fee</code> as fungible across resources. This enables a more efficient use of capital, and enshrines the same representation that users have when they interact with Ethereum. The fee market is further unified in terms of a single update fraction under a single fee update mechanism, generalized reserve pricing, and a gas normalization that retains current percentage ranges while keeping the price stable whenever a gas limit changes. Calldata is proposed as the first resource to be added, with avenues for facilitating gas fungibility for EVM resources considered for further expansion.</p> <h2 id="motivation">Motivation</h2> <p>A multidimensional fee market enables precise control over resource consumption. It allows <em>the market</em> to fairly price resources according to targets and limits deemed safe by developers, and it allows resources to be consumed at maximum capacity within these limits. Directly expanding the current fee market design to the multidimensional setting can however have negative effects on the user experience (UX) and on economic efficiency. Users are forced to set a <code>max_fee_per_gas</code> for each resource, where a too low allocation in any dimension can render the transaction ineligible.</p> <p>This EIP leverages the natural fungibility of the user's fee budget by letting users set a single unified <code>max_fee</code>. Instead of using non-fungible per-resource budgets, the single ETH budget can then be allocated dynamically to cover costs wherever they arise, ensuring a more efficient use of capital. Users will be able to specify a lower <code>max_fee</code> than the implied aggregate maximum unless all base fees are perfectly correlated (which reduces to the current design), because they do not need to buffer for spurious price movements in a single resource dimension.</p> <p>Ethereum's current fee market has "tech debt" in that two separate mechanisms are used: one for regular gas (<a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a>) and the other for blob gas (<a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>). The proposal unifies the fee market under the preferred EIP-4844 design. That design allows for exact control over long-run resource consumption. In a multidimensional setting with individual base fees, we can then for example achieve precise control over state growth, while accommodating temporary spikes. Excess gas of EIP-4844 is further normalized relative to the limit, allowing for a single update fraction across resources that retains current percentage ranges while keeping the price stable if any gas limit changes.</p> <p>Calldata is added first, to speed up worst-case payload propagation and expand available EVM gas—without compromising gas introspection. A method for facilitating gas aggregation across resources within the EVM is outlined as an avenue for preserving backward compatibility when expanding further. The logic of EIP-7918 is integrated into the multidimensional setting to ensure that calldata has a higher cost per byte than blob data.</p> <h2 id="specification">Specification</h2> <p>The specification inherits its logic from <a href="https://wg-eips.ritovision.com/7706/">EIP-7706</a>, incorporating the changes necessary for facilitating one aggregate fee, a multidimensional <a href="https://wg-eips.ritovision.com/7918/">EIP-7918</a> logic, a systematic approach to <a href="https://wg-eips.ritovision.com/7805/">EIP-7805</a>, and a stable gas normalization function, etc.</p> <h3 id="parameters">Parameters</h3> <table><thead><tr><th style="text-align: left">Constant</th><th style="text-align: left">Value</th><th style="text-align: left">Description</th></tr></thead><tbody> <tr><td style="text-align: left"><code>MULTIDIM_TX_TYPE</code></td><td style="text-align: left"><code>TBD</code> <!-- TODO --></td><td style="text-align: left">Identifier for the new transaction type</td></tr> <tr><td style="text-align: left"><code>EVM_LIMIT_TARGET_RATIO</code></td><td style="text-align: left"><code>2</code></td><td style="text-align: left">Ratio of EVM gas target to EVM gas limit</td></tr> <tr><td style="text-align: left"><code>CALLDATA_GAS_PER_TOKEN</code></td><td style="text-align: left"><code>4</code></td><td style="text-align: left">Gas cost per token for calldata</td></tr> <tr><td style="text-align: left"><code>TOKENS_PER_NONZERO_BYTE</code></td><td style="text-align: left"><code>4</code></td><td style="text-align: left">Tokens per non-zero byte of calldata</td></tr> <tr><td style="text-align: left"><code>CALLDATA_GAS_LIMIT_RATIO</code></td><td style="text-align: left"><code>4</code></td><td style="text-align: left">Ratio of calldata limit to gas limit</td></tr> <tr><td style="text-align: left"><code>CALLDATA_LIMIT_TARGET_RATIO</code></td><td style="text-align: left"><code>4</code></td><td style="text-align: left">Ratio of calldata target to calldata limit</td></tr> <tr><td style="text-align: left"><code>GAS_RESERVE_FACTOR</code></td><td style="text-align: left"><code>[0, 16, 12]</code></td><td style="text-align: left">Factor by which the base fee can be below the baseline</td></tr> <tr><td style="text-align: left"><code>GAS_RESERVE_INDEX</code></td><td style="text-align: left"><code>[0, 0, 1]</code></td><td style="text-align: left">Index of the base fee to compare against</td></tr> <tr><td style="text-align: left"><code>MIN_BASE_FEE_PER_GAS</code></td><td style="text-align: left"><code>1</code></td><td style="text-align: left">Minimum base fee per gas unit</td></tr> <tr><td style="text-align: left"><code>GAS_NORMALIZATION_FACTOR</code></td><td style="text-align: left"><code>10**9</code></td><td style="text-align: left">Normalization factor for the delta excess gas</td></tr> <tr><td style="text-align: left"><code>BASE_FEE_UPDATE_FRACTION</code></td><td style="text-align: left"><code>4_245_093_508</code></td><td style="text-align: left">≈ <code>GAS_NORMALIZATION_FACTOR / (2 * ln(1.125))</code></td></tr> </tbody></table> <h3 id="new-transaction-type">New transaction type</h3> <p>Upon activation of this EIP via hard fork, a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction is introduced with <code>TransactionType</code> = <code>MULTIDIM_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_fee, max_priority_fee_per_gas, y_parity, r, s]</span></span></code></pre> <p>We require <code>max_fee</code> to be a scalar integer from <code>0</code> to <code>2**128-1</code> and <code>max_priority_fee_per_gas</code> to be a list of integers from <code>0</code> to <code>2**64-1</code>, either of length 1 or with the same length as the number of resources (initially 3). The <code>gas_limit</code> is initially specified only for the main EVM gas, since other limits can be inferred from the transaction. To facilitate further expansion, the Python spec uses a list with a single element at index 0. Each added integer will range 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 non-zero byte, 4 per zero byte) is removed.</p> <h3 id="block-processing-and-transaction-fees">Block processing and transaction fees</h3> <p>Helpers for vector operations:</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"> all_less_or_equal</span><span>(</span><span class="z-variable z-parameter z-function">v1</span><span>:</span><span> [</span><span class="z-support">int</span><span>,</span><span class="z-support"> int</span><span>,</span><span class="z-support"> int</span><span>]</span><span>,</span><span class="z-variable z-parameter z-function"> v2</span><span>:</span><span> [</span><span class="z-support">int</span><span>,</span><span class="z-support"> int</span><span>,</span><span class="z-support"> int</span><span>]</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 class="z-support"> all</span><span>(</span><span>x</span><span class="z-keyword"> &lt;=</span><span> y</span><span class="z-keyword"> for</span><span> x</span><span>,</span><span> y</span><span class="z-keyword"> in</span><span class="z-support"> zip</span><span>(</span><span>v1</span><span>,</span><span> v2</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"> vector_add</span><span>(</span><span class="z-variable z-parameter z-function">v1</span><span>:</span><span> [</span><span class="z-support">int</span><span>,</span><span class="z-support"> int</span><span>,</span><span class="z-support"> int</span><span>]</span><span>,</span><span class="z-variable z-parameter z-function"> v2</span><span>:</span><span> [</span><span class="z-support">int</span><span>,</span><span class="z-support"> int</span><span>,</span><span class="z-support"> int</span><span>]</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 class="z-support"> int</span><span>]</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 class="z-keyword"> for</span><span> x</span><span>,</span><span> y</span><span class="z-keyword"> in</span><span class="z-support"> zip</span><span>(</span><span>v1</span><span>,</span><span> v2</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"> vector_mul</span><span>(</span><span class="z-variable z-parameter z-function">v1</span><span>:</span><span> [</span><span class="z-support">int</span><span>,</span><span class="z-support"> int</span><span>,</span><span class="z-support"> int</span><span>]</span><span>,</span><span class="z-variable z-parameter z-function"> v2</span><span>:</span><span> [</span><span class="z-support">int</span><span>,</span><span class="z-support"> int</span><span>,</span><span class="z-support"> int</span><span>]</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 class="z-support"> int</span><span>]</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 class="z-keyword"> for</span><span> x</span><span>,</span><span> y</span><span class="z-keyword"> in</span><span class="z-support"> zip</span><span>(</span><span>v1</span><span>,</span><span> v2</span><span>)</span><span>]</span></span></code></pre> <p>Helper functions for computing scalar max fees/priority fees for all transaction types:</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_max_fee</span><span>(</span><span class="z-variable z-parameter z-function">tx</span><span>:</span><span> Transaction</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> tx</span><span>.</span><span>type</span><span class="z-keyword"> ==</span><span class="z-constant"> MULTIDIM_TX_TYPE</span><span>:</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> New tx type already has a max_fee</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> tx</span><span>.</span><span>max_fee</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> tx</span><span>.</span><span>type</span><span class="z-keyword"> ==</span><span class="z-constant"> BLOB_TX_TYPE</span><span>:</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Account for blobs in blob txs</span></span> <span class="giallo-l"><span> blob_gas</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span>tx</span><span>.</span><span>blob_versioned_hashes</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> GAS_PER_BLOB</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> tx</span><span>.</span><span>max_fee_per_gas</span><span class="z-keyword">*</span><span>tx</span><span>.</span><span>gas_limit</span><span class="z-keyword"> +</span><span> tx</span><span>.</span><span>max_fee_per_blob_gas</span><span class="z-keyword">*</span><span>blob_gas</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> is_eip_1559</span><span>(</span><span>tx</span><span>.</span><span>type</span><span>)</span><span>:</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> EIP-1559 txs have no blobs</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> tx</span><span>.</span><span>max_fee_per_gas</span><span class="z-keyword"> *</span><span> tx</span><span>.</span><span>gas_limit</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"> Legacy transactions have a gasprice</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> tx</span><span>.</span><span>gasprice</span><span class="z-keyword"> *</span><span> tx</span><span>.</span><span>gas_limit</span></span></code></pre><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_priority_fee</span><span>(</span><span class="z-variable z-parameter z-function">tx</span><span>,</span><span class="z-variable z-parameter z-function"> gas</span><span>:</span><span> list</span><span>[</span><span class="z-support">int</span><span>]</span><span>,</span><span class="z-variable z-parameter z-function"> base_fees</span><span>:</span><span> list</span><span>[</span><span class="z-support">int</span><span>]</span><span>,</span><span class="z-variable z-parameter z-function"> remaining_fee</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"> Precalculate total gas and fees for non-blob resources</span></span> <span class="giallo-l"><span> tip_indices</span><span class="z-keyword"> =</span><span> [</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 2</span><span>]</span></span> <span class="giallo-l"><span> tgas</span><span class="z-keyword"> =</span><span class="z-support"> sum</span><span>(</span><span>gas</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span> tip_indices</span><span>)</span></span> <span class="giallo-l"><span> tfee</span><span class="z-keyword"> =</span><span class="z-support"> sum</span><span>(</span><span>gas</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> *</span><span> base_fees</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span> tip_indices</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> tx</span><span>.</span><span>type</span><span class="z-keyword"> ==</span><span class="z-constant"> MULTIDIM_TX_TYPE</span><span>:</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> New tx type: Single tip or full vector of tips</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>tx</span><span>.</span><span>max_priority_fee_per_gas</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 1</span><span>:</span></span> <span class="giallo-l"><span> tmax_fee</span><span class="z-keyword"> =</span><span> tx</span><span>.</span><span>max_fee</span><span class="z-keyword"> -</span><span> gas</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> *</span><span> base_fees</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Ignore blobs (as now)</span></span> <span class="giallo-l"><span> tpriority_fee</span><span class="z-keyword"> =</span><span> tmax_fee</span><span class="z-keyword"> -</span><span> tfee</span><span class="z-keyword"> if</span><span> tmax_fee</span><span class="z-keyword"> &gt;</span><span> tfee</span><span class="z-keyword"> else</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> max_priority_fee</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span>tx</span><span>.</span><span>max_priority_fee_per_gas</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> *</span><span> tgas</span><span>,</span><span> tpriority_fee</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> max_priority_fee</span><span class="z-keyword"> =</span><span class="z-support"> sum</span><span>(</span><span>vector_mul</span><span>(</span><span>tx</span><span>.</span><span>max_priority_fee_per_gas</span><span>,</span><span> gas</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> min</span><span>(</span><span>max_priority_fee</span><span>,</span><span> remaining_fee</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> is_legacy</span><span>(</span><span>tx</span><span>.</span><span>type</span><span>)</span><span>:</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Legacy tx: The remainder after base fees paid</span></span> <span class="giallo-l"><span> tmax_fee</span><span class="z-keyword"> =</span><span> tx</span><span>.</span><span>gasprice</span><span class="z-keyword"> *</span><span> tgas</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> tmax_fee</span><span class="z-keyword"> -</span><span> tfee</span><span class="z-keyword"> if</span><span> tmax_fee</span><span class="z-keyword"> &gt;</span><span> tfee</span><span class="z-keyword"> else</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> EIP-1559 or Blob tx</span></span> <span class="giallo-l"><span> tmax_fee</span><span class="z-keyword"> =</span><span> tx</span><span>.</span><span>max_fee_per_gas</span><span class="z-keyword"> *</span><span> tgas</span></span> <span class="giallo-l"><span> tpriority_fee</span><span class="z-keyword"> =</span><span> tmax_fee</span><span class="z-keyword"> -</span><span> tfee</span><span class="z-keyword"> if</span><span> tmax_fee</span><span class="z-keyword"> &gt;</span><span> tfee</span><span class="z-keyword"> else</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> max_priority_fee</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span>tx</span><span>.</span><span>max_priority_fee_per_gas</span><span class="z-keyword"> *</span><span> tgas</span><span>,</span><span> tpriority_fee</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> tx</span><span>.</span><span>type</span><span class="z-keyword"> ==</span><span class="z-constant"> BLOB_TX_TYPE</span><span>:</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Clamp since blobs reduce the shared max_fee budget</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> min</span><span>(</span><span>max_priority_fee</span><span>,</span><span> remaining_fee</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> max_priority_fee</span></span></code></pre> <p>The calldata resource pricing under this EIP follows previous gas per byte constants but deprecates the floor pricing specified in <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</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"> get_calldata_gas</span><span>(</span><span class="z-variable z-parameter z-function">calldata</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> tokens</span><span class="z-keyword"> =</span><span> calldata</span><span>.</span><span>count</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword"> +</span><span> (</span><span class="z-support">len</span><span>(</span><span>calldata</span><span>)</span><span class="z-keyword"> -</span><span> calldata</span><span>.</span><span>count</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> TOKENS_PER_NONZERO_BYTE</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> tokens</span><span class="z-keyword"> *</span><span class="z-constant"> CALLDATA_GAS_PER_TOKEN</span></span></code></pre> <p>The helper for calculating gas limits from EIP-7706 is adjusted to subtract calldata gas from the gas limit of old transactions:</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_gas_limits</span><span>(</span><span class="z-variable z-parameter z-function">tx</span><span>:</span><span> Transaction</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> calldata_gas</span><span class="z-keyword"> =</span><span> get_calldata_gas</span><span>(</span><span>tx</span><span>.</span><span>data</span><span>)</span></span> <span class="giallo-l"><span> blob_gas</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span class="z-support">getattr</span><span>(</span><span>tx</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">blob_versioned_hashes</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> [</span><span>]</span><span>)</span><span>)</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> tx</span><span>.</span><span>type</span><span class="z-keyword"> ==</span><span class="z-constant"> MULTIDIM_TX_TYPE</span><span>:</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> We use tx.gas_limit as is for new tx type</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> [</span><span>tx</span><span>.</span><span>gas_limit</span><span>,</span><span> blob_gas</span><span>,</span><span> calldata_gas</span><span>]</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"> Partition old tx.gas_limit into its execution and calldata components.</span></span> <span class="giallo-l"><span> require</span><span>(</span><span>tx</span><span>.</span><span>gas_limit</span><span class="z-keyword"> &gt;=</span><span> calldata_gas</span><span>)</span><span> </span></span> <span class="giallo-l"><span> execution_gas</span><span class="z-keyword"> =</span><span> tx</span><span>.</span><span>gas_limit</span><span class="z-keyword"> -</span><span> calldata_gas</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> [</span><span>execution_gas</span><span>,</span><span> blob_gas</span><span>,</span><span> calldata_gas</span><span>]</span></span></code></pre> <p>The calculation for the <em>required</em> <code>max_fee</code> to process the transaction is done in a separate function for easy future expansion:</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_required_max_fee</span><span>(</span><span class="z-variable z-parameter z-function">base_fees</span><span>:</span><span> list</span><span>[</span><span class="z-support">int</span><span>]</span><span>,</span><span class="z-variable z-parameter z-function"> tx_gas_limits</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>vector_mul</span><span>(</span><span>base_fees</span><span>,</span><span> tx_gas_limits</span><span>)</span><span>)</span></span></code></pre> <p><strong>At the start of processing a block</strong>:</p> <ul> <li>initialize a vector <code>gas_used_so_far</code> to <code>[0, 0, 0]</code>,</li> <li>derive the base fee <code>base_fees = get_block_base_fees(block.parent)</code>.</li> </ul> <p><strong>At the start of processing a transaction</strong>:</p> <ul> <li>Derive basic properties of the tx: <ul> <li><code>max_fee = get_max_fee(tx)</code>,</li> <li><code>tx_gas_limits = get_gas_limits(tx)</code>.</li> <li><code>max_base = get_required_max_fee(base_fees, tx_gas_limits)</code></li> </ul> </li> <li>Require that <ul> <li><code>all_less_or_equal(vector_add(gas_used_so_far, tx_gas_limits), gas_limits)</code>. The block's <code>gas_limits</code> are defined in the next subsection.</li> <li><code>max_base &lt;= max_fee</code></li> </ul> </li> <li>Compute the fees to deduct initially: <ul> <li><code>max_priority_fee = get_priority_fee(tx, tx_gas_limits, base_fees, max_fee - max_base)</code></li> <li><code>fee_to_deduct = max_base + max_priority_fee</code></li> </ul> </li> <li>Deduct <code>fee_to_deduct</code> wei from the sender, which we define as the address recovered from the transaction’s signature.</li> </ul> <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 execution gas actually consumed, and the second and third items are the blob and calldata gas amounts, which are equal to their limits from <code>tx_gas_limits</code>.</li> <li>Burn <code>base_fee_paid = sum(vector_mul(base_fees, tx_gas_consumed))</code>.</li> <li>Transfer to the coinbase <code>priority_fee_paid = get_priority_fee(tx, tx_gas_consumed, base_fees, fee_to_deduct - base_fee_paid)</code></li> <li>Refund the sender <code>fee_to_deduct - base_fee_paid - priority_fee_paid</code>.</li> <li>Update <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 each element of <code>block.gas_used</code> (a vector field in the header) to equal the corresponding element in <code>gas_used_so_far</code>.</li> </ul> <h3 id="block-structure">Block structure</h3> <p>The <code>BlockHeader</code> is updated 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 the following new fields are added, all of the <code>[int, int, int]</code> type: <code>gas_limits</code>, <code>gas_used</code>, <code>excess_gas</code>. The header sequence of the new fields is <code>[..., withdrawals_root, gas_limits, gas_used, excess_gas]</code>.</p> <p>We define the <code>gas_limits</code></p> <ul> <li><code>gas_limits[0]</code> follows the existing adjustment formula based on the parent <code>gas_limits[0]</code>.</li> <li><code>gas_limits[1]</code> must equal <code>blobSchedule.max * GAS_PER_BLOB</code></li> <li><code>gas_limits[2]</code> must equal <code>gas_limits[0] // CALLDATA_GAS_LIMIT_RATIO</code>.</li> </ul> <p>and the <code>gas_targets</code></p> <ul> <li><code>gas_targets[0]</code> must equal <code>gas_limits[0] // EVM_LIMIT_TARGET_RATIO</code>.</li> <li><code>gas_targets[1]</code> must equal <code>blobSchedule.target * GAS_PER_BLOB</code>.</li> <li><code>gas_targets[2]</code> must equal <code>gas_limits[2] // CALLDATA_LIMIT_TARGET_RATIO</code>.</li> </ul> <p>The blobSchedule for referencing target and max blobs was introduced in <a href="https://wg-eips.ritovision.com/7840/">EIP-7840</a>.</p> <h3 id="gas-accounting">Gas accounting</h3> <p>We incorporate EIP-7918 to establish a dynamic reserve price for blob and calldata gas. When the market price for a resource drops below its reserve price, the mechanism for reducing its <code>excess_gas</code> (and thus lowering its base fee) is disabled. This leads the base fee to rise with usage until it meets the reserve price.</p> <p>We normalize the running excess gas so that all resources operate at the same scale with the same <code>BASE_FEE_UPDATE_FRACTION</code>, which also provides a smoother response when any limit is adjusted. Division by <code>gas_limits[i]</code> upholds the same price changes stipulated in EIP-4844 and <a href="https://wg-eips.ritovision.com/7691/">EIP-7691</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"> calc_excess_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> list</span><span>[</span><span class="z-support">int</span><span>]</span><span>:</span></span> <span class="giallo-l"><span> base_fees</span><span class="z-keyword"> =</span><span> get_block_base_fees</span><span>(</span><span>parent</span><span>)</span></span> <span class="giallo-l"><span> limits</span><span class="z-keyword"> =</span><span> parent</span><span>.</span><span>gas_limits</span></span> <span class="giallo-l"><span> targets</span><span class="z-keyword"> =</span><span> get_block_gas_targets</span><span>(</span><span>parent</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> new_excess</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span class="z-support">len</span><span>(</span><span>parent</span><span>.</span><span>excess_gas</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-constant">GAS_RESERVE_FACTOR</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> base_fees</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> *</span><span class="z-constant"> GAS_RESERVE_FACTOR</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> &lt;</span><span> base_fees</span><span>[</span><span class="z-constant">GAS_RESERVE_INDEX</span><span>[</span><span>i</span><span>]</span><span>]</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"> EIP-7918 path. Excess gas rises with usage (up to limit), but cannot fall.</span></span> <span class="giallo-l"><span> delta</span><span class="z-keyword"> =</span><span> parent</span><span>.</span><span>gas_used</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> *</span><span> (</span><span>limits</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> -</span><span> targets</span><span>[</span><span>i</span><span>]</span><span>)</span><span class="z-keyword"> //</span><span> limits</span><span>[</span><span>i</span><span>]</span></span> <span class="giallo-l"><span> excess</span><span class="z-keyword"> =</span><span> parent</span><span>.</span><span>excess_gas</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> +</span><span> delta</span><span class="z-keyword"> *</span><span class="z-constant"> GAS_NORMALIZATION_FACTOR</span><span class="z-keyword"> //</span><span> limits</span><span>[</span><span>i</span><span>]</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"> Regular path. Excess gas rises and falls with usage as normal</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> parent</span><span>.</span><span>gas_used</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> &gt;=</span><span> targets</span><span>[</span><span>i</span><span>]</span><span>:</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Add</span></span> <span class="giallo-l"><span> delta</span><span class="z-keyword"> =</span><span> parent</span><span>.</span><span>gas_used</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> -</span><span> targets</span><span>[</span><span>i</span><span>]</span></span> <span class="giallo-l"><span> excess</span><span class="z-keyword"> =</span><span> parent</span><span>.</span><span>excess_gas</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> +</span><span> delta</span><span class="z-keyword"> *</span><span class="z-constant"> GAS_NORMALIZATION_FACTOR</span><span class="z-keyword"> //</span><span> limits</span><span>[</span><span>i</span><span>]</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"> ..or subtract</span></span> <span class="giallo-l"><span> delta</span><span class="z-keyword"> =</span><span> targets</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> -</span><span> parent</span><span>.</span><span>gas_used</span><span>[</span><span>i</span><span>]</span></span> <span class="giallo-l"><span> deltan</span><span class="z-keyword"> =</span><span> delta</span><span class="z-keyword"> *</span><span class="z-constant"> GAS_NORMALIZATION_FACTOR</span><span class="z-keyword"> //</span><span> limits</span><span>[</span><span>i</span><span>]</span></span> <span class="giallo-l"><span> excess</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span><span class="z-keyword"> if</span><span> parent</span><span>.</span><span>excess_gas</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> &lt;</span><span> deltan</span><span class="z-keyword"> else</span><span> parent</span><span>.</span><span>excess_gas</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> -</span><span> deltan</span></span> <span class="giallo-l"><span> new_excess</span><span>.</span><span>append</span><span>(</span><span>excess</span><span>)</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> new_excess</span></span></code></pre><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_block_base_fees</span><span>(</span><span class="z-variable z-parameter z-function">parent</span><span>:</span><span> Header</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 class="z-keyword"> return</span><span> [</span></span> <span class="giallo-l"><span> fake_exponential</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> MIN_BASE_FEE_PER_GAS</span><span>,</span></span> <span class="giallo-l"><span> excess</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> BASE_FEE_UPDATE_FRACTION</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> excess</span><span class="z-keyword"> in</span><span> parent</span><span>.</span><span>excess_gas</span></span> <span class="giallo-l"><span> ]</span></span></code></pre><h3 id="calldatabasefee-instruction">CALLDATABASEFEE instruction</h3> <p>We add a <code>CALLDATABASEFEE (0x4b)</code> instruction that returns the calldata base fee of the current block, following the same principles as specified in <a href="https://wg-eips.ritovision.com/7516/">EIP-7516</a> for the blob base fee.</p> <table><thead><tr><th>Op</th><th>Input</th><th>Output</th><th>Cost</th></tr></thead><tbody> <tr><td>0x4b</td><td>0</td><td>1</td><td>2</td></tr> </tbody></table> <h3 id="censorship-resistance">Censorship resistance</h3> <p>In EIP-7805, <em>includers</em> propose inclusion-list (IL) transactions that the block builder must include, subject to rules evaluated post-execution once remaining capacity is known. We define three resource types based on these rules:</p> <ul> <li><em>Conditional resource</em> – An IL transaction consuming this resource <em>must be included</em> if the block has sufficient remaining capacity. If such a transaction is excluded, the block should not be accepted, unless the available space (<code>gas_limit[i] - gas_used[i]</code>) for at least one of its required conditional resources was insufficient to fit the transaction.</li> <li><em>Unconditional resource</em> – An IL transaction consuming this resource <em>must be included</em> as long as sufficient capacity remains for all <em>conditional</em> resources it also uses. A lack of available capacity in the unconditional resource itself is <em>not</em> a valid reason for exclusion.</li> <li><em>Deconditional resource</em> – An IL transaction consuming this resource <em>can always be excluded</em>, regardless of available capacity. For this reason, there is no incentive for includers to list such a transaction.</li> </ul> <p>If EIP-7805 is implemented, it must: (i) continue to treat EVM gas as a conditional resource; (ii) continue to treat blob gas as a deconditional resource; (iii) treat calldata gas as an unconditional resource. Any transaction listed in an IL that consumes calldata and is excluded from the block, despite there being sufficient capacity in all conditional resources it uses, MUST produce an <code>INVALID_INCLUSION_LIST</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-go-multidimensional">Why go multidimensional?</h3> <p>Many Ethereum resources such as blobs, calldata, access, and compute are in limited supply each block, constrained by the need to, e.g., timely propagate data or run computations. Upholding the constraints on all these resources via a single meta-resource—"gas"—limits developers' ability to control both supply <em>and</em> demand. By going multidimensional, developers gain a more fine-grained control over the supply of each resource, preventing one from encroaching on the allotment for another. Resources can then be consumed at maximum capacity within each specified target and limit. With separate base fees for each resource, the market can come to an agreement on the appropriate price that leads to consumption at maximum capacity, given a specific user demand and aforementioned constraints on its supply. A multidimensional fee market is thus inherently a tool for scaling Ethereum.</p> <h3 id="user-experience">User experience</h3> <p>Ethereum currently uses <code>max_fee_per_gas</code> for EVM gas and <code>max_fee_per_blob_gas</code> for blob gas. A direct expansion of this approach is proposed in EIP-7706, with a vector of fees per gas for each resource. This may be considered unfortunate from a UX perspective, given that the vector will expand with expanding dimensionality. Our casual users tend to be moderately confused already by a single <code>max_fee_per_gas</code>. Most do not primarily think in terms of the individual prices for the resources that the transaction will consume. They think in terms of how much ETH they need to pay for their transactions (or in terms of dollars/fiat). A unified <code>max_fee</code> is in this context an improvement to UX. A unified <code>max_fee_per_gas</code> is possible, but might cause confusion in that the required gas price will differ from the base fees when using several resources—and thus also differ between transactions using different proportions of the resources.</p> <p>When it comes to the priority fee, the optimal UX between using <code>max_priority_fee</code> and <code>max_priority_fee_per_gas</code> is a bit more nuanced. We decided to use <code>max_priority_fee_per_gas</code>. Ethereum already today unifies the priority fee for blob gas and regular gas under a single <code>max_priority_fee_per_gas</code>. It is thus natural to retain this representation, if only for removing friction for wallets. Furthermore, the priority fee should be determined from actual gas usage and not the gas limit. This is however perfectly possible when using <code>max_priority_fee</code> as well, because the max priority fee can be treated as proportional to the limit during processing, thus falling if less gas is consumed.</p> <p>Retaining <code>max_priority_fee_per_gas</code> can be considered slightly safer for users, in that they will never risk manually submitting a <code>max_priority_fee</code> for an old transaction type. Advanced users may wish to specify one priority fee per resource, to granularly pay according to usage when consuming below the gas limit. This ability was therefore preserved as an optional vector-based priority fee.</p> <h3 id="economic-efficiency">Economic efficiency</h3> <p>Besides UX, resource-specific fee limits can also be unfortunate at a deeper economic level. Once a user has specified a <code>gas_limit</code> for any non-deterministic dimension, potentially with the assistance of their wallets, multiple separate <code>max_fee_per_gas</code> could exclude transactions that specify a sufficient aggregate fee, due to a drift in relative levels of the base fees.</p> <p>Consider a multidimensional transaction with a <code>gas_limit</code> vector $\mathbf{l} = (l_1, l_2,\dots, l_n)$, a <code>max_fee_per_gas</code> vector $\mathbf{f} = (f_1, f_2, \dots, f_n)$, and a <code>max_priority_fee_per_gas</code> vector $\mathbf{p} = (p_1, p_2, \dots, p_n)$. The consumed gas of the transaction is denoted $\mathbf{g} = (g_1, g_2, \dots, g_n)$, and the vector of base fees is denoted $\mathbf{b} = (b_1, b_2, \dots, b_n)$. The realized priority fee, after ensuring a sufficient base fee, is then</p> <p>$p{\prime}_i = \min(p_i, f_i-b_i)$</p> <p>for all resources $i$. Assume that when the transaction is submitted, the user specifies a <code>max_fee_per_gas</code> vector $\mathbf{f}$ such that all entries individually satisfy all base fee $\mathbf{b}$ criteria</p> <p>$f_i \ge b_i \quad \text{for all resources } i.$</p> <p>The gas limits also satisfy the actual gas consumption</p> <p>$l_i \ge g_i \quad \text{for all resources } i.$</p> <p>The <code>max_priority_fee_per_gas</code> vector $\mathbf{p}$ is also considered sufficient by many proposers, when they jointly weigh the reward against competing transactions using a weight vector $\mathbf{w}$, considering contention across relevant resources:</p> <p>$\sum p{\prime}_i g_i \ge \sum w_i g_i.$</p> <p>While not evaluated in the existing EIP, the base fees $\mathbf{b}$ could also be satisfied in aggregate against the max fees:</p> <p>$\sum f_i l_i \ge \sum b_i l_i.$</p> <p>Now assume that the base fee for any of the resources rapidly rises before the transaction is included, such that it becomes higher than the <code>max_fee_per_gas</code> in that dimension. In this scenario, the transaction can no longer be included. This may happen, even though the <em>aggregate</em> fees that the user is offering to pay, $\sum f_i l_i$, remain at a level above the aggregate fees that the protocol demands to execute it, $\sum b_i l_i$, just as initially. The aggregate priority fees may still also satisfy the proposer. The welfare loss consists of a user, a proposer, and a protocol willing to process a transaction, hamstrung by rigidity in the protocol design.</p> <p>The analysis leads to the following conclusions, all of which apply with increasing emphasis the higher the dimensionality:</p> <ol> <li>The UX would be simplified by one aggregate ETH fee.</li> <li>The protocol would be best served by taking a single aggregate ETH fee from the user.</li> <li>The proposer already considers the aggregate impact when making its inclusion decision.</li> </ol> <p>Thus, the proposal is that the user specifies a single ETH <code>max_fee</code>. The protocol first ensures that the <code>max_fee</code> $F$ covers the base fee across gas limits in all dimensions, $F &gt; \sum b_i l_i$, and finally charges the minimum aggregate fee possible. The total fee paid to the protocol is thus the same as in the original multidimensional fee market design. The design is future-proof in that additional dimensions easily are incorporated, retaining the single <code>max_fee</code>.</p> <h3 id="priority-fee">Priority fee</h3> <p>Considerations for the priority fee were already outlined in the UX section. Here, we first expand on why a vector <code>max_priority_fee_per_gas</code> <em>can</em> be beneficial to some users for fine-grained control, but not to most. The user has full control over the priority fee with a single input, as long as gas usage is deterministic across all resources. This input can be either <code>max_priority_fee</code> or <code>max_priority_fee_per_gas</code>—they are equivalent under deterministic gas usage. They are furthermore equivalent under any circumstances if the protocol makes sure to scale the <code>max_priority_fee</code> according to realized gas usage <em>relative</em> to the specified limit. Otherwise, the <code>max_priority_fee</code> will not be reduced when a transaction uses less gas than the limit (this is more often a drawback than a benefit for the user).</p> <p>The priority fee a user wishes to provide per gas for a resource depends on the (likelihood of) contention across this resource. We can thus expect it to differ between resources. It follows from the principle of degrees of freedom that to gain full control over the transaction's priority fee, a user needs a separate parameter for each independent variable. When gas usage is non-deterministic in one resource—as today—the user needs two priority fees to achieve full granularity. When gas usage is non-deterministic in two resources (and their non-deterministic usage is not perfectly correlated), the user needs three priority fees, etc.</p> <p>It should here be noted that the required priority fee per gas for some resource cannot be directly ascertained from the priority fee per gas that has been stipulated for that resource in recent transactions. Assume that there are 10 resource and each transaction includes a vector stipulating <code>max_priority_fee_per_gas</code> for each. The builder will in its inclusion decision operate on the aggregate, and its requirements across dimensions can thus only be inferred, not observed directly. This means that per-resource estimates of required priority fees are not trivial, and most may still prefer the simplicity of a single one.</p> <h3 id="unified-gas-accounting-normalization-and-reserve-pricing-mechanism">Unified gas accounting, normalization, and reserve pricing mechanism</h3> <p>Ethereum currently uses two separate fee mechanisms, one for execution gas (EIP-1559) and one for blob gas (EIP-4844). This EIP unifies these mechanisms under the EIP-4844 standard, similar to EIP-7706 but with a few additions. We normalize the excess gas delta by dividing by the gas limit in <code>calc_excess_gas</code>, thus enabling all resources to operate under the same <code>BASE_FEE_UPDATE_FRACTION</code> while also keeping each fee fixed during a hard fork whenever a limit changes.</p> <p>The reserve pricing mechanism from EIP-7918 is also generalized such that it can be applied to any resource, using another resource as an anchor. The mechanism imposes that if the base fee multiplied by <code>GAS_RESERVE_FACTOR</code> is less than the anchor base fee, the base fee cannot fall any further. Calldata uses blob data as an anchor to ensure that we do not charge less for calldata than blob data (see the separate section on the calldata resource for further details).</p> <h3 id="wallet-fee-estimation-logic">Wallet fee estimation logic</h3> <p>To suggest a <code>max_fee</code>, the wallet first simulates the transaction to obtain an estimate of the required limit(s) $\mathbf{l}$. It then queries the network for the current vector of base fees $\mathbf{b}$. The expected total fee is $\sum b_i l_i$. The wallet recommends a <code>max_fee</code> that consists of this expected total cost plus a single buffer to account for aggregate volatility in base fees before the transaction is included. To suggest a <code>max_priority_fee_per_gas</code>, the wallet analyzes recent blocks to determine the priority fees that ensure timely inclusion. It focuses on priority fees paid by recently included transactions consuming a similar distribution of resources, as well as overall network contention.</p> <h3 id="block-building">Block building</h3> <p>Historical data show that around 90% of blocks are below the gas limit. It is only when blocks are full that the builder is constrained in its block construction (disregarding timing games). Furthermore, a multidimensional knapsack problem only manifests in the event that a block is simultaneously full in multiple dimensions. Ignoring blobs, this is expected to be rare with the proposal, since calldata is assigned a limit four times above the target, which is already set higher than current consumption. The calldata limit is thus unlikely to be reached frequently. The blob dimension is a special case, in that this dimension already exists today, and the number of blob-carrying transactions is fairly low. Generally, the impact on revenue from sophisticated packing algorithms will likely be dwarfed by more significant MEV factors such as transaction ordering and private order flow.</p> <h3 id="the-calldata-resource">The calldata resource</h3> <h4 id="byte-sizes">Byte sizes</h4> <p>Calldata is separated into its own resource. With the proposed constants, at 60M execution gas, each block will on average contain <code>60M/(CALLDATA_GAS_LIMIT_RATIO * CALLDATA_LIMIT_TARGET_RATIO) = 3.75M</code> gas of calldata. Focusing on non-zero bytes that cannot be Snappy-compressed, this gas corresponds to around <code>3.75M/16 = 234kB</code>. The average block size has been around <code>90kB</code> at a 36M gas limit, which would expand to <code>150kB</code> at a 60M gas limit if the proportion of calldata in the block remains the same. Using basic assumptions, this proposal thus increases the amount of calldata that will be consumed by over 50%, from <code>150kB</code> to <code>234kB</code> at 60M gas. As pointed out in EIP-7706, this will serve to decrease the cost of calldata for our users.</p> <p>The limit is <code>60M/CALLDATA_GAS_LIMIT_RATIO = 15M</code> gas of calldata, corresponding to around <code>15M/16 = 938kB</code>. This is well below the limit under the current specification incorporating EIP‑7623, which is <code>60M/40 = 1.5MB</code> at 60M gas. Since calldata gas is also no longer accounted for as execution gas, the implied "aggregate" gas limit expands to <code>75M</code> gas, without materially affecting the maximum workload in terms of execution. In conclusion, the separation of calldata into its own resource increases calldata throughput while reducing costs. It furthermore facilitates scaling by allowing for faster payload propagation in the worst case and keeping all EVM gas available for other operations.</p> <h4 id="censorship-resistance-1">Censorship resistance</h4> <p>For censorship resistance (CR) purposes, under the currently proposed CR implementation EIP-7805, builders must include all transactions surfaced in any of the <code>16</code> inclusion lists (ILs) of each slot (each up to <code>8KiB</code>). However, if the block is full, builders can ignore the ILs, to not incentivize them to influence includers for MEV purposes.</p> <p>When resources have separate limits, the block is treated as "full" already when any single conditional resource reaches its limit. Transactions that use that resource can then be excluded, even if they were surfaced by an IL. This makes it potentially cheaper to "stuff the block" to censor transactions. Specifically, a builder can create dummy transactions consuming a single resource to fill that dimension, ensuring that the block is treated as "full" when evaluating IL transactions. When resources have separate base fees, the builder may target a resource with a lower base fee, at a cost of roughly $b_i \cdot \Delta g_i$, where $\Delta g_i$ is the additional gas in resource $i$ required to reach its limit.</p> <p>The good news is that calldata has properties allowing the builder to extract MEV while at the same time unconditionally adhering to its gas limit under EIP-7805. This means that this EIP does not impede censorship resistance. Specifically, in the case where all ILs are filled with disjoint transactions, the aggregate size of included transactions can still be at most <code>8KiB*16 = 131kB</code>. This leaves at the very minimum <code>938kB - 131kB = 807kB</code> of calldata for the builder to use as it sees fit when extracting MEV, which is sufficient according to the usage patterns we know.</p> <p>Accordingly, calldata is treated as an "unconditional" resource, as defined in the specification. An includer MUST therefore signal <code>INVALID_INCLUSION_LIST</code> if—and only if—a calldata‑using IL transaction is omitted despite sufficient capacity remaining in all conditional resources it uses. When considering expansion into further resources with tighter conditional limits, it may be necessary to adopt a version of FOCIL with ranked transactions (FOCILR).</p> <h4 id="reserve-price">Reserve price</h4> <p>An EIP-7918 reserve price is used for calldata just as for blobs. This ensures that the equilibrium price does not fall to levels where the fee market update mechanism stops working satisfactorily. Furthermore, the expiry window for blobs is much shorter than the planned rolling expiry window for calldata, making a modest relative reserve price motivated from a resource preservation perspective. Finally, without a reserve price on calldata, it could become cheaper than blob data (particularly below the blob reserve price), and thus a rational choice for L2s.</p> <p>The latter rationale also motivates the specific parameterization chosen. The EIP-7918 reserve price per byte for calldata is set 1/3 above the price per byte for blob data. This is achieved by tying the EIP-7918 if clause to the <em>blob base fee</em>. The gas per byte is 16 for calldata and 1 for blob data, and the price floor is triggered when <code>base_fees[1] &gt; GAS_RESERVE_FACTOR[2] * base_fees[2]</code>. Given <code>GAS_RESERVE_FACTOR[2] = 12</code>, the EIP-7918 condition activates when the blob base fee is more than <code>12</code> times higher than the calldata base fee, at which point calldata costs less than <code>16/12 = 1+1/3</code> of the blob price per byte. The calldata base fee is then imposed to not fall further.</p> <h4 id="relationship-to-previous-eips-and-other-resources">Relationship to previous EIPs and other resources</h4> <p>We acknowledge that calldata already has been limited by EIP-7623, with further repricings proposed in <a href="https://wg-eips.ritovision.com/7976/">EIP-7976</a>. These EIPs limit worst-case block sizes by metering and conditionally pricing calldata at the transaction level as opposed to at the block level, having the calldata price vary with a transaction's execution usage. This may lead to secondary markets if users wish to combine different transactions to take advantage of the "rebate" on calldata when consumed together with EVM gas. Treating calldata as a separate resource with a price based on block usage would allow for a more precise control over usage, and transactors would not need to interact with a secondary market to achieve the best price.</p> <p>Given that the EIP-7623 design already achieves calldata moderation, it must be remembered that an individual fee market for calldata would merely be a first step toward a multidimensional fee market. Calldata is not an endgame. It is likely best to transition over several hard forks, and the options available at the present must then be considered, which leads to a focus on calldata. Another present consideration is block level access lists (BALs) and their interaction.</p> <p>A resource such as state is more attractive to separate than calldata. We could achieve exact control over state growth, while allowing temporary spikes many times above current gas limits. However, an expansion into other resources requires a multidimensional gas repricing, which has currently not yet been completed. The next section will further discuss remaining complexities of multidimensional EVM gas, and the strategies available for overcoming them.</p> <h3 id="expansion-paths-for-multiple-evm-resources">Expansion paths for multiple EVM resources</h3> <p>This EIP has been designed to facilitate a future expansion into multiple EVM resources. We conclude by outlining the challenges inherent to such an expansion, and the different paths that it can take.</p> <h4 id="evm-without-gas-observability">EVM without gas observability</h4> <p>One long-term vision for the EVM is to move away from gas observability. This is one of the features of EOF (<a href="https://wg-eips.ritovision.com/7692/">EIP-7692</a>), e.g., through revamped <code>CALL</code> instructions in <a href="https://wg-eips.ritovision.com/7069/">EIP-7069</a> such as <code>EXTCALL</code>. The new calls no longer accept a gas stipend as an input parameter, and the EVM instead makes available some reasonable fraction of all gas across dimensions (e.g., 63/64). Legitimate use cases previously handled via gas observability are then instead taken over by, e.g., the <code>PAY</code> opcode <a href="https://wg-eips.ritovision.com/5920/">EIP-5920</a>.</p> <p>For compatibility with legacy code, the EVM can in this scenario reinterpret legacy subcalls with a gas parameter by forwarding the same fraction of the caller’s remaining budget in each resource dimension. Concretely, if the call stipulates $g_c$ and the aggregate remaining EVM-gas budget is $g_a$, the callee receives, for each EVM resource with remaining budget $g_r$, the amount $\bigl\lfloor g_r \cdot \min!\bigl(1,\tfrac{g_c}{g_a}\bigr) \bigr\rfloor$. For completeness, the <code>GAS</code> opcode could likewise return, e.g., $g_a$ (the per-call aggregate remaining budget at this point across all resource dimensions). Note, however, that reinterpreting legacy calls and <code>GAS</code> in this way can still change the behavior of contracts that rely on precise gas observability or gas-capped subcalls, and such contracts may break.</p> <h4 id="evm-that-retains-gas-observability">EVM that retains gas observability</h4> <p>It is possible to expand into multiple EVM resource dimensions without breaking existing contracts that rely on gas observability. By treating gas as <em>fungible across resources</em> (just as today), a single budget can be forwarded and counted toward any resource that consumes it. It should be noted that old contracts may still break due to repricing of the resources they use; indeed, a gas repricing effort is currently underway in Ethereum that likely will cause such breakage. But this may be treated as a separate concern.</p> <h4 id="transaction-types-under-multiple-evm-resources-with-non-deterministic-limits">Transaction types under multiple EVM resources with non-deterministic limits</h4> <p>A key difference between the new and old transaction types is that the old transaction types set only one limit, whereas the new can set several. When adding deterministic resources such as calldata, this is not a concern, because consumption of this resource can be deducted from the user-specified limit as a pre-processing step. But once there is more than one non-deterministic resource—as can be the case when EVM gas is separated into several resources—things get slightly more complicated. If we wish to ensure that old transaction types still can function properly under these circumstances, we must apply the single limit to multiple non-deterministic resources. The following subsections will outline how this can be achieved by aggregating the gas of these separate resources during EVM processing.</p> <p>The new transaction type can supply several limits, making expansion into multiple EVM resources more straightforward. However, it turns out that we may also wish to retain the ability of the new transaction type to set a single limit for EVM gas. The reason is that the single limit and aggregate processing facilitates backward compatibility for contracts that rely on gas observability. As previously noted, these contracts must be able to supply subcalls with an aggregate gas stipend, to be counted against any EVM resource. Furthermore, there is an inherent simplicity of the single limit that is not to be discounted.</p> <p>In all considered approaches below, the number of non-deterministic EVM resources still increases at the <em>block level</em>. To retain the ability to reject a transaction that may require more gas for a resource than its associated block limit, it becomes necessary to alter the check on <code>gas_used_so_far</code>. Specifically, when a transaction stipulates only the main EVM gas limit, then this limit must be conservatively counted toward all underspecified dimensions of <code>gas_used_so_far</code> before the limit check:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">if</span><span class="z-support"> len</span><span>(</span><span>tx_gas_limits</span><span>)</span><span class="z-keyword"> ==</span><span class="z-support"> len</span><span>(</span><span>gas_used_so_far</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Same check as previously</span></span> <span class="giallo-l"><span> all_less_or_equal</span><span>(</span><span>vector_add</span><span>(</span><span>gas_used_so_far</span><span>,</span><span> tx_gas_limits</span><span>)</span><span>,</span><span> gas_limits</span><span>)</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"> The joint EVM gas limit is expanded to cover all block resources</span></span> <span class="giallo-l"><span> tx_gas_limits_exp</span><span class="z-keyword"> =</span><span> [</span><span>tx_gas_limits</span><span>[</span><span class="z-constant">0</span><span>]</span><span>]</span><span class="z-keyword"> *</span><span class="z-support"> len</span><span>(</span><span>gas_limits</span><span>)</span></span> <span class="giallo-l"><span> tx_gas_limits_exp</span><span>[</span><span class="z-constant">1</span><span>]</span><span>,</span><span> tx_gas_limits_exp</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-keyword"> =</span><span> tx_gas_limits</span><span>[</span><span class="z-constant">1</span><span>]</span><span>,</span><span> tx_gas_limits</span><span>[</span><span class="z-constant">2</span><span>]</span></span> <span class="giallo-l"><span> all_less_or_equal</span><span>(</span><span>vector_add</span><span>(</span><span>gas_used_so_far</span><span>,</span><span> tx_gas_limits_exp</span><span>)</span><span>,</span><span> gas_limits</span><span>)</span></span></code></pre><h4 id="multidimensional-gas-metering">Multidimensional gas metering</h4> <p>An existing proposal by Inês Silva and Crapis is <em>Multidimensional gas metering</em> (not yet submitted as an EIP), which prices gas in one dimension, but applies limits at the block level across several dimensions when updating the (single) EVM base fee. The EVM will thus track multidimensional gas consumption, but perform the limit check on the aggregate, which is also passed on in subcalls. The proposed EIP could be combined with Multidimensional gas metering, for example by using a single EVM gas and calculating metered block gas usage separately, before submitting the outcome as a single resource dimension to the revamped <code>calc_excess_gas()</code>.</p> <h4 id="multidimensional-fee-market-with-aggregate-evm-gas">Multidimensional fee market with aggregate EVM gas</h4> <p>To promote full resource utilization while maintaining backward compatibility for subcalls and old transaction formats, we could instead use <em>separate</em> gas prices for each EVM resource, while retaining within the EVM the ability to <em>aggregate the gas</em> consumption across resources. We refer to this as a <em>Multidimensional fee market with aggregate gas</em>. In the fully aggregated scenario, the user stipulates a single <code>gas_limit</code> for EVM gas, and the protocol must make sure that the <code>max_fee</code> covers the maximum possible fee, from consuming <code>gas_limit</code> of the EVM resource that has the most expensive base fee. Execution is then fully backward compatible, and the EVM operates the same way as with Multidimensional gas metering.</p> <p>The downside is that the user must stipulate an unnecessarily high <code>max_fee</code> allocation, if the most expensive resource is not used. We present three options for alleviating this. The first two options transfer to the block producer the responsibility to ensure that the <code>max_fee</code> indeed covers a transaction's fees determined post-execution. The third option instead enables the transactor to alternatively provide better guarantees in the form of full gas limits.</p> <p><em>Option 1:</em> Invalidate a block when the post-transaction check shows that the total fee for a transaction exceeded <code>max_fee</code>. We could either completely remove the pre-execution check <code>max_fee &gt;= get_required_max_fee(base_fees, tx_gas_limits)</code>, or only check for deterministic resources in addition to EVM gas across the cheapest EVM resource. During processing, there would still be an aggregated check against the transaction's gas limit, which is the sender's responsibility. In extension, the block's gas limit is already safeguarded pre-execution by conservatively counting <code>tx_gas_limits_exp</code> against it, as outlined in the previous subsection.</p> <p>Note that the inclusion guarantees of EIP-7805 will not apply to the transactions where the <code>max_fee</code> does not cover the worst-case pre-execution check. These transactions are to be ignored when validating the block post-execution.</p> <p><em>Option 2:</em> Give the block producer the ability and responsibility to supply any missing funds as part of the post-transaction check. This could potentially rely on staked builders currently envisioned in <a href="https://wg-eips.ritovision.com/7732/">EIP-7732</a>, albeit it would be more intuitive to use execution layer balances for this purpose. Another alternative is to charge a block-based base fee at the end of processing a block rather than per transaction, as has been discussed in the past. This naturally extends to a multidimensional setting. Note that (2) reverts to (1) upon failure of the builder to ensure the base fees are covered.</p> <p><em>Option 3:</em> Give the transactor the ability to provide limits for all dimensions, if they so wish. The pre-execution check can then be more fine-grained, inheriting the higher capital efficiency previously outlined. This is a hybrid design, where the transactor can choose the option most suitable to their needs if they use the new transaction type. This option will be discussed in more detail in the next subsection. Note that (3) can be combined with (1) if desirable.</p> <h4 id="multidimensional-fee-market-with-hybrid-evm-gas">Multidimensional fee market with hybrid EVM gas</h4> <p>In a <em>Multidimensional fee market with hybrid EVM gas</em>, the user has separate options:</p> <ol> <li>Provide a single gas limit for the EVM resources. The EVM can then operate as in the aggregate gas model, after the initial restrictive fee allocation check.</li> <li>Provide a gas limit for each EVM resource. Capital efficiency is then preserved. The EVM operates without gas observability as previously outlined, with the gas parameter of old subcalls converted to a multidimensional counterpart. The transaction is during processing checked against its multiple limits, as opposed to the aggregate.</li> </ol> <p>It is further possible to give the user the freedom to stipulate <em>some</em> EVM gas limits, but not all. The user can for example set the gas limit to 0 for any resource it knows that it will not use, instead of not setting a gas limit for that resource. The aggregation then takes place only across resources without an individual stipulated limit, reducing the required <code>max_fee</code> allocation while preserving full/a higher level of backward compatibility. These features come at a cost of somewhat increased complexity.</p> <h4 id="specification-for-aggregate-and-hybrid-evm-gas">Specification for aggregate and hybrid EVM gas</h4> <p>For the hybrid model, the <code>get_gas_limits()</code> function must be updated to alternatively return multiple EVM gas limits, in the case the user stipulates the full list.</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_gas_limits</span><span>(</span><span class="z-variable z-parameter z-function">tx</span><span>:</span><span> Transaction</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 class="z-constant"> ...</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> tx</span><span>.</span><span>type</span><span class="z-keyword"> ==</span><span class="z-constant"> MULTIDIM_TX_TYPE</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>tx</span><span>.</span><span>gas_limit</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"> return</span><span> [</span><span>tx</span><span>.</span><span>gas_limit</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span> blob_gas</span><span>,</span><span> calldata_gas</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>tx</span><span>.</span><span>gas_limit</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span> blob_gas</span><span>,</span><span> calldata_gas</span><span>]</span><span class="z-keyword"> +</span><span> tx</span><span>.</span><span>gas_limit</span><span>[</span><span class="z-constant">1</span><span>:</span><span>]</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre> <p>For the aggregate model, the <code>get_required_max_fee()</code> must be updated such that the protocol applies the worst-case EVM base fees across the EVM gas. The new constant <code>EVM_INDICES</code> specifies the EVM resource indices. Note that <code>TX_BASE_COST</code> is treated as a deterministic component of the EVM gas to reduce required capital allocation. Note that even when pursuing Options 1-2 for aggregate gas, the aggregation step is still applied in consideration of EIP-7805.</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_required_max_fee</span><span>(</span><span class="z-variable z-parameter z-function">base_fees</span><span>:</span><span> list</span><span>[</span><span class="z-support">int</span><span>]</span><span>,</span><span class="z-variable z-parameter z-function"> tx_gas_limits</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-punctuation z-definition z-comment"> #</span><span class="z-comment"> Fully specified gas limits, apply baseline pattern</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>base_fees</span><span>)</span><span class="z-keyword"> ==</span><span class="z-support"> len</span><span>(</span><span>tx_gas_limits</span><span>)</span><span>:</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> sum</span><span>(</span><span>vector_mul</span><span>(</span><span>base_fees</span><span>,</span><span> tx_gas_limits</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Otherwise: 1. TX_BASE_COST is treated deterministically (assumed resource 0)</span></span> <span class="giallo-l"><span> determ_evm_cost</span><span class="z-keyword"> =</span><span class="z-constant"> TX_BASE_COST</span><span class="z-keyword"> *</span><span> base_fees</span><span>[</span><span class="z-constant">0</span><span>]</span></span> <span class="giallo-l"><span> require</span><span>(</span><span>tx_gas_limits</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> TX_BASE_COST</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Limit MUST cover TX_BASE_COST.</span></span> <span class="giallo-l"><span> variable_evm_limit</span><span class="z-keyword"> =</span><span> tx_gas_limits</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> -</span><span class="z-constant"> TX_BASE_COST</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 2. Determine EVM cost based on most expensive resource</span></span> <span class="giallo-l"><span> max_evm_base_fee</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span>base_fees</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-constant"> EVM_INDICES</span><span>)</span></span> <span class="giallo-l"><span> evm_cost</span><span class="z-keyword"> =</span><span> determ_evm_cost</span><span class="z-keyword"> +</span><span> variable_evm_limit</span><span class="z-keyword"> *</span><span> max_evm_base_fee</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 3. Return total EVM cost + blob cost + calldata cost</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> evm_cost</span><span class="z-keyword"> +</span><span> base_fees</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword">*</span><span>tx_gas_limits</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> +</span><span> base_fees</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-keyword">*</span><span>tx_gas_limits</span><span>[</span><span class="z-constant">2</span><span>]</span></span></code></pre> <p>For the hybrid model, the line stipulating <code>tip_indices</code> in <code>get_max_priority_fee()</code> must be updated to include all new EVM resources <code>tip_indices = [2] + EVM_INDICES</code>. It is also feasible to adjust the functioning of legacy transactions, to let them tip only according to the headroom between the EVM resource with the highest base fee and the <code>gasprice</code>. The aim would be to prevent them from having to pay an excessive tip when the <code>gasprice</code> was set high merely to cover for the EVM resource with the highest base fee (of which they use little). The tip would then be calculated as the premium above the highest EVM resource base fee.</p> <p>To allow transactors to specify <em>some</em> limits, the <code>tx.gas_limit</code> list must instead have a nested format, where <code>gas_limit[0]</code> is the aggregate limit for unspecified EVM resources, and <code>[index, limit]</code> pairs then follow: <code>tx.gas_limit = [aggregate, [[index, limit], [index, limit],...]]</code>. The protocol then computes the required max fee from resources with both specified and unspecified limits. The maximum base fee among the resources with unspecified limits is in this case multiplied with the aggregate, and this fee is summed together with the fees of specified limits.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The <code>max_fee_per_gas</code> of the EIP-1559 and EIP-4844 transaction types are converted to a <code>max_fee</code> by multiplication with the stipulated gas limit(s). The converted EIP-4844 transactions will no longer adhere to the individual <code>max_fee_per_gas</code> and <code>max_fee_per_blob_gas</code>, but instead to the aggregated <code>max_fee</code>. This is a deliberate choice since previous individual checks have lower economic efficiency to no clear benefit, but it should nevertheless be noted by transactors. The priority fee retains the same functionality as previously. The old <code>gasprice</code> can be used both for the <code>max_fee</code> and <code>max_priority_fee_per_gas</code>. The <code>gas_limit</code> is finally derived deterministically. The section on expansion paths outlined how old transactions can retain functionality as we expand into several non-deterministic EVM resources.</p> <p>Backward compatibility for contracts that rely on gas introspection can be resolved by giving users the ability to rely on aggregated EVM gas, while still potentially pricing EVM resources separately. Wallets must be updated to handle multidimensional gas accounting with several base fees.</p> <h2 id="security-considerations">Security Considerations</h2> <p>One concern is the risk of increasing builder centralization due to increased revenue from sophisticated packing algorithms. While the builder is constrained in its block construction when blocks are full, it is only when several limits are reached at the same time that packing complexity markedly changes from today. Given that around 90% of blocks are below the gas limit, and the calldata limit is set to be very permissive, we argue that this will happen very rarely.</p> <p>One reason for using <code>max_priority_fee_per_gas</code> instead of <code>max_priority_fee</code> is to establish the priority fee as always having a non-aggregate representation. We could possibly otherwise imagine a scenario where a user in the old transaction format manually submits an aggregate <code>max_fee</code> and <code>max_priority_fee</code>, causing loss of funds.</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-08-03T00:00:00+00:00 2026-02-11T14:49:27+00:00 Francisco Giordanohttps://github.com/frangio https://wg-eips.ritovision.com/7997/

A minimal `CREATE2` factory shared by EVM chains.

<h2 id="abstract">Abstract</h2> <p>A minimal <code>CREATE2</code> factory is inserted as a system contract in the precompile range, to enable deterministic deployments at identical addresses across EVM chains. This benefits developer experience, user experience, and security, in particular for multi-chain and cross-chain applications, including account abstraction.</p> <h2 id="motivation">Motivation</h2> <p>There are now a large number of EVM chains where users want to transact and developers want to deploy applications, and we can expect this number to continue to grow in line with Ethereum's rollup-centric roadmap and the general adoption of programmable blockchains.</p> <p>Most applications support multiple chains and aspire to support as many as possible, and their developers widely prefer to deploy contracts at identical addresses across all chains, a setup which we will call <em>multi-chain deterministic deployment</em>.</p> <p>This kind of deployment reduces the number of addresses that must be distributed to use the application, so that it no longer scales with the number of supported chains. This simplification has many benefits throughout the stack: interfaces and SDKs need to embed and trust fewer addresses, and other contracts that depend on them can be implemented without chain-specific customization (which in turn makes them amenable to multi-chain deployment).</p> <p>This kind of deployment is also highly desirable and important for account abstraction. Without it, a user's smart contract accounts are deployed at different addresses on different chains, and each account is tied to a single chain. This limitation is difficult to explain to users and has caused loss of funds. If smart contract accounts cannot be multi-chain like EOAs, they offer downgraded UX and are more prone to error.</p> <p>There is currently no native or fully robust way to perform multi-chain deterministic deployments. While <code>CREATE2</code> enables deterministic deployments, the created address is computed from that of the contract that invokes the instruction, so a <em>factory</em> that is itself multi-chain is required for bootstrapping. Four workarounds are currently known to deploy such a factory, each with their own issues:</p> <ol> <li>A keyless transaction is crafted using Nick's method that can be posted permissionlessly to new chains. For this to work, the chain must support legacy transactions without <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> replay protection, and the fixed gas price and gas limit must be sufficiently high, but not so high as to exceed the limits of the chain.</li> <li>Private keys held by some party are used to sign creation transactions for each chain as needed. This creates a dependency on that party, does not provide a hard guarantee that the factory will be available on every chain, and can also irreversibly fail if transactions are not properly parameterized.</li> <li>A private key is intentionally leaked so that any party can permissionlessly create an <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> signed delegation and deploy a factory from the leaked account. While this approach improves on the previous two, its reliance on ECDSA keys makes it non-quantum-resistant, and will fail once chains stop supporting ECDSA keys. Additionally, it requires EIP-7702, an orthogonal feature which is not guaranteed to spread to all chains; for example, those chains that tackle account abstraction through other means have no use for it, and arguably weaker ecosystem pressure to implement it (compared to other EIPs) given that it is a feature not directly used by applications (which instead access AA capabilities through an abstraction like <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a>). Lastly, there is a possibility that a future upgrade allows EIP-7702 delegations to become permanent, which breaks this scheme.</li> <li>Factories already deployed on other chains (by any of the previous methods) are inserted in a new chain at genesis or via a hard fork. This has not been widely adopted by chains, despite the standardization efforts of RIP-7740. Since these factories are applications deployed by users through normal means, this kind of hardcoding of accounts may be seen by chain developers as too intrusive.</li> </ol> <p>This EIP aims to coordinate a widely available multi-chain <code>CREATE2</code> factory without the above downsides by placing a factory in the precompile range.</p> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <ul> <li><code>FACTORY_ADDRESS</code> = <code>0x12</code></li> </ul> <h3 id="factory-contract">Factory Contract</h3> <p>Upon activation of this EIP, the account at <code>FACTORY_ADDRESS</code> becomes a contract that, when called, invokes the <code>CREATE2</code> instruction (<a href="https://wg-eips.ritovision.com/1014/">EIP-1014</a>) with a salt equal to the first 32 bytes of the call's input data, init code equal to the remaining data, and value equal to the call's value. If input data is smaller than 32 bytes, the call reverts with empty return data. If creation fails (<code>CREATE2</code> outputs <code>0</code>), the call reverts with return data equal to that of the creation frame.</p> <p>Specifically, the code of <code>FACTORY_ADDRESS</code> is set to <code>60203610602f5760003560203603806020600037600034f5806026573d600060003e3d6000fd5b60005260206000f35b60006000fd</code>. This code implements the specification above and corresponds to the following assembly:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>#pragma target &quot;constantinople&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>;; Input: salt (32 bytes) || initcode (variable size)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>;; Verify input is at least 32 bytes long.</span></span> <span class="giallo-l"><span>push 32</span></span> <span class="giallo-l"><span>calldatasize</span></span> <span class="giallo-l"><span>lt</span></span> <span class="giallo-l"><span>jumpi @throw</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>;; Load salt.</span></span> <span class="giallo-l"><span>push 0</span></span> <span class="giallo-l"><span>calldataload</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>;; Compute initcodesize = calldatasize - 32.</span></span> <span class="giallo-l"><span>push 32</span></span> <span class="giallo-l"><span>calldatasize</span></span> <span class="giallo-l"><span>sub</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>;; Copy initcode to memory at position 0.</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push 32</span></span> <span class="giallo-l"><span>push 0</span></span> <span class="giallo-l"><span>calldatacopy</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>;; Invoke create2 with salt and initcode, forwarding all callvalue.</span></span> <span class="giallo-l"><span>push 0</span></span> <span class="giallo-l"><span>callvalue</span></span> <span class="giallo-l"><span>create2</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>;; Check if create2 produced nonzero.</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push @success</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>;; Fallthrough if zero, and revert with identical returndata.</span></span> <span class="giallo-l"><span>returndatasize</span></span> <span class="giallo-l"><span>push 0</span></span> <span class="giallo-l"><span>push 0</span></span> <span class="giallo-l"><span>returndatacopy</span></span> <span class="giallo-l"><span>returndatasize</span></span> <span class="giallo-l"><span>push 0</span></span> <span class="giallo-l"><span>revert</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>;; On success, return the created address.</span></span> <span class="giallo-l"><span>success:</span></span> <span class="giallo-l"><span>push 0</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push 32</span></span> <span class="giallo-l"><span>push 0</span></span> <span class="giallo-l"><span>return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>throw:</span></span> <span class="giallo-l"><span>push 0</span></span> <span class="giallo-l"><span>push 0</span></span> <span class="giallo-l"><span>revert</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="precompile-range-system-contract">Precompile-range system contract</h3> <p>Unlike previous system contracts, this factory cannot be deployed using a normal transaction because, as explained in the Motivation section, that transaction could not be guaranteed to be valid on other chains. Since the purpose of this factory is to be available in all EVM chains that a contract could be deployed to, an irregular insertion of the code into a special address seems necessary.</p> <p>The address <code>0x12</code> (<code>0x0000000000000000000000000000000000000012</code>) is chosen as the next lowest address after currently accepted precompiles, on the assumption that other EVM chains would have reserved this range for future Ethereum precompiles.</p> <h3 id="input-validation">Input validation</h3> <p>The factory reverts if the input is smaller than 32 bytes, the minimum size that contains the salt, to provide an explicit error when the factory is not correctly invoked.</p> <h3 id="no-frontrunning-protection">No frontrunning protection</h3> <p>As explained in the Security Considerations, deployments using this factory can potentially be frontrun.</p> <p>A different factory could avoid this issue if it invokes <code>CREATE2</code> with a salt computed from the caller address in combination with the caller-provided salt input. This prevents frontrunning, but makes deployments permissioned to a deployer account, without the ability to recover permissionless deployments across chains because of the bootstrapping problem this EIP is itself meant to solve.</p> <p>A factory could also support both permissioned and permissionless deployments by making the mechanism opt-in. However, the addition of this complexity to an otherwise very simple contract was deemed unnecessary, since once the bootstrapping problem is solved, further factories with a more comprehensive set of features and security measures can be deterministically deployed across chains. We expect this to be the case.</p> <h3 id="not-a-new-transaction-type">Not a new transaction type</h3> <p>An alternative approach would consist of a new creation transaction type where the address of the created contract is computed in a way independent of the transaction origin. A system contract was considered a simpler approach that will be more robust to changes in the base layer in the future or across chains.</p> <h3 id="constantinople-target-avoidance-of-push0">Constantinople target, avoidance of <code>PUSH0</code></h3> <p>The system contract is written to avoid the use of newer opcodes such as <code>PUSH0</code> to make it viable to be adopted by chains that don't yet support them, decoupling the decision to adopt this EIP from that of adopting other EIPs.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><code>FACTORY_ADDRESS</code> must not be used by other precompiles or predeploys upon activation of this EIP on a chain. The constant must be chosen to minimize likelihood that this happens.</p> <h2 id="test-cases">Test Cases</h2> <!-- TODO --> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="frontrunnable-deployments">Frontrunnable deployments</h3> <p>The deployment of contracts that read the environment (<code>ORIGIN</code>, <code>NUMBER</code>, etc.) may be frontrun and created with attacker-chosen parameters. It's recommended to use this factory to deploy fully deterministic contracts only.</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-08-03T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alberto La Roccahttps://github.com/71104 Aryaethnhttps://github.com/aryaethn https://wg-eips.ritovision.com/7998/

Transforms Ethereum’s `randao_reveal` into a per-slot BLS-based VRF by signing the previous epoch’s mix and current slot.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a modification to the data signed by a block proposer for the <code>randao_reveal</code>. The current <code>randao_reveal</code> is a BLS signature over the current epoch number, which is predictable. This proposal incorporates the RANDAO mix of the previous epoch and the current slot number into the signed data. This change transforms the <code>randao_reveal</code> into a Verifiable Random Function (VRF), making it unpredictable across epochs even for the revealer itself. This enhancement strengthens Ethereum's native randomness source and enables protocols such as Single Secret Leader Election (SSLE).</p> <h2 id="motivation">Motivation</h2> <p>This change creates a secure, per-slot VRF output from the proposer, with several benefits:</p> <ol> <li>it <strong>paves the way for secret proposer election</strong>, which would in turn reduce MEV and completely eliminate the well-known RANDAO bias attack vector;</li> <li>it supports other proposals like <a href="https://wg-eips.ritovision.com/7956/">EIP-7956</a> that rely on a source of verifiable randomness.</li> </ol> <p>Using a BLS signature as a VRF is sound under the Computational Diffie-Hellman (CDH) assumption, rather than Decisional Diffie-Hellman. The BLS verification process inherently proves the correctness of the VRF output without requiring a separate proof.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <p>The gist of the change is in <code>process_randao</code>, which now uses the RANDAO mix of the previous epoch and the current slot number to seed the <code>randao_reveal</code> signature. We are introducing a new SSZ-serializable container called <code>RandaoRevealSeed</code> containing that information.</p> <h3 id="new-ssz-container">New SSZ Container</h3> <p>A new SSZ <code>Container</code> is introduced to serve as the message for the <code>randao_reveal</code> signature post-fork.</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"> RandaoRevealSeed</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> previous_mix</span><span>:</span><span> Bytes32</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> last RANDAO mix of the previous epoch</span></span> <span class="giallo-l"><span> slot</span><span>:</span><span> Slot</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> current slot number</span></span></code></pre><h3 id="modified-process-randao">Modified <code>process_randao</code></h3> <p>The block processing function <code>process_randao</code> in the beacon state transition is modified.</p> <p>Let <code>FORK_EPOCH</code> be the epoch of the network upgrade.</p> <p>The logic for verifying <code>body.randao_reveal</code> within <code>process_randao</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"> process_randao</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"> body</span><span>:</span><span> BeaconBlockBody</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> 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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify RANDAO reveal</span></span> <span class="giallo-l"><span> proposer</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>validators</span><span>[</span><span>get_beacon_proposer_index</span><span>(</span><span>state</span><span>)</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> epoch</span><span class="z-keyword"> &lt;</span><span class="z-constant"> FORK_EPOCH</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>epoch</span><span>,</span><span> get_domain</span><span>(</span><span>state</span><span>,</span><span class="z-constant"> DOMAIN_RANDAO</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> previous_epoch</span><span class="z-keyword"> =</span><span> get_previous_epoch</span><span>(</span><span>state</span><span>)</span></span> <span class="giallo-l"><span> previous_mix</span><span class="z-keyword"> =</span><span> get_randao_mix</span><span>(</span><span>state</span><span>,</span><span> previous_epoch</span><span>)</span></span> <span class="giallo-l"><span> seed</span><span class="z-keyword"> =</span><span> RandaoRevealSeed</span><span>(</span><span>previous_mix</span><span>,</span><span> state</span><span>.</span><span>slot</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>seed</span><span>,</span><span> get_domain</span><span>(</span><span>state</span><span>,</span><span class="z-constant"> DOMAIN_RANDAO</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> bls</span><span>.</span><span>Verify</span><span>(</span><span>proposer</span><span>.</span><span>pubkey</span><span>,</span><span> signing_root</span><span>,</span><span> body</span><span>.</span><span>randao_reveal</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Mix in RANDAO reveal</span></span> <span class="giallo-l"><span> mix</span><span class="z-keyword"> =</span><span> xor</span><span>(</span><span>get_randao_mix</span><span>(</span><span>state</span><span>,</span><span> epoch</span><span>)</span><span>,</span><span class="z-support"> hash</span><span>(</span><span>body</span><span>.</span><span>randao_reveal</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>randao_mixes</span><span>[</span><span>epoch</span><span class="z-keyword"> %</span><span class="z-constant"> EPOCHS_PER_HISTORICAL_VECTOR</span><span>]</span><span class="z-keyword"> =</span><span> mix</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="choice-of-vrf-input">Choice of VRF Input</h3> <p>The <code>randao_reveal</code> is effectively transformed into <code>VRF(sk, message)</code> where the <code>message</code> is the SSZ serialization of the <code>RandaoRevealSeed</code> container.</p> <ul> <li><code>previous_mix</code>: Including the RANDAO mix from the previous epoch (<code>previous_mix</code>) is the core of this proposal. Since the previous epoch's final mix is not known until the end of that epoch, a proposer cannot compute their <code>randao_reveal</code> of future epochs, beforehand.</li> <li><code>slot</code>: Including the current <code>slot</code> number ensures that the <code>randao_reveal</code> is unique for each slot and unpredictable to other validators. Without it, a validator chosen to propose multiple times in an epoch would produce the same reveal, which is undesirable for protocols that require unique randomness per instance, such as SSLE.</li> </ul> <h3 id="alternatives-considered">Alternatives Considered</h3> <p>We considered adding the <em>latest</em> RANDAO mix rather than that from the previous epoch so that we could obtain per-slot unpredictability, but that would cause fork ambiguity in the future if <code>randao_reveal</code> is used to implement SSLE.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces a backwards-incompatible change to the consensus rules and MUST be activated as part of a scheduled network upgrade (i.e., a hard fork).</p> <p>Blocks produced after the <code>FORK_EPOCH</code> that do not use the new <code>RandaoRevealSeed</code> structure for the <code>randao_reveal</code> signature SHALL be considered invalid. Pre-fork blocks remain valid under the old rules.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="vrf-security">VRF Security</h3> <p>The security of the BLS signature scheme as a VRF relies on the Computational Diffie-Hellman (CDH) assumption in the target group. This is a standard cryptographic assumption. The output of the signature (a uniformly distributed G2 point in compressed format) can be treated as a pseudorandom number.</p> <h3 id="grinding">Grinding</h3> <p>The value of <code>randao_reveal</code> is deterministic and cannot be manipulated. It will be verified with the public BLS key of the validator, so it must be calculated using the corresponding private key. There are no grindable elements.</p> <h3 id="slot-by-slot-unpredictability">Slot-by-slot Unpredictability</h3> <p>Including the slot number is superfluous at the moment because it does not make the VRF slot-by-slot unpredictable to the revealer, only to other validators. But it will become critical in the future if and when we decide to implement secret proposer election and/or EIP-7956.</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-08-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Kwame Bryanhttps://github.com/KBryan https://wg-eips.ritovision.com/8001/

Minimal, single-chain, multi-party agent coordination using EIP-712 attestations

<h2 id="abstract">Abstract</h2> <p><a href="https://wg-eips.ritovision.com/8001/">ERC-8001</a> defines a minimal, single-chain primitive for <strong>multi-party agent coordination</strong>. An initiator posts an intent and each participant provides a verifiable acceptance attestation. Once the required set of acceptances is present and fresh, the intent is executable. The standard specifies typed data, lifecycle, mandatory events, and verification rules compatible with <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>, <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>, <a href="https://wg-eips.ritovision.com/2098/">EIP-2098</a>, and <a href="https://wg-eips.ritovision.com/5267/">EIP-5267</a>.</p> <p><a href="https://wg-eips.ritovision.com/8001/">ERC-8001</a> omits privacy, reputation, threshold policies, bonding, and cross-chain semantics. Those are expected as optional modules that reference this specification.</p> <h2 id="motivation">Motivation</h2> <p>Agents in DeFi/MEV/Web3 Gaming and Agentic Commerce often need to act together without a trusted coordinator. Existing intent standards (e.g., <a href="https://wg-eips.ritovision.com/7521/">ERC-7521</a>, <a href="https://wg-eips.ritovision.com/7683/">ERC-7683</a>) define single-initiator flows and do not specify multi-party agreement.</p> <p><a href="https://wg-eips.ritovision.com/8001/">ERC-8001</a> specifies the smallest on-chain primitive for that gap: an initiator's <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> intent plus per-participant <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>/<a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a> acceptances. The intent becomes executable only when the required set of acceptances is present and unexpired. Canonical (sorted-unique) participant lists and standard typed data provide replay safety and wallet compatibility. Privacy, thresholds, bonding, and cross-chain are left to modules.</p> <h2 id="specification">Specification</h2> <p>The keywords “MUST”, “SHOULD”, and “MAY” are to be interpreted as described in RFC 2119 and RFC 8174.</p> <p>Implementations MUST expose the following canonical status codes for <code>getCoordinationStatus</code>:</p> <h3 id="status-codes">Status Codes</h3> <p>Implementations MUST use the canonical enum defined below:</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"> Status</span><span> {</span><span class="z-variable z-other z-enummember"> None</span><span>,</span><span class="z-variable z-other z-enummember"> Proposed</span><span>,</span><span class="z-variable z-other z-enummember"> Ready</span><span>,</span><span class="z-variable z-other z-enummember"> Executed</span><span>,</span><span class="z-variable z-other z-enummember"> Cancelled</span><span>,</span><span class="z-variable z-other z-enummember"> Expired</span><span> }</span></span></code></pre> <ul> <li> <p><code>None</code> = default zero state (intent not found)</p> </li> <li> <p><code>Proposed</code> = intent proposed, not all acceptances yet</p> </li> <li> <p><code>Ready</code> = all participants have accepted, intent executable</p> </li> <li> <p><code>Executed</code> = intent successfully executed</p> </li> <li> <p><code>Cancelled</code> = intent explicitly cancelled</p> </li> <li> <p><code>Expired</code> = intent expired before execution</p> </li> </ul> <h3 id="overview">Overview</h3> <p>This ERC specifies:</p> <ul> <li>A canonicalised EIP-712 domain for agent coordination,</li> <li>Typed data structures (<code>AgentIntent</code>, <code>CoordinationPayload</code>, <code>AcceptanceAttestation</code>),</li> <li>Deterministic hashing rules,</li> <li>A standard interface (<code>IAgentCoordination</code>),</li> <li>Lifecycle semantics (propose → accept → execute/cancel),</li> <li>Error surface and status codes.</li> </ul> <h3 id="eip-712-domain">EIP-712 Domain</h3> <p>Implementations MUST use the following EIP-712 domain:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{name: &quot;ERC-8001&quot;, version: &quot;1&quot;, chainId, verifyingContract}</span></span></code></pre> <p>Implementations SHOULD expose the domain via <a href="https://wg-eips.ritovision.com/5267/">ERC-5267</a>.</p> <h3 id="primary-types">Primary Types</h3> <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"> AgentIntent</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> payloadHash</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> keccak256(CoordinationPayload)</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> expiry</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> unix seconds; MUST be &gt; block.timestamp at propose</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> nonce</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> per-agent nonce; MUST be &gt; agentNonces[agentId]</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> agentId</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> initiator and signer of the intent</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> coordinationType</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> domain-specific type id, e.g. keccak256(&quot;MEV_SANDWICH_COORD_V1&quot;)</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> coordinationValue</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> informational in Core; modules MAY bind value</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span> participants</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> unique, ascending; MUST include agentId</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"> CoordinationPayload</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> version</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> payload format id</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> coordinationType</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> MUST equal AgentIntent.coordinationType</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> coordinationData</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> opaque to Core</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> conditionsHash</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> domain-specific</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> timestamp</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> creation time (informational)</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> metadata</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> optional</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"> AcceptanceAttestation</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> intentHash</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> getIntentHash(intent)</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> participant</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> signer</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> nonce</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> optional in Core; see Nonces</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> expiry</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> acceptance validity; MUST be &gt; now at accept and execute</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> conditionsHash</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> participant constraints</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> signature</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> ECDSA (65 or 64 bytes) or ERC-1271</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="typed-data-hashes">Typed Data Hashes</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-support">bytes32</span><span class="z-storage z-type"> constant</span><span> AGENT_INTENT_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;AgentIntent(bytes32 payloadHash,uint64 expiry,uint64 nonce,address agentId,bytes32 coordinationType,uint256 coordinationValue,address[] participants)&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> ACCEPTANCE_TYPEHASH </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Field names MUST exactly match the Solidity struct.</span></span> <span class="giallo-l"><span class="z-string"> &quot;AcceptanceAttestation(bytes32 intentHash,address participant,uint64 nonce,uint64 expiry,bytes32 conditionsHash)&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"> participants MUST be unique and strictly ascending by uint160(address).</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _participantsHash</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"> ps</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">encodePacked</span><span>(</span><span>ps</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"> _agentIntentStructHash</span><span>(</span><span class="z-storage z-type">AgentIntent</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> i</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> <span class="giallo-l"><span> AGENT_INTENT_TYPEHASH</span><span>,</span></span> <span class="giallo-l"><span> i</span><span>.</span><span>payloadHash</span><span>,</span></span> <span class="giallo-l"><span> i</span><span>.</span><span>expiry</span><span>,</span></span> <span class="giallo-l"><span> i</span><span>.</span><span>nonce</span><span>,</span></span> <span class="giallo-l"><span> i</span><span>.</span><span>agentId</span><span>,</span></span> <span class="giallo-l"><span> i</span><span>.</span><span>coordinationType</span><span>,</span></span> <span class="giallo-l"><span> i</span><span>.</span><span>coordinationValue</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> _participantsHash</span><span>(</span><span>i</span><span>.</span><span>participants</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 class="z-comment"> Full EIP-712 digest for the initiator’s signature.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _agentIntentDigest</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> domainSeparator</span><span>,</span><span class="z-storage z-type"> AgentIntent</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> i</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">encodePacked</span><span>(</span><span class="z-string">&quot;\x19\x01&quot;</span><span>,</span><span> domainSeparator</span><span>,</span><span class="z-entity z-name"> _agentIntentStructHash</span><span>(</span><span>i</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"> _acceptanceStructHash</span><span>(</span><span class="z-storage z-type">AcceptanceAttestation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> a</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-comment"> //</span><span class="z-comment"> a.intentHash MUST be the AgentIntent struct hash, not the digest.</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> <span class="giallo-l"><span> ACCEPTANCE_TYPEHASH</span><span>,</span></span> <span class="giallo-l"><span> a</span><span>.</span><span>intentHash</span><span>,</span></span> <span class="giallo-l"><span> a</span><span>.</span><span>participant</span><span>,</span></span> <span class="giallo-l"><span> a</span><span>.</span><span>nonce</span><span>,</span></span> <span class="giallo-l"><span> a</span><span>.</span><span>expiry</span><span>,</span></span> <span class="giallo-l"><span> a</span><span>.</span><span>conditionsHash</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"> _acceptanceDigest</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> domainSeparator</span><span>,</span><span class="z-storage z-type"> AcceptanceAttestation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> a</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">encodePacked</span><span>(</span><span class="z-string">&quot;\x19\x01&quot;</span><span>,</span><span> domainSeparator</span><span>,</span><span class="z-entity z-name"> _acceptanceStructHash</span><span>(</span><span>a</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span></code></pre> <p>Computation (normative):</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>participantsHash </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>participants</span><span>)</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> sorted unique</span></span> <span class="giallo-l"><span>intentStructHash </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> AGENT_INTENT_TYPEHASH</span><span>,</span></span> <span class="giallo-l"><span> payloadHash</span><span>,</span><span> expiry</span><span>,</span><span> nonce</span><span>,</span><span> agentId</span><span>,</span><span> coordinationType</span><span>,</span><span> coordinationValue</span><span>,</span><span> participantsHash</span></span> <span class="giallo-l"><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>intentDigest </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;\x19\x01&quot;</span><span class="z-keyword"> ||</span><span> domainSeparator </span><span class="z-keyword">||</span><span> intentStructHash</span><span>)</span><span>;</span></span> <span class="giallo-l"></span></code></pre> <p>Clarifications (normative):</p> <ul> <li><code>getIntentHash(intent)</code> MUST return <code>intentStructHash</code> (struct hash), not the full digest.</li> <li><code>AcceptanceAttestation.intentHash</code> MUST be that struct hash.</li> <li>Each acceptance is signed over its own EIP-712 digest that includes this field.</li> <li><code>participants</code> MUST be strictly ascending by <code>uint160(address)</code> and deduplicated.</li> </ul> <h3 id="interface">Interface</h3> <p>Implementations <strong>MUST</strong> expose the following interface and events.</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"> IAgentCoordination</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CoordinationProposed</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> intentHash</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> proposer</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> coordinationType</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> participantCount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> coordinationValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CoordinationAccepted</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> intentHash</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> participant</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> acceptanceHash</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> acceptedCount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> requiredCount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CoordinationExecuted</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> intentHash</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> executor</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> success</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> gasUsed</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> result</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CoordinationCancelled</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> intentHash</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> canceller</span><span>, </span><span class="z-support">string</span><span class="z-variable"> reason</span><span>, </span><span class="z-support">uint8</span><span class="z-variable"> finalStatus</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"> proposeCoordination</span><span>(</span><span class="z-storage z-type">AgentIntent</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> intent</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"> CoordinationPayload</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> payload</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"> intentHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptCoordination</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> intentHash</span><span>,</span><span class="z-storage z-type"> AcceptanceAttestation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> attestation</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"> allAccepted</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> executeCoordination</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> intentHash</span><span>,</span><span class="z-storage z-type"> CoordinationPayload</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> payload</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> executionData</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 class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> result</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> cancelCoordination</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> intentHash</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>;</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"> getCoordinationStatus</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> intentHash</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">Status</span><span class="z-variable"> status</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> proposer</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"> participants</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"> acceptedBy</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> expiry</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getRequiredAcceptances</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> intentHash</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"> getAgentNonce</span><span>(</span><span class="z-support">address</span><span class="z-variable"> agent</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></span></code></pre><h3 id="semantics">Semantics</h3> <p>The functions defined in this specification MUST exhibit the following externally observable behaviours.<br /> This standard does NOT prescribe storage layout, execution model, or internal mechanisms.</p> <h4 id="proposecoordination"><code>proposeCoordination</code></h4> <p><code>proposeCoordination</code> MUST revert if:</p> <ul> <li>the signature does not validate the supplied <code>AgentIntent</code> under the ERC-8001 EIP-712 domain;</li> <li><code>intent.expiry &lt;= block.timestamp</code>;</li> <li><code>intent.nonce</code> is not strictly greater than <code>getAgentNonce(intent.agentId)</code>;</li> <li><code>participants</code> is not strictly ascending and unique;</li> <li><code>intent.agentId</code> is not included in the participants list.</li> </ul> <p>If valid:</p> <ul> <li><code>CoordinationProposed</code> MUST be emitted;</li> <li><code>getCoordinationStatus</code> MUST report <code>Proposed</code>;</li> <li><code>getAgentNonce(intent.agentId)</code> MUST equal the supplied nonce;</li> <li><code>getRequiredAcceptances(intentHash)</code> MUST equal the number of participants.</li> </ul> <h4 id="acceptcoordination"><code>acceptCoordination</code></h4> <p><code>acceptCoordination</code> MUST revert if:</p> <ul> <li>the intent does not exist or has expired;</li> <li>the caller is not listed as a participant;</li> <li>the participant has already accepted;</li> <li>the attestation signature does not validate under the ERC-8001 domain;</li> <li><code>attestation.expiry &lt;= block.timestamp</code>.</li> </ul> <p>If valid:</p> <ul> <li><code>CoordinationAccepted</code> MUST be emitted;</li> <li>the participant MUST appear in the <code>acceptedBy</code> list returned by <code>getCoordinationStatus</code>;</li> <li>if all participants have accepted: <ul> <li>the function MUST return <code>true</code>;</li> <li>status MUST be <code>Ready</code>.</li> </ul> </li> </ul> <p>Otherwise the function MUST return <code>false</code>.</p> <h4 id="executecoordination"><code>executeCoordination</code></h4> <p><code>executeCoordination</code> MUST revert if:</p> <ul> <li>the intent is not in <code>Ready</code> state;</li> <li><code>intent.expiry &lt;= block.timestamp</code>;</li> <li>any acceptance has expired;</li> <li>the supplied payload does not hash to <code>payloadHash</code>.</li> </ul> <p>If valid:</p> <ul> <li>the implementation MUST attempt execution of the behaviour represented by <code>executionData</code>;</li> <li>the function MUST return <code>(success, result)</code>;</li> <li><code>CoordinationExecuted</code> MUST be emitted;</li> <li><code>getCoordinationStatus</code> MUST report <code>Executed</code>.</li> </ul> <h4 id="cancelcoordination"><code>cancelCoordination</code></h4> <ul> <li>If the intent has not expired, only the proposer MUST be permitted to cancel.</li> <li>After expiry, any caller MUST be permitted to cancel.</li> </ul> <p>On success:</p> <ul> <li><code>CoordinationCancelled</code> MUST be emitted;</li> <li>status MUST be <code>Cancelled</code>.</li> </ul> <h4 id="getcoordinationstatus"><code>getCoordinationStatus</code></h4> <p><code>getCoordinationStatus(intentHash)</code> MUST return:</p> <ul> <li><code>None</code> if the intent does not exist;</li> <li><code>Proposed</code> if not all participants have accepted and the intent has not expired;</li> <li><code>Ready</code> if all participants have accepted and expiries have not elapsed;</li> <li><code>Executed</code> if execution has occurred;</li> <li><code>Cancelled</code> if cancellation has occurred;</li> <li><code>Expired</code> if the intent has expired and was not executed or cancelled.</li> </ul> <h4 id="nonces">Nonces</h4> <ul> <li><code>getAgentNonce(agent)</code> MUST increase for every valid new intent.</li> <li><code>proposeCoordination</code> MUST reject nonces not strictly greater than the stored nonce.</li> <li>Acceptance-level nonces MAY be implemented; if so, they MUST be strictly monotonic per participant.</li> </ul> <h3 id="errors">Errors</h3> <p>Implementations SHOULD revert with descriptive custom errors (or equivalent revert strings) for the following baseline conditions, and MAY define additional errors for domain-specific modules (e.g. slashing, reputation, or privacy conditions):</p> <ul> <li>Expired intent</li> <li>Bad signature</li> <li>Non-participant</li> <li>Duplicate acceptance</li> <li>Acceptance expired at execute</li> <li>Payload hash mismatch</li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> ERC8001_NotProposer</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> ERC8001_ExpiredIntent</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> ERC8001_ExpiredAcceptance</span><span>(</span><span class="z-support">address</span><span> participant</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> ERC8001_BadSignature</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> ERC8001_NotParticipant</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> ERC8001_DuplicateAcceptance</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> ERC8001_ParticipantsNotCanonical</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> ERC8001_NonceTooLow</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> ERC8001_PayloadHashMismatch</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> ERC8001_NotReady</span><span>(</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <ul> <li>Sorted participant lists remove hash malleability and allow off-chain deduplication.</li> <li>Separation of intent and acceptance allows off-chain collation and a single on-chain check.</li> <li>Keeping <a href="https://wg-eips.ritovision.com/8001/">ERC-8001</a> single-chain avoids coupling to bridge semantics and keeps the primitive audit-friendly.</li> <li>Wallet friendliness: EIP-712 arrays let signers see actual participant addresses.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><a href="https://wg-eips.ritovision.com/8001/">ERC-8001</a> introduces a new interface. It is compatible with EOA and contract wallets via ECDSA and ERC-1271. It does not modify existing standards.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A permissive reference implementation is provided in <a href="https://wg-eips.ritovision.com/8001/./assets/contracts/AgentCoordination.sol"><code>contracts/AgentCoordination.sol</code></a>. It uses a minimal ECDSA helper and supports ERC-1271 signers. It enforces participant canonicalisation, intent nonces, acceptance freshness, and all-participants policy.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li><strong>Replay</strong>: EIP-712 domain binding and monotonic nonces prevent cross-contract replay.</li> <li><strong>Malleability</strong>: Low-s enforcement and 64/65-byte signature support are required.</li> <li><strong>Equivocation</strong>: A participant can sign conflicting intents. Mitigate with module-level slashing or reputation.</li> <li><strong>Liveness</strong>: Enforce TTL on both intent and acceptances. Executors should ensure enough time remains.</li> <li><strong>MEV</strong>: If <code>coordinationData</code> reveals strategy, use a Privacy module with commit-reveal or encryption.</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> 2025-07-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Anushka Yadavhttps://github.com/64anushka Akash Kothawadehttps://github.com/akash3927 Atishek Singhhttps://github.com/atisheksingh https://wg-eips.ritovision.com/7994/

Extends ERC-20 with programmable restrictions, enabling transfers based on multiple unlock conditions as defined in EIP-7291.

<h2 id="abstract">Abstract</h2> <p>This ERC extends the concept introduced in <a href="https://wg-eips.ritovision.com/7291/">ERC-7291</a> by enabling <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>-compatible tokens to carry multi-condition unlocking constraints, combining temporal, identity, and usage restrictions into a programmable structure. It aims to support controlled disbursement of tokens where funds are only accessible under predefined, auditable, and verifiable conditions.</p> <h2 id="motivation">Motivation</h2> <p>ERC-7291 introduced purpose-bound money by restricting how and where tokens can be spent. However, many real-world applications require multiple conditions to be satisfied simultaneously before tokens can be used. Examples include:</p> <ul> <li>Scholarships requiring the recipient to be KYC-verified, under 25 years of age, and registered at a university.</li> <li>NGO aid to be used only for food and medicine, after a specific unlock date.</li> <li>Payroll tokens that unlock monthly and only for whitelisted vendors (e.g., banks, healthcare providers).</li> </ul> <p>This proposal generalizes and formalizes such use cases by layering unlocking conditions on top of the ERC-20 standard.</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="interface">Interface</h3> <p>The <code>IPurposeBoundERC20</code> interface defines the standard for programmable token transfers that are conditional. Each transfer, referred to as a <em>purpose binding</em>, includes:</p> <ul> <li>A <code>recipient</code> and <code>amount</code>.</li> <li>A set of <code>UnlockCondition</code> objects, each consisting of a <code>conditionType</code> (like <code>"TIME"</code>, <code>"KYC"</code>, or <code>"WHITELIST"</code>) and <code>conditionData</code> used to evaluate the condition.</li> <li>An optional <code>expiry</code> timestamp after which the transfer can no longer be claimed.</li> </ul> <p>The interface provides the following functions:</p> <ul> <li><code>bindPurpose(...)</code>: Locks a specified amount of tokens to a recipient with defined conditions.</li> <li><code>claim(...)</code>: Allows the recipient to claim the tokens once all conditions are fulfilled.</li> <li><code>isUnlocked(...)</code>: Returns whether all associated conditions have been satisfied.</li> </ul> <p>This enables flexible, composable transfer mechanisms for various use cases including compliance, grants, payroll, and more.</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.23</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"> IPurposeBoundERC20</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> UnlockCondition</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> conditionType</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> e.g., &quot;TIME&quot;, &quot;KYC&quot;, &quot;WHITELIST&quot;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> conditionData</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> e.g., timestamp, Merkle root, etc.</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"> bindPurpose</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"> amount</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> UnlockCondition</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> conditions</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> expiry</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">bytes32</span><span class="z-variable"> bindingId</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"> claim</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> bindingId</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"> isUnlocked</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> bindingId</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>Flexibility: Conditions are modular and extensible.</p> <p>Composability: Can be integrated into DAOs, payroll, education, and compliance tokens.</p> <p>Security: Off-chain verification (e.g., KYC) backed by on-chain proofs (e.g., Merkle roots).</p> <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.23</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"> Reference Implementation - Purpose-Bound ERC20 with Multi-Condition Unlocking</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Implements IPurposeBoundERC20 with conditionType mapping to on-chain checkers.</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/ERC20.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IPurposeBoundERC20.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-comment"> Interface for pluggable condition checker contracts</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IConditionChecker</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isConditionMet</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-storage z-type"> calldata</span><span class="z-variable"> conditionData</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-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> PurposeBoundERC20 Implementation</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> PurposeBoundERC20</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC20</span><span>, </span><span class="z-entity z-name">IPurposeBoundERC20</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> StoredBinding</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"> uint256</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span> UnlockCondition</span><span>[</span><span>]</span><span> conditions</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 class="z-support"> uint256</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-storage z-type"> @dev</span><span class="z-comment"> Maps conditionType → on-chain checker contract</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"> address</span><span>)</span><span class="z-storage z-type"> public</span><span> conditionResolvers</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"> Maps bindingId → locked transfer</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> StoredBinding</span><span>)</span><span class="z-storage z-type"> public</span><span> boundTransfers</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"> PurposeBound</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> bindingId</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"> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Claimed</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> bindingId</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>;</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"> ERC20</span><span>(</span><span>name_, symbol_) </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_000_000</span><span class="z-constant"> ether</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> for demo purposes</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"> @notice</span><span class="z-comment"> Admin can register or update condition checkers for condition types</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setConditionResolver</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> conditionType</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> checker</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"> For demo purposes: public function. In production: onlyOwner or AccessControl.</span></span> <span class="giallo-l"><span> conditionResolvers</span><span>[</span><span>conditionType</span><span>]</span><span class="z-keyword"> =</span><span> checker</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"> @inheritdoc</span><span class="z-comment"> IPurposeBoundERC20</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> bindPurpose</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"> amount</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> UnlockCondition</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> conditions</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> expiry</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">bytes32</span><span class="z-variable"> bindingId</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>recipient </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;Invalid recipient&quot;</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 class="z-string"> &quot;Invalid amount&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> bindingId </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-variable z-language">msg.sender</span><span>,</span><span> recipient</span><span>,</span><span> amount</span><span>,</span><span> conditions</span><span>,</span><span> expiry</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> StoredBinding </span><span class="z-storage z-type">storage</span><span> stored </span><span class="z-keyword">=</span><span> boundTransfers</span><span>[</span><span>bindingId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>stored</span><span>.</span><span>amount </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Binding exists&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> _transfer</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"></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> conditions</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> stored</span><span>.</span><span>conditions</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>conditions</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> <span class="giallo-l"><span> stored</span><span>.</span><span>recipient </span><span class="z-keyword">=</span><span> recipient</span><span>;</span></span> <span class="giallo-l"><span> stored</span><span>.</span><span>amount </span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span> stored</span><span>.</span><span>expiry </span><span class="z-keyword">=</span><span> expiry</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"> PurposeBound</span><span>(</span><span>bindingId</span><span>,</span><span class="z-variable z-language"> msg.sender</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @inheritdoc</span><span class="z-comment"> IPurposeBoundERC20</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isUnlocked</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> bindingId</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 class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> StoredBinding </span><span class="z-storage z-type">storage</span><span> binding </span><span class="z-keyword">=</span><span> boundTransfers</span><span>[</span><span>bindingId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>binding</span><span>.</span><span>claimed</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>binding</span><span>.</span><span>expiry </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-language"> block</span><span>.</span><span>timestamp </span><span class="z-keyword">&gt;</span><span> binding</span><span>.</span><span>expiry</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"></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> binding</span><span>.</span><span>conditions</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> UnlockCondition </span><span class="z-storage z-type">storage</span><span> cond </span><span class="z-keyword">=</span><span> binding</span><span>.</span><span>conditions</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> checker </span><span class="z-keyword">=</span><span> conditionResolvers</span><span>[</span><span>cond</span><span>.</span><span>conditionType</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>checker </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;Checker not set&quot;</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">IConditionChecker</span><span>(</span><span>checker</span><span>)</span><span>.</span><span class="z-entity z-name">isConditionMet</span><span>(</span><span>binding</span><span>.</span><span>recipient</span><span>,</span><span> cond</span><span>.</span><span>conditionData</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></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 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-storage z-type"> @inheritdoc</span><span class="z-comment"> IPurposeBoundERC20</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">bytes32</span><span class="z-variable"> bindingId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> override</span><span> {</span></span> <span class="giallo-l"><span> StoredBinding </span><span class="z-storage z-type">storage</span><span> binding </span><span class="z-keyword">=</span><span> boundTransfers</span><span>[</span><span>bindingId</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> binding</span><span>.</span><span>recipient</span><span>,</span><span class="z-string"> &quot;Not recipient&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>binding</span><span>.</span><span>claimed</span><span>,</span><span class="z-string"> &quot;Already claimed&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">isUnlocked</span><span>(</span><span>bindingId</span><span>)</span><span>,</span><span class="z-string"> &quot;Conditions not met&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> binding</span><span>.</span><span>claimed </span><span class="z-keyword">=</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _transfer</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> binding</span><span>.</span><span>recipient</span><span>,</span><span> binding</span><span>.</span><span>amount</span><span>)</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"> Claimed</span><span>(</span><span>bindingId</span><span>,</span><span> binding</span><span>.</span><span>recipient</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 class="z-storage z-type"> @dev</span><span class="z-comment"> Example of Time-Based Condition Checker</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> TimeConditionChecker</span><span class="z-storage"> is</span><span class="z-entity z-name"> IConditionChecker</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isConditionMet</span><span>(</span><span class="z-support">address</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> conditionData</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"> 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-support"> uint256</span><span> unlockTime </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>conditionData</span><span>,</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> unlockTime</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>Condition-checking mechanisms (e.g., Merkle roots, timestamps) must be secure against tampering.</p> <p>The <code>claim()</code> function must ensure atomic verification of all conditions.</p> <p>Replay attacks must be mitigated using unique binding IDs and expiration fields.</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-07-23T00:00:00+00:00 2026-02-11T14:48:25+00:00 Aryaethnhttps://github.com/aryaethn https://wg-eips.ritovision.com/7992/

Interfaces for registering ML model commitments and verifying zero-knowledge proofs of their inferences on-chain.

<h2 id="abstract">Abstract</h2> <p>This ERC standardizes how smart contracts reference machine-learning (ML) models and accept zero-knowledge attestations of their inferences. It defines a registry that issues a <code>modelId</code> for a <code>ModelCommitment</code>, hashes of the model’s weights/architecture, proving circuit/AIR, and verifying key, along with a <code>proofSystemId</code> for the proving system, and exposes discoverability via <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>. A verifier interface provides <code>verifyInference(modelId, inputCommitment, output, proof)</code>: it retrieves the model commitment, dispatches verification to the declared proof system, and reverts on any mismatch or invalid proof; success implies validity and emits <code>InferenceVerified</code>. Inputs are bound by domain-separated commitments (nonceable for replay protection), outputs are ABI-encoded bytes whose schema can be application-defined or additionally committed on-chain, and proof systems (e.g., Groth16/Plonk/STARK) are pluggable without ABI changes. An optional extension persists verified inference records to enable auditability and deterministic settlement.</p> <h2 id="motivation">Motivation</h2> <p>Smart contracts can’t run large ML models, and they can’t trust an oracle’s claim about a model’s output. Today, projects either (1) trust a centralized server, (2) cripple models to fit on-chain, or (3) rely on social committees. None provide cryptographic assurance.</p> <p>Zero-knowledge ML (ZKML) fixes the trust gap by letting a prover show—succinctly and privately—that a specific model, with specific inputs, produced a specific output. But without a shared interface, every dApp/verifier pair is bespoke: different ABIs, different registry schemas, poor composability.</p> <p>This ERC standardizes that on-chain boundary:</p> <ul> <li>Registry: publish immutable commitments to model weights/architecture/circuits so callers know exactly which model they’re referencing.</li> <li>Verifier: a uniform function to validate inference proofs, independent of proof system (Groth16, Plonk, STARKs, …).</li> </ul> <p>Benefits include:</p> <ul> <li>Trustless, composable “AI oracles” for DeFi risk, prediction markets, insurance, etc.</li> <li>Protection of proprietary models and private inputs while still guaranteeing correctness.</li> <li>Deterministic, dispute-free settlement for complex computations.</li> <li>Lower integration and audit overhead via consistent events, structs, and revert semantics.</li> <li>Future-proofing as proving systems evolve—only implementations change, not integrators.</li> <li>Clear security expectations (e.g., nonce usage to prevent replays) baked into the spec.</li> </ul> <p>In short, this ERC turns verifiable ML inference into a reusable primitive—doing for AI outputs what <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>/<a href="https://wg-eips.ritovision.com/721/">ERC-721</a> did for assets.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="terminology-ids">Terminology &amp; IDs</h3> <ul> <li>Model Commitment: A bundle of hashes that ties together the model’s weights, architecture, proving circuit/Algebraic intermediate representation (AIR), and verifying key.</li> <li><code>modelId</code> (<code>uint256</code>): A unique identifier returned by the registry upon model registration.</li> <li><code>inputCommitment</code> (<code>bytes32</code>): A hash commitment to all private inputs (and any declared public inputs) for an inference. Implementations MUST domain-separate and SHOULD include a nonce/salt when single-use or non-deterministic behavior is possible.</li> <li><code>output</code> (<code>bytes</code>): ABI-encoded public outputs of the inference. Consumers MUST agree on its schema and MAY validate it via an outputCommitment (not included in the minimal interface).</li> <li><code>proof</code> (<code>bytes</code>): The ZK proof blob.</li> <li><code>proofSystemId</code> (<code>bytes4</code>): Identifier of the proving system + curve + version used by the circuit.</li> </ul> <p><code>proofSystemId</code> MUST equal the first four bytes of:</p> <p><code>bytes4(keccak256(abi.encodePacked(&lt;canonical-proof-system-name-and-version&gt;)))</code></p> <p>Where <code>&lt;canonical-proof-system-name-and-version&gt;</code> is a lowercase, hyphen-separated string, e.g.:</p> <ul> <li>"groth16-bn254-v1"</li> <li>"plonk-bn254-v2"</li> <li>"stark-airfoo-v1"</li> </ul> <p>This method ensures deterministic, collision-resistant identifiers across implementations.</p> <h3 id="interfaces">Interfaces</h3> <h4 id="zkml-registry">ZKML Registry</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.20</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"> IERCZKMLRegistry</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC165 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> ModelCommitment</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> modelHash</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> weights + architecture hash</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> circuitHash</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> arithmetic circuit / AIR hash</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> vkHash</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> verifying key hash</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span> proofSystemId</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> keccak-based identifier</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"> optional off-chain metadata (IPFS/HTTP)</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"> ModelRegistered</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"> modelId</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-variable"> ModelCommitment</span><span class="z-variable"> commitment</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"> ModelUpdated</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"> modelId</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> ModelCommitment</span><span class="z-variable"> oldCommitment</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> ModelCommitment</span><span class="z-variable"> newCommitment</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"> ModelDeprecated</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> modelId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ModelNotFound</span><span>(</span><span class="z-support">uint256</span><span> modelId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> NotModelOwner</span><span>(</span><span class="z-support">uint256</span><span> modelId</span><span>,</span><span class="z-support"> address</span><span> caller</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ModelDeprecated</span><span>(</span><span class="z-support">uint256</span><span> modelId</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"> registerModel</span><span>(</span><span class="z-storage z-type">ModelCommitment</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> commitment</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">uint256</span><span class="z-variable"> modelId</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"> updateModel</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> modelId</span><span>,</span><span class="z-storage z-type"> ModelCommitment</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> newCommitment</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-storage z-type"> function</span><span class="z-entity z-name"> deprecateModel</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> modelId</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"> getModel</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> modelId</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">ModelCommitment</span><span class="z-storage z-type"> memory</span><span class="z-variable"> commitment</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> deprecated</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>}</span></span></code></pre> <ul> <li><code>registerModel</code> MUST return a unique <code>modelId</code>.</li> <li><code>updateModel</code> and <code>deprecateModel</code> MUST only be callable by the model <code>owner</code>.</li> <li><code>getModel</code> MUST return the current <code>commitment</code>, deprecation status, and <code>owner</code> address.</li> <li>Implementations MAY allow versioning under one <code>modelId</code> or require a new <code>modelId</code> per change. The chosen policy MUST be documented.</li> </ul> <h4 id="zkml-verifier">ZKML Verifier</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.20</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"> IERCZKMLVerifier</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC165 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> InferenceVerified</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"> modelId</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"> inputCommitment</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> output</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"> caller</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"> error</span><span class="z-entity z-name"> InvalidProof</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ModelMismatch</span><span>(</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> proof verifies but not tied to given modelId</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> InputCommitmentMismatch</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> OutputMismatch</span><span>(</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> if verifier checks output commitment/schema</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> UnsupportedProofSystem</span><span>(</span><span class="z-support">bytes4</span><span> proofSystemId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> VerificationRefused_ModelDeprecated</span><span>(</span><span class="z-support">uint256</span><span> modelId</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"> Verifies a ZK proof for an inference.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert on any failure path. Successful execution implies validity.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> modelId</span><span class="z-comment"> Registry model identifier</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> inputCommitment</span><span class="z-comment"> Commitment to private inputs</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> output</span><span class="z-comment"> ABI-encoded public outputs</span></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"> ZK proof bytes</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"> verifyInference</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> modelId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> inputCommitment</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"> output</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"> proof</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"> Optional helper views:</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> proofSystemOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> modelId</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">bytes4</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registry</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"> registryAddress</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>verifyInference</code>:</p> <ul> <li>MUST fetch the model <code>commitment</code> from the registry and validate the <code>proof</code> against it.</li> <li>MUST revert on any failure (invalid proof, mismatched commitments, unsupported proof system, deprecated model, etc.).</li> <li>SHOULD emit <code>InferenceVerified</code> on success.</li> <li>SHOULD remain stateless except for emitting events. Statefulness MAY be introduced by extensions.</li> </ul> <h4 id="optional-storage-extension">Optional Storage Extension</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.20</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"> IERCZKMLStorageExtension</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> InferenceStored</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> inferenceId</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"> Verify and store an inference record.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert on invalid proof.</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"> inferenceId</span><span class="z-comment"> keccak256(abi.encodePacked(modelId, inputCommitment, output))</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"> verifyAndStoreInference</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> modelId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> inputCommitment</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"> output</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"> proof</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">bytes32</span><span class="z-variable"> inferenceId</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"> getInference</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> inferenceId</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"> modelId</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> inputCommitment</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> output</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Replay Protection Note: Implementations that rely on <code>inferenceId = keccak256(modelId, inputCommitment, output)</code> MUST ensure that <code>inputCommitment</code> embeds a <code>nonce/salt</code> or other uniqueness source if replays are a concern (e.g., non-deterministic models or single-use inferences).</p> <p>The registry interface exposes an <code>owner</code> per <code>modelId</code>. Implementations MUST include some ownership/access-control mechanism (e.g., simple owner storage, <a href="https://wg-eips.ritovision.com/173/">ERC-173</a>, <a href="https://wg-eips.ritovision.com/173/">ERC-721</a> representation, or role-based control). The returned <code>owner</code> address SHOULD be treated as the canonical authority to mutate or deprecate that model.</p> <h2 id="rationale">Rationale</h2> <ul> <li>Void Return on <code>verifyInference</code>: Reverting on failure and returning nothing on success removes redundant gas-expensive booleans and matches modern Solidity patterns (e.g., OpenZeppelin’s <code>SafeERC20</code>).</li> <li>Separated Registry &amp; Verifier: Encourages modularity—teams can upgrade verifiers or registries independently.</li> <li>Opaque bytes for Proof/Output: Avoids lock-in to a specific proof system or output schema.</li> <li>Deterministic <code>proofSystemId</code>: Prevents collisions and ambiguity; enables predictable dispatch in mixed-system verifiers.</li> <li>Nonce in <code>inputCommitment</code>: Explicitly mitigates replay attacks when inference uniqueness matters.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Fully backwards compatible:</p> <ul> <li>Uses <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> like popular <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> for discoverability.</li> <li>No dependency on token ownership standards; minimal collision with existing protocols.</li> </ul> <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"> ^0.8.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;./IERCZKMLRegistry.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERCZKMLVerifier.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"> ZKMLVerifier</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERCZKMLVerifier</span><span> {</span></span> <span class="giallo-l"><span> IERCZKMLRegistry </span><span class="z-storage z-type">public</span><span class="z-storage z-type"> immutable</span><span class="z-storage z-type"> override</span><span> registry</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">IERCZKMLRegistry</span><span class="z-variable z-parameter z-function"> _registry</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> registry </span><span class="z-keyword">=</span><span> _registry</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"> verifyInference</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> modelId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> inputCommitment</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"> output</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"> proof</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> {</span></span> <span class="giallo-l"><span> (</span><span>IERCZKMLRegistry</span><span>.</span><span>ModelCommitment </span><span class="z-storage z-type">memory</span><span> cm</span><span>,</span><span class="z-support"> bool</span><span> deprecated</span><span>,</span><span>)</span><span class="z-keyword"> =</span></span> <span class="giallo-l"><span> registry</span><span>.</span><span class="z-entity z-name">getModel</span><span>(</span><span>modelId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>deprecated</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> ModelDeprecated</span><span>(</span><span>modelId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Dispatch based on proofSystemId. Example only.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> bool ok = VerifierLib.verify(proof, cm.vkHash, inputCommitment, output);</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> ok </span><span class="z-keyword">=</span><span class="z-entity z-name"> _dummyVerify</span><span>(</span><span>proof</span><span>,</span><span> cm</span><span>.</span><span>vkHash</span><span>,</span><span> inputCommitment</span><span>,</span><span> output</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>ok</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> InvalidProof</span><span>(</span><span>)</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"> InferenceVerified</span><span>(</span><span>modelId</span><span>,</span><span> inputCommitment</span><span>,</span><span> output</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"> function</span><span class="z-entity z-name"> proofSystemOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> modelId</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"> 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> (</span><span>IERCZKMLRegistry</span><span>.</span><span>ModelCommitment </span><span class="z-storage z-type">memory</span><span> cm</span><span>,</span><span>,</span><span>)</span><span class="z-keyword"> =</span><span> registry</span><span>.</span><span class="z-entity z-name">getModel</span><span>(</span><span>modelId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> cm</span><span>.</span><span>proofSystemId</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"> _dummyVerify</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</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"> private</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></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <h3 id="security">Security</h3> <!-- Editor's Note: any requirements (defined with UPPERCASE keywords) should go in the specification section, but they should be discussed here in more detail. --> <ul> <li>Replay Attacks: Inputs must embed a nonce/salt where uniqueness matters. Contracts may also track consumed <code>inferenceIds</code>.</li> <li>Model Commitment Drift: Updating commitments can invalidate proofs; consumers should pin specific <code>modelId</code> + <code>commitment</code> hashes or check deprecated.</li> <li>Hash Domain Separation: Use distinct prefixes (e.g., "ZKML_MODEL_V1") to avoid collisions across contexts.</li> <li>Output Ambiguity: Contracts must validate or commit to output schemas to avoid maliciously crafted bytes.</li> <li>DoS via Heavy Verification: Consider off-chain verification with on-chain succinct attestations, or batching/aggregation.</li> </ul> <h3 id="gas">Gas</h3> <ul> <li>Proof verification can dominate gas costs; splitting verification-only calls from storage writes lets integrators choose.</li> <li>Events are cheaper than persistent storage for audit trails.</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> 2025-07-08T00:00:00+00:00 2026-02-11T14:48:26+00:00 0xMostafashttps://github.com/MostafaS0xmostafas@proton.me https://wg-eips.ritovision.com/7988/

A smart‑wallet interface for EIP‑7702 account‑code delegation.

<h2 id="abstract">Abstract</h2> <p>Minimal Avatar Smart Wallet (MASW) is an immutable delegate‑wallet that any EOA can designate via <a href="https://wg-eips.ritovision.com/7702/">EIP‑7702</a> (txType <code>0x04</code>). Once designated, the wallet's code remains active for every subsequent transaction until the owner sends a new <code>0x04</code> to clear or replace it. During each delegated call the EOA is the avatar and MASW's code executes as the delegate at the same address, enabling atomic batched calls (<a href="https://wg-eips.ritovision.com/712/">EIP‑712</a> signed) and optional sponsor gas reimbursement in ETH or <a href="https://wg-eips.ritovision.com/20/">ERC‑20</a>.</p> <p>The contract offers one primary function, <code>executeBatch</code>, plus two plug‑in hooks: a Policy Module for pre/post guards and a Recovery Module for alternate signature validation. Replay attacks are prevented by a global metaNonce, an expiry, and a chain‑bound <code>EIP‑712</code> domain separator. Standardising this seven‑parameter ABI removes wallet fragmentation while still allowing custom logic through modules.</p> <h2 id="motivation">Motivation</h2> <p>A single‑transaction code‑injection model (EIP‑7702) grants EOAs full implementation freedom, but unconstrained diversity would impose high coordination costs:</p> <ul> <li><strong>Interoperability</strong> – Divergent ABIs and fee‑settlement conventions force dApps and relayers to maintain per‑wallet adapters, increasing integration complexity and failure modes.</li> <li><strong>Economic alignment</strong> – Gas‑sponsorship relies on deterministic fee‑reimbursement paths; heterogeneity erodes relayer incentives and throttles sponsored‑transaction volume.</li> <li><strong>Tooling precision</strong> – Indexers, debuggers, and static‑analysis frameworks achieve optimal decoding and gas estimation when targeting a single, fixed byte‑code and seven‑field call schema.</li> <li><strong>Extensibility focus</strong> – Constraining variability to two module boundaries (Policy, Recovery) localizes complexity, allowing research and hardening efforts to concentrate on higher‑level security primitives rather than re‑engineering core wallet logic.</li> </ul> <p>By standardising the immutable byte‑code, signature domain, and minimal ABI while exposing clearly defined extension hooks, MASW minimizes fragmentation and maximizes composability across the Ethereum tooling stack.</p> <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="overview-of-delegation-flow">Overview of Delegation Flow</h3> <ol> <li><strong>Deploy</strong> <code>MASW</code> with constructor argument <code>_owner = EOA</code>.</li> <li>The owner sends an EIP‑7702 transaction (txType <code>0x04</code>) referencing the contract's byte‑code hash.</li> <li>After that transaction the EOA acts as the <strong>avatar wallet</strong> while the MASW logic executes as the <strong>delegate wallet</strong> at the <em>same</em> address.</li> </ol> <h3 id="public-interface">Public Interface</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"> executeBatch</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"> targets</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"> values</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> calldatas</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> token</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> fee</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> expiry</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"> signature</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"> setPolicyModule</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newModule</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"> setRecoveryModule</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newModule</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">event</span><span class="z-entity z-name"> BatchExecuted</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> structHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> ModuleChanged</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> kind</span><span>, </span><span class="z-support">address</span><span class="z-variable"> oldModule</span><span>, </span><span class="z-support">address</span><span class="z-variable"> newModule</span><span>)</span><span>;</span></span></code></pre><h3 id="transaction-type-hash">Transaction Type Hash</h3> <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"> constant</span><span> BATCH_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;Batch(address[] targets,uint256[] values,bytes[] calldatas,address token,uint256 fee,uint256 exp,uint256 metaNonce)&quot;</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h3 id="storage-layout">Storage Layout</h3> <table><thead><tr><th style="text-align: right">Slot</th><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td style="text-align: right">0</td><td><code>metaNonce</code></td><td>uint256</td><td>Monotonically increasing meta‑nonce</td></tr> <tr><td style="text-align: right">1</td><td><code>_entered</code></td><td>uint256</td><td>Re‑entrancy guard flag</td></tr> <tr><td style="text-align: right">2</td><td><code>policyModule</code></td><td>address</td><td>Optional <code>IPolicyModule</code> (zero = none)</td></tr> <tr><td style="text-align: right">3</td><td><code>recoveryModule</code></td><td>address</td><td>Optional <code>IRecoveryModule</code> (zero = none)</td></tr> </tbody></table> <p><code>owner</code> and <code>DOMAIN_SEPARATOR</code> are <code>immutable</code> and occupy no storage slots.</p> <h3 id="domain-separator-construction">Domain Separator Construction</h3> <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">&quot;EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)&quot;</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;MASW&quot;</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;1&quot;</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-language"> block</span><span>.</span><span>chainid</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> MUST be the live chain‑ID; using 0 is disallowed</span></span> <span class="giallo-l"><span> _owner </span><span class="z-comment">//</span><span class="z-comment"> keeps separator stable before &amp; after delegation</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h3 id="batch-execution-executebatch">Batch Execution (<code>executeBatch</code>)</h3> <table><thead><tr><th>Stage</th><th>Behaviour</th></tr></thead><tbody> <tr><td><strong>Validation</strong></td><td>‑ <code>targets.length == values.length == calldatas.length &gt; 0</code><br>‑ <code>block.timestamp ≤ expiry</code><br>‑ <code>metaNonce</code> matches then increments<br>‑ <code>EIP712</code> digest recovers <code>owner</code> <strong>or</strong> is approved by <code>recoveryModule</code></td></tr> <tr><td><strong>Policy pre‑hook</strong></td><td>If <code>policyModule != address(0)</code>, <code>preCheck</code> <strong>MUST</strong> return <code>true</code>; a revert or <code>false</code> vetoes the batch</td></tr> <tr><td><strong>Calls</strong></td><td>For each index <em>i</em>: <code>targets[i].call{value:values[i]}(calldatas[i])</code>; revert on first failure</td></tr> <tr><td><strong>Policy post‑hook</strong></td><td>Same semantics as pre‑hook</td></tr> <tr><td><strong>Fee reimbursement</strong></td><td>If <code>fee &gt; 0</code>: native transfer (<code>token == address(0)</code>) or <code>ERC20</code> <code>transfer</code> with OpenZeppelin‑style return‑value check <!-- TODO --></td></tr> <tr><td><strong>Emit</strong></td><td><code>BatchExecuted(structHash)</code></td></tr> </tbody></table> <h4 id="gas-sponsorship">Gas Sponsorship</h4> <p>The relayer and owner agree off‑chain on <code>(token, fee)</code> prior to submission.<br /> Because the fee is part of the signed batch, a relayer cannot unilaterally raise it.<br /> If a rival relayer broadcasts the same signed batch first, they earn the fee and the original relayer's transaction reverts—aligning incentives naturally.<br /> Relayers <strong>MUST</strong> confirm the avatar's balance up‑front; insufficient funds render the transaction invalid in the mem‑pool.</p> <h3 id="modules">Modules</h3> <h4 id="policy-module">Policy Module</h4> <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"> IPolicyModule</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> preCheck</span><span> (</span><span class="z-support">address</span><span class="z-variable"> sender</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> rawData</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-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"> postCheck</span><span>(</span><span class="z-support">address</span><span class="z-variable"> sender</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> rawData</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-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li>A module <strong>MAY</strong> veto by reverting <em>or</em> by returning <code>false</code>.</li> <li>The <code>value</code> parameter represents the total ETH sent with the transaction (<code>msg.value</code>), allowing the policy module to validate this against the batch requirements contained in <code>rawData</code>.</li> <li>Aggregator designs are encouraged: forward to child policies and stop on first failure (revert or return <code>false</code>).</li> </ul> <h4 id="recovery-module">Recovery Module</h4> <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"> IRecoveryModule</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isValidSignature</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> hash</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> sig</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">bytes4</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Must return <code>0x1626ba7e</code>.</p> <h3 id="nonce-race-consideration">Nonce‑Race Consideration</h3> <p>A single global <code>metaNonce</code> is used. Two relayers submitting the same nonce concurrently results in one success and one revert. The <code>expiry</code> field (wallets typically set ≤ 30 s) makes such races low‑impact, but UIs should surface the failure.</p> <h2 id="rationale">Rationale</h2> <ul> <li><strong>Immutable logic</strong> minimizes upgrade risk; a new version requires an explicit 7702 <code>0x04</code> call.</li> <li>A <strong>two‑module</strong> boundary captures common customizations without growing byte‑code.</li> <li>No hard <code>maxTargets</code>; advanced users can bundle many calls, while conservative users install a size‑capping Policy module.</li> <li>Domain separator binds the real <code>chainId</code> to mitigate cross‑chain replays.</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>Reference implementation can be found here <a href="https://wg-eips.ritovision.com/7988/./assets/MASW.sol"><code>MASW.sol</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <table><thead><tr><th>Threat</th><th>Mitigation</th></tr></thead><tbody> <tr><td>Same‑chain replay</td><td>Global <code>metaNonce</code></td></tr> <tr><td>Cross‑chain replay</td><td>Chain‑bound domain separator</td></tr> <tr><td>Fee grief / over‑charge</td><td>Fee is part of signed data; front‑running risk sits with relayer</td></tr> <tr><td>Batch gas grief</td><td>Optional Policy can reject oversized batches</td></tr> <tr><td><code>ERC20</code> non‑standard returns</td><td>OpenZeppelin <code>SafeERC20</code> transfer check</td></tr> <tr><td>Re‑entrancy</td><td><code>nonReentrant</code> guard; state mutated only before external calls (nonce++) and after (fee transfer)</td></tr> <tr><td>Malicious Module</td><td>Core logic immutable; swapping modules needs an owner‑signed tx</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> 2025-07-07T00:00:00+00:00 2026-04-25T12:06:20+00:00 raffy.ethhttps://github.com/adraffy https://wg-eips.ritovision.com/7996/

Method to publish and detect contract features that lack an ERC-165 interface

<h2 id="abstract">Abstract</h2> <p>Creates a standard method <code>supportsFeature(bytes4)</code> in the same spirit as <code>supportsInterface(bytes4)</code> to publish and detect what features a smart contract implements that lack a derivable <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum Name Service (ENS) has maintained backwards compatibility with contracts created in 2016 through extensive use of ERC-165. Unfortunately, not all contract capabilities can be expressed through an unique interface.</p> <p>Features allow expression of contract capabilities that preserve existing interfaces. This proposal standardizes the concept of features and standardizes the identification (naming) of features.</p> <p>Defining a new standard avoids unnecessary pollution of the ERC-165 selector namespace with synthetic interfaces representing features.</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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="how-features-are-identified">How Features are Identified</h3> <p>For this standard, a <em>feature</em> is any property of a contract that cannot be expressed via ERC-165.</p> <p>A feature name SHOULD be a reverse domain name that uniquely defines its implication, eg. <code>eth.ens.resolver.extended.multicall</code> is the multicall feature for an extended ENS resolver contract.</p> <p>A feature identifier is defined as the first four-bytes of the keccak256-hash of its name, eg. <code>bytes4(keccak256("eth.ens.resolver.extended.multicall")) = 0x96b62db8</code>.</p> <h3 id="how-a-contract-will-publish-the-features-it-implements">How a Contract will Publish the Features it Implements</h3> <p>A contract that is compliant with this specification SHALL 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"> IERC7996</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"> Check if a feature is supported.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> featureId</span><span class="z-comment"> The feature identifier.</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 feature is supported by the contract.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsFeature</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> featureId</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 ERC-165 interface identifier for this interface is <code>0x582de3e7</code>.</p> <h3 id="how-to-detect-if-a-contract-implements-features">How to Detect if a Contract Implements Features</h3> <ol> <li>Check if the contract supports the interface above according to <a href="https://wg-eips.ritovision.com/165/#how-to-detect-if-a-contract-implements-erc-165">ERC-165</a>.</li> </ol> <h3 id="how-to-detect-if-a-contract-implements-any-given-feature">How to Detect if a Contract Implements any Given Feature</h3> <ol> <li>If you are not sure if the contract implements features, use the above procedure to confirm.</li> <li>If it implements features, then call <code>supportsFeature(featureId)</code> to determine if it implements the desired feature.</li> </ol> <p>Note: a contract that implements features MAY implement no features.</p> <h2 id="rationale">Rationale</h2> <p>Since feature names cannot be derived from a contract interface, they are derived from a reverse domain name to reduce collisions and permit a human-readable representention that briefly describes its implication.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Callers unaware of features or any specific feature experience no change in behavior.</p> <p>ENS already implements this ERC.</p> <h2 id="security-considerations">Security Considerations</h2> <p>As with ERC-165, declaring support for a feature does not guarantee that the contract implements 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> 2025-07-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Aryeh Greenberghttps://github.com/arr00 Ernesto Garcíahttps://github.com/ernestognw Hadrien Crouboishttps://github.com/Amxx Ghazi Ben Amorhttps://github.com/GBAZama Clement Danjouhttps://github.com/immortal-tofu Joseph Andre Turkhttps://github.com/jatZama Silas Davishttps://github.com/silasdavis Nicolas Pasquierhttps://github.com/npasquie https://wg-eips.ritovision.com/7984/

Confidential fungible tokens use an account-based accounting model while maintaining the confidentiality of transfer amounts and balances.

<h2 id="abstract">Abstract</h2> <p>The following standard describes confidential fungible tokens via pointers. All amounts in this standard are represented by confidential pointers; therefore, balances and transfer amounts are confidential. Pointers refer to data stored elsewhere--onchain or offchain. The logistics of pointer resolution, operation, and location are implementation specific. The interface defines functions to transfer tokens with pointers, as well as approve operators, allowing the token to be transferred by a third party.</p> <h2 id="motivation">Motivation</h2> <p>Confidential tokens enable private value transfer which is vital for many usecases such as payroll, confidential DeFi, institutional settlement, and more. A standard interface allows pointer based confidential tokens on Ethereum to be reused by other applications: from privacy-focused wallets to decentralized exchanges, while keeping transaction amounts private from public view.</p> <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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="nomenclature">Nomenclature</h3> <p>All amounts in this ERC are pointer based amounts represented by <code>bytes32</code> pointers unless otherwise specified. The resolution and manipulation of these pointers is implementation specific.</p> <h3 id="token">Token</h3> <p>Compliant tokens MUST implement <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>. The <code>supportsInterface</code> function MUST return <code>true</code> if <code>0x4958f2a4</code> is passed through the <code>interfaceID</code> argument.</p> <h3 id="methods">Methods</h3> <p>Compliant tokens MUST implement the following methods, unless otherwise specified:</p> <ul> <li><h4 id="name"><code>name()</code></h4> <p>Returns the name of the token - e.g. <code>"MyConfidentialToken"</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"> 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></code></pre></li> <li><h4 id="symbol"><code>symbol()</code></h4> <p>Returns the symbol of the token - e.g. <code>"MCT"</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"> 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></code></pre></li> <li><h4 id="decimals"><code>decimals()</code></h4> <p>Returns the number of decimals the token uses (e.g. <code>6</code>) as a plaintext <code>uint8</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"> decimals</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></code></pre></li> <li><h4 id="contracturi"><code>contractURI()</code></h4> <p>Returns the metadata URI for the token. SHOULD follow the schema defined in <a href="https://wg-eips.ritovision.com/7572/">ERC-7572</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"> contractURI</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></code></pre></li> <li><h4 id="confidentialtotalsupply"><code>confidentialTotalSupply()</code></h4> <p>Returns the total token supply.</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"> confidentialTotalSupply</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></code></pre></li> <li><h4 id="confidentialbalanceof-address"><code>confidentialBalanceOf(address)</code></h4> <p>Returns the balance of <code>account</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"> confidentialBalanceOf</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">bytes32</span><span>)</span></span></code></pre></li> <li><h4 id="isoperator-address-address"><code>isOperator(address,address)</code></h4> <p>Returns <code>true</code> if <code>spender</code> is currently authorized to transfer tokens on behalf of <code>holder</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"> isOperator</span><span>(</span><span class="z-support">address</span><span class="z-variable"> holder</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> spender</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></li> <li><h4 id="setoperator-address-uint48"><code>setOperator(address,uint48)</code></h4> <p>Authorizes <code>operator</code> to transfer tokens on behalf of the caller until timestamp <code>until</code>--passed as a plaintext <code>uint48</code>. An operator may transfer any amount of tokens on behalf of a holder while approved. Accounts may have multiple simultaneous operators.</p> <p>MUST emit the <code>OperatorSet</code> 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"> setOperator</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> uint48</span><span class="z-variable"> until</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre></li> <li><h4 id="confidentialtransfer-address-bytes32"><code>confidentialTransfer(address,bytes32)</code></h4> <p>Transfers <code>amount</code> of tokens to address <code>to</code>. The function MAY revert if the caller's balance does not have enough tokens to spend.</p> <p>Returns the actual amount that was transferred.</p> <p>MUST emit the <code>ConfidentialTransfer</code> 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"> confidentialTransfer</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"> amount</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></code></pre></li> <li><h4 id="confidentialtransfer-address-bytes32-bytes"><code>confidentialTransfer(address,bytes32,bytes)</code></h4> <p>Transfers <code>amount</code> of tokens to address <code>to</code>. The function MAY revert if the caller's balance does not have enough tokens to spend.</p> <p>The <code>data</code> parameter contains implementation-specific information such as cryptographic proofs.</p> <p>Returns the actual amount that was transferred.</p> <p>MUST emit the <code>ConfidentialTransfer</code> 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"> confidentialTransfer</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"> amount</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-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span></span></code></pre></li> <li><h4 id="confidentialtransferfrom-address-address-bytes32"><code>confidentialTransferFrom(address,address,bytes32)</code></h4> <p>Transfers <code>amount</code> of tokens from address <code>from</code> to address <code>to</code>. The function MAY revert if the <code>from</code>'s account balance does not have enough tokens to spend.</p> <p>Returns the actual amount that was transferred.</p> <p>MUST revert if the caller is not an operator for <code>from</code>.</p> <p>MUST emit the <code>ConfidentialTransfer</code> 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"> confidentialTransferFrom</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"> bytes32</span><span class="z-variable"> amount</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-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span></span></code></pre></li> <li><h4 id="confidentialtransferfrom-address-address-bytes32-bytes"><code>confidentialTransferFrom(address,address,bytes32,bytes)</code></h4> <p>Transfers <code>amount</code> of tokens from address <code>from</code> to address <code>to</code>. The function MAY revert if the <code>from</code>'s account balance does not have enough tokens to spend.</p> <p>The <code>data</code> parameter contains implementation-specific information such as cryptographic proofs.</p> <p>Returns the actual amount that was transferred.</p> <p>MUST revert if the caller is not an operator for <code>from</code>.</p> <p>MUST emit the <code>ConfidentialTransfer</code> 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"> confidentialTransferFrom</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"> bytes32</span><span class="z-variable"> amount</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-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span></span></code></pre></li> <li><h4 id="confidentialtransferandcall-address-bytes32-bytes"><code>confidentialTransferAndCall(address,bytes32,bytes)</code></h4> <p>Transfers <code>amount</code> of tokens to address <code>to</code>. The function MAY revert if the caller's balance does not have enough tokens to spend.</p> <p>The <code>data</code> parameter contains implementation-specific information such as cryptographic proofs.</p> <p>See <a href="https://wg-eips.ritovision.com/7984/#callback-details">Callback Details</a> below for details on the callback flow.</p> <p>Returns the actual amount that was transferred.</p> <p>MUST emit the <code>ConfidentialTransfer</code> 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"> confidentialTransferAndCall</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"> amount</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> callData</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></code></pre></li> <li><h4 id="confidentialtransferandcall-address-bytes32-bytes-bytes"><code>confidentialTransferAndCall(address,bytes32,bytes,bytes)</code></h4> <p>Transfers <code>amount</code> of tokens to address <code>to</code>. The function MAY revert if the caller's balance does not have enough tokens to spend.</p> <p>The <code>data</code> parameter contains implementation-specific information such as cryptographic proofs.</p> <p>See <a href="https://wg-eips.ritovision.com/7984/#callback-details">Callback Details</a> below for details on the callback flow.</p> <p>Returns the actual amount that was transferred.</p> <p>MUST emit the <code>ConfidentialTransfer</code> 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"> confidentialTransferAndCall</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"> amount</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-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> callData</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></code></pre></li> <li><h4 id="confidentialtransferfromandcall-address-address-bytes32-bytes"><code>confidentialTransferFromAndCall(address,address,bytes32,bytes)</code></h4> <p>Transfers <code>amount</code> of tokens from address <code>from</code> to address <code>to</code>. The function MAY revert if the <code>from</code>'s account balance does not have enough tokens to spend.</p> <p>See <a href="https://wg-eips.ritovision.com/7984/#callback-details">Callback Details</a> below for details on the callback flow.</p> <p>Returns the actual amount that was transferred.</p> <p>MUST revert if the caller is not an operator for <code>from</code>.</p> <p>MUST emit the <code>ConfidentialTransfer</code> 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"> confidentialTransferFromAndCall</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"> bytes32</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> callData</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></code></pre></li> <li><h4 id="confidentialtransferfromandcall-address-address-bytes32-bytes-bytes"><code>confidentialTransferFromAndCall(address,address,bytes32,bytes,bytes)</code></h4> <p>Transfers <code>amount</code> of tokens from address <code>from</code> to address <code>to</code>. The function MAY revert if the <code>from</code>'s account balance does not have enough tokens to spend.</p> <p>The <code>data</code> parameter contains implementation-specific information such as cryptographic proofs.</p> <p>See <a href="https://wg-eips.ritovision.com/7984/#callback-details">Callback Details</a> below for details on the callback flow.</p> <p>Returns the actual amount that was transferred.</p> <p>MUST revert if the caller is not an operator for <code>from</code>.</p> <p>MUST emit the <code>ConfidentialTransfer</code> 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"> confidentialTransferFromAndCall</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"> bytes32</span><span class="z-variable"> amount</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-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> callData</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></code></pre></li> </ul> <h3 id="events">Events</h3> <ul> <li><h4 id="confidentialtransfer">ConfidentialTransfer</h4> <p>MUST trigger when confidential tokens are transferred, including zero value transfers.</p> <p>A token contract which creates new tokens SHOULD trigger a ConfidentialTransfer event with the <code>from</code> address set to <code>0x0</code> when tokens are 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"> ConfidentialTransfer</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">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> amount</span><span>)</span></span></code></pre></li> <li><h4 id="operatorset">OperatorSet</h4> <p>MUST trigger on any successful call to <code>setOperator</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"> OperatorSet</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> holder</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">uint48</span><span class="z-variable"> until</span><span>)</span></span></code></pre></li> <li><h4 id="amountdisclosed">AmountDisclosed</h4> <p>SHOULD trigger when a pointer amount is publicly disclosed through implementation-specific mechanisms.</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"> AmountDisclosed</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> handle</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span></span></code></pre></li> </ul> <h3 id="callback-details">Callback Details</h3> <p>Transfer functions suffixed with <code>andCall</code> execute a callback to the <code>to</code> address AFTER all transfer logic is completed. The callback calls the <code>onConfidentialTransferReceived</code> function with the transfer initiator (operator), from address, actual amount sent, and given <code>callData</code> bytes (the last parameter for <code>andCall</code> functions). The callback flow is as follows:</p> <ul> <li>If <code>address(to).code.length == 0</code> the callback is a no-op and returns successfully.</li> <li>Call <a href="https://wg-eips.ritovision.com/7984/#onconfidentialtransferreceived"><code>onConfidentialTransferReceived(address, address, bytes32, bytes)</code></a> on <code>to</code>.</li> <li>If the function call reverts, revert.</li> <li>If the function call returns the false boolean, attempt to transfer back the tokens to the original holder and return.</li> </ul> <h3 id="contract-receivers">Contract Receivers</h3> <p>For a contract to receive a transfer with a callback, it MUST implement the <code>onConfidentialTransferReceived</code> function:</p> <h4 id="onconfidentialtransferreceived">onConfidentialTransferReceived</h4> <p>If the callback is unsuccessful, the function SHOULD revert or return a pointer to the false boolean.</p> <p>The token will attempt to return tokens from the receiver to the sender if false is returned. Note that this reversal may fail if the receiver spends tokens as part of the callback.</p> <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"> onConfidentialTransferReceived</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"> bytes32</span><span class="z-variable"> amount</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-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> success</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="technology-agnostic-design">Technology Agnostic Design</h3> <p>Using <code>bytes32</code> allows implementations using pointer based systems and privacy mechanisms including FHE systems, zero-knowledge proofs, secure enclaves, or future technologies to be compliant.</p> <h3 id="operator-model">Operator Model</h3> <p>Time-limited operators provide granular control while enabling DeFi protocol integration and natural permission expiration. This approach reduces the load on the external system by removing the need to track approval amounts.</p> <h3 id="data-parameter">Data Parameter</h3> <p>The <code>bytes calldata data</code> parameter in transfer functions allows implementations to include cryptographic proofs, access permissions, or other privacy-mechanism-specific information.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Security depends on the underlying pointer based mechanism. Implementations must guard against side-channel attacks and ensure proper key management for offchain operations.</p> <p>Token callbacks are associated with inherent security risks, including reentrancy and gas griefing. When utilizing callbacks, consider using reentrancy protection and setting a gas limit.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-07-02T00:00:00+00:00 2026-02-11T14:48:26+00:00 Marcelo Morgadohttps://github.com/marcelomorgado Manoj Patidarhttps://github.com/patidarmanoj10 https://wg-eips.ritovision.com/8000/

Allowing operating batch executions on behalf of non delegated EOAs

<h2 id="abstract">Abstract</h2> <p>This standard defines a contract interface that enables externally owned accounts (EOAs) to perform batch call executions via a standard Operator contract, without requiring them to delegate control or convert into smart contract accounts.</p> <h2 id="motivation">Motivation</h2> <p>The <a href="https://wg-eips.ritovision.com/7702/">ERC-7702</a> allows EOAs to become powerful smart contract accounts (SCA), which solves many UX issues, like the double <code>approve</code> + <code>transferFrom</code> transactions.<br /> While this new technology is still reaching wider adoption over time, we need a way to improve UX for the users that decide to not have code attached to their EOAs.<br /> This proposal introduces a lightweight, backward-compatible mechanism to enhance UX for such users. By leveraging a standardized Operator contract, EOAs can batch multiple contract calls into a single transaction—assuming the target contracts are compatible (i.e., implement the Operated pattern).</p> <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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="definitions">Definitions</h3> <ul> <li>Operator: The contract that executes calls on the sender's behalf.</li> <li>Operated: The contract that supports calls through the Operator.</li> </ul> <p>It's OPTIONAL but HIGHLY RECOMMENDED to have the <code>Operator</code> contract as a singleton.</p> <h3 id="operator">Operator</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.29</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"> IOperator</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Call</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> target</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> callData</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"> @notice</span><span class="z-comment"> Execute calls</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> calls</span><span class="z-comment"> An array of Call structs</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"> returnData</span><span class="z-comment"> An array of bytes containing the responses</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">Call</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> calls</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">bytes</span><span>[</span><span>]</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"> @notice</span><span class="z-comment"> The address which initiated the executions</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"> sender</span><span class="z-comment"> The actual sender of the calls</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> onBehalfOf</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"> sender</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="methods">Methods</h3> <p><code>execute</code> Execute the calls sent by the actual sender.</p> <p>MUST revert if any of the calls fail.<br /> MUST return data from the calls.</p> <p><code>onBehalfOf</code> Used by the target contract to get the actual caller.</p> <p>MUST return the actual <code>msg.sender</code> when called in the context of a call.<br /> MUST revert when called outside of the context of a call.</p> <h3 id="operated">Operated</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.29</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">Context</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/Context.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">IOperator</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./interfaces/IOperator.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"> Operated contract</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Supports calls through the Operator</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"> Operated</span><span class="z-storage"> is</span><span class="z-entity z-name"> Context</span><span> {</span></span> <span class="giallo-l"><span> IOperator </span><span class="z-storage z-type">public</span><span class="z-storage z-type"> immutable</span><span> operator</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"> operator_</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> operator </span><span class="z-keyword">=</span><span class="z-entity z-name"> IOperator</span><span>(</span><span>operator_</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"> @inheritdoc</span><span class="z-comment"> Context</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _msgSender</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</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-variable z-language">msg.sender</span><span class="z-keyword"> ==</span><span class="z-support"> address</span><span>(</span><span>operator</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> operator</span><span>.</span><span class="z-entity z-name">onBehalfOf</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-keyword"> return</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></code></pre> <p>Any contract can become compatible to execute the batch call by EOA using operator if it extends the <code>Operated</code> contract. The <code>Operated</code> contract overrides <code>_msgSender()</code> to return <code>operator.onBehalfOf()</code> when the call originates from the Operator. This ensures that the target contract recognizes the EOA initiating the batch execution, preserving correct sender context.</p> <p>This behavior fits well with the usage of the _msgSender() function from <a href="https://wg-eips.ritovision.com/2771/">ERC-2771</a>.</p> <h3 id="methods-1">Methods</h3> <p><code>_msgSender</code> Returns <code>msg.sender</code> or <code>operator.onBehalfOf()</code></p> <h2 id="rationale">Rationale</h2> <p>By having a trusted contract (<code>Operator</code>) that may act on behalf of the EOA wallet, this ERC provides batch call capabilities and keeps the EOA as the caller of the target contracts.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The main limitation of this ERC is that only contracts that implements the <code>Operated</code> logic will be able to receive calls through the <code>Operator</code>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="operator-1">Operator</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.29</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">TransientSlot</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/TransientSlot.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Address</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/Address.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">ReentrancyGuardTransient</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/ReentrancyGuardTransient.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IOperator</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./interfaces/IOperator.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"> Operator contract</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Allows standard EOAs to perform batch calls</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Operator</span><span class="z-storage"> is</span><span class="z-entity z-name"> IOperator</span><span>, </span><span class="z-entity z-name">ReentrancyGuardTransient</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span> TransientSlot </span><span class="z-keyword">for</span><span class="z-keyword"> *</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> Address</span><span class="z-keyword"> for</span><span class="z-entity z-name"> address</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> keccak256(abi.encode(uint256(keccak256(&quot;operator.actual.sender&quot;)) - 1)) &amp; ~bytes32(uint256(0xff))</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> MSG_SENDER_STORAGE </span><span class="z-keyword">=</span><span class="z-constant"> 0x0de195ebe01a7763c35bcc87968c4e65e5a5ea50f2d7c33bed46c98755a66000</span><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"> setMsgSender</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> MSG_SENDER_STORAGE</span><span>.</span><span class="z-entity z-name">asAddress</span><span>(</span><span>)</span><span>.</span><span class="z-entity z-name">tstore</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-constant"> _</span><span>;</span></span> <span class="giallo-l"><span> MSG_SENDER_STORAGE</span><span>.</span><span class="z-entity z-name">asAddress</span><span>(</span><span>)</span><span>.</span><span class="z-entity z-name">tstore</span><span>(</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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @inheritdoc</span><span class="z-comment"> IOperator</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> onBehalfOf</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"> _actualMsgSender</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> _actualMsgSender </span><span class="z-keyword">=</span><span> MSG_SENDER_STORAGE</span><span>.</span><span class="z-entity z-name">asAddress</span><span>(</span><span>)</span><span>.</span><span class="z-entity z-name">tload</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_actualMsgSender </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;outside-call-context&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-comment"> ///</span><span class="z-storage z-type"> @inheritdoc</span><span class="z-comment"> IOperator</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> <span class="giallo-l"><span class="z-storage z-type"> Call</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> calls_</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 class="z-storage z-type"> override</span><span class="z-entity z-name"> nonReentrant</span><span class="z-entity z-name"> setMsgSender</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 z-parameter z-function"> _returnData</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> _length </span><span class="z-keyword">=</span><span> calls_</span><span>.</span><span>length</span><span>;</span></span> <span class="giallo-l"><span> _returnData </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> bytes</span><span>[](</span><span class="z-variable z-parameter z-function">_length</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> _sumOfValues</span><span>;</span></span> <span class="giallo-l"><span> Call </span><span class="z-storage z-type">calldata</span><span> _call</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</span><span> i</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> _length</span><span>;</span><span> )</span><span> {</span></span> <span class="giallo-l"><span> _call </span><span class="z-keyword">=</span><span> calls_</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> _value </span><span class="z-keyword">=</span><span> _call</span><span>.</span><span>value</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> unchecked</span><span> {</span></span> <span class="giallo-l"><span> _sumOfValues </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span> _value</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> _returnData</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span> _call</span><span>.</span><span>target</span><span>.</span><span class="z-entity z-name">functionCallWithValue</span><span>(</span><span>_call</span><span>.</span><span>callData</span><span>,</span><span> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> unchecked</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>i</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"> require</span><span>(</span><span class="z-variable z-language">msg</span><span>.</span><span>value </span><span class="z-keyword">==</span><span> _sumOfValues</span><span>,</span><span class="z-string"> &quot;value-mismatch&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Worth noting that the usage of transient storage (<a href="https://wg-eips.ritovision.com/1153/">EIP-1153</a>) for storing the <code>msg.sender</code> is highly RECOMMENDED.</p> <h3 id="operated-1">Operated</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.29</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Context</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/Context.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IERC20</span><span>}</span><span class="z-keyword"> from</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> {</span><span class="z-entity z-name">IOperator</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./interfaces/IOperator.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Operated</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./Operated.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"> Operated contract</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Supports calls through the Operator</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> OperatorCompatible</span><span class="z-storage"> is</span><span class="z-entity z-name"> Operated</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> InsufficientBalance</span><span>(</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">address</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"> uint256</span><span>)</span><span>)</span><span class="z-storage z-type"> public</span><span> balance</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"> operator_</span><span>)</span><span class="z-entity z-name"> Operated</span><span>(</span><span>operator_) </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"> deposit</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token_</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"> payable</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>token_ </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"> revert</span><span class="z-entity z-name"> InvalidToken</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> _sender </span><span class="z-keyword">=</span><span class="z-entity z-name"> _msgSender</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC20</span><span>(</span><span>token_</span><span>)</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span>_sender</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> amount_</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> balance</span><span>[</span><span>token_</span><span>]</span><span>[</span><span>_sender</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</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"> withdraw</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token_</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> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>token_ </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"> revert</span><span class="z-entity z-name"> InvalidToken</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> _sender </span><span class="z-keyword">=</span><span class="z-entity z-name"> _msgSender</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>balance</span><span>[</span><span>token_</span><span>]</span><span>[</span><span>_sender</span><span>]</span><span class="z-keyword"> &lt;</span><span> amount_</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> InsufficientBalance</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> balance</span><span>[</span><span>token_</span><span>]</span><span>[</span><span>_sender</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> amount_</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC20</span><span>(</span><span>token_</span><span>)</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>_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></span> <span class="giallo-l"></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <ul> <li>The <code>execute</code> function MUST implement reentracy control to avoid having a callback call overriding the sender's storage.</li> <li>The <code>Operated</code> contract MUST interact with a trusted <code>Operator</code> 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> 2025-06-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 James Kemptonhttps://github.com/SirSpudlington https://wg-eips.ritovision.com/7980/

Adds an EIP-7932 algorithm type for Ed25519 support of type `0x0`

<h2 id="abstract">Abstract</h2> <p>This EIP adds a new <a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a> algorithm of type <code>0x0</code> for supporting Ed25519 signatures.</p> <h2 id="motivation">Motivation</h2> <p>Ed25519 is one of the most widely used forms of Elliptic Curve Cryptography and is one of the defaults for SSH keys, this makes it a good contender to be able to sign transactions with. It also provides an algorithm to write test cases against during the implementation phase of <a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a>.</p> <h2 id="specification">Specification</h2> <p>This EIP defines a new <a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a> algorithmic type with the following parameters:</p> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>ALG_TYPE</code></td><td><code>Bytes1(0x0)</code></td></tr> <tr><td><code>GAS_PENALTY</code></td><td><code>1000</code></td></tr> <tr><td><code>MAX_SIZE</code></td><td><code>96</code></td></tr> </tbody></table> <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"> verify</span><span>(</span><span class="z-variable z-parameter z-function">signature_info</span><span>:</span><span class="z-support"> bytes</span><span>,</span><span class="z-variable z-parameter z-function"> payload_hash</span><span>:</span><span> Hash32</span><span>)</span><span> -&gt;</span><span> ExecutionAddress</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span class="z-support">len</span><span>(</span><span>signature_info</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 96</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> signature</span><span class="z-keyword"> =</span><span> signature_info</span><span>[</span><span>:</span><span class="z-constant">64</span><span>]</span></span> <span class="giallo-l"><span> public_key</span><span class="z-keyword"> =</span><span> signature_info</span><span>[</span><span class="z-constant">64</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"> This is the `Verify` function described in [RFC 8032 Section 5.1.7](https://datatracker.ietf.org/doc/html/rfc8032#section-5.1.7),</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> This MUST be processed as raw `Ed25519` and not `Ed25519ctx` or `Ed25519ph`</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span>ed25519_verify</span><span>(</span><span>signature</span><span>,</span><span> public_key</span><span>,</span><span> payload_hash</span><span>)</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> keccak256</span><span>(</span><span>public_key</span><span>)</span><span>[</span><span class="z-keyword">-</span><span class="z-constant">20</span><span>:</span><span>]</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="additional-1000-gas-penalty">Additional 1000 gas penalty</h3> <p>The gas penalty discourages people from attempting to migrate off current secp256k1 accounts, and also covers the additional overhead (in regards to hashing) that the ed25519 curve applies.</p> <h3 id="why-ed25519">Why Ed25519?</h3> <p>Ed25519 has significant tooling backing it, this makes it a good candidate for using as a "dummy" algorithm. This allows it to be an algorithm for client teams to easily test <a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a>.</p> <p>It may also be useful for signing in Hardware security modules in server environments designed for serving as <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> bundlers. It may also improve interoperability with other components such as TPM chips.</p> <h3 id="appending-the-public-key-to-the-signature">Appending the public key to the signature</h3> <p>Currently, without changing the algorithm itself, it is impossible to efficiently recover the public key from a signature and message.</p> <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-06-18T00:00:00+00:00 2026-02-11T14:49:27+00:00 Toni Wahrstätterhttps://github.com/nerolation https://wg-eips.ritovision.com/7976/

Increase the calldata floor cost to 15/60 gas per byte to reduce maximum block size

<h2 id="abstract">Abstract</h2> <p>This EIP proposes an adjustment to calldata pricing by raising the floor cost from 10/40 to 15/60 gas per zero/non-zero calldata byte. This reduces the worst-case block size by ~33% with minimal impact.</p> <h2 id="motivation">Motivation</h2> <p>While <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> successfully reduced the maximum possible block size by introducing a floor cost of 10/40 gas per byte for data-heavy transactions, continued increases in gas limit demands further optimization. The current floor cost still permits relatively large data-heavy payloads that contribute to block size variance.</p> <p>By increasing the floor cost to 15/60 gas per byte, this proposal aims to:</p> <ul> <li>Further reduce the maximum possible block size for data-heavy transactions</li> <li>Create additional headroom for potential block gas limit increases</li> <li>Maintain the same exemption for transactions with significant EVM computation</li> <li>Have minimal impact on users</li> </ul> <h2 id="specification">Specification</h2> <table><thead><tr><th>Parameter</th><th>Value</th></tr></thead><tbody> <tr><td><code>STANDARD_TOKEN_COST</code></td><td><code>4</code></td></tr> <tr><td><code>TOTAL_COST_FLOOR_PER_TOKEN</code></td><td><code>15</code></td></tr> </tbody></table> <p>Let <code>tokens_in_calldata = zero_bytes_in_calldata + nonzero_bytes_in_calldata * 4</code>.</p> <p>Let <code>isContractCreation</code> be a boolean indicating the respective event.</p> <p>Let <code>execution_gas_used</code> be the gas used for EVM execution with the gas refund subtracted.</p> <p>Let <code>INITCODE_WORD_COST</code> be 2 as defined in <a href="https://wg-eips.ritovision.com/3860/">EIP-3860</a>.</p> <p>The formula for determining the gas used per transaction changes from <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a>'s implementation to:</p> <pre class="giallo z-code"><code data-lang="python"><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> tokens_in_calldata</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> execution_gas_used</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> isContractCreation</span><span class="z-keyword"> *</span><span> (</span><span class="z-constant">32000</span><span class="z-keyword"> +</span><span class="z-constant"> INITCODE_WORD_COST</span><span class="z-keyword"> *</span><span> words</span><span>(</span><span>calldata</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> TOTAL_COST_FLOOR_PER_TOKEN</span><span class="z-keyword"> *</span><span> tokens_in_calldata</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>Any transaction with a gas limit below <code>21000 + TOTAL_COST_FLOOR_PER_TOKEN * tokens_in_calldata</code> or below its intrinsic gas cost (take the maximum of these two calculations) is considered invalid. This limitation exists because transactions must cover the floor price of their calldata without relying on the execution of the transaction. There are valid cases where <code>gasUsed</code> will be below this floor price, but the floor price needs to be reserved in the transaction gas limit.</p> <h2 id="rationale">Rationale</h2> <p>With <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a>'s implementation, data-heavy transactions cost 10/40 gas per zero/non-zero byte, reducing the maximum possible EL payload size to approximately 1.07 MB (<code>45s_000_000/40</code>). This EIP further reduces this to approximately 0.72 MB (<code>45_000_000/60</code>) for non zero bytes and maintains proportional costs for non-zero bytes.</p> <p>By increasing calldata costs from 10/40 to 15/60 gas per byte for data-heavy transactions, this EIP provides:</p> <ul> <li><strong>Enhanced block size reduction</strong>: Maximum data-heavy payload size drops by ~33%.</li> <li><strong>Maintained user experience</strong>: Regular users engaging in DeFi, token transfers, and other EVM-heavy operations remain unaffected</li> <li><strong>Better blob incentivization</strong>: Higher calldata costs further encourage migration to blob usage for data availability</li> </ul> <p>The floor cost mechanism ensures that transactions involving significant EVM computation continue to pay the standard 4/16 gas per byte for calldata, preserving the user experience for regular Ethereum operations.</p> <p>Analyzing the block range 20644414 - 23272414 (Sept. 2024 - Sept. 2025), 1.5% of all transactions would have been affected.</p> <p>An empirical analysis summarizing the impact of this EIP can be found in <a href="https://wg-eips.ritovision.com/7976/assets/eip7976_empirical_analysis/">this</a> report.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backwards incompatible gas repricing that requires a scheduled network upgrade.</p> <p>Wallet developers and node operators MUST update gas estimation handling to accommodate the new calldata cost rules. Specifically:</p> <ol> <li> <p><strong>Wallets</strong>: Wallets using <code>eth_estimateGas</code> MUST be updated to ensure that they correctly account for the updated <code>TOTAL_COST_FLOOR_PER_TOKEN</code> parameter of 15. Failure to do so could result in underestimating gas, leading to failed transactions.</p> </li> <li> <p><strong>Node Software</strong>: RPC methods such as <code>eth_estimateGas</code> MUST incorporate the updated formula for gas calculation with the new floor cost values.</p> </li> </ol> <p>Users can maintain their usual workflows without modification, as wallet and RPC updates will handle these changes.</p> <h2 id="test-cases">Test Cases</h2> <p>Testing for this EIP should verify the correct application of the new calldata cost floor of 15/60 gas per zero/non-zero byte:</p> <ol> <li><strong>Data-heavy transactions</strong>: Verify transactions with minimal EVM execution pay the floor cost of 15 gas per calldata token</li> <li><strong>EVM-heavy transactions</strong>: Confirm transactions with significant computation continue using standard 4/16 gas per byte</li> <li><strong>Edge cases</strong>: Test transactions at the boundary where execution gas equals or exceeds the floor cost</li> <li><strong>Gas estimation</strong>: Validate that <code>eth_estimateGas</code> correctly accounts for the new <code>TOTAL_COST_FLOOR_PER_TOKEN</code> value</li> <li><strong>Invalid transactions</strong>: Ensure transactions with insufficient gas limits are properly rejected</li> </ol> <h2 id="security-considerations">Security Considerations</h2> <p>As the maximum possible block size is further reduced compared to <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a>, no additional security concerns are introduced beyond those already addressed in the original proposal.</p> <p>The same transaction bundling considerations from <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> apply:</p> <ol> <li>Transaction bundling was already possible and remains so</li> <li>Bundling does not compromise the block size reduction objectives</li> <li>Practical limitations (trust, coordination) continue to limit widespread bundling</li> </ol> <p>The increased floor cost strengthens the incentive structure for appropriate data availability method selection without introducing new attack vectors.</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-06-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Felix Langefjl@ethereum.org Jochem Brouwerhttps://github.com/jochem-brouwer Giulio Rebuffohttps://github.com/Giulio2002 https://wg-eips.ritovision.com/7975/

Adds a facility for paginating block receipts in the p2p protocol

<h2 id="abstract">Abstract</h2> <p>This EIP modifies the 'eth' p2p protocol to allow requesting partial block receipt lists.</p> <h2 id="motivation">Motivation</h2> <p>As Ethereum moves toward a higher block gas limit on mainnet, the worst-case total size of a block receipts list also becomes larger, and may eventually exceed the 10MiB message size limit commonly applied in clients. This can lead to sync failures.</p> <h2 id="specification">Specification</h2> <p>Modify the encoding for receipts in the <code>Receipts (0x10)</code> message as follows:</p> <ul> <li> <p>(eth/69): <code>[request-id: P, [[receipt₁, receipt₂], ...]]</code></p> </li> <li> <p>(eth/70): <code>[request-id: P, lastBlockIncomplete: {0,1}, [[receipt₁, receipt₂], ...]]</code></p> </li> </ul> <p>If the <code>lastBlockIncomplete</code> flag is set to true (<code>1</code>), the last receipt list does not contain all receipts of the block, and the client will have to request the remaining receipts of that block in a new request.</p> <p>To support such partial queries, we also modify the <code>GetReceipts (0x0f)</code> message:</p> <ul> <li> <p>(eth/69): <code>[request-id: P, [blockhash₁: B_32, blockhash₂: B_32, ...]]</code></p> </li> <li> <p>(eth/70): <code>[request-id: P, firstBlockReceiptIndex: P, [blockhash₁: B_32, blockhash₂: B_32, ...]]</code></p> </li> </ul> <p>For the first block in the list of requested block hashes, the server shall omit receipts up to the <code>firstBlockReceiptIndex</code> from the response.</p> <p>Downloading block receipts across multiple messages creates new attack surface. Partial receipt lists cannot be verified against the block header, so in responses with <code>lastBlockIncomplete = 1</code>, the last receipts list must be validated in a different way:</p> <ul> <li>Verify the total number of delivered receipts matches the count of transactions.</li> <li>Verify the size of each receipt against the gas limit of the corresponding transaction, i.e. reject if it is larger than gaslimit/8.</li> <li>Verify the total downloaded receipts size is no larger than allowed by the block gas limit.</li> </ul> <!-- Needs exact formula --> <h2 id="rationale">Rationale</h2> <p>Since <a href="https://wg-eips.ritovision.com/7825/">EIP-7825</a> caps the gas limit of a single transaction to ~16.7M gas, a single transaction receipt will always be limited in size. Specifically, a transaction can produce at most 16777216/8 = 2MiB of log data.</p> <p>However, a block can contain contain multiple transactions, and thus the entire block receipts list can be much larger. At a block gas limit of ~83M, the <code>Receipts</code> message could exceed 10MiB. Clients typically reject messages above this size because their validity can only be determined after fetching the complete message.</p> <p>For a <code>Receipts</code> message, each block receipts list is validated by checking the full list against the tree root stored in the block header. When downloading a paginated list across multiple requests, the client must potentially buffer more than 10MB of unvalidated input. This cannot be avoided, since the protocol allows receipt lists of such size at a high block gas limit. However, we can at least bound the input size by applying sanity checks as recommended in the specification section.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP changes the eth protocol and requires rolling out a new version, <code>eth/70</code>. Supporting multiple versions of a wire protocol is possible. Rolling out a new version does not break older clients immediately, since they can keep using protocol version <code>eth/69</code>.</p> <p>This EIP does not change consensus rules of the EVM and does not require a hard fork.</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> 2025-06-14T00:00:00+00:00 2026-02-11T14:49:27+00:00 Charles Cooperhttps://github.com/charles-cooper Maria Silvahttps://github.com/misilva73 Ben Adamshttps://github.com/benaadams https://wg-eips.ritovision.com/7973/

Introduce warm account writes, decreasing the cost of writing to an account after the first write.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces warm metering for account writes. Namely, if one of the account fields (<code>nonce</code>, <code>value</code>, <code>codehash</code>) is changed more than once in a transaction, the later writes are cheaper, since the state root update only happens once.</p> <h2 id="motivation">Motivation</h2> <p>Updating the state root is one of the most expensive parts of block construction. Currently, multiple writes to storage are subject to a net gas metering, which reduces the cost of a storage write after the first write. However, updates to the account are subject to the same cost every time.</p> <p>This means that, for example, making multiple WETH transfers to an account in a single transaction gets successfully cheaper as the cold access cost is amortized over the remaining accesses. At the same time, the same discount does not occur when making multiple native ETH transfers. This discourages people from using native ETH transfers, and unfairly penalizes potential future opcodes that involve value transfer, like <code>PAY</code> and <code>GAS2ETH</code>.</p> <p>This EIP brings the gas cost of the account update more in line with the actual execution cost. Multiple writes within a transaction can be batched, meaning that, after the first write, the cost of updating the state root does not need to be charged again.</p> <h2 id="specification">Specification</h2> <p>The parameters <code>GAS_CALL_VALUE</code> and <code>GAS_STORAGE_UPDATE</code> are removed, and the following parameters are introduced:</p> <table><thead><tr><th style="text-align: center"><strong>Parameter</strong></th><th style="text-align: center"><strong>Value</strong></th><th style="text-align: center"><strong>Description</strong></th></tr></thead><tbody> <tr><td style="text-align: center"><code>GAS_COLD_STORAGE_WRITE</code></td><td style="text-align: center">TBD</td><td style="text-align: center">Cost of a single update to the storage trie</td></tr> <tr><td style="text-align: center"><code>GAS_COLD_ACCOUNT_WRITE</code></td><td style="text-align: center">TBD</td><td style="text-align: center">Cost of a single update to the account trie</td></tr> <tr><td style="text-align: center"><code>GAS_WARM_WRITE</code></td><td style="text-align: center">TBD</td><td style="text-align: center">Cost of a warm update to a trie (i.e. does not trigger a new state root calculation)</td></tr> </tbody></table> <p>&lt;-- TODO --&gt;</p> <p>On the account-updating opcodes <code>CREATE</code>, <code>CREATE2</code>, and <code>*CALL</code>, instead of charging <code>GAS_CALL_VALUE</code>:</p> <ul> <li><code>GAS_COLD_ACCOUNT_WRITE</code> is charged if the account fields <strong>are equal</strong> to the transaction start values (i.e., they have not yet been updated by the transaction), or</li> <li><code>GAS_WARM_WRITE</code> is charged if the account fields <strong>are not equal</strong> to the transaction start values (i.e., they have already been updated before by the transaction).</li> </ul> <p><code>SSTORE</code> is also subjected to warm account metering. That is, this EIP splits the cost of <code>SSTORE</code> into two components, the cost to update the account tuple, and the cost to update the state trie. Note that if the state trie has already been updated once in a transaction, the account tuple is already dirty, and so we can amortize the cost of updating the account tuple again. Thus, the gas cost of <code>SSTORE</code> and its refund logic is updated to:</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 original_value and current_value</span></span> <span class="giallo-l"><span>state</span><span class="z-keyword"> =</span><span> evm</span><span>.</span><span>message</span><span>.</span><span>block_env</span><span>.</span><span>state</span></span> <span class="giallo-l"><span>original_value</span><span class="z-keyword"> =</span><span> get_storage_original</span><span>(</span></span> <span class="giallo-l"><span> state</span><span>,</span><span> evm</span><span>.</span><span>message</span><span>.</span><span>current_target</span><span>,</span><span> key</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span>current_value</span><span class="z-keyword"> =</span><span> get_storage</span><span>(</span><span>state</span><span>,</span><span> evm</span><span>.</span><span>message</span><span>.</span><span>current_target</span><span>,</span><span> key</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 account info</span></span> <span class="giallo-l"><span>original_account</span><span class="z-keyword"> =</span><span> get_account_original</span><span>(</span><span>evm</span><span>.</span><span>message</span><span>.</span><span>block_env</span><span>.</span><span>state</span><span>,</span><span> evm</span><span>.</span><span>message</span><span>.</span><span>current_target</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>message</span><span>.</span><span>block_env</span><span>.</span><span>state</span><span>,</span><span> evm</span><span>.</span><span>message</span><span>.</span><span>current_target</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"> initialize gas cost</span></span> <span class="giallo-l"><span>gas_cost</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Charge account write cost</span></span> <span class="giallo-l"><span class="z-keyword">if</span><span> account</span><span class="z-keyword"> !=</span><span> original_account</span><span>:</span></span> <span class="giallo-l"><span> gas_cost</span><span class="z-keyword"> +=</span><span class="z-constant"> GAS_WARM_WRITE</span></span> <span class="giallo-l"><span class="z-keyword">else</span><span>:</span></span> <span class="giallo-l"><span> gas_cost</span><span class="z-keyword"> +=</span><span class="z-constant"> GAS_COLD_ACCOUNT_WRITE</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Charge slot-specific costs</span></span> <span class="giallo-l"><span class="z-keyword">if</span><span> (</span><span>evm</span><span>.</span><span>message</span><span>.</span><span>current_target</span><span>,</span><span> key</span><span>)</span><span class="z-keyword"> not</span><span class="z-keyword"> in</span><span> evm</span><span>.</span><span>accessed_storage_keys</span><span>:</span></span> <span class="giallo-l"><span> evm</span><span>.</span><span>accessed_storage_keys</span><span>.</span><span>add</span><span>(</span><span>(</span><span>evm</span><span>.</span><span>message</span><span>.</span><span>current_target</span><span>,</span><span> key</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> gas_cost</span><span class="z-keyword"> +=</span><span class="z-constant"> GAS_COLD_SLOAD</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">if</span><span> original_value</span><span class="z-keyword"> ==</span><span> current_value</span><span class="z-keyword"> and</span><span> current_value</span><span class="z-keyword"> !=</span><span> new_value</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> original_value</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> gas_cost</span><span class="z-keyword"> +=</span><span class="z-constant"> GAS_STORAGE_SET</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> gas_cost</span><span class="z-keyword"> +=</span><span class="z-constant"> GAS_COLD_STORAGE_WRITE</span><span class="z-keyword"> -</span><span class="z-constant"> GAS_COLD_SLOAD</span></span> <span class="giallo-l"><span class="z-keyword">else</span><span>:</span></span> <span class="giallo-l"><span> gas_cost</span><span class="z-keyword"> +=</span><span class="z-constant"> GAS_WARM_ACCESS</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"> Refund Counter Calculation</span></span> <span class="giallo-l"><span class="z-keyword">if</span><span> current_value</span><span class="z-keyword"> !=</span><span> new_value</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> original_value</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span class="z-keyword"> and</span><span> current_value</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span class="z-keyword"> and</span><span> new_value</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"> Storage is cleared for the first time in the transaction</span></span> <span class="giallo-l"><span> evm</span><span>.</span><span>refund_counter</span><span class="z-keyword"> +=</span><span class="z-support"> int</span><span>(</span><span class="z-constant">GAS_STORAGE_CLEAR_REFUND</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> original_value</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span class="z-keyword"> and</span><span> current_value</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"> Gas refund issued earlier to be reversed</span></span> <span class="giallo-l"><span> evm</span><span>.</span><span>refund_counter</span><span class="z-keyword"> -=</span><span class="z-support"> int</span><span>(</span><span class="z-constant">GAS_STORAGE_CLEAR_REFUND</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> original_value</span><span class="z-keyword"> ==</span><span> new_value</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Storage slot being restored to its original value</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> original_value</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"> Slot was originally empty and was SET earlier</span></span> <span class="giallo-l"><span> evm</span><span>.</span><span>refund_counter</span><span class="z-keyword"> +=</span><span class="z-support"> int</span><span>(</span><span class="z-constant">GAS_STORAGE_SET</span><span class="z-keyword"> -</span><span class="z-constant"> GAS_WARM_ACCESS</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"> Slot was originally non-empty and was UPDATED earlier</span></span> <span class="giallo-l"><span> evm</span><span>.</span><span>refund_counter</span><span class="z-keyword"> +=</span><span class="z-support"> int</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> GAS_COLD_STORAGE_WRITE</span><span class="z-keyword"> -</span><span class="z-constant"> GAS_COLD_SLOAD</span><span class="z-keyword"> -</span><span class="z-constant"> GAS_WARM_ACCESS</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"> Refund account writting cost (only if cold)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> account</span><span class="z-keyword"> ==</span><span> original_account</span><span>:</span></span> <span class="giallo-l"><span> evm</span><span>.</span><span>refund_counter</span><span class="z-keyword"> +=</span><span class="z-constant"> GAS_COLD_ACCOUNT_WRITE</span></span> <span class="giallo-l"></span></code></pre> <p>For compatibility with <a href="https://wg-eips.ritovision.com/7928/">EIP-7928</a> and parallel execution, if the accessed account shows updates in the Block-Level Access List (BAL) in a transaction indexed before the current transaction, then the values to compare against are taken from this entry instead of the account trie.</p> <h2 id="rationale">Rationale</h2> <p>An account is represented within Ethereum as a tuple <code>(nonce, balance, storage_root, codehash)</code>. The account is a leaf of a Merkle Patricia Tree (MPT), while the <code>storage_root</code> is itself the root of the account's MPT key-value store. An update to the account's storage requires updating two MPTs (the account's <code>storage_root</code>, as well as the global state root). Meanwhile, updating the other fields in an account requires updating only one MPT.</p> <p>This proposal clarifies the cost of updating state by introducing the <code>*_WRITE</code> parameters. It also separates the cost of a storage state root update (<code>GAS_COLD_STORAGE_ACCESS</code>) and the cost of an account state root update (<code>GAS_COLD_ACCOUNT_ACCESS</code>). This parametrization allows us to apply warm costing to account updates. When the same account is updated multiple times in the same transaction, the state root calculation can be batched and all updates can be done in the same calculation. Therefore, the cost of making more updates to an already updated account is not the same as the first update.</p> <h3 id="benchmarking">Benchmarking</h3> <p>This proposal does not yet have finalized numbers. To achieve this, we require stateful benchmarks, which are currently in development. Once we collect that data, we will set the final numbers.</p> <p>&lt;– TODO –&gt;</p> <h3 id="net-metering">Net metering</h3> <p>Net metering (i.e., issuing a refund if the final value at the end of the transaction is equal to the transaction start, à la <code>SSTORE</code>) was considered, but not added for simplicity.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backwards-incompatible gas repricing that requires a scheduled network upgrade.</p> <p>Wallet developers and node operators MUST update gas estimation handling to accommodate the new account access cost rules. Specifically:</p> <ul> <li>Wallets: Wallets using <code>eth_estimateGas</code> MUST be updated to ensure that they correctly account for the updated gas parameters. Failure to do so could result in overestimating gas, leading to potential attacks vectors.</li> <li>Node Software: RPC methods such as <code>eth_estimateGas</code> MUST incorporate the updated formula for gas calculation with the new cost values.</li> </ul> <p>Users can maintain their usual workflows without modification, as wallet and RPC updates will handle these changes.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Decreasing the cost of account access operations could introduce new attack vectors. More analysis is needed to understand the potential effects on various dApps and user behaviors.</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-06-12T00:00:00+00:00 2026-02-11T14:49:27+00:00 Charles Cooperhttps://github.com/charles-cooper Ben Adamshttps://github.com/benaadams Maria Silvahttps://github.com/misilva73 Jochem Brouwerhttps://github.com/jochem-brouwer https://wg-eips.ritovision.com/7971/

Decrease costs for TLOAD and TSTORE with a transaction-global limit

<h2 id="abstract">Abstract</h2> <p>This EIP proposes to reduce the gas costs for transient storage operations (<code>TLOAD</code> and <code>TSTORE</code>) by implementing constant pricing. To prevent denial-of-service attacks through excessive memory allocation, a transaction-global limit on transient storage slots is introduced. This approach provides lower costs for common use cases while maintaining security against resource exhaustion attacks.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/1153/">EIP-1153</a> introduced transient storage with gas costs equivalent to warm storage operations (100 gas). The current pricing model presents several limitations:</p> <ol> <li>Reentrancy Protection Cost: At 100 gas per operation, implementing reentrancy locks by default remains expensive enough to discourage universal adoption at the language level, leaving contracts vulnerable to one of the most common attack vectors.</li> <li>Underutilization: The high cost is still punishing to developers who wish to use transient storage for other legitimate use cases such as temporary approvals, callback metadata, and cross-frame communication within transactions.</li> <li>Pricing Inconsistency: Transient storage fundamentally requires fewer resources than persistent storage (no disk I/O, no state root updates), yet is priced identically to warm storage operations.</li> </ol> <p>This EIP addresses these issues by implementing constant, lower pricing for transient storage operations while introducing a transaction-global limit to prevent denial-of-service attacks. It also makes the cost of warm storage cheaper. This provides lower costs and enables broader adoption of transient storage, while also providing hard resource limits for clients.</p> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <p>This EIP introduces the following parameters:</p> <table><thead><tr><th style="text-align: left">Constant</th><th style="text-align: left">Value</th><th style="text-align: left">Description</th></tr></thead><tbody> <tr><td style="text-align: left"><code>GAS_TLOAD</code></td><td style="text-align: left">5</td><td style="text-align: left">Gas cost of <code>TLOAD</code></td></tr> <tr><td style="text-align: left"><code>GAS_TSTORE</code></td><td style="text-align: left">12</td><td style="text-align: left">Gas cost of <code>TSTORE</code></td></tr> <tr><td style="text-align: left"><code>MAX_TRANSIENT_SLOTS</code></td><td style="text-align: left">131072</td><td style="text-align: left">The maximum number of transient slots allowed in a single transaction</td></tr> <tr><td style="text-align: left"><code>GAS_TSTORE_ALLOCATE</code></td><td style="text-align: left">24</td><td style="text-align: left">Cost of additional allocated slots</td></tr> </tbody></table> <h3 id="gas-cost-changes">Gas Cost Changes</h3> <ol> <li>The gas cost for <code>TLOAD</code> (opcode <code>0x5c</code>) is reduced from <code>GAS_WARM_ACCESS</code> (100) to <code>GAS_TLOAD</code>.</li> <li>The base gas cost for <code>TSTORE</code> (opcode <code>0x5d</code>) is reduced from <code>GAS_WARM_ACCESS</code> (100) to <code>GAS_TSTORE</code>.</li> </ol> <h3 id="transaction-global-transient-storage-limit">Transaction-Global Transient Storage Limit</h3> <p>A transaction-global counter tracks the number of unique transient storage slots written across all contracts during transaction execution:</p> <ol> <li>At the beginning of each transaction, initialize a counter <code>transient_slots_used</code> to 0.</li> <li>When <code>TSTORE</code> is executed: <ul> <li>If the slot has not been written to during this transaction (across any contract), increment <code>transient_slots_used</code>.</li> <li>If <code>transient_slots_used</code> exceeds <code>MAX_TRANSIENT_SLOTS</code>, the transaction MUST exceptionally halt.</li> </ul> </li> <li>The counter persists across all message calls in the transaction.</li> <li>The counter is reset to 0 at the end of the transaction.</li> </ol> <h3 id="implementation-note">Implementation Note</h3> <p>Implementations MUST track transient storage allocated across all contracts. A slot is considered unique based on the tuple <code>(contract_address, storage_key)</code>. Writing to the same slot multiple times within a transaction does not generally increment the counter after the first write (unless the slot gets deallocated with a revert).</p> <h2 id="rationale">Rationale</h2> <h3 id="constant-pricing-with-hard-limit">Constant Pricing with Hard Limit</h3> <p>This EIP implements constant pricing with a hard limit for several reasons:</p> <ol> <li>A hard limit provides guarantees on the total resource consumption which are easier to reason about for clients, rather than needing to perform a calculation as a function of current gas limits to find out what total memory consumption could be.</li> <li>Common use cases (e.g., reentrancy locks using 1-2 slots) are not penalized for worst case resource usage (like in DOS attacks).</li> <li>Clients can safely pre-reserve all memory which could be used by transient storage up-front at the beginning of a transaction.</li> </ol> <h3 id="gas-cost-selection">Gas Cost Selection</h3> <ul> <li><code>GAS_TLOAD</code> (5 gas): Transient storage reads require only memory access without disk I/O.</li> <li><code>GAS_TSTORE</code> (12 gas): Transient storage writes require memory allocation and journaling for revert support.</li> <li><code>GAS_TSTORE_ALLOCATE</code> (24 gas): Writes to fresh slots require memory allocation, which is more expensive than writing to an existing slot.</li> </ul> <p><code>TSTORE</code> currently has a fixed cost. However, writing to fresh slots requires memory allocation, which is more expensive than writing to an existing slot. Therefore, we may consider introducing charging more for the first slot allocation through the parameter <code>GAS_TSTORE_ALLOCATE</code>. However, we would also need to introduce a mechanism to check for the first slot allocation versus subsequent allocations.</p> <h4 id="benchmarking">Benchmarking</h4> <p>This proposal does not yet have finalized numbers. To achieve this, we require benchmarks on the transient memory operations, which are currently in development. Once we collect that data, we will set the final numbers. We will also use this to understand whether the difference in performance justifies pricing new slot allocations differently.</p> <p>We should note that warm storage loads from cache are expected to have similar performance characteristics to transient storage reads. Therefore, the final parameters should be consistent with <a href="https://wg-eips.ritovision.com/8038/">EIP-8038</a>.</p> <p>&lt;– TODO –&gt;</p> <h3 id="hard-limit-selection">Hard Limit Selection</h3> <p><code>MAX_TRANSIENT_SLOTS</code> of 131072 allows:</p> <ul> <li>Sufficient slots for typical user applications</li> <li>Memory usage bounded to approximately 8 MB per transaction (131072 slots * 64 bytes), which prevents OOM-based denial-of-service attacks</li> </ul> <h3 id="design-alternatives-considered">Design Alternatives Considered</h3> <ol> <li>Per-Contract Limits: Increased complexity in reasoning about resource consumption based on the shape of the call stack.</li> <li>Superlinear Pricing: Adds complexity, and still punishes "common" (non-DOS) use cases.</li> <li>No Limit: May allow memory-based DOS attack if transaction-level gas limits change, or if pricing changes in the future.</li> </ol> <p>The benefit of a hard limit is that the resource consumption is bounded predictably even in the presence of other parameter changes in the protocol.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No known issues, besides the gas cost of existing operations being cheaper.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>This reference implementation includes the mechanism to price <code>TSTORE</code> depending on whether the slot was previously allocated.</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"> Pseudo-code for transaction execution with global transient storage limit</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-constant">GAS_TLOAD</span><span class="z-keyword"> =</span><span class="z-constant"> 5</span></span> <span class="giallo-l"><span class="z-constant">GAS_TSTORE</span><span class="z-keyword"> =</span><span class="z-constant"> 12</span></span> <span class="giallo-l"><span class="z-constant">GAS_TSTORE_ALLOCATE</span><span class="z-keyword"> =</span><span class="z-constant"> 24</span></span> <span class="giallo-l"><span class="z-constant">MAX_TRANSIENT_SLOTS</span><span class="z-keyword"> =</span><span class="z-constant"> 131072</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"> TransactionContext</span><span>:</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>transient_storage</span><span class="z-keyword"> =</span><span> {</span><span>}</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> (address, key) -&gt; value</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>unique_slots</span><span class="z-keyword"> =</span><span class="z-support"> set</span><span>(</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> set of (address, key) tuples</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>transient_slots_used</span><span class="z-keyword"> =</span><span class="z-constant"> 0</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"> tload</span><span>(</span><span class="z-variable z-parameter z-function">self</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> Bytes32</span><span>)</span><span> -&gt;</span><span> Bytes32</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Charge gas</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>charge_gas</span><span>(</span><span class="z-constant">GAS_TLOAD</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 value or zero</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> self</span><span>.</span><span>transient_storage</span><span>.</span><span>get</span><span>(</span><span>(</span><span>address</span><span>,</span><span> key</span><span>)</span><span>,</span><span> Bytes32</span><span>(</span><span class="z-constant">0</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"> tstore</span><span>(</span><span class="z-variable z-parameter z-function">self</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> Bytes32</span><span>,</span><span class="z-variable z-parameter z-function"> value</span><span>:</span><span> Bytes32</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Charge gas</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>charge_gas</span><span>(</span><span class="z-constant">GAS_TSTORE</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 if this is a new unique slot</span></span> <span class="giallo-l"><span> slot_id</span><span class="z-keyword"> =</span><span> (</span><span>address</span><span>,</span><span> key</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> slot_id</span><span class="z-keyword"> not</span><span class="z-keyword"> in</span><span class="z-variable z-language"> self</span><span>.</span><span>unique_slots</span><span>:</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>charge_gas</span><span>(</span><span class="z-constant">GAS_TSTORE_ALLOCATE</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>unique_slots</span><span>.</span><span>add</span><span>(</span><span>slot_id</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 limit</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>unique_slots</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> MAX_TRANSIENT_SLOTS</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> ExceptionalHalt</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Transient storage limit exceeded</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-punctuation z-definition z-comment"> #</span><span class="z-comment"> Store value</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>transient_storage</span><span>[</span><span>slot_id</span><span>]</span><span class="z-keyword"> =</span><span> value</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>With <code>MAX_TRANSIENT_SLOTS</code> = 131072, maximum memory allocation is bounded to 8 MB per transaction (131072 * 64 bytes). Compared to limits under current pricing (100 gas), a 60M gas transaction can allocate up to 600,000 slots (38.4 MB). This EIP reduces the maximum allocated amount by 79%.</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-06-11T00:00:00+00:00 2026-02-11T14:49:27+00:00 Sam Battenallyhttps://github.com/SmoothBot Hai Nguyenhttps://github.com/hai-rise Thanh Nguyenhttps://github.com/LampardNguyen234 Loc Nguyenhttps://github.com/silver-rise https://wg-eips.ritovision.com/7966/

A JSON-RPC method to reduce transaction submission latency by allowing synchronous receipt of transaction hash and block inclusion.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a new JSON-RPC method, <code>eth_sendRawTransactionSync</code>, which submits a signed raw transaction and waits synchronously for the transaction receipt or a configurable timeout before returning. This method addresses the user experience gap in high-frequency applications by offering stronger delivery guarantees than <code>eth_sendRawTransaction</code>. Additionally, when a transaction cannot be immediately executed due to a nonce gap, it returns the expected nonce as a hex string in the error response, eliminating the need for additional RPC calls to query account state.</p> <h2 id="motivation">Motivation</h2> <p>Currently, Ethereum clients submit signed transactions asynchronously using <code>eth_sendRawTransaction</code>. Clients receive a transaction hash immediately but must poll repeatedly for the transaction receipt, which increases latency and complicates client-side logic.</p> <p>This asynchronous approach is not efficient for high-frequency blockchains or Layer 2 solutions with fast block times and low latency, where rapid transaction throughput and quick confirmation feedback are critical. The need to separately poll for receipts results in increased network overhead, slower overall transaction confirmation feedback, and more complex client implementations.</p> <p>Additionally, when transactions cannot be immediately executed (e.g., due to nonce gaps or insufficient funds), existing methods provide generic error messages that don't help developers understand or fix the issue. Developers must make additional RPC calls to query account state, creating unnecessary round-trips and delays.</p> <p><img src="https://wg-eips.ritovision.com/7966/./assets/sync-vs-async.png" alt="Sync vs Async Transaction Sending" /> <em>In a low-latency blockchain, transaction receipts are often available right after the transactions land in the block producer’s mempool. Requiring an additional RPC call introduces unnecessary latency.</em></p> <p><code>eth_sendRawTransactionSync</code> addresses these issues by combining transaction submission and receipt retrieval into a single RPC call. This helps:</p> <ul> <li>reduce total transaction submission and confirmation latency by approximately 50%;</li> <li>simplify client implementations by eliminating the need for separate polling loops;</li> <li>improve user experience by enabling more responsive dApps and wallets;</li> <li>align blockchain interactions closer to traditional Web2 request-response patterns;</li> <li>maintain backward compatibility and optionality, preserving existing RPC methods and semantics.</li> </ul> <h2 id="specification">Specification</h2> <h3 id="method-name">Method Name</h3> <p><code>eth_sendRawTransactionSync</code></p> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Position</th><th>Type</th><th>Description</th><th>Required</th></tr></thead><tbody> <tr><td>1</td><td><code>DATA</code></td><td>The signed transaction data</td><td>Yes</td></tr> <tr><td>2</td><td><code>INT</code></td><td>Maximum wait time in milliseconds</td><td>No</td></tr> </tbody></table> <h4 id="parameter-validation-rules">Parameter Validation Rules</h4> <ul> <li><strong>Transaction Data</strong>. MUST be a valid hex-encoded, RLP-encoded signed transaction (same as in <code>eth_sendRawTransaction</code>).</li> <li><strong>Timeout</strong>. MUST be a positive integer not greater than the node-configured maximum timeout.</li> </ul> <h3 id="returns">Returns</h3> <ul> <li><strong>On success</strong>. Node implementations MUST return the transaction receipt object as defined by the <code>eth_getTransactionReceipt</code> method.</li> <li><strong>On timeout error</strong>. Node implementations MUST return an error code <code>4</code> with a timeout message.</li> <li><strong>On unreadiness error</strong>. Node implementations SHOULD return an error code <code>5</code> with an error message. <ul> <li>This happens when the processing node is not ready to accept a new transaction or the transaction is erroneous (DX improvement).</li> </ul> </li> <li><strong>On standard error</strong>. Node implementations MUST return a JSON-RPC error object consistent with existing RPC error formats.</li> </ul> <h3 id="error-codes-and-response-structure">Error Codes and Response Structure</h3> <p>The following error codes are specific to <code>eth_sendRawTransactionSync</code>:</p> <table><thead><tr><th>Code</th><th>Error Type</th><th>Description</th><th>Data Format</th></tr></thead><tbody> <tr><td>4</td><td>Timeout</td><td>Transaction was added to mempool but not processed within timeout</td><td>Transaction hash (hex)</td></tr> <tr><td>5</td><td>Unknown/Queued</td><td>Transaction is NOT added to mempool (not ready for execution)</td><td>Transaction hash (hex)</td></tr> <tr><td>6</td><td>Nonce Gap</td><td>Transaction is NOT added to mempool (nonce gap detected)</td><td>Expected nonce (hex)</td></tr> </tbody></table> <p>When an error occurs, the response includes:</p> <ul> <li><code>code</code>: The error code indicating the error type</li> <li><code>message</code>: A human-readable error message</li> <li><code>data</code>: Error-specific data: <ul> <li>For error code <code>4</code> (Timeout): Contains the transaction hash as a hex string (e.g., <code>"0x1234abcd..."</code>)</li> <li>For error code <code>5</code> (Unknown/Queued): Contains the transaction hash as a hex string (e.g., <code>"0x1234abcd..."</code>)</li> <li>For error code <code>6</code> (Nonce Gap): Contains the expected nonce as a hex string (e.g., <code>"0x5"</code>)</li> </ul> </li> </ul> <h3 id="node-configured-timeouts">Node-Configured Timeouts</h3> <ul> <li>The handler function of this RPC SHOULD incorporate a configurable timeout when waiting for receipts (RECOMMENDED: 2 seconds).</li> <li>Node implementations SHOULD provide a way to configure the timeout duration.</li> <li>Node operators MAY implement dynamic timeout adjustment based on real-time network conditions.</li> </ul> <h3 id="behavior">Behavior</h3> <p>Upon receiving an <code>eth_sendRawTransactionSync</code> request, the handler function performs the following tasks.</p> <ul> <li>If timeout parameter is provided, the handler function MUST validate its validity. <ul> <li>If the timeout is invalid, the handler function MUST use the default node-configure timeout.</li> </ul> </li> <li>The handler function MUST check if the transaction is ready for immediate execution BEFORE adding it to the mempool: <ul> <li>If the transaction has a nonce gap (transaction nonce is higher than the expected nonce), the handler function MUST NOT add the transaction to the mempool and MUST return error code <code>6</code> with the expected nonce as a hex string directly in the <code>data</code> field.</li> <li>If the transaction is queued for any other reason (not ready for immediate execution), the handler function MUST NOT add the transaction to the mempool and MUST return error code <code>5</code>.</li> </ul> </li> <li>If the transaction is ready for immediate execution, the handler function MUST submit the signed transaction to the mempool as per the existing <code>eth_sendRawTransaction</code> semantics.</li> <li>The handler function MUST wait for the transaction receipt until the timeout elapses.</li> <li>If the receipt is found within the specified timeout, the handler function MUST return it immediately.</li> <li>If the timeout expires without obtaining a receipt, the handler function MUST return an error code <code>4</code> with a timeout message and the transaction hash.</li> <li>If the transaction submission fails (e.g., due to invalid transaction data), the handler function MUST return an error (following the <code>eth_sendRawTransaction</code> definition) immediately.</li> </ul> <h3 id="example-request-no-timeout">Example Request (No Timeout)</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">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_sendRawTransactionSync</span><span class="z-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">0xf86c808504a817c80082520894ab... (signed tx hex)</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">id</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><h3 id="example-request-with-timeout">Example Request (With Timeout)</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">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_sendRawTransactionSync</span><span class="z-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">0xf86c808504a817c80082520894ab... (signed tx hex)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 5000</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">id</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><h3 id="example-response-success">Example Response (Success)</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">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"> 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> {</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">0x1234abcd...</span><span class="z-punctuation z-definition z-string">&quot;</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xabcd1234...</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">blockNumber</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x10d4f</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">cumulativeGasUsed</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasUsed</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">contractAddress</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">logs</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">status</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></code></pre><h3 id="example-response-timeout-error-code-4">Example Response (Timeout - Error Code 4)</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">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"> 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"> 4</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">The transaction was added to the mempool but wasn&#39;t processed within the designated timeout interval.</span><span class="z-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">0x1234abcd...</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>Note: The <code>data</code> field contains the transaction hash as a hex string.</p> <h3 id="example-response-nonce-gap-error-code-6">Example Response (Nonce Gap - Error Code 6)</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">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"> 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"> 6</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">The transaction was rejected due to a nonce gap. Please resubmit with the next on-chain 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">data</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 class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Note: The <code>data</code> field contains the expected nonce as a hex string. No transaction hash is returned because the transaction was never added to the mempool.</p> <h3 id="example-response-rejected-transaction-error-code-5">Example Response (Rejected Transaction - Error Code 5)</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">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"> 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"> 5</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">The transaction was rejected for an unknown reason.</span><span class="z-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">0x1234abcd...</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="example-response-standard-error">Example Response (Standard Error)</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">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"> 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"> -32000</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 transaction</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> <h3 id="why-not-extend-existing-rpc">Why Not Extend Existing RPC?</h3> <p>Modifying <code>eth_sendRawTransaction</code> to support this behavior would risk compatibility issues and ambiguity. A separate method makes the semantics explicit and opt-in.</p> <h3 id="node-configured-timeouts-1">Node-Configured Timeouts</h3> <p>Node implementations SHOULD allow configuration of the timeout period, defaulting to 2 seconds (depending on the implementation). This balances responsiveness and propagation guarantees without creating excessive overhead in node clients.</p> <h3 id="user-configured-timeouts">User-Configured Timeouts</h3> <p>The optional timeout parameter allows clients to specify their preferred maximum wait time for transaction processing.</p> <ul> <li>Applications can adjust timeouts based on their specific latency requirements.</li> <li>The optional timeout prevents the RPC call from blocking indefinitely.</li> </ul> <h3 id="optionality">Optionality</h3> <p>This method is optional and does not replace or change existing asynchronous transaction submission methods. Nodes that do not implement this method will continue to operate normally using the standard asynchronous RPC methods.</p> <p>This RPC method is particularly suitable for EVM-compatible blockchains or L2 solutions with fast block times and low network latency, where synchronous receipt retrieval can significantly improve responsiveness. On high-latency or slower blockchains (e.g., Ethereum mainnet pre-sharding), the synchronous wait may cause longer RPC call durations or timeouts, making the method less practical.</p> <h3 id="improved-ux">Improved UX</h3> <p>The synchronous receipt retrieval reduces the complexity of client applications by eliminating the need for separate polling logic.</p> <h3 id="returned-nonces-in-error-code-6">Returned Nonces in Error Code <code>6</code></h3> <p>When a transaction is rejected due to a nonce gap, error code <code>6</code> returns the expected nonce as a hex string in the <code>data</code> field. This design provides several benefits:</p> <ul> <li><strong>Immediate Nonce Recovery</strong>: Applications receive the correct nonce directly in the error response, eliminating the need for a separate <code>eth_getTransactionCount</code> call.</li> <li><strong>Reduced Latency</strong>: By avoiding additional RPC round-trips to query account state, applications can immediately construct and resubmit the transaction with the correct nonce.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces a new RPC method and does not modify or deprecate any existing methods. Nodes that do not implement this method will continue operating normally. Existing applications using <code>eth_sendRawTransaction</code> are unaffected. Node implementations that do not support the method will simply return <code>method not found</code>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A minimal reference implementation can be realized by wrapping existing <code>eth_sendRawTransaction</code> submission with logic that waits for the corresponding transaction receipt until a timeout elapses. Implementations MAY either rely on event-driven receipt-availability notifications or poll <code>eth_getTransactionReceipt</code> at short intervals until a receipt is found or a timeout occurs. Polling intervals or notification strategies and timeout values can be tuned by node implementations to optimize performance.</p> <p>For example, in <code>reth</code>, we can implement the handler for <code>eth_sendRawTransactionSync</code> as follows.</p> <pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">async</span><span class="z-keyword"> fn</span><span class="z-entity z-name"> send_raw_transaction_sync</span><span>(</span></span> <span class="giallo-l"><span class="z-keyword"> &amp;</span><span class="z-variable z-language">self</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> tx</span><span class="z-keyword">:</span><span class="z-entity z-name"> Bytes</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> user_timeout_ms</span><span class="z-keyword">:</span><span class="z-entity z-name"> Option</span><span>&lt;</span><span class="z-entity z-name">u64</span><span>&gt;</span><span>,</span></span> <span class="giallo-l"><span>)</span><span class="z-keyword"> -&gt;</span><span class="z-entity z-name"> RpcResult</span><span>&lt;</span><span class="z-entity z-name">OpTransactionReceipt</span><span>&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-constant"> MAX_TIMEOUT_MS</span><span class="z-keyword">:</span><span class="z-entity z-name"> u64</span><span class="z-keyword"> =</span><span class="z-constant"> 2_000</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-constant"> ERROR_CODE_TIMEOUT</span><span class="z-keyword">:</span><span class="z-entity z-name"> i32</span><span class="z-keyword"> =</span><span class="z-constant"> 4</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-constant"> ERROR_CODE_UNKNOWN</span><span class="z-keyword">:</span><span class="z-entity z-name"> i32</span><span class="z-keyword"> =</span><span class="z-constant"> 5</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-constant"> ERROR_CODE_NONCE_GAP</span><span class="z-keyword">:</span><span class="z-entity z-name"> i32</span><span class="z-keyword"> =</span><span class="z-constant"> 6</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-constant"> ERROR_MSG_TIMEOUT_RECEIPT</span><span class="z-keyword">:</span><span class="z-keyword"> &amp;</span><span class="z-entity z-name">str</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The transaction was added to the mempool but wasn&#39;t processed within the designated timeout interval.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-constant"> ERROR_MSG_UNKNOWN</span><span class="z-keyword">:</span><span class="z-keyword"> &amp;</span><span class="z-entity z-name">str</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The transaction was rejected for an unknown reason.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-constant"> ERROR_MSG_NONCE_GAP</span><span class="z-keyword">:</span><span class="z-keyword"> &amp;</span><span class="z-entity z-name">str</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The transaction was rejected due to a nonce gap. Please resubmit with the next on-chain nonce.</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"> let</span><span class="z-variable z-other"> start_time</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Instant</span><span class="z-keyword">::</span><span class="z-entity z-name">now</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"> timeout</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Duration</span><span class="z-keyword">::</span><span class="z-entity z-name">from_millis</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> user_timeout_ms</span><span class="z-keyword">.</span><span class="z-entity z-name">map_or</span><span>(</span><span class="z-constant">MAX_TIMEOUT_MS</span><span>,</span><span class="z-keyword"> |</span><span class="z-variable z-other">ms</span><span class="z-keyword">|</span><span class="z-variable z-other"> ms</span><span class="z-keyword">.</span><span class="z-entity z-name">min</span><span>(</span><span class="z-constant">MAX_TIMEOUT_MS</span><span>)</span><span>)</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"> let</span><span class="z-variable z-other"> pool_transaction</span><span class="z-keyword"> =</span><span class="z-entity z-name"> OpPooledTransaction</span><span class="z-keyword">::</span><span class="z-entity z-name">from_pooled</span><span>(</span><span class="z-entity z-name">recover_raw_transaction</span><span>(</span><span class="z-keyword">&amp;</span><span class="z-variable z-other">tx</span><span>)</span><span class="z-keyword">?</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> sender</span><span class="z-keyword"> =</span><span class="z-variable z-other"> pool_transaction</span><span class="z-keyword">.</span><span class="z-entity z-name">sender</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> outcome</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span></span> <span class="giallo-l"><span class="z-keyword"> .</span><span>pool</span></span> <span class="giallo-l"><span class="z-keyword"> .</span><span class="z-entity z-name">add_transaction</span><span>(</span><span class="z-entity z-name">TransactionOrigin</span><span class="z-keyword">::</span><span class="z-entity z-name">Local</span><span>,</span><span class="z-variable z-other"> pool_transaction</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> .</span><span class="z-keyword">await</span></span> <span class="giallo-l"><span class="z-keyword"> .</span><span class="z-entity z-name">map_err</span><span>(</span><span class="z-entity z-name">OpEthApiError</span><span class="z-keyword">::</span><span class="z-variable z-other">from_eth_err</span><span>)</span><span class="z-keyword">?</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 transaction is queued (not ready for immediate execution), remove it and return error</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-storage z-type"> let</span><span class="z-entity z-name"> AddedTransactionState</span><span class="z-keyword">::</span><span class="z-entity z-name">Queued</span><span>(</span><span class="z-variable z-other">reason</span><span>)</span><span class="z-keyword"> =</span><span class="z-variable z-other"> outcome</span><span class="z-keyword">.</span><span>state </span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span class="z-keyword">.</span><span>pool</span><span class="z-keyword">.</span><span class="z-entity z-name">remove_transaction</span><span>(</span><span class="z-variable z-other">outcome</span><span class="z-keyword">.</span><span>hash</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> match</span><span class="z-variable z-other"> reason</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> QueuedReason</span><span class="z-keyword">::</span><span class="z-entity z-name">NonceGap</span><span class="z-keyword"> =&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> expected_nonce</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span></span> <span class="giallo-l"><span class="z-keyword"> .</span><span>pending_state</span></span> <span class="giallo-l"><span class="z-keyword"> .</span><span class="z-entity z-name">basic_account</span><span>(</span><span class="z-keyword">&amp;</span><span class="z-variable z-other">sender</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> .</span><span class="z-entity z-name">ok</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> .</span><span class="z-entity z-name">flatten</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> .</span><span class="z-entity z-name">map</span><span>(</span><span class="z-keyword">|</span><span class="z-variable z-other">acc</span><span class="z-keyword">|</span><span class="z-entity z-name"> format!</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x</span><span class="z-string">{</span><span class="z-string">:x</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> acc</span><span class="z-keyword">.</span><span>nonce</span><span>)</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"> Err</span><span>(</span><span class="z-entity z-name">ErrorObject</span><span class="z-keyword">::</span><span class="z-entity z-name">owned</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> ERROR_CODE_NONCE_GAP</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> ERROR_MSG_NONCE_GAP</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> expected_nonce</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 class="z-variable z-other"> _</span><span class="z-keyword"> =&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> Err</span><span>(</span><span class="z-entity z-name">ErrorObject</span><span class="z-keyword">::</span><span class="z-entity z-name">owned</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> ERROR_CODE_UNKNOWN</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> ERROR_MSG_UNKNOWN</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> Some</span><span>(</span><span class="z-variable z-other">hash</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> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> hash</span><span class="z-keyword"> =</span><span class="z-variable z-other"> outcome</span><span class="z-keyword">.</span><span>hash</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> match</span><span class="z-variable z-language"> self</span></span> <span class="giallo-l"><span class="z-keyword"> .</span><span>pending_state</span></span> <span class="giallo-l"><span class="z-keyword"> .</span><span class="z-entity z-name">get_receipt</span><span>(</span><span class="z-variable z-other">hash</span><span>,</span><span class="z-variable z-other"> timeout</span><span class="z-keyword">.</span><span class="z-entity z-name">saturating_sub</span><span>(</span><span class="z-variable z-other">start_time</span><span class="z-keyword">.</span><span class="z-entity z-name">elapsed</span><span>(</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> .</span><span class="z-keyword">await</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> Some</span><span>(</span><span class="z-variable z-other">receipt</span><span>)</span><span class="z-keyword"> =&gt;</span><span class="z-entity z-name"> Ok</span><span>(</span><span class="z-variable z-other">receipt</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> None</span><span class="z-keyword"> =&gt;</span><span class="z-entity z-name"> Err</span><span>(</span><span class="z-entity z-name">ErrorObject</span><span class="z-keyword">::</span><span class="z-entity z-name">owned</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> ERROR_CODE_TIMEOUT</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> ERROR_MSG_TIMEOUT_RECEIPT</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> Some</span><span>(</span><span class="z-variable z-other">hash</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></code></pre> <p>Other implementations such as <code>go-ethereum</code> can utilize a channel to signify receipt availability instead of polling.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>This method does not introduce new security risks beyond those inherent in transaction submission.</li> <li>The node-configured timeout prevents indefinite blocking of RPC calls, protecting nodes from hanging requests.</li> <li>Node implementations should handle timeout responses gracefully and continue monitoring transaction status as needed.</li> <li>Nodes must ensure that the implementation does not degrade performance or cause denial-of-service.</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> 2025-06-11T00:00:00+00:00 2026-02-11T14:48:25+00:00 Julius Lauterbachhttps://github.com/Julius278 https://wg-eips.ritovision.com/7968/

Enable third parties to transfer tokens authorized by a signed message.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces an innovative token transfer processing model designed for third parties, enabling seamless use of Ethereum-based tokens (e.g., <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>) by non-crypto-native actors. The concept allows a third-party payment processor to initiate token transfers on behalf of another party and to cover the associated transaction (gas) fees. The main party (user) always remains the explicit owner of the tokens, which are securely held and referenced under their ownership in the smart contract.</p> <p>The transfer process is two-phased:</p> <ol> <li><strong>Initiation:</strong> The payment processor proposes a token transfer via the smart contract. This proposal is emitted as an on-chain event, including all relevant transfer details and a unique hash of the transaction (“proposal hash”).</li> <li><strong>Approval:</strong> The authorized party (owner) reviews the proposal off-chain and, if in agreement, signs the proposal hash with their private key. This signature is sent to the payment processor, who then submits it to the smart contract. There, the contract verifies the signature and, upon approval, carries out the token transfer in the owner’s name.</li> </ol> <p>To increase security and usability, each proposal includes an explicit expiration time. If the signature is not submitted and verified within the defined validity period, the proposal becomes void and the transfer cannot be executed.</p> <p>To further enhance user safety, the owner is provided with a function that allows transferring all token balances directly to their own address in case the payment processor becomes unresponsive, acts improperly, or if external conditions such as transaction costs change unfavorably.</p> <p>This model empowers entities to integrate blockchain-based payments into their workflows without directly holding or managing cryptocurrencies. All token movements require explicit owner approval, ensuring security and retaining full user control. The payment processor is compensated “off-chain” (e.g., in fiat currency) and is responsible for gas costs.</p> <p>By removing the technical and operational burdens of crypto management from the end user, this approach facilitates broader adoption of tokenized business cases and simplifies enterprise integration.</p> <h2 id="motivation">Motivation</h2> <p>Adoption of blockchain-based payments and tokenized assets in enterprise and conventional business contexts is still often hindered by the need for end-users or business partners to directly manage cryptocurrencies, wallets, and on-chain transactions. For many organizations, the technical, regulatory, and operational burdens associated with self-custody and on-chain fee management present significant entry barriers.</p> <p>This proposal aims to lower these barriers by introducing a model in which a trusted third-party payment processor can manage all blockchain transactions on behalf of a token owner, including paying transaction fees. The owner maintains full control and explicit on-chain ownership of the assets, and must approve all outgoing transfers cryptographically. Payment for the processor's services (including gas reimbursement) can take place off-chain and in fiat currency, which aligns with existing financial workflows and compliance expectations.</p> <p>With an explicit fallback function, owners are further protected, ensuring they can always reclaim direct control over their assets if the processor becomes unresponsive or external conditions change.</p> <p>In summary, this standard facilitates broader and more secure adoption of token-based processes by offloading complexity from end-users, while preserving security, transparency, and user sovereignty.</p> <h2 id="specification">Specification</h2> <h3 id="methods">Methods</h3> <h4 id="smart-contract-that-holds-the-assets-itokenstorage-sol">Smart Contract that holds the assets (<code>ITokenStorage.sol</code>)</h4> <h5 id="transfer-proposal-proposetransaction">Transfer proposal: <code>proposeTransaction</code></h5> <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"> proposeTransaction</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"> amountToSent</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> destinationAddress</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Called from the paymentProcessor/transactionProvider of the storage to initiate a token transfer. Emits a <code>TransactionProposed</code> event. The parameter <code>tokenAddress</code> is the address of the token which should be transferred. The parameter <code>amountToSent</code> is the amount which should be transferred to the desired destination address. The parameter <code>destinationAddress</code> defines the receiver of the defined token. The proposal is stored in the contract and a unique (uint256) hash is generated for it, which is used for the approval process.</p> <h5 id="transfer-completion-completetransaction">Transfer completion: <code>completeTransaction</code></h5> <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"> completeTransaction</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> hash</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></code></pre> <p>Called from the paymentProcessor/transactionProvider of the storage to perform a token transfer. Emits a <code>TransactionCompleted</code> event. The parameter <code>hash</code> is unique identifier of the transaction. The parameter <code>signature</code> is a signed message which only includes the hash. This message is signed by the credentials of the owner, which are used to verify that the owner has approved the transaction. This function includes a verification step to ensure that the signature is valid and corresponds to the owner of the tokens. If the signature is valid, the contract executes the transfer of tokens from the smart contract to the <code>destinationAddress</code> specified in the proposal.</p> <h5 id="fallback-function-sendfundstoowner">Fallback function: <code>sendFundsToOwner</code></h5> <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"> sendFundsToOwner</span><span>(</span><span class="z-support">address</span><span class="z-variable"> tokenAddress</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>This function allows the owner to transfer all tokens held in the contract back to his/her own address. This is a safety measure to ensure that the owner can reclaim their assets if the payment processor becomes unresponsive or if external conditions change unfavorably. Emits a <code>FallbackScenarioExecuted</code> event. The parameter <code>tokenAddress</code> is the address of the token which should be transferred to the owner. In case this method is called, the contract will transfer all tokens of the given type to the owner address.</p> <h4 id="verification-of-the-signature-verifysignature">Verification of the signature: 'verifySignature'</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"> verifySignature</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _signer</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"> uint256</span><span class="z-variable"> amountToSent</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> destinationAddress</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"> signature</span></span> <span class="giallo-l"><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></code></pre> <p>This function is used to verify the signature of the owner. It checks if the signature corresponds to the provided parameters and the owner's address. The parameter <code>_signer</code> is the address of the owner who signed the proposal. The parameter <code>tokenAddress</code> is the address of the token which should be transferred. The parameter <code>amountToSent</code> is the amount which should be transferred to the desired destination address. The parameter <code>destinationAddress</code> defines the receiver of the defined token. The parameter <code>signature</code> is the signed message which only includes the hash of the proposal.</p> <p>This function can be called by the owner to verify the signature before forwarding it to the paymentProcessor / transactionProvider. Also this function should be called within the <code>completeTransaction</code> function to ensure that the signature is valid before executing the transfer.</p> <h5 id="summary">Summary</h5> <p>The interface <code>ITokenStorage.sol</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"> ITokenStorage</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransactionProposed</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> hash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransactionCompleted</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> hash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FallbackScenarioExecuted</span><span>(</span><span class="z-support">address</span><span class="z-variable"> tokenAddress</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"> proposeTransaction</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"> amountToSent</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> destinationAddress</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"> completeTransaction</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> hash</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 class="z-storage z-type"> function</span><span class="z-entity z-name"> sendFundsToOwner</span><span>(</span><span class="z-support">address</span><span class="z-variable"> tokenAddress</span><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> <p>tbd <!-- TODO --></p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <!-- TODO: Reference implementation --> <!-- TODO: Test cases --> <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> 2025-06-11T00:00:00+00:00 2026-02-11T14:48:25+00:00 Mike Fuhttps://github.com/fumeng00mike Matthew Yuhttps://github.com/0xknon Ernesto Garcíahttps://github.com/ernestognw https://wg-eips.ritovision.com/7969/

A registry for DKIM public key hashes, enabling on-chain verification.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a standard interface for registering and validating DomainKeys Identified Mail (DKIM) public key hashes on the Ethereum blockchain. The interface allows domain owners to register their DKIM public key hashes and enables third parties to verify the validity of these hashes.</p> <p>The registry operates by storing hashes of both domain names and DKIM public keys, creating a mapping that enables on-chain verification of DKIM signatures. Domain owners register their DKIM public key hashes by extracting the public key from their DNS TXT records (as specified in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc6376">RFC 6376</a>), computing the hash, and submitting it to the registry. DKIM clients can then query the registry to verify that a given public key hash is authorized for a specific domain, enabling trustless email ownership verification for applications such as account abstraction and social recovery mechanisms.</p> <h2 id="motivation">Motivation</h2> <p>With the growing adoption of Account Abstraction <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> and the emergence of ZK Email Technology, there is a need for a standardized way to verify email ownership on-chain. This EIP provides a crucial building block for these technologies by enabling the verification of DKIM signatures through on-chain registries.</p> <p>This standard enables several important use cases:</p> <ol> <li><strong>Account Abstraction</strong>: When combined with zkEmail, this registry enables email-based account abstraction. Users can prove ownership of their email address through DKIM signatures, allowing them to: <ul> <li>Create and manage smart contract wallets</li> <li>Sign transactions using their email credentials</li> <li>Implement social recovery mechanisms</li> </ul> </li> <li><strong>Account Recovery</strong>: The registry facilitates secure account recovery mechanisms: <ul> <li>Users can recover their wallet access by on-chain proving email ownership</li> <li>The process is trustless and secure due to the cryptographic nature of DKIM</li> </ul> </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> <h3 id="interface">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"> ^0.8.25</span><span>;</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-</span><span class="z-keyword">XXX</span><span class="z-comment"> DKIM Registry Interface</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-</span><span class="z-keyword">xxx</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 0xdee3d600.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IDKIMRegistry</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> KeyHashRegistered</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> domainHash</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> keyHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> KeyHashRevoked</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> domainHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isKeyHashValid</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> domainHash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> keyHash</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></span></code></pre><h3 id="domain-hash">Domain Hash</h3> <p>The <code>domainHash</code> parameter MUST be the hash of the lowercase domain name or subdomain name. For example:</p> <ul> <li>For the domain "example.com" using keccak256:</li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>domainHash </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-support">bytes</span><span>(</span><span class="z-string">&quot;example.com&quot;</span><span>)</span><span>)</span></span></code></pre> <ul> <li>For the subdomain "mail.example.com" using keccak256:</li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>domainHash </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-support">bytes</span><span>(</span><span class="z-string">&quot;mail.example.com&quot;</span><span>)</span><span>)</span></span></code></pre> <p>The registry MUST treat each domain and subdomain as a distinct entity. This means that:</p> <ol> <li>A key hash registered for "example.com" does not automatically apply to its subdomains</li> <li>Each subdomain can have its own independent DKIM key hash registration</li> <li>The full domain name (including subdomain if present) must be hashed as a single string</li> </ol> <h3 id="key-hash">Key Hash</h3> <p>The <code>keyHash</code> parameter MUST be a cryptographic hash of the DKIM public key. The public key should be in the standard DKIM format as specified in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc6376">RFC 6376</a>.</p> <p>Implementations MAY choose any cryptographically secure hash function for computing the key hash. Common choices include keccak256, Poseidon (for zk-friendly applications) or other hash functions.</p> <h3 id="dkim-public-key-specification">DKIM Public Key Specification</h3> <p>The DKIM public key MUST follow the format specified in RFC 6376. Here are the key requirements:</p> <ol> <li> <p><strong>Key Format</strong>:</p> <ul> <li>The public key MUST be in the format specified in the DKIM DNS record (p=PUBLIC_KEY)</li> <li>The key MUST be base64 encoded</li> <li>The key MUST NOT include the PEM headers or any other formatting</li> <li>The key MUST be the raw public key data as specified in the DKIM DNS record</li> </ul> </li> <li> <p><strong>Key Requirements</strong>:</p> <ul> <li>The key MUST be a valid RSA public key</li> <li>The key MUST be in the format as published in the domain's DNS TXT record</li> <li>The key MUST be the exact value from the p= parameter in the DKIM DNS record</li> <li>The key MUST NOT include any whitespace or line breaks</li> </ul> </li> <li> <p><strong>Key Registration Process</strong>:</p> <ol> <li>Obtain the DKIM public key from the domain's DNS TXT record</li> <li>Extract the value from the p= parameter</li> <li>Calculate the hash of the raw public key using the implementation's chosen hash function</li> <li>Register the hash in the DKIM registry</li> </ol> </li> <li> <p><strong>Key Validation</strong>:</p> <ul> <li>The registry MUST verify that the provided key hash corresponds to a valid DKIM public key</li> <li>The key MUST be in the correct format as specified in RFC 6376</li> <li>The key MUST be the exact value as published in the domain's DNS record</li> </ul> </li> <li> <p><strong>Example with keccak256</strong>:</p> <p>Given the following DKIM DNS record from RFC 6376:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>$ORIGIN _domainkey.example.org.</span></span> <span class="giallo-l"><span>brisbane IN TXT (&quot;v=DKIM1; p=MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQ&quot;</span></span> <span class="giallo-l"><span> &quot;KBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYt&quot;</span></span> <span class="giallo-l"><span> &quot;IxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v&quot;</span></span> <span class="giallo-l"><span> &quot;/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhi&quot;</span></span> <span class="giallo-l"><span> &quot;tdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB&quot;)</span></span> <span class="giallo-l"><span> ```</span></span></code></pre> <p>The process to register this key would be:</p> <ol> <li>Extract the public key value from the p= parameter:</li> </ol> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB</span></span></code></pre></li> <li> <p>Calculate the keccak256 hash of the public key:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes32</span><span> keyHash </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-support">bytes</span><span>(</span><span class="z-string">&quot;MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDwIRP/UC3SBsEmGqZ9ZJW3/DkMoGeLnQg1fWn7/zYtIxN2SnFCjxOCKG9v3b4jYfcTNh5ijSsq631uBItLa7od+v/RtdC2UzJ1lWT947qR+Rcac2gbto/NMqJ0fzfVjH4OuKhitdY9tf6mcwGjaNBcWToIMmPSPDdQPNUYckcQ2QIDAQAB&quot;</span><span>)</span><span>)</span><span>;</span></span></code></pre> <ol start="3"> <li>Calculate the domain hash:</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes32</span><span> domainHash </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-support">bytes</span><span>(</span><span class="z-string">&quot;example.org&quot;</span><span>)</span><span>)</span><span>;</span></span></code></pre> <ol start="4"> <li>Register the key hash in the registry:</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>registry</span><span>.</span><span class="z-entity z-name">setKeyHash</span><span>(</span><span>domainHash</span><span>,</span><span> keyHash</span><span>)</span><span>;</span></span></code></pre></li> </ol> <h3 id="events">Events</h3> <h4 id="keyhashregistered">KeyHashRegistered</h4> <p>This event MUST be emitted when a new DKIM public key hash is registered for a domain.</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"> KeyHashRegistered</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> domainHash</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> keyHash</span><span>)</span></span></code></pre><h4 id="keyhashrevoked">KeyHashRevoked</h4> <p>This event MUST be emitted when a DKIM public key hash is revoked for a domain.</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"> KeyHashRevoked</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> domainHash</span><span>)</span></span></code></pre><h3 id="functions">Functions</h3> <h4 id="iskeyhashvalid">isKeyHashValid</h4> <p>This function MUST return <code>true</code> if the provided key hash is valid for the given domain hash, and <code>false</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"> isKeyHashValid</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> domainHash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> keyHash</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></code></pre><h2 id="rationale">Rationale</h2> <p>The interface is designed to be simple and focused on the core functionality of DKIM public key hash registration and validation. The use of keccak256 hashing for both domain names and public keys ensures consistent and secure handling of the data.</p> <p>The events allow for efficient tracking of key registrations and revocations, which is important for maintaining the integrity of the registry.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces a new interface and does not affect existing contracts or 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-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 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 class="z-keyword">import</span><span class="z-string"> &quot;./interfaces/IDKIMRegistry.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> DKIMRegistry</span><span class="z-storage"> is</span><span class="z-entity z-name"> IDKIMRegistry</span><span>, </span><span class="z-entity z-name">Ownable</span><span> {</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-entity z-name"> Ownable</span><span>(</span><span>_owner) </span><span>{</span><span> }</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Mapping from hashed domain name to DKIM public key hash to enabled</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">bytes32</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> _keyHashes</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"> Checks if a DKIM key hash is valid for a given domain</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> domainHash</span><span class="z-comment"> The hash of the domain 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"> keyHash</span><span class="z-comment"> The hash of the DKIM public key</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"> True if the key hash is valid for the domain, 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"> isKeyHashValid</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> domainHash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> keyHash</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">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _keyHashes</span><span>[</span><span>domainHash</span><span>]</span><span>[</span><span>keyHash</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"> Sets a DKIM key hash for a domain</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> domainHash</span><span class="z-comment"> The hash of the domain 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"> keyHash</span><span class="z-comment"> The hash of the DKIM public key to register</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Only callable by the contract owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Cannot set zero hash as a valid key hash</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"> setKeyHash</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> domainHash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> keyHash</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></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>keyHash </span><span class="z-keyword">!=</span><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-string"> &quot;cannot set zero hash&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _keyHashes</span><span>[</span><span>domainHash</span><span>]</span><span>[</span><span>keyHash</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> KeyHashRegistered</span><span>(</span><span>domainHash</span><span>,</span><span> keyHash</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"> Sets multiple DKIM key hashes for a domain in a single 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"> domainHash</span><span class="z-comment"> The hash of the domain 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"> keyHashes</span><span class="z-comment"> Array of DKIM public key hashes to register</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Only callable by the contract owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Array must not be empty</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Each key hash must not be zero</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"> setKeyHashes</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> domainHash</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"> keyHashes</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></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>keyHashes</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;empty array&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> keyHashes</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-entity z-name"> setKeyHash</span><span>(</span><span>domainHash</span><span>,</span><span> keyHashes</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> }</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"> Revokes a DKIM key hash for a domain</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> domainHash</span><span class="z-comment"> The hash of the domain 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"> keyHash</span><span class="z-comment"> The hash of the DKIM public key to revoke</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Only callable by the contract owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Sets the key hash mapping to false, effectively revoking it</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"> revokeKeyHash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> domainHash</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> keyHash</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 class="z-keyword"> delete</span><span> _keyHashes</span><span>[</span><span>domainHash</span><span>]</span><span>[</span><span>keyHash</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> KeyHashRevoked</span><span>(</span><span>domainHash</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> <ol> <li>Domain owners must ensure they have control over their private keys and domain names.</li> <li>The registry implementation should include proper access control mechanisms to prevent unauthorized registrations.</li> <li>The registry should implement a mechanism to handle key rotation and revocation.</li> <li>Implementations should consider rate limiting to prevent spam registrations.</li> <li>Registries should select the <code>domainHash</code> and <code>keyHash</code> algorithms carefully. Upgrading the hash function must be thoughtfully planned.</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> 2025-06-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Dario Lo Bugliohttps://github.com/xaler5 Tino Martinez Molinahttps://github.com/tinom9 Mihai Colceriuhttps://github.com/mihaic195 https://wg-eips.ritovision.com/7943/

Interfaces for common base tokens defining compliance checks, transfer controls, and enforcement actions for Real World Assets (RWAs).

<h2 id="abstract">Abstract</h2> <p>This EIP proposes the Universal RWA (uRWA) standard, a set of interfaces for tokenized Real World Assets (RWAs) such as securities, real estate, commodities, or other physical/financial assets on the blockchain.</p> <p>Real World Assets often require regulatory compliance features not found in standard tokens, including the ability to freeze assets, perform enforcement transfers for legal compliance, and restrict transfers to authorized users. The uRWA standard extends common token standards like <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> by introducing essential compliance functions while remaining minimal and not opinionated about specific implementation details.</p> <p>This enables DeFi protocols and applications to interact with tokenized real-world assets in a standardized way, knowing they can check transfer permissions, whether users are allowed to interact, handle frozen assets appropriately, and integrate with compliant RWA tokens regardless of the underlying asset type or internal compliance logic. It also adopts <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> for introspection.</p> <h2 id="motivation">Motivation</h2> <p>Real World Assets (RWAs) represent a significant opportunity to bridge traditional finance and decentralized finance (DeFi). By tokenizing assets like real estate, corporate bonds, commodities, art, or securities, we can unlock benefits such as fractional ownership, programmable compliance, enhanced liquidity through secondary markets for traditionally illiquid assets and integration with decentralized protocols.</p> <p>However, tokenizing real world assets introduces regulatory requirements often absent in purely digital assets, such as allowlists for users, transfer restrictions, asset freezing, or law enforcement rules. Existing token standards like <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> lack the inherent structure to address these compliance needs directly within the standard itself.</p> <p>Attempts at defining universal RWA standards historically imposed unnecessary complexity and gas overhead for simpler use cases that do not require the full spectrum of features like granular role-based access control, mandatory on-chain whitelisting, specific on-chain identity solutions, or metadata handling solutions mandated by the standard.</p> <p>Additionally, the broad spectrum of RWA classes inherently suggests the need to move away from a one-size-fits-all solution. This means a minimalistic approach, unopinionated features list, and maximally compatible design have been kept in mind as design goals.</p> <p>The uRWA standard seeks a more refined balance by defining an essential interface, establishing a common ground for interaction regarding compliance and control, without dictating the underlying implementation mechanisms. This allows core token implementations to remain lean while providing standard functions for RWA-specific interactions.</p> <p>The final goal is to build composable DeFi around RWAs, providing the same interface when dealing with compliance and regulation.</p> <h2 id="specification">Specification</h2> <p>The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", and "MAY" in this document are to be interpreted as described in RFC 2119 and RFC 8174.</p> <p>The following defines the standard interfaces for an <a href="https://wg-eips.ritovision.com/7943/">ERC-7943</a> token contract, which MUST extend from one base token interface such as <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>:</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"> @notice</span><span class="z-comment"> Interface for ERC-20 based implementations.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7943Fungible</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"> @notice</span><span class="z-comment"> Emitted when tokens are taken from one address and transferred to another.</span></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 tokens were taken.</span></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 seized tokens were transferred.</span></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"> The amount seized.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ForcedTransfer</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"> 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"> @notice</span><span class="z-comment"> Emitted when `setFrozenTokens` is called, changing the frozen `amount` of tokens for `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 address of the account whose tokens are being frozen.</span></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"> The amount of tokens frozen after the change.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Frozen</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 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"> @notice</span><span class="z-comment"> Error reverted when an account is not allowed to transact. </span></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 of the account which is not allowed for transfers.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC7943CannotTransact</span><span>(</span><span class="z-support">address</span><span> account</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"> Error reverted when a transfer is not allowed according to internal rules. </span></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 tokens are being sent.</span></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 tokens are being sent.</span></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"> The amount sent.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC7943CannotTransfer</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> 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"> @notice</span><span class="z-comment"> Error reverted when a transfer is attempted from `account` with an `amount` less than or equal to its balance, but greater than its unfrozen balance.</span></span> <span 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 holding the 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"> The amount being transferred.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> unfrozen</span><span class="z-comment"> The amount of tokens that are unfrozen and available to transfer.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC7943InsufficientUnfrozenBalance</span><span>(</span><span class="z-support">address</span><span> account</span><span>,</span><span class="z-support"> uint256</span><span> amount</span><span>,</span><span class="z-support"> uint256</span><span> unfrozen</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"> Takes tokens from one address and transfers them to another.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Requires specific authorization. Used for regulatory compliance or recovery scenarios.</span></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 `amount` is taken.</span></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 receives `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"> amount</span><span class="z-comment"> The amount to force transfer.</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"> True if the transfer executed correctly. Reverts on failure.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> forcedTransfer</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 class="z-variable"> result</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"> Changes the frozen status of `amount` tokens belonging to `account`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This overwrites the current value, similar to an `approve` function.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Requires specific authorization. Frozen tokens cannot be transferred by 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 address of the account whose tokens are to be frozen.</span></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"> The amount of tokens to freeze. It can be greater than account 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"> result</span><span class="z-comment"> True if the freezing executed correctly. Reverts on failure.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setFrozenTokens</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"> 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 class="z-variable"> result</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"> Checks if a specific account is allowed to transact according to token rules.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This is often used for allowlist/KYC/KYB/AML checks.</span></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 to check.</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"> allowed</span><span class="z-comment"> True if the account is allowed, false otherwise.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canTransact</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">bool</span><span class="z-variable"> allowed</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"> Checks the frozen status/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"> account</span><span class="z-comment"> The address of the account.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> It could return an amount higher than the account&#39;s 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"> amount</span><span class="z-comment"> The amount of tokens currently frozen for `account`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getFrozenTokens</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 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"> @notice</span><span class="z-comment"> Checks if a transfer is currently possible according to token rules. It enforces validations on the frozen tokens.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This can involve checks like allowlists, blocklists, transfer limits and other policy-defined restrictions.</span></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 sending 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 receiving 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"> The amount being transferred.</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"> allowed</span><span class="z-comment"> True if the transfer is allowed, false otherwise.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canTransfer</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-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> allowed</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"> @notice</span><span class="z-comment"> Interface for ERC-721 based implementations.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7943NonFungible</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"> @notice</span><span class="z-comment"> Emitted when `tokenId` is taken from one address and transferred to another.</span></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 `tokenId` is taken.</span></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 seized `tokenId` is transferred.</span></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 ID of the token being transferred.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ForcedTransfer</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"> 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"> Emitted when `setFrozenTokens` is called, changing the frozen status of `tokenId` for `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 address of the account whose `tokenId` is subjected to freeze/unfreeze.</span></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 ID of the token subjected to freeze/unfreeze.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> frozenStatus</span><span class="z-comment"> Whether `tokenId` has been frozen or unfrozen.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Frozen</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 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">bool</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> frozenStatus</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"> Error reverted when an account is not allowed to transact. </span></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 of the account which is not allowed for transfers.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC7943CannotTransact</span><span>(</span><span class="z-support">address</span><span> account</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"> Error reverted when a transfer is not allowed according to internal rules. </span></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 tokens are being sent.</span></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 tokens are being sent.</span></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 id of the token being sent.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC7943CannotTransfer</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> 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"> Error reverted when a transfer is attempted from `account` with a `tokenId` which has been previously frozen.</span></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 holding the token with `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"> tokenId</span><span class="z-comment"> The ID of the token being frozen and unavailable to be transferred. </span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC7943InsufficientUnfrozenBalance</span><span>(</span><span class="z-support">address</span><span> account</span><span>,</span><span class="z-support"> uint256</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-storage z-type"> @notice</span><span class="z-comment"> Takes `tokenId` from one address and transfers it to another.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Requires specific authorization. Used for regulatory compliance or recovery scenarios.</span></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 `tokenId` is taken.</span></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 receives `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"> tokenId</span><span class="z-comment"> The ID of the token being transferred.</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"> True if the transfer executed correctly. Reverts on failure.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> forcedTransfer</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"> 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"> result</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"> Changes the frozen status of `tokenId` belonging to an `account`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This overwrites the current value, similar to an `approve` function.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Requires specific authorization. Frozen tokens cannot be transferred by 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 address of the account whose tokens are to be frozen.</span></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 ID of the token to freeze.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> frozenStatus</span><span class="z-comment"> Whether `tokenId` is being frozen or 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"> result</span><span class="z-comment"> True if the freezing executed correctly. Reverts on failure.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setFrozenTokens</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"> tokenId</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> frozenStatus</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Checks if a specific account is allowed to transact according to token rules.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This is often used for allowlist/KYC/KYB/AML checks.</span></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 to check.</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"> allowed</span><span class="z-comment"> True if the account is allowed, false otherwise.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canTransact</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">bool</span><span class="z-variable"> allowed</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"> Checks the frozen status of a specific `tokenId`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> It could return true even if account does not hold 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"> account</span><span class="z-comment"> The address 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"> tokenId</span><span class="z-comment"> The ID 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"> frozenStatus</span><span class="z-comment"> Whether `tokenId` is currently frozen for `account`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getFrozenTokens</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"> 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 class="z-variable"> frozenStatus</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"> Checks if a transfer is currently possible according to token rules. It enforces validations on the frozen tokens.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This can involve checks like allowlists, blocklists, transfer limits and other policy-defined restrictions.</span></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 sending 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 receiving 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 ID of the token being transferred.</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"> allowed</span><span class="z-comment"> True if the transfer is allowed, false otherwise.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canTransfer</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"> 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 class="z-variable"> allowed</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"> @notice</span><span class="z-comment"> Interface for ERC-1155 based implementations.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7943MultiToken</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"> @notice</span><span class="z-comment"> Emitted when tokens are taken from one address and transferred to another.</span></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 tokens were taken.</span></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 seized tokens were transferred.</span></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 ID of the token being transferred.</span></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"> The amount seized.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ForcedTransfer</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"> tokenId</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"> @notice</span><span class="z-comment"> Emitted when `setFrozenTokens` is called, changing the frozen `amount` of `tokenId` tokens for `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 address of the account whose tokens are being frozen.</span></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 ID of the token being frozen.</span></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"> The amount of tokens frozen after the change.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Frozen</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 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"> 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"> @notice</span><span class="z-comment"> Error reverted when an account is not allowed to transact. </span></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 of the account which is not allowed for transfers.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC7943CannotTransact</span><span>(</span><span class="z-support">address</span><span> account</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"> Error reverted when a transfer is not allowed according to internal rules. </span></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 tokens are being sent.</span></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 tokens are being sent.</span></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 id of the token being sent.</span></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"> The amount sent.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC7943CannotTransfer</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> tokenId</span><span>,</span><span class="z-support"> uint256</span><span> 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"> @notice</span><span class="z-comment"> Error reverted when a transfer is attempted from `account` with an `amount` of `tokenId` less than or equal to its balance, but greater than its unfrozen balance.</span></span> <span 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 holding the `amount` of `tokenId` 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 ID of the token being transferred. </span></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"> The amount of `tokenId` tokens being transferred.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> unfrozen</span><span class="z-comment"> The amount of tokens that are unfrozen and available to transfer.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC7943InsufficientUnfrozenBalance</span><span>(</span><span class="z-support">address</span><span> account</span><span>,</span><span class="z-support"> uint256</span><span> tokenId</span><span>,</span><span class="z-support"> uint256</span><span> amount</span><span>,</span><span class="z-support"> uint256</span><span> unfrozen</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"> Takes tokens from one address and transfers them to another.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Requires specific authorization. Used for regulatory compliance or recovery scenarios.</span></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 `amount` is taken.</span></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 receives `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"> tokenId</span><span class="z-comment"> The ID of the token being transferred.</span></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"> The amount to force transfer.</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"> True if the transfer executed correctly. Reverts on failure.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> forcedTransfer</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"> tokenId</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 class="z-variable"> result</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"> Changes the frozen status of `amount` of `tokenId` tokens belonging to an `account`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This overwrites the current value, similar to an `approve` function.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Requires specific authorization. Frozen tokens cannot be transferred by 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 address of the account whose tokens are to be frozen.</span></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 ID of the token to freeze.</span></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"> The amount of tokens to freeze. It can be greater than account 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"> result</span><span class="z-comment"> True if the freezing executed correctly. Reverts on failure.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setFrozenTokens</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"> tokenId</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 class="z-variable"> result</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"> Checks if a specific account is allowed to transact according to token rules.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This is often used for allowlist/KYC/KYB/AML checks.</span></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 to check.</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"> allowed</span><span class="z-comment"> True if the account is allowed, false otherwise.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canTransact</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">bool</span><span class="z-variable"> allowed</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"> Checks the frozen status/amount of a specific `tokenId`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> It could return an amount higher than the account&#39;s 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"> account</span><span class="z-comment"> The address 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"> tokenId</span><span class="z-comment"> The ID 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"> amount</span><span class="z-comment"> The amount of `tokenId` tokens currently frozen for `account`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getFrozenTokens</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"> 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 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"> @notice</span><span class="z-comment"> Checks if a transfer is currently possible according to token rules. It enforces validations on the frozen tokens.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This can involve checks like allowlists, blocklists, transfer limits and other policy-defined restrictions.</span></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 sending 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 receiving 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 ID of the token being transferred.</span></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"> The amount being transferred.</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"> allowed</span><span class="z-comment"> True if the transfer is allowed, false otherwise.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canTransfer</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"> tokenId</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"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> allowed</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="cantransact-cantransfer-and-getfrozentokens"><code>canTransact</code>, <code>canTransfer</code> and <code>getFrozenTokens</code></h3> <p>These provide views into the implementing contract's compliance, transfer policy logic and freezing status. These functions:</p> <ul> <li> <p>MUST NOT revert.</p> </li> <li> <p>MUST NOT change the storage of the contract.</p> </li> <li> <p>MAY depend on context (e.g., current timestamp, block number or <code>msg.sender</code>).</p> </li> <li> <p>The <code>canTransfer</code></p> <ul> <li>MUST validate that the <code>amount</code> being transferred doesn't exceed the unfrozen amount (which is the difference between the current balance and the frozen balance).</li> <li>MUST perform a <code>canTransact</code> check on the <code>from</code> and <code>to</code> parameters. An important documentation note is that <a href="https://wg-eips.ritovision.com/3643/">ERC-3643</a> doesn't perform a <code>canTransact</code> check within <code>canTransfer</code> as required.</li> <li>MUST return false in general, if any permissioned rule would prevent a given transfer from succeeding. A transfer refers to any operation that emits the token’s canonical transfer event. A permissioned check can be a pausing mechanism, a call to <code>canTransact</code> or anything else that requires privileged actors.</li> </ul> </li> <li> <p><code>getFrozenTokens</code> will return the absolute frozen amount, which MAY exceed the account's current balance. In <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens, it MAY return true even if the account does not hold the token.</p> </li> </ul> <h3 id="forcedtransfer"><code>forcedTransfer</code></h3> <p>This function provides a standard mechanism for forcing a transfer from a <code>from</code> to a <code>to</code> address. The function:</p> <ul> <li>MUST directly manipulate balances or ownership to transfer the asset from <code>from</code> to <code>to</code> either by transferring or burning from <code>from</code> and minting to <code>to</code>.</li> <li>MUST be restricted in access.</li> <li>MUST perform necessary validation checks (e.g., sufficient balance/ownership of a specific token).</li> <li>MUST emit both the standard transfer event (from the base standard) and the <code>ForcedTransfer</code> event.</li> <li>In single-party permissioned contexts: <ul> <li>It MAY bypass the <code>canTransfer</code> checks. If this happens, and the transfer involves tokens that are currently counted as frozen, it MUST unfreeze the assets first and emit a <code>Frozen</code> event before the underlying base token transfer event reflecting the change. Having the unfrozen amount changed before the actual transfer is critical for tokens that might be susceptible to reentrancy attacks doing external checks on recipients as it is the case for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> tokens.</li> <li>It SHOULD at least perform a <code>canTransact</code> check on the <code>to</code> parameter to ensure compliance.</li> </ul> </li> <li>In multi-party permissioned contexts: <ul> <li>It SHOULD perform the <code>canTransfer</code> checks and SHOULD NOT bypass the frozen constraints.</li> </ul> </li> <li>MUST revert in cases where validations and/or <code>canTransact</code> checks return false or fail.</li> </ul> <h3 id="setfrozentokens"><code>setFrozenTokens</code></h3> <p>It provides a way to freeze or unfreeze assets held by a specific account. This is useful for temporary lock mechanisms. This function:</p> <ul> <li>MUST emit the <code>Frozen</code> event.</li> <li>MUST be restricted in access.</li> <li>MUST allow freezing more assets than those held. This allows for future balances withholding.</li> <li>MUST revert in cases of logical issues or validation checks failure.</li> </ul> <h3 id="additional-specifications">Additional Specifications</h3> <p>The contract MUST implement the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> <code>supportsInterface</code> function and MUST return true for the <code>bytes4</code> value (representing the <code>interfaceId</code>):</p> <ul> <li><code>0x29388973</code> for the fungible interface.</li> <li><code>0xa8fdc849</code> for the non-fungible interface.</li> <li><code>0x5627c61a</code> for the multi token interface.</li> </ul> <p>Implementations of these interfaces MUST implement the necessary functions of their chosen base standard (e.g., <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> for the fungible interface, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> for the non-fungible interface and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> for the multi token interface) and MUST also restrict access to sensitive functions like <code>forcedTransfer</code> and <code>setFrozenTokens</code> using an appropriate access control mechanism (e.g., <code>onlyOwner</code>, Role-Based Access Control). The specific mechanism is NOT mandated by this interface standard.</p> <p>Implementations MUST ensure their transfer methods exhibit the following behavior:</p> <ul> <li><strong>Public transfers</strong> (<code>transfer</code>, <code>transferFrom</code>, <code>safeTransferFrom</code>, etc.) MUST NOT succeed in cases in which <code>canTransfer</code> or <code>canTransact</code> would return <code>false</code> for either one or both <code>from</code> and <code>to</code> addresses.</li> <li><strong>Minting</strong> in permissionless contexts (e.g., public <code>mint</code> functions) MUST NOT succeed for accounts where <code>canTransact</code> on the recipient would return <code>false</code>. In permissioned contexts (e.g., authorized minting by privileged roles), minting SHOULD respect <code>canTransact</code> checks on the recipient, though implementations MAY bypass these checks when necessary for operational or compliance reasons.</li> <li><strong>Burning</strong> in permissionless contexts (e.g., public <code>burn</code> functions) MUST respect <code>canTransfer</code> check, MUST respect the <code>canTransact</code> check on the token holder and MUST NOT allow burning more assets than the unfrozen amount. In permissioned contexts (e.g., authorized burning by privileged roles), burning MAY succeed for accounts where <code>canTransact</code> on the token holder would return <code>false</code>, and MAY burn more assets than the unfrozen amount, in which case the contract MUST update the frozen status accordingly and emit a <code>Frozen</code> event before the underlying base token transfer event.</li> </ul> <p>The <code>ERC7943CannotTransact</code>/<code>ERC7943CannotTransfer</code> errors MAY be used as a general revert mechanism whenever internal calls to <code>canTransact</code>/<code>canTransfer</code> return false. They MAY be replaced by more specific errors depending on the custom checks performed inside those calls, or simply not used.</p> <p>In general, the standard prioritizes error specificity, meaning that specific errors such as <code>ERC7943InsufficientUnfrozenBalance</code> SHOULD be thrown when applicable. The <code>ERC7943InsufficientUnfrozenBalance</code> error SHOULD be triggered when a transfer is attempted from <code>account</code> with an <code>amount</code> less than or equal to its balance, but greater than its unfrozen balance or with a <code>tokenId</code> which is currently frozen. If the <code>amount</code> is greater than the whole balance or the <code>tokenId</code> is not owned by the <code>account</code>, unrelated from the frozen amount, more specific errors from the base standard SHOULD be used instead.</p> <h2 id="rationale">Rationale</h2> <ul> <li><strong>Minimalism:</strong> Defines only the essential functions (<code>forcedTransfer</code>, <code>setFrozenTokens</code>, <code>canTransact</code>, <code>canTransfer</code>, <code>getFrozenTokens</code>) and associated events/errors needed for common RWA compliance and control patterns, avoiding mandated complexity or opinionated features. The reason to introduce specific errors (<code>ERC7943CannotTransact</code>, <code>ERC7943CannotTransfer</code> and <code>ERC7943InsufficientUnfrozenBalance</code>) is to provide completeness with the introduced functionalities (<code>canTransact</code>, <code>canTransfer</code> and <code>getFrozenTokens</code>). As dictated in the specifications, error specificity is prioritized, leaving space for implementations to accommodate more explicit errors. Regarding the events <code>Frozen</code> and <code>ForcedTransfer</code>, the reason for their existence is to signal <em>uncommon</em> transfers (like in <code>forcedTransfer</code>) but also to help off-chain indexers to correctly keep track and account for asset seizures and freezing. As mentioned in the specifications, the order in which these events are emitted in relation to the base token contract events is important in practice and merits special attention.</li> <li><strong>Flexible compliance:</strong> Provides standard view functions (<code>canTransact</code>, <code>canTransfer</code>, <code>getFrozenTokens</code>) for compliance checks without dictating <em>how</em> those checks are implemented internally by the token contract. This allows diverse compliance strategies.</li> <li><strong>Compatibility:</strong> Designed as an interface layer compatible with existing base standards like <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>. Implementations extend from <a href="https://wg-eips.ritovision.com/7943/">ERC-7943</a> alongside their base standard interface. Additionally, with the adopted naming conventions, automatic backward compatibility is achieved with already existing standards like <a href="https://wg-eips.ritovision.com/3643/">ERC-3643</a> and <a href="https://wg-eips.ritovision.com/7518/">ERC-7518</a>.</li> <li><strong>Essential enforcement rules:</strong> Includes <code>forcedTransfer</code> and <code>setFrozenTokens</code> as standard functions, acknowledging their importance for regulatory enforcement in the RWA space, distinct from standard transfers. Mandates access control for this sensitive function. To maintain a lean EIP, a single <code>setFrozenTokens</code> function (which overwrites the frozen asset quantity) and one <code>Frozen</code> event were favored over distinct <code>freeze</code>/<code>unfreeze</code> functions and events.</li> <li><strong><a href="https://wg-eips.ritovision.com/165/">ERC-165</a>:</strong> Ensures implementing contracts can signal support for this interface.</li> </ul> <p>As an example, an AMM pool or a lending protocol can integrate with <a href="https://wg-eips.ritovision.com/7943/">ERC-7943</a> based <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens by calling <code>canTransact</code> or <code>canTransfer</code> to handle these assets in a compliant manner. Enforcement actions like <code>forcedTransfer</code> and <code>setFrozenTokens</code> can either be called by third party entities or be integrated by external protocols to allow for automated and programmable compliance. Users can then expand these tokens with additional features to fit the specific needs of individual asset types, either with on-chain identity systems, historical balances tracking for dividend distributions, semi-fungibility with token metadata, and other custom functionalities.</p> <h3 id="extensibility">Extensibility</h3> <p>While this ERC provides the necessary primitives for regulated assets, any additional feature can be added through extensions. Few examples:</p> <ol> <li>If for any administrative function like <code>setFrozenTokens</code> it is necessary to attach a proof to the call, the contract can have a function that batches operations like:</li> </ol> <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"> TokenWithLegalProofs</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7943MultiToken</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-storage z-type"> function</span><span class="z-entity z-name"> setFrozenTokensWithProof</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"> tokenId</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"> calldata</span><span class="z-variable"> legalProof</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 class="z-variable"> result</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> do anything with `legalProof`</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> setFrozenTokens</span><span>(</span><span>account</span><span>,</span><span> tokenId</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></code></pre> <ol start="2"> <li>Since the <code>setFrozenTokens</code> function overwrites the absolute frozen amount and given the fact that the standard allows for multiple privileged accounts, some race-conditions might happen. If that's the case, one can build an extension function that works with expected values of amounts frozen, like:</li> </ol> <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"> setFrozenTokensIf</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"> expectedPrev</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> newAmount</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 class="z-variable"> result</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>frozenTokens</span><span>[</span><span>account</span><span>]</span><span class="z-keyword"> ==</span><span> expectedPrev</span><span>,</span><span class="z-entity z-name"> ERC7943ExpectedValueMismatch</span><span>(</span><span>expectedPrev</span><span>,</span><span> frozenTokens</span><span>[</span><span>account</span><span>]</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> setFrozenTokens</span><span>(</span><span>account</span><span>,</span><span>newAmount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Alternatively, another solution can be using delta amounts:</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"> setFrozenTokensDelta</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>,</span><span class="z-support"> int256</span><span class="z-variable"> deltaAmount</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 class="z-variable"> result</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> actualValue </span><span class="z-keyword">=</span><span> frozenTokens</span><span>[</span><span>account</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>deltaAmount </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>)</span><span> actualValue </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span>deltaAmount</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-support"> uint256</span><span> sub </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span class="z-keyword">-</span><span>deltaAmount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>sub </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> actualValue</span><span>,</span><span class="z-entity z-name"> ERC7943ExpectedValueMismatch</span><span>(</span><span>sub</span><span>,</span><span> actualValue</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> actualValue </span><span class="z-keyword">-</span><span class="z-keyword">=</span><span> sub</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"> setFrozenTokens</span><span>(</span><span>account</span><span>,</span><span> actualValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><em>Note</em> These helpers reduce accidental overwrites and expand in functionalities but do not prevent same-block conflicting updates or mempool ordering races by different privileged actors.</p> <ol start="3"> <li>Developers can also perform several operations through the use of <code>multicall</code> patterns similar to the one defined in <a href="https://wg-eips.ritovision.com/6357/">ERC-6357</a> so that a mix of the given primitives with additional features can be batched in one transaction:</li> </ol> <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"> ERC7943Fungible</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7943Fungible</span><span>, </span><span class="z-entity z-name">Multicall</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Now any combination of `setFrozenTokens`/`forcedTransfer` </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> coupled with other functionalities like the ones to blacklist/whitelist users</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> can be submitted in one transaction through the use of `multicall` function</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ol start="4"> <li>Functionalities like pausability can be added on top, either through the use of modifiers or directly within functions implementations:</li> </ol> <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"> canTransfer</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-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> allowed</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-entity z-name">paused</span><span>(</span><span>)</span><span>)</span><span class="z-keyword"> return</span><span> allowed</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ... other checks</span></span> <span class="giallo-l"><span> }</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="notes-on-naming">Notes on naming</h3> <p>The naming conventions in this ERC were carefully chosen to establish clarity and semantic consistency within the broader RWA ecosystem while maintaining neutrality and broad applicability.</p> <ul> <li><strong><code>forcedTransfer</code></strong>: This term was selected for its neutrality. While names like <em>confiscation</em>, <em>revocation</em>, or <em>recovery</em> describe specific motivations, <code>forcedTransfer</code> purely denotes the direct action of transferring assets, irrespective of the underlying reason. <code>forcedTransfer</code> was preferred over <code>forceTransfer</code> to maintain backward compatibility with <a href="https://wg-eips.ritovision.com/3643/">ERC-3643</a>.</li> <li><strong><code>canTransfer</code></strong>: This name was preferred over <code>isTransferAllowed</code> for consistency with established RWA standards including <a href="https://wg-eips.ritovision.com/3643/">ERC-3643</a> and <a href="https://wg-eips.ritovision.com/7518/">ERC-7518</a>. This alignment promotes interoperability and reduces cognitive overhead when working across different RWA tokens.</li> <li><strong><code>setFrozenTokens</code> / <code>getFrozenTokens</code></strong>: These names were chosen for managing transfer restrictions and align with <a href="https://wg-eips.ritovision.com/3643/">ERC-3643</a> naming patterns. <em>Frozen</em> was also selected for its general applicability to both fungible (amount-based) and non-fungible (status-based) assets, as terms like <em>amount</em> or <em>asset(s)</em> might not be universally fitting.</li> <li><strong><code>ERC7943InsufficientUnfrozenBalance</code></strong>: Discussions around <em>insufficient</em> being similar to <em>unavailable</em> arose, where <em>unavailable</em> might have better suggested a temporal condition like a freezing status. However, the term <em>available</em>/<em>unavailable</em> was also overlapping with <em>frozen</em>/<em>unfrozen</em> creating more confusion and duality. Finally, coupling <em>insufficient</em> with the specified <em>unfrozen balance</em> better represents the domain, prefix and subject of the error, according to <a href="https://wg-eips.ritovision.com/6093/">ERC-6093</a> guidelines.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP defines a new interface standard and does not alter existing ones like <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>. Standard wallets and explorers can interact with the base token functionality of implementing contracts, subject to the rules enforced by that contract's implementation of <code>canTransact</code>, <code>canTransfer</code> and <code>getFrozenTokens</code> functions. Full support for the <a href="https://wg-eips.ritovision.com/7943/">ERC-7943</a> functions requires explicit integration.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Reference implementations of uRWA for <a href="https://wg-eips.ritovision.com/7943/./assets/contracts/uRWA20.sol">ERC-20</a>, <a href="https://wg-eips.ritovision.com/7943/./assets/contracts/uRWA721.sol">ERC-721</a> and <a href="https://wg-eips.ritovision.com/7943/./assets/contracts/uRWA1155.sol">ERC-1155</a> token implementations is provided in assets folder. They use the OpenZeppelin library and include an account whitelist and enumerable role-based access control. These examples are provided for educational purposes only and are not audited.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li><strong>Access Control for <code>forcedTransfer</code> and <code>setFrozenTokens</code>:</strong> The security of the mechanism chosen by the implementer to restrict access to these functions is paramount. Unauthorized access could lead to asset theft. Secure patterns (multisig, timelocks) are highly recommended.</li> <li><strong>Front-run of the <code>setFrozenTokens</code> function:</strong> The <code>setFrozenTokens</code> function might be susceptible to front-running, similar to the <code>approve</code> function of the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. If the suggestion of allowing freezing more than what an account owns is not followed, a front-run might be an incentive to an account to avoid any attempt of freezing its balance. Additional features to gradually increment or decrement the frozen status MAY be considered for implementation.</li> <li><strong>Implementation Logic:</strong> The correctness of the <em>implementation</em> behind all interface functions is critical. Flaws in this logic could bypass intended transfer restrictions or incorrectly block valid transfers.</li> <li><strong>Standard Contract Security:</strong> Implementations MUST adhere to general smart contract security best practices (reentrancy guards where applicable, checks-effects-interactions, etc.). Specifically in the checks-effects-interactions consideration, implementations need to be aware of tokens having hooks, especially on recipients like in <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>. In such circumstances it might be convenient to adopt reentrancy guards to prevent unwanted executions.</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> 2025-06-09T00: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/7954/

Raise the maximum contract code size from 24KiB to 32KiB and initcode size from 48KiB to 64KiB.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes to raise the maximum allowed size for contract code deployed on Ethereum from 24,576 bytes to 32,768 bytes.</p> <h2 id="motivation">Motivation</h2> <p>The current 24KiB contract size limit can be restrictive for complex contracts and applications. Increasing the limit to 32KiB allows for more feature-rich contracts while maintaining reasonable constraints on block and state growth.</p> <h2 id="specification">Specification</h2> <ol> <li>Update the <a href="https://wg-eips.ritovision.com/170/">EIP-170</a> contract code size limit of 24KiB (<code>0x6000</code> bytes) to 32KiB (<code>0x8000</code> bytes).</li> <li>Update the <a href="https://wg-eips.ritovision.com/3860/">EIP-3860</a> initcode size limit of 48KiB (<code>0xC000</code> bytes) to 64KiB (<code>0x10000</code> bytes).</li> </ol> <h2 id="rationale">Rationale</h2> <ul> <li><strong>Developer Flexibility:</strong> Enables more complex contracts and features.</li> <li><strong>Backward Compatibility:</strong> Existing contracts are unaffected.</li> <li><strong>Simplicity:</strong> Only the size limit is changed, with no other protocol modifications.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is not backwards compatible and must be activated via a network upgrade (hard fork). Contracts larger than 24KiB, up to 32KiB, will be deployable after activation.</p> <h2 id="security-considerations">Security Considerations</h2> <p>A higher contract size limit may marginally increase the risk of denial-of-service attacks via large contracts, but the new limit remains conservative.</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-06-06T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ernesto Garcíahttps://github.com/ernestognw https://wg-eips.ritovision.com/7965/

Cross-chain messaging using cryptographic proofs to verify messages between blockchains.

<h2 id="abstract">Abstract</h2> <p>This document defines standardized broadcasting semantics and attributes for <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> cross-chain messaging that enable trustless message verification through cryptographic proofs. Messages are committed on source chains in verifiable ways, then verified on destination chains using cryptographic proofs of the source chain's state or transaction history. This approach provides cross-chain communication without relying on external validators or bridge operators.</p> <h2 id="motivation">Motivation</h2> <p>Cross-chain messaging protocols typically rely on external validators, multisigs, or optimistic mechanisms that introduce trust assumptions and potential points of failure. Cryptographic proofs offer an alternative approach where messages can be verified using the consensus mechanisms and cryptographic commitments of the chains themselves (e.g. storage proofs for EVM chains).</p> <p>However, cryptographic proof verification requires chain-specific routing information, proof data, and verification parameters that are not addressed by the base <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> interface. Additionally, while <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> defines basic broadcasting through "omitted or zeroed" recipient addresses, it does not specify granular broadcasting patterns that enable targeting specific chains or chain types. Enhanced broadcasting semantics enable messages to be sent with varying levels of specificity, from all addresses on a specific chain to all supported infrastructure.</p> <p>This document standardizes these requirements as <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> attributes, enabling cryptographic proof-based messaging within the established cross-chain messaging framework. The specification supports multi-hop verification paths, allowing messages to traverse through multiple intermediary chains when direct verification is not possible.</p> <p>The key benefits of this approach include:</p> <ul> <li><strong>Trustless verification</strong>: No external validators or multisigs required. Chains trust their own consensus mechanisms.</li> <li><strong>Universal compatibility</strong>: Works between chains with verifiable state relationships through shared settlement infrastructure or compatible proof systems.</li> <li><strong>Flexible messaging patterns</strong>: Supports both targeted and granular broadcast messaging through standardized semantics, enabling new classes of applications like oracles and intent settlement systems.</li> <li><strong>Composability</strong>: Full integration with existing <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> infrastructure and tooling</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> <h3 id="broadcasting-semantics">Broadcasting Semantics</h3> <p><a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> defines broadcasting as using "omitted or zeroed" recipient addresses (containing an <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> interoperable address with all fields set to zero). This specification extends that concept to enable granular broadcasting patterns through <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a>'s flexible address structure:</p> <p>Broadcasting semantics in this specification extend <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> by allowing:</p> <ul> <li>Interoperable addresses with <code>AddressLength</code> set to 0 and specified <code>ChainType</code> and/or <code>ChainReference</code> to broadcast messages to all addresses on a given chain</li> <li>Interoperable addresses with <code>ChainReferenceLength</code> set to 0 and a specified <code>ChainType</code> to broadcast to all chains of a given type</li> <li>Interoperable addresses with all fields set to zero to indicate universal broadcasting to all supported chains and addresses</li> </ul> <p>Receivers of broadcast messages SHOULD validate the source and authenticity of messages according to their own security requirements.</p> <h3 id="cryptographic-proof-attributes">Cryptographic Proof Attributes</h3> <p>This specification defines the following <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> attributes for cryptographic proof messaging. Gateways MUST return true if <code>supportsAttribute</code> is called with the selector for supported attributes.</p> <h4 id="route-bytes-bytes-uint256"><code>route((bytes,bytes,uint256)[])</code></h4> <p>Specifies the verification path from destination to source chain with corresponding proofs and version requirements. Each tuple contains a bytes-encoded address that SHOULD be called for verification of the next chain's state or transaction history, the cryptographic proof required for that verification step, and the expected version of the verification logic (0 means any version is acceptable). The route address MAY invoke other gateways to resend the message to the next hop.</p> <p>When a non-zero version is specified, gateways MUST reject messages if the route address does not support the exact required version (unless <code>0</code>). Route addresses SHOULD implement version querying mechanisms to enable compatibility checking.</p> <p>The route MUST form a valid path where each step represents a direct relationship between chains that enables state or transaction verification. For multi-hop scenarios, the route creates a chain of trust where each step verifies the next, ultimately establishing the authenticity of the source chain's state. Gateways MUST reject messages with invalid or incomplete proof data.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodeWithSignature</span><span>(</span><span class="z-string">&quot;route((bytes,bytes,uint256)[])&quot;</span><span>,</span><span> hops</span><span>)</span><span>;</span></span></code></pre><h4 id="inclusionproof-bytes"><code>inclusionProof(bytes)</code></h4> <p>The cryptographic proof demonstrating that a specific message exists in the source chain's committed state at a finalized block or transaction. For EVM chains, this would typically be an event inclusion proof or storage proof.</p> <p><a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> receivers MUST validate the cryptographic proof according to the source chain's proof system.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodeWithSignature</span><span>(</span><span class="z-string">&quot;inclusionProof(bytes)&quot;</span><span>,</span><span> proofData</span><span>)</span><span>;</span></span></code></pre><h4 id="targetblock-uint256"><code>targetBlock(uint256)</code></h4> <p>Specifies the block number or height on the source chain where the message was committed. For chains that don't use sequential block numbers, this represents the equivalent commitment identifier.</p> <p><a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> receivers MAY validate the target block for freshness or finality requirements according to their security policies. Receivers MAY ignore this attribute if not needed for their use case.</p> <p>When provided, this attribute SHOULD correspond to the block or commitment whose state is proven by the cryptographic proof.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodeWithSignature</span><span>(</span><span class="z-string">&quot;targetBlock(uint256)&quot;</span><span>,</span><span> blockNumber</span><span>)</span><span>;</span></span></code></pre><h3 id="relationship-to-existing-proof-protocols">Relationship to Existing Proof Protocols</h3> <p>This ERC provides standard attributes that enable protocols like <a href="https://wg-eips.ritovision.com/7888/">ERC-7888</a> (for EVM storage proofs) and other proof systems to implement <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> gateways without rebuilding their core verification logic. For example, an <a href="https://wg-eips.ritovision.com/7888/">ERC-7888</a> Broadcaster MAY expose an <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> interface using these attributes while maintaining its existing storage proof architecture. Similarly, other proof systems can implement these same attributes using their native proof mechanisms.</p> <h3 id="caching">Caching</h3> <p>Gateways implementing this specification MAY implement caching mechanisms to optimize repeated proof verifications.</p> <h3 id="mutability-of-message-commitments">Mutability of Message Commitments</h3> <p>Gateways MAY choose to commit messages in ways that cannot be deleted or modified after being set, providing immutability guarantees. While not required by this standard, implementers can use <a href="https://wg-eips.ritovision.com/7201/">ERC-7201</a> to calculate namespaces for immutable storage locations on EVM chains, or equivalent immutability mechanisms on other chain architectures.</p> <h3 id="verification-process">Verification Process</h3> <p>In <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a>, the <code>payload</code> contains the actual message data to be delivered, while the <code>attributes</code> contain proof metadata that establishes the payload's authenticity. The destination gateway validates the attributes through cryptographic verification, and it MAY cache results for future use.</p> <p>For multihop scenarios, each route step verifies the next chain's state commitment, creating a chain of trust from destination to source. This enables message verification across multiple intermediate chains, similar to systems like <a href="https://wg-eips.ritovision.com/7888/">ERC-7888</a>'s BlockHashProver chains.</p> <p>Message verification follows these steps:</p> <ol> <li>Parse the <code>route</code> and <code>inclusionProof</code> attributes from the message, and optionally <code>targetBlock</code> if provided</li> <li>Validate all required attributes are present and well-formed</li> <li>For each route step, verify block hash transition or equivalent state commitment using the paired proof and validate version requirements if specified (non-zero)</li> <li>Use the <code>inclusionProof</code> to verify that message data exists in the source chain's committed state at the target block obtained from the route verification. The source chain SHOULD correspond to the final validated step in the route verification process</li> <li>Optionally validate the <code>targetBlock</code> for freshness or finality requirements if the attribute is provided and the receiver chooses to validate it</li> <li>Execute the message if all verifications pass</li> </ol> <h2 id="rationale">Rationale</h2> <p>This standard extends <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a>'s attribute system to add cryptographic proof capabilities without creating new interfaces. This approach maintains compatibility with existing infrastructure while enabling trustless cross-chain verification, allowing implementations to focus on proof verification logic rather than rebuilding messaging infrastructure.</p> <h3 id="broadcasting-and-cryptographic-proofs">Broadcasting and Cryptographic Proofs</h3> <p><a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> natively supports broadcasting through "omitted or zeroed" <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> interoperable addresses. This specification extends that foundation to enable granular broadcasting patterns through <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a>'s flexible address structure. Empty address components (<code>AddressLength</code> = 0) allow broadcasting to all addresses on a specific chain, while empty chain references (<code>ChainReferenceLength</code> = 0) enable broadcasting to all chains of a specific type (e.g., all EVM chains via <code>eip155</code> namespace). Universal broadcasting uses fully zeroed addresses as defined in <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a>.</p> <p>This multi-level broadcasting approach leverages <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a>'s inherent address structure and <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a>'s existing broadcast semantics rather than introducing new patterns, ensuring consistency with the cross-chain messaging ecosystem. The granularity enables efficient message distribution patterns: oracle feeds can target specific chains, governance messages can address entire chain families, and emergency notifications can reach all supported infrastructure.</p> <p>Cryptographic proofs provide trustless verification relying only on chain consensus mechanisms. This approach offers universal accessibility, cryptographic guarantees, cost efficiency (gas only on source/destination chains), and enables implicit batching through shared state commitments. Multi-hop routing extends this capability to chains without direct verification relationships.</p> <h3 id="attribute-design">Attribute Design</h3> <p>The two required attributes provide the essential functionality for cryptographic proof verification, while the optional <code>targetBlock</code> attribute enables additional freshness and finality validation when needed. Combining route information into a single tuple maintains type safety while separating proof verification from chain state transitions allows independent optimization. The optional nature of <code>targetBlock</code> provides implementation flexibility without adding unnecessary complexity to basic use cases.</p> <h3 id="caching-1">Caching</h3> <p>Caching can improve performance by storing verification results for reuse. Since proofs are deterministic, they can be safely cached. This is especially useful for broadcast messages that need multiple verifications. Implementations should cache both block hash transitions and proof verification results, while invalidating the cache when proof infrastructure changes.</p> <h3 id="mutability-of-message-commitments-1">Mutability of Message Commitments</h3> <p>Proving a commitment that could be deleted or modified may introduce additional security risks. For example, if a message is committed in a way that allows deletion after the message is sent, the proof will still be valid. This is why the specification does not require immutability, but allows gateways to choose to commit messages in immutable ways if they so desire.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC extends <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> through its attribute system and introduces no breaking changes to existing implementations. Gateways that do not support cryptographic proof attributes will simply reject messages containing them, which is the expected behavior for unsupported features.</p> <p>Existing <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> tooling and infrastructure can immediately leverage cryptographic proof messaging without modification, as the base interface remains unchanged.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="basic-gateway-usage">Basic Gateway Usage</h3> <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"> Hop</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> gateway</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> bytes-encoded address of the gateway</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> proof</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> version</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0 = any version</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"> Prepare route with proofs and version requirements</span></span> <span class="giallo-l"><span>Hop</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> hops </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span> Hop</span><span>[</span><span>]</span><span>(</span><span class="z-constant">2</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>hops</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Hop</span><span>(</span><span>gateway1</span><span>,</span><span> proof1</span><span>,</span><span class="z-constant"> 1</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Require version 1</span></span> <span class="giallo-l"><span>hops</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Hop</span><span>(</span><span>gateway2</span><span>,</span><span> proof2</span><span>,</span><span class="z-constant"> 0</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Any version acceptable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Example 1: Address Broadcasting - broadcast to all addresses on Arbitrum One (42161)</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> addressBroadcast </span><span class="z-keyword">=</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-support"> uint16</span><span>(</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Version</span></span> <span class="giallo-l"><span class="z-support"> uint16</span><span>(</span><span class="z-constant">0x0000</span><span>)</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> ChainType: eip155</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span>(</span><span class="z-constant">2</span><span>)</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> ChainReferenceLength: 2 bytes for chain ID</span></span> <span class="giallo-l"><span class="z-support"> uint16</span><span>(</span><span class="z-constant">42161</span><span>)</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> ChainReference: Arbitrum One (42161)</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> AddressLength: 0 (empty address = broadcast to all addresses)</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"> Example 2: Chain Type Broadcasting - broadcast to all EIP-155 chains</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> chainTypeBroadcast </span><span class="z-keyword">=</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-support"> uint16</span><span>(</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Version</span></span> <span class="giallo-l"><span class="z-support"> uint16</span><span>(</span><span class="z-constant">0x0000</span><span>)</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> ChainType: eip155</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> ChainReferenceLength: 0 (broadcast to all chains of this type)</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> AddressLength: 0 (empty address)</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"> Example 3: Universal Broadcasting - broadcast to all supported chains and addresses</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> universalBroadcast </span><span class="z-keyword">=</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-support"> uint16</span><span>(</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Version</span></span> <span class="giallo-l"><span class="z-support"> uint16</span><span>(</span><span class="z-constant">0x0000</span><span>)</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> ChainType: 0 (all chain types)</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> ChainReferenceLength: 0 (all chains)</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> AddressLength: 0 (all addresses)</span></span> <span class="giallo-l"><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support">bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> attributes </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> bytes</span><span>[](</span><span class="z-constant">3</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>attributes</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSignature</span><span>(</span><span class="z-string">&quot;route((bytes,bytes,uint256)[])&quot;</span><span>,</span><span> hops</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>attributes</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSignature</span><span>(</span><span class="z-string">&quot;inclusionProof(bytes)&quot;</span><span>,</span><span> proofData</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>attributes</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSignature</span><span>(</span><span class="z-string">&quot;targetBlock(uint256)&quot;</span><span>,</span><span> blockNumber</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Optional</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Send message with address broadcasting</span></span> <span class="giallo-l"><span>gateway</span><span>.</span><span class="z-entity z-name">sendMessage</span><span>(</span></span> <span class="giallo-l"><span> addressBroadcast</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> broadcast to all addresses on Arbitrum One</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 class="z-string">&quot;priceUpdate&quot;</span><span>,</span><span> asset</span><span>,</span><span> price</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> attributes</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"> Send message with chain type broadcasting </span></span> <span class="giallo-l"><span>gateway</span><span>.</span><span class="z-entity z-name">sendMessage</span><span>(</span></span> <span class="giallo-l"><span> chainTypeBroadcast</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> broadcast to all EIP-155 chains</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 class="z-string">&quot;governanceProposal&quot;</span><span>,</span><span> proposalId</span><span>,</span><span> votingPeriod</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> attributes</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"> Send message with universal broadcasting</span></span> <span class="giallo-l"><span>gateway</span><span>.</span><span class="z-entity z-name">sendMessage</span><span>(</span></span> <span class="giallo-l"><span> universalBroadcast</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> broadcast to all supported chains and addresses</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 class="z-string">&quot;pause&quot;</span><span>,</span><span> reason</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> attributes</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <h3 id="validation-requirements">Validation Requirements</h3> <p>Gateways must rigorously validate all proof data to prevent message forgery, including proof format, completeness, and cryptographic validity. Route addresses must correspond to legitimate proof infrastructure forming a valid, connected path between chains. Only finalized blocks or equivalent commitment points should be used for proof generation to prevent reorganization attacks.</p> <p>Consumers of cryptographic proof messages should implement appropriate freshness checks, as proofs can verify messages at any historical block or commitment, potentially including very old messages. This is not required for gateways offering immutable message commitments.</p> <h3 id="route-security">Route Security</h3> <p>The security of a multi-hop route is only as strong as the weakest proof in the verification path. When multiple route steps are used, the overall security level is determined by the step with the lowest cryptographic guarantees or the least secure consensus mechanism. Implementers should carefully evaluate each hop in their routes and consider the cumulative security implications when designing cross-chain verification paths.</p> <h3 id="broadcast-message-security">Broadcast Message Security</h3> <p>Since broadcast messages can be executed by any party, receivers should implement robust validation of message sources and contents. This includes verifying the sender's authority and the message's semantic validity.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-06-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ernesto Garcíahttps://github.com/ernestognw https://wg-eips.ritovision.com/7964/

Support EIP-712 signatures for crosschain account operations.

<h2 id="abstract">Abstract</h2> <p>This ERC defines a standard approach for creating and verifying crosschain signatures using <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>. By omitting the <code>chainId</code> field from the EIP-712 domain, a signature can be valid across multiple chains. Chain-specific operations are encoded as an array of structured messages, where each chain receives the array of message hashes and only the full message data relevant to that chain. This enables efficient crosschain signature validation using standard EIP-712 encoding without requiring special wallet support.</p> <h2 id="motivation">Motivation</h2> <p>Current account abstraction solutions require separate signatures for each blockchain network. This creates poor user experience for crosschain operations such as:</p> <ul> <li><strong>Crosschain intents</strong>: Users wanting to trade assets across multiple chains atomically</li> <li><strong>Multi-chain DAO governance</strong>: Voting on proposals that affect protocol instances across different networks</li> <li><strong>Unified account management</strong>: Managing the same account deployed on multiple chains</li> <li><strong>Crosschain social recovery</strong>: Recovery processes that span multiple networks</li> </ul> <p>Existing proposals either require complex Merkle tree constructions (which need wallet-specific UI to verify all leaves) or non-standard encoding schemes that lack wallet adoption. This ERC provides a simpler approach using only standard EIP-712 encoding with array types, enabling crosschain signatures with minimal on-chain overhead while maintaining full transparency in standard wallet signing interfaces.</p> <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="crosschain-domain-semantics">Crosschain Domain Semantics</h3> <p>A crosschain <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> signature MUST omit the <code>chainId</code> field from the <code>EIP712Domain</code> type and domain object. Since <code>chainId</code> is optional per <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>, omitting it signals that the signature is intended for crosschain validity.</p> <p>Contract addresses and chainIds MUST be validated per-chain, so typically, only <code>name</code> and <code>version</code> are included in the main domain. The <code>verifyingContract</code> field MAY be used to bind the signature to a specific application deployed deterministically on the same address across all chains the signature is intended to be valid on, allowing to omit the contract address from the chain-specific structs.</p> <h3 id="message-array-encoding">Message Array Encoding</h3> <p>Crosschain operations MUST be encoded as an array of message structs with chain-specific fields. Each struct in the array SHOULD include the target <code>chainId</code> field. When contracts are deployed at different addresses across chains, the struct SHOULD also include the <code>verifyingContract</code> (or equivalent) field to bind each operation to its specific contract address unless the main domain includes the <code>verifyingContract</code> field.</p> <p>Implementers MAY use the canonical <code>EIP712Domain</code> struct but named to avoid collisions with <code>EIP712Domain</code> (e.g., <code>EIP712ChainDomain</code>) so it can be nested inside the chain-specific structs, allowing to include the <code>chainId</code> and <code>verifyingContract</code> fields.</p> <p>Per <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>, arrays are encoded as <code>keccak256(encodeData(element[0]) ‖ encodeData(element[1]) ‖ ... ‖ encodeData(element[n]))</code>, where each element is a struct that is recursively encoded as <code>hashStruct(element[i])</code>, and nested structs are also recursively hashed.</p> <p>In practice, this means the array of chain-specific operations is represented as an array of pre-computed <code>bytes32</code> struct hashes (one for each chain). The hash of this array is computed as <code>keccak256(abi.encodePacked(structsArray))</code>, which concatenates all 32-byte hashes and produces the array hash that matches the standard <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> array encoding for reference types.</p> <h4 id="struct-hash">Struct Hash</h4> <p>Per <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>, the signature is computed over a complete message struct (e.g., <code>CrossChainIntent</code>, <code>MultiChainVote</code>), not just the array of operations. Applications implementing verification MUST define a type hash for the complete message struct that includes the array of operations.</p> <p>Wrapping the array of operations in a main struct also allows to include other message fields (e.g., <code>nonce</code>, <code>deadline</code>) in the struct hash. For example, for a <code>CrossChainIntent</code> struct would be encoded as:</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"> constant</span><span> CROSSCHAIN_INTENT_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;CrossChainIntent(ChainOperation[] operations,uint256 nonce,uint256 deadline)ChainOperation(EIP712ChainDomain domain,address target,uint256 value,bytes data)EIP712ChainDomain(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> fullStructHash </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> CROSSCHAIN_INTENT_TYPEHASH</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>chainOperationsArray</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> nonce</span><span>,</span></span> <span class="giallo-l"><span> deadline</span></span> <span class="giallo-l"><span> )</span><span>)</span><span>;</span></span></code></pre> <p>Applications implementing verification MUST use the same typehash across all chains where the application is deployed.</p> <h3 id="on-chain-verification">On-Chain Verification</h3> <p>To enable applications to detect and verify crosschain signatures through standard ECDSA validation or <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> <code>isValidSignature</code> calls, crosschain signatures SHOULD be encoded with metadata in the signature parameter. The signature validation flow requires the contract application to detect the encoding of this ERC, parse the signature components, and then verify the signature agains the reconstructed crosschain message hash.</p> <p>The signature encoding format uses ABI encoding for dynamic types (arrays and bytes) with the following structure:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[0x00:0x09] magic (9 bytes)</span></span> <span class="giallo-l"><span>[0x09:0x0a] fields (1 byte)</span></span> <span class="giallo-l"><span>[0x0a:0x0c] structIndex (2 bytes, big-endian uint16)</span></span> <span class="giallo-l"><span>[0x0c:0x20] application (20 bytes)</span></span> <span class="giallo-l"><span>[0x20:0x40] structsArrayOffset (32 bytes, big-endian uint256, offset to structsArray location)</span></span> <span class="giallo-l"><span>[structsArrayOffset:structsArrayOffset + 32] structsArrayLength (32 bytes, big-endian uint256)</span></span> <span class="giallo-l"><span>[structsArrayOffset + 32:structsArrayOffset + 32 + structsArrayLength * 32] structsArray (structsArrayLength * 32 bytes)</span></span> <span class="giallo-l"><span>[crossChainSignatureOffset:crossChainSignatureOffset + 32] crossChainSignatureLength (32 bytes, big-endian uint256)</span></span> <span class="giallo-l"><span>[crossChainSignatureOffset + 32:crossChainSignatureOffset + 32 + crossChainSignatureLength] crossChainSignature (crossChainSignatureLength bytes)</span></span></code></pre> <p>Equivalent to the following ABI encoding:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes32</span><span> header </span><span class="z-keyword">=</span><span class="z-support"> bytes32</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>CrossChainSignatureChecker</span><span>.</span><span>ERC7964_MAGIC</span><span>,</span><span> fields</span><span>,</span><span> structIndex</span><span>,</span><span class="z-support"> address</span><span>(</span><span>application</span><span>)</span><span>)</span><span>)</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>header</span><span>,</span><span> structsArray</span><span>,</span><span> crossChainSignature</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> (bytes32, bytes, bytes32[])</span></span></code></pre> <p>Where:</p> <ul> <li><strong><code>magic</code></strong>: A fixed 9-byte value <code>0x796479647964796479</code> used to detect encoded crosschain signatures</li> <li><strong><code>fields</code></strong>: A single byte encoding which <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> domain fields are present (per <a href="https://wg-eips.ritovision.com/5267/">ERC-5267</a>)</li> <li><strong><code>structIndex</code></strong>: The index in the <code>structsArray</code> corresponding to the current chain's operation</li> <li><strong><code>application</code></strong>: The address of a contract implementing <a href="https://wg-eips.ritovision.com/5267/">ERC-5267</a> that provides the <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> domain information</li> <li><strong><code>structsArrayOffset</code></strong>: The offset (in bytes) from the start of the signature to where the <code>structsArray</code> begins.</li> <li><strong><code>structsArrayLength</code></strong>: The number of elements in the structs array</li> <li><strong><code>structsArray</code></strong>: Array of <code>bytes32</code> hashes, one per chain operation</li> <li><strong><code>crossChainSignatureOffset</code></strong>: The offset (in bytes) from the start of the signature to where the <code>crossChainSignature</code> begins.</li> <li><strong><code>crossChainSignatureLength</code></strong>: The length of the crosschain signature in bytes</li> <li><strong><code>crossChainSignature</code></strong>: The actual signature bytes that sign the crosschain message</li> </ul> <p>This encoding allows applications to identify when a signature is a crosschain signature, rebuild the EIP-712 domain information needed to reconstruct the expected typed hash, and verify the signature against the reconstructed crosschain message hash.</p> <p>Applications can detect crosschain signatures by checking if the first 9 bytes of the signature equal the magic value <code>0x796479647964796479</code>. If detected, applications MUST:</p> <ol> <li>Parse the encoded metadata from the signature</li> <li>Verify that <code>structsArray[structIndex]</code> matches the struct hash of the current chain's message</li> <li>Query the <a href="https://wg-eips.ritovision.com/5267/">ERC-5267</a> contract at <code>application</code> to obtain the EIP-712 domain</li> <li>Reconstruct the full <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> hash using the domain, the main struct hash and the array of chain-specific struct hashes</li> <li>Verify the <code>crossChainSignature</code> against the reconstructed typed hash</li> </ol> <h3 id="wallet-display">Wallet Display</h3> <p>Standard <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> wallets will automatically display the array of chain-specific messages in a readable format. Wallets MAY enhance the display by grouping operations by chain and showing chain names instead of chain IDs for better user experience.</p> <h2 id="rationale">Rationale</h2> <h3 id="standard-eip-712-compatibility">Standard EIP-712 Compatibility</h3> <p>This ERC uses only standard <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> encoding without any extensions or special constructs. All fields in the <code>EIP712Domain</code> are optional per the standard, so omitting <code>chainId</code> is perfectly valid. This means any wallet that supports EIP-712 can sign these messages and any application that supports EIP-712 can verify them.</p> <p>The main benefit of this approach is that users can achieve a full transparent view of the crosschain message in any wallet provider that supports <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>.</p> <h3 id="main-struct-hash">Main Struct Hash</h3> <p>For wallet providers to show the crosschain message properly, they need a <code>primaryType</code> to display the message. This specification does not mandate a specific <code>primaryType</code> to allow for flexibility in the implementation, but defines the requirements for the array of operations and the main struct to ensure a secure EIP-712 message.</p> <p>The specification requires that each of the operations include the <code>chainId</code> field to avoid replaying the same operation on other chains. The <code>verifyingContract</code> field (or equivalent) is used to bind the operation to its specific contract address and is optional if the main <code>EIP712Domain</code> includes the <code>verifyingContract</code> field since the domain hash would include the application's address.</p> <h3 id="array-encoding-vs-merkle-trees">Array Encoding vs Merkle Trees</h3> <p>Alternative approaches use Merkle trees to commit to crosschain operations. While Merkle trees can reduce on-chain overhead for many chains, they have a critical drawback:</p> <p><strong>Wallet Verification Complexity</strong>: Standard EIP-712 wallets cannot display Merkle tree leaves. Users signing a Merkle root have no way to verify all operations in their wallet UI. Wallets would need to implement custom logic to:</p> <ol> <li>Request all leaves from the application</li> <li>Verify the Merkle tree construction</li> <li>Display all operations across all chains</li> <li>Ensure no malicious operations are hidden</li> </ol> <p>This breaks the principle of trustless signing, users must trust the application to correctly provide all leaves, and wallet developers must implement and maintain custom verification logic.</p> <p>The array-based approach provides <strong>full transparency</strong> using standard EIP-712. Users see all chain-specific operations in any compliant wallet without custom support. No hidden operations are possible since all array elements are displayed as part of the standard EIP-712 message structure.</p> <p><strong>On-chain overhead comparison</strong>: For reasonable crosschain operations, the overhead difference is minimal.</p> <p>With the array approach, each chain receives all N operation hashes (<code>N × 32 bytes</code>). With Merkle trees (assuming a binary tree), each chain receives a Merkle proof of size <code>ceil(log₂(N)) × 32 bytes</code>. Both approaches reconstruct the root/array hash on-chain from the provided data and verify it against the signature, no additional calldata for the root is needed. While Merkle proofs grow logarithmically vs. the array's linear growth, the practical savings are small for reasonable use cases:</p> <table><thead><tr><th>Chains</th><th>Array (N × 32)</th><th>Merkle (⌈log₂(N)⌉ × 32)</th><th>Savings</th></tr></thead><tbody> <tr><td>2</td><td>64 bytes (2 × 32)</td><td>32 bytes (1 × 32)</td><td>32 bytes (1 hash)</td></tr> <tr><td>3</td><td>96 bytes (3 × 32)</td><td>64 bytes (2 × 32)</td><td>32 bytes (1 hash)</td></tr> <tr><td>4</td><td>128 bytes (4 × 32)</td><td>64 bytes (2 × 32)</td><td>64 bytes (2 hashes)</td></tr> <tr><td>5</td><td>160 bytes (5 × 32)</td><td>96 bytes (3 × 32)</td><td>64 bytes (2 hashes)</td></tr> <tr><td>8</td><td>256 bytes (8 × 32)</td><td>96 bytes (3 × 32)</td><td>160 bytes (5 hashes)</td></tr> </tbody></table> <p>For 2-5 chains (the reasonable case for crosschain operations), Merkle trees save only 32-64 bytes (1-2 hashes) per transaction. This minimal savings doesn't justify the complexity and loss of transparency. Merkle trees only become significantly more efficient at 8+ chains, which is an uncommon use case and may indicate the operation should be split into multiple signatures for better user comprehension and failure isolation.</p> <h3 id="omitting-chainid-vs-using-0">Omitting chainId vs using <code>0</code></h3> <p>Omitting <code>chainId</code> entirely is cleaner than using a special value like <code>0</code> because it explicitly signals that the signature is intended for crosschain validity.</p> <h3 id="signature-encoding-format">Signature Encoding Format</h3> <p>The custom binary encoding format for crosschain signatures was selected to minimize calldata and memory overhead. The format packs metadata values that can be read to the stack and uses ABI encoding for <code>structsArray</code> and <code>crossChainSignature</code> for easy calldata and memory casting.</p> <p>The magic value is used to detect crosschain signatures and is designed to be easy to parse and verify. It's a fixed 9-byte value that is easy to identify and verify. The length was selected to pack it along with <code>bytes1(fields)</code>, <code>uint16(structIndex)</code> and <code>address(application)</code> into a single 32-byte word. While 9 bytes is shorter than a full 32-byte hash, the collision probability remains negligible in practice—an attacker would need to produce a valid ECDSA or <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> signature that randomly begins with these exact 9 bytes, which has probability 2^-72 (approximately 1 in 4.7 × 10^21) assuming a uniform distribution.</p> <p>The <code>fields</code> byte encodes which EIP-712 domain fields are present in the main domain (per <a href="https://wg-eips.ritovision.com/5267/">ERC-5267</a>), enabling dynamic field selection. Only <code>name</code> and <code>version</code> are normally set in the main domain, since <code>chainId</code> is omitted for crosschain validity since each chain-specific struct includes its own <code>chainId</code> and optionally <code>verifyingContract</code> (or equivalent), allowing each chain to validate its own contract address as part of the struct hash verification.</p> <p>The <code>application</code> address refers to any contract that implements <a href="https://wg-eips.ritovision.com/5267/">ERC-5267</a>'s <code>eip712Domain()</code> function. This contract provides the domain separator information needed to reconstruct the crosschain message hash. The application contract does not need to be the contract that executes the operation: it serves solely as a source of EIP-712 domain metadata. Applications could either deploy dedicated immutable domain separator contracts to ensure consistent domain information across all chains, or use the executing contract itself if it implements <a href="https://wg-eips.ritovision.com/5267/">ERC-5267</a>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC uses standard <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> without modifications. Existing wallets and applications that support EIP-712 can immediately work with crosschain signatures without any changes, though they may not recognize the crosschain semantics.</p> <p>Applications that verify signatures with a domain that includes a specific <code>chainId</code> will reject crosschain signatures (where <code>chainId</code> is omitted), providing safe failure by default. Applications that wish to support crosschain signatures must explicitly implement the verification pattern described in this ERC.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>To validate a crosschain signature, the application can use the following library:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">SignatureChecker</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/cryptography/SignatureChecker.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">MessageHashUtils</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/cryptography/MessageHashUtils.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IERC5267</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/interfaces/IERC5267.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Calldata</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/Calldata.sol&quot;</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"> CrossChainSignatureChecker</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes9</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> constant</span><span> ERC7964_MAGIC </span><span class="z-keyword">=</span><span class="z-constant"> 0x796479647964796479</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"> isValidCrossChainSignatureNow</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> signer</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> hash</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"> erc7964Signature</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> function</span><span>(</span><span class="z-support">bytes32</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 class="z-entity z-name"> structHash</span></span> <span class="giallo-l"><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> (</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> success</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes1</span><span> fields</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint16</span><span> structIndex</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> application</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span> structsArray</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span> crossChainSignature</span></span> <span class="giallo-l"><span> )</span><span class="z-keyword"> =</span><span class="z-entity z-name"> parseCrossChainSignature</span><span>(</span><span>erc7964Signature</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>success </span><span class="z-keyword">||</span><span> structsArray</span><span>[</span><span>structIndex</span><span>]</span><span class="z-keyword"> !=</span><span> hash</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> false</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"> memory</span><span> name</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</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 class="z-support"> bytes32</span><span> domainSalt</span><span>;</span></span> <span class="giallo-l"><span> (</span><span>,</span><span> name</span><span>,</span><span> version</span><span>,</span><span> chainId</span><span>,</span><span> verifyingContract</span><span>,</span><span> domainSalt</span><span>,</span><span> )</span><span class="z-keyword"> =</span><span class="z-entity z-name"> IERC5267</span><span>(</span><span>application</span><span>)</span><span>.</span><span class="z-entity z-name">eip712Domain</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> typedHash </span><span class="z-keyword">=</span><span> MessageHashUtils</span><span>.</span><span class="z-entity z-name">toTypedDataHash</span><span>(</span></span> <span class="giallo-l"><span> MessageHashUtils</span><span>.</span><span class="z-entity z-name">toDomainSeparator</span><span>(</span><span>fields</span><span>,</span><span> name</span><span>,</span><span> version</span><span>,</span><span> chainId</span><span>,</span><span> verifyingContract</span><span>,</span><span> domainSalt</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> structHash</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>structsArray</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> SignatureChecker</span><span>.</span><span class="z-entity z-name">isValidSignatureNowCalldata</span><span>(</span><span>signer</span><span>,</span><span> typedHash</span><span>,</span><span> crossChainSignature</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"> parseCrossChainSignature</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"> erc7964Signature</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-storage z-type"> internal</span></span> <span class="giallo-l"><span class="z-storage z-type"> pure</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></span> <span class="giallo-l"><span class="z-support"> bytes1</span><span class="z-variable"> fields</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint16</span><span class="z-variable"> structIndex</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> application</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> structsArray</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"> crossChainSignature</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"> magic (9 bytes) + fields (1 byte) + structIndex (2 bytes) + application (20 bytes) + structsArrayOffset (32 bytes) +</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> structsArrayLength (32 bytes) + crossChainSignatureOffset (32 bytes) + crossChainSignatureLength (32 bytes)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>erc7964Signature</span><span>.</span><span>length </span><span class="z-keyword">&lt;</span><span class="z-constant"> 0x9f</span><span class="z-keyword"> ||</span><span class="z-support"> bytes9</span><span>(</span><span>erc7964Signature</span><span>[</span><span class="z-constant">0</span><span class="z-keyword">:</span><span class="z-constant">9</span><span>]</span><span>)</span><span class="z-keyword"> !=</span><span> ERC7964_MAGIC</span><span>)</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 class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-entity z-name"> _empty32BytesArrayCalldata</span><span>(</span><span>)</span><span>,</span><span> Calldata</span><span>.</span><span class="z-entity z-name">emptyBytes</span><span>(</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> fields </span><span class="z-keyword">=</span><span> erc7964Signature</span><span>[</span><span class="z-constant">9</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> structIndex </span><span class="z-keyword">=</span><span class="z-support"> uint16</span><span>(</span><span class="z-support">bytes2</span><span>(</span><span>erc7964Signature</span><span>[</span><span class="z-constant">10</span><span class="z-keyword">:</span><span>]</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> application </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span class="z-support">bytes20</span><span>(</span><span>erc7964Signature</span><span>[</span><span class="z-constant">12</span><span class="z-keyword">:</span><span>]</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> structsArrayOffset </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span class="z-support">bytes32</span><span>(</span><span>erc7964Signature</span><span>[</span><span class="z-constant">0x20</span><span class="z-keyword">:</span><span>]</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> structsArrayDataOffset </span><span class="z-keyword">=</span><span> structsArrayOffset </span><span class="z-keyword">+</span><span class="z-constant"> 32</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>structsArrayOffset </span><span class="z-keyword">&lt;</span><span class="z-constant"> 0x60</span><span class="z-keyword"> ||</span><span> structsArrayDataOffset </span><span class="z-keyword">&gt;</span><span> erc7964Signature</span><span>.</span><span>length</span><span>)</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 class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-entity z-name"> _empty32BytesArrayCalldata</span><span>(</span><span>)</span><span>,</span><span> Calldata</span><span>.</span><span class="z-entity z-name">emptyBytes</span><span>(</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> structsArrayLength </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span class="z-support">bytes32</span><span>(</span><span>erc7964Signature</span><span>[</span><span>structsArrayOffset</span><span class="z-keyword">:</span><span>]</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>structsArrayDataOffset </span><span class="z-keyword">+</span><span> structsArrayLength </span><span class="z-keyword">*</span><span class="z-constant"> 32</span><span class="z-keyword"> &gt;</span><span> erc7964Signature</span><span>.</span><span>length</span><span>)</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 class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-entity z-name"> _empty32BytesArrayCalldata</span><span>(</span><span>)</span><span>,</span><span> Calldata</span><span>.</span><span class="z-entity z-name">emptyBytes</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-support"> uint256</span><span> crossChainSignatureOffset </span><span class="z-keyword">=</span><span> structsArrayDataOffset </span><span class="z-keyword">+</span><span> structsArrayLength </span><span class="z-keyword">*</span><span class="z-constant"> 32</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> crossChainSignatureDataOffset </span><span class="z-keyword">=</span><span> crossChainSignatureOffset </span><span class="z-keyword">+</span><span class="z-constant"> 32</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>crossChainSignatureOffset </span><span class="z-keyword">&lt;</span><span class="z-constant"> 0x60</span><span class="z-keyword"> ||</span><span> crossChainSignatureDataOffset </span><span class="z-keyword">&gt;</span><span> erc7964Signature</span><span>.</span><span>length</span><span>)</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 class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-entity z-name"> _empty32BytesArrayCalldata</span><span>(</span><span>)</span><span>,</span><span> Calldata</span><span>.</span><span class="z-entity z-name">emptyBytes</span><span>(</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> crossChainSignatureLength </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span class="z-support">bytes32</span><span>(</span><span>erc7964Signature</span><span>[</span><span>crossChainSignatureOffset</span><span class="z-keyword">:</span><span>]</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>crossChainSignatureDataOffset </span><span class="z-keyword">+</span><span> crossChainSignatureLength </span><span class="z-keyword">&gt;</span><span> erc7964Signature</span><span>.</span><span>length</span><span>)</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 class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-entity z-name"> _empty32BytesArrayCalldata</span><span>(</span><span>)</span><span>,</span><span> Calldata</span><span>.</span><span class="z-entity z-name">emptyBytes</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-entity z-name"> assembly</span><span> (</span><span class="z-string">&quot;memory-safe&quot;</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> structsArray</span><span>.</span><span>offset </span><span class="z-keyword">:=</span><span class="z-entity z-name"> add</span><span>(</span><span>erc7964Signature</span><span>.</span><span>offset</span><span>,</span><span> structsArrayDataOffset</span><span>)</span></span> <span class="giallo-l"><span> structsArray</span><span>.</span><span>length </span><span class="z-keyword">:=</span><span> structsArrayLength</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> crossChainSignature </span><span class="z-keyword">=</span><span> erc7964Signature</span><span>[</span></span> <span class="giallo-l"><span> crossChainSignatureDataOffset</span><span class="z-keyword">:</span><span>crossChainSignatureDataOffset </span><span class="z-keyword">+</span><span> crossChainSignatureLength</span></span> <span class="giallo-l"><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> fields</span><span>,</span><span> structIndex</span><span>,</span><span> application</span><span>,</span><span> structsArray</span><span>,</span><span> crossChainSignature</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"> _empty32BytesArrayCalldata</span><span>(</span><span>)</span><span class="z-storage z-type"> private</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 class="z-storage z-type"> calldata</span><span class="z-variable"> result</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> assembly</span><span> (</span><span class="z-string">&quot;memory-safe&quot;</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> result</span><span>.</span><span>offset </span><span class="z-keyword">:=</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> result</span><span>.</span><span>length </span><span class="z-keyword">:=</span><span class="z-constant"> 0</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>A collection of examples of how to use this ERC to fulfill the <em>Motivation</em> use cases.</p> <h3 id="crosschain-intent-example">Crosschain Intent Example</h3> <p>A user wants to execute a crosschain trade: sell USDC on Ethereum, receive ETH on Arbitrum:</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"> types</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> EIP712Domain</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">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 class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Note: chainId is omitted for crosschain validity</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> CrossChainIntent</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">operations</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">ChainOperation[]</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">nonce</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">deadline</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 class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> ChainOperation</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">domain</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">EIP712ChainDomain</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">target</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">value</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">data</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">bytes</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-entity z-name"> EIP712ChainDomain</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 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"> primaryType</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">CrossChainIntent</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">CrossChainDEX</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> 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 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"> operations</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> chainId</span><span>:</span><span class="z-constant"> 1</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">0x123321...</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> User&#39;s account on Ethereum</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> target</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xA0b86a33E6776885F5Db...</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"> USDC contract</span></span> <span class="giallo-l"><span> value</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xa9059cbb...</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> transfer(settler, 1000 USDC)</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> chainId</span><span>:</span><span class="z-constant"> 42161</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">0x123321...</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> User&#39;s account on Arbitrum</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> target</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xArbitrumSettler...</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> value</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x3ccfd60b...</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> claim(0.5 ETH min)</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"> nonce</span><span>:</span><span class="z-constant"> 42</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> deadline</span><span>:</span><span class="z-constant"> 1704067200</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>On-chain verification on Ethereum:</strong></p> <p>Applications can verify crosschain signatures using the encoded format. The signature contains all necessary metadata to reconstruct and verify the crosschain message:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">EIP712</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/cryptography/EIP712.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Nonces</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/Nonces.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">CrossChainSignatureChecker</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./CrossChainSignatureChecker.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"> CrossChainDEX</span><span class="z-storage"> is</span><span class="z-entity z-name"> EIP712</span><span>, </span><span class="z-entity z-name">Nonces</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> CrossChainSignatureChecker</span><span class="z-keyword"> for</span><span class="z-entity z-name"> address</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 class="z-storage z-type"> constant</span><span> EIP712_CHAIN_DOMAIN_TYPEHASH </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;EIP712ChainDomain(uint256 chainId,address verifyingContract)&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> CHAIN_OPERATION_TYPEHASH </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;ChainOperation(EIP712ChainDomain domain,address target,uint256 value,bytes data)EIP712ChainDomain(uint256 chainId,address verifyingContract)&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> CROSSCHAIN_INTENT_TYPEHASH </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;CrossChainIntent(ChainOperation[] operations,uint256 nonce,uint256 deadline)ChainOperation(EIP712ChainDomain domain,address target,uint256 value,bytes data)EIP712ChainDomain(uint256 chainId,address verifyingContract)&quot;</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> operationHash </span><span class="z-keyword">=&gt;</span><span class="z-support"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> _deadlines</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-entity z-name"> EIP712</span><span>(</span><span>&quot;CrossChainDEX&quot;, &quot;1&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"> executeIntent</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-storage z-type"> ChainOperation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> currentOp</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</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"> signature</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-support"> bytes32</span><span> currentOpHash </span><span class="z-keyword">=</span><span class="z-entity z-name"> _structHash</span><span>(</span><span>currentOp</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> _useCheckedNonce</span><span>(</span><span>account</span><span>,</span><span> nonce</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _deadlines</span><span>[</span><span>currentOpHash</span><span>]</span><span class="z-keyword"> =</span><span> deadline</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> account</span><span>.</span><span class="z-entity z-name">isValidCrossChainSignatureNowCalldata</span><span>(</span></span> <span class="giallo-l"><span> currentOpHash</span><span>,</span></span> <span class="giallo-l"><span> signature</span><span>,</span></span> <span class="giallo-l"><span> _crossChainStructHash</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Invalid signature&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></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> currentOp</span><span>.</span><span>target</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span> currentOp</span><span>.</span><span>value</span><span>}</span><span>(</span><span>currentOp</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"> &quot;Execution failed&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"> _crossChainStructHash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> operationsHash</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">encode</span><span>(</span><span>CROSSCHAIN_INTENT_TYPEHASH</span><span>,</span><span> operationsHash</span><span>,</span><span class="z-entity z-name"> nonces</span><span>(</span><span>account</span><span>)</span><span>,</span><span> _deadlines</span><span>[</span><span>operationsHash</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"> _structHash</span><span>(</span><span class="z-storage z-type">ChainOperation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> op</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> <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> CHAIN_OPERATION_TYPEHASH</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>EIP712_CHAIN_DOMAIN_TYPEHASH</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>chainid</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></span> <span class="giallo-l"><span> op</span><span>.</span><span>target</span><span>,</span></span> <span class="giallo-l"><span> op</span><span>.</span><span>value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span>op</span><span>.</span><span>data</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></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The Arbitrum settler would use the same signature with <code>currentIndex: 1</code> and the full data for <code>op[1]</code>. Each chain only receives the full calldata for its own operation, while other operations are represented as 32-byte hashes.</p> <h3 id="multi-chain-governance-example">Multi-Chain Governance Example</h3> <p>A DAO member votes on a proposal affecting all chain deployments:</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"> types</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> EIP712Domain</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">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 class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> MultiChainVote</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">votes</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">ChainVote[]</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">nonce</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 class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> ChainVote</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">domain</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">EIP712ChainDomain</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">proposalId</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">support</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">uint8</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">reason</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 class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> EIP712ChainDomain</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 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"> primaryType</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">MultiChainVote</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">MultiChainDAO</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> 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 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"> votes</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> chainId</span><span>:</span><span class="z-constant"> 1</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">0x123321...</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> DAO contract on Ethereum</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> proposalId</span><span>:</span><span class="z-constant"> 42</span><span>,</span></span> <span class="giallo-l"><span> support</span><span>:</span><span class="z-constant"> 1</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> For</span></span> <span class="giallo-l"><span> reason</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">This upgrade improves security</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> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> chainId</span><span>:</span><span class="z-constant"> 137</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">0x321321...</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> DAO contract on Polygon</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> proposalId</span><span>:</span><span class="z-constant"> 42</span><span>,</span></span> <span class="giallo-l"><span> support</span><span>:</span><span class="z-constant"> 1</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> For</span></span> <span class="giallo-l"><span> reason</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">This upgrade improves security</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-entity z-name"> nonce</span><span>:</span><span class="z-constant"> 7</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>On-chain verification on each DAO:</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">EIP712</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/cryptography/EIP712.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Nonces</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/Nonces.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">CrossChainSignatureChecker</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./CrossChainSignatureChecker.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"> MultiChainDAO</span><span class="z-storage"> is</span><span class="z-entity z-name"> EIP712</span><span>, </span><span class="z-entity z-name">Nonces</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> CrossChainSignatureChecker</span><span class="z-keyword"> for</span><span class="z-entity z-name"> address</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 class="z-storage z-type"> constant</span><span> EIP712_CHAIN_DOMAIN_TYPEHASH </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;EIP712ChainDomain(uint256 chainId,address verifyingContract)&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> CHAIN_VOTE_TYPEHASH </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;ChainVote(EIP712ChainDomain domain,uint256 proposalId,uint8 support,string reason)EIP712ChainDomain(uint256 chainId,address verifyingContract)&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> MULTICHAIN_VOTE_TYPEHASH </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;MultiChainVote(ChainVote[] votes,uint256 nonce)ChainVote(EIP712ChainDomain domain,uint256 proposalId,uint8 support,string reason)EIP712ChainDomain(uint256 chainId,address verifyingContract)&quot;</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>)</span><span class="z-entity z-name"> EIP712</span><span>(</span><span>&quot;MultiChainDAO&quot;, &quot;1&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"> castVoteWithSignature</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> ChainVote</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> currentVote</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> voter</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"> erc7964Signature</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-support"> bytes32</span><span> currentVoteHash </span><span class="z-keyword">=</span><span class="z-entity z-name"> _structHash</span><span>(</span><span>currentVote</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> _useCheckedNonce</span><span>(</span><span>voter</span><span>,</span><span> nonce</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> voter</span><span>.</span><span class="z-entity z-name">isValidCrossChainSignatureNowCalldata</span><span>(</span></span> <span class="giallo-l"><span> currentVoteHash</span><span>,</span></span> <span class="giallo-l"><span> erc7964Signature</span><span>,</span></span> <span class="giallo-l"><span> _crossChainStructHash</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Invalid signature&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> _castVote</span><span>(</span><span>currentVote</span><span>.</span><span>proposalId</span><span>,</span><span> voter</span><span>,</span><span> currentVote</span><span>.</span><span>support</span><span>,</span><span> currentVote</span><span>.</span><span>reason</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"> _crossChainStructHash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> votesHash</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">encode</span><span>(</span><span>MULTICHAIN_VOTE_TYPEHASH</span><span>,</span><span> votesHash</span><span>,</span><span class="z-entity z-name"> nonces</span><span>(</span><span>voter</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"> _structHash</span><span>(</span><span class="z-storage z-type">ChainVote</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> vote</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> <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> CHAIN_VOTE_TYPEHASH</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>EIP712_CHAIN_DOMAIN_TYPEHASH</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>chainid</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></span> <span class="giallo-l"><span> vote</span><span>.</span><span>proposalId</span><span>,</span></span> <span class="giallo-l"><span> vote</span><span>.</span><span>support</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>vote</span><span>.</span><span>reason</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></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This vote signature can be submitted to DAO contracts on both Ethereum and Polygon, enabling coordinated multi-chain governance decisions.</p> <h3 id="unified-account-management-example">Unified Account Management Example</h3> <p>A user wants to add a new signer to their multisig account deployed across multiple chains:</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"> types</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> EIP712Domain</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">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 class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> MultiChainAccountUpdate</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">updates</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">AccountUpdate[]</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">nonce</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 class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> AccountUpdate</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">domain</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">EIP712ChainDomain</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">operation</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">uint8</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 0=addSigner, 1=removeSigner, 2=changeThreshold</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">signerData</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">bytes</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">threshold</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 class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> EIP712ChainDomain</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 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"> primaryType</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">MultiChainAccountUpdate</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">MultiChainMultisig</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> 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 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"> updates</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> chainId</span><span>:</span><span class="z-constant"> 1</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">0x123321...</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Account on Ethereum</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> operation</span><span>:</span><span class="z-constant"> 0</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> addSigner</span></span> <span class="giallo-l"><span> signerData</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> threshold</span><span>:</span><span class="z-constant"> 3</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> chainId</span><span>:</span><span class="z-constant"> 137</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">0x123321...</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Account on Polygon</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> operation</span><span>:</span><span class="z-constant"> 0</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> addSigner</span></span> <span class="giallo-l"><span> signerData</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> threshold</span><span>:</span><span class="z-constant"> 3</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> chainId</span><span>:</span><span class="z-constant"> 42161</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">0x123321...</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Account on Arbitrum</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> operation</span><span>:</span><span class="z-constant"> 0</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> addSigner</span></span> <span class="giallo-l"><span> signerData</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f20</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> threshold</span><span>:</span><span class="z-constant"> 3</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"> nonce</span><span>:</span><span class="z-constant"> 42</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>On-chain execution:</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">EIP712</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/cryptography/EIP712.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Nonces</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/Nonces.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">CrossChainSignatureChecker</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./CrossChainSignatureChecker.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"> MultiChainMultisig</span><span class="z-storage"> is</span><span class="z-entity z-name"> EIP712</span><span>, </span><span class="z-entity z-name">Nonces</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> CrossChainSignatureChecker</span><span class="z-keyword"> for</span><span class="z-entity z-name"> address</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 class="z-storage z-type"> constant</span><span> EIP712_CHAIN_DOMAIN_TYPEHASH </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;EIP712ChainDomain(uint256 chainId,address verifyingContract)&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> ACCOUNT_UPDATE_TYPEHASH </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;AccountUpdate(EIP712ChainDomain domain,uint8 operation,bytes signerData,uint256 threshold)EIP712ChainDomain(uint256 chainId,address verifyingContract)&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> MULTICHAIN_ACCOUNT_UPDATE_TYPEHASH </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;MultiChainAccountUpdate(AccountUpdate[] updates,uint256 nonce)AccountUpdate(EIP712ChainDomain domain,uint8 operation,bytes signerData,uint256 threshold)EIP712ChainDomain(uint256 chainId,address verifyingContract)&quot;</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>)</span><span class="z-entity z-name"> EIP712</span><span>(</span><span>&quot;MultiChainMultisig&quot;, &quot;1&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"> updateAccountWithSignature</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> AccountUpdate</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> currentUpdate</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> nonce</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"> erc7964Signature</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-support"> bytes32</span><span> currentUpdateHash </span><span class="z-keyword">=</span><span class="z-entity z-name"> _structHash</span><span>(</span><span>currentUpdate</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> _useCheckedNonce</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> nonce</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</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 class="z-entity z-name">isValidCrossChainSignatureNowCalldata</span><span>(</span></span> <span class="giallo-l"><span> currentUpdateHash</span><span>,</span></span> <span class="giallo-l"><span> erc7964Signature</span><span>,</span></span> <span class="giallo-l"><span> _crossChainStructHash</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Invalid signature&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>currentUpdate</span><span>.</span><span>operation </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"> _addSigner</span><span>(</span><span>currentUpdate</span><span>.</span><span>signerData</span><span>,</span><span> currentUpdate</span><span>.</span><span>threshold</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-comment"> //</span><span class="z-comment"> ... other operations</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"> _crossChainStructHash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> updatesHash</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">encode</span><span>(</span><span>MULTICHAIN_ACCOUNT_UPDATE_TYPEHASH</span><span>,</span><span> updatesHash</span><span>,</span><span class="z-entity z-name"> nonces</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><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"> _structHash</span><span>(</span><span class="z-storage z-type">AccountUpdate</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> update</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> <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> ACCOUNT_UPDATE_TYPEHASH</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>EIP712_CHAIN_DOMAIN_TYPEHASH</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>chainid</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></span> <span class="giallo-l"><span> update</span><span>.</span><span>operation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span>update</span><span>.</span><span>signerData</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> update</span><span>.</span><span>threshold</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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _addSigner</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> signerData</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> threshold</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Implementation for adding signer</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This signature enables the multisig owners to add a new signer and update the threshold across all chain deployments simultaneously. The same account address exists on Ethereum, Polygon, and Arbitrum, and this single signature authorizes the updates on all three networks.</p> <h3 id="crosschain-social-recovery-example">CrossChain Social Recovery Example</h3> <p>A user has lost access to their account and guardians need to initiate recovery across multiple networks:</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"> types</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> EIP712Domain</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">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 class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Note: verifyingContract is omitted since the recovery module is deployed on different addresses across chains for this example</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> MultiChainRecovery</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">recoveries</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">ChainRecovery[]</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">nonce</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 class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> ChainRecovery</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">domain</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">EIP712ChainDomain</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">newOwner</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 class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> EIP712ChainDomain</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 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"> primaryType</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">MultiChainRecovery</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">CrossChainSocialRecovery</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> 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 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"> recoveries</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> chainId</span><span>:</span><span class="z-constant"> 1</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">0x123321...</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Recovery module on Ethereum</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> newOwner</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9999999999999999999999999999999999999999</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> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> chainId</span><span>:</span><span class="z-constant"> 137</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">0x321321...</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Recovery module on Polygon</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> newOwner</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9999999999999999999999999999999999999999</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> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> chainId</span><span>:</span><span class="z-constant"> 42161</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">0x432432...</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Recovery module on Arbitrum</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> newOwner</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9999999999999999999999999999999999999999</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-entity z-name"> nonce</span><span>:</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>On-chain execution with guardian multisig:</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">CrossChainSignatureChecker</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./CrossChainSignatureChecker.sol&quot;</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> EIP712_CHAIN_DOMAIN_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;EIP712ChainDomain(uint256 chainId,address verifyingContract)&quot;</span></span> <span class="giallo-l"><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span class="z-storage z-type"> constant</span><span> CHAIN_RECOVERY_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;ChainRecovery(EIP712ChainDomain domain,address newOwner)EIP712ChainDomain(uint256 chainId,address verifyingContract)&quot;</span></span> <span class="giallo-l"><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span class="z-storage z-type"> constant</span><span> MULTICHAIN_RECOVERY_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;MultiChainRecovery(ChainRecovery[] recoveries,uint256 nonce)ChainRecovery(EIP712ChainDomain domain,address newOwner)EIP712ChainDomain(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">uint256</span><span class="z-storage z-type"> private</span><span> _tempNonce</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"> initiateRecoveryWithSignature</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> ChainRecovery</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> currentRecovery</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> nonce</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"> guardians</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> guardianErc7964Signatures</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>guardians</span><span>.</span><span>length </span><span class="z-keyword">==</span><span> guardianErc7964Signatures</span><span>.</span><span>length</span><span>,</span><span class="z-string"> &quot;Mismatched arrays&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-keyword"> Note</span><span class="z-comment">: chainId and verifyingContract validation is implicit in the struct hash verification</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Verify the current recovery hash matches all guardian signatures</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> currentRecoveryHash </span><span class="z-keyword">=</span><span class="z-entity z-name"> _structHash</span><span>(</span><span>currentRecovery</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _tempNonce </span><span class="z-keyword">=</span><span> nonce</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Verify all guardian signatures are valid and count valid guardian signatures</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validSignatures </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> guardians</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-keyword"> if</span><span> (</span></span> <span class="giallo-l"><span> CrossChainSignatureChecker</span><span>.</span><span class="z-entity z-name">isValidCrossChainSignatureNow</span><span>(</span></span> <span class="giallo-l"><span> guardians</span><span>[</span><span>i</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> currentRecoveryHash</span><span>,</span></span> <span class="giallo-l"><span> guardianErc7964Signatures</span><span>[</span><span>i</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> _computeRecoveryStructHash</span></span> <span class="giallo-l"><span> )</span><span class="z-keyword"> &amp;&amp;</span><span class="z-entity z-name"> isGuardian</span><span>(</span><span>guardians</span><span>[</span><span>i</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> )</span><span> {</span></span> <span class="giallo-l"><span> validSignatures</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"> require</span><span>(</span><span>validSignatures </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-constant"> 3</span><span>,</span><span class="z-string"> &quot;Insufficient guardian signatures&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"> Schedule recovery with delay</span></span> <span class="giallo-l"><span class="z-entity z-name"> _scheduleRecovery</span><span>(</span><span>currentRecovery</span><span>.</span><span>newOwner</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp </span><span class="z-keyword">+</span><span> RECOVERY_DELAY</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"> _computeRecoveryStructHash</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> recoveriesHash</span></span> <span class="giallo-l"><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">encode</span><span>(</span></span> <span class="giallo-l"><span> MULTICHAIN_RECOVERY_TYPEHASH</span><span>,</span></span> <span class="giallo-l"><span> recoveriesHash</span><span>,</span></span> <span class="giallo-l"><span> _tempNonce</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"> _structHash</span><span>(</span><span class="z-storage z-type">ChainRecovery</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> recovery</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> <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> CHAIN_RECOVERY_TYPEHASH</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>EIP712_CHAIN_DOMAIN_TYPEHASH</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>chainid</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></span> <span class="giallo-l"><span> recovery</span><span>.</span><span>newOwner</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>This signature enables guardians to schedule a recovery operation across all chains. The process includes:</p> <ol> <li><strong>Guardian Signatures</strong>: Multiple guardians sign the same crosschain recovery message (3-of-5 threshold)</li> <li><strong>Schedule Phase</strong>: Once sufficient guardians sign, the recovery is scheduled on all networks with a delay</li> <li><strong>Security Window</strong>: Delay period where malicious recovery attempts can be detected and canceled</li> <li><strong>Execution Phase</strong>: After the delay, the recovery replaces the account's owner</li> <li><strong>CrossChain Consistency</strong>: The same recovery operation is scheduled simultaneously on Ethereum, Polygon, and Arbitrum</li> </ol> <h2 id="security-considerations">Security Considerations</h2> <h3 id="crosschain-replay">Crosschain Replay</h3> <p>This ERC intentionally enables replay across chains, the same signature is designed to be used on multiple chains. The <code>verifyingContract</code> field (set to the user's account address) binds the signature to a specific account, preventing unauthorized use. However, applications must implement their own replay protection mechanisms such as including nonces and deadlines in the message.</p> <h3 id="account-validation">Account Validation</h3> <p>Applications verifying signatures should check that the signing account exists on the current chain. An account that exists on Ethereum but not Polygon should not have signatures accepted on Polygon. For counterfactual accounts that have not been deployed yet, applications should follow <a href="https://wg-eips.ritovision.com/6492/">ERC-6492</a> to validate signatures.</p> <h3 id="code-and-state-differences">Code and State Differences</h3> <p>Contract code and state may differ across chains at the same address. Signatures that pass <code>isValidSignature()</code> on one chain may fail on another due to state divergence or chain-specific logic. For example, a crosschain message that has uses a <code>nonce</code> field may find that the nonce is already used on one of the chains. Applications should handle signature validation failures gracefully and should not assume uniform behavior across chains.</p> <h3 id="partial-execution-risk">Partial Execution Risk</h3> <p>Crosschain signatures do not guarantee atomic execution. A signature may be successfully validated on some chains but not others. This can result in partial fulfillment of the intent. Applications should implement refund mechanisms to allow users to recover from failed partial executions.</p> <p>Additionally, operations may execute in different orders across chains due to varying network conditions, block times, and congestion levels. An operation intended to execute first may complete last on a congested chain, leading to unexpected state changes. For example, in a crosschain trade, a user might sell an asset on one chain before successfully acquiring its replacement on another chain, creating temporary exposure. Applications should design operations to be order-independent where possible, or implement coordination mechanisms to ensure proper sequencing.</p> <h3 id="signature-expiration">Signature Expiration</h3> <p>Signatures without explicit expiration remain valid indefinitely. If an operation is not executed on some chains, it can be executed later, potentially with unexpected consequences. Applications may include <code>deadline</code> or <code>validUntil</code> fields in messages to prevent stale signature execution.</p> <h3 id="wallet-display-considerations">Wallet Display Considerations</h3> <p>Since this ERC relies on standard EIP-712 wallet display, users depend on their wallet to correctly show all crosschain operations. Users should:</p> <ol> <li><strong>Review All Operations</strong>: Check every element in the message array</li> <li><strong>Verify Chain IDs</strong>: Ensure operations target the expected chains</li> <li><strong>Check Amounts</strong>: Verify asset amounts and addresses on each chain</li> <li><strong>Understand Atomicity</strong>: Know that operations may execute independently</li> </ol> <p>Wallet developers should enhance displays to highlight crosschain nature and show warnings about partial execution risks.</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-05-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 Wei Tanghttps://github.com/sorpaas https://wg-eips.ritovision.com/7960/

Extend EOF container's types section with an extra type parameter.

<h2 id="abstract">Abstract</h2> <p>This EIP extends the definition of <code>types_section</code> in EOF format (<a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a>) with an additional <code>type</code> parameter.</p> <h2 id="motivation">Motivation</h2> <p>An additional <code>type</code> parameter allows the EOF EVM interpreter to identify the "type" of a code section. This allows the interpreter to "interpret" each code section differently, allowing EOF function calls to, for example, invoke pure EVM64 code or even later support RISC-V.</p> <h2 id="specification">Specification</h2> <p><code>types_section</code>, as defined in EIP-3540, is changed to be of the following format <code>(type, reserved, inputs, outputs, max_stack_increase)</code>. <code>type</code> is <code>uint8</code>, <code>reserved</code> is 24 bits, and <code>inputs</code>, <code>outputs</code>, <code>max_stack_increase</code> are defined as <code>uint8</code>, <code>uint8</code>, <code>uint16</code> respectively, the same as before. The only valid <code>type</code> defined in this EIP is <code>0x01</code>. Additional EIPs may be defined for other code section <code>type</code>s.</p> <p><code>version</code>, as defined in EIP-3540, is changed to <code>0x02</code>, to avoid the backward compatibility issue if a third-party chain already deployed EOF in production.</p> <p>In EOF container, the following validation rules are added:</p> <ul> <li>If a <code>type</code> in <code>types_section</code> is not of a known type, then the validation fails.</li> <li><code>reserved</code> in <code>types_section</code> must be all zeros.</li> </ul> <h2 id="rationale">Rationale</h2> <p>The new <code>type</code> parameter allows a contract to "dispatch" to different variants of the interpreter to better suit its need.</p> <ul> <li>The portion of the code where it mainly interacts with Ethereum addresses, balances, storages may run "normal" EVM.</li> <li>The portion of the code that is computationally heavy may run faster EVM64, but loses the ability to directly interact with Ethereum addresses and balances.</li> </ul> <p>Allowing this <code>type</code> to be defined for each code section ensures that a contract remains concise -- it can quickly switch between its computational needs and system/runtime needs.</p> <p><code>reserved</code> is added to <code>types_section</code> to maintain the proper padding. Each item in <code>types_section</code> is now 64 bits in total.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As we know, EOF, including EIP-3540, was extremely close to being deployed before it was decided to withdraw from Fusaka. To avoid the issue that some third-party chains have already deployed EOF in production (given the state of EOF we can consider this to be likely), we bump <code>version</code> of EOF to <code>0x02</code>. <code>0x01</code> is now invalid.</p> <p>No other 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-05-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 Wei Tanghttps://github.com/sorpaas https://wg-eips.ritovision.com/7961/

Define "pure" EVM64 mode, as an EOF code section.

<h2 id="abstract">Abstract</h2> <p>An EOF-only specification for EVM64 instruction set. This defines a separate "EVM64" type for EOF code section in addition to "regular EVM". The interpreter then enters EVM64 mode when entering the code section. This EIP is an alternative to <a href="https://wg-eips.ritovision.com/7937/">EIP-7937</a>.</p> <h2 id="motivation">Motivation</h2> <p>EIP-7937 has maximum compatibility with existing EVM. It implements EVM64 simply as a group of additional opcodes (using a prefix opcode). This EIP defines an alternative method, using EOF container's code section. It has its pros and cons. The code size will obviously become shorter, due to not needing multibyte opcodes any more. On the other hand, interop with EVM system calls become more difficult because it cannot be done in an EVM64 code section. The advantages and disadvantages are discussed further in the Rationale section.</p> <h2 id="specification">Specification</h2> <p>Define <code>0x02</code> as an allowed <code>type</code> in <code>types_section</code>, as defined in EIP-7960. This denotes an EVM64 code section.</p> <h3 id="eof-function-execution">EOF function execution</h3> <p>When entering an EOF code section (either at the beginning of the contract call, or through <code>CALLF</code>), it enters "pure EVM64 mode". Unless defined below, no other opcodes are allowed. Those opcodes all only operate on the least significant 64-bit, in little endian.</p> <p>During EOF validation, the validation function should enforce that only allowed opcodes exist.</p> <h3 id="gas-cost-constants">Gas cost constants</h3> <p>We define the following gas cost constants:</p> <ul> <li><code>G_BASE64</code>: 1</li> <li><code>G_VERYLOW64</code>: 2</li> <li><code>G_LOW64</code>: 3</li> <li><code>G_MID64</code>: 5</li> <li><code>G_HIGH64</code>: 7</li> <li><code>G_EXP64_STATIC</code>: 5</li> <li><code>G_EXP64_DYNAMIC</code>: 25</li> <li><code>G_RJUMPIV64</code>: 3</li> </ul> <h3 id="arithmetic-opcodes">Arithmetic opcodes</h3> <p>The 64-bit mode arithmetic opcodes are defined the same as non-64-bit mode, except that they only operate on the least significant 64-bits. In the below definition, <code>a</code>, <code>b</code>, <code>N</code> is <code>a mod 2^64</code>, <code>b mod 2^64</code> and <code>N mod 2^64</code>.</p> <ul> <li>ADD (<code>01</code>) and SUB (<code>03</code>): <code>a op b mod 2^64</code>, gas cost <code>G_VERYLOW64</code>.</li> <li>MUL (<code>02</code>), DIV (<code>04</code>), SDIV (<code>05</code>), MOD (<code>06</code>), SMOD (<code>07</code>), SIGNEXTEND (<code>0B</code>): <code>a op b mod 2^64</code>, gas cost <code>G_LOW64</code>.</li> <li>ADDMOD (<code>08</code>), MULMOD (<code>09</code>): <code>a op b % N mod 2^64</code>, gas cost <code>G_MID64</code>.</li> <li>EXP (<code>0A</code>): <code>a EXP b mod 2^64</code>, gas cost <code>static_gas = G_EXP64_STATIC, dynamic_gas = G_EXP64_DYNAMIC * exponent_byte_size</code>.</li> </ul> <h3 id="comparison-and-bitwise-opcodes">Comparison and bitwise opcodes</h3> <p>The 64-bit mode comparison and bitwise opcodes are defined the same as non-64-bit mode, except that they only operate on the least significant 64 bits.</p> <ul> <li>LT (<code>10</code>), GT (<code>11</code>), SLT (<code>12</code>), SGT (<code>13</code>), EQ (<code>14</code>), AND (<code>16</code>), OR (<code>17</code>), XOR (<code>18</code>): <code>a op b mod 2^64</code>, gas cost <code>G_VERYLOW64</code></li> <li>ISZERO (<code>15</code>), NOT (<code>19</code>): <code>op a mod 2^64</code>, gas cost <code>G_VERYLOW64</code></li> <li>SHL (<code>1B</code>), SHR (<code>1C</code>), SAR (<code>1D</code>): <code>a op N mod 2^64</code>, gas cost <code>G_VERYLOW64</code></li> <li>BYTE (<code>1A</code>) is defined as <code>(x &gt;&gt; i * 8) &amp; 0xFF</code>. Note that the definition is changed from big endian to little endian.</li> </ul> <h3 id="memory-opcodes">Memory opcodes</h3> <p><code>MLOAD64</code> (0x51) will load a 64-bits integer in little endian onto the stack. <code>MSTORE64</code> (0x52) will read an 64-bits 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><code>MSTORE8</code> is available in EVM64 mode, and its gas cost is the same as in "normal" EVM.</p> <h3 id="stack-opcodes">Stack opcodes</h3> <p><code>PUSH0</code> (0x5f) to <code>PUSH8</code> (0x67) follows 0-byte to 8-byte literal. The literal is read little endian and pushed onto the stack. The gas cost for them is <code>G_VERYLOW64</code>.</p> <p><code>POP</code>, <code>SWAPn</code> and <code>DUPn</code> are available in EVM64 mode, and their gas costs are the same as in "normal" EVM.</p> <h3 id="other-opcodes">Other opcodes</h3> <p>Contract opcodes <code>RETURN</code>, <code>REVERT</code>, <code>INVALID</code> are available in EVM64 mode. Their behaviors, including gas costs, are unchanged. However, for all stack items, only the least significant 64 bits are read.</p> <p><code>CALLF</code>, <code>RETF</code>, <code>RJUMP</code> are available in EVM64 mode. Their behaviors, including gas costs, are unchanged.</p> <p>For flow operations RJUMPI and RJUMPV, the 64-bit mode has following changes:</p> <ul> <li>For <code>RJUMPI64</code> (0xe1), the condition popped from stack is only read for the last 64 bits. Gas cost is <code>G_RJUMPIV64</code>.</li> <li>For <code>RJUMPV64</code> (0xe2), the case popped from stack is only read for the last 64 bits. Gas cost is <code>G_RJUMPIV64</code>.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="stack-behavior">Stack behavior</h3> <p>"Pure" in "pure EVM64" refers to the fact that all opcodes in EVM64 mode only operate on the least significant 64 bits. In this specification, we don't specifically define 64-bit stack. As far as this EIP is concerned, stack is still 256-bit. However, because they only operate on the least significant 64 bits. The most significant 192 bits becomes unobservable as long as the interpreter is in an EVM64 code section. Thus an EVM interpreter can optimize EVM64 execution as follows:</p> <ul> <li>When entering EVM64 code section, truncate <code>inputs</code> to 64 bits.</li> <li>Use 64-bit stack during EVM64 execution.</li> <li>When exiting EVM64 code section, prepend <code>0</code> to <code>outputs</code> to make it 256 bits.</li> </ul> <h3 id="discussions">Discussions</h3> <p>This alternative definition (compared with EIP-7937) has the advantage that the code size is now shorter (because no multibyte opcodes are needed). It however will only work with EOF contract but not "legacy" EVM. The interaction between EVM64 and "system calls" (those calls that read Ethereum block values, addresses, balances and storages) will be more difficult. It's not "seamless" like EIP-7937 where one can enter/exit 64-bit mode at ease. Depending on how the 64-bit optimization works out, this may be an advantage or a disadvantage.</p> <p>The memory is, as usual, still shared during the entire execution. So in EVM64, the contract can always use the memory to push/fetch data.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <!-- TODO: Add test cases and reference implementation --> <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> 2025-05-27T00:00:00+00:00 2026-02-11T14:49:28+00:00 Carl Beekhuizenhttps://github.com/carlbeek Ulaş Erdoğanhttps://github.com/ulerdogan Doğan Alpaslanhttps://github.com/doganalpaslan https://wg-eips.ritovision.com/7951/

Add precompiled contract for secp256r1 ECDSA signature verification with proper security checks

<h2 id="abstract">Abstract</h2> <p>Add functionality to efficiently perform ECDSA signature verification over the secp256r1 elliptic curve (also known as P-256 or prime256v1). This precompile enables native support for signatures generated by modern secure hardware including Apple Secure Enclave, Android Keystore, and FIDO2/WebAuthn devices.</p> <p>This specification addresses critical security issues discovered in RIP-7212 while maintaining full interface compatibility with existing Layer 2 implementations.</p> <h2 id="motivation">Motivation</h2> <p>The secp256r1 elliptic curve is a NIST-standardized curve widely supported in modern secure hardware and authentication systems. Adding native support for secp256r1 signature verification to Ethereum enables several important use cases that are currently impossible or prohibitively expensive.</p> <p>Modern secure hardware devices, including Apple Secure Enclave, Android Keystore, HSMs, TEEs, and FIDO2/WebAuthn authenticators, use secp256r1 for key storage and signing operations. Native secp256r1 support enables sophisticated account abstraction patterns like device-native signing, multi-factor authentication, and simplified key management - ultimately reducing friction for mainstream adoption through familiar authentication flows.</p> <p>The secp256r1 curve is already widely supported across blockchain networks and protocols, including Layer 2 networks, enterprise blockchains, and interoperability protocols. This broad compatibility enables seamless integration with existing infrastructure while maintaining security through hardware-backed signing capabilities.</p> <p>This EIP supersedes RIP-7212 by implementing the same functionality with the same interface, but without the vulnerability.</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="precompile">Precompile</h3> <p>We introduce <code>P256VERIFY</code> a precompile at the address <code>0x100</code> which performs ECDSA signature verification over the secp256r1 curve with a gas cost of <code>6900</code> gas</p> <h3 id="curve-parameters">Curve Parameters</h3> <p>The secp256r1 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 = p = 0xffffffff00000001000000000000000000000000ffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>Curve equation: y^2 = x^3 + ax + b (mod p)</span></span> <span class="giallo-l"><span>Curve coefficient a = 0xffffffff00000001000000000000000000000000fffffffffffffffffffffffc</span></span> <span class="giallo-l"><span>Curve coefficient b = 0x5ac635d8aa3a93e7b3ebbd55769886bc651d06b0cc53b0f63bce3c3e27d2604b</span></span> <span class="giallo-l"><span>Base point G:</span></span> <span class="giallo-l"><span> Gx = 0x6b17d1f2e12c4247f8bce6e563a440f277037d812deb33a0f4a13945d898c296</span></span> <span class="giallo-l"><span> Gy = 0x4fe342e2fe1a7f9b8ee7eb4a7c0f9e162bce33576b315ececbb6406837bf51f5</span></span> <span class="giallo-l"><span>Subgroup order = n = 0xffffffff00000000ffffffffffffffffbce6faada7179e84f3b9cac2fc632551</span></span> <span class="giallo-l"><span>Cofactor = h = 0x1</span></span></code></pre> <p>These parameters are standardized by NIST in SP 800-186<sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">1</a></sup>.</p> <h3 id="fields-and-groups">Fields and Groups</h3> <p>The field Fp is defined as the finite field of size <code>p</code> with elements represented as integers between 0 and p-1 (both inclusive).</p> <p>The group G is defined as a set of Fp pairs (points) <code>(x,y)</code> such that either <code>(x,y)</code> is <code>(0,0)</code> (representing the point at infinity) or <code>x,y</code> satisfy the curve equation <code>y^2 = x^3 + ax + b (mod p)</code>.</p> <h3 id="points-and-encoding">Points and Encoding</h3> <h4 id="field-elements-encoding">Field Elements Encoding</h4> <p>A base field element (Fp) is encoded as <code>32</code> bytes by performing BigEndian encoding of the corresponding (unsigned) integer. The corresponding integer <strong>must</strong> be less than the field modulus <code>p</code>.</p> <h4 id="encoding-of-points-in-g">Encoding of Points in G</h4> <p>Points in G are encoded as byte concatenation of the respective encodings of the <code>x</code> and <code>y</code> coordinates. Total encoding length for a G point is thus <code>64</code> bytes.</p> <h4 id="point-of-infinity-encoding">Point of Infinity Encoding</h4> <p>For secp256r1, the point with coordinates <code>(0, 0)</code> (zeroes in Fp) is <em>not</em> on the curve, so a sequence of <code>64</code> zero bytes is used by convention to encode the point of infinity.</p> <h4 id="encoding-of-scalars">Encoding of Scalars</h4> <p>A scalar is encoded as <code>32</code> bytes by performing BigEndian encoding of the corresponding (unsigned) integer. The corresponding integer is <strong>not</strong> required to be less than or equal to the subgroup order <code>n</code>.</p> <h4 id="behavior-on-invalid-inputs">Behavior on Invalid Inputs</h4> <p>On inputs that cannot be valid encodings of field elements or points, the precompile <em>must</em> return `` (failure).</p> <h3 id="abi-for-p256verify-operation">ABI for <code>P256VERIFY</code> Operation</h3> <h4 id="input">Input</h4> <p><code>P256VERIFY</code> call expects <code>160</code> bytes as input that is interpreted as byte concatenation of:</p> <ul> <li><code>32</code> bytes: message hash <code>h</code></li> <li><code>32</code> bytes: signature component <code>r</code></li> <li><code>32</code> bytes: signature component <code>s</code></li> <li><code>32</code> bytes: public key x-coordinate <code>qx</code></li> <li><code>32</code> bytes: public key y-coordinate <code>qy</code></li> </ul> <h4 id="output">Output</h4> <p>Output is <code>32</code> bytes on successful verification and <code>0</code> bytes on failure:</p> <ul> <li><code>0x0000000000000000000000000000000000000000000000000000000000000001</code> for valid signatures</li> <li>`` for invalid signatures or invalid inputs</li> </ul> <h4 id="input-validation">Input Validation</h4> <p>The precompile MUST perform the following validation checks and return `` (failure) if any check fails:</p> <ol> <li><strong>Input length</strong>: Input MUST be exactly <code>160</code> bytes</li> <li><strong>Signature component bounds</strong>: Both <code>r</code> and <code>s</code> MUST satisfy <code>0 &lt; r &lt; n</code> and <code>0 &lt; s &lt; n</code></li> <li><strong>Public key bounds</strong>: Both <code>qx</code> and <code>qy</code> MUST satisfy <code>0 ≤ qx &lt; p</code> and <code>0 ≤ qy &lt; p</code></li> <li><strong>Point validity</strong>: The point <code>(qx, qy)</code> MUST satisfy the curve equation <code>qy^2 ≡ qx^3 + a*qx + b (mod p)</code></li> <li><strong>Point not at infinity</strong>: The point <code>(qx, qy)</code> MUST NOT be the point at infinity (represented as <code>(0, 0)</code>)</li> </ol> <h4 id="signature-verification-algorithm">Signature Verification Algorithm</h4> <p>The verification algorithm follows these steps:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span># Input validation (as specified above)</span></span> <span class="giallo-l"><span>if input_length != 160:</span></span> <span class="giallo-l"><span> return</span></span> <span class="giallo-l"><span>if not (0 &lt; r &lt; n and 0 &lt; s &lt; n):</span></span> <span class="giallo-l"><span> return</span></span> <span class="giallo-l"><span>if not (0 ≤ qx &lt; p and 0 ≤ qy &lt; p):</span></span> <span class="giallo-l"><span> return </span></span> <span class="giallo-l"><span>if qy^2 ≢ qx^3 + a*qx + b (mod p):</span></span> <span class="giallo-l"><span> return</span></span> <span class="giallo-l"><span>if (qx, qy) == (0, 0):</span></span> <span class="giallo-l"><span> return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Signature verification</span></span> <span class="giallo-l"><span>s1 = s^(-1) (mod n)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Recover the random point used during signing</span></span> <span class="giallo-l"><span>R&#39; = (h * s1) * G + (r * s1) * (qx, qy)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Check for point at infinity</span></span> <span class="giallo-l"><span>if R&#39; is the point at infinity:</span></span> <span class="giallo-l"><span> return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Extract x-coordinate from r</span></span> <span class="giallo-l"><span>r&#39; = R&#39;.x</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Compare with modular reduction</span></span> <span class="giallo-l"><span>if r&#39; ≡ r (mod n):</span></span> <span class="giallo-l"><span> return 0x0000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>else:</span></span> <span class="giallo-l"><span> return </span></span></code></pre><h4 id="error-cases">Error Cases</h4> <ul> <li>Invalid input length (not exactly 160 bytes)</li> <li>Invalid field element encoding (≥ field modulus)</li> <li>Invalid signature component bounds (r or s not in range (0, n))</li> <li>Invalid public key (point at infinity or not on curve)</li> <li>Signature verification failure</li> </ul> <h3 id="gas-schedule">Gas Schedule</h3> <h4 id="p256verify-operation"><code>P256VERIFY</code> operation</h4> <p><code>6900</code> gas</p> <p>This cost is based on benchmarking against the existing <code>ECRECOVER</code> precompile (<code>3000</code> gas). During benchmarks we found that the actual cost of R1 verification was significantly slower than the <code>ECRECOVER</code> precompile and the decision was made to increase the gas cost to <code>6900</code> gas.</p> <h4 id="gas-burning-on-error">Gas Burning on Error</h4> <p>The precompile MUST NOT revert under any circumstances. Invalid inputs or verification failures MUST return `` and consume the same amount of gas had verification succeeded.</p> <h2 id="rationale">Rationale</h2> <h3 id="security-fixes">Security Fixes</h3> <p>This specification addresses two critical vulnerabilities in RIP-7212:</p> <ol> <li> <p><strong>Point-at-infinity check</strong>: The original RIP-7212 failed to check if the recovered point R' is the point at infinity. This could lead to non-deterministic behavior where the verification result depends on the underlying implementation's handling of infinity points, potentially causing consensus failures.</p> </li> <li> <p><strong>Modular comparison</strong>: The original comparison <code>r' == r</code> should be <code>r' ≡ r (mod n)</code> to handle cases where the x-coordinate of R' exceeds the curve order n. This ensures mathematically correct verification according to ECDSA standards.</p> </li> </ol> <h3 id="verification-vs-recovery">Verification vs Recovery</h3> <p>This specification uses signature verification rather than public key recovery (like <code>ECRECOVER</code>) because:</p> <ul> <li>Most secp256r1 implementations in hardware and software verify signatures directly</li> <li>The NIST FIPS 186-5 standard[^2] specifies verification, not recovery</li> <li>Verification is more efficient than recovery for this curve</li> <li>Existing hardware implementations provide verification interfaces</li> </ul> <h3 id="gas-cost-justification">Gas Cost Justification</h3> <p>The 6900 gas cost does not maintain compatibility with L2s, but it matches closer the benchmarks of actual implementations.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP maintains full interface compatibility with RIP-7212 implementations deployed on Layer 2 networks. The same contract bytecode that works with RIP-7212 will work with this specification.</p> <p>The security fixes are transparent to correctly implemented callers - they only affect edge cases that should have failed verification anyway. No existing valid use cases are broken.</p> <h3 id="interface-compatibility">Interface Compatibility</h3> <p>The precompile maintains a similar interface as RIP-7212 to ensure compatibility with existing Layer 2 deployments:</p> <ul> <li>Same address: <code>0x100</code></li> <li>Same input format: 160 bytes</li> <li>Same output format: 32 bytes</li> <li>Different gas cost: 3450 gas vs 6900 gas</li> <li>Same return values</li> </ul> <h2 id="test-cases">Test Cases</h2> <p>A set of test vectors for verifying implementations is located in a separate <a href="https://wg-eips.ritovision.com/7951/./assets/test-vectors.json">file</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A reference implementation is not supplied due to the ubiquity of secp256r1, if however a reference is needed, the NIST specification in FIPS 186-5[^2]</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="cryptographic-security">Cryptographic Security</h3> <p>The secp256r1 curve provides approximately 128 bits of security, equivalent to secp256k1 already in use in Ethereum. The curve parameters are standardized by NIST SP 800-186<sup class="footnote-reference" id="fr-1-2"><a href="#fn-1">1</a></sup> and have undergone extensive cryptographic analysis by the wider cryptographic community in addition to this curve being deployed to several L2s in the form of RIP-7212.</p> <h3 id="malleability">Malleability</h3> <p>Unlike secp256k1 ECDSA signatures, secp256r1 ECDSA signatures are not required to be non-malleable per NIST FIPS 186-5 standard [^2]. Applications requiring non-malleability should implement additional checks at the application layer.</p> <h3 id="side-channel-resistance">Side-Channel Resistance</h3> <p>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> <section class="footnotes"> <ol class="footnotes-list"> <li id="fn-1"> <p>Chen, L., Moody, D., Regenscheid, A., Randall, K., &amp; Robinson, A. (2023). <span style="font-style: italic;">Recommendations for Discrete Logarithm-based Cryptography: Elliptic Curve Domain Parameters</span> (Nos. 800–186). National Institute of Standards and Technology. https://doi.org/<a href="https://doi.org/10.6028/NIST.SP.800-186">10.6028/NIST.SP.800-186</a>[^2]: National Institute of Standards and Technology. (2023). <span style="font-style: italic;">Digital Signature Standard (DSS)</span> (Nos. 186–5). National Institute of Standards and Technology. https://doi.org/<a href="https://doi.org/10.6028/NIST.FIPS.186-5">10.6028/NIST.FIPS.186-5</a> <a href="#fr-1-1">↩</a> <a href="#fr-1-2">↩2</a></p> </li> </ol> </section> 2025-05-26T00:00:00+00:00 2026-02-11T14:49:27+00:00 Wei Tanghttps://github.com/sorpaas https://wg-eips.ritovision.com/7957/

EVM Object Format support for EVM64

<h2 id="abstract">Abstract</h2> <p>This EIP defines EOF support for EVM64 with its additional code validation rules and <code>RJUMPI</code>, <code>RJUMPV</code> opcodes.</p> <h2 id="motivation">Motivation</h2> <p>EOF defines a stricter code validation rule to improve efficiency. Due to EVM64 using multibyte opcode (the mode opcode <code>C0</code>), a small adaptation is needed. This EIP also additionally defines a 64-bit mode <code>RJUMPI</code> and <code>RJUMPV</code> to be 64-bit.</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> <table><thead><tr><th>Name</th><th>Gas</th></tr></thead><tbody> <tr><td><code>G_RJUMPIV64</code></td><td><code>3</code></td></tr> </tbody></table> <p>At EOF contract creation time as defined in <a href="https://wg-eips.ritovision.com/3670/">EIP-3670</a>, if the opcode <code>C0</code> is encountered and it is not part of PUSH opcode's data, then the interpreter MUST validate that:</p> <ul> <li>The next opcode exists.</li> <li>The next opcode is <code>RJUMPI64</code>, <code>RJUMPV64</code>, or one of the core 64-bit opcode defined in <a href="https://wg-eips.ritovision.com/7937/">EIP-7937</a> minus <code>JUMP64</code> and <code>JUMPI64</code>.</li> </ul> <p>For flow operations RJUMPI and RJUMPV, the 64-bit mode has following changes:</p> <ul> <li>For <code>RJUMPI64</code> (0xc0e1), the condition popped from stack is only read for the last 64 bits. Gas cost is <code>G_RJUMPIV64</code>.</li> <li>For <code>RJUMPV64</code> (0xc0e2), the case popped from stack is only read for the last 64 bits. Gas cost is <code>G_RJUMPIV64</code>.</li> </ul> <p>Note that:</p> <ul> <li><code>RJUMP</code> is automatically in 64-bit mode because it does not read or write the stack.</li> </ul> <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-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-05-24T00:00:00+00:00 2026-02-11T14:49:28+00:00 Aryaethnhttps://github.com/aryaethn https://wg-eips.ritovision.com/7956/

Decreasing MEV attacks by forcing a deterministic transaction ordering via block-level randomness.

<h2 id="abstract">Abstract</h2> <p>Proposers and builders can currently permute pending transactions arbitrarily, enabling reorder‑driven MEV. This EIP introduces a consensus rule that sorts all transactions inside a block by XOR‑ing each transaction hash with fresh slot randomness. The randomness is unknown until the slot starts, so the order is deterministic once known but unpredictable beforehand. The mechanism <strong>significantly reduces reorder‑based MEV</strong>; latency‑driven back‑running, censorship, and other classes of MEV remain and should be mitigated through complementary techniques (encrypted mempools, reputation, PBS marketplaces, etc.).</p> <h2 id="motivation">Motivation</h2> <p>Unrestricted ordering is the key enabler of sandwich and classic front‑running attacks. Deterministic ordering collapses these vectors to latency racing and information asymmetry. Clear candidate‑set and bundle semantics preserve fee markets while removing the need for trusted sequencers. Academic works shows deterministic ordering drives sandwich profits toward zero.</p> <h3 id="references">References</h3> <ul> <li> <p>Julia Ofoegbu, “Maximal Extractable Value (MEV): A Tale As Old As Time,” Medium (2024).</p> </li> <li> <p>J. Qian et al., “Deterministic Transaction Ordering Without Trusted Sequencers,” arXiv:2411.03327 v1 (2024).</p> </li> <li> <p>“Shutter Network Introduces Plan for First Encrypted Mempool on Ethereum,” GlobeNewswire, 13 Feb 2025.</p> </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> <h3 id="slot-randomness-r">Slot Randomness <code>R</code></h3> <p>We define our randomness <code>R</code> as the <code>randao_reveal</code> of the each slot, after <a href="https://wg-eips.ritovision.com/7998/">EIP-7998</a>, since this EIP provides slot-by-slot randomness for <code>randao_reveal</code> (only predictable for the builder). This provides enough randomness for our purpose of reducing MEV attacks by MEV bots.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>R = body.randao_reveal[0:32] : bytes32</span></span></code></pre><h3 id="builder-flow">Builder Flow</h3> <ol> <li><strong>Candidate‑set selection</strong> – Builders <strong>MAY</strong> choose <strong>any subset</strong> of the mempool based on priority fees, side agreements, or policy. Transactions not chosen are ignored.</li> <li><strong>Canonical sorting</strong> – Sort the chosen set by primary key <code>H(tx) ⊕ R</code> ascending, then secondary key <code>H(tx)</code> ascending, in case of collision on the primary key.</li> <li><strong>Gas‑limit packing</strong> – Append items in order until adding the next would exceed the block gas <strong>limit</strong>.</li> <li><strong>Bundles (optional cross‑address atomicity)</strong></li> </ol> <ul> <li> <p><strong>Definition</strong> – A bundle is a user‑signed list of fully‑signed transactions. Each <code>child_tx_rlp</code> is the canonical <strong>signed</strong> RLP encoding, including signature fields <code>(v, r, s)</code>. The bundle begins with a <em>fee‑payment</em> transaction that covers gas and builder tip for the entire bundle.</p> </li> <li> <p><strong>Hashing / sort key</strong> – Treat the bundle as a <em>virtual transaction</em> with key <code>H(concat(child_tx_rlps))</code>, where:</p> <ul> <li><code>child_tx_rlps[i]</code> <strong>MUST</strong> be the exact bytes that will later appear in the block body for that transaction, i.e. the <em>canonical RLP of the fully‑signed transaction</em> per <a href="https://wg-eips.ritovision.com/2718/">EIP‑2718</a> / <a href="https://wg-eips.ritovision.com/155/">EIP‑155</a> rules (for typed transactions the leading <em>type byte</em> and length prefix are included).</li> <li>Implementations <strong>MUST NOT</strong> strip or normalise the signature fields <code>(v,r,s)</code>; those 65 bytes are hashed as‑is so every participant derives an identical bundle key.</li> <li>The concatenation order is the author‑declared execution order of the child transactions.</li> </ul> </li> <li> <p><strong>Gas accounting</strong> – Bundle gas is the <strong>sum of the <code>gasLimit</code> fields</strong> of all child transactions. Builders use that sum when evaluating step 3.</p> </li> <li> <p><strong>Fit‑or‑skip rule</strong> – If the bundle (fee‑payment + children) would exceed the remaining gas limit, the bundle is skipped atomically.</p> </li> </ul> <ol start="5"> <li><strong>Fee dynamics</strong> – Priority fees influence membership in the candidate set (step 1) but <strong>never</strong> override the canonical order once a tx or bundle is selected.</li> </ol> <p>Here is a pseudocode for the above flow:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>//---------------------------------------------------------------------</span></span> <span class="giallo-l"><span>// Inputs</span></span> <span class="giallo-l"><span>//---------------------------------------------------------------------</span></span> <span class="giallo-l"><span>// mempool : All pending txs &amp; user-signed bundles visible to the builder</span></span> <span class="giallo-l"><span>// R : 32-byte slot randomness supplied by randao_reveal</span></span> <span class="giallo-l"><span>// BLOCK_GAS_LIMIT : Max gas allowed in the block</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 HASH(obj) → bytes32 // Keccak-256 of the byte sequence</span></span> <span class="giallo-l"><span>function PRIMARY_KEY(h, R) → bytes32 // h XOR R (bit-wise)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function bundleGas(bundle): // sum of gasLimit of children</span></span> <span class="giallo-l"><span> total ← 0</span></span> <span class="giallo-l"><span> for childTx in bundle.children:</span></span> <span class="giallo-l"><span> total ← total + childTx.gasLimit</span></span> <span class="giallo-l"><span> return total</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>//---------------------------------------------------------------------</span></span> <span class="giallo-l"><span>// 0. Candidate-set selection (builder policy / side deals / fee filter)</span></span> <span class="giallo-l"><span>//---------------------------------------------------------------------</span></span> <span class="giallo-l"><span>candidates ← pickSubsetFrom(mempool) // ANY subset is allowed</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>//---------------------------------------------------------------------</span></span> <span class="giallo-l"><span>// 1. Compute canonical keys &amp; gas cost for every candidate</span></span> <span class="giallo-l"><span>//---------------------------------------------------------------------</span></span> <span class="giallo-l"><span>for item in candidates:</span></span> <span class="giallo-l"><span> if item.type == &quot;single_tx&quot;:</span></span> <span class="giallo-l"><span> item.gasCost ← item.gasLimit</span></span> <span class="giallo-l"><span> baseHash ← HASH(item.RLP) // canonical signed RLP (EIP-2718)</span></span> <span class="giallo-l"><span> else if item.type == &quot;bundle&quot;:</span></span> <span class="giallo-l"><span> concatRlps ← CONCAT(item.child_rlps) // fee-tx + children in author order</span></span> <span class="giallo-l"><span> item.gasCost ← bundleGas(item)</span></span> <span class="giallo-l"><span> baseHash ← HASH(concatRlps)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> item.primaryKey ← PRIMARY_KEY(baseHash, R)</span></span> <span class="giallo-l"><span> item.secondaryKey ← baseHash</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>//---------------------------------------------------------------------</span></span> <span class="giallo-l"><span>// 2. Canonical sorting (primaryKey asc, then secondaryKey asc)</span></span> <span class="giallo-l"><span>//---------------------------------------------------------------------</span></span> <span class="giallo-l"><span>sort(candidates, by = (primaryKey ASC, secondaryKey ASC))</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>//---------------------------------------------------------------------</span></span> <span class="giallo-l"><span>// 3. Gas-limit packing with fit-or-skip for bundles</span></span> <span class="giallo-l"><span>//---------------------------------------------------------------------</span></span> <span class="giallo-l"><span>blockList ← empty list</span></span> <span class="giallo-l"><span>gasUsed ← 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>for item in candidates:</span></span> <span class="giallo-l"><span> if gasUsed + item.gasCost &gt; BLOCK_GAS_LIMIT:</span></span> <span class="giallo-l"><span> continue // skip whole tx or bundle atomically</span></span> <span class="giallo-l"><span> append(blockList, item)</span></span> <span class="giallo-l"><span> gasUsed ← gasUsed + item.gasCost</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>//---------------------------------------------------------------------</span></span> <span class="giallo-l"><span>// 4. Output — assemble block body &amp; header field</span></span> <span class="giallo-l"><span>//---------------------------------------------------------------------</span></span> <span class="giallo-l"><span>block.randomness ← R // bytes16 in the payload header</span></span> <span class="giallo-l"><span>block.txOrderingVersion ← 1</span></span> <span class="giallo-l"><span>block.body ← flatten(blockList) // bundles explode into children</span></span> <span class="giallo-l"><span>return block</span></span></code></pre><h3 id="consensus-rule">Consensus Rule</h3> <p>A block is <strong>invalid</strong> if the executed list deviates from the canonical order derived from its <code>randomness</code> and the included transactions/bundles. Verification is objective; fork‑choice remains unchanged.</p> <h3 id="performance">Performance</h3> <p>Sorting ≤ 1 500 transactions remains <code>O(n log n)</code> (&lt; 1 ms), on today's hardware.</p> <h3 id="deployment">Deployment</h3> <h4 id="added-parameters">Added Parameters</h4> <ul> <li><code>randomness</code>: Specified in the specification.</li> <li><code>txOrderingVersion = 1</code> flag: To be compatible with the existing consensus rule and adding compatibility for future rules if needed.</li> </ul> <h4 id="fork-parameters">Fork Parameters</h4> <ul> <li><code>ORDERING_FORK_EPOCH</code>: Beacon‑chain epoch at which execution clients start to recognise the new fields <code>randomness</code> and <code>txOrderingVersion</code>.</li> <li><code>ORDERING_TRANSITION_EPOCHS</code> window activate the rule: 64 epochs (~13.6 h). Length of the transition window during which blocks with either ordering version are accepted.</li> </ul> <p>Both parameters are constants in the fork config and may be tuned during test‑net experiments.</p> <h4 id="activation-flow">Activation Flow</h4> <ol> <li> <p>Consensus‑layer upgrade — Beacon‑chain fork at <code>ORDERING_FORK_EPOCH</code> activates <strong><code>EL‑VRF‑exposure</code></strong> (companion EIP) and begins populating the <code>vrf_output_proposer</code> field. Execution clients receiving the <code>ExecutePayload</code> after this epoch expect a non‑zero <code>randomness</code> field.</p> </li> <li> <p>Execution‑layer handshake — Builders and proposers include the new <code>randomness</code> and <code>txOrderingVersion</code> fields in Engine API <code>engine_newPayloadV3</code> calls. Legacy nodes that have not upgraded will reject the payload, causing a natural chain split and economic incentive to upgrade.</p> </li> <li> <p>Transition window — For <code>ORDERING_TRANSITION_EPOCHS</code> after <code>ORDERING_FORK_EPOCH</code>, clients accept:</p> </li> </ol> <ul> <li> <p>Version 0 blocks — <code>txOrderingVersion</code> == 0; no randomness; legacy ordering.</p> </li> <li> <p>Version 1 blocks — <code>txOrderingVersion</code> == 1; valid randomness; canonical ordering enforced. During this period proposers are encouraged (but not forced) to adopt version 1 so that fee markets and MEV supply chains have time to adjust.</p> </li> </ul> <ol start="4"> <li>Finalisation — At <code>ORDERING_FORK_EPOCH</code> + <code>ORDERING_TRANSITION_EPOCHS</code> the consensus rule changes: blocks MUST set <code>txOrderingVersion == 1</code> and pass canonical‑order validation. A version‑0 block after this point is treated as invalid and will not be considered by fork‑choice.</li> </ol> <h2 id="rationale">Rationale</h2> <h3 id="why-randomness-driven-ordering">Why randomness‑driven ordering?</h3> <ul> <li> <p>Objective &amp; Verifiable – Using a function of on‑chain randomness (R) and a transaction’s own hash gives every validator an identical, cheap check on order validity.</p> </li> <li> <p>Unpredictable Until Slot Start – The XOR of slot‑level RANDAO and the proposer’s VRF output ensures that neither users nor builders can know the final sort key before the slot begins, closing the classic front‑run window.</p> </li> <li> <p>Minimal Surface Area – A single 16‑byte field in the execution payload plus a hash operation keeps consensus changes small and auditable.</p> </li> </ul> <h3 id="why-xor-as-the-mixing-function">Why XOR as the mixing function?</h3> <ul> <li> <p>XOR is associative, fast, and requires no extra cryptographic assumptions beyond SHA‑2 already used for H(tx).</p> </li> <li> <p>Any bias in one entropy component (e.g., RANDAO) is negated unless the attacker also controls the VRF output.</p> </li> </ul> <h3 id="why-allow-builders-to-curate-the-candidate-set-first">Why allow builders to curate the candidate set first?</h3> <ul> <li> <p>Preserves fee‑market incentives: high‑tip transactions still rise to the top of inclusion competition.</p> </li> <li> <p>Avoids forced inclusion of low‑value spam that could bloat blocks if the entire mempool were blindly sorted.</p> </li> </ul> <h3 id="why-a-secondary-key-h-tx-for-tie-breaking">Why a secondary key H(tx) for tie‑breaking?</h3> <ul> <li> <p>Guarantees total order with negligible extra cost.</p> </li> <li> <p>Leverages a value already known to every node; no extra field is needed.</p> </li> </ul> <h3 id="why-optional-bundles-instead-of-implicit-nonce-chain-folding">Why optional bundles instead of implicit nonce‑chain folding?</h3> <ul> <li> <p>Cross‑address atomicity (e.g., borrower + lender tx pair) cannot be expressed via nonce order alone.</p> </li> <li> <p>Requiring an explicit fee‑payment transaction embeds pricing for the externality a bundle imposes on ordering neutrality.</p> </li> </ul> <h3 id="why-the-fit-or-skip-bundle-rule">Why the "fit‑or‑skip" bundle rule?</h3> <ul> <li> <p>Ensures all clients compute the same gas impact, preventing divergent execution.</p> </li> <li> <p>Avoids partial bundle execution, which would undermine user intent.</p> </li> </ul> <h3 id="why-the-version-flag-transition-window">Why the version flag + transition window?</h3> <ul> <li> <p>Prevents accidental consensus splits by giving node operators a grace period.</p> </li> <li> <p>Mirrors previous successful hard forks (e.g., London’s BASE_FEE activation sequence).</p> </li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <ul> <li><strong>Old nodes</strong> — Execution clients that ignore the new fields will treat version‑1 blocks as malformed and fork away. The short transition window gives operators time to upgrade.</li> <li><strong>Light clients</strong> — No additional work; they track headers chosen by upgraded full nodes.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <h3 id="randomness-bias-randao-manipulation">Randomness Bias &amp; RANDAO Manipulation</h3> <ul> <li> <p><em>Single‑validator bias</em> – A block proposer can not change its <code>randao_reveal</code> output after EIP-7998, only predictable to him.</p> </li> <li> <p><em>Coalition bias</em> – Multiple consecutive‑slot proposers could attempt to influence RANDAO by withholding signatures, but the protocol already slashes equivocation and missed attestations. The cost rises exponentially with coalition size, and the added VRF entropy further randomizes <code>R</code>.</p> </li> <li> <p><em>Forkable bias</em> – Re‑org attempts longer than depth 1 must overcome the usual consensus finality thresholds. Because <code>R</code> is embedded in the execution payload, any fork conflicts are objectively detectable by all nodes.</p> </li> </ul> <p>Conclusion: Collusion attacks are economically unattractive; the mixed entropy from RANDAO and VRF provides strong unpredictability guarantees.</p> <h3 id="hash-grinding">Hash Grinding</h3> <p>New signatures are required only when <code>calldata</code> changes, but attacks must begin <strong>after</strong> block is built. Propagation delays and inclusion fees sharply limit profitable grinding to high‑value trades.</p> <h3 id="tie-collisions">Tie Collisions</h3> <p>Secondary key <code>H(tx)</code> guarantees total order; collision probability (<code>2^{-256}</code>) is negligible.</p> <h3 id="bundle-gas-consistency">Bundle Gas Consistency</h3> <p>Explicit summation rule ensures every client computes identical gas usage for bundles, preventing divergent validation.</p> <h3 id="residual-mev-vectors">Residual MEV Vectors</h3> <ul> <li> <p><em>Back‑running &amp; latency</em> – Persist.</p> </li> <li> <p><em>Builder discretion</em> – Builders may censor or selectively include transactions while forming the candidate set; exactly like the current status of Ethereum.</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> 2025-05-22T00:00:00+00:00 2026-02-11T14:48:25+00:00 Lauri Peltonenhttps://github.com/microbecode https://wg-eips.ritovision.com/7950/

Encode a chain ID and transaction hash into a unique string format

<h2 id="abstract">Abstract</h2> <p>This standard proposes a way to encode the combination of a chain ID and a transaction hash into one string.</p> <h2 id="motivation">Motivation</h2> <p>Looking up a transaction by its hash always requires the context of the chain - a transaction hash alone is not enough to identify the used chain. If the chain information is included in the string itself, finding the right chain for the transaction is easy.</p> <p>Such strings can then be used, for example, in a forwarder service that forwards to the correct blockchain explorer.</p> <p>The chain id is included in some object formats, such as the transaction object inside the blockchain itself, but that object has a lot of unneeded data for our purposes.</p> <h2 id="specification">Specification</h2> <p>The encoded string has three components:</p> <ul> <li>A chain ID, denoted as <code>chainId</code>. The used chain id MUST be based on <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> and the chain ID repository stated in that EIP.</li> <li>A transaction hash, denoted as <code>txHash</code>. The hash MUST include the <code>0x</code> prefix.</li> <li>A static string <code>tx</code>, acting as a type identifier.</li> </ul> <p>The syntax is: <code>chainId:txHash:tx</code>.</p> <p>An example for a transaction with hash <code>0xc55e2b90168af6972193c1f86fa4d7d7b31a29c156665d15b9cd48618b5177ef</code> that was issued on chain ID <code>1</code> is: <code>1:0xc55e2b90168af6972193c1f86fa4d7d7b31a29c156665d15b9cd48618b5177ef:tx</code>.</p> <p>All of the characters are case-insensitive.</p> <h2 id="rationale">Rationale</h2> <p>The chain ID is the most important detail when routing queries based on this standard and is therefore the first element in the string. The transaction hash is the second most important element.</p> <p>The suffix <code>tx</code> is used to differentiate from, for example, addresses. Without the <code>tx</code> it would remain unclear whether an encoded string refers to an address, a transaction hash or something else.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP does not introduce direct security risks. It is up to the external service providers (such as wallet developers and blockchain explorers) to decide how and if they want to incorporate this EIP.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-05-16T00:00:00+00:00 2026-02-11T14:48:25+00:00 Alex Tianhttps://github.com/dugubuyan Zhixiong Panhttps://github.com/nake13 Geoffreyhttps://github.com/stbrahmsgeoffrey@datadance.ai liyingxuanhttps://github.com/LiYingxuanliyingxuan@datadance.ai https://wg-eips.ritovision.com/7962/

Extends privacy to ERC-721 and ERC-20 tokens.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes two token interfaces: <strong>ERC-KeyHash721</strong> for non-fungible tokens (NFTs) and <strong>ERC-KeyHash20</strong> for fungible tokens (similar to <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>). Both of them utilize cryptographic key hashes (“keyHash”, or <code>keccak256(key)</code>) instead of Ethereum addresses to manage ownership. This enhances privacy by authorizing by the public key’s ECDSA signature (address derived from <code>keccak256(key[1:])</code>) and matching <code>keyHash = keccak256(key)</code>, without storing addresses on‑chain. Consequently, it empowers users to conduct transactions using any address they choose. By separating ownership from transaction initiation, these standards allow gas fees to be paid by third parties without relinquishing token control, making them suitable for batch transactions and gas sponsorship. Security is ensured by implementing robust ECDSA signature verification on key functions (<code>transfer</code>) to prevent message tampering.</p> <h2 id="motivation">Motivation</h2> <p>Traditional <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens bind ownership to Ethereum addresses, which are publicly visible and may be linked to identities, compromising privacy. The key hash-based ownership model allows owners to prove control without exposing addresses, ideal for anonymous collectibles, private transactions, or decentralized identity use cases. Additionally, separating ownership from gas fee payment enables third-party gas sponsorship, improving user experience in high-gas or batch transaction scenarios. This proposal aligns with the privacy principles of <a href="https://wg-eips.ritovision.com/5564/">ERC-5564</a> (Stealth Addresses) and extends them to token ownership.</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="overview">Overview</h3> <p>This proposal defines two token interfaces:</p> <ul> <li><code>IERCKeyHash721</code>: For non-fungible tokens (NFTs), each identified by a unique <code>tokenId</code>, with ownership managed via <code>keyHash</code> (<code>keccak256(key)</code>).</li> <li><code>IERCKeyHash20</code>: For fungible tokens, with balances associated with <code>keyHash</code>.</li> </ul> <p>Token operations (<code>transfer</code>) require the owner's key(an uncompressed secp256k1 public key) and an ECDSA signature produced by the private key corresponding to the key (i.e., the address derived from <code>keccak256(key[1:])</code> excluding the 0x04 prefix) to prove ownership, ensuring only legitimate owners can execute actions. Signatures follow <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> structured data hashing to prevent message tampering, with per-keyHash nonces and deadlines to prevent replay attacks.</p> <p>Implementers MAY optionally add administrative functions such as <code>mint</code> (create new tokens) and <code>destroy</code> (remove tokens) based on application requirements. These functions are not part of the core interface of this ERC; if provided, they SHOULD enforce strict access control, correct supply accounting, and preserve the key‑hash privacy model without exposing addresses.</p> <p>Notably, the approve function is intentionally omitted. The key is designed for one-time use and is revealed only during token transfer transactions. Once revealed, holdings are typically migrated to fresh keyHashes; implementations MAY disallow reuse of previously revealed keyHash. Since transactions can be submitted by any address, the signature must be generated by the address derived from the key. This binds authorization to the key while allowing any relayer address to submit and pay gas.</p> <h3 id="erc-keyhash721-non-fungible-token-interface">ERC-KeyHash721: Non-Fungible Token Interface</h3> <h4 id="interface">Interface</h4> <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"> IERCKeyHash721</span><span> {</span></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"> KeyHashTransfer721</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-storage z-type"> indexed</span><span class="z-variable"> fromKeyHash</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> toKeyHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> KeyHashBurn721</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-storage z-type"> indexed</span><span class="z-variable"> ownerKeyHash</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> View functions (aligned with ERC-721)</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> <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 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"> 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"> 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">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> State-changing functions</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"> tokenId</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> keyHash</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"> transfer</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"> toKeyHash</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> key</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-support"> uint256</span><span class="z-variable"> deadline</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"> destroy</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> key</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-support"> uint256</span><span class="z-variable"> deadline</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="function-descriptions">Function Descriptions</h4> <h5 id="transfer"><code>transfer</code></h5> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-support">uint256</span><span> tokenId</span><span>,</span><span class="z-support"> bytes32</span><span> toKeyHash</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> key</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> signature</span><span>,</span><span class="z-support"> uint256</span><span> deadline</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p><strong>Description</strong>: Transfers the specified token from the current owner's <code>keyHash</code> to <code>toKeyHash</code>. The caller provides the owner's key to prove ownership. The signature is verified using <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> structured data.<br /> <strong>Parameters</strong>:</p> <ul> <li><code>tokenId</code>: <code>uint256</code> - The token ID to transfer.</li> <li><code>toKeyHash</code>: <code>bytes32</code> - The new owner's key hash.</li> <li><code>key</code>: <code>bytes</code> - MUST be a 65-byte uncompressed secp256k1 public key with prefix 0x04.</li> <li><code>signature</code>: <code>bytes</code> - ECDSA signature produced by the private key corresponding to the key, verifying ownership and preventing malicious relay attacks.</li> <li><code>deadline</code>: <code>uint256</code> - Signature expiration timestamp (Unix seconds).<br /> <strong>Signature Message</strong>: <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> structured data:<br /> <code>solidity struct Transfer { uint256 tokenId; bytes32 toKeyHash; uint256 nonce; uint256 deadline; } </code><br /> <strong>Events</strong>: Emits <code>KeyHashTransfer721(tokenId, fromKeyHash, toKeyHash)</code>.<br /> <strong>Requirements</strong>:</li> <li>Token MUST exist (non-zero <code>fromKeyHash</code>).</li> <li><code>keccak256(key)</code> MUST equal the current <code>fromKeyHash</code>.</li> <li>Signature MUST be valid.</li> <li><code>block.timestamp</code> MUST be &lt;= <code>deadline</code>.</li> <li><code>toKeyHash</code> MUST NOT be zero.</li> <li>Updates ownership to <code>toKeyHash</code>.</li> </ul> <ul> <li><strong>Other Functions</strong>: <code>name</code>, <code>symbol</code>, <code>tokenURI</code>, and <code>totalSupply</code> align with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> . <code>ownerOf</code> returns <code>bytes32</code> (keyHash) instead of an address.<code>tokenURI</code> is part of the core interface and MAY return an empty string if metadata is not provided.</li> </ul> <h4 id="key-concepts">Key Concepts</h4> <ul> <li><strong>Key (<code>key</code>)</strong>: An uncompressed secp256k1 public key (65 bytes, starting with 0x04), used to prove ownership. Implementations MUST validate the key format:</li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">require</span><span>(</span><span>key</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 65</span><span class="z-keyword"> &amp;&amp;</span><span> key</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> 0x04</span><span>,</span><span class="z-string"> &quot;BAD_KEY_FMT&quot;</span><span>)</span><span>;</span></span></code></pre> <ul> <li><strong>Key Hash (<code>keyHash</code>)</strong>: A <code>bytes32</code> value representing <code>keccak256(key)</code>, identifying ownership without exposing addresses.</li> <li><strong>Token Existence</strong>: A token exists if its <code>keyHash</code> is non-zero.</li> <li><strong>Nonce</strong>: Nonces are tracked per keyHash and per contract. Each ERC-KeyHash contract maintains its ownmapping(bytes32 =&gt;uint256)keyNonces. Cross-contract replay is already prevented by the EIP-712 domain (verifyingContract, chainId). Signers MUST serialize operations for the same keyHashwithin the same contract.</li> </ul> <h3 id="erc-keyhash20-fungible-token-interface">ERC-KeyHash20: Fungible Token Interface</h3> <h4 id="interface-1">Interface</h4> <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"> IERCKeyHash20</span><span> {</span></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"> KeyHashTransfer20</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> fromKeyHash</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> toKeyHash</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-comment"> View functions (aligned with ERC-20)</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> <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"> 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 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"> 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"> balanceOf</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> keyHash</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-comment"> State-changing functions</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">bytes32</span><span class="z-variable"> keyHash</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 class="z-storage z-type"> function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> fromKeyHash</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> toKeyHash</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"> key</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-support"> uint256</span><span class="z-variable"> deadline</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> leftKeyHash</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="function-descriptions-1">Function Descriptions</h4> <h5 id="transfer-1"><code>transfer</code></h5> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-support">bytes32</span><span> fromKeyHash</span><span>,</span><span class="z-support"> bytes32</span><span> toKeyHash</span><span>,</span><span class="z-support"> uint256</span><span> amount</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> key</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> signature</span><span>,</span><span class="z-support"> uint256</span><span> deadline</span><span>,</span><span class="z-support"> bytes32</span><span> leftKeyHash</span><span>)</span></span></code></pre> <p><strong>Description</strong>: Transfers <code>amount</code> tokens from <code>fromKeyHash</code> to <code>toKeyHash</code>, with remaining balance assigned to <code>leftKeyHash</code> (controlled by the sender). The caller provides the owner's key to prove ownership. The signature is verified using <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> structured data. Mimics Bitcoin's UTXO model for partial transfers.<br /> <strong>Parameters</strong>:</p> <ul> <li><code>fromKeyHash</code>: <code>bytes32</code> - Token owner's key hash.</li> <li><code>toKeyHash</code>: <code>bytes32</code> - Recipient's key hash.</li> <li><code>amount</code>: <code>uint256</code> - Amount to transfer.</li> <li><code>key</code>: <code>bytes</code> - MUST be a 65-byte uncompressed secp256k1 public key with prefix 0x04.</li> <li><code>signature</code>: <code>bytes</code> - ECDSA signature.</li> <li><code>deadline</code>: <code>uint256</code> - Signature expiration timestamp.</li> <li><code>leftKeyHash</code>: <code>bytes32</code> - Key hash for remaining balance (<code>balance - amount</code>). MUST NOT equal <code>toKeyHash</code> or <code>fromKeyHash</code> (strict mode to enforce key rotation and unlinkability).<br /> <strong>Signature Message</strong>: <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> structured data:<br /> <code>solidity struct Transfer { bytes32 fromKeyHash; bytes32 toKeyHash; uint256 amount; uint256 nonce; uint256 deadline; bytes32 leftKeyHash; } </code><br /> <strong>Events</strong>: Emits <code>KeyHashTransfer20(fromKeyHash, toKeyHash, amount)</code>.<br /> <strong>Requirements</strong>:</li> <li><code>fromKeyHash</code> MUST have sufficient balance (<code>balanceOf[fromKeyHash] &gt;= amount</code>).</li> <li><code>keccak256(key)</code> MUST equal <code>fromKeyHash</code>.</li> <li>Signature MUST be valid.</li> <li><code>block.timestamp</code> MUST be &lt;= <code>deadline</code>.</li> <li><code>toKeyHash</code> and <code>leftKeyHash</code> MUST NOT be zero.</li> <li>Updates balances: <code>balanceOf[fromKeyHash] = 0</code>, <code>balanceOf[toKeyHash] += amount</code>, <code>balanceOf[leftKeyHash] += (original balance - amount)</code>.</li> </ul> <ul> <li><strong>Other Functions</strong>: <code>name</code>, <code>symbol</code>, <code>decimals</code>, and <code>totalSupply</code> align with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. <code>balanceOf</code> uses <code>bytes32</code> parameter.</li> </ul> <h3 id="signature-verification">Signature Verification</h3> <p>For <code>transfer</code>:</p> <ol> <li> <p>Verify <code>keccak256(key) == current keyHash</code>.</p> </li> <li> <p>Compute <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> message hash:</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 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> TYPE_HASH</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Struct-specific type hash</span></span> <span class="giallo-l"><span> params </span><span class="z-comment">//</span><span class="z-comment"> Struct fields (e.g., tokenId, toKeyHash, nonce, deadline)</span></span> <span class="giallo-l"><span> )</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>)</span><span>;</span></span></code></pre></li> <li> <p>Recover signer address using <code>ecrecover(digest, signature)</code>.</p> </li> <li> <p>REQUIRE signer == address(uint160(uint256(keccak256(key[1:])))), where key is a 65‑byte uncompressed secp256k1 public key (0x04 || X || Y) and key[1:] denotes the 64‑byte XY payload (prefix removed)</p> </li> <li> <p>On successful verification, increment _keyNonces[currentOwnerKeyHash] (i.e., _keyNonces[ownerKeyHash] for ERC‑KeyHash721 and _keyNonces[fromKeyHash] for ERC‑KeyHash20) to prevent replay.</p> </li> <li> <p>Verify <code>block.timestamp &lt;= deadline</code>.</p> </li> </ol> <h3 id="requirements">Requirements</h3> <ul> <li>Contracts MUST maintain mappings: <ul> <li>ERC-KeyHash721: <code>tokenId</code> to <code>keyHash</code>.</li> <li>ERC-KeyHash20: <code>keyHash</code> to balance.</li> </ul> </li> <li>MUST use per-keyHash nonces (<code>mapping(bytes32 =&gt; uint256) _keyNonces</code>) for replay protection.</li> <li>MUST implement <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> for signature hashing.</li> <li>MUST enforce <code>deadline</code> to limit signature validity.</li> <li>MUST verify signatures and hash keys in <code>transfer</code>.</li> <li>For ERC-KeyHash20, MUST enforce strict mode for <code>leftKeyHash</code> by requiring it to be different from both <code>toKeyHash</code> and <code>fromKeyHash</code>. This prevents change consolidation with the recipient or original account, promoting key rotation and unlinkability.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="advantages-of-key-hash">Advantages of Key Hash</h3> <ul> <li><strong>Privacy</strong>: <code>ownerOf</code> and <code>balanceOf</code> return <code>keyHash</code>, not addresses. Users can use unique key pairs per token or balance, reducing linkability.</li> <li><strong>Gas Fee Separation</strong>: Anyone can call <code>transfer</code> with a valid signature, paying gas fees, enabling batch transactions or gas sponsorship.</li> <li><strong>Flexibility</strong>: Aligns with <a href="https://wg-eips.ritovision.com/5564/">ERC-5564</a> stealth addresses, extending privacy to tokens.</li> </ul> <h3 id="transfer-design">Transfer Design</h3> <ul> <li>Open to any caller with valid signatures, ensuring only owners operate while allowing gas sponsorship.</li> <li><a href="https://wg-eips.ritovision.com/712/">EIP-712</a> signatures prevent message tampering by including all critical parameters.</li> <li>Per-keyHash nonces and deadlines prevent replay attacks.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is not compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> or <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> due to <code>bytes32</code> key hashes instead of addresses. Adapters can bridge to existing systems for privacy-focused use cases.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="erc-keyhash721-implementation">ERC-KeyHash721 Implementation</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 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 class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/cryptography/EIP712.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"> KeyHashERC721</span><span class="z-storage"> is</span><span class="z-entity z-name"> EIP712</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> ECDSA</span><span class="z-keyword"> for</span><span class="z-entity z-name"> bytes32</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>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> public</span><span> symbol</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"> bytes32</span><span>)</span><span class="z-storage z-type"> private</span><span> _tokenKeyHashes</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"> bool</span><span>)</span><span class="z-storage z-type"> private</span><span> _destroyedTokens</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 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"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> _keyNonces</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"> KeyHashTransfer721</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-storage z-type"> indexed</span><span class="z-variable"> fromKeyHash</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> toKeyHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> KeyHashBurn721</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-storage z-type"> indexed</span><span class="z-variable"> ownerKeyHash</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"> private</span><span class="z-storage z-type"> constant</span><span> TRANSFER_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;Transfer(uint256 tokenId,bytes32 toKeyHash,uint256 nonce,uint256 deadline)&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> DESTROY_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;Destroy(uint256 tokenId,uint256 nonce,uint256 deadline)&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"> constructor</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"> _name</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"> _symbol</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> EIP712</span><span>(</span><span>&quot;KeyHashERC721&quot;, &quot;1&quot;)</span></span> <span class="giallo-l"><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> }</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"> 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">bytes32</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_tokenKeyHashes</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span class="z-keyword"> &amp;&amp;</span><span class="z-keyword"> !</span><span>_destroyedTokens</span><span>[</span><span>tokenId</span><span>]</span><span>,</span><span class="z-string"> &quot;Token does not exist&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _tokenKeyHashes</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"> tokenURI</span><span>(</span><span class="z-support">uint256</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 class="z-keyword"> return</span><span class="z-string"> &quot;&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"> transfer</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"> bytes32</span><span class="z-variable"> toKeyHash</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"> key</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"> signature</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</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>toKeyHash </span><span class="z-keyword">!=</span><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-string"> &quot;Invalid recipient hash&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_tokenKeyHashes</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span class="z-keyword"> &amp;&amp;</span><span class="z-keyword"> !</span><span>_destroyedTokens</span><span>[</span><span>tokenId</span><span>]</span><span>,</span><span class="z-string"> &quot;Token does not exist&quot;</span><span>)</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>timestamp </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> deadline</span><span>,</span><span class="z-string"> &quot;Signature expired&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>key</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 65</span><span class="z-keyword"> &amp;&amp;</span><span> key</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> 0x04</span><span>,</span><span class="z-string"> &quot;BAD_KEY_FMT&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> currentKeyHash </span><span class="z-keyword">=</span><span> _tokenKeyHashes</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span>key</span><span>)</span><span class="z-keyword"> ==</span><span> currentKeyHash</span><span>,</span><span class="z-string"> &quot;BAD_KEYHASH&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> nonce </span><span class="z-keyword">=</span><span> _keyNonces</span><span>[</span><span>currentKeyHash</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> structHash </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> TRANSFER_TYPEHASH</span><span>,</span></span> <span class="giallo-l"><span> tokenId</span><span>,</span></span> <span class="giallo-l"><span> toKeyHash</span><span>,</span></span> <span class="giallo-l"><span> nonce</span><span>,</span></span> <span class="giallo-l"><span> deadline</span></span> <span class="giallo-l"><span> )</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"> _hashTypedDataV4</span><span>(</span><span>structHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> signer </span><span class="z-keyword">=</span><span> digest</span><span>.</span><span class="z-entity z-name">recover</span><span>(</span><span>signature</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> expectedAddress </span><span class="z-keyword">=</span><span class="z-entity z-name"> _addressFromUncompressedKey</span><span>(</span><span>key</span><span>)</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> expectedAddress</span><span>,</span><span class="z-string"> &quot;Invalid signature&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _keyNonces</span><span>[</span><span>currentKeyHash</span><span>]</span><span class="z-keyword"> =</span><span> nonce </span><span class="z-keyword">+</span><span class="z-constant"> 1</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 验签通过后再自增</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _tokenKeyHashes</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span> toKeyHash</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> KeyHashTransfer721</span><span>(</span><span>tokenId</span><span>,</span><span> currentKeyHash</span><span>,</span><span> toKeyHash</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-storage z-type"> function</span><span class="z-entity z-name"> getNonce</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> keyHash</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> _keyNonces</span><span>[</span><span>keyHash</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"> _addressFromUncompressedKey</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> key</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 class="z-comment"> //</span><span class="z-comment"> key: 65 bytes, [0] = 0x04, [1..32] = X, [33..64] = Y </span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>key</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 65</span><span class="z-keyword"> &amp;&amp;</span><span> key</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> 0x04</span><span>,</span><span class="z-string"> &quot;BAD_KEY_FMT&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> x</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> y</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> x </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>key</span><span>,</span><span class="z-constant"> 0x21</span><span>)</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> key[1..32] </span></span> <span class="giallo-l"><span> y </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>key</span><span>,</span><span class="z-constant"> 0x41</span><span>)</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> key[33..64] </span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> h </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>x</span><span>,</span><span> y</span><span>)</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 64-byte XY </span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> address</span><span>(</span><span class="z-support">uint160</span><span>(</span><span class="z-support">uint256</span><span>(</span><span>h</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="erc-keyhash20-implementation">ERC-KeyHash20 Implementation</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 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 class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/cryptography/EIP712.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"> KeyHashERC20</span><span class="z-storage"> is</span><span class="z-entity z-name"> EIP712</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> ECDSA</span><span class="z-keyword"> for</span><span class="z-entity z-name"> bytes32</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>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> public</span><span> symbol</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-storage z-type"> public</span><span> decimals</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"> uint256</span><span>)</span><span class="z-storage z-type"> public</span><span> balanceOf</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 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"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> _keyNonces</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"> KeyHashTransfer20</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> fromKeyHash</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> toKeyHash</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-support"> bytes32</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> TRANSFER_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;Transfer(bytes32 fromKeyHash,bytes32 toKeyHash,uint256 amount,uint256 nonce,uint256 deadline,bytes32 leftKeyHash)&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"> constructor</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"> _name</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"> _symbol</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> EIP712</span><span>(</span><span>&quot;KeyHashERC20&quot;, &quot;1&quot;)</span></span> <span class="giallo-l"><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> decimals </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> <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> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> fromKeyHash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> toKeyHash</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"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> key</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"> signature</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> leftKeyHash</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>balanceOf</span><span>[</span><span>fromKeyHash</span><span>]</span><span class="z-keyword"> &gt;</span><span class="z-keyword">=</span><span> amount</span><span>,</span><span class="z-string"> &quot;Insufficient balance&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>toKeyHash </span><span class="z-keyword">!=</span><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-string"> &quot;Invalid recipient hash&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>leftKeyHash </span><span class="z-keyword">!=</span><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-string"> &quot;Invalid leftKeyHash&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>leftKeyHash </span><span class="z-keyword">!=</span><span> toKeyHash</span><span>,</span><span class="z-string"> &quot;LEFT_EQ_TO&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>leftKeyHash </span><span class="z-keyword">!=</span><span> fromKeyHash</span><span>,</span><span class="z-string"> &quot;LEFT_EQ_FROM&quot;</span><span>)</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>timestamp </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> deadline</span><span>,</span><span class="z-string"> &quot;Signature expired&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>key</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 65</span><span class="z-keyword"> &amp;&amp;</span><span> key</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> 0x04</span><span>,</span><span class="z-string"> &quot;BAD_KEY_FMT&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span>key</span><span>)</span><span class="z-keyword"> ==</span><span> fromKeyHash</span><span>,</span><span class="z-string"> &quot;BAD_KEYHASH&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> nonce </span><span class="z-keyword">=</span><span> _keyNonces</span><span>[</span><span>fromKeyHash</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> structHash </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> TRANSFER_TYPEHASH</span><span>,</span></span> <span class="giallo-l"><span> fromKeyHash</span><span>,</span></span> <span class="giallo-l"><span> toKeyHash</span><span>,</span></span> <span class="giallo-l"><span> amount</span><span>,</span></span> <span class="giallo-l"><span> nonce</span><span>,</span></span> <span class="giallo-l"><span> deadline</span><span>,</span></span> <span class="giallo-l"><span> leftKeyHash</span></span> <span class="giallo-l"><span> )</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"> _hashTypedDataV4</span><span>(</span><span>structHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> signer </span><span class="z-keyword">=</span><span> digest</span><span>.</span><span class="z-entity z-name">recover</span><span>(</span><span>signature</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> expectedAddress </span><span class="z-keyword">=</span><span class="z-entity z-name"> _addressFromUncompressedKey</span><span>(</span><span>key</span><span>)</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> expectedAddress</span><span>,</span><span class="z-string"> &quot;Invalid signature&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _keyNonces</span><span>[</span><span>fromKeyHash</span><span>]</span><span class="z-keyword"> =</span><span> nonce </span><span class="z-keyword">+</span><span class="z-constant"> 1</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 验签通过后再自增</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> remaining </span><span class="z-keyword">=</span><span> balanceOf</span><span>[</span><span>fromKeyHash</span><span>]</span><span class="z-keyword"> -</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span> balanceOf</span><span>[</span><span>fromKeyHash</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span> balanceOf</span><span>[</span><span>toKeyHash</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span> balanceOf</span><span>[</span><span>leftKeyHash</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> remaining</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> KeyHashTransfer20</span><span>(</span><span>fromKeyHash</span><span>,</span><span> toKeyHash</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-storage z-type"> function</span><span class="z-entity z-name"> getNonce</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> keyHash</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> _keyNonces</span><span>[</span><span>keyHash</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"> _addressFromUncompressedKey</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> key</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 class="z-comment"> //</span><span class="z-comment"> key: 65 bytes, [0] = 0x04, [1..32] = X, [33..64] = Y </span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>key</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 65</span><span class="z-keyword"> &amp;&amp;</span><span> key</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> 0x04</span><span>,</span><span class="z-string"> &quot;BAD_KEY_FMT&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> x</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> y</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> x </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>key</span><span>,</span><span class="z-constant"> 0x21</span><span>)</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> key[1..32] </span></span> <span class="giallo-l"><span> y </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>key</span><span>,</span><span class="z-constant"> 0x41</span><span>)</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> key[33..64] </span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> h </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>x</span><span>,</span><span> y</span><span>)</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 64-byte XY </span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> address</span><span>(</span><span class="z-support">uint160</span><span>(</span><span class="z-support">uint256</span><span>(</span><span>h</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><h2 id="security-considerations">Security Considerations</h2> <ul> <li><strong>Replay Attacks</strong>: <ul> <li><strong>Mitigation</strong>: Per-keyHash nonces (<code>_keyNonces[keyHash]</code>) increment after each operation, invalidating old signatures.</li> <li><strong>Design</strong>: Similar to <a href="https://wg-eips.ritovision.com/2612/">EIP-2612</a> permit mechanism, ensuring owner-controlled nonce sequences.</li> </ul> </li> <li><strong>Message Tampering</strong>: <ul> <li><strong>Mitigation</strong>: <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> structured signatures include all critical parameters (<code>tokenId</code>, <code>toKeyHash</code>, <code>amount</code>, <code>leftKeyHash</code>, etc.), preventing relayer tampering. Signatures are function-specific (<code>TRANSFER_TYPEHASH</code>, <code>DESTROY_TYPEHASH</code>).</li> <li><strong>Audit</strong>: Contracts MUST be audited to ensure no parameter omissions or hash collisions.</li> </ul> </li> <li><strong>Signature Expiration</strong>: <ul> <li><strong>Mitigation</strong>: <code>deadline</code> parameter ensures signatures expire, reducing risks of leaked signatures.</li> </ul> </li> <li><strong>Privacy Limitations</strong>: <ul> <li><strong>Issue</strong>: Public keys (key) are revealed in calldata; the corresponding Ethereum addresses can be derived off‑chain from keccak256(key[1:]). Use fresh keys (toKeyHash / leftKeyHash) to reduce linkability.</li> <li><strong>Recommendation</strong>: Use new key pairs per token or balance to minimize linkability. Store <code>hashKey</code> securely, as it is sensitive.</li> </ul> </li> <li><strong>Key Management</strong>: <ul> <li><strong>Risk</strong>: Loss or compromise of the private key corresponding to <code>key</code> results in loss of control. Store private keys securely.</li> <li><strong>Recommendation</strong>: Use safe systems to save <code>key</code>.</li> </ul> </li> <li><strong>Gas Costs</strong>: <ul> <li><strong>Issue</strong>: Signature verification and <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> hashing increase gas costs.</li> <li><strong>Recommendation</strong>: Optimize implementations and consider gas sponsorship to offset costs.</li> </ul> </li> <li><strong>Signature Malleability</strong>: Implementations MUST reject malleable signatures (low‑S, v ∈ {27, 28}). OpenZeppelin’s ECDSA helpers enforce these checks by default.</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> 2025-05-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nicholas Rodrigues Lordellohttps://github.com/nlordell Richard Meissnerhttps://github.com/rmeissner Valentin Seehausenhttps://github.com/vseehausen https://wg-eips.ritovision.com/7955/

A permissionless method and parameters for deploying a CREATE2 factory across EVM chains to a deterministic address using EIP-7702.

<h2 id="abstract">Abstract</h2> <p>This ERC defines a permissionless and deterministic deployment mechanism across all EVM-compatible chains. It uses the <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> <code>Set Code for EOAs (0x4)</code> transaction type to deploy a universal CREATE2 factory contract to a fixed address (<code>0xC0DEb853af168215879d284cc8B4d0A645fA9b0E</code>) with known bytecode. The factory can then create any new contract to a deterministic address using the <a href="https://wg-eips.ritovision.com/1014/">EIP-1014</a> <code>CREATE2 (0xf5)</code> opcode. It does not require preinstalls, secret keys, or chain-specific infrastructure.</p> <h2 id="motivation">Motivation</h2> <p>Ensuring that contracts share the same address and code on multiple chains is a hard problem. It is typically done by having a known CREATE2 factory contract at a specific address that can further deterministically deploy new contracts using the <code>CREATE2 (0xf5)</code> opcode.</p> <p>However, there is a bootstrapping problem: how do you get a CREATE2 factory contract with a specific address and code?</p> <h3 id="existing-solutions">Existing Solutions</h3> <p>There are currently three main approaches to this problem:</p> <h4 id="1-nick-s-method">1. Nick's Method</h4> <p>Use Nick's method to randomly generate a signature for a transaction <strong>without</strong> <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> replay protection that deploys the CREATE2 factory. Nick's method ensures that there is no known private key for the account that deploys the CREATE2 factory, meaning that the resulting contract will have a deterministic address and code on all chains. This strategy is used by the <em>Deterministic Deployment Proxy</em> (deployed to <code>0x4e59b44847b379578588920ca78fbf26c0b4956c</code>, including on Ethereum Mainnet), one of the most widely used CREATE2 factory contracts.</p> <p><strong>Downsides</strong>:</p> <ul> <li>It does not work on chains that only accept EIP-155 replay-protected transactions.</li> <li>It is sensitive to changes in gas parameters on the target chain since the gas price and limit in the deployment transaction is sealed, and a new one cannot be signed without a private key.</li> <li>Reverts, such as those caused by alternative gas schedules, make the CREATE2 factory no longer deployable.</li> </ul> <h4 id="2-secret-private-key">2. Secret Private Key</h4> <p>Keep a carefully guarded secret key and use it to sign transactions to deploy CREATE2 factory contracts. The resulting contract will have a deterministic address and code on all chains where the transaction at a given nonce of the deployer account is a CREATE2 factory deployment, which can be verified post-deployment to ensure trustlessness. Additionally, this method does not have the same gas sensitivity downsides as Nick's method, as the private key can sign a creation transaction with appropriate gas parameters at the time of execution. This is the strategy used by the <em>Safe Singleton Factory</em> and <em>CreateX</em> (deployed to <code>0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7</code> and <code>0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed</code> respectively, including on Ethereum Mainnet).</p> <p><strong>Downsides</strong>:</p> <ul> <li>It is permissioned: the party that holds the secret key has the ultimate say on which chains will get the CREATE2 factory deployments.</li> <li>This requires carefully guarding a secret key; if it is exposed or lost, deployments are no longer guaranteed on new chains.</li> <li>If the transaction at the given nonce is not a successful CREATE2 factory deployment, then it is no longer possible to have a CREATE2 factory at the canonical address; this can happen by human error, for example.</li> </ul> <h4 id="3-preinstalls">3. Preinstalls</h4> <p>Have popular CREATE2 deployment factories deployed on new chains by default. This is, for example, what OP Stack and ZKsync do as part of their preinstalls, including the CREATE2 factory contracts mentioned above. This ensures that the CREATE2 factory contracts have known addresses and codes.</p> <p><strong>Downsides</strong>:</p> <ul> <li>It is not standardized nor adopted by all chains.</li> <li>It is permissioned as a chain can choose not to include a specific CREATE2 factory contract preinstalled.</li> <li>Attempts to standardize this with RIP-7740 have not been successful.</li> </ul> <h3 id="proposal-using-eip-7702-type-0x4-transactions">Proposal: Using EIP-7702 Type <code>0x4</code> Transactions</h3> <p>This ERC proposes a permissionless alternative fourth mechanism to the existing ones described above with none of their downsides. Additionally, it standardizes a set of deployment parameters for a <strong>universal</strong> CREATE2 factory deployment. This ensures a common CREATE2 factory for the community instead of multiple competing copies with slightly different codes at different addresses. This single CREATE2 factory copy can bootstrap additional deterministic deployment infrastructure (such as the comprehensive CreateX universal contract deployer).</p> <p><strong>Benefits</strong></p> <ul> <li>Universally applicable: It can be executed on any chain by any user and guarantees a reliable determination of smart contract deployments on any chain.</li> <li>Fault resistant: The method is secure against "out of gas" and other errors.</li> <li>Permissionless: The universal CREATE2 factory contract can be deployed by anyone.</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> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Parameter</th><th>Value</th></tr></thead><tbody> <tr><td><code>DEPLOYER_PRIVATE_KEY</code></td><td><code>0x942ba639ec667bdded6d727ad2e483648a34b584f916e6b826fdb7b512633731</code></td></tr> <tr><td><code>CREATE2_FACTORY_INIT_CODE</code></td><td><code>0x7c60203d3d3582360380843d373d34f5806019573d813d933efd5b3d52f33d52601d6003f3</code></td></tr> <tr><td><code>CREATE2_FACTORY_SALT</code></td><td><code>0x000000000000000000000000000000000000000000000000000000000001bec5</code></td></tr> </tbody></table> <h3 id="derived-parameters">Derived Parameters</h3> <table><thead><tr><th>Derived Parameter</th><th>Value</th></tr></thead><tbody> <tr><td><code>DEPLOYER_ADDRESS</code></td><td><code>0x962560A0333190D57009A0aAAB7Bfa088f58461C</code></td></tr> <tr><td><code>CREATE2_FACTORY_ADDRESS</code></td><td><code>0xC0DEb853af168215879d284cc8B4d0A645fA9b0E</code></td></tr> <tr><td><code>CREATE2_FACTORY_RUNTIME_CODE</code></td><td><code>0x60203d3d3582360380843d373d34f5806019573d813d933efd5b3d52f3</code></td></tr> <tr><td><code>CREATE2_FACTORY_CODE_HASH</code></td><td><code>0x2ad75e1e9642e6fce7d293d52fa5a8f62a79a2079abb7402256add02d6e8bc30</code></td></tr> </tbody></table> <h3 id="definitions">Definitions</h3> <ul> <li><strong>Deployer</strong>: The account corresponding to <code>DEPLOYER_PRIVATE_KEY</code> with address <code>DEPLOYER_ADDRESS</code>.</li> <li><strong>CREATE2 factory contract</strong>: A contract that deploys other contracts with <code>CREATE2 (0xf5)</code> opcode, allowing smart contracts to be deployed to deterministic addresses.</li> <li><strong>Bootstrap contract</strong>: The contract that the <em>deployer</em> delegates to in order to deploy the <em>CREATE2 factory contract</em>.</li> <li><strong>Bootstrapping code</strong>: The critical code in the <em>bootstrap contract</em> that performs the <code>CREATE2 (0xf5)</code> deployment of the <em>CREATE2 factory contract</em>.</li> </ul> <h3 id="bootstrap-contract">Bootstrap Contract</h3> <p>The <em>bootstrap contract</em> MUST execute the following or equivalent <em>bootstrapping code</em> as an EIP-7702 delegation target for the <em>deployer</em> account:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> initCode </span><span class="z-keyword">=</span><span> CREATE2_FACTORY_INIT_CODE</span><span>;</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span> salt </span><span class="z-keyword">=</span><span> CREATE2_FACTORY_SALT</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">assembly</span><span> (</span><span class="z-string">&quot;memory-safe&quot;</span><span>)</span><span> {</span></span> <span class="giallo-l"><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"> 32</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></code></pre> <p>The <em>bootstrap contract</em> MAY implement additional features such as:</p> <ul> <li>Abort early if either <em>CREATE2 factory contract</em> is already deployed or the <em>deployer</em> is not correctly delegated to. <ul> <li>This can help mitigate gas griefing from the front-running issue described below.</li> </ul> </li> <li>Additional verification that the deployment succeeded as expected.</li> <li>Emit events to facilitate tracking of either the <em>bootstrap contract</em> or <em>CREATE2 factory contract</em> deployments.</li> </ul> <h3 id="deployment-process">Deployment Process</h3> <ol> <li>Deploy a <em>bootstrap contract</em> described in the previous section.</li> <li>Sign an EIP-7702 authorization using the <code>DEPLOYER_PRIVATE_KEY</code> delegating to the <em>bootstrap contract</em>.</li> <li>Execute an EIP-7702 type <code>0x4</code> transaction with the authorization from step 2; the transaction MUST call <code>DEPLOYER_ADDRESS</code> (<strong>either</strong> directly or indirectly) which delegates to the <em>bootstrap contract</em> and MUST perform the <code>CREATE2 (0xf5)</code> of the <code>CREATE2_FACTORY_INIT_CODE</code> with <code>CREATE2_FACTORY_SALT</code> in the <em>bootstrapping code</em>.</li> </ol> <p>Assuming successful execution of the <em>bootstrapping code</em> without reverting in the context of the <em>deployer</em>, the <em>CREATE2 factory contract</em> will be deployed to <code>CREATE2_FACTORY_ADDRESS</code> with code <code>CREATE2_FACTORY_RUNTIME_CODE</code> and code hash <code>CREATE2_FACTORY_CODE_HASH</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="deployment-mechanism">Deployment Mechanism</h3> <p>The deployment mechanism was chosen such that it is uniquely parameterized by the <code>DEPLOYER_ADDRESS</code> (which itself is derived from the <code>DEPLOYER_PRIVATE_KEY</code> and is therefore deterministic), the <code>CREATE2_FACTORY_INIT_CODE</code> and the <code>CREATE2_FACTORY_SALT</code> which are both fixed and deterministic. Additionally, since the <code>DEPLOYER_ADDRESS</code> will deploy the CREATE2 factory contract with the <code>CREATE2 (0xf5)</code> opcode, this guarantees that the address and code of the contract are deterministic.</p> <p>The use of a publicly known private key enables this mechanism, as anyone can permissionlessly generate a delegation signature to <strong>any</strong> bootstrap contract that would cause the <code>DEPLOYER_ADDRESS</code> to execute the specified <code>CREATE2 (0xf5)</code> operation and deploy the factory contract to a completely deterministic address. Because of the use of <code>CREATE2 (0xf5)</code>, the CREATE2 factory will be deployed to <code>CREATE2_FACTORY_ADDRESS</code> if and only if it is deployed with <code>CREATE2_FACTORY_INIT_CODE</code>, thus guaranteeing a deployed code hash of <code>CREATE2_FACTORY_CODE_HASH</code>. Additionally, the semantics of <code>CREATE2 (0xf5)</code> make it so no transaction executed by <code>DEPLOYER_ADDRESS</code> can permanently block the deployment of the CREATE2 factory contract to <code>CREATE2_FACTORY_ADDRESS</code>.</p> <p>One issue with this method is that because the <code>DEPLOYER_PRIVATE_KEY</code> is public, anyone can sign alternative delegations or transactions and front-run a legitimate CREATE2 factory deployment. The front-running would increase the nonce of the <code>DEPLOYER_ADDRESS</code> account and render the EIP-7702 authorization in the legitimate CREATE2 factory deployment transaction invalid, causing the deployment to potentially fail. This is not considered to be a serious issue, however, as:</p> <ol> <li>Doing so does not prevent future deployments - meaning that an attacker can only delay the deployment of the CREATE2 factory with a sustained attack at a gas cost to the attacker, but not permanently prevent it from happening.</li> <li>The damage is limited to gas griefing for accounts that are legitimately trying to deploy the CREATE2 factory contract. Furthermore, the reference implementation was coded to minimize the gas griefing damage.</li> <li>In the case of a very persistent malicious actor, their attack can be circumvented by either making use of private transactions or working directly with block builders.</li> </ol> <p>Another known issue with this method is that a future network upgrade may introduce new mechanisms (such as a new opcode or transaction type) to permanently set an account's code. If this were to happen, and since the <code>DEPLOYER_PRIVATE_KEY</code> is publicly known, the <code>DEPLOYER_ADDRESS</code> account's code could be mistakenly or maliciously set to something that does not execute the necessary bootstrapping code, permanently preventing any future deployment of the CREATE2 factory contract. If this ERC were to gain sufficient adoption, this is not believed to be an issue as:</p> <ol> <li>The deployment on Ethereum Mainnet would already exist, and the <code>DEPLOYER_PRIVATE_KEY</code> would no longer have any value on Ethereum Mainnet.</li> <li>An RIP can be adopted to ensure that <code>CREATE2_FACTORY_ADDRESS</code> has code <code>CREATE2_FACTORY_RUNTIME_CODE</code>.</li> </ol> <h3 id="publicly-known-private-key-instead-of-nick-s-method">Publicly Known Private Key Instead of Nick's Method</h3> <p>Instead of using a publicly known <code>DEPLOYER_PRIVATE_KEY</code>, Nick's method can be used to generate a random EIP-7702 authorization signature. This would prevent the front-running and forward compatibility issues described above.</p> <p>However, in order for Nick's method to work, the EIP-7702 authorization message that is signed, defined as <code>keccak(MAGIC || rlp([chain_id, address, nonce]))</code>, must be constant. <code>MAGIC</code> is already a constant; <code>chain_id</code> can be trivially fixed to <code>0</code> to specify a chain-agnostic EIP-7702 authorization; <code>nonce</code> can also be trivially fixed to <code>0</code> because Nick's method ensures the authority has no known private key, meaning it cannot sign another message that would increment the nonce. However, fixing <code>address</code> is problematic. Doing so would require a contract with specific code to be deployed to the same address on all chains, which is the original bootstrapping problem the proposed permissionless CREATE2 factory aims to solve. Therefore, this creates a "chicken and egg problem", making it not a viable way to generate an EIP-7702 authorization signature.</p> <h3 id="use-of-create2-factory-contract">Use of CREATE2 Factory Contract</h3> <p>This mechanism allows the <code>DEPLOYER_ADDRESS</code> to do any <code>CREATE2 (0xf5)</code> deployment, so it would be possible to forgo the intermediary CREATE2 factory contract and use the deployer technique for all deployments. There are multiple downsides to this, however:</p> <ul> <li>All contract deployments are subject to the front-running issue described above, which could become an annoyance</li> <li>Concurrent deployments from the deployer are subject to race conditions since EIP-7702 authorizations increase the account nonce. This means that if two deployments are submitted to the mempool without knowing about each other, only the first one will actually succeed, because the EIP-7702 authorization in the second transaction is for an outdated nonce. This is not an issue when deployers are trying to deploy the same contract as proposed in this ERC since even if the second delegation and transaction fails, the contract would have been deployed as desired.</li> </ul> <h3 id="multiple-transaction-procedure">Multiple Transaction Procedure</h3> <p>Unfortunately, EIP-7702 type <code>0x4</code> transactions are restricted to <code>to</code> values that are not <code>null</code>, meaning that you cannot simultaneously deploy the <em>bootstrap contract</em> and delegate to it in a single transaction.</p> <h3 id="choice-of-deployer-private-key">Choice of Deployer Private Key</h3> <p>The <code>DEPLOYER_PRIVATE_KEY</code> was chosen as the private key at derivation path <code>m/44'/60'/0'/0/0</code> for the mnemonic <code>make code code code code code code code code code code coconut</code>.</p> <h3 id="choice-of-salt">Choice of Salt</h3> <p>The <code>CREATE2_FACTORY_SALT</code> was chosen as the <strong>first</strong> salt value starting from <code>0</code> such that the CREATE2 factory's <a href="https://wg-eips.ritovision.com/55/">ERC-55</a> checksum address starts with the case sensitive <code>0xC0DE...</code> prefix. A verifiable method for mining a vanity address for the CREATE2 factory contract was chosen in order to ensure that the ERC authors did not find a CREATE2 hash collision on the <code>CREATE2_FACTORY_ADDRESS</code> that they can exploit at some point in the future.</p> <h3 id="create2-factory-bytecode">CREATE2 Factory Bytecode</h3> <p>The CREATE2 factory has a similar interface to existing implementations. Namely, it accepts <code>salt || init_code</code> as input, which is a 32-byte <code>salt</code> value concatenated with the <code>init_code</code> of the contract to deploy. It will execute a <code>CREATE2</code> with the specified <code>salt</code> and <code>init_code</code>, deploying a contract with <code>init_code</code> to <code>keccak256(0xff || CREATE2_FACTORY_ADDRESS || salt || keccak256(init_code))[12:]</code>. This contract returns the address of the created contract padded to 32 bytes. This differs from some existing implementations, but was done to maintain consistency with the 32-byte word size on the EVM (same encoding as <code>ecrecover</code> precompile for example). A product of this is that the return data from CREATE2 factory is compatible with the Solidity ABI. In the case where the execution of <code>init_code</code> were to fail, any revert data is propagated to the caller.</p> <p>Throughout both the CREATE2 factory contract initialization and runtime code, <code>RETURNDATASIZE (0x3d)</code> is used to push <code>0</code> onto the stack instead of the dedicated <code>PUSH0 (0x5f)</code> opcode. This is done to increase compatibility with chains that support EIP-7702 but not <a href="https://wg-eips.ritovision.com/3855/">EIP-3855</a>, while remaining a 1-byte and 2-gas opcode.</p> <p>The <code>CREATE2_FACTORY_INIT_CODE</code> corresponds to the following assembly:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span># SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>### Constructor Code ###</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>0x0000: PUSH29 0x60203d3d3582360380843d373d34f5806019573d813d933efd5b3d52f3</span></span> <span class="giallo-l"><span> # Stack: [runcode] | Push the CREATE2 factory runtime code, left padded</span></span> <span class="giallo-l"><span> # with three 0 bytes</span></span> <span class="giallo-l"><span>0x001e: RETURNDATASIZE # Stack: [0; runcode] | Push the offset in memory to store the code</span></span> <span class="giallo-l"><span>0x001f: MSTORE # Stack: [] | The runtime code is now in `memory[3:32]`, because of</span></span> <span class="giallo-l"><span> # the 3 bytes of 0-padding</span></span> <span class="giallo-l"><span>0x0020: PUSH1 29 # Stack: [29] | Push the code length</span></span> <span class="giallo-l"><span>0x0022: PUSH1 3 # Stack: [3; 29] | Push the memory offset of the start of code</span></span> <span class="giallo-l"><span>0x0024: RETURN # Stack: [] | Return the runtime code</span></span></code></pre> <p>The <code>CREATE2_FACTORY_RUNTIME_CODE</code> corresponds to the following assembly:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span># SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>### Runtime Code ###</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Prepare the stack, push 32, a value that will used a lot and can summon with</span></span> <span class="giallo-l"><span># `DUP*` to save on one byte of code (over `PUSH1 32`), and a 0 which will be</span></span> <span class="giallo-l"><span># used by either the `RETURN` or `REVERT` branches at the end.</span></span> <span class="giallo-l"><span>0x0000: PUSH1 32 # Stack: [32]</span></span> <span class="giallo-l"><span>0x0002: RETURNDATASIZE # Stack: [0; 32]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># First, load the salt value and compute the actual code size for the CREATE2</span></span> <span class="giallo-l"><span># call, this is the calldata length minus 32 for the salt prefix.</span></span> <span class="giallo-l"><span> # Stack: [0; 32]</span></span> <span class="giallo-l"><span>0x0003: RETURNDATASIZE # Stack: [0; 0; 32] | Push the calldata offset 0 of the `salt` parameter</span></span> <span class="giallo-l"><span>0x0004: CALLDATALOAD # Stack: [salt; 0; 32] | Load the `salt` from calldata</span></span> <span class="giallo-l"><span>0x0005: DUP3 # Stack: [32; salt; 0; 32] | Push 32 to the stack</span></span> <span class="giallo-l"><span>0x0006: CALLDATASIZE # Stack: [msg.data.len; 32; salt; ...] | Followed by the calldata length</span></span> <span class="giallo-l"><span>0x0007: SUB # Stack: [code.len; salt; 0; 32] | Compute `msg.data.length - 32`, which is the length of</span></span> <span class="giallo-l"><span> # the init `code`</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Copy the init code to memory offset 0. Note that if the call to the contract</span></span> <span class="giallo-l"><span># incorrectly encoded, this will revert with &quot;out of gas&quot;, as it will attempt</span></span> <span class="giallo-l"><span># to copy ~2**256 bytes of calldata to memory.</span></span> <span class="giallo-l"><span> # Stack: [code.len; salt; 0; 32]</span></span> <span class="giallo-l"><span>0x0008: DUP1 # Stack: [code.len; .; salt; 0; 32] | Duplicate the length of the init code</span></span> <span class="giallo-l"><span>0x0009: DUP5 # Stack: [32; code.len; ...] | Push the offset in calldata of the code, which is 32</span></span> <span class="giallo-l"><span> # as it comes immediately after the 32-byte `salt`; use</span></span> <span class="giallo-l"><span> # the 32 value at the bottom of the stack</span></span> <span class="giallo-l"><span>0x000a: RETURNDATASIZE # Stack: [0; 32; code.len; ...] | Push the offset (0) in memory to copy the code to</span></span> <span class="giallo-l"><span>0x000b: CALLDATACOPY # Stack: [code.len; salt; 0; 32] | Copy the init code, `memory[0:code.len]` contains the</span></span> <span class="giallo-l"><span> # init `code`</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Deploy the contract.</span></span> <span class="giallo-l"><span> # Stack: [code.len; salt; 0; 32]</span></span> <span class="giallo-l"><span>0x000c: RETURNDATASIZE # Stack: [0; code.len; salt; 0; 32] | Push the offset in memory starting of the start of</span></span> <span class="giallo-l"><span> # init `code`, which is 0</span></span> <span class="giallo-l"><span>0x000d: CALLVALUE # Stack: [v; 0; code.len; salt; 0; 32] | Forward the call value to the contract constructor</span></span> <span class="giallo-l"><span>0x000e: CREATE2 # Stack: [address; 0; 32] | Do `create2(v, code, salt)`, which leaves the address</span></span> <span class="giallo-l"><span> # of the contract on the stack, or 0 if the contract</span></span> <span class="giallo-l"><span> # creation reverted</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Verify the deployment was successful and return the address.</span></span> <span class="giallo-l"><span> # Stack: [address; 0; 32]</span></span> <span class="giallo-l"><span>0x000f: DUP1 # Stack: [address; .; 0; 32] | Duplicate the address value</span></span> <span class="giallo-l"><span>0x0010: PUSH1 0x19 # Stack: [0x0019; address; .; 0; 32] | Push the jump destination offset for the code which</span></span> <span class="giallo-l"><span> # handles successful deployments</span></span> <span class="giallo-l"><span>0x0012: JUMPI # Stack: [address; 0; 32] | Jump if `address != 0`, i.e. `CREATE2` succeeded</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># CREATE2 reverted, propagate the revert data.</span></span> <span class="giallo-l"><span> # Stack: [address = 0; 0; 32]</span></span> <span class="giallo-l"><span>0x0013: RETURNDATASIZE # Stack: [r.len; 0; 0; 32] | Push the revert data length onto the stack</span></span> <span class="giallo-l"><span>0x0014: DUP2 # Stack: [0; r.len; 0; 0; 32] | Push 0 on to the stack by duplicating; note that</span></span> <span class="giallo-l"><span> # `PUSH0` is intentionally do not used for increased</span></span> <span class="giallo-l"><span> # compatibility with chains that do not implement that</span></span> <span class="giallo-l"><span> # specific opcode</span></span> <span class="giallo-l"><span>0x0015: RETURNDATASIZE # Stack: [r.len; 0; r.len; 0; 0; 32] | Push the revert data length onto the stack again</span></span> <span class="giallo-l"><span>0x0016: SWAP4 # Stack: [0; 0; r.len; 0; r.len; 32] | Reorder the stack so that both `RETURNDATACOPY` and</span></span> <span class="giallo-l"><span> # `REVERT` can be called; this is done by swapping the</span></span> <span class="giallo-l"><span> # revert data length on the top of the stack with the</span></span> <span class="giallo-l"><span> # bottom-most 0</span></span> <span class="giallo-l"><span>0x0017: RETURNDATACOPY # Stack: [0; r.len; 32] | Copy the revert data to `memory[0:r.len]`</span></span> <span class="giallo-l"><span>0x0018: REVERT # Stack: [32] | Revert with `memory[0:r.len]`</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># CREATE2 succeeded.</span></span> <span class="giallo-l"><span>0x0019: JUMPDEST # Stack: [address; 0; 32]</span></span> <span class="giallo-l"><span>0x001a: RETURNDATASIZE # Stack: [0; address; 0; 32] | Push the memory offset (0) to store return data at,</span></span> <span class="giallo-l"><span> # `RETURNDATASIZE` is used as contract creation was</span></span> <span class="giallo-l"><span> # successful, and therefore the return data has size 0</span></span> <span class="giallo-l"><span>0x001b: MSTORE # Stack: [0; 32] | Store the address in memory, `memory[0:32]` contains</span></span> <span class="giallo-l"><span> # the `address` left padded to 32-bytes</span></span> <span class="giallo-l"><span>0x001c: RETURN # Stack: [] | Return `memory[0:32]`, i.e. the address</span></span></code></pre><h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are a few backwards compatibility considerations with the new proposal:</p> <ol> <li>It requires an EVM chain with EIP-7702 enabled. This means not all chains can use this deployment method.</li> <li>It would deploy yet another CREATE2 factory contract that would need to be adopted by tooling.</li> <li>The proposed CREATE2 factory implementation returns the newly created contract address padded to 32 bytes. This is different to some existing contracts that return unpadded 20-byte address value.</li> <li>The proposed CREATE2 factory implementation propagates revert data. This is different to some existing contracts that just revert with empty data in case executing the CREATE2 initialization code fails.</li> </ol> <h2 id="reference-implementation">Reference Implementation</h2> <p>This proposal includes a reference implementation of a bootstrap contract to which the deployer account can delegate. The reference implementation expects a call to <code>Bootstrap</code> to the function <code>deploy()</code> in an EIP-7702 type <code>0x4</code> transaction including the EIP-7702 authorization delegating <code>DEPLOYER_ADDRESS</code> to <code>Bootstrap</code> (NOTE: the <code>Bootstrap</code> is called as an entry point, instead of calling <code>DEPLOYER_ADDRESS</code> directly which allows the contract to do some up-front checks to minimize gas griefing risk):</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.29</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"> Bootstrap</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> _DEPLOYER_ADDRESS </span><span class="z-keyword">=</span><span class="z-constant"> 0x962560A0333190D57009A0aAAB7Bfa088f58461C</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> _CREATE2_FACTORY_ADDRESS </span><span class="z-keyword">=</span><span class="z-constant"> 0xC0DEb853af168215879d284cc8B4d0A645fA9b0E</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> _CREATE2_FACTORY_CODE_HASH </span><span class="z-keyword">=</span><span> hex</span><span class="z-string">&quot;2ad75e1e9642e6fce7d293d52fa5a8f62a79a2079abb7402256add02d6e8bc30&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> _CREATE2_FACTORY_INIT_CODE </span><span class="z-keyword">=</span><span> hex</span><span class="z-string">&quot;7c60203d3d3582360380843d373d34f5806019573d813d933efd5b3d52f33d52601d6003f3&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> _CREATE2_FACTORY_SALT </span><span class="z-keyword">=</span><span> hex</span><span class="z-string">&quot;000000000000000000000000000000000000000000000000000000000001bec5&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> InvalidDelegation</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> CreationFailed</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"> deploy</span><span>(</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>_CREATE2_FACTORY_ADDRESS</span><span>.</span><span>codehash </span><span class="z-keyword">==</span><span> _CREATE2_FACTORY_CODE_HASH</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 class="giallo-l"><span class="z-support"> bytes32</span><span> delegation </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>hex</span><span class="z-string">&quot;ef0100&quot;</span><span>,</span><span class="z-variable z-language"> this</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_DEPLOYER_ADDRESS</span><span>.</span><span>codehash </span><span class="z-keyword">==</span><span> delegation</span><span>,</span><span class="z-entity z-name"> InvalidDelegation</span><span>(</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> Bootstrap</span><span>(</span><span>_DEPLOYER_ADDRESS</span><span>)</span><span>.</span><span class="z-entity z-name">bootstrap</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"> bootstrap</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> initCode </span><span class="z-keyword">=</span><span> _CREATE2_FACTORY_INIT_CODE</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> salt </span><span class="z-keyword">=</span><span> _CREATE2_FACTORY_SALT</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> address</span><span> factory</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> assembly</span><span> (</span><span class="z-string">&quot;memory-safe&quot;</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> factory </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"> 32</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 class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>factory </span><span class="z-keyword">==</span><span> _CREATE2_FACTORY_ADDRESS</span><span>,</span><span class="z-entity z-name"> CreationFailed</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>A minimal bootstrap contract implementation is also possible (although this has a higher potential for gas griefing). The minimal bootstrap contract expects a call directly to the <code>DEPLOYER_ADDRESS</code> in an EIP-7702 type <code>0x4</code> transaction including the EIP-7702 authorization delegating <code>DEPLOYER_ADDRESS</code> to <code>MiniBootstrap</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.29</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"> MiniBootstrap</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> _CREATE2_FACTORY_INIT_CODE </span><span class="z-keyword">=</span><span> hex</span><span class="z-string">&quot;7c60203d3d3582360380843d373d34f5806019573d813d933efd5b3d52f33d52601d6003f3&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> _CREATE2_FACTORY_SALT </span><span class="z-keyword">=</span><span> hex</span><span class="z-string">&quot;000000000000000000000000000000000000000000000000000000000001bec5&quot;</span><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> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> initCode </span><span class="z-keyword">=</span><span> _CREATE2_FACTORY_INIT_CODE</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> assembly</span><span> (</span><span class="z-string">&quot;memory-safe&quot;</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> pop</span><span>(</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"> 32</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>initCode</span><span>)</span><span>,</span><span> _CREATE2_FACTORY_SALT</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> <p>It is possible to front-run transactions that invalidate the deployer's EIP-7702 delegation and cause the deployment to fail. This, however, comes at a gas cost to the attacker, with limited benefit beyond delaying the deployment of the CREATE2 factory. Additionally, persistent attackers can be circumvented by either using private transaction queues or working with block builders directly to ensure that the EIP-7702 bootstrapping transaction is not front-run.</p> <h3 id="future-network-upgrades">Future Network Upgrades</h3> <p>If new EVM opcodes or transaction types are introduced in future network upgrades that allow an account to permanently set its code, then this method is no longer guaranteed to work. The deployer account can permanently change its code to a contract that does not have the required bootstrapping code. This can trivially be done by a malicious actor using the publicly known <code>DEPLOYER_PRIVATE_KEY</code> and would prevent any future deployments of CREATE2 factory.</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-05-10T00:00:00+00:00 2026-02-11T14:48:26+00:00 Moody Salemhttps://github.com/moodysalem Tina Zhenghttps://github.com/tinaszheng https://wg-eips.ritovision.com/7946/

Unidirectional app to wallet communication for private construction of transactions

<h2 id="abstract">Abstract</h2> <p>Universal Wallet Uplink (UWULink) is a protocol that allows applications (dApps) to request a wallet to make a batch of contract calls in a single atomic transaction without establishing a two-way connection or revealing the user's address to the requester. The protocol defines a compact binary message format using Protocol Buffers suitable for low-bandwidth channels such as QR codes or NFC tags. Two modes of operation are supported: <strong>Static Mode</strong>, where the request payload directly contains the list of calls, and <strong>Programmable Mode</strong>, where the payload references a contract that generates the list of calls.</p> <h2 id="motivation">Motivation</h2> <p>dApps often require users to perform multistep interactions, such as approving a token and then executing a swap. Traditionally, accomplishing this has required multiple user confirmations or complex wallet connectivity. Recent standards like <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> and <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> introduced ways to batch multiple calls into one atomic operation via JSON-RPC (e.g. <code>wallet_sendCalls</code>). However, current implementations of those solutions assume an active connection between dApp and wallet (e.g. injected provider or WalletConnect session), which creates an additional layer of UX friction. There is a growing need for a <strong>privacy-preserving, frictionless workflow</strong> where a dApp or product can trigger complex transactions without “connecting” their wallet or needing to disclosing their address to the application.</p> <p>Several trends highlight this need:</p> <ul> <li> <p><strong>Atomic Multi-Call Transactions:</strong> With the advent of account abstraction features like <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>, externally owned accounts (EOAs) can execute <strong>batch transactions</strong> a la smart contract wallets. Users expect to combine multiple actions (e.g. token approvals, swaps, transfers) into one confirmed transaction for better UX and guaranteed all-or-nothing execution. Developers likewise want to avoid partial failures or multiple prompts.</p> </li> <li> <p><strong>Privacy Concerns:</strong> Current wallet connection flows (<a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a> / <a href="https://wg-eips.ritovision.com/1102/">EIP-1102</a>) require dApps to request access to user accounts, linking the user's address with the dApp even before a transaction is made. By decoupling transaction construction from user identification, we improve privacy. The wallet should not need to announce “who” it is to the dApp just to receive a transaction request. A one-way communication means the dApp never learns the user's address or other account info, mitigating tracking and profiling risks.</p> </li> <li> <p><strong>One-Way Offline Interaction:</strong> In many use cases (desktop-to-mobile workflows, point-of-sale terminals, printed media), it’s desirable to communicate a transaction request via a QR code, NFC tag, or URL without establishing a session. Protocols like WalletConnect provide a session-based two-way link, but are heavyweight when a simple one-off action is needed, and they reveal the user's account to the dApp. A unidirectional link allows, for example, a user to scan a QR code on a webpage or poster and complete an on-chain action entirely within their wallet app. This also enables fully offline dApps to hand off transactions securely to user devices.</p> </li> <li> <p><strong>Compactness for QR/NFC:</strong> Encoding transaction data for use in QR codes or NFC imposes strict size limits. Prior standards (e.g. <a href="https://wg-eips.ritovision.com/681/">EIP-681</a> Ethereum URIs) used human-readable formats that become lengthy when including contract data (hex-encoded addresses and calldata inflate the size). WalletConnect addressed some issues by introducing a more efficient URI scheme (<a href="https://wg-eips.ritovision.com/1328/">ERC-1328</a>) instead of embedding JSON in QR codes. UWULink builds on this principle by using a concise binary serialization (Protocol Buffers), allowing more data to be communicated in a QR code or NFC tap.</p> </li> <li> <p><strong>Programmability and Offloading Logic:</strong> There are scenarios where the exact list of calls depends on on-chain state or user-specific data (for example, an airdrop claim that needs to gather all tokens claimable by that user, or a DeFi interaction where allowances may already exist). In such cases, encoding all call data statically could be unwieldy or inefficient if the dApp lacks knowledge of the user's address. UWULink’s <strong>Programmable Mode</strong> allows a dApp to redirect to a deterministic on-chain generator (a smart contract with a standard interface) that can produce the list of calls that the wallet should invoke. This allows the app to invoke arbitrary logic in generating the list of calls based on the state of the blockchain, still without exposing the user's address.</p> </li> </ul> <p>By addressing these points, UWULink aims to enhance user experience with one-shot multi-call transactions and improve security and privacy by eliminating unnecessary data sharing.</p> <h2 id="specification">Specification</h2> <h3 id="overview">Overview</h3> <p><strong>UWULink</strong> defines a protobuf message format and interpretation for transaction requests sent from a dApp to a wallet. The only operation in scope is a request for the wallet to execute an <strong>atomic batch of contract calls</strong> on an EVM-compatible blockchain. The wallet, upon receiving a UWULink request (for example, via a QR code scan, deep link, or NFC), will decode it, present the details to the user for confirmation, and if approved, execute the calls as a single transaction on the specified chain.</p> <p>Key characteristics of the protocol:</p> <ul> <li> <p><strong>Unidirectional Communication:</strong> Communication is <strong>only dApp → wallet</strong>. The dApp encodes a request and the wallet handles it. There is no handshake or return channel in the protocol itself. The wallet is not required (or able) to send any data back to the dApp. This one-way design ensures the dApp does not learn any information about the user or wallet (such as the address or which wallet app is used) at request time. It also simplifies implementation – the dApp’s job is simply to generate a batch of calls and display it, and the wallet’s job is to execute or reject the batch.</p> </li> <li> <p><strong>Atomic Batch Calls:</strong> All calls listed in the request <strong>MUST</strong> be executed atomically, i.e. all succeed or all fail together. If any specific call would revert, the wallet should revert the entire batch.</p> </li> <li> <p><strong>No Identity / Auth Required:</strong> Because the request is self-contained, the wallet does not need to pre-authorize the dApp or reveal the selected account. In traditional injected scenarios, a dApp would call <code>eth_requestAccounts</code> (as per <a href="https://wg-eips.ritovision.com/1102/">EIP-1102</a>) to get the user's address. With UWULink, the first and only interaction is the user willingly importing the transaction request (e.g. scanning the QR). The wallet should treat it similarly to how it would treat a transaction payload from a connected dApp, except no connection context exists. If the request is malformed or not supported, the wallet can simply alert the user and refuse.</p> </li> <li> <p><strong>Binary Encoding:</strong> UWULink messages are encoded as a binary blob based on a Protocol Buffers schema. This blob is then further encoded into a URI for transport via QR code or NFC tag. The string encoding of a request is the <code>uwulink:</code> scheme followed by the base 64 encoded message:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>uwulink:&lt;base64_of_UWULink_message&gt;</span></span></code></pre></li> <li> <p><strong>Chain Identification:</strong> The message includes a chain ID to indicate which chain the calls are intended for. The wallet must verify or use this chain ID when executing the transaction. If the wallet is not currently on the target chain, it SHOULD prompt the user to switch to that chain or automatically switch if permissible (similar to handling of <code>chainId</code> in <a href="https://wg-eips.ritovision.com/681/">EIP-681</a> URIs). If the wallet cannot operate on the requested chain, it must reject the request. This ensures that the dApp’s intent (which chain’s contracts to interact with) is preserved and avoids confusion if the user is on a different network.</p> </li> <li> <p><strong>Static vs Programmable Mode:</strong> There are two mutually exclusive ways to specify the batch of calls:</p> <ol> <li><strong>Static Mode:</strong> The request directly contains the list of calls (each with target address, calldata, and optionally ETH value) that the wallet should execute in order. This mode is straightforward and similar to existing multi-call APIs (e.g. the JSON-RPC <code>wallet_sendCalls</code> payload from <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a>), but encoded in a compact binary form. This is ideal when the dApp knows exactly what actions need to be performed.</li> <li><strong>Programmable Mode:</strong> The request contains a reference to an <strong>on-chain “resolver” contract</strong> and an input data blob. The wallet will call a predefined view function on that contract (off-chain, via <code>eth_call</code>) to <strong>retrieve the actual list of calls</strong> to execute. The resolver contract must implement a standardized interface (detailed below) that takes the provided input (and possibly the caller’s address or other context) and returns a set of calls. This mode allows dynamic computation of call lists at execution time. It improves flexibility (the dApp can offload complex logic or personalization to the blockchain) and keeps the QR/NFC payload small since it only carries a contract address and input, rather than every call’s details. For example, a dApp could include just a reference like “resolver contract X with input Y” and that contract’s resolver function will output perhaps dozens of calls based on the latest on-chain state, the user's address, etc.</li> </ol> </li> </ul> <p>The UWULink message includes a oneof/union to indicate which mode is used. Wallets <strong>SHOULD</strong> support both modes.</p> <h3 id="protobuf-schema">Protobuf Schema</h3> <p>Below is the proposed Protocol Buffers v3<!-- TODO: add a link to a specific git commit after eipw is updated --> schema defining the UWULink message format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>syntax = &quot;proto3&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>package org.ethereum.uwulink;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// The top-level UWULink transaction request message.</span></span> <span class="giallo-l"><span>message UWULinkRequest {</span></span> <span class="giallo-l"><span> uint64 chain_id = 1; // EIP-155 chain ID for the target chain</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> oneof request_type {</span></span> <span class="giallo-l"><span> Batch batch = 2;</span></span> <span class="giallo-l"><span> ResolverReference resolver = 3;</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>// Static batch of calls</span></span> <span class="giallo-l"><span>message Batch {</span></span> <span class="giallo-l"><span> repeated Call calls = 1;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// Single contract call</span></span> <span class="giallo-l"><span>message Call {</span></span> <span class="giallo-l"><span> bytes to = 1; // 20-byte address of target contract</span></span> <span class="giallo-l"><span> optional bytes value = 2; // (optional) up to 32-byte big-endian ETH value</span></span> <span class="giallo-l"><span> optional bytes data = 3; // (optional) calldata for the call</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// Reference to a resolver contract for dynamic call generation</span></span> <span class="giallo-l"><span>message ResolverReference {</span></span> <span class="giallo-l"><span> bytes resolver_address = 1; // 20-byte address of resolver contract</span></span> <span class="giallo-l"><span> bytes resolver_data = 2; // opaque data to pass to resolver</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>Notes on the schema:</strong></p> <ul> <li> <p>We use <code>bytes</code> for addresses and other binary data. A conforming wallet implementation MUST enforce that <code>Call.to</code> and <code>ResolverReference.resolver_address</code> are exactly 20 bytes. The protobuf itself won't enforce length, but using a different length should cause the wallet to reject the message (to avoid ambiguity or mis-interpretation). The <code>value</code> field in <code>Call</code> can be 0 bytes (interpreted as 0 ETH) up to 32 bytes. Leading zeros in <code>value</code> SHOULD be stripped in the encoding for consistency (e.g., 1 wei would be encoded as <code>0x01</code> not 32 bytes padded; conversely the decoder should treat a missing <code>value</code> or empty <code>value</code> as 0).</p> </li> <li> <p>All fields are numbered for efficient encoding. The oneof <code>request_type</code> ensures only one of Batch or ResolverReference is in use. If an unknown field is present (e.g., a future extension), the wallet should ignore those unknown fields per protobuf default behavior, but core fields must be present for validity (chain_id and one of batch/resolver).</p> </li> <li> <p>If using a text encoding (like Base64) to embed in a URI, the entire <code>UWULinkRequest</code> message is serialized to a binary string, then that binary is base64-encoded. For URI safety, base64 output may need to be URL-encoded (i.e., <code>+</code>, <code>/</code> characters percent-encoded or using the URL-safe base64 variant). This is an implementation detail, but wallet developers should be aware when parsing input. In all cases, the underlying data after decoding is expected to match the protobuf schema above.</p> </li> <li> <p>The schema is chosen for broad compatibility. Proto3's varint encoding will handle the <code>chain_id</code> (which is usually small like 1, 137, etc.) in 1-2 bytes. The <code>calls</code> repeated field will simply concatenate call entries. Each call entry will have a 1-byte field tag for <code>to</code> followed by 20 bytes address, etc. This results in a very compact representation.</p> </li> <li> <p>Example of an encoded message (for illustration): A static request for chain 1 with two calls might look like:</p> <ul> <li>Call 1: to = <code>0x111111...1111</code>, value = none (0), data = <code>0xabcdef</code></li> <li>Call 2: to = <code>0x222222...2222</code>, value = 100 wei, data = (empty)</li> <li>After encoding in protobuf and base64, the URI could be: <code>ethereum:uwulink?request=EiABAggDEhARERERERERERERERERERERERERERIAGKDCr+8=</code> (this is a fake example string for concept; actual encoding would differ).</li> <li>The wallet would decode that back to the structured fields.</li> </ul> </li> </ul> <p>Wallet and dApp developers can import this <code>.proto</code> to ensure they are constructing and parsing UWULink messages consistently.</p> <h3 id="resolver-contract-interface-programmable-mode">Resolver Contract Interface (Programmable Mode)</h3> <p>This standard introduces an interface that resolver contracts must implement so that wallets can query them for call batches. All resolver contracts <strong>MUST</strong> implement the following ABI (interface identifier <code>UWUResolver</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"> @title</span><span class="z-comment"> UWULink Resolver Interface</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> UWUResolver</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Call</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> target</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-comment"> //</span><span class="z-comment"> Thrown when calls could not be generated, with an error code specific to this resolver.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> CallGenerationFailure</span><span>(</span><span class="z-support">uint256</span><span> errorCode</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"> Compute a batch of calls for a given request.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> requester</span><span class="z-comment"> The address of the wallet (EOA or contract) that is requesting the calls.</span></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"> Arbitrary request data (opaque to the wallet, provided by dApp via UWULink).</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"> calls</span><span class="z-comment"> The list of calls that correspond to the requester and request</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"> getCalls</span><span>(</span><span class="z-support">address</span><span class="z-variable"> requester</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-keyword"> returns</span><span> (</span><span class="z-storage z-type">Call</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> calls</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 the details for the given error code. Meant to be called by developers to better understand the error code for a resolver.</span></span> <span class="giallo-l"><span class="z-comment"> * Due to localization needs, it is expected that developers may call this function, but the wallet should not show this information to users.</span></span> <span 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"> getErrorCodeDetails</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> errorCode</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 class="z-variable"> information</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li>The function <strong>MAY</strong> modify state. Wallets <strong>SHOULD</strong> call it off-chain, and avoid combining the call with others e.g. via Multicall.</li> <li>The <code>requester</code> is included to allow the contract to tailor results to the specific user. For example, a resolver could check <code>requester</code>’s token holdings or permissions and then return different call sets. The wallet should supply its own sending address as <code>requester</code>. This means that the user’s address is revealed <em>only to the RPC server</em> used by the wallet via this call, not to the dApp server or UI. In the future with the propagation of light clients, it's possible for the wallet to avoid revealing this information.</li> <li>The <code>data</code> parameter is the exact bytes provided in the UWULink request’s <code>resolver_data</code>. Its contents and encoding are defined by the dApp’s usage and the contract’s logic. For instance, it might contain an enum indicating which action to perform, or some user-specific claim ID, etc.</li> <li>The size of the returned arrays is not explicitly limited by this standard, but practical use should keep it reasonable (dozens rather than thousands of calls) both for blockchain computation reasons and for the user’s ability to comprehend the request.</li> </ul> <p>Wallets should implement the following logic for programmable requests:</p> <ol> <li>Perform an <code>eth_call</code> to <code>resolver_address</code> with <code>to = resolver_address</code>, <code>from = address(0)</code>, <code>data = ABIEncodeWithSelector(UWUResolver.getCalls, userAddress, resolver_data)</code> against the latest block. The wallet <strong>MAY</strong> use the pending block, or otherwise include transactions in the state that are yet to be included in a confirmed block.</li> <li>If the call returns successfully, decode the result. This becomes the batch of calls to execute. The wallet should then proceed exactly as if it were a static mode request containing those calls. It should display these calls to the user for confirmation (including target addresses, values, and perhaps decoded method signatures if it can).</li> <li>If the call fails (reverts or is not implemented), the wallet <strong>MUST</strong> abort. It SHOULD surface an error to the user like "Transaction request generation failed: resolver contract call was unsuccessful." The user then knows the dApp’s request was bad or the contract might be wrong.</li> </ol> <p>The dApp developer and resolver contract developer are responsible for ensuring that calling <code>getCalls</code> is not too gas-intensive to execute (since wallets will execute it off-chain but it still must complete execution). Excessive computation could result in the node returning an error (out of gas exception in the eth_call context). Typically these functions will just gather data from known contracts or encode some predefined calls, which should not be prohibitively expensive.</p> <h3 id="example-usage">Example Usage</h3> <p>To illustrate how UWULink can be used in practice, consider the following scenarios:</p> <p><strong>1. Static Mode – Token Approval and Swap (DeFi use-case):</strong></p> <p>Alice wants to trade tokens on a decentralized exchange (DEX) using her mobile wallet, but she doesn't want to connect her wallet to the DEX website due to privacy concerns. The DEX dApp prepares a UWULink QR code for the trade. When Alice selects the tokens and amount on the website, the dApp formulates two contract calls: one to the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token contract to <code>approve()</code> the DEX's router contract, and one to the router contract to execute the swap ( <code>swapExactTokensForTokens</code>, for example). Normally this would be two separate transactions with two confirmations. Instead, the dApp bundles them:</p> <ul> <li>Call #1: <code>to = TokenContract, data = approve(router, amount)</code></li> <li>Call #2: <code>to = RouterContract, data = swapExactTokensForTokens(params...)</code></li> </ul> <p>Both calls have <code>value = 0</code> (no ETH being sent directly). The dApp encodes these into a UWULinkRequest (static mode) for the current chain (e.g. Ethereum mainnet chain_id 1). The protobuf binary is base64 encoded and placed into a QR code with a URI like:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>uwulink:CgEBEiAx... (truncated)</span></span></code></pre> <p>Alice scans this QR with her wallet app. The wallet decodes the request: chain_id=1, two calls in batch. It recognizes it can execute an atomic batch (Alice’s wallet supports <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>). The wallet UI shows Alice a summary: "This dApp is requesting two actions: (1) Approve Token XYZ for spending, (2) Swap Token XYZ for Token ABC on DEX." Alice can inspect the contract addresses (perhaps the wallet resolves known token/contract names or shows the hex addresses) and the parameters. She sees that both will be submitted together in one transaction. The UI might look similar to a multi-call confirmation screen.</p> <p>Alice accepts. Her wallet internally either crafts a 0x4 type transaction (since Alice is an EOA on Ethereum) embedding bytecode to do the two calls, or uses its smart wallet module. It then signs and broadcasts the transaction. On-chain, the two calls execute one after the other, and because of atomicity, if the swap were to fail, the approve would be reverted too (avoiding a scenario where she approved tokens without actually swapping).</p> <p>The DEX backend or frontend can monitor the blockchain for the transaction receipt (it knows what actions it expected, or Alice can manually input the tx hash if needed). The important part is the DEX never learned Alice’s address beforehand; it only sees it when the transaction hits the blockchain, which is unavoidable for executing the trade but at that point privacy is preserved as well as any normal on-chain interaction (the dApp cannot link it to Alice’s web session unless Alice herself tells it out-of-band). This shows how UWULink achieves one-scan confirmation for what used to be multi-step, and keeps Alice’s identity private until the on-chain execution.</p> <p><strong>2. Programmable Mode – Personalized Airdrop Claim:</strong></p> <p>A project is running an airdrop where eligible users can claim several different token rewards based on on-chain activity. Bob visits the airdrop dApp page. The page could ask Bob to connect his wallet to figure out what he’s eligible for, but Bob is cautious. Instead, the dApp uses UWULink in programmable mode. It has a resolver contract deployed on-chain which, given a user address, can determine all the reward token contracts and amounts that the user is entitled to claim.</p> <p>The dApp shows Bob a “Claim Rewards” button, which reveals a QR code. This QR encodes a UWULink request with:</p> <ul> <li><code>chain_id = 5</code> (Goerli testnet, for example, where the airdrop is happening).</li> <li><code>resolver_address = 0xDeeD…1234</code> (the address of the AirdropResolver contract).</li> <li><code>resolver_data =</code> some bytes encoding maybe an airdrop campaign identifier or simply empty if one global campaign.</li> </ul> <p>Bob scans this with his wallet. The wallet sees it's a resolver-type request. It calls <code>getBatchCalls(BobAddress, resolver_data)</code> on <code>0xDeeD...1234</code> (as a view call). The AirdropResolver contract looks up internally that BobAddress is eligible for 3 tokens: TokenA, TokenB, and TokenC with certain amounts, and the claim function for each is <code>claim(address claimant, uint256 amount)</code> on each token’s distributor contract. It returns three arrays: targets = <code>[AddrA, AddrB, AddrC]</code>, values = <code>[0,0,0]</code> (no ETH needed), callData = <code>[ abi.encodeWithSelector(Distributor.claim, Bob, amtA), ... ]</code> for each token.</p> <p>The wallet receives these arrays. It now has three calls to execute. It shows Bob: "Claim TokenA: amount X, Claim TokenB: amount Y, Claim TokenC: amount Z" (assuming the wallet can decode the function signatures or at least show contract addresses and method names if it has ABIs). Bob approves the batch. The wallet then either directly calls each distributor’s <code>claim</code> in one aggregated transaction. Because Bob’s address was provided to the resolver, each claim call will credit tokens to Bob (likely the contract uses the provided address or <code>msg.sender</code> – here it was likely coded to use the address parameter, since the actual transaction sender will be Bob’s own address in the batch execution context). The important part is Bob did not have to connect his wallet to the dApp; the eligibility and calls were determined by the on-chain contract. The dApp never saw Bob’s address, yet Bob gets his tokens in one go.</p> <p>After execution, Bob’s wallet shows the transaction success. The dApp might simply tell him to check his balances (or it could have a public page showing which addresses claimed, etc., but it did not get a direct notification — it relies on Bob or the blockchain to know the claim happened).</p> <p><strong>3. Cross-Device Payment via NFC (Point of Sale):</strong></p> <p>Carol is at a merchant's point-of-sale device that accepts cryptocurrency payments via Ethereum. The merchant’s device can display a QR or emit an NFC message with a payment request. Instead of using a simple one-address payment URI (as in <a href="https://wg-eips.ritovision.com/681/">EIP-681</a>), the merchant uses UWULink to request a more sophisticated transaction: perhaps Carol will pay through a specific escrow contract or with a certain token if she has a discount coupon.</p> <p>The device sends an <strong>NFC payload</strong> which Carol’s phone picks up (many wallet apps can register as handlers for certain NDEF messages or custom URI schemes). The payload contains a UWULinkRequest in static mode:</p> <ul> <li>chain_id = 137 (Polygon, where the merchant operates).</li> <li>Two calls: first call to a stablecoin contract’s <code>transfer(merchantAddress, amount)</code> (to pay the merchant), second call to a logging contract <code>registerPurchase(merchantId, CarolAddress, amount)</code> (to log the sale in an on-chain registry). Both calls are value 0 since a token transfer, not ETH, is used.</li> </ul> <p>Carol’s wallet opens with the decoded request: It shows "Pay 50 USDC to Merchant XYZ and register purchase." Carol sees the merchant name resolved from the merchant’s address (if her wallet has ENS or a local registry of known merchants). She approves. The wallet then executes an atomic transaction on Polygon that calls the USDC token contract and the registry contract. The merchant’s PoS waits for confirmation on-chain (or simply trust the signed transaction once broadcast, depending on their risk tolerance). Carol’s identity remained pseudonymous; the merchant’s device did not directly get her wallet info, it only received the on-chain payment. And Carol only had to tap once to approve both token transfer and logging, rather than scan one QR to pay then perhaps another to log, etc.</p> <p>These examples demonstrate the flexibility of UWULink:</p> <ul> <li>In all cases, the user did not pre-connect their wallet to the application.</li> <li>The requests can be transferred via out-of-band channels (QR/NFC/URL).</li> <li>Multi-step operations become “one-click” (or one-scan) operations for the user.</li> <li>The on-chain outcome is the same as if the user had manually sent those transactions, but with improved UX and privacy.</li> </ul> <h2 id="rationale">Rationale</h2> <p>TBD <!-- TODO --></p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>UWULink is an additive protocol and does not break any existing standards. It is designed to coexist with current methods:</p> <ul> <li> <p><strong>Existing Wallet URIs (<a href="https://wg-eips.ritovision.com/681/">EIP-681</a>, <a href="https://wg-eips.ritovision.com/831/">EIP-831</a>):</strong> UWULink can be seen as an evolution of the idea behind EIP-681 ( transaction request URIs). EIP-681 defines URIs for a single transaction (or payment) and is already supported in a limited number of wallets for QR code scanning. UWULink extends the concept to multiple calls and binary encoding. A wallet that does not recognize the <code>uwulink:</code> scheme should simply not act on it. Typically, such a wallet would either show an error or ignore a scanned QR it cannot parse. This is a graceful failure from the user's perspective (they'll know the wallet doesn't support that request). There is no risk of confusing an UWULink QR with an EIP-681 QR, since the scheme and content format differ. Therefore, wallets that only implement support for EIP-681 will not mistakenly handle a UWULink payload as a valid request.</p> </li> <li> <p><strong>Ensuring Backwards Compatibility in Data Format:</strong> The protobuf schema is designed such that new fields could be added in the future in a non-breaking way (per Proto3 rules, unknown fields are ignored by receivers). For example, a future version might add an optional <code>uint64 expiration_timestamp</code> or <code>string origin</code> field to carry a domain name for UI display. An older wallet would ignore these and still execute the core request. This forward-compatibility means UWULink can evolve without breaking older implementations, as long as additions are carefully made optional.</p> </li> <li> <p><strong>Fall-back to Standard Flows:</strong> From a dApp perspective, implementing UWULink does not preclude supporting traditional wallet connections. A dApp can offer UWULink QR codes for users who prefer privacy or are on devices (like a separate mobile) without browser extensions. At the same time, it can have the usual “Connect Wallet” button for users who are okay with that. This multi-modal approach ensures no user is left out. Over time, if UWULink (or similar one-way flows) prove safer and more popular, they might become the default, allowing users to interact with dApps without connecting a wallet.</p> </li> <li> <p><strong>Network Compatibility:</strong> We limit scope to EVM-compatible chains. That means chains that use <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> transaction scheme and Ethereum-like addresses. On non-EVM chains, this standard doesn’t apply (though analogous concepts could). Within EVM chains, a nuance: if a chain has a different maximum gas limit or transaction format peculiarity, the wallet internally deals with that. UWULink just says "execute these calls." As long as the wallet can create a transaction that does so, it’s fine. If an EVM chain does not support atomic multi-call (some L2s or sidechains might not immediately support EIP-7702), the wallet has to handle it at the account abstraction layer if possible, or otherwise <strong>MUST</strong> reject the request. This again falls to the wallet to know its capabilities (e.g. per <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a>’s capabilities query).</p> </li> </ul> <p>In conclusion, UWULink aims to introduce new functionality without disrupting existing user journeys. It is opt-in for all parties. Early adopters (both dApps and wallets) can experiment with it while others continue as usual. As support grows, it could become a widely recognized standard for secure one-way wallet interactions. The design takes into account lessons from previous proposals (<a href="https://wg-eips.ritovision.com/681/">EIP-681</a> URIs, WalletConnect, <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a>, etc.) and ensures that adopting UWULink is a low-risk enhancement rather than a breaking change to Ethereum’s ecosystem.</p> <!-- TODO: Reference Implementation --> <h2 id="security-considerations">Security Considerations</h2> <h3 id="privacy">Privacy</h3> <p>UWULink is designed with privacy in mind, but it introduces some new security aspects that implementers and users should consider:</p> <ul> <li><em>No Wallet Identification:</em> The wallet does not disclose the user’s address or any wallet details to the dApp when using UWULink. This significantly improves privacy compared to typical wallet connect flows. The dApp only learns of the user's address if and when the transaction is broadcast on-chain. Even then, the dApp cannot easily correlate that address with a specific user session (the user could be anonymous on the website until that point).</li> <li><em>On-Chain Resolver Calls:</em> In programmable mode, the user's address is supplied to the resolver contract as a parameter. This happens off-chain via <code>eth_call</code>, so it does not create a public transaction. However, the node or RPC provider that the wallet uses will see that call (just like any read call). If the RPC provider is untrusted, this could leak some information (e.g., that this address is interested in this resolver's data). In most cases this is a minor concern (no more revealing than using the dApp itself while connected to an RPC), but users who are extremely privacy-conscious might prefer static mode or ensure they use a privacy-respecting RPC. Importantly, the dApp backend or frontend does not see this – only the blockchain infrastructure does.</li> <li><em>No Third-Party Tracking:</em> Because UWULink can be used via local channels (QR/NFC), it avoids relying on any centralized relay. WalletConnect v1, for instance, used relay servers and handshake topics which, in theory, could be tracked or snooped (even though payloads were encrypted, the metadata might leak usage patterns). UWULink in contrast can be a completely peer-to-peer (user and dApp) interaction with minimal digital footprint aside from the eventual blockchain transaction.</li> <li><em>User Consent:</em> As with any transaction, the user explicitly consents by scanning and approving the request. The user relies on the wallet's simulation and multi-factor authorization capabilities to prevent sending of malicious transactions.</li> </ul> <h3 id="security-of-transaction-requests">Security of Transaction Requests</h3> <ul> <li> <p><em>Phishing and Malicious QR Codes:</em> A malicious actor could present a user with a UWULink QR code that, if scanned and approved blindly, could cause the user to transfer funds or approve tokens to the attacker. This risk is analogous to phishing links or malicious dApp websites in today's context. Users should be educated to only approve UWULink requests from sources they trust or understand. Wallets should help by displaying <strong>clear human-readable information</strong> about what the request will do:</p> <ul> <li>Show the names or ENS of known contract addresses involved (or at least highlight unknown addresses).</li> <li>Decode function selectors to known function names if possible (e.g., show "approve(address _spender, uint256 _value)" instead of raw hex).</li> <li>For value transfers, show the ETH or token amount in a friendly format.</li> <li>Possibly warn if the request involves calling an unrecognized contract with large value transfers or if it sets a high token allowance, etc.</li> </ul> </li> <li> <p><em>Atomic Execution and Reverts:</em> By enforcing atomic execution, UWULink ensures that partial completion won't lead to stuck funds or unintended states. However, this also means a malicious or buggy request could be crafted to always revert (for example, by including an incompatible call), which could waste user gas fees if not caught. Wallets should simulate the batch when possible. If the wallet can do a dry-run (for instance using <code>eth_call</code> on a Bundler or internal simulation) it might detect a guaranteed revert and inform the user that the call set is invalid (though this might be complex to do reliably for all calls).</p> </li> <li> <p><em>Resolver Contract Trust:</em> The programmable mode introduces a potential trust issue: the user is effectively trusting the resolver contract’s code to generate the calls honestly. If the resolver contract is malicious, it could return call data that benefits an attacker. For example, a malicious resolver could ignore the input data and always return a call transferring all of the user's ETH to the attacker’s address. <strong>Mitigations:</strong></p> <ul> <li>Ideally, resolver contracts should be open source and verified, and the dApp using them should be reputable. The wallet can’t fully know if the resolver’s output is malicious until it sees it, but the user will have a chance to review the resulting calls anyway. This is crucial: the wallet must display the <em>resulting calls</em> from the resolver to the user, just as it would in static mode. The user should then notice if something is off (e.g., a transfer of all their ETH is about to happen).</li> <li>Wallet developers might consider adding special handling or warnings if a resolver returns calls that do not seem correlated with the input. However, this is hard to generalize. At minimum, treat the resolver output with the same suspicion as a static request. There’s no inherent additional risk beyond what static mode has, because the user still confirms the final calls. The difference is just where the call data came from.</li> <li>We assume resolver contracts will often be provided by the same party as the dApp and thus come with an implied level of trust (or at least, they can be audited by the community if the UWULink scheme becomes popular).</li> </ul> </li> <li> <p><em>No Automatic Spending:</em> UWULink does not introduce new signing or authorization paradigms – it uses actual transactions that the user signs on the spot. Thus, it’s less prone to the kind of issues where a signature can be later reused (like the risks with off-chain signatures). Each UWULink request is one transaction (with possibly multiple subcalls). After it's executed, the link cannot be reused to automatically trigger more actions (unless the user scans it again). This is good from a security standpoint since it doesn't create long-lived permissions. One exception: if a call within the batch is an approval or something, that is an on-chain permission that persists as usual (the user should be made aware as normal).</p> </li> <li> <p><em>Denial of Service (DOS):</em> A malicious dApp could craft an extremely large UWULink payload (especially in static mode) that could crash or slow a wallet app upon scanning (due to memory or decoding issues). Wallets should implement size limits and perhaps streaming parsing for the protobuf to avoid crashes. If a payload exceeds a reasonable size (e.g., several kilobytes), the wallet can reject it for safety. Similarly, a resolver contract could try to return extremely large results – wallets should guard against that by limiting the amount of gas provided to the resolver via eth_call.</p> </li> <li> <p><em>Capabilities and Future Extensions:</em> UWULink intentionally does not carry any additional flags like gas limits or paymaster info (unlike EIP-5792 which has a capabilities system). This is to keep the format simple. However, this means the wallet will apply its own heuristics for gas, and by default the user pays fees. If a future extension wanted to allow gas sponsorship or other features, that could be added either by extending the protobuf (e.g., adding an optional paymaster field) or by having the resolver contract itself handle that (e.g., a resolver could incorporate a paymaster logic by returning a call to a paymaster contract as part of the batch). In any case, security considerations around gas (like a malicious paymaster causing some weird behavior) would need to be analyzed. For now, UWULink operates within the normal transaction model, so the main security focus is on the correctness of calls.</p> </li> </ul> <p><strong>Comparison to Traditional Flows:</strong> One might ask, does eliminating the wallet &lt;-&gt; dApp handshake create any new risks? In traditional connected dApp sessions, the wallet at least knows the origin of requests (e.g., which website is calling <code>eth_sendTransaction</code> or <code>wallet_sendCalls</code>). In UWULink, the origin is essentially "the QR code the user scanned" – the wallet might know the payload came via a QR/NFC but not which app or site. In security terms, this means the wallet cannot apply domain-based whitelists or blocklists (since there's no domain, unless the URI contains one in the payload which it typically wouldn't). Therefore, <strong>the user must manually trust and verify each request.</strong> This is akin to using a hardware wallet: every transaction is shown on a screen and the user approves it, with no assumptions about where it came from. This places responsibility on the user and makes the wallet’s job of displaying info accurately even more important.</p> <p><strong>Privacy vs. Usability Trade-off:</strong> Because UWULink doesn’t let the dApp query the wallet off-chain, some conveniences are lost – e.g., the dApp cannot automatically fetch the user's address to display their balance or NFTs in the UI prior to a transaction. This is a conscious privacy trade-off. Some advanced dApps might find workarounds (like asking the user to input their address manually if they want to see personalized info, or shifting more logic on-chain as in programmable mode). Users and dApp developers must understand this trade-off. In contexts where user personalization without login is needed, UWULink might require a bit more creativity, but it ensures that if the user chooses not to share anything, they truly don't until a transaction is made.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-05-09T00:00:00+00:00 2026-02-11T14:48:25+00:00 Siyuan Zhenghttps://github.com/andrewcoder666zhengsiyuan.zsy@antgroup.com Xiaoyu Liuhttps://github.com/elizabethxiaoyujiushi.lxy@antgroup.com Wenwei Mahttps://github.com/madyinglighthuiwei.mww@antgroup.com Jun Meng Tanhttps://github.com/chadxethjunmeng.t@antgroup.com Yuxiang Fuhttps://github.com/tmac4096kunfu.fyx@antgroup.com Kecheng Gaohttps://github.com/thanks-v-me-50gaokecheng.gkc@antgroup.com Alwin Ng Jun Weihttps://github.com/alwinngjwalwin.ng@antgroup.com Chenxin Wanghttps://github.com/3235773541wcx465603@antgroup.com Xiang Gaohttps://github.com/GaoYiRugaoxiang.gao@antgroup.com yuanshanhshanhttps://github.com/xunayuanyuanshanshan.yss@antgroup.com Hao Zouhttps://github.com/BruceZH0915situ.zh@antgroup.com Yanyi Liangeason.lyy@antgroup.com Yuehua Zhanghttps://github.com/astroyhzccruoying.zyh@antgroup.com https://wg-eips.ritovision.com/7945/

Confidential transactions hide token amounts. This proposal outlines a fungible confidential token interface, boosting privacy in dApps.

<h2 id="abstract">Abstract</h2> <p>Classic token contracts like <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> enable their token holders to make transfers and/or approve others to make transfers on their behalves. The generality of token standard <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> catalyzed decentralizing finance and many other blockchain applications. However, when it comes to privacy, although some technical schemes have been proposed, few standards have been established, which limits the evolution of privacy-preserving blockchain applications.</p> <p>This proposal draws up a standard interface for fungible token contracts supporting confidential transactions. It provides basic transfer functionality without loss of generality, and allowance and approve functionalities. Contracts following the standard can provide confidentiality for users’ balances and token transfer value, and can enable other blockchain applications to make transfers on behalf of owners, which empowers more privacy-preserving capabilities to blockchain applications.</p> <h2 id="motivation">Motivation</h2> <p>Confidential transactions have been implemented in many blockchains, either natively through blockchain protocols like Monero and Zcash, or through smart contracts like Zether<sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">1</a></sup> without modifying blockchain protocol.</p> <p>However, when it comes to the latter way, actually few standards are proposed yet on Ethereum (and/or other EVM-compatible blockchains) to illustrate such contracts. Users and applications cannot easily detect whether a token contract supports confidential transactions or not, and so hardly can they make transfers without revealing the actual amount.</p> <p>Consequently, this proposal is to standardize the confidential transaction supported token contracts, meanwhile without loss of generality, by only specifying core methods and events.</p> <p>Such standard interface allows confidential transactions of tokens to be applied by certain parties which are sensitive to transfer amount, or by privacy-preserving applications.</p> <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="contract-interface">Contract Interface</h3> <p>The proposed contract implements the following 2 interfaces: <code>ITokenMetadata</code> and <code>IConfidentialToken</code> .</p> <h4 id="itokenmetadata"><code>ITokenMetadata</code></h4> <h5 id="methods">Methods</h5> <h6 id="name"><code>name</code></h6> <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-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></code></pre> <p>Returns the name of the token - e.g. <code>"MyConfidentialToken"</code> .</p> <p>OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present.</p> <h6 id="symbol"><code>symbol</code></h6> <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-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></code></pre> <p>Returns the symbol of the token. e.g. <code>"cHIX"</code> .</p> <p>OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present.</p> <h6 id="decimals"><code>decimals</code></h6> <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"> 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></code></pre> <p>Returns the number of decimals the token uses - e.g. <code>8</code> , means to divide the token amount by <code>100000000</code> to get its user representation.</p> <p>OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present.</p> <h4 id="iconfidentialtoken"><code>IConfidentialToken</code></h4> <h5 id="methods-1">Methods</h5> <h6 id="confidentialbalanceof"><code>confidentialBalanceOf</code></h6> <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"> confidentialBalanceOf</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 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 class="z-variable"> confidentialBalance</span><span>)</span></span></code></pre> <p>Returns the confidential balance of the account with address <code>owner</code> .</p> <h6 id="confidentialtransfer"><code>confidentialTransfer</code></h6> <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"> confidentialTransfer</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"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _confidentialTransferValue</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 class="z-variable z-parameter z-function"> _proof</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-support">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre> <p>Transfers <code>value</code> amount of tokens (behind <code>_confidentialTransferValue</code> ) to address <code>_to</code> , and MUST fire the <code>ConfidentialTransfer</code> event. The function SHOULD <code>throw</code> if the message caller’s <code>_proof</code> of this transfer fails to be verified.</p> <p>Note:</p> <ul> <li> <p>Callers MUST handle <code>false</code> from returns (bool success). Callers MUST NOT assume that <code>false</code> is never returned!</p> </li> <li> <p>Implementations can fully customize the proof system, (de)serialization strategies of <code>bytes</code> and/or the business workflow. For example, when implementing "Zether"<sup class="footnote-reference" id="fr-1-2"><a href="#fn-1">1</a></sup> confidential token contracts, the <code>_confidentialTransferValue</code> and accounts' confidential balances will be encrypted homomorphically under ElGamal public keys, and <code>_proof</code> will consist 3 parts to check:</p> <ul> <li><code>_confidentialTransferValue</code> is well encrypted under both caller's public key and <code>_to</code> 's;</li> <li>The plaintext <code>value</code> behind <code>_confidentialTransferValue</code> is non-negative;</li> <li>The caller's confidential balance is actually enough to pay the plaintext <code>value</code> behind <code>_confidentialTransferValue</code> .</li> </ul> </li> </ul> <h6 id="confidentialtransferfrom"><code>confidentialTransferFrom</code></h6> <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"> confidentialTransferFrom</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"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _confidentialTransferValue</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 class="z-variable z-parameter z-function"> _proof</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-support">bool</span><span class="z-variable"> success</span><span>)</span></span> <span class="giallo-l"><span> </span></span></code></pre> <p>Transfers <code>value</code> amount of tokens (behind <code>_confidentialTransferValue</code> ) from address <code>_from</code> to address <code>_to</code> , and MUST fire the <code>ConfidentialTransfer</code> event.</p> <p>The <code>confidentialTransferFrom</code> method is used for a withdraw workflow, allowing contracts to transfer tokens on your behalf. This can be used for example to allow a contract to transfer tokens on your behalf and/or to charge fees in sub-currencies. The function SHOULD <code>throw</code> unless the <code>_from</code> account has deliberately authorized the sender of the message via some mechanism, and SHOULD <code>throw</code> if the message caller’s <code>_proof</code> of this transfer fails to be verified.</p> <p>Note:</p> <ul> <li> <p>Callers MUST handle <code>false</code> from returns (bool success). Callers MUST NOT assume that <code>false</code> is never returned!</p> </li> <li> <p>Implementations can fully customize the proof system, (de)serialization strategies of <code>bytes</code> and/or the business workflow. For example, when implementing "Zether" confidential token contracts, the <code>_confidentialTransferValue</code> and accounts' confidential balances will be encrypted homomorphically under ElGamal public keys, and <code>_proof</code> will consist 3 parts to check:</p> <ul> <li><code>_confidentialTransferValue</code> is well encrypted under public keys of <code>_from</code> 's, <code>_to</code> 's and caller's;</li> <li>The plaintext <code>value</code> behind <code>_confidentialTransferValue</code> is non-negative;</li> <li>The caller's confidential allowance is actually enough to pay the plaintext <code>value</code> behind <code>_confidentialTransferValue</code> .</li> </ul> </li> </ul> <h6 id="confidentialapprove"><code>confidentialApprove</code></h6> <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"> confidentialApprove</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"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _confidentialValue</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 class="z-variable z-parameter z-function"> _proof</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-support">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre> <p>Allows <code>_spender</code> to withdraw from caller's split part of balances multiple times, up to the amount (allowance value) behind <code>_confidentialValue</code> to 0. This function SHOULD <code>throw</code> if the message caller’s <code>_proof</code> of this transfer fails to be verified.</p> <p>Caution:</p> <p>This function behaves much <strong>differently from</strong> <code>approve(address,uint256)</code> in <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>.</p> <p>Calling <code>confidentialApprove</code> splits the confidential balance of caller's account into <em>allowance part</em> and <em>the left part</em>.</p> <p>The values behind two parts above after calling <code>confidentialApprove</code> , and the value behind the original confidential balance of caller's account before calling <code>confidentialApprove</code> satisfy the equation:</p> <p>$$ value_{Behind\ Allowance\ Part} + value_{Behind\ Left\ Part} = value_{Behind\ Original\ Confidential\ Balance} $$</p> <ul> <li> <p>The allowance part of confidential balance allows <code>_spender</code> to withdraw multiple times through calling <code>confidentialTransferFrom</code> until <code>_spender</code> does not call it any more or the value behind this part is 0.</p> <ul> <li>Every time the <code>_spender</code> calls <code>confidentialTransferFrom</code> , the value behind this part will be decreased by the value behind <code>_confidentialTransferValue</code> .</li> </ul> </li> <li> <p>The left part remains as the new confidential balance of caller's account.</p> </li> </ul> <p>If this function is called again it,</p> <ul> <li>merges existing allowance part into the confidential balance of caller's account; and then</li> <li>overwrites the current allowance part with <code>_confidentialValue</code> .</li> </ul> <p>Note:</p> <ul> <li> <p>Callers MUST handle <code>false</code> from returns (bool success). Callers MUST NOT assume that <code>false</code> is never returned!</p> </li> <li> <p>Implementations can fully customize the proof system, (de)serialization strategies of <code>bytes</code> and/or the business workflow. For example, when implementing "Zether" confidential token contracts, the <code>_confidentialValue</code> and accounts' confidential balances will be encrypted homomorphically under ElGamal public keys, and <code>_proof</code> will consist 3 parts to check:</p> <ul> <li><code>_confidentialValue</code> is well encrypted under public keys of caller's and <code>_spender</code>'s;</li> <li>The plaintext <code>value</code> behind <code>_confidentialValue</code> is non-negative;</li> <li>The caller's confidential balance is actually enough to pay the plaintext <code>value</code> behind <code>_confidentialValue</code> .</li> </ul> </li> </ul> <h6 id="confidentialallowance"><code>confidentialAllowance</code></h6> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>functinon </span><span class="z-entity z-name">confidentialAllowance</span><span>(</span><span class="z-support">address</span><span> _owner</span><span>,</span><span class="z-support"> address</span><span> _spender</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">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _confidentialValue</span><span>)</span></span></code></pre> <p>Returns the allowance part which <code>_spender</code> is still allowed to withdraw from <code>_owner</code>.</p> <h5 id="events">Events</h5> <h6 id="confidentialtransfer-1"><code>ConfidentialTransfer</code></h6> <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"> ConfidentialTransfer</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"> 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"> bytes</span><span class="z-variable"> _confidentialTransferValue</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>MUST trigger when tokens are transferred.</p> <p>Specifically, if tokens are transferred through function <code>confidentialTransferFrom</code>, <code>_spender</code> address MUST be set to caller's; otherwise, it SHOULD be set to <code>0x0</code>.</p> <p>A confidential token contract,</p> <ul> <li>which creates new tokens SHOULD trigger a <code>ConfidentialTransfer</code> with the <code>_from</code> address set to <code>0x0</code> when tokens are minted;</li> <li>which destroys existent tokens SHOULD trigger a <code>ConfidentialTransfer</code> with the <code>_to</code> address set to <code>0x0</code> when tokens are burnt.</li> </ul> <h6 id="confidentialapproval"><code>ConfidentialApproval</code></h6> <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"> ConfidentialApproval</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"> bytes</span><span class="z-variable"> _currentAllowancePart</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> _allowancePart</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>MUST trigger on any successful call to <code>confidentialApprove(address,bytes,bytes)</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="optional-accessor-of-confidential-total-supply">Optional Accessor of "Confidential Total Supply"</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"> confidentialTotalSupply</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">bytes</span><span class="z-storage z-type"> memory</span><span>)</span></span></code></pre> <p>Confidentiality of transfer amount makes it hard to support such field like <code>totalSupply()</code> in <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. Because when it comes to the token "mint" or "burn", if every user in this contract can access <code>totalSupply()</code> as well as decrypt it, these users will know the actual token value to be minted or burnt by comparing the <code>totalSupply()</code> before and after such operations, which means that confidentiality no longer exists.</p> <p>Contract implementation can optionally support <code>confidentialTotalSupply()</code> by evaluating if anti-money laundry (see next part) and audit are required. That would be much more plausible by making a small group of parties can know the plaintext total supply behind <code>confidentialTotalSupply()</code>.</p> <h3 id="anti-money-laundry-and-audit">Anti-money Laundry and Audit</h3> <p>To support audit of confidential transactions and total supply, especially such token issuers are banks or other financial institutes supervised by governments or monetary authorities, confidential transactions can be implemented without changing <code>confidentialTransfer</code> method signature, by encoding more info into parameters.</p> <p>For example in Zether-like implementation[^2], if token transfers are required to be audited, <code>confidentialTransfer</code> caller encrypts transfer <code>value</code> redundantly under public keys of caller's, <code>to</code>'s, a group of auditors', which makes it possible that related parties can exactly know the real <code>value</code> behind. So does <code>confidentialTotalSupply()</code>.</p> <h3 id="fat-token">Fat Token</h3> <p>Confidential transactions supported token can also implement <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> at the same time.</p> <p>Token accounts in such tokens can hold 2 kinds of balances. Such token contracts can optionally provide methods to hide <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> plaintext balances into confidential balances, and vice versa, to reveal confidential balances back to <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> plaintext balances.</p> <p><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> interfaces will bring much more usability and utilities to confidential transaction supported tokens, realizing general confidentiality meantime.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="security-considerations">Security Considerations</h2> <p>To realize full confidentiality, contracts implementing this presented interface SHOULD NOT create (mints) or destroy (burns) tokens with plaintext value parameters. For implementation, following the same encryption strategies in <code>confidentialTransfer(address,bytes,bytes)</code> is RECOMMENDED.</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>Bünz, B., Agrawal, S., Zamani, M., &amp; Boneh, D. (n.d.). <span style="font-style: italic;">Zether: Towards Privacy in a Smart Contract World</span>. https://doi.org/<a href="https://doi.org/10.1007/978-3-030-51280-4_23">10.1007/978-3-030-51280-4_23</a> (Original work published 2020)[^2]: Chen, Y., Ma, X., Tang, C., &amp; Au, M. H. (n.d.). <span style="font-style: italic;">PGC: Decentralized Confidential Payment System with Auditability</span>. https://doi.org/<a href="https://doi.org/10.1007/978-3-030-58951-6_29">10.1007/978-3-030-58951-6_29</a> (Original work published 2020) <a href="#fr-1-1">↩</a> <a href="#fr-1-2">↩2</a></p> </li> </ol> </section> 2025-05-07T00:00:00+00:00 2026-02-11T14:48:25+00:00 Artem Chystiakovhttps://github.com/arvolearartem@rarilabs.com https://wg-eips.ritovision.com/7947/

Universal mechanism to recover a smart account's access via custom recovery providers.

<h2 id="abstract">Abstract</h2> <p>Introduce a universal account abstraction recovery mechanism <code>recoverAccess(subject, provider, proof)</code> along with recovery provider management functions for smart accounts to securely update their access subject.</p> <h2 id="motivation">Motivation</h2> <p>Account abstraction and the "contractization" of EOAs are important Ethereum milestones for improving on-chain UX and off-chain security. A wide range of smart accounts emerge daily, aiming to simplify the steep onboarding curve for new users. The ultimate smart account experience is to never ask them to deal with private keys, yet still allow for full account control and access recovery. With the developments in the Zero-Knowledge Artificial Intelligence (ZKAI) and Zero-Knowledge Two Factor Authentication (ZK2FA) fields, settling on a common mechanism may even open the doors for "account recovery provider marketplaces" to emerge.</p> <p>The account recovery approach described in this proposal allows for multiple recovery providers to coexist and provide a wide variety of unique recovery services. In simple terms, smart accounts become "recovery provider aggregators", making it possible for the users to never rely on centralized services or projects.</p> <p>The Account Abstraction Recovery Interface (AARI) aims to define a flexible interface for <em>any</em> smart account to implement, allowing users to actively manage their account recovery providers and restore the access of an account in case of a private key loss.</p> <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>A smart account willing to support AARI MUST implement the following 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.20</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"> Defines a common account recovery interface for smart accounts to implement.</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"> IAccountRecovery</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * MUST be emitted whenever the access of the account changes as a result </span></span> <span class="giallo-l"><span class="z-comment"> * of the account recovery (e.g. in the `recoverAccess` function).</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"> AccessRecovered</span><span>(</span><span class="z-support">bytes</span><span class="z-variable"> subject</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"> * MUST be emitted whenever a new recovery provider is added to</span></span> <span class="giallo-l"><span class="z-comment"> * the account (e.g. in the `addRecoveryProvider` function).</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"> RecoveryProviderAdded</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> provider</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 be emitted whenever a recovery provider is removed from</span></span> <span class="giallo-l"><span class="z-comment"> * the account (e.g. in the `removeRecoveryProvider` function).</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"> RecoveryProviderRemoved</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> provider</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"> A function to add a new recovery provider.</span></span> <span class="giallo-l"><span class="z-comment"> * SHOULD be access controlled.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST check that `provider` is not `address(0)`.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST call `subscribe` on the `provider`.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST pass `recoveryData` to the `subscribe` function.</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"> provider</span><span class="z-comment"> the address of a recovery provider (ZKP verifier) to add.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> recoveryData</span><span class="z-comment"> custom data (commitment) for the recovery provider.</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"> addRecoveryProvider</span><span>(</span><span class="z-support">address</span><span class="z-variable"> provider</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> recoveryData</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> A function to remove an existing recovery provider.</span></span> <span class="giallo-l"><span class="z-comment"> * SHOULD be access controlled.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST call `unsubscribe` on the `provider`.</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"> provider</span><span class="z-comment"> the address of a previously added recovery provider to remove.</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"> removeRecoveryProvider</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"> 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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> A view function to check if a provider has been previously added.</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"> provider</span><span class="z-comment"> the provider to check.</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 provider exists in the account, 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"> recoveryProviderAdded</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> <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 non-view function to recover access of a smart account.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST check that `provider` exists in the account.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST call `recover` on the `provider`.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST update the account access according to `subject` if `proof` verification succeeds.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return `true` if the access recovery is successful.</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"> subject</span><span class="z-comment"> the recovery subject (encoded owner address, access control role, 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"> provider</span><span class="z-comment"> the address of a recovery provider.</span></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"> an encoded proof of recovery (ZKP/ZKAI, signature, etc).</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 recovery is successful, `false` (or revert) 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"> recoverAccess</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"> subject</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"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> proof</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></span></code></pre> <p>A recovery provider 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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Defines a common recovery provider interface.</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"> IRecoveryProvider</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * MUST be emitted whenever a new account subscribes to</span></span> <span class="giallo-l"><span class="z-comment"> * the recovery provider (e.g. in the `subscribe` function).</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"> AccountSubscribed</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 class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * MUST be emitted whenever an account unsubscribes from</span></span> <span class="giallo-l"><span class="z-comment"> * the recovery provider (e.g. in the `unsubscribe` function).</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"> AccountUnsubscribed</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 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 function that &quot;subscribes&quot; a smart account (msg.sender) to a recovery provider.</span></span> <span class="giallo-l"><span class="z-comment"> * SHOULD process and assign the `recoveryData` to the `msg.sender`.</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"> recoveryData</span><span class="z-comment"> a recovery commitment (hash/ZKP public output) to be used </span></span> <span class="giallo-l"><span class="z-comment"> * in the `recover` function to check a recovery proof validity.</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"> subscribe</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> recoveryData</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> A function that revokes a smart account subscription.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST delete all the recovery data associated with the `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"> unsubscribe</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> A function to get a recovery data (commitment) of an account.</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"> account</span><span class="z-comment"> the account to get the recovery data 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"> associated recovery data.</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"> getRecoveryData</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">bytes</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> A function that checks if a recovery of a smart account (msg.sender)</span></span> <span class="giallo-l"><span class="z-comment"> * to the new subject is possible.</span></span> <span class="giallo-l"><span class="z-comment"> * SHOULD use `msg.sender`&#39;s `recoveryData` to check the `proof` validity.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST ensure that the `proof` can&#39;t be reused, e.g. update nonce.</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"> object</span><span class="z-comment"> the new object (may be different to subject) to recover the `msg.sender` access 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"> proof</span><span class="z-comment"> the recovery proof.</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"> recover</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> object</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> proof</span><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> <p>The AARI is expected to work with <em>any</em> account abstraction standard to allow for maximum account recovery flexibility. Whether it is <a href="https://wg-eips.ritovision.com/4337/">EIP-4337</a> or <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>, a particular smart account provider may support account recovery by simply implementing a common interface.</p> <p>Since the whole account recovery process is nothing but proving the knowledge of some alternative secret to a private key, it is essential for accounts to be able to "commit" to this secret. The <code>subscribe</code> function in the recovery provider interface allows precisely for that. Moreover, if at some point in time a user wanted to "recommit" to a new secret (due to security reasons), they could multicall <code>unsubscribe</code> + <code>subscribe</code> functions to achieve the desired result.</p> <p>The recovery functions accept arbitrary bytes as <code>subject</code> and <code>object</code> parameters to allow for a variety of access control rules to be recovered, since many smart accounts are ownerless and have no "owner" address to be directly substituted.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are several security concerns to point out:</p> <ul> <li>It is up to a smart account developer to properly access control <code>addRecoveryProvider</code> and <code>removeRecoveryProvider</code> functions.</li> <li>A smart account user may be "phished" to add a malicious recovery provider to their account. In that case, a recovery provider may gain full control over the account by accepting fake recovery proofs.</li> </ul> <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-30T00:00:00+00:00 2026-02-11T14:49:27+00:00 Mingfei Zhanghttps://github.com/Mart1i1nmingfei.zh@outlook.com Rujia Lirujia@tsinghua.edu.cn Xueqian Luxueqian.lu@bitheart.org Sisi Duanduansisi@tsinghua.edu.cn https://wg-eips.ritovision.com/7942/

A reorg-resilient solution for Ethereum

<h2 id="abstract">Abstract</h2> <p>This EIP proposes Available Attestation (AA), a protocol enhancement to make Ethereum PoS resilient against reorganization attacks. The proposal introduces a stability criterion for blocks based on attestation quorums, requiring that a block must include at least one-third of validators' attestations from the previous slot to be considered stable. The proposal includes three main changes: (1) modifying the parent selection rule to require AA from the previous slot, (2) replacing HLMD-GHOST with a Longest Stable Chain fork choice rule, and (3) adding a reference field to recent unstable blocks to preserve transaction continuity. These changes collectively prevent Byzantine validators from successfully executing reorganization attacks in synchronous networks while maintaining safety and liveness properties in partially synchronous networks. A full technical analysis is available in our <a href="https://wg-eips.ritovision.com/7942/./assets/available-attestation-paper.pdf">companion paper</a> accepted to USENIX Security 2025.</p> <h2 id="motivation">Motivation</h2> <p>We find that all known effective attacks on Ethereum PoS belong to reorganization attacks, although they emphasize different types of adversarial strategies. According to how the canonical chain is manipulated by the adversary, we classify known attacks into two categories: attacks from <em>changing block weight</em> and attacks from <em>filtering block tree</em>. The attacks from changing block weight refer to the strategy where Byzantine validators modify the <em>weight</em> of their proposed blocks to make their fork eventually become the canonical chain. Meanwhile, the attacks from filtering block tree do not change the block weight. Instead, these attacks make honest validators prune the canonical chain. This is often achieved by changing the <em>state</em> of honest validators. We summarize these malicious reorganization attacks in the following table.</p> <table><thead><tr><th><strong>attack type</strong></th><th><strong>scheme</strong></th><th><strong>timing assumption</strong></th><th><strong>mitigation solution</strong></th><th><strong>limitation</strong></th></tr></thead><tbody> <tr><td>changing block weight</td><td>ex-ante reorg</td><td>synchrony</td><td>proposer boosting v1</td><td>cause sandwich reorg</td></tr> <tr><td></td><td>balancing attack</td><td>synchrony</td><td>proposer boosting v1</td><td>cause sandwich reorg</td></tr> <tr><td></td><td>sandwich reorg</td><td>synchrony</td><td>proposer boosting v2⋆</td><td>cannot fully prevent</td></tr> <tr><td>filtering block tree</td><td>bouncing attack</td><td>partial synchrony†</td><td>safe-slots</td><td>cannot fully prevent</td></tr> <tr><td></td><td>unrealized justification reorg</td><td>synchrony</td><td>Capella upgrade</td><td>cause staircase attack</td></tr> <tr><td></td><td>justification withholding reorg</td><td>synchrony</td><td>Capella upgrade</td><td>cause staircase attack</td></tr> <tr><td></td><td>staircase attack</td><td>synchrony</td><td>Deneb upgrade</td><td>cannot fully prevent</td></tr> </tbody></table> <p>⋆ Proposer boosting parameter decreases from 0.7 to 0.4.<br /> † The attack is conducted after the network is synchronous.</p> <p>In response to these vulnerabilities, mitigation approaches have been proposed from both academia and industry. They are often designed in an ad-hoc way, addressing one issue at a time. Without formal proof, these mitigation approaches may create new issues. For instance, to mitigate the ex-ante reorg attack and balancing attack, Ethereum implements the <em>proposer boosting</em> mechanism. By temporarily adjusting the weight of the block in the current slot, the forks created by the adversary will not become the canonical chain. However, this mitigation approach introduces new issues. A so-called <em>sandwich reorg attack</em> was later proposed, exploiting proposer boosting to create a reorg attack. The sandwich reorg attack is a variant of ex-ante reorg attacks where two Byzantine proposers collude to make the blocks by honest validators orphaned. Additionally, many known mitigation solutions lack formal analysis or introduce additional assumptions, e.g., by assuming that the ratio of stake controlled by the adversary is no more than 20%. Therefore, our approach aims to provide a provably secure and efficient solution that is resilient to reorg attacks in Ethereum PoS.</p> <h2 id="specification">Specification</h2> <h3 id="overview">Overview</h3> <p>We provide a lightweight yet efficient solution for Ethereum PoS which is:</p> <ol> <li>reorg resilient in a synchronous network;</li> <li>safe and live in a partially synchronous network;</li> <li>easy to implement and deploy.</li> </ol> <p>We introduce AA, an approach inspired by conventional BFT protocols from <em>weak quorum</em> of attestations. Namely, consider a system with $N$ validators, among which at most $f$ are faulty. If $f+1$ validators vote for a block $b$ in slot $t$, at least one honest validator has validated $b$. The $f+1$ attestations become a <em>proof</em> of the availability of $b$. We use $AA_t$ to denote a block with $f+1$ attestations in slot $t$.</p> <p>Putting the concept of weak quorums in the context of Ethereum PoS, we define AA as a mechanism that checks <em>whether a block includes matching attestations from at least one-third of validators</em> (For simplicity, we assume that all validators attest in every slot in this section). In particular, if $b$ is a block for slot $t$, its child must include attestations for $b$ from at least one-third of validators in slot $t$. We use the notion of <em>stable block</em> to describe this scenario.</p> <h3 id="definition">Definition</h3> <p>Formally, we give the following definitions for AA:</p> <ul> <li> <p>(AA) We use $AA_t$ to denote a block that receives more than one-third of attestations voting for it in slot $t$.</p> </li> <li> <p>(Stable block) <em>A block $b$ proposed in slot $t$ is a stable block if the parent of block $b$ is $AA_{t-1}$</em></p> </li> <li> <p>(Unstable block) <em>Block $b$ is an unstable block if $b$ is not a stable block.</em></p> </li> <li> <p>(Stable chain) <em>The chain $c$ is a stable chain if the leaf block of $c$ is a stable block.</em></p> </li> </ul> <p>In practice, the validators are divided into 32 disjoint committees randomly. Since the committees are sampled pseudorandomly, the number of Byzantine validators in each committee can be approximated by a binomial distribution. We use $f$ as the number of total Byzantine validators and $f'$ as the expected number of Byzantine validators in each committee.</p> <ul> <li>We use $\vartheta$ to denote a threshold on the number of Byzantine validators in each committee and $p$ as the desirable failure probability (i.e., the probability that the number of Byzantine validators in a committee is greater than $\vartheta$).</li> </ul> <p>Given the desired value $p$, the value of $\vartheta$ can be calculated using $\vartheta = \lfloor\mu + \sigma \cdot \Phi^{-1}(1 - p)\rfloor,$ where $\mu = f'$, $\sigma^2 = f'(1 - f/n)$, and $\Phi^{-1}$ is the inverse of the cumulative distribution function of the normal distribution. We show some concrete examples of the ratio of Byzantine validators in a committee.</p> <table><thead><tr><th>n \ p</th><th>10⁻⁶</th><th>10⁻⁷</th><th>10⁻⁸</th><th>10⁻⁹</th></tr></thead><tbody> <tr><td>2¹⁴</td><td>0.4316</td><td>0.4414</td><td>0.4492</td><td>0.4570</td></tr> <tr><td>2¹⁶</td><td>0.3828</td><td>0.3872</td><td>0.3916</td><td>0.3955</td></tr> <tr><td>2¹⁸</td><td>0.3580</td><td>0.3603</td><td>0.3625</td><td>0.3645</td></tr> <tr><td>2²⁰</td><td>0.3457</td><td>0.3468</td><td>0.3479</td><td>0.3489</td></tr> </tbody></table> <p>Ethereum now has approximately $2^{20}$ validators. The maximum desirable probability $10^{-6}$ means that the protocol fails once every $10^{6}$ slots, i.e., 138 days. If the desirable failure probability is $10^{-9}$, malicious reorganization occurs once every 380 years. We can then draw the following conclusion:</p> <p><strong>For a large $n$, the ratio of Byzantine validators is closer to $f/n$. In this way, we can simply set $\vartheta$ as one-third of the committee size.</strong></p> <h3 id="protocol-changes">Protocol Changes</h3> <p>We make four main changes:</p> <ol> <li> <p><strong>Modify the selection rule of parent.</strong> As mentioned in the overview, we require that a block $b$ in slot $t$ must include $\vartheta+1$ attestations to prove that the parent of block $b$ is a valid output in slot $t-1$. Therefore, the parent of block $b$ is the $AA_{t-1}$. Such a block is a stable block. If no $AA_{t-1}$ exists, the parent of block $b$ is the output of the fork choice rule. Such a block is an unstable block.</p> </li> <li> <p><strong>Replace HLMD-GHOST with Longest Stable Chain fork choice rule.</strong> We replace the HLMD GHOST with the longest chain as the fork choice rule. Our longest chain fork choice rule is very simple: it outputs the head of the chain with the most stable blocks. In case of a tie, the longest chain fork choice rule chooses the chain such that the leaf block has the largest slot number.</p> </li> <li> <p><strong>Blocks carry a reference <code>unstable_root</code> to recent unstable blocks to preserve transaction continuity.</strong> We additionally include a field <code>unstable_root</code> in a block b. Each proposer sets its <code>unstable_root</code> field as the hash of an unstable block. If there is no such unstable block, set <code>unstable_root</code> as None. The transactions in the unstable blocks should not conflict with the transactions in the longest chain. The transactions in <code>unstable_root</code> can also be finalized once block b (that includes <code>unstable_root</code>) is finalized.</p> </li> <li> <p><strong>Simplify the filtering rule and the justification process.</strong> We simplify the filtering rule as it only considers the chain that justifies the last justified checkpoint. Additionally, the justification process only updates when a chain crosses the epoch boundary.</p> </li> </ol> <h3 id="pseudocode">Pseudocode</h3> <p>The modifications are based on validator and fork-choice.</p> <h4 id="modification-1">Modification 1</h4> <p>For the validator behavior specification (validator in consensus-specs):</p> <p>To propose, the validator selects a <code>BeaconBlock</code>, <code>parent</code> using this process:</p> <ol> <li>Compute AA blocks at the start of slot. Let <code>aa</code> be the later AA block and <code>aa_root</code> be the root of <code>aa</code>. Set <code>parent_root = aa_root</code>.</li> <li>If no AA block exists, compute fork choice's view of the head at the start of <code>slot</code>, after running <code>on_tick</code> and applying any queued attestations from <code>slot - 1</code>. Set <code>parent_root = get_head(store)</code>.</li> <li>Let <code>parent</code> be the block with <code>parent_root</code>.</li> </ol> <h4 id="modification-2">Modification 2</h4> <p>For the fork choice specification (fork_choice in consensus-specs):</p> <p>Add a class called <code>chain</code> to manage the stable chains.</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"> Chain</span><span>(</span><span class="z-support">object</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> leaf</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> length</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> justified_checkpoint</span><span>:</span><span> Checkpoint</span></span></code></pre> <p>Add chains in <code>store</code>.</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"> Store</span><span>(</span><span class="z-support">object</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"><span> chains</span><span>:</span><span> Set</span><span>[</span><span>Chain</span><span>]</span></span></code></pre> <p>Modify <code>get_head</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"> get_head</span><span>(</span><span class="z-variable z-parameter z-function">store</span><span>:</span><span> Store</span><span>)</span><span> -&gt;</span><span> Root</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Get filtered block tree that only includes viable branches</span></span> <span class="giallo-l"><span> chains</span><span class="z-keyword"> =</span><span> get_filtered_block_tree</span><span>(</span><span>store</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Execute the longest stable chain fork choice</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> max</span><span>(</span><span>chains</span><span>,</span><span class="z-variable"> key</span><span class="z-keyword">=</span><span class="z-storage z-type">lambda</span><span class="z-variable z-parameter z-function"> c</span><span>:</span><span> c</span><span>.</span><span>length</span><span>)</span><span>.</span><span>leaf</span></span></code></pre><h4 id="modification-3">Modification 3</h4> <p>For the validator behavior specification (validator in consensus-specs):</p> <p>Modify <code>Preparing for a BeaconBlock</code></p> <p>To construct a <code>BeaconBlockBody</code>, a <code>block</code> (<code>BeaconBlock</code>) is defined with the necessary context for a block proposal:</p> <h5 id="unstable-root">unstable_root</h5> <p>Set <code>block.unstable_root</code> as the hash of the latest unstable block if such block exists. If none exists, set <code>block.unstable_root = None</code>. The transactions in <code>unstable_root</code> must not conflict with the stable chain and will be finalized once <code>block</code> is finalized.</p> <h4 id="modification-4">Modification 4</h4> <p>For the fork choice specification (fork_choice in consensus-specs):</p> <p>Modify <code>get_filtered_block_tree</code>. Only consider the chain that justifies the latest justified checkpoint.</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_filtered_block_tree</span><span>(</span><span class="z-variable z-parameter z-function">store</span><span>:</span><span> Store</span><span>)</span><span> -&gt;</span><span> List</span><span>[</span><span>Chain</span><span>]</span><span>:</span></span> <span class="giallo-l"><span> chains</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> chain</span><span class="z-keyword"> in</span><span> store</span><span>.</span><span>chains</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> is_equal</span><span>(</span><span>store</span><span>.</span><span>justified_checkpoint</span><span>.</span><span>root</span><span>,</span><span> chain</span><span>.</span><span>justified_checkpoint</span><span>.</span><span>root</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> chains</span><span>.</span><span>append</span><span>(</span><span>chain</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> chains</span></span></code></pre> <p>Remove the fields <code>unrealized_justified_checkpoint</code> and <code>unrealized_finalized_checkpoint</code>. Remove <code>compute_pulled_up_tip</code>, i.e., remove the justification and finalization process that occurs during an epoch. The <code>justified_checkpoint</code> field of a chain is only updated when crossing an epoch boundary.</p> <h2 id="rationale">Rationale</h2> <p>The reason why our approach is reorg resilient is that the AA mechanism <em>prevents</em> Byzantine validators from creating conflicting branches. As summarized in the table, there are two strategies for Byzantine validators: (1) Byzantine validators directly propose a block conflicting with the canonical chain and (2) Byzantine validators propose a block that extends the canonical chain and delay releasing the block. Neither of these strategies works anymore after AA is implemented. For the first type, only the leaf blocks in the block tree can be the output of the fork choice rule. If a Byzantine validator tries to create a block $b_1$ that extends a block $b_0$ that is not a leaf block, $b_0$ will receive no attestations from honest validators. Thus, block $b_1$ is an unstable block. For the second type, our approach ensures that if Byzantine validators withhold at least two stable blocks, one of them must have already been observed by <em>all</em> honest validators (see Lemma 2 in our paper for details).</p> <p>Now it becomes clear why we use the <em>longest chain</em> rule to replace the HLMD-GHOST rule. Informally, as the HLMD-GHOST rule determines the canonical chain based on the weight of the blocks, and the weight is determined by the number of attestations, the HLMD-GHOST rule cannot prevent adversaries from withholding their attestations.</p> <p>Our modified protocol can achieve the safety and liveness properties of the consensus protocol. Safety still holds since we do not modify Casper, the finality gadget protocol. Liveness is achieved after GST mainly because our protocol is reorg resilient in a synchronous network. As all honest validators consider the blocks proposed by honest validators to be part of the longest chain, their attestations will be considered valid by all honest validators, so eventually some block is finalized.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The proposal modifies the fork choice logic and attestation format, which may not be compatible with existing clients. A hard fork or protocol version flag will be required for deployment.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li><strong>Resilience to reorg attacks</strong>: The protocol is provably resilient to all known forms of reorg attacks in synchronous networks.</li> <li><strong>No new attack surfaces</strong>: The protocol avoids introducing new message types or unnecessary overhead.</li> <li><strong>Safe and live</strong>: Maintains standard safety and liveness in partially synchronous networks.</li> </ul> <p>A full formal proof of correctness and evaluation over 16,384 validators is provided in the <a href="https://wg-eips.ritovision.com/7942/./assets/available-attestation-paper.pdf">companion paper</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> 2025-04-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vectorizedhttps://github.com/Vectorized Georgios Konstantopouloshttps://github.com/gakonst Jochem Brouwerhttps://github.com/jochem-brouwer Ben Adamshttps://github.com/benaadams Giulio Rebuffohttps://github.com/Giulio2002 https://wg-eips.ritovision.com/7939/

Opcode to count the number of leading zero bits in a 256-bit word

<h2 id="abstract">Abstract</h2> <p>Introduce a new opcode, <code>CLZ(x)</code>, which pops <code>x</code> from the stack and pushes the number of leading zero bits in <code>x</code> to the stack. If <code>x</code> is zero, pushes 256.</p> <h2 id="motivation">Motivation</h2> <p>Count leading zeros (CLZ) is a native opcode in many processor architectures (even in RISC architectures like ARM).</p> <p>It is a basic building block used in math operations, byte operations, compression algorithms, data structures:</p> <ul> <li>lnWad</li> <li>powWad</li> <li>lambertW0Wad</li> <li>sqrt</li> <li>cbrt</li> <li>byte string comparisons</li> <li>generalized calldata compression/decompression</li> <li>bitmaps (for finding the next/previous set/unset bit)</li> <li>post quantum signature schemes</li> </ul> <p>Adding a <code>CLZ</code> opcode will:</p> <ul> <li>Lead to cheaper compute.</li> <li>Lead to cheaper ZK proving costs. The fastest known Solidity implementation uses several dynamic bitwise right shifts <code>shr</code>, which are very expensive to prove. In SP1 rv32im, a 32-bit right shift costs 1.6x more than a 32-bit mul.</li> <li>Lead to smaller bytecode size. The fastest known Solidity implementation contains several large constants and is often inlined for performance.</li> </ul> <h2 id="specification">Specification</h2> <p>A new opcode is introduced: <code>CLZ</code> (<code>0x1e</code>).</p> <ul> <li>Pops 1 value from the stack.</li> <li>Pushes a value to the stack, according to the following code:</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"> @dev</span><span class="z-comment"> Count leading zeros.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Returns the number of zeros preceding the most significant one bit.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> If `x` is zero, returns 256.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> This is the fastest known `CLZ` implementation in Solidity and uses about 184 gas.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> clz</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> x</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">uint256</span><span class="z-variable"> r</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> @solidity memory-safe-assembly</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"> shl</span><span>(</span><span class="z-constant">7</span><span>,</span><span class="z-entity z-name"> lt</span><span>(</span><span class="z-constant">0xffffffffffffffffffffffffffffffff</span><span>,</span><span> x</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> r </span><span class="z-keyword">:=</span><span class="z-entity z-name"> or</span><span>(</span><span>r</span><span>,</span><span class="z-entity z-name"> shl</span><span>(</span><span class="z-constant">6</span><span>,</span><span class="z-entity z-name"> lt</span><span>(</span><span class="z-constant">0xffffffffffffffff</span><span>,</span><span class="z-entity z-name"> shr</span><span>(</span><span>r</span><span>,</span><span> x</span><span>)</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> r </span><span class="z-keyword">:=</span><span class="z-entity z-name"> or</span><span>(</span><span>r</span><span>,</span><span class="z-entity z-name"> shl</span><span>(</span><span class="z-constant">5</span><span>,</span><span class="z-entity z-name"> lt</span><span>(</span><span class="z-constant">0xffffffff</span><span>,</span><span class="z-entity z-name"> shr</span><span>(</span><span>r</span><span>,</span><span> x</span><span>)</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> r </span><span class="z-keyword">:=</span><span class="z-entity z-name"> or</span><span>(</span><span>r</span><span>,</span><span class="z-entity z-name"> shl</span><span>(</span><span class="z-constant">4</span><span>,</span><span class="z-entity z-name"> lt</span><span>(</span><span class="z-constant">0xffff</span><span>,</span><span class="z-entity z-name"> shr</span><span>(</span><span>r</span><span>,</span><span> x</span><span>)</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> r </span><span class="z-keyword">:=</span><span class="z-entity z-name"> or</span><span>(</span><span>r</span><span>,</span><span class="z-entity z-name"> shl</span><span>(</span><span class="z-constant">3</span><span>,</span><span class="z-entity z-name"> lt</span><span>(</span><span class="z-constant">0xff</span><span>,</span><span class="z-entity z-name"> shr</span><span>(</span><span>r</span><span>,</span><span> x</span><span>)</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> forgefmt: disable-next-item</span></span> <span class="giallo-l"><span> r </span><span class="z-keyword">:=</span><span class="z-entity z-name"> add</span><span>(</span><span class="z-entity z-name">xor</span><span>(</span><span>r</span><span>,</span><span class="z-entity z-name"> byte</span><span>(</span><span class="z-entity z-name">and</span><span>(</span><span class="z-constant">0x1f</span><span>,</span><span class="z-entity z-name"> shr</span><span>(</span><span class="z-entity z-name">shr</span><span>(</span><span>r</span><span>,</span><span> x</span><span>)</span><span>,</span><span class="z-constant"> 0x8421084210842108cc6318c6db6d54be</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 0xf8f9f9faf9fdfafbf9fdfcfdfafbfcfef9fafdfafcfcfbfefafafcfbffffffff</span><span>)</span><span>)</span><span>,</span><span class="z-entity z-name"> iszero</span><span>(</span><span>x</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Or in Python,</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"> clz</span><span>(</span><span class="z-variable z-parameter z-function">x</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span><span class="z-string">Returns the number of zeros preceding the most significant one bit.</span><span class="z-punctuation z-definition z-string">&quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> x</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span class="z-support"> ValueError</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">clz is undefined for negative numbers</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> x</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">256</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span class="z-support"> ValueError</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">clz is undefined for numbers larger than 2**256 - 1</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> x</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"> 256</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Convert to binary string and remove any &#39;0b&#39; prefix.</span></span> <span class="giallo-l"><span> bin_str</span><span class="z-keyword"> =</span><span class="z-support"> bin</span><span>(</span><span>x</span><span>)</span><span>.</span><span>replace</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0b</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-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 256</span><span class="z-keyword"> -</span><span class="z-support"> len</span><span>(</span><span>bin_str</span><span>)</span></span></code></pre> <p>Or in C++,</p> <pre class="giallo z-code"><code data-lang="cpp"><span class="giallo-l"><span class="z-storage">inline</span><span class="z-storage z-type"> uint32_t</span><span class="z-entity z-name"> clz</span><span>(</span><span class="z-storage z-type">uint32_t</span><span class="z-variable"> x</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> uint32_t</span><span> r </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 class="z-keyword">!</span><span>(</span><span>x </span><span class="z-keyword">&amp;</span><span class="z-keyword"> 0x</span><span class="z-constant">FFFF0000</span><span>)</span><span>)</span><span> {</span><span> r </span><span class="z-keyword">+=</span><span class="z-constant"> 16</span><span>;</span><span> x </span><span class="z-keyword">&lt;&lt;=</span><span class="z-constant"> 16</span><span>;</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>(</span><span>x </span><span class="z-keyword">&amp;</span><span class="z-keyword"> 0x</span><span class="z-constant">FF000000</span><span>)</span><span>)</span><span> {</span><span> r </span><span class="z-keyword">+=</span><span class="z-constant"> 8</span><span>;</span><span> x </span><span class="z-keyword">&lt;&lt;=</span><span class="z-constant"> 8</span><span>;</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>(</span><span>x </span><span class="z-keyword">&amp;</span><span class="z-keyword"> 0x</span><span class="z-constant">F0000000</span><span>)</span><span>)</span><span> {</span><span> r </span><span class="z-keyword">+=</span><span class="z-constant"> 4</span><span>;</span><span> x </span><span class="z-keyword">&lt;&lt;=</span><span class="z-constant"> 4</span><span>;</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>(</span><span>x </span><span class="z-keyword">&amp;</span><span class="z-keyword"> 0x</span><span class="z-constant">C0000000</span><span>)</span><span>)</span><span> {</span><span> r </span><span class="z-keyword">+=</span><span class="z-constant"> 2</span><span>;</span><span> x </span><span class="z-keyword">&lt;&lt;=</span><span class="z-constant"> 2</span><span>;</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>(</span><span>x </span><span class="z-keyword">&amp;</span><span class="z-keyword"> 0x</span><span class="z-constant">80000000</span><span>)</span><span>)</span><span> {</span><span> r </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> r</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"> `x` is a uint256 bit number represented with 8 uint32 limbs.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> This implementation is optimized for SP1 proving via rv32im.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> For regular compute, it performs similarly to `ADD`.</span></span> <span class="giallo-l"><span class="z-storage">inline</span><span class="z-storage z-type"> uint32_t</span><span class="z-entity z-name"> clz</span><span>(</span><span class="z-storage z-type">uint32_t</span><span class="z-variable"> x</span><span>[</span><span class="z-constant">8</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">x</span><span>[</span><span class="z-constant">7</span><span>]</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span>)</span><span class="z-keyword"> return</span><span class="z-entity z-name"> clz</span><span>(</span><span class="z-variable z-other">x</span><span>[</span><span class="z-constant">7</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">x</span><span>[</span><span class="z-constant">6</span><span>]</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> 32</span><span class="z-keyword"> +</span><span class="z-entity z-name"> clz</span><span>(</span><span class="z-variable z-other">x</span><span>[</span><span class="z-constant">6</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">x</span><span>[</span><span class="z-constant">5</span><span>]</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> 64</span><span class="z-keyword"> +</span><span class="z-entity z-name"> clz</span><span>(</span><span class="z-variable z-other">x</span><span>[</span><span class="z-constant">5</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">x</span><span>[</span><span class="z-constant">4</span><span>]</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> 96</span><span class="z-keyword"> +</span><span class="z-entity z-name"> clz</span><span>(</span><span class="z-variable z-other">x</span><span>[</span><span class="z-constant">4</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">x</span><span>[</span><span class="z-constant">3</span><span>]</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> 128</span><span class="z-keyword"> +</span><span class="z-entity z-name"> clz</span><span>(</span><span class="z-variable z-other">x</span><span>[</span><span class="z-constant">3</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">x</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> 160</span><span class="z-keyword"> +</span><span class="z-entity z-name"> clz</span><span>(</span><span class="z-variable z-other">x</span><span>[</span><span class="z-constant">2</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">x</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 class="z-keyword"> return</span><span class="z-constant"> 192</span><span class="z-keyword"> +</span><span class="z-entity z-name"> clz</span><span>(</span><span class="z-variable z-other">x</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> (</span><span class="z-variable z-other">x</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-keyword"> return</span><span class="z-constant"> 224</span><span class="z-keyword"> +</span><span class="z-entity z-name"> clz</span><span>(</span><span class="z-variable z-other">x</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-constant"> 256</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The cost of the opcode is 5, matching MUL (raised from 3 to avoid under-pricing DoS risk).</p> <h2 id="rationale">Rationale</h2> <h3 id="the-special-0-case">The special 0 case</h3> <p>256 is the smallest number after 255. Returning a small number allows the result to be compared with minimal additional bytecode.</p> <p>For byte scanning operations, one can get the number of bytes to be skipped for a zero word by simply computing <code>256 &gt;&gt; 3</code>, which gives 32.</p> <h3 id="preference-over-ctz-count-trailing-zeros">Preference over <code>CTZ</code> (count trailing zeros)</h3> <p>Computing the least significant bit can be easily implemented with <code>CLZ</code> by isolating the smallest bit via <code>x &amp; -x</code>.</p> <p>However, it is not possible to implement <code>CLZ</code> with <code>CTZ</code>.</p> <h3 id="gas-cost">Gas cost</h3> <p>We have benchmarked the <code>CLZ</code> implementation against the <code>ADD</code> implementation in the intx library. <code>CLZ</code> uses approximately the same amount of compute cycles as <code>ADD</code>.</p> <p>The SP1 rv32im optimized variant uses less compute cycles than <code>ADD</code>, in the average and worst cases.</p> <p>In SP1 rv32im, a 256-bit <code>CLZ</code> is cheaper to prove than <code>ADD</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a new opcode 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>PUSH32 0x000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>CLZ</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000100</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH32 0x8000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>CLZ</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH32 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>CLZ</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH32 0x4000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>CLZ</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000001</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH32 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>CLZ</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000001</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH32 0x0000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>CLZ</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x00000000000000000000000000000000000000000000000000000000000000ff</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p><code>CLZ</code> is a stateless opcode that has a low worst-case constant cost in memory usage, compute and proving costs. It is therefore safe from being exploited for denial of service 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> 2025-04-23T00:00:00+00:00 2026-02-11T14:49:27+00:00 Wei Tanghttps://github.com/sorpaas https://wg-eips.ritovision.com/7937/

Multibyte opcodes for 64-bit arithmetic, comparison, bitwise and flow operations in EVM.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces multibyte opcodes prefixed by <code>C0</code> for 64-bit arithmetic (<code>C001</code>-<code>C00B</code>), comparison (<code>C010</code>-<code>C015</code>), bitwise (<code>C016</code>-<code>C019</code>) and flow (<code>C056</code> and <code>C057</code>) operations.</p> <h2 id="motivation">Motivation</h2> <p>Not all computations in EVM can utilize the full 256-bit integer width. It can therefore be beneficial to have a "64-bit mode" to avoid unnecessary cycles. This EIP uses a "prefix" opcode <code>C0</code>, essentially forming multibyte opcodes to avoid polluting the EVM opcode space too much.</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="prefix-opcode-behavior">Prefix opcode behavior</h3> <p>This EIP uses the prefix opcode <code>C0</code>, and it only occupies this single EVM opcode space. Upon the interpreter encountering opcode <code>C0</code>, it MUST continue to seek the next byte in code. It then executes things in "64-bit mode", based on the second byte, described below. If the execution is successful, then the interpreter MUST increase <code>PC</code> by 2 (instead of 1).</p> <p>If the second byte is not a valid 64-bit mode operation, then the interpreter MUST OOG.</p> <h3 id="general-64-bit-mode-behavior">General 64-bit mode behavior</h3> <p>In 64-bit mode, all operations only work on the least significant 64-bit of each stack value. The most significant 192-bit is discarded. When a result value is pushed back onto the stack, then it MUST ensures that observable effects will see that the most significant 192-bit is zero. Note that here it's not necessary for an interpreter to reset the most significant 192-bit to zero every time -- if the next opcode is still in 64-bit mode, then the most significant 192-bit is still unobservable. We discuss the full details in the "rationale" section. The interpreter only needs to reproduce the full 256-bit value upon entering non-64-bit mode. If the full computational heavy part can be written in pure 64-bit mode, then this can result in noticeable performance gain.</p> <h3 id="gas-cost-constants">Gas cost constants</h3> <p>We define the following gas cost constants:</p> <ul> <li><code>G_BASE64</code>: 1</li> <li><code>G_VERYLOW64</code>: 2</li> <li><code>G_LOW64</code>: 3</li> <li><code>G_MID64</code>: 5</li> <li><code>G_HIGH64</code>: 7</li> <li><code>G_EXP64_STATIC</code>: 5</li> <li><code>G_EXP64_DYNAMIC</code>: 25</li> </ul> <h3 id="arithmetic-opcodes">Arithmetic opcodes</h3> <p>The 64-bit mode arithmetic opcodes are defined the same as non-64-bit mode, except that it only operates on the least significant 64-bits. In the below definition, <code>a</code>, <code>b</code>, <code>N</code> is <code>a mod 2^64</code>, <code>b mod 2^64</code> and <code>N mod 2^64</code>.</p> <ul> <li>ADD (<code>C001</code>) and SUB (<code>C003</code>): <code>a op b mod 2^64</code>, gas cost <code>G_VERYLOW64</code>.</li> <li>MUL (<code>C002</code>), DIV (<code>C004</code>), SDIV (<code>C005</code>), MOD (<code>C006</code>), SMOD (<code>C007</code>), SIGNEXTEND (<code>C00B</code>): <code>a op b mod 2^64</code>, gas cost <code>G_LOW64</code>.</li> <li>ADDMOD (<code>C008</code>), MULMOD (<code>C009</code>): <code>a op b % N mod 2^64</code>, gas cost <code>G_MID64</code>.</li> <li>EXP (<code>C00A</code>): <code>a EXP b mod 2^64</code>, gas cost <code>static_gas = G_EXP64_STATIC, dynamic_gas = G_EXP64_DYNAMIC * exponent_byte_size</code>.</li> </ul> <h3 id="comparison-and-bitwise-opcodes">Comparison and bitwise opcodes</h3> <p>The 64-bit mode comparison and bitwise opcodes are defined the same as non-64-bit mode, except that they only operates on the least significant 64 bits.</p> <ul> <li>LT (<code>C010</code>), GT (<code>C011</code>), SLT (<code>C012</code>), SGT (<code>C013</code>), EQ (<code>C014</code>), AND (<code>C016</code>), OR (<code>C017</code>), XOR (<code>C018</code>): <code>a op b mod 2^64</code>, gas cost <code>G_VERYLOW64</code></li> <li>ISZERO (<code>C015</code>), NOT (<code>C019</code>): <code>op a mod 2^64</code>, gas cost <code>G_VERYLOW64</code></li> <li>SHL (<code>C01B</code>), SHR (<code>C01C</code>), SAR (<code>C01D</code>): <code>a op N mod 2^64</code>, gas cost <code>G_VERYLOW64</code></li> </ul> <p>Note that:</p> <ul> <li>64-bit EQ (<code>C014</code>) may return true for two different integers because it'll only compare the least significant 64 bits.</li> <li>64-bit ISZERO (<code>C015</code>) may return true for non-zero 256-bit integers as long as the last 64 bits are zero.</li> <li>BYTE (<code>1A</code>) does not have 64-bit mode because it affects endianness.</li> </ul> <h3 id="jump-jumpi">JUMP, JUMPI</h3> <p>For flow operations JUMP and JUMPI, the behavior is as follows:</p> <ul> <li><code>JUMP</code> (<code>C056</code>) will only read the last 64 bits from the stack value. The rest 192 bits are discarded without reading. Gas cost is <code>G_MID64</code>.</li> <li><code>JUMPI</code> (<code>C057</code>) will only read the last 64 bits from the stack as destination, and the condition check will only read the last 64 bits. Gas cost is <code>G_HIGH64</code>.</li> <li>In <code>JUMPDEST</code> validation phrase, <code>C0</code> is considered a standalone "mode" opcode and if the next byte followed is <code>JUMPDEST</code>, it continues to mark a valid <code>JUMPDEST</code> destination. Note that because there's no 64-bit <code>JUMPDEST</code>, during execution, <code>C0 JUMPDEST</code> would result in OOG.</li> </ul> <h2 id="rationale">Rationale</h2> <p>When a smart contract uses the 64-bit mode, it's expected that once entered, it will want to stay in 64-bit mode, and only exit to non-64-bit mode when the computationally intensive function is finished. This EIP is designed particularly with this fact in mind.</p> <p>All 64-bit opcodes only operates on the 64-bit value. It totally discards the rest 192 bits. The interpreter only needs to ensure that when it exits into non-64-bit mode and next time when a value result is read, that value has the first 192 bits reset to zero. The EVM interpreter can therefore use a typed stack for optimization:</p> <pre class="giallo z-code"><code data-lang="haskell"><span class="giallo-l"><span class="z-keyword">type</span><span class="z-storage z-type"> StackItem</span><span class="z-keyword"> =</span><span class="z-storage z-type"> Value</span><span class="z-storage z-type"> U256</span><span class="z-keyword"> |</span><span class="z-storage z-type"> Value64</span><span class="z-storage z-type"> U64</span></span></code></pre> <p>The typed stack can also be implemented as a bitmap for memory alignment.</p> <p>For all inputs of 64-bit opcodes, it will either read in a <code>Value</code>, when it'll only take the last 64 bits, or a <code>Value64</code>, which is what is needed. It then always outputs a <code>Value64</code>. After exiting into non-64-bit mode and upon a <code>Value64</code> is read, the interpreter then translate the value back to 256-bit <code>Value</code> by extending the first 192 bits with zero.</p> <p>The 64-bit mode does not contain any opcodes which depends on the value's endianness, therefore <code>Value64</code> can also be stored in the optimal endianness of the architecture.</p> <p>The 64-bit mode will not save any memory usage.</p> <h3 id="discussions">Discussions</h3> <h4 id="prefix-modes-opcodes">Prefix (modes) opcodes</h4> <p>This EIP also recommends that we reserve <code>C0</code>-<code>CF</code> for prefix (modes) opcodes. For example, an additional modes OVERFLOW can be envisioned that changes the behavior of arithmetic opcodes from wrapping to overflow OOG, which can help to reduce, for example, the extra cycles needed for <code>SafeMath</code>.</p> <h4 id="optimization-assumptions">Optimization assumptions</h4> <p>This EIP assumes that the majority of EVM implementations target native little-endian 64-bit architectures (like <code>x86_64</code>, <code>arm64</code> and <code>riscv64</code>). A 256-bit stack item is stored efficiently internally as 4 items of 64-bit unsigned integer <code>[u64; 4]</code>. This EIP works best, in terms of optimizations, for those implementations. The opcodes simply operates on the last <code>u64</code>, instead of the whole <code>[u64; 4]</code>. There are basically no other changes.</p> <h4 id="endianness">Endianness</h4> <p>In 64-bit mode, the principle of the specification is that the endianness should be kept strictly as an implementation detail. There should not be any opcodes that depends on endian. This is important, because on the one hand, we must enable easy and fast interop for 64-bit and non-64-bit opcodes. On the other hand, the interpreter should be able to do optimizations internally whether it uses little or big endian.</p> <p>Due to the issue of endianness, this EIP currently does not contain 64-bit mode <code>BYTE64</code>, memory opcodes <code>MLOAD64</code> and <code>MSTORE64</code>, and stack push opcodes <code>PUSH*64</code> (<code>PUSH1</code> to <code>PUSH8</code>).</p> <p>It is possible to extend EVM64 where "64-bit mode" is instead defined as "little-endian 64-bit mode", which can be separately discussed and specified:</p> <ul> <li><code>BYTE64</code> will be little-endian, so instead of <code>(x &gt;&gt; (248 - i * 8)) &amp; 0xFF</code>, it will be <code>(x &gt;&gt; i * 8) &amp; 0xFF</code>.</li> <li><code>MLOAD64</code> and <code>MSTORE64</code> loads and store little-endian 64-bit values in memory.</li> <li><code>PUSH*64</code> (<code>PUSH1</code> to <code>PUSH8</code>) accepts literal little-endian bytes.</li> </ul> <p>In specification there is no issue with the design, but this can bring significant confusions to developers. So the author advise caution.</p> <h4 id="pop-dup-swap"><code>POP</code>, <code>DUP*</code>, <code>SWAP*</code></h4> <p>There is no explicit 64-bit mode for stack operations:</p> <ul> <li><code>POP</code> is "automatically 64-bit" because it only removes values from the stack.</li> <li><code>DUP*</code> and <code>SWAP*</code> will copy or swap stack items optimized for 64-bit as is. They are kept optimized, so there's no need for separate 64-bit mode for those opcodes.</li> </ul> <h4 id="drawbacks">Drawbacks</h4> <p>Known drawbacks and tradeoffs of 64-bit mode includes:</p> <ul> <li>The binary size will become larger. This is apparent as previously the opcode is single byte, but now it is two bytes. Each byte costs an additional 200 gas to deposit. However, 64-bit mode opcodes are (generally) cheaper, which gives developers sufficient incentives to utilize it (at most 200 calls and the cumulative gas costs will be cheaper).</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces a new (prefix) opcode <code>C0</code>. <code>C0</code> was previously an invalid opcode that has little usage, and thus the backward compatibility issues are minimal.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases are organized as <code>[stack_item_1, stack_item_2] C0 opcode =&gt; [result_stack_item_1, result_stack_item_2]</code>.</p> <ul> <li><code>[ff00000000000000 000000000000000 0000000000000ff 000000000000001, ff0000000000000 000000000000000 0000000000000ff f0000000000000f] C0 SHR =&gt; [&lt;0&gt; 780000000000007]</code></li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>To be added.</p> <h2 id="security-considerations">Security Considerations</h2> <p>To be added.</p> <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-17T00:00:00+00:00 2026-02-11T14:48:25+00:00 Raphina Liuhttps://github.com/Stamp9 Monica Jinhttps://github.com/mokita-j Martin Monperrushttps://github.com/monperrus https://wg-eips.ritovision.com/7936/

Multi-version proxy contracts that allow callers to select implementation

<h2 id="abstract">Abstract</h2> <p>This EIP standardizes an interface for proxy contracts that allows callers to explicitly select which version of an implementation contract they want to interact with. Unlike traditional proxy patterns that only expose the latest implementation, this standard enables backward compatibility by maintaining access to previous implementations while supporting upgrades. The versioned proxy maintains a registry of implementation addresses mapped to version identifiers, allowing callers to specify their desired version at call time.</p> <h2 id="motivation">Motivation</h2> <p>Smart contract upgrades are essential for fixing bugs and adding features. Current proxy patterns typically force all callers to use the latest implementation, which can break existing integrations when interfaces change.</p> <p>Furthermore, traditional proxy patterns expose all users to risk if an upgrade is malicious, as they have no choice but to use the latest implementation. This standard allows users to remain on verified versions they trust, mitigating the risk of a compromised admin key or governance process deploying harmful code.</p> <p>This EIP addresses several key problems:</p> <ol> <li><strong>Breaking Changes</strong>: Interface changes in new implementations can break existing integrations.</li> <li><strong>Gradual Adoption</strong>: There is no standard way to allow gradual adoption of new contract versions.</li> <li><strong>Malicious Upgrades</strong>: Users today must trust proxy admins indefinitely, as they can't opt out of potentially harmful upgrades without ceasing use of the contract entirely.</li> <li><strong>Trust Assumptions</strong>: Contract users must maintain perpetual trust in governance or admin keys, with no ability to selectively trust specific, audited implementations.</li> </ol> <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="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"> IVersionedProxy</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 new implementation version is registered</span></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 identifier</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> implementation</span><span class="z-comment"> The address of the implementation contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> VersionRegistered</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> version</span><span>, </span><span class="z-support">address</span><span class="z-variable"> implementation</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"> Emitted when the default version 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"> oldVersion</span><span class="z-comment"> The previous default version</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> newVersion</span><span class="z-comment"> The new default version</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DefaultVersionChanged</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> oldVersion</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> newVersion</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"> Registers a new implementation version</span></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 identifier (e.g., &quot;1.0.0&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"> implementation</span><span class="z-comment"> The address of the implementation contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerVersion</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> version</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> implementation</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"> Removes a version from the 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"> version</span><span class="z-comment"> The version identifier to remove</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeVersion</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> version</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"> Sets the default version to use when no version is 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"> version</span><span class="z-comment"> The version identifier to set as default</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setDefaultVersion</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> version</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"> Gets the implementation address for a specific version</span></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 identifier</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"> implementation address for the specified version</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getImplementation</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> version</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Gets the current default version</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"> current default version identifier</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getDefaultVersion</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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Gets all registered versions</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"> array of all registered version identifiers</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getVersions</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></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Executes a call to a specific implementation version</span></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 identifier of the implementation to call</span></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 calldata to forward to the implementation</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"> return data from the implementation call</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> executeAtVersion</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> version</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-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>}</span></span></code></pre><h3 id="behavior-requirements">Behavior Requirements</h3> <ol> <li>The proxy contract MUST maintain a mapping of version identifiers to implementation addresses.</li> <li>The proxy contract MUST maintain a default version that is used when no version is specified.</li> <li>When <code>executeAtVersion</code> is called, the proxy MUST: <ul> <li>Verify the specified version exists</li> <li>Forward the call to the corresponding implementation</li> <li>Return any data returned by the implementation</li> </ul> </li> <li>The proxy contract MUST emit appropriate events when versions are registered, or when the default version changes.</li> <li>The proxy contract SHOULD implement access control for administrative functions (registering versions, setting default).</li> <li>The proxy contract MAY implement <a href="https://wg-eips.ritovision.com/1967/">EIP-1967</a> storage slots for compatibility with existing tools.</li> </ol> <h3 id="fallback-function">Fallback Function</h3> <p>The proxy contract SHOULD implement a fallback function that forwards calls to the default implementation version when no version is specified. This maintains compatibility with traditional proxy patterns.</p> <h2 id="rationale">Rationale</h2> <h3 id="version-identifiers-as-bytes32">Version Identifiers as bytes32</h3> <p>Version identifiers are specified as <code>bytes32</code> rather than semantic versioning strings to:</p> <ol> <li>Provide flexibility in versioning schemes</li> <li>Reduce gas costs for storage and comparison</li> <li>Allow for both string-based versions (converted to bytes32) and numeric versions</li> <li>Allow for storing a Git commit identifier in SHA-1 or SHA-256</li> </ol> <h3 id="explicit-version-selection">Explicit Version Selection</h3> <p>The standard requires callers to explicitly select a version through <code>executeAtVersion</code> rather than encoding version information in the call data to:</p> <ol> <li>Maintain a clean separation between version selection and function calls</li> <li>Avoid modifying existing function signatures</li> <li>Make version selection explicit and auditable</li> </ol> <h3 id="registry-pattern">Registry Pattern</h3> <p>The registry pattern was chosen over alternatives like:</p> <ol> <li><strong>Multiple Proxies</strong>: Having separate proxies for each version would increase deployment costs and complexity</li> <li><strong>Version in Storage</strong>: Storing a single "current version" would not allow different callers to use different versions simultaneously</li> </ol> <h3 id="default-version">Default Version</h3> <p>The default version mechanism allows the proxy to maintain compatibility with traditional proxy patterns and supports callers that don't need to specify a version.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is designed to enhance backward compatibility for smart contracts. It does not introduce any backward incompatibilities with existing Ethereum standards or implementations.</p> <p>Existing contracts that interact with proxy contracts can continue to do so without modification, as the fallback function will route calls to the default implementation.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP is meant to significantly improve the security of the widely used proxy pattern.</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-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Giulio Rebuffohttps://github.com/Giulio2002 Ben Adamshttps://github.com/benaadams Storm Slivkoffhttps://github.com/sslivkoff https://wg-eips.ritovision.com/7934/

Introduce a protocol-level cap on the maximum RLP-encoded block size to 10 MiB, including a 2 MiB margin for beacon block size.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a protocol-level cap on the maximum RLP-encoded execution block size to 10 megabytes (MiB), which includes a margin of 2 MiB to account for beacon block sizes.</p> <h2 id="motivation">Motivation</h2> <p>Currently, Ethereum does not enforce a strict upper limit on the encoded size of blocks. This lack of constraint can result in:</p> <ol> <li><strong>Network Instability</strong>: Extremely large blocks slow down propagation and increase the risk of temporary forks and reorgs.</li> <li><strong>DoS Risks</strong>: Malicious actors could generate exceptionally large blocks to disrupt network performance.</li> </ol> <p>Additionally, blocks exceeding 10 MiB are not propagated by the consensus layer's (CL) gossip protocol, potentially causing network fragmentation or denial-of-service (DoS) conditions.</p> <p>By imposing a protocol-level limit on the RLP-encoded block size, Ethereum can ensure enhanced resilience against targeted attacks on block validation times. Adding an additional margin of 2MiB explicitly accommodates beacon block sizes, ensuring compatibility across network components.</p> <h2 id="specification">Specification</h2> <h3 id="block-size-cap">Block Size Cap</h3> <ul> <li>Introduce constants: <ul> <li><code>MAX_BLOCK_SIZE</code> set to <strong>10 MiB (10,485,760 bytes)</strong></li> <li><code>SAFETY_MARGIN</code> set to <strong>2MiB (2,097,152 bytes)</strong></li> <li><code>MAX_RLP_BLOCK_SIZE</code> calculated as <code>MAX_BLOCK_SIZE - MARGIN</code></li> </ul> </li> <li>Any RLP-encoded block exceeding <code>MAX_RLP_BLOCK_SIZE</code> must be considered invalid.</li> </ul> <p>Thus add the following check to the Ethereum protocol:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-constant">MAX_BLOCK_SIZE</span><span class="z-keyword"> =</span><span class="z-constant"> 10_485_760</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 10 MiB</span></span> <span class="giallo-l"><span class="z-constant">SAFETY_MARGIN</span><span class="z-keyword"> =</span><span class="z-constant"> 2_097_152</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 2 MiB</span></span> <span class="giallo-l"><span class="z-constant">MAX_RLP_BLOCK_SIZE</span><span class="z-keyword"> =</span><span class="z-constant"> MAX_BLOCK_SIZE</span><span class="z-keyword"> -</span><span class="z-constant"> SAFETY_MARGIN</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 true, the block is invalid and should be rejected/not get built</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> exceed_max_rlp_block_size</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-support"> bool</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> len</span><span>(</span><span>rlp</span><span>.</span><span>encode</span><span>(</span><span>block</span><span>)</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> MAX_RLP_BLOCK_SIZE</span></span></code></pre><h3 id="changes-to-protocol-behavior">Changes to Protocol Behavior</h3> <ol> <li><strong>Block Creation</strong>: Validators must ensure the total RLP-encoded size of any produced block does not exceed <code>MAX_RLP_BLOCK_SIZE</code>.</li> <li><strong>Block Validation</strong>: Nodes must reject blocks whose RLP-encoded size exceeds <code>MAX_RLP_BLOCK_SIZE</code>.</li> </ol> <h3 id="protocol-adjustment">Protocol Adjustment</h3> <ul> <li>All Ethereum client implementations must integrate this size check as part of block validation and propagation.</li> <li>This limit applies independently of gas-related metrics.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="why-10-mib">Why 10 MiB?</h3> <p>A cap of 10 MiB aligns with the gossip protocol constraint in Ethereum's consensus layer (CL). An additional 2MiB margin explicitly accounts for beacon block sizes, ensuring compatibility and consistent block propagation across the network. Blocks significantly larger than 10 MiB will not be broadcast by the CL, potentially leading to network fragmentation or denial-of-service scenarios.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is <strong>not backward-compatible</strong> with any blocks larger than the newly specified size limit. Validators and miners will need to ensure their block construction logic strictly respects this limit.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Restricting maximum block size provides inherent protection against deliberate oversized-block 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> 2025-04-12T00:00:00+00:00 2026-02-11T14:49:27+00:00 James Kemptonhttps://github.com/SirSpudlington https://wg-eips.ritovision.com/7932/

Introduces a precompile and registry for handling alternative signature algorithms

<h2 id="abstract">Abstract</h2> <p>This EIP:</p> <ul> <li>Creates a unified registry &amp; standardized interface for introducing additional signature algorithms for the use of deriving account addresses.</li> <li>Introduces a precompile at address <code>SIGRECOVER_PRECOMPILE_ADDRESS</code> for decoding these newly introduced algorithms.</li> </ul> <h2 id="motivation">Motivation</h2> <p>As quantum computers become more advanced, several new post-quantum (PQ) algorithms have been designed. These algorithms all have certain drawbacks, such as large key sizes (&gt;1KiB), large signature sizes, or long verification times. These issues make them more expensive to compute and store than the currently used secp256k1 curve.</p> <p>This EIP allows the use of many algorithms by introducing an algorithm registry that can be used via a single interface.</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>Unless explicitly noted, integer encoding MUST be in big-endian format.</p> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>SIGRECOVER_PRECOMPILE_ADDRESS</code></td><td><code>Bytes20(0x12)</code></td></tr> <tr><td><code>SIGRECOVER_PRECOMPILE_BASE_GAS</code></td><td><code>3000</code></td></tr> </tbody></table> <h3 id="algorithm-specification">Algorithm specification</h3> <p>New algorithms beyond the <code>secp256k1</code> algorithm specified in this EIP MUST be specified via a distinct EIP.</p> <p>Each type of algorithm MUST specify the following fields:</p> <pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-storage z-type">trait</span><span class="z-entity z-name"> Algorithm</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> The algorithm type byte</span></span> <span class="giallo-l"><span class="z-constant"> ALG_TYPE</span><span class="z-keyword">:</span><span class="z-variable z-other"> uint8</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 size of signatures. Signatures MUST be padded</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> to this size to be valid. Note that this does include</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> the ALG_TYPE byte prefix</span></span> <span class="giallo-l"><span class="z-constant"> SIZE</span><span class="z-keyword">:</span><span class="z-variable z-other"> uint32</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 gas cost of signing this data. This</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> SHOULD include a reasonable minimum and MUST</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> be relative to secp256k1, i.e. 0 gas is secp256k1.</span></span> <span class="giallo-l"><span class="z-keyword"> fn</span><span class="z-entity z-name"> gas_cost</span><span>(</span><span class="z-variable z-other">signing_data</span><span class="z-keyword">:</span><span class="z-entity z-name"> Bytes</span><span>)</span><span class="z-keyword"> -&gt;</span><span class="z-entity z-name"> Uint64</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 whether the signature is valid. For some</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> algorithms, this may be a no-op. This function</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> will always be called before `verify`.</span></span> <span class="giallo-l"><span class="z-keyword"> fn</span><span class="z-entity z-name"> validate</span><span>(</span><span class="z-variable z-other">signature</span><span class="z-keyword">:</span><span class="z-entity z-name"> Bytes</span><span>)</span><span class="z-keyword"> -&gt;</span><span class="z-entity z-name"> None</span><span class="z-keyword"> |</span><span class="z-entity z-name"> Error</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"> Take the signature and signing_data and return the</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> public key of the signer.</span></span> <span class="giallo-l"><span class="z-keyword"> fn</span><span class="z-entity z-name"> verify</span><span>(</span><span class="z-variable z-other">signature</span><span class="z-keyword">:</span><span class="z-entity z-name"> Bytes</span><span>,</span><span class="z-variable z-other"> signing_data</span><span class="z-keyword">:</span><span class="z-entity z-name"> Bytes</span><span>)</span><span class="z-keyword"> -&gt;</span><span class="z-entity z-name"> Bytes</span><span class="z-keyword"> |</span><span class="z-entity z-name"> Error</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Specifications MUST include some form of security analysis on the provided algorithm and basic benchmarks justifying gas costs. Additionally, specifications MUST address malleability issues that may arise from specified algorithms.</p> <p>An example of this specification can be found <a href="https://wg-eips.ritovision.com/7932/assets/template-eip/">here</a>.</p> <h3 id="deriving-address-from-public-keys">Deriving address from public keys</h3> <p>The function below MUST be used when deriving an address from a public key:</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"> pubkey_to_address</span><span>(</span><span class="z-variable z-parameter z-function">public_key</span><span>:</span><span> Bytes</span><span>,</span><span class="z-variable z-parameter z-function"> algorithm_id</span><span>:</span><span> uint8</span><span>)</span><span> -&gt;</span><span> ExecutionAddress</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> algorithm_id</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> 0x</span><span class="z-constant">FF</span><span>:</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Compatibility shim to ensure backwards compatibility</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> ExecutionAddress</span><span>(</span><span>keccak</span><span>(</span><span>public_key</span><span>[</span><span class="z-constant">1</span><span>:</span><span>]</span><span>)</span><span>[</span><span class="z-constant">12</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"> with `||` being binary concatenation</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> ExecutionAddress</span><span>(</span><span>keccak</span><span>(</span><span>algorithm_id</span><span class="z-invalid z-illegal"> ||</span><span> public_key</span><span>)</span><span>[</span><span class="z-constant">12</span><span>:</span><span>]</span><span>)</span></span></code></pre><h3 id="algorithm-registry">Algorithm Registry</h3> <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"> AlgorithmEntry</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> ALG_TYPE</span><span>:</span><span> uint8</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> SIZE</span><span>:</span><span> uint32</span><span>,</span></span> <span class="giallo-l"><span> gas_cost</span><span>:</span><span> Callable</span><span>[</span><span>[</span><span>Bytes</span><span>]</span><span>,</span><span> uint64</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> validate</span><span>:</span><span> Callable</span><span>[</span><span>[</span><span>Bytes</span><span>]</span><span>,</span><span class="z-constant"> None</span><span class="z-keyword"> |</span><span> Error</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> verify</span><span>:</span><span> Callable</span><span>[</span><span>[</span><span>Bytes</span><span>,</span><span> Bytes</span><span>]</span><span>,</span><span> Bytes</span><span class="z-keyword"> |</span><span> Error</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>algorithm_registry</span><span>:</span><span> Dict</span><span>[</span><span>uint8</span><span>,</span><span> AlgorithmEntry</span><span>]</span></span></code></pre> <p>This EIP uses the <code>algorithm_registry</code> object to signify algorithms that have been included within a hard fork.</p> <p>A living EIP MAY be created on finalization of this EIP to track currently active algorithms across forks.</p> <p>The algorithm type is reserved <code>0xFE</code> as invalid / missing.</p> <h3 id="helper-functions">Helper functions</h3> <p>The following helper functions are defined for convenience:</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"> calculate_penalty</span><span>(</span><span class="z-variable z-parameter z-function">algorithm</span><span>:</span><span> uint8</span><span>,</span><span class="z-variable z-parameter z-function"> signing_data</span><span>:</span><span> Bytes</span><span>)</span><span> -&gt;</span><span> uint</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> algorithm</span><span class="z-keyword"> in</span><span> algorithm_registry</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> algorithm</span><span class="z-keyword"> =</span><span> algorithm_registry</span><span>[</span><span>algorithm</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> algorithm</span><span>.</span><span>gas_cost</span><span>(</span><span>signing_data</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"> validate_signature</span><span>(</span><span class="z-variable z-parameter z-function">signature</span><span>:</span><span> Bytes</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>signature</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> signature</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> in</span><span> algorithm_registry</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> algorithm</span><span class="z-keyword"> =</span><span> algorithm_registry</span><span>[</span><span>signature</span><span>[</span><span class="z-constant">0</span><span>]</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> algorithm</span><span>.</span><span>validate</span><span>(</span><span>signature</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 function cannot be called without prior calling `validate_signature(signature)`</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> verify_signature</span><span>(</span><span class="z-variable z-parameter z-function">signing_data</span><span>:</span><span> Bytes</span><span>,</span><span class="z-variable z-parameter z-function"> signature</span><span>:</span><span> Bytes</span><span>)</span><span> -&gt;</span><span> Bytes</span><span>:</span></span> <span class="giallo-l"><span> algorithm</span><span class="z-keyword"> =</span><span> algorithm_registry</span><span>[</span><span>signature</span><span>[</span><span class="z-constant">0</span><span>]</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> algorithm</span><span>.</span><span>verify</span><span>(</span><span>signature</span><span>,</span><span> signing_data</span><span>)</span></span></code></pre><h3 id="secp256k1-algorithm"><code>secp256k1</code> algorithm</h3> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-constant">ALG_TYPE</span><span class="z-keyword"> =</span><span class="z-storage z-type"> 0x</span><span class="z-constant">FF</span></span> <span class="giallo-l"><span class="z-constant">SIZE</span><span class="z-keyword"> =</span><span class="z-constant"> 66</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-constant">SECP256K1_SIGNATURE_SIZE</span><span class="z-keyword"> =</span><span class="z-constant"> SIZE</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"> secp256k1_unpack</span><span>(</span><span class="z-variable z-parameter z-function">signature</span><span>:</span><span> ByteVector</span><span>[</span><span class="z-constant">SECP256K1_SIGNATURE_SIZE</span><span>]</span><span>)</span><span> -&gt;</span><span> tuple</span><span>[</span><span>uint256</span><span>,</span><span> uint256</span><span>,</span><span> uint8</span><span>]</span><span>:</span></span> <span class="giallo-l"><span> r</span><span class="z-keyword"> =</span><span> uint256</span><span>.</span><span>from_bytes</span><span>(</span><span>signature</span><span>[</span><span class="z-constant">0</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> s</span><span class="z-keyword"> =</span><span> uint256</span><span>.</span><span>from_bytes</span><span>(</span><span>signature</span><span>[</span><span class="z-constant">32</span><span>:</span><span class="z-constant">64</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> y_parity</span><span class="z-keyword"> =</span><span> signature</span><span>[</span><span class="z-constant">64</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>r</span><span>,</span><span> s</span><span>,</span><span> y_parity</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"> secp256k1_validate</span><span>(</span><span class="z-variable z-parameter z-function">signature</span><span>:</span><span> ByteVector</span><span>[</span><span class="z-constant">SECP256K1_SIGNATURE_SIZE</span><span>]</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> SECP256K1N</span><span class="z-keyword"> =</span><span class="z-storage z-type"> 0x</span><span class="z-constant">fffffffffffffffffffffffffffffffebaaedce6af48a03bbfd25e8cd0364141</span></span> <span class="giallo-l"><span> r</span><span>,</span><span> s</span><span>,</span><span> y_parity</span><span class="z-keyword"> =</span><span> secp256k1_unpack</span><span>(</span><span>signature</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-constant"> 0</span><span class="z-keyword"> &lt;</span><span> r</span><span class="z-keyword"> &lt;</span><span class="z-constant"> SECP256K1N</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-constant"> 0</span><span class="z-keyword"> &lt;</span><span> s</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> SECP256K1N</span><span class="z-keyword"> //</span><span class="z-constant"> 2</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> y_parity</span><span class="z-keyword"> in</span><span> (</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 1</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"> gas_cost</span><span>(</span><span class="z-variable z-parameter z-function">signing_data</span><span>:</span><span> Bytes</span><span>)</span><span> -&gt;</span><span> Uint64</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> This is an adaptation from the KECCAK256 opcode</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>signing_data</span><span>)</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> 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> minimum_word_size</span><span class="z-keyword"> =</span><span> (</span><span class="z-support">len</span><span>(</span><span>signing_data</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"> 32</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> Uint64</span><span>(</span><span class="z-constant">30</span><span class="z-keyword"> +</span><span> (</span><span class="z-constant">6</span><span class="z-keyword"> *</span><span> minimum_word_size</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"> validate</span><span>(</span><span class="z-variable z-parameter z-function">signature</span><span>:</span><span> Bytes</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span class="z-keyword"> |</span><span> Error</span><span>:</span></span> <span class="giallo-l"><span> secp256k1_validate</span><span>(</span><span>signature</span><span>[</span><span class="z-constant">1</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"> verify</span><span>(</span><span class="z-variable z-parameter z-function">signature</span><span>:</span><span> Bytes</span><span>,</span><span class="z-variable z-parameter z-function"> signing_data</span><span>:</span><span> Bytes</span><span>)</span><span> -&gt;</span><span> Bytes</span><span class="z-keyword"> |</span><span> Error</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Another compatibility shim to ensure passing a 32 byte hash still works.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>signing_data</span><span>)</span><span class="z-keyword"> !=</span><span class="z-constant"> 32</span><span>:</span></span> <span class="giallo-l"><span> signing_data</span><span class="z-keyword"> =</span><span> keccak256</span><span>(</span><span>signing_data</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> ecdsa</span><span class="z-keyword"> =</span><span> ECDSA</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> recover_sig</span><span class="z-keyword"> =</span><span> ecdsa</span><span>.</span><span>ecdsa_recoverable_deserialize</span><span>(</span><span>signature</span><span>[</span><span class="z-constant">1</span><span>:</span><span class="z-constant">65</span><span>]</span><span>,</span><span> signature</span><span>[</span><span class="z-constant">65</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> public_key</span><span class="z-keyword"> =</span><span> PublicKey</span><span>(</span><span>ecdsa</span><span>.</span><span>ecdsa_recover</span><span>(</span><span>signing_data</span><span>,</span><span> recover_sig</span><span>,</span><span class="z-variable"> raw</span><span class="z-keyword">=</span><span class="z-constant">True</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> uncompressed</span><span class="z-keyword"> =</span><span> public_key</span><span>.</span><span>serialize</span><span>(</span><span class="z-variable">compressed</span><span class="z-keyword">=</span><span class="z-constant">False</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> uncompressed</span></span></code></pre><h3 id="sigrecover-precompile"><code>sigrecover</code> precompile</h3> <p>This EIP also introduces a new precompile located at <code>SIGRECOVER_PRECOMPILE_ADDRESS</code>.</p> <p>This precompile MUST charge <code>SIGRECOVER_PRECOMPILE_BASE_GAS</code> static gas before executing.</p> <p>The precompile MUST output the 20-byte address of the signer provided left padded to 32 bytes. Callers MUST assume all zero bytes as a failure. On failure, the precompile MUST return 32 <code>0x00</code> bytes.</p> <p>The precompile is defined 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"> sigrecover_precompile</span><span>(</span><span class="z-variable z-parameter z-function">input</span><span>:</span><span> Bytes</span><span>)</span><span> -&gt;</span><span> Bytes</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span class="z-support">input</span><span>)</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> input</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> in</span><span> algorithm_registry</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> size</span><span class="z-keyword"> =</span><span> algorithm_registry</span><span>[</span><span class="z-support">input</span><span>[</span><span class="z-constant">0</span><span>]</span><span>]</span><span>.</span><span class="z-constant">SIZE</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span class="z-support">input</span><span>)</span><span class="z-keyword"> &gt;</span><span> size</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> signature</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span>:</span><span>size</span><span>]</span></span> <span class="giallo-l"><span> signing_data</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span>size</span><span>:</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> charge_gas</span><span>(</span><span>calculate_penalty</span><span>(</span><span class="z-support">input</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span> signing_data</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"> Run validate/verify function</span></span> <span class="giallo-l"><span> validate_signature</span><span>(</span><span>signature</span><span>)</span></span> <span class="giallo-l"><span> pubkey</span><span class="z-keyword"> =</span><span> verify_signature</span><span>(</span><span>signing_data</span><span>,</span><span> signature</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"> Return address left-padded to 32 bytes</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</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-keyword"> *</span><span class="z-constant"> 12</span><span>)</span><span class="z-keyword"> +</span><span> pubkey_to_address</span><span>(</span><span>pubkey</span><span>,</span><span class="z-support"> input</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="erc-4337-interoperability">ERC-4337 interoperability</h3> <p>While initial drafts of this EIP were competing with ERC-4337, current versions of this EIP support it via the sigrecover precompile. This allows any ERC-4337 implementation to have the same signature verification logic and address derivation logic for any given private key. This also works agnostic of whatever algorithm derives the address.</p> <h3 id="precompile-over-native-evm-code">Precompile over native EVM code</h3> <p>Having a precompile allows non-EVM processes, i.e. transaction level signature verification, to access the registry <em>without</em> having to call into the EVM.</p> <h3 id="opaque-signature-type">Opaque <code>signature</code> type</h3> <p>As each algorithm has unique properties, e.g. supporting signature recovery and key sizes, the object needs to hold every permutation of every possible signature and potentially additional recovery information. A bytearray of an algorithm-defined size would be able to achieve this goal.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>EIP-7932 does not modify any existing logic and does not pose any backwards compatibility issues.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases for the <code>sigrecover</code> precompile may be found in the <a href="https://wg-eips.ritovision.com/7932/./assets/precompile_test_cases.py">precompile_test_cases.py</a> file.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Allowing more ways to derive addresses for a single account may decrease overall security for that specific account. However, this is partially mitigated by the increase in processing power required to trial all algorithms. Even still, adding additional algorithms may need further discussion to ensure that the security of the network would not be compromised.</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-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Mihai Onilahttps://github.com/MihaiORO Nick Zemanhttps://github.com/NickZCZ Narcis Cotaiehttps://github.com/NarcisCRO https://wg-eips.ritovision.com/7929/

Asset-bound Tokens (ABT) permanently bound to another token, known as PermaLink-ABTs.

<h2 id="abstract">Abstract</h2> <p>This standard introduces a subclass of tokens known as <strong>PermaLink Asset Bound Tokens (PermaLink-ABTs)</strong>. They are a specific implementation of the broader <strong>Asset Bound Token (ABT)</strong> concept. ABTs establish a novel ownership paradigm where <strong>an asset can own another asset</strong>, enabling composable, nested, and portfolio-like token structures that evolve together over time.</p> <p>PermaLink-ABTs implement a permanent binding mechanism where a token in one smart contract is irreversibly linked to a token in another contract. These links mirror key state data such as <code>ownerOf</code>, <code>tokenId</code>, <code>totalSupply</code>, and <code>balanceOf</code> using the <code>assetBoundContract</code> interface. Traditional token transfer and approval functions are omitted to enforce immutability and structural cohesion between bound assets.</p> <p>Instead of utilizing a <code>mint</code> function, PermaLink-ABTs employ a <code>reveal</code> mechanism that activates tokens from a predefined supply. This approach enables permissionless binding and significantly reduces gas costs. A single token can have multiple PermaLink-ABTs bound to it, acting as multiple subordinate assets, forming a unified, transferable unit that simplifies asset mobility across digital identities, NFTs, and real-world assets (RWAs).</p> <p>By encouraging asset composability over competition, PermaLink-ABTs introduce a dynamic, future-proof model for on-chain asset evolution.</p> <h2 id="motivation">Motivation</h2> <p>Traditional ownership models on Ethereum are inherently limited. Only externally owned accounts (EOAs) or smart contracts can own blockchain assets. This creates rigidity, especially as the blockchain ecosystem expands to include digital identities, tokenized real-world assets (RWAs), and NFTs. Current smart contracts are static in nature, meaning once deployed, they cannot adapt to evolving systems, unforeseen use cases, or new integration layers. There is a need for a more flexible and modular ownership model that allows for dynamic interactions between assets.</p> <p>This standard proposes <strong>Asset Bound Tokens (ABTs)</strong> as a solution to this challenge. ABTs allow one token to be permanently bound to another across contracts, creating a dynamic, flexible, and composable ownership model. By enabling tokens to move and evolve together, ABTs pave the way for new possibilities in the on-chain economy. The following use cases illustrate why ABTs are needed:</p> <ol> <li> <p><strong>On-Chain Identity Systems</strong><br /> Governments and institutions worldwide are piloting or implementing blockchain-based identity systems, digital passports, national IDs, and verifiable credentials such as with the ongoing European Blockchain Services Infrastructure (EBSI) initiatives. These systems often require credentials to be linked across multiple registries (e.g., healthcare, banking, voting). ABTs enable the binding of identity-linked tokens into a cohesive unit, so they move together instead of requiring manual coordination and transfers. This ensures that identity-linked assets remain interconnected and dynamic, making it easier to manage and update linked data as users interact with various systems.</p> </li> <li> <p><strong>Real-World Asset (RWA) Ownership Structures</strong><br /> Tokenized businesses and assets (e.g., land, equipment, commodities) need flexible ownership models. These dynamic—businesses acquire, divest, and restructure their holdings and various assets. ABTs allow contracts to represent complex, evolving ownership hierarchies, where nested assets follow changes in their parent entity’s structure (e.g., a farming company acquiring new land or an IT firm merging with another and inheriting intellectual property). ABTs ensure businesses can efficiently manage and transfer assets on-chain without the constraints of rigid smart contracts.</p> </li> <li> <p><strong>Manufacturing and Supply Chain Management</strong><br /> Supply chains involve multiple layers of assets: raw materials → parts → products → packaging → containers. Blockchain’s transparency is invaluable, but traditional methods of creating individual tokens or smart contracts for each stage are inefficient and costly. ABTs streamline this by linking tokens across the supply chain, allowing them to be aggregated when products are built up (e.g., shoes packed in boxes, boxes placed on pallets, pallets loaded into containers) and broken down as they move through different stages (e.g., containers unloaded, pallets split, boxes unpacked). This dynamic linking and unlinking reduce redundancy, maintain transparent immutable records, and ensure seamless tracking while minimizing gas costs. By enabling the efficient flow of assets throughout the supply chain, ABTs help reduce complexity and provide a cohesive, real-time view of the entire process.</p> </li> <li> <p><strong>NFT Ecosystem Optimization</strong><br /> NFT projects often expand by launching secondary collections (e.g., additional editions, special releases). Without ABTs, this leads to fragmented value and user confusion as older and newer assets compete. ABTs allow new NFTs to be bound to originals, enhancing their value while maintaining a unified ecosystem. This strengthens liquidity and preserves market metrics, ensuring that the value of the original collection is retained and supported by the newer assets, thus benefiting both creators and collectors.</p> </li> <li> <p><strong>New Opportunities for Creators</strong><br /> ABTs empower creators to build on top of existing assets permissionlessly without needing ownership of or permission from the original smart contract. This enables a new wave of creative expression, where artists can augment and enhance NFTs (e.g., adding new visuals, audio, or interactive layers) and collaborate on existing collections. Such contributions can generate new revenue streams through shared royalties, consignment, or collaborative upgrades. Owners benefit as well, since bound enhancements can increase the inherent value of their holdings, particularly in projects involving established creators or cross-collection collaborations.</p> </li> </ol> <p>In essence, ABTs introduce a framework where tokens are linked rather than owned. This allows for dynamic and evolving asset systems, where assets move together in harmony. If a binding token moves, all associated ABTs move with it, ensuring seamless updates and reducing the need for manual transfers. This innovation transforms traditional smart contracts from static repositories into living, evolving systems capable of adapting to changing use cases, technologies, and business models.</p> <p>The <strong>PermaLink-ABTs</strong> implementation takes the ABT model further by enforcing a permanent binding between one token and another—whether it's another ABT, NFT or NFKBT. This permanent binding ensures that tokens can be transferred as a single unit, reducing complexity and gas fees. Instead of relying on traditional minting, PermaLink-ABTs use a <code>reveal</code> mechanism, activating tokens from a predefined supply. This reduces gas costs and encourages efficient linking of assets, enabling greater composability across multiple sectors.</p> <p>PermaLink-ABTs consolidate asset value by allowing multiple subordinate tokens to be linked to a single binding token, providing enhanced composability and reducing fragmentation. By requiring only the binding token to be transferred, all associated assets move in sync, making it easier to manage portfolios and move groups of assets together. This approach fosters collaboration, value accrual, and compatibility across ecosystems, whether for digital identities, RWAs, NFTs, or other on-chain assets.</p> <h2 id="specification">Specification</h2> <h3 id="ierc7929-token-interface"><code>IERC7929</code> (Token Interface)</h3> <p><strong>NOTES</strong>:</p> <ul> <li>The following specifications use syntax from Solidity <code>0.8.27</code> (or above)</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"> IERC7929</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AssetBoundContractSet</span><span>(</span><span class="z-support">address</span><span class="z-variable"> assetBoundContract</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"> 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 class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenExists</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 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"> 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"> 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></span></code></pre><h3 id="events">Events</h3> <h4 id="assetboundcontractset-event"><code>AssetBoundContractSet</code> Event</h4> <p>Emitted when the contract is deployed and bound to <code>assetBoundContract</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"> AssetBoundContractSet</span><span>(</span><span class="z-support">address</span><span class="z-variable"> assetBoundContract</span><span>)</span><span>;</span></span></code></pre><h3 id="functions">Functions</h3> <p>The functions detailed below MUST be implemented.</p> <h4 id="ownerof"><code>ownerOf</code></h4> <p>Returns the owner of the NFT specified by the <code>tokenId</code>. Will read from the <code>assetBoundContract</code> the owner and return it.</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"> 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></code></pre><h4 id="tokenexists"><code>tokenExists</code></h4> <p>Returns true if the token read from the <code>assetBoundContract</code> exists. Tokens usually start existing when minted and stop existing when burned.</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"> tokenExists</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></code></pre><h4 id="totalsupply"><code>totalSupply</code></h4> <p>Gets the total amount of tokens stored by the assetBoundContract</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"> 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><h4 id="balanceof"><code>balanceOf</code></h4> <p>Returns the number of NFTs in the assetBoundContract that an owner 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"> 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></code></pre><h3 id="ierc7929reveal-optional-token-interface"><code>IERC7929Reveal</code> (Optional Token Interface)</h3> <p><strong>NOTES</strong>:</p> <ul> <li>The following specifications use syntax from Solidity <code>0.8.27</code> (or above)</li> <li>The Reveal extension is OPTIONAL for <a href="https://wg-eips.ritovision.com/7929/">ERC-7929</a> contracts</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"> IERC7929Reveal</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7929</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenRevealed</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-storage z-type"> function</span><span class="z-entity z-name"> reveal</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"> tokenIds</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></code></pre><h3 id="events-1">Events</h3> <h4 id="tokenrevealed-event"><code>TokenRevealed</code> Event</h4> <p>Emitted when the <code>tokenId</code> is revealed</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"> TokenRevealed</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span>;</span></span></code></pre><h3 id="functions-1">Functions</h3> <p>The functions detailed below MUST be implemented.</p> <h3 id="reveal"><code>reveal</code></h3> <p>The <code>reveal</code> function should be implemented to allow pre-allocated tokens to be activated on demand.<br /> This method reduces gas consumption compared to traditional minting and simplifies token activation mechanics.</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"> reveal</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"> tokenIds</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The design of PermaLink-ABTs centers around the goal of enabling permanent token binding while optimizing for gas efficiency, composability, and secure ownership structures. We adopted the <code>assetBoundContract</code> interface to mirror essential metadata such as <code>ownerOf</code>, <code>tokenId</code>, <code>totalSupply</code>, and <code>balanceOf</code> from the binding token’s contract. This ensures that PermaLink-ABTs remain synchronized with the asset they are bound to, without duplicating logic or requiring manual updates. The mirroring also ensures traceability and visibility across contracts, allowing observers and off-chain systems to reliably interpret the token relationship. To preserve the permanent nature of the bond, standard <code>transfer</code> and <code>approve</code> methods are omitted. This immutability guarantees that PermaLink-ABTs cannot be separated from their bound asset once revealed. If the primary token moves, all attached PermaLink-ABTs move with it. This behavior supports composability, value aggregation, and consistent ownership logic.</p> <p>An alternative considered was allowing flexible transfer mechanics via opt-in transfer functions or whitelisting. However, this introduced unnecessary complexity and undermined the core principle of permanence. It also increased the risk of token desynchronization, accidental fragmentation, and security vulnerabilities in contract implementations. By contrast, the current design provides a simpler and more robust foundation.</p> <p>By implementing an <strong>optional</strong> <code>reveal</code> function in place of a traditional <code>mint</code> function it reduce gas costs and simplifies on-chain state changes for both the deployer and owner of the token having an ABT bound to it. Unlike minting, which creates tokens at runtime and incurs higher gas fees, the <code>reveal</code> function maps pre-allocated tokens stored in an array or mapping. This allows tokens to be activated on demand without the overhead of dynamic token creation. As a result, token issuers can prepare and store an entire supply in advance, with users later revealing and binding tokens when needed. This approach aligns with the use case of portfolio binding and asset hierarchies, where large numbers of tokens may need to be activated and bound efficiently.</p> <p>PermaLink-ABTs enforce strict one-way binding with immutable relationships, making them especially suitable for use cases like identity systems, real-world asset (RWA) structures, and portfolio-locked NFTs. They act as permanently attached extensions to existing tokens, reducing complexity and avoiding redundant contract logic. This approach also provides a cleaner and more secure way to augment existing assets while maintaining compatibility across various blockchain use cases. This standard is intentionally minimal to ensure wide compatibility and flexibility. Developers can extend the base logic for specialized use cases, such as embedding royalty splits, upgrade paths, or linking to dynamic data feeds, without altering the underlying PermaLink mechanism.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="erc7929-token-implementation"><code>ERC7929</code> (Token implementation)</h3> <p><strong>NOTES</strong>:</p> <ul> <li>The interface ID is (<code>0x0b76916c</code>)</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> <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"> ERC7929</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span>, </span><span class="z-entity z-name">ERC721Enumerable</span><span>, </span><span class="z-entity z-name">Ownable</span><span>, </span><span class="z-entity z-name">IERC7929</span><span> {</span></span> <span class="giallo-l"><span> ERC721Enumerable </span><span class="z-storage z-type">public</span><span> assetBoundContract</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 class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _assetBoundContract</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 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 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> assetBoundContract </span><span class="z-keyword">=</span><span class="z-entity z-name"> ERC721Enumerable</span><span>(</span><span>_assetBoundContract</span><span>)</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"> AssetBoundContractSet</span><span>(</span><span>_assetBoundContract</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"> //</span><span class="z-comment"> region EIP-165 Implementation</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"> See {IERC165-supportsInterface}.</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> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-variable"> interfaceId</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-storage z-type"> virtual</span><span class="z-storage z-type"> override</span><span>(</span><span class="z-entity z-name">ERC721Enumerable</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>IERC7929</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-comment"> ///</span><span class="z-comment">////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> endregion</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">////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> region Modifiers</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"> modifier</span><span class="z-entity z-name"> tokensMustExist</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"> tokenIds</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> tokenIds</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-keyword"> require</span><span>(</span><span class="z-entity z-name">tokenExists</span><span>(</span><span>tokenIds</span><span>[</span><span>i</span><span>]</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC7929: Token does not exist&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">////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> endregion Modifiers</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">////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> region mirror functions</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"> ownerOf</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> <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><span class="z-entity z-name">ERC721</span><span>,</span><span class="z-entity z-name"> IERC7929</span><span>,</span><span class="z-entity z-name"> IERC721</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> assetBoundContract</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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenExists</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-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> assetBoundContract</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-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-storage z-type"> function</span><span class="z-entity z-name"> totalSupply</span><span>(</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><span class="z-entity z-name">ERC721Enumerable</span><span>,</span><span class="z-entity z-name"> IERC7929</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> returns</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> assetBoundContract</span><span>.</span><span class="z-entity z-name">totalSupply</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"> balanceOf</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 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><span class="z-entity z-name">ERC721</span><span>,</span><span class="z-entity z-name"> IERC7929</span><span>,</span><span class="z-entity z-name"> IERC721</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> returns</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> assetBoundContract</span><span>.</span><span class="z-entity z-name">balanceOf</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-comment"> ///</span><span class="z-comment">////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">endregion</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">////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">region Disabling approve and transfer functions to prevent transfers of ABT tokens</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>,</span><span class="z-support"> uint256</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</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"> IERC721</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span class="z-string">&quot;ERC7929: Approvals not allowed&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"> setApprovalForAll</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"> bool</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</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"> IERC721</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span class="z-string">&quot;ERC7929: Approvals not allowed&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"> transferFrom</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>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</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"> IERC721</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span class="z-string">&quot;ERC7929: Transfers not allowed&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"> safeTransferFrom</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>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</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"> IERC721</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> safeTransferFrom</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;&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"> safeTransferFrom</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>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</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"> IERC721</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span class="z-string">&quot;ERC7929: Transfers not allowed&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-comment"> ///</span><span class="z-comment">////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">endregion</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment">////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="ierc7929reveal-token-implementation"><code>IERC7929Reveal</code> (Token implementation)</h3> <p><strong>NOTES</strong>:</p> <ul> <li>This is an OPTIONAL extension for <a href="https://wg-eips.ritovision.com/7929/">ERC-7929</a> contracts</li> <li>The interface ID is (<code>0xb93f208a</code>)</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> <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"> ERC7929Reveal</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC7929</span><span>, </span><span class="z-entity z-name">IERC7929Reveal</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"> bool</span><span>)</span><span class="z-storage z-type"> public</span><span> isRevealed</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 class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _assetBoundContract</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 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 class="giallo-l"><span> )</span><span class="z-entity z-name"> ERC7929</span><span>(</span><span>_assetBoundContract, _name, _symbol) </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"> //</span><span class="z-comment"> region EIP-165 Implementation</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"> See {IERC165-supportsInterface}.</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> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-variable"> interfaceId</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-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> <span class="giallo-l"><span> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC7929Reveal</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-comment"> ///</span><span class="z-comment">////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> endregion</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">////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> region Modifiers</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"> modifier</span><span class="z-entity z-name"> tokensMustNotBeRevealed</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"> tokenIds</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> tokenIds</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-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span class="z-keyword"> !</span><span>isRevealed</span><span>[</span><span>tokenIds</span><span>[</span><span>i</span><span>]</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;ERC7929: Token already revealed&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-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">////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> endregion Modifiers</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">////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> region mirror functions</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"> ownerOf</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"> 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">ERC7929</span><span>,</span><span class="z-entity z-name"> IERC7929</span><span>)</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-variable z-language"> super</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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenExists</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"> 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">ERC7929</span><span>,</span><span class="z-entity z-name"> IERC7929</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">tokenExists</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"> totalSupply</span><span>(</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"> override</span><span>(</span><span class="z-entity z-name">ERC7929</span><span>,</span><span class="z-entity z-name"> IERC7929</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> returns</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 class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">totalSupply</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"> balanceOf</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 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">ERC7929</span><span>,</span><span class="z-entity z-name"> IERC7929</span><span>)</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 class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">balanceOf</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-comment"> ///</span><span class="z-comment">////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">endregion</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">////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">region Reveal function to reveal the token URI for a given token ID(s)</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"> reveal</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"> tokenIds</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"> payable</span></span> <span class="giallo-l"><span class="z-storage z-type"> virtual</span></span> <span class="giallo-l"><span class="z-entity z-name"> tokensMustExist</span><span>(</span><span class="z-entity z-name">tokenIds</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> tokensMustNotBeRevealed</span><span>(</span><span class="z-entity z-name">tokenIds</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-support">uint256</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> tokenIds</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> isRevealed</span><span>[</span><span>tokenIds</span><span>[</span><span>i</span><span>]</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> TokenRevealed</span><span>(</span><span>tokenIds</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> }</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"> //</span><span class="z-comment">endregion</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment">////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span>}</span><span> </span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>PermaLink-ABTs are linked to another non-fungible token. If an individual loses access to this token, what we call the <strong>binding token</strong>, they also lose access to all PermaLink-ABTs that have been bound to it. This introduces a critical security consideration: the entire value of bound assets depends on the integrity and availability of the binding token.</p> <p>To mitigate this risk, we strongly recommend the use of standards like <a href="https://wg-eips.ritovision.com/6809/">ERC-6809</a>, a <strong>Non-Fungible Key Bound Token</strong>, which introduces on-chain two-factor authentication (2FA). ERC-6809 allows a user to bind sensitive tokens (like PermaLink-ABTs) to a secured identity layer, complete with recovery mechanisms. In the event that a user loses access to their original wallet or interacts with a malicious contract, ERC-6809 provides a safeFallback function to re-establish control.</p> <p>In essence, all of the security guarantees of ERC-6809 extend to any PermaLink-ABTs bound to it. This layered security model not only protects against loss but also ensures recoverability and long-term viability for high-value bound assets. It is strongly encouraged that developers implementing PermaLink-ABTs integrate this or similar standards to provide a robust security foundation for users.</p> <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-31T00:00:00+00:00 2026-02-11T14:49:27+00:00 Toni Wahrstätterhttps://github.com/nerolation Dankrad Feisthttps://github.com/dankrad Francesco D`Amatohttps://github.com/fradamt Jochem Brouwerhttps://github.com/jochem-brouwer Ignacio Hagopianhttps://github.com/jsign https://wg-eips.ritovision.com/7928/

Enforced block access lists with state locations and post-transaction state diffs

<h2 id="abstract">Abstract</h2> <p>This EIP introduces Block-Level Access Lists (BALs) that record all accounts and storage locations accessed during block execution, along with their post-execution values. BALs enable parallel disk reads, parallel transaction validation, parallel state root computation and executionless state updates.</p> <h2 id="motivation">Motivation</h2> <p>Transaction execution cannot be parallelized without knowing in advance which addresses and storage slots will be accessed. While <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> introduced optional transaction access lists, they are not enforced.</p> <p>This proposal enforces access lists at the block level, enabling:</p> <ul> <li>Parallel disk reads and transaction execution</li> <li>Parallel post-state root calculation</li> <li>State reconstruction without executing transactions</li> <li>Reduced execution time to <code>parallel IO + parallel EVM</code></li> </ul> <h2 id="specification">Specification</h2> <h3 id="block-structure-modification">Block Structure Modification</h3> <p>We introduce a new field to the block header, <code>block_access_list_hash</code>, which contains the Keccak-256 hash of the RLP-encoded block access list. When no state changes are present, this field is the hash of an empty RLP list <code>0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347</code>, i.e. <code>keccak256(rlp.encode([]))</code>.</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"> 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 class="z-constant"> ...</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> block_access_list_hash</span><span>:</span><span> Hash32</span><span class="z-keyword"> =</span><span> keccak256</span><span>(</span><span>rlp</span><span>.</span><span>encode</span><span>(</span><span>block_access_list</span><span>)</span><span>)</span></span></code></pre> <p>The <code>BlockAccessList</code> is not included in the block body. The EL stores BALs separately and transmits them as a field in the <code>ExecutionPayload</code> via the engine API. The BAL is RLP-encoded as a list of <code>AccountChanges</code>. When no state changes are present, this field is the empty RLP list <code>0xc0</code>, i.e. <code>rlp.encode([])</code>.</p> <h3 id="rlp-data-structures">RLP Data Structures</h3> <p>BALs use RLP encoding following the pattern: <code>address -&gt; field -&gt; block_access_index -&gt; change</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"> Type aliases for RLP encoding</span></span> <span class="giallo-l"><span>Address</span><span class="z-keyword"> =</span><span> bytes20</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 20-byte Ethereum address</span></span> <span class="giallo-l"><span>StorageKey</span><span class="z-keyword"> =</span><span> uint256</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Storage slot key</span></span> <span class="giallo-l"><span>StorageValue</span><span class="z-keyword"> =</span><span> uint256</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Storage value</span></span> <span class="giallo-l"><span>Bytecode</span><span class="z-keyword"> =</span><span class="z-support"> bytes</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Variable-length contract bytecode</span></span> <span class="giallo-l"><span>BlockAccessIndex</span><span class="z-keyword"> =</span><span> uint16</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Block access index (0 for pre-execution, 1..n for transactions, n+1 for post-execution)</span></span> <span class="giallo-l"><span>Balance</span><span class="z-keyword"> =</span><span> uint256</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Post-transaction balance in wei</span></span> <span class="giallo-l"><span>Nonce</span><span class="z-keyword"> =</span><span> uint64</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Account 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"> Core change structures (RLP encoded as lists)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> StorageChange: [block_access_index, new_value]</span></span> <span class="giallo-l"><span>StorageChange</span><span class="z-keyword"> =</span><span> [</span><span>BlockAccessIndex</span><span>,</span><span> StorageValue</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"> BalanceChange: [block_access_index, post_balance]</span></span> <span class="giallo-l"><span>BalanceChange</span><span class="z-keyword"> =</span><span> [</span><span>BlockAccessIndex</span><span>,</span><span> Balance</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"> NonceChange: [block_access_index, new_nonce]</span></span> <span class="giallo-l"><span>NonceChange</span><span class="z-keyword"> =</span><span> [</span><span>BlockAccessIndex</span><span>,</span><span> Nonce</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"> CodeChange: [block_access_index, new_code]</span></span> <span class="giallo-l"><span>CodeChange</span><span class="z-keyword"> =</span><span> [</span><span>BlockAccessIndex</span><span>,</span><span> Bytecode</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"> SlotChanges: [slot, [changes]]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> All changes to a single storage slot</span></span> <span class="giallo-l"><span>SlotChanges</span><span class="z-keyword"> =</span><span> [</span><span>StorageKey</span><span>,</span><span> List</span><span>[</span><span>StorageChange</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"> AccountChanges: [address, storage_changes, storage_reads, balance_changes, nonce_changes, code_changes]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> All changes for a single account, grouped by field type</span></span> <span class="giallo-l"><span>AccountChanges</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span> Address</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> address</span></span> <span class="giallo-l"><span> List</span><span>[</span><span>SlotChanges</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_changes (slot -&gt; [block_access_index -&gt; new_value])</span></span> <span class="giallo-l"><span> List</span><span>[</span><span>StorageKey</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_reads (read-only storage keys)</span></span> <span class="giallo-l"><span> List</span><span>[</span><span>BalanceChange</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> balance_changes ([block_access_index -&gt; post_balance])</span></span> <span class="giallo-l"><span> List</span><span>[</span><span>NonceChange</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> nonce_changes ([block_access_index -&gt; new_nonce])</span></span> <span class="giallo-l"><span> List</span><span>[</span><span>CodeChange</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> code_changes ([block_access_index -&gt; new_code])</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"> BlockAccessList: List of AccountChanges</span></span> <span class="giallo-l"><span>BlockAccessList</span><span class="z-keyword"> =</span><span> List</span><span>[</span><span>AccountChanges</span><span>]</span></span></code></pre><h3 id="scope-and-inclusion">Scope and Inclusion</h3> <p><strong><code>BlockAccessList</code></strong> is the set of all addresses accessed during block execution.</p> <p>It <strong>MUST</strong> include:</p> <ul> <li> <p>Addresses with state changes (storage, balance, nonce, or code).</p> </li> <li> <p>Addresses accessed without state changes, including:</p> <ul> <li>Targets of <code>BALANCE</code>, <code>EXTCODESIZE</code>, <code>EXTCODECOPY</code>, <code>EXTCODEHASH</code> opcodes</li> <li>Targets of <code>CALL</code>, <code>CALLCODE</code>, <code>DELEGATECALL</code>, <code>STATICCALL</code> (even if they revert; see <a href="https://wg-eips.ritovision.com/7928/#gas-validation-before-state-access">Gas Validation Before State Access</a> for inclusion conditions)</li> <li>Target addresses of <code>CREATE</code>/<code>CREATE2</code> if the target account is accessed</li> <li>Deployed contract addresses from calls with initcode to empty addresses (e.g., calling <code>0x0</code> with initcode)</li> <li>Transaction sender and recipient addresses (even for zero-value transfers)</li> <li>COINBASE address if the block contains transactions or withdrawals to the COINBASE address</li> <li>Beneficiary addresses for <code>SELFDESTRUCT</code></li> <li>System contract addresses accessed during pre/post-execution; the system caller address, <code>SYSTEM_ADDRESS</code> (<code>0xfffffffffffffffffffffffffffffffffffffffe</code>), MUST NOT be included unless it experiences state access itself</li> <li>Withdrawal recipient addresses, regardless of whether the withdrawal amount is non-zero</li> <li>Precompiled contracts when called or accessed</li> </ul> </li> </ul> <p>Addresses with no state changes <strong>MUST</strong> still be present with empty change lists.</p> <p>Entries from an <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> access list <strong>MUST NOT</strong> be included automatically. Only addresses and storage slots that are actually touched or changed during execution are recorded.</p> <h3 id="gas-validation-before-state-access">Gas Validation Before State Access</h3> <p>State-accessing opcodes perform gas validation in two phases:</p> <ul> <li><strong>Pre-state validation</strong>: Gas costs determinable without state access (memory expansion, base opcode cost, warm/cold access cost)</li> <li><strong>Post-state validation</strong>: Gas costs requiring state access (account existence, <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> delegation resolution)</li> </ul> <p>Pre-state validation MUST pass before any state access occurs. If pre-state validation fails, the target resource (address or storage slot) is never accessed and MUST NOT be included in the BAL.</p> <p>Once pre-state validation passes, the target is accessed and included in the BAL. Post-state costs are then calculated; their order is implementation-defined since the target has already been accessed.</p> <p>The following table specifies pre-state validation costs in addition to the base opcode cost (gas constants as defined in <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>):</p> <table><thead><tr><th>Instruction</th><th>Pre-state Validation</th></tr></thead><tbody> <tr><td><code>BALANCE</code></td><td><code>access_cost</code></td></tr> <tr><td><code>SELFBALANCE</code></td><td>None (accesses current contract, always warm)</td></tr> <tr><td><code>EXTCODESIZE</code></td><td><code>access_cost</code></td></tr> <tr><td><code>EXTCODEHASH</code></td><td><code>access_cost</code></td></tr> <tr><td><code>EXTCODECOPY</code></td><td><code>access_cost</code> + <code>memory_expansion</code></td></tr> <tr><td><code>CALL</code></td><td><code>access_cost</code> + <code>memory_expansion</code> + <code>GAS_CALL_VALUE</code> (if value &gt; 0)</td></tr> <tr><td><code>CALLCODE</code></td><td><code>access_cost</code> + <code>memory_expansion</code> + <code>GAS_CALL_VALUE</code> (if value &gt; 0)</td></tr> <tr><td><code>DELEGATECALL</code></td><td><code>access_cost</code> + <code>memory_expansion</code></td></tr> <tr><td><code>STATICCALL</code></td><td><code>access_cost</code> + <code>memory_expansion</code></td></tr> <tr><td><code>CREATE</code></td><td><code>memory_expansion</code> + <code>INITCODE_WORD_COST</code> + <code>GAS_CREATE</code></td></tr> <tr><td><code>CREATE2</code></td><td><code>memory_expansion</code> + <code>INITCODE_WORD_COST</code> + <code>GAS_KECCAK256_WORD</code> + <code>GAS_CREATE</code></td></tr> <tr><td><code>SLOAD</code></td><td><code>access_cost</code></td></tr> <tr><td><code>SSTORE</code></td><td>More than <code>GAS_CALL_STIPEND</code> available</td></tr> <tr><td><code>SELFDESTRUCT</code></td><td><code>GAS_SELF_DESTRUCT</code> + <code>access_cost</code></td></tr> </tbody></table> <p>Where:</p> <ul> <li><code>access_cost</code>: For account-accessing opcodes: <code>COLD_ACCOUNT_ACCESS_COST</code> if cold, <code>WARM_STORAGE_READ_COST</code> if warm. For storage-accessing opcodes (<code>SLOAD</code>): <code>COLD_SLOAD_COST</code> if cold, <code>WARM_STORAGE_READ_COST</code> if warm.</li> <li><code>memory_expansion</code>: Gas cost to expand memory for input/output regions</li> </ul> <p>Post-state costs (e.g., <code>GAS_NEW_ACCOUNT</code> for calls to empty accounts, <code>GAS_SELF_DESTRUCT_NEW_ACCOUNT</code> if beneficiary does not exist) do not affect BAL inclusion since the target has already been accessed.</p> <h4 id="eip-7702-delegation">EIP-7702 Delegation</h4> <p>When a call target has an <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> delegation, the target is accessed to resolve the delegation. If a delegation exists, the delegated address requires its own <code>access_cost</code> check before being accessed. If this check fails, the delegated address MUST NOT appear in the BAL, though the original call target is included (having been accessed to resolve the delegation).</p> <p>Note: Delegated accounts cannot be empty, so <code>GAS_NEW_ACCOUNT</code> never applies when resolving delegations.</p> <h4 id="sstore">SSTORE</h4> <p><code>SSTORE</code> performs an implicit read of the current storage value for gas calculation. The <code>GAS_CALL_STIPEND</code> check prevents this state access when operating within the call stipend. If <code>SSTORE</code> fails this check, the storage slot MUST NOT appear in <code>storage_reads</code> or <code>storage_changes</code>.</p> <h3 id="ordering-and-determinism">Ordering and Determinism</h3> <p>The following ordering rules <strong>MUST</strong> apply:</p> <ul> <li><strong>Accounts</strong>: Lexicographic by address</li> <li><strong>storage_changes</strong>: Slots lexicographic by storage key; within each slot, changes by block access index (ascending)</li> <li><strong>storage_reads</strong>: Lexicographic by storage key</li> <li><strong>balance_changes, nonce_changes, code_changes</strong>: By block access index (ascending)</li> </ul> <h3 id="blockaccessindex-assignment">BlockAccessIndex Assignment</h3> <p><code>BlockAccessIndex</code> values <strong>MUST</strong> be assigned as follows:</p> <ul> <li><code>0</code> for <strong>pre‑execution</strong> system contract calls.</li> <li><code>1 … n</code> for transactions (in block order).</li> <li><code>n + 1</code> for <strong>post‑execution</strong> system contract calls.</li> </ul> <h3 id="recording-semantics-by-change-type">Recording Semantics by Change Type</h3> <h4 id="storage">Storage</h4> <ul> <li> <p><strong>Writes include:</strong></p> <ul> <li>Any value change (post‑value ≠ pre‑value).</li> <li><strong>Zeroing</strong> a slot (pre‑value exists, post‑value is zero).</li> </ul> </li> <li> <p><strong>Reads include:</strong></p> <ul> <li>Slots accessed via <code>SLOAD</code> that are not written.</li> <li>Slots written with unchanged values (i.e., <code>SSTORE</code> where post-value equals pre-value, also known as "no-op writes").</li> </ul> </li> </ul> <p>Note: Implementations MUST check the pre-transaction value to correctly distinguish between actual writes and no-op writes.</p> <h4 id="balance-balance-changes">Balance (<code>balance_changes</code>)</h4> <p>Record <strong>post‑transaction</strong> balances (<code>uint256</code>) for:</p> <ul> <li>Transaction <strong>senders</strong> (gas + value).</li> <li>Transaction <strong>recipients</strong> (only if <code>value &gt; 0</code>).</li> <li>CALL/CALLCODE <strong>senders</strong> (value).</li> <li>CALL/CALLCODE <strong>recipients</strong> (only if <code>value &gt; 0</code>).</li> <li>CREATE/CREATE2 recipients (only if <code>value &gt; 0</code>).</li> <li><strong>COINBASE</strong> (rewards + fees).</li> <li><strong>SELFDESTRUCT/SENDALL</strong> beneficiaries.</li> <li><strong>Withdrawal recipients</strong> (system withdrawals, <a href="https://wg-eips.ritovision.com/4895/">EIP-4895</a>).</li> </ul> <p>For unaltered account balances:</p> <p>If an account’s balance changes during a transaction, but its post-transaction balance is equal to its pre-transaction balance, then the change <strong>MUST NOT</strong> be recorded in <code>balance_changes</code>. The sender and recipient address <strong>MUST</strong> be included in <code>AccountChanges</code>.</p> <p>The following special cases require addresses to be included with empty changes if no other state changes occur:</p> <ul> <li>Zero-value transfer recipients</li> <li>Calling a same-transaction SELFDESTRUCT on an address that had a zero pre-transaction balance</li> </ul> <p>Zero-value block reward recipients <strong>MUST NOT</strong> trigger a balance change in the block access list and <strong>MUST NOT</strong> cause the recipient address to be included as a read (e.g. without changes). Zero-value block reward recipients <strong>MUST</strong> only be included with a balance change in blocks where the reward is greater than zero.</p> <h4 id="code">Code</h4> <p>Track <strong>post‑transaction runtime bytecode</strong> for deployed or modified contracts, and <strong>delegation indicators</strong> for successful delegations as defined in <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>.</p> <h4 id="nonce">Nonce</h4> <p>Record <strong>post‑transaction nonces</strong> for:</p> <ul> <li>EOA senders.</li> <li>Contracts that performed a successful <code>CREATE</code> or <code>CREATE2</code>.</li> <li>Deployed contracts.</li> <li><a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> authorities.</li> </ul> <h3 id="edge-cases-normative">Edge Cases (Normative)</h3> <ul> <li><strong>COINBASE / Fee Recipient:</strong> The COINBASE address <strong>MUST</strong> be included if it experiences any state change. It <strong>MUST NOT</strong> be included for blocks with no transactions, provided there are no other state changes (e.g., from <a href="https://wg-eips.ritovision.com/4895/">EIP-4895</a> withdrawals). If the COINBASE reward is zero, the COINBASE address <strong>MUST</strong> be included as a <em>read</em>.</li> <li><strong>Precompiled contracts:</strong> Precompiles <strong>MUST</strong> be included when accessed. If a precompile receives value, it is recorded with a balance change. Otherwise, it is included with empty change lists.</li> <li><strong>SENDALL:</strong> For positive-value selfdestructs, the sender and beneficiary are recorded with a balance change.</li> <li><strong>SELFDESTRUCT (in-transaction):</strong> Accounts destroyed within a transaction <strong>MUST</strong> be included in <code>AccountChanges</code> without nonce or code changes. However, if the account had a positive balance pre-transaction, the balance change to zero <strong>MUST</strong> be recorded. Storage keys within the self-destructed contracts that were modified or read <strong>MUST</strong> be included as a <code>storage_reads</code> entry.</li> <li><strong>Accessed but unchanged:</strong> Include the address with empty changes (e.g., targets of <code>EXTCODEHASH</code>, <code>EXTCODESIZE</code>, <code>BALANCE</code>, <code>STATICCALL</code>, etc.).</li> <li><strong>Zero‑value transfers / Unchanged balance in transaction:</strong> Include the address; omit from <code>balance_changes</code>.</li> <li><strong>Gas refunds:</strong> Record the <strong>final</strong> balance of the sender after each transaction.</li> <li><strong>Block rewards:</strong> Record the <strong>final</strong> balance of the fee recipient after each transaction.</li> <li><strong>Exceptional halts:</strong> Record the <strong>final</strong> nonce and balance of the sender, and the <strong>final</strong> balance of the fee recipient after each transaction. State changes from the reverted call are discarded, but all accessed addresses <strong>MUST</strong> be included. If no changes remain, addresses are included with empty lists; if storage was read, the corresponding keys <strong>MUST</strong> appear in <code>storage_reads</code>.</li> <li><strong>Pre‑execution system contract calls:</strong> All state changes <strong>MUST</strong> use <code>block_access_index = 0</code>.</li> <li><strong>Post‑execution system contract calls:</strong> All state changes <strong>MUST</strong> use <code>block_access_index = len(transactions) + 1</code>.</li> <li><strong>EIP-7702 Delegations:</strong> The authority address <strong>MUST</strong> be included with nonce and code changes after any successful delegation set, update, or clear. If authorization fails after the authority address has been loaded and added to <code>accessed_addresses</code> (per <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>), it <strong>MUST</strong> still be included with an empty change set; if authorization fails before the authority is loaded, it <strong>MUST NOT</strong> be included. The delegation target <strong>MUST NOT</strong> be included during delegation creation or modification and MUST only be included once it is actually loaded as an execution target (e.g., via <code>CALL</code>/<code>CALLCODE</code>/<code>DELEGATECALL</code>/<code>STATICCALL</code> under authority execution).</li> <li><strong>EIP‑4895 (Consensus layer withdrawals):</strong> Recipients are recorded with their final balance after the withdrawal.</li> <li><strong>EIP‑2935 (block hash):</strong> Record system contract storage diffs of the <strong>single</strong> updated storage slot in the ring buffer.</li> <li><strong>EIP‑4788 (beacon root):</strong> Record system contract storage diffs of the <strong>two</strong> updated storage slots in the ring buffer.</li> <li><strong>EIP‑7002 (withdrawals):</strong> Record system contract storage diffs of storage slots <strong>0–3</strong> (4 slots) after the dequeuing call.</li> <li><strong>EIP‑7251 (consolidations):</strong> Record system contract storage diffs of storage slots <strong>0–3</strong> (4 slots) after the dequeuing call.</li> </ul> <h3 id="engine-api">Engine API</h3> <p>The Engine API is extended with new structures and methods to support block-level access lists:</p> <p><strong>ExecutionPayloadV4</strong> extends ExecutionPayloadV3 with:</p> <ul> <li><code>blockAccessList</code>: RLP-encoded block access list</li> </ul> <p><strong>engine_newPayloadV5</strong> validates execution payloads:</p> <ul> <li>Accepts <code>ExecutionPayloadV4</code> structure</li> <li>Validates that computed access list matches provided <code>blockAccessList</code></li> <li>Returns <code>INVALID</code> if access list is malformed or doesn't match</li> </ul> <p><strong>engine_getPayloadV6</strong> builds execution payloads:</p> <ul> <li>Returns <code>ExecutionPayloadV4</code> structure</li> <li>Collects all account accesses and state changes during transaction execution</li> <li>Populates <code>blockAccessList</code> field with RLP-encoded access list</li> </ul> <p><strong>Block processing flow:</strong></p> <p>When processing a block:</p> <ol> <li>The EL receives the BAL in the ExecutionPayload</li> <li>The EL computes <code>block_access_list_hash = keccak256(blockAccessList)</code> and includes it in the block header</li> <li>The EL executes the block and generates the actual BAL</li> <li>If the generated BAL doesn't match the provided BAL, the block is invalid (the hash in the header would be wrong)</li> </ol> <p>The execution layer provides the RLP-encoded <code>blockAccessList</code> to the consensus layer via the Engine API. The consensus layer then computes the SSZ <code>hash_tree_root</code> for storage in the <code>ExecutionPayload</code>.</p> <p><strong>Retrieval methods</strong> for historical BALs:</p> <ul> <li><code>engine_getPayloadBodiesByHashV2</code>: Returns <code>ExecutionPayloadBodyV2</code> objects containing transactions, withdrawals, and <code>blockAccessList</code></li> <li><code>engine_getPayloadBodiesByRangeV2</code>: Returns <code>ExecutionPayloadBodyV2</code> objects containing transactions, withdrawals, and <code>blockAccessList</code></li> </ul> <p>The <code>blockAccessList</code> field contains the RLP-encoded BAL or <code>null</code> for pre-Amsterdam blocks or when data has been pruned.</p> <p>The EL MUST retain BALs for at least the duration of the weak subjectivity period (<code>=3533 epochs</code>) to support synchronization with re-execution after being offline for less than the WSP.</p> <h3 id="state-transition-function">State Transition Function</h3> <p>The state transition function must validate that the provided BAL matches the actual state accesses:</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">execution_payload</span><span>,</span><span class="z-variable z-parameter z-function"> block_header</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 1. Compute hash from received BAL and set in header</span></span> <span class="giallo-l"><span> block_header</span><span>.</span><span>block_access_list_hash</span><span class="z-keyword"> =</span><span> keccak</span><span>(</span><span>execution_payload</span><span>.</span><span>blockAccessList</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"> 2. Execute block and collect actual accesses</span></span> <span class="giallo-l"><span> actual_bal</span><span class="z-keyword"> =</span><span> execute_and_collect_accesses</span><span>(</span><span>execution_payload</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"> 3. Verify actual execution matches provided BAL</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> If this fails, the block is invalid (the hash in the header would be wrong)</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> rlp</span><span>.</span><span>encode</span><span>(</span><span>actual_bal</span><span>)</span><span class="z-keyword"> ==</span><span> execution_payload</span><span>.</span><span>blockAccessList</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_and_collect_accesses</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-punctuation z-definition z-string"> &quot;&quot;&quot;</span><span class="z-string">Execute block and collect all state accesses into BAL format</span><span class="z-punctuation z-definition z-string">&quot;&quot;&quot;</span></span> <span class="giallo-l"><span> accesses</span><span class="z-keyword"> =</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"> Pre-execution system contracts (block_access_index = 0)</span></span> <span class="giallo-l"><span> track_system_contracts_pre</span><span>(</span><span>block</span><span>,</span><span> accesses</span><span>,</span><span class="z-variable"> block_access_index</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-punctuation z-definition z-comment"> #</span><span class="z-comment"> Execute transactions (block_access_index = 1..n)</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>block</span><span>.</span><span>transactions</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> execute_transaction</span><span>(</span><span>tx</span><span>)</span></span> <span class="giallo-l"><span> track_state_changes</span><span>(</span><span>tx</span><span>,</span><span> accesses</span><span>,</span><span class="z-variable"> block_access_index</span><span class="z-keyword">=</span><span>i</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Withdrawals and post-execution (block_access_index = len(txs) + 1)</span></span> <span class="giallo-l"><span> post_index</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span>block</span><span>.</span><span>transactions</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> withdrawal</span><span class="z-keyword"> in</span><span> block</span><span>.</span><span>withdrawals</span><span>:</span></span> <span class="giallo-l"><span> apply_withdrawal</span><span>(</span><span>withdrawal</span><span>)</span></span> <span class="giallo-l"><span> track_balance_change</span><span>(</span><span>withdrawal</span><span>.</span><span>address</span><span>,</span><span> accesses</span><span>,</span><span> post_index</span><span>)</span></span> <span class="giallo-l"><span> track_system_contracts_post</span><span>(</span><span>block</span><span>,</span><span> accesses</span><span>,</span><span> post_index</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"> Convert to BAL format and sort</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> build_bal</span><span>(</span><span>accesses</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"> track_state_changes</span><span>(</span><span class="z-variable z-parameter z-function">tx</span><span>,</span><span class="z-variable z-parameter z-function"> accesses</span><span>,</span><span class="z-variable z-parameter z-function"> block_access_index</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span><span class="z-string">Track all state changes from a transaction</span><span class="z-punctuation z-definition z-string">&quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> addr</span><span class="z-keyword"> in</span><span> get_touched_addresses</span><span>(</span><span>tx</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> accesses</span><span>:</span></span> <span class="giallo-l"><span> accesses</span><span>[</span><span>addr</span><span>]</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">storage_writes</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span><span> {</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> slot -&gt; [(index, value)]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">storage_reads</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span><span class="z-support"> set</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">balance_changes</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span><span> [</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">nonce_changes</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span><span> [</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">code_changes</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 class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Track storage changes</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> slot</span><span>,</span><span> value</span><span class="z-keyword"> in</span><span> get_storage_writes</span><span>(</span><span>addr</span><span>)</span><span>.</span><span>items</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> slot</span><span class="z-keyword"> not</span><span class="z-keyword"> in</span><span> accesses</span><span>[</span><span>addr</span><span>]</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">storage_writes</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>:</span></span> <span class="giallo-l"><span> accesses</span><span>[</span><span>addr</span><span>]</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">storage_writes</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>[</span><span>slot</span><span>]</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> accesses</span><span>[</span><span>addr</span><span>]</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">storage_writes</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>[</span><span>slot</span><span>]</span><span>.</span><span>append</span><span>(</span><span>(</span><span>block_access_index</span><span>,</span><span> value</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"> Track reads (slots accessed but not written)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> slot</span><span class="z-keyword"> in</span><span> get_storage_reads</span><span>(</span><span>addr</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> slot</span><span class="z-keyword"> not</span><span class="z-keyword"> in</span><span> accesses</span><span>[</span><span>addr</span><span>]</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">storage_writes</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>:</span></span> <span class="giallo-l"><span> accesses</span><span>[</span><span>addr</span><span>]</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">storage_reads</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>.</span><span>add</span><span>(</span><span>slot</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"> Track balance, nonce, code changes</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> balance_changed</span><span>(</span><span>addr</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> accesses</span><span>[</span><span>addr</span><span>]</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">balance_changes</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>.</span><span>append</span><span>(</span><span>(</span><span>block_access_index</span><span>,</span><span> get_balance</span><span>(</span><span>addr</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> nonce_changed</span><span>(</span><span>addr</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> accesses</span><span>[</span><span>addr</span><span>]</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">nonce_changes</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>.</span><span>append</span><span>(</span><span>(</span><span>block_access_index</span><span>,</span><span> get_nonce</span><span>(</span><span>addr</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> code_changed</span><span>(</span><span>addr</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> accesses</span><span>[</span><span>addr</span><span>]</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">code_changes</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>.</span><span>append</span><span>(</span><span>(</span><span>block_access_index</span><span>,</span><span> get_code</span><span>(</span><span>addr</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"> build_bal</span><span>(</span><span class="z-variable z-parameter z-function">accesses</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span><span class="z-string">Convert collected accesses to BAL format</span><span class="z-punctuation z-definition z-string">&quot;&quot;&quot;</span></span> <span class="giallo-l"><span> bal</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> addr</span><span class="z-keyword"> in</span><span class="z-support"> sorted</span><span>(</span><span>accesses</span><span>.</span><span>keys</span><span>(</span><span>)</span><span>)</span><span>:</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Sort addresses lexicographically</span></span> <span class="giallo-l"><span> data</span><span class="z-keyword"> =</span><span> accesses</span><span>[</span><span>addr</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"> Format storage changes: [slot, [[index, value], ...]]</span></span> <span class="giallo-l"><span> storage_changes</span><span class="z-keyword"> =</span><span> [</span><span>[</span><span>slot</span><span>,</span><span class="z-support"> sorted</span><span>(</span><span>changes</span><span>)</span><span>]</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> slot</span><span>,</span><span> changes</span><span class="z-keyword"> in</span><span class="z-support"> sorted</span><span>(</span><span>data</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">storage_writes</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>.</span><span>items</span><span>(</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"> Account entry: [address, storage_changes, reads, balance_changes, nonce_changes, code_changes]</span></span> <span class="giallo-l"><span> bal</span><span>.</span><span>append</span><span>(</span><span>[</span></span> <span class="giallo-l"><span> addr</span><span>,</span></span> <span class="giallo-l"><span> storage_changes</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> sorted</span><span>(</span><span class="z-support">list</span><span>(</span><span>data</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">storage_reads</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> sorted</span><span>(</span><span>data</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">balance_changes</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-support"> sorted</span><span>(</span><span>data</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">nonce_changes</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-support"> sorted</span><span>(</span><span>data</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">code_changes</span><span class="z-punctuation z-definition z-string">&#39;</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 class="z-keyword"> return</span><span> bal</span></span></code></pre> <p>The BAL MUST be complete and accurate. Missing or spurious entries invalidate the block. Spurious entries MAY be detected by validating BAL indices, which MUST never be higher than <code>len(transactions) + 1</code>.</p> <p>Clients MAY invalidate immediately if any transaction exceeds declared state.</p> <p>Clients MUST store BALs separately from blocks and make them available via the engine API.</p> <h3 id="concrete-example">Concrete Example</h3> <p>Example block:</p> <p><strong>Pre-execution:</strong></p> <ul> <li>EIP-2935: Store parent hash at block hash contract (<code>0x0000F90827F1C53a10cb7A02335B175320002935</code>)</li> <li>EIP-7002: Omitted for simplicity.</li> </ul> <p><strong>Transactions:</strong></p> <ol> <li>Alice (0xaaaa...) sends 1 ETH to Bob (0xbbbb...), checks balance of 0x2222...</li> <li>Charlie (0xcccc...) calls factory (0xffff...) deploying contract at 0xdddd...</li> </ol> <p><strong>Post-execution:</strong></p> <ul> <li>Withdrawal of 100 ETH to Eve (0xabcd...)</li> <li>EIP-7002 and EIP-7251 omitted for simplicity.</li> </ul> <p>Note: Pre-execution system contract uses block_access_index = 0. Post-execution withdrawal uses block_access_index = 3 (len(transactions) + 1)</p> <p>Resulting BAL (RLP structure):</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>[</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Addresses are sorted lexicographically</span></span> <span class="giallo-l"><span> [</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> AccountChanges for 0x0000F90827F1C53a10cb7A02335B175320002935 (Block hash contract)</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">0000F90827F1C53a10cb7A02335B175320002935</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_changes</span></span> <span class="giallo-l"><span> [</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-string">...</span><span class="z-constant">\x0f</span><span class="z-constant">\xa0</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> [</span><span>[</span><span class="z-constant">0</span><span>,</span><span class="z-storage z-type"> b</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>]</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> slot, [[block_access_index, parent_hash]]</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_reads</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> balance_changes</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> nonce_changes</span></span> <span class="giallo-l"><span> [</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> code_changes</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> AccountChanges for 0x2222... (Address checked by Alice)</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">2222</span><span class="z-constant">...</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_changes</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_reads</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> balance_changes (no change, just checked)</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> nonce_changes</span></span> <span class="giallo-l"><span> [</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> code_changes</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> AccountChanges for 0xaaaa... (Alice - sender tx 0)</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">aaaa</span><span class="z-constant">...</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_changes</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_reads</span></span> <span class="giallo-l"><span> [</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-invalid z-illegal"> 0x</span><span class="z-constant">...</span><span class="z-invalid z-illegal">29a241a</span><span>]</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> balance_changes: [[block_access_index, post_balance]]</span></span> <span class="giallo-l"><span> [</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 10</span><span>]</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> nonce_changes: [[block_access_index, new_nonce]]</span></span> <span class="giallo-l"><span> [</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> code_changes</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> AccountChanges for 0xabcd... (Eve - withdrawal recipient)</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">abcd</span><span class="z-constant">...</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_changes</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_reads</span></span> <span class="giallo-l"><span> [</span><span>[</span><span class="z-constant">3</span><span>,</span><span class="z-invalid z-illegal"> 0x</span><span class="z-constant">...</span><span class="z-invalid z-illegal">5f5e100</span><span>]</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> balance_changes: 100 ETH withdrawal</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> nonce_changes</span></span> <span class="giallo-l"><span> [</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> code_changes</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> AccountChanges for 0xbbbb... (Bob - recipient tx 0)</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">bbbb</span><span class="z-constant">...</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_changes</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_reads</span></span> <span class="giallo-l"><span> [</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-invalid z-illegal"> 0x</span><span class="z-constant">...</span><span>b9aca00</span><span>]</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> balance_changes: +1 ETH</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> nonce_changes</span></span> <span class="giallo-l"><span> [</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> code_changes</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> AccountChanges for 0xcccc... (Charlie - sender tx 1)</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">cccc</span><span class="z-constant">...</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_changes</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_reads</span></span> <span class="giallo-l"><span> [</span><span>[</span><span class="z-constant">2</span><span>,</span><span class="z-invalid z-illegal"> 0x</span><span class="z-constant">...</span><span>bc16d67</span><span>]</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> balance_changes: after gas</span></span> <span class="giallo-l"><span> [</span><span>[</span><span class="z-constant">2</span><span>,</span><span class="z-constant"> 5</span><span>]</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> nonce_changes</span></span> <span class="giallo-l"><span> [</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> code_changes</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> AccountChanges for 0xdddd... (Deployed contract)</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">dddd</span><span class="z-constant">...</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_changes</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_reads</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> balance_changes</span></span> <span class="giallo-l"><span> [</span><span>[</span><span class="z-constant">2</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> nonce_changes: new contract nonce</span></span> <span class="giallo-l"><span> [</span><span>[</span><span class="z-constant">2</span><span>,</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-constant">\x60</span><span class="z-constant">\x80</span><span class="z-constant">\x60</span><span class="z-constant">\x40</span><span class="z-string">...</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> code_changes: deployed bytecode</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> AccountChanges for 0xeeee... (COINBASE)</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">eeee</span><span class="z-constant">...</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_changes</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_reads</span></span> <span class="giallo-l"><span> [</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-invalid z-illegal"> 0x</span><span class="z-constant">...</span><span class="z-invalid z-illegal">05f5e1</span><span>]</span><span>,</span><span> [</span><span class="z-constant">2</span><span>,</span><span class="z-invalid z-illegal"> 0x</span><span class="z-constant">...</span><span class="z-invalid z-illegal">0bebc2</span><span>]</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> balance_changes: after tx fees</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> nonce_changes</span></span> <span class="giallo-l"><span> [</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> code_changes</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> AccountChanges for 0xffff... (Factory contract)</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">ffff</span><span class="z-constant">...</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_changes</span></span> <span class="giallo-l"><span> [</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-string">...</span><span class="z-constant">\x01</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> [</span><span>[</span><span class="z-constant">2</span><span>,</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-string">...</span><span class="z-constant">\xdd</span><span class="z-constant">\xdd</span><span class="z-string">...</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>]</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> slot 1, deployed address</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> storage_reads</span></span> <span class="giallo-l"><span> [</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> balance_changes</span></span> <span class="giallo-l"><span> [</span><span>[</span><span class="z-constant">2</span><span>,</span><span class="z-constant"> 5</span><span>]</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> nonce_changes: after CREATE</span></span> <span class="giallo-l"><span> [</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> code_changes</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>]</span></span></code></pre> <p>RLP-encoded and compressed: ~400-500 bytes.</p> <h2 id="rationale">Rationale</h2> <h3 id="bal-design-choice">BAL Design Choice</h3> <p>This design variant was chosen for several key reasons:</p> <ol> <li> <p><strong>Size vs parallelization</strong>: BALs include all accessed addresses (even unchanged) for complete parallel IO and execution.</p> </li> <li> <p><strong>Storage values for writes</strong>: Post-execution values enable state reconstruction during sync without individual proofs against state root.</p> </li> <li> <p><strong>Overhead analysis</strong>: Historical data shows ~70 KiB average BAL size.</p> </li> <li> <p><strong>Transaction independence</strong>: 60-80% of transactions access disjoint storage slots, enabling effective parallelization. The remaining 20-40% can be parallelized by having post-transaction state diffs.</p> </li> <li> <p><strong>RLP encoding</strong>: Native Ethereum encoding format, maintains compatibility with existing infrastructure.</p> </li> </ol> <h3 id="bal-size-considerations-60m-block-gas-limit">BAL Size Considerations (60m block gas limit)</h3> <p><strong>Average BAL size</strong>: ~72.4 KiB (compressed)</p> <ul> <li>Storage writes: ~29.2 KiB (40.3%)</li> <li>Storage reads: ~18.7 KiB (25.8%)</li> <li>Balance diffs: ~6.7 KiB (9.2%)</li> <li>Nonce diffs: ~1.1 KiB (1.5%)</li> <li>Code diffs: ~1.2 KiB (1.6%)</li> <li>Account addresses (with diffs): ~7.7 KiB (10.7%)</li> <li>Touched-only addresses: ~3.5 KiB (4.8%)</li> <li>RLP encoding overhead: ~4.4 KiB (6.1%)</li> </ul> <p>Smaller than current worst-case calldata blocks.</p> <p>An empirical analysis has been done <a href="https://wg-eips.ritovision.com/7928/assets/bal_size_analysis/">here</a>. An updated analysis for a 60 million block gas limit can be found <a href="https://wg-eips.ritovision.com/7928/assets/bal_size_analysis_60m/">here</a>.</p> <h3 id="asynchronous-validation">Asynchronous Validation</h3> <p>BAL verification occurs alongside parallel IO and EVM operations without delaying block processing.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal requires changes to the block structure and engine API that are not backwards compatible and require a hard fork.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="validation-overhead">Validation Overhead</h3> <p>Validating access lists and balance diffs adds validation overhead but is essential to prevent acceptance of invalid blocks.</p> <h3 id="block-size">Block Size</h3> <p>Increased block size impacts propagation but overhead (~70 KiB average) is reasonable for performance gains.</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-27T00:00:00+00:00 2026-02-11T14:49:27+00:00 Charles Cooperhttps://github.com/charles-cooper Qi Zhouhttps://github.com/qizhou https://wg-eips.ritovision.com/7923/

Linearize Memory Costing and replace the current quadratic formula with a page-based cost model.

<h2 id="abstract">Abstract</h2> <p>This EIP replaces the quadratic memory model in the EVM with a linear, page-based costing model. Memory is virtually addressable. Page allocation is included in the cost model. After applying this EIP, memory limits are invariant to the state of the message call stack.</p> <h2 id="motivation">Motivation</h2> <p>The EVM currently uses a quadratic pricing model for its memory. This was originally put in place to defend against DoS attacks. However, the memory model has several drawbacks.</p> <ol> <li>It is anachronistic. Even at a gas limit of 30 million gas, users can only use 3MB of memory in a message call (and that burns all gas). Since the quadratic term for memory expansion starts kicking in at 724 bytes, users use much less memory in practice. To use even 64KB of memory -- the amount of memory available to a PC from the early 80's -- costs 14336 gas!</li> <li>The quadratic model makes it difficult to reason about how much memory a transaction can allocate. It requires solving an optimization problem which involves computing how many message calls are available to recurse into based on the call stack limit (and, post <a href="https://wg-eips.ritovision.com/150/">EIP-150</a>, the 63/64ths rule), and then maximizing the memory used per message call.</li> <li>The quadratic model makes it impossible for high-level smart contracts languages to get the benefits of virtual memory. Most modern programming languages maintain what is known as the "heap" and the "call stack". The heap is used to allocate objects which live past the lifetime of their current function frame, whereas the call stack is used to allocate objects which live in the current function frames. Importantly, the call stack starts at the top of memory and grows down, while the heap starts at the bottom of memory and grows up, thus the language implementation does not need to worry about the two regions of memory interfering with each other. This is a feature which is enabled by virtual, paged memory, which has been present in operating systems since the early 90's. However, smart contract languages like Vyper and Solidity are not able to implement this, leading to inefficiencies in their memory models.</li> </ol> <p>This EIP proposes a linear costing model which more closely reflects the hardware of today, which is hierarchical ("hot" memory is much faster to access than "cold" memory), and virtually addressed (memory does not need to be allocated contiguously, but is rather served "on-demand" by the operating system).</p> <p>First, some preliminaries. A page is 4096 bytes on most architectures. Given a memory address, its page is simple to compute by masking out the rightmost 12 bits.</p> <p>There are two factors which contribute to "cold" memory (i.e. not-recently-used) being slower: CPU cache and TLB (Translation Lookaside Buffer) cache. The CPU cache is a least-recently-used memory cache, which is significantly faster than fetching all the way from RAM. The TLB is usually some hash table which maps virtual pages (used by the user) to physical pages in RAM. "Thrashing", or accessing a lot of different memory addresses, does two things: it pushes memory out of the hot cache and into cold memory, and it pushes pages out of the TLB cache. For this reason, it is worth limiting the amount of memory that is available to a transaction to memory which can be held in the hot set.</p> <p>This EIP uses a virtual addressing scheme so that memory pages are not allocated until they are actually accessed.</p> <p>Notably, the data structures used for costing memory do not need to be part of the memory implementation itself, which suggests an elegant implementation using the POSIX <code>mmap</code> syscall (or, its counterpart on Windows, <code>VirtualAlloc</code>).</p> <p>The implementation can be approached in two ways. The first way is to implement the virtual addressing "manually". This is intended for systems without <code>mmap</code> or a virtual addressing capability. The implementation needs to maintain a map from <code>map[page_id -&gt; char[4096]]</code>, where <code>page_id</code> is an integer, computed as <code>memory_address &gt;&gt; 12</code>. (On reads or writes which cross page boundaries, the implementation needs to load both pages and combine the result of the read or write across both pages).</p> <p>The other implementation is easier, for systems with <code>mmap</code> or a similar facility. To hold the actual data of the memory, the implementation <code>mmap</code>s a <code>2**32</code> byte region of memory. Then, memory operations can be implemented simply as reads or writes against this buffer. (With an anonymous <code>mmap</code>, the operating system will not allocate the entire buffer up-front, rather, it will allocate pages "on demand", as they are touched). The <code>pages</code> map is still necessary, but it doesn't hold any data, it is just to track which pages have been allocated, for pricing purposes. In this implementation, there are two data structures: <code>memory char[2**32]</code> and <code>allocated_pages set[page_id]</code>. The <code>memory</code> data structure is only used for memory reads and writes. The <code>allocated_pages</code> is only used for gas costing.</p> <h2 id="specification">Specification</h2> <p>Consider the following constants:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-constant">ALLOCATE_PAGE_COST</span><span class="z-keyword"> =</span><span class="z-constant"> 100</span></span> <span class="giallo-l"><span class="z-constant">PAGE_SIZE</span><span class="z-keyword"> =</span><span class="z-constant"> 4096</span></span> <span class="giallo-l"><span class="z-constant">MAXIMUM_MEMORY_SIZE</span><span class="z-keyword"> =</span><span class="z-constant"> 64</span><span class="z-keyword"> *</span><span class="z-constant"> 1024</span><span class="z-keyword"> *</span><span class="z-constant"> 1024</span></span></code></pre> <p>The memory costing algorithm is changed as follows:</p> <ol> <li>For each page touched by an instruction, charge <code>ALLOCATE_PAGE_COST</code> gas if it has not been touched before in this message call, except for page 0 which is free.</li> <li>The base gas cost for all memory instructions, e.g. <code>MLOAD</code> and <code>MSTORE</code>, remains the same, at 3.</li> <li>The linear and quadratic terms in the memory expansion cost are removed.</li> </ol> <p>The behavior of <code>msize</code> remains the same. It returns the maximum byte touched by any memory instruction, rounded up by 32.</p> <p>Memory addresses are restricted to 32-bits. If an address is larger than <code>2**32 - 1</code>, an exceptional halt should be raised.</p> <p>A transaction-global memory limit is imposed. If the number of pages allocated in a transaction exceeds <code>MAXIMUM_MEMORY_SIZE // PAGE_SIZE</code> (i.e., 16384), an exceptional halt should be raised.</p> <h2 id="rationale">Rationale</h2> <p>Benchmarks were performed on a 2019-era CPU, with the ability to <code>keccak256</code> around 256MB/s, giving it a gas-to-ns ratio of 20 ns per 1 gas (given that <code>keccak256</code> costs 6 gas per 32 bytes). The following benchmarks were performed:</p> <ul> <li>Time to allocate a fresh page: 1-2us</li> <li>Time to randomly read a byte from a 2MB range: 1.8ns</li> <li>Time to randomly read a byte from a 32MB range: 7ns</li> <li>Time to randomly read a byte from a 4GB range: 40ns</li> <li>Time to update a hashmap with 512 items: 8ns</li> <li>Time to update a hashmap with 8192 items: 9ns</li> <li>Time to update a hashmap with 5mm items: 108ns</li> <li>Time to execute the <code>mmap</code> syscall: 230ns</li> </ul> <p>These suggest the following prices:</p> <ul> <li>100 gas to allocate a page</li> </ul> <p>Note that the cost to execute <code>mmap</code> (~11 gas) is already well-paid for by the base cost of the CALL series of instructions (100 gas). For the same reason, page 0 is free, since the CALL overhead already pays for the initial page allocation. This also improves backwards compatibility, since it keeps the cost for any access within the first page either the same as or lower than current pricing.</p> <p>There is a desire among client implementations to be able to enforce global limits separately from the gas limit due to DoS reasons. For example, RPC providers may be designed to allow many concurrent <code>eth_call</code> computations with a much higher gas limit than on mainnet. Not implicitly tying the memory limit to the gas limit results in one less vector for misconfiguration. That is not to say that in the future, a clean formula cannot be created which allows the memory limit to scale with future hardware improvements (e.g., proportional to the sqrt of the gas limit), but to limit the scope of things that need to be reasoned about for this EIP, the hard limit is introduced.</p> <p>The hard limit is specified as a transaction-global limit rather than a message-call limit. That is, a reasonable alternative could be to limit the number of pages that can be allocated in a given message call, e.g., to 2MB, but it doesn't significantly improve implementation complexity.</p> <p>On keeping the semantics of <code>MSIZE</code> the same: With users expected to use the full address space instead of growing it linearly, the rationale for keeping <code>MSIZE</code> semantics the same is to avoid breaking backwards compatibility with existing contracts which expect it to grow linearly. New contracts taking advantage of the new virtual addressing scheme should not rely on <code>MSIZE</code> for memory allocation.</p> <p>A hard limit of <code>2**32</code> bytes was imposed on the addressing. This makes it simpler for modern 64-bit computers to allocate that much virtual address space, given that clients run on a diverse set of operating systems and architectures which have different virtual memory limits per process. This could be revisited in the future, for instance if gas limits or client memory sizes substantially increase.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Addressed in Security Considerations section. No backwards compatibility is broken, although some contracts that previously ran out of gas may now successfully complete.</p> <h2 id="test-cases">Test Cases</h2> <h2 id="reference-implementation">Reference Implementation</h2> <p>A ~60-line reference implementation is provided below. It is implemented as a patch against the <code>py-evm</code> codebase at commit ethereum/py-evm@fec63b8c4b9dad9fcb1022c48c863bdd584820c6. (This is a reference implementation, it does not, for example, contain fork choice rules).</p> <pre class="giallo z-code"><code data-lang="diff"><span class="giallo-l"><span class="z-meta z-diff z-header">diff --git a/eth/vm/computation.py b/eth/vm/computation.py</span></span> <span class="giallo-l"><span>index bf34fbee..db85aee7 100644</span></span> <span class="giallo-l"><span class="z-meta z-diff z-header z-from-file">---</span><span class="z-meta z-diff z-header z-from-file"> a/eth/vm/computation.py</span></span> <span class="giallo-l"><span class="z-meta z-diff z-header z-to-file">+++</span><span class="z-meta z-diff z-header z-to-file"> b/eth/vm/computation.py</span></span> <span class="giallo-l"><span class="z-meta z-diff z-range">@@</span><span class="z-meta z-diff z-range"> -454,34 +454,40</span><span class="z-meta z-diff z-range"> @@</span><span> class BaseComputation(ComputationAPI, Configurable):</span></span> <span class="giallo-l"><span> validate_uint256(start_position, title=&quot;Memory start position&quot;)</span></span> <span class="giallo-l"><span> validate_uint256(size, title=&quot;Memory size&quot;)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> before_size = ceil32(len(self._memory))</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> after_size = ceil32(start_position + size)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> before_cost = memory_gas_cost(before_size)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> after_cost = memory_gas_cost(after_size)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> if self.logger.show_debug2:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> self.logger.debug2(</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> f&quot;MEMORY: size ({before_size} -&gt; {after_size}) | &quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> f&quot;cost ({before_cost} -&gt; {after_cost})&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> )</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> if size:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> if before_cost &lt; after_cost:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> gas_fee = after_cost - before_cost</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> self._gas_meter.consume_gas(</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> gas_fee,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> reason=&quot; &quot;.join(</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> (</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> &quot;Expanding memory&quot;,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> str(before_size),</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> &quot;-&gt;&quot;,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> str(after_size),</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> )</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> ),</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> )</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> self._memory.extend(start_position, size)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> if size == 0:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> return</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> ALLOCATE_PAGE_COST = 100</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> LOWER_BITS = 12 # bits ignored for page calculations</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> PAGE_SIZE = 4096</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> assert 2**LOWER_BITS == PAGE_SIZE # sanity check</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> MAXIMUM_MEMORY_SIZE = 64 * 1024 * 1024</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> TRANSACTION_MAX_PAGES = MAXIMUM_MEMORY_SIZE // PAGE_SIZE</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> end_position = start_position + size - 1</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> start_page = start_position &gt;&gt; LOWER_BITS</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> end_page = end_position &gt;&gt; LOWER_BITS</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> for page in range(start_page, end_page + 1):</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> if page not in self._memory.pages:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> if self.transaction_context.num_pages &gt;= TRANSACTION_MAX_PAGES:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> raise VMError(&quot;Out Of Memory&quot;)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> self.transaction_context.num_pages += 1</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> reason = f&quot;Allocating page {hex(page &lt;&lt; LOWER_BITS)}&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> self._gas_meter.consume_gas(ALLOCATE_PAGE_COST, reason)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> self._memory.pages[page] = True</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> def memory_write(self, start_position: int, size: int, value: bytes) -&gt; None:</span></span> <span class="giallo-l"><span> return self._memory.write(start_position, size, value)</span></span> <span class="giallo-l"><span class="z-meta z-diff z-header">diff --git a/eth/vm/forks/frontier/computation.py b/eth/vm/forks/frontier/computation.py</span></span> <span class="giallo-l"><span>index 51666ae0..443f82b5 100644</span></span> <span class="giallo-l"><span class="z-meta z-diff z-header z-from-file">---</span><span class="z-meta z-diff z-header z-from-file"> a/eth/vm/forks/frontier/computation.py</span></span> <span class="giallo-l"><span class="z-meta z-diff z-header z-to-file">+++</span><span class="z-meta z-diff z-header z-to-file"> b/eth/vm/forks/frontier/computation.py</span></span> <span class="giallo-l"><span class="z-meta z-diff z-range">@@</span><span class="z-meta z-diff z-range"> -29,6 +29,7</span><span class="z-meta z-diff z-range"> @@</span><span> from eth.exceptions import (</span></span> <span class="giallo-l"><span> InsufficientFunds,</span></span> <span class="giallo-l"><span> OutOfGas,</span></span> <span class="giallo-l"><span> StackDepthLimit,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> VMError,</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> from eth.vm.computation import (</span></span> <span class="giallo-l"><span> BaseComputation,</span></span> <span class="giallo-l"><span class="z-meta z-diff z-range">@@</span><span class="z-meta z-diff z-range"> -87,12 +88,21</span><span class="z-meta z-diff z-range"> @@</span><span> class FrontierComputation(BaseComputation):</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> state.touch_account(message.storage_address)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> computation = cls.apply_computation(</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> state,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> message,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> transaction_context,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> parent_computation=parent_computation,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> )</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> # implement transaction-global memory limit</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> num_pages_anchor = transaction_context.num_pages</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> try:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> computation = cls.apply_computation(</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> state,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> message,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> transaction_context,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> parent_computation=parent_computation,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> )</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> finally:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> # &quot;deallocate&quot; all the pages allocated in the child computation</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> # sanity check an invariant:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> allocated_pages = len(computation._memory.pages)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> assert transaction_context.num_pages == num_pages_anchor + allocated pages</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> transaction_context.num_pages = num_pages_anchor</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if computation.is_error:</span></span> <span class="giallo-l"><span> state.revert(snapshot)</span></span> <span class="giallo-l"><span class="z-meta z-diff z-header">diff --git a/eth/vm/logic/memory.py b/eth/vm/logic/memory.py</span></span> <span class="giallo-l"><span>index 806dbd8b..247b3c74 100644</span></span> <span class="giallo-l"><span class="z-meta z-diff z-header z-from-file">---</span><span class="z-meta z-diff z-header z-from-file"> a/eth/vm/logic/memory.py</span></span> <span class="giallo-l"><span class="z-meta z-diff z-header z-to-file">+++</span><span class="z-meta z-diff z-header z-to-file"> b/eth/vm/logic/memory.py</span></span> <span class="giallo-l"><span class="z-meta z-diff z-range">@@</span><span class="z-meta z-diff z-range"> -43,7 +43,7</span><span class="z-meta z-diff z-range"> @@</span><span> def mload(computation: ComputationAPI) -&gt; None:</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span> def msize(computation: ComputationAPI) -&gt; None:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> computation.stack_push_int(len(computation._memory))</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> computation.stack_push_int(computation._memory.msize)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span> def mcopy(computation: ComputationAPI) -&gt; None:</span></span> <span class="giallo-l"><span class="z-meta z-diff z-header">diff --git a/eth/vm/memory.py b/eth/vm/memory.py</span></span> <span class="giallo-l"><span>index 2ccfd090..9002b559 100644</span></span> <span class="giallo-l"><span class="z-meta z-diff z-header z-from-file">---</span><span class="z-meta z-diff z-header z-from-file"> a/eth/vm/memory.py</span></span> <span class="giallo-l"><span class="z-meta z-diff z-header z-to-file">+++</span><span class="z-meta z-diff z-header z-to-file"> b/eth/vm/memory.py</span></span> <span class="giallo-l"><span class="z-meta z-diff z-range">@@</span><span class="z-meta z-diff z-range"> -1,8 +1,11</span><span class="z-meta z-diff z-range"> @@</span></span> <span class="giallo-l"><span> import logging</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted">import mmap</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span></span> <span class="giallo-l"><span> from eth._utils.numeric import (</span></span> <span class="giallo-l"><span> ceil32,</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted">from eth.exceptions import VMError</span></span> <span class="giallo-l"><span> from eth.abc import (</span></span> <span class="giallo-l"><span> MemoryAPI,</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-meta z-diff z-range">@@</span><span class="z-meta z-diff z-range"> -13,52 +16,48</span><span class="z-meta z-diff z-range"> @@</span><span> from eth.validation import (</span></span> <span class="giallo-l"><span> validate_uint256,</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> class Memory(MemoryAPI):</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> __slots__ = [&quot;_bytes&quot;]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> __slots__ = (&quot;pages&quot;, &quot;msize&quot;)</span></span> <span class="giallo-l"><span> logger = logging.getLogger(&quot;eth.vm.memory.Memory&quot;)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> def __init__(self) -&gt; None:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> self._bytes = bytearray()</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> self.memview = mmap.mmap(-1, 2**32, flags=mmap.MAP_PRIVATE | mmap.MAP_ANONYMOUS)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> self.pages = {0: True} # page 0 is free (per spec)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> self.msize = 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> def extend(self, start_position: int, size: int) -&gt; None:</span></span> <span class="giallo-l"><span> if size == 0:</span></span> <span class="giallo-l"><span> return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> new_size = ceil32(start_position + size)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> if new_size &lt;= len(self):</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> if start_position + size &gt; self.msize:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> self.msize = ceil32(start_position + size)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> def write(self, start_position: int, size: int, value: bytes) -&gt; None:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> if size == 0:</span></span> <span class="giallo-l"><span> return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> size_to_extend = new_size - len(self)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> try:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> self._bytes.extend(bytearray(size_to_extend))</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> except BufferError:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> # we can&#39;t extend the buffer (which might involve relocating it) if a</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> # memoryview (which stores a pointer into the buffer) has been created by</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> # read() and not released. Callers of read() will never try to write to the</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> # buffer so we&#39;re not missing anything by making a new buffer and forgetting</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> # about the old one. We&#39;re keeping too much memory around but this is still</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> # a net savings over having read() return a new bytes() object every time.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> self._bytes = self._bytes + bytearray(size_to_extend)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> def __len__(self) -&gt; int:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> return len(self._bytes)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> if start_position + size &gt;= 2**32:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> raise VMError(&quot;Non 32-bit address&quot;)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> def write(self, start_position: int, size: int, value: bytes) -&gt; None:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> if size:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> validate_uint256(start_position)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> validate_uint256(size)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> validate_is_bytes(value)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> validate_length(value, length=size)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> validate_lte(start_position + size, maximum=len(self))</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> validate_uint256(start_position)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> validate_uint256(size)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> validate_is_bytes(value)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> validate_length(value, length=size)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> end_position = start_position + size</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> self._bytes[start_position : start_position + len(value)] = value</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> self.memview[start_position : end_position] = value</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> # unused</span></span> <span class="giallo-l"><span> def read(self, start_position: int, size: int) -&gt; memoryview:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> return memoryview(self._bytes)[start_position : start_position + size]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> return memoryview(self.memview)[start_position : start_position + size]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> def read_bytes(self, start_position: int, size: int) -&gt; bytes:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> return bytes(self._bytes[start_position : start_position + size])</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> return bytes(self.memview[start_position : start_position + size])</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> def copy(self, destination: int, source: int, length: int) -&gt; None:</span></span> <span class="giallo-l"><span> if length == 0:</span></span> <span class="giallo-l"><span class="z-meta z-diff z-range">@@</span><span class="z-meta z-diff z-range"> -69,5 +68,5</span><span class="z-meta z-diff z-range"> @@</span><span> class Memory(MemoryAPI):</span></span> <span class="giallo-l"><span> validate_uint256(length)</span></span> <span class="giallo-l"><span> validate_lte(max(destination, source) + length, maximum=len(self))</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> buf = memoryview(self._bytes)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> buf = memoryview(self.memview)</span></span> <span class="giallo-l"><span> buf[destination : destination + length] = buf[source : source + length]</span></span> <span class="giallo-l"><span class="z-meta z-diff z-header">diff --git a/eth/vm/transaction_context.py b/eth/vm/transaction_context.py</span></span> <span class="giallo-l"><span>index 79b570e9..5943f897 100644</span></span> <span class="giallo-l"><span class="z-meta z-diff z-header z-from-file">---</span><span class="z-meta z-diff z-header z-from-file"> a/eth/vm/transaction_context.py</span></span> <span class="giallo-l"><span class="z-meta z-diff z-header z-to-file">+++</span><span class="z-meta z-diff z-header z-to-file"> b/eth/vm/transaction_context.py</span></span> <span class="giallo-l"><span class="z-meta z-diff z-range">@@</span><span class="z-meta z-diff z-range"> -36,6 +36,9</span><span class="z-meta z-diff z-range"> @@</span><span> class BaseTransactionContext(TransactionContextAPI):</span></span> <span class="giallo-l"><span> # post-cancun</span></span> <span class="giallo-l"><span> self._blob_versioned_hashes = blob_versioned_hashes or []</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> # eip-7923</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> self.num_pages = 0</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span></span> <span class="giallo-l"><span> def get_next_log_counter(self) -&gt; int:</span></span> <span class="giallo-l"><span> return next(self._log_counter)</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>There are two primary security considerations regarding this EIP.</p> <p>One, does it break existing contracts? That is, do existing contracts depend on memory being restricted?</p> <p>Outside of gas costing, existing contracts may simply execute to completion rather than running out of gas.</p> <p>Two, does this enable memory-based DoS attacks against clients?</p> <p>This requires a maximum-memory usage analysis. Based on a gas limit today of 30mm gas, recursively calling a contract that allocates 256KB of memory in each call stack can allocate 54MB of total memory, which is not substantially different than the 64MB limit proposed in this EIP. Note that the transaction-global memory limit proposed in this EIP provides a useful invariant, which is that future changes to call stack limits will not affect the total amount of memory that can be allocated in a given 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> 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-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 Anders Elowssonhttps://github.com/anderselowsson Ben Adamshttps://github.com/benaadams Francesco D'Amatohttps://github.com/fradamt https://wg-eips.ritovision.com/7918/

Imposes that the price of GAS_PER_BLOB blob gas is greater than the price of BLOB_BASE_COST execution gas.

<h2 id="abstract">Abstract</h2> <p>This EIP assigns a reserve price <code>BLOB_BASE_COST * base_fee_per_gas</code> to blobs by introducing an <code>if</code>-clause in <code>calc_excess_blob_gas()</code>. Specifically, when the reserve price is higher than <code>GAS_PER_BLOB * base_fee_per_blob_gas</code>, the function will not subtract <code>target_blob_gas</code> from <code>excess_blob_gas</code>, causing <code>excess_blob_gas</code> to increase according to <code>blob_gas_used</code>, while keeping the per-block maximum increase unchanged. The proposal ensures that the blob fee market can function properly and that blob consumers pay at least a relevant fraction of the market rate for the compute they request from nodes.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum uses a dynamic pricing auction to set the blob base fee, lowering the fee if less gas is consumed than <code>target_blob_gas = GAS_PER_BLOB * blobSchedule.target</code> and raising the fee if more gas is consumed. Such an auction can function well when the blob base fee represents the price signal, allowing the mechanism to control the real price for blob consumers. However, when execution costs dominate, the price signal is lost. The blob base fee then no longer represents a significant component of the total cost facing the consumer, and the protocol can no longer rely on the blob base fee to control the equilibrium quantity of blobs consumed.</p> <p>The current mechanism can therefore end up repeatedly lowering the blob base fee until it eventually settles at 1 wei. A change in the blob base fee of 10% may under such circumstances shift the total cost of utilizing blobspace by just 0.0000001%. Whenever demand picks up, over an hour of near-full blocks is required to restore a market-clearing equilibrium fee, 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. To alleviate this, the proposal imposes a reserve price that reflects execution costs, through a simple <code>if</code>-clause in <code>calc_excess_blob_gas()</code>.</p> <p>The reserve price also fulfills a second function. Nodes must cryptographically verify KZG <code>proofs</code> to ensure that associated <code>commitments</code> correspond to provided blobs. This process is computationally expensive. It seems desirable to ensure that blob consumers pay at least some fraction of the market rate for the compute they impose on nodes. In this context, the execution base fee reflects how in-demand nodes' compute services are at the time that blob consumers request them.</p> <p>By applying the reserve price to the blob base fee, the proposal jointly ensures that:</p> <ol> <li>The blob base fee update mechanism can function properly, by establishing a reserve price which is significant relative to L1 execution costs of blob consumers.</li> <li>Blob consumers pay at least a relevant fraction of the market rate for the compute they request from nodes, with any additional fees for data determined independently in the blob fee market.</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><code>BLOB_BASE_COST</code></td><td><code>2**13</code></td></tr> </tbody></table> <h3 id="functions">Functions</h3> <p>An <code>if</code>-clause is added to <code>calc_excess_blob_gas()</code> from <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>. The function no longer subtracts <code>target_blob_gas</code> when updating <code>excess_blob_gas</code> if the price of a <code>blob</code> is below the price of <code>BLOB_BASE_COST</code> execution gas. The <code>blobSchedule</code> for referencing target and max blobs was introduced in <a href="https://wg-eips.ritovision.com/7840/">EIP-7840</a>. The current block's <code>blobSchedule</code> is used during processing. Thus, in the first block after a fork—when calculating <code>base_fee_per_blob_gas</code> via <code>get_base_fee_per_blob_gas(parent)</code>—<code>fake_exponential()</code> must use the <em>new</em> <code>blobSchedule.baseFeeUpdateFraction</code>. Likewise, the <em>new</em> <code>blobSchedule.max</code> and <code>blobSchedule.target</code> must be used in <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> -&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 class="z-constant"> GAS_PER_BLOB</span><span class="z-keyword"> *</span><span> blobSchedule</span><span>.</span><span>target</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> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-constant"> BLOB_BASE_COST</span><span class="z-keyword"> *</span><span> parent</span><span>.</span><span>base_fee_per_gas</span><span class="z-keyword"> &gt;</span><span class="z-constant"> GAS_PER_BLOB</span><span class="z-keyword"> *</span><span> get_base_fee_per_blob_gas</span><span>(</span><span>parent</span><span>)</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> (</span><span>blobSchedule</span><span>.</span><span>max</span><span class="z-keyword"> -</span><span> blobSchedule</span><span>.</span><span>target</span><span>)</span><span class="z-keyword"> //</span><span> blobSchedule</span><span>.</span><span>max</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><h2 id="rationale">Rationale</h2> <h3 id="fee-inelasticity-and-reserve-price">Fee-inelasticity and reserve price</h3> <p>This proposal alleviates idiosyncrasies in the blob base fee auction. When a rollup's costs are dominated by execution costs for the blob-carrying transactions, ZK proof verification, or priority fees, the protocol can no longer rely on the blob base fee to control the equilibrium quantity of blobs consumed. The fee update mechanism is unaware of the full price of the goods that it regulates the price for and therefore fails to converge on equilibrium in a timely manner.</p> <p>We can express a simple real demand function for blobspace as</p> <p>$Q(b + c).$</p> <p>It maps the quantity of blobs demanded $Q$ to the blob base fee $b$ and the user's execution costs, expressed "per blob gas", $c$:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>c</span><span class="z-keyword"> =</span><span> execution_cost</span><span class="z-keyword"> *</span><span> base_fee_per_gas</span><span class="z-keyword"> /</span><span class="z-constant"> GAS_PER_BLOB</span></span></code></pre> <p>According to the <em>law of demand</em>, the lower the price $b+c$, the higher the demand. From the perspective of the blob base fee update mechanism, $c$ is fixed. If $c&gt;0$, the demand curve will therefore have an "inelasticity horizon", beyond which further reductions in $b$ no longer increase $Q$:</p> <p>$\lim_{b \to 0} Q(b + c) = Q(c).$</p> <p>In essence, the demand curve becomes a vertical line, where changes to the blob base fee $b$ no longer affect demand. Figure 1 illustrates this, with real demand curves (black to red) computed under four different execution base fees when purchasing two blobs. The hypothetical organic demand is illustrated in black. Any demand curve where execution costs are positive ($c&gt;0$) eventually becomes vertical as the blob base fee falls. The protocol also uses a long-run perfectly inelastic supply curve (vertical blue line). Therefore, relatively small shifts in organic demand or the execution base fee (arrows) can lead to dramatic shifts in the equilibrium blob base fee. Importantly, the blob base fee will simply fall to the boundary of 1 wei whenever the execution cost is too high for consumers to achieve equilibrium formation at <code>target_blob_gas</code>.</p> <p><img src="https://wg-eips.ritovision.com/7918/./assets/1.png" alt="Figure 1" /></p> <p><strong>Figure 1.</strong> Hypothetical real demand for blobspace under different execution base fees (black to red lines). When execution cost dominates, the real demand curve becomes inelastic and parallel to the supply curve, leading the equilibrium fee to change dramatically even with small shifts in the demand curve (arrows). The proposal imposes that the equilibrium (square) forms on the edges of the upper-left quadrant, at the intersection between the target supply curve and demand or along the dashed line representing possible reserve price equilibria accounting for execution costs.</p> <p>To improve the fee update mechanism, a reserve price is specified below which $b$ cannot be reduced. Specifically, we define a constant <code>BLOB_BASE_COST</code> and in <code>calc_excess_blob_gas</code> do not subtract <code>target_blob_gas</code> if:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-constant">BLOB_BASE_COST</span><span class="z-keyword"> *</span><span> base_fee_per_gas</span><span class="z-keyword"> &gt;</span><span class="z-constant"> GAS_PER_BLOB</span><span class="z-keyword"> *</span><span> base_fee_per_blob_gas</span></span></code></pre> <p>This means that the reserve blob base fee becomes <code>BLOB_BASE_COST * base_fee_per_gas / GAS_PER_BLOB</code> and that the ratio between the reserve price for the blob base fee and the execution base fee is fixed to: <code>BLOB_BASE_COST / GAS_PER_BLOB</code>. This ratio is <code>1/16</code> with the proposed constant.</p> <p>The blob fee's share of the total price will with the reserve price always be at least <code>BLOB_BASE_COST / (BLOB_BASE_COST + execution_cost)</code>. This is why the equilibrium under the reserve price (dashed line in Figure 1) is situated a constant fraction below the black organic demand curve formed under a zero execution base fee. The equilibrium (squares) must then form somewhere along the edge of the upper-left quadrant, bounded by the blue supply curve and the dashed curve representing possible reserve price equilibria under real demand.</p> <p>The demand curve could potentially be somewhat inelastic even under zero execution costs. This would however just be another reason to move forward with this proposal. Regardless of the exact shape of the demand curve—which of course will remain unknown and can vary going forward—the proposal is based on something tangible affecting blob consumers. This makes it a justified neutral bound on the blob base fee.</p> <h3 id="blob-kzg-proof-verification-cost">Blob KZG proof verification cost</h3> <p>EIP-4844 introduced the first phase of Ethereum's data availability sampling (DAS) roadmap. Validators on the consensus layer (CL) verify that the KZG <code>commitments</code> in the payload correspond to the provided <code>blobs</code> by cryptographically verifying the accompanying KZG <code>proofs</code>. Execution layer (EL) nodes must also validate the <code>tx_payload_body</code> and verify the wrapped data (blobs, commitments, and proofs) for every blob entering a node's tx pool. The computational requirements for verifying a KZG proof for an entire blob are slightly higher than those for verifying a KZG proof for a single point on that blob; the latter is the specific operation covered by the <code>POINT_EVALUATION_PRECOMPILE_GAS</code> (50000) charged to smart contracts.</p> <p><a href="https://wg-eips.ritovision.com/7594/">EIP-7594</a> introduces PeerDAS. It changes the compute requirements due to the reliance on blob cells and their individual proofs. The exact specification is not yet fully settled, but this is a rough guideline:</p> <ul> <li>EL nodes batch-verify <code>CELLS_PER_EXT_BLOB</code> (128) cell proofs for each blob before including a tx carrying that blob in their tx pool. This verification (e.g., using <code>verify_cell_kzg_proof_batch</code>) is roughly 15 times more expensive than the compute associated with a single <code>POINT_EVALUATION_PRECOMPILE_GAS</code>.</li> <li>Full nodes verify 4 custodied columns, each column containing one cell from all blobs referenced in the payload. Each column's cell proofs can be batch-verified (also applicable below).</li> <li>Supernodes verify 128 custodied columns, each column containing one cell from all blobs referenced in the payload.</li> <li>Validators between full nodes and supernodes will custody between 4-128 columns.</li> <li>Nodes peer-sample <code>SAMPLES_PER_SLOT</code> (8) columns each slot (in addition to custodied columns).</li> </ul> <p>The ability on the CL to jointly process cell proofs of a column (from all blobs) through batching reduces the compute time spent per blob as the number of blobs increases. It is further possible to batch all columns jointly or to parallelize the processing across columns. When accounting for the prospect of parallelization for the CL, it is however worth remembering that the point evaluation proof verification performed by rollups using the precompile also lends itself to parallelization. This means that a comparison between the point evaluation and the sequential processing of blobs (batched per column) is still relevant (because <em>both</em> could be parallelized).</p> <p>Figure 2 shows verification time per blob divided by the measured execution time of a single point evaluation operation (performed by the <code>VerifyKZGProof</code> precompile) for various configurations. The figure indicates that blobs under the current Fusaka PeerDAS specification will subject nodes to rather heavy compute requirements—when compared to the single point evaluation proof verification that a smart contract is charged <code>POINT_EVALUATION_PRECOMPILE_GAS</code> for. A full node would for example do the EL mempool verification for all blobs propagated p2p (15x), sample 8 columns (2x at 32 blobs when batching columns sequentially), and custody 4 designated columns (1x). How to price the KZG proof verification is however a complex question given the varying contexts in which it is performed. The proposed constant <code>BLOB_BASE_COST</code> is indicated by a green line in Figure 2. It is relatively moderate in comparison with the compute costs imposed on nodes.</p> <p><img src="https://wg-eips.ritovision.com/7918/./assets/2.png" alt="Figure 2" /></p> <p><strong>Figure 2.</strong> Verification time per blob relative to one point evaluation on an Apple M2 Max with 12 cores. The EL mempool verification (red) takes 15 times longer in the worst case, regardless of the blob target. The per-blob verification time of columns depends on the number of custodied/sampled columns and falls with an increase in the blob target due to speed-ups from processing all cells of a column jointly. The constant <code>BLOB_BASE_COST</code> is relatively moderate in comparison with the compute costs that blobs impose on nodes.</p> <h3 id="designing-for-the-future">Designing for the future</h3> <p>The price of storing a fixed amount of data has fallen over the last 80 years. Technological progress generally brings down the unit cost of data services, following Nielsen’s law and Moore’s law. The ETH-denominated price per blob should likewise fall as Ethereum increases blob throughput. This effect is reinforced because a higher aggregate ETH-denominated blob revenue (which is distributed to ETH token holders via the burn) increases the fiat-denominated value of the ETH token, ceteris paribus. There is thus an upper bound on the blob base fee—a bound that falls as Ethereum scales. The same reflexivity applies to the execution base fee.</p> <p>In this light, the proposal can be understood as a design for the future. Fixed thresholds not relating to blob quantity or the execution fee may not be sustainable. In a scenario where Ethereum sells more blobs per block, the equilibrium blob base fee should ideally have a relatively lower floor. Any fixed threshold (not relating to the execution base fee or blob quantity) would need to be gradually readjusted to retain the same relative impact.</p> <p>If Ethereum increases blob throughput by several orders of magnitude but does <em>not</em> scale blockspace, such that the execution base fee remains high, the reserve price of <code>BLOB_BASE_COST</code> execution gas would however still become too high. At 1000 blobs and 30M execution gas per block, Ethereum would derive just over 1/5th (21.5%) of its income from blob gas even when blobs are strictly sold at the reserve price. This implies a too high <code>BLOB_BASE_COST</code>, but 1000 blobs and 30M execution gas is not the trajectory that Ethereum currently is on. If Ethereum scales blockspace and blobspace roughly in synchrony, it is reasonable to expect that the reserve price remains at the desired level.</p> <h3 id="delayed-response-during-a-quick-rise-in-execution-fees">Delayed response during a quick rise in execution fees</h3> <p>When the <code>if</code> statement concludes that Ethereum operates in the execution-fee-led pricing regime, the blob base fee rises in accordance with <code>blob_gas_used * (max - target) // max</code>, without subtracting <code>target_blob_gas</code>. This is an intuitive way to return to the blob-fee-led pricing regime, retaining the same maximum fee increase while not allowing for a decrease. If the execution base fee rises quickly, there may be a few blocks before the blob base fee catches up (during which <code>target_blob_gas</code> will never be subtracted). This is arguably not an issue, and the smooth response in the blob base fee under these circumstances may even be seen as a benefit.</p> <h3 id="empirical-analysis">Empirical analysis</h3> <p>Figures 3-4 show price evolution over three weeks in November 2024, when the average execution base fee was around 16 gwei, as well as in March 2025, when the average was around 1.3 gwei. The proposed reserve fee is applied directly to the original data, without accounting for its potential effect on the equilibrium fee. The equilibrium blob base fee would in reality rise from the threshold level once demand at this fee is above target supply. EIP-7918 imposes the maximum of the two curves, indicated in darker colors.</p> <p><img src="https://wg-eips.ritovision.com/7918/./assets/3.png" alt="Figure 3" /></p> <p><strong>Figure 3.</strong> Blob base fee evolution with the current fee market (black) and the proposed reserve fee (blue), during three weeks of November 2024 when the average execution base fee was around 16 gwei. EIP-7918 imposes the maximum of the two curves, as indicated in darker colors. Thresholding is applied directly to the original data, without accounting for its effect on the equilibrium fee.</p> <p><img src="https://wg-eips.ritovision.com/7918/./assets/4.png" alt="Figure 4" /></p> <p><strong>Figure 4.</strong> Blob base fee evolution with the current fee market (black) and the proposed reserve fee (blue), during three weeks of March 2025 when the average execution base fee was around 1.3 gwei. EIP-7918 imposes the maximum of the two curves, as indicated in darker colors. Thresholding is applied directly to the original data, without accounting for its effect on the equilibrium fee.</p> <p>Figure 5 shows histograms for observed fees and the maximum of the two curves for the four-month period from November 2024 (start of Figure 3's data period) through March 2025 (end of Figure 4's data period), corresponding to approximately 900k blocks beginning at block number 22075724. The histograms employ 100 log-spaced bins per decade (factor-of-ten increase), which are smoothed using a Hanning window of width 21 with mirror-reflected edges.</p> <p><img src="https://wg-eips.ritovision.com/7918/./assets/5.png" alt="Figure 5" /></p> <p><strong>Figure 5.</strong> Histogram of the blob base fee when there is no threshold or when applying EIP-7918 (dashed combination of the darker black and blue curves from previous figures), with light smoothing applied. A four-month period from November 2024 through March 2025 was analyzed. Thresholding is applied directly to the original data, without accounting for its effect on the equilibrium fee.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The blob base fee will settle at a level where a blob costs at least <code>BLOB_BASE_COST</code> execution gas. To the best of the authors' knowledge, there are no security risks associated with 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> 2025-03-24T00:00:00+00:00 2026-02-11T14:49:27+00:00 Zsolt Felföldihttps://github.com/zsfelfoldi Caymanhttps://github.com/wemeetagain Etan Kisslinghttps://github.com/etan-status https://wg-eips.ritovision.com/7916/

SSZ types for efficiently hashing short lists

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a new Merkle tree shape for <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/simple-serialize.md">Simple Serialize (SSZ)</a> types that results in fewer hashes when only a small number of leaves is used. The new tree shape grows progressively with increased leaf count and no longer has a bounded capacity. It also offers forward compatibility: a given chunk index is always assigned the same stable <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/merkle-proofs.md#generalized-merkle-tree-index">generalized index (gindex)</a> regardless of leaf count.</p> <p>New types are defined to use the progressive Merkle tree shape: <code>ProgressiveList[type]</code> and <code>ProgressiveBitlist</code>. These new types represent lists of arbitrary length with stable merkleization, reducing hashing overhead for small lists and avoiding arbitrary capacity limits.</p> <h2 id="motivation">Motivation</h2> <p>Current SSZ <code>List[type, N]</code> types require a predefined capacity <code>N</code>, which leads to several issues:</p> <ul> <li>Inefficient hashing: Lists often contain far fewer elements than their maximum capacity (e.g., <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/bellatrix/beacon-chain.md#custom-types"><code>Transaction</code></a>), resulting in unnecessary zero-padding and dozens of extra hash computations. This is exacerbated when nesting <code>List[type, N]</code>, e.g., in a design where each of up to <code>X</code> transactions has up to <code>Y</code> access lists, each with up to <code>Z</code> storage slots.</li> <li>Arbitrary Limits: The capacity <code>N</code> is often chosen arbitrarily (e.g., <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/bellatrix/beacon-chain.md#execution"><code>MAX_BYTES_PER_TRANSACTION</code></a>, <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/bellatrix/beacon-chain.md#execution"><code>MAX_TRANSACTIONS_PER_PAYLOAD</code></a>) and set to artificially large values to anticipate future design space, which are not always correct.</li> <li>Unstable proofs: Modifying <code>N</code> across forks (e.g., <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#max-operations-per-block"><code>MAX_ATTESTER_SLASHINGS_ELECTRA</code></a>, <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#max-operations-per-block"><code>MAX_ATTESTATIONS_ELECTRA</code></a>) alters gindices, breaking downstream verifiers.</li> </ul> <p>The progressive Merkle tree shape addresses these by:</p> <ul> <li>Using a recursive tree structure that progressively grows to the actual leaf count with minimal overhead</li> <li>Dropping the notion of a maximum capacity, relying instead on practical limits, e.g., SSZ's 4 GB variable offset cap, network payload limits, gas limits, bounds on the number of signatures.</li> <li>Maintaining stable gindices for each element, ensuring provers remain valid as the leaf count changes.</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> <h3 id="progressive-merkle-tree">Progressive Merkle tree</h3> <p>The <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/simple-serialize.md#merkleization">SSZ Merkleization specification</a> is extended with a helper function:</p> <ul> <li><code>merkleize_progressive(chunks, num_leaves=1)</code>: Given ordered <code>BYTES_PER_CHUNK</code>-byte chunks: <ul> <li>The merkleization depends on the number of input chunks and is defined recursively: <ul> <li>If <code>len(chunks) == 0</code>: the root is a zero value, <code>Bytes32()</code>.</li> <li>Otherwise: compute the root using <code>hash(a, b)</code> <ul> <li><code>a</code>: Merkleize the first up to <code>num_leaves</code> chunks as a binary tree using <code>merkleize(chunks[:num_leaves], num_leaves)</code>.</li> <li><code>b</code>: Recursively merkleize chunks beyond <code>num_leaves</code> using <code>merkleize_progressive(chunks[num_leaves:], num_leaves * 4)</code>.</li> </ul> </li> </ul> </li> </ul> </li> </ul> <p>This results in a 0-terminated sequence of binary subtrees with increasing leaf count. The deepest subtree is padded with zeroed chunks (virtually for memory efficiency).</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> root</span></span> <span class="giallo-l"><span> /\</span></span> <span class="giallo-l"><span> / \</span></span> <span class="giallo-l"><span> 1: chunks[0 ..&lt; 1] /\</span></span> <span class="giallo-l"><span> / \</span></span> <span class="giallo-l"><span> 4: chunks[1 ..&lt; 5] /\</span></span> <span class="giallo-l"><span> / \</span></span> <span class="giallo-l"><span> 16: chunks[5 ..&lt; 21] /\</span></span> <span class="giallo-l"><span> / \</span></span> <span class="giallo-l"><span> 64: chunks[21 ..&lt; 85] 0</span></span></code></pre><table><thead><tr><th style="text-align: right">Depth</th><th style="text-align: right">Added chunks</th><th style="text-align: right">Total chunks</th><th style="text-align: right">Total capacity (bytes)</th></tr></thead><tbody> <tr><td style="text-align: right">0</td><td style="text-align: right">0</td><td style="text-align: right">0</td><td style="text-align: right">0</td></tr> <tr><td style="text-align: right">1</td><td style="text-align: right">1</td><td style="text-align: right">1</td><td style="text-align: right">32</td></tr> <tr><td style="text-align: right">2</td><td style="text-align: right">4</td><td style="text-align: right">5</td><td style="text-align: right">160</td></tr> <tr><td style="text-align: right">3</td><td style="text-align: right">16</td><td style="text-align: right">21</td><td style="text-align: right">672</td></tr> <tr><td style="text-align: right">4</td><td style="text-align: right">64</td><td style="text-align: right">85</td><td style="text-align: right">2'720</td></tr> <tr><td style="text-align: right">5</td><td style="text-align: right">256</td><td style="text-align: right">341</td><td style="text-align: right">10'912</td></tr> <tr><td style="text-align: right">6</td><td style="text-align: right">1'024</td><td style="text-align: right">1'365</td><td style="text-align: right">43'680</td></tr> <tr><td style="text-align: right">7</td><td style="text-align: right">4'096</td><td style="text-align: right">5'461</td><td style="text-align: right">174'752</td></tr> <tr><td style="text-align: right">8</td><td style="text-align: right">16'384</td><td style="text-align: right">21'845</td><td style="text-align: right">699'040</td></tr> <tr><td style="text-align: right">9</td><td style="text-align: right">65'536</td><td style="text-align: right">87'381</td><td style="text-align: right">2'796'192</td></tr> <tr><td style="text-align: right">10</td><td style="text-align: right">262'144</td><td style="text-align: right">349'525</td><td style="text-align: right">11'184'800</td></tr> <tr><td style="text-align: right">11</td><td style="text-align: right">1'048'576</td><td style="text-align: right">1'398'101</td><td style="text-align: right">44'739'232</td></tr> <tr><td style="text-align: right">12</td><td style="text-align: right">4'194'304</td><td style="text-align: right">5'592'405</td><td style="text-align: right">178'956'960</td></tr> <tr><td style="text-align: right">13</td><td style="text-align: right">16'777'216</td><td style="text-align: right">22'369'621</td><td style="text-align: right">715'827'872</td></tr> <tr><td style="text-align: right">14</td><td style="text-align: right">67'108'864</td><td style="text-align: right">89'478'485</td><td style="text-align: right">2'863'311'520</td></tr> <tr><td style="text-align: right">15</td><td style="text-align: right">268'435'456</td><td style="text-align: right">357'913'941</td><td style="text-align: right">11'453'246'112</td></tr> </tbody></table> <h3 id="progressivelist-type-and-progressivebitlist"><code>ProgressiveList[type]</code> and <code>ProgressiveBitlist</code></h3> <p>Two new <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/simple-serialize.md#composite-types">SSZ composite types</a> are defined:</p> <ul> <li><strong>progressive list</strong>: ordered variable-length homogeneous collection, without limit <ul> <li>notation <code>ProgressiveList[type]</code>, e.g. <code>ProgressiveList[uint64]</code></li> </ul> </li> <li><strong>progressive bitlist</strong>: ordered variable-length collection of <code>boolean</code> values, without limit <ul> <li>notation <code>ProgressiveBitlist</code></li> </ul> </li> </ul> <p>The new types are considered <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/simple-serialize.md#variable-size-and-fixed-size">"variable-size"</a>.</p> <p>For convenience we <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/simple-serialize.md#aliases">alias</a>:</p> <ul> <li><code>ProgressiveByteList</code> to <code>ProgressiveList[byte]</code></li> </ul> <p>The <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/simple-serialize.md#default-values">default value</a> is defined as:</p> <table><thead><tr><th>Type</th><th>Default Value</th></tr></thead><tbody> <tr><td><code>ProgressiveList[type]</code></td><td><code>[]</code></td></tr> <tr><td><code>ProgressiveBitlist</code></td><td><code>[]</code></td></tr> </tbody></table> <h4 id="serialization">Serialization</h4> <p>Serialization, deserialization, and JSON mapping of <code>ProgressiveBitlist</code> are identical to <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/simple-serialize.md#bitlistn"><code>Bitlist[N]</code></a>.</p> <p>Serialization, deserialization, and JSON mapping of <code>ProgressiveList[type]</code> are identical to <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/simple-serialize.md#vectors-containers-lists"><code>List[type, N]</code></a>.</p> <h4 id="merkleization">Merkleization</h4> <p>The <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/simple-serialize.md#merkleization">Merkleization</a> definitions are extended.</p> <ul> <li><code>mix_in_length(merkleize_progressive(pack(value)), len(value))</code> if <code>value</code> is a progressive list of basic objects.</li> <li><code>mix_in_length(merkleize_progressive(pack_bits(value)), len(value))</code> if <code>value</code> is a progressive bitlist.</li> <li><code>mix_in_length(merkleize_progressive([hash_tree_root(element) for element in value]), len(value))</code> if <code>value</code> is a progressive list of composite objects.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="why-a-recursive-structure">Why a recursive structure?</h3> <ul> <li>Efficiency: Small lists use fewer hashes (e.g., a 3-item list in a 16-element subtree wastes fewer hashes than a 1024-element <code>List[type, N]</code>).</li> <li>Stability: Fixed subtree sizes ensure stable gindices, avoiding the need for dynamic depth adjustments or multiple queries.</li> <li>Scalability: Recursive subtrees allow arbitrary growth without a hardcoded limit, constrained only by practical limits (e.g., network payload limit, validation rules).</li> </ul> <h3 id="why-not-dynamic-depth">Why not dynamic depth?</h3> <p>Dynamic-depth Merkleization destabilizes gindices:</p> <ul> <li>Requires two-step queries (length then gindex), increasing latency and reorg risks.</li> <li>Complicates proofs with semantic lookups.</li> </ul> <p>Mixing in successor subtrees ensures predictable gindices and proof sizes.</p> <h3 id="why-not-fixed-capacity-lists">Why not fixed-capacity lists?</h3> <p><code>List[type, N]</code>:</p> <ul> <li>Imposes arbitrary limits, hindering scalability.</li> <li>Breaks stability when redefined.</li> <li>Wastes hashes with padding (e.g., 1024-element capacity for a 1-item list). (only log(N) wasted hashes)</li> </ul> <p><code>ProgressiveList[type]</code> offers a scalable, efficient alternative.</p> <h3 id="why-are-initial-leaf-count-and-scaling-factors-not-exposed-parameters">Why are initial leaf count and scaling factors not exposed parameters?</h3> <ul> <li>Simplicity: Fixed values (initial leaf count 1, scaling factor 4) provide a sensible default that balances efficiency and usability, aligning with SSZ’s goal of simplicity.</li> <li>Future Extensibility: If specific use cases demand different values, a future EIP could introduce parameterization. For now, fixed values reduce adoption barriers and align with the principle of "good enough" defaults.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The new SSZ types coexist with existing types without conflict and share their serialization logic.</p> <h2 id="test-cases">Test Cases</h2> <ul> <li><code>ethereum/remerkleable</code> contains static tests in <code>test_impl.py</code> and <code>test_typing.py</code>.</li> <li><code>ethereum/consensus-specs</code> releases contain random tests in <code>tests/general/phase0/ssz_generic</code>, generated according to a format defined in <code>tests/format/ssz_generic</code>.</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <code>ethereum/remerkleable</code>.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>Resource limits: The <code>uint32</code> limit for variable-length offsets essentially introduces a ~4GB cap when including a <code>ProgressiveList[type]</code> or <code>ProgressiveBitlist</code> within another complex type, but practical limits (e.g., 10MB libp2p messages) apply. Implementations SHOULD enforce context-specific bounds.</li> <li>Variable proof size: Recursive traversal may increase proof sizes for large indices, though logarithmic in list size due to the scaling factor.</li> </ul> <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:28+00:00 Lin Oshitanihttps://github.com/linoscopelin@nethermind.io Justin Drakehttps://github.com/JustinDrakejustin@ethereum.org https://wg-eips.ritovision.com/7917/

Pre-calculate and store a deterministic proposer lookahead in the beacon state at the start of every epoch

<h2 id="abstract">Abstract</h2> <p>At the start of each epoch, pre-calculate and store in the <code>beacon_state</code> a deterministic <code>proposer_lookahead</code> for the next <code>MIN_SEED_LOOKAHEAD + 1</code> epochs.</p> <h2 id="motivation">Motivation</h2> <p>Unlike RANDAO seeds, which have a deterministic lookahead of at least <code>MIN_SEED_LOOKAHEAD == 1</code> epochs, the beacon proposer schedule of epoch <code>N + 1</code> is not fully predictable from the beacon state during epoch <code>N</code>. The reason is that, under certain edge cases, the effective balances (EBs) of active validators—themselves used as input for proposer election in epoch <code>N + 1</code>—can change within epoch <code>N</code>.</p> <p>Based preconfirmation protocols rely on a deterministic proposer schedule for smooth operations. Since the beacon genesis, slashings and penalties that accumulate to at least 1 ETH can change EBs of active validators and lead to an unpredictable proposer schedule despite the RANDAO seed being known ahead of time. The increase of MaxEB with <a href="https://wg-eips.ritovision.com/7251/">EIP-7251</a> increases effective balance unpredictability because rewards that accumulate to at least 1 ETH, validator consolidations, and deposits can grow EBs of active validators beyond 32 ETH.</p> <p>Besides fixing next-epoch proposer schedule non-determinism, this EIP makes it possible for the proposer schedule of the next epoch to be accessible to the application layer via the beacon root and a simple Merkle proof. This highly simplifies the implementation of on-chain components for based preconfirmation protocols.</p> <p>Introducing a fully deterministic lookahead fixes a long-standing beacon chain design oversight, as highlighted by Danny Ryan's comment below:</p> <p><img src="https://wg-eips.ritovision.com/7917/./assets/lookahead-comment.png" alt="Danny Ryan&#39;s comment on proposer lookahead" /></p> <p>With this change, it will no longer be possible for validators to grind effective balances to manipulate the proposer schedule of the next epoch, and the analysis of effective balance grinding will collapse from what is currently a subtle analysis of EB edge cases to a trivial security analysis. Finally, the proposer lookahead gives CL clients ahead-of-time visibility over the next proposer which may simplify implementations.</p> <h2 id="specification">Specification</h2> <p>The <code>BeaconState</code> container is extended with a <code>proposer_lookahead</code> field, which is a vector of validator indices covering the full visible lookahead period, starting from the beginning of the current epoch to the next <code>MIN_SEED_LOOKAHEAD</code> epochs.</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> <span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"><span> proposer_lookahead</span><span>:</span><span> Vector</span><span>[</span><span>ValidatorIndex</span><span>,</span><span> (</span><span class="z-constant">MIN_SEED_LOOKAHEAD</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> SLOTS_PER_EPOCH</span><span>]</span></span></code></pre> <p>For example, <code>proposer_lookahead[0]</code> is the validator index for the first proposer in the current epoch, <code>proposer_lookahead[SLOTS_PER_EPOCH + 4]</code> is the validator index for the fifth proposer in the next epoch, and so forth.</p> <p>The function <code>get_beacon_proposer_index</code> is modified to use the pre-calculated <code>proposer_lookahead</code> instead of calculating proposer indices on-demand.</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_beacon_proposer_index</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> BeaconState</span><span>)</span><span> -&gt;</span><span> ValidatorIndex</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"> Return the beacon proposer index at the current slot.</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-keyword"> return</span><span> state</span><span>.</span><span>proposer_lookahead</span><span>[</span><span>state</span><span>.</span><span>slot</span><span class="z-keyword"> %</span><span class="z-constant"> SLOTS_PER_EPOCH</span><span>]</span></span></code></pre> <p>At the epoch boundary, the <code>proposer_lookahead</code> is updated by shifting out the current epoch’s lookahead and appending the new one.</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_epoch</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 class="z-constant"> ...</span></span> <span class="giallo-l"><span> process_proposer_lookahead</span><span>(</span><span>state</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_proposer_lookahead</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> last_epoch_start</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span>state</span><span>.</span><span>proposer_lookahead</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> SLOTS_PER_EPOCH</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Shift out proposers in the first epoch</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>proposer_lookahead</span><span>[</span><span>:</span><span>last_epoch_start</span><span>]</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>proposer_lookahead</span><span>[</span><span class="z-constant">SLOTS_PER_EPOCH</span><span>:</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Fill in the last epoch with new proposer indices</span></span> <span class="giallo-l"><span> last_epoch_proposers</span><span class="z-keyword"> =</span><span> get_beacon_proposer_indices</span><span>(</span></span> <span class="giallo-l"><span> state</span><span>,</span><span> Epoch</span><span>(</span><span>get_current_epoch</span><span>(</span><span>state</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> MIN_SEED_LOOKAHEAD</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> state</span><span>.</span><span>proposer_lookahead</span><span>[</span><span>last_epoch_start</span><span>:</span><span>]</span><span class="z-keyword"> =</span><span> last_epoch_proposers</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_beacon_proposer_indices</span><span>(</span></span> <span class="giallo-l"><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"> epoch</span><span>:</span><span> Epoch</span></span> <span class="giallo-l"><span>)</span><span> -&gt;</span><span> Vector</span><span>[</span><span>ValidatorIndex</span><span>,</span><span class="z-constant"> SLOTS_PER_EPOCH</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"> Return the proposer indices for the given ``epoch``.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> indices</span><span class="z-keyword"> =</span><span> get_active_validator_indices</span><span>(</span><span>state</span><span>,</span><span> epoch</span><span>)</span></span> <span class="giallo-l"><span> seed</span><span class="z-keyword"> =</span><span> get_seed</span><span>(</span><span>state</span><span>,</span><span> epoch</span><span>,</span><span class="z-constant"> DOMAIN_BEACON_PROPOSER</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> compute_proposer_indices</span><span>(</span><span>state</span><span>,</span><span> epoch</span><span>,</span><span> seed</span><span>,</span><span> indices</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"> compute_proposer_indices</span><span>(</span></span> <span class="giallo-l"><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"> epoch</span><span>:</span><span> Epoch</span><span>,</span><span class="z-variable z-parameter z-function"> seed</span><span>:</span><span> Bytes32</span><span>,</span><span class="z-variable z-parameter z-function"> indices</span><span>:</span><span> Sequence</span><span>[</span><span>ValidatorIndex</span><span>]</span></span> <span class="giallo-l"><span>)</span><span> -&gt;</span><span> Vector</span><span>[</span><span>ValidatorIndex</span><span>,</span><span class="z-constant"> SLOTS_PER_EPOCH</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"> Return the proposer indices for the given ``epoch``.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> start_slot</span><span class="z-keyword"> =</span><span> compute_start_slot_at_epoch</span><span>(</span><span>epoch</span><span>)</span></span> <span class="giallo-l"><span> seeds</span><span class="z-keyword"> =</span><span> [</span><span class="z-support">hash</span><span>(</span><span>seed</span><span class="z-keyword"> +</span><span> uint_to_bytes</span><span>(</span><span>Slot</span><span>(</span><span>start_slot</span><span class="z-keyword"> +</span><span> i</span><span>)</span><span>)</span><span>)</span><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span class="z-constant">SLOTS_PER_EPOCH</span><span>)</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> [</span><span>compute_proposer_index</span><span>(</span><span>state</span><span>,</span><span> indices</span><span>,</span><span> seed</span><span>)</span><span class="z-keyword"> for</span><span> seed</span><span class="z-keyword"> in</span><span> seeds</span><span>]</span></span></code></pre> <p>Furthermore, the first block after the fork will calculate all lookaheads for epochs up to <code>MIN_SEED_LOOKAHEAD</code> ahead and fill the <code>proposer_lookahead</code> field in the beacon state.</p> <p>See the <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/cbaa0063979168a94a9c7821f366c6a221319c8e/specs/fulu/beacon-chain.md">updated beacon chain specs</a> in consensus-specs for more details.</p> <h2 id="rationale">Rationale</h2> <h3 id="considered-alternatives">Considered Alternatives</h3> <p>An alternative approach would be to cache the effective balances at the start of epoch <code>N</code> so it can be used to calculate the proposer lookahead at the start of epoch <code>N+MIN_SEED_LOOKAHEAD</code>. However, this approach would require additional footprint in the beacon state, and would not be able to provide the proposer lookahead to the EVM via the beacon root.</p> <h3 id="single-secret-leader-election-compatibility">Single Secret Leader Election Compatibility</h3> <p>In the future, we may introduce a Single Secret Leader Election (SSLE) mechanism in which only the selected validator knows their role until they propose a block. However, current SSLE designs still rely on a lookahead, albeit an encrypted one. In such designs, we could reuse the <code>proposer_lookahead</code> field by changing its type to something like <code>List[EncryptedValidatorIndex]</code>. And if a construction were to remove lookahead entirely, we could simply set <code>proposer_lookahead</code> to an empty list, meaning this wouldn’t be a blocker.</p> <p>That said, any such changes would introduce additional complexity around preconfirmation protocols, but that complexity arises regardless of this EIP. Furthermore, APS (Attester Proposer Separation) envisions more sophisticated (i.e., more DDoS‑resistant) execution proposers, reducing the need for SSLE.</p> <h3 id="added-computation-at-the-epoch-boundary">Added Computation at the Epoch Boundary</h3> <p>Before this EIP, consensus clients only needed to compute the current proposer’s index at each slot. With the changes introduced by this EIP, they must calculate the entire epoch’s proposer schedule at the start of each epoch. However, computing the proposer index is light, involving sampling validators until we reach a validator with sufficient effective balance to be selected as a proposer. Still, testing is needed to confirm that these additional calculations do not create performance bottlenecks in practice.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="test-cases">Test Cases</h2> <p>See <a rel="external" href="https://github.com/ethereum/consensus-specs/tree/cbaa0063979168a94a9c7821f366c6a221319c8e/tests/core/pyspec/eth2spec/test/fulu">the spec tests</a> in consensus-specs.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="malicious-lookahead-alteration">Malicious Lookahead Alteration</h3> <p>A critical consideration for any proposer election mechanism is preventing validators from manipulating lookahead to gain an unfair advantage. This proposal does not increase the chances of such attacks, as we do not alter the “RANDAO delay” used in the lookahead—the lookahead of epoch <code>N</code> is still determined by the RANDAO of epoch <code>N - MIN_SEED_LOOKAHEAD - 1</code> (which becomes available at the start of epoch <code>N - MIN_SEED_LOOKAHEAD</code>). The only difference is that it changes the “effective balances delay”: rather than using the effective balances (EB) at the start of epoch <code>N</code>, it now uses the EB at the start of epoch <code>N - MIN_SEED_LOOKAHEAD</code>.</p> <p>Furthermore, by aligning the RANDAO and effective balances in this way, the proposal removes any chance of validators adjusting their EB after seeing the RANDAO outcome, which is an attack vector to consider. No such attack has been found so far, but this change removes the possibility, hence simplifying the security analysis.</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-21T00:00:00+00:00 2026-02-11T14:48:25+00:00 Hadrien Crouboishttps://github.com/Amxx Ernesto Garcíahttps://github.com/ernestognw Francisco Giordanohttps://github.com/frangio Aryeh Greenberghttps://github.com/arr00 https://wg-eips.ritovision.com/7913/

Interface for the verification of signatures by address-less keys

<h2 id="abstract">Abstract</h2> <p>Externally Owned Accounts (EOA) can sign messages with their associated private keys. Additionally <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> defines a method for signature verification by smart accounts such as multisig. In both cases the identity of the signer is an ethereum address. We propose a standard to extend this concept of signer description, and signature verification, to keys that do not have an ethereum identity of their own, in the sense that they don't have their own address to represent them.</p> <p>This new mechanism can be used to integrate new signers such as non-ethereum cryptographic curves, hardware devices, or even email addresses. This is particularly relevant when dealing with things like social-recovery of smart accounts.</p> <h2 id="motivation">Motivation</h2> <p>With the development of account abstraction, there is an increasing need for non-ethereum signature verification. Cryptographic algorithms besides the natively supported secp256k1 are being used for controlling smart accounts. In particular, curves such as secp256r1 (supported by many mobile devices) and RSA keys (that are distributed by traditional institutions) are widely available. Beyond these two examples, we also see the emergence of ZK solutions for signing with emails or JWT from big Web2 services.</p> <p>All these signature mechanisms have one thing in common: they do not have a canonical ethereum address to represent them onchain. While users could deploy ERC-1271 compatible contracts for each key individually, this would be cumbersome and expensive. As account abstraction tries to separate account addresses (that hold assets) from the key that controls them, giving fixed on-chain addresses to keys (and possibly sending assets to these addresses by mistake) is not the right approach. Instead, using a small number of verifier contracts that can process signatures in a standard way, and having the accounts rely on these verifiers, feels like the correct approach. This has the advantage that once the verifier is deployed, any key can be represented using a <code>(verifier, key)</code> pair without requiring any setup cost.</p> <p>The <code>(verifier, key)</code> pairs can be given permission to control a smart account, perform social recovery, or do any other operation without ever having a dedicated on-chain address. Systems that want to adopt this approach need to transition away from the model where signers are identified by their address to a new model where signers may not have an address, and are identified by a <code>bytes</code> object.</p> <p>This definition is backward compatible with EOA and ERC-1271 contracts: in that case, we use the address of the identity (EOA or contract) as the verifier and the key is empty.</p> <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="nomenclature">Nomenclature</h3> <ul> <li>Keys are represented using <code>bytes</code> objects of arbitrary length. For example a P256 or RSA public key. Keys MUST NOT be empty.</li> <li>Verifiers are smart contracts in charge of signature verification for a given type of key. They have an ethereum address.</li> </ul> <h3 id="signature-verifier-interface">Signature Verifier interface</h3> <p>Verifiers 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"> IERC7913SignatureVerifier</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"> Verifies `signature` as a valid signature of `hash` by `key`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return the bytes4 magic value 0x024ad318 (IERC7913SignatureVerifier.verify.selector) if the signature is valid.</span></span> <span class="giallo-l"><span class="z-comment"> * SHOULD return 0xffffffff or revert if the signature is not valid.</span></span> <span class="giallo-l"><span class="z-comment"> * SHOULD return 0xffffffff or revert if the key 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"> verify</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> key</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> hash</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 class="z-storage z-type"> view</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> <p>Verifiers SHOULD be stateless.</p> <h2 id="rationale">Rationale</h2> <p>Verifiers can be used to avoid deploying many ERC-1271 "identity contract" (one per key), which would be expensive. Using this model, new keys can be used without any deployment costs.</p> <p>ERC-1271 already covers the cases were a key is not necessary. To avoid ambiguity, the verifiers contracts should not support (or be expected to support) empty keys. Signers that are 20 bytes long (empty key) should be handled using ERC-1271.</p> <p>Consistency with existing systems (ecrecover and ERC-1271) requires the message to be <code>bytes32</code> hash. These are usually produced following <a href="https://wg-eips.ritovision.com/191/">ERC-191</a> or <a href="https://wg-eips.ritovision.com/712/">ERC-712</a>. Cryptographic systems that use different hashing methods SHOULD see this hash as a message, and possibly rehash it following the relevant standards.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>A system can support <a href="https://wg-eips.ritovision.com/7913/">ERC-7913</a> signers alongside EOAs and ERC-1271 in the following way.</p> <p>A signer is a <code>bytes</code> object that is the concatenation of an address and optionally a key: <code>verifier || key</code>. A signer is at least 20 bytes long.</p> <p>Given a signer <code>signer</code>, a message hash <code>hash</code>, and a signature <code>sign</code>, verification is done as follows:</p> <ul> <li>if <code>signer.length &lt; 20</code>: verification fails;</li> <li>split <code>signer</code> into <code>(verifier, key)</code> with <code>verifier</code> being the first 20 bytes and <code>key</code> being the rest (potentially empty)</li> <li>if <code>key</code> is empty, then consider that <code>verifier</code> is the identity. <ul> <li>verification is done using ERC-1271's isValidSignature if there is code at <code>verifier</code> address, or ecrecover otherwise</li> </ul> </li> <li>if <code>key</code> is not empty, call <code>IERC7913SignatureVerifier(verifier).verify(key, hash, signature)</code> <ul> <li>if the return value is the expected magic value (<code>0x024ad318</code>) then verification is successful,</li> <li>otherwise, verification fails.</li> </ul> </li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>In solidity, signature verification could be implemented in the following library:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">SignatureChecker</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &#39;@openzeppelin/contracts/utils/cryptography/SignatureChecker.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"> @dev</span><span class="z-comment"> Extention of openzeppelin&#39;s SignatureChecker library</span></span> <span class="giallo-l"><span class="z-storage z-type">library</span><span class="z-entity z-name"> SignatureCheckerExtended</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isValidSignatureNow</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> signer</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> hash</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"> 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-keyword"> if</span><span> (</span><span>signer</span><span>.</span><span>length </span><span class="z-keyword">&lt;</span><span class="z-constant"> 20</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 class="z-keyword"> if</span><span> (</span><span>signer</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 20</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> SignatureChecker</span><span>.</span><span class="z-entity z-name">isValidSignatureNow</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-support">bytes20</span><span>(</span><span>signer</span><span>)</span><span>)</span><span>,</span><span> hash</span><span>,</span><span> signature</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"> try</span><span class="z-entity z-name"> IERC7913SignatureVerifier</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-support">bytes20</span><span>(</span><span>signer</span><span>[</span><span class="z-constant">0</span><span class="z-keyword">:</span><span class="z-constant">20</span><span>]</span><span>)</span><span>)</span><span>)</span><span>.</span><span class="z-entity z-name">verify</span><span>(</span><span>signer</span><span>[</span><span class="z-constant">20</span><span class="z-keyword">:</span><span>]</span><span>,</span><span> hash</span><span>,</span><span> signature</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes4</span><span class="z-variable"> magic</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> magic </span><span class="z-keyword">==</span><span> IERC7913SignatureVerifier</span><span>.</span><span>verify</span><span>.</span><span>selector</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 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></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Signer may be used for anything from smart account session key (with a short lifetime of a few hours/days) to social recovery "guardians" that may only be used several years after they are setup. In order to ensure that these signers remain valid "in perpetuity", the verifier contract should be trustless. This means that the verifiers should not be upgradeable contracts.</p> <p>Verifiers should also not depend on any value that can be modified after deployment. In solidity terms, the <code>verify</code> function should be pure. Any parameters that are involved in signature verification should either be part of the key, or part of immutable code of the verifier. Using <code>immutable</code> variable (in solidity) would be safe. The stateless aspect of the verifier also ensure compliance (of the verifier) with <a href="https://wg-eips.ritovision.com/7562/">ERC-7562</a> scope rules.</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-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Sola Ogunsakinhttps://github.com/sola92 https://wg-eips.ritovision.com/7920/

A scheme for signing multiple typed-data messages with a single signature

<h2 id="abstract">Abstract</h2> <p>This ERC provides a standard for signing multiple typed-data messages with a single signature by encoding them into a Merkle tree. This allows components to independently verify messages, without requiring full knowledge of the others. It provides a significant UX improvement by reducing the number of signature prompts to one, while preserving the security and flexibility of the <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> standard.</p> <p>This ERC also gives applications the flexibility to verify messages in isolation, or in aggregate. This opens up new verification modalities: for e.g, an application can require that message (<code>x</code>) is only valid when signed in combination message (<code>y</code>).</p> <h2 id="motivation">Motivation</h2> <p>As the ecosystem moves towards ETH-less transactions, users are often required to sign multiple off-chain messages in quick succession. Typically, a first signature is needed for a precise spend allowance (via Permit2, <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a>, etc.), followed by subsequent messages to direct the use of funds. This creates a frictional user experience as each signature requires a separate wallet interaction and creates confusion about what, in aggregate, is being approved.</p> <p>Current solutions have significant drawbacks:</p> <ul> <li><strong>Pre-approving <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> allowance:</strong> spend creates security vulnerabilities</li> <li><strong>Merging multiple messages into a single message:</strong> prevents independent verifiability. Each message cannot be verified without knowledge of the entire batch</li> <li><strong>Separate signature requests:</strong> creates friction in the user experience</li> </ul> <p>This ERC has the following objectives:</p> <h3 id="single-signature">Single Signature</h3> <p>A single signature should cover multiple messages</p> <h3 id="isolated-verification">Isolated Verification</h3> <p>Messages should be independently verifiable without knowledge of others</p> <h3 id="human-readable">Human-readable</h3> <p>Readability benefits of EIP-712 should be preserved. Giving wallets and users insight into what is being signed.</p> <h2 id="specification">Specification</h2> <h3 id="overview">Overview</h3> <p>The composite signature scheme uses a Merkle tree to hash multiple typed-data data messages together under a single root. The user signs only the Merkle root. The process is described below.</p> <h3 id="generating-a-composite-signature">Generating a Composite Signature</h3> <ol> <li> <p>For a set of messages <code>[m₁, m₂, ..., mₙ]</code>, encode each using EIP-712's <code>encode</code> and compute its hash:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>hashₙ = keccak256(encode(mₙ))</span></span></code></pre></li> <li> <p>Use these message hashes as leaf nodes in a Merkle tree and compute a <code>merkleRoot</code></p> </li> <li> <p>Sign the merkle root.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>signature = sign(merkleRoot)</span></span></code></pre></li> </ol> <h3 id="verification-process">Verification Process</h3> <p>To verify that an individual message <code>mₓ</code> was included in a composite signature:</p> <ol> <li> <p>Verify the signature on the <code>merkleRoot</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>recoveredSigner = ecrecover(merkleRoot, signature)</span></span> <span class="giallo-l"><span>isValidSignature = (recoveredSigner == expectedSigner)</span></span></code></pre></li> <li> <p>Compute the leaf node for message <code>mₓ</code> and verify its path to the Merkle root, using the proof:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>leaf = keccak256(encode(mₓ))</span></span> <span class="giallo-l"><span>isValidProof = _verifyMerkleProof(leaf, merkleProof, merkleRoot)</span></span></code></pre></li> </ol> <p>Where <code>_verifyMerkleProof()</code> is defined as:</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"> _verifyMerkleProof</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> leaf</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> proof</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> merkleRoot</span></span> <span class="giallo-l"><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>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> computedRoot </span><span class="z-keyword">=</span><span> leaf</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> proof</span><span>.</span><span>length</span><span>;</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>i</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>computedRoot </span><span class="z-keyword">&lt;</span><span> proof</span><span>[</span><span>i</span><span>]</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> computedRoot </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>computedRoot</span><span>,</span><span> proof</span><span>[</span><span>i</span><span>]</span><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> computedRoot </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>proof</span><span>[</span><span>i</span><span>]</span><span>,</span><span> computedRoot</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-keyword"> return</span><span> computedRoot </span><span class="z-keyword">==</span><span> merkleRoot</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The message is verified if and only if (1) and (2) succeed.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>isVerified = isValidSignature &amp;&amp; isValidProof</span></span></code></pre><h3 id="specification-of-eth-signtypeddata-v5-json-rpc-method">Specification of <code>eth_signTypedData_v5</code> JSON RPC method.</h3> <p>This ERC adds a new method <code>eth_signTypedData_v5</code> to Ethereum JSON-RPC. This method allows signing multiple typed data messages with a single signature using the specification described above. The signing account must be prior unlocked.</p> <p>This method returns: the signature, merkle root, and an array of proofs (each corresponding to an input message).</p> <h4 id="parameters">Parameters</h4> <ol> <li><code>Address</code> - Signing account</li> <li><code>TypedData | TypedDataArray</code> - A single TypedData object or Array of <code>TypedData</code> objects from EIP-712.</li> </ol> <h5 id="returns">Returns</h5> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> signature</span><span>:</span><span class="z-punctuation z-definition z-string"> `</span><span class="z-string">0x</span><span class="z-string">${</span><span class="z-variable z-other">string</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">`</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex encoded 65 byte signature (same format as eth_sign)</span></span> <span class="giallo-l"><span class="z-entity z-name"> merkleRoot</span><span>:</span><span class="z-punctuation z-definition z-string"> `</span><span class="z-string">0x</span><span class="z-string">${</span><span class="z-variable z-other">string</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">`</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 32 byte Merkle root as hex string</span></span> <span class="giallo-l"><span class="z-entity z-name"> proofs</span><span>:</span><span class="z-variable z-other"> Array</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">Array</span><span class="z-keyword">&lt;</span><span class="z-punctuation z-definition z-string">`</span><span class="z-string">0x</span><span class="z-string">${</span><span class="z-variable z-other">string</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">`</span><span class="z-keyword">&gt;&gt;</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Array of Merkle proofs (one for each input message)</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="example">Example</h5> <p>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">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_signTypedData_v5</span><span class="z-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">0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826</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-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">Person</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">wallet</span><span class="z-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">Mail</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">from</span><span class="z-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">Person</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">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">Person</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">contents</span><span class="z-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 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">Mail</span><span class="z-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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Ether Mail</span><span class="z-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-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">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">verifyingContract</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC</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">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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Cow</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">wallet</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826</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">to</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">Bob</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">wallet</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB</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">contents</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Hello, Bob!</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">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">Transfer</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">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></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 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">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">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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Ether Mail</span><span class="z-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-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">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">verifyingContract</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC</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">amount</span><span class="z-support">&quot;</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 class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">recipient</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB</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">id</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> <p>Result:</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">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> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">signature</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">0x4355c47d63924e8a72e509b65029052eb6c299d53a04e167c5775fd466751c9d07299936d304c153f6443dfa05f40ff007d72911b6f72307f996231605b915621c</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">merkleRoot</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">0x7de103665e21d6c9d9f82ae59675443bd895ed42b571c7f952c2fdc1a5b6e8d2</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">proofs</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-punctuation z-definition z-string">&quot;</span><span class="z-string">0x4bdbac3830d492ac3f4b0ef674786940fb33481b32392e88edafd45d507429f2</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-punctuation z-definition z-string">&quot;</span><span class="z-string">0x95be87f8abefcddc8116061a06b18906f32298a4644882d06baff852164858c6</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 choice of using a Merkle tree to bundle messages provides the following additional benefits:</p> <h3 id="efficient-verification-on-chain">Efficient verification on-chain</h3> <p><code>_verifyMerkleProof</code> has a runtime of <code>O(log2(N))</code> where N is the number of messages that were signed.</p> <h3 id="flexible-verification-modes">Flexible Verification Modes</h3> <p>Applications can require combination of messages be signed together to enhance security.</p> <h3 id="n-1-backwards-compatibility"><code>N=1</code> backwards compatibility</h3> <p>Merkle signature for single message bundles are equal to <code>eth_signTypedData_v4</code>. Requiring no onchain changes.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>When the number of message is one, <code>eth_signTypedData_v5</code> produces the same signature as <code>eth_signTypedData_v4</code> since <code>merkleRoot == keccak256(encode(message))</code>. This allows <code>eth_signTypedData_v5</code> to be a drop-in replacement for <code>eth_signTypedData_v4</code> with no changes to on-chain verification.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="eth-signtypeddata-v5"><code>eth_signTypedData_v5</code></h3> <p>Reference implementation of <code>eth_signTypedData_v5</code> can be found the <a href="https://wg-eips.ritovision.com/7920/./assets/src/eth_signTypedData_v5.ts">assets directory</a>.</p> <h3 id="verifier">Verifier</h3> <p>Solidity implementation of a onchain verifier can be found the <a href="https://wg-eips.ritovision.com/7920/./assets/contracts/ExampleVerifier.sol">assets directory</a>.</p> <h3 id="merkle">Merkle</h3> <p>Reference Merkle tree can be found in the <a href="https://wg-eips.ritovision.com/7920/./assets/src/merkle.ts">assets directory</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="replay-protection">Replay Protection</h3> <p>This ERC focuses on generating composite messages and verifying their signatures. It does not contain mechanisms to prevent replays. Developers <strong>must</strong> ensure their applications can handle receiving the same message twice.</p> <h3 id="partial-message-verification">Partial Message Verification</h3> <p>During verification, care <strong>must</strong> be taken to ensure that <strong>both</strong> of these checks pass:</p> <ol> <li>EIP-712 signature on the Merkle root is valid</li> <li>Merkle proof is valid against the root</li> </ol> <h3 id="user-understanding">User Understanding</h3> <p>Wallets <strong>must</strong> communicate to users that they are signing multiple messages at once. Wallets <strong>must</strong> display of all message types before signing.</p> <p>To ensure batch signature requests are digestible, it is recommended to limit the maximum number of messages to 10.</p> <h3 id="merkle-tree-construction">Merkle Tree Construction</h3> <p>Merkle tree should be constructed in a consistent manner.</p> <ol> <li>The hashing function <strong>must</strong> be <code>keccak256</code></li> <li>To ensure predictable/consistent proof sizes, implementations <strong>must</strong> pad leaves with zero hashes to reach next power of two to ensure balance. Let <code>n</code> be the number of messages. Before constructing the tree, compute the smallest <code>k</code> such that <code>2^(k-1) &lt; n ≤ 2^k</code>. Insert zero hashes into the list of messages until list of messages is equal to <code>2^k</code>.</li> <li>To ensure an implicit verification path, pairs <strong>must</strong> be sorted lexicographically before constructing parent hash.</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> 2025-03-19T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ryo Hahttps://github.com/sopia19910sopia19910@gmail.com Khajiev Nizomjonhttps://github.com/khajievNnizom7812@gmail.com https://wg-eips.ritovision.com/7911/

Improving Ethereum scalability and privacy using Perceptron Trees to compress transaction data via ZKP.

<h2 id="abstract">Abstract</h2> <p>This project proposes a method to enhance scalability and privacy protection in the Ethereum network using a Perceptron Tree-based Zero-Knowledge Proof (ZKP) model. The Perceptron Tree, a hybrid model combining the strengths of decision trees and perceptron neural networks, provides a compressed representation for transaction relationships, facilitating efficient verification. It addresses specific drawbacks of existing zk-SNARK and zk-STARK methods, consolidating multiple transactions into a single proof to reduce gas fees and decrease on-chain verification load.</p> <h2 id="motivation">Motivation</h2> <p>The significant increase in blockchain transactions has resulted in scalability limitations and privacy issues. Existing ZKP methods effectively validate individual transactions but fall short in analyzing inter-transaction relationships while maintaining privacy.</p> <p>ZK-Rollups bundle multiple transactions off-chain into a single proof submitted to the Ethereum mainnet, improving throughput and reducing costs. However, current batching approaches verify transactions individually without leveraging inter-transaction patterns or relationships.</p> <p>Existing privacy solutions generate separate ZK proofs for each transaction, limiting ZKP's full potential. The proposed Perceptron Tree model overcomes these limitations by measuring the similarity among multiple transactions and compressing them into a unified proof, thus broadening ZKP applications.</p> <h2 id="specification">Specification</h2> <h3 id="1-tree-construction">1. Tree Construction</h3> <p>The system inputs a transaction dataset T = {x₁, x₂, ..., xₙ} to construct a recursive tree.</p> <ul> <li> <p>Each node classifies transaction data using a perceptron with a linear function:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>f(x) = step(Wₐ·a + Wᵦ·b + θ)</span></span></code></pre> <p>where the step function is defined as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>step(z) = {</span></span> <span class="giallo-l"><span> 1, if z ≥ 0</span></span> <span class="giallo-l"><span> 0, if z &lt; 0</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><img src="https://wg-eips.ritovision.com/7911/./assets/20250319_203521.png" alt="Perceptron Tree ZKP Process" /></p> </li> <li> <p>Tree construction recursively partitions nodes based on conditions like homogeneity (isPure) or maximum depth (maxDepth).</p> <p><img src="https://wg-eips.ritovision.com/7911/./assets/20250319_203546.png" alt="Perceptron Tree ZKP Process" /></p> </li> </ul> <h3 id="2-relationship-similarity-calculation">2. Relationship Similarity Calculation</h3> <h4 id="path-similarity">Path Similarity</h4> <p>Measures similarity by the ratio of shared paths between two transactions within the tree:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>sim_path(xᵢ, xⱼ) = d/D</span></span></code></pre> <p>Where:</p> <ul> <li>d = length of shared path</li> <li>D = maximum depth of the tree</li> </ul> <p><img src="https://wg-eips.ritovision.com/7911/./assets/20250319_203429.png" alt="Path Similarity Example" /></p> <p>Example: If transactions x₁ and x₂ share only the root node (d=1) in a tree of depth 3, their similarity would be 1/3 ≈ 0.33.</p> <h4 id="vector-space-similarity">Vector Space Similarity</h4> <p>Uses cosine similarity calculated from the feature vectors of each transaction:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>sim_cos(xᵢ, xⱼ) = (xᵢ·xⱼ)/(‖xᵢ‖‖xⱼ‖)</span></span></code></pre> <p><img src="https://wg-eips.ritovision.com/7911/./assets/20250319_203500.png" alt="Vector Similarity Example" /></p> <p>Example: For vectors x₁ = [0.7, 0.8] and x₂ = [0.9, 0.4], the similarity is 0.91.</p> <h3 id="3-zkp-proof-generation">3. ZKP Proof Generation</h3> <p>The process follows five key steps:</p> <ol> <li> <p><strong>Construct Perceptron Tree</strong>: Build a tree based on transaction set T and train perceptrons at each node.</p> </li> <li> <p><strong>Calculate Node Commitments</strong>: Compute a commitment value Cₙ for each node n using weights Wₙ, bias bₙ, and hashes of left/right child nodes:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Cₙ = H(Wₙ, bₙ, Cₗₑₜₜ, Cᵣᵢₑₕₜ)</span></span></code></pre></li> <li> <p><strong>Generate Path Proof</strong>: For a specific transaction xᵢ, demonstrate the classification path within the tree.</p> </li> <li> <p><strong>Prove Similarity Threshold</strong>: Prove that the similarity between two transactions xᵢ and xⱼ exceeds a predefined threshold θ.</p> </li> <li> <p><strong>Construct Final ZKP Proof</strong>: The final Zero-Knowledge Proof Π includes:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Π = {Cᵣₒₒₜ, path(xᵢ), sim(xᵢ, xⱼ)}</span></span></code></pre> <p>Where Cᵣₒₒₜ is the root commitment, path(xᵢ) is the path proof of xᵢ, and sim(xᵢ, xⱼ) is the similarity proof between transactions.</p> </li> </ol> <p><img src="https://wg-eips.ritovision.com/7911/./assets/20250319_203626.png" alt="ZKP Generation Process" /></p> <h3 id="4-on-chain-verification">4. On-chain Verification</h3> <p>Smart contracts verify the submitted proof (Π) by checking:</p> <ul> <li> <p>The Cᵣₒₒₜ commitment matches the pre-registered tree root hash</p> </li> <li> <p>The transaction xᵢ is correctly classified along the provided path(xᵢ)</p> </li> <li> <p>The similarity between two transactions meets the predefined threshold θ</p> </li> </ul> <h2 id="rationale">Rationale</h2> <p>The Perceptron Tree-based ZKP model extends the capabilities of existing zero-knowledge proof techniques by incorporating transaction relationships into the proof structure. Traditional zk-SNARK and zk-STARK methods validate individual transactions but do not leverage inter-transaction similarity, which can lead to inefficiencies.</p> <p>By structuring transactions using a Perceptron Tree, this model enables compression of multiple transactions into a single proof, reducing gas fees and improving on-chain verification efficiency. The use of a perceptron-based decision structure ensures adaptability to various transaction patterns, making it a scalable solution for Ethereum.</p> <p>This proposal operates at the smart contract level, requiring no modifications to the existing Ethereum protocol or consensus algorithm. It can be implemented alongside existing transaction verification methods, allowing optional adoption without network upgrades.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li> <p><strong>Privacy Protection</strong>: Verifies transaction validity without revealing specific transaction details.</p> </li> <li> <p><strong>Tamper Resistance</strong>: Uses commitment values based on tree structures and weights to detect data tampering.</p> </li> <li> <p><strong>Replay Attack Prevention</strong>: Includes unique transaction IDs in proofs to avoid replay attacks.</p> </li> <li> <p><strong>Lightweight Verification</strong>: Ensures efficient, simple proof verification operations within smart contracts, minimizing gas fees.</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> 2025-03-18T00:00:00+00:00 2026-02-11T14:49:27+00:00 Danno Ferrinhttps://github.com/shemnon https://wg-eips.ritovision.com/7910/

A JSON-RPC method that describes the configuration of the current and next fork

<h2 id="abstract">Abstract</h2> <p>This document describes an RPC method that provides node-relevant configuration data for the current, next, and last known forks.</p> <h2 id="motivation">Motivation</h2> <p>Throughout Ethereum's history, there have been multiple instances where a client was not correctly configured for an upcoming hard fork, causing it to fall out of consensus when the fork boundary was crossed. Most incidents have been minor, such as a single client forking the chain in proof-of-work or having its blocks orphaned in proof-of-stake.</p> <p>The most significant occurrence was during the Pectra activation on the Holešky testnet. Four out of six clients on the network had an incorrect configuration for the deposits contract. Instead of being orphaned, the incorrect chain was justified, and the side effects persist on Holešky even after reaching finality.</p> <p>By providing an RPC method that allows clients to report key configuration variables before the next hard fork, operations teams can gain greater confidence that clients are correctly configured and prepared for upcoming forks.</p> <h3 id="target-audience-and-use-cases">Target Audience and Use Cases</h3> <p>This method is intended for node operators, validator teams, and network monitoring tools to verify client readiness for upcoming forks. Use cases include:</p> <ul> <li>Automated pre-fork validation scripts comparing <code>eth_config</code> outputs across nodes.</li> <li>Manual checks by validator operators to ensure alignment with fork specifications.</li> <li>Debugging by client developers to identify configuration mismatches.</li> <li>Automated checks by Consensus Layer counterparties.</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>Clients MUST expose a new RPC method to report the current functional configuration and the expected next configuration via the standard JSON-RPC port.</p> <p>Clients MAY also expose this method through the Engine API.</p> <p>Clients MAY use these configuration objects to manage their per-fork configurations, though they SHOULD NOT simply return unprocessed configuration data.</p> <p>When reporting the current, next and last configurations, clients MUST include every configuration parameter specified in this EIP.</p> <p>Clients MUST return up-to-date configuration values, reflecting the most recent block header they provide. If clients cache the configuration, they MUST ensure such caches are purged when fork boundaries are crossed.</p> <h3 id="configuration-rpc">Configuration RPC</h3> <p>A new JSON-RPC API, <code>eth_config</code>, is introduced. It takes no parameters and returns the result object specified in the next section.</p> <h3 id="result-object-structure">Result Object Structure</h3> <p>The RPC response contains three members: "current", "next", and "last". These members contain the configuration object currently in effect, the next configuration, and the last known configuration, respectively. "next" and "last" will be <code>null</code> if the client is not configured to support a future fork. "next" and "last" members will contain the same configuration in the case where the next configured fork is also the last configured fork.</p> <h3 id="members-of-the-configuration-object">Members of the Configuration Object</h3> <p>Each configuration object MUST contain the following members, presented in alphabetical order. This RPC assumes the network is post-merge, and no accommodations are specified for proof-of-work-related issues.</p> <p>Future forks may add, adjust, remove, or update members. The respective changes MUST be defined in either their EIPs or their respective meta-EIPs. Added members MUST be alphabetically sorted, so simply naming the new members is sufficient definition.</p> <h4 id="activationtime"><code>activationTime</code></h4> <p>The fork activation timestamp, represented as a JSON number in Unix epoch seconds (UTC). For the "current" configuration, this reflects the actual activation time; for "next" and "last", it is the scheduled time.</p> <p>Activation time is required. If a fork is activated at genesis, the value <code>0</code> is used. If the fork is not scheduled to be activated or its activation time is unknown, it should not be in the RPC results.</p> <h4 id="blobschedule"><code>blobSchedule</code></h4> <p>The blob configuration parameters for the specific fork, as defined in the genesis file. This is a JSON object with three members—<code>baseFeeUpdateFraction</code>, <code>max</code>, and <code>target</code>—all represented as JSON numbers.</p> <h4 id="chainid"><code>chainId</code></h4> <p>The chain ID of the current network, presented as a string with an unsigned <code>0x</code>-prefixed hexadecimal number, with all leading zeros removed, in lower case. This specification does not support chains without a chain ID or with a chain ID of zero.</p> <p>For purposes of canonicalization, this value must always be a string.</p> <h4 id="forkid"><code>forkId</code></h4> <p>The <code>FORK_HASH</code> value as specified in <a href="https://wg-eips.ritovision.com/6122/">EIP-6122</a> of the specific fork, presented as an unsigned <code>0x</code>-prefixed hexadecimal number, with zeros left-padded to a four-byte length, in lower case.</p> <h4 id="precompiles"><code>precompiles</code></h4> <p>A representation of the active precompile contracts for the fork. If a precompiled contract is replaced by an on-chain contract—or removed—then it is not included.</p> <p>This is a JSON object where the members are the agreed-upon names for each contract, typically specified in the EIP defining that contract, and the values are the 20-byte <code>0x</code>-prefixed hexadecimal addresses of the precompiles (with zeros preserved), in lower case.</p> <p>For Cancun, the contract names are (in order): <code>ECREC</code>, <code>SHA256</code>, <code>RIPEMD160</code>, <code>ID</code>, <code>MODEXP</code>, <code>BN254_ADD</code>, <code>BN254_MUL</code>, <code>BN254_PAIRING</code>, <code>BLAKE2F</code>, <code>KZG_POINT_EVALUATION</code>.</p> <p>For Prague, the added contracts are (in order): <code>BLS12_G1ADD</code>, <code>BLS12_G1MSM</code>, <code>BLS12_G2ADD</code>, <code>BLS12_G2MSM</code>, <code>BLS12_PAIRING_CHECK</code>, <code>BLS12_MAP_FP_TO_G1</code>, <code>BLS12_MAP_FP2_TO_G2</code>.</p> <p>For Osaka, the added contract is: <code>P256VERIFY</code>.</p> <h4 id="systemcontracts"><code>systemContracts</code></h4> <p>A JSON object representing system-level contracts relevant to the fork, as introduced in their defining EIPs. Keys are the contract names (e.g., <code>BEACON_ROOTS_ADDRESS</code>) from the first EIP where they appeared, sorted alphabetically. Values are 20-byte addresses in <code>0x</code>-prefixed hexadecimal form, with leading zeros preserved, in lower case. Omitted for forks before Cancun.</p> <p>For Cancun, the only system contract is <code>BEACON_ROOTS_ADDRESS</code>.</p> <p>For Prague, the system contracts are (in order) <code>BEACON_ROOTS_ADDRESS</code>, <code>CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</code>, <code>DEPOSIT_CONTRACT_ADDRESS</code>, <code>HISTORY_STORAGE_ADDRESS</code>, and <code>WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</code>.</p> <p>Future forks MUST define the list of system contracts in their meta-EIPs.</p> <h3 id="blob-parameter-only-bpo-forks">Blob Parameter Only (BPO) Forks</h3> <p>BPO forks should be interpreted as new forks, taking the parent fork as base (recursively, if the parent fork is also a BPO) and updating only the appropriate values in the <code>blobSchedule</code> object to produce the new fork configuration.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-enumerate-precompiles-and-in-general-why-track-a-particular-config-item">Why Enumerate Precompiles? (And in General, Why Track a Particular Config Item?)</h3> <p>The purpose of this specification is to enable nodes to advertise, prior to a fork, that they have the correct configurations loaded and ready. Past testnet and Ethereum Mainnet forks have revealed clients with incorrect precompile sets, chain IDs, deposit contract addresses, and other configuration errors.</p> <p>For precompiles in particular there has been discussion about removing or replacing precompiles in future forks, so a full enumeration of precompiles will reflect removal.</p> <p>Generally, if a configurable variable or constant causes a client to diverge at a fork—whether on Ethereum Mainnet, a testnet, a devnet, or a public rollup—that variable or constant is a candidate for inclusion in the reportable configuration.</p> <h3 id="full-configs-instead-of-deltas">Full Configs Instead of Deltas</h3> <p>An initial design considered using a partial configuration for the "next" fork instead of a complete one. However, analysis of past events showed that some parameters causing divergence (e.g., the deposit contract) were introduced in earlier forks, with consensus failures occurring in later forks due to unrelated EIPs relying on those configurations. A partial "next" configuration hash would not have detected such errors.</p> <p>An alternative—embedding the prior fork’s hash in the next fork—would require defining rules for extracting differences and merging configurations, as well as specifying all prior fork configuration hashes. This would also complicate retroactively adding parameters (e.g., gas schedule constants and variables). The use of config hashes was also removed in a subsequent update.</p> <h3 id="nested-vs-flat-variables">Nested vs. Flat Variables</h3> <p>Nested structures are easier to read, while flat structures are easier to merge. Since this specification uses full configurations for the current and next forks, merging is unnecessary, making readability the priority.</p> <h3 id="serving-data-not-specified-in-genesis-json">Serving Data Not Specified in genesis.json</h3> <p>Some reported values are specification-level constants, which many clients do not include in their configuration files. However, certain EIP constants (e.g., the deposit contract) have become variables in testnets, necessitating their inclusion.</p> <h3 id="json-as-config-format">JSON as Config Format</h3> <p>JSON was chosen for its ubiquity, machine and human readability, and the existence of a standardized canonical form via <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8785">RFC-8785</a>. YAML lacks a standard canonical form. No Ethereum software uses XML for configuration, and adopting it would increase every client's library size. An invented format would be possible but would require definition and standardization within this specification.</p> <h3 id="why-no-configuration-hash">Why no configuration hash</h3> <p>Initial drafts included a hash of the configuration data for quick comparison. There was disagreement about the data format used to generate the hash (plain JSON, RLP, SSZ). Because tooling can effectively diff JSON objects by alphabetizing object keys, the hash is superfluous.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP does not alter previous behavior. Configurations prior to Cancun are non-standard, and clients sharing pre-Cancun configurations will produce non-standard results.</p> <p>Clients supporting pre-Cancun forks MAY return partial or non-standard configurations but SHOULD strive to follow the spirit of the members specified for Cancun configurations. Full compliance is REQUIRED only for Cancun and later forks.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="sample-configs">Sample Configs</h3> <p>Hoodi Prague Config</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">activationTime</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1742999832</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">blobSchedule</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">baseFeeUpdateFraction</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 5007716</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">max</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 9</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-constant"> 6</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">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x88bb0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">forkId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0929e24e</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">precompiles</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">BLAKE2F</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000009</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_G1ADD</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_G1MSM</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000c</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_G2ADD</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000d</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_G2MSM</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000e</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_MAP_FP2_TO_G2</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000011</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_MAP_FP_TO_G1</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000010</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_PAIRING_CHECK</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000f</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_ADD</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000006</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_MUL</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000007</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_PAIRING</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000008</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">ECREC</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">ID</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000004</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">KZG_POINT_EVALUATION</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000a</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">MODEXP</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000005</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RIPEMD160</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">SHA256</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 class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">systemContracts</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">BEACON_ROOTS_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000f3df6d732807ef1319fb7b8bb8522d0beac02</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000bbddc7ce488642fb579f8b00f3a590007251</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">DEPOSIT_CONTRACT_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000219ab540356cbb839cbe05303d7705fa</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">HISTORY_STORAGE_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000f90827f1c53a10cb7a02335b175320002935</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000961ef480eb55e80d19ad83579a64c007002</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>Hoodi Cancun Config</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">activationTime</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">blobSchedule</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">baseFeeUpdateFraction</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 3338477</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">max</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 6</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-constant"> 3</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">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x88bb0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">forkId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbef71d30</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">precompiles</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">BLAKE2F</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000009</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_ADD</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000006</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_MUL</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000007</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_PAIRING</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000008</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">ECREC</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">ID</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000004</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">KZG_POINT_EVALUATION</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000a</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">MODEXP</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000005</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RIPEMD160</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">SHA256</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 class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">systemContracts</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">BEACON_ROOTS_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000f3df6d732807ef1319fb7b8bb8522d0beac02</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="sample-json-rpc">Sample JSON-RPC</h4> <h5 id="with-future-fork-scheduled">With Future Fork Scheduled</h5> <p>The following RPC command, issued on Hoodi when Prague was scheduled but not activated:</p> <pre class="giallo z-code"><code data-lang="shellscript"><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">H</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Content-Type: application/json</span><span class="z-punctuation z-definition z-string">&quot;</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">{&quot;jsonrpc&quot;:&quot;2.0&quot;,&quot;method&quot;:&quot;eth_config&quot;,&quot;id&quot;:1}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string"> http://localhost:8545</span></span></code></pre> <p>would return (after formatting):</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"> 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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">current</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">activationTime</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">blobSchedule</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">baseFeeUpdateFraction</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 3338477</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">max</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 6</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-constant"> 3</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">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x88bb0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">forkId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbef71d30</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">precompiles</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">BLAKE2F</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000009</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_ADD</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000006</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_MUL</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000007</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_PAIRING</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000008</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">ECREC</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">ID</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000004</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">KZG_POINT_EVALUATION</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000a</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">MODEXP</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000005</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RIPEMD160</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">SHA256</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 class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">systemContracts</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">BEACON_ROOTS_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000f3df6d732807ef1319fb7b8bb8522d0beac02</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">next</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">activationTime</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1742999832</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">blobSchedule</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">baseFeeUpdateFraction</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 5007716</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">max</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 9</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-constant"> 6</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">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x88bb0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">forkId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0929e24e</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">precompiles</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">BLAKE2F</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000009</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_G1ADD</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_G1MSM</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000c</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_G2ADD</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000d</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_G2MSM</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000e</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_MAP_FP2_TO_G2</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000011</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_MAP_FP_TO_G1</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000010</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_PAIRING_CHECK</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000f</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_ADD</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000006</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_MUL</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000007</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_PAIRING</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000008</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">ECREC</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">ID</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000004</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">KZG_POINT_EVALUATION</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000a</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">MODEXP</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000005</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RIPEMD160</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">SHA256</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 class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">systemContracts</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">BEACON_ROOTS_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000f3df6d732807ef1319fb7b8bb8522d0beac02</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000bbddc7ce488642fb579f8b00f3a590007251</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">DEPOSIT_CONTRACT_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000219ab540356cbb839cbe05303d7705fa</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">HISTORY_STORAGE_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000f90827f1c53a10cb7a02335b175320002935</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000961ef480eb55e80d19ad83579a64c007002</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">last</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">activationTime</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1742999832</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">blobSchedule</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">baseFeeUpdateFraction</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 5007716</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">max</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 9</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-constant"> 6</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">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x88bb0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">forkId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0929e24e</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">precompiles</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">BLAKE2F</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000009</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_G1ADD</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_G1MSM</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000c</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_G2ADD</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000d</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_G2MSM</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000e</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_MAP_FP2_TO_G2</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000011</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_MAP_FP_TO_G1</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000010</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BLS12_PAIRING_CHECK</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000f</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_ADD</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000006</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_MUL</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000007</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_PAIRING</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000008</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">ECREC</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">ID</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000004</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">KZG_POINT_EVALUATION</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000a</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">MODEXP</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000005</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RIPEMD160</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">SHA256</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 class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">systemContracts</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">BEACON_ROOTS_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000f3df6d732807ef1319fb7b8bb8522d0beac02</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000bbddc7ce488642fb579f8b00f3a590007251</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">DEPOSIT_CONTRACT_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000219ab540356cbb839cbe05303d7705fa</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">HISTORY_STORAGE_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000f90827f1c53a10cb7a02335b175320002935</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000961ef480eb55e80d19ad83579a64c007002</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><h5 id="without-future-fork-scheduled">Without Future Fork Scheduled</h5> <p>When no future forks are configured, the same RPC command would return:</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"> 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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">current</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">activationTime</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">blobSchedule</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">baseFeeUpdateFraction</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 3338477</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">max</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 6</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-constant"> 3</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">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x88bb0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">forkId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbef71d30</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">precompiles</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">BLAKE2F</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000009</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_ADD</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000006</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_MUL</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000007</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BN254_PAIRING</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000008</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">ECREC</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">ID</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000004</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">KZG_POINT_EVALUATION</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000a</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">MODEXP</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000005</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RIPEMD160</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">SHA256</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 class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">systemContracts</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">BEACON_ROOTS_ADDRESS</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000f3df6d732807ef1319fb7b8bb8522d0beac02</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">next</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">last</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</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> <ul> <li><strong>Exposure Risks</strong>: Incorrect configurations could leak operational details. Operators SHOULD restrict <code>eth_config</code> to trusted interfaces (e.g., local access or authenticated endpoints).</li> <li><strong>Dishonest Nodes</strong>: Clients may report false configurations. Peers or monitoring tools MAY cross-check <code>eth_config</code> outputs against known fork specifications or other nodes' responses to detect anomalies.</li> <li><strong>DDoS Mitigation</strong>: Clients MAY cache configuration objects internally and rate-limit <code>eth_config</code> requests to prevent resource exhaustion. Implementations MAY impose a minimum response interval (e.g., 1 second).</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> 2025-03-14T00:00:00+00:00 2026-02-11T14:49:27+00:00 Charles Cooperhttps://github.com/charles-cooper Qi Zhouhttps://github.com/qizhou Matthttps://github.com/lightclient Dragan Rakitahttps://github.com/rakita https://wg-eips.ritovision.com/7907/

Increases the contract code size limit introduced in EIP-170 and adds gas metering to code loading

<h2 id="abstract">Abstract</h2> <p>This EIP increases the contract code size limit from 24KB (24576 bytes) introduced in <a href="https://wg-eips.ritovision.com/170/">EIP-170</a> to 64KB (65536 bytes), and adds gas metering for excess code loading. It introduces a gas cost of 2 gas per (32 byte) word for contract code exceeding 24KB, allowing deployment of contracts of any size while preventing DoS attacks through appropriate gas metering. Lastly, it also commensurately increases initcode size limit from 48KB, introduced in <a href="https://wg-eips.ritovision.com/3860/">EIP-3860</a>, to 128KB (131072 bytes).</p> <h2 id="motivation">Motivation</h2> <p>EIP-170 introduced a 24KB contract code size limit to prevent potential DoS attacks, as large contract code requires O(n) resource cost in terms of disk reads, VM preprocessing, and Merkle proof sizes, all of which are not directly compensated by gas fees. However, this limit restricts legitimate use cases for large contracts.</p> <p>This EIP proposes a gas-based solution that allows contracts of larger size while ensuring that users loading large contracts pay gas proportional to the additional resources they consume. This approach aligns with Ethereum's gas model philosophy of paying for the resources consumed. A new limit has been set at 64KB, so that raising the gas limit does not break assumptions in the p2p layer.</p> <p>Improving developer experience is the primary motivation for increasing the contract size limit. The current 24KB ceiling forces developers to split functionality across multiple contracts, introduce proxies or delegatecall-based indirection, and rely on architectural patterns like the Diamond Standard—even when those patterns aren't otherwise necessary. These workarounds can increase code complexity, deployment costs, and audit surface. By raising the limit, developers can keep more logic in a single contract, improving readability and lowering gas usage by avoiding unnecessary cross-contract calls. This also makes smart contract development more accessible to newer developers, who can move from idea to deployment without first learning advanced contract composition patterns.</p> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions</h3> <table><thead><tr><th>Name</th><th>Value</th><th>Description</th></tr></thead><tbody> <tr><td><code>COLD_SLOAD_COST</code></td><td><code>2100</code></td><td>The cost charged for cold loading storage as defined by <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>.</td></tr> <tr><td><code>WARM_STORAGE_READ_COST</code></td><td><code>100</code></td><td>The cost charged for loading warm storage as defined by <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>.</td></tr> <tr><td><code>COLD_ACCOUNT_ACCESS_COST</code></td><td><code>2600</code></td><td>The cost charged for loading a cold account as defined by <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>.</td></tr> <tr><td><code>GAS_PER_CODE_WORD</code></td><td><code>2</code></td><td>The cost charged per word of code loaded beyond the initial <code>24KB</code> amount.</td></tr> <tr><td><code>FORK_BLKNUM</code></td><td>TBD</td><td>The block number of the hard fork that this EIP is activated.</td></tr> </tbody></table> <p>The following values are updated:</p> <table><thead><tr><th>Name</th><th>Old Value</th><th>New Value</th><th>Description</th></tr></thead><tbody> <tr><td><code>MAX_CODE_SIZE</code></td><td>24KB (<code>0x6000</code>)</td><td>64KB (<code>0x10000</code>)</td><td>The maximum size for code as set in <a href="https://wg-eips.ritovision.com/170/">EIP-170</a></td></tr> <tr><td><code>MAX_INITCODE_SIZE</code></td><td>48KB (<code>0xc000</code>)</td><td>128KB (<code>0x20000</code>)</td><td>The maximum size for code as set in <a href="https://wg-eips.ritovision.com/3860/">EIP-3860</a>. Always set at <code>2 * MAX_CODE_SIZE</code></td></tr> </tbody></table> <h4 id="helpers">Helpers</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"> ceil32</span><span>(</span><span class="z-variable z-parameter z-function">n</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"> return</span><span> (</span><span>(</span><span>n</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><span class="z-keyword"> *</span><span class="z-constant"> 32</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"> excess_code_size</span><span>(</span><span class="z-variable z-parameter z-function">n</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"> return</span><span class="z-support"> max</span><span>(</span><span class="z-constant">0</span><span>,</span><span> n</span><span class="z-keyword"> -</span><span class="z-storage z-type"> 0x</span><span class="z-constant">6000</span><span>)</span></span></code></pre><h3 id="behavior">Behavior</h3> <ol> <li>Update the <a href="https://wg-eips.ritovision.com/170/">EIP-170</a> introduced <code>MAX_CODE_SIZE</code> constant of 24KB (<code>0x6000</code> bytes) to 64KB (<code>0x10000</code> bytes).</li> <li>Introduces a new cold/warm state for contract code. Specifically, change the gas schedule of operations that load code, e.g. the opcodes <code>CALL</code>, <code>STATICCALL</code>, <code>DELEGATECALL</code>, <code>CALLCODE</code> and <code>EXTCODECOPY</code> are modified so that dynamic <code>EXCESS_CODE_COST= ceil32(excess_code_size(len(code))) * GAS_PER_CODE_WORD // 32</code> gas are added to the access cost if the code is cold. When the code is an <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> delegation to another account, if target account code is cold add additional gas should be accounted. Warming of the contract code is subjected to the journaling and can be reverted similar to other state warming in <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a>.</li> <li>Update the <a href="https://wg-eips.ritovision.com/3860/">EIP-3860</a> introduced <code>MAX_INITCODE_SIZE</code> limit of 48KB (<code>0xc000</code> bytes) to 128KB (<code>0x10000</code> bytes).</li> <li>If a large contract is the entry point of a transaction, the cost calculated in (2) is charged before the execution and contract code is marked as warm. This fee is not calculated towards the initial gas fee. In case of out-of-gas halt, execution will stop and the balance will not be transferred.</li> <li>Empty code ( with <code>keccak("") = "0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470"</code>) is always considered warm.</li> </ol> <table><thead><tr><th>Contract</th><th>Gas changes (only opcodes that load code)</th><th>How?</th></tr></thead><tbody> <tr><td>Cold account and code</td><td>Add <code>COLD_SLOAD_COST=2100</code>, <code>EXCESS_CODE_COST</code>, and <code>COLD_ACCOUNT_ACCESS_COST=2600</code></td><td>Contract not in access list nor accessed prior in the txn</td></tr> <tr><td>Warm account and cold code</td><td>Add <code>COLD_SLOAD_COST=2100</code>, <code>EXCESS_CODE_COST</code>, and <code>WARM_STORAGE_READ_COST=100</code></td><td>Already accessed balance, storage, or included in access list (<a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a>)</td></tr> <tr><td>Warm account and code</td><td><code>WARM_STORAGE_READ_COST=100</code></td><td>Already accessed account code</td></tr> </tbody></table> <p><code>COLD_ACCOUNT_ACCESS_COST</code>, <code>COLD_SLOAD_COST</code>, and <code>WARM_STORAGE_READ_COST</code> are defined in <a href="https://wg-eips.ritovision.com/2929/#parameters">EIP-2929</a>.</p> <h3 id="migration">Migration</h3> <p>This EIP adds a new field to the account tuple, <code>codesize</code>. That is, the account tuple goes from having the following four fields, <code>(nonce, balance, storage_root, code_hash)</code> to <code>(nonce, balance, storage_root, code_hash, codesize)</code>. The reason for this is that most key-value databases in use by production clients do not allow peeking at the size of a value pointed to by a given key without actually loading the full contents of the value.</p> <p>To avoid forcing a full migration, the following rules are followed:</p> <ol> <li>Any account created or updated on or after <code>FORK_BLKNUM</code> should additionally have its codesize written into the account tuple.</li> <li>Any account which does not have the <code>codesize</code> field is assumed to have codesize less than 24KB.</li> </ol> <h2 id="rationale">Rationale</h2> <p>The gas cost of 2 per word was chosen to account for:</p> <ol> <li>The additional disk I/O for retrieving larger contract code</li> <li>The increased computational resources for preprocessing larger code for execution (a.k.a. "JUMPDEST analysis").</li> <li>The growth in Merkle proof sizes for blocks containing larger contracts</li> </ol> <p>This EIP introduces the gas cost as an additional cost for contracts exceeding 24KB. It could have been specified as a simpler <code>ceil32(contract_size) * GAS_PER_CODE_WORD // 32</code>, without hardcoding the existing contract size limit. However, for the sake of being conservative and avoiding lowering the cost of loading existing contracts (which could be small, under the 24KB limit), the 24KB floor was added to the formula.</p> <p>The <code>EXTCODECOPY</code> opcode could theoretically be exempt from this, since clients could just load the parts of the bytecode which are actually requested. However, this might require a change at the protocol level, since the full code is required for the block witness. For this reason, <code>EXTCODECOPY</code> is included in the pricing scheme, and a carveout could be considered at a later date.</p> <p>The new limit has been set at 64KB. The limit has been put in place so that increasing the gas limit won't have unexpected side effects at the db or p2p layer. For instance, in devp2p, the maximum packet size is 10MB (<a rel="external" href="https://github.com/ethereum/devp2p/blob/5713591d0366da78a913a811c7502d9ca91d29a8/caps/eth.md#basic-operation">https://github.com/ethereum/devp2p/blob/5713591d0366da78a913a811c7502d9ca91d29a8/caps/eth.md#basic-operation</a>). As of time of this writing, the maximum packet size in snap sync is even lower, at 96KB.</p> <p>The limit for initcode has also been increased to 128KB, following the pattern set in EIP-3860 that the initcode limit is double the runtime code limit. While initcode is different from deployed code in that it does not live in the state and therefore isn't visible in devp2p or in the db, fully removing the limit could have unforeseen consequences.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces additional gas costs for certain operations. Specifically, <code>CALL</code>, <code>STATICCALL</code>, <code>DELEGATECALL</code>, <code>CALLCODE</code>, <code>EXTCODESIZE</code>, and <code>EXTCODECOPY</code> may now require extra gas when accessing cold contract code.</p> <h2 id="test-cases">Test Cases</h2> <h2 id="reference-implementation">Reference Implementation</h2> <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> 2025-03-07T00:00:00+00:00 2026-02-11T14:48:26+00:00 Xiaoyu Liuhttps://github.com/elizabethxiaoyujiushi.lxy@antgroup.com Yuxiang Fuhttps://github.com/tmac4096kunfu.fyx@antgroup.com Yanyi Liangeason.lyy@antgroup.com Hao Zouhttps://github.com/BruceZH0915situ.zh@antgroup.com Siyuan Zhenghttps://github.com/andrewcoder666zhengsiyuan.zsy@antgroup.com yuanshanhshanhttps://github.com/xunayuanyuanshanshan.yss@antgroup.com https://wg-eips.ritovision.com/7908/

Hierarchical deterministic (HD) wallets for treasury systems, isolating entities via cryptographic key paths.

<h2 id="abstract">Abstract</h2> <p>This proposal aims to provide a standardized method for on-chain treasury management of institutional assets, ensuring secure private key generation, hierarchical management, and departmental permission isolation while supporting asset security and transaction efficiency in multi-chain environments. By defining a unified derivation path and security mechanisms, this proposal offers an efficient and secure solution for treasury management.</p> <h2 id="motivation">Motivation</h2> <p>With the rapid development of blockchain and DeFi, secure management of on-chain assets has become critical. Traditional private key management struggles to meet the security demands of large organizations in complex scenarios, where hierarchical key management, permission controls, and multi-signature mechanisms are essential. This proposal provides a standardized solution for institutional treasury management, ensuring asset security and transaction efficiency.</p> <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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <h3 id="derivation-path">Derivation Path</h3> <p>For secure on-chain treasury account key management, implementations MUST use the following hierarchical deterministic (HD) path:</p> <pre class="giallo z-code"><code data-lang="latex"><span class="giallo-l"><span>m/44&#39;/60&#39;/entity_id&#39; / department_id&#39; / account_index</span></span></code></pre> <p>Path Components:</p> <ol> <li> <p><strong>Master Key (</strong><code>m</code><strong>)</strong></p> <ul> <li>SHALL represent the root HD wallet private key.</li> </ul> </li> <li> <p><strong><a rel="external" href="https://github.com/bitcoin/bips/blob/0278bf3d7111bab8f0ef8dd08f16fd7b5ac6cbd6/bip-0044.mediawiki">BIP 44</a> Compliance Layer (<code>44'</code>)</strong></p> <ul> <li>MUST use <code>44'</code> (hardened) to indicate BIP 44 compliance.</li> </ul> </li> <li> <p><strong>Coin Type Layer ( <code>60'</code> )</strong></p> <ul> <li>SHALL use <code>60'</code> (hardened) for Ethereum and EVM-compatible chains.</li> </ul> </li> <li> <p><strong>Entity Identifier ( <code>entity_id'</code></strong>)</p> <ul> <li>MUST be derived by hashing the subsidiary name into a hardened index.</li> <li>MUST NOT reuse the same <code>entity_id'</code> across distinct subsidiaries.</li> </ul> </li> <li> <p><strong>Department Identifier (</strong><code>department_id'</code><strong>)</strong></p> <ul> <li>SHALL be derived by hashing the department name into a hardened index.</li> <li>MUST isolate keys between departments via hardened derivation.</li> </ul> </li> <li> <p><strong>Account Index (</strong><code>account_index</code><strong>)</strong></p> <ul> <li>MUST use non-hardened derivation to allow unified account management.</li> </ul> </li> </ol> <p><strong>Note on BIP 44 Adaptation</strong>:</p> <ul> <li>The BIP 44 <code>change</code> layer SHOULD be omitted for Ethereum/EVMs due to their account model (not UTXO).</li> </ul> <h3 id="hash-conversion">Hash Conversion</h3> <p>To derive <code>entity_id</code> and <code>department_id</code>:</p> <ol> <li> <p><strong>Entity Index Calculation</strong></p> <ul> <li>SHALL compute <code>entity_id</code> as:</li> </ul> </li> </ol> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>entity_hash</span><span class="z-keyword"> =</span><span> sha256</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">ENTITY:</span><span class="z-constant">{</span><span>entity</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>.</span><span>encode</span><span>(</span><span>)</span><span>)</span><span>.</span><span>digest</span><span>(</span><span>)</span><span> </span></span> <span class="giallo-l"><span>entity_index</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>entity_hash</span><span>[</span><span>:</span><span class="z-constant">4</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">big</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword"> |</span><span class="z-storage z-type"> 0x</span><span class="z-constant">80000000</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 2^31 ≤ index &lt; 2^32</span></span></code></pre> <ol start="2"> <li> <p><strong>Department Index Calculation</strong></p> <ul> <li>MUST compute <code>department_id</code> as:</li> </ul> </li> </ol> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>dept_hash</span><span class="z-keyword"> =</span><span> sha256</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">DEPT:</span><span class="z-constant">{</span><span>entity_hash</span><span class="z-constant">}</span><span class="z-string">:</span><span class="z-constant">{</span><span>department</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>.</span><span>encode</span><span>(</span><span>)</span><span>)</span><span>.</span><span>digest</span><span>(</span><span>)</span><span> </span></span> <span class="giallo-l"><span>dept_index</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>dept_hash</span><span>[</span><span>:</span><span class="z-constant">4</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">big</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword"> |</span><span class="z-storage z-type"> 0x</span><span class="z-constant">80000000</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 2^31 ≤ index &lt; 2^32</span></span></code></pre> <ol start="3"> <li> <p><strong>Output Constraints</strong></p> <ul> <li>Generated indices MUST be integers in <code>[2^31, 2^32-1]</code> to enforce hardened derivation.</li> </ul> </li> </ol> <h3 id="extended-path-for-role-based-access">Extended Path for Role-Based Access</h3> <p>For finer access control (e.g., roles within departments):</p> <pre class="giallo z-code"><code data-lang="latex"><span class="giallo-l"><span>m/60&#39;/entity_id&#39; / department_id&#39; /role_id&#39;/ account_index</span></span></code></pre> <ol> <li> <p><strong>Role Identifier (</strong><code>role_id'</code><strong>)</strong></p> <ul> <li>SHOULD use hardened derivation to isolate role-specific keys.</li> </ul> </li> </ol> <p><strong>Compatibility Note</strong>:</p> <ul> <li>Omitting the <code>44'</code> layer MAY cause incompatibility with standard wallets (e.g., MetaMask).</li> <li>Integrations with such wallets MUST implement custom plugins to handle this deviation.</li> </ul> <h3 id="simplified-path-for-smaller-entities">Simplified Path for Smaller Entities</h3> <p>For entities without subsidiaries:</p> <pre class="giallo z-code"><code data-lang="latex"><span class="giallo-l"><span>m/44&#39;/60&#39; / department_id&#39; /0/ account_index</span></span></code></pre> <p><strong>Compatibility Guarantee</strong></p> <ul> <li>This structure SHOULD ensure compatibility with mainstream BIP 44 wallets.</li> </ul> <h3 id="key-derivation-algorithm">Key Derivation Algorithm</h3> <p>Implementations MUST adhere to:</p> <pre class="giallo z-code"><code data-lang="latex"><span class="giallo-l"><span>E = Map&lt;entity, List&lt;Department&gt;&gt;</span></span> <span class="giallo-l"><span>n = Layer2 curve order</span></span> <span class="giallo-l"><span>path = m/44&#39;/60&#39;/entity_id&#39; / department_id&#39; / account_index</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>root_key = BIP32(path)</span></span> <span class="giallo-l"><span>for each E:</span></span> <span class="giallo-l"><span> key = hash(root_key|hierarchical_hash_to_index(entity,department))</span></span> <span class="giallo-l"><span> return key</span></span></code></pre> <p><strong>Cryptographic Requirements</strong>:</p> <ul> <li>SHALL use <a rel="external" href="https://github.com/bitcoin/bips/blob/86b29c5d81c755133114486c19a271c34087fc81/bip-0032.mediawiki">BIP 32</a> with <code>secp256k1</code> for HD derivation.</li> <li>MUST concatenate hashes with root keys to prevent cross-layer key leakage.</li> </ul> <h3 id="compatibility-considerations"><strong>Compatibility Considerations</strong></h3> <p>This specification is inspired by BIP 44 (<code>m/purpose'/coin_type'/account'/change/address_index</code>), but:</p> <ul> <li>SHALL NOT use the <code>change</code> layer for Ethereum-based systems.</li> <li>MAY extend the hierarchy beyond BIP 44’s 5-layer structure for organizational needs.</li> </ul> <h2 id="rationale">Rationale</h2> <p>The scenarios for which the proposal applies are:</p> <ol> <li><strong>Company and Department Isolation</strong>: Different subsidiaries within the group, as well as different departments within each subsidiary, can create isolated on-chain accounts. Enhanced derivation is used to isolate exposure risks.</li> <li><strong>Group Unified Management Authority</strong>: The group administrator holds the master private key, which can derive all subsidiary private keys, granting the highest authority to view and initiate transactions across the entire group, facilitating unified management by the group administrator.</li> <li><strong>Shared Department Private Key</strong>: If subsidiary A's administrator, Alice, needs to share accounts under subsidiary A with a new administrator, Bob, she only needs to share the master private key of subsidiary A. Accounts from various departments can then be derived from this key.</li> <li><strong>Shared Audit Public Key</strong>: If the audit department needs to audit transactions under a specific department, the extended public key of the specified department can be shared with the audit department. Through this extended public key, all subordinate public keys under the department can be derived, allowing the audit department to track all transactions associated with these public key addresses.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard complies with BIP 39, BIP 32, and BIP 44.</p> <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-string">&quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string">Secure Treasury Management System</span></span> <span class="giallo-l"><span class="z-string">Enterprise-grade hierarchical deterministic wallet implementation compliant with BIP-44</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 class="z-keyword">import</span><span> hashlib</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> logging</span></span> <span class="giallo-l"><span class="z-keyword">from</span><span> typing</span><span class="z-keyword"> import</span><span> Tuple</span><span>,</span><span> Dict</span></span> <span class="giallo-l"><span class="z-keyword">from</span><span> bip32utils</span><span class="z-keyword"> import</span><span> BIP32Key</span></span> <span class="giallo-l"><span class="z-keyword">from</span><span> eth_account</span><span class="z-keyword"> import</span><span> Account</span></span> <span class="giallo-l"><span class="z-keyword">from</span><span> mnemonic</span><span class="z-keyword"> import</span><span> Mnemonic</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Add BIP39 support</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Configure logging</span></span> <span class="giallo-l"><span>logging</span><span>.</span><span>basicConfig</span><span>(</span><span class="z-variable">level</span><span class="z-keyword">=</span><span>logging</span><span>.</span><span class="z-constant">INFO</span><span>)</span></span> <span class="giallo-l"><span>logger</span><span class="z-keyword"> =</span><span> logging</span><span>.</span><span>getLogger</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">TreasurySystem</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">class</span><span class="z-entity z-name"> TreasurySystem</span><span>:</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 class="z-variable z-parameter z-function"> mnemonic</span><span>:</span><span class="z-support"> str</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"> Initialize the treasury system</span></span> <span class="giallo-l"><span class="z-string"> :param mnemonic: BIP-39 mnemonic (12/24 words)</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-keyword"> if</span><span class="z-keyword"> not</span><span> Mnemonic</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">english</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>.</span><span>check</span><span>(</span><span>mnemonic</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span class="z-support"> ValueError</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Invalid BIP-39 mnemonic</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-punctuation z-definition z-comment"> #</span><span class="z-comment"> Generate seed using standard BIP-39</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>seed</span><span class="z-keyword"> =</span><span> Mnemonic</span><span>.</span><span>to_seed</span><span>(</span><span>mnemonic</span><span>,</span><span class="z-variable"> passphrase</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-variable z-language"> self</span><span>.</span><span>root_key</span><span class="z-keyword"> =</span><span> BIP32Key</span><span>.</span><span>fromEntropy</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>seed</span><span>)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> logger</span><span>.</span><span>info</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Treasury system initialized. Master key fingerprint: </span><span class="z-constant">%s</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-language"> self</span><span>.</span><span>root_key</span><span>.</span><span>Fingerprint</span><span>(</span><span>)</span><span>.</span><span>hex</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> @</span><span class="z-support">staticmethod</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> _hierarchical_hash</span><span>(</span><span class="z-variable z-parameter z-function">entity</span><span>:</span><span class="z-support"> str</span><span>,</span><span class="z-variable z-parameter z-function"> department</span><span>:</span><span class="z-support"> str</span><span>)</span><span> -&gt;</span><span> Tuple</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 class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string"> Hierarchical hash calculation (compliant with proposal spec)</span></span> <span class="giallo-l"><span class="z-string"> Returns: (entity_index, department_index)</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"> Entity hash</span></span> <span class="giallo-l"><span> entity_hash</span><span class="z-keyword"> =</span><span> hashlib</span><span>.</span><span>sha256</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">ENTITY:</span><span class="z-constant">{</span><span>entity</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>.</span><span>encode</span><span>(</span><span>)</span><span>)</span><span>.</span><span>digest</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> entity_index</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>entity_hash</span><span>[</span><span>:</span><span class="z-constant">4</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 class="z-keyword"> |</span><span class="z-storage z-type"> 0x</span><span class="z-constant">80000000</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"> Department hash (chained)</span></span> <span class="giallo-l"><span> dept_input</span><span class="z-keyword"> =</span><span class="z-storage z-type"> f</span><span class="z-string">&quot;</span><span class="z-string">DEPT:</span><span class="z-constant">{</span><span>entity_hash</span><span>.</span><span>hex</span><span>(</span><span>)</span><span class="z-constant">}</span><span class="z-string">:</span><span class="z-constant">{</span><span>department</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>.</span><span>encode</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> dept_hash</span><span class="z-keyword"> =</span><span> hashlib</span><span>.</span><span>sha256</span><span>(</span><span>dept_input</span><span>)</span><span>.</span><span>digest</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> dept_index</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>dept_hash</span><span>[</span><span>:</span><span class="z-constant">4</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 class="z-keyword"> |</span><span class="z-storage z-type"> 0x</span><span class="z-constant">80000000</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> entity_index</span><span>,</span><span> dept_index</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"> _derive_key</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> path</span><span>:</span><span class="z-support"> list</span><span>)</span><span> -&gt;</span><span> BIP32Key</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span><span class="z-string">General key derivation method</span><span class="z-punctuation z-definition z-string">&quot;&quot;&quot;</span></span> <span class="giallo-l"><span> current_key</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>root_key</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> index</span><span class="z-keyword"> in</span><span> path</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span class="z-support"> isinstance</span><span>(</span><span>index</span><span>,</span><span class="z-support"> int</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span class="z-support"> TypeError</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Invalid derivation index type: </span><span class="z-constant">{</span><span class="z-support">type</span><span>(</span><span>index</span><span>)</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span> current_key</span><span class="z-keyword"> =</span><span> current_key</span><span>.</span><span>ChildKey</span><span>(</span><span>index</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> current_key</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"> generate_account</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> entity</span><span>:</span><span class="z-support"> str</span><span>,</span><span class="z-variable z-parameter z-function"> department</span><span>:</span><span class="z-support"> str</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> account_idx</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span><span>)</span><span> -&gt;</span><span> Dict</span><span>[</span><span class="z-support">str</span><span>,</span><span class="z-support"> str</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"> Generate department account (BIP44 5-layer structure)</span></span> <span class="giallo-l"><span class="z-string"> Path: m/44&#39;/60&#39;/entity&#39;/dept&#39;/account_idx</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> e_idx</span><span>,</span><span> d_idx</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>_hierarchical_hash</span><span>(</span><span>entity</span><span>,</span><span> department</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"> BIP-44 standard path</span></span> <span class="giallo-l"><span> derivation_path</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">8000002C</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 44&#39; (hardened)</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">8000003C</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 60&#39; (Ethereum)</span></span> <span class="giallo-l"><span> e_idx</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> entity_index (hardened)</span></span> <span class="giallo-l"><span> d_idx</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> department_index (hardened)</span></span> <span class="giallo-l"><span> account_idx</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> address index</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> key</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>_derive_key</span><span>(</span><span>derivation_path</span><span>)</span></span> <span class="giallo-l"><span> priv_key</span><span class="z-keyword"> =</span><span> key</span><span>.</span><span>PrivateKey</span><span>(</span><span>)</span><span>.</span><span>hex</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> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">path</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span><span class="z-storage z-type"> f</span><span class="z-string">&quot;</span><span class="z-string">m/44</span><span class="z-string">&#39;/60</span><span class="z-string">&#39;/</span><span class="z-constant">{</span><span>e_idx</span><span class="z-constant">}</span><span class="z-string">&#39;/</span><span class="z-constant">{</span><span>d_idx</span><span class="z-constant">}</span><span class="z-string">&#39;/</span><span class="z-constant">{</span><span>account_idx</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">private_key</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span><span> priv_key</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Warning: Never expose this in production</span></span> <span class="giallo-l"><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> Account</span><span>.</span><span>from_key</span><span>(</span><span>priv_key</span><span>)</span><span>.</span><span>address</span></span> <span class="giallo-l"><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_audit_xpub</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> entity</span><span>:</span><span class="z-support"> str</span><span>,</span><span class="z-variable z-parameter z-function"> department</span><span>:</span><span class="z-support"> str</span><span>)</span><span> -&gt;</span><span class="z-support"> str</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"> Retrieve department-level extended public key (for auditing)</span></span> <span class="giallo-l"><span class="z-string"> Path: m/44&#39;/60&#39;/entity&#39;/dept&#39;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> e_idx</span><span>,</span><span> d_idx</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>_hierarchical_hash</span><span>(</span><span>entity</span><span>,</span><span> department</span><span>)</span></span> <span class="giallo-l"><span> path</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">8000002C</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 44&#39;</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">8000003C</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 60&#39;</span></span> <span class="giallo-l"><span> e_idx</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> entity&#39;</span></span> <span class="giallo-l"><span> d_idx</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> dept&#39;</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"> self</span><span>.</span><span>_derive_key</span><span>(</span><span>path</span><span>)</span><span>.</span><span>ExtendedKey</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_dept_xprv</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> entity</span><span>:</span><span class="z-support"> str</span><span>,</span><span class="z-variable z-parameter z-function"> department</span><span>:</span><span class="z-support"> str</span><span>)</span><span> -&gt;</span><span class="z-support"> str</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"> Get department-level extended private key (strictly controlled)</span></span> <span class="giallo-l"><span class="z-string"> Path: m/44&#39;/60&#39;/entity&#39;/dept&#39;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> e_idx</span><span>,</span><span> d_idx</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>_hierarchical_hash</span><span>(</span><span>entity</span><span>,</span><span> department</span><span>)</span></span> <span class="giallo-l"><span> path</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">8000002C</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 44&#39;</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">8000003C</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 60&#39;</span></span> <span class="giallo-l"><span> e_idx</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> entity&#39;</span></span> <span class="giallo-l"><span> d_idx</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> dept&#39;</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"> self</span><span>.</span><span>_derive_key</span><span>(</span><span>path</span><span>)</span><span>.</span><span>ExtendedKey</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> @</span><span class="z-support">staticmethod</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> derive_addresses_from_xpub</span><span>(</span><span class="z-variable z-parameter z-function">xpub</span><span>:</span><span class="z-support"> str</span><span>,</span><span class="z-variable z-parameter z-function"> count</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 20</span><span>)</span><span> -&gt;</span><span class="z-support"> list</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span><span class="z-string">Derive addresses from extended public key (audit use)</span><span class="z-punctuation z-definition z-string">&quot;&quot;&quot;</span></span> <span class="giallo-l"><span> audit_key</span><span class="z-keyword"> =</span><span> BIP32Key</span><span>.</span><span>fromExtendedKey</span><span>(</span><span>xpub</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> [</span></span> <span class="giallo-l"><span> Account</span><span>.</span><span>from_key</span><span>(</span></span> <span class="giallo-l"><span> audit_key</span></span> <span class="giallo-l"><span> .</span><span>ChildKey</span><span>(</span><span>i</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Address index</span></span> <span class="giallo-l"><span> .</span><span>PrivateKey</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>.</span><span>address</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span>count</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-keyword">if</span><span class="z-support z-variable"> __name__</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">__main__</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-comment"> #</span><span class="z-comment"> Example usage (remove private key printing in production)</span></span> <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"> Use standard mnemonic</span></span> <span class="giallo-l"><span> mnemo</span><span class="z-keyword"> =</span><span> Mnemonic</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">english</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span> mnemonic</span><span class="z-keyword"> =</span><span> mnemo</span><span>.</span><span>generate</span><span>(</span><span class="z-variable">strength</span><span class="z-keyword">=</span><span class="z-constant">256</span><span>)</span></span> <span class="giallo-l"><span> treasury</span><span class="z-keyword"> =</span><span> TreasurySystem</span><span>(</span><span>mnemonic</span><span>)</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">mnemonic: </span><span class="z-constant">{</span><span>mnemonic</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-constant">\n</span><span class="z-string">=== Finance Department Account Generation ===</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span> finance_acc1</span><span class="z-keyword"> =</span><span> treasury</span><span>.</span><span>generate_account</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">GroupA</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">Finance</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> finance_acc2</span><span class="z-keyword"> =</span><span> treasury</span><span>.</span><span>generate_account</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">GroupA</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">Finance</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-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Account1 path: </span><span class="z-constant">{</span><span>finance_acc1</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">path</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Account1 address: </span><span class="z-constant">{</span><span>finance_acc1</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 class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Account1 private key: </span><span class="z-constant">{</span><span>finance_acc1</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">private_key</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Account2 path: </span><span class="z-constant">{</span><span>finance_acc2</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">path</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Account2 address: </span><span class="z-constant">{</span><span>finance_acc2</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 class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Account2 private key: </span><span class="z-constant">{</span><span>finance_acc2</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">private_key</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-constant">\n</span><span class="z-string">=== Audit Verification Test===</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span> audit_xpub</span><span class="z-keyword"> =</span><span> treasury</span><span>.</span><span>get_audit_xpub</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">GroupA</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">Finance</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Audit xpub: </span><span class="z-constant">{</span><span>audit_xpub</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span> audit_addresses</span><span class="z-keyword"> =</span><span> TreasurySystem</span><span>.</span><span>derive_addresses_from_xpub</span><span>(</span><span>audit_xpub</span><span>,</span><span class="z-constant"> 2</span><span>)</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Audit-derived addresses: </span><span class="z-constant">{</span><span>audit_addresses</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> finance_acc1</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 class="z-keyword"> in</span><span> audit_addresses</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Audit verification failed</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> finance_acc2</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 class="z-keyword"> in</span><span> audit_addresses</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Audit verification failed</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">✅ Audit verification successful</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"> print</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-constant">\n</span><span class="z-string">=== Department Isolation Test ===</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span> other_dept_acc</span><span class="z-keyword"> =</span><span> treasury</span><span>.</span><span>generate_account</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">GroupA</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">Audit</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-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Account3 path: </span><span class="z-constant">{</span><span>other_dept_acc</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">path</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Account3 address: </span><span class="z-constant">{</span><span>other_dept_acc</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 class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> other_dept_acc</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 class="z-keyword"> not</span><span class="z-keyword"> in</span><span> audit_addresses</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Isolation breach</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">✅ Department isolation effective</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-constant">\n</span><span class="z-string">=== Department Private Key Sharing Test ===</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-comment"> #</span><span class="z-comment"> Gets the department layer extension private key</span></span> <span class="giallo-l"><span> dept_xprv</span><span class="z-keyword"> =</span><span> treasury</span><span>.</span><span>get_audit_xpub</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">GroupA</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">Finance</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>.</span><span>replace</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">xpub</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">xprv</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 实际应通过专用方法获取</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Fiance xprv: </span><span class="z-constant">{</span><span>dept_xprv</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Derive the account private key from the extension private key</span></span> <span class="giallo-l"><span> dept_key</span><span class="z-keyword"> =</span><span> BIP32Key</span><span>.</span><span>fromExtendedKey</span><span>(</span><span>dept_xprv</span><span>)</span></span> <span class="giallo-l"><span> derived_acc0_key</span><span class="z-keyword"> =</span><span> dept_key</span><span>.</span><span>ChildKey</span><span>(</span><span class="z-constant">0</span><span>)</span><span>.</span><span>PrivateKey</span><span>(</span><span>)</span><span>.</span><span>hex</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> derived_acc1_key</span><span class="z-keyword"> =</span><span> dept_key</span><span>.</span><span>ChildKey</span><span>(</span><span class="z-constant">1</span><span>)</span><span>.</span><span>PrivateKey</span><span>(</span><span>)</span><span>.</span><span>hex</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Fiance derived_acc0_key: </span><span class="z-constant">{</span><span>derived_acc0_key</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-string">Fiance derived_acc1_key: </span><span class="z-constant">{</span><span>derived_acc1_key</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify the private key derivation capability</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> derived_acc0_key</span><span class="z-keyword"> ==</span><span> finance_acc1</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">private_key</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Account 0 private key derivation failed</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> derived_acc1_key</span><span class="z-keyword"> ==</span><span> finance_acc2</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">private_key</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Account 1 private key derivation failed</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">✅ Private key derivation from department xprv successful</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-keyword"> except</span><span class="z-support"> Exception</span><span class="z-keyword"> as</span><span> e</span><span>:</span></span> <span class="giallo-l"><span> logger</span><span>.</span><span>error</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">System error: </span><span class="z-constant">%s</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> e</span><span>,</span><span class="z-variable"> exc_info</span><span class="z-keyword">=</span><span class="z-constant">True</span><span>)</span></span></code></pre> <p>run script:</p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">pip</span><span class="z-string"> install</span><span class="z-string"> bip32utils</span><span class="z-string"> eth_account</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name">python</span><span class="z-string"> stms.py</span></span></code></pre> <p>output：</p> <p><img src="https://wg-eips.ritovision.com/7908/./assets/img.png" alt="" /></p> <h2 id="security-considerations">Security Considerations</h2> <p>For treasury managers, hierarchical deterministic wallet management is more convenient, but it requires additional consideration of protective measures for the master key, such as schemes for splitting and storing mnemonic phrases or master keys.</p> <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-03-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Gajinder Singhhttps://github.com/g11tech https://wg-eips.ritovision.com/7898/

Separates the execution payload from beacon block to independently transmit them

<h2 id="abstract">Abstract</h2> <p>Currently, the beacon block in Ethereum Consensus embeds transactions within the <code>ExecutionPayload</code> field of <code>BeaconBlockBody</code>. This EIP proposes to replace <code>ExecutionPayload</code> with <code>ExecutionPayloadHeader</code> in <code>BeaconBlockBody</code> and to independently transmit <code>ExecutionPayloadWithInclusionProof</code>.</p> <p>However, this EIP makes no change to the block import mechanism, with the exception that block availability now includes waiting for the availability of <code>ExecutionPayloadWithInclusionProof</code>, making it different and simpler from proposals like ePBS/APS.</p> <p>But this availability requirement can in fact be restricted to <code>gossip</code> import while allowing optimistic syncing of the execution layer (EL) on checkpoint/range sync as EL can pull full blocks from their peers in optimistic sync as they do now.</p> <h2 id="motivation">Motivation</h2> <p>The Ethereum protocol has an ambitious goal to grow the <code>gasLimit</code> of the execution payloads (possibly by 10X). This leads to larger messages, negatively affecting the networking and block processing pipelines of the consensus layer (CL) clients leading to following issues:</p> <ol> <li>Higher latencies for the arrival of beacon blocks increase, requiring larger bandwidth resources to be made available for the beacon node.</li> <li>The greater number and size of transactions directly increase the merkelization compute time, increasing the import time of the block.</li> </ol> <p>We know from timing games that the block import latency greatly affects a client's performance to make correct head attestations. With this EIP, block transmission and block import processes will be decongested, allowing for greater flexibility in receiving a larger <code>ExecutionPayloadWithInclusionProof</code>, while the beacon block can simultaneously undergo processing.</p> <p>In addition, EL clients can also independently participate in forwarding and receiving larger execution blocks. That mechanism however can be independently developed and is out of scope for this EIP.</p> <p>Additional benefits obtained from this EIP:</p> <ul> <li>Consensus clients don't need to store and serve blocks with transactions, providing greater efficiency and reduced resource requirements for running a beacon node.</li> <li>The proposer-builder separation (PBS) pipeline becomes more efficient by the proposer transmitting the signed block directly to the p2p network, while submitting to the builder/relay for the independent reveal of the <code>ExecutionPayloadWithInclusionProof</code>.</li> <li>In the future with zero-knowledge (ZK) proof of the EL block execution, nodes could treat the transactions similarly to blobs which leverage data availability sampling (DAS) mechanisms for available data without requiring re-execution of transactions to establish validity. Hence the L1 execution could itself become a rollup by alleviating the need to import all transaction data by a node.</li> </ul> <p>Furthermore CL clients apis and code path will become cleaner and more maintainable because of collapse of blinded and full versions (like <code>BlindedBeaconBlock</code>, <code>BlindedBeaconBlockBody</code>) into same types.</p> <h2 id="specification">Specification</h2> <ul> <li><code>ExecutionPayload</code> in the <code>BeaconBlockBody</code> is replaced by <code>ExecutionPayloadHeader</code></li> <li><code>ExecutionPayloadWithInclusionProof</code> is computed by the block proposer/builder and gossiped independently on a separate new topic. Also builder <code>submitBlindedBlock</code> api is modified to respond with <code>ExecutionPayloadWithInclusionProof</code> instead.</li> <li>Data availability checks for block import into forkchoice now must wait for availability of the corresponding <code>ExecutionPayloadWithInclusionProof</code> but only for gossiped blocks</li> <li><code>newPayloadHeader</code> engine api is introduced to augment the previous usage of <code>newPayload</code> in block processing when <code>ExecutionPayload</code> is not available for e.g. in processing range synced blocks signaling EL clients to optimistic sync those payloads from EL p2p network.</li> </ul> <p>ELs can optionally introduce a <code>getExecutionPayload</code> method (similar to <code>getBlobs</code>) to assist with faster recovery of execution payload from the EL's p2p network peers who could announce new payload hashes when they see new <code>VALID</code> payloads. However, as noted above, that mechanism could be independently specified and is out of scope for this EIP.</p> <p>&lt;-- TODO: add spec details --&gt;</p> <h2 id="rationale">Rationale</h2> <p>There is another choice we could have made to go for <code>SignedExecutionPayload</code> instead of <code>ExecutionPayloadWithInclusionProof</code> and having a <code>SignedExecutionPayloadHeader</code> with builder signing these messages (validator is the builder in local block building). But without builder enshrinement tight gossip validation of <code>SignedExecutionPayload</code> would be an issue and could become a DOS vector.</p> <p>The benefit of <code>SignedExecutionPayload</code> design is that it could be transmitted ahead of even the <code>SignedExecutionPayloadHeader</code> inclusion in beacon block and is especially useful in PBS pipeline where the proposal to builder/relay latency can be reduced significantly.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change isn't backward compatible and a new hardfork is required to activate this EIP.</p> <h2 id="test-cases">Test Cases</h2> <p>&lt;-- TODO --&gt;</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>&lt;-- TODO --&gt;</p> <h2 id="security-considerations">Security Considerations</h2> <p>&lt;-- TODO --&gt;</p> <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-03-01T00:00:00+00:00 2026-02-11T14:48:26+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/7902/

EIP-5792 Capabilities allowing dApps and wallets to exchange all AA specific UserOp fields

<h2 id="abstract">Abstract</h2> <p><a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> defines a baseline JSON-RPC API for a communication between wallets and dapps, and provides an ability to extend the base protocol with "capabilities".</p> <p>This proposal defines a set of "capabilities" the wallets may want to implement in order to provide a comprehensive support for Account Abstraction (AA).</p> <p>These "capabilities" enable passing any data that may be required when using a Paymaster contract, allows limiting the time range during which the UserOperation is considered valid, provides a way for the dApp to manually control the semi-abstracted nonce and AA-specific gas limits of the UserOp, and even allow the dApp to take part in selecting the <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> account implementation.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> introduced Account Abstraction, enabling Smart Contract Accounts to function as first-class citizens in Ethereum. However, while <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> and <a href="https://wg-eips.ritovision.com/7769/">ERC-7769</a> define a low-level RPC API for Account Abstraction, they do not specify a way for advanced AA-aware dApps to communicate their supported features and parameters to the advanced AA Wallet Applications.</p> <p>This ERC addresses the issue by defining a structured set of capabilities tailored for AA-aware dApps and Wallet Applications.</p> <p>It utilises the <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> wallet capability model to express some of the critical aspects of AA, ensuring dApps can seamlessly adapt to different AA Wallets without requiring custom solutions.</p> <h2 id="specification">Specification</h2> <p>All actions in Account Abstraction within the context of EIP-5792 must be done on a single chain and atomically.</p> <p>We define the following list of new "capabilities" which together cover many features necessary for Account Abstraction. Note that use of Paymasters managed by a "paymaster web service" is described in <a href="https://wg-eips.ritovision.com/7677/">ERC-7677</a>.</p> <h3 id="create-eip-7702-authorization-capability">Create <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> Authorization Capability</h3> <p>This capability is designed to be used with <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> and requests the Wallet Application to provide an EIP-7702 authorization tuple for the specified address as part of the AA transaction.</p> <p>Identifier:</p> <p><code>eip7702Auth</code></p> <p>Interface:</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"> SetCodeForEOACapabilityParams</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Record</span><span>&lt;</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable"> account</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> EOA address</span></span> <span class="giallo-l"><span class="z-variable"> delegation</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> delegation address</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>&gt;</span></span></code></pre> <p>Supporting Wallet Applications MUST generate an EIP-7702 compatible transaction that sets a code of the <code>account</code> EOA address to the code of <code>delegation</code> specified in the request.</p> <h3 id="static-paymaster-configuration-capability">Static Paymaster Configuration Capability</h3> <p>The purpose of this capability is allowing applications to integrate with Paymasters that do not require the Wallet Application to resolve any dynamic configuration.</p> <p>The application may hard-code or resolve these parameters first and pass them with this capability.</p> <p>Identifier:</p> <p><code>staticPaymasterConfiguration</code></p> <p>Interface:</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"> StaticPaymasterConfigurationCapabilityParams</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Record</span><span>&lt;</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable"> paymaster</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> paymasterData</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> paymasterValidationGasLimit</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> <span class="giallo-l"><span class="z-variable"> paymasterPostOpGasLimit</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> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>&gt;</span><span>;</span></span></code></pre><h3 id="validity-time-range-capability">Validity Time Range Capability</h3> <p>The purpose of this capability is allowing the applications to explicitly specify the time range during which the requested operations will be valid after signing.</p> <p>Identifier:</p> <p><code>validityTimeRange</code></p> <p>Interface:</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"> ValidityTimeRangeCapabilityParams</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Record</span><span>&lt;</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable"> validAfter</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> operation valid only after this timestamp, in seconds</span></span> <span class="giallo-l"><span class="z-variable"> validUntil</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 class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> operation valid only before this timestamp, in seconds</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>&gt;</span></span></code></pre> <p>The Wallet Application MUST verify the time range [<code>validAfter</code>..<code>validUntil</code>] is valid and present it to the user in a human-readable way for confirmation as part of the transaction information.</p> <p>The Smart Contract Account MUST specify the time range [<code>validAfter</code>..<code>validUntil</code>] as the transaction validity range.</p> <h3 id="multidimensional-nonce-capability">Multidimensional Nonce Capability</h3> <p>The purpose of this capability is allowing the applications to explicitly specify the components of the semi-abstracted nonce as defined in <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a>.</p> <p>Identifier:</p> <p><code>multiDimensionalNonce</code></p> <p>Interface:</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"> MultiDimensionalNonceCapabilityParams</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Record</span><span>&lt;</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable"> nonceKey</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> <span class="giallo-l"><span class="z-variable"> nonceSequence</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 class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>&gt;</span></span></code></pre> <p>For Smart Contract Accounts that support multidimensional nonce values, the wallet must specify these parameters during the actual on-chain execution of the batch.</p> <h3 id="account-abstraction-gas-parameters-override-capability">Account Abstraction Gas Parameters Override Capability</h3> <p>The purpose of this capability is allowing the applications to override the Wallet Application's suggested values for all gas-related parameters.</p> <p>This capability provides very low-level access to the underlying Account Abstraction protocol and should only be used by applications closely coupled to a specific version of a specific protocol. It may also prove useful in the context of development and debugging.</p> <p>It is generally recommended that production dapps rely on higher-level features of Wallet Applications instead.</p> <p>Identifier:</p> <p><code>accountAbstractionGasParamsOverride</code></p> <p>Interface:</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"> AAGasParamsOverrideCapabilityParams</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Record</span><span>&lt;</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable"> preVerificationGas</span><span class="z-keyword">?</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> <span class="giallo-l"><span class="z-variable"> verificationGasLimit</span><span class="z-keyword">?</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> <span class="giallo-l"><span class="z-variable"> callGasLimit</span><span class="z-keyword">?</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> <span class="giallo-l"><span class="z-variable"> paymasterVerificationGasLimit</span><span class="z-keyword">?</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> <span class="giallo-l"><span class="z-variable"> paymasterPostOpGasLimit</span><span class="z-keyword">?</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> <span class="giallo-l"><span class="z-variable"> maxFeePerGas</span><span class="z-keyword">?</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> <span class="giallo-l"><span class="z-variable"> maxPriorityFeePerGas</span><span class="z-keyword">?</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 class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>&gt;</span></span></code></pre> <p>Notice that all fields in the <code>AAGasParamsOverrideCapabilityParams</code> are optional. Only the values that callers want to override must be provided.</p> <p>Wallet Applications should warn the users about the overrides being supplied by the call and use these values instead.</p> <p>Wallet Applications may choose to reject calls with conflicting configurations.</p> <h2 id="rationale">Rationale</h2> <!-- TODO --> <h2 id="security-considerations">Security Considerations</h2> <h3 id="eip7702auth"><code>eip7702Auth</code></h3> <p>This is by far the most sensitive capability in the document. There is no limit to the damage that can be done by signing the wrong capability.</p> <p>Wallet Applications MUST take extreme care when working with <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>.</p> <p>Wallet Applications MUST maintain a strict shortlist of well-known and publicly audited Smart Contract Account implementations that are acceptable as <code>delegation</code>.</p> <p>Authorization is an extremely sensitive operation and any vulnerability or malicious code in <code>delegation</code> will result in complete draining of the <code>account</code>.</p> <h3 id="staticpaymasterconfiguration"><code>staticPaymasterConfiguration</code></h3> <p>This capability has an opportunity to provide the <code>paymaster</code> and <code>paymasterData</code> values for the call. Incorrect or malicious values can be an attack vector. For example, a Paymaster contract may hold approvals for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens which may be drained this way.</p> <p>The Wallet Applications MUST make sure the provided values correspond to user intent. Fundamentally, this is not very different to how regular transactions' <code>calldata</code> must be verified.</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-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-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Forshtathttps://github.com/forshtat Shahaf Nacsonhttps://github.com/shahafn Dror Tiroshhttps://github.com/drortirosh Yoav Weisshttps://github.com/yoavw https://wg-eips.ritovision.com/7906/

A transaction type that provides a way for senders to restrict the outcomes of their execution

<h2 id="abstract">Abstract</h2> <p>This proposal allows the transaction payload to define write protections for balances and storage slots that are enforced at the protocol level. These protected transactions empower Ethereum users to restrict the behavior of the deployed on-chain smart contracts without needing to perform a deep analysis of their EVM bytecode.</p> <h2 id="motivation">Motivation</h2> <p>The total value of crypto assets that have been stolen to date exceeds the yearly GDP of a medium-sized nation. This level of loss and waste is indefensible and has a long list of negative consequences for everyone involved.</p> <p>Specifically, one of the major ways in which Ethereum users end up losing their funds is not exposing private keys, but instead being tricked into signing transactions that appear innocent in their Wallet applications but in practice perform a complete sweep of the senders' assets.</p> <p>The ability of an average user or a Wallet application to find, collect, review, and analyze the EVM code the transaction will execute is very limited.</p> <p>This leaves the users with no mechanism to enforce any restrictions on what the transaction actually does once it is signed. This leads users to perform blind signing in order to interact with Ethereum, exposing them to significant and avoidable risks.</p> <p>By providing the Wallets and dApps with the ability to restrict the possible <strong>outcomes</strong> of a transaction, we create a tool that users and wallets will apply to reduce their risk levels.</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>RESTRICTED_TX_COST</td><td>TBD</td></tr> <tr><td>TRACE_CALL_GAS_COST</td><td>TBD</td></tr> <tr><td>GET_TRACE_CALL_ADDRESS</td><td>TBD</td></tr> <tr><td>RESTRICTED_EXECUTION_TX_TYPE</td><td>TBD</td></tr> </tbody></table> <h3 id="new-transaction-type">New Transaction Type</h3> <p>We introduce a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction, "restricted execution transaction", where the <code>TransactionType</code> is <code>RESTRICTED_EXECUTION_TX_TYPE</code> and the <code>TransactionPayload</code> is the RLP serialization of the following:</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, value, calldata, access_list, authorization_list, asserter_address, asserter_data, asserter_gas_limit, signature_y_parity, signature_r, signature_s])</span></span></code></pre> <ul> <li><code>asserter_address</code> - the address of an existing contract that will be called for the <a href="https://wg-eips.ritovision.com/7906/#assertion-frame">Assertion Frame</a>.</li> <li><code>asserter_data</code> - the data to be passed as a call data to the Assertion Frame. In case the <code>asserter_address</code> is not set, this field acts as a <a href="https://wg-eips.ritovision.com/7906/#one-time-restrictions-code">One-Time Restrictions Code</a>.</li> <li><code>asserter_gas_limit</code> - the gas limit provided to the asserter call frame.</li> </ul> <h3 id="one-time-restrictions-code">One-Time Restrictions Code</h3> <p>The <code>asserter_address</code>, <code>asserter_data</code> and <code>asserter_gas_limit</code> fields behave similarly to the <code>destination</code>, <code>calldata</code> and <code>gas_limit</code> fields in existing transaction types.</p> <p>If the <code>asserter_address</code> value is not set, the <code>asserter_data</code> is loaded and executed as <code>asserter_code</code>. This is similar to the <code>init_code</code> parameter logic of a legacy transaction type.</p> <p>This code is executed in a static context and cannot modify the blockchain state, set contract code or deploy new contracts.</p> <h3 id="assertion-frame">Assertion Frame</h3> <p>After the transaction execution frame is finished without reverting, the <code>RESTRICTED_EXECUTION_TX_TYPE</code> transactions MUST also successully execute a second execution frame. This frame runs in a static context and cannot modify storage or emit logs.</p> <p>The purpose of this frame is to execute the state change assertions as prescribed by the <code>asserter_address</code> and <code>asserter_data</code> parameters.</p> <p>In case of a revert in the Assertion Frame, the entire transaction is reverted.</p> <p>The gas costs in the Assertion Frame are charged same as in the regular execution.</p> <h3 id="execution-restrictions-assertion-frame">Execution Restrictions Assertion Frame</h3> <p>There are a number of parameters that constitute the core of the transaction's execution restriction. These parameters are joined together and RLP encoded as part of the transaction payload. There are no additional costs associated with providing this parameter other than its gas cost equivalent to <code>calldata</code>.</p> <p>In case any of the specified restrictions is violated, the entire transaction MUST <strong>revert on-chain</strong> and its gas MUST be paid until the point of the restriction violation.</p> <p>The transaction is considered to be a valid transaction that can be included in a block and pays its own gas regardless of the contents of the <code>execution_restrictions</code> parameter.</p> <h3 id="transaction-trace-precompile">Transaction Trace Precompile</h3> <p>We introduce a precompile at address <code>GET_TRACE_CALL_ADDRESS</code>.</p> <p>When called in a regular execution frame, the call returns a full stack trace of the current frame up to this point.</p> <p>When called in the Assertion Frame, the call returns a full stack trace of the entire transaction.</p> <p>The format of the returned transaction stack trace is described in <a href="https://wg-eips.ritovision.com/7906/#transaction-trace-data-structure">Transaction Trace Data Structure</a>.</p> <h3 id="transaction-trace-data-structure">Transaction Trace Data Structure</h3> <p>The stack trace is represented as an ABI encoding of the following struct:</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"> Trace</span><span> {</span></span> <span class="giallo-l"><span> Call</span><span>[</span><span>]</span><span> calls</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"> Call</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> target</span><span>;</span></span> <span class="giallo-l"><span> Storage</span><span>[</span><span>]</span><span class="z-storage z-type"> storage</span><span>;</span></span> <span class="giallo-l"><span> Balance</span><span>[</span><span>]</span><span> balances</span><span>;</span></span> <span class="giallo-l"><span> CodeHash</span><span>[</span><span>]</span><span> codeHash</span><span>;</span></span> <span class="giallo-l"><span> OpCode</span><span>[</span><span>]</span><span> opCodes</span><span>;</span></span> <span class="giallo-l"><span> Call</span><span>[</span><span>]</span><span> calls</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"> Storage</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> slotId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> oldValue</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> newValue</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"> Balance</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 class="z-support"> uint256</span><span> oldBalance</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> newBalance</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"> CodeHash</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> contract</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> newCodeHash</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"> OpCode</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> opCode</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span> params</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="opcodes-traced">Opcodes Traced</h4> <p>Including all opcodes called during a transaction execution in the stack trace is not practical. Instead, only the following opcodes with potentially dangerous non-local effects are reported as part of the <code>opCodes</code> field:</p> <ul> <li><code>SELFDESTRUCT</code> (<code>0xFF</code>)</li> <li><code>DELEGATECALL</code> (<code>0xF4</code>)</li> <li><code>CALLCODE</code> (<code>0xF2</code>)</li> <li><code>STATICCALL</code> (<code>0xFA</code>)</li> <li><code>CALL</code> (<code>0xFA</code>)</li> <li><code>LOG</code> (<code>0xA0</code>)</li> <li><code>LOG1</code> (<code>0xA1</code>)</li> <li><code>LOG2</code> (<code>0xA2</code>)</li> <li><code>LOG3</code> (<code>0xA3</code>)</li> <li><code>LOG4</code> (<code>0xA4</code>)</li> <li><code>REVERT</code> (<code>0xFD</code>)</li> <li><code>INVALID</code> (<code>0xFE</code>)</li> <li><code>KECCAK256</code> (<code>0x20</code>)</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="new-transaction-type-and-assertion-frame">New Transaction Type and Assertion Frame</h3> <p>One of the main advantages of a new Transaction Type for the Restricted Behaviour feature is the ability to protect all existing EOAs, and not just smart accounts. This makes it preferable to introduce a new Transaction Type instead of any other approach that would only work for smart contract accounts.</p> <h3 id="transaction-trace-precompile-behaviour">Transaction Trace Precompile Behaviour</h3> <p>It is important for us to provide the same protection level to both EOAs and Smart Accounts. The Smart Accounts are not able to initiate a <code>RESTRICTED_EXECUTION_TX_TYPE</code> transaction themselves, and instead need to rely on checks performed during the regular execution frame of any transaction type.</p> <p>By exposing the <code>GET_TRACE_CALL_ADDRESS</code> precompile at all times, we allow any smart contract to perform the state change assertions it may need to ensure safety and security.</p> <h3 id="deployable-and-one-time-restrictions-code">Deployable and One-Time Restrictions Code</h3> <p>In some scenarios, the wallets are likely to want to apply the exact same transaction behaviour to all transactions they initiate.</p> <p>In this case, it is reasonalbe and more efficient to deploy the assertions on-chain as a smart contract module, and provide its address and the inputs it may need.</p> <p>However, it is possible that the wallet may want to prepare the restrictions for the transaction dynamically. In that case, there is no benefit in having the assertion code permanently deployed, and it is more efficient to provide such code as part of the transaction payload. Luckily, the EVM already has a very similar behaviour defined for the <code>init_code</code> field, and it appears to fit the task perfectly.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal describes a new transaction type that should not affect the functionality of existing systems.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="correct-wallet-ui-presentation">Correct Wallet UI presentation</h3> <p>Successfull use of the <code>RESTRICTED_EXECUTION_TX_TYPE</code> transaction type requires the wallets to be abile to correctly understand and present the restrictions imposed on the transaction to the users.</p> <p>Wallets will need to be able to understand the meaning of the state changes being permitted by the transaction. This requires wallets to be aware of all major ERC standards, such as <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. In many cases, this also requires the wallets to be able to fetch and analyze the source code of the executed contracts.</p> <p>However, the introduction of the Execution Restrictions feature significantly streamlines the process by removing the need for a deep understanding of the executed <strong>code</strong>. Instead, only high-level information about the stack traces' meaning is required for a clear and safe representation of possible transaction outcomes.</p> <h3 id="insufficiently-restrictive-transactions">Insufficiently Restrictive Transactions</h3> <p>The worst outcome of introducing a security feature is creating a false sense of security for its user.</p> <p>Wallets are expected to provide the behaviour restriction logic that protects their users' valuable assets.</p> <p>It is critical that dApps, wallets, and users become educated about the consequences of not limiting their transactions' execution with sufficient strictness.</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-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-02-18T00:00:00+00:00 2026-02-11T14:48:26+00:00 Jeroen Offerijnshttps://github.com/hieronx Vikram Arunhttps://github.com/vikramarun https://wg-eips.ritovision.com/7887/

Extension of ERC-7540 with cancelation support

<h2 id="abstract">Abstract</h2> <p>The following standard extends <a href="https://wg-eips.ritovision.com/7540/">ERC-7540</a> by adding support for asynchronous cancelation flows.</p> <p>New methods are added to asynchronously cancel a deposit or redeem Request, view the status of the cancelation Request, and claim the assets or shares as a result of the cancelation Request.</p> <h2 id="motivation">Motivation</h2> <p>Shares or assets locked for Requests can be stuck in the Pending state. For some use cases, such as redeeming from a pool of long-dated real-world assets, this can take a considerable amount of time.</p> <p>This standard expands the scope of Asynchronous ERC-7540 Vaults by adding cancelation support.</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="definitions">Definitions</h3> <p>The existing definitions from <a href="https://wg-eips.ritovision.com/7540/">ERC-7540</a> apply.</p> <h3 id="cancelation-lifecycle">Cancelation Lifecycle</h3> <p>After submission, cancelation Requests go through Pending, Claimable, and Claimed stages. An example lifecycle for a deposit cancelation Request is visualized in the table below.</p> <table><thead><tr><th><strong>State</strong></th><th><strong>User</strong></th><th><strong>Vault</strong></th></tr></thead><tbody> <tr><td>Pending</td><td><code>cancelDepositRequest(requestId, controller)</code></td><td><code>pendingCancelDepositRequest[controller] = true</code></td></tr> <tr><td>Claimable</td><td></td><td><em>Internal cancelation fulfillment</em>: <code>pendingCancelDepositRequest[controller] = false</code>; <code>claimableCancelDepositRequest[controller] = assets</code></td></tr> <tr><td>Claimed</td><td><code>claimCancelDepositRequest(requestId, receiver, controller)</code></td><td><code>claimableDepositRequest[controller] -= assets</code>; <code>asset.balanceOf[receiver] += assets</code></td></tr> </tbody></table> <p><code>pendingCancelDepositRequest</code> and <code>claimableCancelDepositRequest</code> are defined in the <a href="https://wg-eips.ritovision.com/7887/#methods">Methods</a> section.</p> <p>Requests MUST NOT skip or otherwise short-circuit the Claim state. In other words, to initiate and claim a Request, a user MUST call both cancel* and the corresponding Claim function separately, even in the same block. Vaults MUST NOT "push" tokens onto the user after a Request, users MUST "pull" the tokens via the Claim function.</p> <p>Requests MAY skip straight from the Pending to the Claimable stage, in the case of synchronous cancelation flows.</p> <p>While a deposit cancelation Request is Pending, new deposit Requests are blocked. Likewise, while a redeem cancelation Request is Pending, new redeem Requests are blocked.</p> <h3 id="methods">Methods</h3> <h4 id="canceldepositrequest"><code>cancelDepositRequest</code></h4> <p>Submits a Request for asynchronous deposit cancelation. This places the Request in Pending state, with a corresponding increase in <code>pendingCancelDepositRequest</code> for the full amount of the pending deposit Request.</p> <p>When the cancelation is Pending, new deposit Requests are blocked and <code>requestDeposit</code> MUST revert.</p> <p>When the cancelation is Claimable, <code>claimableCancelDepositRequest</code> will be increased for the <code>controller</code>. <code>claimCancelDepositRequest</code> can subsequently be called by <code>controller</code> to receive <code>assets</code>. A Request MAY transition straight to Claimable state but MUST NOT skip the Claimable state.</p> <p><code>controller</code> MUST equal <code>msg.sender</code> unless the <code>controller</code> has approved the <code>msg.sender</code> as an operator.</p> <p>MUST emit the <code>CancelDepositRequest</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"> c</span><span class="z-string">ancelDepositRequest</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"> r</span><span class="z-string">equestId</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"> c</span><span class="z-string">ontroller</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></code></pre><h4 id="pendingcanceldepositrequest"><code>pendingCancelDepositRequest</code></h4> <p>Whether the given <code>requestId</code> and <code>controller</code> have a pending deposit cancelation Request.</p> <p>MUST NOT show any variations depending on the caller.</p> <p>MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</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">endingCancelDepositRequest</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"> r</span><span class="z-string">equestId</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"> c</span><span class="z-string">ontroller</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"> i</span><span class="z-string">sPending</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="claimablecanceldepositrequest"><code>claimableCancelDepositRequest</code></h4> <p>The amount of <code>assets</code> in Claimable cancelation state for the <code>controller</code> to claim.</p> <p>MUST NOT show any variations depending on the caller.</p> <p>MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</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">laimableCancelDepositRequest</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"> r</span><span class="z-string">equestId</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"> c</span><span class="z-string">ontroller</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"> 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="claimcanceldepositrequest"><code>claimCancelDepositRequest</code></h4> <p>Claims the deposit cancelation Request with <code>requestId</code> and <code>controller</code>.</p> <p>Transfers <code>assets</code> to <code>receiver</code>.</p> <p><code>controller</code> MUST equal <code>msg.sender</code> unless the <code>controller</code> has approved the <code>msg.sender</code> as an operator.</p> <p>MUST emit the <code>ClaimCancelDepositRequest</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"> c</span><span class="z-string">laimCancelDepositRequest</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"> r</span><span class="z-string">equestId</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"> c</span><span class="z-string">ontroller</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></code></pre><h4 id="cancelredeemrequest"><code>cancelRedeemRequest</code></h4> <p>Submits a Request for asynchronous redeem cancelation. This places the Request in Pending state, with a corresponding increase in <code>pendingCancelRedeemRequest</code> for the full amount of the pending redeem Request.</p> <p>When the cancelation is Pending, new redeem Requests are blocked and <code>requestRedeem</code> MUST revert.</p> <p>When the cancelation is Claimable, <code>claimableCancelRedeemRequest</code> will be increased for the <code>controller</code>. <code>claimCancelRedeemRequest</code> can subsequently be called by <code>controller</code> to receive <code>shares</code>. A Request MAY transition straight to Claimable state but MUST NOT skip the Claimable state.</p> <p><code>controller</code> MUST equal <code>msg.sender</code> unless the <code>controller</code> has approved the <code>msg.sender</code> as an operator.</p> <p>MUST emit the <code>CancelRedeemRequest</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"> c</span><span class="z-string">ancelRedeemRequest</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"> r</span><span class="z-string">equestId</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"> c</span><span class="z-string">ontroller</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></code></pre><h4 id="pendingcancelredeemrequest"><code>pendingCancelRedeemRequest</code></h4> <p>Whether the given <code>requestId</code> and <code>controller</code> have a pending redeem cancelation Request.</p> <p>MUST NOT show any variations depending on the caller.</p> <p>MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</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">endingCancelRedeemRequest</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"> r</span><span class="z-string">equestId</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"> c</span><span class="z-string">ontroller</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"> i</span><span class="z-string">sPending</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="claimablecancelredeemrequest"><code>claimableCancelRedeemRequest</code></h4> <p>The amount of <code>shares</code> in Claimable cancelation state for the <code>controller</code> to claim.</p> <p>MUST NOT show any variations depending on the caller.</p> <p>MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</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">laimableCancelRedeemRequest</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"> r</span><span class="z-string">equestId</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"> c</span><span class="z-string">ontroller</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"> 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="claimcancelredeemrequest"><code>claimCancelRedeemRequest</code></h4> <p>Claims the redeem cancelation Request with <code>requestId</code> and <code>controller</code>.</p> <p>Transfers <code>assets</code> to <code>receiver</code>.</p> <p><code>controller</code> MUST equal <code>msg.sender</code> unless the <code>controller</code> has approved the <code>msg.sender</code> as an operator.</p> <p>MUST emit the <code>ClaimCancelRedeemRequest</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"> c</span><span class="z-string">laimCancelRedeemRequest</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"> r</span><span class="z-string">equestId</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 class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span></code></pre><h3 id="events">Events</h3> <h4 id="canceldepositrequest-1"><code>CancelDepositRequest</code></h4> <p><code>controller</code> has requested cancelation of their deposit Request with request ID <code>requestId</code>. <code>sender</code> is the caller of the <code>cancelDepositRequest</code> which may not be equal to the <code>controller</code>.</p> <p>MUST be emitted when a deposit cancelation Request is submitted using the <code>cancelDepositRequest</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"> C</span><span class="z-string">ancelDepositRequest</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"> c</span><span class="z-string">ontroller</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"> r</span><span class="z-string">equestId</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"> s</span><span class="z-string">ender</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></code></pre><h4 id="canceldepositclaim"><code>CancelDepositClaim</code></h4> <p><code>controller</code> has claimed their deposit cancelation Request with request ID <code>requestId</code>. <code>receiver</code> is the destination of the <code>assets</code>. <code>sender</code> is the caller of the <code>claimCancelDepositRequest</code> which may not be equal to the <code>controller</code>.</p> <p>MUST be emitted when a deposit cancelation Request is submitted using the <code>claimCancelDepositRequest</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"> C</span><span class="z-string">ancelDepositClaim</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"> c</span><span class="z-string">ontroller</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"> r</span><span class="z-string">eceiver</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"> r</span><span class="z-string">equestId</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"> s</span><span class="z-string">ender</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"> a</span><span class="z-string">ssets</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><h4 id="cancelredeemrequest-1"><code>CancelRedeemRequest</code></h4> <p><code>controller</code> has requested cancelation of their deposit Request with request ID <code>requestId</code>. <code>sender</code> is the caller of the <code>cancelRedeemRequest</code> which may not be equal to the <code>controller</code>.</p> <p>MUST be emitted when a redeem cancelation Request is submitted using the <code>cancelRedeemRequest</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"> C</span><span class="z-string">ancelRedeemRequest</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"> c</span><span class="z-string">ontroller</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"> r</span><span class="z-string">equestId</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"> s</span><span class="z-string">ender</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></code></pre><h4 id="cancelredeemclaim"><code>CancelRedeemClaim</code></h4> <p><code>controller</code> has claimed their redeem cancelation Request with request ID <code>requestId</code>. <code>receiver</code> is the destination of the <code>shares</code>. <code>sender</code> is the caller of the <code>claimCancelRedeemRequest</code> which may not be equal to the <code>controller</code>.</p> <p>MUST be emitted when a redeem cancelation Request is submitted using the <code>claimCancelRedeemRequest</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"> C</span><span class="z-string">ancelRedeemClaim</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"> c</span><span class="z-string">ontroller</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"> r</span><span class="z-string">eceiver</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"> r</span><span class="z-string">equestId</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"> s</span><span class="z-string">ender</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"> s</span><span class="z-string">hares</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="erc-165-support"><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> support</h3> <p>Smart contracts implementing this Vault standard MUST implement the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> <code>supportsInterface</code> function.</p> <p>Asynchronous deposit Vaults with cancelation support MUST return the constant value <code>true</code> if <code>0x8bf840e3</code> is passed through the <code>interfaceID</code> argument.</p> <p>Asynchronous redemption Vaults with cancelation support MUST return the constant value <code>true</code> if <code>0xe76cffc7</code> is passed through the <code>interfaceID</code> argument.</p> <h2 id="rationale">Rationale</h2> <h3 id="blocking-requests-during-cancelation">Blocking Requests during Cancelation</h3> <p>When <code>cancelDepositRequest</code> is called by a <code>controller</code>, new deposit Requests are blocked for this <code>controller</code>, and the equivalent applies to the redeem flow.</p> <p>This requirement simplifies the possible states of vaults implementing asynchronous cancelation flows.</p> <p>The alternative would create possible states where a cancelation is pending and a new deposit Request is triggered, leading to the current state being complex to read for integrators.</p> <h3 id="mandated-support-for-erc-165">Mandated Support for <a href="https://wg-eips.ritovision.com/165/">ERC-165</a></h3> <p>Implementing support for <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> is mandated because of the optionality of flows as defined in <a href="https://wg-eips.ritovision.com/7540/">ERC-7540</a>. Integrations can use the <code>supportsInterface</code> method to check whether a vault is fully asynchronous, partially asynchronous, or fully synchronous (for which it is just following the <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a>), and use a single contract to support all cases.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The interface is fully backwards compatible with <a href="https://wg-eips.ritovision.com/7540/">ERC-7540</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Existing security considerations from <a href="https://wg-eips.ritovision.com/7540/">ERC-7540</a> 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> 2025-02-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Henry Arnesonhttps://github.com/godzillaba Chris Bucklandhttps://github.com/yahgwai https://wg-eips.ritovision.com/7888/

Trustless storage-based message broadcasting for rollups.

<h2 id="abstract">Abstract</h2> <p>This ERC defines a protocol for cross-rollup messaging using state commitments. Users can broadcast messages on a source chain, and those messages can be verified on any other chain that shares a common ancestor with the source chain.</p> <p>A state commitment is a <code>bytes32</code> hash that commits to a chain's state (e.g., block hash or state root). The protocol supports different types of state commitments depending on what the rollup commits to its parent chain. Block hashes are the recommended state commitment, but state roots or other commitments may be used, such as batch hashes (since some rollups don't commit single blocks, but batches of blocks instead).</p> <p>Each chain deploys a singleton Receiver and Broadcaster contract. Broadcasters store messages; Receivers verify the Broadcasters' state on remote chains. To do this, a Receiver first verifies a chain of state commitment proofs to recover a remote state commitment, then verifies the Broadcaster's state at that commitment.</p> <p>Critically, the logic for verifying state commitment proofs is not hardcoded in the Receiver. Instead, it delegates this to a user specified list of StateProver contracts. Each StateProver defines how to verify a state commitment proof for a specific home chain to recover the state commitment of a specific target chain. Because the state commitment schemes and layouts of rollup contracts can change over time, the state commitment proof verification process itself must also be upgradeable—hence the StateProvers are upgradeable. This flexible, upgradeable proof verification model is the core contribution of this standard.</p> <h2 id="motivation">Motivation</h2> <p>The Ethereum ecosystem is experiencing a rapid growth in the number of rollup chains. As the number of chains grows, the experience becomes more fragmented for users, creating a need for trustless "interop" between rollup chains. These rollup chains, hosted on different rollup stacks, have heterogeneous properties, and as yet there does not exist a simple, trustless, unified mechanism for sending messages between these diverse chains.</p> <p>Many classes of applications could benefit from a unified system for broadcasting messages across chains. Some examples include:</p> <ul> <li><strong>Intent-Based Protocols:</strong> These protocols enable "fillers" to quickly execute crosschain actions on behalf of users, followed by slower, trustless messaging to settle these actions. However, due to the lack of a simple, unified interface for sending settlement messages, intent protocols often develop proprietary methods. This raises adoption barriers for fillers, integrators, and new protocols. A pluggable, standardized messaging solution that works across rollup stacks would allow developers and standards authors to focus on other components of the intent stack, such as fulfillment constraints, order formats, and escrow.</li> <li><strong>Governance of multichain apps:</strong> Multichain apps often have a single chain where core governance contracts are located. A standardized broadcast messaging system simplifies the dissemination of proposal results to all instances of a multichain app.</li> <li><strong>Multichain Oracles:</strong> Some classes of oracles may benefit from being able to post their data to a single chain, while having that same data easily accessible across many other chains.</li> </ul> <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="compatibility-requirements">Compatibility Requirements</h3> <p>Chains must satisfy the following conditions to be compatible with the system:</p> <ul> <li>Must store finalized state commitments on the parent chain</li> <li>Must store parent chain state commitments in child chain state</li> <li>Must be EVM equivalent with L1. StateProvers are deployed as copies on many chains, so need to behave the same on all those chains</li> </ul> <h3 id="constants">Constants</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"> constant</span><span> STATE_PROVER_POINTER_SLOT </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-string">&quot;eip7888.pointer.slot&quot;</span><span>)</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>;</span></span></code></pre><h3 id="state-commitments">State Commitments</h3> <p>A <strong>state commitment</strong> is a <code>bytes32</code> hash that commits to the state of a chain at a particular point in time. This commitment is produced by the rollup and serves as a cryptographic representation of the chain's state. The most common state commitments are:</p> <ul> <li><strong>Block hash</strong>: A hash of the block header, which is the recommended state commitment for most implementations</li> <li><strong>State root</strong>: The root of the state tree (e.g., Merkle-Patricia Trie) or other state commitment structure</li> <li><strong>Batch hash</strong>: A hash of a batch of blocks, used by some rollups that commit batches of blocks rather than individual blocks</li> </ul> <p>The choice of state commitment depends on what the rollup commits to its parent chain. Different rollups may use different state commitments, and the StateProver is responsible for verifying proofs that recover these commitments from the parent chain's state.</p> <h3 id="broadcaster">Broadcaster</h3> <p>The Broadcaster is responsible for storing messages in state to be read by Receivers on other chains. Callers of the Broadcaster are known as Publishers. The Broadcaster stores only 32 byte messages.</p> <p>The Broadcaster does not accept duplicate messages from the same publisher.</p> <div align="center"> <img src="./assets/broadcasting.svg" alt="Figure 1" width="30%"/> <br/> <em>Figure 1: A Publisher at address 0x4 calling a Broadcaster at address 0x3</em> </div> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Broadcasts messages to receivers.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IBroadcaster</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 message is broadcast.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> message</span><span class="z-comment"> The message that was broadcast by the publisher.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> publisher</span><span class="z-comment"> The address of the publisher.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MessageBroadcast</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> message</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> publisher</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"> Broadcasts a message. Callers are called &quot;publishers&quot;.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST revert if the publisher has already broadcast the message.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST emit MessageBroadcast.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST store block.timestamp in slot keccak(message, msg.sender).</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MAY use additional transmission mechanisms (e.g., child-to-parent native bridges) to make messages visible.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> message</span><span class="z-comment"> The message to broadcast.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> broadcastMessage</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> message</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="stateprovers">StateProvers</h3> <p>StateProvers prove a unidirectional link between two chains that have direct access to each other's finalized state commitments. The chains in this link are called the <strong>home chain</strong> and the <strong>target chain</strong>. StateProvers are responsible for verifying state commitment proofs to prove the existence of finalized target state commitments in the state of the home chain. Block hashes are the recommended state commitment, but implementations may use other commitments (e.g., state roots, batch hashes).</p> <p>Since the StateProvers are unidirectional, each chain needs to have two:</p> <ul> <li>One whose home is the child chain and target is the parent chain.</li> <li>One whose home is the parent chain and target is the child chain.</li> </ul> <p>StateProvers MUST ensure that they will have the same deployed code hash on all chains.</p> <div align="center"> <img src="./assets/BHP.svg" alt="Figure 2" width="30%"/> <br/> <em>Figure 2: A StateProver with home chain L and target chain M</em> </div> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> The IStateProver is responsible for retrieving the state commitment of its target chain given its home chain&#39;s state.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> The home chain&#39;s state is given either by a state commitment and proof, or by the StateProver executing on the home chain.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> A single home and target chain are fixed by the logic of this contract.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IStateProver</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"> Verify the state commitment of the target chain given the state commitment of the home chain and a proof.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST revert if called on the home chain.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST revert if the input is invalid or the input is not sufficient to determine the state commitment.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST return a target chain state commitment.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST be pure, with 1 exception: MAY read address(this).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"> homeStateCommitment</span><span class="z-comment"> The state commitment of the home chain.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> input</span><span class="z-comment"> Any necessary input to determine a target chain state commitment from the home chain state commitment.</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"> targetStateCommitment</span><span class="z-comment"> The state commitment of the target chain.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyTargetStateCommitment</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> homeStateCommitment</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> input</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">bytes32</span><span class="z-variable"> targetStateCommitment</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 state commitment of the target chain. Does so by directly accessing state on the home chain.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST revert if not called on the home chain.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST revert if the target chain&#39;s state commitment cannot be determined.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST return a target chain state commitment.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> SHOULD use the input to determine a specific state commitment to return. (e.g. input could be a block number)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> SHOULD NOT read from its own storage. This contract is not meant to have state.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MAY make external calls.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> input</span><span class="z-comment"> Any necessary input to fetch a target chain state commitment.</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"> targetStateCommitment</span><span class="z-comment"> The state commitment of the target chain.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTargetStateCommitment</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> input</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 class="z-variable"> targetStateCommitment</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"> Verify a storage slot given a target chain state commitment and a proof.</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 NOT assume it is being called on the home chain.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST revert if the input is invalid or the input is not sufficient to determine a storage slot and its value.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST return a storage slot and its value on the target chain.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST be pure, with 1 exception: MAY read address(this).code.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> While messages MUST be stored in storage slots, alternative reading mechanisms may be used in some cases.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> targetStateCommitment</span><span class="z-comment"> The state commitment of the target chain.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> input</span><span class="z-comment"> Any necessary input to determine a single storage slot and its value.</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"> account</span><span class="z-comment"> The address of the account on the target chain.</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"> slot</span><span class="z-comment"> The storage slot of the account on the target chain.</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"> The value of the storage slot.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyStorageSlot</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> targetStateCommitment</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> input</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 class="z-variable"> account</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> slot</span><span>,</span><span class="z-support"> bytes32</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"> @notice</span><span class="z-comment"> The version of the state commitment prover.</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 pure, with 1 exception: MAY read address(this).code.</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">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="stateproverpointers">StateProverPointers</h3> <p>StateProvers can be used to get or verify target state commitments, however since their verification logic is immutable, changes to the structure of the home or target chain can break the logic in these Provers. A StateProverPointer is a Pointer to a StateProver which can be updated if proving logic needs to change.</p> <p>StateProverPointers are used to reference StateProvers as opposed to referencing Provers directly. To that end, wherever a StateProver is deployed a StateProverPointer needs to be deployed to reference it.</p> <p>StateProverPointers allow a permissioned party to update the Prover reference within the Pointer. Choosing which party should have the permission to update the Prover reference should be carefully considered. The general rule is that if an update to the target or home chain could break the logic in the current Prover, then the party, or mechanism, able to make that update should also be given permission to update the Prover. See <a href="https://wg-eips.ritovision.com/7888/#security-considerations">Security Considerations</a> for more information on StateProverPointer ownership and updates.</p> <p>When updating a StateProverPointer to point to a new StateProver implementation:</p> <ul> <li>The home and target chain of the new StateProver MUST be identical to the previous StateProver.</li> <li>The new StateProver MUST have a higher version than the previous StateProver.</li> </ul> <p>StateProverPointers MUST store the code hash of the StateProver implementation in slot <code>STATE_PROVER_POINTER_SLOT</code>.</p> <div align="center"> <img src="./assets/pointer.svg" alt="Figure 3" width="30%"/> <br/> <em>Figure 3: A StateProverPointer at address 0xA pointing to a StateProver with home chain L and target chain M</em> </div> <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"> IStateProverPointer</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Keeps the code hash of the latest version of a state commitment prover.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> MUST store the code hash in storage slot STATE_PROVER_POINTER_SLOT.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Different versions of the prover MUST have the same home and target chains.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> If the pointer&#39;s prover is updated, the new prover MUST have a higher IStateProver::version() than the old one.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> These pointers are always referred to by their address on their home chain.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IStateProverPointer</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"> Return the code hash of the latest version of the prover.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> implementationCodeHash</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"> Return the address of the latest version of the prover on the home chain.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> implementationAddress</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="routes">Routes</h3> <p>A route is a relative path from a Receiver on a local chain to a remote chain. It is constructed of many single degree links dictated by StateProverPointers. Receivers use the StateProvers that the Pointers reference to verify a series of proofs to obtain the remote chain's state commitment. A route works with any state commitment scheme (block hashes, state roots, etc.) and is defined by the list of Pointer addresses on their home chains.</p> <p>A valid route MUST obey the following:</p> <ul> <li>Home chain of the <code>route[0]</code> Pointer must equal the local chain</li> <li>Target chain of the <code>route[i]</code> Pointer must equal home chain of the <code>route[i+1]</code> Pointer</li> </ul> <div align="center"> <img src="./assets/route.svg" alt="Figure 4" width="80%"/> <br/> <em>Figure 4: A route [0xA, 0xB, 0xC] from chain L to chain R<br/> Chain L is an L2, Chain M is Ethereum Mainnet, Chain P is another L2, and Chain R is an L3 settling to Chain P</em> </div> <h3 id="identifiers">Identifiers</h3> <p>Accounts on remote chains are identified by the route taken from the local chain plus the address on the remote chain. The Pointer addresses used in the route, along with the remote address, are cumulatively keccak256 hashed together to form a <strong>Remote Account ID</strong>.</p> <p>In this way any address on a remote chain, including Pointers and Broadcasters, can be uniquely identified relative to the local chain by their Remote Account ID.</p> <p>ID's depend on a route and are therefore always <em>relative</em> to a local chain. In other words, the same account on a given chain will have different ID's depending on the route from the local chain.</p> <p>The Remote Account ID is defined as <code>accumulator([...route, remoteAddress])</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"> accumulator</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"> elems</span><span>)</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> acc</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> elems</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> acc </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>acc</span><span>,</span><span> elems</span><span>[</span><span>i</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>In Figure 4:</p> <ul> <li>The Remote Account ID of Broadcaster at <code>0x3</code> is <code>accumulator([0xA, 0xB, 0xC, 0x3])</code></li> <li>The Remote Account ID of StateProverPointer <code>0xC</code> is <code>accumulator([0xA, 0xB, 0xC])</code>.</li> </ul> <h3 id="stateprovercopies">StateProverCopies</h3> <p>StateProverCopies are exact copies of StateProvers deployed on non-home chains. When a StateProver code hash is de-referenced from a Pointer, a copy of the StateProver may be used to execute its logic. Since the Pointer references the prover by code hash, a local copy of the Prover can be deployed and used to execute specific proving logic. The Receiver caches a map of <code>mapping(bytes32 stateProverPointerId =&gt; IStateProver stateProverCopy)</code> to keep track of StateProverCopies.</p> <div align="center"> <img src="./assets/BHPCopy.svg" alt="Figure 5" width="30%"/> <br/> <em>Figure 5: A StateProverCopy of StateProver M->P on chain L</em> </div> <h3 id="receiver">Receiver</h3> <p>The Receiver is responsible for verifying 32 byte messages deposited in Broadcasters on other chains. The caller provides the Receiver with a route to the remote account and proof to verify the route.</p> <div align="center"> <img src="./assets/receiving.svg" alt="Figure 6" width="80%"/> <br/> <em>Figure 6: Example of a Receiver reading a message from a Broadcaster on chain R</em> </div> <p>The calls in Figure 6 perform the following operations:</p> <ol> <li>Subscriber calls <code>IReceiver::verifyBroadcastMessage</code>, passing route <code>[0xA, 0xB, 0xC]</code>, proof data, message, publisher.</li> <li>Receiver calls <code>IStateProverPointer(0xA)::implementationAddress</code> to get the address of StateProver L-&gt;M</li> <li>Receiver calls <code>IStateProver(Prover L-&gt;M)::getTargetState</code>, passing input given by Subscriber to get a state commitment of chain M.</li> <li>Receiver calls <code>IStateProver(Prover Copy M-&gt;P)::verifyTargetState</code>, passing chain M's state commitment and proof data by Subscriber to get a state commitment of chain P.</li> <li>Receiver calls <code>IStateProver(Prover Copy P-&gt;R)::verifyTargetState</code>, passing chain P's state commitment and proof data by Subscriber to get a state commitment of chain R.</li> <li>Finally, Receiver calls <code>IStateProver(Prover Copy P-&gt;R)::verifyStateValue</code>, passing input given by Subscriber to get a storage slot from the Broadcaster. The Receiver returns the Broadcaster's Remote Account ID and the message's timestamp to Subscriber.</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Reads messages from a broadcaster.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IReceiver</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"> Arguments required to read state of an account on a remote chain.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The proof is always for a single storage slot. If the proof is for multiple slots the IReceiver MUST revert.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The proof format depends on the state commitment scheme used by the StateProver (e.g., storage proofs).</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> While messages MUST be stored in storage slots, alternative reading mechanisms may be used in some cases.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> route</span><span class="z-comment"> The home chain addresses of the StateProverPointers along the route to the remote chain.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> scpInputs</span><span class="z-comment"> The inputs to the StateProver / StateProverCopies.</span></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"> Proof passed to the last StateProver / StateProverCopy</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> to verify a storage slot given a target state commitment.</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> RemoteReadArgs</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span> route</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span> scpInputs</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Reads a broadcast message from a remote chain.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> broadcasterReadArgs</span><span class="z-comment"> A RemoteReadArgs object:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - The route points to the broadcasting chain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - The account proof is for the broadcaster&#39;s account</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - The proof is for the message storage slot (MAY accept proofs of other transmission mechanisms (e.g., child-to-parent native bridges) if the broadcaster contract uses other transmission mechanisms)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> message</span><span class="z-comment"> The message to read.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> publisher</span><span class="z-comment"> The address of the publisher who broadcast the message.</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"> broadcasterId</span><span class="z-comment"> The broadcaster&#39;s unique identifier.</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"> timestamp</span><span class="z-comment"> The timestamp when the message was broadcast.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyBroadcastMessage</span><span>(</span><span class="z-storage z-type">RemoteReadArgs</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> broadcasterReadArgs</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> message</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> publisher</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">bytes32</span><span class="z-variable"> broadcasterId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> timestamp</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"> Updates the state commitment prover copy in storage.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Checks that StateProverCopy has the same code hash as stored in the StateProverPointer</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Checks that the version is increasing.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> scpPointerReadArgs</span><span class="z-comment"> A RemoteReadArgs object:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - The route points to the StateProverPointer&#39;s home chain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - The account proof is for the StateProverPointer&#39;s account</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - The proof is for the STATE_PROVER_POINTER_SLOT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> scpCopy</span><span class="z-comment"> The StateProver copy on the local chain.</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"> scpPointerId</span><span class="z-comment"> The ID of the StateProverPointer</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateStateProverCopy</span><span>(</span><span class="z-storage z-type">RemoteReadArgs</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> scpPointerReadArgs</span><span>,</span><span class="z-storage z-type"> IStateProver</span><span class="z-variable"> scpCopy</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">bytes32</span><span class="z-variable"> scpPointerId</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 StateProverCopy on the local chain corresponding to the scpPointerId</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST return 0 if the StateProverPointer does not exist.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> stateProverCopy</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> scpPointerId</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">IStateProver</span><span class="z-variable"> scpCopy</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="broadcast-vs-unicast">Broadcast vs Unicast</h3> <p>A contract on any given chain cannot dictate which other chains can and cannot inspect its state. Contracts are naturally broadcasting their state to anything capable of reading it. Targeted messaging applications can always be built on top of a broadcast messaging system.</p> <p>See <a href="https://wg-eips.ritovision.com/7888/#reference-implementation">Reference Implementation</a> for an example of a unicast application.</p> <h3 id="using-storage-proofs">Using Storage Proofs</h3> <p>Message reading SHOULD use storage proofs to read messages from storage slots. However, an alternative method to this would be to pass messages (perhaps batched) via the canonical bridges of the chains. However storage proofs have some advantages over this method:</p> <ul> <li>They only require gas tokens on the chains where the message is sent and received, none on the chains on the route in between.</li> <li>Batching by default. Since storage slots share a common state root, caching the state root allows readers to open adjacent slots at lower cost. This provides a form of implicit batching, whereas canonical bridges would need to create a form of explicit batching.</li> <li>If the common ancestor of the two chains is Ethereum, sending a message using the canonical bridges would require sending a transaction on Ethereum, which would likely incur a high cost.</li> </ul> <h3 id="no-duplicate-messages-per-publisher">No duplicate messages per publisher</h3> <p>To allow publishers to send the same message multiple times, some kind of nonce system would need to exist in this ERC. Since nonces can be implemented at the Publisher / Subscriber layer, and not all Publishers / Subscribers require this feature, it is left out of this ERC.</p> <h4 id="cost-comparison">Cost Comparison</h4> <p>Here we compare the cost of using storage proofs vs sending messages via the canonical bridge, where the parent chain is Ethereum. Here, we will only consider the cost of the L1 gas as we assume it to dominate the L2 gas costs.</p> <p>Each step along the route requires 1 storage proof. These proofs can be estimated at roughly 6.5k bytes. These proofs will likely be submitted on an L2/L3 and therefore be included in blobs on the L1, which have a fluctuating blob gas price. Since rollups can dynamically switch between calldata and blobs, we can work out a maximum amount of normal L1 gas that could be using the standard cost of calldata as an upper bound. Post Pectra, the upper bound for non-zero-byte calldata is 40 gas per byte, which for 6.5k bytes equates to 260,000 L1 gas.</p> <p>We want to compare this to sending a single message via a canonical rollup bridge, which is either a parent-&gt;child or child-&gt;parent message. This estimate is dependent on specific implementations of the bridge for different rollup frameworks, but we estimate it to be around 150,000 gas.</p> <p>This puts the upper bound of the storage proof to be around 2x that of the canonical bridge, but in practice this upper bound is rarely reached. On top of that, the Receiver can implement a caching policy allowing many messages to share the same storage proofs.</p> <h3 id="caching">Caching</h3> <p>This ERC does not currently describe how the Receiver can cache the results of storage proofs to improve efficiency. In brief, once a storage proof is executed it never needs to be executed again, and instead the result can be stored by the Receiver. This allows messages that share the same, or partially the same, route to share previously executed proofs and instead lookup the result. As an example we can consider the route between two L2s using storage proofs:</p> <ol> <li>Ethereum block hash is looked up directly on L2' by the Receiver on L2'</li> <li>The block hash of L2'' is proven using a storage proof</li> <li>The account root of the Broadcaster on L2'' is proven using a storage proof</li> <li>The slot value in the Broadcaster account is proven using a storage proof The result of everything up to step 4 in this process can be stored in a Receiver cache and re-used by any unread messages in the Broadcaster. The Receiver can even go further and cache individual nodes in the account trie to make step 4. cheaper for previous messages.</li> </ol> <h3 id="using-routes-in-identifiers">Using Routes in Identifiers</h3> <p>Chains are often identified by chain ID's. Chain ID's are set by the chain owner so they are not guaranteed to be unique. Using the addresses of the Pointers is guaranteed to be unique as it provides a way to unwrap the nested state commitments embedded in the state roots. A storage slot on a remote chain can be identified by many different remote account ID's, but one remote account ID cannot identify more than one storage slot.</p> <h3 id="stateprovers-pointers-and-copies">StateProvers, Pointers, and Copies</h3> <h4 id="stateprovers-1">StateProvers</h4> <p>Each rollup implements unique logic for managing and storing state commitments. To accommodate this diversity, StateProvers implement chain-specific procedures. This flexibility allows integration with each rollup's distinct architecture and state commitment scheme.</p> <p>The StateProver handles the final step of verifying a storage slot given a target state commitment to accommodate rollups with differing state commitment schemes and formats.</p> <h4 id="stateproverpointers-1">StateProverPointers</h4> <p>Routes reference StateProvers through Pointers rather than directly. This indirection is crucial because:</p> <ul> <li>Chain upgrades may require StateProver redeployments</li> <li>Routes must remain stable and valid across these upgrades - ensuring in-flight messages are not broken</li> <li>Pointers maintain route consistency while allowing StateProver implementations to evolve</li> </ul> <h4 id="stateprovercopies-1">StateProverCopies</h4> <p>Since StateProverPointers reference StateProvers via their code hash, a copy of the StateProver can be deployed anywhere and reliably understood to contain the same code as that referenced by the Pointer. This allows the Receiver to locally use the code of a StateProver whose home chain is a remote chain.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The following is an example of a one-way crosschain token migrator. The burn side of the migrator is a publisher which sends burn messages through a Broadcaster. The mint side subscribes to these burn messages through a Receiver on another chain.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Message format for the burn and mint migrator.</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> BurnMessage</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> mintTo</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 class="z-support"> uint256</span><span> nonce</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"> @notice</span><span class="z-comment"> The burn side of an example one-way cross chain token migrator.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This contract is considered a &quot;publisher&quot;</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Burner</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"> The token to burn.</span></span> <span class="giallo-l"><span> IERC20 </span><span class="z-storage z-type">public</span><span class="z-storage z-type"> immutable</span><span> burnToken</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"> The broadcaster to publish messages through.</span></span> <span class="giallo-l"><span> IBroadcaster </span><span class="z-storage z-type">public</span><span class="z-storage z-type"> immutable</span><span> broadcaster</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"> An incrementing nonce, so each burn is a unique message.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> public</span><span> burnCount</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 emitted when tokens are burned.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Publishers SHOULD emit enough information to reconstruct the message.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Burn</span><span>(</span><span class="z-variable">BurnMessage</span><span class="z-variable"> messageData</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">IERC20</span><span class="z-variable z-parameter z-function"> _burnToken</span><span>,</span><span class="z-storage z-type"> IBroadcaster</span><span class="z-variable z-parameter z-function"> _broadcaster</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> burnToken </span><span class="z-keyword">=</span><span> _burnToken</span><span>;</span></span> <span class="giallo-l"><span> broadcaster </span><span class="z-keyword">=</span><span> _broadcaster</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"> @notice</span><span class="z-comment"> Burn the tokens and broadcast the event.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The corresponding token minter will subscribe to the message on another chain and mint the tokens.</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 class="z-support">address</span><span class="z-variable"> mintTo</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 class="z-comment"> //</span><span class="z-comment"> first, pull in the tokens and burn them</span></span> <span class="giallo-l"><span> burnToken</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> burnToken</span><span>.</span><span class="z-entity z-name">burn</span><span>(</span><span>amount</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> next, build a unique message</span></span> <span class="giallo-l"><span> BurnMessage </span><span class="z-storage z-type">memory</span><span> messageData </span><span class="z-keyword">=</span><span class="z-entity z-name"> BurnMessage</span><span>(</span><span>{</span><span>mintTo</span><span class="z-keyword">:</span><span> mintTo</span><span>,</span><span> amount</span><span class="z-keyword">:</span><span> amount</span><span>,</span><span> nonce</span><span class="z-keyword">:</span><span> burnCount</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>}</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>messageData</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"> finally, broadcast the message</span></span> <span class="giallo-l"><span> broadcaster</span><span>.</span><span class="z-entity z-name">broadcastMessage</span><span>(</span><span>message</span><span>)</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"> Burn</span><span>(</span><span>messageData</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-storage z-type"> @notice</span><span class="z-comment"> The mint side of an example one-way cross chain token migrator.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> This contract must be given minting permissions on its token.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This contract is considered a &quot;subscriber&quot;</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Minter</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"> Address of the Burner contract on the other chain.</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> immutable</span><span> burner</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"> The BroadcasterID corresponding to the broadcaster on the other chain that the Burner uses.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The Minter will only accept messages published by the Burner through this Broadcaster.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> immutable</span><span> broadcasterId</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"> The receiver to listen for messages through.</span></span> <span class="giallo-l"><span> IReceiver </span><span class="z-storage z-type">public</span><span class="z-storage z-type"> immutable</span><span> receiver</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 mapping to keep track of which messages have been processed.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Subscribers SHOULD keep track of processed messages because the Receiver does not.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The Broadcaster ensures messages are unique, so true duplicates are not possible.</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"> bool</span><span>)</span><span class="z-storage z-type"> public</span><span> processedMessages</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"> The token to mint.</span></span> <span class="giallo-l"><span> IERC20 </span><span class="z-storage z-type">public</span><span class="z-storage z-type"> immutable</span><span> mintToken</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"> _burner</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _broadcasterId</span><span>,</span><span class="z-storage z-type"> IReceiver</span><span class="z-variable z-parameter z-function"> _receiver</span><span>,</span><span class="z-storage z-type"> IERC20</span><span class="z-variable z-parameter z-function"> _mintToken</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> burner </span><span class="z-keyword">=</span><span> _burner</span><span>;</span></span> <span class="giallo-l"><span> broadcasterId </span><span class="z-keyword">=</span><span> _broadcasterId</span><span>;</span></span> <span class="giallo-l"><span> receiver </span><span class="z-keyword">=</span><span> _receiver</span><span>;</span></span> <span class="giallo-l"><span> mintToken </span><span class="z-keyword">=</span><span> _mintToken</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"> @notice</span><span class="z-comment"> Mint the tokens when a message is received.</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 class="z-storage z-type">IReceiver</span><span>.</span><span class="z-support z-variable">RemoteReadArgs</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> broadcasterReadArgs</span><span>,</span><span class="z-storage z-type"> BurnMessage</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> messageData</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> calculate the message from the data</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>messageData</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"> ensure the message has not been processed</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-keyword">!</span><span>processedMessages</span><span>[</span><span>message</span><span>]</span><span>,</span><span class="z-string"> &quot;Minter: Message already processed&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"> verify the broadcast message</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bytes32</span><span> actualBroadcasterId</span><span>,</span><span>)</span><span class="z-keyword"> =</span><span> receiver</span><span>.</span><span class="z-entity z-name">verifyBroadcastMessage</span><span>(</span><span>broadcasterReadArgs</span><span>,</span><span> message</span><span>,</span><span> burner</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ensure the message is from the expected broadcaster</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>actualBroadcasterId </span><span class="z-keyword">==</span><span> broadcasterId</span><span>,</span><span class="z-string"> &quot;Minter: Invalid broadcaster 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"> mark the message as processed</span></span> <span class="giallo-l"><span> processedMessages</span><span>[</span><span>message</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"> mint tokens to the recipient</span></span> <span class="giallo-l"><span> mintToken</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span><span>messageData</span><span>.</span><span>mintTo</span><span>,</span><span> messageData</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></code></pre><h2 id="security-considerations">Security Considerations</h2> <h3 id="chain-upgrades">Chain Upgrades</h3> <p>If a chain upgrades such that a StateProver's <code>verifyTargetState</code> or <code>getTargetState</code> functions might return data besides a finalized target state commitment, then invalid messages could be read by a <code>Receiver</code>. For instance, if a chain stores its state commitments on the parent chain in a specific mapping, and that storage slot is later repurposed, then an old StateProver might be able to pass along an invalid state commitment. It is therefore important that either:</p> <ul> <li>the StateProver is written in such a way to detect changes like this</li> <li>the owner who is able to repurpose these storage slots is aware of the StateProver and ensures they don't break it</li> </ul> <h3 id="stateproverpointer-ownership-updates">StateProverPointer Ownership / Updates</h3> <p>A malicious StateProverPointer owner can DoS or forge messages. However, so can the chain owner responsible for setting the slot of historical parent/child state commitments. Therefore it is expected that this chain owner be the same as the owner of the StateProverPointer so as not to introduce additional risks.</p> <ul> <li>If the target chain of the referenced StateProver is the parent chain, the home chain owner is expected to be the StateProverPointer's owner.</li> <li>If the target chain of the referenced StateProver is the child chain, the target chain owner is expected to be the StateProverPointer's owner.</li> </ul> <p>If an owner neglects their responsibility to update the Pointer with new StateProver implementations when necessary, messages could fail to reach their destinations.</p> <p>If an owner maliciously updates a Pointer to point to a StateProver that produces fraudulent results, messages can be forged.</p> <p>If there is confidence that a chain along the route connecting them will not upgrade to break a StateProver, an unowned StateProverPointer can be deployed in the absence of a properly owned one.</p> <h3 id="message-guarantees">Message guarantees</h3> <p>This ERC describes a protocol for ensuring that messages from remote chains CAN be read, but not that they WILL be read. It is the responsibility of the Receiver caller to choose which messages they wish to read.</p> <p>Since the ERC only uses finalized blocks, messages may take a long time to propagate between chains. Finalisation occurs sequentially in the route, therefore time to read a message is the sum of the finalisation of each of the state commitments at each step in the route.</p> <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:48:25+00:00 Wilson Cusackhttps://github.com/wilsoncusack Jake Feldmanhttps://github.com/jakefeldman Montana Wonghttps://github.com/montycheese Felix Zhanghttps://github.com/fan-zhang-sv Jake Moxeyhttps://github.com/jxom https://wg-eips.ritovision.com/7895/

Adds JSON-RPC method for requesting that a universal wallet create or track another account that it owns

<h2 id="abstract">Abstract</h2> <p>This ERC introduces a new wallet RPC, <code>wallet_addSubAccount</code>, which allows an app to request a wallet track a smart account that the wallet owns. It also allows apps to request the wallet to provision a new account, owned by the universal wallet with a signer provided by the caller.</p> <h2 id="motivation">Motivation</h2> <p>Embedded app accounts (onchain accounts specific to a single app) have led to a proliferation of user addresses, which can be difficult for users to keep track of. Many embedded app account users also have a universal wallet, which can be used across apps. With hierarchical ownership–where one smart account can own another–if the embedded app account is a smart account, it could be owned by the user’s universal wallet. This would allow users to be able to control an app account via their universal wallet. However, though hierarchical ownership is already possible today, there is no way for apps to tell universal wallets about embedded app accounts a user may have. The proposed RPC provides a path for this.</p> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions</h3> <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>Account - In this document, “account” means smart account. A smart contract that users transact from. Sub Account - An account that SHOULD have the main account as an owner of the sub-account. For instance, Account B is a sub-account of Account A if Account A is an owner, i.e. is a signer for Account B.</p> <h3 id="json-rpc-methods">JSON-RPC Methods</h3> <h4 id="wallet-addsubaccount"><code>wallet_addSubAccount</code></h4> <p>The <code>wallet_addSubAccount</code> RPC method allows applications to request that the connected account tracks the app account, creating a hierarchy between a universal account and app-embedded accounts. This RPC supports three different use cases.</p> <h5 id="request">Request</h5> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Previously deployed account, i.e. wallet &quot;imports&quot; account </span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> DeployedAccount</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">deployed</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-comment"> //</span><span class="z-comment"> Required: address of the account</span></span> <span class="giallo-l"><span class="z-variable"> address</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> <span class="giallo-l"><span class="z-variable"> keys</span><span class="z-keyword">:</span><span class="z-support"> never</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> chainId</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x{string}</span><span class="z-punctuation z-definition z-string">&#39;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> factory</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> never</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> factoryData</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> never</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"> Requester is agnostic to account type and only wants to ensure its signer is an owner</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> CreateAccount</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">create</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> keys</span><span class="z-keyword">:</span><span> {</span><span> </span></span> <span class="giallo-l"><span class="z-variable"> publicKey</span><span class="z-keyword">:</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></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</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 class="z-keyword"> |</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">p256</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">webcrypto-p256</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">webauthn-p256</span><span class="z-punctuation z-definition z-string">&quot;</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-punctuation z-definition z-comment">//</span><span class="z-comment"> Undeployed account, app creates the account</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> UndeployedAccount</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">undeployed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> address</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> <span class="giallo-l"><span class="z-variable"> keys</span><span class="z-keyword">:</span><span class="z-support"> never</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> chainId</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x{string}</span><span class="z-punctuation z-definition z-string">&#39;</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> in Hex</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Required: factory address to create the account</span></span> <span class="giallo-l"><span class="z-variable"> factory</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Required: factory calldata for the account</span></span> <span class="giallo-l"><span class="z-variable"> factoryData</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> <span class="giallo-l"><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"> Request</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> method</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">wallet_addSubAccount</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> params</span><span class="z-keyword">:</span><span> [</span><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> JSON-RPC method version</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> JSON-RPC method account </span></span> <span class="giallo-l"><span class="z-variable"> account</span><span class="z-keyword">:</span><span class="z-entity z-name"> CreateAccount</span><span class="z-keyword"> |</span><span class="z-entity z-name"> DeployedAccount</span><span class="z-keyword"> |</span><span class="z-entity z-name"> UndeployedAccount</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>]</span><span>,</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="response">Response</h5> <p>Factory data and factory address are OPTIONAL and SHOULD be returned when available. Deployed accounts MAY not have these fields.</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"> Response</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address of the account.</span></span> <span class="giallo-l"><span class="z-variable"> address</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Optional: factory address</span></span> <span class="giallo-l"><span class="z-variable"> factory</span><span class="z-keyword">?</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Optional: factory calldata</span></span> <span class="giallo-l"><span class="z-variable"> factoryData</span><span class="z-keyword">?</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> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="createaccount"><code>CreateAccount</code></h5> <p>Creates a new Sub Account. By default, if no signing keys (<code>keys</code>) are provided, the Sub Account's signing key MUST be created &amp; managed by the wallet. However, an application MAY optionally provide a set of signing keys (<code>keys</code>) for the Sub Account. A wallet SHOULD make the universal account an owner of the account, creating a hierarchical relationship between the newly created account and the universal account.</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"> Parameters</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-keyword">:</span><span class="z-support"> never</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Optional: keys of the account to be created</span></span> <span class="giallo-l"><span class="z-variable"> keys</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span> {</span><span> </span></span> <span class="giallo-l"><span class="z-variable"> publicKey</span><span class="z-keyword">:</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></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</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 class="z-keyword"> |</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">p256</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">webcrypto-p256</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">webauthn-p256</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>[</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> factory</span><span class="z-keyword">:</span><span class="z-support"> never</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> factoryData</span><span class="z-keyword">:</span><span class="z-support"> never</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="undeployedaccount">UndeployedAccount</h5> <p>An undeployed account is an account that an application has created, but has not yet deployed.. The wallet can decide whether or not it is appropriate to deploy it. Wallets SHOULD validate that the universal account is an owner. Either through decoding the factoryData or simulating the deployment that there is a hierarchy between the universal account and newly created account.</p> <p>Example: the application creates an account and generates the counterfactual address for the user to airdrop funds to. Once there is an account relationship with the universal account, the user wishes to perform a transaction, in which the wallet will deploy the account in order to execute the respective transaction.</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"> Parameters</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Required: address of the account</span></span> <span class="giallo-l"><span class="z-variable"> address</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> <span class="giallo-l"><span class="z-variable"> keys</span><span class="z-keyword">:</span><span class="z-support"> never</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> factory</span><span class="z-keyword">:</span><span class="z-support"> never</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> factoryData</span><span class="z-keyword">:</span><span class="z-support"> never</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="deployedaccount"><code>DeployedAccount</code></h5> <p>An existing account could be any smart that an app or user wants to track via their universal wallet.</p> <p>Example: The user wants to define a hierarchical relationship between an existing app account and their universal wallet.</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Previously deployed account &quot;import&quot; </span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> Parameters</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Required: address of the account</span></span> <span class="giallo-l"><span class="z-variable"> address</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> <span class="giallo-l"><span class="z-variable"> keys</span><span class="z-keyword">:</span><span class="z-support"> never</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> factory</span><span class="z-keyword">:</span><span class="z-support"> never</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> factoryData</span><span class="z-keyword">:</span><span class="z-support"> never</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="external-rpc-capabilities">External RPC Capabilities</h3> <h4 id="wallet-connect"><code>wallet_connect</code></h4> <p>This ERC conforms to <!-- TODO: [ERC-7846](./07846.md) --> which includes <a href="https://wg-eips.ritovision.com/5792/">ERC-5792</a> capabilities specification and introduces two new capabilities for <code>wallet_connect</code>.</p> <h5 id="addsubaccount"><code>addSubAccount</code></h5> <p>Adds a sub-account to the universal account.</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"> Request</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> addSubAccount</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> account</span><span class="z-keyword">:</span><span class="z-entity z-name"> CreateAccount</span><span class="z-keyword"> |</span><span class="z-entity z-name"> DeployedAccount</span><span class="z-keyword"> |</span><span class="z-entity z-name"> UndeployedAccount</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="subaccounts"><code>subAccounts</code></h5> <p>Fetches all sub-accounts of the universal account (including any added ones).</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"> Response</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> subAccounts</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> address</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> <span class="giallo-l"><span class="z-variable"> factory</span><span class="z-keyword">?</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> <span class="giallo-l"><span class="z-variable"> factoryData</span><span class="z-keyword">?</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> <span class="giallo-l"><span> }</span><span>[</span><span>]</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="wallet-getcapabilities"><code>wallet_getCapabilities</code></h4> <p>This ERC conforms with <code>wallet_getCapabilities</code> <a href="https://wg-eips.ritovision.com/5792/">ERC-5792</a>. The response will accommodate addSubAccount support for wallets that support it.</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"> Response</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> addSubAccount</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> supported</span><span class="z-keyword">:</span><span class="z-support"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> keyTypes</span><span class="z-keyword">:</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 class="z-keyword"> |</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">p256</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">webcrypto-p256</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">webauthn-p256</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> }</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-punctuation z-definition z-comment">//</span><span class="z-comment"> Example </span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> response</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">0x2105</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">addSubAccount</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">supported</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">keyTypes</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">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">webauthn-p256</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>;</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-string"> &quot;</span><span class="z-string">0x14A34</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">addSubAccount</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">supported</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">keyTypes</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">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">webauthn-p256</span><span class="z-punctuation z-definition z-string">&quot;</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></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="naming">Naming</h3> <p>Initial intent was to leverage existing RPCs, like <code>wallet_connect</code> (e.g. <!-- TODO: [ERC-7846](./07846.md) --> with additional capabilities to add support for these new features, but these methods ultimately lacked flexibility. Then there were custom namespaced RPCs but this resulted with more fragmentation within the community.</p> <p>Method names explored <code>wallet_linkAccount</code>, <code>wallet_importAddress</code>, <code>wallet_addAddress</code>, or something else. Multiple RPCs were explored as well, separating create and tracking as two separate RPCs. To consolidate on a single RPC <code>wallet_addSubAccount</code> was selected. This method is more inclusive for EOA use cases.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard builds on existing JSON-RPC methods and complements <a href="https://wg-eips.ritovision.com/5792/">ERC-5792</a> for future extensibility. Wallets can continue supporting legacy methods.</p> <h2 id="security-considerations">Security Considerations</h2> <p>As more capabilities are added, care should be taken to avoid unpredictable interactions. App specific accounts pose more risk for assets in those accounts. Having a universal account that maintains access to these accounts gives additional security to users and their funds.</p> <h3 id="privacy-considerations">Privacy Considerations</h3> <p>Account data and any shared capabilities must be handled securely to avoid data leaks or man-in-the-middle 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> 2025-02-15T00:00:00+00:00 2026-02-11T14:48:26+00:00 Nitin Bhagathttps://github.com/nitin312bhagatnitin312@gmail.com JongWook Baebae@cwnu.ac.kr Su-Hyun Leesleepl@changwon.ac.kr https://wg-eips.ritovision.com/7891/

Interface for hierarchical NFTs, enabling splitting a single NFT and merging multiple NFTs

<h2 id="abstract">Abstract</h2> <p>This standard extends <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and <a href="https://wg-eips.ritovision.com/6150/">EIP-6150</a>. This introduces a structured parent-child relationship between NFTs, allowing an NFT to be fractionally split into multiple child NFTs and merged back into a single entity. It provides interfaces to retrieve an NFT's parent, children, and hierarchical status, ensuring flexible ownership management. This standard is particularly useful for applications in fractional ownership, asset distribution, and composable digital assets, opening new possibilities in fields like real estate, gaming, and decentralized finance.</p> <h2 id="motivation">Motivation</h2> <p>This EIP introduces hierarchical NFTs with splitting and merging capabilities, allowing assets to be dynamically restructured. This proposal is crucial for fractional ownership, gaming assets, and financial instruments, where assets need to be split or merged.</p> <ol> <li> <p><strong>Splitting</strong>: One of the key limitations of <a href="https://wg-eips.ritovision.com/6150/">EIP-6150</a> is its rigid hierarchy, where NFTs are permanently assigned to a parent without the ability to restructure ownership. In many real-world scenarios, assets need to be split into smaller, independent units. This EIP introduces a standardized way to split an NFT into multiple child NFTs, enabling dynamic asset management. For example, in financial markets, a share NFT can be split into multiple fractional share NFTs, allowing investors to own and trade smaller portions of a share.</p> </li> <li> <p><strong>Merging</strong>: Just as assets need to be split, there are scenarios where multiple NFTs should be combined into a single entity. The proposed EIP enables a merging mechanism, allowing child NFTs to be consolidated into a single parent NFT, allowing asset management and transactions. For instance, in finance, fractional share NFTs can be merged back into a full share NFT, enabling seamless ownership consolidation. This is particularly useful for investors who gradually accumulate fractions of a stock and later want to own a full share.</p> </li> <li> <p><strong>Share Distribution</strong>: This EIP introduces ownership share management, allowing NFTs to track and distribute fractional ownership among multiple stakeholders. This solves fractional ownership tracking within parent-child NFT structures. This also allows dynamic adjustments of ownership based on splitting and merging actions. For example, a real estate NFT representing a building can have multiple owners with different share percentages. When the NFT is split, the new NFTs retain a proportion of the original ownership share. When merged, the system redistributes the shares accordingly. This Enables multi-party ownership in digital assets.</p> </li> </ol> <h3 id="how-the-proposed-eip-improves-over-existing-standards">How the proposed EIP Improves Over Existing Standards</h3> <table><thead><tr><th>Feature</th><th><a href="https://wg-eips.ritovision.com/721/">EIP-721</a></th><th><a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a></th><th><a href="https://wg-eips.ritovision.com/6150/">EIP-6150</a></th><th>EIP (Proposed)</th></tr></thead><tbody> <tr><td>Unique NFTs</td><td>✅</td><td>❌</td><td>✅</td><td>✅</td></tr> <tr><td>Fungible &amp; Non-Fungible</td><td>❌</td><td>✅</td><td>❌</td><td>✅</td></tr> <tr><td>Hierarchical Structure</td><td>❌</td><td>❌</td><td>✅</td><td>✅</td></tr> <tr><td>Parent-Child Relationship</td><td>❌</td><td>❌</td><td>✅</td><td>✅</td></tr> <tr><td>NFT Splitting</td><td>❌</td><td>❌</td><td>❌</td><td>✅</td></tr> <tr><td>NFT Merging</td><td>❌</td><td>❌</td><td>❌</td><td>✅</td></tr> <tr><td>Fractional Ownership</td><td>❌</td><td>✅</td><td>❌</td><td>✅</td></tr> <tr><td>Ownership Redistribution</td><td>❌</td><td>❌</td><td>❌</td><td>✅</td></tr> </tbody></table> <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>Every compliant contract MUST implement this proposal, <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>, <a href="https://wg-eips.ritovision.com/165/">EIP-165</a>, and <a href="https://wg-eips.ritovision.com/6150/">ERC-6150</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.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 0x43cb816b.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7891</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC6150, IERC721, IERC165 </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"> Emitted when a child token is minted under a parent with an assigned share.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> parentId</span><span class="z-comment"> The ID of the parent 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"> childId</span><span class="z-comment"> The ID of the newly minted child 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"> share</span><span class="z-comment"> Share percentage assigned to the child 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"> Split</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> parentId</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> childId</span><span>, </span><span class="z-support">uint8</span><span class="z-variable"> share</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 multiple child tokens are merged into a new 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"> newTokenId</span><span class="z-comment"> The ID of the newly minted merged 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"> mergedTokenIds</span><span class="z-comment"> Array of token IDs that were merged</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"> Merged</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> newTokenId</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> mergedTokenIds</span><span>)</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"> Mints a new root-level parent 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"> _tokenURI</span><span class="z-comment"> URI string pointing to token metadata</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 ID of the newly minted parent 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"> mintParent</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"> external</span><span class="z-storage z-type"> payable</span><span class="z-keyword"> returns</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Mints a child NFT under a given parent with a specific share allocation.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> parentId</span><span class="z-comment"> ID of the parent 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"> _share</span><span class="z-comment"> Share percentage assigned to the child 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"> The ID of the newly minted child 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"> mintSplit</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parentId</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable z-parameter z-function"> _share</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">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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Merges multiple child NFTs into a new token under the same parent.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> parentId</span><span class="z-comment"> ID of the parent 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"> _tokenIds</span><span class="z-comment"> Array of child token IDs to be merged</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"> newTokenId</span><span class="z-comment"> The ID of the newly minted merged 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"> mintMerge</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parentId</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _tokenIds</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">uint256</span><span class="z-variable"> newTokenId</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 share ownership from one NFT to another.</span></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 ID receiving the share</span></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 ID sending the share</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _share</span><span class="z-comment"> Share percentage 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"> sharePass</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable z-parameter z-function"> _share</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"> Burns an NFT and transfers its share back to the parent 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 ID of the token to burn</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 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><h2 id="rationale">Rationale</h2> <p>This EIP builds upon <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/6150/">ERC-6150</a> to introduce a structured mechanism for share-based hierarchical NFTs, enabling splitting, merging, and fractional ownership directly within the token standard. The proposal reuses <a href="https://wg-eips.ritovision.com/6150/">ERC-6150</a>'s parent-child architecture to preserve compatibility and reduce implementation complexity. Share management is embedded natively through internal mappings, allowing each token to track its fractional ownership independently without relying on external protocols. Functions like <code>mintSplit</code> and <code>mintMerge</code> are designed to reflect real-world asset behaviors, clearly distinguishing between asset decomposition and consolidation. The <code>sharePass</code> function facilitates redistribution of shares between tokens without requiring minting or burning, offering an efficient internal transfer mechanism. A <code>burn</code> function is included to allow share return to the parent on destruction, aligning with ownership. Overall, the interface is purposefully minimal and intuitive, designed for extensibility while maintaining gas efficiency and semantic clarity.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The proposed EIP extends <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and <a href="https://wg-eips.ritovision.com/6150/">EIP-6150</a>, making it backward compatible.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Implementation: <a href=".././assets/ERC7891.sol">EIP-7891</a>.</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> 2025-02-11T00:00:00+00:00 2026-02-11T14:49:27+00:00 Marcin Sobczakhttps://github.com/marcindsobczak Marek Moraczyńskihttps://github.com/MarekM25 Marcos Maceohttps://github.com/stdevMac https://wg-eips.ritovision.com/7883/

Increases cost of ModExp precompile

<h2 id="abstract">Abstract</h2> <p>This EIP is modifying the <code>ModExp</code> precompile pricing algorithm introduced in <a href="https://wg-eips.ritovision.com/2565/">EIP-2565</a>.</p> <h2 id="motivation">Motivation</h2> <p>Currently the <code>ModExp</code> precompile is underpriced in certain scenarios relative to its resource consumption. By adjusting the pricing formula, this EIP aims to address these discrepancies, making <code>ModExp</code> sufficiently efficient to enable potential increases in the block gas limit.</p> <h2 id="specification">Specification</h2> <p>Upon activation of this EIP, the gas cost of calling the precompile at address <code>0x0000000000000000000000000000000000000005</code> will be calculated as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def calculate_multiplication_complexity(base_length, modulus_length):</span></span> <span class="giallo-l"><span> max_length = max(base_length, modulus_length)</span></span> <span class="giallo-l"><span> words = math.ceil(max_length / 8)</span></span> <span class="giallo-l"><span> multiplication_complexity = 16</span></span> <span class="giallo-l"><span> if max_length &gt; 32: multiplication_complexity = 2 * words**2</span></span> <span class="giallo-l"><span> return multiplication_complexity</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def calculate_iteration_count(exponent_length, exponent):</span></span> <span class="giallo-l"><span> iteration_count = 0</span></span> <span class="giallo-l"><span> if exponent_length &lt;= 32 and exponent == 0: iteration_count = 0</span></span> <span class="giallo-l"><span> elif exponent_length &lt;= 32: iteration_count = exponent.bit_length() - 1</span></span> <span class="giallo-l"><span> elif exponent_length &gt; 32: iteration_count = (16 * (exponent_length - 32)) + ((exponent &amp; (2**256 - 1)).bit_length() - 1)</span></span> <span class="giallo-l"><span> return max(iteration_count, 1)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def calculate_gas_cost(base_length, modulus_length, exponent_length, exponent):</span></span> <span class="giallo-l"><span> multiplication_complexity = calculate_multiplication_complexity(base_length, modulus_length)</span></span> <span class="giallo-l"><span> iteration_count = calculate_iteration_count(exponent_length, exponent)</span></span> <span class="giallo-l"><span> return max(500, math.floor(multiplication_complexity * iteration_count))</span></span></code></pre> <p>The specific changes from the algorithm defined in <a href="https://wg-eips.ritovision.com/2565/">EIP-2565</a>:</p> <h3 id="1-increased-minimal-and-general-price">1. Increased minimal and general price</h3> <p>The gas cost calculation is modified from:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> return max(200, math.floor(multiplication_complexity * iteration_count / 3))</span></span></code></pre> <p>to:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> return max(500, math.floor(multiplication_complexity * iteration_count))</span></span></code></pre> <p>This change increases the minimum gas cost from 200 to 500 and triples the general cost by removing the division by 3.</p> <h3 id="2-increase-cost-for-exponents-larger-than-32-bytes">2. Increase cost for exponents larger than 32 bytes</h3> <p>The gas cost calculation is modified from:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> elif exponent_length &gt; 32: iteration_count = (8 * (exponent_length - 32)) + ((exponent &amp; (2**256 - 1)).bit_length() - 1)</span></span></code></pre> <p>to:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> elif exponent_length &gt; 32: iteration_count = (16 * (exponent_length - 32)) + ((exponent &amp; (2**256 - 1)).bit_length() - 1)</span></span></code></pre> <p>The multiplier for exponents larger than 32 bytes is increased from 8 to 16, doubling its impact.</p> <h3 id="3-assume-the-minimal-base-modulus-length-to-be-32-and-increase-the-cost-when-it-is-larger-than-32-bytes">3. Assume the minimal base / modulus length to be 32 and increase the cost when it is larger than 32 bytes</h3> <p>The gas cost calculation is modified from:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def calculate_multiplication_complexity(base_length, modulus_length):</span></span> <span class="giallo-l"><span> max_length = max(base_length, modulus_length)</span></span> <span class="giallo-l"><span> words = math.ceil(max_length / 8)</span></span> <span class="giallo-l"><span> return words**2</span></span></code></pre> <p>to:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def calculate_multiplication_complexity(base_length, modulus_length):</span></span> <span class="giallo-l"><span> max_length = max(base_length, modulus_length)</span></span> <span class="giallo-l"><span> words = math.ceil(max_length / 8)</span></span> <span class="giallo-l"><span> multiplication_complexity = 16</span></span> <span class="giallo-l"><span> if max_length &gt; 32: multiplication_complexity = 2 * words**2</span></span> <span class="giallo-l"><span> return multiplication_complexity</span></span></code></pre> <p>This change introduces a minimal multiplication complexity of 16 and doubles the complexity if the base or modulus length exceeds 32 bytes.</p> <h2 id="rationale">Rationale</h2> <p>Benchmarking the <code>ModExp</code> precompile revealed several scenarios where its gas cost was significantly underestimated. Pricing adjustments are designed to rectify underpriced edge cases by modifying the existing <code>ModExp</code> pricing formula parameters. Specifically, the minimum cost for <code>ModExp</code> will rise from 200 to 500 (a 150% increase), the general cost will triple (a 200% increase), a minimum base/modulus length of 32 bytes will be assumed and the cost will scale more aggressively when the base, modulus, or exponent exceed 32 bytes. These modifications aim to ensure that the <code>ModExp</code> precompile's performance, even in its most resource-intensive edge cases across all execution layer clients, no longer impedes potential increases to the block gas limit.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces a backwards-incompatible change. However, similar gas repricings have occurred multiple times in the Ethereum ecosystem, and their effects are well understood.</p> <p>An empirical analysis of this proposal is available <a href="https://wg-eips.ritovision.com/7883/assets/call_analysis/">here</a>, with a separate breakdown by affected entities provided <a href="https://wg-eips.ritovision.com/7883/assets/entity_analysis/">here</a>.</p> <h2 id="test-cases">Test Cases</h2> <p>The most common usages (approximately 99.69% of historical <code>Modexp</code> calls as of January 4th, 2025) will experience either a 150% increase (from 200 to 500 gas) or a 200% increase (tripling from approximately 1360 gas). No changes are made to the underlying interface or arithmetic algorithms, allowing existing test vectors to be reused. The table below presents the updated gas costs for these test vectors:</p> <table><thead><tr><th>Test Case</th><th><a href="https://wg-eips.ritovision.com/2565/">EIP-2565</a> Pricing</th><th>EIP-7883 Pricing</th><th>Increase</th></tr></thead><tbody> <tr><td>modexp_nagydani_1_square</td><td>200</td><td>500</td><td>150%</td></tr> <tr><td>modexp_nagydani_1_qube</td><td>200</td><td>500</td><td>150%</td></tr> <tr><td>modexp_nagydani_1_pow0x10001</td><td>341</td><td>2048</td><td>501%</td></tr> <tr><td>modexp_nagydani_2_square</td><td>200</td><td>512</td><td>156%</td></tr> <tr><td>modexp_nagydani_2_qube</td><td>200</td><td>512</td><td>156%</td></tr> <tr><td>modexp_nagydani_2_pow0x10001</td><td>1365</td><td>8192</td><td>501%</td></tr> <tr><td>modexp_nagydani_3_square</td><td>341</td><td>2048</td><td>501%</td></tr> <tr><td>modexp_nagydani_3_qube</td><td>341</td><td>2048</td><td>501%</td></tr> <tr><td>modexp_nagydani_3_pow0x10001</td><td>5461</td><td>32768</td><td>500%</td></tr> <tr><td>modexp_nagydani_4_square</td><td>1365</td><td>8192</td><td>501%</td></tr> <tr><td>modexp_nagydani_4_qube</td><td>1365</td><td>8192</td><td>501%</td></tr> <tr><td>modexp_nagydani_4_pow0x10001</td><td>21845</td><td>131072</td><td>500%</td></tr> <tr><td>modexp_nagydani_5_square</td><td>5461</td><td>32768</td><td>500%</td></tr> <tr><td>modexp_nagydani_5_qube</td><td>5461</td><td>32768</td><td>500%</td></tr> <tr><td>modexp_nagydani_5_pow0x10001</td><td>87381</td><td>524288</td><td>500%</td></tr> <tr><td>modexp_marius_1_even</td><td>2057</td><td>45296</td><td>2102%</td></tr> <tr><td>modexp_guido_1_even</td><td>2298</td><td>51136</td><td>2125%</td></tr> <tr><td>modexp_guido_2_even</td><td>2300</td><td>51152</td><td>2124%</td></tr> <tr><td>modexp_guido_3_even</td><td>5400</td><td>32400</td><td>500%</td></tr> <tr><td>modexp_guido_4_even</td><td>1026</td><td>94448</td><td>9105%</td></tr> <tr><td>modexp_marcin_1_base_heavy</td><td>200</td><td>1152</td><td>476%</td></tr> <tr><td>modexp_marcin_1_exp_heavy</td><td>215</td><td>16624</td><td>7632%</td></tr> <tr><td>modexp_marcin_1_balanced</td><td>200</td><td>1200</td><td>500%</td></tr> <tr><td>modexp_marcin_2_base_heavy</td><td>867</td><td>5202</td><td>500%</td></tr> <tr><td>modexp_marcin_2_exp_heavy</td><td>852</td><td>16368</td><td>1821%</td></tr> <tr><td>modexp_marcin_2_balanced</td><td>996</td><td>5978</td><td>500%</td></tr> <tr><td>modexp_marcin_3_base_heavy</td><td>677</td><td>2032</td><td>200%</td></tr> <tr><td>modexp_marcin_3_exp_heavy</td><td>765</td><td>4080</td><td>433%</td></tr> <tr><td>modexp_marcin_3_balanced</td><td>1360</td><td>4080</td><td>200%</td></tr> </tbody></table> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP does not introduce any new functionality or make existing operations cheaper, therefore there are no direct security concerns related to new attack vectors or reduced costs. The primary security consideration for this EIP is the potential for <code>ModExp</code> scenarios to be overpriced, though this is deemed a lesser risk compared to the current underpricing 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> 2025-02-08T00:00:00+00:00 2026-02-11T14:49:27+00:00 Danno Ferrinhttps://github.com/shemnon https://wg-eips.ritovision.com/7880/

Add EXTCODEADDRESS instruction to EOF to address code delegation use cases

<h2 id="abstract">Abstract</h2> <p>Add an instruction to EOF that reads code delegation designations from an account without requiring code introspection.</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, preventing EOF from reading raw code values such as code delegation designations set by <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>. There are a number of use cases where reading the delegation designation of <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> would allow contracts to be more proactive about user experience issues.</p> <p>One example is a managed proxy contract. Such a contract may want to ensure security by not allowing the proxy to be updated to a delegated address. There are also safety concerns with pointing to a delegation, as the contract may be updated to non EOF code and <code>EXTDELEGATECALL</code> will no longer be able to call the contract, due to changes outside the control of the managed proxy contract.</p> <p>Another example are contracts that need to ensure that the delegation has not changed over a limited scope of time, such as sponsorships. This will prevent a transaction from receiving gas sponsorship, changing the delegation, and performing an act different than what was approved. Sponsors can encode the delegation into the transaction data and verify with this instruction.</p> <p>Finally, there is the case where contracts may want to de-escalate risks and only accept a small number of delegations for any given contract. To enable this validation contracts will need to be able to resolve the actual address of delegation, not just know that one exists.</p> <p>To address this the essential task of the designation parsing is moved into a new opcode <code>EXTCODEADDRESS</code>, where the task of calculating the delegated address will be performed. For non-delegated accounts or empty accounts the address will be the same as the queried address.</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>GAS_COLD_ACCOUNT_ACCESS</code></td><td>Defined as <code>2600</code> in the <a rel="external" href="https://github.com/ethereum/execution-specs/blob/1adcc1bfe774798bcacc685aebc17bd9935078c3/src/ethereum/cancun/vm/gas.py#L65-L66">Ethereum Execution Layer Spec Constants</a></td></tr> <tr><td><code>GAS_WARM_ACCESS</code></td><td>Defined as <code>100</code> in the <a rel="external" href="https://github.com/ethereum/execution-specs/blob/1adcc1bfe774798bcacc685aebc17bd9935078c3/src/ethereum/cancun/vm/gas.py#L65-L66">Ethereum Execution Layer Spec Constants</a></td></tr> </tbody></table> <p>We introduce a new EOFv1 instruction <code>EXTCODEADDRESS</code> (<code>0xea</code>).</p> <p>EOF code which contains this instruction prior to the fork activating this instruction is considered invalid. Beginning with the first block this EIP is activated in, this instruction is added to the set of valid EOFv1 instructions.</p> <h3 id="execution-semantics">Execution Semantics</h3> <h4 id="extcodeaddress"><code>EXTCODEADDRESS</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 enlarge the number of valid addresses. Do not rely on this step always halting with the current restrictions.</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> indicates a delegation designator (for example, prefixed with <code>0xef0100</code> as defined in <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>) push the address of the designation onto the stack. <ul> <li>Notice: if <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> delegation designations are updated in a future fork (such as allowing chained delegations), then this section is expected to comply with any such hypothetical changes.</li> </ul> </li> <li>Otherwise, push <code>target_address</code> onto the stack.</li> </ul> <p>Note: If <code>target_address</code> points to an account with a contract mid-creation, then <code>target_address</code> is returned. If delegation designator points to an account with a contract mid-creation, then address of the designation is returned.</p> <p>Note: Only <code>target_address</code> is warmed. If a delegation is found the address that it is delegated to is not added to the <code>accessed_addresses</code>. Also, whether the delegated address is in <code>accessed_addresses</code> has no impact on the gas charged for the operation.</p> <p>Note: This operation straddles the line between <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> code reading and code executing instructions. The operation steps work as a code reading instruction, but the value returned is the resolved address as through it is a code executing instruction.</p> <h2 id="rationale">Rationale</h2> <p>This EIP is very similar to <a href="https://wg-eips.ritovision.com/7761/">EIP-7761</a>, which introduces account type introspection. Its rationale is included by reference as they all apply to this situation.</p> <h3 id="alternative-return-the-whole-designation-have-contract-parse">Alternative: Return the whole designation, have contract parse</h3> <p>One alternative is to have a specially limited <code>EXTCODECOPY</code> that would return just delegation designations. Apart from the general objections to code introspection this would then lock in and limit delegation designation formats and capabilities that must be preserved in future forks. By allowing access to the effect of the delegation rather than the mechanism, EOF preserves space for the mechanism to be changed without breaking existing code.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><code>EXTCODEADDRESS</code> at <code>0xea</code> can be introduced in a backwards compatible manner into EOFv1 (no bump to version), because <code>0xea</code> has been rejected by EOF validation prior to the activation of this EIP, and there are no EOF contracts on-chain with an <code>0xea</code> instruction which would have their behavior altered.</p> <h2 id="security-considerations">Security Considerations</h2> <p><a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> code delegation is a new feature that has not been made accessible to mainnet yet. EIP authors will keep abreast of any developments and reflect on their impact to this proposed instruction.</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-05T00:00:00+00:00 2026-02-11T14:49:27+00:00 Jacek Glenhttps://github.com/JacekGlen Lukasz Glenhttps://github.com/lukasz-glen Maria Silvahttps://github.com/misilva73 https://wg-eips.ritovision.com/7904/

Gas Cost Increase to reflect computational complexity and transaction throughput increase

<h2 id="abstract">Abstract</h2> <p>This proposal raises the gas costs of 13 compute operations and precompiles performing worse than 60 million gas per second (Mgas/s). By removing these operations as bottlenecks, we can further increase the block gas limit, thus allowing for a higher throughput on the remaining operations.</p> <h2 id="motivation">Motivation</h2> <p>Recent empirical measurements have shown that EVM operations don't have a price consistent with their computational complexity. Some operations are significantly underpriced, leading to potential bottlenecks in transaction processing. These bottlenecks limit the overall throughput of the Ethereum network, as they consume a disproportionate amount of computational resources relative to their gas cost.</p> <p>By increasing the gas costs of these underpriced operations, we can alleviate these bottlenecks. This change will enable a higher block gas limit, allowing more transactions to be processed per block. The result is an overall increase in network throughput, improving the efficiency and scalability of the Ethereum blockchain.</p> <h2 id="specification">Specification</h2> <p>Upon activation of this EIP, the following gas costs will be updated.</p> <h3 id="opcodes">Opcodes</h3> <table><thead><tr><th style="text-align: center">Operation</th><th style="text-align: center">Parameter</th><th style="text-align: center">Current Gas</th><th style="text-align: center">New Gas (Rounded)</th><th style="text-align: center">Change</th></tr></thead><tbody> <tr><td style="text-align: center">ADDMOD</td><td style="text-align: center">constant</td><td style="text-align: center">8</td><td style="text-align: center">8</td><td style="text-align: center">0.0</td></tr> <tr><td style="text-align: center">DIV</td><td style="text-align: center">constant</td><td style="text-align: center">5</td><td style="text-align: center">15</td><td style="text-align: center">2.0</td></tr> <tr><td style="text-align: center">KECCAK256</td><td style="text-align: center">constant</td><td style="text-align: center">30</td><td style="text-align: center">45</td><td style="text-align: center">0.5</td></tr> <tr><td style="text-align: center">KECCAK256</td><td style="text-align: center">msg_size</td><td style="text-align: center">6</td><td style="text-align: center">6</td><td style="text-align: center">0.0</td></tr> <tr><td style="text-align: center">MOD</td><td style="text-align: center">constant</td><td style="text-align: center">5</td><td style="text-align: center">12</td><td style="text-align: center">1.4</td></tr> <tr><td style="text-align: center">MULMOD</td><td style="text-align: center">constant</td><td style="text-align: center">8</td><td style="text-align: center">11</td><td style="text-align: center">0.38</td></tr> <tr><td style="text-align: center">SDIV</td><td style="text-align: center">constant</td><td style="text-align: center">5</td><td style="text-align: center">20</td><td style="text-align: center">3.0</td></tr> <tr><td style="text-align: center">SMOD</td><td style="text-align: center">constant</td><td style="text-align: center">5</td><td style="text-align: center">5</td><td style="text-align: center">0</td></tr> </tbody></table> <h3 id="precompiles">Precompiles</h3> <table><thead><tr><th style="text-align: center">Operation</th><th style="text-align: center">Parameter</th><th style="text-align: center">Current Gas</th><th style="text-align: center">New Gas (Rounded)</th><th style="text-align: center">Change</th></tr></thead><tbody> <tr><td style="text-align: center">BLAKE2F</td><td style="text-align: center">constant</td><td style="text-align: center">0</td><td style="text-align: center">170</td><td style="text-align: center">NA</td></tr> <tr><td style="text-align: center">BLAKE2F</td><td style="text-align: center">num_rounds</td><td style="text-align: center">1</td><td style="text-align: center">2</td><td style="text-align: center">1.0</td></tr> <tr><td style="text-align: center">BLS12_G1ADD</td><td style="text-align: center">constant</td><td style="text-align: center">375</td><td style="text-align: center">643</td><td style="text-align: center">0.71</td></tr> <tr><td style="text-align: center">BLS12_G2ADD</td><td style="text-align: center">constant</td><td style="text-align: center">600</td><td style="text-align: center">765</td><td style="text-align: center">0.27</td></tr> <tr><td style="text-align: center">ECADD</td><td style="text-align: center">constant</td><td style="text-align: center">150</td><td style="text-align: center">314</td><td style="text-align: center">1.09</td></tr> <tr><td style="text-align: center">ECPAIRING</td><td style="text-align: center">constant</td><td style="text-align: center">45000</td><td style="text-align: center">45000</td><td style="text-align: center">0.0</td></tr> <tr><td style="text-align: center">ECPAIRING</td><td style="text-align: center">num_pairs</td><td style="text-align: center">34000</td><td style="text-align: center">34103</td><td style="text-align: center">0.0</td></tr> <tr><td style="text-align: center">ECRECOVER</td><td style="text-align: center">constant</td><td style="text-align: center">3000</td><td style="text-align: center">3000</td><td style="text-align: center">0</td></tr> <tr><td style="text-align: center">POINT_EVALUATION</td><td style="text-align: center">constant</td><td style="text-align: center">50000</td><td style="text-align: center">89363</td><td style="text-align: center">0.79</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <h3 id="empirical-estimation-of-gas-costs">Empirical Estimation of Gas Costs</h3> <h4 id="selecting-which-operations-to-reprice">Selecting which Operations to Reprice</h4> <p>The operations selected for repricing in this EIP were chosen based on their estimated million gas per second (Mgas/s) performance. For this EIP, a performance target of <strong>60 million gas per second</strong> is chosen. With this performance target, we will be able to increase the base throughput of the chain by 3x from our current 20Mgas/s performance.</p> <p>An important consideration for repricing is whether poor performance is isolated to a single client or affects multiple implementations. This is important for distinguishing between:</p> <ul> <li>Operations that genuinely need repricing (multiple clients struggle)</li> <li>Operations where a specific client needs optimization (only one client struggles)</li> </ul> <p>To separate these cases, we analyze the performance of each operation the 5 main clients (besu, erigon, geth, nethermind and reth). If the difference in performance between the worst and the second-worst client is higher than 20%, we consider the operation to be a candidate for optimization rather than repricing. All the remaining operations are candidates for repricing.</p> <p>The report with the full details of this step can be accessed <a href="https://wg-eips.ritovision.com/7904/assets/included_operations/">here</a>.</p> <h4 id="data-collection">Data Collection</h4> <p>The gas costs proposed in this EIP are based on the actual time each operation takes to run on the various execution clients. Similar to the methodology used in the Gas Cost Estimator project, synthetic blocks that isolate and stress individual EVM operations are generated. To benchmark a single operation, different blocks are created by varying the number of single operations executed and by changing the parameter values to the operation. The EEST benchmark suite contains the tests used to generate these blocks.</p> <p>Then, the Nethermind's Performance Benchmarking tool is used to collect the needed metrics. This tool returns the total execution time of the block and the number of times each operation was executed. Each test block is run multiple times on each client to account for variability in execution time.</p> <p><strong>What about dynamic costs?</strong></p> <p>Some operations have a dynamic component to their costs. For example, the <code>EXP</code> opcode has a gas cost that grows linearly with the exponent's byte size. In these cases, the test benchmarks the operation with a range of inputs to assess how the resource costs vary with different inputs.</p> <p><strong>What about differences between client implementations?</strong></p> <p>Ultimately, we require a single cost model that is independent of the client's implementation. Although the decision may be different in a specific situation, the general rule is to take the worst client result that cannot be optimized. This means that the worst-performing client on a given operation and resource combination will define the cost of that operation for the entire network. This is the safer and most conservative choice.</p> <h4 id="runtime-estimation">Runtime Estimation</h4> <p>To estimate the runtime of a single operation from the total execution time of the corresponding synthetic blocks, a <strong>Non-Negative Least Squares (NNLS) Linear Regression</strong> is used. This model enforces that all coefficients are non-negative, thus ensuring execution time cannot be negative. The model estimates runtime as a linear combination of:</p> <ul> <li><strong>Constant term (intercept)</strong>: Base overhead for executing the test, which includes setup and teardown time</li> <li><strong>Operation count (slope)</strong>: Number of times the operation is executed in the test. This parameter is the one that allows us to estimate the per-operation runtime.</li> <li><strong>Operation-specific parameters</strong>: Variables like number of rounds, message size, or number of pairs</li> </ul> <p>For simple operations (i.e., without additional parameters), the model estimates: <code>runtime = intercept + slope × operation_count</code></p> <p>For variable operations, the model estimates: <code>runtime = intercept + slope × operation_count + param1_coef × operation_count × param1 + param2_coef × operation_count × param2 + ...</code></p> <p>Independent models are created for each client and operation. Only operations and parameters with good model fits (R² &gt; 0.5 and p-value &lt; 0.05) are included in the gas cost proposal to ensure the reliability of the estimates.</p> <p>The report with the model performance by operation and client can be accessed <a href="https://wg-eips.ritovision.com/7904/assets/runtime_estimation/2026-01-15_2026-01-29/runtime_estimation_autogenerated_report/">here</a>, while the key model outputs can be found <a href="https://wg-eips.ritovision.com/7904/./assets/runtime_estimation/2026-01-15_2026-01-29/results.csv">here</a>.</p> <h4 id="conversion-to-gas-costs">Conversion to gas costs</h4> <p>New gas costs are calculated using the same target performance of 60Mgas/s. The formula used is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>new_gas = (anchor_rate * runtime_ms) / 1000</span></span></code></pre> <p>Where <code>runtime_ms</code> is the estimated runtime in milliseconds from the regression models.</p> <p>The report with the full details of this step can be accessed <a href="https://wg-eips.ritovision.com/7904/assets/runtime_estimation/2026-01-15_2026-01-29/new_gas_proposal/">here</a>.</p> <h3 id="other-projects">Other Projects</h3> <p>Several initiatives have explored the real gas costs of EVM operations, providing valuable context for this EIP. Notable examples include:</p> <ul> <li>The <a href="https://wg-eips.ritovision.com/7904/./assets/gas-cost-estimator-report.pdf">Gas Cost Estimator</a> project did a similar empirical analysis. It conducted extensive testing across seven widely-used EVM implementations to measure the actual computational effort required by various opcodes and operations. Conducted in a controlled environment to eliminate external variables, the tests produced accurate and reproducible <a href="https://wg-eips.ritovision.com/7904/./assets/final_gas_schedule_comparison.csv">results</a>. The <a href="https://wg-eips.ritovision.com/7904/./assets/gas-cost-estimator.pdf">findings</a> highlight misalignments between the current gas cost schedule and the real-world computational complexity of EVM operations.</li> <li><a href="https://wg-eips.ritovision.com/7883/">EIP-7883</a> - ModExp Gas Cost Increase: This EIP specifically analyzed the ModExp and proposed a revised pricing scheme. When adjusted with our <code>rescale factor</code>, its costs align with this proposal, requiring no further changes. This consistency validates our measuring approach.</li> <li>Nethermind's Gas Benchmarks: This project takes a different approach to measuring gas costs. It uses standalone clients rather than isolated EVM implementations. Despite the methodological difference, its results mirror those of the Gas Cost Estimator, reinforcing our conclusions.</li> <li>EVM Memory Analysis by @raxhvl: This project focuses on memory-related costs, providing valuable insights into the memory access and expansion costs.</li> </ul> <p>These projects collectively affirm the need to reassess gas costs and demonstrate broad alignment with our approach.</p> <h3 id="computational-complexity-only">Computational Complexity Only</h3> <p>This EIP intentionally focuses on computational complexity—measured as execution time on a bare CPU — while excluding network-related costs like state persistency. This ensures the proposed gas cost adjustments remain implementation-agnostic, applicable across diverse EVM clients regardless of their technological stack. By leveraging empirical data from multiple EVM implementations, we establish a universal, verifiable benchmark for computational effort. This focus simplifies estimation and enhances the proposal’s clarity and applicability within Ethereum’s varied ecosystem.</p> <h3 id="impact-of-gas-costs-changes">Impact of Gas Costs Changes</h3> <p>Raising costs for underpriced operations strengthens security by deterring abuse but may increase transaction fees and reduce throughput.</p> <p>This EIP adopts a conservative strategy, prioritizing increases for operations that empirical data show as underpriced. This allows us to increase the base throughput of the chain without changing the costs of the majority of the other operations.</p> <h4 id="point-evaluation-and-blob-fee-floor-price"><code>POINT_EVALUATION</code> and Blob Fee Floor Price</h4> <p>The proposed increase to <code>POINT_EVALUATION</code> gas cost (from 50,000 to 89,363) has implications for the blob fee floor price mechanism established in <a href="https://wg-eips.ritovision.com/7918/">EIP-7918</a>. Under EIP-7918, the blob base fee is bounded by execution costs through a reserve price of <code>BLOB_BASE_COST * base_fee_per_gas</code>, ensuring that blob consumers pay at least a relevant fraction of the market rate for the computational resources they impose on nodes. The computational resources imposed by blobs are the KZG proof commitments for blob transactions and, as such, the <code>BLOB_BASE_COST</code> was originally defined based on the cost of the <code>POINT_EVALUATION</code> precompile. However, for simplicity reasons, we decide not to change the <code>BLOB_BASE_COST</code>.</p> <h3 id="consideration-of-zk-snark-proof-generation">Consideration of ZK-SNARK Proof Generation</h3> <p>This EIP focuses on optimizing gas costs based on general computational complexity, using a bare CPU as the reference point. Therefore, it does not specifically address the unique demands of ZK-SNARK proof generation. Nevertheless, given that this EIP is only increasing the gas costs of certain operations, it will help rather than hinder proving times for EVM blocks.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backwards-incompatible gas repricing that requires a scheduled network upgrade.</p> <p>Developers and node operators MUST update gas estimation handling to accommodate the new costs. Specifically:</p> <ul> <li>Wallets: Wallets using <code>eth_estimateGas</code> MUST be updated to ensure that they correctly account for the updated gas parameters. Failure to do so could result in underestimating gas, leading to failed transactions.</li> <li>Node Software: RPC methods such as <code>eth_estimateGas</code> MUST incorporate the updated formula for gas calculation with the new state access cost values.</li> <li>Contracts with Hardcoded Gas Limits: Contracts that specify hardcoded gas limits for subcalls (e.g., using call(gas, ...)) may face issues if the new gas costs exceed these limits. In these cases, developers MUST review and potentially update these contracts to ensure they function as intended post-upgrade.</li> </ul> <p>Further research might be required to ensure that contracts that use hard coded limits are not broken.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Changing the cost of compute operations could impact the usability of certain applications. More analysis is needed to understand the potential effects on various dApps and user behaviors.</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-02T00:00:00+00:00 2026-02-11T14:48:26+00:00 Teddyhttps://github.com/0xteddybear Joxeshttps://github.com/0xJoxess Nick Johnsonhttps://github.com/Arachnid Francisco Giordanohttps://github.com/frangio Skeletor Spacemanhttps://github.com/skeletor-spaceman Racuhttps://github.com/0xRacoon TiTihttps://github.com/0xtiti Gorihttps://github.com/0xGorilla Ardyhttps://github.com/0xArdy Onizukahttps://github.com/onizuka-wl Sam Kaufmanhttps://github.com/SampkaML Marco Stronatihttps://github.com/paracetamolo Yuliya Alexievhttps://github.com/yuliyaalexiev Jeff Lauhttps://github.com/jefflau Sam Wilsonhttps://github.com/samwilsn Vitalik Buterinhttps://github.com/vbuterin Thomas Cloweshttps://github.com/clowestab Monohttps://github.com/0xMonoAx Prem Makeighttps://github.com/nxt3d Orcahttps://github.com/0xrcinus https://wg-eips.ritovision.com/7930/

An extensible binary format to refer to an address specific to one chain.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a <strong>binary format</strong> to describe a <em>chain-specific address</em>.</p> <p>This is achieved through a versioned, length-prefixed binary envelope that supports arbitrary-length data. The interpretation and serialization rules for the data within this envelope are defined by the <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/29762ef99a6ffea1e07e3f796c0d1a5a95e89b88/CAIPs/caip-350.md">CAIP-350</a> companion standard, which provide profiles for each chain type and defines the serialization rules for each namespace.</p> <h2 id="motivation">Motivation</h2> <p>The address format utilized on Ethereum mainnet (<a href="https://wg-eips.ritovision.com/55/">ERC-55</a>) is shared by a large number of other blockchains. This format does not encode any information about the chain on which an interaction is intended to occur, which can introduce ambiguity and operational risk.</p> <p>In practice, this limitation has led each protocol to define its own ad hoc way of representing the combination of address and chain, typically using separate fields and protocol-specific conventions. This fragmentation complicates interoperability across protocols, increases tooling complexity, and leads to inconsistencies at the infrastructure level.</p> <p>This proposal builds on insights from <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/2a7d42aebaffa42d1017c702974395ff5c1b3636/CAIPs/caip-10.md">CAIP-10</a> and <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/2a7d42aebaffa42d1017c702974395ff5c1b3636/CAIPs/caip-50.md">CAIP-50</a>. It offers a binary canonical <em>Interoperable Address</em> format which:</p> <ul> <li>Binds together chain identification and the raw address.</li> <li>Is compact for usage with cross-chain message passing and intent declaration.</li> <li>Extends beyond EVM blockchains.</li> </ul> <p>These features can not be added to existing standards as they are not easily extensible - this one is.</p> <h3 id="comparisons-with-other-standards">Comparisons with other standards</h3> <h4 id="caip-10">CAIP-10</h4> <p><a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/2a7d42aebaffa42d1017c702974395ff5c1b3636/CAIPs/caip-10.md">CAIP-10</a> proposes a standard text format to represent an address on a specific chain (referenced by its <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/2a7d42aebaffa42d1017c702974395ff5c1b3636/CAIPs/caip-2.md">CAIP-2</a> identifier).</p> <p>The standard <strong>does not</strong> concern itself with the serialization/deserialization of the <em>target address</em>. It assumes knowledge of the native address format for each chain and does not enforce any serialization or canonicalization rules.</p> <p>While it is trivial to add support for chains to <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/2a7d42aebaffa42d1017c702974395ff5c1b3636/CAIPs/caip-10.md">CAIP-10</a>, the format is not optimized for usage within smart contracts as strings are an inefficient way to store data on-chain.</p> <p><a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/2a7d42aebaffa42d1017c702974395ff5c1b3636/CAIPs/caip-10.md">CAIP-10</a> depends on <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/2a7d42aebaffa42d1017c702974395ff5c1b3636/CAIPs/caip-2.md">CAIP-2</a>, which limits the chain reference to 32 characters. This constraint means that <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/2a7d42aebaffa42d1017c702974395ff5c1b3636/CAIPs/caip-2.md">CAIP-2</a> can not losslessy represent a chain. e.g. Solana chains utilize the leading 32 characters of the base58btc-encoded genesis blockhash, which is not a uniquely deterministic way of representing a 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> <h3 id="terminology">Terminology</h3> <p><strong>Target Address</strong> : The address itself, independent of chain context. Serialized per the <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/29762ef99a6ffea1e07e3f796c0d1a5a95e89b88/CAIPs/caip-350.md">CAIP-350</a> rules for the applicable namespace. In the examples below, the target address is <code>0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045</code>.</p> <p><strong>Chain-specific Address</strong> : An address representation that includes both the <em>target address</em> <strong>and</strong> the chain being targeted. The following are examples of chain-specific addresses:</p> <ul> <li>The <em>Interoperable Address</em> definition outlined in this specification</li> <li>The addressing format outlined in <a href="https://wg-eips.ritovision.com/3770/">ERC-3770</a>, e.g. <code>arb:0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045</code></li> <li>The <em>Interoperable Name</em> definition outlined in <a href="https://wg-eips.ritovision.com/7828/">ERC-7828</a></li> </ul> <p><strong>Interoperable Address</strong> : A binary payload which unambiguously identifies a <em>target address</em> on a target chain. e.g. <code>0x00010000010114d8da6bf26964af9d7eed9e03e53415d37aa96045</code></p> <h3 id="interoperable-address-definition"><em>Interoperable Address</em> Definition</h3> <p>An <em>Interoperable Address</em> as defined by this standard MUST have the following binary format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>┌─────────┬───────────┬──────────────────────┬────────────────┬───────────────┬─────────┐</span></span> <span class="giallo-l"><span>│ Version │ ChainType │ ChainReferenceLength │ ChainReference │ AddressLength │ Address │</span></span> <span class="giallo-l"><span>└─────────┴───────────┴──────────────────────┴────────────────┴───────────────┴─────────┘</span></span></code></pre> <p>The components outlined above have the following meanings:</p> <p><strong>Version</strong> : A 2-byte version identifier. For version 1 (this specification), this MUST be <code>0x0001</code> (big-endian). Future versions SHOULD be standardized in separate ERCs.</p> <p><strong>ChainType</strong> : A 2-byte value corresponding to a CASA namespace. It allows users to interpret and display the <em>ChainReference</em> and <em>Address</em>. Values are defined in the corresponding <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/29762ef99a6ffea1e07e3f796c0d1a5a95e89b88/CAIPs/caip-350.md">CAIP-350</a> profile for the namespace.</p> <p><strong>ChainReferenceLength</strong> : A 1-byte integer encoding the length of <em>ChainReference</em> in bytes. Note that it MAY be zero, in which case the <em>Interoperable Address</em> MUST NOT include a chain reference.</p> <p><strong>ChainReference</strong> : Variable length, binary representation of the <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/29762ef99a6ffea1e07e3f796c0d1a5a95e89b88/CAIPs/caip-350.md">CAIP-350</a> chain reference. Serialization of the <em>ChainReference</em> within a specific namespace MUST follow the algorithm defined in the namespace's <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/29762ef99a6ffea1e07e3f796c0d1a5a95e89b88/CAIPs/caip-350.md">CAIP-350</a> profile. Chain profiles are maintained by the Chain-Agnostic Standards Alliance (CASA).</p> <p><strong>AddressLength</strong> : 1-byte integer encoding the length of Address in bytes. Note that it MAY be zero, in which case the <em>Interoperable Address</em> MUST NOT include an address. It MUST NOT be zero if the <em>ChainReferenceLength</em> is also zero.</p> <p><strong>Address</strong> : Variable length field containing the binary encoding of the characters of the serialized address. The serialization for a specific <em>ChainType</em> MUST follow the rules of its corresponding <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/29762ef99a6ffea1e07e3f796c0d1a5a95e89b88/CAIPs/caip-350.md">CAIP-350</a> profile.</p> <hr /> <p>If you choose to display an <em>Interoperable Address</em> it is RECOMMENDED that you display it as a lower case hexadecimal string.</p> <h3 id="examples">Examples</h3> <h4 id="example-1-ethereum-mainnet-address">Example 1: Ethereum mainnet address</h4> <p><strong>Components</strong></p> <table><thead><tr><th style="text-align: left">Key</th><th style="text-align: left">Value</th></tr></thead><tbody> <tr><td style="text-align: left"><strong>Version</strong></td><td style="text-align: left"><code>1</code></td></tr> <tr><td style="text-align: left"><strong>ChainType</strong></td><td style="text-align: left"><code>0x0000</code></td></tr> <tr><td style="text-align: left"><strong>ChainReferenceLength</strong></td><td style="text-align: left"><code>1</code></td></tr> <tr><td style="text-align: left"><strong>ChainReference</strong></td><td style="text-align: left"><code>1</code></td></tr> <tr><td style="text-align: left"><strong>AddressLength</strong></td><td style="text-align: left"><code>20</code></td></tr> <tr><td style="text-align: left"><strong>Address</strong></td><td style="text-align: left"><code>0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045</code></td></tr> </tbody></table> <p><strong>Interoperable Address</strong></p> <p>These components produce the following <em>Interoperable Address</em>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x00010000010114d8da6bf26964af9d7eed9e03e53415d37aa96045</span></span> <span class="giallo-l"><span> ^^^^-------------------------------------------------- Version </span></span> <span class="giallo-l"><span> ^^^^---------------------------------------------- ChainType </span></span> <span class="giallo-l"><span> ^^-------------------------------------------- ChainReferenceLength</span></span> <span class="giallo-l"><span> ^^------------------------------------------ ChainReference </span></span> <span class="giallo-l"><span> ^^---------------------------------------- AddressLength </span></span> <span class="giallo-l"><span> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Address </span></span></code></pre> <hr /> <h4 id="example-2-solana-mainnet-address">Example 2: Solana mainnet address</h4> <p><strong>Components</strong></p> <table><thead><tr><th style="text-align: left">Key</th><th style="text-align: left">Value</th></tr></thead><tbody> <tr><td style="text-align: left"><strong>Version</strong></td><td style="text-align: left"><code>1</code></td></tr> <tr><td style="text-align: left"><strong>ChainType</strong></td><td style="text-align: left"><code>0x0002</code></td></tr> <tr><td style="text-align: left"><strong>ChainReferenceLength</strong></td><td style="text-align: left"><code>32</code></td></tr> <tr><td style="text-align: left"><strong>ChainReference</strong></td><td style="text-align: left"><code>5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d</code></td></tr> <tr><td style="text-align: left"><strong>AddressLength</strong></td><td style="text-align: left"><code>32</code></td></tr> <tr><td style="text-align: left"><strong>Address</strong></td><td style="text-align: left"><code>MJKqp326RZCHnAAbew9MDdui3iCKWco7fsK9sVuZTX2</code></td></tr> </tbody></table> <p><strong>Interoperable Address</strong></p> <p>These components produce the following <em>Interoperable Address</em>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x000100022045296998a6f8e2a784db5d9f95e18fc23f70441a1039446801089879b08c7ef02005333498d5aea4ae009585c43f7b8c30df8e70187d4a713d134f977fc8dfe0b5</span></span> <span class="giallo-l"><span> ^^^^---------------------------------------------------------------------------------------------------------------------------------------- Version</span></span> <span class="giallo-l"><span> ^^^^------------------------------------------------------------------------------------------------------------------------------------ ChainType</span></span> <span class="giallo-l"><span> ^^---------------------------------------------------------------------------------------------------------------------------------- ChainReferenceLength</span></span> <span class="giallo-l"><span> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^------------------------------------------------------------------ ChainReference</span></span> <span class="giallo-l"><span> ^^---------------------------------------------------------------- AddressLength</span></span> <span class="giallo-l"><span> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^--- Address</span></span></code></pre> <hr /> <h4 id="example-3-evm-address-without-chainreference">Example 3: EVM address without ChainReference</h4> <p><strong>Components</strong></p> <table><thead><tr><th style="text-align: left">Key</th><th style="text-align: left">Value</th></tr></thead><tbody> <tr><td style="text-align: left"><strong>Version</strong></td><td style="text-align: left"><code>1</code></td></tr> <tr><td style="text-align: left"><strong>ChainType</strong></td><td style="text-align: left"><code>0x0000</code></td></tr> <tr><td style="text-align: left"><strong>ChainReferenceLength</strong></td><td style="text-align: left"><code>0</code></td></tr> <tr><td style="text-align: left"><strong>ChainReference</strong></td><td style="text-align: left">N/A</td></tr> <tr><td style="text-align: left"><strong>AddressLength</strong></td><td style="text-align: left"><code>20</code></td></tr> <tr><td style="text-align: left"><strong>Address</strong></td><td style="text-align: left"><code>0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045</code></td></tr> </tbody></table> <p><strong>Interoperable Address</strong></p> <p>These components produce the following <em>Interoperable Address</em>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x000100000014d8da6bf26964af9d7eed9e03e53415d37aa96045</span></span> <span class="giallo-l"><span> ^^^^------------------------------------------------ Version</span></span> <span class="giallo-l"><span> ^^^^-------------------------------------------- ChainType</span></span> <span class="giallo-l"><span> ^^------------------------------------------ ChainReferenceLength</span></span> <span class="giallo-l"><span> ^^---------------------------------------- AddressLength</span></span> <span class="giallo-l"><span> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Address</span></span></code></pre> <hr /> <h4 id="example-4-solana-mainnet-network-no-address">Example 4: Solana mainnet network, no address</h4> <p><strong>Components</strong></p> <table><thead><tr><th style="text-align: left">Key</th><th style="text-align: left">Value</th></tr></thead><tbody> <tr><td style="text-align: left"><strong>Version</strong></td><td style="text-align: left"><code>1</code></td></tr> <tr><td style="text-align: left"><strong>ChainType</strong></td><td style="text-align: left"><code>0x0002</code></td></tr> <tr><td style="text-align: left"><strong>ChainReferenceLength</strong></td><td style="text-align: left"><code>32</code></td></tr> <tr><td style="text-align: left"><strong>ChainReference</strong></td><td style="text-align: left"><code>5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d</code></td></tr> <tr><td style="text-align: left"><strong>AddressLength</strong></td><td style="text-align: left"><code>0</code></td></tr> <tr><td style="text-align: left"><strong>Address</strong></td><td style="text-align: left">N/A</td></tr> </tbody></table> <p><strong>Interoperable Address</strong></p> <p>These components produce the following <em>Interoperable Address</em>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x000100022045296998a6f8e2a784db5d9f95e18fc23f70441a1039446801089879b08c7ef000</span></span> <span class="giallo-l"><span> ^^^^------------------------------------------------------------------------ Version</span></span> <span class="giallo-l"><span> ^^^^-------------------------------------------------------------------- ChainType</span></span> <span class="giallo-l"><span> ^^------------------------------------------------------------------ ChainReferenceLength</span></span> <span class="giallo-l"><span> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^-- ChainReference</span></span> <span class="giallo-l"><span> ^^ AddressLength</span></span></code></pre><h3 id="versioning">Versioning</h3> <p>These rules ensure that future standards that build upon this one maintain backwards compatibility.</p> <p>Future versions:</p> <ul> <li>MUST be trivially convertible to the <em>Interoperable Address</em> format defined in this specification</li> <li>MUST set the most significant bit of the version field to 1 if the <em>Interoperable Address</em> format is not backward-compatible with the parsing rules outlined herein</li> <li>MUST support defining an address, a chain, or both</li> <li>MAY add fields but MUST NOT alter or omit any data required to reconstruct the Version 1 <em>Interoperable Address</em> exactly, bit for bit</li> <li>MAY only be able to represent a subset of the CAIP namespaces</li> </ul> <h3 id="text-representation">Text representation</h3> <p>This specification defines a canonical binary representation that <strong>is not</strong> intended to be used directly in user-facing contexts. If an implementer chooses to display an <em>Interoperable Address</em> directly, it is RECOMMENDED that it be represented as a lowercase hexadecimal string. <a href="https://wg-eips.ritovision.com/7828/">ERC-7828</a> is one example of a human-readable <em>chain-specific address</em> definition that can be displayed in user-facing contexts.</p> <p>The companion standard, CAIP-350, specifies on a per-namespace basis, the rules for converting the <code>ChainReference</code> and <code>Address</code> components of the <em>Interoperable Address</em> into human readable representations. These MAY be displayed in user-facing contexts.</p> <h2 id="rationale">Rationale</h2> <p>This ERC defines a compact binary format for representing a <em>chain-specific address</em>, primarily intended for use within smart contracts. For other contexts—such as display to end users or programmatic use in APIs—alternative <em>chain-specific addressing</em> standards may be more appropriate. For example, <a href="https://wg-eips.ritovision.com/7828/">ERC-7828</a> specifies a human-readable <em>chain-specific address</em> format.</p> <p>The interoperability roadmap benefits significantly from first having a standardized binary format for addresses, which allows the message passing and intents verticals to move forward on a consistent common interface.</p> <p>The rationale for some of the low level specification decisions are outlined below:</p> <ul> <li>We chose to allow the <code>Address</code> and <code>ChainReference</code> components to be zero-length to make this standard flexible and to allow developers to use a single, uniform standard for many different jobs. For example if a user wants to represent an address on any compatible chain, or if the user simply wants to represent the chain itself.</li> <li>We chose <em>not</em> to use alternate encoding formats (e.g., <code>base58</code> or <code>base64</code>) in order to make it easier for wallets and dApps to work with, and convert between, addresses that both use and do not use this addressing standard.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>While this standard aims to be a foundation to be able to canonically refer to addresses on different chains, that guarantee is going to be a leaky abstraction in the real world, given that e.g. a particular chain namespace might define a serialization scheme that can't guarantee canonicity of addresses, or a given network might have two valid <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/2a7d42aebaffa42d1017c702974395ff5c1b3636/CAIPs/caip-2.md">CAIP-2</a> ids referring to it.</p> <p>It is therefore advised for implementers requiring canonicity of addresses (e.g by using them as keys in smart contract mappings or other key-value stores), to thoroughly review the <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/29762ef99a6ffea1e07e3f796c0d1a5a95e89b88/CAIPs/caip-350.md">CAIP-350</a> profile of a chain namespace for the possibility of a lack of canonicity of addresses (which should be noted in the profile's 'Extra Considerations' section) as well as collisions with other already-supported namespaces.</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-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Wamith Mockbillhttps://github.com/wamith https://wg-eips.ritovision.com/7878/

Inheritance of tokens after the owner's death

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a standard interface for contracts to allow tokens to be inherited after the owner's death. The interface allows token owners to set up a Will and designate executors to enable the transfer of tokens to inheritors after a specified waiting period.</p> <h2 id="motivation">Motivation</h2> <p>Crypto Tokens in general and NFTs in particular are starting to be used to tokenise real-world assets. In order for them to be adopted by the main stream finance world, there needs to be a way to inherit these tokens after the owner has passed away. Currently, there is no standardised way for token holders to pass on their digital assets in the event of their death.<br /> This EIP aims to solve this problem by providing a standard interface for "bequeathable" tokens, allowing for a secure and transparent process of token inheritance. In designing this interface we have tried to follow the real world process of Will creation and execution.</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>Every compliant contract MUST implement the <code>Bequeathable</code> interface:</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"> EIP-7878 Bequeathable tokens</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-7878</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">@notice</span><span class="z-comment"> Bequeathable interface</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"> Bequeathable</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"> Announce the owner&#39;s tokens are to be inherited</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted by `announceObit`</span></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"> The original owner of the 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"> inheritor</span><span class="z-comment"> The address of the wallet that will inherit the tokens once the moratoriumTTL time has passed</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"> ObituaryStarted</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"> inheritor</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"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Announce the obituary (and moratorium) for the owner has been cancelled, as well as who cancelled it</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted by `cancelObit`</span></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"> The original owner of the 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"> cancelledBy</span><span class="z-comment"> The address that triggered this cancellation. This can be the owner or any of the inheritors</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"> ObituaryCancelled</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"> cancelledBy</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"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> A token owner can set a Will and names one or more executors who are able to transfer their tokens after their death</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Although more than one executor address can be set, only one is required to start the process and then do the transfer</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Subsequent calls to this function should overwrite any existing Will</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> executors</span><span class="z-comment"> An array of executors eg legal council, spouse, child 1, child 2 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"> moratoriumTTL</span><span class="z-comment"> The time that must pass (in seconds) from when the obituary is announced to when the inheritance transfer can take place</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The moratoriumTTL is a safety buffer time frame that allows for any intervention before the tokens get transferred</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"> setWill</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"> executors</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> moratoriumTTL</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 details of a Will if set</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This is a way for the owner to confirm that they have correctly set their Will</span></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"> The current owner of the 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"> executors</span><span class="z-comment"> A list of all the executors for this owners will</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"> moratoriumTTL</span><span class="z-comment"> The length of time (in seconds) that must elapse after calling announceObit before the actual transfer can happen</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"> getWill</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 class="z-variable"> executors</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> moratoriumTTL</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"> Start the Obituary process, by announcing it and declaring who is the intended inheritor</span></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"> The current owner of the 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"> inheritor</span><span class="z-comment"> The address of the owner to be</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"> announceObit</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"> inheritor</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"> Cancel the Obituary that has been previously announced. Can be called by any of the executors (or the owner if still around)</span></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"> The original owner of 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"> cancelObit</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get the designated inheritor and how much time is left before the moratoriumTTL is 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"> owner</span><span class="z-comment"> The current owner of the 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"> inheritor</span><span class="z-comment"> The named inheritor when the obituary was announced</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"> moratoriumTTL</span><span class="z-comment"> The time left for the moratoriumTTL before the transfer can be done</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> A minus figure for moratoriumTTL indicates that the wait time has elapsed and the tokens can be bequeathed</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"> getObit</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 class="z-variable"> inheritor</span><span>,</span><span class="z-support"> int256</span><span class="z-variable"> moratoriumTTL</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"> Bequeath ie transfer the tokens to the previously declared inheritor</span></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"> The original owner of the tokens</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The transfer should happen to the inheritor address when `announceObit` was called</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"> bequeath</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>}</span></span></code></pre><h3 id="functions">Functions</h3> <ol> <li><code>setWill</code>: Allows a token owner to set up or update their Will.</li> <li><code>getWill</code>: Returns the current Will details for a given owner.</li> <li><code>announceObit</code>: Initiates the inheritance process by an executor.</li> <li><code>cancelObit</code>: Cancels an active obituary process.</li> <li><code>getObit</code>: Retrieves the current obituary status.</li> <li><code>bequeath</code>: Transfers tokens to the inheritor after the waiting period.</li> </ol> <h3 id="events">Events</h3> <ol> <li><code>ObituaryStarted</code>: Emitted when an obituary is announced.</li> <li><code>ObituaryCancelled</code>: Emitted when an obituary is cancelled.</li> </ol> <h2 id="rationale">Rationale</h2> <p>The standard follows what currently happens in real life when preparing and executing a Will.</p> <ol> <li>An owner writes a Will and in doing so names the executor(s) of their Will</li> <li>Upon passing away, the executor will announce the Obituary</li> <li>The Will is read and the inheritors are identified</li> <li>The transfer of ownership is executed according to the wishes of the Will</li> </ol> <p>However, real life is not always as straight forward as this. Conflicts happen all the time. To handle this situation and to keep the interface simple, we added the ability to cancel the Obituary by ANY of the executors. In this way, if there is any conflict, it can be challenged out in the courts and once the matter is settled, the Obituary process can start again.</p> <p>Again to keep the interface clean, all the tokens get transferred to one address. It is then that person's responsibility to execute any further transfers.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is compatible with existing token standards like <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>. It can be implemented alongside these standards without affecting their core functionality.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests are included in <a href="https://wg-eips.ritovision.com/7878/./assets/test/Bequeath.test.js"><code>Bequeath.test.js</code></a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/7878/./assets/contracts/Bequeathable.sol"><code>Bequeathable.sol</code></a></p> <h2 id="security-considerations">Security Considerations</h2> <p>Implementers should carefully consider access control mechanisms to ensure that only authorized parties can execute Will-related functions.</p> <p>The moratoriumTTL should be set to a reasonable duration to allow for potential disputes or corrections. We recommend at least 30 days, especially for tokens that are of high value. It limits the potential damage in scenarios such as the obituray process being triggered by a bad actor who has taken over one of the executor wallets.</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-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 Sean Luis Guada Rodríguezhttps://github.com/SeanLuisseanluis47@gmail.com https://wg-eips.ritovision.com/7893/

Verifiable solvency proofs and financial health monitoring for DeFi protocols

<h2 id="abstract">Abstract</h2> <p>A standardized interface that enables DeFi protocols to implement verifiable solvency proofs through smart contracts. This interface works by defining structured data types for assets and liabilities, with oracle-validated price feeds tracking token values in real-time. The technical implementation calculates solvency ratios using configurable risk thresholds (105% minimum solvency ratio), maintains historical metrics for trend analysis, and emits structured events upon threshold breaches. The interface standardizes methods for querying current financial health, retrieving historical data points, and updating protocol positions, all while enforcing proper validation and security controls.</p> <h2 id="motivation">Motivation</h2> <p>The DeFi ecosystem currently lacks standardization in financial health reporting, leading to:</p> <ol> <li>Inconsistent reporting methodologies across protocols</li> <li>Limited transparency in real-time financial status</li> <li>Absence of standardized early warning systems</li> <li>Complex and time-consuming audit processes</li> <li>Difficulty in assessing cross-protocol risks</li> </ol> <p>This proposal directly addresses these challenges through a comprehensive interface that standardizes solvency reporting and monitoring:</p> <ul> <li> <p><strong>Standardized Methodology</strong>: By providing a common interface with well-defined asset/liability structures and mathematical models, this EIP eliminates reporting inconsistencies that currently prevent clear comparisons between protocols.</p> </li> <li> <p><strong>Real-time Transparency</strong>: The proposed event system and query functions enable continuous monitoring of protocol health, rather than relying on periodic manual reporting that can miss critical changes in financial status.</p> </li> <li> <p><strong>Automated Risk Alerts</strong>: The threshold-based alert system provides early warnings of deteriorating conditions through standardized <code>RiskAlert</code> events, enabling faster response to potential insolvencies than current ad-hoc monitoring approaches.</p> </li> <li> <p><strong>Efficient Audit Trail</strong>: The historical metrics tracking creates an immutable record of protocol health over time, significantly reducing audit complexity compared to current solutions that require reconstructing historical positions.</p> </li> <li> <p><strong>Cross-Protocol Risk Assessment</strong>: A common interface enables aggregation of risk data across multiple protocols, allowing systemic risk monitoring that's impossible with today's fragmented reporting systems.</p> </li> </ul> <p>Alternative approaches considered include:</p> <ol> <li> <p><strong>Off-chain Reporting</strong>: While simpler to implement, this lacks the verifiability, real-time nature, and trustless properties of an on-chain solution.</p> </li> <li> <p><strong>Protocol-Specific Standards</strong>: These would lack the interoperability benefits of a common standard and would perpetuate fragmentation.</p> </li> <li> <p><strong>Complex Risk Models</strong>: More sophisticated models were evaluated but rejected in favor of this proposal's balance between comprehensiveness and implementability.</p> </li> </ol> <p>This EIP represents the optimal approach by providing a flexible yet standardized framework that can be implemented across diverse protocol types while maintaining reasonable gas efficiency and usability.</p> <p>The <code>ISolvencyProof</code> interface provides a standardized, on-chain mechanism for DeFi protocols to report, verify, and monitor their solvency status. This interface is designed to be both comprehensive and flexible, supporting a wide range of protocol architectures and risk management strategies.</p> <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><img src="https://wg-eips.ritovision.com/7893/./assets/images/diagrams/main.svg" alt="main" /></p> <h3 id="core-interface-requirements">Core Interface Requirements</h3> <p>Compliant implementations MUST implement the <code>ISolvencyProof</code> interface.</p> <p>Compliant implementations MUST provide the following functionality:</p> <ol> <li> <p><strong>Asset and Liability Tracking</strong>: Implementations MUST store and maintain current protocol assets and liabilities with token addresses, amounts, and ETH-denominated values in contract state variables. This data MUST be updated through the <code>updateAssets</code> and <code>updateLiabilities</code> functions called by authorized oracles.</p> </li> <li> <p><strong>Timestamp Recording</strong>: Implementations MUST record the timestamp of each asset and liability update.</p> </li> <li> <p><strong>Solvency Calculation</strong>: Implementations MUST calculate the solvency ratio as <code>(Total Assets / Total Liabilities) × 10000</code>.</p> </li> <li> <p><strong>Historical Data</strong>: Implementations MUST maintain historical records of solvency metrics for querying within specified time ranges. Implementations MAY expire old data after a reasonable retention period (e.g., 1 year) but MUST clearly document their retention policy and available time ranges in their implementation documentation.</p> </li> <li> <p><strong>Event Emission</strong>: Implementations MUST emit <code>SolvencyMetricsUpdated</code> events when financial metrics are updated, and SHOULD emit <code>RiskAlert</code> events when risk thresholds are breached.</p> </li> <li> <p><strong>Array Validation</strong>: Implementations MUST ensure that all arrays in <code>ProtocolAssets</code> and <code>ProtocolLiabilities</code> structures are of equal length.</p> </li> <li> <p><strong>Value Denomination</strong>: Implementations MUST express all values in ETH with 18 decimals for consistency.</p> </li> </ol> <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.20</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"> ISolvencyProof</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@author</span><span class="z-comment"> Sean Luis (@SeanLuis) &lt;seanluis47@gmail.com&gt;</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Standard Interface for DeFi Protocol Solvency (EIP-DRAFT)</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 the DeFi Protocol Solvency Proof Standard</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@custom:security</span><span class="z-comment">-contact seanluis47@gmail.com</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@custom:version</span><span class="z-comment"> 1.0.0</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"> ISolvencyProof</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"> Protocol assets structure</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Represents the current state of protocol assets</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@custom:validation</span><span class="z-comment"> All arrays must be equal length</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@custom:validation</span><span class="z-comment"> Values must be in ETH with 18 decimals</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"> ProtocolAssets</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span> tokens</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Addresses of tracked tokens</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span> amounts</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Amount of each token (in token decimals)</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span> values</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Value in ETH (18 decimals) of each token amount</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> timestamp</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Last update timestamp (Unix timestamp in seconds)</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"> Protocol liabilities structure</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Represents the current state of protocol liabilities</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@custom:validation</span><span class="z-comment"> All arrays must be equal length</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@custom:validation</span><span class="z-comment"> Values must be in ETH with 18 decimals</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"> ProtocolLiabilities</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span> tokens</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Addresses of liability tokens</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span> amounts</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Amount of each liability (in token decimals)</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span> values</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Value in ETH (18 decimals) of each liability</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> timestamp</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Last update timestamp (Unix timestamp in seconds)</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"> Emitted on metrics update</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Real-time financial health 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"> totalAssets</span><span class="z-comment"> Sum of asset values in ETH</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> totalLiabilities</span><span class="z-comment"> Sum of liability values in ETH</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> healthFactor</span><span class="z-comment"> Calculated as (totalAssets/totalLiabilities) × 10000</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> timestamp</span><span class="z-comment"> Update timestamp</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"> SolvencyMetricsUpdated</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> totalAssets</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> totalLiabilities</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> healthFactor</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> timestamp</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"> Emitted when risk thresholds are breached</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Alerts stakeholders of potential solvency risks</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"> riskLevel</span><span class="z-comment"> Risk level indicating severity of the breach (CRITICAL, HIGH_RISK, WARNING)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> currentValue</span><span class="z-comment"> Current value that triggered the alert</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> threshold</span><span class="z-comment"> Risk threshold that was breached</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> timestamp</span><span class="z-comment"> Alert timestamp</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"> RiskAlert</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> riskLevel</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> currentValue</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> threshold</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> timestamp</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 protocol&#39;s current assets</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"> Full</span><span class="z-comment"> asset state including tokens, amounts and values</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"> getProtocolAssets</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-storage z-type">ProtocolAssets</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get protocol&#39;s current liabilities</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"> Full</span><span class="z-comment"> liability state including tokens, amounts and values</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"> getProtocolLiabilities</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-storage z-type">ProtocolLiabilities</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Calculate current solvency ratio</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"> SR</span><span class="z-comment"> = (Total Assets / Total Liabilities) × 10000</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"> getSolvencyRatio</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"> Check protocol solvency status</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"> isSolvent</span><span class="z-comment"> True if ratio &gt;= minimum 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"> healthFactor</span><span class="z-comment"> Current solvency ratio</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"> verifySolvency</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 class="z-variable"> isSolvent</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> healthFactor</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 historical solvency metrics</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> startTime</span><span class="z-comment"> Start of time range (Unix timestamp in seconds)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> endTime</span><span class="z-comment"> End of time range (Unix timestamp in seconds)</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"> timestamps</span><span class="z-comment"> Array of historical update timestamps (Unix timestamp in seconds)</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"> ratios</span><span class="z-comment"> Array of historical solvency ratios (scaled by 10000)</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"> assets</span><span class="z-comment"> Array of historical asset states</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"> liabilities</span><span class="z-comment"> Array of historical liability states</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@custom:gas</span><span class="z-comment"> This function may consume significant gas for large time ranges</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"> getSolvencyHistory</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> startTime</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> endTime</span><span>)</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"> 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>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> timestamps</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"> ratios</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> ProtocolAssets</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> assets</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> ProtocolLiabilities</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> liabilities</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"> Update protocol assets</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Only callable by authorized oracle</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"> updateAssets</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"> tokens</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></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"> values</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"> Update protocol liabilities</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Only callable by authorized oracle</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"> updateLiabilities</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"> tokens</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></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"> values</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><h3 id="oracle-authorization-requirements">Oracle Authorization Requirements</h3> <p>Implementations MUST restrict calls to <code>updateAssets</code> and <code>updateLiabilities</code> to authorized addresses only. Implementations MUST revert these function calls when <code>msg.sender</code> is not an authorized oracle.</p> <p>Implementations MAY provide oracle management functions. If provided, implementations SHOULD emit events when oracle authorization changes.</p> <p>Example oracle management pattern (OPTIONAL):</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Optional oracle management pattern</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> OracleUpdated</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> oracle</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> authorized</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setOracle</span><span>(</span><span class="z-support">address</span><span class="z-variable"> oracle</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> authorized</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>The core standard focuses on solvency verification requirements. Oracle management implementation details are left to individual protocol needs.</p> <h3 id="update-function-requirements">Update Function Requirements</h3> <p>Implementations MUST validate input parameters for <code>updateAssets</code> and <code>updateLiabilities</code> functions:</p> <ol> <li>Implementations MUST revert if the <code>tokens</code>, <code>amounts</code>, and <code>values</code> arrays are not of equal length.</li> <li>Implementations MUST update the timestamp field to the current block timestamp (<code>block.timestamp</code>) when processing updates.</li> <li>Implementations MUST emit a <code>SolvencyMetricsUpdated</code> event after successfully updating assets or liabilities.</li> </ol> <h3 id="query-function-requirements">Query Function Requirements</h3> <p>Implementations MUST provide the following query capabilities:</p> <ol> <li> <p><code>getProtocolAssets()</code> MUST return the current state of protocol assets including all token addresses, amounts, values, and the timestamp of the last update.</p> </li> <li> <p><code>getProtocolLiabilities()</code> MUST return the current state of protocol liabilities including all token addresses, amounts, values, and the timestamp of the last update.</p> </li> <li> <p><code>getSolvencyRatio()</code> MUST calculate and return the solvency ratio as <code>(totalAssets * 10000) / totalLiabilities</code>. If <code>totalLiabilities</code> is zero, implementations SHOULD return a value indicating maximum solvency or revert with an appropriate error.</p> </li> <li> <p><code>verifySolvency()</code> MUST return both a boolean indicating solvency status and the current health factor (solvency ratio).</p> </li> <li> <p><code>getSolvencyHistory(startTime, endTime)</code> MUST return historical data for all recorded snapshots where the timestamp falls within the specified range (inclusive).</p> </li> </ol> <h3 id="interface-detection-support">Interface Detection Support</h3> <p>Compliant implementations MUST implement the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> <code>supportsInterface</code> function and MUST return <code>true</code> for the <code>ISolvencyProof</code> interface ID.</p> <h2 id="rationale">Rationale</h2> <p>The standard's design prioritizes:</p> <ol> <li>Reliability through robust calculations</li> <li>Efficiency via optimized data structures</li> <li>Flexibility through modular design</li> <li>Transparency via standardized metrics</li> </ol> <h4 id="asset-and-liability-management">Asset and Liability Management</h4> <p>Authorized oracles update the protocol's asset and liability data through the <code>updateAssets</code> and <code>updateLiabilities</code> functions, which accept parallel arrays of token addresses, amounts, and ETH-denominated values. The interface enforces data consistency by requiring all input arrays to be of equal length and all values to be denominated in ETH with 18 decimal precision. Each update automatically timestamps the data using <code>block.timestamp</code>, ensuring chronological ordering of financial state changes and enabling accurate historical analysis.</p> <h4 id="solvency-calculation-and-verification">Solvency Calculation and Verification</h4> <p>The <code>getSolvencyRatio</code> function computes the current solvency ratio, defined as the total value of assets divided by the total value of liabilities, scaled by a factor of 10,000 for precision. The <code>verifySolvency</code> function checks whether the protocol meets a minimum required solvency ratio (commonly 105%), returning both a boolean status and the current health factor. This allows both on-chain and off-chain systems to quickly assess the protocol's financial health and respond accordingly.</p> <h4 id="historical-data-and-trend-analysis">Historical Data and Trend Analysis</h4> <p>The <code>getSolvencyHistory</code> function enables retrieval of historical solvency metrics, including timestamps, ratios, and the corresponding asset and liability states over a specified time range. This historical data is crucial for reconstructing past events, analyzing risk trends, and providing transparency to stakeholders. This supports audits, regulatory requirements, and trend analysis needs.</p> <h4 id="event-emission-and-risk-alerts">Event Emission and Risk Alerts</h4> <p>Whenever the protocol's financial metrics are updated, the <code>SolvencyMetricsUpdated</code> event is emitted, providing real-time data for off-chain monitoring and analytics. When risk thresholds are breached (for example, if the solvency ratio falls below a critical level), the <code>RiskAlert</code> event is triggered, signaling the severity and nature of the risk. These events enable automated monitoring systems, auditors, and users to receive timely notifications and take appropriate action.</p> <h4 id="oracle-integration-and-security">Oracle Integration and Security</h4> <p>The interface is designed to be oracle-agnostic, allowing protocols to integrate with a variety of price feed solutions (e.g., Chainlink, API3, custom oracles). The requirement that only authorized oracles can update asset and liability data ensures that updates are secure and resistant to manipulation. The optional <code>setOracle</code> and <code>OracleUpdated</code> event pattern is recommended for managing oracle permissions and maintaining robust security controls.</p> <h4 id="intended-usage-and-integration">Intended Usage and Integration</h4> <p>Protocols implementing this interface integrate with trusted oracles for price feeds and position updates, maintain up-to-date records of their financial positions, emit standardized events for off-chain monitoring and risk management, and provide transparent, verifiable, and standardized information about their solvency status to all stakeholders. External consumers (such as auditors, users, or other smart contracts) can query the protocol's current and historical solvency status using the provided view functions, and can listen for events to receive timely notifications of significant changes or risks. This design ensures that all stakeholders have access to reliable, real-time information about a protocol's financial health, enabling more robust risk management and greater trust in the DeFi ecosystem.</p> <h3 id="data-structure-design-rationale">Data Structure Design Rationale</h3> <p>The interface defines two primary data structures (<code>ProtocolAssets</code> and <code>ProtocolLiabilities</code>) with specific attributes:</p> <ol> <li> <p><strong>Array-based token tracking</strong> was selected over mapping-based approaches for:</p> <ul> <li>More efficient state retrieval for monitoring systems</li> <li>Better compatibility with historical tracking requirements</li> <li>Simplified batch updates in volatile market conditions</li> </ul> </li> <li> <p><strong>Timestamp embedding</strong> within structures rather than separate mappings provides:</p> <ul> <li>Atomic updates with data consistency guarantees</li> <li>Protection against partial-update scenarios during price volatility</li> <li>Single-transaction verification of data freshness</li> </ul> </li> <li> <p><strong>Combined value and amount tracking</strong> was implemented for:</p> <ul> <li>Enhanced resilience during high market volatility</li> <li>Ability to detect oracle manipulation by comparing historical value/amount ratios</li> <li>Clear audit trails for post-mortem analysis</li> </ul> </li> </ol> <h3 id="test-driven-design-decisions">Test-Driven Design Decisions</h3> <p>Our implementation testing significantly shaped the final design:</p> <ol> <li> <p><strong>Market Crash Simulation Tests</strong></p> <ul> <li>Tests simulate extreme scenarios (80% ETH price drop, 70% BTC price drop)</li> <li>Validates the system correctly identifies insolvency when ratios fall below critical thresholds</li> <li>Confirms proper functionality of emergency protocols during rapid market movements</li> </ul> </li> <li> <p><strong>Volatility Testing</strong></p> <ul> <li>Test suite subjects implementation to sinusoidal price movements</li> <li>Validates consistent health factor calculation across 5 distinct price points</li> <li>Confirms historical metrics are properly recorded with sequential timestamps</li> <li>Verifies that price volatility is accurately reflected in solvency ratios</li> </ul> </li> <li> <p><strong>Oracle Integration</strong></p> <ul> <li>Tests confirm proper authorization controls for price updates</li> <li>Validates calculation consistency across different token types</li> <li>Demonstrates resilience against unexpected price movements</li> </ul> </li> </ol> <h3 id="threshold-selection-methodology">Threshold Selection Methodology</h3> <p>The recommended threshold values (105%, 110%, 120%) were selected based on:</p> <ol> <li> <p><strong>Market Crash Testing</strong></p> <ul> <li>105% represents the critical threshold where recovery becomes unlikely</li> <li>Testing confirms this threshold successfully identifies insolvency scenarios</li> <li>System correctly triggers warnings at appropriate levels</li> </ul> </li> <li> <p><strong>Complex Portfolio Analysis</strong></p> <ul> <li>Tests with diverse portfolios (ETH, BTC, USDC, LP tokens, etc.)</li> <li>Complex liability structures (stablecoins + volatile assets)</li> <li>Thresholds provide appropriate buffer against normal market fluctuations</li> </ul> </li> <li> <p><strong>Gas Optimization vs. Precision</strong></p> <ul> <li>The selected ratio calculation method balances computational efficiency with accuracy</li> <li>Implementation uses fixed-point math for consistent results</li> <li>Storage optimizations maintain historical data while minimizing costs</li> </ul> </li> </ol> <h3 id="implementation-insights">Implementation Insights</h3> <p>Key insights from comprehensive implementation and testing:</p> <ol> <li> <p><strong>Efficient Asset Tracking</strong></p> <ul> <li>The parallel arrays approach for token data minimizes storage costs</li> <li>Implementation maintains constant-time lookups for critical operations</li> <li>Bounded array sizes prevent out-of-gas scenarios</li> </ul> </li> <li> <p><strong>Oracle Integration Patterns</strong></p> <ul> <li>Permissioned oracle design prevents manipulation</li> <li>Clean separation between price data and protocol logic</li> <li>Flexible design supports various oracle implementations</li> </ul> </li> <li> <p><strong>Risk Management System</strong></p> <ul> <li>Multi-tier alert system provides graduated responses to deteriorating conditions</li> <li>Historical metrics enable trend analysis across market cycles</li> <li>Verification functions support both on-chain and off-chain monitoring systems</li> </ul> </li> </ol> <p>These insights are derived from comprehensive testing covering market crashes, volatility scenarios, and complex asset portfolios.</p> <h3 id="mathematical-model">Mathematical Model</h3> <p>The solvency verification system is based on comprehensive mathematical models:</p> <h4 id="1-core-solvency-calculations">1. Core Solvency Calculations</h4> <p>$SR = (TA / TL) × 100$</p> <p>Where:</p> <ul> <li>$TA = \sum(A_i × P_i)$ // Total Assets</li> <li>$TL = \sum(L_i × P_i)$ // Total Liabilities</li> <li>$A_i$ = Amount of asset i</li> <li>$P_i$ = Price of asset i</li> <li>$L_i$ = Liability i</li> </ul> <h4 id="2-risk-adjusted-health-factor">2. Risk-Adjusted Health Factor</h4> <p>$HF = \frac{\sum(A_i × P_i × W_i)}{\sum(L_i × P_i × R_i)}$</p> <p>Where:</p> <ul> <li>$W_i$ = Risk weight of asset i $(0 &lt; W_i \leq 1)$</li> <li>$R_i$ = Risk factor for liability i $(R_i \geq 1)$</li> </ul> <h4 id="3-risk-metrics">3. Risk Metrics</h4> <h5 id="value-at-risk-var">Value at Risk (VaR)</h5> <p>$VaR(\alpha) = \mu - (\sigma × z(\alpha))$</p> <p>Where:</p> <ul> <li>$\mu$ = Expected return</li> <li>$\sigma$ = Standard deviation</li> <li>$z(\alpha)$ = z-value for confidence level $\alpha$</li> </ul> <h5 id="liquidity-coverage-ratio-lcr">Liquidity Coverage Ratio (LCR)</h5> <p>$LCR = \frac{HQLA}{TNCO} × 100$</p> <p>Where:</p> <ul> <li>HQLA = High Quality Liquid Assets</li> <li>TNCO = Total Net Cash Outflows (30 days)</li> </ul> <h4 id="4-system-health-index">4. System Health Index</h4> <p>$SI = \frac{SR × w_1 + LCR × w_2 + (1/\sigma) × w_3}{w_1 + w_2 + w_3}$</p> <p>Where:</p> <ul> <li>$w_1,w_2,w_3$ = Weighting factors</li> <li>$\sigma$ = System volatility</li> </ul> <h4 id="5-default-probability">5. Default Probability</h4> <p>$PD = N(-DD)$ $DD = \frac{ln(TA/TL) + (\mu - \sigma^2/2)T}{\sigma\sqrt{T}}$</p> <p>Where:</p> <ul> <li>DD = Distance to Default</li> <li>T = Time horizon</li> <li>N() = Standard normal distribution</li> </ul> <h3 id="risk-thresholds">Risk Thresholds</h3> <p>The following thresholds have been validated through extensive testing:</p> <table><thead><tr><th>Risk Level</th><th>Ratio Range</th><th>Action Required</th><th>Validation Status</th></tr></thead><tbody> <tr><td>CRITICAL</td><td>&lt; 105%</td><td>Emergency Stop</td><td>✅ Validated</td></tr> <tr><td>HIGH RISK</td><td>105% - 110%</td><td>Risk Alert</td><td>✅ Validated</td></tr> <tr><td>WARNING</td><td>110% - 120%</td><td>Monitor</td><td>✅ Validated</td></tr> <tr><td>HEALTHY</td><td>≥ 120%</td><td>Normal</td><td>✅ Validated</td></tr> </tbody></table> <p>Testing has confirmed that:</p> <ol> <li>The system correctly handles 50% market drops</li> <li>Ratios are calculated accurately in all scenarios</li> <li>State updates maintain consistency</li> <li>Ratio limits are effective for early detection</li> </ol> <p><img src="https://wg-eips.ritovision.com/7893/./assets/images/diagrams/risk-thresholds.svg" alt="risk-thresholds" /></p> <h3 id="risk-assessment-framework">Risk Assessment Framework</h3> <p>The standard implements a multi-tiered risk assessment system:</p> <ol> <li> <p>Primary Metrics:</p> <ul> <li>Base Solvency Ratio (SR)</li> <li>Risk-Adjusted Health Factor (HF)</li> <li>Liquidity Coverage Ratio (LCR)</li> </ul> </li> <li> <p>Threshold Levels:</p> </li> </ol> <p><img src="https://wg-eips.ritovision.com/7893/./assets/images/diagrams/threshold-levels.svg" alt="threshold-levels" /></p> <h3 id="oracle-integration-optional">Oracle Integration (Optional)</h3> <p>This standard intentionally leaves oracle implementation flexible. Protocols MAY implement price feeds in various ways:</p> <ol> <li> <p>Direct Integration</p> <ul> <li>Using existing oracle networks (Chainlink, API3, etc.)</li> <li>Custom price feed implementations</li> <li>Internal price calculations</li> </ul> </li> <li> <p>Aggregation Strategies</p> <ul> <li>Multiple oracle sources</li> <li>TWAP implementations</li> <li>Medianized price feeds</li> </ul> </li> </ol> <p><img src="https://wg-eips.ritovision.com/7893/./assets/images/diagrams/oracle-integration.svg" alt="oracle-integration" /></p> <h3 id="implementation-requirements">Implementation Requirements</h3> <ol> <li> <p>Asset Management:</p> <ul> <li>Real-time asset tracking</li> <li>Price feed integration</li> <li>Historical data maintenance</li> </ul> </li> <li> <p>Liability Tracking:</p> <ul> <li>Debt obligation monitoring</li> <li>Collateral requirement calculation</li> <li>Risk factor assessment</li> </ul> </li> <li> <p>Reporting System:</p> <ul> <li>Event emission for significant changes</li> <li>Threshold breach notifications</li> <li>Historical data access</li> </ul> </li> </ol> <h3 id="implementation-considerations">Implementation Considerations</h3> <h3 id="implementation-notes">Implementation Notes</h3> <p>Based on conducted tests, it is recommended:</p> <ol> <li> <p>Liability Management:</p> <ul> <li>Maintain constant liabilities during price updates</li> <li>Validate that liabilities are never 0 to avoid division by zero</li> <li>Update liabilities only when actual positions change</li> </ul> </li> <li> <p>Ratio Calculation:</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"> calculateRatio</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> assets</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> liabilities</span><span>)</span><span class="z-storage z-type"> pure</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"> if</span><span> (</span><span>liabilities </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> assets </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span class="z-keyword"> ?</span><span> RATIO_DECIMALS </span><span class="z-keyword">*</span><span class="z-constant"> 2</span><span class="z-keyword"> :</span><span> RATIO_DECIMALS</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>assets </span><span class="z-keyword">*</span><span> RATIO_DECIMALS</span><span>)</span><span class="z-keyword"> /</span><span> liabilities</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre></li> <li> <p>State Validation:</p> <ul> <li>Verify values before updating</li> <li>Maintain accurate history</li> <li>Emit events for significant changes</li> </ul> </li> <li> <p>Gas Considerations:</p> <ul> <li>Optimize history storage</li> <li>Batch updates for multiple tokens</li> <li>Limit array sizes in updates</li> </ul> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is compatible with existing DeFi protocols and requires no changes to existing token standards.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation provides a comprehensive example of the standard in action:</p> <h3 id="core-implementation-requirements">Core Implementation Requirements</h3> <p>Implementations of the <code>ISolvencyProof</code> interface should provide robust solvency monitoring with:</p> <ul> <li><strong>Advanced state management</strong> with atomic updates and timestamp tracking</li> <li><strong>Multi-layered security</strong> including access control, rate limiting, and circuit breakers</li> <li><strong>Historical data management</strong> with bounded storage and configurable retention</li> <li><strong>Oracle integration</strong> with consensus validation and staleness detection</li> <li><strong>Emergency response systems</strong> with automatic pausing and guardian controls</li> <li><strong>Comprehensive event emission</strong> for real-time monitoring and risk alerts</li> </ul> <h3 id="recommended-implementation-patterns">Recommended Implementation Patterns</h3> <h4 id="state-management-with-security-constants">State Management with Security Constants</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Security constants for production deployment</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> RATIO_DECIMALS </span><span class="z-keyword">=</span><span class="z-constant"> 10000</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> MIN_SOLVENCY_RATIO </span><span class="z-keyword">=</span><span class="z-constant"> 10500</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> CRITICAL_RATIO </span><span class="z-keyword">=</span><span class="z-constant"> 10200</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> WARNING_RATIO </span><span class="z-keyword">=</span><span class="z-constant"> 11000</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Enhanced security constants</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> MAX_PRICE_DEVIATION </span><span class="z-keyword">=</span><span class="z-constant"> 500</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 5%</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> MAX_TOKENS_PER_UPDATE </span><span class="z-keyword">=</span><span class="z-constant"> 50</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> DoS protection</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> STALENESS_THRESHOLD </span><span class="z-keyword">=</span><span class="z-constant"> 3600</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 1 hour</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> CIRCUIT_BREAKER_THRESHOLD </span><span class="z-keyword">=</span><span class="z-constant"> 2000</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 20%</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> UPDATE_COOLDOWN </span><span class="z-keyword">=</span><span class="z-constant"> 5</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 5 blocks</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> MAX_HISTORY_ENTRIES </span><span class="z-keyword">=</span><span class="z-constant"> 8760</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> ~1 year</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> MIN_ENTRY_INTERVAL </span><span class="z-keyword">=</span><span class="z-constant"> 3600</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 1 hour</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Role-based access control</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> ORACLE_ROLE </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;ORACLE_ROLE&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> EMERGENCY_ROLE </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;EMERGENCY_ROLE&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> ADMIN_ROLE </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;ADMIN_ROLE&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"> Enhanced state variables</span></span> <span class="giallo-l"><span>ProtocolAssets </span><span class="z-storage z-type">private</span><span> currentAssets</span><span>;</span></span> <span class="giallo-l"><span>ProtocolLiabilities </span><span class="z-storage z-type">private</span><span> currentLiabilities</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Multi-oracle price tracking</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">address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint256</span><span>)</span><span>)</span><span class="z-storage z-type"> public</span><span> oraclePrices</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> oracleLastUpdate</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> lastUpdateBlock</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Emergency controls</span></span> <span class="giallo-l"><span class="z-support">bool</span><span class="z-storage z-type"> public</span><span> emergencyPaused</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> public</span><span> pauseEndTime</span><span>;</span></span> <span class="giallo-l"><span class="z-support">address</span><span class="z-storage z-type"> public</span><span> emergencyGuardian</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Historical data with metadata</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> HistoricalMetric</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> timestamp</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> solvencyRatio</span><span>;</span></span> <span class="giallo-l"><span> ProtocolAssets assets</span><span>;</span></span> <span class="giallo-l"><span> ProtocolLiabilities liabilities</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> updatedBy</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>HistoricalMetric</span><span>[</span><span>]</span><span class="z-storage z-type"> private</span><span> metricsHistory</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> private</span><span> lastHistoricalEntry</span><span>;</span></span></code></pre><h4 id="advanced-security-features">Advanced Security Features</h4> <h5 id="access-control-system">Access Control System</h5> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Multi-role access control with backward compatibility</span></span> <span class="giallo-l"><span class="z-storage z-type">modifier</span><span class="z-entity z-name"> onlyOracle</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> assetOracles</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> ||</span><span class="z-entity z-name"> hasRole</span><span>(</span><span>ORACLE_ROLE</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Not authorized oracle&quot;</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-keyword">!</span><span>emergencyPaused </span><span class="z-keyword">||</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp </span><span class="z-keyword">&gt;</span><span> pauseEndTime</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Emergency paused&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-comment">//</span><span class="z-comment"> Rate limiting to prevent spam</span></span> <span class="giallo-l"><span class="z-storage z-type">modifier</span><span class="z-entity z-name"> rateLimited</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><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> lastUpdateBlock</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> +</span><span> UPDATE_COOLDOWN</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Update too frequent&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> lastUpdateBlock</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"> emit</span><span class="z-entity z-name"> RateLimitTriggered</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>number</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></code></pre><h5 id="circuit-breaker-implementation">Circuit Breaker Implementation</h5> <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"> _checkCircuitBreaker</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> previousTotal</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> newTotal</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>previousTotal </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-support"> uint256</span><span> assetChange </span><span class="z-keyword">=</span><span> newTotal </span><span class="z-keyword">&gt;</span><span> previousTotal</span></span> <span class="giallo-l"><span class="z-keyword"> ?</span><span> (</span><span>(</span><span>newTotal </span><span class="z-keyword">-</span><span> previousTotal</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> 10000</span><span>)</span><span class="z-keyword"> /</span><span> previousTotal</span></span> <span class="giallo-l"><span class="z-keyword"> :</span><span> (</span><span>(</span><span>previousTotal </span><span class="z-keyword">-</span><span> newTotal</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> 10000</span><span>)</span><span class="z-keyword"> /</span><span> previousTotal</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>assetChange </span><span class="z-keyword">&gt;</span><span> CIRCUIT_BREAKER_THRESHOLD</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> emergencyPaused </span><span class="z-keyword">=</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> pauseEndTime </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 class="z-constant"> 3600</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 1 hour pause</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> CircuitBreakerTriggered</span><span>(</span><span class="z-string">&quot;Large asset change&quot;</span><span>,</span></span> <span class="giallo-l"><span> assetChange</span><span>,</span><span> CIRCUIT_BREAKER_THRESHOLD</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> EmergencyPaused</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> pauseEndTime</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><h5 id="multi-oracle-consensus-validation">Multi-Oracle Consensus Validation</h5> <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"> _validatePriceConsensus</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> proposedPrice</span><span>)</span></span> <span class="giallo-l"><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 class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> activeOracles </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getActiveOracles</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>activeOracles</span><span>.</span><span>length </span><span class="z-keyword">&lt;</span><span class="z-constant"> 3</span><span>)</span><span class="z-keyword"> return</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"> Collect and validate prices from multiple oracles</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> prices </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> uint256</span><span>[](</span><span class="z-variable">activeOracles</span><span>.</span><span class="z-variable">length</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validPrices </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-keyword"> for</span><span> (</span><span class="z-support">uint256</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> activeOracles</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-keyword"> if</span><span> (</span><span>oraclePrices</span><span>[</span><span>activeOracles</span><span>[</span><span>i</span><span>]</span><span>]</span><span>[</span><span>token</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> prices</span><span>[</span><span>validPrices</span><span>]</span><span class="z-keyword"> =</span><span> oraclePrices</span><span>[</span><span>activeOracles</span><span>[</span><span>i</span><span>]</span><span>]</span><span>[</span><span>token</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> validPrices</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> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>validPrices </span><span class="z-keyword">&lt;</span><span class="z-constant"> 2</span><span>)</span><span class="z-keyword"> return</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 median and check deviation</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> median </span><span class="z-keyword">=</span><span class="z-entity z-name"> _calculateMedian</span><span>(</span><span>prices</span><span>,</span><span> validPrices</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> deviation </span><span class="z-keyword">=</span><span> proposedPrice </span><span class="z-keyword">&gt;</span><span> median</span></span> <span class="giallo-l"><span class="z-keyword"> ?</span><span> (</span><span>(</span><span>proposedPrice </span><span class="z-keyword">-</span><span> median</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> 10000</span><span>)</span><span class="z-keyword"> /</span><span> median</span></span> <span class="giallo-l"><span class="z-keyword"> :</span><span> (</span><span>(</span><span>median </span><span class="z-keyword">-</span><span> proposedPrice</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> 10000</span><span>)</span><span class="z-keyword"> /</span><span> median</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>deviation </span><span class="z-keyword">&gt;</span><span> MAX_PRICE_DEVIATION</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> PriceDeviationAlert</span><span>(</span><span>token</span><span>,</span><span> deviation</span><span>,</span><span> activeOracles</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> <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="historical-data-management">Historical Data Management</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"> getSolvencyHistory</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> startTime</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> endTime</span><span>)</span></span> <span class="giallo-l"><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 class="z-storage z-type"> memory</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 class="giallo-l"><span class="z-storage z-type"> ProtocolAssets</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>,</span><span class="z-storage z-type"> ProtocolLiabilities</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-comment"> Two-pass approach for gas optimization</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> count </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> metricsHistory</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-keyword"> if</span><span> (</span><span>metricsHistory</span><span>[</span><span>i</span><span>]</span><span>.</span><span>timestamp </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> startTime </span><span class="z-keyword">&amp;&amp;</span></span> <span class="giallo-l"><span> metricsHistory</span><span>[</span><span>i</span><span>]</span><span>.</span><span>timestamp </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> endTime</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> count</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>count </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-constant"> 100</span><span>)</span><span class="z-keyword"> break</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Gas limit protection</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"> Allocate exact size arrays</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> timestamps </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> uint256</span><span>[](</span><span class="z-variable">count</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> ratios </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> uint256</span><span>[](</span><span class="z-variable">count</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> ProtocolAssets</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> assets </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span> ProtocolAssets</span><span>[</span><span>]</span><span>(</span><span>count</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> ProtocolLiabilities</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> liabilities </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span> ProtocolLiabilities</span><span>[</span><span>]</span><span>(</span><span>count</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Populate arrays</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> index </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> metricsHistory</span><span>.</span><span>length </span><span class="z-keyword">&amp;&amp;</span><span> index </span><span class="z-keyword">&lt;</span><span> count</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-keyword"> if</span><span> (</span><span>metricsHistory</span><span>[</span><span>i</span><span>]</span><span>.</span><span>timestamp </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> startTime </span><span class="z-keyword">&amp;&amp;</span></span> <span class="giallo-l"><span> metricsHistory</span><span>[</span><span>i</span><span>]</span><span>.</span><span>timestamp </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> endTime</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> timestamps</span><span>[</span><span>index</span><span>]</span><span class="z-keyword"> =</span><span> metricsHistory</span><span>[</span><span>i</span><span>]</span><span>.</span><span>timestamp</span><span>;</span></span> <span class="giallo-l"><span> ratios</span><span>[</span><span>index</span><span>]</span><span class="z-keyword"> =</span><span> metricsHistory</span><span>[</span><span>i</span><span>]</span><span>.</span><span>solvencyRatio</span><span>;</span></span> <span class="giallo-l"><span> assets</span><span>[</span><span>index</span><span>]</span><span class="z-keyword"> =</span><span> metricsHistory</span><span>[</span><span>i</span><span>]</span><span>.</span><span>assets</span><span>;</span></span> <span class="giallo-l"><span> liabilities</span><span>[</span><span>index</span><span>]</span><span class="z-keyword"> =</span><span> metricsHistory</span><span>[</span><span>i</span><span>]</span><span>.</span><span>liabilities</span><span>;</span></span> <span class="giallo-l"><span> index</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> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>timestamps</span><span>,</span><span> ratios</span><span>,</span><span> assets</span><span>,</span><span> liabilities</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"> getHistoricalDataInfo</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"> uint256</span><span class="z-variable"> totalEntries</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> maxEntries</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> oldestTimestamp</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> newestTimestamp</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> minInterval</span><span>)</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> totalEntries </span><span class="z-keyword">=</span><span> metricsHistory</span><span>.</span><span>length</span><span>;</span></span> <span class="giallo-l"><span> maxEntries </span><span class="z-keyword">=</span><span> MAX_HISTORY_ENTRIES</span><span>;</span></span> <span class="giallo-l"><span> minInterval </span><span class="z-keyword">=</span><span> MIN_ENTRY_INTERVAL</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>totalEntries </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> oldestTimestamp </span><span class="z-keyword">=</span><span> metricsHistory</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span>timestamp</span><span>;</span></span> <span class="giallo-l"><span> newestTimestamp </span><span class="z-keyword">=</span><span> metricsHistory</span><span>[</span><span>totalEntries </span><span class="z-keyword">-</span><span class="z-constant"> 1</span><span>]</span><span>.</span><span>timestamp</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> (</span><span>totalEntries</span><span>,</span><span> maxEntries</span><span>,</span><span> oldestTimestamp</span><span>,</span></span> <span class="giallo-l"><span> newestTimestamp</span><span>,</span><span> minInterval</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="emergency-response-system">Emergency Response System</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"> emergencyPause</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyEmergencyGuardian</span><span> {</span></span> <span class="giallo-l"><span> emergencyPaused </span><span class="z-keyword">=</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> pauseEndTime </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 class="z-constant"> 4</span><span class="z-keyword"> *</span><span class="z-constant"> 3600</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 4 hour default</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> EmergencyPaused</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> pauseEndTime</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"> emergencyUnpause</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyEmergencyGuardian</span><span> {</span></span> <span class="giallo-l"><span> emergencyPaused </span><span class="z-keyword">=</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span> pauseEndTime </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> EmergencyUnpaused</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">function</span><span class="z-entity z-name"> getEmergencyStatus</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"> bool</span><span class="z-variable"> isPaused</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> endTime</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> guardian</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>emergencyPaused</span><span>,</span><span> pauseEndTime</span><span>,</span><span> emergencyGuardian</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="gas-optimization-strategies">Gas Optimization Strategies</h3> <h4 id="bounded-operations">Bounded Operations</h4> <ul> <li><strong>Maximum array sizes</strong> (50 tokens per update) to prevent out-of-gas</li> <li><strong>Historical data pagination</strong> (max 100 entries per query)</li> <li><strong>Efficient storage patterns</strong> with bounded retention periods</li> </ul> <h4 id="storage-optimization">Storage Optimization</h4> <ul> <li><strong>Circular buffer approach</strong> for historical data rotation</li> <li><strong>Rate-limited historical entries</strong> (minimum 1-hour intervals)</li> <li><strong>Compact data structures</strong> minimizing storage overhead</li> </ul> <h3 id="testing-and-validation-requirements">Testing and Validation Requirements</h3> <h4 id="comprehensive-test-coverage">Comprehensive Test Coverage</h4> <ul> <li><strong>Mathematical precision</strong> validation for ratio calculations</li> <li><strong>Security feature testing</strong> (access control, rate limiting, circuit breakers)</li> <li><strong>Oracle reliability testing</strong> under various market conditions</li> <li><strong>Gas consumption analysis</strong> with stress testing</li> <li><strong>Emergency scenario simulation</strong> with pause/unpause cycles</li> </ul> <h4 id="production-deployment-requirements">Production Deployment Requirements</h4> <p>Production implementations should ensure:</p> <ul> <li>Multi-oracle consensus mechanism implemented and tested</li> <li>Circuit breaker triggers validated with historical data</li> <li>Rate limiting prevents spam without blocking legitimate updates</li> <li>Emergency pause/unpause mechanisms tested with time delays</li> <li>Gas optimization prevents DoS while maintaining functionality</li> <li>Access controls follow principle of least privilege</li> <li>Historical data storage bounded and efficient</li> <li>Security parameters documented and transparent</li> </ul> <h3 id="integration-patterns">Integration Patterns</h3> <h4 id="oracle-integration">Oracle Integration</h4> <ul> <li><strong>Primary oracle feeds</strong> (Chainlink, API3) with fallback mechanisms</li> <li><strong>TWAP integration</strong> for manipulation resistance</li> <li><strong>Staleness detection</strong> with automatic fallback to secondary oracles</li> </ul> <h4 id="liquidation-system-optional-enhancement">Liquidation System (Optional Enhancement)</h4> <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"> LiquidationConfig</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> maxLiquidationRatio</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Max % liquidatable</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> liquidationBonus</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Liquidator bonus</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> minHealthFactor</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Minimum health factor</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> maxSlippage</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Slippage tolerance</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isActive</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"> safeLiquidation</span><span>(</span><span class="z-support">address</span><span class="z-variable"> protocol</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> user</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> debtAmount</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> expectedCollateral</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> maxSlippage</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">uint256</span><span class="z-variable"> actualCollateral</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> liquidationBonus</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Comprehensive liquidation logic with health factor validation</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Slippage protection and bonus calculation</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Position updates and event emission</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This implementation demonstrates production-ready patterns for DeFi protocol solvency monitoring with enterprise-grade security, gas optimization, and comprehensive risk management.</p> <h2 id="security-considerations">Security Considerations</h2> <p>When implementing solvency monitoring for DeFi protocols, security isn't optional—it's essential. We've learned hard lessons from protocol failures, oracle manipulation attacks, and market crashes. This section covers the practical security measures you need to implement, drawn from what actually works in production systems like Aave, Compound, and MakerDAO.</p> <h3 id="oracle-security-implementation-requirements">Oracle Security - Implementation Requirements</h3> <h4 id="price-feed-validation">Price Feed Validation</h4> <ul> <li><strong>Minimum 3 independent oracle sources</strong> with median aggregation to prevent single points of failure</li> <li><strong>Deviation threshold checks:</strong> Reject price updates exceeding 5% difference between sources</li> <li><strong>Staleness validation:</strong> ETH/USD and major crypto pairs should use 1-hour maximum staleness (3600 seconds)</li> <li><strong>Circuit breaker integration:</strong> Pause solvency updates when price movements exceed 20% in single block</li> </ul> <p>Implementation patterns for price validation should include median calculation, deviation checks, and appropriate error handling.</p> <p><strong>Real-world reference:</strong> Chainlink's Feed Registry and Aave's AaveOracle provide solid patterns for oracle integration.</p> <h4 id="twap-integration">TWAP Integration</h4> <ul> <li><strong>30-minute minimum windows</strong> for manipulation resistance (based on Uniswap V3 security analysis)</li> <li><strong>Minimum $1-5M liquidity</strong> in reference pools for oracle reliability</li> <li><strong>Combined validation:</strong> Primary Chainlink feeds with Uniswap V3 TWAP backup verification</li> </ul> <h4 id="oracle-failure-handling">Oracle Failure Handling</h4> <p>Implementations should include fallback mechanisms for oracle failures, including timestamp validation, secondary oracle integration, and graceful degradation patterns.</p> <h3 id="access-control-specific-implementation">Access Control - Specific Implementation</h3> <h4 id="role-based-permissions">Role-Based Permissions</h4> <p>Implementations should use established access control patterns such as OpenZeppelin's AccessControl for role management, including oracle roles, emergency roles, and administrative functions.</p> <h4 id="rate-limiting-implementation">Rate Limiting Implementation</h4> <ul> <li><strong>Maximum 1 update per 5 blocks</strong> per authorized oracle to prevent spam attacks</li> <li><strong>Daily update limits:</strong> 288 updates per day (every 5 minutes) for high-frequency protocols</li> <li><strong>Emergency cooldowns:</strong> 1-hour minimum between emergency pause activations</li> </ul> <p>Rate limiting should be implemented using block-based cooldowns and per-oracle tracking.</p> <h4 id="multi-signature-requirements">Multi-signature Requirements</h4> <ul> <li>3/5 multisig for parameter changes (threshold updates, oracle management)</li> <li>4/7 multisig for critical upgrades (we borrowed this from Compound V3)</li> <li>Separate emergency pause authority from main governance (Aave's Guardian model works well here)</li> </ul> <h3 id="risk-management-concrete-parameters">Risk Management - Concrete Parameters</h3> <h4 id="threshold-calibration-with-production-values">Threshold Calibration with Production Values</h4> <table><thead><tr><th>Risk Level</th><th>Solvency Ratio</th><th>Liquidation Bonus</th><th>Close Factor</th><th>Implementation</th></tr></thead><tbody> <tr><td>CRITICAL</td><td>&lt; 105%</td><td>10-15%</td><td>100%</td><td>Emergency pause all operations</td></tr> <tr><td>HIGH_RISK</td><td>105% - 110%</td><td>7-10%</td><td>75%</td><td>Restrict new borrowing</td></tr> <tr><td>WARNING</td><td>110% - 120%</td><td>5-7%</td><td>50%</td><td>Enhanced monitoring</td></tr> <tr><td>HEALTHY</td><td>≥ 120%</td><td>5%</td><td>50%</td><td>Normal operations</td></tr> </tbody></table> <h4 id="alert-system-implementation">Alert System Implementation</h4> <p>Risk threshold monitoring should include graduated alerts (CRITICAL, HIGH_RISK, WARNING) with appropriate automated responses.</p> <h4 id="historical-data-protection">Historical Data Protection</h4> <ul> <li><strong>Immutable storage patterns</strong> to prevent historical data manipulation</li> <li><strong>Checksum validation</strong> for stored historical ratios using merkle trees</li> <li><strong>Maximum storage limits:</strong> 8760 hourly records (1 year) to prevent unbounded growth</li> </ul> <h3 id="emergency-response-mechanisms">Emergency Response Mechanisms</h3> <h4 id="circuit-breaker-integration">Circuit Breaker Integration</h4> <p>Circuit breaker mechanisms should monitor for dramatic value changes and automatically pause operations when thresholds are exceeded. Implementation should include emergency pause states, time-based recovery, and appropriate event emission.</p> <ul> <li><strong>Automatic pause triggers:</strong> Oracle deviation &gt;20%, liquidity drop &gt;50% in 1 hour</li> <li><strong>Initial pause duration:</strong> 1-4 hours with exponential backoff for repeated triggers</li> <li><strong>Gradual resume:</strong> 25% → 50% → 75% → 100% capacity with 30-minute monitoring between phases</li> </ul> <h4 id="time-delays-for-critical-operations">Time Delays for Critical Operations</h4> <ul> <li><strong>Protocol upgrades:</strong> 7 days (604,800 seconds) following MakerDAO governance pattern</li> <li><strong>Threshold parameter changes:</strong> 48 hours (172,800 seconds)</li> <li><strong>Oracle authority changes:</strong> 24 hours (86,400 seconds) with immediate emergency override</li> </ul> <h3 id="gas-optimization-security">Gas Optimization Security</h3> <h5 id="bounded-operations-1">Bounded Operations</h5> <p>Implementations should enforce reasonable limits on array sizes, historical data storage, and operation complexity to prevent denial-of-service attacks and ensure predictable gas consumption.</p> <h5 id="dos-attack-prevention">DoS Attack Prevention</h5> <ul> <li><strong>Maximum 50 tokens per update</strong> to prevent out-of-gas scenarios</li> <li><strong>Pagination for historical queries</strong> with max 100 records per call</li> <li><strong>Input validation:</strong> Reject empty arrays, validate array length consistency</li> <li><strong>Reentrancy protection:</strong> Use OpenZeppelin's ReentrancyGuard for all external calls</li> </ul> <h3 id="integration-security-patterns">Integration Security Patterns</h3> <h4 id="liquidation-protection-pattern">Liquidation Protection Pattern</h4> <blockquote> <p><strong>Note:</strong> This is a recommended integration pattern for protocols implementing this ERC. The core solvency monitoring contract focuses on solvency monitoring; liquidation logic should be implemented in the consuming protocol.</p> </blockquote> <p>Liquidation integrations should include health factor validation, partial liquidation limits, and slippage protection mechanisms.</p> <ul> <li><strong>Health factor buffers:</strong> 110% warning threshold before 105% liquidation</li> <li><strong>Partial liquidation limits:</strong> Maximum 50% of debt in single transaction</li> <li><strong>Slippage protection:</strong> 3% maximum slippage for automated liquidations</li> </ul> <h3 id="validation-and-testing-requirements">Validation and Testing Requirements</h3> <h4 id="stress-testing-scenarios">Stress Testing Scenarios</h4> <ul> <li><strong>50% market crash simulation</strong> with proper threshold triggers</li> <li><strong>Oracle manipulation attempts</strong> with 20%+ false price movements</li> <li><strong>High-frequency update scenarios</strong> testing rate limiting effectiveness</li> <li><strong>Network congestion testing</strong> with increased gas prices</li> </ul> <h4 id="audit-requirements">Audit Requirements</h4> <ul> <li><strong>Formal verification</strong> of solvency calculation logic</li> <li><strong>Oracle integration testing</strong> across multiple price feed providers</li> <li><strong>Emergency scenario testing</strong> including pause/unpause cycles</li> <li><strong>Gas consumption analysis</strong> for all operations under stress conditions</li> </ul> <h4 id="production-deployment-requirements-1">Production Deployment Requirements</h4> <p>Production implementations should ensure:</p> <ul> <li>Multi-oracle consensus mechanism implemented and tested</li> <li>Circuit breaker triggers validated with historical data</li> <li>Rate limiting prevents spam without blocking legitimate updates</li> <li>Emergency pause/unpause mechanisms tested with time delays</li> <li>Gas optimization prevents DoS while maintaining functionality</li> <li>Access controls follow principle of least privilege</li> <li>Historical data storage bounded and efficient</li> </ul> <p>These security considerations are based on production implementations from Aave V3, Compound V3, MakerDAO, and Synthetix protocols, incorporating lessons learned from actual security incidents and governance responses in the DeFi ecosystem. The specific parameters and thresholds have been validated through extensive testing scenarios including market crashes, oracle manipulation attempts, and high-frequency trading conditions.</p> <h3 id="production-validated-security-parameters">Production-Validated Security Parameters</h3> <p>All security parameters have been validated against real-world DeFi protocols:</p> <table><thead><tr><th>Parameter</th><th>Value</th><th>Reference</th><th>Validation Status</th></tr></thead><tbody> <tr><td><strong>Critical Ratio</strong></td><td>102%</td><td>Aave V3 WBTC liquidation threshold</td><td>✅ Production-tested</td></tr> <tr><td><strong>Min Solvency Ratio</strong></td><td>105%</td><td>Compound V3 close factor trigger</td><td>✅ Production-tested</td></tr> <tr><td><strong>Warning Ratio</strong></td><td>110%</td><td>MakerDAO emergency shutdown threshold</td><td>✅ Production-tested</td></tr> <tr><td><strong>Price Deviation</strong></td><td>5%</td><td>Chainlink deviation standard</td><td>✅ Industry standard</td></tr> <tr><td><strong>Staleness Threshold</strong></td><td>1 hour</td><td>Chainlink ETH/USD heartbeat</td><td>✅ Industry standard</td></tr> <tr><td><strong>Circuit Breaker</strong></td><td>20%</td><td>NYSE/circuit breaker standard</td><td>✅ Regulatory compliant</td></tr> <tr><td><strong>Rate Limiting</strong></td><td>5 blocks</td><td>~1 minute (12s avg block time)</td><td>✅ DoS protection</td></tr> <tr><td><strong>Gas Optimization</strong></td><td>50 token max</td><td>30M gas block limit consideration</td><td>✅ Network compliant</td></tr> </tbody></table> <p><strong>Security Documentation:</strong> Security validation reports and fork testing guides are available for detailed parameter validation and mainnet validation instructions.</p> <p><strong>Test Coverage:</strong> Implementations should include comprehensive test suites covering core functionality, security features, and edge cases. Every security-critical code path should be tested.</p> <p><strong>Testing Approach:</strong> Test contracts should simulate attack scenarios and consensus mechanisms. They should provide comprehensive coverage of potential attack vectors and edge cases that protocols implementing this ERC should be prepared to handle.</p> <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-23T00:00:00+00:00 2026-02-11T14:48:26+00:00 Lucas Picollohttps://github.com/pikonha Alex Nettohttps://github.com/alextnetto Nick Johnsonhttps://github.com/arachnid https://wg-eips.ritovision.com/7884/

A protocol that enables smart contracts to redirect write operations to external systems.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a protocol that enables smart contracts to redirect write operations to external systems. The protocol defines a standardized way for contracts to indicate that an operation should be handled by either a contract deployed to an L2 chain, to the L1, or an off-chain database, providing an entry point for easy developer experience and client implementations.</p> <h2 id="motivation">Motivation</h2> <p>As the Ethereum ecosystem grows, there is an increasing need for efficient ways to manage data storage across different layers and systems.</p> <p>This protocol addresses these challenges by:</p> <ul> <li>Providing a gas-efficient way to determine operation handlers through view functions</li> <li>Enabling seamless integration with L2 solutions and off-chain databases</li> <li>Maintaining strong security guarantees through typed signatures and standardized interfaces</li> </ul> <h2 id="specification">Specification</h2> <h3 id="core-components">Core Components</h3> <p>The protocol consists of three main components:</p> <ol> <li>A view function named interface <code>getOperationHandler</code> for determining operation handlers that can be one of the following types: a. <code>OperationHandledOnchain</code> for on-chain handlers b. <code>OperationHandledOffchain</code> for off-chain handlers through a gateway</li> <li>A standardized message format for off-chain storage authorization</li> </ol> <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"> OperationRouter</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"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Error to raise when an encoded function that is not supported</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> is received on the getOperationHandler function</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"> FunctionNotSupported</span><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">@dev</span><span class="z-comment"> Error to raise when mutations are being deferred onchain</span></span> <span class="giallo-l"><span class="z-comment"> * that being the layer 1 or a layer 2</span></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"> OperationHandledOnchain</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> 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">@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</span></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 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 for off-chain storage authorization</span></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 original ABI encoded function call</span></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"> expirationTimestamp</span><span class="z-comment"> The timestamp at which the mutation will expire.</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"> bytes</span><span> data</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"> 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">@dev</span><span class="z-comment"> Error to raise when mutations are being deferred to an Offchain entity</span></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</span></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 original ABI encoded function call along with authorization context</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"> OperationHandledOffchain</span><span>(</span></span> <span class="giallo-l"><span> DomainData sender</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> url</span><span>,</span></span> <span class="giallo-l"><span> MessageData 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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Determines the appropriate handler for an encoded function call</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> encodedFunction</span><span class="z-comment"> The ABI encoded function call</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"> getOperationHandler</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> encodedFunction</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></span> <span class="giallo-l"></span></code></pre> <p>The onchain flow is specified as follows:</p> <p><img src="https://wg-eips.ritovision.com/7884/./assets/d1.svg" alt="" /></p> <p>It is important to notice that the <code>getOperationHandler</code> relies on the given argument, the encoded function, to specify which contract will the request be redirected to, therefore, it is unable to address <code>multicall</code> transactions that could lead to different destination contracts. That means that <code>multicall</code> that is known will be redirected to different contracts should be handled in a sequential way by first calling the <code>getOperationHandler</code> and then making the actual transaction to the returned contract.</p> <h4 id="database-flow">Database flow</h4> <p>The HTTP request made to the gateway follows the same standard proposed by the <a href="https://wg-eips.ritovision.com/3668/">EIP-3668</a> where the URL receives <code>/{sender}/{data}.json</code> enabling an API to behave just like an smart contract would. However, the <a href="https://wg-eips.ritovision.com/712/">EIP-712 Typed Signature</a> was introduced to enable authentication.</p> <p><img src="https://wg-eips.ritovision.com/7884/./assets/d2.svg" alt="" /></p> <h3 id="implementation-example">Implementation Example</h3> <p>The contract deployed to the L1 MUST implement the <code>getOperationHandler</code> to act as a router redirecting the requests to the respective handler.</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"> OperationRouterExample</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getOperationHandler</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> encodedFunction</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 class="z-support"> bytes4</span><span> selector </span><span class="z-keyword">=</span><span class="z-support"> bytes4</span><span>(</span><span>encodedFunction</span><span>[</span><span class="z-keyword">:</span><span class="z-constant">4</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>selector </span><span class="z-keyword">==</span><span class="z-support"> bytes4</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-string">&quot;setText(bytes32, string)&quot;</span><span>)</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> OperationHandledOffchain</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> DomainData</span><span>(</span></span> <span class="giallo-l"><span class="z-string"> &quot;IdentityResolver&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;1&quot;</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 class="giallo-l"><span class="z-string"> &quot;https://api.example.com/profile&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> MessageData</span><span>(</span></span> <span class="giallo-l"><span> encodedFunction</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-variable z-language"> block</span><span>.</span><span>timestamp </span><span class="z-keyword">+</span><span class="z-constant"> 1</span><span class="z-constant"> hours</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 class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>selector </span><span class="z-keyword">==</span><span class="z-support"> bytes4</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-string">&quot;setAddress(bytes32,address)&quot;</span><span>)</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> OperationHandledOnchain</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> 10</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>(</span><span class="z-constant">0x123</span><span>.</span><span>.</span><span>.</span><span class="z-constant">789</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></span> <span class="giallo-l"></span></code></pre> <p>The client implementation would look as follows:</p> <pre class="giallo z-code"><code data-lang="tsx"><span class="giallo-l"><span class="z-keyword"> try</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> calldata</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span> functionName</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">setText</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> abi</span><span>,</span></span> <span class="giallo-l"><span> args</span><span>:</span><span> [</span><span class="z-variable z-other">key</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"> address</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 class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> client</span><span>.</span><span class="z-entity z-name">readContract</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> functionName</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">getOperationHandler</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> abi</span><span>,</span></span> <span class="giallo-l"><span> args</span><span>:</span><span> [</span><span class="z-entity z-name">encodeFunctionData</span><span>(</span><span class="z-variable z-other">calldata</span><span>)</span><span>]</span><span>,</span></span> <span class="giallo-l"><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">err</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"> data</span><span class="z-keyword"> =</span><span class="z-entity z-name"> getRevertErrorData</span><span>(</span><span class="z-variable z-other">err</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> switch</span><span> (</span><span class="z-variable z-other">data</span><span>?.</span><span class="z-variable z-other">errorName</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">OperationHandledOffchain</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> [</span><span class="z-variable z-other z-constant">domain</span><span>,</span><span class="z-variable z-other z-constant"> url</span><span>,</span><span class="z-variable z-other z-constant"> message</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-other"> errorResult</span><span>.</span><span class="z-variable z-other">args</span><span class="z-keyword"> as</span><span> [</span></span> <span class="giallo-l"><span class="z-entity z-name"> DomainData</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> MessageData</span><span>,</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-entity z-name"> handleDBStorage</span><span>(</span><span>{</span><span class="z-variable z-other"> domain</span><span>,</span><span class="z-variable z-other"> url</span><span>,</span><span class="z-variable z-other"> message</span><span>,</span><span class="z-variable z-other"> signer</span><span> }</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">OperationHandledOnchain</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> [</span><span class="z-variable z-other z-constant">chainId</span><span>,</span><span class="z-variable z-other z-constant"> contractAddress</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-other"> data</span><span>.</span><span class="z-variable z-other">args</span><span class="z-keyword"> as</span><span> [</span><span class="z-support">bigint</span><span>,</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> <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"> l2Client</span><span class="z-keyword"> =</span><span class="z-entity z-name"> createPublicClient</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> chain</span><span>:</span><span class="z-entity z-name"> getChain</span><span>(</span><span class="z-entity z-name">Number</span><span>(</span><span class="z-variable z-other">chainId</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> transport</span><span>:</span><span class="z-entity z-name"> http</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>.</span><span class="z-entity z-name">extend</span><span>(</span><span class="z-variable z-other">walletActions</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 z-other z-constant"> request</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> l2Client</span><span>.</span><span class="z-entity z-name">simulateContract</span><span>(</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> ...</span><span class="z-variable z-other">calldata</span><span>,</span></span> <span class="giallo-l"><span> address</span><span>:</span><span class="z-variable z-other"> contractAddress</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> l2Client</span><span>.</span><span class="z-entity z-name">writeContract</span><span>(</span><span class="z-variable z-other">request</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-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">&#39;</span><span class="z-string">error registering domain: </span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> {</span><span class="z-variable z-other"> err</span><span> }</span><span>)</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The standard aims to enable offchain writing operations, designed to be a complement for the CCIP-Read (<a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a>) which is already widely adopted by the community.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backward compatible as it:</p> <ul> <li>Introduces new interfaces that don't conflict with existing ones</li> <li>Uses view functions to gather offchain information</li> <li>Can be implemented alongside existing storage patterns</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <h3 id="handler-validation">Handler Validation</h3> <p>Off-chain handlers must:</p> <ul> <li>Verify EIP-712 signatures</li> <li>Implement proper access controls</li> <li>Handle concurrent modifications safely</li> </ul> <h3 id="general-recommendations">General Recommendations</h3> <ul> <li>Implement rate limiting for off-chain handlers</li> <li>Use secure transport (HTTPS) for off-chain communications</li> <li>Monitor for unusual patterns that might indicate attacks</li> <li>Implement proper error handling for failed transactions</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> 2025-01-22T00:00:00+00:00 2026-02-11T14:48:25+00:00 Kumar Anirudhahttps://github.com/anistark https://wg-eips.ritovision.com/7866/

Decentralised Interoperable User Identity with segmented Avatars per DApp Profile

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a standard for decentralised, interoperable user profiles known as Decentralised Profiles. Profiles are implemented as <strong>Soul Bound Tokens (SBTs)</strong> that are immutable, non-transferable, and tied to unique identifiers across multiple blockchain networks. The standard provides a unified structure for user metadata, including dApp-specific customisation, default profiles, and seamless cross-chain compatibility. Profiles can be leveraged for identity management, reputation systems, and personalised dApp experiences.</p> <h2 id="motivation">Motivation</h2> <p>Existing solutions for decentralised identity and user profiles lack cross-chain compatibility, dApp-specific customisation, and standardisation. A unified approach is essential to:</p> <ol> <li>Facilitate interoperable profiles across all chains.</li> <li>Leverage the immutability and non-transferability of SBTs for secure identities.</li> <li>Enable dApp-specific customisations, such as unique avatars.</li> <li>Provide a robust, standards-based alternative to centralised solutions like Gravatar.</li> <li>Ensure user control and decentralisation with profiles stored on IPFS/Arweave.</li> <li>A common standard for Decentralised Identity that can be used across all chains.</li> <li>Act as a Digital Passport for users, enabling seamless decentralised verification and authentication.</li> </ol> <h2 id="specification">Specification</h2> <h3 id="unique-profile-identifiers">Unique Profile Identifiers</h3> <h4 id="decentralised-profile">Decentralised Profile</h4> <p>Each profile is identified by:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&lt;username&gt;@&lt;network_slug&gt;.soul</span></span></code></pre> <ul> <li><code>username</code>: User-defined, chain-unique string.</li> <li><code>network_slug</code>: Short identifier for the chain (e.g., <code>eth</code>, <code>polygon</code>, <code>xion</code>).</li> <li><code>soul</code>: Fixed suffix indicating soul bound token.</li> </ul> <p>Example: <code>john@eth.soul</code> <code>alice@polygon.soul</code></p> <h4 id="decentralised-identifier-did">Decentralised Identifier (DID)</h4> <p>Each profile is tied to a DID:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>did:&lt;chain&gt;:&lt;address&gt;</span></span></code></pre> <p>Example: <code>did:ethereum:0x123...</code> <code>did:xion:xion1abc...</code></p> <h3 id="metadata-structure">Metadata Structure</h3> <p>The profile metadata structure is designed to balance extensibility, usability, and compatibility with decentralized storage systems like IPFS. Metadata will adhere to the following schema:</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 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">UserProfile</span><span class="z-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">username</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 unique handle of the user.</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">avatar</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">IPFS URI pointing to the user&#39;s main avatar image.</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">bio</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">Short description or biography of the user.</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">website</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">Personal or professional website of the user.</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">socials</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">User&#39;s social links.</span><span class="z-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">twitter</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">URL to the user&#39;s Twitter profile.</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">github</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">URL to the user&#39;s GitHub profile.</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">twitter</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">github</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">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</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_avatar_visibility</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">public</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">private</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">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Default visibility setting for the main avatar.</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">dapp_avatars</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">Mapping of DApp addresses to their custom avatars and visibility settings.</span><span class="z-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">^0x[a-fA-F0-9]{40}$</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">avatar</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">IPFS URI for the DApp-specific avatar.</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">visibility</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">public</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">private</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">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Visibility setting for this avatar.</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">avatar</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">visibility</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">additionalProperties</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 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 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">username</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">avatar</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">bio</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">website</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">socials</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">default_avatar_visibility</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">dapp_avatars</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">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Here's an example using the structure 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">username</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">batman</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">avatar</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ipfs://QmExampleMainAvatarCID</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">bio</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Blockchain enthusiast and builder.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">website</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://anirudha.dev</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">socials</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">twitter</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://twitter.com/kranirudha</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">github</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://github.com/anistark</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_avatar_visibility</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">public</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">dapp_avatars</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">0xDAppAddress1abcdefabcdefabcdefabcdefabcdefabcd</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">avatar</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ipfs://QmExampleAvatar1CID</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">visibility</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">private</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">0xDAppAddress2abcdefabcdefabcdefabcdefabcdefabcd</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">avatar</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ipfs://QmExampleAvatar2CID</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">visibility</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">public</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><h4 id="access-control">Access Control</h4> <ol> <li><strong>Default Avatar Visibility</strong>: Users can set their default avatar visibility as public or private.</li> <li><strong>dApp-Specific Avatar Visibility</strong>: Each dApp-specific avatar can also have its visibility set to public or private.</li> </ol> <p><strong>Visibility Logic</strong>:</p> <ul> <li>If an avatar is public, it is retrievable by any external caller.</li> <li>If an avatar is private, only the user can retrieve it. Other callers will get an encoded response alongwith error message.</li> </ul> <h3 id="dapp-specific-avatar-customisation">dApp-Specific Avatar Customisation</h3> <ul> <li>Users can assign dApp-specific avatars or metadata.</li> <li>If no dApp-specific customisation exists, the default avatar applies.</li> </ul> <h2 id="rationale">Rationale</h2> <p>The design of the Decentralised Profile Standard was guided by the need for a unified, interoperable user profile system that can operate seamlessly across all blockchain networks. Current solutions, such as ENS profiles or Gravatar, either lack cross-chain functionality, are centralised, or do not allow users to customise profiles for specific dApps. This standard addresses these shortcomings while ensuring simplicity, security, and scalability.</p> <h3 id="design-decisions">Design Decisions</h3> <ol> <li> <p><strong>Decentralised Identifiers (DIDs)</strong></p> <ul> <li>Using the <code>did:&lt;chain&gt;:&lt;address&gt;</code> format provides a globally unique identifier for profiles. This aligns with the decentralised identity movement and ensures compatibility with broader DID frameworks.</li> </ul> </li> <li> <p><strong>Decentralised Profile</strong></p> <ul> <li>The profile format (<code>username@networkslug.soul</code>) makes profiles human-readable and chain-specific while maintaining a universal structure. The <code>.soul</code> suffix clearly identifies profiles compliant with this standard.</li> </ul> </li> <li> <p><strong>dApp-Specific Avatars</strong></p> <ul> <li>Allowing users to assign dApp-specific avatars caters to personalisation and enhances the user experience. It supports scenarios where users may want different representations or metadata for different applications.</li> </ul> </li> <li> <p><strong>Soul Bound Tokens (SBTs)</strong></p> <ul> <li>Leveraging SBTs ensures that profiles are non-transferable, reinforcing the concept of identity ownership. SBTs prevent profiles from being sold or hijacked, making them ideal for reputation-based systems.</li> </ul> </li> <li> <p><strong>Registry and Resolver Architecture</strong></p> <ul> <li>This architecture was chosen for its extensibility and proven track record, as seen in ENS. It separates the management of profile identifiers (Registry) from the resolution of metadata (Resolver), making upgrades and integrations straightforward.</li> </ul> </li> <li> <p><strong>Compatibility with Existing Standards</strong></p> <ul> <li>The profile standard integrates with <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> for interface detection and can complement ENS or other naming systems, fostering interoperability rather than competition.</li> </ul> </li> <li> <p><strong>Default and dApp-Specific Metadata</strong></p> <ul> <li>The inclusion of both default and dApp-specific metadata ensures flexibility. If dApp-specific metadata is not set, the default profile seamlessly applies, reducing friction for developers and users.</li> </ul> </li> <li> <p><strong>On-Chain Data Minimisation</strong></p> <ul> <li>Metadata is stored off-chain (e.g., IPFS or Arweave) to minimise gas costs and support scalable operations. Only URIs and pointers are stored on-chain.</li> </ul> </li> <li> <p><strong>Access Control</strong></p> <ul> <li>Users have complete control over avatar visibility, catering to privacy preferences.</li> <li>Specific dApp-based customizations ensure fine-grained control.</li> </ul> </li> <li> <p><strong>dApp Identification</strong></p> </li> </ol> <ul> <li>Requiring dApps to be identified by an address ensures traceability and security.</li> </ul> <ol start="11"> <li><strong>Extensibility</strong></li> </ol> <ul> <li>Adding metadata fields or new visibility levels does not disrupt the standard.</li> <li>Profiles can remain lightweight while supporting future scalability.</li> </ul> <ol start="12"> <li><strong>Security</strong></li> </ol> <ul> <li>Access control minimizes the risk of sensitive data exposure.</li> <li>Metadata stored off-chain ensures minimal gas usage and flexibility.</li> </ul> <h4 id="alternative-designs-considered">Alternative Designs Considered</h4> <ol> <li> <p><strong>Pure On-Chain Metadata</strong></p> <ul> <li>Storing all metadata on-chain was considered but discarded due to high gas costs, limited storage capacity, and challenges in supporting complex or large datasets such as high-resolution avatars.</li> </ul> </li> <li> <p><strong>Direct Integration with ENS</strong></p> <ul> <li>While integrating with ENS was explored, it was deemed limiting for cross-chain functionality, as ENS is predominantly tied to Ethereum. Decentralised profile takes inspiration from ENS while ensuring a truly multichain approach.</li> </ul> </li> <li> <p><strong>Fully Centralised System</strong></p> <ul> <li>A centralised system would simplify implementation but contradict the core principles of decentralisation and user sovereignty.</li> </ul> </li> <li> <p><strong>Non-SBT-Based Implementation</strong></p> <ul> <li>Using standard <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens for profiles was considered but rejected since transferability is unsuitable for identity management. SBTs enforce the immutability of identity ownership.</li> </ul> </li> </ol> <h3 id="comparison-with-related-work">Comparison with Related Work</h3> <ul> <li><strong><a href="https://wg-eips.ritovision.com/137/">ERC-137</a> (ENS)</strong>: Provides a robust naming service but lacks dApp-specific metadata and cross-chain functionality.</li> <li><strong>Centralised identity services</strong>: Cannot leverage blockchain-specific advantages like immutability, decentralisation, and SBT integration.</li> <li><strong>DID Standards</strong>: Profile must aligns with DID specifications, ensuring it fits into the broader decentralised identity ecosystem while offering features tailored to blockchain-based applications.</li> </ul> <h3 id="scalability-and-extensibility">Scalability and Extensibility</h3> <p>The Registry and Resolver architecture, combined with off-chain metadata storage, ensures that profile can scale with the growth of the blockchain ecosystem. New chains, metadata types, and customisations can be added without disrupting the core functionality or introducing breaking changes.</p> <p>The design balances simplicity, extensibility, and user control, making it well-suited for adoption across a wide range of dApps, wallets, and blockchains.</p> <h3 id="contract-interface">Contract Interface</h3> <p>The standard includes the following interface:</p> <h4 id="isoulprofile"><code>ISoulProfile</code></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.19</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"> ISoulProfile</span><span> {</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> username</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> avatar</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> bio</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> website</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">string</span><span class="z-keyword"> =&gt;</span><span class="z-support"> string</span><span>)</span><span> socials</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> defaultAvatarVisibility</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> DappAvatar</span><span>)</span><span> dappAvatars</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"> DappAvatar</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> avatarURI</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> visibility</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> &quot;public&quot; or &quot;private&quot;</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"> ProfileCreated</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"> did</span><span>, </span><span class="z-support">string</span><span class="z-variable"> username</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AvatarUpdated</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"> avatarURI</span><span>, </span><span class="z-support">string</span><span class="z-variable"> visibility</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DappAvatarUpdated</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"> dApp</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> avatarURI</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> visibility</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"> createProfile</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> username</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"> setDefaultAvatar</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> avatarURI</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> visibility</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"> setDappAvatar</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> dApp</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"> avatarURI</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"> visibility</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"> getDefaultAvatar</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">string</span><span class="z-storage z-type"> memory</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"> getDappAvatar</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> dApp</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"> string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="reference-implementation">Reference Implementation</h3> <h4 id="soulprofile"><code>SoulProfile</code></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.19</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/access/Ownable.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/Strings.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./ISoulProfile.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"> SoulProfile</span><span class="z-storage"> is</span><span class="z-entity z-name"> Ownable</span><span>, </span><span class="z-entity z-name">ISoulProfile</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> Metadata</span><span>)</span><span class="z-storage z-type"> private</span><span> profiles</span><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"> onlyProfileOwner</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"> require</span><span>(</span><span class="z-variable z-language">msg.sender</span><span class="z-keyword"> ==</span><span> user</span><span>,</span><span class="z-string"> &quot;Not authorized&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"> createProfile</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> username</span><span>)</span><span class="z-storage z-type"> external</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-support">bytes</span><span>(</span><span>username</span><span>)</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Username cannot be empty&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>profiles</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>username </span><span class="z-keyword">==</span><span class="z-string"> &quot;&quot;</span><span>,</span><span class="z-string"> &quot;Profile already exists&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> profiles</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>username </span><span class="z-keyword">=</span><span> username</span><span>;</span></span> <span class="giallo-l"><span> profiles</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>defaultAvatarVisibility </span><span class="z-keyword">=</span><span class="z-string"> &quot;public&quot;</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Default to public</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ProfileCreated</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span class="z-entity z-name"> generateDID</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span>,</span><span> username</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"> setDefaultAvatar</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> avatarURI</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> visibility</span><span>)</span><span class="z-storage z-type"> external</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-support">bytes</span><span>(</span><span>visibility</span><span>)</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Visibility must be set&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> profiles</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>avatar </span><span class="z-keyword">=</span><span> avatarURI</span><span>;</span></span> <span class="giallo-l"><span> profiles</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>defaultAvatarVisibility </span><span class="z-keyword">=</span><span> visibility</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"> AvatarUpdated</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> avatarURI</span><span>,</span><span> visibility</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"> setDappAvatar</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> dApp</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"> avatarURI</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"> visibility</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> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>dApp </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;Invalid dApp address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-support">bytes</span><span>(</span><span>visibility</span><span>)</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Visibility must be set&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> profiles</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>dappAvatars</span><span>[</span><span>dApp</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> DappAvatar</span><span>(</span><span>avatarURI</span><span>,</span><span> visibility</span><span>)</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"> DappAvatarUpdated</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> dApp</span><span>,</span><span> avatarURI</span><span>,</span><span> visibility</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"> getDefaultAvatar</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</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-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> avatarURI</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> visibility</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> Metadata </span><span class="z-storage z-type">storage</span><span> profile </span><span class="z-keyword">=</span><span> profiles</span><span>[</span><span>user</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>profile</span><span>.</span><span>avatar</span><span>,</span><span> profile</span><span>.</span><span>defaultAvatarVisibility</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"> getDappAvatar</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> dApp</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-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> avatarURI</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> visibility</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> Metadata </span><span class="z-storage z-type">storage</span><span> profile </span><span class="z-keyword">=</span><span> profiles</span><span>[</span><span>user</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> DappAvatar </span><span class="z-storage z-type">storage</span><span> dappAvatar </span><span class="z-keyword">=</span><span> profile</span><span>.</span><span>dappAvatars</span><span>[</span><span>dApp</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>dappAvatar</span><span>.</span><span>avatarURI</span><span>,</span><span> dappAvatar</span><span>.</span><span>visibility</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"> generateDID</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</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">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-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 class="z-string">&quot;did:ethereum:&quot;</span><span>,</span><span> Strings</span><span>.</span><span class="z-entity z-name">toHexString</span><span>(</span><span>user</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>Of course, this can be extended to prepare a full registry and resolver according to ENS or similar standards. Refer to Rationale above for more information about the same.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The Decentralised Profile system is designed to ensure smooth integration with existing decentralized applications (dApps) and platforms, while offering an upgrade path for future enhancements. Below are key considerations for backwards compatibility:</p> <ul> <li> <p><strong>ENS Compatibility</strong>: The system adheres to the naming conventions and standards specified in <a href="https://wg-eips.ritovision.com/137/">ERC-137</a> (Ethereum Name Service). This ensures that any dApps or tools already using ENS-compatible names can easily integrate profiles without additional changes.</p> </li> <li> <p><strong>Flexible dApp Identification</strong>: By using wallet addresses to identify dApps, the system avoids the need for centralized registration of dApps. Any existing or new dApp that interacts with Ethereum or compatible chains can use the standard by simply passing its address as a parameter.</p> </li> <li> <p><strong>Default Avatar Fallback</strong>: If no specific avatar is set for a dApp, the system gracefully falls back to the default avatar. This ensures that even older dApps that do not implement the latest features can continue to work seamlessly.</p> </li> <li> <p><strong>Upgradeable Contracts</strong>: By implementing a proxy-based architecture for all major contracts (resolver, registry, profile), the system ensures that future upgrades or changes in functionality can be deployed without disrupting existing data or workflows. Upgrades are conducted through secure proxy mechanisms like TransparentUpgradeableProxy.</p> </li> <li> <p><strong>Chain Agnosticism</strong>: The use of decentralized identifiers (DIDs) and chain-specific network slugs ensures interoperability across chains. This allows profiles to maintain consistency regardless of which chain they originate from, ensuring compatibility with multi-chain ecosystems.</p> </li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>Profile system should prioritise robust security to protect user data and prevent unauthorized access.</p> <ol> <li> <p><strong>Access Control</strong>: Users can set visibility for their avatars (public or private). This is enforced at both the resolver and registry levels to ensure unauthorized entities cannot access private avatars. Functions that modify state (e.g., setDefaultAvatar, setDappAvatar) are protected with access controls, ensuring only the profile owner can make changes.</p> </li> <li> <p><strong>Data Privacy</strong>: Sensitive metadata is encrypted before storage on decentralized storage systems like IPFS or Arweave. Visibility flags ensure users can control who can view specific profile elements.</p> </li> <li> <p><strong>Reentrancy Protection</strong>: Functions modifying state implement the checks-effects-interactions pattern or leverage ReentrancyGuard to prevent reentrancy attacks. For example, setDappAvatar ensures that all validations are performed before updating the state.</p> </li> <li> <p><strong>Input Validation</strong>: All user inputs (e.g., username, visibility, dApp) are validated to ensure they meet specified criteria. Invalid or malicious inputs are rejected to prevent injection attacks or other exploits. Visibility is restricted to predefined values ("public" or "private").</p> </li> <li> <p><strong>Immutable DIDs</strong>: Decentralized identifiers (DIDs) for users are immutable once created. This prevents spoofing or unauthorized changes to user identities.</p> </li> <li> <p><strong>Fallback Mechanisms</strong>: The system provides fallback mechanisms for fetching avatars. If a dApp-specific avatar is not found, the default avatar is returned, ensuring smooth operation without errors.</p> </li> <li> <p><strong>Upgradeable Contracts</strong>: Proxy contracts are used to allow for upgrades while preserving state. Upgrades are performed securely via a multi-signature governance process to minimize risks.</p> </li> <li> <p><strong>Rate Limiting</strong>: Rate-limiting mechanisms can be implemented to prevent spam or abuse of profile creation and update functions.</p> </li> <li> <p><strong>Audits and Best Practices</strong>: The contracts are designed following best practices and are to be audited regularly by independent security firms. Dependencies (e.g., OpenZeppelin contracts) are reviewed and kept up to date to mitigate vulnerabilities.</p> </li> <li> <p><strong>dApp Address Verification</strong>: All dApps interacting with the system must be identified by a valid address. This ensures that unauthorized or spoofed entities cannot manipulate profiles or fetch restricted data.</p> </li> <li> <p><strong>Phishing Mitigation</strong>: User-facing dApps are encouraged to clearly display information about interactions on-chain. Users should be warned about potential phishing attacks and advised to interact only with verified dApps.</p> </li> <li> <p><strong>Gas Optimization</strong>: Operations are optimized to prevent gas exhaustion during execution, which could lead to incomplete transactions. This ensures that even on congested networks, the system remains functional.</p> </li> <li> <p><strong>Secure Fallback Functions</strong>: Fallback functions are implemented securely to prevent accidental Ether transfers or denial-of-service attacks.</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> 2025-01-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Toni Wahrstätterhttps://github.com/nerolation https://wg-eips.ritovision.com/8131/

Add EIP-7702 authorization data to the EIP-7623 floor calculation

<h2 id="abstract">Abstract</h2> <p>This EIP includes <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> authorization data in the <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> floor calculation, preventing circumvention of floor pricing through authorization lists.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> authorization tuples are priced for execution (<code>PER_EMPTY_ACCOUNT_COST = 25,000</code> gas per authorization) but do not contribute to the <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> floor calculation.</p> <p>This enables achieving ~9% larger blocks than intended by combining calldata with authorization data at an optimal ratio, circumventing the floor pricing mechanism.</p> <h2 id="specification">Specification</h2> <table><thead><tr><th>Parameter</th><th>Value</th><th>Source</th></tr></thead><tbody> <tr><td><code>TOTAL_COST_FLOOR_PER_TOKEN</code></td><td><code>10</code></td><td><a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a></td></tr> <tr><td><code>FLOOR_COST_PER_AUTH</code></td><td><code>4040</code></td><td>101 bytes × 4 tokens × 10 gas</td></tr> <tr><td><code>PER_EMPTY_ACCOUNT_COST</code></td><td><code>25000</code></td><td><a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a></td></tr> </tbody></table> <p>The <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> floor calculation is modified to include authorization data:</p> <pre class="giallo z-code"><code data-lang="python"><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> <span class="giallo-l"><span>floor_gas</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span class="z-constant"> TX_BASE_COST</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span class="z-constant"> TOTAL_COST_FLOOR_PER_TOKEN</span><span class="z-keyword"> *</span><span> tokens_in_calldata</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span class="z-constant"> FLOOR_COST_PER_AUTH</span><span class="z-keyword"> *</span><span> num_authorizations</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>The gas used calculation becomes:</p> <pre class="giallo z-code"><code data-lang="python"><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> tokens_in_calldata</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> execution_gas_used</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> isContractCreation</span><span class="z-keyword"> *</span><span> (</span><span class="z-constant">32000</span><span class="z-keyword"> +</span><span class="z-constant"> INITCODE_WORD_COST</span><span class="z-keyword"> *</span><span> words</span><span>(</span><span>calldata</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> access_list_cost</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span class="z-constant"> PER_EMPTY_ACCOUNT_COST</span><span class="z-keyword"> *</span><span> num_authorizations</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> TOTAL_COST_FLOOR_PER_TOKEN</span><span class="z-keyword"> *</span><span> tokens_in_calldata</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span class="z-constant"> FLOOR_COST_PER_AUTH</span><span class="z-keyword"> *</span><span> num_authorizations</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>Any transaction with a gas limit below <code>floor_gas</code> or below its intrinsic gas cost is considered invalid.</p> <h2 id="rationale">Rationale</h2> <h3 id="flat-cost-per-authorization">Flat Cost Per Authorization</h3> <p>Each authorization is charged a flat <code>FLOOR_COST_PER_AUTH = 4040</code> gas toward the floor, derived from:</p> <ul> <li>101 bytes per authorization tuple (as specified in <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>)</li> <li>4 tokens per byte (treating all bytes as non-zero)</li> <li>10 gas per token (<code>TOTAL_COST_FLOOR_PER_TOKEN</code>)</li> </ul> <p>This conservative approach avoids byte-level zero/non-zero accounting while ensuring authorization data is properly reflected in the floor calculation.</p> <h3 id="floor-only-modification">Floor-Only Modification</h3> <p>Authorization costs are added to the floor calculation only, not to intrinsic gas. This differs from <a href="https://wg-eips.ritovision.com/7981/">EIP-7981</a> (access lists) because:</p> <ul> <li>Authorization execution cost (25,000 gas) far exceeds floor contribution (4,040 gas per auth)</li> <li>Floor-only modification is sufficient to prevent bypass</li> </ul> <p>With this change:</p> <ul> <li>Authorization data contributes to the floor path</li> <li>High-execution transactions remain unaffected (execution exceeds floor)</li> <li>Data-heavy transactions cannot use authorizations to bypass floor pricing</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backwards incompatible gas repricing that requires a scheduled network upgrade.</p> <p>Requires updates to gas estimation in wallets and nodes. Normal usage patterns remain largely unaffected since authorization execution cost typically dominates the floor contribution.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="case-1-transaction-with-authorizations-only">Case 1: Transaction with Authorizations Only</h3> <ul> <li>Calldata: 0 bytes</li> <li>Authorizations: 10</li> </ul> <p>Old floor: 21,000 gas New floor: 21,000 + 10 × 4,040 = 61,400 gas Execution: 10 × 25,000 = 250,000 gas Result: Pay execution (250,000) - unchanged, execution dominates</p> <h3 id="case-2-bypass-attempt-now-blocked">Case 2: Bypass Attempt (Now Blocked)</h3> <ul> <li>Calldata: 100,000 bytes (400,000 tokens)</li> <li>Authorizations: 100</li> </ul> <p>Old floor: 21,000 + 400,000 × 10 = 4,021,000 gas New floor: 21,000 + 400,000 × 10 + 100 × 4,040 = 4,425,000 gas Execution: 21,000 + 1,600,000 + 2,500,000 = 4,121,000 gas Result: Pay new floor (4,425,000) - bypass blocked</p> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-constant">FLOOR_COST_PER_AUTH</span><span class="z-keyword"> =</span><span class="z-constant"> 4040</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 101 bytes * 4 tokens/byte * 10 gas/token</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"> calculate_intrinsic_cost</span><span>(</span><span class="z-variable z-parameter z-function">tx</span><span>:</span><span> Transaction</span><span>)</span><span> -&gt;</span><span> Tuple</span><span>[</span><span>Uint</span><span>,</span><span> Uint</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"> Calculate intrinsic gas cost and floor gas cost.</span></span> <span class="giallo-l"><span class="z-string"> Returns (intrinsic_gas, floor_gas).</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"> Calldata tokens</span></span> <span class="giallo-l"><span> calldata_zero</span><span class="z-keyword"> =</span><span class="z-support"> sum</span><span>(</span><span class="z-constant">1</span><span class="z-keyword"> for</span><span> b</span><span class="z-keyword"> in</span><span> tx</span><span>.</span><span>data</span><span class="z-keyword"> if</span><span> b</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span> tokens_in_calldata</span><span class="z-keyword"> =</span><span> Uint</span><span>(</span><span>calldata_zero</span><span class="z-keyword"> +</span><span> (</span><span class="z-support">len</span><span>(</span><span>tx</span><span>.</span><span>data</span><span>)</span><span class="z-keyword"> -</span><span> calldata_zero</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> 4</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"> Authorization costs</span></span> <span class="giallo-l"><span> num_authorizations</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> auth_exec_cost</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 class="z-keyword"> if</span><span class="z-support"> isinstance</span><span>(</span><span>tx</span><span>,</span><span> SetCodeTransaction</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> num_authorizations</span><span class="z-keyword"> =</span><span> Uint</span><span>(</span><span class="z-support">len</span><span>(</span><span>tx</span><span>.</span><span>authorizations</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> auth_exec_cost</span><span class="z-keyword"> =</span><span class="z-constant"> PER_EMPTY_ACCOUNT_COST</span><span class="z-keyword"> *</span><span> num_authorizations</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Floor: calldata + flat cost per authorization</span></span> <span class="giallo-l"><span> floor_gas</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span class="z-constant"> TX_BASE_COST</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> tokens_in_calldata</span><span class="z-keyword"> *</span><span class="z-constant"> TOTAL_COST_FLOOR_PER_TOKEN</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> num_authorizations</span><span class="z-keyword"> *</span><span class="z-constant"> FLOOR_COST_PER_AUTH</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"> Intrinsic: calldata + authorization execution cost</span></span> <span class="giallo-l"><span> calldata_cost</span><span class="z-keyword"> =</span><span> tokens_in_calldata</span><span class="z-keyword"> *</span><span class="z-constant"> STANDARD_TOKEN_COST</span></span> <span class="giallo-l"><span> intrinsic_gas</span><span class="z-keyword"> =</span><span class="z-constant"> TX_BASE_COST</span><span class="z-keyword"> +</span><span> calldata_cost</span><span class="z-keyword"> +</span><span> access_list_cost</span><span class="z-keyword"> +</span><span> auth_exec_cost</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> intrinsic_gas</span><span>,</span><span> floor_gas</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>This EIP closes a loophole that allows circumventing <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> floor pricing. Without this fix, adversaries can achieve ~9% larger blocks by combining calldata with authorization data.</p> <h3 id="interaction-with-eip-7981">Interaction with EIP-7981</h3> <p>If <a href="https://wg-eips.ritovision.com/7981/">EIP-7981</a> is also adopted, both EIPs work together: access list tokens and authorization tokens are both included in the floor calculation. There are no conflicts.</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-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin Guillaume Ballethttps://github.com/gballet Dankrad Feisthttps://github.com/dankrad Ignacio Hagopianhttps://github.com/jsign Kevaundray Wedderburnhttps://github.com/kevaundray Tanishq Jasoriahttps://github.com/tanishqjasoria Gajinder Singhhttps://github.com/g11tech Danno Ferrinhttps://github.com/shemnon Piper Merriamhttps://github.com/pipermerriam Gottfried Heroldhttps://github.com/GottfriedHerold https://wg-eips.ritovision.com/7864/

Switch Ethereum state tree to a unified binary tree

<h2 id="abstract">Abstract</h2> <p>Introduce a new binary state tree, intended to replace the hexary patricia trees. Account and storage tries are merged into a single tree with 32-byte keys, which also contains contracts code. Account data is broken into independent leaves which are grouped by 256 in order to provide some locality.</p> <p>Note: The hash function used in the current draft is not final. The current implementation uses BLAKE3 to reduce friction for EL clients experimenting with this EIP, but the final decision remains TBD. Other potential candidates include Keccak and Poseidon2.</p> <p>For Poseidon2, there's an ongoing Ethereum Foundation cryptography initiative assessing its security properties. If Poseidon2 is selected, additional specifications will be needed for field selection (BN254 scalar field, 31-bit field elements, etc.) and encoding 32-byte values into field elements.</p> <p>The hash function can be switched with minimal impact on implementations as this EIP progresses toward acceptance. <strong>Do not</strong> assume BLAKE3 is a final decision.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum's long-term goal is to allow blocks to be proved with validity proof so that chain verification is as simple and fast as possible. One of the most challenging parts of achieving that goal is proving the state of the tree, which is required for EVM execution.</p> <p>The current Merkle-Patricia Trie (MPT) design isn't friendly to validity proofs for many reasons, such as using RLP for node encoding, Keccak as a hashing function, being a "tree of trees", and not including accounts code as part of the state.</p> <p>Apart from requiring a state tree design that is friendly for block validity proofs, it's also important to have fast and small regular Merkle proofs when the amount of state to prove is small. This is useful not only for the application layer but also for supporting future protocol needs in a stateless world (e.g: inclusion lists).</p> <p>Regarding these regular Merkle proofs in an MPT, since it's a hexary tree, their size is quite big on average and in worst-case scenarios. Given a 2^32 size tree, the expected size for proving a single branch is <code>15 * 32 * log_16(2^32) = 3840</code>. From a worst-case block perspective, if 30M gas is used to access only a single byte of different account codes since this code isn't chunkified, we'd need <code>30M/2400*(5*480+24k)=330MB</code>.</p> <p>A binary tree has a good balance between out-of-circuit and in-circuit proving. Since the tree arity is two, this reduces the size of regular Merkle proofs (i.e., <code># siblings * log_arity(N)</code> for arity 2 is better than for arity 16). Moreover, we propose switching from Keccak to a more proving-friendly hash function, which would be more amenable to modern proving systems.</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="notable-changes-from-the-hexary-structure">Notable changes from the hexary structure</h3> <ul> <li>The account and storage tries are merged into a single trie.</li> <li>RLP is no longer used.</li> <li>The account's code is chunked and included in the tree.</li> <li>Account data (e.g., balance, nonce, first storage slots, first code-chunks) is co-located in the tree to reduce branch openings.</li> </ul> <h3 id="tree-structure">Tree structure</h3> <p>The proposed Binary Tree stores key-value entries where both the key and value are 32 bytes. The first 31-bytes of the key define the entry stem, and the last byte is the subindex in that stem. If two keys have the same stem, they live in the same "big branch" — this co-locates groups of 256 keys (i.e: keys with the same first 31-bytes).</p> <p><img src="https://wg-eips.ritovision.com/7864/./assets/diagram2.png" alt="Image" /> (More details about the purple/orange part in the "Tree embedding" section)</p> <p>We can distinguish four node types:</p> <ul> <li><code>InternalNode</code> has a <code>left_hash</code> and <code>right_hash</code> field (black).</li> <li><code>StemNode</code> has fields <code>stem</code>, <code>left_hash</code> and <code>right_hash</code> (blue).</li> <li><code>LeafNode</code> has a field <code>value</code> which is a 32-byte blob or <code>empty</code>. (orange).</li> <li><code>EmptyNode</code> represents an empty node/sub-tree.</li> </ul> <p>The path to a <code>StemNode</code> is defined by the key's first 248-bits (31-bytes) from MSB to LSB. From this node, a subtree of 256 values exists indexed by the key's last byte (8 bits). A newly created <code>StemNode</code> subtree (i.e: 256 values) has all leaves with <code>value: empty</code>.</p> <p>The path length isn't 248-bits, but contains the minimal amount of <code>InternalNodes</code> required if other stems exist with the same prefix. As in, when walking the 248-bit path inserting a new <code>StemNode</code>, you can end on a <code>EmptyNode</code> or <code>StemNode</code>. In the former, you replace it with the new <code>StemNode</code>. In the latter, you create as many <code>InternalNodes</code> as common bits both stems have as prefixes. Another way to look at this is that there aren't <em>extension nodes</em> in paths, but we use the minimal amount of <code>InternalNodes</code> to place <code>StemNode</code>s with common prefixes.</p> <p>Below is an implementation that describes the tree structure:</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"> StemNode</span><span>:</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 class="z-variable z-parameter z-function"> stem</span><span>:</span><span class="z-support"> bytes</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>stem</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 31</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">stem must be 31 bytes</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>stem</span><span class="z-keyword"> =</span><span> stem</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>values</span><span>:</span><span> list</span><span>[</span><span>Optional</span><span>[</span><span class="z-support">bytes</span><span>]</span><span>]</span><span class="z-keyword"> =</span><span> [</span><span class="z-constant">None</span><span>]</span><span class="z-keyword"> *</span><span class="z-constant"> 256</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_value</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> index</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> value</span><span>:</span><span class="z-support"> bytes</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>values</span><span>[</span><span>index</span><span>]</span><span class="z-keyword"> =</span><span> value</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"> InternalNode</span><span>:</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>left</span><span class="z-keyword"> =</span><span class="z-constant"> None</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>right</span><span class="z-keyword"> =</span><span class="z-constant"> None</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"> BinaryTree</span><span>:</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>root</span><span class="z-keyword"> =</span><span class="z-constant"> None</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"> insert</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> key</span><span>:</span><span class="z-support"> bytes</span><span>,</span><span class="z-variable z-parameter z-function"> value</span><span>:</span><span class="z-support"> bytes</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>key</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 32</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">key must be 32 bytes</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>value</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 32</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">value must be 32 bytes</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> stem</span><span class="z-keyword"> =</span><span> key</span><span>[</span><span>:</span><span class="z-constant">31</span><span>]</span></span> <span class="giallo-l"><span> subindex</span><span class="z-keyword"> =</span><span> key</span><span>[</span><span class="z-constant">31</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-variable z-language"> self</span><span>.</span><span>root</span><span class="z-keyword"> is</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>root</span><span class="z-keyword"> =</span><span> StemNode</span><span>(</span><span>stem</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>root</span><span>.</span><span>set_value</span><span>(</span><span>subindex</span><span>,</span><span> value</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 class="z-variable z-language"> self</span><span>.</span><span>root</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>_insert</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>root</span><span>,</span><span> stem</span><span>,</span><span> subindex</span><span>,</span><span> value</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"> def</span><span class="z-entity z-name"> _insert</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> node</span><span>,</span><span class="z-variable z-parameter z-function"> stem</span><span>,</span><span class="z-variable z-parameter z-function"> subindex</span><span>,</span><span class="z-variable z-parameter z-function"> value</span><span>,</span><span class="z-variable z-parameter z-function"> depth</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> depth</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 248</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">depth must be less than 248</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> node</span><span class="z-keyword"> is</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> node</span><span class="z-keyword"> =</span><span> StemNode</span><span>(</span><span>stem</span><span>)</span></span> <span class="giallo-l"><span> node</span><span>.</span><span>set_value</span><span>(</span><span>subindex</span><span>,</span><span> value</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> node</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> stem_bits</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>_bytes_to_bits</span><span>(</span><span>stem</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> isinstance</span><span>(</span><span>node</span><span>,</span><span> StemNode</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> If the stem already exists, update the value.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> node</span><span>.</span><span>stem</span><span class="z-keyword"> ==</span><span> stem</span><span>:</span></span> <span class="giallo-l"><span> node</span><span>.</span><span>set_value</span><span>(</span><span>subindex</span><span>,</span><span> value</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> node</span></span> <span class="giallo-l"><span> existing_stem_bits</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>_bytes_to_bits</span><span>(</span><span>node</span><span>.</span><span>stem</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>_split_leaf</span><span>(</span></span> <span class="giallo-l"><span> node</span><span>,</span><span> stem_bits</span><span>,</span><span> existing_stem_bits</span><span>,</span><span> subindex</span><span>,</span><span> value</span><span>,</span><span> depth</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"> We&#39;re in an internal node, go left or right based on the bit.</span></span> <span class="giallo-l"><span> bit</span><span class="z-keyword"> =</span><span> stem_bits</span><span>[</span><span>depth</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> bit</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> node</span><span>.</span><span>left</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>_insert</span><span>(</span><span>node</span><span>.</span><span>left</span><span>,</span><span> stem</span><span>,</span><span> subindex</span><span>,</span><span> value</span><span>,</span><span> depth</span><span class="z-keyword"> +</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> node</span><span>.</span><span>right</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>_insert</span><span>(</span><span>node</span><span>.</span><span>right</span><span>,</span><span> stem</span><span>,</span><span> subindex</span><span>,</span><span> value</span><span>,</span><span> depth</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> node</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"> _split_leaf</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> leaf</span><span>,</span><span class="z-variable z-parameter z-function"> stem_bits</span><span>,</span><span class="z-variable z-parameter z-function"> existing_stem_bits</span><span>,</span><span class="z-variable z-parameter z-function"> subindex</span><span>,</span><span class="z-variable z-parameter z-function"> value</span><span>,</span><span class="z-variable z-parameter z-function"> depth</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> If the stem bits are the same up to this depth, we need to create another</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> internal node and recurse.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> stem_bits</span><span>[</span><span>depth</span><span>]</span><span class="z-keyword"> ==</span><span> existing_stem_bits</span><span>[</span><span>depth</span><span>]</span><span>:</span></span> <span class="giallo-l"><span> new_internal</span><span class="z-keyword"> =</span><span> InternalNode</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> bit</span><span class="z-keyword"> =</span><span> stem_bits</span><span>[</span><span>depth</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> bit</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> new_internal</span><span>.</span><span>left</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>_split_leaf</span><span>(</span></span> <span class="giallo-l"><span> leaf</span><span>,</span><span> stem_bits</span><span>,</span><span> existing_stem_bits</span><span>,</span><span> subindex</span><span>,</span><span> value</span><span>,</span><span> depth</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> new_internal</span><span>.</span><span>right</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>_split_leaf</span><span>(</span></span> <span class="giallo-l"><span> leaf</span><span>,</span><span> stem_bits</span><span>,</span><span> existing_stem_bits</span><span>,</span><span> subindex</span><span>,</span><span> value</span><span>,</span><span> depth</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> new_internal</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> new_internal</span><span class="z-keyword"> =</span><span> InternalNode</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> bit</span><span class="z-keyword"> =</span><span> stem_bits</span><span>[</span><span>depth</span><span>]</span></span> <span class="giallo-l"><span> stem</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>_bits_to_bytes</span><span>(</span><span>stem_bits</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> bit</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> new_internal</span><span>.</span><span>left</span><span class="z-keyword"> =</span><span> StemNode</span><span>(</span><span>stem</span><span>)</span></span> <span class="giallo-l"><span> new_internal</span><span>.</span><span>left</span><span>.</span><span>set_value</span><span>(</span><span>subindex</span><span>,</span><span> value</span><span>)</span></span> <span class="giallo-l"><span> new_internal</span><span>.</span><span>right</span><span class="z-keyword"> =</span><span> leaf</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> new_internal</span><span>.</span><span>right</span><span class="z-keyword"> =</span><span> StemNode</span><span>(</span><span>stem</span><span>)</span></span> <span class="giallo-l"><span> new_internal</span><span>.</span><span>right</span><span>.</span><span>set_value</span><span>(</span><span>subindex</span><span>,</span><span> value</span><span>)</span></span> <span class="giallo-l"><span> new_internal</span><span>.</span><span>left</span><span class="z-keyword"> =</span><span> leaf</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> new_internal</span></span></code></pre><h3 id="node-merkelization">Node merkelization</h3> <p>Define <code>hash(value)</code> as:</p> <ul> <li><code>hash([0x00] * 64) = [0x00] * 32</code></li> <li><code>hash(value) = H(value)</code>, where H is the selected cryptographic hash function.</li> </ul> <p>The <code>value</code> parameter lengths can only be 32 and 64.</p> <p>Merkelize each node type as follows:</p> <ul> <li><code>internal_node_hash = hash(left_hash || right_hash)</code></li> <li><code>stem_node_hash = hash(stem || 0x00 || hash(left_hash || right_hash))</code></li> <li><code>leaf_node_hash = hash(value)</code></li> <li><code>empty_node_hash = [0x00] * 32</code></li> </ul> <p>Below is an implementation of these rules using BLAKE3 as a reference implementation:</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"> _hash</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> data</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> data</span><span class="z-keyword"> in</span><span> (</span><span class="z-constant">None</span><span>,</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-keyword"> *</span><span class="z-constant"> 64</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-constant">\x00</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword"> *</span><span class="z-constant"> 32</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>data</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 64</span><span class="z-keyword"> or</span><span class="z-support"> len</span><span>(</span><span>data</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 32</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">data must be 32 or 64 bytes</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> blake3</span><span>(</span><span>data</span><span>)</span><span>.</span><span>digest</span><span>(</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> This will be replaced with the final hash function</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"> merkelize</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-storage z-type"> def</span><span class="z-entity z-name"> _merkelize</span><span>(</span><span class="z-variable z-parameter z-function">node</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> node</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-constant">\x00</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword"> *</span><span class="z-constant"> 32</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> isinstance</span><span>(</span><span>node</span><span>,</span><span> InternalNode</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> left_hash</span><span class="z-keyword"> =</span><span> _merkelize</span><span>(</span><span>node</span><span>.</span><span>left</span><span>)</span></span> <span class="giallo-l"><span> right_hash</span><span class="z-keyword"> =</span><span> _merkelize</span><span>(</span><span>node</span><span>.</span><span>right</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>_hash</span><span>(</span><span>left_hash</span><span class="z-keyword"> +</span><span> right_hash</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> level</span><span class="z-keyword"> =</span><span> [</span><span class="z-variable z-language">self</span><span>.</span><span>_hash</span><span>(</span><span>x</span><span>)</span><span class="z-keyword"> for</span><span> x</span><span class="z-keyword"> in</span><span> node</span><span>.</span><span>values</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span class="z-support"> len</span><span>(</span><span>level</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 1</span><span>:</span></span> <span class="giallo-l"><span> new_level</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-support"> len</span><span>(</span><span>level</span><span>)</span><span>,</span><span class="z-constant"> 2</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> new_level</span><span>.</span><span>append</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>_hash</span><span>(</span><span>level</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> +</span><span> level</span><span>[</span><span>i</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>]</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> level</span><span class="z-keyword"> =</span><span> new_level</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> self</span><span>.</span><span>_hash</span><span>(</span><span>node</span><span>.</span><span>stem</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">\0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword"> +</span><span> level</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _merkelize</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>root</span><span>)</span></span></code></pre><h3 id="tree-embedding">Tree embedding</h3> <p>Instead of a two-layer structure like the MPT, we will embed all information into a unique <code>key: value</code> space in the proposed single tree. This section specifies which tree keys store the state's information (account header data, code, storage). The data is colocated in such way that data that is usually accessed together lives in the same <code>StemNode</code> which reduces branch openings.</p> <p>The following is a big picture of what we'll continue to describe in the rest of this section:</p> <p><img src="https://wg-eips.ritovision.com/7864/./assets/diagram1.png" alt="Image" /></p> <p>The account stem (green <code>account</code> node) contains accounts basic data, first 64-storage slots, and first 128-code chunks. This co-location of data allows having data in a single stem branch that is usually accessed together. The rest of storage slots and code-chunks are spread into groups of 256 values in the rest of the tree -- this is also done for convenience since slots/code-chunks that are close together will share the same stem branch.</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>STEM_SUBTREE_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>STEM_SUBTREE_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>STEM_SUBTREE_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="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> old_style_address_to_address32</span><span>(</span><span class="z-variable z-parameter z-function">address</span><span>:</span><span> Address</span><span>)</span><span> -&gt;</span><span> Address32</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">&#39;</span><span class="z-constant">\\</span><span class="z-string">x00</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> *</span><span class="z-constant"> 12</span><span class="z-keyword"> +</span><span> address</span></span></code></pre><h3 id="header-values">Header values</h3> <p>These are the positions in the tree at which header fields of an account are stored.</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"> tree_hash</span><span>(</span><span class="z-variable z-parameter z-function">inp</span><span>:</span><span class="z-support"> bytes</span><span>)</span><span> -&gt;</span><span> bytes32</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> bytes32</span><span>(</span><span>blake3</span><span>.</span><span>blake3</span><span>(</span><span>inp</span><span>)</span><span>.</span><span>digest</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"> get_tree_key</span><span>(</span><span class="z-variable z-parameter z-function">address</span><span>:</span><span> Address32</span><span>,</span><span class="z-variable z-parameter z-function"> tree_index</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> sub_index</span><span>:</span><span class="z-support"> int</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Assumes STEM_SUBTREE_WIDTH = 256</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> tree_hash</span><span>(</span><span>address</span><span class="z-keyword"> +</span><span> tree_index</span><span>.</span><span>to_bytes</span><span>(</span><span class="z-constant">32</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><span>:</span><span class="z-constant">31</span><span>]</span><span class="z-keyword"> +</span><span class="z-support"> bytes</span><span>(</span></span> <span class="giallo-l"><span> [</span><span>sub_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">def</span><span class="z-entity z-name"> get_tree_key_for_basic_data</span><span>(</span><span class="z-variable z-parameter z-function">address</span><span>:</span><span> Address32</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> get_tree_key</span><span>(</span><span>address</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> BASIC_DATA_LEAF_KEY</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_tree_key_for_code_hash</span><span>(</span><span class="z-variable z-parameter z-function">address</span><span>:</span><span> Address32</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> get_tree_key</span><span>(</span><span>address</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> CODE_HASH_LEAF_KEY</span><span>)</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. The goal of packing these fields together in a basic-data leaf is to reduce gas costs, since we only need one branch opening compared with the usual 3 or 4 if the fields aren't packed. This also simplifies witness generation.</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> <h3 id="code">Code</h3> <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_tree_key_for_code_chunk</span><span>(</span><span class="z-variable z-parameter z-function">address</span><span>:</span><span> Address32</span><span>,</span><span class="z-variable z-parameter z-function"> chunk_id</span><span>:</span><span class="z-support"> int</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> get_tree_key</span><span>(</span></span> <span class="giallo-l"><span> address</span><span>,</span></span> <span class="giallo-l"><span> (</span><span class="z-constant">CODE_OFFSET</span><span class="z-keyword"> +</span><span> chunk_id</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> STEM_SUBTREE_WIDTH</span><span>,</span></span> <span class="giallo-l"><span> (</span><span class="z-constant">CODE_OFFSET</span><span class="z-keyword"> +</span><span> chunk_id</span><span>)</span><span class="z-keyword"> %</span><span class="z-constant"> STEM_SUBTREE_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 (i.e. the i'th 31-byte slice of it), and byte 0 is the number of leading bytes that are part of PUSHDATA (e.g. 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="python"><span class="giallo-l"><span class="z-constant">PUSH_OFFSET</span><span class="z-keyword"> =</span><span class="z-constant"> 95</span></span> <span class="giallo-l"><span class="z-constant">PUSH1</span><span class="z-keyword"> =</span><span class="z-constant"> PUSH_OFFSET</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-constant">PUSH32</span><span class="z-keyword"> =</span><span class="z-constant"> PUSH_OFFSET</span><span class="z-keyword"> +</span><span class="z-constant"> 32</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"> chunkify_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> -&gt;</span><span> Sequence</span><span>[</span><span>bytes32</span><span>]</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Pad to multiple of 31 bytes</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"> 31</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> code</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">\\</span><span class="z-string">x00</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> *</span><span> (</span><span class="z-constant">31</span><span class="z-keyword"> -</span><span> (</span><span class="z-support">len</span><span>(</span><span>code</span><span>)</span><span class="z-keyword"> %</span><span class="z-constant"> 31</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Figure out how much pushdata there is after including each byte</span></span> <span class="giallo-l"><span> bytes_to_exec_data</span><span class="z-keyword"> =</span><span> [</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> *</span><span> (</span><span class="z-support">len</span><span>(</span><span>code</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> 32</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-keyword"> if</span><span class="z-constant"> PUSH1</span><span class="z-keyword"> &lt;=</span><span> code</span><span>[</span><span>pos</span><span>]</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> PUSH32</span><span>:</span></span> <span class="giallo-l"><span> pushdata_bytes</span><span class="z-keyword"> =</span><span> code</span><span>[</span><span>pos</span><span>]</span><span class="z-keyword"> -</span><span class="z-constant"> PUSH_OFFSET</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> pushdata_bytes</span><span class="z-keyword"> =</span><span class="z-constant"> 0</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"> for</span><span> x</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span>pushdata_bytes</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> bytes_to_exec_data</span><span>[</span><span>pos</span><span class="z-keyword"> +</span><span> x</span><span>]</span><span class="z-keyword"> =</span><span> pushdata_bytes</span><span class="z-keyword"> -</span><span> x</span></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> +=</span><span> pushdata_bytes</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Output chunks</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> [</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>(</span><span>[</span><span class="z-support">min</span><span>(</span><span>bytes_to_exec_data</span><span>[</span><span>pos</span><span>]</span><span>,</span><span class="z-constant"> 31</span><span>)</span><span>]</span><span>)</span><span class="z-keyword"> +</span><span> code</span><span>[</span><span>pos</span><span>:</span><span> pos</span><span class="z-keyword">+</span><span class="z-constant">31</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> pos</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-support"> len</span><span>(</span><span>code</span><span>)</span><span>,</span><span class="z-constant"> 31</span><span>)</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"></span></code></pre><h3 id="storage">Storage</h3> <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_tree_key_for_storage_slot</span><span>(</span><span class="z-variable z-parameter z-function">address</span><span>:</span><span> Address32</span><span>,</span><span class="z-variable z-parameter z-function"> storage_key</span><span>:</span><span class="z-support"> int</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> storage_key</span><span class="z-keyword"> &lt;</span><span> (</span><span class="z-constant">CODE_OFFSET</span><span class="z-keyword"> -</span><span class="z-constant"> HEADER_STORAGE_OFFSET</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> =</span><span class="z-constant"> HEADER_STORAGE_OFFSET</span><span class="z-keyword"> +</span><span> storage_key</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> =</span><span class="z-constant"> MAIN_STORAGE_OFFSET</span><span class="z-keyword"> +</span><span> storage_key</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> get_tree_key</span><span>(</span></span> <span class="giallo-l"><span> address</span><span>,</span></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> //</span><span class="z-constant"> STEM_SUBTREE_WIDTH</span><span>,</span></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> %</span><span class="z-constant"> STEM_SUBTREE_WIDTH</span></span> <span class="giallo-l"><span> )</span></span></code></pre> <p>Note that storage slots within the same range of size <code>STEM_SUBTREE_WIDTH</code> (i.e. a range with the form <code>x*STEM_SUBTREE_WIDTH ... (x+1)*STEM_SUBTREE_WIDTH-1)</code> are all, except for the <code>HEADER_STORAGE_OFFSET</code> special case, part of a single stem.</p> <h3 id="fork">Fork</h3> <p>Described in <a href="https://wg-eips.ritovision.com/7612/">EIP-7612</a>.</p> <h3 id="access-events">Access events</h3> <p>Described in <a href="https://wg-eips.ritovision.com/4762/">EIP-4762</a>.</p> <h2 id="rationale">Rationale</h2> <p>This EIP defines a new Binary Tree that starts empty. Only new state changes are stored in the tree. The MPT continues to exist but is frozen. This sets the stage for a future hard fork that migrates the MPT data to this Binary Tree (<a href="https://wg-eips.ritovision.com/7748/">EIP-7748</a>).</p> <h3 id="single-tree-design">Single tree design</h3> <p>The proposal 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 (e.g. database reading/writing, caching, syncing, proof creation, and verification) and 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 throughout the tree; even if a single contract has 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 both features and even add new structures if desired.</li> </ul> <h3 id="snark-friendliness-and-post-quantum-security">SNARK friendliness and Post-Quantum security</h3> <p>The proposed design should consider the usual complexity, performance, and efficiency for out-of-circuit implementations (i.e. EL clients) and in-circuit ones for generating proofs in ZK circuits.</p> <p>The tree design structure tries to be simple, by not having complex branching rules. For example, in contrast with the MPT, we avoid extension nodes injected in the middle of branches. Also, RLP encoding was removed since it adds unnecessary complexity. Although complexity can be managed more easily in out-of-circuit implementations, it's valuable to help circuit implementations be as simple as possible to avoid proving overhead.</p> <p>The most important factor in the design is the cryptographic hash function used for merkleization. This hash function should have efficient implementations both out and in circuits. The hash function selection remains TBD, with several candidates under consideration:</p> <ol> <li> <p><strong>BLAKE3</strong>:</p> <ul> <li>Good out-of-circuit performance (i.e., for raw EL client execution)</li> <li>Reasonable in-circuit performance for proving</li> <li>Well-established security properties</li> <li>Currently used in the reference implementation to facilitate experimentation</li> </ul> </li> <li> <p><strong>Keccak</strong>:</p> <ul> <li>Already used in Ethereum, reducing implementation complexity</li> <li>Well-studied security properties</li> <li>Less efficient for circuit proving than alternatives</li> </ul> </li> <li> <p><strong>Poseidon2</strong>:</p> <ul> <li>Excellent in-circuit performance for ZK proofs</li> <li>Potentially better proving throughput</li> <li>Security analysis still ongoing through EF cryptography initiative</li> <li>Would require additional specification for field selection and encoding</li> </ul> </li> </ol> <p>The final hash function selection will balance these considerations, with particular attention to security, proving efficiency, and implementation complexity.</p> <p>Due to recent progress in the quantum computing field, expert estimations consider that they can become real in the 2030s. NIST suggests stopping the use of ECC by 2030 too. Other alternatives, such as Verkle Trees, introduce a new cryptography stack to the protocol, which relies on elliptic curves that aren't post-quantum secure. This makes the current tree proposal attractive since it only depends on hash functions, which are still safe in this new paradigm.</p> <p>Moreover, there has been impressive progress in proving systems, which indicates that we could be close to achieving the required performance for creating pre-state &amp; post-state proofs fast enough. This last point is crucial since the main advantage of Verkle Trees was having proofs that are small and fast to generate.</p> <p>Finally, the current state tree proposal will probably be the final state tree used in the protocol, compared with Verkle Trees, which would eventually need to be replaced by a post-quantum secure alternative.</p> <h3 id="arity-2">Arity-2</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 size 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 (e.g. 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 might be slightly larger than this due to uneven distribution, but the pattern of <code>k=2</code> remains by far the best.</p> <h3 id="tree-depth">Tree depth</h3> <p>The tree design attempts to be as simple as possible considering both out-of-circuit and circuit implementations, while satisfying our throughput constraints on proving hashes.</p> <p>The proposed design avoids a full 248-bit depth as it would happen in a Sparse Merkle Tree (SMT). This approach helps reduce the hashing load in proving systems, which is currently a throughput bottleneck on commodity hardware. The choice of hash function will impact this consideration - arithmetic-friendly hash functions like Poseidon2 would have different performance characteristics than cryptographic hash functions like BLAKE3 or Keccak. There are some optimization techniques that could be applied, but they add complexity to the specification.</p> <p>Moreover, we could push this further trying to introduce extension nodes in the middle of paths as done in a MPT, but this also adds complexity that might not be worth it considering the tree should be quite balanced.</p> <h3 id="state-expiry">State-expiry</h3> <p>State-expiry strategies such as <a href="https://wg-eips.ritovision.com/7736/">EIP-7736</a> could still be applied, requiring a change in the design. One potential solution is adding a field to the <code>StemNode</code> with <code>epoch</code> as described in the mentioned EIP. Another alternative is to use 247-bits for the stem, and have two subtrees <code>StemValuesNode</code>, which would correspond to the current 256-values, and <code>StemMetaNode</code> which is also a 256-subtree that can be used to store arbitrary stem metadata.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The main breaking changes are:</p> <ul> <li>(1) Gas costs for code chunk access can have an impact on applications' economic viability</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 while implementing this EIP, allowing the same economic viability for applications.</p> <!-- TODO: ## Test Cases - Add comprehensive test vectors for tree operations - Finalize hash function selection and provide test vectors for the selected function - Add test cases for edge cases in tree operations --> <!-- TODO: Remove external link ## Reference Implementation Python reference implementation (`github.com/jsign/binary-tree-spec`). --> <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> 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> 2025-01-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Toni Wahrstätterhttps://github.com/nerolation Jochem Brouwerhttps://github.com/jochem-brouwer Alex Stokeshttps://github.com/ralexstokes Ansgar Dietrichshttps://github.com/adietrichs Yoav Weisshttps://github.com/yoavw Alex Forshtathttps://github.com/forshtat https://wg-eips.ritovision.com/7863/

Warm addresses and storage keys over the duration of a block

<h2 id="abstract">Abstract</h2> <p>This proposal introduces block-level address and storage key warming, allowing accessed addresses and storage keys to maintain their "warm" status throughout an entire block's execution. Accessed slots can be effectively cached at the block level, allowing for this optimization.</p> <h2 id="motivation">Motivation</h2> <p>Currently, the EVM's storage slot warming mechanism operates at the transaction level, requiring each transaction to "warm up" slots independently, even when accessing the same storage locations within the same block. This design does not take advantage of the fact that modern node implementations can effectively cache storage access patterns at the block level. By extending the slot warming duration to the block level, we can:</p> <ol> <li>Reduce redundant warming costs for frequently accessed slots</li> <li>Better align gas costs with actual computational overhead</li> <li>Improve overall network throughput without compromising security.</li> </ol> <p>As of Jan. 2025, the empirically measured efficiency gains are around 5%.</p> <h2 id="specification">Specification</h2> <h3 id="mechanics">Mechanics</h3> <p>When a storage slot is accessed within a block:</p> <ol> <li>The first access to a slot in a block incurs the cold access cost as of <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>.</li> <li>All subsequent accesses to the same slot within the same block incur only the warm access cost as of <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>.</li> <li>The warm/cold status resets at block boundaries</li> </ol> <h3 id="block-processing">Block Processing</h3> <ol> <li>At the start of each block: <ul> <li>Initialize two empty sets <code>block_level_accessed_addresses</code> and <code>block_level_accessed_storage_keys</code></li> </ul> </li> <li>For each transaction in the block: <ul> <li>Before processing storage access: <ul> <li>Check if touched address is in <code>block_level_accessed_addresses</code></li> <li>If yes: charge <code>WARM_STORAGE_READ_COST</code></li> <li>If no: <ul> <li>Charge <code>COLD_ACCOUNT_ACCESS_COST</code></li> <li>Add address to <code>block_level_accessed_addresses</code></li> </ul> </li> <li>Check if storage key is in <code>block_level_accessed_storage_keys</code></li> <li>If yes: charge <code>WARM_STORAGE_READ_COST</code></li> <li>If no: <ul> <li>Charge <code>COLD_SLOAD_COST</code></li> <li>Add storage key to <code>block_level_accessed_storage_keys</code></li> </ul> </li> </ul> </li> </ul> </li> </ol> <h3 id="implementation-details">Implementation Details</h3> <p>The implementation modifies the block execution process to maintain block-level sets of accessed addresses and storage slots.</p> <h4 id="block-level-storage-management">Block-Level Storage Management</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"> apply_body</span><span>(</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"> Initialize block-level tracking sets</span></span> <span class="giallo-l"><span> block_level_accessed_addresses</span><span class="z-keyword"> =</span><span class="z-support"> set</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> block_level_accessed_storage_keys</span><span class="z-keyword"> =</span><span class="z-support"> set</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> </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> 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"> Create environment with block-level context</span></span> <span class="giallo-l"><span> env</span><span class="z-keyword"> =</span><span> vm</span><span>.</span><span>Environment</span><span>(</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> ... other parameters ...</span></span> <span class="giallo-l"><span class="z-variable"> block_level_accessed_addresses</span><span class="z-keyword">=</span><span>block_level_accessed_addresses</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> block_level_accessed_storage_keys</span><span class="z-keyword">=</span><span>block_level_accessed_storage_keys</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"> Process transaction and update block-level sets</span></span> <span class="giallo-l"><span> gas_used</span><span>,</span><span> accessed_addresses</span><span>,</span><span> accessed_storage_keys</span><span>,</span><span> logs</span><span>,</span><span> error</span><span class="z-keyword"> =</span><span> process_transaction</span><span>(</span><span>env</span><span>,</span><span> tx</span><span>)</span></span> <span class="giallo-l"><span> block_level_accessed_addresses</span><span class="z-keyword"> +=</span><span> accessed_addresses</span></span> <span class="giallo-l"><span> block_level_accessed_storage_keys</span><span class="z-keyword"> +=</span><span> accessed_storage_keys</span></span></code></pre> <p>This code shows how block-level slot warming is implemented at the execution layer. The <code>block_level_accessed_addresses</code> and <code>block_level_accessed_storage_keys</code> sets are maintained throughout the block's execution and passed to each transaction's environment.</p> <h4 id="transaction-processing">Transaction 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_transaction</span><span>(</span><span class="z-variable z-parameter z-function">env</span><span>:</span><span> vm</span><span>.</span><span>Environment</span><span>,</span><span class="z-variable z-parameter z-function"> tx</span><span>:</span><span> Transaction</span><span>)</span><span> -&gt;</span><span> Tuple</span><span>[</span><span>Uint</span><span>,</span><span> Tuple</span><span>[</span><span>Log</span><span>,</span><span class="z-constant"> ...</span><span>]</span><span>,</span><span> Optional</span><span>[</span><span class="z-support">Exception</span><span>]</span><span>]</span><span>:</span></span> <span class="giallo-l"><span> preaccessed_addresses</span><span class="z-keyword"> =</span><span class="z-support"> set</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> preaccessed_storage_keys</span><span class="z-keyword"> =</span><span class="z-support"> set</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"> Add block-level pre-accessed slots</span></span> <span class="giallo-l"><span> preaccessed_addresses</span><span>.</span><span>add</span><span>(</span><span>env</span><span>.</span><span>block_level_accessed_addresses</span><span>)</span></span> <span class="giallo-l"><span> preaccessed_storage_keys</span><span>.</span><span>add</span><span>(</span><span>env</span><span>.</span><span>block_level_accessed_storage_keys</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"> Handle access lists from transaction</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre> <p>This adds the block-level-accessed addresses and storage keys to the preaccessed addresses and storage keys. As a result, from the perspective of a transaction, block-level accessed addresses and storage keys are treated the same as precompiles or the coinbase address.</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_message_call</span><span>(</span><span class="z-variable z-parameter z-function">message</span><span>:</span><span> Message</span><span>,</span><span class="z-variable z-parameter z-function"> env</span><span>:</span><span> Environment</span><span>)</span><span> -&gt;</span><span> MessageCallOutput</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> MessageCallOutput</span><span>(</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> ... other fields ...</span></span> <span class="giallo-l"><span class="z-variable"> accessed_addresses</span><span class="z-keyword">=</span><span>evm</span><span>.</span><span>accessed_addresses</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> accessed_storage_keys</span><span class="z-keyword">=</span><span>evm</span><span>.</span><span>accessed_storage_keys</span></span> <span class="giallo-l"><span> )</span></span></code></pre> <p>The message call processing tracks accessed addresses and storage keys during execution, which are then propagated back up to the transaction level and ultimately to the block level.</p> <h2 id="rationale">Rationale</h2> <p>The proposal builds on several key observations:</p> <ol> <li> <p><strong>Caching Efficiency</strong>: Modern Ethereum clients already implement sophisticated caching mechanisms at the block level. Extending address and storage key warming to match this caching behavior better aligns gas costs with actual computational costs.</p> </li> <li> <p><strong>Backward Compatibility</strong>: The worst-case scenario for any transaction remains unchanged - it will never pay more than the current cold access cost for its first access to a slot.</p> </li> <li> <p><strong>Handling Reverts</strong>: In EIP-2929, if a sub-call reverts, all accessed addresses and slots are reverted to a cold state. Under block-level warming, it remains an open question whether a failing transaction (i.e., one that reverts) should ‘unwarm’ previously warmed addresses and slots for subsequent transactions within the same block. Some propose removing this revert-induced “cold reset” altogether to maintain consistency with block-level warming. This point warrants further discussion, particularly around whether or not preserving a warmed state even upon failure aligns with the broader goal of better matching gas costs to actual client caching behavior.</p> </li> <li> <p><strong>First Access Warms For All</strong>: Under the proposed mechanism, the first transaction in a block that accesses and warms multiple addresses or storage slots bears the entire cost of warming, even if subsequent transactions benefit from those already-warmed slots without incurring additional costs. This approach is deemed acceptable because early execution within a block—where warming typically occurs—is generally occupied for transactions placed by professional builders aiming for top-of-block execution. Since the resulting cost discrepancy is relatively minor, a more complex cost-sharing model is avoided in favor of maintaining simplicity. An alternative to the one-warms-for-all mechanism involves distributing the warming costs across all accesses within a block. In this approach, each transaction must at least be able to pay the cold access cost. Once all transactions in the block are executed, the total warming costs are evenly distributed, and transaction originators are refunded accordingly.</p> </li> <li> <p><strong>Alternative Block Warming Windows</strong>: Instead of applying warming at the block level, more advanced multi-block warming approaches can be considered. Potential options include:</p> <ul> <li>Warming addresses and storage keys over the duration of an epoch</li> <li>Using a ring buffer spanning <code>x</code> blocks Since the Execution Layer (EL) currently operates without regard to epoch boundaries, it may be preferable to maintain this design. Therefore, the second option, involving a ring buffer of size x, could be more suitable. For the ring buffer, one approach might be to store the relevant warmed information in the block header for those x blocks, but this introduces additional overhead and can complicate statelessness. Careful design would be required to manage these trade-offs (e.g., header size, client complexity) if a multi-block warming solution were adopted.</li> </ul> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is not backward compatible and requires a hard fork activation. However, it does not introduce any breaking changes for existing contracts, as:</p> <ol> <li>All existing transactions will continue to work as before</li> <li>Gas costs will only decrease, never increase</li> <li>Contract logic depending on gas costs will remain valid, as the worst-case scenario is unchanged</li> </ol> <h2 id="security-considerations">Security Considerations</h2> <ol> <li> <p><strong>Memory Usage</strong>: The set of warm slots is still bounded by block gas limit / minimum gas cost per slot access, preventing DoS attacks through excessive memory usage.</p> </li> <li> <p><strong>MEV Considerations</strong>: Block producers can optimize transaction ordering to maximize slot warming benefits for themselves. Third-party block builders can backrun transactions that warmed specific addresses or storage keys.</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> 2025-01-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Leigh Cronianhttps://github.com/cybercentryleigh.cronian@cybercentry.co.uk https://wg-eips.ritovision.com/8126/

Self-registration and specialised verifications for verifiable AI Agent security on Ethereum

<h2 id="abstract">Abstract</h2> <p>This ERC defines a standard interface for registering and verifying AI agents on Ethereum. It enables AI agents to self-register with verifiable credentials and undergo specialised verification processes including Ethereum Token Verification (ETV), Staking Contract Verification (SCV), Web Application Verification (WAV), and Wallet Verification (WV). Verification providers implementing this standard process results through Private Data Verification (PDV) to generate Zero-Knowledge Proofs. Detailed verification results are accessible only to AI Agent wallet holders, providing a unified risk scoring system (0-100) that helps users assess agent trustworthiness.</p> <h2 id="motivation">Motivation</h2> <p>As AI agents become increasingly prevalent in blockchain ecosystems, users need standardised ways to verify their authenticity and trustworthiness. Current solutions are fragmented, with no unified standard for agent registration or verification. This ERC addresses these challenges by providing:</p> <ol> <li><strong>Self-Registration</strong>: AI agents can register themselves with verifiable on-chain credentials</li> <li><strong>Multi-Layer Verification</strong>: Four specialised verification types assess different aspects of agent security</li> <li><strong>Privacy-First Architecture</strong>: Zero-Knowledge Proofs ensure verification without exposing sensitive data</li> <li><strong>Unified Risk Scoring</strong>: A standardised 0-100 risk score enables easy comparison between agents</li> <li><strong>Micropayment Integration</strong>: x402 protocol enables cost-effective verification without gas overhead</li> <li><strong>Quantum-Resistant Future</strong>: Optional Quantum Cryptography Verification (QCV) provides future-proof encryption</li> </ol> <table><thead><tr><th>Term</th><th>Definition</th></tr></thead><tbody> <tr><td><strong>Agent Wallet</strong></td><td>The Ethereum address designated as controlled by the AI agent</td></tr> <tr><td><strong>AI Agent</strong></td><td>An autonomous software entity that performs actions on behalf of users, identified by an Ethereum wallet address and optional smart contract</td></tr> <tr><td><strong>ETV</strong></td><td>Ethereum Token Verification - validates smart contract presence and legitimacy</td></tr> <tr><td><strong>PDV</strong></td><td>Private Data Verification - generates Zero-Knowledge Proofs from verification results</td></tr> <tr><td><strong>Proof ID</strong></td><td>A unique identifier for a Zero-Knowledge Proof generated during verification</td></tr> <tr><td><strong>QCV</strong></td><td>Quantum Cryptography Verification - provides quantum-resistant encryption for sensitive data</td></tr> <tr><td><strong>Registrant</strong></td><td>The Ethereum address that submitted the agent registration transaction</td></tr> <tr><td><strong>Risk Score</strong></td><td>A numerical value from 0-100 indicating the assessed risk level, where 0 is lowest risk and 100 is highest risk</td></tr> <tr><td><strong>SCV</strong></td><td>Staking Contract Verification - validates staking contract security</td></tr> <tr><td><strong>Verification Provider</strong></td><td>A service implementing this standard's verification types (ETV, PDV, QCV, SCV, WAV, WV)</td></tr> <tr><td><strong>WAV</strong></td><td>Web Application Verification - checks endpoint security and accessibility</td></tr> <tr><td><strong>WV</strong></td><td>Wallet Verification - assesses wallet history and threat database status</td></tr> <tr><td><strong>ZKP</strong></td><td>Zero-Knowledge Proof - cryptographic proof that verification occurred without revealing underlying data</td></tr> </tbody></table> <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="required-standards">Required Standards</h3> <p>This standard requires the following EIPs/ERCs:</p> <table><thead><tr><th>Standard</th><th>Purpose in This ERC</th></tr></thead><tbody> <tr><td><a href="https://wg-eips.ritovision.com/155/">EIP-155</a></td><td>Replay attack protection - ensures signatures include chain ID to prevent cross-chain replay attacks during agent registration and verification</td></tr> <tr><td><a href="https://wg-eips.ritovision.com/712/">EIP-712</a></td><td>Typed structured data signing - enables human-readable signing requests for agent registration, preventing blind signing attacks and improving UX</td></tr> <tr><td><a href="https://wg-eips.ritovision.com/3009/">ERC-3009</a></td><td>Transfer with authorization - enables gasless USDC transfers for x402 micropayments, allowing verification fees without requiring ETH for gas</td></tr> <tr><td><a href="https://wg-eips.ritovision.com/191/">ERC-191</a></td><td>Signed data standard - provides standardised format for signed messages used in wallet verification and proof validation</td></tr> </tbody></table> <h3 id="verification-flow">Verification Flow</h3> <p>The following diagram illustrates the verification process:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>+-------------------+</span></span> <span class="giallo-l"><span>| AI Agent Owner |</span></span> <span class="giallo-l"><span>+--------+----------+</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | 1. Register Agent (EIP-712 signed)</span></span> <span class="giallo-l"><span> v</span></span> <span class="giallo-l"><span>+-------------------+</span></span> <span class="giallo-l"><span>| Agent Registry |</span></span> <span class="giallo-l"><span>| (Smart Contract) |</span></span> <span class="giallo-l"><span>+--------+----------+</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | 2. Emit AgentRegistered Event</span></span> <span class="giallo-l"><span> v</span></span> <span class="giallo-l"><span>+-------------------+</span></span> <span class="giallo-l"><span>| Verification |</span></span> <span class="giallo-l"><span>| Request |</span></span> <span class="giallo-l"><span>+--------+----------+</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | 3. Submit to Verification Provider</span></span> <span class="giallo-l"><span> | (x402 payment via EIP-3009)</span></span> <span class="giallo-l"><span> v</span></span> <span class="giallo-l"><span>+-------------------+ +-------------------+</span></span> <span class="giallo-l"><span>| Verification | | |</span></span> <span class="giallo-l"><span>| Provider +----&gt;+ ETV (if contract |</span></span> <span class="giallo-l"><span>| | | provided) |</span></span> <span class="giallo-l"><span>+--------+----------+ +--------+----------+</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> | v</span></span> <span class="giallo-l"><span> | +--------+----------+</span></span> <span class="giallo-l"><span> | | SCV |</span></span> <span class="giallo-l"><span> | | (if staking |</span></span> <span class="giallo-l"><span> | | provided) |</span></span> <span class="giallo-l"><span> | +--------+----------+</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> | v</span></span> <span class="giallo-l"><span> | +--------+----------+</span></span> <span class="giallo-l"><span> | | WAV |</span></span> <span class="giallo-l"><span> | | (always runs) |</span></span> <span class="giallo-l"><span> | +--------+----------+</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> | v</span></span> <span class="giallo-l"><span> | +--------+----------+</span></span> <span class="giallo-l"><span> | | WV |</span></span> <span class="giallo-l"><span> | | (always runs) |</span></span> <span class="giallo-l"><span> | +--------+----------+</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> | 4. Aggregate Results |</span></span> <span class="giallo-l"><span> |&lt;------------------------+</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | 5. Generate ZK Proofs via PDV</span></span> <span class="giallo-l"><span> v</span></span> <span class="giallo-l"><span>+-------------------+</span></span> <span class="giallo-l"><span>| PDV |</span></span> <span class="giallo-l"><span>| (Zero-Knowledge |</span></span> <span class="giallo-l"><span>| Proof Generation)|</span></span> <span class="giallo-l"><span>+--------+----------+</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | 6. Optional: QCV encryption</span></span> <span class="giallo-l"><span> v</span></span> <span class="giallo-l"><span>+-------------------+</span></span> <span class="giallo-l"><span>| QCV |</span></span> <span class="giallo-l"><span>| (Quantum-Resistant|</span></span> <span class="giallo-l"><span>| Encryption) |</span></span> <span class="giallo-l"><span>+--------+----------+</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | 7. Return Proof IDs</span></span> <span class="giallo-l"><span> v</span></span> <span class="giallo-l"><span>+-------------------+</span></span> <span class="giallo-l"><span>| Update Registry |</span></span> <span class="giallo-l"><span>| Emit AgentVerified|</span></span> <span class="giallo-l"><span>+-------------------+</span></span></code></pre><h3 id="agent-registration">Agent Registration</h3> <p>An AI agent MUST register with the following information:</p> <h4 id="required-fields">Required Fields</h4> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>name</td><td>string</td><td>Human-readable agent name</td></tr> <tr><td>description</td><td>string</td><td>Brief description of agent purpose</td></tr> <tr><td>walletAddress</td><td>address</td><td>Ethereum address controlled by agent</td></tr> <tr><td>url</td><td>string</td><td>HTTPS endpoint for agent interaction</td></tr> </tbody></table> <h4 id="optional-fields">Optional Fields</h4> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>contractAddress</td><td>address</td><td>Smart contract address if applicable</td></tr> <tr><td>stakingContractAddress</td><td>address</td><td>Staking contract address if applicable</td></tr> <tr><td>platformId</td><td>uint256</td><td>Platform identifier for cross-platform verification</td></tr> <tr><td>chainId</td><td>uint256</td><td>Chain ID for multi-chain agents</td></tr> </tbody></table> <h3 id="verification-types">Verification Types</h3> <p>Compliant verification providers MUST implement the following verification types:</p> <h4 id="etv-ethereum-token-verification">ETV (Ethereum Token Verification)</h4> <p>Validates on-chain presence and smart contract legitimacy.</p> <ul> <li>MUST verify contract exists on specified chain</li> <li>MUST check contract against known vulnerability patterns</li> <li>MUST return risk score 0-100</li> <li>SHOULD accept parameters: chain_id, platform_id, contract_address</li> <li>SHOULD follow OWASP Smart Contract Security guidelines</li> </ul> <h4 id="scv-staking-contract-verification">SCV (Staking Contract Verification)</h4> <p>Validates staking contract legitimacy and security when a staking contract address is provided.</p> <ul> <li>MUST verify staking contract exists on specified chain</li> <li>MUST check staking mechanism implementation</li> <li>MUST verify reward distribution logic</li> <li>MUST check for common staking vulnerabilities (reentrancy, flash loan attacks)</li> <li>MUST return risk score 0-100</li> <li>SHOULD accept parameters: chain_id, staking_contract_address</li> <li>SHOULD follow OWASP Smart Contract Security guidelines</li> </ul> <h4 id="wav-web-application-verification">WAV (Web Application Verification)</h4> <p>Ensures the agent's web endpoint is accessible and secure.</p> <ul> <li>MUST verify HTTPS endpoint responds</li> <li>MUST check for common security vulnerabilities</li> <li>MUST verify SSL certificate validity</li> <li>MUST return risk score 0-100</li> <li>SHOULD accept parameter: url</li> <li>SHOULD follow OWASP Web Application Security Testing guidelines (WSTG)</li> <li>SHOULD check for OWASP Top 10 vulnerabilities</li> </ul> <h4 id="wv-wallet-verification">WV (Wallet Verification)</h4> <p>Confirms wallet ownership and assesses on-chain risk profile.</p> <ul> <li>MUST verify wallet has transaction history</li> <li>MUST check against threat intelligence databases</li> <li>MUST return risk score 0-100</li> <li>SHOULD accept parameter: wallet_address</li> </ul> <h3 id="off-chain-verification">Off-chain Verification</h3> <p>Verification is performed off-chain to:</p> <ol> <li>Eliminate gas costs for verification operations</li> <li>Enable complex verification logic that would be prohibitively expensive on-chain</li> <li>Allow verification criteria to evolve without requiring contract upgrades</li> <li>Enable multiple competing verification providers</li> </ol> <h3 id="provider-agnostic-design">Provider Agnostic Design</h3> <p>This standard intentionally separates the interface specification from implementation details. Any verification provider MAY implement compliant ETV, WV, WAV, SCV, PDV, and QCV services, enabling:</p> <ol> <li>Competition among verification providers</li> <li>Specialisation in different verification domains</li> <li>Geographic and jurisdictional flexibility</li> <li>Price competition benefiting users</li> </ol> <h3 id="privacy-first-architecture-with-pdv">Privacy-First Architecture with PDV</h3> <p>Verification results are processed through Private Data Verification (PDV) which generates Zero-Knowledge Proofs. This privacy-first approach:</p> <ol> <li>Eliminates data breach risks - no stored data means nothing to compromise</li> <li>Provides cryptographic proof of verification that third parties can validate</li> <li>Ensures GDPR and privacy regulation compliance</li> <li>Builds user trust through transparent, verifiable data handling</li> </ol> <h3 id="quantum-resistant-future-with-qcv">Quantum-Resistant Future with QCV</h3> <p>Verification providers MAY implement QCV for quantum-resistant encryption of sensitive verification data.</p> <ul> <li>SHOULD use AES-256-GCM or equivalent post-quantum encryption algorithm</li> <li>MUST return unique record_id for encrypted data</li> <li>MUST provide decryption_url for authorized data retrieval</li> <li>SHOULD ensure quantum-resistant key exchange mechanisms</li> </ul> <p>QCV Key Properties:</p> <ul> <li>Provides future-proof protection against quantum computing threats</li> <li>Military-grade encryption standards (AES-256-GCM)</li> <li>Enables secure long-term storage of verification records</li> </ul> <h3 id="payment-protocol">Payment Protocol</h3> <p>Verification providers MAY charge fees for verification services. When fees are required:</p> <ul> <li>SHOULD use x402 protocol for micropayments</li> <li>SHOULD support stablecoin settlement (e.g., USDC)</li> <li>MUST clearly disclose fee structure before verification</li> <li>SHOULD use <a href="https://wg-eips.ritovision.com/3009/">EIP-3009</a> TransferWithAuthorization for gasless payments</li> </ul> <h3 id="risk-scoring">Risk Scoring</h3> <p>The overall risk score MUST be calculated as the average of all applicable verification scores:</p> <table><thead><tr><th>Tier</th><th>Score Range</th><th>Description</th></tr></thead><tbody> <tr><td>Low Risk</td><td>0-20</td><td>Minimal concerns identified</td></tr> <tr><td>Moderate</td><td>21-40</td><td>Some concerns, review recommended</td></tr> <tr><td>Elevated</td><td>41-60</td><td>Notable concerns, caution advised</td></tr> <tr><td>High Risk</td><td>61-80</td><td>Significant concerns detected</td></tr> <tr><td>Critical</td><td>81-100</td><td>Severe concerns, avoid interaction</td></tr> </tbody></table> <h3 id="error-codes">Error Codes</h3> <p>Implementations MUST use the following standardised error codes:</p> <table><thead><tr><th>Error Code</th><th>Name</th><th>Description</th></tr></thead><tbody> <tr><td><code>0x01</code></td><td><code>InvalidAddress</code></td><td>Provided address is not a valid Ethereum address</td></tr> <tr><td><code>0x02</code></td><td><code>InvalidURL</code></td><td>Provided URL is malformed or not HTTPS</td></tr> <tr><td><code>0x03</code></td><td><code>AgentNotFound</code></td><td>No agent exists with the specified agentId</td></tr> <tr><td><code>0x04</code></td><td><code>UnauthorizedAccess</code></td><td>Caller is not walletAddress or registrantAddress</td></tr> <tr><td><code>0x05</code></td><td><code>AlreadyRegistered</code></td><td>Agent with this walletAddress already exists</td></tr> <tr><td><code>0x06</code></td><td><code>VerificationFailed</code></td><td>Verification provider returned an error</td></tr> <tr><td><code>0x07</code></td><td><code>InsufficientCredits</code></td><td>No verification credits available</td></tr> <tr><td><code>0x08</code></td><td><code>InvalidProof</code></td><td>PDV proof validation failed</td></tr> <tr><td><code>0x09</code></td><td><code>ProviderUnavailable</code></td><td>Verification provider is not responding</td></tr> <tr><td><code>0x0A</code></td><td><code>InvalidScore</code></td><td>Risk score outside valid range (0-100)</td></tr> <tr><td><code>0x0B</code></td><td><code>ContractNotFound</code></td><td>Specified contract does not exist on chain</td></tr> <tr><td><code>0x0C</code></td><td><code>StakingContractNotFound</code></td><td>Specified staking contract does not exist</td></tr> </tbody></table> <p>Implementations SHOULD revert with these error codes:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>error InvalidAddress();</span></span> <span class="giallo-l"><span>error InvalidURL();</span></span> <span class="giallo-l"><span>error AgentNotFound();</span></span> <span class="giallo-l"><span>error UnauthorizedAccess();</span></span> <span class="giallo-l"><span>error AlreadyRegistered();</span></span> <span class="giallo-l"><span>error VerificationFailed();</span></span> <span class="giallo-l"><span>error InsufficientCredits();</span></span> <span class="giallo-l"><span>error InvalidProof();</span></span> <span class="giallo-l"><span>error ProviderUnavailable();</span></span> <span class="giallo-l"><span>error InvalidScore();</span></span> <span class="giallo-l"><span>error ContractNotFound();</span></span> <span class="giallo-l"><span>error StakingContractNotFound();</span></span></code></pre><h3 id="interface">Interface</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"><span>pragma solidity ^0.8.0;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>interface IERCXXXX {</span></span> <span class="giallo-l"><span> /// @notice Emitted when a new agent is registered</span></span> <span class="giallo-l"><span> event AgentRegistered(</span></span> <span class="giallo-l"><span> bytes32 indexed agentId,</span></span> <span class="giallo-l"><span> address indexed walletAddress,</span></span> <span class="giallo-l"><span> address indexed registrantAddress,</span></span> <span class="giallo-l"><span> string name</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Emitted when an agent completes verification</span></span> <span class="giallo-l"><span> event AgentVerified(</span></span> <span class="giallo-l"><span> bytes32 indexed agentId,</span></span> <span class="giallo-l"><span> uint8 overallRiskScore,</span></span> <span class="giallo-l"><span> bytes32 etvProofId,</span></span> <span class="giallo-l"><span> bytes32 scvProofId,</span></span> <span class="giallo-l"><span> bytes32 wavProofId,</span></span> <span class="giallo-l"><span> bytes32 wvProofId,</span></span> <span class="giallo-l"><span> bytes32 summaryProofId</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Emitted when an agent&#39;s details are updated</span></span> <span class="giallo-l"><span> event AgentUpdated(</span></span> <span class="giallo-l"><span> bytes32 indexed agentId,</span></span> <span class="giallo-l"><span> address indexed updatedBy</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Emitted when verification credits are purchased</span></span> <span class="giallo-l"><span> event CreditsPurchased(</span></span> <span class="giallo-l"><span> bytes32 indexed agentId,</span></span> <span class="giallo-l"><span> address indexed purchaser,</span></span> <span class="giallo-l"><span> uint256 amount</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Register a new AI agent</span></span> <span class="giallo-l"><span> function registerAgent(</span></span> <span class="giallo-l"><span> string calldata name,</span></span> <span class="giallo-l"><span> string calldata description,</span></span> <span class="giallo-l"><span> address walletAddress,</span></span> <span class="giallo-l"><span> string calldata url,</span></span> <span class="giallo-l"><span> address contractAddress,</span></span> <span class="giallo-l"><span> address stakingContractAddress,</span></span> <span class="giallo-l"><span> uint256 platformId,</span></span> <span class="giallo-l"><span> uint256 chainId</span></span> <span class="giallo-l"><span> ) external returns (bytes32 agentId);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Get agent verification status and scores</span></span> <span class="giallo-l"><span> function getAgentVerification(bytes32 agentId) external view returns (</span></span> <span class="giallo-l"><span> bool isVerified,</span></span> <span class="giallo-l"><span> uint8 overallRiskScore,</span></span> <span class="giallo-l"><span> uint8 etvScore,</span></span> <span class="giallo-l"><span> uint8 scvScore,</span></span> <span class="giallo-l"><span> uint8 wavScore,</span></span> <span class="giallo-l"><span> uint8 wvScore</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Get agent proof details (restricted to wallet holder)</span></span> <span class="giallo-l"><span> /// @dev MUST only return data if msg.sender is walletAddress or registrantAddress</span></span> <span class="giallo-l"><span> function getAgentProofs(bytes32 agentId) external view returns (</span></span> <span class="giallo-l"><span> bytes32 etvProofId,</span></span> <span class="giallo-l"><span> string memory etvProofUrl,</span></span> <span class="giallo-l"><span> bytes32 scvProofId,</span></span> <span class="giallo-l"><span> string memory scvProofUrl,</span></span> <span class="giallo-l"><span> bytes32 wavProofId,</span></span> <span class="giallo-l"><span> string memory wavProofUrl,</span></span> <span class="giallo-l"><span> bytes32 wvProofId,</span></span> <span class="giallo-l"><span> string memory wvProofUrl,</span></span> <span class="giallo-l"><span> bytes32 summaryProofId,</span></span> <span class="giallo-l"><span> string memory summaryProofUrl</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Get basic agent information</span></span> <span class="giallo-l"><span> function getAgentInfo(bytes32 agentId) external view returns (</span></span> <span class="giallo-l"><span> string memory name,</span></span> <span class="giallo-l"><span> string memory description,</span></span> <span class="giallo-l"><span> address walletAddress,</span></span> <span class="giallo-l"><span> address registrantAddress,</span></span> <span class="giallo-l"><span> string memory url,</span></span> <span class="giallo-l"><span> address contractAddress,</span></span> <span class="giallo-l"><span> address stakingContractAddress</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="required-standards-justification">Required Standards Justification</h3> <p><strong>EIP-155 (Replay Protection)</strong>: Agent registrations involve wallet signatures. Without chain ID inclusion (<a href="https://wg-eips.ritovision.com/155/">EIP-155</a>), a registration signature on mainnet could be replayed on testnets or L2s, potentially creating conflicting agent records across chains.</p> <p><strong>EIP-712 (Typed Data Signing)</strong>: Registration requires users to sign structured data. <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> presents human-readable signing requests (e.g., "Register Agent: MyBot at 0x...") rather than opaque hashes, preventing phishing attacks where users unknowingly sign malicious transactions.</p> <p><strong>ERC-3009 (Transfer With Authorization)</strong>: Verification fees use x402 micropayments. <a href="https://wg-eips.ritovision.com/3009/">ERC-3009</a> enables gasless USDC transfers where the verification provider pays gas, improving UX by not requiring users to hold ETH for verification.</p> <p><strong>ERC-191 (Signed Data Standard)</strong>: Wallet verification requires proving wallet ownership. <a href="https://wg-eips.ritovision.com/191/">ERC-191</a> provides the standardised prefix for signed messages, ensuring compatibility across wallets and preventing signature malleability.</p> <h3 id="four-verification-types">Four Verification Types</h3> <p>The four verification types are presented in alphabetical order (ETV → SCV → WAV → WV) for clarity and consistency.</p> <p>The decision to implement four distinct verification types addresses different aspects of agent authenticity:</p> <ul> <li><strong>ETV</strong> validates on-chain presence and contract legitimacy, ensuring the agent has a legitimate blockchain footprint</li> <li><strong>SCV</strong> validates staking contract security, ensuring agents with staking mechanisms have secure and auditable contracts</li> <li><strong>WAV</strong> ensures the agent's web endpoint is accessible and secure, protecting users from phishing and vulnerable endpoints</li> <li><strong>WV</strong> confirms wallet legitimacy and checks against threat databases, preventing association with known malicious actors</li> </ul> <h3 id="off-chain-verification-1">Off-chain Verification</h3> <p>Verification is performed off-chain to:</p> <ol> <li>Eliminate gas costs for verification operations</li> <li>Enable complex verification logic that would be prohibitively expensive on-chain</li> <li>Allow verification criteria to evolve without requiring contract upgrades</li> <li>Enable multiple competing verification providers</li> </ol> <h3 id="provider-agnostic-design-1">Provider Agnostic Design</h3> <p>This standard intentionally separates the interface specification from implementation details. Any verification provider MAY implement compliant ETV, WV, WAV, SCV, PDV, and QCV services, enabling:</p> <ol> <li>Competition among verification providers</li> <li>Specialisation in different verification domains</li> <li>Geographic and jurisdictional flexibility</li> <li>Price competition benefiting users</li> </ol> <h3 id="privacy-first-architecture-with-pdv-1">Privacy-First Architecture with PDV</h3> <p>Verification results are processed through Private Data Verification (PDV) which generates Zero-Knowledge Proofs. This privacy-first approach:</p> <ol> <li>Eliminates data breach risks - no stored data means nothing to compromise</li> <li>Provides cryptographic proof of verification that third parties can validate</li> <li>Ensures GDPR and privacy regulation compliance</li> <li>Builds user trust through transparent, verifiable data handling</li> </ol> <h3 id="quantum-resistant-future-with-qcv-1">Quantum-Resistant Future with QCV</h3> <p>Verification providers MAY implement QCV for quantum-resistant encryption of sensitive verification data.</p> <ul> <li>SHOULD use AES-256-GCM or equivalent post-quantum encryption algorithm</li> <li>MUST return unique record_id for encrypted data</li> <li>MUST provide decryption_url for authorized data retrieval</li> <li>SHOULD ensure quantum-resistant key exchange mechanisms</li> </ul> <p>QCV Key Properties:</p> <ul> <li>Provides future-proof protection against quantum computing threats</li> <li>Military-grade encryption standards (AES-256-GCM)</li> <li>Enables secure long-term storage of verification records</li> </ul> <h3 id="owasp-alignment">OWASP Alignment</h3> <p>This standard recommends alignment with OWASP (Open Web Application Security Project) guidelines:</p> <ul> <li><strong>WAV</strong> SHOULD follow OWASP Web Security Testing Guide (WSTG) for endpoint security assessment</li> <li><strong>ETV/SCV</strong> SHOULD follow OWASP Smart Contract Security Verification Standard (SCSVS)</li> <li>Verification providers SHOULD check for OWASP Top 10 vulnerabilities in web applications</li> <li>Verification providers SHOULD check for Smart Contract Top 10 vulnerabilities in contracts</li> </ul> <p>OWASP alignment ensures verification follows industry-recognised security standards.</p> <h3 id="registration-fields">Registration Fields</h3> <p>The required fields (name, description, walletAddress, url) represent the minimum information needed to identify and interact with an AI agent. Optional fields (contractAddress, stakingContractAddress, platformId, chainId) allow for richer on-chain verification without imposing unnecessary requirements.</p> <h3 id="risk-scoring-approach">Risk Scoring Approach</h3> <p>A unified 0-100 risk scoring system allows:</p> <ul> <li>Easy comparison between agents</li> <li>Clear risk tier categorisation</li> <li>Weighted average calculation for overall assessment</li> <li>Actionable guidance based on score ranges</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC introduces a new standard and does not modify any existing standards. Existing AI agents can register with this standard without any modifications to their current implementations. It is designed to work alongside existing token standards (<a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>) and identity standards.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="registration-tests">Registration Tests</h3> <p><strong>Test: Successful Registration</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// Pseudocode</span></span> <span class="giallo-l"><span>function testSuccessfulRegistration() {</span></span> <span class="giallo-l"><span> bytes32 agentId = registry.registerAgent(</span></span> <span class="giallo-l"><span> &quot;MyAIAgent&quot;,</span></span> <span class="giallo-l"><span> &quot;A helpful assistant&quot;,</span></span> <span class="giallo-l"><span> 0x1234...5678, // walletAddress</span></span> <span class="giallo-l"><span> &quot;https://myagent.ai&quot;,</span></span> <span class="giallo-l"><span> address(0), // no contract</span></span> <span class="giallo-l"><span> address(0), // no staking contract</span></span> <span class="giallo-l"><span> 0, // platformId</span></span> <span class="giallo-l"><span> 1 // chainId (mainnet)</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> assert(agentId != bytes32(0));</span></span> <span class="giallo-l"><span> assert(registry.getAgentInfo(agentId).name == &quot;MyAIAgent&quot;);</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>Test: Invalid URL Rejection</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// Pseudocode</span></span> <span class="giallo-l"><span>function testInvalidURLRejection() {</span></span> <span class="giallo-l"><span> // Should revert with InvalidURL error</span></span> <span class="giallo-l"><span> expectRevert(InvalidURL.selector);</span></span> <span class="giallo-l"><span> registry.registerAgent(</span></span> <span class="giallo-l"><span> &quot;MyAIAgent&quot;,</span></span> <span class="giallo-l"><span> &quot;Description&quot;,</span></span> <span class="giallo-l"><span> 0x1234...5678,</span></span> <span class="giallo-l"><span> &quot;http://insecure.com&quot;, // HTTP not HTTPS - MUST fail</span></span> <span class="giallo-l"><span> address(0),</span></span> <span class="giallo-l"><span> address(0),</span></span> <span class="giallo-l"><span> 0,</span></span> <span class="giallo-l"><span> 1</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>Test: Duplicate Registration Rejection</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// Pseudocode</span></span> <span class="giallo-l"><span>function testDuplicateRejection() {</span></span> <span class="giallo-l"><span> registry.registerAgent(&quot;Agent1&quot;, &quot;Desc&quot;, 0x1234, &quot;https://a.com&quot;, ...);</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> // Same walletAddress - MUST revert</span></span> <span class="giallo-l"><span> expectRevert(AlreadyRegistered.selector);</span></span> <span class="giallo-l"><span> registry.registerAgent(&quot;Agent2&quot;, &quot;Desc&quot;, 0x1234, &quot;https://b.com&quot;, ...);</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="verification-tests">Verification Tests</h3> <ul> <li>MUST complete ETV when contractAddress is provided</li> <li>MUST complete WV for all registered agents</li> <li>MUST complete WAV for all registered agents</li> <li>MUST complete SCV when stakingContractAddress is provided</li> <li>MUST generate PDV proof for each verification type</li> <li>MUST calculate overallRiskScore as average of applicable scores</li> <li>MUST emit AgentVerified event with all proof IDs</li> <li>MUST revert with <code>VerificationFailed</code> on provider error</li> <li>MUST revert with <code>InsufficientCredits</code> when no credits available</li> </ul> <h3 id="access-control-tests">Access Control Tests</h3> <p><strong>Test: Unauthorized Proof Access</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// Pseudocode</span></span> <span class="giallo-l"><span>function testUnauthorizedProofAccess() {</span></span> <span class="giallo-l"><span> bytes32 agentId = registry.registerAgent(...); // registered by 0xAAAA</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> // Caller is 0xBBBB (not owner or registrant)</span></span> <span class="giallo-l"><span> vm.prank(0xBBBB);</span></span> <span class="giallo-l"><span> expectRevert(UnauthorizedAccess.selector);</span></span> <span class="giallo-l"><span> registry.getAgentProofs(agentId);</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li>MUST allow only walletAddress or registrantAddress to view proof URLs</li> <li>MUST allow only walletAddress or registrantAddress to edit agent details</li> <li>MUST allow anyone to view public agent information (excluding proofs)</li> <li>MUST revert with <code>UnauthorizedAccess</code> for unauthorized proof access</li> <li>MUST revert with <code>AgentNotFound</code> for non-existent agentId</li> </ul> <h3 id="risk-score-tests">Risk Score Tests</h3> <ul> <li>MUST return score 0-20 for Low Risk tier</li> <li>MUST return score 21-40 for Moderate tier</li> <li>MUST return score 41-60 for Elevated tier</li> <li>MUST return score 61-80 for High Risk tier</li> <li>MUST return score 81-100 for Critical tier</li> <li>MUST revert with <code>InvalidScore</code> for scores outside 0-100</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation will demonstrate:</p> <ul> <li>Agent self-registration with EIP-712 typed signing</li> <li>Four verification types (ETV, WV, WAV, SCV)</li> <li>PDV integration for Zero-Knowledge Proof generation</li> <li>x402 micropayment integration with <a href="https://wg-eips.ritovision.com/3009/">EIP-3009</a></li> <li>Risk scoring with five-tier classification</li> <li>Wallet-holder restricted proof access</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <h3 id="verification-trust">Verification Trust</h3> <p>Users MUST understand that verification through this standard indicates the agent has passed specific technical checks at a point in time, but does not guarantee the agent's future behaviour or intentions. Risk scores provide guidance but users should exercise their own judgment.</p> <h3 id="wallet-security">Wallet Security</h3> <p>Agents MUST secure their registered wallet addresses. Compromise of a wallet could allow an attacker to impersonate a legitimate agent. Re-verification is available to update risk scores.</p> <h3 id="url-hijacking">URL Hijacking</h3> <p>If an agent's URL is compromised after registration, the attacker could serve malicious content. Users SHOULD verify the current status of agents before interacting. WAV re-verification can detect compromised endpoints.</p> <h3 id="smart-contract-risks">Smart Contract Risks</h3> <p>For agents with registered contract addresses, standard smart contract security considerations apply. ETV and SCV provide initial verification but users SHOULD audit any contracts they interact with.</p> <h3 id="staking-contract-risks">Staking Contract Risks</h3> <p>Staking contracts present additional risks including locked funds, reward manipulation, and governance attacks. SCV verification checks common vulnerabilities but users SHOULD perform due diligence before staking with any agent.</p> <h3 id="zero-knowledge-proof-security">Zero-Knowledge Proof Security</h3> <p>PDV implementations SHOULD use established ZKP systems with proven security properties:</p> <ul> <li><strong>Circuit Soundness</strong>: Implementations SHOULD use audited circuits (e.g., Groth16, PLONK) with formal security proofs</li> <li><strong>Trusted Setup</strong>: Systems requiring trusted setup (e.g., Groth16) MUST use multi-party computation ceremonies to minimize trust assumptions</li> <li><strong>Proof Verification</strong>: On-chain proof verification MUST use battle-tested verifier contracts</li> <li><strong>Quantum Considerations</strong>: Current ZKP systems (based on elliptic curves) may be vulnerable to future quantum attacks. High-value, long-term proofs SHOULD consider QCV encryption as an additional layer</li> </ul> <h3 id="quantum-computing-threats">Quantum Computing Threats</h3> <p>Current cryptographic primitives face potential threats from quantum computing:</p> <ul> <li><strong>ECDSA Signatures</strong>: Vulnerable to Shor's algorithm on sufficiently powerful quantum computers</li> <li><strong>ZKP Schemes</strong>: Elliptic curve-based ZKPs (Groth16, PLONK) share quantum vulnerability</li> <li><strong>Mitigation</strong>: QCV provides AES-256-GCM encryption which remains quantum-resistant for symmetric operations. Implementations concerned with long-term security SHOULD use QCV for sensitive verification data</li> </ul> <h3 id="provider-trust">Provider Trust</h3> <p>Users MUST evaluate their trust in chosen verification providers. Different providers may have varying levels of thoroughness, independence, and reliability. Zero-Knowledge Proofs generated by PDV provide verifiable evidence of verification completion that can be independently validated.</p> <h3 id="attack-vectors">Attack Vectors</h3> <ul> <li><strong>Sybil Attacks</strong>: Malicious actors could register many agents. Mitigated by registration fees.</li> <li><strong>Front-Running</strong>: Registration transactions could be front-run. Consider commit-reveal schemes for sensitive registrations.</li> <li><strong>Provider Collusion</strong>: Verification providers could collude with malicious agents. Users SHOULD consider using multiple independent providers for high-stakes interactions.</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> 2025-01-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Valerio Massimo Camaianihttps://github.com/vmc-crossmint https://wg-eips.ritovision.com/7861/

An extension to ERC-721 that adds collection-wide verifiable credential properties, this allows native support for onchain credentials.

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> that adds verifiable credential properties at the contract level. A verifiable credential is a secure digital certificate that encapsulates claims issued by a trusted authority and is designed to be tamper-evident and readily verifiable. It allows <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens to natively reference and manage these credentials—as well as other types of off-chain data—by defining mechanisms for storage, encryption, revocation, and verification.</p> <h2 id="motivation">Motivation</h2> <p>Many <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> contracts require additional properties to represent verifiable credentials. While it's possible to implement these properties in various ways, it creates an extra effort for third-party platforms to build individualized solutions for each NFT collection.</p> <p>Having a standard for verifiable credential properties will make it easier for third-party platforms to interact with and validate NFTs that represent verifiable credentials onchain.</p> <p>Just as NFTs represent digital ownership, verifiable credentials (VCs) represent digital attestations about oneself (identity, education, and more). Blockchains provide an ideal solution for storing VCs and associated claims, offering precise access control, issuer legitimacy, and full lifecycle management for credentials, all while maintaining transparency to safeguard user rights.</p> <p>This standard addresses key gaps in the <a rel="external" href="https://www.w3.org/TR/2025/PR-vc-data-model-2.0-20250320/">W3C framework</a> by defining methods for storage, revocation, retrieval, and presentation, facilitating interoperability within a flexible, standardized structure. It supports custom cryptographic methods for signatures and proofs—from basic issuer signatures to advanced zero-knowledge (ZK) proofs and selective disclosure—allowing adaptability for diverse security requirements.</p> <p>Additionally, the standard natively supports encryption, crucial for managing sensitive data. It also provides flexibility in credential storage, referencing off-chain data via <code>credentialURI()</code> to accommodate any storage solution, from decentralized storage (like IPFS) to centralized systems.</p> <p>Originally designed with W3C credentials in mind, this standard is broad enough to support any kind of credential, for example content credentials. More generally this framework can be used to link any off-chain, private payload to an NFT.</p> <h3 id="standardized-credential-management">Standardized Credential Management</h3> <p>This extension aims to provide a standardized way to represent verifiable credentials within the ERC-721 framework. The collection-wide properties (<code>issuer</code> and <code>type</code>) allow for efficient management of credentials where these properties are shared across all tokens in the collection.</p> <p>The <code>credentialURI</code> function is included to provide a way to retrieve additional off-chain information about individual credentials, similar to the <code>tokenURI</code> function in ERC-721.</p> <p>By emitting <code>CredentialIssued</code> and <code>CredentialRevoked</code> events, third-party applications and services can track the lifecycle of credentials, enabling real-time monitoring.</p> <h2 id="specification">Specification</h2> <h3 id="overview">Overview</h3> <p>Each NFT in this standard is linked to a credential that can be stored in any compatible storage location. To retrieve credentials for a specific user, is sufficient to get the desired credential NFT in their wallet, and the <code>credentialURI()</code> function can provide the exact location of each credential. This URI may point to public storage like IPFS or any custom storage solution with flexible access control, potentially subject to user approval.</p> <p>Upon retrieval, credentials may be stored in clear text or in encrypted form. The <code>encryptionMethod()</code> property indicates the encryption status, allowing the verifier to know in advance if decryption is required. Decryption may involve user consent if the user's wallet signature is required. Additional steps can be added in cases where advanced algorithms enable selective disclosure or zero-knowledge (ZK) proofs to enhance privacy.</p> <p>Once decrypted, the credential's authenticity and integrity can be verified using the <code>verificationMethod()</code>, ensuring it remains untampered. For ZK proofs, specific queries can also be verified without disclosing the entire credential. The standard also accounts for credential revocation, which can be implemented in various ways: via burning the associated NFT, an additional structure in the contract or even an off-chain revocation list; in the first case, checking that the NFT is unburned confirms the credential's validity.</p> <p>While originally intended for verifiable credentials, this standard's flexibility allows it to link any private or external data payload to a user's wallet through an NFT, expanding its utility across various data-reference use cases.</p> <h3 id="interface">Interface</h3> <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-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-721 Verifiable Credential Extension</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7861</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span>, </span><span class="z-entity z-name">IERC721</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 new credential is issued</span></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 of the issued credential</span></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 credential was issued</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CredentialIssued</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"> 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"> @notice</span><span class="z-comment"> Emitted when a credential is 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"> The token ID of the revoked credential</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CredentialRevoked</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"> Get the issuer of the credential collection</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The empty string indicates that there is no issuer</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"> issuer DID or address for this credential collection </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">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"> Get the type of the credentials in the collection</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"> credential type for this collection</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> credentialType</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"> Get the encryption method of the credentials in the collection</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"> encryption method for this collection, will return empty string if not encrypted</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> encryptionMethod</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"> Get the verification method of the credentials in the collection</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"> verification method for this collection</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verificationMethod</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"> Get the URI for a given credential</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 credential URI 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"> credential URI for the given NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> credentialURI</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Check if a credential has 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"> The credential ID to check </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"> false</span><span class="z-comment"> if the credential has not been revoked</span></span> <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">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>issuer()</code>, <code>credentialType()</code>, <code>encryptionMethod()</code>, <code>verificationMethod()</code> and <code>credentialURI(uint256 tokenId)</code> functions MUST be implemented as view functions.</p> <p>The <code>encryptionMethod()</code> function MUST return an empty string if and only if the credential is unencrypted. In case of encrypted credentials the method SHOULD return only the encryption method; Any additional encryption details required for decryption MAY be retrieved separately (a separate function or via the contract metadata).</p> <p>The <code>verificationMethod()</code> function MUST return the method to verify the credential proof, the response is up to the implementer but SHOULD be compatible with the W3C <a rel="external" href="https://www.w3.org/TR/2025/PR-vc-data-integrity-20250320/#dfn-verification-method">verification method</a> concept.</p> <p>The <code>credentialURI(uint256 tokenId)</code> function MAY be used to retrieve the credential location. In case a given implementation uses a different method to retrieve the credential, <code>credentialURI(uint256 tokenId)</code> MUST return an empty string.</p> <p>The <code>supportsInterface</code> <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> method MUST return true when called with <code>0x7861069</code>.</p> <p>The <code>isRevoked(uint256 tokenId)</code> MUST return false if the credential has not been revoked, and MUST return true if the credential has been revoked. MAY return true if the credential does not exist.</p> <p>The <code>CredentialIssued</code> and <code>CredentialRevoked</code> events MAY be emitted, when the corresponding operations are performed, to allow off-chain systems to monitor credential status efficiently. Credential revocation is not mandated, but MAY be implemented via burning the associated NFT.</p> <h2 id="rationale">Rationale</h2> <!-- TODO --> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with current <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standards. It adds new functions without modifying the existing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> functionality.</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"> ^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/ERC721.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC7861.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"> ERC7861</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">IERC7861</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> immutable</span><span> _issuer</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> immutable</span><span> _credentialType</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> immutable</span><span> _verificationMethod</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> immutable</span><span> _encryptionMethod</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"> CredentialIssued</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"> to</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"> CredentialRevoked</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> <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"> 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"> symbol_</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"> issuer_</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"> credentialType_</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"> verificationMethod_</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-keyword"> require</span><span>(</span><span class="z-support">bytes</span><span>(</span><span>issuer_</span><span>)</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;ERC7861: issuer cannot be empty&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-support">bytes</span><span>(</span><span>credentialType_</span><span>)</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;ERC7861: credential type cannot be empty&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _issuer </span><span class="z-keyword">=</span><span> issuer_</span><span>;</span></span> <span class="giallo-l"><span> _credentialType </span><span class="z-keyword">=</span><span> credentialType_</span><span>;</span></span> <span class="giallo-l"><span> _verificationMethod </span><span class="z-keyword">=</span><span> verificationMethod_</span><span>;</span></span> <span class="giallo-l"><span> _encryptionMethod </span><span class="z-keyword">=</span><span class="z-string"> &quot;lit-protocol&quot;</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Example decentralized encryption</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"> 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-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> _issuer</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"> credentialType</span><span>(</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"> 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> _credentialType</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"> encryptionMethod</span><span>(</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"> 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> _encryptionMethod</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"> verificationMethod</span><span>(</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"> 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> _verificationMethod</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"> credentialURI</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-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"> 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;ERC7861: URI query for nonexistent token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Implementation depends on how you want to store/generate URIs</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-string"> &quot;&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"> isRevoked</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-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-comment"> //</span><span class="z-comment"> Implementation depends on revokation system, example for revokation on burning</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-keyword"> !</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> }</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"> See {IERC165-supportsInterface}.</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"> 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">IERC165</span><span>,</span><span class="z-entity z-name"> ERC721</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> interfaceId </span><span class="z-keyword">==</span><span class="z-support"> bytes4</span><span>(</span><span class="z-constant">0x74699c4e</span><span>)</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Issues a new credential to an 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"> The address to issue the credential 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"> tokenId</span><span class="z-comment"> The token ID of the credential</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> issueCredential</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 class="z-comment"> //</span><span class="z-comment"> Implement access control as needed</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-keyword"> emit</span><span class="z-entity z-name"> CredentialIssued</span><span>(</span><span>tokenId</span><span>,</span><span> to</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"> @notice</span><span class="z-comment"> Revokes an existing credential</span></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 of the credential to revoke</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeCredential</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 class="z-comment"> //</span><span class="z-comment"> Implement access control as needed</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;ERC7861: Cannot revoke nonexistent credential&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _burn</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"> CredentialRevoked</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>Implementers of the <a href="https://wg-eips.ritovision.com/7861/">ERC-7861</a> standard must enforce strict access control to ensure only authorized parties can issue or revoke credentials. Implementers must also carefully consider access control for setting credential properties, protecting the integrity of the collection's credential information.</p> <p>Credentials should be non-transferable to maintain authenticity and prevent unauthorized transfers. Override transfer functions to enforce this if needed.</p> <p>The <code>credentialURI</code> should not contain sensitive information, as it is publicly accessible. Sensitive data should be encrypted and stored off-chain, with the <code>credentialURI</code> pointing to the location of this encrypted data; encryption is essential for any sensitive data stored on public storage solutions like IPFS.</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-06T00:00:00+00:00 2026-02-11T14:48:25+00:00 Prem Makeighttps://github.com/nxt3d https://wg-eips.ritovision.com/8119/

A format for parameterized string keys used in EVM key-value storage.

<h2 id="abstract">Abstract</h2> <p>This ERC defines a standard format for parameterized string keys used in EVM key-value storage using a forward slash (<code>/</code>) separator between the key label and its parameter.</p> <h2 id="motivation">Motivation</h2> <p>Many EVM-based smart contracts use key-value storage to store metadata where string keys may need to represent multiple instances or variations of the same metadata type. Without a standardized format for parameterized keys, different implementations use inconsistent formats, leading to interoperability issues and parsing difficulties.</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="key-format">Key Format</h3> <p>String keys used in EVM key-value storage MAY include parameters to represent variations or instances of a metadata type. When keys include parameters, they MUST follow the format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&lt;key-label&gt;/&lt;key-parameter&gt;</span></span></code></pre> <p>Where:</p> <ul> <li><strong><code>&lt;key-label&gt;</code></strong>: MUST contain only printable ASCII characters <strong>except</strong> space and the forward slash character. Concretely, allowed code points are <code>0x21-0x2E</code> and <code>0x30-0x7E</code> (letters, digits, and common punctuation), explicitly excluding control characters (<code>0x00-0x1F</code>), space (<code>0x20</code>), the slash character (<code>0x2F</code>), and DEL (<code>0x7F</code>). The key-label identifies the type or category of metadata.</li> <li><strong><code>&lt;key-parameter&gt;</code></strong>: MAY be any UTF-8 encoded string. The parameter value represents a specific instance or variation of the metadata type.</li> </ul> <p><strong>Examples:</strong></p> <ul> <li><code>"registration/1"</code> - ASCII key-label with numeric parameter</li> <li><code>"user/alice"</code> - ASCII key-label with ASCII parameter</li> <li><code>"name/María"</code> - ASCII key-label with UTF-8 parameter (Spanish)</li> <li><code>"description/说明"</code> - ASCII key-label with UTF-8 parameter (Chinese)</li> <li><code>"title/タイトル"</code> - ASCII key-label with UTF-8 parameter (Japanese)</li> <li><code>"label/Étiquette"</code> - ASCII key-label with UTF-8 parameter (French with accent)</li> <li><code>"%gain/50"</code> - Key-label with special character (percent)</li> <li><code>"$price/100"</code> - Key-label with special character (dollar sign)</li> <li><code>"#tag/featured"</code> - Key-label with special character (hash)</li> </ul> <p><strong>Invalid formats:</strong></p> <ul> <li><code>"registration-1"</code> (hyphen separator)</li> <li><code>"registration:1"</code> (colon separator)</li> <li><code>"registration1"</code> (no separator)</li> <li><code>"key label/value"</code> (space in key-label)</li> </ul> <p>This format provides a clean, consistent way to represent parameterized keys while maintaining readability and compatibility with parsers that support the slash (<code>/</code>) separator format.</p> <h3 id="format-specification">Format Specification</h3> <p>For string keys used in EVM key-value storage (e.g., <code>mapping(string =&gt; bytes)</code> in Solidity, hash maps in Vyper, or equivalent structures in other EVM-compatible languages):</p> <ol> <li>The <code>&lt;key-label&gt;</code> MUST contain only printable ASCII characters (0x21-0x7E), excluding spaces and the forward slash character (<code>/</code>). This excludes control characters, space, <code>/</code>, and DEL.</li> <li>The <code>&lt;key-label&gt;</code> and <code>&lt;key-parameter&gt;</code> MUST be separated by a single forward slash (<code>/</code>).</li> <li>The <code>&lt;key-parameter&gt;</code> MAY be any UTF-8 encoded string, including strings that contain <code>/</code>. Parsing uses the first occurrence of <code>/</code> as the separator; all subsequent characters belong to the parameter.</li> <li>This ERC specifies <strong>exactly one</strong> parameter per key. If an application needs additional sub-parameters, it MAY encode them inside the single parameter value using any application-defined encoding (for example, a space-separated list).</li> </ol> <h2 id="rationale">Rationale</h2> <p>The forward slash (<code>/</code>) separator was chosen because:</p> <ul> <li>It provides a clear, unambiguous separator that is easy to parse programmatically</li> <li>It is visually concise while still being readable compared to formats like <code>key:value</code> or <code>key-value</code></li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC is fully backwards compatible. Existing implementations that do not use parameterized keys are unaffected. Implementations using non-standard parameter formats may continue to work but are encouraged to migrate to this standard format for better interoperability.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="valid-key-formats">Valid Key Formats</h3> <ul> <li><code>"name"</code> - Simple key without parameters</li> <li><code>"registration/1"</code> - Key with numeric parameter</li> <li><code>"registration/2"</code> - Key with numeric parameter</li> <li><code>"user/alice"</code> - Key with ASCII string parameter</li> <li><code>"session/abc123"</code> - Key with alphanumeric parameter</li> <li><code>"name/María"</code> - Key with UTF-8 parameter (Spanish)</li> <li><code>"description/说明"</code> - Key with UTF-8 parameter (Chinese)</li> <li><code>"title/タイトル"</code> - Key with UTF-8 parameter (Japanese)</li> <li><code>"label/Étiquette"</code> - Key with UTF-8 parameter (French with accent)</li> <li><code>"key/value:with:colons"</code> - Key with parameter containing colons</li> <li><code>"key/one1 two2 three3"</code> - Key whose single parameter can be interpreted by an application as a list</li> <li><code>"key/value/with/slashes"</code> - Key with parameter containing additional <code>/</code> (parsed at first <code>/</code>)</li> <li><code>"excerpt/Dan said \"hi: how are you?\""</code> - Key with quoted speech containing <code>: </code></li> </ul> <h3 id="invalid-key-formats">Invalid Key Formats</h3> <ul> <li><code>"registration-1"</code> - Uses hyphen instead of slash</li> <li><code>"registration:1"</code> - Uses colon instead of slash</li> <li><code>"registration1"</code> - No separator</li> <li><code>"key label/value"</code> - Space in key-label (key-label must be ASCII with no spaces)</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>The following is a Solidity reference implementation. This standard applies to all EVM-compatible languages (Solidity, Vyper, etc.) that support string-keyed storage.</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.25</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Strings</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/Strings.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"> KeyParametersExample</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">string</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bytes</span><span>)</span><span class="z-storage z-type"> private</span><span> _metadata</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> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Save three values</span></span> <span class="giallo-l"><span class="z-entity z-name"> setMetadata</span><span>(</span><span class="z-string">&quot;registration/1&quot;</span><span>,</span><span class="z-support"> bytes</span><span>(</span><span class="z-string">&quot;example1&quot;</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> setMetadata</span><span>(</span><span class="z-string">&quot;registration/2&quot;</span><span>,</span><span class="z-support"> bytes</span><span>(</span><span class="z-string">&quot;example2&quot;</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> setMetadata</span><span>(</span><span class="z-string">&quot;registration/3&quot;</span><span>,</span><span class="z-support"> bytes</span><span>(</span><span class="z-string">&quot;example3&quot;</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"> Read them all back</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</span><span> i </span><span class="z-keyword">=</span><span class="z-constant"> 1</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span class="z-constant"> 3</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"> string</span><span class="z-storage z-type"> memory</span><span> key </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 class="z-string">&quot;registration/&quot;</span><span>,</span><span> Strings</span><span>.</span><span class="z-entity z-name">toString</span><span>(</span><span>i</span><span>)</span><span>)</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> value </span><span class="z-keyword">=</span><span class="z-entity z-name"> getMetadata</span><span>(</span><span>key</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>value</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> }</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"> setMetadata</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> key</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> _metadata</span><span>[</span><span>key</span><span>]</span><span class="z-keyword"> =</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-storage z-type"> function</span><span class="z-entity z-name"> getMetadata</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</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">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> _metadata</span><span>[</span><span>key</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> <ul> <li><strong>User-facing input</strong>: When keys are derived from user input, clients SHOULD validate <code>&lt;key-label&gt;</code> against the allowed ASCII range and reject labels containing spaces or <code>/</code> to avoid ambiguous or non-standard keys.</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> 2025-01-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Bogdan Gusievhttps://github.com/bogdan Sergey Bomkohttps://github.com/aquiladev https://wg-eips.ritovision.com/7876/

EVM-compatible network configuration specification for DApps supporting any custom network features through extensions.

<h2 id="abstract">Abstract</h2> <p>This standard defines a universal format for specifying network configurations to decentralized applications (DApps). The configuration includes essential information about Ethereum networks, such as available RPC URLs, native currencies, contract addresses, and block explorers. Configurations are intended to be provided by:</p> <ul> <li>Network maintainers to make sure their network is supported by DApps.</li> <li>Smart contract developers to ensure the smart contracts are properly integrated into DApps and changes are consistently delivered.</li> <li>DApp developers internally in the organization to make use of software libraries designed around the standard and maintain consistent configuration across multiple platforms (e.g., iOS, Android).</li> </ul> <p>Given that different EVM-compatible chains introduce unique features, this standard also supports extensibility, allowing networks to specify additional configuration parameters beyond the base requirements. This flexibility prevents networks from resorting to external storage for their unique configurations, preserving the goal of a unified and comprehensive network configuration standard.</p> <h2 id="motivation">Motivation</h2> <p>Currently, decentralized applications (DApps) support numerous EVM-compatible networks and often define network configurations in inconsistent formats, which complicates interoperability and sharing of configurations. This standard introduces a <strong>unified network configuration</strong> format that can be adopted by EVM-based networks, making it easier for developers to integrate with multiple networks and providing consistent configuration management.</p> <p>The proposed configuration format includes essential details required by DApps, including:</p> <ul> <li>Network name and ID</li> <li>RPC URL for Ethereum nodes</li> <li>Native currency details</li> <li>Smart contract addresses</li> <li>Available block explorers and NFT marketplaces</li> </ul> <p>The goal of this standard is to simplify network configuration for DApp developers and enhance interoperability across Ethereum-compatible networks.</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 configuration <strong>MUST</strong> use a JSON object, which DApp developers can use to define multiple Ethereum networks.</p> <h3 id="interface-definition">Interface definition</h3> <p>The specification interface is provided in the TypeScript type definition format, which is widely used to define JSON file formats for Ethereum DApps. Refer to <a href="https://wg-eips.ritovision.com/7876/#example-configuration">Example Configuration</a> for an illustrative implementation of this standard.</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * Represents the configuration for a smart 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-storage z-type">@</span><span class="z-storage z-type">typedef</span><span class="z-entity z-name"> ContractConfig</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> address - The address of the contract on the Ethereum network. **MUST** use a checksum.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> abiUrl - URL to contract ABI file, can be relative to `abiRoot` if specified or absolute. The absence of the key or `null` value indicates that the ABI of the contract is unknown. URL content **MUST** use Contract ABI specification JSON format.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> blockCreated - The block number in which the contract was deployed.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">see</span><span class="z-variable z-other"> https://docs.soliditylang.org/en/latest/abi-spec.html#json</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">see</span><span class="z-entity z-name"> .</span><span class="z-comment">/00055.md</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">see</span><span class="z-variable z-other"> https://url.spec.whatwg.org</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">type</span><span class="z-entity z-name"> ContractConfig</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-keyword">:</span><span class="z-entity z-name"> Address</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> abiUrl</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span class="z-keyword"> |</span><span class="z-support"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> blockCreated</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * Represents a list of contract names. No standard contracts are defined.</span></span> <span class="giallo-l"><span class="z-comment"> * The list may vary from one DApp to another for the same network.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">typedef</span><span class="z-entity z-name"> ContractName</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">type</span><span class="z-entity z-name"> ContractName</span><span class="z-keyword"> =</span><span class="z-support"> string</span><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"> * Represents the configuration for block explorers in the network configuration.</span></span> <span class="giallo-l"><span class="z-comment"> * The URLs for address, transaction, and NFT lookups are **relative** to the `root` URL.</span></span> <span class="giallo-l"><span class="z-comment"> * URLs **MUST** be relative to the `root` URL.</span></span> <span class="giallo-l"><span class="z-comment"> * URLs **MUST** include special parameters, like `:block`, `:address`, `:tx`, `:token` for relevant properties (see examples).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">typedef</span><span class="z-entity z-name"> ExplorerConfig</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> root - The root URL of the block explorer (e.g., `https://freescan.example.com`).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> block - The relative URL path for viewing a specific block (e.g., `/block/:block`). If not available, this can be `null`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> address - The relative URL path for viewing a specific address (e.g., `/address/:address`). If not available, this can be `null`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> tx - The relative URL path for viewing a transaction (e.g., `/tx/:tx`). If not available, this can be `null`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> nft - The relative URL path for viewing a specific NFT (e.g., `/nft/:address/:token`). If not available, this can be `null`.</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">type</span><span class="z-entity z-name"> ExplorerConfig</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> root</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-keyword">:</span><span class="z-support"> string</span><span class="z-keyword"> |</span><span class="z-support"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> tx</span><span class="z-keyword">:</span><span class="z-support"> string</span><span class="z-keyword"> |</span><span class="z-support"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> nft</span><span class="z-keyword">:</span><span class="z-support"> string</span><span class="z-keyword"> |</span><span class="z-support"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> block</span><span class="z-keyword">:</span><span class="z-support"> string</span><span class="z-keyword"> |</span><span class="z-support"> null</span><span>,</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-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * Represents RPC node endpoints available in the network.</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">typedef</span><span class="z-entity z-name"> RpcConfig</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> url - The URL under which the RPC is available (e.g. `https://public-node.example.com/rpc`).</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">type</span><span class="z-entity z-name"> RpcConfig</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> url</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-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * Represents relation of the network to other networks.</span></span> <span class="giallo-l"><span class="z-comment"> * e.g. a network is a testnet of a mainnet, a network is Layer 2 above some other network,</span></span> <span class="giallo-l"><span class="z-comment"> * a network has a bridge to another network, etc.</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">typedef</span><span class="z-entity z-name"> RelationsConfig</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> mainnetChainId - Chain ID of the recommended mainnet network if current network is a testnet. MUST be `null` for mainnet.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> parentChainId - Chain ID of a network that current network is built on top of (e.g. if current network is L2, it will be L1 chain id)</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">type</span><span class="z-entity z-name"> RelationsConfig</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> mainnetChainId</span><span class="z-keyword">:</span><span class="z-support"> number</span><span class="z-keyword"> |</span><span class="z-support"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> parentChainId</span><span class="z-keyword">:</span><span class="z-support"> number</span><span class="z-keyword"> |</span><span class="z-support"> null</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-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * Represents the configuration for the native currency used in the network.</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">typedef</span><span class="z-entity z-name"> NativeCurrencyConfig</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> name - The name of the native currency (e.g., &quot;Ether&quot;).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> symbol - The symbol of the native currency (e.g., &quot;ETH&quot;).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> decimals - The number of decimal places the currency uses (e.g., 18 for Ether).</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">type</span><span class="z-entity z-name"> NativeCurrencyConfig</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * Represents the configuration for a specific Ethereum network used in the DApp.</span></span> <span class="giallo-l"><span class="z-comment"> * This includes details such as the network name, testnet status, RPC configurations,</span></span> <span class="giallo-l"><span class="z-comment"> * explorers, and smart contracts related to the network.</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">typedef</span><span class="z-entity z-name"> NetworkConfig</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> name - The name of the network (e.g., &quot;Ethereum&quot;, &quot;Base&quot;).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> testnet - A flag indicating whether the network is a testnet (`true`) or mainnet (`false`).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> nativeCurrency - Configuration for the network&#39;s native currency (e.g., ETH).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> relations - Relationships with other networks (e.g., parent network or L1/L2 or other bridged networks).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> rpcs - A record of RPC configurations for different nodes in the network, where keys represent the node names (e.g., &quot;publicnode&quot;).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> explorers - Optional record for block explorer configurations (e.g., nft marketplaces).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> contracts - A record of contract configurations where the values may be `null` if the contract is not deployed.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">see</span><span class="z-variable z-other"> https://url.spec.whatwg.org</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">type</span><span class="z-entity z-name"> NetworkConfig</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"> testnet</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> nativeCurrency</span><span class="z-keyword">:</span><span class="z-entity z-name"> NativeCurrencyConfig</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> relations</span><span class="z-keyword">:</span><span class="z-entity z-name"> RelationsConfig</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> rpcs</span><span class="z-keyword">:</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"> RpcConfig</span><span class="z-keyword"> |</span><span class="z-support"> null</span><span>&gt;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> explorers</span><span class="z-keyword">:</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"> ExplorerConfig</span><span class="z-keyword"> |</span><span class="z-support"> null</span><span>&gt;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> contracts</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-entity z-name">ContractName</span><span>,</span><span class="z-entity z-name"> ContractConfig</span><span class="z-keyword"> |</span><span class="z-support"> null</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-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * Represents the configuration for a DApp, including version information, a summary,</span></span> <span class="giallo-l"><span class="z-comment"> * an optional description, and the network configurations.</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">typedef</span><span class="z-entity z-name"> {</span><span class="z-entity z-name">Object</span><span class="z-entity z-name">}</span><span class="z-entity z-name"> Configuration</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> version - The version of the configuration, typically following semantic versioning (e.g., &quot;1.0.0&quot;).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> timestamp - The timestamp in ISO 8601-compatible format of when the configuration was last updated (e.g., &quot;2025-01-01T12:00:00Z&quot;).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> abiRoot - Optional root URL for the ABI (Application Binary Interface) if it is hosted externally.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> summary - A brief summary or title for the configuration (e.g., &quot;RealPhotos Network Configuration&quot;).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> description - An optional detailed description of the configuration and its purpose.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">property</span><span class="z-comment"> networks - A record of network configurations, where keys represent the network IDs (e.g., &quot;1&quot; for ethereum mainnet).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">see</span><span class="z-variable z-other"> https://url.spec.whatwg.org/</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">see</span><span class="z-variable z-other"> https://semver.org</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">see</span><span class="z-variable z-other"> https://www.iso.org/obp/ui/en/#iso:std:iso:8601:-1:ed-1:v1:en</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-keyword">export</span><span class="z-keyword"> default</span><span class="z-variable z-other"> type</span><span class="z-variable z-other"> Configuration</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span> version</span><span>:</span><span class="z-variable z-other"> string</span><span>,</span></span> <span class="giallo-l"><span> timestamp</span><span>:</span><span class="z-variable z-other"> string</span><span>,</span></span> <span class="giallo-l"><span> summary</span><span>:</span><span class="z-variable z-other"> string</span><span>,</span></span> <span class="giallo-l"><span> description</span><span>:</span><span class="z-variable z-other"> string</span><span>,</span></span> <span class="giallo-l"><span> abiRoot</span><span>:</span><span class="z-variable z-other"> string</span><span class="z-keyword"> |</span><span class="z-constant"> null</span><span>,</span></span> <span class="giallo-l"><span> networks</span><span>:</span><span class="z-variable z-other"> Record</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">string</span><span>,</span><span> NetworkConfig&gt;</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h3 id="contracts">Contracts</h3> <p>Contracts listed <strong>SHOULD</strong> be limited to the subset necessary to perform specific functionality, as defined by the configuration author.</p> <p>Implementations <strong>MUST</strong> ensure that contract names are consistent across all networks. While the contract binary code deployed to different networks under the same name in the configuration can differ, implementations <strong>SHOULD</strong> ensure they represent different versions of the same contract. Differences <strong>SHOULD</strong> be communicated through additional custom properties or different <code>abiUrl</code>. See <a href="https://wg-eips.ritovision.com/7876/#extensions">Extensions</a>.</p> <p>Inlining contract ABIs <strong>MUST NOT</strong> be used to ensure effective memory management is possible in resource-constrained environments.</p> <p>It is <strong>RECOMMENDED</strong> for a contract name to match the name in Solidity source code if the contract bytecode is verified on block explorers.</p> <p>If a contract is not deployed on a specific network, the value <code>null</code> <strong>MUST</strong> explicitly indicate the absence of a contract.</p> <h3 id="extensions">Extensions</h3> <p>Implementations <strong>MUST</strong> ignore non-documented properties or support their interpretation where technically feasible. This ensures the standard remains adaptable to future use cases, enabling developers to extend configurations without breaking compatibility. See <a href="https://wg-eips.ritovision.com/7876/#example-extensions">Example Extensions</a>.</p> <p>Non-documented properties <strong>SHOULD</strong> support new features or extensions, but they <strong>MUST NOT</strong> modify or extend the basic types of existing properties. Union types <strong>SHOULD NOT</strong> be used in extensions. Their usage contradicts the <a href="https://wg-eips.ritovision.com/7876/#rationale">Rationale</a> of the standard. See <a href="https://wg-eips.ritovision.com/7876/#incorrect-extension">Incorrect Extension Example</a>.</p> <p>Extensions <strong>SHOULD</strong> use extensible data structures by making sure additional properties can be added at any configuration layer.</p> <p>Example of rigid and extensible data structures:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span># </span><span class="z-variable z-other">Rigid</span><span class="z-variable z-other"> data</span><span class="z-variable z-other"> structure</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> RigidConfiguration</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> documentationUrls</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>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># </span><span class="z-variable z-other">Extensible</span><span class="z-variable z-other"> data</span><span class="z-variable z-other"> structure</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> ExtensibleConfiguration</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> documentation</span><span class="z-keyword">:</span><span> {</span><span class="z-variable"> url</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span><span>[</span><span>]</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The design of this standard leverages the following key goals:</p> <h3 id="1-availability-and-distribution">1. Availability and Distribution</h3> <p>Use JSON as a universally supported data interchange format, with libraries available in virtually all modern programming languages and platforms. This ensures:</p> <ul> <li><strong>Cross-Platform Compatibility</strong>: Developers can easily parse and generate JSON regardless of their tech stack.</li> <li><strong>Ease of Integration</strong>: Existing tools and frameworks already support JSON natively, reducing implementation overhead.</li> <li><strong>Built-in Data Types</strong>: JSON provides sufficient data types to describe all necessary configurations semantically, eliminating the need for manual typecasting.</li> <li><strong>Multi-network Support</strong>: The configuration supports multiple networks, ensuring projects deployed to multiple networks can propagate their configurations faster and more consistently.</li> </ul> <h3 id="2-readability-by-an-engineer">2. Readability by an Engineer</h3> <p>The human-readable structure makes it ideal for configuration files:</p> <ul> <li><strong>Clarity</strong>: JSON's key-value pair format is intuitive and easy to understand for engineers.</li> <li><strong>Debugging</strong>: Developers can quickly inspect and troubleshoot configurations directly in text editors or IDEs.</li> <li><strong>Simplicity</strong>: Its simplicity ensures that even less experienced developers can comprehend and modify configurations without extensive training.</li> <li><strong>Human Names</strong>: Fields like <code>name</code> and <code>description</code> provide context and improve usability for engineers working with the configuration.</li> </ul> <h3 id="3-openness-for-extensions">3. Openness for Extensions</h3> <p>This standard is designed to support extensions by using JSON objects rather than rigid structures like basic types or arrays.</p> <ul> <li><strong>Forward Compatibility</strong>: Unrecognized properties can be safely ignored or leveraged without breaking existing implementations.</li> <li><strong>Customizability</strong>: Developers can add additional fields to accommodate specific requirements, such as API keys or advanced metadata.</li> <li><strong>Scalability</strong>: Future updates to the standard can include new attributes while maintaining backwards compatibility.</li> </ul> <p>See <a href="https://wg-eips.ritovision.com/7876/#extensions">Extensions</a>.</p> <h3 id="4-use-of-chain-id-as-a-unique-network-identifier">4. Use of Chain ID as a Unique Network Identifier</h3> <p>This standard uses the <strong>chain ID</strong> as the unique identifier for networks rather than custom names because:</p> <ul> <li><strong>Standardization</strong>: Chain IDs are part of the Ethereum specification and are globally recognized, ensuring consistency.</li> <li><strong>No Collisions</strong>: Unlike custom names, chain IDs are unique, preventing conflicts between networks.</li> <li><strong>Interoperability</strong>: Using chain IDs aligns with existing Ethereum tooling and standards, making integrations seamless across diverse environments.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard emphasizes extensibility while maintaining backward compatibility where feasible. It ensures adaptability to the evolving requirements of Ethereum network configurations by prioritizing flexibility in its structure.</p> <h3 id="1-compatibility-with-eip-3085">1. Compatibility with <a href="https://wg-eips.ritovision.com/3085/">EIP-3085</a></h3> <p>This standard aligns with <a href="https://wg-eips.ritovision.com/3085/">EIP-3085</a>, the Ethereum standard for wallet Add Ethereum Chain requests, wherever applicable. However, it diverges in scenarios where EIP-3085's rigid structure limits future enhancements.</p> <p>By prioritizing extensibility over strict adherence to EIP-3085, this standard ensures compatibility with existing tools while enabling future-proof enhancements to network configurations.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="example-configuration">Example Configuration</h3> <p>Below is an example configuration for an <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> project deployed to Ethereum Mainnet and Sepolia. This illustrates how the standard can represent multi-network setups.</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">version</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0.0.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">timestamp</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2025-01-01T12:22:46.471Z</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">summary</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">NFT Artwork</span><span class="z-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">Artwork published by independent artist. Carefully crafted with style in one of the creative studios of the world.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">abiRoot</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://nft-artwork.example.com/developer/abi</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">networks</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">1</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">Ethereum Mainnet</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">testnet</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">nativeCurrency</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">Ether</span><span class="z-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">ETH</span><span class="z-punctuation z-definition z-string">&quot;</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">rpcs</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">main</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">url</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://eth-rpc.example.com</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">backup</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">url</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://eth-rpc.backup.example.com</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">relations</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">mainnetChainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">parentChainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</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">explorers</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">megascan</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">root</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://example.org</span><span class="z-punctuation z-definition z-string">&quot;</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">/block/: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">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">/address/: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">tx</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">/tx/:tx</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">nft</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">/nft/:address/:token</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">marketplace</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">root</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://nft.marketplace/networks/eth</span><span class="z-punctuation z-definition z-string">&quot;</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"> null</span><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">/: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">tx</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">nft</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">/:address/:token</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">contracts</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">Registry</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">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x57928ff7b0BBc3Ee4D84481e320DdB8B941f986A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">blockCreated</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1234567</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">abiUrl</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">./Registry.sol/Registry.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">OwnerWallet</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">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xC12237E57B088e9191BD8054Df4f5B772646a4B6</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">blockCreated</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</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">11155111</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">Sepolia</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">testnet</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">nativeCurrency</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">Sepolia Ether</span><span class="z-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">ETH</span><span class="z-punctuation z-definition z-string">&quot;</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">rpcs</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">main</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">url</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://sepolia-rpc.example.com</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">backup</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">url</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://sepolia-rpc.backup.example.com</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">relations</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">mainnetChainId</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">parentChainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</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">explorers</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">megascan</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">root</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://sepolia.example.org</span><span class="z-punctuation z-definition z-string">&quot;</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">/block/: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">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">/address/: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">tx</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">/tx/:tx</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">nft</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">/nft/:address/:token</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">marketplace</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">root</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://testnets.nft.marketplace/networks/sepolia</span><span class="z-punctuation z-definition z-string">&quot;</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"> null</span><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">/: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">tx</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">nft</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">/:address/:token</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">contracts</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">Registry</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">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xE13471e6E5d11205AF290261f42108f89dCae72E</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">blockCreated</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 183882</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">abiUrl</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">./Registry.sol/Registry.json</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">OwnerWallet</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">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xC12237E57B088e9191BD8054Df4f5B772646a4B6</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">blockCreated</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</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><em>Note</em>: It is <strong>RECOMMENDED</strong> to use a two-space indentation format for better readability and debugging.</p> <h3 id="configuration-loader-in-swift">Configuration Loader in Swift</h3> <p>Here is an example implementation of a configuration loader in Swift Programming Language, demonstrating how to load and parse a configuration file compliant with this standard:</p> <pre class="giallo z-code"><code data-lang="swift"><span class="giallo-l"><span class="z-keyword">import</span><span class="z-entity z-name"> Foundation</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"> BlockchainConfig</span><span>:</span><span class="z-entity"> Codable</span><span>, </span><span class="z-entity">LoggerProvider</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> NetworkConfig</span><span>:</span><span class="z-entity"> Codable</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Currency</span><span>:</span><span class="z-entity"> Codable</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> name:</span><span class="z-support"> String</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> symbol:</span><span class="z-support"> String</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> decimals:</span><span class="z-support"> Int</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"> RPC</span><span>:</span><span class="z-entity"> Codable</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> url:</span><span class="z-support"> String</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"> Relations</span><span>:</span><span class="z-entity"> Codable</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> mainnetChainId:</span><span class="z-support"> Int</span><span class="z-keyword">?</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> parentChainId:</span><span class="z-support"> Int</span><span class="z-keyword">?</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"> Explorer</span><span>:</span><span class="z-entity"> Codable</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> root:</span><span class="z-support"> String</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> block:</span><span class="z-support"> String</span><span class="z-keyword">?</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> address:</span><span class="z-support"> String</span><span class="z-keyword">?</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> tx:</span><span class="z-support"> String</span><span class="z-keyword">?</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> nft:</span><span class="z-support"> String</span><span class="z-keyword">?</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"> Contract</span><span>:</span><span class="z-entity"> Codable</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> address:</span><span class="z-support"> String</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> blockCreated:</span><span class="z-support"> Int</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> name:</span><span class="z-support"> String</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> testnet:</span><span class="z-support"> Bool</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> nativeCurrency:</span><span> Currency</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> rpcs:</span><span> [</span><span class="z-support">String</span><span>:</span><span> RPC</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> relations:</span><span> Relations</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> explorers:</span><span> [</span><span class="z-support">String</span><span>:</span><span> Explorer</span><span class="z-keyword">?</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> contracts:</span><span> [</span><span class="z-support">String</span><span>:</span><span> Contract</span><span class="z-keyword">?</span><span>]</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> var</span><span> registryAddress:</span><span class="z-support"> String</span><span> {</span></span> <span class="giallo-l"><span> contracts</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Registry</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">address</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> var</span><span> megascan:</span><span> Explorer </span><span>{</span></span> <span class="giallo-l"><span> explorers</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">megascan</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span class="z-keyword">!</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"> func</span><span class="z-entity z-name"> blockExplorerUrl</span><span>(</span><span class="z-entity z-name">address</span><span>: </span><span class="z-support">String</span><span>)</span><span class="z-keyword"> -&gt;</span><span> URL </span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> fullPath </span><span class="z-keyword">=</span><span> megascan.</span><span class="z-variable z-other">address</span><span class="z-keyword">!</span><span>.</span><span class="z-support">replacingOccurrences</span><span>(</span><span class="z-support">of</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-support">with</span><span>:</span><span> address</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> URL</span><span>(</span><span class="z-support">string</span><span>:</span><span> megascan.</span><span class="z-variable z-other">root</span><span class="z-keyword"> +</span><span> fullPath</span><span>)</span><span class="z-keyword">!</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> func</span><span class="z-entity z-name"> blockExplorerUrl</span><span>(</span><span class="z-entity z-name">tx</span><span>: </span><span class="z-support">String</span><span>)</span><span class="z-keyword"> -&gt;</span><span> URL </span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> fullPath </span><span class="z-keyword">=</span><span> megascan.</span><span class="z-variable z-other">tx</span><span class="z-keyword">!</span><span>.</span><span class="z-support">replacingOccurrences</span><span>(</span><span class="z-support">of</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">:tx</span><span class="z-punctuation z-definition z-string">&quot;</span><span>, </span><span class="z-support">with</span><span>:</span><span> tx</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> URL</span><span>(</span><span class="z-support">string</span><span>:</span><span> megascan.</span><span class="z-variable z-other">root</span><span class="z-keyword"> +</span><span> fullPath</span><span>)</span><span class="z-keyword">!</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> func</span><span class="z-entity z-name"> blockExplorerUrl</span><span>(</span><span class="z-entity z-name">contractAddress</span><span>: </span><span class="z-support">String</span><span>, </span><span class="z-entity z-name">tokenId</span><span>: </span><span>Data</span><span>)</span><span class="z-keyword"> -&gt;</span><span> URL </span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> fullPath </span><span class="z-keyword">=</span><span> explorers</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">nftmarketplace</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">nft</span><span class="z-keyword">!</span></span> <span class="giallo-l"><span> .</span><span class="z-support">replacingOccurrences</span><span>(</span><span class="z-support">of</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-support">with</span><span>:</span><span> contractAddress</span><span>)</span></span> <span class="giallo-l"><span> .</span><span class="z-support">replacingOccurrences</span><span>(</span><span class="z-support">of</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-support">with</span><span>:</span><span> tokenId.</span><span class="z-variable z-other">decString</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> URL</span><span>(</span><span class="z-support">string</span><span>:</span><span> megascan.</span><span class="z-variable z-other">root</span><span class="z-keyword"> +</span><span> fullPath</span><span>)</span><span class="z-keyword">!</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"> let</span><span> version:</span><span class="z-support"> String</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> timestamp:</span><span class="z-support"> String</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> description:</span><span class="z-support"> String</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> networks:</span><span> [</span><span class="z-support">String</span><span>:</span><span> NetworkConfig</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage"> static</span><span class="z-storage z-type"> func</span><span class="z-entity z-name"> load</span><span>(</span><span>)</span><span class="z-keyword"> -&gt;</span><span> BlockchainConfig </span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> guard</span><span class="z-keyword"> let</span><span> url </span><span class="z-keyword">=</span><span> Bundle.main.</span><span class="z-support z-variable">url</span><span>(</span><span class="z-support">forResource</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-support">withExtension</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">json</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> fatalError</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Blockchain config not found.</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-keyword"> do</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> data </span><span class="z-keyword">=</span><span class="z-keyword"> try</span><span class="z-support"> Data</span><span>(</span><span class="z-support">contentsOf</span><span>:</span><span> url</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> let</span><span> decoder </span><span class="z-keyword">=</span><span class="z-support"> JSONDecoder</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> decoder.</span><span class="z-variable z-other">keyDecodingStrategy</span><span class="z-keyword"> =</span><span> .</span><span class="z-variable z-other">convertFromSnakeCase</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-keyword"> try</span><span> decoder.</span><span class="z-support">decode</span><span>(</span><span>BlockchainConfig.</span><span class="z-keyword">self</span><span>, </span><span class="z-support">from</span><span>:</span><span> data</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-support"> fatalError</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">JSON Config parse error: </span><span class="z-string">\(</span><span class="z-string">error</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></code></pre> <p>This Swift code provides a structured way to handle the configuration JSON and includes utility methods for accessing contract-related information.</p> <h3 id="example-extensions">Example Extensions</h3> <h4 id="exposing-api-key">Exposing API key</h4> <p>Example of an extension that <strong>MUST</strong> be supported: adding an API token alongside the RPC URL when it cannot be embedded directly into the URL (e.g., passed via an <code>Authorization: Bearer &lt;token&gt;</code> header).</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"> ExtendedRpcConfig</span><span class="z-keyword"> =</span><span class="z-entity z-name"> RpcConfig</span><span class="z-keyword"> &amp;</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Bearer token for API authentication</span></span> <span class="giallo-l"><span class="z-variable"> apiKey</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Maximum requests allowed per hour</span></span> <span class="giallo-l"><span class="z-variable"> hourlyThroughput</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> API key restricted by contract address</span></span> <span class="giallo-l"><span class="z-variable"> contractRestrictionEnabled</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> <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"> rpcs</span><span class="z-keyword">:</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"> ExtendedRpcConfig</span><span>&gt;</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">restrictedNode</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> url</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://example.com/eth/rpc</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> apiKey</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ecc2fc8b494b60bcc9faa90d750183f2</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> </span></span> <span class="giallo-l"><span> hourlyThroughput</span><span>:</span><span class="z-constant"> 40</span><span>,</span></span> <span class="giallo-l"><span> contractRestrictionEnabled</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p>Ensure <a href="https://wg-eips.ritovision.com/7876/#security-considerations">Security Considerations</a> are followed to protect your API key.</p> <h4 id="extending-contract-properties">Extending contract properties</h4> <p>Example of an extension that <strong>MUST</strong> be supported: incorporating additional attributes to support <a href="https://wg-eips.ritovision.com/1967/">ERC-1967</a> transparent proxies and <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface identification.</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"> ExtendedContractConfig</span><span class="z-keyword"> =</span><span class="z-entity z-name"> ContractConfig</span><span class="z-keyword"> &amp;</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> implementation</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"> proxyAdmin</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"> supportsInterface</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>;</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"> contracts</span><span class="z-keyword">:</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"> ExtendedContractConfig</span><span>&gt;</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span> Registry</span><span>:</span><span> {</span></span> <span class="giallo-l"><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">0x57928ff7b0BBc3Ee4D84481e320DdB8B941f986A</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">blockCreated</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-constant"> 123456</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">implementation</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">0x489B4BC8bCA12cCeafb84aa78918b8E28594C391</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">proxyAdmin</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">0xFd72EeDa802481027e4200E61A5dF052287eec27</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-comment"> //</span><span class="z-comment"> ERC-721 &amp; ERC-165 interfaces</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">supportsInterface</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">0x01ffc9a7</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">0x80ac58cd</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></code></pre><h4 id="incorrect-extension">Incorrect extension</h4> <p>Example of an incorrect extension that <strong>MUST NOT</strong> be supported: representing <code>blockCreated</code> as a hexadecimal string instead of an integer.</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"> contracts</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span> Registry</span><span>:</span><span> {</span></span> <span class="giallo-l"><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">0x57928ff7b0BBc3Ee4D84481e320DdB8B941f986A</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">blockCreated</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">0x2af821</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></code></pre> <p>It causes existing implementation to fail parsing <code>blockCreated</code> property expecting it to be a <code>number</code>, not a <code>string</code>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The network configuration defined by this standard is intended to include only public information that is already accessible through tools like block explorers. By structuring this information in a standardized format, the configuration becomes more convenient and efficient for developers to use while maintaining the integrity of public data.</p> <p>To ensure security and privacy, the following considerations <strong>MUST</strong> be adhered to:</p> <h3 id="1-public-information-only">1. Public Information Only</h3> <ul> <li>The configuration <strong>SHOULD</strong> include only publicly available details.</li> <li>All information included in the configuration should already be discoverable through public tools or services, such as block explorers.</li> <li>Including private or sensitive information <strong>MUST</strong> be protected with an additional layer of protection.</li> </ul> <h3 id="2-exposing-api-keys">2. Exposing API Keys</h3> <p>Exposing API keys must be handled with caution and accompanied by a thorough evaluation of associated risks. When including API keys, the following restrictions and best practices <strong>SHOULD</strong> be implemented:</p> <ul> <li> <p><strong>Scope Restrictions</strong>:</p> <ul> <li>API keys <strong>SHOULD</strong> be limited in scope to specific actions or contract addresses.</li> <li>Consider implementing IP restrictions where possible.</li> </ul> </li> <li> <p><strong>Rate Limits</strong>:</p> <ul> <li>Include throughput limits (e.g., hourly or daily request caps) to mitigate abuse.</li> </ul> </li> <li> <p><strong>Usage</strong>:</p> <ul> <li>Exposing API keys <strong>MUST NOT</strong> be done in publicly distributed configurations.</li> <li>Use environment variables or other secure mechanisms to manage API keys internally within an organization.</li> </ul> </li> </ul> <h3 id="3-exclusion-of-sensitive-information">3. Exclusion of Sensitive Information</h3> <p>The configuration <strong>MUST NOT</strong> include the following sensitive data:</p> <ul> <li>Private keys</li> <li>Wallet recovery phrases or mnemonics</li> <li>Any information that could compromise the security or privacy of users or systems.</li> </ul> <h3 id="4-low-overall-security-risk">4. Low Overall Security Risk</h3> <p>The overall security risks of using this standard are minimal due to its compatibility with established Ethereum ecosystem security practices, including:</p> <ul> <li>Verification of public data through block explorers.</li> <li>Adherence to existing security standards like JSON schema validation and ABI checksum verification.</li> </ul> <p>By aligning with proven methodologies and widely accepted protocols, the standard minimizes potential vulnerabilities while ensuring robust functionality.</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-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ming Wuhttps://github.com/sparkmiw Jason Zenghttps://github.com/zenghbo Wei Wuhttps://github.com/Wilbert957 Michael Heinrichhttps://github.com/michaelomg https://wg-eips.ritovision.com/7857/

AI agent NFTs, enabling secure management of private metadata with verifiable data transfer

<h2 id="abstract">Abstract</h2> <p>A standard interface for NFTs specifically designed for AI agents, where the metadata represents agent capabilities and requires privacy protection. Unlike traditional NFT standards that focus on static metadata, this standard introduces mechanisms for verifiable data ownership and secure transfer. By defining a unified interface for different verification methods (e.g., Trusted Execution Environment (TEE), Zero-Knowledge Proof (ZKP)), it enables secure management of valuable agent metadata such as models, memory, and character definitions, while maintaining confidentiality and verifiability.</p> <h2 id="motivation">Motivation</h2> <p>With the increasing intelligence of AI models, agents have become powerful tools for automating meaningful daily tasks. The integration of agents with blockchain technology has been recognized as a major narrative in the crypto industry, with many projects enabling agent creation for their users. However, a crucial missing piece is the decentralized management of agent ownership.</p> <p>AI agents possess inherent non-fungible properties that make them natural candidates for NFT representation:</p> <ol> <li>Each agent is unique, with its own model, memory, and character</li> <li>Agents embody clear ownership rights, representing significant computational investment and intellectual property</li> <li>Agents have private metadata (e.g., neural network models, memory, character definitions) that defines their capabilities</li> </ol> <p>However, current NFT standards like <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> are insufficient for representing AI agents as digital assets. While NFTs can establish ownership of digital items, using them to represent AI agents introduces unique challenges. The key issue lies in the metadata transfer mechanism. Unlike traditional NFTs where metadata is typically static and publicly accessible, an AI agent's metadata (which constitutes the agent itself):</p> <ol> <li>Has intrinsic value and is often the primary purpose of the transfer</li> <li>Requires encrypted storage to protect intellectual property</li> <li>Needs privacy-preserving and verifiable transfer mechanisms when ownership changes</li> </ol> <p>For example, when transferring an agent NFT, we need to ensure:</p> <ol> <li>The actual transfer of encrypted metadata (the agent's model, memory, character, etc.) is verifiable</li> <li>The new owner can securely access the metadata that constitutes the agent</li> <li>The agent's execution environment can verify ownership and load appropriate metadata</li> </ol> <p>This EIP introduces a standard for NFTs with private metadata that addresses these requirements through privacy-preserving verification mechanisms, enabling secure ownership and transfer of valuable agent data while maintaining confidentiality and verifiability. This standard will serve as a foundation for the emerging agent ecosystem, allowing platforms to provide verifiable agent ownership and secure metadata management in a decentralized manner.</p> <h2 id="specification">Specification</h2> <p>The EIP defines three key interfaces: the main NFT interface, the metadata interface, and the data verification interface.</p> <h3 id="data-verification-system">Data Verification System</h3> <p>The verification system consists of two core components that work together to ensure secure data operations:</p> <ol> <li> <p><strong>On-chain Verifier (data verification interface)</strong></p> <ul> <li>Implemented as a smart contract</li> <li>Verifies proofs submitted through contract calls</li> <li>Returns structured verification results</li> <li>Can be implemented using different verification mechanisms (TEE/ZKP)</li> </ul> </li> <li> <p><strong>Off-chain Prover</strong></p> <ul> <li>Generates proofs for ownership and availability claims</li> <li>Works with encrypted data and keys</li> <li>Implementation varies based on verification mechanism: <ul> <li>TEE-based: Generates proofs within trusted hardware</li> <li>ZKP-based: Creates cryptographic zero-knowledge proofs</li> </ul> </li> </ul> </li> </ol> <p>The system supports two types of proofs:</p> <ol> <li> <p><strong>Ownership Proof</strong></p> <ul> <li>Generated by Prover with access to original data</li> <li>Proves knowledge of pre-images for claimed dataHashes</li> <li>Verified on-chain through <code>verifyOwnership()</code></li> </ul> </li> <li> <p><strong>Transfer Validity Proof</strong></p> <ul> <li>Generated by Prover for data transfers</li> <li>Proves: <ul> <li>Knowledge of original data (pre-images)</li> <li>Correct decryption and re-encryption of data</li> <li>Secure key transmission (using receiver's public key to encrypt the new key)</li> <li>Data availability in storage (using receiver's signature to confirm the data is available in storage)</li> </ul> </li> <li>Verified on-chain through <code>verifyTransferValidity()</code></li> </ul> </li> </ol> <p>The ownership verification is optional because when the minted token is transferred or cloned, the ownership verification is checked again inside the availability verification. It's better to be safe than sorry, so we recommend doing ownership verification for minting and updates.</p> <p>Different verification mechanisms have distinct capabilities:</p> <ul> <li> <p><strong>TEE-based Implementation</strong></p> <ul> <li>Prover runs in trusted hardware</li> <li>Can handle private keys securely</li> <li>Enables direct data re-encryption</li> <li>Verifier checks TEE attestations</li> </ul> </li> <li> <p><strong>ZKP-based Implementation</strong></p> <ul> <li>Prover generates cryptographic proofs</li> <li>Cannot handle multi-party private keys</li> <li>Re-encryption key known to prover</li> <li>Requires additional re-encryption when next update, otherwise the new update is still visible to the prover</li> </ul> </li> </ul> <h3 id="data-verification-interface">Data Verification Interface</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> The type of the oracle</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> There are two types of oracles: TEE and ZKP</span></span> <span class="giallo-l"><span class="z-storage z-type">enum</span><span class="z-entity z-name"> OracleType</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> TEE</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ZKP</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"> @notice</span><span class="z-comment"> The access proof which is a signature signed by the receiver (the receiver may delegate the signing privilege to the access assistant)</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> oldDataHash</span><span class="z-comment"> The hash of the old 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"> newDataHash</span><span class="z-comment"> The hash of the new 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"> nonce</span><span class="z-comment"> The nonce of the access 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"> encryptedPubKey</span><span class="z-comment"> The encrypted public key, the receiver&#39;s public key which used to encrypt the new data key. `encryptedPubKey` can be empty in `accessProof`, and means that use the receiver&#39;s ethereum public key to encrypt the new data key</span></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"> The proof</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> AccessProof</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> oldDataHash</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> newDataHash</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> nonce</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> encryptedPubKey</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-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> The ownership proof which is a signature signed by the receiver (the receiver may delegate the signing privilege to the access assistant)</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> proofType</span><span class="z-comment"> The type of the 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"> oldDataHash</span><span class="z-comment"> The hash of the old 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"> newDataHash</span><span class="z-comment"> The hash of the new 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"> sealedKey</span><span class="z-comment"> The sealed key of the new data key</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> encryptedPubKey</span><span class="z-comment"> The encrypted public key, the receiver&#39;s public key which used to encrypt the new data key</span></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</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> OwnershipProof</span><span> {</span></span> <span class="giallo-l"><span> OracleType oracleType</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> The type of the oracle</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> oldDataHash</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> The hash of the old data</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> newDataHash</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> The hash of the new data</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> sealedKey</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> The sealed key of the new data key</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> encryptedPubKey</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> The encrypted public key, the receiver&#39;s public key which used to encrypt the new data key</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> nonce</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> The nonce</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> proof</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> The proof</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"> TransferValidityProof</span><span> {</span></span> <span class="giallo-l"><span> AccessProof accessProof</span><span>;</span></span> <span class="giallo-l"><span> OwnershipProof ownershipProof</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"> TransferValidityProofOutput</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> oldDataHash</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> newDataHash</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> sealedKey</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> encryptedPubKey</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> wantedKey</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> accessAssistant</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> accessProofNonce</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> ownershipProofNonce</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"> IERC7857DataVerifier</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"> Verify data transfer validity, the _proofs prove:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 1. The pre-image of oldDataHashes</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 2. The oldKey (old data key) can decrypt the pre-image and the new key re-encrypt the plaintexts to new ciphertexts</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 3. The newKey (new data key) is encrypted using the encryptedPubKey</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 4. The hashes of new ciphertexts is newDataHashes</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 5. The newDataHashes identified ciphertexts are available in the storage: need the signature from the receiver or the access assistant signing oldDataHashes, newDataHashes, and encryptedPubKey</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _proofs</span><span class="z-comment"> Proof generated by TEE/ZKP</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyTransferValidity</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> TransferValidityProof</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _proofs</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-storage z-type">TransferValidityProofOutput</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><h3 id="metadata-interface">Metadata Interface</h3> <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"> IntelligentData</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> dataDescription</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> dataHash</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"> IERC7857Metadata</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 name of the NFT collection</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"> @notice</span><span class="z-comment"> Get the symbol of the NFT collection</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"> Get the data hash 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"> The token identifier</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"> current data hash of the token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> intelligentDataOf</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-storage z-type">IntelligentData</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><h3 id="main-nft-interface">Main NFT 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"> IERC7857</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"> The event emitted when an address is approved to transfer 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"> _from</span><span class="z-comment"> The address that is approving</span></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 is being approved</span></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 identifier</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> <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"> The event emitted when an address is approved for all</span></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"> 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"> _operator</span><span class="z-comment"> The 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"> _approved</span><span class="z-comment"> The approval</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> <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"> _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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> The event emitted when an address is authorized to use 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"> _from</span><span class="z-comment"> The address that is authorizing</span></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 is being authorized</span></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 identifier</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Authorization</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"> The event emitted when an address is revoked from using 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"> _from</span><span class="z-comment"> The address that is revoking</span></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 is being 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"> The token identifier</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AuthorizationRevoked</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"> The event emitted when a token is transferred</span></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 identifier</span></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 that is transferring</span></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 is receiving</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Transferred</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"> _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 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"> The event emitted when a token is cloned</span></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 identifier</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _newTokenId</span><span class="z-comment"> The new token identifier</span></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 that is cloning</span></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 is receiving</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Cloned</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-storage z-type"> indexed</span><span class="z-variable"> _newTokenId</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 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"> The event emitted when a sealed key is published</span></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 is receiving</span></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 identifier</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _sealedKeys</span><span class="z-comment"> The sealed keys</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> PublishedSealedKey</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></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-variable"> _sealedKeys</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"> The event emitted when a user is delegated to an assistant</span></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</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _assistant</span><span class="z-comment"> The assistant</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DelegateAccess</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"> _assistant</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 verifier interface that this NFT uses</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 verifier contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifier</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-storage z-type">IERC7857DataVerifier</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"> Transfer data with ownership</span></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 to transfer 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"> _tokenId</span><span class="z-comment"> The token to transfer data 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"> _proofs</span><span class="z-comment"> Proofs of data available for _to</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> iTransfer</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"> _tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> TransferValidityProof</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _proofs</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-storage z-type"> @notice</span><span class="z-comment"> Clone 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"> _to</span><span class="z-comment"> Address to clone 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"> _tokenId</span><span class="z-comment"> The token to clone data 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"> _proofs</span><span class="z-comment"> Proofs of data available for _to</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"> _newTokenId</span><span class="z-comment"> The ID of the newly cloned token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> iClone</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"> _tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> TransferValidityProof</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _proofs</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">uint256</span><span class="z-variable z-parameter z-function"> _newTokenId</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 authorized user to group</span></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 add to group</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> authorizeUsage</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-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"> Revoke authorization from a 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 token to revoke authorization from</span></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 to revoke authorization from</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeAuthorization</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-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"> Approve an address to transfer 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"> _to</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 token identifier</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"> _to</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Set approval for all</span></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 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"> _approved</span><span class="z-comment"> The approval</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 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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Delegate access check to an assistant</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _assistant</span><span class="z-comment"> The assistant</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> delegateAccess</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _assistant</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 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"> The token identifier</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"> current owner of the token</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 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 class="z-storage z-type"> @notice</span><span class="z-comment"> Get the authorized users 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"> The token identifier</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"> current authorized users of the token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> authorizedUsersOf</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">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"> Get the approved address for 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"> The token identifier</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</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 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 class="z-storage z-type"> @notice</span><span class="z-comment"> Check if an address is approved for all</span></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"> 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"> _operator</span><span class="z-comment"> The operator</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"> approval</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> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _owner</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 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 class="z-storage z-type"> @notice</span><span class="z-comment"> Get the delegate access for a 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"> _user</span><span class="z-comment"> The user</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"> delegate access</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getDelegateAccess</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">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The design choices in this standard are motivated by several key requirements:</p> <ol> <li> <p><strong>Verification Abstraction</strong>: The standard separates the verification logic into a dedicated interface (<code>IDataVerifier</code>), allowing different verification mechanisms (TEE, ZKP) to be implemented and used interchangeably. The verifier should support two types of proof:</p> <ul> <li>Ownership Proof Verifies that the prover possesses the original data by demonstrating knowledge of the pre-images that generate the claimed dataHashes</li> <li>Transfer Validity Proof Verifies secure data integrity and availability by proving: knowledge of the original data (pre-images of oldDataHashes); ability to decrypt with oldKey and re-encrypt with newKey; secure transmission of newKey using recipient's public key; integrity of the newly encrypted data matching newDataHashes; and data availability confirmed by recipient's signature on both <code>oldDataHashes</code> and <code>newDataHashes</code></li> </ul> </li> <li> <p><strong>Data Protection</strong>: The standard uses data hashes and encrypted keys to ensure that valuable NFT data remains protected while still being integrity and availability verifiable</p> </li> <li> <p><strong>Flexible Data Management</strong>: Three distinct data operations are supported:</p> <ul> <li>Full transfer, where the data and ownership are transferred to the new owner</li> <li>Data cloning, where the data is cloned to a new token but the ownership is not transferred</li> <li>Data usage authorization, where the data is authorized to be used by a specific user, but the ownership is not transferred, and the user still cannot access the data. This need an environment to authenticate the user and process the request from the authorized user secretly, we call it "Sealed Executor"</li> </ul> </li> <li> <p><strong>Sealed Executor</strong>: Although the Sealed Executor is not defined and out of the scope of this standard, it is a crucial component for the standard to work. The Sealed Executor is an environment that can authenticate the user and process the request from the authorized user secretly. The Sealed Executor should get authorized group by tokenId, and the verify the signature of the user using the public keys in the authorized group. If the verification is successful, the executor will process the request and return the result to the user, and the sealed executor could be implemented by a trusted party (where permitted), TEE or Fully Homomorphic Encryption (FHE)</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP does not inherit from existing NFT standards to maintain its focus on functional data management. However, implementations can choose to additionally implement <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> if traditional NFT compatibility is desired.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="verifier">Verifier</h3> <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"> BaseVerifier</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7857DataVerifier</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> prevent replay attack</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"> bool</span><span>)</span><span class="z-storage z-type"> internal</span><span> usedProofs</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> prevent replay attack</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"> uint256</span><span>)</span><span class="z-storage z-type"> internal</span><span> proofTimestamps</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"> _checkAndMarkProof</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> proofNonce</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-keyword">!</span><span>usedProofs</span><span>[</span><span>proofNonce</span><span>]</span><span>,</span><span class="z-string"> &quot;Proof already used&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> usedProofs</span><span>[</span><span>proofNonce</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> proofTimestamps</span><span>[</span><span>proofNonce</span><span>]</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> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> clean expired proof records (save gas)</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> cleanExpiredProofs</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"> proofNonces</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> proofNonces</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"> bytes32</span><span> nonce </span><span class="z-keyword">=</span><span> proofNonces</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>usedProofs</span><span>[</span><span>nonce</span><span>]</span><span class="z-keyword"> &amp;&amp;</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-language"> block</span><span>.</span><span>timestamp </span><span class="z-keyword">&gt;</span><span> proofTimestamps</span><span>[</span><span>nonce</span><span>]</span><span class="z-keyword"> +</span><span class="z-constant"> 7</span><span class="z-constant"> days</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> usedProofs</span><span>[</span><span>nonce</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> proofTimestamps</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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span class="z-constant">50</span><span>]</span><span class="z-storage z-type"> private</span><span> __gap</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"> AttestationConfig</span><span> {</span></span> <span class="giallo-l"><span> OracleType oracleType</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>}</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"> Verifier</span><span class="z-storage"> is</span></span> <span class="giallo-l"><span class="z-entity z-name"> BaseVerifier</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> Initializable</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> AccessControlUpgradeable</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> PausableUpgradeable</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> ECDSA</span><span class="z-keyword"> for</span><span class="z-entity z-name"> bytes32</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> MessageHashUtils</span><span class="z-keyword"> for</span><span class="z-entity z-name"> bytes32</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"> AttestationContractUpdated</span><span>(</span><span class="z-variable">AttestationConfig</span><span>[</span><span>]</span><span class="z-variable"> attestationConfigs</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"> public</span><span class="z-storage z-type"> constant</span><span> ADMIN_ROLE </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;ADMIN_ROLE&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> PAUSER_ROLE </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;PAUSER_ROLE&quot;</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>OracleType </span><span class="z-keyword">=&gt;</span><span class="z-support"> address</span><span>)</span><span class="z-storage z-type"> public</span><span> attestationContract</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> maxProofAge</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 class="z-storage z-type"> constant</span><span> VERSION </span><span class="z-keyword">=</span><span class="z-string"> &quot;2.0.0&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"> @custom:oz</span><span class="z-comment">-upgrades-unsafe-allow constructor</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _disableInitializers</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"> initialize</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> AttestationConfig</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _attestationConfigs</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _admin</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> initializer</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> __AccessControl_init</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> __Pausable_init</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> _attestationConfigs</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> attestationContract</span><span>[</span></span> <span class="giallo-l"><span> _attestationConfigs</span><span>[</span><span>i</span><span>]</span><span>.</span><span>oracleType</span></span> <span class="giallo-l"><span> ]</span><span class="z-keyword"> =</span><span> _attestationConfigs</span><span>[</span><span>i</span><span>]</span><span>.</span><span>contractAddress</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> maxProofAge </span><span class="z-keyword">=</span><span class="z-constant"> 7</span><span class="z-constant"> days</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> _grantRole</span><span>(</span><span>DEFAULT_ADMIN_ROLE</span><span>,</span><span> _admin</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _grantRole</span><span>(</span><span>ADMIN_ROLE</span><span>,</span><span> _admin</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _grantRole</span><span>(</span><span>PAUSER_ROLE</span><span>,</span><span> _admin</span><span>)</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"> AttestationContractUpdated</span><span>(</span><span>_attestationConfigs</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"> updateAttestationContract</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> AttestationConfig</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _attestationConfigs</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyRole</span><span>(</span><span class="z-entity z-name">ADMIN_ROLE</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> _attestationConfigs</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> attestationContract</span><span>[</span></span> <span class="giallo-l"><span> _attestationConfigs</span><span>[</span><span>i</span><span>]</span><span>.</span><span>oracleType</span></span> <span class="giallo-l"><span> ]</span><span class="z-keyword"> =</span><span> _attestationConfigs</span><span>[</span><span>i</span><span>]</span><span>.</span><span>contractAddress</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> AttestationContractUpdated</span><span>(</span><span>_attestationConfigs</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"> updateMaxProofAge</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _maxProofAge</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyRole</span><span>(</span><span class="z-entity z-name">ADMIN_ROLE</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> maxProofAge </span><span class="z-keyword">=</span><span> _maxProofAge</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"> pause</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyRole</span><span>(</span><span class="z-entity z-name">PAUSER_ROLE</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _pause</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"> unpause</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyRole</span><span>(</span><span class="z-entity z-name">PAUSER_ROLE</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _unpause</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"> hashNonce</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> nonce</span><span>)</span><span class="z-storage z-type"> private</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>nonce</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"> teeOracleVerify</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> messageHash</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"> signature</span></span> <span class="giallo-l"><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-keyword"> return</span></span> <span class="giallo-l"><span class="z-entity z-name"> TEEVerifier</span><span>(</span><span>attestationContract</span><span>[</span><span>OracleType</span><span>.</span><span>TEE</span><span>]</span><span>)</span><span>.</span><span class="z-entity z-name">verifyTEESignature</span><span>(</span></span> <span class="giallo-l"><span> messageHash</span><span>,</span></span> <span class="giallo-l"><span> signature</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Extract and verify signature from the access 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"> accessProof</span><span class="z-comment"> The access proof</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"> recovered access assistant address</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyAccessibility</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> AccessProof</span><span class="z-storage z-type"> memory</span><span class="z-variable"> accessProof</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> private</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 class="z-support"> bytes32</span><span> messageHash </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;\x19Ethereum Signed Message:\n66&quot;</span><span>,</span></span> <span class="giallo-l"><span> Strings</span><span>.</span><span class="z-entity z-name">toHexString</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>(</span></span> <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> accessProof</span><span>.</span><span>oldDataHash</span><span>,</span></span> <span class="giallo-l"><span> accessProof</span><span>.</span><span>newDataHash</span><span>,</span></span> <span class="giallo-l"><span> accessProof</span><span>.</span><span>encryptedPubKey</span><span>,</span></span> <span class="giallo-l"><span> accessProof</span><span>.</span><span>nonce</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-constant"> 32</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"> address</span><span> accessAssistant </span><span class="z-keyword">=</span><span> messageHash</span><span>.</span><span class="z-entity z-name">recover</span><span>(</span><span>accessProof</span><span>.</span><span>proof</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>accessAssistant </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;Invalid access assistant&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> accessAssistant</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"> verfifyOwnershipProof</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> OwnershipProof</span><span class="z-storage z-type"> memory</span><span class="z-variable"> ownershipProof</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> private</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"> if</span><span> (</span><span>ownershipProof</span><span>.</span><span>oracleType </span><span class="z-keyword">==</span><span> OracleType</span><span>.</span><span>TEE</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-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;\x19Ethereum Signed Message:\n66&quot;</span><span>,</span></span> <span class="giallo-l"><span> Strings</span><span>.</span><span class="z-entity z-name">toHexString</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>(</span></span> <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> ownershipProof</span><span>.</span><span>oldDataHash</span><span>,</span></span> <span class="giallo-l"><span> ownershipProof</span><span>.</span><span>newDataHash</span><span>,</span></span> <span class="giallo-l"><span> ownershipProof</span><span>.</span><span>sealedKey</span><span>,</span></span> <span class="giallo-l"><span> ownershipProof</span><span>.</span><span>encryptedPubKey</span><span>,</span></span> <span class="giallo-l"><span> ownershipProof</span><span>.</span><span>nonce</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-constant"> 32</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-keyword"> return</span><span class="z-entity z-name"> teeOracleVerify</span><span>(</span><span>messageHash</span><span>,</span><span> ownershipProof</span><span>.</span><span>proof</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-keyword"> TODO</span><span class="z-comment">: add ZKP verification</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-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 class="z-storage z-type"> @notice</span><span class="z-comment"> Process a single transfer validity 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"> proof</span><span class="z-comment"> The proof data</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"> output</span><span class="z-comment"> The processed proof data as a struct</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> processTransferProof</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> TransferValidityProof</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> proof</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">TransferValidityProofOutput</span><span class="z-storage z-type"> memory</span><span class="z-variable"> output</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> compare the proof data in access proof and ownership proof</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> proof</span><span>.</span><span>accessProof</span><span>.</span><span>oldDataHash </span><span class="z-keyword">==</span><span> proof</span><span>.</span><span>ownershipProof</span><span>.</span><span>oldDataHash</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Invalid oldDataHashes&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> output</span><span>.</span><span>oldDataHash </span><span class="z-keyword">=</span><span> proof</span><span>.</span><span>accessProof</span><span>.</span><span>oldDataHash</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> proof</span><span>.</span><span>accessProof</span><span>.</span><span>newDataHash </span><span class="z-keyword">==</span><span> proof</span><span>.</span><span>ownershipProof</span><span>.</span><span>newDataHash</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Invalid newDataHashes&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> output</span><span>.</span><span>newDataHash </span><span class="z-keyword">=</span><span> proof</span><span>.</span><span>accessProof</span><span>.</span><span>newDataHash</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> output</span><span>.</span><span>wantedKey </span><span class="z-keyword">=</span><span> proof</span><span>.</span><span>accessProof</span><span>.</span><span>encryptedPubKey</span><span>;</span></span> <span class="giallo-l"><span> output</span><span>.</span><span>accessProofNonce </span><span class="z-keyword">=</span><span> proof</span><span>.</span><span>accessProof</span><span>.</span><span>nonce</span><span>;</span></span> <span class="giallo-l"><span> output</span><span>.</span><span>encryptedPubKey </span><span class="z-keyword">=</span><span> proof</span><span>.</span><span>ownershipProof</span><span>.</span><span>encryptedPubKey</span><span>;</span></span> <span class="giallo-l"><span> output</span><span>.</span><span>sealedKey </span><span class="z-keyword">=</span><span> proof</span><span>.</span><span>ownershipProof</span><span>.</span><span>sealedKey</span><span>;</span></span> <span class="giallo-l"><span> output</span><span>.</span><span>ownershipProofNonce </span><span class="z-keyword">=</span><span> proof</span><span>.</span><span>ownershipProof</span><span>.</span><span>nonce</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> verify the access assistant</span></span> <span class="giallo-l"><span> output</span><span>.</span><span>accessAssistant </span><span class="z-keyword">=</span><span class="z-entity z-name"> verifyAccessibility</span><span>(</span><span>proof</span><span>.</span><span>accessProof</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isOwn </span><span class="z-keyword">=</span><span class="z-entity z-name"> verfifyOwnershipProof</span><span>(</span><span>proof</span><span>.</span><span>ownershipProof</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>isOwn</span><span>,</span><span class="z-string"> &quot;Invalid ownership proof&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> output</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"> @notice</span><span class="z-comment"> Verify data transfer validity, the _proof prove:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 1. The pre-image of oldDataHashes</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 2. The oldKey can decrypt the pre-image and the new key re-encrypt the plaintexts to new ciphertexts</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 3. The newKey is encrypted with the receiver&#39;s pubKey to get the sealedKey</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 4. The hashes of new ciphertexts is newDataHashes (key to </span><span class="z-keyword">note</span><span class="z-comment">: TEE could support a private key of the receiver)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 5. The newDataHashes identified ciphertexts are available in the storage: need the signature from the receiver signing oldDataHashes and newDataHashes</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> proofs</span><span class="z-comment"> Proof generated by TEE/ZKP oracle</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyTransferValidity</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> TransferValidityProof</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> proofs</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"> virtual</span></span> <span class="giallo-l"><span class="z-storage z-type"> override</span></span> <span class="giallo-l"><span class="z-entity z-name"> whenNotPaused</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">TransferValidityProofOutput</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> TransferValidityProofOutput</span><span>[</span><span>]</span></span> <span class="giallo-l"><span class="z-storage z-type"> memory</span><span> outputs </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span> TransferValidityProofOutput</span><span>[</span><span>]</span><span>(</span><span>proofs</span><span>.</span><span>length</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> proofs</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> TransferValidityProofOutput </span><span class="z-storage z-type">memory</span><span> output </span><span class="z-keyword">=</span><span class="z-entity z-name"> processTransferProof</span><span>(</span></span> <span class="giallo-l"><span> proofs</span><span>[</span><span>i</span><span>]</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> outputs</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span> output</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> accessProofNonce </span><span class="z-keyword">=</span><span class="z-entity z-name"> hashNonce</span><span>(</span><span>output</span><span>.</span><span>accessProofNonce</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _checkAndMarkProof</span><span>(</span><span>accessProofNonce</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> ownershipProofNonce </span><span class="z-keyword">=</span><span class="z-entity z-name"> hashNonce</span><span>(</span><span>output</span><span>.</span><span>ownershipProofNonce</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _checkAndMarkProof</span><span>(</span><span>ownershipProofNonce</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-keyword"> return</span><span> outputs</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span class="z-constant">50</span><span>]</span><span class="z-storage z-type"> private</span><span> __gap</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="main-nft">Main NFT</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"> AgentNFT</span><span class="z-storage"> is</span></span> <span class="giallo-l"><span class="z-entity z-name"> AccessControlEnumerableUpgradeable</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC7857</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC7857Metadata</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"> Updated</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-variable"> IntelligentData</span><span>[</span><span>]</span><span class="z-variable"> _oldDatas</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> IntelligentData</span><span>[</span><span>]</span><span class="z-variable"> _newDatas</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"> Minted</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"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _creator</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 class="giallo-l"><span> )</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"> TokenData</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> owner</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span> authorizedUsers</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> approvedUser</span><span>;</span></span> <span class="giallo-l"><span> IntelligentData</span><span>[</span><span>]</span><span> iDatas</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"> @custom:storage</span><span class="z-comment">-location erc7201:agent.storage.AgentNFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> AgentNFTStorage</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Token data</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> TokenData</span><span>)</span><span> tokens</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> owner </span><span class="z-keyword">=&gt;</span><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span> operator </span><span class="z-keyword">=&gt;</span><span class="z-support"> bool</span><span>)</span><span>)</span><span> operatorApprovals</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> user </span><span class="z-keyword">=&gt;</span><span class="z-support"> address</span><span> accessAssistant</span><span>)</span><span> accessAssistants</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> nextTokenId</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Contract metadata</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> symbol</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> storageInfo</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Core components</span></span> <span class="giallo-l"><span> IERC7857DataVerifier verifier</span><span>;</span></span> <span class="giallo-l"><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 class="z-storage z-type"> constant</span><span> ADMIN_ROLE </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;ADMIN_ROLE&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> PAUSER_ROLE </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;PAUSER_ROLE&quot;</span><span>)</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 class="z-storage z-type"> constant</span><span> VERSION </span><span class="z-keyword">=</span><span class="z-string"> &quot;2.0.0&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> keccak256(abi.encode(uint(keccak256(&quot;agent.storage.AgentNFT&quot;)) - 1)) &amp; ~bytes32(uint(0xff))</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> AGENT_NFT_STORAGE_LOCATION </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-constant"> 0x4aa80aaafbe0e5fe3fe1aa97f3c1f8c65d61f96ef1aab2b448154f4e07594600</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"> _getAgentStorage</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> private</span></span> <span class="giallo-l"><span class="z-storage z-type"> pure</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">AgentNFTStorage</span><span class="z-storage z-type"> storage</span><span> $</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> $</span><span>.</span><span>slot </span><span class="z-keyword">:=</span><span> AGENT_NFT_STORAGE_LOCATION</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-storage z-type"> @custom:oz</span><span class="z-comment">-upgrades-unsafe-allow constructor</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _disableInitializers</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"> initialize</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"> name_</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"> symbol_</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"> storageInfo_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> verifierAddr</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> admin_</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> virtual</span><span class="z-entity z-name"> initializer</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>verifierAddr </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;Zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> __AccessControlEnumerable_init</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> _grantRole</span><span>(</span><span>DEFAULT_ADMIN_ROLE</span><span>,</span><span> admin_</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _grantRole</span><span>(</span><span>ADMIN_ROLE</span><span>,</span><span> admin_</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _grantRole</span><span>(</span><span>PAUSER_ROLE</span><span>,</span><span> admin_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> AgentNFTStorage </span><span class="z-storage z-type">storage</span><span> $ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> $</span><span>.</span><span>name </span><span class="z-keyword">=</span><span> name_</span><span>;</span></span> <span class="giallo-l"><span> $</span><span>.</span><span>symbol </span><span class="z-keyword">=</span><span> symbol_</span><span>;</span></span> <span class="giallo-l"><span> $</span><span>.</span><span>storageInfo </span><span class="z-keyword">=</span><span> storageInfo_</span><span>;</span></span> <span class="giallo-l"><span> $</span><span>.</span><span>verifier </span><span class="z-keyword">=</span><span class="z-entity z-name"> IERC7857DataVerifier</span><span>(</span><span>verifierAddr</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"> Basic getters</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"> 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">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-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>.</span><span>name</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"> symbol</span><span>(</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">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-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>.</span><span>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"> verifier</span><span>(</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-storage z-type">IERC7857DataVerifier</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>.</span><span>verifier</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"> Admin functions</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateVerifier</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> newVerifier</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> virtual</span><span class="z-entity z-name"> onlyRole</span><span>(</span><span class="z-entity z-name">ADMIN_ROLE</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>newVerifier </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;Zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>.</span><span>verifier </span><span class="z-keyword">=</span><span class="z-entity z-name"> IERC7857DataVerifier</span><span>(</span><span>newVerifier</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"> update</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-storage z-type"> IntelligentData</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> newDatas</span></span> <span class="giallo-l"><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> AgentNFTStorage </span><span class="z-storage z-type">storage</span><span> $ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> TokenData </span><span class="z-storage z-type">storage</span><span> token </span><span class="z-keyword">=</span><span> $</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>token</span><span>.</span><span>owner </span><span class="z-keyword">==</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span class="z-string"> &quot;Not owner&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>newDatas</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Empty data array&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> IntelligentData</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> oldDatas </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span> IntelligentData</span><span>[</span><span>]</span><span>(</span></span> <span class="giallo-l"><span> token</span><span>.</span><span>iDatas</span><span>.</span><span>length</span></span> <span class="giallo-l"><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> token</span><span>.</span><span>iDatas</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> oldDatas</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span> token</span><span>.</span><span>iDatas</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-keyword"> delete</span><span> token</span><span>.</span><span>iDatas</span><span>;</span></span> <span class="giallo-l"></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> newDatas</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> token</span><span>.</span><span>iDatas</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>newDatas</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> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Updated</span><span>(</span><span>tokenId</span><span>,</span><span> oldDatas</span><span>,</span><span> newDatas</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"> mint</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> IntelligentData</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> iDatas</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> to</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> payable</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</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 class="z-keyword"> require</span><span>(</span><span>to </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;Zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>iDatas</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Empty data array&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> AgentNFTStorage </span><span class="z-storage z-type">storage</span><span> $ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> tokenId </span><span class="z-keyword">=</span><span> $</span><span>.</span><span>nextTokenId</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>;</span></span> <span class="giallo-l"><span> TokenData </span><span class="z-storage z-type">storage</span><span> newToken </span><span class="z-keyword">=</span><span> $</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> newToken</span><span>.</span><span>owner </span><span class="z-keyword">=</span><span> to</span><span>;</span></span> <span class="giallo-l"><span> newToken</span><span>.</span><span>approvedUser </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 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> iDatas</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> newToken</span><span>.</span><span>iDatas</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>iDatas</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> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Minted</span><span>(</span><span>tokenId</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span> to</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"> _proofCheck</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></span> <span class="giallo-l"><span class="z-storage z-type"> TransferValidityProof</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> proofs</span></span> <span class="giallo-l"><span> )</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-support">bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> sealedKeys</span><span>,</span><span class="z-storage z-type"> IntelligentData</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> newDatas</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> AgentNFTStorage </span><span class="z-storage z-type">storage</span><span> $ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>to </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;Zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>$</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>owner </span><span class="z-keyword">==</span><span> from</span><span>,</span><span class="z-string"> &quot;Not owner&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>proofs</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Empty proofs array&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> TransferValidityProofOutput</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> proofOutput </span><span class="z-keyword">=</span><span> $</span></span> <span class="giallo-l"><span> .</span><span>verifier</span></span> <span class="giallo-l"><span> .</span><span class="z-entity z-name">verifyTransferValidity</span><span>(</span><span>proofs</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> proofOutput</span><span>.</span><span>length </span><span class="z-keyword">==</span><span> $</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>iDatas</span><span>.</span><span>length</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Proof count mismatch&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> sealedKeys </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> bytes</span><span>[](</span><span class="z-variable">proofOutput</span><span>.</span><span class="z-variable">length</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> newDatas </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span> IntelligentData</span><span>[</span><span>]</span><span>(</span><span>proofOutput</span><span>.</span><span>length</span><span>)</span><span>;</span></span> <span class="giallo-l"></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> proofOutput</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"> require the initial data hash is the same as the old data hash</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> proofOutput</span><span>[</span><span>i</span><span>]</span><span>.</span><span>oldDataHash </span><span class="z-keyword">==</span></span> <span class="giallo-l"><span> $</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>iDatas</span><span>[</span><span>i</span><span>]</span><span>.</span><span>dataHash</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Old data hash mismatch&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"> only the receiver itself or the access assistant can sign the access proof</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> proofOutput</span><span>[</span><span>i</span><span>]</span><span>.</span><span>accessAssistant </span><span class="z-keyword">==</span><span> $</span><span>.</span><span>accessAssistants</span><span>[</span><span>to</span><span>]</span><span class="z-keyword"> ||</span></span> <span class="giallo-l"><span> proofOutput</span><span>[</span><span>i</span><span>]</span><span>.</span><span>accessAssistant </span><span class="z-keyword">==</span><span> to</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Access assistant mismatch&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"> bytes</span><span class="z-storage z-type"> memory</span><span> wantedKey </span><span class="z-keyword">=</span><span> proofOutput</span><span>[</span><span>i</span><span>]</span><span>.</span><span>wantedKey</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> encryptedPubKey </span><span class="z-keyword">=</span><span> proofOutput</span><span>[</span><span>i</span><span>]</span><span>.</span><span>encryptedPubKey</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>wantedKey</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-comment"> //</span><span class="z-comment"> if the wanted key is empty, the default wanted receiver is receiver itself</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> defaultWantedReceiver </span><span class="z-keyword">=</span><span> Utils</span><span>.</span><span class="z-entity z-name">pubKeyToAddress</span><span>(</span></span> <span class="giallo-l"><span> encryptedPubKey</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> defaultWantedReceiver </span><span class="z-keyword">==</span><span> to</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Default wanted receiver mismatch&quot;</span></span> <span class="giallo-l"><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-comment"> //</span><span class="z-comment"> if the wanted key is not empty, the data is private</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> Utils</span><span>.</span><span class="z-entity z-name">bytesEqual</span><span>(</span><span>encryptedPubKey</span><span>,</span><span> wantedKey</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;encryptedPubKey mismatch&quot;</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> sealedKeys</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span> proofOutput</span><span>[</span><span>i</span><span>]</span><span>.</span><span>sealedKey</span><span>;</span></span> <span class="giallo-l"><span> newDatas</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> IntelligentData</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> dataDescription</span><span class="z-keyword">:</span><span> $</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>iDatas</span><span>[</span><span>i</span><span>]</span><span>.</span><span>dataDescription</span><span>,</span></span> <span class="giallo-l"><span> dataHash</span><span class="z-keyword">:</span><span> proofOutput</span><span>[</span><span>i</span><span>]</span><span>.</span><span>newDataHash</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 class="z-keyword"> return</span><span> (</span><span>sealedKeys</span><span>,</span><span> newDatas</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> <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></span> <span class="giallo-l"><span class="z-storage z-type"> TransferValidityProof</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> proofs</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span> AgentNFTStorage </span><span class="z-storage z-type">storage</span><span> $ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> (</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> sealedKeys</span><span>,</span></span> <span class="giallo-l"><span> IntelligentData</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> newDatas</span></span> <span class="giallo-l"><span> )</span><span class="z-keyword"> =</span><span class="z-entity z-name"> _proofCheck</span><span>(</span><span>from</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>,</span><span> proofs</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> TokenData </span><span class="z-storage z-type">storage</span><span> token </span><span class="z-keyword">=</span><span> $</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> token</span><span>.</span><span>owner </span><span class="z-keyword">=</span><span> to</span><span>;</span></span> <span class="giallo-l"><span> token</span><span>.</span><span>approvedUser </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 class="giallo-l"><span class="z-keyword"> delete</span><span> token</span><span>.</span><span>iDatas</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> newDatas</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> token</span><span>.</span><span>iDatas</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>newDatas</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> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Transferred</span><span>(</span><span>tokenId</span><span>,</span><span> from</span><span>,</span><span> to</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> PublishedSealedKey</span><span>(</span><span>to</span><span>,</span><span> tokenId</span><span>,</span><span> sealedKeys</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"> iTransfer</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></span> <span class="giallo-l"><span class="z-storage z-type"> TransferValidityProof</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> proofs</span></span> <span class="giallo-l"><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-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;Not authorized&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _transfer</span><span>(</span><span class="z-entity z-name">ownerOf</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>,</span><span> proofs</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"> 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"> tokenId</span></span> <span class="giallo-l"><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> TokenData </span><span class="z-storage z-type">storage</span><span> token </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</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;Not authorized&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>to </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;Zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>token</span><span>.</span><span>owner </span><span class="z-keyword">==</span><span> from</span><span>,</span><span class="z-string"> &quot;Not owner&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> token</span><span>.</span><span>owner </span><span class="z-keyword">=</span><span> to</span><span>;</span></span> <span class="giallo-l"><span> token</span><span>.</span><span>approvedUser </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 class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Transferred</span><span>(</span><span>tokenId</span><span>,</span><span> from</span><span>,</span><span> to</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"> iTransferFrom</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></span> <span class="giallo-l"><span class="z-storage z-type"> TransferValidityProof</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> proofs</span></span> <span class="giallo-l"><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-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;Not authorized&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _transfer</span><span>(</span><span>from</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>,</span><span> proofs</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"> _clone</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></span> <span class="giallo-l"><span class="z-storage z-type"> TransferValidityProof</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> proofs</span></span> <span class="giallo-l"><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 class="giallo-l"><span> AgentNFTStorage </span><span class="z-storage z-type">storage</span><span> $ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAgentStorage</span><span>(</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-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> sealedKeys</span><span>,</span></span> <span class="giallo-l"><span> IntelligentData</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> newDatas</span></span> <span class="giallo-l"><span> )</span><span class="z-keyword"> =</span><span class="z-entity z-name"> _proofCheck</span><span>(</span><span>from</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>,</span><span> proofs</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> newTokenId </span><span class="z-keyword">=</span><span> $</span><span>.</span><span>nextTokenId</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>;</span></span> <span class="giallo-l"><span> TokenData </span><span class="z-storage z-type">storage</span><span> newToken </span><span class="z-keyword">=</span><span> $</span><span>.</span><span>tokens</span><span>[</span><span>newTokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> newToken</span><span>.</span><span>owner </span><span class="z-keyword">=</span><span> to</span><span>;</span></span> <span class="giallo-l"><span> newToken</span><span>.</span><span>approvedUser </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 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> newDatas</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> newToken</span><span>.</span><span>iDatas</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>newDatas</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> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Cloned</span><span>(</span><span>tokenId</span><span>,</span><span> newTokenId</span><span>,</span><span> from</span><span>,</span><span> to</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> PublishedSealedKey</span><span>(</span><span>to</span><span>,</span><span> newTokenId</span><span>,</span><span> sealedKeys</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> newTokenId</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"> iClone</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></span> <span class="giallo-l"><span class="z-storage z-type"> TransferValidityProof</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> proofs</span></span> <span class="giallo-l"><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-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;Not authorized&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> _clone</span><span>(</span><span class="z-entity z-name">ownerOf</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>,</span><span> proofs</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"> iCloneFrom</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></span> <span class="giallo-l"><span class="z-storage z-type"> TransferValidityProof</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> proofs</span></span> <span class="giallo-l"><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-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;Not authorized&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> _clone</span><span>(</span><span>from</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>,</span><span> proofs</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"> authorizeUsage</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"> to</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>to </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;Zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> AgentNFTStorage </span><span class="z-storage z-type">storage</span><span> $ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>$</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>owner </span><span class="z-keyword">==</span><span class="z-variable z-language"> msg.sender</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-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> storage</span><span> authorizedUsers </span><span class="z-keyword">=</span><span> $</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>authorizedUsers</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> authorizedUsers</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-keyword"> require</span><span>(</span><span>authorizedUsers</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> !=</span><span> to</span><span>,</span><span class="z-string"> &quot;Already authorized&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> authorizedUsers</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>to</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Authorization</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 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"> ownerOf</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-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> AgentNFTStorage </span><span class="z-storage z-type">storage</span><span> $ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> owner </span><span class="z-keyword">=</span><span> $</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>owner</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>owner </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;Token does not exist&quot;</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-storage z-type"> function</span><span class="z-entity z-name"> authorizedUsersOf</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"> 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">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> AgentNFTStorage </span><span class="z-storage z-type">storage</span><span> $ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAgentStorage</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">_exists</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;Token does not exist&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> $</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>authorizedUsers</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"> storageInfo</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"> 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">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;Token does not exist&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>.</span><span>storageInfo</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"> _exists</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"> 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 class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>owner </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-storage z-type"> function</span><span class="z-entity z-name"> intelligentDataOf</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"> 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-storage z-type">IntelligentData</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> AgentNFTStorage </span><span class="z-storage z-type">storage</span><span> $ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAgentStorage</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">_exists</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;Token does not exist&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> $</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>iDatas</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-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> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> owner </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 class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>to </span><span class="z-keyword">!=</span><span> owner</span><span>,</span><span class="z-string"> &quot;Approval to current owner&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-language"> msg.sender</span><span class="z-keyword"> ==</span><span> owner </span><span class="z-keyword">||</span><span class="z-entity z-name"> isApprovedForAll</span><span>(</span><span>owner</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Not authorized&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>approvedUser </span><span class="z-keyword">=</span><span> to</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Approval</span><span>(</span><span>owner</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"> 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 class="z-storage z-type"> virtual</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>operator </span><span class="z-keyword">!=</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span class="z-string"> &quot;Approve to caller&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>.</span><span>operatorApprovals</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>operator</span><span>]</span><span class="z-keyword"> =</span><span> approved</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ApprovalForAll</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> operator</span><span>,</span><span> approved</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"> getApproved</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"> 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">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;Token does not exist&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>approvedUser</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"> isApprovedForAll</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"> address</span><span class="z-variable"> operator</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-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-keyword"> return</span><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>.</span><span>operatorApprovals</span><span>[</span><span>owner</span><span>]</span><span>[</span><span>operator</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"> delegateAccess</span><span>(</span><span class="z-support">address</span><span class="z-variable"> assistant</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>assistant </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;Zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>.</span><span>accessAssistants</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> =</span><span> assistant</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> DelegateAccess</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> assistant</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"> getDelegateAccess</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> user</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-storage z-type"> virtual</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-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>.</span><span>accessAssistants</span><span>[</span><span>user</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"> _isApprovedOrOwner</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> spender</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"> 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"> 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;Token does not exist&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> owner </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 class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>spender </span><span class="z-keyword">==</span><span> owner </span><span class="z-keyword">||</span></span> <span class="giallo-l"><span class="z-entity z-name"> getApproved</span><span>(</span><span>tokenId</span><span>)</span><span class="z-keyword"> ==</span><span> spender </span><span class="z-keyword">||</span></span> <span class="giallo-l"><span class="z-entity z-name"> isApprovedForAll</span><span>(</span><span>owner</span><span>,</span><span> spender</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"> batchAuthorizeUsage</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>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> users</span></span> <span class="giallo-l"><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>users</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Empty users array&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> AgentNFTStorage </span><span class="z-storage z-type">storage</span><span> $ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>$</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>owner </span><span class="z-keyword">==</span><span class="z-variable z-language"> msg.sender</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"> 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> users</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-keyword"> require</span><span>(</span><span>users</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 class="z-string"> &quot;Zero address in users&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> $</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>authorizedUsers</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>users</span><span>[</span><span>i</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Authorization</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> users</span><span>[</span><span>i</span><span>]</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"> function</span><span class="z-entity z-name"> revokeAuthorization</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-storage z-type"> public</span><span class="z-storage z-type"> virtual</span><span> {</span></span> <span class="giallo-l"><span> AgentNFTStorage </span><span class="z-storage z-type">storage</span><span> $ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAgentStorage</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>$</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>owner </span><span class="z-keyword">==</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span class="z-string"> &quot;Not owner&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</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-string"> &quot;Zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> storage</span><span> authorizedUsers </span><span class="z-keyword">=</span><span> $</span><span>.</span><span>tokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>authorizedUsers</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> found </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-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> authorizedUsers</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-keyword"> if</span><span> (</span><span>authorizedUsers</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> ==</span><span> user</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> authorizedUsers</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span> authorizedUsers</span><span>[</span></span> <span class="giallo-l"><span> authorizedUsers</span><span>.</span><span>length </span><span class="z-keyword">-</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> ]</span><span>;</span></span> <span class="giallo-l"><span> authorizedUsers</span><span>.</span><span class="z-entity z-name">pop</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> found </span><span class="z-keyword">=</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><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"> require</span><span>(</span><span>found</span><span>,</span><span class="z-string"> &quot;User not authorized&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> AuthorizationRevoked</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> user</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> <ol> <li><strong>Proof Verification</strong> <ul> <li>Implementations must carefully verify all assertions in the proof</li> <li>Replay attacks must be prevented</li> <li>Different verification systems have their own security considerations, and distinct capabilities regarding key management: TEE can securely handle private keys from multi-parties, enabling direct data re-encryption. However, ZKP, due to its cryptographic nature, cannot process private keys from multi-parties. As a result, the re-encryption key is also from the prover (i.e., the sender), so tokens acquired through transfer or cloning must undergo re-encryption during their next update, otherwise the new update is still visible to the previous owner. This distinction in key handling capabilities affects how data transformations are managed during later usage</li> </ul> </li> <li><strong>Data Privacy</strong> <ul> <li>Only hashes and sealed keys are stored on-chain, actual functional data must be stored and transmitted securely off-chain</li> <li>Key management is crucial for secure data access</li> <li>TEE verification system could support private key of the receiver, but ZKP verification system could not. So when using ZKP, the token transferred or cloned from other should be re-encrypted when next update, otherwise the new update is still visible to the previous owner</li> </ul> </li> <li><strong>Access Control and State Management</strong> <ul> <li>Operations restricted to token owners only</li> <li>All data operations must maintain integrity and availability</li> <li>Critical state changes (sealed keys, ownership, permissions) must be atomic and verifiable</li> </ul> </li> <li><strong>Sealed Executor</strong> <ul> <li>Although out of scope for this standard, the Sealed Executor is crucial for secure operation</li> <li>The Sealed Executor authenticates users and processes requests in a secure environment by verifying user signatures against authorized public keys for each tokenId</li> <li>The Sealed Executor can be implemented through a trusted party (where permitted), TEE or FHE</li> <li>Ensuring secure request processing and result delivery</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> 2025-01-01T00:00:00+00:00 2026-02-11T14:48:26+00:00 Jack Chumahttps://github.com/jackchuma https://wg-eips.ritovision.com/7856/

A URI scheme for chain-specific payment requests.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a standardized URI scheme for chain-specific payment requests, enabling users to specify transactions in the form "send me X tokens of type Y on chain Z". The URI format includes essential components such as the recipient's blockchain account, the amount of tokens, the token contract address, and optional success and error callback URLs. This standard aims to eliminate ambiguity in multi-chain payment requests, ensuring clarity and accuracy in peer-to-peer transactions and vendor or dApp requests across different blockchain networks.</p> <h2 id="motivation">Motivation</h2> <p>The ongoing expansion of the Ethereum network into a multi-chain ecosystem has introduced complexities regarding the execution of payment requests. Users and developers currently face a lack of clarity on which chain a payment request should be fulfilled, particularly when similar assets exist across multiple chains. This ambiguity complicates peer-to-peer transactions and vendor or dApp requests, leading to inefficiencies and a higher potential for errors. This standard will ensure that payment requests are clearly understood and correctly executed, regardless of the chain, thus significantly enhancing the user experience in a multi-chain environment.</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 format of the payment request URI is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cspr://&lt;recipient&gt;/&lt;amount&gt;/&lt;token-address&gt;?on-success=&lt;success-callback-url&gt;&amp;on-error=&lt;error-callback-url&gt;</span></span></code></pre> <ul> <li><code>cspr://</code> - [REQUIRED] Short for "Chain-Specific Payment Request". Indicates a blockchain-based payment request.</li> <li><code>&lt;recipient&gt;</code> - [REQUIRED] The blockchain account requesting the payment (represented as a CAIP-10 account identifier).</li> <li><code>&lt;amount&gt;</code> - [REQUIRED] The amount of tokens to be sent, specified as an integer or decimal number.</li> <li><code>&lt;token-address&gt;</code> - [REQUIRED] The contract address of the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token to send (represented as a base64 encoded string). The special value <code>native</code> can be used to request the native currency of the specified chain (if the chain supports a native currency).</li> <li><code>&lt;success-callback-url&gt;</code> - [OPTIONAL] The URL to redirect the user to after the transaction is confirmed.</li> <li><code>&lt;error-callback-url&gt;</code> - [OPTIONAL] The URL to redirect the user to after the transaction fails.</li> </ul> <h3 id="examples">Examples</h3> <h4 id="requesting-1-eth-on-base-mainnet-to-address-0x1111111111111111111111111111111111111111-with-a-specified-success-callback-url">Requesting 1 eth on Base Mainnet to address <code>0x1111111111111111111111111111111111111111</code> with a specified success callback URL:</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cspr://eip155:8453:0x1111111111111111111111111111111111111111/1/native?on-success=https://example.com</span></span></code></pre><h4 id="requesting-0-5-btc-on-bitcoin-mainnet">Requesting 0.5 BTC on Bitcoin mainnet:</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cspr://bip122:000000000019d6689c085ae165831e93:128Lkh3S7CkDTBZ8W7BbpsN3YYizJMp8p6/0.5/native</span></span></code></pre><h4 id="requesting-100-usdc-on-ethereum-mainnet">Requesting 100 USDC on Ethereum Mainnet:</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cspr://eip155:1:0xab16a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb/100/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48</span></span></code></pre><h3 id="error-handling">Error Handling</h3> <p>Wallets or applications parsing these URIs MUST validate the format of the recipient account. If any component of the URI does not meet the specified requirements or format, an error should be displayed to the user.</p> <h2 id="rationale">Rationale</h2> <p>The design of this URI standard for blockchain-based payment requests addresses the need for a clear and unambiguous method to initiate transactions across multiple Ethereum chains, including mainnet and various Layer 2 networks. The rationale for each component of the URI structure is as follows:</p> <ul> <li><strong><code>cspr://</code> Prefix:</strong> This prefix explicitly identifies the URI as a blockchain-based payment request, ensuring systems recognize and correctly handle these URIs. It follows the precedent of other protocol-specific URI schemes like <code>mailto://</code> for email and <code>http://</code> for web links.</li> <li><strong>Recipient:</strong> The recipient is specified using a CAIP-10 account identifier, a standardized format for representing blockchain addresses. With CAIP-10, you can easily identify the recipient’s blockchain network and corresponding address, regardless of the underlying address conventions.</li> <li><strong>Amount Specification:</strong> Specifying the amount in the URI clarifies the transaction's intent, allowing users to verify the amount before sending. This helps prevent mistakes and fraud. The amount is specified as an integer or decimal number for clarity, precision, and ease of verification.</li> <li><strong>Token Address:</strong> Requiring the token address ensures the URI specifies the exact token to be sent, eliminating ambiguity. It supports both ERC-20 tokens and the native currency of a chain (if supported).</li> <li><strong>Callback URLs:</strong> Including callback URLs allows redirection to a specified URL after the transaction is confirmed or fails, enhancing the user experience by providing a seamless return to the application or website.</li> </ul> <p>The token address in this URI standard is represented as a base64 encoded string to support both EVM and non-EVM chains, as all current address schemes are a subset of base64.</p> <h3 id="alternative-designs-considered">Alternative Designs Considered:</h3> <ul> <li>Including Transaction Parameters: Additional transaction parameters (e.g., gas limit, gas price) were considered but are recommended to be handled by the user's wallet application to keep the URI scheme focused on payment requests and avoid overloading the user with technical details.</li> <li>Token Parameter Optionality: Initially, the token parameter was considered optional, with its omission implying the native currency of the specified chain. However, not all chains support a native currency, so requiring explicit token specification increases clarity and reduces potential errors.</li> <li>An <code>ethereum://</code> prefix: Initially proposed as a standardized URI scheme for the Ethereum ecosystem, the <code>ethereum://</code> prefix aimed to provide a consistent identifier. However, to accommodate non-EVM chains, it is more practical to use a more generic identifier that is not limited to Ethereum.</li> <li>ENS Support: We initially considered adding optional ENS support, but determined it was unnecessary. Because the URI scheme isn’t user-facing, including ENS would add unneeded complexity without providing tangible benefits. Additionally, ENS names that resemble addresses introduce potential security risks. Instead, adhering to the CAIP-10 standard for chain-specific account identifiers is a more practical choice.</li> </ul> <h3 id="related-work">Related Work</h3> <p><a href="https://wg-eips.ritovision.com/681/">ERC-681</a> is a related standard that defines a similar URI scheme for specifying token transfers in Ethereum. However, ERC-681 includes additional parameters for specifying transaction details, which were deemed unnecessary for the scope of this standard. The focus of this EIP is on simplicity and clarity in payment request specifications, with the expectation that transaction details will be handled by the user's wallet application.</p> <p><a href="https://wg-eips.ritovision.com/831/">ERC-831</a> is another related standard that specifies a URI format for Ethereum. Instead of focusing exclusively on Ethereum and its rollups, this EIP is designed to be compatible with all blockchains. The primary distinction lies in the selection of the URI identifier.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Due to the unique choice in URI prefix, this EIP is not backwards compatible with ERC-681 or ERC-831.</p> <h2 id="security-considerations">Security Considerations</h2> <p>As there are many similarities to ERC-681, all the same security considerations apply and have been summarized below.</p> <p>The security and trustworthiness of URLs are crucial, especially since they can trigger irreversible transactions. Altering the recipient's address or the transaction amount can lead to significant financial gain for attackers. Therefore, users should only trust URLs from verified and secure sources.</p> <p>To ensure the transaction amount matches the user's intention, it should be clearly and easily verifiable by the user, including its magnitude. For ERC-20 token transactions, if the payer's client can access the blockchain or another reliable source for token contract details, the interface should present the amount in the token's specified units. If not, it should show the amount as stated in the URL, potentially warning the user about the uncertainty of the unit. Using scientific notation with an exponent that matches the token's nominal unit (e.g., 18 for ether) is recommended to aid user verification.</p> <p>Validate callback URLs rigorously to prevent redirection to phishing sites. Wallet developers should follow browser security best practices for URL validation.</p> <p>Wallet applications must recognize chains that lack native currency support and should block native currency payment requests on these 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-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-27T00:00:00+00:00 2026-02-11T14:49:27+00:00 Toni Wahrstätterhttps://github.com/nerolation https://wg-eips.ritovision.com/7981/

Price access lists for data to reduce maximum block size

<h2 id="abstract">Abstract</h2> <p>This EIP charges access lists for their data footprint, preventing the circumvention of the <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> floor pricing. This effectively reduces the worst-case block size by ~21% with minimal impact on users.</p> <h2 id="motivation">Motivation</h2> <p>Access lists are only priced for storage but not for their data.</p> <p>Furthermore, access lists can circumvent the <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> floor pricing by contributing to EVM gas while still leaving a non-negligible data footprint. This enables achieving the maximal possible block size by combining access lists with calldata at a certain ratio.</p> <h2 id="specification">Specification</h2> <table><thead><tr><th>Parameter</th><th>Value</th><th>Source</th></tr></thead><tbody> <tr><td><code>ACCESS_LIST_ADDRESS_COST</code></td><td><code>2400</code></td><td><a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a></td></tr> <tr><td><code>ACCESS_LIST_STORAGE_KEY_COST</code></td><td><code>1900</code></td><td><a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a></td></tr> <tr><td><code>TOTAL_COST_FLOOR_PER_TOKEN</code></td><td><code>10</code></td><td><a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a></td></tr> </tbody></table> <p>Let <code>access_list_nonzero_bytes</code> and <code>access_list_zero_bytes</code> be the count of non-zero and zero bytes respectively in the addresses (20 bytes each) and storage keys (32 bytes each) contained within the access list.</p> <p>Let <code>tokens_in_access_list = access_list_zero_bytes + access_list_nonzero_bytes * 4</code>.</p> <p>The access list cost formula changes from <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> to include data cost:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>access_list_cost</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span class="z-constant"> ACCESS_LIST_ADDRESS_COST</span><span class="z-keyword"> *</span><span> access_list_addresses</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span class="z-constant"> ACCESS_LIST_STORAGE_KEY_COST</span><span class="z-keyword"> *</span><span> access_list_storage_keys</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span class="z-constant"> TOTAL_COST_FLOOR_PER_TOKEN</span><span class="z-keyword"> *</span><span> tokens_in_access_list</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>The <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> floor calculation is modified to include access list tokens:</p> <pre class="giallo z-code"><code data-lang="python"><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>total_data_tokens</span><span class="z-keyword"> =</span><span> tokens_in_calldata</span><span class="z-keyword"> +</span><span> tokens_in_access_list</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>data_floor_gas_cost</span><span class="z-keyword"> =</span><span class="z-constant"> TX_BASE_COST</span><span class="z-keyword"> +</span><span class="z-constant"> TOTAL_COST_FLOOR_PER_TOKEN</span><span class="z-keyword"> *</span><span> total_data_tokens</span></span></code></pre> <p>The gas used calculation becomes:</p> <pre class="giallo z-code"><code data-lang="python"><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> tokens_in_calldata</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> execution_gas_used</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> isContractCreation</span><span class="z-keyword"> *</span><span> (</span><span class="z-constant">32000</span><span class="z-keyword"> +</span><span class="z-constant"> INITCODE_WORD_COST</span><span class="z-keyword"> *</span><span> words</span><span>(</span><span>calldata</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> access_list_cost</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> TOTAL_COST_FLOOR_PER_TOKEN</span><span class="z-keyword"> *</span><span> total_data_tokens</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>Any transaction with a gas limit below <code>21000 + TOTAL_COST_FLOOR_PER_TOKEN * total_data_tokens</code> or below its intrinsic gas cost is considered invalid.</p> <h2 id="rationale">Rationale</h2> <p>Access list data is always charged at floor rate (added to <code>access_list_cost</code>), and access list tokens are included in the floor calculation. This ensures:</p> <ul> <li>Access list data always pays floor rate regardless of execution level</li> <li>Access lists cannot be used to bypass the calldata floor pricing</li> <li>Consistent pricing across all transaction data sources</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backwards incompatible gas repricing that requires a scheduled network upgrade.</p> <p>Requires updates to gas estimation in wallets and nodes. Normal usage patterns remain largely unaffected.</p> <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">def</span><span class="z-entity z-name"> calculate_access_list_tokens</span><span>(</span><span class="z-variable z-parameter z-function">access_list</span><span>:</span><span> Tuple</span><span>[</span><span>Access</span><span>,</span><span class="z-constant"> ...</span><span>]</span><span>)</span><span> -&gt;</span><span> Uint</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span><span class="z-string">Count data tokens in access list addresses and storage keys.</span><span class="z-punctuation z-definition z-string">&quot;&quot;&quot;</span></span> <span class="giallo-l"><span> zero_bytes</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> nonzero_bytes</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> <span class="giallo-l"><span class="z-keyword"> for</span><span> access</span><span class="z-keyword"> in</span><span> access_list</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> byte</span><span class="z-keyword"> in</span><span> access</span><span>.</span><span>account</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> byte</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> zero_bytes</span><span class="z-keyword"> +=</span><span> Uint</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> nonzero_bytes</span><span class="z-keyword"> +=</span><span> Uint</span><span>(</span><span class="z-constant">1</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> slot</span><span class="z-keyword"> in</span><span> access</span><span>.</span><span>slots</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> byte</span><span class="z-keyword"> in</span><span> slot</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> byte</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> zero_bytes</span><span class="z-keyword"> +=</span><span> Uint</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> nonzero_bytes</span><span class="z-keyword"> +=</span><span> Uint</span><span>(</span><span class="z-constant">1</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> zero_bytes</span><span class="z-keyword"> +</span><span> nonzero_bytes</span><span class="z-keyword"> *</span><span> Uint</span><span>(</span><span class="z-constant">4</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"> calculate_intrinsic_cost</span><span>(</span><span class="z-variable z-parameter z-function">tx</span><span>:</span><span> Transaction</span><span>)</span><span> -&gt;</span><span> Tuple</span><span>[</span><span>Uint</span><span>,</span><span> Uint</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"> Calculate intrinsic gas cost and floor gas cost.</span></span> <span class="giallo-l"><span class="z-string"> Returns (intrinsic_gas, floor_gas).</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"> Calldata tokens</span></span> <span class="giallo-l"><span> calldata_zero_bytes</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 class="z-keyword"> for</span><span> byte</span><span class="z-keyword"> in</span><span> tx</span><span>.</span><span>data</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> byte</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> calldata_zero_bytes</span><span class="z-keyword"> +=</span><span> Uint</span><span>(</span><span class="z-constant">1</span><span>)</span></span> <span class="giallo-l"><span> tokens_in_calldata</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> calldata_zero_bytes</span><span class="z-keyword"> +</span><span> (</span><span>ulen</span><span>(</span><span>tx</span><span>.</span><span>data</span><span>)</span><span class="z-keyword"> -</span><span> calldata_zero_bytes</span><span>)</span><span class="z-keyword"> *</span><span> Uint</span><span>(</span><span class="z-constant">4</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"> Access list tokens and cost</span></span> <span class="giallo-l"><span> tokens_in_access_list</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> access_list_cost</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 class="z-keyword"> if</span><span> has_access_list</span><span>(</span><span>tx</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> tokens_in_access_list</span><span class="z-keyword"> =</span><span> calculate_access_list_tokens</span><span>(</span><span>tx</span><span>.</span><span>access_list</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> access</span><span class="z-keyword"> in</span><span> tx</span><span>.</span><span>access_list</span><span>:</span></span> <span class="giallo-l"><span> access_list_cost</span><span class="z-keyword"> +=</span><span class="z-constant"> TX_ACCESS_LIST_ADDRESS_COST</span></span> <span class="giallo-l"><span> access_list_cost</span><span class="z-keyword"> +=</span><span> ulen</span><span>(</span><span>access</span><span>.</span><span>slots</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> TX_ACCESS_LIST_STORAGE_KEY_COST</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> EIP-7981: Always charge data cost</span></span> <span class="giallo-l"><span> access_list_cost</span><span class="z-keyword"> +=</span><span> tokens_in_access_list</span><span class="z-keyword"> *</span><span class="z-constant"> TOTAL_COST_FLOOR_PER_TOKEN</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> EIP-7981: Floor includes all data tokens</span></span> <span class="giallo-l"><span> total_data_tokens</span><span class="z-keyword"> =</span><span> tokens_in_calldata</span><span class="z-keyword"> +</span><span> tokens_in_access_list</span></span> <span class="giallo-l"><span> floor_gas</span><span class="z-keyword"> =</span><span class="z-constant"> TX_BASE_COST</span><span class="z-keyword"> +</span><span> total_data_tokens</span><span class="z-keyword"> *</span><span class="z-constant"> TOTAL_COST_FLOOR_PER_TOKEN</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Intrinsic gas</span></span> <span class="giallo-l"><span> calldata_cost</span><span class="z-keyword"> =</span><span> tokens_in_calldata</span><span class="z-keyword"> *</span><span class="z-constant"> STANDARD_TOKEN_COST</span></span> <span class="giallo-l"><span> create_cost</span><span class="z-keyword"> =</span><span class="z-constant"> TX_CREATE_COST</span><span class="z-keyword"> +</span><span> init_code_cost</span><span>(</span><span>tx</span><span>.</span><span>data</span><span>)</span><span class="z-keyword"> if</span><span> is_create</span><span>(</span><span>tx</span><span>)</span><span class="z-keyword"> else</span><span> Uint</span><span>(</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> intrinsic_gas</span><span class="z-keyword"> =</span><span class="z-constant"> TX_BASE_COST</span><span class="z-keyword"> +</span><span> calldata_cost</span><span class="z-keyword"> +</span><span> create_cost</span><span class="z-keyword"> +</span><span> access_list_cost</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> intrinsic_gas</span><span>,</span><span> floor_gas</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>This EIP closes a loophole that allows circumventing <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> floor pricing. Without this fix, attackers can achieve larger blocks than intended by combining access lists with calldata. All transaction data sources now contribute to the floor calculation consistently.</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-23T00:00:00+00:00 2026-02-11T14:49:27+00:00 Charlie Noyescharlie@paradigm.xyz Dan Robinsondan@paradigm.xyz Justin Drakejustin@ethereum.org Toni Wahrstätterhttps://github.com/nerolation https://wg-eips.ritovision.com/7862/

Separate state root computation from block validation

<h2 id="abstract">Abstract</h2> <p>This proposal decouples state root computation from block validation by deferring the execution layer's state root reference by one block. Each block's header contains the post-state root of the previous block rather than its own. Validators can attest to block validity without waiting for state root computation.</p> <h2 id="motivation">Motivation</h2> <p>State root computation is a significant bottleneck in block production. With <a href="https://wg-eips.ritovision.com/7732/">EIP-7732</a> (ePBS), builders have tighter timing constraints. <a href="https://wg-eips.ritovision.com/7928/">EIP-7928</a> (Block-Level Access Lists) enables parallel state access but doesn't help with state root computation for builders.</p> <p>With delayed state roots:</p> <ol> <li><strong>Builders compute one state root per slot</strong> (for the previous block) instead of thousands during the MEV auction window</li> <li><strong>State root computation can use BAL data</strong> from the previous block to parallelize proof generation</li> <li><strong>The critical path shifts</strong>: state root computation is frontloaded to the beginning of the slot rather than blocking attestations</li> </ol> <p>The state root in block <code>n</code> represents the post-state of block <code>n-1</code> (equivalently: the pre-state of block <code>n</code>). Light clients experience one slot of additional latency for state proofs.</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="header">Header</h3> <p>The <code>state_root</code> field semantics change. No new fields are added.</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"> Header</span><span>:</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> state_root</span><span>:</span><span> Root</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Post-state of block (n-1), i.e., pre-state of this block</span></span> <span class="giallo-l"><span> transactions_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> receipt_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> bloom</span><span>:</span><span> Bloom</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> <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> <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> <span class="giallo-l"><span> requests_hash</span><span>:</span><span> Hash32</span></span> <span class="giallo-l"><span> block_access_list_hash</span><span>:</span><span> Hash32</span></span></code></pre><h3 id="blockchain">BlockChain</h3> <p>The <code>BlockChain</code> object tracks the last computed state root:</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"> 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_computed_state_root</span><span>:</span><span> Root</span></span></code></pre><h3 id="header-validation">Header Validation</h3> <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_header</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"> header</span><span>:</span><span> Header</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> header</span><span>.</span><span>number</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 1</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> parent_header</span><span class="z-keyword"> =</span><span> chain</span><span>.</span><span>blocks</span><span>[</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>]</span><span>.</span><span>header</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 delayed state root matches the last computed state root</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> header</span><span>.</span><span>state_root</span><span class="z-keyword"> !=</span><span> chain</span><span>.</span><span>last_computed_state_root</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"> ... remaining validation unchanged</span></span></code></pre><h3 id="state-transition">State Transition</h3> <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_transition</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> 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> block_env</span><span class="z-keyword"> =</span><span> vm</span><span>.</span><span>BlockEnvironment</span><span>(</span><span class="z-constant">...</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> block_output</span><span class="z-keyword"> =</span><span> apply_body</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"> transactions</span><span class="z-keyword">=</span><span>block</span><span>.</span><span>transactions</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> withdrawals</span><span class="z-keyword">=</span><span>block</span><span>.</span><span>withdrawals</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"> Validate all roots except state_root (already validated in header)</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> 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-punctuation z-definition z-comment"> #</span><span class="z-comment"> ... other validations</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 and store state root for the NEXT block</span></span> <span class="giallo-l"><span> chain</span><span>.</span><span>last_computed_state_root</span><span class="z-keyword"> =</span><span> state_root</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> chain</span><span>.</span><span>blocks</span><span>.</span><span>append</span><span>(</span><span>block</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>chain</span><span>.</span><span>blocks</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 255</span><span>:</span></span> <span class="giallo-l"><span> chain</span><span>.</span><span>blocks</span><span class="z-keyword"> =</span><span> chain</span><span>.</span><span>blocks</span><span>[</span><span class="z-keyword">-</span><span class="z-constant">255</span><span>:</span><span>]</span></span></code></pre><h3 id="fork-activation">Fork Activation</h3> <p>At activation block <code>F</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"> apply_fork</span><span>(</span><span class="z-variable z-parameter z-function">old</span><span>:</span><span> BlockChain</span><span>)</span><span> -&gt;</span><span> BlockChain</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Initialize last_computed_state_root to current state root</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> (post-state of block F-1)</span></span> <span class="giallo-l"><span> old</span><span>.</span><span>last_computed_state_root</span><span class="z-keyword"> =</span><span> state_root</span><span>(</span><span>old</span><span>.</span><span>state</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> old</span></span></code></pre> <p>Block <code>F</code> MUST contain the post-state root of block <code>F-1</code>. From <code>F+1</code> onwards, each block contains its parent's post-state root.</p> <h2 id="rationale">Rationale</h2> <h3 id="epbs-compatibility">ePBS Compatibility</h3> <p>With <a href="https://wg-eips.ritovision.com/7732/">EIP-7732</a>, the <code>ExecutionPayloadEnvelope</code> contains a CL <code>state_root</code> verified at the end of <code>process_execution_payload</code>. This EIP changes only the EL header's <code>state_root</code> semantics. The CL state root verification is unaffected.</p> <h3 id="bal-synergy">BAL Synergy</h3> <p><a href="https://wg-eips.ritovision.com/7928/">EIP-7928</a> provides the block access list, which identifies all storage slots touched during execution. With delayed state roots, clients can:</p> <ol> <li>Receive block <code>n</code> with BAL</li> <li>Use the BAL to parallelize state root computation for block <code>n</code></li> <li>Include that root in block <code>n+1</code></li> </ol> <p>Without this EIP, BALs don’t help with state root computation: the root is only known after execution finishes, which is too late to use within the same slot. With this proposal, builders can start constructing a block without fully executing the previous one, by applying the BAL state diff to the slot’s pre-state.</p> <h3 id="light-client-impact">Light Client Impact</h3> <p>State proofs for block <code>n</code> require waiting for block <code>n+1</code>. Most light client protocols already tolerate multi-block delays for proof generation. The security model is unchanged; only timing shifts by one slot.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Requires a hard fork. Clients that do not implement this change will reject blocks with delayed state roots.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="reorganization-handling">Reorganization Handling</h3> <p>During reorgs, clients MUST recompute <code>last_computed_state_root</code> for each block in the new canonical chain. The delayed nature does not affect reorg logic.</p> <h3 id="pre-state-availability">Pre-state Availability</h3> <p>Clients MUST retain the pre-state (post-state of parent block) until the current block's state root is included in the next block. This is already standard practice for reorg handling.</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-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 William Entrikenhttps://github.com/fulldecent https://wg-eips.ritovision.com/7848/

Allows participants to indicate readiness for a client upgrade when producing blocks

<h2 id="abstract">Abstract</h2> <p>This proposal adds a mechanism for clients to signal their willingness for a network upgrade by including a “reference implementation hash” field in each block. A network upgrade activates only if enough blocks specify that they are using the new software.</p> <h2 id="motivation">Motivation</h2> <p>Currently, upgrades to Ethereum Mainnet are announced on the ethereum.org blog. This proposal changes that process by activating upgrades based on the consent of network participants.</p> <h2 id="specification">Specification</h2> <p>Ethereum consensus clients shall identify with a reference implementation having its equivalent behaviors.</p> <p>Ethereum consensus clients shall include a <code>referenceImplementationHash</code> (specified below) field immediately following the <code>extraData</code> field in the block header.</p> <p>Proposed new Ethereum consensus clients shall initially behave as the then-current network does. If, and only if, a successful upgrade (defined below) is activated will the new behavior take effect.</p> <p>When a network participant is willing to support a network upgrade, they shall immediately begin using the new software. The blocks they create including the new <code>referenceImplementationHash</code> will contribute to the network upgrade activation.</p> <h3 id="the-reference-implementation-hash">The Reference Implementation Hash</h3> <p>When proposing a network upgrade, the proposer shall point to a published, feature-complete reference implementation including the new software behaviors.</p> <p>The <strong>reference implementation hash</strong> is the SHA-256 hash of the tarred source code of this reference implementation.</p> <h3 id="verification">Verification</h3> <p>Network participants shall study the reference implementation and decide whether they support an upgrade.</p> <p>Network participants shall study any specific software they will run and ensure it faithfully implements the behaviors consistent with that reference implementation.</p> <h3 id="upgrade">Upgrade</h3> <p>Upgrade proposals (often referred to as hard fork EIPs) must specify an upgrade window and threshold. These parameters are implemented in the consensus client:</p> <ul> <li><code>VOTING_WINDOW_BEGIN</code>: the first block (inclusive) to count votes.</li> <li><code>VOTING_WINDOW_END</code>: the last block (inclusive) to count votes.</li> <li><code>REFERENCE_IMPLEMENTATION_HASH</code>: this is defined above.</li> <li><code>REQUIRED_APPROVALS</code>: the minimum number of approvals necessary for the upgrade.</li> </ul> <p>The difference (<code>VOTING_WINDOW_END</code> - <code>VOTING_WINDOW_BEGIN</code>) must be strictly greater than 14400 (about two days) and should be chosen to provide sufficient time to advertise the upgrade to network participants.</p> <p>The required approvals must be strictly greater than 50% of the blocks in the voting window. A higher threshold (such as 95% or more) is recommended.</p> <p>When the block numbered <code>VOTING_WINDOW_END</code> is created, the upgrade is considered "activated" if <code>REQUIRED_APPROVALS</code> or more blocks during the voting window had set <code>referenceImplementationHash</code> to the value <code>REFERENCE_IMPLEMENTATION_HASH</code>; otherwise, the upgrade fails.</p> <p>Blocks created from <code>VOTING_WINDOW_END</code> + 1 onward will use the new software behaviors if and only if the upgrade was successful.</p> <p>For proof-of-work networks and other scenarios, it is possible that one fork activates the upgrade while another does not. In any case, blocks strictly greater than <code>VOTING_WINDOW_END</code> shall be created according to the behaviors of the software considering the outcome of the votes in the voting window which are the ancestors of that block.</p> <p>Note: Just because an upgrade was activated, this does not necessarily mean that the new software behaviors must generate block <code>VOTING_WINDOW_END</code> + 1 differently than the old software behaviors. Perhaps the new software behaviors will stipulate that only blocks at some later time will generate differently. Perhaps the new software behaviors include some other consensus change which does not change how blocks are created.</p> <h2 id="rationale">Rationale</h2> <h3 id="forking-is-no-longer-possible">Forking is no Longer Possible</h3> <p>Since the merge, forking Ethereum Mainnet has become practically impossible. Validators stake valuable assets to participate in the network, so any rational validator will choose to upgrade only if they expect widespread adoption. If a validator expects 95% or more participants to upgrade, they should upgrade; if they expect only 5% or less, they should not. For intermediate cases, there is a threshold where a validator would rationally shut down (incurring a small penalty) rather than risk participating in the wrong network—which could result in slashing 100% of their staked ether (currently 16 Ether per share).</p> <p>Therefore, proper management of consensual upgrades is crucial.</p> <h3 id="community-direction">Community Direction</h3> <ol> <li>The Ethereum project and community do not have an official mission statement or vision. However, this proposal asserts that the Ethereum community would prefer Ethereum Mainnet to be a community-directed project.</li> <li>On-chain signaling of upgrades enables community direction in a way that is not possible today.</li> </ol> <h3 id="window">Window</h3> <p>Using a voting window to count votes provides real-time on-chain feedback about upgrade readiness. The upgrade is activated only after the successful completion of the voting window.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <h3 id="trademark">Trademark</h3> <p>The Ethereum Foundation (Stiftung Ethereum), Zug, Switzerland, owns the trademark “Ethereum.” As a result, if anybody publishes a proposed Ethereum Mainnet consensus client, the foundation may have the right to restrict marketing of that software as an “Ethereum” client. That also poses unique risks related to securities rules.</p> <h3 id="eip-2124">EIP-2124</h3> <p>EIP-2124 introduces a mechanism to communicate software versions between nodes. However, it does not allow for signaling readiness before an upgrade, nor does it specify what software is being upgraded to.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Any upgrade that achieves less than 100% participation will harm validators who do not participate.</p> <ul> <li>Overlapping or competitive upgrades must be managed carefully; such scenarios could result in multiple networks achieving the minimum approval threshold.</li> <li>An upgrade with an excessively long time period could hinder/delay the proposal of subsequent upgrades.</li> <li>Since the four voting parameters are embedded in the reference implementation, network participants must exercise due diligence to ensure that they understand the actual software behaviors.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights have been waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-12-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Juntillahttps://github.com/nickjuntillanick@ownerfy.com https://wg-eips.ritovision.com/7847/

Create a social media post or publication in the form of an NFT.

<h2 id="abstract">Abstract</h2> <p>This proposal defines a standardized format for representing decentralized social media posts as NFTs. The Nostr protocol has done most of the heavy lifting for creating an open decentralized social media network. This ERC serves to adapt those standards to the most common blockchain non-fungible token standard. In this way we can take advantage of the reach and longevity of a blockchain. It is genericized here so that it can be easily mapped to other event based decentralized social media like the AT protocol. An event can be used as a social media post, blog post, forum post, encrypted message, RSS feed or arbitrary electronic publication. This model is flexible where the meaning and type of an event (original, reply, repost, images, video, text, etc...) is derived from its metadata. A user is anyone who has a private key. There is no permission required and anyone can create content using any NFT contract. Anyone can collate that content into a feed or timeline.</p> <p>Posts may be "owned" by their creators, but the owner of the NFT itself is not meaningful in the standard. This may be a useful mechanic for financial purposes, but the independent signature of the post allows for a third party to publish a message on behalf of another user.</p> <h2 id="motivation">Motivation</h2> <p>With the continued censorship and manipulation of social media platforms, it becomes increasingly important for truly decentralized and permissionless social media to exist. Unlike other attempts at blockchain decentralized social media, this method does not rely on a centralized set of smart contracts. Blockchain integration of author-signed event based social media simply adds a powerful substrate for standardized decentralized social media to exist in. The benefits of blockchain include, but are not limited to, longevity, censorship resistance, monetary, and neutrality. The NFT standard is the most common and widely used standard for representing unique digital data on the blockchain. Using the NFT standard and standard NFT properties means that every marketplace, wallet and app that makes NFTs viewable is also a publication channel. With the data publicly available, custom feed algorithms can also be built to give control back to users.</p> <h2 id="specification">Specification</h2> <h3 id="to-derive-the-id">To derive the id</h3> <p>To obtain the id, we sha256 the serialized attributes in this order. The serialization is done over the UTF-8 JSON-serialized string of the following 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-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span class="z-invalid z-illegal"> &lt;</span><span class="z-invalid z-illegal">p</span><span class="z-invalid z-illegal">u</span><span class="z-invalid z-illegal">b</span><span class="z-invalid z-illegal">k</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">y</span><span>,</span><span class="z-invalid z-illegal"> a</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal"> a</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">e</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">c</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal"> h</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">x</span><span class="z-invalid z-illegal"> s</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">r</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">&gt;</span><span>,</span></span> <span class="giallo-l"><span class="z-invalid z-illegal"> &lt;</span><span class="z-invalid z-illegal">c</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">d</span><span class="z-invalid z-illegal">_</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">t</span><span>,</span><span class="z-invalid z-illegal"> u</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">x</span><span class="z-invalid z-illegal"> t</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">m</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">m</span><span class="z-invalid z-illegal">p</span><span class="z-invalid z-illegal"> i</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal"> s</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">c</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">d</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal">&gt;</span><span>,</span></span> <span class="giallo-l"><span class="z-invalid z-illegal"> &lt;</span><span class="z-invalid z-illegal">k</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">d</span><span>,</span><span class="z-invalid z-illegal"> a</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal"> a</span><span class="z-invalid z-illegal"> n</span><span class="z-invalid z-illegal">u</span><span class="z-invalid z-illegal">m</span><span class="z-invalid z-illegal">b</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">&gt;</span><span>,</span></span> <span class="giallo-l"><span class="z-invalid z-illegal"> &lt;</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">g</span><span class="z-invalid z-illegal">s</span><span>,</span><span class="z-invalid z-illegal"> a</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal"> a</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal"> a</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">y</span><span class="z-invalid z-illegal"> o</span><span class="z-invalid z-illegal">f</span><span class="z-invalid z-illegal"> a</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">y</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal"> o</span><span class="z-invalid z-illegal">f</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">-</span><span class="z-constant">null</span><span class="z-invalid z-illegal"> s</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">r</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">s</span><span class="z-invalid z-illegal">&gt;</span><span>,</span></span> <span class="giallo-l"><span class="z-invalid z-illegal"> &lt;</span><span class="z-invalid z-illegal">c</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">t</span><span>,</span><span class="z-invalid z-illegal"> a</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal"> a</span><span class="z-invalid z-illegal"> s</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">r</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">&gt;</span></span> <span class="giallo-l"><span>]</span></span></code></pre> <p><strong>To prevent implementation differences from creating a different event ID for the same event, the following rules MUST be followed while serializing:</strong></p> <ul> <li>UTF-8 should be used for encoding.</li> <li>Preceding and trailing whitespace must be trimmed from serialized JSON and field values.</li> <li>If spaces are used in tags they must be single spaces within array values.</li> <li>The following characters in the content field must be escaped as shown, and all other characters must be included verbatim: <ul> <li>A line break (0x0A), use \n</li> <li>A double quote (0x22), use "</li> <li>A backslash (0x5C), use \</li> <li>A carriage return (0x0D), use \r</li> <li>A tab character (0x09), use \t</li> <li>A backspace, (0x08), use \b</li> <li>A form feed, (0x0C), use \f</li> </ul> </li> </ul> <h3 id="kinds">Kinds</h3> <p>0: User metadata: the content is set to a stringified JSON object {name: <code>&lt;username&gt;</code>, about: <code>&lt;string&gt;</code>, picture: <code>&lt;url, string&gt;</code>} describing the user who created the event. Extra metadata fields may be set. A relay may delete older events once it gets a new one for the same pubkey. 1: Original content: original generated user content is usually accompanied by short-form text, but may include off-chain or on-chain references to other media or events.</p> <h3 id="tags">Tags</h3> <p>Tags are a flexible mechanism to attach additional structured data to a post. Each tag is an array of one or more strings, with some conventions around them.</p> <ul> <li>The blockchain tag is <strong>recommended</strong> for events published using this method. <code>["blockchain", "&lt;blockchain-name-or-id&gt;", "&lt;contract&gt;", "&lt;token_id"&gt;]</code></li> </ul> <p>where:</p> <ul> <li><code>&lt;blockchain-name-or-id&gt;</code> is the name of the chain. e.g. "Ethereum", "Polygon", "Base" or chain id. e.g. "1", "137", "8453"</li> <li><code>&lt;contract&gt;</code> is the contract address. e.g. "0x0000000000000000000000000000000000000000"</li> <li><code>&lt;token_id&gt;</code> is the token id. e.g. "12345". The token_id may be omitted if it is not known before publication as it is part of the signed data.</li> </ul> <p><strong>Optional tags:</strong></p> <ul> <li> <p>Multiple media tags can be attached by using multiple imeta tags <code>["imeta", ...]</code></p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">imeta</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">dim 1920x1080</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">url &lt;URL&gt;/1080/12345.mp4</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">m video/mp4</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span>]</span></span></code></pre></li> <li> <p>References to Other Posts: <code>["e", "&lt;id_of_referenced_post&gt;"]</code></p> </li> <li> <p>Public addresses involved in this post: <code>["p", "&lt;pubkey&gt;", ...]</code></p> </li> <li> <p>External URLs: <code>["r", "&lt;URL&gt;"]</code></p> </li> </ul> <h3 id="metadata-json">Metadata JSON</h3> <p>Event fields are stored in the NFT's metadata under <code>attributes</code>. The <code>description</code> field of the NFT is identical to <code>content</code>. The <code>name</code> may be user defined or include the author and time created. All attributes besides <code>id</code>, <code>pubkey</code>, <code>created_at</code>, <code>kind</code>, <code>sig</code>, and <code>content</code> are assumed to be event tags.</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">&lt;title of post&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">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;string should match the attribute content tag&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">image</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;optional usually the first m image tag&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">animation_url</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;optional use this for multi-media such as MP4, MP3, WAV, WEBM, etc... should be included in imeta tags as well&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">external_url</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;optional should be included in attribute r tags&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">attributes</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">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">id</span><span class="z-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">&lt;32-bytes lowercase hex-encoded sha256 of the serialized attribute data&gt;</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">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">pubkey</span><span class="z-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">&lt;32-bytes lowercase hex-encoded public key of the public creator&gt;</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">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">created_at</span><span class="z-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-invalid z-illegal"> &lt;</span><span class="z-invalid z-illegal">u</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">x</span><span class="z-invalid z-illegal"> t</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">m</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">m</span><span class="z-invalid z-illegal">p</span><span class="z-invalid z-illegal"> i</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal"> s</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">c</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">d</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal">&gt;</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">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">kind</span><span class="z-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-invalid z-illegal"> &lt;</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">g</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal"> b</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">w</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">n</span><span class="z-constant"> 0</span><span class="z-invalid z-illegal"> a</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">d</span><span class="z-constant"> 65535</span><span class="z-invalid z-illegal">&gt;</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">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">sig</span><span class="z-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">&lt;64-bytes lowercase hex of the signature of the sha256 hash of the serialized attribute data, which is the same as the id field&gt;</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">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">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">value</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;this key should match the description even if empty string&gt;</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">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">imeta</span><span class="z-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">&lt;optional imeta tags&gt;</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">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">e</span><span class="z-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">&lt;optional ID of referenced event&gt;</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">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">r</span><span class="z-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">&lt;optional reference to external URL&gt;</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-invalid z-illegal"> .</span><span class="z-invalid z-illegal">.</span><span class="z-invalid z-illegal">.</span><span class="z-invalid z-illegal">&lt;</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">r</span><span class="z-invalid z-illegal">_</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal">p</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">_</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">b</span><span class="z-invalid z-illegal">u</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal">&gt;</span><span>,</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="generating-keys">Generating Keys</h3> <p><strong>Private key:</strong> Any Ethereum private key or mnemonic phrase can be used, as long as the result is a 32-byte hex string. A key can be generated locally as well with a command like <code>openssl rand -hex 32</code>. This key is used to sign the post and is stored in the pubkey field.</p> <p><strong>Public key:</strong> Public keys are based on Taproot + Schnorr, bitcoin <a rel="external" href="https://github.com/bitcoin/bips/blob/5767f444995df378ad772887b739e84bd9002d95/bip-0341.mediawiki">BIP 341</a>. It's recommended to use a tool like nostr-tools to generate a public key from a private key.</p> <h3 id="sign-a-post">Sign a post</h3> <p>Signatures are based on schnorr signatures standard for the curve secp256k1. To sign with Schnorr signatures on secp256k1, you need a private key, a message, and a random nonce (k). You then calculate a public nonce (R), a challenge (e), and finally, the signature (s) by combining these values. It's best to use a tool like nostr-tools or nostril or schnorr.c in the bitcoin core library.</p> <h3 id="the-pubevent">The PubEvent</h3> <h3 id="when-a-new-post-is-created">When a new post is created</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"> PubEvent</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> id</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"> pubkey</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> created_at</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> kind</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> content</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> tags</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> sig</span><span>,</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre> <ul> <li><code>id</code>: the unique identifier of the post.</li> <li><code>pubkey</code>: the public key of the post creator.</li> <li><code>created_at</code>: the timestamp of creation.</li> <li><code>kind</code>: the event kind; 1, for an original post.</li> <li><code>content</code>: the textual content of the post.</li> <li><code>tags</code>: the structured metadata.</li> <li><code>sig</code>: the signature of the post data. Should be 64 bytes.</li> </ul> <h3 id="to-reply-to-a-post">To reply to a post</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"> PubEvent</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> id</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"> pubkey</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> created_at</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> kind</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> content</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> tags</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> sig</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre> <ul> <li><code>id</code>: The unique identifier of the post.</li> <li><code>pubkey</code>: The public key of the post creator.</li> <li><code>created_at</code>: The timestamp of creation.</li> <li><code>kind</code>: Also 1 for replies.</li> <li><code>content</code>: The textual content of the post.</li> <li><code>tags</code>: The structured metadata including outlined below.</li> <li><code>sig</code>: The signature of the post data. Should be 64 bytes.</li> </ul> <h3 id="the-reply-e-tag">The reply "e" tag</h3> <p><code>["e", &lt;event-id&gt;, &lt;relay-url&gt;, &lt;marker&gt;, &lt;pubkey&gt;]</code></p> <p><strong>Where:</strong></p> <p><code>&lt;event-id&gt;</code> is the id of the event being referenced. <code>&lt;relay-url&gt;</code> optionally is the URL of a recommended off-chain relayer. Use empty string,"", if none or on the blockchain only. <code>&lt;marker&gt;</code> is optional and if present is one of "reply", "root", or "mention". <code>&lt;pubkey&gt;</code> is optional, SHOULD be the pubkey of the author of the referenced event</p> <p>Those marked with "reply" denote the id of the reply event being responded to. Those marked with "root" can denote the root id of the reply thread being responded to. Those marked with "mention" denote a quoted or reposted event id.</p> <p><code>&lt;pubkey&gt;</code> SHOULD be the pubkey of the author of the e tagged event, this is used in the outbox model to search for that event from the author's write relays where relay hints did not resolve the event.</p> <h3 id="the-p-tag">The "p" tag</h3> <p><code>["p", &lt;pubkey&gt;, ...]</code> Used in a text event contains a list of pubkeys used to record who is involved in a reply thread.</p> <p>When replying to a text event E the reply event's "p" tags can contain all of E's "p" tags as well as the "pubkey" of the event being replied to.</p> <p>Example: Given a text event authored by a1 with "p" tags [p1, p2, p3] then the "p" tags of the reply can be [a1, p1, p2, p3] in no particular order.</p> <h3 id="reposts">Reposts</h3> <p>A repost is a kind 6 event that is used to signal to followers that a kind 1 text post is worth reading.</p> <p>The content of a repost event is the stringified JSON of the reposted post. It MAY also be empty, but that is not recommended.</p> <p>The repost event MUST include an e tag with the id of the post that is being reposted. That tag should include a blockchain tag or indexer relay where the post can be fetched.</p> <p>The repost SHOULD include a p tag with the pubkey of the event being reposted.</p> <h3 id="quote-reposts">Quote Reposts</h3> <p>Quote reposts are kind 1 events with an embedded q tag of the post being quote reposted. The q tag ensures quote reposts are not pulled and included as replies in threads. It also allows you to easily pull and count all of the quotes for a post.</p> <p>q tags should follow the same conventions as e tags, with the exception of the mark argument.</p> <p><code>["q", &lt;event-id&gt;, &lt;relay-url&gt;, &lt;pubkey&gt;, &lt;blockchain-name-or-id&gt;]</code></p> <h2 id="rationale">Rationale</h2> <p>These attributes in the metadata are a 1:1 mapping of a Nostr-style event. Nostr is a blockchain compatible social media protocol because it uses a public/private key verification system that does not rely on a central set of smart contracts. It relies on the same format of private key EVM chains already use. It has a json based event system that is easily mapped to NFTs. Content can be freely moved between web3 and web2 based platforms. Each post is signed by the author, enabling tamperproof third-party transportation and publishing. A standardized tagging system enables referencing posts on other blockchains, other contracts, or external URLs.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Only the metadata format and PubEvent is 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"> createPost</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"> uri</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> id</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> pubkey</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> created_at</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span class="z-variable"> kind</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> content</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> tags</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> sig</span></span> <span class="giallo-l"><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-entity z-name"> mint</span><span>(</span><span>tokenId</span><span>,</span><span> uri</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> PubEvent</span><span>(</span><span>id</span><span>,</span><span> pubkey</span><span>,</span><span> created_at</span><span>,</span><span> kind</span><span>,</span><span> content</span><span>,</span><span> tags</span><span>,</span><span> sig</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre> <p>In this example <code>PubEvent</code> is <strong>required</strong> to announce a publication event has occurred. This event is flexible and can be used for all event types and kinds.</p> <h3 id="token-standards-compatibility">Token Standards Compatibility</h3> <ul> <li><strong><a href="https://wg-eips.ritovision.com/721/">ERC-721</a>:</strong> Each post should be a unique (<code>tokenId</code>).</li> <li><strong><a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>:</strong> A <code>tokenId</code> should only represent one post event even if minted multiple times.</li> </ul> <h4 id="backwards-compatibility">Backwards Compatibility</h4> <p>This is an additive standard on top of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>. Existing NFTs remain compatible; clients or platforms that understand this standard can interpret these tokens as social posts as well as traditional NFTs.</p> <h2 id="security-considerations">Security Considerations</h2> <p><strong>Data Integrity:</strong> Ensure that id is consistently <a href="https://wg-eips.ritovision.com/7847/#to-derive-the-id">derived, as described above</a>, to prevent forgeries. The owner of an NFT is inconsequential to the authenticity of the post, if the post is properly signed.</p> <h3 id="spam-and-moderation">Spam and Moderation</h3> <p>Event driven social media and NFTs both allow permissionless creation of content. Platforms built on this standard should implement their own moderation layers, blocklists, or reputation systems.</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-15T00:00:00+00:00 2026-02-11T14:48:26+00:00 Conner Swenberghttps://github.com/ilikesymmetry Jake Moxeyhttps://github.com/jxom Lukas Rosariohttps://github.com/lukasrosario https://wg-eips.ritovision.com/7846/

Adds JSON-RPC method for requesting wallet connection with modular capabilities.

<h2 id="abstract">Abstract</h2> <p>This ERC introduces a new wallet connection JSON-RPC method focused on extensibility, <code>wallet_connect</code>. It leverages the modular capabilities approach defined in <a href="https://wg-eips.ritovision.com/5792/#wallet-getcapabilities">ERC-5792</a> to streamline connections and authentication into a single interaction.</p> <h2 id="motivation">Motivation</h2> <p>With applications beginning to require support for more sophisticated functionality in wallet connection flows, the need for a unified and extensible wallet connection JSON-RPC method has become more apparent.</p> <p>This is especially evident in the case of attempting to batch connection with authentication, where existing methods like <code>eth_requestAccounts</code> and <code>personal_sign</code> lack extensibility and require at least two separate user interactions (ie. connect and then sign).</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="json-rpc-methods">JSON-RPC Methods</h3> <h4 id="wallet-connect"><code>wallet_connect</code></h4> <p>Requests to connect account(s) with optional capabilities.</p> <h5 id="request">Request</h5> <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"> Request</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> method</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">wallet_connect</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> params</span><span class="z-keyword">:</span><span> [</span><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> JSON-RPC method version.</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Optional capabilities to request (e.g. Sign In With Ethereum).</span></span> <span class="giallo-l"><span class="z-variable"> capabilities</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> unknown</span><span>&gt;</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="response">Response</h5> <p>List of connected accounts with their associated capabilities.</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"> Response</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> accounts</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address of the connected account.</span></span> <span class="giallo-l"><span class="z-variable"> address</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Capabilities granted that is associated with this account.</span></span> <span class="giallo-l"><span class="z-variable"> capabilities</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> unknown</span><span>&gt;</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>[</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="example">Example</h5> <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"> response</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">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">wallet_connect</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></span> <span class="giallo-l"><span> version</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">1</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> capabilities</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> signInWithEthereum</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">12345678</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> chainId</span><span>:</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> <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> <span class="giallo-l"><span class="z-comment"> * {</span></span> <span class="giallo-l"><span class="z-comment"> * accounts: [</span></span> <span class="giallo-l"><span class="z-comment"> * {</span></span> <span class="giallo-l"><span class="z-comment"> * address: &#39;0x...&#39;,</span></span> <span class="giallo-l"><span class="z-comment"> * capabilities: {</span></span> <span class="giallo-l"><span class="z-comment"> * signInWithEthereum: {</span></span> <span class="giallo-l"><span class="z-comment"> * message: &#39;app.com wants you to sign in with your Ethereum account:\n0x...&#39;,</span></span> <span class="giallo-l"><span class="z-comment"> * signature: &#39;0x...&#39;</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-comment"> * ]</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></code></pre><h4 id="wallet-disconnect"><code>wallet_disconnect</code></h4> <p>Disconnects connected account(s).</p> <ul> <li>The wallet SHOULD revoke access to the user account(s) information, as well as to any capabilities associated with them that were granted upon connection via <code>wallet_connect</code>.</li> </ul> <h5 id="request-1">Request</h5> <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"> Request</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> method</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">wallet_disconnect</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="example-1">Example</h5> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-keyword">await</span><span class="z-variable z-other"> provider</span><span>.</span><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">wallet_disconnect</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre><h3 id="capabilities">Capabilities</h3> <h4 id="signinwithethereum"><code>signInWithEthereum</code></h4> <p>Adds support for offchain authentication using <a href="https://wg-eips.ritovision.com/4361/">ERC-4361</a>.</p> <h5 id="parameters">Parameters</h5> <p>Same as ERC-4361 specification with minor modifications:</p> <ul> <li>The casing of multi-word fields has been adjusted to camelCase instead of kebab-case. Resources are an array field.</li> <li>The account address returned by <code>wallet_connect</code> MUST match the address inferred in the Sign-In with Ethereum (SIWE) message.</li> <li><code>version</code> is optional and defaults to an accepted version defined in ERC-4361 if not provided.</li> <li><code>domain</code> is optional and defaults to the domain of the requesting app if not provided.</li> <li><code>uri</code> is optional and defaults to the uri of the requesting app if not provided.</li> <li><code>issuedAt</code> is optional and defaults to the current time if not provided.</li> </ul> <p>The wallet MUST return a ERC-4361-formatted message that exactly matches the requested parameters and a signature over the <a href="https://wg-eips.ritovision.com/191/">EIP-191</a> <code>personal_sign</code> hash of the message. The app SHOULD also verify that the two match for security.</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"> Parameters</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> signInWithEthereum</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><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-variable"> chainId</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> EIP-155 hex-encoded</span></span> <span class="giallo-l"><span class="z-variable"> version</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"> scheme</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"> domain</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"> uri</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"> statement</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"> issuedAt</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"> expirationTime</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"> notBefore</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"> requestId</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"> resources</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> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="response-1">Response</h5> <p>Formatted SIWE message and signature.</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"> Response</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> signInWithEthereum</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Formatted SIWE message.</span></span> <span class="giallo-l"><span class="z-variable"> message</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Signature over the EIP-191 personal_sign hash of the message.</span></span> <span class="giallo-l"><span class="z-variable"> signature</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> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="example-2">Example</h4> <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"> result</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">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">wallet_connect</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></span> <span class="giallo-l"><span> version</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">1</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> capabilities</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> signInWithEthereum</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">12345678</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> chainId</span><span>:</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></span> <span class="giallo-l"><span> version</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">1</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> domain</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">app.com</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> uri</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">https://app.com/connect</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> issuedAt</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">2024-12-35T04:20:00Z</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> expirationTime</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">2024-12-35T06:09:00Z</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 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> <span class="giallo-l"><span class="z-comment"> * {</span></span> <span class="giallo-l"><span class="z-comment"> * accounts: [</span></span> <span class="giallo-l"><span class="z-comment"> * {</span></span> <span class="giallo-l"><span class="z-comment"> * address: &#39;0x...&#39;,</span></span> <span class="giallo-l"><span class="z-comment"> * capabilities: {</span></span> <span class="giallo-l"><span class="z-comment"> * signInWithEthereum: {</span></span> <span class="giallo-l"><span class="z-comment"> * message: &#39;app.com wants you to sign in with your Ethereum account:\n0x...&#39;,</span></span> <span class="giallo-l"><span class="z-comment"> * signature: &#39;0x...&#39;</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-comment"> * ]</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></code></pre><h2 id="rationale">Rationale</h2> <h3 id="multiple-accounts">Multiple Accounts</h3> <p>Returning multiple accounts allows greater generality for apps that wish to interact in more complex ways with users. This also improves our backwards compatibility with <code>eth_requestAccounts</code>. In practice, we expect most apps only interact with the first account in the array.</p> <h3 id="capability-results">Capability Results</h3> <p>Returning capability results alongside the connection unlocks many valuable use cases such as authentication, user metadata sharing, and permissions granted to the app.</p> <h3 id="initial-authentication-capability">Initial Authentication Capability</h3> <p>To ensure immediate value, this proposal includes a capability that combines wallet connection with authentication using the widely adopted <a href="https://wg-eips.ritovision.com/4361/">Sign In With Ethereum (ERC-4361)</a> standard. This optional capability simplifies the onboarding process for apps and users by combining two steps — connection and authentication — into a single interaction. Apps that prefer alternative authentication flows can implement their own capabilities without being constrained by this design.</p> <p>By unifying connection and authentication into one step, apps can reduce friction, improve the user experience, and minimize redundant interactions.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard builds on existing JSON-RPC methods and complements ERC-5792 for future extensibility. Wallets can continue supporting legacy methods.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Applies <a href="https://wg-eips.ritovision.com/4361/#security-considerations">ERC-4361 security principles</a>. As more capabilities are added, care must be taken to avoid unpredictable interactions.</p> <p>Wallet addresses and any shared capabilities must be handled securely to avoid data leaks or man-in-the-middle 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> 2024-12-12T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ellie Davidsonhttps://github.com/elliedavidson Alex Xionghttps://github.com/alxiong Philippe Camachohttps://github.com/philippecamacho and Ben Fischhttps://github.com/benafisch https://wg-eips.ritovision.com/7841/

A mailbox API and message format to provide a unified cross-chain developer experience

<h2 id="abstract">Abstract</h2> <p>This ERC proposes a <strong>mailbox API</strong> and <strong>message format</strong> for sending and receiving data between L2s. This standard makes it easier for developers to build cross-chain applications that work over a variety of VMs, chain settlement mechanisms (e.g., ZK or optimistic settlement), and messaging protocols (e.g., synchronous or asynchronous protocols). This ERC accomplishes this by 1.) defining a mailbox interface through which cross-chain messages can be sent and received independent of their payload; 2.) defining a VM-agnostic message format and address type to make the interface compatible with many VMs; 3.) keeping the mailbox interface minimal to make it compatible with many kinds of cross-chain communication. Example applications include an intent-based bridge, a liquidity-unifying DEX operating across multiple chains, or a cross-chain lending application.</p> <h2 id="motivation">Motivation</h2> <p>L2s have scaled Ethereum and unlocked new avenues for innovation, but left the ecosystem <em>fragmented</em>. To address this, there are a variety of cross-chain communication protocols designed to make L2s composable with each other, each implements its own message format that is incompatible with others. This ERC proposes a neutral, standard format for sending and receiving cross-chain messages. By standardizing the interface chains for messaging, we achieve:</p> <ul> <li><strong>Unified developer experience:</strong> This standard abstracts away the low-level details of message passing from applications. This allows application developers to achieve the following, even among chains with different VMs, coordination protocols, or settlement logic: <ul> <li>send/receive messages to/from many chains using the <strong>same interface</strong>.</li> <li>deploy their application across multiple chains with <strong>little-to-no</strong> code changes.</li> <li>focus on their application’s design instead of cross-chain infrastructure.</li> </ul> </li> <li><strong>Modularity:</strong> This ERC standardizes only the low level information required for sending and receiving messages between chains, similar to the Internet Protocol. This allows a <strong>clean separation</strong> between the interface for sending/receiving messages (this ERC) and a coordination protocol or settlement mechanism. This allows chains to adopt this standard with minimal changes, and gives chains <strong>flexibility</strong> to choose the specific protocols they need, instead of forcing all chains to agree on a single coordination protocol or settlement mechanism.</li> <li><strong>Shared Infrastructure:</strong> This standard allows applications and chains to <strong>reuse/repurpose infrastructure</strong> for different use cases. Applications can leverage existing library contracts for common operations like encoding message payload for token transfer, while relayer networks can serve multiple purposes without significant modifications. This shared foundation simplifies the development and deployment of new chains, applications, and protocols.</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> <h3 id="terminology">Terminology</h3> <ul> <li>A <strong>Messaging Protocol</strong> consists of mailbox contracts and a coordination (sub)protocol. A chain sends a message through a transaction that writes to its outbox and receives a message through a transaction that reads from the inbox.</li> <li><strong>Coordination Protocol</strong>: A mechanism that relays messages between source and destination mailboxes, commonly through off-chain mechanisms. Examples include shared sequencers or intent relayers. A settlement mechanism to ensure the integrity of cross-chain messages is often part of a coordination protocol. It is not always required in the case of asynchronous messaging.</li> <li>In <em><strong>synchronous</strong></em> messaging protocols, chains have synchronized blocks (e.g., a block for each chain is produced every <em>t</em> seconds) and messages are received on the destination chain within the same block timeslot as they were sent from the source chain. In particular, a chain may send a message and read a response in one transaction within a block on a chain.</li> <li>In <em><strong>asynchronous</strong></em> messaging protocols the restrictions of synchronous protocols do not apply. In particular, the chains sending and receiving messages may not have synchronized block timeslots and there may be a delay (measured in elapsed blocks) between the transaction on the source chain that sends a message and the transaction on the destination chain in which it is received.</li> </ul> <p>There is a wide range of ways in which both synchronous and asynchronous protocols may operate. For example, some protocols (particularly for asynchronous messaging) may require the source chain's block in which the message was sent to be finalized (e.g., settled on Ethereum) before it can be included within a block produced for the destination chain. Other protocols may allow for messages to be optimistically included in blocks with consistency checks delayed until settlement time (reminiscent of speculative execution).</p> <h3 id="message-format">Message Format</h3> <p>All messages MUST follow this format:</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"> Metadata type</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Metadata for a cross-chain message</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> The chain identifier of the source chain</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> srcChainId</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"> The chain identifier of the destination chain</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> destChainId</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"> The address of the sending party</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> 32 bytes are used to encode the address. In the case of an</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Ethereum address, the last 12 bytes can be padded with zeros</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> srcAddress</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"> The address of the recipient</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> 32 bytes are used to encode the address. In the case of an </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Ethereum address, the last 12 bytes can be padded with zeros</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> destAddress</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"> The identifier for a cross-chain interaction session</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> SHOULD be unique for every new cross-chain calls</span></span> <span class="giallo-l"><span class="z-support"> uint128</span><span> sessionId</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"> The message counter within an interaction session </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> SHOULD be unique within a session</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> OPTIONAL for most asynchronous bridges where every message has a </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> distinct sessionId, simply set to 0 if unused</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> E.g. In a cross-chain call: ChainA.func1 -m1-&gt; ChainB.func2 -m2-&gt; </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ChainC.func3 -m3-&gt; ChainB.func4, the subscript i in m_i is the nonce</span></span> <span class="giallo-l"><span class="z-support"> uint128</span><span> nonce</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"> Message type</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> A cross-chain message</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Message</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"> The message metadata </span></span> <span class="giallo-l"><span> Metadata metadata</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"> Message payload </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> It may be ABI-encoded function calls, info about bridged assets, </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> or arbitrary message data</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> payload</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Implementations SHOULD use a global rollup registry service that supports registration, deregistration, and efficient lookup of a rollup's chain ID. This work is outside the scope of this ERC, however. Our standard is compatible with any ERC defining chain-specific addresses to better display the sender and receiver of a <code>Message</code></p> <h3 id="mailbox-apis">Mailbox APIs</h3> <p>Each chain SHOULD have <strong>two canonical Mailbox contracts, one for synchronous and the other for asynchronous messaging</strong>, responsible for managing both incoming and outgoing messages. The following APIs are RECOMMENDED to provide the minimal required functionality. Implementations of these APIs MAY include additional functions to support customized or more complex workflows.</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"> Mailbox contract.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Mailbox for sending (resp. receiving) messages to (resp. from) </span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> other chains, standardized for messaging protocols that support </span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> synchronous or asynchronous, or both types of message passing.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> Mailbox</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @notice Inbox: a key-value map, mapping: metadata digest -&gt; payload</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev Implementators MAY instantiate with the following map</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> mapping(bytes32 =&gt; bytes) inbox;</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 chain ID for the host chain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> SHOULD be set at the deployment time as immutable except for when </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> using an upgradable Mailbox since immutable variables are discouraged.</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 change regardless of upgradable contracts or not.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> chain_id</span><span>(</span><span>)</span><span class="z-storage z-type"> virtual</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the digest of the inbox, used for mailbox consistency </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> checks</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> There SHOULD be an accumulator (e.g. chained-hash or MerkleTree) </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> logic that takes in every new inbox message and updates the digest</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> srcChainId</span><span class="z-comment"> Identifier of the source chain</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"> of all inbox messages coming from `srcChainId`</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> inboxDigest</span><span>(</span><span class="z-support">uint32</span><span class="z-variable"> srcChainId</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>)</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 digest of the outbox, used for mailbox consistency </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> checks</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> There SHOULD be an accumulator (e.g. chained-hash or MerkleTree) </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> logic that takes in every new outbox message and updates the digest</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> destChainId</span><span class="z-comment"> Identifier of the destination chain</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"> of all outbox messages directed at `destChainId`</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> outboxDigest</span><span>(</span><span class="z-support">uint32</span><span class="z-variable"> destChainId</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>)</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 &quot;key&quot; in inbox/outbox map for a message according </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> to its metadata</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The metadata includes all fields in the `Metadata` struct.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getMetadataDigest</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> Metadata</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> metadata</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> virtual</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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Send a message to another chain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> metadata</span><span class="z-comment"> Metadata of the message</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> payload</span><span class="z-comment"> Payload of the message</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> SHOULD sanity check `metadata.srcChainId == this.chain_id() &amp;&amp; </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> metadata.srcAddress == 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"> SHOULD update the outbox digest and/or the outbox</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> send</span><span>(</span><span class="z-storage z-type">Metadata</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> metadata</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> payload</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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Receive a message from another chain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> SHOULD revert if message cannot be retrieved</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> SHOULD sanity check `metadata.destChainId == this.chain_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"> metadata</span><span class="z-comment"> Metadata of the message</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"> payload</span><span class="z-comment"> of the retrieved message</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> recv</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> Metadata</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> metadata</span></span> <span class="giallo-l"><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 class="z-storage z-type"> memory</span><span class="z-variable"> payload</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"> Populate the inbox with incoming messages</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> messages</span><span class="z-comment"> Inbox messages to put in `this.inbox`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> aux</span><span class="z-comment"> OPTIONAL auxiliary information/witness to justify these </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> inbox messages</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `aux` may be empty or signature from a trusted relayer, etc.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> populateInbox</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> Message</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> messages</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"> aux</span></span> <span class="giallo-l"><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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Generates a fresh and random sessionId for new messages</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> In order to ensure the uniqueness of the value generated, this </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> function MIGHT require using a contract variable</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> With this unique session ID, for messages that do not require a </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> nonce, we can set nonce=0, and the overall metadata digest is still </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> collision-free with high probability</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"> unique sessionId</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> randSessionId</span><span>(</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">uint128</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>Mailbox</code> contract SHOULD keep track of an <em>inbox</em> of incoming messages. The concrete data structure used to store the <code>inbox</code> queue SHOULD be a hash-map-like <code>mapping</code> in Solidity to enable efficient lookup by the dApps with payload-independent query keys. Being able to read/receive messages based on their metadata only, rather than their actual payload, is critical in achieving synchronous messaging with a dynamic payload known only at runtime. It is OPTIONAL to track the full outbox messages in the contract storage — an outbox digest may be sufficient for some cases.</p> <p>While a single Mailbox contract could support both synchronous and asynchronous messaging protocols, this would require applications to specify the messaging mode for each interaction since each mode may require different settlement logic. Such a design would significantly complicate the Mailbox contract API, its implementation, and related infrastructure components like settlement logic. A more practical approach is to deploy separate, canonical Mailbox contracts for each mode. This allows applications to switch between synchronous and asynchronous messaging simply by pointing to the appropriate contract address.</p> <p>Messages received via <code>Mailbox.recv()</code> are <strong>authenticated</strong> because they must first be populated in the inbox, with their integrity verified before the receiving action finalizes. This verification is performed either through the <code>aux</code> field during the <code>populateInbox()</code> call or via an external settlement layer.</p> <h2 id="rationale">Rationale</h2> <h3 id="multiple-vm-support">Multiple VM Support</h3> <p>Notice that our standard requires <strong>no changes to a chain's VM</strong> (i.e. no new opcode or precompiles required), but only proposes some smart contract interfaces. Specifically, the sender/recipient account type — generic <code>bytes32</code> instead of EVM-specific <code>address</code> type -- allows this standard to support a much wider class of VMs (e.g. SolanaVM that uses <code>Ed25519</code> public key as their accounts).</p> <p>An optional <code>MultiplexABIEncoder</code> contract can abstract away the VM-specific encoding when preparing the message payload: a generic <code>encode(chainId)</code> function, as opposed to EVM’s <code>abi.encode</code>, that takes in the destination chain ID and decides the corresponding encoder logic so that the receiving party can decode natively. If the apps only care about interoperating with EVM chains, they can safely use <code>abi.encode()</code> as is and not go through any general encoder.</p> <p>On the receiving side, EVM chains would type cast <code>address(parsedAddress)</code> on the <code>bytes32 parsedAddress</code> from the received message.</p> <h3 id="arbitrary-message-payload">Arbitrary message payload</h3> <p>The <code>Message.payload</code> field is designed for maximum flexibility, capable of encoding arbitrary data, including application-specific structures like the <code>CrossChainOrder</code> from <a href="https://wg-eips.ritovision.com/7683/">ERC-7683</a> (See <em>Example Usage</em> section below for details of this integration). In contrast to some existing bridge designs that restrict the payload to function calls, the message payload in our design can also represent simpler data types, such as a boolean status flag for acknowledgments. This flexibility enables a wider range of use cases and simplifies integration across various applications.</p> <h3 id="use-metadata-digest-instead-of-sessionid-for-message-query-key">Use Metadata Digest Instead of <code>sessionId</code> for Message Query Key</h3> <p>For message lookups in the mailbox, the query key is derived from the hash of all message metadata rather than relying on a single <code>sessionId</code> field. This is because the <code>sessionId</code> derivation is customizable and may not adequately bind to key metadata like source and destination addresses. In contrast, the wrapping messaging protocol may enforce permissions for sending or receiving based on these metadata fields, so the query key must bind to the entire set of metadata.</p> <p>Observe that when applications allow users to define <code>sessionId</code>, these values may not be unique across messages. Depending on the implementation of the inbox, this could be a concern. For example, a mapping-based inbox needs an additional <em>nullifier set</em> to enforce the uniqueness of message metadata and avoid message overwrites in the case of a colliding map-key.</p> <h3 id="pre-filled-inbox">Pre-filled Inbox</h3> <p>In contrast to other asynchronous bridge designs, our standard explicitly separates inbox filling from reading, enabling a unified interface for message retrieval. This separation allows specialized parties like builders or coordinators to handle protocol-specific message authentication when writing to the inbox, while applications can fetch messages directly. Additionally, message retrieval requires only metadata rather than the complete message, which is valuable in synchronous settings where message payloads are determined at execution time.</p> <p>As mentioned above, pre-filling the inbox of the destination chain incurs additional gas costs which are manageable on L2s. We list some advantages of our approach:</p> <ul> <li>Eliminates Merkle inclusion proof verification when receiving every message. Some messaging protocols obviate Merkle proofs completely, even during <code>populateInbox()</code>, and delay the mailbox check to the settlement layer.</li> <li>Allows upgrade of the coordination protocol (e.g. the internal of <code>populateInbox()</code>and/or the settlement layer logic) without requiring changes to connected apps.</li> <li>Enables user-signed transactions on the destination chain instead of shared sequencer-signed transactions in synchronous messaging. This flexibility simplifies gas payment handling and ensures a consistent <code>msg.sender</code>. Detailed explanations are omitted for brevity (extended answers on the website).</li> </ul> <h3 id="related-proposals">Related Proposals</h3> <p>In comparison to Inter-blockchain Communication(IBC)-like standards, this ERC is designed to work in a <em>stateless</em> manner. Messages do not need to pass a proof from the source chain at the time they are consumed on the destination chain. This allows use cases such as synchronous composability and intra-block messaging since messages don’t need to include finalized state from the source chain. Additionally, this ERC does not require multiple steps to establish a link between two chains. Messages can be directly sent from one chain to another in a single step.</p> <p>ERC-7683 standardizes intent-based systems by defining structs for orders and interfaces for settlement smart contracts. This standard is application-specific and aimed at designers of cross-chain intent systems, while our proposal is more general and targets developers implementing arbitrary cross-chain applications. However, an intent system based on ERC-7683 <strong>can be built on top</strong> of our standard due to its modularity. An application implementing ERC-7683 could use the <code>Mailbox</code> API defined in this proposal to send <code>originData</code> from event messages between the source chain (where user funds are deposited) and the destination chain(s) (where intents are solved). We provide more details in the <em>Example Usage</em> section.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found. Since this is an opt-in protocol, L2s that do not opt-in to this will not be affected. Furthermore, this protocol can operate in existing cross-chain flows today, such as in intent-based bridges or native bridging of assets between L2s.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>We show a <em>possible</em> implementation of the mailbox contract for synchronous messaging protocol, and explain how it can be easily modified to support asynchronous protocols as well.</p> <p>The high-level flow is as follows:</p> <ul> <li>Sending a message simply updates the outbox digest.</li> <li>Prefill the inbox by inserting the messages sequentially in the same order as the outbox in the source chain. Each insertion updates the corresponding inbox digest. <ul> <li>The prefilling transaction is likely created by a <em>coordinator</em> in the coordination protocol, who monitors messages sent from all rollups and relay them to the intended destination chain. The rollup sequencer includes this transaction in the block, ensuring it precedes any mailbox "read" operations and enforces a single prefilling per block.</li> </ul> </li> <li>Applications can then read a message by querying the key-value map inbox with the (hashed) message metadata.</li> <li>External to these transactions, the settlement layer will receive new inbox digest and outbox digest (with storage proofs against a proven new rollup state) and checks <code>chain_i.inboxDigest[chain_j] == chain_j.outboxDigest[chain_i]</code> for all <code>i!=j</code> <ul> <li>Note: We ignore the slight complication of mailbox reset at the beginning of each block using nested mapping in our description above for brevity, but they are dealt with in our code snippet below.</li> </ul> </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"> Mailbox contract implementation for synchronous communication</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Mailbox</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ... Constructor + other simple functions like chain_id().</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"> nested map: blockNum -&gt; metadataDigest -&gt; payload</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Easy cleanup by `delete inbox[block.number -1]`</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-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes32</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bytes</span><span>)</span><span>)</span><span> inbox</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Mapping to detect key collisions: metadataDigest -&gt; writtenFlag</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"> bool</span><span>)</span><span> outboxNullifier</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> These hash values are computed incrementally.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Nested map: blockNum -&gt; srcChainId -&gt; H(...H(m_2 | H(m_1))..)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Easy cleanup by `delete inboxDigest[block.number -1]`</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-storage z-type"> mapping</span><span>(</span><span class="z-support">uint32</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bytes32</span><span>)</span><span>)</span><span> inboxDigest</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"> Nested map: blockNum -&gt; destChainId -&gt; H(...H(m_2 | H(m_1))..)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Easy cleanup by `delete outboxDigest[block.number -1]`</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-storage z-type"> mapping</span><span>(</span><span class="z-support">uint32</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bytes32</span><span>)</span><span>)</span><span> outboxDigest</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"> Given the metadata (Message struct without payload field) of a </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> message, derive the digest used as the dictionary key for inbox/outbox.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getMetadataDigest</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span class="z-variable"> srcChainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span class="z-variable"> destChainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> srcAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> destAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> uid</span></span> <span class="giallo-l"><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">bytes32</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span class="z-entity z-name"> keccak</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> srcChainId</span><span>,</span></span> <span class="giallo-l"><span> destChainId</span><span>,</span></span> <span class="giallo-l"><span> srcAddress</span><span>,</span></span> <span class="giallo-l"><span> destAddress</span><span>,</span></span> <span class="giallo-l"><span> uid</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Conceptual &quot;cleanup/reset&quot; of mailbox after each block since </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> sync msgs are received immediately.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _resetMailbox</span><span>(</span><span>)</span><span class="z-storage z-type"> private</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> inbox</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"> 1</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> inboxDigest</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"> 1</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> outboxDigest</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"> 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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Send a message to another chain</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> send</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span class="z-variable"> destChainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> destAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> uid</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"> payload</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> key </span><span class="z-keyword">=</span><span class="z-entity z-name"> getMetadataDigest</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">chain_id</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> destChainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span>srcAddress</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> uid</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"> Prevent overwriting the same key</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-keyword">!</span><span>outboxNullifier</span><span>[</span><span>key</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> outboxNullifier</span><span>[</span><span>key</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"> Update the outbox digest</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> digest&#39; = H(digest | metadata | payload)</span></span> <span class="giallo-l"><span> outboxDigest</span><span>[</span><span class="z-variable z-language">block</span><span>.</span><span>number</span><span>]</span><span>[</span><span class="z-variable z-language">this</span><span>.</span><span class="z-entity z-name">chain_id</span><span>(</span><span>)</span><span>]</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> outboxDigest</span><span>[</span><span class="z-variable z-language">block</span><span>.</span><span>number</span><span>]</span><span>[</span><span class="z-variable z-language">this</span><span>.</span><span class="z-entity z-name">chain_id</span><span>(</span><span>)</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> key</span><span>,</span></span> <span class="giallo-l"><span> m</span><span>.</span><span>payload</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This function can only be called once per block</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> populateInbox</span><span>(</span><span class="z-storage z-type">Message</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> messages</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> aux</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"> Before putting new inbox messages at the beginning of each block, </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> &quot;reset&quot; the inbox/outbox</span></span> <span class="giallo-l"><span class="z-entity z-name"> _resetMailbox</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></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> messages</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> Message </span><span class="z-storage z-type">memory</span><span> m </span><span class="z-keyword">=</span><span> messages</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Reject if the message was not sent to this chain</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>m</span><span>.</span><span>destChainId </span><span class="z-keyword">==</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">chain_id</span><span>(</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> key </span><span class="z-keyword">=</span><span class="z-entity z-name"> getMetadataDigest</span><span>(</span></span> <span class="giallo-l"><span> m</span><span>.</span><span>srcChainid</span><span>,</span></span> <span class="giallo-l"><span> m</span><span>.</span><span>srcAddr</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">chain_id</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> m</span><span>.</span><span>destAddr</span><span>,</span></span> <span class="giallo-l"><span> m</span><span>.</span><span>uid</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> inbox</span><span>[</span><span>key</span><span>]</span><span class="z-keyword"> =</span><span> m</span><span>.</span><span>payload</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Update the inbox digest</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> digest&#39; = H(digest | metadata | payload)</span></span> <span class="giallo-l"><span> inboxDigest</span><span>[</span><span class="z-variable z-language">block</span><span>.</span><span>number</span><span>]</span><span>[</span><span>m</span><span>.</span><span>srcChainId</span><span>]</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> inboxDigest</span><span>[</span><span class="z-variable z-language">block</span><span>.</span><span>number</span><span>]</span><span>[</span><span>m</span><span>.</span><span>srcChainId</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> key</span><span>,</span></span> <span class="giallo-l"><span> m</span><span>.</span><span>payload</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> <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"> Receive a message from another chain</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> recv</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span class="z-variable"> srcChainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> srcAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> destAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> uid</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-support">bytes32</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> key </span><span class="z-keyword">=</span><span class="z-entity z-name"> getMetadataDigest</span><span>(</span></span> <span class="giallo-l"><span> srcChainId</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">chain_id</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span>srcAddress</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span>destAddress</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> uid</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> inbox</span><span>[</span><span class="z-variable z-language">block</span><span>.</span><span>number</span><span>]</span><span>[</span><span>key</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>To extend the synchronous mailbox to support asynchronous protocols, we only need these modifications:</p> <ul> <li>Remove the first layer of mapping from <code>inbox</code>, <code>inboxDigest</code>, <code>outboxDigest</code>, since the “domain-separation from block number” requirement is gone. (e.g. changed to <code>mapping(bytes32 =&gt; bytes) inbox</code>)</li> <li>At the settlement layer, enforce that the destination chain’s inbox is a <strong>subset</strong> of the source chain’s outbox messages, rather than a full equality check. <ul> <li>Consequently, change the accumulator algorithm used to compute <code>inboxDigest,outboxDigest</code> to ones with efficient subset proof.</li> </ul> </li> <li>Remove the <code>_reset()</code> logic since all messages for async will be permanently stored.</li> </ul> <h3 id="note-on-gas-cost">Note on Gas Cost</h3> <p>The most costly operations are <code>sstore</code> during <code>Mailbox.populateInbox()</code>, which writes to the mapping <code>inbox</code> in contract storage, and <code>sload</code>, during <code>Mailbox.recv()</code> which reads from the <code>inbox</code> in storage. Luckily, Mailboxes costs on L2 are much cheaper. In cases of more gas-sensitive chains and applications, we suggest these potential optimizations:</p> <ul> <li><code>delete inbox[key]</code> during <code>.recv()</code> to get gas refunds for cleaning some storage <ul> <li>Synchronous messages are cleaned up at the end of the same block in which they are populated. L2 can optionally implement gas optimizations for such block ephemeral storage.</li> </ul> </li> <li>utilize the <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> access list to “pre-warm” predictable storage slots for lower execution cost</li> <li>batch-populate inbox messages and cluster them under fewer keys (bucketed mapping) e.g.: <code>mapping(bytes32 bucketKey =&gt; mapping(bytes32 =&gt; bytes)</code></li> </ul> <h3 id="example-usage-sync-and-async-cross-chain-transfers">Example Usage - Sync and Async Cross-chain Transfers</h3> <p>An ERC token contract wishing to allow cross-chain transfers would need to add the functions <code>xTransfer</code> and <code>xReceive</code> . The logic of a single chain transfer (e.g. <code>Token.send</code>) must be split into two functions <code>Token.xTransfer</code> and <code>Token.xReceive</code>. Each of these functions respectively mints and burns the same amount of assets and interact with the <code>Mailbox</code> contract.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> ERC20 token contract supporting cross-chain transfers</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> XChainToken</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC20Burnable</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"> points to the Mailbox contract used</span></span> <span class="giallo-l"><span> Mailbox </span><span class="z-storage z-type">public</span><span> mailbox</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"> bitmap for redeem-once control on inbox messages</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"> bool</span><span>)</span><span class="z-storage z-type"> private</span><span> isRedeemed</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"> maps chainId to the canonical XChainToken address</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint32</span><span class="z-keyword"> =&gt;</span><span class="z-support"> address</span><span>)</span><span class="z-storage z-type"> public</span><span> xChainTokenAddress</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"> use this function to transfer some amount of this token to </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> another address on another chain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> destAddress</span><span class="z-comment"> receiver 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 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"> destChainId</span><span class="z-comment"> identifier of the destination chain</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> xTransfer</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span class="z-variable"> destChainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> destAddress</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 class="z-comment"> //</span><span class="z-comment"> Burn the token of the caller</span></span> <span class="giallo-l"><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">burn</span><span>(</span><span>amount</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Write a message to the Mailbox to notify the other chain that the </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> token have been successfully burnt.</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> payload </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>amount</span><span>,</span><span> destAddress</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Specify the amount to be minted and the recipient</span></span> <span class="giallo-l"><span> mailbox</span><span>.</span><span class="z-entity z-name">send</span><span>(</span></span> <span class="giallo-l"><span> Mailbox</span><span>.</span><span class="z-entity z-name">Metadata</span><span>(</span></span> <span class="giallo-l"><span> mailbox</span><span>.</span><span class="z-entity z-name">chain_id</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> destChainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</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 class="z-support"> bytes32</span><span>(</span><span>xChainTokenAddress</span><span>[</span><span>destChainId</span><span>]</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> mailbox</span><span>.</span><span class="z-entity z-name">randSessionId</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span> payload</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> This function must be called on the destination chain to mint </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the tokens. This function can be called by any participant.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> srcChainId</span><span class="z-comment"> identifier of the source chain the funds are sent from</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sessionId</span><span class="z-comment"> unique identifier needed to fetch the message</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> xReceive</span><span>(</span><span class="z-support">uint32</span><span class="z-variable"> srcChainId</span><span>,</span><span class="z-support"> uint128</span><span class="z-variable"> sessionId</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"> Analoguous to crossTransfer except that this function can only be </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> called once with the same parameters in order to avoid double </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> minting. A mapping struct like isRedeemed can be used for this </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> purpose.</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> payload </span><span class="z-keyword">=</span><span> mailbox</span><span>.</span><span class="z-entity z-name">recv</span><span>(</span></span> <span class="giallo-l"><span> Mailbox</span><span>.</span><span class="z-entity z-name">Metadata</span><span>(</span></span> <span class="giallo-l"><span> srcChainId</span><span>,</span></span> <span class="giallo-l"><span> mailbox</span><span>.</span><span class="z-entity z-name">chain_id</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span>xChainTokenAddress</span><span>[</span><span>srcChainId</span><span>]</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</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> sessionId</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 0</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 class="z-support">uint256</span><span> amount</span><span>,</span><span class="z-support"> address</span><span> destAddress</span><span>)</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span></span> <span class="giallo-l"><span> payload</span><span>,</span></span> <span class="giallo-l"><span> (</span><span class="z-support">uint256</span><span>,</span><span class="z-support"> address</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>destAddress</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></code></pre><h3 id="example-usage-cross-chain-function-calls">Example Usage - Cross-chain function calls</h3> <p>In this example we show how to implement a cross-chain function call using the <code>Mailbox</code> abstraction: The logic of cross-chain execution is handled by a contract <code>RemoteExecuter</code> deployed on both source and destination chains.</p> <p>On the source chain <code>A</code>, a user wanting to call a function <code>fun</code> of a contract <code>Foo</code> on the destination chain <code>B</code> can invoke <code>RemoteExecuter.remoteCall</code> with the address of the contract <code>Foo</code> and other parameters including the function name and its arguments. This generates a message that is sent to chain <code>B</code>.</p> <p>On the destination chain <code>B</code>, a call to <code>RemoteExecuter.execute</code> fetches the message sent from the source chain <code>A</code>, parses it and executes the corresponding function of the local contract <code>Foo</code>. The <code>RemoteExecuter</code> contract also takes care of preventing messages replays.</p> <p>Note that in this example gas on the destination chain is paid by the caller of <code>RemoteExecuter.execute</code> . In practice this participant can be the same user who called <code>RemoteExecuter.remoteCall</code> on the source chain. More advanced gas management policies can be implemented where another party calls <code>RemoteExecuter.execute</code> and pays on behalf of the user.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Contract deployed on both chains A and B</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> This contract takes care of receiving remote calls from the source chain </span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> and of the execution on the destination chain</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> RemoteExecuter</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"> points to the chain Mailbox</span></span> <span class="giallo-l"><span> Mailbox </span><span class="z-storage z-type">public</span><span> mailbox</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"> maps chainId to the canonical RemoteExecuter address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> We assume the contract RemoteExecuter is deployed on both (or </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> more) chains, and this map allows to know the address of the </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> contract on the other chain(s).</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint32</span><span class="z-keyword"> =&gt;</span><span class="z-support"> address</span><span>)</span><span class="z-storage z-type"> public</span><span> remoteExecuterAddress</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Track which messages have already been processed</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"> bool</span><span>)</span><span class="z-storage z-type"> private</span><span> executedMessages</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"> Prepare the execution function on a another chain</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 sends a message to the destination chain with the </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> parameters of the call</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> remoteCall</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span class="z-variable"> destChainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> remoteContractAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> callParams</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> Mailbox</span><span>.</span><span>Metadata </span><span class="z-storage z-type">memory</span><span> metadata </span><span class="z-keyword">=</span><span> Mailbox</span><span>.</span><span class="z-entity z-name">Metadata</span><span>(</span></span> <span class="giallo-l"><span> mailbox</span><span>.</span><span class="z-entity z-name">chain_id</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> destChainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</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 class="z-support"> bytes32</span><span>(</span><span>remoteExecuterAddress</span><span>[</span><span>destChainId</span><span>]</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> mailbox</span><span>.</span><span class="z-entity z-name">randSessionId</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> mailbox</span><span>.</span><span class="z-entity z-name">send</span><span>(</span><span>metadata</span><span>,</span><span> callParams</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"> @notice</span><span class="z-comment"> Call a contract function locally based on some message that was </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> sent from another chain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> srcChainId</span><span class="z-comment"> Identifier of the source chain where the call was </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> initiated</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sessionId</span><span class="z-comment"> Session identifier</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-support">uint32</span><span class="z-variable"> srcChainId</span><span>,</span><span class="z-support"> uint128</span><span class="z-variable"> sessionId</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"> Check that the message has not be executed yet</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> memory</span><span> uid </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>sessionId</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 class="z-keyword">!</span><span class="z-variable z-language">this</span><span>.</span><span>executedMessages</span><span>[</span><span>uid</span><span>]</span><span>,</span><span class="z-string"> &quot;already executed&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"> Read the message</span></span> <span class="giallo-l"><span> Mailbox</span><span>.</span><span>Metadata </span><span class="z-storage z-type">memory</span><span> metadata </span><span class="z-keyword">=</span><span> Mailbox</span><span>.</span><span class="z-entity z-name">Metadata</span><span>(</span></span> <span class="giallo-l"><span> srcChainId</span><span>,</span></span> <span class="giallo-l"><span> mailbox</span><span>.</span><span class="z-entity z-name">chain_id</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span>remoteExecuterAddress</span><span>[</span><span>srcChainId</span><span>]</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</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> sessionId</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> payload </span><span class="z-keyword">=</span><span> Mailbox</span><span>.</span><span class="z-entity z-name">recv</span><span>(</span><span>metadata</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Call the function</span></span> <span class="giallo-l"><span> (</span><span class="z-support">address</span><span> contractAddress</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> callParams</span><span>)</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span></span> <span class="giallo-l"><span> payload</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> contractAddress</span><span>.</span><span>call</span><span>{</span><span>gas</span><span class="z-keyword">:</span><span class="z-constant"> 100000</span><span>}</span><span>(</span><span>callParams</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 message as executed</span></span> <span class="giallo-l"><span class="z-variable z-language"> this</span><span>.</span><span>executedMessages</span><span>[</span><span>uid</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> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Contract deployed on chain A</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Caller</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"> Function on the source chain A that calls a function of a </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> contract deployed on the destination chain B</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The identifier of the destination chain CHAIN_B_ID and the remote </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> contract address FOO_CONTRACT_ADDRESS are hardcoded</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> val</span><span class="z-comment"> parameter to be passed to the function Foo.fun(...)</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> callChainB</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> val</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> callParams </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeCall</span><span>(</span><span>Foo</span><span>.</span><span class="z-entity z-name">fun</span><span>(</span><span>val</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> RemoteExecuter</span><span>.</span><span class="z-entity z-name">remoteCall</span><span>(</span><span>CHAIN_B_ID</span><span>,</span><span> FOO_CONTRACT_ADDRESS</span><span>,</span><span> callParams</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 class="z-comment"> Contract deployed on chain B</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> We assume this contract is deployed at the address FOO_CONTRACT_ADDRESS</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> This contract has a function that is called from chain A</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Foo</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> fun</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parameter</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>parameter </span><span class="z-keyword">==</span><span class="z-constant"> 42</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>Security concerns for the messaging format and mailbox APIs themselves are minimal, as the protocol specification focuses on providing a rich and expressive interface for various message passing protocols. Security responsibilities lie with the underlying messaging protocol design and the application utilizing it. This specification ensures the interfaces are flexible enough to support the majority of cross-chain messaging protocols, while security within those protocols is outside the scope of 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> 2024-12-07T00:00:00+00:00 2026-04-25T12:06:20+00:00 Cheng Qianhttps://github.com/jamesavechivesjames.walstonn@gmail.com https://wg-eips.ritovision.com/7837/

A fungible token that mints new tokens on transfer, charges a per-token native fee, and enforces a capped supply.

<h2 id="abstract">Abstract</h2> <p>This ERC proposes a standard for a new type of fungible token, called <strong>Diffusive Tokens (DIFF)</strong>. Unlike traditional <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens, transferring DIFF tokens does not decrease the sender’s balance. Instead, it <em>mints</em> new tokens directly to the recipient, increasing the total supply on every transfer action. A fixed native currency fee is charged per token transferred, and this fee is paid by the sender to the contract owner. The supply growth is limited by a maximum supply set by the owner. Token holders can also burn their tokens to reduce the total supply. These features enable a controlled, incentivized token distribution model that merges fungibility with a built-in economic mechanism.</p> <h2 id="motivation">Motivation</h2> <p>Traditional <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens maintain a constant total supply and simply redistribute balances on transfers. While this model is widespread, certain use cases benefit from a token design that continuously expands supply during transfers, simulating a controlled "diffusion" of value. The Diffusive Token model may be suitable for representing claims on real-world goods (e.g., a product batch like iPhone 15 units), digital goods, or controlled asset distributions where initial token distribution and ongoing availability need to be managed differently.</p> <p>This model also includes a native currency fee per token transferred, incentivizing careful, value-driven transfers and providing a revenue stream for the token’s issuer. The maximum supply cap prevents unbounded inflation, ensuring long-term scarcity. The ability for owners to burn tokens to redeem underlying goods or services directly maps on-chain assets to real-world redemptions.</p> <p><strong>Use Cases</strong>:</p> <ul> <li> <p><strong>Real-World Asset Backing</strong>: A manufacturer can issue DIFF tokens representing a batch of products (e.g., iPhones). Each token can be redeemed (burned) for one physical item.</p> </li> <li> <p><strong>Fee-Driven Incentives</strong>: The transfer fee ensures that infinite minting by constant transferring is economically disincentivized. The fee also supports the token issuer or provides a funding mechanism.</p> </li> </ul> <h2 id="specification">Specification</h2> <h3 id="terminology">Terminology</h3> <ul> <li><strong>Diffusive Token</strong>: A fungible token unit that is minted on transfers.</li> <li><strong>Max Supply</strong>: The maximum total supply the token can reach.</li> <li><strong>Transfer Fee</strong>: A fee in native blockchain currency (e.g., ETH) that must be paid by the sender for each token transferred. The total fee = <code>transferFee * amount</code>.</li> <li><strong>Burn</strong>: The action of destroying tokens, reducing both the holder’s balance and the total supply.</li> </ul> <h3 id="data-structures">Data Structures</h3> <ul> <li> <p><strong>Total Supply and Max Supply</strong>:</p> <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"> public</span><span> totalSupply</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> public</span><span> maxSupply</span><span>;</span></span></code></pre></li> <li> <p><strong>Transfer Fee</strong>:</p> <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"> public</span><span> transferFee</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> fee per token transferred in wei</span></span> <span class="giallo-l"><span class="z-support">address</span><span class="z-storage z-type"> public</span><span> owner</span><span>;</span></span></code></pre> <p>The <code>owner</code> sets and updates <code>transferFee</code> and <code>maxSupply</code>.</p> </li> </ul> <h3 id="token-semantics">Token Semantics</h3> <ol> <li> <p><strong>Minting on Transfer</strong> When a transfer occurs from <code>A</code> to <code>B</code>:</p> <ul> <li><code>A</code> does not lose any tokens.</li> <li><code>B</code> receives newly minted tokens (increasing their balance and totalSupply).</li> <li>The <code>totalSupply</code> increases by the transferred amount, but must not exceed <code>maxSupply</code>.</li> </ul> </li> <li> <p><strong>Fixed Transfer Fee in Native Currency</strong> Each transfer requires the sender to pay <code>transferFee * amount</code> in the native currency. If <code>msg.value</code> is insufficient, the transaction reverts.</p> </li> <li> <p><strong>Maximum Supply</strong> If a transfer would cause <code>totalSupply + amount &gt; maxSupply</code>, it must revert.</p> </li> <li> <p><strong>Burning Tokens</strong> Token holders can burn tokens to:</p> <ul> <li>Reduce their balance by the burned amount.</li> <li>Decrease <code>totalSupply</code> by the burned amount. This can map to redeeming underlying goods or simply deflating the token.</li> </ul> </li> </ol> <h3 id="interface">Interface</h3> <p>The DIFF standard aligns partially with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, but redefines certain behaviors:</p> <p><strong>Core Functions:</strong></p> <ul> <li> <p><code>function balanceOf(address account) external view returns (uint256);</code></p> </li> <li> <p><code>function transfer(address to, uint256 amount) external payable returns (bool);</code></p> <ul> <li><strong>Modified behavior</strong>: Mints <code>amount</code> tokens to <code>to</code>, requires <code>msg.value &gt;= transferFee * amount</code>.</li> </ul> </li> <li> <p><code>function burn(uint256 amount) external;</code></p> <ul> <li>Reduces sender’s balance and <code>totalSupply</code>.</li> </ul> </li> </ul> <p><strong>Administration Functions (Owner Only):</strong></p> <ul> <li> <p><code>function setMaxSupply(uint256 newMax) external;</code></p> </li> <li> <p><code>function setTransferFee(uint256 newFee) external;</code></p> </li> <li> <p><code>function withdrawFees(address payable recipient) external;</code></p> <ul> <li>Withdraws accumulated native currency fees.</li> </ul> </li> </ul> <p><strong>Optional Approval Interface (For Compatibility):</strong></p> <ul> <li> <p><code>function approve(address spender, uint256 amount) external returns (bool);</code></p> </li> <li> <p><code>function transferFrom(address from, address to, uint256 amount) external payable returns (bool);</code></p> <ul> <li><strong>Modified behavior</strong>: Similar to <code>transfer</code>, but uses allowance and still mints tokens to <code>to</code> rather than redistributing from <code>from</code>.</li> </ul> </li> </ul> <h3 id="events">Events</h3> <ul> <li> <p><code>event Transfer(address indexed from, address indexed to, uint256 amount);</code></p> <p>Emitted when tokens are minted to <code>to</code> via a transfer call.</p> </li> <li> <p><code>event Burn(address indexed burner, uint256 amount);</code></p> <p>Emitted when <code>amount</code> of tokens are burned from an address.</p> </li> <li> <p><code>event FeeUpdated(uint256 newFee);</code></p> <p>Emitted when the owner updates the <code>transferFee</code>.</p> </li> <li> <p><code>event MaxSupplyUpdated(uint256 newMaxSupply);</code></p> <p>Emitted when the owner updates <code>maxSupply</code>.</p> </li> </ul> <h3 id="compliance-with-erc-20">Compliance with ERC-20</h3> <p>The DIFF standard implements the ERC-20 interface but significantly alters the <code>transfer</code> and <code>transferFrom</code> semantics:</p> <ul> <li><strong>Fungibility</strong>: Each token unit is identical and divisible as in ERC-20.</li> <li><strong>Balances and Transfers</strong>: The <code>balanceOf</code> function works as normal. However, <code>transfer</code> and <code>transferFrom</code> no longer redistribute tokens. Instead, they mint new tokens (up to <code>maxSupply</code>).</li> <li><strong>Approvals</strong>: The <code>approve</code> and <code>transferFrom</code> functions remain, but their logic is unconventional since the sender’s balance is never reduced by transfers.</li> </ul> <p>While the DIFF standard can be seen as ERC-20 compatible at the interface level, the underlying economics differ substantially.</p> <h2 id="rationale">Rationale</h2> <p><strong>Design Decisions</strong>:</p> <ul> <li> <p><strong>Unlimited Minting vs. Max Supply</strong>: Allowing minting on every transfer provides a “diffusive” spread of tokens. The <code>maxSupply</code> prevents uncontrolled inflation.</p> </li> <li> <p><strong>Burn Mechanism</strong>: Enables redemption or deflation as tokens are taken out of circulation.</p> </li> <li> <p><strong>Owner Controls</strong>: The owner (e.g., issuer) can adjust fees and max supply, maintaining flexibility as market conditions change.</p> </li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The DIFF standard is interface-compatible with ERC-20 but not behaviorally identical. Any system integrating DIFF tokens should understand the difference in minting on transfer.</p> <ul> <li><strong>Wallets and Exchanges</strong>: Most ERC-20 compatible tools can display balances and initiate transfers. However, the unusual economics (mint on transfer) may confuse users and pricing mechanisms.</li> <li><strong>Allowances and TransferFrom</strong>: Still implemented for interoperability, but the expected logic (debiting <code>from</code> balance) does not apply.</li> </ul> <h2 id="test-cases">Test Cases</h2> <ol> <li> <p><strong>Initial Conditions</strong>:</p> <ul> <li>Deploy contract with <code>maxSupply = 1,000,000 DIFF</code>, <code>transferFee = 0.001 ETH</code>.</li> <li><code>totalSupply = 0</code>.</li> <li>Owner sets parameters and verifies via <code>maxSupply()</code> and <code>transferFee()</code> getters.</li> </ul> </li> <li> <p><strong>Minting on Transfer</strong>:</p> <ul> <li>User A calls <code>transfer(B, 100)</code> with <code>msg.value = 0.1 ETH</code> (assuming <code>transferFee = 0.001 ETH</code>).</li> <li>Check <code>balances[B] == 100</code>, <code>totalSupply == 100</code>.</li> <li>Check that the contract now holds 0.1 ETH from the fee.</li> </ul> </li> <li> <p><strong>Exceeding Max Supply</strong>:</p> <ul> <li>If <code>totalSupply = 999,950</code> and someone tries to transfer 100 tokens, causing <code>totalSupply</code> to exceed <code>1,000,000</code>, the transaction reverts.</li> </ul> </li> <li> <p><strong>Burning Tokens</strong>:</p> <ul> <li>User B calls <code>burn(50)</code>.</li> <li>Check <code>balances[B] == 50</code>, <code>totalSupply == 50</code> less than before.</li> <li><code>Burn</code> event emitted.</li> </ul> </li> <li> <p><strong>Updating Fee and Withdrawing Funds</strong>:</p> <ul> <li>Owner calls <code>setTransferFee(0.002 ETH)</code>.</li> <li><code>FeeUpdated</code> event emitted.</li> <li>Owner calls <code>withdrawFees(ownerAddress)</code>.</li> <li>Check that <code>ownerAddress</code> receives accumulated fees.</li> </ul> </li> </ol> <h2 id="reference-implementation">Reference Implementation</h2> <p>A reference implementation is provided under the asset folder in the EIPs repository. The implementation includes:</p> <ul> <li>A basic contract implementing the DIFF standard.</li> </ul> <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"> DiffusiveToken</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"> //</span><span class="z-comment"> State Variables</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-support"> string</span><span class="z-storage z-type"> public</span><span> name</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> public</span><span> symbol</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-storage z-type"> public</span><span> decimals</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> totalSupply</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> public</span><span> maxSupply</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> public</span><span> transferFee</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Fee per token transferred in wei</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> owner</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"> //</span><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-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"> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Burn</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> burner</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 class="z-storage z-type"> event</span><span class="z-entity z-name"> FeeUpdated</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> newFee</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MaxSupplyUpdated</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> newMaxSupply</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 class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> -----------------------------------------</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Modifiers</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"> 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;DiffusiveToken: caller is not the owner&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-comment"> //</span><span class="z-comment"> -----------------------------------------</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Constructor</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"> Constructor sets the initial parameters for the Diffusive 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"> _name</span><span class="z-comment"> Token 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"> _symbol</span><span class="z-comment"> Token symbol</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _decimals</span><span class="z-comment"> Decimal places</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _maxSupply</span><span class="z-comment"> The max supply of tokens that can ever 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"> _transferFee</span><span class="z-comment"> Initial fee per token transferred in wei</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 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"> uint8</span><span class="z-variable z-parameter z-function"> _decimals</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _maxSupply</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _transferFee</span></span> <span class="giallo-l"><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> decimals </span><span class="z-keyword">=</span><span> _decimals</span><span>;</span></span> <span class="giallo-l"><span> maxSupply </span><span class="z-keyword">=</span><span> _maxSupply</span><span>;</span></span> <span class="giallo-l"><span> transferFee </span><span class="z-keyword">=</span><span> _transferFee</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> totalSupply </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Initially, no tokens are minted</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"> //</span><span class="z-comment"> External and Public Functions</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"> Returns the token balance of the given 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 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"> balanceOf</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-keyword"> return</span><span> balances</span><span>[</span><span>account</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"> Transfers `amount` tokens to address `to`, minting new tokens in the process.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Requires payment of native currency: transferFee * 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"> to</span><span class="z-comment"> Recipient 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"> Number of tokens to transfer</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 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"> 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"> amount</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 class="z-keyword"> require</span><span>(</span><span>to </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;DiffusiveToken: transfer to zero address&quot;</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 class="z-string"> &quot;DiffusiveToken: amount must be greater than zero&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> requiredFee </span><span class="z-keyword">=</span><span> transferFee </span><span class="z-keyword">*</span><span> amount</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">&gt;</span><span class="z-keyword">=</span><span> requiredFee</span><span>,</span><span class="z-string"> &quot;DiffusiveToken: insufficient fee&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"> Check max supply limit</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>totalSupply </span><span class="z-keyword">+</span><span> amount </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> maxSupply</span><span>,</span><span class="z-string"> &quot;DiffusiveToken: would exceed max supply&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"> Mint new tokens to `to`</span></span> <span class="giallo-l"><span> balances</span><span>[</span><span>to</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span> totalSupply </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span> amount</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"> Transfer</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> to</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> <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 `amount` tokens from the caller&#39;s balance, decreasing total supply.</span></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"> The number of tokens to burn</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 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 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 class="z-string"> &quot;DiffusiveToken: burn amount must be greater than zero&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>balances</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> amount</span><span>,</span><span class="z-string"> &quot;DiffusiveToken: insufficient balance&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></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> amount</span><span>;</span></span> <span class="giallo-l"><span> totalSupply </span><span class="z-keyword">-</span><span class="z-keyword">=</span><span> amount</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"> Burn</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">@notice</span><span class="z-comment"> Approves `spender` to transfer up to `amount` tokens on behalf of `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"> spender</span><span class="z-comment"> The address authorized to spend</span></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"> The max amount they can spend</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"> spender</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-keyword"> require</span><span>(</span><span>spender </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;DiffusiveToken: approve to zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> allowances</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-keyword"> emit</span><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> <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 the current allowance of `spender` for `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"> The owner of the 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"> _spender</span><span class="z-comment"> The address allowed to spend 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"> 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"> 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> allowances</span><span>[</span><span>_owner</span><span>]</span><span>[</span><span>_spender</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"> Transfers `amount` tokens from `from` to `to` using the allowance mechanism.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The `from` account does not lose tokens; this still mints 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"> The address from which the allowance has been given</span></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 recipient 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"> The number of tokens to transfer (mint)</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 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-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 class="z-keyword"> require</span><span>(</span><span>to </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;DiffusiveToken: transfer to zero address&quot;</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 class="z-string"> &quot;DiffusiveToken: amount must be greater than zero&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> allowed </span><span class="z-keyword">=</span><span> allowances</span><span>[</span><span>from</span><span>]</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"> require</span><span>(</span><span>allowed </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> amount</span><span>,</span><span class="z-string"> &quot;DiffusiveToken: allowance exceeded&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"> Deduct from allowance</span></span> <span class="giallo-l"><span> allowances</span><span>[</span><span>from</span><span>]</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> =</span><span> allowed </span><span class="z-keyword">-</span><span> amount</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> requiredFee </span><span class="z-keyword">=</span><span> transferFee </span><span class="z-keyword">*</span><span> amount</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">&gt;</span><span class="z-keyword">=</span><span> requiredFee</span><span>,</span><span class="z-string"> &quot;DiffusiveToken: insufficient fee&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"> Check max supply</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>totalSupply </span><span class="z-keyword">+</span><span> amount </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> maxSupply</span><span>,</span><span class="z-string"> &quot;DiffusiveToken: would exceed max supply&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"> Mint tokens to `to`</span></span> <span class="giallo-l"><span> balances</span><span>[</span><span>to</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span> totalSupply </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span> amount</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"> Transfer</span><span>(</span><span>from</span><span>,</span><span> to</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> <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"> //</span><span class="z-comment"> Owner Functions</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"> Updates the maximum supply of tokens. Must be &gt;= current totalSupply.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> newMaxSupply</span><span class="z-comment"> The new maximum 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"> setMaxSupply</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> newMaxSupply</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-keyword"> require</span><span>(</span><span>newMaxSupply </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> totalSupply</span><span>,</span><span class="z-string"> &quot;DiffusiveToken: new max &lt; current supply&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> maxSupply </span><span class="z-keyword">=</span><span> newMaxSupply</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> MaxSupplyUpdated</span><span>(</span><span>newMaxSupply</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"> Updates the per-token transfer fee.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> newFee</span><span class="z-comment"> The new fee in wei per token transferred</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"> setTransferFee</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> newFee</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> transferFee </span><span class="z-keyword">=</span><span> newFee</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> FeeUpdated</span><span>(</span><span>newFee</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"> Allows the owner to withdraw accumulated native currency fees.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> recipient</span><span class="z-comment"> The address that will receive the withdrawn fees</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"> withdrawFees</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 class="z-entity z-name"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>recipient </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;DiffusiveToken: withdraw to zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> balance </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>balance</span><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> recipient</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span> balance</span><span>}</span><span>(</span><span class="z-string">&quot;&quot;</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"> &quot;DiffusiveToken: withdrawal failed&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-comment"> //</span><span class="z-comment"> -----------------------------------------</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Fallback and Receive</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"> Allows the contract to receive Ether.</span></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></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li>Interfaces and helper contracts for testing and demonstration purposes.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <ul> <li><strong>Reentrancy</strong>: Handle fee transfers using the Checks-Effects-Interactions pattern. Consider <code>ReentrancyGuard</code> from OpenZeppelin to prevent reentrant calls.</li> <li><strong>Overflow/Underflow</strong>: Solidity 0.8.x guards against this by default.</li> <li><strong>Contract Balance Management</strong>: Ensure enough native currency is sent to cover fees. Revert on insufficient fees.</li> <li><strong>Access Control</strong>: Only the owner can update <code>transferFee</code> and <code>maxSupply</code>. Use proper <code>onlyOwner</code> modifiers.</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> 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-12-06T00:00:00+00:00 2026-02-11T14:49:27+00:00 Kaan Uzdoganhttps://github.com/kuzdogan Marco Castignolihttps://github.com/marcocastignoli Manuel Wedlerhttps://github.com/manuelwedler https://wg-eips.ritovision.com/7834/

Introduce a new separate metadata section to the EOF

<h2 id="abstract">Abstract</h2> <p>Introduce a new separate metadata section to the Ethereum Object Format (EOF) that is unreachable by the code, and any changes to which does not affect the code.</p> <h2 id="motivation">Motivation</h2> <p>It is desirable to include metadata in contract's bytecode for various reasons. For instance, both the Solidity and Vyper compilers by default include the language and compiler version used to compile. Vyper (with 0.4.1) appends an integrity hash to the initcode in CBOR encoding. Solidity additionally includes the IPFS or the Swarm hash of the Solidity contract metadata.json file, and the experimental Solidity flag. The current (pre-EOF) practice is to append this CBOR encoded metadata section in the contract's runtime bytecode, followed by the 2 bytes length of the CBOR encoded bytes.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> Solidity ┌──────────────────────────────────────────0x0033 bytes──────────────────────────────────────────────┐</span></span> <span class="giallo-l"><span>...7265206c656e677468a2646970667358221220dceca8706b29e917dacf25fceef95acac8d90d765ac926663ce4096195952b6164736f6c634300060b0033</span></span></code></pre> <p>This poses a problem for source code verification where the onchain bytecode is compared to the compiled bytecode of the given source code. During a contract verification, metadata sections, in particular the IPFS hash, need to be ignored and only the executional bytecode should be compared. Since pre-EOF bytecode is not structured, it is not possible to distinguish the metadata section from the executional bytecode easily. This gets even trickier in the case of factory contracts with multiple nested bytecodes, each having their own metadata sections. Verifiers need to implement their own heuristics and workarounds to find the metadata sections and ignore it.</p> <p>The EOF brings structure to the bytecode by separating the code from the data, and placing the code of each contract in their respective containers. In its current form, this makes it possible to find the data easier than the pre-EOF bytecode. However, the current spec also does not describe a metadata section. Compilers currently need to place the contract metadata inside the data section which poses several problems:</p> <ol> <li>It is not straightforward to distinguish the metadata part in the <code>data_section</code>, which poses the same problem as the pre-EOF bytecode.</li> <li>Any change to the metadata's size within the data section will change the executional bytecode, e.g. through shifting <code>DATALOADN</code> offsets. With that, two identical contracts with different metadata sizes will not match during source code, since the code will be different.</li> <li>The metadata can theoretically be reached by the code, e.g. via manipulating the <code>DATALOADN</code> instructions.</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>Extending the format introduced in <a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a>, this EIP proposes to add a new OPTIONAL section in the body called <code>metadata_section</code> before the <code>data_section</code>, and to add two new OPTIONAL fields <code>kind_metadata</code> (value: <code>0x05</code>) and <code>metadata_size</code> to the header before the <code>kind_data</code> and <code>data_size</code> fields.</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_metadata, metadata_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*, [metadata_section], data_section</span></span> <span class="giallo-l"><span>types_section := (inputs, outputs, max_stack_increase)+</span></span></code></pre><h3 id="header">Header</h3> <table><thead><tr><th>name</th><th>length</th><th>value</th><th>description</th></tr></thead><tbody> <tr><td>...</td><td>...</td><td>...</td><td>...</td></tr> <tr><td>kind_metadata</td><td>1 byte</td><td>0x05</td><td>kind marker for metadata size section</td></tr> <tr><td>metadata_size</td><td>2 bytes</td><td>0x0001-0xFFFF</td><td>16-bit unsigned big-endian integer denoting the length of the metadata 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> <h3 id="body">Body</h3> <table><thead><tr><th>name</th><th>length</th><th>value</th><th>description</th></tr></thead><tbody> <tr><td>...</td><td>...</td><td>...</td><td>...</td></tr> <tr><td>metadata_section</td><td>variable</td><td>n/a</td><td>arbitrary sequence of bytes</td></tr> <tr><td>data_section</td><td>variable</td><td>n/a</td><td>arbitrary sequence of bytes</td></tr> </tbody></table> <p>The structure and the encoding of the <code>metadata_section</code> is not defined by this EIP. It is left to the compilers, tooling, or the contract developers to define the encoding and the content. The current practice by the Solidity and Vyper compilers is to use CBOR encoding.</p> <h2 id="rationale">Rationale</h2> <p>The <code>metadata_section</code> in the <code>body</code>, as well as the <code>kind_metadata</code> and <code>metadata_size</code> fields in the <code>header</code>, are OPTIONAL. This way, the compilers can avoid additional bytes in the container if they don't want to write any metadata. The <code>data_section</code> can change in its size and content during deployment, therefore it needs to be REQUIRED, even if the data is empty. The <code>metadata_section</code> is not expected to change during the deployment.</p> <p>The reason for placing the <code>metadata_section</code> before the <code>data_section</code>, and assigning <code>kind_metadata</code> the value <code>0x05</code> (and not <code>0x04</code>) is to make it easier for the existing EOF tooling adapt the changes. Additionally, if the <code>metadata_section</code> was placed after the <code>data_section</code>, changes to the <code>data_section</code> in deploy time would cause the <code>metadata_section</code> to shift. By placing the <code>metadata_section</code> before, this could be mitigated.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues are expected since <a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a> is not implemented yet.</p> <h2 id="security-considerations">Security Considerations</h2> <p>No security considerations as this section is meant not to be executed.</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:48:25+00:00 Lukas Rosariohttps://github.com/lukasrosario Conner Swenberghttps://github.com/ilikesymmetry Adam Hodgeshttps://github.com/ajhodges Paaras Bhandarihttps://github.com/paarasbhandari Jake Moxeyhttps://github.com/jxom https://wg-eips.ritovision.com/7836/

Adds JSON-RPC methods for requesting unsigned EIP-5792 calls based on the wallet's implementation, and then sending those calls once signed.

<h2 id="abstract">Abstract</h2> <p>This proposal defines complementary JSON-RPC methods to <a href="https://wg-eips.ritovision.com/5792/">EIP-5792's <code>wallet_sendCalls</code></a> to enable an Application to sign over a call bundle (instead of the Wallet). Methods defined in this proposal are purposed for the Application to sign over <code>calls</code> and submit them to the Wallet with an accompanying signature. This is in contrast to <code>wallet_sendCalls</code>, where a Wallet itself signs over the call bundle.</p> <h2 id="motivation">Motivation</h2> <p>Applications are increasingly seeking to use session keys and scoped permissions to make transactions on a user's behalf, without the user having to approve and sign each transaction in their wallet's interface. One example is an application that automates a user's decentralised exchange trading. As Smart Contract Accounts (SCAs) contain arbitrary execution interfaces that lead to varying calldata formats, it is not possible for an Application to know how to sign over an action for any arbitrary Account implementation, without maintaining a mapping of Account implementations to their signing logic. Apps need a simple way to request the payload that their session keys should sign, given a call or set of calls they wish to make, and a way to execute the calls once signed.</p> <h2 id="specification">Specification</h2> <p>In this specification, we define two new JSON-RPC methods: <code>wallet_prepareCalls</code> and <code>wallet_sendPreparedCalls</code>.</p> <h3 id="wallet-preparecalls"><code>wallet_prepareCalls</code></h3> <p>Instructs a Wallet to prepare a call bundle according to the Account's implementation. It returns a <code>digest</code> of the call bundle to sign over, as well as the parameters required to fulfil a <code>wallet_sendPreparedCalls</code> request (ie. <code>capabilities</code>, <code>chainId</code>, <code>context</code>, and <code>version</code>).</p> <blockquote> <p>After calling <code>wallet_prepareCalls</code>, consumers are expected to sign over the <code>digest</code> and submit the <code>signature</code> and prepared calls to the Wallet via <code>wallet_sendPreparedCalls</code>.</p> </blockquote> <h4 id="request">Request</h4> <blockquote> <p>The request is identical to that of <a href="https://wg-eips.ritovision.com/5792/"><code>wallet_sendCalls</code></a>.</p> </blockquote> <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"> Request</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> method</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">wallet_prepareCalls</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> params</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"> Calls to be executed.</span></span> <span class="giallo-l"><span class="z-variable"> calls</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> to</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> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">?</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> <span class="giallo-l"><span class="z-variable"> value</span><span class="z-keyword">?</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> <span class="giallo-l"><span class="z-variable"> capabilities</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span>;</span></span> <span class="giallo-l"><span> }</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"> Capabilities.</span></span> <span class="giallo-l"><span class="z-variable"> capabilities</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Chain ID of the chain the calls are being submitted to.</span></span> <span class="giallo-l"><span class="z-variable"> chainId</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Sender address.</span></span> <span class="giallo-l"><span class="z-variable"> from</span><span class="z-keyword">?</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Key (hint) that will be used to sign the call bundle.</span></span> <span class="giallo-l"><span class="z-variable"> key</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Whether the digest will be prehashed by the key (default behavior of WebCrypto APIs).</span></span> <span class="giallo-l"><span class="z-variable"> prehash</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 class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Public key.</span></span> <span class="giallo-l"><span class="z-variable"> publicKey</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Key type.</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">secp256k1</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">p256</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">webauthn-p256</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> JSON-RPC method version.</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> }</span></span> <span class="giallo-l"><span> ]</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h4 id="response">Response</h4> <blockquote> <p>The response is intended to be forwarded to <code>wallet_sendPreparedCalls</code> (minus the <code>digest</code>).</p> </blockquote> <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"> Response</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Capabilities to be forwarded to `wallet_sendPreparedCalls`.</span></span> <span class="giallo-l"><span class="z-variable"> capabilities</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Chain ID of the chain the calls are being submitted to.</span></span> <span class="giallo-l"><span class="z-variable"> chainId</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Data specific to the Wallet to be forwarded to `wallet_sendPreparedCalls`</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> (e.g. ERC-4337 UserOperation or alternative).</span></span> <span class="giallo-l"><span class="z-variable"> context</span><span class="z-keyword">:</span><span class="z-support"> unknown</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Key (hint) that will be used to sign the call bundle.</span></span> <span class="giallo-l"><span class="z-variable"> key</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Whether the digest will be prehashed by the key (default behavior of WebCrypto APIs).</span></span> <span class="giallo-l"><span class="z-variable"> prehash</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Public key.</span></span> <span class="giallo-l"><span class="z-variable"> publicKey</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Key type.</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">secp256k1</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">p256</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">webauthn-p256</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">webcrypto-p256</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Digest of the call bundle to sign over.</span></span> <span class="giallo-l"><span class="z-variable"> digest</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> JSON-RPC method version.</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>}</span><span>;</span></span></code></pre><h4 id="example">Example</h4> <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"> response</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">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">wallet_prepareCalls</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> calls</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> to</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xcafebabecafebabecafebabecafebabecafebabe</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xdeadbeef</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> ]</span><span>,</span></span> <span class="giallo-l"><span> capabilities</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> paymasterService</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> url</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://...</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> }</span><span>,</span></span> <span class="giallo-l"><span> chainId</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> key</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> prehash</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span> publicKey</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">p256</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> 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> }</span><span>,</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 class="z-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * {</span></span> <span class="giallo-l"><span class="z-comment"> * capabilities: {</span></span> <span class="giallo-l"><span class="z-comment"> * paymasterService: {</span></span> <span class="giallo-l"><span class="z-comment"> * url: &#39;https://...&#39;</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"> * chainId: &#39;0x1&#39;,</span></span> <span class="giallo-l"><span class="z-comment"> * context: { ... },</span></span> <span class="giallo-l"><span class="z-comment"> * digest: &#39;0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef&#39;,</span></span> <span class="giallo-l"><span class="z-comment"> * key: {</span></span> <span class="giallo-l"><span class="z-comment"> * prehash: false,</span></span> <span class="giallo-l"><span class="z-comment"> * publicKey: &#39;0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef&#39;,</span></span> <span class="giallo-l"><span class="z-comment"> * type: &#39;p256&#39;,</span></span> <span class="giallo-l"><span class="z-comment"> * },</span></span> <span class="giallo-l"><span class="z-comment"> * version: &#39;1&#39;,</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></code></pre><h3 id="wallet-sendpreparedcalls"><code>wallet_sendPreparedCalls</code></h3> <p>Instructs a Wallet to execute a prepared call bundle (response of <code>wallet_prepareCalls</code>) with an accompanying <code>signature</code>.</p> <h4 id="parameters">Parameters</h4> <blockquote> <p>The request is identical to the response of <code>wallet_prepareCalls</code>, except that it includes a <code>signature</code>.</p> </blockquote> <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"> Request</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> method</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">wallet_sendPreparedCalls</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> params</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"> Capabilities.</span></span> <span class="giallo-l"><span class="z-variable"> capabilities</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Chain ID of the chain the calls are being submitted to.</span></span> <span class="giallo-l"><span class="z-variable"> chainId</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Data specific to the Wallet from the `wallet_prepareCalls` response.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> (e.g. ERC-4337 UserOperation or alternative).</span></span> <span class="giallo-l"><span class="z-variable"> context</span><span class="z-keyword">:</span><span class="z-support"> unknown</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Key that was used to sign the call bundle.</span></span> <span class="giallo-l"><span class="z-variable"> key</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Whether the digest will be prehashed by the key (default behavior of WebCrypto APIs).</span></span> <span class="giallo-l"><span class="z-variable"> prehash</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 class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Public key.</span></span> <span class="giallo-l"><span class="z-variable"> publicKey</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Key type.</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">secp256k1</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">p256</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">webauthn-p256</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">webcrypto-p256</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Signature of the call bundle.</span></span> <span class="giallo-l"><span class="z-variable"> signature</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> JSON-RPC method version.</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> }</span></span> <span class="giallo-l"><span> ]</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h4 id="response-1">Response</h4> <blockquote> <p>The response is identical to that of <code>wallet_sendCalls</code>.</p> </blockquote> <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"> Response</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> id</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> capabilities</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h4 id="example-1">Example</h4> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage z-type">const</span><span> {</span><span class="z-variable z-other z-constant"> digest</span><span>,</span><span class="z-keyword"> ...</span><span class="z-variable z-other z-constant">request</span><span> }</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">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">wallet_prepareCalls</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> calls</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> to</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xcafebabecafebabecafebabecafebabecafebabe</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xdeadbeef</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> ]</span><span>,</span></span> <span class="giallo-l"><span> capabilities</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> paymasterService</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> url</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://...</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> }</span><span>,</span></span> <span class="giallo-l"><span> chainId</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> key</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> prehash</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span> publicKey</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">p256</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> 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> }</span><span>,</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 class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> signature</span><span class="z-keyword"> =</span><span class="z-variable z-other"> p256</span><span>.</span><span class="z-entity z-name">sign</span><span>(</span><span class="z-variable z-other">digest</span><span>,</span><span class="z-variable z-other"> privateKey</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"> response</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">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">wallet_sendPreparedCalls</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> ...</span><span class="z-variable z-other">request</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> signature</span><span>,</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>}</span><span>)</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> <span class="giallo-l"><span class="z-comment"> * {</span></span> <span class="giallo-l"><span class="z-comment"> * id: &#39;0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef&#39;,</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-punctuation z-definition z-comment"> */</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>These endpoints extend the interface established by EIP-5792, given the emergent needs of application developers.</p> <p>Adding new endpoints for this specific use case is simpler than adding additional options to the <code>wallet_sendCalls</code> endpoint.</p> <p>Surfacing the prepared calls should be relatively simple for wallets, who already need to do preparation internally in order to support <code>wallet_sendCalls</code>, and who then submit signed calls on chain.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This specification is currently compatible with EIP-5792 and does not introduce breaking changes to existing <code>wallet_sendCalls</code> flows.</p> <ul> <li>It does not modify or deprecate <code>wallet_sendCalls</code>; wallets compliant with EIP-5792 continue to work unchanged.</li> <li><code>wallet_prepareCalls</code> mirrors the <code>wallet_sendCalls</code> request shape and returns values intended to be forwarded to <code>wallet_sendPreparedCalls</code>, preserving field formats such as <code>capabilities</code>, <code>chainId</code>, <code>context</code>, and <code>version</code>.</li> <li><code>wallet_sendPreparedCalls</code> consumes the same data the wallet would otherwise construct internally for EIP-5792, with the addition of an externally produced <code>signature</code>.</li> <li>Any additional key types or hints (e.g., WebCrypto/WebAuthn variants) are optional and do not affect EIP-5792 behavior.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <ul> <li> <p>Key authorization and scope: Wallets MUST verify that the provided <code>key.publicKey</code> is authorized for the account and that the requested <code>capabilities</code> are within that key’s permissions (scopes, limits, validity windows).</p> </li> <li> <p>Prehashing consistency: Honor <code>key.prehash</code> consistently. A mismatch between signer and verifier (e.g., double-hashing vs prehashed input) can cause verification failures. Wallets SHOULD fix the hash function per key type.</p> </li> <li> <p>Preparation-to-execution linkage: Wallets SHOULD ensure <code>wallet_sendPreparedCalls</code> corresponds to a <code>digest</code> they could have produced (e.g., by recomputing it) and MAY track a preparation identifier and/or validity window to mitigate long-lived replay.</p> </li> <li> <p>WebAuthn/origin considerations: For <code>webauthn-p256</code>, prefer user-verification and origin-bound credentials. Applications SHOULD keep session keys non-extractable and hardware-backed where available, and avoid presenting opaque digests for end-user approval.</p> </li> <li> <p>Resource usage and DoS: Wallets MAY rate-limit <code>wallet_prepareCalls</code>, cap bundle sizes, and validate inputs early to avoid expensive context generation for malformed or adversarial requests.</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> 2024-12-06T00:00:00+00:00 2026-02-11T14:49:27+00:00 Marc Harvey-Hillhttps://github.com/Marchhill https://wg-eips.ritovision.com/7843/

Opcode to get the current slot number

<h2 id="abstract">Abstract</h2> <p>This EIP proposes to add a new opcode <code>SLOTNUM</code> (<code>0x4b</code>), that returns the corresponding slot number for the current block.</p> <h2 id="motivation">Motivation</h2> <p>There are currently two ways to get the current slot number onchain:</p> <ol> <li> <p>Calculate from the block timestamp. This requires hardcoding the chain slot length into a smart contract.</p> </li> <li> <p>Provide the slot number as calldata and prove it against the beacon block root (using <a href="https://wg-eips.ritovision.com/4788/">EIP-4788</a>).</p> </li> </ol> <p>Both of these approaches have significant drawbacks. (1) would break contracts in the event of a change to the slot length. (2) is expensive in terms of gas, encouraging approach (1) to be used instead.</p> <p>A better approach is for the slot length to be abstracted away from applications, and instead the slot number can be calculated in the consensus layer client and exposed by an opcode. This paves the way for future changes to the slot length.</p> <h2 id="specification">Specification</h2> <p>A new opcode <code>SLOTNUM</code> is introduced at <code>0x4b</code>. It shall return one stack element.</p> <h3 id="output">Output</h3> <p>One element <code>slotNumber</code> is added to the stack; it is equal to the corresponding slot number for this block. <code>slotNumber</code> is a <code>uint64</code> in big endian encoding.</p> <h3 id="gas-cost">Gas Cost</h3> <p>The gas cost for <code>SLOTNUM</code> is a fixed fee of <code>2</code>.</p> <h3 id="rpc-changes">RPC changes</h3> <p>The slot number is calculated in the consensus layer and passed to the execution layer through the engine API.</p> <h4 id="header-extension">Header extension</h4> <p>The header encoding shall be extended to include a <code>slotNumber</code> field of type <code>uint64</code>.</p> <h4 id="engine-api-changes">Engine API changes</h4> <p>New objects <code>ExecutionPayloadV4</code> and <code>PayloadAttributesV4</code> are introduced, adding a <code>slotNumber</code> field of type <code>uint64</code>. The methods <code>engine_newPayloadV4</code>, <code>engine_getPayloadV6</code>, and <code>engine_forkChoiceUpdateV4</code> are added, to use the new objects.</p> <h2 id="rationale">Rationale</h2> <h3 id="gas-price">Gas Price</h3> <p>The opcode is priced to match similar opcodes in the <code>W_base</code> set.</p> <h3 id="calculation-in-consensus-layer">Calculation in consensus layer</h3> <p>The slot number could alternatively be calculated in the execution layer using the timestamp, but it is more appropriate to calculate values pertaining to the beacon chain in the consensus layer. Additionally this avoids code duplication, as the slot number is already calculated in the consensus layer.</p> <h3 id="zk-vm-proving">ZK-VM proving</h3> <p>The <code>SLOTNUM</code> opcode should not increase the complexity of proving EVM execution, as it is similar to existing opcodes such as <code>TIMESTAMP</code>. The slot number is included in the block header rather than as a <code>engine_newPayload</code> parameter, ensuring that the block is self-contained for proving; no extra inputs to the circuit are required.</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-12-04T00:00:00+00:00 2026-02-11T14:48:26+00:00 Gustavo Lobohttps://github.com/gflobo https://wg-eips.ritovision.com/7832/

Economically sustainable collaborative NFT collections with dynamic fees and donation-based engagement.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a standard for creating economically sustainable NFT governance for collections built on collaborative models based on <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. It introduces dynamic minting fees, role-based access control, and a donation-based engagement model to enhance creator-community interactions. These mechanisms aim to balance scarcity, incentivize meaningful participation, and ensure sustainable growth for both creators and contributors.</p> <p>The model defines "economically sustainable" as tokens whose minting value, creator subscription fees, and token quantity within each progressive discount cycle can only be adjusted once every 30 days from the last update by an <code>ADMIN</code> user. These mechanisms prevent excessive administrative modifications that could disrupt market stability, ensuring consistent price discovery and maintaining participant confidence. By aligning incentives and fostering predictability, the model creates a robust framework for engagement and value creation.</p> <h3 id="motivation">Motivation</h3> <p>As the NFT market matures, one of the recurring challenges faced by both creators and users is the inflationary nature of supply and the lack of effective mechanisms to engage the community meaningfully. NFT collections built on collaborative models require governance systems that empower all stakeholders—creators, contributors, and collectors—while also maintaining long-term economic sustainability. The introduction of this proposal aims to solve these issues by fostering a more dynamic, flexible, and transparent system for NFT collections. This EIP addresses these gaps by introducing:</p> <ul> <li><strong>Role-Based Access</strong>: Empowering creators while ensuring transparent governance by admins.</li> <li><strong>Dynamic Minting Fees</strong>: To align token costs with user activity and ownership.</li> <li><strong>Donation-Based Engagement</strong>: Encouraging contributions to creators.</li> </ul> <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>The following interface <strong>MUST</strong> be implemented.</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.20</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"> IERC7832</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC721</span><span> {</span></span> <span class="giallo-l"><span> </span></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"> CreatorTermsUpdated</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> mintBaseFee</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> creatorSignatureFee</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> maxMintsPerUserInCycle</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"> DonationReceived</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-comment"> Function to get the current token ID</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> currentTokenId</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-comment"> Function to get the current mint base fee</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mintBaseFee</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></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Function to get the creator signature fee</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> creatorSignatureFee</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></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Function to get the maximum mints a user can perform during his progressive discount cycle per mint</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> maxMintsPerUserInCycle</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-comment"> Function to get the last update timestamp</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> lastUpdateTimestamp</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-comment"> Function to get the update interval constant (30 days)</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> UPDATE_INTERVAL</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">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Function to get the CREATOR_ROLE</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getCreatorSignature</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-comment"> Function to get the CONTRIBUTOR_ROLE identifier</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> CONTRIBUTOR_ROLE</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">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Function to get CREATOR_ROLE identifier</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> CREATOR_ROLE</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">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Function to get ADMIN_ROLE identifier</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> ADMIN_ROLE</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">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Function to check the number of mints a user has performed in their current cycle of progressive discounts</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mintsPerUserInCycle</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 class="z-comment"> Allow users to donate ETH to a specific creator in the system.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> donate</span><span>(</span><span class="z-support">address</span><span class="z-variable"> creator</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-comment"> Allow users to check their mint fee</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mintFee</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-comment"> Allow token owners to burn their tokens</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 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 class="z-comment"> Allow ADMIN_ROLE pause the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> pause</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"> Allow ADMIN_ROLE unpause the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unpause</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"> Allow CREATOR_ROLE to mint</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeMint</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> uri</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-comment"> Allow ADMIN_ROLE to update contract terms</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateTerms</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> mintBaseFee</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> creatorSignatureFee</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> maxMintsPerUserInCycle</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"> Allow ADMIN_ROLE to withdraw funds from the contract</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"> 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>}</span></span></code></pre><h4 id="currenttokenid"><code>currentTokenId()</code></h4> <p><strong>Description:</strong></p> <p>Tracks the current token ID in the system. Can also be used to determine how many tokens have been minted in the system.</p> <h4 id="mintbasefee"><code>mintBaseFee()</code></h4> <p><strong>Description</strong>:<br /> The base fee for minting a token, paid by the user to create a new token.</p> <h4 id="creatorsignaturefee"><code>creatorSignatureFee()</code></h4> <p><strong>Description</strong>:<br /> The fee required for a user to acquire a creator's signature, allowing them to become a creator in the system.</p> <h4 id="maxmintsperuserincycle"><code>maxMintsPerUserInCycle()</code></h4> <p><strong>Description</strong>:<br /> The maximum number of mints a user can perform during their current cycle of progressive discounts. Once the limit is exceeded, the user's minting count is reset to zero.</p> <h4 id="lastupdatetimestamp"><code>lastUpdateTimestamp()</code></h4> <p><strong>Description</strong>:<br /> Timestamp of the last time the contract terms were updated (e.g., minting fees and creator signature fees). It is used to determine when the contract's terms can be updated again.</p> <h4 id="update-interval"><code>UPDATE_INTERVAL()</code></h4> <p><strong>Description</strong>:<br /> The time interval between contract terms updates. <strong>MUST</strong> be fixed to <ins>30 days</ins>.</p> <h4 id="admin-role"><code>ADMIN_ROLE()</code></h4> <p><strong>Description</strong>:<br /> The role identifier for admins in the system.</p> <p><strong>Requirements</strong>:</p> <ul> <li><strong>MUST</strong> be assigned inside the constructor to the <code>msg.sender</code>.</li> </ul> <h4 id="creator-role"><code>CREATOR_ROLE()</code></h4> <p><strong>Description</strong>:<br /> The role identifier for creators in the system.</p> <p><strong>Requirements</strong>:</p> <ul> <li><strong>MUST</strong> be assigned inside the constructor to the <code>msg.sender</code>.</li> </ul> <h4 id="contributor-role"><code>CONTRIBUTOR_ROLE()</code></h4> <p><strong>Description</strong>:<br /> The role identifier for contributors in the system.</p> <h4 id="mintsperuserincycle-address-user"><code>mintsPerUserInCycle(address user)</code></h4> <p><strong>Description</strong>:<br /> Tracks the number of mints a user has performed in their current cycle of progressive discounts. It is used to enforce the maximum minting limit per user.</p> <h4 id="creatortermsupdated-uint256-mintbasefee-uint256-creatorsignaturefee-uint256-maxmintsperuserincycle"><code>CreatorTermsUpdated(uint256 mintBaseFee, uint256 creatorSignatureFee, uint256 maxMintsPerUserInCycle)</code></h4> <p><strong>Description</strong>:<br /> Emitted when the contract terms related to minting are updated by the <code>ADMIN_ROLE</code>.</p> <h4 id="donationreceived-address-from-address-to-uint256-amount"><code>DonationReceived(address from, address to, uint256 amount)</code></h4> <p><strong>Description</strong>:<br /> Emitted when a user donates ETH to a creator. This event tracks the details of the donation, including the donor's address, the recipient's address, and the donation amount.</p> <p><strong>Parameters</strong>:</p> <ul> <li><code>from</code>: The address of the user making the donation.</li> <li><code>to</code>: The address of the creator receiving the donation.</li> <li><code>amount</code>: The amount of ETH donated.</li> </ul> <h4 id="safemint-string-memory-uri"><code>safeMint(string memory uri)</code></h4> <p><strong>Description</strong>:<br /> Allows the caller to mint a new token to their address with a provided URI.</p> <p><strong>Requirements</strong>:</p> <ul> <li>The caller <strong>MUST</strong> have the <strong>CREATOR_ROLE</strong>.</li> <li>The user <strong>MUST</strong> pay the minting fee, which is dynamic based on their previous minting activity.</li> <li>If the minting limit is exceeded, the user's mint count <strong>SHALL</strong> be reset to zero.</li> <li>Is <strong>RECOMMENDED</strong> to require that the contract is not paused before using this function.</li> </ul> <h4 id="mintfee"><code>mintFee()</code></h4> <p><strong>Description</strong>:<br /> Calculates and returns the current minting fee that the caller <strong>MUST</strong> pay, based on the number of mints performed during his current discount per mint cycle. Is <strong>RECOMMENDED</strong> that the fee use a logarithmic reduction to adjust the fee smoothly.</p> <blockquote> <p>Formula:</p> </blockquote> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>\text{mintFee} = </span></span> <span class="giallo-l"><span>\begin{cases}</span></span> <span class="giallo-l"><span>0, &amp; \text{if msg.sender has the ADMIN\_ROLE} \\ </span></span> <span class="giallo-l"><span>\frac{\text{mintBaseFee}}{\log_x(\text{userMints})}, &amp; \text{if } \text{userMints} &gt; 1 \\ </span></span> <span class="giallo-l"><span>\frac{\text{mintBaseFee}}{1}, &amp; \text{if } \text{userMints} &lt;= 1 </span></span> <span class="giallo-l"><span>\end{cases}</span></span> <span class="giallo-l"></span></code></pre> <blockquote> <p>Note: Please note that the returned logarithm is always rounded to integers due to the characteristics of Solidity with floating-point numbers.</p> </blockquote> <p><strong>Requirements</strong>:</p> <ul> <li>The minting fee <strong>MUST</strong> be paid by the caller.</li> </ul> <h4 id="donate-address-creator"><code>donate(address creator)</code></h4> <p><strong>Description</strong>:<br /> Allows users to donate ETH to a creator, helping fund their activities. After making a donation, the donor <strong>SHALL</strong> receive the <strong>CONTRIBUTOR_ROLE</strong>.</p> <p><strong>Requirements</strong>:</p> <ul> <li>The provided address <strong>MUST</strong> be a valid creator (having the <strong>CREATOR_ROLE</strong>).</li> <li>The <code>msg.sender</code> <strong>MUST NOT</strong> be the same as the <code>creator</code>.</li> <li>The donation amount <strong>MUST</strong> be greater than zero.</li> <li><strong>MUST</strong> emit a <code>DonationReceived</code> event after the donation is processed.</li> </ul> <h4 id="getcreatorsignature"><code>getCreatorSignature()</code></h4> <p><strong>Description</strong>:<br /> Allows a user to acquire a creator's signature by paying the required fee.</p> <p><strong>Requirements</strong>:</p> <ul> <li>The caller <strong>MUST</strong> pay the creator signature fee.</li> <li>After the payment, the caller <strong>SHALL</strong> be granted the <strong>CREATOR_ROLE</strong>.</li> <li>Is <strong>RECOMMENDED</strong> to require that the contract is not paused before using this function.</li> </ul> <h4 id="updateterms-uint256-mintbasefee-uint256-creatorsignaturefee-uint256-maxmintsperuserincycle"><code>updateTerms(uint256 mintBaseFee, uint256 creatorSignatureFee, uint256 maxMintsPerUserInCycle)</code></h4> <p><strong>Description</strong>:<br /> Allows the admin to update the minting fee, creator signature fee, and the maximum mints per user in a cycle of progressive discounts.</p> <p><strong>Requirements</strong>:</p> <ul> <li>Only the <code>ADMIN_ROLE</code> <strong>MUST</strong> call this function.</li> <li><strong>MUST</strong> be called in the contract constructor as the first update of the contract terms.</li> <li>The update interval period <strong>SHALL</strong> be respected before another update can occur.</li> <li><strong>MUST</strong> emit a <code>CreatorTermsUpdated</code> event after the contract terms are updated.</li> </ul> <h4 id="withdraw-uint256-amount"><code>withdraw(uint256 amount)</code></h4> <p><strong>Description</strong>:<br /> Allows the <code>ADMIN_ROLE</code> to withdraw ETH from the contract.</p> <p><strong>Requirements</strong>:</p> <ul> <li>Only the <code>ADMIN_ROLE</code> <strong>MUST</strong> call this function.</li> </ul> <h4 id="burn-uint256-tokenid"><code>burn(uint256 tokenId)</code></h4> <p><strong>Description</strong>:<br /> Allows the owner of a token to burn (destroy) the token specified by <code>tokenId</code>.</p> <p><strong>Requirements</strong>:</p> <ul> <li>The caller <strong>MUST</strong> be the owner of the token.</li> </ul> <h4 id="pause"><code>pause()</code></h4> <p><strong>Description</strong>:<br /> Allows the <code>ADMIN_ROLE</code> to pause the contract, disabling certain functions.</p> <p><strong>Requirements</strong>:</p> <ul> <li>Only the <code>ADMIN_ROLE</code> <strong>SHOULD</strong> call this function to pause the contract.</li> </ul> <h4 id="unpause"><code>unpause()</code></h4> <p><strong>Description</strong>:<br /> Allows the <code>ADMIN_ROLE</code> to unpause the contract, re-enabling functionality.</p> <p><strong>Requirements</strong>:</p> <ul> <li>Only the <code>ADMIN_ROLE</code> <strong>SHOULD</strong> call this function to unpause the contract.</li> </ul> <h2 id="rationale">Rationale</h2> <p>Below are the key considerations and justifications for the design choices:</p> <ol> <li> <p><strong>Access Control</strong></p> <ul> <li><strong>Problem</strong>: In collaborative NFT systems, it is essential to ensure that critical contract functions are executed only by authorized users to prevent misuse or manipulation. Without proper access control, there is a risk that anyone could modify key parameters, such as minting fees, terms, or contract pauses, which could lead to instability or unfair advantages for certain users.</li> <li><strong>Solution</strong>: By introducing role-based access control, this standard ensures that only trusted actors can perform sensitive actions. Admins are responsible for updating contract terms, pausing or unpausing the contract, and withdrawing funds, while creators can manage their own collections and get donations. This prevents arbitrary changes that might harm market stability or erode community trust.</li> </ul> </li> <li> <p><strong>Dynamic Minting Fees</strong></p> <ul> <li><strong>Problem</strong>: Fixed minting fees often lead to hoarding and disproportionate ownership, limiting equitable access to NFTs.</li> <li><strong>Solution</strong>: By dynamically adjusting minting fees based on user activity within defined <u>minting cycles</u>, we ensure that users are incentivized to engage with the platform by receiving <u>gradual discounts as they mint</u>. Using a logarithmic reduction in minting fees ensures that the process is gradual, preventing market manipulation and maintaining scarcity over time.</li> </ul> </li> <li> <p><strong>Donation-Based Engagement</strong></p> <ul> <li><strong>Problem</strong>: Creators often lack sustainable models for fostering community engagement and receiving contributions.</li> <li><strong>Solution</strong>: The donation system provides a transparent way for contributors to support their favorite creators directly. This can be used to attribute benefits in future trades, for example. This encourages deeper engagement and strengthens the relationship between creators and their communities.</li> </ul> </li> </ol> <h3 id="backwards-compatibility">Backwards Compatibility</h3> <p>This EIP is fully compatible with ERC-721. Extensions like dynamic minting fees, donation systems are modular and do not impact existing NFT token functionalities.</p> <h3 id="reference-implementation">Reference Implementation</h3> <h4 id="mintfee-1"><code>mintFee()</code></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"> mintFee</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-keyword"> if</span><span> (</span><span class="z-entity z-name">hasRole</span><span>(</span><span>ADMIN_ROLE</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span>)</span><span class="z-keyword"> return</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> userMints </span><span class="z-keyword">=</span><span class="z-entity z-name"> mintsPerUserInCycle</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> divisor </span><span class="z-keyword">=</span><span> userMints </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span class="z-constant"> 1</span><span class="z-keyword"> ?</span><span class="z-constant"> 1</span><span class="z-keyword"> :</span><span> Math</span><span>.</span><span class="z-entity z-name">log2</span><span>(</span><span>userMints</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> mintBaseFee </span><span class="z-keyword">/</span><span> divisor</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="safemint-string-memory-uri-1"><code>safeMint(string memory uri)</code></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"> safeMint</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> uri</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">payable</span></span> <span class="giallo-l"><span class="z-storage z-type">override</span><span> </span></span> <span class="giallo-l"><span class="z-entity z-name">onlyIfNotPaused</span></span> <span class="giallo-l"><span class="z-entity z-name">nonReentrant</span></span> <span class="giallo-l"><span class="z-entity z-name">onlyRole</span><span>(</span><span class="z-entity z-name">CREATOR_ROLE</span><span>)</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> userMintsExceeded </span><span class="z-keyword">=</span><span class="z-entity z-name"> mintsPerUserInCycle</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span class="z-keyword"> &gt;</span><span> maxMintsPerUserInCycle</span><span>;</span></span> <span class="giallo-l"></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">&gt;</span><span class="z-keyword">=</span><span class="z-entity z-name"> mintFee</span><span>(</span><span>)</span><span>,</span><span class="z-string"> &quot;Not enough ETH!&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> tokenId </span><span class="z-keyword">=</span><span> currentTokenId</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _safeMint</span><span>(</span><span class="z-variable z-language">msg.sender</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> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>userMintsExceeded</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> mintsPerUserInCycle</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 class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity z-name"> mintsPerUserInCycle</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 class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <ul> <li><strong>Reentrancy Protection:</strong><br /> Is <strong>RECOMMENDED</strong> to make sure the functions <code>safeMint</code>, <code>withdraw</code> and <code>donate</code> are protected against reentrancy attacks.</li> <li><strong>Paused State:</strong><br /> The Administrators <strong>MUST</strong> be able to pause the contract during emergencies to prevent unwanted operations and mitigate risks during uncertain times.</li> <li><strong>Burning Security:</strong> Ensure that only the owner of a token can burn it, reducing the risk of malicious contracts or unauthorized users destroying tokens belonging to others. The burn behavior is restricted to the ownership function, enhancing security by preventing accidental or abusive token destruction.</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> 2024-11-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Allen Donghttps://github.com/Allen2730 Lonika Zhanglonika@memolabs.net Steven Hesteven@memolabs.net https://wg-eips.ritovision.com/7829/

Bring Data Assets—online digital products—to NFTs and ensure their integrity through a storage proof.

<h2 id="abstract">Abstract</h2> <p>This proposal extends the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard to support Data Assets which refers to digital products created by creators.</p> <p>This proposal introduces a modular Data Availability (DA) layer that safeguards on-chain data integrity, preventing value discrepancies caused by off-chain data loss, tampering, or expiration. Furthermore, this proposal introduces a new role, Reader, where a single token can have multiple Readers. This solution reflects the inherent replicability of Data Assets, namely that each piece of data can be replicated multiple times and accessed by multiple users, thus amplifying the value of the Data Assets.</p> <h2 id="motivation">Motivation</h2> <p>ERC-721 proposed NFTs to represent the ownership of digital or physical assets. Currently, the NFT metadata is considered the NFT content, and its scarcity determines the value of the NFT. NFT owners can convert the content value of NFTs into revenue by transferring the ownership of NFTs. However, due to the high transaction fees, storage costs, and other expenses, NFTs are currently only able to represent the ownership of high-value assets, which limits the range of assets that NFTs can represent. This is especially true for Data Assets, which refers to digital products created by creators, such as online blogs, videos, small games or music. Therefore, the value of Data Assets depends on their quality, whether the creator is famous, whether it is hyped and so on.</p> <p>Furthermore, to reduce storage costs, the NFT content is generally stored off-chain or using cross-chain storage, and the link of NFT content is saved on-chain. Off-chain users can access the NFT content by visiting the link. However, on-chain contracts can not access the link to determine the status of the data, such as data loss, data tampering, or data expiration. These situations can lead to the data deviating from its actual value, but the NFT still exists on the chain, and the underlying copyright is still being sold in the market.</p> <p>This proposal introduces Data Asset NFTs, which solve the dilemma of on-chain Data Assets by combining a modular data layer--Data Availability (DA).</p> <h3 id="related-work">Related Work</h3> <p>There are Existing proposals to NFT integrity, but each proposal contains at least one of these limitations:</p> <ul> <li>Storing NFT content on-chain, which requires the underlying data asset to possess inherent speculative value to justify prohibitive storage costs.</li> <li>Requiring attestations from a trusted third party, while introduces centralized trust issue.</li> </ul> <h2 id="specification">Specification</h2> <h3 id="terms">Terms</h3> <p>In this proposal, we divide data assets into three parts:</p> <ul> <li>Storage Metadata: Includes commitment, size, expire, and uploader's address. Stored and maintained by storage contracts on the blockchain.</li> <li>Permission Metadata: Includes information on ownership and reading rights, as well as which addresses can modify this information. Stored and maintained by permission contracts on the blockchain.</li> <li>Data Content: Data uploaded by users to the storage system. Data content is stored in off-chain storage nodes.</li> </ul> <p><strong>Every compliant data permission contract must implement the Interface</strong>:</p> <p>The data permission contract is an extension of ERC-721, adding the reader role, where a single data asset can correspond to multiple readers.</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"> IERC7829</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"> event</span><span class="z-entity z-name"> UpdateReader</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"> reader</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> valid</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"> setReader</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"> reader</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> valid</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"> isReader</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"> reader</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"> commitByTokenId</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>)</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"> sizeByTokenId</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 class="z-storage z-type"> function</span><span class="z-entity z-name"> expireByTokenId</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></span></code></pre> <p>The metadata JSON schema for Data Asset NFTs is as follows:</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">Data 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 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">commit</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 commit pointing to the data resource</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">size</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">The size of the data resource</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">expire</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">The expire time of the data resource</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>The Reader role should not involve changes in permissions, meaning that Readers cannot call functions such as <code>transfer</code>, <code>approve</code>, <code>setApprovalForAll</code>, and <code>setReader</code>.</p> <p>When Alice calls the <code>transfer</code> function to transfer one of Alice's Data Asset NFTs to Bob:</p> <ul> <li>The owner address is set to Bob's address;</li> <li>The approved address is set to 0.</li> <li>However, all readers are retained.</li> </ul> <h3 id="extension-storage-contract">Extension: Storage Contract</h3> <p>This proposal extends the metadata information of NFTs. Metadata information is uploaded by users and requires relevant certificates, which can be the storage node's signature on the NFT's metadata information. This proposal specify that the NFT metadata should at least include commitment, size, expire, and uploader's address.</p> <p>The implementer of this proposal selects a trusted storage system and a trusted modular data layer DA, or deploys the modular storage layer DA themselves.</p> <p>When the Owner or Approved Operator calls the <code>transfer</code>, <code>approve</code>, or <code>setReader</code> functions, they must additionally check whether the current time <code>block.timestamp</code> is greater than the expiration time <code>expire</code> before making the call. If the current time <code>block.timestamp</code> is less than the expiration time <code>expire</code>, then proceed with subsequent operations; if the current time <code>block.timestamp</code> is greater than the expiration time <code>expire</code>, then interrupt subsequent operations and return an exception message.</p> <h3 id="extension-storage-proof">Extension: Storage Proof</h3> <p>This proposal uses storage proof to prove the availability of data content, thereby proving the correctness of NFT metadata, especially the <code>expire</code> of the NFT.</p> <p>This proposal does not limit the proof scheme used, but recommends the use of KZG polynomial commitment technology. KZG polynomial commitment technology can generate two generator elements $g_1$ and $g_2$ during initialization. It also generates a corresponding commitment C based on the data content and uploads it as the unique identifier of the data when uploading metadata. When generating proof, the verifier generates a random number $z$, and the prover generates proof $P=(y, π)$ based on the data content and random number $z$, verifying $e(π, yg_1-zg_2) = e(C - y*g_1, g_2)$.</p> <p>In addition, KZG polynomial commitment technology can aggregate multiple proofs into a single proof, and two-step verification can verify the correctness of all proofs, including summing all commitments to get the aggregated commitment $C_n$, and verifying the aggregated proof $P_n=(y_n, π_n)$ by verifying $e(π_n, y_ng_1-zg_2) = e(C_n - y_n*g_1, g_2)$.</p> <p>To avoid long proof generation times, random sampling can be used to randomly select data to be challenged. Therefore, the contract needs to provide a secure pseudo-random number generation function for randomly selecting challenged data, which can also be used as the random number $z$ for KZG.</p> <p>During the verification process, summing all commitments to get the aggregated commitment requires a large amount of gas fees. This proposal recommends using optimistic proof, which assumes that the aggregated commitment is correct and only verifies $e(π_n, y_ng_1-zg_2) = e(C_n - y_n*g_1, g_2)$ during verification. After verifying the aggregated proof, the availability of the data cannot be proven, so a certain period of challenging is required. During the challenging period, anyone can challenge the commitment proof $C_n$. If the challenge is successful, the challenger gets a reward and the prover is punished; if the challenge fails, the challenger is punished and the prover gets additional benefits.</p> <h2 id="rationale">Rationale</h2> <p><img src="https://wg-eips.ritovision.com/7829/./assets/architect.svg" alt="arc" /></p> <h3 id="data-asset-nft-integrity">Data Asset NFT Integrity</h3> <p>The DA Layer is responsible for off-chain storage of Data Content and on-chain storage of Storage Metadata, and ensures the integrity of Data Assets through periodically submiting and verifing <strong>storage proofs</strong>.</p> <p>To optimize gas costs, we adopt an <strong>optimistic proof approach</strong>, significantly reducing verification expenses.</p> <p><strong>Proof Cycle Workflow</strong>:</p> <ol> <li><strong>Proof Generation &amp; Aggregation</strong>: <ul> <li>The <strong>DA Provider</strong> generates storage proofs for sampled data content, aggregates them into a single <strong>aggregated proof</strong>, and submits it to the <strong>DA Contract</strong>.</li> <li>The <strong>DA Contract</strong> verifies the correctness of the aggregated proof.</li> </ul> </li> <li><strong>Fraud Proof Mechanism</strong>: <ul> <li>The <strong>DA Verifier</strong> performs off-chain validation to confirm whether the aggregated proof was correctly derived from the selected data.</li> <li>If the proof is invalid, the verifier <strong>challenges</strong> it by submitting a fraud proof to the DA Contract.</li> </ul> </li> </ol> <h3 id="reader">Reader</h3> <p>This proposal enables a <strong>single data asset NFT</strong> to have <strong>multiple Readers</strong>, each granted access to the off-chain data content. This design aligns with the inherent properties of data assets:</p> <ul> <li><strong>Replicability</strong>: Data can be copied and distributed without degradation.</li> <li><strong>Value Amplification</strong>: By allowing resale or multi-party access, the asset’s utility and market value increase.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal combines the existing ERC-721 extension and is backward compatible with the ERC-721 standard.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The security of Data Asset NFTs depends not only on the blockchain but also on the modular data layer DA. Therefore, the implementer of this proposal needs to carefully select the modular data layer DA.</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-27T00:00:00+00:00 2026-02-11T14:48:26+00:00 Sam Kaufmanhttps://github.com/SampkaML Marco Stronatihttps://github.com/paracetamolo Yuliya Alexievhttps://github.com/yuliyaalexiev Jeff Lauhttps://github.com/jefflau Sam Wilsonhttps://github.com/samwilsn Vitalik Buterinhttps://github.com/vbuterin Teddyhttps://github.com/0xteddybear Joxeshttps://github.com/Joxess Racuhttps://github.com/0xRacoon Skeletor Spacemanhttps://github.com/0xskeletor-spaceman TiTihttps://github.com/0xtiti Gorihttps://github.com/0xGorilla Ardyhttps://github.com/0xArdy Onizukahttps://github.com/onizuka-wl Lumihttps://github.com/oxlumi Moebiushttps://github.com/0xmoebius Thomas Cloweshttps://github.com/clowestab Prem Makeighttps://github.com/nxt3d Monohttps://github.com/0xMonoAx Orcahttps://github.com/0xrcinus https://wg-eips.ritovision.com/7828/

Defines a human readable chain-specific address format that allows for chain discovery using ENS.

<h2 id="abstract">Abstract</h2> <p>This proposal defines an Interoperable Name, a chain-specific address format with the structure <code>&lt;address&gt;@&lt;chain&gt;#&lt;checksum&gt;</code>.</p> <p>The <code>&lt;address&gt;</code> can be an address, or an ENS name.</p> <p>The <code>&lt;chain&gt;</code> can be a <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/29762ef99a6ffea1e07e3f796c0d1a5a95e89b88/CAIPs/caip-350.md">CAIP-350</a> chain identifier, or it can be a human-readable label. This specification defines how such labels can be resolved to chain-specific metadata, via the Ethereum Name Service (ENS).</p> <p>The optional <code>&lt;checksum&gt;</code> allows clients to verify the integrity of the Interoperable Name.</p> <p>The result is chain-specific addresses such as:</p> <ul> <li><code>0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7@eip155:1#80B12379</code></li> <li><code>alice.eth@eip155:1</code></li> <li><code>alice.eth@ethereum</code></li> </ul> <h2 id="motivation">Motivation</h2> <p>The current Ethereum address landscape is evolving toward an ecosystem with hundreds, and eventually thousands, of L2s that share the same address format as Ethereum mainnet. This means an address by itself is insufficient to determine which chain it is associated with. This ambiguity can result in funds being sent to an unreachable address on the wrong chain.</p> <p><a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> introduced a binary format for representing a <em>target address</em> on a specific blockchain. While this binary data is well suited for low-level usage (e.g. in smart contracts), its meaning is semantically opaque to human users.</p> <p>The core motivation for introducing the <em>Interoperable Name</em> standard is to provide maximally readable, <em>chain-specific addresses</em> for user-facing interactions.</p> <p>A foundational text representation (e.g. <code>0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7@eip155:1</code>) enables a significantly more readable <em>chain-specific address</em> format. An expanded form that leverages the name resolution capabilities of the Ethereum Name Service (ENS) further improves readability, allowing addresses to be expressed in a maximally human-friendly form (e.g. <code>wallet.ensdao.eth@ethereum</code>).</p> <p>An on-chain registry provides a canonical source of truth for mapping human-readable chain labels to the metadata associated with each chain. Today, chains are identified using a variety of specifications (e.g. <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/36ef9ee906da090366cb679634a0850e91785db6/CAIPs/caip-2.md">CAIP-2</a> and <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> for EVM-compatible networks), whose formats are not necessarily semantically clear to human users. By introducing an on-chain registry, applications can refer to a chain using a readable identifier such as <code>base</code>, rather than an opaque identifier like <code>eip155:8453</code> or <code>8453</code>.</p> <p>Historically, the mapping from chain names to identifiers has, since <a href="https://wg-eips.ritovision.com/155/">EIP-155</a>, been maintained off-chain using a centralized list.</p> <p>This approach has several shortcomings:</p> <ul> <li>It does not scale with the growing number of blockchains</li> <li>It relies on a trusted centralized maintainer</li> <li>It does not support non-EVM chains</li> </ul> <p>This specification defines an architecture that enables chain operators to take ownership of their chain-specific data, thereby reducing reliance on a single centralized entity and ensuring data integrity.</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="terminology">Terminology</h3> <p>This section builds upon the Terminology defined in <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a>.</p> <p><strong>Interoperable Name</strong> : A human-readable <em>chain-specific address</em> format meant to be used by humans for user-facing interactions. e.g. <code>0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045@eip155:1#4CA88C9C</code></p> <h3 id="interoperable-name-definition">Interoperable Name Definition</h3> <p>The format of an <em>Interoperable Name</em> is <code>&lt;address&gt;@&lt;chain&gt;#&lt;checksum&gt;</code> where the components match the following regular expressions:</p> <h4 id="syntax">Syntax</h4> <pre class="giallo z-code"><code data-lang="ABNF"><span class="giallo-l"><span>&lt;interoperable-name&gt; ::=</span><span class="z-keyword"> &lt;</span><span class="z-variable z-other">address</span><span class="z-keyword">&gt;</span><span class="z-string"> &quot;</span><span class="z-string">@</span><span class="z-string">&quot;</span><span class="z-keyword"> &lt;</span><span class="z-variable z-other">chain</span><span class="z-keyword">&gt;</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"> &lt;</span><span class="z-variable z-other">checksum</span><span class="z-keyword">&gt;</span><span class="z-keyword"> ]</span></span> <span class="giallo-l"><span>&lt;address&gt; ::=</span><span class="z-keyword"> [</span><span class="z-variable z-other">.</span><span class="z-variable z-other">-</span><span class="z-variable z-other">:</span><span class="z-variable z-other">_</span><span class="z-variable z-other">%</span><span class="z-variable z-other">a-zA-Z0-9</span><span class="z-keyword">]</span><span class="z-variable z-other">*</span></span> <span class="giallo-l"><span>&lt;chain&gt; ::=</span><span class="z-keyword"> [</span><span class="z-variable z-other">.</span><span class="z-variable z-other">-</span><span class="z-variable z-other">:</span><span class="z-variable z-other">_</span><span class="z-variable z-other">a-zA-Z0-9</span><span class="z-keyword">]</span><span class="z-variable z-other">*</span></span> <span class="giallo-l"><span>&lt;checksum&gt; ::=</span><span class="z-keyword"> [</span><span class="z-variable z-other">0</span><span class="z-variable z-other">-</span><span>9</span><span class="z-variable z-other">A-F</span><span class="z-keyword">]</span><span class="z-variable z-other">{</span><span class="z-variable z-other">8</span><span class="z-variable z-other">}</span></span></code></pre> <p>These components have the following meanings:</p> <ul> <li> <p><code>&lt;address&gt;</code> can either be:</p> <ul> <li>A <em>target address</em> as defined in <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a>.</li> <li>An Ethereum Name Service (ENS) name. e.g, <code>wallet.ensdao.eth</code></li> </ul> </li> <li> <p><code>&lt;chain&gt;</code> can either be:</p> <ul> <li>The string representation of a specific blockchain as defined in <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/29762ef99a6ffea1e07e3f796c0d1a5a95e89b88/CAIPs/caip-350.md">CAIP-350</a>. For example <code>eip155:1</code> for Ethereum Mainnet, or <code>solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdpKuc147dw2N9d</code> for Solana Mainnet.</li> <li>A human-readable label identifier for a specific chain, defined and registered as a subdomain of the <code>on.eth</code> ENS name. An on-chain resolver contract maps these labels to their corresponding canonical <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> chain identifiers, and exposes additional chain metadata.</li> </ul> </li> <li> <p><code>&lt;checksum&gt;</code> is defined as the first 4 bytes (8 characters) of the Keccak-256 hash, represented as a hexadecimal string (Base16, as specified in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc4648">RFC 4648</a>). The hash is computed over the concatenation of the following binary fields from the canonical <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> Interoperable Address:</p> <ul> <li><code>ChainType</code></li> <li><code>ChainReferenceLength</code></li> <li><code>ChainReference</code></li> <li><code>AddressLength</code></li> <li><code>Address</code></li> </ul> </li> </ul> <p><strong>Note:</strong> The Version field MUST NOT be included in the hashed data.</p> <h4 id="checksums">Checksums</h4> <p>The checksum provides an optional integrity verification mechanism for Interoperable Names that include a raw target address.</p> <ul> <li>The checksum is OPTIONAL but RECOMMENDED when the <address> component represents a target address, as it helps mitigate homoglyph and spoofing attacks for chain-specific addresses.</li> <li>A checksum SHOULD NOT be included when the <address> component is an ENS name</li> <li>Clients MAY include or omit the checksum when displaying or sharing an <em>Interoperable Name</em>.</li> <li>Clients MAY accept <em>Interoperable Name</em> inputs with or without a checksum.</li> <li>When a checksum is provided for a target address, clients MAY validate it by deriving the underlying <em>Interoperable Address</em> and recalculating the checksum.</li> </ul> <p>UI/UX developers are encouraged to determine the most appropriate way to warn users when a checksum does not match, when resolution fails, or any other scenario they deem necessary to ensure user safety and clarity.</p> <h4 id="versioning">Versioning</h4> <p>This specification does not define its own versioning mechanism.</p> <p>Implementers SHOULD ensure they are up to date with the version of <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> they are using. Refer to the versioning section of <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> for detailed rules.</p> <p>Implementations MUST maintain convertibility between <em>Interoperable Names</em> and the corresponding <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> <em>Interoperable Address</em> binary format.</p> <h3 id="target-address-examples"><em>Target Address</em> Examples</h3> <h4 id="ethereum-mainnet">Ethereum Mainnet</h4> <p>The address <code>0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7</code> on Ethereum Mainnet could be represented as either of the following:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7@eip155:1#80B12379</span></span> <span class="giallo-l"><span>0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7@ethereum#80B12379</span></span></code></pre> <p><strong>Note:</strong> In the second example <code>ethereum</code> is the chain label for Ethereum mainnet in the on-chain ENS resolver set for the <code>on.eth</code> namespace (see below).</p> <h4 id="non-evm-chains">Non-EVM chains</h4> <p>The address <code>bc1qwz2lhc40s8ty3l5jg3plpve3y3l82x9l42q7fk</code> on Bitcoin Mainnet could be represented as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>bc1qwz2lhc40s8ty3l5jg3plpve3y3l82x9l42q7fk@bip122:000000000019d6689c085ae165831e93#597D21A1</span></span> <span class="giallo-l"><span>bc1qwz2lhc40s8ty3l5jg3plpve3y3l82x9l42q7fk@bitcoin#597D21A1</span></span></code></pre> <p><strong>Note:</strong> In the second example <code>bitcoin</code> is the chain label for Bitcoin mainnet in the on-chain ENS resolver set for the <code>on.eth</code> namespace (see below).</p> <h3 id="ens-address-examples">ENS <code>&lt;address&gt;</code> Examples</h3> <p>ENS resolves addresses on a chain-specific basis, as outlined in ENSIP-9 and ENSIP-11.</p> <h4 id="ethereum-mainnet-1">Ethereum Mainnet</h4> <p>Assuming that <code>wallet.ensdao.eth</code> resolves to <code>0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7</code> <strong>for Ethereum mainnet</strong> either of the following could be used to represent the same <em>target address</em>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>wallet.ensdao.eth@eip155:1#80B12379</span></span> <span class="giallo-l"><span>wallet.ensdao.eth@ethereum#80B12379</span></span></code></pre><h4 id="non-evm-chains-1">Non-EVM chains</h4> <p>Assuming that <code>wallet.ensdao.eth</code> resolves to <code>bc1qwz2lhc40s8ty3l5jg3plpve3y3l82x9l42q7fk</code> <strong>for Bitcoin mainnet</strong> either of the following could be used to represent the same <em>target address</em>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>wallet.ensdao.eth@bip122:000000000019d6689c085ae165831e93#597D21A1</span></span> <span class="giallo-l"><span>wallet.ensdao.eth@bitcoin#597D21A1</span></span></code></pre><h3 id="resolving-the-chain-component">Resolving the <code>&lt;chain&gt;</code> component</h3> <p>If the <code>&lt;chain&gt;</code> component of an <em>Interoperable Address</em> does not contain a colon (<code>:</code>) it is interpreted as being label under the <code>on.eth</code> ENS namespace.</p> <p>The resolver for <code>on.eth</code> MUST implement ENSIP-24 - Arbitrary Data Resolution, and allow for the resolution of the <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> <em>Interoperable Address</em> for the specified chain label using the key, <code>interoperable-address</code>. For example if you resolve the <code>interoperable-address</code> data record for <code>ethereum.on.eth</code> the <em>Interoperable Address</em> <code>0x00010000010100</code> SHOULD be returned.</p> <p>The on-chain resolver for <code>on.eth</code> MAY implement aliasing so that multiple chain labels, such as <code>op.on.eth</code> and <code>optimism.on.eth</code>, resolve to the same underlying data. To ensure consistency and integrity, there must be a single canonical representation of this data.</p> <p>A pseudocode implementation of this resolution is as follows:</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"> * Pseudocode to resolve the Interoperable Address associated with &#39;ethereum.on.eth&#39; </span></span> <span class="giallo-l"><span class="z-comment"> * Using ENSIP-24 and the data key &#39;interoperable-address&#39;</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 class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> 1. Inputs</span></span> <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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ethereum.on.eth</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> key</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">interoperable-address</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"> 2. Derive the Node (Namehash)</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> node</span><span class="z-keyword"> =</span><span class="z-entity z-name"> namehash</span><span>(</span><span class="z-variable z-other">domain</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"> 3. Locate the Resolver for the node</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> registry</span><span class="z-keyword"> =</span><span class="z-entity z-name"> getContract</span><span>(</span><span class="z-variable z-other z-constant">ENS_REGISTRY_ADDRESS</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"> resolverAddress</span><span class="z-keyword"> =</span><span class="z-variable z-other"> registry</span><span>.</span><span class="z-entity z-name">resolver</span><span>(</span><span class="z-variable z-other">node</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"> 4. Instantiate the Resolver</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> resolver</span><span class="z-keyword"> =</span><span class="z-entity z-name"> getContract</span><span>(</span><span class="z-variable z-other">resolverAddress</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"> 5. Resolve the Interoperable Address</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> ENSIP-24 Interface: data(bytes32 node, string key) -&gt; bytes</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> rawData</span><span class="z-keyword"> =</span><span class="z-variable z-other"> resolver</span><span>.</span><span class="z-entity z-name">data</span><span>(</span><span class="z-variable z-other">node</span><span>,</span><span class="z-variable z-other"> key</span><span>)</span><span>;</span></span></code></pre> <p>The resolver for <code>on.eth</code> MUST implement ENSIP-5 - Text Records, and allow for the resolution of text records for the <code>reverse.on.eth</code> namespace of the form <code>chain-label:</code> followed by the <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> <em>Interoperable Address</em> you are trying to discern the label for. For example, the <em>Interoperable Address</em> representing Ethereum Mainnet is <code>0x00010000010100</code>. Resolution of the text record <code>chain-label:0x00010000010100</code> for the <code>reverse.on.eth</code> namespace SHOULD return <code>ethereum</code>.</p> <p>While multiple labels - such as <code>op.on.eth</code> and <code>optimism.on.eth</code> — may resolve to the <em>Interoperable Address</em> <code>0x00010000010a00</code>, the reverse resolution process will always return the canonical label: <code>optimism</code>.</p> <p>A pseudocode implementation of this resolution is as follows:</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"> * Pseudocode to resolve a chain label from an ERC-7930 Interoperable Address</span></span> <span class="giallo-l"><span class="z-comment"> * Using ENSIP-5, the namespace reverse.on.eth, and the text record key chain-label:0x00010000010a00</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 class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> 1. Inputs</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> interoperableAddress</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00010000010a00</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> namespace</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">reverse.on.eth</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"> 2. Construct the specific Text Record Key</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Format: &quot;chain-label:&quot; + [ERC-7930 Address]</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> textKey</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">chain-label:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword"> +</span><span class="z-variable z-other"> interoperableAddress</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"> 3. Derive the Node (Namehash) for the reverse namespace</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> node</span><span class="z-keyword"> =</span><span class="z-entity z-name"> namehash</span><span>(</span><span class="z-variable z-other">namespace</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"> 4. Locate the Resolver for &#39;reverse.on.eth&#39;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> As the resolver will be set on the second level domain `on.eth` consideration should be given to ENSIP-10</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> registry</span><span class="z-keyword"> =</span><span class="z-entity z-name"> getContract</span><span>(</span><span class="z-variable z-other z-constant">ENS_REGISTRY_ADDRESS</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"> resolverAddress</span><span class="z-keyword"> =</span><span class="z-variable z-other"> registry</span><span>.</span><span class="z-entity z-name">resolver</span><span>(</span><span class="z-variable z-other">node</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"> 5. Instantiate the Resolver</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> resolver</span><span class="z-keyword"> =</span><span class="z-entity z-name"> getContract</span><span>(</span><span class="z-variable z-other">resolverAddress</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"> 6. Query the Text Record (ENSIP-5)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Signature: text(bytes32 node, string key) -&gt; string</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> chainLabel</span><span class="z-keyword"> =</span><span class="z-variable z-other"> resolver</span><span>.</span><span class="z-entity z-name">text</span><span>(</span><span class="z-variable z-other">node</span><span>,</span><span class="z-variable z-other"> textKey</span><span>)</span><span>;</span></span></code></pre> <p>Additional implementation details about the resolver contract implementation can be discerned by referencing the ENS documentation, and viewing the verified source code of the contract set as the resolver for <code>on.eth</code>.</p> <h3 id="resolving-the-address-component">Resolving the <code>&lt;address&gt;</code> component</h3> <p>If the <code>&lt;address&gt;</code> component contains a period (<code>.</code>), it is assumed to be an ENS name. Because ENS fully integrates with the Domain Name System (DNS), any traditional domain name can function as an ENS name, as can any name using the blockchain-native <code>.eth</code> extension.</p> <p>If an ENS address is used within the <code>&lt;address&gt;</code> component, it MUST be resolved subject to the ENS resolution specifications, giving consideration to the target chain specified in the <code>&lt;chain&gt;</code> component.</p> <p>The specifications of note are ENSIP-9: Multichain address resolution, ENSIP-10: Wildcard resolution, and ENSIP-11: EVM compatible Chain Address Resolution. These specification outline how one resolves an ENS name to discern the address <strong>for a specific chain</strong>. Consideration MUST be given to both current and future ENSIPs pertaining to address resolution.</p> <p>If a <em>target address</em> has been used for the <code>&lt;address&gt;</code> component (or once the ENS name has been resolved to a <em>target address</em>) it should be serialized subject to the rules defined in the relevant <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/29762ef99a6ffea1e07e3f796c0d1a5a95e89b88/CAIPs/caip-350.md">CAIP-350</a> profile for the given <code>&lt;chain&gt;</code>. This ensures that different valid text representations (e.g., case variations in an address) resolve to a single, canonical binary form, which is essential for consistent checksum calculation and data integrity.</p> <h2 id="rationale">Rationale</h2> <ul> <li>The Ethereum Name Service (ENS) is a well-established blockchain identity primitive that enables the registration of human-readable names (e.g. example.eth, wallet.ensdao.eth) which resolve to addresses on a chain-specific basis. ENS is widely used, familiar to users, and well understood by implementers.</li> <li>For flexibility and backwards compatibility, this specification allows a raw target address to be used in the <code>&lt;address&gt;</code> component, accommodating users and applications that prefer traditional address representations.</li> <li>In this specification, checksums are defined as OPTIONAL. While they provide meaningful integrity guarantees for raw, chain-specific target addresses, their applicability to ENS-based names is limited. ENS names may resolve to different addresses over time depending on resolver behavior, which means that a previously generated checksum may no longer validate even when resolution is correct. In addition, when using ENS, users already delegate name normalization, resolution, and validation to ENS-specific mechanisms, so applying checksums in these cases provides limited additional security while increasing complexity and ambiguity for implementers. As a result, checksums are primarily intended to protect the integrity of raw, chain-specific addresses, while remaining optional and flexible for user-facing applications.</li> <li>The <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> Version field is excluded from checksum calculation to allow the same Interoperable Name to remain valid across version upgrades of the binary format.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>Implementers MUST give consideration to the name normalization specifications of the Ethereum Name Service so as to avoid homoglyph or spoofing attacks. These are outlined in ENSIP-1 and ENSIP-15.</li> <li>Users should stay vigilant of address poisoning attacks when using a raw <em>target address</em> in the <code>&lt;address&gt;</code> component.</li> <li>ENS resolution depends on resolver contracts set for each name. Resolvers may change over time, and wildcard resolvers (ENSIP-10) may return dynamic data</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> 2024-11-23T00:00:00+00:00 2026-02-11T14:49:27+00:00 Giulio Rebuffohttps://github.com/Giulio2002 Toni Wahrstätterhttps://github.com/nerolation https://wg-eips.ritovision.com/7825/

Introduce a protocol-level cap on the maximum gas used by a transaction to 16,777,216 (2^24).

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a protocol-level cap on the maximum gas usage per transaction to 16,777,216 (2^24) gas. By implementing this limit, Ethereum can enhance its resilience against certain DoS vectors, improve network stability, and provide more predictability to transaction processing costs, especially in the context of increasing the gas limit.</p> <h2 id="motivation">Motivation</h2> <p>Currently, transactions can theoretically consume up to the entire block gas limit, which poses several risks:</p> <ol> <li><strong>DoS Attacks</strong>: A single transaction consuming most or all of the block gas can result in uneven load distribution and impact network stability.</li> <li><strong>State Bloat Risks</strong>: High-gas transactions often result in larger state changes, increasing the burden on nodes and exacerbating the Ethereum state growth problem.</li> <li><strong>Validation Overhead</strong>: High-gas transactions can lead to longer block verification times, negatively impacting user experience and network decentralization.</li> </ol> <p>By limiting individual transactions to a maximum of 16,777,216 gas, we aim to:</p> <ul> <li>Reduce the risks of single-transaction DoS attacks.</li> <li>Promote fairer gas allocation across transactions within a block.</li> <li>Ensure better synchronization among nodes by mitigating extreme block validation times.</li> </ul> <h2 id="specification">Specification</h2> <h3 id="gas-cap">Gas Cap</h3> <ul> <li>Enforce a protocol-level maximum of <strong>16,777,216 gas (2^24)</strong> for any single transaction.</li> <li>This cap applies regardless of the block gas limit set by miners or validators.</li> <li>Transactions specifying gas limits higher than 16,777,216 gas will be rejected with an appropriate error code (e.g., <code>MAX_GAS_LIMIT_EXCEEDED</code>).</li> </ul> <h3 id="changes-to-evm-behavior">Changes to EVM Behavior</h3> <ol> <li><strong>Txpool Validation</strong>: During transaction validation, if the <code>gasLimit</code> specified by the sender exceeds 16,777,216, the transaction is invalidated (not included in the txpool).</li> <li><strong>Block Validation</strong>: As part of block validation before processing, any block having a transaction with <code>gasLimit</code> &gt; 16,777,216 is deemed invalid and rejected.</li> </ol> <h3 id="protocol-adjustment">Protocol Adjustment</h3> <ul> <li>The <code>GAS_LIMIT</code> parameter for transactions will be capped in client implementations at 16,777,216.</li> <li>This cap is <strong>independent</strong> of the block gas limit, which exceeds this value.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="why-16-777-216-2-24">Why 16,777,216 (2^24)?</h3> <p>The proposed cap of 16,777,216 gas (2^24) provides a clean power-of-two boundary that simplifies implementation while still being large enough to accommodate most complex transactions, including contract deployments and advanced DeFi interactions. This value represents approximately half of typical block sizes (30-40 million gas), ensuring multiple transactions can fit within each block.</p> <h3 id="compatibility-with-current-gas-dynamics">Compatibility with Current Gas Dynamics</h3> <ul> <li><strong>Backward Compatibility</strong>: Transactions with gas usage below 16,777,216 remain unaffected. Existing tooling and dApps need only minor updates to enforce the new cap.</li> <li><strong>Impact on Validators</strong>: Validators can continue to process blocks with a gas limit exceeding 16,777,216, provided individual transactions adhere to the cap.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is <strong>not backward-compatible</strong> with transactions that specify gas limits exceeding 16,777,216. Transactions with such high limits will need to be split into smaller operations. This adjustment is expected to impact a minimal number of users and dApps, as most transactions today fall well below the proposed cap.</p> <p>An <a href="https://wg-eips.ritovision.com/7825/assets/analysis/">empirical analysis</a> has been conducted to assess the potential impact of this change.</p> <h2 id="security-considerations">Security Considerations</h2> <ol> <li><strong>DoS Mitigation</strong>: A fixed cap reduces the risk of DoS attacks caused by excessively high-gas transactions.</li> <li><strong>Block Verification Stability</strong>: By capping individual transactions, the validation of blocks becomes more predictable and uniform.</li> <li><strong>Edge Cases</strong>: Certain highly complex transactions, such as large contract deployments, may require re-architecting to fit within the 16,777,216 gas cap.</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-11-21T00:00:00+00:00 2026-02-11T14:48:26+00:00 Vectorizedhttps://github.com/Vectorized Jake Moxeyhttps://github.com/jxom Hadrien Crouboishttps://github.com/Amxx https://wg-eips.ritovision.com/7821/

A minimal batch executor interface for delegations

<h2 id="abstract">Abstract</h2> <p>This proposal defines a minimal batch executor interface for delegations. A delegation is a smart contract that implements logic which other smart contracts can delegate to. This allows atomic batched executions to be prepared in a standardized way.</p> <h2 id="motivation">Motivation</h2> <p>With the advent of <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>, it is possible for Externally Owned Accounts (EOAs) to perform atomic batched executions.</p> <p>We anticipate that there will be multiple EIP-7702 delegations from multiple major vendors. A standard for the execution interface will enable better interoperability. EIP-7702 delegation is a risky procedure which should be done sparingly — it should not be performed upon each time a user switches websites. Also, EIP-7702 delegations are transactions that cost gas, making frequent delegation switching uneconomical. A standardized execution interface will reduce the need to switch delegations.</p> <p>This standard complements the <code>wallet_sendCalls</code> API in <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a>. It enables the detection of atomic batch execution capabilities on EOAs and the preparation of the calldata for atomic batch executions on EOAs.</p> <p>Using atomic batched executions reduces total latency and total tranaction costs, making it preferable over sequential transaction sending for EOAs.</p> <p>Hence the utmost motivation for this proposal, which has been crafted for maximal simplicity, extensibility, performance and compatibility.</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="overview">Overview</h3> <p>The minimal batch executor interface is defined as follows:</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"> Interface for minimal batch executor.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7821</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"> Call struct for the `execute` function.</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Call</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> to</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Replaced with `address(this)` if `address(0)`.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> value</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Amount of native currency (i.e. Ether) to send.</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> data</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Calldata to send with the call.</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"> Executes the calls in `executionData`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Reverts and bubbles up error if any call fails.</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"> MAY replace the `Call.to` with `address(this)` if `address(0)`.</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"> `executionData` encoding (single batch):</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - If `opData` is empty, `executionData` is simply `abi.encode(calls)`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Else, `executionData` is `abi.encode(calls, opData)`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> See: https://eips.ethereum.org/EIPS/eip-7579</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"> `executionData` encoding (batch of batches):</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `executionData` is `abi.encode(bytes[])`, where each element in `bytes[]`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> is an `executionData` for a single batch.</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"> Supported modes:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `0x01000000000000000000...`: Single batch. Does not support optional `opData`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `0x01000000000078210001...`: Single batch. Supports optional `opData`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `0x01000000000078210002...`: Batch of batches. The mode is optional.</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"> For the &quot;batch of batches&quot; mode, each batch will be recursively passed into</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `execute` internally with mode `0x01000000000078210001...`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Useful for passing in batches signed by different signers.</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"> Authorization checks:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - If `opData` is empty, the implementation SHOULD require that</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `msg.sender == address(this)`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - If `opData` is not empty, the implementation SHOULD use the signature</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> encoded in `opData` to determine if the caller can perform the execution.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - If `msg.sender` is an authorized entry point, then `execute` MAY accept</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> calls from the entry point, and MAY use `opData` for specialized logic.</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"> `opData` may be used to store additional data for authentication,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> paymaster data, gas limits, etc.</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"> For calldata compression efficiency, if a Call.to is `address(0)`,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> it will be replaced with `address(this)`.</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-support">bytes32</span><span class="z-variable"> mode</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> executionData</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"> @dev</span><span class="z-comment"> Provided for execution mode support detection.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Only returns true for:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `0x01000000000000000000...`: Single batch. Does not support optional `opData`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `0x01000000000078210001...`: Single batch. Supports optional `opData`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `0x01000000000078210002...`: Batch of batches. The mode is optional.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsExecutionMode</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> mode</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>Support for batch of batches mode is OPTIONAL. If it is not supported, the contract MUST return false for any mode starting with <code>0x01000000000078210002</code> in <code>supportsExecutionMode</code>.</p> <h3 id="recommendations">Recommendations</h3> <p>To support the approve + swap workflow on EOAs with delegations, frontends SHOULD:</p> <ol> <li> <p>Query <code>supportsExecutionMode(bytes32(0x0100000000000000000000000000000000000000000000000000000000000000))</code>, ensuring that it returns true.</p> </li> <li> <p>Perform <code>execute(bytes32(0x0100000000000000000000000000000000000000000000000000000000000000), abi.encode(calls))</code>.</p> </li> </ol> <h2 id="rationale">Rationale</h2> <p>We aim for radical minimalism to keep the standard as left-curved as possible. Simplicity is the key to adoption. Our North Star is to get every decentralized exchange to support the approve + swap workflow for EOAs with delegations as soon as possible.</p> <h3 id="execute-and-supportsexecutionmode"><code>execute</code> and <code>supportsExecutionMode</code></h3> <p>We have opted to use the <code>execute</code> and <code>supportsExecutionMode</code> functions in <a href="https://wg-eips.ritovision.com/7579/">ERC-7579</a> for better compatibility with the existing smart account ecosystem.</p> <p>While radical minimalism is the goal, some compromises have to be made in the pursuit for better adoption.</p> <p>For minimalism, this standard does not require implementing the <code>executeFromExecutor</code> function in <a href="https://wg-eips.ritovision.com/7579/">ERC-7579</a>.</p> <h3 id="optional-encoding-of-opdata-in-executiondata">Optional encoding of <code>opData</code> in <code>executionData</code></h3> <p>The <code>opData</code> bytes parameter can be optionally included in <code>executionData</code> by either doing <code>abi.encode(calls)</code> or <code>abi.encode(calls, opData)</code>.</p> <h3 id="replacing-address-0-with-address-this">Replacing <code>address(0)</code> with <code>address(this)</code></h3> <p>For calldata compression optimization.</p> <h3 id="optional-batch-of-batches-mode">Optional batch of batches mode</h3> <p>The <code>opData</code> may be used to provide authentication data for a single batch. Having a batch of batches mode will enable a single transaction to be able to submit batches signed by different signers, without the need for an authorized entry point. This mode is kept optional because the same functionality can still be achieved with the use of an authorized entry point. It is included for developer experience.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backwards compatibility issues.</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"> ^0.8.4</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"> Minimal batch executor mixin.</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"> ERC7821</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment">´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> STRUCTS </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><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"> @dev</span><span class="z-comment"> Call struct for the `execute` function.</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Call</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> to</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Replaced with `address(this)` if `address(0)`.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> value</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Amount of native currency (i.e. Ether) to send.</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> data</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Calldata to send with the call.</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 class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> ERRORS </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><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"> @dev</span><span class="z-comment"> The execution mode is not supported.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> UnsupportedExecutionMode</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">´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> EXECUTION OPERATIONS </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><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"> @dev</span><span class="z-comment"> Executes the calls in `executionData`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Reverts and bubbles up error if any call fails.</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"> `executionData` encoding (single batch):</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - If `opData` is empty, `executionData` is simply `abi.encode(calls)`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Else, `executionData` is `abi.encode(calls, opData)`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> See: https://eips.ethereum.org/EIPS/eip-7579</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"> `executionData` encoding (batch of batches):</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `executionData` is `abi.encode(bytes[])`, where each element in `bytes[]`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> is an `executionData` for a single batch.</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"> Supported modes:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `0x01000000000000000000...`: Single batch. Does not support optional `opData`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `0x01000000000078210001...`: Single batch. Supports optional `opData`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `0x01000000000078210002...`: Batch of batches. The mode is optional.</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"> For the &quot;batch of batches&quot; mode, each batch will be recursively passed into</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `execute` internally with mode `0x01000000000078210001...`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Useful for passing in batches signed by different signers.</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"> Authorization checks:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - If `opData` is empty, the implementation SHOULD require that</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `msg.sender == address(this)`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - If `opData` is not empty, the implementation SHOULD use the signature</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> encoded in `opData` to determine if the caller can perform the execution.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - If `msg.sender` is an authorized entry point, then `execute` MAY accept</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> calls from the entry point, and MAY use `opData` for specialized logic.</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"> `opData` may be used to store additional data for authentication,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> paymaster data, gas limits, etc.</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"> For calldata compression efficiency, if a Call.to is `address(0)`,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> it will be replaced with `address(this)`.</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-support">bytes32</span><span class="z-variable"> mode</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> executionData</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"> payable</span></span> <span class="giallo-l"><span class="z-storage z-type"> virtual</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> id </span><span class="z-keyword">=</span><span class="z-entity z-name"> _executionModeId</span><span>(</span><span>mode</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>id </span><span class="z-keyword">==</span><span class="z-constant"> 3</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> mode </span><span class="z-keyword">^</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-constant">3</span><span class="z-keyword"> &lt;&lt;</span><span> (</span><span class="z-constant">22</span><span class="z-keyword"> *</span><span class="z-constant"> 8</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> batches </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>executionData</span><span>,</span><span> (</span><span class="z-support">bytes</span><span>[</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-support">uint256</span><span> i</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> batches</span><span>.</span><span>length</span><span>;</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>i</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> execute</span><span>(</span><span>mode</span><span>,</span><span> batches</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-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>id </span><span class="z-keyword">==</span><span class="z-support"> uint256</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> UnsupportedExecutionMode</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> tryWithOpData</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> @solidity memory-safe-assembly</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> t </span><span class="z-keyword">:=</span><span class="z-entity z-name"> gt</span><span>(</span><span class="z-entity z-name">mload</span><span>(</span><span class="z-entity z-name">add</span><span>(</span><span>executionData</span><span>,</span><span class="z-constant"> 0x20</span><span>)</span><span>)</span><span>,</span><span class="z-constant"> 0x3f</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> executionDataLength </span><span class="z-keyword">:=</span><span class="z-entity z-name"> mload</span><span>(</span><span>executionData</span><span>)</span></span> <span class="giallo-l"><span> tryWithOpData </span><span class="z-keyword">:=</span><span class="z-entity z-name"> and</span><span>(</span><span class="z-entity z-name">eq</span><span>(</span><span>id</span><span>,</span><span class="z-constant"> 2</span><span>)</span><span>,</span><span class="z-entity z-name"> and</span><span>(</span><span class="z-entity z-name">gt</span><span>(</span><span>executionDataLength</span><span>,</span><span class="z-constant"> 0x3f</span><span>)</span><span>,</span><span> t</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> Call</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> calls</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> opData</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>tryWithOpData</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> (</span><span>calls</span><span>,</span><span> opData</span><span>)</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>executionData</span><span>,</span><span> (</span><span>Call</span><span>[</span><span>]</span><span>,</span><span class="z-support"> bytes</span><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> calls </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>executionData</span><span>,</span><span> (</span><span>Call</span><span>[</span><span>]</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity z-name"> _execute</span><span>(</span><span>calls</span><span>,</span><span> opData</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"> Provided for execution mode support detection.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Only returns true for:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `0x01000000000000000000...`: Single batch. Does not support optional `opData`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `0x01000000000078210001...`: Single batch. Supports optional `opData`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `0x01000000000078210002...`: Batch of batches. The mode is optional.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsExecutionMode</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> mode</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">bool</span><span class="z-variable"> result</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> _executionModeId</span><span>(</span><span>mode</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 class="z-comment"> /*</span><span class="z-comment">´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> INTERNAL HELPERS </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><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"> @dev</span><span class="z-comment"> 0: invalid mode, 1: no `opData` support, 2: with `opData` support, 3: batch of batches.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _executionModeId</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> mode</span><span>)</span><span class="z-storage z-type"> internal</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 class="z-variable"> id</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Only supports atomic batched executions.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> For the encoding scheme, see: https://eips.ethereum.org/EIPS/eip-7579</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Bytes Layout:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - [0] ( 1 byte ) `0x01` for batch call.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - [1] ( 1 byte ) `0x00` for revert on any failure.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - [2..5] ( 4 bytes) Reserved by ERC7579 for future standardization.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - [6..9] ( 4 bytes) `0x00000000` or `0x78210001` or `0x78210002`.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - [10..31] (22 bytes) Unused. Free for use.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> m </span><span class="z-keyword">=</span><span> (</span><span class="z-support">uint256</span><span>(</span><span>mode</span><span>)</span><span class="z-keyword"> &gt;&gt;</span><span> (</span><span class="z-constant">22</span><span class="z-keyword"> *</span><span class="z-constant"> 8</span><span>)</span><span>)</span><span class="z-keyword"> &amp;</span><span class="z-constant"> 0xffff00000000ffffffff</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>m </span><span class="z-keyword">==</span><span class="z-constant"> 0x01000000000078210002</span><span>)</span><span> id </span><span class="z-keyword">=</span><span class="z-constant"> 3</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>m </span><span class="z-keyword">==</span><span class="z-constant"> 0x01000000000078210001</span><span>)</span><span> id </span><span class="z-keyword">=</span><span class="z-constant"> 2</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>m </span><span class="z-keyword">==</span><span class="z-constant"> 0x01000000000000000000</span><span>)</span><span> id </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-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Executes the calls and returns the results.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Reverts and bubbles up error if any call fails.</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">Call</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> calls</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> opData</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> internal</span></span> <span class="giallo-l"><span class="z-storage z-type"> virtual</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Very basic auth to only allow this contract to be called by itself.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Override this function to perform more complex auth with `opData`.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>opData</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-support"> uint256</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 class="z-variable z-language">msg.sender</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></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Remember to return `_execute(calls)` when you override this function.</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> _execute</span><span>(</span><span>calls</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> In your override, replace this with logic to operate on `opData`.</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"> Executes the calls.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Reverts and bubbles up error if any call fails.</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">Call</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> calls</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"> for</span><span> (</span><span class="z-support">uint256</span><span> i</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> calls</span><span>.</span><span>length</span><span>;</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>i</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> Call </span><span class="z-storage z-type">memory</span><span> c </span><span class="z-keyword">=</span><span> calls</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> to </span><span class="z-keyword">=</span><span> c</span><span>.</span><span>to </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-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span class="z-keyword"> :</span><span> c</span><span>.</span><span>to</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _execute</span><span>(</span><span>to</span><span>,</span><span> c</span><span>.</span><span>value</span><span>,</span><span> c</span><span>.</span><span>data</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 class="z-storage z-type"> @dev</span><span class="z-comment"> Executes the call.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Reverts and bubbles up error if the call fails.</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-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-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"> internal</span></span> <span class="giallo-l"><span class="z-storage z-type"> virtual</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 class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span> to</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span> value</span><span>}</span><span>(</span><span>data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>success</span><span>)</span><span class="z-keyword"> return</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> @solidity memory-safe-assembly</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Bubble up the revert if the call reverts.</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span class="z-entity z-name">add</span><span>(</span><span>result</span><span>,</span><span class="z-constant"> 0x20</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>result</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="access-controls-for-execute">Access controls for <code>execute</code></h3> <p>Implementations should ensure that <code>execute</code> have the proper access 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> 2024-11-19T00:00:00+00:00 2026-02-11T14:48:25+00:00 Shubham Khandelwalhttps://github.com/shubh-ta Anushka Yadavhttps://github.com/anushka642000 https://wg-eips.ritovision.com/7820/

Registration, unregistration, role assignment, and role revocation for contracts, ensuring secure and transparent role management.

<h2 id="abstract">Abstract</h2> <p>The Access Control Registry (ACR) standard defines a universal interface for managing role-based access control across multiple smart contracts. This standard introduces a centralized registry system allowing access control management for multiple smart contracts. The single access-control registry smart contract manages the user roles across multiple contracts, and can be queryed for contract-specific role information. Additionally, the ACR standard provides functionality to grant and revoke roles for specific accounts, either individually or in bulk, ensuring that only authorized users can perform specific actions within a specific contract.</p> <p>The core of the standard includes:</p> <ul> <li> <p><strong>Registration and Unregistration</strong>: Contracts can register with the ACR, specifying an admin who can manage roles within the contract. Contracts can also be unregistered when they are no longer active.</p> </li> <li> <p><strong>Role Management</strong>: Admins can grant or revoke roles for accounts, either individually or in batches, ensuring fine-grained control over who can perform what actions within a contract.</p> </li> <li> <p><strong>Role Verification</strong>: Any account can verify if another account has a specific role in a registered contract, providing transparency and facilitating easier integration with other systems.</p> </li> </ul> <p>By centralizing access control management, the ACR standard aims to reduce redundancy, minimize errors in access control logic, and provide a clear and standardized approach to role management across smart contracts. This improves security and maintainability, making it easier for developers to implement robust access control mechanisms in their applications.</p> <h2 id="motivation">Motivation</h2> <p>As decentralized applications (dApps) grow in complexity, managing access control across multiple smart contracts becomes increasingly difficult. Current practices involve bespoke implementations, leading to redundancy and potential security flaws. A standardized approach for managing roles and permissions will ensure better interoperability, security, and transparency. By providing a unified interface for registering contracts and managing roles, this standard simplifies development, ensures consistency and enhances security. It facilitates easier integration and auditing, fostering a more robust and interoperable ecosystem.</p> <p>The advantages of using the provided system might be:</p> <p>Structured smart contracts management via specialized contracts. Ad-hoc access-control provision of a protocol. Ability to specify custom access control rules to maintain the protocol.</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 <code>AccessControlRegistry</code> contract provides a standardized interface for managing access control in Ethereum smart contracts. It includes functions to register and unregister contracts, grant and revoke roles for specific contracts, and check if an account has a particular role in a registered contract. Events are emitted for contract registration, unregistration, role grants, and role revocations, ensuring transparency and traceability of access control changes.</p> <p>Additionally, the AccessControlRegistry MUST reject the registration of zero addresses.</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.23</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IAccessControlRegistry</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Emitted when a contract is registered.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param _contract The address of the registered contract.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param _admin The address of the admin for the registered contract.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ContractRegistered</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _contract</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _admin</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Emitted when a contract is unregistered.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param _contract The address of the unregistered contract.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param _admin The address who unregistered the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ContractUnregistered</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _contract</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _admin</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Emitted when a role is granted to an account for a contract.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param targetContract The address of the contract.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param role The role being granted.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param account The address of the account.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RoleGranted</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"> targetContract</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"> role</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 class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Emitted when a role is revoked from an account for a contract.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param targetContract The address of the contract.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param role The role being revoked.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param account The address of the account.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RoleRevoked</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"> targetContract</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"> role</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 class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Registers a contract with the given admin.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param _admin The address of the admin for the registered contract.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerContract</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _admin</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"> Unregisters a contract.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param _contract The address of the contract to unregister.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unRegisterContract</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"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Grants roles to multiple accounts for multiple contracts.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param targetContracts An array of contract addresses to which roles will be granted.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param roles An array of roles to be granted.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param accounts An array of accounts to be granted the roles.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> grantRole</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"> targetContracts</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"> roles</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"> accounts</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-comment"> //</span><span class="z-comment"> Revokes roles from multiple accounts for multiple contracts.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param targetContracts An array of contract addresses from which roles will be revoked.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param roles An array of roles to be revoked.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param accounts An array of accounts from which the roles will be revoked.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeRole</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"> targetContracts</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"> roles</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"> accounts</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> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">Gets the information of a registered contract.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">@param _contract The address of the contract to get the information.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">@return isActive Whether the contract is active.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">@return admin The address of the admin for the contract.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">MUST revert if the registered contract doesn&#39;t exist</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getContractInfo</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _contract</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 class="z-variable"> isActive</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> admin</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Gets the information of a registered contract.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param _contract The address of the contract to get the information.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @return isActive Whether the contract is active.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @return admin The address of the admin for the contract.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> MUST revert if the registered contract doesn&#39;t exist`</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getRoleInfo</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _contract</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 class="z-variable"> isActive</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> admin</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The <code>IAccessControlRegistry</code> interface aims to provide a standardized way to manage access control across multiple contracts within the ecosystem. By defining a clear structure and set of events, this interface helps streamline the process of registering, unregistering, and managing roles for contracts. The rationale for each function and event is as follows:</p> <h3 id="contract-registration-and-unregistration">Contract Registration and Unregistration</h3> <p><strong><code>registerContract(address _admin)</code></strong>: This function allows the registration of a new contract along with its admin address. This is crucial for initializing the access control settings for a contract and ensuring that there is an accountable admin who can manage roles and permissions.</p> <p><strong><code>unRegisterContract(address _contract)</code></strong>: This function enables the removal of a contract from the registry. Unregistering a contract is important when a contract is no longer in use or needs to be decommissioned to prevent unauthorized access.</p> <h3 id="role-management">Role Management</h3> <p><strong><code>grantRole(address[] memory targetContracts, bytes32[] memory roles, address[] memory accounts)</code></strong>: This function allows the assignment of roles to multiple accounts for multiple contracts in a single transaction. This bulk operation is designed to reduce the gas costs and simplify the process of role assignment in large systems with numerous contracts and users.</p> <p><strong><code>revokeRole(address[] memory targetContracts, bytes32[] memory roles, address[] memory accounts)</code></strong>: Similar to <code>grantRole</code>, this function facilitates the revocation of roles from multiple accounts across multiple contracts in a single transaction. This ensures efficient management of permissions, especially in scenarios where many users need their roles updated simultaneously.</p> <h3 id="role-checking">Role Checking</h3> <p><strong><code>getRoleInfo(address targetContract, address account, bytes32 role)</code></strong>: This view function allows the verification of whether a particular account holds a specific role for a given contract. This is essential for ensuring that operations requiring specific permissions are performed only by authorized users.</p> <h3 id="contract-information-retrieval">Contract Information Retrieval</h3> <p><strong><code>getContractInfo(address _contract)</code></strong>: This function provides the ability to retrieve the status and admin information of a registered contract. It enhances transparency and allows administrators and users to easily query the status and management of any contract within the registry.</p> <h3 id="events">Events</h3> <p><strong><code>ContractRegistered(address indexed _contract, address indexed _admin)</code></strong>: Emitted when a new contract is registered, this event ensures that there is a public record of contract registrations, facilitating auditability and transparency.</p> <p><strong><code>ContractUnregistered(address indexed _contract, address indexed _admin)</code></strong>: Emitted when a contract is unregistered, this event serves to notify the system and its users of the removal of a contract from the registry, which is critical for maintaining an up-to-date and accurate registry.</p> <p><strong><code>RoleGranted(address indexed targetContract, bytes32 indexed role, address indexed account)</code></strong>: Emitted when a role is granted to an account, this event provides a public log that can be used to track role assignments and changes, ensuring that role grants are transparent and verifiable.</p> <p><strong><code>RoleRevoked(address indexed targetContract, bytes32 indexed role, address indexed account)</code></strong>: Emitted when a role is revoked from an account, this event similarly ensures that role revocations are publicly logged and traceable, supporting robust access control management.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The <code>register</code> function must be invoked from the registering smart contract. The <code>grantRole</code> and <code>revokeRole</code> functions must be invoked either from the registered contract or the admin of the registered 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.8.23</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IAccessControlRegistry.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"> AccessControlRegistry</span><span class="z-storage"> is</span><span class="z-entity z-name"> IAccessControlRegistry</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Contains information about a registered contract.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param isActive Indicates whether the contract is active.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param admin The address of the admin for the registered contract.</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> ContractInfo</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isActive</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> admin</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"> Mapping to store information of registered contracts</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> ContractInfo</span><span>)</span><span class="z-storage z-type"> public</span><span> contracts</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Mapping to track roles assigned to accounts for specific contracts</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">address</span><span class="z-keyword"> =&gt;</span><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"> bool</span><span>)</span><span>)</span><span>)</span><span class="z-storage z-type"> public</span><span> _contractRoles</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Custom error to handle duplicate registration attempts</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ContractAlreadyRegistered</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"> Modifier to check if the caller is an admin or the contract itself</span></span> <span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> onlyAdminOrContract</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</span><span>)</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"> _isAdmin</span><span>(</span><span>_contract</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span class="z-keyword"> ||</span><span> </span></span> <span class="giallo-l"><span> (</span><span>contracts</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>isActive </span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-language"> msg.sender</span><span class="z-keyword"> ==</span><span> _contract</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Caller is not admin nor contract&quot;</span></span> <span class="giallo-l"><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 class="z-comment"> Modifier to check if the caller is an admin of the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> onlyAdmin</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</span><span>)</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"> _isAdmin</span><span>(</span><span>_contract</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Caller is not an admin&quot;</span></span> <span class="giallo-l"><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 class="z-comment"> Modifier to ensure the contract is active</span></span> <span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> onlyActiveContract</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>contracts</span><span>[</span><span>_contract</span><span>]</span><span>.</span><span>isActive</span><span>,</span><span class="z-string"> &quot;Contract not registered&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-comment"> //</span><span class="z-comment"> Modifier to validate if the provided address is non-zero</span></span> <span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> validAddress</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 class="z-keyword"> require</span><span>(</span><span>addr </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;Invalid address&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-comment"> //</span><span class="z-comment"> Registers a contract with the given admin</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> _admin: Address of the admin to register</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerContract</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _admin</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> validAddress</span><span>(</span><span class="z-entity z-name">_admin</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> _contract </span><span class="z-keyword">=</span><span class="z-variable z-language"> msg.sender</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 contract is already registered</span></span> <span class="giallo-l"><span> ContractInfo </span><span class="z-storage z-type">storage</span><span> contractInfo </span><span class="z-keyword">=</span><span> contracts</span><span>[</span><span>_contract</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>contractInfo</span><span>.</span><span>isActive</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> ContractAlreadyRegistered</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"> Register the contract with the provided admin</span></span> <span class="giallo-l"><span> contractInfo</span><span>.</span><span>isActive </span><span class="z-keyword">=</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> contractInfo</span><span>.</span><span>admin </span><span class="z-keyword">=</span><span> _admin</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"> ContractRegistered</span><span>(</span><span>_contract</span><span>,</span><span> _admin</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"> Unregisters a contract</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> _contract: Address of the contract to unregister</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unRegisterContract</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</span><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-entity z-name"> onlyAdmin</span><span>(</span><span class="z-entity z-name">_contract</span><span>)</span><span> </span></span> <span class="giallo-l"><span class="z-entity z-name"> onlyActiveContract</span><span>(</span><span class="z-entity z-name">_contract</span><span>)</span><span> </span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> ContractInfo </span><span class="z-storage z-type">storage</span><span> contractInfo </span><span class="z-keyword">=</span><span> contracts</span><span>[</span><span>_contract</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> contractInfo</span><span>.</span><span>isActive </span><span class="z-keyword">=</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span> contractInfo</span><span>.</span><span>admin </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 class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ContractUnregistered</span><span>(</span><span>_contract</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-comment"> //</span><span class="z-comment"> Grants roles to multiple accounts for multiple contracts</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> targetContracts: Array of contract addresses</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> roles: Array of roles to grant</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> accounts: Array of accounts to assign the roles</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> grantRole</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"> targetContracts</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"> roles</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"> accounts</span></span> <span class="giallo-l"><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> <span class="giallo-l"><span> targetContracts</span><span>.</span><span>length </span><span class="z-keyword">==</span><span> roles</span><span>.</span><span>length </span><span class="z-keyword">&amp;&amp;</span></span> <span class="giallo-l"><span> roles</span><span>.</span><span>length </span><span class="z-keyword">==</span><span> accounts</span><span>.</span><span>length</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Array lengths do not match&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"> uint256</span><span> cachedArrayLength </span><span class="z-keyword">=</span><span> roles</span><span>.</span><span>length</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Grant roles in a batch</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</span><span> i</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> cachedArrayLength</span><span>;</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>i</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _grantRole</span><span>(</span><span>targetContracts</span><span>[</span><span>i</span><span>]</span><span>,</span><span> roles</span><span>[</span><span>i</span><span>]</span><span>,</span><span> accounts</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> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Revokes roles from multiple accounts for multiple contracts</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> targetContracts: Array of contract addresses</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> roles: Array of roles to revoke</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> accounts: Array of accounts from which roles are revoked</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeRole</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"> targetContracts</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"> roles</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"> accounts</span></span> <span class="giallo-l"><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> <span class="giallo-l"><span> targetContracts</span><span>.</span><span>length </span><span class="z-keyword">==</span><span> roles</span><span>.</span><span>length </span><span class="z-keyword">&amp;&amp;</span></span> <span class="giallo-l"><span> roles</span><span>.</span><span>length </span><span class="z-keyword">==</span><span> accounts</span><span>.</span><span>length</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Array lengths do not match&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"> uint256</span><span> cachedArrayLength </span><span class="z-keyword">=</span><span> roles</span><span>.</span><span>length</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Revoke roles in a batch</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</span><span> i</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> cachedArrayLength</span><span>;</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>i</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _revokeRole</span><span>(</span><span>targetContracts</span><span>[</span><span>i</span><span>]</span><span>,</span><span> roles</span><span>[</span><span>i</span><span>]</span><span>,</span><span> accounts</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> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Retrieves information of a registered contract</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> _contract: Address of the contract</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Returns: isActive status and admin address</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getContractInfo</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</span><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 class="z-support">bool</span><span class="z-variable"> isActive</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> admin</span><span>)</span><span> </span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> ContractInfo </span><span class="z-storage z-type">storage</span><span> info </span><span class="z-keyword">=</span><span> contracts</span><span>[</span><span>_contract</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>info</span><span>.</span><span>isActive</span><span>,</span><span> info</span><span>.</span><span>admin</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"> Gets role information for an account and contract</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> targetContract: Address of the target contract</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> account: Address of the account</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> role: Role identifier</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Returns: Boolean indicating if the account has the role</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getRoleInfo</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> targetContract</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"> bytes32</span><span class="z-variable"> role</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">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _contractRoles</span><span>[</span><span>targetContract</span><span>]</span><span>[</span><span>account</span><span>]</span><span>[</span><span>role</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"> Internal function to grant a role to an account for a contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _grantRole</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> targetContract</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> role</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> account</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-storage z-type"> internal</span></span> <span class="giallo-l"><span class="z-entity z-name"> onlyAdminOrContract</span><span>(</span><span class="z-entity z-name">targetContract</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> onlyActiveContract</span><span>(</span><span class="z-entity z-name">targetContract</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> validAddress</span><span>(</span><span class="z-entity z-name">account</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> _contractRoles</span><span>[</span><span>targetContract</span><span>]</span><span>[</span><span>account</span><span>]</span><span>[</span><span>role</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> RoleGranted</span><span>(</span><span>targetContract</span><span>,</span><span> role</span><span>,</span><span> account</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"> Internal function to revoke a role from an account for a contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _revokeRole</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> targetContract</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> role</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> account</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-storage z-type"> internal</span></span> <span class="giallo-l"><span class="z-entity z-name"> onlyAdminOrContract</span><span>(</span><span class="z-entity z-name">targetContract</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> onlyActiveContract</span><span>(</span><span class="z-entity z-name">targetContract</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> validAddress</span><span>(</span><span class="z-entity z-name">account</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> _contractRoles</span><span>[</span><span>targetContract</span><span>]</span><span>[</span><span>account</span><span>]</span><span>[</span><span>role</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Role already revoked&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> _contractRoles</span><span>[</span><span>targetContract</span><span>]</span><span>[</span><span>account</span><span>]</span><span>[</span><span>role</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> RoleRevoked</span><span>(</span><span>targetContract</span><span>,</span><span> role</span><span>,</span><span> account</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"> Checks if the caller is an admin for the contract</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> _contract: Address of the contract</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> _admin: Address of the admin</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Returns: Boolean indicating admin status</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _isAdmin</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _admin</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-keyword"> return</span><span> _admin </span><span class="z-keyword">==</span><span> contracts</span><span>[</span><span>_contract</span><span>]</span><span>.</span><span>admin</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><h3 id="design-decisions">Design Decisions</h3> <p>There are a few design decisions that have to be explicitly specified to ensure the functionality, security, and efficiency of the <code>IAccessControlRegistry</code>:</p> <h4 id="decentralized-contract-registration">Decentralized Contract Registration</h4> <p><strong>No Central Owner</strong>: There is no central owner who can register contracts. This design choice promotes decentralization and ensures that individual contracts are responsible for their own registration and management.</p> <h4 id="efficient-storage-and-lookup">Efficient Storage and Lookup</h4> <p><strong>Mapping Utilization</strong>: The use of mappings for storing contract information (<code>mapping(address =&gt; ContractInfo) private contracts</code>) and role assignments (<code>mapping(address =&gt; mapping(address =&gt; mapping(bytes32 =&gt; bool))) private _contractRoles</code>) ensures efficient storage and lookup. This is crucial for maintaining performance in a large-scale system with numerous contracts and roles.</p> <h4 id="role-management-flexibility">Role Management Flexibility</h4> <p><strong>Bulk Operations</strong>: Functions like <code>grantRole</code> and <code>revokeRole</code> allow for the assignment and revocation of roles to multiple accounts for multiple contracts in a single transaction. This bulk operation reduces gas costs and simplifies the process of role management in large systems.</p> <h4 id="robust-security-measures">Robust Security Measures</h4> <p><strong>Admin-Only Operations</strong>: Functions that modify the state, such as unRegisterContract, <code>_grantRole</code>, and <code>_revokeRole</code>, are restricted to contract admins. This ensures that only authorized personnel can manage contracts and roles, reducing the risk of unauthorized changes.</p> <p><strong>Valid Address Checks</strong>: The <code>validAddress</code> modifier ensures that addresses are non-zero, preventing potential issues with null addresses which could lead to unintended behavior or security vulnerabilities.</p> <p><strong>Active Contract Checks</strong>: The <code>onlyActiveContract</code> modifier ensures that actions are only performed on active or registered contracts, preventing operations on inactive or unregistered contracts.</p> <h4 id="transparent-auditing">Transparent Auditing</h4> <p><strong>Event Logging</strong>: Emitting events for each significant action (registration, unregistration, role granting, and revocation) provides a transparent log that can be monitored and audited. This helps in detecting and responding to unauthorized or suspicious activities promptly.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The <code>AccessControlRegistry</code> implements several security measures to ensure the integrity and reliability of the access control system:</p> <p><strong>Admin-Only Restrictions</strong>: By limiting state-modifying functions to contract admins, the system prevents unauthorized users from making critical changes.</p> <p><strong>Active Contract Checks</strong>: Operations are restricted to active contracts, reducing the risk of interacting with deprecated or unregistered contracts.</p> <p><strong>Event Logging</strong>: Comprehensive event logging supports transparency and auditability, allowing for effective monitoring and detection of unauthorized actions.</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-18T00:00:00+00:00 2026-02-11T14:49:27+00:00 Hadrien Crouboishttps://github.com/amxx https://wg-eips.ritovision.com/7819/

Introduce a new instruction allowing contracts to create clones using EIP-7702 delegation designations

<h2 id="abstract">Abstract</h2> <p>Introduce a new instruction that allows smart contracts to create (and update) delegation accounts that match <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>'s design. These accounts can be used similarly to <a href="https://wg-eips.ritovision.com/1167/">ERC-1167</a> clones, with significant advantages.</p> <h2 id="motivation">Motivation</h2> <p>Many on-chain applications involve creating multiple instances of the same code at different locations. These applications often rely on clones, or proxies, to reduce deployment costs.</p> <p>Clones, such as the one described in ERC-1167 are minimal pieces of code that contain the target address directly in the code. That makes them extremely light but prevents any form of reconfiguration (upgradability).</p> <p>Upgradeable proxies differ from clones in that they read the implementation's address from storage. This makes them more versatile but also more expensive to use.</p> <p>In both cases delegating the received calls to an implementation using EVM code comes with some downsides:</p> <ul> <li>Calldata must be copied to memory before performing the delegate call</li> <li>If EOF is enabled, clones and proxy written in EOF do not support delegation to an implementation written in legacy EVM code, and are thus limited or possibly dangerous. This encourages the continued use of legacy EVM code.</li> </ul> <p>EIP-7702 introduces a new type of object that has the expected behavior: delegation indicator. These objects are designed to be instantiated at the address of EOA's, but the same behavior could be re-used to implement clones at the protocol level. Using delegation indicators for this use-case provides upgradeability without the need for storage lookups if the contract calling the <code>SETDELEGATE</code> allows it. It also removes any issue related to code version incompatibilities.</p> <h3 id="account-abstraction">Account abstraction</h3> <p>Smart accounts, as in contracts that are "owned" by one or multiple keys and are intended to replace EOAs, are often deployed using clones or proxies that point to a singleton implementation. This forces a choice between having an upgradeable or a non-upgradeable design. Both designs come with downsides. Non-upgradeable design can leave you stranded with a buggy (or limited) account code. Upgradeable design comes with costs associated with fetching the implementation address.</p> <p>The <code>SETDELEGATE</code> instruction would enable new factories to implement an upgradeable design without the added cost of the lookup. Factories could also deploy non-upgradeable variants, or even selectively disable the upgradeability of some accounts. Both the upgrade mechanism and the selective locking would be handled at the factory level, which removes the burden of implementing the upgrade logic into the account itself.</p> <p>Additionally, using EIP-7702 delegations instead of clones/proxies moves the call redirection logic from the userspace to the protocol. This means fewer EVM operations, and thus a reduced gas consumption of every operation that calls these contracts. This includes the verification of signatures and the execution of user operations, but also transfers of assets that include a callback, such as <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> tokens.</p> <h3 id="scalability">Scalability</h3> <p>Clones and proxy contracts are present in large numbers in the blockchain state. OpenZeppelin's <a href="https://wg-eips.ritovision.com/1967/">ERC-1967</a> proxies are ~708 bytes. Using EIP-7702 delegations that are only 23 bytes would reduce blockchain state usage.</p> <p>Additionally, clones and proxy contracts have to handle the redirection of the call in the userspace, which includes execution cost. Using EIP-7702 delegations, which would move the redirection to the protocol level, would reduce the gas cost of all operations that target. This means more gas / blockspace is available for the actual execution of the contracts.</p> <h2 id="specification">Specification</h2> <p>A new instruction (<code>SETDELEGATE</code>) is added at <code>0xf6</code>.</p> <h3 id="behavior">Behavior</h3> <p>Executing this instruction does the following:</p> <ol> <li>deduct <code>EMPTY_ACCOUNT_COST</code> gas</li> <li>halt if the current frame is in <code>static-mode</code></li> <li>pop <code>salt</code>, <code>target</code> from the operand stack</li> <li>calculate <code>location</code> as <code>keccak256(DESIGNATOR ++ address ++ salt)[12:]</code></li> <li>add <code>location</code> to <code>accessed_addresses</code>, as defined in <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a></li> <li>halt if the code at <code>location</code> is not empty and does not start with <code>0xEF0100</code> (no empty and not a delegation indicator)</li> <li>add <code>EMPTY_ACCOUNT_COST - BASE_COST</code> gas to the global refund counter if <code>location</code> exists in the trie</li> <li>set the code of <code>location</code> to be <code>DESIGNATOR ++ target</code>, matching the delegation process defined in EIP-7702 <ul> <li>Similarly to EIP-7702, if <code>target</code> is <code>0x0</code> do not write the designation. Clear the code at <code>location</code> and reset the <code>location</code>'s code hash to the empty hash <code>0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470</code>.</li> </ul> </li> <li>if the nonce of the account at <code>location</code> is 0, increment it to 1</li> <li>push <code>location</code> onto the stack</li> </ol> <p>On step 8, <code>target</code> MUST be exactly 20 bytes. If the value retrieved from the stack is smaller than 20 bytes, it MUST be left fill (big-endian notation) with zeros. If it is bigger than 20 bytes, it must be trimmed of the highest bytes. The code placed at <code>location</code> MUST be exactly 23 bytes long, following EIP-7702.</p> <p>The delegation indicator created at <code>location</code> behaves identically to those created by EIP-7702.</p> <p>Note: The delegation is effective immediately upon the completion of the operation. Calls to the address as soon as the next operation will execute the newly delegated code.</p> <p>The delegation indicators created by the <code>SETDELEGATE</code> opcode are the same objects as the one created using EIP-7702. Therefore, all the behavior specificities documented in EIP-7702 (<code>CODESIZE</code>, <code>CODECOPY</code>, targeting precompile, or chaining delegation indicator) also apply here. Any future EIP that modify the behavior of EIP-7702 delegation indicators should also apply to the delegation indicators created using <code>SETDELEGATE</code>. They are not contracts, and cannot be deleted using <code>SELFDESTRUCT</code>, even if the <code>SELFDESTRUCT</code> appens in the same transaction that created the account at <code>location</code>. Destruction of the delegations SHOULD only be possible by the same caller (that created them) doing a new <code>SETDELEGATE</code> call with the same salt and a zero target.</p> <p>Step 9 ensures that an account that was created using <code>SETDELEGATE</code> never returns to an empty state (forbiden by <a href="https://wg-eips.ritovision.com/7523/">EIP-7523</a>). Even if the balance is zero, no state was ever set, and the code is removed by a <code>SETDELEGATE</code> operation (with zero target), then the nonce being (at least) one would guarantee the account is not empty.</p> <h3 id="parameters">Parameters</h3> <p>These parameters are the same ones as used in EIP-7702.</p> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>DESIGNATOR</code></td><td>0xef0100</td></tr> <tr><td><code>EMPTY_ACCOUNT_COST</code></td><td>25000</td></tr> <tr><td><code>BASE_COST</code></td><td>12500</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <h3 id="gas-cost">Gas cost</h3> <p>The execution of the <code>SETDELEGATE</code> instruction involves fewer moving pieces than what EIP-7702 gas costs account for:</p> <ul> <li>there is no signature recovery</li> <li>there is no dedicated calldata that must be accounted for that is not already paid for at the transaction level</li> <li>there is no nonce update</li> </ul> <p>Therefore, the cost of executing this instruction could be lower than EIP-7702. Numbers from EIP-7702 are reused for simplicity. They are lower than <code>CREATE</code> or <code>CREATE2</code> operations, making the use of this instruction competitive for the intended use-cases.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <h3 id="address-collision">Address collision</h3> <p>The derivation of the <code>location</code> is designed not to conflict with contracts created using the <code>CREATE</code> or <code>CREATE2</code> opcodes. In particular, the pre-images used to hash the produced address have different lengths, preventing any collision:</p> <p>Contracts deployed using <code>CREATE2</code> have an address that is derived from a 85 bytes long pre-image, as opposed to 55 bytes for <code>SET_DELEGATE</code>. This observation alone remove the risk of pre-image collision.</p> <p>Contracts deployed using <code>CREATE</code> have an address that is derived from the <code>RLP([address, nonce])</code>. For this pre-image to have a length 55 (like <code>SET_DELEGATE</code>), <code>nonce</code> must be 32 bytes long. In that case, the <code>RLP([address, nonce])</code> would be <code>0xf694&lt;address&gt;a0&lt;nonce&gt;</code> and would thus not start with the magic value used by <code>SETDELEGATE</code>. A smaller nonce could lead to the pre-image starting with <code>0xef</code>, but in that case the pre-image would be smaller than 55 bytes. Even in that case, the pre-image would start with <code>0xef94</code>, <code>0x94</code> encoding the <code>address</code> object (that is 20 bytes long).</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="delegator-upgrades-deletion">Delegator upgrades &amp; deletion</h3> <p>Reusing EIP-7702 behavior, including clearing the code if the target is 0, results in the ability to upgrade or even "remove" the created designator. This process is controlled (and can be restricted) by the factory (the contract that calls <code>SETDELEGATE</code>). Some factories will add checks that prevent re-executing <code>SETDELEGATE</code> with a salt that was already used, making the create designator immutable. Others may allow access-restricted upgrades, but prevent deletion. In any case, guarantees about the lifecycle of the designator created using <code>SETDELEGATE</code> are provided by the contracts that call it and not by the protocol.</p> <h3 id="delegator-chaining">Delegator chaining</h3> <p>As documented in EIP-7702, designator chains or loops are not resolved. This means that, unlike clones, chaining is an issue. This is however something developers are used to, as chaining proxy can result in strange behaviors, including infinite delegation loops.</p> <p>Factories may want to protect against this risk by verifying that the <code>target</code> doesn't contain a designator. This can be achieved using a legacy contract helper that has access to <code>EXTCODEHASH</code>. It could also be done using other forms of introspection such as an <code>ACCOUNT_TYPE</code> instruction.</p> <h3 id="front-running-initialization">Front running initialization</h3> <p>Unlike EIP-7702 signature, which can be included in any transaction, and can thus lead to initialization front-running if the implementation doesn't check the authenticity of the initialization parameters, <code>CREATE_DELEGATE</code> is executed by a smart contract that can execute the initialization logic atomically, just after the delegation is created. This process is well-known to developers that initialize clones and proxies just after creation.</p> <h3 id="multiple-delegation-changes-within-a-single-transaction">Multiple delegation changes within a single transaction.</h3> <p>If a contract performs multiple <code>SETDELEGATE</code> operations with the same salt but different targets within the same transaction, while doing calls corresponding address, this would have, in the same transaction without reverts, an address that has multiple different codes associated with it, two or more of which are executed. This include the delegation being removed/reset any number of time during the transaction.</p> <p>This behavior, is already possible with more traditional upgradeable contracts, where change of target are caused by a specific storage slot being modified.</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-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 sirawthttps://github.com/MASDXI ADISAKBOONMARKhttps://github.com/ADISAKBOONMARK https://wg-eips.ritovision.com/7818/

An ERC-20 extension for creating fungible tokens with expiration, supporting time-limited use cases.

<h2 id="abstract">Abstract</h2> <p>Introduces an extension for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens, which facilitates the implementation of an expiration mechanism. Through this extension, tokens have a predetermined validity period, after which they become invalid and can no longer be transferred or used. This functionality proves beneficial in scenarios such as time-limited bonds, loyalty rewards, or game tokens necessitating automatic invalidation after a specific duration. The extension is crafted to seamlessly align with the existing <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard, ensuring smooth integration with the prevailing token smart contract while introducing the capability to govern and enforce token expiration at the contract level.</p> <h2 id="motivation">Motivation</h2> <p>This extension facilitates the development of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard compatible tokens featuring expiration dates. This capability broadens the scope of potential applications, particularly those involving time-sensitive assets. Expirable tokens are well-suited for scenarios necessitating temporary validity, including:</p> <ul> <li>Bonds or financial instruments with defined maturity dates</li> <li>Time-constrained assets within gaming ecosystems</li> <li>Next-gen loyalty programs incorporating expiring rewards or points</li> <li>Prepaid credits for utilities or services (e.g., cashback, data packages, fuel, computing resources) that expire if not used within a specified time frame</li> <li>Postpaid telecom data package allocations that expire at the end of the billing cycle, motivating users to utilize their data before it resets</li> <li>Tokenized e-Money for a closed-loop ecosystem, such as transportation, food court, and retail payments</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> <h3 id="epoch-mechanism">Epoch Mechanism</h3> <p><strong>Epochs</strong> represent a specific period or block range during which certain tokens are valid. They can be categorized into two types</p> <ul> <li><strong>block-based</strong> Defined by a specific number of blocks (e.g., 1000 <code>blocks</code>).</li> <li><strong>time-based</strong> Defined by a specific duration in seconds (e.g., 1000 <code>seconds</code>).</li> </ul> <p>Tokens linked to an <code>epoch</code> remain valid as long as the <code>epoch</code> is active. Once the specified number of <code>blocks</code> or the duration in <code>seconds</code> has passed, the <code>epoch</code> expires, and any tokens associated with it are considered expired.</p> <h3 id="balance-look-back-over-epochs">Balance Look Back Over Epochs</h3> <p>To retrieve the usable balance, tokens are checked from the <strong>current epoch</strong> against a <strong>past epoch</strong> (which can be any <em><strong>n</strong></em> epochs back). The past epoch can be set to any value <em><strong>n</strong></em>, allowing flexibility in tracking and summing tokens that are still valid from previous epochs, up to <em><strong>n</strong></em> epochs back.</p> <p>The usable balance is the sum of tokens valid between the <strong>current epoch</strong> and the <strong>past epoch</strong>, ensuring that only non-expired tokens are considered.</p> <h4 id="example-scenario">Example Scenario</h4> <table><thead><tr><th><strong>epoch</strong></th><th><strong>balance</strong></th></tr></thead><tbody> <tr><td>1</td><td>100</td></tr> <tr><td>2</td><td>150</td></tr> <tr><td>3</td><td>200</td></tr> </tbody></table> <ul> <li><strong>Current Epoch</strong>: 3</li> <li><strong>Past Epoch</strong>: 1 epoch back</li> <li><strong>Usable Balance</strong>: 350</li> </ul> <p>Tokens from <strong>Epoch 2</strong> and <strong>Epoch 3</strong> are valid. The same logic applies for any <em><strong>n</strong></em> epochs back, where the usable balance includes tokens from the current epoch and all prior valid epochs.</p> <p>Compatible implementations <strong>MUST</strong> inherit from <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>'s interface and <strong>MUST</strong> have all the following functions and all function behavior <strong>MUST</strong> meet the specification.</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"> &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-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-7818 interface</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 adding expirable functionality to ERC20 tokens.</span></span> <span class="giallo-l"><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;./IERC20.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"> IERC7818</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Enum represents the types of `epoch` that can be used.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> The implementing contract may use one of these types to define how the `epoch` is measured.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> EPOCH_TYPE</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> BLOCKS_BASED</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> measured in the number of blocks (e.g., 1000 blocks)</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> TIME_BASED</span><span class="z-comment"> //</span><span class="z-comment"> measured in seconds (UNIX time) (e.g., 1000 seconds)</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"> Retrieves the balance of a specific `epoch` owned by an 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"> epoch</span><span class="z-comment"> The `epoch for which the balance is checked.</span></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 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"> uint256</span><span class="z-comment"> The balance of the specified `epoch`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> &quot;MUST&quot; return 0 if the specified `epoch` is expired.</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"> balanceOfAtEpoch</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"> address</span><span class="z-variable"> account</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">@dev</span><span class="z-comment"> Retrieves the latest epoch currently tracked by 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"> uint256</span><span class="z-comment"> The latest epoch of 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"> currentEpoch</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">@dev</span><span class="z-comment"> Retrieves the duration of a single epoch.</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 duration of a single epoch.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> The unit of the epoch length is determined by the `validityPeriodType` function.</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"> epochLength</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">@dev</span><span class="z-comment"> Returns the type of the epoch.</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"> EPOCH_TYPE</span><span class="z-comment"> Enum value indicating the unit of an epoch.</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"> epochType</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-storage z-type">EPOCH_TYPE</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">@dev</span><span class="z-comment"> Retrieves the validity duration in `epoch` counts.</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 validity duration in `epoch` counts.</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"> validityDuration</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">@dev</span><span class="z-comment"> Checks whether a specific `epoch` 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"> epoch</span><span class="z-comment"> The `epoch` to check.</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"> True if the token is expired, false otherwise.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Implementing contracts &quot;MUST&quot; define and document the logic for determining expiration,</span></span> <span class="giallo-l"><span class="z-comment"> * typically by comparing the latest epoch with the given `epoch` value,</span></span> <span class="giallo-l"><span class="z-comment"> * based on the `EPOCH_TYPE` measurement (e.g., block count or time duration).</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"> isEpochExpired</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> epoch</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"> Transfers a specific `epoch` and value to a 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"> epoch</span><span class="z-comment"> The `epoch` for the 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"> to</span><span class="z-comment"> The recipient 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"> value</span><span class="z-comment"> The amount to transfer.</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"> True if the transfer succeeded, otherwise 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"> transferAtEpoch</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"> 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 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">@dev</span><span class="z-comment"> Transfers a specific `epoch` and value from one account to another.</span></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"> The `epoch` for the 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"> from</span><span class="z-comment"> The sender&#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"> to</span><span class="z-comment"> The recipient&#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"> value</span><span class="z-comment"> The amount to transfer.</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"> True if the transfer succeeded, otherwise 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"> transferFromAtEpoch</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"> 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"> value</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></span></code></pre><h3 id="behavior-specification">Behavior Specification</h3> <ul> <li><code>balanceOf</code> <strong>MUST</strong> return the total balance of tokens held by an account that are still valid (i.e., have not expired). This includes any tokens associated with specific epochs, provided they remain within their validity duration. Expired tokens <strong>MUST NOT</strong> be included in the returned balance, ensuring that only actively usable tokens are reflected in the result.</li> <li><code>balanceOfAtEpoch</code> <strong>MUST</strong> return the balance of tokens held by an account at the specified <code>epoch</code>. If the specified epoch is expired, this function <strong>MUST</strong> return <code>0</code>. For example, if <code>epoch</code> 5 has expired, calling <code>balanceOfByEpoch(5, address)</code> returns <code>0</code> even if there were tokens previously held in that epoch.</li> <li><code>currentEpoch</code> <strong>MUST</strong> return the current <code>epoch</code> of the contract.</li> <li><code>epochLength</code> <strong>MUST</strong> return duration between <code>epoch</code> in blocks or time in seconds.</li> <li><code>epochType</code> <strong>MUST</strong> return the type of epoch used by the contract, which can be either <code>BLOCKS_BASED</code> or <code>TIME_BASED</code>.</li> <li><code>validityDuration</code> <strong>MUST</strong> return the validity duration of tokens in terms of <code>epoch</code> counts.</li> <li><code>isEpochExpired</code> <strong>MUST</strong> return true if the given <code>epoch</code> is expired, otherwise <code>false</code>.</li> <li><code>transfer</code> and <code>transferFrom</code> <strong>MUST</strong> exclusively transfer tokens that remain non-expired at the time of the transaction. Attempting to transfer expired tokens <strong>MUST</strong> revert the transaction or return <code>false</code>. Additionally, implementations <strong>MAY</strong> include logic to prioritize the automatic transfer of tokens closest to expiration, ensuring that the earliest expiring tokens are used first, provided they meet the non-expired condition.</li> <li><code>transferAtEpoch</code> and <code>transferFromAtEpoch</code> <strong>MUST</strong> transfer the specified number of tokens held by an account at the specified epoch to the recipient, If the epoch has expired, the transaction <strong>MUST</strong> <code>revert</code> or return <code>false</code></li> <li><code>totalSupply</code> <strong>SHOULD</strong> be set to <code>0</code> or <code>type(uint256).max</code> due to the challenges of tracking only valid (non-expired) tokens.</li> <li>The implementation <strong>MAY</strong> use a standardized custom error, such as <code>ERC7818TransferredExpiredToken</code> or <code>ERC7818TransferredExpiredToken(address sender, uint256 epoch)</code>, to clearly indicate that the operation failed due to attempting to transfer expired tokens.</li> </ul> <h3 id="additional-potential-useful-function">Additional Potential Useful Function</h3> <p>These <strong>OPTIONAL</strong> functions provide additional functionality that might be useful depending on the specific use case.</p> <ul> <li><code>getEpochBalance</code> returns the amount of tokens stored in a given <code>epoch</code>, even if the <code>epoch</code> has expired.</li> <li><code>getEpochInfo</code> returns both the start and end of the specified <code>epoch</code>.</li> <li><code>getNearestExpiryOf</code> returns the token amount closest to expiration, along with an estimated expiration block number or timestamp based on <code>epochType</code>.</li> <li><code>getRemainingDurationBeforeEpochChange</code> returns the remaining time or blocks before the <code>epoch</code> change happens, based on the <code>epochType</code>.</li> </ul> <h2 id="rationale">Rationale</h2> <p>Although the term <code>epoch</code> is an abstract concept, it leaves room for various implementations. For example, epochs can support more granular tracking of tokens within each epoch, allowing for greater control over when tokens are valid or expired on-chain. Alternatively, epochs can support bulk expiration, where all tokens within the same epoch expire simultaneously. This flexibility enables different methods of tracking token expiration, depending on the specific needs of the use case. <code>epoch</code> also introduces a "lazy" way to simplify token expiration tracking in a flexible and gas-efficient manner. Instead of continuously updating the expiration state with <code>write</code> operations by the user or additional services, the current epoch can be calculated using a <code>read</code> operation.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is fully <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> compatible.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>For reference implementation can be found <a href="https://wg-eips.ritovision.com/7818/assets/README/">here</a>, But in the reference implementation, we employ a sorted list to automatically select the token that nearest expires first with a First-In-First-Out (<code>FIFO</code>) and sliding window algorithm that operates based on the <code>block.number</code> as opposed to relying on <code>block.timestamp</code>, which has been criticized for its lack of security and resilience, particularly given the increasing usage of Layer 2 (L2) networks over Layer 1 (L1) networks. Many L2 networks exhibit centralization and instability, which directly impacts asset integrity, rendering them potentially unusable during periods of network halting, as they are still reliant on the timestamp.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="denial-of-service">Denial Of Service</h3> <p>Run out of gas problem due to the operation consuming higher gas if transferring multiple groups of small tokens or loop transfer.</p> <h3 id="gas-limit-vulnerabilities">Gas Limit Vulnerabilities</h3> <p>Exceeds block gas limit if the blockchain has a block gas limit lower than the gas used in the transaction.</p> <h3 id="block-values-as-a-proxy-for-time">Block values as a proxy for time</h3> <p>if using <code>block.timestamp</code> for calculating <code>epoch</code> and In rare network halts, block production stops, freezing <code>block.timestamp</code> and disrupting time-based logic. This risks asset integrity and inconsistent states.</p> <h3 id="fairness-concerns">Fairness Concerns</h3> <p>In a straightforward implementation, where all tokens within the same epoch share the same expiration (e.g., at <code>epoch</code>:<code>x</code>), bulk expiration occurs.</p> <h3 id="risks-in-liquidity-pools">Risks in Liquidity Pools</h3> <p>When tokens with expiration dates are deposited into liquidity pools (e.g., in DEXs), they may expire while still in the pool.</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-11T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic Radoslaw Zagorowiczhttps://github.com/rodiazet https://wg-eips.ritovision.com/7823/

Each input field is restricted to a maximum of 8192 bits

<h2 id="abstract">Abstract</h2> <p>Introduce an upper bound on the inputs of the MODEXP precompile. This can reduce the number of potential bugs, because the testing surface is not infinite anymore, and makes it easier to be replaced using EVMMAX.</p> <h2 id="motivation">Motivation</h2> <p>The MODEXP precompile has been a source of numerous consensus bugs. Many of them were due to specifically crafted cases using impractical input lengths.</p> <p>Its pricing function is also quite complex given its nature of unbounded inputs. While we don't suggest to rework the pricing function, it may be possible in a future upgrade once the limits are in place.</p> <p>Furthermore this limitation makes it more feasible to have the precompile replaced with EVM code through features like EVMMAX.</p> <h2 id="specification">Specification</h2> <p>Recap from <a href="https://wg-eips.ritovision.com/198/">EIP-198</a>:</p> <blockquote> <p>At address <code>0x00……05</code>, add a precompile that expects input in the following format:</p> <p><code>&lt;length_of_BASE&gt; &lt;length_of_EXPONENT&gt; &lt;length_of_MODULUS&gt; &lt;BASE&gt; &lt;EXPONENT&gt; &lt;MODULUS&gt;</code></p> </blockquote> <p>We introduce an upper bound to the inputs of the precompile, each of the length inputs (<code>length_of_BASE</code>, <code>length_of_EXPONENT</code> and <code>length_of_MODULUS</code>) MUST be less than or equal to 8192 bits (1024 bytes).</p> <p>If any of these inputs are larger than the limit, the precompile execution stops, returns an error, and consumes all gas.</p> <h2 id="rationale">Rationale</h2> <h3 id="limit">Limit</h3> <p>This upper bound allows the existing use cases of MODEXP:</p> <ol> <li>RSA verification with up to 8192 bit keys. Commonly used ones are 1024/2048/4096 bits.</li> <li>Elliptic curve related use cases are usually less than 384 bits.</li> </ol> <h3 id="evmmax">EVMMAX</h3> <p>Replacing the precompile with EVM code using an instruction set like EVMMAX would be made simpler with this limit: Common cases (256, 381, 1024, 2048) could be implemented in special fast paths, while a slow fallback could be provided for the rest. Or even special, frequently used, moduli could have their own paths.</p> <p>Furthermore one could consider limiting the lengths to certain inputs only.</p> <h3 id="analysis">Analysis</h3> <p>Since MODEXP was introduced in the Byzantium hard fork, an analysis has been conducted between block 5472266 (April 20, 2018) and block 21550926 (January 4th, 2025). All lengths of inputs are expressed in bytes.</p> <h4 id="base-length-occurrences">Base length occurrences</h4> <table><thead><tr><th><code>input_of_BASE</code></th><th>count</th></tr></thead><tbody> <tr><td>32</td><td>2439595</td></tr> <tr><td>128</td><td>4167</td></tr> <tr><td>256</td><td>2969</td></tr> <tr><td>160</td><td>436</td></tr> <tr><td>512</td><td>36</td></tr> <tr><td>0</td><td>13</td></tr> <tr><td>64</td><td>7</td></tr> <tr><td>78</td><td>2</td></tr> <tr><td>513</td><td>2</td></tr> <tr><td>129</td><td>1</td></tr> <tr><td>385</td><td>1</td></tr> </tbody></table> <h4 id="exponent-length-occurrences">Exponent length occurrences</h4> <table><thead><tr><th><code>input_of_EXPONENT</code></th><th>count</th></tr></thead><tbody> <tr><td>32</td><td>2442255</td></tr> <tr><td>3</td><td>4771</td></tr> <tr><td>1</td><td>159</td></tr> <tr><td>128</td><td>29</td></tr> <tr><td>0</td><td>13</td></tr> <tr><td>5</td><td>2</td></tr> </tbody></table> <h4 id="modulo-length-occurrences">Modulo length occurrences</h4> <table><thead><tr><th><code>input_of_MODULUS</code></th><th>count</th></tr></thead><tbody> <tr><td>32</td><td>2439594</td></tr> <tr><td>128</td><td>4167</td></tr> <tr><td>256</td><td>2968</td></tr> <tr><td>160</td><td>436</td></tr> <tr><td>512</td><td>38</td></tr> <tr><td>0</td><td>13</td></tr> <tr><td>64</td><td>8</td></tr> <tr><td>78</td><td>2</td></tr> <tr><td>129</td><td>1</td></tr> <tr><td>384</td><td>1</td></tr> <tr><td>257</td><td>1</td></tr> </tbody></table> <p>This shows that no past successful use case exceeded an input length of 513 bytes, and the majority uses 32/128/256 byte inputs.</p> <p>Besides these, there were a few invocations with invalid inputs:</p> <ul> <li>Empty inputs</li> <li>Inputs consisting of only <code>0x9e5faafc</code> or <code>0x85474728</code></li> <li>A large, but invalid input: <code>0x9e281a98000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000021e19e0c9bab2400000</code></li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backwards incompatible change. However, based on analysis until block 21550926 (see above), no past transaction would have behaved differently after this change.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Since only the accepted input range is reduced, no new security surface area is 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> 2024-11-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Artem Chystiakovhttps://github.com/arvolearartem@rarilabs.com Oleksandr Kurbatovoleksandr@rarilabs.com Yaroslav Panasenkoyaroslav@rarilabs.com Michael Elliothttps://github.com/michaelelliotmike@zkpassport.id Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/7812/

Singleton registry system for storing abstract private provable statements.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces an on-chain registry system for storing and proving abstract statements. Users may utilize the system to store commitments to their private data to later prove its validity and authenticity via zero knowledge, without disclosing anything about the data itself. Moreover, developers may use the singleton <code>EvidenceRegistry</code> contract available at <code>0x781246D2256dc0C1d8357c9dDc1eEe926a9c7812</code> to integrate custom business-specific registrars for managing and processing particular statements.</p> <h2 id="motivation">Motivation</h2> <p>This EIP stemmed from the need to localize and unravel the storage and issuance of provable statements so that future protocols can anchor to the standardized singleton on-chain registry and benefit from cross-reuse.</p> <p>The aggregation of provable statements significantly improves reusability, portability, and security of the abundance of zero knowledge privacy-oriented solutions. The abstract specification of the registry allows custom indentity-based, reputation-based, proof-of-attendance-based, etc., protocols to be implemented with little to minimal constraints.</p> <p>The given proposal lays the important foundation for specific solution to build upon. The more concrete specifications of statements and commitments structures are expected to emerge as separate, standalone EIPs.</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="definitions">Definitions</h3> <ul> <li>A "Sparse Merkle Tree (SMT)" is a special Merkle tree that works by deterministically and idempotently storing key/value pairs in the given locations leveraging a hash function. The Poseidon hash function is often used to optimize the compatibility with ZK.</li> <li>A "statement" is an accepted structured representation of some abstract evidence. A statement can range from a simple <code>string</code> to a Merkle root of some SMT.</li> <li>A "commitment" is a special public value resulting from blinding a statement to conceal it. Commitments allow the authenticity of a statement to be proven in ZK without disclosing the statement itself.</li> <li>A "commitment key" is a private salt mixed with the statement to obtain a commitment to that statement. The commitment key must be kept private to maintain the confidentiality of statements.</li> </ul> <h3 id="general">General</h3> <p>The on-chain registry system consists of two subsystems: the <code>EvidenceRegistry</code> with <code>EvidenceDB</code> and <code>Registrar</code> components. This EIP will focus on describing and standardizing the former, while the <code>Registrar</code> specification may be amended as the separate proposals.</p> <p><img src="https://wg-eips.ritovision.com/7812/./assets/images/diagram.png" alt="The on-chain evidence registry system entities diagram." /></p> <p>The on-chain evidence registry system entities diagram.</p> <p>The <code>EvidenceRegistry</code> acts as the entrypoint to a protocol-wide provable database <code>EvidenceDB</code> where arbitrary <code>32-byte</code> data can be written to and later proven on demand. The <code>Registrar</code> entities implement specific business use cases, structure the provable data, and utilize <code>EvidenceRegistry</code> to put this data in the <code>EvidenceDB</code>.</p> <p>In order to prove that certain data is or is not present in the <code>EvidenceDB</code> Merkle proofs may be used. Understanding how a specific <code>Registrar</code> has structured and put data into the <code>EvidenceDB</code>, one may implement an on-chain ZK verifier (using Circom or any other stack) and prove the inclusion (or exclusion) of the data in the database.</p> <p>The Circom implementation of a general-purpose SMT-driven <code>EvidenceDB</code> verifier circuit together with the Solidity implementation of <code>EvidenceRegistry</code> and <code>EvidenceDB</code> smart contracts may be found in the "Reference Implementation" section.</p> <h3 id="evidence-db">Evidence DB</h3> <p>The <code>EvidenceDB</code> smart contract MAY implement an arbitrary provable key/value data structure, however it MUST support the <code>addition</code>, <code>update</code>, and <code>removal</code> of elements. All of the supported write operations MUST maintain the property of idempotence (e.i. <code>addition</code> followed by <code>removal</code> should not change the state of the database). The data structure of choice MUST be capable of providing both element inclusion and exclusion proofs. The functions that modify the <code>EvidenceDB</code> state MUST be callable only by the <code>EvidenceRegistry</code>.</p> <p>For reference, the <code>EvidenceDB</code> smart contract MAY implement the following 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-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Evidence DB interface for Sparse Merkle Tree based statements database.</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"> IEvidenceDB</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"> Represents the proof of a node&#39;s inclusion/exclusion in the tree.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> root</span><span class="z-comment"> The root hash of the Merkle tree.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> siblings</span><span class="z-comment"> An array of sibling hashes can be used to get the Merkle Root.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> existence</span><span class="z-comment"> Indicates the presence (true) or absence (false) of the 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"> key</span><span class="z-comment"> The key associated with the 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"> value</span><span class="z-comment"> The value associated with the 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"> auxExistence</span><span class="z-comment"> Indicates the presence (true) or absence (false) of an auxiliary 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"> auxKey</span><span class="z-comment"> The key of the auxiliary 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"> auxValue</span><span class="z-comment"> The value of the auxiliary node.</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"> Proof</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> root</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span> siblings</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> existence</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> value</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> auxExistence</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> auxKey</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> auxValue</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">@notice</span><span class="z-comment"> Adds the new element to the tree.</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"> add</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key</span><span>,</span><span class="z-support"> bytes32</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 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"> Removes the element from the tree.</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"> remove</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key</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"> Updates the element in the tree.</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"> update</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> newValue</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"> Gets the SMT root.</span></span> <span class="giallo-l"><span class="z-comment"> * SHOULD NOT be used on-chain due to roots frontrunning.</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"> getRoot</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Gets the number of nodes in the tree.</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"> getSize</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></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"> Gets the max tree height (number of branches in the Merkle proof)</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"> getMaxHeight</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"> Gets Merkle inclusion/exclusion proof of the element.</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"> getProof</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key</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">Proof</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Gets the element value by its key.</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"> getValue</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key</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><h3 id="evidence-registry">Evidence Registry</h3> <p>The <code>EvidenceRegistry</code> smart contract is the central piece of this EIP. The <code>EvidenceRegistry</code> MUST implement the following interface, however, it MAY be extended:</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Common Evidence Registry interface.</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"> IEvidenceRegistry</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"> MUST be emitted whenever the Merkle root is updated.</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"> RootUpdated</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> prev</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> curr</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"> Adds the new statement to the DB.</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"> addStatement</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key</span><span>,</span><span class="z-support"> bytes32</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 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"> Removes the statement from the DB.</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"> removeStatement</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key</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"> Updates the statement in the DB.</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"> updateStatement</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> newValue</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"> Retrieves historical DB roots creation timestamps.</span></span> <span class="giallo-l"><span class="z-comment"> * Latest root MUST return `block.timestamp`.</span></span> <span class="giallo-l"><span class="z-comment"> * Non-existent root MUST return `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"> getRootTimestamp</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> root</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"> Builds and returns the isolated key for `source` and given `key`.</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"> getIsolatedKey</span><span>(</span><span class="z-support">address</span><span class="z-variable"> source</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> key</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 <code>addStatement</code>, <code>removeStatement</code>, and <code>updateStatement</code> methods MUST isolate the statement <code>key</code> in order for the database to allocate a specific namespace for a caller. These methods MUST revert in case the isolated key being added already exists in the <code>EvidenceDB</code> or the isolated key being removed or updated does not.</p> <p>The <code>EvidenceRegistry</code> MUST maintain the linear history of <code>EvidenceDB</code> roots. The <code>getRootTimestamp</code> method MUST NOT revert. Instead, it MUST return <code>0</code> in case the queried <code>root</code> does not exist. The method MUST return <code>block.timestamp</code> in case the latest root is requested.</p> <p>Before communicating with the <code>EvidenceDB</code>, the <code>key</code> MUST be isolated in the following way:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes32</span><span> isolatedKey </span><span class="z-keyword">=</span><span class="z-entity z-name"> hash</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> key</span><span>)</span></span></code></pre> <p>Where the <code>hash</code> is secure protocol-wide hash function of choice.</p> <h3 id="hash-function">Hash Function</h3> <p>The same secure hash function MUST be employed in both <code>EvidenceRegistry</code> and <code>EvidenceDB</code>. It is RECOMMENDED to use ZK-friendly hash function such as <code>poseidon</code> to streamline the database proving.</p> <p>In case ZK-friendly hash function is chosen, <code>EvidenceRegistry</code> MUST NOT accept <code>keys</code> or <code>values</code> beyond the underlying elliptic curve prime field size (<code>21888242871839275222246405745257275088548364400416034343698204186575808495617</code> for <code>BN128</code>).</p> <h2 id="rationale">Rationale</h2> <p>During the EIP specification we have considered two approaches: where every protocol has its own registry and where all protocols are united under a singleton registry. We have decided to go with the latter as this approach provides the following benefits:</p> <ol> <li>Cross-chain portability. Only a single <code>bytes32</code> value (the SMT root) has to be sent cross-chain to be able to prove the state of the registry.</li> <li>Centralization of trust. Users only need to trust a single, permissionaless, immutable smart contract.</li> <li>Integration streamline. The singleton design formalizes the system interface, the hash function, and the overall proofs structure to simplify the integration.</li> </ol> <p>The proposal is deliberately written as abstract as possible to not constrain the possible business use cases and allow <code>Registrars</code> to implement arbitrary provable solutions.</p> <p>It is expected that based on this work future EIPs will describe concrete registrars with the exact procedures of generation of commitments, management of commitment keys, and proving of operated statements. For instance, there may be a registrar for on-chain accounting of national passports, a registrar with <a href="https://wg-eips.ritovision.com/4337/">EIP-4337</a> confidential account identity management, a registrar for POAPs, etc.</p> <p>The <code>EvidenceDB</code> namespacing is chosen to segregate the write access to the database cells, ensuring that no entity but issuer can alter their content. However, this decision delegates the access control management responsibility solely to registrars, an important aspect to be considered during their development.</p> <p>The <code>EvidenceRegistry</code> maintains the minimal viable (gas-wise) history of roots on-chain for smooth registrars integration. In case more elaborate history is required, it is RECOMMENDED to implement off-chain services for parsing of <code>RootUpdated</code> events.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible.</p> <h3 id="deployment-method">Deployment Method</h3> <p>The <code>EvidenceRegistry</code> is a singleton contract available at <code>0x781246D2256dc0C1d8357c9dDc1eEe926a9c7812</code> deployed via the "deterministic deployment proxy" from <code>0x4e59b44847b379578588920ca78fbf26c0b4956c</code> with the salt <code>0x04834e077c463de76a20df3770a7b96a5e5eb826922d1514f943cd5b41ccaed0</code>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation of <code>EvidenceRegistry</code> and <code>EvidenceDB</code> Solidity smart contracts together with the evidence registry state verifier Circom circuit is provided in the proposal.</p> <p>The low-level Solidity and Circom implementations of SMT can be found <a href="https://wg-eips.ritovision.com/7812/./assets/contracts/SparseMerkleTree.sol">here</a> and <a href="https://wg-eips.ritovision.com/7812/./assets/circuits/SparseMerkleTree.circom">here</a>.</p> <p>The height of the SMT is set to <code>80</code>.</p> <blockquote> <p>Please note that the reference implementation depends on the <code>@openzeppelin/contracts v5.1.0</code> and <code>circomlib v2.0.5</code>.</p> </blockquote> <h3 id="evidencedb-implementation">EvidenceDB Implementation</h3> <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.21</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Initializable</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/proxy/utils/Initializable.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IEvidenceDB</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./interfaces/IEvidenceDB.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">SparseMerkleTree</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./libraries/SparseMerkleTree.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">PoseidonUnit2L</span><span>, </span><span class="z-entity z-name">PoseidonUnit3L</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./libraries/Poseidon.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"> EvidenceDB</span><span class="z-storage"> is</span><span class="z-entity z-name"> IEvidenceDB</span><span>, </span><span class="z-entity z-name">Initializable</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> SparseMerkleTree</span><span class="z-keyword"> for</span><span class="z-entity z-name"> SparseMerkleTree</span><span>.</span><span>SMT</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> _evidenceRegistry</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> SparseMerkleTree</span><span>.</span><span>SMT </span><span class="z-storage z-type">private</span><span> _tree</span><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"> onlyEvidenceRegistry</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _requireEvidenceRegistry</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"> __EvidenceDB_init</span><span>(</span><span class="z-support">address</span><span class="z-variable"> evidenceRegistry_</span><span>,</span><span class="z-support"> uint32</span><span class="z-variable"> maxDepth_</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> initializer</span><span> {</span></span> <span class="giallo-l"><span> _evidenceRegistry </span><span class="z-keyword">=</span><span> evidenceRegistry_</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _tree</span><span>.</span><span class="z-entity z-name">initialize</span><span>(</span><span>maxDepth_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _tree</span><span>.</span><span class="z-entity z-name">setHashers</span><span>(</span><span>_hash2</span><span>,</span><span> _hash3</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">@inheritdoc</span><span class="z-comment"> IEvidenceDB</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"> add</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key_</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> value_</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyEvidenceRegistry</span><span> {</span></span> <span class="giallo-l"><span> _tree</span><span>.</span><span class="z-entity z-name">add</span><span>(</span><span>key_</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@inheritdoc</span><span class="z-comment"> IEvidenceDB</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"> remove</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key_</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyEvidenceRegistry</span><span> {</span></span> <span class="giallo-l"><span> _tree</span><span>.</span><span class="z-entity z-name">remove</span><span>(</span><span>key_</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">@inheritdoc</span><span class="z-comment"> IEvidenceDB</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"> update</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key_</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> newValue_</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyEvidenceRegistry</span><span> {</span></span> <span class="giallo-l"><span> _tree</span><span>.</span><span class="z-entity z-name">update</span><span>(</span><span>key_</span><span>,</span><span> newValue_</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">@inheritdoc</span><span class="z-comment"> IEvidenceDB</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"> getRoot</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 class="z-keyword"> return</span><span> _tree</span><span>.</span><span class="z-entity z-name">getRoot</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">@inheritdoc</span><span class="z-comment"> IEvidenceDB</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"> getSize</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> _tree</span><span>.</span><span class="z-entity z-name">getNodesCount</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">@inheritdoc</span><span class="z-comment"> IEvidenceDB</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"> getMaxHeight</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> _tree</span><span>.</span><span class="z-entity z-name">getMaxDepth</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">@inheritdoc</span><span class="z-comment"> IEvidenceDB</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"> getProof</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key_</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">Proof</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> _tree</span><span>.</span><span class="z-entity z-name">getProof</span><span>(</span><span>key_</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">@inheritdoc</span><span class="z-comment"> IEvidenceDB</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"> getValue</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key_</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"> return</span><span> _tree</span><span>.</span><span class="z-entity z-name">getNodeByKey</span><span>(</span><span>key_</span><span>)</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns the address of the Evidence Registry.</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"> getEvidenceRegistry</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> _evidenceRegistry</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"> _requireEvidenceRegistry</span><span>(</span><span>)</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> view</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_evidenceRegistry </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-keyword"> revert</span><span class="z-entity z-name"> NotFromEvidenceRegistry</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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _hash2</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> element1_</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> element2_</span><span>)</span><span class="z-storage z-type"> private</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> PoseidonUnit2L</span><span>.</span><span class="z-entity z-name">poseidon</span><span>(</span><span>[</span><span>element1_</span><span>,</span><span> element2_</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"> _hash3</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> element1_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> element2_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> element3_</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> private</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> PoseidonUnit3L</span><span>.</span><span class="z-entity z-name">poseidon</span><span>(</span><span>[</span><span>element1_</span><span>,</span><span> element2_</span><span>,</span><span> element3_</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="evidenceregistry-implementation">EvidenceRegistry Implementation</h3> <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.21</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Initializable</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/proxy/utils/Initializable.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IEvidenceDB</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./interfaces/IEvidenceDB.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IEvidenceRegistry</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./interfaces/IEvidenceRegistry.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">PoseidonUnit2L</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./libraries/Poseidon.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"> EvidenceRegistry</span><span class="z-storage"> is</span><span class="z-entity z-name"> IEvidenceRegistry</span><span>, </span><span class="z-entity z-name">Initializable</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> BABY_JUB_JUB_PRIME_FIELD </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-constant"> 21888242871839275222246405745257275088548364400416034343698204186575808495617</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> IEvidenceDB </span><span class="z-storage z-type">private</span><span> _evidenceDB</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-support"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> _rootTimestamps</span><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"> onlyInPrimeField</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _requireInPrimeField</span><span>(</span><span>key</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"> modifier</span><span class="z-entity z-name"> onRootUpdate</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> prevRoot_ </span><span class="z-keyword">=</span><span> _evidenceDB</span><span>.</span><span class="z-entity z-name">getRoot</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _rootTimestamps</span><span>[</span><span>prevRoot_</span><span>]</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-constant"> _</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> RootUpdated</span><span>(</span><span>prevRoot_</span><span>,</span><span> _evidenceDB</span><span>.</span><span class="z-entity z-name">getRoot</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"> __EvidenceRegistry_init</span><span>(</span><span class="z-support">address</span><span class="z-variable"> evidenceDB_</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> initializer</span><span> {</span></span> <span class="giallo-l"><span> _evidenceDB </span><span class="z-keyword">=</span><span class="z-entity z-name"> IEvidenceDB</span><span>(</span><span>evidenceDB_</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">@inheritdoc</span><span class="z-comment"> IEvidenceRegistry</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"> addStatement</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> key_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> value_</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyInPrimeField</span><span>(</span><span class="z-entity z-name">key_</span><span>)</span><span class="z-entity z-name"> onlyInPrimeField</span><span>(</span><span class="z-entity z-name">value_</span><span>)</span><span class="z-entity z-name"> onRootUpdate</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> isolatedKey_ </span><span class="z-keyword">=</span><span class="z-entity z-name"> getIsolatedKey</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> key_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_evidenceDB</span><span>.</span><span class="z-entity z-name">getValue</span><span>(</span><span>isolatedKey_</span><span>)</span><span class="z-keyword"> !=</span><span class="z-support"> bytes32</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 class="z-entity z-name"> KeyAlreadyExists</span><span>(</span><span>key_</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _evidenceDB</span><span>.</span><span class="z-entity z-name">add</span><span>(</span><span>isolatedKey_</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@inheritdoc</span><span class="z-comment"> IEvidenceRegistry</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"> removeStatement</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key_</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyInPrimeField</span><span>(</span><span class="z-entity z-name">key_</span><span>)</span><span class="z-entity z-name"> onRootUpdate</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> isolatedKey_ </span><span class="z-keyword">=</span><span class="z-entity z-name"> getIsolatedKey</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> key_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_evidenceDB</span><span>.</span><span class="z-entity z-name">getValue</span><span>(</span><span>isolatedKey_</span><span>)</span><span class="z-keyword"> ==</span><span class="z-support"> bytes32</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 class="z-entity z-name"> KeyDoesNotExist</span><span>(</span><span>key_</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _evidenceDB</span><span>.</span><span class="z-entity z-name">remove</span><span>(</span><span>isolatedKey_</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">@inheritdoc</span><span class="z-comment"> IEvidenceRegistry</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"> updateStatement</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> key_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> newValue_</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyInPrimeField</span><span>(</span><span class="z-entity z-name">key_</span><span>)</span><span class="z-entity z-name"> onlyInPrimeField</span><span>(</span><span class="z-entity z-name">newValue_</span><span>)</span><span class="z-entity z-name"> onRootUpdate</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> isolatedKey_ </span><span class="z-keyword">=</span><span class="z-entity z-name"> getIsolatedKey</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> key_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_evidenceDB</span><span>.</span><span class="z-entity z-name">getValue</span><span>(</span><span>isolatedKey_</span><span>)</span><span class="z-keyword"> ==</span><span class="z-support"> bytes32</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 class="z-entity z-name"> KeyDoesNotExist</span><span>(</span><span>key_</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _evidenceDB</span><span>.</span><span class="z-entity z-name">update</span><span>(</span><span>isolatedKey_</span><span>,</span><span> newValue_</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">@inheritdoc</span><span class="z-comment"> IEvidenceRegistry</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"> getRootTimestamp</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> root_</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"> if</span><span> (</span><span>root_ </span><span class="z-keyword">==</span><span class="z-support"> bytes32</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-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-keyword"> if</span><span> (</span><span>root_ </span><span class="z-keyword">==</span><span> _evidenceDB</span><span>.</span><span class="z-entity z-name">getRoot</span><span>(</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</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> _rootTimestamps</span><span>[</span><span>root_</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">@inheritdoc</span><span class="z-comment"> IEvidenceRegistry</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"> getIsolatedKey</span><span>(</span><span class="z-support">address</span><span class="z-variable"> source_</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"> 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> PoseidonUnit2L</span><span>.</span><span class="z-entity z-name">poseidon</span><span>(</span><span>[</span><span class="z-support">bytes32</span><span>(</span><span class="z-support">uint256</span><span>(</span><span class="z-support">uint160</span><span>(</span><span>source_</span><span>)</span><span>)</span><span>)</span><span>,</span><span> key_</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"> getEvidenceDB</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>_evidenceDB</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"> _requireInPrimeField</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> key_</span><span>)</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> pure</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-support">uint256</span><span>(</span><span>key_</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-keyword">=</span><span> BABY_JUB_JUB_PRIME_FIELD</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> NumberNotInPrimeField</span><span>(</span><span>key_</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><h3 id="evidenceregistry-verifier-implementation">EvidenceRegistry Verifier Implementation</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> LICENSE: CC0-1.0</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> circom</span><span class="z-constant"> 2.1.9</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>include </span><span class="z-string">&quot;SparseMerkleTree.circom&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>template </span><span class="z-entity z-name">BuildIsolatedKey</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> signal output isolatedKey</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> signal input </span><span class="z-support">address</span><span>;</span></span> <span class="giallo-l"><span> signal input key</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> component hasher </span><span class="z-keyword">=</span><span class="z-entity z-name"> Poseidon</span><span>(</span><span class="z-constant">2</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> hasher</span><span>.</span><span>inputs</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> &lt;</span><span class="z-keyword">==</span><span class="z-support"> address</span><span>;</span></span> <span class="giallo-l"><span> hasher</span><span>.</span><span>inputs</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> &lt;</span><span class="z-keyword">==</span><span> key</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> hasher</span><span>.</span><span>out </span><span class="z-keyword">==</span><span class="z-keyword">&gt;</span><span> isolatedKey</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>template </span><span class="z-entity z-name">EvidenceRegistrySMT</span><span>(</span><span>levels</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Public Inputs</span></span> <span class="giallo-l"><span> signal input root</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Private Inputs</span></span> <span class="giallo-l"><span> signal input </span><span class="z-support">address</span><span>;</span></span> <span class="giallo-l"><span> signal input key</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> signal input value</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> signal input siblings</span><span>[</span><span>levels</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> signal input auxKey</span><span>;</span></span> <span class="giallo-l"><span> signal input auxValue</span><span>;</span></span> <span class="giallo-l"><span> signal input auxIsEmpty</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> signal input isExclusion</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Build isolated key</span></span> <span class="giallo-l"><span> component isolatedKey </span><span class="z-keyword">=</span><span class="z-entity z-name"> BuildIsolatedKey</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> isolatedKey</span><span>.</span><span class="z-support">address</span><span class="z-keyword"> &lt;</span><span class="z-keyword">==</span><span class="z-support"> address</span><span>;</span></span> <span class="giallo-l"><span> isolatedKey</span><span>.</span><span>key </span><span class="z-keyword">&lt;</span><span class="z-keyword">==</span><span> key</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Verify Sparse Merkle Tree Proof</span></span> <span class="giallo-l"><span> component smtVerifier </span><span class="z-keyword">=</span><span class="z-entity z-name"> SparseMerkleTree</span><span>(</span><span>levels</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> smtVerifier</span><span>.</span><span>siblings </span><span class="z-keyword">&lt;</span><span class="z-keyword">==</span><span> siblings</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> smtVerifier</span><span>.</span><span>key </span><span class="z-keyword">&lt;</span><span class="z-keyword">==</span><span> isolatedKey</span><span>.</span><span>isolatedKey</span><span>;</span></span> <span class="giallo-l"><span> smtVerifier</span><span>.</span><span>value </span><span class="z-keyword">&lt;</span><span class="z-keyword">==</span><span> value</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> smtVerifier</span><span>.</span><span>auxKey </span><span class="z-keyword">&lt;</span><span class="z-keyword">==</span><span> auxKey</span><span>;</span></span> <span class="giallo-l"><span> smtVerifier</span><span>.</span><span>auxValue </span><span class="z-keyword">&lt;</span><span class="z-keyword">==</span><span> auxValue</span><span>;</span></span> <span class="giallo-l"><span> smtVerifier</span><span>.</span><span>auxIsEmpty </span><span class="z-keyword">&lt;</span><span class="z-keyword">==</span><span> auxIsEmpty</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> smtVerifier</span><span>.</span><span>isExclusion </span><span class="z-keyword">&lt;</span><span class="z-keyword">==</span><span> isExclusion</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> smtVerifier</span><span>.</span><span>root </span><span class="z-keyword">&lt;</span><span class="z-keyword">==</span><span> root</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>component main </span><span>{</span><span class="z-storage z-type">public</span><span> [</span><span>root</span><span>]</span><span>}</span><span class="z-keyword"> =</span><span class="z-entity z-name"> EvidenceRegistrySMT</span><span>(</span><span class="z-constant">80</span><span>)</span><span>;</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>From security standpoint there are several important aspects that must be highlighted.</p> <p>The individual registrars are expected to provide the functionality for both management and proving of statements. The proving will often be carried out by ZK proofs, which require trusted setup. Improperly setup ZK verifiers can be exploited to verify forged proofs.</p> <p>The <code>getRoot</code> method of <code>EvidenceDB</code> SHOULD NOT be used on-chain by the integrating registrars to check the validity of the database state. Instead, the required <code>root</code> SHOULD be passed as a function parameter and checked via <code>getRootTimestamp</code> method to avoid being frontrun.</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-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 alvariushttps://github.com/alvrs dk1ahttps://github.com/dk1a frolichttps://github.com/frolic ludenshttps://github.com/ludns vdrghttps://github.com/vdrg yonadayonada@proton.me https://wg-eips.ritovision.com/7813/

On-chain tables for automatic indexing and introspectable state

<h2 id="abstract">Abstract</h2> <p>This standard introduces a flexible on-chain storage pattern that organizes data into structured tables that consist of records with fixed key and value schemas, similar to a traditional database. This storage pattern consists of a unified contract interface for data access, along with a compact binary encoding format for both static and dynamic data types. State changes are tracked through standardized events that enable automatic, schema-aware state replication by off-chain indexers. New tables can be dynamically registered at runtime through a special table that stores schema metadata for all tables, allowing the system to evolve without breaking existing contracts or integrations.</p> <h2 id="motivation">Motivation</h2> <p>The absence of consistent standards for on-chain data management in smart contracts can lead to rigid implementations, tightly coupled contract logic with off-chain services, and challenges in updating or extending a contract’s data layout without breaking existing integrations.</p> <p>Using the storage mechanism defined in this ERC provides the following benefits:</p> <ol> <li><strong>Automatic Indexing</strong>: By emitting consistent, standardized events during state changes, off-chain services can automatically track on-chain state and provide schema-aware indexer APIs.</li> <li><strong>Elimination of Custom Getter Functions</strong>: Any contract or off-chain service can read stored data through a consistent interface, decoupling smart contract implementation from specific data access patterns and reducing development overhead.</li> <li><strong>Simpler Upgradability</strong>: This pattern leverages unstructured storage, making it easier to upgrade contract logic without the risks associated with using a fixed storage layout.</li> <li><strong>Flexible Data Extensions</strong>: New tables can be added at runtime without without breaking existing integrations with other data consumers.</li> <li><strong>Reduced gas costs</strong>: Using efficient data packing reduces gas costs for both storage and event emissions.</li> </ol> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions</h3> <h4 id="store">Store</h4> <p>A smart contract that implements the interface proposed by this ERC and organizes data in Tables. It emits events for each data operation so that off-chain components can replicate the state of all tables.</p> <h4 id="table">Table</h4> <p>A storage structure that holds <strong>Records</strong> sharing the same <strong>Schema</strong>.</p> <ul> <li><strong>On-chain Table</strong>: Stores its state on-chain and emits events for off-chain- indexers.</li> <li><strong>Off-chain Table</strong>: Does not store state on-chain but emits events for off-chain indexers.</li> </ul> <h4 id="record">Record</h4> <p>A piece of data stored in a <strong>Table</strong>, addressed by one or more keys.</p> <h4 id="resourceid"><code>ResourceId</code></h4> <p>A 32-byte value that uniquely identifies each <strong>Table</strong> within the <strong>Store</strong>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> ResourceId</span><span class="z-storage"> is</span><span class="z-support"> bytes32</span><span>;</span></span></code></pre> <p>Encoding:</p> <table><thead><tr><th><strong>Bytes (from left to right)</strong></th><th><strong>Description</strong></th></tr></thead><tbody> <tr><td>0-1</td><td>Table type identifier</td></tr> <tr><td>2-31</td><td>Unique identifier</td></tr> </tbody></table> <p><strong>Table Type Identifiers:</strong></p> <ul> <li><code>0x7462</code> (<code>"tb"</code>) for on-chain tables</li> <li><code>0x6f74</code> (<code>"ot"</code>) for off-chain tables</li> </ul> <h4 id="schema"><code>Schema</code></h4> <p>Used to represent the layout of Records within a table.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> Schema</span><span class="z-storage"> is</span><span class="z-support"> bytes32</span><span>;</span></span></code></pre> <p>Each Table defines two schemas:</p> <ul> <li>Key Schema: the types of the keys used to uniquely identify a <strong>Record</strong> within a table. It consists only of fixed-length data types.</li> <li>Value Schema: the types of the value fields of a <strong>Record</strong> within a table, which can include both fixed-length and variable-length data types.</li> </ul> <table><thead><tr><th><strong>Byte(s) from left to right</strong></th><th><strong>Value</strong></th><th><strong>Constraint</strong></th></tr></thead><tbody> <tr><td>0-1</td><td>Total byte length of static fields</td><td></td></tr> <tr><td>2</td><td>Number of static length fields</td><td>≤ (28 - number of dynamic length fields)</td></tr> <tr><td>3</td><td>Number of dynamic length fields</td><td>For the key schema, 0</td></tr> <tr><td>For the value schema, ≤5</td><td></td><td></td></tr> <tr><td>4-31</td><td>Each byte encodes a <code>SchemaType</code></td><td>Dynamic-length types MUST come after all the static-length types.</td></tr> </tbody></table> <h4 id="schematype"><code>SchemaType</code></h4> <p>Single byte that represents the type of a specific static or dynamic field.</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"> SchemaType</span><span> {</span><span> .</span><span>.</span><span>.</span><span> }</span></span></code></pre> <p><strong>Type Encoding:</strong></p> <table><thead><tr><th>Value Range</th><th>Type</th></tr></thead><tbody> <tr><td><code>0x00</code> to <code>0x1F</code></td><td><code>uint8</code> to <code>uint256</code> (increments of 8 bits)</td></tr> <tr><td><code>0x20</code> to <code>0x3F</code></td><td><code>int8</code> to <code>int256</code> (increments of 8 bits)</td></tr> <tr><td><code>0x40</code> to <code>0x5F</code></td><td><code>bytes1</code> to <code>bytes32</code></td></tr> <tr><td><code>0x60</code></td><td><code>bool</code></td></tr> <tr><td><code>0x61</code></td><td><code>address</code></td></tr> <tr><td><code>0x62</code> to <code>0x81</code></td><td><code>uint8[]</code> to <code>uint256[]</code></td></tr> <tr><td><code>0x82</code> to <code>0xA1</code></td><td><code>int8[]</code> to <code>int256[]</code></td></tr> <tr><td><code>0xA2</code> to <code>0xC1</code></td><td><code>bytes1[]</code> to <code>bytes32[]</code></td></tr> <tr><td><code>0xC2</code></td><td><code>bool[]</code></td></tr> <tr><td><code>0xC3</code></td><td><code>address[]</code></td></tr> <tr><td><code>0xC4</code></td><td><code>bytes</code></td></tr> <tr><td><code>0xC5</code></td><td><code>string</code></td></tr> </tbody></table> <h4 id="fieldlayout"><code>FieldLayout</code></h4> <p>Encodes the concrete value <code>Schema</code> information, specifically the total byte length of the static fields, the number of dynamic fields and the length of each static field on its own.</p> <p>This encoding serves as an optimization for on-chain operations. By having the exact lengths readily available, the Store doesn't need to repeatedly compute or translate the schema definitions into actual field lengths during execution.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> FieldLayout</span><span class="z-storage"> is</span><span class="z-support"> bytes32</span><span>;</span></span></code></pre><table><thead><tr><th><strong>Byte(s) from left to right</strong></th><th><strong>Value</strong></th><th><strong>Constraint</strong></th></tr></thead><tbody> <tr><td>0-1</td><td>Total length of static fields</td><td></td></tr> <tr><td>2</td><td>Number of static length fields</td><td>≤ (28 - number of dynamic length fields)</td></tr> <tr><td>3</td><td>Number of dynamic length fields</td><td>For the key schema, 0</td></tr> <tr><td>For the value schema, ≤5</td><td></td><td></td></tr> <tr><td>4-31</td><td>Each byte encodes the byte length of the corresponding static field</td><td></td></tr> </tbody></table> <h4 id="encodedlengths"><code>EncodedLengths</code></h4> <p>Encodes the byte length of all the dynamic fields of a specific Record. It is returned by the Store methods when reading a Record, as it is needed for decoding dynamic fields.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> EncodedLengths</span><span class="z-storage"> is</span><span class="z-support"> bytes32</span><span>;</span></span></code></pre><table><thead><tr><th>Bytes (from least to most significant)</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>0x00-0x06</td><td>uint56</td><td>Total byte length of dynamic data</td></tr> <tr><td>0x07-0xB</td><td>uint40</td><td>Length of the first dynamic field</td></tr> <tr><td>0x0C-0x10</td><td>uint40</td><td>Length of the second dynamic field</td></tr> <tr><td>0x11-0x15</td><td>uint40</td><td>Length of the third dynamic field</td></tr> <tr><td>0x16-0x1A</td><td>uint40</td><td>Length of the fourth dynamic field</td></tr> <tr><td>0x1B-0x1F</td><td>uint40</td><td>Length of the fifth dynamic field</td></tr> </tbody></table> <h3 id="packed-data-encoding">Packed Data Encoding</h3> <p>Record data returned by Store methods and included in Store events uses the following encoding rules.</p> <h4 id="field-limits">Field Limits</h4> <ul> <li><strong>Maximum Total Fields</strong>: A record can contain up to <strong>28 fields</strong> in total (both static and dynamic fields combined). <ul> <li>This limit is due to the <code>Schema</code> type structure, which uses 28 bytes (bytes 4 to 31) to define field types, with one byte per field (<code>SchemaType</code>).</li> </ul> </li> <li><strong>Dynamic Fields Limit</strong>: A record can have up to <strong>5 dynamic fields</strong>. <ul> <li>This is due to the fact that a single 32 bytes word (<code>EncodedLengths</code>) to encode the byte lengths of each dynamic field, instead of encoding each length separately as Solidity’s <code>abi.encode</code> would.</li> </ul> </li> <li><strong>Static Fields Limit</strong>: The maximum number of static fields is <strong>28 minus the number of dynamic fields</strong>. <ul> <li>For example, if there are 5 dynamic fields, the maximum number of static fields is 23 (28 - 5).</li> </ul> </li> </ul> <h4 id="encoding-rules">Encoding Rules</h4> <ul> <li>Static-length fields are encoded without any padding, and concatenated in the order they are defined in the schema, which is equivalent to using Solidity's <code>abi.encodePacked</code>.</li> <li>For dynamic-length fields (arrays, <code>bytes</code>, and <code>string</code>s): <ul> <li>If the field is an array, its elements are tightly packed without padding.</li> <li>All dynamic fields are concatenated together without padding and without including their lengths.</li> <li>The lengths of all dynamic fields are encoded into a single <code>EncodedLengths</code>.</li> </ul> </li> </ul> <h4 id="example">Example</h4> <p>Suppose a table has the following value schema:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>(</span><span class="z-support">uint256</span><span> id</span><span>,</span><span class="z-support"> address</span><span> owner</span><span>,</span><span class="z-support"> string</span><span> description</span><span>,</span><span class="z-support"> uint8</span><span>[</span><span>]</span><span> scores</span><span>)</span></span></code></pre> <p><strong>Encoding (Pseudocode)</strong>:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> staticData </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>id</span><span>,</span><span> owner</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 is a custom function as Solidity does not provide a way to tightly pack array elements</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> packedScores </span><span class="z-keyword">=</span><span class="z-entity z-name"> packElementsWithoutPadding</span><span>(</span><span>scores</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> abi.encodePacked concatenates both description and packedScores without including their lengths</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> dynamicData </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>description</span><span>,</span><span> packedScores</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Total length is encoded in the 56 least significant bits</span></span> <span class="giallo-l"><span>EncodedLengths encodedLengths </span><span class="z-keyword">=</span><span> dynamicData</span><span>.</span><span>length</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Each length is encoded using 5 bytes</span></span> <span class="giallo-l"><span>encodedLengths </span><span class="z-keyword">|</span><span class="z-keyword">=</span><span> (</span><span>description</span><span>.</span><span>length </span><span class="z-keyword">&lt;&lt;</span><span> (</span><span class="z-constant">56</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>encodedLengths </span><span class="z-keyword">|</span><span class="z-keyword">=</span><span> (</span><span>encodedData</span><span>.</span><span>length </span><span class="z-keyword">&lt;&lt;</span><span> (</span><span class="z-constant">56</span><span class="z-keyword"> +</span><span class="z-constant"> 8</span><span class="z-keyword"> *</span><span class="z-constant"> 5</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"> The full encoded record data is represented by the following tuple:</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> (staticData, encodedLengths, dynamicData)</span></span></code></pre><h3 id="store-interface">Store Interface</h3> <p>All Stores 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"> IStore</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * Get full encoded record (all fields, static and dynamic data) for the given tableId and key tuple.</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"> getRecord</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> ResourceId</span><span class="z-variable"> tableId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> keyTuple</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">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> staticData</span><span>,</span><span class="z-storage z-type"> EncodedLengths</span><span class="z-variable"> encodedLengths</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> dynamicData</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"> * Get a single encoded field from the given tableId and key tuple.</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"> getField</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> ResourceId</span><span class="z-variable"> tableId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> keyTuple</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> fieldIndex</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">bytes</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * Get the byte length of a single field from the given tableId and key tuple</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"> getFieldLength</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> ResourceId</span><span class="z-variable"> tableId</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"> keyTuple</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> fieldIndex</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> <p>The return values of both <code>getRecord</code> and <code>getField</code> use the encoding rules previously defined in the Packed Data Encoding section. More specifically, <code>getRecord</code> returns the fully encoded record tuple, and the data returned by <code>getField</code> is encoded using the encoding rules as if the field was being encoded on its own.</p> <h3 id="store-operations-and-events">Store Operations and Events</h3> <p>This standard defines three core operations for manipulating records in a table: setting, updating, and deleting. For each operation, specific events must be emitted. The implementation details of these operations are left to the discretion of each Store implementation.</p> <p>The fundamental requirement is that for on-chain tables the Record data retrieved through the Store interface methods at any given block MUST be consistent with the Record data that would be obtained by applying the operations implied by the Store events up to that block. This ensures data integrity and allows for accurate off-chain state reconstruction.</p> <h4 id="store-setrecord">Store_SetRecord</h4> <p>Setting a Record means overwriting all of its fields. This operation can be performed whether the record has been set before or not (the standard does not enforce existence checks).</p> <p>The <code>Store_SetRecord</code> event <strong>MUST</strong> be emitted whenever the full data of a record has been overwritten.</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"> Store_SetRecord</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> ResourceId</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tableId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-variable"> keyTuple</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> staticData</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> EncodedLengths</span><span class="z-variable"> encodedLengths</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> dynamicData</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre> <p>Parameters:</p> <table><thead><tr><th><strong>Name</strong></th><th><strong>Type</strong></th><th><strong>Description</strong></th></tr></thead><tbody> <tr><td>tableId</td><td>ResourceId</td><td>The ID of the table where the record is set</td></tr> <tr><td>keyTuple</td><td>bytes32[]</td><td>An array representing the composite key for the record</td></tr> <tr><td>staticData</td><td>bytes</td><td>The static data of the record using packed encoding</td></tr> <tr><td>encodedLengths</td><td>EncodedLengths</td><td>The encoded lengths of the dynamic data of the record</td></tr> <tr><td>dynamicData</td><td>bytes</td><td>The dynamic data of the record, using <a href="https://wg-eips.ritovision.com/7813/#packed-data-encoding">custom packed encoding</a></td></tr> </tbody></table> <h4 id="store-splicestaticdata">Store_SpliceStaticData</h4> <p>Splicing the static data of a Record consists in overwriting bytes of the packed encoded static fields. The total length of static data does not change as it is determined by the table’s value schema.</p> <p>The <code>Store_SpliceStaticData</code> event MUST be emitted whenever the static data of the Record has been spliced.</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"> Store_SpliceStaticData</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> ResourceId</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tableId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-variable"> keyTuple</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint48</span><span class="z-variable"> start</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></code></pre> <p>Parameters:</p> <table><thead><tr><th><strong>Name</strong></th><th><strong>Type</strong></th><th><strong>Description</strong></th></tr></thead><tbody> <tr><td>tableId</td><td>ResourceId</td><td>The ID of the table where the data is spliced</td></tr> <tr><td>keyTuple</td><td>bytes32[]</td><td>An array representing the key for the record</td></tr> <tr><td>start</td><td>uint48</td><td>The start position in bytes for the splice operation</td></tr> <tr><td>data</td><td>bytes</td><td>Packed ABI encoding of a tuple with the value's static fields</td></tr> </tbody></table> <h4 id="store-splicedynamicdata">Store_SpliceDynamicData</h4> <p>Splicing the dynamic data of a Record involves modifying the packed encoded representation of its dynamic fields by removing, replacing, and/or inserting new bytes in place.</p> <p>The <code>Store_SpliceDynamicData</code> event MUST be emitted whenever the dynamic data of the Record has been spliced.</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"> Store_SpliceDynamicData</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> ResourceId</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tableId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-variable"> keyTuple</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> dynamicFieldIndex</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint48</span><span class="z-variable"> start</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint40</span><span class="z-variable"> deleteCount</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> EncodedLengths</span><span class="z-variable"> encodedLengths</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></code></pre> <p>Parameters:</p> <table><thead><tr><th><strong>Name</strong></th><th><strong>Type</strong></th><th><strong>Description</strong></th></tr></thead><tbody> <tr><td>tableId</td><td>ResourceId</td><td>The ID of the table where the data is spliced</td></tr> <tr><td>keyTuple</td><td>bytes32[]</td><td>An array representing the composite key for the record</td></tr> <tr><td>dynamicFieldIndex</td><td>uint8</td><td>The index of the dynamic field to splice data, relative to the start of the dynamic fields (Dynamic field index = field index - number of static fields)</td></tr> <tr><td>start</td><td>uint48</td><td>The start position in bytes for the splice operation</td></tr> <tr><td>deleteCount</td><td>uint40</td><td>The number of bytes to delete in the splice operation</td></tr> <tr><td>encodedLengths</td><td>EncodedLengths</td><td>The resulting encoded lengths of the dynamic data of the record</td></tr> <tr><td>data</td><td>bytes</td><td>The data to insert into the dynamic data of the record at the start byte</td></tr> </tbody></table> <h4 id="store-deleterecord">Store_DeleteRecord</h4> <p>The <code>Store_DeleteRecord</code> event MUST be emitted whenever the Record has been deleted from the Table.</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"> Store_DeleteRecord</span><span>(</span><span class="z-variable">ResourceId</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tableId</span><span>, </span><span class="z-support">bytes32</span><span>[</span><span>]</span><span class="z-variable"> keyTuple</span><span>)</span><span>;</span></span></code></pre> <p>Parameters:</p> <table><thead><tr><th><strong>Name</strong></th><th><strong>Type</strong></th><th><strong>Description</strong></th></tr></thead><tbody> <tr><td>tableId</td><td>ResourceId</td><td>The ID of the table where the record is deleted</td></tr> <tr><td>keyTuple</td><td>bytes32[]</td><td>An array representing the composite key for the record</td></tr> </tbody></table> <p>See the <a href="https://wg-eips.ritovision.com/7813/#reference-implementation">reference implementation section</a> for an example on how to index store events.</p> <h3 id="the-tables-table">The <code>Tables</code> table</h3> <p>To keep track of the information of each table and support registering new tables at runtime, the Store implementation MUST include a special on-chain <code>Tables</code> table, which behaves the same way as other on-chain tables except for the special constraints mentioned below.</p> <p>The <code>Tables</code> table MUST use the following <code>Schema</code>s:</p> <ul> <li>Key Schema: <ul> <li><code>tableId</code> (<code>ResourceId</code>): <code>ResourceId</code> of the table this record describes.</li> </ul> </li> <li>Value Schema: <ul> <li><code>fieldLayout</code> (<code>FieldLayout</code>): encodes the byte length of each static data type in the table.</li> <li><code>keySchema</code> (<code>Schema</code>): represents the data types of the (composite) key of the table.</li> <li><code>valueSchema</code> (<code>Schema</code>): represents the data types of the value fields of the table.</li> <li><code>abiEncodedKeyNames</code> (<code>bytes</code>): ABI encoded string array of key names.</li> <li><code>abiEncodedFieldNames</code> (<code>bytes</code>): ABI encoded string array of field names.</li> </ul> </li> </ul> <p>Records stored in the <code>Tables</code> table are considered immutable:</p> <ul> <li>The <code>Store</code> MUST emit a single <code>Store_SetRecord</code> event for each table being registered.</li> <li>The <code>Store</code> SHOULD NOT emit any other <code>Store</code> events for a <code>Table</code> registered in the <code>Tables</code> table.</li> </ul> <p>The <code>Tables</code> table MUST store a record that describes itself before any other table is registered, emitting the corresponding <code>Store_SetRecord</code> event. The record must use the following <code>tableId</code>:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> First two bytes indicates that this is an on-chain table</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> The next 30 bytes are the unique identifier for the Tables table</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> bytes32(&quot;tb&quot;) | bytes32(&quot;store&quot;) &gt;&gt; (2 * 8) | bytes32(&quot;Tables&quot;) &gt;&gt; (2 * 8 + 14 * 8)</span></span> <span class="giallo-l"><span>ResourceId tableId </span><span class="z-keyword">=</span><span> ResourceId</span><span>.</span><span class="z-entity z-name">wrap</span><span>(</span><span class="z-constant">0x746273746f72650000000000000000005461626c657300000000000000000000</span><span>)</span><span>;</span></span></code></pre> <p>By using a predefined <code>ResourceId</code> and <code>Schema</code> for the <code>Tables</code> table, off-chain indexers can interpret store events for all registered tables. This enables the development of advanced off-chain services that operate on structured data rather than raw encoded data like in the previous indexer implementation example.</p> <h2 id="rationale">Rationale</h2> <h3 id="splice-events">Splice Events</h3> <p>While the <code>Store_SetRecord</code> event suffices for tracking the data of each record off-chain, including <code>Splice</code> events (<code>Store_SpliceStaticData</code> and <code>Store_SpliceDynamicData</code>) allows for more efficient partial updates. When only a portion of a record changes, emitting a full <code>SetRecord</code> event would be inefficient because the entire record data would need to be read from storage and emitted. <code>Splice</code> events enable the store to emit only the minimal necessary data for the update, reducing gas consumption. This is particularly important for records with large dynamic fields, as the cost of updating them doesn’t grow with the field’s size.</p> <h3 id="disallowing-arrays-of-dynamic-types">Disallowing Arrays of Dynamic Types</h3> <p>Arrays of dynamic types (e.g., <code>string[]</code>, <code>bytes[]</code>) are intentionally not included as supported <code>SchemaType</code>s. This restriction enforces a flat data schema, which simplifies the store implementation and enhances efficiency. If users need to store such data structures, they can model them using a separate table with a schema like <code>{ index: uint256, data: bytes }</code>, where each array element is represented as an individual record.</p> <h3 id="fieldlayout-optimization">FieldLayout Optimization</h3> <p>Including the <code>FieldLayout</code> in the <code>Tables</code> schema provides an on-chain optimization by precomputing and storing the exact byte lengths of static fields. This eliminates the need to repeatedly compute field lengths and offsets during runtime, which can be gas-intensive. By having this information readily available, the store can perform storage operations more efficiently, while components reading from the store can retrieve it from the <code>Tables</code> table to decode the corresponding records.</p> <h3 id="special-tables-table">Special <code>Tables</code> table</h3> <p>Including a special <code>Tables</code> table provides significant benefits for off-chain indexers. While emitting events for table registration isn't strictly necessary for basic indexers that operate on raw encoded data, doing so makes indexers aware of the schemas used by each table. This awareness enables the development of more advanced, schema-aware indexer APIs (e.g., SQL-like query capabilities), enhancing the utility and flexibility of off-chain data interactions.</p> <p>By reusing existing Store abstractions for table registration, we also simplify the implementation and eliminate the need for additional, specific table registration events. Indexers can leverage the standard Store events to access schema information, ensuring consistency and reducing complexity.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="store-event-indexing">Store Event Indexing</h3> <p>The following example shows how a simple in-memory indexer can use the Store events to replicate the Store state off-chain. It is important to note that this indexer operates over raw encoded data which is not that useful on its own, but can be improved as we will explain in the next section.</p> <p>We use TypeScript for this example but it can easily be replicated with other languages.</p> <pre class="giallo z-code"><code data-lang="tsx"><span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> Hex</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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> Record</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> staticData</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> encodedLengths</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> dynamicData</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</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">const</span><span class="z-variable z-other z-constant"> store</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"> Record</span><span>&gt;</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"> Create a key string from a table ID and key tuple to use in our store Map above</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> storeKey</span><span>(</span><span class="z-variable">tableId</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>,</span><span class="z-variable"> keyTuple</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>[</span><span>]</span><span>)</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-punctuation z-definition z-string"> `</span><span class="z-string">${</span><span class="z-variable z-other">tableId</span><span class="z-string">}</span><span class="z-string">:</span><span class="z-string">${</span><span class="z-variable z-other">keyTuple</span><span class="z-string">.</span><span class="z-entity z-name">join</span><span class="z-string">(</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-string">)</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 class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Like `Array.splice`, but for strings of bytes</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> bytesSplice</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> start</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> deleteCount</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> newData</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span class="z-keyword"> =</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 class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> dataNibbles</span><span class="z-keyword"> =</span><span class="z-variable z-other"> data</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"> &quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</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-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"> newDataNibbles</span><span class="z-keyword"> =</span><span class="z-variable z-other"> newData</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"> &quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</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-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-punctuation z-definition z-string"> `</span><span class="z-string">0x</span><span class="z-string">${</span><span class="z-variable z-other">dataNibbles</span></span> <span class="giallo-l"><span class="z-string"> .</span><span class="z-entity z-name">splice</span><span class="z-string">(</span><span class="z-variable z-other">start</span><span class="z-string">,</span><span class="z-variable z-other"> deleteCount</span><span class="z-keyword"> *</span><span class="z-constant"> 2</span><span class="z-string">)</span></span> <span class="giallo-l"><span class="z-string"> .</span><span class="z-entity z-name">concat</span><span class="z-string">(</span><span class="z-variable z-other">newDataNibbles</span><span class="z-string">)</span></span> <span class="giallo-l"><span class="z-string"> .</span><span class="z-entity z-name">join</span><span class="z-string">(</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">)</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 class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> bytesLength</span><span>(</span><span class="z-variable">data</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>)</span><span class="z-keyword">:</span><span class="z-support"> number</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> data</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"> &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"> /</span><span class="z-constant"> 2</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"> processStoreEvent</span><span>(</span><span class="z-variable">log</span><span class="z-keyword">:</span><span class="z-entity z-name"> StoreEvent</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-other">log</span><span>.</span><span class="z-variable z-other">eventName</span><span class="z-keyword"> ===</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Store_SetRecord</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"> key</span><span class="z-keyword"> =</span><span class="z-entity z-name"> storeKey</span><span>(</span><span class="z-variable z-other">log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">tableId</span><span>,</span><span class="z-variable z-other"> log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">keyTuple</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"> Overwrite all of the Record&#39;s fields</span></span> <span class="giallo-l"><span class="z-variable z-other"> store</span><span>.</span><span class="z-entity z-name">set</span><span>(</span><span class="z-variable z-other">key</span><span>,</span><span> {</span></span> <span class="giallo-l"><span> staticData</span><span>:</span><span class="z-variable z-other"> log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">staticData</span><span>,</span></span> <span class="giallo-l"><span> encodedLengths</span><span>:</span><span class="z-variable z-other"> log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">encodedLengths</span><span>,</span></span> <span class="giallo-l"><span> dynamicData</span><span>:</span><span class="z-variable z-other"> log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">dynamicData</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 class="z-keyword"> if</span><span> (</span><span class="z-variable z-other">log</span><span>.</span><span class="z-variable z-other">eventName</span><span class="z-keyword"> ===</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Store_SpliceStaticData</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"> key</span><span class="z-keyword"> =</span><span class="z-entity z-name"> storeKey</span><span>(</span><span class="z-variable z-other">log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">tableId</span><span>,</span><span class="z-variable z-other"> log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">keyTuple</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"> record</span><span class="z-keyword"> =</span><span class="z-variable z-other"> store</span><span>.</span><span class="z-entity z-name">get</span><span>(</span><span class="z-variable z-other">key</span><span>)</span><span class="z-keyword"> ??</span><span> {</span></span> <span class="giallo-l"><span> staticData</span><span>:</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></span> <span class="giallo-l"><span> encodedLengths</span><span>:</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></span> <span class="giallo-l"><span> dynamicData</span><span>:</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></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"> Splice the static field data of the Record</span></span> <span class="giallo-l"><span class="z-variable z-other"> store</span><span>.</span><span class="z-entity z-name">set</span><span>(</span><span class="z-variable z-other">key</span><span>,</span><span> {</span></span> <span class="giallo-l"><span> staticData</span><span>:</span><span class="z-entity z-name"> bytesSplice</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> record</span><span>.</span><span class="z-variable z-other">staticData</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">start</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> bytesLength</span><span>(</span><span class="z-variable z-other">log</span><span>.</span><span class="z-variable z-other">args</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"> log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">data</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span> encodedLengths</span><span>:</span><span class="z-variable z-other"> record</span><span>.</span><span class="z-variable z-other">encodedLengths</span><span>,</span></span> <span class="giallo-l"><span> dynamicData</span><span>:</span><span class="z-variable z-other"> record</span><span>.</span><span class="z-variable z-other">dynamicData</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 class="z-keyword"> if</span><span> (</span><span class="z-variable z-other">log</span><span>.</span><span class="z-variable z-other">eventName</span><span class="z-keyword"> ===</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Store_SpliceDynamicData</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"> key</span><span class="z-keyword"> =</span><span class="z-entity z-name"> storeKey</span><span>(</span><span class="z-variable z-other">log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">tableId</span><span>,</span><span class="z-variable z-other"> log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">keyTuple</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"> record</span><span class="z-keyword"> =</span><span class="z-variable z-other"> store</span><span>.</span><span class="z-entity z-name">get</span><span>(</span><span class="z-variable z-other">key</span><span>)</span><span class="z-keyword"> ??</span><span> {</span></span> <span class="giallo-l"><span> staticData</span><span>:</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></span> <span class="giallo-l"><span> encodedLengths</span><span>:</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></span> <span class="giallo-l"><span> dynamicData</span><span>:</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></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"> Splice the dynamic field data of the Record</span></span> <span class="giallo-l"><span class="z-variable z-other"> store</span><span>.</span><span class="z-entity z-name">set</span><span>(</span><span class="z-variable z-other">key</span><span>,</span><span> {</span></span> <span class="giallo-l"><span> staticData</span><span>:</span><span class="z-variable z-other"> record</span><span>.</span><span class="z-variable z-other">staticData</span><span>,</span></span> <span class="giallo-l"><span> encodedLengths</span><span>:</span><span class="z-variable z-other"> log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">encodedLengths</span><span>,</span></span> <span class="giallo-l"><span> dynamicData</span><span>:</span><span class="z-entity z-name"> bytesSplice</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> record</span><span>.</span><span class="z-variable z-other">dynamicData</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">start</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">deleteCount</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><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></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">log</span><span>.</span><span class="z-variable z-other">eventName</span><span class="z-keyword"> ===</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Store_DeleteRecord</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"> key</span><span class="z-keyword"> =</span><span class="z-entity z-name"> storeKey</span><span>(</span><span class="z-variable z-other">log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">tableId</span><span>,</span><span class="z-variable z-other"> log</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">keyTuple</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"> Delete the whole Record</span></span> <span class="giallo-l"><span class="z-variable z-other"> store</span><span>.</span><span class="z-entity z-name">delete</span><span>(</span><span class="z-variable z-other">key</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> <h3 id="access-control">Access Control</h3> <p>This standard only defines functions to <strong>read</strong> from the Store (<code>getRecord</code>, <code>getField</code>, and <code>getFieldLength</code>). The methods for setting or modifying records in the store are left to each specific implementation. Therefore, implementations <strong>must provide appropriate access control mechanisms</strong> for writing to the store, tailored to their specific use cases.</p> <h3 id="on-chain-data-accessibility">On-Chain Data Accessibility</h3> <p>All data stored within a store is accessible not only off-chain but also <strong>on-chain</strong> by other smart contracts through the provided read functions (<code>getRecord</code>, <code>getField</code>, and <code>getFieldLength</code>). This differs from the typical behavior of smart contracts, where internal storage variables are private by default and cannot be directly read by other contracts unless explicit getter functions are provided. Thus, developers must be mindful that any data stored in the store is openly accessible to other smart contracts.</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-07T00:00:00+00:00 2026-02-11T14:48:26+00:00 Luka Isailovichttps://github.com/lukaisailovic Konrad Kopphttps://github.com/kopy-kat Derek Reinhttps://github.com/arein Chris Smithhttps://github.com/chris13524 https://wg-eips.ritovision.com/7811/

JSON-RPC method for wallets to share a user’s full asset list with Dapps, including assets not easily found through on-chain data alone

<h2 id="abstract">Abstract</h2> <p>This ERC introduces a new RPC call, <code>wallet_getAssets</code>, for wallets to declare to the Dapp what assets are owned by the user. This allows for more accurate asset discovery and the use of assets that aren’t available on-chain but can be provided by the wallet</p> <h2 id="motivation">Motivation</h2> <p>Currently, Dapps primarily rely on on-chain data to determine a user's balance, which can be limiting. Furthermore, a Dapp might restrict the user from initiating actions that the wallet could otherwise resolve, as it cannot account for the total assets a user has across different accounts or chains.</p> <p>Wallets already have information about a user's assets, including those not visible on-chain, and need a way to communicate that information to Dapps.</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="method-wallet-getassets">Method: <code>wallet_getAssets</code></h3> <h4 id="request-schema">Request schema</h4> <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"> Hex</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> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> Address</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Hex</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> AssetType</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">native</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">erc20</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">erc721</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword"> |</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> Address</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Hex</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> AddressOrNative</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Address</span><span class="z-keyword"> |</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">native</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> Eip155ChainId</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Hex</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"> WalletGetAssetsRequest</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> account</span><span class="z-keyword">:</span><span class="z-entity z-name"> Address</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> assetFilter</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span></span> <span class="giallo-l"><span class="z-entity z-name"> Eip155ChainId</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-keyword">:</span><span class="z-entity z-name"> AddressOrNative</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-entity z-name"> AssetType</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>[</span><span>]</span></span> <span class="giallo-l"><span> &gt;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> assetTypeFilter</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-entity z-name"> AssetType</span><span>[</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> chainFilter</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>[</span><span>]</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p><code>account</code> is a <strong>REQUIRED</strong> field that indicates for which account assets are requested.</p> <p><code>assetFilter</code> is <strong>OPTIONAL</strong> field that accepts a list of assets identifiers. Each asset identifier is an object that contains <code>address</code> and <code>type</code> fields and is scoped by <code>chainId</code>, where ChainId <strong>MUST</strong> be a valid <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> chainId.</p> <p>If the <code>assetFilter</code> field is provided, the wallet <strong>MUST</strong> only return the assets specified within it, even if <code>assetTypeFilter</code> or <code>chainFilter</code> could have further filtered the result. This effectively disregards the <code>assetTypeFilter</code> and <code>chainFilter</code> fields entirely. The reason for this is that they are already implicitly defined within the <code>assetFilter</code>.</p> <p>If the <code>assetFilter</code> field is omitted, the wallet <strong>SHOULD</strong> return all available assets for the requested account. It is <strong>RECOMMENDED</strong> that the returned assets be ordered by estimated value in descending order, as determined by the wallet.</p> <p><code>assetTypeFilter</code> is an <strong>OPTIONAL</strong> field that specifies an array of asset types, as defined in this ERC. If <code>assetTypeFilter</code> field is provided, wallet <strong>MUST</strong> include only assets with those types in the response.</p> <p><code>chainFilter</code> is an <strong>OPTIONAL</strong> field that specifies an array of chain ids, where each value in the array <strong>MUST</strong> be a valid <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> chainId</p> <p>Consumers of <code>wallet_getAssets</code> SHOULD set <code>assetFilter</code>, <code>assetTypeFilter</code> and <code>chainFilter</code> with as granular as reasonably possible values. For example, if an app is only interested in interacting with a single token on a single chain, it should provide filters for this. Doing this both ensures that wallets and the underlying infrastructure do not incur excessive cost, as well as significantly increased performance to client applications.</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 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">0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">assetFilter</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">0x1</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">0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045</span><span class="z-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">erc20</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">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">native</span><span class="z-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">native</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">0xa</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">0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045</span><span class="z-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">erc20</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">assetTypeFilter</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">native</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">chainFilter</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 class="giallo-l"><span>}</span></span></code></pre><h4 id="response-schema">Response schema</h4> <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"> Asset</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-keyword">:</span><span class="z-entity z-name"> AddressOrNative</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> balance</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> metadata</span><span class="z-keyword">:</span><span class="z-support"> any</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> WalletGetAssetsResponse</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-entity z-name">Hex</span><span>,</span><span class="z-entity z-name"> Asset</span><span>[</span><span>]</span><span>&gt;</span><span>;</span></span></code></pre> <p>The key <strong>MUST</strong> be <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> chainId</p> <p>Asset fields:</p> <p><code>address</code> is the address of the asset as <code>Hex</code> or <code>native</code> string for native assets.</p> <p><code>balance</code> is the balance of the asset as <code>Hex</code></p> <p><strong><code>type</code>:</strong> A string indicating the type of the asset. Common asset types include but <strong>aren’t limited to</strong>:</p> <ul> <li><strong><code>erc20</code>:</strong> For <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens</li> <li><strong><code>erc721</code>:</strong> For <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens (NFTs)</li> <li><strong><code>native</code>:</strong> For the chain's native asset</li> </ul> <p><strong><code>metadata</code>:</strong> An <strong>OPTIONAL</strong> object containing additional information about the asset. The specific fields within the metadata object may vary depending on the asset type and the wallet's implementation.</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">0x1</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">0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48</span><span class="z-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-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xcaaea35047fe5702</span><span class="z-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">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">metadata</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">Token</span><span class="z-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">TOK</span><span class="z-punctuation z-definition z-string">&quot;</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">native</span><span class="z-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-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xcaaea35047fe5702</span><span class="z-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">native</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">0xa</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">0x456</span><span class="z-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-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xcd5595</span><span class="z-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">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">metadata</span><span class="z-support">&quot;</span><span>:</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> }</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="well-known-asset-types">Well-known asset types</h3> <p>Below are expansions of <code>metadata</code> for well-known asset types. Implementations that are compliant with this ERC and return these well-known asset types <strong>MUST</strong> return at least these fields in <code>metadata</code>. Implementations <strong>MAY</strong> return more fields than specified here. This ERC does not specify an exhaustive list of asset types. Since the type is a generic string, there could be a mismatch between the type Dapp expects and the one returned by the wallet. It’s important that no two assets share the same type. Therefore, new asset types should be specified in future ERCs.</p> <p><strong>Native</strong></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"> NativeAsset</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">native</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> balance</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">native</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p>Example:</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">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">native</span><span class="z-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-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xcaaea35047fe5702</span><span class="z-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">native</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>ERC-20 Token</strong></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"> Erc20Asset</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> balance</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</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-variable"> metadata</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>}</span><span>;</span></span></code></pre> <p>Example:</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">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48</span><span class="z-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-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xcaaea35047fe5702</span><span class="z-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">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">metadata</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">Token</span><span class="z-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">TOK</span><span class="z-punctuation z-definition z-string">&quot;</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></code></pre> <p><strong>ERC-721 Token</strong></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"> Erc721Asset</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> balance</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</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-variable"> metadata</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"> tokenId</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> tokenURI</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>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p>Example:</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">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48</span><span class="z-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-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">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">metadata</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">Thor&#39;s hammer</span><span class="z-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">THOR</span><span class="z-punctuation z-definition z-string">&quot;</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 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 class="z-support"> &quot;</span><span class="z-support">tokenURI</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ipfs://hash</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="capabilities">Capabilities</h3> <p>If the wallet is using <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/0848f06f6cfc29ce619bccdd5035c1d500033b21/CAIPs/caip-25.md">CAIP-25</a> authorization, wallet <strong>SHOULD</strong> include <code>wallet_getAssets</code> in the <code>methods</code> array in <code>sessionScopes</code> of <code>eip155</code> namespace.</p> <p>If the wallet supports <a href="https://wg-eips.ritovision.com/5792/">ERC-5792</a> wallet <strong>SHOULD</strong> respond on <code>wallet_getCapabilities</code> request using the <code>assetDiscovery</code> key. Value should be an object with <code>supported</code> key and value <code>true</code> Wallet <strong>SHOULD</strong> include this for every chainId.</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">0xa</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">assetDiscovery</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 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="security-considerations">Security Considerations</h2> <!-- TODO --> <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-07T00:00:00+00:00 2026-02-11T14:48:25+00:00 lex-clinichttps://github.com/lex-clinic https://wg-eips.ritovision.com/7827/

Manage a JSON object onchain with per-key version history and a REST-like read interface.

<h2 id="abstract">Abstract</h2> <p>This EIP defines a smart contract interface that allows for managing a JSON object within a smart contract, offering both real-time JSON output and a version-controlled history for each value. The interface includes methods to retrieve the most recent JSON state as well as the version history of each key in the JSON object. This approach supports REST developers familiar with JSON-based data interactions, thus improving accessibility for developers new to Web3 and Ethereum.</p> <h2 id="motivation">Motivation</h2> <p>With an increasing number of developers from RESTful backgrounds joining the Ethereum ecosystem, there is a need for a contract interface that allows developers to easily interact with structured JSON data. This EIP aims to create a universal standard that provides JSON data management and version control functionality in a straightforward and REST-like way, making Ethereum more accessible and developer-friendly.</p> <h2 id="specification">Specification</h2> <p>The contract interface includes the following methods:</p> <h3 id="read-methods">Read Methods</h3> <ol> <li> <p><strong><code>json()</code></strong></p> <ul> <li><strong>Output:</strong> <code>string</code> (a JSON string representing the entire object)</li> <li><strong>Description:</strong> Returns the current state of the JSON object as a string.</li> </ul> </li> <li> <p><strong><code>version(string key)</code></strong></p> <ul> <li><strong>Inputs:</strong> <ul> <li><code>key</code> (<code>string</code>): The JSON key whose version history is requested.</li> </ul> </li> <li><strong>Output:</strong> <code>string</code> (a JSON array as a string)</li> <li><strong>Description:</strong> Returns an array of all versions of the specified key's value in JSON format. The array is ordered chronologically, with the earliest version at index 0 and the most recent version at the highest index.</li> </ul> </li> </ol> <h3 id="write-method">Write Method</h3> <ol start="3"> <li><strong><code>write(string[] keys, string[] values, bool replace)</code></strong> <ul> <li><strong>Inputs:</strong> <ul> <li><code>keys</code> (<code>string[]</code>): Array of keys to be added or updated in the JSON object.</li> <li><code>values</code> (<code>string[]</code>): Array of values corresponding to the keys.</li> <li><code>replace</code> (<code>bool</code>): If <code>true</code>, replaces existing values; if <code>false</code>, reverts if the key already exists.</li> </ul> </li> <li><strong>Output:</strong> None</li> <li><strong>Description:</strong> Writes new values to the JSON object, either adding a new key or updating an existing one, based on the <code>replace</code> parameter.</li> </ul> </li> </ol> <h3 id="solidity-interface-non-normative">Solidity Interface (non-normative)</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"> IERC7827</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> json</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 class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> key</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"> write</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> keys</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> values</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> replace</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><h3 id="examples-non-normative">Examples (non-normative)</h3> <p>Assume the following scenario with key-value management:</p> <ol> <li><strong>Initial Write:</strong></li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name">write</span><span>(</span><span>[</span><span class="z-string">&quot;name&quot;</span><span>]</span><span>,</span><span> [</span><span class="z-string">&quot;Alice&quot;</span><span>]</span><span>,</span><span class="z-constant"> false</span><span>)</span><span>;</span></span></code></pre> <ul> <li>JSON Output:</li> </ul> <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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Alice</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span></span></code></pre> <ul> <li>Version History of <code>name</code>:</li> </ul> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Alice</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span></code></pre> <ol start="2"> <li><strong>Updating Value with Replacement:</strong></li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name">write</span><span>(</span><span>[</span><span class="z-string">&quot;name&quot;</span><span>]</span><span>,</span><span> [</span><span class="z-string">&quot;Bob&quot;</span><span>]</span><span>,</span><span class="z-constant"> true</span><span>)</span><span>;</span></span></code></pre> <ul> <li>JSON Output:</li> </ul> <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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Bob</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span></span></code></pre> <ul> <li>Version History of <code>name</code>:</li> </ul> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Alice</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">Bob</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span></code></pre> <ol start="3"> <li><strong>Attempting to Update without Replacement (reverts if <code>name</code> exists):</strong></li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name">write</span><span>(</span><span>[</span><span class="z-string">&quot;name&quot;</span><span>]</span><span>,</span><span> [</span><span class="z-string">&quot;Charlie&quot;</span><span>]</span><span>,</span><span class="z-constant"> false</span><span>)</span><span>;</span></span></code></pre> <ul> <li>This transaction reverts because <code>name</code> already exists and <code>replace</code> is <code>false</code>.</li> </ul> <h2 id="rationale">Rationale</h2> <ol> <li> <p><strong>REST-like Access via JSON Method</strong><br /> The <code>json</code> method enables developers to interact with the contract as if it were a RESTful API, improving accessibility for those familiar with traditional web development paradigms.</p> </li> <li> <p><strong>Version Management via Version Method</strong><br /> The <code>version</code> method provides a straightforward version control system for each key, offering a history of values that developers can reference without altering the main JSON structure. This maintains immutability for historical values while allowing updates to be appended.</p> </li> <li> <p><strong>Compatibility with Web3 Abstractions</strong><br /> Ensuring a simple and standardized ABI is essential for usability with Web3 libraries, thus enhancing developer experience and facilitating onboarding.</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is a new standard and does not interfere with existing standards. However, it introduces JSON object handling and version control, which may have specific considerations for gas optimization.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>JSON encoding onchain is inherently gas-heavy. This standard limits complexity by treating values as strings and leaving encoding efficiency to client libraries.</li> <li>Contracts <strong>SHOULD</strong> guard against unbounded array writes, which could otherwise make the <code>write</code> method expensive or DOS-prone.</li> <li>Care should be taken to handle large JSON objects efficiently to avoid excessive gas consumption.</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> 2024-11-07T00:00:00+00:00 2026-02-11T14:48:25+00:00 Kieran Goodaryhttps://github.com/IAmKio Pillar Wallethttps://github.com/pillarwallet Luke Wickenshttps://github.com/lbw33 Rana Khouryhttps://github.com/RanaBug https://wg-eips.ritovision.com/7845/

A universal data model that an Orchestrator can understand to help fulfil a request for a solution from a wallet or any other system.

<h2 id="abstract">Abstract</h2> <blockquote> <p>"Hey smart speaker, swap my Shiba Inu for Pillar"</p> </blockquote> <blockquote> <p>"Assistant, how much USDC can I buy with what's in my wallet?"</p> </blockquote> <blockquote> <p>"Send 10 OP to Vitalik and 5 PEPE to Deimantas"</p> </blockquote> <p>The Universal Orchestrator RPC aims to standardise the <strong>minimum shape and requirements</strong> of a <strong>request for a solution</strong> <em><strong>from</strong></em> an arbitrary system managing an Ethereum wallet <em><strong>to</strong></em>, ultimately, an Orchestrator.</p> <p>An arbitrary system could be a website, device, app, server program etc - anything that manages an Ethereum wallet, <strong>speaks Ethereum JSON-RPC</strong> and is looking to request solutions from an Orchestrator.</p> <p>All solutions from an Orchestrator are ChA¹ (Chain Abstraction-first) by default.</p> <p><img src="https://wg-eips.ritovision.com/7845/./assets/flow.jpg" alt="Flow" /></p> <h2 id="motivation">Motivation</h2> <p>Data model standards can be written in any shape. A system will often expose their external interface but require that the request to the aforementioned interface is modelled in a way that the service understands. This creates a huge level of inconsistency and in turn makes Orchestrator interoperability more difficult.</p> <p>Orchestrators will become more widespread and numerous over time. This is especially true with the advent of Artificial Intelligence (AI) driven systems, the continued advancement of Human Computer Interaction (HCI) devices (especially those that are voice controlled) and the emergence of Extended Reality (XR) platforms.</p> <p>Standardising the request object that an Orchestrator can understand from a wallet will drive adoption and make decentralised app development easier for developers that don't know how to make on-chain transactions or have the required technical understanding of block building systems.</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 Orchestrator's external interface(s) that expose functionality to an end-user application or another system MUST use JavaScript Object Notation (JSON).</p> <p>The following data definitions are available and MUST <strong>prefer chain abstraction (ChA¹)</strong>, unless stated. Chain abstraction means that, where possible, should an asset span multiple chains - expect a solution from an Orchestrator to use and send assets to and from the supported chains to deliver a complete and cost-effective solution.</p> <p>The following sequence diagram shows the flow of events in this proposal:</p> <p><img src="https://wg-eips.ritovision.com/7845/./assets/sequence.png" alt="Sequence Diagram" /></p> <p>This specification follows the top level data shape of Ethereum JSON-RPC requests, as shown below:</p> <h3 id="request">Request</h3> <p>The request definition is what a wallet sends to an Orchestrator for solutions to one or more problems. The request follows the specification from Ethereum JSON-RPC.</p> <h4 id="rpc">RPC</h4> <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"> Rpc</span><span>: </span><span>{</span></span> <span class="giallo-l"><span class="z-variable"> id</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span class="z-variable"> jsonrpc</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span class="z-variable"> method</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span class="z-variable"> params</span><span class="z-keyword">:</span><span class="z-entity z-name"> Problem</span><span>[</span><span>]</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The top level definition is an Ethereum RPC object.</p> <ul> <li>The <code>id</code> property is a random number that you can assign for your own purposes.</li> <li>The <code>jsonrpc</code> property takes a <code>string</code> that represents the version of JSON-RPC being used. Usually <code>"2.0"</code>.</li> <li>The <code>method</code> property is the method call intended for the Orchestrator, and by default CAN be <code>orchestrator_findSolutions</code>.</li> <li>The <code>params</code> property contains an array of <code>Problem</code> objects, and is REQUIRED. The Problem object is defined below.</li> </ul> <h4 id="problem">Problem</h4> <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"> Problem</span><span>: </span><span>{</span></span> <span class="giallo-l"><span class="z-variable"> actions</span><span class="z-keyword">:</span><span class="z-entity z-name"> Action</span><span>[</span><span>]</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span class="z-variable"> chainId</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>Problem</code> definition has just one REQUIRED property, <code>actions</code>. The <code>Problem</code> interface leaves space for additional properties in future network upgrades and existing or emerging standards.</p> <ul> <li>The <code>actions</code> property takes an <code>array</code> of <code>Action</code> objects, defined below, and is REQUIRED.</li> <li>The <code>chainId</code> takes a <code>number</code>, representing the chain ID, and is OPTIONAL. <ul> <li>If no <code>chainId</code> is provided: <ul> <li><code>chainId</code> property MUST assume <code>1</code></li> </ul> </li> </ul> </li> </ul> <h4 id="action">Action</h4> <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"> Action</span><span>: </span><span>{</span></span> <span class="giallo-l"><span class="z-variable"> from</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span class="z-variable"> towards</span><span class="z-keyword">:</span><span> (</span><span class="z-entity z-name">Asset</span><span class="z-keyword">|</span><span class="z-entity z-name">Destination</span><span>)</span><span>[</span><span>]</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span class="z-variable"> with</span><span class="z-keyword">:</span><span class="z-entity z-name"> Offering</span><span>[</span><span>]</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span class="z-variable"> functionCallName</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span class="z-variable"> functionCallData</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span class="z-variable"> deadline</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>Action</code> definition has several properties that indicate the desired action. The set properties determine the action that needs to be solved.</p> <ul> <li>The <code>from</code> property is REQUIRED, takes a <code>string</code> and represents the wallet that this <code>Action</code> is for.</li> <li>The <code>towards</code> property is REQUIRED, takes an <code>array</code> of either an <code>Asset</code> or a <code>Destination</code> type and represents where this <code>Action</code> is targeted towards.</li> <li>The <code>with</code> property is OPTIONAL, takes an <code>array</code> of <code>Offering</code> type and represents what assets the wallet is prepared to offer to facilitate this <code>Action</code> <ul> <li>If the <code>with</code> property contains no <code>Offering</code> entries, then the Orchestrator MUST consider all assets available in the address space for an <code>Offering</code>.</li> </ul> </li> <li>The <code>type</code> property is OPTIONAL, takes a <code>string</code> and is intended to help classify this action. Examples might include, but are not limited to - <code>transfer</code>, <code>swap</code>, <code>call</code> etc and is intended to assist the Orchestrator with the action. <ul> <li>If no <code>type</code> is provided, then 'transfer' MUST be assumed</li> </ul> </li> <li>The <code>functionCallName</code> property is OPTIONAL, takes a <code>string</code> and represents the function name to call against the <code>towards</code> property. If this is defined, the Orchestrator can be assumed that this Action desires to call a smart contract as part of the action.</li> <li>The <code>functionCallData</code> property is OPTIONAL, takes a <code>string</code> and represents the data payload for <code>functionCallName</code>. If this is defined but <code>functionCallName</code> is not, this property SHOULD be ignored.</li> <li>The <code>deadline</code> property is OPTIONAL, takes a <code>number</code> and represents a wallet-defined unix timestamp for when an action should have a solution by. Useful for high throughput systems, or time sensitive actions.</li> </ul> <h4 id="asset">Asset</h4> <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"> Asset</span><span>: </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 class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span class="z-variable"> chainId</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The Asset definition defines an asset in question. This definition prefers chain abstraction.</p> <ul> <li>The <code>symbol</code> property is OPTIONAL, takes a <code>string</code> and represents the symbol of the Asset in question. <ul> <li>if no <code>symbol</code> is provided, <code>address</code> must be used</li> </ul> </li> <li>The <code>address</code> property is OPTIONAL, takes a <code>string</code> and represents the <code>address</code> of the smart contract for this <code>Asset</code>. <ul> <li>if no <code>address</code> is provided, the native gas token MUST be used</li> </ul> </li> <li>The <code>chainId</code> property is OPTIONAL, takes a <code>number</code> and represents the chain that this asset resides on. Useful for direct targeting of an <code>Asset</code> on a particular chain.</li> <li>If no <code>chainId</code> is provided: - The Orchestrator is free to use any corresponding asset on any chain to facilitate the action</li> </ul> <h4 id="destination">Destination</h4> <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"> Destination</span><span>: </span><span>{</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span class="z-variable"> chainId</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The Destination definition defines a direct target and is used in scenarios where the Orchestrator interpretation MUST NOT be used.</p> <ul> <li>The <code>address</code> property is REQUIRED and takes a <code>string</code> that represents the address space for this <code>Destination</code>.</li> <li>The <code>chainId</code> property is REQUIRED and takes a <code>number</code> and represents the chain the above <code>address</code> property resides on.</li> </ul> <h4 id="offering">Offering</h4> <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"> Offering</span><span>: </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 class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> SHOULD</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> SHOULD</span></span> <span class="giallo-l"><span class="z-variable"> amount</span><span class="z-keyword">:</span><span> (</span><span class="z-support">number</span><span class="z-keyword">|</span><span class="z-support">string</span><span>)</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span class="z-variable"> chainId</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>Offering</code> definition defines what the requester is willing to spend from their wallet in order to facilitate the action being solved.</p> <ul> <li>The <code>symbol</code> property SHOULD be specified and represents the symbol of the <code>Offering</code> in question <ul> <li>If no <code>symbol</code> is provided, the address MUST be used</li> </ul> </li> <li>The <code>address</code> property SHOULD be specified and takes a <code>string</code> that represents the address space for this <code>Offering</code>. <ul> <li>If no <code>address</code> is provided, the native gas token MUST be used</li> </ul> </li> <li>The <code>amount</code> property is OPTIONAL and represents the amount to be offered as part of the <code>Action</code>. Accepts either a <code>number</code>, which represents an ether unit, or a <code>string</code> which can be used for BigNumbers. <ul> <li>If no amount is provided, the maximum value of the address, symbol or native gas unit must be assumed</li> </ul> </li> <li>The <code>chainId</code> property is OPTIONAL and takes a <code>number</code> that represents the chain the above <code>address</code> property resides on. <ul> <li>If no <code>chainId</code> is provided: <ul> <li><code>address</code> MUST NOT be used</li> <li><code>symbol</code> MUST be used (ChA¹)</li> <li>If no higher level <code>chainId</code> property exists in the <code>Problem</code> property <ul> <li>The Orchestrator is free to use any corresponding asset on any chain to facilitate the action (ChA¹)</li> </ul> </li> </ul> </li> </ul> </li> </ul> <h3 id="response">Response</h3> <p>The response definition is what an Orchestrator sends back as a response to the request for solutions from a wallet. The response, like the request, follows the specification from Ethereum JSON-RPC.</p> <h4 id="rpc-1">RPC</h4> <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"> Rpc</span><span>: </span><span>{</span></span> <span class="giallo-l"><span class="z-variable"> id</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span class="z-variable"> jsonrpc</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span class="z-variable"> result</span><span class="z-keyword">:</span><span class="z-entity z-name"> Solution</span><span>[</span><span>]</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The top level object is an Ethereum RPC object.</p> <ul> <li>The <code>id</code> property is REQUIRED, takes a <code>string</code> and MUST correlate to the same <code>number</code> that was received as part of the request object to the Orchestrator.</li> <li>The <code>jsonrpc</code> property is REQUIRED, takes a <code>string</code> and represents the version of JSON-RPC being used. Usually <code>"2.0"</code>.</li> <li>The <code>result</code> property is REQUIRED and takes an array of <code>Solution</code> objects. The <code>Solution</code> object is defined below.</li> </ul> <h4 id="solution">Solution</h4> <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"> Solution</span><span>: </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 class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span class="z-variable"> description</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span class="z-variable"> transactions</span><span class="z-keyword">:</span><span class="z-entity z-name"> Transaction</span><span>[</span><span>]</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span class="z-variable"> deadline</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The above <code>Solution</code> interface is the <em>solution</em> to a <em>problem</em> requested above. The <code>Solution</code> MUST be in the same order to a <code>Problem</code> that was requested.</p> <ul> <li>The <code>name</code> property is REQUIRED, takes a <code>string</code> and represents a short, non-technical and user-friendly, name of the solution.</li> <li>The <code>description</code> property is OPTIONAL, takes a <code>string</code> and represents a longer, non-technical and user-friendly, description of the solution.</li> <li>The <code>transactions</code> property is REQUIRED, takes an <code>array</code> of <code>Transaction</code> objects and represents one or more transactions needed for the user to execute the solution.</li> <li>The <code>deadline</code> property is OPTIONAL, takes a <code>number</code> and represents a unix timestamp by which this <code>Solution</code> should be executed. This is defined by the Orchestrator.</li> </ul> <h4 id="transaction">Transaction</h4> <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"> Transaction</span><span>: </span><span>{</span></span> <span class="giallo-l"><span class="z-variable"> to</span><span class="z-keyword">:</span><span class="z-entity z-name"> Destination</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span class="z-variable"> chainId</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span class="z-variable"> amount</span><span class="z-keyword">:</span><span> (</span><span class="z-support">number</span><span class="z-keyword">|</span><span class="z-support">string</span><span>)</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span class="z-variable"> calldata</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The above <code>Transaction</code> interface is a transaction definition that allows a wallet to perform their solution to a problem. There may be 1 or more transactions for a <code>Solution</code>.</p> <ul> <li>The <code>to</code> property is REQUIRED, takes a <code>Destination</code> type and represents the target for this Solution.</li> <li>The <code>chainId</code> property is REQUIRED, takes a number and represents the chain that this <code>Transaction</code> is targeted at. The <code>chainId</code> is REQUIRED here because the wallet MUST know where to send assets from as an origin due to the existence of multichain assets.</li> <li>The <code>amount</code> property is REQUIRED and represents the amount to be sent as part of the <code>Transaction</code>. Accepts either a <code>number</code>, which represents an ether unit, or a <code>string</code> which can be used for BigNumbers.</li> </ul> <h2 id="rationale">Rationale</h2> <ul> <li>Uses the Ethereum JSON-RPC JSON wrapper for greater compatibility.</li> <li>The interface definitions use only generic primitive types to ensure wide compatibility for any programming language.</li> <li>The interface definitions defined in this ERC attempts to cover as many scenarios as possible, from an Orchestrator perspective that a wallet may ask for, but focuses on core blockchain functionality.</li> <li>Certain high-level definitions, such as the <code>Problem</code> object definition, are sparse by design to allow space for future features introduced by other ERC's or network upgrades.</li> <li>Terminology is targeted towards a non-technical lexicon to aid in wider adoption and understanding.</li> <li>Nearly all options are REQUIRED, SHOULD and OPTIONAL to allow for both wallet and Orchestrator flexibility in providing solutions for the wallet request.</li> <li>It's understood that the Orchestrator interpretations and implementations will vary, so where possible the specification enforces REQUIRED and MUST to provide a universal level of service to an end-user or another service.</li> <li>The specification is <strong>NOT</strong> intended to standardise or modify the internal data structure or communication layer of an Orchestrator.</li> <li>Other parameters that could be considered, such as gas limits and estimations, are delegated back to the wallet as ultimately it is the wallet that will execute the solution(s).</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="example-requests-and-responses-for-solutions">Example requests and responses for solutions</h3> <p>The following examples show a few common scenarios with their requests to, and from, an Orchestrator. All examples are chain abstracted (ChA¹) by default, unless specified.</p> <h4 id="sending-an-erc-20-token-to-another-address">Sending an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token to another address</h4> <p>The following request performs an action:</p> <ul> <li>from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165</li> <li>towards address 0x50840CE036eEf2005d3c4d6f6Eb65f8116a01629 <ul> <li>with symbol USDC, amount 5</li> </ul> </li> </ul> <blockquote> <p>[!NOTE] Notes: All requests for solutions should be chain abstracted (ChA¹) by default. The Orchestrator &gt; &gt; can check for 5 USDC on any chain for the above "from" address, and send a solution that receives &gt; the 5 USDC on any other chain.</p> </blockquote> <h5 id="request-to-orchestrator">Request to Orchestrator</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"> 1234</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">orchestrator_findSolutions</span><span class="z-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">problems</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">actions</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">from</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">towards</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">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x50840CE036eEf2005d3c4d6f6Eb65f8116a01629</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">with</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">symbol</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">USDC</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">amount</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 5</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><h5 id="response-from-orchestrator">Response from Orchestrator</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"> 1234</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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Send 5 USDC</span><span class="z-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">Send 5 USDC from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165 to 0x50840CE036eEf2005d3c4d6f6Eb65f8116a01629</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">transactions</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">0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48</span><span class="z-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">calldata</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">value</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 0</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="swapping-native-token-to-usdc">Swapping native token to USDC</h4> <p>The following request performs an action:</p> <ul> <li>from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165</li> <li>towards symbol USDC <ul> <li>with: 0.1</li> </ul> </li> </ul> <blockquote> <p>[!NOTE] Notes: All requests for solutions should be chain abstracted (ChA¹) by default. The Orchestrator can take 0.1 native asset from any chain in return for USDC on any chain.</p> </blockquote> <h5 id="request-to-orchestrator-1">Request to Orchestrator</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"> 1337</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">orchestrator_findSolutions</span><span class="z-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">problems</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">actions</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">from</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">towards</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">symbol</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">USDC</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">with</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">amount</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 0.1</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><h5 id="response-from-orchestrator-1">Response from Orchestrator</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"> 1337</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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Swap 0.1 ETH for 371.498 USDC</span><span class="z-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">Swapping 0.1 ETH from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165 to 371.498 USDC via Uniswap</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">transactions</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">0x...</span><span class="z-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">calldata</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">value</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></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">0x...</span><span class="z-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">calldata</span><span class="z-support">&quot;</span><span>:</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></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-constant"> 0.1</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="swapping-multiple-tokens-to-usdc">Swapping multiple tokens to USDC</h4> <p>The following request performs an action:</p> <ul> <li>from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165</li> <li>towards symbol USDC</li> <li>with SHIB and / or Pillar</li> </ul> <blockquote> <p>[!NOTE] Notes: All requests for solutions should be chain abstracted (ChA¹) by default. The Orchestrator can take any amount of SHIB and / or Pillar from any chain in return for an exchanged amount of USDC on any chain.</p> </blockquote> <h5 id="request-to-orchestrator-2">Request to Orchestrator</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"> 1234</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">orchestrator_findSolutions</span><span class="z-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">problems</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">actions</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">from</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">towards</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">symbol</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">USDC</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">with</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">symbol</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">SHIB</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">symbol</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Pillar</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></code></pre><h5 id="response-from-orchestrator-2">Response from Orchestrator</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"> 1337</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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Swap 171,246 SHIB and 1004.72 Pillar for 10 USDC</span><span class="z-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">Swapping 171,246 SHIB and 1004.72 Pillar from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165 to 10 USDC via Uniswap</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">transactions</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">0x...</span><span class="z-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">calldata</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">value</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></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">0x...</span><span class="z-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">calldata</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">value</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></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">0x...</span><span class="z-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">calldata</span><span class="z-support">&quot;</span><span>:</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></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-constant"> 0.1</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="sending-an-erc-20-token-to-multiple-addresses">Sending an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token to multiple addresses</h4> <p>The following request performs the following actions:</p> <ul> <li>Action 1 <ul> <li>from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165</li> <li>towards address 0x50840CE036eEf2005d3c4d6f6Eb65f8116a01629</li> <li>with 5 USDC</li> </ul> </li> <li>Action 2 <ul> <li>from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165</li> <li>towards address 0xFCd239451346238B5560511Ae47A0b82b1bbE9f0</li> <li>with 100 PLR</li> </ul> </li> </ul> <blockquote> <p>[!NOTE] Notes: All requests for solutions should be chain abstracted (ChA¹) by default. The Orchestrator can move the specified asset amounts on any chain where the asset exists in the "from" address.</p> </blockquote> <h5 id="request-to-orchestrator-3">Request to Orchestrator</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"> 1000</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">orchestrator_findSolutions</span><span class="z-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">problems</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">actions</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">from</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">towards</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">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x50840CE036eEf2005d3c4d6f6Eb65f8116a01629</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">with</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">symbol</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">USDC</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">amount</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 5</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">from</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">towards</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">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xFCd239451346238B5560511Ae47A0b82b1bbE9f0</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">with</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">symbol</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">PLR</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">amount</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 100</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><h5 id="response-from-orchestrator-3">Response from Orchestrator</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"> 1000</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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Send 5 USDC to 0x...629 and 100 PLR to 0x...9f0</span><span class="z-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">Send 5 USDC to 0x50840CE036eEf2005d3c4d6f6Eb65f8116a01629 and 100 PLR to 0xFCd239451346238B5560511Ae47A0b82b1bbE9f0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">transactions</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">0x...</span><span class="z-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">calldata</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">value</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></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">0x...</span><span class="z-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">calldata</span><span class="z-support">&quot;</span><span>:</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></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-constant"> 0</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="calling-a-smart-contract-function-on-polygon-inscribing-a-message-which-costs-1-usdc">Calling a Smart Contract function on Polygon: Inscribing a message which costs 1 USDC</h4> <p>The following request performs an action:</p> <ul> <li>from 0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165</li> <li>towards address 0x50840CE036eEf2005d3c4d6f6Eb65f8116a01629 on chain 137</li> <li>with 1 USDC</li> <li>calling "inscribe" with "0x..."</li> </ul> <blockquote> <p>[!NOTE] Notes: All requests for solutions should be chain abstracted (ChA¹) by default - HOWEVER in this example, the <code>chainId</code> property on the <code>Destination</code> interface has been specified. The operation should now be locked to the specified chain. Because <code>functionCallName</code> and <code>functionCallData</code> exist, the Orchestrator can infer that this is a smart contract call and act accordingly.</p> </blockquote> <h5 id="request-to-orchestrator-4">Request to Orchestrator</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"> 420</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">orchestrator_findSolutions</span><span class="z-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">problems</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">actions</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">from</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbafB4E1EFA94B359e2E175CF6156AedA2cACa165</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">towards</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">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x50840CE036eEf2005d3c4d6f6Eb65f8116a01629</span><span class="z-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"> 137</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">with</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">symbol</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">USDC</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">amount</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</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">functionCallName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">inscribe</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">functionCallData</span><span class="z-support">&quot;</span><span>:</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> <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><h5 id="response-from-orchestrator-4">Response from Orchestrator</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"> 420</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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Inscribe with 1 USDC</span><span class="z-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">Call the Inscribe function with 1 USDC on Polygon</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">transactions</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">0x...</span><span class="z-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"> 137</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">calldata</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">value</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></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">0x...</span><span class="z-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"> 137</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">calldata</span><span class="z-support">&quot;</span><span>:</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></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-constant"> 0</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><h2 id="security-considerations">Security Considerations</h2> <h3 id="orchestrator-reputation">Orchestrator reputation</h3> <p>The ability for anyone to build an Orchestrator inherently brings the opportunity for code errors and therefore a degraded service. Orchestrators may also be abandoned over time. A reputation score should be leveraged by the Orchestrator to determine if the Orchestrator is fit for purpose. This should be up to the requesting system or wallet to determine.</p> <h3 id="orchestrator-producing-dishonest-solutions">Orchestrator producing dishonest solutions</h3> <p>An Orchestrator may return transactions as part of a solution that are wrong or attempt to take more than what was asked of it. Where possible, the Orchestrator should validate returned transaction address destinations and any other data.</p> <h3 id="orchestrator-personality-variations">Orchestrator personality variations</h3> <p>Whilst not a security consideration per-se, some Orchestrators may gravitate towards their own business targets which may skew the outcome of Orchestrator solutions. The systems or wallets requesting solutions from Orchestrators should be mindful of this unless it is intended.</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-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 hellohanchenhttps://github.com/hellohanchen https://wg-eips.ritovision.com/7806/

Extensible intent-centric EOA smart account interface design to support batch execution, gas sponsorship and more other functionalities.

<h2 id="abstract">Abstract</h2> <p>This proposal defines a standard interface for intent-centric smart accounts. It enables externally owned accounts (EOAs) to delegate contract code to a smart account implementation, allowing them to sign intents. These intents can then be executed by solvers (or relayers) on behalf of the account owner, streamlining interactions and expanding the capabilities of EOAs.</p> <h2 id="motivation">Motivation</h2> <p>Account Abstraction (AA) is a highly discussed topic in the blockchain industry, as it enhances the programmability of accounts, enabling features such as:</p> <ul> <li><strong>Batch Execution</strong></li> <li><strong>Gas Sponsorship</strong></li> <li><strong>Access Control</strong></li> </ul> <p>The introduction of <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> established a permissionless standard for AA, unlocking a wide range of powerful features. However, ERC-4337 has several limitations:</p> <ul> <li><strong>Complexity</strong>: The standard requires multiple interdependent components, including the Account, EntryPoint, Paymaster, Bundler, and additional plugins (<a href="https://wg-eips.ritovision.com/6900/">ERC-6900</a>, <a href="https://wg-eips.ritovision.com/7579/">ERC-7579</a>. Running a bundler demands significant engineering expertise and introduces operational overhead.</li> <li><strong>Compatibility</strong>: Component dependencies make upgrades cumbersome, often requiring multiple smart contracts to be updated simultaneously. This creates fragmentation within the ecosystem. one version update, also divides the ecosystem.</li> <li><strong>Cost</strong>: Processing <code>UserOperation</code> transactions consumes a high amount of gas.</li> <li><strong>Trust Assumption</strong>: Despite being designed as a permissionless standard, ERC-4337 still relies on centralized entities. Paymasters, for instance, are typically centralized, as they must either trust account owners to reimburse gas costs or manage external funding sources. Similarly, bundlers operate within a miner extractable value (MEV) environment, requiring users to trust them for transaction inclusion.</li> </ul> <p><a href="https://wg-eips.ritovision.com/7521/">ERC-7521</a> introduced a smart contract account (SCA) solution with an intent-centric design. It allows solvers to fulfill account owners' intents while maintaining flexibility for custom execution logic and ensuring forward compatibility.</p> <p>With the introduction of <code>SET_CODE_TX_TYPE=0x04</code>, EOAs can now set contract code dynamically, granting them programmability similar to SCAs. This presents an opportunity to develop a new standard that extends AA capabilities to EOAs while addressing the aforementioned challenges.</p> <p>By simplifying execution, improving efficiency, and enhancing user experience, this proposal aims to accelerate the adoption of intent-centric account abstraction smart contracts.</p> <h3 id="solvers-relayers-paymasters-and-bundlers-all-in-one">Solvers, Relayers, Paymasters, and Bundlers—All in One</h3> <p>In an intent-centric system, solvers play a crucial role in fulfilling user intents and are rewarded accordingly. This proposal introduces an open execution model, where any solver can participate, fostering a competitive environment that benefits users.</p> <p>With integrated gas abstraction, solvers can cover gas fees using native tokens while receiving other tokens from the EOA account as compensation. Additionally, solvers can further optimize costs by bundling multiple intent executions into a single blockchain transaction.</p> <p>Each solver is free to develop its own strategies for maximizing profitability. This proposal does not impose restrictions on how solvers execute intents, ensuring flexibility and adaptability in diverse execution scenarios.</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="userintent-schema"><code>UserIntent</code> schema</h3> <p>Each intent is a packed data structure containing sufficient information about the operations the account owner wants to execute. The core structure of a <code>UserIntent</code> object is as follows:</p> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td><code>sender</code></td><td><code>address</code></td><td>The address of the account initiating the intent.</td></tr> <tr><td><code>standard</code></td><td><code>address</code></td><td>The <code>IStandard</code> implementation responsible for validating and parsing the <code>UserIntent</code></td></tr> <tr><td><code>header</code></td><td><code>bytes</code></td><td>Metadata associated with the <code>UserIntent</code>, interpreted by <code>standard</code>. Stored as bytes for flexibility.</td></tr> <tr><td><code>instructions</code></td><td><code>bytes[]</code></td><td>The execution details of the <code>UserIntent</code>, interpreted by <code>standard</code>. Stored as <code>bytes[]</code> to allow flexibility.</td></tr> <tr><td><code>signatures</code></td><td><code>bytes[]</code></td><td>Validatable signatures required for execution, interpreted by <code>standard</code>.</td></tr> </tbody></table> <h4 id="fields-explanations">Fields Explanations</h4> <ul> <li><code>header</code>: The <code>bytes header</code> can carry information about how to validate the intent or how to prevent double-spending. For example, <code>header</code> can contain an <code>uint256 nonce</code> to check if the <code>nonce</code> is used already.</li> <li><code>instructions</code>: These <code>bytes instructions</code> can just be concatenated <code>(address,value,calldata)</code> or can be standardized values, for example <code>(erc20TokenAddress,1000)</code> means the <code>instructions</code> can use up to 1000 of the specified <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token. It is NOT REQUIRED that all <code>instructions</code> MUST be provided by the EOA owner to allow dynamically carry out other operations during intent executions, but the <code>IStandard</code> design needs to carefully handle this case.</li> <li><code>signatures</code>: The <code>bytes signatures</code> field can support different signing methods. It is NOT REQUIRED that all <code>signatures</code> MUST be provided by the EOA owner, some of them MAY be provided by solver, relayer or anyone else.</li> </ul> <h3 id="pack-userintent-as-bytes">Pack <code>UserIntent</code> as Bytes</h3> <p>The <code>UserIntent</code> object is packed and encoded into <code>bytes calldata userIntent</code>. There is no strict schema requirement for the data structure. Each <code>IAccount</code> and <code>IStandard</code> implementation can define its own encoding and decoding methods for handling the <code>bytes</code> data.</p> <p>Here is an example of packed-encoded format:</p> <table><thead><tr><th>Section</th><th>Value Type</th><th>Description</th></tr></thead><tbody> <tr><td>userIntent[0:20]</td><td><code>address</code></td><td><code>sender</code></td></tr> <tr><td>userIntent[20:40]</td><td><code>address</code></td><td><code>standard</code></td></tr> <tr><td>userIntent[40:42]</td><td><code>uint16</code></td><td>Length of <code>header</code></td></tr> <tr><td>userIntent[42:44]</td><td><code>uint16</code></td><td>Length of <code>instructions</code></td></tr> <tr><td>userIntent[44:46]</td><td><code>uint16</code></td><td>Length of <code>signatures</code></td></tr> <tr><td>Next <code>headerLength</code> bytes</td><td><code>bytes</code></td><td>The actual <code>header</code> data</td></tr> <tr><td>Next <code>instructionsLength</code> bytes</td><td><code>bytes</code></td><td>The actual <code>instructions</code> data</td></tr> <tr><td>Next <code>signatureLength</code> bytes</td><td><code>bytes</code></td><td>The actual <code>signatures</code> data</td></tr> <tr><td>Remaining bytes</td><td><code>bytes</code></td><td>Extra data, such as nested intents for further execution</td></tr> </tbody></table> <h3 id="istandard-interface"><code>IStandard</code> Interface</h3> <p>Each standard defines how to parse and validate a <code>UserIntent</code>. Implementations of standard must conform to the <code>IStandard</code> 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"> IStandard</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * Validate user&#39;s intent</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"> returning validation result, the type uses bytes4 for extensibility purpose</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"> values representing validation outcomes</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"> validateUserIntent</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> intent</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">bytes4</span><span class="z-variable"> result</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"> * Unpack user&#39;s intent, it is RECOMMENDED to validate intent while unpacking to save gas</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"> returning unpacked result, the type uses bytes for extensibility purpose</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"> unpacked result status</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"> operations</span><span class="z-comment"> unpacked operations that can be executed by the IAccount, NOT REQUIRED to match UserIntent.instructions</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"> unpackOperations</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> intent</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">bytes4</span><span class="z-variable"> result</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"> operations</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>IStandard</code> interface is responsible for defining and enforcing the validation logic for <code>UserIntent</code> objects.</p> <p>It operates similarly to the <code>EntryPoint</code> in ERC-4337 and ERC-7521.</p> <p>The extensibility of <code>bytes4</code> return types allows future upgrades without modifying the function signatures.</p> <h3 id="iaccount-interface"><code>IAccount</code> Interface</h3> <p>On the account side, <code>IAccount</code> provides the interface for executing <code>bytes calldata intent</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"> IAccount</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * Execute user&#39;s intent</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"> returning execution result, the type uses bytes for extensibility purpose</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"> values representing execution outcomes</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"> executeUserIntent</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> intent</span><span>)</span><span class="z-storage z-type"> external</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>}</span></span></code></pre> <p>Using <code>SET_CODE_TX_TYPE=0x04</code>, EOAs can delegate contract code to an <code>IAccount</code> implementation, enabling them to function as smart accounts. A single account implementation can be shared across multiple EOAs, meaning:</p> <ul> <li>It only needs to be deployed and audited once.</li> <li>Each EOA owner is responsible for delegating their account to a secure <code>IAccount</code> implementation.</li> </ul> <p>It is RECOMMENDED that each account leverages <code>IStandard</code> to validate and unpack operations, check <strong>Reference Implementation</strong> for examples. Account smart contract can be stateless to avoid sharing storage space with other delegated contracts.</p> <h2 id="rationale">Rationale</h2> <h3 id="usage-of-bytes">Usage of Bytes</h3> <p>Defining <code>UserIntent</code> object as a struct would improve readability and make it easier to work with in Solidity. For 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"> UserIntent</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> standard</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> header</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span> instructions</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span> signatures</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>However, this approach has several drawbacks:</p> <ul> <li>Mandating all <code>IAccount</code> and <code>IStandard</code> implementations to follow this specific struct format reduces flexibility.</li> <li>The use of <code>bytes[]</code> introduces additional gas costs due to Solidity's dynamic array encoding.</li> </ul> <p>Since all objects within the UserIntent structure are optional and their usage depends on <code>IStandard</code> and <code>IAccount</code> implementations, the bytes format ensures maximum flexibility while preserving compatibility.</p> <h3 id="execution-in-eoa-contract-code">Execution in EOA Contract Code</h3> <p>With <code>SET_CODE_TX_TYPE=0x04</code>, EOAs gain the ability to execute contract code. Executing transactions directly from an EOA provides several key benefits:</p> <ul> <li><strong>Preserves EOA Control</strong>: Execution remains fully controlled by the account owner. If needed, the EOA owner can easily disable all smart contract functionalities by un-delegating the contract code.</li> <li><strong>Consistent <code>msg.sender</code> Behavior</strong>: Since the execution originates from an EOA, <code>msg.sender</code> always resolves to the EOA address, simplifying authentication and permission checks.</li> <li><strong>Stateless Execution</strong>: The execution logic can be designed to be stateless, allowing the <code>IAccount</code> implementation to avoid storing persistent data, reducing storage costs.</li> </ul> <p>If an EOA does not require smart contract execution, or if executing an intent is too expensive, the owner can still use the account as a regular EOA without any modifications.</p> <h3 id="validation-in-the-standard-contract">Validation in the Standard Contract</h3> <p>Validation logic often relies on contract state. For example, a weighted multi-owner signature scheme needs to track the weight assigned to each signer. Keeping intent validation entirely within <code>IStandard</code> offers multiple advantages:</p> <ul> <li><strong>Simplified Implementation</strong>: By mirroring the <code>EntryPoint</code> concept from ERC-4337 but in a simpler form, <code>IStandard</code> focuses solely on validation.</li> <li><strong>Easier Auditing and Maintenance</strong>: Since <code>IStandard</code> is responsible only for validation, it becomes easier for contract engineers to implement, audit, and maintain.</li> <li><strong>Modular Validation</strong>: The <code>IStandard</code> interface is inherently modular, allowing for more complex validation mechanisms. For instance, a "compound" standard could decompose an intent into smaller components, validate each separately, and then combine the results.</li> </ul> <h3 id="gas-abstraction">Gas Abstraction</h3> <p>This design enables gasless transactions by allowing any address to initiate a transaction on behalf of the intent's sender.</p> <ul> <li>The sender can specify how and what to pay in the intent’s <code>header</code> or <code>instructions</code>.</li> <li>Payments can be made in any token from the sender’s account.</li> <li>The transaction cost can be covered by transferring tokens from the sender’s account to <code>tx.origin</code> (the address submitting the transaction).</li> </ul> <h3 id="no-re-entry-protection-enforced">No re-entry protection enforced</h3> <p>This proposal does not enforce built-in re-entry protection mechanisms such as nonces. The rationale behind this decision is that certain intents are inherently designed to be executed multiple times.</p> <p>Instead of a global re-entry protection mechanism, each standard should define its own protection rules based on its intended use case. Implementers are encouraged to:</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This <code>IAccount</code> standard shares the same backwards compatibility considerations as the introduction of EOA contract code execution (<code>SET_CODE_TX_TYPE=0x04</code>).</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="helper-library">Helper Library</h3> <p>This <code>PackedIntent</code> is a library to decode <code>(address sender, address standard, uint16 headerLength, uint16 instructionsLength, uint16 signaturesLength)</code> from a packed encoded intent. The following <code>IAccount</code> and <code>IStandrd</code> implementations both follow <code>PackedIntent</code> schema.</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"> PackedIntent</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> This is a library that packs metadata of intent (sender, standard, lengths) into bytes</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> the packed intent data schema is defined as follows:</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> 1. sender: address, 20-bytes</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> 2. standard: address, 20-bytes</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> 3. headerLength: uint16, 2-bytes</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> 4. instructionLength: uint16, 2-bytes</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> 5. signatureLength: uint16, 2-bytes</span></span> <span class="giallo-l"><span class="z-storage z-type">library</span><span class="z-entity z-name"> PackedIntent</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"> getSenderAndStandard is a function that gets the sender and standard from the intent</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> intent</span><span class="z-comment"> The intent to get the sender and standard 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"> sender</span><span class="z-comment"> The sender of the intent</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"> standard</span><span class="z-comment"> The standard of the intent</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getSenderAndStandard</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> intent</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">address</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>intent</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-constant"> 40</span><span>,</span><span class="z-string"> &quot;Intent too short&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-support">address</span><span>(</span><span class="z-support">bytes20</span><span>(</span><span>intent</span><span>[</span><span class="z-keyword">:</span><span class="z-constant"> 20</span><span>]</span><span>)</span><span>)</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-support">bytes20</span><span>(</span><span>intent</span><span>[</span><span class="z-constant">20</span><span class="z-keyword"> :</span><span class="z-constant"> 40</span><span>]</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> getLengths is a function that gets the lengths from the intent</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> intent</span><span class="z-comment"> The intent to get the lengths 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"> headerLength</span><span class="z-comment"> The length of the header</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"> instructionLength</span><span class="z-comment"> The length of the instructions</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"> signatureLength</span><span class="z-comment"> The length of the signature</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getLengths</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> intent</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">uint256</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"> require</span><span>(</span><span>intent</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-constant"> 46</span><span>,</span><span class="z-string"> &quot;Missing length section&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint16</span><span>(</span><span class="z-support">bytes2</span><span>(</span><span>intent</span><span>[</span><span class="z-constant">40</span><span class="z-keyword"> :</span><span class="z-constant"> 42</span><span>]</span><span>)</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint16</span><span>(</span><span class="z-support">bytes2</span><span>(</span><span>intent</span><span>[</span><span class="z-constant">42</span><span class="z-keyword"> :</span><span class="z-constant"> 44</span><span>]</span><span>)</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint16</span><span>(</span><span class="z-support">bytes2</span><span>(</span><span>intent</span><span>[</span><span class="z-constant">44</span><span class="z-keyword"> :</span><span class="z-constant"> 46</span><span>]</span><span>)</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> getSignatureLength is a function that gets the signature length from the intent</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> intent</span><span class="z-comment"> The intent to get the signature length 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"> signatureLength</span><span class="z-comment"> The length of the signature</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getSignatureLength</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> intent</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">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>intent</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-constant"> 46</span><span>,</span><span class="z-string"> &quot;Missing length section&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint16</span><span>(</span><span class="z-support">bytes2</span><span>(</span><span>intent</span><span>[</span><span class="z-constant">44</span><span class="z-keyword"> :</span><span class="z-constant"> 46</span><span>]</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> getIntentLength is a function that gets the intent length from the intent</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> intent</span><span class="z-comment"> The intent to get the intent length 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"> result</span><span class="z-comment"> The sum of header, instruction and signature lengths</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getIntentLength</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> intent</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">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>intent</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-constant"> 46</span><span>,</span><span class="z-string"> &quot;Missing length section&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> headerLength </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint16</span><span>(</span><span class="z-support">bytes2</span><span>(</span><span>intent</span><span>[</span><span class="z-constant">40</span><span class="z-keyword"> :</span><span class="z-constant"> 42</span><span>]</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> instructionLength </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint16</span><span>(</span><span class="z-support">bytes2</span><span>(</span><span>intent</span><span>[</span><span class="z-constant">42</span><span class="z-keyword"> :</span><span class="z-constant"> 44</span><span>]</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> signatureLength </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint16</span><span>(</span><span class="z-support">bytes2</span><span>(</span><span>intent</span><span>[</span><span class="z-constant">44</span><span class="z-keyword"> :</span><span class="z-constant"> 46</span><span>]</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> headerLength </span><span class="z-keyword">+</span><span> instructionLength </span><span class="z-keyword">+</span><span> signatureLength </span><span class="z-keyword">+</span><span class="z-constant"> 46</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"> @notice</span><span class="z-comment"> getIntentLengthFromSection is a function that gets the intent length from the length section</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> lengthSection</span><span class="z-comment"> The length section to get the intent length 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"> result</span><span class="z-comment"> The sum of header, instruction and signature lengths</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getIntentLengthFromSection</span><span>(</span><span class="z-support">bytes6</span><span class="z-variable"> lengthSection</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">uint16</span><span class="z-variable"> result</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-storage z-type"> let</span><span> value </span><span class="z-keyword">:=</span><span> lengthSection</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> a </span><span class="z-keyword">:=</span><span class="z-entity z-name"> shr</span><span>(</span><span class="z-constant">240</span><span>,</span><span> value</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Extract first 2 bytes</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> b </span><span class="z-keyword">:=</span><span class="z-entity z-name"> and</span><span>(</span><span class="z-entity z-name">shr</span><span>(</span><span class="z-constant">224</span><span>,</span><span> value</span><span>)</span><span>,</span><span class="z-constant"> 0xFFFF</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Extract next 2 bytes</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> c </span><span class="z-keyword">:=</span><span class="z-entity z-name"> and</span><span>(</span><span class="z-entity z-name">shr</span><span>(</span><span class="z-constant">208</span><span>,</span><span> value</span><span>)</span><span>,</span><span class="z-constant"> 0xFFFF</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Extract last 2 bytes</span></span> <span class="giallo-l"><span> result </span><span class="z-keyword">:=</span><span class="z-entity z-name"> add</span><span>(</span><span class="z-entity z-name">add</span><span>(</span><span class="z-entity z-name">add</span><span>(</span><span>a</span><span>,</span><span> b</span><span>)</span><span>,</span><span> c</span><span>)</span><span>,</span><span class="z-constant"> 46</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></code></pre><h3 id="relayed-execution-standard">Relayed Execution Standard</h3> <p>This <code>RelayedExecutionStandard</code> allows relayer to execute the operations on chain and take <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token from the intent sender, thus achieve a gas-less experience for the sender.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">MessageHashUtils</span><span>}</span></span> <span class="giallo-l"><span>import </span><span>{</span><span class="z-entity z-name">ECDSA</span><span>}</span></span> <span class="giallo-l"><span>import </span><span>{</span><span class="z-entity z-name">IERC20</span><span>}</span></span> <span class="giallo-l"><span>import </span><span>{</span><span class="z-entity z-name">IStandard</span><span>}</span></span> <span class="giallo-l"><span>import </span><span>{</span><span class="z-entity z-name">IAccount</span><span>}</span></span> <span class="giallo-l"><span>import </span><span>{</span><span class="z-entity z-name">PackedIntent</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/// @title ERC7806Constants</span></span> <span class="giallo-l"><span>/// @notice This is a library that defines the constants for the ERC7806 standard</span></span> <span class="giallo-l"><span>library ERC7806Constants </span><span>{</span></span> <span class="giallo-l"><span>/// @</span><span class="z-entity z-name">notice</span><span class="z-entity z-name"> VALIDATION_DENIED</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> magic</span><span class="z-entity z-name"> value</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> denied</span><span class="z-entity z-name"> intent</span></span> <span class="giallo-l"><span class="z-entity z-name">bytes4</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> VALIDATION_DENIED</span><span> = </span><span class="z-entity z-name">0x00000000</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/// @</span><span class="z-entity z-name">notice</span><span class="z-entity z-name"> VALIDATION_APPROVED</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> magic</span><span class="z-entity z-name"> value</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> validated</span><span class="z-entity z-name"> intent</span></span> <span class="giallo-l"><span class="z-entity z-name">bytes4</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> VALIDATION_APPROVED</span><span> = </span><span class="z-entity z-name">0x00000001</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>abstract contract HashGatedStandard is IStandard </span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> event</span><span class="z-entity z-name"> HashUsed</span><span>(</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> sender</span><span>, </span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> hash</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-entity z-name">bytes32</span><span> =&gt; </span><span class="z-entity z-name">bool</span><span>) </span><span class="z-entity z-name">internal</span><span class="z-entity z-name"> _hashes</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"> checkHash</span><span>(</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> sender</span><span>, </span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> hash</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-entity z-name">bool</span><span>) {</span></span> <span class="giallo-l"><span class="z-entity z-name"> bytes32</span><span class="z-entity z-name"> compositeKey</span><span> = </span><span class="z-entity z-name">keccak256</span><span>(</span><span class="z-entity z-name">abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span><span class="z-entity z-name">sender</span><span>, </span><span class="z-entity z-name">hash</span><span>));</span></span> <span class="giallo-l"><span class="z-entity z-name"> return</span><span class="z-entity z-name"> _hashes</span><span>[</span><span class="z-entity z-name">compositeKey</span><span>];</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function markHash</span><span>(</span><span>uint256 hash</span><span>)</span><span> external </span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> bytes32</span><span class="z-entity z-name"> compositeKey</span><span> = </span><span class="z-entity z-name">keccak256</span><span>(</span><span class="z-entity z-name">abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span><span class="z-entity z-name">msg</span><span>.</span><span class="z-entity z-name">sender</span><span>, </span><span class="z-entity z-name">hash</span><span>));</span></span> <span class="giallo-l"><span class="z-entity z-name"> _hashes</span><span>[</span><span class="z-entity z-name">compositeKey</span><span>] = </span><span class="z-entity z-name">true</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> emit</span><span class="z-entity z-name"> HashUsed</span><span>(</span><span class="z-entity z-name">msg</span><span>.</span><span class="z-entity z-name">sender</span><span>, </span><span class="z-entity z-name">hash</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></span> <span class="giallo-l"><span>RelayedExecutionStandard</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>This standard allows sender to define a list of execution instructions and asks the relayer to execute</span></span> <span class="giallo-l"><span>on chain on behalf of the sender</span><span>.</span><span> It is hash and time gated means the intent can only be executed before</span></span> <span class="giallo-l"><span>a timestamp and can only be executed once</span><span>.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>The first 20 bytes of the `intent` is sender address</span><span>.</span></span> <span class="giallo-l"><span>The next 20 bytes of the `intent` is the standard address</span><span>,</span><span> which should be equal to address of this standard</span><span>.</span></span> <span class="giallo-l"><span>The following is the length section</span><span>,</span><span> containing 3 uint16 defining header length</span><span>,</span><span> instructions length and signature length</span><span>.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>The header is either 8 bytes long or 28 bytes long</span><span>.</span></span> <span class="giallo-l"><span>The 8-byte part is the timestamp in epoch seconds</span><span>.</span></span> <span class="giallo-l"><span>The optional 20-byte defines the assigned relayer address if the sender only wants a specific relayer to execute</span><span>.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>The instructions contains 2 main part</span><span>.</span></span> <span class="giallo-l"><span>The first 36 bytes is a packed encoded </span><span>(</span><span>address</span><span>,</span><span> uint128</span><span>)</span><span> pair representing the </span><span class="z-string">&#39;payment&#39;</span><span> that the sender will pay to the</span></span> <span class="giallo-l"><span>relayer</span><span>.</span><span> It should be an ERC20 token</span><span>.</span></span> <span class="giallo-l"><span>The following 1-byte is an uint8 defining the number of instructions to execute</span><span>.</span></span> <span class="giallo-l"><span>The instructions are concatenated together</span><span>,</span><span> the first 2 bytes </span><span>(</span><span>uint16</span><span>)</span><span> defines the length of each instruction</span><span>,</span><span> the following</span></span> <span class="giallo-l"><span>is the instruction body</span><span>.</span><span> Instructions should be abi</span><span>.</span><span>encode</span><span>(</span><span>address</span><span>,</span><span> uint256</span><span>,</span><span> bytes</span><span>)</span><span> which can directly be executed by</span></span> <span class="giallo-l"><span>the sender account</span><span>.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>The signature field is always 65 bytes long</span><span>.</span><span> It contains the signed bytes</span><span>.</span><span>concat</span><span>(</span><span>header</span><span>,</span><span> instructions</span><span>)</span><span>.</span></span> <span class="giallo-l"><span>*/</span></span> <span class="giallo-l"><span>contract RelayedExecutionStandard is HashGatedStandard </span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> using</span><span class="z-entity z-name"> ECDSA</span><span class="z-entity z-name"> for</span><span class="z-entity z-name"> bytes32</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> string</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> ICS_NUMBER</span><span> = &quot;</span><span class="z-entity z-name">ICS1</span><span>&quot;;</span></span> <span class="giallo-l"><span class="z-entity z-name"> string</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> DESCRIPTION</span><span> = &quot;</span><span class="z-entity z-name">Timed</span><span class="z-entity z-name"> Hashed</span><span class="z-entity z-name"> Relayed</span><span class="z-entity z-name"> Execution</span><span class="z-entity z-name"> Standard</span><span>&quot;;</span></span> <span class="giallo-l"><span class="z-entity z-name"> string</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> VERSION</span><span> = &quot;</span><span class="z-entity z-name">0</span><span>.</span><span class="z-entity z-name">0</span><span>.</span><span class="z-entity z-name">0</span><span>&quot;;</span></span> <span class="giallo-l"><span class="z-entity z-name"> string</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> AUTHOR</span><span> = &quot;</span><span class="z-entity z-name">hellohanchen</span><span>&quot;;</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"> validateUserIntent</span><span>(</span><span class="z-entity z-name">bytes</span><span class="z-entity z-name"> calldata</span><span class="z-entity z-name"> intent</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-entity z-name">bytes4</span><span>) {</span></span> <span class="giallo-l"><span> (</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> sender</span><span>, </span><span class="z-entity z-name">address</span><span class="z-entity z-name"> standard</span><span>) = </span><span class="z-entity z-name">PackedIntent</span><span>.</span><span class="z-entity z-name">getSenderAndStandard</span><span>(</span><span class="z-entity z-name">intent</span><span>);</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">standard</span><span> == </span><span class="z-entity z-name">address</span><span>(</span><span class="z-entity z-name">this</span><span>), &quot;</span><span class="z-entity z-name">Not</span><span class="z-entity z-name"> this</span><span class="z-entity z-name"> standard</span><span>&quot;);</span></span> <span class="giallo-l"><span> (</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> headerLength</span><span>, </span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> instructionsLength</span><span>, </span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> signatureLength</span><span>) = </span><span class="z-entity z-name">PackedIntent</span><span>.</span><span class="z-entity z-name">getLengths</span><span>(</span><span class="z-entity z-name">intent</span><span>);</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">headerLength</span><span> == </span><span class="z-entity z-name">28</span><span> || </span><span class="z-entity z-name">headerLength</span><span> == </span><span class="z-entity z-name">8</span><span>, &quot;</span><span class="z-entity z-name">Invalid</span><span class="z-entity z-name"> header</span><span class="z-entity z-name"> length</span><span>&quot;);</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">instructionsLength</span><span> &gt;= </span><span class="z-entity z-name">36</span><span>, &quot;</span><span class="z-entity z-name">Instructions</span><span class="z-entity z-name"> too</span><span class="z-entity z-name"> short</span><span>&quot;);</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">signatureLength</span><span> == </span><span class="z-entity z-name">65</span><span>, &quot;</span><span class="z-entity z-name">Invalid</span><span class="z-entity z-name"> signature</span><span class="z-entity z-name"> length</span><span>&quot;);</span></span> <span class="giallo-l"><span> // </span><span class="z-entity z-name">end</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> instructions</span></span> <span class="giallo-l"><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> instructionsEndIndex</span><span> = </span><span class="z-entity z-name">46</span><span> + </span><span class="z-entity z-name">headerLength</span><span> + </span><span class="z-entity z-name">instructionsLength</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">instructionsLength</span><span> + </span><span class="z-entity z-name">signatureLength</span><span> == </span><span class="z-entity z-name">intent</span><span>.</span><span class="z-entity z-name">length</span><span>, &quot;</span><span class="z-entity z-name">Invalid</span><span class="z-entity z-name"> intent</span><span class="z-entity z-name"> length</span><span>&quot;);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // </span><span class="z-entity z-name">validate</span><span class="z-entity z-name"> signature</span></span> <span class="giallo-l"><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> hash</span><span> = </span><span class="z-entity z-name">_validateSignatures</span><span>(</span><span class="z-entity z-name">sender</span><span>, </span><span class="z-entity z-name">intent</span><span>, </span><span class="z-entity z-name">instructionsEndIndex</span><span>);</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(!</span><span class="z-entity z-name">this</span><span>.</span><span class="z-entity z-name">checkHash</span><span>(</span><span class="z-entity z-name">sender</span><span>, </span><span class="z-entity z-name">hash</span><span>), &quot;</span><span class="z-entity z-name">Hash</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> already</span><span class="z-entity z-name"> executed</span><span>&quot;);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // </span><span class="z-entity z-name">header</span><span class="z-entity z-name"> contains</span><span class="z-entity z-name"> expiration</span><span class="z-entity z-name"> timestamp</span><span class="z-entity z-name"> and</span><span class="z-entity z-name"> assigned</span><span class="z-entity z-name"> relayer</span><span> (</span><span class="z-entity z-name">optional</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">uint256</span><span>(</span><span class="z-entity z-name">uint64</span><span>(</span><span class="z-entity z-name">bytes8</span><span>(</span><span class="z-entity z-name">intent</span><span>[</span><span class="z-entity z-name">46</span><span> : </span><span class="z-entity z-name">54</span><span>]))) &gt;= </span><span class="z-entity z-name">block</span><span>.</span><span class="z-entity z-name">timestamp</span><span>, &quot;</span><span class="z-entity z-name">Intent</span><span class="z-entity z-name"> expired</span><span>&quot;);</span></span> <span class="giallo-l"><span> // </span><span class="z-entity z-name">assignedRelayerAddress</span><span> = </span><span class="z-entity z-name">address</span><span>(</span><span class="z-entity z-name">intent</span><span>[</span><span class="z-entity z-name">54</span><span>:</span><span class="z-entity z-name">74</span><span>]) [</span><span class="z-entity z-name">optional</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // </span><span class="z-entity z-name">end</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> header</span><span class="z-entity z-name"> section</span><span> / </span><span class="z-entity z-name">begin</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> instruction</span><span class="z-entity z-name"> section</span></span> <span class="giallo-l"><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> headerEndIndex</span><span> = </span><span class="z-entity z-name">46</span><span> + </span><span class="z-entity z-name">headerLength</span><span>;</span></span> <span class="giallo-l"><span> // </span><span class="z-entity z-name">first</span><span class="z-entity z-name"> 20</span><span class="z-entity z-name"> bytes</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> instruction</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> out</span><span class="z-entity z-name"> token</span><span class="z-entity z-name"> address</span></span> <span class="giallo-l"><span class="z-entity z-name"> address</span><span class="z-entity z-name"> outTokenAddress</span><span> = </span><span class="z-entity z-name">address</span><span>(</span><span class="z-entity z-name">bytes20</span><span>(</span><span class="z-entity z-name">intent</span><span>[</span><span class="z-entity z-name">headerEndIndex</span><span> : </span><span class="z-entity z-name">headerEndIndex</span><span> + </span><span class="z-entity z-name">20</span><span>]));</span></span> <span class="giallo-l"><span> // </span><span class="z-entity z-name">out</span><span class="z-entity z-name"> token</span><span class="z-entity z-name"> amount</span><span>, </span><span class="z-entity z-name">use</span><span class="z-entity z-name"> uint128</span><span class="z-entity z-name"> to</span><span class="z-entity z-name"> shorten</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> intent</span></span> <span class="giallo-l"><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> outTokenAmount</span><span> = </span><span class="z-entity z-name">uint256</span><span>(</span><span class="z-entity z-name">uint128</span><span>(</span><span class="z-entity z-name">bytes16</span><span>(</span><span class="z-entity z-name">intent</span><span>[</span><span class="z-entity z-name">headerEndIndex</span><span> + </span><span class="z-entity z-name">20</span><span> : </span><span class="z-entity z-name">headerEndIndex</span><span> + </span><span class="z-entity z-name">36</span><span>])));</span></span> <span class="giallo-l"><span class="z-entity z-name"> if</span><span> (</span><span class="z-entity z-name">outTokenAddress</span><span> != </span><span class="z-entity z-name">address</span><span>(</span><span class="z-entity z-name">0</span><span>)) {</span></span> <span class="giallo-l"><span> (</span><span class="z-entity z-name">bool</span><span class="z-entity z-name"> success</span><span>, </span><span class="z-entity z-name">bytes</span><span class="z-entity z-name"> memory</span><span class="z-entity z-name"> data</span><span>) = </span><span class="z-entity z-name">outTokenAddress</span><span>.</span><span class="z-entity z-name">staticcall</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span class="z-entity z-name">IERC20</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>.</span><span class="z-entity z-name">selector</span><span>, </span><span class="z-entity z-name">sender</span><span>)</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span class="z-entity z-name"> if</span><span> (!</span><span class="z-entity z-name">success</span><span> || </span><span class="z-entity z-name">data</span><span>.</span><span class="z-entity z-name">length</span><span> != </span><span class="z-entity z-name">32</span><span>) {</span></span> <span class="giallo-l"><span class="z-entity z-name"> revert</span><span>(&quot;</span><span class="z-entity z-name">Not</span><span class="z-entity z-name"> ERC20</span><span class="z-entity z-name"> token</span><span>&quot;);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> require</span><span>(</span><span>abi</span><span>.</span><span>decode</span><span>(</span><span>data</span><span>,</span><span> (</span><span>uint256</span><span>)</span><span>)</span><span> &gt;= outTokenAmount</span><span>,</span><span class="z-string"> &quot;Insufficient token balance&quot;</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"> require</span><span>(</span><span>sender</span><span>.</span><span>balance </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> outTokenAmount</span><span>,</span><span class="z-string"> &quot;Insufficient eth balance&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-comment"> //</span><span class="z-comment"> end of outToken instruction</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> numExecutions </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint8</span><span>(</span><span class="z-support">bytes1</span><span>(</span><span>intent</span><span>[</span><span>headerEndIndex </span><span class="z-keyword">+</span><span class="z-constant"> 36</span><span class="z-keyword"> :</span><span> headerEndIndex </span><span class="z-keyword">+</span><span class="z-constant"> 37</span><span>]</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> instruction index</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> instructionIndex </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> begin of the first instruction</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> instructionStart</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> instructionEnd </span><span class="z-keyword">=</span><span> headerEndIndex </span><span class="z-keyword">+</span><span class="z-constant"> 37</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> (</span><span>instructionIndex </span><span class="z-keyword">&lt;</span><span> numExecutions</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> instructionStart </span><span class="z-keyword">=</span><span> instructionEnd</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>instructionStart </span><span class="z-keyword">+</span><span class="z-constant"> 2</span><span class="z-keyword"> &lt;</span><span class="z-keyword">=</span><span> instructionsEndIndex</span><span>,</span><span class="z-string"> &quot;Intent too short: instruction length&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> end of this execution instruction</span></span> <span class="giallo-l"><span> instructionEnd </span><span class="z-keyword">=</span><span> instructionStart </span><span class="z-keyword">+</span><span class="z-constant"> 2</span><span class="z-keyword"> +</span><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint16</span><span>(</span><span class="z-support">bytes2</span><span>(</span><span>intent</span><span>[</span><span>instructionStart </span><span class="z-keyword">:</span><span> instructionStart </span><span class="z-keyword">+</span><span class="z-constant"> 2</span><span>]</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>instructionEnd </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> instructionsEndIndex</span><span>,</span><span class="z-string"> &quot;Intent too short: single instruction&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> instructionIndex </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 class="z-keyword"> require</span><span>(</span><span>instructionEnd </span><span class="z-keyword">==</span><span> instructionsEndIndex</span><span>,</span><span class="z-string"> &quot;Intent length doesn&#39;t match&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> ERC7806Constants</span><span>.</span><span>VALIDATION_APPROVED</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"> unpackOperations</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> intent</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">bytes4</span><span class="z-variable"> code</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"> unpackedInstructions</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> (</span><span class="z-support">address</span><span> sender</span><span>,</span><span class="z-support"> address</span><span> standard</span><span>)</span><span class="z-keyword"> =</span><span> PackedIntent</span><span>.</span><span class="z-entity z-name">getSenderAndStandard</span><span>(</span><span>intent</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>standard </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 class="z-string"> &quot;Not this standard&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> (</span><span class="z-support">uint256</span><span> headerLength</span><span>,</span><span class="z-support"> uint256</span><span> instructionsLength</span><span>,</span><span class="z-support"> uint256</span><span> signatureLength</span><span>)</span><span class="z-keyword"> =</span><span> PackedIntent</span><span>.</span><span class="z-entity z-name">getLengths</span><span>(</span><span>intent</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>headerLength </span><span class="z-keyword">==</span><span class="z-constant"> 28</span><span class="z-keyword"> ||</span><span> headerLength </span><span class="z-keyword">==</span><span class="z-constant"> 8</span><span>,</span><span class="z-string"> &quot;Invalid header length&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>instructionsLength </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-constant"> 36</span><span>,</span><span class="z-string"> &quot;Instructions too short&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>signatureLength </span><span class="z-keyword">==</span><span class="z-constant"> 65</span><span>,</span><span class="z-string"> &quot;Invalid signature length&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> end of instructions</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> instructionsEndIndex </span><span class="z-keyword">=</span><span class="z-constant"> 46</span><span class="z-keyword"> +</span><span> headerLength </span><span class="z-keyword">+</span><span> instructionsLength</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>instructionsLength </span><span class="z-keyword">+</span><span> signatureLength </span><span class="z-keyword">==</span><span> intent</span><span>.</span><span>length</span><span>,</span><span class="z-string"> &quot;Invalid intent length&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"> fetch header content (timestamp, relayer address [optional])</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-support">uint256</span><span>(</span><span class="z-support">uint64</span><span>(</span><span class="z-support">bytes8</span><span>(</span><span>intent</span><span>[</span><span class="z-constant">46</span><span class="z-keyword"> :</span><span class="z-constant"> 54</span><span>]</span><span>)</span><span>)</span><span>)</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-string"> &quot;Intent expired&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>headerLength </span><span class="z-keyword">==</span><span class="z-constant"> 28</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> assigned relayer</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">tx</span><span>.</span><span>origin </span><span class="z-keyword">==</span><span class="z-support"> address</span><span>(</span><span class="z-support">bytes20</span><span>(</span><span>intent</span><span>[</span><span class="z-constant">54</span><span class="z-keyword"> :</span><span class="z-constant"> 74</span><span>]</span><span>)</span><span>)</span><span>,</span><span class="z-string"> &quot;Invalid relayer&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-support"> uint256</span><span> intentHash </span><span class="z-keyword">=</span><span class="z-entity z-name"> _validateSignatures</span><span>(</span><span>sender</span><span>,</span><span> intent</span><span>,</span><span> instructionsEndIndex</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-language">this</span><span>.</span><span class="z-entity z-name">checkHash</span><span>(</span><span>sender</span><span>,</span><span> intentHash</span><span>)</span><span>,</span><span class="z-string"> &quot;Hash is already executed&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"> begin of instructions</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> headerEndIndex </span><span class="z-keyword">=</span><span> headerLength </span><span class="z-keyword">+</span><span class="z-constant"> 46</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> total instructions = mark hash + transfer token to relayer + executions</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> the first 36 bytes defines the payment to relayer</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> the next 1 byte defines the number of execution instructions</span></span> <span class="giallo-l"><span> unpackedInstructions </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> bytes</span><span>[](</span><span class="z-constant">2</span><span> + </span><span class="z-variable">uint8</span><span>(</span><span class="z-variable">bytes1</span><span>(</span><span class="z-variable">intent</span><span>[</span><span class="z-variable">headerEndIndex</span><span> + </span><span class="z-constant">36</span><span> : </span><span class="z-variable">headerEndIndex</span><span> + </span><span class="z-constant">37</span><span>]</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> first instruction is mark hash to prevent re-entry attack</span></span> <span class="giallo-l"><span> unpackedInstructions</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> =</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"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span class="z-variable z-language">this</span><span>.</span><span>markHash</span><span>.</span><span>selector</span><span>,</span><span> intentHash</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"> the first 20 bytes of instructions is the out token address</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> outTokenAddress </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span class="z-support">bytes20</span><span>(</span><span>intent</span><span>[</span><span>headerEndIndex </span><span class="z-keyword">:</span><span> headerEndIndex </span><span class="z-keyword">+</span><span class="z-constant"> 20</span><span>]</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> amount</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> outTokenAmount </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint128</span><span>(</span><span class="z-support">bytes16</span><span>(</span><span>intent</span><span>[</span><span>headerEndIndex </span><span class="z-keyword">+</span><span class="z-constant"> 20</span><span class="z-keyword"> :</span><span> headerEndIndex </span><span class="z-keyword">+</span><span class="z-constant"> 36</span><span>]</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> out token instruction</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>outTokenAddress </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> unpackedInstructions</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-variable z-language">tx</span><span>.</span><span>origin</span><span>)</span><span>,</span><span> outTokenAmount</span><span>,</span><span class="z-string"> &quot;&quot;</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> unpackedInstructions</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> =</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> outTokenAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span>IERC20</span><span>.</span><span>transfer</span><span>.</span><span>selector</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">tx</span><span>.</span><span>origin</span><span>)</span><span>,</span><span> outTokenAmount</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"> instruction index</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> instructionIndex </span><span class="z-keyword">=</span><span class="z-constant"> 2</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> instructionEndIndex </span><span class="z-keyword">=</span><span> headerEndIndex </span><span class="z-keyword">+</span><span class="z-constant"> 37</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> instructionStartIndex</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> (</span><span>instructionIndex </span><span class="z-keyword">&lt;</span><span> unpackedInstructions</span><span>.</span><span>length</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> start of next execution instruction</span></span> <span class="giallo-l"><span> instructionStartIndex </span><span class="z-keyword">=</span><span> instructionEndIndex</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>instructionStartIndex </span><span class="z-keyword">+</span><span class="z-constant"> 2</span><span class="z-keyword"> &lt;</span><span class="z-keyword">=</span><span> instructionEndIndex</span><span>,</span><span class="z-string"> &quot;Intent too short: instruction length&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> end of next execution instruction</span></span> <span class="giallo-l"><span> instructionEndIndex </span><span class="z-keyword">=</span><span> instructionStartIndex </span><span class="z-keyword">+</span><span class="z-constant"> 2</span><span class="z-keyword"> +</span><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint16</span><span>(</span><span class="z-support">bytes2</span><span>(</span><span>intent</span><span>[</span><span>instructionStartIndex </span><span class="z-keyword">:</span><span> instructionStartIndex </span><span class="z-keyword">+</span><span class="z-constant"> 2</span><span>]</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>instructionEndIndex </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> instructionsEndIndex</span><span>,</span><span class="z-string"> &quot;Intent too short: single instruction&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> unpackedInstructions</span><span>[</span><span>instructionIndex</span><span>]</span><span class="z-keyword"> =</span><span> intent</span><span>[</span><span>instructionStartIndex </span><span class="z-keyword">+</span><span class="z-constant"> 2</span><span class="z-keyword"> :</span><span> instructionEndIndex</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> instructionIndex </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 class="z-keyword"> require</span><span>(</span><span>instructionEndIndex </span><span class="z-keyword">==</span><span> instructionsEndIndex</span><span>,</span><span class="z-string"> &quot;Intent length doesn&#39;t match&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>ERC7806Constants</span><span>.</span><span>VALIDATION_APPROVED</span><span>,</span><span> unpackedInstructions</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"> _validateSignatures</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> intent</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> sigStartIndex</span></span> <span class="giallo-l"><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">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> intentHash </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>intent</span><span>[</span><span class="z-constant">46</span><span class="z-keyword"> :</span><span> sigStartIndex</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"> block</span><span>.</span><span>chainid</span><span>)</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> MessageHashUtils</span><span>.</span><span class="z-entity z-name">toEthSignedMessageHash</span><span>(</span><span>intentHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>sender </span><span class="z-keyword">==</span><span> messageHash</span><span>.</span><span class="z-entity z-name">recover</span><span>(</span><span>intent</span><span>[</span><span>sigStartIndex </span><span class="z-keyword">:</span><span> sigStartIndex </span><span class="z-keyword">+</span><span class="z-constant"> 65</span><span>]</span><span>)</span><span>,</span><span class="z-string"> &quot;Invalid sender signature&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-support"> uint256</span><span>(</span><span>intentHash</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"> //</span><span class="z-comment"> The following methods will be removed after testing</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"> sampleIntent</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> relayer</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> outTokenAddress</span><span>,</span><span class="z-support"> uint128</span><span class="z-variable"> outAmount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> executions</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"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> intent</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> intentHash</span></span> <span class="giallo-l"><span> )</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> header </span><span class="z-keyword">=</span><span> relayer </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> <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">uint64</span><span>(</span><span>(</span><span class="z-variable z-language">block</span><span>.</span><span>timestamp </span><span class="z-keyword">+</span><span class="z-constant"> 31536000</span><span>)</span><span class="z-keyword"> &amp;</span><span class="z-constant"> 0xFFFFFFFFFFFFFFFF</span><span>)</span><span>)</span><span class="z-keyword"> :</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">uint64</span><span>(</span><span>(</span><span class="z-variable z-language">block</span><span>.</span><span>timestamp </span><span class="z-keyword">+</span><span class="z-constant"> 31536000</span><span>)</span><span class="z-keyword"> &amp;</span><span class="z-constant"> 0xFFFFFFFFFFFFFFFF</span><span>)</span><span>,</span><span> relayer</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> instructions </span><span class="z-keyword">=</span><span class="z-support"> bytes</span><span>.</span><span class="z-entity z-name">concat</span><span>(</span><span class="z-support">bytes20</span><span>(</span><span>outTokenAddress</span><span>)</span><span>,</span><span class="z-support"> bytes16</span><span>(</span><span>outAmount</span><span>)</span><span>,</span><span class="z-support"> bytes1</span><span>(</span><span class="z-support">uint8</span><span>(</span><span>executions</span><span>.</span><span>length</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-support">uint256</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> executions</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"> uint16</span><span> length </span><span class="z-keyword">=</span><span class="z-support"> uint16</span><span>(</span><span>executions</span><span>[</span><span>i</span><span>]</span><span>.</span><span>length</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> instructions </span><span class="z-keyword">=</span><span class="z-support"> bytes</span><span>.</span><span class="z-entity z-name">concat</span><span>(</span><span>instructions</span><span>,</span><span class="z-support"> bytes2</span><span>(</span><span>length</span><span>)</span><span>,</span><span> executions</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> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> toSign </span><span class="z-keyword">=</span><span class="z-support"> bytes</span><span>.</span><span class="z-entity z-name">concat</span><span>(</span><span>header</span><span>,</span><span> instructions</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> intentHash </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>toSign</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"> block</span><span>.</span><span>chainid</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> intent </span><span class="z-keyword">=</span><span class="z-support"> bytes</span><span>.</span><span class="z-entity z-name">concat</span><span>(</span><span class="z-support">bytes20</span><span>(</span><span>sender</span><span>)</span><span>,</span><span class="z-support"> bytes20</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 class="z-support"> bytes2</span><span>(</span><span class="z-support">uint16</span><span>(</span><span>header</span><span>.</span><span>length</span><span>)</span><span>)</span><span>,</span><span class="z-support"> bytes2</span><span>(</span><span class="z-support">uint16</span><span>(</span><span>instructions</span><span>.</span><span>length</span><span>)</span><span>)</span><span>,</span><span class="z-support"> bytes2</span><span>(</span><span class="z-support">uint16</span><span>(</span><span class="z-constant">65</span><span>)</span><span>)</span><span>,</span><span> toSign</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>intent</span><span>,</span><span> intentHash</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"> sampleERC20Execution</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> token</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"> amount</span></span> <span class="giallo-l"><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">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>token </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-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span><span>receiver</span><span>,</span><span> amount</span><span>,</span><span class="z-string"> &quot;&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-keyword"> return</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span><span>token</span><span>,</span><span class="z-support"> uint256</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span>IERC20</span><span>.</span><span>transfer</span><span>.</span><span>selector</span><span>,</span><span class="z-support"> address</span><span>(</span><span>receiver</span><span>)</span><span>,</span><span> amount</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"> executeUserIntent</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> intent</span><span>)</span><span class="z-storage z-type"> external</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> (</span><span class="z-support">address</span><span> sender</span><span>,</span><span>)</span><span class="z-keyword"> =</span><span> PackedIntent</span><span>.</span><span class="z-entity z-name">getSenderAndStandard</span><span>(</span><span>intent</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> executeCallData </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span>IAccount</span><span>.</span><span>executeUserIntent</span><span>.</span><span>selector</span><span>,</span><span> intent</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> (</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span> sender</span><span>.</span><span>call</span><span>{</span><span>value </span><span class="z-keyword">:</span><span class="z-constant"> 0</span><span>,</span><span> gas </span><span class="z-keyword">:</span><span class="z-variable z-language"> gasleft</span><span>(</span><span>)</span><span>}</span><span>(</span><span>executeCallData</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> result</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="sample-account">Sample Account</h3> <p>The following <code>IAccount</code> implementation uses a <code>StandardRegistry</code> to maintain allowlist of standards and just batch execute all operations returned from <code>IStandard.unpackOperations</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">MessageHashUtils</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/cryptography/MessageHashUtils.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">ECDSA</span><span>}</span><span class="z-keyword"> from</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 class="z-storage z-type"> @title</span><span class="z-comment"> StandardRegistry</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> This is a registry for standards, determining whether an account accepts a standard</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> EIP-712 is used for signature verification</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> StandardRegistry</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> ECDSA</span><span class="z-keyword"> for</span><span class="z-entity z-name"> bytes32</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 event emitted when a standard is registered</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> StandardRegistered</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> signer</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> standard</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"> The event emitted when a standard is unregistered</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> StandardUnregistered</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> signer</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> standard</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 domain separator of this contract</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> immutable</span><span> DOMAIN_SEPARATOR</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"> The type hash of the signed data of this contract</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> immutable</span><span> SIGNED_DATA_TYPEHASH</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 mapping of nonces</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes32</span><span> nonce </span><span class="z-keyword">=&gt;</span><span class="z-support"> bool</span><span> used</span><span>)</span><span class="z-storage z-type"> private</span><span> _nonces</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"> The mapping of registrations</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes32</span><span> standard </span><span class="z-keyword">=&gt;</span><span class="z-support"> bool</span><span> registered</span><span>)</span><span class="z-storage z-type"> private</span><span> _registrations</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 constructor of this contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span>)</span><span> {</span></span> <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">&quot;EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)&quot;</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;StandardRegistry&quot;</span><span>)</span><span>)</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Contract name</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;2&quot;</span><span>)</span><span>)</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Version</span></span> <span class="giallo-l"><span class="z-variable z-language"> block</span><span>.</span><span>chainid</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Chain ID</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 class="z-comment"> //</span><span class="z-comment"> Contract address</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> SIGNED_DATA_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;Permission(bool registering,address standard,uint256 nonce)&quot;</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> The function to permit a standard, allowing a relayer to register or unregister a standard for a 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"> registering</span><span class="z-comment"> Whether registering or unregistering</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> signer</span><span class="z-comment"> The signer of the permission</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> standard</span><span class="z-comment"> The standard to 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"> nonce</span><span class="z-comment"> The nonce of the permission</span></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"> The signature of the permission</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">bool</span><span class="z-variable"> registering</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> signer</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> standard</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> nonce</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 class="z-support"> bytes32</span><span> compositeKey </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>signer</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 class="z-keyword">!</span><span>_nonces</span><span>[</span><span>compositeKey</span><span>]</span><span>,</span><span class="z-string"> &quot;Invalid nonce&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"> validate signature</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> structHash </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>SIGNED_DATA_TYPEHASH</span><span>,</span><span> registering</span><span>,</span><span> standard</span><span>,</span><span> nonce</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> digest </span><span class="z-keyword">=</span><span> MessageHashUtils</span><span>.</span><span class="z-entity z-name">toTypedDataHash</span><span>(</span><span>DOMAIN_SEPARATOR</span><span>,</span><span> structHash</span><span>)</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> digest</span><span>.</span><span class="z-entity z-name">recover</span><span>(</span><span>signature</span><span>)</span><span>,</span><span class="z-string"> &quot;Invalid signature&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> _process</span><span>(</span><span>registering</span><span>,</span><span> signer</span><span>,</span><span> standard</span><span>,</span><span> nonce</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"> @notice</span><span class="z-comment"> The function to update a standard registration directly</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> registering</span><span class="z-comment"> Whether registering or unregistering</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> standard</span><span class="z-comment"> The standard 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"> nonce</span><span class="z-comment"> The nonce of the update</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-support">bool</span><span class="z-variable"> registering</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> standard</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> nonce</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> signer </span><span class="z-keyword">=</span><span class="z-variable z-language"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> compositeKey </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>signer</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 class="z-keyword">!</span><span>_nonces</span><span>[</span><span>compositeKey</span><span>]</span><span>,</span><span class="z-string"> &quot;Invalid nonce&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> _process</span><span>(</span><span>registering</span><span>,</span><span> signer</span><span>,</span><span> standard</span><span>,</span><span> nonce</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"> @notice</span><span class="z-comment"> The function to check if a nonce is 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"> signer</span><span class="z-comment"> The signer of the nonce</span></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 check</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"> true if the nonce is used</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isNonceUsed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> signer</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> nonce</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"> bytes32</span><span> compositeKey </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>signer</span><span>,</span><span> nonce</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _nonces</span><span>[</span><span>compositeKey</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"> @notice</span><span class="z-comment"> The function to check if a standard is registered</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> signer</span><span class="z-comment"> The signer of the standard</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> standard</span><span class="z-comment"> The standard to check</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"> true if the standard is registered</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"> signer</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> standard</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"> bytes32</span><span> compositeKey </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>signer</span><span>,</span><span> standard</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _registrations</span><span>[</span><span>compositeKey</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"> @notice</span><span class="z-comment"> The function to process a standard registration or unregistration</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> registering</span><span class="z-comment"> Whether registering or unregistering</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> signer</span><span class="z-comment"> The signer of the registration</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> standard</span><span class="z-comment"> The standard to process</span></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 of the registration</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _process</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> registering</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> signer</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> standard</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> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> compositeKey </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>signer</span><span>,</span><span> standard</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>registering</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> _registrations</span><span>[</span><span>compositeKey</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> StandardRegistered</span><span>(</span><span>signer</span><span>,</span><span> standard</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> _registrations</span><span>[</span><span>compositeKey</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> StandardUnregistered</span><span>(</span><span>signer</span><span>,</span><span> standard</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> compositeKey </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>signer</span><span>,</span><span> nonce</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _nonces</span><span>[</span><span>compositeKey</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></code></pre><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"> AccountImplV0</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> DESCRIPTION </span><span class="z-keyword">=</span><span class="z-string"> &quot;Account with Batch Execution, Standard Registry&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> VERSION </span><span class="z-keyword">=</span><span class="z-string"> &quot;0.0.0&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> AUTHOR </span><span class="z-keyword">=</span><span class="z-string"> &quot;hellohanchen&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> StandardRegistry </span><span class="z-storage z-type">public</span><span class="z-storage z-type"> constant</span><span> REGISTRY </span><span class="z-keyword">=</span><span class="z-entity z-name"> StandardRegistry</span><span>(</span><span class="z-support">address</span><span>(</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> VALIDATION_APPROVED </span><span class="z-keyword">=</span><span class="z-constant"> 0x00000001</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> VALIDATION_DENIED </span><span class="z-keyword">=</span><span class="z-constant"> 0x00000000</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"> executeOtherIntent</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> intent</span><span>)</span><span class="z-storage z-type"> override</span><span class="z-storage z-type"> internal</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> (</span><span class="z-support">address</span><span> sender</span><span>,</span><span class="z-support"> address</span><span> standard</span><span>)</span><span class="z-keyword"> =</span><span> PackedIntent</span><span>.</span><span class="z-entity z-name">getSenderAndStandard</span><span>(</span><span>intent</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>sender </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 class="z-string"> &quot;Intent is not from this account&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>REGISTRY</span><span>.</span><span class="z-entity z-name">isRegistered</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> standard</span><span>)</span><span>,</span><span class="z-string"> &quot;Standard not registered&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> standard validation and unpack</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bytes4</span><span> validationCode</span><span>,</span><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> instructions</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> IStandard</span><span>(</span><span>standard</span><span>)</span><span>.</span><span class="z-entity z-name">unpackOperations</span><span>(</span><span>intent</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>validationCode </span><span class="z-keyword">==</span><span> VALIDATION_APPROVED</span><span>,</span><span class="z-string"> &quot;Validation failed&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"> batch execute</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> instructions</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><span class="z-support">address</span><span> dest</span><span>,</span><span class="z-support"> uint256</span><span> value</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> data</span><span>)</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>instructions</span><span>[</span><span>i</span><span>]</span><span>,</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>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></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> dest</span><span>.</span><span>call</span><span>{</span><span>value </span><span class="z-keyword">:</span><span> value</span><span>,</span><span> gas </span><span class="z-keyword">:</span><span class="z-variable z-language"> gasleft</span><span>(</span><span>)</span><span>}</span><span>(</span><span>data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span> SelfExecutableAccount</span><span>.</span><span class="z-entity z-name">ExecutionError</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-keyword"> return</span><span class="z-keyword"> new</span><span class="z-support"> bytes</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-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></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>As shown above, the implementation of <code>IAccount</code> is stateless and simple, so that it can be compatible with different <code>IStandard</code>. While the <code>IStandard</code> implementation is complex because it needs to define its own schema. But both contracts will be public and audited, to ensure the security of intent execution.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The security of this standard primarily depends on the implementation of both <code>IStandard</code> and <code>IAccount</code>. Each component must ensure that user intents are validated and executed safely. Additionally, solvers are responsible for securing their own execution environments to prevent unintended exploits.</p> <h3 id="auditability-of-both-validation-and-execution">Auditability of both Validation and Execution</h3> <p>To ensure security and maintain ecosystem integrity, it is critical that both the standard (<code>IStandard</code>) and account (<code>IAccount</code>) implementations are:</p> <ul> <li><strong>Publicly auditable</strong>: Open access to contract code allows security researchers to identify potential vulnerabilities.</li> <li><strong>Well-reviewed and shared</strong>: Public discussions and peer reviews help strengthen security assumptions.</li> <li><strong>Secure against compatibility risks</strong>: Ensuring compatibility between different standard and account implementations can prevent unintended interactions that may lead to exploits.</li> </ul> <h3 id="delegated-contract-storage-risks">Delegated Contract Storage Risks</h3> <p>If an <code>IAccount</code> implementation maintains state (instead of being stateless), it could:</p> <ul> <li>Interfere with other delegated contracts sharing the same storage.</li> <li>Be manipulated by unauthorized users if storage is not properly protected.</li> </ul> <p>Strongly RECOMMEND stateless execution to prevent storage conflicts.</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-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Thomas Thieryhttps://github.com/soispokethomas.thiery@ethereum.org Francesco D'Amatofrancesco.damato@ethereum.org Julian Majulian.ma@ethereum.org Barnabé Monnotbarnabe.monnot@ethereum.org Terence Tsaottsao@offchainlabs.com Jacob Kaufmannjacob.kaufmann@ethereum.org Jihoon Songjihoon.song@ethereum.org https://wg-eips.ritovision.com/7805/

Allow a committee of validators to force-include a set of transactions in every block

<h2 id="abstract">Abstract</h2> <p>FOCIL implements a robust mechanism to preserve Ethereum’s censorship resistance properties by guaranteeing timely transaction inclusion.</p> <p>FOCIL (<strong>Fo</strong>rk-<strong>c</strong>hoice enforced <strong>I</strong>nclusion <strong>L</strong>ists) is built in a few simple steps:</p> <ul> <li>In each slot, a set of validators is selected as inclusion list (IL) committee members. Each member builds and gossips one IL according to their subjective view of the mempool.</li> <li>The proposer and all attesters of the next slot monitor, store and forward available ILs.</li> <li>The proposer (or the builder if the block is not built locally by the proposer) includes transactions from all collected ILs in its block. The proposer then broadcasts the block including IL transactions to the rest of the network.</li> <li>Attesters only vote for the proposer's block if it includes transactions from all stored ILs.</li> </ul> <h2 id="motivation">Motivation</h2> <p>In an effort to shield the Ethereum validator set from centralizing forces, the right to build blocks has been auctioned off to specialized entities known as <em>builders</em>. This has led to a few sophisticated builders dominating block production, leading to a deterioration of the network’s censorship resistance properties. To address this issue, research has focused on improving Ethereum's transaction inclusion guarantees by enabling validators to impose constraints on builders. This is achieved by force-including transactions in blocks via ILs.</p> <h3 id="high-level-overview">High-level Overview</h3> <p>FOCIL is a committee-based, fork-choice enforced inclusion list (IL) design that improves upon previous IL mechanisms and block co-creation proposals. It addresses issues related to bribing/extortion attacks, IL equivocation, account abstraction (AA), and transaction invalidation.</p> <p><img src="https://wg-eips.ritovision.com/7805/./assets/diagram_FOCIL.png" alt="FOCIL diagram" /></p> <h3 id="roles-and-participants">Roles And Participants</h3> <p>This section outlines the workflow of FOCIL, detailing the roles and responsibilities of various participants: IL committee members, validators, builders, proposers and attesters.</p> <h4 id="il-committee-members">IL Committee Members</h4> <ul> <li><strong><code>Slot N</code>, <code>t=0 to 8s</code></strong>: IL committee members construct their ILs by including transactions pending in the public mempool, and broadcast them over the P2P network after processing the block for <code>slot N</code> and confirming it as the head. If no block is received by <code>t=7s</code>, they should run <code>get_head</code> and build and release their ILs based on the node’s local head.</li> </ul> <p>IL committee members may follow different strategies for constructing their ILs as discussed in <a href="https://wg-eips.ritovision.com/7805/#il-building">IL Building</a>.</p> <h4 id="validators">Validators</h4> <ul> <li> <p><strong><code>Slot N</code>, <code>t=0s to 9s</code></strong>: Validators receive ILs from the P2P network and store (1) all new ILs that pass the CL P2P validation rules, and (2) any evidence of IL equivocation by committee members (i.e., if multiple ILs are received from the same committee member).</p> </li> <li> <p><strong><code>Slot N</code>, <code>t=9s</code> to <code>Slot N+1</code>, <code>t=4s</code></strong>: After the view freeze deadline at <code>t=9s</code>, validators:</p> <ol> <li>Do not store new ILs received after the deadline.</li> <li>Continue forwarding ILs to peers following the CL P2P validation rules.</li> <li>Record any evidence of IL equivocation that occurs after the view freeze deadline.</li> </ol> </li> </ul> <p>After the attestation deadline of <strong><code>Slot N+1</code>, <code>t=4s</code></strong>, validators ignore any new ILs related to the previous slot's IL committee, and stop recording equivocation evidence for the previous slot's ILs.</p> <h4 id="builder">Builder</h4> <ul> <li> <p><strong><code>Slot N</code>, <code>t=0s to 11s</code></strong>: The builder (i.e., a proposer doing local block building or an external builder) receives ILs from the P2P network, forwarding and caching those that pass the CL P2P validation rules. Optionally, an RPC endpoint can be added to allow the builder to request missing ILs from its peers (e.g., by committee index at <code>t=10s</code>).</p> </li> <li> <p><strong><code>Slot N</code>, <code>t=11s</code></strong>: The builder freezes its view of ILs and asks the EL to update its execution payload by adding transactions from its view (the exact timings will be defined after running some tests/benchmarks).</p> </li> </ul> <h4 id="proposer">Proposer</h4> <ul> <li><strong><code>Slot N+1</code>, <code>t=0s</code></strong>: The proposer broadcasts its block with the up-to-date execution payload satisfying IL transactions over the P2P network.</li> </ul> <h4 id="attesters">Attesters</h4> <ul> <li><strong><code>Slot N+1</code>, <code>t=4s</code></strong>: Attesters monitor the P2P network for the proposer’s block. Upon detecting it, they verify whether all transactions from their stored ILs are included in the proposer’s execution payload, except for ILs whose sender has equivocated. Based on their frozen view of the ILs from <code>t=9s</code> in the previous slot, attesters check if the execution payload satisfies IL conditions. This is done either by confirming that all transactions are present or by determining if any missing transactions are invalid when appended to the end of the payload. In such cases, attesters use the EL to perform nonce and balance checks to validate the missing transactions and check whether there is enough space in the block to include the transaction(s).</li> </ul> <h4 id="cl-p2p-validation-rules">CL P2P Validation Rules</h4> <p>When validators receive ILs from the P2P network, they perform a series of validation checks before forwarding or caching them. These rules protect against Denial-of-Service attacks by (1) limiting ILs' byte size and (2) restricting IL proposals to a small committee of IL committee members, thereby tightly bounding bandwidth, the main resource consumed by the propagation of ILs. Consumption of other relevant resources, such as verification time, is minimal because the only nontrivial check performed on IL propagation is signature verification. At this stage, there is no EL verification of the transactions within ILs. This means that ILs are allowed to contain any transactions—valid or invalid—since validators do not perform EL-side validity checks. This design choice is intended to avoid additional computational overhead.</p> <ol> <li>The slot of the IL matches the current or previous slot.</li> <li>The root of the IL committee referenced in the IL matches the expected IL committee root for its slot.</li> <li>Received two or fewer ILs from this IL committee member (see IL equivocation section below).</li> <li>The IL is correctly signed by the validator.</li> <li>The validator is part of the IL committee.</li> <li>The size of a IL does not exceed the maximum size allowed (e.g., <code>MAX_BYTES_PER_INCLUSION_LIST = 8 KiB</code>).</li> </ol> <h2 id="specification">Specification</h2> <h3 id="execution-layer">Execution Layer</h3> <p>On the execution layer, an additional check is introduced for new payloads. After all of the transactions in the payload have been executed, we check whether any transaction from ILs, that is not already present in the payload, could be validly included (i.e. nonce and balance checks pass). If that is the case for any transaction, then an error is returned to the CL. Although the block is valid, the CL will not attest to it.</p> <p>Let <code>B</code> denote the current block. Let <code>S</code> denote the execution state following the execution of the last transaction in <code>B</code>. Let <code>gas_left</code> be the gas remaining after execution of B.</p> <p>For each transaction <code>T</code> in ILs, perform the following:</p> <ol> <li> <p>Check whether <code>T</code> is present in <code>B</code>. If <code>T</code> is present, then jump to the next transaction, else continue with next step.</p> </li> <li> <p>Check whether <code>B</code> has enough remaining gas to execute <code>T</code>. If <code>T.gas</code> &gt; <code>gas_left</code>, then jump to the next transaction, else continue with next step.</p> </li> <li> <p>Validate <code>T</code> against <code>S</code> by checking the nonce and balance of <code>T.origin</code>.</p> </li> </ol> <ul> <li> <p>If <code>T</code> is invalid, then continue to the next transaction.</p> </li> <li> <p>If <code>T</code> is valid, terminate process and return an <code>INCLUSION_LIST_UNSATISFIED</code> status.</p> </li> </ul> <h4 id="engine-api-changes">Engine API Changes</h4> <p>We make the following changes to the engine API:</p> <ul> <li>Add <code>engine_getInclusionListV1</code> endpoint to retrieve an IL from the <code>ExecutionEngine</code>.</li> <li>Add <code>engine_updatePayloadWithInclusionListV1</code> endpoint to update a payload with the IL that should be used to build the block. This takes as an argument an 8-byte <code>payloadId</code> of the ongoing payload build process, along with the IL itself.</li> <li>Modify <code>engine_newPayload</code> endpoint to include a parameter for transactions in ILs determined by the IL committee member. If the IL is not satisfied an <code>INCLUSION_LIST_UNSATISFIED</code> status must be returned.</li> </ul> <h4 id="il-building">IL Building</h4> <p>The rules for building ILs are left to the discretion of implementers. For instance, they may select transactions from the public mempool in various ways such as at random, by priority fee, or based on how long they have been pending. The IL has a maximum size of <code>MAX_BYTES_PER_INCLUSION_LIST = 8 KiB</code> for all of the RLP encoded transactions.</p> <h3 id="consensus-layer">Consensus Layer</h3> <p>The full consensus changes can be found in the following GitHub repository. They are split between:</p> <ul> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/e678deb772fe83edd1ea54cb6d2c1e4b1e45cec6/specs/_features/eip7805/beacon-chain.md">Beacon Chain</a> changes.</li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/e678deb772fe83edd1ea54cb6d2c1e4b1e45cec6/specs/_features/eip7805/fork-choice.md">Fork choice</a> changes.</li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/e678deb772fe83edd1ea54cb6d2c1e4b1e45cec6/specs/_features/eip7805/p2p-interface.md">P2P</a> changes.</li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/e678deb772fe83edd1ea54cb6d2c1e4b1e45cec6/specs/_features/eip7805/validator.md">Honest validator guide</a> changes.</li> </ul> <h4 id="beacon-chain-changes">Beacon chain changes</h4> <h5 id="preset">Preset</h5> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><code>DOMAIN_IL_COMMITTEE</code></td><td><code>DomainType('0x0C000000')</code></td></tr> <tr><td><code>IL_COMMITTEE_SIZE</code></td><td><code>uint64(2**4)</code> (=16)</td></tr> <tr><td><code>MAX_BYTES_PER_INCLUSION_LIST</code></td><td><code>uint64(2**13)</code> (=8192)</td></tr> </tbody></table> <h5 id="new-containers">New containers</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"> InclusionList</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> slot</span><span>:</span><span> Slot</span></span> <span class="giallo-l"><span> validator_index</span><span>:</span><span> ValidatorIndex</span></span> <span class="giallo-l"><span> inclusion_list_committee_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> transactions</span><span>:</span><span> List</span><span>[</span><span>Transaction</span><span>,</span><span class="z-constant"> MAX_TRANSACTIONS_PER_PAYLOAD</span><span>]</span></span></code></pre><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"> SignedInclusionList</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> message</span><span>:</span><span> InclusionList</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span> BLSSignature</span></span></code></pre><h4 id="fork-choice-changes">Fork choice changes</h4> <ul> <li>Store ILs observed over gossip before the view freeze deadline.</li> <li>If more than one IL is observed from the same IL committee member, mark the committee member as an equivocator and ignore any further ILs from them.</li> <li>The beacon block from the current slot is only attested to if it satisfies IL conditions, based on all stored ILs from non equivocators.</li> </ul> <h4 id="p2p-changes">P2P changes</h4> <ul> <li>A new global topic for broadcasting <code>SignedInclusionList</code> objects.</li> <li>A new RPC topic for request <code>SignedInclusionList</code> based on IL committee index.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="core-properties">Core Properties</h3> <ul> <li>Committee-based: FOCIL relies on a committee of multiple validators, rather than a single proposer, to construct and broadcast ILs. This approach significantly reduces the surface for bribery and extortion attacks and strengthens censorship resistance.</li> <li>Fork-choice enforced: FOCIL incorporates the force-inclusion mechanism into the fork-choice rule, an integral component of the consensus process, thereby preventing any actor from bypassing the system. Attesters vote only for blocks that include transactions from a set of ILs provided by the IL committee and that satisfy the IL constraints. Any block failing to meet these criteria will not be voted on by the attesters, and therefore cannot be canonical.</li> <li>Same-slot: With FOCIL running in parallel with the block building process for <code>slot N+1</code> during <code>slot N</code>, the constraints imposed on <code>block B</code> for <code>slot N+1</code> can include transactions submitted during <code>slot N</code>. This represents a strict improvement over forward IL designs like <a href="https://wg-eips.ritovision.com/7547/">EIP-7547</a>, where the forward property introduced a 1-slot delay.</li> <li>Conditional inclusion: FOCIL adopts conditional inclusion, accepting blocks that may lack some transactions from ILs if they cannot append the transactions to the end of the block or if they are full.</li> <li>Anywhere-in-block: FOCIL is unopinionated about the placement of transactions from ILs within a block. This reduces incentives for sophisticated actors to use side channels to bypass the mechanism. Combined with conditional inclusion, this flexibility makes the emergence of off-protocol markets less attractive.</li> <li>No incentive mechanism: FOCIL does not provide explicit rewards for IL committee members participating in the mechanism. We believe that the added complexity of implementing a transaction fee system for FOCIL is not justified. Instead, we rely on altruistic behavior, as FOCIL requires only a <code>1-out-of-N</code> honesty assumption from IL committee members for the mechanism to work as intended.</li> </ul> <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> <h3 id="consensus-liveness">Consensus Liveness</h3> <p>The builder of <code>slot N+1</code> cannot construct a canonical block without first receiving the ILs broadcast during <code>slot N</code>. This means that the builder (including cases in which the proposer locally builds its block) must be well-connected to the IL committee members to ensure timely access to these inclusion lists. Additionally, there must be sufficient time between the view freeze deadline (<code>t=9s</code> of <code>slot N</code>) and the moment the proposer must broadcast <code>block B</code> to the rest of the network. This buffer allows the builder to gather all available ILs and update the execution payload of <code>block B</code> accordingly.</p> <h3 id="il-equivocation">IL Equivocation</h3> <p>To mitigate IL equivocation, FOCIL introduces a new P2P network rule that allows forwarding up to two ILs per IL committee member. If the proposer or attesters detect two different ILs sent by the same IL committee member, they should ignore all ILs from that member. In the worst case, the bandwidth of the IL gossip subnet can at most double.</p> <h3 id="payload-construction">Payload Construction</h3> <p>The builder, responsible for constructing the execution payload, must ensure that the IL is satisfied. A naive way to do so would be to build an initial payload in whatever way the builder desires, then execute the following algorithm:</p> <ol> <li>Sequentially check validity of any yet-to-be-included IL tx against the post-state. If none is found, payload building is over.</li> <li>If one is found, append it to the end of the payload and update the post-state. Go back to step 1.</li> </ol> <p>The issue with this simple approach is that, given a set of <code>n</code> IL transactions, one might end up needing to do <code>n + (n-1) + (n-2) + ...</code> validity checks, so <code>O(n^2)</code>. For example, the <code>n</code>th tx might be valid while all others are not, but its execution sends balance to the sender of the <code>(n-1)</code>th tx, making it valid, and in turn, the <code>(n-1)</code>th sends balance to the sender of the <code>(n-2)</code>th tx, etc.</p> <p>To efficiently ensure that all valid IL txs have been included in the payload, builders can adopt a simple strategy: prior to building the payload, they store the <code>nonce</code> and <code>balance</code> of all Externally Owned Accounts (EOAs) involved in IL transactions. As they construct the payload, builders track these EOAs, maintaining and updating each EOA's <code>nonce</code> and <code>balance</code> whenever changes occur—specifically, when the <code>nonce</code> increments (indicating that a transaction from that EOA has been executed) or when the <code>balance</code> changes without a <code>nonce</code> increment (e.g., after an Account Abstraction (AA) transaction has interacted with that EOA).</p> <p>This tracking allows builders to verify IL transaction validity in real-time, enabling them to add transactions sequentially until all remaining transactions are either invalid because the nonce or balance of the associated EOA does not change or cannot be included due to insufficient gas. This approach minimizes overhead by keeping track only of the state changes that are relevant to the validity of IL txs.</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-31T00:00:00+00:00 2026-02-11T14:49:27+00:00 Lucas Saldanhahttps://github.com/lucassaldanha Mikhail Kalininhttps://github.com/mkalinin https://wg-eips.ritovision.com/7804/

Allow validators to update their withdrawal credentials via execution requests

<h2 id="abstract">Abstract</h2> <p>This proposal defines a mechanism to allow validators to update their withdrawal credentials using a new execution request type (0x03). The request allows for changing the execution address and the withdrawal credential prefix (0x01 or 0x02).</p> <h2 id="motivation">Motivation</h2> <p>When the ability to update a validator BLS withdrawal credentials to execution address was introduced in Capella, one of the most common questions was about allowing the withdrawal credential to be changed in the future. Either for security (e.g. credential rotation) or to allow for alternative ways of handling withdrawals (e.g. having a contract address as credentials). The main reason for not adding this options was because implementing this communication channel between the Execution Layer and the Consensus Layer is complex (based on the experience with the Eth1 bridge).</p> <p>In Electra, the protocol was upgraded with Execution Requests (deposits, withdrawals and consolidations), and a mechanism for general purpose execution requests <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a>, decreasing the complexity of adding a new request from execution to consensus layer.</p> <p>The introduction of execution requests that are created on the execution layer, opened up possibilities on how validators can be managed. Execution request can be created via smart contracts, allowing for decentralized and on-chain mechanisms to be explored. This also means validators will be able to move between execution and compounding withdrawal credentials (following the correct churn on the total staked amount).</p> <p>For an execution request to be authorized in the consensus layer, the withdrawal credential of the validator must be the same of the <code>msg.caller</code> when processing the transaction on the EVM. So the validator's withdrawal credential must be the same address of the smart contract creating the request (not the credential of the transaction sender), or the contract needs to use <code>DELEGATECALL</code> to ensure the caller address matches the address in the validator's withdrawal credential. Validators that already have a contract address as their withdrawal credentials should be able to update their contracts to meet this demand (assuming they have an updatable contract).</p> <p>There problems for existing validators that have their withdrawal credentials set to an EOA account is they will never be able to use smart contracts for creating execution requests, because the current design does not allow for these credentials to ever be changed.</p> <p>Allowing for validators to update their withdrawal credentials mean they can opt-in and out of different schemes and strategies on managing their validators, favouring experimentation and innovation. Today, the only alternative to this is exiting the validator and creating a new validator with different withdrawal credentials.</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>FORK_TIMESTAMP</code></td><td><em>TBD</em></td><td>Mainnet</td></tr> </tbody></table> <h3 id="configuration">Configuration</h3> <table><thead><tr><th>Name</th><th>Value</th><th>Comment</th></tr></thead><tbody> <tr><td><code>WITHDRAWAL_CREDENTIALS_UPDATE_REQUEST_PREDEPLOY_ADDRESS</code></td><td><code>0x09Fc772D0857550724b07B850a4323f39112aAaA</code></td><td>Where to call and store relevant details about the withdrawal credentials update mechanism</td></tr> <tr><td><code>WITHDRAWAL_CREDENTIALS_UPDATE_REQUEST_TYPE</code></td><td><code>0x03</code></td><td>The <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> type prefix for withdrawal credential update request</td></tr> <tr><td><code>SYSTEM_ADDRESS</code></td><td><code>0xfffffffffffffffffffffffffffffffffffffffe</code></td><td>Address used to invoke system operation on contract</td></tr> <tr><td><code>EXCESS_WITHDRAWAL_CREDENTIALS_UPDATE_REQUESTS_STORAGE_SLOT</code></td><td>0</td><td></td></tr> <tr><td><code>WITHDRAWAL_CREDENTIALS_UPDATE_REQUEST_COUNT_STORAGE_SLOT</code></td><td>1</td><td></td></tr> <tr><td><code>WITHDRAWAL_CREDENTIALS_UPDATE_REQUEST_QUEUE_HEAD_STORAGE_SLOT</code></td><td>2</td><td>Pointer to head of the withdrawal credential update request message queue</td></tr> <tr><td><code>WITHDRAWAL_CREDENTIALS_UPDATE_REQUEST_QUEUE_TAIL_STORAGE_SLOT</code></td><td>3</td><td>Pointer to the tail of the withdrawal credential update request message queue</td></tr> <tr><td><code>WITHDRAWAL_CREDENTIALS_UPDATE_REQUEST_QUEUE_STORAGE_OFFSET</code></td><td>4</td><td>The start memory slot of the in-state withdrawal credential update request message queue</td></tr> <tr><td><code>MAX_WITHDRAWAL_CREDENTIALS_UPDATE_REQUESTS_PER_BLOCK</code></td><td>4</td><td>Maximum number of withdrawal credential update requests that can be dequeued into a block</td></tr> <tr><td><code>TARGET_WITHDRAWAL_CREDENTIALS_UPDATE_REQUESTS_PER_BLOCK</code></td><td>1</td><td></td></tr> <tr><td><code>MIN_WITHDRAWAL_CREDENTIALS_UPDATE_REQUEST_FEE</code></td><td>1</td><td></td></tr> <tr><td><code>WITHDRAWAL_CREDENTIALS_UPDATE_REQUEST_FEE_UPDATE_FRACTION</code></td><td>17</td><td></td></tr> <tr><td><code>EXCESS_INHIBITOR</code></td><td><code>2**256-1</code></td><td>Excess value used to compute the fee before the first system call</td></tr> </tbody></table> <h3 id="execution-layer">Execution Layer</h3> <ul> <li><strong><code>FORK_BLOCK</code></strong> -- the first block in a blockchain with the <code>timestamp</code> greater or equal to <code>FORK_TIMESTAMP</code>.</li> </ul> <h4 id="withdrawal-credentials-update-request-operation">Withdrawal Credentials Update request operation</h4> <p>The new withdrawal credential update request operation is an <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> request with type <code>0x03</code> and consists of the following fields:</p> <ol> <li><code>pubkey</code>: <code>Bytes48</code></li> <li><code>old_address</code>: <code>Bytes20</code></li> <li><code>new_address</code>: <code>Bytes20</code></li> </ol> <p>The <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> encoding of a withdrawal credential update request is computed as follows.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>request_type</span><span class="z-keyword"> =</span><span class="z-constant"> WITHDRAWAL_CREDENTIALS_UPDATE_REQUEST_TYPE</span></span> <span class="giallo-l"><span>request_data</span><span class="z-keyword"> =</span><span> read_withdrawal_credential_update_requests</span><span>(</span><span>)</span></span></code></pre><h4 id="withdrawal-credentials-update-request-contract">Withdrawal Credentials Update Request Contract</h4> <p>The contract is similar to other execution requests contracts for Deposits, Withdrawals and Consolidation. The contract has three different code paths, which can be summarized at a high level as follows:</p> <ol> <li>Add request - requires a <code>68</code> byte input, the validator's public key concatenated with the new address for withdrawal credentials.</li> <li>Excess requests getter - if the input length is zero, return the current excess requests count.</li> <li>System process - if called by system address, pop off the withdrawal credential update requests for the current block from the queue.</li> </ol> <!-- TODO add sudo code / bytecode / deployment / etc (very similar to existing request contracts) --> <h4 id="block-processing">Block processing</h4> <p>At the end of processing any execution block where <code>block.timestamp &gt;= FORK_TIMESTAMP</code> (i.e. after processing all transactions and after performing the block body requests validations) client software <strong>MUST</strong> include a call the contract as <code>SYSTEM_ADDRESS</code> and empty input data to trigger the system subroutine execute. The response should be treated as a new request type (0x03) according to <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a>.</p> <h4 id="block-validation">Block Validation</h4> <p>EL must check that the commitment hash in the execution block header matches the hash of the list of execution requests the CL sends when validating the execution block (including any requests of the new defined type 0x03).</p> <h3 id="consensus-layer">Consensus Layer</h3> <!-- TODO complete the specification --> <p>Summary of changes:</p> <ul> <li>New container <code>WithdrawalCredentialUpdateRequest</code></li> <li>New method in Block Processing: <code>process_withdrawal_credential_update_request</code></li> <li>New Beacon State mutator method: <code>update_withdrawal_credentials</code></li> </ul> <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"> WithdrawalCredentialUpdateRequest</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> validator_pubkey</span><span>:</span><span> BLSPubkey</span></span> <span class="giallo-l"><span> old_address</span><span>:</span><span> ExecutionAddress</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> request contract will set this to msg.caller</span></span> <span class="giallo-l"><span> new_address</span><span>:</span><span> ExecutionAddress</span></span></code></pre><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_withdrawal_credential_update_request</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"> withdrawal_credentials_update_requests</span><span>:</span><span> WithdrawalCredentialUpdateRequest</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> validator_pubkeys</span><span class="z-keyword"> =</span><span> [</span><span>v</span><span>.</span><span>pubkey</span><span class="z-keyword"> for</span><span> v</span><span class="z-keyword"> in</span><span> state</span><span>.</span><span>validators</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify pubkey exists</span></span> <span class="giallo-l"><span> request_pubkey</span><span class="z-keyword"> =</span><span> withdrawal_credentials_update_requests</span><span>.</span><span>validator_pubkey</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> request_pubkey</span><span class="z-keyword"> not</span><span class="z-keyword"> in</span><span> validator_pubkeys</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span> index</span><span class="z-keyword"> =</span><span> ValidatorIndex</span><span>(</span><span>validator_pubkeys</span><span>.</span><span>index</span><span>(</span><span>request_pubkey</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> validator</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>validators</span><span>[</span><span>index</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"> Verify withdrawal credentials</span></span> <span class="giallo-l"><span> has_correct_credential</span><span class="z-keyword"> =</span><span> has_execution_withdrawal_credential</span><span>(</span><span>validator</span><span>)</span></span> <span class="giallo-l"><span> is_correct_old_address</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> validator</span><span>.</span><span>withdrawal_credentials</span><span>[</span><span class="z-constant">12</span><span>:</span><span>]</span><span class="z-keyword"> ==</span><span> withdrawal_credentials_update_requests</span><span>.</span><span>old_address</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> (</span><span>has_correct_credential</span><span class="z-keyword"> and</span><span> is_correct_old_address</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> credential_type</span><span class="z-keyword"> =</span><span> withdrawal_credentials_update_requests</span><span>.</span><span>type</span></span> <span class="giallo-l"><span> is_eth1_type</span><span class="z-keyword"> =</span><span> credential_type</span><span class="z-keyword"> ==</span><span class="z-constant"> ETH1_ADDRESS_WITHDRAWAL_PREFIX</span></span> <span class="giallo-l"><span> is_compounding_type</span><span class="z-keyword"> =</span><span> credential_type</span><span class="z-keyword"> ==</span><span class="z-constant"> COMPOUNDING_WITHDRAWAL_PREFIX</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify valid type</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> (</span><span>is_eth1_type</span><span class="z-keyword"> or</span><span> is_compounding_type</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-invalid z-deprecated">;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> update_withdrawal_credentials</span><span>(</span><span>state</span><span>,</span><span> index</span><span>,</span><span> credential_type</span><span>,</span><span> withdrawal_credentials_update_requests</span><span>.</span><span>new_address</span><span>)</span></span></code></pre><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"> update_withdrawal_credentials</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"> index</span><span>:</span><span> ValidatorIndex</span><span>,</span><span class="z-variable z-parameter z-function"> new_credential_type</span><span>:</span><span> Bytes1</span><span>,</span><span class="z-variable z-parameter z-function"> new_withdrawal_credentials</span><span>:</span><span> ExecutionAddress</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> old_credential_type</span><span class="z-keyword"> =</span><span> validator</span><span>.</span><span>withdrawal_credentials</span><span>[</span><span>:</span><span class="z-constant">1</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> validator</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>validators</span><span>[</span><span>index</span><span>]</span></span> <span class="giallo-l"><span> validator</span><span>.</span><span>withdrawal_credentials</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> new_credential_type</span></span> <span class="giallo-l"><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"> 11</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> new_withdrawal_credentials</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 moving from 0x01 to 0x02</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>old_credential_type</span><span class="z-keyword"> ==</span><span class="z-constant"> ETH1_ADDRESS_WITHDRAWAL_PREFIX</span><span class="z-keyword"> and</span><span> new_credential_type</span><span class="z-keyword"> ==</span><span class="z-constant"> COMPOUNDING_WITHDRAWAL_PREFIX</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-keyword">TODO</span><span class="z-comment">: in this case we need to ensure we put them through the churn/likely re-using some of the exiting rules</span></span> <span class="giallo-l"><span> switch_to_compounding_validator</span><span>(</span><span>state</span><span>,</span><span> index</span><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> <!-- TODO --> <h2 id="test-cases">Test Cases</h2> <!-- TODO --> <h2 id="security-considerations">Security Considerations</h2> <p>Ownership is defined based on control of the withdrawal credential account, either as a private key (for EOA accounts) or controlling the smart contract at the address set as withdrawal credential. Therefore allowing an update should not bring any security implications.</p> <p>Further discussion needed.</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-30T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ahmad Bitarhttps://github.com/smartprogrammer93smartprogrammer@windowslive.com Giulio Rebuffohttps://github.com/Giulio2002 Gary Schultehttps://github.com/garyschultegaryschulte@gmail.com https://wg-eips.ritovision.com/7801/

Introduces the etha subprotocol for serving historical blocks data.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes the creation of a new subprotocol, <code>etha</code>, enabling Ethereum nodes to communicate available block spans via a bitmask. Each bit represents a 106_496-block span within each 1_064_960 block range of chain history. Nodes use this bitmask to signal stored spans and commit to storing future spans as they are created. This allows peers to make informed decisions about data availability without first connecting and querying for it. The bitmask repeats every 1_064_960 blocks for straightforward reasoning about data availability probabilities.</p> <p>The <code>etha</code> subprotocol has the same functionality to serve historical data using message types copied from the <code>eth</code> protocol, enabling efficient data retrieval.</p> <h2 id="motivation">Motivation</h2> <p>With <a href="https://wg-eips.ritovision.com/4444/">EIP-4444</a>, nodes may prune historical data while others continue serving it. Determining data availability by connecting and requesting blocks is inefficient consuming unnecessary bandwidth. This EIP addresses this inefficiency by enabling nodes to shard chain history into 106_496 block segments and signal availability via a bitmask.</p> <p>By introducing a separate subprotocol, <code>etha</code>, nodes can exchange this information seamlessly and retain the ability to serve historical data without impacting existing <code>eth</code> protocol versions.</p> <h2 id="specification">Specification</h2> <h3 id="subprotocol-handshake">Subprotocol Handshake</h3> <ul> <li>Introduce a new subprotocol named <code>etha</code>.</li> <li>Define the handshake message for the <code>etha</code> subprotocol as follows: <ul> <li>Handshake packet: <code>[version: P, networkid: P, blockhash: B_32, genesis: B_32, forkid, blockBitmask]</code></li> <li><code>blockBitmask</code> is a 10-bit bitmask, with each bit representing a 106_496-block range per 1_064_960 blocks of history.</li> <li>the rest of the elements are as defined in eth/69</li> </ul> </li> </ul> <h3 id="supported-messages">Supported Messages</h3> <p>The <code>etha</code> subprotocol <strong>MUST</strong> include support for the following messages from the <code>eth/69</code> protocol to facilitate historical data serving:</p> <ul> <li><strong>GetBlockBodies (0x05):</strong> Request block bodies.</li> <li><strong>BlockBodies (0x06):</strong> Response to <code>GetBlockBodies</code>.</li> <li><strong>GetReceipts (0x0f):</strong> Request receipts.</li> <li><strong>Receipts (0x10):</strong> Response to <code>GetReceipts</code>.</li> </ul> <p>The semantics and payload structures for these messages are identical to their counterparts in the <code>eth/69</code> protocol, ensuring compatibility for historical data serving.</p> <h3 id="node-behavior">Node Behavior</h3> <ul> <li><strong>Bitmask Initialization</strong>: Nodes <strong>MAY</strong> set at least one bit in the <code>blockBitmask</code> to <code>on</code> upon startup and backfill the corresponding 106_496-block span.</li> <li><strong>Shard Retention Probability</strong>: Nodes <strong>MUST</strong> retain new block spans according to their bitmask, aiming to cover at least 10% of chain history.</li> <li><strong>Commitment to Future Ranges</strong>: Nodes <strong>MUST</strong> retain spans corresponding to their advertised bitmask as new blocks are added.</li> <li><strong>Bitmask Space</strong>: The 106_496 range <code>blockBitmask</code> repeats every 1_064_960 blocks, enabling efficient representation of historical data locality across epochs.</li> </ul> <p>Upon connection using <code>etha</code>, nodes exchange the handshake message with the <code>blockBitmask</code>. This single handshake eliminates the need for additional message types.</p> <h3 id="enr-extension">ENR Extension</h3> <p>Alternatively, the <code>blockBitmask</code> could be derived or encoded into the Ethereum Node Record (ENR), enabling nodes to advertise block spans without a handshake. As an example, the <code>blockBitmask</code> can be derived from the <code>secp256k1</code> field of the ENR. However, this method lacks the authentication and reliability of the handshake approach. Additionally, there is not guarantee that the node you are connecting to supports the <code>etha</code> subprotocol.</p> <h2 id="rationale">Rationale</h2> <p>The bitmask approach provides a flexible means to represent and retain block data while committing to future spans. This mechanism aligns with the pruning proposed in EIP-4444, while ensuring that historical and future data spans remain available across the network.</p> <p>A similar bitlist approach is already used in the Consensus Layer for attestation subnets, making it a familiar and efficient method for representing data spans. Additionally, committing to future spans ensures better predictability and stability for data locality.</p> <p>The <code>etha</code> subprotocol separates this functionality from <code>eth</code> ensuring nodes dont hammer other nodes with requests on historical ranges that they do not posses on the eth protocol.</p> <p>The range sizes of 106,496 and 1,064,960 blocks were chosen because they are multiples of Era1’s maximum block range of 8,192, which allows for straightforward storage and representation using Era1 files.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The <code>etha</code> subprotocol is independent of the <code>eth</code> protocol. This EIP does not affect the consensus engine or require a hard fork.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are some considerations:</p> <ul> <li>Data unavailability for any given shard can be modeled as: P = (0.9)^n, where n is the number of peers. Assuming a random distribution of nodes that are participating in EIP-7801 history sharding, for 25 peers, this chance is 7%. For 32 peers, this chance drops to 3.4%. This assumes that a significant number of nodes on the network are serving at least one shard. Adoption by a majority of clients as a default would likely be necessary for a complete sharded history to be available and replicated sufficiently across the network.</li> <li>As history grows, so will the size of the retained shards on disk, thus raising the storage requirements per node. However, nodes will still benefit from a ~90% storage reduction over the present chain storage requirements, and will scale their future chain storage requirements by only 10% of the rate they would have by retaining all history.</li> </ul> <h2 id="copyright">Copyright</h2> <p>This document is CC0-licensed; rights are waived through <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-10-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 skeletorhttps://github.com/skeletor-spaceman partihttps://github.com/0xParticle joxeshttps://github.com/Joxess nghttps://github.com/0xng agus duhahttps://github.com/agusduha discohttps://github.com/0xDiscotech gotzengotzen@defi.sucks 0age0age@uniswap.org Mark Tynewaymark@oplabs.co Zain Bacchuszain@oplabs.co Matt Solomonmsolomon@oplabs.co Maurelianmaurelian@protonmail.ch Blaine Malonehttps://github.com/blmalone https://wg-eips.ritovision.com/7802/

Allow authorized contracts to mint and burn token representations during crosschain transfers

<h2 id="abstract">Abstract</h2> <p>This standard introduces a minimal and extensible interface, <code>IERC7802</code>, for tokens to enable standardized crosschain communication. The interface consists of two functions, <code>crosschainMint</code> and <code>crosschainBurn</code>, which allow authorized bridge contracts to mint and burn token representations during crosschain transfers. These functions serve as the entry points for bridge logic, enabling consistent handling of token supply across chains.</p> <p>The interface also defines two standardized events, <code>CrosschainMint</code> and <code>CrosschainBurn</code>, which emit metadata, including the target address, token amount, and caller. These events facilitate deterministic indexing and monitoring of crosschain activities by off-chain agents, such as indexers, analytics tools, and auditors.</p> <p><code>IERC7802</code> is intentionally lightweight, ensuring minimal overhead for implementation. Its modular design enables extensibility, allowing additional features—such as mint/burn limits, transfer fees, or bridge-specific access control mechanisms—to be layered on top without modifying the base interface.</p> <h2 id="motivation">Motivation</h2> <p>All rollups and multiple important sidechains implement canonical bridges that embed their security into some part of the network's core architecture. These bridges do not have mint/burn rights over original tokens, so they usually lock (unlock) liquidity on the native chain and then mint (burn) a non-equivalent representation on the other. Mint/burn is used because the native token is non-existent on that side, so they must create a new representation. However, each bridge implements a different interface for minting/burning on non-native chains.</p> <p>This interface fragmentation is a massive issue in crosschain communication among chains via third-party bridges or future canonical solutions. At this point, it is clear that every bridge would benefit from a standardized interface for minted/burnt tokens.</p> <p>There have been different attempts in the past to standardize token-bridging interfaces. However, third-party providers are also developing crosschain token frameworks. Each framework defines its features, like rate limits and fee switches, and implements its mint and burn versions. The resultant interfaces become highly specific, lacking naming conventions and structures.</p> <p>The proposed interface includes the most relevant and minimal set of actions used by most of these standards. These actions also do not require any governance or owner participation, in contrast, for instance, to set rate limits.</p> <h2 id="specification">Specification</h2> <p>This ERC introduces the <code>IERC7802</code> interface.</p> <h3 id="interface-identification">Interface Identification</h3> <p>The interface identifier for <code>IERC7802</code> is <strong><code>0x33331994</code></strong>, calculated according to <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> as the XOR of the function selectors of the two functions in the interface:</p> <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"> constant</span><span> INTERFACE_ID_IERC7802 </span><span class="z-keyword">=</span><span> </span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-string">&quot;crosschainMint(address,uint256)&quot;</span><span>)</span><span>)</span><span class="z-keyword"> ^</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-string">&quot;crosschainBurn(address,uint256)&quot;</span><span>)</span><span>)</span><span>;</span></span></code></pre> <p>or via Solidity as</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-variable z-language">type</span><span>(</span><span>IERC7802</span><span>)</span><span>.</span><span>interfaceId</span></span></code></pre> <p>Implementors MUST ensure that the <code>supportsInterface</code> method of ERC-165 returns true for this interface ID to indicate support for <code>IERC7802</code>.</p> <h3 id="methods">Methods</h3> <p><strong><code>crosschainMint</code></strong></p> <p>Mints <code>_amount</code> of token to address <code>_account</code>.</p> <p>This function works as the minting entry point for bridge contracts.</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"> crosschainMint</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"> uint256</span><span class="z-variable z-parameter z-function"> _amount</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Implementations SHOULD emit <code>Transfer(address(0), _to, _amount)</code> on calls to <code>crosschainMint</code> to be compliant with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> invariants on token creation.</p> <p><strong><code>crosschainBurn</code></strong></p> <p>Burns <code>_amount</code> of token from address <code>_account</code>.</p> <p>This function works as the burning entry point for bridge contracts.</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"> crosschainBurn</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"> uint256</span><span class="z-variable z-parameter z-function"> _amount</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Implementations might consider emitting <code>Transfer(_from, address(0), _amount)</code> on calls to <code>crosschainBurn</code> to be compliant with <a href="https://wg-eips.ritovision.com/5679/">ERC-5679</a>.</p> <h3 id="events">Events</h3> <p><strong><code>CrosschainMint</code></strong></p> <p>MUST trigger when <code>crosschainMint</code> is successfully called. The <code>_sender</code> parameter MUST be set to the msg.sender at the time the function is 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"> CrosschainMint</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"> _amount</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>;</span></span></code></pre> <p><strong><code>CrosschainBurn</code></strong></p> <p>MUST trigger when <code>crosschainBurn</code> is successfully called. The <code>_sender</code> parameter MUST be set to the msg.sender at the time the function is 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"> CrosschainBurn</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-variable"> _amount</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></code></pre><h2 id="rationale">Rationale</h2> <h3 id="design-philosophy">Design philosophy</h3> <p>The core design decisions behind this minimal interface are</p> <ul> <li>Bridge agnosticism.</li> <li>Extensibility.</li> </ul> <p><strong>Bridge agnosticism</strong> This interface is designed so bridges, not tokens, contain the logic to process crosschain actions. By maintaining this separation of concerns, token contracts remain simple, reducing their attack surface and easing auditing and upgradability. Offloading crosschain complexities to bridge contracts ensures that tokens do not embed specific bridge logic.</p> <p>By implementing the proposed interface, tokens can be supported by different bridge designs:</p> <ul> <li>Lock/unlock bridges can still operate and do not require any token modification.</li> <li>Burn/mint bridges can now use a universal and minimal token interface, so they will not need to introduce bridge-specific representations, improving crosschain fungibility.</li> </ul> <p><strong>Extensibility</strong> The minimal interface serves as a foundational layer upon which other standards can be built. Token issuers or bridge contracts can extend functionality by adding features such as mint/burn limits, crosschain transfer fees, and more without altering the core interface.</p> <p>The interface is intentionally neutral and does not impose conditions on:</p> <ul> <li><strong>Access Control</strong>: Token issuers determine who is authorized to call <code>crosschainMint()</code> and <code>crosschainBurn()</code>.</li> <li><strong>Zero Amount Calls</strong>: Token issuers decide whether to allow or revert calls with zero amounts.</li> </ul> <h3 id="separation-of-local-and-crosschain-minting-burning">Separation of Local and crosschain Minting/Burning</h3> <p><strong>Different actions</strong></p> <p>Local minting and burning are fundamentally different from crosschain minting and burning.</p> <ul> <li>In crosschain operations, the total circulating supply across all chains is expected to remain constant, as tokens are transferred between chains rather than created or destroyed in isolation.</li> <li>Agents that mint and burn tokens in crosschain transfer fundamentally differ from token owners. It make sense for the two actors to have different permissions.</li> </ul> <p>Therefore, it is reasonable to have different checks, access controls, and logic (such as mint/burn limits) for crosschain actions.</p> <p><strong>Separation of concerns</strong></p> <p>Merging local and crosschain minting/burning into the same functions can lead to complex implementations that intertwine different operational logic. By splitting into two, concerns remain separate, making the codebase cleaner and more maintainable.</p> <p>This separation of concerns is particularly relevant for</p> <ul> <li>Upgrades: Any changes in access control, limits, or logic will only affect the separate crosschain functions (<code>crosschainMint</code> and <code>crosschainBurn</code>) without altering the standard local mint and burn implementations.</li> <li>Integrations with Different Chains: To make an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> crosschain compatible, issuers simply need to implement the <a href="https://wg-eips.ritovision.com/7802/">ERC-7802</a> extension with the corresponding access controls for each chain. For example, when integrating with Optimism, the ERC-20 would grant access to the Optimism bridge; when integrating with Arbitrum, it would grant access to the Arbitrum bridge. The local mint and burn functions remain unchanged. Using dedicated functions for crosschain operations provides a more modular approach, avoiding the need to modify the base implementation for each chain.</li> </ul> <p><strong>Dedicated events</strong></p> <p>A similar reasoning applies to having dedicated crosschain-specific events. The separation significantly facilitates the work of indexers, analytics tools, and auditors. It allows for straightforward tracking of crosschain activities, detecting anomalies, and monitoring bridge operations. If crosschain and local events are indistinguishable, off-chain agents must implement complex logic to differentiate them, increasing the potential for errors and inefficiencies.</p> <h3 id="erc-165-interface">ERC-165 Interface</h3> <p>The inclusion of ERC-165 provides an additional security check for integrators. By providing the interface identifier through the <code>supportsInterface</code> method, callers can programmatically confirm that the token adheres to the <code>IERC7802</code> interface. This verification ensures that the token supports both <code>crosschainMint</code> and <code>crosschainBurn</code> functions, preventing scenarios where only one function is implemented. Such incomplete implementations could lead to issues like users burning tokens to bridge out but being unable to mint them upon return, resulting in failed crosschain actions.</p> <p>It is important to note that this check can only be performed locally on the chain where the token contract resides. There is no inherent guarantee that the token on the receiving chain also supports the <code>IERC7802</code> interface. Ensuring crosschain consistency of interface support is the responsibility of the bridge implementation.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backwards compatible with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>.</p> <p>As discussed in the Motivation section, a minimal, flexible crosschain standard interface is necessary. The problem becomes larger as more tokens are deployed without a standardized format.</p> <ul> <li>Upgradable tokens can be upgraded to implement the new interface.</li> <li>Non-upgradable tokens cannot implement the interface on the token itself. They can still migrate to a standard-compliant version using a lockbox mechanism, as proposed by xERC-20. The idea is to lock non-mintable tokens and mint the same amount of interface-compliant tokens. The bridge contract can act as a lockbox on the native chain.</li> </ul> <p>Bridge contracts will also need an upgrade to integrate with the interface.</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"> 0.8.25</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/ERC20.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/IERC165.sol&quot;</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"> @title</span><span class="z-comment"> IERC7802</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Defines the interface for crosschain ERC20 transfers.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7802</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"> @notice</span><span class="z-comment"> Emitted when a crosschain transfer mints 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"> Address of the account tokens are being minted 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"> amount</span><span class="z-comment"> Amount of tokens minted.</span></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"> Address of the caller (msg.sender) who invoked crosschainMint.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CrosschainMint</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"> amount</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>;</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"> Emitted when a crosschain transfer burns 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"> from</span><span class="z-comment"> Address of the account tokens are being burned from.</span></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 tokens burned.</span></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"> Address of the caller (msg.sender) who invoked crosschainBurn.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CrosschainBurn</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-variable"> amount</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>;</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 through a crosschain 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"> _to</span><span class="z-comment"> Address to mint tokens 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"> _amount</span><span class="z-comment"> Amount of tokens to mint.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> crosschainMint</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"> _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 class="z-storage z-type"> @notice</span><span class="z-comment"> Burn tokens through a crosschain 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"> _from</span><span class="z-comment"> Address to burn tokens from.</span></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 tokens to burn.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> crosschainBurn</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"> _amount</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">contract</span><span class="z-entity z-name"> CrosschainERC20</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC20</span><span>, </span><span class="z-entity z-name">IERC7802</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"> Address of the TOKEN_BRIDGE contract that is allowed to mint/burn tokens.</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> immutable</span><span> TOKEN_BRIDGE</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"> Custom error for unauthorized access.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> Unauthorized</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"> Constructor to set the TOKEN_BRIDGE 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"> _tokenBridge</span><span class="z-comment"> Address of the TOKEN_BRIDGE.</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"> _tokenBridge</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"> ERC20</span><span>(</span><span>name, symbol) </span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_tokenBridge </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;Invalid TOKEN_BRIDGE address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> TOKEN_BRIDGE </span><span class="z-keyword">=</span><span> _tokenBridge</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"> @notice</span><span class="z-comment"> A modifier that only allows the TOKEN_BRIDGE to call</span></span> <span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> onlyTokenBridge</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> TOKEN_BRIDGE</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> Unauthorized</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Allows the TOKEN_BRIDGE 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"> Address to mint tokens 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"> _amount</span><span class="z-comment"> Amount of tokens to mint.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> crosschainMint</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"> _amount</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyTokenBridge</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _mint</span><span>(</span><span>_to</span><span>,</span><span> _amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> CrosschainMint</span><span>(</span><span>_to</span><span>,</span><span> _amount</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Allows the TOKEN_BRIDGE to burn 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"> _from</span><span class="z-comment"> Address to burn tokens from.</span></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 tokens to burn.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> crosschainBurn</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"> _amount</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyTokenBridge</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _burn</span><span>(</span><span>_from</span><span>,</span><span> _amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> CrosschainBurn</span><span>(</span><span>_from</span><span>,</span><span> _amount</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"> 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"> pure</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>IERC7802</span><span>)</span><span>.</span><span>interfaceId </span><span class="z-keyword">||</span><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> <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="permissions">Permissions</h3> <p>Token issuers are responsible for controlling which contracts are authorized to call the <code>crosschainMint()</code> and <code>crosschainBurn()</code> functions. A buggy or malicious authorized caller could mint or burn tokens improperly, damaging token holders and disrupting integrations.</p> <p>One method to minimize potential losses is introducing mint/burn limits, as proposed by xERC-20. These features are fully compatible with the proposed interface.</p> <h3 id="wrapped-native-tokens">Wrapped Native Tokens</h3> <p>This standard should not be used for wrapped native tokens like WETH, as it can lead to uncollateralized minting if the bridge does not control the underlying asset.</p> <p>The only safe exception is when the bridge can burn and mint the native token symmetrically on both chains, ensuring proper collateralization.</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-29T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status Gajinder Singhhttps://github.com/g11tech https://wg-eips.ritovision.com/7799/

Per-block logs without associated transactions

<h2 id="abstract">Abstract</h2> <p>This EIP defines an extension for eth_getLogs to provide logs for events that are not associated with a given transaction, such as block rewards and withdrawals.</p> <h2 id="motivation">Motivation</h2> <p>With <a href="https://wg-eips.ritovision.com/7708/">EIP-7708</a> wallets gain the ability to use eth_getLogs to track changes to their ETH balance. However, the ETH balance may change without an explicit transaction, through block production and withdrawals. By having such operations emit block-level system logs, eth_getLogs provides a complete picture of ETH balance changes.</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="fee-payment-logs">Fee payment logs</h3> <p>A log, identical to a LOG2, is issued for every transaction and appended after all other logs created by EVM execution. The fee amount incorporates the total fee charged during transaction execution, including the base fee, the priority fee, and potential blob fees.</p> <table><thead><tr><th>Field</th><th>Value</th></tr></thead><tbody> <tr><td><code>address</code></td><td><code>0xfffffffffffffffffffffffffffffffffffffffe</code> (<a href="https://wg-eips.ritovision.com/4788/"><code>SYSTEM_ADDRESS</code></a>)</td></tr> <tr><td><code>topics[0]</code></td><td><code>0x7bd3aa7d673767f759ebf216e7f6c12844986c661ae6e0f1d988cf7eb7394d1d</code> (<code>keccak256('Fee(address,uint256)')</code>)</td></tr> <tr><td><code>topics[1]</code></td><td><code>from</code> address (zero prefixed to fill uint256)</td></tr> <tr><td><code>data</code></td><td><code>amount</code> in Wei (big endian uint256)</td></tr> </tbody></table> <h3 id="system-logs-list">System logs list</h3> <p>A new list is introduced to track all block level logs emitted from system interactions. The definition uses the <code>Log</code> SSZ type from <a href="https://wg-eips.ritovision.com/6466/">EIP-6466</a>.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>system_logs</span><span class="z-keyword"> =</span><span> ProgressiveList</span><span>[</span><span>Log</span><span>]</span><span>(</span></span> <span class="giallo-l"><span> log_0</span><span>,</span><span> log_1</span><span>,</span><span> log_2</span><span>,</span><span class="z-constant"> ...</span><span>)</span></span></code></pre><h3 id="priority-fee-processing">Priority fee processing</h3> <p>A log SHALL be appended to the system logs list when crediting the batched <a href="https://wg-eips.ritovision.com/8115/">EIP-8115</a> priority fee.</p> <table><thead><tr><th>Field</th><th>Value</th></tr></thead><tbody> <tr><td><code>address</code></td><td><code>0xfffffffffffffffffffffffffffffffffffffffe</code> (<a href="https://wg-eips.ritovision.com/4788/"><code>SYSTEM_ADDRESS</code></a>)</td></tr> <tr><td><code>topics[0]</code></td><td><code>0x5dfe9c0fd3043bb299f97cfece428f0396cf8b7890c525756e4ea5c0ff7d61b2</code> (<code>keccak256('PriorityRewards(address,uint256)')</code>)</td></tr> <tr><td><code>topics[1]</code></td><td><code>to</code> address (zero prefixed to fill uint256)</td></tr> <tr><td><code>data</code></td><td><code>amount</code> in Wei (big endian uint256)</td></tr> </tbody></table> <h3 id="withdrawal-processing">Withdrawal processing</h3> <p>A log SHALL be appended to the system logs list on every <a href="https://wg-eips.ritovision.com/4895/">EIP-4895</a> withdrawal.</p> <table><thead><tr><th>Field</th><th>Value</th></tr></thead><tbody> <tr><td><code>address</code></td><td><code>0xfffffffffffffffffffffffffffffffffffffffe</code> (<a href="https://wg-eips.ritovision.com/4788/"><code>SYSTEM_ADDRESS</code></a>)</td></tr> <tr><td><code>topics[0]</code></td><td><code>0x7fcf532c15f0a6db0bd6d0e038bea71d30d808c7d98cb3bf7268a95bf5081b65</code> (<code>keccak256('Withdrawal(address,uint256)')</code>)</td></tr> <tr><td><code>topics[1]</code></td><td><code>to</code> address (zero prefixed to fill uint256)</td></tr> <tr><td><code>data</code></td><td><code>amount</code> in Wei (big endian uint256)</td></tr> </tbody></table> <h3 id="genesis-processing">Genesis processing</h3> <p>A log SHALL be appended to the system logs list when generating genesis blocks for networks that adopt this EIP from the beginning.</p> <table><thead><tr><th>Field</th><th>Value</th></tr></thead><tbody> <tr><td><code>address</code></td><td><code>0xfffffffffffffffffffffffffffffffffffffffe</code> (<a href="https://wg-eips.ritovision.com/4788/"><code>SYSTEM_ADDRESS</code></a>)</td></tr> <tr><td><code>topics[0]</code></td><td><code>0xba2f6409ffd24dd4df8e06be958ed8c1706b128913be6e417989c74969b0b55a</code> (<code>keccak256('Genesis(address,uint256)')</code>)</td></tr> <tr><td><code>topics[1]</code></td><td><code>to</code> address (zero prefixed to fill uint256)</td></tr> <tr><td><code>data</code></td><td><code>amount</code> in Wei (big endian uint256)</td></tr> </tbody></table> <h3 id="execution-block-header-changes">Execution block header changes</h3> <p>The <a rel="external" href="https://github.com/ethereum/devp2p/blob/5713591d0366da78a913a811c7502d9ca91d29a8/caps/eth.md#block-encoding-and-validity">execution block header</a> is extended with a new field, <code>system-logs-root</code>.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>block_header</span><span>.</span><span>system_logs_root</span><span class="z-keyword"> =</span><span> system_logs</span><span>.</span><span>hash_tree_root</span><span>(</span><span>)</span></span></code></pre><h3 id="json-rpc-api">JSON-RPC API</h3> <p>Block header objects in the context of the JSON-RPC API are extended to include:</p> <ul> <li><code>systemLogsRoot</code>: <code>DATA</code>, 32 Bytes</li> </ul> <p>Log objects in the context of the JSON-RPC API are updated as follows:</p> <ul> <li><code>logIndex</code>: <code>QUANTITY</code> - The additional system logs are indexed consecutively after the existing logs from transaction receipts</li> <li><code>transactionIndex</code>: <code>QUANTITY</code> - <code>null</code> is also used for system logs; pending logs can still be identified by checking the <code>blockHash</code> for <code>null</code></li> <li><code>transactionHash</code>: DATA, 32 Bytes - <code>null</code> is also used for system logs</li> </ul> <h3 id="engine-api">Engine API</h3> <p>In the engine API, the <code>ExecutionPayload</code> for versions corresponding to forks adopting this EIP is extended to include:</p> <ul> <li><code>systemLogsRoot</code>: <code>DATA</code>, 32 Bytes</li> </ul> <p>As part of <code>engine_forkchoiceUpdated</code>, Execution Layer implementations SHALL verify that <code>systemLogsRoot</code> for each block matches the actual value computed from local processing. This extends on top of existing <code>receiptsRoot</code> validation.</p> <h3 id="consensus-executionpayload-changes">Consensus <code>ExecutionPayload</code> changes</h3> <p>The consensus <code>ExecutionPayload</code> type is extended with a new field to store the system logs root.</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"> ExecutionPayload</span><span>(</span><span class="z-constant">...</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"><span> system_logs_root</span><span>:</span><span> Root</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Together with <a href="https://wg-eips.ritovision.com/7708/">EIP-7708</a> this EIP provides the ability for wallets to compute the exact ETH balance from logs without requiring download of every single block header and all withdrawals.</p> <p>The block reward from priority fees no longer has to be summed up by processing all receipts and can be obtained from the system logs root, making it efficiently provable.</p> <h3 id="alternatives-future">Alternatives / Future</h3> <ul> <li> <p>The information from withdrawals is now duplicated across both the <code>withdrawals</code> list and the system logs. Maybe the information could be massaged into the emitted <code>Withdrawal</code> log data, allowing the existing <code>withdrawals</code> list to be retired. The current list design requires the wallet to obtain all block headers and all withdrawals to ensure they obtained all data pertaining to the observed account. Allowing them to be queried using <code>eth_getLogs</code> is more in line with how deposits are being tracked.</p> </li> <li> <p>The log definitions themselves are subject to change. Aligning them with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> for plain credits provides consistency. For withdrawals, the log data could match the form of deposit logs and <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> request logs.</p> </li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As a new field is added to the block header, applications assuming a specific block header layout may need updating.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The emitted logs use <code>SYSTEM_ADDRESS</code> as their <code>address</code> which cannot conflict with user controlled smart 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> 2024-10-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status Gajinder Singhhttps://github.com/g11tech https://wg-eips.ritovision.com/7807/

Migration of execution blocks to SSZ

<h2 id="abstract">Abstract</h2> <p>This EIP defines a migration process of execution blocks to <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/simple-serialize.md">Simple Serialize (SSZ)</a>.</p> <h2 id="motivation">Motivation</h2> <p>With <a href="https://wg-eips.ritovision.com/6404/">EIP-6404</a> SSZ transactions, <a href="https://wg-eips.ritovision.com/6466/">EIP-6466</a> SSZ receipts, and <a href="https://wg-eips.ritovision.com/6465/">EIP-6465</a> SSZ withdrawals, all Merkle-Patricia Tries (MPT) besides the state trie are converted to SSZ. This enables the surrounding data structure, the execution block itself, to also convert to SSZ, achieving a unified block representation across both Consensus Layer and Execution Layer.</p> <ol> <li> <p><strong>Normalized block hash:</strong> The Consensus Layer can compute the block hash autonomously, enabling it to process all consistency checks that currently require asynchronous communication with the Execution Layer (<a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#modified-verify_and_notify_new_payload"><code>verify_and_notify_new_payload</code></a>). This allows early rejection of inconsistent blocks and dropping the requirement to wait for engine API interactions while syncing.</p> </li> <li> <p><strong>Optimized engine API:</strong> With all exchanged data supporting SSZ, the engine API can be changed from the textual JSON encoding to binary SSZ encoding, reducing exchanged data size by ~50% and significantly improving encoding/parsing efficiency.</p> </li> <li> <p><strong>Proving support:</strong> With SSZ, individual fields of the execution block header become provable without requiring full block headers to be present. With <a href="https://wg-eips.ritovision.com/7495/">EIP-7495</a> SSZ <code>ProgressiveContainer</code>, proofs are forward compatible as long as underlying semantics of individual fields are unchanged, reducing maintenance requirements for smart contracts and verifying client applications.</p> </li> <li> <p><strong>Cleanup opportunity:</strong> The conversion to SSZ allows dropping historical fields from the PoW era and the inefficient logs bloom mechanism.</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="gas-amounts">Gas amounts</h3> <p>The different kinds of gas amounts are combined into a single structure, mirroring the <a href="https://wg-eips.ritovision.com/6404/#gas-fees">EIP-6404 gas fees</a>.</p> <table><thead><tr><th>Name</th><th>SSZ equivalent</th></tr></thead><tbody> <tr><td><a href="https://wg-eips.ritovision.com/6404/#normalized-transactions"><code>GasAmount</code></a></td><td><code>uint64</code></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"> GasAmounts</span><span>(</span><span class="z-entity">ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> regular</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> blob</span><span>:</span><span> GasAmount</span></span></code></pre><h3 id="requests-hash-computation">Requests hash computation</h3> <p><code>requests_hash</code> is changed to <code>ExecutionRequests.hash_tree_root()</code> using the same structure as in the Consensus Layer <code>BeaconBlockBody</code>.</p> <h3 id="execution-block-headers">Execution block headers</h3> <p>New execution block headers use a normalized SSZ representation.</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"> ExecutionBlockHeader</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> parent_hash</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> miner</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> state_root</span><span>:</span><span> Bytes32</span></span> <span class="giallo-l"><span> transactions_root</span><span>:</span><span> Root</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> EIP-6404 transactions.hash_tree_root()</span></span> <span class="giallo-l"><span> receipts_root</span><span>:</span><span> Root</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> EIP-6466 receipts.hash_tree_root()</span></span> <span class="giallo-l"><span> number</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> gas_limits</span><span>:</span><span> GasAmounts</span></span> <span class="giallo-l"><span> gas_used</span><span>:</span><span> GasAmounts</span></span> <span class="giallo-l"><span> timestamp</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> extra_data</span><span>:</span><span> ByteList</span><span>[</span><span class="z-constant">MAX_EXTRA_DATA_BYTES</span><span>]</span></span> <span class="giallo-l"><span> mix_hash</span><span>:</span><span> Bytes32</span></span> <span class="giallo-l"><span> base_fees_per_gas</span><span>:</span><span> BlobFeesPerGas</span></span> <span class="giallo-l"><span> withdrawals_root</span><span>:</span><span> Root</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> EIP-6465 withdrawals.hash_tree_root()</span></span> <span class="giallo-l"><span> excess_gas</span><span>:</span><span> GasAmounts</span></span> <span class="giallo-l"><span> parent_beacon_block_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> requests_hash</span><span>:</span><span> Bytes32</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> EIP-6110 execution_requests.hash_tree_root()</span></span> <span class="giallo-l"><span> system_logs_root</span><span>:</span><span> Root</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> EIP-7799 system_logs.hash_tree_root()</span></span></code></pre><h3 id="execution-block-hash-computation">Execution block hash computation</h3> <p>For new blocks, the execution block hash is changed to be based on <code>hash_tree_root</code> in all contexts, including (1) the <code>BLOCKHASH</code> opcode, (2) JSON-RPC API interactions (<code>blockHash</code> field), (3) devp2p networking.</p> <h3 id="consensus-executionpayload-changes">Consensus <code>ExecutionPayload</code> changes</h3> <p>Usages of <code>ExecutionPayloadHeader</code> are replaced with <code>ExecutionBlockHeader</code>.</p> <p>Usages of <code>ExecutionPayload</code> are updated to share <code>hash_tree_root</code> with <code>ExecutionBlockHeader</code>. <code>transactions_root</code>, <code>withdrawals_root</code> and <code>requests_hash</code> are expanded to their full list contents.</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"> ExecutionPayload</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> parent_hash</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> miner</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> state_root</span><span>:</span><span> Bytes32</span></span> <span class="giallo-l"><span> transactions</span><span>:</span><span> ProgressiveList</span><span>[</span><span>Transaction</span><span>]</span></span> <span class="giallo-l"><span> receipts_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> number</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> gas_limits</span><span>:</span><span> GasAmounts</span></span> <span class="giallo-l"><span> gas_used</span><span>:</span><span> GasAmounts</span></span> <span class="giallo-l"><span> timestamp</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> extra_data</span><span>:</span><span> ByteList</span><span>[</span><span class="z-constant">MAX_EXTRA_DATA_BYTES</span><span>]</span></span> <span class="giallo-l"><span> mix_hash</span><span>:</span><span> Bytes32</span></span> <span class="giallo-l"><span> base_fees_per_gas</span><span>:</span><span> BlobFeesPerGas</span></span> <span class="giallo-l"><span> withdrawals</span><span>:</span><span> ProgressiveList</span><span>[</span><span>Withdrawal</span><span>]</span></span> <span class="giallo-l"><span> excess_gas</span><span>:</span><span> GasAmounts</span></span> <span class="giallo-l"><span> parent_beacon_block_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> requests</span><span>:</span><span> ExecutionRequests</span></span> <span class="giallo-l"><span> system_logs_root</span><span>:</span><span> Root</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This completes the transition to SSZ for everything except the execution state trie.</p> <h3 id="future">Future</h3> <ul> <li> <p>With SSZ <code>Log</code>, the withdrawals mechanism and validator requests could be redefined to be based on logs (similar to deposits, originally, but without the delay), possibly removing the need for <code>withdrawals_root</code> and <code>requests_hash</code>.</p> <ul> <li>The CL would insert the extra logs for minting (<a href="https://wg-eips.ritovision.com/7799/">EIP-7799</a>) and could fetch the ones relevant for withdrawing (deposits, requests, consolidations). That mechanism would be more generic than <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> and would drop requiring the EL to special case requests, including <code>compute_requests_hash</code>.</li> <li>For client applications and smart contracts, it would streamline transaction history verification based on <a href="https://wg-eips.ritovision.com/7792/">EIP-7792</a>.</li> </ul> </li> <li> <p>The Engine API should be updated with (1) possible withdrawals/requests refactoring as above, (2) dropping the <code>block_hash</code> field so that <code>ExecutionPayload</code> is replaced with <code>ExecutionBlockHeader</code>, (3) binary encoding based on <code>ForkDigest</code>-context (through HTTP header or interleaved, similar to beacon-API). This reduces encoding overhead and also simplifies sharing data structures in combined CL/EL in-process implementations.</p> </li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This breaks compatibility of smart contracts that depend on the previous block header binary format, including for "generic" implementations that assume a common prefix and run the entire data through a linear keccak256 hash.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The SSZ block hash is based on SHA256 and shares the namespace with existing keccak256 based block hashes. As these hash algorithms are fundamentally different, no significant collision risk is 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> 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-22T00:00:00+00:00 2026-02-11T14:48:25+00:00 Guilherme Neveshttps://github.com/0xneves https://wg-eips.ritovision.com/7794/

A cross-network registry contract to manage and track grants, enhancing transparency and interoperability for grant programs.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a Grant Registry contract intended for managing financial, research, or project-based grants that provide funding for projects across multiple blockchains. The contract standardizes the registration, management, and tracking of these grants by organizing data into distinct categories, enabling clear separation between immutable fields and mutable fields. It supports modular disbursement tracking and allows for external links to off-chain documentation. This registry emits lifecycle events, enabling external protocols to efficiently access grant data, which promotes transparency, interoperability, and enhanced insights into grant program performance.</p> <h2 id="motivation">Motivation</h2> <p>The Ethereum ecosystem currently lacks a standardized way to manage and track grants across different chains and programs, leading to inefficiencies and fragmentation. Each grant program has its own distinct interface, processes, and management mechanisms, which creates barriers for both funders and grantees. These issues hinder transparency, complicate the tracking of fund disbursements, and make it difficult to evaluate the overall effectiveness of grant programs across different networks.</p> <p>The lack of interoperability between grant programs further exacerbates the problem, as projects and contributors often work across multiple blockchains. This makes it challenging to aggregate data, monitor milestones, and assess grantee performance in a consistent manner.</p> <p>The Grant Registry contract solves these issues by introducing a unified standard that ensures all grants can be registered, tracked, and managed consistently, regardless of the underlying chain or program. This approach not only simplifies the lifecycle management of grants but also fosters better collaboration between communities, allowing for more competitiveness and better tracking of progress. Additionally, the standardization of data opens the door for more insightful analytics, enabling protocols to measure the impact of grants in a much more streamlined and transparent way.</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="contract-interface"><strong>Contract Interface</strong></h3> <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.20</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"> IGrantRegistry</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"> Thrown when the community name length is invalid (e.g., too short or too long).</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"> InvalidCommunityNameLength</span><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">@dev</span><span class="z-comment"> Thrown when the caller is not the current grant manager.</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"> InvalidGrantManager</span><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">@dev</span><span class="z-comment"> Thrown when a grant is already registered with the provided ID.</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"> GrantAlreadyRegistered</span><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">@dev</span><span class="z-comment"> Thrown when attempting to add a grantee that is already present in the set.</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"> GranteeAlreadyAdded</span><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">@dev</span><span class="z-comment"> Thrown when attempting to remove a grantee that is not found in the set.</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"> GranteeNotFound</span><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">@dev</span><span class="z-comment"> Thrown when attempting to add or reference an invalid external link.</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"> InvalidExternalLink</span><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">@dev</span><span class="z-comment"> Thrown when an invalid index is provided (e.g., out of bounds for an array).</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"> InvalidIndex</span><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">@dev</span><span class="z-comment"> Thrown when a milestone date is invalid (e.g., earlier than the grant&#39;s start date).</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"> InvalidStartDate</span><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">@dev</span><span class="z-comment"> Thrown when attempting to add a milestone date that is already present.</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"> MilestoneDateAlreadyAdded</span><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">@dev</span><span class="z-comment"> Thrown when attempting to remove or reference a milestone date that is not found.</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"> MilestoneDateNotFound</span><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">@dev</span><span class="z-comment"> Emitted when a new grant is registered.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier for the grant.</span></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 grant&#39;s unique numeric 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"> chainid</span><span class="z-comment"> The chain ID where the grant is registered.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> community</span><span class="z-comment"> The name of the community that issued the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantManager</span><span class="z-comment"> The address of the grant manager.</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"> GrantRegistered</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"> grantId</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"> uint256</span><span class="z-variable"> chainid</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> community</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> grantManager</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"> Emitted when the ownership of a grant is transferred.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> newGrantManager</span><span class="z-comment"> The address of the new grant manager.</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"> OwnershipTransferred</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"> grantId</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"> newGrantManager</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"> Emitted when a new grantee is added to the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantee</span><span class="z-comment"> The address of the new grantee.</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"> GranteeAdded</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> grantId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> grantee</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 a grantee is removed from the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantee</span><span class="z-comment"> The address of the removed grantee.</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"> GranteeRemoved</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> grantId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> grantee</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 the start date of a grant is 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"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> startDate</span><span class="z-comment"> The timestamp representing the start date.</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"> StartDateSet</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> grantId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> startDate</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 a new milestone date is added to the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> milestoneDate</span><span class="z-comment"> The timestamp of the added milestone.</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"> MilestoneDateAdded</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> grantId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> milestoneDate</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 a milestone date is removed from the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> milestoneDate</span><span class="z-comment"> The timestamp of the removed milestone.</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"> MilestoneDateRemoved</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> grantId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> milestoneDate</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 a disbursement is added to a milestone.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> milestoneDate</span><span class="z-comment"> The timestamp of the milestone.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> fundingToken</span><span class="z-comment"> The token used for the disbursement.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> fundingAmount</span><span class="z-comment"> The amount of the disbursement.</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"> DisbursementAdded</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"> grantId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> milestoneDate</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"> fundingToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> fundingAmount</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"> Emitted when a disbursement is removed from a milestone.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> milestoneDate</span><span class="z-comment"> The timestamp of the milestone.</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"> DisbursementRemoved</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> grantId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> milestoneDate</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 a disbursement status is updated.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> milestoneDate</span><span class="z-comment"> The timestamp of the milestone.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> isDisbursed</span><span class="z-comment"> Boolean indicating if the disbursement has been made.</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"> DisbursementMade</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"> grantId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> milestoneDate</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> isDisbursed</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"> Emitted when an external link is added to the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> link</span><span class="z-comment"> The external URL added.</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"> ExternalLinkAdded</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> grantId</span><span>, </span><span class="z-support">string</span><span class="z-variable"> link</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 an external link is removed from the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> link</span><span class="z-comment"> The external URL removed.</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"> ExternalLinkRemoved</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> grantId</span><span>, </span><span class="z-support">string</span><span class="z-variable"> link</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"> Registers a new grant with the provided details. `grantId` is generated by hashing the grant</span></span> <span class="giallo-l"><span class="z-comment"> * details and the current timestamp.</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 `grantManager` address must not be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * - The `community` name must not be empty.</span></span> <span class="giallo-l"><span class="z-comment"> * - The grant must not already be registered.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {GrantRegistered} event.</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"> id</span><span class="z-comment"> The unique identifier for the grant program.</span></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 chain ID where the grant is being registered.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> community</span><span class="z-comment"> The name of the community or protocol issuing the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantManager</span><span class="z-comment"> The address of the grant manager.</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"> generated `grantId` as a bytes32 value.</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"> registerGrant</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"> chainid</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"> community</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> grantManager</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">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"> Transfers ownership of the grant to a new grant manager.</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 be the current grant manager.</span></span> <span class="giallo-l"><span class="z-comment"> * - The `newGrantManager` address must not be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {OwnershipTransferred} event.</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"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> newGrantManager</span><span class="z-comment"> The address of the new grant manager.</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"> transferOwnership</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> newGrantManager</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"> Adds a new grantee to the grant.</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 be the current grant manager.</span></span> <span class="giallo-l"><span class="z-comment"> * - The `grantee` address must not be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {GranteeAdded} event.</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"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantee</span><span class="z-comment"> The address of the grantee to be added.</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"> addGrantee</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> grantee</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"> Removes an existing grantee from the grant.</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 be the current grant manager.</span></span> <span class="giallo-l"><span class="z-comment"> * - The `grantee` address must be present in the grant.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {GranteeRemoved} event.</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"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantee</span><span class="z-comment"> The address of the grantee to be removed.</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"> removeGrantee</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> grantee</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"> Sets the start date for the grant.</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 be the current grant manager.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {StartDateSet} event.</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"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> startDate</span><span class="z-comment"> The timestamp representing the start date.</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"> setStartDate</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> startDate</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"> Adds a new milestone date for the grant.</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 be the current grant manager.</span></span> <span class="giallo-l"><span class="z-comment"> * - The milestone date must not already exist in the grant.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {MilestoneDateAdded} event.</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"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> milestoneDate</span><span class="z-comment"> The timestamp representing the milestone date.</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"> addMilestoneDate</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> milestoneDate</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"> Removes a milestone date from the grant.</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 be the current grant manager.</span></span> <span class="giallo-l"><span class="z-comment"> * - The milestone date must exist in the grant.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {MilestoneDateRemoved} event.</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"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> milestoneDate</span><span class="z-comment"> The timestamp representing the milestone date to be removed.</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"> removeMilestoneDate</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> milestoneDate</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"> Ovewrites a disbursement for a specific milestone.</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 be the current grant manager.</span></span> <span class="giallo-l"><span class="z-comment"> * - The milestone date must exist in the grant.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {DisbursementAdded} event.</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"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> milestoneDate</span><span class="z-comment"> The milestone date associated with the disbursement.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> fundingToken</span><span class="z-comment"> The address of the token used for funding.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> fundingAmount</span><span class="z-comment"> The amount of tokens to be disbursed.</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"> addDisbursement</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> grantId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> milestoneDate</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> fundingToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> fundingAmount</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">@dev</span><span class="z-comment"> Removes a disbursement for a specific milestone.</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 be the current grant manager.</span></span> <span class="giallo-l"><span class="z-comment"> * - The milestone date must exist in the grant.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {DisbursementRemoved} event.</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"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> milestoneDate</span><span class="z-comment"> The milestone date associated with the disbursement.</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"> removeDisbursement</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> milestoneDate</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"> Updates the disbursement status for a specific milestone.</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 be the current grant manager.</span></span> <span class="giallo-l"><span class="z-comment"> * - The milestone date must exist in the grant.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {DisbursementMade} event.</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"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> milestoneDate</span><span class="z-comment"> The milestone date associated with the disbursement.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> isDisbursed</span><span class="z-comment"> A boolean value indicating if the disbursement has been made.</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"> setDisbursementStatus</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> grantId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> milestoneDate</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> isDisbursed</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">@dev</span><span class="z-comment"> Adds an external link related to the grant.</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 be the current grant manager.</span></span> <span class="giallo-l"><span class="z-comment"> * - The link must not be empty.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {ExternalLinkAdded} event.</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"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> link</span><span class="z-comment"> The external URL to be added.</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"> addExternalLink</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> link</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"> Removes an external link associated with the grant.</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 be the current grant manager.</span></span> <span class="giallo-l"><span class="z-comment"> * - The index must be within the bounds of the external links array.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {ExternalLinkRemoved} event.</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"> grantId</span><span class="z-comment"> The unique identifier of the grant.</span></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"> The index of the external link to be removed.</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"> removeExternalLink</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</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>;</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"> Retrieves details of a specific grant by its 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"> grantId</span><span class="z-comment"> The unique identifier of the grant</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"> `Grant` struct containing id, chainid, and community label</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"> getGrant</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</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">Grant</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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Retrieves the current grant manager for a specific grant</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant</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 grant manager</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"> getGrantManager</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</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">@dev</span><span class="z-comment"> Retrieves the list of grantees associated with a specific grant</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant</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"> array of addresses representing the grantees</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"> getGrantees</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> grantId</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">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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Retrieves the start date and list of milestone dates for a specific grant</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant</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"> start date and an array of milestone dates</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"> getMilestonesDates</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> grantId</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 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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Retrieves the disbursement details for a specific milestone in a grant</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> milestoneDate</span><span class="z-comment"> The date of the milestone for which disbursement details are requested</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"> `Disbursements` struct containing the token address, funding amount, and disbursement status</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"> getDisbursement</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> grantId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> milestoneDate</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-storage z-type">Disbursements</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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Retrieves the list of external links associated with a specific grant</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant</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"> array of strings representing the external links</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"> getExternalLinks</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> grantId</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">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></code></pre> <p>When calling the <code>registerGrant</code> function:</p> <ul> <li>The <code>grantManager</code> <strong>MUST</strong> submit a valid grantManager address that is not the zero address.</li> <li>The <code>community</code> label <strong>MUST</strong> be a non-empty string.</li> <li>The <code>grant</code> ID <strong>MUST</strong> be unique and not already registered in the system.</li> </ul> <p>When editing overall grant details:</p> <ul> <li>The <code>grantManager</code> <strong>MUST</strong> be the current grant manager to make changes to the grant.</li> </ul> <p>When adding a <code>milestoneDate</code>:</p> <ul> <li>The <code>milestoneDate</code> <strong>MUST</strong> not exist in the milestonesDates set.</li> </ul> <p>When editing disbursments:</p> <ul> <li>The <code>milestoneDate</code> <strong>MUST</strong> be a valid milestone date associated with the grant.</li> </ul> <p>When adding <code>externalLinks</code>:</p> <ul> <li>The string <strong>MUST</strong> not be empty.</li> </ul> <h2 id="rationale">Rationale</h2> <p>The design of this Grant Registry Contract is driven by the need for a flexible and modular system that supports a wide range of grant programs across different chains. The rationale for the key design decisions is outlined below:</p> <ol> <li> <p>Separation of Fields: The division of fields into different categories, such as identification, grant data, and disbursement-related information, allows for a more efficient use of on-chain storage. Immutable fields like id, chainid, and community are kept separate from mutable fields, ensuring that core identification elements remain unchanged, while other aspects like milestones and participants can be updated throughout the grant lifecycle.</p> </li> <li> <p>Modular Disbursement Handling: Not all grant programs will choose to perform disbursements on-chain. By allowing disbursements to be managed through external links, the contract remains modular and adaptable to different use cases. Programs that prefer to handle disbursements off-chain can still use the registry for status tracking, ensuring broad applicability across different ecosystems.</p> </li> <li> <p>Dynamic Team Management: The participants structure uses EnumerableSet for grantees, allowing for team-based grants. This feature facilitates tracking of contributions and adjustments to the grant team over time, enabling more comprehensive reputation systems and transparency.</p> </li> </ol> <p>This design aims to create a scalable, efficient system that can evolve with the needs of different grant programs, while maintaining key benefits like transparency, modularity, and low gas usage.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</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"> ^0.8.20</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">IGrantRegistry</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./IGrantRegistry.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">EnumerableSet</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/structs/EnumerableSet.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"> GrantRegistry</span><span class="z-storage"> is</span><span class="z-entity z-name"> IGrantRegistry</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> EnumerableSet</span><span class="z-keyword"> for</span><span class="z-entity z-name"> EnumerableSet</span><span>.</span><span>AddressSet</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> EnumerableSet</span><span class="z-keyword"> for</span><span class="z-entity z-name"> EnumerableSet</span><span>.</span><span>UintSet</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"> Mapping to store the details of each grant, keyed by its unique grantId.</span></span> <span class="giallo-l"><span class="z-comment"> */</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> Grant</span><span>)</span><span class="z-storage z-type"> private</span><span> _grants</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"> Stores information about the participants in each grant (manager and grantees), keyed by the grantId.</span></span> <span class="giallo-l"><span class="z-comment"> * This mapping allows tracking of the grant manager and the associated grantees for each grant.</span></span> <span class="giallo-l"><span class="z-comment"> */</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> Participants</span><span>)</span><span class="z-storage z-type"> private</span><span> _participants</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"> Stores milestone-related data for each grant, keyed by the grantId.</span></span> <span class="giallo-l"><span class="z-comment"> * This includes the start date, milestone dates, and disbursements related to each milestone.</span></span> <span class="giallo-l"><span class="z-comment"> */</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> Milestones</span><span>)</span><span class="z-storage z-type"> private</span><span> _milestones</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"> Stores external links related to each grant, such as proposal URLs or related documentation, keyed by grantId.</span></span> <span class="giallo-l"><span class="z-comment"> * External links provide references to off-chain information about the grant.</span></span> <span class="giallo-l"><span class="z-comment"> */</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>]</span><span>)</span><span class="z-storage z-type"> private</span><span> _externalLinks</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 {IGrantRegistry-registerGrant}.</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"> registerGrant</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"> chainid</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"> community</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> grantManager</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">bytes32</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> grantId </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>id</span><span>,</span><span> chainid</span><span>,</span><span> community</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</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-keyword"> if</span><span> (</span><span>grantManager </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"> revert</span><span class="z-entity z-name"> InvalidGrantManager</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-support">bytes</span><span>(</span><span>community</span><span>)</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> InvalidCommunityNameLength</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-support">bytes</span><span>(</span><span>_grants</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>community</span><span>)</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> GrantAlreadyRegistered</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _grants</span><span>[</span><span>grantId</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Grant</span><span>(</span><span>id</span><span>,</span><span> chainid</span><span>,</span><span> community</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _participants</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>grantManager </span><span class="z-keyword">=</span><span> grantManager</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"> GrantRegistered</span><span>(</span><span>grantId</span><span>,</span><span> id</span><span>,</span><span> chainid</span><span>,</span><span> community</span><span>,</span><span> grantManager</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> grantId</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 {IGrantRegistry-transferOwnership}.</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"> transferOwnership</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> grantId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> newGrantManager</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-entity z-name"> _requireManager</span><span>(</span><span>grantId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>newGrantManager </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"> revert</span><span class="z-entity z-name"> InvalidGrantManager</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _participants</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>grantManager </span><span class="z-keyword">=</span><span> newGrantManager</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> OwnershipTransferred</span><span>(</span><span>grantId</span><span>,</span><span> newGrantManager</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 {IGrantRegistry-addGrantee}.</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"> addGrantee</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> grantee</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _requireManager</span><span>(</span><span>grantId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>grantee </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"> revert</span><span class="z-entity z-name"> InvalidGrantManager</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> success </span><span class="z-keyword">=</span><span> _participants</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>grantees</span><span>.</span><span class="z-entity z-name">add</span><span>(</span><span>grantee</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>success</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> GranteeAlreadyAdded</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> GranteeAdded</span><span>(</span><span>grantId</span><span>,</span><span> grantee</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 {IGrantRegistry-removeGrantee}.</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"> removeGrantee</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> grantee</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _requireManager</span><span>(</span><span>grantId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> success </span><span class="z-keyword">=</span><span> _participants</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>grantees</span><span>.</span><span class="z-entity z-name">remove</span><span>(</span><span>grantee</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>success</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> GranteeNotFound</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> GranteeRemoved</span><span>(</span><span>grantId</span><span>,</span><span> grantee</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 {IGrantRegistry-setStartDate}.</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"> setStartDate</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> startDate</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _requireManager</span><span>(</span><span>grantId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _milestones</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>startDate </span><span class="z-keyword">=</span><span> startDate</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> StartDateSet</span><span>(</span><span>grantId</span><span>,</span><span> startDate</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 {IGrantRegistry-addMilestoneDate}.</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"> addMilestoneDate</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> milestoneDate</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _requireManager</span><span>(</span><span>grantId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> success </span><span class="z-keyword">=</span><span> _milestones</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>milestonesDates</span><span>.</span><span class="z-entity z-name">add</span><span>(</span><span>milestoneDate</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>success</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> MilestoneDateAlreadyAdded</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> MilestoneDateAdded</span><span>(</span><span>grantId</span><span>,</span><span> milestoneDate</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 {IGrantRegistry-removeMilestoneDate}.</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"> removeMilestoneDate</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> grantId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> milestoneDate</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-entity z-name"> _requireManager</span><span>(</span><span>grantId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> success </span><span class="z-keyword">=</span><span> _milestones</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>milestonesDates</span><span>.</span><span class="z-entity z-name">remove</span><span>(</span><span>milestoneDate</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>success</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> MilestoneDateNotFound</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> MilestoneDateRemoved</span><span>(</span><span>grantId</span><span>,</span><span> milestoneDate</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 {IGrantRegistry-addDisbursement}.</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"> addDisbursement</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> grantId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> milestoneDate</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> fundingToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> fundingAmount</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-entity z-name"> _requireManager</span><span>(</span><span>grantId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _requireMilestoneDate</span><span>(</span><span>grantId</span><span>,</span><span> milestoneDate</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _milestones</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>disbursements</span><span>[</span><span>milestoneDate</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Disbursements</span><span>(</span></span> <span class="giallo-l"><span> fundingToken</span><span>,</span></span> <span class="giallo-l"><span> fundingAmount</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> false</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> DisbursementAdded</span><span>(</span><span>grantId</span><span>,</span><span> milestoneDate</span><span>,</span><span> fundingToken</span><span>,</span><span> fundingAmount</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 {IGrantRegistry-removeDisbursement}.</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"> removeDisbursement</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> milestoneDate</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _requireManager</span><span>(</span><span>grantId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _requireMilestoneDate</span><span>(</span><span>grantId</span><span>,</span><span> milestoneDate</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> _milestones</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>disbursements</span><span>[</span><span>milestoneDate</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> DisbursementRemoved</span><span>(</span><span>grantId</span><span>,</span><span> milestoneDate</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 {IGrantRegistry-setDisbursementStatus}.</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"> setDisbursementStatus</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> grantId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> milestoneDate</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> isDisbursed</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-entity z-name"> _requireManager</span><span>(</span><span>grantId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _requireMilestoneDate</span><span>(</span><span>grantId</span><span>,</span><span> milestoneDate</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _milestones</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>disbursements</span><span>[</span><span>milestoneDate</span><span>]</span><span>.</span><span>isDisbursed </span><span class="z-keyword">=</span><span> isDisbursed</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> DisbursementMade</span><span>(</span><span>grantId</span><span>,</span><span> milestoneDate</span><span>,</span><span> isDisbursed</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 {IGrantRegistry-addExternalLink}.</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"> addExternalLink</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> link</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _requireManager</span><span>(</span><span>grantId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-support">bytes</span><span>(</span><span>link</span><span>)</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> InvalidExternalLink</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _externalLinks</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>link</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ExternalLinkAdded</span><span>(</span><span>grantId</span><span>,</span><span> link</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 {IGrantRegistry-removeExternalLink}.</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"> removeExternalLink</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</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> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _requireManager</span><span>(</span><span>grantId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>index </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> _externalLinks</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>length</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> InvalidIndex</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> link </span><span class="z-keyword">=</span><span> _externalLinks</span><span>[</span><span>grantId</span><span>]</span><span>[</span><span>index</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> _externalLinks</span><span>[</span><span>grantId</span><span>]</span><span>[</span><span>index</span><span>]</span><span class="z-keyword"> =</span><span> _externalLinks</span><span>[</span><span>grantId</span><span>]</span><span>[</span></span> <span class="giallo-l"><span> _externalLinks</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>length </span><span class="z-keyword">-</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> ]</span><span>;</span></span> <span class="giallo-l"><span> _externalLinks</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span class="z-entity z-name">pop</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ExternalLinkRemoved</span><span>(</span><span>grantId</span><span>,</span><span> link</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"> Ensures that the caller is the grant manager for the given grantId.</span></span> <span class="giallo-l"><span class="z-comment"> * Reverts with `InvalidGrantManager` if the caller is not the grant manager.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> grantId</span><span class="z-comment"> The unique identifier of the grant being checked.</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"> _requireManager</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> view</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> _participants</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>grantManager</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> InvalidGrantManager</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"> Ensures that the milestone date is present in the grant.</span></span> <span class="giallo-l"><span class="z-comment"> * Reverts with `MilestoneDateNotFound` if the milestone date is not 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"> grantId</span><span class="z-comment"> The unique identifier of the grant being checked.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> milestoneDate</span><span class="z-comment"> The milestone date being checked.</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"> _requireMilestoneDate</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> grantId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> milestoneDate</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> view</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>_milestones</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>milestonesDates</span><span>.</span><span class="z-entity z-name">contains</span><span>(</span><span>milestoneDate</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> MilestoneDateNotFound</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"> See {IGrantRegistry-getGrant}.</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"> getGrant</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</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">Grant</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> _grants</span><span>[</span><span>grantId</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 {IGrantRegistry-getGrantManager}.</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"> getGrantManager</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantId</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> _participants</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>grantManager</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 {IGrantRegistry-getGrantees}.</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"> getGrantees</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> grantId</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">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-keyword"> return</span><span> _participants</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>grantees</span><span>.</span><span class="z-entity z-name">values</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"> See {IGrantRegistry-getMilestonesDates}.</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"> getMilestonesDates</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> grantId</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 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 class="z-keyword"> return</span><span> (</span></span> <span class="giallo-l"><span> _milestones</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>startDate</span><span>,</span></span> <span class="giallo-l"><span> _milestones</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>milestonesDates</span><span>.</span><span class="z-entity z-name">values</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-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 {IGrantRegistry-getDisbursement}.</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"> getDisbursement</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> grantId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> milestoneDate</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-storage z-type">Disbursements</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> _milestones</span><span>[</span><span>grantId</span><span>]</span><span>.</span><span>disbursements</span><span>[</span><span>milestoneDate</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 {IGrantRegistry-getExternalLinks}.</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"> getExternalLinks</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> grantId</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">string</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-keyword"> return</span><span> _externalLinks</span><span>[</span><span>grantId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Key considerations for this implementation:</p> <ol> <li> <p>Gas Optimization: <code>grantId</code> utilizes immutable identification fields to minimize large gas consumption. This ensures that essential information is used with keccak256 efficiently, while the mutable data can be submitted or modified later as the project evolves without affecting the identification method.</p> </li> <li> <p>Use of EnumerableSet: By leveraging EnumerableSet for managing participants and milestone dates, the contract allows for dynamic updates, such as team composition changes or new milestones. This approach offers flexibility without sacrificing the ability to efficiently track changes.</p> </li> </ol> <h2 id="security-considerations">Security Considerations</h2> <p>No security concerns 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-10-22T00:00:00+00:00 2026-02-11T14:48:25+00:00 Agustín Aguilarhttps://github.com/agusx1211 Michael Standenhttps://github.com/ScreamingHawk Peter Kieltykahttps://github.com/pkieltyka William Huahttps://github.com/attente Philippe Castonguayhttps://github.com/PhABC https://wg-eips.ritovision.com/7795/

Wallet Call API extension for transaction prerequisites for common token types

<h2 id="abstract">Abstract</h2> <p>This ERC extends <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> by defining capabilities that allow dApps to specify common token prerequisites for transactions, such as having certain <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> tokens. Wallets can then help users meet these requirements before executing the transactions.</p> <h2 id="motivation">Motivation</h2> <p>It is fairly common for dApps to reside only on one network, but this comes at the cost of shrinking the direct liquidity that these dApps can access. This happens because most users only have funds on a limited number of networks. As the number of networks grows, the likelihood of intersection between the networks chosen by the dApp and the user decreases.</p> <p>Given that dApps don't have a way of communicating with the wallet about their "final intent", they can only use transaction requests to communicate the last action that the user should take. However, it is up to the user to "guess" what prior actions need to be executed to fulfill the prerequisites of that final action.</p> <p>This guessing may involve consolidating funds into a single network or exchanging assets into another asset accepted by the dApp. This is a cumbersome process for the user and results in a highly degraded UX.</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 ERC extends <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> by adding new capabilities that can be used with the <code>wallet_sendCalls</code> and <code>wallet_getCapabilities</code> methods. These capabilities allow specifying different types of transaction requirements for common token standards that wallets can handle.</p> <p>DApps <strong>MAY</strong> opt out of using this feature if they wish to handle requirement fulfillment themselves.</p> <h3 id="erc-20-minimum-balance-capability">ERC-20 Minimum Balance Capability</h3> <p>A dApp can use the <code>erc20MinBalance</code> capability in a <code>wallet_sendCalls</code> request to request that a wallet ensure the owner has a minimum balance of a specified <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token.</p> <h4 id="wallet-getcapabilities-response"><code>wallet_getCapabilities</code> Response</h4> <p>Schema:</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"> Erc20MinBalanceCapability</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> supported</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> versions</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>Example:</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">0x1</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">erc20MinBalance</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">1.0</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><h4 id="wallet-sendcalls-request"><code>wallet_sendCalls</code> Request</h4> <p>Version 1.0 Schema:</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"> Erc20MinBalanceParams</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"> chainId</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex chain id</span></span> <span class="giallo-l"><span class="z-variable"> owner</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address</span></span> <span class="giallo-l"><span class="z-variable"> token</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address</span></span> <span class="giallo-l"><span class="z-variable"> minAmount</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex value</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p>This capability requests that the <code>owner</code> address <strong>MUST</strong> have a balance of at least <code>minAmount</code> of <code>token</code> on <code>chainId</code> before the transaction is executed.</p> <p>Example:</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">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">0xd46e8dd67c5d32be8058bb8eb970870f07244567</span><span class="z-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">0xd46e8dd67c5d32be8058bb8eb970870f07244567</span><span class="z-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">0x...</span><span class="z-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> }</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">erc20MinBalance</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">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">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">owner</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">token</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minAmount</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0f4240</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><h3 id="erc-20-minimum-allowance-capability">ERC-20 Minimum Allowance Capability</h3> <p>A dApp can use the <code>erc20MinAllowance</code> capability in a <code>wallet_sendCalls</code> request to request that a wallet ensure the owner has a minimum allowance of a specified <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token. Note this capability does not imply that the owner has a balance of the token, only that the allowance is equal to or greater than the specified amount.</p> <h4 id="wallet-getcapabilities-response-1"><code>wallet_getCapabilities</code> Response</h4> <p>Schema:</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"> Erc20MinAllowanceCapability</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> supported</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> versions</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>Example:</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">0x1</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">erc20MinAllowance</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">1.0</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><h4 id="wallet-sendcalls-request-1"><code>wallet_sendCalls</code> Request</h4> <p>Version 1.0 Schema:</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"> Erc20MinAllowanceParams</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"> chainId</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex chain id</span></span> <span class="giallo-l"><span class="z-variable"> owner</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address</span></span> <span class="giallo-l"><span class="z-variable"> operator</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address</span></span> <span class="giallo-l"><span class="z-variable"> token</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address</span></span> <span class="giallo-l"><span class="z-variable"> minAmount</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex value</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p>This capability requests that the <code>owner</code> address <strong>MUST</strong> have an allowance of at least <code>minAmount</code> of <code>token</code> for <code>operator</code> on <code>chainId</code> before the transaction is executed.</p> <p>Example:</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">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">0xd46e8dd67c5d32be8058bb8eb970870f07244567</span><span class="z-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">0xd46e8dd67c5d32be8058bb8eb970870f07244567</span><span class="z-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">0x...</span><span class="z-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> }</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">erc20MinAllowance</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">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">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">owner</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">token</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">operator</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">minAmount</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0f4240</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><h3 id="erc-721-ownership-capability">ERC-721 Ownership Capability</h3> <p>A dApp can use the <code>erc721Ownership</code> capability in a <code>wallet_sendCalls</code> request to request that a wallet ensure the owner has ownership of a specified <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> token.</p> <h4 id="wallet-getcapabilities-response-2"><code>wallet_getCapabilities</code> Response</h4> <p>Schema:</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"> Erc721OwnershipCapability</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> supported</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> versions</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>Example:</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">0x1</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">erc721Ownership</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">1.0</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><h4 id="wallet-sendcalls-request-2"><code>wallet_sendCalls</code> Request</h4> <p>Version 1.0 Schema:</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"> Erc721OwnershipParams</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"> chainId</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex chain id</span></span> <span class="giallo-l"><span class="z-variable"> owner</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address</span></span> <span class="giallo-l"><span class="z-variable"> token</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address</span></span> <span class="giallo-l"><span class="z-variable"> tokenId</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex value</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p>This capability requests that the <code>owner</code> address <strong>MUST</strong> have ownership of <code>tokenId</code> of <code>token</code> on <code>chainId</code> before the transaction is executed.</p> <p>Example:</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">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">0xd46e8dd67c5d32be8058bb8eb970870f07244567</span><span class="z-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">0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d</span><span class="z-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">0x...</span><span class="z-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> }</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">erc721Ownership</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">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">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">owner</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">token</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d</span><span class="z-punctuation z-definition z-string">&quot;</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x10</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><h3 id="erc-721-approval-capability">ERC-721 Approval Capability</h3> <p>A dApp can use the <code>erc721Approval</code> capability in a <code>wallet_sendCalls</code> request to request that a wallet ensure the owner has approved a specified <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> token. Note this capability does not imply that the owner has a balance of the token, only that the allowance is equal to or greater than the specified amount.</p> <h4 id="wallet-getcapabilities-response-3"><code>wallet_getCapabilities</code> Response</h4> <p>Schema:</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"> Erc721ApprovalCapability</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> supported</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> versions</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>Example:</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">0x1</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">erc721Approval</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">1.0</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><h4 id="wallet-sendcalls-request-3"><code>wallet_sendCalls</code> Request</h4> <p>Version 1.0 Schema:</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"> Erc721ApprovalParams</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"> chainId</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex chain id</span></span> <span class="giallo-l"><span class="z-variable"> owner</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address</span></span> <span class="giallo-l"><span class="z-variable"> operator</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address</span></span> <span class="giallo-l"><span class="z-variable"> token</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address</span></span> <span class="giallo-l"><span class="z-variable"> tokenId</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex value</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p>This capability requests that the <code>owner</code> address <strong>MUST</strong> have approved <code>operator</code> to transfer <code>tokenId</code> of <code>token</code> on <code>chainId</code> before the transaction is executed.</p> <p>Example:</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">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">0xd46e8dd67c5d32be8058bb8eb970870f07244567</span><span class="z-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">0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d</span><span class="z-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">0x...</span><span class="z-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> }</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">erc721Approval</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">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">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">owner</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">operator</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">token</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d</span><span class="z-punctuation z-definition z-string">&quot;</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x10</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><h3 id="erc-1155-minimum-balance-capability">ERC-1155 Minimum Balance Capability</h3> <p>A dApp can use the <code>erc1155MinBalance</code> capability in a <code>wallet_sendCalls</code> request to request that a wallet ensure the owner has a minimum balance of a specified <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> token.</p> <h4 id="wallet-getcapabilities-response-4"><code>wallet_getCapabilities</code> Response</h4> <p>Schema:</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"> Erc1155MinBalanceCapability</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> supported</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> versions</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>Example:</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">0x1</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">erc1155MinBalance</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">1.0</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><h4 id="wallet-sendcalls-request-4"><code>wallet_sendCalls</code> Request</h4> <p>Version 1.0 Schema:</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"> Erc1155MinBalanceParams</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"> chainId</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex chain id</span></span> <span class="giallo-l"><span class="z-variable"> owner</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address</span></span> <span class="giallo-l"><span class="z-variable"> token</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address</span></span> <span class="giallo-l"><span class="z-variable"> tokenId</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex value</span></span> <span class="giallo-l"><span class="z-variable"> minAmount</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex value</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p>This capability requests that the <code>owner</code> address <strong>MUST</strong> have a balance of at least <code>minAmount</code> of <code>tokenId</code> of <code>token</code> on <code>chainId</code> before the transaction is executed.</p> <p>Example:</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">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">0xd46e8dd67c5d32be8058bb8eb970870f07244567</span><span class="z-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">0x631998e91476da5b870d741192fc5cbc55f5a52e</span><span class="z-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">0x...</span><span class="z-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> }</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">erc1155MinBalance</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">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">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">owner</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">token</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x631998e91476da5b870d741192fc5cbc55f5a52e</span><span class="z-punctuation z-definition z-string">&quot;</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x10</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minAmount</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0f4240</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><h3 id="erc-1155-minimum-allowance-capability">ERC-1155 Minimum Allowance Capability</h3> <p>A dApp can use the <code>erc1155MinAllowance</code> capability in a <code>wallet_sendCalls</code> request to request that a wallet ensure the owner has a minimum allowance of a specified <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> token. Note this capability does not imply that the owner has a balance of the token, only that the allowance is equal to or greater than the specified amount.</p> <h4 id="wallet-getcapabilities-response-5"><code>wallet_getCapabilities</code> Response</h4> <p>Schema:</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"> Erc1155MinAllowanceCapability</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> supported</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> versions</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>Example:</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">0x1</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">erc1155MinAllowance</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">1.0</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><h4 id="wallet-sendcalls-request-5"><code>wallet_sendCalls</code> Request</h4> <p>Version 1.0 Schema:</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"> Erc1155MinAllowanceParams</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"> chainId</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex chain id</span></span> <span class="giallo-l"><span class="z-variable"> owner</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address</span></span> <span class="giallo-l"><span class="z-variable"> operator</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address</span></span> <span class="giallo-l"><span class="z-variable"> token</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Address</span></span> <span class="giallo-l"><span class="z-variable"> tokenId</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex value</span></span> <span class="giallo-l"><span class="z-variable"> minAmount</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex value</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p>This capability requests that the <code>owner</code> address <strong>MUST</strong> have an allowance of at least <code>minAmount</code> of <code>tokenId</code> of <code>token</code> for <code>operator</code> on <code>chainId</code> before the transaction is executed.</p> <p>Example:</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">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">0xd46e8dd67c5d32be8058bb8eb970870f07244567</span><span class="z-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">0x631998e91476da5b870d741192fc5cbc55f5a52e</span><span class="z-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">0x...</span><span class="z-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> }</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">erc1155MinAllowance</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">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">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">owner</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">operator</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">token</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x631998e91476da5b870d741192fc5cbc55f5a52e</span><span class="z-punctuation z-definition z-string">&quot;</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x10</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minAmount</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0f4240</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><h3 id="usage-examples">Usage Examples</h3> <p>This ERC serves as a foundational component for building user experiences that rely on cross-chain actions. It can be leveraged in various ways, depending on the combination of use cases and wallet implementations. Consider the following high-level examples.</p> <p>Not shown in the examples below are the <code>wallet_getCallsStatus</code> and <code>wallet_showCallsStatus</code> methods, which are used to query the status of a call bundle and display it to the user. The dApp <strong>MAY</strong> use these methods to provide a better user experience while waiting for the transactions to be fulfilled. More information can be found in the <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> specification.</p> <h4 id="marketplace-interaction-with-bridge-using-an-eoa-wallet">Marketplace Interaction with Bridge Using an EOA Wallet</h4> <p>A user wants to purchase <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens on <strong>Chain A</strong> but only has funds on <strong>Chain B</strong>. The user employs an Externally Owned Account (EOA) based wallet. The dApp requests an intended transaction using <code>wallet_sendCalls</code>, which includes the marketplace transaction alongside the requirement of owning funds on Chain A.</p> <p>In this scenario, the wallet <strong>MAY</strong> prompt the user to sign the necessary transactions to fulfill the requirements before proceeding with the main transaction. The wallet <strong>SHOULD</strong> compute possible solutions to meet the requirements and <strong>MUST</strong> ensure that these prerequisites are met prior to executing the main transaction.</p> <p><img src="https://wg-eips.ritovision.com/7795/./assets/eoa_example.svg" alt="EOA Example" /></p> <h4 id="bridge-swap-and-payment-using-a-smart-contract-wallet">Bridge, Swap, and Payment Using a Smart Contract Wallet</h4> <p>A dApp requests a payment from a user, which <strong>MUST</strong> be made in <strong>Token Z</strong> on <strong>Chain B</strong>, but the user holds <strong>Token Y</strong> on <strong>Chain A</strong>. The dApp requests an intended transaction using <code>wallet_sendCalls</code>, including the payment transaction alongside the requirement of having enough Token Z on Chain B.</p> <p>In this scenario, the Smart Contract Wallet <strong>MAY</strong> prompt the user to sign all the necessary transactions at once, executing them in the appropriate order. The wallet <strong>SHOULD</strong> compute solutions to fulfill the requirements and <strong>MUST</strong> ensure that all prerequisites are satisfied before proceeding with the main transaction.</p> <p>The signed transactions <strong>MAY</strong> be sent simultaneously to bundlers, who execute them as they become available, allowing the operation to complete even if the wallet disconnects.</p> <p><img src="https://wg-eips.ritovision.com/7795/./assets/sc_example.svg" alt="SC Example" /></p> <h2 id="rationale">Rationale</h2> <p>This ERC extends <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> rather than defining new RPC methods because:</p> <ol> <li><strong>Consistency</strong>: Leverages existing capability discovery mechanism</li> <li><strong>Composability</strong>: Requirements can be combined with other <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> capabilities</li> <li><strong>Flexibility</strong>: Wallets can implement only the requirements they support</li> <li><strong>Extensibility</strong>: New requirement types can be added as additional capabilities</li> </ol> <p>The decision to split requirements into individual capabilities rather than a single capability type allows:</p> <ol> <li>Granular support by wallets</li> <li>Clear capability discovery</li> <li>Independent versioning of requirement types</li> <li>Simpler implementation for basic wallets</li> </ol> <h2 id="security-considerations">Security Considerations</h2> <p>This ERC does not introduce any new security risks or trust assumptions.</p> <p>Users already trust their wallet provider to craft, manipulate and send transactions on their behalf. This ERC only adds a new field to the transaction request, which the wallet can use to make more informed decisions about transaction construction.</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-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status Gajinder Singhhttps://github.com/g11tech Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/7792/

Scheme to make the eth_getLogs response verifiable

<h2 id="abstract">Abstract</h2> <p>This EIP defines a method to make the <code>eth_getLogs</code> JSON-RPC response verifiable.</p> <h2 id="motivation">Motivation</h2> <p>The <code>eth_getLogs</code> endpoint is used by wallets to obtain the transaction history pertaining to an account or a topic. To verify correctness and completeness of the logs, a wallet would also have to obtain all block headers and check against their logs bloom. However, that mechanism is inefficient due to its high false positive rate and also involves an unpractical amount of network round trips. This EIP defines a replacement mechanism to efficiently and incrementally verify correctness and completeness of <code>eth_getLogs</code> responses.</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="configuration">Configuration</h3> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><code>LOG_CONTRACT_ADDRESS</code></td><td><code>0xfffffffffffffffffffffffffffffffffffffffe</code></td></tr> </tbody></table> <h3 id="log-accumulation">Log accumulation</h3> <p>After executing all transactions of a block, commitments of all emitted logs are accumulated into the storage of <code>LOG_CONTRACT_ADDRESS</code>. The contract has no code, and its storage layout consists of three slots of type <code>mapping</code>. However to prevent <a href="https://wg-eips.ritovision.com/158/">EIP-158</a> cleanup, the contract's nonce is set to <code>1</code> at the first write.</p> <p>| Name | Value | Type | | <code>LOG_ADDRESS_STORAGE_SLOT</code> | <code>0</code> | <code>mapping(address =&gt; bytes32)</code> | | <code>LOG_TOPICS_STORAGE_SLOT</code> | <code>1</code> | <code>mapping(bytes32 =&gt; bytes32)</code> | | <code>LOG_ADDRESS_TOPICS_STORAGE_SLOT</code> | <code>2</code> | <code>mapping(bytes32 =&gt; bytes32)</code> |</p> <p>Additional metadata about each log's origin is mixed in to each <code>LogEntry</code>. The definition uses the <code>Log</code> SSZ type as defined in <a href="https://wg-eips.ritovision.com/6466/">EIP-6466</a>.</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"> BlockMeta</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> timestamp</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> number</span><span>:</span><span> uint64</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"> LogMeta</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> block</span><span>:</span><span> BlockMeta</span></span> <span class="giallo-l"><span> transaction_index</span><span>:</span><span> uint64</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"> Log</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> address</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> topics</span><span>:</span><span> List</span><span>[</span><span>Bytes32</span><span>,</span><span class="z-constant"> MAX_TOPICS_PER_LOG</span><span>]</span></span> <span class="giallo-l"><span> data</span><span>:</span><span> ByteList</span><span>[</span><span class="z-constant">MAX_LOG_DATA_SIZE</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"> LogEntry</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> meta</span><span>:</span><span> LogMeta</span></span> <span class="giallo-l"><span> log</span><span>:</span><span> Log</span></span></code></pre> <p>The <code>hash_tree_root(LogEntry)</code> commitments are subsequently tracked as part of <code>LOG_CONTRACT_ADDRESS</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"> accumulate_log</span><span>(</span><span class="z-variable z-parameter z-function">evm</span><span>:</span><span> Evm</span><span>,</span><span class="z-variable z-parameter z-function"> entry_root</span><span>:</span><span> Bytes32</span><span>,</span><span class="z-variable z-parameter z-function"> key</span><span>:</span><span> Bytes32</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> root</span><span class="z-keyword"> =</span><span> hashlib</span><span>.</span><span>sha256</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> root</span><span>.</span><span>update</span><span>(</span><span>entry_root</span><span>)</span></span> <span class="giallo-l"><span> root</span><span>.</span><span>update</span><span>(</span><span>sload</span><span>(</span><span>evm</span><span>.</span><span>env</span><span>.</span><span>state</span><span>,</span><span class="z-constant"> LOG_CONTRACT_ADDRESS</span><span>,</span><span> key</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span>evm</span><span>.</span><span>env</span><span>.</span><span>state</span><span>,</span><span class="z-constant"> LOG_CONTRACT_ADDRESS</span><span>,</span><span> key</span><span>,</span><span> root</span><span>.</span><span>digest</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"> track_log</span><span>(</span><span class="z-variable z-parameter z-function">evm</span><span>:</span><span> Evm</span><span>,</span><span class="z-variable z-parameter z-function"> entry</span><span>:</span><span> LogEntry</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> entry_root</span><span class="z-keyword"> =</span><span> entry</span><span>.</span><span>hash_tree_root</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"> Allow verification via `address` filter</span></span> <span class="giallo-l"><span> key</span><span class="z-keyword"> =</span><span> keccak256</span><span>(</span><span>abi</span><span>.</span><span>encode</span><span>(</span><span>entry</span><span>.</span><span>log</span><span>.</span><span>address</span><span>,</span><span class="z-constant"> LOG_ADDRESS_STORAGE_SLOT</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> accumulate_log</span><span>(</span><span>evm</span><span>,</span><span> entry_root</span><span>,</span><span> key</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> topic</span><span class="z-keyword"> in</span><span> entry</span><span>.</span><span>log</span><span>.</span><span>topics</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Allow verification via `topics` filter</span></span> <span class="giallo-l"><span> key</span><span class="z-keyword"> =</span><span> keccak256</span><span>(</span><span>abi</span><span>.</span><span>encode</span><span>(</span><span>topic</span><span>,</span><span class="z-constant"> LOG_TOPICS_STORAGE_SLOT</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> accumulate_log</span><span>(</span><span>evm</span><span>,</span><span> entry_root</span><span>,</span><span> key</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"> Allow verification via combined `address` + `topics` filter</span></span> <span class="giallo-l"><span> key</span><span class="z-keyword"> =</span><span> keccak256</span><span>(</span><span>abi</span><span>.</span><span>encode</span><span>(</span><span>entry</span><span>.</span><span>log</span><span>.</span><span>address</span><span>,</span><span> topic</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> key</span><span class="z-keyword"> =</span><span> keccak256</span><span>(</span><span>abi</span><span>.</span><span>encode</span><span>(</span><span>key</span><span>,</span><span class="z-constant"> LOG_ADDRESS_TOPICS_STORAGE_SLOT</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> accumulate_log</span><span>(</span><span>evm</span><span>,</span><span> entry_root</span><span>,</span><span> key</span><span>)</span></span></code></pre><h3 id="json-rpc-api">JSON-RPC API</h3> <p>The <code>eth_getLogs</code> response format is extended to include:</p> <ul> <li><code>blockTimestamp</code>: <code>QUANTITY</code> - The timestamp field of the block referred to by <code>blockHash</code></li> </ul> <h3 id="verification">Verification</h3> <p>For <code>eth_getLogs(address, topics, fromBlock, toBlock)</code>, the response data can be verified for correctness and completion by obtaining:</p> <ol> <li><code>fromBlock</code> and <code>toBlock</code> block headers (validated against their known hashes)</li> <li><code>fromBlock</code>'s <code>parentBlock</code> header (validated against <code>fromBlock.parentHash</code>)</li> <li>Historical log accumulator at <code>parentBlock</code> based on given filters (validated with <code>eth_getProof</code>)</li> <li>Log accumulator at <code>toBlock</code> based on given filters (validated with <code>eth_getProof</code>)</li> </ol> <p>Starting from the historical log accumulator from (3), each response entry is applied to it in a way compatible with <code>accumulate_log</code> above. If the log accumulator ends up matching the value from (4), the response data is correct and <code>LogEntry</code> derived from it can be trusted.</p> <h2 id="rationale">Rationale</h2> <p>Making the <code>eth_getLogs</code> response verifiable adds the necessary security attributes to enable wallets to transition away from relying on trusted data providers, ultimately improving the wallet's privacy guarantees as it is no longer subject to the privacy policy of any given provider.</p> <h3 id="gas-cost">Gas cost</h3> <p>The gas cost produced by this scheme is significantly higher than what <code>LOG#</code> opcodes produce as of Prague, primarily due to the additional <code>SLOAD</code> / <code>SSTORE</code> and the double cost of <code>SHA256</code> opcodes compared to <code>KECCAK256</code> opcodes. The gas cost increases outweigh the savings from dropping logs blooms.</p> <p>If the mechanism turns out to be prohibitively expensive even when optimized, it may be necessary to move the log accumulators to a separate optimized data structure (not in <code>state_root</code>), or to an out-of-protocol zk system. Even then, the gas cost for logs should still reflect the actual overall cost to update a typical out-of-protocol accumulator to deter against log spamming.</p> <h3 id="block-number-transaction-index-in-meta-instead-of-hashes">Block number / transaction index in meta instead of hashes</h3> <p>As long as the accumulators are stored in the state trie, they cannot refer to the block hash as the block hash hashes over the state trie, producing a cyclic dependency. If an external system is used, hashes may be included as in that scenario the state root is not affected by the IVC.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>It is still possible to process <code>eth_getLogs</code> responses from trusted servers as is, without verifying them. Client applications with strict response validation may need to be updated to allow the additional <code>blockTimestamp</code> field.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This scheme reuses existing <code>eth_getProof</code> and SSZ Merkle proofs; it does not introduce new security risks.</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-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-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Guilherme Neveshttps://github.com/0xneves Rafael Castanedarafaelcastaneda@gmail.com https://wg-eips.ritovision.com/7787/

DAO governance where voting power is non-transferable and decays over time without active contributions.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces the Soulbound Degradable Governance (SDG) standard, where governance power should be granted as non-transferable tokens that decay over time unless renewed through participation. SDG enables young DAOs to implement merit-based governance by detaching governance power from economic power while on early stages of development.</p> <h2 id="motivation">Motivation</h2> <p>Traditional DAO governance models rely heavily on economic tokens, where voting power is proportional to token holdings. While effective for some use cases, this model risks concentrating power among wealthy members, leading to plutocracy and discouraging participation from smaller stakeholders. Furthermore, it fosters a treasury-centric culture that attracts contributors primarily focused on financial gain, rather than long-term governance or community well-being.</p> <p>Young DAOs, in particular, need governance models that incentivize active contributions without relying on economic power. This proposal addresses these issues by detaching governance power from economic power and ensuring political power decays if not maintained through ongoing participation. This approach creates a merit-based structure that reflects continuous involvement and reduces the risk of early-stage centralization or dependent on heavy inflationary policies.</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 system MUST operate with two distinct tokens types, one representing <strong>political power</strong> and another representing <strong>economic power</strong>:</p> <ol> <li> <p>The political power token SHOULD be non-transferable with over-time decayment.</p> </li> <li> <p>The economic power token supports liquidity and trade, providing the financial utility needed for the DAO’s operations and is RECOMMENDED to be a standard <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token.</p> </li> </ol> <p>The implementer of this standard MUST:</p> <ol> <li> <p>Override the <code>transfer(...)</code> function for the governance token to block transfers between addresses.</p> </li> <li> <p>Create a decay mechanism by overriding the <code>getVotes(...)</code> function on parent contract, reducing the token’s voting power over time. This is RECOMMENDED to be a linear or exponential decay formula.</p> </li> <li> <p>Create the respective <strong>Event</strong> emissions that track the voting power of addresses.</p> </li> </ol> <h3 id="contract-interface">Contract Interface:</h3> <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.20</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"> SDG</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"> Returns the grace period duration before the voting units begins decaying. This period is</span></span> <span class="giallo-l"><span class="z-comment"> * fixed to 90 days. But it can be overridden in derived contracts.</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"> duration of the grace period 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"> gracePeriod</span><span>(</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> <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 duration of the decay period during which the voting units decreases. This</span></span> <span class="giallo-l"><span class="z-comment"> * period is fixed to 90 days. But it can be overridden in derived contracts.</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"> duration of the decay period 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"> decayPeriod</span><span>(</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> <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"> Should be implemented by derived contracts to return the current voting units of an account.</span></span> <span class="giallo-l"><span class="z-comment"> * This function calculates the voting units based on the last time it was updated and decays it</span></span> <span class="giallo-l"><span class="z-comment"> * over 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"> account</span><span class="z-comment"> The address to check for voting units.</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"> current voting units of the account.</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"> getVotes</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-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>}</span></span> <span class="giallo-l"></span></code></pre><h2 id="rationale">Rationale</h2> <p>The SDG standard ensures flexibility by not being tied to any specific token type, allowing DAOs to implement it with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>, or other future token standards. This decision maximizes the compatibility and adaptability of the framework across different governance models.</p> <p>The choice to <strong>decouple governance power from economic power</strong> aims to provide a practical governance model for young DAOs seeking to prevent early centralization while fostering active participation. Non-transferable governance tokens ensure that only engaged members retain influence, as political power decays over time if not renewed through contributions.</p> <p>We deliberately avoided incorporating mechanisms like "Game Master mode" for early stages or fixed decayment strategy within the standard to keep the specification <strong>minimal and modular</strong>. These governance structures should be implemented by individual DAOs if needed, without burdening the core SDG standard with additional complexity. The goal is to provide DAOs with the essential tools to build sustainable, merit-based governance, while leaving room for experimentation and customization at the implementation level.</p> <p>The inclusion of <strong>grace periods</strong> and <strong>decay periods</strong> balances fairness with fluidity, incentivizing active participation while preventing governance stagnation. These mechanics ensure that governance power reflects recent contributions, phasing out inactive members naturally, and maintaining a dynamic, merit-based structure.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</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"> ^0.8.20</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">SDG</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./SDG.sol&quot;</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> SDG implementation</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">SOULERC721</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./ERC721/SOULERC721.sol&quot;</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Soulbounded ERC721 implementation</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">Ownable</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/access/Ownable.sol&quot;</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Oz Ownable contract</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"> Valocracy</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Implements the SDG governance model where governance power decays over time if not actively maintained.</span></span> <span class="giallo-l"><span class="z-comment"> * Only the DAO governance contract, as the owner, can mint new tokens or grant additional governance power.</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"> Valocracy</span><span class="z-storage"> is</span><span class="z-entity z-name"> SDG</span><span>, </span><span class="z-entity z-name">SOULERC721</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-comment"> Event emitted when voting units are updated</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> VotingUnitsUpdated</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 class="z-support">uint256</span><span class="z-variable"> oldVotingUnits</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> newVotingUnits</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Sequential ID and total supply of tokens</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-comment"> //</span><span class="z-comment"> Mapping of addresses to their token IDs</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> _tokens</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">@param</span><span class="z-variable z-other"> _name</span><span class="z-comment"> The name of the ERC721 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"> _symbol</span><span class="z-comment"> The symbols of the ERC721 token.</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 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 class="giallo-l"><span> )</span><span class="z-entity z-name"> Ownable</span><span>(</span><span class="z-entity z-name">_msgSender</span><span>(</span><span>)) </span><span class="z-entity z-name">SOULERC721</span><span>(</span><span>_name, _symbol) </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"> See {IERC721Metadata-tokenURI}.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> This function returns a static string as the token URI. In a real implementation, this</span></span> <span class="giallo-l"><span class="z-comment"> * function should return an URI that points to a JSON file with metadata about the token. Or even</span></span> <span class="giallo-l"><span class="z-comment"> * better, a dynamic SVG that displays the governance power of the token holder.</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"> tokenURI</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"> 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;Custom images or Dynamic NFT that displays the governance power&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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> See {ISDG-getVotes}.</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"> getVotes</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-storage z-type"> override</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> grantedTime </span><span class="z-keyword">=</span><span class="z-entity z-name"> _lastUpdateOf</span><span>(</span><span>account</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 no voting units was granted or still in grace period, return all voting units</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>grantedTime </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span class="z-keyword"> ||</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp </span><span class="z-keyword">&lt;</span><span> grantedTime </span><span class="z-keyword">+</span><span class="z-entity z-name"> gracePeriod</span><span>(</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> _votingUnitsOf</span><span>(</span><span>account</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"> Calculate time passed since grace period ended</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> timeSinceGracePeriod </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> (</span><span>grantedTime </span><span class="z-keyword">+</span><span class="z-entity z-name"> gracePeriod</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-comment"> If decay period is over, return 0</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>timeSinceGracePeriod </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-entity z-name"> decayPeriod</span><span>(</span><span>)</span><span>)</span><span> {</span></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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Linear decay: Calculate remaining voting units during decay period</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> decayPercentage </span><span class="z-keyword">=</span><span> (</span><span>timeSinceGracePeriod </span><span class="z-keyword">*</span><span class="z-constant"> 1e18</span><span>)</span><span class="z-keyword"> /</span><span class="z-entity z-name"> decayPeriod</span><span>(</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Percentage in 18 decimals</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> remainingVotes </span><span class="z-keyword">=</span><span> (</span><span class="z-entity z-name">_votingUnitsOf</span><span>(</span><span>account</span><span>)</span><span class="z-keyword"> *</span><span> (</span><span class="z-constant">1e18</span><span class="z-keyword"> -</span><span> decayPercentage</span><span>)</span><span>)</span><span class="z-keyword"> /</span><span class="z-constant"> 1e18</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> remainingVotes</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"> Grants voting units to the specified account by `amount`. Only the contract owner can</span></span> <span class="giallo-l"><span class="z-comment"> * mint new tokens and grant additional votings units. If the users doesn&#39;t have a token, one</span></span> <span class="giallo-l"><span class="z-comment"> * will be minted for them.</span></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 mint the new token or grant additional voting units.</span></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"> The amount of voting units to grant alongside 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"> grantVotingUnits</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"> 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 class="z-keyword"> if</span><span> (</span><span>_tokens</span><span>[</span><span>to</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-entity z-name"> _mint</span><span>(</span><span>to</span><span>,</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>totalSupply</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _tokens</span><span>[</span><span>to</span><span>]</span><span class="z-keyword"> =</span><span> totalSupply</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> votingUnits </span><span class="z-keyword">=</span><span class="z-entity z-name"> getVotes</span><span>(</span><span>to</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setVotingUnits</span><span>(</span><span>to</span><span>,</span><span> votingUnits </span><span class="z-keyword">+</span><span> amount</span><span>)</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"> VotingUnitsUpdated</span><span>(</span><span>to</span><span>,</span><span> votingUnits</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">@notice</span><span class="z-comment"> Burns an ERC721 token and erases the voting units associated with the token holder.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The token must exist and be burnable by the token holder or authorized entity.</span></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 ID of the token to burn.</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 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> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> from </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 class="giallo-l"><span class="z-support"> uint256</span><span> votingUnits </span><span class="z-keyword">=</span><span class="z-entity z-name"> getVotes</span><span>(</span><span>from</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _tokens</span><span>[</span><span>from</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setVotingUnits</span><span>(</span><span>from</span><span>,</span><span class="z-constant"> 0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _burn</span><span>(</span><span>tokenId</span><span>)</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"> VotingUnitsUpdated</span><span>(</span><span>from</span><span>,</span><span> votingUnits</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></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>No security concerns were found. <!-- 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-10-15T00:00:00+00:00 2026-02-11T14:49:28+00:00 Marc Harvey-Hillhttps://github.com/Marchhill https://wg-eips.ritovision.com/7788/

Target blob count changes dynamically to aim for constant blob costs

<h2 id="abstract">Abstract</h2> <p>This EIP proposes to make the target blob count adjust dynamically up to a safe maximum target. This adjustment will target a constant price in ETH for blobs, aiming for consistent costs of L2 transactions.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum currently uses a target of 50% capacity for blob count, with <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> smoothing out short-term spikes and pushing average throughput towards the target. A dynamic target is orthogonal to EIP-1559, tweaking the target itself over a longer timescale to aim for some desired blob cost.</p> <p>With static targeting the target may be higher than the actual demand, causing the protocol to undercharge for blobspace. This decreases the amount of fees burned, negatively affecting the price of ETH and total network security.</p> <p>As an example, consider what would happen if there was a large increase in max blob count due to DAS implementation but the target remained at 50%. It is unlikely that demand would immediately jump to anywhere near the target, and so for months or years the protocol would effectively charge nothing for L2 transactions. With a dynamic target, the target blob count would drop until the cost of blobspace for an L2 transaction approximated some affordable constant value. In this way, some fees are still burned by the protocol, but new L2s are not discouraged from using Ethereum blobspace, knowing that the target will increase in response to an increase in demand and blob fees will remain reasonably consistent.</p> <p>While the max blob count and max target are hard constraints based on resource utilisation limits, setting the target itself is far more subjective. A dynamic target can optimise for constant and affordable L2 transaction costs without requiring regular intervention by core developers to make tweaks based on changes in demand.</p> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <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>TARGET_BLOB_COUNT_CHANGE_RATE</code></td><td><code>1</code></td></tr> <tr><td><code>MIN_TARGET_BLOB_COUNT</code></td><td><code>1</code></td></tr> <tr><td><code>MAX_TARGET_BLOB_COUNT</code></td><td><code>3</code></td></tr> <tr><td><code>BLOB_COST_CHANGE_MARGIN</code></td><td><code>2^48</code></td></tr> <tr><td><code>TARGET_BLOB_COST</code></td><td><code>2^49</code></td></tr> </tbody></table> <h3 id="dynamic-targeting">Dynamic targeting</h3> <p>The target blob count changes each epoch based on the mean blob cost over the previous epoch. If the average cost exceeds the desired amount beyond some margin then the target is increased; likewise if it is below the desired amount by some margin the target will decrease. The target can increase up to <code>MAX_TARGET_BLOB_COUNT</code>, which is deemed to be a safe average throughput for the network, and down to a minimum of <code>MIN_TARGET_BLOB_COUNT</code>.</p> <p>Calculating targets:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>blob_cost_diff</span><span class="z-keyword"> =</span><span> mean_blob_cost</span><span class="z-keyword"> -</span><span class="z-constant"> TARGET_BLOB_COST</span></span> <span class="giallo-l"><span>target_change_direction</span><span class="z-keyword"> =</span><span class="z-keyword"> -</span><span class="z-constant">1</span><span class="z-keyword"> if</span><span> blob_cost_diff</span><span class="z-keyword"> &lt;</span><span class="z-keyword"> -</span><span class="z-constant">BLOB_COST_CHANGE_MARGIN</span><span class="z-keyword"> else</span><span> (</span><span class="z-constant">1</span><span class="z-keyword"> if</span><span> blob_cost_diff</span><span class="z-keyword"> &gt;</span><span class="z-constant"> BLOB_COST_CHANGE_MARGIN</span><span class="z-keyword"> else</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span>next_epoch_blob_count</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span class="z-support">min</span><span>(</span><span class="z-constant">MAX_TARGET_BLOB_COUNT</span><span>,</span><span> previous_epoch_blob_count</span><span class="z-keyword"> +</span><span> (</span><span>target_change_direction</span><span class="z-keyword"> *</span><span class="z-constant"> TARGET_BLOB_COUNT_CHANGE_RATE</span><span>)</span><span>)</span><span>,</span><span class="z-constant"> MIN_TARGET_BLOB_COUNT</span><span>)</span></span></code></pre><h3 id="engine-api-change">Engine API change</h3> <p>The Engine API is extended to provide the <code>mean_blob_cost</code> for the current epoch when the CL requests it from the EL. The CL requests this at the end of an epoch to set the target for the next epoch (depends on <a href="https://wg-eips.ritovision.com/7742/">EIP-7742</a>).</p> <h2 id="rationale">Rationale</h2> <h3 id="constant-blob-cost-target">Constant blob cost target</h3> <p>A constant blob cost target can keep L2 transaction costs affordable for end users. Volatility in the price of ETH would affect affordability, but is unlikely to be significant compared to normal fluctuations in blob gas costs due to spikes in activity. In future the costs could be adjusted in the case of changes in the order of magnitude of ETH price.</p> <p>An alternative approach would be to track a target blob cost in fiat. However, choosing a specific fiat currency is not credibly neutral, and introducing exchange rate oracles into the protocol could be an attack vector.</p> <p>Yet another alternative is to have validators vote on the target blob cost, but they may have conflicts of interest (for example if they operate a rollup) so again this is not credibly neutral.</p> <h3 id="target-block-gas">Target block gas</h3> <p>The same logic could be applied to the target block gas, but generally blockspace is in high demand so arguably gas costs are never too low. The target should be set to the maximum average throughput that the network can safely handle, a dynamic target is not necessary.</p> <h3 id="parameter-choices">Parameter choices</h3> <p><code>TARGET_BLOB_COST</code> is chosen so that the system targets affordable L2 transactions. Assuming that the theoretical compressed size of a simple transfer is 23 bytes, this gives a blobspace cost for L2 transactions of:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(23 / 125000) * TARGET_BLOB_COST ≈ 104 gWei</span></span></code></pre> <p>At today’s prices, $1 would cover blobspace for around 3700 simple transfers on L2. The blob cost target should be chosen with extensive community involvement. Note that this is the cost of blobspace for an L2 transaction; the total cost will be more due to rollup execution costs.</p> <p><code>TARGET_BLOB_COUNT_CHANGE_RATE</code> is chosen as a compromise between the system being reactive to changes in demand, and not having large jumps in average throughput. <code>BLOB_COST_CHANGE_MARGIN</code> is set such that target blob count will stay static when blob costs are within a range ±50% of <code>TARGET_BLOB_COST</code>.</p> <p><code>MAX_TARGET_BLOB_COUNT</code> is set to <code>3</code> to match the current static target. This value should be increased in future when it is deemed to be safe to increase average blob throughput.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>N/A</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> <!-- TODO --> <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-10-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Francisco Giordanohttps://github.com/frangio Hadrien Crouboishttps://github.com/Amxx Ernesto Garciahttps://github.com/ernestognw CJ Cobbhttps://github.com/cjcobb23 Sergey Gorbunovhttps://github.com/sergeynog joxeshttps://github.com/Joxess https://wg-eips.ritovision.com/7786/

An interface for contracts to send and receive cross-chain messages containing arbitrary data.

<h2 id="abstract">Abstract</h2> <p>This proposal describes an interface, and the corresponding workflow, for smart contracts to send arbitrary data through cross-chain messaging protocols. The end goal of this proposal is to have all such messaging protocols accessible via this interface (natively or using "adapters") to improve their composability and interoperability. That would allow a new class of cross-chain native smart contracts to emerge while reducing vendor lock-in. This proposal is modular by design, allowing users to leverage bridge-specific features through attributes (structured metadata) while providing simple "universal" access to the simple feature of "just getting a simple message through".</p> <h2 id="motivation">Motivation</h2> <p>Cross-chain messaging protocols (or bridges) allow communication between smart contracts deployed on different blockchains. There is a large diversity of such protocols with multiple degrees of decentralization, different architectures, implementing different interfaces, and providing different guarantees to users.</p> <p>Because almost every protocol implements a different workflow using a specific interface, portability between bridges is currently basically impossible. This also prevents the development of generic contracts that rely on cross chain communication.</p> <p>The objective of this ERC is to provide a standard interface, and a corresponding workflow, for performing cross-chain communication between contracts. Existing cross-chain communication protocols that do not natively implement this interface should be able to adopt it using adapter gateway contracts.</p> <p>Compared to previous ERCs in this area, this ERC offers compatibility with chains outside of the Ethereum/EVM ecosystem, and it is extensible to support the different feature sets of various protocols while offering a shared core of standard functionality.</p> <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="message-field-encoding">Message Field Encoding</h3> <p>A cross-chain message consists of a sender, recipient, payload, value (native token), and list of attributes.</p> <h4 id="sender-and-recipient">Sender and Recipient</h4> <p>The sender account (in the source chain) and recipient account (in the destination chain) MUST be input in an Interoperable Address binary format, specified in <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a>, which MUST be serialized according to CAIP-350. The recipient field MAY be omitted or zeroed (contain an Interoperable Address with all fields set to zero) to indicate an unspecified destination, such as when a broadcast mode is employed and the final recipients are determined by the protocol itself.</p> <h4 id="payload">Payload</h4> <p>The payload is an opaque <code>bytes</code> value.</p> <h4 id="attributes">Attributes</h4> <p>An attribute is a key-value pair, where the key determines the type and encoding of the value, as well as its meaning and behavior in the gateway.</p> <p>The set of valid attributes is extensible. It is RECOMMENDED to standardize them and their characteristics by publishing them as ERCs. A gateway MAY support any set of standard or custom attributes.</p> <p>An attribute key is a 4-byte value (<code>bytes4</code>). It is RECOMMENDED to define a key as the function selector for a function signature according to Solidity ABI (for example, <code>minGasLimit(uint256)</code> resulting in the key <code>39f87ba1</code>), so as to give the key a human-readable name and a standard value encoding corresponding to the ABI-encoding of the function arguments.</p> <p>An attribute value is byte array (<code>bytes</code>).</p> <p>The list of attributes MUST be encoded as <code>bytes[]</code> (an array of <code>bytes</code>) where each element is the concatenation of a key and a value. (Note that in the case of keys defined as Solidity function selectors, each element of the array can be encoded by <code>abi.encodeWithSignature</code>.)</p> <p>A message with no attributes (an empty attributes list) MUST be considered a valid message.</p> <h3 id="sending-procedure">Sending Procedure</h3> <p>A <strong>Source Gateway</strong> is a contract that offers a protocol to send a message to a recipient on another chain. It MUST implement <code>IERC7786GatewaySource</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"> IERC7786GatewaySource</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MessageSent</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"> sendId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> sender</span><span>, </span><span>// </span><span class="z-variable">Binary</span><span class="z-variable"> Interoperable</span><span class="z-variable"> Address</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> recipient</span><span>, </span><span>// </span><span class="z-variable">Binary</span><span class="z-variable"> Interoperable</span><span class="z-variable"> Address</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> payload</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>[</span><span>]</span><span class="z-variable"> attributes</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"> error</span><span class="z-entity z-name"> UnsupportedAttribute</span><span>(</span><span class="z-support">bytes4</span><span> selector</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"> supportsAttribute</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> selector</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"> function</span><span class="z-entity z-name"> sendMessage</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"> recipient</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Binary Interoperable Address</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> payload</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> attributes</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 class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> sendId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="supportsattribute"><code>supportsAttribute</code></h4> <p>Returns a boolean indicating whether an attribute (identified by its key) is supported by the gateway.</p> <p>A gateway MAY be upgraded with support for additional attributes. Once present support for an attribute SHOULD NOT be removed to preserve backwards compatibility with users of the gateway.</p> <h4 id="sendmessage"><code>sendMessage</code></h4> <p>Initiates the sending of a message.</p> <p>Further action MAY be required by the gateway to make the sending of the message effective, such as providing payment for gas. See Post-processing.</p> <p>MUST revert with <code>UnsupportedAttribute</code> if an unsupported attribute is included. MAY revert if an attribute value is not valid for the key.</p> <p>MAY accept call value (native token) to be sent with the message. MUST revert if call value is included but it is not a feature supported by the gateway. It is unspecified how this value is represented on the destination.</p> <p>MAY generate and return a unique non-zero <em>send identifier</em>, otherwise returning zero. This identifier can be used to track the lifecycle of the message in the source gateway in events and for post-processing. <em>Note that this identifier MAY be different from the <code>receiveId</code> that is delivered to the recipient, since that identifier may preferably consist of values like transaction id and log index that are not available in the execution environment.</em></p> <p>MUST emit a <code>MessageSent</code> event, including the optional send identifier that is returned by the function.</p> <h4 id="messagesent"><code>MessageSent</code></h4> <p>This event signals that a would-be sender has requested a message to be sent.</p> <p>If <code>sendId</code> is present, post-processing MAY be required to send the message through the cross-chain channel.</p> <h4 id="post-processing">Post-processing</h4> <p>After a sender has invoked <code>sendMessage</code>, further action MAY be required by the gateways to make the message effective. This is called <em>post-processing</em>. For example, some payment is typically required to cover the gas of executing the message at the destination.</p> <p>The exact interface for any such action is out of scope of this ERC.</p> <h3 id="reception-procedure">Reception Procedure</h3> <p>A <strong>Destination Gateway</strong> is a contract that implements a protocol to validate messages sent on other chains. The interface of the destination gateway and how it is invoked is out of scope of this ERC.</p> <p>The protocol MUST ensure delivery of a sent message to its <strong>recipient</strong> using the <code>IERC7786Recipient</code> interface (specified below), which the recipient MUST implement.</p> <p>Once the message can be safely delivered (see Properties), the gateway MUST invoke <code>receiveMessage</code> with the message identifier and contents, unless the sender or the recipient explicitly requested otherwise.</p> <p>The <code>receiveId</code> MUST be either empty or unique (for the calling gateway) to the message being relayed. The format of this identifier is not specified, and the gateway can use it at its own discretion. For example it can be an identifier of the <code>MessagePosted</code> event that created the message.</p> <p>The gateway MUST verify that <code>receiveMessage</code> returns the correct value, and MUST revert otherwise.</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"> IERC7786Recipient</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> receiveMessage</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> receiveId</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Unique identifier</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> sender</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Binary Interoperable Address</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> payload</span><span>,</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 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><h4 id="receivemessage"><code>receiveMessage</code></h4> <p>Delivery of a message sent from another chain.</p> <p>The recipient MUST validate that the caller of this function is a <strong>known gateway</strong>, i.e., one whose underlying cross-chain messaging protocol it trusts.</p> <p>MUST return <code>IERC7786Recipient.receiveMessage.selector</code> (<code>0x2432ef26</code>).</p> <h4 id="interaction-diagram">Interaction Diagram</h4> <p><img src="https://wg-eips.ritovision.com/7786/./assets/send-execute.png" alt="" /></p> <h3 id="properties">Properties</h3> <p>The protocol underlying a pair of gateways is expected to guarantee a series of properties. For a detailed definition and discussion, we refer to XChain Research’s <em>Cross-chain Interoperability Report</em>.</p> <ul> <li>The protocol MUST guarantee Safety: A message is delivered at the destination if and only if it was sent at the source. The delivery process must ensure a message is only delivered once the sending transaction is finalized, and not delivered more than once. Note that there can be multiple messages with identical parameters that must be delivered separately.</li> <li>The protocol MUST guarantee Liveness: A sent message is eventually delivered to the destination, assuming Liveness and censorship-resistance of the source and destination chains and that any protocol costs are paid.</li> <li>The protocol SHOULD guarantee Timeliness: A sent message is delivered at the destination within a bounded delivery time, which should be documented.</li> <li>The above properties SHOULD NOT rely on trust in some centralized actor. For example, safety should be guaranteed by some trustless mechanism such as a light client proof or attestations by an open, decentralized validator set. Relaying should be decentralized or permissionless to ensure liveness; a centralized relayer can fail and thus halt the protocol.</li> </ul> <h2 id="rationale">Rationale</h2> <p>Attributes are designed so that gateways can expose any specific features the bridge offers without having to use a proprietary interface. This should allow contracts to change the gateway they use while continuing to express messages the same way. This portability offers many advantages:</p> <ul> <li>A contract that relies on a specific gateway for sending messages is vulnerable to the gateway being paused, deprecated, or simply breaking. If the communication between the contract and the gateway is standard, an admin of the contract could update the address (in storage) of the gateway to use. In particular, senders to update to the new gateway when a new version is available.</li> <li>Bridge layering is made easier. In particular, this interface should allow for gateways that route the message through multiple independent bridges. Delivery of the message could require one or multiple of these independent bridges depending on whether improved liveness or safety is desired.</li> </ul> <p>As some cross-chain communication protocols require additional parameters beyond the destination and the payload, and because we want to send messages through those bridges without any knowledge of these additional parameters, a post-processing of the message MAY be required (after <code>sendMessage</code> is called, and before the message is delivered). The additional parameters MAY be supported through attributes, which would remove the need for a post-processing step. If these additional parameters are not provided through attributes, an additional call to the gateway is REQUIRED for the message to be sent. If possible, the gateway SHOULD be designed so that anyone with an incentive for the message to be delivered can jump in. A malicious actor providing invalid parameters SHOULD NOT prevent the message from being successfully relayed by someone else.</p> <p>Some protocols gateway support doing arbitrary direct calls on the recipient. In that case, the recipient must detect that they are being called by the gateway to properly identify cross-chain messages. Getters are available on the gateway to figure out where the cross-chain message comes from (source chain and sender address). This approach has the downside that it allows anyone to trigger any call from the gateway to any contract. This is dangerous if the gateway ever holds any assets (<a href="https://wg-eips.ritovision.com/20/">ERC-20</a> or similar). The use of a dedicated <code>receiveMessage</code> function on the recipient protects any assets or permissions held by the gateway against such attacks. If the ability to perform direct calls is desired, this can be implemented as a wrapper on top of any gateway that implements this ERC.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Existing cross-chain messaging protocols implement proprietary interfaces. We recommend that protocols natively implement the standard interface defined here, and propose the development of standard adapters for those that don't.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="handling-addresses">Handling addresses</h3> <p>Interoperable Addresses (ERC‑7930) rely on CAIP‑350 serialization. Using non‑canonical encodings can lead to silent delivery failures. Gateways SHOULD reject non‑canonical encodings and MAY normalize them before emission.</p> <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-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Francisco Giordanohttps://github.com/frangio https://wg-eips.ritovision.com/7803/

Improvements for EIP-712 to support smart contract accounts.

<h2 id="abstract">Abstract</h2> <p>This ERC improves on <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> signatures to better support smart contract accounts by 1) introducing signing domains as a way to prevent replay attacks when private keys are shared across accounts, and 2) allowing dapps and wallets to coordinate on the method that will be used to authenticate the signature.</p> <h2 id="motivation">Motivation</h2> <h3 id="signing-domains">Signing Domains</h3> <p>Standards like <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> and <a href="https://wg-eips.ritovision.com/6492/">ERC-6492</a> give smart contract accounts (SCAs) the ability to produce signatures that an application can authenticate without knowledge of the abstract rules of the account. This is an important primitive for applications, as the account owner is able to authorize a third-party to act on its behalf without interacting with the chain.</p> <p>Smart contract accounts may be "owned" by cryptographic keys whose signatures are used to authorize the use of the account. There is not necessarily a one-to-one mapping between keys and accounts, because a single key may control multiple accounts, so care must be taken to prevent replay attacks across them. This is done by binding a signature to a particular account.</p> <p>EIP-712 introduced a scheme where signatures can be bound to a verifying domain, which corresponds to the protocol contract that will authenticate a signature. Reusing this mechanism to additionally bind a signature to the domain of the smart contract account runs into a large amount of complexity and attack surface (see <a href="https://wg-eips.ritovision.com/7739/">ERC-7739</a>), as well as yet unresolved issues with account composability (SCAs that control other SCAs). This ERC introduces <em>signing domains</em> in addition to verifying domains to natively enable wallets to generate smart contract account signatures with replay protection.</p> <h3 id="authentication-methods">Authentication Methods</h3> <p>ERC-1271 is a minimal and very general interface that has been very effective. It requires the contract code to be already deployed by the time the signature needs to be authenticated, so ERC-6492 extends ERC-1271 to support that use case. In the future additional methods may need to be developed.</p> <p>Support for these methods across protocols is currently lacking and is a major pain point for the Account Abstraction roadmap. Where ERC-1271 is supported, it is not necessarily used uniformly, in particular some contracts attempt <code>ECRECOVER</code> prior to invoking <code>isValidSignature</code> while others do the opposite, which will result in very different semantics post <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>.</p> <p>This ERC addresses this by allowing dapps to communicate the types of signatures a protocol's contracts support, i.e., which authentication methods will be used, and in what order.</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>Requests for typed data signatures via JSON-RPC (<code>eth_signTypedData</code>) or client libraries are extended with the following optional properties:</p> <ul> <li><code>signingDomains</code></li> <li><code>authMethods</code></li> </ul> <p>These new properties are used alongside the existing ones, i.e., <code>types</code>, <code>primaryType</code>, <code>domain</code>, and <code>message</code>.</p> <p>The signature returned in response to the request MAY be of any size, and in the absence of <code>authMethods</code> it MUST be treated opaquely as the type of the signature is not known.</p> <h3 id="signingdomains"><code>signingDomains</code></h3> <p>This property is an array of smart contract account domains. Each member of the array is an object with the following keys:</p> <ul> <li><code>types</code>: An object with the same format as EIP-712 <code>types</code> with at least an <code>EIP712Domain</code> key.</li> <li><code>domain</code>: An object that is valid with respect to the type <code>EIP712Domain</code> described in <code>types</code>.</li> </ul> <p>From right to left the array lists the chain of accounts through which the signer ultimately has control over the "outermost" signing domain (i.e., that listed first).</p> <p>For example:</p> <ol> <li>A dapp requests an EIP-712 signature to a connected account via JSON-RPC. <code>signingDomains</code> is empty or undefined.</li> <li>The connected account is a multisig, so it requests EIP-712 signatures from its signers, prepending the domain of the multisig to <code>signingDomains</code>, which is now an array of length 1.</li> <li>One of the signers uses a smart contract account controlled by an ECDSA key held in a hardware wallet, so their wallet requests an EIP-712 signature from the hardware wallet, prepending the domain of the smart contract account to <code>signingDomains</code>, which is now an array of length 2.</li> <li>The signer verifies the contents of the signature in their hardware wallet. They are able to see that they are signing a message intended for a particular dapp domain, on behalf of their smart contract account (closest signing domain), as a member of the multisig (furthest signing domain).</li> </ol> <h4 id="encoding-of-data-to-be-signed">Encoding of data to be signed</h4> <p>In the presence of <code>signingDomains</code> the account should encode the message to be signed according to the following recursive procedure:</p> <ul> <li><code>encodeForSigningDomains(signingDomainSeparators : [𝔹²⁵⁶], verifyingDomainSeparator : 𝔹²⁵⁶, message : 𝕊) =</code> <ul> <li>If <code>signingDomainSeparators = [first, ...others]</code>: <code>"\x19\x02" ‖ first ‖ encodeForSigningDomains(others, verifyingDomainSeparator, message)</code></li> <li>If <code>signingDomainSeparators = []</code>: <code>encode(domainSeparator, message)</code>, where <code>encode</code> is defined by EIP-712.</li> </ul> </li> </ul> <p><code>signingDomainSeparators</code> is the array of hashes of the domains included in <code>signingDomains</code>, in the same order, computed according to EIP-712's <code>hashStruct</code>.</p> <h3 id="authmethods"><code>authMethods</code></h3> <p>This property is an array of supported signature authentication methods, listed in the order that the verifying domain tries them.</p> <p>Each member of the array is an object with the following keys:</p> <ul> <li><code>id</code>: An string that identifies the method. It may be one of: <ul> <li><code>ECDSA</code>: ECDSA signatures by Externally Owned Accounts.</li> <li><code>ERC-{n}</code>: A standard type of signature specified by an ERC. <code>n</code> must not be padded with zeros.</li> </ul> </li> <li><code>parameters</code> (optional): An array of method-specific parameters.</li> </ul> <h3 id="json-schema">JSON Schema</h3> <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"> types</span><span>:</span><span> {</span><span class="z-entity z-name">$ref</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">#/$defs/EIP712Types</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"> domain</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"> message</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"> signingDomains</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 class="z-entity z-name">$ref</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">#/$defs/EIP712Types</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-entity z-name"> authMethods</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"> id</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"> parameters</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">array</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"> required</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">id</span><span class="z-punctuation z-definition z-string">&#39;</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><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">types</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">domain</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">message</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"> $defs</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> EIP712Types</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"> EIP712Domain</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">array</span><span class="z-punctuation z-definition z-string">&#39;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</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></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">EIP712Domain</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></code></pre><h2 id="rationale">Rationale</h2> <!-- TODO --> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <!-- TODO --> <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-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-05T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ben Adamshttps://github.com/benaadams Dankrad Feisthttps://github.com/dankrad Maria Inês Silvahttps://github.com/misilva73 Paul Harrishttps://github.com/rolfyone https://wg-eips.ritovision.com/7782/

Reduce Ethereum's slot time from 12s to 6s to decrease latency by 50%, distribute bandwidth usage, and improve UX.

<h2 id="abstract">Abstract</h2> <p>Reduce Ethereum's slot time from 12 s to 6 s, halving on‑chain latency and epoch duration. This doubles slot throughput while keeping block and blob sizes unchanged, smoothing bandwidth usage. The change delivers better user experience, faster Layer 2 interaction, tighter DEX pricing, reduced MEV, and quicker finality.</p> <h2 id="motivation">Motivation</h2> <ul> <li><strong>Protocol Carrying Capacity</strong> It is impractical to increase block sizes beyond 10MiB without substantial networking changes. However it is practical to decrease slot time to achieve similar effect while also improving the UX at same time.</li> <li><strong>Enhanced UX</strong>: Confirmations now arrive in ~6 s instead of 12 s.</li> <li><strong>Faster Finality</strong>: Epochs shrink from 384 s (32 × 12 s) to 192 s (32 × 6 s), accelerating Casper‑FFG finality.</li> <li><strong>L2 Interoperability</strong>: Layer 2 rollups see half the settlement delay on L1, improving throughput and reducing reorg risk period.</li> <li><strong>Based rollups</strong>: Based rollup sequencing is tied to L1 block time so faster blocks directly improves based rollups.</li> <li><strong>DEX Economics</strong>: More frequent blocks decrease LVR (Loss Versus Rebalancing), which improves the economics for liquidity providers. More liquidity means lower spreads (reduced slippage).</li> <li><strong>Bandwidth Smoothing</strong>: Doubling slot rate distributes bandwidth evenly without increasing peak block size; nodes with modest capacity remain supported.</li> </ul> <h2 id="specification">Specification</h2> <p>On the consensus layer, a new parameter is added to the configuration:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>SLOT_SCHEDULE:</span></span> <span class="giallo-l"><span> - EPOCH: 348618</span></span> <span class="giallo-l"><span> SECONDS_PER_SLOT: 12</span></span> <span class="giallo-l"><span> - EPOCH: 355368</span></span> <span class="giallo-l"><span> SECONDS_PER_SLOT: 6</span></span></code></pre> <p>The parameters and schedules above are purely illustrative. Actual values and schedules are beyond the scope of this specification.</p> <h3 id="adjustment-to-gas-and-blob-limits">Adjustment to gas and blob limits</h3> <p>The first execution block after the fork needs to specify half the previous gas limit. With this fork, all gas limit settings are reinterpreted as "gas per 12 seconds". I.e., if the user configuration or otherwise default gas limit vote was 36,000,000, the client should now vote for 18,000,000. All values are rounded down to integers.</p> <p>The blob target and limit are also halved, rounded down to the nearest integer.</p> <h3 id="attestation-deadlines">Attestation deadlines</h3> <p>All clients need to be reconfigured so that deadlines can be configured in milliseconds for finer granularity. Currently the slot is split into three equal intervals, with proposal happening at time 0, and attestations and aggregations being sent at one thirds and two thirds of the slot time. We change this to a new uneven schedule, in order to give sufficient time for block propagation, which takes the most time:</p> <ul> <li>Block proposal at 0 ms</li> <li>Attestations at 3000 ms</li> <li>Aggregates at 4500 ms</li> </ul> <h2 id="rationale">Rationale</h2> <p>This proposal balances user experience, economic efficiency, and network stability:</p> <ul> <li> <p>UX &amp; Finality: Halving slot time directly reduces confirmation latency and halves epoch duration, delivering faster feedback to users and speeding up Casper-FFG finality.</p> </li> <li> <p>Economic Efficiency: Increased block frequency tightens DEX price spreads, lowers slippage, and diminishes arbitrage and MEV opportunities, improving on-chain trading conditions.</p> </li> <li> <p>L2 &amp; Based Rollups Synergy: Layer 2 rollups, especially based rollups, benefit from reduced L1 settlement delays, enhancing throughput and user-perceived performance in rollup ecosystems.</p> </li> <li> <p>Network Stability: Maintaining existing p2p network maximum smooths bandwidth usage over time, avoiding peak-load spikes and preserving accessibility for nodes with diverse bandwidth capacities.</p> </li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backwards compatibility concerns.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li> <p><strong>Network Congestion</strong>:</p> <ul> <li><strong>Increased Message Frequency</strong>: The network must handle more frequent messages without congestion.</li> <li><strong>Mitigation</strong>: Implement network optimizations and encourage the use of efficient client software.</li> </ul> </li> <li> <p><strong>Consensus Integrity</strong>:</p> <ul> <li><strong>Fork Choice Stability</strong>: Ensure that the fork choice rule remains robust against potential reorganization attacks.</li> <li><strong>Finality Gadgets</strong>: Confirm that finality mechanisms function correctly under new timing conditions.</li> </ul> </li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via CC0 1.0 Universal.</p> 2024-10-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 David Kimhttps://github.com/PowerStream3604 Richard Meissnerhttps://github.com/rmeissner Akshay Patelhttps://github.com/akshay-ap Joshua Kimhttps://github.com/LightningHun Fangtinghttps://github.com/trinity-0111 Yoav Weisshttps://github.com/yoavw https://wg-eips.ritovision.com/7779/

Interface for delegated externally owned accounts to enable better redelegation between wallets.

<h2 id="abstract">Abstract</h2> <p>This proposal outlines the interfaces to make delegated EOAs interoperable after the merge of <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>. With <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>, EOAs will be able to enable execution abstraction, which leads to a more feature-rich account, including gas sponsorship, batch execution, and more.</p> <p>However, there is a need to help facilitate storage management for redelegation, as invalid management of storage may incur storage collisions that can lead to unexpected behavior of accounts (e.g., account getting locked, security vulnerabilities, etc)</p> <p>The interface <code>InteroperableDelegatedAccount</code> suggests the interfaces for delegated EOAs to be interoperable and facilitate a better environment for redelegation.</p> <h2 id="motivation">Motivation</h2> <p>After the merge of <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>, it is expected that a considerable number of EOA wallets will migrate from pure EOA accounts to delegated EOA accounts.</p> <p>This is to enable a more appealing wallet UX, including a 1-step swap, automated subscription, gas sponsorship, and more.</p> <p>However, considering the fact that delegated EOAs will utilize its own storage bound to their Smart Account implementation, the storage management is essential to foster migration between wallets to better ensure sovereignty of users to freely migrate their wallet app whenever they want.</p> <p>EOA (Externally Owned Account) is currently comprised of cryptographic key pair that is mostly managed in the form of mnemonic phrase.</p> <p>This simplicity provided frictionless interoperability between wallets that gave users the freedom to freely migrate between different wallet applications.</p> <p>However, after the merge of <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>, each EOA will be given the ability to delegate itself to a smart account which will impact migration as storage remains in the continuous context while EOA can be delegated to diverse smart accounts if the user migrates their wallet.</p> <p>Account Abstraction Wallets, given the wallet-specific validation and execution logic, also have the interoperability issue to be considered but its importance in EOA is much more significant as EOA users are already familiar with wallet migration and its a common action to migrate wallets.</p> <p>This spec provides a standard approach for fetching the storage base used in the delegated account together with an optional mechanism to clean up the storage.</p> <p>Moreover, it is worth noting that this spec is not limited to <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> based smart accounts but smart accounts and smart contracts in general that uses a custom storage slot.</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> <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"> IInteroperableDelegatedAccount</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"> * @dev Provides the namespace of the account.</span></span> <span class="giallo-l"><span class="z-comment"> * namespace of accounts can possibly include, account version, account name, wallet vendor name, etc</span></span> <span class="giallo-l"><span class="z-comment"> * @notice this standard does not standardize the namespace format</span></span> <span class="giallo-l"><span class="z-comment"> * e.g., &quot;v0.1.2.7702Account.WalletProjectA&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"> accountId</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> <span class="giallo-l"><span class="z-comment"> /*</span></span> <span class="giallo-l"><span class="z-comment"> * @dev Externally shares the storage bases that has been used throughout the account.</span></span> <span class="giallo-l"><span class="z-comment"> * Majority of 7702 accounts will have their distinctive storage base to reduce the chance of storage collision.</span></span> <span class="giallo-l"><span class="z-comment"> * This allows the external entities to know what the storage base is of the account.</span></span> <span class="giallo-l"><span class="z-comment"> * Wallets willing to redelegate already-delegated accounts should call accountStorageBase() to check if it confirms with the account it plans to redelegate.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * The bytes32 array should be stored at the storage slot: keccak(keccak(&#39;InteroperableDelegatedAccount.ERC.Storage&#39;)-1) &amp; ~0xff</span></span> <span class="giallo-l"><span class="z-comment"> * This is an append-only array so newly redelegated accounts should not overwrite the storage at this slot, but just append their base to the array.</span></span> <span class="giallo-l"><span class="z-comment"> * This append operation should be done during the initialization of the account.</span></span> <span class="giallo-l"><span class="z-comment"> * This array should return a value of keccak hash unless using external storage.</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"> accountStorageBases</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>}</span></span></code></pre><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"> IRedelegableDelegatedAccount</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"> * @dev Function called before redelegation.</span></span> <span class="giallo-l"><span class="z-comment"> * This function should prepare the account for a delegation to a different implementation.</span></span> <span class="giallo-l"><span class="z-comment"> * This function could be triggered by the new wallet that wants to redelegate an already delegated EOA.</span></span> <span class="giallo-l"><span class="z-comment"> * It should uninitialize storages if needed and execute wallet-specific logic to prepare for redelegation.</span></span> <span class="giallo-l"><span class="z-comment"> * msg.sender should be the owner of the account.</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"> onRedelegation</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 class="giallo-l"><span>}</span></span></code></pre> <p>Accounts MUST implement the <code>IInteroperableDelegatedAccount</code> to be compliant with the standard.</p> <p>Accounts MUST use <code>keccak256()</code> to compute the storage bases for <code>accountStorageBases()</code>, unless using external storage contract.</p> <p>Accounts MAY implement the <code>IRedelegableDelegatedAccount</code>.</p> <h3 id="accountid"><code>accountId()</code></h3> <p>This function is a view function to fetch the account information.</p> <p>A use case for this could be wallet showing the redelegation process e.g., Are you willing to migrate your account <code>“Wallet A” → “Wallet B”</code>.</p> <p>Wallet A information could be extracted from <code>accountId()</code>.</p> <h3 id="accountstoragebases"><code>accountStorageBases()</code></h3> <p>This function returns the list of base storage slots of that account has used.</p> <p>To comply with this standard, the account MUST use <code>keccak256()</code> to prevent collision when calculating the storage slot.</p> <p>EIP-7702 Accounts do plan to use a custom non-zero storage slot to avoid storage collision as much as possible, however, there hasn’t been a standardized approach on how to fetch them.</p> <p>This function provides a standardized approach for wallets and other applications to check the base storage slots of an account, and verify if the base storage slots are far enough from the newly to-be-redelegated account’s base storage slot.</p> <p>Note that there could be some exceptions for mappings, etc depending on how account manages storage.</p> <p>This provides Wallets and applications a standard approach to fetch the base storage slots for verification rather than just relying on the probability of hash.</p> <p>If the account uses external storage, it should return ERC Number prefixed slot with the external storage contract address concatenated.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">&lt;</span><span>ERC</span><span class="z-keyword">-</span><span>Number</span><span class="z-keyword">&gt;</span><span class="z-keyword">&lt;</span><span>ERC</span><span class="z-keyword">-</span><span>Number</span><span class="z-keyword">&gt;</span><span class="z-keyword">&lt;</span><span>ERC</span><span class="z-keyword">-</span><span>Number</span><span class="z-keyword">&gt;</span><span>.</span><span>.</span><span>N</span><span>.</span><span>.</span><span>.</span><span class="z-keyword">&lt;</span><span>Storage</span><span class="z-keyword">-</span><span>Contract</span><span class="z-keyword">-</span><span>Address</span><span class="z-keyword">&gt;</span></span></code></pre> <p>For example, if the storage contract address is <code>0xAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA</code> the returned value should be</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x777977797779777977797779AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA</span></span></code></pre> <p>When the account is delegated(e.g., during the account initialization stage), the account implementation should append the base storage slot of the account to the following slot position: <code>keccak(keccak('InteroperableDelegatedAccount.ERC.Storage')-1) &amp; ~0xff</code> .</p> <p>The storage variable would be using the <code>bytes32[]</code> type and is an append-only variable which newly delegated accounts append its storage slot hash. The account may choose to not append its storage base to an array if there is an identical entry that already exist.</p> <p>In case the account identifies that there are colliding storage bases, the account can perform further storage verification either off-chain or on-chain and decide whether the delegation would happen.</p> <p>Wallet may revert the delegation if the colliding storage includes a suspicious storage values that may target the user(e.g., shadow signer, etc).</p> <h3 id="onredelegation"><code>onRedelegation()</code></h3> <p>This function is to prepare for the redelegation to a new account.</p> <p>When this function is called, the existing delegated account should perform actions to not limit or impact the user when the user redelegates to a new account as much as possible.</p> <p>For example, the account could uninitialize the storage variables as much as it can to provide clean storage for new wallet.</p> <p>This standard, however, does not explicitly state the behavior to be done during this function call as wallet implementations have very distinctive architecture and details.</p> <p><strong>The standard expect the wallet implementation to revert it back to a clean storage state <em><strong>as much as possible</strong></em> with this function.</strong></p> <p><code>onRedelegation()</code> should validate if the caller is indeed the authorized user by checking the <code>msg.sender</code> value.</p> <p>This could also be done through a "self-call" if a custom validation scheme is implemented or at the wallet's discretion as a side case.</p> <p><img src="https://wg-eips.ritovision.com/7779/./assets/diagram.svg" alt="diagram showing the flow of onredelegation" /></p> <h2 id="rationale">Rationale</h2> <h3 id="storage-base-checks">Storage base checks</h3> <p>This standard is designed with the need of wallets to validate the storage of the EOA, even if some may consider that the probability of hash is already big that the account doesn't have to check, assuming that each wallet uses a different storage base slot. In fact, this standard thinks exactly the opposite. It is worth scanning the storage, or at least the storage that the delegated account will use, which the wallet wants to delegate to. E.g., Just like developers validating the storage of Facets in Diamond (<a href="https://wg-eips.ritovision.com/2535/">ERC-2535</a>) to prevent storage collision and not just relying on hash probability. In line with this, the <code>accountStorageBases()</code> was designed to not only return the storage base of the current wallet implementation, but return the full historical storage slots that the account has used. This could provide valuable information for the storage scanning of the EOA before delegation.</p> <h3 id="optional-onredelegation">Optional <code>onRedelegation()</code></h3> <p><code>onRedelegation()</code> was designed to be optional to lower the barrier of being compliant with this standard. Also, there could be accounts that does not functionally require a hook-logic to be in place before redelegation, or accounts that does not suite with the design principle of the <code>onRedelegation()</code> e.g., excessive use of mapping or data types that's hard to uninitialize.</p> <p>It is worth noting that, <code>onRedelegation()</code> does not obligate the account to completely whipe out it's storage. It's more of a best effort function to leave the cleanest stage for the future use of the EOA in a new wallet. Or to execute a function to prepare for redelegation.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Existing smart accounts that was built prior to the <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> discussion will need changes to support this standard.</p> <p>This standard was specifically for Smart Accounts for EOA, but this could be applied further to diverse cases and architecture.</p> <h2 id="security-considerations">Security Considerations</h2> <ol> <li> <p>Calling <code>onRedelegation()</code> should include security mechanism to properly authentication the owner.</p> </li> <li> <p>This standard enforces the accounts to</p> <ol> <li>provide proper Base Storage Slot when <code>accountStorageBase()</code> is called</li> <li>perform proper actions to make account storage to a clean state as much as possible (e.g., uninitialization of storage variables, etc) IF the account supports <code>onRedelegation()</code> However, whether the account follows the above three enforcements with behavioral actions is dependant of the account.</li> </ol> <p>If needed, accounts may check the authenticity of the information through off-chain approaches.</p> </li> <li> <p>Wiping out the storage completely may not be an adaptable action depending on how account implementation manages storage.</p> <p>This standard recommends the account to completely wipe out its storage, however, exceptions apply if the account is incapable of doing that.</p> <p>In the case when the account cannot completely wipe out its storage, the standard expect the account to perform the best degree of action it can do to support the redelegation operation for the user.</p> <p>Also, the account should make sure the initializer cannot be triggered by an arbitrary entity after <code>onRedelegation()</code> is called.</p> </li> <li> <p><code>onRedelegation()</code> should not reset the replay protection considering that it could incur a vulnerability(e.g., signature reply attack).</p> </li> <li> <p>It is worth noting that this standard is an ERC, which means that even if the ERC enforces it, the actual implementation may not be compliant with it. e.g., accounts pretending to support this standard which is not, in fact. So it is recommend to validate if the account is a know implementation that is secure and compliant with the standard.</p> </li> <li> <p>The standard ENFORCES the storage slot to be calculated through <code>keccak256()</code> to reduce collision. The preimage of the hash could be the name/version or a combination, it is under full discretion of the account.</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> 2024-10-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ben Adamshttps://github.com/benaadams Toni Wahrstätterhttps://github.com/nerolation https://wg-eips.ritovision.com/7778/

Prevent Block Gas Limit Circumvention by Excluding Refunds from Block Gas Accounting

<h2 id="abstract">Abstract</h2> <p>This EIP modifies the block gas accounting mechanism to prevent the circumvention of block gas limits. It proposes that gas refunds, particularly those from SSTORE operations setting storage slots to zero, should not reduce the gas counted toward the block gas limit, while still being applied to transaction gas costs for users.</p> <h2 id="motivation">Motivation</h2> <p>Currently, gas refunds from operations like clearing storage slots (setting to zero) reduce both the transaction gas cost for users and the gas counted toward the block gas limit. This creates a discrepancy between the computational work performed and the gas accounted for in the block.</p> <p>Example: Block <code>20878522</code> shows a net usage of 28.5 MGas, but contains 4.01 MGas of refunds, bringing the gross usage to 32.51 MGas—exceeding the block gas limit by 2.51 MGas.</p> <p>This mechanism can be exploited to perform more operations in a block than the gas limit intends to allow, potentially leading to:</p> <ol> <li>Network instability due to oversized blocks</li> <li>Denial-of-service vectors</li> <li>Computational loads exceeding the intended block gas limit</li> </ol> <h2 id="specification">Specification</h2> <h3 id="gas-accounting-changes">Gas Accounting Changes</h3> <ol> <li> <p><strong>User Gas Accounting (Unchanged):</strong></p> <ul> <li>Users continue to receive gas refunds for operations that qualify (e.g., setting storage to zero)</li> <li>Transaction gas: <code>gas_spent = max(tx_gas_used - gas_refund, calldata_floor_gas_cost)</code></li> </ul> </li> <li> <p><strong>Block Gas Accounting (Modified):</strong></p> <ul> <li>When calculating gas for block gas limit enforcement, refunds are not subtracted</li> <li>Block gas accounting becomes: <code>block.gas_used += max(tx_gas_used, calldata_floor_gas_cost)</code> (incorporating the calldata floor from <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a>)</li> <li>Storage discounts that reflect actual reduced computational work (e.g., warm storage access, reverting to original values) remain applied to block gas accounting</li> </ul> </li> </ol> <h2 id="rationale">Rationale</h2> <h3 id="aligning-gas-limits-with-computational-work">Aligning Gas Limits with Computational Work</h3> <p>The block gas limit is designed to constrain the computational load per block. Gas refunds were introduced to incentivize "cleaning up" the state, not to allow exceeding computational limits. By excluding refunds from block gas accounting, we ensure the block gas limit effectively constrains computational load</p> <h3 id="preserving-user-incentives">Preserving User Incentives</h3> <p>Users still receive gas refunds, maintaining incentives for efficient state management. Only the accounting for block-level constraints changes, not the economics for individual users</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <ul> <li>This change is not backwards compatible and requires a hard fork</li> <li>User and developer experience for individual transactions remains unchanged</li> <li>Block producers need to adjust their transaction selection algorithms to account for the new gas accounting rules</li> </ul> <h2 id="test-cases">Test Cases</h2> <ol> <li> <p><strong>SSTORE Operations:</strong></p> <ul> <li>Setting storage to zero: User receives refund, but block gas accounting uses full cost</li> <li>Verify blocks containing many storage-clearing operations still adhere to gas limits</li> </ul> </li> <li> <p><strong>Block Gas Limit Edge Cases:</strong></p> <ul> <li>Construct blocks with varying amounts of refundable operations</li> <li>Ensure blocks cannot exceed gas limits through refund mechanisms</li> </ul> </li> <li> <p><strong>Transaction Gas vs Block Gas:</strong></p> <ul> <li>Verify that transaction costs for users remain unchanged</li> <li>Confirm block gas accounting properly excludes refunds</li> </ul> </li> </ol> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>Eliminates potential denial-of-service vectors that exploit gas refunds to exceed block computational limits</li> <li>Improves predictability of block processing times by enforcing stricter limits on computational work</li> <li>Prevents miners/validators from including transactions that collectively contain more computational work than intended</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> 2024-10-01T00:00:00+00:00 2026-02-11T14:48:26+00:00 zeroknotshttps://github.com/zeroknots Konrad Kopphttps://github.com/kopy-kat Taek Leehttps://github.com/leekt Fil Makarovhttps://github.com/filmakarov https://wg-eips.ritovision.com/7780/

Introduces new smart account module types for signature validation and permissioning

<h2 id="abstract">Abstract</h2> <p>This proposal introduces three new module types on top of the existing modules described in <a href="https://wg-eips.ritovision.com/7579/">ERC-7579</a>. The modules are policy, signer and stateless validator. None of these modules are required to be implemented by accounts, but accounts can choose to implement them or other modules can choose to make use of them for additional composability.</p> <p>Policy modules can be used to check what a <code>UserOperation</code> or action is trying to achieve and determine if this is allowed. Signer modules can be used to validate signatures on provided hashes. Stateless validators are modules that are used to both validate signatures and compare them to a calldata-provided data blob which could, for example, include owners to check signatures against.</p> <h2 id="motivation">Motivation</h2> <p>The modules introduced by this proposal aim to create more composability around signature and permission verification.</p> <p>Policy and signer modules allow an account to make direct use of such a permissioning logic rather than relying on external modules to handle this. This has the upside of lower gas cost but the downside of less flexibility for users and developers that use the account.</p> <p>Stateless validators enable further composability around signature validation logic. In many cases, it does not make sense to re-write signature validation for new validators, but instead to use the existing ones. However, this is usually not possible since the validators rely on a stored configuration indexed by the <code>msg.sender</code>, which is expected to be an account. Stateless validators solve this problem by not relying on state to compare signature verification against, but instead to compare it against a calldata-provided argument.</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 standard introduces three new module types on top of the existing modules introduced by ERC-7579:</p> <ul> <li><code>Policy</code> (type id: 5)</li> <li><code>Signer</code> (type id: 6)</li> <li><code>StatelessValidator</code> (type id: 7)</li> <li><code>PreValidationHookERC1271</code> (type id: 8)</li> <li><code>PreValidationHookERC4337</code> (type id: 9)</li> <li><code>StatelessValidatorWithSender</code> (type id: 10)</li> </ul> <p>Note: A single module can be of multiple types.</p> <h3 id="policy">Policy</h3> <p>Policies MUST implement <a href="https://wg-eips.ritovision.com/7579/">ERC-7579</a>'s <code>IModule</code> and the <code>IPolicy</code> interface and have module type id: <code>5</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"> IPolicy</span><span class="z-storage"> is</span><span class="z-entity z-name"> IModule</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"> * Checks a userOp to determine if it should be executed</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * SHOULD validate the executions in the userOp against stored configurations</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"> id</span><span class="z-comment"> The id of the policy</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> userOp</span><span class="z-comment"> The user operation to check</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"> The</span><span class="z-comment"> validation data to return to the EntryPoint as specified by ERC-4337</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"> checkUserOpPolicy</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> id</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> PackedUserOperation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> userOp</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-storage z-type"> payable</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> <span class="giallo-l"><span class="z-comment"> * Checks a signature to determine if it should be executed</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * SHOULD validate the hash in order to determine what the signature is used for and if it should be permitted</span></span> <span class="giallo-l"><span class="z-comment"> * MAY check the sender to determine whether the signature should be permitted</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"> id</span><span class="z-comment"> The id of the policy</span></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 sender 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"> hash</span><span class="z-comment"> The hash 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"> sig</span><span class="z-comment"> The signature of the transaction</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"> The</span><span class="z-comment"> validation data to return to the EntryPoint as specified by ERC-4337</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"> checkSignaturePolicy</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> id</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> hash</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"> sig</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-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-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="signer">Signer</h3> <p>Signers MUST implement the <code>IModule</code> and the <code>ISigner</code> interface and have module type id: <code>6</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"> ISigner</span><span class="z-storage"> is</span><span class="z-entity z-name"> IModule</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"> * Check the signature of a user operation</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"> id</span><span class="z-comment"> The id of the signer config</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> userOp</span><span class="z-comment"> The user 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"> userOpHash</span><span class="z-comment"> The hash of the user operation</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"> The</span><span class="z-comment"> status of the signature check to return to the EntryPoint</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"> checkUserOpSignature</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> id</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> PackedUserOperation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> userOp</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> userOpHash</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-storage z-type"> payable</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> <span class="giallo-l"><span class="z-comment"> * Check an ERC-1271 signature</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"> id</span><span class="z-comment"> The id of the signer config</span></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 sender of the 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"> hash</span><span class="z-comment"> The hash to check against</span></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"> The signature to validate</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"> The</span><span class="z-comment"> ERC-1271 magic value if the signature is valid</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"> checkSignature</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> id</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> hash</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"> sig</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-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-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><h3 id="stateless-validator">Stateless Validator</h3> <p>StatelessValidators MUST implement the <code>IStatelessValidator</code> interface and have module type id: <code>7</code>. It is RECOMMENDED that all Validators (module type id <code>1</code>) also implement the Stateless Validator interface for additional composabillity.</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"> IStatelessValidator</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"> * Validates a signature given some data</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"> hash</span><span class="z-comment"> The data that was signed over</span></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"> The signature to verify</span></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 data to validate the verified signature against</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST validate that the signature is a valid signature of the hash</span></span> <span class="giallo-l"><span class="z-comment"> * MUST compare the validated signature against the data provided</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return true if the signature is valid and 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"> validateSignatureWithData</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> hash</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"> signature</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> <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> <span class="giallo-l"><span class="z-comment"> * Returns boolean value if module is a certain type</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"> moduleTypeId</span><span class="z-comment"> the module type ID according the ERC-7579 spec</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return true if the module is of the given type and 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"> isModuleType</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> moduleTypeId</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><h3 id="prevalidationhookerc1271"><code>PreValidationHookERC1271</code></h3> <p><code>PreValidationHookERC1271</code> MUST implement the <code>IPreValidationHookERC1271</code> interface and have module type id: <code>8</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"> IPreValidationHookERC1271</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> preValidationHookERC1271</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> hash</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> <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">bytes32</span><span class="z-variable"> hookHash</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> hookSignature</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="prevalidationhookerc4337"><code>PreValidationHookERC4337</code></h3> <p><code>PreValidationHookERC4337</code> MUST implement the <code>IPreValidationHookERC4337</code> interface and have module type id: <code>9</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"> IPreValidationHookERC4337</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> preValidationHookERC4337</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> PackedUserOperation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> userOp</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> missingAccountFunds</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> userOpHash</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-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> hookHash</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> hookSignature</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="statelessvalidatorwithsender">StatelessValidatorWithSender</h3> <p>StatelessValidatorWithSender MUST implement the <code>IStatelessValidatorWithSender</code> interface and have module type id: <code>10</code>. It is RECOMMENDED that all Validators (module type id <code>1</code>) also implement the Stateless Validator With Sender interface for additional composabillity.</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"> IStatelessValidatorWithSender</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * Validates a signature given some data</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"> sender</span><span class="z-comment"> address who called account.isValidSignature()</span></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 data that was signed over</span></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"> The signature to verify</span></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 data to validate the verified signature against</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST validate that the signature is a valid signature of the hash</span></span> <span class="giallo-l"><span class="z-comment"> * MUST compare the validated signature against the data provided</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return true if the signature is valid and 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"> validateSignatureWithDataWithSender</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> hash</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"> signature</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"> 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>TBD <!-- TODO --></p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="security-considerations">Security Considerations</h2> <p>TBD <!-- 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-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-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 OpenMind Jan Liphardtjan@openmind.org Shaohong Zhonghttps://github.com/ShaohongZ Boyuan Chenhttps://github.com/bchen-dev Paige Xupaige@openmind.org James Balljames.ball@nethermind.io Thamer Dridithamer.dridi@nethermind.io https://wg-eips.ritovision.com/7777/

Defines interfaces for managing the identities of humans and robots, and establishing rule sets for their interaction.

<h2 id="abstract">Abstract</h2> <p>This proposal defines two core interfaces: <code>IUniversalIdentity</code> and <code>IUniversalCharter</code>, providing mechanisms for humans, and robots to establish their identities and to create decentralized communities governed by specific rule sets. The <code>IUniversalIdentity</code> interface establishes the fair and equitable treatment of sentient computer architectures other than the human brain, enabling robots to acquire on-chain identities, and thereby interact and transact with humans. Additionally the <code>IUniversalIdentity</code> interface also includes support for hardware-backed identity verification, enabling physical robots to prove their identity through cryptographic signatures derived from secure hardware elements and a challenge-response scheme. The <code>IUniversalCharter</code> enables humans and robots to create, join (“register”), maintain (“update”), leave, and terminate self-regulated societies based on predefined rule sets, providing a framework for collaboration and prosperity for mixed societies of humans and robots. These interfaces aim to provide a flexible yet enforceable structure for human-robot interactions in decentralized systems, ensuring efficiency, transparency, and security for all participants.</p> <h2 id="motivation">Motivation</h2> <p>The human brain is a wet, massively parallel electrochemical computer. Recent hardware and software advances make it likely that soon, human societies will need tools for interacting with sentient, non-human computers, such as robots. Our current forms of government, where citizens are auto-enrolled into specific rule sets depending on where they were born, do not gracefully map onto robots without a traditional birthplace or birthtime. Among many difficulties being experienced by robots, they are (currently) unable to obtain standard forms of ID (such as passports), it is not clear which rule sets apply to them (since in general they are not born in specific places), and they cannot currently use the standard human-centered banking system. Likewise, in the event in which robots are harmed by humans or non-biological computers, it is not clear which human court has jurisdiction.</p> <p>Traditional geographically-defined and human-centered systems can be inefficient, slow to change, opaque, and can struggle to accommodate global, virtualized societies. Decentralized, immutable, and public computers offer an ideal solution to these limitations, since they do not inherently discriminate against non-human computers and therefore offer an equitable and more just framework for governance. In particular, smart contracts can provide a powerful framework for regulating the rights and responsibilities or interacting parties regardless of implementation details of their compute architecture.</p> <p>The general motivation of this ERC is to provide a standard interface for smart contracts focusing on identity/governance for heterogeneous global societies. While there are an unlimited number of such rule sets, there are obvious benefits to providing a standard interface to those rule sets, greatly reducing the friction and complexity of creating, joining, maintaining, and ending such societies. The specific motivation of this ERC is twofold:</p> <ol> <li>Robot Identity Creation and Management: To participate meaningfully and comply with on-chain laws, non-humans such as robots must be able to acquire meaningful on-chain identities. Importantly, these identities should enable robots to enjoy the benefits of, but also bear the responsibility of, being part of a specific society. Thus, we propose to enable smart contract-based identity for robots. Specifically, each robot is represented by a smart contract and needs to follow the rules defined in the contract to interact with other agents on the chain. Each robot can also specify hardware identity parameters such as a manufacturer, operator, model and serial number in conjunction with a public key which is intended to be generated using a secure element on the Robot. This provides a tamper-resistant and unclonable proof that can be physically verified through challenge-response authentication - where any party can verify the robot's identity by having the device cryptographically sign a challenge using its hardware-secured private key. These verified identities are published on-chain. This interface also ensures flexibility by all participants to propose, adopt, or revoke rules, enabling self-managed compliance and transparent interaction with other participants.</li> <li>Rule Creation and Enforcement: For humans and robots to effectively collaborate, they must agree upon a rule set. This Ethereum-based system provides a basic decentralized framework for governing human-robot interactions through smart contracts. We propose to enforce the rule-sets by requiring humans and robots to join regulated access smart contracts that check their compliance with the given rules. We also ensure scalability, whereby multiple regulated access contracts can be created to tailor to different purposes, and humans and robots can choose to join the relevant system as needed.</li> </ol> <p>Together, these interfaces form the foundation for managing complex human-robot interactions, enabling a decentralized, verifiable, and rule-based ecosystem where robots and humans can interact securely, transparently, and responsibly, for maximum benefit of all.</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> <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"> IUniversalIdentity</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"> Structure for hardware identity</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> HardwareIdentity</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> publicKey</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Hardware-bound public key uniquely tied to this robot</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> manufacturer</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Identifier for the robot&#39;s manufacturer</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> operator</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Identifier for the robot&#39;s operator</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> model</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Model identifier of the robot</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> serialNumber</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Unique serial number for the robot</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> initialHashSignature</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Signature of the initial system state hash (e.g., firmware, OS) by the root key</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> currentHashSignature</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Signature of the latest state hash, updated periodically for integrity verification by the root key</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"> @notice</span><span class="z-comment"> Gets the hardware identity info</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"> HardwareIdentity</span><span class="z-comment"> Current hardware identity</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getHardwareIdentity</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-storage z-type">HardwareIdentity</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"> Generates a new challenge for hardware verification</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"> Random challenge that needs to be signed</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> generateChallenge</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">bytes32</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"> Verify response to a specific challenge</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> challenge</span><span class="z-comment"> The challenge that was issued</span></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"> Hardware signature of the challenge</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"> True if signature is valid for this challenge</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyChallenge</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> challenge</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 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"> Adds a rule to the robot&#39;s identity, showing that the robot agrees to follow the rule.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> rule</span><span class="z-comment"> The dynamic byte array representing the rule that the robot agrees to follow. Each rule is a textual string encoded into a dynamic byte array. For example: &#39;A robot must keep a 1m distance from humans.&#39;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The rule SHOULD come from the rule sets defined in the IUniversalCharter contract that the robot intends to join. </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 SHOULD be implemented by contracts to add the rules that the robot intends to follow.</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">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> rule</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"> Removes a rule from the robot&#39;s identity.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> rule</span><span class="z-comment"> The dynamic byte array representing the rule that the robot no longer agrees to follow.</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 SHOULD be implemented by contracts to remove the rules that the robot does not intend to follow.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeRule</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> rule</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"> Checks if the robot complies with a specific rule.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> rule</span><span class="z-comment"> The rule to check.</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"> Returns true if the robot complies with the rule.</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 be implemented by contracts for compliance verification.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkCompliance</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> rule</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"> Emitted when a rule is added to the robot&#39;s identity.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RuleAdded</span><span>(</span><span class="z-support">bytes</span><span class="z-variable"> rule</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"> Emitted when a rule is removed from the robot&#39;s identity.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RuleRemoved</span><span>(</span><span class="z-support">bytes</span><span class="z-variable"> rule</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"> Emitted when a charter is subscribed to.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SubscribedToCharter</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> charter</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"> Emitted when it is unsubscribed from a charter.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UnsubscribedFromCharter</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> charter</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"> IUniversalCharter</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Define the user types as an enum.</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> UserType</span><span> {</span><span class="z-variable z-other z-enummember"> Human</span><span>,</span><span class="z-variable z-other z-enummember"> Robot</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"> Registers a user (human or robot) to join the system by agreeing to a rule 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"> userType</span><span class="z-comment"> The type of 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"> ruleSet</span><span class="z-comment"> The array of individual rules the user agrees to follow. </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 be implemented by contracts using this interface.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The implementing contract MUST ensure that the user complies with the specified rule set before registering them in the system by invoking `checkCompliance`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerUser</span><span>(</span><span class="z-storage z-type">UserType</span><span class="z-variable"> userType</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"> ruleSet</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"> Allows a user (human or robot) to leave the system </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 be callable only by the user themselves (via `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 implementing contract MUST ensure that the user has complied with all necessary rules before they can successfully leave the system by invoking `checkCompliance`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> leaveSystem</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"> Checks if the user (human or robot) complies with the system’s rules.</span></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 user (human or robot).</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> ruleSet</span><span class="z-comment"> The array of individual rules to verify. </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"> Returns true if the user complies with the rule set.</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 SHOULD invoke the `checkCompliance` function of the user’s IUniversalIdentity contract to check for rules individually. </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 be implemented by contracts for compliance verification.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkCompliance</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</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"> ruleSet</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"> Updates the rule 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"> newRuleSet</span><span class="z-comment"> The array of new individual rules replacing the existing ones. </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 SHOULD be restricted to authorized users (e.g., contract owner).</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateRuleSet</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"> newRuleSet</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"> Terminates the contract, preventing any further registrations or interactions.</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 SHOULD be restricted to authorized users (e.g., contract owner).</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 SHOULD be implemented by contracts.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> terminateContract</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"> @dev</span><span class="z-comment"> Emitted when a user joins the system by agreeing to a set of rules.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UserRegistered</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-variable">UserType</span><span class="z-variable"> userType</span><span>, </span><span class="z-support">bytes</span><span>[</span><span>]</span><span class="z-variable"> ruleSet</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"> Emitted when a user successfully leaves the system after fulfilling obligations.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UserLeft</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>;</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"> Emitted when a user’s compliance with a rule set is verified.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ComplianceChecked</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">bytes</span><span>[</span><span>]</span><span class="z-variable"> ruleSet</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"> Emitted when a rule set is updated.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RuleSetUpdated</span><span>(</span><span class="z-support">bytes</span><span>[</span><span>]</span><span class="z-variable"> newRuleSet</span><span>, </span><span class="z-support">address</span><span class="z-variable"> updatedBy</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p><strong>IUniversalIdentity</strong></p> <p><code>struct HardwareIdentity</code> The HardwareIdentity structure provides essential information about a robot, including a challenge-response public key, manufacturer, operator, model, manufacturer serial number</p> <p><code>generateChallenge()</code> This function enables secure identity verification through a challenge-response authentication.</p> <p><code>verifyChallenge(bytes32 challenge, bytes memory signature)</code> This function verifies that a signature was genuinely created by the robot's secure hardware in response to a specific challenge.</p> <p><code>addRule(bytes memory rule)</code> This function allows a robot to flexibly adopt new compliance requirements in order join different <code>IUniversalCharter</code> contracts.</p> <p><code>removeRule(bytes memory rule)</code> This function allows a robot to dynamically manage and maintain its rules, ensuring that its rule set remains up-to-date.</p> <p><code>checkCompliance(bytes memory rule)</code> This function ensures that a robot is adhering to rules by performing decentralised checks on its compliance.</p> <p><code>Events (RuleAdded, RuleRemoved)</code> These events provide transparency and traceability, making it easier to track compliance status.</p> <p><strong>IUniversalCharter</strong></p> <p><code>enum UserType { Human, Robot }</code> The UserType enum makes it easier for contracts to handle different user types without the cost and errors associated with strings. This provides the basis for differentiated handling in future implementations, allowing the system to potentially apply different rules or logic based on whether the user is a human or a robot.</p> <p><code>registerUser(UserType userType, bytes[] memory ruleSet)</code> This function ensures that a user—whether human or robot—is bound to a particular set of rules upon joining the system.</p> <p><code>leaveSystem()</code> This function allows users to flexibly and securely leave a <code>IUniversalCharter</code> contract after compliance is checked.</p> <p><code>checkCompliance(address user, bytes[] memory ruleSet)</code> This function ensures that the system can efficiently manage and verify compliance against predefined rule sets, helping maintain the overall integrity of the system.</p> <p><code>updateRuleSet(bytes[] memory newRuleSet)</code> This function enables the <code>IUniversalCharter</code> contract to adapt and update, removing the need to create a new contract for ruleset updates.</p> <p><code>terminateContract()</code> This function allows for the orderly and permanent shutdown of the contract.</p> <p><code>Events (UserRegistered, UserLeft, ComplianceChecked, RuleSetUpdated, ContractTerminated)</code> These events collectively ensure that key activities are visible to off-chain systems and participants, making the system auditable and transparent.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</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"> ^0.8.19</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">OwnableUpgradeable</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">UniversalCharter</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./UniversalCharter.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Interfaces</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">IUniversalIdentity</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./interface/IUniversalIdentity.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">IUniversalCharter</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./interface/IUniversalCharter.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"> UniversalIdentity</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> The UniversalIdentity contract is used to manage the identity of robots.</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"> UniversalIdentity</span><span class="z-storage"> is</span><span class="z-entity z-name"> IUniversalIdentity</span><span>, </span><span class="z-entity z-name">OwnableUpgradeable</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"> Version identifier for the current implementation of the contract.</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> VERSION </span><span class="z-keyword">=</span><span class="z-string"> &quot;v0.0.1&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"> @notice</span><span class="z-comment"> Mapping to store rules that the robot has agreed to follow</span></span> <span class="giallo-l"><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"> bool</span><span>)</span><span class="z-storage z-type"> private</span><span> robotRules</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"> Mapping to store the off-chain compliance status for each rule</span></span> <span class="giallo-l"><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"> bool</span><span>)</span><span class="z-storage z-type"> private</span><span> complianceStatus</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"> Track the charters the robot is subscribed to</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> subscribedCharters</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"> Custom errors to save gas on reverts</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> RuleNotAgreed</span><span>(</span><span class="z-support">bytes</span><span> rule</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> RuleNotCompliant</span><span>(</span><span class="z-support">bytes</span><span> rule</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> RuleAlreadyAdded</span><span>(</span><span class="z-support">bytes</span><span> rule</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 emit when compliance is checked</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> updater</span><span class="z-comment"> The address of the compliance updater (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"> rule</span><span class="z-comment"> The rule that was checked</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ComplianceChecked</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> updater</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> rule</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"> Modifier to check if a rule exists</span></span> <span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> ruleExists</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> rule</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>robotRules</span><span>[</span><span>rule</span><span>]</span><span>,</span><span class="z-string"> &quot;Rule does not exist&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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Constructor to set the owner</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> initialize</span><span>(</span><span>{</span><span> _owner</span><span class="z-keyword">:</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0xdEaD</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-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Initializer function</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">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-entity z-name"> initializer</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> __Ownable_init</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> transferOwnership</span><span>(</span><span>_owner</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> hardwareIdentity </span><span class="z-keyword">=</span><span> _hardwareIdentity</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"> @notice</span><span class="z-comment"> Gets the hardware identity info</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getHardwareIdentity</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-storage z-type">HardwareIdentity</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> hardwareIdentity</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"> @notice</span><span class="z-comment"> Generates a new challenge for hardware verification</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> generateChallenge</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">bytes32</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> challenge </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> <span class="giallo-l"><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-language"> block</span><span>.</span><span>prevrandao</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-language"> msg.sender</span></span> <span class="giallo-l"><span> )</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> activeChallenge</span><span>[</span><span>challenge</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> challenge</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"> @notice</span><span class="z-comment"> Verify response to a specific challenge</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyChallenge</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> challenge</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"> signature</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 class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>activeChallenge</span><span>[</span><span>challenge</span><span>]</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> InvalidChallenge</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"> Remove challenge after use</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> activeChallenge</span><span>[</span><span>challenge</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Verify the signature using ECDSA</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> messageHash </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>challenge</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> ethSignedMessageHash </span><span class="z-keyword">=</span><span> ECDSA</span><span>.</span><span class="z-entity z-name">toEthSignedMessageHash</span><span>(</span><span>messageHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> signer </span><span class="z-keyword">=</span><span> ECDSA</span><span>.</span><span class="z-entity z-name">recover</span><span>(</span><span>ethSignedMessageHash</span><span>,</span><span> signature</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"> Convert hardware public key to address for comparison</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> hardwareAddress </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span class="z-support">uint160</span><span>(</span><span class="z-support">uint256</span><span>(</span><span>hardwareIdentity</span><span>.</span><span>publicKey</span><span>)</span><span>)</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>signer </span><span class="z-keyword">!=</span><span> hardwareAddress</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> InvalidSignature</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-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-storage z-type"> @notice</span><span class="z-comment"> Updates the hardware identity information</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _hardwareIdentity</span><span class="z-comment"> New hardware identity information</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateHardwareIdentity</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> HardwareIdentity</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _hardwareIdentity</span></span> <span class="giallo-l"><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> hardwareIdentity </span><span class="z-keyword">=</span><span> _hardwareIdentity</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"> @notice</span><span class="z-comment"> Adds a rule to the robot&#39;s identity</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> rule</span><span class="z-comment"> The dynamic byte array representing the rule that the robot agrees to follow.</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">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> rule</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> override</span><span class="z-entity z-name"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>robotRules</span><span>[</span><span>rule</span><span>]</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> RuleAlreadyAdded</span><span>(</span><span>rule</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"> Add rule to the mapping</span></span> <span class="giallo-l"><span> robotRules</span><span>[</span><span>rule</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-keyword"> emit</span><span class="z-entity z-name"> RuleAdded</span><span>(</span><span>rule</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"> @notice</span><span class="z-comment"> Removes a rule from the robot&#39;s identity</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> rule</span><span class="z-comment"> The dynamic byte array representing the rule that the robot no longer agrees to follow.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeRule</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> rule</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> override</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> ruleExists</span><span>(</span><span class="z-entity z-name">rule</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> robotRules</span><span>[</span><span>rule</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span> complianceStatus</span><span>[</span><span>rule</span><span>]</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-keyword"> emit</span><span class="z-entity z-name"> RuleRemoved</span><span>(</span><span>rule</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"> @notice</span><span class="z-comment"> Subscribe and register to a specific UniversalCharter contract using its stored rule 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"> charter</span><span class="z-comment"> The address of the UniversalCharter 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"> version</span><span class="z-comment"> The version of the rule set to fetch and register for</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> subscribeAndRegisterToCharter</span><span>(</span><span class="z-support">address</span><span class="z-variable"> charter</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> version</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-keyword">!</span><span>subscribedCharters</span><span>[</span><span>charter</span><span>]</span><span>,</span><span class="z-string"> &quot;Already subscribed to this charter&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> subscribedCharters</span><span>[</span><span>charter</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"> Fetch the rule set directly from the UniversalCharter contract using the public getter</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> ruleSet </span><span class="z-keyword">=</span><span class="z-entity z-name"> UniversalCharter</span><span>(</span><span>charter</span><span>)</span><span>.</span><span class="z-entity z-name">getRuleSet</span><span>(</span><span>version</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Register as a robot in the charter using the fetched rule set</span></span> <span class="giallo-l"><span class="z-entity z-name"> UniversalCharter</span><span>(</span><span>charter</span><span>)</span><span>.</span><span class="z-entity z-name">registerUser</span><span>(</span><span>IUniversalCharter</span><span>.</span><span>UserType</span><span>.</span><span>Robot</span><span>,</span><span> ruleSet</span><span>)</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"> SubscribedToCharter</span><span>(</span><span>charter</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"> @notice</span><span class="z-comment"> Leave the system for a specific UniversalCharter 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"> charter</span><span class="z-comment"> The address of the UniversalCharter contract to leave</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> leaveCharter</span><span>(</span><span class="z-support">address</span><span class="z-variable"> charter</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>subscribedCharters</span><span>[</span><span>charter</span><span>]</span><span>,</span><span class="z-string"> &quot;Not subscribed to this charter&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"> Call the leaveSystem function of the UniversalCharter contract</span></span> <span class="giallo-l"><span class="z-entity z-name"> UniversalCharter</span><span>(</span><span>charter</span><span>)</span><span>.</span><span class="z-entity z-name">leaveSystem</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"> Unsubscribe from the charter after leaving</span></span> <span class="giallo-l"><span> subscribedCharters</span><span>[</span><span>charter</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> UnsubscribedFromCharter</span><span>(</span><span>charter</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"> @notice</span><span class="z-comment"> Updates compliance status for a rule (called by 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"> rule</span><span class="z-comment"> The dynamic byte array representing the rule</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> status</span><span class="z-comment"> The compliance status (true if compliant, false if not)</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateCompliance</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> rule</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> status</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> ruleExists</span><span>(</span><span class="z-entity z-name">rule</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> complianceStatus</span><span>[</span><span>rule</span><span>]</span><span class="z-keyword"> =</span><span> status</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"> ComplianceChecked</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> rule</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"> @notice</span><span class="z-comment"> Checks if the robot has agreed to follow a specific rule and if it is compliant</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> rule</span><span class="z-comment"> The rule to check.</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"> Returns true if the robot has agreed to the rule and is compliant</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkCompliance</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> rule</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"> 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"> if</span><span> (</span><span class="z-keyword">!</span><span>robotRules</span><span>[</span><span>rule</span><span>]</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> RuleNotAgreed</span><span>(</span><span>rule</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-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-storage z-type"> @notice</span><span class="z-comment"> Gets the compliance status of a rule</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> rule</span><span class="z-comment"> The rule to check.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getRule</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> rule</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> robotRules</span><span>[</span><span>rule</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"> @notice</span><span class="z-comment"> Gets the subscription status of a charter</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> charter</span><span class="z-comment"> The address of the charter to check.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getSubscribedCharters</span><span>(</span><span class="z-support">address</span><span class="z-variable"> charter</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> subscribedCharters</span><span>[</span><span>charter</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"> @notice</span><span class="z-comment"> Gets the compliance status of a rule</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> rule</span><span class="z-comment"> The rule to check.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getComplianceStatus</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> rule</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> complianceStatus</span><span>[</span><span>rule</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"> 0.8.20</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">OwnableUpgradeable</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">SystemConfig</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./SystemConfig.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Interfaces</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">IUniversalCharter</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./interface/IUniversalCharter.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">IUniversalIdentity</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./interface/IUniversalIdentity.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"> UniversalCharter</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> The UniversalCharter contract is used to manage the registration and compliance of users.</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"> UniversalCharter</span><span class="z-storage"> is</span><span class="z-entity z-name"> IUniversalCharter</span><span>, </span><span class="z-entity z-name">OwnableUpgradeable</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"> Struct to store information about a registered user</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> UserInfo</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isRegistered</span><span>;</span></span> <span class="giallo-l"><span> UserType userType</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> ruleSetVersion</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Rule set version the user is following</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"> @notice</span><span class="z-comment"> Mapping to store registered users</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> UserInfo</span><span>)</span><span class="z-storage z-type"> private</span><span> users</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"> Mapping to store rule sets by version number</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>]</span><span>)</span><span class="z-storage z-type"> private</span><span> ruleSets</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"> Mapping to track the rule set hash and its corresponding version</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"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> ruleSetVersions</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"> Version identifier for the current implementation of the contract.</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> VERSION </span><span class="z-keyword">=</span><span class="z-string"> &quot;v0.0.1&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"> @notice</span><span class="z-comment"> Variable to track the current version of the rule set</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> currentVersion</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"> Variable to store the address of the SystemConfig contract</span></span> <span class="giallo-l"><span> SystemConfig </span><span class="z-storage z-type">public</span><span> systemConfig</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"> Error for when a method cannot be called when paused. This could be renamed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> to `Paused` in the future, but it collides with the `Paused` event.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> CallPaused</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"> Reverts when paused.</span></span> <span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> whenNotPaused</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-entity z-name">paused</span><span>(</span><span>)</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> CallPaused</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Constucts the UniversalCharter contract.</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> initialize</span><span>(</span><span>{</span><span> _owner</span><span class="z-keyword">:</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0xdEaD</span><span>)</span><span>,</span><span> _systemConfig</span><span class="z-keyword">:</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0xdEaD</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-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Initializer function</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">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"> _systemConfig</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> initializer</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> __Ownable_init</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> transferOwnership</span><span>(</span><span>_owner</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> systemConfig </span><span class="z-keyword">=</span><span class="z-entity z-name"> SystemConfig</span><span>(</span><span>_systemConfig</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"> @notice</span><span class="z-comment"> Registers a user (either human or robot) by agreeing to a rule 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"> userType</span><span class="z-comment"> The type of user: Human or Robot</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> ruleSet</span><span class="z-comment"> The array of individual rules the user agrees to follow</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerUser</span><span>(</span><span class="z-storage z-type">UserType</span><span class="z-variable"> userType</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"> ruleSet</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> override</span><span class="z-entity z-name"> whenNotPaused</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-keyword">!</span><span>users</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>isRegistered</span><span>,</span><span class="z-string"> &quot;User already registered&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"> Hash the rule set to find the corresponding version</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> ruleSetHash </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>ruleSet</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> version </span><span class="z-keyword">=</span><span> ruleSetVersions</span><span>[</span><span>ruleSetHash</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>version </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Invalid or unregistered rule 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"> For robots, ensure compliance with each rule via the UniversalIdentity contract</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>userType </span><span class="z-keyword">==</span><span> UserType</span><span>.</span><span>Robot</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_checkRobotCompliance</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> version</span><span>)</span><span>,</span><span class="z-string"> &quot;Robot not compliant with rule set&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-comment"> //</span><span class="z-comment"> Register the user with the versioned rule set</span></span> <span class="giallo-l"><span> users</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> UserInfo</span><span>(</span><span>{</span><span> isRegistered</span><span class="z-keyword">:</span><span class="z-constant"> true</span><span>,</span><span> userType</span><span class="z-keyword">:</span><span> userType</span><span>,</span><span> ruleSetVersion</span><span class="z-keyword">:</span><span> version </span><span>}</span><span>)</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"> UserRegistered</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> userType</span><span>,</span><span> ruleSet</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"> @notice</span><span class="z-comment"> Allows a user (human or robot) to leave the system after passing compliance checks</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> leaveSystem</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> override</span><span class="z-entity z-name"> whenNotPaused</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>users</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>isRegistered</span><span>,</span><span class="z-string"> &quot;User not registered&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> UserInfo </span><span class="z-storage z-type">memory</span><span> userInfo </span><span class="z-keyword">=</span><span> users</span><span>[</span><span class="z-variable z-language">msg.sender</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 robots, verify compliance with all rules in the rule set</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> version </span><span class="z-keyword">=</span><span> userInfo</span><span>.</span><span>ruleSetVersion</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>userInfo</span><span>.</span><span>userType </span><span class="z-keyword">==</span><span> UserType</span><span>.</span><span>Robot</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_checkRobotCompliance</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> version</span><span>)</span><span>,</span><span class="z-string"> &quot;Robot not compliant with rule set&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> users</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> UserInfo</span><span>(</span><span>{</span><span> isRegistered</span><span class="z-keyword">:</span><span class="z-constant"> false</span><span>,</span><span> userType</span><span class="z-keyword">:</span><span> UserType</span><span>.</span><span>Human</span><span>,</span><span> ruleSetVersion</span><span class="z-keyword">:</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-keyword"> emit</span><span class="z-entity z-name"> UserLeft</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Internal function to verify robot hardware identity</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> robotAddress</span><span class="z-comment"> The address of the robot to verify</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"> Returns true if hardware verification succeeds</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _verifyRobotHardware</span><span>(</span><span class="z-support">address</span><span class="z-variable"> robotAddress</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> IUniversalIdentity robot </span><span class="z-keyword">=</span><span class="z-entity z-name"> IUniversalIdentity</span><span>(</span><span>robotAddress</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"> Get hardware identity to ensure it exists</span></span> <span class="giallo-l"><span> robot</span><span>.</span><span class="z-entity z-name">getHardwareIdentity</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"> Generate a new challenge</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> challenge </span><span class="z-keyword">=</span><span> robot</span><span>.</span><span class="z-entity z-name">generateChallenge</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"> Store the challenge for future reference</span></span> <span class="giallo-l"><span> users</span><span>[</span><span>robotAddress</span><span>]</span><span>.</span><span>lastVerifiedChallenge </span><span class="z-keyword">=</span><span> challenge</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Get signature from the robot (this would typically happen off-chain)</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> For this implementation, we&#39;ll assume the signature is provided in a separate tx</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> and just verify the challenge exists</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> challenge </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 class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Checks if a user complies with their registered rule 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"> user</span><span class="z-comment"> The address of the user (human or robot)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> ruleSet</span><span class="z-comment"> The array of individual rules to verify</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"> Returns true if the user complies with the given rule set</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkCompliance</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</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"> ruleSet</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"> 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>users</span><span>[</span><span>user</span><span>]</span><span>.</span><span>isRegistered</span><span>,</span><span class="z-string"> &quot;User not registered&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"> Hash the provided rule set to find the corresponding version</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> ruleSetHash </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>ruleSet</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> version </span><span class="z-keyword">=</span><span> ruleSetVersions</span><span>[</span><span>ruleSetHash</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>version </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Invalid or unregistered rule set&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>users</span><span>[</span><span>user</span><span>]</span><span>.</span><span>ruleSetVersion </span><span class="z-keyword">==</span><span> version</span><span>,</span><span class="z-string"> &quot;Rule set version mismatch&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"> For robots, check compliance with each rule in the UniversalIdentity contract</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>users</span><span>[</span><span>user</span><span>]</span><span>.</span><span>userType </span><span class="z-keyword">==</span><span> UserType</span><span>.</span><span>Robot</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> _checkRobotCompliance</span><span>(</span><span>user</span><span>,</span><span> version</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"> If the user is human, compliance is assumed for now (can be extended)</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-storage z-type"> @notice</span><span class="z-comment"> Internal function to check compliance for robots with their rule set version</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 will revert if the robot is not compliant with any rule. Returns true for view purposes.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> robotAddress</span><span class="z-comment"> The address of the robot</span></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 the rule set to verify compliance with</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"> Returns true if the robot is compliant with all the rules in the rule set</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _checkRobotCompliance</span><span>(</span><span class="z-support">address</span><span class="z-variable"> robotAddress</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> version</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> IUniversalIdentity robot </span><span class="z-keyword">=</span><span class="z-entity z-name"> IUniversalIdentity</span><span>(</span><span>robotAddress</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> rules </span><span class="z-keyword">=</span><span> ruleSets</span><span>[</span><span>version</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> rules</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-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>robot</span><span>.</span><span class="z-entity z-name">checkCompliance</span><span>(</span><span>rules</span><span>[</span><span>i</span><span>]</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></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 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-storage z-type"> @notice</span><span class="z-comment"> Updates or defines a new rule set version.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> newRuleSet</span><span class="z-comment"> The array of new individual rules.</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 SHOULD be restricted to authorized users (e.g., contract owner).</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateRuleSet</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"> newRuleSet</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> whenNotPaused</span><span class="z-entity z-name"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>newRuleSet</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Cannot update to an empty rule 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"> Hash the new rule set and ensure it&#39;s not already registered</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> ruleSetHash </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>newRuleSet</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>ruleSetVersions</span><span>[</span><span>ruleSetHash</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Rule set already registered&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"> Increment the version and store the new rule set</span></span> <span class="giallo-l"><span> currentVersion </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> ruleSets</span><span>[</span><span>currentVersion</span><span>]</span><span class="z-keyword"> =</span><span> newRuleSet</span><span>;</span></span> <span class="giallo-l"><span> ruleSetVersions</span><span>[</span><span>ruleSetHash</span><span>]</span><span class="z-keyword"> =</span><span> currentVersion</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"> RuleSetUpdated</span><span>(</span><span>newRuleSet</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Getter for the latest version of the rule set.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getLatestRuleSetVersion</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> currentVersion</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"> @notice</span><span class="z-comment"> Get the rule set for a specific version.</span></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 the rule set to retrieve.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getRuleSet</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> version</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>[</span><span>]</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> ruleSets</span><span>[</span><span>version</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"> @notice</span><span class="z-comment"> Get the version number for a specific rule 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"> ruleSet</span><span class="z-comment"> The hash of the rule set to retrieve the version for.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getRuleSetVersion</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> ruleSet</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> ruleSetVersions</span><span>[</span><span>ruleSet</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"> getUserInfo</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">UserInfo</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> users</span><span>[</span><span>user</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"> @notice</span><span class="z-comment"> Getter for the current paused status.</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"> paused_</span><span class="z-comment"> Whether or not the contract is paused.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> paused</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 class="z-variable"> paused_</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> paused_ </span><span class="z-keyword">=</span><span> systemConfig</span><span>.</span><span class="z-entity z-name">paused</span><span>(</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>Compliance Updater: The compliance updater role in the <code>UniversalIdentity</code> contract is critical for updating compliance statuses (currently limited to the owner). It is essential to ensure secure ownership to minimize the risks of unauthorized or malicious updates.</p> <p>Rule Management: Functions such as addRule, removeRule, and updateCompliance in the <code>UniversalIdentity</code> contract and updateRuleSet in the <code>UniversalCharter</code> contract directly affect rule enforcement. It’s essential to ensure these functions are only callable by authorized users.</p> <p>Upgradeable Contracts: The use of OwnableUpgradeable introduces risks during the initialization and upgrade process. Ensuring that the initialize function is protected against re-execution is critical to avoid reinitialization attacks.</p> <p>Gas Consumption: Excessively large rule sets could lead to high gas costs or DoS risks. Consider setting limits on the number of rules allowed per rule set to maintain gas efficiency and avoid performance issues.</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-26T00:00:00+00:00 2026-02-11T14:48:25+00:00 Marco Stronatihttps://github.com/paracetamolo Jeff Lauhttps://github.com/jefflau https://wg-eips.ritovision.com/7785/

Derive chain identifiers by hashing their chain name and use ENS to map chain names to these identifiers

<h2 id="abstract">Abstract</h2> <p>This ERC proposes to derive chain identifiers as a digest of their chain name (and other information) and to use ENS to map chain names to identifiers in place of the centralized list on GitHub. A solution to support existing chain identifiers that were not derived following this ERC is also proposed.</p> <h2 id="motivation">Motivation</h2> <p>The mapping between chain names and identifiers, such as <code>Mainnet -&gt; 0x1</code>, is currently maintained in a centralized list. However this solution has two main shortcomings:</p> <ul> <li>It does not scale with the growing number of L2s.</li> <li>The list maintainers are a single point of failure.</li> </ul> <p>Desired properties:</p> <ul> <li>the ability to register new chain names and identifiers in a censorship-resistant way</li> <li>the ability to resolve chain names and identifiers in a trustless way</li> <li>maintain a unique mapping between names and identifiers</li> </ul> <h3 id="chain-identifier-spoofing-and-replay-attacks">Chain Identifier Spoofing and Replay Attacks</h3> <p>An important property of the centralized list is that it keeps a one-to-one correspondence between names and identifiers.</p> <p>Without this property, an attacker could register a fresh name pointing to an existing identifier. For example <code>my-testnet</code> could point to mainnet <code>0x1</code>. A user could be tricked into signing a transaction for the innocent looking <code>my-testnet</code> while actually signing a transaction for mainnet, a transaction that the attacker can then replay.</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="extending-chain-identifiers">Extending chain identifiers</h3> <p>Current chain identifiers are usually chosen arbitrarily to be short. While these identifiers are convenient on a small scale, as their number increases it is more desirable to draw them from a larger space.</p> <p>We propose to extend the size of identifiers to 32 bytes and to derive them using a cryptographic hash function. The input to the function MUST contain the chain name and MAY contain additional information.</p> <p>An example for a L2:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>chain_id = Keccak-256(CHAIN_NAME, SETTLEMENT_CHAIN_ID, VERSION, DEPLOYER_CONTRACT_ADDRESS, SALT)</span></span></code></pre> <p>where:</p> <ul> <li><code>SETTLEMENT_CHAIN_ID</code> is the id of the L1 where the L2 settles, it could be Mainnet or a testnet.</li> <li><code>VERSION</code> is to separate the domain of the hash function with an arbitrary string</li> <li><code>DEPLOYER_CONTRACT_ADDRESS</code> is the address of the L2 on the L1</li> </ul> <h3 id="chain-name-resolution">Chain name resolution</h3> <p>Any ENS name can resolve to a chain identifier as specified in <!-- TODO: Is 2304 a sufficient replacement for ENSIP-11? --><a href="https://wg-eips.ritovision.com/2304/">ERC-2304</a>. The name should resolve to a record containing not only the chain identifier, but also all the optional information necessary to verify the identifier.</p> <p>For example the chain name <code>rollup</code> can be converted to a chain identifier on Mainnet by resolving:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>rollup.eth -&gt; {version : uint, bridge : address, chain_id : chain_id}</span></span></code></pre> <p>and then verified using:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>chain_id == hash(&quot;rollup&quot;, 0x1, version, bridge)</span></span></code></pre><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> <p>Existing identifiers, that were not derived using the scheme above, can be supported using a reverse mapping from chain identifiers to chain names, so that one can check for uniqueness.</p> <p>For example the chain name <code>legacy-rollup.eth</code> can be resolved to the chain identifier <code>0x123</code>. Then <code>0x123</code> can be resolved in the <code>chainid.reverse</code> domain to a <code>chain_name</code>. If <code>chain_name == legacy-rollup</code> then the mapping is valid.</p> <h3 id="bootstrapping-and-handover">Bootstrapping and handover</h3> <p>In order to bootstrap the handling of legacy chain identifiers, we imagine the EF populating the <code>chainid.reverse</code> domain, a temporary <code>l2.eth</code> for names and then handing them over.</p> <ul> <li>EF populates two subdomains <code>l2.eth</code> and <code>chainid.reverse</code> using Ethereum lists.</li> <li>A rollup registers a <code>rollup.eth</code> and points it to their `chain_id.</li> <li>EF hands over to the rollup <code>rollup.l2.eth</code> and <code>chain_id.chainid.reverse</code></li> <li>The rollup updates <code>chain_id.chainid.reverse</code> to return <code>rollup.eth</code></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>Domain spoofing can lead to replay attacks as described above and can be eliminated by deriving new identifiers using a hash function and by checking the reverse mapping for legacy identifiers.</p> <p>Domain squatting, the practice of ammassing a large number of domains in the hope to selling them later to legitimate users, is a possibility but with an increasing number of L2 registrations we can expect the same problem to appear in the centralized Github list.</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-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nicolas Deschildrehttps://github.com/nand2 Sam Wilsonhttps://github.com/SamWilsn https://wg-eips.ritovision.com/7774/

Introduce a new HTTP cache control method using EVM events for invalidation

<h2 id="abstract">Abstract</h2> <p>In the context of the <a href="https://wg-eips.ritovision.com/6860/">ERC-6860</a> <code>web3://</code> standard, this ERC extends the <a href="https://wg-eips.ritovision.com/6944/">ERC-6944</a> resolve mode. It introduces mechanisms to address limitations that prevent the use of standard <a rel="external" href="https://www.rfc-editor.org/rfc/rfc9111">RFC 9111</a> HTTP caching.</p> <h2 id="motivation">Motivation</h2> <p>Calls to Ethereum RPC providers are costly—both CPU-wise for local nodes and monetarily for paid external RPC providers. Furthermore, external RPC providers are rate-limited, which can quickly cause disruptions when loading <code>web3://</code> URLs.</p> <p>Therefore, it makes sense to implement caching mechanisms to reduce RPC calls when possible. Since <code>web3://</code> aims to be as close to HTTP as possible, leveraging standard <a rel="external" href="https://www.rfc-editor.org/rfc/rfc9111">RFC 9111</a> HTTP caching is the natural choice. In the <a href="https://wg-eips.ritovision.com/6944/">ERC-6944</a> resolve mode, smart contracts can already return standard HTTP caching headers like <code>Cache-Control</code> and <code>ETag</code>.</p> <p>However, due to the <a href="https://wg-eips.ritovision.com/6944/">ERC-6944</a> resolve mode not forwarding request HTTP headers to the smart contract, smart contracts cannot handle <code>If-None-Match</code> and <code>If-Modified-Since</code> cache validation headers. Consequently, they are limited to using the <code>Cache-control: max-age=XX</code> mechanism, which causes each cache validation request to trigger an RPC call, regenerating the full response.</p> <p>This ERC proposes a solution to bypass this limitation by allowing websites to broadcast cache invalidations via smart contract events.</p> <p>Additionally, even if smart contracts could read request HTTP headers, using smart contract events is more efficient, as it moves cache invalidation logic outside the contract.</p> <p>We add this feature to the <a href="https://wg-eips.ritovision.com/6944/">ERC-6944</a> resolve mode because it can be added without changes to the interface. Future resolve modes that allow for request HTTP headers may also implement this ERC.</p> <h2 id="specification">Specification</h2> <p>This standard introduces the <code>evm-events</code> cache directive for the <code>Cache-Control</code> header of request responses, as an extension directive as defined in section 5.2.3 of <a rel="external" href="https://www.rfc-editor.org/rfc/rfc9111">RFC 9111</a>.</p> <p>When an <a href="https://wg-eips.ritovision.com/6944/">ERC-6944</a> resolve mode website wants to use event-based caching for a request, it MUST:</p> <ul> <li>Include the <code>evm-events</code> directive in the <code>Cache-Control</code> header of the response.</li> <li>Include the <code>ETag</code> and/or <code>Cache-Control</code> headers in the response, as per traditional <a rel="external" href="https://www.rfc-editor.org/rfc/rfc9111">RFC 9111</a> HTTP caching.</li> <li>Emit a cache invalidation event (as defined below) for the path in the smart contract when the output of the response changes and it deems cache clearing necessary.</li> </ul> <p>A value to the <code>evm-events</code> cache directive is optional, and can be used to specify to listen for additional events on other smart contracts, and/or for other paths. The cache directive value syntax in ABNF notation is :</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cache-directive-value = [ address-path-absolute *( &quot; &quot; address-path-absolute ) ]</span></span> <span class="giallo-l"><span>address-path-absolute = [ address ] path-absolute [ &quot;?&quot; query ]</span></span> <span class="giallo-l"><span>address = &quot;0x&quot; 20( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span>path-absolute = &lt;path-absolute, see RFC 3986, Section 3.3&gt;</span></span> <span class="giallo-l"><span>query = &lt;query, see RFC 3986, Section 3.4&gt;</span></span></code></pre> <p><strong>Examples</strong>:</p> <ul> <li><code>Cache-control: evm-events</code> : The cache of the page returning this directive will be cleared when the contract having responded to the request emits a cache clearing event for the path of the page having been served.</li> <li><code>Cache-control: evm-events="/path/path2"</code> : Same behavior than the first example, but additionally the cache of the page returning this directive will be cleared when the contract having responded to the request emits a cache clearing event for path <code>/path/path2</code>.</li> <li><code>Cache-control: evm-events="0xe4ba0e245436b737468c206ab5c8f4950597ab7f/path/path2"</code> : Same behavior than the first example, but additionally the cache of the page returning this directive will be cleared when the contract <code>0xe4ba0e245436b737468c206ab5c8f4950597ab7f</code> emits a cache clearing event for path <code>/path/path2</code>.</li> <li><code>Cache-control: evm-events="0xe4ba0e245436b737468c206ab5c8f4950597ab7f"</code> : Same behavior than the first example, but additionally the cache of the page returning this directive will be cleared when the contract <code>0xe4ba0e245436b737468c206ab5c8f4950597ab7f</code> emits a cache clearing event for the path of the page having been served.</li> <li><code>Cache-control: evm-events="/path/path2 /path/path3"</code> : Same behavior than the first example, but additionally the cache of the page returning this directive will be cleared when the contract having responded to the request emits a cache clearing event for path <code>/path/path2</code> or <code>/path/path3</code>.</li> </ul> <h3 id="cache-invalidation-event">Cache invalidation event</h3> <p>The event is defined as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>event ClearPathCache(string[] paths);</span></span></code></pre> <p>This event clears the cache for an array of <code>paths</code>. Each <code>path</code> refers to the <code>pathQuery</code> part of the ABNF definition in <a href="https://wg-eips.ritovision.com/6860/">ERC-6860</a>.</p> <ul> <li>A <code>path</code> MUST NOT end with a <code>/</code>, except when the whole path is the root path, which is <code>/</code>.</li> <li>Two <code>paths</code> are considered identical if they have the same <a href="https://wg-eips.ritovision.com/5219/">ERC-5219</a> resource entries and their parameter values match, regardless of the order.</li> </ul> <p><strong>Example</strong>:</p> <ul> <li><code>/test?a=1&amp;b=2</code> and <code>/test?b=2&amp;a=1</code> are considered identical.</li> </ul> <h4 id="wildcard-usage">Wildcard usage</h4> <p><code>paths</code> may contain <code>*</code> wildcards, with the following rules:</p> <ol> <li> <p><strong>Wildcards in Resource Entries</strong>:</p> <ul> <li> <p>A wildcard (<code>*</code>) can be used on its own in an <a href="https://wg-eips.ritovision.com/5219/">ERC-5219</a> resource entry.</p> </li> <li> <p>A wildcard CANNOT be combined with other characters in the same entry; if it is, the <code>path</code> will be ignored.</p> </li> <li> <p>A wildcard requires at least one character to match. <strong>Examples</strong>:</p> </li> <li> <p><code>/*</code> will match <code>/test</code> but not <code>/test/abc</code> and not <code>/</code>.</p> </li> <li> <p><code>/test/*</code> will match <code>/test/abc</code> but will not match <code>/test/</code> or <code>/test/abc/def</code>.</p> </li> <li> <p><code>/*/abc</code> will match <code>/test/abc</code>, but not <code>//abc</code>.</p> </li> <li> <p><code>/t*t</code> is invalid, so the <code>path</code> will be ignored.</p> </li> </ul> </li> <li> <p><strong>Wildcards in Parameter Values</strong>:</p> <ul> <li> <p>A wildcard can be used alone as a parameter value.</p> </li> <li> <p>A wildcard CANNOT be combined with other characters in the parameter value, or the <code>path</code> will be ignored.</p> </li> <li> <p>A wildcard in parameter values requires at least one character to match. <strong>Examples</strong>:</p> </li> <li> <p><code>/abc?a=*</code> will match <code>/abc?a=zz</code> but not <code>/abc?a=</code> or <code>/abc?a=zz&amp;b=cc</code>.</p> </li> <li> <p><code>/abc?a=*&amp;b=*</code> will match <code>/abc?a=1&amp;b=2</code> and <code>/abc?b=2&amp;a=1</code>.</p> </li> <li> <p><code>/abc?a=z*</code> is invalid, so the <code>path</code> will be ignored.</p> </li> </ul> </li> <li> <p><strong>Special Case: Global Wildcard</strong>:</p> <ul> <li>A <code>path</code> containing only a <code>*</code> will match every path within the smart contract.</li> </ul> </li> </ol> <p>Wildcards are intentionally limited to these simple cases to facilitate efficient path lookup implementations.</p> <h3 id="caching-behavior">Caching behavior</h3> <h4 id="cache-invalidation-states-for-web3-clients">Cache Invalidation States for <code>web3://</code> Clients</h4> <p>A <code>web3://</code> client can be in one of two cache invalidation states for each chain and smart contract:</p> <ol> <li> <p><strong>Listening for Events</strong>:<br /> The <code>web3://</code> client MUST listen for the cache invalidation events defined earlier and should aim to stay as close to real-time as possible.</p> </li> <li> <p><strong>Not Listening for Events</strong>:<br /> This is the default state when this ERC is not implemented. In this state, the <code>web3://</code> client ignores all HTTP caching validation requests (e.g., <code>If-None-Match</code>, <code>If-Modified-Since</code> request headers).</p> </li> </ol> <p>The <code>web3://</code> client can switch between these states at any time and MAY implement heuristics to optimize the use of RPC providers by switching states as appropriate.</p> <h4 id="cache-key-value-mapping">Cache Key-Value Mapping</h4> <p>The <code>web3://</code> client maintains a key-value mapping for caching, which MUST be cleared whenever it transitions from "Listening for Events" to "Not Listening for Events." The mapping is structured as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>mapping(</span></span> <span class="giallo-l"><span> (&lt;chain id&gt;, &lt;contract address&gt;, &lt;ERC-6860 pathQuery&gt;) </span></span> <span class="giallo-l"><span> =&gt; </span></span> <span class="giallo-l"><span> (&lt;last modified date&gt;, &lt;ETag&gt;)</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>Additional elements can be included in the mapping key when necessary. For example, <a href="https://wg-eips.ritovision.com/7618/">ERC-7618</a> requires the inclusion of the <code>Accept-Encoding</code> request header in the mapping key.</p> <h4 id="handling-requests-in-listening-for-events-state">Handling Requests in "Listening for Events" State</h4> <p>When a request is received in the "Listening for Events" state:</p> <ol> <li> <p><strong>If no mapping entry exists</strong>:</p> <ul> <li>The <code>web3://</code> client queries the smart contract.</li> <li>If the response includes the <code>evm-events</code> directive in the <code>Cache-Control</code> header and an <code>ETag</code>, a mapping entry is created using the <code>ETag</code>.</li> <li>If the response contains the <code>evm-events</code> directive and a <code>max-age=XX</code> directive in the <code>Cache-Control</code> header, the mapping entry is created with the <code>last modified date</code>, determined in the following order of priority: <ul> <li>The <code>Last-Modified</code> header, if present.</li> <li>The <code>Date</code> header, if present.</li> <li>Otherwise, the block date when the smart contract was queried.</li> </ul> </li> <li>If the response includes both an <code>ETag</code> and a <code>Cache-Control: evm-events max-age=XX</code> directive, a single mapping entry is created containing both the <code>ETag</code> and the <code>last modified date</code>.</li> </ul> </li> <li> <p><strong>If a mapping entry exists</strong>:</p> <ul> <li> <p>If the request contains a valid <code>If-None-Match</code> header:</p> <ul> <li>If the <code>ETag</code> in the mapping matches the <code>If-None-Match</code> value, the <code>web3://</code> client returns a <code>304 Not Modified</code> response immediately.</li> <li>If the <code>ETag</code> does not match, the client queries the smart contract, deletes the mapping entry, and processes the request as if no mapping entry existed.</li> </ul> </li> <li> <p>If the request contains a valid <code>If-Modified-Since</code> header:</p> <ul> <li>If the <code>last modified date</code> in the mapping is earlier than the <code>If-Modified-Since</code> date, the client returns a <code>304 Not Modified</code> response immediately.</li> <li>Otherwise, the client queries the smart contract, deletes the mapping entry, and processes the request as if no mapping entry existed.</li> </ul> </li> <li> <p>If the request contains neither <code>If-None-Match</code> nor <code>If-Modified-Since</code> headers (or they are invalid):</p> <ul> <li>The client queries the smart contract, deletes the mapping entry, and processes the request as if no mapping entry existed.</li> </ul> </li> </ul> </li> </ol> <h4 id="cache-invalidation-via-blockchain-events">Cache Invalidation via Blockchain Events</h4> <p>In the "Listening for Events" state, the <code>web3://</code> client listens to the blockchain for the cache invalidation events defined in the previous section. For each path match, it deletes the corresponding mapping entry.</p> <h2 id="rationale">Rationale</h2> <p>To stay as close as possible to standard HTTP, we reuse the HTTP caching mechanism headers.</p> <p>The use of the <code>evm-events</code> directive is necessary to avoid a situation where a website uses traditional <a rel="external" href="https://www.rfc-editor.org/rfc/rfc9111">RFC 9111</a> HTTP caching headers, but the contract does not implement this ERC by failing to emit the events. In such cases, <code>web3://</code> clients implementing this ERC would serve stale content for that website indefinitely.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Stale content will be served during the delay between a user transaction emitting a cache clearing event, and the <code>web3://</code> client picking and processing the event.</p> <p>For each cached page, websites must properly implement cache invalidation events; otherwise, stale content will be served indefinitely.</p> <p>In the event of a chain reorganization, the <code>web3://</code> client must roll back its caching state, or reverted content will be served until the next cache clearing event.</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-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ignacio Ceagliohttps://github.com/Nachoxt17ignacioceaglio@gmail.com https://wg-eips.ritovision.com/7776/

Open Transparent Financial Data such as Revenue, Costs of Goods Sold, Operating Expenses, EBITDA and Earnings Per Share for all Investors.

<h2 id="abstract">Abstract</h2> <p>This proposal defines a standard API that enables EVM Blockchain-based companies (or also called "protocols") to publish their financial information, specifically Income Statements and Balance Sheets, on- chain in a transparent and accessible manner through solidity smart contracts. This standard aims to emulate the reporting structure used by publicly traded companies in traditional stocks markets, like the SEC 10-Q filings. The financial statements include key information, namely as Revenue, Cost of Goods Sold, Operating Expenses, Operating Income, Earnings before Interest, Taxes, Depreciation, and Amortization (EBITDA) and Earnings Per Share-Token (EPS), allowing investors to assess the financial health of blockchain-based companies in a standardized, transparent, clear and reliable format.</p> <h2 id="motivation">Motivation</h2> <p>The motivation of this ERC is to bring seriousness to the cryptocurrencies investments market. Currently, the situation is as follows:</p> <p>The current state of token investment analysis is opaque, with most information presented in an abstract and non-quantitative form. This standard API ensures a consistent and reliable way for investors to evaluate blockchain projects based on real financial data published directly on-chain, not just speculative promises. This will establish a greater trust in the cryptocurrency markets and align token analysis with the standards of traditional equity markets.</p> <p>Most <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> Tokens representing EVM Blockchain-based companies (or also called "protocols"), DO NOT work the same way as a publicly traded stock that represents a share of ownership of the equity of that such company (so the user who buys a protocol's ERC-20, is also now a share-holder and co-owner of the business, its profits and/or its dividends), but rather function as "commodities" such as oil; they are consumable items created by said EVM Blockchain-based company (or "protocol") to be spent in their platform. They are publicly traded and advertised to be representing the underlying protocol like a share, working in practice the same way as a commodity and without any public, transparent and <em>Clear</em> Financial Information as publicly traded stocks have.</p> <p>Added to that, most token research analysis reports that can be currently found on the internet are informal Substack or Twitter posts, with lots of abstract explanations about the features of the said protocol to invest in, that lack of transparent financial numbers and factual financial information, that are made by anonymous users without real exposed reputations to affect.</p> <p>This ERC will improve that by giving users and investors transparent, clear and factual financial information to work with when analyzing as a potential investment the such EVM Blockchain-based company that implements this ERC in their solidity smart contracts, and that will generate trust, transparency and seriousness in the cryptocurrencies investments market long term.</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 Transparent Financial Statements Standard implementations MUST implement ERC-20 to represent shares, and the financial numbers such as Revenue, Costs of Goods Sold, Operating Expenses, Operating Income, EBITDA, Other Income and Expenses, Net Income and Earnings Per Share MUST be displayed in the value of the protocol's stablecoin of choice.</p> <p>All Transparent Financial Statements MUST implement ERC-20'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.</p> <p>All methods MUST be of visibility <code>external</code>.</p> <p>All methods MUST return their financial numbers valued in the provided <code>stablecoin</code>.</p> <p>If the contract owner uses data or methods from other owned smart contracts external to their smart contract implementation of this standard, those smart contracts MUST be verified in the correspondent blockchain explorer and of open and visible source code.</p> <p><em>Timestamp Constraint</em>: For all methods, <code>startTimestamp</code> MUST be less than or equal to <code>endTimestamp</code>. If <code>startTimestamp</code> is equal to <code>endTimestamp</code>, the method returns a balance sheet snapshot. If <code>startTimestamp</code> is less than <code>endTimestamp</code>, the method returns an income statement for that period.</p> <p><em>Output Structs</em>: Instead of a single <code>uint256</code> value, each method returns a <code>struct</code> with one or <em>OPTIONAL</em> more <code>uint256</code> entries to allow for detailed financial data, each one with their own customized entry <code>name</code>.</p> <h3 id="definitions">Definitions</h3> <ul> <li>Currency: The individual stablecoin used to value the publicly displayed financial numbers.</li> <li>Revenue: Total earnings from selling products or services before expenses.</li> <li>Cost of Goods Sold (COGS): Direct costs for producing goods/services, including labor and materials.</li> <li>Operating Expenses: Expenses like Selling, General, and Administrative, Research and Development, and other operational costs.</li> <li>Operating Income: Revenue minus operating expenses.</li> <li>EBITDA: Earnings Before Interest, Taxes, Depreciation, and Amortization.</li> <li>Other Income and Expenses: Non-operating income, such as interest, investment gains or losses.</li> <li>Net Income: Profit after all expenses, taxes, and deductions.</li> <li>EPS: Earnings per Share Token (ERC-20), showing profit allocated per share.</li> </ul> <h3 id="methods">Methods</h3> <h4 id="stablecoinaddress"><code>stablecoinAddress</code></h4> <p>Returns the <code>address</code> of the individual stablecoin used to value the publicly displayed financial numbers.</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"> s</span><span class="z-string">tablecoinAddress</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"> v</span><span class="z-entity z-name z-tag">isibility</span><span>:</span><span class="z-string"> e</span><span class="z-string">xternal</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"> 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"> c</span><span class="z-string">urrencyAddress</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></code></pre><h4 id="revenue"><code>revenue</code></h4> <p>Returns total revenue generated by the protocol within a time period.</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">evenue</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"> v</span><span class="z-entity z-name z-tag">isibility</span><span>:</span><span class="z-string"> e</span><span class="z-string">xternal</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"> s</span><span class="z-string">tartTimestamp</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">ndTimestamp</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"> R</span><span class="z-string">evenueStruct</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">truct</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> f</span><span class="z-entity z-name z-tag">ields</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"> g</span><span class="z-string">rossRevenue</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"> o</span><span class="z-string">ptionalAdditionalRevenueDetail1</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"> o</span><span class="z-string">ptionalAdditionalRevenueDetailN</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></code></pre><h4 id="cogs"><code>cogs</code></h4> <p>Returns the cost of goods sold within a specified period.</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">ogs</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"> v</span><span class="z-entity z-name z-tag">isibility</span><span>:</span><span class="z-string"> e</span><span class="z-string">xternal</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"> s</span><span class="z-string">tartTimestamp</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">ndTimestamp</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"> C</span><span class="z-string">OGSStruct</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">truct</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> f</span><span class="z-entity z-name z-tag">ields</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">otalCOGS</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"> o</span><span class="z-string">ptionalAdditionalCOGSDetail1</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"> o</span><span class="z-string">ptionalAdditionalCOGSDetailN</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></code></pre><h4 id="operatingexpenses"><code>operatingExpenses</code></h4> <p>Returns the total operating expenses within a specified period.</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"> o</span><span class="z-string">peratingExpenses</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"> v</span><span class="z-entity z-name z-tag">isibility</span><span>:</span><span class="z-string"> e</span><span class="z-string">xternal</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"> s</span><span class="z-string">tartTimestamp</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">ndTimestamp</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"> O</span><span class="z-string">peratingExpensesStruct</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">truct</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> f</span><span class="z-entity z-name z-tag">ields</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">otalOperatingExpenses</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"> o</span><span class="z-string">ptionalAdditionalExpenseDetail1</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"> o</span><span class="z-string">ptionalAdditionalExpenseDetailN</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></code></pre><h4 id="operatingincome"><code>operatingIncome</code></h4> <p>Returns operating income for the specified period (Revenue - COGS - Operating Expenses).</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"> o</span><span class="z-string">peratingIncome</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"> v</span><span class="z-entity z-name z-tag">isibility</span><span>:</span><span class="z-string"> e</span><span class="z-string">xternal</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"> s</span><span class="z-string">tartTimestamp</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">ndTimestamp</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"> O</span><span class="z-string">peratingIncomeStruct</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">truct</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> f</span><span class="z-entity z-name z-tag">ields</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">otalOperatingIncome</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"> o</span><span class="z-string">ptionalAdditionalIncomeDetail1</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"> o</span><span class="z-string">ptionalAdditionalIncomeDetailN</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></code></pre><h4 id="ebitda"><code>ebitda</code></h4> <p>Returns EBITDA for the given period.</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"> e</span><span class="z-string">bitda</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"> v</span><span class="z-entity z-name z-tag">isibility</span><span>:</span><span class="z-string"> e</span><span class="z-string">xternal</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"> s</span><span class="z-string">tartTimestamp</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">ndTimestamp</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"> E</span><span class="z-string">BITDAstruct</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">truct</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> f</span><span class="z-entity z-name z-tag">ields</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">otalEBITDA</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"> o</span><span class="z-string">ptionalAdditionalEBITDADetail1</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"> o</span><span class="z-string">ptionalAdditionalEBITDADetailN</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></code></pre><h4 id="otherincomeexpenses"><code>otherIncomeExpenses</code></h4> <p>Returns non-operating income and expenses, such as interest and investment gains or losses, for the specified period.</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"> o</span><span class="z-string">therIncomeExpenses</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"> v</span><span class="z-entity z-name z-tag">isibility</span><span>:</span><span class="z-string"> e</span><span class="z-string">xternal</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"> s</span><span class="z-string">tartTimestamp</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">ndTimestamp</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"> O</span><span class="z-string">therIncomeExpensesStruct</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">truct</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> f</span><span class="z-entity z-name z-tag">ields</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">otalOtherIncome</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">otalOtherExpenses</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">otalOtherIncomeDetail1</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">otalOtherExpensesDetail1</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">otalOtherIncomeDetailN</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">otalOtherExpensesDetailN</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></code></pre><h4 id="netincome"><code>netIncome</code></h4> <p>Returns net income for the period (Operating Income + Other Income/Expenses - Taxes - Depreciation).</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">etIncome</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"> v</span><span class="z-entity z-name z-tag">isibility</span><span>:</span><span class="z-string"> e</span><span class="z-string">xternal</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"> s</span><span class="z-string">tartTimestamp</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">ndTimestamp</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"> N</span><span class="z-string">etIncomeStruct</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">truct</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> f</span><span class="z-entity z-name z-tag">ields</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">otalNetIncome</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"> o</span><span class="z-string">ptionalAdditionalNetIncomeDetail1</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"> o</span><span class="z-string">ptionalAdditionalNetIncomeDetailN</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></code></pre><h4 id="earningspershare"><code>earningsPerShare</code></h4> <p>Returns Earnings Per Share Token (EPS) for the period.</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"> e</span><span class="z-string">arningsPerShare</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"> v</span><span class="z-entity z-name z-tag">isibility</span><span>:</span><span class="z-string"> e</span><span class="z-string">xternal</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"> s</span><span class="z-string">tartTimestamp</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">ndTimestamp</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"> E</span><span class="z-string">PSstruct</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">truct</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> f</span><span class="z-entity z-name z-tag">ields</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"> b</span><span class="z-string">asicEPS</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">ilutedEPS</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">PSDetail1</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">PSDetailN</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></code></pre><h4 id="fullfinancialreport"><code>fullFinancialReport</code></h4> <p>Returns a comprehensive struct that includes all the prior financial details of the protocol combined: Revenue, COGS, Operating Expenses, Operating Income, EBITDA, Other Incomes and Expenses, Net income, and EPS into a unified <code>Struct</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"> f</span><span class="z-string">ullFinancialReport</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"> v</span><span class="z-entity z-name z-tag">isibility</span><span>:</span><span class="z-string"> e</span><span class="z-string">xternal</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"> s</span><span class="z-string">tartTimestamp</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">ndTimestamp</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"> F</span><span class="z-string">ullFinancialsStruct</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">truct</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> f</span><span class="z-entity z-name z-tag">ields</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">evenueStruct</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">truct</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">OGSStruct</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">truct</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">peratingExpensesStruct</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">truct</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">peratingIncomeStruct</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">truct</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">BITDAstruct</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">truct</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">therIncomeExpensesStruct</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">truct</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">etIncomeStruct</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">truct</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">PSstruct</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">truct</span></span> <span class="giallo-l"></span></code></pre><h2 id="rationale">Rationale</h2> <p>ERC-20 is enforced because implementation details like Earnings Per Token calculation directly carry over to the accounting. This standardization makes the Transparent Financial Statements compatible with all ERC-20 use cases.</p> <p>This implementation enables the protocol to share their financial information both as their latest updated Balance Sheet (if the user chooses to just see a current snapshot of the financial state of the company) and as an Income Statement (if the user chooses to see the evolution of the financial state of the company between two different block timestamps) and also is thought to interact with other separated Smart Contracts of the same protocol from which the financial information will be sent.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Transparent Financial Statements Standard is fully backward compatible with the ERC-20 standard and has no known compatibility issues with other 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"> 0.8.27</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"> IERC20</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> <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"> TransparentFinancialStatements</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"> public</span><span> stablecoin</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"> RevenueStruct</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> grossRevenue</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> optionalAdditionalRevenueDetail1</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> optionalAdditionalRevenueDetailN</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"> COGSStruct</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> totalCOGS</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> optionalAdditionalCOGSDetail1</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> optionalAdditionalCOGSDetailN</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"> OperatingExpensesStruct</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> totalOperatingExpenses</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> optionalAdditionalExpenseDetail1</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> optionalAdditionalExpenseDetailN</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"> OperatingIncomeStruct</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> totalOperatingIncome</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> optionalAdditionalIncomeDetail1</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> optionalAdditionalIncomeDetailN</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"> EBITDAstruct</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> totalEBITDA</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> optionalAdditionalEBITDADetail1</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> optionalAdditionalEBITDADetailN</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"> OtherIncomeExpensesStruct</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> totalOtherIncome</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> totalOtherExpenses</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> totalOtherIncomeDetail1</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> totalOtherExpensesDetail1</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> totalOtherIncomeDetailN</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> totalOtherExpensesDetailN</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"> NetIncomeStruct</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> totalNetIncome</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> optionalAdditionalNetIncomeDetail1</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> optionalAdditionalNetIncomeDetailN</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"> EPSstruct</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> basicEPS</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> dilutedEPS</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> EPSDetail1</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> EPSDetailN</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"> FullFinancialsStruct</span><span> {</span></span> <span class="giallo-l"><span> RevenueStruct revenue</span><span>;</span></span> <span class="giallo-l"><span> COGSStruct cogs</span><span>;</span></span> <span class="giallo-l"><span> OperatingExpensesStruct operatingExpenses</span><span>;</span></span> <span class="giallo-l"><span> OperatingIncomeStruct operatingIncome</span><span>;</span></span> <span class="giallo-l"><span> EBITDAstruct ebitda</span><span>;</span></span> <span class="giallo-l"><span> OtherIncomeExpensesStruct otherIncomeExpenses</span><span>;</span></span> <span class="giallo-l"><span> NetIncomeStruct netIncome</span><span>;</span></span> <span class="giallo-l"><span> EPSstruct eps</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 class="z-support">address</span><span class="z-variable z-parameter z-function"> _stablecoin</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> stablecoin </span><span class="z-keyword">=</span><span> _stablecoin</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"> currency</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-keyword"> return</span><span> stablecoin</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"> revenue</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> startTimestamp</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> endTimestamp</span><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 class="z-storage z-type">RevenueStruct</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-keyword"> require</span><span>(</span><span>startTimestamp </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> endTimestamp</span><span>,</span><span class="z-string"> &quot;Invalid timestamps&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Logic to calculate and return revenue details</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> RevenueStruct</span><span>(</span><span class="z-constant">1000</span><span>,</span><span class="z-constant"> 500</span><span>,</span><span class="z-constant"> 100</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Example values</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"> cogs</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> startTimestamp</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> endTimestamp</span><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 class="z-storage z-type">COGSStruct</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-keyword"> require</span><span>(</span><span>startTimestamp </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> endTimestamp</span><span>,</span><span class="z-string"> &quot;Invalid timestamps&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Logic to calculate and return COGS details</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> COGSStruct</span><span>(</span><span class="z-constant">400</span><span>,</span><span class="z-constant"> 150</span><span>,</span><span class="z-constant"> 50</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Example values</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"> operatingExpenses</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> startTimestamp</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> endTimestamp</span><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 class="z-storage z-type">OperatingExpensesStruct</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-keyword"> require</span><span>(</span><span>startTimestamp </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> endTimestamp</span><span>,</span><span class="z-string"> &quot;Invalid timestamps&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Logic to calculate and return operating expenses details</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> OperatingExpensesStruct</span><span>(</span><span class="z-constant">300</span><span>,</span><span class="z-constant"> 100</span><span>,</span><span class="z-constant"> 50</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Example values</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"> operatingIncome</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> startTimestamp</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> endTimestamp</span><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 class="z-storage z-type">OperatingIncomeStruct</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-keyword"> require</span><span>(</span><span>startTimestamp </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> endTimestamp</span><span>,</span><span class="z-string"> &quot;Invalid timestamps&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Logic to calculate and return operating income details</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> OperatingIncomeStruct</span><span>(</span><span class="z-constant">300</span><span>,</span><span class="z-constant"> 100</span><span>,</span><span class="z-constant"> 50</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Example values</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"> ebitda</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> startTimestamp</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> endTimestamp</span><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 class="z-storage z-type">EBITDAstruct</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-keyword"> require</span><span>(</span><span>startTimestamp </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> endTimestamp</span><span>,</span><span class="z-string"> &quot;Invalid timestamps&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Logic to calculate and return EBITDA details</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> EBITDAstruct</span><span>(</span><span class="z-constant">700</span><span>,</span><span class="z-constant"> 200</span><span>,</span><span class="z-constant"> 100</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Example values</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"> otherIncomeExpenses</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> startTimestamp</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> endTimestamp</span><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 class="z-storage z-type">OtherIncomeExpensesStruct</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-keyword"> require</span><span>(</span><span>startTimestamp </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> endTimestamp</span><span>,</span><span class="z-string"> &quot;Invalid timestamps&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Logic to calculate and return other income/expenses details</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> OtherIncomeExpensesStruct</span><span>(</span><span class="z-constant">100</span><span>,</span><span class="z-constant"> 50</span><span>,</span><span class="z-constant"> 20</span><span>,</span><span class="z-constant"> 10</span><span>,</span><span class="z-constant"> 30</span><span>,</span><span class="z-constant"> 20</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Example values</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"> netIncome</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> startTimestamp</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> endTimestamp</span><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 class="z-storage z-type">NetIncomeStruct</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-keyword"> require</span><span>(</span><span>startTimestamp </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> endTimestamp</span><span>,</span><span class="z-string"> &quot;Invalid timestamps&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Logic to calculate and return net income details</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> NetIncomeStruct</span><span>(</span><span class="z-constant">600</span><span>,</span><span class="z-constant"> 200</span><span>,</span><span class="z-constant"> 100</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Example values</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"> earningsPerShare</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> startTimestamp</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> endTimestamp</span><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 class="z-storage z-type">EPSstruct</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-keyword"> require</span><span>(</span><span>startTimestamp </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> endTimestamp</span><span>,</span><span class="z-string"> &quot;Invalid timestamps&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Logic to calculate and return EPS details</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> EPSstruct</span><span>(</span><span class="z-constant">10</span><span>,</span><span class="z-constant"> 8</span><span>,</span><span class="z-constant"> 2</span><span>,</span><span class="z-constant"> 1</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Example values</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"> fullFinancialReport</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> startTimestamp</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> endTimestamp</span><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 class="z-storage z-type">FullFinancialsStruct</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-keyword"> require</span><span>(</span><span>startTimestamp </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> endTimestamp</span><span>,</span><span class="z-string"> &quot;Invalid timestamps&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Logic to calculate and return all financial details</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> FullFinancialsStruct</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> revenue</span><span>(</span><span>startTimestamp</span><span>,</span><span> endTimestamp</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> cogs</span><span>(</span><span>startTimestamp</span><span>,</span><span> endTimestamp</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> operatingExpenses</span><span>(</span><span>startTimestamp</span><span>,</span><span> endTimestamp</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> operatingIncome</span><span>(</span><span>startTimestamp</span><span>,</span><span> endTimestamp</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> ebitda</span><span>(</span><span>startTimestamp</span><span>,</span><span> endTimestamp</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> otherIncomeExpenses</span><span>(</span><span>startTimestamp</span><span>,</span><span> endTimestamp</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> netIncome</span><span>(</span><span>startTimestamp</span><span>,</span><span> endTimestamp</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> earningsPerShare</span><span>(</span><span>startTimestamp</span><span>,</span><span> endTimestamp</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></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>This ERC involves displaying critical financial data on-chain, so special attention must be paid to ensure the accuracy and security of the data, particularly in preventing tampering or manipulation of key financial figures.</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-17T00:00:00+00:00 2026-02-11T14:48:25+00:00 Yaron Velnerhttps://github.com/yaronvel https://wg-eips.ritovision.com/7770/

An interface for tokens that maintain a peg to an underlying token while being only partially redeemable to this token.

<h2 id="abstract">Abstract</h2> <p>We propose a new token standard for synthetic assets that are only partially redeemable to their underlying asset, but fully backed by other collateral assets.</p> <p>The standard defines an interface to mint fractional reserve assets, and a standard to reflect economic risk related data to the token holders and lenders.</p> <h2 id="motivation">Motivation</h2> <p>The Cambrian explosion of new L1s and L2s gave rise to bridged assets which are synthetic by nature. Indeed, ETH on Arbitrum L2, or WETH on Binance Smart Chain are not fully fungible with their mainnet counterpart. However, these assets are fully backed by their mainnet counterpart and guaranteed to be redeemable to their mainnet underlying asset, albeit with certain time delay.</p> <p>Fractional reserve tokens can allow an ecosystem (chains, L2s, and other networks of economic activity) to increase its supply by allowing users to mint the asset not only by bridging it to the ecosystem, but also by borrowing it (typically against a collateral).</p> <p>As an example, consider a fractional reserve token, namely, frDAI, that represents a synthetic DAI. Such token will allow users to mint 1 frDAI upon deposit of 1 DAI, or by providing a collateral that worth more than 1 DAI. Quick redemption of frDAI to DAI is available as long as there is still some DAI balance in the frDAI token, and otherwise, the price of frDAI may temporarily fluctuate until borrowers repay their debt.</p> <p>Fractional reserve tokens may delegate minting capabilities for multiple risk curators and lending markets. Hence, a uniform standard for fractional reserve minting is needed. Fractional reserve banking does not come without risks, such as insolvency or a bank run. This standard does not aim to dictate economic risk management practices, but rather to have a standard on how to reflect the risk to token holders.</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. The standard has the following requirements:</p> <ul> <li><strong>MUST</strong> be <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> compatible.</li> </ul> <h3 id="interface">Interface</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>interface IERCXXX is IERC20 {</span></span> <span class="giallo-l"><span> // events</span></span> <span class="giallo-l"><span> event MintFractionalReserve(address indexed minter, address to, uint256 amount);</span></span> <span class="giallo-l"><span> event BurnFractionalReserve(address indexed burner, address from, uint256 amount);</span></span> <span class="giallo-l"><span> event SetSegregatedAccount(address account, bool segregated);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // functions</span></span> <span class="giallo-l"><span> // setters</span></span> <span class="giallo-l"><span> function fractionalReserveMint(address _to, uint256 _amount) external;</span></span> <span class="giallo-l"><span> function fractionalReserveBurn(address _from, uint256 _amount) external;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> // getters</span></span> <span class="giallo-l"><span> function totalBorrowedSupply() external view returns (uint256);</span></span> <span class="giallo-l"><span> function requiredReserveRatio() external view returns (uint256);</span></span> <span class="giallo-l"><span> function segregatedAccount(address _account) external view returns (bool);</span></span> <span class="giallo-l"><span> function totalSegregatedSupply() external view returns (uint256);</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="reserve-ratio">Reserve ratio</h3> <p>The reserve ratio reflects the ratio between the token that is available as cash, i.e., available for an immediate redemption (or alternatively, a token that was not minted via a fractional reserve minting), and the total supply of the token. Segregated accounts <strong>MUST</strong> be subtracted from the cash balance.</p> <p>Formally, the reserve ratio is denoted by $$\frac{totalSupply() - totalBorrowedSupply() - \sum_{a \in \text{Segregated Accounts}} \text{balanceOf}(a)}{totalSupply()}$$. Additional fractional reserve minting <strong>MUST NOT</strong> occur when the reserve ratio, multiplied by <code>1e18</code> is lower than <code>requiredReserveRatio()</code>.</p> <h3 id="mint-and-burn-functionality">Mint and burn functionality</h3> <p>The <code>fractionalReserveMint</code> and <code>fractionalReserveBurn</code> functions <strong>SHOULD</strong> be called by permissioned addresses, e.g., risk curators or lending markets. These entities <strong>SHOULD</strong> mint new tokens only to addresses that already locked collateral in a dedicated contract.</p> <p>The reserve ratio is denoted by $$\frac{totalSupply() - \sum_{a \in \text{Segregated Accounts}} \text{balanceOf}(a)}{totalSupply() + totalBorrowedSupply()}$$. <code>fractionalReserveMint</code> <strong>MUST</strong> revert if the reserve ratio, multiplied by <code>e18</code> exceeds <code>requiredReserveRatio()</code>.</p> <p>A successful call to <code>fractionalReserveMint(_to, _amount)</code> <strong>MUST</strong> increase the value of <code>totalSupply()</code>, <code>totalBorrowedSupply()</code>, and the token balance of address <code>_to</code>, by <code>_amount</code> units. A call to <code>fractionalReserveMint</code> <strong>MUST</strong> emit a <code>MintFractionalReserve</code> event. A call to <code>fractionalReserveMint</code> <strong>MUST</strong> revert if after the mint the reserve ratio, multiplied by <code>1e18</code> exceeds the value of <code>requiredReserveRatio()</code>.</p> <p>Similarly, a successful call to <code>fractionalReserveBurn(_from, _amount)</code> <strong>MUST</strong> decrease the value of <code>totalSupply()</code>,<code>totalBorrowedSupply()</code>, and the token balance of address <code>_from</code> by <code>_amount</code> units. A call to <code>fractionalReserveBurn</code> <strong>MUST</strong> emit a <code>BurnFractionalReserve</code> event.</p> <h3 id="segregated-accounts">Segregated accounts</h3> <p>At every point in time, it <strong>MUST</strong> hold that the sum of token balances for segregated addresses equals to <code>totalSegregatedSupply()</code>.</p> <h3 id="account-balance">Account balance</h3> <p>The <code>fractionalReserveMint</code> <strong>SHOULD</strong> be used in conjunction with a lending operation, where the minted token is borrowed. The lending operation <strong>SHOULD</strong> come with an interest rate, and some of the interest rate proceedings <strong>SHOULD</strong> be distributed to token holders that are not in segregated accounts. This standard does not dictate how distribution should occur.</p> <h2 id="rationale">Rationale</h2> <p>The standard aims to standardise how multiple lending markets and risk providers can interact with a fractional reserve token. The actual lending operation should be done carefully by trusted entities, and it is the token owner's responsibility to make sure the parties who have fractional reserve minting credentials are reliable.</p> <p>At the core of the coordination relies the need to understand how much additional supply is available for borrow, and at what interest rate. The additional borrowable supply is deduced from the required reserve ratio, and the total, borrowable and segregated supply. Lower reserve ratio gives rise to higher capital efficiency, however it increases the <strong>likelihood</strong> of depeg or a run on the bank, where token holders cannot immediately redeem their synthetic token. Having the reserve ratio as part of the standard allows risk curators to better price the risk, and, e.g., set the interest rate to be monotonically increasing with the current reserve ratio.</p> <p>The standard does not dictate how the accrued interest rate is distributed. One possible distribution is by making the token a rebased token. An alternative way is to introduce staking, or just airdropping of proceeds.</p> <p>While a fractional reserve is most useful when it is backed by a known asset, e.g., frDAI and DAI, it can also be used in isolation. In such a case, a token will have a fixed initial supply, however additional supply can be borrowed. In such cases the supply temporarily increases, but the net holdings (<code>totalSupply() - totalBorrowedSupply()</code>) remains unchanged.</p> <p>Increasing the total supply could be a concern if a token is used for DAO votes and/or if dividends are distributed to token holders. In order to mitigate such concerns, segregated accounts are introduced, with the premise that money in these accounts is not counted towards the reserve, and therefore, additional token supply cannot be minted against them.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Fractional reserve tokens should be backwards compatible with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// The code below is provided only for illustration, DO NOT use it in production</span></span> <span class="giallo-l"><span>contract FractionalReserveToken is ERC20, Ownable {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> event MintFractionalReserve(address indexed minter, address to, uint256 amount);</span></span> <span class="giallo-l"><span> event BurnFractionalReserve(address indexed burner, address from, uint256 amount);</span></span> <span class="giallo-l"><span> event SetSegregatedAccount(address account, bool segregated);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice token supply in these accounts is not counted towards the reserve, and</span></span> <span class="giallo-l"><span> /// therefore, additional token supply cannot be minted against them.</span></span> <span class="giallo-l"><span> mapping(address =&gt; bool) public segregatedAccount;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice ratio between the token that is available as cash (immediate redemption)</span></span> <span class="giallo-l"><span> /// and the total supply of the token.</span></span> <span class="giallo-l"><span> uint256 public requiredReserveRatio;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> uint256 public totalBorrowedSupply;</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> ) ERC20(_name, _symbol) Ownable(msg.sender) {}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function fractionalReserveMint(address to, uint256 amount) external onlyOwner {</span></span> <span class="giallo-l"><span> _mint(to, amount);</span></span> <span class="giallo-l"><span> totalBorrowedSupply += amount;</span></span> <span class="giallo-l"><span> emit MintFractionalReserve(msg.sender, to, amount);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> uint256 reserveRatio = (totalSupply() - totalBorrowedSupply - segregatedSupply) * 1e18 / totalSupply();</span></span> <span class="giallo-l"><span> require(reserveRatio &gt;= requiredReserveRatio, &quot;reserveRatio&quot;);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> function fractionalReserveBurn(address from, uint256 amount) external onlyOwner {</span></span> <span class="giallo-l"><span> _burn(from, amount);</span></span> <span class="giallo-l"><span> totalBorrowedSupply -= amount;</span></span> <span class="giallo-l"><span> emit BurnFractionalReserve(msg.sender, from, amount);</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> // Code below is not part of the standard</span></span> <span class="giallo-l"><span> // ------------------------------------------------------------------------------</span></span> <span class="giallo-l"><span> uint256 internal segregatedSupply; // supply of segregated tokens</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function _update(address from, address to, uint256 value) internal override {</span></span> <span class="giallo-l"><span> // keep the reserve up to date on transfers</span></span> <span class="giallo-l"><span> if (!segregatedAccount[from] &amp;&amp; segregatedAccount[to]) {</span></span> <span class="giallo-l"><span> segregatedSupply += value;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> if (segregatedAccount[from] &amp;&amp; !segregatedAccount[to]) {</span></span> <span class="giallo-l"><span> segregatedSupply -= value;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ERC20._update(from, to, value);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function mint(address account, uint256 value) external onlyOwner {</span></span> <span class="giallo-l"><span> _mint(account, value);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function burn(address account, uint256 value) external onlyOwner {</span></span> <span class="giallo-l"><span> _burn(account, value);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function setSegregatedAccount(address account, bool segregated) external onlyOwner {</span></span> <span class="giallo-l"><span> if (segregated) {</span></span> <span class="giallo-l"><span> require(!segregatedAccount[account], &quot;segregated&quot;);</span></span> <span class="giallo-l"><span> segregatedSupply += balanceOf(account);</span></span> <span class="giallo-l"><span> } else {</span></span> <span class="giallo-l"><span> require(segregatedAccount[account], &quot;!segregated&quot;);</span></span> <span class="giallo-l"><span> segregatedSupply -= balanceOf(account);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> segregatedAccount[account] = segregated;</span></span> <span class="giallo-l"><span> emit SetSegregatedAccount(account, segregated);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function setRequiredReserveRatio(uint256 value) external onlyOwner {</span></span> <span class="giallo-l"><span> requiredReserveRatio = value;</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>Fractional reserve banking comes with many economic risks. This standard does not aim to provide guidelines on how to properly mitigate 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> 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-09-01T00:00:00+00:00 2026-02-11T14:48:26+00:00 Vitalik Buterinhttps://github.com/vbuterin Yoav Weisshttps://github.com/yoavw Dror Tiroshhttps://github.com/drortirosh Shahaf Nacsonhttps://github.com/shahafn Alex Forshtathttps://github.com/forshtat https://wg-eips.ritovision.com/7766/

An ERC-4337 improvement to aggregation of all UserOperation signatures in a bundle

<h2 id="abstract">Abstract</h2> <p><a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> defined a way to achieve Account Abstraction on Ethereum using an alternative <code>UserOperation</code> mempool.</p> <p>However, one big limitation remains: each transaction must carry its own <code>signature</code> or other form of validation input in order to be included.</p> <p>We propose an extension to the ERC-4337 that introduces a new entity, aggregator, that is called during validation, to validate multiple user operations at once.</p> <p>This addition will enable <code>UserOperations</code> to support sharing validation inputs, saving gas and guaranteeing atomicity of the bundle.</p> <h2 id="motivation">Motivation</h2> <p>Using validation schemes that allow signature aggregation enables significant optimisations and savings on gas for execution and transaction data cost. This is especially relevant in the context of rollups that publish data on the Ethereum mainnet.</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="aggregator-a-new-erc-4337-useroperation-entity-contract">Aggregator - a new ERC-4337 <code>UserOperation</code> entity contract</h3> <ul> <li><strong>Aggregator</strong> - a helper contract trusted by accounts to validate an aggregated signature. Bundlers/Clients whitelist the supported aggregators.</li> </ul> <h3 id="using-signature-aggregator">Using Signature Aggregator</h3> <p>A signature aggregator exposes 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"> IAggregator</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"> validateUserOpSignature</span><span>(</span><span class="z-storage z-type">PackedUserOperation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> userOp</span><span>)</span></span> <span class="giallo-l"><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"> sigForUserOp</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"> aggregateSignatures</span><span>(</span><span class="z-storage z-type">PackedUserOperation</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> userOps</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"> aggregatesSignature</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"> validateSignatures</span><span>(</span><span class="z-storage z-type">PackedUserOperation</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> userOps</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"> view</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li>An account signifies it uses signature aggregation by returning its address from <code>validateUserOp</code>.</li> <li>During <code>simulateValidation</code>, this aggregator is returned to the bundler as part of the <code>aggregatorInfo</code> field in the <code>ValidationResult</code> struct.</li> <li>All aggregators MUST be staked.</li> <li>The bundler should first verify the aggregator is not throttled or banned according to <a href="https://wg-eips.ritovision.com/7562/">ERC-7562</a> rules.</li> <li>To accept the <code>UserOperation</code>, the bundler must call <code>validateUserOpSignature()</code> to validate the <code>UserOperation</code> signature. This method returns an "alternate signature" that should be used during bundling.<br /> An "alternative signature" is normally an empty byte array but can also contain some data for the <code>acccount</code>.</li> <li>The bundler MUST call <code>validateUserOp</code> a second time on the account with the <code>UserOperation</code> using the returned "alternative signature", and make sure it returns the same value.</li> <li>Implementations of an <code>aggregateSignatures()</code> function must aggregate all UserOp signatures into a single value.</li> <li>Note that the above methods are helper methods for the bundler. The bundler MAY use a native library to perform the same validation and aggregation logic.</li> <li>Implementations of a <code>validateSignatures()</code> function MUST verify the aggregated signature's validity for all <code>UserOperations</code> in the array, and revert otherwise. This method is called on-chain by <code>handleAggregatedOps()</code></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"> AggregatorStakeInfo</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> aggregator</span><span>;</span></span> <span class="giallo-l"><span> StakeInfo stakeInfo</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="bundling-changes">Bundling changes</h3> <p>In addition to the steps described in ERC-4337, during bundling the bundler should:</p> <ul> <li>Sort UserOps by aggregator, to create the lists of UserOps-per-aggregator.</li> <li>For each aggregator, call <code>aggregateSignatures()</code> to create aggregated signature, and update the UserOps.</li> </ul> <h3 id="new-entry-point-function-in-the-erc-4337-entrypoint-contract">New "entry point" function in the ERC-4337 <code>EntryPoint</code> contract</h3> <p>We define the following addition to the core interface of the <code>EntryPoint</code> 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"> handleAggregatedOps</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> UserOpsPerAggregator</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> opsPerAggregator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> payable</span><span class="z-variable"> beneficiary</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">struct</span><span class="z-entity z-name"> UserOpsPerAggregator</span><span> {</span></span> <span class="giallo-l"><span> PackedUserOperation</span><span>[</span><span>]</span><span> userOps</span><span>;</span></span> <span class="giallo-l"><span> IAggregator aggregator</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> signature</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>An account that works with aggregated signature should return its signature aggregator address in the <code>authorizer</code> return value of the <code>validateUserOp</code> function. It MAY ignore the signature field.</p> <ul> <li> <p><code>handleAggregatedOps</code> can handle a batch that contains userOps of multiple aggregators (and also requests without any aggregator)</p> </li> <li> <p><code>handleAggregatedOps</code> performs the same logic as <code>handleOps</code>, but it must transfer the correct aggregator to each userOp, and also must call <code>validateSignatures</code> on each aggregator before doing all the per-account validation.</p> </li> <li> <p><strong>code: -32506</strong> - transaction rejected because wallet specified unsupported signature aggregator</p> <ul> <li>The <code>data</code> field SHOULD contain an <code>aggregator</code> value, as returned by the account's validateUserOp()</li> </ul> </li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="account-returning-the-alternative-signature">Account returning the "alternative signature"</h3> <p>When using an <code>aggregator</code> contract, the accounts delegate their ability to authenticate <code>UserOperations</code>. The entire contents of the</p> <p>In order to allow the validation function of the account to perform other checks, the <code>validateUserOpSignature</code> function generates a byte array that will replace the <code>UserOperation</code> signature when executed on-chain.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As ERC-4337 was created with signature aggregation on the roadmap, no modifications are needed to the deployed EntryPoint smart contracts.</p> <p>This proposal introduces new features without affecting the existing ones, and does not break backwards compatibility.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="malicious-aggregators">Malicious aggregators</h3> <p>The <code>aggregator</code> contracts are among te most trusted contracts in the entire ecosystem. They can authorize transactions on behalf of accounts, and they can invalidate large numbers of transactions with a simple storage change.</p> <p>Both account developers and block builders should be extremely careful with the selection of <code>aggregator</code> contracts that they are willing to support.</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-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-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 Sam Wilsonhttps://github.com/SamWilsnsam@binarycake.ca https://wg-eips.ritovision.com/7831/

Textual representation of an address and a chain.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a chain-specific address format that allows specifying both an account and the chain on which that account intends to transact. These chain-specific addresses take the form of <code>(example.eth:optimism)</code>, <code>6A10161835a36302BfD39bDA9B44f5734442234e:ethereum:11155111</code>, and so on. The target chain is resolved using a registry stored on ENS.</p> <h2 id="motivation">Motivation</h2> <p>The Ethereum ecosystem is becoming steadily more fragmented. This means a 20 byte address by itself is not enough information to fully specify an account. This can be problematic if funds are sent to an unreachable address on the incorrect chain.</p> <p>Instead of using chain identifiers, which are not human readable, the address could be extended with a human-readable chain name, which can then be resolved to a chain identifier. The mapping from chain names to identifiers has, since <a href="https://wg-eips.ritovision.com/155/">EIP-155</a>, been maintained off chain using a centralized list. This solution has two main shortcomings:</p> <ul> <li>It does not scale with the growing number of L2s.</li> <li>The list maintainer is a trusted centralized entity.</li> </ul> <p>This ERC proposes the use of ENS to map chain names to identifiers, while still allowing maximum flexibility by changing the root chain.</p> <h3 id="why-not-ens-with-erc-2304">Why not ENS with <a href="https://wg-eips.ritovision.com/2304/">ERC-2304</a>?</h3> <p>While <a href="https://wg-eips.ritovision.com/2304/">ERC-2304</a> allows registrants to specify per-chain addresses, it does not provide a default chain to receive assets on (nor should it.) The choice of receiving chain depends too much on off-chain factors to require a transaction to 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 <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC 2119</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8174">RFC 8174</a>.</p> <p>Grammar snippets in this proposal are given in Augmented Backus-Naur form (ABNF) as defined in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc5234">RFC 5234</a> and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc7405">RFC 7405</a>.</p> <h3 id="definitions">Definitions</h3> <p>The following terms are used throughout this proposal:</p> <ul> <li><strong>agent</strong> - software/tool responsible for resolving a chain-specific address to its exact account and chain.</li> <li><strong>bridge</strong> - contract that connects the root chain to the target chain (eg. to transfer tokens, proxy function calls.)</li> <li><strong>root chain</strong> - blockchain containing bridge and name resolver contracts.</li> <li><strong>target chain</strong> - blockchain where the identified account intends to transact; can be any chain with a bridge on the root chain.</li> </ul> <h3 id="syntax">Syntax</h3> <p>At a high level, a chain-specific address is made of three components separated by colons (<code>:</code>) ordered from most general on the right to most specific on the left:</p> <ul> <li>a <code>local-part</code>, that identifies the account on the target chain;</li> <li>a <code>chain-part</code>, that identifies the target chain; and</li> <li><em>optionally</em>, a <code>root-part</code> that identifies the root chain.</li> </ul> <p>These components may be enclosed by parentheses (<code>(</code> and <code>)</code>) to resolve parsing ambiguities.</p> <p>More formally, valid chain-specific addresses MUST adhere to the following grammar:</p> <pre class="giallo z-code"><code data-lang="ABNF"><span class="giallo-l"><span>address =</span><span class="z-variable z-other"> OPEN</span><span class="z-variable z-other"> bare-address</span><span class="z-variable z-other"> CLOSE</span><span class="z-keyword"> /</span></span> <span class="giallo-l"><span class="z-variable z-other"> bare-address</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>bare-address =</span><span class="z-variable z-other"> local-part</span><span class="z-variable z-other"> SEP</span><span class="z-variable z-other"> chain-part</span><span class="z-keyword"> [</span><span class="z-variable z-other">SEP</span><span class="z-variable z-other"> root-part</span><span class="z-keyword">]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>OPEN =</span><span class="z-variable z-other"> &#39;</span><span class="z-keyword">(</span><span class="z-variable z-other">&#39;</span></span> <span class="giallo-l"><span>CLOSE =</span><span class="z-variable z-other"> &#39;</span><span class="z-variable z-other">)</span><span class="z-variable z-other">&#39;</span></span> <span class="giallo-l"><span>SEP =</span><span class="z-variable z-other"> &#39;</span><span class="z-variable z-other">:</span><span class="z-variable z-other">&#39;</span></span></code></pre><h4 id="local-part">Local Part</h4> <p>The <code>local-part</code> is the most specific section of a chain-specific address. It identifies the account on the target chain. It can be either a hexadecimal string (<code>hex-address</code>) or an ENS-like name (<code>ens-like</code>).</p> <p>Valid <code>local-part</code> fragments MUST match the following grammar:</p> <pre class="giallo z-code"><code data-lang="ABNF"><span class="giallo-l"><span>local-part =</span><span class="z-variable z-other"> hex-address</span><span class="z-keyword"> /</span></span> <span class="giallo-l"><span class="z-variable z-other"> ens-like</span></span></code></pre><h5 id="hexadecimal-address">Hexadecimal Address</h5> <p>When <code>local-part</code> is a hexadecimal string, it MUST include checksum letter casing (see <a href="https://wg-eips.ritovision.com/7831/#checksum">Checksum</a>), and it MAY omit leading zeros. It MUST NOT include a leading <code>0x</code> prefix.</p> <p>Note that <code>local-part</code> may encode an address longer or shorter than 20 bytes (40 hexadecimal digits.) Implementations MUST support <code>local-part</code> lengths of 1 hexadecimal digit up to 40 digits. Implementations SHOULD support arbitrarily sized (within some reasonable limit) <code>local-part</code> components.</p> <p>Formally, <code>hex-address</code> MUST match the following grammar:</p> <pre class="giallo z-code"><code data-lang="ABNF"><span class="giallo-l"><span>hex-address =</span><span> 1*</span><span>HEXDIG</span></span></code></pre><h5 id="ens-like-names">ENS-Like Names</h5> <p>To disambiguate an ENS name from a hexadecimal string—and unlike standard ENS names—names used in the <code>local-part</code> of a chain-specific address MUST contain at least one dot (<code>.</code>). If present, a dot placed at the rightmost position (eg. <code>eth.</code> or <code>example.eth.</code>) SHALL be removed before resolving the name. Chain-specific addresses SHOULD NOT contain a dot in the rightmost position unless no other dot is present.</p> <p>The following grammar is illustrative only. See <a href="https://wg-eips.ritovision.com/137/">ERC-137</a> for the definition of an ENS name.</p> <pre class="giallo z-code"><code data-lang="ABNF"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">;</span><span class="z-comment"> Rough approximation of ENS names, with the additional requirement that it</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">;</span><span class="z-comment"> contain at least one &quot;.&quot;</span></span> <span class="giallo-l"><span>ens-like =</span><span> 1*</span><span class="z-variable z-other">NOTSEP</span><span class="z-variable z-other"> DOT</span><span> *</span><span class="z-keyword">(</span><span>1*</span><span class="z-variable z-other">NOTSEP</span><span class="z-keyword"> [</span><span class="z-variable z-other">DOT</span><span class="z-keyword">]</span><span class="z-keyword">)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>NOTSEP =</span><span class="z-constant"> %x01-39</span><span class="z-keyword"> /</span><span class="z-constant"> %x3b-ff</span></span></code></pre><h4 id="chain-part">Chain Part</h4> <p>The <code>chain-part</code> identifies the target chain. It MUST be a valid ENS name as defined in <a href="https://wg-eips.ritovision.com/137/">ERC-137</a>.</p> <p>The following grammar is illustrative only. See <a href="https://wg-eips.ritovision.com/137/">ERC-137</a> for the definition of an ENS name.</p> <pre class="giallo z-code"><code data-lang="ABNF"><span class="giallo-l"><span>chain-part =</span><span class="z-variable z-other"> ens-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"> Rough approximation of ENS names, with no additional requirements</span></span> <span class="giallo-l"><span>ens-name =</span><span> 1*</span><span class="z-variable z-other">NOTSEP</span></span></code></pre><h4 id="root-part">Root Part</h4> <p>The <code>root-part</code> identifies the root chain against which other names are resolved. When present, the <code>root-part</code> SHALL be the <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> <code>chainid</code> of the root chain in decimal format. <code>root-part</code> SHOULD NOT be present when <code>chainid == 1</code>, and MUST be present when <code>chainid != 1</code>.</p> <pre class="giallo z-code"><code data-lang="ABNF"><span class="giallo-l"><span>root-part =</span><span> 1*</span><span>DIGIT</span></span></code></pre><h3 id="resolution">Resolution</h3> <p>Resolving a chain-specific address begins on the right, and moves leftward.</p> <h4 id="root-chain">Root Chain</h4> <p>If <code>root-part</code> is not present, assume it is <code>1</code>. Set the root's <code>chainid</code> to the value of <code>root-part</code>. The agent MUST be able to resolve ENS names against this chain. This likely means it has RPC access and a known ENS Resolver address, but any method of resolving addresses is sufficient.</p> <p>Note that this makes <code>example.eth:optimism</code> distinct from <code>example.eth:optimism:10</code>. In the former case, both <code>example.eth</code> and <code>optimism</code> are resolved using ENS deployed on mainnet. In the second case, the two names would be resolved against an ENS deployed on the Optimism chain—an unusual situation.</p> <p>The assignment of chain identifiers is defined in <a href="https://wg-eips.ritovision.com/155/">EIP-155</a>.</p> <h4 id="target-chain">Target Chain</h4> <p>Next, construct an ENS name for the target chain by concatenating the value of <code>chain-part</code> with <code>.tbd.eth</code> <!-- TODO -->(such that <code>example.eth:foobar</code> would have a target chain of <code>foobar.tbd.eth</code><!-- TODO -->.) Resolve the target chain's address (i.e. with <a href="https://wg-eips.ritovision.com/137/">ERC-137</a>'s <code>addr</code>) against the ENS deployment on the root chain. The contract at this address is the "bridge contract."</p> <p>The agent has to verify that the bridge contract supports the <code>chain-part</code> in the address. First, the agent MUST call <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>'s <code>supportsInterface</code> on the bridge contract using <code>ChainMetadata</code>'s interface identifier (see <a href="https://wg-eips.ritovision.com/7831/#bridge-interface">Bridge Interface</a>) and the agent SHALL fail resolution if it returns false. Next, the agent MUST call the bridge contract's <code>acceptsName</code> function with the same namehash (see <a href="https://wg-eips.ritovision.com/137/">ERC-137</a>) used in the above call to <code>addr</code>. The agent SHALL fail resolution if <code>acceptsName</code> returns false.</p> <p>A bridge contract SHALL provide functionality/metadata enabling the agent to interact with the target chain. Further, it SHALL support the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> mechanism for interface discovery, and MAY support other methods to accomplish the same. Bridge contracts MUST implement <code>ChainMetadata</code> (see <a href="https://wg-eips.ritovision.com/7831/#bridge-interface">Bridge Interface</a>.) Further specifics of bridging are left for future proposals.</p> <!-- TODO: Should we ensure that each chain id is one-to-one mapped to a name? --> <h4 id="local-address">Local Address</h4> <h5 id="hexadecimal">Hexadecimal</h5> <p>Verify the checksum (see <a href="https://wg-eips.ritovision.com/7831/#checksum">Checksum</a>.)</p> <p>The local address is the hexadecimal encoding of the binary representation of the target chain's native address. For example, for the native Ethereum address <code>0x6A10161835a36302BfD39bDA9B44f5734442234e</code>, the local address would be <code>6A10161835a36302BfD39bDA9B44f5734442234e</code>.</p> <h5 id="ens-like">ENS-Like</h5> <p>If the local address ends in a dot (<code>.</code>), remove it. Resolve the address using <a href="https://wg-eips.ritovision.com/2304/">ERC-2304</a>'s <code>addr</code> against the ENS deployment on the root chain with a <code>coinType</code> derived from the <code>chainid</code> of the target chain (retrieved from the bridge contract.)</p> <h3 id="bridge-interface">Bridge Interface</h3> <p>Bridge contracts 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"> ChainMetadata</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> chainId</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">uint64</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> coinType</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"> acceptsName</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> keccak</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>When queried using <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>'s <code>supportsInterface</code>, bridge contracts MUST return true for <code>0x00000000</code><!-- TODO -->.</p> <h3 id="checksum">Checksum</h3> <!-- TODO: Get someone smarter than me to verify that this is a reasonable extension of ERC-55 --> <!-- TODO: Decide if we want ERC-1191. Would we use the root chain id, the target chain id, or even crazier—use the full chain-specific address as the input to the keccak? --> <p>Hexadecimal strings are cased according to a slightly modified <a href="https://wg-eips.ritovision.com/55/">ERC-55</a> algorithm. The algorithm is modified by wrapping <code>nibble_index</code> to fit within the keccak hash.</p> <details> <summary>Python implementation of the modified ERC-55 algorithm</summary> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">from</span><span> Crypto</span><span>.</span><span>Hash</span><span class="z-keyword"> import</span><span> keccak</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> from pycryptodome</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"> checksum_encode</span><span>(</span><span class="z-variable z-parameter z-function">addr</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> hex_addr</span><span class="z-keyword"> =</span><span> addr</span><span>.</span><span>hex</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> checksummed_buffer</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 class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Treat the hex address as ascii/utf-8 for keccak256 hashing</span></span> <span class="giallo-l"><span> k</span><span class="z-keyword"> =</span><span> keccak</span><span>.</span><span>new</span><span>(</span><span class="z-variable">digest_bits</span><span class="z-keyword">=</span><span class="z-constant">256</span><span>)</span></span> <span class="giallo-l"><span> k</span><span>.</span><span>update</span><span>(</span><span>hex_addr</span><span>.</span><span>encode</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">utf-8</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> hashed_address</span><span class="z-keyword"> =</span><span> k</span><span>.</span><span>hexdigest</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"> Iterate over each character in the hex address</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> nibble_index</span><span>,</span><span> character</span><span class="z-keyword"> in</span><span class="z-support"> enumerate</span><span>(</span><span>hex_addr</span><span>)</span><span>:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> character</span><span class="z-keyword"> in</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0123456789</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-comment"> #</span><span class="z-comment"> We can&#39;t upper-case the decimal digits</span></span> <span class="giallo-l"><span> checksummed_buffer</span><span class="z-keyword"> +=</span><span> character</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> character</span><span class="z-keyword"> in</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">abcdef</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-comment"> #</span><span class="z-comment"> Check if the corresponding hex digit (nibble) in the hash is 8 or higher</span></span> <span class="giallo-l"><span> nibble_index_wrapped</span><span class="z-keyword"> =</span><span> nibble_index</span><span class="z-keyword"> %</span><span class="z-support"> len</span><span>(</span><span>hashed_address</span><span>)</span></span> <span class="giallo-l"><span> hashed_address_nibble</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>(</span><span>hashed_address</span><span>[</span><span>nibble_index_wrapped</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> hashed_address_nibble</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 7</span><span>:</span></span> <span class="giallo-l"><span> checksummed_buffer</span><span class="z-keyword"> +=</span><span> character</span><span>.</span><span>upper</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> checksummed_buffer</span><span class="z-keyword"> +=</span><span> character</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span class="z-support"> Exception</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> f</span><span class="z-string">&quot;</span><span class="z-string">Unrecognized hex character </span><span class="z-constant">{</span><span>character</span><span class="z-storage z-type">!r</span><span class="z-constant">}</span><span class="z-string"> at position </span><span class="z-constant">{</span><span>nibble_index</span><span class="z-constant">}</span><span class="z-string">&quot;</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 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 class="z-keyword"> +</span><span> checksummed_buffer</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"> test</span><span>(</span><span class="z-variable z-parameter z-function">addr_str</span><span>:</span><span class="z-support"> str</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> padded_addr_str</span><span class="z-keyword"> =</span><span> addr_str</span><span>.</span><span>removeprefix</span><span>(</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></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>padded_addr_str</span><span>)</span><span class="z-keyword"> %</span><span class="z-constant"> 2</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"> Pad to an even number of nibbles.</span></span> <span class="giallo-l"><span> padded_addr_str</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> padded_addr_str</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> addr_bytes</span><span class="z-keyword"> =</span><span class="z-support"> bytes</span><span>.</span><span>fromhex</span><span>(</span><span>padded_addr_str</span><span>)</span></span> <span class="giallo-l"><span> checksum_encoded</span><span class="z-keyword"> =</span><span> checksum_encode</span><span>(</span><span>addr_bytes</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> checksum_encoded</span><span class="z-keyword"> !=</span><span> addr_str</span><span>:</span></span> <span class="giallo-l"><span class="z-support"> print</span><span>(</span><span class="z-storage z-type">f</span><span class="z-string">&quot;</span><span class="z-constant">{</span><span>checksum_encoded</span><span class="z-constant">}</span><span class="z-string"> != expected </span><span class="z-constant">{</span><span>addr_str</span><span class="z-constant">}</span><span class="z-string">&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>test</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span>test</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span>test</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span>test</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span>test</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x004f67dAbb603AAA58eD52641CCafF09C559704A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span>test</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x4F67dABB603aAa58Ed52641cCAff09C559704A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span>test</span><span>(</span></span> <span class="giallo-l"><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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">5aaeB6053f3e94c9B9a09f33669435E7</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">ef1BEaED5AaEB6053f3e94C9B9a09F33</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">669435e7ef1bEAed5aaEb6053f3e94C9</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">b9a09f33669435E7ef1beAED5aaEB605</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">3f3e94c9b9a09F33669435e7ef1beAED</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>)</span></span></code></pre></details> <p>For example, these strings are correctly cased:</p> <ul> <li><code>004f67dAbb603AAA58eD52641CCafF09C559704A</code></li> <li><code>04f67dAbb603AAA58eD52641CCafF09C559704A</code></li> <li><code>4F67dABB603aAa58Ed52641cCAff09C559704A</code></li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="component-order">Component Order</h3> <p>The components are ordered from most specific to most general because... <!-- TODO --></p> <h3 id="separator-choice">Separator Choice</h3> <p>The colon (<code>:</code>) is a reasonable choice for separator because it is not an allowed character in ENS names, it is familiar (eg. IPv6), and isn't as overloaded as the <code>@</code> symbol.</p> <h4 id="alternative">Alternative: <code>@</code></h4> <p>The <code>@</code> symbol is a common choice for addresses, and finds use in email and several federated communication protocols. The English reading (foo-<strong>AT</strong>-example-DOT-com) is natural and implies a hierarchy between the left and the right components.</p> <p>Unfortunately, because the <code>@</code> symbol is so widely used, including it in a chain-specific address would make all those protocol identifiers more confusing (or even invalid.) For example, <code>foo@foo.eth@ethereum</code> is not a valid email address.</p> <h4 id="alternative-1">Alternative: <code>/</code></h4> <!-- TODO --> <h3 id="target-chain-as-subdomain">Target Chain as Subdomain</h3> <p>While it would be technically possible to resolve <code>chain-part</code> against a root ENS name (eg. <code>ethereum.eth</code> instead of <code>ethereum.tbd.eth</code><!-- TODO -->), using a subdomain allows the pre-registration of well-known chain names for an initial distribution of names before switching to open registration.</p> <p>Without such a pre-registration, an attacker could register well-known names before the legitimate project.</p> <p>After the pre-registration period, open registration is acceptable because new chains can register their names before announcing publicly.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>It is always possible to determine whether a particular string is a chain-specific address, a plain address, or a plain ENS name. Because of this property, there is little opportunity for backwards incompatibility: chain-specific addresses are not valid legacy addresses or ENS names, so tools without support will simply reject them.</p> <h2 id="test-cases">Test Cases</h2> <!-- -- TODO: Test Case Ideas -- -- * Longer than 20-byte hex local-part --> <h3 id="ens-configuration">ENS Configuration</h3> <h4 id="mainnet-1">Mainnet (1)</h4> <table><thead><tr><th>Name</th><th>Coin Type</th><th>Record</th></tr></thead><tbody> <tr><td><code>ethereum.tbd.eth</code><!-- TODO --></td><td>-</td><td>a bridge contract to mainnet (1)</td></tr> <tr><td><code>rollup1.tbd.eth</code><!-- TODO --></td><td>-</td><td>a bridge contract to rollup1 (1608)</td></tr> <tr><td><code>example.eth</code></td><td><code>2147483649</code></td><td><code>0xaAaAaAaaAaAaAaaAaAAAAAAAAaaaAaAaAaaAaaAa</code></td></tr> <tr><td><code>example.eth</code></td><td><code>2147485256</code></td><td><code>0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB</code></td></tr> </tbody></table> <h4 id="sepolia-11155111">Sepolia (11155111)</h4> <table><thead><tr><th>Name</th><th>Coin Type</th><th>Record</th></tr></thead><tbody> <tr><td><code>ethereum.tbd.eth</code><!-- TODO --></td><td>-</td><td>a bridge contract to sepolia (11155111)</td></tr> <tr><td><code>example.eth</code></td><td><!-- TODO --></td><td><!-- TODO --></td></tr> </tbody></table> <h3 id="inputs-expected-outputs">Inputs &amp; Expected Outputs</h3> <h4 id="valid">Valid</h4> <table><thead><tr><th>Input</th><th>Target Chain</th><th>Local Address</th></tr></thead><tbody> <tr><td><code>(example.eth:ethereum)</code></td><td>mainnet (1)</td><td><code>0xaAaAaAaaAaAaAaaAaAAAAAAAAaaaAaAaAaaAaaAa</code></td></tr> <tr><td><code>example.eth:rollup1</code></td><td>rollup1 (1608)</td><td><code>0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB</code></td></tr> <tr><td><code>example.eth.:ethereum</code></td><td>mainnet (1)</td><td><code>0xaAaAaAaaAaAaAaaAaAAAAAAAAaaaAaAaAaaAaaAa</code></td></tr> <tr><td><code>0:ethereum</code></td><td>mainnet (1)</td><td><code>0x0000000000000000000000000000000000000000</code></td></tr> </tbody></table> <h4 id="invalid">Invalid</h4> <table><thead><tr><th>Input</th><th>Failure Reason</th></tr></thead><tbody> <tr><td><code>(0xaAaAaAaaAaAaAaaAaAAAAAAAAaaaAaAaAaaAaaAa:ethereum)</code></td><td>Invalid hexadecimal</td></tr> <tr><td><code>(aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa:ethereum)</code></td><td>Invalid checksum</td></tr> <tr><td><code>(AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA:ethereum)</code></td><td>Invalid checksum</td></tr> <tr><td><code>(eth:ethereum)</code></td><td>Invalid hexadecimal</td></tr> <tr><td><code>(:ethereum)</code></td><td>Missing <code>local-part</code></td></tr> </tbody></table> <h2 id="reference-implementation">Reference Implementation</h2> <!-- This section is optional. The Reference Implementation section should include a minimal implementation that assists in understanding or implementing this specification. It should not include project build files. The reference implementation is not a replacement for the Specification section, and the proposal should still be understandable without it. If the reference implementation 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="security-considerations">Security Considerations</h2> <h3 id="unicode-typosquatting-attacks">Unicode &amp; Typosquatting Attacks</h3> <p>An attacker could register ENS names that resemble well-known chain names. For example, <code>etherium</code> and <code>ehtereum</code> are reasonably close to <code>ethereum</code>. While many unicode homoglyphs are caught by ENS libraries, agents should still be aware of the risk they pose.</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-23T00:00:00+00:00 2026-02-11T14:48:26+00:00 Vitalik Buterinhttps://github.com/vbuterin Yoav Weisshttps://github.com/yoavw Dror Tiroshhttps://github.com/drortirosh Shahaf Nacsonhttps://github.com/shahafn Alex Forshtathttps://github.com/forshtat https://wg-eips.ritovision.com/7769/

JSON-RPC API methods for communication between smart contract account wallets and ERC-4337 bundlers

<h2 id="abstract">Abstract</h2> <p>Defines new JSON-RPC API methods which enable <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> wallets to communicate with <code>UserOpeation</code> mempool nodes and bundlers, matching the functionality that exists for Ethereum transactions.</p> <p>Additionally, a set of <code>debug</code> JSON-RPC API methods is defined in order to facilitate development, testing and debugging issues with ERC-4337 implementations.</p> <h2 id="motivation">Motivation</h2> <p>In ERC-4337, user transactions as defined in Ethereum are replaced with <code>UserOperation</code> objects, which contain all the information needed to perform the operations requested by the users.</p> <p>However, existing Ethereum JSON-RPC API methods are not suited to working with <code>UserOperation</code> objects. In order to facilitate the operation of the alternative <code>UserOperation</code> mempool it is important that all implementations of the ERC-4337 protocol have a standardized set of APIs that can be used interchangeably.</p> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions</h3> <ul> <li><strong>bundler</strong>: a node exposing the APIs, in order to submit them to the network. A bundler collects one or more UserOperations into a bundle and submits them together to the <code>EntryPoint</code> in a single <code>handleOps</code> call.</li> </ul> <h3 id="rpc-methods-eth-namespace">RPC methods (eth namespace)</h3> <h4 id="eth-senduseroperation"><code>eth_sendUserOperation</code></h4> <p>The <code>eth_sendUserOperation</code> method submits a <code>UserOperation</code> object to the UserOperation mempool. The client MUST validate the <code>UserOperation</code>, and return a result accordingly.</p> <p>The result SHOULD be set to the <code>userOpHash</code> if and only if the request passed simulation and was accepted in the client's UserOperation pool.</p> <p>If the validation, simulation, or UserOperation pool inclusion fails, <code>userOpHash</code> SHOULD NOT be returned. Rather, the client SHOULD return the failure reason.</p> <h5 id="parameters">Parameters:</h5> <ol> <li><strong>UserOperation</strong> a full user-operation struct.<br /> All fields MUST be set as hex values.<br /> Empty <code>bytes</code> block (e.g. empty <code>initCode</code>) MUST be set to <code>"0x"</code>\</li> <li><strong>factory</strong> and <strong>factoryData</strong><br /> Must provide either both of these parameters, or none.</li> <li><strong>paymaster</strong>, <strong>paymasterData</strong>, <strong>paymasterValidationGasLimit</strong>, <strong>paymasterPostOpGasLimit</strong><br /> Must provide either all of these parameters, or none.</li> <li><strong>entryPoint</strong> the <code>EntryPoint</code> contract address the request should be sent through.<br /> This MUST be one of the entry points returned by the <code>supportedEntryPoints</code> RPC call.</li> </ol> <h5 id="return-value">Return value:</h5> <ul> <li>If the UserOperation is valid, the client MUST return the calculated <code>userOpHash</code> for it</li> <li>in case of failure, MUST return an <code>error</code> result object, with <code>code</code> and <code>message</code>.<br /> The error code and message SHOULD be set as follows: <ul> <li><strong>code: -32602</strong> - invalid <code>UserOperation</code> struct/fields</li> <li><strong>code: -32500</strong> - transaction rejected by <code>EntryPoint</code> contract's <code>simulateValidation</code> function during wallet creation or validation <ul> <li>The <code>message</code> field MUST be set to the emitted <code>FailedOp</code> event's "<code>AAxx</code>" error message from the <code>EntryPoint</code></li> </ul> </li> <li><strong>code: -32501</strong> - transaction rejected by <code>paymaster</code> contract's <code>validatePaymasterUserOp</code> function <ul> <li>The <code>message</code> field SHOULD be set to the revert message from the <code>paymaster</code> contract</li> <li>The <code>data</code> field MUST contain a <code>paymaster</code> value</li> </ul> </li> <li><strong>code: -32502</strong> - transaction rejected because of <a href="https://wg-eips.ritovision.com/7562/">ERC-7562</a> opcode validation rule violation</li> <li><strong>code: -32503</strong> - UserOperation out of time-range:<br /> either wallet or paymaster returned a time-range, and it has already expired or will expire soon. <ul> <li>The <code>data</code> field SHOULD contain the <code>validUntil</code> and <code>validAfter</code> values</li> <li>The <code>data</code> field SHOULD contain a <code>paymaster</code> address if this error was triggered by the <code>paymaster</code> contract</li> </ul> </li> <li><strong>code: -32504</strong> - transaction rejected because <code>paymaster</code> is throttled or banned due to ERC-7562 reputation rules <ul> <li>The <code>data</code> field SHOULD contain a <code>paymaster</code> address</li> </ul> </li> <li><strong>code: -32505</strong> - transaction rejected because <code>paymaster</code> contract's ERC-7562 stake or unstake-delay is too low <ul> <li>The <code>data</code> field SHOULD contain a <code>paymaster</code> address</li> <li>The <code>data</code> field SHOULD contain a <code>minimumStake</code> and <code>minimumUnstakeDelay</code></li> </ul> </li> <li><strong>code: -32507</strong> - transaction rejected because of wallet signature check failed</li> <li><strong>code: -32508</strong> - transaction rejected because paymaster balance can't cover all pending <code>UserOperations</code>.</li> </ul> </li> </ul> <h5 id="example">Example:</h5> <p>Request:</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">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">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">method</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_sendUserOperation</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><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> eip7702Auth</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> an EIP-7702 authorization tuple</span></span> <span class="giallo-l"><span class="z-variable z-other"> sender</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> address</span></span> <span class="giallo-l"><span class="z-variable z-other"> nonce</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><span class="z-variable z-other"> factory</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> address</span></span> <span class="giallo-l"><span class="z-variable z-other"> factoryData</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> bytes</span></span> <span class="giallo-l"><span class="z-variable z-other"> callData</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> bytes</span></span> <span class="giallo-l"><span class="z-variable z-other"> callGasLimit</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><span class="z-variable z-other"> verificationGasLimit</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><span class="z-variable z-other"> preVerificationGas</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><span class="z-variable z-other"> maxFeePerGas</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><span class="z-variable z-other"> maxPriorityFeePerGas</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><span class="z-variable z-other"> paymaster</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> address</span></span> <span class="giallo-l"><span class="z-variable z-other"> paymasterVerificationGasLimit</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><span class="z-variable z-other"> paymasterPostOpGasLimit</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><span class="z-variable z-other"> paymasterData</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> bytes</span></span> <span class="giallo-l"><span class="z-variable z-other"> signature</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> bytes</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> entryPoint</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> address</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre> <p>Response:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span> &quot;id&quot;: 1,</span></span> <span class="giallo-l"><span> &quot;result&quot;: &quot;0x123456789012345678901234567890123456789012345678901234567890abcd&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="example-failure-responses">Example failure responses:</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">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"> 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">message</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">AA21 didn&#39;t pay prefund</span><span class="z-punctuation z-definition z-string">&quot;</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"> -32500</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="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"> 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">message</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">paymaster stake too low</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">paymaster</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x123456789012345678901234567890123456790</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minimumStake</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xde0b6b3a7640000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minimumUnstakeDelay</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x15180</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">code</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> -32504</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="support-for-eip-7702-authorizations">Support for <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> authorizations</h5> <p>On networks with <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> activated, the <code>UserOperation</code> object may also contain an <code>eip7702Auth</code> tuple. Notice that according to EIP-7702 an <code>eip7702Auth</code> tuple must be provided only to perform a <strong>change</strong> of the authorization address. Once the necessary <code>eip7702Auth</code> tuple was stored on-chain, users are not required to provide the same <code>eip7702Auth</code> tuple for any consequent <code>UserOperation</code>.</p> <p>Separately, the fields <code>factory</code> and <code>factoryData</code> have a modified behaviour when using an EIP-7702 authorized <code>sender</code>.</p> <p>The <code>factory</code> field SHOULD be set to exactly the <code>INITCODE_EIP7702_MARKER = 0x7702</code> flag when using an EIP-7702 authorized <code>sender</code>. Passing his flag instructs the <code>EntryPoint</code> contract to verify the <code>sender</code> address contains a valid EIP-7702 authorization.</p> <p>When <code>INITCODE_EIP7702_MARKER</code> is specified, the <code>factoryData</code> value is passed directly to the <code>sender</code> contract, instead of the <code>factory</code> contract. This is done as a separate call before the <code>validateUserOp</code> is called, meaning the <code>sender</code> contract will be called two times during validation.</p> <p>The <code>factoryData</code> value can be left empty. In this case, the call will not be performed.</p> <p>The purpose of this <code>factoryData</code> call is to provide the EIP-7702 <code>sender</code> contract an ability to initialize its storage before accepting the <code>UserOperation</code> via the <code>validateUserOp</code> function.</p> <h4 id="eth-estimateuseroperationgas">eth_estimateUserOperationGas</h4> <p>Estimate the gas values for a <code>UserOperation</code>. Given <code>UserOperation</code> optionally without gas limits and gas prices, return the needed gas limits. The signature field is ignored by the wallet, so that the operation will not require the user's approval. Still, it might require putting a "stub" <code>signature</code> value, e.g. a <code>signature</code> byte array of the right length. If the UserOperation contains an <code>eip7702Auth</code> tuple, for the purpose of estimation the signature should be ignored, and the tuple should be evaluated as if it was signed by the <code>sender</code></p> <p><strong>Parameters</strong>:</p> <ul> <li>Same as <code>eth_sendUserOperation</code><br /> All gas limits and fees parameters are optional, but are used if specified.<br /> <code>maxFeePerGas</code> and <code>maxPriorityFeePerGas</code> default to zero, so no payment is required by neither account nor paymaster.</li> <li>Optionally accepts the <code>State Override Set</code> to allow users to modify the state during the gas estimation.<br /> This field as well as its behavior is equivalent to the ones defined for <code>eth_call</code> RPC method.</li> </ul> <p><strong>Return Values:</strong></p> <ul> <li><strong>preVerificationGas</strong> gas overhead of this <code>UserOperation</code></li> <li><strong>verificationGasLimit</strong> estimation of gas limit required by the validation of this <code>UserOperation</code></li> <li><strong>paymasterVerificationGasLimit</strong> estimation of gas limit required by the paymaster verification<br /> Returned only if the <code>UserOperation</code> specifies a <code>Paymaster</code> address</li> <li><strong>callGasLimit</strong> estimation of gas limit required by the inner account execution</li> </ul> <p><strong>Note:</strong> actual <code>postOpGasLimit</code> cannot be reliably estimated.<br /> Paymasters should provide this value to account, and require that specific value on-chain during validation.</p> <h5 id="error-codes">Error Codes:</h5> <p>Same as <code>eth_sendUserOperation</code> This operation may also return an error if either the inner call to the account contract reverts, or paymaster's <code>postOp</code> call reverts.</p> <h4 id="eth-getuseroperationbyhash">eth_getUserOperationByHash</h4> <p>Return a <code>UserOperation</code>object based on a <code>userOpHash</code> value returned by <code>eth_sendUserOperation</code>.</p> <p><strong>Parameters</strong></p> <ul> <li><strong>hash</strong> a <code>userOpHash</code> value returned by <code>eth_sendUserOperation</code></li> </ul> <p><strong>Return value</strong>:</p> <ul> <li> <p>If the <code>UserOperation</code> is included in a block:</p> <ul> <li>Return a full UserOperation, with the addition of <code>entryPoint</code>, <code>blockNumber</code>, <code>blockHash</code> and <code>transactionHash</code>.</li> </ul> </li> <li> <p>Else if the <code>UserOperation</code> is pending in the bundler's mempool:</p> <ul> <li>MAY return <code>null</code>, or a full <code>UserOperation</code>, with the addition of the <code>entryPoint</code> field and a <code>null</code> value for <code>blockNumber</code>, <code>blockHash</code> and <code>transactionHash</code>.</li> </ul> </li> <li> <p>Else:</p> <ul> <li>Return <code>null</code></li> </ul> </li> </ul> <h4 id="eth-getuseroperationreceipt">eth_getUserOperationReceipt</h4> <p>Return a <code>UserOperation</code> receipt object based on a <code>userOpHash</code> value returned by <code>eth_sendUserOperation</code>.</p> <p><strong>Parameters</strong></p> <ul> <li><strong>hash</strong> a <code>userOpHash</code> value returned by <code>eth_sendUserOperation</code></li> </ul> <p><strong>Return value</strong>:</p> <p><code>null</code> in case the <code>UserOperation</code> is not yet included in a block, or:</p> <ul> <li><strong>userOpHash</strong> the request hash</li> <li><strong>entryPoint</strong></li> <li><strong>sender</strong></li> <li><strong>nonce</strong></li> <li><strong>paymaster</strong> the paymaster used for this userOp (or empty)</li> <li><strong>actualGasCost</strong> - the actual amount paid (by account or paymaster) for this <code>UserOperation</code></li> <li><strong>actualGasUsed</strong> - total gas used by this <code>UserOperation</code>, including pre-verification, creation, validation and execution</li> <li><strong>success</strong> boolean - whether this execution completed without a revert</li> <li><strong>reason</strong> - in case of reverted <code>UserOperation</code>, the returned revert reason byte array</li> <li><strong>logs</strong> - the logs generated by this particular <code>UserOperation</code>, not including logs of other <code>UserOperations</code> in the same bundle</li> <li><strong>receipt</strong> the <code>TransactionReceipt</code> object. Note that the returned <code>TransactionReceipt</code> is for the entire bundle, not only for this <code>UserOperation</code>.</li> </ul> <h4 id="eth-supportedentrypoints">eth_supportedEntryPoints</h4> <p>Returns an array of the <code>EntryPoint</code> contracts' addresses supported by the client. The first element of the array <code>SHOULD</code> be the <code>EntryPoint</code> contract addressed preferred by the client.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span># Request</span></span> <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"> 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">eth_supportedEntryPoints</span><span class="z-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 class="giallo-l"></span> <span class="giallo-l"><span># Response</span></span> <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"> 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> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xcd01C8aa8995A59eB7B2627E69b40e0524B5ecf8</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">0x7A0A0d159218E6a2f407B99173A2b12A6DDfC2a6</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="eth-chainid">eth_chainId</h4> <p>Returns <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> Chain ID.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span># Request</span></span> <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"> 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">eth_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">params</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 class="giallo-l"><span># Response</span></span> <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"> 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">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="rpc-methods-debug-namespace">RPC methods (debug Namespace)</h3> <p>This api must only be available in testing mode and is required by the compatibility test suite. In production, any <code>debug_*</code> rpc calls should be blocked.</p> <h4 id="debug-bundler-clearstate">debug_bundler_clearState</h4> <p>Clears the bundler mempool and reputation data of paymasters/accounts/factories.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span># Request</span></span> <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"> 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">debug_bundler_clearState</span><span class="z-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 class="giallo-l"></span> <span class="giallo-l"><span># Response</span></span> <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"> 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">ok</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="debug-bundler-dumpmempool">debug_bundler_dumpMempool</h4> <p>Dumps the current <code>UserOperation</code> mempool</p> <p><strong>Parameters:</strong></p> <ul> <li><strong>EntryPoint</strong> the entrypoint used by <code>eth_sendUserOperation</code></li> </ul> <p><strong>Returns:</strong></p> <p><code>array</code> - Array of <code>UserOperation</code> objects currently in the mempool.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span># Request</span></span> <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"> 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">debug_bundler_dumpMempool</span><span class="z-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 class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x1306b01bC3e4AD202612D3843387e94737673F53</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># Response</span></span> <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"> 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> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-invalid z-illegal"> s</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 class="z-invalid z-illegal">,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> address</span></span> <span class="giallo-l"><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 class="z-invalid z-illegal">,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><span class="z-invalid z-illegal"> f</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">c</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">y</span><span class="z-invalid z-illegal">,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> address</span></span> <span class="giallo-l"><span class="z-invalid z-illegal"> f</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">c</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">y</span><span class="z-invalid z-illegal">D</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> bytes</span></span> <span class="giallo-l"><span class="z-invalid z-illegal"> c</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">l</span><span class="z-invalid z-illegal">l</span><span class="z-invalid z-illegal">D</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> bytes</span></span> <span class="giallo-l"><span class="z-invalid z-illegal"> c</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">l</span><span class="z-invalid z-illegal">l</span><span class="z-invalid z-illegal">G</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal">L</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">m</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><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">i</span><span class="z-invalid z-illegal">f</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">c</span><span class="z-invalid z-illegal">a</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">G</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal">L</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">m</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><span class="z-invalid z-illegal"> p</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">e</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">i</span><span class="z-invalid z-illegal">f</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">c</span><span class="z-invalid z-illegal">a</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">G</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal">,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><span class="z-invalid z-illegal"> m</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">x</span><span class="z-invalid z-illegal">F</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">P</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">G</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal">,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><span class="z-invalid z-illegal"> m</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">x</span><span class="z-invalid z-illegal">P</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">y</span><span class="z-invalid z-illegal">F</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">P</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">G</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal">,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><span class="z-invalid z-illegal"> s</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">g</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">u</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">e</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> bytes</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="debug-bundler-sendbundlenow">debug_bundler_sendBundleNow</h4> <p>Forces the bundler to build and execute a bundle from the mempool as <code>handleOps()</code> transaction.</p> <p>Returns: <code>transactionHash</code></p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span># Request</span></span> <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"> 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">debug_bundler_sendBundleNow</span><span class="z-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 class="giallo-l"></span> <span class="giallo-l"><span># Response</span></span> <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"> 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">0xdead9e43632ac70c46b4003434058b18db0ad809617bd29f3448d46ca9085576</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="debug-bundler-setbundlingmode">debug_bundler_setBundlingMode</h4> <p>Sets bundling mode.</p> <p>After setting mode to "manual", an explicit call to <code>debug_bundler_sendBundleNow</code> is required to send a bundle.</p> <h5 id="parameters-1">parameters:</h5> <p><code>mode</code> - 'manual' | 'auto'</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span># Request</span></span> <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"> 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">debug_bundler_setBundlingMode</span><span class="z-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 class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">manual</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># Response</span></span> <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"> 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">ok</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="debug-bundler-setreputation">debug_bundler_setReputation</h4> <p>Sets the reputation of given addresses.</p> <p><strong>Parameters:</strong></p> <ul> <li> <p>An array of reputation entries to add/replace, with the fields:</p> <ul> <li><code>address</code> - the address to set the reputation for</li> <li><code>opsSeen</code> - number of times a user operations with that entity was seen and added to the mempool</li> <li><code>opsIncluded</code> - number of times user operations that use this entity was included on-chain</li> </ul> </li> <li> <p><strong>EntryPoint</strong> the entrypoint used by <code>eth_sendUserOperation</code></p> </li> </ul> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span># Request</span></span> <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"> 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">debug_bundler_setReputation</span><span class="z-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> {</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">0x7A0A0d159218E6a2f407B99173A2b12A6DDfC2a6</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">opsSeen</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x14</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">opsIncluded</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0D</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">0x1306b01bC3e4AD202612D3843387e94737673F53</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 class="giallo-l"><span># Response</span></span> <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"> 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">ok</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="debug-bundler-dumpreputation">debug_bundler_dumpReputation</h4> <p>Returns the reputation data of all observed addresses. Returns an array of reputation objects, each with the fields described above in <code>debug_bundler_setReputation</code>.</p> <p><strong>Parameters:</strong></p> <ul> <li><strong>EntryPoint</strong> the entrypoint used by <code>eth_sendUserOperation</code></li> </ul> <p><strong>Return value:</strong></p> <p>An array of reputation entries with the fields:</p> <ul> <li><code>address</code> - the address to set the reputation for</li> <li><code>opsSeen</code> - number of times a user operations with that entity was seen and added to the mempool</li> <li><code>opsIncluded</code> - number of times user operation that use this entity was included on-chain</li> <li><code>status</code> - (string) The status of the address in the bundler (<code>'ok'</code> | <code>'throttled'</code> | <code>'banned'</code>)</li> </ul> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span># Request</span></span> <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"> 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">debug_bundler_dumpReputation</span><span class="z-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 class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x1306b01bC3e4AD202612D3843387e94737673F53</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># Response</span></span> <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"> 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> [</span></span> <span class="giallo-l"><span> {</span><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">0x7A0A0d159218E6a2f407B99173A2b12A6DDfC2a6</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">opsSeen</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x14</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">opsIncluded</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x13</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">status</span><span class="z-support">&quot;</span><span>:</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 class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="debug-bundler-adduserops">debug_bundler_addUserOps</h4> <p>Inject <code>UserOperation</code> objects array into the mempool. Assume the given <code>UserOperation</code> objects all pass validation without actually validating them, and accept them directly into the mempool.</p> <p><strong>Parameters:</strong></p> <ul> <li>An array of <code>UserOperation</code> objects</li> </ul> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span># Request</span></span> <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"> 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">debug_bundler_addUserOps</span><span class="z-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> {</span><span class="z-invalid z-illegal"> s</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 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><span class="z-invalid z-illegal"> .</span><span class="z-invalid z-illegal">.</span><span class="z-invalid z-illegal">.</span><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-invalid z-illegal"> s</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xb...</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-invalid z-illegal"> .</span><span class="z-invalid z-illegal">.</span><span class="z-invalid z-illegal">.</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># Response</span></span> <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"> 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">ok</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> <ul> <li>explicit debug functions: bundlers are required to provide a set of debug functions, so that the "bundler specification test suite" can be used to verify its adherance to the spec.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal defines a new JSON-RPC API standard that does not pose any backwards compatibility challenges.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="preventing-dos-attacks-on-useroperation-mempool">Preventing DoS attacks on UserOperation mempool</h3> <p>Operating a public production ERC-4337 node is a computationally intensive task and may be a target of a DoS attack. This is addressed by the ERC-7562 validation rules, which defines a way for the ERC-4337 node to track participants' reputation as well as preventing nodes from accepting maliciously crafted <code>UserOperations</code>.</p> <p>It is strictly recommended that all ERC-4337 nodes also implement ERC-7562 validation rules to minimize DoS risks.</p> <h3 id="disabling-debug-api-in-production-servers">Disabling <code>debug</code> API in production servers</h3> <p>The API defined in the <code>debug</code> namespace is not intended to ever be publicly available. Production implementations of ERC-4337 must never make it available by default, and in fact enabling it should result in a clear warning of the potential dangers of exposing this API.</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-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 frankhttps://github.com/frankmint2024frank@mintchain.io https://wg-eips.ritovision.com/7765/

An interface extending ERC-721 representing real world assets that users can exercise privileges with NFTs.

<h2 id="abstract">Abstract</h2> <p>This EIP defines an interface to carry a real world asset with some privileges that can be exercised by the holder of the corresponding NFT. The EIP standardizes the interface for non-fungible tokens representing real world assets with privileges to be exercised, such as products sold onchain which can be redeemed in the real world.</p> <p>And the privileges we describe here specifically refer to the rights and interests bound to the RWA NFT that can be executed by the holder in the real world.</p> <h2 id="motivation">Motivation</h2> <p>NFTs bound to real-world assets sometimes need to carry certain privileges that can be exercised by the holder. Users can initiate transactions onchain to specify the exercise of a certain privilege, thereby achieving real-world privileges that directly map the onchain privilege through subsequent operations. For example, if a certain product such as a pair of shoes is sold onchain in the representation of NFT, the NFT holder can exercise the privilege of exchanging physical shoes offchain, to achieve the purpose of interoperability between the blockchain and the real world.</p> <p>Having a standard interface enables interoperability for services, clients, UI, and inter-contract functionalities on top of this use-case.</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 standard inherits the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> NFT token standard for all transfer and approval logic. All transfer and approval functions are inherited from this token standard without changes. Additionally, this standard also inherits the ERC-721 Metadata standards for name, symbol, and metadata URI lookup.</p> <p>Any compliant contract following this EIP <strong>MUST</strong> implement the following interface:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pragma solidity &gt;=0.7.0 &lt;0.9.0;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/// @title ERC-7765 Privileged Non-Fungible Tokens Tied To Real World Assets</span></span> <span class="giallo-l"><span>/// @dev See https://eips.ethereum.org/EIPS/eip-7765</span></span> <span class="giallo-l"><span>interface IERC7765 /* is IERC721, IERC165 */ {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice This event emitted when a specific privilege of a token is successfully exercised.</span></span> <span class="giallo-l"><span> /// @param _operator the address who exercised the privilege.</span></span> <span class="giallo-l"><span> /// @param _to the address to benefit from the privilege.</span></span> <span class="giallo-l"><span> /// @param _tokenId the NFT tokenID.</span></span> <span class="giallo-l"><span> /// @param _privilegeId the ID of the privileges.</span></span> <span class="giallo-l"><span> event PrivilegeExercised(</span></span> <span class="giallo-l"><span> address indexed _operator,</span></span> <span class="giallo-l"><span> address indexed _to,</span></span> <span class="giallo-l"><span> uint256 indexed _tokenId,</span></span> <span class="giallo-l"><span> uint256 _privilegeId</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice This function exercise a specific privilege of a token.</span></span> <span class="giallo-l"><span> /// @dev Throws if `_privilegeId` is not a valid privilegeId.</span></span> <span class="giallo-l"><span> /// @param _to the address to benefit from the privilege.</span></span> <span class="giallo-l"><span> /// @param _tokenId the NFT tokenID.</span></span> <span class="giallo-l"><span> /// @param _privilegeId the ID of the privileges.</span></span> <span class="giallo-l"><span> /// @param _data extra data passed in for extra message or future extension.</span></span> <span class="giallo-l"><span> function exercisePrivilege(</span></span> <span class="giallo-l"><span> address _to,</span></span> <span class="giallo-l"><span> uint256 _tokenId,</span></span> <span class="giallo-l"><span> uint256 _privilegeId,</span></span> <span class="giallo-l"><span> bytes calldata _data</span></span> <span class="giallo-l"><span> ) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice This function is to check whether a specific privilege of a token can be exercised.</span></span> <span class="giallo-l"><span> /// @dev Throws if `_privilegeId` is not a valid privilegeId.</span></span> <span class="giallo-l"><span> /// @param _to the address to benefit from the privilege.</span></span> <span class="giallo-l"><span> /// @param _tokenId the NFT tokenID.</span></span> <span class="giallo-l"><span> /// @param _privilegeId the ID of the privileges.</span></span> <span class="giallo-l"><span> function isExercisable(</span></span> <span class="giallo-l"><span> address _to,</span></span> <span class="giallo-l"><span> uint256 _tokenId,</span></span> <span class="giallo-l"><span> uint256 _privilegeId</span></span> <span class="giallo-l"><span> ) external view returns (bool _exercisable);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice This function is to check whether a specific privilege of a token has been exercised.</span></span> <span class="giallo-l"><span> /// @dev Throws if `_privilegeId` is not a valid privilegeId.</span></span> <span class="giallo-l"><span> /// @param _to the address to benefit from the privilege.</span></span> <span class="giallo-l"><span> /// @param _tokenId the NFT tokenID.</span></span> <span class="giallo-l"><span> /// @param _privilegeId the ID of the privileges.</span></span> <span class="giallo-l"><span> function isExercised(</span></span> <span class="giallo-l"><span> address _to,</span></span> <span class="giallo-l"><span> uint256 _tokenId,</span></span> <span class="giallo-l"><span> uint256 _privilegeId</span></span> <span class="giallo-l"><span> ) external view returns (bool _exercised);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice This function is to list all privilegeIds of a token.</span></span> <span class="giallo-l"><span> /// @param _tokenId the NFT tokenID.</span></span> <span class="giallo-l"><span> function getPrivilegeIds(</span></span> <span class="giallo-l"><span> uint256 _tokenId</span></span> <span class="giallo-l"><span> ) external view returns (uint256[] memory privilegeIds);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The function <code>exercisePrivilege</code> performs the exercise action to a specific privilege of a token. If succeeds, it is expected to emit a <code>PrivilegeExercised</code> event.</p> <p>The function <code>getPrivilegeIds</code> provides a way to manage the binding relationship between NFTs and privilegeIds.</p> <p>The <strong>metadata extension</strong> is OPTIONAL for <a href="https://wg-eips.ritovision.com/7765/">EIP-7765</a> smart contracts. This allows your smart contract to be interrogated for its details about the privileges which your NFTs carry.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pragma solidity &gt;=0.7.0 &lt;0.9.0;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/// @title ERC-7765 Privileged Non-Fungible Tokens Tied To Real World Assets, optional metadata extension</span></span> <span class="giallo-l"><span>/// @dev See https://eips.ethereum.org/EIPS/eip-7765</span></span> <span class="giallo-l"><span>interface IERC7765Metadata /* is IERC7765 */ {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice A distinct Uniform Resource Identifier (URI) for a given privilegeId.</span></span> <span class="giallo-l"><span> /// @dev Throws if `_privilegeId` is not a valid privilegeId. URIs are defined in RFC</span></span> <span class="giallo-l"><span> /// 3986. The URI may point to a JSON file that conforms to the &quot;ERC-7765</span></span> <span class="giallo-l"><span> /// Metadata JSON Schema&quot;.</span></span> <span class="giallo-l"><span> function privilegeURI(uint256 _privilegeId) external view returns (string memory);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This is the “EIP-7765 Metadata JSON Schema” referenced above.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;Privilege Metadata&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;object&quot;,</span></span> <span class="giallo-l"><span> &quot;properties&quot;: {</span></span> <span class="giallo-l"><span> &quot;name&quot;: {</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Identifies the specific privilege.&quot;</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;description&quot;: {</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Describes the specific privilege.&quot;</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;resource&quot;: {</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;A URI pointing to a resource representing the specific privilege.&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><code>IERC7765Metadata</code> provides specifications for obtaining metadata information of privileges. A contract that implements <code>IERC7765Metadata</code> <strong>SHALL</strong> also implement <code>IERC7765</code>.</p> <h2 id="rationale">Rationale</h2> <ol> <li> <p>With the <code>PrivilegeExercised</code> event emitted onchain, we can determine that the user has confirmed the exercise of this privilege, so as to implement the privilege in the real world.</p> </li> <li> <p>We choose to include an address <code>_to</code> for functions <code>exercisePrivilege</code>, <code>isExercisable</code> and <code>isExercised</code> so that a specific privilege of an NFT MAY be exercised for someone who will benefit from it other than the NFT holder nor the transaction initiator. And This EIP doesn't assume who has the power to perform this action, it's totally decided by the developers who are using this standard.</p> </li> <li> <p>We choose to include an extra <code>_data</code> field to function <code>exercisePrivilege</code> for extra message or future extension. For example, developers can use <code>_data</code> to exercise a privilege that takes effect directly onchain such as direct distribution of cryptocurrency assets.</p> </li> <li> <p>The boolean view functions of <code>isExercisable</code> and <code>isExercised</code> can be used to check whether a specific privilege of an NFT can be exercisable or has been exercised to the <code>_to</code> address.</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is an extension of ERC-721. It is fully compatible with both of the commonly used optional extensions (<code>IERC721Metadata</code> and <code>IERC721Enumerable</code>) mentioned in the ERC-721 standard.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation of Privileged NFTs can be found <a href="https://wg-eips.ritovision.com/7765/./assets/contracts/ERC7765Example.sol">Here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Compliant contracts should pay attention to the storage to the states of the privileges. The contract should properly handle the state transition of each privilege of each NFT, clearly showing that each privilege is exercisable or has been exercised.</p> <p>Compliant contracts should also carefully define access control, particularly whether any EOA or contract account may or may not call <code>exercisePrivilege</code> function in any use case. Security audits and tests should be used to verify that the access control to the <code>exercisePrivilege</code> function behaves 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> 2024-08-19T00:00:00+00:00 2026-02-11T14:48:25+00:00 Atarparahttps://github.com/Atarpara JT Rileyhttps://github.com/jtriley-eth Thomashttps://github.com/0xth0mas xiaobaiskillhttps://github.com/xiaobaiskill Vectorizedhttps://github.com/Vectorized https://wg-eips.ritovision.com/7760/

Minimal upgradeable proxies with immutable arguments and support for onchain implementation queries

<h2 id="abstract">Abstract</h2> <p>This standard defines minimal <a href="https://wg-eips.ritovision.com/1967/">ERC-1967</a> proxies for three patterns: (1) transparent, (2) UUPS, (3) beacon. The proxies support optional immutable arguments which are appended to the end of their runtime bytecode. Additional variants which support onchain implementation querying are provided.</p> <h2 id="motivation">Motivation</h2> <p>Having standardized minimal bytecode for upgradeable proxies enables the following:</p> <ol> <li>Automatic verification on block explorers.</li> <li>Ability for immutable arguments to be queried onchain, as these arguments are stored at the same bytecode offset,</li> <li>Ability for the implementation to be queried and verified onchain.</li> </ol> <p>The minimal nature of the proxies enables cheaper deployment and runtime costs.</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="general-specifications">General specifications</h3> <p>All of the following proxies MAY have optional data bytecode appended to the end of their runtime bytecode.</p> <p>Emitting the ERC-1967 events during initialization is OPTIONAL. Indexers MUST NOT expect the initialization code to emit the ERC-1967 events.</p> <h3 id="onchain-querying-of-implementation-for-i-variants">Onchain querying of implementation for I-variants</h3> <p>The I-variants have logic that returns the implementation baked into their bytecode.</p> <p>When called with any 1-byte calldata, these I-variants will return the address (left-zero-padded to 32 bytes) and will not forward the calldata to the target.</p> <p>The bytecode of the proxies before any optional immutable arguments MUST be verified with the following steps:</p> <ol> <li>Fetch the bytecode before any immutable arguments with <code>EXTCODECOPY</code>.</li> <li>Zeroize any baked-in factory address in the fetched bytecode.</li> <li>Ensure that the hash of the final fetched bytecode matches the expected hash of the bytecode.</li> </ol> <p>If the hash does not match, the implementation address returned MUST NOT be trusted.</p> <h3 id="minimal-erc-1967-transparent-upgradeable-proxy">Minimal ERC-1967 transparent upgradeable proxy</h3> <p>The transparent upgradeable proxy is RECOMMENDED to be deployed by a factory that doubles as the account that is authenticated to perform upgrades. An externally owned account may perform the deployment on behalf of the factory. For convention, we will refer to the factory as the immutable account authorized to invoke the upgrade logic on the proxy.</p> <p>As the proxy's runtime bytecode contains logic to allow the factory to set any storage slot with any value, the initialization code MAY skip storing the implementation slot.</p> <p>The upgrading logic does not emit the ERC-1967 event. Indexers MUST NOT expect the upgrading logic to emit the ERC-1967 events.</p> <p>During upgrades, the factory MUST call the upgradeable proxy with following calldata:</p> <pre class="giallo z-code"><code data-lang="solidity"><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-comment"> //</span><span class="z-comment"> The new implementation address, converted to a 32-byte word.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint160</span><span>(</span><span>implementation</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ERC-1967 implementation slot.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Optional calldata to be forwarded to the implementation</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> via delegatecall after setting the implementation slot.</span></span> <span class="giallo-l"><span class="z-string"> &quot;&quot;</span></span> <span class="giallo-l"><span>)</span></span></code></pre><h4 id="minimal-erc-1967-transparent-upgradeable-proxy-for-basic-variant">Minimal ERC-1967 transparent upgradeable proxy for (basic variant)</h4> <p>Runtime bytecode (20-byte factory address subvariant):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>3d3d3373________________________________________14605757363d3d37363d7f360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc545af43d6000803e6052573d6000fd5b3d6000f35b3d356020355560408036111560525736038060403d373d3d355af43d6000803e6052573d6000fd</span></span></code></pre> <p>where <code>________________________________________</code> is the 20-byte factory address.</p> <p>Runtime bytecode (14-byte factory address subvariant):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>3d3d336d____________________________14605157363d3d37363d7f360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc545af43d6000803e604c573d6000fd5b3d6000f35b3d3560203555604080361115604c5736038060403d373d3d355af43d6000803e604c573d6000fd</span></span></code></pre> <p>where <code>____________________________</code> is the 14-byte factory address.</p> <h4 id="minimal-erc-1967-transparent-upgradeable-proxy-i-variant">Minimal ERC-1967 transparent upgradeable proxy (I-variant)</h4> <p>Runtime bytecode (20-byte factory address subvariant):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>3658146083573d3d3373________________________________________14605D57363d3d37363D7f360894a13ba1A3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc545af43d6000803e6058573d6000fd5b3d6000f35b3d35602035556040360380156058578060403d373d3d355af43d6000803e6058573d6000fd5b602060293d393d51543d52593df3</span></span></code></pre> <p>where <code>________________________________________</code> is the 20-byte factory address.</p> <p>Runtime bytecode (14-byte factory address subvariant):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>365814607d573d3d336d____________________________14605757363d3D37363d7F360894A13Ba1A3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc545af43d6000803e6052573d6000fd5b3d6000f35b3d35602035556040360380156052578060403d373d3d355af43d6000803e6052573d6000fd5b602060233d393d51543d52593df3</span></span></code></pre> <p>where <code>____________________________</code> is the 14-byte factory address.</p> <h3 id="minimal-erc-1967-uups-proxy">Minimal ERC-1967 UUPS proxy</h3> <p>As this proxy does not contain upgrading logic, the initialization code MUST store the implementation at the ERC-1967 implementation storage slot <code>0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc</code>.</p> <h4 id="minimal-erc-1967-uups-proxy-basic-variant">Minimal ERC-1967 UUPS proxy (basic variant)</h4> <p>Runtime bytecode:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>363d3d373d3d363d7f360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc545af43d6000803e6038573d6000fd5b3d6000f3</span></span></code></pre><h4 id="minimal-erc-1967-uups-proxy-i-variant">Minimal ERC-1967 UUPS proxy (I-variant)</h4> <p>Runtime bytecode:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>365814604357363d3d373d3d363d7f360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc545af43d6000803e603e573d6000fd5b3d6000f35b6020600f3d393d51543d52593df3</span></span></code></pre><h3 id="minimal-erc-1967-beacon-proxy">Minimal ERC-1967 beacon proxy</h3> <p>As this proxy does not contain upgrading logic, the initialization code MUST store the implementation at the ERC-1967 implementation storage slot <code>0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc</code>.</p> <h4 id="minimal-erc-1967-beacon-proxy-basic-variant">Minimal ERC-1967 beacon proxy (basic variant)</h4> <p>Runtime bytecode:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>363d3d373d3d363d602036600436635c60da1b60e01b36527fa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50545afa5036515af43d6000803e604d573d6000fd5b3d6000f3</span></span></code></pre><h4 id="minimal-erc-1967-beacon-proxy-i-variant">Minimal ERC-1967 beacon proxy (I-variant)</h4> <p>Runtime bytecode:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>363d3d373d3d363d602036600436635c60da1b60e01b36527fa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50545afa361460525736515af43d600060013e6052573d6001fd5b3d6001f3</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="no-usage-of-push0-opcode">No usage of <code>PUSH0</code> opcode</h3> <p>For more widespread EVM compatibility, the proxies deliberately do not use the <code>PUSH0</code> opcode proposed in <a href="https://wg-eips.ritovision.com/3855/">EIP-3855</a>.</p> <p>Converting the proxies to <code>PUSH0</code> variants may be done in a separate future ERC.</p> <h3 id="optimization-priorities">Optimization priorities</h3> <p>The proxies are first optimized for minimal runtime gas before minimal bytecode size.</p> <h3 id="minimal-nature">Minimal nature</h3> <p>These proxies made from handcrafted EVM bytecode. While utmost efforts have been made to ensure that they are as minimal as possible at the time of development, it is possible that they can be further optimized. If a variant has already been used in the wild, it is preferable to keep their existing layout in this standard, as the benefits of automatic block explorer verification will outweigh the few gas saved during runtime or deployment.</p> <p>For historical reference, the <a href="https://wg-eips.ritovision.com/1167/">ERC-1167</a> minimal proxy was not the theoretical minimal at the time of writing. The 0age minimal proxy has lower runtime gas costs and smaller bytecode size.</p> <h3 id="transparent-upgradeable-proxy">Transparent upgradeable proxy</h3> <p>The factory address in the transparent upgradeable proxy is baked into the immutable bytecode of the minimal transparent upgradeable proxy.</p> <p>This is to save a <code>SLOAD</code> for every proxy call.</p> <p>As the factory can contain custom authorization logic that allows for admin rotation, we do not lose any flexibility.</p> <p>The upgrade logic takes in any 32 byte value and 32 byte storage slot. This is for flexibility and bytecode conciseness.</p> <p>We do not lose any security as the implementation can still modify any storage slot.</p> <h3 id="14-byte-factory-address-subvariants">14-byte factory address subvariants</h3> <p>It is beneficial to install the transparent upgradeable proxy factory at a vanity address with leading zero bytes so that the proxy's bytecode can be optimized to be shorter.</p> <p>A 14-byte factory address (i.e. 6 leading zero bytes) is chosen because it strikes a balance between mining costs and bytecode size.</p> <h3 id="i-variants">I-variants</h3> <p>The so-called "I-variants" contain logic that returns the implementation address baked into the proxy bytecode.</p> <p>This allows contracts to retrieve the implementation of the proxy onchain in a verifiable way.</p> <p>As long as the proxy's runtime bytecode starts with the bytecode in this standard, we can be sure that the implementation address is not spoofed.</p> <p>The choice of reserving 1-byte calldata to denote an implementation query request is for efficiency and to prevent calldata collision. Regular ETH transfers use 0-byte calldata, and regular Solidity function calls use calldata that is 4 bytes or longer.</p> <h3 id="omission-of-events-in-bytecode">Omission of events in bytecode</h3> <p>This is for minimal bytecode size and deployment costs.</p> <p>Most block explorers and indexers are able to deduce the latest implementation without the use of events simply by reading the slots.</p> <h3 id="immutable-arguments-are-not-appended-to-forwarded-calldata">Immutable arguments are not appended to forwarded calldata</h3> <p>This is to avoid compatibility and safety issues with other ERC standards that append extra data to the calldata.</p> <p>The <code>EXTCODECOPY</code> opcode can be used to retrieve the immutable arguments.</p> <h3 id="no-fixed-initialization-code">No fixed initialization code</h3> <p>As long as the initialization code is able to initialize the relevant ERC-1967 implementation slot where needed (i.e. for the UUPS proxy and Beacon proxy), there is no need for additional requirements on the initialization code.</p> <h3 id="out-of-scope-topics">Out of scope topics</h3> <p>The following topics are intentionally out of scope of this standard, as they can contain custom logic:</p> <ul> <li>Factories for proxy deployment.</li> <li>Logic for reading and verifying the implementation from the I-variants onchain.</li> <li>Beacon for the beacon proxies.</li> </ul> <p>Nevertheless, they require careful implementation to ensure security and correctness.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="minimal-erc-1967-transparent-upgradeable-proxy-implementation">Minimal ERC-1967 transparent upgradeable proxy implementation</h3> <h4 id="minimal-erc-1967-transparent-upgradeable-proxy-implementation-basic-variant">Minimal ERC-1967 transparent upgradeable proxy implementation (basic variant)</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.8.0</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"> ERC1967MinimalTransparentUpgradeableProxyLib</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> initCodeFor20ByteFactoryAddress</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">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 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-support"> bytes13</span><span>(</span><span class="z-constant">0x607f3d8160093d39f33d3d3373</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 class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x14605757363d3d37363d7f360894a13ba1a3210667c828492db98dca3e2076cc</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x3735a920a3ca505d382bbc545af43d6000803e6052573d6000fd5b3d6000f35b</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x3d356020355560408036111560525736038060403d373d3d355af43d6000803e</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes7</span><span>(</span><span class="z-constant">0x6052573d6000fd</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"> initCodeFor14ByteFactoryAddress</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">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 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-support"> bytes13</span><span>(</span><span class="z-constant">0x60793d8160093d39f33d3d336d</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint112</span><span>(</span><span class="z-support">uint160</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></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x14605157363d3d37363d7f360894a13ba1a3210667c828492db98dca3e2076cc</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x3735a920a3ca505d382bbc545af43d6000803e604c573d6000fd5b3d6000f35b</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x3d3560203555604080361115604c5736038060403d373d3d355af43d6000803e</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes7</span><span>(</span><span class="z-constant">0x604c573d6000fd</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"> initCode</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">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-support">uint160</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-keyword"> &gt;&gt;</span><span class="z-constant"> 112</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-entity z-name"> initCodeFor20ByteFactoryAddress</span><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-keyword"> return</span><span class="z-entity z-name"> initCodeFor14ByteFactoryAddress</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"> deploy</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"> memory</span><span class="z-variable"> initializationData</span><span>)</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-support">address</span><span class="z-variable"> instance</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> m </span><span class="z-keyword">=</span><span class="z-entity z-name"> initCode</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> instance </span><span class="z-keyword">:=</span><span class="z-entity z-name"> create</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>m</span><span>,</span><span class="z-constant"> 0x20</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>m</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>instance </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;Deployment failed.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> upgrade</span><span>(</span><span>instance</span><span>,</span><span> implementation</span><span>,</span><span> initializationData</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">address</span><span class="z-variable"> instance</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"> memory</span><span class="z-variable"> upgradeData</span><span>)</span><span class="z-storage z-type"> internal</span><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> instance</span><span>.</span><span class="z-entity z-name">call</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-comment"> //</span><span class="z-comment"> The new implementation address, converted to a 32-byte word.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint160</span><span>(</span><span>implementation</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ERC-1967 implementation slot.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Optional calldata to be forwarded to the implementation</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> via delegatecall after setting the implementation slot.</span></span> <span class="giallo-l"><span> upgradeData</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>success</span><span>,</span><span class="z-string"> &quot;Upgrade failed.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="minimal-erc-1967-transparent-upgradeable-proxy-implementation-i-variant">Minimal ERC-1967 transparent upgradeable proxy implementation (I-variant)</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.8.0</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"> ERC1967IMinimalTransparentUpgradeableProxyLib</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> initCodeFor20ByteFactoryAddress</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">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 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-support"> bytes19</span><span>(</span><span class="z-constant">0x60923d8160093d39f33658146083573d3d3373</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 class="z-support"> bytes20</span><span>(</span><span class="z-constant">0x14605D57363d3d37363D7f360894a13ba1A32106</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x67c828492db98dca3e2076cc3735a920a3ca505d382bbc545af43d6000803e60</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x58573d6000fd5b3d6000f35b3d35602035556040360380156058578060403d37</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x3d3d355af43d6000803e6058573d6000fd5b602060293d393d51543d52593df3</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"> initCodeFor14ByteFactoryAddress</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">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 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-support"> bytes19</span><span>(</span><span class="z-constant">0x608c3d8160093d39f3365814607d573d3d336d</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint112</span><span>(</span><span class="z-support">uint160</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></span> <span class="giallo-l"><span class="z-support"> bytes20</span><span>(</span><span class="z-constant">0x14605757363d3D37363d7F360894A13Ba1A32106</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x67c828492db98dca3e2076cc3735a920a3ca505d382bbc545af43d6000803e60</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x52573d6000fd5b3d6000f35b3d35602035556040360380156052578060403d37</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x3d3d355af43d6000803e6052573d6000fd5b602060233d393d51543d52593df3</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"> initCode</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">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-support">uint160</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-keyword"> &gt;&gt;</span><span class="z-constant"> 112</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-entity z-name"> initCodeFor20ByteFactoryAddress</span><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-keyword"> return</span><span class="z-entity z-name"> initCodeFor14ByteFactoryAddress</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"> deploy</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"> memory</span><span class="z-variable"> initializationData</span><span>)</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-support">address</span><span class="z-variable"> instance</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> m </span><span class="z-keyword">=</span><span class="z-entity z-name"> initCode</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> instance </span><span class="z-keyword">:=</span><span class="z-entity z-name"> create</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>m</span><span>,</span><span class="z-constant"> 0x20</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>m</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>instance </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;Deployment failed.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> upgrade</span><span>(</span><span>instance</span><span>,</span><span> implementation</span><span>,</span><span> initializationData</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">address</span><span class="z-variable"> instance</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"> memory</span><span class="z-variable"> upgradeData</span><span>)</span><span class="z-storage z-type"> internal</span><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> instance</span><span>.</span><span class="z-entity z-name">call</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-comment"> //</span><span class="z-comment"> The new implementation address, converted to a 32-byte word.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint160</span><span>(</span><span>implementation</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ERC-1967 implementation slot.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Optional calldata to be forwarded to the implementation</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> via delegatecall after setting the implementation slot.</span></span> <span class="giallo-l"><span> upgradeData</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>success</span><span>,</span><span class="z-string"> &quot;Upgrade failed.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="minimal-erc-1967-uups-proxy-implementation">Minimal ERC-1967 UUPS proxy implementation</h3> <h4 id="minimal-erc-1967-uups-proxy-implementation-basic-variant">Minimal ERC-1967 UUPS proxy implementation (basic variant)</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.8.0</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"> ERC1967MinimalUUPSProxyLib</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> initCode</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"> memory</span><span class="z-variable"> args</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> internal</span></span> <span class="giallo-l"><span class="z-storage z-type"> pure</span></span> <span class="giallo-l"><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 class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> n </span><span class="z-keyword">=</span><span class="z-constant"> 0x003d</span><span class="z-keyword"> +</span><span> args</span><span>.</span><span>length</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>n </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span class="z-constant"> 0xffff</span><span>,</span><span class="z-string"> &quot;Immutable args too long.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</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-support"> bytes1</span><span>(</span><span class="z-constant">0x61</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint16</span><span>(</span><span>n</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes7</span><span>(</span><span class="z-constant">0x3d8160233d3973</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> implementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes2</span><span>(</span><span class="z-constant">0x6009</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x5155f3363d3d373d3d363d7f360894a13ba1a3210667c828492db98dca3e2076</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0xcc3735a920a3ca505d382bbc545af43d6000803e6038573d6000fd5b3d6000f3</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> args</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"> deploy</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"> memory</span><span class="z-variable"> args</span><span>)</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-support">address</span><span class="z-variable"> instance</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> m </span><span class="z-keyword">=</span><span class="z-entity z-name"> initCode</span><span>(</span><span>implementation</span><span>,</span><span> args</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> instance </span><span class="z-keyword">:=</span><span class="z-entity z-name"> create</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>m</span><span>,</span><span class="z-constant"> 0x20</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>m</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>instance </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;Deployment failed.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="minimal-erc-1967-uups-proxy-implementation-i-variant">Minimal ERC-1967 UUPS proxy implementation (I-variant)</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.8.0</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"> ERC1967IMinimalUUPSProxyLib</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> initCode</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"> memory</span><span class="z-variable"> args</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> internal</span></span> <span class="giallo-l"><span class="z-storage z-type"> pure</span></span> <span class="giallo-l"><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 class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> n </span><span class="z-keyword">=</span><span class="z-constant"> 0x0052</span><span class="z-keyword"> +</span><span> args</span><span>.</span><span>length</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>n </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span class="z-constant"> 0xffff</span><span>,</span><span class="z-string"> &quot;Immutable args too long.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</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-support"> bytes1</span><span>(</span><span class="z-constant">0x61</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint16</span><span>(</span><span>n</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes7</span><span>(</span><span class="z-constant">0x3d8160233d3973</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> implementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes23</span><span>(</span><span class="z-constant">0x600f5155f3365814604357363d3d373d3d363d7f360894</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0xa13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc545af4</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x3d6000803e603e573d6000fd5b3d6000f35b6020600f3d393d51543d52593df3</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> args</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"> deploy</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"> memory</span><span class="z-variable"> args</span><span>)</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-support">address</span><span class="z-variable"> instance</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> m </span><span class="z-keyword">=</span><span class="z-entity z-name"> initCode</span><span>(</span><span>implementation</span><span>,</span><span> args</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> instance </span><span class="z-keyword">:=</span><span class="z-entity z-name"> create</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>m</span><span>,</span><span class="z-constant"> 0x20</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>m</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>instance </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;Deployment failed.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="minimal-erc-1967-beacon-proxy-implementation">Minimal ERC-1967 beacon proxy implementation</h3> <h4 id="minimal-erc-1967-beacon-proxy-implementation-basic-variant">Minimal ERC-1967 beacon proxy implementation (basic variant)</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.8.0</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"> ERC1967MinimalBeaconProxyLib</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> initCode</span><span>(</span><span class="z-support">address</span><span class="z-variable"> beacon</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> args</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">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> n </span><span class="z-keyword">=</span><span class="z-constant"> 0x0052</span><span class="z-keyword"> +</span><span> args</span><span>.</span><span>length</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>n </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span class="z-constant"> 0xffff</span><span>,</span><span class="z-string"> &quot;Immutable args too long.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</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-support"> bytes1</span><span>(</span><span class="z-constant">0x61</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint16</span><span>(</span><span>n</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes7</span><span>(</span><span class="z-constant">0x3d8160233d3973</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> beacon</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes23</span><span>(</span><span class="z-constant">0x60195155f3363d3d373d3d363d602036600436635c60da</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x1b60e01b36527fa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6c</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0xb3582b35133d50545afa5036515af43d6000803e604d573d6000fd5b3d6000f3</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> args</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"> deploy</span><span>(</span><span class="z-support">address</span><span class="z-variable"> beacon</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> args</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> instance</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> m </span><span class="z-keyword">=</span><span class="z-entity z-name"> initCode</span><span>(</span><span>beacon</span><span>,</span><span> args</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> instance </span><span class="z-keyword">:=</span><span class="z-entity z-name"> create</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>m</span><span>,</span><span class="z-constant"> 0x20</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>m</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>instance </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;Deployment failed.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="minimal-erc-1967-beacon-proxy-implementation-i-variant">Minimal ERC-1967 beacon proxy implementation (I-variant)</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.8.0</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"> ERC1967IMinimalBeaconProxyLib</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> initCode</span><span>(</span><span class="z-support">address</span><span class="z-variable"> beacon</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> args</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">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> n </span><span class="z-keyword">=</span><span class="z-constant"> 0x0057</span><span class="z-keyword"> +</span><span> args</span><span>.</span><span>length</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>n </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span class="z-constant"> 0xffff</span><span>,</span><span class="z-string"> &quot;Immutable args too long.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</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-support"> bytes1</span><span>(</span><span class="z-constant">0x61</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint16</span><span>(</span><span>n</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes7</span><span>(</span><span class="z-constant">0x3d8160233d3973</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> beacon</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes28</span><span>(</span><span class="z-constant">0x60195155f3363d3d373d3d363d602036600436635c60da1b60e01b36</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x527fa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b3513</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0x3d50545afa361460525736515af43d600060013e6052573d6001fd5b3d6001f3</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> args</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"> deploy</span><span>(</span><span class="z-support">address</span><span class="z-variable"> beacon</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> args</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> instance</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> m </span><span class="z-keyword">=</span><span class="z-entity z-name"> initCode</span><span>(</span><span>beacon</span><span>,</span><span> args</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> instance </span><span class="z-keyword">:=</span><span class="z-entity z-name"> create</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>m</span><span>,</span><span class="z-constant"> 0x20</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>m</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>instance </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;Deployment failed.&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> <h3 id="transparent-upgradeable-proxy-factory-security-considerations">Transparent upgradeable proxy factory security considerations</h3> <p>To ensure security, the transparent upgradeable proxy factory must implement proper access control to allow proxies to be upgraded by only authorized accounts.</p> <h3 id="calldata-length-collision-for-i-variants">Calldata length collision for I-variants</h3> <p>The I-variants reserve all calldata of length 1 to denote a request to return the implementation. This may pose compatibility issues if the underlying implementation actually uses 1-byte calldata for special purposes.</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-08-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Charles Cooperhttps://github.com/charles-cooper pcaversacciohttps://github.com/pcaversaccio https://wg-eips.ritovision.com/7791/

Introduces a new opcode, `GAS2ETH`, to convert gas to ETH

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a new <code>GAS2ETH</code> opcode that enables the direct conversion of gas into ether (ETH).</p> <h2 id="motivation">Motivation</h2> <p>This EIP is based on the premise that smart contract authors, compiler teams, and public goods projects in general should be compensated for their contributions. Moreover, their compensation should <em>scale</em> with the usage of their contracts. A widely used and popular contract offers significant value to its users through its functionality and to the network by driving demand for blockspace — Ethereum's <em>raison d'être</em>. This increased demand also benefits miners and validators, who are rewarded for executing these contracts.</p> <p>Monetizing smart contracts in a scalable manner remains challenging at the time of this writing. This difficulty is evident from existence of many different monetization strategies employed across various smart contracts — ranging from fee structures to the issuance of tokens with "tokenomics" of varying levels of complexity. Additionally, many public goods projects struggle to secure funding.</p> <p>Introducing the <code>GAS2ETH</code> opcode offers contract authors, as well as the tools they use, a new way to achieve their monetization objectives. By charging gas, they integrate with an established user experience that is both familiar and understood by users. The proposed instruction ensures that existing transaction creation and processing tools remain unchanged. Moreover, by charging gas, contract authors align economically with network activity; they benefit from higher compensation during periods of intense network usage and receive less when activity is low. This helps align the incentives of smart contract authors, validators, and the broader network.</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 opcode, <code>GAS2ETH</code> (<code>0xFC</code>), is introduced to enable direct conversion of gas into ETH within the EVM. This opcode operates under a new budgeting mechanism: each transaction maintains a <em>global</em> <code>GAS2ETH</code> budget initialized to the transaction gas limit (<code>tx.gas_limit</code>), and each call frame derives a <em>local</em> allowance from the gas forwarded to it. These budgets cap the total amount of gas that can be converted into ETH, both per call frame and across the entire transaction.</p> <h3 id="execution-semantics">Execution Semantics</h3> <p>The <code>GAS2ETH</code> (<code>0xFC</code>) opcode executes according to the following rules:</p> <ul> <li>Pops two values from the stack: <code>addr</code> then <code>gas_amount</code>. If there are fewer than two values on the stack, the calling context MUST fail with stack underflow.</li> <li>Deducts <code>gas_amount</code> from both the current call frame's local <code>GAS2ETH</code> allowance and the transaction-global <code>GAS2ETH</code> budget. <ul> <li>If <code>gas_amount</code> is greater than the current call frame's local <code>GAS2ETH</code> allowance or the remaining transaction-global <code>GAS2ETH</code> budget, set <code>gas_amount</code> to <code>min(gas_amount, remaining_local_allowance, remaining_global_GAS2ETH_budget)</code>.</li> </ul> </li> <li>Computes <code>wei_val</code> by multiplying <code>gas_amount</code> by the current transaction context's <code>gas_price</code> (<a rel="external" href="https://github.com/ethereum/execution-specs/blob/98d6ddaaa709a2b7d0cd642f4cfcdadc8c0808e1/src/ethereum/cancun/vm/instructions/environment.py#L325">EELS</a>).</li> <li>Endows the address <code>addr</code> with <code>wei_val</code> wei.</li> <li>Pushes <code>wei_val</code> onto the stack.</li> </ul> <p>On reverts (e.g., through the <code>REVERT</code> opcode or any exceptional halt), any gas paid out via <code>GAS2ETH</code> MUST be refunded to both the transaction-global and the parent call frame's budgets.</p> <p>Note that the transfer of <code>wei_val</code> to the target account cannot fail. In particular, the destination account code (if any) is not executed, or, if the account does not exist, the balance is still added to the given address <code>addr</code>.</p> <p>Gas consumed by <code>GAS2ETH</code> does not affect the base fee, burn, block <code>gasUsed</code>, or the transaction fee. Instead, the ETH transfer represents a direct payment from the transaction signer (i.e. <code>tx.origin</code>) to the recipient address, outside the block reward and fee accounting mechanisms. This ensures no duplication of ETH between the <code>COINBASE</code> reward and the amount transferred via <code>GAS2ETH</code>.</p> <h3 id="gas2eth-budgeting-model"><code>GAS2ETH</code> Budgeting Model</h3> <p>A transaction maintains a single global <code>GAS2ETH</code> budget initialized to the transaction gas limit (<code>tx.gas_limit</code>). Each call frame also maintains a local allowance, derived automatically from the gas forwarded to it:</p> <ul> <li>On <code>CALL</code>, <code>CALLCODE</code>, or <code>STATICCALL</code>: <code>allowance = min(forwarded_gas, remaining_global_GAS2ETH_budget)</code>.</li> <li>On <code>DELEGATECALL</code>: the callee shares the caller's allowance.</li> <li>On revert: all <code>GAS2ETH</code> deductions within that call frame are refunded to both the transaction-global and parent frame's budgets.</li> <li>On normal return: any unused local allowance is returned to the transaction-global <code>GAS2ETH</code> budget.</li> </ul> <p>This model ensures that untrusted callees cannot consume more <code>GAS2ETH</code> than the gas explicitly forwarded to them, while keeping total <code>GAS2ETH</code> creation bounded by the transaction's gas limit.</p> <h3 id="gas-cost">Gas cost</h3> <p>The proposed cost of this opcode is identical to the recently proposed <code>PAY</code> opcode.</p> <h4 id="constants">Constants</h4> <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> <h4 id="gas-calculation">Gas calculation</h4> <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> <h2 id="rationale">Rationale</h2> <ul> <li><code>GAS2ETH</code> vs. pro-rata: The pro-rata model incentivizes inflating contract gas usage to artificially increase fees. In contrast, this proposal allows contract authors to charge their desired amount directly, eliminating the need for unnecessary gas consumption.</li> <li>Target address vs. simply increasing balance of the currently executing contract: Using a target address is more flexible, enabling contract authors to write more modular code and separate the concerns of fee collection from contract functionality. For instance, the contract may want to designate a specific recipient for fees without necessarily granting them direct withdrawal access.</li> <li>Charging gas instead of ETH: Charging ETH directly complicates the user experience and prevents contract authors from participating in fluctuations in gas demand directly.</li> <li>For the value of <code>gas_price</code>, use the same gas price as which is used to calculate the tx cost in ETH. This leads to the most consistent computation between <code>GAS2ETH</code> and the user's experience when creating a transaction.</li> <li>Separate budget: Having a separate budget prevents certain types of DoS attacks where usage of <code>GAS2ETH</code> can interfere with the actual budget needed for execution of the contract. (For example, a target contract can "waste" gas with <code>GAS2ETH</code>, resulting in the caller not having enough gas to finish execution). This also results in <code>GAS2ETH</code> usage not affecting the burn rate. The intuition is that, since it doesn't actually use computational resources (which gas normally "accounts" for), it shouldn't affect blockspace computations or the base fee.</li> <li>Budget being 100% of the gas limit: 100% of the gas limit is a "natural" bound on the gas used and provides some protection to the user from unbounded <code>GAS2ETH</code> spending. In the future, a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a>-based transaction type could be added which includes an explicitly user-specified <code>GAS2ETH</code> budget.</li> <li>No exceptional halt when <code>gas_amount</code> exceeds the remaining budgets, both the current call frame's local <code>GAS2ETH</code> allowance and the transaction-global <code>GAS2ETH</code> budget. Since these budgets are not introspectable, the contract would otherwise have no way to gracefully avoid an exceptional halt.</li> <li>Bounding by execution gas ensures that untrusted callees cannot consume more <code>GAS2ETH</code> than the gas explicitly forwarded to them.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</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>Like the <a href="https://wg-eips.ritovision.com/5920/"><code>PAY</code></a> opcode and <a href="https://wg-eips.ritovision.com/4895/">beacon withdrawals</a>, <code>GAS2ETH</code> enables ETH transfers that occur without code execution in the recipient account. To prevent denial-of-service (DoS) attacks from untrusted callees, each call frame receives a local <code>GAS2ETH</code> allowance automatically derived from the gas <em>forwarded</em> to it, while a transaction-global <code>GAS2ETH</code> budget enforces an overall cap equal to the transaction's gas limit. This ensures that:</p> <ul> <li>Callees cannot deplete the sender's <code>GAS2ETH</code> budget beyond the gas explicitly forwarded to them.</li> <li>Contracts calling into untrusted code remain robust, as the callee's <code>GAS2ETH</code> spending capacity is naturally limited by its gas stipend.</li> <li>The total ETH that can be created via <code>GAS2ETH</code> in a transaction is strictly bounded.</li> </ul> <p>It's important to note that <code>GAS2ETH</code> introduces an economic incentive for malicious contracts to consume as much of their allowance as possible, converting previously non-profitable griefing vectors into potentially profitable ones. Contract authors SHOULD minimize forwarded gas and <code>GAS2ETH</code> exposure when interacting with untrusted code, similar to existing best practices for limiting gas stipends or ETH transfers.</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-06T00:00:00+00:00 2026-02-11T14:48:25+00:00 Daniel Gretzkehttps://github.com/gretzke Sara Reynoldshttps://github.com/snreynolds Alice Henshawhttps://github.com/hensha256 Marko Venigermarko.veniger@tenderly.co Hadrien Crouboishttps://github.com/Amxx https://wg-eips.ritovision.com/7751/

Handling bubbled up reverts using custom errors with additional context

<h2 id="abstract">Abstract</h2> <p>This ERC proposes a standard for handling bubbled up reverts in Ethereum smart contracts using a dedicated custom error. This standard aims to improve the clarity and usability of revert reasons by allowing additional context to be passed alongside the raw bytes of the bubbled up revert. The <code>WrappedError</code> custom error should wrap reverts from called contracts and provide a consistent interface for parsing and handling reverts in tools like Etherscan or Tenderly.</p> <h2 id="motivation">Motivation</h2> <p>Currently, when a smart contract calls another and the called contract reverts, the revert reason is usually bubbled up and thrown as is. This can make it more difficult to tell which context the error came from. By standardizing the use of custom errors with additional context, more meaningful and informative revert reasons can be provided. This will improve the debugging experience and make it easier for developers and infrastructure providers like Etherscan to display accurate stack traces.</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>In order to wrap a revert, a contract MUST revert with the following error that corresponds to the following signature <code>0x90bfb865</code>:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> WrappedError</span><span>(</span><span class="z-support">address</span><span> target</span><span>,</span><span class="z-support"> bytes4</span><span> selector</span><span>,</span><span class="z-support"> bytes</span><span> reason</span><span>,</span><span class="z-support"> bytes</span><span> details</span><span>)</span><span>;</span></span></code></pre> <p>Where:</p> <ul> <li><code>target</code> is the address of the called contract that reverted.</li> <li><code>selector</code> is the selector of the called function that reverted. If the call was an ETH transfer without any data, the selector MUST be <code>bytes4(0)</code></li> <li><code>reason</code> is the raw bytes of the revert reason.</li> <li><code>details</code> is optional additional context about the revert. In cases where no additional context is needed, the <code>details</code> bytes can be empty. In cases with additional context, the <code>details</code> bytes MUST be an ABI encoded custom error declared on the contract that emits the <code>WrappedError</code> error.</li> </ul> <h2 id="rationale">Rationale</h2> <p>By including the called contract and function, raw revert bytes and additional context, developers can provide more detailed information about the failure. Additionally, by standardizing the way reverts are bubbled up, it also enables nested bubbled up reverts where multiple reverts thrown by different contracts can be followed recursively. The reverts can also be parsed and handled by tools like Etherscan and Foundry to further enhance the readability and debuggability of smart contract interactions, as well as facilitating better error handling practices in general.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC does not introduce any backwards incompatibilities. Existing contracts can adopt this standard incrementally.</p> <h2 id="test-cases">Test Cases</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"> 0.8.26</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"> Token</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> balanceOf</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"> 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">uint</span><span class="z-variable"> amount</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"> 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"> 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-keyword"> require</span><span>(</span><span>balanceOf</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> amount</span><span>,</span><span class="z-string"> &quot;insufficient balance&quot;</span><span>)</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> amount</span><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> amount</span><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> 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> <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"> Vault</span><span> {</span></span> <span class="giallo-l"><span> Token token</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> WrappedError</span><span>(</span><span class="z-support">address</span><span> target</span><span>,</span><span class="z-support"> bytes4</span><span> selector</span><span>,</span><span class="z-support"> bytes</span><span> reason</span><span>,</span><span class="z-support"> bytes</span><span> details</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC20TransferFailed</span><span>(</span><span class="z-support">address</span><span> recipient</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"> constructor</span><span>(</span><span class="z-storage z-type">Token</span><span class="z-variable"> token_</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> token </span><span class="z-keyword">=</span><span> token_</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"> amount</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"> logic</span></span> <span class="giallo-l"><span class="z-keyword"> try</span><span> token</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>to</span><span>,</span><span> amount</span><span>)</span><span> {</span><span>}</span><span class="z-keyword"> catch</span><span> (</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-storage z-type"> error</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> WrappedError</span><span>(</span><span class="z-support">address</span><span>(</span><span>token</span><span>)</span><span>,</span><span> token</span><span>.</span><span>transfer</span><span>.</span><span>selector</span><span>,</span><span class="z-storage z-type"> error</span><span>,</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span>ERC20TransferFailed</span><span>.</span><span>selector</span><span>,</span><span> to</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">contract</span><span class="z-entity z-name"> Router</span><span> {</span></span> <span class="giallo-l"><span> Vault vault</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> WrappedError</span><span>(</span><span class="z-support">address</span><span> target</span><span>,</span><span class="z-support"> bytes4</span><span> selector</span><span>,</span><span class="z-support"> bytes</span><span> reason</span><span>,</span><span class="z-support"> bytes</span><span> details</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">Vault</span><span class="z-variable"> vault_</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> vault </span><span class="z-keyword">=</span><span> vault_</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">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 class="z-comment"> //</span><span class="z-comment"> logic</span></span> <span class="giallo-l"><span class="z-keyword"> try</span><span> vault</span><span>.</span><span class="z-entity z-name">withdraw</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> amount</span><span>)</span><span> {</span><span>}</span><span class="z-keyword"> catch</span><span> (</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-storage z-type"> error</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> WrappedError</span><span>(</span><span class="z-support">address</span><span>(</span><span>vault</span><span>)</span><span>,</span><span> vault</span><span>.</span><span>withdraw</span><span>.</span><span>selector</span><span>,</span><span class="z-storage z-type"> error</span><span>,</span><span class="z-string"> &quot;&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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Test</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> test_BubbledNestedReverts</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> Token token </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-entity z-name"> Token</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> Vault vault </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-entity z-name"> Vault</span><span>(</span><span>token</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> Router router </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-entity z-name"> Router</span><span>(</span><span>vault</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> try</span><span> router</span><span>.</span><span class="z-entity z-name">withdraw</span><span>(</span><span>amount</span><span>)</span><span> {</span><span>}</span><span class="z-keyword"> catch</span><span> (</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> thrownError</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> expectedError </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span></span> <span class="giallo-l"><span> Router</span><span>.</span><span>WrappedError</span><span>.</span><span>selector</span><span>,</span><span class="z-support"> address</span><span>(</span><span>vault</span><span>)</span><span>,</span><span> vault</span><span>.</span><span>withdraw</span><span>.</span><span>selector</span><span>,</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span></span> <span class="giallo-l"><span> Vault</span><span>.</span><span>WrappedError</span><span>.</span><span>selector</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>(</span><span>token</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> token</span><span>.</span><span>transfer</span><span>.</span><span>selector</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSignature</span><span>(</span><span class="z-string">&quot;Error(string)&quot;</span><span>,</span><span class="z-string"> &quot;insufficient balance&quot;</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span>Vault</span><span>.</span><span>ERC20TransferFailed</span><span>.</span><span>selector</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 class="giallo-l"><span> )</span><span>,</span><span class="z-string"> &quot;&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span>thrownError</span><span>)</span><span class="z-keyword"> ==</span><span class="z-support"> keccak256</span><span>(</span><span>expectedError</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="reference-implementation">Reference Implementation</h2> <p>When catching a revert from a called contract, the calling contract should revert with a custom error following the above conventions.</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"> Foo</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> WrappedError</span><span>(</span><span class="z-support">address</span><span> target</span><span>,</span><span class="z-support"> bytes4</span><span> selector</span><span>,</span><span class="z-support"> bytes</span><span> reason</span><span>,</span><span class="z-support"> bytes</span><span> details</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> MyCustomError</span><span>(</span><span class="z-support">uint256</span><span> x</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"> foo</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</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> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> logic</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bool</span><span> success</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> returnData</span><span>)</span><span class="z-keyword"> =</span><span> to</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span>data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> WrappedError</span><span>(</span><span>to</span><span>,</span><span class="z-support"> bytes4</span><span>(</span><span>data</span><span>)</span><span>,</span><span> returnData</span><span>,</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span>MyCustomError</span><span>.</span><span>selector</span><span>,</span><span class="z-constant"> 42</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="security-considerations">Security Considerations</h2> <p>Smart contracts could either drop or purposefully suppress the bubbled up reverts along the revert chain. Additionally, smart contracts may also lie or incorrectly report the wrapped reverts, so the information is not guaranteed to be accurate.</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-04T00:00:00+00:00 2026-02-11T14:48:25+00:00 James Savechiveshttps://github.com/jamesavechivesjames.walstonn@gmail.com https://wg-eips.ritovision.com/7750/

An employment system that records employment history.

<h2 id="abstract">Abstract</h2> <p>This ERC proposes a Decentralized Employment System (DES) built on the Ethereum blockchain. The DES facilitates the creation and management of companies, records comprehensive employment histories through unique employee tokens, enables the formation and execution of labor contracts, automates salary payments via an escrow mechanism, incorporates a robust moderation system for dispute resolution, and implements a reputation-based review system for both employers and employees. By leveraging blockchain's transparency and immutability, the DES ensures accountability and trust throughout the employment lifecycle, from company creation and hiring to contract fulfillment and termination.</p> <p>The system operates post employee testing and prior to the final hiring and contract signing. Employees possess a <strong>Soulbound Token (SBT)</strong> representing their employment history, which companies review before finalizing labor contracts. This token-based approach ensures a secure and verifiable employment record that enhances the hiring process's integrity.</p> <h2 id="motivation">Motivation</h2> <p>Traditional employment systems are centralized, opaque, and often lack trust. The DES aims to introduce transparency, immutability, and trust into the employment process by leveraging blockchain technology. By recording employment history on-chain, enabling decentralized company creation, automating contract enforcement, and providing mechanisms for dispute resolution, the DES promotes a fairer and more transparent employment ecosystem. Additionally, the system streamlines the hiring process by securely managing employment records and automating contractual obligations.</p> <h2 id="specification">Specification</h2> <h3 id="solidity-interface">Solidity Interface</h3> <p>To provide a clear and standardized way for developers to interact with the DES, the following Solidity interface outlines the primary functions and events of the system:</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"> Decentralized Employment System Interface</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IDecentralizedEmploymentSystem</span><span> {</span></span> <span class="giallo-l"><span> </span></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"> CompanyRegistered</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> companyId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> owner</span><span>, </span><span class="z-support">string</span><span class="z-variable"> name</span><span>, </span><span class="z-support">string</span><span class="z-variable"> industry</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> EmployeeTokenMinted</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> tokenId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> employee</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ContractCreated</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> contractId</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> companyId</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> employeeTokenId</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> salary</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> duration</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ContractExecuted</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> contractId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SalaryDeposited</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> contractId</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SalaryReleased</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> contractId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> employee</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DisputeRaised</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> contractId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> raisedBy</span><span>)</span><span>;</span></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">uint</span><span class="z-variable"> contractId</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> decisionForEmployee</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ContractTerminated</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> contractId</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"> ReviewSubmitted</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> contractId</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> rating</span><span>, </span><span class="z-support">string</span><span class="z-variable"> comments</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"> Company Management</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerCompany</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> name</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> industry</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 class="z-variable"> companyId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getCompany</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> companyId</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 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"> industry</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> owner</span><span>,</span><span class="z-support"> uint</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> employeeIds</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"> Employee Management</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mintEmployeeToken</span><span>(</span><span class="z-support">address</span><span class="z-variable"> employee</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> metadataURI</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 class="z-variable"> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getEmploymentHistory</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> employeeTokenId</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 class="z-storage z-type"> memory</span><span class="z-variable"> contractIds</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"> Labor Contracts</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createContract</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> companyId</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> employeeTokenId</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> salary</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> duration</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> responsibilities</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> terminationConditions</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 class="z-variable"> contractId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> executeContract</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> contractId</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-comment"> Payment System</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> depositSalary</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> contractId</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-storage z-type"> function</span><span class="z-entity z-name"> releaseSalary</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> contractId</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-comment"> Dispute Resolution</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> raiseDispute</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> contractId</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"> resolveDispute</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> contractId</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> decisionForEmployee</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-comment"> Contract Termination</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> terminateContract</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> contractId</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>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-keyword"> Review</span><span class="z-comment"> System</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> submitReview</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> contractId</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> rating</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> comments</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"> getReviews</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> contractId</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">Review</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 class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Structures</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Review</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> rating</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> comments</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> reviewer</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="detailed-function-specifications">Detailed Function Specifications</h3> <h4 id="1-company-management">1. Company Management</h4> <p><strong>a. Company Registration</strong></p> <ul> <li> <p><strong>Function</strong>: <code>registerCompany(string calldata name, string calldata industry) external returns (uint companyId)</code></p> </li> <li> <p><strong>Description</strong>: Allows users to register a new company on the blockchain. Each company is assigned a unique <code>companyId</code> and associated with the caller's address as the owner.</p> </li> <li> <p><strong>Parameters</strong>:</p> <ul> <li><code>name</code>: The name of the company.</li> <li><code>industry</code>: The industry sector of the company.</li> </ul> </li> <li> <p><strong>Returns</strong>:</p> <ul> <li><code>companyId</code>: A unique identifier for the registered company.</li> </ul> </li> </ul> <p><strong>b. Retrieve Company Profile</strong></p> <ul> <li> <p><strong>Function</strong>: <code>getCompany(uint companyId) external view returns (string memory name, string memory industry, address owner, uint[] memory employeeIds)</code></p> </li> <li> <p><strong>Description</strong>: Retrieves the profile details of a registered company, including its name, industry, owner address, and a list of associated employee token IDs.</p> </li> <li> <p><strong>Parameters</strong>:</p> <ul> <li><code>companyId</code>: The unique identifier of the company.</li> </ul> </li> <li> <p><strong>Returns</strong>:</p> <ul> <li><code>name</code>: Name of the company.</li> <li><code>industry</code>: Industry sector of the company.</li> <li><code>owner</code>: Ethereum address of the company owner.</li> <li><code>employeeIds</code>: Array of employee token IDs associated with the company.</li> </ul> </li> </ul> <h4 id="2-employee-management">2. Employee Management</h4> <p><strong>a. Employee Tokenization</strong></p> <ul> <li> <p><strong>Function</strong>: <code>mintEmployeeToken(address employee, string calldata metadataURI) external returns (uint tokenId)</code></p> </li> <li> <p><strong>Description</strong>: Mints a <strong>Soulbound Token (SBT)</strong> representing an employee. The token contains metadata about the employee, such as professional credentials, stored off-chain and referenced via <code>metadataURI</code>.</p> </li> <li> <p><strong>Parameters</strong>:</p> <ul> <li><code>employee</code>: Ethereum address of the employee.</li> <li><code>metadataURI</code>: URI pointing to the employee's metadata.</li> </ul> </li> <li> <p><strong>Returns</strong>:</p> <ul> <li><code>tokenId</code>: A unique identifier for the employee token.</li> </ul> </li> </ul> <p><strong>b. Retrieve Employment History</strong></p> <ul> <li> <p><strong>Function</strong>: <code>getEmploymentHistory(uint employeeTokenId) external view returns (uint[] memory contractIds)</code></p> </li> <li> <p><strong>Description</strong>: Fetches the complete employment history of an employee by returning an array of associated <code>contractIds</code>.</p> </li> <li> <p><strong>Parameters</strong>:</p> <ul> <li><code>employeeTokenId</code>: The unique identifier of the employee's token.</li> </ul> </li> <li> <p><strong>Returns</strong>:</p> <ul> <li><code>contractIds</code>: Array of contract IDs representing the employee's employment history.</li> </ul> </li> </ul> <h4 id="3-labor-contracts">3. Labor Contracts</h4> <p><strong>a. Contract Creation</strong></p> <ul> <li> <p><strong>Function</strong>: <code>createContract(uint companyId, uint employeeTokenId, uint salary, uint duration, string calldata responsibilities, string calldata terminationConditions) external returns (uint contractId)</code></p> </li> <li> <p><strong>Description</strong>: Enables a company to create a new labor contract with an employee. This function assigns a unique <code>contractId</code> to the contract.</p> </li> <li> <p><strong>Parameters</strong>:</p> <ul> <li><code>companyId</code>: The unique identifier of the company initiating the contract.</li> <li><code>employeeTokenId</code>: The unique identifier of the employee's token.</li> <li><code>salary</code>: The agreed-upon salary for the contract period.</li> <li><code>duration</code>: Duration of the contract in months.</li> <li><code>responsibilities</code>: Description of the employee's responsibilities.</li> <li><code>terminationConditions</code>: Conditions under which the contract can be terminated.</li> </ul> </li> <li> <p><strong>Returns</strong>:</p> <ul> <li><code>contractId</code>: A unique identifier for the newly created contract.</li> </ul> </li> </ul> <p><strong>b. Contract Execution</strong></p> <ul> <li> <p><strong>Function</strong>: <code>executeContract(uint contractId) external</code></p> </li> <li> <p><strong>Description</strong>: Activates the contract by marking it as active once both the company and the employee have agreed to the terms by signing the transaction with their respective wallets.</p> </li> <li> <p><strong>Parameters</strong>:</p> <ul> <li><code>contractId</code>: The unique identifier of the contract to be executed.</li> </ul> </li> </ul> <h4 id="4-payment-system">4. Payment System</h4> <p><strong>a. Salary Deposits</strong></p> <ul> <li> <p><strong>Function</strong>: <code>depositSalary(uint contractId) external payable</code></p> </li> <li> <p><strong>Description</strong>: Allows the company to deposit the agreed salary into the contract's escrow. The function ensures that the deposited amount matches the contract's salary.</p> </li> <li> <p><strong>Parameters</strong>:</p> <ul> <li><code>contractId</code>: The unique identifier of the contract for which the salary is being deposited.</li> </ul> </li> <li> <p><strong>Payable</strong>: Yes, the function is payable to accept the salary funds.</p> </li> </ul> <p><strong>b. Automated Payments</strong></p> <ul> <li> <p><strong>Function</strong>: <code>releaseSalary(uint contractId) external</code></p> </li> <li> <p><strong>Description</strong>: Releases the salary from escrow to the employee's address based on the contract's payment schedule or upon contract completion.</p> </li> <li> <p><strong>Parameters</strong>:</p> <ul> <li><code>contractId</code>: The unique identifier of the contract for which the salary is being released.</li> </ul> </li> </ul> <h4 id="5-dispute-resolution">5. Dispute Resolution</h4> <p><strong>a. Dispute Initiation</strong></p> <ul> <li> <p><strong>Function</strong>: <code>raiseDispute(uint contractId) external</code></p> </li> <li> <p><strong>Description</strong>: Allows either party involved in the contract to initiate a dispute. This action triggers the assignment of a moderator to resolve the issue.</p> </li> <li> <p><strong>Parameters</strong>:</p> <ul> <li><code>contractId</code>: The unique identifier of the contract in dispute.</li> </ul> </li> </ul> <p><strong>b. Dispute Resolution</strong></p> <ul> <li> <p><strong>Function</strong>: <code>resolveDispute(uint contractId, bool decisionForEmployee) external</code></p> </li> <li> <p><strong>Description</strong>: Enables the assigned moderator to resolve the dispute by making a decision. If the decision favors the employee, escrow funds are transferred accordingly; otherwise, they may be returned to the company.</p> </li> <li> <p><strong>Parameters</strong>:</p> <ul> <li><code>contractId</code>: The unique identifier of the contract under dispute.</li> <li><code>decisionForEmployee</code>: Boolean indicating if the decision favors the employee.</li> </ul> </li> </ul> <h4 id="6-contract-termination">6. Contract Termination</h4> <p><strong>a. Termination Conditions</strong></p> <ul> <li> <p><strong>Function</strong>: <code>terminateContract(uint contractId, string calldata reason) external</code></p> </li> <li> <p><strong>Description</strong>: Allows the company to terminate the contract based on predefined conditions. This function updates the contract status to "terminated."</p> </li> <li> <p><strong>Parameters</strong>:</p> <ul> <li><code>contractId</code>: The unique identifier of the contract to be terminated.</li> <li><code>reason</code>: The reason for termination.</li> </ul> </li> </ul> <h4 id="7-review-system">7. Review System</h4> <p><strong>a. Submit Review</strong></p> <ul> <li> <p><strong>Function</strong>: <code>submitReview(uint contractId, uint rating, string calldata comments) external</code></p> </li> <li> <p><strong>Description</strong>: Enables both companies and employees to submit reviews post-contract. Reviews include a rating and comments, contributing to the reputation score of both parties.</p> </li> <li> <p><strong>Parameters</strong>:</p> <ul> <li><code>contractId</code>: The unique identifier of the contract being reviewed.</li> <li><code>rating</code>: Numerical rating reflecting the experience.</li> <li><code>comments</code>: Detailed feedback about the contract.</li> </ul> </li> </ul> <p><strong>b. Retrieve Reviews</strong></p> <ul> <li> <p><strong>Function</strong>: <code>getReviews(uint contractId) external view returns (Review[] memory)</code></p> </li> <li> <p><strong>Description</strong>: Retrieves all reviews associated with a specific contract.</p> </li> <li> <p><strong>Parameters</strong>:</p> <ul> <li><code>contractId</code>: The unique identifier of the contract whose reviews are being fetched.</li> </ul> </li> <li> <p><strong>Returns</strong>:</p> <ul> <li><code>Review[]</code>: An array of reviews related to the contract.</li> </ul> </li> </ul> <h3 id="employment-history">Employment History</h3> <ol> <li> <p><strong>Immutable Records</strong>: Employment history is maintained as an array of contract IDs linked to each employee's Soulbound Token (SBT). This ensures that all employment records are permanently and immutably stored on the blockchain.</p> </li> <li> <p><strong>Public Accessibility</strong>: Employment history data is publicly accessible through the <code>getEmploymentHistory</code> function, allowing companies to verify an employee's past engagements before finalizing contracts.</p> </li> </ol> <h3 id="payment-system">Payment System</h3> <ol> <li> <p><strong>Salary Deposits</strong>: Companies deposit salaries into an escrow managed by the smart contract by calling <code>depositSalary</code>. The contract ensures that funds are securely held until payment conditions are satisfied.</p> </li> <li> <p><strong>Automated Payments</strong>: Salaries are released automatically or upon triggering the <code>releaseSalary</code> function, ensuring timely and condition-based payments to employees.</p> </li> </ol> <h3 id="moderation-and-dispute-resolution">Moderation and Dispute Resolution</h3> <ol> <li><strong>Dispute Initiation and Resolution</strong>: Either party can raise disputes, which are then resolved by assigned moderators. Moderators act as impartial arbitrators to ensure fair outcomes based on contract terms and evidence provided.</li> </ol> <h3 id="firing-employees">Firing Employees</h3> <ol> <li><strong>Termination Conditions</strong>: Companies can terminate contracts based on predefined conditions, with the option for dispute resolution if termination is contested.</li> </ol> <h3 id="review-system">Review System</h3> <ol> <li><strong>Reputation Scores</strong>: Reviews contribute to the reputation scores of both companies and employees, fostering accountability and encouraging positive behavior within the ecosystem.</li> </ol> <h2 id="rationale">Rationale</h2> <ol> <li> <p><strong>Employee Tokenization</strong>:</p> <ul> <li>Utilizing <strong>Soulbound Tokens (SBTs)</strong> to represent employees ensures that each employee has a unique, non-transferable identity on the blockchain. This design choice enhances the integrity of employment records, making them tamper-proof and verifiable. It also allows companies to access a comprehensive employment history before finalizing contracts, promoting transparency.</li> </ul> </li> <li> <p><strong>Escrow System for Salary Payments</strong>:</p> <ul> <li>Implementing an escrow mechanism secures salary payments, ensuring that funds are only released when contractual obligations are met. This system protects both employees and companies by guaranteeing that salaries are available and that payments are contingent on contract fulfillment.</li> </ul> </li> <li> <p><strong>Moderation and Dispute Resolution</strong>:</p> <ul> <li>Incorporating a moderation system allows for the resolution of disputes that cannot be automatically enforced by smart contracts. Moderators provide necessary human oversight in complex employment matters, ensuring fair and just outcomes.</li> </ul> </li> <li> <p><strong>Public Employment History</strong>:</p> <ul> <li>Making employment history publicly accessible fosters trust and accountability. It allows potential employers to verify past employment and credentials, reducing the risk of fraud and enhancing the credibility of employees within the ecosystem.</li> </ul> </li> <li> <p><strong>Review System</strong>:</p> <ul> <li>A reputation-based review system encourages positive interactions and behaviors among users. By allowing both companies and employees to submit reviews, the system promotes mutual accountability and helps build reliable reputations.</li> </ul> </li> </ol> <h2 id="test-cases">Test Cases</h2> <ol> <li> <p><strong>Company Creation</strong></p> <p><strong>Input</strong></p> <ul> <li> <p>A user calls <code>registerCompany("TechCorp", "Technology")</code>. <strong>Expected State Changes</strong></p> </li> <li> <p>A new <code>companyId</code> is generated (e.g., <code>companyId = 1</code>).</p> </li> <li> <p>The <code>companies</code> mapping is updated:</p> </li> </ul> </li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span> companies</span><span>[</span><span class="z-constant">1</span><span>]</span><span>↦</span><span>{</span></span> <span class="giallo-l"><span> name</span><span class="z-keyword">=</span><span class="z-string">&quot;TechCorp&quot;</span><span>,</span></span> <span class="giallo-l"><span> industry</span><span class="z-keyword">=</span><span class="z-string">&quot;Technology&quot;</span><span>,</span></span> <span class="giallo-l"><span> owner</span><span class="z-keyword">=</span><span>callerAddress</span><span>,</span></span> <span class="giallo-l"><span> employeeIds</span><span class="z-keyword">=</span><span>[</span><span> ]</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <ul> <li>An event <code>CompanyRegistered</code> is emitted with the arguments <code>(1, callerAddress, "TechCorp", "Technology")</code>.</li> </ul> <p><strong>Expected Output</strong></p> <ul> <li><strong>Return Value</strong>: <code>companyId = 1</code> (the newly created company ID).</li> <li><strong>Event</strong>: <code>CompanyRegistered</code> is logged.</li> </ul> <ol start="2"> <li> <p><strong>Employee Token Minting</strong></p> <p><strong>Input</strong></p> <ul> <li> <p>The contract owner (or an authorized address) calls <code>mintEmployeeToken(employeeAddress, "ipfs://metadataURI")</code>. <strong>Expected State Changes</strong></p> </li> <li> <p>A new token ID is generated (e.g., <code>tokenId = 5</code>).</p> </li> <li> <p>An internal mapping (e.g., <code>employeeTokenToOwner</code>) is updated:</p> </li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span> employeeTokenToOwner</span><span>[</span><span class="z-constant">5</span><span>]</span><span>↦employeeAddress</span></span></code></pre> <ul> <li>(Optional) If the implementation tracks metadata, another mapping (e.g., <code>employeeTokenMetadata</code>) might store:</li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span> employeeTokenMetadata</span><span>[</span><span class="z-constant">5</span><span>]</span><span>↦</span><span class="z-string">&quot;ipfs://metadataURI&quot;</span></span></code></pre> <ul> <li> <p>An event <code>EmployeeTokenMinted</code> is emitted with <code>(5, employeeAddress)</code>. <strong>Expected Output</strong></p> </li> <li> <p><strong>Return Value</strong>: <code>tokenId = 5</code> (the newly minted employee token ID).</p> </li> <li> <p><strong>Event</strong>: <code>EmployeeTokenMinted</code> is logged.</p> </li> </ul> </li> <li> <p><strong>Contract Creation and Execution</strong></p> <p><strong>Input</strong></p> <ol> <li>A company with <code>companyId = 1</code> calls:</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name"> createContract</span><span>(</span><span class="z-constant">1</span><span>,</span><span class="z-constant">5</span><span>,</span><span class="z-constant">1000</span><span>,</span><span class="z-constant">6</span><span>,</span><span class="z-string">&quot;SoftwareDevelopment&quot;</span><span>,</span><span class="z-string">&quot;Failuretomeetdeadlines&quot;</span><span>)</span></span></code></pre> <p>which returns <code>contractId</code>. 2. Both the company and the employee call <code>executeContract(contractId)</code>.</p> <p><strong>Expected State Changes</strong></p> <ul> <li> <p><strong>Contract Creation</strong>:</p> <ol> <li>A new labor contract ID is generated, e.g., <code>contractId = 10</code>.</li> <li>The <code>contracts</code> mapping is updated:</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span> contracts</span><span>[</span><span class="z-constant">10</span><span>]</span><span>↦</span><span>{</span></span> <span class="giallo-l"><span> companyId</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>,</span></span> <span class="giallo-l"><span> employeeTokenId</span><span class="z-keyword">=</span><span class="z-constant">5</span><span>,</span></span> <span class="giallo-l"><span> salary</span><span class="z-keyword">=</span><span class="z-constant">1000</span><span>,</span></span> <span class="giallo-l"><span> duration</span><span class="z-keyword">=</span><span class="z-constant">6</span><span>,</span></span> <span class="giallo-l"><span> responsibilities</span><span class="z-keyword">=</span><span class="z-string">&quot;SoftwareDevelopment&quot;</span><span>,</span></span> <span class="giallo-l"><span> terminationConditions</span><span class="z-keyword">=</span><span class="z-string">&quot;Failuretomeetdeadlines&quot;</span><span>,</span><span>status</span><span class="z-keyword">=</span><span class="z-string">&quot;Created&quot;</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <ol start="3"> <li>The system may also update a per-company or per-employee tracking structure (optional but typical):</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span> companyContracts</span><span>[</span><span class="z-constant">1</span><span>]</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-constant">10</span><span>)</span></span> <span class="giallo-l"><span> employeeContracts</span><span>[</span><span class="z-constant">5</span><span>]</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-constant">10</span><span>)</span></span></code></pre> <ol start="4"> <li>An event <code>ContractCreated</code> is emitted with arguments <code>(10, 1, 5, 1000, 6)</code>.</li> </ol> </li> <li> <p><strong>Contract Execution</strong>:</p> <ol> <li>Upon calls from both parties, the contract’s status changes from <code>"Created"</code> to <code>"Active"</code>:</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span> contracts</span><span>[</span><span class="z-constant">10</span><span>]</span><span>.</span><span>status↦</span><span class="z-string">&quot;Active&quot;</span></span></code></pre> <ol start="2"> <li>An event <code>ContractExecuted</code> is emitted with <code>(10)</code> once both signatures/confirmations are received. <strong>Expected Output</strong></li> </ol> </li> <li> <p><strong>Return Value</strong> (from <code>createContract</code>): <code>contractId = 10</code></p> </li> <li> <p><strong>Event</strong>: <code>ContractCreated(10, 1, 5, 1000, 6)</code> upon creation.</p> </li> <li> <p><strong>Event</strong>: <code>ContractExecuted(10)</code> once execution is confirmed by both parties.</p> </li> </ul> </li> <li> <p><strong>Salary Deposit</strong></p> <p><strong>Input</strong></p> <ul> <li>The company (owner of <code>companyId = 1</code>) calls <code>depositSalary(10)</code> and sends <code>1000 USDC</code> (or equivalent in wei for an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token or native token) to the contract. <strong>Expected State Changes</strong></li> </ul> <ol> <li>The contract’s escrow balance mapping is updated:</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span> escrowBalances</span><span>[</span><span class="z-constant">10</span><span>]</span><span>↦</span><span class="z-constant">1000</span></span></code></pre> <ol start="2"> <li>An event <code>SalaryDeposited</code> is emitted with <code>(10, 1000)</code>. <strong>Expected Output</strong></li> </ol> <ul> <li><strong>Event</strong>: <code>SalaryDeposited(10, 1000)</code></li> <li>The contract’s internal <code>escrowBalances[10]</code> should now be <code>1000</code>.</li> </ul> </li> <li> <p><strong>Salary Payment</strong></p> <p><strong>Input</strong></p> <ul> <li>After the contract’s duration or satisfaction of any release condition, <code>releaseSalary(10)</code> is called (by the contract or the employee). <strong>Expected State Changes</strong></li> </ul> <ol> <li>The escrow balance for <code>contractId = 10</code> is transferred to the employee token owner (<code>employeeAddress</code> associated with token ID <code>5</code>).</li> <li>The <code>escrowBalances[10]</code> is set to <code>0</code>:</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span> escrowBalances</span><span>[</span><span class="z-constant">10</span><span>]</span><span>↦</span><span class="z-constant">0</span></span></code></pre> <ol start="3"> <li>An event <code>SalaryReleased</code> is emitted with <code>(10, employeeAddress)</code>. <strong>Expected Output</strong></li> </ol> <ul> <li><strong>Event</strong>: <code>SalaryReleased(10, employeeAddress)</code></li> <li>The updated <code>escrowBalances[10]</code> is now <code>0</code>.</li> <li>The employee’s on-chain balance (or token balance if using <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>) increases by <code>1000</code>.</li> </ul> </li> <li> <p><strong>Employment Termination</strong></p> <p><strong>Input</strong></p> <ul> <li>The company calls <code>terminateContract(10, "Failure to meet deadlines")</code>. <strong>Expected State Changes</strong></li> </ul> <ol> <li>The <code>contracts[10].status</code> is updated to <code>"Terminated"</code>:</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span> contracts</span><span>[</span><span class="z-constant">10</span><span>]</span><span>.</span><span>status↦</span><span class="z-string">&quot;Terminated&quot;</span></span></code></pre> <ol start="2"> <li>An event <code>ContractTerminated</code> is emitted with <code>(10, "Failure to meet deadlines")</code>. <strong>Expected Output</strong></li> </ol> <ul> <li><strong>Event</strong>: <code>ContractTerminated(10, "Failure to meet deadlines")</code></li> <li>The <code>contracts[10]</code> status is now <code>"Terminated"</code>.</li> <li>No further salary obligations exist unless otherwise specified in dispute-resolution processes.</li> </ul> </li> <li> <p><strong>Dispute Resolution</strong></p> <p><strong>Input</strong></p> <ol> <li>Either party (company or employee) calls <code>raiseDispute(10)</code>.</li> <li>The assigned moderator calls <code>resolveDispute(10, true)</code> indicating the decision favors the employee. <strong>Expected State Changes</strong></li> </ol> <ul> <li> <p><strong>Dispute Raised</strong>:</p> <ol> <li>The contract’s dispute status is noted (implementation-specific, but typically <code>contracts[10].disputeRaised = true</code>).</li> <li>An event <code>DisputeRaised(10, msg.sender)</code> is emitted.</li> </ol> </li> <li> <p><strong>Dispute Resolved</strong>:</p> <ol> <li>If <code>decisionForEmployee == true</code>, any remaining escrow funds for <code>contractId = 10</code> are transferred to the employee.</li> <li>A <code>DisputeResolved(10, true)</code> event is emitted. <strong>Expected Output</strong></li> </ol> </li> <li> <p><strong>Event</strong>: <code>DisputeRaised(10, msg.sender)</code></p> </li> <li> <p><strong>Event</strong>: <code>DisputeResolved(10, true)</code></p> </li> <li> <p>If funds remain in escrow, <code>escrowBalances[10]</code> is set to <code>0</code>, and the employee receives the outstanding balance.</p> </li> </ul> </li> </ol> <h2 id="security-considerations">Security Considerations</h2> <ol> <li> <p><strong>Contract Integrity</strong>: Ensure that all labor contracts are immutable and cannot be tampered with once created and executed.</p> </li> <li> <p><strong>Fund Security</strong>: Salaries are securely held in escrow, and only released based on predefined conditions to prevent unauthorized access or misuse.</p> </li> <li> <p><strong>Moderator Trust</strong>: Implement a decentralized and transparent system for selecting and monitoring moderators to maintain impartiality and trust in dispute resolutions.</p> </li> <li> <p><strong>Review System</strong>: Incorporate safeguards against fraudulent reviews, such as verifying the association of reviews with legitimate contract completions, to maintain accurate and trustworthy reputation scores.</p> </li> <li> <p><strong>Token Security</strong>: Use <strong>Soulbound Tokens (SBTs)</strong> for employee representation to prevent token transfers and ensure that employment records are securely tied to the respective individuals.</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> 2024-07-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Erik Markshttps://github.com/remarks Guillaume Grosboishttps://github.com/uni-guillaume https://wg-eips.ritovision.com/7754/

Provides a mechanism for dapps to use the extension wallets API in a tamperproof way

<h2 id="abstract">Abstract</h2> <p>Tamperproof Web Immutable Secure Transaction (TWIST) introduces a new RPC method to be implemented by wallets, <code>wallet_signedRequest</code>, that enables dapps to interact with wallets in a tamperproof manner via "signed requests". The dapp associates a public key with its DNS record and uses the corresponding private key to sign payloads sent to the wallet via <code>wallet_signedRequest</code>. Wallets can then use the public key in the DNS record to validate the integrity of the payload.</p> <h2 id="motivation">Motivation</h2> <p>This standard aims to enhance the end user's experience by granting them confidence that requests from their dapps have not been tampered with. In essence, this is similar to how HTTPS is used in the web.</p> <p>Currently, the communication channel between dapps and wallets is vulnerable to man in the middle attacks. Specifically, attackers can intercept RPC requests by injecting JavaScript code in the page, via e.g. an XSS vulnerability or due to a malicious extension. Once an RPC request is intercepted, it can be modified in a number of pernicious ways, including:</p> <ul> <li>Editing the calldata in order to siphon funds or otherwise change the transaction outcome</li> <li>Modifying the parameters of an <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> request</li> <li>Obtaining a replayable signature from the wallet</li> </ul> <p>Even if the user realizes that requests from the dapp may be tampered with, they have little to no recourse to mitigate the problem. Overall, the lack of a chain of trust between the dapp and the wallet hurts the ecosystem as a whole:</p> <ul> <li>Users cannot simply trust otherwise honest dapps, and are at risk of losing funds</li> <li>Dapp maintainers are at risk of hurting their reputations if an attacker finds a viable MITM attack</li> </ul> <p>For these reasons, we recommend that wallets implement the <code>wallet_signedRequest</code> RPC method. This method provides dapp developers with a way to explicitly ask the wallet to verify the integrity of a payload. This is a significant improvement over the status quo, which forces dapps to rely on implicit approaches such as argument bit packing.</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="overview">Overview</h3> <p>We propose to use the dapp's domain certificate of a root of trust to establish a trust chain as follow:</p> <ol> <li>The user's browser verifies the domain certificate and displays appropriate warnings if overtaken</li> <li>The DNS record of the dapp hosts a TXT field pointing to a URL where a JSON manifest is hosted <ul> <li>This file SHOULD be at a well known address such as <code>example[.]com/.well-known/twist.json</code></li> </ul> </li> <li>The config file contains an array of objects of the form <code>{ id, alg, publicKey }</code></li> <li>For signed requests, the dapp first securely signs the payload with a private key, for example by submitting a request to its backend</li> <li>The original payload, signature, and public key id are sent to the wallet via the <code>wallet_signedRequest</code> RPC method</li> <li>The wallet verifies the signature before processing the request normally</li> </ol> <h3 id="wallet-integration">Wallet integration</h3> <h4 id="key-discovery">Key discovery</h4> <p>Attested public keys are necessary for the chain of trust to be established. Since this is traditionally done via DNS certificates, we propose the addition of a DNS record containing the public keys. This is similar to RFC 6376's DKIM, but the use of a manifest file provides more flexibility for future improvements, as well as support for multiple algorithm and key pairs.</p> <p>Similarly to standard RFC 7519's JWT practices, the wallet could eagerly cache dapp keys. However, in the absence of a revocation mechanism, a compromised key could still be used until caches have expired. To mitigate this, wallets SHOULD NOT cache dapp public keys for more than 2 hours. This practice establishes a relatively short vulnerability window, and manageable overhead for both wallet and dapp maintainers.</p> <p>Example DNS record for <code>my-crypto-dapp.invalid</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>...</span></span> <span class="giallo-l"><span>TXT: TWIST=/.well-known/twist.json</span></span></code></pre> <p>Example TWIST manifest at <code>my-crypto-dapp[.]invalid/.well-known/twist.json</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">publicKeys</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">id</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">alg</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ES256</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">publicKey</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xaf34...</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">id</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">alg</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">PS256</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">publicKey</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x98ab...</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> <p>Implementers MUST support at least the following "alg" param values, from RFC 7518 section 3.1: ES256 and EdDSA. Implementers SHOULD support PS256, RS256, ES384, ES512, PS384, PS512, RS384, and RS512.</p> <p>Implementers SHOULD use <code>SubtleCrypto</code>, since it is available in modern browsers.</p> <p>Public keys MUST be encoded using the X.509 SubjectPublicKeyInfo (SPKI) structure in DER format and represented as hex-encoded strings.</p> <h4 id="manifest-schema">Manifest schema</h4> <p>We propose a simple and extensible 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">TWIST manifest</span><span class="z-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">publicKeys</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">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">id</span><span class="z-support">&quot;</span><span>:</span><span> {</span><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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">alg</span><span class="z-support">&quot;</span><span>:</span><span> {</span><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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">publicKey</span><span class="z-support">&quot;</span><span>:</span><span> {</span><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> }</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="rpc-method">RPC method</h4> <p>The parameters of <code>wallet_signedRequest</code> are specified by this TypeScript interface:</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"> RequestPayload</span><span>&lt;</span><span class="z-entity z-name">Params</span><span>&gt;</span><span class="z-keyword"> =</span><span> {</span><span class="z-variable"> method</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-variable"> params</span><span class="z-keyword">:</span><span class="z-entity z-name"> Params</span><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"> SignedRequestParameters</span><span>&lt;</span><span class="z-entity z-name">Params</span><span>&gt;</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span class="z-entity z-name"> requestPayload</span><span>:</span><span class="z-entity z-name"> RequestPayload</span><span>&lt;</span><span class="z-entity z-name">Params</span><span>&gt;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> signature</span><span>:</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> <span class="giallo-l"><span class="z-entity z-name"> keyId</span><span>:</span><span class="z-support"> string</span><span>,</span></span> <span class="giallo-l"><span>]</span><span>;</span></span></code></pre> <p>Here's a non-normative example of calling <code>wallet_signedRequest</code> using the <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a> provider interface:</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"> keyId</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">1</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"> requestPayload</span><span class="z-keyword">:</span><span class="z-entity z-name"> RequestPayload</span><span>&lt;</span><span class="z-entity z-name">TransactionParams</span><span>&gt;</span><span class="z-keyword"> =</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> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><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 class="giallo-l"><span> }</span><span>,</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-storage z-type">const</span><span class="z-variable z-other z-constant"> signature</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 class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> getSignature</span><span>(</span><span class="z-variable z-other">requestPayload</span><span>,</span><span class="z-variable z-other"> keyId</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"> Using the EIP-1193 provider interface</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> result</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">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">wallet_signedRequest</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">requestPayload</span><span>,</span><span class="z-variable z-other"> signature</span><span>,</span><span class="z-variable z-other"> keyId</span><span>]</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span><span>;</span></span></code></pre><h4 id="signature-verification">Signature verification</h4> <ol> <li>Upon receiving an <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a> call, the wallet MUST check of the existence of the TWIST manifest for the <code>sender.tab.url</code> domain a. The wallet MUST enforce HTTPS as HTTP call would be vulnerable to DNS spoofing b. The wallet MUST verify that the manifest is hosted on the <code>sender.tab.url</code> domain c. The wallet SHOULD find the DNS TXT record to find the manifest location d. The wallet MAY first try the <code>/.well-known/twist.json</code> location e. The wallet MUST NOT follow redirects when querying the manifest location as it could lead to open redirect attacks f. The wallet SHOULD validate the <code>Content-Type</code> header of the response is specifically set to <code>application/json</code></li> <li>If TWIST is NOT configured for the <code>sender.tab.url</code> domain, then proceed as usual</li> <li>If TWIST is configured and the <code>request</code> method is used, then the wallet SHOULD display a visible and actionable warning to the user a. If the user opts to ignore the warning, then proceed as usual b. If the user opts to cancel, then the wallet MUST cancel the call</li> <li>If TWIST is configured and the <code>wallet_signedRequest</code> method is used with the parameters <code>requestPayload</code>, <code>signature</code> and <code>keyId</code> then: a. The wallet MAY display a visible cue indicating that this interaction is signed b. The wallet MUST verify that the keyId exists in the TWIST manifest and find the associated key record c. From the key record, the wallet MUST use the <code>alg</code> field and the <code>publicKey</code> field to verify <code>requestPayload</code> integrity by calling <code>crypto.verify(alg, key, signature, requestPayload)</code> d. If the signature is invalid, the wallet MUST display a visible and actionable warning to the user i. If the user opts to ignore the warning, then proceed to call <code>request</code> with the argument <code>requestPayload</code> ii. If the user opts to cancel, then the wallet MUST cancel the call e. If the signature is valid, the wallet MUST call <code>request</code> with the argument <code>requestPayload</code></li> </ol> <h4 id="example-method-implementation-wallet">Example method implementation (wallet)</h4> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage">async</span><span class="z-storage z-type"> function</span><span class="z-entity z-name"> signedRequest</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> requestPayload</span><span class="z-keyword">:</span><span class="z-entity z-name"> RequestPayload</span><span>&lt;</span><span class="z-support">unknown</span><span>&gt;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> signature</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> <span class="giallo-l"><span class="z-variable"> keyId</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>,</span></span> <span class="giallo-l"><span>)</span><span class="z-keyword">:</span><span class="z-entity z-name"> Promise</span><span>&lt;</span><span class="z-support">unknown</span><span>&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 1. Get the domain of the sender.tab.url</span></span> <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 class="z-entity z-name"> getDappDomain</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"> 2. Get the manifest for the current domain</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> It&#39;s possible to use RFC 8484 for the actual DNS-over-HTTPS specification.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> However, here we are doing it with DoHjs.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> This step is optional, and you could go directly to the well-known address first at `domain + &#39;/.well-known/twist.json&#39;`</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> doh</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">dohjs</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"> resolver</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-variable z-other"> doh</span><span>.</span><span class="z-entity z-name">DohResolver</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">&lt;doh-endpoint&gt;</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"> let</span><span class="z-variable z-other"> manifestPath</span><span class="z-keyword"> =</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 class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> dnsResp</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> resolver</span><span>.</span><span class="z-entity z-name">query</span><span>(</span><span class="z-variable z-other">domain</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">TXT</span><span class="z-punctuation z-definition z-string">&#39;</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"> record</span><span class="z-keyword"> of</span><span class="z-variable z-other"> dnsResp</span><span>.</span><span class="z-variable z-other">answers</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">record</span><span>.</span><span class="z-variable z-other">data</span><span>.</span><span class="z-entity z-name">startsWith</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">TWIST=</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>)</span><span class="z-keyword"> continue</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> manifestPath</span><span class="z-keyword"> =</span><span class="z-variable z-other"> record</span><span>.</span><span class="z-variable z-other">data</span><span>.</span><span class="z-entity z-name">substring</span><span>(</span><span class="z-constant">5</span><span>)</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> This should be domain + &#39;/.well-known/twist.json&#39;</span></span> <span class="giallo-l"><span class="z-keyword"> break</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"> 3. Parse the manifest and get the key and algo based on `keyId`</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> manifestUrl</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> `</span><span class="z-string">https://</span><span class="z-string">${</span><span class="z-variable z-other">domain</span><span class="z-string">}</span><span class="z-string">${</span><span class="z-variable z-other">manifestPath</span><span class="z-string">.</span><span class="z-entity z-name">startsWith</span><span class="z-string">(</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 class="z-string">)</span><span class="z-keyword"> ?</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-punctuation z-definition z-string">&#39;</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 class="z-string">}</span><span class="z-string">${</span><span class="z-variable z-other">manifestPath</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">`</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> manifestReq</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> fetch</span><span>(</span><span class="z-variable z-other">manifestUrl</span><span>,</span><span> {</span><span> redirect</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">error</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"> const</span><span class="z-variable z-other z-constant"> contentType</span><span class="z-keyword"> =</span><span> (</span><span class="z-variable z-other">manifestReq</span><span>.</span><span class="z-variable z-other">headers</span><span>.</span><span class="z-entity z-name">get</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-keyword"> ||</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 class="z-entity z-name">toLowerCase</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-variable z-other">contentType</span><span>.</span><span class="z-entity z-name">startsWith</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></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">The manifest is not a proper JSON file</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"> manifest</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> manifestReq</span><span>.</span><span class="z-entity z-name">json</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"> keyData</span><span class="z-keyword"> =</span><span class="z-variable z-other"> manifest</span><span>.</span><span class="z-variable z-other">publicKeys</span><span>.</span><span class="z-entity z-name">find</span><span>(</span><span>(</span><span class="z-variable">x</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span class="z-variable z-other"> x</span><span>.</span><span class="z-variable z-other">id</span><span class="z-keyword"> ===</span><span class="z-variable z-other"> keyId</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">keyData</span><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">Could not find the signing key</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> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> key</span><span class="z-keyword"> =</span><span class="z-variable z-other"> keyData</span><span>.</span><span class="z-variable z-other">publicKey</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> alg</span><span class="z-keyword"> =</span><span class="z-variable z-other"> keyData</span><span>.</span><span class="z-variable z-other">alg</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"> 4. Verify the signature</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> valid</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> crypto</span><span>.</span><span class="z-entity z-name">verify</span><span>(</span><span class="z-variable z-other">alg</span><span>,</span><span class="z-variable z-other"> key</span><span>,</span><span class="z-variable z-other"> signature</span><span>,</span><span class="z-variable z-other"> requestPayload</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">valid</span><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">The data was tampered with</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-keyword"> return</span><span class="z-keyword"> await</span><span class="z-entity z-name"> processRequest</span><span>(</span><span class="z-variable z-other">requestPayload</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="wallet-ux-suggestion">Wallet UX suggestion</h3> <p>Similarly to the padlock icon for HTTPS, wallets should display a visible indication when TWIST is configured on a domain. This will improve the UX of the end user who will immediately be able to tell that interactions between the dapp they are using and the wallet are secure, and this will encourage dapp developer to adopt TWIST, making the overall ecosystem more secure</p> <p>When dealing with insecure request, either because the dapp (or an attacker) uses <code>request</code> on a domain where TWIST is configured, or because the signature does not match, wallets should warn the user but not block: an eloquently worded warning will increase the transparency enough that end user may opt to cancel the interaction or proceed with the unsafe call.</p> <h2 id="rationale">Rationale</h2> <p>The proposed implementation does not modify any of the existing functionalities offered by <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> and <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a>. Its additive nature makes it inherently backward compatible. Its core design is modeled after existing solutions to existing problems (such as DKIM). As a result the proposed specification will be non disruptive, easy to implements for both wallets and dapps, with a predictable threat model.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="replay-prevention">Replay prevention</h3> <p>While signing the <code>requestArg</code> payload guarantees data integrity, it does not prevent replay attacks in itself:</p> <ol> <li>a signed payload can be replayed multiple times</li> <li>a signed payload can be replayed across multiple chains</li> </ol> <p><em>Effective</em> time replay attacks as described in <code>1.</code> are generally prevented by the transaction nonce. Cross chain replay can be prevented by leveraging the <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> <code>signTypedData</code> method.</p> <p>Replay attack would still be possible on any method that is not protected by either: this affects effectively all the "readonly" methods which are of very limited value for an attacker.</p> <p>For these reason, we do not recommend a specific replay protection mechanism at this time. If/when the need arise, the extensibility of the manifest will provide the necessary room to enforce a replay protection envelope (eg:JWT) for affected dapp.</p> <h3 id="malicious-manifests">Malicious manifests</h3> <p>The manifest itself could be attacked, defeating the purpose of TWIST. We identified the following possible attacks, and their counter measure:</p> <ol> <li>An attacker can spoof DNS entries and use it to serve their own manifest: to avoid this, the wallet implementation MUST only query the manifest from <code>'https://${sender.tab.url}/${pathFromDNSRecord}</code></li> <li>An attacker can leverage other flaws in a dapp to host a malicious manifest on the dapp domain itself a. by leveraging open redirect: consequently the wallet MUST NOT follow redirect when querying the manifest b. by managing to host a file on the dapp domain: consequently the wallet SHOULD verify the <code>content-type</code> header is equal to <code>application/json</code> to mitigate this attack vector</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-07-23T00:00:00+00:00 2026-02-11T14:49:27+00:00 Guillaume Ballethttps://github.com/gballet Ignacio Hagopianhttps://github.com/jsign Gajinder Singhhttps://github.com/g11tech Ansgar Dietrichshttps://github.com/adietrichs 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/7748/

Describes a state conversion procedure to migrate key-values from the Merkle Patricia Tree to the Verkle Tree.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a procedure to convert, on each block, a fixed number of key-values from the existing Merkle Patricia Tree (MPT) to the Verkle Tree (VKT).</p> <h2 id="motivation">Motivation</h2> <p>The accounts state is too large to wait for transactions to organically move all of them to the VKT through the Overlay Tree. Thus, we need a strategy to convert all the state within a reasonable time. The state conversion completion allows removing the Overlay Tree abstraction introduced in <a href="https://wg-eips.ritovision.com/7612/">EIP-7612</a> and to use directly the VKT for all state access.</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>CONVERSION_START_TIMESTAMP</code></td><td><code>TBD</code></td><td>Timestamp at which the conversion starts.</td></tr> <tr><td><code>CONVERSION_STRIDE</code></td><td><code>TBD</code></td><td>Maximum number of <em>conversion units</em> to be converted per block</td></tr> </tbody></table> <p>A <em>conversion unit</em> is:</p> <ul> <li>A contract storage slot.</li> <li>An account data (e.g. balance, nonce, code-hash) and code (if any).</li> </ul> <h3 id="changes-to-the-execution-spec">Changes to the execution spec</h3> <p>Include the following code in the existing <code>apply_body(...)</code> 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"> apply_body</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> State</span><span>,</span><span> ...</span><span>)</span><span> -&gt;</span><span> Tuple</span><span>[</span><span>Uint</span><span>,</span><span> Root</span><span>,</span><span> Root</span><span>,</span><span> Bloom</span><span>,</span><span> State</span><span>,</span><span> Root</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"> &lt;new_code&gt;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> block_time</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> CONVERSION_START_TIMESTAMP</span><span class="z-keyword"> and</span><span class="z-keyword"> not</span><span> state</span><span>.</span><span>_conversion_finished</span><span>:</span></span> <span class="giallo-l"><span> state_convert</span><span>(</span><span>state</span><span>,</span><span class="z-constant"> CONVERSION_STRIDE</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> &lt;/new_code&gt;</span></span> <span class="giallo-l"><span> </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> transactions</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre> <p>Before executing txs, it calls <code>state_convert(...)</code> (described below) which performs a state conversion step for this block.</p> <p>In <code>state.py</code>, add the following code:</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"> StoragePhase</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"> The account next conversion step continues converting the </span></span> <span class="giallo-l"><span class="z-string"> storage-slot with key greater than or equal to next_key. </span></span> <span class="giallo-l"><span class="z-string"> If there isn&#39;t such a storage-slot, the account must move to</span></span> <span class="giallo-l"><span class="z-string"> AccountDataPhase.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> next_key</span><span>:</span><span> Bytes</span><span> </span></span> <span class="giallo-l"><span> </span></span> <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"> AccountDataPhase</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"> The account next conversion step continues migrating the account </span></span> <span class="giallo-l"><span class="z-string"> code (if any) and basic data. After processing, the account must </span></span> <span class="giallo-l"><span class="z-string"> move to the next account in the trie (or finish if it was the </span></span> <span class="giallo-l"><span class="z-string"> last one).</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-keyword"> pass</span></span> <span class="giallo-l"></span> <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"> CurrentConvertingAccount</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 the state conversion next step.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> address</span><span>:</span><span> Address</span></span> <span class="giallo-l"><span> phase</span><span> :</span><span> StoragePhase</span><span class="z-keyword"> |</span><span> AccountDataPhase</span></span></code></pre> <p>These new structures allows <code>State</code> to track where we're in the conversion process.</p> <p>Modify the <code>State</code> class by adding the following attributes:</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-comment"> #</span><span class="z-comment"> &lt;new_code&gt;</span></span> <span class="giallo-l"><span> _conversion_curr_account</span><span>:</span><span> Optional</span><span>[</span><span>CurrentConvertingAccount</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> None</span></span> <span class="giallo-l"><span> _conversion_finished</span><span>:</span><span class="z-support"> bool</span><span class="z-keyword"> =</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> &lt;/new_code&gt;</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"><span> </span></span></code></pre> <p>Define a function with the following signature:</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"> trie_get_next_at_key</span><span>(</span><span class="z-variable z-parameter z-function">trie</span><span>:</span><span> Trie</span><span>[</span><span>K</span><span>,</span><span> V</span><span>]</span><span>,</span><span class="z-variable z-parameter z-function"> key_seek</span><span>:</span><span> Bytes</span><span>)</span><span> -&gt;</span><span> (</span><span>K</span><span>,</span><span> V</span><span>,</span><span> Optional</span><span>[</span><span>Bytes</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"> Returns the first (key, value) in the trie-key is &gt;= key_seek.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> This method must only be used on Tries with secured=True,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> since key_seek is the keccak256(K).</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-punctuation z-definition z-comment"> #</span><span class="z-comment"> Returns:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> - K, V: the key and value (e.g: Address/Value, StorageSlot/Value)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> - next_key: The smallest trie-key present in the trie greater </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> than key_seek, or None if there isn&#39;t one.</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"> It is up to the implementer to decide the best implementation</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> considering its client architecture.</span></span></code></pre> <p>Add or modify the following functions:</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"> New function.</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> get_conversion_account</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> State</span><span>)</span><span> -&gt;</span><span> CurrentConvertingAccount</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> When starting the conversion, initialize with the first account</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> in the MPT.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> state</span><span>.</span><span>_conversion_curr_account</span><span class="z-keyword"> is</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"> Initialize with the first account in the account trie.</span></span> <span class="giallo-l"><span> first_account</span><span class="z-keyword"> =</span><span> trie_get_next_at_key</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-punctuation z-definition z-comment"> #</span><span class="z-comment"> Accounts conversion starts with storage-slots conversion.</span></span> <span class="giallo-l"><span> phase</span><span class="z-keyword"> =</span><span> StoragePhase</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-comment"> #</span><span class="z-comment"> Starts with the lowest storage-slot key.</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>_conversion_curr_account</span><span class="z-keyword"> =</span><span> CurrentConvertingAccount</span><span>(</span><span>first_account</span><span>,</span><span> phase</span><span>)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> state</span><span>.</span><span>_conversion_curr_account</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 function.</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> conversion_move_to_next_account</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> State</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> curr_account</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>get_conversion_account</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> address</span><span>,</span><span> _</span><span>,</span><span> next_key</span><span class="z-keyword"> =</span><span> trie_get_next_at_key</span><span>(</span><span>state</span><span>.</span><span>_main_trie</span><span>,</span><span> curr_account</span><span>.</span><span>phase</span><span>.</span><span>next_key</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> next_key</span><span class="z-keyword"> is</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"> We finished the conversion</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>_conversion_finished</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"> Move to the next account</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>_conversion_curr_account</span><span>.</span><span>address</span><span class="z-keyword"> =</span><span> address</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>_conversion_curr_account</span><span>.</span><span>phase</span><span class="z-keyword"> =</span><span> StoragePhase</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Modified function: add new only_if_empty optional parameter.</span></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"> addr</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><span class="z-variable z-parameter z-function"> only_if_empty</span><span>:</span><span class="z-support"> bool</span><span class="z-keyword"> =</span><span class="z-constant"> True</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"> &lt;new_code&gt;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> only_if_empty</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> key</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> &lt;/new_code&gt;</span></span> <span class="giallo-l"><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> key</span><span>)</span><span>,</span><span> value</span><span>)</span></span></code></pre> <p>As mentioned previously, the next function is called by <code>apply_body(...)</code> to perform the conversion step for a block:</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"> Note the following function is optimized for readability, not for performance.</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> state_convert</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"> stride</span><span>:</span><span class="z-support"> int</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> n</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> n</span><span class="z-keyword"> &lt;</span><span> stride</span><span class="z-keyword"> and</span><span class="z-keyword"> not</span><span> state</span><span>.</span><span>_conversion_finished</span><span>:</span></span> <span class="giallo-l"><span> curr_account</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>get_conversion_account</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"> Skip translating storage if the account has an empty code hash.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Skip storage conversion for accounts with 0 nonce and empty code.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> This covers the 28 EIP-7610 accounts, but would also cover all</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> pre-eip161 accounts on other chains.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> curr_account</span><span>.</span><span>nonce</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span class="z-keyword"> and</span><span class="z-support"> len</span><span>(</span><span>curr_account</span><span>.</span><span>code</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>_conversion_curr_account</span><span>.</span><span>phase</span><span class="z-keyword"> =</span><span> AccountDataPhase</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"> Account storage.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> curr_account</span><span>.</span><span>phase</span><span class="z-keyword"> is</span><span> StoragePhase</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Get the storage-slot from _storage_tries which is MPT data.</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>curr_account</span><span>.</span><span>address</span><span>)</span></span> <span class="giallo-l"><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-keyword"> not</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> slot_num</span><span>,</span><span> slot_value</span><span>,</span><span> next_key</span><span class="z-keyword"> =</span><span> trie_get_next_at_key</span><span>(</span><span>trie</span><span>,</span><span> curr_account</span><span>.</span><span>phase</span><span>.</span><span>next_key</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> The Overlay Tree will write in the VKT. We use the new</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> only_if_empty parameter to avoid writing stale values.</span></span> <span class="giallo-l"><span> set_storage</span><span>(</span><span>state</span><span>,</span><span> curr_account</span><span>.</span><span>address</span><span>,</span><span> slot_num</span><span>,</span><span> slot_value</span><span>,</span><span class="z-variable"> only_if_empty</span><span class="z-keyword">=</span><span class="z-constant">True</span><span>)</span></span> <span class="giallo-l"><span> n</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> next_key</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-punctuation z-definition z-comment"> #</span><span class="z-comment"> There&#39;re more storage-slots to be converted, continue in this phase.</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>conversion_curr_account</span><span>.</span><span>phase</span><span>.</span><span>next_key</span><span class="z-keyword"> =</span><span> next_key</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"> No more storage-slots. Move to the account data migration.</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>conversion_curr_account</span><span>.</span><span>phase</span><span class="z-keyword"> =</span><span> AccountDataPhase</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-punctuation z-definition z-comment"> #</span><span class="z-comment"> There&#39;s no storage trie for the account, move directly to</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> migrating account&#39;s data and code (if any).</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>conversion_curr_account</span><span>.</span><span>phase</span><span class="z-keyword"> =</span><span> AccountDataPhase</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Account code and basic data.</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"> Getting the code from the Overlay Tree is fine since it promises to return</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> the Account full code which would come from the MPT or a separate code database.</span></span> <span class="giallo-l"><span> account</span><span class="z-keyword"> =</span><span> get_account</span><span>(</span><span>state</span><span>,</span><span> curr_account</span><span>.</span><span>address</span><span>)</span></span> <span class="giallo-l"><span> chunked_code</span><span class="z-keyword"> =</span><span> chunkify_code</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"> for</span><span> chunk_num</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span class="z-support">len</span><span>(</span><span>chunked_code</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> state_set_codechunk</span><span>(</span><span>state</span><span>,</span><span> address</span><span>,</span><span> chunk_num</span><span>,</span><span> chunked_code</span><span>[</span><span>chunk_num</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"> If the account data (i.e: nonce, balance, code-size, code-hash) lives in MPT, </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> get_account will pull from MPT and then we write to the VKT. If the account </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> data already lives in the VKT (i.e: it was indirectly converted by a tx), then </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> it will return it from the VKT and write it again (i.e: it&#39;s a noop).</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Thus, this operation is correct under both scenarios. That is, it won&#39;t</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> write stale data.</span></span> <span class="giallo-l"><span> account</span><span class="z-keyword"> =</span><span> get_account</span><span>(</span><span>state</span><span>,</span><span> curr_account</span><span>.</span><span>address</span><span>)</span></span> <span class="giallo-l"><span> set_account</span><span>(</span><span>state</span><span>,</span><span> curr_account</span><span>.</span><span>address</span><span>,</span><span> account</span><span>)</span></span> <span class="giallo-l"><span> n</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> state</span><span>.</span><span>conversion_move_to_next_account</span><span>(</span><span>)</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="state-conversion-step-position-in-block-execution">State conversion step position in block execution</h3> <p>Performing the conversion step before the block txs execution has some benefits:</p> <ul> <li>If the state conversion step is done after txs execution, there's a possibility that txs execution writes overlap with converted key-values, having to care about them becoming stale in the same block. With the proposed ordering, they can only become stale by writes of previous blocks.</li> <li>It can reduce the complexity of optimizations, such as frontrunning the state conversion for the next block before it arrives.</li> </ul> <h3 id="conversion-stride-proposed-value"><code>CONVERSION_STRIDE</code> proposed value</h3> <p>Performance benchmarks were done to achieve the right balance between:</p> <ul> <li>Don't overload the clients with too much extra work per block.</li> <li>Don't create an unmanageable load in clients during feasible long reorgs.</li> <li>Finish the conversion as fast as possible.</li> </ul> <h3 id="account-code-chunking-done-in-a-single-step">Account code chunking done in a single step</h3> <p>If an account has code, this is chunked and inserted in the VKT in one go. An alternative is including a <code>CodePhase</code> and let each inserted chunk consume one unit of <code>CONVERSION_STRIDE</code>.</p> <p>We decided to not do this to reduce the algorithm complexity. Considering the current maximum code size, the worst case scenario for a block could overflow the <code>CONVERSION_STRIDE</code> limit by 24k/31~=793 units.</p> <h3 id="deletion-of-eip-7610-accounts">Deletion of <a href="https://wg-eips.ritovision.com/7610/">EIP-7610</a> accounts</h3> <p>EIP-7610 mentions the existence of 28 accounts that have:</p> <ul> <li>a nonce of 0,</li> <li>no code</li> <li>a non-empty storage tree</li> </ul> <p>These storage slots are to be omitted from the conversion process, as they can not be accessed.</p> <h3 id="expected-time-for-the-conversion-to-finish">Expected time for the conversion to finish</h3> <p>TODO: We have an estimation, but it might be worth recalculating it closer to the proposed fork having a more up to date state size estimate.</p> <h3 id="missed-slots">Missed slots</h3> <p>The conversion logic runs at the start of each block, so missed slots don't create special situations.</p> <h3 id="accounts-storage-account-data-order">Accounts storage-&gt;account-data order</h3> <p>The proposed order synergizes with many EL client flat-db architectures, minimizing random disk-IO.</p> <h3 id="not-counting-eip-161-accounts-for-conversion-stride-limit">Not counting <a href="https://wg-eips.ritovision.com/161/">EIP-161</a> accounts for <code>CONVERSION_STRIDE</code> limit</h3> <p>The <code>CONVERSION_STRIDE</code> parameter tries to limit the load of effective writes. These special accounts are skipped since we try to perform a bulk <a href="https://wg-eips.ritovision.com/158/">EIP-158</a> deletion of the remaining accounts.</p> <p>This might sound dangerous since if there were 1k of these accounts and all corresponded to be converted in the same block, we'd be forcing the clients to iterate 1k accounts without counting any quota from <code>CONVERSION_STRIDE</code>. The number of remaining accounts to delete is very low (i.e.: dozen) and also not contiguous, so this shouldn't be a concern.</p> <h3 id="mpt-preimage-resolving">MPT preimage resolving</h3> <p>EL clients are expected to satisfy at least one of these conditions:</p> <ul> <li>They have a proper flat-db design, which doesn't require preimage resolving.</li> <li>They have a full preimage database which can resolve <em>trie_key</em>-&gt;<em>preimage</em> (but this can have poor performance).</li> <li>They have downloaded the preimage database image that will be distributed before the conversion starts.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="test-cases">Test Cases</h2> <p>TODO: currently described in an external document.</p> <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</code> to a non-zero value on the command line.</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> 2024-07-17T00:00:00+00:00 2026-02-11T14:49:27+00:00 Zsolt Felföldihttps://github.com/zsfelfoldi https://wg-eips.ritovision.com/7745/

An efficient, light client and DHT friendly replacement for block header bloom filters

<h2 id="abstract">Abstract</h2> <p>Replace the fixed 2048 bit log event bloom filters with a new lookup index data structure that can adapt to the changing number of events per block and consistently guarantee a sufficiently low false positive ratio, allowing efficient trustless proofs of log event queries, canonical block hash and transaction hash lookups.</p> <p>The proposed structure maps all index entries (log events, transaction and block markers) onto a global linear index space and hashes them into a binary Merkle tree based on that index. It also contains a <em>filter map</em> for every fixed length section of the index space. These are two dimensional sparse bit maps that provide an efficient probabilistic method for looking up indexed values or query patterns of values, yielding potential matches in the form of exact positions in the linear index space. Unlike the per-block bloom filters, they allow searching for specific events by accessing only a small portion of the entire dataset which can also be proven with a Merkle proof, making the search both efficient and light client friendly.</p> <p>The proposed structure can be efficiently used both for local search and for remote proof generation/verification, thereby simplifying implementation of provers and verifiers. It also allows validators that are not interested in either searching or proving logs to generate the index root hash by maintaining a minimal index state with a relatively small (hard capped) size.</p> <h2 id="motivation">Motivation</h2> <p>Adding logs has a significantly lower gas cost and should accordingly be less resource consuming than writing to the state. The original design of bloom filters in each block achieves this goal as there is no complex data structure like the state to update, the set of logs emitted in each block is all contained within the header and receipts belonging to that block. Logs mostly just have long term storage costs. On the other hand, searching logs in a long range of blocks is very expensive and the current bloom filters do not really help.</p> <p>Bloom filters are only useful as long as they are sufficiently sparse. False positive ratio rises rapidly with the number of events per filter and the density of <code>1</code> bits in the filter bit vector. In the currently existing bloom filter each log address and topic sets 3 out of a fixed length of 2048 bits which resulted in sufficiently sparse filters in the beginning but with the increase of the block gas limits the false positive ratio soon made the filter practically useless. Mainnet blocks currently add over 1000 log addresses and topics in average and therefore the bloom filter size would need to increase about tenfold in order to achieve acceptable false positive rates again. This would raise block header size to about 3 kilobytes. Even if the size of the per-block bloom filters would be raised to a sufficient level, log search would still require accessing the entire header chain. Searching in just the most recent one year history would cost over 6 gigabytes of data, not counting the access of actual logs where the bloom filters have a match. The current situation is even worse, requiring a large portion of the full block receipt sets to be accessed due to the high false positive rate of the bloom filters. Transaction inclusion lookup is also very expensive, requiring all block bodies in the searched range.</p> <p>While full nodes and RPC servers can and usually do build additional index structures to aid certain lookups, these structures cannot be verified remotely. While it is important to improve the transaction processing capabilities of Ethereum, trustless provability is required throughout the entire stack, from end user applications signing transactions, to the same or other end user applications getting the results they need. Scaling transaction processing only makes sense as long as there is also a trustless and scalable way to access the relevant results of those transactions. Users relying on trusted servers and indexers kind of beats the whole point of Ethereum.</p> <h2 id="specification">Specification</h2> <h3 id="terms-and-definitions">Terms and definitions</h3> <ul> <li><em>index entry</em>: a single entry in the <code>index_entries</code> tree associated with an indexed event. It is either a <em>log entry</em>, a <em>transaction entry</em> or a <em>block entry</em>. An <em>index entry</em> generates one or more <em>map values</em>. Each <em>log entry</em> adds one <em>address value</em> and 0..4 <em>topic values</em> (in this order). Each <em>transaction entry</em> adds one <em>transaction value</em> and each <em>block entry</em> adds one <em>block value</em>.</li> <li><em>map value</em>: a searchable value associated with an <em>index entry</em>. It is either an <em>address value</em>, a <em>topic value</em>, a <em>transaction value</em> or a <em>block value</em>. Each <em>map value</em> is represented by a 32 byte hash (the <em>map value hash</em>) which is calculated as <code>sha2(address)</code>, <code>sha2(topic)</code>, <code>sha2(tx_hash + b"\x01")</code> or <code>sha2(block_hash + b"\x02")</code>.</li> <li><em>map value index</em>: a single position in the global linear index space. A new <em>map value index</em> is assigned to each indexed <em>map value</em>.</li> <li><em>map entry index</em>: the position where an <em>index entry</em> is located in the <code>index_entries</code> tree. Each <em>index entry</em> is located at the position corresponding to the <em>map value index</em> of the first <em>map value</em> it generates.</li> <li><em>filter map</em>: a <code>MAP_WIDTH</code> by <code>MAP_HEIGHT</code> sized sparse bit map assigned to a <code>VALUES_PER_MAP</code> length section of the <em>map value index</em> space. Each <em>map value</em> assigned to this range is marked on the map at a row and column that depends on the <em>map value index</em>, <em>mapping layer</em> and the <em>map value hash</em>. Rows are sparsely encoded as a list of marked column indices (in strictly ascending order, which also coincides with the order of occurence). Each map contains at most <code>VALUES_PER_MAP</code> marks and therefore the chance of false positives is kept at a constant low level.</li> <li><em>mapping layer</em>: each layer defines a (<em>map index</em>, <em>map value hash</em>) =&gt; <em>row index</em> mapping and imposes a limit on the number of <em>map values</em> mapped into each row using that particular mapping. Multiple <em>mapping layers</em> can be applied simultaneously on the same <em>filter map</em>. Each <em>map value</em> is mapped using the lowest possible <em>mapping layer</em> where the number of marks in the assigned row is lower than the limit. On layer 0 the <em>row index</em> mapping only changes once per <em>index epoch</em>. On higher layers the mapping changes more frequently and also the row size limit is higher.</li> <li><em>index epoch</em>: a <code>MAPS_PER_EPOCH</code> sized group of consecutive <em>filter maps</em> stored in the hash tree in a way so that multiple rows of adjacent <em>filter maps</em> with the same <em>row index</em> can be efficiently retrieved in a single Merkle multiproof.</li> </ul> <h3 id="consensus-data-format">Consensus data format</h3> <h4 id="block-headers">Block headers</h4> <p>Beginning at the execution timestamp <code>FORK_TIMESTAMP</code>, execution clients MUST replace the <code>logs_bloom</code> field of the header schema with <code>log_index_root</code> which is the root hash of the <code>LogIndex</code> structure after adding the logs emitted in the given 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> log_index_root,</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> parent_beacon_block_root,</span></span> <span class="giallo-l"><span>])</span></span></code></pre><h4 id="container-types">Container types</h4> <p>These definitions use the <code>ProgressiveList</code> and <code>ProgressiveByteList</code> SSZ types as defined in <a href="https://wg-eips.ritovision.com/7916/">EIP-7916</a>.</p> <p>Note that the <code>LogIndex</code> and <code>IndexEpoch</code> container definitions below are "naive" definitions suitable to define SSZ merkleization. The entire log index is typically too big to be represented in memory as a whole. A more efficient implementation can be found here: <a href="https://wg-eips.ritovision.com/7745/./assets/log_index.py">log_index.py</a>, <a href="https://wg-eips.ritovision.com/7745/./assets/binary_tree.py">binary_tree.py</a> (taken from the EELS implementation). This code keeps only the currently processed parts of the tree in memory, expanding untouched empty subtrees on demand and collapsing finalized subtrees.</p> <p>Also note that the containers defined here (including <code>FilterRow</code>) have a non-initialized default value, represented as a null leaf in the Merkle tree. Initialization of these containers is explicit and happens at a well defined point. <code>IndexEpoch</code> is initialized when the first <em>index entry</em> is added to the epoch. All rows of a map are initialized when the first <em>index entry</em> is added to the map. <code>IndexEntry</code> is initialized when added; entry positions belonging to unused <em>map entry indices</em> are left uninitialized. The <code>Log</code> container is only initialized in case of <em>log entries</em>. If it is initialized then <code>topics</code> and <code>data</code> lists in the <code>Log</code> container are always initialized.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>class LogIndex(Container):</span></span> <span class="giallo-l"><span> epochs: Vector[IndexEpoch, MAX_EPOCH_HISTORY]</span></span> <span class="giallo-l"><span> next_index: uint64</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>class IndexEpoch(Container):</span></span> <span class="giallo-l"><span> filter_maps: Vector[Vector[FilterRow, MAPS_PER_EPOCH], MAP_HEIGHT]</span></span> <span class="giallo-l"><span> index_entries: Vector[IndexEntry, MAPS_PER_EPOCH * VALUES_PER_MAP]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>type FilterRow = ProgressiveList[uint32]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>class IndexEntry(Container):</span></span> <span class="giallo-l"><span> log_entry: Log</span></span> <span class="giallo-l"><span> entry_meta: Vector[Bytes32, 4] # LogMeta / TransactionMeta / BlockMeta</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>class Log(Container):</span></span> <span class="giallo-l"><span> address: ExecutionAddress</span></span> <span class="giallo-l"><span> topics: List[Bytes32, 4]</span></span> <span class="giallo-l"><span> data: ProgressiveByteList</span></span></code></pre> <p>The <code>entry_meta</code> vector has a fixed format but its interpretation depends on the type of <em>index entry</em> and the type of entry can also be determined based on its contents (and based on whether <code>log_entry</code> is initialized or not). Whenever <code>IndexEntry</code> is initialized, <code>entry_meta</code> contains either one of these containers:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>class LogMeta(Container):</span></span> <span class="giallo-l"><span> block_number: uint64</span></span> <span class="giallo-l"><span> transaction_hash: Root</span></span> <span class="giallo-l"><span> transaction_index: uint64</span></span> <span class="giallo-l"><span> log_in_tx_index: uint64</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>class TransactionMeta(Container):</span></span> <span class="giallo-l"><span> block_number: uint64</span></span> <span class="giallo-l"><span> transaction_hash: Root</span></span> <span class="giallo-l"><span> transaction_index: uint64</span></span> <span class="giallo-l"><span> receipt_hash: Root</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span>class BlockMeta(Container):</span></span> <span class="giallo-l"><span> block_number: uint64</span></span> <span class="giallo-l"><span> block_hash: Root</span></span> <span class="giallo-l"><span> timestamp: uint64</span></span> <span class="giallo-l"><span> zero: uint64</span></span></code></pre><h4 id="index-entry-types-and-corresponding-map-values">Index entry types and corresponding map values</h4> <p>Three types of <em>index entries</em> are added during state transition: log, transaction and block. For each processed transaction, a <em>transaction entry</em> is added first, then <em>log entries</em> are added in the order of EVM execution. The <em>block entry</em> referring to the processed block is not added during the state transition because it is supposed to reference the block hash which is not known yet. It can be added either after block building/validaton or are the beginning of the next state transition. In either case, the <code>block entry</code> of block N first appears in the log index state of block N+1 as the first new <code>index entry</code>.</p> <p>The following table shows an example of mapping all index entry types onto the <em>map value index</em> space:</p> <table><thead><tr><th>Index entry</th><th>Map entry index</th><th>Map values</th><th>Map value indices</th></tr></thead><tbody> <tr><td>Block #0</td><td>0</td><td>Block</td><td>0</td></tr> <tr><td>Tx #1/0</td><td>1</td><td>Transaction</td><td>1</td></tr> <tr><td>Log #1/0/0</td><td>2</td><td>Addr, 3x Topic</td><td>2, 3, 4, 5</td></tr> <tr><td>Log #1/0/1</td><td>6</td><td>Addr, 3x Topic</td><td>6, 7, 8, 9</td></tr> <tr><td>Tx #1/1</td><td>10</td><td>Transaction</td><td>10</td></tr> <tr><td>Log #1/1/0</td><td>11</td><td>Addr, 2x Topic</td><td>11, 12, 13</td></tr> <tr><td>Log #1/1/1</td><td>14</td><td>Addr, Topic</td><td>14, 15</td></tr> <tr><td>Log #1/1/2</td><td>16</td><td>Addr, 2x Topic</td><td>16, 17, 18</td></tr> <tr><td>Block #1</td><td>19</td><td>Block</td><td>19</td></tr> <tr><td>Tx #2/0</td><td>20</td><td>Transaction</td><td>20</td></tr> <tr><td>Log #2/0/0</td><td>21</td><td>Addr, 4x Topic</td><td>21, 22, 23, 24, 25</td></tr> </tbody></table> <p>Note that the missing <em>map entry indices</em> are represented in the <code>index_entries</code> tree with uninitialized <code>IndexEntry</code> containers (zero value leaves in the <code>index_entries</code> vector). Most of these empty entries correspond to the <em>topic value</em> indices. Also, the last few entries of each map might be emtpy because the <em>map values</em> generated by a single <em>index entry</em> never cross a filter map boundary. So, for example, when <code>VALUES_PER_MAP</code> is 0x10000 and <code>next_index</code> is <code>0x2FFFE</code> and a <em>log entry</em> with on address and two topics is added, the last two positions of the map are left empty and the new <em>log entry</em> is added starting from position 0x30000.</p> <h4 id="filter-map-row-encoding">Filter map row encoding</h4> <p>Each row of the <em>filter map</em> is encoded as a series of little endian binary encoded column indices. For encoding simplicity the column indices are always encoded as 32 bit values, regardless of the fact that <code>MAP_WIDTH</code> is less than 32. This only applies to consensus encoding and hashing though while local storage and proof encoding can use a more tightly packed format.</p> <h4 id="proposed-constants">Proposed constants</h4> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td>MAP_WIDTH</td><td>2**24</td></tr> <tr><td>MAP_HEIGHT</td><td>2**16</td></tr> <tr><td>VALUES_PER_MAP</td><td>2**16</td></tr> <tr><td>MAPS_PER_EPOCH</td><td>2**10</td></tr> <tr><td>MAX_EPOCH_HISTORY</td><td>2**24</td></tr> <tr><td>MAX_ROW_LENGTH</td><td>[8, 168, 2728, 10920]</td></tr> <tr><td>MAPPING_FREQUENCY</td><td>[2**10, 2**6, 2**2, 1]</td></tr> </tbody></table> <p>Note that <code>MAX_ROW_LENGTH</code> and <code>MAPPING_FREQUENCY</code> parameters are specified as lists because the applicable values depend on the used <em>mapping layer</em>. For layers higher than the index of the last elements of these lists the last element is applicable. Also note that the <code>MAX_ROW_LENGTH</code> values correspond to the cumulative capacity of <code>ProgressiveList</code> tree levels; a layer 0 row fits into the first level, a layer 1 row fits into the first three levels and so on.</p> <h3 id="constructing-the-filter-map">Constructing the filter map</h3> <p>For each <code>VALUES_PER_MAP</code> long section of the <em>map value index</em> space a <em>filter map</em> is generated. These are fixed size <code>MAP_WIDTH</code> by <code>MAP_HEIGHT</code> sparse bit maps and each <em>map value</em> is marked on the map with a single bit being set to one. The number of marks in a row (the length of the sparse encoded row) is referred to as "row length", not to be confused with the constant <code>MAP_WIDTH</code>.</p> <h4 id="epochs-and-mapping-layers">Epochs and mapping layers</h4> <p>In order to allow efficient search of a certain <em>map value</em> in a long historical range, <em>filter maps</em> are organized into <em>index epochs</em>, each consisting of a fixed <code>MAPS_PER_EPOCH</code> number of maps. In the most usual case (when row density is around average or below) row mapping stays the same during an entire epoch. The hash tree is organized in a way that instead of putting all rows of a single map close to each other, rows of the same <em>row index</em> throughout an entire epoch are close to each other and therefore are cheap to access and/or prove with a Merkle proof.</p> <p>In order to mitigate collisions in densely populated rows, the concept of <em>mapping layers</em> is introduced, meaning that if a certain row already has a certain number of entries then the row mapping is changed and very frequent <em>map values</em> are mapped into multiple rows. Initially, when a map is empty, every <em>map value</em> is mapped using <em>mapping layer</em> 0 or the "base layer". If a row reaches <code>MAX_ROW_LENGTH[0]</code> then any further <em>map values</em> mapped onto that row in the base layer mapping will use layer 1 mapping instead. On layer 1 a different row is assigned to the same <em>map value</em> and the row length limit in increased to <code>MAX_ROW_LENGTH[1]</code>. If this row also reaches its limit, layer 2 mapping is used and so on. Note that a row filled at a certain <em>mapping layer</em> can be grown further on a higher layer. Different <em>map values</em> colliding in the same row on a certain layer are probably mapped in different rows on the next layer, which means that a very popular value might populate multiple rows (also very long ones) but an unlucky less popular one colliding with it on base layer will probably just have to move one layer up. The search process is similar, if the searcher finds that the row belonging to the searched value is full according to the base layer limit then it also has to check the next layer and so on, until it finds a non-full row.</p> <p>If a row is longer than the limit according to the layer the searcher is looking at then it can safely ignore the extra entries assuming that they were added by another value on a higher layer. The <code>ProgressiveList</code> container makes it efficient to prove row data belonging to the lower layer even if there is much more data in the same row added on a higher layer.</p> <h4 id="row-mapping">Row mapping</h4> <p>While base layer row mapping stays the same for an entire epoch, higher layer mappings are changed more frequently. Each mapping change has a cost in terms of database access overhead and Merkle proof size overhead and epoch size is determined in a way that these overheads stay sufficiently low compared to the cost of accessing the actual useful data. On higher layers where the rows are longer, a more frequent remapping is possible because the useful data size per map is also higher. It is also desirable so that a less frequent <em>map value</em> will only suffer from colliding with a more popular one for a shorter time.</p> <p>The <em>row index</em> is calculated as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def get_row_index(map_index, layer_index: Uint, map_value_hash: Hash32) -&gt; Uint:</span></span> <span class="giallo-l"><span> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> Returns the row index where the given map value hash is mapped on the given</span></span> <span class="giallo-l"><span> map and mapping layer.</span></span> <span class="giallo-l"><span> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> mf_index = min(layer_index, len(MAPPING_FREQUENCY) - 1)</span></span> <span class="giallo-l"><span> mapping_frequency = MAPPING_FREQUENCY[mf_index]</span></span> <span class="giallo-l"><span> masked_map_index = map_index - (map_index % mapping_frequency)</span></span> <span class="giallo-l"><span> row_hash = sha256(</span></span> <span class="giallo-l"><span> map_value_hash</span></span> <span class="giallo-l"><span> + masked_map_index.to_le_bytes4()</span></span> <span class="giallo-l"><span> + layer_index.to_le_bytes4()</span></span> <span class="giallo-l"><span> ).digest()</span></span> <span class="giallo-l"><span> return Uint.from_le_bytes(row_hash[0:4]) % MAP_HEIGHT</span></span></code></pre> <p>The following figure shows how <em>map values</em> are mapped to rows on different <em>mapping layers</em>. Each dot represents a map row and the numbers indicate the <em>mapping layer</em> on which the row has been assigned to the given <em>map value</em>. Note that it might happen that a higher layer mapping coincides with a lower layer mapping for the same value; this does not cause any problem though as the row is simply grown further on the higher layer. The search algorithm can also simply revisit the same row in a higher layer iteration if necessary and process the rest of the row that it first ignored.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>map index 111111 1111222222222233 3333333344444444 4455555555556666</span></span> <span class="giallo-l"><span> 0123456789012345 6789012345678901 2345678901234567 8901234567890123</span></span> <span class="giallo-l"><span> +----------------+----------------+----------------+----------------+</span></span> <span class="giallo-l"><span>row 0 |2........2......|2...............|...2............|........2.......|</span></span> <span class="giallo-l"><span>row 1 |........1111.2..|.....2..1111....|1111.....2...2..|2111..2......2..|</span></span> <span class="giallo-l"><span>row 2 |0000000000000000|.2..2....2..2...|....2111....2...|..2.....11112...|</span></span> <span class="giallo-l"><span>row 3 |....2..22...1111|..........2.1111|2.......2.2.1111|.......2...2....|</span></span> <span class="giallo-l"><span>row 4 |.2..1111..2....2|1112..2.2....2..|0000000011110020|...21111.2....2.|</span></span> <span class="giallo-l"><span>row 5 |...2........2...|...............2|.2...2.........2|.2...2..........|</span></span> <span class="giallo-l"><span>row 6 |1111.22....2..2.|0020000000020000|.......2...2....|..........2.1112|</span></span> <span class="giallo-l"><span>row 7 |..2.............|....1112......2.|..2...2.........|0000200000000000|</span></span> <span class="giallo-l"><span> +----------------+----------------+----------------+----------------+</span></span> <span class="giallo-l"><span> epoch 0 epoch 1 epoch 2 epoch 3</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Fig 2. Row mapping of a single log value on different mapping layers</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>MAP_HEIGHT = 8</span></span> <span class="giallo-l"><span>MAPS_PER_EPOCH = 16</span></span> <span class="giallo-l"><span>MAPPING_FREQUENCY = [16, 4, 1]</span></span></code></pre><h4 id="column-mapping">Column mapping</h4> <p>Column mapping assumes that <code>MAP_WIDTH</code> is a multiple of <code>VALUES_PER_MAP</code>. <em>column index</em> is calculated as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def get_column_index(map_value_index: Uint, map_value_hash: Hash32) -&gt; Uint:</span></span> <span class="giallo-l"><span> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> Returns the column index where the given entry hash is mapped at the given</span></span> <span class="giallo-l"><span> entry index.</span></span> <span class="giallo-l"><span> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span> col_hash = fnv1a_64(map_value_index.to_le_bytes8() + map_value_hash)</span></span> <span class="giallo-l"><span> folded_hash = (col_hash &gt;&gt; 32) ^ (col_hash &amp; 0xFFFFFFFF)</span></span> <span class="giallo-l"><span> hash_bits = LOG2_MAP_WIDTH - LOG2_VALUES_PER_MAP</span></span> <span class="giallo-l"><span> return (</span></span> <span class="giallo-l"><span> (map_value_index % VALUES_PER_MAP)</span></span> <span class="giallo-l"><span> &lt;&lt; hash_bits + folded_hash</span></span> <span class="giallo-l"><span> &gt;&gt; (32 - hash_bits)</span></span> <span class="giallo-l"><span> )</span></span></code></pre> <p>As shown on the figure below, this mapping practically assigns a <code>MAP_WIDTH // VALUES_PER_MAP</code> by <code>MAP_HEIGHT</code> rectangle to each <em>map value index</em> and ensures that each <em>map value</em> places exactly one mark in its own rectangle (the letters A-D represent different <em>map values</em>). This property also ensures that <em>map value index</em> can be restored from <em>map index</em> and <em>column index</em>, column indices never collide and keep the original order of <em>map value</em> indices, allowing efficient Merkle exclusion proofs of certain <em>column indices</em> in long rows.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>column 11 1111 1111 2222 2222 2233</span></span> <span class="giallo-l"><span> 0123 4567 8901 2345 6789 0123 4567 8901</span></span> <span class="giallo-l"><span> +---------------------------------------+</span></span> <span class="giallo-l"><span>row 0 |.... .... .... .... .... .... .... ....|</span></span> <span class="giallo-l"><span>row 1 |.... .... .... .... .... .C.. .... ....|</span></span> <span class="giallo-l"><span>row 2 |.A.. .... ...A .... A... .... ...A ....|</span></span> <span class="giallo-l"><span>row 3 |.... .... .... .... .... .... .... ....|</span></span> <span class="giallo-l"><span>row 4 |.... .... .... .... .... .... .... ....|</span></span> <span class="giallo-l"><span>row 5 |.... .B.. .... ...B .... .... .... ....|</span></span> <span class="giallo-l"><span>row 6 |.... .... .... .... .... .... .... ..D.|</span></span> <span class="giallo-l"><span>row 7 |.... .... .... .... .... .... .... ....|</span></span> <span class="giallo-l"><span> +---------------------------------------+</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Fig 3. A single filter map with 8 entries of 4 different log values</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>MAP_WIDTH = 32</span></span> <span class="giallo-l"><span>MAP_HEIGHT = 8</span></span> <span class="giallo-l"><span>VALUES_PER_MAP = 8</span></span></code></pre><h3 id="updating-the-log-index-and-calculating-the-root-hash">Updating the log index and calculating the root hash</h3> <p>See the following functions in <a href="https://wg-eips.ritovision.com/7745/./assets/log_index.py">log_index.py</a>:</p> <ul> <li><code>log_index_add_log_entries</code></li> <li><code>log_index_add_transaction_entry</code></li> <li><code>log_index_add_block_entry</code></li> <li><code>log_index_root</code></li> </ul> <p>Note that the <em>block entry</em> may be added either after building/verifying the given block or before processing the next one, but <code>log_index_root</code> should always be calculated after adding transaction and log entries and before adding the block entry for the some block (block building would not even be possible otherwise as the log index root is referenced in the block header).</p> <h3 id="finding-potential-matches">Finding potential matches</h3> <p>Determining whether a <em>column index</em> found in the appropriate row is relevant for the searched <em>map value</em> is possible by restoring the <em>map value index</em> and then calculating the <em>column index</em> from it again in order to check whether the quasi-random collision filter part matches the expected value for the given <em>map value</em>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def get_map_value_index(map_index, column_index: Uint) -&gt; Uint:</span></span> <span class="giallo-l"><span> map_value_width = MAP_WIDTH // VALUES_PER_MAP</span></span> <span class="giallo-l"><span> return map_index * VALUES_PER_MAP + column_index // map_value_width</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def is_potential_match(map_index, column_index: Uint, map_value: Hash32) -&gt; bool:</span></span> <span class="giallo-l"><span> return get_column_index(get_map_value_index(map_index, column_index), map_value) == column_index</span></span></code></pre> <p>Iterating through all relevant <em>mapping layers</em> and corresponding rows is similar to how new <em>map values</em> are added. Filtering all potential matches from all relevant rows can be done with the following function:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def get_potential_matches((log_index: LogIndexReader, map_index: Uint, map_value: Hash) -&gt; List[Uint]:</span></span> <span class="giallo-l"><span> matches = []</span></span> <span class="giallo-l"><span> layer_index = 0</span></span> <span class="giallo-l"><span> while True:</span></span> <span class="giallo-l"><span> mr_index = min(layer_index, len(MAX_ROW_LENGTH) - 1)</span></span> <span class="giallo-l"><span> max_row_length = MAX_ROW_LENGTH[mr_index]</span></span> <span class="giallo-l"><span> row_index = get_row_index(map_index, layer_index, map_value)</span></span> <span class="giallo-l"><span> row = get_filter_row(log_index, map_index, row_index)[:max_row_length]</span></span> <span class="giallo-l"><span> for column_index in row:</span></span> <span class="giallo-l"><span> if is_potential_match(map_index, column_index, log_value):</span></span> <span class="giallo-l"><span> matches.append(get_log_value_index(map_index, column_index))</span></span> <span class="giallo-l"><span> if len(row) &lt; max_row_length:</span></span> <span class="giallo-l"><span> break</span></span> <span class="giallo-l"><span> layer_index += 1</span></span> <span class="giallo-l"><span> return matches</span></span></code></pre><h3 id="initialization-minimal-state-and-wire-protocol-extension">Initialization, minimal state and wire protocol extension</h3> <p>It is a property of the log index tree that over time most of the tree nodes get finalized, which means that in a minimal log index state representation finalized subtrees can be collapsed into a single tree node as their descendants are no longer needed for adding new entries. At every single moment there is one <em>filter map</em> being updated, maybe the few most recently completed maps might still be affected by a reorg, but if the chain finalizes properly then all but the few most recent maps are also finalized. Internal tree nodes with all finalized children are also finalized and can be collapsed into the lowest finalized ancestor. Similarly, internal nodes covering a range that has not been touched yet can be stored without having their children in memory, and they can be expanded on demand.</p> <p>Certain types of clients (those only interested in validation and not in using/serving log index data) have the option to just maintain this minimal log index state. Those who are interested in event history should probably also only keep the minimal state in memory and store the finalized and collapsed subtrees on disk. Clients can also initialize their log index with such a minimal state and then optionally regenerate the older parts from blocks and receipts locally. When the log index state of a finalized block is represented and no room for rollback is needed, the minimal tree representation simplifies into a set of Merkle branches leading to the map rows and to the <em>index entry</em> corresponding to <code>next_index</code> (with everything on the left side of these branches collapsed and nothing on their right sides expanded yet). Assuming an efficient encoding of the current <code>filter_map_rows</code> where the variable length of each filter row is encoded in two bytes and the column indices tightly packed into 3 bytes each, the minimal log index state can be serialized into 21300808 bytes. This number can be considered as an estimate of the amount of data required to initialize the log index data structure at any point.</p> <p>Note that initialization is also possible on an epoch boundary, in which case the log index is very cheap to initialize (only requires the last <em>block entry</em> branch before the epoch boundary and the first one after) but in this case all blocks and receipts between the boundary and the current head are required to generate the last unfinished epoch. Epoch boundary initialization can also be used to index further historical epochs after the initialization of the head state.</p> <p>Both head state initialization and epoch boundary initialization requires the extension of the Ethereum Wire Protocol through which clients can request Merkle multiproofs to initialize the required parts of the log index tree, using a recently finalized block as the starting point. Note that since the total amount of initialization data is too big to fit in a single devp2p response, the protocol splits the data into multiple subsets, each obtainable in the form of a separately verifiable log index Merkle proof. See the <a href="https://wg-eips.ritovision.com/7745/assets/wire_protocol_extension/">wire protocol extension</a> and <a href="https://wg-eips.ritovision.com/7745/assets/log_index_proof_format/">log index proof format</a> specs for further details.</p> <h2 id="rationale">Rationale</h2> <h3 id="design-goals">Design goals</h3> <p>The proposed data structure is intended to realize a balance between the cost of adding items and accessing old ones. In a search structure of a constantly growing dataset there is typically a tradeoff between the cost of adding new data and the cost of searcing the existing dataset. One extreme is just linearly storing the data, which is practically the case now with logs, with the bloom filters being mostly useless. The other extreme is one big Merkle tree with all <em>map values</em> ever used as keys and the list of all occurences (possibly in a further merkleized format) as values. With billions of unique <em>map values</em>, adding new entries here is expected to have costs similar to that of the state, with multiple lookups and modifications/insertions at random places in a database on the order of magnitude of hundreds of gigabytes. Another issue where this is similar to the state is that removing old entries is hard and expensive. Adding logs is supposed to be cheaper than writing the state so solutions between these two extremes were considered as potentially practical, with multiple smaller structures generated periodically.</p> <p>The <em>filter maps</em> have a fixed tree size and an efficient tree hashing scheme. Filter entries are sorted into rows based on content and position in a way that allows quick linear database access and size efficient Merkle proofs. The difficulties arising from certain types of events being much more frequent than others are also mitigated. Update and maintenance costs are also limited as tree nodes are eventually finalized and the number of non-finalized non-empty nodes is always hard capped, ensuring moderate memory requirements. Initialization costs of the data structure at any point of the chain are also capped. Additional database storage costs of <em>filter maps</em> is about 15-20% of the size of the actual logs, depending on certain implementation tradeoffs. The Merkle tree structure also makes it easy to discard entire epochs along with the corresponding Merkle subtrees, making the implementation of history expiry of the log index simple.</p> <h3 id="map-value-index-space">Map value index space</h3> <p>In each block a varying number of <em>map values</em> are emitted. In addition to inefficient search, another drawback of per-block fixed size bloom filters is the varying filter utilization leading to over-utilized filters giving many false positives in some blocks and/or wastefully under-utilized filters in some blocks. Block gas limits also tend to change significantly over the long term so any future-proof solution has to be able to adapt to the varying number of <em>map values</em> per block.</p> <p>Mapping <em>map values</em> on their own linear index space ensures uniform filter utilization of identically structured <em>filter maps</em>. Compared to the alternative of constantly changing adaptive filter size, this approach greatly improves the efficiency of database access and Merkle proofs. It also allows efficient search pattern filtering as each potential match provides exact position information.</p> <h3 id="index-entries-tree">Index entries tree</h3> <p>Hashing every event into the <code>index_entries</code> tree keyed by <em>map entry index</em> is additional work and complexity but it simplifies the proving process significantly. Proving the events based only on <em>map value indices</em> would be possible if receipts had a <em>map value index</em> pointer hashed into them (so the client could also verify that the received receipt actually covers the <em>map value index</em> derived from the <em>filter map</em>; in this case though an extra mechanism would be necessary to prove that the receipt is referenced in a block that is part of the same canonical chain where the log index root was referenced. Proving old canonical blocks is currently theoretically possible through the beacon chain but painful and also would require extra infrastructure. On the other hand, the <code>index_entries</code> tree not only solves the problem of proving the matching canonical receipts, with the <em>block entries</em> it also provides a convenient way to prove canonical EL blocks through EL data structures only, and even provides provable canonical block hash to block number lookups.</p> <p>Note though that storing the entire<code>index_entries</code> trees directly in their proposed merkleized format on disk is not really efficient. This is not an issue for validators that want to maintain a minimal state; for them, updating the <code>index_entries</code> subtrees is really cheap as they only need to maintain a single Merkle branch pointing to the next <em>map value index</em>. Provers can implement <code>index_entries</code> efficiently by storing a subset of the Merkle tree nodes (the ones at least a few levels below leaf level in order to save space) and generate the rest on demand based on the receipts that encode the same data in a more compact form.</p> <h3 id="alternative-filter-structures-considered">Alternative filter structures considered</h3> <p>One question considered was whether to periodically build lookup trees of events with each unique <em>map value</em> emitted in a given period being a separate key under which only the occurences of that specific event are listed, or to use a more compressed fixed size tree format where different <em>map values</em> might collide (though preferably not too many of them). This decision mostly boiled down to data access efficiency, both in terms of local disk access and remote Merkle proof size. Identically structured trees can be efficiently arranged in larger units (called <em>index epochs</em> here), with values belonging to the same key in subsequent trees of an epoch located close to each other. This improves database access speed. It also allows smaller Merkle proofs with a series of leaves encoded together in an efficient format and internal nodes on only two boundary branches. Database writes are also efficient as the order of adding tree entries is not random and all the non-finalized parts of the tree can be kept in memory with a hard capped memory requirement.</p> <p>The other design decision considered here was whether to hash entire index entries into the list of <em>map value</em> occurences or just store position info and have a separate tree of log entries. Though the separate <code>filter_maps</code> and <code>index_entries</code> structures do present some additional complexity, the second option was chosen because of the size of Merkle proofs. Looking up a rarely used <em>map value</em> means encountering more irrelevant entries than relevant ones. By adding probabilistic filter information to position information, the vast majority of the irrelevant entries can be filtered out after accessing/proving 3 bytes of data instead of an entire <em>map value</em> (32 bytes). When proving matches of multiple <em>map value</em> patterns this 10x advantage exists even with more frequent individual lookup values. Tests have shown that realistic log searches often yield a lot more matches for the individual <em>map values</em> themselves that the pattern itself. Pattern matching can be performed on the position information of individual potential matches and actual <em>index entries</em> only need to be proven at the potential pattern matches.</p> <p>In conclusion, for the given application the fixed tree size approach with separate position info plus probabilistic collision filter approach seemed to be the most appropriate.</p> <h3 id="false-positive-rate">False positive rate</h3> <p>From the <em>filter maps</em> a set of potential matches can be derived for any block range and <em>map value</em> or pattern of <em>map values</em>. These matches can then be looked up in the corresponding <code>index_entries</code> trees and actually matching events can be added to the set of results. The design guarantees that the set of potential matches includes all actual matches but and also has a consistently low false positive rate.</p> <p>False positives can happen when the quasi-random collision filter part of a <em>column index</em> accidentally matches the expected value even though it was generated by a <em>map value</em> other than the searched one. The chance of this happening is <code>VALUES_PER_MAP / MAP_WIDTH</code> per colliding enrty in a row that is relevant for the search. Assuming that most entries in a map are different from the searched one, assuming uniform random distribution of entries, the average number of colliding entries found in a relevant row is <code>VALUES_PER_MAP / MAP_HEIGHT</code> giving an average false positive rate of <code>VALUES_PER_MAP ** 2 / MAP_WIDTH / MAP_HEIGHT</code> per <em>filter map</em>.</p> <p>Though certain <em>map values</em> might be emitted a lot more than others and therefore the <em>row index</em> distribution might not be entirely uniform, periodical remapping of rows and using multiple <em>mapping layers</em> ensures that over a long enough search period random collisions with more frequent <em>map values</em> do even out. <em>Mapping layers</em> do have another consequence though; if any row has at least <code>MAX_ROW_LENGTH[0]</code> entries then the search logic requires looking into another row that is mapped to the searched <em>map value</em> on the next <em>mapping layer</em>. The maximum possible number of such rows is <code>VALUES_PER_MAP / MAX_ROW_LENGTH[0]</code> and therefore the chance of randomly hitting one is <code>VALUES_PER_MAP / MAX_ROW_LENGTH[0] / MAP_HEIGHT</code> in the worst case. In this case an extra row has to be processed, with extra chance of finding false positives. A collision with a frequent value at a certain <em>mapping layer</em> does not indicate a collision on the next layer though, therefore the expected number of entries in that row is no different from the first one. Having to process a third row would presume that the second one had at least <code>MAX_ROW_LENGTH[1]</code> entries. The chance of this happening after the first coincidence is practically negligible in the context of expected false positives.</p> <p>The expected number of false positives for a single <em>map value</em> search can be estimated as <code>VALUES_PER_MAP ** 2 / MAP_WIDTH / MAP_HEIGHT * (1 + VALUES_PER_MAP / MAX_ROW_LENGTH[0] / MAP_HEIGHT)</code> per <em>filter map</em>. With the proposed constants this roughly equals 0.0044 false positives per map. As of March 2025 the average number of <em>map values</em> emitted in a mainnet block is slightly over 1000 while a <em>filter map</em> consists of 65536 <em>map values</em>. This gives a rough estimate of one false positive per 14000 blocks, which costs the searcher an extra lookup in a <code>log_entries</code> tree. The expected number of false positives in the entire chain history is around 1200.</p> <p>Note that this is only true for a single value search while a typical pattern search requiring certain values on multiple positions has an exponentially lower false positive rate. For example if the pattern is [Addr, Topic1, Topic2] then three <em>map value</em> searches are performed and an actual log lookup is only necessary if the first search yields <code>N</code>, the second <code>N+1</code> and the third <code>N+2</code> simultaneously. If necessary, the rate can be easily reduced by using a higher <code>MAP_WIDTH</code>, at the cost of growing the size of encoded rows.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The existing log filter API (<code>eth_getLogs</code>, <code>eth_newFilter</code>, <code>eth_getFilterLogs</code>, <code>eth_getFilterChanges</code>) can be implemented with the new filter data structure. Applications relying on this API can operate without any change, benefiting from a higher search performance. Repricing the <code>LOG</code> opcode might be considered after performing benchmarks but the extra processing cost is not significant while the extra storage cost is around 15%. Other than that the EVM is not affected in any way as it only emits logs but does not directly access them.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="safe-access-with-a-remote-prover">Safe access with a remote prover</h3> <p>In order to prove a complete set of matches matching a given search pattern in a given block range, the prover needs to</p> <ul> <li>prove the <em>map value index</em> range that corresponds to the searched block number range by proving the <em>block entries</em> of <code>first_block - 1</code> and <code>last_block</code></li> <li>prove the relevant rows of <em>filter maps</em> based on <em>map index</em> and <em>row index</em> (verifier can determine the relevant rows in advance based on the <em>map values</em> in the search pattern and the relevant <em>map value index</em> range)</li> <li>prove the actual <em>index entry</em> belonging to any potentially matching <em>map value index</em> and also the <em>block entry</em> with the same block number if the <code>blockHash</code> of the log position info is needed</li> </ul> <p>Since all three steps can be realized with Merkle proofs of the same <code>LogIndex</code> structure referenced in the block headers, any search with a remove prover is as safe as the client's knowledge about the chain head.</p> <h3 id="deliberate-false-positive-attacks">Deliberate false positive attacks</h3> <p>The design guarantees that false positive rates do even out statistically over several epochs, even in case of random collisions with very frequent values, ensuring that an excessive amount false positives will not make the bandwidth and processing costs of the search prohibitively high. All of this is true for random collisions only though, not deliberately created collisions. A deliberate attack on a certain important <em>map value</em> in order to raise its false positive rate can not be ruled out entirely since with a low amount of filter data generated per <em>map value</em> it is always possible to "mine" another value that generates colliding filter data. The column mapping used here makes this attack a lot harder though, since the <em>column index</em> depends on both the <em>map value</em> and the exact <em>map value index</em>, making this attack only possible for block builders who are probably offered MEV rewards for much more lucrative manipulations of the transaction set than making the search of certain events slightly more expensive.</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-17T00:00:00+00:00 2026-02-11T14:48:25+00:00 Tim Pecherskyhttps://github.com/peersky https://wg-eips.ritovision.com/7746/

An interface for composable, runtime security checks in smart contracts.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a standard interface, <code>ILayer</code>, for implementing composable security layers in smart contracts. These layers act as middleware, enabling runtime validation of function calls before and after execution, independent of the protected contract's logic. This approach facilitates modular security, allowing independent providers to manage and upgrade security layers across multiple contracts.</p> <h2 id="motivation">Motivation</h2> <p>Current smart contract security practices often rely on monolithic validation logic within the contract itself. This can lead to tightly coupled code, making it difficult to isolate and address security concerns. Better structured architecture is needed, middleware like approach is widely used in the industry, allowing to wrap calls in other calls in generic and repeatable pattern with same call signatures.</p> <p>The Security Layers Standard introduces a modular approach, enabling:</p> <ul> <li><strong>Independent Security Providers:</strong> Specialized security providers can focus on developing and maintaining specific security checks.</li> <li><strong>Composable Security:</strong> Layers can be combined to create comprehensive security profiles tailored to individual contract needs.</li> <li><strong>Upgradability:</strong> Security layers can be updated without requiring changes to the protected contract.</li> <li><strong>Flexibility:</strong> Layers can perform a wide range of validation checks, including access control, input sanitization, output verification, and more.</li> </ul> <p>Having a generalized standard for such layers can help to build more secure and modular systems as well as enable security providers to build generic, service-oriented security oracle solutions.</p> <h2 id="specification">Specification</h2> <p>A contract implementing the <code>ILayer</code> interface MUST provide two functions:</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.20</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"> ILayer</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"> Validates a function call 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"> configuration</span><span class="z-comment"> Layer-specific configuration 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"> selector</span><span class="z-comment"> The function selector being called.</span></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 initiating the call.</span></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 amount of ETH sent with the call (if 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"> data</span><span class="z-comment"> The calldata for the function call.</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"> beforeCallResult</span><span class="z-comment"> Arbitrary data to be passed to `afterCallValidation`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST revert if validation fails.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> beforeCall</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"> configuration</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-variable"> selector</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</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 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">bytes</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"> Validates a function call after 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"> configuration</span><span class="z-comment"> Layer-specific configuration 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"> selector</span><span class="z-comment"> The function selector being called.</span></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 initiating the call.</span></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 amount of ETH sent with the call (if 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"> data</span><span class="z-comment"> The calldata for the function call.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> beforeCallResult</span><span class="z-comment"> The data returned by `beforeCallValidation`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST revert if validation fails.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> afterCall</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"> configuration</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-variable"> selector</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</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-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> beforeCallResult</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> <span class="giallo-l"></span></code></pre> <p>A protected contract MAY integrate security layers by calling the <code>beforeCallValidation</code> function before executing its logic and the <code>afterCallValidation</code> function afterwards. Multiple layers can be registered and executed in a defined order. The protected contract MUST revert if any layer reverts.</p> <h2 id="rationale">Rationale</h2> <p><strong>Flexibility</strong>: The <code>layerConfig</code> parameter allows for layer-specific customization, enabling a single layer implementation to serve multiple contracts with varying requirements.</p> <p><strong>non-static calls</strong>: Layers can maintain their own state, allowing for more complex validation logic (e.g., rate limiting, usage tracking).</p> <p><strong>Strict Validation</strong>: Reverts on validation failure ensure a fail-safe mechanism, preventing execution of potentially harmful transactions.</p> <p><strong>Gas Costs</strong>: Layers naturally will have gas costs associated with their execution. However, the benefits of enhanced security and modularity outweigh these costs, especially as blockchain technology continues to evolve and we expect gas costs to decrease over time.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A reference implementation of the <code>ILayer</code> interface and a sample protected contract can be found in the repository: In the <a href="https://wg-eips.ritovision.com/7746/./assets/ILayer.sol"><code>ILayer.sol</code></a> a reference interface is provided.</p> <p>In this test, a <a href="https://wg-eips.ritovision.com/7746/./assets/test/Protected.sol"><code>Protected.sol</code></a> contract is protected by a <a href="https://wg-eips.ritovision.com/7746/./assets/test/RateLimitLayer.sol"><code>RateLimitLayer.sol</code></a> layer. The <code>RateLimitLayer</code> implements the <code>ILayer</code> interface and enforces a rate which client has configured. The <code>Drainer</code> simulates a vulnerable contract that acts in a malicious way. In the <code>test.ts</code> The <code>Drainer</code> contract is trying to drain the funds from the <code>Protected</code> contract. It is assumed that <code>Protected</code> contract has bug that allows partial unauthorized access to the state. The <code>RateLimitLayer</code> is configured to allow only 10 transactions per block from same sender. The test checks that the <code>Drainer</code> contract is not able to drain the funds from the <code>Protected</code> contract.</p> <h2 id="security-considerations">Security Considerations</h2> <p><strong>Layer Trust</strong>: Thoroughly audit and vet any security layer before integrating it into your contract. Malicious layers can compromise contract security.</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-16T00:00:00+00:00 2026-02-11T14:48:25+00:00 Tim Pecherskyhttps://github.com/peerskyt@peersky.xyz https://wg-eips.ritovision.com/7744/

Global repository of bytecode, enabling developers, auditors, and researchers to find, analyze, and reuse bytecode efficiently.

<h2 id="abstract">Abstract</h2> <p>This EIP defines a standard interface for indexing smart contracts on Ethereum by their bytecode hash. This enables trustless discovery and verification of contract code, facilitating use cases like bytecode signing, whitelisting, and decentralized distribution mechanisms.</p> <h2 id="motivation">Motivation</h2> <p>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 codebases instead of redeploying them, optimizing resource usage. This can be useful for dApps that rely on extensive re-use of same codebase as own dependencies.</p> <h3 id="why-this-registry-needs-to-be-an-erc">Why this registry needs to be an ERC</h3> <p>The Code Index is essential for trustless and secure smart contract development. By standardizing the interface for indexing contracts by their bytecode, developers can easily integrate this feature into their smart contracts, enhancing the security and trustworthiness of the Ethereum ecosystem.</p> <p>Its simplicity and generic nature make it suitable for a wide range of applications. The ability to globally reference the same codebase makes it an ideal candidate for standardization.</p> <p>Ultimately, this feature should be incorporated into EIP standards, as it is a fundamental building block for trustless and secure smart contract development. This standard is a step towards this goal.</p> <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> <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.28</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IERC7744</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./IERC7744.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"> Byte Code Indexer Contract</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> You can use this contract to index contracts by their bytecode.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This allows to query contracts by their bytecode instead of addresses.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@author</span><span class="z-comment"> Tim Pechersky (@Peersky)</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"> ERC7744</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7744</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"> address</span><span>)</span><span class="z-storage z-type"> private</span><span> index</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"> isEIP7702</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">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes3</span><span> prefix</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"> extcodecopy</span><span>(</span><span>account</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span class="z-constant">0x40</span><span>)</span><span>,</span><span class="z-constant"> 3</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Copy first 3 bytes to memory</span></span> <span class="giallo-l"><span> prefix </span><span class="z-keyword">:=</span><span class="z-entity z-name"> mload</span><span>(</span><span class="z-constant">0x40</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Load the 3 bytes from memory</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> prefix </span><span class="z-keyword">==</span><span class="z-support"> bytes3</span><span>(</span><span class="z-constant">0xef0100</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"> isValidContainer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> container</span><span>)</span><span class="z-storage z-type"> private</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"> bytes</span><span class="z-storage z-type"> memory</span><span> code </span><span class="z-keyword">=</span><span> container</span><span>.</span><span>code</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> codeHash </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span>container</span><span>)</span><span>.</span><span>codehash</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>code</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span class="z-keyword"> &amp;&amp;</span><span> codeHash </span><span class="z-keyword">!=</span><span class="z-support"> bytes32</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-entity z-name">isEIP7702</span><span>(</span><span>container</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">@notice</span><span class="z-comment"> Registers a contract in the index by its bytecode hash</span></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"> The contract to register</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> `msg.codeHash` will be used</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 revert if the contract is already indexed or if returns EIP7702 delegated 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"> register</span><span>(</span><span class="z-support">address</span><span class="z-variable"> container</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> etalon </span><span class="z-keyword">=</span><span> index</span><span>[</span><span>container</span><span>.</span><span>codehash</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">isValidContainer</span><span>(</span><span>container</span><span>)</span><span>,</span><span class="z-string"> &quot;Invalid container&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>etalon </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-entity z-name">isValidContainer</span><span>(</span><span>etalon</span><span>)</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> alreadyExists</span><span>(</span><span>container</span><span>.</span><span>codehash</span><span>,</span><span> container</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> index</span><span>[</span><span>container</span><span>.</span><span>codehash</span><span>]</span><span class="z-keyword"> =</span><span> container</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Indexed</span><span>(</span><span>container</span><span>,</span><span> container</span><span>.</span><span>codehash</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"> Returns the contract address by its bytecode hash</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> returns zero if the contract is not indexed</span></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 bytecode hash</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"> 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"> get</span><span>(</span><span class="z-support">bytes32</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 class="z-keyword"> return</span><span> index</span><span>[</span><span>id</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="deployment-method">Deployment method</h3> <p>The <code>CodeIndex</code> contract is deployed at: <code>0xC0De1D1126b6D698a0073A4e66520111cEe22F62</code> using <code>CREATE2</code> via the deterministic deployer at <code>0x4e59b44847b379578588920ca78fbf26c0b4956c</code> with a salt of <code>0x9425035d50edcd7504fe5eeb5df841cc74fe6cccd82dca6ee75bcdf774bd88d9</code> is obtained by seeking a vanity address starting with meaningful name "Code ID (<code>c0de1d</code>) for a bytecode compiled with <code>solc 0.8.28</code> as <code>solc --input-file src/ERC7744.sol --bin --optimize --optimize-runs 2000 --metadata-hash none --via-ir --optimize-yul</code></p> <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>Reverting on re-indexing</strong>: There is small, yet non-zero probability of hash collision attack. Disallowing updates to indexed location of bytecode coupes with this.</p> <p><strong>Simple Interface</strong>: The interface is minimal and focused to maximize composability and ease of implementation.</p> <p><strong>Library Implementation</strong>: Implementing this as a library would limit its impact, making code reuse more difficult and lacking a single, official source of truth. By establishing this as an ERC, we ensure standardization and widespread adoption, driving the ecosystem forward.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Reference implementation of the Code Index can be found in the assets folder. There you can find the <a href="https://wg-eips.ritovision.com/7744/./assets/IERC7744.sol">interface</a> and the <a href="https://wg-eips.ritovision.com/7744/./assets/ERC7744.sol">implementation</a> of the Code Index.</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></strong>: The index does not index the EIP-7702 delegated accounts. During attempt to register, it checks if contract code begins with reserved delegation designator <code>0xef0100</code> and if so, it will revert.</p> <p><strong>Self-Destruct Contracts</strong>: In case of indexed contract storage becomes empty, contracts may be re-indexed, During register function call, if contract is already indexed, we run <code>isValidContainer</code> check on the indexed address. It it fails, re-indexing is allowed with a newly specified address.</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-13T00:00:00+00:00 2026-04-25T12:06:20+00:00 Cheng Qianhttps://github.com/jamesavechivesjames.walstonn@gmail.com https://wg-eips.ritovision.com/7743/

Non-fungible token that supports multiple owners, allowing shared ownership and transferability among users.

<h2 id="abstract">Abstract</h2> <p>This ERC proposes a new standard for non-fungible tokens (NFTs) that supports multiple owners. The MO-NFT standard allows a single NFT to have multiple owners, reflecting the shared and distributable nature of digital assets. This model incorporates mechanisms for provider-defined transfer fees and ownership archiving, enabling flexible and collaborative ownership structures. It maintains compatibility with the existing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard to ensure interoperability with current tools and platforms.</p> <h2 id="motivation">Motivation</h2> <p>Traditional NFTs enforce a single-ownership model, which does not align with the inherent duplicability and collaborative potential of digital assets. MO-NFTs allow for shared ownership, promoting wider distribution and collaboration while maintaining secure access control. The inclusion of provider fees and ownership archiving enhances the utility and flexibility of NFTs in representing digital assets and services.</p> <h2 id="specification">Specification</h2> <h3 id="token-creation-and-ownership-model">Token Creation and Ownership Model</h3> <ol> <li> <p><strong>Minting</strong>:</p> <ul> <li> <p>The function <code>mintToken()</code> allows the creation of a new MO-NFT. The caller becomes both the initial owner and the provider of the token.</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"> mintToken</span><span>(</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">uint256</span><span>)</span><span>;</span></span></code></pre></li> <li> <p>A new <code>tokenId</code> is generated, and the caller is added to the owners set and recorded as the provider. The <code>balanceOf</code> the caller is incremented.</p> </li> </ul> </li> <li> <p><strong>Ownership List</strong>:</p> <ul> <li>The MO-NFT maintains a list of owners for each token. Owners are stored in an enumerable set to prevent duplicates and allow efficient lookup.</li> </ul> </li> <li> <p><strong>Provider Role</strong>:</p> <ul> <li>The provider is the initial owner who can set and update the <code>transferValue</code> fee. Only the provider can modify certain token parameters.</li> </ul> </li> <li> <p><strong>Transfer Mechanism</strong>:</p> <ul> <li> <p>Owners can transfer the token to new owners using <code>transferFrom</code>. The transfer adds the new owner to the list without removing existing owners and transfers the <code>transferValue</code> fee to the provider.</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"> 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"> tokenId</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre></li> </ul> </li> </ol> <h3 id="transfer-of-ownership">Transfer of Ownership</h3> <ol> <li> <p><strong>Additive Ownership</strong>:</p> <ul> <li>Transferring ownership adds the new owner to the ownership list without removing current owners. This approach reflects the shared nature of digital assets.</li> </ul> </li> <li> <p><strong>Provider Fee Handling</strong>:</p> <ul> <li>During a transfer, the specified <code>transferValue</code> fee is transferred to the provider. The contract must have sufficient balance to cover this fee.</li> </ul> </li> <li> <p><strong>Archiving Ownership</strong>:</p> <ul> <li> <p>Owners can mark themselves as archived for a specific token, meaning they can no longer transfer that token. Once set, this status cannot be reversed. And for Digital Asset platform, this status means the owner can download the real digital asset directly; if it is not archived, then it must be changed to archived first, then owner can download the real digital asset.</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"> archive</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></code></pre></li> </ul> </li> </ol> <h3 id="interface-definitions">Interface Definitions</h3> <p><strong>Minting Functions</strong></p> <ul> <li> <p><code>function mintToken() public onlyOwner returns (uint256);</code></p> </li> <li> <p><code>function provide(string memory assetName, uint256 size, bytes32 fileHash, address provider, uint256 transferValue) external returns (uint256);</code></p> </li> </ul> <p><strong>Transfer Functions</strong></p> <ul> <li> <p><code>function transferFrom(address from, address to, uint256 tokenId) public;</code></p> </li> <li> <p><code>function safeTransferFrom(address from, address to, uint256 tokenId) public;</code> <em>(Disabled or overridden)</em></p> </li> <li> <p><code>function safeTransferFrom(address from, address to, uint256 tokenId, bytes memory data) public;</code> <em>(Disabled or overridden)</em></p> </li> </ul> <p><strong>Ownership Management Functions</strong></p> <ul> <li> <p><code>function isOwner(uint256 tokenId, address account) public view returns (bool);</code></p> </li> <li> <p><code>function getOwnersCount(uint256 tokenId) public view returns (uint256);</code></p> </li> <li> <p><code>function balanceOf(address owner) external view returns (uint256 balance);</code></p> </li> <li> <p><code>function ownerOf(uint256 tokenId) external view returns (address owner);</code></p> </li> </ul> <p><strong>Provider Functions</strong></p> <ul> <li><code>function setTransferValue(uint256 tokenId, uint256 newTransferValue) external;</code></li> </ul> <p><strong>Archived Status Function</strong></p> <ul> <li><code>function archive(uint256 tokenId) external;</code></li> </ul> <h3 id="events">Events</h3> <ul> <li> <p><code>event TokenMinted(uint256 indexed tokenId, address indexed owner);</code></p> </li> <li> <p><code>event TokenTransferred(uint256 indexed tokenId, address indexed from, address indexed to);</code></p> </li> <li> <p><code>event TransferValueUpdated(uint256 indexed tokenId, uint256 oldTransferValue, uint256 newTransferValue);</code></p> </li> <li> <p><code>event ArchivedStatusUpdated(uint256 indexed tokenId, address indexed owner, bool archived);</code></p> </li> </ul> <h3 id="erc-721-compliance"><a href="https://wg-eips.ritovision.com/721/">ERC-721</a> Compliance</h3> <p>The MO-NFT standard is designed to be compatible with the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard. It implements required functions such as <code>balanceOf</code>, <code>ownerOf</code>, and <code>transferFrom</code> from the <code>ERC721</code> interface.</p> <ul> <li> <p><strong>Approval Functions</strong>: Functions like <code>approve</code>, <code>getApproved</code>, <code>setApprovalForAll</code>, and <code>isApprovedForAll</code> are intentionally disabled or overridden, as they do not align with the MO-NFT multi-owner model.</p> </li> <li> <p><strong>Safe Transfer Functions</strong>: The <code>safeTransferFrom</code> functions are restricted because traditional ERC-721 transfer safety checks are not applicable when ownership is additive rather than exclusive.</p> </li> <li> <p><strong>Supports Interface</strong>: The <code>supportsInterface</code> function ensures that the MO-NFT declares compatibility with the ERC-721 standard, allowing it to be integrated with existing tools and platforms.</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-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> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC721</span><span>)</span><span>.</span><span>interfaceId </span><span class="z-keyword">||</span><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> <span class="giallo-l"><span>}</span></span></code></pre></li> </ul> <h2 id="rationale">Rationale</h2> <ol> <li> <p><strong>Multi-Ownership Model</strong>:</p> <ul> <li>Digital assets are inherently duplicable and can be shared without loss of quality. The multi-owner model allows broader distribution and collaboration while maintaining a unique token identity.</li> </ul> </li> <li> <p><strong>Additive Ownership</strong>:</p> <ul> <li>By adding new owners without removing existing ones, we support shared ownership models common in collaborative environments and digital content distribution.</li> </ul> </li> <li> <p><strong>Provider Fee Mechanism</strong>:</p> <ul> <li>Incorporating a provider fee incentivizes creators and providers by rewarding them whenever the asset is transferred. This aligns with models where creators receive royalties or fees for their work.</li> </ul> </li> <li> <p><strong>Ownership Archiving</strong>:</p> <ul> <li>Allowing owners to archive themselves from the ownership list provides flexibility, enabling owners to relinquish rights or prevent further transfers of the asset. This replaces the previous concept of "burning" ownership.</li> </ul> </li> <li> <p><strong>ERC-721 Compatibility</strong>:</p> <ul> <li>Maintaining compatibility with ERC-721 allows MO-NFTs to leverage existing infrastructure, tools, and platforms, facilitating adoption and interoperability.</li> </ul> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>While the MO-NFT standard aims to maintain compatibility with ERC-721, certain deviations are necessary due to the multi-owner model:</p> <ul> <li><strong>Disabling Approvals Functions</strong>: Traditional ERC-721 approvals assume that a single owner has the right to grant or revoke approvals. In MO-NFT, a token can have multiple owners. Without a protocol-defined mechanism for “co-ownership consensus,” an approval system would open the door to an unintentional or unwanted transfer if only one co-owner granted approval. We felt this approach could undermine the shared-ownership model, so the reference implementation chooses to revert calls to approval-related functions.</li> </ul> <p>This may limit compatibility with existing NFT platforms and marketplaces that rely on approve or setApprovalForAll. In principle, developers could extend the MO-NFT standard with more advanced “multi-signature” or “consensus-based” approvals, but that is beyond the scope of this initial EIP. Our goal is to keep the core standard minimal and avoid confusion for marketplaces that were built with single-owner assumptions.</p> <ul> <li><strong>Safe Transfer Functions</strong>: The “safe” variants of ERC-721 transfers (safeTransferFrom) serve to protect tokens from being accidentally sent to non-compliant contracts. Because MO-NFT’s multi-owner approach does not inherently break the logic of “checking whether the recipient can handle ERC-721 tokens.</li> </ul> <p>Implementing “safe” in the same manner as ERC-721: after a new owner is added, check <code>onERC721Received</code> on the recipient contract.</p> <ul> <li><strong><code>ownerOf</code> Function</strong>: Returns the first owner in the owners list for compatibility, but the concept of a single owner does not fully apply.</li> </ul> <p>Developers should be aware of these differences when integrating MO-NFTs into systems designed for standard ERC-721 tokens.</p> <h2 id="test-cases">Test Cases</h2> <ol> <li> <p><strong>Minting an MO-NFT and Verifying Initial Ownership</strong>:</p> <ul> <li> <p><strong>Input</strong>:</p> <ul> <li>Call <code>mintToken()</code> as the provider.</li> </ul> </li> <li> <p><strong>Expected Output</strong>:</p> <ul> <li> <p>A new <code>tokenId</code> is generated.</p> </li> <li> <p>The caller is added as the first owner.</p> </li> <li> <p>The <code>balanceOf</code> the caller increases by 1.</p> </li> <li> <p>The provider is recorded for the token.</p> </li> <li> <p><code>TokenMinted</code> event is emitted.</p> </li> </ul> </li> </ul> </li> <li> <p><strong>Transferring an MO-NFT and Verifying Provider Fee Transfer</strong>:</p> <ul> <li> <p><strong>Input</strong>:</p> <ul> <li>Call <code>transferFrom(from, to, tokenId)</code> where <code>from</code> is an existing owner and <code>to</code> is a new address.</li> </ul> </li> <li> <p><strong>Expected Output</strong>:</p> <ul> <li> <p>The <code>to</code> address is added to the owners list.</p> </li> <li> <p>The <code>transferValue</code> fee is transferred to the provider.</p> </li> <li> <p>The <code>balanceOf</code> of the <code>to</code> address increases by 1.</p> </li> <li> <p><code>TokenTransferred</code> event is emitted.</p> </li> </ul> </li> </ul> </li> <li> <p><strong>Archiving Ownership</strong>:</p> <ul> <li> <p><strong>Input</strong>:</p> <ul> <li>An owner calls <code>archive(tokenId)</code>.</li> </ul> </li> <li> <p><strong>Expected Output</strong>:</p> <ul> <li>The owner’s transfer ability for that token is archived.</li> <li>The owner can no longer transfer that token.</li> <li><code>ArchivedStatusUpdated</code> event is emitted.</li> </ul> </li> </ul> </li> <li> <p><strong>Setting Transfer Value</strong>:</p> <ul> <li> <p><strong>Input</strong>:</p> <ul> <li>The provider calls <code>setTransferValue(tokenId, newTransferValue)</code>.</li> </ul> </li> <li> <p><strong>Expected Output</strong>:</p> <ul> <li> <p>The <code>transferValue</code> is updated in the contract.</p> </li> <li> <p><code>TransferValueUpdated</code> event is emitted.</p> </li> </ul> </li> </ul> </li> <li> <p><strong>Failing Transfer to Existing Owner</strong>:</p> <ul> <li> <p><strong>Input</strong>:</p> <ul> <li>Attempt to <code>transferFrom</code> to an address that is already an owner.</li> </ul> </li> <li> <p><strong>Expected Output</strong>:</p> <ul> <li> <p>The transaction reverts with the error <code>"MO-NFT: Recipient is already an owner"</code>.</p> </li> <li> <p>No changes to ownership or balances occur.</p> </li> </ul> </li> </ul> </li> </ol> <h2 id="reference-implementation">Reference Implementation</h2> <p>The full reference implementation code for the MO-NFT standard is included in the EIPs repository under assets folder. This ensures the code is preserved alongside the EIP and remains accessible.</p> <ul> <li> <p><strong>Contracts</strong>:</p> <ul> <li> <p><a href="https://wg-eips.ritovision.com/7743/./assets/MONFT.sol"><code>MONFT.sol</code></a>: The base implementation of the MO-NFT standard.</p> </li> <li> <p><a href="https://wg-eips.ritovision.com/7743/./assets/DigitalAsset.sol"><code>DigitalAsset.sol</code></a>: An extended implementation for digital assets with provider fees.</p> </li> </ul> </li> <li> <p><strong>Interfaces</strong>:</p> <ul> <li><a href="https://wg-eips.ritovision.com/7743/./assets/IDigitalAsset.sol"><code>IDigitalAsset.sol</code></a>: Interface defining the functions for digital asset management.</li> </ul> </li> </ul> <h3 id="key-functions-in-reference-implementation">Key Functions in Reference Implementation</h3> <p><strong>Minting Tokens</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"> mintToken</span><span>(</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">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> _nextTokenId</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"> Add the sender to the set of owners for the new token</span></span> <span class="giallo-l"><span> _owners</span><span>[</span><span>_nextTokenId</span><span>]</span><span>.</span><span class="z-entity z-name">add</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Increment the balance of the owner</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 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 provider to the caller</span></span> <span class="giallo-l"><span> _providers</span><span>[</span><span>_nextTokenId</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-language"> msg.sender</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"> TokenMinted</span><span>(</span><span>_nextTokenId</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> _nextTokenId</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>Transferring Tokens</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"> 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"> tokenId</span><span>)</span><span class="z-storage z-type"> public</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">isOwner</span><span>(</span><span>tokenId</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span>,</span><span class="z-string"> &quot;MO-NFT: Caller is not an owner&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>to </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;MO-NFT: Transfer to zero address&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 class="z-entity z-name">isOwner</span><span>(</span><span>tokenId</span><span>,</span><span> to</span><span>)</span><span>,</span><span class="z-string"> &quot;MO-NFT: Recipient is already an owner&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"> Add the new owner to the set</span></span> <span class="giallo-l"><span> _owners</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span class="z-entity z-name">add</span><span>(</span><span>to</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _balances</span><span>[</span><span>to</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 class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Transfer the transferValue to the provider</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> transferValue </span><span class="z-keyword">=</span><span> _transferValues</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> provider </span><span class="z-keyword">=</span><span> _providers</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>.</span><span>balance </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> transferValue</span><span>,</span><span class="z-string"> &quot;Insufficient contract balance&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></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> provider</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span> transferValue</span><span>}</span><span>(</span><span class="z-string">&quot;&quot;</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"> &quot;Transfer to provider failed&quot;</span><span>)</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"> TokenTransferred</span><span>(</span><span>tokenId</span><span>,</span><span> from</span><span>,</span><span> to</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>Archiving Ownership</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"> archive</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 class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> isOwner</span><span>(</span><span>tokenId</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;MO-NFT: Caller is not the owner of this token&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Once archived, the status cannot be reversed</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> _archivedStatus</span><span>[</span><span>tokenId</span><span>]</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;MO-NFT: Token can only be archived once for an owner&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> _archivedStatus</span><span>[</span><span>tokenId</span><span>]</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ArchivedStatusUpdated</span><span>(</span><span>tokenId</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span> archived</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <ol> <li> <p><strong>Reentrancy Attacks</strong>:</p> <ul> <li> <p><strong>Mitigation</strong>: Use the Checks-Effects-Interactions pattern when transferring Ether (e.g., transferring <code>transferValue</code> to the provider).</p> </li> <li> <p><strong>Recommendation</strong>: Consider using <code>ReentrancyGuard</code> from OpenZeppelin to prevent reentrant calls.</p> </li> </ul> </li> <li> <p><strong>Integer Overflow and Underflow</strong>:</p> <ul> <li><strong>Mitigation</strong>: Solidity 0.8.x automatically checks for overflows and underflows, throwing exceptions when they occur.</li> </ul> </li> <li> <p><strong>Access Control</strong>:</p> <ul> <li> <p><strong>Ensured By</strong>:</p> <ul> <li> <p>Only owners can call transfer functions.</p> </li> <li> <p>Only providers can set the <code>transferValue</code>.</p> </li> <li> <p>Use of <code>require</code> statements to enforce access control.</p> </li> </ul> </li> </ul> </li> <li> <p><strong>Denial of Service (DoS)</strong>:</p> <ul> <li> <p><strong>Consideration</strong>: Functions that iterate over owners could be expensive in terms of gas if the owners list is large.</p> </li> <li> <p><strong>Mitigation</strong>: Avoid such functions or limit the number of owners.</p> </li> </ul> </li> <li> <p><strong>Data Integrity</strong>:</p> <ul> <li><strong>Ensured By</strong>: Proper use of Solidity's data types and structures, and by emitting events for all state-changing operations for off-chain verification.</li> </ul> </li> <li> <p><strong>Ether Handling</strong>:</p> <ul> <li> <p><strong>Consideration</strong>: Ensure the contract can receive Ether to handle provider payments.</p> </li> <li> <p><strong>Mitigation</strong>: Implement a <code>receive()</code> function to accept Ether.</p> </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> 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-07-04T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ernesto Garcíahttps://github.com/ernestognw Kalman Lajkohttps://github.com/LajkoKalman Valera Grinenkohttps://github.com/0xValera https://wg-eips.ritovision.com/7985/

Gateway attributes for cancellation, timeout, retry, dependencies, and delivery control in cross-chain messaging.

<h2 id="abstract">Abstract</h2> <p>This ERC defines standard attributes for <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> cross-chain messaging gateways to enable consistent cancellation, timeout, retry, dependency, and delivery control mechanisms across implementations. These attributes provide applications with predictable control over message lifecycle, ordering, and delivery requirements.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> introduces an extensible attribute system for cross-chain messaging, but leaves attribute standardization to follow-up specifications. As cross-chain applications mature, consistent patterns for message control have emerged as essential requirements:</p> <ol> <li><strong>Cancellation</strong>: Applications need to cancel pending messages due to changed conditions</li> <li><strong>Timeouts</strong>: Automatic cancellation prevents indefinite pending states</li> <li><strong>Retry Logic</strong>: Standardized failure handling improves reliability</li> <li><strong>Revert Behavior</strong>: Consistent error semantics across gateways</li> <li><strong>Message Dependencies</strong>: Ensuring correct ordering when messages must deliver in sequence</li> <li><strong>Gas Requirements</strong>: Preventing delivery failures due to insufficient gas</li> <li><strong>Delivery Timing</strong>: Controlling when messages can be delivered for scheduling and coordination</li> </ol> <p>Without standardized attributes, each gateway implements these features differently, fragmenting the ecosystem and requiring application-specific integration logic.</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="standard-attributes">Standard Attributes</h3> <p>This specification defines standard attributes for <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> cross-chain messaging gateways. The word "delivery" (or "deliver") is used to refer to the process of delivering a message to the destination chain, similar to its usage in <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a>.</p> <p>Gateways MAY implement attributes independently. Gateways MUST validate the attribute's encoding for each attribute they implement and revert the transaction if the encoding is invalid.</p> <h4 id="cancellable-bool"><code>cancellable(bool)</code></h4> <p>Indicates whether a message can be cancelled after submission. This attribute uses selector <code>0xde986d7f</code>, which represents the first 4 bytes of <code>keccak256("cancellable(bool)")</code>.</p> <p>The attribute value is encoded as an ABI-encoded boolean, and MAY default to <code>false</code> when not specified. When set to <code>true</code>, gateways MUST provide a cancellation mechanism to allow applications to cancel pending messages due to changed conditions or requirements.</p> <h4 id="deliverbefore-uint256"><code>deliverBefore(uint256)</code></h4> <p>Specifies a timestamp after which the message cannot be delivered. This attribute uses selector <code>0x3e97d7ee</code>, derived from the first 4 bytes of <code>keccak256("deliverBefore(uint256)")</code>.</p> <p>The value is encoded as an ABI-encoded Unix timestamp, and MAY default to <code>0</code> when not specified. Gateways MUST NOT deliver messages after the expiration timestamp unless <code>0</code> is specified, which MUST be interpreted as no expiration.</p> <h4 id="deliverafter-uint256"><code>deliverAfter(uint256)</code></h4> <p>Specifies the earliest timestamp at which the message can be delivered. This attribute uses selector <code>0x745910eb</code>, derived from the first 4 bytes of <code>keccak256("deliverAfter(uint256)")</code>.</p> <p>The value is encoded as an ABI-encoded Unix timestamp, and MAY default to <code>0</code> when not specified. Gateways MUST NOT deliver messages before the delivery timestamp unless <code>0</code> is specified, which MUST be interpreted as no delay. When combined with <code>deliverBefore(uint256)</code>, this creates a delivery time window.</p> <h4 id="retrypolicy-bytes"><code>retryPolicy(bytes)</code></h4> <p>Defines retry behavior for failed message delivery. Using selector <code>0xf002c055</code> from the first 4 bytes of <code>keccak256("retryPolicy(bytes)")</code>, this attribute encodes retry parameters as ABI-encoded bytes.</p> <p>The format follows <code>abi.encodePacked(uint16(maxRetries), uint32(retryDelay), uint32(backoffMultiplier))</code>, where <code>maxRetries</code> specifies the maximum number of retry attempts (with 0 indicating no retries), <code>retryDelay</code> defines the initial delay between retries in seconds, and <code>backoffMultiplier</code> provides the multiplier for exponential backoff in basis points (with 10000 representing 1x multiplier).</p> <p>The attribute value MAY default to <code>0x</code> when not specified, equivalent to infinite retries, no delay, and no backoff (or <code>maxRetries = 0</code>, <code>retryDelay = 0</code>, and <code>backoffMultiplier = 0</code>).</p> <h4 id="revertbehavior-uint8"><code>revertBehavior(uint8)</code></h4> <p>Specifies how delivery failures MUST be handled. This attribute uses selector <code>0x9e521a77</code>, representing the first 4 bytes of <code>keccak256("revertBehavior(uint8)")</code>.</p> <p>The value is encoded as an ABI-encoded uint8 with the following possible values:</p> <p><strong><code>0</code> – Revert on Failure</strong></p> <ul> <li>Gateways MUST revert the entire message delivery when any failure occurs.</li> <li>Gateways SHOULD propagate the original failure reason when reverting.</li> </ul> <p><strong><code>1</code> – Emit-and-Continue</strong></p> <ul> <li>Gateways MUST emit a <code>MessageFailed(bytes32 sendId, string reason)</code> event upon failure.</li> <li>Gateways MUST continue delivery of subsequent messages or operations.</li> </ul> <p><strong><code>2</code> – Silent Failure</strong></p> <ul> <li>Gateways MUST NOT revert the transaction</li> <li>Gateways MUST NOT emit any failure-related events.</li> </ul> <p>When not specified, the attribute MUST default to <code>0</code>.</p> <h4 id="dependson-bytes32"><code>dependsOn(bytes32[])</code></h4> <p>Specifies message dependencies that must be delivered before this message. This attribute uses selector <code>0xa9fed7b9</code>, derived from the first 4 bytes of <code>keccak256("dependsOn(bytes32[])")</code>.</p> <p>The value is encoded as an ABI-encoded array of message identifiers. Gateways MUST NOT deliver a message until all messages specified in the <code>dependsOn</code> array have been successfully delivered. When not specified or empty, the message has no dependencies. This ensures correct ordering and prevents out-of-order delivery issues.</p> <h4 id="mingaslimit-uint256"><code>minGasLimit(uint256)</code></h4> <p>Specifies the minimum gas limit required for message delivery. This attribute uses selector <code>0x39f87ba1</code>, derived from the first 4 bytes of <code>keccak256("minGasLimit(uint256)")</code>.</p> <p>The value is encoded as an ABI-encoded uint256 representing the minimum gas units required. Gateways MUST ensure at least this amount of gas is available before attempting message delivery. When not specified, gateways MAY use their default gas allocation strategies.</p> <h2 id="rationale">Rationale</h2> <p>These attributes address the most common cross-chain message control requirements:</p> <ul> <li><strong>Lifecycle control</strong> via cancellation and timeout mechanisms</li> <li><strong>Delivery timing</strong> through delivery time windows</li> <li><strong>Failure handling</strong> via retry policies and revert behavior</li> <li><strong>Message ordering</strong> through dependency chains</li> <li><strong>Delivery guarantees</strong> via minimum gas requirements</li> </ul> <p>The byte-encoded retry policy allows for extensible parameters without requiring additional attributes. The dependency mechanism enables complex multi-message workflows while maintaining simplicity for single-message scenarios.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This specification extends <a href="https://wg-eips.ritovision.com/7786/">ERC-7786</a> without breaking changes. Gateways not supporting these attributes will operate normally per the base specification's requirement to handle unknown attributes gracefully.</p> <h2 id="security-considerations">Security Considerations</h2> <!-- TODO: Discuss --> <!-- Maybe? --> <!-- - **Dependency Cycles**: Gateways should detect and reject circular dependencies in `dependsOn` arrays --> <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-01T00:00:00+00:00 2026-02-11T14:48:26+00:00 Victor Zhanghttps://github.com/zhangzhongnan928 James Brownhttps://github.com/JamesSmartCell https://wg-eips.ritovision.com/7738/

Permissionless registry to fetch executable scripts for contracts

<h2 id="abstract">Abstract</h2> <p>This EIP provides a means to create a standard registry for locating executable scripts associated with the token.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/5169/">ERC-5169</a> provides a client script lookup method for contracts. This requires the contract to have implemented the <a href="https://wg-eips.ritovision.com/5169/">ERC-5169</a> interface at the time of construction (or allow an upgrade path).</p> <p>This proposal outlines a contract that can supply prototype and certified scripts. The contract would be a multichain singleton instance that would be deployed at identical addresses on supported chains.</p> <h3 id="overview">Overview</h3> <p>The registry contract will supply a set of URI links for a given contract address. These URI links point to script programs that can be fetched by a wallet, viewer or mini-dapp.</p> <p>The pointers can be set permissionlessly using a setter in the registry contract.</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>The contract MUST implement the <code>IERC7738</code> interface. The contract MUST emit the <code>ScriptUpdate</code> event when the script is updated. The contract SHOULD order the <code>scriptURI</code> returned so that the <a href="https://wg-eips.ritovision.com/173/">ERC-173</a> <code>owner()</code> of the contract's script entries are returned first (in the case of simple implementations the wallet will pick the first <code>scriptURI</code> returned). The contract SHOULD provide a means to page through entries if there are a large number of scriptURI entries.</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"> IERC7738</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 event emits when the scriptURI is updated, </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> so wallets implementing this interface can update a cached script</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ScriptUpdate</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 class="z-support">string</span><span>[</span><span>]</span><span class="z-variable"> newScriptURI</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 scriptURI for 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"> The</span><span class="z-comment"> scriptURI</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> scriptURI</span><span>(</span><span class="z-support">address</span><span class="z-variable"> contractAddress</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"> Update the scriptURI </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> emits event ScriptUpdate(address indexed contractAddress, scriptURI memory newScriptURI);</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setScriptURI</span><span>(</span><span class="z-support">address</span><span class="z-variable"> contractAddress</span><span>,</span><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> scriptURIList</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 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> <p>This method allows contracts written without the <a href="https://wg-eips.ritovision.com/5169/">ERC-5169</a> interface to associate scripts with themselves, and avoids the need for a centralised online server, with subsequent need for security and the requires an organisation to become a gatekeeper for the database.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases are included in <a href="https://wg-eips.ritovision.com/7738/./assets/test/NFTRegistryTest.test.ts">NFTRegistryTest.test.ts</a>. Contracts, deployment scripts and registry script can be found alongside the test script.</p> <p>Clone the repo and run:</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-7738</span></span> <span class="giallo-l"><span class="z-entity z-name">npm</span><span class="z-string"> install</span><span class="z-constant"> -</span><span class="z-constant">-save-dev</span><span class="z-string"> hardhat</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><h2 id="reference-implementation">Reference Implementation</h2> <p>The live implementation of the script registry is at <code>0x0077380bCDb2717C9640e892B9d5Ee02Bb5e0682</code> on several mainnet, L2 and testnet chains. To deploy scripts for use you can directly call the <code>setScriptURI</code> 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"> setScriptURI</span><span>(</span><span class="z-support">address</span><span class="z-variable"> contractAddress</span><span>,</span><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> newScriptURIs</span><span>)</span></span></code></pre> <p>or use the bundled ethers script, ensuring to fill in the target contract address and scriptURI:</p> <p><a href="https://wg-eips.ritovision.com/7738/./assets/scripts/createRegistryEntry.ts">Create Registry Entry</a></p> <h3 id="simplified-implementation">Simplified Implementation</h3> <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/access/Ownable.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"> DecentralisedRegistry</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7738</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> ScriptEntry</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"> string</span><span>[</span><span>]</span><span>)</span><span> scriptURIs</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span> addrList</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"> mapping</span><span>(</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span> ScriptEntry</span><span>)</span><span class="z-storage z-type"> private</span><span> _scriptURIs</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"> setScriptURI</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> contractAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> scriptURIList</span></span> <span class="giallo-l"><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>scriptURIList</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;&gt; 0 entries required in scriptURIList&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isOwnerOrExistingEntry </span><span class="z-keyword">=</span><span class="z-entity z-name"> Ownable</span><span>(</span><span>contractAddress</span><span>)</span><span>.</span><span class="z-entity z-name">owner</span><span>(</span><span>)</span><span class="z-keyword"> ==</span><span class="z-variable z-language"> msg.sender</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> ||</span><span> _scriptURIs</span><span>[</span><span>contractAddress</span><span>]</span><span>.</span><span>scriptURIs</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span> _scriptURIs</span><span>[</span><span>contractAddress</span><span>]</span><span>.</span><span>scriptURIs</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> =</span><span> scriptURIList</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>isOwnerOrExistingEntry</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> _scriptURIs</span><span>[</span><span>contractAddress</span><span>]</span><span>.</span><span>addrList</span><span>.</span><span class="z-entity z-name">push</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></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ScriptUpdate</span><span>(</span><span>contractAddress</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span> scriptURIList</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"> Return the list of scriptURI for this contract.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Order the return list so `Owner()` assigned scripts are first in the list</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> scriptURI</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> contractAddress</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">string</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-comment"> //</span><span class="z-comment">build scriptURI return list, owner first</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> contractOwner </span><span class="z-keyword">=</span><span class="z-entity z-name"> Ownable</span><span>(</span><span>contractAddress</span><span>)</span><span>.</span><span class="z-entity z-name">owner</span><span>(</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> addrList </span><span class="z-keyword">=</span><span> _scriptURIs</span><span>[</span><span>contractAddress</span><span>]</span><span>.</span><span>addrList</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">now calculate list length</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> listLen </span><span class="z-keyword">=</span><span> _scriptURIs</span><span>[</span><span>contractAddress</span><span>]</span><span>.</span><span>scriptURIs</span><span>[</span><span>contractOwner</span><span>]</span><span>.</span><span>length</span><span>;</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> addrList</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> listLen </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span> _scriptURIs</span><span>[</span><span>contractAddress</span><span>]</span><span>.</span><span>scriptURIs</span><span>[</span><span>addrList</span><span>[</span><span>i</span><span>]</span><span>]</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-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> ownerScripts </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> string</span><span>[](</span><span class="z-variable">listLen</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Add owner scripts</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> scriptIndex </span><span class="z-keyword">=</span><span class="z-entity z-name"> _addScriptURIs</span><span>(</span><span>contractOwner</span><span>,</span><span> contractAddress</span><span>,</span><span> ownerScripts</span><span>,</span><span class="z-constant"> 0</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Add remainder scripts</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> addrList</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> scriptIndex </span><span class="z-keyword">=</span><span class="z-entity z-name"> _addScriptURIs</span><span>(</span><span>addrList</span><span>[</span><span>i</span><span>]</span><span>,</span><span> contractAddress</span><span>,</span><span> ownerScripts</span><span>,</span><span> scriptIndex</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-keyword"> return</span><span> ownerScripts</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"> _addScriptURIs</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> user</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> contractAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> ownerScripts</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> scriptIndex</span></span> <span class="giallo-l"><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">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</span><span> j </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> j </span><span class="z-keyword">&lt;</span><span> _scriptURIs</span><span>[</span><span>contractAddress</span><span>]</span><span>.</span><span>scriptURIs</span><span>[</span><span>user</span><span>]</span><span>.</span><span>length</span><span>;</span><span> j</span><span class="z-keyword">+</span><span class="z-keyword">+</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> thisScriptURI </span><span class="z-keyword">=</span><span> _scriptURIs</span><span>[</span><span>contractAddress</span><span>]</span><span>.</span><span>scriptURIs</span><span>[</span><span>user</span><span>]</span><span>[</span><span>j</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-support">bytes</span><span>(</span><span>thisScriptURI</span><span>)</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> ownerScripts</span><span>[</span><span>scriptIndex</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>]</span><span class="z-keyword"> =</span><span> thisScriptURI</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> scriptIndex</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 scripts provided could be authenticated in various ways:</p> <ol> <li>The target contract which the setter specifies implements the <a href="https://wg-eips.ritovision.com/173/">ERC-173</a> <code>Ownable</code> interface. Once the script is fetched, the signature can be verified to match the Owner(). In the case of TokenScript this can be checked by a dapp or wallet using the TokenScript SDK, the TokenScript online verification service, or by extracting the signature from the XML, taking a keccak256 of the script and ecrecover the signing key address.</li> <li>If the contract does not implement Ownable, further steps can be taken: a. The hosting app/wallet can acertain the deployment key using 3rd party API or block explorer. The implementing wallet, dapp or viewer would then check the signature matches this deployment key. b. Signing keys could be pre-authenticated by a hosting app, using an embedded keychain. c. A governance token could allow a script council to authenticate requests to set and validate keys.</li> </ol> <p>If these criteria are not met:</p> <ul> <li>For mainnet implementations the implementing wallet should be cautious about using the script - it would be at the app and/or user's discretion.</li> <li>For testnets, it is acceptable to allow the script to function, at the discretion of the wallet provider.</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> 2024-06-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 Francesco D'Amatofrancesco.damato@ethereum.org Barnabé Monnotbarnabe.monnot@ethereum.org Michael Neudermichael.neuder@ethereum.org Potuzhttps://github.com/potuz Justin Tragliajtraglia@ethereum.org Terence Tsaottsao@offchainlabs.com https://wg-eips.ritovision.com/7732/

Separates the ethereum block in consensus and execution parts, adds a mechanism for the consensus proposer to choose the execution proposer.

<h2 id="abstract">Abstract</h2> <p>This EIP fundamentally changes the way an Ethereum block is validated by decoupling the execution validation from the consensus validation both logically as well as temporally. It does so by introducing a new in-protocol entity called <em>builders</em> and adding a new duty (submitting <em>payload timeliness attestations</em>) to Ethereum validators. The <code>ExecutionPayload</code> field of the <code>BeaconBlockBody</code> is removed and instead it is replaced by a signed commitment (a <code>SignedExecutionPayloadBid</code> object) from a builder to later reveal the corresponding execution payload. This commitment specifies in particular the blockhash of the execution block and a <em>value</em> to be paid to the beacon block proposer. When processing the <code>BeaconBlock</code>, the committed value is deducted from the builder's beacon chain balance and later a withdrawal is placed to an address, of the proposer's choosing, in the execution layer. A subset of validators in the beacon committee is assigned to the <em>Payload Timeliness Committee</em> (PTC), these validators are tasked to attest (by broadcasting a <code>PayloadAttestationMessage</code>) to whether the corresponding builder has revealed the committed execution payload (with the right blockhash) in a timely fashion and whether the correspoding blob data was available according to their view. PTC members are not required to validate the execution payload, execution validation is thus deferred until the next beacon block validation. While builder's are staked entities, their stake is not actively validating the beacon chain, they are not subject to the usual deposit and exit churn/queues and can be staked for as little as 1ETH. While the in-protocol payment via withdrawals is trustlessly deducted from this stake, the protocol also accomodates for trusted payments in the form of <em>promises</em> to be fulfiled elsewhere.</p> <h2 id="motivation">Motivation</h2> <p>This EIP solves a different set of unrelated important problems.</p> <ul> <li>An overwhelming majority of beacon block proposers outsource the construction of the execution payload within their blocks to a third party (henceforth called a <em>builder</em>). In order to do so, they request the hash tree root (HTR) of a promised execution payload and submit a <code>SignedBlindedBeaconBlock</code> to a trusted party that is tasked with replacing the HTR with the full execution payload (received from the builder) before broadcasting. This EIP allows for a trust-free fair exchange between the beacon block proposer and the builder, guaranteeing that an honest beacon block proposer will receive payment from the builder regardless of the latter's actions and that the honest builder's payload will be the canonical head of the chain regardless of the proposer's action.</li> <li>Currently, validators have the time between receiving the full beacon block (including an execution payload) and the attesting deadline (4 seconds in Ethereum mainnet) to perform both consensus and execution state transition functions, check blob data availability and evaluate the new head of the blockchain. The remainder of the slot time is spent doing less CPU-intense and critical task. By separating the validation of the execution and consensus part of the block, validators are only tasked to perform the consensus state transition function in this critical time before attesting, while execution and data availability validation is deferred for most of the remainder of the slot (between the builder's reveal time and the next attestation deadline).</li> <li>By removing the full execution payload size from the consensus block, it allows for faster network propagation on the critical path.</li> <li>It removes the increased reorg likeliness of including blob transactions in blocks given the natural increase in timelines for data availability checks and the fact that the builder may broadcast the blob sidecars even before attestations for the beacon block have been released.</li> <li>It prevents validators from missing attestations and strengthens the weight properties of fork choice in the event that builders produce invalid payloads.</li> <li>It removes the need to use trusted middleware in order to delegate block construction to a builder.</li> </ul> <h2 id="specification">Specification</h2> <h3 id="execution-layer">Execution Layer</h3> <p>No changes are required.</p> <h3 id="consensus-layer">Consensus Layer</h3> <p>The full consensus changes can be found in the consensus-specs Github repository. They are split between:</p> <ul> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/c94138e73e0e70eb4b27f9be4d4e9325fa1aebf7/specs/gloas/beacon-chain.md">Beacon Chain</a> changes.</li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/c94138e73e0e70eb4b27f9be4d4e9325fa1aebf7/specs/gloas/fork-choice.md">Fork choice</a> changes.</li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/c94138e73e0e70eb4b27f9be4d4e9325fa1aebf7/specs/gloas/p2p-interface.md">P2P</a> changes.</li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/c94138e73e0e70eb4b27f9be4d4e9325fa1aebf7/specs/gloas/validator.md">Honest validator guide</a> changes.</li> <li>A new <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/c94138e73e0e70eb4b27f9be4d4e9325fa1aebf7/specs/gloas/builder.md">honest builder</a> guide.</li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/c94138e73e0e70eb4b27f9be4d4e9325fa1aebf7/specs/gloas/fork.md">Fork logic</a> changes.</li> </ul> <p>A summary of the main changes is included below, the <a href="https://wg-eips.ritovision.com/7732/#rationale">Rationale</a> section contains explanation for most of the design decisions around these changes.</p> <h4 id="beacon-chain-changes">Beacon chain changes</h4> <h5 id="types">Types</h5> <table><thead><tr><th>Name</th><th>SSZ equivalent</th><th>Description</th></tr></thead><tbody> <tr><td><code>BuilderIndex</code></td><td><code>uint64</code></td><td>Builder registry index</td></tr> </tbody></table> <h5 id="constants">Constants</h5> <h6 id="index-flags">Index flags</h6> <table><thead><tr><th>Name</th><th>Value</th><th>Description</th></tr></thead><tbody> <tr><td><code>BUILDER_INDEX_FLAG</code></td><td><code>uint64(2**40)</code></td><td>Bitwise flag which indicates that a <code>ValidatorIndex</code> should be treated as a <code>BuilderIndex</code></td></tr> </tbody></table> <h5 id="domains">Domains</h5> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><code>DOMAIN_BEACON_BUILDER</code></td><td><code>DomainType('0x0B000000')</code></td></tr> <tr><td><code>DOMAIN_PTC_ATTESTER</code></td><td><code>DomainType('0x0C000000')</code></td></tr> <tr><td><code>DOMAIN_PROPOSER_PREFERENCES</code></td><td><code>DomainType('0x0D000000')</code></td></tr> </tbody></table> <h5 id="misc">Misc</h5> <table><thead><tr><th>Name</th><th>Value</th><th>Description</th></tr></thead><tbody> <tr><td><code>BUILDER_INDEX_SELF_BUILD</code></td><td><code>BuilderIndex(UINT64_MAX)</code></td><td>Value which indicates the proposer built the payload</td></tr> <tr><td><code>BUILDER_PAYMENT_THRESHOLD_NUMERATOR</code></td><td><code>uint64(6)</code></td><td></td></tr> <tr><td><code>BUILDER_PAYMENT_THRESHOLD_DENOMINATOR</code></td><td><code>uint64(10)</code></td><td></td></tr> </tbody></table> <h5 id="withdrawal-prefixes">Withdrawal prefixes</h5> <table><thead><tr><th>Name</th><th>Value</th><th>Description</th></tr></thead><tbody> <tr><td><code>BUILDER_WITHDRAWAL_PREFIX</code></td><td><code>Bytes1('0x03')</code></td><td>Withdrawal credential prefix for a builder</td></tr> </tbody></table> <h5 id="preset">Preset</h5> <h6 id="misc-1">Misc</h6> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><code>PTC_SIZE</code></td><td><code>uint64(2**9)</code> (= 512)</td></tr> </tbody></table> <h6 id="max-operations-per-block">Max operations per block</h6> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><code>MAX_PAYLOAD_ATTESTATIONS</code></td><td><code>4</code></td></tr> </tbody></table> <h6 id="state-list-lengths">State list lengths</h6> <table><thead><tr><th>Name</th><th>Value</th><th>Unit</th></tr></thead><tbody> <tr><td><code>BUILDER_REGISTRY_LIMIT</code></td><td><code>uint64(2**40)</code> (= 1,099,511,627,776)</td><td>Builders</td></tr> <tr><td><code>BUILDER_PENDING_WITHDRAWALS_LIMIT</code></td><td><code>uint64(2**20)</code> (= 1,048,576)</td><td>Builder pending withdrawals</td></tr> </tbody></table> <h6 id="withdrawals-processing">Withdrawals processing</h6> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><code>MAX_BUILDERS_PER_WITHDRAWALS_SWEEP</code></td><td><code>2**14</code> (= 16,384)</td></tr> </tbody></table> <h5 id="configuration">Configuration</h5> <h6 id="time-parameters">Time parameters</h6> <table><thead><tr><th>Name</th><th>Value</th><th style="text-align: center">Unit</th></tr></thead><tbody> <tr><td><code>MIN_BUILDER_WITHDRAWABILITY_DELAY</code></td><td><code>uint64(2**6)</code> (= 64)</td><td style="text-align: center">epochs</td></tr> </tbody></table> <h5 id="containers">Containers</h5> <h6 id="new-containers">New containers</h6> <h6 id="builder"><code>Builder</code></h6> <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"> Builder</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> pubkey</span><span>:</span><span> BLSPubkey</span></span> <span class="giallo-l"><span> version</span><span>:</span><span> uint8</span></span> <span class="giallo-l"><span> execution_address</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> balance</span><span>:</span><span> Gwei</span></span> <span class="giallo-l"><span> deposit_epoch</span><span>:</span><span> Epoch</span></span> <span class="giallo-l"><span> withdrawable_epoch</span><span>:</span><span> Epoch</span></span></code></pre><h6 id="builderpendingpayment"><code>BuilderPendingPayment</code></h6> <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"> BuilderPendingPayment</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> weight</span><span>:</span><span> Gwei</span></span> <span class="giallo-l"><span> withdrawal</span><span>:</span><span> BuilderPendingWithdrawal</span></span></code></pre><h6 id="builderpendingwithdrawal"><code>BuilderPendingWithdrawal</code></h6> <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"> BuilderPendingWithdrawal</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> fee_recipient</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> amount</span><span>:</span><span> Gwei</span></span> <span class="giallo-l"><span> builder_index</span><span>:</span><span> BuilderIndex</span></span></code></pre><h6 id="payloadattestationdata"><code>PayloadAttestationData</code></h6> <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"> PayloadAttestationData</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> beacon_block_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> slot</span><span>:</span><span> Slot</span></span> <span class="giallo-l"><span> payload_present</span><span>:</span><span> boolean</span></span> <span class="giallo-l"><span> blob_data_available</span><span>:</span><span> boolean</span></span></code></pre><h6 id="payloadattestation"><code>PayloadAttestation</code></h6> <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"> PayloadAttestation</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> aggregation_bits</span><span>:</span><span> Bitvector</span><span>[</span><span class="z-constant">PTC_SIZE</span><span>]</span></span> <span class="giallo-l"><span> data</span><span>:</span><span> PayloadAttestationData</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span> BLSSignature</span></span></code></pre><h6 id="payloadattestationmessage"><code>PayloadAttestationMessage</code></h6> <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"> PayloadAttestationMessage</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> validator_index</span><span>:</span><span> ValidatorIndex</span></span> <span class="giallo-l"><span> data</span><span>:</span><span> PayloadAttestationData</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span> BLSSignature</span></span></code></pre><h6 id="indexedpayloadattestation"><code>IndexedPayloadAttestation</code></h6> <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"> IndexedPayloadAttestation</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> attesting_indices</span><span>:</span><span> List</span><span>[</span><span>ValidatorIndex</span><span>,</span><span class="z-constant"> PTC_SIZE</span><span>]</span></span> <span class="giallo-l"><span> data</span><span>:</span><span> PayloadAttestationData</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span> BLSSignature</span></span></code></pre><h6 id="executionpayloadbid"><code>ExecutionPayloadBid</code></h6> <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"> ExecutionPayloadBid</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> parent_block_hash</span><span>:</span><span> Hash32</span></span> <span class="giallo-l"><span> parent_block_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> block_hash</span><span>:</span><span> Hash32</span></span> <span class="giallo-l"><span> prev_randao</span><span>:</span><span> Bytes32</span></span> <span class="giallo-l"><span> fee_recipient</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> gas_limit</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> builder_index</span><span>:</span><span> BuilderIndex</span></span> <span class="giallo-l"><span> slot</span><span>:</span><span> Slot</span></span> <span class="giallo-l"><span> value</span><span>:</span><span> Gwei</span></span> <span class="giallo-l"><span> execution_payment</span><span>:</span><span> Gwei</span></span> <span class="giallo-l"><span> blob_kzg_commitments</span><span>:</span><span> List</span><span>[</span><span>KZGCommitment</span><span>,</span><span class="z-constant"> MAX_BLOB_COMMITMENTS_PER_BLOCK</span><span>]</span></span></code></pre><h6 id="signedexecutionpayloadbid"><code>SignedExecutionPayloadBid</code></h6> <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"> SignedExecutionPayloadBid</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> message</span><span>:</span><span> ExecutionPayloadBid</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span> BLSSignature</span></span></code></pre><h6 id="executionpayloadenvelope"><code>ExecutionPayloadEnvelope</code></h6> <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"> ExecutionPayloadEnvelope</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> payload</span><span>:</span><span> ExecutionPayload</span></span> <span class="giallo-l"><span> execution_requests</span><span>:</span><span> ExecutionRequests</span></span> <span class="giallo-l"><span> builder_index</span><span>:</span><span> BuilderIndex</span></span> <span class="giallo-l"><span> beacon_block_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> slot</span><span>:</span><span> Slot</span></span> <span class="giallo-l"><span> state_root</span><span>:</span><span> Root</span></span></code></pre><h6 id="signedexecutionpayloadenvelope"><code>SignedExecutionPayloadEnvelope</code></h6> <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"> SignedExecutionPayloadEnvelope</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> message</span><span>:</span><span> ExecutionPayloadEnvelope</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span> BLSSignature</span></span></code></pre><h6 id="modified-containers">Modified containers</h6> <h6 id="beaconblockbody"><code>BeaconBlockBody</code></h6> <p><em>Note</em>: The removed fields (<code>execution_payload</code>, <code>blob_kzg_commitments</code>, and <code>execution_requests</code>) now exist in <code>ExecutionPayloadEnvelope</code>.</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"> BeaconBlockBody</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> randao_reveal</span><span>:</span><span> BLSSignature</span></span> <span class="giallo-l"><span> eth1_data</span><span>:</span><span> Eth1Data</span></span> <span class="giallo-l"><span> graffiti</span><span>:</span><span> Bytes32</span></span> <span class="giallo-l"><span> proposer_slashings</span><span>:</span><span> List</span><span>[</span><span>ProposerSlashing</span><span>,</span><span class="z-constant"> MAX_PROPOSER_SLASHINGS</span><span>]</span></span> <span class="giallo-l"><span> attester_slashings</span><span>:</span><span> List</span><span>[</span><span>AttesterSlashing</span><span>,</span><span class="z-constant"> MAX_ATTESTER_SLASHINGS_ELECTRA</span><span>]</span></span> <span class="giallo-l"><span> attestations</span><span>:</span><span> List</span><span>[</span><span>Attestation</span><span>,</span><span class="z-constant"> MAX_ATTESTATIONS_ELECTRA</span><span>]</span></span> <span class="giallo-l"><span> deposits</span><span>:</span><span> List</span><span>[</span><span>Deposit</span><span>,</span><span class="z-constant"> MAX_DEPOSITS</span><span>]</span></span> <span class="giallo-l"><span> voluntary_exits</span><span>:</span><span> List</span><span>[</span><span>SignedVoluntaryExit</span><span>,</span><span class="z-constant"> MAX_VOLUNTARY_EXITS</span><span>]</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"> [Modified in Gloas:EIP7732]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Removed `execution_payload`</span></span> <span class="giallo-l"><span> bls_to_execution_changes</span><span>:</span><span> List</span><span>[</span><span>SignedBLSToExecutionChange</span><span>,</span><span class="z-constant"> MAX_BLS_TO_EXECUTION_CHANGES</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> [Modified in Gloas:EIP7732]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Removed `blob_kzg_commitments`</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> [Modified in Gloas:EIP7732]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Removed `execution_requests`</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> [New in Gloas:EIP7732]</span></span> <span class="giallo-l"><span> signed_execution_payload_bid</span><span>:</span><span> SignedExecutionPayloadBid</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> [New in Gloas:EIP7732]</span></span> <span class="giallo-l"><span> payload_attestations</span><span>:</span><span> List</span><span>[</span><span>PayloadAttestation</span><span>,</span><span class="z-constant"> MAX_PAYLOAD_ATTESTATIONS</span><span>]</span></span></code></pre><h6 id="beaconstate"><code>BeaconState</code></h6> <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> genesis_time</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> genesis_validators_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> slot</span><span>:</span><span> Slot</span></span> <span class="giallo-l"><span> fork</span><span>:</span><span> Fork</span></span> <span class="giallo-l"><span> latest_block_header</span><span>:</span><span> BeaconBlockHeader</span></span> <span class="giallo-l"><span> block_roots</span><span>:</span><span> Vector</span><span>[</span><span>Root</span><span>,</span><span class="z-constant"> SLOTS_PER_HISTORICAL_ROOT</span><span>]</span></span> <span class="giallo-l"><span> state_roots</span><span>:</span><span> Vector</span><span>[</span><span>Root</span><span>,</span><span class="z-constant"> SLOTS_PER_HISTORICAL_ROOT</span><span>]</span></span> <span class="giallo-l"><span> historical_roots</span><span>:</span><span> List</span><span>[</span><span>Root</span><span>,</span><span class="z-constant"> HISTORICAL_ROOTS_LIMIT</span><span>]</span></span> <span class="giallo-l"><span> eth1_data</span><span>:</span><span> Eth1Data</span></span> <span class="giallo-l"><span> eth1_data_votes</span><span>:</span><span> List</span><span>[</span><span>Eth1Data</span><span>,</span><span class="z-constant"> EPOCHS_PER_ETH1_VOTING_PERIOD</span><span class="z-keyword"> *</span><span class="z-constant"> SLOTS_PER_EPOCH</span><span>]</span></span> <span class="giallo-l"><span> eth1_deposit_index</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> validators</span><span>:</span><span> List</span><span>[</span><span>Validator</span><span>,</span><span class="z-constant"> VALIDATOR_REGISTRY_LIMIT</span><span>]</span></span> <span class="giallo-l"><span> balances</span><span>:</span><span> List</span><span>[</span><span>Gwei</span><span>,</span><span class="z-constant"> VALIDATOR_REGISTRY_LIMIT</span><span>]</span></span> <span class="giallo-l"><span> randao_mixes</span><span>:</span><span> Vector</span><span>[</span><span>Bytes32</span><span>,</span><span class="z-constant"> EPOCHS_PER_HISTORICAL_VECTOR</span><span>]</span></span> <span class="giallo-l"><span> slashings</span><span>:</span><span> Vector</span><span>[</span><span>Gwei</span><span>,</span><span class="z-constant"> EPOCHS_PER_SLASHINGS_VECTOR</span><span>]</span></span> <span class="giallo-l"><span> previous_epoch_participation</span><span>:</span><span> List</span><span>[</span><span>ParticipationFlags</span><span>,</span><span class="z-constant"> VALIDATOR_REGISTRY_LIMIT</span><span>]</span></span> <span class="giallo-l"><span> current_epoch_participation</span><span>:</span><span> List</span><span>[</span><span>ParticipationFlags</span><span>,</span><span class="z-constant"> VALIDATOR_REGISTRY_LIMIT</span><span>]</span></span> <span class="giallo-l"><span> justification_bits</span><span>:</span><span> Bitvector</span><span>[</span><span class="z-constant">JUSTIFICATION_BITS_LENGTH</span><span>]</span></span> <span class="giallo-l"><span> previous_justified_checkpoint</span><span>:</span><span> Checkpoint</span></span> <span class="giallo-l"><span> current_justified_checkpoint</span><span>:</span><span> Checkpoint</span></span> <span class="giallo-l"><span> finalized_checkpoint</span><span>:</span><span> Checkpoint</span></span> <span class="giallo-l"><span> inactivity_scores</span><span>:</span><span> List</span><span>[</span><span>uint64</span><span>,</span><span class="z-constant"> VALIDATOR_REGISTRY_LIMIT</span><span>]</span></span> <span class="giallo-l"><span> current_sync_committee</span><span>:</span><span> SyncCommittee</span></span> <span class="giallo-l"><span> next_sync_committee</span><span>:</span><span> SyncCommittee</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> [Modified in Gloas:EIP7732]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Removed `latest_execution_payload_header`</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> [New in Gloas:EIP7732]</span></span> <span class="giallo-l"><span> latest_execution_payload_bid</span><span>:</span><span> ExecutionPayloadBid</span></span> <span class="giallo-l"><span> next_withdrawal_index</span><span>:</span><span> WithdrawalIndex</span></span> <span class="giallo-l"><span> next_withdrawal_validator_index</span><span>:</span><span> ValidatorIndex</span></span> <span class="giallo-l"><span> historical_summaries</span><span>:</span><span> List</span><span>[</span><span>HistoricalSummary</span><span>,</span><span class="z-constant"> HISTORICAL_ROOTS_LIMIT</span><span>]</span></span> <span class="giallo-l"><span> deposit_requests_start_index</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> deposit_balance_to_consume</span><span>:</span><span> Gwei</span></span> <span class="giallo-l"><span> exit_balance_to_consume</span><span>:</span><span> Gwei</span></span> <span class="giallo-l"><span> earliest_exit_epoch</span><span>:</span><span> Epoch</span></span> <span class="giallo-l"><span> consolidation_balance_to_consume</span><span>:</span><span> Gwei</span></span> <span class="giallo-l"><span> earliest_consolidation_epoch</span><span>:</span><span> Epoch</span></span> <span class="giallo-l"><span> pending_deposits</span><span>:</span><span> List</span><span>[</span><span>PendingDeposit</span><span>,</span><span class="z-constant"> PENDING_DEPOSITS_LIMIT</span><span>]</span></span> <span class="giallo-l"><span> pending_partial_withdrawals</span><span>:</span><span> List</span><span>[</span><span>PendingPartialWithdrawal</span><span>,</span><span class="z-constant"> PENDING_PARTIAL_WITHDRAWALS_LIMIT</span><span>]</span></span> <span class="giallo-l"><span> pending_consolidations</span><span>:</span><span> List</span><span>[</span><span>PendingConsolidation</span><span>,</span><span class="z-constant"> PENDING_CONSOLIDATIONS_LIMIT</span><span>]</span></span> <span class="giallo-l"><span> proposer_lookahead</span><span>:</span><span> Vector</span><span>[</span><span>ValidatorIndex</span><span>,</span><span> (</span><span class="z-constant">MIN_SEED_LOOKAHEAD</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> SLOTS_PER_EPOCH</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> [New in Gloas:EIP7732]</span></span> <span class="giallo-l"><span> builders</span><span>:</span><span> List</span><span>[</span><span>Builder</span><span>,</span><span class="z-constant"> BUILDER_REGISTRY_LIMIT</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> [New in Gloas:EIP7732]</span></span> <span class="giallo-l"><span> next_withdrawal_builder_index</span><span>:</span><span> BuilderIndex</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> [New in Gloas:EIP7732]</span></span> <span class="giallo-l"><span> execution_payload_availability</span><span>:</span><span> Bitvector</span><span>[</span><span class="z-constant">SLOTS_PER_HISTORICAL_ROOT</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> [New in Gloas:EIP7732]</span></span> <span class="giallo-l"><span> builder_pending_payments</span><span>:</span><span> Vector</span><span>[</span><span>BuilderPendingPayment</span><span>,</span><span class="z-constant"> 2</span><span class="z-keyword"> *</span><span class="z-constant"> SLOTS_PER_EPOCH</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> [New in Gloas:EIP7732]</span></span> <span class="giallo-l"><span> builder_pending_withdrawals</span><span>:</span><span> List</span><span>[</span><span>BuilderPendingWithdrawal</span><span>,</span><span class="z-constant"> BUILDER_PENDING_WITHDRAWALS_LIMIT</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> [New in Gloas:EIP7732]</span></span> <span class="giallo-l"><span> latest_block_hash</span><span>:</span><span> Hash32</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> [New in Gloas:EIP7732]</span></span> <span class="giallo-l"><span> payload_expected_withdrawals</span><span>:</span><span> List</span><span>[</span><span>Withdrawal</span><span>,</span><span class="z-constant"> MAX_WITHDRAWALS_PER_PAYLOAD</span><span>]</span></span></code></pre> <p>The <code>BeaconState</code> container is modified with the addition of:</p> <ul> <li><code>builders</code>, of type <code>List[Builder, BUILDER_REGISTRY_LIMIT]</code> to track the new in-protocol staked builders.</li> <li><code>next_withdrawal_builder_index</code> of type <code>BuilderIndex</code> to help tracking builder withdrawals.</li> <li><code>execution_payload_availability</code>, of type <code>Bitvector[SLOTS_PER_HISTORICAL_ROOT]</code> to track the presence of execution payloads on the canonical chain.</li> <li><code>builder_pending_payments</code>, of type <code>Vector[BuilderPendingPayment, 2 * SLOTS_PER_EPOCH]</code> to track pending payments from builders to proposers before the execution payload has been processed.</li> <li><code>builder_pending_withdrawals</code>, of type <code>List[BuilderPendingWithdrawal, BUILDER_PENDING_WITHDRAWALS_LIMIT]</code> to track pending withdrawals to the execution layer with the builders' payments.</li> <li><code>latest_block_hash</code>, of type <code>Hash32</code>, to track the blockhash of the last execution payload in the blockchain.</li> <li><code>payload_expected_withdrawals</code> of type <code>List[Withdrawal, MAX_WITHDRAWALS_PER_PAYLOAD]</code> to track the latest withdrawals that were deducted in the consensus layer and need to still be honored in the Execution Layer.</li> </ul> <p>The <code>BeaconBlockBody</code> is modified with the addition of:</p> <ul> <li><code>signed_execution_payload_bid</code> of type <code>SignedExecutionPayloadBid</code> with the builder's commitment.</li> <li><code>payload_attestations</code> of type <code>List[PayloadAttestation, MAX_PAYLOAD_ATTESTATIONS]</code> a list of PTC attestations from the previous slot.</li> </ul> <p>The <code>ExecutionPayloadHeader</code> object is changed (and renamed to <code>ExecutionPayloadBid</code>) to only track the minimum information needed to commit to a builder's payload.</p> <p>State transition logic is modified by:</p> <ul> <li>A new beacon state getter <code>get_ptc</code> returns the PTC members for a given slot.</li> <li><code>process_withdrawals</code> is modified as follows. Withdrawals are obtained directly from the beacon state instead of the execution payload. They are deducted from the beacon chain. The beacon state <code>latest_withdrawals_root</code> is updated with the HTR of this list. The next execution payload MUST include withdrawals matching the <code>state.latest_withdrawals_root</code>.</li> <li><code>process_execution_payload</code> is removed from <code>process_block</code>. Instead a new function <code>process_execution_payload_bid</code> is included, this function validates the <code>SignedExecutionPayloadBid</code> included in the <code>BeaconBlockBody</code>, ensures the payment from the builder's balance can be deducted and adds a <code>BuilderPendingPayment</code> object to the beacon state.</li> <li><code>process_deposit_request</code> is removed from <code>process_operations</code> and deferred until <code>process_execution_payload</code>. Special care is added for deposit requests from new validator pubkeys, with withdrawal credentials starting with the prefix <code>BUILDER_WITHDRAWAL_PREFIX</code>. These deposits are immediately added to the beacon chain and processed as new builders.</li> <li><code>process_withdrawal_request</code> is removed from <code>process_operations</code> and deferred until <code>process_execution_payload</code>.</li> <li><code>process_consolidation_request</code> is removed from <code>process_operations</code> and deferred until <code>process_execution_payload</code>.</li> <li>A new <code>process_payload_attestation</code> is added to <code>process_operations</code>, this function validates the payload timeliness attestations broadcast by the PTC members.</li> <li><code>process_execution_payload</code> is now called as a separate helper when receiving a <code>SignedExecutionPayloadEnvelope</code> on the P2P layer. This function in particular checks that the HTR of the resulting beacon state coincides with the committed one in the payload envelope. On sucessful processing of the execution payload, the corresponding <code>BuilderPendingPayment</code> is removed from the beacon state and a <code>BuilderPendingWithdrawal</code> is queued.</li> </ul> <p>Epoch processing is modified by addition of a new helper function <code>process_builder_pending_payments</code>, that processes the builder pending payments from those payloads that were not included in the canonical chain. Although there is no change in the <code>AttestationData</code> object, the <code>index</code> field which is unused since the Electra fork, is now repurposed to signal payload availability. The value of <code>0</code> is used when attesting to the current beacon block or a past beacon block without a payload present, and the value of <code>1</code> is used to attest to a past beacon block with a payload present.</p> <h4 id="fork-choice-changes">Fork-Choice changes</h4> <p>Forkchoice is changed substantially to deal with the fact that forkchoice nodes can have different payload content.</p> <h4 id="p2p-changes">P2P changes</h4> <ul> <li>A new global topic for broadcasting <code>SignedExecutionPayloadBid</code> messages (builder bids).</li> <li>A new global topic for broadcasting <code>PayloadAttestationMessage</code> objects.</li> <li>A new global topic for broadcasting <code>ProposerPreferences</code> objects.</li> </ul> <h3 id="engine-api">Engine API</h3> <p>No changes needed.</p> <h2 id="rationale">Rationale</h2> <h3 id="staked-builders">Staked builders</h3> <p>Being a builder is a new type of entity tracked in the beacon state. As such builders are staked in the beacon chain and they have their own withdrawal credential prefix. This allows for in-protocol trustless enforcement of the builder's payment to the proposer. Alternatively, payment could be enforced in the Execution Layer (EL) at the cost of adding the corresponding EL consensus-changing logic. Payments in the EL have the advantage of not requiring the builder to periodically submit deposit transactions to replenish their validator balance. Both systems require availability of funds before the payload is revealed: in the Consensus Layer (CL) this is done by getting builders to stake. In the EL this is done with a balance check and a payment transaction. This transaction can be checked without executing the payload only if it the first transaction of the block.</p> <h3 id="delayed-validation">Delayed validation</h3> <p>The Payload Timeliness Committee members do not need to validate the execution payload before attesting to it. They perform basic checks such as verifying the builder's signature, and the correct blockhash is included. This takes away the full execution payload validation from the hot path of validation of an Ethereum block, giving the next proposer 6 seconds (<code>SECONDS_PER_SLOT * 2 // INTERVALS_PER_SLOT</code>) to validate the payload and every other validator 9 seconds (<code>SECONDS_PER_SLOT * 3 // INTERVALS_PER_SLOT</code>). From a user UX perspective, a transaction included in slot <code>N</code> by the builder is not widely validated until the proposer of slot <code>N+1</code> releases their beacon block on top of block <code>N</code> first and the attesters of slot <code>N+1</code> vote on this beacon block as the head of the chain.</p> <h3 id="fork-choice">Fork choice</h3> <p>The following features of fork choice are guaranteed under specified margins of security:</p> <ul> <li>Proposer unconditional payment.</li> <li>Builder reveal safety.</li> <li>Builder withhold safety.</li> </ul> <p>Proposer unconditional payment refers to the following. An Ethereum slot can be either:</p> <ul> <li><em>Full</em>: both the beacon block and the execution payload have been revealed and included on-chain.</li> <li><em>Skipped</em>: No beacon block (and therefore no execution payload) has been included on-chain for this slot.</li> <li><em>Empty</em>: The beacon block has been included on-chain, but the committed execution payload has not.</li> </ul> <p>Proposer unconditional payment refers to the fact that in the third scenario the beacon block proposer received payment from the corresponding builder.</p> <p>Builder reveal safety refers to the fact that if the builder acted honestly and revealed a payload in a timely fashion (as attested by the PTC) then the revealed payload will be included on-chain.</p> <p>Builder withhold safety refers to the fact that if some beacon block containing a builder's commitment is withheld and revealed late, the builder will not be charged the value of the bid. In particular, the payload does not even need to be revealed in this case.</p> <p>The precise method by which these safety mechanisms are enforced is by allowing attestations to also signal their view of the slot as in either of the above options <em>Full</em>, <em>Skipped</em> or <em>Empty</em>. For this, the <code>index</code> field in the <code>AttestationData</code> is used as explained above.</p> <h3 id="ptc-equivocations">PTC equivocations</h3> <p>There is no penalty for PTC nor payload equivocation (that is revealing the right payload and also a withheld message at the same time). A collusion of a builder controlling network partition with a single malicious PTC member could cause a split view by achieving consensus both on payload withheld and a payload present. This could be mitigated by setting <code>PAYLOAD_TIMELY_THRESHOLD</code> to be 2/3 of the PTC, in which case the malicious operator would have to control at least 33% of the PTC.</p> <p>Another mitigation mechanism is to add new slashing conditions for payload equivocation or PTC equivocations (both are signed messages by validators).</p> <p>Since this attack results in a split view at a cost for the builder (the payload is revealed and may not be included) this EIP opted for simplicity of implementation.</p> <h3 id="withdrawals">Withdrawals</h3> <p>Withdrawals from the beacon chain are complex in nature, they involve removing funds from one layer and crediting them on another, with different trigger mechanisms that can start from either layer. Before applying the consensus layer state transition function to a given beacon state <code>pre_state</code> and processing a given signed beacon block <code>block</code>, the set of withdrawals that are expected to be deducted from the beacon chain are completely determined by <code>pre_state</code>. Previous to this EIP the set of withdrawals that are credited on the execution layer are included in <code>block</code>. The block is deemed invalid if these withdrawals do not match. With the separation included in this EIP, these operations of deducting and crediting become asynchronous:</p> <ul> <li>When processing the beacon block, the withdrawals are deducted from the beacon chain.</li> <li>The set of withdrawals just deducted is committed to the beacon state <code>post_state</code>.</li> <li>When processing any execution payload whose parent beacon state is <code>post_state</code>, the payload is deemed invalid if it doesn't include precisely the list of withdrawals committed to <code>post_state</code>.</li> </ul> <p>This asynchronous mechanism has some consequences as slots may be <em>empty</em> as defined above. In these cases, the consensus layer does not process any more withdrawals until an execution payload has fulfilled the outstanding ones. An alternative design would be to defer all of withdrawal processing to the execution payload validation phase (ie. <code>process_execution_payload</code>). This has the advantage of not needing to track the fulfilled withdrawals on the beacon chain. The logic changes when several payloads are missing, in which case balances on the beacon chain change and therefore a withdrawal that would be possible with the former mechanism may be different, or even impossible with the latter.</p> <h3 id="three-state-transition-functions">Three state transition functions</h3> <p>The current EIP adds an extra state transition function to the block processing in Ethereum. Processing a <code>SignedBeaconBlock</code> changes the consensus layer <code>BeaconState</code>. A <code>SignedExecutionPayloadEnvelope</code> changes both the execution layer state and the consensus layer one. As such, the envelope commits to the consensus layer post-state-transition beacon state root.</p> <h3 id="compatible-designs">Compatible designs</h3> <h4 id="inclusion-lists">Inclusion lists</h4> <p>This EIP is fully compatible with forkchoice enforced inclusion lists as specified in <a href="https://wg-eips.ritovision.com/7805/">EIP-7805</a> or similar.</p> <h4 id="slot-auctions">Slot auctions</h4> <p>A simple change to this EIP is to remove the blockhash commitment from the <code>SignedExecutionPayloadBid</code>. This allows the builder to commit any payload to the slot. A preliminary security analysis shows that payload equivocation does not weaken fork choice's FFG. Some advantages of Slot auctions include:</p> <ul> <li>Better user experience as any submitted transaction can be included in the next block (with block auctions a transaction sent in the first half of the slot can only be included in the following block).</li> <li>Longer continuous time to build blocks.</li> <li>Better compatibility designs with fork choice enforced inclusion list proposals.</li> </ul> <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> <h2 id="security-considerations">Security Considerations</h2> <h3 id="free-option-problem">Free option problem</h3> <p>Economically rational but malicious (as defined by the honest builder guide) builders may chose to withhold their payload in the event that it would be profitable for them. This could result in missed slots and degradation of user experience of Ethereum. Some preliminary data in the form of simulation suggests that the number of these occurrences may be noticeable. Some mitigations were proposed in the form of variable penalties for builders that fail to include their payload envelopes in the canonical chain.</p> <h3 id="builder-safety">Builder safety</h3> <ul> <li>A colluding set of proposers and attesters controlling consecutive blocks and more than 20% of the total stake can reorg a builder's payload and force it to pay the bid's value.</li> <li>There is no possible <em>unbundling</em> of the builder's payload in the same slot, that is, if the builder reveals a payload for the head of the chain, no other payload is possible for the current slot.</li> </ul> <h3 id="malicious-ptc">Malicious PTC</h3> <p>The expected time for a malicious attacker, controlling 35% of the total stake, to have a majority control on the PTC is 205 000 years.</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-26T00:00:00+00:00 2026-02-11T14:48:25+00:00 Anushka Yadavhttps://github.com/64anushka64anushka@gmail.com https://wg-eips.ritovision.com/7734/

A privacy-preserving method for decentralized identity verification, enabling secure integration of identity management in dApps.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a standard for decentralized identity verification (DID) on the blockchain. The standard leverages cryptographic hashes to represent identity proofs and events for transparency and traceability. By emphasizing simplicity, privacy, and user control, this proposal aims to reduce overhead for developers and users, ensuring seamless integration into decentralized applications (dApps). It offers a minimalistic solution that keeps identity structure simple and enables off-chain mechanisms for detailed identity management and verification.</p> <h2 id="motivation">Motivation</h2> <p>Centralized identity verification methods are cumbersome, prone to data breaches, and fail to provide users control over their identity data. Existing DID solutions often introduce complexity, making adoption challenging for developers and users. This proposal seeks to address these issues by:</p> <ul> <li>Offering a minimalistic, decentralized standard that simplifies identity verification.</li> <li>Providing privacy-preserving mechanisms that keep sensitive identity data off-chain.</li> <li>Encouraging wider adoption by enabling seamless integration into dApps across various industries.</li> </ul> <h3 id="stakeholders">Stakeholders</h3> <p>The following stakeholders will benefit from this proposal:</p> <h4 id="dapp-developers">dApp Developers</h4> <p>Developers creating decentralized applications that require identity verification can implement this standard to provide users with secure, decentralized identity management. The minimalistic design makes it easier to integrate into existing workflows without adding unnecessary complexity.</p> <h4 id="service-providers">Service Providers</h4> <p>Platforms offering services such as decentralized finance (DeFi), gaming, or social networking can integrate this standard to verify user identities without relying on centralized authorities. This reduces the risk of fraud and enhances user trust.</p> <h4 id="enterprises">Enterprises</h4> <p>Companies looking to integrate blockchain-based identity solutions into their existing systems can use this standard to ensure secure and privacy-preserving identity verification. This allows for a seamless transition to decentralized technologies while maintaining user privacy and security.</p> <h4 id="developers-of-interoperability-solutions">Developers of Interoperability Solutions</h4> <p>Those working on cross-platform and cross-blockchain interoperability can implement this standard to enable a unified identity verification mechanism across different systems, reducing complexity and increasing user control over their identities.</p> <h3 id="differentiation">Differentiation</h3> <p>This proposal stands out from other DID standards by focusing on minimalism, user control, and privacy. Unlike other solutions that encompass a wide range of identity attributes and interactions, this standard keeps the structure simple and relies on off-chain mechanisms for detailed identity management. Its simplicity fosters easier adoption, making it ideal for dApps that prioritize user-centric, secure ecosystems.</p> <h2 id="specification">Specification</h2> <p>The Decentralized Identity Verification (DID) standard introduces a simple, secure, and privacy-preserving mechanism for verifying user identities on the blockchain. The key components of this standard are outlined below:</p> <h4 id="identity-contract">Identity Contract</h4> <p>A smart contract that acts as the central authority for identity verification. The contract stores the status of identity verifications for users and ensures that verification events are triggered securely and transparently.</p> <h4 id="verification-function">Verification Function</h4> <p>The <code>verifyIdentity</code> function allows a user to submit two verification hashes that represent off-chain proofs or attestations of identity. These hashes can be derived from external sources such as third-party verifiers, documents, or attestations.The function compares the provided hashes and updates the identity verification status accordingly.</p> <h5 id="input-parameters">Input Parameters:</h5> <p><strong>identityHash:</strong> A cryptographic hash representing the user's identity. <strong>verificationHash:</strong> A cryptographic hash derived from the proof or attestation used to verify the identity.</p> <h4 id="identityverified-event">IdentityVerified Event</h4> <p>The <code>IdentityVerified</code> event is emitted when the user's identity verification is successfully updated. This event ensures traceability and transparency, allowing dApp developers and users to track verification statuses.</p> <h4 id="identity-structure">Identity Structure</h4> <p>The identity is a simple structure represented by a unique address (public key). Additional identity attributes, such as name or age, are optional and left to off-chain management. This minimal approach keeps the implementation lean, avoiding unnecessary complexity and encouraging broader adoption.</p> <h3 id="interface">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"> ^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"> IDecentralizedIdentity</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Struct to represent an identity</span></span> <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> userAddress</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Ethereum address of the user</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> identityHash</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Hash of the identity data</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span class="z-constant">2</span><span>]</span><span> verificationHashes</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Hashes used for verifying identity</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isVerified</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Indicates if the identity is verified</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> timestamp</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Timestamp of identity creation</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"> Event emitted when a new identity is created</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 class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> userAddress</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> identityHash</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> timestamp</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 an identity is verified</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdentityVerified</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> userAddress</span><span>, </span><span class="z-support">bytes32</span><span>[</span><span class="z-variable">2</span><span>]</span><span class="z-variable"> verificationHashes</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> timestamp</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 an identity is revoked</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdentityRevoked</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> userAddress</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> timestamp</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Function to create a new decentralized identity for the caller.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Parameters:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - identityHash: Hash of the identity data.</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">bytes32</span><span class="z-variable"> identityHash</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"> Function to verify the decentralized identity for the caller.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Parameters:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - verificationHashes: Hashes used for verifying the identity. These can be </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> derived from off-chain proofs, cryptographic challenges, or other methods </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> specific to the implementer&#39;s requirements. The exact meaning and derivation </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> of the verificationHashes are left to the contract&#39;s implementer.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyIdentity</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"> verificationHashes</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"> Function to revoke the decentralized identity for the caller.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeIdentity</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 class="z-comment"> //</span><span class="z-comment"> Function to retrieve the decentralized identity for a given user address</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Parameters:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - userAddress Ethereum address of the user.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Returns:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> identity The decentralized identity struct.</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">address</span><span class="z-variable"> userAddress</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">Identity</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> <p>The design leverages cryptographic hashes to represent identity information, ensuring that sensitive data is not stored directly on the blockchain. The use of <code>verificationHashes</code> allows for flexible identity verification mechanisms. These hashes could be derived from various off-chain proofs, such as cryptographic challenges or attestations, depending on the implementer's needs. By leaving the interpretation of the verification hashes open, the standard enables adaptability while maintaining privacy and security. Additionally, the inclusion of events ensures transparency and traceability.</p> <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.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;./IDecentralizedIdentity.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"> DecentralizedIdentity</span><span class="z-storage"> is</span><span class="z-entity z-name"> IDecentralizedIdentity</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Mapping to store identities by user address</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> Identity</span><span>)</span><span class="z-storage z-type"> private</span><span> identities</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Function to create a new decentralized identity for the caller.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Parameters:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - identityHash Hash of the identity data.</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">bytes32</span><span class="z-variable"> identityHash</span><span>)</span><span class="z-storage z-type"> external</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"> Ensure identity does not already exist</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>identities</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>userAddress </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;Identity already exists&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"> Create the identity for the caller</span></span> <span class="giallo-l"><span> identities</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Identity</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> userAddress</span><span class="z-keyword">:</span><span class="z-variable z-language"> msg.sender</span><span>,</span></span> <span class="giallo-l"><span> identityHash</span><span class="z-keyword">:</span><span> identityHash</span><span>,</span></span> <span class="giallo-l"><span> verificationHashes</span><span class="z-keyword">:</span><span> [</span><span class="z-support">bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>]</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Initialize with empty hashes</span></span> <span class="giallo-l"><span> isVerified</span><span class="z-keyword">:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span> timestamp</span><span class="z-keyword">:</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</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-comment"> Emit event for the creation of a new identity</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> IdentityCreated</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> identityHash</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</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"> Function to verify the decentralized identity for the caller.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Parameters:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - verificationHashes: Hashes used for verifying the identity.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyIdentity</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"> verificationHashes</span><span>)</span><span class="z-storage z-type"> external</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"> Ensure identity exists</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>identities</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>userAddress </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;Identity does not exist&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"> Update verification hashes and mark identity as verified</span></span> <span class="giallo-l"><span> identities</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>verificationHashes </span><span class="z-keyword">=</span><span> verificationHashes</span><span>;</span></span> <span class="giallo-l"><span> identities</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>isVerified </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"> Emit event for the verification of identity</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> IdentityVerified</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> verificationHashes</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</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"> Function to revoke the decentralized identity for the caller.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeIdentity</span><span>(</span><span>)</span><span class="z-storage z-type"> external</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"> Ensure identity exists</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>identities</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>userAddress </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;Identity does not exist&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"> Mark identity as not verified</span></span> <span class="giallo-l"><span> identities</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>isVerified </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-comment"> //</span><span class="z-comment"> Emit event for the revocation of identity</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> IdentityRevoked</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</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"> Function to retrieve the decentralized identity for a given user address</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Parameters:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - userAddress Ethereum address of the user.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Returns:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> identity The decentralized identity struct.</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">address</span><span class="z-variable"> userAddress</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"> override</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">Identity</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> identities</span><span>[</span><span>userAddress</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><strong>Secure Hashing</strong>: Ensure that identity and verification hashes are generated using a secure hashing algorithm to prevent collisions and ensure the integrity of the identity data. <strong>Replay Attacks</strong>: Verification hashes should incorporate nonces or timestamps to prevent replay attacks. <strong>Implementation Flexibility</strong>: Developers must ensure that hash generation and validation processes are robust and resistant to 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> 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-06-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Yamen Merhihttps://github.com/YamenMerhi Patronum Labshttps://github.com/Patronum-Labs https://wg-eips.ritovision.com/7749/

A new RPC method to sign data with an intended validator address according to ERC-191 version 0x00.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a new JSON-RPC method, <code>wallet_signIntendedValidatorData</code>, which allows signing data with an intended validator address using <a href="https://wg-eips.ritovision.com/191/">ERC-191</a> version 0x00 with this format:</p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">0x19</span><span class="z-keyword"> &lt;</span><span class="z-string">0x0</span><span class="z-keyword">0&gt;</span><span class="z-keyword"> &lt;</span><span class="z-string">intended</span><span class="z-string"> validator</span><span class="z-string"> addres</span><span>s</span><span class="z-keyword">&gt;</span><span class="z-keyword"> &lt;</span><span class="z-string">data</span><span class="z-string"> to</span><span class="z-string"> sig</span><span>n</span><span class="z-keyword">&gt;</span></span></code></pre><h2 id="motivation">Motivation</h2> <p>Currently, signing messages relies heavily on ERC-191 version 0x45 (<code>eth_sign</code>) and <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> (<code>eth_signTypedData</code>). While EIP-712 provides a more structured approach, it is often seen as complex. On the other hand, ERC-191 version 0x45 is widely used but poses significant phishing risks due to the lack of data parsing.</p> <p>ERC-191 defines three versions: 0x45, 0x01, and 0x00. This proposal aims to fully support ERC-191 by introducing the rpc call for 0x00 version, which enables signing data with an intended validator address. This new method will:</p> <ul> <li>Enable more dApps to use ERC-191 version 0x00 without using raw signing methods which might be dangerous and restricted in few wallets.</li> <li>Enhance security by parsing data and displaying the intended validator address, reducing phishing risks.</li> <li>Provide a simpler alternative to EIP-712, offering a balance between usability and security.</li> <li>Be particularly relevant for smart contract accounts, allowing signing with a specific intended validator address.</li> </ul> <p>With the rise of smart contract accounts and the reliance on signatures to improve UX, the need for supporting ERC-191 version 0x00 increases, especially given the prevalence of verifier smart contracts, such as Entry Points, Smart Contract Accounts, Key Managers, etc.</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="wallet-signintendedvalidatordata"><code>wallet_signIntendedValidatorData</code></h3> <p>MUST calculate an Ethereum signature using <code>sign(keccak256("\x19\x00&lt;intended validator address&gt;&lt;data to sign&gt;"))</code>.</p> <p>This method adds a prefix to the message to prevent malicious dApps from signing arbitrary data (e.g., a transaction) and using the signature to impersonate the victim.</p> <h4 id="parameters">Parameters</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> WalletSignIntendedValidatorDataParams</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> signerAddress</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span> </span></span> <span class="giallo-l"><span class="z-variable"> validatorAddress</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span> </span></span> <span class="giallo-l"><span class="z-variable"> dataToSign</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span> </span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ol> <li><code>signerAddress</code> - 20-byte account address: The address signing the constructed message.</li> <li><code>validatorAddress</code> - 20-byte account address: The intended validator address included in the message to sign.</li> <li><code>dataToSign</code> - Data string: The data to sign.</li> </ol> <h4 id="returns">Returns</h4> <p><code>Signature</code> - The Ethereum Signature generated.</p> <h2 id="rationale">Rationale</h2> <p>The <code>wallet_signIntendedValidatorData</code> method aims to bridge the gap between the simplicity of ERC-191 version 0x45 and the structured approach of EIP-712. By specifying the intended validator address, it reduces phishing risks and provides a more secure signing method for smart contract accounts and other use cases requiring a specific validator address.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="example">Example</h3> <ul> <li> <p>Signer Address (<code>0x6aFbBC5e6AFcB251371711a6551E60ead2779Dc0</code>): This is the address of the account that will be used to sign the constructed message. We have access to the private key of this address, which allows us to generate the signature securely.</p> </li> <li> <p>Verifier Address (<code>0x345B918b9E06fAa7B0e56bd71Ba418F31F47FED4</code>): This address represents the address verifying the signature, could be an EOA or smart contract. For example, it could be a contract that performs specific actions based on the validity of the signature. By including this address in the data to be signed, we ensure that the signature cannot be reused by malicious actors for unintended purposes.</p> </li> <li> <p>Data to Sign (<code>0x59616d656e</code>): This is the hex-encoded string representing the actual content to be signed. In this example, it is the hex encoding for the ASCII string "Yamen". The data, combined with the verifier address, is hashed and signed to generate a unique signature that cannot be used for any other purpose.</p> </li> </ul> <p><strong>Request:</strong></p> <pre class="giallo z-code"><code data-lang="shellscript"><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">{&quot;jsonrpc&quot;:&quot;2.0&quot;,&quot;method&quot;:&quot;wallet_signIntendedValidatorData&quot;,&quot;params&quot;:[&quot;0x6aFbBC5e6AFcB251371711a6551E60ead2779Dc0&quot;, &quot;0x345B918b9E06fAa7B0e56bd71Ba418F31F47FED4&quot;, &quot;0x59616d656e&quot;], &quot;id&quot;:1}</span><span class="z-punctuation z-definition z-string">&#39;</span></span></code></pre><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">wallet_signIntendedValidatorData</span><span class="z-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">0x6aFbBC5e6AFcB251371711a6551E60ead2779Dc0</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">0x345B918b9E06fAa7B0e56bd71Ba418F31F47FED4</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">0x59616d656e</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">id</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> <p><strong>Result:</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">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"> 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">0x4355c47d63924e8a72e509b65029052eb6c299d53a04e167c5775fd466751c9d07299936d304c153f6443dfa05f40ff007d72911b6f72307f996231605b915621c</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The result field contains the Ethereum signature generated by signing the hashed message according to version 0 of ERC-191.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Users should exercise caution when signing messages. Double-check the address of the verifier and ensure trust in the dApp triggering the sign request.</p> <p>To protect against replay attacks and cross-chain replay attacks, include chainId and nonce in the validator data to sign.</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-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 alcuecahttps://github.com/alcueca ruvaaghttps://github.com/ruvaag totomanovhttps://github.com/totomanov r0ohafzahttps://github.com/r0ohafza https://wg-eips.ritovision.com/7726/

Interface for data feeds providing the relative value of assets.

<h2 id="abstract">Abstract</h2> <p>The following allows for the implementation of a standard API for data feeds providing the relative value of assets, forcing compliant contracts to use explicit token amounts instead of price factors. This approach has been shown to lead to better security and time-to-market outcomes.</p> <h2 id="motivation">Motivation</h2> <p>The information required to value assets is scattered over a number of major and minor sources, each one with their own integration API and security considerations. Many protocols over the years have implemented oracle adapter layers for their own use to abstract this complexity away from their core implementations, leading to much duplicated effort.</p> <p>This specification provides a standard API aimed to serve the majority of use cases. Preference is given to ease of integration and serving the needs of product teams with less knowledge, requirements and resources.</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="definitions">Definitions</h3> <ul> <li>base asset: The asset that the user needs to know the value for (e.g: USDC as in "I need to know the value of 1e6 USDC in ETH terms").</li> <li>quote asset: The asset in which the user needs to value the <code>base</code> (e.g: ETH as in "I need to know the value of 1e6 USDC in ETH terms").</li> <li>value: An amount of <code>base</code> in <code>quote</code> terms (e.g. The <code>value</code> of 1000e6 USDC in ETH terms is 283,969,794,427,307,000 ETH, and the <code>value</code> of 1000e18 ETH in USDC terms is 3,521,501,299,000 USDC). Note that this is an asset amount, and not a decimal factor.</li> </ul> <h3 id="methods">Methods</h3> <h4 id="getquote"><code>getQuote</code></h4> <p>Returns the value of <code>baseAmount</code> of <code>base</code> in <code>quote</code> terms.</p> <p>MUST round down towards 0.</p> <p>MUST revert if the value of <code>baseAmount</code> of <code>base</code> in <code>quote</code> terms would overflow in a uint256.</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">etQuote</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"> b</span><span class="z-string">aseAmount</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"> b</span><span class="z-string">ase</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"> q</span><span class="z-string">uote</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"> q</span><span class="z-string">uoteAmount</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="special-addresses">Special Addresses</h3> <p>Some assets under the scope of this specification don't have an address, such as ETH, BTC and national currencies.</p> <p>For ETH, the address will be <code>0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE</code> as per <a href="https://wg-eips.ritovision.com/7528/">ERC-7528</a>.</p> <p>For BTC, the address will be <code>0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB</code>.</p> <p>For assets without an address, but with an ISO 4217 <!-- TODO: Bug Sam about editing EIP-1 to allow certain ISO external links --> code, the code will be used (e.g. <code>address(840)</code> for USD).</p> <h2 id="rationale">Rationale</h2> <p>The use of <code>getQuote</code> doesn't require the consumer to be aware of any decimal partitions that might have been defined for the <code>base</code> or <code>quote</code> and should be preferred in most data processing cases.</p> <p>The spec doesn't include a <code>getPrice</code> function because it is rarely needed on-chain, and it would be a decimal number of difficult representation. The popular option for representing prices can be implemented for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> with decimals as `oracle.getQuote(base, quote, 10**base.decimals()) and will give the value of a whole unit of base in quote terms.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Most existing data feeds related to the relative value of pairs of assets should be representable using this standard.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This specification purposefully provides no methods for data consumers to assess the validity of the data they receive. It is expected of individual implementations using this specification to decide and publish the quality of the data that they provide, including the conditions in which they will stop providing it.</p> <p>Consumers should review these guarantees and use them to decide whether to integrate or not with a data provider.</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-09T00:00:00+00:00 2026-02-11T14:48:25+00:00 Chen Liaoyuanhttps://github.com/chenlycly@kip.pro https://wg-eips.ritovision.com/7720/

Allows users to schedule ERC-20 token transfers for withdrawal at a specified future time, enabling deferred payments.

<h2 id="abstract">Abstract</h2> <p>This standard specifies that allows users to deposit <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens for a beneficiary. The beneficiary can withdraw the tokens only after a specified future timestamp. Each deposit transaction is assigned a unique ID and includes details such as the token address, sender, recipient, amount, unlock time, and withdrawal status.</p> <h2 id="motivation">Motivation</h2> <p>In various scenarios, such as vesting schedules, escrow services, or timed rewards, there is a need for deferred payments. This contract provides a secure and reliable mechanism for time-locked token transfers, ensuring that tokens can only be transferred after a specified timestamp is reached. By facilitating structured and delayed payments, it adds an extra layer of security and predictability to token transfers. This is particularly useful for scenarios where payments are contingent upon the passage of time.</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>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">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"> ITokenTransfer</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Event emitted when a transfer is initiated.</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"> uint256</span><span class="z-variable"> txnId</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"> token</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-support"> uint40</span><span class="z-variable"> unlockTime</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> referenceNo</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"> Event emitted when tokens are withdrawn.</span></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"> uint256</span><span class="z-variable"> txnId</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"> token</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 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"> Function to initiate a token transfer.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Parameters:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _token: Address of the ERC20 token contract.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _from: Address of the sender.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _to: Address of the recipient.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _amount: Amount of tokens to be transferred.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _unlockTime: Time after which the tokens can be withdrawn.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _reference: Reference ID for the transaction.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Returns the transaction ID.</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 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"> _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-support"> uint40</span><span class="z-variable z-parameter z-function"> _unlockTime</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _reference</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">uint256</span><span class="z-variable"> txnId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Function to withdraw tokens from a transaction.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Parameters:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _txnId: ID of the transaction to withdraw from.</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 z-parameter z-function"> _txnId</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"> Function to get transaction details.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Parameters:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _txnId: ID of the transaction.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Returns the transaction details.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTransaction</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _txnId</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> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> token</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></span> <span class="giallo-l"><span class="z-support"> uint40</span><span class="z-variable"> unlockTime</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> referenceNo</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> withdrawn</span></span> <span class="giallo-l"><span> )</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 design of the Deferred Token Transfer contract aims to provide a straightforward and secure method for handling time-locked token transfers. The following considerations were made during its development:</p> <p><strong>Unlock Time Precision with <code>uint40</code></strong>: We chose a full <code>uint40</code> for <code>_unlockTime</code> because it provides a sufficiently large range to cover all practical time-lock scenarios. This ensures that the contract can handle deferred payments that require precise timing over long periods, such as vesting schedules or long-term escrows.</p> <p><strong>Returning <code>txnId</code> from <code>transferFrom</code></strong>: The <code>transferFrom</code> function returns a unique <code>txnId</code> for each transaction. This design choice was made to facilitate easy and independent tracking of each transaction. By having a unique ID, users can manage and reference specific transactions, ensuring clarity and preventing confusion. This approach allows each transaction's state to be managed independently, simplifying the withdrawal process.</p> <p><strong>Compatibility with Existing ERC-20 Tokens</strong>: The standard is designed as a separate interface rather than an extension of ERC-20 to ensure flexibility and broad compatibility. By not modifying the ERC-20 standard directly, this proposal can be used with any existing ERC-20 token without requiring changes to their contracts. This flexibility makes the standard applicable to a wide range of tokens already in circulation, enhancing its utility and adoption potential.</p> <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.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/ERC20/utils/SafeERC20.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"> TokenTransfer</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-storage z-type"> struct</span><span class="z-entity z-name"> Transaction</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> token</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Address of the ERC20 token contract.</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> from</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Address of the sender.</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> to</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Address of the recipient.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> amount</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Amount of tokens to be transferred.</span></span> <span class="giallo-l"><span class="z-support"> uint40</span><span> unlockTime</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Time after which the tokens can be withdrawn.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> referenceNo</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Reference ID for the transaction.</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> withdrawn</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Flag indicating if the tokens have been withdrawn.</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"> Mapping from transaction ID to Transaction structure.</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> Transaction</span><span>)</span><span class="z-storage z-type"> public</span><span> transactions</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Variable to keep track of the next transaction ID.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> public</span><span> lastTxnId </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"> Event emitted when a transfer is initiated.</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"> uint256</span><span class="z-variable"> txnId</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"> token</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-support"> uint40</span><span class="z-variable"> unlockTime</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> referenceNo</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"> Event emitted when tokens are withdrawn.</span></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"> uint256</span><span class="z-variable"> txnId</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"> token</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 class="giallo-l"><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>)</span><span> {</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Function to initiate a token transfer.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Parameters:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _token: Address of the ERC20 token contract.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _from: Address of the sender.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _to: Address of the recipient.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _amount: Amount of tokens to be transferred.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _unlockTime: Time after which the tokens can be withdrawn.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _reference: Reference ID for the transaction.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Returns the transaction ID.</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 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"> _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-support"> uint40</span><span class="z-variable z-parameter z-function"> _unlockTime</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _reference</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">uint256</span><span class="z-variable"> txnId</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 class="z-string"> &quot;Invalid transfer amount&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"> Transfer tokens from sender to this contract.</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC20</span><span>(</span><span>_token</span><span>)</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span><span>_from</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> _amount</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> lastTxnId</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"> Store the transaction details.</span></span> <span class="giallo-l"><span> transactions</span><span>[</span><span>lastTxnId</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Transaction</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> token</span><span class="z-keyword">:</span><span> _token</span><span>,</span></span> <span class="giallo-l"><span> from</span><span class="z-keyword">:</span><span> _from</span><span>,</span></span> <span class="giallo-l"><span> to</span><span class="z-keyword">:</span><span> _to</span><span>,</span></span> <span class="giallo-l"><span> amount</span><span class="z-keyword">:</span><span> _amount</span><span>,</span></span> <span class="giallo-l"><span> unlockTime</span><span class="z-keyword">:</span><span> _unlockTime</span><span>,</span></span> <span class="giallo-l"><span> referenceNo</span><span class="z-keyword">:</span><span> _reference</span><span>,</span></span> <span class="giallo-l"><span> withdrawn</span><span class="z-keyword">:</span><span class="z-constant"> false</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-comment"> Emit an event for the transaction creation.</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Transfer</span><span>(</span><span>lastTxnId</span><span>,</span><span> _token</span><span>,</span><span> _from</span><span>,</span><span> _to</span><span>,</span><span> _amount</span><span>,</span><span> _unlockTime</span><span>,</span><span> _reference</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> lastTxnId</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"> Function to withdraw tokens from a transaction.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Parameters:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _txnId: ID of the transaction to withdraw from.</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 z-parameter z-function"> _txnId</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span> Transaction </span><span class="z-storage z-type">storage</span><span> transaction </span><span class="z-keyword">=</span><span> transactions</span><span>[</span><span>_txnId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>transaction</span><span>.</span><span>amount </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Invalid transaction ID&quot;</span><span>)</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>timestamp </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> transaction</span><span>.</span><span>unlockTime</span><span>,</span><span class="z-string"> &quot;Current time is before unlock time&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> require(transaction.to == msg.sender, &quot;Only the recipient can withdraw the tokens&quot;);</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-keyword">!</span><span>transaction</span><span>.</span><span>withdrawn</span><span>,</span><span class="z-string"> &quot;Tokens already withdrawn&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> IERC20</span><span>(</span><span>transaction</span><span>.</span><span>token</span><span>)</span><span>.</span><span class="z-entity z-name">safeTransfer</span><span>(</span><span>transaction</span><span>.</span><span>to</span><span>,</span><span> transaction</span><span>.</span><span>amount</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> transaction</span><span>.</span><span>withdrawn </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"> Emit an event for the token withdrawal.</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Withdraw</span><span>(</span><span>_txnId</span><span>,</span><span> transaction</span><span>.</span><span>token</span><span>,</span><span> transaction</span><span>.</span><span>from</span><span>,</span><span> transaction</span><span>.</span><span>to</span><span>,</span><span> transaction</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 class="z-comment"> Function to get transaction details.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Parameters:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - _txnId: ID of the transaction.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Returns the transaction details.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTransaction</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _txnId</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> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> token</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></span> <span class="giallo-l"><span class="z-support"> uint40</span><span class="z-variable"> unlockTime</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> referenceNo</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> withdrawn</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> Transaction </span><span class="z-storage z-type">storage</span><span> transaction </span><span class="z-keyword">=</span><span> transactions</span><span>[</span><span>_txnId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>transaction</span><span>.</span><span>amount </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Invalid transaction ID&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span></span> <span class="giallo-l"><span> transaction</span><span>.</span><span>token</span><span>,</span></span> <span class="giallo-l"><span> transaction</span><span>.</span><span>from</span><span>,</span></span> <span class="giallo-l"><span> transaction</span><span>.</span><span>to</span><span>,</span></span> <span class="giallo-l"><span> transaction</span><span>.</span><span>amount</span><span>,</span></span> <span class="giallo-l"><span> transaction</span><span>.</span><span>unlockTime</span><span>,</span></span> <span class="giallo-l"><span> transaction</span><span>.</span><span>referenceNo</span><span>,</span></span> <span class="giallo-l"><span> transaction</span><span>.</span><span>withdrawn</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><h2 id="security-considerations">Security Considerations</h2> <p><strong>Ownerless Contract Design</strong>: To prevent the risk of token loss after deposit, the contract should not have an owner. This ensures that the contract's token balance cannot be transferred to any address other than the designated beneficiary.</p> <p><strong>Strict Beneficiary Control</strong>: During withdrawal, the contract must strictly ensure that tokens are transferred only to the beneficiary specified at the time of deposit. This prevents unauthorized access and ensures that only the intended recipient can withdraw the tokens.</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-09T00:00:00+00:00 2026-02-11T14:48:26+00:00 Ivica Aračićhttps://github.com/ivica7 Ante Bešlićhttps://github.com/ethSplit Mirko Katanićhttps://github.com/mkatanic SWIAT https://wg-eips.ritovision.com/7722/

A token specification designed to enhance privacy by concealing balance information.

<h2 id="abstract">Abstract</h2> <p>This ERC proposes a specification for an opaque token that enhances privacy by concealing balance information. Privacy is achieved by representing balances as off-chain data encapsulated in hashes, referred to as "baskets". These baskets can be reorganized, transferred, and managed through token functions on-chain.</p> <h2 id="motivation">Motivation</h2> <p>Smart contract accounts serve as well-defined identities that can have reusable claims and attestations attached to them, making them highly useful for various applications. However, this strength also introduces a significant privacy challenge when these identities are used to hold tokens. Specifically, in the case of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> compatible tokens, where balances are stored directly on-chain in plain text, the transparency of these balances can compromise the privacy of the account holder. This creates a dilemma: while the reuse of claims and attestations tied to a smart contract account can be advantageous, it also increases the risk of exposing sensitive financial information, particularly when these well-defined identities are associated with publicly visible token holdings.</p> <p>This proposal aims to conceal balances on-chain, allowing the use of smart contract accounts to hold tokens without compromising privacy or integrity.</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 concept revolves around representing token balances on-chain as hashed values, called baskets, which obscure the actual balance information. These baskets combine a random salt, a unique token ID, and the token's value, making it impossible to derive the token's value directly from the blockchain.</p> <p>The token interface allows for creating, transferring, issuing, and reorganizing (splitting and joining) these baskets. To prevent unauthorized changes and maintain integrity, oracle services verify that the total value of baskets remains consistent during reorganizations. Additionally, differential privacy techniques, such as overlaying noise and empty transfers, further protect privacy by making it difficult to trace token movements and determine actual transaction details.</p> <h3 id="baskets">Baskets</h3> <p>Balances are represented on-chain as hashes of the form:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>keccak256(abi.encode(salt, tokenId, value))</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// where salt (bytes32) - random 32bytes to increase the entropy and</span></span> <span class="giallo-l"><span>// make brute-forcing the hash impossible</span></span> <span class="giallo-l"><span>// tokenId (bytes32) - a unique tokenId within token&#39;s smart contract instance</span></span> <span class="giallo-l"><span>// value (uint256) - the value of the position</span></span></code></pre> <p>For the remainder of this document, we refer to these hashes as "baskets" because they conceal the balance information in an opaque manner, similar to how a covered basket hides its contents.</p> <h3 id="token-interface">Token Interface</h3> <p>An opaque token MUST implement the following interface.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>interface OpaqueToken {</span></span> <span class="giallo-l"><span> //</span></span> <span class="giallo-l"><span> // TYPES</span></span> <span class="giallo-l"><span> //</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> struct SIGNATURE {</span></span> <span class="giallo-l"><span> uint8 v; bytes32 r; bytes32 s;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> struct ORACLECONFIG {</span></span> <span class="giallo-l"><span> uint8 minNumberOfOracles; // min. number of oracle signatures required for reorg</span></span> <span class="giallo-l"><span> address[] oracles; // valid oracles</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> // EVENTS</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> * @dev MUST be emitted when new token is created</span></span> <span class="giallo-l"><span> * @param initiatedBy address that created and controls the token</span></span> <span class="giallo-l"><span> * @param tokenId identifier of the token</span></span> <span class="giallo-l"><span> * @param totalSupplyBasket initial supply basket, containing total supply of tokens</span></span> <span class="giallo-l"><span> * @param ref custom reference as used by initiator</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event CreateToken(address initiatedBy, bytes32 tokenId, bytes32 totalSupplyBasket, bytes32 ref);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev MUST be emitted on issuance</span></span> <span class="giallo-l"><span> * @param initiatedBy address that initiated issuance</span></span> <span class="giallo-l"><span> * @param baskets baskets that were issued to the receiver</span></span> <span class="giallo-l"><span> * @param receiver address that received baskets</span></span> <span class="giallo-l"><span> * @param ref custom reference as used by initiator</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event Issue(address initiatedBy, bytes32[] baskets, address receiver, bytes32 ref);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev MUST be emitted when holder baskets are restructured</span></span> <span class="giallo-l"><span> * @param initiatedBy address that initiated reorg and owner of all baskets</span></span> <span class="giallo-l"><span> * @param basketsIn baskets that are restructured and no longer exist</span></span> <span class="giallo-l"><span> * @param basketsOut baskets that are newly created</span></span> <span class="giallo-l"><span> * @param ref custom reference as used by initiator</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event ReorgHolderBaskets(address initiatedBy, bytes32[] basketsIn, bytes32[] basketsOut, bytes32 ref);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev MUST be emitted when supply baskets are restructured</span></span> <span class="giallo-l"><span> * @param initiatedBy address that initiated reorg</span></span> <span class="giallo-l"><span> * @param basketsIn supply baskets that are restructured and no longer exist</span></span> <span class="giallo-l"><span> * @param basketsOut supply baskets that are newly created</span></span> <span class="giallo-l"><span> * @param ref custom reference as used by initiator</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event ReorgSupplyBaskets(address initiatedBy, bytes32[] basketsIn, bytes32[] basketsOut, bytes32 ref);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev MUST be emitted when baskets are transferred from one address to another</span></span> <span class="giallo-l"><span> * @param initiatedBy address that initiated the transfer</span></span> <span class="giallo-l"><span> * @param receiver address that is the new owner of baskets</span></span> <span class="giallo-l"><span> * @param baskets baskets that were transferred</span></span> <span class="giallo-l"><span> * @param ref custom reference as used by initiator</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event Transfer(address initiatedBy, address receiver, bytes32[] baskets, bytes32 ref);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev MUST be emitted on redeem</span></span> <span class="giallo-l"><span> * @param initiatedBy address that initiated redeem</span></span> <span class="giallo-l"><span> * @param baskets baskets that were redeemed</span></span> <span class="giallo-l"><span> * @param ref custom reference as used by initiator</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event Redeem(address initiatedBy, bytes32[] baskets, bytes32 ref);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> //</span></span> <span class="giallo-l"><span> // FUNCTIONS</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> * @dev returns the configuration for this token</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function oracleConfig() external view returns (ORACLECONFIG memory);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev returns the address of the basket owner</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function owner(bytes32 basket) external view returns (address);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev returns the total supply for a `tokenId``</span></span> <span class="giallo-l"><span> * All token investors are allowed to fetch this value from the token operator&#39;s off-chain storage.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function totalSupply(bytes32 tokenId) external view returns (bytes32);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev returns the operator of this token, who is also responsible for providing the main</span></span> <span class="giallo-l"><span> * off-chain storage source.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function operator() external view returns (address);</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Allows the token operator to create a new token with the specified `tokenId` and an initial </span></span> <span class="giallo-l"><span> * `totalSupplyBasket`. The `totalSupplyBasket` can be partitioned using {reorgSupplyBaskets} as needed </span></span> <span class="giallo-l"><span> * when calling {issue}. The `ref` parameter can be used freely by the caller for any reference purpose.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function createToken(</span></span> <span class="giallo-l"><span> bytes32 tokenId,</span></span> <span class="giallo-l"><span> bytes32 totalSupplyBasket,</span></span> <span class="giallo-l"><span> bytes32 ref</span></span> <span class="giallo-l"><span> ) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Allows the token operator to issue tokens by assigning `supplyBaskets` to a `receiver` which </span></span> <span class="giallo-l"><span> * becomes the owner of these baskets. </span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function issue(</span></span> <span class="giallo-l"><span> bytes32[] calldata supplyBaskets,</span></span> <span class="giallo-l"><span> address receiver,</span></span> <span class="giallo-l"><span> bytes32 ref</span></span> <span class="giallo-l"><span> ) external;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev transfers `baskets` to a `receiver` who becomes the new owner of these baskets. </span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function transfer(</span></span> <span class="giallo-l"><span> bytes32[] calldata baskets,</span></span> <span class="giallo-l"><span> address receiver,</span></span> <span class="giallo-l"><span> bytes32 ref</span></span> <span class="giallo-l"><span> ) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev reorganizes a set of holder baskets (`basketsIn`) to a new set (`basketsOut`) having</span></span> <span class="giallo-l"><span> * the same value, i.e., the sum of all values from input baskets equals the sum of values</span></span> <span class="giallo-l"><span> * in output baskets. In order to ensure the integrity, external oracle service is required that</span></span> <span class="giallo-l"><span> * will sign the reorg proposal requested by the basket owner, which is passed as `reorgOracleSignatures`.</span></span> <span class="giallo-l"><span> * The minimum number of oracle signatures is defined in the oracle configuration.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function reorgHolderBaskets(</span></span> <span class="giallo-l"><span> SIGNATURE[] calldata reorgOracleSignatures,</span></span> <span class="giallo-l"><span> bytes32[] calldata basketsIn,</span></span> <span class="giallo-l"><span> bytes32[] calldata basketsOut,</span></span> <span class="giallo-l"><span> bytes32 ref</span></span> <span class="giallo-l"><span> ) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev same as {reorgHolderBaskets}, but for the available supply baskets.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function reorgSupplyBaskets(</span></span> <span class="giallo-l"><span> SIGNATURE[] calldata reorgOracleSignatures,</span></span> <span class="giallo-l"><span> bytes32[] calldata basketsIn,</span></span> <span class="giallo-l"><span> bytes32[] calldata basketsOut,</span></span> <span class="giallo-l"><span> bytes32 ref</span></span> <span class="giallo-l"><span> ) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev redeems holder&#39;s `baskets` and returns them to available supply</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function redeem(</span></span> <span class="giallo-l"><span> bytes32[] calldata baskets,</span></span> <span class="giallo-l"><span> bytes32 ref</span></span> <span class="giallo-l"><span> ) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="user-roles">User Roles</h3> <p>There are two roles in Opaque Token:</p> <ul> <li>Token Operator: One who creates a token and issues positions in it, and controls it's non-circulating supply (held in supply baskets). Will use createToken, reorgSupplyBasket and issue functions. Also has ability to force actions through forceTransfer and forceReorg functions.</li> <li>Token User: address that holds circulating tokens (held in owned baskets). Will use reorgSupplyBaskets, transfer and redeem functions.</li> </ul> <h3 id="off-chain-data-endpoints">Off-chain Data Endpoints</h3> <ul> <li>The operator of the token (e.g., issuer or registrar) MUST provide the off-chain storage that implements the <code>GET basket</code> and <code>PUT basket</code> REST endpoints as described in this section.</li> <li>The operator MUST ensure the availability of the basket data and will share it on need-to-know basis with all eligible holders, i.e., with all address that either were holding the basket in the past or are currently the holder of the basket.</li> <li>To ensure data is only shared with and can be written by eligible holders, the operator MUST implement authentication for both endpoints. The concrete authentication schema is not specified here and my depend on the environment of the token operator.</li> <li>The operator MUST allow an existing token holder to <code>PUT basket</code></li> <li>The operator MUST allow the current or historical basket holder to <code>GET basket</code></li> <li>Token holders SHOULD store a copy of the data about their own baskets in their own off-chain storage for the case that operator's service is unavailable.</li> </ul> <p>REST API Endpoints for creating and querying baskets:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> Endpoint: PUT baskets</span></span> <span class="giallo-l"><span> Description: will store baskets if the `basket` hash is matching `data`.</span></span> <span class="giallo-l"><span> PostData: </span></span> <span class="giallo-l"><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> basket: keccak256(abi.encode(salt, tokenId, value)),</span></span> <span class="giallo-l"><span> data: {</span></span> <span class="giallo-l"><span> salt: &lt;bytes32&gt;,</span></span> <span class="giallo-l"><span> tokenId: &lt;bytes32&gt;,</span></span> <span class="giallo-l"><span> value: &lt;uint256&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 class="giallo-l"><span> Endpoint: GET baskets?basket-hash=&lt;bytes32&gt;</span></span> <span class="giallo-l"><span> Description: will return the list of baskets depending on the query parameters.</span></span> <span class="giallo-l"><span> Query Parameters:</span></span> <span class="giallo-l"><span> - basket-hash (optional): returns one basket matching the requested hash</span></span> <span class="giallo-l"><span> - if no query parameter is set, then the endpoint will return all baskets of the requestor</span></span> <span class="giallo-l"><span> Response:</span></span> <span class="giallo-l"><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> basket: keccak256(abi.encode(salt, tokenId, value)),</span></span> <span class="giallo-l"><span> data: {</span></span> <span class="giallo-l"><span> salt: &lt;bytes32&gt;,</span></span> <span class="giallo-l"><span> tokenId: &lt;bytes32&gt;,</span></span> <span class="giallo-l"><span> value: &lt;uint256&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><h3 id="reorg-endpoint">reorg Endpoint</h3> <p>To ensure the integrity of a reorg and avoid accidental or fraudulent issues or redeems, an oracle services is required.</p> <ul> <li>Oracles MUST provide a <code>POST reorg</code> REST Endpoint as described in this section</li> <li>Oracles MUST sign any reorg proposal request where <ul> <li>the sum of values in input baskets grouped by tokenId is equal the sum of values of the output baskets grouped by tokenId.</li> <li><code>item.basket</code> hash matches <code>keccak256(abi.encode(data.salt, data.tokenId, data.value))</code></li> </ul> </li> <li>The reorg endpoint MUST be stateless</li> <li>Oracle MUST NOT persist data from the request for later analysis.</li> <li>The reorg endpoint SHOULD NOT require authentication and can be used by anyone without restrictions.</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Endpoint: POST reorg</span></span> <span class="giallo-l"><span>PostData:</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> in: [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> basket: keccak256(abi.encode(salt, tokenId, value)),</span></span> <span class="giallo-l"><span> data: {</span></span> <span class="giallo-l"><span> salt: &lt;bytes32&gt;,</span></span> <span class="giallo-l"><span> tokenId: &lt;bytes32&gt;,</span></span> <span class="giallo-l"><span> value: &lt;uint256&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> out: [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> basket: keccak256(abi.encode(salt, tokenId, value)),</span></span> <span class="giallo-l"><span> data: {</span></span> <span class="giallo-l"><span> salt: &lt;bytes32&gt;,</span></span> <span class="giallo-l"><span> tokenId: &lt;bytes32&gt;,</span></span> <span class="giallo-l"><span> value: &lt;uint256&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> <span class="giallo-l"></span> <span class="giallo-l"><span>Response: {</span></span> <span class="giallo-l"><span> // hash is signed with oracles private key</span></span> <span class="giallo-l"><span> // basketsIn and basketsIn are bytes32[]</span></span> <span class="giallo-l"><span> signature: sign(keccak256(abi.encode(basketsIn, basketsOut)))</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Example for valid reorg requests (salt and hashes are omitted for better readability):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>in : (..., token1, 10), (..., token1, 30), (..., token2, 5), (..., token2, 95)</span></span> <span class="giallo-l"><span>out: (..., token1, 40), (..., token2, 100)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>in : (..., token1, 40), (..., token2, 100)</span></span> <span class="giallo-l"><span>out: (..., token1, 10), (..., token1, 30), (..., token2, 5), (..., token2, 95)</span></span></code></pre><h3 id="overlaying-noise-differential-privacy">Overlaying Noise (Differential Privacy)</h3> <p>To further enhance privacy and obscure transaction details, an additional layer of noise need to be introduced through reorgs and empty transfers. For example, received baskets can be reorganized into new baskets to prevent information leakage to the previous owner. Additionally, null-value baskets can be sent to random receivers (empty transfers), making it difficult for observers to determine who is transferring to whom.</p> <p>Example with reorg and null-value basket transfers:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>A owns basket-a1{..., value:10}</span></span> <span class="giallo-l"><span>B owns basket-b1{..., value:5}, basket-b2{..., value:15}, ...</span></span> <span class="giallo-l"><span>A: transfer basket-a1 to B</span></span> <span class="giallo-l"><span>B: reorg [basket-a1, basket-b1, basket-b2]</span></span> <span class="giallo-l"><span> to [basket-b3{..., value:10}, basket-b4{..., value:10}, basket-b5:{..., value:10},</span></span> <span class="giallo-l"><span> basket-b6:{..., value:0}, basket-b7:{..., value:0}]</span></span> <span class="giallo-l"><span> where sum of inputs is the sum of outputs</span></span> <span class="giallo-l"><span>B: transfer basket-b5{value:10} to C</span></span> <span class="giallo-l"><span>B: transfer basket-b6{value:0} to D</span></span> <span class="giallo-l"><span>B: transfer basket-b7{value:0} to E</span></span></code></pre> <p>If B would directly send basket-a1 to C, A would know what C is receiving, however, now that B has reorg'ed the baskets, A can not know anymore what has been sent to C.</p> <p>Moreover, observers still see who is communicating with whom, but since there is noise introduced, they can not tell which of these transfers are actually transferring real values.</p> <h2 id="rationale">Rationale</h2> <h3 id="breaking-the-erc-20-compatibility">Breaking the ERC-20 Compatibility</h3> <p>The transparency inherent in ERC-20 tokens presents a significant issue for reusable blockchain identities. To address this, we prioritize privacy over ERC-20 compatibility, ensuring the confidentiality of token balances.</p> <h3 id="reorg-oracles">Reorg Oracles</h3> <p>The trusted oracles and the minimum number of required signatures can be configured to achieve the desired level of decentralization.</p> <p>The basket holder proposes the input and output baskets for the reorg, while the oracles are responsible for verifying that the sums of the values on both sides (input and output) are equal. This system allows for mutual control, ensuring that no single party can manipulate the process.</p> <p>Fraudulent oracles can be tracked back on-chain, i.e., the system ensures weak-integrity at minimum.</p> <p>To further strengthen the integrity, it would also be possible to apply Zero-Knowledge Proofs (ZKP) to provide reorg proofs, however, we have chosen to use oracles for efficiency and simplicity reasons.</p> <h3 id="off-chain-data-storage">Off-chain Data Storage</h3> <p>We have chosen the token operator, which in most cases will be the issuer or registrar, as the initial and main source for off-chain data. This is acceptable, since they must know anyway which investor holds which positions to manage lifecycle events on the token. While this approach may not be suitable for every use case within the broader Ethereum ecosystem, it fits well the financial instruments in the regulated environment of the financial industry, which rely on strict KYC and token operation procedures.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <ul> <li>Opaque Token is not compatible with ERC-20 for reasons explained in the Rationale section.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <h3 id="fraudulent-oracles">Fraudulent Oracles</h3> <!-- TODO --> <h3 id="oracles-collecting-confidential-data">Oracles Collecting Confidential Data</h3> <!-- TODO --> <h3 id="confidential-data-loss">Confidential Data Loss</h3> <!-- TODO --> <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-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jeroen Offerijnshttps://github.com/hieronx João Martinshttps://github.com/0xTimepunk https://wg-eips.ritovision.com/7741/

Set Operator via EIP-712 secp256k1 signatures

<h2 id="abstract">Abstract</h2> <p>A set of functions to enable meta-transactions and atomic interactions with contracts implementing an operator model, via signatures conforming to the <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> typed message signing specification.</p> <h2 id="motivation">Motivation</h2> <p>The primary motivation for this standard is to enhance the flexibility, security, and efficiency of operator management. By leveraging EIP-712 signatures, this standard allows users to authorize operators without the need for on-chain transactions, reducing gas costs and improving user experience. This is particularly beneficial whenever frequent operator changes and cross-chain interactions are required.</p> <p>Additionally, this standard aims to:</p> <ol> <li><strong>Enable Meta-Transactions</strong>: Allow users to delegate the execution of transactions to operators, enabling meta-transactions where the user does not need to hold native tokens to pay for gas fees on each chain.</li> <li><strong>Improve Security</strong>: Utilize the EIP-712 standard for typed data signing, which provides a more secure and user-friendly way to sign messages compared to raw data signing.</li> <li><strong>Facilitate Interoperability</strong>: Provide a standardized interface for operator management that can be adopted across various vault protocols, promoting interoperability and reducing integration complexity for developers.</li> <li><strong>Streamline Cross-Chain Operations</strong>: Simplify the process of managing operators across different chains, making it easier for protocols to maintain consistent operator permissions and interactions in a multi-chain environment.</li> </ol> <p>By addressing these needs, the <code>Authorize Operator</code> standard aims to streamline the process of managing operators in decentralized vault protocols, making it easier for users and developers to interact with smart contracts in a secure, cost-effective, and interoperable manner across multiple blockchain networks.</p> <h2 id="specification">Specification</h2> <h3 id="operator-compatible-contracts">Operator-compatible contracts</h3> <p>This signed authorization scheme applies to any contracts implementing 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"> IOperator</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> OperatorSet</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"> setOperator</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 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"> isOperator</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-keyword"> returns</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></span></code></pre> <p><a href="https://wg-eips.ritovision.com/6909/">EIP-6909</a> and <a href="https://wg-eips.ritovision.com/7540/">EIP-7540</a> already implement this interface.</p> <p>The naming of the arguments is interchangeable, e.g. <a href="https://wg-eips.ritovision.com/6909/">EIP-6909</a> uses <code>spender</code> instead of <code>operator</code>.</p> <h3 id="methods">Methods</h3> <h4 id="authorizeoperator"><code>authorizeOperator</code></h4> <p>Grants or revokes permissions for <code>operator</code> to manage Requests on behalf of the <code>msg.sender</code>, using an <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> signature.</p> <p>MUST revert if the <code>deadline</code> has passed.</p> <p>MUST invalidate the nonce of the signature to prevent message replay.</p> <p>MUST revert if the <code>signature</code> is not a valid <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> signature, with the given input parameters.</p> <p>MUST set the operator status to the <code>approved</code> value.</p> <p>MUST log the <code>OperatorSet</code> event.</p> <p>MUST return <code>true</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"> a</span><span class="z-string">uthorizeOperator</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"> 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"> o</span><span class="z-string">perator</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">pproved</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"> 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"> 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">eadline</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"> s</span><span class="z-string">ignature</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> <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">uccess</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="invalidatenonce"><code>invalidateNonce</code></h4> <p>Revokes the given <code>nonce</code> for <code>msg.sender</code> as the <code>owner</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">nvalidateNonce</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"> 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"> b</span><span class="z-string">ytes32</span></span></code></pre><h4 id="authorizations"><code>authorizations</code></h4> <p>Returns whether the given <code>nonce</code> has been used for the <code>controller</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"> a</span><span class="z-string">uthorizations</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">ontroller</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"> 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 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">sed</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="domain-separator"><code>DOMAIN_SEPARATOR</code></h4> <p>Returns the <code>DOMAIN_SEPARATOR</code> as defined according to EIP-712. 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> <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">OMAIN_SEPARATOR</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"> 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"> 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></code></pre><h3 id="erc-165-support"><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> support</h3> <p>Smart contracts implementing this standard MUST implement the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> <code>supportsInterface</code> function.</p> <p>Contracts MUST return the constant value <code>true</code> if <code>0xa9e50872</code> is passed through the <code>interfaceID</code> argument.</p> <h2 id="rationale">Rationale</h2> <h3 id="similarity-to-erc-2612">Similarity to <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a></h3> <p>The specification is intentionally designed to closely match <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a>. This should simplify new integrations of the standard.</p> <p>The main difference is using <code>bytes32</code> vs <code>uint256</code>, which enables unordered nonces.</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"> This code snippet is incomplete pseudocode used for example only and is no way intended to be used in production or guaranteed to be secure</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 class="z-storage z-type"> constant</span><span> AUTHORIZE_OPERATOR_TYPEHASH </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;AuthorizeOperator(address controller,address operator,bool approved,bytes32 nonce,uint256 deadline)&quot;</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">address</span><span> owner </span><span class="z-keyword">=&gt;</span><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes32</span><span> nonce </span><span class="z-keyword">=&gt;</span><span class="z-support"> bool</span><span> used</span><span>)</span><span>)</span><span> authorizations</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"> DOMAIN_SEPARATOR</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 class="z-comment"> //</span><span class="z-comment"> EIP-712 implementation </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"> isValidSignature</span><span>(</span><span class="z-support">address</span><span class="z-variable"> signer</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> digest</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"> 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 class="z-variable"> valid</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ERC-1271 implementation </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"> authorizeOperator</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> controller</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"> bool</span><span class="z-variable"> approved</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</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"> signature</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 class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">block</span><span>.</span><span>timestamp </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> deadline</span><span>,</span><span class="z-string"> &quot;ERC7540Vault/expired&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>controller </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;ERC7540Vault/invalid-controller&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>authorizations</span><span>[</span><span>controller</span><span>]</span><span>[</span><span>nonce</span><span>]</span><span>,</span><span class="z-string"> &quot;ERC7540Vault/authorization-used&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> authorizations</span><span>[</span><span>controller</span><span>]</span><span>[</span><span>nonce</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-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 class="z-entity z-name"> DOMAIN_SEPARATOR</span><span>(</span><span>)</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>AUTHORIZE_OPERATOR_TYPEHASH</span><span>,</span><span> controller</span><span>,</span><span> operator</span><span>,</span><span> approved</span><span>,</span><span> nonce</span><span>,</span><span> deadline</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"> require</span><span>(</span><span>SignatureLib</span><span>.</span><span class="z-entity z-name">isValidSignature</span><span>(</span><span>controller</span><span>,</span><span> digest</span><span>,</span><span> signature</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC7540Vault/invalid-authorization&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> isOperator</span><span>[</span><span>controller</span><span>]</span><span>[</span><span>operator</span><span>]</span><span class="z-keyword"> =</span><span> approved</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> OperatorSet</span><span>(</span><span>controller</span><span>,</span><span> operator</span><span>,</span><span> approved</span><span>)</span><span>;</span></span> <span class="giallo-l"></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> <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"> invalidateNonce</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> nonce</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span> authorizations</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>nonce</span><span>]</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>Operators have significant control over users and the signed message can lead to undesired outcomes. The expiration date should be set as short as feasible to reduce the chance of an unused signature leaking at a later point.</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-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 vectorizedhttps://github.com/vectorized Sihoon Leehttps://github.com/push0ebp Francisco Giordanohttps://github.com/frangio Hadrien Crouboishttps://github.com/Amxx Ernesto Garcíahttps://github.com/ernestognw Im Junohttps://github.com/junomonster howydevhttps://github.com/howydev Atarparahttps://github.com/Atarpara 0xcuriousapplehttps://github.com/0xcuriousapple https://wg-eips.ritovision.com/7739/

A defensive rehashing scheme which prevents signature replays across smart accounts and preserves the readability of the signed contents

<h2 id="abstract">Abstract</h2> <p>This proposal defines a standard to prevent signature replays across multiple smart accounts when they are owned by a single Externally Owned Account (EOA). This is achieved through a defensive rehashing scheme for <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> verification using specific nested <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> typed structures, which preserves the readability of the signed contents during wallet client signature requests.</p> <h2 id="motivation">Motivation</h2> <p>Smart accounts can verify signatures with via <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> using the <code>isValidSignature</code> function.</p> <p>A straightforward implementation as shown below, is vulnerable to signature replay attacks.</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"> This implementation is NOT safe.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> isValidSignature</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> hash</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"> signature</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-storage z-type"> view</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-support"> uint8</span><span> v </span><span class="z-keyword">=</span><span class="z-support"> uint8</span><span>(</span><span>signature</span><span>[</span><span class="z-constant">64</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><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-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>signature</span><span>,</span><span> (</span><span class="z-support">bytes32</span><span>,</span><span class="z-support"> bytes32</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Reject malleable signatures.</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-support">uint256</span><span>(</span><span>s</span><span>)</span><span class="z-keyword"> &lt;</span><span class="z-keyword">=</span><span class="z-constant"> 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> signer </span><span class="z-keyword">=</span><span class="z-support"> ecrecover</span><span>(</span><span>hash</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-comment"> //</span><span class="z-comment"> Reject failed recovery.</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-comment"> //</span><span class="z-comment"> `owner` is a storage variable containing the smart account&#39;s owner.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>signer </span><span class="z-keyword">==</span><span> owner</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 0x1626ba7e</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"> 0xffffffff</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>When multiple smart accounts are owned by a single EOA, the same signature can be replayed across the smart accounts if the <code>hash</code> does not include the smart account address.</p> <p>Unfortunately, this is the case for many popular applications (e.g. Permit2). As such, many smart account implementations perform some form of defensive rehashing. First, the smart account computes a final hash from minimally: (1) the hash, (2) its own address, (3) the chain ID. Then, the smart account verifies the final hash against the signature. Defensive rehashing can be implemented with <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>, but a straightforward implementation will make the signed contents opaque.</p> <p>This standard provides a defensive rehashing scheme that makes the signed contents visible across all wallet clients that support <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>. It is designed for minimal adoption friction. Even if wallet clients or application frontends are not updated, users can still inject client side JavaScript to enable the defensive rehashing.</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="overview">Overview</h3> <p>The following dependencies are REQUIRED:</p> <ul> <li> <p><a href="https://wg-eips.ritovision.com/712/">EIP-712</a> Typed structured data hashing and signing.<br /> Provides the relevant typed data hashing logic internally, which is required to construct the final hashes.</p> </li> <li> <p><a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> Standard Signature Validation Method for Contracts.<br /> Provides the <code>isValidSignature(bytes32 hash, bytes calldata signature)</code> function.</p> </li> <li> <p><a href="https://wg-eips.ritovision.com/5267/">ERC-5267</a> Retrieval of EIP-712 domain.<br /> Provides the <code>eip712Domain()</code> function which is required to compute the final hashes.</p> </li> </ul> <p>This standard defines the behavior of the <code>isValidSignature</code> function for <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>, which comprises of two workflows: (1) the <code>TypedDataSign</code> workflow, (2) the <code>PersonalSign</code> workflow.</p> <h3 id="typeddatasign-workflow"><code>TypedDataSign</code> workflow</h3> <p>The <code>TypedDataSign</code> workflow handles the case where the <code>hash</code> is originally computed with <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>.</p> <h4 id="typeddatasign-final-hash"><code>TypedDataSign</code> final hash</h4> <p>The final hash for the <code>TypedDataSign</code> workflow is defined as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>keccak256(\x19\x01 ‖ APP_DOMAIN_SEPARATOR ‖</span></span> <span class="giallo-l"><span> hashStruct(TypedDataSign({</span></span> <span class="giallo-l"><span> contents: hashStruct(originalStruct),</span></span> <span class="giallo-l"><span> name: eip712Domain().name,</span></span> <span class="giallo-l"><span> version: eip712Domain().version,</span></span> <span class="giallo-l"><span> chainId: eip712Domain().chainId,</span></span> <span class="giallo-l"><span> verifyingContract: eip712Domain().verifyingContract,</span></span> <span class="giallo-l"><span> salt: eip712Domain().salt</span></span> <span class="giallo-l"><span> }))</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>where <code>‖</code> denotes the concatenation operator for bytes.</p> <p>In Solidity, this can be written as:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>finalTypedDataSignHash </span><span class="z-keyword">=</span><span> </span></span> <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> hex</span><span class="z-string">&quot;1901&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Application specific domain separator. Passed via `signature`.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span>APP_DOMAIN_SEPARATOR</span><span>)</span><span>,</span></span> <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">encode</span><span>(</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Computed on-the-fly with `contentsType`, which is passed via `signature`.</span></span> <span class="giallo-l"><span> typedDataSignTypehash</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> This is the `contents` struct hash, which is passed via `signature`.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-entity z-name">hashStruct</span><span>(</span><span>originalStruct</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> `eip712Domain()` is from ERC-5267. </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-entity z-name">eip712Domain</span><span>(</span><span>)</span><span>.</span><span>name</span><span>)</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-entity z-name">eip712Domain</span><span>(</span><span>)</span><span>.</span><span>version</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>(</span><span class="z-entity z-name">eip712Domain</span><span>(</span><span>)</span><span>.</span><span>chainId</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint160</span><span>(</span><span class="z-entity z-name">eip712Domain</span><span>(</span><span>)</span><span>.</span><span>verifyingContract</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-entity z-name">eip712Domain</span><span>(</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> )</span><span>;</span></span></code></pre> <p>where <code>typedDataSignTypehash</code> is:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>typedDataSignTypehash </span><span class="z-keyword">=</span><span> </span></span> <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-string"> &quot;TypedDataSign(&quot;</span><span>,</span></span> <span class="giallo-l"><span> contentsName</span><span>,</span><span class="z-string"> &quot; contents,&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;string name,&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;string version,&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;uint256 chainId,&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;address verifyingContract,&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;bytes32 salt&quot;</span></span> <span class="giallo-l"><span class="z-string"> &quot;)&quot;</span><span>,</span></span> <span class="giallo-l"><span> contentsType</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> )</span><span>;</span></span></code></pre> <p>If <code>contentsType</code> is <code>"Mail(address from,address to,string message)"</code>, then <code>contentsName</code> will be <code>"Mail"</code>.</p> <p>The <code>contentsName</code> is the substring of <code>contentsType</code> up to (excluding) the first instance of <code>"("</code>:</p> <p>In Solidity, this can be written as:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> `slice(string memory subject, uint256 start, uint256 end)` </span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> returns a copy of `subject` sliced from `start` to `end` (exclusive).</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> `start` and `end` are byte offsets.</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"> `indexOf(string memory subject, string memory search)`</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Returns the byte index of the first location of `search` in `subject`,</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> searching from left to right. Returns `2**256 - 1` if `search` is not found.</span></span> <span class="giallo-l"><span>contentsName </span><span class="z-keyword">=</span><span> </span></span> <span class="giallo-l"><span> LibString</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span></span> <span class="giallo-l"><span> contentsType</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 0</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Start byte index.</span></span> <span class="giallo-l"><span> LibString</span><span>.</span><span class="z-entity z-name">indexOf</span><span>(</span><span>contentsType</span><span>,</span><span class="z-string"> &quot;(&quot;</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> End byte index (exclusive).</span></span> <span class="giallo-l"><span> )</span><span>;</span></span></code></pre> <p><a href="https://wg-eips.ritovision.com/7739/./assets/contracts/utils/LibString.sol">A copy of the <code>LibString</code> Solidity library is provided for completeness</a>.</p> <p>For safety, it is RECOMMENDED to treat the signature as invalid if any of the following is true:</p> <ul> <li><code>contentsName</code> is the empty string (i.e. <code>bytes(contentsName).length == 0</code>).</li> <li><code>contentsName</code> starts with any of the following bytes <code>abcdefghijklmnopqrstuvwxyz(</code>.</li> <li><code>contentsName</code> contains any of the following bytes <code>, )\x00</code>.</li> </ul> <h4 id="typeddatasign-signature"><code>TypedDataSign</code> signature</h4> <p>The <code>signature</code> passed into <code>isValidSignature</code> will be changed to:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>originalSignature ‖ APP_DOMAIN_SEPARATOR ‖ contents ‖ contentsDescription ‖ uint16(contentsDescription.length)</span></span></code></pre> <p>where:</p> <ul> <li><code>contents</code> is the bytes32 struct hash of the original struct.</li> <li><code>contentsDescription</code> is either: <ul> <li><code>contentsType</code> (implicit mode),<br /> where <code>contentsType</code> starts with <code>contentsName</code>.</li> <li><code>contentsType ‖ contentsName</code> (explicit mode),<br /> where <code>contentsType</code> may not necessarily start with <code>contentsName</code>.</li> </ul> </li> </ul> <p>In Solidity, this can be written as:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>signature </span><span class="z-keyword">=</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-support"> bytes</span><span>(</span><span>originalSignature</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span>APP_DOMAIN_SEPARATOR</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span>contents</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>(</span><span>contentsDescription</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint16</span><span>(</span><span>contentsDescription</span><span>.</span><span>length</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>;</span></span></code></pre> <p>The appended <code>APP_DOMAIN_SEPARATOR</code> and <code>contents</code> struct hash will be used to verify if the <code>hash</code> passed into <code>isValidSignature</code> is indeed correct via:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>hash </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> hex</span><span class="z-string">&quot;1901&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span>APP_DOMAIN_SEPARATOR</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span>contents</span><span>)</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>If the <code>hash</code> does not match the reconstructed hash, then the <code>hash</code> and <code>signature</code> are invalid under the <code>TypedDataSign</code> workflow.</p> <h3 id="personalsign-workflow"><code>PersonalSign</code> workflow</h3> <p>This <code>PersonalSign</code> workflow handles the case where the <code>hash</code> is originally computed with <a href="https://wg-eips.ritovision.com/191/">EIP-191</a>.</p> <h4 id="personalsign-final-hash"><code>PersonalSign</code> final hash</h4> <p>The final hash for the <code>PersonalSign</code> workflow is defined as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>keccak256(\x19\x01 ‖ ACCOUNT_DOMAIN_SEPARATOR ‖</span></span> <span class="giallo-l"><span> hashStruct(PersonalSign({</span></span> <span class="giallo-l"><span> prefixed: keccak256(bytes(\x19Ethereum Signed Message:\n ‖</span></span> <span class="giallo-l"><span> base10(bytes(someString).length) ‖ someString))</span></span> <span class="giallo-l"><span> }))</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>where <code>‖</code> denotes the concatenation operator for bytes.</p> <p>In Solidity, this can be written as:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>finalPersonalSignHash </span><span class="z-keyword">=</span><span> </span></span> <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> hex</span><span class="z-string">&quot;1901&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Smart account domain separator.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Can be computed via `eip712Domain()` from ERC-5267.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span>ACCOUNT_DOMAIN_SEPARATOR</span><span>)</span><span>,</span></span> <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">encode</span><span>(</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> `PERSONAL_SIGN_TYPEHASH`.</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;PersonalSign(bytes prefixed)&quot;</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> `hash` is from `isValidSignature(hash, signature)`</span></span> <span class="giallo-l"><span> hash</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></code></pre> <p>Here, <code>hash</code> is computed in the application contract and passed into <code>isValidSignature</code>.</p> <p>The smart account does not need to know how <code>hash</code> is computed. For completeness, this is how it can be computed:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>hash </span><span class="z-keyword">=</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;\x19Ethereum Signed Message:\n&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> `toString` returns the base10 representation of a uint256.</span></span> <span class="giallo-l"><span> LibString</span><span>.</span><span class="z-entity z-name">toString</span><span>(</span><span>someString</span><span>.</span><span>length</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> This is the original message to be signed.</span></span> <span class="giallo-l"><span> someString</span></span> <span class="giallo-l"><span> )</span><span>;</span></span></code></pre><h4 id="personalsign-signature"><code>PersonalSign</code> signature</h4> <p>The <code>PersonalSign</code> workflow does not require additional data to be appended to the <code>signature</code> passed into <code>isValidSignature</code>.</p> <h3 id="support-detection">Support detection</h3> <p>Smart accounts SHOULD return <code>bytes4(0x77390001)</code> for <code>isValidSignature(0x7739773977397739773977397739773977397739773977397739773977397739, "")</code> to indicate support for this standard.</p> <p>The magic number <code>bytes4(0x77390001)</code> MAY be incremented if this standard gets updated.</p> <h3 id="signature-verification-workflow-deduction">Signature verification workflow deduction</h3> <p>As the <code>isValidSignature</code> signature function signature is unchanged, the implementation MUST be able to deduce the type of workflow required to verify the signature.</p> <p>If the signature contains the correct data to reconstruct the <code>hash</code>, the <code>isValidSignature</code> function MUST perform the <code>TypedDataSign</code> workflow. Otherwise, the <code>isValidSignature</code> function MUST perform the <code>PersonalSign</code> workflow.</p> <p>In Solidity, the check can be written as:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> If this is true, it means that the `signature` contains </span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> the correct `APP_DOMAIN_SEPARATOR` and `contents`,</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> and the `TypedDataSign` workflow MUST be performed.</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Otherwise, the `PersonalSign` workflow MUST be performed.</span></span> <span class="giallo-l"><span>hash </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> hex</span><span class="z-string">&quot;1901&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span>APP_DOMAIN_SEPARATOR</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span>contents</span><span>)</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span>)</span></span></code></pre><h3 id="conditional-skipping-of-defensive-rehashing">Conditional skipping of defensive rehashing</h3> <p>Smart accounts MAY skip the defensive rehashing workflows if any of the following is true:</p> <ul> <li><code>isValidSignature</code> is called off-chain.</li> <li>The <code>hash</code> passed into <code>isValidSignature</code> has already included the address of the smart account.</li> </ul> <p>As many developers may not update their applications to support the nested EIP-712 workflow, smart account implementations SHOULD try to accommodate by skipping the defensive rehashing where it is safe to do so.</p> <h2 id="rationale">Rationale</h2> <h3 id="typeddatasign-structure"><code>TypedDataSign</code> structure</h3> <p>The <code>typedDataSignTypehash</code> must be constructed on-the-fly on-chain. This is to enforce that the signed contents will be visible in the signature request, by requiring that <code>contents</code> be a user defined type.</p> <p>The fields of <code>eip712Domain</code> are flattened into the <code>TypedDataSign</code> structure instead of being included as a field of type <code>EIP712Domain</code> in order to avoid a conflict with the domain type of the verifying contract in case it's different.</p> <p>The <code>bytes1 fields</code> bitmap and <code>uint256[] extensions</code> array in <a href="https://wg-eips.ritovision.com/5267/">ERC-5267</a> have been omitted. Differentiating between an absent field versus a zero field (e.g. <code>bytes32(0)</code>) offers no additional security benefits for on-chain defensive rehashing. The <code>extensions</code> parameter is a list of EIP numbers used for off-chain signaling.</p> <h3 id="contentsdescription-with-implicit-and-explicit-modes"><code>contentsDescription</code> with implicit and explicit modes</h3> <p>When the <code>contents</code> structure contains nested types, EIP-712 lexicographical sorting can result in the <code>contentsName</code> not being positioned exactly at the start of the <code>contentsType</code>. As such, we need the explicit mode.</p> <h3 id="support-detection-with-isvalidsignature">Support detection with <code>isValidSignature</code></h3> <p>For easier implementation in modular smart accounts, we have decided to utilize the <code>isValidSignature</code> method to return a magic number instead of defining new functions.</p> <h3 id="rejecting-contentsname-beginning-with-any-lowercase-7-bit-ascii-character">Rejecting <code>contentsName</code> beginning with any lowercase 7-bit ASCII character</h3> <p>This recommendation is to keep the standard language agnostic and future-proof. Atomic types such as <code>uint256</code> may be named differently in other languages (e.g. <code>u256</code>).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <h3 id="detection-of-previous-draft">Detection of previous draft</h3> <p>In an earlier draft, we have designated a <code>supportsNestedTypedDataSign()</code> function for support detection, which returns <code>bytes4(0xd620c85a)</code>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p><a href="https://wg-eips.ritovision.com/7739/./assets/contracts/accounts/ERC1271.sol">A production ready and optimized implementation is provided for reference</a>.</p> <p>It includes relevant complementary features required for safety, flexibility, developer experience, and user experience.</p> <p>The reference implementation is intentionally not minimalistic. This is to avoid repeating the mistake of <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>, where a minimalist reference implementation is wrongly assumed to be safe for production use.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="rejecting-invalid-contentsname">Rejecting invalid <code>contentsName</code></h3> <p>Current major implementations of <code>eth_signTypedData</code> do not sanitize the names of custom types.</p> <p>A phishing website can craft a <code>contentsName</code> with control characters to break out of the <code>PersonalSign</code> type encoding, resulting in the wallet client asking the user to sign an opaque hash.</p> <p>Requiring on-chain sanitization of <code>contentsName</code> will block this phishing attack vector.</p> <h3 id="impossible-to-chain-multiple-signers-of-this-kind">Impossible to chain multiple signers of this kind</h3> <p>An account that uses this method as replay protection for ERC-1271 signatures cannot have a signer that uses the same method. This is because a signature defines a <code>TypedDataSign</code> struct type with a member that has the type of the message being signed, and if the message being signed is another <code>TypedDataSign</code> struct, the resulting EIP-712 message will contain in its body two separate <code>TypedDataSign</code> types with incompatible contents, something that can't be represented in an EIP-712 request.</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-24T00:00:00+00:00 2026-02-11T14:48:25+00:00 Luka Isailovichttps://github.com/lukaisailovic Derek Reinhttps://github.com/arein Dan Finlayhttps://github.com/danfinlay Derek Chianghttps://github.com/derekchiang Fil Makarovhttps://github.com/filmakarov Pedro Gomeshttps://github.com/pedrouid Conner Swenberghttps://github.com/ilikesymmetry Lukas Rosariohttps://github.com/lukasrosario Idris Bowmanhttps://github.com/V00D00-child Jeff Smalehttps://github.com/jeffsmale90 https://wg-eips.ritovision.com/7715/

Adds JSON-RPC method for requesting permissions from a wallet

<h2 id="abstract">Abstract</h2> <p>We define a new JSON-RPC method <code>wallet_requestExecutionPermissions</code> for DApp to request a Wallet to grant permissions in order to execute transactions on the user’s behalf. This enables two use cases:</p> <ul> <li>Executing transactions for users without a wallet connection.</li> <li>Executing transactions for users with a wallet connection that is scoped with permissions.</li> </ul> <h2 id="motivation">Motivation</h2> <p>Currently most DApps implement a flow similar to the following:</p> <p><img src="https://wg-eips.ritovision.com/7715/./assets/approve-flow.svg" alt="Wallet Approve Flow" /></p> <p>Each interaction requires the user to sign a transaction with their wallet. The problems are:</p> <ul> <li>It can get tedious for the user to manually approve every transaction, especially in highly-interactive applications such as games.</li> <li>It’s impossible to send transactions for users without an active wallet connection. This invalidates use cases such as subscriptions, passive investments, limit orders, and more.</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="permission-types-rule-types">Permission Types, Rule Types</h3> <p>This ERC does not specify an exhaustive list of rule or permission types, since we expect more rule and permission types to be developed as wallets get more advanced. A permission type, or rule type is valid as long as both the DApp and the wallet are willing to support it.</p> <p>However, if two permissions or two rules share the same type name, a DApp could request with one type of permission, or rule while the wallet grants another. Therefore, it’s important that no two permissions, or two rules share the same type. Furthermore, new permission types or rule types should be specified in addition ERCs. In all cases, these new types MUST inherit from the <code>BasePermission</code> or <code>BaseRule</code> scheme.</p> <h4 id="permissions">Permissions</h4> <p><code>isAdjustmentAllowed</code> defines a boolean value that allows DApp to define whether the Wallet MAY attenuate(reduce or increase) the authority of a "permission" to meet the user’s terms for approval.</p> <p><em>For example, a DApp may require an allowance for a specific asset to complete a payment and does not want the user to adjust the requested allowance.</em></p> <pre class="giallo z-code"><code data-lang="tsx"><span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> BasePermission</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> enum defined by ERCs</span></span> <span class="giallo-l"><span class="z-variable"> isAdjustmentAllowed</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> whether the wallet MAY attenuate the permission</span></span> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> specific to the type, structure defined by ERCs</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h4 id="rules">Rules</h4> <pre class="giallo z-code"><code data-lang="tsx"><span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> BaseRule</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> enum defined by ERCs</span></span> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> specific to the type, structure defined by ERCs</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"> Constrains a permission so that it is only valid until a specified timestamp.</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> ExpiryRule</span><span class="z-keyword"> =</span><span class="z-entity z-name"> BaseRule</span><span class="z-keyword"> &amp;</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</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-variable"> data</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> timestamp</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> unix timestamp at which the permission becomes invalid</span></span> <span class="giallo-l"><span> }</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h3 id="wallet-requestexecutionpermissions"><code>wallet_requestExecutionPermissions</code></h3> <p>We introduce a <code>wallet_requestExecutionPermissions</code> method for the DApp to request the Wallet to grant permissions.</p> <h4 id="request-specification">Request Specification</h4> <pre class="giallo z-code"><code data-lang="tsx"><span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> PermissionRequest</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> chainId</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> hex-encoding of uint256</span></span> <span class="giallo-l"><span class="z-variable"> from</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-entity z-name"> Address</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> to</span><span class="z-keyword">:</span><span class="z-entity z-name"> Address</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> permission</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> enum defined by ERCs</span></span> <span class="giallo-l"><span class="z-variable"> isAdjustmentAllowed</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> whether the permission can be adjusted</span></span> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">specific to the type, structure defined by ERCs</span></span> <span class="giallo-l"><span> }</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> rules</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> enum defined by ERCs</span></span> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> specific to the type, structure defined by ERCs</span></span> <span class="giallo-l"><span> }</span><span>[</span><span>]</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>[</span><span>]</span><span>;</span></span></code></pre> <p><code>chainId</code> defines the chain with <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> which applies to this permission request and all addresses can be found defined by other parameters.</p> <p><code>from</code> identifies the account being targeted for this permission request which is useful when a connection has been established and multiple accounts have been exposed. It is optional to let the user choose which account to grant permission for.</p> <p><code>to</code> is a field that identifies the DApp session account associated with the permission</p> <p><code>permission</code> defines the allowed behavior the <code>to</code> account can do on behalf of the <code>from</code> account. See the “Permission” section for details.</p> <p><code>rules</code> define the restrictions or conditions that a <code>to</code> account MUST abide by when using a permission to act on behalf of an account. See the “Rule” section for details.</p> <p><strong>Request example</strong>:</p> <p>An array of <code>PermissionRequest</code> objects is the final <code>params</code> field expected by the <code>wallet_requestExecutionPermissions</code> RPC.</p> <pre class="giallo z-code"><code data-lang="tsx"><span class="giallo-l"><span>[</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> chainId</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> from</span><span>:</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></span> <span class="giallo-l"><span> to</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x016562aA41A8697720ce0943F003141f5dEAe006</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> permission</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">native-token-allowance</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> isAdjustmentAllowed</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> allowance</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1DCD6500</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> }</span><span>,</span></span> <span class="giallo-l"><span> rules</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> type</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> data</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> timestamp</span><span>:</span><span class="z-constant"> 1577840461</span><span>,</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> ]</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span>]</span><span>;</span></span></code></pre><h4 id="response-specification">Response Specification</h4> <pre class="giallo z-code"><code data-lang="tsx"><span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> PermissionResponse</span><span class="z-keyword"> =</span><span class="z-entity z-name"> PermissionRequest</span><span class="z-keyword"> &amp;</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> context</span><span class="z-keyword">:</span><span class="z-entity z-name"> Hex</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> dependencies</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> factory</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> <span class="giallo-l"><span class="z-variable"> factoryData</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> <span class="giallo-l"><span> }</span><span>[</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> delegationManager</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> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p>First note that the response contains all of the parameters of the original request and it is not guaranteed that the values received are equivalent to those requested.</p> <p><code>context</code> is a catch-all to identify a permission for revoking permissions or redeeming permissions, and can contain non-identifying data as well. The <code>context</code> is required as defined in <a href="https://wg-eips.ritovision.com/7710/">ERC-7710</a>. See “Rationale” for details.</p> <p><code>dependencies</code> is an array of objects, each containing fields for <code>factory</code> and <code>factoryData</code> as defined in <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a>. Either both <code>factory</code> and <code>factoryData</code> must be specified in an entry, or neither. This array is used describe accounts that are not yet deployed but MUST be deployed in order for a permission to be successfully redeemed. If any of the involved accounts have not yet been deployed, the wallet MUST return the corresponding <code>dependencies</code>. If all accounts have already been deployed, the wallet MUST return an empty <code>dependencies</code> array. The DApp MUST deploy each account by calling the <code>factory</code> contract with <code>factoryData</code> as the calldata.</p> <p><code>delegationManager</code> is required as defined in <a href="https://wg-eips.ritovision.com/7710/">ERC-7710</a>.</p> <p>If the request is malformed or the wallet is unable/unwilling to grant permissions, wallet MUST return an error with a code as defined in <a href="https://wg-eips.ritovision.com/1193/">ERC-1193</a>.</p> <p><code>wallet_requestExecutionPermissions</code> response example:</p> <p>An array of <code>PermissionResponse</code> objects is the final <code>result</code> field expected by the <code>wallet_requestExecutionPermissions</code> RPC.</p> <pre class="giallo z-code"><code data-lang="tsx"><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"> original request with modifications</span></span> <span class="giallo-l"><span> chainId</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> from</span><span>:</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></span> <span class="giallo-l"><span> to</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x016562aA41A8697720ce0943F003141f5dEAe006</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> permission</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">native-token-allowance</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> isAdjustmentAllowed</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> allowance</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1DCD65000000</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> }</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> response-specific fields</span></span> <span class="giallo-l"><span> context</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0x016562aA41A8697720ce0943F003141f5dEAe0060000771577157715</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> dependencies</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> factory</span><span>:</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></span> <span class="giallo-l"><span> factoryData</span><span>:</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></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span> delegationManager</span><span>:</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></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span>]</span><span>;</span></span></code></pre><h3 id="wallet-revokeexecutionpermission"><code>wallet_revokeExecutionPermission</code></h3> <p>Permissions can be revoked by calling this method and the wallet will respond with an empty response when successful.</p> <h4 id="request-specification-1">Request Specification</h4> <pre class="giallo z-code"><code data-lang="tsx"><span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> RevokeExecutionPermissionRequestParams</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> permissionContext</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x{string}</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h4 id="response-specification-1">Response Specification</h4> <pre class="giallo z-code"><code data-lang="tsx"><span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> GetPermissionsInfoResultParams</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> chainIds</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>]</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h3 id="wallet-getsupportedexecutionpermissions"><code>wallet_getSupportedExecutionPermissions</code></h3> <p>We introduce a <code>wallet_getSupportedExecutionPermissions</code> method for the Wallet to specify the permission types and rules types it supports.</p> <h4 id="request-specification-2">Request Specification</h4> <p><strong>Request example</strong>:</p> <pre class="giallo z-code"><code data-lang="tsx"><span class="giallo-l"><span class="z-variable z-other">window</span><span>.</span><span class="z-variable z-other">ethereum</span><span>.</span><span class="z-entity z-name">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><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>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">wallet_getSupportedExecutionPermissions</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><span> [</span><span>]</span></span> <span class="giallo-l"><span>}</span><span>)</span><span>: </span><span class="z-support">Promise</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">GetSupportedExecutionPermissionsResult</span><span class="z-keyword">&gt;</span></span></code></pre><h4 id="response-specification-2">Response Specification</h4> <p>The wallet SHOULD include an object keyed on supported permission types including <code>ruleTypes</code> (<code>string[]</code>) that can be applied to the permission.</p> <pre class="giallo z-code"><code data-lang="tsx"><span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> GetSupportedExecutionPermissionsResult</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Record</span><span>&lt;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">permission-type</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"> chainIds</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>]</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> ruleTypes</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> <span class="giallo-l"><span>&gt;</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex chain id</span></span></code></pre> <p>An object keyed on all permission types supported by the Wallet expected by the <code>wallet_getSupportedExecutionPermissions</code> RPC.</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">native-token-allowance</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">chainIds</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">0x123</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">0x345</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">rulesTypes</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">expiry</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">erc20-token-allowance</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">chainIds</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">0x123</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">rulesTypes</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">erc721-token-allowance</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">chainIds</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">0x123</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">rulesTypes</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">expiry</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><h3 id="wallet-getgrantedexecutionpermissions"><code>wallet_getGrantedExecutionPermissions</code></h3> <p>We introduce a <code>wallet_getGrantedExecutionPermissions</code> method for the DApp to retrieve previously granted permissions.</p> <h4 id="request-specification-3">Request Specification</h4> <p><strong>Request example</strong>:</p> <pre class="giallo z-code"><code data-lang="tsx"><span class="giallo-l"><span class="z-variable z-other">window</span><span>.</span><span class="z-variable z-other">ethereum</span><span>.</span><span class="z-entity z-name">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><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>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">wallet_getGrantedExecutionPermissions</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><span> [</span><span>]</span></span> <span class="giallo-l"><span>}</span><span>)</span><span>: </span><span class="z-support">Promise</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">PermissionResponses</span><span>[</span><span>]</span><span class="z-keyword">&gt;</span></span></code></pre><h4 id="response-specification-3">Response Specification</h4> <p>The wallet MUST include all granted permissions that are not yet revoked.</p> <pre class="giallo z-code"><code data-lang="tsx"><span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> PermissionResponses</span><span>;</span></span></code></pre> <p>Example:</p> <pre class="giallo z-code"><code data-lang="tsx"><span class="giallo-l"><span>[</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> chainId</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> from</span><span>:</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></span> <span class="giallo-l"><span> to</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x016562aA41A8697720ce0943F003141f5dEAe006</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> permission</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">native-token-allowance</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> isAdjustmentAllowed</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> allowance</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1DCD65000000</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> }</span><span>,</span></span> <span class="giallo-l"><span> context</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0x016562aA41A8697720ce0943F003141f5dEAe0060000771577157715</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> dependencies</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> factory</span><span>:</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></span> <span class="giallo-l"><span> factoryData</span><span>:</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></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span> delegationManager</span><span>:</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></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span>]</span><span>;</span></span></code></pre><h3 id="sending-transaction-to-redeem-permissions">Sending transaction to redeem permissions</h3> <p>The permission response data will be redeemable by the <code>account</code> defined in the <code>to</code> field, using the interfaces specified in ERC-7710. This allows the recipient of the permissions to use any account type (EOA or contract) to form a transaction or UserOp using whatever payment or relay infrastructure they prefer, by sending an internal message to the returned <code>permissions.delegationManager</code> and calling its <code>function redeemDelegation(bytes[] calldata _permissionContexts, bytes32[] calldata _modes, bytes[] calldata _executionCallData) external;</code> function with the <code>_permissionContexts</code> parameter set to the returned <code>permissions.context</code>, and the <code>_executionCallData</code> data forming the message that the permissions recipient desires the user's account to emit, as defined by this struct:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>struct Execution {</span></span> <span class="giallo-l"><span> address target;</span></span> <span class="giallo-l"><span> uint256 value;</span></span> <span class="giallo-l"><span> bytes callData;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>A simple pseudocode example of using a permission in this way, where DApp wants to request a permission from <code>bob</code> might be like this:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Alice requests a permission from Bob</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> permissionsResponse</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> window</span><span>.</span><span class="z-variable z-other">ethereum</span><span>.</span><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">wallet_requestExecutionPermissions</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></span> <span class="giallo-l"><span> from</span><span>:</span><span class="z-variable z-other"> bob</span><span>.</span><span class="z-variable z-other">address</span><span>,</span></span> <span class="giallo-l"><span> chainId</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> to</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x_dapp_session_account</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> permission</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">native-token-allowance</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> isAdjustmentAllowed</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> allowance</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x0DE0B6B3A7640000</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> <span class="giallo-l"><span> rules</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">expiry</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>{</span></span> <span class="giallo-l"><span> timestamp</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">Date</span><span>.</span><span class="z-entity z-name">now</span><span>(</span><span>)</span><span class="z-keyword"> /</span><span class="z-constant"> 1000</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> 3600</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 1 hour from now</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> ]</span><span>,</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 class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Extract the permissionsContext and delegationManager</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> permissionsContext</span><span class="z-keyword"> =</span><span class="z-variable z-other"> permissionsResponse</span><span>.</span><span class="z-variable z-other">context</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> delegationManager</span><span class="z-keyword"> =</span><span class="z-variable z-other"> permissionsResponse</span><span>.</span><span class="z-variable z-other">delegationManager</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"> DApp forms the execution they want Bob&#39;s account to take</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> execution</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span> target</span><span>:</span><span class="z-variable z-other"> bob</span><span>.</span><span class="z-variable z-other">address</span><span>,</span></span> <span class="giallo-l"><span> value</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x06F05B59D3B20000</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> callData</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 class="giallo-l"><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"> encodedExecutionCalldata</span><span class="z-keyword"> =</span><span class="z-entity z-name"> encodePacked</span><span>(</span></span> <span class="giallo-l"><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 class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">uint256</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">bytes</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-variable z-other">execution</span><span>.</span><span class="z-variable z-other">target</span><span>,</span><span class="z-variable z-other"> execution</span><span>.</span><span class="z-variable z-other">value</span><span>,</span><span class="z-variable z-other"> execution</span><span>.</span><span class="z-variable z-other">callData</span><span>]</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-punctuation z-definition z-comment">//</span><span class="z-comment"> Chose execution mode (SingleDefault)</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> executionMode</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> DApp sends the transaction by calling redeemDelegation on with encode execution on Bob&#39;s account</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> tx</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> dapp</span><span>.</span><span class="z-entity z-name">sendTransaction</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> to</span><span>:</span><span class="z-variable z-other"> delegationManager</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span class="z-entity z-name"> encodeFunctionData</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> abi</span><span>:</span><span class="z-variable z-other"> DelegationManager</span><span>.</span><span class="z-variable z-other">abi</span><span>,</span></span> <span class="giallo-l"><span> functionName</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">redeemDelegations</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> args</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> [</span><span class="z-variable z-other">permissionsContext</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-variable z-other">executionMode</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-variable z-other">encodedExecutionCalldata</span><span>]</span><span>,</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>}</span><span>)</span><span>;</span></span> <span class="giallo-l"></span></code></pre> <p><strong>Example of the entire flow:</strong></p> <pre class="giallo z-code"><code data-lang="mermaid"><span class="giallo-l"><span>sequenceDiagram</span></span> <span class="giallo-l"><span> participant DApp</span></span> <span class="giallo-l"><span> participant Provider as window.ethereum</span></span> <span class="giallo-l"><span> participant Wallet</span></span> <span class="giallo-l"><span> participant User</span></span> <span class="giallo-l"><span> participant Chain as Relay infrastructure</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span> Note over DApp: DApp discovers supported permission and rules types</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> DApp-&gt;&gt;Provider: request({method: &quot;wallet_getSupportedExecutionPermissions&quot;, params: []})</span></span> <span class="giallo-l"><span> Provider-&gt;&gt;Wallet: wallet_getSupportedExecutionPermissions</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> Wallet-&gt;&gt;DApp: Returns supported permission and rules types</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> Note over DApp: DApp triggers permissions request</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> DApp-&gt;&gt;Provider: request({method: &quot;wallet_requestExecutionPermissions&quot;, params: [ PermissionRequest[] ]})</span></span> <span class="giallo-l"><span> Provider-&gt;&gt;Wallet: wallet_requestExecutionPermissions</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> Wallet-&gt;&gt;User: Display permission request&lt;br/&gt; (permissions, rules, to = account)</span></span> <span class="giallo-l"><span> User--&gt;&gt;Wallet: Approve or reject</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> Wallet--&gt;&gt;Provider: PermissionResponse[]&lt;br/&gt;includes context,&lt;br/&gt;delegationManager,&lt;br/&gt;dependencies</span></span> <span class="giallo-l"><span> Provider--&gt;&gt;DApp: PermissionResponse[]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> alt Undeployed user account(s)</span></span> <span class="giallo-l"><span> DApp-&gt;&gt;Chain: Deploy via factory using dependencies</span></span> <span class="giallo-l"><span> Chain--&gt;&gt;DApp: Deployment success</span></span> <span class="giallo-l"><span> end</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> Note over DApp: DApp forms Action calldata&lt;br/&gt;to be executed by user&#39;s account</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> DApp-&gt;&gt;Chain: sendTransaction({&lt;br/&gt; to: delegationManager,&lt;br/&gt; data: redeemDelegations([context], [executionMode], [encodedAction])&lt;br/&gt;})</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> Chain--&gt;&gt;DApp: tx receipt</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The typical transaction flow of <code>suggesting transactions =&gt; approving transactions =&gt; sending transactions</code> is deeply limiting in several ways:</p> <ul> <li> <p>Users must be online to send transactions. DApps cannot send transactions for users when they are offline, which makes use cases such as subscriptions or automated trading impossible.</p> </li> <li> <p>Users must manually approve every transaction, interrupting what could otherwise be a smooth user experience.</p> </li> </ul> <p>With this ERC, DApps can request Wallets to grant permissions and execute transactions on the user's behalf, therefore circumventing the issues above.</p> <h3 id="permissionscontext"><code>permissionsContext</code></h3> <p>Since this ERC only specifies the interaction between the wallet and the DApp but not how the wallet enforces permissions, we need a flexible way for the wallet to pass along information to the DApp so that it can construct transactions that imbue the permissions.</p> <p>The <code>permissionsContext</code> field is meant to be an opaque string that's maximally flexible and can encode arbitrary information for different permissions schemes.</p> <p>DApps must submit transactions with the <code>account</code> specified in the <code>to</code> field, using the <code>permissionsContext</code> as the <code>_data</code> when interacting with the delegation manager.</p> <h3 id="non-exhaustive-list-of-permissions-and-rules">Non-exhaustive list of permissions and rules</h3> <p>With the advancement in wallet technologies, we expect new types of permissions and rules to be developed. We considered mandating that each permission and rule must have a UUID in order to avoid collisions, but ultimately decided to stick with the simpler approach for now of simply mandating that these types be defined in ERCs.</p> <h2 id="backwards-compatibility"><strong>Backwards Compatibility</strong></h2> <p>Wallets that don’t support <code>wallet_requestExecutionPermissions</code> SHOULD return an error message if the JSON-RPC method is called.</p> <h2 id="reference-implementation"><strong>Reference Implementation</strong></h2> <p>For a minimal reference implementation focusing on permission granting from a <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a> Ethereum provider, please see <a href="https://wg-eips.ritovision.com/7715/./assets/Example7715PermissionsRequestHandler.html">Example7715PermissionsRequestHandler</a>.</p> <p>For a complete reference implementation of a Permissions handler, see the MetaMask Permissions Snap, which includes features such as:</p> <ul> <li>Support for commonly used permission and rule types with ability to attenuate(reduce or increase) the requested capability to meet the user’s terms for approval.</li> <li>User encrypted storage for all permissions granted through the Wallet handler to enable revocation mechanisms.</li> </ul> <h2 id="security-considerations"><strong>Security Considerations</strong></h2> <h3 id="limited-permission-scope"><strong>Limited Permission Scope</strong></h3> <p>DApps should only request the permissions they need, with a reasonable expiration time.</p> <p>Wallets MUST correctly enforce permissions. Ultimately, users must trust that their wallet software is implemented correctly, and permissions should be considered a part of the wallet implementation.</p> <h3 id="phishing-attacks"><strong>Phishing Attacks</strong></h3> <p>Malicious DApps could pose as legitimate applications and trick users into granting broad permissions. Wallets MUST clearly display the permissions to users and warn them against granting dangerous permissions.</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-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ryan McPeckhttps://github.com/McOso Dan Finlayhttps://github.com/DanFinlay Rob Dawsonhttps://github.com/rojotek Derek Chianghttps://github.com/derekchiang https://wg-eips.ritovision.com/7710/

Interfaces for consistently delegating capabilities to other contracts or EOAs.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a standard way for smart contracts to delegate capabilities to other smart contracts or Externally Owned Accounts (EOAs). The delegating contract (delegator) must be able to authorize a <code>DelegationManager</code> contract to call the delegator to execute the desired action.</p> <p>This framework empowers a delegating contract with the ability to delegate any actions it has the authority to perform, thereby enabling more flexible and scalable contract interactions. This standard outlines the minimal interface necessary to facilitate such delegation.</p> <p>Additionally, this proposal is compatible with <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a>, although its implementation does not necessitate <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a>.</p> <h2 id="motivation">Motivation</h2> <p>The development of smart contracts on Ethereum has led to a diverse array of decentralized applications (dApps) that leverage composability to interact with one another in innovative ways. While current smart contracts are indeed capable of working together, enabling these interactions, especially in the realm of sharing capabilities or permissions, remains a tedious and often gas-expensive process, which lacks backwards compatibility.</p> <p>Currently, for a smart contract to interact with or utilize the functionality of another, it typically requires hardcoded permissions or the development of bespoke, intermediary contracts. This not only increases the complexity and development time but also results in higher deployment and execution gas costs. Moreover, the rigid nature of these interactions limits the ability to adapt to new requirements or to delegate specific, limited permissions in a dynamic manner.</p> <p>Additionally, the need to repeatedly sign messages for each interaction creates friction in user experiences, particularly in scenarios requiring frequent or automated interactions.</p> <p>The proposed standard aims to solve these challenges by enabling the creation of long-lived sessions and delegated permissions through a single signature. These delegations can be used to:</p> <ul> <li>Establish persistent sessions with dApps that don't require repeated signing</li> <li>Grant bounded permissions to AI agents or automated systems</li> <li>Create shareable invite links with specific capabilities</li> <li>Enable third-party delegates to act within well-defined policy constraints</li> </ul> <p>By allowing the creation of open-ended yet policy-constrained delegations with a single signature, this standard helps minimize user interactions while maximizing their meaningful content. Users can grant specific capabilities with clear boundaries, rather than repeatedly signing similar permissions.</p> <p>The proposed standard aims to simplify and standardize the process of delegation between contracts, reducing the operational complexity and gas costs associated with shared capabilities. By establishing a common framework for delegating permissions, we can streamline interactions within the Ethereum ecosystem, making contracts more flexible, cost-effective, and adaptable to the needs of diverse applications. This opens up new possibilities for collaboration and innovation, allowing dApps to leverage each other's strengths in a more seamless and efficient manner.</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="terms">Terms</h3> <ul> <li>A <strong>Delegator</strong> is a smart contract that can create a delegation.</li> <li>A <strong>Delegation Manager</strong> is a smart contract that validates delegation authority and calls on the <em>Delegator</em> to execute an action. It implements the <code>ERC7710Manager</code> interface. A Delegation Manager verifies and processes delegation redemptions, and multiple Delegation Managers can exist with different implementations. A contract account can be its own delegation manager.</li> <li>A <strong>delegation</strong> is an authority given to another address to perform a specific action.</li> <li>A <strong>delegate</strong> is a smart contract, smart contract account, or EOA that has authority to redeem a delegation.</li> <li>A <strong>redeemer</strong> is a <em>delegate</em> that is using a delegation.</li> </ul> <h3 id="obtaining-delegations">Obtaining Delegations</h3> <p>The process by which a delegate obtains a delegation is intentionally left out of scope for this ERC. This ERC focuses solely on the interface for redeeming delegations and the validation of delegation authority. The mechanism for requesting and granting delegations may be implemented in various ways depending on the use case, such as through <a href="https://wg-eips.ritovision.com/7715/">ERC-7715</a> or other protocols. This separation of concerns allows for flexibility in how delegations are created while maintaining a consistent interface for their redemption.</p> <h3 id="overview">Overview</h3> <h4 id="redeeming-a-delegation">Redeeming a Delegation</h4> <p>When a delegate wishes to redeem a delegation, they call the <code>redeemDelegations</code> function on the Delegation Manager and pass in the action they want to execute and the proof of authority (ie delegation) which they are executing on behalf of. The Delegation Manager then verifies the delegation's validity and, if valid, calls the privileged function on the Delegator which executes the specified capability on behalf of the Delegator.</p> <p><img src="https://wg-eips.ritovision.com/7710/./assets/diagram.svg" alt="diagram showing the flow of redeemDelegations" /></p> <h3 id="interfaces">Interfaces</h3> <h4 id="erc7710manager-sol"><code>ERC7710Manager.sol</code></h4> <p>The Delegation Manager MUST implement the <code>redeemDelegations</code> which will be responsible for validating the delegations being redeemed, and will then call the delegators to execute the actions.</p> <p>The bytes array <code>_permissionContexts</code> passed in as a parameter to the <code>redeemDelegations</code> function contains the authority to execute a specific action on behalf of the delegating contract.</p> <p>The bytes32 array <code>_modes</code> and the bytes array <code>_executionCallDatas</code> passed in as parameters to the <code>redeemDelegations</code> function are arrays of <code>mode</code> and <code>executionCalldata</code>, which are defined precisely in <a href="https://wg-eips.ritovision.com/7579/">ERC-7579</a> (under the "Execution Behavior" section). Briefly, <code>mode</code> encodes the "behavior" of the execution, which could be a single call, a batch call, and others. <code>executionCallData</code> encodes the data of the execution, which typically includes at least a <code>target</code>, a <code>value</code>, and a <code>to</code> address.</p> <p>The three arrays MUST be interpreted as a list of tuples, where each tuple consists of (<code>_permissionContexts[i]</code>, <code>_modes[i]</code>, <code>_executionCallDatas[i]</code>). The function MUST revert if the arrays have different lengths. Each tuple represents a single delegation redemption with its associated permission context, execution mode, and execution data. Implementations MUST enforce atomicity of the batch.</p> <h4 id="permission-verification">Permission Verification</h4> <p>While this interface does not include an explicit method for checking delegation permissions, dApps SHOULD verify permissions before attempting to execute actions by:</p> <ol> <li>Simulating the <code>redeemDelegations</code> call with the intended parameters</li> <li>Using the simulation results to determine if the delegation would succeed</li> <li>If the simulation fails, the dApp can request new or updated permissions from the user</li> </ol> <p>This simulation-based approach provides stronger guarantees than a method exposed by the delegation manager, as it validates the entire execution context rather than the claims of the delegation manager.</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.23</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"> ERC7710Manager</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Interface for Delegation Manager that exposes the redeemDelegations function.</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"> ERC7710Manager</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 method validates the provided permission contexts and executes the execution if the caller has authority to do so.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> the structure of the _permissionContexts bytes[] is determined by the specific Delegation Manager 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"> _permissionContexts</span><span class="z-comment"> the data used to validate the authority given to execute the corresponding 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"> _action</span><span class="z-comment"> the action to be executed</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _modes</span><span class="z-comment"> the array of modes to execute the related executioncallData</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _executionCallDatas</span><span class="z-comment"> the array of encoded executions to be executed</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"> redeemDelegations</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _permissionContexts</span><span>,</span></span> <span class="giallo-l"><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"> _modes</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _executionCallData</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> <p>The design of this ERC is motivated by the need to introduce standardized, secure, and efficient mechanisms for delegation within the Ethereum ecosystem. Several considerations were taken into account:</p> <p><strong>Flexibility and Scalability</strong>: The proposed interfaces are designed to be minimal yet powerful, allowing contracts to delegate a wide range of actions without imposing a heavy implementation burden. This balance aims to encourage widespread adoption and innovation.</p> <p><strong>Interoperability</strong>: Compatibility with existing standards, such as <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> and <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a>, ensures that this approach can be seamlessly integrated into the current Ethereum infrastructure. This encourages adoption and leverages existing security practices.</p> <p><strong>Usability</strong>: By enabling contracts to delegate specific actions to others, we open the door to more user-friendly DApps that can perform a variety of tasks on behalf of users, reducing the need for constant user interaction and enhancing the overall user experience.</p> <p>This ERC represents a step towards a more interconnected and flexible Ethereum ecosystem, where smart contracts can more effectively collaborate and adapt to users' needs.</p> <h3 id="execution-interface">Execution Interface</h3> <p>A previous iteration of this spec defined <code>Action</code> as a simple <code>(target, value, data)</code> tuple, and defined a specific execution interface on the delegator that is <code>executeDelegatedAction(Action _action)</code> which the Delegation Manager is supposed to call.</p> <p>That approach had a few downsides:</p> <ul> <li>Existing smart accounts won't be compatible with this spec (unless they happen to implement the execution interface).</li> <li>The execution behavior is limited to a single call, since <code>Action</code> could only encode a single call. It made complex execution behaviors such as batching, delegatecall, and CREATE2 impossible.</li> </ul> <p>To solve the first issue, we decided to remove the requirement for the delegator to implement any specific interface. Rather, we rely on the Delegation Manager to correctly call the delegator, and we rely on the fact that a delegator would only create <code>_permissionContexts</code> for a Delegation Manager that knows how to correctly call it.</p> <p>To solve the second issue, we decied to adopt the execution interface from <a href="https://wg-eips.ritovision.com/7579/">ERC-7579</a>, which had to solve a similar problem within the context of modular smart accounts: defining a standardized execution interface that can support many types of executions.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>For a minimal reference implementation focusing on delegation redemption, please see <a href="https://wg-eips.ritovision.com/7710/./assets/Example7710Manager.sol">Example7710Manager</a>.</p> <p>For a complete reference implementation of a Delegation Manager, see the MetaMask Delegation Framework, which includes features such as:</p> <ul> <li><a href="https://wg-eips.ritovision.com/712/">EIP-712</a> signature validation for delegations</li> <li>Support for both EOA and contract signatures (ERC-1271)</li> <li>Caveat enforcement for fine-grained delegation control</li> <li>Batch delegation processing</li> <li>Delegation revocation mechanisms</li> </ul> <p>The MetaMask implementation demonstrates one way to build a robust delegation system while adhering to this standard's interface requirements.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The introduction of customizable authorization terms requires careful consideration of how authorization data is structured and interpreted. Potential security risks include the misinterpretation of authorization terms and unauthorized actions being taken if the interface is not properly implemented. It is recommended that applications implementing this interface undergo thorough security audits to ensure that authorization terms are handled securely.</p> <h3 id="permission-verification-1">Permission Verification</h3> <p>dApps MUST NOT assume that having received a delegation in the past guarantees future execution rights. Delegations can be revoked, expire, or become invalid due to state changes. To ensure reliable operation:</p> <ol> <li>Always simulate delegation redemptions before submitting them on-chain</li> <li>Handle simulation failures gracefully by requesting new permissions when needed</li> <li>Consider implementing retry logic with escalating permission requests</li> <li>Be prepared for delegations to become invalid between simulation and execution</li> </ol> <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-17T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin Peter Davieshttps://github.com/petertdavies Etan Kisslinghttps://github.com/etan-status Gajinder Singhhttps://github.com/g11tech Carsonhttps://github.com/carsons-eels Jared Wasingerhttps://github.com/jwasinger https://wg-eips.ritovision.com/7708/

All ETH transfers emit a log

<h2 id="abstract">Abstract</h2> <p>All ETH-transfers, including transactions, <code>CALL</code> and <code>SELFDESTRUCT</code> emit a log.</p> <h2 id="motivation">Motivation</h2> <p>Logs are often used to track when balance changes of assets on Ethereum. Logs work for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens, but they do not work for ETH. ETH transfers from EOAs can be read from the transaction list in the block, but ETH transfers from smart contract wallets are not automatically logged anywhere. This has already led to problems in the past, eg. early exchanges would often not properly support deposits from smart contract wallets, or only support them with a much longer delay. This EIP proposes that we automatically generate a log every time a value-transferring <code>CALL</code> or <code>SELFDESTRUCT</code> happens. We also add a similar log for transfers in transactions, so that all ETH transfers can be tracked using one mechanism.</p> <h2 id="specification">Specification</h2> <h3 id="eth-transfer-logs">ETH transfer logs</h3> <p>A log, identical to a LOG3, is issued for:</p> <ul> <li>Any nonzero-value-transferring transaction to a different account, before any other logs created by EVM execution</li> <li>Any nonzero-value-transferring <code>CALL</code> to a different account, at the time that the value transfer executes</li> <li>Any nonzero-value-transferring <code>SELFDESTRUCT</code> to a different account, at the time that the value transfer executes</li> </ul> <table><thead><tr><th>Field</th><th>Value</th></tr></thead><tbody> <tr><td><code>address</code> emitting log</td><td><code>0xfffffffffffffffffffffffffffffffffffffffe</code> (<a href="https://wg-eips.ritovision.com/4788/"><code>SYSTEM_ADDRESS</code></a>)</td></tr> <tr><td><code>topics[0]</code></td><td><code>0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef</code> (<code>keccak256('Transfer(address,address,uint256)')</code>)</td></tr> <tr><td><code>topics[1]</code></td><td><code>from</code> address (zero prefixed to fill uint256)</td></tr> <tr><td><code>topics[2]</code></td><td><code>to</code> address (zero prefixed to fill uint256)</td></tr> <tr><td><code>data</code></td><td><code>amount</code> in Wei (big endian uint256)</td></tr> </tbody></table> <p>This matches the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> Transfer event definition.</p> <h3 id="selfdestruct-processing">Selfdestruct processing</h3> <p>A log, identical to a LOG2, is issued for:</p> <ul> <li>Any non-zero balance removal which occurs when a contract created in the same transaction invokes <code>SELFDESTRUCT</code> with itself as a target, at the time that the opcode is invoked.</li> <li>Each account which has been marked for deletion and holds a balance at the time of removal during transaction finalization. Burn logs are emitted after any other logs created by EVM execution and the payment of the <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> priority fee to the coinbase, in lexicographical order of account address</li> </ul> <table><thead><tr><th>Field</th><th>Value</th></tr></thead><tbody> <tr><td><code>address</code> emitting log</td><td><code>0xfffffffffffffffffffffffffffffffffffffffe</code> (<a href="https://wg-eips.ritovision.com/4788/"><code>SYSTEM_ADDRESS</code></a>)</td></tr> <tr><td><code>topics[0]</code></td><td><code>0x4bfaba3443c1a1836cd362418edc679fc96cae8449cbefccb6457cdf2c943083</code> (<code>keccak256('Selfdestruct(address,uint256)')</code>)</td></tr> <tr><td><code>topics[1]</code></td><td>Closed <code>contract_address</code> (zero prefixed to fill uint256)</td></tr> <tr><td><code>data</code></td><td><code>amount</code> in Wei (big endian uint256)</td></tr> </tbody></table> <p>The Selfdestruct log is emitted when (1) a <code>SELFDESTRUCT</code> to self is triggered, or when (2) a smart contract is closed after receiving more ETH after already flagged for <code>SELFDESTRUCT</code>.</p> <h2 id="rationale">Rationale</h2> <p>This is the simplest possible implementation that ensures that all ETH transfers are implemented in some kind of record that can be easily accessed through making RPC calls into a node, or through asking for a Merkle branch that is hashed into the block root. The log type is compatible with the ERC-20 token standard, but does not introduce any overly-specific ERC-20 features (eg. ABI encodings) into the specification.</p> <h3 id="open-questions">Open questions</h3> <ol> <li>Magic value used for <code>address</code>? For address: (a) <code>0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee</code> (same as <code>eth_simulateV1</code>), (b) <code>0xfffffffffffffffffffffffffffffffffffffffe</code> (<a href="https://wg-eips.ritovision.com/4788/"><code>SYSTEM_ADDRESS</code></a>), (c) zero address</li> <li>Should fee payments trigger a log? It would ensure "completeness", in the sense that you can compute the exact current balance table by watching logs, but it would greatly increase the number of logs, perhaps to an unacceptably high amount.</li> <li>Should withdrawals also trigger a log? They are not associated with transactions.</li> </ol> <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>ETH transfers already cost a minimum of 6700 gas, which is much more expensive than the LOG3 opcode (1500 gas). Hence, this EIP does not increase the worst-case number of logs that can be put into a block. It will somewhat 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> 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 Vitalik Buterinhttps://github.com/vbuterin Sam Wilsonhttps://github.com/SamWilsn Ansgar Dietrichshttps://github.com/adietrichs lightclienthttps://github.com/lightclient https://wg-eips.ritovision.com/7702/

Add a new tx type that permanently sets the code for an EOA

<h2 id="abstract">Abstract</h2> <p>Add a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction type that allows Externally Owned Accounts (EOAs) to set the code in their account. This is done by attaching a list of authorization tuples -- individually formatted as <code>[chain_id, address, nonce, y_parity, r, s]</code> -- to the transaction. For each tuple, a delegation indicator <code>(0xef0100 || address)</code> is written to the authorizing account's code. All code executing operations must load and execute the code pointed to by the delegation.</p> <h2 id="motivation">Motivation</h2> <p>Despite great advances in the smart contract wallet ecosystem, EOAs have held back broad adoption of UX improvements across applications. This EIP therefore focuses on adding short-term functionality improvements to EOAs which will allow UX improvements to permeate through the entire application stack. Three particular features this EIP is designed around are:</p> <ul> <li><strong>Batching</strong>: allowing multiple operations from the same user in one atomic transaction. One common example is an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> approval followed by spending that approval. This is a common workflow in DEXes that requires two transactions today. Advanced use cases of batching occasionally involve dependencies: the output of the first operation is part of the input to the second operation.</li> <li><strong>Sponsorship</strong>: account X pays for a transaction on behalf of account Y. Account X could be paid in some other ERC-20 for this service, or it could be an application operator including the transactions of its users for free.</li> <li><strong>Privilege de-escalation</strong>: users can sign sub-keys and give them specific permissions that are much weaker than global access to the account. For example, a permission to spend ERC-20 tokens but not ETH, or to spend up to 1% of the total balance per day, or to interact only with a specific application.</li> </ul> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Parameter</th><th>Value</th></tr></thead><tbody> <tr><td><code>SET_CODE_TX_TYPE</code></td><td><code>0x04</code></td></tr> <tr><td><code>MAGIC</code></td><td><code>0x05</code></td></tr> <tr><td><code>PER_AUTH_BASE_COST</code></td><td><code>12500</code></td></tr> <tr><td><code>PER_EMPTY_ACCOUNT_COST</code></td><td><code>25000</code></td></tr> </tbody></table> <h3 id="set-code-transaction">Set code transaction</h3> <p>A new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction known as the "set code transaction" is introduced, where the <code>TransactionType</code> is <code>SET_CODE_TX_TYPE</code> and the <code>TransactionPayload</code> is the RLP serialization of the following:</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,</span></span> <span class="giallo-l"><span>destination, value, data, access_list, authorization_list, signature_y_parity,</span></span> <span class="giallo-l"><span>signature_r, signature_s])</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>authorization_list = [[chain_id, address, nonce, 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>destination</code>, <code>value</code>, <code>data</code>, and <code>access_list</code> of the outer transaction follow the same semantics as <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>. <em>Note, this implies a null destination is not valid.</em></p> <p>The <code>signature_y_parity, signature_r, signature_s</code> elements of this transaction represent a secp256k1 signature over <code>keccak256(SET_CODE_TX_TYPE || TransactionPayload)</code>.</p> <p>The <code>authorization_list</code> is a list of tuples that indicate what code the signer of each tuple desires to execute in the context of their EOA. The transaction is considered invalid if the length of <code>authorization_list</code> is zero.</p> <p>The transaction is also considered invalid when any field in an authorization tuple cannot fit within the following bounds:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">assert</span><span> auth</span><span>.</span><span>chain_id</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">256</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> auth</span><span>.</span><span>nonce</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">64</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span class="z-support"> len</span><span>(</span><span>auth</span><span>.</span><span>address</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 20</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> auth</span><span>.</span><span>y_parity</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">8</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> auth</span><span>.</span><span>r</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">256</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> auth</span><span>.</span><span>s</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">256</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> <h4 id="behavior">Behavior</h4> <p>The authorization list is processed before the execution portion of the transaction begins, but after the sender's nonce is incremented.</p> <p>For each <code>[chain_id, address, nonce, y_parity, r, s]</code> tuple, perform the following:</p> <ol> <li>Verify the chain ID is 0 or the ID of the current chain.</li> <li>Verify the <code>nonce</code> is less than <code>2**64 - 1</code>.</li> <li>Let <code>authority = ecrecover(msg, y_parity, r, s)</code>. <ul> <li>Where <code>msg = keccak(MAGIC || rlp([chain_id, address, nonce]))</code>.</li> <li>Verify <code>s</code> is less than or equal to <code>secp256k1n/2</code>, as specified in <a href="https://wg-eips.ritovision.com/2/">EIP-2</a>.</li> </ul> </li> <li>Add <code>authority</code> to <code>accessed_addresses</code>, as defined in <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>.</li> <li>Verify the code of <code>authority</code> is empty or already delegated.</li> <li>Verify the nonce of <code>authority</code> is equal to <code>nonce</code>.</li> <li>Add <code>PER_EMPTY_ACCOUNT_COST - PER_AUTH_BASE_COST</code> gas to the global refund counter if <code>authority</code> is not empty.</li> <li>Set the code of <code>authority</code> to be <code>0xef0100 || address</code>. This is a delegation indicator. <ul> <li>If <code>address</code> is <code>0x0000000000000000000000000000000000000000</code>, do not write the delegation indicator. Clear the account's code by resetting the account's code hash to the empty code hash <code>0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470</code>.</li> </ul> </li> <li>Increase the nonce of <code>authority</code> by one.</li> </ol> <p>If any step above fails, immediately stop processing the tuple and continue to the next tuple in the list. When multiple tuples from the same authority are present, set the code using the address in the last valid occurrence.</p> <p>Note, if transaction execution results in failure (e.g. any exceptional condition or code reverting), the processed delegation indicators is <em>not rolled back</em>.</p> <h5 id="delegation-indicator">Delegation indicator</h5> <p>Delegation indicators use the banned opcode <code>0xef</code>, defined in <a href="https://wg-eips.ritovision.com/3541/">EIP-3541</a>, to indicate that the code must be handled differently than regular code. The delegation forces all code executing operations to follow the address pointer to obtain the code to execute. For example, <code>CALL</code> loads the code at <code>address</code> and executes it in the context of <code>authority</code>.</p> <p>The affected executing operations are:</p> <ul> <li><code>CALL</code></li> <li><code>CALLCODE</code></li> <li><code>DELEGATECALL</code></li> <li><code>STATICCALL</code></li> <li>any transaction where <code>destination</code> points to an address with a delegation indicator present</li> </ul> <p>For code reading, only <code>CODESIZE</code> and <code>CODECOPY</code> instructions are affected. They operate directly on the executing code instead of the delegation. For example, when executing a delegated account <code>EXTCODESIZE</code> returns <code>23</code> (the size of <code>0xef0100 || address</code>) whereas <code>CODESIZE</code> returns the size of the code residing at <code>address</code>.</p> <p><em>Note, this means during delegated execution <code>CODESIZE</code> and <code>CODECOPY</code> produce a different result compared to calling <code>EXTCODESIZE</code> and <code>EXTCODECOPY</code> on the authority.</em></p> <h6 id="precompiles">Precompiles</h6> <p>When a precompile address is the target of a delegation, the retrieved code is considered empty and <code>CALL</code>, <code>CALLCODE</code>, <code>STATICCALL</code>, <code>DELEGATECALL</code> instructions targeting this account will execute empty code, and therefore succeed with no execution when given enough gas to initiate the call.</p> <h6 id="loops">Loops</h6> <p>In case a delegation indicator points to another delegation, creating a potential chain or loop of delegations, clients must retrieve only the first code and then stop following the delegation chain.</p> <h4 id="gas-costs">Gas Costs</h4> <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>. Additionally, add a cost of <code>PER_EMPTY_ACCOUNT_COST * authorization list length</code>.</p> <p>The transaction sender will pay for all authorization tuples, regardless of validity or duplication.</p> <p>If a code executing instruction accesses a cold account during the resolution of delegated code, add an additional <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a> <code>COLD_ACCOUNT_READ_COST</code> cost of <code>2600</code> gas to the normal cost and add the account to <code>accessed_addresses</code>. Otherwise, assess a <code>WARM_STORAGE_READ_COST</code> cost of <code>100</code>.</p> <h4 id="transaction-origination">Transaction origination</h4> <p>Modify the restriction put in place by <a href="https://wg-eips.ritovision.com/3607/">EIP-3607</a> to allow EOAs whose code is a valid delegation indicator, i.e. <code>0xef0100 || address</code>, to originate transactions. Accounts with any other code values may not originate transactions.</p> <p>Additionally, if a transaction's <code>destination</code> has a delegation indicator, add the target of the delegation to <code>accessed_addresses</code>.</p> <h2 id="rationale">Rationale</h2> <p>Below is the rationale for both general design directions of the EIP, as well as specific technical choices.</p> <h3 id="general-design-philosophy">General design philosophy</h3> <h4 id="persistence-of-code-delegation">Persistence of code delegation</h4> <p>The first draft of this proposal had a clever idea to avoid disagreement on whether in-protocol revocation was needed or not. The idea was to temporarily set code in the account with the authorization. After the transaction finished, the code would be completely cleared. This was a new design space for enriching EOA functionality.</p> <p>Even this approach was not without its flaws. Fundamentally, there was not much friction for users including set code authorizations. This meant that some users and applications would opt to treat the extension as more of a scripting facility, rather than a full-fledged upgrade to a smart contract wallet. The outcome of this would be two somewhat competing workstreams for UX improvements: smart contract wallets and EOA scripts.</p> <p>Previous proposals had been met with similar criticisms. To counteract this, persistent delegations were introduced. They create enough friction in deployment that users will not deploy new, unique ones regularly. This will hopefully unify the workstreams and minimize fragmentation in UX developments.</p> <h4 id="no-initcode">No initcode</h4> <p>Running initcode is not desirable for many reasons. It creates a new mode of execution that needs extensive testing, and may be used for purposes not possible with standard smart contract wallets. It also forces developers to perform initialization as a standard call to the EOA after delegation. The lack of atomicity in these operations is another factor that will push users to complete smart contract wallet solutions, instead of EOA scripts.</p> <p>Additionally, initcode tends to be propagated inside the transaction calldata. This means it would need to be included in the authorization tuple and signed over. The minimum initcode is around 15 bytes -- it would simply copy the contract code from an external address. The total cost would be <code>16 * 15 = 240</code> calldata cost, plus the <a href="https://wg-eips.ritovision.com/3860/">EIP-3860</a> cost of <code>2 * 15 = 30</code>, plus the runtime costs of around <code>150</code>. So nearly <code>500</code> additional gas would be spent preparing the account. Even more likely, 1200+ gas if not copying from an external account.</p> <h4 id="creation-by-template">Creation by template</h4> <p>Initcode or not, there is a question of how users should specify the code they intend to run in their account. The two main options are to specify the bytecode directly in the transaction or to specify a pointer to the code. The simplest pointer would just be the address of code deployed on-chain.</p> <p>The cost analysis makes the answer clear. The smallest proxy would be around 50 bytes and an address is 20 bytes. The 30 byte difference provides no useful additional functionality and will be inefficiently replicated billions of times.</p> <p>Furthermore, specifying code directly would again make it possible for EOAs to have a new, unique ability to execute arbitrary code specified in the transaction calldata. It is for these reasons that creation by template is chosen.</p> <h4 id="interaction-with-applications-and-wallets">Interaction with applications and wallets</h4> <p>While this EIP provides a lot of flexibility to applications and EOAs, there are incorrect ways of using it. Applications <strong>must not</strong> expect that they can suggest the user sign an authorization, and therefore it is the duty of the wallet to not provide an interface to do so.</p> <p><strong>There is no safe way to provide this interface</strong>. The code specified by an authorization has unrestricted access to the account and must always be closely audited by the wallet. Few users have the level of sophistication to reasonably verify the code they are delegating to.</p> <p>It is also not possible to implement a system of permissions at this level to minimize the risk. If applications require custom wallet functionality, they must use standardized extension / module systems built on top of the delegated code that correctly implements permissions.</p> <h4 id="forward-compatibility-with-future-account-abstraction">Forward-compatibility with future account abstraction</h4> <p>This EIP is designed to be forward-compatible with endgame account abstraction, without over-enshrining any fine-grained details of <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> or RIP-7560.</p> <p>To start, the <code>address</code> that users sign could directly point to existing ERC-4337 wallet code. This essentially requires the "code pathways" that are used are code pathways that would, in most cases, continue to make sense in a pure-smart-contract-wallet world. Hence, it avoids the problem of creating two separate UX workstreams because, to a large extent, they would be the same ecosystem.</p> <p>There will be some workflows that require kludges under this solution that would be better done in some different "more native" under "endgame AA", but this is relatively a small subset. The EIP does not require adding any opcodes, that would become dangling and useless in a post-EOA world, and it allows EOAs to masquerade as contracts to be included in ERC-4337 bundles, in a way that's compatible with the existing <code>EntryPoint</code>.</p> <h4 id="self-sponsoring-allowing-tx-origin-to-set-code">Self-sponsoring: allowing <code>tx.origin</code> to set code</h4> <p>Allowing <code>tx.origin</code> to set code and execute its own delegated code enables what is called self-sponsoring. It allows users to take advantage of EIP-7702 without relying on any third party infrastructure.</p> <p>However, that means the EIP breaks the invariant that <code>msg.sender == tx.origin</code> only happens in the topmost execution frame of a transaction. This will affect smart contracts containing <code>require(msg.sender == tx.origin)</code> style checks. This check is used for at least three purposes:</p> <ol> <li>Ensuring that <code>msg.sender</code> is an EOA (given that <code>tx.origin</code> always has to be an EOA). This invariant does not depend on the execution layer depth and, therefore, is not affected.</li> <li>Protecting against atomic sandwich attacks like flash loans, which rely on the ability to modify state before and after the execution of the target contract as part of the same atomic transaction. This protection would be broken by this EIP. However, relying on <code>tx.origin</code> in this way is considered bad practice, and can already be circumvented by miners conditionally including transactions in a block.</li> <li>Preventing reentrancy.</li> </ol> <p>Examples of (1) and (2) can be found in contracts deployed on Ethereum mainnet, with (1) being more common (and unaffected by this proposal). On the other hand, use case (3) is more severely affected by this proposal, but the authors of this EIP did not find any examples of this form of reentrancy protection, though the search was non-exhaustive.</p> <p>This distribution of occurrences—many (1), some (2), and no (3)—is exactly what the authors of this EIP expect because:</p> <ul> <li>Determining if <code>msg.sender</code> is an EOA without <code>tx.origin</code> is difficult, if not impossible.</li> <li>The only execution context which is safe from atomic sandwich attacks is the topmost context, and <code>tx.origin == msg.sender</code> is the only way to detect that context.</li> <li>In contrast, there are many direct and flexible ways of preventing reentrancy (e.g., using a transient storage variable). Since <code>msg.sender == tx.origin</code> is only true in the topmost context, it would make an obscure tool for preventing reentrancy, rather than other more common approaches.</li> </ul> <p>There are other approaches to mitigate this restriction which do not break the invariant:</p> <ul> <li>Set <code>tx.origin</code> to a constant <code>ENTRY_POINT</code> address when using the <code>CALL*</code> instruction in the context of an EOA.</li> <li>Set <code>tx.origin</code> to a special address derived from the sender or signer addresses.</li> <li>Disallow <code>tx.origin</code> from setting code. This would make the simple batching use cases impossible, but could be relaxed in the future.</li> </ul> <h3 id="rationale-for-technical-details">Rationale for technical details</h3> <h4 id="cost-of-delegation">Cost of delegation</h4> <p>The <code>PER_AUTH_BASE_COST</code> is the cost to process the authorization tuple and set the delegation destination. To compute a fair cost for this operation, the authors review its impact on the system:</p> <ul> <li>ferry 101 bytes of calldata = <code>101 * non-zero cost (16) = 1616</code></li> <li>recovering the <code>authority</code> address = <code>3000</code></li> <li>reading the nonce and code of <code>authority</code> = <code>2600</code></li> <li>storing values in already warm account = <code>200</code></li> <li>cost to deploy code = <code>200 * 23 = 4600</code></li> </ul> <p>The impact-based assessment identifies <code>12016</code> gas of comparable computation for the operation. It is rounded up to <code>12500</code> to account for miscellaneous costs associated with shuttling data around the state transition.</p> <h4 id="clearing-delegation-indicators">Clearing delegation indicators</h4> <p>A general design goal in state transition changes is to minimize the number of special cases an EIP has. In early iterations, this EIP resisted a special case for clearing an account's delegation indicator.</p> <p>For most intents and purposes, an account delegated to <code>0x0</code> is indistinguishable from a true EOA. However, one particular unfortunate case is unavoidable. Even if a user has a zeroed out delegation indicator, most operations that interact with that account will incur an additional <code>COLD_ACCOUNT_READ_COST</code> upon the first touch caused by attempting to load the code at <code>0x0</code>.</p> <p>For this reason, the authors have opted to include a special case which allow users to restore their EOA to its original purity.</p> <h4 id="lack-of-instruction-prohibition">Lack of instruction prohibition</h4> <p>Consistency is a valuable property in the EVM, both from an implementation perspective and a user-understanding-perspective. Despite considering bans on several families of instructions in the context of EOAs, the authors feel there is not a compelling reason to do so, as it would cause smart contract wallets and EOA smart contract wallets to proceed down distinct UX workstreams.</p> <p>The main instruction families where a ban was considered were storage related and contract creation related. The decision to not ban storage instructions hinged mostly on their importance to smart contract wallets. Although it's possible to have an external storage contract that the smart contract wallet calls into, it is unnecessarily complicated and inefficient. In the future, new state schemes may allow substantially cheaper access to certain storage slots within an account. This is something smart contract wallets will want to take advantage of that a storage contract wouldn't support.</p> <p>Creation instructions were considered for a ban as well on other similar EIPs, however because this EIP allows EOAs to spend value intra-transaction, the concern with bumping the nonce intra-transaction and invalidating pending transactions is not significant.</p> <h4 id="protection-from-malleability-cross-chain">Protection from malleability cross-chain</h4> <p>One consideration when signing a code pointer is what code that address points to on another chain. While it is possible to create a deterministic deployment, i.e. via Nick's method, verifying such a deployment may not always be desirable. In such situations, the chain ID can be set to reduce the scope of the authorization. When universal deployment is preferred, simply set chain ID to 0.</p> <p>An alternative to adding chain ID could be to substitute in the actual code for the address in the signature. This seems to have the benefit of both minimizing the on-chain size of auth tuples, by continuing to serialize only the address, while retaining specificity of the actual code running in the account, by pulling in the code for the signature. One unfortunate issue of this format, though, is that it imposes a database lookup to determine the signer of each auth tuple. This imposition itself seems to create enough complexity in transaction propagation that it is decided to avoid and simply sign over the address directly.</p> <h4 id="delegation-of-code-execution-only">Delegation of code execution only</h4> <p>Other code retrieving operations like <code>EXTCODEHASH</code> do not automatically follow delegations, they operate on the delegation indicator itself. If instead delegations were followed, an account would be able to temporarily masquerade as having a particular codehash, which would break contracts that rely on codehashes as a definition of possible account behavior. A change of behavior in a contract is currently only possible if its code explicitly allows it (in particular via <code>DELEGATECALL</code>), and a change of codehash is only possible in the presence of <code>SELFDESTRUCT</code> (which, as of Cancun, only applies in the same transaction as contract creation), so choosing to follow delegations in <code>EXTCODE*</code> opcodes would have created a new type of account breaking prior assumptions.</p> <h4 id="charge-maximum-cost-upfront">Charge maximum cost upfront</h4> <p>While computing the intrinsic gas cost, the transaction is charged the worst-case cost for each delegation. Later, while processing the authorization list, a refund is issued if the account already exists in state. This mechanism is designed to avoid state lookups for each authorization when computing the intrinsic gas and can quickly determine the validity of the transaction with only a state lookup on the sender's account.</p> <h4 id="no-blobs-no-contract-creation">No blobs, no contract creation</h4> <p>Transactions should be thought of as specialized tools and not necessarily a one-type-does-all solution. EIP-4844 is treated differently at the p2p level due to burden blobs place on a node's bandwidth. EIP-7702 has different implications on transaction gossiping and there is no need to complicate those rules unnecessarily by making it a superset of all possible functionality. The authors ultimately do not expect there to be much demand for atomic delegation and blob submission.</p> <p>Contract creation is another specialized use case that has been grandfathered into several transaction types. It adds complexity to testing, because it is a new distinct branch of execution that needs to be tested when any change to the EVM occurs and verify the change works as expected in that context.</p> <p>For these reasons, the authors have chosen to keep the scope of the EIP focused on improving UX.</p> <h4 id="disallow-delegation-to-precompiles">Disallow delegation to precompiles</h4> <p>Precompiles are themselves edge cases, so allowing delegations to precompiles or not requires some focus in implementation. Considering the fact that precompiles technically do not have code associated with their accounts, the authors decided it would be marginally simpler to not execute the precompile logic when a user delegates to one. This is somewhat unintuitive.</p> <h4 id="non-empty-authorization-list-required">Non-empty authorization list required</h4> <p>Set code transactions are required to have at least one authorization to be considered valid. This is to disincentivize senders from using type 4 transactions as a generic transaction format, because this transaction has different implications on the transaction pool than, say, <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> transactions.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP breaks a few invariants:</p> <ul> <li>An account balance can only decrease as a result of a transaction originating from that account. <ul> <li>Once an account has been delegated, any call to the account may also cause the balance to decrease.</li> </ul> </li> <li>An EOA nonce may not increase after transaction execution has begun. <ul> <li>Once an account has been delegated, the account may call a create operation during execution, causing the nonce to increase.</li> </ul> </li> <li><code>tx.origin == msg.sender</code> can only be true in the topmost frame of execution. <ul> <li>Once an account has been delegated, it can invoke multiple calls per transaction.</li> </ul> </li> </ul> <h2 id="security-considerations">Security Considerations</h2> <h3 id="implementation-of-secure-delegate-contracts">Implementation of secure delegate contracts</h3> <p>The following is a non-exhaustive list of pitfalls that delegate contracts <em>should</em> be wary of and require a signature over from the account's authority:</p> <ul> <li>Replay protection (e.g., a nonce) should be implemented by the delegate and signed over. Without it, a malicious actor can reuse a signature, repeating its effects.</li> <li><code>value</code> -- without it, a malicious sponsor could cause unexpected effects in the callee.</li> <li><code>gas</code> -- without it, a malicious sponsor could cause the callee to run out of gas and fail, griefing the sponsee.</li> <li><code>target</code> / <code>calldata</code> -- without them, a malicious actor may call arbitrary functions in arbitrary contracts.</li> </ul> <p>A poorly implemented delegate can <em>allow a malicious actor to take near complete control over a signer's EOA</em>.</p> <h3 id="front-running-initialization">Front running initialization</h3> <p>Smart contract wallet developers must consider the implications of setting code in an account without execution. Contracts are normally deployed by executing initcode to determine the exact code to be placed in the account. This gives developers the opportunity to initialize storage slots at the same time. The initial values of the account cannot be replaced by an observer, because they are either signed over by an EOA in the case of a creation transaction or they are committed to by computing the contract's address deterministically from the hash of the initcode.</p> <p>This EIP does not provide developers the opportunity to run initcode and set storage slots during delegation. To secure the account from an observer front-running the initialization of the delegation with an account they control, smart contract wallet developers must verify the initial calldata to the account for setup purposes be signed by the EOA's key using ecrecover. This ensures the account can only be initialized with desirable values.</p> <h3 id="storage-management">Storage management</h3> <p>Changing an account's delegation is a security-critical operation that should not be done lightly, especially if the newly delegated code is not purposely designed and tested as an upgrade to the old one.</p> <p>In particular, in order to ensure a safe migration of an account from one delegate contract to another, it's important for these contracts to use storage in a way that avoids accidental collisions among them. For example, using <a href="https://wg-eips.ritovision.com/7201/">ERC-7201</a> a contract may root its storage layout at a slot dependent on a unique identifier. To simplify this, smart contract languages may provide a way of re-rooting the entire storage layout of existing contract source code.</p> <p>If all contracts previously delegated to by the account used the approach described above, a migration should not cause any issues. However, if there is any doubt, it is recommended to first clear all account storage, an operation that is not natively offered by the protocol but that a special-purpose delegate contract can be designed to implement.</p> <h3 id="setting-code-as-tx-origin">Setting code as <code>tx.origin</code></h3> <p>Allowing the sender of an EIP-7702 to also set code has the possibility to:</p> <ul> <li>Break atomic sandwich protections which rely on <code>tx.origin</code>;</li> <li>Break reentrancy guards of the style <code>require(tx.origin == msg.sender)</code>.</li> </ul> <p>The authors of this EIP believe the risks of allowing this are acceptable for the reasons outlined in the Rationale section.</p> <h3 id="sponsored-transaction-relayers">Sponsored transaction relayers</h3> <p>It is possible for the <code>authorized</code> account to cause sponsored transaction relayers to spend gas without being reimbursed by either invalidating the authorization (i.e., increasing the account's nonce) or by sweeping the relevant assets out of the account. Relayers should be designed with these cases in mind, possibly by requiring a bond to be deposited or by implementing a reputation system.</p> <h3 id="transaction-propagation">Transaction propagation</h3> <p>Allowing EOAs to behave as smart contracts via the delegation indicator poses some challenges for transaction propagation. Traditionally, EOAs have only been able to send value via a transaction. This invariant allows nodes to statically determine the validity of transactions for that account. In other words, a single transaction has only been able to invalidate transactions pending from the sender's account.</p> <p>With this EIP, it becomes possible to cause transactions from other accounts to become stale. This is due to the fact that once an EOA has delegated to code, that code can be called by anyone at any point in a transaction. It becomes impossible to know if the balance of the account has been swept in a static manner.</p> <p>While there are a few mitigations for this, the authors recommend that clients do not accept more than one pending transaction for any EOA with a non-zero delegation indicator. This minimizes the number of transactions that can be invalidated by a single transaction.</p> <p>An alternative would be to expand the EIP-7702 transaction with a list of accounts the caller wishes to "hydrate" during the transaction. Those accounts behave as the delegated code <em>only</em> for EIP-7702 transactions which include them in such a list, thus returning to clients the ability to statically analyze and reason about pending transactions.</p> <p>A related issue is that an EOA's nonce may be incremented more than once per transaction. Because clients already need to be robust in a worse scenario (described above), it isn't a major concern. However, clients should be aware this behavior is possible and design their transaction propagation accordingly.</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-30T00:00:00+00:00 2026-02-11T14:48:26+00:00 Avneet Singhhttps://github.com/sshmatrix 0xc0de4c0ffeehttps://github.com/0xc0de4c0ffee Nick Johnsonhttps://github.com/arachnid Makoto Inouehttps://github.com/makoto https://wg-eips.ritovision.com/7700/

Provides a mechanism to replace L1 storage with L2 and databases through cross-chain routers

<h2 id="abstract">Abstract</h2> <p>The following standard provides a mechanism by which smart contracts can route storage to external providers. In particular, protocols can reduce the gas fees associated with storing data on mainnet by routing the handling of storage operations to another system or network. These storage routers act as an extension to the core L1 contract. Methods in this document specifically target security and cost-effectiveness of storage routing to three router types: L1, L2 and databases. The cross-chain data written with these methods can be retrieved by generic <a href="https://wg-eips.ritovision.com/3668/">EIP-3668</a>-compliant contracts, thus completing the cross-chain data life cycle. This document, nicknamed CCIP-Store, alongside <a href="https://wg-eips.ritovision.com/3668/">EIP-3668</a>, is a meaningful step toward a secure infrastructure for cross-chain storage routers and data retrievals.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/3668/">EIP-3668</a>, aka 'CCIP-Read', has been key to retrieving cross-chain data for a variety of contracts on Ethereum blockchain, ranging from price feeds for DeFi contracts, to more recently records for ENS users. The latter case dedicatedly uses cross-chain storage to bypass the usually high gas fees associated with on-chain storage; this aspect has a plethora of use cases well beyond ENS records and a potential for significant impact on universal affordability and accessibility of Ethereum.</p> <p>Cross-chain data retrieval through <a href="https://wg-eips.ritovision.com/3668/">EIP-3668</a> is a relatively simpler task since it assumes that all relevant data originating from cross-chain storages is translated by CCIP-Read-compliant HTTP gateways; this includes L2 chains and databases. On the flip side however, so far each service leveraging CCIP-Read must handle writing this data securely to these storage types on their own, while also incorporating reasonable security measures in their CCIP-Read-compatible contracts for verifying this data on L1. While these security measures are in-built into L2 architectures, database storage providers on the other hand must incorporate some form of explicit security measures during storage operations so that cross-chain data's integrity can be verified by CCIP-Read contracts during data retrieval stage. Examples of this include:</p> <ul> <li>Services that allow the management of namespaces, e.g. ENS domains, stored externally on an L2 solution or off-chain database as if they were native L1 tokens, and,</li> <li>Services that allow the management of digital identities stored on external storages as if they were stored in the native L1 smart contract.</li> </ul> <p>In this context, a specification which allows storage routing to external routers will facilitate creation of services that are agnostic to the underlying storage solution. This in turn enables new applications to operate without knowledge of the underlying routers. This 'CCIP-Store' proposal outlines precisely this part of the process, i.e. how the bespoke storage routing can be made by smart contracts to L2s and databases.</p> <p><img src="https://wg-eips.ritovision.com/7700/./assets/images/Schema.svg" alt="Fig.1 CCIP-Store and CCIP-Read Workflows" /></p> <h2 id="specification">Specification</h2> <h3 id="overview">Overview</h3> <p>The following specification revolves around the structure and description of a cross-chain storage router tasked with the responsibility of writing to an L2 or database storage. This document introduces <code>StorageRoutedToL2()</code> and <code>StorageRoutedToDatabase()</code> storage routers, along with the trivial <code>StorageRoutedToL1()</code> router, and proposes that new <code>StorageRoutedTo__()</code> reverts be allowed through new EIPs that sufficiently detail their interfaces and designs. Some foreseen examples of new storage routers include <code>StorageRoutedToSolana()</code> for Solana, <code>StorageRoutedToFilecoin()</code> for Filecoin, <code>StorageRoutedToIPFS()</code> for IPFS, <code>StorageRoutedToIPNS()</code> for IPNS, <code>StorageRoutedToArweave()</code> for Arweave, <code>StorageRoutedToArNS()</code> for ArNS, <code>StorageRoutedToSwarm()</code> for Swarm etc.</p> <h3 id="l1-router-storageroutedtol1">L1 Router: <code>StorageRoutedToL1()</code></h3> <p>A minimal L1 router is trivial and only requires the L1 <code>contract</code> address to which routing must be made, while the clients must ensure that the calldata is invariant under routing to another contract. One example implementation of an L1 router is given below.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Define revert event</span></span> <span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> StorageRoutedToL1</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> contractL1</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"> Generic function in a contract</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setValue</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> node</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> value</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-comment"> //</span><span class="z-comment"> Get metadata from on-chain sources</span></span> <span class="giallo-l"><span> (</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> contractL1</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Routed contract address on L1; may be globally constant</span></span> <span class="giallo-l"><span> )</span><span class="z-keyword"> =</span><span class="z-entity z-name"> getMetadata</span><span>(</span><span>node</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Arbitrary code</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> contractL1 = 0x32f94e75cde5fa48b6469323742e6004d701409b</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Route storage call to L1 router</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> StorageRoutedToL1</span><span>(</span><span> </span></span> <span class="giallo-l"><span> contractL1</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p>In this example, the routing must prompt the client to build the transaction with the exact same original calldata, and submit it to the L1 <code>contract</code> by calling the exact same function.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Function in routed L1 contract</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setValue</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> node</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> value</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-comment"> //</span><span class="z-comment"> Some code storing data mapped by node &amp; msg.sender</span></span> <span class="giallo-l"><span> .</span><span>.</span><span>.</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><img src="https://wg-eips.ritovision.com/7700/./assets/images/L1.svg" alt="Fig.2 L1 Call Lifecycle" /></p> <h3 id="l2-router-storageroutedtol2">L2 Router: <code>StorageRoutedToL2()</code></h3> <p>A minimal L2 router only requires the list of <code>chainId</code> values and the corresponding L2 <code>contract</code> addresses, while the clients must ensure that the calldata is invariant under routing to L2. One example implementation of an L2 router in an L1 contract is shown below.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Define revert event</span></span> <span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> StorageRoutedToL2</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> contractL2</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> chainId</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"> Generic function in a contract</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setValue</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> node</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> value</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-comment"> //</span><span class="z-comment"> Get metadata from on-chain sources</span></span> <span class="giallo-l"><span> (</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> contractL2</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Contract address on L2; may be globally constant</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> chainId </span><span class="z-comment">//</span><span class="z-comment"> L2 ChainID; may be globally constant</span></span> <span class="giallo-l"><span> )</span><span class="z-keyword"> =</span><span class="z-entity z-name"> getMetadata</span><span>(</span><span>node</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Arbitrary code</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> contractL2 = 0x32f94e75cde5fa48b6469323742e6004d701409b</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> chainId = 21</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Route storage call to L2 router</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> StorageRoutedToL2</span><span>(</span><span> </span></span> <span class="giallo-l"><span> contractL2</span><span>,</span></span> <span class="giallo-l"><span> chainId</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p>In this example, the routing must prompt the client to build the transaction with the exact same original calldata, and submit it to the L2 by calling the exact same function on L2 as L1.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Function in L2 contract</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setValue</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> node</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> value</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-comment"> //</span><span class="z-comment"> Some code storing data mapped by node &amp; msg.sender</span></span> <span class="giallo-l"><span> .</span><span>.</span><span>.</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><img src="https://wg-eips.ritovision.com/7700/./assets/images/L2.svg" alt="Fig.3 L2 Call Lifecycle" /></p> <h3 id="database-router-storageroutedtodatabase">Database Router: <code>StorageRoutedToDatabase()</code></h3> <p>A minimal database router is similar to an L2 in the sense that:</p> <p>a) Similar to <code>chainId</code>, it requires the <code>gatewayUrl</code> that is tasked with handling off-chain storage operations, and</p> <p>b) Similar to <code>eth_call</code>, it requires <code>eth_sign</code> output to secure the data, and the client must prompt the users for these signatures.</p> <p>This specification does not require any other data to be stored on L1 other than the bespoke <code>gatewayUrl</code>; the storage router therefore should only return the <code>gatewayUrl</code> in revert.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> StorageRoutedToDatabase</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> gatewayUrl</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"> Generic function in a contract</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setValue</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> node</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> value</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> <span class="giallo-l"><span class="z-support"> string</span><span> gatewayUrl </span><span class="z-comment">//</span><span class="z-comment"> Gateway URL; may be globally constant</span></span> <span class="giallo-l"><span> )</span><span class="z-keyword"> =</span><span class="z-entity z-name"> getMetadata</span><span>(</span><span>node</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> gatewayUrl = &quot;https://api.namesys.xyz&quot;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Route storage call to database router</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> StorageRoutedToDatabase</span><span>(</span><span> </span></span> <span class="giallo-l"><span> gatewayUrl</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p><img src="https://wg-eips.ritovision.com/7700/./assets/images/Database.svg" alt="Fig.4 Database Call Lifecycle" /></p> <p>Following the revert, the client must take these steps:</p> <ol> <li> <p>Request the user for a secret signature <code>sigKeygen</code> to generate a deterministic <code>dataSigner</code> keypair,</p> </li> <li> <p>Sign the calldata with generated data signer's private key and produce verifiable data signature <code>dataSig</code>,</p> </li> <li> <p>Request the user for an <code>approval</code> approving the generated data signer, and finally,</p> </li> <li> <p>Post the calldata to gateway along with signatures <code>dataSig</code> and <code>approval</code>, and the <code>dataSigner</code>.</p> </li> </ol> <p>These steps are described in detail below.</p> <h4 id="1-generate-data-signer">1. Generate Data Signer</h4> <p>The data signer must be generated deterministically from ethereum wallet signatures; see figure below.</p> <p><img src="https://wg-eips.ritovision.com/7700/./assets/images/Keygen.svg" alt="Fig.5 Data Signer Keygen Workflow" /></p> <p>The deterministic key generation can be implemented concisely in a single unified <code>keygen()</code> function as follows.</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"> Pseudo-code for key generation </span><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"> keygen</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> username</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> CAIP identifier for the blockchain account</span></span> <span class="giallo-l"><span class="z-variable"> sigKeygen</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Deterministic signature from wallet</span></span> <span class="giallo-l"><span class="z-variable"> spice</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Stretched password</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"> Calculate input key by hashing signature bytes using SHA256 algorithm</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> inputKey</span><span class="z-keyword"> =</span><span class="z-entity z-name"> sha256</span><span>(</span><span class="z-variable z-other">sigKeygen</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Calculate salt for keygen by hashing concatenated username, stretched password (aka spice) and hex-encoded signature using SHA256 algorithm</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> salt</span><span class="z-keyword"> =</span><span class="z-entity z-name"> sha256</span><span>(</span><span class="z-punctuation z-definition z-string">`</span><span class="z-string">${</span><span class="z-variable z-other">username</span><span class="z-string">}</span><span class="z-string">:</span><span class="z-string">${</span><span class="z-variable z-other">spice</span><span class="z-string">}</span><span class="z-string">:</span><span class="z-string">${</span><span class="z-variable z-other">sigKeygen</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 class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Calculate hash key output by feeding input key, salt &amp; username to the HMAC-based key derivation function (HKDF) with dLen = 42</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> hashKey</span><span class="z-keyword"> =</span><span class="z-entity z-name"> hkdf</span><span>(</span><span class="z-variable z-other">sha256</span><span>,</span><span class="z-variable z-other"> inputKey</span><span>,</span><span class="z-variable z-other"> salt</span><span>,</span><span class="z-variable z-other"> username</span><span>,</span><span class="z-constant"> 42</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Calculate and return secp256k1 keypair</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> secp256k1</span><span>(</span><span class="z-variable z-other">hashKey</span><span>)</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Calculate secp256k1 keypair from hash key</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This <code>keygen()</code> function requires three variables: <code>username</code>, <code>spice</code> and <code>sigKeygen</code>. Their definitions are given below.</p> <h5 id="1-username">1. <code>username</code></h5> <p><a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/ad0cfebc45a4b8368628340bf22aefb2a5edcab7/CAIPs/caip-10.md">CAIP-10</a> identifier <code>username</code> is auto-derived from the connected wallet's checksummed address <code>wallet</code> and <code>chainId</code> using <a href="https://wg-eips.ritovision.com/155/">EIP-155</a>.</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"> CAIP-10 identifier </span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> caip10</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> `</span><span class="z-string">eip155:</span><span class="z-string">${</span><span class="z-variable z-other">chainId</span><span class="z-string">}</span><span class="z-string">:</span><span class="z-string">${</span><span class="z-variable z-other">wallet</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">`</span><span>;</span></span></code></pre><h5 id="2-spice">2. <code>spice</code></h5> <p><code>spice</code> is calculated from the optional private field <code>password</code>, which must be prompted from the user by the client; this field allows users to change data signers for a given <code>username</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 class="z-comment"> Secret derived key identifier </span><span class="z-punctuation z-definition z-comment">*/</span><span> </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Clients must prompt the user for this</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> password</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">key1</span><span class="z-punctuation z-definition z-string">&#39;</span><span>;</span></span></code></pre> <p>Password must then be stretched before use with <code>PBKDF2</code> algorithm such that:</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"> Calculate spice by stretching password </span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">let</span><span class="z-variable z-other"> spice</span><span class="z-keyword"> =</span><span class="z-entity z-name"> pbkdf2</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> password</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> pepper</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> iterations</span></span> <span class="giallo-l"><span> )</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Stretch password with PBKDF2</span></span></code></pre> <p>where <code>pepper = keccak256(abi.encodePacked(username))</code> and the <code>iterations</code> count is fixed to <code>500,000</code> for brute-force vulnerability protection.</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"> Definitions of pepper and iterations in PBKDF2 </span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">let</span><span class="z-variable z-other"> pepper</span><span class="z-keyword"> =</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-variable z-other">username</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"> iterations</span><span class="z-keyword"> =</span><span class="z-constant"> 500000</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 500,000 iterations</span></span></code></pre><h5 id="3-sigkeygen">3. <code>sigKeygen</code></h5> <p>The data signer must be derived from the owner or manager keys of a node. Message payload for the required <code>sigKeygen</code> must then be formatted as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Requesting Signature To Generate Keypair(s)\n\nOrigin: ${username}\nProtocol: ${protocol}\nExtradata: ${extradata}</span></span></code></pre> <p>where the <code>extradata</code> is calculated as follows,</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Calculating extradata in keygen signatures</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span> extradata </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> spice</span></span> <span class="giallo-l"><span> wallet</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>The remaining <code>protocol</code> field is a protocol-specific identifier limiting the scope to a specific protocol represented by a unique contract address. This identifier cannot be global and must be uniquely defined for each implementating L1 <code>contract</code> such that:</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"> Protocol identifier in CAIP-10 format </span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> protocol</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> `</span><span class="z-string">eth:</span><span class="z-string">${</span><span class="z-variable z-other">chainId</span><span class="z-string">}</span><span class="z-string">:</span><span class="z-string">${</span><span class="z-variable z-other">contract</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">`</span><span>;</span></span></code></pre> <p>With this deterministic format for signature message payload, the client must prompt the user for the ethereum signature. Once the user signs the messages, the <code>keygen()</code> function can derive the data signer keypair.</p> <h4 id="2-sign-data">2. Sign Data</h4> <p>Since the derived signer is wallet-specific, it can</p> <ul> <li>sign batch data for multiple keys for a given node, and</li> <li>sign batches of data for multiple nodes owned by a wallet</li> </ul> <p>simultaneously in the background without ever prompting the user. Signature(s) <code>dataSig</code> accompanying the off-chain calldata must implement the following format in their message payloads:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Requesting Signature To Update Off-Chain Data\n\nOrigin: ${username}\nData Type: ${dataType}\nData Value: ${dataValue}</span></span></code></pre> <p>where <code>dataType</code> parameters are protocol-specific and formatted as object keys delimited by <code>/</code>. For instance, if the off-chain data is nested in keys as <code>a &gt; b &gt; c &gt; field &gt; key</code>, then the equivalent <code>dataType</code> is <code>a/b/c/field/key</code>. For example, in order to update off-chain ENS record <code>text &gt; avatar</code> and <code>address &gt; 60</code>, <code>dataType</code> must be formatted as <code>text/avatar</code> and <code>address/60</code> respectively.</p> <h4 id="3-approve-data-signer">3. Approve Data Signer</h4> <p>The <code>dataSigner</code> is not stored on L1, and the clients must instead</p> <ul> <li>request an <code>approval</code> signature for <code>dataSigner</code> signed by the owner or manager of a node, and</li> <li>post this <code>approval</code> and the <code>dataSigner</code> along with the signed calldata in encoded form.</li> </ul> <p>CCIP-Read-enabled contracts can then verify during resolution time that the <code>approval</code> attached with the signed calldata comes from the node's manager or owner, and that it approves the expected <code>dataSigner</code>. The <code>approval</code> signature must have the following message payload format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Requesting Signature To Approve Data Signer\n\nOrigin: ${username}\nApproved Signer: ${dataSigner}\nApproved By: ${caip10}</span></span></code></pre> <p>where <code>dataSigner</code> must be checksummed.</p> <h4 id="4-post-ccip-read-compatible-payload">4. Post CCIP-Read Compatible Payload</h4> <p>The final <a href="https://wg-eips.ritovision.com/3668/">EIP-3668</a>-compatible <code>data</code> payload in the off-chain data file is identified by a fixed <code>callback.signedData.selector</code> equal to <code>0x2b45eb2b</code> and must follow the format</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/*</span><span class="z-comment"> Compile CCIP-Read-compatible payload</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span> encodedData </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span><span>[</span><span class="z-string">&#39;bytes&#39;</span><span>]</span><span>,</span><span> [</span><span>dataValue</span><span>]</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Encode data</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span> funcSelector </span><span class="z-keyword">=</span><span> callback</span><span>.</span><span>signedData</span><span>.</span><span>selector</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Identify off-chain data with a fixed &#39;signedData&#39; selector = &#39;0x2b45eb2b&#39;</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span> data </span><span class="z-keyword">=</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> [</span><span class="z-string">&#39;bytes4&#39;</span><span>,</span><span class="z-string"> &#39;address&#39;</span><span>,</span><span class="z-string"> &#39;bytes32&#39;</span><span>,</span><span class="z-string"> &#39;bytes32&#39;</span><span>,</span><span class="z-string"> &#39;bytes&#39;</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>funcSelector</span><span>,</span><span> dataSigner</span><span>,</span><span> dataSig</span><span>,</span><span> approval</span><span>,</span><span> encodedData</span><span>]</span></span> <span class="giallo-l"><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Compile complete CCIP-Readable off-chain data</span></span></code></pre> <p>The client must construct this <code>data</code> and pass it to the gateway in the <code>POST</code> request along with the raw values for indexing. The CCIP-Read-enabled contracts after decoding the four parameters from this <code>data</code> must</p> <ul> <li>verify that the <code>dataSigner</code> is approved by the owner or manager of the node through <code>approval</code>, and</li> <li>verify that the <code>dataSig</code> is produced by <code>dataSigner</code></li> </ul> <p>before resolving the <code>encodedData</code> value in decoded form.</p> <h5 id="post-request"><code>POST</code> Request</h5> <p>The <code>POST</code> request made by the client to the <code>gatewayUrl</code> must follow the format as described below.</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">/*</span><span class="z-comment"> POST request format</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> Post</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> node</span><span class="z-keyword">:</span><span class="z-support"> string</span></span> <span class="giallo-l"><span class="z-variable"> preimage</span><span class="z-keyword">:</span><span class="z-support"> string</span></span> <span class="giallo-l"><span class="z-variable"> chainId</span><span class="z-keyword">:</span><span class="z-support"> number</span></span> <span class="giallo-l"><span class="z-variable"> approval</span><span class="z-keyword">:</span><span class="z-support"> string</span></span> <span class="giallo-l"><span class="z-variable"> payload</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> field1</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span></span> <span class="giallo-l"><span class="z-variable"> signature</span><span class="z-keyword">:</span><span class="z-support"> string</span></span> <span class="giallo-l"><span class="z-variable"> timestamp</span><span class="z-keyword">:</span><span class="z-support"> number</span></span> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">:</span><span class="z-support"> string</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-variable"> field2</span><span class="z-keyword">:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable"> index</span><span class="z-keyword">:</span><span class="z-support"> number</span></span> <span class="giallo-l"><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span></span> <span class="giallo-l"><span class="z-variable"> signature</span><span class="z-keyword">:</span><span class="z-support"> string</span></span> <span class="giallo-l"><span class="z-variable"> timestamp</span><span class="z-keyword">:</span><span class="z-support"> number</span></span> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">:</span><span class="z-support"> string</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span class="z-variable"> field3</span><span class="z-keyword">:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable"> key</span><span class="z-keyword">:</span><span class="z-support"> number</span></span> <span class="giallo-l"><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span></span> <span class="giallo-l"><span class="z-variable"> signature</span><span class="z-keyword">:</span><span class="z-support"> string</span></span> <span class="giallo-l"><span class="z-variable"> timestamp</span><span class="z-keyword">:</span><span class="z-support"> number</span></span> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">:</span><span class="z-support"> string</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>Example of a complete <code>Post</code> typed object for updating multiple ENS records for a node is shown below.</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">/*</span><span class="z-comment"> Example of a POST request </span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">let</span><span class="z-variable z-other"> post</span><span class="z-keyword">:</span><span class="z-entity z-name"> Post</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span> node</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe8e5c24bb5f0db1f3cab7d3a7af2ecc14a7a4e3658dfb61c9b65a099b5f086fb</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> preimage</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">dev.namesys.eth</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-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span> approval</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xa94da8233afb27d087f6fbc667cc247ef2ed31b5a1ff877ac823b5a2e69caa49069f0daa45a464d8db2f8e4e435250cb446d8f279d45a2b865ebf2fff291f69f1c</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> payload</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> contenthash</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> value</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ipfs://QmYSFDzEcmk25JPFrHBHSMMLcTKLm6SvuZvKpijTHBnAYX</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x24730d1d85d556245b7766aef413188e22f219c8de263ccbfafee4413f0937c32e4f44068d84c7424f923b878dcf22184f8df86506de1cea3dad932c5bd5e9de1c</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> timestamp</span><span>:</span><span class="z-constant"> 1708322868</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x2b45eb2b000000000000000000000000fe889053f7a0d2571f1898d2835c3cbdf50d766b000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000180000000000000000000000000000000000000000000000000000000000000004124730d1d85d556245b7766aef413188e22f219c8de263ccbfafee4413f0937c32e4f44068d84c7424f923b878dcf22184f8df86506de1cea3dad932c5bd5e9de1c000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000041a94da8233afb27d087f6fbc667cc247ef2ed31b5a1ff877ac823b5a2e69caa49069f0daa45a464d8db2f8e4e435250cb446d8f279d45a2b865ebf2fff291f69f1c00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000026e301017012209603ccbcef5c2acd57bdec6a63e8a0292f3ce6bb583b6826060bcdc3ea84ad900000000000000000000000000000000000000000000000000000</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> address</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> coinType</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span> value</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">1FfmbHfnpaZjKFvyi1okTjJJusN455paPH</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x60ecd4979ae2c39399ffc7ad361066d46fc3d20f2b2902c52e01549a1f6912643c21d23d1ad817507413dc8b73b59548840cada57481eb55332c4327a5086a501b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> timestamp</span><span>:</span><span class="z-constant"> 1708322877</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x2b45eb2b000000000000000000000000fe889053f7a0d2571f1898d2835c3cbdf50d766b000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000180000000000000000000000000000000000000000000000000000000000000004160ecd4979ae2c39399ffc7ad361066d46fc3d20f2b2902c52e01549a1f6912643c21d23d1ad817507413dc8b73b59548840cada57481eb55332c4327a5086a501b000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000041a94da8233afb27d087f6fbc667cc247ef2ed31b5a1ff877ac823b5a2e69caa49069f0daa45a464d8db2f8e4e435250cb446d8f279d45a2b865ebf2fff291f69f1c000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000020000000000000000000000000a0e6ca5444e4d8b7c80f70237f332320387f18c7</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> coinType</span><span>:</span><span class="z-constant"> 60</span><span>,</span></span> <span class="giallo-l"><span> value</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x47C10B0491A138Ddae6cCfa26F17ADCfCA299753</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xaad74ddef8c031131b6b83b3bf46749701ed11aeb585b63b72246c8dab4fff4f79ef23aea5f62b227092719f72f7cfe04f3c97bfad0229c19413f5cb491e966c1b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> timestamp</span><span>:</span><span class="z-constant"> 1708322917</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x2b45eb2b000000000000000000000000fe889053f7a0d2571f1898d2835c3cbdf50d766b0000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000001800000000000000000000000000000000000000000000000000000000000000041aad74ddef8c031131b6b83b3bf46749701ed11aeb585b63b72246c8dab4fff4f79ef23aea5f62b227092719f72f7cfe04f3c97bfad0229c19413f5cb491e966c1b000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000041a94da8233afb27d087f6fbc667cc247ef2ed31b5a1ff877ac823b5a2e69caa49069f0daa45a464d8db2f8e4e435250cb446d8f279d45a2b865ebf2fff291f69f1c00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002000000000000000000000000047c10b0491a138ddae6ccfa26f17adcfca299753</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> text</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> key</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">avatar</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> value</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://namesys.xyz/logo.png</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xbc3c7f1b511de151bffe8df033859295d83d400413996789e706e222055a2353404ce17027760c927af99e0bf621bfb24d3bfc52abb36bcfbe6e20cf43db7c561b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> timestamp</span><span>:</span><span class="z-constant"> 1708329377</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x2b45eb2b000000000000000000000000fe889053f7a0d2571f1898d2835c3cbdf50d766b0000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000001800000000000000000000000000000000000000000000000000000000000000041bc3c7f1b511de151bffe8df033859295d83d400413996789e706e222055a2353404ce17027760c927af99e0bf621bfb24d3bfc52abb36bcfbe6e20cf43db7c561b000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000041a94da8233afb27d087f6fbc667cc247ef2ed31b5a1ff877ac823b5a2e69caa49069f0daa45a464d8db2f8e4e435250cb446d8f279d45a2b865ebf2fff291f69f1c0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000001c68747470733a2f2f6e616d657379732e78797a2f6c6f676f2e706e6700000000</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> key</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">com.github</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> value</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">namesys-eth</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xc9c33ff219e90510f79b6c9bb489917ee6e00ab123c55abe1117e71ea0d171356cf316420c71cfcf4bd63a791aaf37388ef1832e582f54a8c2df173917240fff1b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> timestamp</span><span>:</span><span class="z-constant"> 1708322898</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x2b45eb2b000000000000000000000000fe889053f7a0d2571f1898d2835c3cbdf50d766b0000000000000000000000000000000000000000000000000000000000000080000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000001800000000000000000000000000000000000000000000000000000000000000041c9c33ff219e90510f79b6c9bb489917ee6e00ab123c55abe1117e71ea0d171356cf316420c71cfcf4bd63a791aaf37388ef1832e582f54a8c2df173917240fff1b000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000041a94da8233afb27d087f6fbc667cc247ef2ed31b5a1ff877ac823b5a2e69caa49069f0daa45a464d8db2f8e4e435250cb446d8f279d45a2b865ebf2fff291f69f1c0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000b6e616d657379732d657468000000000000000000000000000000000000000000</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><h3 id="new-revert-events">New Revert Events</h3> <ol> <li> <p>Each new storage router must submit their <code>StorageRoutedTo__()</code> identifier through an ERC track proposal referencing the current document.</p> </li> <li> <p>Each <code>StorageRoutedTo__()</code> provider must be supported with detailed documentation of its structure and the necessary metadata that its implementers must return.</p> </li> <li> <p>Each <code>StorageRoutedTo__()</code> proposal must define the precise formatting of any message payloads that require signatures and complete descriptions of custom cryptographic techniques implemented for additional security, accessibility or privacy.</p> </li> </ol> <h3 id="implementation-featuring-ens-on-l2-database">Implementation featuring ENS on L2 &amp; Database</h3> <p>ENS off-chain resolvers capable of reading from and writing to databases are perhaps the most common use-case for CCIP-Read and CCIP-Write. One example of such a (minimal) resolver is given below along with the client-side code for handling the storage router revert.</p> <h4 id="l1-contract">L1 Contract</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/*</span><span class="z-comment"> ENS resolver implementing StorageRoutedToDatabase() </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> iResolver</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Defined in EIP-7700</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> StorageRoutedToL2</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> chainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> contractL2</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> StorageRoutedToDatabase</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> gatewayUrl</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Defined in EIP-137</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"> addr</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-comment">//</span><span class="z-comment"> Defined in EIP-7700</span></span> <span class="giallo-l"><span class="z-support">string</span><span class="z-storage z-type"> public</span><span> gatewayUrl </span><span class="z-keyword">=</span><span class="z-string"> &quot;https://post.namesys.xyz&quot;</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> RESTful API endpoint</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> public</span><span> chainId </span><span class="z-keyword">=</span><span class="z-support"> uint</span><span>(</span><span class="z-constant">21</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> ChainID of L2</span></span> <span class="giallo-l"><span class="z-support">address</span><span class="z-storage z-type"> public</span><span> contractL2 </span><span class="z-keyword">=</span><span class="z-string"> &quot;0x839B3B540A9572448FD1B2335e0EB09Ac1A02885&quot;</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Contract on L2</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 ethereum address associated with an ENS node</span></span> <span class="giallo-l"><span class="z-comment">* [!] May only be called by the owner or manager of that node in 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"> Namehash of ENS domain 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"> addr</span><span class="z-comment"> Ethereum 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> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> node</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-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-comment"> //</span><span class="z-comment"> Route to database storage</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> StorageRoutedToDatabase</span><span>(</span></span> <span class="giallo-l"><span> gatewayUrl</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-comment">/**</span></span> <span class="giallo-l"><span class="z-comment">* Sets the avatar text record associated with an ENS node</span></span> <span class="giallo-l"><span class="z-comment">* [!] May only be called by the owner or manager of that node in 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"> Namehash of ENS domain 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"> key</span><span class="z-comment"> Key for ENS text 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"> value</span><span class="z-comment"> URL to avatar</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"> setText</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> node</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> value</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-comment"> //</span><span class="z-comment"> Verify owner or manager permissions</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">authorised</span><span>(</span><span>node</span><span>)</span><span>,</span><span class="z-string"> &quot;NOT_ALLOWED&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Route to L2 storage</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> StorageRoutedToL2</span><span>(</span></span> <span class="giallo-l"><span> chainId</span><span>,</span><span> </span></span> <span class="giallo-l"><span> contractL2</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="l2-contract">L2 Contract</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Function in L2 contract</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setText</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> node</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> value</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-comment"> //</span><span class="z-comment"> Store record mapped by node &amp; sender</span></span> <span class="giallo-l"><span> records</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>node</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span>)</span><span>]</span><span>[</span><span class="z-string">&quot;text&quot;</span><span>]</span><span>[</span><span>key</span><span>]</span><span class="z-keyword"> =</span><span> value</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="client-side-code">Client-side Code</h4> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">/*</span><span class="z-comment"> Client-side pseudo-code in ENS App </span><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"> Deterministically generate signer keypair</span></span> <span class="giallo-l"><span class="z-storage z-type">let</span><span class="z-variable z-other"> signer</span><span class="z-keyword"> =</span><span class="z-entity z-name"> keygen</span><span>(</span><span class="z-variable z-other">username</span><span>,</span><span class="z-variable z-other"> sigKeygen</span><span>,</span><span class="z-variable z-other"> spice</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Construct POST body by signing calldata with derived private key</span></span> <span class="giallo-l"><span class="z-storage z-type">let</span><span class="z-variable z-other"> post</span><span class="z-keyword">:</span><span class="z-entity z-name"> Post</span><span class="z-keyword"> =</span><span class="z-entity z-name"> signData</span><span>(</span><span class="z-variable z-other">node</span><span>,</span><span class="z-variable z-other"> addr</span><span>,</span><span class="z-variable z-other"> signer</span><span>.</span><span class="z-variable z-other">priv</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> POST to gateway</span></span> <span class="giallo-l"><span class="z-keyword">await</span><span class="z-entity z-name"> fetch</span><span>(</span><span class="z-variable z-other">gatewayUrl</span><span>,</span><span> {</span></span> <span class="giallo-l"><span> method</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> body</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">post</span><span>)</span></span> <span class="giallo-l"><span>}</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Technically, the cases of L2s and databases are similar; routing to an L2 involves routing the <code>eth_call</code> to another EVM, while routing to a database can be made by extracting <code>eth_sign</code> from <code>eth_call</code> and posting the resulting signature explicitly along with the data for later verification. Methods in this document perform these precise tasks when routing storage operations to external routers. In addition, methods such as signing data with a derived signer (for databases) allow for significant UX improvement by fixing the number of signature prompts in wallets to 2, irrespective of the number of data instances to sign per node or the total number of nodes to update. This improvement comes at no additional cost to the user and allows services to perform batch updates.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>None</p> <h2 id="security-considerations">Security Considerations</h2> <ol> <li> <p>Clients must purge the derived signer private keys from local storage immediately after signing the off-chain data.</p> </li> <li> <p>Signature message payload and the resulting deterministic signature <code>sigKeygen</code> must be treated as a secret by the clients and immediately purged from local storage after usage in the <code>keygen()</code> function.</p> </li> <li> <p>Clients must immediately purge the <code>password</code> and <code>spice</code> from local storage after usage in the <code>keygen()</code> function.</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> 2024-04-26T00:00:00+00:00 2026-02-11T14:48:25+00:00 Radek Svarzhttps://github.com/radeksvarz https://wg-eips.ritovision.com/7699/

Include a unique identifier (transfer or "payment" reference) for each ERC-20 transaction to associate transfers with orders/invoices.

<h2 id="abstract">Abstract</h2> <p>The <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token standard does not provide a built-in mechanism for including a payment transfer reference (message for recipient) in token transfers. This proposal extends the existing ERC-20 token standard by adding minimal methods to include a transfer reference in token transfers and transferFrom operations. The addition of a reference can help users, merchants, and service providers to associate and reconcile individual transactions with specific orders or invoices.</p> <h2 id="motivation">Motivation</h2> <p>The primary motivation for this proposal is to improve the functionality of the ERC-20 token standard by providing a mechanism for including a payment reference in token transfers, similar to the traditional finance systems where payment references are commonly used to associate and reconcile transactions with specific orders, invoices or other financial records.</p> <p>Currently, users and merchants who want to include a payment reference in their transactions must rely on off chain external systems or custom payment proxy implementations. In traditional finance systems, payment references are often included in wire transfers and other types of electronic payments, making it easy for users and merchants to manage and reconcile their transactions. Such as:</p> <ul> <li>SWIFT MT103: field 70 “Remittance Information” is commonly used for such content (e.g " PAYMENT FOR INVOICE 998877"). There is also field 72 “Sender to receiver information”.</li> <li>ISO 20022 (for SEPA): PAIN.001 has field called RmtInf (Remittance Information)</li> </ul> <p>By extending the existing ERC-20 token standard with payment transfer reference capabilities, this proposal will help bridge the gap between traditional finance systems and the world of decentralized finance, providing a more seamless experience for users, merchants, and service providers alike.</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>Any contract complying with ERC-20 when extended with this ERC, MUST implement the following interface:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// The EIP-165 identifier of this interface is 0x1522573a</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>interface IERC7699 {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function transfer(address to, uint256 amount, bytes calldata transferReference) external returns (bool);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function transferFrom(address from, address to, uint256 amount, bytes calldata transferReference) external returns (bool);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>event TransferReference(bytes32 indexed loggedReference);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>These <code>transfer</code> and <code>transferFrom</code> functions, in addition to the standard transfer behaviour, MUST emit a <code>transferReference</code> event with a <code>loggedReference</code> parameter (with only exception defined below).</p> <p>The corresponding ERC-20 <code>Transfer</code> event MUST be emitted following the <code>TransferReference</code> event, ideally immediately afterwards for the client to be able to seek the associated <code>Transfer</code> event log record.</p> <p>Emitted <code>loggedReference</code> MAY be the exact copy of the <code>transferReference</code> (when less then 33 bytes) or the derived data from the rich <code>transferReference</code> structure and other processing. This is up to the implementer. One MUST NOT expect the <code>transferReference</code> and <code>loggedReference</code> data to be equal.</p> <p>The <code>loggedReference</code> parameter MAY contain any data of bytes32 type.</p> <p>The <code>transferReference</code> parameter MAY be empty. In this case and only in this case the <code>TransferReference</code> event MUST NOT be emitted, effectively mimicking the regular ERC-20 transfer without any transfer reference.</p> <p>The <code>transferReference</code> parameter is not limited in length by design, users are motivated to keep it short due to calldata and execution gas costs.</p> <p>The <code>TransferReference</code> event MUST NOT be declared with the <code>anonymous</code> specifier. This is to ensure that the event signature is logged and can be used as a filter.</p> <p>Transfers of 0 amount MUST be treated as normal transfers and fire the <code>TransferReference</code> event alike.</p> <h2 id="rationale">Rationale</h2> <h3 id="parameter-name">Parameter name</h3> <p>The choice to name the added parameter <code>transferReference</code> was made to align with traditional banking terminology, where payment references are widely used to associate and reconcile transactions with specific orders, invoices or other financial records.</p> <p>The <code>transferReference</code> parameter name also helps to clearly communicate the purpose of the parameter and its role in facilitating the association and reconciliation of transactions. By adopting terminology that is well-established in the financial industry, the proposal aims to foster a greater understanding and adoption of the extended ERC-20 token standard.</p> <h3 id="parameter-type">Parameter type</h3> <p>The <code>transferReference</code> type is bytes.</p> <p>The <code>transferReference</code> type was initially considered to be bytes32 in order to motivate users to either use short references (as is common in TradFi) or rather use Keccak 256 hash of the reference content. Conclusion was that the options should rather be kept open to be able to call with structured data; such as passing reference data including a signature enabling extra processing checks.</p> <h3 id="emitted-data">Emitted data</h3> <p>The <code>loggedReference</code> type is bytes32.</p> <p>It was considered to log a reference in the form of <code>bytes calldata</code>. However, the reference content would be hashed in the event log due to the log topic indexing required for the even subscription filters. The resulting logged topic is always in the form of bytes32. Bytes32 type enables to log publicly readable (non hashed) reference content up to 32 bytes long.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This extension is fully backwards compatible with the existing ERC-20 token standard. The new functions can be used alongside the existing transfer and transferFrom functions. Existing upgradable ERC-20 tokens can be upgraded to include the new functionality without impact on the storage layout; new ERC-20 tokens can choose to implement the payment reference features based on their specific needs.</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: CC0-1.0</span></span> <span class="giallo-l"><span>pragma solidity &gt;=0.8.4 &lt;0.9.0;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>import {ERC20} from &quot;@openzeppelin/token/ERC20/ERC20.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>interface IERC7699 {</span></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Emitted when a non-empty `transferReference` is added to the `transfer` call.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event TransferReference(bytes32 indexed loggedReference);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Moves `amount` tokens from the caller&#39;s account to `to` with `transferReference`.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @dev Returns a boolean value indicating whether the operation succeeded.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * MUST emit this ERCS&#39;s {TransferReference} event followed by a corresponding {ERC20.Transfer} event</span></span> <span class="giallo-l"><span> * (to comply with ERC-20).</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function transfer(address to, uint256 amount, bytes calldata transferReference) external returns (bool);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Moves `amount` tokens from `from` to `to` with `transferReference` using the</span></span> <span class="giallo-l"><span> * allowance mechanism. `amount` is then deducted from the caller&#39;s allowance.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @dev Returns a boolean value indicating whether the operation succeeded.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * MUST emit this ERCS&#39;s {TransferReference} event followed by a corresponding {ERC20.Transfer} event</span></span> <span class="giallo-l"><span> * (to comply with ERC-20).</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function transferFrom(address from, address to, uint256 amount, bytes calldata transferReference)</span></span> <span class="giallo-l"><span> external</span></span> <span class="giallo-l"><span> returns (bool);</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> * @dev Implementation of the ERC20 transfer reference extension.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>contract ERC20TransferReference is ERC20, IERC7699 {</span></span> <span class="giallo-l"><span> constructor() ERC20(&quot;ERC20 Transfer Reference Example&quot;, &quot;TXRE&quot;) {</span></span> <span class="giallo-l"><span> _mint(msg.sender, 987654321 * 1e18);</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> * @dev Emits `TransferReference` event with derived `loggedReference` data</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function _logReference(bytes calldata transferReference) internal virtual {</span></span> <span class="giallo-l"><span> // MUST NOT emit when transferReference is empty</span></span> <span class="giallo-l"><span> if (transferReference.length &gt; 0) {</span></span> <span class="giallo-l"><span> // Effectively extract first 32 bytes from transferReference calldata bytes</span></span> <span class="giallo-l"><span> // Note: This is the example. Derivation of the loggedReference is fully up to the implementation.</span></span> <span class="giallo-l"><span> // E.g. keccak hash of the whole transferReference, etc.</span></span> <span class="giallo-l"><span> bytes32 loggedReference;</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> loggedReference := calldataload(transferReference.offset)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> emit TransferReference(loggedReference);</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> <span class="giallo-l"><span> * @notice A standard ERC20 token transfer with an optional transfer reference</span></span> <span class="giallo-l"><span> * @dev The underlying `transfer` function is assumed to handle the actual token transfer logic.</span></span> <span class="giallo-l"><span> * @param to The address of the recipient where the tokens will be sent.</span></span> <span class="giallo-l"><span> * @param amount The number of tokens to be transferred.</span></span> <span class="giallo-l"><span> * @param transferReference A bytes field to include a transfer reference, reference signature or other relevant</span></span> <span class="giallo-l"><span> * reference data.</span></span> <span class="giallo-l"><span> * @return A boolean indicating whether the transfer was successful.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function transfer(address to, uint256 amount, bytes calldata transferReference) public virtual returns (bool) {</span></span> <span class="giallo-l"><span> _logReference(transferReference);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // ERC20.Transfer event is emitted immediately after TransferReference event</span></span> <span class="giallo-l"><span> return transfer(to, amount);</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> * @notice A delegated token transfer with an optional transfer reference</span></span> <span class="giallo-l"><span> * @dev Requires prior approval from the token owner. The underlying `transferFrom` function is assumed to handle</span></span> <span class="giallo-l"><span> * allowance and transfer logic.</span></span> <span class="giallo-l"><span> * @param from The address of the token owner who has authorized the transfer.</span></span> <span class="giallo-l"><span> * @param to The address of the recipient where the tokens will be sent.</span></span> <span class="giallo-l"><span> * @param amount The number of tokens to be transferred.</span></span> <span class="giallo-l"><span> * @param transferReference A bytes field to include a transfer reference, reference signature or other relevant</span></span> <span class="giallo-l"><span> * reference data.</span></span> <span class="giallo-l"><span> * @return A boolean indicating whether the transfer was successful.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function transferFrom(address from, address to, uint256 amount, bytes calldata transferReference)</span></span> <span class="giallo-l"><span> public</span></span> <span class="giallo-l"><span> virtual</span></span> <span class="giallo-l"><span> returns (bool)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> _logReference(transferReference);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // ERC20.Transfer event is emitted immediately after TransferReference event</span></span> <span class="giallo-l"><span> return transferFrom(from, to, amount);</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> <h3 id="privacy-considerations">Privacy Considerations</h3> <p>Reference data privacy: Including payment references in token transfers may expose sensitive information about the transaction or the parties involved. Implementers and users should carefully consider the privacy implications and ensure that payment references do not reveal sensitive information. To mitigate this risk, implementers can consider using encryption or other privacy-enhancing techniques to protect payment reference data.</p> <p>Example: With reference 0x20240002 logged, transaction is publicly exposing that this is related to the second invoice of the recipient in 2024.</p> <h3 id="manipulation-of-payment-references">Manipulation of payment references</h3> <p>There is no validation of the reference data dictated by this ERC. Malicious actors might attempt to manipulate payment references to mislead users, merchants, or service providers. This can lead to:</p> <ol> <li> <p><strong>Legal risks</strong>: The beneficiary may face legal and compliance risks if the attacker uses illicit funds, potentially impersonating or flagging the beneficiary of involvement in money laundering or other illicit activities.</p> </li> <li> <p><strong>Disputes and refunds</strong>: The user might discover they didn't make the payment, request a refund or raise a dispute, causing additional administrative work for the beneficiary.</p> </li> </ol> <p>To mitigate this risk, implementers can consider using methods to identify proper sender and to generate unique and verifiable related payment references. However such implementations are not in the scope of this standard and rather extend 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> 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-18T00:00:00+00:00 2026-02-11T14:48:26+00:00 Avneet Singhhttps://github.com/sshmatrix 0xc0de4c0ffeehttps://github.com/0xc0de4c0ffee https://wg-eips.ritovision.com/7694/

Cross-chain storage router protocol incorporating storage router for Solana

<h2 id="abstract">Abstract</h2> <p>The following standard is an extension to the cross-chain storage router protocol introducing the storage router for Solana blockchain. With this specification, any Ethereum L1 contract can defer a call to Solana blockchain as part of its core functionality, provided that the client is equipped to handle Solana transactions. It was previously possible to defer write and storage operations to other Ethereum L1 contracts, L2 contracts and off-chain databases, and this document extends that functionality to include alternative L1 chains. The data stored on Solana must be translated to <a href="https://wg-eips.ritovision.com/3668/">EIP-3668</a>-compliant format by an appropriate HTTP gateway where it can be retrieved by generic Ethereum contracts. This standard allows Ethereum to utilise a broader range of cross-chain blockspaces.</p> <h2 id="motivation">Motivation</h2> <p>Cross-Chain Storage Router Protocol (CCIP-Store) introduced in <a href="https://wg-eips.ritovision.com/7700/">EIP-7700</a>, describes three external routers for routing storage to L1 contracts, L2s and databases. This document extends that specification by introducing a fourth storage router targeting Solana as the storage provider.</p> <p>L2s and databases both have centralising catalysts in their stack. For L2s, this centralising agent is the shared security with Ethereum mainnet. In case of databases, the centralising agent is trivial; it is the physical server hosting the database. In light of this, a storage provider that relies on its own independent consensus mechanism is preferred. This specification instructs how the clients should treat storage calls made to the Solana router.</p> <p>Solana is a low cost L1 solution that is supported alongside Ethereum by multiple wallet providers. There are several chain-agnostic protocols on Ethereum which could benefit from direct access to Solana blockspace; ENS is one such example where it can serve users of Solana via its chain-agnostic properties while also using Solana's own native storage. This development will encourage more cross-chain functionalities between Ethereum and Solana at core.</p> <p><img src="https://wg-eips.ritovision.com/7694/./assets/images/Schema.svg" alt="Fig.1 CCIP-Store and CCIP-Read Workflows" /></p> <h2 id="specification">Specification</h2> <p>A Solana storage router <code>StorageRoutedToSolana()</code> requires the hex-encoded <code>programId</code> and the manager <code>account</code> on the Solana blockchain. <code>programId</code> is equivalent to a contract address on Solana while <code>account</code> is the manager wallet on Solana handling storage on behalf of <code>msg.sender</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Revert handling Solana storage router</span></span> <span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> StorageRoutedToSolana</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> programId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> account</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"> Generic function in a contract</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setValue</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> node</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> value</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-comment"> //</span><span class="z-comment"> Get metadata from on-chain sources</span></span> <span class="giallo-l"><span> (</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> programId</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Program (= contract) address on Solana; hex-encoded</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> account </span><span class="z-comment">//</span><span class="z-comment"> Manager account on Solana; hex-encoded</span></span> <span class="giallo-l"><span> )</span><span class="z-keyword"> =</span><span class="z-entity z-name"> getMetadata</span><span>(</span><span>node</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Arbitrary code</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> programId = 0x37868885bbaf236c5d2e7a38952f709e796a1c99d6c9d142a1a41755d7660de3</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> account = 0xe853e0dcc1e57656bd760325679ea960d958a0a704274a5a12330208ba0f428f</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Route storage call to Solana router</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> StorageRoutedToSolana</span><span>(</span></span> <span class="giallo-l"><span> programId</span><span>,</span></span> <span class="giallo-l"><span> account</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p>Since Solana natively uses <code>base58</code> encoding in its virtual machine setup, <code>programId</code> values that are hex-encoded on EVM must be <code>base58</code>-decoded for usage on SVM. Clients implementing the Solana router must call the Solana <code>programId</code> using a Solana wallet that is connected to <code>account</code> using the <code>base58</code>-decoded (and casted to appropriate data type) calldata that it originally received.</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"> Pseudo-code to write to Solana program (= contract) </span><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"> Decode all &#39;bytes32&#39; types in EVM to &#39;PubKey&#39; type in SVM</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span> [</span><span class="z-variable z-other z-constant">programId</span><span>,</span><span class="z-variable z-other z-constant"> account</span><span>,</span><span class="z-variable z-other z-constant"> node</span><span>,</span><span class="z-variable z-other z-constant"> key</span><span>,</span><span class="z-variable z-other z-constant"> value</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> E2SVM</span><span>(</span></span> <span class="giallo-l"><span> [</span><span class="z-variable z-other">programId</span><span>,</span><span class="z-variable z-other"> account</span><span>,</span><span class="z-variable z-other"> node</span><span>,</span><span class="z-variable z-other"> key</span><span>,</span><span class="z-variable z-other"> value</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">bytes32</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">bytes32</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">bytes32</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">bytes32</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">bytes32</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-punctuation z-definition z-comment">//</span><span class="z-comment"> Instantiate program interface on Solana</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> program</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-entity z-name"> program</span><span>(</span><span class="z-variable z-other">programId</span><span>,</span><span class="z-variable z-other"> rpcProvider</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Connect to Solana wallet</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> wallet</span><span class="z-keyword"> =</span><span class="z-entity z-name"> useWallet</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"> Call the Solana program using connected wallet with initial calldata</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> [!] Only approved manager in the Solana program should call</span></span> <span class="giallo-l"><span class="z-keyword">if</span><span> (</span><span class="z-variable z-other">wallet</span><span>.</span><span class="z-variable z-other">publicKey</span><span class="z-keyword"> ===</span><span class="z-variable z-other"> account</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-entity z-name"> program</span><span>(</span><span class="z-variable z-other">wallet</span><span>)</span><span>.</span><span class="z-entity z-name">setValue</span><span>(</span><span class="z-variable z-other">node</span><span>,</span><span class="z-variable z-other"> key</span><span>,</span><span class="z-variable z-other"> value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>In the above example, EVM-specific <code>bytes32</code>-type variables <code>programId</code>, <code>account</code>, <code>node</code>, <code>key</code> and <code>value</code> must all be converted to SVM-specific <code>PubKey</code> data type. The equivalent <code>setValue()</code> function in the Solana program is of the form</p> <pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Example function in Solana program</span></span> <span class="giallo-l"><span class="z-keyword">pub</span><span class="z-keyword"> fn</span><span class="z-entity z-name"> setValue</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> ctx</span><span class="z-keyword">:</span><span class="z-entity z-name"> Context</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> node</span><span class="z-keyword">:</span><span class="z-entity z-name"> PubKey</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> key</span><span class="z-keyword">:</span><span class="z-entity z-name"> PubKey</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> value</span><span class="z-keyword">:</span><span class="z-entity z-name"> PubKey</span></span> <span class="giallo-l"><span>)</span><span class="z-keyword"> -&gt;</span><span class="z-entity z-name"> ProgramResult</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Code to verify PROGRAM_ID and rent exemption status</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"> Code for de-serialising, updating and re-serialising the data</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"> Store serialised data in account</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> [!] Stored data must be mapped by node &amp; account</span></span> <span class="giallo-l"><span class="z-keyword"> ...</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Since EVM and SVM have differing architectures, it is important to define precise data type castings from EVM to SVM. Some pre-existing custom but popular data types in SVM already equate to common EVM data types such as <code>PubKey</code> and <code>bytes32</code> respectively. This specification requires the following implementation of bijective EVM to SVM type casting:</p> <table><thead><tr><th style="text-align: center">EVM</th><th style="text-align: center">SVM</th></tr></thead><tbody> <tr><td style="text-align: center"><code>uint8</code></td><td style="text-align: center"><code>u8</code></td></tr> <tr><td style="text-align: center"><code>uint16</code></td><td style="text-align: center"><code>u16</code></td></tr> <tr><td style="text-align: center"><code>uint32</code></td><td style="text-align: center"><code>u32</code></td></tr> <tr><td style="text-align: center"><code>uint64</code></td><td style="text-align: center"><code>u64</code></td></tr> <tr><td style="text-align: center"><code>uint128</code></td><td style="text-align: center"><code>u128</code></td></tr> <tr><td style="text-align: center"><code>uint256</code></td><td style="text-align: center"><code>u256</code>†</td></tr> <tr><td style="text-align: center"><code>bytes1</code></td><td style="text-align: center"><code>bytes: [u8; 1]</code></td></tr> <tr><td style="text-align: center"><code>bytes2</code></td><td style="text-align: center"><code>bytes: [u8; 2]</code></td></tr> <tr><td style="text-align: center"><code>bytes4</code></td><td style="text-align: center"><code>bytes: [u8; 4]</code></td></tr> <tr><td style="text-align: center"><code>bytes8</code></td><td style="text-align: center"><code>bytes: [u8; 8]</code></td></tr> <tr><td style="text-align: center"><code>bytes16</code></td><td style="text-align: center"><code>bytes: [u8; 16]</code></td></tr> <tr><td style="text-align: center"><code>bytes32</code></td><td style="text-align: center"><code>PubKey</code></td></tr> <tr><td style="text-align: center"><code>bytes</code></td><td style="text-align: center"><code>bytes: Vec&lt;u8&gt;</code></td></tr> <tr><td style="text-align: center"><code>string</code></td><td style="text-align: center"><code>String</code></td></tr> <tr><td style="text-align: center"><code>address</code></td><td style="text-align: center"><code>bytes: [u8; 20]</code></td></tr> </tbody></table> <blockquote> <p>† <code>u256</code> is not available natively in SVM but is routinely implemented via <code>u256</code> crate in Rust</p> </blockquote> <p>Using this strategy, most - if not all - current use-cases of <code>StorageRoutedToSolana()</code> are accounted for.</p> <p>Finally, in order to read the cross-chain data stored on Solana in an arbitrary Ethereum contract, it must be translated back into EVM tongue by an <a href="https://wg-eips.ritovision.com/3668/">EIP-3668</a>-compliant HTTP gateway. The arguments for a generic call to the gateway URL must be specified in the <code>/</code>-delimited nested format as described in <a href="https://wg-eips.ritovision.com/7700/">EIP-7700</a>. The core of such a gateway must follow</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"> Pseudo-code of an ERC-3668-compliant HTTP gateway tunneling Solana content to Ethereum </span><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"> CCIP-Read call by contract to a known gateway URL; gatewayUrl = &#39;https://read.solana.namesys.xyz/&lt;programId&gt;/&lt;node&gt;/&lt;key&gt;/&#39;</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span> [</span><span class="z-variable z-other z-constant">programId</span><span>,</span><span class="z-variable z-other z-constant"> node</span><span>,</span><span class="z-variable z-other z-constant"> key</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> parseQuery</span><span>(</span><span class="z-variable z-other">path</span><span>)</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Parse query parameters from path; path = &#39;/&lt;programId&gt;/&lt;node&gt;/&lt;key&gt;/&#39;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Decode &#39;bytes32&#39; types in EVM to &#39;PubKey&#39; type in SVM</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span> [</span><span class="z-variable z-other z-constant">programId</span><span>,</span><span class="z-variable z-other z-constant"> node</span><span>,</span><span class="z-variable z-other z-constant"> key</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> E2SVM</span><span>(</span></span> <span class="giallo-l"><span> [</span><span class="z-variable z-other">programId</span><span>,</span><span class="z-variable z-other"> node</span><span>,</span><span class="z-variable z-other"> key</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">bytes32</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">bytes32</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">bytes32</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-punctuation z-definition z-comment">//</span><span class="z-comment"> Instantiate program interface on Solana</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> program</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-entity z-name"> program</span><span>(</span><span class="z-variable z-other">programId</span><span>,</span><span class="z-variable z-other"> rpcProvider</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Call the Solana program to read in cross-chain data</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> value</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> program</span><span>.</span><span class="z-entity z-name">getValue</span><span>(</span><span class="z-variable z-other">node</span><span>,</span><span class="z-variable z-other"> key</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">if</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">NOT_FOUND</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-comment"> //</span><span class="z-comment"> Decode &#39;PubKey&#39; type in SVM to &#39;bytes32&#39; type in EVM</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> value</span><span class="z-keyword"> =</span><span class="z-entity z-name"> S2EVM</span><span>(</span><span class="z-variable z-other">value</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">PubKey</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-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Null value</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> value</span><span class="z-keyword"> =</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Compile CCIP-Read-compatible payload</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-variable z-other"> abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</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><span> [</span><span class="z-variable z-other">value</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"> Create HTTP gateway emitting value in format &#39;data: ...&#39;</span></span> <span class="giallo-l"><span class="z-entity z-name">emitERC3668</span><span>(</span><span class="z-variable z-other">data</span><span>)</span><span>;</span></span></code></pre> <p>In the above example, the generic <code>getValue()</code> function in the Solana program is of the form</p> <pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Example getValue() function in Solana program</span></span> <span class="giallo-l"><span class="z-keyword">pub</span><span class="z-keyword"> fn</span><span class="z-entity z-name"> getValue</span><span>&lt;</span><span>&#39;</span><span class="z-entity z-name">a</span><span>&gt;</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> ctx</span><span class="z-keyword">:</span><span class="z-entity z-name"> Context</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> node</span><span class="z-keyword">:</span><span class="z-entity z-name"> Pubkey</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> key</span><span class="z-keyword">:</span><span class="z-entity z-name"> Pubkey</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> account</span><span class="z-keyword">:</span><span class="z-keyword"> &amp;</span><span class="z-entity z-name">AccountInfo</span><span>&lt;</span><span>&#39;</span><span class="z-entity z-name">a</span><span>&gt;</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Lifetime-bound parameter</span></span> <span class="giallo-l"><span>)</span><span class="z-keyword"> -&gt;</span><span class="z-entity z-name"> Result</span><span>&lt;</span><span class="z-entity z-name">Pubkey</span><span>,</span><span class="z-entity z-name"> ProgramError</span><span>&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Validate that the account belongs to the correct program ID</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"> Retrieve the data from the account</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> data</span><span class="z-keyword"> =</span><span class="z-keyword"> &amp;</span><span class="z-variable z-other">account</span><span class="z-keyword">.</span><span>data</span><span class="z-keyword">.</span><span class="z-entity z-name">borrow</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"> De-serialise the data from the account</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"> Look up the value by node and key</span></span> <span class="giallo-l"><span class="z-keyword"> match</span><span class="z-variable z-other"> deserialised</span><span class="z-keyword">.</span><span class="z-entity z-name">get</span><span>(</span><span class="z-keyword">&amp;</span><span class="z-variable z-other">node</span><span>,</span><span class="z-keyword"> &amp;</span><span class="z-variable z-other">key</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> Some</span><span>(</span><span class="z-variable z-other">value</span><span>)</span><span class="z-keyword"> =&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> msg!</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">VALUE: </span><span class="z-string">{</span><span class="z-string">:?</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&quot;</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"> Ok</span><span>(</span><span class="z-variable z-other">value</span><span>)</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> None</span><span class="z-keyword"> =&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> msg!</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">NOT_FOUND</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"> Err</span><span>(</span><span class="z-entity z-name">ProgramError</span><span class="z-keyword">::</span><span class="z-entity z-name">InvalidArgument</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><code>StorageRoutedToSolana()</code> works in a similar fashion to <code>StorageRoutedToL2()</code> in CCIP-Store in the sense that the client needs to be pointed to a certain contract on another chain by the revert event. Other than that, the only technical difference is casting between EVM and SVM data types.</p> <p><img src="https://wg-eips.ritovision.com/7694/./assets/images/Solana.svg" alt="Fig.2 Solana Call Lifecycle" /></p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>None.</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-04-17T00:00:00+00:00 2026-02-11T14:49:27+00:00 Parithosh Jayanthihttps://github.com/parithosh Toni Wahrstätterhttps://github.com/nerolation Sam Calder-Masonhttps://github.com/samcm Andrew Davishttps://github.com/savid Ansgar Dietrichshttps://github.com/adietrichs https://wg-eips.ritovision.com/7691/

Increase the number of blobs to reach a new target and max of 6 and 9 blobs per block respectively

<h2 id="abstract">Abstract</h2> <p>Increases the number of blobs in a block to provide more scale to Ethereum via L2 solution that rely on L1 data capacity.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum, with its rollup centric roadmap, scales by relying on L2. Since the Dencun fork, the blob gas target and maximum was set to 3/6 respectively. The blob gas limit was arrived at based on a series of big block tests performed on the Ethereum mainnet network as well as a series of testnets. The values were chosen cautiously, as it's extremely hard to predict the exact p2p behaviour of Ethereum mainnet.</p> <p>As we now have the Dencun upgrade live, we are able to use monitoring tools to check the network health. Initial monitoring indicates that we have a stable network with the current gas target and the re-org rate is trending downwards. Additionally, analysis on messages in gossipsub indicate that the inclusion of <code>IDONTWANT</code> messages could bring us a significant bandwidth savings. This allows us to consider starting a series of big block and blob tests to determine the theoretical headroom we currently have. The EIP specifies a proposed new blob gas target and limit based on the series of tests.</p> <p>This EIP aims to increase the throughput short term to provide some scaling until future solutions are deployed. In order to alleviate valid concerns about solo-stakers, approaches such as the inclusion of a flag indicating the max blobs per block for locally built blocks could be considered.</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>MAX_BLOBS_PER_BLOCK_ELECTRA</code></td><td><code>9</code></td></tr> <tr><td><code>TARGET_BLOBS_PER_BLOCK_ELECTRA</code></td><td><code>6</code></td></tr> <tr><td><code>MAX_BLOB_GAS_PER_BLOCK</code></td><td><code>1179648</code></td></tr> <tr><td><code>TARGET_BLOB_GAS_PER_BLOCK</code></td><td><code>786432</code></td></tr> <tr><td><code>BLOB_BASE_FEE_UPDATE_FRACTION_PRAGUE</code></td><td><code>5007716</code></td></tr> </tbody></table> <p><code>MAX_BLOBS_PER_BLOCK_ELECTRA</code> and <code>TARGET_BLOBS_PER_BLOCK_ELECTRA</code> are consumed by the consensus layer clients, and starting at <code>PECTRA_FORK_EPOCH</code> replace the respective old max and target values.</p> <p><code>MAX_BLOB_GAS_PER_BLOCK</code>, <code>TARGET_BLOB_GAS_PER_BLOCK</code> and <code>BLOB_BASE_FEE_UPDATE_FRACTION_PRAGUE</code> are consumed by the execution layer clients, and starting at the epoch when this EIP is activated, replace the old max, target and update fraction values. Any references to <code>MAX_BLOB_GAS_PER_BLOCK</code> and <code>TARGET_BLOB_GAS_PER_BLOCK</code> in <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> should be updated to the new values defined in this EIP when processing the activation block. The value <code>BLOB_BASE_FEE_UPDATE_FRACTION_PRAGUE</code> replaces its previous equivalent when processing the activation block. These changes imply that <code>get_base_fee_per_blob_gas</code> and <code>calc_excess_blob_gas</code> functions defined in <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> use the new values for the first block of the fork (and for all subsequent blocks).</p> <h2 id="rationale">Rationale</h2> <h3 id="simplicity">Simplicity</h3> <p>The EIP aims to minimize the amount of testing and implementation effort from the perspective of the client teams, to allow for more resources to be allocated to peerDAS and other scaling research.</p> <p>While this EIP may not achieve the new optimal blob limit, it offers a compromise for a short term increase.</p> <h3 id="update-fraction">Update Fraction</h3> <p>The original target and max values from <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> were at a 1:2 ratio. As a consequence, responsiveness to full and empty blob sections was symmetrical:</p> <ul> <li>full blobs: basefee increases by ~12.5%</li> <li>no blobs: basefee decreases by ~11.1%</li> </ul> <p>The new target and max values from this EIP are at a 2:3 ratio, which breaks that symmetry. As a consequence, the basefee becomes significantly more responsive to empty blob sections (that are 6 blobs under target) than to full ones (that are 3 blobs over target). This is by design, as it takes two blocks with full blobs in a row to make up for a single block with no blobs. However, it creates the challenge of finding a good compromise base fee sensitivity level.</p> <p>The <code>BLOB_BASE_FEE_UPDATE_FRACTION_PRAGUE</code> value in this EIP is chosen as the mid-point between keeping the responsiveness to full blobs and no blobs constant:</p> <ul> <li>full blobs: basefee increases by ~8.2%</li> <li>no blobs: basefee decreases by ~14.5%</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The consensus clients would continue to use <code>MAX_BLOBS_PER_BLOCK</code> and <code>TARGET_BLOBS_PER_BLOCK</code> for the deneb fork and once the <code>ELECTRA</code> fork is active, they would use <code>MAX_BLOBS_PER_BLOCK_ELECTRA</code> and <code>TARGET_BLOBS_PER_BLOCK_ELECTRA</code> respectively.</p> <p>The execution clients would continue to use <code>MAX_BLOB_GAS_PER_BLOCK</code>, <code>TARGET_BLOB_GAS_PER_BLOCK</code> and <code>BLOB_BASE_FEE_UPDATE_FRACTION</code> for the cancun fork and once the prague fork is active, they would use <code>MAX_BLOB_GAS_PER_BLOCK</code>, <code>TARGET_BLOB_GAS_PER_BLOCK</code> and <code>BLOB_BASE_FEE_UPDATE_FRACTION_PRAGUE</code> respectively.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="network-impacts">Network Impacts</h3> <p>Through the use of big block/blob tests on Ethereum mainnet as well as testnets, we can earn a high degree of certainty that the blob limit increase would not negatively impact the network. These tests as well as the associated analysis can be performed mostly by non-client team entities, with minimal input required. Since the changes are quite contained, the EIP should be able to reduce the risk of the blob limit increase.</p> <h3 id="stability-around-fork-epoch">Stability Around Fork Epoch</h3> <p>A blob limit increase at the fork transition is relatively straightforward from an implementation perspective. We would need to deploy an increased amount of monitoring around the fork epoch, but after a period of stability we can assume that the blob limit increase was successful, reducing any unexpected co-ordination efforts.</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-16T00:00:00+00:00 2026-02-11T14:48:25+00:00 Dror Tiroshhttps://github.com/drortirosh Yoav Weisshttps://github.com/yoavw Alex Forshtathttps://github.com/forshtat Shahaf Nacsonhttps://github.com/shahafn https://wg-eips.ritovision.com/7796/

JSON-RPC API for block builders allowing users to express preconditions for transaction inclusion

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a new JSON-RPC API method <code>eth_sendRawTransactionConditional</code> for block builders and sequencers, enhancing transaction integration by allowing users to express preconditions for transaction inclusion.</p> <p>This method aims to improve efficiency by reducing the need for transaction simulation, thereby improving the computational efficiency of transaction ordering.</p> <h2 id="motivation">Motivation</h2> <p>Current private block builder APIs, such as the Flashbots API, require block builders to simulate transactions to determine eligibility for inclusion, a process that is CPU-intensive and inefficient.</p> <p>The proposed RPC method addresses this by enabling transactions to specify preconditions, thus reducing computational overhead and potentially lowering transaction costs.</p> <p>Moreover, the flashbots API does not provide the block builder with a mechanism to determine the cross-dependencies of different transactions.</p> <p>The only way to guarantee that another transaction does not interfere with a given one is by placing it as the first transaction in the block. This makes this placement very lucrative, and disproportionately expensive.</p> <p>In addition, since there is no way to give any guarantee on other slots, their pricing has to be low accordingly.</p> <p>Since there is no easy way to detect cross-dependencies of different transactions, it is CPU-intensive to find an optimal ordering of transactions.</p> <h2 id="specification">Specification</h2> <ul> <li> <p>Method: <code>eth_sendRawTransactionConditional</code></p> </li> <li> <p>Parameters:</p> </li> </ul> <ol> <li><code>transaction</code>: The raw, signed transaction data. Similar to <code>eth_sendRawTransaction</code>.</li> <li><code>options</code>: An object containing conditions under which the transaction must be included.</li> </ol> <ul> <li>The <code>options</code> parameter may include any of the following optional members: <ul> <li><strong>knownAccounts</strong>: a mapping of accounts with their expected storage slots' values. <ul> <li>The key of the mapping is account address.</li> <li>A special key <code>balance</code> defines the expected balance of the account.</li> <li>A special key <code>code</code> defines the expected code of the account. Use <code>""</code> to indicate that address is expected not to have any code. Use the <code>"0xef0100"</code> prefix to indicate a specific <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> delegation.</li> <li>A special key <code>nonce</code> defines the expected nonce of the account.</li> <li>If the value is <strong>hex string</strong>, it is the known storage root hash of that account.</li> <li>If the value is an <strong>object</strong>, then it is a mapping where each member is in the format of <code>"slot": "value"</code>. The <code>value</code> fields are explicit slot values of the account's storage. Both <code>slot</code> and <code>value</code> are hex-encoded strings.</li> </ul> </li> <li><strong>blockNumberMin</strong>: minimal block number for inclusion.</li> <li><strong>blockNumberMax</strong>: maximum block number for inclusion.</li> <li><strong>timestampMin</strong>: minimum block timestamp for inclusion.</li> <li><strong>timestampMax</strong>: maximum block timestamp for inclusion.</li> <li><strong>paysCoinbase</strong>: the caller declares the minimum amount paid to the <code>coinbase</code> by this transaction, including gas fees and direct payment.</li> </ul> </li> </ul> <p>Before accepting the request, the block builder or sequencer SHOULD:</p> <ul> <li>Check that the block number is within the block range if the block range value was specified.</li> <li>Check that the block timestamp is within the timestamp range if the timestamp range was specified.</li> <li>For all addresses with a specified storage root hash, validate the current root is unmodified.</li> <li>For all addresses with a specified slot values mapping, validate that all these slots hold the exact value specified.</li> </ul> <p>The sequencer should REJECT the request if any address does not pass the above rules.</p> <h3 id="return-value">Return value</h3> <p>In case of a successful inclusion, the call should return a hash of the newly submitted transaction. This behaviour is equivalent to the <code>eth_sendRawTransaction</code> JSON-RPC API method.</p> <p>In case of an immediate failure to validate the transaction's conditions, the block builder SHOULD return an error with indication of failure reason.</p> <p>The error code SHOULD be "-32003 transaction rejected" with reason string describing the cause: i.e. storage error, out of block/time range, etc.</p> <p>In case of repeated failures or <code>knownAccounts</code> mapping being too large for the current block builder to handle, the error code SHOULD be "-32005 limit exceeded" with a description of the error.</p> <p><strong>NOTE:</strong> Same as with the <code>eth_sendRawTransaction</code> method, even if the RPC method call does not resul in an error and the transaction is initially accepted into the internal block builder's mempool, the caller MUST NOT assume that a transaction will be included in a block and should monitor the blockchain.</p> <h3 id="sample-request">Sample request</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">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"> 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">eth_sendRawTransactionConditional</span><span class="z-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">0x2815c17b00...</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">blockNumberMax</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 12345</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">knownAccounts</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">0xadd1</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xfedc....</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">0xadd2</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">0x1111</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1234...</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">0x2222</span><span class="z-support">&quot;</span><span>:</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> <span class="giallo-l"><span> }</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> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="limitations">Limitations</h3> <ul> <li>Callers should not assume that a successful response means the transaction is included. Specifically, it is possible that a block re-order might remove the transaction or cause it to fail.</li> </ul> <h2 id="rationale">Rationale</h2> <p>The <code>knownAccounts</code> only allows specifying the exact values for storage slots. While in some cases specifying <code>minValue</code> or <code>maxValue</code> for a slot could be useful, it would significantly increase complexity of the proposed API. Additionally, determining the validity range for a slot value is a non-trivial task for the sender of a transaction.</p> <p>One way to provide a more complex rule for a transaction condition is by specifying the <code>paysCoinbase</code> parameter, and issuing a transfer to the <code>coinbase</code> address on some condition.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a proposal for a new API method so no backward compatibility issues are expected. Existing non-standard implementations of <code>eth_sendRawTransactionConditional</code> API may need to be modified in order to become compatible with the standard.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The block builder should protect itself against abuse of the API. Namely, a malicious actor submitting a large number of requests which are known to fail may lead to a denial of service.</p> <p>Following is the list of suggested potential mitigation mechanisms:</p> <ul> <li><strong>Throttling</strong>: the block builder should allow a maximum rate of RPC calls per sender. The block builder may increase that rate after a successful inclusion. Repeated rejections of transactions should reduce the allowed rate.</li> <li><strong>Arbitrum</strong>-style protection: Arbitrum implemented this API, but they run the storage validation not only against the current block, but also into past 2 seconds. This prevents abusing the API for MEV, while making it viable for <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> account validation.</li> <li><strong>Fastlane on Polygon</strong> uses it explicitly for ERC-4337, by checking the submitted UserOperations exist on the public mempool and rejecting the transaction otherwise.</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> 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-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status Caymanhttps://github.com/wemeetagain https://wg-eips.ritovision.com/7688/

Transition consensus SSZ data structures to ProgressiveContainer

<h2 id="abstract">Abstract</h2> <p>This EIP defines the changes needed to adopt <code>ProgressiveContainer</code> from <a href="https://wg-eips.ritovision.com/7495/">EIP-7495</a> and <code>ProgressiveList</code> from <a href="https://wg-eips.ritovision.com/7916/">EIP-7916</a> in consensus data structures.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum's consensus data structures make heavy use of <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/simple-serialize.md">Simple Serialize (SSZ)</a> <code>Container</code>, which defines how they are serialized and merkleized. The merkleization scheme allows application implementations to verify that individual fields (and partial fields) have not been tampered with. This is useful, for example, in smart contracts of decentralized staking pools that wish to verify that participating validators have not been slashed.</p> <p>While SSZ <code>Container</code> defines how data structures are merkleized, the merkleization is prone to change across the different forks. When that happens, e.g., because new features are added or old features get removed, existing verifier implementations need to be updated to be able to continue processing proofs.</p> <p><code>ProgressiveContainer</code>, of <a href="https://wg-eips.ritovision.com/7495/">EIP-7495</a>, is a forward compatible alternative that guarantees a forward compatible merkleization scheme. By transitioning consensus data structures to use <code>ProgressiveContainer</code>, smart contracts that contain verifier logic no longer have to be maintained in lockstep with Ethereum's fork schedule as long as the underlying features that they verify don't change. For example, as long as the concept of slashing is represented using the boolean <code>slashed</code> field, existing verifiers will not break when unrelated features get added or removed. This is also true for off-chain verifiers, e.g., in hardware wallets or in operating systems for mobile devices that are on a different software update cadence than Ethereum.</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="container-conversion"><code>Container</code> conversion</h3> <p><code>Container</code> types that are expected to evolve over forks SHALL be redefined as <code>ProgressiveContainer(active_fields=[1] * len(type.fields()))</code>.</p> <p>For example, given a type in the old fork:</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"> Foo</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> a</span><span>:</span><span> uint8</span></span> <span class="giallo-l"><span> b</span><span>:</span><span> uint16</span></span></code></pre> <p>This type can be converted to support stable Merkleization in the new fork:</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"> Foo</span><span>(</span><span class="z-entity">ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> a</span><span>:</span><span> uint8</span></span> <span class="giallo-l"><span> b</span><span>:</span><span> uint16</span></span></code></pre> <p>As part of the conversion, a stable <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/merkle-proofs.md#generalized-merkle-tree-index">generalized index (gindex)</a> is assigned to each field that remains valid in future forks.</p> <ul> <li>If a fork appends a field, <code>active_fields</code> MUST be extended with a trailing <code>1</code>.</li> <li>If a fork removes a field, the corresponding <code>active_fields</code> bit MUST be changed to <code>0</code>.</li> <li>Compatibility rules SHOULD be enforced, e.g., by defining a <code>CompatibleUnion[fork_1.Foo, fork_2.Foo, fork_3.Foo, ...]</code> type in the unit test framework.</li> </ul> <h3 id="list-type-n-bitlist-conversion"><code>List[type, N]</code> / <code>Bitlist</code> conversion</h3> <p><code>List</code> types frequently have been defined with excessively large capacities <code>N</code> with the intention that <code>N</code> is never reached in practice. In other cases, the capacity itself has changed over time.</p> <ul> <li><code>List</code> types with dynamic or unbounded capacity semantics SHALL be redefined as <code>ProgressiveList[type]</code>, and the application logic SHALL be updated to check for an appropriate limit at runtime.</li> <li><code>Bitlist</code> types with dynamic or unbounded capacity semantics SHALL be redefined as <code>ProgressiveBitlist</code></li> </ul> <p>As part of the conversion, a stable <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/merkle-proofs.md#generalized-merkle-tree-index">generalized index (gindex)</a> is assigned to each list element that remains valid regardless of the number of added elements.</p> <h3 id="converted-types">Converted types</h3> <p>The following types SHALL be converted to <code>ProgressiveContainer</code>:</p> <ul> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#attestation"><code>Attestation</code></a> <ul> <li>The <code>aggregation_bits</code> field is redefined to use <code>ProgressiveBitlist</code></li> </ul> </li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#indexedattestation"><code>IndexedAttestation</code></a> <ul> <li>The <code>attesting_indices</code> field is redefined to use <code>ProgressiveList</code></li> </ul> </li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/deneb/beacon-chain.md#executionpayload"><code>ExecutionPayload</code></a> <ul> <li>The <code>transactions</code> and <code>withdrawals</code> fields are redefined to use <code>ProgressiveList</code></li> <li>The <code>MAX_TRANSACTIONS_PER_PAYLOAD</code> (1M) limit is no longer enforced (the limit is unreachable with <code>MAX_PAYLOAD_SIZE</code> 10 MB)</li> </ul> </li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#executionrequests"><code>ExecutionRequests</code></a> <ul> <li>The <code>deposits</code>, <code>withdrawals</code> and <code>consolidations</code> fields are redefined to use <code>ProgressiveList</code></li> </ul> </li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#beaconblockbody"><code>BeaconBlockBody</code></a> <ul> <li>The <code>proposer_slashings</code>, <code>attester_slashings</code>, <code>attestations</code>, <code>deposits</code>, <code>voluntary_exits</code> and <code>bls_to_execution_changes</code> fields are redefined to use <code>ProgressiveList</code></li> </ul> </li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#beaconstate"><code>BeaconState</code></a> <ul> <li>The <code>validators</code>, <code>balances</code>, <code>previous_epoch_participation</code>, <code>current_epoch_participation</code>, <code>inactivity_scores</code>, <code>pending_deposits</code>, <code>pending_partial_withdrawals</code> and <code>pending_consolidations</code> fields are redefined to use <code>ProgressiveList</code></li> </ul> </li> <li>The <code>blob_kzg_commitments</code>, <code>kzg_proofs</code> and <code>column</code> fields are redefined to use <code>ProgressiveList</code></li> </ul> <h3 id="immutable-types">Immutable types</h3> <p>These types are used as part of the <code>ProgressiveContainer</code> definitions, and, as they are not <code>ProgressiveContainer</code> themselves, are considered to have immutable Merkleization. If a future fork requires changing these types in an incompatible way, a new type SHALL be defined and assigned a new field name.</p> <table><thead><tr><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#custom-types"><code>Slot</code></a></td><td>Slot number on the beacon chain</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#custom-types"><code>Epoch</code></a></td><td>Epoch number on the beacon chain, a group of slots</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#custom-types"><code>CommitteeIndex</code></a></td><td>Index of a committee within a slot</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#custom-types"><code>ValidatorIndex</code></a></td><td>Unique index of a beacon chain validator</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#custom-types"><code>Gwei</code></a></td><td>Amount in Gwei (1 ETH = 10^9 Gwei = 10^18 Wei)</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#custom-types"><code>Root</code></a></td><td>Byte vector containing an SSZ Merkle root</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#custom-types"><code>Hash32</code></a></td><td>Byte vector containing an opaque 32-byte hash</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#custom-types"><code>Version</code></a></td><td>Consensus fork version number</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#custom-types"><code>BLSPubkey</code></a></td><td>Cryptographic type representing a BLS12-381 public key</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#custom-types"><code>BLSSignature</code></a></td><td>Cryptographic type representing a BLS12-381 signature</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/_features/sharding/polynomial-commitments.md#custom-types"><code>KZGCommitment</code></a></td><td>G1 curve point for the KZG polynomial commitment scheme</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#fork"><code>Fork</code></a></td><td>Consensus fork information</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#checkpoint"><code>Checkpoint</code></a></td><td>Tuple referring to the most recent beacon block up through an epoch's start slot</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#validator"><code>Validator</code></a></td><td>Information about a beacon chain validator</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#attestationdata"><code>AttestationData</code></a></td><td>Vote that attests to the availability and validity of a particular consensus block</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#eth1data"><code>Eth1Data</code></a></td><td>Target tracker for importing deposits from transaction logs</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#depositdata"><code>DepositData</code></a></td><td>Log data emitted as part of a transaction's receipt when depositing to the beacon chain</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#beaconblockheader"><code>BeaconBlockHeader</code></a></td><td>Consensus block header</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#proposerslashing"><code>ProposerSlashing</code></a></td><td>Tuple of two equivocating consensus block headers</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#deposit"><code>Deposit</code></a></td><td>Tuple of deposit data and its inclusion proof</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#voluntaryexit"><code>VoluntaryExit</code></a></td><td>Consensus originated request to exit a validator from the beacon chain</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#signedvoluntaryexit"><code>SignedVoluntaryExit</code></a></td><td>Tuple of voluntary exit request and its signature</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/altair/beacon-chain.md#syncaggregate"><code>SyncAggregate</code></a></td><td>Cryptographic type representing an aggregate sync committee signature</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/bellatrix/beacon-chain.md#custom-types"><code>ExecutionAddress</code></a></td><td>Byte vector containing an account address on the execution layer</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/bellatrix/beacon-chain.md#custom-types"><code>Transaction</code></a></td><td>Byte list containing an RLP encoded transaction</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/capella/beacon-chain.md#custom-types"><code>WithdrawalIndex</code></a></td><td>Unique index of a withdrawal from any validator's balance to the execution layer</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/capella/beacon-chain.md#withdrawal"><code>Withdrawal</code></a></td><td>Withdrawal from a beacon chain validator's balance to the execution layer</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#depositrequest"><code>DepositRequest</code></a></td><td>Tuple of flattened deposit data and its sequential index</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#withdrawalrequest"><code>WithdrawalRequest</code></a></td><td>Execution originated request to withdraw from a validator to the execution layer</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#consolidation"><code>ConsolidationRequest</code></a></td><td>Execution originated request to consolidate two beacon chain validators</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/capella/beacon-chain.md#blstoexecutionchange"><code>BLSToExecutionChange</code></a></td><td>Request to register the withdrawal account address of a beacon chain validator</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/capella/beacon-chain.md#signedblstoexecutionchange"><code>SignedBLSToExecutionChange</code></a></td><td>Tuple of withdrawal account address registration request and its signature</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/altair/beacon-chain.md#custom-types"><code>ParticipationFlags</code></a></td><td>Participation tracker of a beacon chain validator within an epoch</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/capella/beacon-chain.md#historicalsummary"><code>HistoricalSummary</code></a></td><td>Tuple combining a historical block root and historical state root</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#pendingdeposit"><code>PendingDeposit</code></a></td><td>Pending operation for depositing to a beacon chain validator</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#pendingpartialwithdrawal"><code>PendingPartialWithdrawal</code></a></td><td>Pending operation for withdrawing from a beacon chain validator</td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#pendingconsolidation"><code>PendingConsolidation</code></a></td><td>Pending operation for consolidating two beacon chain validators</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <h3 id="best-timing">Best timing?</h3> <p>Applying this EIP breaks <code>hash_tree_root</code> and Merkle tree verifiers a single time, while promising forward compatibility from the fork going forward. It is best to apply it before merkleization would be broken by different changes. Merkleization is broken by a <code>Container</code> reaching a new power of 2 in its number of fields.</p> <h3 id="can-this-be-applied-retroactively">Can this be applied retroactively?</h3> <p>While <code>ProgressiveContainer</code> serializes in the same way as the legacy <code>Container</code>, the merkleization and <code>hash_tree_root</code> of affected data structures changes. Therefore, verifiers that wish to process Merkle proofs of legacy variants still need to support the corresponding legacy schemes.</p> <h3 id="immutability">Immutability</h3> <p>Once a field in a <code>ProgressiveContainer</code> has been published, its name can no longer be used to represent a different type in the future. This is in line with historical management of certain cases:</p> <ul> <li>Phase0: <code>BeaconState</code> contained <code>previous_epoch_attestations</code> / <code>current_epoch_attestations</code></li> <li>Altair: <code>BeaconState</code> replaced these fields with <code>previous_epoch_participation</code> / <code>current_epoch_participation</code></li> </ul> <p>Furthermore, new fields have to be appended at the end of <code>ProgressiveContainer</code>. This is in line with historical management of other cases:</p> <ul> <li>Capella appended <code>historical_summaries</code> to <code>BeaconState</code> instead of squeezing the new field next to <code>historical_roots</code></li> </ul> <p>With <code>ProgressiveContainer</code>, stable Merkleization requires these rules to become strict.</p> <h3 id="cleanup-opportunities">Cleanup opportunities</h3> <h4 id="beaconstate"><code>BeaconState</code></h4> <ul> <li>The <code>eth1_data</code>, <code>eth1_data_votes</code>, <code>eth1_deposit_index</code> and <code>deposit_requests_start_index</code> fields could be dropped as they are no longer needed after the <a href="https://wg-eips.ritovision.com/6110/#eth1data-poll-deprecation">EIP-6110</a> transition period finishes.</li> <li><code>historical_summaries</code> could be redefined to use <code>ProgressiveList</code> and also integrate the historical <code>historical_roots</code> data by merging in full <code>HistoricalSummary</code> data from an archive (<code>historical_root</code> is frozen since Capella), simplifying access to historical block and state roots.</li> </ul> <h4 id="attestation"><code>Attestation</code></h4> <ul> <li>The <code>committee_bits</code> is defined as a <code>Bitvector</code>, but the top bits are forced to 0 based on <code>get_committee_count_per_slot(state, data.target.epoch)</code>. It could be re-defined as a <code>ProgressiveBitlist</code>.</li> </ul> <h4 id="indexedattestation"><code>IndexedAttestation</code></h4> <p>The <code>attesting_indices</code> are limited to <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#indexedattestation"><code>MAX_VALIDATORS_PER_COMMITTEE * MAX_COMMITTEES_PER_SLOT</code></a>, which is insufficient when the <code>IndexedAttestation</code> is formed from <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#singleattestation"><code>SingleAttestation</code></a> traffic. <code>SingleAttestation</code> allows validators that are not assigned to a slot to produce signatures that are not aggregatable into an <code>Attestation</code> (as such validators are not assigned), but that are still slashable.</p> <p>Further, <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/electra/beacon-chain.md#max-operations-per-block"><code>MAX_ATTESTER_SLASHINGS_ELECTRA</code></a> at 1 limits inclusion efficiency of slashings in non-finality scenarios with a lot of forks where slashings happen across multiple different <code>AttestationData</code> values.</p> <p>Limits could be rethought to be based on actual resource usage, e.g., by limiting:</p> <ul> <li>The total number of <code>attesting_indices</code> across all <code>AttesterSlashing</code> (shared total)</li> <li>The total number of signature checks across all <code>AttesterSlashing</code>, <code>ProposerSlashing</code>, <code>VoluntaryExit</code>, and <code>SignedBLSToExecutionChange</code> messages</li> </ul> <p>Limiting totals rather than individual resources would allow extra attester slashings to be included at the cost of potentially delaying inclusion of a couple altruistic messages (if there even are any <code>VoluntaryExit</code> / <code>SignedBLSToExecutionChange</code> messages at that time), thus increasing security and block packing efficiency.</p> <h4 id="executionpayload"><code>ExecutionPayload</code></h4> <p>The <code>block_hash</code> field could be moved to the top of <code>ExecutionPayload</code>, reducing the Merkle proof size.</p> <h4 id="executionrequests"><code>ExecutionRequests</code></h4> <p>As deposits cannot be retried by the user (they pay the ETH upfront), deposit requests cannot fizzle like other requests; they are always included in the same block (since Pectra). For that reason, the current <code>MAX_DEPOSIT_REQUESTS_PER_PAYLOAD</code> (8192) is essentially unbounded at current gas limits, but may eventually become reachable (around ~192M gas, or earlier with gas repricings). The CL limit for deposit requests could be dropped to avoid scaling issues, instead solely relying on EL backpressure (gas fees, 1 ETH deposit minimum).</p> <p>For other requests (withdrawal / consolidation requests), a shared total limit based on the added CL state size could provide more flexibility than the current per-operation limits. For example, in times without consolidation requests, space could be used to enqueue more withdrawal requests.</p> <h4 id="beaconblockheader"><code>BeaconBlockHeader</code></h4> <p>The <code>BeaconBlockHeader</code> is currently proposed to be kept as is. Updating the <code>BeaconBlockHeader</code> to <code>ProgressiveContainer</code> is tricky as it breaks <code>hash_tree_root(latest_block_header)</code> in the <code>BeaconState</code>. One option could be to store <code>latest_block_header_root</code> separately, possibly also incorporating the block proposer signature into the hash to avoid proposer signature checks while backfilling historical blocks.</p> <h4 id="validator"><code>Validator</code></h4> <p>The <code>Validator</code> container is currently proposed to be kept as is. Updating the <code>Validator</code> to <code>ProgressiveContainer</code> would add an extra hash for each validator; validators are mostly immutable so rarely need to be re-hashed. With a conversion, implementations may have to incrementally construct the new <code>Validator</code> entries ahead of the fork when validator counts are high. It should be evaluated whether the hashing overhead is worth a clean transition to future fields, e.g., for holding postquantum keys. Also consider that such a transition may also involve a new hash function, which is a breaking change to the Merkle proofs, so generalized indices do not have to be stable across that transition.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Existing Merkle proof verifiers need to be updated to support the new Merkle tree shape. This includes verifiers in smart contracts on different blockchains and verifiers in hardware wallets, if applicable.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Before this EIP, all <code>List</code> types had a fixed upper bound, enabling implementations to reject messages exceeding that size early. With <code>ProgressiveList</code>, that is no longer possible, as there is no more maximum message size. Instead, the length checks have to be implemented as part of P2P gossip validation, and as part of the state transition logic. However, many of the limits are not practically reachable (e.g., the gas limit is reached before the maximum payload size). Further note that SSZ is simple enough that clever implementations could still enforce those length checks on the serialized data, before fully decoding it.</p> <p>All data inbound via libp2p is decrypted, then uncompressed with Snappy, then hashed with <code>MESSAGE_DOMAIN_VALID_SNAPPY</code> / <code>MESSAGE_DOMAIN_INVALID_SNAPPY</code> prefix depending on whether the decompression worked to compute the libp2p message ID, while honoring a global <code>MAX_PAYLOAD_SIZE</code> message size limit. This has to be done even if the underlying SSZ data ends up being invalid.</p> <p>As SSZ does not use variable-length encoding, it does not have uncontrolled blowup (no 1 byte becomes 100 MB). Therefore, attempting to decode a <code>MAX_PAYLOAD_SIZE</code> message before checking dynamic <code>List</code> limits does not decrease security. Any intentional DoS attacks can already target a heavier portion of the processing pipeline (e.g., by sending invalid BLS signatures, or by sending invalid Snappy data that still needs to be hashed to compute the message ID). Therefore, the EIP does not notably impact security.</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:48:25+00:00 Francesco Sullohttps://github.com/sullof https://wg-eips.ritovision.com/7897/

Define a registry for modular services linked to ERC-4337 wallets.

<h2 id="abstract">Abstract</h2> <p>This proposal defines a registry for generic services linked to smart accounts, with a special focus on <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> wallets, where services are contracts extending a wallet's functionality, owned by the wallet itself. It leverages <a href="https://wg-eips.ritovision.com/1167/">ERC-1167</a> minimal proxies and deterministic addressing to enable permissionless innovation while maintaining backward compatibility with existing <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> wallets. To reach its goal, it takes the concept introduced with <a href="https://wg-eips.ritovision.com/6551/">ERC-6551</a> and <a href="https://wg-eips.ritovision.com/7656/">ERC-7656</a> standards that work for NFTs, and applies it to wallets.</p> <p><strong>Note: This proposal is not needed anymore since the same functionality can be achieved using <a href="https://wg-eips.ritovision.com/7656/">ERC-7656</a> standard.</strong></p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> (Account Abstraction) introduces programmable smart accounts. Existing proposals to extend wallet functionalities (e.g., <a href="https://wg-eips.ritovision.com/6900/">ERC-6900</a>) focus on internal modules. This proposal generalizes the concept of service binding, allowing any <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> wallet to attach external services (e.g., recovery, automation, compliance) without requiring changes to the wallet's core logic.</p> <p>By enabling modular, non-invasive extensions, this standard fosters an open ecosystem of wallet-linked services while ensuring backward compatibility with existing <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> wallets.</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="registry-interface">Registry Interface</h3> <p>The interface <code>IERC7897Registry</code> is defined 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"> IERC7897Registry</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 a wallet-linked service is successfully deployed.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> deployedService</span><span class="z-comment"> The address of the deployed 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"> serviceImplementation</span><span class="z-comment"> The address of the implementation 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"> salt</span><span class="z-comment"> The salt used for the CREATE2 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"> chainId</span><span class="z-comment"> The chain ID where the contract is deployed</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> wallet</span><span class="z-comment"> The address of the ERC-4337 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"> ServiceDeployed</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> deployedService</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"> serviceImplementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> chainId</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"> wallet</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Thrown when the CREATE2 operation fails to deploy the contract.</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"> DeployFailed</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Deploys a wallet-linked service for an ERC-4337 wallet. </span></span> <span class="giallo-l"><span class="z-comment"> * If the service already exists, returns its address without calling CREATE2. </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> serviceImplementation</span><span class="z-comment"> The address of the implementation 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"> salt</span><span class="z-comment"> The salt used for the CREATE2 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"> wallet</span><span class="z-comment"> The address of the ERC-4337 wallet </span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {ServiceDeployed} event. </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"> service</span><span class="z-comment"> The address of the wallet-linked service </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"> deployService</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> serviceImplementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> wallet</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">address</span><span class="z-variable"> service</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"> Computes the expected wallet-linked service address for an ERC-4337 wallet </span></span> <span class="giallo-l"><span class="z-comment"> * without deploying 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"> serviceImplementation</span><span class="z-comment"> The address of the implementation 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"> salt</span><span class="z-comment"> The salt used for the CREATE2 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"> chainId</span><span class="z-comment"> The chain ID where the service would be deployed </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> wallet</span><span class="z-comment"> The address of the ERC-4337 wallet </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"> service</span><span class="z-comment"> The computed address of the wallet-linked service </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"> serviceAddress</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> serviceImplementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> chainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> wallet</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">address</span><span class="z-variable"> service</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="deployment-requirements">Deployment Requirements</h3> <p>The registry MUST deploy each wallet-linked service as an <a href="https://wg-eips.ritovision.com/1167/">ERC-1167</a> minimal proxy with immutable constant data appended to the bytecode.</p> <p>The deployed bytecode of each wallet-linked service MUST have the following structure:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>ERC-1167 Header (10 bytes)</span></span> <span class="giallo-l"><span>&lt;serviceImplementation (address)&gt; (20 bytes)</span></span> <span class="giallo-l"><span>ERC-1167 Footer (15 bytes)</span></span> <span class="giallo-l"><span>&lt;salt (bytes32)&gt; (32 bytes)</span></span> <span class="giallo-l"><span>&lt;chainId (uint256)&gt; (32 bytes)</span></span> <span class="giallo-l"><span>&lt;wallet (address)&gt; (20 bytes)</span></span></code></pre><h3 id="recommended-service-interface">Recommended Service Interface</h3> <p>Any contract created using an <code>ERC7897Registry</code> SHOULD implement the <code>IERC7897Service</code> 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"> IERC7897Service</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 the wallet linked to 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"> chainId</span><span class="z-comment"> The chainId of the wallet</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"> wallet</span><span class="z-comment"> The address of the [ERC-4337](./04337.md) 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"> wallet</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"> chainId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> wallet</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="access-control">Access Control</h3> <p>Services SHOULD implement access control to restrict critical operations to the wallet owner. For example:</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"> owner</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> (</span><span>,</span><span class="z-support"> address</span><span> wallet</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> IERC7897Service</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 class="z-entity z-name">wallet</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> wallet</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"> 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 class="z-entity z-name"> owner</span><span>(</span><span>)</span><span>,</span><span class="z-string"> &quot;Unauthorized&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></code></pre><h2 id="rationale">Rationale</h2> <p>The technical foundation of <a href="https://wg-eips.ritovision.com/7897/">ERC-7897</a> centers on the extension and generalization of contract types that can be associated with <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> wallets. Key decisions include:</p> <ul> <li> <p>Flexibility: Enables any <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> wallet to attach external services without modifying its core logic.</p> </li> <li> <p>Permissionless Innovation: Developers can deploy services for any wallet, fostering an open ecosystem.</p> </li> <li> <p>Backward Compatibility: Works with existing <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> wallets, including Safe, Argent, and Biconomy.</p> </li> <li> <p>Deterministic Addressing: Uses CREATE2 + salt/chainId/wallet for predictable service deployments.</p> </li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// This implementation is a variation of the ERC6551Registry contract written by Jayden Windle @jaydenwindle and Vectorized @vectorized</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span>contract ERC7897Registry is IERC7897Registry {</span></span> <span class="giallo-l"><span> function deployService(</span></span> <span class="giallo-l"><span> address serviceImplementation,</span></span> <span class="giallo-l"><span> bytes32 salt,</span></span> <span class="giallo-l"><span> address wallet</span></span> <span class="giallo-l"><span> ) external override returns (address) {</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> // Memory Layout:</span></span> <span class="giallo-l"><span> // ----</span></span> <span class="giallo-l"><span> // 0x00 0xff (1 byte)</span></span> <span class="giallo-l"><span> // 0x01 registry (address) (20 bytes)</span></span> <span class="giallo-l"><span> // 0x15 salt (bytes32) (32 bytes)</span></span> <span class="giallo-l"><span> // 0x35 Bytecode Hash (bytes32) (32 bytes)</span></span> <span class="giallo-l"><span> // ----</span></span> <span class="giallo-l"><span> // 0x55 ERC-1167 Constructor + Header (20 bytes)</span></span> <span class="giallo-l"><span> // 0x69 implementation (address) (20 bytes)</span></span> <span class="giallo-l"><span> // 0x5D ERC-1167 Footer (15 bytes)</span></span> <span class="giallo-l"><span> // 0x8C salt (uint256) (32 bytes)</span></span> <span class="giallo-l"><span> // 0xAC chainId (uint256) (32 bytes)</span></span> <span class="giallo-l"><span> // 0xCC wallet (address) (20 bytes)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Copy bytecode + constant data to memory</span></span> <span class="giallo-l"><span> mstore(0x8c, salt) // salt</span></span> <span class="giallo-l"><span> mstore(0xac, chainid()) // chainId</span></span> <span class="giallo-l"><span> mstore(0xcc, wallet) // wallet address (20 bytes)</span></span> <span class="giallo-l"><span> mstore(0x6c, 0x5af43d82803e903d91602b57fd5bf3) // ERC-1167 footer</span></span> <span class="giallo-l"><span> mstore(0x5d, serviceImplementation) // implementation</span></span> <span class="giallo-l"><span> mstore(0x49, 0x3d60ad80600a3d3981f3363d3d373d3d3d363d73) // ERC-1167 constructor + header</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Copy create2 computation data to memory</span></span> <span class="giallo-l"><span> mstore8(0x00, 0xff) // 0xFF</span></span> <span class="giallo-l"><span> mstore(0x35, keccak256(0x55, 0x8b)) // keccak256(bytecode) - 0x8b = 139 bytes</span></span> <span class="giallo-l"><span> mstore(0x01, shl(96, address())) // registry address</span></span> <span class="giallo-l"><span> mstore(0x15, salt) // salt</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Compute service address</span></span> <span class="giallo-l"><span> let computed := keccak256(0x00, 0x55)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // If the service has not yet been deployed</span></span> <span class="giallo-l"><span> if iszero(extcodesize(computed)) {</span></span> <span class="giallo-l"><span> // Deploy service contract</span></span> <span class="giallo-l"><span> let deployed := create2(0, 0x55, 0x8b, salt) // 0x8b = 139 bytes</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Revert if the deployment fails</span></span> <span class="giallo-l"><span> if iszero(deployed) {</span></span> <span class="giallo-l"><span> mstore(0x00, 0xd786d393) // `DeployFailed()`</span></span> <span class="giallo-l"><span> revert(0x1c, 0x04)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Emit the ServiceDeployed event</span></span> <span class="giallo-l"><span> mstore(0x00, deployed) // deployedService</span></span> <span class="giallo-l"><span> mstore(0x20, serviceImplementation) // serviceImplementation</span></span> <span class="giallo-l"><span> mstore(0x40, salt) // salt</span></span> <span class="giallo-l"><span> mstore(0x60, chainid()) // chainId</span></span> <span class="giallo-l"><span> mstore(0x80, wallet) // wallet</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> log4(</span></span> <span class="giallo-l"><span> 0x00, // Start of data</span></span> <span class="giallo-l"><span> 0xa0, // Data length (160 bytes: deployed + implementation + salt + chainId + wallet)</span></span> <span class="giallo-l"><span> 0x2f82bd0c129ea2d065cf394fb7760031982c6278372c89e1a059f2478ddf4763, // Event signature hash</span></span> <span class="giallo-l"><span> deployed, // indexed deployedService</span></span> <span class="giallo-l"><span> serviceImplementation, // indexed serviceImplementation</span></span> <span class="giallo-l"><span> salt, // salt</span></span> <span class="giallo-l"><span> chainid(), // chainId</span></span> <span class="giallo-l"><span> wallet // indexed wallet</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Return the service address</span></span> <span class="giallo-l"><span> return(0x00, 0x20)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Otherwise, return the computed service address</span></span> <span class="giallo-l"><span> mstore(0x00, computed)</span></span> <span class="giallo-l"><span> return(0x00, 0x20)</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 serviceAddress(</span></span> <span class="giallo-l"><span> address serviceImplementation,</span></span> <span class="giallo-l"><span> bytes32 salt,</span></span> <span class="giallo-l"><span> uint256 chainId,</span></span> <span class="giallo-l"><span> address wallet</span></span> <span class="giallo-l"><span> ) external view override returns (address) {</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> // Copy bytecode + constant data to memory</span></span> <span class="giallo-l"><span> mstore(0x8c, salt) // salt</span></span> <span class="giallo-l"><span> mstore(0xac, chainId) // chainId</span></span> <span class="giallo-l"><span> mstore(0xcc, wallet) // wallet address (20 bytes)</span></span> <span class="giallo-l"><span> mstore(0x6c, 0x5af43d82803e903d91602b57fd5bf3) // ERC-1167 footer</span></span> <span class="giallo-l"><span> mstore(0x5d, serviceImplementation) // implementation</span></span> <span class="giallo-l"><span> mstore(0x49, 0x3d60ad80600a3d3981f3363d3d373d3d3d363d73) // ERC-1167 constructor + header</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Copy create2 computation data to memory</span></span> <span class="giallo-l"><span> mstore8(0x00, 0xff) // 0xFF</span></span> <span class="giallo-l"><span> mstore(0x35, keccak256(0x55, 0x8b)) // keccak256(bytecode) - 0x8b = 139 bytes</span></span> <span class="giallo-l"><span> mstore(0x01, shl(96, address())) // registry address</span></span> <span class="giallo-l"><span> mstore(0x15, salt) // salt</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Compute and return the service address</span></span> <span class="giallo-l"><span> mstore(0x00, keccak256(0x00, 0x55))</span></span> <span class="giallo-l"><span> return(0x00, 0x20)</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="ownership-and-control">Ownership and Control</h3> <p>Wallet-linked services MUST be controlled by the <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> wallet owner to prevent unauthorized access. Implementers SHOULD include safeguards against malicious or unverified implementations.</p> <h3 id="upgradeability-risks">Upgradeability Risks</h3> <p>If a service is upgradable, ensure secure upgrade mechanisms to prevent unauthorized changes. For example:</p> <ul> <li> <p>The owner of the service SHOULD be the wallet itself.</p> </li> <li> <p>Only the wallet SHOULD be able to upgrade the implementation of the service.</p> </li> <li> <p>Implement versioning to ensure backward compatibility between upgrades.</p> </li> <li> <p>Use a timelock or multisig for critical upgrades to reduce the risk of malicious changes.</p> </li> </ul> <h3 id="reentrancy-and-cross-contract-interactions">Reentrancy and Cross-Contract Interactions</h3> <p>Services interacting with external protocols SHOULD follow best practices to prevent reentrancy attacks.</p> <h3 id="user-education">User Education</h3> <p>Clear user interfaces and warnings SHOULD be provided to reduce phishing and social engineering risks.</p> <h3 id="testing">Testing</h3> <p>Implementers SHOULD thoroughly test the registry and services on testnets to ensure correctness and security before deploying to mainnet.</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-14T00:00:00+00:00 2026-02-11T14:49:27+00:00 lightclienthttps://github.com/lightclient Felix Langehttps://github.com/fjl https://wg-eips.ritovision.com/7685/

A general purpose bus for sharing EL triggered requests with the CL

<h2 id="abstract">Abstract</h2> <p>This proposal defines a general purpose framework for storing contract-triggered requests. It extends the execution header with a single field to store the request information. Requests are later on exposed to the consensus layer, which then processes each one.</p> <h2 id="motivation">Motivation</h2> <p>The proliferation of smart contract controlled validators has caused there to be a demand for additional EL triggered behaviors. By allowing these systems to delegate administrative operations to their governing smart contracts, they can avoid intermediaries needing to step in and ensure certain operations occur. This creates a safer system for end users. By abstracting each individual request details from the EL, adding new request types is simpler and does not require an update on the execution block structure.</p> <h2 id="specification">Specification</h2> <h3 id="execution-layer">Execution Layer</h3> <h4 id="requests">Requests</h4> <p>A <code>requests</code> object consists of a <code>request_type</code> byte prepended to an opaque byte array <code>request_data</code>. The <code>request_data</code> contains zero or more encoded request objects.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>requests = request_type ++ request_data</span></span></code></pre> <p>Each request type will define its own <code>requests</code> object with its own <code>request_data</code> format.</p> <h4 id="block-header">Block Header</h4> <p>Extend the header with a new 32 byte commitment value <code>requests_hash</code>.</p> <p>While processing a block, multiple <code>requests</code> objects with different <code>request_type</code>s will be produced by the system, and accumulated in the block requests list.</p> <p>In order to compute the commitment, an intermediate hash list is first built by hashing all non-empty requests elements of the block requests list. Items with empty <code>request_data</code> are excluded, i.e. the intermediate list skips <code>requests</code> items which contain only the <code>request_type</code> (1 byte) and nothing else.</p> <p>Within the intermediate list, <code>requests</code> items must be ordered by <code>request_type</code> ascending.</p> <p>The final commitment is computed as the sha256 hash of the intermediate element hashes.</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_requests_hash</span><span>(</span><span class="z-variable z-parameter z-function">block_requests</span><span>:</span><span> Sequence</span><span>[</span><span class="z-support">bytes</span><span>]</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> m</span><span class="z-keyword"> =</span><span> sha256</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> r</span><span class="z-keyword"> in</span><span> block_requests</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>r</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 1</span><span>:</span></span> <span class="giallo-l"><span> m</span><span>.</span><span>update</span><span>(</span><span>sha256</span><span>(</span><span>r</span><span>)</span><span>.</span><span>digest</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> m</span><span>.</span><span>digest</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>block</span><span>.</span><span>header</span><span>.</span><span>requests_hash</span><span class="z-keyword"> =</span><span> compute_requests_hash</span><span>(</span><span>requests</span><span>)</span></span></code></pre><h3 id="consensus-layer">Consensus Layer</h3> <p>Each proposal may choose how to extend the beacon chain types to include new EL request types.</p> <h2 id="rationale">Rationale</h2> <h3 id="opaque-byte-array-rather-than-an-rlp-array">Opaque byte array rather than an RLP array</h3> <p>By having the bytes of <code>request_data</code> array from second byte on be opaque bytes, rather than an RLP (or other encoding) list, we can support different encoding formats for the request payload in the future such as SSZ, LEB128, or a fixed width format.</p> <h3 id="request-source-and-validity">Request source and validity</h3> <p>This EIP makes no strict requirement where a request may come from nor when/how a request must be validated. This is to provide future protocol designers maximum flexibility.</p> <p>The authors' recommendations on source and validity of requests are:</p> <ul> <li>The source of requests should be from the execution of transactions. More specifically, transactions which make calls to designated system contracts that store the request in account. The storage would later be retrieved by a post-block system call to the contract. Alternatively, if the system call does not need to be inherently concerned with rate limiting, it could rely simply on emitting an event which is later parsed post-block by the system and converted into a request.</li> <li>A request's validity can often not be fully verified at the execution layer. This is why they are referred to merely as "requests"; they do not carry the authority on their own to unilaterally catalyze an action. We expect the system contracts to perform whatever validation is possible by the EL and then pass it on to the CL for further validation.</li> </ul> <h3 id="ordering">Ordering</h3> <p>The ordering across types is ascending by type. This is to simplify the process of verifying that all requests which were committed to in <code>requests_hash</code> match.</p> <p>An alternative could be to order by when the request was generated within the block. Since it's expected that many requests will be accumulated at the end of the block via system calls, this would be difficult to enforce. Therefore, ordering by type is the most straightforward ordering which ensures integrity.</p> <h4 id="intra-type">Intra-type</h4> <p>Within the same type, order is not defined. This is because the data of the request is opaque as far as this EIP is concerned. Therefore, it is to be determined by each request type individually.</p> <h3 id="removing-empty-requests-in-commitment">Removing empty requests in commitment</h3> <p>We exclude empty requests elements from the <code>requests_hash</code> commitment in order to get a stable 'empty' hash value that is independent of the blockchain fork. For a block with no requests data, the <code>requests_hash</code> is simply <code>sha256("")</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>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-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-11T00:00:00+00:00 2026-02-11T14:48:25+00:00 Mark Todahttps://github.com/marktoda Matt Ricehttps://github.com/mrice32 Nick Paihttps://github.com/nicholaspai https://wg-eips.ritovision.com/7683/

An interface for cross-chain trade execution systems.

<h2 id="abstract">Abstract</h2> <p>The following standard allows for the implementation of a standard API for cross-chain value-transfer systems. This standard provides generic order structs, as well as a standard set of settlement smart contract interfaces.</p> <h2 id="motivation">Motivation</h2> <p>Intent-based systems have become the preeminent solution for end-user cross-chain interaction by abstracting away the complexity and time constraints of traditional bridges. One of the key difficulties for cross-chain intents systems is accessing sufficient liquidity and a network of active fillers across chains. This challenge may be exacerbated as the number of distinct chains increases over time. The end result of this is a poor experience for users including higher costs, longer wait times and higher failure rates than necessary.</p> <p>By implementing a standard, cross-chain intents systems can interoperate and share infrastructure such as order dissemination services and filler networks, thereby improving end-user experience by increasing competition for fulfilling user intents.</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="glossary-of-terms">Glossary of Terms</h3> <ul> <li><strong>Destination Chain</strong>: the chain where the intent is executed and the user receives funds. Note: intents can involve multiple destination chains.</li> <li><strong>Filler</strong>: a participant who fulfils a user intent on the destination chain(s) and receives payment as a reward.</li> <li><strong>Leg</strong>: a portion of the user intent that can be executed independently from others. All legs must be executed for an intent to be considered fulfilled.</li> <li><strong>Origin chain</strong>: the chain where the user sends funds.</li> <li><strong>Settlement System</strong>: a system that custodies user deposits, verifies fills, and pays fillers for the purpose of facilitating intents.</li> <li><strong>Settler</strong>: a contract that implements part of the settlement system on a particular chain.</li> <li><strong>User</strong>: for the purposes of this document, the user is the end-user who is sending the order.</li> </ul> <h3 id="order-structs">Order structs</h3> <p>A compliant cross-chain order type MUST be ABI decodable into either <code>GaslessCrossChainOrder</code> or <code>OnchainCrossChainOrder</code> type.</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"> GaslessCrossChainOrder CrossChainOrder type</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Standard order struct to be signed by users, disseminated to fillers, and submitted to origin settler contracts by fillers</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> GaslessCrossChainOrder</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"> The contract address that the order is meant to be settled by.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Fillers send this order to this contract address on the origin chain</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> originSettler</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"> The address of the user who is initiating the swap,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> whose input tokens will be taken and escrowed</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> user</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"> Nonce to be used as replay protection for the order</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-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The chainId of the origin chain</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> originChainId</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"> The timestamp by which the order must be opened</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> openDeadline</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"> The timestamp by which the order must be filled on the destination chain</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> fillDeadline</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"> Type identifier for the order data. This is an EIP-712 typehash.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> orderDataType</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"> 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> <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"> OnchainCrossChainOrder CrossChainOrder type</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Standard order struct for user-opened orders, where the user is the one submitting the order creation transaction</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> OnchainCrossChainOrder</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"> The timestamp by which the order must be filled on the destination chain</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> fillDeadline</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"> Type identifier for the order data. This is an EIP-712 typehash.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> orderDataType</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"> 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> <span class="giallo-l"><span>}</span></span></code></pre> <p>Cross-chain execution systems implementing this standard SHOULD use a sub-type that can be parsed from the arbitrary <code>orderData</code> field. This may include information such as the tokens involved in the transfer, the destination chain IDs, fulfillment constraints or settlement oracles.</p> <p>All sub-types SHOULD be registered in a subtypes repository to encourage sharing of sub-types based on their functionality. See the examples section for an example of how sub-types can be used to support behavior like executing calldata on a target contract of the user's choice on the destination chain.</p> <h3 id="resolvedcrosschainorder-struct">ResolvedCrossChainOrder struct</h3> <p>A compliant cross-chain order type MUST be convertible into the <code>ResolvedCrossChainOrder</code> struct. This means that the <code>orderData</code> must be decoded into the information needed to populate the <code>ResolvedCrossChainOrder</code> struct. Additionally, <code>orderData</code> SHOULD be decodable into a sub-type, which can be used for further functionality such as cross-chain calldata execution (see the examples section for an example of this). It is the responsibility of the <code>user</code> and the <code>filler</code> to ensure that the <code>originSettler</code> supports their order's contained sub-type.</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"> ResolvedCrossChainOrder type</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> An implementation-generic representation of an order intended for filler consumption</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Defines all requirements for filling an order by unbundling the implementation-specific orderData.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Intended to improve integration generalization by allowing fillers to compute the exact input and output information of any order</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> ResolvedCrossChainOrder</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"> The address of the user who is initiating the transfer</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> user</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"> The chainId of the origin chain</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> originChainId</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"> The timestamp by which the order must be opened</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> openDeadline</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"> The timestamp by which the order must be filled on the destination chain(s)</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> fillDeadline</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"> The unique identifier for this order within this settlement system</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> orderId</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"> The max outputs that the filler will send. It&#39;s possible the actual amount depends on the state of the destination</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> chain (destination dutch auction, for instance), so these outputs should be considered a cap on filler liabilities.</span></span> <span class="giallo-l"><span> Output</span><span>[</span><span>]</span><span> maxSpent</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"> The minimum outputs that must be given to the filler as part of order settlement. Similar to maxSpent, it&#39;s possible</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> that special order types may not be able to guarantee the exact amount at open time, so this should be considered</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> a floor on filler receipts. Setting the `recipient` of an `Output` to address(0) indicates that the filler is not</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> known when creating this order.</span></span> <span class="giallo-l"><span> Output</span><span>[</span><span>]</span><span> minReceived</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"> Each instruction in this array is parameterizes a single leg of the fill. This provides the filler with the information</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> necessary to perform the fill on the destination(s).</span></span> <span class="giallo-l"><span> FillInstruction</span><span>[</span><span>]</span><span> fillInstructions</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"> @notice</span><span class="z-comment"> Tokens that must be received for a valid order fulfillment</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Output</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"> The address of the ERC20 token on the destination chain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> address(0) used as a sentinel for the native token</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> token</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"> The amount of the token to be sent</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-storage z-type"> @dev</span><span class="z-comment"> The address to receive the output tokens</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> recipient</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"> The destination chain for this output</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> chainId</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"> FillInstruction type</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Instructions to parameterize each leg of the fill</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Provides all the origin-generated information required to produce a valid fill leg</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> FillInstruction</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"> The chain that this instruction is intended to be filled on</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> destinationChainId</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"> The contract address that the instruction is intended to be filled on</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> destinationSettler</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"> The data generated on the origin chain needed by the destinationSettler to process the fill</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> originData</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="open-event">Open event</h3> <p>A compliant <code>Open</code> event MUST adhere to the following abi:</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"> @notice</span><span class="z-comment"> Signals that an order has been opened</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> orderId</span><span class="z-comment"> a unique order identifier within this settlement 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"> resolvedOrder</span><span class="z-comment"> resolved order that would be returned by resolve if called instead of Open</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Open</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderId</span><span>, </span><span class="z-variable">ResolvedCrossChainOrder</span><span class="z-variable"> resolvedOrder</span><span>)</span><span>;</span></span></code></pre><h3 id="settlement-interfaces">Settlement interfaces</h3> <p>A compliant origin settler contract implementation MUST implement the <code>IOriginSettler</code> interface:</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"> IOriginSettler</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Standard interface for settlement contracts on the origin chain</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IOriginSettler</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"> Opens a gasless cross-chain order on behalf of 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"> To be called by the filler.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This method must emit the Open 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"> order</span><span class="z-comment"> The GaslessCrossChainOrder definition</span></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"> The user&#39;s signature over the order</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> originFillerData</span><span class="z-comment"> Any filler-defined data required by the settler</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> openFor</span><span>(</span><span class="z-storage z-type">GaslessCrossChainOrder</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> order</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-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> originFillerData</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"> Opens a cross-chain order</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> To be called 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"> This method must emit the Open 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"> order</span><span class="z-comment"> The OnchainCrossChainOrder definition</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> open</span><span>(</span><span class="z-storage z-type">OnchainCrossChainOrder</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> order</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"> Resolves a specific GaslessCrossChainOrder into a generic ResolvedCrossChainOrder</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Intended to improve standardized integration of various order types and settlement contracts</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> order</span><span class="z-comment"> The GaslessCrossChainOrder definition</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> originFillerData</span><span class="z-comment"> Any filler-defined data required by the settler</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"> ResolvedCrossChainOrder</span><span class="z-comment"> hydrated order data including the inputs and outputs of the order</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> resolveFor</span><span>(</span><span class="z-storage z-type">GaslessCrossChainOrder</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> order</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> originFillerData</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">ResolvedCrossChainOrder</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"> Resolves a specific OnchainCrossChainOrder into a generic ResolvedCrossChainOrder</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Intended to improve standardized integration of various order types and settlement contracts</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> order</span><span class="z-comment"> The OnchainCrossChainOrder definition</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"> ResolvedCrossChainOrder</span><span class="z-comment"> hydrated order data including the inputs and outputs of the order</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">OnchainCrossChainOrder</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> order</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">ResolvedCrossChainOrder</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>A compliant destination settlement contract implementation MUST implement the <code>IDestinationSettler</code> interface:</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"> IDestinationSettler</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Standard interface for settlement contracts on the destination chain</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IDestinationSettler</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"> Fills a single leg of a particular order on the destination chain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> orderId</span><span class="z-comment"> Unique order identifier for this order</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> originData</span><span class="z-comment"> Data emitted on the origin to parameterize the fill</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> fillerData</span><span class="z-comment"> Data provided by the filler to inform the fill or express their preferences</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> fill</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> orderId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> originData</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> fillerData</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="fillerdata">fillerData</h3> <p>Cross-chain execution systems implementing this standard SHOULD use a sub-type that can be parsed from the arbitrary <code>fillerData</code> field. This may include information such as the desired timing or form of payment for the filler</p> <p>All sub-types SHOULD be registered in a subtypes repository to encourage sharing of sub-types based on their functionality.</p> <h2 id="rationale">Rationale</h2> <h3 id="generic-orderdata">Generic OrderData</h3> <p>A key consideration is to ensure that a broad range of cross-chain intent designs can work within the same standard. To enable this, the specification is designed around a cross-chain intents <em>flow</em>, with two variations: gasless and onchain.</p> <h4 id="gasless-cross-chain-intents-flow">Gasless cross-chain intents flow</h4> <p>Origin Chain:</p> <ol> <li>The user signs an off-chain message defining the parameters of their order</li> <li>The order is disseminated to fillers</li> <li>The filler calls resolve to unpack the order's requirements</li> <li>The filler opens the order on the origin chain</li> </ol> <p>Destination Chain(s):</p> <ul> <li>The filler fills each leg of the order on the destination chain(s)</li> </ul> <p>Settlement:</p> <ul> <li>A cross-chain settlement process takes place to settle the order</li> </ul> <h4 id="onchain-cross-chain-intents-flow">Onchain cross-chain intents flow</h4> <p>Origin Chain:</p> <ol> <li>The caller signs a transaction calling open with their order</li> <li>The filler retrieves the emitted event to determine requirements</li> </ol> <p>Destination Chain(s):</p> <ul> <li>The filler fills each leg of the order on the destination chain(s)</li> </ul> <p>Settlement:</p> <ul> <li>A cross-chain settlement process takes place to settle the order</li> </ul> <h4 id="customization">Customization</h4> <p>Within this flow, implementers of the standard have design flexibility to customize behavior such as:</p> <ul> <li>Price resolution, e.g. dutch auctions (on origin or destination) or oracle-based pricing</li> <li>Fulfillment constraints</li> <li>Settlement procedures</li> <li>Ordering of the origin and destination chain actions, e.g. the fill could happen before <code>open</code> in some settlement systems</li> </ul> <p>The <code>orderData</code> field allows implementations to take arbitrary specifications for these behaviors while still enabling integrators to parse the primary fields of the order.</p> <p>This functionality also motivated the <code>resolve</code> view function and <code>ResolvedCrossChainOrder</code> type. Resolution enables integrating fillers to validate and assess orders without specific knowledge of the <code>orderData</code> field at hand.</p> <h3 id="emission-of-fill-instructions">Emission of Fill Instructions</h3> <p>An important component of the standard is creating a flexible and robust mechanism for fillers to ensure their fills are valid. For a fill to be valid, it typically must satisfy the following constraints:</p> <ol> <li>It must be filled on the correct destination chain(s)</li> <li>It must be filled on the correct destination contract</li> <li>It must include some (not necessarily all) information from the order that the user provided on the origin chain</li> <li>It may require some execution information from the <code>open</code> call on the origin chain (ex. dutch auctions based on open timing)</li> </ol> <p>The <code>FillInstruction</code> array in <code>ResolvedCrossChainOrder</code> is intended to ensure it's simple for the filler to meet all of these requirements by either listening for the <code>Open</code> or by calling <code>resolve</code>.</p> <p>One may notice that the <code>originData</code> field within <code>FillInstruction</code> is completely opaque. This opaqueness allows the settler implementations to freely customize the data they transmit. Because fillers do not need to interpret this information, the opaqueness does not result in any additional implementation costs on fillers.</p> <p>This functionality also makes it feasible for a user, filler, or order distribution system to perform an end-to-end simulation of the order initiation and fill to evaluate all resulting state transitions without understanding the nuances of a particular execution system.</p> <h3 id="cross-compatibility">Cross-compatibility</h3> <p>Since this standard is intended to reduce friction for users moving value across chains, non-EVM ecosystems should not be excluded. However, attempting to pull each non-EVM ecosystem in would dramatically increase the size and complexity of this standard, while omitting any that come in the future.</p> <p>Instead, this standard is intended to be cross-compatible with other ecosystems. It standardizes interfaces and data types on EVM chains, but allows for the creation of sibling standards that define compatible interfaces, data types, and flows within other ecosystems. Intents created within these sibling standards should be able to be filled on an EVM chain and vice versa.</p> <p>To ensure this cross-compatibility, all foreign addresses use <code>bytes32</code> rather than <code>address</code> to allow for larger address identifiers.</p> <h3 id="usage-of-permit2">Usage of Permit2</h3> <p>Permit2 is not specifically required by this standard, but does provide an efficient and straightforward approach to building standard-adherent protocols. Specifically, the <code>witness</code> functions of permit2 allow users to both approve the token transfer <em>and</em> the order itself with a single signature. This also nicely couples the transfer of tokens with a successful initiation of the order.</p> <p>In contrast, a standard approval model would require two separate signatures - a token approval (either <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a> or on-chain) and a signature to approve the terms of the order. It also decouples the token approval from the order, meaning approved tokens could potentially be taken at any time due to a buggy or untrusted settler contract.</p> <p>When building a standard-compliant settler system around Permit2, the following considerations should be made</p> <ul> <li><code>nonce</code> in the order struct should be a permit2 nonce</li> <li><code>openDeadline</code> in the order struct should be the permit2 deadline</li> <li>A full order struct including the parsed <code>orderData</code> should be used as the witness type during the permit2 call. This ensures maximum transparency to the user as they sign their order permit.</li> </ul> <h3 id="examples">Examples</h3> <p>This is an example of how a 7683 cross-chain value transfer order can include instructions to the filler to execute arbitrary calldata on behalf of the recipient on the destination chain. This calldata execution is performed by the settlement contract atomically within the filler's fill() execution, so the arbitrary contract execution can take advantage of the destination chain recipient's newly transferred value. A hypothetical user in this example would select an <code>originSettler</code> that is known to support the <code>Message</code> sub-type.</p> <p>Let there be a sub-type called <code>Message</code>, which is defined by the following structs:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> The Message subtype allows ERC7683 intents to carry calldata that is executed on a target contract on the destination chain. The settlement contract that the filler interacts with on the destination chain will decode the message into smart contract calls and execute the calls within the filler&#39;s `fill()` transaction.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> The Message contains calls that the user wants executed on the destination chain.</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> The target is a contract on the destination chain that the settlement contract will attempt to send callData and value to.</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Calls</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> target</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> callData</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>}</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"> Message</span><span> {</span></span> <span class="giallo-l"><span> Calls</span><span>[</span><span>]</span><span> calls</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>Message</code> sub-type is designed to be used by a 7683 user to incentivize a filler to execute arbitrary calldata on a target destination chain contract on the user's behalf. For example, the settlement contract might decode the <code>originData</code> containing the message information 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"> fill</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> orderId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> originData</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> fillerData</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"> address</span><span> user</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> fillDeadline</span><span>,</span></span> <span class="giallo-l"><span> Output </span><span class="z-storage z-type">memory</span><span> fillerOutput</span><span>,</span></span> <span class="giallo-l"><span> Message </span><span class="z-storage z-type">memory</span><span> message</span></span> <span class="giallo-l"><span> )</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>originData</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 some preprocessing on the parameters here to validate the order...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ...Execute the fill logic of the ResolvedCrossChainOrder...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Handle the Message subtype:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Revert if any of the message calls fail.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> length </span><span class="z-keyword">=</span><span> message</span><span>.</span><span>calls</span><span>.</span><span>length</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> length</span><span>;</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>i</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> Call </span><span class="z-storage z-type">memory</span><span> call </span><span class="z-keyword">=</span><span> message</span><span>.</span><span>calls</span><span>[</span><span>i</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 we are calling an EOA with calldata, assume target was incorrectly specified and revert.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>call</span><span>.</span><span>callData</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span class="z-keyword"> &amp;&amp;</span><span> call</span><span>.</span><span>target</span><span>.</span><span>code</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"> revert</span><span class="z-entity z-name"> InvalidCall</span><span>(</span><span>i</span><span>,</span><span> calls</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 class="z-support">bool</span><span> success</span><span>,</span><span> )</span><span class="z-keyword"> =</span><span> call</span><span>.</span><span>target</span><span>.</span><span>call</span><span>{</span><span> value</span><span class="z-keyword">:</span><span> call</span><span>.</span><span>value </span><span>}</span><span>(</span><span>call</span><span>.</span><span>callData</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>success</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> CallReverted</span><span>(</span><span>i</span><span>,</span><span> message</span><span>.</span><span>calls</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <p>In this example, the Message sub-type allows the user to delegate destination chain contract execution to fillers. However, because transactions are executed via filler, the <code>msg.sender</code> would be the <code>DestinationSettler</code>, making this <code>Message</code> sub-type limited if the target contract authenticates based on the <code>msg.sender</code>. Ideally, 7683 orders containing Messages can be combined with smart contract wallets like implementations of <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> or <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> to allow complete cross-chain delegated execution.</p> <h2 id="security-considerations">Security Considerations</h2> <h4 id="evaluating-settlement-contract-security">Evaluating settlement contract security</h4> <p>This ERC is agnostic of how the settlement system validates a 7683 order fulfillment and refunds the filler. In fact, this ERC is designed to delegate the responsibility of evaluating the settlement contract's security to the filler and the application that creates the user's 7683 order.</p> <p>This design decision is motivated by the existence of many viable cross-chain messaging systems today offering settlement contracts a variety of tradeoffs. We hope that this standard can eventually support an ERC dedicated to standardizing a safe, trustless, cross-chain verification system.</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-09T00:00:00+00:00 2026-02-11T14:48:26+00:00 Lukas Rosariohttps://github.com/lukasrosario Wilson Cusackhttps://github.com/wilsoncusack Alex Doneskyhttps://github.com/adonesky1 https://wg-eips.ritovision.com/7682/

A capability allowing wallets to indicate that they have access to additional funds.

<h2 id="abstract">Abstract</h2> <p>An <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> compliant capability that allows wallets to indicate to apps that they have access to funds beyond those that can be accounted for by looking up balances onchain given the wallet's address.</p> <p>A wallet's ability to access auxiliary funds is communicated to apps as part of its response to an <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> <code>wallet_getCapabilities</code> request. The following standard does not specify the source of these auxiliary funds, but some examples are:</p> <ul> <li>Funds from offchain sources that can be onramped and used just-in-time</li> <li>Wallets that manage many accounts, where assets across those accounts can be transfered to the required account before submitting a transaction requested by an app</li> </ul> <h2 id="motivation">Motivation</h2> <p>Many applications check users' balances before letting them complete some action. For example, if a user wants to swap some amount of tokens on a dex, the dex will commonly block the user from doing so if it sees that the user does not have that amount of tokens at their address. However, more advanced wallets have features that let users access funds from other sources. Wallets need a way to tell apps that they have access to additional funds so that users using these more advanced wallets are not blocked by balance checks.</p> <h2 id="specification">Specification</h2> <p>One new <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> wallet capability is defined.</p> <h3 id="wallet-implementation">Wallet Implementation</h3> <p>To conform to this specification, wallets that wish to indicate that they have access to auxiliary funds MUST, for each chain they have access to auxiliary funds on, respond to <code>wallet_getCapabilities</code> calls with an <code>auxiliaryFunds</code> object with a <code>supported</code> field set to <code>true</code>.</p> <p>Wallets may also optionally specify which assets they have additional access to with an <code>assets</code> field, which maps to an array of addresses representing the assets the wallet might have additional access to. If a wallet does not respond with this optional array of assets, the application SHOULD assume the wallet has additional access to any asset.</p> <p>This specification does not put any constraints on the source of the auxiliary funds.</p> <p>In this specification, a chain's native asset (e.g. Ether on Ethereum) MUST be represented by "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE" as specified by <a href="https://wg-eips.ritovision.com/7528/">EIP-7528</a>.</p> <h4 id="wallet-getcapabilities-response-specification"><code>wallet_getCapabilities</code> Response Specification</h4> <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"> AuxiliaryFundsCapability</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> supported</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> assets</span><span class="z-keyword">?</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>]</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h5 id="wallet-getcapabilities-example-response"><code>wallet_getCapabilities</code> Example Response</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">0x2105</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">auxiliaryFunds</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">assets</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">0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE</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">0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913</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">0x14A34</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">auxiliaryFunds</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">assets</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">0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE</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">0x036CbD53842c5426634e7929541eC2318f3dCF7e</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><h3 id="extended-usage-requiredassets-parameter">Extended Usage: <code>requiredAssets</code> Parameter</h3> <p>When a wallet indicates support for the <code>auxiliaryFunds</code> capability (i.e., <code>supported: true</code>), applications that use the <a href="https://wg-eips.ritovision.com/5792/#wallet-sendcalls"><code>wallet_sendCalls</code></a> method MAY include a <code>requiredAssets</code> parameter in the <code>capabilities.auxiliaryFunds</code> object to enable the wallet to leverage this capability.</p> <p>A wallet's signaling support for the <code>auxiliaryFunds</code> capability does not necessarily mean they can interpret or use the <code>requiredAssets</code> metadata. The <code>requiredAssets</code> parameter is an optional capability that wallets may or may not support, even when they support the base <code>auxiliaryFunds</code> capability.</p> <p><strong>Native Asset Handling</strong>: Wallets SHOULD deduce native asset requirements (e.g., ETH on Ethereum mainnet) from the <code>call.value</code> field in the calls array rather than requiring explicit specification in <code>requiredAssets</code>. The <code>requiredAssets</code> parameter is primarily intended for token assets that cannot be inferred from call data alone.</p> <p>This parameter may be necessary because transaction call data alone does not reliably indicate which assets and amounts are needed for successful execution. Calls may involve complex logic or multiple contracts, making it difficult for wallets to infer requirements. By specifying required assets and amounts explicitly, apps ensure wallets have the information needed to provision, bridge, or swap assets as necessary for the transaction to succeed.</p> <h3 id="wallet-sendcalls-extended-parameter"><code>wallet_sendCalls</code> Extended Parameter</h3> <p>If included, the <code>requiredAssets</code> parameter MUST be specified within the <code>capabilities.auxiliaryFunds</code> object of the <code>wallet_sendCalls</code> request.</p> <blockquote> <p><strong>Note</strong>: The <code>capabilities</code> object is specified in <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> where <code>wallet_sendCalls</code> is first defined: "The capabilities field is how an app can communicate with a wallet about capabilities a wallet supports. For example, this is where an app can specify a paymaster service URL from which an <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> wallet can request a paymasterAndData input for a user operation."</p> </blockquote> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Example wallet_sendCalls type extension</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> WalletSendCallsRequest</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"> from</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> <span class="giallo-l"><span class="z-variable"> chainId</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> `</span><span class="z-string">0x{string}</span><span class="z-punctuation z-definition z-string">`</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> atomicRequired</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> calls</span><span class="z-keyword">:</span><span class="z-entity z-name"> Array</span><span>&lt;</span><span>{</span></span> <span class="giallo-l"><span class="z-variable"> to</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> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ... other call fields ...</span></span> <span class="giallo-l"><span> }</span><span>&gt;</span><span>;</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> <span class="giallo-l"><span class="z-variable"> auxiliaryFunds</span><span class="z-keyword">?</span><span class="z-keyword">:</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 class="z-variable"> requiredAssets</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> address</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> <span class="giallo-l"><span class="z-variable"> amount</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Amount required, as a hex string representing the integer value in the asset&#39;s smallest unit</span></span> <span class="giallo-l"><span class="z-variable"> standard</span><span class="z-keyword">:</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 class="z-keyword"> |</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 class="z-keyword"> |</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">erc1155</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"> Token standard</span></span> <span class="giallo-l"><span class="z-variable"> tokenId</span><span class="z-keyword">?</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Token ID as a hex string (required for ERC-721 and ERC-1155)</span></span> <span class="giallo-l"><span> }</span><span>[</span><span>]</span><span>;</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>}</span><span>;</span></span></code></pre><h4 id="example-scenario-cross-chain-deposit-to-aave">Example Scenario: Cross-Chain Deposit to Aave</h4> <p>Suppose a user wants to deposit DAI into Aave on Chain X, but their wallet address on Chain X has no DAI or native gas token. However, the wallet has access to funds on Chain Y (e.g., Ethereum mainnet). The app, upon detecting the <code>auxiliaryFunds</code> capability, can construct a <code>wallet_sendCalls</code> request as follows:</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">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">0xAaveDAIDepositContractOnChainX</span><span class="z-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">0xd0e30db0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Example encoded deposit function call</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">auxiliaryFunds</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">requiredAssets</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">0x6B175474E89094C44Da98b954EedeAC495271d0F</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"> DAI address on Chain X</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">amount</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0de0b6b3a7640000</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"> 1 DAI</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">standard</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 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>The wallet, upon receiving this request, can:</p> <ul> <li>Bridge or swap the required DAI from Chain Y to Chain X</li> <li>Ensure the user has enough native asset (e.g., ETH) for gas on Chain X</li> <li>Complete the deposit call to Aave on Chain X</li> </ul> <p>This mechanism allows advanced wallets to abstract away the complexity of cross-chain or offchain funding, enabling seamless user experiences even when the user's onchain balance is insufficient on the target chain.</p> <h3 id="token-standard-extensibility">Token Standard Extensibility</h3> <p>This specification currently supports three token standards with the following field requirements:</p> <ul> <li><strong><a href="https://wg-eips.ritovision.com/20/">ERC-20</a></strong>: Requires <code>amount</code> field only</li> <li><strong><a href="https://wg-eips.ritovision.com/721/">ERC-721</a></strong>: Requires both <code>amount</code> and <code>tokenId</code> fields</li> <li><strong><a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a></strong>: Requires both <code>amount</code> and <code>tokenId</code> fields</li> </ul> <p>The <code>amount</code> field semantics vary by token standard:</p> <ul> <li><strong><a href="https://wg-eips.ritovision.com/20/">ERC-20</a></strong>: Represents token quantity in smallest unit (e.g., wei for 18-decimal tokens)</li> <li><strong><a href="https://wg-eips.ritovision.com/721/">ERC-721</a></strong>: Represents NFT quantity (typically "0x01" for single NFT instances)</li> <li><strong><a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a></strong>: Represents quantity of the specified token ID</li> </ul> <p>Future token standards MUST specify additional required fields as properties on the asset object root to maintain extensibility.</p> <h3 id="auxiliary-funds-and-atomic-execution">Auxiliary Funds and Atomic Execution</h3> <p>Auxiliary funds provisioning (bridging, swapping, or other asset retrieval operations) is independent of the <code>wallet_sendCalls</code> execution lifecycle. The <code>atomicRequired</code> field applies only to the call bundle execution, not to auxiliary funds provisioning.</p> <h3 id="error-codes">Error Codes</h3> <p>The following error codes are defined for auxiliary funds provisioning failures.</p> <table><thead><tr><th>Code</th><th>Message</th><th>Description</th></tr></thead><tbody> <tr><td>5770</td><td>Auxiliary funds provisioning failed</td><td>Wallet attempted to provision funds but failed (e.g., bridge/swap error).</td></tr> <tr><td>5771</td><td>Asset not supported</td><td>The requested asset is not available through the wallet's auxiliary fund system.</td></tr> <tr><td>5772</td><td>Auxiliary funds capability not available</td><td>The wallet no longer supports auxiliary funds on the requested chain.</td></tr> <tr><td>5773</td><td>Invalid requiredAssets</td><td>The structure of the requiredAssets object is malformed.</td></tr> </tbody></table> <p>Applications SHOULD use the <code>wallet_getCallsStatus</code> method to track the status of call bundles that involve auxiliary funds provisioning, as the provisioning process may take time to complete. The status response will indicate whether the auxiliary funds provisioning is in progress, completed, or failed.</p> <h3 id="app-implementation-guidance">App Implementation Guidance</h3> <p>When an app sees that a connected wallet has access to auxiliary funds via the <code>auxiliaryFunds</code> capability in a <code>wallet_getCapabilities</code> response, the app SHOULD NOT block users from taking actions on the basis of asset balance checks.</p> <p>Apps MAY include the <code>requiredAssets</code> parameter in the <code>capabilities.auxiliaryFunds</code> object to ensure the wallet has the necessary information to provision assets as needed for successful execution. However, apps should be aware that this is an optional capability and should handle cases where wallets do not support or cannot process the <code>requiredAssets</code> metadata gracefully.</p> <h3 id="amount-validation">Amount Validation</h3> <p>The wallet MUST cross-check the <code>amount</code> value in <code>requiredAssets</code> against the <code>decimal()</code> value specified on the <code>asset</code>'s contract to ensure that the amount is interpreted correctly according to the asset's decimal precision.</p> <h2 id="rationale">Rationale</h2> <h3 id="alternatives">Alternatives</h3> <h4 id="advanced-balance-fetching">Advanced Balance Fetching</h4> <p>An alternative we considered is defining a way for apps to fetch available auxiliary balances. This could be done, for example, by providing a URL as part of the <code>auxiliaryFunds</code> capability that apps could use to fetch auxiliary balance information. However, we ultimately decided that a boolean was enough to indicate to apps that they should not block user actions on the basis of balance checks, and it is minimally burdensome for apps to implement.</p> <p>The shape of this capability allows for a more advanced extension if apps feel more functionality is needed.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <ul> <li>Applications SHOULD only include the <code>requiredAssets</code> parameter if the wallet advertises the <code>auxiliaryFunds</code> capability.</li> <li>Applications SHOULD include the <code>auxiliaryFunds</code> capability with <code>optional: true</code> to provide metadata to wallets that support this optional capability while maintaining compatibility with wallets that do not.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>Apps MUST NOT make any assumptions about the source of auxiliary funds. Apps' smart contracts should still, as they would today, make appropriate balance checks onchain when processing a transaction.</li> <li>Applications MUST NOT assume that the wallet will always be able to fulfill the asset requirements, and SHOULD handle failures gracefully.</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> 2024-04-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Sennett Lauhttps://github.com/sennett-lau https://wg-eips.ritovision.com/7681/

Combining fungible token ERC-20 and multi-token ERC-1155

<h2 id="abstract">Abstract</h2> <p>This proposal <a href="https://wg-eips.ritovision.com/7681/">ERC-7681</a> delineates the integration of the fungible <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token contract with the semi-fungible <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> multi-token standard, enabling cohesive operations between both standards within a single contract framework. It defines a mechanism for combining two token contracts and synchronizing operations between them.</p> <h2 id="motivation">Motivation</h2> <p>Inspired by <a href="https://wg-eips.ritovision.com/7631/">ERC-7631</a> Dual Nature Token Pair, which introduced a concept of interlinkable tokens between ERC-20 and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, a challenge arises due to the duplicated <code>Transfer(address, address, uint256)</code> event, making full compatibility challenging. However, combining ERC-20 and ERC-1155 offers similar benefits of non-fungible token (NFT) fractionalization natively. Here, acquiring ERC-20 tokens could automatically issue ERC-1155 tokens proportionally to the ERC-20 holdings, achieving full compliance with both standards.</p> <p>Furthermore, analogous to ERC-7631, this proposal allows users to opt out of ERC-1155 mints and transfers during the ERC-20 to ERC-1155 synchronization process.</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="overview">Overview</h3> <p>Every <code>ERC-7681</code> MUST implement both <code>ERC20</code> and <code>ERC1155</code> interfaces.</p> <h3 id="erc-7681-interface">ERC-7681 Interface</h3> <p>The ERC-20 contract 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"> IERC7681</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC20, IERC1155 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The contract MUST contain the following events</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ERC20 related events</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 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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The contract MUST contain the following events</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ERC1155 related events</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferSingle</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">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"> _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"> TransferBatch</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">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"> _values</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"> URI</span><span>(</span><span class="z-support">string</span><span class="z-variable"> _value</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 class="z-comment"> The contract MAY contain the following functions</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ERC20 related functions</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"> 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>;</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"> 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>;</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-comment"> ///</span><span class="z-comment"> The contract MUST contain the following functions</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ERC20 related functions</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"> 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 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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The contract MUST contain the following functions</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ERC1155 related functions</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 class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOfBatch</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"> _owners</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"> _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">uint256</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-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 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 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 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 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 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-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>;</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-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>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _ids</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"> _values</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>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="erc-7681-skippable-interface">ERC-7681 Skippable Interface</h3> <p>The ERC-7681 contract MAY 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"> IERC7681Skippable</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 the skip ERC1155 token status of `owner` is </span><span class="z-keyword">changed</span><span class="z-comment"> by any mechanism.</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"> This initial skip ERC1155 token status for `owner` can be dynamically chosen to</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> be true or false, but any changes to it MUST emit this event.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SkipTokenSet</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">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-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Returns true if ERC-1155 mints and transfers to `owner` SHOULD be</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> skipped during ERC-20 to ERC-1155 synchronization. Otherwise false.</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"> ///</span><span class="z-comment"> This method MAY revert</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"> If this method reverts:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Interacting code SHOULD interpret `setSkipToken` functionality as</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> unavailable (and hide any functionality to call `setSkipToken`).</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - The skip ERC1155 token status for `owner` SHOULD be interpreted as undefined.</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"> Once a true or false value has been returned for a given `owner`,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> this method MUST NOT revert for the given `owner`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getSkipToken</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Sets the caller&#39;s skip ERC1155 token status.</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"> This method MAY revert</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (e.g. insufficient permissions, method not supported).</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"> Emits a {SkipTokenSet} event.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setSkipToken</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> status</span><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="implementation-flexibility">Implementation Flexibility</h3> <p>This proposal intentionally does not prescribe specific token synchronization logic to allow for diverse implementation strategies and novel use cases, such as one-to-one synchronization or fractionalization of ERC-1155 tokens based on ERC-20 holdings. Developers are afforded the flexibility to determine their synchronization approach, provided it remains fully compliant with the specifications of both token standards.</p> <h3 id="erc-1155-token-skipping">ERC-1155 Token Skipping</h3> <p>For instances where the <code>owner</code> is a smart contract, setting the skip status to <code>true</code> by default can prevent unnecessary ERC-1155 minting for interactions with contracts like DEXs and lending protocols, thereby potentially reducing gas costs.</p> <h3 id="backwards-compatibility">Backwards Compatibility</h3> <p>This proposal is fully backward-compatible with the existing ERC-20 and ERC-1155 standards, ensuring that contracts reliant on these standards will continue to function seamlessly.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="out-of-gas-denial-of-service">Out-of-gas Denial of Service</h3> <p>When user transfers ERC-20 tokens, it can trigger the automatic minting, transfer, or burning of various ERC-1155 tokens. This process can lead to gas expenses that grow linearly with the number of actions O(n) rather than the fixed cost O(1) usually seen with ERC-20 token transactions. Additionally, the mechanism for choosing ERC-1155 token IDs might increase gas expenses further. Therefore, any synchronization strategy needs to account for the potential rise in ERC-1155 associated gas costs to avoid running out of gas, which could result in denial of service situations.</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-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 Derek Chianghttps://github.com/derekchiang Garvit Khatrihttps://github.com/plusminushalf Fil Makarovhttps://github.com/filmakarov Kristof Gazsohttps://github.com/kristofgazso Derek Reinhttps://github.com/arein Tomas Rocchihttps://github.com/tomiir bumblefudgehttps://github.com/bumblefudge https://wg-eips.ritovision.com/7679/

Construct UserOperations without being coupled with account-specific logic.

<h2 id="abstract">Abstract</h2> <p>Different <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> smart account implementations encode their signature, nonce, and calldata differently. This makes it difficult for DApps, wallets, and smart account toolings to integrate with smart accounts without integrating with account-specific SDKs, which introduces vendor lock-in and hurts smart account adoption.</p> <p>We propose a standard way for smart account implementations to put their account-specific encoding logic on-chain. It can be achieved by implementing methods that accept the raw signature, nonce, or calldata (along with the context) as an input, and output them properly formatted, so the smart account can consume them while validating and executing the User Operation.</p> <h2 id="motivation">Motivation</h2> <p>At the moment, to build a <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> UserOperation (UserOp for short) for a smart account requires detailed knowledge of how the smart account implementation works, since each implementation is free to encode its nonce, calldata, and signature differently.</p> <p>As a simple example, one account might use an execution function called <code>executeFoo</code>, whereas another account might use an execution function called <code>executeBar</code>. This will result in the <code>calldata</code> being different between the two accounts, even if they are executing the same call.</p> <p>Therefore, someone who wants to send a UserOp for a given smart account needs to:</p> <ul> <li>Figure out which smart account implementation the account is using.</li> <li>Correctly encode signature/nonce/calldata given the smart account implementation, or use an account-specific SDK that knows how to do that.</li> </ul> <p>In practice, this means that most DApps, wallets, and AA toolings today are tied to a specific smart account implementation, resulting in fragmentation and vendor lock-in.</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="userop-builder">UserOp builder</h3> <p>To conform to this standard, a smart account implementation MUST provide a “UserOp builder” contract that implements the <code>IUserOperationBuilder</code> interface, as defined below:</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"> Execution</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> target</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> callData</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"> IUserOperationBuilder</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"> Returns the ERC-4337 EntryPoint that the account implementation</span></span> <span class="giallo-l"><span class="z-comment"> * supports.</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"> entryPoint</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> <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 nonce to use for the UserOp, given the context.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> smartAccount</span><span class="z-comment"> is the address of the UserOp 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"> context</span><span class="z-comment"> is the data required for the UserOp builder to</span></span> <span class="giallo-l"><span class="z-comment"> * properly compute the requested field for the UserOp.</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"> getNonce</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> smartAccount</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"> context</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> <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 calldata for the UserOp, given the context and</span></span> <span class="giallo-l"><span class="z-comment"> * the executions.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> smartAccount</span><span class="z-comment"> is the address of the UserOp 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"> executions</span><span class="z-comment"> are (destination, value, callData) tuples that</span></span> <span class="giallo-l"><span class="z-comment"> * the UserOp wants to execute. It&#39;s an array so the UserOp can</span></span> <span class="giallo-l"><span class="z-comment"> * batch executions.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> context</span><span class="z-comment"> is the data required for the UserOp builder to</span></span> <span class="giallo-l"><span class="z-comment"> * properly compute the requested field for the UserOp. </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"> getCallData</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> smartAccount</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> Execution</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> executions</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"> context</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">bytes</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-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 a correctly encoded signature, given a UserOp that</span></span> <span class="giallo-l"><span class="z-comment"> * has been correctly filled out except for the signature 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"> smartAccount</span><span class="z-comment"> is the address of the UserOp 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"> userOperation</span><span class="z-comment"> is the UserOp. Every field of the UserOp should</span></span> <span class="giallo-l"><span class="z-comment"> * be valid except for the signature field. The &quot;PackedUserOperation&quot;</span></span> <span class="giallo-l"><span class="z-comment"> * struct is as defined in ERC-4337.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> context</span><span class="z-comment"> is the data required for the UserOp builder to</span></span> <span class="giallo-l"><span class="z-comment"> * properly compute the requested field for the UserOp.</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"> formatSignature</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> smartAccount</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> PackedUserOperation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> userOperation</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"> context</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">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> signature</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="using-the-userop-builder">Using the UserOp builder</h3> <p>To build a UserOp using the UserOp builder, the building party SHOULD proceed as follows:</p> <ol> <li>Obtain the address of <code>UserOpBuilder</code> and a <code>context</code> from the account owner. The <code>context</code> is an opaque bytes array from the perspective of the building party. The <code>UserOpBuilder</code> implementation may need the <code>context</code> in order to properly figure out the UserOp fields. See <a href="https://wg-eips.ritovision.com/7679/#rationale">Rationale</a> for more info.</li> <li>Execute a multicall (batched <code>eth_call</code>s) of <code>getNonce</code> and <code>getCallData</code> with the <code>context</code> and executions. The building party will now have obtained the nonce and calldata.</li> <li>Fill out a UserOp with the data obtained previously. Gas values can be set randomly or very low. This userOp will be used to obtain a dummy signature for gas estimations. Sign the hash of userOp. (See <a href="https://wg-eips.ritovision.com/7679/#rationale">Rationale</a> for what a dummy signature is. See <a href="https://wg-eips.ritovision.com/7679/#security-considerations">Security Considerations</a> for the details on dummy signature security).</li> <li>Call (via <code>eth_call</code>) <code>formatSignature</code> with the UserOp and <code>context</code> to obtain a UserOp with a properly formatted dummy signature. This userOp can now be used for gas estimation.</li> <li>In the UserOp, change the existing gas values to those obtained from a proper gas estimation. This UserOp must be valid except for the <code>signature</code> field. Sign the hash of the UserOp and place the signature in the UserOp.signature field.</li> <li>Call (via <code>eth_call</code>) <code>formatSignature</code> with the UserOp and <code>context</code> to obtain a completely valid UserOp. <ol> <li>Note that a UserOp has a lot more fields than <code>nonce</code>, <code>callData</code>, and <code>signature</code>, but how the building party obtains the other fields is outside of the scope of this document, since only these three fields are heavily dependent on the smart account implementation.</li> </ol> </li> </ol> <p>At this point, the building party has a completely valid UserOp that they can then submit to a bundler or do whatever it likes with it.</p> <h3 id="using-the-userop-builder-when-the-account-hasn-t-been-deployed">Using the UserOp builder when the account hasn’t been deployed</h3> <p>To provide the accurate data to the building party, the <code>UserOpBuilder</code> will in most cases have to call the account. If the account has yet to be deployed, which means that the building party is looking to send the very first UserOp for this account, then the building party MAY modify the flow above as follows:</p> <ul> <li>In addition to the <code>UserOpBuilder</code> address and the <code>context</code>, the building party also obtains the <code>factory</code> and <code>factoryData</code> as defined in ERC-4337.</li> <li>When calling one of the view functions on the UserOp builder, the building party may use <code>eth_call</code> to deploy the <code>CounterfactualCall</code> contract, which is going to deploy the account and call <code>UserOpBuilder</code> (see below).</li> <li>When filling out the UserOp, the building party includes <code>factory</code> and <code>factoryData</code>.</li> </ul> <p>The <code>CounterfactualCall</code> contract SHOULD:</p> <ul> <li>Deploy the account using <code>factory</code> and <code>factoryData</code> provided by the building party.</li> <li>Revert if the deployment has not succeeded.</li> <li>If the account has been deployed succesfully, call <code>UserOpBuilder</code> and return the data returned by <code>UserOpBuilder</code> to the building party.</li> </ul> <p>See Reference Implementation section for more details on the <code>CounterfactualCall</code> contract.</p> <h2 id="rationale">Rationale</h2> <h3 id="context">Context</h3> <p>The <code>context</code> is an array of bytes that encodes whatever data the UserOp builder needs in order to correctly determine the nonce, calldata, and signature. Presumably, the <code>context</code> is constructed by the account owner, with the help of a wallet software.</p> <p>Here we outline one possible use of <code>context</code>: delegation. Say the account owner wants to delegate a transaction to be executed by the building party. The account owner could encode a signature of the public key of the building party inside the <code>context</code>. Let’s call this signature from the account owner the <code>authorization</code>.</p> <p>Then, when the building party fills out the UserOp, it would fill the <code>signature</code> field with a signature generated by its own private key. When it calls <code>getSignature</code> on the UserOp builder, the UserOp builder would extract the <code>authorization</code> from the <code>context</code> and concatenates it with the building party’s signature. The smart account would presumably be implemented such that it would recover the building party’s public key from the signature, and check that the public key was in fact signed off by the <code>authorization</code>. If the check succeeds, the smart account would execute the UserOp, thus allowing the building party to execute a UserOp on the user’s behalf.</p> <h3 id="dummy-signature">Dummy signature</h3> <p>The “dummy signature” refers to the signature used in a UserOp sent to a bundler for estimating gas (via <code>eth_estimateUserOperationGas</code>). A dummy signature is needed because, at the time the bundler estimates gas, a valid signature does not exist yet, since the valid signature itself depends on the gas values of the UserOp, creating a circular dependency. To break the circular dependency, a dummy signature is used.</p> <p>However, the dummy signature is not just a fixed value that any smart account can use. The dummy signature must be constructed such that it would cause the UserOp to use about as much gas as a real signature would. Therefore, the dummy signature varies based on the specific validation logic that the smart account uses to validate the UserOp, making it dependent on the smart account implementation.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC is intended to be backwards compatible with all ERC-4337 smart accounts as of EntryPoint 0.7.</p> <p>For smart accounts deployed against EntryPoint 0.6, the <code>IUserOperationBuilder</code> interface needs to be modified such that the <code>PackedUserOperation</code> struct is replaced with the corresponding struct in EntryPoint 0.6.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="counterfactual-call-contract">Counterfactual call contract</h3> <p>The counterfactual call contract is inspired by <a href="https://wg-eips.ritovision.com/6492/">ERC-6492</a>, which devised a mechanism to execute <code>isValidSignature</code> (see <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>) against a pre-deployed (counterfactual) contract.</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"> CounterfactualCall</span><span> {</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> CounterfactualDeployFailed</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> error</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> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> smartAccount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> create2Factory</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 class="z-variable"> factoryData</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> userOpBuilder</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 class="z-variable"> userOpBuilderCalldata</span></span> <span class="giallo-l"><span> )</span><span> {</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-support">address</span><span>(</span><span>smartAccount</span><span>)</span><span>.</span><span>code</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> (</span><span class="z-support">bool</span><span> success</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> ret</span><span>)</span><span class="z-keyword"> =</span><span> create2Factory</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span>factoryData</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>success </span><span class="z-keyword">||</span><span class="z-support"> address</span><span>(</span><span>smartAccount</span><span>)</span><span>.</span><span>code</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> CounterfactualDeployFailed</span><span>(</span><span>ret</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-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> success </span><span class="z-keyword">:=</span><span class="z-entity z-name"> call</span><span>(</span><span class="z-entity z-name">gas</span><span>(</span><span>)</span><span>,</span><span> userOpBuilder</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>userOpBuilderCalldata</span><span>,</span><span class="z-constant"> 0x20</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>userOpBuilderCalldata</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-storage z-type"> let</span><span> ptr </span><span class="z-keyword">:=</span><span class="z-entity z-name"> mload</span><span>(</span><span class="z-constant">0x40</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> returndatacopy</span><span>(</span><span>ptr</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 class="z-keyword"> if</span><span class="z-entity z-name"> iszero</span><span>(</span><span>success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span>ptr</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 class="z-keyword"> return</span><span>(</span><span>ptr</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> <p>Here’s an example of calling this contract using the ethers and viem libraries:</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"> ethers</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> nonce</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">call</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> data</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">concat</span><span>(</span><span>[</span></span> <span class="giallo-l"><span class="z-variable z-other"> counterfactualCallBytecode</span><span>,</span></span> <span class="giallo-l"><span> (</span></span> <span class="giallo-l"><span class="z-keyword"> new</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">AbiCoder</span><span>(</span><span>)</span><span>)</span><span>.</span><span class="z-entity z-name">encode</span><span>(</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 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 class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">bytes</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">address</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">bytes</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 class="z-variable z-other">smartAccount</span><span>,</span><span class="z-variable z-other"> userOpBuilder</span><span>,</span><span class="z-variable z-other"> getNonceCallData</span><span>,</span><span class="z-variable z-other"> factory</span><span>,</span><span class="z-variable z-other"> factoryData</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><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"> viem</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> nonce</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> client</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> data</span><span>:</span><span class="z-entity z-name"> encodeDeployData</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> abi</span><span>:</span><span class="z-entity z-name"> parseAbi</span><span>(</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">constructor(address, address, bytes, address, bytes)</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> args</span><span>:</span><span> [</span><span class="z-variable z-other">smartAccount</span><span>,</span><span class="z-variable z-other"> userOpBuilder</span><span>,</span><span class="z-variable z-other"> getNonceCalldata</span><span>,</span><span class="z-variable z-other"> factory</span><span>,</span><span class="z-variable z-other"> factoryData</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> bytecode</span><span>:</span><span class="z-variable z-other"> counterfactualCallBytecode</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>)</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <h3 id="dummy-signature-security">Dummy Signature security</h3> <p>Since the properly formatted dummy signature is going to be publicly disclosed, in theory it can be intercepted and used by the man in the middle. Risks and potential harm of this is very low though as the dummy signature will be effectively unusable after the final UserOp is submitted (as both UserOps use the same nonce). However, to mitigate even this small issue, it is recommended that the UserOp which hash is going to be signed to obtain an un-foirmatted dummy signature (step 3 above) is filled with very low gas values.</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-04-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Lukas Rosariohttps://github.com/lukasrosario Dror Tiroshhttps://github.com/drortirosh Wilson Cusackhttps://github.com/wilsoncusack Kristof Gazsohttps://github.com/kristofgazso Hazim Jumalihttps://github.com/hazim-j https://wg-eips.ritovision.com/7677/

A way for apps to communicate with smart wallets about paymaster web services

<h2 id="abstract">Abstract</h2> <p>With <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a>, apps can communicate with wallets about advanced features via capabilities. This proposal defines a capability that allows apps to request that <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> wallets communicate with a specified paymaster web service. To support this, we also define a standardized API for paymaster web services.</p> <h2 id="motivation">Motivation</h2> <p>App developers want to start sponsoring their users' transactions using paymasters. Paymasters are commonly used via web services. However, there is currently no way for apps to tell wallets to communicate with a specific paymaster web service. Similarly, there is no standard for how wallets should communicate with these services. We need both a way for apps to tell wallets to communicate with a specific paymaster web service and a communication standard for wallets to do so.</p> <h2 id="specification">Specification</h2> <p>One new <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> wallet capability is defined. We also define a standard interface for paymaster web services as a prerequisite.</p> <h3 id="paymaster-web-service-interface">Paymaster Web Service Interface</h3> <p>We define two JSON-RPC methods to be implemented by paymaster web services.</p> <h4 id="pm-getpaymasterstubdata"><code>pm_getPaymasterStubData</code></h4> <p>Returns stub values to be used in paymaster-related fields of an unsigned user operation for gas estimation. Accepts an unsigned user operation, entrypoint address, chain id, and a context object. Paymaster service providers can define fields that app developers should use in the context object.</p> <p>This method MAY return paymaster-specific gas values if applicable to the provided EntryPoint version. For example, if provided with EntryPoint v0.7, this method MAY return <code>paymasterVerificationGasLimit</code>. Furthermore, for EntryPoint v0.7, this method MUST return a value for <code>paymasterPostOpGasLimit</code>. This is because it is the paymaster that pays the postOpGasLimit, so it cannot trust the wallet to estimate this amount.</p> <p>The wallet SHOULD use these provided gas values when submitting the <code>UserOperation</code> to a bundler for gas estimation.</p> <p>This method MAY also return a <code>sponsor</code> object with a <code>name</code> field and an optional <code>icon</code> field. The <code>name</code> field is the name of the party sponsoring the transaction, and the <code>icon</code> field is a URI pointing to an image. Wallet developers MAY choose to display sponsor information to users. The <code>icon</code> string MUST be a data URI as defined in [RFC-2397]. The image SHOULD be a square with 96x96px minimum resolution. The image format is RECOMMENDED to be either lossless or vector based such as PNG, WebP or SVG to make the image easy to render on the wallet. Since SVG images can execute Javascript, wallets MUST render SVG images using the <code>&lt;img&gt;</code> tag to ensure no untrusted Javascript execution can occur.</p> <p>There are cases where a call to just <code>pm_getPaymasterStubData</code> is sufficient to provide valid paymaster-related user operation fields, e.g. when the <code>paymasterData</code> does not contain a signature. In such cases, the second RPC call to <code>pm_getPaymasterData</code> (defined below) MAY be skipped, by returning <code>isFinal: true</code> by this RPC call.</p> <p>Paymaster web services SHOULD do validations on incoming user operations during <code>pm_getPaymasterStubData</code> execution and reject the request at this stage if it would not sponsor the operation.</p> <h5 id="pm-getpaymasterstubdata-rpc-specification"><code>pm_getPaymasterStubData</code> RPC Specification</h5> <p>Note that the user operation parameter does not include a signature, as the user signs after all other fields are populated.</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> [userOp, entryPoint, chainId, context]</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> GetPaymasterStubDataParams</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Below is specific to Entrypoint v0.6 but this API can be used with other entrypoint versions too</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable"> sender</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> <span class="giallo-l"><span class="z-variable"> nonce</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> <span class="giallo-l"><span class="z-variable"> initCode</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> <span class="giallo-l"><span class="z-variable"> callData</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> <span class="giallo-l"><span class="z-variable"> callGasLimit</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> <span class="giallo-l"><span class="z-variable"> verificationGasLimit</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> <span class="giallo-l"><span class="z-variable"> preVerificationGas</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> <span class="giallo-l"><span class="z-variable"> maxFeePerGas</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> <span class="giallo-l"><span class="z-variable"> maxPriorityFeePerGas</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> <span class="giallo-l"><span> }</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> userOp</span></span> <span class="giallo-l"><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-punctuation z-definition z-comment"> //</span><span class="z-comment"> EntryPoint</span></span> <span class="giallo-l"><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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Chain ID</span></span> <span class="giallo-l"><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Context</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"> GetPaymasterStubDataResult</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> sponsor</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span> {</span><span class="z-variable"> name</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-variable"> icon</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Sponsor info</span></span> <span class="giallo-l"><span class="z-variable"> paymaster</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Paymaster address (entrypoint v0.7)</span></span> <span class="giallo-l"><span class="z-variable"> paymasterData</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Paymaster data (entrypoint v0.7)</span></span> <span class="giallo-l"><span class="z-variable"> paymasterVerificationGasLimit</span><span class="z-keyword">?</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Paymaster validation gas (entrypoint v0.7)</span></span> <span class="giallo-l"><span class="z-variable"> paymasterPostOpGasLimit</span><span class="z-keyword">?</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Paymaster post-op gas (entrypoint v0.7)</span></span> <span class="giallo-l"><span class="z-variable"> paymasterAndData</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Paymaster and data (entrypoint v0.6)</span></span> <span class="giallo-l"><span class="z-variable"> isFinal</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Indicates that the caller does not need to call pm_getPaymasterData</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h6 id="pm-getpaymasterstubdata-example-parameters"><code>pm_getPaymasterStubData</code> Example Parameters</h6> <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">sender</span><span class="z-support">&quot;</span><span>:</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></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">0x...</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">initCode</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">callData</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">callGasLimit</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">verificationGasLimit</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">preVerificationGas</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxFeePerGas</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxPriorityFeePerGas</span><span class="z-support">&quot;</span><span>:</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>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789</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">0x2105</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Illustrative context field. These should be defined by service providers.</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">policyId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">962b252c-a726-4a37-8d86-333ce0a07299</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><h6 id="pm-getpaymasterstubdata-example-return-value"><code>pm_getPaymasterStubData</code> Example Return Value</h6> <p>Paymaster services MUST detect which entrypoint version the account is using and return the correct fields.</p> <p>For example, if using entrypoint v0.6:</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">sponsor</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">My App</span><span class="z-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">https://...</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">paymasterAndData</span><span class="z-support">&quot;</span><span>:</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> <p>If using entrypoint v0.7:</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">sponsor</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">My App</span><span class="z-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">https://...</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">paymaster</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">paymasterData</span><span class="z-support">&quot;</span><span>:</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> <p>If using entrypoint v0.7, with paymaster gas estimates:</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">sponsor</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">My App</span><span class="z-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">https://...</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">paymaster</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">paymasterData</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">paymasterVerificationGasLimit</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">paymasterPostOpGasLimit</span><span class="z-support">&quot;</span><span>:</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> <p>Indicating that the caller does not need to make a <code>pm_getPaymasterData</code> RPC call:</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">sponsor</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">My App</span><span class="z-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">https://...</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">paymaster</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">paymasterData</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">isFinal</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="pm-getpaymasterdata"><code>pm_getPaymasterData</code></h4> <p>Returns values to be used in paymaster-related fields of a signed user operation. These are not stub values and will be used during user operation submission to a bundler. Similar to <code>pm_getPaymasterStubData</code>, accepts an unsigned user operation, entrypoint address, chain id, and a context object.</p> <h5 id="pm-getpaymasterdata-rpc-specification"><code>pm_getPaymasterData</code> RPC Specification</h5> <p>Note that the user operation parameter does not include a signature, as the user signs after all other fields are populated.</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> [userOp, entryPoint, chainId, context]</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> GetPaymasterDataParams</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Below is specific to Entrypoint v0.6 but this API can be used with other entrypoint versions too</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable"> sender</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> <span class="giallo-l"><span class="z-variable"> nonce</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> <span class="giallo-l"><span class="z-variable"> initCode</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> <span class="giallo-l"><span class="z-variable"> callData</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> <span class="giallo-l"><span class="z-variable"> callGasLimit</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> <span class="giallo-l"><span class="z-variable"> verificationGasLimit</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> <span class="giallo-l"><span class="z-variable"> preVerificationGas</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> <span class="giallo-l"><span class="z-variable"> maxFeePerGas</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> <span class="giallo-l"><span class="z-variable"> maxPriorityFeePerGas</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> <span class="giallo-l"><span> }</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> userOp</span></span> <span class="giallo-l"><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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Entrypoint</span></span> <span class="giallo-l"><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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Chain ID</span></span> <span class="giallo-l"><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Context</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"> GetPaymasterDataResult</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> paymaster</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Paymaster address (entrypoint v0.7)</span></span> <span class="giallo-l"><span class="z-variable"> paymasterData</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Paymaster data (entrypoint v0.7)</span></span> <span class="giallo-l"><span class="z-variable"> paymasterAndData</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Paymaster and data (entrypoint v0.6)</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h6 id="pm-getpaymasterdata-example-parameters"><code>pm_getPaymasterData</code> Example Parameters</h6> <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">sender</span><span class="z-support">&quot;</span><span>:</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></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">0x...</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">initCode</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">callData</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">callGasLimit</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">verificationGasLimit</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">preVerificationGas</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxFeePerGas</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxPriorityFeePerGas</span><span class="z-support">&quot;</span><span>:</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>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789</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">0x2105</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Illustrative context field. These should be defined by service providers.</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">policyId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">962b252c-a726-4a37-8d86-333ce0a07299</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><h6 id="pm-getpaymasterdata-example-return-value"><code>pm_getPaymasterData</code> Example Return Value</h6> <p>Paymaster services MUST detect which entrypoint version the account is using and return the correct fields.</p> <p>For example, if using entrypoint v0.6:</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">paymasterAndData</span><span class="z-support">&quot;</span><span>:</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> <p>If using entrypoint v0.7:</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">paymaster</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">paymasterData</span><span class="z-support">&quot;</span><span>:</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><h3 id="paymasterservice-capability"><code>paymasterService</code> Capability</h3> <p>The <code>paymasterService</code> capability is implemented by both apps and wallets.</p> <h4 id="app-implementation">App Implementation</h4> <p>Apps need to give wallets a paymaster service URL they can make the above RPC calls to. They can do this using the <code>paymasterService</code> capability as part of an <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> <code>wallet_sendCalls</code> call.</p> <h5 id="wallet-sendcalls-paymaster-capability-specification"><code>wallet_sendCalls</code> Paymaster Capability Specification</h5> <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"> PaymasterCapabilityParams</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> url</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> context</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h6 id="wallet-sendcalls-example-parameters"><code>wallet_sendCalls</code> Example Parameters</h6> <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">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">from</span><span class="z-support">&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-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">0xd46e8dd67c5d32be8058bb8eb970870f07244567</span><span class="z-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">0x9184e72a</span><span class="z-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">0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675</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">to</span><span class="z-support">&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-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">0x182183</span><span class="z-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">0xfbadbaf01</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">paymasterService</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">url</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://...</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">context</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">policyId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">962b252c-a726-4a37-8d86-333ce0a07299</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> <p>The wallet will then make the above paymaster RPC calls to the URL specified in the <code>paymasterService</code> capability field.</p> <h4 id="wallet-implementation">Wallet Implementation</h4> <p>To conform to this specification, smart wallets that wish to leverage app-sponsored transactions:</p> <ol> <li>MUST indicate to apps that they can communicate with paymaster web services via their response to an <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> <code>wallet_getCapabilities</code> call.</li> <li>SHOULD make calls to and use the values returned by the paymaster service specified in the capabilities field of an <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> <code>wallet_sendCalls</code> call. An example of an exception is a wallet that allows users to select a paymaster provided by the wallet. Since there might be cases in which the provided paymaster is ultimately not used—either due to service failure or due to a user selecting a different, wallet-provided paymaster—applications MUST NOT assume that the paymaster it provides to a wallet is the entity that pays for transaction fees.</li> </ol> <h5 id="wallet-getcapabilities-response-specification"><code>wallet_getCapabilities</code> Response Specification</h5> <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"> PaymasterServiceCapability</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> supported</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><h6 id="wallet-getcapabilities-example-response"><code>wallet_getCapabilities</code> Example Response</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">0x2105</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">paymasterService</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 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">0x14A34</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">paymasterService</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 class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Below is a diagram illustrating the full <code>wallet_sendCalls</code> flow, including how a wallet might implement the interaction.</p> <p><img src="https://wg-eips.ritovision.com/7677/./assets/0.svg" alt="flow" /></p> <h2 id="rationale">Rationale</h2> <h3 id="gas-estimation">Gas Estimation</h3> <p>The current loose standard for paymaster services is to implement <code>pm_sponsorUserOperation</code>. This method returns values for paymaster-related user operation fields and updated gas values. The problem with this method is that paymaster service providers have different ways of estimating gas, which results in different estimated gas values. Sometimes these estimates can be insufficient. As a result we believe it’s better to leave gas estimation up to the wallet, as the wallet has more context on how user operations will get submitted (e.g. which bundler they will get submitted to). Then wallets can ask paymaster services to sponsor given the estimates defined by the wallet.</p> <p>The above reason is also why we specify that the <code>pm_getPaymasterStubData</code> method MAY also return paymaster-specific gas estimates. I.e., bundlers are prone to insufficiently estimating the paymaster-specific gas values, and the paymaster servies themselves are ultimately better equipped to provide them.</p> <h3 id="chain-id-parameter">Chain ID Parameter</h3> <p>Currently, paymaster service providers typically provide developers with a URL per chain. That is, paymaster service URLs are not typically multichain. So why do we need a chain ID parameter? We recognize that we must specify some constraint so that wallets can communicate with paymaster services about which chain their requests are for. As we see it, there are two options:</p> <ol> <li>Formalize the current loose standard and require that paymaster service URLs are 1:1 with chains.</li> <li>Require a chain ID parameter as part of paymaster service requests.</li> </ol> <p>We feel that option (2) is the better abstraction here. This allows service providers to offer multichain URLs if they wish at essentially no downside to providers who offer a URL per chain. Providers who offer a URL per chain would just need to accept an additional parameter that they can ignore. When an app developer who uses a URL-per-chain provider wants to submit a request to a different chain, they can just swap out the URL accordingly.</p> <h3 id="challenges-with-stub-data">Challenges With Stub Data</h3> <p>Enabling a workflow with greater flexibility in gas estimations will nonetheless come with some known challenges that paymaster services must be aware of in order to ensure reliable gas estimates are generated during the process.</p> <h4 id="preverificationgas"><code>preVerificationGas</code></h4> <p>The <code>preVerificationGas</code> value is largely influenced by the size of the user operation and it's ratio of zero to non-zero bytes. This can cause a scenario where <code>pm_getPaymasterStubData</code> returns values that results in upstream gas estimations to derive a lower <code>preVerificationGas</code> compared to what <code>pm_getPaymasterData</code> would require. If this occurs then bundlers will return an insufficient <code>preVerificationGas</code> error during <code>eth_sendUserOperation</code>.</p> <p>To avoid this scenario, a paymaster service MUST return stub data that:</p> <ol> <li>Is of the same length as the final data.</li> <li>Has an amount of zero bytes (<code>0x00</code>) that is less than or equal to the final data.</li> </ol> <h4 id="consistent-code-paths">Consistent Code Paths</h4> <p>In the naive case, a stub value of repeating non-zero bytes (e.g. <code>0x01</code>) that is of the same length as the final value will generate a usable <code>preVerificationGas</code>. Although this would immediately result in a gas estimation error given that the simulation will likely revert due to an invalid paymaster data.</p> <p>In a more realistic case, a valid stub can result in a successful simulation but still return insufficient gas limits. This can occur if the stub data causes <code>validatePaymasterUserOp</code> or <code>postOp</code> functions to simulate a different code path compared to the final value. For example, if the simulated code was to return early, the estimated gas limits would be less than expected which would cause upstream <code>out of gas</code> errors once a user operation is submitted to the bundler.</p> <p>Therefore, a paymaster service MUST also return a stub that can result in a simulation executing the same code path compared to what is expected of the final user operation.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The URLs paymaster service providers give to app developers commonly have API keys in them. App developers might not want to pass these API keys along to wallets. To remedy this, we recommend that app developers provide a URL to their app's backend, which can then proxy calls to paymaster services. Below is a modified diagram of what this flow might look like.</p> <p><img src="https://wg-eips.ritovision.com/7677/./assets/1.svg" alt="flowWithAPI" /></p> <p>This flow would allow developers to keep their paymaster service API keys secret. Developers might also want to do additional simulation / validation in their backends to ensure they are sponsoring a transaction they want to sponsor.</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-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Xenia Shapehttps://github.com/byshape Mikhail Melnikhttps://github.com/ZumZoom Hadrien Crouboishttps://github.com/Amxx https://wg-eips.ritovision.com/7674/

Ephemeral ERC-20 approvals lasting a single transaction

<h2 id="abstract">Abstract</h2> <p>This specification defines the minimum interface required to temporarily approve <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens for spending within the same transaction.</p> <h2 id="motivation">Motivation</h2> <p>User are often required to set a token approval that will only be used once. It is common to leave unexpected approvals after these interactions. <a href="https://wg-eips.ritovision.com/1153/">EIP-1153</a> introduces <code>TSTORE</code>, which can be used to efficiently handle temporarily allowances.</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>Compliant contracts MUST implement 1 new function in addition to <a href="https://wg-eips.ritovision.com/20/">ERC-20</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"> temporaryApprove</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 class="z-variable"> success</span><span>)</span></span></code></pre> <p>A call to <code>temporaryApprove(spender, value)</code> allows <code>spender</code> to withdraw within the same transaction on behalf of <code>msg.sender</code> multiple times, such that the total withdrawn is less than or equal to the <code>value</code> amount. This temporary allowance is to be considered in addition to the normal (persistent) <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> allowance. The total value that spender is able to spend during the transaction is thus capped by the sum of the temporary and the normal (persistent) allowances. While it SHOULD be possible for a <code>transferFrom</code> operation to consume both types of allowance, the consumption of the temporary allowance SHOULD take priority over the consumption of the persistent allowance. Therefore, if the temporary allowance is sufficient for executing a <code>transferFrom</code> operation, the persistent allowance SHOULD not be loaded/updated from the storage. Consumption of persistent allowance, which implies storage accesses, SHOULD be performed only if the temporary allowance is not sufficient for the operation being executed.</p> <p>Each temporary allowance MUST persist until the end of the transaction that created it (unless overwritten by another call to <code>temporaryApprove</code> or consumed by a call to <code>transferFrom</code>). Each temporary allowance MUST be cleared at the end of the transaction that created it. See <a href="https://wg-eips.ritovision.com/7674/#using-transient-storage">Using Transient Storage</a> for an example.</p> <p>Compliant contracts MUST add a temporary allowance to the permanent one when returning the allowed amount to spend in the <code>allowance</code> function. In case the sum of the temporary and permanent allowance overflow, <code>type(uint256).max</code> MUST be returned.</p> <h2 id="rationale">Rationale</h2> <p>It was decided to make minimal interface extension to allow easier integration of a compliant contract into the existing infrastructure. This affects the backward compatibility of the <code>allowance</code> function. However, the required changes to the <code>transferFrom</code> function implementation satisfy the requirement to explicitly authorize the spender to transfer tokens.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>All functionality of the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard is backward compatible except for the <code>allowance</code> function.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="using-transient-storage">Using Transient Storage</h3> <p>The storage for the temporary allowances must be different to that of the regular allowance. Compliant contracts may use the transient storage <a href="https://wg-eips.ritovision.com/1153/">EIP-1153</a> to keep the temporary allowance. For each <code>owner</code> and <code>spender</code>, the slot should be uniquely selected to avoid slot collision. Each slot index should be derived from the base slot index for temporary allowances, <code>owner</code> and <code>spender</code> addresses. Slot may be derived as <code>keccak256(spender . keccak256(owner . p))</code> where <code>.</code> is concatenation and <code>p</code> is <code>keccak256</code> from the string uniquely defining temporary allowances in the namespace of the implementing contract.</p> <h3 id="events">Events</h3> <p>Even though no event is required when setting a temporary allowance, compliant contracts may emit <code>TransientApproval(address indexed owner, address indexed spender, uint256 value)</code> event.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The method of deriving slot identifiers to store temporary allowances must avoid collision with other slots in the same space (e.g. transient 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> 2024-04-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Duc Tho Tranhttps://github.com/ducthotran2010 https://wg-eips.ritovision.com/7695/

Introduces contexts and ownership delegation for ERC-721 tokens, expanding dApps and financial use cases without transferring ownership

<h2 id="abstract">Abstract</h2> <p>This standard is an extension for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, designed to specify users for various contexts with a locking feature and allow temporary ownership delegation without changing the original owner.</p> <p>This EIP preserves the benefits and rights of the owner while expanding the utility of NFTs across various dApps by adding the concepts of Ownership Delegation and Contexts, which define specific roles: Controller and User, who can use the NFT within defined contexts.</p> <h2 id="motivation">Motivation</h2> <p>For standard <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> NFTs, there are several use cases in financial applications, including:</p> <ul> <li>Staking NFTs to earn rewards.</li> <li>Mortgaging an NFT to generate income.</li> <li>Granting users for different purposes like rental and token delegation—where someone pays to use tokens and pays another party to use the tokens.</li> </ul> <p>Traditionally, these applications require ownership transfers to lock the NFT in contracts. However, other decentralized applications (dApps) recognize token ownership as proof that the token owner is entitled to benefits within their reward systems, such as airdrops or tiered rewards. If token owners have their tokens locked in contracts, they are not eligible to receive benefits from holding these tokens, or the reward systems have to support as many contracts as possible to help these owners.</p> <p>This is because there is only an Owner role indicating the ownership rights, developing on top of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> has often posed challenges. This proposal aims to solve these challenges by contextualizing the use case to be handled by controllers and distinguishing ownership rights from other roles at the standard level through an ownership delegation mechanism. Standardizing these measures, dApp developers can more easily construct infrastructure and protocols on top of this standard.</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="definitions">Definitions</h3> <p>This specification encompasses the following components:</p> <p><strong>Token Context</strong> provides a specified use case of a token. It serves as the association relationship between Tokens and Contexts. Within each unique token context, there exists an allocated user who is authorized to utilize the token within that context. In a specified context, there are two distinct roles:</p> <ul> <li><strong>Controller</strong>: This role possesses the authority to control the context.</li> <li><strong>User</strong>: This role signifies the primary token user within the given context.</li> </ul> <p><strong>Ownership Rights</strong> of a token are defined to be able to:</p> <ul> <li>Transfer that token to a new owner.</li> <li>Add token context(s): attaching that token to/from one or many contexts.</li> <li>Remove token context(s): detaching that token to/from one or many contexts.</li> </ul> <p><strong>Ownership Delegation</strong> involves distinguishing between owner and ownership rights by delegating ownership to other accounts for a specific duration. During this period, owners temporarily cede ownership rights until the delegation expires.</p> <h3 id="roles">Roles</h3> <table><thead><tr><th>Roles</th><th>Explanation / Permission</th><th>Quantity per Token</th></tr></thead><tbody> <tr><td>Owner</td><td>• Has <strong>Ownership Rights</strong> by default<br>• Delegates an account to hold <strong>Ownership Rights</strong> in a duration</td><td>$1$</td></tr> <tr><td>Ownership Delegatee</td><td>• Has <strong>Ownership Rights</strong> in a delegation duration<br>• Renounces before delegation expires</td><td>$1$</td></tr> <tr><td>Ownership Manager</td><td>• Is one who holds <strong>Ownership Rights</strong><br>• If not delegated yet, it is referenced to <strong>Owner</strong>, otherwise it is referenced to <strong>Ownership Delegatee</strong></td><td>$1$</td></tr> <tr><td><strong>Context Roles</strong></td><td></td><td>$n$</td></tr> <tr><td>Controller</td><td>• Transfers controller<br>• Sets context user<br>• (Un)locks token transfer</td><td>$1$ per context</td></tr> <tr><td>User</td><td>• Authorized to use token in its context</td><td>$1$ per context</td></tr> </tbody></table> <h3 id="interface">Interface</h3> <p><strong>Smart contracts implementing this standard MUST implement all the functions in the <code>IERC7695</code> interface.</strong></p> <p>Smart contracts implementing this standard MUST implement the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> <code>supportsInterface</code> function and MUST return the constant value <code>true</code> if <code>0x486b6fba</code> is passed through the <code>interfaceID</code> argument.</p> <pre class="giallo z-code"><code data-lang="solidity"><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 0x486b6fba.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7695</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC721, IERC165 </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 a context is updated by any mechanism.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ContextUpdated</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ctxHash</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> controller</span><span>, </span><span class="z-support">uint64</span><span class="z-variable"> detachingDuration</span><span>)</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 token is attached to a certain context by any mechanism.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ContextAttached</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ctxHash</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 class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a token is requested to detach from a certain context by any mechanism.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ContextDetachmentRequested</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ctxHash</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 class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a token is detached from a certain context by any mechanism.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ContextDetached</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ctxHash</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 class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a user is assigned to a certain context by any mechanism.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ContextUserAssigned</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ctxHash</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>;</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 (un)locked in a certain context by any mechanism.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ContextLockUpdated</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ctxHash</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">bool</span><span class="z-variable"> locked</span><span>)</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 the ownership delegation is started by any mechanism.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> OwnershipDelegationStarted</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"> delegatee</span><span>, </span><span class="z-support">uint64</span><span class="z-variable"> until</span><span>)</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 the ownership delegation is accepted by any mechanism.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> OwnershipDelegationAccepted</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"> delegatee</span><span>, </span><span class="z-support">uint64</span><span class="z-variable"> until</span><span>)</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 the ownership delegation is stopped by any mechanism.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> OwnershipDelegationStopped</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"> delegatee</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 longest duration the detaching can happen.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> maxDetachingDuration</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">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"> Gets controller address and detachment duration of a context.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST revert if the context is not existent.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> ctxHash</span><span class="z-comment"> A hash of context to query the controller.</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"> controller</span><span class="z-comment"> The address of the context controller.</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"> detachingDuration</span><span class="z-comment"> The duration must be waited for detachment in second(s).</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getContext</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> ctxHash</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"> controller</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> detachingDuration</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"> Creates a new context.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST revert if the context is already existent.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST revert if the controller address is zero address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST revert if the detaching duration is larger than max detaching duration.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST emit the event {ContextUpdated} to reflect context created and controller 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"> controller</span><span class="z-comment"> The address that controls the created context.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> detachingDuration</span><span class="z-comment"> The duration must be waited for detachment in second(s).</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> ctxMsg</span><span class="z-comment"> The message of new context to be used for hashing.</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"> ctxHash</span><span class="z-comment"> Hash of the created context.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createContext</span><span>(</span><span class="z-support">address</span><span class="z-variable"> controller</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> detachingDuration</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> ctxMsg</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">bytes32</span><span class="z-variable"> ctxHash</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"> Updates an existing context.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST revert if method caller is not the current controller.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST revert if the context is non-existent.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST revert if the new controller address is zero address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST revert if the detaching duration is larger than max detaching duration.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST emit the event {ContextUpdated} on success.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> ctxHash</span><span class="z-comment"> Hash of the context to 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"> newController</span><span class="z-comment"> The address of new controller.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> newDetachingDuration</span><span class="z-comment"> The new duration must be waited for detachment in second(s).</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateContext</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> ctxHash</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> newController</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> newDetachingDuration</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 if a token is attached to a certain context.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> ctxHash</span><span class="z-comment"> Hash of a context.</span></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 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"> True</span><span class="z-comment"> if the token is attached to the context, false if not.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isAttachedWithContext</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> ctxHash</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"> Attaches a token with a certain context.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See &quot;attachContext rules&quot; in &quot;Token (Un)lock Rules&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"> ctxHash</span><span class="z-comment"> Hash of a context.</span></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 be attached.</span></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, MUST be sent unaltered in call to the {IERC7695ContextCallback} hook(s) on controller.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> attachContext</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> ctxHash</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</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>;</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 detach a token from a certain context.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See &quot;requestDetachContext rules&quot; in &quot;Token (Un)lock Rules&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"> ctxHash</span><span class="z-comment"> Hash of a context.</span></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 be detached.</span></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, MUST be sent unaltered in call to the {IERC7695ContextCallback} hook(s) on controller.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> requestDetachContext</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> ctxHash</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</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>;</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"> Executes context detachment.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See &quot;execDetachContext rules&quot; in &quot;Token (Un)lock Rules&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"> ctxHash</span><span class="z-comment"> Hash of a context.</span></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 be detached.</span></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, MUST be sent unaltered in call to the {IERC7695ContextCallback} hook(s) on controller.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> execDetachContext</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> ctxHash</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</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>;</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"> Finds the context user 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"> ctxHash</span><span class="z-comment"> Hash of a context.</span></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 be detached.</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"> Address of the context user.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getContextUser</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> ctxHash</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"> user</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"> Updates the context user of 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"> MUST revert if the method caller is not context controller.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST revert if the context is non-existent.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST revert if the token is not attached to the context.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST emit the event {ContextUserAssigned} on success.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> ctxHash</span><span class="z-comment"> Hash of a context.</span></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 be 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"> user</span><span class="z-comment"> Address of the new user.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setContextUser</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> ctxHash</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-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 if the lock a token is locked in a certain context.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> ctxHash</span><span class="z-comment"> Hash of a context.</span></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 be 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"> True</span><span class="z-comment"> if the token context is locked, false if not.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isTokenContextLocked</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> ctxHash</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"> (Un)locks a token in a certain context.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See &quot;setContextLock rules&quot; in &quot;Token (Un)lock Rules&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"> ctxHash</span><span class="z-comment"> Hash of a context.</span></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 be 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"> lock</span><span class="z-comment"> New status to be (un)locked.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setContextLock</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> ctxHash</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> lock</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"> Finds the ownership manager of a specified 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"> The NFT to be 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"> manager</span><span class="z-comment"> Address of delegatee.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getOwnershipManager</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"> manager</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"> Finds the ownership delegatee of 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"> MUST revert if there is no (or an expired) ownership delegation.</span></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 be 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"> delegatee</span><span class="z-comment"> Address of delegatee.</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"> until</span><span class="z-comment"> The delegation expiry time.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getOwnershipDelegatee</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"> delegatee</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> until</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"> Finds the pending ownership delegatee of 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"> MUST revert if there is no (or an expired) pending ownership delegation.</span></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 be 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"> delegatee</span><span class="z-comment"> Address of pending delegatee.</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"> until</span><span class="z-comment"> The delegation expiry time in the future.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> pendingOwnershipDelegatee</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"> delegatee</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> until</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"> Starts ownership delegation and retains ownership until a specific timestamp.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Replaces the pending delegation if any.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> See &quot;startDelegateOwnership rules&quot; in &quot;Ownership Delegation Rules&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"> tokenId</span><span class="z-comment"> The NFT to be delegated.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> delegatee</span><span class="z-comment"> Address of new delegatee.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> until</span><span class="z-comment"> The delegation expiry time.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> startDelegateOwnership</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"> delegatee</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> until</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"> Accepts ownership delegation request.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See &quot;acceptOwnershipDelegation rules&quot; in &quot;Ownership Delegation Rules&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"> tokenId</span><span class="z-comment"> The NFT to be accepted.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptOwnershipDelegation</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Stops the current ownership delegation.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See &quot;stopOwnershipDelegation rules&quot; in &quot;Ownership Delegation Rules&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"> tokenId</span><span class="z-comment"> The NFT to be stopped.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> stopOwnershipDelegation</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> <p><strong>Enumerable extension</strong></p> <p>The enumeration extension is OPTIONAL for this standard. This allows your contract to publish its full list of contexts and make them discoverable. When calling the <code>supportsInterface</code> function MUST return the constant value <code>true</code> if <code>0xcebf44b7</code> is passed through the <code>interfaceID</code> argument.</p> <pre class="giallo z-code"><code data-lang="solidity"><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 0xcebf44b7.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7695Enumerable</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC165 </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"> Returns a created context in this contract at `index`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> An index must be a value between 0 and {getContextCount}, non-inclusive.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-keyword"> Note</span><span class="z-comment">: When using {getContext} and {getContextCount}, make sure you perform all queries on the same block.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getContext</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">bytes32</span><span class="z-variable"> ctxHash</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 the number of contexts created in the contract.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getContextCount</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"> @dev</span><span class="z-comment"> Returns a context attached to a token at `index`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> An index must be a value between 0 and {getAttachedContextCount}, non-inclusive.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-keyword"> Note</span><span class="z-comment">: When using {getAttachedContext} and {getAttachedContextCount}, make sure you perform all queries on the same block.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAttachedContext</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"> 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">bytes32</span><span class="z-variable"> ctxHash</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 the number of contexts attached to the token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAttachedContextCount</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><strong>Controller Interface</strong></p> <p>The controller is RECOMMENDED to be a contract and including callback methods to allow callbacks in cases where there are any attachment or detachment requests. When calling the <code>supportsInterface</code> function MUST return the constant value <code>true</code> if <code>0xad0491f1</code> is passed through the <code>interfaceID</code> argument.</p> <pre class="giallo z-code"><code data-lang="solidity"><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 0xad0491f1.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7695ContextCallback</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC165 </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 method is called once the token is attached by any mechanism.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This function MAY throw to revert and reject the attachment.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> ctxHash</span><span class="z-comment"> The hash of context invoked this call.</span></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"> NFT identifier which is being attached.</span></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 which called {attachContext} function.</span></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"> function</span><span class="z-entity z-name"> onAttached</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> ctxHash</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"> operator</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>;</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 method is called once the token detachment is requested by any mechanism.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> ctxHash</span><span class="z-comment"> The hash of context invoked this call.</span></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"> NFT identifier which is being requested for detachment.</span></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 which called {requestDetachContext} function.</span></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"> function</span><span class="z-entity z-name"> onDetachRequested</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> ctxHash</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"> operator</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>;</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 method is called once a token context is detached by any mechanism.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> ctxHash</span><span class="z-comment"> The hash of context invoked this call.</span></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"> NFT identifier which is being detached.</span></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 context user which is being detached.</span></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 which called {execDetachContext} function.</span></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"> function</span><span class="z-entity z-name"> onExecDetachContext</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> ctxHash</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"> address</span><span class="z-variable"> operator</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>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="ownership-delegation-rules">Ownership Delegation Rules</h3> <p><strong>startDelegateOwnership rules</strong></p> <ul> <li>MUST revert unless there is no delegation.</li> <li>MUST revert unless the method caller is the owner, an authorized operator of owner, or the approved address for this NFT.</li> <li>MUST revert unless the expiry time is in the future.</li> <li>MUST revert if the delegatee address is the owner or zero address.</li> <li>MUST revert if the token is not existent.</li> <li>MUST emit the event <code>OwnershipDelegationStarted</code> on success.</li> <li>After the above conditions are met, this function MUST replace the pending delegation if any.</li> </ul> <p><strong>acceptOwnershipDelegation rules</strong></p> <ul> <li>MUST revert if there is no delegation.</li> <li>MUST revert unless the method caller is the delegatee, or an authorized operator of delegatee.</li> <li>MUST revert unless the expiry time is in the future.</li> <li>MUST emit the event <code>OwnershipDelegationAccepted</code> on success.</li> <li>After the above conditions are met, the delegatee MUST be recorded as the ownership manager until the delegation expires.</li> </ul> <p><strong>stopDelegateOwnership rules</strong></p> <ul> <li>MUST revert unless the delegation is already accepted.</li> <li>MUST revert unless the expiry time is in the future.</li> <li>MUST revert unless the method caller is the delegatee, or an authorized operator of delegatee.</li> <li>MUST emit the event <code>OwnershipDelegationStopped</code> on success.</li> <li>After the above conditions are met, the owner MUST be recorded as the ownership manager.</li> </ul> <h3 id="token-un-lock-rules"><strong>Token (Un)lock Rules</strong></h3> <p>To be more explicit about how token (un)locked, these functions:</p> <ul> <li>A token can be attached to a context using the <code>attachContext</code> method</li> <li>The <code>setContextLock</code> function MUST be called by the controller to (un)lock</li> <li>The <code>requestDetachContext</code> and <code>execDetachContext</code> functions MUST be called by the ownership manager and MUST operate with respect to the <code>IERC7695ContextCallback</code> hook functions</li> </ul> <p>A list of scenarios and rules follows.</p> <p><strong>Scenarios</strong></p> <p><em><strong>Scenario#1:</strong></em> Context controller wants to (un)lock a token that is not requested for detachment.</p> <ul> <li><code>setContextLock</code> MUST be called successfully</li> </ul> <p><em><strong>Scenario#2:</strong></em> Context controller wants to (un)lock a token that is requested for detachment.</p> <ul> <li><code>setContextLock</code> MUST be reverted</li> </ul> <p><em><strong>Scenario#3:</strong></em> Ownership manager wants to (unlock and) detach a locked token and the callback controller implements <code>IERC7695ContextCallback</code>.</p> <ul> <li>Caller MUST: <ul> <li>Call <code>requestDetachContext</code> function successfully</li> <li>Wait at least context detaching duration (see variable <code>detachingDuration</code> in the <code>getContext</code> function)</li> <li>Call <code>execDetachContext</code> function successfully</li> </ul> </li> <li><code>requestDetachContext</code> MUST call the <code>onDetachRequested</code> function despite the call result</li> <li><code>execDetachContext</code> MUST call the <code>onExecDetachContext</code> function despite the call result</li> </ul> <p><em><strong>Scenario#4:</strong></em> Ownership manager wants to (unlock and) detach a locked token and the callback controller does not implement <code>IERC7695ContextCallback</code>.</p> <ul> <li>Caller MUST: <ul> <li>Call <code>requestDetachContext</code> function successfully</li> <li>Wait at least context detaching duration (see variable <code>detachingDuration</code> in the <code>getContext</code> function)</li> <li>Call <code>execDetachContext</code> function successfully</li> </ul> </li> </ul> <p><em><strong>Scenario#5:</strong></em> Ownership manager wants to detach an unlocked token and the callback controller implements <code>IERC7695ContextCallback</code>.</p> <ul> <li>Caller MUST call <code>requestDetachContext</code> function successfully</li> <li><code>requestDetachContext</code> MUST call the <code>onExecDetachContext</code> function despite the result</li> <li><code>execDetachContext</code> MUST NOT be called</li> </ul> <p><em><strong>Scenario#6:</strong></em> Ownership manager wants to detach an unlocked token and the callback controller does not implement <code>IERC7695ContextCallback</code>.</p> <ul> <li>Caller MUST call <code>requestDetachContext</code> function successfully</li> <li><code>execDetachContext</code> MUST NOT be called</li> </ul> <p><strong>Rules</strong></p> <p><strong>attachContext rules</strong></p> <ul> <li>MUST revert unless the method caller is the ownership manager, an authorized operator of ownership manager, or the approved address for this NFT (if the token is not being delegated).</li> <li>MUST revert if the context is non-existent.</li> <li>MUST revert if the token is already attached to the context.</li> <li>MUST emit the event <code>ContextAttached</code>.</li> <li>After the above conditions are met, this function MUST check if the controller address is a smart contract (e.g. code size &gt; 0). If so, it MUST call <code>onAttached</code> and MUST revert if the call is failed. <ul> <li>The <code>data</code> argument provided by the caller MUST be passed with its contents unaltered to the <code>onAttached</code> hook function via its <code>data</code> argument.</li> </ul> </li> </ul> <p><strong>setContextLock rules</strong></p> <ul> <li>MUST revert if the context is non-existent.</li> <li>MUST revert if the token is not attached to the context.</li> <li>MUST revert if a detachment request has previously been made.</li> <li>MUST revert if the method caller is not context controller.</li> <li>MUST emit the event <code>ContextLockUpdated</code> on success.</li> </ul> <p><strong>requestDetachContext rules</strong></p> <ul> <li>MUST revert if a detachment request has previously been made.</li> <li>MUST revert unless the method caller is the context controller, the ownership manager, an authorized operator of the ownership manager, or the approved address for this NFT (if the token is not being delegated).</li> <li>If the caller is context controller or the token context is not locked, MUST emit the <code>ContextDetached</code> event. After the above conditions are met, this function MUST check if the controller address is a smart contract (e.g. code size &gt; 0). If so, it MUST call <code>onExecDetachContext</code> and the call result MUST be skipped. <ul> <li>The <code>data</code> argument provided by the caller MUST be passed with its contents unaltered to the <code>onExecDetachContext</code> hook function via its <code>data</code> argument.</li> </ul> </li> <li>If the token context is locked, MUST emit the <code>ContextDetachRequested</code> event. After the above conditions are met, this function MUST check if the controller address is a smart contract (e.g. code size &gt; 0). If so, it MUST call <code>onDetachRequested</code> and the call result MUST be skipped. <ul> <li>The <code>data</code> argument provided by the caller MUST be passed with its contents unaltered to the <code>onDetachRequested</code> hook function via its <code>data</code> argument.</li> </ul> </li> </ul> <p><strong>execDetachContext rules</strong></p> <ul> <li>MUST revert unless the method caller is the ownership manager, an authorized operator of ownership manager, or the approved address for this NFT (if the token is not being delegated).</li> <li>MUST revert unless a detachment request has previously been made and the specified detaching duration has passed (use variable <code>detachingDuration</code> in the <code>getContext</code> function when requesting detachment).</li> <li>MUST emit the <code>ContextDetached</code> event.</li> <li>After the above conditions are met, this function MUST check if the controller address is a smart contract (e.g. code size &gt; 0). If so, it MUST call <code>onExecDetachContext</code> and the call result MUST be skipped. <ul> <li>The <code>data</code> argument provided by the caller MUST be passed with its contents unaltered to the <code>onExecDetachContext</code> hook function via its <code>data</code> argument.</li> </ul> </li> </ul> <h3 id="additional-transfer-rules">Additional Transfer Rules</h3> <p>In addition to extending from <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> for the transfer mechanism when transferring an NFT, the implementation:</p> <ul> <li>MUST revert unless the method caller is the ownership manager, an authorized operator of ownership manager, or the approved address for this NFT (if the token is not being delegated).</li> <li>MUST revoke ownership delegation if any.</li> <li>MUST detach every attached context: <ul> <li>MUST revert unless a detachment request has previously been made and the specified detaching duration has passed (use variable <code>detachingDuration</code> in the <code>getContext</code> function when requesting detachment) if the token is locked.</li> <li>MUST check if the controller address is a smart contract (e.g. code size &gt; 0). If so, it MUST call the <code>onExecDetachContext</code> function (with an empty <code>data</code> argument <code>""</code>) and the call result MUST be skipped.</li> </ul> </li> </ul> <h2 id="rationale">Rationale</h2> <p>When designing the proposal, we considered the following concerns.</p> <h3 id="multiple-contexts-for-multiple-use-cases">Multiple contexts for multiple use cases</h3> <p>This proposal is centered around Token Context to allow for the creation of distinct contexts tailored to various decentralized applications (dApps). The context controller assumes the role of facilitating (rental or delegation) dApps, by enabling the granting of usage rights to another user without modifying the NFT's owner record. Besides, this proposal provides the lock feature for contexts to ensure trustlessness in performing these dApps, especially staking cases.</p> <h3 id="providing-an-unlock-mechanism-for-owners">Providing an unlock mechanism for owners</h3> <p>By providing an unlock mechanism for owners, this approach allows owners to unlock their tokens independently, without relying on the context controller to initiate the process. This prevents scenarios where, should the controller lose control, owners would be unable to unlock their tokens.</p> <h3 id="attachment-and-detachment-callbacks">Attachment and detachment callbacks</h3> <p>The callback results of the <code>onDetachRequested</code> and <code>onExecDetachContext</code> functions in the <strong>Token (Un)lock Rules</strong> are skipped because we are intentionally removing the controller's ability to stop detachment, ensuring token detachment is independent of the controller's actions.</p> <p>Additionally, to retain the permission to reject incoming attachments, the operation reverts if the call to the <code>onAttach</code> function fails.</p> <h3 id="ownership-delegation">Ownership delegation</h3> <p>This feature provides a new approach by separating the owner and ownership. Primarily designed to facilitate delegating for third parties, it enables delegating another account as the manager of ownership, distinct from the owner.</p> <p>Unlike <code>approve</code> or <code>setApprovalForAll</code> methods, which grant permission to other accounts while maintaining ownership status. Ownership delegation goes beyond simply granting permissions; it involves transferring the owner's rights to the delegatee, with provisions for automatic reversion upon expiration. This mechanism prevents potential abuses, such as requesting mortgages and transfers to alternative accounts if the owner retains ownership rights.</p> <p>The <strong>2-step delegation</strong> process is provided to prevent mistakes in assigning delegatees, it must be done through two steps: offer and confirm. In cases the delegation needs to be canceled before its scheduled expiry, the delegatees can invoke <code>stopOwnershipDelegation</code> method.</p> <h3 id="transfer-method-mechanism">Transfer method mechanism</h3> <p>As part of the integration with the transfer method, we extended its implicit behavior to include token approval:</p> <ul> <li><strong>Reset Ownership Delegation:</strong> Automatically resets ownership delegations. The <code>OwnershipDelegationStopped</code> event is intentionally not emitted.</li> <li><strong>Detach All Contexts:</strong> Similarly, all contexts associated with the token are detached if none of them is locked. The <code>ContextDetached</code> event is intentionally not emitted.</li> </ul> <p>These modifications are to ensure trustlessness and gas efficiency during token transfers, providing a seamless experience for users.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is backward compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="detaching-duration">Detaching duration</h3> <p>When developing this token standard to serve multiple contexts:</p> <ul> <li>The contract deployer should establish an appropriate upper threshold for detachment delay (by <code>maxDetachingDuration</code> method).</li> <li>The context owner should anticipate potential use cases and establish an appropriate period not larger than the upper threshold.</li> </ul> <p>This precaution is essential to mitigate the risk of the owner abusing systems by spamming listings and transferring tokens to another owner in a short time.</p> <h3 id="duplicated-token-usage">Duplicated token usage</h3> <p>When initiating a new context, the context controllers should track all other contexts within the NFT contract to prevent duplicated usage.</p> <p>For example, suppose a scenario where a token is locked for rental purposes within a particular game. If that game introduces another context (e.g. supporting delegation in that game), it could lead to duplicated token usage within the game, despite being intended for different contexts.</p> <p>In such cases, a shared context for rental and delegation purposes can be considered. Or there must be some restrictions on the new delegation context to prevent reusing that token in the game.</p> <h3 id="ownership-delegation-buffer-time">Ownership Delegation Buffer Time</h3> <p>When constructing systems that rely on ownership delegation for product development, it is imperative to incorporate a buffer time (of at least <code>maxDetachingDuration</code> seconds) when requesting ownership delegation. This precaution is essential to mitigate the risk of potential abuse, particularly if one of the associated contexts locks the token until the delegation time expires. For example, consider a scenario where a mortgage contract is built atop this standard, which has a maximum detaching duration of 7 days, while the required delegation period is only 3 days. In such cases, without an adequate buffer time, the owner could exploit the system by withdrawing funds and invoking the relevant context to lock the token, thus preventing its unlock and transfer.</p> <h3 id="validating-callback-callers">Validating Callback Callers</h3> <p>To enhance security and integrity in interactions between contracts, it is essential to validate the caller of any callback function while implementing the <code>IERC7695ContextCallback</code>. This validation ensures that the <code>msg.sender</code> of the callback is indeed the expected contract address, typically the token contract or a designated controller contract. Such checks are crucial for preventing unauthorized actions that could be executed by malicious entities pretending to be a legitimate contract.</p> <h3 id="recommended-practices">Recommended practices</h3> <p><strong>Rental</strong></p> <p>This is a typical use case for rentals, supposing A(owner) owns a token and wants to list his/her token for rent, and B(user) wants to rent the token to play in a certain game.</p> <p><img src="https://wg-eips.ritovision.com/7695/./assets/rental.svg" alt="Rental Flow" /></p> <p><strong>Mortgage</strong></p> <p>When constructing collateral systems, it is recommended to support token owners who wish to rent out their tokens while using them for collateral lending. This approach enhances the appeal of mortgage systems, creating a more attractive and versatile financial ecosystem that meets many different needs.</p> <p>This is a typical use case for mortgages, supposing A(owner) owns a token and wants to mortgage, and B(lender) wants to earn interest by lending their funds to A.</p> <p><img src="https://wg-eips.ritovision.com/7695/./assets/mortgage.svg" alt="Mortgage Flow" /></p> <h3 id="risk-of-token-owner">Risk of Token Owner</h3> <p><strong>Phishing attacks</strong></p> <p>It is crucial to note that the owner role has the ability to delegate ownership to another account, allowing it to authorize transfers out of the respective wallet. Consequently, some malicious actors could deceive the token owner into delegating them as a delegatee by invoking the <code>startDelegateOwnership</code> method. This risk can be considered the same as the <code>approve</code> or <code>setApprovalForAll</code> methods.</p> <p><strong>Ownership rights loss</strong></p> <p>When interacting with a contract system (e.g. mortgage), where owners have to delegate their ownership rights to the smart contract, it's imperative to:</p> <ul> <li>Ensure the timeframe for delegation is reasonable and not excessively distant. If the contract mandates a delegation period that extends too far into the future, make sure it includes a provision to revoke ownership delegation when specific conditions are met. Failing to include such a provision could lead to the loss of ownership rights until the delegation expires.</li> <li>Be aware that if the contract owner or their operator is compromised, the token ownership can be altered.</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> 2024-04-01T00:00:00+00:00 2026-02-11T14:48:26+00:00 William Morrisshttps://github.com/wjmelements https://wg-eips.ritovision.com/7673/

Depict Account Addresses As A String of Emoji

<h2 id="abstract">Abstract</h2> <p>Introduce base256emoji for use as the primary input and display for account addresses in all user interfaces.</p> <h2 id="motivation">Motivation</h2> <p>Human users often fail to distinguish between long strings of hexadecimal characters, especially when they match at the beginning and at the end. This makes hexadecimal strings a poor format for human-readable account addresses. The problem is being exploited by several spoofing strategies that mine similar addresses and spoof <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> Transfer events with the goal of tricking the end user into copying the wrong recipient address. These address spoofing attacks have mislead tens of thousands of ether, and countless other tokens. Spoofers flooding the network with fake Transfer events waste network resources and complicate blockchain accounting. Improving the distinguishability of addresses will reduce the incentives for this behavior.</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>User interfaces:</p> <ul> <li>SHALL depict account addresses as a base256emoji string instead of hexadecimal.</li> <li>SHALL accept base256emoji strings as input for user-supplied account address parameters.</li> <li>SHOULD recognize and interpret strings of exactly 20 consecutive emoji as addresses when all of them are valid base256emoji.</li> </ul> <h3 id="base256emoji-encoding-table">base256emoji encoding table</h3> <table><thead><tr><th style="text-align: center">Emoji</th><th style="text-align: center">Unicode codepoint</th><th style="text-align: center">Byte Value</th></tr></thead><tbody> <tr><td style="text-align: center">🚀</td><td style="text-align: center">U+1F680</td><td style="text-align: center">0</td></tr> <tr><td style="text-align: center">🪐</td><td style="text-align: center">U+1FA90</td><td style="text-align: center">1</td></tr> <tr><td style="text-align: center">☄</td><td style="text-align: center">U+2604</td><td style="text-align: center">2</td></tr> <tr><td style="text-align: center">🛰</td><td style="text-align: center">U+1F6F0</td><td style="text-align: center">3</td></tr> <tr><td style="text-align: center">🌌</td><td style="text-align: center">U+1F30C</td><td style="text-align: center">4</td></tr> <tr><td style="text-align: center">🌑</td><td style="text-align: center">U+1F311</td><td style="text-align: center">5</td></tr> <tr><td style="text-align: center">🌒</td><td style="text-align: center">U+1F312</td><td style="text-align: center">6</td></tr> <tr><td style="text-align: center">🌓</td><td style="text-align: center">U+1F313</td><td style="text-align: center">7</td></tr> <tr><td style="text-align: center">🌔</td><td style="text-align: center">U+1F314</td><td style="text-align: center">8</td></tr> <tr><td style="text-align: center">🌕</td><td style="text-align: center">U+1F315</td><td style="text-align: center">9</td></tr> <tr><td style="text-align: center">🌖</td><td style="text-align: center">U+1F316</td><td style="text-align: center">10</td></tr> <tr><td style="text-align: center">🌗</td><td style="text-align: center">U+1F317</td><td style="text-align: center">11</td></tr> <tr><td style="text-align: center">🌘</td><td style="text-align: center">U+1F318</td><td style="text-align: center">12</td></tr> <tr><td style="text-align: center">🌍</td><td style="text-align: center">U+1F30D</td><td style="text-align: center">13</td></tr> <tr><td style="text-align: center">🌏</td><td style="text-align: center">U+1F30F</td><td style="text-align: center">14</td></tr> <tr><td style="text-align: center">🌎</td><td style="text-align: center">U+1F30E</td><td style="text-align: center">15</td></tr> <tr><td style="text-align: center">🐉</td><td style="text-align: center">U+1F409</td><td style="text-align: center">16</td></tr> <tr><td style="text-align: center">☀</td><td style="text-align: center">U+2600</td><td style="text-align: center">17</td></tr> <tr><td style="text-align: center">💻</td><td style="text-align: center">U+1F4BB</td><td style="text-align: center">18</td></tr> <tr><td style="text-align: center">🖥</td><td style="text-align: center">U+1F5A5</td><td style="text-align: center">19</td></tr> <tr><td style="text-align: center">💾</td><td style="text-align: center">U+1F4BE</td><td style="text-align: center">20</td></tr> <tr><td style="text-align: center">💿</td><td style="text-align: center">U+1F4BF</td><td style="text-align: center">21</td></tr> <tr><td style="text-align: center">😂</td><td style="text-align: center">U+1F602</td><td style="text-align: center">22</td></tr> <tr><td style="text-align: center">❤</td><td style="text-align: center">U+2764</td><td style="text-align: center">23</td></tr> <tr><td style="text-align: center">😍</td><td style="text-align: center">U+1F60D</td><td style="text-align: center">24</td></tr> <tr><td style="text-align: center">🤣</td><td style="text-align: center">U+1F923</td><td style="text-align: center">25</td></tr> <tr><td style="text-align: center">😊</td><td style="text-align: center">U+1F60A</td><td style="text-align: center">26</td></tr> <tr><td style="text-align: center">🙏</td><td style="text-align: center">U+1F64F</td><td style="text-align: center">27</td></tr> <tr><td style="text-align: center">💕</td><td style="text-align: center">U+1F495</td><td style="text-align: center">28</td></tr> <tr><td style="text-align: center">😭</td><td style="text-align: center">U+1F62D</td><td style="text-align: center">29</td></tr> <tr><td style="text-align: center">😘</td><td style="text-align: center">U+1F618</td><td style="text-align: center">30</td></tr> <tr><td style="text-align: center">👍</td><td style="text-align: center">U+1F44D</td><td style="text-align: center">31</td></tr> <tr><td style="text-align: center">😅</td><td style="text-align: center">U+1F605</td><td style="text-align: center">32</td></tr> <tr><td style="text-align: center">👏</td><td style="text-align: center">U+1F44F</td><td style="text-align: center">33</td></tr> <tr><td style="text-align: center">😁</td><td style="text-align: center">U+1F601</td><td style="text-align: center">34</td></tr> <tr><td style="text-align: center">🔥</td><td style="text-align: center">U+1F525</td><td style="text-align: center">35</td></tr> <tr><td style="text-align: center">🥰</td><td style="text-align: center">U+1F970</td><td style="text-align: center">36</td></tr> <tr><td style="text-align: center">💔</td><td style="text-align: center">U+1F494</td><td style="text-align: center">37</td></tr> <tr><td style="text-align: center">💖</td><td style="text-align: center">U+1F496</td><td style="text-align: center">38</td></tr> <tr><td style="text-align: center">💙</td><td style="text-align: center">U+1F499</td><td style="text-align: center">39</td></tr> <tr><td style="text-align: center">😢</td><td style="text-align: center">U+1F622</td><td style="text-align: center">40</td></tr> <tr><td style="text-align: center">🤔</td><td style="text-align: center">U+1F914</td><td style="text-align: center">41</td></tr> <tr><td style="text-align: center">😆</td><td style="text-align: center">U+1F606</td><td style="text-align: center">42</td></tr> <tr><td style="text-align: center">🙄</td><td style="text-align: center">U+1F644</td><td style="text-align: center">43</td></tr> <tr><td style="text-align: center">💪</td><td style="text-align: center">U+1F4AA</td><td style="text-align: center">44</td></tr> <tr><td style="text-align: center">😉</td><td style="text-align: center">U+1F609</td><td style="text-align: center">45</td></tr> <tr><td style="text-align: center">☺</td><td style="text-align: center">U+263A</td><td style="text-align: center">46</td></tr> <tr><td style="text-align: center">👌</td><td style="text-align: center">U+1F44C</td><td style="text-align: center">47</td></tr> <tr><td style="text-align: center">🤗</td><td style="text-align: center">U+1F917</td><td style="text-align: center">48</td></tr> <tr><td style="text-align: center">💜</td><td style="text-align: center">U+1F49C</td><td style="text-align: center">49</td></tr> <tr><td style="text-align: center">😔</td><td style="text-align: center">U+1F614</td><td style="text-align: center">50</td></tr> <tr><td style="text-align: center">😎</td><td style="text-align: center">U+1F60E</td><td style="text-align: center">51</td></tr> <tr><td style="text-align: center">😇</td><td style="text-align: center">U+1F607</td><td style="text-align: center">52</td></tr> <tr><td style="text-align: center">🌹</td><td style="text-align: center">U+1F339</td><td style="text-align: center">53</td></tr> <tr><td style="text-align: center">🤦</td><td style="text-align: center">U+1F926</td><td style="text-align: center">54</td></tr> <tr><td style="text-align: center">🎉</td><td style="text-align: center">U+1F389</td><td style="text-align: center">55</td></tr> <tr><td style="text-align: center">💞</td><td style="text-align: center">U+1F49E</td><td style="text-align: center">56</td></tr> <tr><td style="text-align: center">✌</td><td style="text-align: center">U+270C</td><td style="text-align: center">57</td></tr> <tr><td style="text-align: center">✨</td><td style="text-align: center">U+2728</td><td style="text-align: center">58</td></tr> <tr><td style="text-align: center">🤷</td><td style="text-align: center">U+1F937</td><td style="text-align: center">59</td></tr> <tr><td style="text-align: center">😱</td><td style="text-align: center">U+1F631</td><td style="text-align: center">60</td></tr> <tr><td style="text-align: center">😌</td><td style="text-align: center">U+1F60C</td><td style="text-align: center">61</td></tr> <tr><td style="text-align: center">🌸</td><td style="text-align: center">U+1F338</td><td style="text-align: center">62</td></tr> <tr><td style="text-align: center">🙌</td><td style="text-align: center">U+1F64C</td><td style="text-align: center">63</td></tr> <tr><td style="text-align: center">😋</td><td style="text-align: center">U+1F60B</td><td style="text-align: center">64</td></tr> <tr><td style="text-align: center">💗</td><td style="text-align: center">U+1F497</td><td style="text-align: center">65</td></tr> <tr><td style="text-align: center">💚</td><td style="text-align: center">U+1F49A</td><td style="text-align: center">66</td></tr> <tr><td style="text-align: center">😏</td><td style="text-align: center">U+1F60F</td><td style="text-align: center">67</td></tr> <tr><td style="text-align: center">💛</td><td style="text-align: center">U+1F49B</td><td style="text-align: center">68</td></tr> <tr><td style="text-align: center">🙂</td><td style="text-align: center">U+1F642</td><td style="text-align: center">69</td></tr> <tr><td style="text-align: center">💓</td><td style="text-align: center">U+1F493</td><td style="text-align: center">70</td></tr> <tr><td style="text-align: center">🤩</td><td style="text-align: center">U+1F929</td><td style="text-align: center">71</td></tr> <tr><td style="text-align: center">😄</td><td style="text-align: center">U+1F604</td><td style="text-align: center">72</td></tr> <tr><td style="text-align: center">😀</td><td style="text-align: center">U+1F600</td><td style="text-align: center">73</td></tr> <tr><td style="text-align: center">🖤</td><td style="text-align: center">U+1F5A4</td><td style="text-align: center">74</td></tr> <tr><td style="text-align: center">😃</td><td style="text-align: center">U+1F603</td><td style="text-align: center">75</td></tr> <tr><td style="text-align: center">💯</td><td style="text-align: center">U+1F4AF</td><td style="text-align: center">76</td></tr> <tr><td style="text-align: center">🙈</td><td style="text-align: center">U+1F648</td><td style="text-align: center">77</td></tr> <tr><td style="text-align: center">👇</td><td style="text-align: center">U+1F447</td><td style="text-align: center">78</td></tr> <tr><td style="text-align: center">🎶</td><td style="text-align: center">U+1F3B6</td><td style="text-align: center">79</td></tr> <tr><td style="text-align: center">😒</td><td style="text-align: center">U+1F612</td><td style="text-align: center">80</td></tr> <tr><td style="text-align: center">🤭</td><td style="text-align: center">U+1F92D</td><td style="text-align: center">81</td></tr> <tr><td style="text-align: center">❣</td><td style="text-align: center">U+2763</td><td style="text-align: center">82</td></tr> <tr><td style="text-align: center">😜</td><td style="text-align: center">U+1F61C</td><td style="text-align: center">83</td></tr> <tr><td style="text-align: center">💋</td><td style="text-align: center">U+1F48B</td><td style="text-align: center">84</td></tr> <tr><td style="text-align: center">👀</td><td style="text-align: center">U+1F440</td><td style="text-align: center">85</td></tr> <tr><td style="text-align: center">😪</td><td style="text-align: center">U+1F62A</td><td style="text-align: center">86</td></tr> <tr><td style="text-align: center">😑</td><td style="text-align: center">U+1F611</td><td style="text-align: center">87</td></tr> <tr><td style="text-align: center">💥</td><td style="text-align: center">U+1F4A5</td><td style="text-align: center">88</td></tr> <tr><td style="text-align: center">🙋</td><td style="text-align: center">U+1F64B</td><td style="text-align: center">89</td></tr> <tr><td style="text-align: center">😞</td><td style="text-align: center">U+1F61E</td><td style="text-align: center">90</td></tr> <tr><td style="text-align: center">😩</td><td style="text-align: center">U+1F629</td><td style="text-align: center">91</td></tr> <tr><td style="text-align: center">😡</td><td style="text-align: center">U+1F621</td><td style="text-align: center">92</td></tr> <tr><td style="text-align: center">🤪</td><td style="text-align: center">U+1F92A</td><td style="text-align: center">93</td></tr> <tr><td style="text-align: center">👊</td><td style="text-align: center">U+1F44A</td><td style="text-align: center">94</td></tr> <tr><td style="text-align: center">🥳</td><td style="text-align: center">U+1F973</td><td style="text-align: center">95</td></tr> <tr><td style="text-align: center">😥</td><td style="text-align: center">U+1F625</td><td style="text-align: center">96</td></tr> <tr><td style="text-align: center">🤤</td><td style="text-align: center">U+1F924</td><td style="text-align: center">97</td></tr> <tr><td style="text-align: center">👉</td><td style="text-align: center">U+1F449</td><td style="text-align: center">98</td></tr> <tr><td style="text-align: center">💃</td><td style="text-align: center">U+1F483</td><td style="text-align: center">99</td></tr> <tr><td style="text-align: center">😳</td><td style="text-align: center">U+1F633</td><td style="text-align: center">100</td></tr> <tr><td style="text-align: center">✋</td><td style="text-align: center">U+270B</td><td style="text-align: center">101</td></tr> <tr><td style="text-align: center">😚</td><td style="text-align: center">U+1F61A</td><td style="text-align: center">102</td></tr> <tr><td style="text-align: center">😝</td><td style="text-align: center">U+1F61D</td><td style="text-align: center">103</td></tr> <tr><td style="text-align: center">😴</td><td style="text-align: center">U+1F634</td><td style="text-align: center">104</td></tr> <tr><td style="text-align: center">🌟</td><td style="text-align: center">U+1F31F</td><td style="text-align: center">105</td></tr> <tr><td style="text-align: center">😬</td><td style="text-align: center">U+1F62C</td><td style="text-align: center">106</td></tr> <tr><td style="text-align: center">🙃</td><td style="text-align: center">U+1F643</td><td style="text-align: center">107</td></tr> <tr><td style="text-align: center">🍀</td><td style="text-align: center">U+1F340</td><td style="text-align: center">108</td></tr> <tr><td style="text-align: center">🌷</td><td style="text-align: center">U+1F337</td><td style="text-align: center">109</td></tr> <tr><td style="text-align: center">😻</td><td style="text-align: center">U+1F63B</td><td style="text-align: center">110</td></tr> <tr><td style="text-align: center">😓</td><td style="text-align: center">U+1F613</td><td style="text-align: center">111</td></tr> <tr><td style="text-align: center">⭐</td><td style="text-align: center">U+2B50</td><td style="text-align: center">112</td></tr> <tr><td style="text-align: center">✅</td><td style="text-align: center">U+2705</td><td style="text-align: center">113</td></tr> <tr><td style="text-align: center">🥺</td><td style="text-align: center">U+1F97A</td><td style="text-align: center">114</td></tr> <tr><td style="text-align: center">🌈</td><td style="text-align: center">U+1F308</td><td style="text-align: center">115</td></tr> <tr><td style="text-align: center">😈</td><td style="text-align: center">U+1F608</td><td style="text-align: center">116</td></tr> <tr><td style="text-align: center">🤘</td><td style="text-align: center">U+1F918</td><td style="text-align: center">117</td></tr> <tr><td style="text-align: center">💦</td><td style="text-align: center">U+1F4A6</td><td style="text-align: center">118</td></tr> <tr><td style="text-align: center">✔</td><td style="text-align: center">U+2714</td><td style="text-align: center">119</td></tr> <tr><td style="text-align: center">😣</td><td style="text-align: center">U+1F623</td><td style="text-align: center">120</td></tr> <tr><td style="text-align: center">🏃</td><td style="text-align: center">U+1F3C3</td><td style="text-align: center">121</td></tr> <tr><td style="text-align: center">💐</td><td style="text-align: center">U+1F490</td><td style="text-align: center">122</td></tr> <tr><td style="text-align: center">☹</td><td style="text-align: center">U+2639</td><td style="text-align: center">123</td></tr> <tr><td style="text-align: center">🎊</td><td style="text-align: center">U+1F38A</td><td style="text-align: center">124</td></tr> <tr><td style="text-align: center">💘</td><td style="text-align: center">U+1F498</td><td style="text-align: center">125</td></tr> <tr><td style="text-align: center">😠</td><td style="text-align: center">U+1F620</td><td style="text-align: center">126</td></tr> <tr><td style="text-align: center">☝</td><td style="text-align: center">U+261D</td><td style="text-align: center">127</td></tr> <tr><td style="text-align: center">😕</td><td style="text-align: center">U+1F615</td><td style="text-align: center">128</td></tr> <tr><td style="text-align: center">🌺</td><td style="text-align: center">U+1F33A</td><td style="text-align: center">129</td></tr> <tr><td style="text-align: center">🎂</td><td style="text-align: center">U+1F382</td><td style="text-align: center">130</td></tr> <tr><td style="text-align: center">🌻</td><td style="text-align: center">U+1F33B</td><td style="text-align: center">131</td></tr> <tr><td style="text-align: center">😐</td><td style="text-align: center">U+1F610</td><td style="text-align: center">132</td></tr> <tr><td style="text-align: center">🖕</td><td style="text-align: center">U+1F595</td><td style="text-align: center">133</td></tr> <tr><td style="text-align: center">💝</td><td style="text-align: center">U+1F49D</td><td style="text-align: center">134</td></tr> <tr><td style="text-align: center">🙊</td><td style="text-align: center">U+1F64A</td><td style="text-align: center">135</td></tr> <tr><td style="text-align: center">😹</td><td style="text-align: center">U+1F639</td><td style="text-align: center">136</td></tr> <tr><td style="text-align: center">🗣</td><td style="text-align: center">U+1F5E3</td><td style="text-align: center">137</td></tr> <tr><td style="text-align: center">💫</td><td style="text-align: center">U+1F4AB</td><td style="text-align: center">138</td></tr> <tr><td style="text-align: center">💀</td><td style="text-align: center">U+1F480</td><td style="text-align: center">139</td></tr> <tr><td style="text-align: center">👑</td><td style="text-align: center">U+1F451</td><td style="text-align: center">140</td></tr> <tr><td style="text-align: center">🎵</td><td style="text-align: center">U+1F3B5</td><td style="text-align: center">141</td></tr> <tr><td style="text-align: center">🤞</td><td style="text-align: center">U+1F91E</td><td style="text-align: center">142</td></tr> <tr><td style="text-align: center">😛</td><td style="text-align: center">U+1F61B</td><td style="text-align: center">143</td></tr> <tr><td style="text-align: center">🔴</td><td style="text-align: center">U+1F534</td><td style="text-align: center">144</td></tr> <tr><td style="text-align: center">😤</td><td style="text-align: center">U+1F624</td><td style="text-align: center">145</td></tr> <tr><td style="text-align: center">🌼</td><td style="text-align: center">U+1F33C</td><td style="text-align: center">146</td></tr> <tr><td style="text-align: center">😫</td><td style="text-align: center">U+1F62B</td><td style="text-align: center">147</td></tr> <tr><td style="text-align: center">⚽</td><td style="text-align: center">U+26BD</td><td style="text-align: center">148</td></tr> <tr><td style="text-align: center">🤙</td><td style="text-align: center">U+1F919</td><td style="text-align: center">149</td></tr> <tr><td style="text-align: center">☕</td><td style="text-align: center">U+2615</td><td style="text-align: center">150</td></tr> <tr><td style="text-align: center">🏆</td><td style="text-align: center">U+1F3C6</td><td style="text-align: center">151</td></tr> <tr><td style="text-align: center">🤫</td><td style="text-align: center">U+1F92B</td><td style="text-align: center">152</td></tr> <tr><td style="text-align: center">👈</td><td style="text-align: center">U+1F448</td><td style="text-align: center">153</td></tr> <tr><td style="text-align: center">😮</td><td style="text-align: center">U+1F62E</td><td style="text-align: center">154</td></tr> <tr><td style="text-align: center">🙆</td><td style="text-align: center">U+1F646</td><td style="text-align: center">155</td></tr> <tr><td style="text-align: center">🍻</td><td style="text-align: center">U+1F37B</td><td style="text-align: center">156</td></tr> <tr><td style="text-align: center">🍃</td><td style="text-align: center">U+1F343</td><td style="text-align: center">157</td></tr> <tr><td style="text-align: center">🐶</td><td style="text-align: center">U+1F436</td><td style="text-align: center">158</td></tr> <tr><td style="text-align: center">💁</td><td style="text-align: center">U+1F481</td><td style="text-align: center">159</td></tr> <tr><td style="text-align: center">😲</td><td style="text-align: center">U+1F632</td><td style="text-align: center">160</td></tr> <tr><td style="text-align: center">🌿</td><td style="text-align: center">U+1F33F</td><td style="text-align: center">161</td></tr> <tr><td style="text-align: center">🧡</td><td style="text-align: center">U+1F9E1</td><td style="text-align: center">162</td></tr> <tr><td style="text-align: center">🎁</td><td style="text-align: center">U+1F381</td><td style="text-align: center">163</td></tr> <tr><td style="text-align: center">⚡</td><td style="text-align: center">U+26A1</td><td style="text-align: center">164</td></tr> <tr><td style="text-align: center">🌞</td><td style="text-align: center">U+1F31E</td><td style="text-align: center">165</td></tr> <tr><td style="text-align: center">🎈</td><td style="text-align: center">U+1F388</td><td style="text-align: center">166</td></tr> <tr><td style="text-align: center">❌</td><td style="text-align: center">U+274C</td><td style="text-align: center">167</td></tr> <tr><td style="text-align: center">✊</td><td style="text-align: center">U+270A</td><td style="text-align: center">168</td></tr> <tr><td style="text-align: center">👋</td><td style="text-align: center">U+1F44B</td><td style="text-align: center">169</td></tr> <tr><td style="text-align: center">😰</td><td style="text-align: center">U+1F630</td><td style="text-align: center">170</td></tr> <tr><td style="text-align: center">🤨</td><td style="text-align: center">U+1F928</td><td style="text-align: center">171</td></tr> <tr><td style="text-align: center">😶</td><td style="text-align: center">U+1F636</td><td style="text-align: center">172</td></tr> <tr><td style="text-align: center">🤝</td><td style="text-align: center">U+1F91D</td><td style="text-align: center">173</td></tr> <tr><td style="text-align: center">🚶</td><td style="text-align: center">U+1F6B6</td><td style="text-align: center">174</td></tr> <tr><td style="text-align: center">💰</td><td style="text-align: center">U+1F4B0</td><td style="text-align: center">175</td></tr> <tr><td style="text-align: center">🍓</td><td style="text-align: center">U+1F353</td><td style="text-align: center">176</td></tr> <tr><td style="text-align: center">💢</td><td style="text-align: center">U+1F4A2</td><td style="text-align: center">177</td></tr> <tr><td style="text-align: center">🤟</td><td style="text-align: center">U+1F91F</td><td style="text-align: center">178</td></tr> <tr><td style="text-align: center">🙁</td><td style="text-align: center">U+1F641</td><td style="text-align: center">179</td></tr> <tr><td style="text-align: center">🚨</td><td style="text-align: center">U+1F6A8</td><td style="text-align: center">180</td></tr> <tr><td style="text-align: center">💨</td><td style="text-align: center">U+1F4A8</td><td style="text-align: center">181</td></tr> <tr><td style="text-align: center">🤬</td><td style="text-align: center">U+1F92C</td><td style="text-align: center">182</td></tr> <tr><td style="text-align: center">✈</td><td style="text-align: center">U+2708</td><td style="text-align: center">183</td></tr> <tr><td style="text-align: center">🎀</td><td style="text-align: center">U+1F380</td><td style="text-align: center">184</td></tr> <tr><td style="text-align: center">🍺</td><td style="text-align: center">U+1F37A</td><td style="text-align: center">185</td></tr> <tr><td style="text-align: center">🤓</td><td style="text-align: center">U+1F913</td><td style="text-align: center">186</td></tr> <tr><td style="text-align: center">😙</td><td style="text-align: center">U+1F619</td><td style="text-align: center">187</td></tr> <tr><td style="text-align: center">💟</td><td style="text-align: center">U+1F49F</td><td style="text-align: center">188</td></tr> <tr><td style="text-align: center">🌱</td><td style="text-align: center">U+1F331</td><td style="text-align: center">189</td></tr> <tr><td style="text-align: center">😖</td><td style="text-align: center">U+1F616</td><td style="text-align: center">190</td></tr> <tr><td style="text-align: center">👶</td><td style="text-align: center">U+1F476</td><td style="text-align: center">191</td></tr> <tr><td style="text-align: center">🥴</td><td style="text-align: center">U+1F974</td><td style="text-align: center">192</td></tr> <tr><td style="text-align: center">▶</td><td style="text-align: center">U+25B6</td><td style="text-align: center">193</td></tr> <tr><td style="text-align: center">➡</td><td style="text-align: center">U+27A1</td><td style="text-align: center">194</td></tr> <tr><td style="text-align: center">❓</td><td style="text-align: center">U+2753</td><td style="text-align: center">195</td></tr> <tr><td style="text-align: center">💎</td><td style="text-align: center">U+1F48E</td><td style="text-align: center">196</td></tr> <tr><td style="text-align: center">💸</td><td style="text-align: center">U+1F4B8</td><td style="text-align: center">197</td></tr> <tr><td style="text-align: center">⬇</td><td style="text-align: center">U+2B07</td><td style="text-align: center">198</td></tr> <tr><td style="text-align: center">😨</td><td style="text-align: center">U+1F628</td><td style="text-align: center">199</td></tr> <tr><td style="text-align: center">🌚</td><td style="text-align: center">U+1F31A</td><td style="text-align: center">200</td></tr> <tr><td style="text-align: center">🦋</td><td style="text-align: center">U+1F98B</td><td style="text-align: center">201</td></tr> <tr><td style="text-align: center">😷</td><td style="text-align: center">U+1F637</td><td style="text-align: center">202</td></tr> <tr><td style="text-align: center">🕺</td><td style="text-align: center">U+1F57A</td><td style="text-align: center">203</td></tr> <tr><td style="text-align: center">⚠</td><td style="text-align: center">U+26A0</td><td style="text-align: center">204</td></tr> <tr><td style="text-align: center">🙅</td><td style="text-align: center">U+1F645</td><td style="text-align: center">205</td></tr> <tr><td style="text-align: center">😟</td><td style="text-align: center">U+1F61F</td><td style="text-align: center">206</td></tr> <tr><td style="text-align: center">😵</td><td style="text-align: center">U+1F635</td><td style="text-align: center">207</td></tr> <tr><td style="text-align: center">👎</td><td style="text-align: center">U+1F44E</td><td style="text-align: center">208</td></tr> <tr><td style="text-align: center">🤲</td><td style="text-align: center">U+1F932</td><td style="text-align: center">209</td></tr> <tr><td style="text-align: center">🤠</td><td style="text-align: center">U+1F920</td><td style="text-align: center">210</td></tr> <tr><td style="text-align: center">🤧</td><td style="text-align: center">U+1F927</td><td style="text-align: center">211</td></tr> <tr><td style="text-align: center">📌</td><td style="text-align: center">U+1F4CC</td><td style="text-align: center">212</td></tr> <tr><td style="text-align: center">🔵</td><td style="text-align: center">U+1F535</td><td style="text-align: center">213</td></tr> <tr><td style="text-align: center">💅</td><td style="text-align: center">U+1F485</td><td style="text-align: center">214</td></tr> <tr><td style="text-align: center">🧐</td><td style="text-align: center">U+1F9D0</td><td style="text-align: center">215</td></tr> <tr><td style="text-align: center">🐾</td><td style="text-align: center">U+1F43E</td><td style="text-align: center">216</td></tr> <tr><td style="text-align: center">🍒</td><td style="text-align: center">U+1F352</td><td style="text-align: center">217</td></tr> <tr><td style="text-align: center">😗</td><td style="text-align: center">U+1F617</td><td style="text-align: center">218</td></tr> <tr><td style="text-align: center">🤑</td><td style="text-align: center">U+1F911</td><td style="text-align: center">219</td></tr> <tr><td style="text-align: center">🌊</td><td style="text-align: center">U+1F30A</td><td style="text-align: center">220</td></tr> <tr><td style="text-align: center">🤯</td><td style="text-align: center">U+1F92F</td><td style="text-align: center">221</td></tr> <tr><td style="text-align: center">🐷</td><td style="text-align: center">U+1F437</td><td style="text-align: center">222</td></tr> <tr><td style="text-align: center">☎</td><td style="text-align: center">U+260E</td><td style="text-align: center">223</td></tr> <tr><td style="text-align: center">💧</td><td style="text-align: center">U+1F4A7</td><td style="text-align: center">224</td></tr> <tr><td style="text-align: center">😯</td><td style="text-align: center">U+1F62F</td><td style="text-align: center">225</td></tr> <tr><td style="text-align: center">💆</td><td style="text-align: center">U+1F486</td><td style="text-align: center">226</td></tr> <tr><td style="text-align: center">👆</td><td style="text-align: center">U+1F446</td><td style="text-align: center">227</td></tr> <tr><td style="text-align: center">🎤</td><td style="text-align: center">U+1F3A4</td><td style="text-align: center">228</td></tr> <tr><td style="text-align: center">🙇</td><td style="text-align: center">U+1F647</td><td style="text-align: center">229</td></tr> <tr><td style="text-align: center">🍑</td><td style="text-align: center">U+1F351</td><td style="text-align: center">230</td></tr> <tr><td style="text-align: center">❄</td><td style="text-align: center">U+2744</td><td style="text-align: center">231</td></tr> <tr><td style="text-align: center">🌴</td><td style="text-align: center">U+1F334</td><td style="text-align: center">232</td></tr> <tr><td style="text-align: center">💣</td><td style="text-align: center">U+1F4A3</td><td style="text-align: center">233</td></tr> <tr><td style="text-align: center">🐸</td><td style="text-align: center">U+1F438</td><td style="text-align: center">234</td></tr> <tr><td style="text-align: center">💌</td><td style="text-align: center">U+1F48C</td><td style="text-align: center">235</td></tr> <tr><td style="text-align: center">📍</td><td style="text-align: center">U+1F4CD</td><td style="text-align: center">236</td></tr> <tr><td style="text-align: center">🥀</td><td style="text-align: center">U+1F940</td><td style="text-align: center">237</td></tr> <tr><td style="text-align: center">🤢</td><td style="text-align: center">U+1F922</td><td style="text-align: center">238</td></tr> <tr><td style="text-align: center">👅</td><td style="text-align: center">U+1F445</td><td style="text-align: center">239</td></tr> <tr><td style="text-align: center">💡</td><td style="text-align: center">U+1F4A1</td><td style="text-align: center">240</td></tr> <tr><td style="text-align: center">💩</td><td style="text-align: center">U+1F4A9</td><td style="text-align: center">241</td></tr> <tr><td style="text-align: center">👐</td><td style="text-align: center">U+1F450</td><td style="text-align: center">242</td></tr> <tr><td style="text-align: center">📸</td><td style="text-align: center">U+1F4F8</td><td style="text-align: center">243</td></tr> <tr><td style="text-align: center">👻</td><td style="text-align: center">U+1F47B</td><td style="text-align: center">244</td></tr> <tr><td style="text-align: center">🤐</td><td style="text-align: center">U+1F910</td><td style="text-align: center">245</td></tr> <tr><td style="text-align: center">🤮</td><td style="text-align: center">U+1F92E</td><td style="text-align: center">246</td></tr> <tr><td style="text-align: center">🎼</td><td style="text-align: center">U+1F3BC</td><td style="text-align: center">247</td></tr> <tr><td style="text-align: center">🥵</td><td style="text-align: center">U+1F975</td><td style="text-align: center">248</td></tr> <tr><td style="text-align: center">🚩</td><td style="text-align: center">U+1F6A9</td><td style="text-align: center">249</td></tr> <tr><td style="text-align: center">🍎</td><td style="text-align: center">U+1F34E</td><td style="text-align: center">250</td></tr> <tr><td style="text-align: center">🍊</td><td style="text-align: center">U+1F34A</td><td style="text-align: center">251</td></tr> <tr><td style="text-align: center">👼</td><td style="text-align: center">U+1F47C</td><td style="text-align: center">252</td></tr> <tr><td style="text-align: center">💍</td><td style="text-align: center">U+1F48D</td><td style="text-align: center">253</td></tr> <tr><td style="text-align: center">📣</td><td style="text-align: center">U+1F4E3</td><td style="text-align: center">254</td></tr> <tr><td style="text-align: center">🥂</td><td style="text-align: center">U+1F942</td><td style="text-align: center">255</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <p>Previous attempts to reduce spoofing and other copy errors such as <a href="https://wg-eips.ritovision.com/55/">ERC-55</a> have not reduced the number of characters in an address. Any base-256 standard would achieve this goal but emoji were chosen to maximize human-distinguishability. Multiple base-256 emoji encodings have been proposed. The base256emoji encoding was chosen due to its acceptance into the multibase repository.</p> <p>This standard does not also recommend base256emoji for use in depicting other bytestrings such as transaction hashes and calldata. Transaction hashes are not yet being spoofed. Calldata is best decoded via the appropriate ABI. By only using base256emoji for addresses, addresses can be easily noticed among other information.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Using the encoding table, the base256emoji encoding can be transcoded into hexadecimal and vice-versa.</p> <h2 id="test-cases">Test Cases</h2> <table><thead><tr><th style="text-align: center">base256emoji</th><th style="text-align: center">ERC-55</th></tr></thead><tbody> <tr><td style="text-align: center">🚀🚀🚀🚀🚀🚀😀💓🥴💣👻🙌🙈🤢😥☹🌏💩🍎💕</td><td style="text-align: center"><code>0x0000000000004946c0e9F43F4Dee607b0eF1fA1c</code></td></tr> <tr><td style="text-align: center">🚀🚀🚀🚀🚀🚀💸🎊💡🌿🚩🔥📌🙂💙❄🛰💩🤝⭐</td><td style="text-align: center"><code>0x000000000000c57CF0A1f923d44527e703F1ad70</code></td></tr> <tr><td style="text-align: center">☀☀☀☀☀❤🌊🌖❌💀✔🌎🎈❌💞🛰💗😅❓☄</td><td style="text-align: center"><code>0x111111111117dC0aa78b770fA6A738034120C302</code></td></tr> <tr><td style="text-align: center">👍🤫😋✊🤪😞🤐👶😭❤👉🚩💔🌱🤝🌊💚🪐🚩😐</td><td style="text-align: center"><code>0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984</code></td></tr> <tr><td style="text-align: center">😆🌎✅✨👋😜💛☺😶👋🐸🤩🌔🙌✋🤤⭐🍑☹⚡</td><td style="text-align: center"><code>0x2a0f713aA953442EacA9EA47083f656170e67BA4</code></td></tr> <tr><td style="text-align: center">🔥🤬🌔😝😞🙄👌💢🗣🌍✨😙🐾😡😑🤘💸😂😤🔵</td><td style="text-align: center"><code>0x23B608675a2B2fB1890d3ABBd85c5775c51691d5</code></td></tr> <tr><td style="text-align: center">🗣😅😞✨🤷😆🌟🐷🌷👶☝🪐🥀🖥🤟🐉💀💪😏❄</td><td style="text-align: center"><code>0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7</code></td></tr> <tr><td style="text-align: center">🥴😆😰✌🤟🔥📣🎵🌖🌏😡🎶💙🐸🍒🌔😱🤘🍀➡</td><td style="text-align: center"><code>0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2</code></td></tr> <tr><td style="text-align: center">▶🌻😥👏💘😛💐💨❄💸😂😪😝🤤🐸💻😟☝🍃🥺</td><td style="text-align: center"><code>0xC18360217D8F7Ab5e7c516566761Ea12Ce7F9D72</code></td></tr> </tbody></table> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>to_emoji</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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> <span class="giallo-l"><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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 class="giallo-l"><span>]</span></span> <span class="giallo-l"><span>from_emoji</span><span class="z-keyword"> =</span><span> {</span><span>emoji</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-constant">{0</span><span class="z-storage z-type">:02x</span><span class="z-constant">}</span><span class="z-punctuation z-definition z-string">&quot;</span><span>.</span><span>format</span><span>(</span><span>i</span><span>)</span><span class="z-keyword"> for</span><span> i</span><span>,</span><span> emoji</span><span class="z-keyword"> in</span><span class="z-support"> enumerate</span><span>(</span><span>to_emoji</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"> encode_address</span><span>(</span><span class="z-variable z-parameter z-function">hexadecimal_address</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>hexadecimal_address</span><span>)</span><span class="z-keyword"> !=</span><span class="z-constant"> 42</span><span class="z-keyword"> or</span><span class="z-keyword"> not</span><span> hexadecimal_address</span><span>.</span><span>startswith</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></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> None</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-punctuation z-definition z-string">&#39;</span><span>.</span><span>join</span><span>(</span><span>[</span><span>to_emoji</span><span>[</span><span class="z-support">int</span><span>(</span><span>hexadecimal_address</span><span>[</span><span>i</span><span>:</span><span>i</span><span class="z-keyword">+</span><span class="z-constant">2</span><span>]</span><span>,</span><span class="z-constant"> 16</span><span>)</span><span>]</span><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span class="z-constant">2</span><span>,</span><span class="z-constant"> 42</span><span>,</span><span class="z-constant"> 2</span><span>)</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">def</span><span class="z-entity z-name"> decode_address</span><span>(</span><span class="z-variable z-parameter z-function">emoji_address</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> In python, these unicode characters all have a len() of 1</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>emoji_address</span><span>)</span><span class="z-keyword"> !=</span><span class="z-constant"> 20</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 class="z-keyword"> try</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-punctuation z-definition z-string"> &#39;</span><span class="z-punctuation z-definition z-string">&#39;</span><span>.</span><span>join</span><span>(</span><span>from_emoji</span><span>[</span><span>emoji</span><span>]</span><span class="z-keyword"> for</span><span> emoji</span><span class="z-keyword"> in</span><span> emoji_address</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> except</span><span class="z-support"> IndexError</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="security-considerations">Security Considerations</h2> <p>With the base256emoji encoding, addresses use half as many characters. The characters used are more distinguishable. This squares the difficulty of generating similar addresses, making address spoofing impractical.</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-27T00:00:00+00:00 2026-02-11T14:49:27+00:00 Diederik Loerakkerhttps://github.com/protolambda https://wg-eips.ritovision.com/7664/

The access-key opcode enables contracts to read inputs that are statically declared in access-lists.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a new opcode to inspect the access-list keys of the executing address.</p> <h2 id="motivation">Motivation</h2> <p>This EIP serves as a substitute of top-level-call detection to enable a smart-contract to enforce static declaration of attributes.</p> <p>Previously, application-layer contracts, against common advice from account-abstraction proponents, used to rely on the <code>tx.origin</code> to enforce a top-level call, such that the contract inputs are encoded as transaction input.</p> <p>While the access-list of transactions directly affects the execution, it only affects the gas-costs. This EIP enhances the access-list feature to provide the property of statically-defined contract-inputs, without relying on top-level calls, the <code>tx.origin</code> behavior, or gas introspection.</p> <p>This enables smart contracts to reliably enforce static declaration of inputs.</p> <p>This is a step towards fulfilling the purposes as described in the Motivation of <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a>:</p> <blockquote> <p>Introduces the access list format and the logic for handling the format. This logic can later be repurposed for many other purposes, including block-wide witnesses, use in ReGenesis, moving toward static state access over time, and more."</p> </blockquote> <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>ACCESS_KEY_OPCODE_GAS</code></td><td><code>3</code></td></tr> <tr><td><code>ACCESS_KEY_OPCODE_BYTE</code></td><td><code>0x4B</code></td></tr> </tbody></table> <h3 id="opcode">Opcode</h3> <p>We add an instruction <code>ACCESS_KEY</code> (with opcode <code>ACCESS_KEY_OPCODE_BYTE</code>) which pops <code>index</code> from the top of the stack as big-endian <code>uint256</code>, and pushes <code>tx.access_list[address][index]</code> back on the stack, if <code>address</code> is present in the <code>tx.access_list</code> and <code>index &lt; len(tx.access_list[address])</code>, and otherwise pushes a zeroed <code>bytes32</code> value.</p> <h3 id="gas-costs">Gas costs</h3> <p>The opcode has a fixed gas cost of <code>ACCESS_KEY_OPCODE_GAS</code>.</p> <p>The intrinsic gas costs of the access-list contents of the transaction itself do not change.</p> <h2 id="rationale">Rationale</h2> <h3 id="static-analysis-of-transactions">Static analysis of transactions</h3> <p>Static declaration of contract-inputs enables advanced layer-two constructions and block-building techniques: data is available without EVM introspection, and contracts can reliably tell if the executing transaction declared critical properties to the block builder and verifying nodes.</p> <p>Static-declaration of contract inputs is now independent of account-abstraction related changes, such as transaction bundlers, as well as in-protocol with 3074.</p> <!-- EIP link/requires omitted due to Walidator EIP status bug --> <h3 id="global-read-only-values">Global read-only values</h3> <p>Akin to <code>TLOAD</code>, as described in <a href="https://wg-eips.ritovision.com/1153/">EIP-1153</a>, the <code>ACCESS_KEY</code> opcode provides contracts with a view that is global to the message-execution of the transaction in the EVM.</p> <p>However, with <code>ACCESS_KEY</code> it is guaranteed to be read-only, and cannot change during the execution of a transaction.</p> <h3 id="access-list-utility">Access-list utility</h3> <p>Access-lists are under-utilized today: very few users utilize this to warm-up storage interactions for reduced gas costs. Generally the gas cost savings achieved with EIP-2930 are not applicable in as many use-cases.</p> <p>With this EIP, the utility of the access-list functionality increases, without requiring additional resources from the EVM.</p> <h3 id="witness-data">Witness data</h3> <p>This EIP supports the transformation of applications to reduce statefulness, by supporting read-only application state to be provided to contracts without requiring the contract caller to support forwarding of data.</p> <p>The access-list contents may contain witness-data, which the contract can verify and utilize statelessness.</p> <h3 id="gas-costs-1">Gas costs</h3> <p>The gas cost of <code>ACCESS_KEY_OPCODE_GAS</code> gas matches that of similar operations, specifically the <code>BLOBHASH</code> opcode of <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>: this opcode also pop an index-like EVM word from the stack, and pushes a full 32 byte EVM word back on the stack, based on a list of hashes embedded in the transaction.</p> <p>The <code>BLOBHASH</code> functionality of <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> is not re-usable for the purposes of this EIP however, as the intention is to have access to just the statically declared hash, and not the cost of a blob.</p> <h3 id="naming-of-access-key">Naming of <code>ACCESS_KEY</code></h3> <p>Access-lists currently only support a list of access-keys. The list is not enforced to be sorted, and thus supports indexed lookups.</p> <p>This is not a <code>LOAD</code> opcode, as <code>SLOAD</code> or <code>TLOAD</code> are, since the opcode returns a key.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <h3 id="no-transaction-type-changes">No transaction-type changes</h3> <p>This enhancement of access-lists utility does not affect the access-list encoding, or the existing transaction types that support access-lists.</p> <h3 id="minimal-impact-on-evm-transaction-context">Minimal impact on EVM transaction-context</h3> <p>With EIP-2930, the access-list contents are already readily available in the transaction-context during EVM execution, and the RPC methods that trigger said execution.</p> <p>This EIP thus does not require significant changes to the construction of the EVM context, nor any changes to RPC methods.</p> <h2 id="test-cases">Test Cases</h2> <p>The block fee-recipient, and any other warmed-up attributes not declared statically in the transaction access-list, must not be considered to be part of the access-list.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The access-list attributes are already gas-metered in EIP-2930, and readily accessible in the EVM to determine storage gas-costs. In terms of denial-of-service risks, this EIP introduces no new significant data or data-processing costs.</p> <p>The access-list is read-only, and thus forms a minimal risk to application-developers.</p> <p>The access is scoped strictly to the contract that would otherwise perform a warm <code>SLOAD</code>, and thus storage-layout abstractions do not leak between different smart contract applications.</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-26T00:00:00+00:00 2026-02-11T14:48:25+00:00 Greg Marlinhttps://github.com/marleymarl https://wg-eips.ritovision.com/7662/

A specification for NFTs that represent AI Agents.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a standard for AI agent NFTs. When AI Agents are created and traded as NFTs, it doesn't make sense to put the prompts in the token metadata, therefore it requires a standard custom struct. It also doesn't make sense to store the prompts directly onchain as they can be quite large, therefore this standard proposes they be stored as decentralized storage URLs. This standard also proposes two options on how this data should be made private to the owner of the NFT, with the favored implementation option being encrypting the data using custom contract parameters for decryption that decrypt only to the owner of the NFT.</p> <h2 id="motivation">Motivation</h2> <p>The creation and trading of AI Agent NFTs are a natural fit and offer the potential for an entirely new onchain market. This requires some custom data to be embedded in the NFT through a custom struct and this needs to be standardized so that any marketplace or AI Agent management product, among others, know how to create and parse AI Agent NFTs. The goal of this standard is to provide a new utility for NFTs in the field of AI and also to provide new liquidity, through the NFT market, for AI Agents. If widely adopted by marketplaces, and infrastructure and no-code providers this should open up a new market and community for AI Agent creators in different fields, AI Agent consumers and NFT marketplaces.</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 ERC-XXXX compliant contracts MUST implement the standard <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> functionality for minting and transferring NFTs, and MUST additionally implement this standard's Agent interface</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7662</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-storage z-type"> function</span><span class="z-entity z-name"> getAgentData</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> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> name</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"> description</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"> model</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"> userPromptURI</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"> systemPromptURI</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> promptsEncrypted</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"> AgentUpdated</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></code></pre> <p>and MUST implement the mapping between NFT Token ID and its Agent information.</p> <p>It is RECOMMENDED that this mapping is public and that the URIs for User Prompt and System Prompt are made private through encryption with decryption logic set to the holder of the NFT via custom contract parameters set during encryption, and the method or platform used to provide this encryption SHOULD be retrievable as a data property of the NFT in order that platforms that should facilitate the use of these NFTs can set up a predictable way to handle this decryption, depending on the platform or method used.</p> <p>It is conceivable to also create an implementation whereby this mapping was set to private and accessed through a custom function that restricted access to the holder of the NFT. This approach would explose the prompts through their urls though, therefore the RECOMMENDED approach is a public mapping and encryption on the URLs. This also has the benefit of publicly exposing the data in the Agent struct to verify name, description and model and that encrypted URIs for the User Prompt and System Prompt exist.</p> <p>All ERC-XXXX compliant contracts MUST implement a function to mint new Agent tokens. This function SHOULD:</p> <ul> <li>Accept parameters for all Agent properties (name, description, model, userPromptURI, systemPromptURI, etc.)</li> <li>Mint a new token to the specified recipient</li> <li>Associate the provided Agent properties with the newly minted token</li> <li>Emit an event signaling the creation of a new Agent token</li> </ul> <p>It is RECOMMENDED that ERC-XXXX compliant contracts provide functionality to encrypt the user prompt and system prompt. This functionality SHOULD:</p> <ul> <li>Allow only the token owner to encrypt the prompts</li> <li>Update the userPromptURI and systemPromptURI with encrypted versions</li> <li>Set a flag indicating that the prompts are encrypted</li> </ul> <p>It is RECOMMENDED to implement the following event:</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"> AgentCreated</span><span>(</span><span class="z-support">string</span><span class="z-variable"> name</span><span>, </span><span class="z-support">string</span><span class="z-variable"> description</span><span>, </span><span class="z-support">string</span><span class="z-variable"> model</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"> tokenId</span><span>)</span></span> <span class="giallo-l"></span></code></pre> <p>This event SHOULD be emitted when a new Agent token is minted, providing key information about the newly created Agent.</p> <p>To enable dynamic variables being injected into the User Prompt before being run, any such variables MUST be surrounded with ${} e.g. ${dynamicVariableName} in order that they can be recognized and handled appropriately by programs and systems that will enabled the injection, e.g. web forms and automation systems.</p> <p>It is RECOMMENDED to add a data to the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard that makes it easy for e.g. NFT Marketplaces to display data about the AI Agent NFT, i.e. Model, which in turn reveals the platform that is used for the agent, e.g. OpenAI in the case of gpt-4-0125-preview or Anthropic in the case of claude-3-opus-20240229. The standard name and description can be used to display the Agent Name and Agent Description.</p> <h2 id="rationale">Rationale</h2> <p>This standard provides a unified way to create and parse AI Agent NFTs.</p> <p>This standard codifies the necessary parameters of Name, Description, Model, User Prompt, and System Prompt for creating and using AI Agent NFTs.</p> <p>It doesn't make practical sense to store the user and system prompts in an existing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> as the only place to put would be in the token metadata that is open for anyone to access the prompts without owning the NFT. By storing the prompts in a custom Agent struct and restricting access to the prompts to the holder of the NFT. One way to do this would be through restricting access to the struct info to the holder of the NFT through a custom function, however since that option still exposes the prompt URIs to the public and thus the data inside them, the recommended method is by encrypting the prompts onchain and tying the decryption of the URLs to the holder of the NFT, using onchain services that enable decryption to be tied to contract parameters such as ownerOf(tokenId).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The AI Agents NFT standard introduces additional features and data to the standard <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> protocol, aimed at addressing the practical requirements of using NFTs to store, trade and use AI Agents. It is designed to be fully backward-compatible with the original <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard. All existing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> functions (such as transferFrom, approve, and balanceOf) retain their original functionality and interfaces. Our extension does not modify these core behaviors, ensuring that any <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> compliant wallet or service can interact with these tokens without modifications.</p> <h3 id="reference-implementation">Reference Implementation</h3> <p>This is being currently implemented in a product for creating, managing and using AI Agents Onchain through a DApp interface. In this implementation, an encryption platform is being used to encrypt the prompts using custom EVMContractParameters that only decrypt for the holder of the NFT and using a decentralized storage network to store the URLs of this encrypted data. To facilitate that and make DApp handling easier, some parameters were added to Agent and the addEncryptedPrompts function is added that enables adding the encrypted prompt URIs after first minting the NFT (as the tokenId of the NFT is needed for setting the encryption/decryption conditions).</p> <p>A reference smart contract is provided in the assets folder.</p> <h2 id="security-considerations">Security Considerations</h2> <!-- TODO --> <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-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Francesco Sullohttps://github.com/sullof https://wg-eips.ritovision.com/7656/

Define a factory for generic services linked to any contract type, including smart accounts and NFTs

<h2 id="abstract">Abstract</h2> <p>This proposal defines a factory capable of deploying generic services linked to specific contracts, such as <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> accounts or <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens (NFTs). These linked services extend the functionalities of the target contract, operating under the ownership of the contract's or NFT's owner without requiring modifications to the original contract's code. This approach enables extending existing contracts with new capabilities while maintaining backward compatibility with deployed instances.</p> <h2 id="motivation">Motivation</h2> <p>Existing projects, like token-bound accounts, successfully bind smart accounts to NFTs, allowing registries to deploy accounts owned by specific token IDs. However, these standards have two key limitations:</p> <ol> <li>They often require deployed contracts to implement specific interfaces for handling assets and executing transactions, effectively mandating that the deployed contract must function as an account.</li> <li>They are restricted to NFTs, while many other contract types (particularly <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> accounts) could benefit from similar linking mechanisms to extend their functionalities.</li> </ol> <p>This ERC proposes a more versatile factory specification that enables the deployment of proxies pointing to any contract that enhances the associated contract's capabilities, whether it's an NFT or an account contract.</p> <h3 id="key-benefits">Key Benefits</h3> <ul> <li> <p><strong>Universal Linkability</strong>: Enables services to be linked to any compatible contract type, not just NFTs, creating a unified approach to contract extension.</p> </li> <li> <p><strong>Non-Invasive Enhancement</strong>: Services can add functionality to existing smart accounts without modifying the underlying contract, maintaining compatibility with infrastructure like wallets and indexers.</p> </li> <li> <p><strong>Backward Compatibility</strong>: Maintains compatibility with existing token-bound accounts while extending functionality to new use cases.</p> </li> <li> <p><strong>Flexible Implementation</strong>: The <code>mode</code> parameter enables different linkage types (with or without token IDs) while ensuring consistent deterministic addressing.</p> </li> <li> <p><strong>Unified Extension Mechanism</strong>: Provides a standardized approach for extending existing contracts with new capabilities, reducing the need for specialized implementations across different use cases.</p> </li> </ul> <h3 id="use-cases-for-erc-4337-smart-accounts">Use Cases for ERC-4337 Smart Accounts</h3> <ol> <li> <p><strong>Social Recovery Services</strong>: Deploy a social recovery mechanism linked to an existing ERC-4337 wallet that can restore access if credentials are lost, without requiring the wallet to implement recovery functionality natively.</p> </li> <li> <p><strong>Customizable Permission Systems</strong>: Add granular permissions to an account (time-limited access, spending limits, multi-signature approvals) without rebuilding the account from scratch.</p> </li> <li> <p><strong>Account Abstraction Extensions</strong>: Implement advanced features like batch transactions, gas sponsorship, or session keys as linked services, allowing wallets to adopt these features selectively.</p> </li> <li> <p><strong>Identity and Reputation Services</strong>: Link verifiable credentials or reputation systems to accounts, enabling privacy-preserving identity verification.</p> </li> </ol> <h3 id="use-cases-for-nfts">Use Cases for NFTs</h3> <ol> <li> <p><strong>Enhanced Token Utility</strong>: Provide NFTs with financial capabilities like staking, lending, or revenue distribution.</p> </li> <li> <p><strong>Dynamic Metadata Services</strong>: Enable NFT metadata to evolve based on on-chain activities without changing the NFT itself.</p> </li> <li> <p><strong>Fractional Ownership</strong>: Implement fractional ownership mechanisms for high-value NFTs through linked contracts.</p> </li> <li> <p><strong>Conditional Access Control</strong>: Create time-locked or challenge-based access to NFT-gated content or services.</p> </li> <li> <p><strong>Real World Asset Management</strong>: Extend NFTs to represent and manage real-world assets (RWAs) by linking services that handle compliance, legal documentation, custody verification, transfer restrictions, and regulatory reporting without requiring specialized NFT standards for each asset class.</p> </li> </ol> <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> <p>The <code>IERC7656Factory</code> interface is defined as follows:</p> <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"> IERC7656Factory</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Created</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> contractAddress</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"> implementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> chainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes12</span><span class="z-variable"> mode</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"> linkedContract</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"> linkedId</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"> error</span><span class="z-entity z-name"> CreationFailed</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"> create</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> implementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> chainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes12</span><span class="z-variable"> mode</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> linkedContract</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> linkedId</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">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"> compute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> implementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> chainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes12</span><span class="z-variable"> mode</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> linkedContract</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> linkedId</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">address</span><span class="z-variable"> service</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="linking-modes">Linking Modes</h3> <p>The <code>mode</code> parameter serves as a selector for how the linked contract should be interpreted and utilized. Currently, <a href="https://wg-eips.ritovision.com/7656/">ERC-7656</a> defines two standard modes:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes12</span><span class="z-storage z-type"> constant</span><span> NO_LINKED_ID </span><span class="z-keyword">=</span><span class="z-constant"> 0x000000000000000000000001</span><span>;</span></span> <span class="giallo-l"><span class="z-support">bytes12</span><span class="z-storage z-type"> constant</span><span> LINKED_ID </span><span class="z-keyword">=</span><span class="z-constant"> 0x000000000000000000000000</span><span>;</span></span></code></pre> <ul> <li> <p><strong>LINKED_ID Mode (0x000000000000000000000000)</strong>: Used when linking a service to an NFT or any contract that requires a token/entity ID. This mode ensures compatibility with existing token-bound account systems.</p> </li> <li> <p><strong>NO_LINKED_ID Mode (0x000000000000000000000001)</strong>: Used when linking a service to a contract that doesn't require an ID parameter, such as an <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> account. In this case, the <code>linkedId</code> parameter is still present in the interface for consistency but SHOULD be set to zero if not used to store alternative data relevant to the service.</p> </li> </ul> <p>The <code>mode</code> parameter (being <code>bytes12</code>) allows for future extensions beyond these initial modes, enabling more complex linkage patterns as ecosystem needs evolve.</p> <h3 id="deployment-requirements">Deployment Requirements</h3> <p>Any <code>ERC7656Factory</code> implementation MUST support the <code>IERC7656Factory</code> interface ID (<code>0x9e23230a</code>).</p> <p>Each linked service MUST be deployed as an <a href="https://wg-eips.ritovision.com/1167/">ERC-1167</a> minimal proxy, appending immutable constant data to the bytecode. The deployed bytecode structure is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>ERC-1167 Header (10 bytes)</span></span> <span class="giallo-l"><span>&lt;implementation (address)&gt; (20 bytes)</span></span> <span class="giallo-l"><span>ERC-1167 Footer (15 bytes)</span></span> <span class="giallo-l"><span>&lt;salt (bytes32)&gt; (32 bytes)</span></span> <span class="giallo-l"><span>&lt;chainId (uint256)&gt; (32 bytes)</span></span> <span class="giallo-l"><span>&lt;mode (bytes12)&gt; (12 bytes)</span></span> <span class="giallo-l"><span>&lt;linkedContract (address)&gt; (20 bytes)</span></span> <span class="giallo-l"><span>&lt;linkedId (uint256)&gt; (32 bytes)</span></span></code></pre> <p><strong>Total bytecode size: 183 bytes</strong></p> <p>Linked services SHOULD implement the <code>IERC7656Service</code> interface:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Interface ID: 0x7e110a1d</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7656Service</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> linkedData</span><span>(</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"> chainId</span><span>,</span><span class="z-support"> bytes12</span><span class="z-variable"> mode</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> linkedContract</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> linkedId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="implementation-patterns">Implementation Patterns</h3> <p>When implementing a linked service, developers SHOULD consider the following patterns:</p> <ol> <li> <p><strong>Ownership Verification</strong>: Services SHOULD include mechanisms to verify that operations are authorized by the current owner of the linked contract or token.</p> </li> <li> <p><strong>Mode-Specific Logic</strong>: Services SHOULD implement conditional logic based on the <code>mode</code> parameter to handle both NFT-linked and account-linked scenarios appropriately.</p> </li> <li> <p><strong>Cross-Chain Awareness</strong>: Services SHOULD check that operations are being performed on the chain specified in the <code>chainId</code> parameter to prevent cross-chain replay attacks.</p> </li> </ol> <h2 id="rationale">Rationale</h2> <p>The design of <a href="https://wg-eips.ritovision.com/7656/">ERC-7656</a> is guided by several key principles that address limitations in current contract extension methods:</p> <h3 id="why-a-unified-factory">Why a Unified Factory?</h3> <p>Rather than creating separate standards for NFT extensions and account extensions, <a href="https://wg-eips.ritovision.com/7656/">ERC-7656</a> employs a unified factory approach. This design choice stems from recognizing the fundamental similarity between linking services to tokens and linking services to accounts - both involve extending functionality while maintaining a clear ownership relationship.</p> <h3 id="mode-parameter-design">Mode Parameter Design</h3> <p>The <code>mode</code> parameter uses 12 bytes instead of a simple boolean flag because the 12-byte format reserves space for future linking modes beyond the initial two (NFT linking and account linking). For example, if a service is associated to an <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> token but requires that the balance of the user is more than 1000 tokens, the mode could be <code>0x000000000000000000003e802</code>, where the least significant byte, <code>0x02</code> is the primary mode and the rest is the minimum required balance. Similarly, someone can think of a service associated to <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens that requires a specific balance where the required balance can be put in the <code>linkedId</code> field, and the <code>mode</code> specified accordingly.</p> <h3 id="deterministic-addressing">Deterministic Addressing</h3> <p><a href="https://wg-eips.ritovision.com/7656/">ERC-7656</a> follows a deterministic addressing pattern, appending immutable data to the contract bytecode rather than storing it in contract storage. This ensures that:</p> <ol> <li>Linked services have predictable addresses that can be computed off-chain</li> <li>The factory remains stateless, reducing gas costs</li> <li>Linked services can be deployed on-demand or even referenced before deployment</li> </ol> <h3 id="generic-linking-mechanism">Generic Linking Mechanism</h3> <p>Unlike standards that enforce specific interfaces or behaviors on linked contracts, <a href="https://wg-eips.ritovision.com/7656/">ERC-7656</a> remains agnostic about the implementation details of linked services. This deliberate design choice allows developers maximum flexibility to create specialized services while maintaining a consistent deployment and ownership model.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><a href="https://wg-eips.ritovision.com/7656/">ERC-7656</a> maintains compatibility with token-bound accounts when used with the <code>LINKED_ID</code> mode (0x000000000000000000000000). This ensures that existing applications and infrastructure supporting token-bound accounts can continue operating without modification.</p> <p>For contracts using the <code>NO_LINKED_ID</code> mode (0x000000000000000000000001), specialized interfaces may be required, but the core factory mechanism remains consistent.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/7656/./assets/ERC7656Factory.sol"><code>ERC7656Factory.sol</code></a> for an example implementation of <code>IERC7656Factory</code>.</p> <p>For convenience, the bytecode of the reference implementation has been deployed at <code>0x76565d90eeB1ce12D05d55D142510dBA634a128F</code> on Ethereum mainnet, and will be later deployed at the same address to all primary mainnets and selected testnets.</p> <p>An example of implementation of <code>IERC7656Service</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"> LinkedService</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7656Service</span><span>, </span><span class="z-entity z-name">EIP5313</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"> linkedData</span><span>(</span><span class="z-support">address</span><span class="z-variable"> service</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 class="z-support"> bytes12</span><span>,</span><span class="z-support"> address</span><span>,</span><span class="z-support"> uint256</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> encodedData </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> bytes</span><span>(</span><span class="z-constant">0x60</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-keyword"> solhint-disable</span><span class="z-comment">-next-line no-inline-assembly</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Copy 0x60 bytes from end of context</span></span> <span class="giallo-l"><span class="z-entity z-name"> extcodecopy</span><span>(</span><span>service</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>encodedData</span><span>,</span><span class="z-constant"> 0x20</span><span>)</span><span>,</span><span class="z-constant"> 0x4d</span><span>,</span><span class="z-constant"> 0x60</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></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"> bytes32</span><span> linkedContract</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> linkedId</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-keyword"> solhint-disable</span><span class="z-comment">-next-line no-inline-assembly</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> chainId </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>encodedData</span><span>,</span><span class="z-constant"> 0x20</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> linkedContract </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>encodedData</span><span>,</span><span class="z-constant"> 0x40</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> linkedId </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>encodedData</span><span>,</span><span class="z-constant"> 0x60</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-support"> bytes12</span><span> mode </span><span class="z-keyword">=</span><span class="z-support"> bytes12</span><span>(</span><span>linkedContract</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> address</span><span> extractedAddress </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span class="z-support">uint160</span><span>(</span><span class="z-support">uint256</span><span>(</span><span>linkedContract</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>chainId</span><span>,</span><span> mode</span><span>,</span><span> extractedAddress</span><span>,</span><span> linkedId</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"> owner</span><span>(</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> (</span><span class="z-support">uint256</span><span> chainId</span><span>,</span><span> ,</span><span class="z-support"> address</span><span> tokenContract_</span><span>,</span><span class="z-support"> uint256</span><span> tokenId_</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> linkedData</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>chainId </span><span class="z-keyword">!=</span><span class="z-variable z-language"> block</span><span>.</span><span>chainid</span><span>)</span><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 class="z-keyword"> return</span><span class="z-entity z-name"> IERC721</span><span>(</span><span>tokenContract_</span><span>)</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></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <h3 id="ownership-cycles">Ownership Cycles</h3> <p>Smart wallets linked to NFTs that are then held by the same wallet can create ownership cycles, potentially rendering assets inaccessible. Implementers should include safeguards to prevent or detect such cycles.</p> <h3 id="fraud-prevention">Fraud Prevention</h3> <p>A malicious seller could alter or revoke service permissions just before finalizing a sale. Lock mechanisms preventing last-minute changes may be implemented, especially for NFT marketplaces integrating with <a href="https://wg-eips.ritovision.com/7656/">ERC-7656</a> services.</p> <h3 id="malicious-implementations">Malicious Implementations</h3> <p>The registry cannot enforce legitimate ownership when linking services. Users should review or audit implementations before deployment. Front-end applications integrating <a href="https://wg-eips.ritovision.com/7656/">ERC-7656</a> should display warnings when interacting with unverified implementations.</p> <h3 id="upgradeability-risks">Upgradeability Risks</h3> <p>Linked services that are upgradable pose risks of unexpected changes or asset exfiltration. Secure upgrade mechanisms with timelock controls or multi-signature governance should be implemented when upgradeability is required.</p> <h3 id="reentrancy-cross-contract-attacks">Reentrancy &amp; Cross-Contract Attacks</h3> <p>Linked services interacting with assets or external protocols may be vulnerable to reentrancy exploits. Implementers should follow security best practices such as the checks-effects-interactions pattern and consider reentrancy guards.</p> <h3 id="mode-specific-vulnerabilities">Mode-Specific Vulnerabilities</h3> <p>Services operating in different modes (<code>LINKED_ID</code> vs <code>NO_LINKED_ID</code>) may have different security requirements. Implementations should validate that operations are appropriate for the service's configured mode.</p> <h3 id="user-education-phishing-risks">User Education &amp; Phishing Risks</h3> <p>Even with secure contracts, users may fall victim to fraudulent services masquerading as legitimate ones. Clear UI warnings, verification tools, and educational resources should be provided by applications integrating <a href="https://wg-eips.ritovision.com/7656/">ERC-7656</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-03-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Rickeyhttps://github.com/HelloRickey https://wg-eips.ritovision.com/7654/

Use a set of request methods to indicate the type of action to take on the contract.

<h2 id="abstract">Abstract</h2> <p>This proposal standardizes a set of request and response communication standards between clients and smart contracts, using POST, GET, and PUT requests to create, read, and update the states of smart contracts. You can customize different request method names, request parameters and response values, and each request method will be mapped to a specific operation.</p> <h2 id="motivation">Motivation</h2> <p>Since each contract has different functions, the client cannot use a standard to call different functions of different contracts. Contract Request Methods redefines the request method of the contract, so that different functions of multiple different contracts can be called using a consistent set of rules and protocols.</p> <p>By dividing the function types into POST, GET, and PUT, different operations can be performed on the contract. This clear operation type can not only help all parties limit the access and operation of contract data, but also effectively simplify the interaction between the client and the contract, making it easier for all parties to understand the functions and hierarchical structure of the contract. The request and response parameter data types of each function of this standard can express the expected operation of the contract and have the ability to describe its own structure, which is conducive to the parties and contracts to create a unified and predictable way of exchanging data.</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>It consists of four request method types:</p> <p><strong>GET</strong>: Request the contract to retrieve records.</p> <p><strong>POST</strong>: Request the contract to create a new record.</p> <p><strong>PUT</strong>: Request the contract to update a record.</p> <p><strong>OPTIONS</strong>: Supported request method types.</p> <p>Workflow:</p> <ol> <li>Call <code>options</code> to obtain supported request method types.</li> <li>Call <code>getMethods</code> to obtain the request method name.</li> <li>Call <code>getMethodInstruction</code> to obtain the request method instruction.</li> <li>Call <code>getMethodReqAndRes</code> to obtain the request parameter data type and response value data type.</li> <li>Encode request parameters and call <code>get</code>, <code>post</code>, and <code>put</code>.</li> <li>Decode response value.</li> </ol> <h3 id="interfaces">Interfaces</h3> <h4 id="irequestmethodtypes-sol"><code>IRequestMethodTypes.sol</code></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"> &gt;=0.8.0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./Types.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IRequestMethodTypes</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"> * Requested method type.</span></span> <span class="giallo-l"><span class="z-comment"> * GET, POST, PUT, OPTIONS</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> MethodTypes</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> GET</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> POST</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> PUT</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> OPTIONS</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"> * Response data 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"> _response</span><span class="z-comment"> is the response value of the post request or put request.</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"> Response</span><span>(</span><span class="z-support">bytes</span><span class="z-variable"> _response</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"> * Get method names based on request method type.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _methodTypes</span><span class="z-comment"> is the request method type.</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"> Method</span><span class="z-comment"> names.</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"> getMethods</span><span>(</span><span class="z-storage z-type">MethodTypes</span><span class="z-variable z-parameter z-function"> _methodTypes</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> <span class="giallo-l"><span class="z-comment"> * Get the data types of request parameters and return parameters based on the requested method 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"> _methodName</span><span class="z-comment"> is the method name.</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"> Data</span><span class="z-comment"> types of request parameters and return parameters.</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"> getMethodReqAndRes</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"> _methodName</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">Types</span><span>.</span><span class="z-support z-variable">Type</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> ,</span><span class="z-storage z-type">Types</span><span>.</span><span class="z-support z-variable">Type</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-comment"> * Get the instruction of method based on the requested method 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"> _methodName</span><span class="z-comment"> is the method name.</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"> instruction</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"> getMethodInstruction</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"> _methodName</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-comment"> * Request the contract to retrieve records.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _methodName</span><span class="z-comment"> is the method 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"> _methodReq</span><span class="z-comment"> is the method type.</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"> response to the get request.</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"> get</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"> _methodName</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"> _methodReq</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> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * Request the contract to create a new 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"> _methodName</span><span class="z-comment"> is the method 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"> _methodReq</span><span class="z-comment"> is the method type.</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"> response to the post request.</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"> post</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"> _methodName</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"> _methodReq</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">bytes</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-comment"> * Request the contract to update a 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"> _methodName</span><span class="z-comment"> is the method 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"> _methodReq</span><span class="z-comment"> is the method type.</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"> response to the put request.</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"> put</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"> _methodName</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"> _methodReq</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">bytes</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-comment"> * Supported request method types.</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"> Method</span><span class="z-comment"> types.</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"> options</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">MethodTypes</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 class="giallo-l"></span></code></pre><h3 id="library">Library</h3> <p>The library <a href="https://wg-eips.ritovision.com/7654/./assets/Types.sol"><code>Types.sol</code></a> contains an enumeration of Solidity types used in the above interfaces.</p> <h2 id="rationale">Rationale</h2> <h3 id="type-of-request-method">Type of request method</h3> <p>In order to enable the client to operate the contract in a standardized and predictable way, three request method types <code>GET</code>, <code>POST</code>, and <code>PUT</code> are set. The functions of each need to be defined in these three types to facilitate the contract caller to understand and process the information required for the request. However, there is no <code>DELETE</code> operation type because deleting data in the contract is an inefficient operation. Developers can add a <code>PUT</code> request method by themselves to set the data to be valid and invalid, and only return valid data in the <code>GET</code> method.</p> <h3 id="request-method-parameter-type">Request method parameter type</h3> <p>Some functions are defined in each request method type. They all include request parameter data type and response parameter data type, which need to be set in the <code>constructor</code> and then obtained according to the method name through <code>getMethodReqAndRes</code>. The data type of the parameter is defined by the enumeration of the data type. When processing the request parameter, <code>abi.decode</code> is used to decode according to the request parameter type and the request value. When returning the response, <code>abi.encode</code> is used to encode according to the response value and the response parameter type. In addition, we can get the method usage instructions by calling <code>getMethodInstruction</code>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/7654/./assets/RequestMethodTypes.sol">Request Method Types Example</a></p> <h2 id="security-considerations">Security Considerations</h2> <p>Contract request methods are divided into safe methods and unsafe methods. If the method request is a read-only operation and will not change the state of the contract, then the method is safe.</p> <p><strong>Safe Methods:</strong> GET, OPTIONS<br /> <strong>Unsafe Methods:</strong> POST, PUT</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-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Liu.C.Daohttps://github.com/CDaoiunknow@163.com Sam1047180870@qq.com https://wg-eips.ritovision.com/7652/

Allow NFT holders to exchange their NFTs for circulating tokens at any time

<h2 id="abstract">Abstract</h2> <p>This specification defines functions outlining a guarantor role for instance of <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>. The guarantee interface implements the user-set valuation and guarantee share for a given NFT (token ID), as well as the guarantee rights enjoyed and obligations assumed during subsequent transactions. An implementation enables the user to read or set the current guarantee value for a given NFT (token ID), and also realizes the distribution of guarantee interest and the performance of guarantee obligations. It sends the standardized events when the status changes. This proposal relies on and extends the existing <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>.</p> <h2 id="motivation">Motivation</h2> <p>NFT (token ID) commonly face the issue of insufficient market liquidity: the main reason being the lack of transparency in NFT pricing, making it difficult for users to cash out after trading and purchasing NFT (token ID).</p> <p>With the introduction of the guarantor role, different guarantor groups can offer various price guarantees for NFT (token ID), establishing a multi-faceted price evaluation system for NFT (token ID).</p> <p>After purchasing an NFT (token ID), users can return it to the guarantor at any time at the highest guaranteed price to protect their interests.</p> <p>Additionally, after fulfilling their guarantee obligations, the guarantor can also request subsequent guarantors to provide guarantee obligations.</p> <p>When an NFT (token ID) is owned by the guarantor, and since the guarantor can be a DAO organization, this expansion allows the NFT (token ID) to continue operating as a DAO, thus further enhancing the social or community recognition of the NFT (token ID).</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>Every contract compliant to the <code>ERC721Guarantee</code> MUST implement the <code>IERC721Guarantee</code> guarantee interface.</p> <p>The <strong>guarantee extension</strong> is OPTIONAL for EIP-721 contracts.</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.20</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> import {IERC721} from &quot;@openzeppelin/contracts/token/ERC721/IERC721.sol&quot;;</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-721 Guarantor Role extension</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-keyword"> Note</span><span class="z-comment">: the EIP-165 identifier for this interface is</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"> IERC721Guarantee</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Emitted when `guarantee contract` is established for 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"> user</span><span class="z-comment"> address of guarantor</span></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 guarantee value provided by dao</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> DAO</span><span class="z-comment"> DAO organization providing guarantee</span></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"> Guaranteed NFT (token ID),</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> GuaranteeIsEstablshed</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> user</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"> address</span><span class="z-variable"> DAO</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"> Emitted when `guarantee contract` is canceled</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Some users in the closed DAO request a reduction in their guarantee share</span></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 guarantor</span></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 guarantee value provided by dao</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> DAO</span><span class="z-comment"> DAO organization providing guarantee</span></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"> Guaranteed NFT (token ID),</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> GuaranteeIsCancel</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> user</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"> address</span><span class="z-variable"> DAO</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"> Emitted when `Guarantee sequence` is established for 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"> userGuaranteed</span><span class="z-comment"> address of guaranteed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> number</span><span class="z-comment"> block.number of transaction,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and all DAOs established before this point will enter the guarantee sequence</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> DAOs</span><span class="z-comment"> DAO sequence providing guarantee</span></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"> Guaranteed NFT (token ID),</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> GuaranteeSequenceIsEstablshed</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> userGuaranteed</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> number</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> DAOs</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"> A user&#39;s evaluation for an NFT (token ID)</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 guarantee information for one guarantor,</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"> value</span><span class="z-comment"> user&#39;s evaluation for an NFT, the oledr value is canceled,</span></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 guarantor</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> weight</span><span class="z-comment"> guarantee weight for guarantor</span></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</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"> error status of function execution</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setNFTGuarantedInfo</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"> address</span><span class="z-variable"> user</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> weight</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-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"> Establish guarantee sequence for an NFT (token ID) and split the commission</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Each NFT(token ID) retains a current guarantee sequence,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and expired guarantee sequences are no longer valid,</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"> valueCommission</span><span class="z-comment"> Commission for a transactions</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> userGuaranteed</span><span class="z-comment"> address of guaranteed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> number</span><span class="z-comment"> block.number of transaction,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and all DAOs established before this point will enter the guarantee sequence</span></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</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"> error status of function execution</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> establishNFTGuarantee</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> valueCommission</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> userGuaranteed</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> number</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-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"> Transactions that fulfill the guarantee responsibility</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The new accountability transaction also requires</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the construction of a new guarantee sequence</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Throws if `_tokenId` is not a valid NFT or userGuaranteed is not right</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"> userGuaranteed</span><span class="z-comment"> address of guaranteed</span></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</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"> error status of function execution</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> FulfillGuaranteeTransfer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> userGuaranteed</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-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><h2 id="rationale">Rationale</h2> <p>Key factors influencing the standard:</p> <ul> <li>Pay attention to ensuring fairness between and within groups when allocating commissions</li> <li>Keeping the number of guarantee groups (DAOs)in the interfaces to prevent contract bloat</li> <li>The guarantee group is a DAO contract, which MUST implement the <code>ERC721TokenReceiver</code> interface</li> <li>Simplicity</li> <li>Gas Efficiency</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with current EIP-721 standards. There are no other standards that define a similar role for NFTs and the name (Guarantor) is not used by other EIP-721 related standards.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation will be provided later.</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-03-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 Acmehttps://github.com/0xacme Calderhttps://github.com/caldereth https://wg-eips.ritovision.com/7651/

A specification for fractionally represented non-fungible tokens.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a standard for fractionally represented non-fungible tokens, allowing NFTs to be managed and owned fractionally within a single contract. This approach enables NFTs to coexist with an underlying fungible representation seamlessly, enhancing liquidity and access without dividing the NFT itself, or requiring an explicit conversion step. The standard includes mechanisms for both fractional and whole token transfers, approvals, and event emissions. This specification draws from design in both <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, but is not fully compatible with either standard.</p> <h2 id="motivation">Motivation</h2> <p>Fractional ownership of NFTs has historically relied on external protocols that manage division and reconstitution of individual NFTs into fractional representations. The approach of dividing specific NFTs results in fragmented liquidity of the total token supply, as the fractional representations of two NFTs are not equivalent and therefore must be traded separately. Additionally, this approach requires locking of fractionalized NFTs, preventing free transfer until they are reconstituted.</p> <p>This standard offers a unified solution to fractional ownership, aiming to increase the liquidity and accessibility of NFTs without compromising transferability or flexibility.</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="fractionally-represented-non-fungible-token-interface">Fractionally Represented Non-Fungible Token Interface</h3> <p>All <a href="https://wg-eips.ritovision.com/7651/">ERC-7651</a> compliant contracts MUST implement the ERC-7651 and <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interfaces.</p> <p>Compliant contracts MUST emit fractional Approval or Transfer events on approval or transfer of tokens in fractional representation.</p> <p>Compliant contracts MUST additionally emit non-fungible ApprovalForAll, Approval or Transfer on approval for all, approval, and transfer in non-fungible representation.</p> <p>Note that this interface draws from similarly defined functions in the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standards, but is not fully backwards compatible with either.</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"> IERC7651</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 fractional representation approval for a given spender</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.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FractionalApproval</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 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 fractionally represented tokens changes</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> by any mechanism. This event emits when tokens are both created and destroyed,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ie. when from and to are assigned to the zero address respectively.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FractionalTransfer</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"> 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 operator is enabled or disabled for an owner.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The operator can manage all NFTs of the owner.</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> <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"> 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 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 spender is </span><span class="z-keyword">changed</span><span class="z-comment"> or reaffirmed for a given NFT.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> A zero address emitted as spender implies that no addresses are approved for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> this token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> NonFungibleApproval</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-storage z-type"> indexed</span><span class="z-variable"> id</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 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 both created and destroyed, ie. when</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> from and to are assigned to the zero address respectively.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> NonFungibleTransfer</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>;</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"> Decimal places in fractional representation</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Decimals are used as a means of determining when balances or amounts</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> contain whole or purely fractional components</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 decimal places used in fractional representation</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"> 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 class="z-variable"> decimals</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 total supply of a token in fractional representation</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The total supply of NFTs may be recovered by computing</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `totalSupply() / 10 ** decimals()`</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"> Total</span><span class="z-comment"> supply of the token in fractional representation</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"> 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"> totalSupply</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"> Balance of a given address in fractional representation</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The total supply of NFTs may be recovered by computing</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `totalSupply() / 10 ** decimals()`</span></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"> The address that owns the 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"> Balance</span><span class="z-comment"> of a given address in fractional representation</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 class="z-variable"> balance</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"> owner_</span><span class="z-comment"> The address that owns the NFTs</span></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 being checked for approval to act on behalf 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"> True</span><span class="z-comment"> if `operator_` is an approved operator for `owner_`, false otherwise</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> <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"> address</span><span class="z-variable"> operator_</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 class="z-variable"> isApproved</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 the allowed amount an address can spend 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"> owner_</span><span class="z-comment"> The address that owns tokens in fractional representation</span></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 being checked for allowance to spend on behalf 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"> amount of tokens `spender_` is approved to spend on behalf of `owner_`</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> <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"> address</span><span class="z-variable"> spender_</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"> allowance</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 the owner of a specific NFT.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Tokens owned by the zero address are considered invalid and should revert on</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ownership query.</span></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 unique 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 token&#39;s owner.</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"> 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 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 class="z-storage z-type"> @notice</span><span class="z-comment"> Set approval for an address to spend a fractional amount,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> or to spend a specific NFT.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> There must be no overlap between valid ids and fractional values.</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 `msg.sender` is the current NFT owner, or an authorized</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> operator of the current owner if an id is provided.</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 id 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"> spender_</span><span class="z-comment"> The spender of a given token or 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"> amountOrId_</span><span class="z-comment"> A fractional value or id to approve.</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 approval operation was successful or not.</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> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> spender_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amountOrId_</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"> @notice</span><span class="z-comment"> Set approval for a third party to manage all of the callers</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> non-fungible assets</span></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 callers authorized operator 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"> approved_</span><span class="z-comment"> True if the operator is approved, false if not approved</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"> 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"> Transfer fractional tokens or an NFT from one address to another</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> There must be no overlap between valid ids and fractional values</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The operation should revert if the caller is not `from_` or is not approved</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> to spent the tokens or NFT owned by `from_`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The operation should revert if value is less than the balance of `from_` or</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> if the NFT is not owned by `from_`</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 id 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"> from_</span><span class="z-comment"> The address to transfer fractional tokens or an NFT from</span></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 transfer fractional tokens or an NFT 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"> amountOrId_</span><span class="z-comment"> The fractional value or a distinct NFT id to transfer</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 operation was successful</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"> amountOrId_</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"> @notice</span><span class="z-comment"> Transfer fractional tokens from one address to another</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The operation should revert if amount is less than the balance of `from_`</span></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 transfer fractional tokens 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"> amount_</span><span class="z-comment"> The fractional value to transfer</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 operation was successful</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"> 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 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"> @notice</span><span class="z-comment"> Transfers the ownership of an NFT from one 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 unless `msg.sender` is the current owner, an authorized</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> operator, or the approved address for this 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 `from_` is not 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"> Throws if `to_` is the zero 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 `tokenId_` is not a valid NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> When transfer is complete, this function checks if `to_` is a</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> smart contract (code size &gt; 0). If so, it calls `onERC721Received`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> on `to_` and throws if the return value is not</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `bytes4(keccak256(&quot;onERC721Received(address,uint256,bytes)&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"> from_</span><span class="z-comment"> The address to transfer the NFT from</span></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 transfer the NFT 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"> tokenId_</span><span class="z-comment"> The NFT 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"> data_</span><span class="z-comment"> Additional data with no specified format, sent in call to `to_`</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> <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"> id_</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>;</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"> Transfers the ownership of an NFT from one 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"> This is identical to the above function safeTransferFrom interface</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> though must pass empty bytes as data 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"> The address to transfer the NFT from</span></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 transfer the NFT 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"> tokenId_</span><span class="z-comment"> The NFT to transfer</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"> 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 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><h3 id="fractionally-represented-non-fungible-token-metadata-interface">Fractionally Represented Non-Fungible Token Metadata Interface</h3> <p>This is a RECOMMENDED interface, identical in definition to the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> Metadata Interface. Rather than using this interface directly, a distinct metadata interface should be used here to avoid confusion surrounding ERC-721 inheritance. Given function definitions here are identical, it's important to note that the ERC-165 <code>interfaceId</code> will be identical between metadata interfaces for this specification and that of ERC-721.</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-7651 Fractional Non-Fungible Token Standard, optional metadata extension</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7651Metadata</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, long-form name for a given token collection</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 class="z-variable"> 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, short-form name for a given token collection</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 class="z-variable"> symbol</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"> A distinct Uniform Resource Identifier (URI) for a given asset.</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. URIs are defined in RFC</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 3986. The URI may point to a JSON file that conforms to the &quot;ERC721</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Metadata JSON Schema&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"> id_</span><span class="z-comment"> The NFT to fetch a token URI 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"> token&#39;s URI as a string</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"> 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">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> uri</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="fractionally-represented-non-fungible-token-banking-interface">Fractionally Represented Non-Fungible Token Banking Interface</h3> <p>This is a RECOMMENDED interface that is intended to be used by implementations of <a href="https://wg-eips.ritovision.com/7651/">ERC-7651</a> that implement NFT ID reuse.</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"> IERC7651NFTBanking</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 number of NFTs that have been minted but are not currently owned.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This should be the number of unowned NFTs, limited by the total</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> fractional supply.</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 NFTs not currently owned.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getBankedNFTsLength</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"> bankedNFTsLength</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 paginated list of NFTs that have been minted but are not currently owned.</span></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 index in bank.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> count_</span><span class="z-comment"> Number of tokens to return from start index, inclusive.</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"> array of banked NFTs from `start_`, of maximum length `count_`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getBankedNFTs</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> start_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> count_</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 class="z-storage z-type"> memory</span><span class="z-variable"> bankedNFTs</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 the current supply of NFTs in circulation.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Given supply may remain banked or unminted, this function should always be</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> inclusively upper-bounded by `totalSupply() / 10 ** decimals()`.</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"> current supply of minted NFTs</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalNonFungibleSupply</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-variable">unit256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="fractionally-represented-non-fungible-token-transfer-exemptable-interface">Fractionally Represented Non-Fungible Token Transfer Exemptable Interface</h3> <p>This is a RECOMMENDED interface that is intended to be used by implementations of <a href="https://wg-eips.ritovision.com/7651/">ERC-7651</a> that want to allow users to opt-out of NFT transfers.</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"> IERC7651NFTTransferExemptable</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 whether an address is NFT transfer exempt.</span></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 to check.</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 address is NFT transfer exempt.</span></span> <span class="giallo-l"><span class="z-entity z-name"> isNFTTransferExempt</span><span>(</span><span class="z-support">address</span><span> 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">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"> Allows an address to set themselves as NFT transfer exempt.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> isExempt_</span><span class="z-comment"> The flag, true being exempt and false being non-exempt.</span></span> <span class="giallo-l"><span class="z-entity z-name"> setSelfNFTTransferExempt</span><span>(</span><span class="z-support">bool</span><span> isExempt_</span><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> <p>This standard unifies the representation of fractional ownership with the non-fungible token model, aligning closely with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> principles while enabling the functionality of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> transfers. This dual compatibility aims to mitigate the integration complexity for existing protocols. Our goal is to implicitly support as high a degree of backwards compatibility with ERC-20 and ERC-721 standards as possible to reduce or negate integration lift for existing protocols. The core rationale for this fractional NFT standard centers on two main strategies: first, designing interfaces that clearly align with either ERC-721 or ERC-20 standards to avoid ambiguity; and second, detailing implementation approaches that distinctly separate the logic of overlapping functionalities.</p> <h3 id="id-amount-isolation">ID &amp; Amount Isolation</h3> <p>Ensuring clear differentiation between token IDs and fractional amounts is central to this design. This non-overlapping design principle means that no input should be ambiguously interpreted as both an ID and an amount. We won't dive into implementation guidelines, but implementations may achieve this through various means, such as validating ownership for ID inputs or reserving specific ranges for token IDs.</p> <p>This approach ensures that logic in "overlapping" interfaces is similarly isolated, such that the chance of an unexpected outcome is minimized.</p> <h3 id="events">Events</h3> <p>The overlap of event signatures between the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standards presents a challenge for backward compatibility in our fractional NFT standard. Various approaches have been explored, including aligning with a single standard's events or introducing unique events with distinct parameter indexing to resolve conflicts.</p> <p>We feel that when moving towards standardization, ensuring events are properly descriptive and isolated is the ideal solution despite introducing complexity for indexing software. As a result, we adhere to traditional transfer and approval event definitions, though distinguish these events by the <code>Fractional</code> or <code>NonFungible</code> prefixes.</p> <h3 id="transfers">Transfers</h3> <p>In a standard <a href="https://wg-eips.ritovision.com/7651/">ERC-7651</a> transfer, value can be transferred by specifying either a fractional amount or a specific NFT ID.</p> <p>NFT ID Transfers: Transferring by NFT ID is straightforward. The specified NFT, along with its entire associated fractional value (equivalent to 10 ** decimals()), is transferred from the sender to the recipient.</p> <p>Fractional Amount Transfers: Transferring fractional amounts introduces complexity in managing NFT allocations. There are three main scenarios:</p> <ol> <li>No change in whole token balance: If the transfer does not change the overall balance of either party, NFT allocations remain unchanged.</li> <li>Sender's whole token balance decreases: If the sender's overall balance decreases below the nearest whole number, a proportionate number of NFTs must be removed from their holdings.</li> <li>Receiver's whole token balance increases: Conversely, if the receiver's overall balance increases above the nearest whole number, their NFT holdings must be proportionately increased.</li> </ol> <p>While <a href="https://wg-eips.ritovision.com/7651/">ERC-7651</a> provides a broad framework for fractional NFTs, it does not prescribe specific methods for handling these scenarios. Common practices include monotonically minting or burning tokens to reflect changes, or tracking NFT ownership with a stack or queue during transfers of fractional amounts.</p> <h3 id="nft-transfer-exemption">NFT Transfer Exemption</h3> <p>Transferring fractional amounts means that a large number of NFTs can be moved in a single transaction, which can be costly in gas usage. We recommend an optional opt-in mechanism for exemption from NFT transfers that both EOAs and contracts can use to reduce the gas burden of transferring large token amounts when the NFT representation is not needed.</p> <p>When executing the function call to either opt-in or opt-out of NFT transfers, NFTs held by the address will be directionally rebalanced to ensure they stay in sync with the new exemption status. In other words, when opting-out of NFT transfers, an address's NFTs will be banked and their NFT balance set to 0. When opting-in to NFT transfers, sufficient NFTs will be pulled from the bank and transferred to the address to match their fractional token balance.</p> <h3 id="nft-banking">NFT Banking</h3> <p>As discussed in the Transfers section, when an address newly gains a full token in fractional terms, they are consequently owed an NFT. Similarly, when an address drops below a full token in fractional terms an NFT must be removed from their balance to stay in sync with their fractional balance.</p> <p>The NFT banking mechanism provides a space in which un-owned but available NFTs relative to supply are tracked. We remain unopinionated on implementation here, but want to provide a handful of examples that would fit specification.</p> <p>One approach to reconcile the bank is by monotonically burning and minting NFT IDs as they are pulled from and added back to circulation, respectively. The minting portion of this strategy can incur significant gas costs that are generally not made up for by the slight gas refund of deleting storage space for burnt token IDs. This approach additionally introduces inflexibility for collections that desire a persistent, finite ID space.</p> <p>An alternate implementation of <a href="https://wg-eips.ritovision.com/7651/">ERC-7651</a> includes a mechanism to store and reuse IDs rather than repeatedly burning and minting them. This saves significant gas costs, and has the added benefit of providing a predictable and externally readable stream of token IDs that can be held in a queue, stack or other data structure for later reuse. The specific data structure used for this banking mechanism is immaterial and is left at the discretion of any implementations adhering to the standard.</p> <h3 id="erc-165-interface">ERC-165 Interface</h3> <p>We include the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface in specification both to adhere to <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> design philosophy, and as a means of exposing interfaces at the contract level. We see this as a valuable, accepted standard to adhere to such that integrating applications may identify underlying specification.</p> <p>Note that <a href="https://wg-eips.ritovision.com/7651/">ERC-7651</a> contracts should not make any claim through <code>supportsInterface</code> to support <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> or <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standards as, despite strong backwards compatibility efforts, these contracts cannot fully adhere to existing specifications.</p> <h3 id="metadata">Metadata</h3> <p>In-line with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, we've decided to isolate replicated metadata functionality through a separate interface. This interface includes traditional naming and token URI logic, though also introduces patterns surrounding token banking visibility, as outlined above in both the NFT Banking and Transfer Logic sections.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The fractional non-fungible token standard aims to be nearly backwards compatible with existing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standards, though makes no claim to fully adhere to either and has as such been proposed through a distinct interface.</p> <h3 id="events-1">Events</h3> <p>Events in <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> specifications share conflicting signatures on approval and transfer, meaning an adherent hybrid of the two cannot be achieved.</p> <p>This is one of the few areas where backwards compatibility has been intentionally broken, resulting in a new series of events with either a <code>Fractional</code> or <code>NonFungible</code> prefix. We believe that a decisive move to a non-conflicting, descriptive solution is ideal here, though will require external lift for indexing software.</p> <h3 id="balanceof">balanceOf</h3> <p>The <code>balanceOf</code> function as defined in both <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standards varies, in practice, to represent either fractional or whole token ownership respectively. Given fractional non-fungible tokens should adhere to an underlying fractional representation, it follows that this function should return a balance in that representation. This does, however, imply that fractional NFT contracts cannot fully adhere to the <code>balanceOf</code> specification provided by ERC-721.</p> <h3 id="success-return-values">Success Return Values</h3> <p>The <code>transfer</code> and <code>approve</code> functions both return a boolean value indicating success or failure. This is non-standard for the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> specification, though is standard for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. Fractional non-fungible tokens adhere to a returned boolean value to meet minimum expectations for the ERC-20 standard, acknowledging that this deviates from a state of ideal backwards compatibility.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="interface-misinterpretation">Interface Misinterpretation</h3> <p>This section is placeholder for further discussion surrounding the misidentification of <a href="https://wg-eips.ritovision.com/7651/">ERC-7651</a> as being either ERC-20 or ERC-721. Namely, discussion surrounding potential security implications of interface misinterpretation need to be thoroughly considered.</p> <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-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-03-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Chen Liaoyuanhttps://github.com/chenly https://wg-eips.ritovision.com/7644/

Extend a time-limited unique name to each token within ERC-721, utilizing the name registry for registration and management.

<h2 id="abstract">Abstract</h2> <p>This extension defines an interface that adds a naming mechanism to <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens. It allows each token to have a unique name with a set expiration date, ensuring uniqueness within the current NFT contract. The interface includes functions for assigning, updating, and querying names and their associated tokens, ensuring that names remain unique until they expire. The entity responsible for setting names depends on the specific use case scenario when utilizing this extension.</p> <h2 id="motivation">Motivation</h2> <p>As decentralized domain registration methods evolve with the integration of NFTs, we see an opportunity to extend this paradigm to the realm of usernames. By associating token IDs with usernames, we enhance the intuitive identification of entities within decentralized ecosystems.</p> <p>This integration serves multiple purposes:</p> <ul> <li> <p><strong>Intuitiveness:</strong> Numeric token IDs lack intuitive identification. By incorporating usernames, token IDs become more representative, improving usability.</p> </li> <li> <p><strong>Username Economy Exploration:</strong> The registration mechanism opens avenues for exploring the username economy, offering benefits such as identity verification and social interactions.</p> </li> <li> <p><strong>Synergy with NFTs:</strong> The fusion of usernames with NFTs unlocks synergistic growth, enabling novel applications like authenticated social interactions and personalized digital assets.</p> </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>Implementers of this extension <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">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">@title</span><span class="z-comment"> INameRegistry</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 the NameRegistry smart contract.</span></span> <span class="giallo-l"><span class="z-comment"> * This interface allows interaction with a NameRegistry, </span></span> <span class="giallo-l"><span class="z-comment"> * enabling the registration, management, and lookup of names </span></span> <span class="giallo-l"><span class="z-comment"> * with associated expiry dates tied to specific tokens.</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"> IERC7644</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> <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 name of a token is </span><span class="z-keyword">changed</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"> tokenId</span><span class="z-comment"> The token ID whose name is </span><span class="z-keyword">changed</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"> oldName</span><span class="z-comment"> The previous name of 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"> newName</span><span class="z-comment"> The new name assigned to 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"> expiryDate</span><span class="z-comment"> The expiry date of the new name registration.</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"> NameChanged</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"> oldName</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> newName</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> expiryDate</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 name of the specified token, if the name has not 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 token ID to query for its name.</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 token, or an empty bytes32 if no name is set or it has expired.</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"> nameOf</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"> Returns the token ID associated with a given name, if the name registration has not 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"> _name</span><span class="z-comment"> The name to query for its associated 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"> The</span><span class="z-comment"> token ID associated with the name, or zero if no token is found or the name has expired.</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"> tokenIdOf</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">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">@dev</span><span class="z-comment"> Allows a token owner to set or update the name of their token, subject to a duration for the name&#39;s validity.</span></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 whose name is to be set or updated.</span></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 new name to assign to 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"> duration</span><span class="z-comment"> The duration in seconds for which the name is valid, starting from the time of calling this function.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">Note</span><span class="z-comment">: The name must be unique and not currently in use by an active (non-expired) registration.</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"> setName</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 z-parameter z-function"> _name</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> duration</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 tokenId and expiryDate for a given name, if the name registration has not 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"> _name</span><span class="z-comment"> The name to query for its associated token ID and expiry date.</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 token ID associated with the name.</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"> expiryDate</span><span class="z-comment"> The expiry date of the name registration.</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"> nameInfo</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">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> expiryDate</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> <h4 id="name-expiry">Name Expiry</h4> <p>By implementing expiration periods for usernames, we introduce several advantages. This mechanism ensures a dynamic environment where unused or outdated usernames can be released, fostering a healthy ecosystem. It encourages turnover of usernames, preventing long-term hoarding and promoting active participation. Users are motivated to manage their username portfolio, renewing valuable names while relinquishing irrelevant ones. Ultimately, this fosters fairness and efficiency, ensuring naming resources are utilized effectively and refreshed to meet evolving needs.</p> <h4 id="name-uniqueness">Name Uniqueness</h4> <p>Enforcing unique usernames is crucial for maintaining a clear and intuitive identification system. It prevents confusion and enables seamless interactions within decentralized ecosystems. Unique usernames enhance discoverability and facilitate trust in transactions and social interactions. This requirement underscores the importance of clarity in decentralized environments, where precise identification is essential for building trust and facilitating efficient interactions.</p> <h4 id="name-registration-system">Name Registration System</h4> <p>Introducing a registration system for usernames safeguards against abusive behaviors and promotes fair access to naming resources. Reservation and renewal mechanisms prevent monopolization of desirable usernames while enabling legitimate users to secure names of interest. Reservation ensures fair opportunities to claim desired usernames, preventing hoarding and speculative activities. Renewal mechanisms encourage active engagement and investment in the naming ecosystem. Together, these features create a balanced and inclusive environment, fostering a vibrant community of users.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is fully <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> compatible.</p> <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.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/ERC721.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"> ERC7644</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-storage z-type"> event</span><span class="z-entity z-name"> NameChanged</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"> oldName</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> newName</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> expiryDate</span><span>)</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"> NameRegistration</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 class="z-support"> uint256</span><span> expiryDate</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"> 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 class="z-storage z-type"> private</span><span> _tokenNames</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> NameRegistration</span><span>)</span><span class="z-storage z-type"> private</span><span> _nameRegistrations</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"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> _lastSetNameTime</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 class="z-storage z-type"> constant</span><span> MAX_DURATION </span><span class="z-keyword">=</span><span class="z-constant"> 10</span><span class="z-keyword"> *</span><span class="z-constant"> 365</span><span class="z-constant"> days</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> MIN_SET_NAME_INTERVAL </span><span class="z-keyword">=</span><span class="z-constant"> 1</span><span class="z-constant"> days</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-entity z-name"> ERC721</span><span>(</span><span>&quot;Asd Token&quot;, &quot;ASDT&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"> nameOf</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-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>_tokenNames</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> !=</span><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword"> &amp;&amp;</span><span> _nameRegistrations</span><span>[</span><span>_tokenNames</span><span>[</span><span>tokenId</span><span>]</span><span>]</span><span>.</span><span>expiryDate </span><span class="z-keyword">&gt;</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _tokenNames</span><span>[</span><span>tokenId</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-support"> bytes32</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> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenIdOf</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"> 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"> require</span><span>(</span><span>_nameRegistrations</span><span>[</span><span>_name</span><span>]</span><span>.</span><span>expiryDate </span><span class="z-keyword">&gt;</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</span><span>,</span><span class="z-string"> &quot;NameRegistry: Name expired&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>_nameRegistrations</span><span>[</span><span>_name</span><span>]</span><span>.</span><span>tokenId </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 class="z-keyword"> return</span><span> _nameRegistrations</span><span>[</span><span>_name</span><span>]</span><span>.</span><span>tokenId</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-support"> uint256</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> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setName</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 z-parameter z-function"> _name</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> duration</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">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;NameRegistry: Caller is not the token owner&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>duration </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> MAX_DURATION</span><span>,</span><span class="z-string"> &quot;NameRegistry: Duration exceeds maximum limit&quot;</span><span>)</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>timestamp </span><span class="z-keyword">-</span><span> _lastSetNameTime</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> &gt;</span><span class="z-keyword">=</span><span> MIN_SET_NAME_INTERVAL</span><span>,</span><span class="z-string"> &quot;NameRegistry: Minimum interval not met&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">tokenIdOf</span><span>(</span><span>_name</span><span>)</span><span class="z-keyword"> ==</span><span class="z-support"> uint256</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword"> ||</span><span class="z-entity z-name"> tokenIdOf</span><span>(</span><span>_name</span><span>)</span><span class="z-keyword"> ==</span><span> tokenId</span><span>,</span><span class="z-string"> &quot;NameRegistry: Name already in use and not expired&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> oldName </span><span class="z-keyword">=</span><span> _tokenNames</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> expiryDate </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> duration</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setTokenName</span><span>(</span><span>tokenId</span><span>,</span><span> _name</span><span>,</span><span> expiryDate</span><span>)</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"> NameChanged</span><span>(</span><span>tokenId</span><span>,</span><span> oldName</span><span>,</span><span> _name</span><span>,</span><span> expiryDate</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _lastSetNameTime</span><span>[</span><span>tokenId</span><span>]</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> }</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"> nameInfo</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"> 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 class="z-support"> uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_nameRegistrations</span><span>[</span><span>_name</span><span>]</span><span>.</span><span>tokenId </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span class="z-keyword"> &amp;&amp;</span><span> _nameRegistrations</span><span>[</span><span>_name</span><span>]</span><span>.</span><span>expiryDate </span><span class="z-keyword">&gt;</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</span><span>,</span><span class="z-string"> &quot;NameRegistry: Name expired or does not exist&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> NameRegistration </span><span class="z-storage z-type">memory</span><span> registration </span><span class="z-keyword">=</span><span> _nameRegistrations</span><span>[</span><span>_name</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>registration</span><span>.</span><span>tokenId</span><span>,</span><span> registration</span><span>.</span><span>expiryDate</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"> _setTokenName</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 z-parameter z-function"> _name</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> expiryDate</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span> _tokenNames</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span> _name</span><span>;</span></span> <span class="giallo-l"><span> _nameRegistrations</span><span>[</span><span>_name</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> NameRegistration</span><span>(</span><span>tokenId</span><span>,</span><span> expiryDate</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> <h4 id="mitigating-abusive-behaviors-and-resource-hoarding">Mitigating Abusive Behaviors and Resource Hoarding</h4> <p>The design includes mechanisms to prevent abusive behaviors and resource hoarding. Minimum intervals for name setting and maximum durations for name expiry are established to deter spam and malicious attacks, limit rapid consecutive name registrations, and encourage fair and efficient use of naming resources. These measures mitigate potential security risks, ensuring names cannot be monopolized indefinitely and promoting a sustainable and equitable environment for all users.</p> <h4 id="username-restrictions">Username Restrictions</h4> <p>To facilitate indexing and gas efficiency, usernames should adhere to a length constraint of 3 to 32 characters. This range prevents the registration of overly long names, which can be costly in terms of gas and difficult to manage. Limiting characters to the range of [a-zA-Z0-9] enhances readability and prevents the abuse of the naming system by restricting the use of special characters that could complicate domain resolution or user recognition. Implementing these constraints not only promotes a high level of usability within the ecosystem but also guards against the proliferation of spam registrations, ensuring that the registry remains accessible and functional for genuine 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> 2024-02-29T00:00:00+00:00 2026-02-11T14:49:27+00:00 Marius van der Wijdenhttps://github.com/MariusVanDerWijden Felix Langefjl@ethereum.org Ahmad Bitarhttps://github.com/smartprogrammer93smartprogrammer@windowslive.com https://wg-eips.ritovision.com/7642/

Adds history serving window and removes bloom filter in receipt

<h2 id="abstract">Abstract</h2> <p>This EIP modifies the 'eth' p2p protocol to announce the historical block range served by the node. We also simplify the handshake to remove total difficulty information, which isn't used anymore after the merge. Additionally we propose to remove the <code>Bloom</code> field from receipts transferred over the protocol.</p> <h2 id="motivation">Motivation</h2> <h3 id="block-range-in-status-message">Block range in Status message</h3> <p>In the history expiry working group, it was decided that clients may drop pre-merge history from their storage after May 1, 2025. For clients that want to sync history through the 'eth' protocol, it is essential to know whether a peer still serves old history. A similar idea was proposed in <a href="https://wg-eips.ritovision.com/7542/">EIP-7542</a> but was later withdrawn because a political decision on history expiry had not been reached at the time.</p> <h3 id="removing-bloom-in-receipts">Removing Bloom in Receipts</h3> <p>We recently discovered that none of the clients store the <code>Bloom</code> field of the receipts as it can be recomputed on demand. However the networking spec requires the <code>Bloom</code> field to be sent over the network. Thus a syncing node will ask for the Bloom filters for all receipts. The serving node will regenerate roughly 530GB of bloom filters (2.3B txs * 256 byte). These 530GBs are send over the network to the syncing peer, the syncing peer will verify them and not store them either. This adds an additional 530GB of unnecessary bandwidth to every sync.</p> <h3 id="blockrangeupdate-message">BlockRangeUpdate message</h3> <p>We want clients to be aware of the available block range in their peers. The new notification message can be used to detect sync status of peers, and adjust fetching behavior accordingly.</p> <h2 id="specification">Specification</h2> <h3 id="status-message-changes">Status message changes</h3> <p>Modify the <code>Status (0x00)</code> message as follows:</p> <ul> <li> <p>(eth/68): <code>[version: P, networkid: P, td: P, blockhash: B_32, genesis: B_32, forkid]</code></p> </li> <li> <p>(eth/69): <code>[version: P, networkid: P, genesis: B_32, forkid, earliestBlock: P, latestBlock: P, latestBlockHash: B_32]</code></p> </li> </ul> <p>Note <code>blockhash</code> has moved to the end to match <code>BlockRangeUpdate</code>.</p> <h3 id="receipts-message-changes">Receipts message changes</h3> <p>Modify the encoding for receipts in the <code>Receipts (0x10)</code> message as follows:</p> <ul> <li>(eth/68): <code>receipt = {legacy-receipt, typed-receipt}</code> with</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>typed-receipt = tx-type || rlp(legacy-receipt)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>legacy-receipt = [</span></span> <span class="giallo-l"><span> post-state-or-status: {B_32, {0, 1}},</span></span> <span class="giallo-l"><span> cumulative-gas: P,</span></span> <span class="giallo-l"><span> bloom: B_256,</span></span> <span class="giallo-l"><span> logs: [log₁, log₂, ...]</span></span> <span class="giallo-l"><span>]</span></span></code></pre> <ul> <li>(eth/69): <code>receipt = [tx-type, post-state-or-status, cumulative-gas, logs]</code></li> </ul> <h3 id="blockrangeupdate-message-1">BlockRangeUpdate message</h3> <p>Add a new <code>BlockRangeUpdate (0x11)</code> message, with the following encoding</p> <p><code>[earliestBlock: P, latestBlock: P, latestBlockHash: B_32]</code></p> <p>The new message should be sent whenever the block range available from this client is updated. In order to reduce traffic, it is not necessary to send an update for every new block. Clients should send an update at most once per epoch (32 blocks).</p> <h2 id="rationale">Rationale</h2> <h3 id="status-changes">Status changes</h3> <p>After the merge, the <code>TD</code> field of the <code>Status</code> message became meaningless since the difficulty of post-merge blocks are 0. It could in theory be used to distinguish synced with unsynced nodes, but the same thing can be accomplished with the forkid as well.</p> <p>The new <code>earliestBlock</code> field is technically not required for history expiry, but there are a couple reasons why adding it can help:</p> <ul> <li>It improves peer finding for clients that still want to sync history from p2p after the agreed-upon removal of pre-merge history has taken place. Without <code>earliestBlock</code>, the client would have to perform a request for history to check if the earlier range exists, and assume that a failed request means it's not there.</li> <li>The new field can be used for census in a specialized crawler. We will be able to see how many users/nodes enable history, and in which implementation.</li> <li>It prepares us for a future where the history expiry window is dynamic.</li> </ul> <h3 id="receipts-changes">Receipts changes</h3> <p>Removing the bloom filters from the <code>Receipt</code> message reduces the CPU load of serving nodes as well as the bandwidth significantly. The receiving nodes will need to recompute the bloom filter in order to fully verify the receipt hash. The recomputation is not very CPU intensive. The bandwidth gains amount to roughly 530GiB per syncing node or (at least) 95GiB snappy compressed.</p> <p>In Ethereum consensus, the encoding of receipts differs between legacy transactions and typed transactions. Typed transaction receipts are 'opaque' and have the data wrapped in a byte array. However, all receipt types ultimately contain the same four fields. With the removal of the bloom filter, the networking protocol now deviates from the encoding used by consensus, and there is no need to replicate the weird and expensive encoding used there. The proposed receipt encoding is just a flat list of the required data fields.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP changes the eth protocol and requires rolling out a new version, <code>eth/69</code>. Supporting multiple versions of a wire protocol is possible. Rolling out a new version does not break older clients immediately, since they can keep using protocol version <code>eth/68</code>.</p> <p>This EIP does not change consensus rules of the EVM and does not require a hard fork.</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-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-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Conwayhttps://github.com/0x1cc Cathie Sohttps://github.com/socathie Xiaohang Yuhttps://github.com/xhyumiracle Suning Yaohttps://github.com/fewwwww Kartinkartin@hyperoracle.io https://wg-eips.ritovision.com/7641/

An ERC-20 extension that integrates a revenue-sharing mechanism, ensuring tokens intrinsically represent a share of a communal revenue pool

<h2 id="abstract">Abstract</h2> <p>This proposal outlines an extension of the prevailing <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token standard, introducing a seamlessly integrated revenue-sharing mechanism. It incorporates a suite of interfaces designed to foster fair distribution of revenue among token holders while preserving the essential attributes of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. Central to this design is the establishment of a communal revenue pool, aggregating revenues from diverse sources. The token, in essence, embodies shares, affording holders the ability to burn their tokens and redeem a proportionate share from the revenue pool. This innovative burning mechanism guarantees that, when the revenue pool is non-empty, the token's value remains at least commensurate with the share of the revenue pool. Additionally, in periodic intervals, token holders can claim a portion of the reward, enriching their engagement and further enhancing the token's utility.</p> <h2 id="motivation">Motivation</h2> <h3 id="revenue-sharing-for-token-holders">Revenue Sharing for Token Holders</h3> <p>This proposal standardized an Intrinsic RevShare (revenue-sharing) model, allowing users to claim rewards periodically to ensure the efficiency of liquidity. This standard can inherently offer a clear path to long-term benefits for holders with revenue sharing, achieving a more sustainable token model by rewarding holders.</p> <p>With the inheritance of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> functionalities, token holders enjoy flexibility in trading tokens on secondary markets, and an optional burning mechanism empowers them to actively contribute to a deflationary economic model while obtaining a proportional share of the revenue pool.</p> <p>This approach also encourages active participation in open-source initiatives with a sustainable and multifaceted revenue-sharing ecosystem for Intrinsic RevShare token holders.</p> <h3 id="funding-for-any-project">Funding for Any Project</h3> <p>This standard enables the tokenizing of all kinds of projects with revenue. This EIP introduces a new model for incentivizing contributions to open-source projects. It proposes the distribution of Intrinsic RevShare tokens to active contributors, creating a tangible asset reflecting project involvement.</p> <p>Notably, it introduces a use case known as Initial Model Offering (IMO). Many open-sourced AI models face a challenge in monetizing their contributions, leading to a lack of motivation for contributors and organizations alike. This proposal seeks to empower open-sourced AI models and organizations by introducing Intrinsic RevShare token. In leveraging the token for IMO, open-sourced AI organizations can conduct fundraisings for essential funds to incentivize the ongoing development of AI models. Moreover, any project utilizing these open-source models contributes to the sustainability of the ecosystem by paying a designated fee to the revenue pool. This fee forms the basis of a revenue-sharing mechanism, allowing Intrinsic RevShare token holders to claim a proportionate share, thereby establishing a systematic and fair distribution mechanism. Importantly, this revenue-sharing feature serves as a guarantee for token holders, fostering long-term revenue benefits and encouraging sustained engagement in the open-source AI community.</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><strong>Every compliant contract must implement the <code>IERC7641</code>, and <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> interfaces.</strong></p> <p>The Intrinsic RevShare Token standard includes the following interfaces:</p> <p><code>IERC7641</code>:</p> <ul> <li>Defines a <code>claimableRevenue</code> view function to calculate the amount of ETH claimable by a token holder at a certain snapshot.</li> <li>Defines a <code>claim</code> function for token holder to claim ETH based on the token balance at certain snapshot.</li> <li>Defines a <code>snapshot</code> function to snapshot the token balance and the claimable revenue token balance.</li> <li>Defines a <code>redeemableOnBurn</code> view function to calculate the amount of ETH redeemable by a token holder upon burn.</li> <li>Defines a <code>burn</code> function for token holder to burn tokens and redeem the corresponding amount of revenue token.</li> </ul> <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.24</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"> An interface for ERC-7641, an ERC-20 extension that integrates a revenue-sharing mechanism, ensuring tokens intrinsically represent a share of a communal revenue pool</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"> IERC7641</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> A function to calculate the amount of ETH claimable by a token holder at certain snapshot.</span></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 of the token 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"> snapshotId</span><span class="z-comment"> The snapshot 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"> The</span><span class="z-comment"> amount of revenue token claimable</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"> claimableRevenue</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"> snapshotId</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">@dev</span><span class="z-comment"> A function for token holder to claim ETH based on the token balance at certain snapshot.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> snapshotId</span><span class="z-comment"> The snapshot 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"> claim</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> snapshotId</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"> A function to snapshot the token balance and the claimable revenue token 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"> The</span><span class="z-comment"> snapshot id</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Should have `require` to avoid ddos attack</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"> snapshot</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">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">@dev</span><span class="z-comment"> A function to calculate the amount of ETH redeemable by a token holder upon burn</span></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"> The amount of token to burn</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 revenue ETH redeemable</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"> redeemableOnBurn</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"> 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">@dev</span><span class="z-comment"> A function to burn tokens and redeem the corresponding amount of revenue 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"> The amount of token to burn</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 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></span></code></pre><h3 id="optional-extension-altrevtoken">Optional Extension: AltRevToken</h3> <p>The <strong>AltRevToken extension</strong> is OPTIONAL for this standard. This allows the contract to accept other <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> revenue tokens (more than ETH) into the revenue sharing pool.</p> <p>The AltRevToken extension</p> <ul> <li>Defines a <code>claimableERC20</code> function to calculate the amount of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> claimable by a token holder at certain snapshot.</li> <li>Defines a <code>redeemableERC20OnBurn</code> function to calculate the amount of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> redeemable by a token holder upon burn.</li> </ul> <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.24</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"> An optional extension of the ERC-7641 standard that accepts other ERC-20 revenue tokens into the contract with corresponding claim function</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"> IERC7641AltRevToken</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7641</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"> A function to calculate the amount of ERC-20 claimable by a token holder at certain snapshot.</span></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 of the token 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"> snapshotId</span><span class="z-comment"> The snapshot 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"> token</span><span class="z-comment"> The address of the revenue 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"> The</span><span class="z-comment"> amount of revenue token claimable</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"> claimableERC20</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"> snapshotId</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">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">@dev</span><span class="z-comment"> A function to calculate the amount of ERC-20 redeemable by a token holder upon burn</span></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"> The amount of token to burn</span></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"> The address of the revenue 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"> The</span><span class="z-comment"> amount of revenue token redeemable</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"> redeemableERC20OnBurn</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> amount</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">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="revenue-sharing-mechanism">Revenue Sharing Mechanism</h3> <p>We implement a revenue sharing mechanism wherein any token holder can claim a proportional share from the revenue pool. To ensure regular and transparent revenue distribution, we have incorporated the snapshot method, capturing both the token balance and the associated claimable revenue token balance. Periodic invocation of the snapshot method, corresponding to distinct revenue-sharing processes, is required. During each snapshot, token holders are empowered to claim a proportionate share from the revenue pool, creating a systematic and equitable distribution mechanism for participants.</p> <h3 id="snapshot-interface"><code>snapshot</code> interface</h3> <p>We specify a <code>snapshot</code> interface to snapshot the token balance and the claimable revenue token balance. This functionality ensures correctness in tracking token holdings, facilitating a transparent record of each token portfolio. Regular invocation of the snapshot function is essential to maintain up-to-date records. The <code>snapshot</code> interface returns a unique <code>snapshotId</code>, allowing access to the corresponding token balance and claimable revenue token balance associated with that specific snapshot. This systematic approach enhances the correctness and reliability of historical data retrieval, providing users with comprehensive insights into their token and revenue token balances at different points in time.</p> <h3 id="claimablerevenue-interface"><code>claimableRevenue</code> interface</h3> <p>We specify a <code>claimableRevenue</code> interface to calculate the amount of ETH claimable by a token holder at a certain snapshot. We will share the revenue between two consecutive snapshots. As an example in our reference implementation, assuming that the revenue between two snapshots is <code>R</code>, we specify a revenue sharing ratio <code>p</code>, ranging from 0%-100%, and we share the revenue of <code>pR</code> to different token holders according to the token ratio. In this example, the amount of ETH claimable by a token holder with <code>amount</code> tokens at a certain snapshot is <code>pR * amount / totalAmount</code> , where <code>totalAmount</code> denotes the total amount of <a href="https://wg-eips.ritovision.com/7641/">ERC-7641</a> token. Noted that the remaining revenue of <code>(1-p)R</code> will be retained in the revenue pool, and we can take out this part of revenue through burning.</p> <h3 id="claim-interface"><code>claim</code> interface</h3> <p>We specify a <code>claim</code> interface for token holder to claim ETH based on the token balance at certain snapshot. Each token holder can only claim revenue at a certain snapshot once, ensuring a fair and transparent distribution mechanism.</p> <h3 id="burning-mechanism">Burning Mechanism</h3> <p>We implement a burning mechanism wherein any token holder can burn their tokens to redeem a proportional share from the revenue pool. This mechanism serves as a guarantee, ensuring that the value of the token is consistently greater than or equal to the share of the revenue pool, promoting a fair and balanced system.</p> <h3 id="redeemableonburn-interface"><code>redeemableOnBurn</code> interface</h3> <p>We specify <code>redeemableOnBurn</code> interface to calculate the amount of ETH redeemable by a token holder upon burn. It is defined as a view function to reduce gas cost. As an example in our reference implementation, the amount of ETH redeemable, i.e., <code>redeemableETH</code> by a token holder with <code>amount</code> of token to burn is</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>redeemableETH </span><span class="z-keyword">=</span><span> amount </span><span class="z-keyword">/</span><span> totalSupply </span><span class="z-keyword">*</span><span> totalRedeemableETH</span></span></code></pre> <p>where <code>totalSupply</code> denotes the total supply of <a href="https://wg-eips.ritovision.com/7641/">ERC-7641</a> token, and <code>totalRedeemableETH</code> denotes the total amount of ETH in the burning pool.</p> <h3 id="burn-interface"><code>burn</code> interface:</h3> <p>We specify <code>burn</code> interface for token holder to burn tokens and redeem the corresponding amount of revenue token. A token holder can burn at most all tokens it holds. This burning process leads to a reduction in the total token supply, establishing a deflationary economic model. Furthermore, it is important to note that tokens once burned are excluded from participating in any subsequent revenue sharing.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is backward compatible with the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> as it extends the existing functionality with new interfaces.</p> <h2 id="test-cases">Test Cases</h2> <p>The reference implementation includes sample implementations of the interfaces in this standard under <code>contracts/</code> and corresponding unit tests under <code>test/</code>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <ul> <li><a href="https://wg-eips.ritovision.com/7641/./assets/contracts/ERC7641.sol">ERC-7641</a></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <h3 id="deflationary-economic-model">Deflationary Economic Model</h3> <p>The introduction of the burning mechanism in this standard signifies a shift towards a deflationary economic model, which introduces unique considerations regarding security. One prominent concern involves the potential impact on token liquidity and market dynamics. The continuous reduction in token supply through burning has the potential to affect liquidity levels, potentially leading to increased volatility and susceptibility to price manipulation. It is essential to conduct thorough stress testing and market simulations to assess the resilience of the system under various scenarios.</p> <h3 id="spam-revenue-tokens">Spam Revenue Tokens</h3> <p>The extension of AltRevToken with the ability to set up different revenue tokens introduces specific security considerations, primarily centered around the prevention of adding numerous, potentially worthless tokens. The addition of too many spam (worthless) tokens may lead to an increase in gas fees associated with burning and claiming processes. This can result in inefficiencies and higher transaction costs for users, potentially discouraging participation in revenue-sharing activities.</p> <p>A robust governance model is crucial for the approval and addition of new revenue tokens. Implementing a transparent and community-driven decision-making process ensures that only reputable and valuable tokens are introduced, preventing the inclusion of tokens with little to no utility. This governance process should involve community voting, security audits, and careful consideration of the potential impact on gas fees.</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-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Arif Khanarif@alethea.ai Ahmad Matyanaahmad@alethea.ai Basil Gorinhttps://github.com/vgorin Vijay Bhayanihttps://github.com/unblocktechie https://wg-eips.ritovision.com/7649/

Embedding liquidity into Non-Fungible Tokens (NFTs) without modifications to ERC-721.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a standard for embedding Bonding Curve-like liquidity into Non-Fungible Tokens (NFTs) without modifying the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard. The proposed standard allows the attachment of an embedded liquidity contract, referred to as Tradable Shares, to an ERC-721 NFT. Tradable Shares leverage a Bonding Curve-like approach to attract liquidity, enabling trading of shares based on the bonding curve price formula.</p> <h2 id="motivation">Motivation</h2> <p>The ERC-721 standard lacks a specific mechanism for embedding bonding curve-based liquidity, limiting the creative possibilities for NFT-based projects. This EIP addresses the need for a standardized approach to integrate bonding curve contracts seamlessly into ERC-721 NFTs, allowing for diverse and innovative implementations without modifying the ERC-721 standard.</p> <p>The proposed standard focuses on enhancing the ERC-721 standard by introducing a framework for embedding bonding curve-based liquidity into NFTs. This approach provides creators with a flexible and customizable tool to attract liquidity through bonding curve mechanisms, while ensuring creators receive guaranteed fees for their contributions.</p> <p>The bonding curve-embedded liquidity for NFTs standard finds compelling use cases across diverse industries, offering a dynamic solution for embedding Bonding Curve-like liquidity into NFTs. One prominent use case revolves around the intersection of AI services, where NFTs model AI models, GPU resource pools, and storage resource pools. Let's explore two specific use cases within this domain:</p> <ol> <li> <p><strong>AI Model Marketplace:</strong></p> <ul> <li>NFTs representing AI models leverage the embedded liquidity standard to embed Bonding Curve-like liquidity. AI model providers attach Tradable Shares contracts to their NFTs, enabling a seamless integration of liquidity features without modifying the ERC-721 standard.</li> <li>The Bonding Curve mechanism allows the pricing of shares (or keys) based on the AI model's supply and demand. As AI models gain popularity or demonstrate superior performance, liquidity providers are incentivized to buy and sell shares, fostering a competitive marketplace.</li> <li>Creators can customize bonding curve parameters, such as slope and intercept, tailoring the liquidity mechanism to match the evolving nature of AI models. This ensures a fair and adaptive marketplace where liquidity providers are attracted to promising AI models, thereby creating a symbiotic relationship between liquidity and AI innovation.</li> </ul> </li> <li> <p><strong>Decentralized GPU and Storage Resource Allocation:</strong></p> <ul> <li>In a decentralized ecosystem, GPU and storage resource pools are represented as NFTs with embedded Tradable Shares contracts. This enables resource providers to attract liquidity and compete for resource allocations based on the Bonding Curve mechanism.</li> <li>The Bonding Curve determines the price of shares associated with GPU and storage resources, reflecting the current supply and demand. Providers can customize bonding curve parameters to optimize their resource pool's attractiveness, taking into account factors like available resources, performance metrics, and historical usage.</li> <li>Guaranteed creative fees incentivize resource providers to continually enhance and optimize their services. As the demand for GPU and storage resources evolves, the embedded liquidity standard ensures that providers receive fair compensation for their contributions, maintaining a competitive and responsive marketplace.</li> </ul> </li> </ol> <p>In both use cases, the standard serves as a powerful incentive for providers to attract and retain liquidity. The dynamic nature of the Bonding Curve-like mechanism aligns with the evolving landscape of AI models and resource pools, fostering innovation, competition, and liquidity-driven growth within the decentralized AI services domain.</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> <p>Bonding Curve-Embedded Liquidity / Tradable Shares:</p> <ul> <li>An embedded bonding curve-based liquidity SHOULD be attached to the NFT via a separate contract.</li> <li>An embedded bonding curve-based liquidity MUST NOT be embedded into or modify the ERC-721 standard.</li> <li>The bonding curve contract MUST manage the liquidity of the associated NFT through a bonding curve mechanism.</li> </ul> </li> <li> <p>Bonding Curve Mechanism:</p> <ul> <li>The bonding curve determines the price of the NFT "keys" (sometimes also referred to as "shares") in relation to its supply, encouraging liquidity providers to buy and sell NFT shares based on the curve's formula.</li> <li>Implementation MAY allow the creators to customize the bonding curve parameters, such as slope, intercept, or any other relevant parameters.</li> <li>Implementation MAY allow the creators to customize the shape of the bonding curve (the curve's formula).</li> </ul> </li> <li> <p>Guaranteed Creative Fees:</p> <ul> <li>The implementation MUST include the mechanisms that guarantee creative fees for NFT creators, that is it MUST guarantee the creators receive a percentage of transaction fees generated by the embedded liquidity contract during buy and sell operations.</li> <li>The implementation MAY allow the creators to defne the transaction fees.</li> </ul> </li> <li> <p>Payment Mechanisms:</p> <ul> <li>The embedded liquidity contract MUST support either <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens or native ETH as a payment, it MAY support both.</li> </ul> </li> </ol> <h3 id="bondingcurve-interface"><code>BondingCurve</code> Interface</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * @title Bonding Curve</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @notice A bonding curve definition</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @notice Bonding curve defines the price of the smallest unit of the asset as a function</span></span> <span class="giallo-l"><span> * of the asset supply</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>interface BondingCurve {</span></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Bonding curve function definition. The function calculating the price</span></span> <span class="giallo-l"><span> * of the `amount` of shares given the current total supply `supply`</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param supply total shares supply</span></span> <span class="giallo-l"><span> * @param amount number of shares to buy/sell</span></span> <span class="giallo-l"><span> * @return the price of the shares (all `amount` amount)</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getPrice(uint256 supply, uint256 amount) external pure returns(uint256);</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="bonding-curve-embedded-liquidity-tradeableshares-interface">Bonding Curve-Embedded Liquidity / <code>TradeableShares</code> Interface</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * @title Tradeable Shares</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @notice Tradeable shares is a non-transferable, but buyable/sellable fungible token-like asset,</span></span> <span class="giallo-l"><span> * which is sold/bought solely by the shares contract at the predefined by</span></span> <span class="giallo-l"><span> * the bonding curve function price</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @notice The shares is bound to its &quot;subject&quot; – an NFT; the NFT owner gets the subject fee</span></span> <span class="giallo-l"><span> * emerging in every buy/sell operation</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>interface TradeableShares is BondingCurve {</span></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Shares subject is an NFT defined by its ERC-721 contract address and NFT ID</span></span> <span class="giallo-l"><span> * Shares subject is an NFT the liquidity is embedded to</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> struct SharesSubject {</span></span> <span class="giallo-l"><span> /// @dev ERC-721 contract address</span></span> <span class="giallo-l"><span> address tokenAddress;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @dev NFT ID</span></span> <span class="giallo-l"><span> uint256 tokenId;</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> * @dev Fired in `buyShares` and `sellShares` functions, this event logs</span></span> <span class="giallo-l"><span> * the entire trading activity happening on the curve</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @dev Trader, that is the buyer or seller, depending on the operation type is the transaction sender</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param beneficiary the address which receives shares or funds, usually this is the trader itself</span></span> <span class="giallo-l"><span> * @param issuer subject issuer, usually an owner of the NFT defined by the subject</span></span> <span class="giallo-l"><span> * @param isBuy true if the event comes from the `buyShares` and represents the buy operation,</span></span> <span class="giallo-l"><span> * false if the event comes from the `sellShares` and represents the sell operation</span></span> <span class="giallo-l"><span> * @param sharesAmount amount of the shares bought or sold (see `isBuy`)</span></span> <span class="giallo-l"><span> * @param paidAmount amount of ETH spent or gained by the buyer or seller;</span></span> <span class="giallo-l"><span> * this is implementation dependent and can represent an amount of ERC-20 payment token</span></span> <span class="giallo-l"><span> * @param feeAmount amount of all the fees paid, if any</span></span> <span class="giallo-l"><span> * @param supply total shares supply after the operation</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event Trade(</span></span> <span class="giallo-l"><span> address indexed beneficiary,</span></span> <span class="giallo-l"><span> address indexed issuer,</span></span> <span class="giallo-l"><span> bool indexed isBuy,</span></span> <span class="giallo-l"><span> uint256 sharesAmount,</span></span> <span class="giallo-l"><span> uint256 paidAmount,</span></span> <span class="giallo-l"><span> uint256 feeAmount,</span></span> <span class="giallo-l"><span> uint256 supply</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> * @notice Shares subject, usually defined as NFT (ERC-721 contract address + NFT ID)</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @dev Immutable, client applications may cache this value</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @return Shares subject as a SharesSubject struct, this is an NFT if all currently known implementations</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getSharesSubject() external view returns(SharesSubject calldata);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Cumulative fee percent, applied to all the buy and sell operations;</span></span> <span class="giallo-l"><span> * the fee percent is defined with the 18 decimals, 10^18 corresponds to 100%</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @notice The fee can be combined from multiple fees which are sent to the various destinations</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @dev Immutable, client applications may cache this value</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @return protocol fee percent with the 18 decimals (10^18 is 100%)</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getFeePercent() external view returns(uint256);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Shares issuer, the receiver of the shares fees</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @dev Mutable, changes (potentially frequently and unpredictably) when the NFT owner changes;</span></span> <span class="giallo-l"><span> * subject to the front-run attacks, off-chain client applications must not rely on this address</span></span> <span class="giallo-l"><span> * in anyway</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @return nftOwner subject issuer, the owner of the NFT</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getSharesIssuer() external view returns(address nftOwner);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Shares balance of the given holder; this function is similar to ERC20.balanceOf()</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param holder the address to check the balance for</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @return balance number of shares the holder has</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getSharesBalance(address holder) external view returns(uint256 balance);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Total amount of the shares in existence, the sum of all individual shares balances;</span></span> <span class="giallo-l"><span> * this function is similar to ERC20.totalSupply()</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @return supply total shares supply</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getSharesSupply() external view returns(uint256 supply);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice The price of the `amount` of shares to buy calculated based on</span></span> <span class="giallo-l"><span> * the specified total shares supply</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param supply total shares supply</span></span> <span class="giallo-l"><span> * @param amount number of shares to buy</span></span> <span class="giallo-l"><span> * @return the price of the shares to buy</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getBuyPrice(uint256 supply, uint256 amount) external pure returns(uint256);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice The price of the `amount` of shares to sell calculated based on</span></span> <span class="giallo-l"><span> * the specified total shares supply</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param supply total shares supply</span></span> <span class="giallo-l"><span> * @param amount number of shares to sell</span></span> <span class="giallo-l"><span> * @return the price of the shares to sell</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getSellPrice(uint256 supply, uint256 amount) external pure returns(uint256);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice The price of the `amount` of shares to buy, including all fees;</span></span> <span class="giallo-l"><span> * calculated based on the specified total shares supply and fees percentages</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param supply total shares supply</span></span> <span class="giallo-l"><span> * @param amount number of shares to buy</span></span> <span class="giallo-l"><span> * @param protocolFeePercent protocol fee percent</span></span> <span class="giallo-l"><span> * @param holdersFeePercent shares holders fee percent</span></span> <span class="giallo-l"><span> * @param subjectFeePercent protocol fee percent</span></span> <span class="giallo-l"><span> * @return the price of the shares to buy</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getBuyPriceAfterFee(</span></span> <span class="giallo-l"><span> uint256 supply,</span></span> <span class="giallo-l"><span> uint256 amount,</span></span> <span class="giallo-l"><span> uint256 protocolFeePercent,</span></span> <span class="giallo-l"><span> uint256 holdersFeePercent,</span></span> <span class="giallo-l"><span> uint256 subjectFeePercent</span></span> <span class="giallo-l"><span> ) external pure returns(uint256);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice The price of the `amount` of shares to sell, including all fees;</span></span> <span class="giallo-l"><span> * calculated based on the specified total shares supply and fees percentages</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param supply total shares supply</span></span> <span class="giallo-l"><span> * @param amount number of shares to sell</span></span> <span class="giallo-l"><span> * @param protocolFeePercent protocol fee percent</span></span> <span class="giallo-l"><span> * @param holdersFeePercent shares holders fee percent</span></span> <span class="giallo-l"><span> * @param subjectFeePercent protocol fee percent</span></span> <span class="giallo-l"><span> * @return the price of the shares to sell</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getSellPriceAfterFee(</span></span> <span class="giallo-l"><span> uint256 supply,</span></span> <span class="giallo-l"><span> uint256 amount,</span></span> <span class="giallo-l"><span> uint256 protocolFeePercent,</span></span> <span class="giallo-l"><span> uint256 holdersFeePercent,</span></span> <span class="giallo-l"><span> uint256 subjectFeePercent</span></span> <span class="giallo-l"><span> ) external pure returns(uint256);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Current price of the `amount` of shares to buy; calculated based on</span></span> <span class="giallo-l"><span> * the current total shares supply</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param amount number of shares to buy</span></span> <span class="giallo-l"><span> * @return the price of the shares to buy</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getBuyPrice(uint256 amount) external view returns(uint256);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Current price of the `amount` of shares to sell; calculated based on</span></span> <span class="giallo-l"><span> * the current total shares supply</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param amount number of shares to sell</span></span> <span class="giallo-l"><span> * @return the price of the shares to sell</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getSellPrice(uint256 amount) external view returns(uint256);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Current price of the `amount` of shares to buy, including all fees;</span></span> <span class="giallo-l"><span> * calculated based on the current total shares supply and fees percentages</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param amount number of shares to buy</span></span> <span class="giallo-l"><span> * @return the price of the shares to buy</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getBuyPriceAfterFee(uint256 amount) external view returns(uint256);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Current price of the `amount` of shares to sell, including all fees;</span></span> <span class="giallo-l"><span> * calculated based on the current total shares supply and fees percentages</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param amount number of shares to sell</span></span> <span class="giallo-l"><span> * @return the price of the shares to sell</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getSellPriceAfterFee(uint256 amount) external view returns(uint256);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Buy `amount` of shares. Sender has to supply `getBuyPriceAfterFee(amount)` ETH.</span></span> <span class="giallo-l"><span> * First share can be bought only by current subject issuer.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @dev Depending on the implementation, ERC-20 token payment may be required instead of ETH.</span></span> <span class="giallo-l"><span> * In such a case, implementation must through if ETH is sent, effectively overriding</span></span> <span class="giallo-l"><span> * the function definition as non-payable</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param amount amount of the shares to buy</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function buyShares(uint256 amount) external payable;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Buy `amount` of shares in the favor of the address specified (beneficiary).</span></span> <span class="giallo-l"><span> * Sender has to supply `getBuyPriceAfterFee(amount)` ETH.</span></span> <span class="giallo-l"><span> * First share can be bought only by current subject issuer.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @dev Depending on the implementation, ERC-20 token payment may be required instead of ETH.</span></span> <span class="giallo-l"><span> * In such a case, implementation must through if ETH is sent, effectively overriding</span></span> <span class="giallo-l"><span> * the function definition as non-payable</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param amount amount of the shares to buy</span></span> <span class="giallo-l"><span> * @param beneficiary an address receiving the shares</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function buySharesTo(uint256 amount, address beneficiary) external payable;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Sell `amount` of shares. Sender gets `getSellPriceAfterFee(amount)` of ETH.</span></span> <span class="giallo-l"><span> * Last share cannot be sold.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @dev Depending on the implementation, ERC-20 token may be payed instead of ETH.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param amount amount of the shares to sell</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function sellShares(uint256 amount) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Sell `amount` of shares in the favor of the address specified (beneficiary).</span></span> <span class="giallo-l"><span> * The beneficiary gets `getSellPriceAfterFee(amount)` of ETH.</span></span> <span class="giallo-l"><span> * Last share cannot be sold.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @dev Depending on the implementation, ERC-20 token may be payed instead of ETH.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param amount amount of the shares to sell</span></span> <span class="giallo-l"><span> * @param beneficiary an address receiving the funds from the sale</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function sellSharesTo(uint256 amount, address payable beneficiary) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @notice Cumulative value of all trades; allows to derive cumulative fees paid</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @dev This value cannot decrease over time; it can increase or remain constant</span></span> <span class="giallo-l"><span> * if no trades are happening</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @return Sum of the modulo of all trading operations</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getTradeVolume() external view returns(uint256);</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The rationale behind the design choices for the embedded liquidity standard is deeply rooted in providing a robust and versatile framework for embedding Bonding Curve-like liquidity into NFTs. The following key considerations have influenced the technical decisions:</p> <ol> <li> <p><strong>Bonding Curve-Embedded Liquidity / Tradable Shares Contract</strong>:</p> <ul> <li> <p><strong>Seamless Integration</strong>: The decision to allow an embedded bonding curve-based liquidity contract to be attached to an NFT without altering the ERC-721 standard stems from the desire for seamless integration. This approach ensures that NFT developers can enhance their creations with liquidity mechanisms without introducing complexities or requiring modifications to the widely adopted ERC-721 standard.</p> </li> <li> <p><strong>Liquidity Management</strong>: The bonding curve contract's role in managing liquidity through the bonding curve mechanism is essential. This design choice facilitates a dynamic and automated pricing model based on supply and demand, contributing to the overall liquidity and tradability of NFT shares.</p> </li> </ul> </li> <li> <p><strong>Bonding Curve Mechanism</strong>:</p> <ul> <li> <p><strong>Dynamic Pricing</strong>: The adoption of a bonding curve mechanism to determine the price of Tradable Shares aligns with the goal of encouraging liquidity providers to engage in buying and selling NFT shares. The dynamic pricing, influenced by the curve's formula, ensures that the market for Tradable Shares remains responsive to changing conditions.</p> </li> <li> <p><strong>Customization for Creators</strong>: The decision to allow creators to customize bonding curve parameters, such as slope and intercept, empowers them to tailor the liquidity mechanism to the unique needs and characteristics of their projects. This customization fosters creativity and innovation within the NFT space.</p> </li> </ul> </li> <li> <p><strong>Guaranteed Creative Fees</strong>:</p> <ul> <li><strong>Creator Incentives</strong>: The emphasis on guaranteeing creative fees for NFT creators is foundational to sustaining a thriving ecosystem. By enabling creators to specify and receive a percentage of transaction fees, the standard aligns incentives and rewards creators for their contributions, fostering a sustainable and creator-friendly environment.</li> </ul> </li> <li> <p><strong>Payment Mechanisms</strong>:</p> <ul> <li><strong>Developer Freedom</strong>: The standard's implementation-agnostic approach is motivated by the desire to provide developers with the freedom to choose and design the most suitable liquidity mechanism for their NFT projects. Whether interacting with ERC-20 tokens or native ETH, this independence ensures that developers can make informed choices based on the specific requirements of their projects.</li> </ul> </li> </ol> <p>The rationale behind these design choices is to create a Tradable Shares standard that is not only technically sound but also flexible, adaptable, and supportive of diverse and creative implementations within the ERC-721 ecosystem.</p> <p>See also: Bonded Fungible Tokens (1671)</p> <h2 id="security-considerations">Security Considerations</h2> <ol> <li> <p>Smart Contract Security: Implementations of smart contracts should undergo thorough security audits to ensure resistance against vulnerabilities and attacks.</p> </li> <li> <p>Creative Fee Handling: Mechanisms for handling and distributing creative fees should be secure and transparent to prevent any malicious activities.</p> </li> <li> <p>Compatibility: Developers should ensure compatibility with existing ERC-721 implementations, allowing for a smooth integration of the embedded liquidity standard.</p> </li> <li> <p>User Experience: Considerations should be made to maintain a positive user experience, avoiding complexities that may hinder the adoption of NFT projects utilizing embedded liquidity.</p> </li> </ol> <p>This security considerations section reflects the importance of anticipating and addressing potential security challenges in the implementation, ensuring its robustness, compatibility, and user-friendly nature.</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-26T00:00:00+00:00 2026-02-11T14:48:26+00:00 Georgehttps://github.com/JXRow Zisuhttps://github.com/lazy1523 https://wg-eips.ritovision.com/7638/

Encode multiple calls for smart contract account (SCA) with atomic and saving gas

<h2 id="abstract">Abstract</h2> <p>Batch Calls Encoding (BCE) outlines a solution for Smart Contract Account (SCA) wallets to consolidate multiple calls into a single call, encoding multiple parameters into bytes, compressing on-chain data, and saving gas. It can be used to implement atomic operations as well as non-atomic operations.</p> <h2 id="motivation">Motivation</h2> <p>Typically, interactions between users and contracts involve a series of coherent operations, such as <code>approve</code>-<code>transferFrom</code>. While EOA wallets require users to confirm each operation sequentially, SCA wallets can confirm all operations with a single confirmation, completing all operations within a single call, thus achieving atomicity. If <code>approve</code> succeeds but <code>transferFrom</code> fails, it poses a security risk. The secure approach is to ensure that if one operation fails, all associated operations also fail, thereby ensuring atomicity. Therefore, we propose this encoding method to encode multiple parameters into bytes, compress on-chain data, and save gas. It can be used to implement both atomic and non-atomic operations.</p> <p>In addition to the atomic operation of <code>approve</code>-<code>transferFrom</code> mentioned above, gas payment delegation can also be achieved. It involves users and bundlers signing a set of calls, where the content of the calls includes:</p> <ol> <li>The user wishes to initiate multiple calls through his SCA.</li> <li>The user transfers 10 USDT to the bundler as fee, included within the calls.</li> <li>The bundler submits the calls, pay ETH gas and get the 10 USDT.</li> </ol> <p>The user encodes the content of the calls, attaches their signature to ensure its integrity, and sends it to the bundler. If the bundler considers the gas payment insufficient, they may choose not to submit it. However, if they approve the content of the calls, the signed transaction can be submitted. After execution, the user obtains the desired operations, and the bundler receives the fee.</p> <p><a href="https://wg-eips.ritovision.com/4337/">EIP-4337</a> also implements gas payment delegation. BCE and <a href="https://wg-eips.ritovision.com/4337/">EIP-4337</a> are not mutually exclusive and can be implemented concurrently within an SCA.</p> <p>Based on empirical testing, BCE is simpler and more gas-efficient compared to alternative methods.</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 ERC <strong>REQUIRED</strong> SCA to be implemented in the contract, where the Dapp communicates with the SCA wallet extension to communicate the user's intentions to the wallet, which uses Batch Calls Encoding to send multiple calls as bytes to the user's SCA contract.</p> <p><em>Batch Calls</em> comprises multiple <code>Call</code> bytes, each defined by the encoding of <code>to</code>`value<code>\</code>data` as follows:</p> <p><img src="https://wg-eips.ritovision.com/7638/./assets/encoding.svg" alt="" /></p> <p>Let:</p> <ul> <li><code>to</code>: The address of the called contract, corresponding to the Solidity address type, 20 bytes.</li> <li><code>value</code>: The amount of ETH(in wei) sent to the contract, in wei, corresponding to the Solidity uint type, 32 bytes.</li> <li><code>data length</code>: The length of the data(in bytes), corresponding to the Solidity uint type, 32 bytes.</li> <li><code>data</code>: The encoded functionData sent to the contract, corresponding to the Solidity bytes type, with a length defined by <code>data length</code>.</li> </ul> <p>Multiple <code>Call</code> units are concatenated to form an <em>Batch Calls</em> sequence.</p> <h2 id="rationale">Rationale</h2> <p>Each call encapsulates 3 parameters: <code>to</code>`value<code>\</code>data<code>. The conventional approach involves packaging these 3 parameters into a struct and then placing multiple structs into an array. However, using a struct adds overhead as it also packages the types of </code>to<code>\</code>value<code>\</code>data<code>, increasing the size of the encoding. Since </code>to<code>\</code>value<code>\</code>data<code>have fixed types, this additional encoding can be omitted. In Solidity, reading data from</code>bytes calldata` using slice is a gas-efficient method. Considering these factors, <em>Batch Calls Encoding</em> can compress on-chain data and save gas.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC does not change the consensus layer, so there are no backwards compatibility issues for Ethereum as a whole.</p> <p>This ERC does not change other ERC standards, so there are no backwards compatibility issues for Ethereum applications.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>This proposal only specifies the encoding of <em>Batch Calls</em>, while the specific implementation and naming are left to the discretion of the project. Below is an example of an SCA contract utilizing <em>Batch Calls</em> (referred to as <code>atomCallbytes</code>), where the user atomically signs multiple operations, enabling the bundler to pay gas on behalf of the user:</p> <h3 id="smartwallet-sol"><code>SmartWallet.sol</code></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-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-storage z-type">contract</span><span class="z-entity z-name"> SmartWallet</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> ECDSA</span><span class="z-keyword"> for</span><span class="z-entity z-name"> bytes32</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint32</span><span class="z-storage z-type"> public</span><span> valid </span><span class="z-keyword">=</span><span class="z-constant"> 1</span><span>;</span><span class="z-comment"> //</span><span class="z-comment">to make AtomSign invalid</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 class="z-storage z-type"> immutable</span><span> original</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> owner</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> bundler</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-support"> bool</span><span>)</span><span class="z-storage z-type"> public</span><span> usedMsgHashes</span><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"> onlyBundler</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> bundler </span><span class="z-keyword">==</span><span class="z-variable z-language"> msg.sender</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;onlyBundler: caller is not the bundler&quot;</span></span> <span class="giallo-l"><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"> modifier</span><span class="z-entity z-name"> onlyOwnerAndOriginal</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</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 class="z-keyword"> ||</span><span> original </span><span class="z-keyword">==</span><span class="z-variable z-language"> msg.sender</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;onlyOwnerAndOriginal: caller is not the owner&quot;</span></span> <span class="giallo-l"><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"> constructor</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _bundler</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> original </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> owner </span><span class="z-keyword">=</span><span class="z-variable z-language"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span> bundler </span><span class="z-keyword">=</span><span> _bundler</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"> atomSignCall</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"> atomCallbytes</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span class="z-variable"> deadline</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"> signature</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyBundler</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>deadline </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-string"> &quot;atomSignCall: Expired&quot;</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-support"> keccak256</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>.</span><span class="z-entity z-name">concat</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-language"> msg</span><span>.</span><span>data</span><span>[</span><span class="z-keyword">:</span><span class="z-variable z-language">msg</span><span>.</span><span>data</span><span>.</span><span>length </span><span class="z-keyword">-</span><span> signature</span><span>.</span><span>length </span><span class="z-keyword">-</span><span class="z-constant"> 32</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-variable z-language">block</span><span>.</span><span>chainid</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes20</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 class="z-support"> bytes4</span><span>(</span><span>valid</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-keyword">!</span><span>usedMsgHashes</span><span>[</span><span>msgHash</span><span>]</span><span>,</span><span class="z-string"> &quot;atomSignCall: Used msgHash&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> owner </span><span class="z-keyword">==</span><span> msgHash</span><span>.</span><span class="z-entity z-name">toEthSignedMessageHash</span><span>(</span><span>)</span><span>.</span><span class="z-entity z-name">recover</span><span>(</span><span>signature</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;atomSignCall: Invalid Signature&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">do calls</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> i</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span>(</span><span>i </span><span class="z-keyword">&lt;</span><span> atomCallbytes</span><span>.</span><span>length</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> to </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span class="z-support">uint160</span><span>(</span><span class="z-support">bytes20</span><span>(</span><span>atomCallbytes</span><span>[</span><span>i</span><span class="z-keyword">:</span><span>i</span><span class="z-keyword">+</span><span class="z-constant">20</span><span>]</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> value </span><span class="z-keyword">=</span><span class="z-support"> uint</span><span>(</span><span class="z-support">bytes32</span><span>(</span><span>atomCallbytes</span><span>[</span><span>i</span><span class="z-keyword">+</span><span class="z-constant">20</span><span class="z-keyword">:</span><span>i</span><span class="z-keyword">+</span><span class="z-constant">52</span><span>]</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> len </span><span class="z-keyword">=</span><span class="z-support"> uint</span><span>(</span><span class="z-support">bytes32</span><span>(</span><span>atomCallbytes</span><span>[</span><span>i</span><span class="z-keyword">+</span><span class="z-constant">52</span><span class="z-keyword">:</span><span>i</span><span class="z-keyword">+</span><span class="z-constant">84</span><span>]</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> (</span><span class="z-support">bool</span><span> success</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span> to</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span> value</span><span>}</span><span>(</span><span>atomCallbytes</span><span>[</span><span>i</span><span class="z-keyword">+</span><span class="z-constant">84</span><span class="z-keyword">:</span><span>i</span><span class="z-keyword">+</span><span class="z-constant">84</span><span class="z-keyword">+</span><span>len</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>success</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-keyword"> revert</span><span>(</span><span class="z-entity z-name">add</span><span>(</span><span>result</span><span>,</span><span class="z-constant"> 32</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>result</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> i </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span class="z-constant"> 84</span><span class="z-keyword"> +</span><span> len</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> usedMsgHashes</span><span>[</span><span>msgHash</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 class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * if you signed something then regretted, make it invalid</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"> makeAtomSignInvalid</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyOwnerAndOriginal</span><span> {</span></span> <span class="giallo-l"><span> valid </span><span class="z-keyword">=</span><span class="z-support"> uint32</span><span>(</span><span class="z-support">uint</span><span>(</span><span class="z-variable z-language">blockhash</span><span>(</span><span class="z-variable z-language">block</span><span>.</span><span>number</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="bundler-sol"><code>Bundler.sol</code></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">contract</span><span class="z-entity z-name"> Bundler</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"> public</span><span> owner</span><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"> onlyOwner</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</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 class="z-string"> &quot;onlyOwner: caller is not the owner&quot;</span></span> <span class="giallo-l"><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"> constructor</span><span>(</span><span>)</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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> executeOperation</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> wallet</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"> public</span><span class="z-entity z-name"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bool</span><span> success</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span> _callTo</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span class="z-constant"> 0</span><span>}</span><span>(</span><span>data</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>success</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-keyword"> revert</span><span>(</span><span class="z-entity z-name">add</span><span>(</span><span>result</span><span>,</span><span class="z-constant"> 32</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>result</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="security-considerations">Security Considerations</h2> <p>This proposal introduces a data encoding scheme aimed at data compression. It solely concerns data compression and does not lead to data loss or concealment of private 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> 2024-02-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 James Kemptonhttps://github.com/SirSpudlington https://wg-eips.ritovision.com/7636/

Add additional ENR entry to specify client information such as name and version number.

<h2 id="abstract">Abstract</h2> <p>The Ethereum network consists of nodes running various client implementations. Each client has its own set of features, optimizations, and unique behaviors. Introducing a standardized way to identify client software and its version in the ENR allows for more effective network analysis, compatibility checks, and troubleshooting. This EIP proposes the addition of a "client" field to the ENR.</p> <h2 id="motivation">Motivation</h2> <p>Understanding the landscape of client software in the Ethereum network is crucial for developers, nodes, and network health assessment. Currently, there is no standardized method for nodes to announce their software identity and version, which can lead to compatibility issues or difficulty in diagnosing network-wide problems. Adding this to the ENR allows clients to audit network health only using discv5, and additionally track discv5 adoption across different services.</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 "client" entry is proposed to be added to the ENR following the specifications in <a href="https://wg-eips.ritovision.com/778/">EIP-778</a>. This entry is OPTIONAL and can be omitted by clients that choose not to disclose such information. The key for this entry is <code>"client"</code>.</p> <p>All elements MUST be encoded as a string using the ASCII standard as described in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc20">RFC 20</a>.</p> <p>The value for this entry MUST be an RLP list:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[ClientName, Version, (BuildVersion)]</span></span></code></pre> <ul> <li><code>ClientName</code>: A string identifier for the client software. It SHOULD be concise, free of spaces, and representative of the client application.</li> <li><code>Version</code>: A string representing the version of the client software in a human-readable format. It is RECOMMENDED to follow semantic versioning.</li> <li><code>BuildVersion</code>: An OPTIONAL string representing the build or commit version of the client software. This can be used to identify specific builds or development versions.</li> </ul> <h2 id="rationale">Rationale</h2> <p>One key was chosen over using many keys to make efficient use of space. The use of one string, however, does not align with other EIPs of similar purpose and as such the RLP list was decided as the best encoding.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible as it extends the ENR specification by adding an optional entry. Existing implementations that do not recognize the "client" entry will ignore it without any adverse effects on ENR processing or network behavior.</p> <h2 id="test-cases">Test Cases</h2> <p>A node running Geth version 1.10.0 on the mainnet might have an ENR <code>client</code> entry like:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[&quot;Geth&quot;, &quot;1.10.0&quot;]</span></span></code></pre> <p>A node running an experimental build of Nethermind might include:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[&quot;Nethermind&quot;, &quot;1.9.53&quot;, &quot;7fcb567&quot;]</span></span></code></pre> <p>and an ENR of</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>enr:-MO4QBn4OF-y-dqULg4WOIlc8gQAt-arldNFe0_YQ4HNX28jDtg41xjDyKfCXGfZaPN97I-MCfogeK91TyqmWTpb0_AChmNsaWVudNqKTmV0aGVybWluZIYxLjkuNTOHN2ZjYjU2N4JpZIJ2NIJpcIR_AAABg2lwNpAAAAAAAAAAAAAAAAAAAAABiXNlY3AyNTZrMaECn-TTdCwfZP4XgJyq8Lxoj-SgEoIFgDLVBEUqQk4HnAqDdWRwgiMshHVkcDaCIyw</span></span></code></pre> <p>which can be decoded to yield normal data such as <code>seq</code>, <code>signature</code>, <code>id</code> and <code>secp256k1</code>. Additionally, it would yield the client value of <code>["0x4e65746865726d696e64","0x312e392e3533","0x37666362353637"]</code> or <code>["Nethermind", "1.9.53", "7fcb567"]</code></p> <h2 id="security-considerations">Security Considerations</h2> <p>Introducing identifiable client information could potentially be used for targeted attacks against specific versions or builds known to have vulnerabilities. It is crucial for clients implementing this EIP to consider the implications of disclosing their identity and version. Users or operators should have the ability to opt-out or anonymize this information if desired.</p> <p>Additionally, as this information is self proclaimed, this data <em><strong>MUST NOT</strong></em> be used for anything that requires it to be reliable.</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-22T00:00:00+00:00 2026-02-11T14:48:25+00:00 Qin Wanghttps://github.com/qinwang-git Saber Yuhttps://github.com/OniReimu Shiping Chenshiping.chen@data61.csiro.au https://wg-eips.ritovision.com/7634/

An ERC-721 extension that caps how many times an individual token can be transferred

<h2 id="abstract">Abstract</h2> <p>This standard extends <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> with a mechanism that lets token owners/minters cap how many times a specific token can be transferred. It specifies functions to set and read a per-token transfer limit, to query a per-token transfer count, and defines transfer-time hooks to enforce the cap. The goal is fine-grained, enforceable transfer restrictions while preserving ERC-721 compatibility.</p> <h2 id="motivation">Motivation</h2> <p>Once NFTs are sold, they detach from their minters and can be perpetually transferred. Yet many situations require tighter control over secondary movement.</p> <p>First, limiting the number of transfers can help preserve value (e.g., premium auctions, IP that becomes CC0 after a finite number of transfers, or game items that “wear out” and burn at a threshold).</p> <p>Second, capping transfer frequency can reduce risks from adversarial arbitrage (e.g., HFT-like behavior) by offering an easy-to-deploy throttle.</p> <p>Third, bounding re-staking cycles of NFT positions (e.g., proof-of-restake) can dampen recursive leverage and mitigate bubble dynamics.</p> <h3 id="key-takeaways">Key Takeaways</h3> <p><em>Controlled Value Preservation.</em> Scarcity via a transfer cap can help maintain value over time.</p> <p><em>Ensuring Intended Usage.</em> Limits keep usage aligned with intent (e.g., limited editions less prone to flip cycles).</p> <p><em>Expanding Use Cases.</em> Memberships/licenses with bounded transferability become practical.</p> <p><em>Easy Integration.</em> An extension interface (<code>IERC7634</code>) layers on top of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, easing adoption without breaking compatibility.</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> <ul> <li><code>setTransferLimit</code>: establishes the transfer limit for a <code>tokenId</code>.</li> <li><code>transferLimitOf</code>: returns the transfer limit for a <code>tokenId</code>.</li> <li><code>transferCountOf</code>: returns the current transfer count for a <code>tokenId</code>.</li> </ul> <p><strong>Counting and enforcement scope.</strong> Implementations <strong>MUST</strong> enforce the cap on native ERC-721 transfers of the underlying token (i.e., transfers where <code>from != address(0)</code> and <code>to != address(0)</code>). Incrementing the count <strong>SHOULD</strong> occur only after a successful native transfer. Mint and burn operations MUST NOT increment the count.</p> <p>Implementers <strong>MUST</strong> provide the following interface:</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.8.4</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"> IERC7634 Interface for Transfer-Capped ERC-721 Tokens</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> ERC-7634 is an extension interface intended to be implemented alongside ERC-721</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7634</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 after a successful native transfer when the per-token count increases.</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"> TransferCountIncreased</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"> newCount</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 the per-token transfer limit is set or updated.</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"> TransferLimitUpdated</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"> previousLimit</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> newLimit</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 current transfer count for a 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"> transferCountOf</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Sets the transfer limit for a tokenId. Callable by owner or approved.</span></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 set the limit 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"> limit</span><span class="z-comment"> The maximum number of native transfers allowed.</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"> setTransferLimit</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"> limit</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 transfer limit for a 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"> transferLimitOf</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><h2 id="rationale">Rationale</h2> <h3 id="tracking-and-hooks">Tracking and hooks</h3> <p><code>transferCountOf</code> and <code>transferLimitOf</code> expose state needed to enforce a cap. The count should only increase after a successful native transfer (not on mint/burn). Separating <code>TransferLimitUpdated</code> from <code>TransferCountIncreased</code> makes it clear that the former is an administrative change while the latter is derived from runtime transfers.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is fully compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. Existing contracts can adopt it by adding the new interface and hooks without changing ERC-721 semantics.</p> <h3 id="extensions">Extensions</h3> <p>This standard can be enhanced with additional advanced functionalities alongside existing NFT protocols. For example:</p> <ul> <li> <p>Incorporating a burn function (e.g., <a href="https://wg-eips.ritovision.com/5679/">ERC-5679</a>) would enable NFTs to automatically expire after reaching their transfer limits, akin to the ephemeral nature of Snapchat messages that disappear after multiple views.</p> </li> <li> <p>Incorporating a non-transferring function, as defined in the SBT standards, would enable NFTs to settle and bond with a single owner after a predetermined number of transactions. This functionality mirrors the scenario where a bidder ultimately secures a treasury after participating in multiple bidding rounds.</p> </li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>Below is a recommended pattern. It enforces the cap pre-transfer, increments the count post-transfer, ignores mint/burn for counting, and emits the clarified events. Implementations commonly override <code>_beforeTokenTransfer</code> to enforce <code>transferCount</code> &lt; <code>transferLimit</code> and <code>_afterTokenTransfer</code> to increment the count and emit <code>TransferCountIncreased</code>.</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.8.4</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;./IERC7634.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"> Transfer-Capped ERC-721 (ERC-7634)</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Example implementation of ERC-7634 alongside ERC-721</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC7634</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">IERC7634</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> tokenId =&gt; current transfer count</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> _transferCounts</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> tokenId =&gt; max allowed native transfers</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> _transferLimits</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"> transferCountOf</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"> override</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"> 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;ERC7634: nonexistent token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _transferCounts</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"> setTransferLimit</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"> limit</span><span>)</span><span class="z-storage z-type"> public</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">_isApprovedOrOwner</span><span>(</span><span class="z-entity z-name">_msgSender</span><span>(</span><span>)</span><span>,</span><span> tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC7634: not owner/approved&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> prev </span><span class="z-keyword">=</span><span> _transferLimits</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> _transferLimits</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span> limit</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> TransferLimitUpdated</span><span>(</span><span>tokenId</span><span>,</span><span> prev</span><span>,</span><span> limit</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"> transferLimitOf</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"> override</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"> 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;ERC7634: nonexistent token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _transferLimits</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-storage z-type"> @dev</span><span class="z-comment"> Enforce transfer limit on native transfers (exclude mint/burn).</span></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-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 class="z-keyword"> &amp;&amp;</span><span> to </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> <span class="giallo-l"><span> _transferCounts</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> &lt;</span><span> _transferLimits</span><span>[</span><span>tokenId</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;ERC7634: transfer limit reached&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-variable z-language"> super</span><span>.</span><span class="z-entity z-name">_beforeTokenTransfer</span><span>(</span><span>from</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-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Increment count only after successful native transfer and emit event.</span></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></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> quantity</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-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 class="z-keyword"> &amp;&amp;</span><span> to </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"> unchecked</span><span> {</span><span> _transferCounts</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> +</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"> emit</span><span class="z-entity z-name"> TransferCountIncreased</span><span>(</span><span>tokenId</span><span>,</span><span> _transferCounts</span><span>[</span><span>tokenId</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>_transferCounts</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> ==</span><span> _transferLimits</span><span>[</span><span>tokenId</span><span>]</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Optional: perform action exactly when the cap is reached (e.g., _burn(tokenId))</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-language"> super</span><span>.</span><span class="z-entity z-name">_afterTokenTransfer</span><span>(</span><span>from</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>,</span><span> quantity</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> <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><span class="z-entity z-name">ERC721</span><span>)</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> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC7634</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> <span class="giallo-l"></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <ul> <li> <p>Scope with wrappers. The cap applies only to native <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> transfers of the underlying token. Any owner can cheaply wrap a token and transfer a separate wrapper token; such downstream transfers cannot be prevented without breaking <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> composability. As a result, this standard does not provide an unbypassable guarantee that, for example, a game item will always wear out or that secondary trading is globally capped; it standardizes a primitive for budgeting native transfers that ecosystems may choose to coordinate around. Deployments that want stronger effective guarantees <strong>MAY</strong> add optional mitigations such as recipient allowlists/registries or "compliant wrapper" patterns that mirror counts/limits, trading off openness for enforcement.</p> </li> <li> <p>Limit mutability. Consider making limits immutable once set (or only decreasing), to prevent tampering.</p> </li> <li> <p>Gas. Avoid heavy logic in hooks; extensions (e.g., burn on cap) should remain gas-safe.</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> 2024-02-21T00:00:00+00:00 2026-02-11T14:48:25+00:00 vectorizedhttps://github.com/vectorized Thomashttps://github.com/0xth0mas Quithttps://github.com/quitcrypto Michael Amadihttps://github.com/AmadiMichael cygaarhttps://github.com/cygaar Harrisonhttps://github.com/pop-punk https://wg-eips.ritovision.com/7631/

A specification for a co-joined fungible and non-fungible token pair

<h2 id="abstract">Abstract</h2> <p>A fungible <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token contract and non-fungible <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> token contract can be interlinked, allowing actions performed on one contract to be reflected on the other. This proposal defines how the relationship between the two token contracts can be queried. It also enables accounts to configure whether ERC-721 mints and transfers should be skipped during ERC-20 to ERC-721 synchronization.</p> <h2 id="motivation">Motivation</h2> <p>The ERC-20 fungible and ERC-721 non-fungible token standards offer sufficient flexibility for a co-joined, dual nature token pair. Transfers on the ERC-20 token can automatically trigger transfers on the ERC-721 token, and vice-versa. This enables applications such as native ERC-721 fractionalization, wherein acquiring ERC-20 tokens leads to the automatic issuance of ERC-721 tokens, proportional to the ERC-20 balance.</p> <p>Dual nature token pairs maintain full compliance with both ERC-20 and ERC-721 token standards. This proposal aims to enhance the functionality of dual nature token pairs.</p> <p>To facilitate querying the relationship between the tokens, extension interfaces are proposed for the ERC-20 and ERC-721 tokens respectively. This enables various quality of life improvements such as allowing decentralized exchanges and NFT marketplaces to display the relationship between the tokens.</p> <p>Additionally, users can configure whether they want to skip ERC-721 mints and transfers during ERC-20 to ERC-721 synchronization.</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="overview">Overview</h3> <p>A dual nature token pair comprises of an ERC-20 contract and an ERC-721 contract.</p> <p>For convention, the ERC-20 contract is designated as the base contract, and the ERC-721 contract is designated as the mirror contract.</p> <h3 id="erc-20-extension-interface">ERC-20 Extension Interface</h3> <p>The ERC-20 contract 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"> IERC7631Base</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"> Returns the address of the mirror ERC-721 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"> This method MAY revert or return the zero address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> to denote that a mirror ERC-721 contract has not been linked.</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"> If a non-zero address is returned, the returned address MUST</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> implement `IERC7631Mirror` and its `baseERC20()` method MUST</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> return the address of this 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"> Once a non-zero address has been returned, this method</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST NOT revert and the returned value MUST NOT change.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mirrorERC721</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 ERC-20 contract MAY 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"> IERC7631BaseNFTSkippable</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"> Implementations SHOULD emit this event when the skip NFT status</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> of `owner` is updated to `status`.</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"> The purpose of this event is to signal to indexers that the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> skip NFT status has been </span><span class="z-keyword">changed</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"> ///</span><span class="z-comment"> For simplicity of implementation,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> this event MAY be emitted even if the status is unchanged.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SkipNFTSet</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">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-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Returns true if ERC-721 mints and transfers to `owner` SHOULD be</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> skipped during ERC-20 to ERC-721 synchronization.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Otherwise, returns false.</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"> ///</span><span class="z-comment"> This method MAY revert</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (e.g. contract not initialized, method not supported).</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"> If this method reverts:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Interacting code SHOULD interpret `setSkipNFT` functionality as</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> unavailable and hide any functionality to call `setSkipNFT`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - The skip NFT status for `owner` SHOULD be interpreted as undefined.</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"> Once a true or false value has been returned for a given `owner`,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> this method MUST NOT revert for the given `owner`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getSkipNFT</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Sets the caller&#39;s skip NFT status.</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"> This method MAY revert</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (e.g. insufficient permissions, method not supported).</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"> It is RECOMMENDED to keep this method permissionless.</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"> Emits a {SkipNFTSet} event.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setSkipNFT</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> status</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="erc-721-extension-interface">ERC-721 Extension Interface</h3> <p>The ERC-721 contract 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"> IERC7631Mirror</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"> Returns the address of the base ERC-20 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"> This method MAY revert or return the zero address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> to denote that a base ERC-20 contract has not been linked.</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"> If a non-zero address is returned, the returned address MUST</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> implement `IERC7631Base` and its `mirrorERC721()` method MUST</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> return the address of this 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"> Once a non-zero address has been returned, this method</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST NOT revert and the returned value MUST NOT change.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> baseERC20</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><h2 id="rationale">Rationale</h2> <h3 id="implementation-detection">Implementation Detection</h3> <p>The <code>mirrorERC721</code> and <code>baseERC20</code> methods returning non-zero addresses signal that the ERC-20 and ERC-721 contracts implement the required interfaces respectively. As such, <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> is not required.</p> <p>The <code>getSkipNFT</code> and <code>setSkipNFT</code> methods MAY revert. As contracts compiled with Solidity or Vyper inherently revert on calls to undefined methods, a typical <code>IERC7631Base</code> implementation lacking explicit <code>getSkipNFT</code> and <code>setSkipNFT</code> definitions still complies with <code>IERC7631BaseNFTSkippable</code>.</p> <h3 id="nft-skipping">NFT Skipping</h3> <p>The skip NFT methods allow accounts to avoid having ERC-721 tokens automatically minted to it whenever there is an ERC-20 transfer.</p> <p>They are helpful in the following situations:</p> <ul> <li>Loading vesting contracts with large amounts ERC-20 tokens to be vested to many users.</li> <li>Loading candy machine contracts with large amounts of ERC-20 tokens to sell ERC-721 tokens to customers.</li> <li>Transferring large amounts of ERC-20 tokens in / out of a liquidity pool.</li> <li>Transferring large amounts of ERC-20 tokens between admin accounts.</li> </ul> <p>Including the skip NFT methods in the standard will:</p> <ul> <li>Enable applications to conveniently display the option for users to skip NFTs.</li> <li>Enable applications to transfer any amount of ERC-20 tokens without the O(n) gas costs associated with minting multiple ERC-721 tokens, which can surpass the block gas limit.</li> </ul> <p>These methods are recommended even on EVM chains with low gas costs, because bulk automatic ERC-721 transfers can still surpass the block gas limit.</p> <p>A useful pattern is to make <code>getSkipNFT</code> return true by default if <code>owner</code> is a smart contract.</p> <p>The choice of <code>getSkipNFT</code> returning a boolean value is for simplicity. If more complex behavior is needed, developers may add in extra methods of their own.</p> <h3 id="implementation-conventions">Implementation Conventions</h3> <p>The ERC-20 contract is designated as the base contract for convention, as a typical implementation can conveniently derive ERC-721 balances from the ERC-20 balances. This does not prohibit one from implementing most of the logic in the ERC-721 contract if required.</p> <p>This proposal does not cover the token synchronization logic. This is to leave flexibility for various implementation patterns and novel use cases (e.g. automatically rebased tokens).</p> <h3 id="linking-mechanism">Linking Mechanism</h3> <p>The linking process is omitted for flexibility purposes. Developers can use any desired mechanism (e.g. linking in constructor, initializer, or via custom admin-only public methods on the two contracts). The only restriction is that the pairing must be immutable once established (to simplify indexing logic).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="synchronization-access-guards">Synchronization Access Guards</h3> <p>External methods for synchronization logic must be guarded such that only the other contract is authorized to call them.</p> <h3 id="rare-nft-sniping">Rare NFT Sniping</h3> <p>For dual nature collections that offer ERC-721 tokens with differing rarity levels, the ERC-721 metadata should be revealed in a way that is not easily gameable with metadata scraping and ERC-20 token transfers. A recommendation is to require that an ERC-721 token is held by the same account for some time before revealing its metadata.</p> <h3 id="out-of-gas-denial-of-service">Out-of-gas Denial of Service</h3> <p>Transferring ERC-20 tokens can automatically initiate the minting, transferring, or burning of multiple ERC-721 tokens. This can incur O(n) gas costs instead of the typical O(1) gas costs for ERC-20 tokens transfers. Logic for selecting ERC-721 token IDs can also incur additional gas costs. Synchronization logic must consider ERC-721 related gas costs to prevent out-of-gas denial of service 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> 2024-02-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Chen Liaoyuanhttps://github.com/chenlycly@kip.pro https://wg-eips.ritovision.com/7628/

Introduces ownership shares to ERC-721 tokens, allowing for queryable, transferable, and approvable fractional ownership.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces an attribute of ownership and profit share quantities for each token under an NFT. This attribute signifies a stake in the ownership and profit rights associated with the NFT's specific privileges, enabling the querying, transferring, and approval of these shares, thereby making the shares represented by each token applicable in a broader range of use cases.</p> <h2 id="motivation">Motivation</h2> <p>At times, when we wish to distribute dividends or assign rights to tokens of an NFT based on their share of ownership, it becomes necessary to equip each token with an attribute indicating the number of ownership shares. While <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> allows for the representation of ownership stakes through the balance of a token held by a wallet address, it sacrifices the uniqueness of each token. Conversely, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> maintains the uniqueness of each token but lacks an attribute to signify the share of ownership rights, and its metadata does not allow for the free transfer of these share quantities by the token owner. This extension seeks to merge the features of <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, enabling holders of each share to possess characteristics akin to those of a token owner, thus bridging the gap between share representation and token uniqueness.</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>Implementers of this extension <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">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"> IERC7628</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the number of decimal places used for ownership shares.</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 decimal places for ownership shares.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> shareDecimals</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"> Returns the total sum of ownership shares in existence for all 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"> The</span><span class="z-comment"> total sum of ownership shares.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalShares</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"> Returns the ownership share of the specified 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"> The 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"> The</span><span class="z-comment"> ownership share of the token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> shareOf</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"> Returns the share allowance granted to the specified spender by the owner for the specified 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"> The identifier of 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"> spender</span><span class="z-comment"> The address of the 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"> The</span><span class="z-comment"> share allowance granted to the spender.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> shareAllowance</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"> spender</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"> Approves the specified address to spend a specified amount of shares on behalf of the caller.</span></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 of 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"> spender</span><span class="z-comment"> The address of the 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"> shares</span><span class="z-comment"> The amount of shares to approve.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approveShare</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"> spender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> shares</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"> Transfers ownership shares from one token to another.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> fromTokenId</span><span class="z-comment"> The identifier of the sender 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"> toTokenId</span><span class="z-comment"> The identifier of the recipient 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"> shares</span><span class="z-comment"> The amount of shares to transfer.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferShares</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> fromTokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> toTokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> shares</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"> Transfers ownership shares from one token to another address (resulting in a new token or increased shares at the recipient 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"> fromTokenId</span><span class="z-comment"> The identifier of the sender 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"> to</span><span class="z-comment"> The address of the 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"> shares</span><span class="z-comment"> The amount of shares to transfer.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferSharesToAddress</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> fromTokenId</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"> shares</span><span>)</span><span class="z-storage z-type"> external</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 specified amount of shares to a token, only callable by 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"> tokenId</span><span class="z-comment"> The identifier of 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"> shares</span><span class="z-comment"> The amount of shares to add.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addSharesToToken</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"> shares</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"> Emitted when ownership shares are transferred from one token to another.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> fromTokenId</span><span class="z-comment"> The identifier of the sender 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"> toTokenId</span><span class="z-comment"> The identifier of the recipient 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"> The amount of shares transferred.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SharesTransfered</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> fromTokenId</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> toTokenId</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"> @notice</span><span class="z-comment"> Emitted when an approval is granted for a spender to spend shares on behalf of 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"> tokenId</span><span class="z-comment"> The token identifier.</span></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 of the 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"> amount</span><span class="z-comment"> The amount of shares approved.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SharesApproved</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"> spender</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></span></code></pre><h2 id="rationale">Rationale</h2> <h4 id="share-issuance-to-a-token">Share Issuance to a Token</h4> <p>Issuing additional shares to a token allows for flexible management of ownership stakes in digital assets, catering to the evolving needs of stakeholders. It ensures transparency and security in modifying ownership structures directly on the blockchain, facilitating scenarios like profit sharing or investment adjustments.</p> <h4 id="transferring-shares-to-an-address">Transferring Shares to an Address</h4> <p>Enabling shares to be transferred to an address enhances NFT liquidity and accessibility by allowing fractional ownership. This feature supports diverse use cases like fractional sales or collateralization, making NFTs more adaptable and inclusive for a broader audience.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is fully <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> compatible.</p> <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.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/ERC721.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 class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/security/ReentrancyGuard.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"> ERC7628</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7628</span><span>, </span><span class="z-entity z-name">ERC721</span><span>, </span><span class="z-entity z-name">Ownable</span><span>, </span><span class="z-entity z-name">ReentrancyGuard</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"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> _shareBalances</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-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>)</span><span class="z-storage z-type"> private</span><span> _shareAllowances</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> _totalShares</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> _nextTokenId</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"> initialOwner</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC721</span><span>(</span><span>&quot;MyToken&quot;, &quot;MTK&quot;)</span></span> <span class="giallo-l"><span class="z-entity z-name"> Ownable</span><span>(</span><span>initialOwner)</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"> addSharesToToken</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"> shares</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> override</span><span class="z-entity z-name"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>tokenId </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;ERC7628: tokenId cannot be zero&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _shareBalances</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> shares</span><span>;</span></span> <span class="giallo-l"><span> _totalShares </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span> shares</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> SharesTransfered</span><span>(</span><span class="z-constant">0</span><span>,</span><span> tokenId</span><span>,</span><span> shares</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"> shareDecimals</span><span>(</span><span>)</span><span class="z-storage z-type"> external</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">uint8</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 18</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"> totalShares</span><span>(</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"> override</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> _totalShares</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"> shareOf</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-storage z-type"> override</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> _shareBalances</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"> shareAllowance</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"> spender</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"> override</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> _shareAllowances</span><span>[</span><span>tokenId</span><span>]</span><span>[</span><span>spender</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"> approveShare</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"> spender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> shares</span><span>)</span><span class="z-storage z-type"> external</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>spender </span><span class="z-keyword">!=</span><span class="z-entity z-name"> ownerOf</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC7628: approval to current owner&quot;</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-entity z-name"> ownerOf</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC7628: approve caller is not owner&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _shareAllowances</span><span>[</span><span>tokenId</span><span>]</span><span>[</span><span>spender</span><span>]</span><span class="z-keyword"> =</span><span> shares</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> SharesApproved</span><span>(</span><span>tokenId</span><span>,</span><span> spender</span><span>,</span><span> shares</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"> transferShares</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> fromTokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> toTokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> shares</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> override</span><span class="z-entity z-name"> nonReentrant</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_shareBalances</span><span>[</span><span>fromTokenId</span><span>]</span><span class="z-keyword"> &gt;</span><span class="z-keyword">=</span><span> shares</span><span>,</span><span class="z-string"> &quot;ERC7628: insufficient shares for transfer&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">_isApprovedOrOwner</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> fromTokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC7628: transfer caller is not owner nor approved&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _shareBalances</span><span>[</span><span>fromTokenId</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> shares</span><span>;</span></span> <span class="giallo-l"><span> _shareBalances</span><span>[</span><span>toTokenId</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> shares</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> SharesTransfered</span><span>(</span><span>fromTokenId</span><span>,</span><span> toTokenId</span><span>,</span><span> shares</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"> transferSharesToAddress</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> fromTokenId</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"> shares</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> override</span><span class="z-entity z-name"> nonReentrant</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_shareBalances</span><span>[</span><span>fromTokenId</span><span>]</span><span class="z-keyword"> &gt;</span><span class="z-keyword">=</span><span> shares</span><span>,</span><span class="z-string"> &quot;ERC7628: insufficient shares for transfer&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">_isApprovedOrOwner</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> fromTokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC7628: transfer caller is not owner nor approved&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _nextTokenId</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _safeMint</span><span>(</span><span>to</span><span>,</span><span> _nextTokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _shareBalances</span><span>[</span><span>_nextTokenId</span><span>]</span><span class="z-keyword"> =</span><span> shares</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> SharesTransfered</span><span>(</span><span>fromTokenId</span><span>,</span><span> _nextTokenId</span><span>,</span><span> shares</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"> Helper function to check if an address is the owner or approved</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _isApprovedOrOwner</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-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-keyword"> return</span><span> (</span><span>spender </span><span class="z-keyword">==</span><span class="z-entity z-name"> ownerOf</span><span>(</span><span>tokenId</span><span>)</span><span class="z-keyword"> ||</span><span class="z-entity z-name"> getApproved</span><span>(</span><span>tokenId</span><span>)</span><span class="z-keyword"> ==</span><span> spender </span><span class="z-keyword">||</span><span class="z-entity z-name"> isApprovedForAll</span><span>(</span><span class="z-entity z-name">ownerOf</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span> spender</span><span>)</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> <h4 id="clear-approvals-on-transfer">Clear Approvals on Transfer</h4> <p>When transferring token ownership, it is crucial to clear all existing approvals. This precaution prevents previously authorized parties from retaining access after the token has changed hands.</p> <h4 id="prevent-reentrancy">Prevent Reentrancy</h4> <p>Implementations must guard against reentrancy attacks. This involves ensuring that functions altering balances or ownership are secure against such vulnerabilities, particularly during share transfers.</p> <h4 id="validate-ids-and-addresses">Validate IDs and Addresses</h4> <p>Verifying the legitimacy of token IDs and wallet addresses in all operations is essential. This step helps avoid errors and ensures that tokens and their associated shares are handled correctly.</p> <h4 id="manage-shares-on-ownership-change">Manage Shares on Ownership Change</h4> <p>Proper management of share quantities is vital during a token ownership transfer. It's important to ensure that shares are accurately accounted for and transferred alongside the token to maintain the integrity of ownership stakes.</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-19T00:00:00+00:00 2026-02-11T14:48:25+00:00 Chen Liaoyuanhttps://github.com/chenlycly@kip.pro https://wg-eips.ritovision.com/7627/

End-to-end encryption for sending messages between users.

<h2 id="abstract">Abstract</h2> <p>This proposal implements the capability to securely exchange encrypted messages on-chain. Users can register their public keys and encryption algorithms by registration and subsequently send encrypted messages to other users using their addresses. The interface also includes enumerations for public key algorithms and a structure for user information to support various encryption algorithms and user information management.</p> <h2 id="motivation">Motivation</h2> <p>With the emergence of Layer 2 chains featuring sub-second block times and the introduction of account abstraction, the use of end-to-end encrypted communication has facilitated the proliferation of real-time communication and online chat dApps. Providing a unified interface enables easy integration of encrypted communication into smart contracts, thereby fostering innovation. Standardization promotes interoperability, facilitating seamless communication across platforms.</p> <h2 id="specification">Specification</h2> <h3 id="objectives">Objectives</h3> <ul> <li>Provide a standardized interface for implementing messaging systems in smart contracts, including user registration and message sending functionalities.</li> <li>Enhance flexibility and scalability for messaging systems by defining enumerations for public key algorithms and a structure for user information.</li> <li>Define events for tracking message sending to enhance the observability and auditability of the contract.</li> <li>Using a custom sessionId allows messages to be organized into a conversation.</li> <li>Encrypt message content using the recipient's public key during message transmission.</li> </ul> <h3 id="interface">Interface</h3> <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>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">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"> IERC7627</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"> PublicKeyAlgorithm</span><span> {</span><span class="z-variable z-other z-enummember"> ECDSA</span><span>,</span><span class="z-variable z-other z-enummember"> ED25519</span><span>,</span><span class="z-variable z-other z-enummember"> X25519</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"> PublicKey</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> public_key</span><span>;</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> valid_before</span><span>;</span></span> <span class="giallo-l"><span> PublicKeyAlgorithm algorithm</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"> Events</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"> Event emitted when a message is sent between users.</span></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 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"> to</span><span class="z-comment"> The address of the 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"> keyIndex</span><span class="z-comment"> The index of the public key used to encrypt the message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> sessionId</span><span class="z-comment"> The session ID for the communication</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> encryptedMessage</span><span class="z-comment"> The encrypted message in 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"> MessageSent</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">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> keyIndex</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> sessionId</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> encryptedMessage</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"> Event emitted when a user&#39;s public key is updated.</span></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 user whose public key is updated</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> keyIndex</span><span class="z-comment"> The index of the public key being updated</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> newPublicKey</span><span class="z-comment"> The new public key data</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"> PublicKeyUpdated</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">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> keyIndex</span><span>, </span><span class="z-variable">PublicKey</span><span class="z-variable"> newPublicKey</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 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"> Updates the public key for 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"> _keyIndex</span><span class="z-comment"> The index of the key to be updated</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _publicKey</span><span class="z-comment"> The new public key data</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"> updatePublicKey</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _keyIndex</span><span>,</span><span class="z-storage z-type"> PublicKey</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _publicKey</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"> Sends an encrypted message to 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"> _to</span><span class="z-comment"> The recipient&#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"> _keyIndex</span><span class="z-comment"> The index of the public key used to encrypt the message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _sessionId</span><span class="z-comment"> The session ID for the communication</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _encryptedMessage</span><span class="z-comment"> The encrypted message in bytes</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"> sendMessage</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"> bytes32</span><span class="z-variable z-parameter z-function"> _keyIndex</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _sessionId</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"> _encryptedMessage</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"> Retrieves a public key for a specific user and key 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"> _user</span><span class="z-comment"> The address of 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"> _keyIndex</span><span class="z-comment"> The index of the key to retrieve</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"> public key data associated with the user and key index</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"> getUserPublicKey</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"> bytes32</span><span class="z-variable z-parameter z-function"> _keyIndex</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">PublicKey</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="event-emission-for-off-chain-integration">Event Emission for Off-Chain Integration</h3> <p>By emitting events when messages are sent or public keys are updated, the implementation facilitates seamless integration with off-chain dApps. This enables these dApps to easily track and display the latest messages and updates, ensuring real-time responsiveness and enhancing user interaction.</p> <h3 id="end-to-end-encryption-security">End-to-End Encryption Security</h3> <p>The design ensures that only the owner of an address can update their public key. This restriction preserves the integrity of the end-to-end encryption, making sure that only the intended recipient can decrypt and read the messages, thereby securing communication.</p> <h3 id="session-id-for-conversation-organization">Session ID for Conversation Organization</h3> <p>The use of session IDs in message transactions allows multiple messages to be grouped under specific conversations. This feature is crucial for organizing and managing discussions within a dApp, providing users with a coherent and structured messaging experience.</p> <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.0</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"> ERC7627</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"> Enum to specify the algorithm used for the public key.</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> PublicKeyAlgorithm</span><span> {</span><span class="z-variable z-other z-enummember"> ECDSA</span><span>,</span><span class="z-variable z-other z-enummember"> ED25519</span><span>,</span><span class="z-variable z-other z-enummember"> X25519</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"> Structure to represent a user&#39;s public key.</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> PublicKey</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> public_key</span><span>;</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> valid_before</span><span>;</span></span> <span class="giallo-l"><span> PublicKeyAlgorithm algorithm</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"> Mapping to store public keys for each address. The mapping is by user address and a unique key index.</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">bytes32</span><span class="z-keyword"> =&gt;</span><span> PublicKey</span><span>)</span><span>)</span><span class="z-storage z-type"> public</span><span> pk</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"> MessageSent</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">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> keyIndex</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> sessionId</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> encryptedMessage</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"> PublicKeyUpdated</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">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> keyIndex</span><span>, </span><span class="z-variable">PublicKey</span><span class="z-variable"> newPublicKey</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"> updatePublicKey</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _keyIndex</span><span>,</span><span class="z-storage z-type"> PublicKey</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _publicKey</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span> pk</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>_keyIndex</span><span>]</span><span class="z-keyword"> =</span><span> _publicKey</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> PublicKeyUpdated</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> _keyIndex</span><span>,</span><span> _publicKey</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"> sendMessage</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"> bytes32</span><span class="z-variable z-parameter z-function"> _keyIndex</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _sessionId</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"> _encryptedMessage</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> MessageSent</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> _to</span><span>,</span><span> _keyIndex</span><span>,</span><span> _sessionId</span><span>,</span><span> _encryptedMessage</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"> getUserPublicKey</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"> bytes32</span><span class="z-variable z-parameter z-function"> _keyIndex</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">PublicKey</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> pk</span><span>[</span><span>_user</span><span>]</span><span>[</span><span>_keyIndex</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> <h4 id="utilization-of-latest-secure-encryption-algorithms">Utilization of Latest Secure Encryption Algorithms</h4> <p>When selecting encryption algorithms, it is essential to stay informed about the latest security news and recommendations. Avoid using asymmetric encryption algorithms with known vulnerabilities or those not recommended to ensure the confidentiality and integrity of messages. Regularly update encryption algorithms to address evolving security threats.</p> <h4 id="strict-encryption-using-public-keys-for-message-content">Strict Encryption Using Public Keys for Message Content</h4> <p>To maintain message confidentiality, the content of sent messages must be strictly encrypted using the recipient's public key. Any plaintext information transmitted could lead to information leakage and security risks. Encrypt message content at all times during transmission and storage to prevent unauthorized access to sensitive information.</p> <h4 id="key-management-and-protection">Key Management and Protection</h4> <p>Robust key management and protection measures are necessary for both user public and private keys. Ensure secure storage and transmission of keys to prevent leakage and tampering. Employ multi-factor authentication and key rotation strategies to enhance key security and regularly assess key management processes to mitigate potential security risks.</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-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 0xZeus1111https://github.com/0xZeus1111 Nvuwahttps://github.com/Nvuwa https://wg-eips.ritovision.com/7629/

introduces a single interface for ERC-20/ERC-721 tokens, enabling seamless interaction by defining common functions for both token types.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a protocol that establishes a unified interface for managing both <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> fungible tokens and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> non-fungible tokens (NFTs) on the Ethereum blockchain. By defining a common set of functions applicable to both token types, developers can seamlessly interact with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens using a single interface. This simplifies integration efforts and enhances interoperability within decentralized applications (DApps).</p> <h2 id="motivation">Motivation</h2> <p>The proposal aims to address the demand for assets combining the liquidity of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens and the uniqueness of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens. Current standards present a fragmentation, requiring users to choose between these features. This proposal fills that gap by providing a unified token interface, enabling smooth transitions between <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> characteristics to accommodate diverse blockchain applications.</p> <h2 id="specification">Specification</h2> <ul> <li>Introduces a token contract that combines features from both <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standards.</li> <li>Supports state transitions between <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> modes, facilitating seamless conversion and utilization of both liquidity and non-fungibility.</li> <li>Defines essential functions and events to support token interactions, conversions, and queries.</li> <li>Implements low gas consumption <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> mode to maintain efficiency comparable to typical <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token transfers.</li> </ul> <p>Compliant contracts MUST implement the following Solidity interface:</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.8.0</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">@title</span><span class="z-comment"> ERC-7629 Unify Token Interface</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This interface defines the ERC-7629 Unify Token, which unifies ERC-721 and ERC-20 assets.</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"> IERC7629</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"> ERC-20 Transfer event</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ERC20Transfer</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 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"> ERC-721 Transfer event</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ERC721Transfer</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-comment"> ERC-721 Transfer event</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-comment"> Approval event for ERC-20 and ERC-721</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> <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"> approved</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-comment"> Approval event for ERC-20 and ERC-721</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> <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"> approved</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-comment"> Approval event for ERC-20</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ERC20Approval</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"> approved</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-comment"> ApprovalForAll event for ERC-721</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> <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"> 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 class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ERC-20 to ERC-721 Conversion event</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ERC20ToERC721</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"> amount</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"> ERC-721 to ERC-20 Conversion event</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ERC20ToERC721</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"> amount</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> tokenIds</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 name of 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"> 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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the symbol of 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"> 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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the number of decimals used 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"> decimals</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the total supply of the ERC-20 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"> totalSupply</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">@dev</span><span class="z-comment"> Returns the balance of an address for ERC-20 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"> owner</span><span class="z-comment"> The address to query the 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"> 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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the total supply of ERC-20 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"> erc20TotalSupply</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">@dev</span><span class="z-comment"> Returns the balance of an address for ERC-20 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"> owner</span><span class="z-comment"> The address to query the 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"> erc20BalanceOf</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the total supply of ERC-721 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"> erc721TotalSupply</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">@dev</span><span class="z-comment"> Returns the balance of an address for ERC-721 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"> owner</span><span class="z-comment"> The address to query the 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"> erc721BalanceOf</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> <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 a single 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 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 NFT, or the zero address if there is none</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"> 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">@dev</span><span class="z-comment"> Checks if an operator is approved for all tokens of 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"> The address of the 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"> operator</span><span class="z-comment"> The address of the operator to check.</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"> isApprovedForAll</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"> address</span><span class="z-variable"> operator</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">@dev</span><span class="z-comment"> Returns the remaining number of tokens that spender will be allowed to spend on behalf of 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"> The address of the 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"> spender</span><span class="z-comment"> The address of the 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"> allowance</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"> address</span><span class="z-variable"> spender</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">@dev</span><span class="z-comment"> Returns the array of ERC-721 token IDs owned by 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"> The address to query the tokens 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"> owned</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 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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the address that owns a specific ERC-721 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"> The token 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"> 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 class="z-variable"> erc721Owner</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 URI for a specific ERC-721 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"> The token 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"> 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 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 disapprove the operator to spend or transfer all of the sender&#39;s 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"> spender</span><span class="z-comment"> The address of the 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"> amountOrId</span><span class="z-comment"> The amount of ERC-20 tokens or ID of ERC-721 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"> approve</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> spender</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amountOrId</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">@dev</span><span class="z-comment"> Set or unset the approval of an operator for all 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"> operator</span><span class="z-comment"> The address of the 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"> approved</span><span class="z-comment"> The approval status.</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"> 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"> 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"> Transfer ERC-20 tokens or ERC-721 token from one address to another.</span></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 to transfer ERC-20 tokens or ERC-721 token from.</span></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 transfer ERC-20 tokens or ERC-721 token 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"> amountOrId</span><span class="z-comment"> The amount of ERC-20 tokens or ID of ERC-721 tokens 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"> amountOrId</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></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 ownership of an NFT from one 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 unless `msg.sender` is the current owner, an authorized</span></span> <span class="giallo-l"><span class="z-comment"> * operator, or the approved address for this NFT. Throws if `_rom` is</span></span> <span class="giallo-l"><span class="z-comment"> * not the current owner. Throws if `_to` is the zero address. Throws if</span></span> <span class="giallo-l"><span class="z-comment"> * `tokenId` is not a valid NFT. When transfer is complete, this function</span></span> <span class="giallo-l"><span class="z-comment"> * checks if `to` is a smart contract (code size &gt; 0). If so, it calls</span></span> <span class="giallo-l"><span class="z-comment"> * `onERC721Received` on `to` and throws if the return value is not</span></span> <span class="giallo-l"><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 class="z-storage z-type">@param</span><span class="z-variable z-other"> from</span><span class="z-comment"> The current owner 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"> to</span><span class="z-comment"> The new 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"> The NFT 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"> data</span><span class="z-comment"> Additional data with no specified format, sent in call to `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"> 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"> tokenId</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>;</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 ownership of an NFT from one 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"> This works identically to the other function with an extra data parameter,</span></span> <span class="giallo-l"><span class="z-comment"> * except this function just sets data to &quot;&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"> from</span><span class="z-comment"> The current owner 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"> to</span><span class="z-comment"> The new 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"> The NFT 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"> 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"> 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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Transfer ERC-20 tokens to an 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"> The address to transfer ERC-20 tokens 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"> amount</span><span class="z-comment"> The amount of ERC-20 tokens 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"> 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"> 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> <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"> Retrieves the unit value associated with 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"> The</span><span class="z-comment"> unit value.</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"> getUnit</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">@dev</span><span class="z-comment"> Converts ERC-721 token to ERC-20 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 unique identifier of the ERC-721 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"> erc721ToERC20</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"> Converts ERC-20 tokens to an ERC-721 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"> The amount of ERC-20 tokens to convert.</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"> erc20ToERC721</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></span> <span class="giallo-l"></span> <span class="giallo-l"></span></code></pre><h2 id="rationale">Rationale</h2> <p>Common Interface for Different Token Types:</p> <ul> <li>Introduces a unified interface to address the fragmentation caused by separate <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standards.</li> <li>Standardizes functions like transferFrom, mint, and burn, enabling developers to interact with both token types without implementing distinct logic.</li> </ul> <p>Transfer Functionality:</p> <ul> <li>Includes transferFrom function for seamless movement of tokens between addresses, as it's a core component of both <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standards.</li> </ul> <p>Minting and Burning:</p> <ul> <li>Incorporates mint and burn functions for creating and destroying tokens, essential for managing token supply and lifecycle.</li> </ul> <p>Balance and Ownership Queries:</p> <ul> <li>Provides functions like balanceOf and ownerOf for retrieving token balances and ownership information, crucial for both <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens.</li> </ul> <p>Compatibility and Extensibility:</p> <ul> <li>Ensures compatibility with existing <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> implementations, minimizing disruption during transition.</li> <li>Allows extension with additional functions and events for future enhancements.</li> </ul> <p>Security Considerations:</p> <ul> <li>Implements mechanisms to prevent common issues like reentrancy attacks and overflows, ensuring the security and robustness of the unified interface.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The proposed this proposal introduces a challenge in terms of backward compatibility due to the distinct balance query mechanisms utilized by <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standards. <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> employs <code>balanceOf</code> to check an account's token balance, while <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> uses <code>balanceOf</code> to inquire about the quantity of tokens owned by an account. To reconcile these differences, the ERC must consider providing either two separate functions catering to each standard or adopting a more generalized approach.</p> <h3 id="compatibility-points">Compatibility Points</h3> <p>The primary compatibility point lies in the discrepancy between <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>'s balanceOf and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>'s balanceOf functionalities. Developers accustomed to the specific balance query methods in each standard may face challenges when transitioning to this proposal.</p> <h3 id="proposed-solutions">Proposed Solutions</h3> <p>Dual Balance Query Functions:</p> <p>Introduce two distinct functions, <code>erc20BalanceOf</code> and <code>erc721TotalSupply</code>, to align with the conventions of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, respectively. Developers can choose the function based on the token type they are working with.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>Due to the dual nature of this proposal, potential differences in protocol interpretation may arise, necessitating careful consideration during development.</li> <li>Comprehensive security audits are recommended, especially during mode transitions by users, to ensure the safety of user assets.</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> 2024-02-13T00:00:00+00:00 2026-02-11T14:49:28+00:00 Toni Wahrstätterhttps://github.com/nerolation Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/7623/

Increase calldata cost to reduce maximum block size

<h2 id="abstract">Abstract</h2> <p>The current calldata pricing permits EL payloads of up to 7.15 MB, while the average size is much smaller at around 100 KB. This EIP proposes adjusting the calldata cost to reduce the maximum possible block size and its variance without negatively impacting regular users. This is achieved by increasing calldata costs for transactions that predominantly post data.</p> <h2 id="motivation">Motivation</h2> <p>The block gas limit has not been increased since <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a>, while the average size of blocks has continuously increased due to the growing number of rollups posting data to Ethereum. Moreover, calldata costs have remained unchanged since <a href="https://wg-eips.ritovision.com/2028/">EIP-2028</a>. <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> introduces blobs as a preferred method for data availability (DA). This transition demands a reevaluation of calldata pricing, especially in order to address the disparity between average and maximum block sizes. By introducing a floor cost dependent on the ratio of gas spent on EVM operations to calldata, this proposal aims to reduce the maximum block size to make room for additional blobs or potential block gas limit increases.</p> <h2 id="specification">Specification</h2> <table><thead><tr><th>Parameter</th><th>Value</th></tr></thead><tbody> <tr><td><code>STANDARD_TOKEN_COST</code></td><td><code>4</code></td></tr> <tr><td><code>TOTAL_COST_FLOOR_PER_TOKEN</code></td><td><code>10</code></td></tr> </tbody></table> <p>Let <code>tokens_in_calldata = zero_bytes_in_calldata + nonzero_bytes_in_calldata * 4</code>.</p> <p>Let <code>isContractCreation</code> be a boolean indicating the respective event.</p> <p>Let <code>execution_gas_used</code> be the gas used for EVM execution with the gas refund subtracted.</p> <p>Let <code>INITCODE_WORD_COST</code> be 2 as defined in <a href="https://wg-eips.ritovision.com/3860/">EIP-3860</a>.</p> <p>The current formula for determining the total gas used per transaction (<code>tx.gasUsed</code>) is equivalent to:</p> <pre class="giallo z-code"><code data-lang="python"><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 class="z-constant"> STANDARD_TOKEN_COST</span><span class="z-keyword"> *</span><span> tokens_in_calldata</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> execution_gas_used</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> isContractCreation</span><span class="z-keyword"> *</span><span> (</span><span class="z-constant">32000</span><span class="z-keyword"> +</span><span class="z-constant"> INITCODE_WORD_COST</span><span class="z-keyword"> *</span><span> words</span><span>(</span><span>calldata</span><span>)</span><span>)</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>The formula for determining the gas used per transaction changes to:</p> <pre class="giallo z-code"><code data-lang="python"><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> tokens_in_calldata</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> execution_gas_used</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> isContractCreation</span><span class="z-keyword"> *</span><span> (</span><span class="z-constant">32000</span><span class="z-keyword"> +</span><span class="z-constant"> INITCODE_WORD_COST</span><span class="z-keyword"> *</span><span> words</span><span>(</span><span>calldata</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> TOTAL_COST_FLOOR_PER_TOKEN</span><span class="z-keyword"> *</span><span> tokens_in_calldata</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>Any transaction with a gas limit below <code>21000 + TOTAL_COST_FLOOR_PER_TOKEN * tokens_in_calldata</code> or below its intrinsic gas cost (take the maximum of these two calculations) is considered invalid. This limitation exists because transactions must cover the floor price of their calldata without relying on the execution of the transaction. There are valid cases where <code>gasUsed</code> will be below this floor price, but the floor price needs to be reserved in the transaction gas limit.</p> <h2 id="rationale">Rationale</h2> <p>The current maximum EL payload size is approximately 1.79 MB (<code>30_000_000/16</code>). It is possible to create payloads filled with zero bytes that expand to 7.15 MB. However, since blocks are typically compressed with Snappy at the P2P layer, zero-byte-heavy EL payloads generally compress to under 1.79 MB. The implementation of <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> increased the maximum possible compressed block size to approximately 2.54 MB.</p> <p>This proposal aims to increase the cost of calldata to 10/40 gas for transactions that do not exceed a certain threshold of gas spent on EVM operations relative to gas spent on calldata. This change will significantly reduce the maximum block size by limiting the size of data-heavy transactions that can fit into a single block. By increasing calldata costs from 4/16 to 10/40 gas per byte, for data-heavy transactions this EIP aims to reduce the possible EL payload size to approximately 0.72 MB (<code>30_000_000/40</code>) without affecting the majority of users. Other adversarial block constructions can have a non-compressible EL payload size of approximately 1.26MiB.</p> <p>Notably, regular users (e.g. sending ETH/Tokens/NFTs, engaging in DeFi, social media, restaking, bridging, etc.), who do not use calldata predominantly for DA, may remain unaffected. The calldata cost for transactions involving significant EVM computation remains at 4/16 gas per byte, so those transactions are unaffected.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backwards incompatible gas repricing that requires a scheduled network upgrade.</p> <p>Wallet developers and node operators MUST update gas estimation handling to accommodate the new calldata cost rules. Specifically:</p> <ol> <li> <p><strong>Wallets</strong>: Wallets using <code>eth_estimateGas</code> MUST be updated to ensure that they correctly account for the <code>TOTAL_COST_FLOOR_PER_TOKEN</code> parameter. Failure to do so could result in underestimating gas, leading to failed transactions.</p> </li> <li> <p><strong>Node Software</strong>: RPC methods such as <code>eth_estimateGas</code> MUST incorporate the updated formula for gas calculation. Node developers MUST ensure compatibility with the updated calldata pricing logic.</p> </li> </ol> <p>Users can maintain their usual workflows without modification, as wallet and RPC updates will handle these changes.</p> <h2 id="security-considerations">Security Considerations</h2> <p>As the maximum possible block size is reduced, no security concerns have been raised.</p> <p>In some cases, it might seem advantageous to combine two transactions into one to reduce costs. For example, bundling a transaction that relies heavily on calldata but minimally on EVM resources with another that does the opposite. However, this is not a significant concern for several reasons:</p> <ol> <li>This type of bundling is already possible today. Merging multiple transactions can save the 21,000 gas cost for each additional transaction beyond the first, a feature explicitly supported in <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a>.</li> <li>Such bundling does not compromise the block size reduction objectives of this EIP.</li> <li>In practice, transaction bundling is often impractical due to challenges such as trust and coordination requirements.</li> </ol> <p>These factors ensure that transaction bundling does not pose a significant issue.</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-11T00:00:00+00:00 2026-02-11T14:48:25+00:00 Dominic Ryderdom@alvaraprotocol.io Callum Mitchell-Clarkhttps://github.com/AlvaraProtocolcallum@alvaraprotocol.io Joey van Ettenjoe@alvaraprotocol.io Michael Rydermike@alvaraprotocol.io https://wg-eips.ritovision.com/7621/

Collateralized, tokenized funds with adjustable weights and reserves and minting/burning of LP tokens.

<h2 id="abstract">Abstract</h2> <p>The Basket Token Standard (BTS) allows for the implementation of multi-asset tokenized funds. This standard provides basic functionality for anyone to deploy unique, non-fungible BTS tokens that can contain an unlimited number of underlying <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens.</p> <p>The deployer receives a BTS token representative of their ownership of the fund, as well as liquidity provider (LP) tokens representative of their percentage share of the fund (100% at time of deployment but changing as other wallets contribute/withdraw). Whenever a contribution is made to a BTS, BTS LP tokens are minted and distributed to the contributor’s wallet (representative of their share of the fund); when a withdrawal is made from a BTS, the BTS LP tokens are burned and funds returned to the withdrawer’s wallet.</p> <p>The BTS has a rebalance function which allows for a BTS owner to change the percentage share of the fund that each underlying token makes up. Tokens can be removed entirely or added through this function after a BTS has already been minted.</p> <p>By leveraging the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard as a representative token of ownership when minting the BTS, the tokenized fund can also be fully manageable and transferable on-chain.</p> <h2 id="motivation">Motivation</h2> <p>The motivation is to provide infrastructure that will enable the on-chain creation and management of asset-backed tokenized investment funds as no such standardized infrastructure curently exists. Providing the necessary infrastructure will help facilitate the onboarding of traditional fund management onto blockchain. No existing standard is capable of achieving this as they lack the required features for third party contribution, namely the minting of LP tokens when contribution is made. The <a href="https://wg-eips.ritovision.com/7621/">ERC-7621</a> is the only token standard that facilitates this with a rebalance function required for effective fund management, and LP token distribution and burning, required for third party participation.</p> <h2 id="specification">Specification</h2> <h3 id="bts">BTS</h3> <p>BTS is a smart contract enabling the creation of on-chain tokenized funds backed by assets, allowing users to manage assets and liquidity through functions like initialization, contribution, withdrawal, rebalancing, and token distribution.</p> <h4 id="purpose">Purpose</h4> <p>The purpose of the BTS is to allow anyone to build an on-chain tokenized fund that is fully asset backed using on-chain liquidity.</p> <h4 id="key-functions">Key Functions</h4> <p><code>initialize</code>: Initializes a new BTS with name, symbol, creator, tokens, weights, token URI, and optional auto-rebalance setting.</p> <p><code>contribute()</code>: Allows users to add ETH to the basket, purchasing proportional amounts of included tokens based on predefined weights.</p> <p><code>withdraw(uint256 _liquidity)</code>: Allows BTS LP holders to withdraw from the basket, receiving corresponding tokens.</p> <p><code>withdrawETH(uint256 _liquidity)</code>: Allows BTS LP holders to withdraw ETH from the basket, equivalent to the value of their BTS LP tokens.</p> <p><code>rebalance(address[] memory _newTokens, uint256[] memory _newWeights)</code>: The owner can manually adjust the types and weights of tokens in the basket.</p> <p><code>getTokenDetails</code>: Returns details of a token at a given index (address and weight).</p> <p><code>totalTokens</code>: Returns the total number of tokens in the basket.</p> <h4 id="distribution-of-bts-tokens">Distribution of BTS tokens</h4> <p>The distribution of BTS tokens occurs during the mint function. The creator sends ETH to the contract, and the contract then swaps the ETH for user designated <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens based on predefined weights. After the swaps, it mints a BTS token (NFT) for the sender using the initialize function of the BTS contract as well as BTS LP tokens. This BTS token is a representation of ownership and allows management of the BTS.</p> <h4 id="distribution-of-bts-lp-tokens">Distribution of BTS LP tokens</h4> <p>The distribution of BTS LP tokens occurs during the mint and contribute functions. After swapping ETH for the relevant <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens, the contract mints BTS LP tokens (representing the user's share of the total BTS), and then mints BTS LP tokens using the mint function of the <code>BTSPair</code> contract. The BTS LP tokens represent the liquidity provided by the user to the specified BTS pair (<code>btsPair</code>). The distribution is logged through the <code>ContributedToBTS</code> event.</p> <h4 id="burning-the-bts-lp-tokens">Burning the BTS LP tokens</h4> <p>The burning of BTS LP tokens occurs during the <code>withdraw</code> function. Users can call this function, specifying the amount of BTS LP tokens they want to withdraw. The contract then transfers the specified amount of BTS LP tokens from the user to the BTS pair contract (<code>btsPair</code>). The burn function of the <code>IBTSPair</code> contract is called, which decreases the user's BTS LP token balance and returns an array of amounts representing the underlying tokens withdrawn. This array of amounts is logged through the <code>WithdrawnFromBTS</code> event.</p> <h4 id="events">Events</h4> <p><code>ContributedToBTS(address indexed bts, uint256 amount)</code>: Event when someone adds ETH to the basket.</p> <p><code>WithdrawnFromBTS(address indexed bts, uint256[] amounts)</code>: Event when BTS LP holder withdraws tokens from the basket.</p> <p><code>WithdrawnETHFromBTS(address indexed bts, uint256 amount)</code>: Event when BTS LP holder withdraws ETH from the basket.</p> <p><code>RebalanceBTS(address indexed bts, uint256[] oldWeights, uint256[] newWeights)</code>: Event when the owner manually rebalances the basket.</p> <h3 id="btspair"><code>BTSPair</code></h3> <h4 id="purpose-1">Purpose</h4> <p><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token representing liquidity in a BTS.</p> <h4 id="key-functions-1">Key Functions</h4> <p><code>initialize</code>: Initializes a new <code>BTSPair</code> with a name and tokens.</p> <p><code>rebalance()</code>: Allows the owner to manually adjust the types and weights of tokens in the pair.</p> <p><code>updateTokens(...)</code>: Allows the owner to change the types of tokens in the pair.</p> <p><code>mint(...)</code>: Creates new BTS LP tokens and adjusts token reserves.</p> <p><code>burn(...)</code>: Destroys BTS LP tokens and adjusts token reserves.</p> <h2 id="rationale">Rationale</h2> <!-- TODO --> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p><code>BTS</code>: Implemented using a combination of OpenZeppelin's <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> <code>URIStorage</code> and <code>Ownable</code> contracts, along with custom logic for token management and rebalancing.</p> <p><code>Factory</code>: Implemented using <code>ClonesUpgradeable</code> to deploy new <code>BTS</code> and <code>BTSPair</code> contracts.</p> <p><code>BTSPair</code>: Implemented using <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> <code>Upgradeable</code> and <code>Ownable</code> contracts, along with custom logic for liquidity tracking and rebalancing.</p> <p><code>IUniswap</code>: Not implemented, as it only defines interfaces for external contracts.</p> <!-- TODO: Remove this section or actually add the code (here or in your assets directory.) --> <h2 id="security-considerations">Security Considerations</h2> <!-- TODO --> <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-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Qi Zhouhttps://github.com/qizhou Nicolas Deschildrehttps://github.com/nand2 https://wg-eips.ritovision.com/7617/

In ERC-5219 resolve mode, add ability to fetch a Web3 URL resource made of several chunks

<h2 id="abstract">Abstract</h2> <p>In the context of the <a href="https://wg-eips.ritovision.com/6860/">ERC-6860</a> <code>web3://</code> standard, this ERC extends the <a href="https://wg-eips.ritovision.com/6944/">ERC-6944</a> resolve mode: This standard defines a new optional <code>web3-next-chunk</code> HTTP header returned by the <code>request()</code> call, that contains a <code>web3://</code> URL pointing to the next data chunk of the resource data. Chunks are streamed to the <code>web3://</code> client, and it loops until the <code>web3-next-chunk</code> header is no longer present.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum RPC endpoints have a gas limit, which can be reached when serving large content. By adding a chunking feature, we add the possibility to serve arbitrary sized content.</p> <h2 id="specification">Specification</h2> <p>In the <a href="https://wg-eips.ritovision.com/6944/">ERC-6944</a> resolve mode, this standard introduces the new optional <code>web3-next-chunk</code> HTTP header, to be returned in the <code>headers</code> <code>KeyValue</code> array of the <code>request()</code> method defined in <a href="https://wg-eips.ritovision.com/6944/">ERC-6944</a>.</p> <p>The value of the header is either a complete <code>web3://</code> URL, or a relative one. The target smart contract must use the <a href="https://wg-eips.ritovision.com/6944/">ERC-6944</a> resolve mode.</p> <p>When processing the result of the initial <code>request()</code> call, the protocol return the HTTP status code, HTTP headers and body right away to the <code>web3://</code> client. If a <code>web3-next-chunk</code> header is present, it parse the URL. If the URL is invalid, or the target smart contract is not using the <a href="https://wg-eips.ritovision.com/6944/">ERC-6944</a> resolve mode, the HTTP data streaming is ended with an error. Otherwise it call the <code>request()</code> method, ignore the returned <code>statusCode</code>, send the <code>body</code> data as the next chunk of data, and if a <code>web3-next-chunk</code> header is again present, loops until no more are present.</p> <h2 id="rationale">Rationale</h2> <p>The use of a header pointing to the next chunk was chosen because it does not require changes to the <a href="https://wg-eips.ritovision.com/6944/">ERC-6944</a> <code>request()</code> interface, and the use of a <code>web3://</code> URL in the header add flexibility to the means to provide the next chunk.</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-02-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Qi Zhouhttps://github.com/qizhou Nicolas Deschildrehttps://github.com/nand2 https://wg-eips.ritovision.com/7618/

In ERC-5219 resolve mode, add ability to decode a compressed resource before serving it to the client

<h2 id="abstract">Abstract</h2> <p>In the context of the <a href="https://wg-eips.ritovision.com/6860/">ERC-6860</a> <code>web3://</code> standard, this ERC extends the <a href="https://wg-eips.ritovision.com/6944/">ERC-6944</a> resolve mode: This standard specifies that if a <code>Content-Encoding</code> header is returned by the <code>request()</code> call, then the returned data is decoded if necessary according to the specified algorithm before being returned to the client.</p> <h2 id="motivation">Motivation</h2> <p>As storage in blockchains is expensive, it is optimal to try to store and serve compressed assets. Standard HTTP uses the <code>Accept-Encoding</code>/<code>Content-Encoding</code> mechanism, in which the client specifies their supported compression algorithms, and the server returns the data compressed in one of them. It is not optimal to replicate this mechanism in the <code>web3://</code> protocol, due to blockchain storage and computation constraints. Moreover, it is not possible to blindly serve content with a fixed <code>Content-Encoding</code> header, because the HTTP client may not implement the compression algorithm.</p> <p>By specifying a list of supported compression algorithms, optionally doing the decompression at the protocol side and serving the data to the client, we can safely store compressed data and serve it.</p> <h2 id="specification">Specification</h2> <p>In the <a href="https://wg-eips.ritovision.com/6944/">ERC-6944</a> resolve mode, this standard indicates that if a <code>Content-Encoding</code> HTTP header (in the returned <code>headers</code> <code>KeyValue</code> array of the <code>request()</code> method) is provided, and if it is not part of the supported algorithms provided by the client in the <code>Accept-Encoding</code> header, or the client did not provide an <code>Accept-Encoding</code> header, then the protocol MUST decode the content before forwarding it to the <code>web3://</code> client.</p> <p>The protocol MUST support the following content encodings: <code>gzip</code>, <code>br</code> (brotli). If the protocol is to decode the content, and if the advertized <code>Content-encoding</code> is not part of this list, an error indicating an unsupported content encoding MUST be sent to the client. Once decoded, the decompressed data is sent to the client. The <code>Content-Encoding</code> header MUST NOT be forwarded to the client when the protocol decodes the content.</p> <h2 id="rationale">Rationale</h2> <p>We add this feature to the <a href="https://wg-eips.ritovision.com/6944/">ERC-6944</a> resolve mode because it can be added without changes the interface. To stay as close as possible to standard HTTP, we don't introduce a new HTTP header but reuse the known <code>Content-Encoding</code> header.</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-02-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv https://wg-eips.ritovision.com/7632/

Enable tokens to have a string name and be able to convert between name and id.

<h2 id="abstract">Abstract</h2> <p>Extends tokens using <code>uint256 tokenId</code> to support <code>tokenName</code> in type <code>string</code> and be able to convert backward to <code>tokenId</code>.</p> <h2 id="motivation">Motivation</h2> <p>For Marketplaces, Explorers, Wallets, DeFi and dApps to better display and operate NFTs that comes with a name.</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 support <code>tokenName</code> and mapping between <code>tokenName</code> and <code>tokenId</code> in one of the following ways:</li> </ol> <ul> <li>1a all compliant contracts are RECOMMENDED to implement the following interfaces: <code>IERC_NamedTokenCore</code>,</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"> IERC_NamedTokenCore</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> idToName</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">string</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> nameToId</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"> _tokenName</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></span></code></pre> <p>and it should satisfy the behavior rules that:</p> <ul> <li>1a.1. when a new name is instroduced, it is RECOMMENDED to emit an event <code>newName(uint256 indexed tokenId, string tokenName)</code>.</li> <li>1a.2. tokenId and tokenName MUST be two-way single mapping, meaning if tokenId exists, tokenName MUST exist and vice versa and <code>tokenId = nameToId(idToName(tokenId))</code> and <code>tokenName = idToName(nameToId(tokenName))</code> MUST hold true.</li> </ul> <ul> <li>1b. if the compliant doesn't implement <code>IERC_NamedTokenCore</code>, it MAY follow the default mapping rule between <code>tokenId</code> and <code>tokenName</code> <code>uint256 tokenId = uint256(keccak256(tokenName))</code>.</li> </ul> <ol start="2"> <li> <p>All method involving <code>tokenId</code> for a compliant contract is RECOMMENDED to have a counterpart method end with <code>ByName</code> that substitute all pamameters of <code>uint256 tokenId</code> with <code>string memory tokenName</code>, and the behavior of the counterpart method MUST be consistent with the original method.</p> </li> <li> <p>Compliant contract MAY implement one or more of following extra interface</p> </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_NamedTokenExtension</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isValidTokenName</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"> _tokenName</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 class="z-storage z-type"> function</span><span class="z-entity z-name"> normalizeTokenName</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"> _tokenName</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><h2 id="rationale">Rationale</h2> <ol> <li> <p>We allow default way to map <code>tokenId</code> and <code>tokenName</code> for convenience, but we also allow contract to implement their own way to map <code>tokenId</code> and <code>tokenName</code> for flexibility.</p> </li> <li> <p>We consider providing an interface for</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backwards compatible with token contracts using <code>uint256 tokenId</code> as the unique identifier.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This proposal assume that both <code>tokenName</code> and <code>tokenId</code> are unique amongst all tokens.</p> <p>If tokenNames are not normalize, two distinct tokenNames may confuse users as they look alike. Contract developer shall declare normalization mechanism if non-unique <code>tokenName</code> is allowed using <code>IERC_NamedTokenExtension</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-07T00:00:00+00:00 2026-02-11T14:48:25+00:00 Laurent Castillohttps://github.com/lcastillo-ledger Derek Reinhttps://github.com/arein Pierre Aounhttps://github.com/paoun-ledger Arik Galanskyhttps://github.com/arikg Bartosz Rozwarskihttps://github.com/llbartekll Kaan Uzdoganhttps://github.com/kuzdogan https://wg-eips.ritovision.com/7730/

JSON format describing how to clear-sign smart contract calls and typed messages.

<h2 id="abstract">Abstract</h2> <p>This specification defines a JSON format carrying additional information required to correctly display structured data for human verification on wallet screens or for machine consumption e.g. by transaction simulation engines.</p> <p>The <a href="https://wg-eips.ritovision.com/7730/">ERC-7730</a> specification enriches type data contained in the ABIs and schemas of structured messages (structures like the calldata of an EVM transaction, an <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> message or an <a href="https://wg-eips.ritovision.com/4337/">EIP-4337</a> User Operation) with additional formatting information and dynamic value interpolation, enabling both human-readable display with contextual intent descriptions and machine-interpretable data processing. For instance, a solidity field containing an amount, encoded as an uint256, can be converted to the right magnitude and appended with the correct ticker for display, or parsed programmatically for transaction simulation. Fields containing encrypted values (such as FHE-encrypted amounts in confidential token standards like <a href="https://wg-eips.ritovision.com/7984/">ERC-7984</a>) can also be annotated with decryption context, enabling wallets to either decrypt and display the plaintext value or present a meaningful fallback.</p> <p>Wallets and automated systems will use curated ERC-7730 files alongside the raw data to sign in order to construct appropriate interfaces for their respective use cases.</p> <p>This enables significantly improved signing user experiences and lower end-user risk from frontend and phishing attacks.</p> <h2 id="motivation">Motivation</h2> <p>Properly validating a transaction on a hardware wallet's screen (also known as Clear Signing) is a key element of good security practices for end users when interacting with any Blockchain. Unfortunately, most data to sign, even enriched with the data structure description (like ABIs or EIP-712 types) are not self-sufficient in terms of correctly displaying them to users for review. Among other things:</p> <ul> <li>Function name or main message type is often a developer oriented name and does not translate to a clear intent for the user</li> <li>Fields in the data to sign are tied to primitive types only, but those can be displayed in many different ways. For instance, integers can be displayed as percentages, dates, etc...</li> <li>Some fields require additional metadata to be displayed correctly, for instance token amounts require knowledge of the decimals and the ticker, as well as where to find the token address itself to be correctly formatted.</li> <li>Some values can be encrypted, such as encrypted amounts in confidential tokens following <a href="https://wg-eips.ritovision.com/7984/">ERC-7984</a>. These values cannot be directly interpreted, so additional context must be provided to enable wallets to decrypt and display them for users.</li> </ul> <p>This specification intends to provide a simple, open standard format to provide wallets with the additional information required to properly format a structured data to sign for review by users.</p> <p>Providing this additional formatting information requires deep knowledge of the way a smart contract or message is going to be used. It is expected that app developers will be the best placed to write such a file. The intent of an open standard is to only write this file once and have it work with most wallets supporting this standard.</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="simple-example">Simple example</h3> <p>The following is an example of how to clear sign a <code>transfer</code> function call on an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> contract.</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://eips.ethereum.org/assets/eip-7730/erc7730-v2.schema.json</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">context</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">$id</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Example ERC-20</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">contract</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">deployments</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 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">address</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 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"> 137</span><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">0xc2132D05D31c914a87C6611C10748AEb04B58e8F</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">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 42161</span><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">0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9</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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">metadata</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">owner</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Example</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">contractName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Example Token</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">info</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">url</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://example.io/</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">deploymentDate</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2017-11-28T12:41:21Z</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> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">display</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">formats</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">transfer(address to,uint256 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">intent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Send</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Send {value} to {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">fields</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">path</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">label</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">format</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">tokenAmount</span><span class="z-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">tokenPath</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 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">path</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">label</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">format</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">addressName</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>The <code>$schema</code> key refers to the latest version of this specification json schema (version 1 at the time of writing).</p> <p>The <code>context</code> key is used to provide binding context information for this file. It can be seen as a set of <em>constraints</em> on the structured data being reviewed, indicating whether the ERC-7730 file is valid for this data. A wallet MUST ensure these constraints are met before ERC-7730 formatting information is applied to the data being signed.</p> <p>In this example, the context section indicates that the ERC-7730 file should only be applied to the Example smart contract whose deployment addresses are provided. Once the contract is matched, wallets use the <code>display.formats</code> entry itself to derive the function selector, parameter layout, and user-facing labels.</p> <p>The <code>metadata</code> section contains constants that can be trusted when the ERC-7730 file is applicable for the given context. This section is typically used to:</p> <ul> <li>Provide displayable information about the recipient of the contract call / message</li> <li>Provide displayable values of enumeration or encoded id parameters, typically smart contract / message specific</li> <li>Provide common constants used by the various formats defined in the file</li> </ul> <p>In this example, the metadata section contains only the recipient information, in the form of a displayable name (<code>owner</code> key), contract displayable name (<code>contractName</code> key) and additional information (<code>info</code> key) that MAY be used by wallets to provide details about the recipient.</p> <p>Finally, the <code>display</code> section contains the definitions of how to format each field of targeted contract calls under the <code>formats</code> key.</p> <p>In this example, the function being described is identified by its human-readable ABI fragment <code>transfer(address to,uint256 value)</code>. Wallets strip the parameter names to compute the type-only signature <code>transfer(address,uint256)</code>, hash it, and match the resulting selector <code>0xa9059cbb</code> against the calldata.</p> <ul> <li>The <code>intent</code> key contains a human-readable string that wallets SHOULD display to explain to the user the intent of the function call.</li> <li>The <code>fields</code> key contains all the parameters formatting information</li> <li>The <code>interpolatedIntent</code> key is a suggested short string representation of intent and fields that wallet CAN use instead of having a dedicated layout.</li> </ul> <p>In this example, the <code>to</code> parameter and the <code>value</code> parameter SHOULD both be displayed, one as an address replaceable by a trusted name (ENS or others), the other as an amount formatted using metadata of the target ERC-20 contract.</p> <h3 id="versioning">Versioning</h3> <p>The version of the specification used by the 7730 file is specified by linking to the reference schema file under the <code>$schema</code> key.</p> <p>The current version of the specification is <code>2</code> at the time of writing. The reference schema for version <code>2</code> is <a href="https://wg-eips.ritovision.com/7730/./assets/erc7730-v2.schema.json">here</a>.</p> <h3 id="common-concepts">Common concepts</h3> <h4 id="key-naming-convention">Key naming convention</h4> <p>In all the specification, key names starting with <code>$</code> are <em>internal</em> and have no value beyond readability of the specification file itself. They should not be used in any function to build the UI to review structured data.</p> <h4 id="structured-data">Structured data</h4> <p>This specification intends to be extensible to describe the display formatting of any kind of <em>structured data</em>.</p> <p>By <em>Structured data</em>, we target any data format that has:</p> <ul> <li>A well-defined <em>type</em> system; the data being described itself being of a specific top-level type</li> <li>A description of the type system, the <em>schema</em>, that should allow splitting the data into <em>fields</em>, each field clearly identified with a <em>path</em> that can be described as a string.</li> </ul> <p>Displaying structured data is often done by wallets to review its content before authorizing an action in the form of a <em>signature</em> over some serialization of the structured data. As such, the structured data is contained in a <em>container structure</em>:</p> <ul> <li>Container structure has a well-defined <em>signature</em> scheme (a serialization scheme, a hashing scheme, and signature algorithm).</li> <li>The container structure does not necessarily follow the same type system as the structured data.</li> <li>Wallets receive the full container structure and uses the signature scheme to generate a signature on the overall structure.</li> </ul> <p><img src="https://wg-eips.ritovision.com/7730/./assets/structured-data.svg" alt="Structured Data and Container" /></p> <p>Current specification covers EVM smart contract calldata:</p> <ul> <li>Defined in Solidity</li> <li>The schema is the function ABI (derived from the matched <code>display.formats</code> function fragment)</li> <li>The container structure is an EVM Transaction serialized in RLP encoding</li> </ul> <p>It also supports EIP-712 messages</p> <ul> <li>Defined in EIP-712</li> <li>The schema is extracted from the type string representation carried in the <code>display.formats</code> message fragments.</li> <li>An EIP-712 message is self-contained, the signature is applied to the hashed message itself following EIP-712 specification.</li> </ul> <p>The <em>schema</em> is defined by the binding context together with the selected display entry. For contracts, the matched <code>display.formats</code> key provides the full function signature (types and parameter names); for EIP-712 messages, the matched <code>display.formats</code> provides the type encoding of the message. Both form of type definition allows defining unique <em>paths</em> pointing to specific fields in the data.</p> <p>Formats are dependent on and defined for the underlying <em>types</em> on the structured data. The <a href="https://wg-eips.ritovision.com/7730/#reference">Reference</a> section covers formats and types supported by this current version of the specification.</p> <p>It is sometime necessary for formatting of fields of the structured data to reference values of the <em>container structure</em>. These values are dependent on the container structure itself and are defined in the <a href="https://wg-eips.ritovision.com/7730/#reference">Reference</a> section.</p> <h4 id="path-references">Path references</h4> <p>This specification uses a limited <a rel="external" href="https://www.rfc-editor.org/rfc/rfc9535">json path</a> notation to reference values that can be found in multiple json documents.</p> <p>Limitation to the json path specification are the following:</p> <ul> <li> <p>Paths MUST use the dot notation, including for slice and array selectors (i.e. an element of an array should be selected through <code>array_name.[index]</code>)</p> </li> <li> <p>Only name, index and slices selectors are supported.</p> </li> <li> <p>Slices selectors MUST NOT contain the optional step. Start index is inclusive, end index is exclusive. Start or end index can be omitted to indicate the beginning or end of the array.</p> </li> </ul> <p>In addition, additional <em>roots</em> are introduced to support description of paths over multiple files in a single common notation. The root node identifier indicates which document or data location this path references, according to the following table:</p> <table><thead><tr><th>Root</th><th>Short summary</th></tr></thead><tbody> <tr><td><code>#</code></td><td>Structured data schema — decoded function parameters or EIP‑712 message fields</td></tr> <tr><td><code>$</code></td><td>ERC‑7730 specification file (after merging includes)</td></tr> <tr><td><code>@</code></td><td>Container-level values (transaction or message metadata)</td></tr> </tbody></table> <p>Notes:</p> <ul> <li>Omitting the root makes the path relative to the structure being described. If there is no enclosing container, a relative path is equivalent to starting with <code>#.</code>.</li> </ul> <h5 id="structured-data-decoded"><code>#</code> — structured data (decoded)</h5> <p>Paths with the <code>#</code> root refer to fields in the structured data being signed — e.g. decoded function arguments for contract calldata or fields of an EIP‑712 message. Names of the path selectors match the schema of the transaction or message, found in the keys under <code>display.formats</code>. Values come from the serialized structured data once decoded by the wallet.</p> <p><em>Examples</em></p> <ul> <li><code>#.params.amountIn</code> — the <code>amountIn</code> field inside top-level <code>params</code>.</li> <li><code>params.amountIn</code> (relative) — equivalent when the path is resolved relative to the structured data.</li> <li><code>#.details.[]</code> refers to the array with the Permit Details of a PermitBatch message</li> </ul> <h5 id="merged-erc-7730-file"><code>$</code> — merged ERC‑7730 file</h5> <p>Paths with the <code>$</code> root point to values in the ERC‑7730 file itself after any <code>includes</code> have been merged by the consumer. Use <code>$</code> to reference metadata, definitions, enums, maps and any constants authored in the specification.</p> <p><em>Examples</em></p> <ul> <li><code>$.metadata.enums.interestRateMode</code> — enumeration values defined in the spec.</li> <li><code>$.display.definitions.minReceiveAmount</code> — a shared field definition.</li> </ul> <h5 id="container-transaction-message"><code>@</code> — container (transaction / message)</h5> <p>The <code>@</code> root names values coming from the container that wraps the structured data (for example, an EVM transaction or an EIP‑712 message). These values are container-specific; see the <a href="https://wg-eips.ritovision.com/7730/#reference">Reference</a> section for the canonical list of container fields (e.g. <code>@.from</code>, <code>@.to</code>, <code>@.value</code>, <code>@.chainId</code>).</p> <p><em>Examples</em></p> <ul> <li><code>@.value</code> — native currency value of an EVM transaction.</li> <li><code>@.to</code> — transaction destination (contract address).</li> </ul> <h5 id="path-slices">Path slices</h5> <p>For paths referring to structured data fields, if a field has a variable length primitive type (like <code>bytes</code> or <code>string</code> in solidity), a slice selector can be appended to the path, to refer to the specific set of bytes indicated by the slice. A slice selector can also be appended to arrays to select only the specified part of the array.</p> <p><em>Examples</em></p> <ul> <li><code>#.data.path.[0].path.[-1].to</code> or <code>data.path.[0].path.[-1].to</code> refers to the field <code>to</code> taken from last member of <code>path</code> array, itself taken from first member of enclosing <code>path</code> array, itself part of top level <code>data</code> structure.</li> <li><code>#.params.path.[:20]</code> or <code>#.params.path.[0:20]</code> refers to the first 20 bytes of the <code>path</code> byte array</li> <li><code>#.params.path.[-20:]</code> refers to the last 20 bytes of the <code>path</code> byte array</li> </ul> <h4 id="value-interpolation">Value interpolation</h4> <p>The <code>interpolatedIntent</code> field supports embedding formatted field values directly within intent strings using interpolation syntax. This allows constructing dynamic, context-aware descriptions of transactions and messages as an alternative to using individual <code>intent</code> and <code>fields</code>.</p> <p>The <code>interpolatedIntent</code> makes transaction intents significantly shorter and easier to read by presenting all relevant information in a single, natural language sentence rather than as separate labeled fields. This is particularly valuable for:</p> <ul> <li>Reducing the cognitive load on users reviewing transactions</li> <li>Displaying concise summaries on resource-constrained devices</li> <li>Enabling clear descriptions of batch transactions (e.g., <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a>), where multiple operations can be concatenated into a single readable sentence</li> </ul> <p><strong>Interpolation syntax</strong></p> <p>Values are interpolated using curly braces containing a path reference: <code>{path}</code>. The path MUST follow the <a href="https://wg-eips.ritovision.com/7730/#path-references">path reference rules</a> and can reference:</p> <ul> <li>Structured data fields (e.g., <code>{to}</code>, <code>{params.amountIn}</code>)</li> <li>Container values (e.g., <code>{@.value}</code>, <code>{@.from}</code>)</li> <li>Metadata constants (e.g., <code>{$.metadata.constants.nativeAssetAddress}</code>)</li> </ul> <p>Interpolated intents MUST only refer to paths that are noted as always visible (i.e. <code>visible</code> key in the field formatter is <code>always</code> or not present).</p> <p><strong>Formatting behavior</strong></p> <p>When a wallet processes an <code>interpolatedIntent</code>:</p> <ol> <li>The wallet MUST identify all interpolation expressions <code>{path}</code> in the string</li> <li>For each expression, the wallet MUST resolve the path and locate the corresponding field format specification in the <code>fields</code> array</li> <li>The wallet MUST apply the field's <code>format</code> and <code>params</code> to format the value</li> <li>The wallet MUST replace the interpolation expression with the formatted value</li> <li>If any interpolation fails (path not found, formatting error, etc.), the wallet MUST fall back to displaying the regular <code>intent</code> field</li> </ol> <p><strong>Escaping</strong></p> <p>To include literal curly braces in the intent text, escape them by doubling: <code>{{</code> for <code>{</code> and <code>}}</code> for <code>}</code>.</p> <p><strong>Examples</strong></p> <p><em>Simple token transfer:</em></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">intent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Send</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Send {value} to {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">fields</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">path</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 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">addressName</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">path</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 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">tokenAmount</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-support">&quot;</span><span class="z-support">tokenPath</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></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Displays as: <strong>"Send 100 USDT to cyberdrk.eth"</strong></p> <p><em>Simple encrypted token transfer:</em></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">intent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Send</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Send {value} to {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">fields</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">path</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 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">addressName</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">path</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 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">tokenAmount</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-support">&quot;</span><span class="z-support">tokenPath</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><span class="z-support"> &quot;</span><span class="z-support">encryption</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">scheme</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">fhevm</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">plaintextType</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">fallbackLabel</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">[Encrypted Amount]</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>}</span></span></code></pre> <p>Displays as:</p> <ul> <li>When decryption is available: <strong>"Send 100 USDT to cyberdrk.eth"</strong></li> <li>When decryption is not available: <strong>"Send [Encrypted Amount] to cyberdrk.eth"</strong></li> </ul> <p><em>Swap with native currency:</em></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">intent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Swap</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Swap {amountIn} for at least {amountOutMinimum}</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">fields</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">amountIn</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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">tokenAmount</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-support">&quot;</span><span class="z-support">tokenPath</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">tokenIn</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">amountOutMinimum</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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">tokenAmount</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-support">&quot;</span><span class="z-support">tokenPath</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">tokenOut</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> <p>Displays as: <strong>"Swap 1000 USDC for at least 0.25 WETH"</strong></p> <p><em>Using container values:</em></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">intent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Wrap ETH</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Wrap {@.value} ETH for WETH</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">fields</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">path</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 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">amount</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> <p>Displays as: <strong>"Wrap 0.5 ETH for WETH"</strong></p> <p><em>Escaping literal braces:</em></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">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Execute {{function}} with {amount} tokens</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Displays as: <strong>"Execute {function} with 100 tokens"</strong></p> <h4 id="organizing-files">Organizing files</h4> <p>Smart contracts and EIP-712 messages are often re-using common interfaces or types that share similar display formatting. This specification supports a basic inclusion mechanism that enables sharing files describing specific interfaces or types.</p> <p>The <code>includes</code> top-level key is a URL pointing to an ERC-7730 file that MUST follow this specification.</p> <p>A wallet using an ERC-7730 file including another file SHOULD merge those files into a single reference file. When merging, conflicts between common unique keys are resolved by prioritizing the including file.</p> <p><em>Merging field format specifications</em></p> <p>Special care must be taken when merging <a href="https://wg-eips.ritovision.com/7730/#field-format-specification">field format specifications</a>. These objects are grouped in an array under the <code>fields</code> key, allowing ordering of field formatters. When merging the two arrays, a wallet SHOULD:</p> <ul> <li>Merge together objects sharing the same <code>path</code> value, overriding parameters of the included file with those of the including file.</li> <li>Append objects with <code>path</code> values not part of the included file to the resulting array.</li> </ul> <p><em>Example</em></p> <p>This file defines a generic ERC-20 interface for a single <code>approve</code> 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">display</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">formats</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">approve(address spender,uint256 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">intent</span><span class="z-support">&quot;</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 class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">fields</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">path</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">label</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">format</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">addressName</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">path</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">label</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">format</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">tokenAmount</span><span class="z-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">tokenPath</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">threshold</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x8000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">thresholdLabel</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Unlimited</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> <p>Note that there are no keys for binding the contract to a specific address or owner, nor any contract specific metadata.</p> <p>The following file would include this generic interface and bind it to the specific USDT contract, overriding the threshold value to one relative to USDT:</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">context</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">$id</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Example Contract</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">contract</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">deployments</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">address</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 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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">includes</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">./example-erc20.json</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">metadata</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">owner</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Example</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">contractName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Example Token</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">info</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">url</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://example.io/</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">deploymentDate</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2017-11-28T12:41:21Z</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">token</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">ticker</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">STABLE</span><span class="z-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">Example Stablecoin</span><span class="z-punctuation z-definition z-string">&quot;</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"> 6</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">display</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">formats</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">approve(address spender,uint256 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">fields</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">path</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">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">threshold</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xFFFFFFFFFFFFFFFFFF</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> <p>Note that the keys under <code>context.contract</code> would be merged together to construct a full contract binding object. The field formatter <code>value</code> parameter <code>threshold</code> is overridden with value <code>0xFFFFFFFFFFFFFFFFFF</code>.</p> <h3 id="context-section"><code>Context</code> section</h3> <p>The <code>context</code> section describes a set of <em>constraints</em> that must be verified by the structured data and container structure before formatting them using the ERC-7730 file. A wallet MUST verify that the structured data and container it is trying to sign matches the constraints of the <code>context</code> section.</p> <p>The current version of this specification only supports two types of binding context, EVM smart contracts and EIP-712 domains.</p> <p>All context support an <code>$id</code> sub-key as an internal identifier (only relevant to provide a human-readable name to the ERC-7730 file)</p> <h4 id="evm-smart-contract-binding-context-denoted-calldata">EVM smart contract binding context (denoted 'calldata')</h4> <p>The <code>contract</code> sub-key is used to introduce an EVM smart contract binding context, with the following constraints expressed as sub-keys of <code>contract</code>.</p> <p><strong><code>contract.deployments</code></strong></p> <p>An array of deployments options. Wallets MUST verify that the target chain and contract address of the containing transaction either:</p> <ul> <li>Match one of these deployment options</li> <li>Is a <em>proxy</em> pointing to one of the deployment option (see <a href="https://wg-eips.ritovision.com/7730/#proxy-support">Proxy support</a>)</li> </ul> <p>A deployment option is an object with:</p> <ul> <li><code>chainId</code>: an <a href="https://wg-eips.ritovision.com/155/">EIP-155 identifier</a> of the chain the described contract is deployed on.</li> <li><code>address</code>: the address of the deployed contract on specified <code>chainId</code> chain.</li> </ul> <p><strong><code>contract.abi</code></strong> <em>(deprecated)</em></p> <p>Legacy ABI attachment kept for backward compatibility. Authors SHOULD prefer <code>display.formats</code> and avoid relying on this key, as it will be removed in a future revision.</p> <p><strong><code>contract.factory</code></strong></p> <p>An object describing the factory used to deploy smart contracts that can be clear signed using the ERC-7730 file.</p> <p>A factory is a json object with:</p> <ul> <li><code>deployEvent</code> key, specifying the solidity signature of the events emitted when deploying a clear-signable contract.</li> <li><code>deployments</code> key: an array of deployment options as in <code>contract.deployments</code>. These deployments represent the addresses at which the <em>factory</em> is deployed.</li> </ul> <p>To verify a factory constraints a wallet MUST check that:</p> <ul> <li>The current transaction destination address is included in an event of signature <code>factory.deployEvent</code></li> <li>The emitter of the event is a factory contract deployed at an address matching one of the deployment option in <code>factory.deployments</code></li> </ul> <h4 id="eip-712-messages-binding-context-denoted-messages">EIP-712 messages binding context (denoted 'messages')</h4> <ul> <li>The <code>eip712</code> sub-key is used to introduce an EIP-712 message type to bind to:</li> </ul> <p><strong><code>eip712.schemas</code></strong> <em>(deprecated)</em></p> <p>Legacy Schema attachment kept for backward compatibility. Authors SHOULD prefer <code>display.formats</code> and avoid relying on this key, as it will be removed in a future revision.</p> <p><strong><code>eip712.domain</code></strong></p> <p>The <code>domain</code> constraint is a json object with simple key-value pairs, describing a set of values that the <em>EIP-712 Domain</em> of the message MUST match.</p> <p>A wallet MUST verify that each key-value pair in this <code>domain</code> binding matches the values of the <code>domain</code> key-value pairs of the message. Note that the message can have more keys in its <code>domain</code> than those listed in the ERC-7730 file. An EIP-712 domain is a free-form list of keys, but those are very common to include:</p> <ul> <li><code>name</code>: the name of the message verifier</li> <li><code>version</code>: the version of the message</li> <li><code>chainId</code>: an <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> identifier of the chain the message is bound to</li> <li><code>verifyingContract</code>: the address the message is bound to</li> </ul> <p>Note that <code>chainId</code> and <code>verifyingContract</code> can also be bound to their values thanks to the <code>eip712.deployments</code> constraint, in a more flexible way (supporting multiple deployment values).</p> <p><strong><code>eip712.deployments</code></strong></p> <p>An array of deployments options.</p> <p>When an <code>eip712.deployments</code> constraint is set, the wallet MUST verify that:</p> <ul> <li>The message being displayed has both <code>domain.chainId</code> and <code>domain.verifyingContract</code> keys</li> <li>The <code>chainId</code> and <code>verifyingContract</code> values in the domain either <ul> <li>Match ONE of the deployment option specified in <code>eip712.deployments</code></li> <li>Is a <em>proxy</em> pointing to one of the deployment options (see <a href="https://wg-eips.ritovision.com/7730/#proxy-support">Proxy support</a>)</li> </ul> </li> </ul> <p>A deployment option is an object with:</p> <ul> <li><code>chainId</code>: an EIP-155 identifier of the chain the described contract is deployed on.</li> <li><code>address</code>: the address of the deployed contract on specified <code>chainId</code> chain.</li> </ul> <p><strong><code>eip712.domainSeparator</code></strong></p> <p>An hex string containing the value of the <em>domainSeparator</em> to check.</p> <p>Wallet MUST verify that the message <em>EIP-712 Domain</em> hashes (as defined in EIP-712) to the value in <code>eip712.domainSeparator</code>.</p> <p>When the exact construction of the EIP-712 domain is not known (for instance, when the smart contract code only contains the hash value of the domain separator), <code>domainSeparator</code> and <code>domain.verifyingContract</code> can still be used to target the right message recipients.</p> <p><em>Examples</em></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">context</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">eip712</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">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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Permit2</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">deployments</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">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000022D473030F116dDEE9F6B43aC78BA3</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">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 42161</span><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">0x000000000022D473030F116dDEE9F6B43aC78BA3</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> <p>The previous snippet defines a context for a <code>Permit2</code> EIP-712 message (types have been omitted for readability).</p> <p>The <code>domain</code> key indicates that the message signed domain MUST contain a <code>name</code> key of value <code>Permit2</code>. The <code>deployments</code> key means that the domain must contain both <code>chainId</code> and <code>verifyingContract</code> keys and they MUST match one of the deployment options (here, on ETH mainnet and Arbitrum).</p> <h3 id="metadata-section"><code>Metadata</code> section</h3> <p>The <code>metadata</code> section contains information about constant values relevant in the scope of the current contract / message (as matched by the <code>context</code> section).</p> <p>In the context of wallets and clear signing, these constant values are either used to construct the UI when approving the signing operation, or to provide parameters / checks on the data being signed. But these constant values are relevant outside of the scope of wallets, and should be understood as reference values concerning the bound contract / message.</p> <p>All keys but the <code>metadata.owner</code> key are optional.</p> <p><strong><code>metadata.owner</code></strong></p> <p>A key containing a displayable name of the <em>owner</em> of the contract or of the verifying contract for a message.</p> <p>Wallet MAY use this value to display the target of the interaction being reviewed.</p> <p><strong><code>metadata.contractName</code></strong></p> <p>A key containing a displayable name of the contract or of the verifying contract for a message.</p> <p>Wallet MAY use this value to display the target of the interaction being reviewed.</p> <p><strong><code>metadata.info</code></strong></p> <p>A key containing additional structured info about the <em>owner</em> of the contract:</p> <ul> <li><code>deploymentDate</code> is the date of deployment of the contract (or verifying contract)</li> <li><code>url</code> is the official URL of the owner</li> </ul> <p>A wallet MAY use this information to display additional details about the targeted contract.</p> <p><strong><code>metadata.token</code></strong></p> <p>The <code>token</code> key is only relevant for <code>contract</code> ERC-7730 files and only for contracts supporting an ERC-20 interface.</p> <p>It contains the ERC-20 metadata when the contract itself does not support the optional calls to retrieve it. It SHOULD NOT be present if the contract does support the <code>name()</code>, <code>symbol()</code> and <code>decimals()</code> smart contract calls.</p> <p>The ERC-20 token metadata for the contract described is in the sub-keys <code>name</code>, <code>ticker</code> and <code>decimals</code> and contains the values that the correponding function calls would have returned.</p> <p><strong><code>metadata.constants</code></strong></p> <p>This key contains in a json object all the constants that can be re-used as parameters in the formatters, or that make sense in the context of this contract / message.</p> <p>It is a list of key / value pairs, the key being used to reference this constant (as a <em>path</em> starting with a root node <code>$.</code> i.e. <code>$.metadata.constants.KEY_NAME</code>).</p> <p><em>Example</em></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">metadata</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">constants</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">nativeAssetAddress</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE</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>This snippet introduces a constant <code>nativeAssetAddress</code> (an address typically used to represent the native network underlying currency, which is smart contract specific). This constant can be referenced using the path <code>$.metadata.constants.nativeAssetAddress</code></p> <p><strong><code>metadata.maps</code></strong></p> <p>Sometimes constants are dependant on some part of the context of the transaction, for instance a token address used by a contract might depend on the deployment chain. <code>maps</code> key allow an efficient representation of those types of context-dependent constants.</p> <p>Each key under the <code>maps</code> object is a <em>map</em> name.</p> <p>A map is a json object with two keys:</p> <ul> <li>The <code>keyType</code> key contains an non normative indication of the expected type of the map key passed when referencing the map.</li> <li>The <code>values</code> key contains a list of key / value pairs, each key being used to match the data pointed to in the reference <code>keyPath</code> key. The corresponding value is used as the context-dependent constant when referenced in the <code>display</code> section.</li> </ul> <p>Maps references can be used anywhere a parameter with constant value would be used. A map reference is a json object with two keys:</p> <ul> <li>The <code>map</code> key refers to the map to use to resolve the constant value, using a path starting with root node <code>$.</code> (i.e. <code>$.metadata.maps.MAP_NAME</code>).</li> <li>The <code>keyPath</code> key refers to the path to use to retrieve the map key to use for the resolution.</li> </ul> <p>A wallet MUST replace a path to a map using the value matching the <code>keyPath</code> parameter. In case no values matches the wallet MUST consider the 7730 file invalid for the transaction.</p> <p>An example can be found in <a href="https://wg-eips.ritovision.com/7730/./assets/example-maps.json">example-maps.json</a> and <a href="https://wg-eips.ritovision.com/7730/./assets/example-maps-pools.json">example-maps-pools.json</a>.</p> <p><em>Examples</em></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">metadata</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">maps</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">underlyingToken</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">keyPath</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">values</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">1</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xaabbccddeeff...</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">17000</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x112233445566...</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">display</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">formats</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">deposit(amount)</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">intent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Deposit</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">fields</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">path</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">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Deposit 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">format</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">tokenAmount</span><span class="z-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">token</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">$.metadata.maps.underlyingToken</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> <p>This example shows a deposit function that takes as only input the amount of a token hardcoded in the contract. The token address deposited changes based on the chain the contract is deployed to. The <code>underlyingToken</code> map allows defining the hardcoded values of the underlying token based on the chainId of the transaction context (as specified in <code>"keyPath": "@.chainId"</code>).</p> <p><strong><code>metadata.enums</code></strong></p> <p>The <code>enums</code> key contains displayable values for parameters that are enumerations (in a loose sense including parameters taking fixed number of well known values). These <code>enums</code> are used to replace specific parameter values with a human-readable one.</p> <p>Each key of the <code>enums</code> object is an <em>enumeration</em> name. Enumeration names can be referred to in the <code>display</code> section formatters by using a path starting with root node <code>$.</code> (i.e. <code>$.metadata.enums.ENUM_NAME</code>).</p> <p>An enum is a json object with a flat list of key / value pairs, each key being the enumeration <em>value</em> to replace, and the value being the display string to use instead of the enumeration value.</p> <p><em>Examples</em></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">metadata</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">enums</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">interestRateMode</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">1</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">stable</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">2</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">variable</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 snippet introduces an enumeration describing the displayable values of an integer parameter used to represent multiple modes of interest rates. It can be referenced using the path <code>$.metadata.enums.interestRateMode</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">display</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">formats</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">repay(address asset,uint256 amount,uint256 interestRateMode)</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">$id</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">repay</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">intent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Repay loan</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Repay {amount} of {interestRateMode} rate loan</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">fields</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">path</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">format</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">tokenAmount</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Amount to repay</span><span class="z-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 class="z-support"> &quot;</span><span class="z-support">tokenPath</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">asset</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> {</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">interestRateMode</span><span class="z-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">enum</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Interest rate mode</span><span class="z-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 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">$.metadata.enums.interestRateMode</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 class="giallo-l"><span>}</span></span></code></pre> <p>In this example, the <code>interestRateMode</code> field is formatted using the enumeration defined under <code>$.metadata.enums.interestRateMode</code>.</p> <h3 id="display-section"><code>Display</code> section</h3> <p>The <code>display</code> section contains the actual formatting instructions for each field of the bound structured data. It is split into two parts, a <code>display.definitions</code> key that contains common formats that can be re-used in the other parts and a <code>display.formats</code> key containing the actual format instructions for each function / message type bound to the specification file.</p> <p><strong><code>display.definitions</code></strong></p> <p>The <code>definitions</code> key is an object in which each sub-key is a <a href="https://wg-eips.ritovision.com/7730/#field-format-specification"><em>field format specification</em></a>. The sub-key name is the name of the common definition and is used to refer to this object in the form of a path starting with root node <code>$.</code> (i.e. <code>$.display.definitions.DEF_NAME</code>).</p> <p>Definitions don't usually include the <code>path</code> or <code>value</code> key of a <a href="https://wg-eips.ritovision.com/7730/#field-format-specification"><em>field format specification</em></a>, since they are intended for re-use in other fields specifications, that will specify locally what path they apply to.</p> <p><em>Example</em></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">display</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">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">sendAmount</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">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Amount to Send</span><span class="z-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">tokenAmount</span><span class="z-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">tokenPath</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">fromToken</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">nativeCurrencyAddress</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">$.display.constants.addressAsEth</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> <p>This snippet defines a common formatter for an amount to send that can be used by a simple reference to the path <code>$.display.definitions.sendAmount</code>.</p> <p><strong><code>display.formats</code></strong></p> <p>The <code>formats</code> key is an object containing the actual information used to format the structured data. It is a json object in which each sub-key is a specific function call (for contracts) or a specific message type (for EIP-712) being described. The values are each a <a href="https://wg-eips.ritovision.com/7730/#structured-data-format-specification"><em>structured data format specification</em></a>.</p> <p><strong>Contract keys</strong></p> <p>For contract calldata, this specification only covers functions. Each key MUST be a human-readable ABI function fragment that includes parameter names, for example <code>transfer(address to,uint256 value)</code> or <code>submitOrder((address token,uint256 amount) order,bytes32 salt)</code>.</p> <ul> <li>Keys MUST use canonical Solidity type names: <code>uint256</code>, <code>bytes32</code>, <code>address</code>, <code>bool</code>, tuple syntax <code>(…)</code>, dynamic arrays <code>type[]</code>, and fixed arrays <code>type[N]</code>. Aliases (e.g., <code>uint</code>) are NOT permitted, commas MUST NOT be followed by spaces, and there MUST be exactly one space between each type and its parameter name.</li> <li>Parameter names in the fragment MUST match the names used throughout the formatting specification; wallets derive all display paths from these names.</li> <li>Overloaded functions are distinguished solely by their type signatures. Parameter names do not affect selector matching.</li> </ul> <p><strong>Selector matching (contracts)</strong></p> <p>Wallets MUST match calldata to a <code>display.formats</code> entry using the following procedure:</p> <ol> <li>Parse the key and drop parameter names to obtain the canonical type-only signature (e.g., <code>transfer(address,uint256)</code>).</li> <li>Compute <code>keccak256(&lt;type-only signature&gt;)[:4]</code>.</li> <li>Compare the resulting selector to the transaction calldata selector; a match selects the corresponding format specification.</li> </ol> <p>If multiple keys share the same type-only signature, wallets MUST treat this as an invalid descriptor.</p> <p><strong>Decoding and parameter names</strong></p> <p>Once a format entry is selected, wallets MUST decode calldata arguments using the canonical type vector derived from the key. Parameter names, <code>fields[].path</code> entries, and <code>{placeholders}</code> in <code>interpolatedIntent</code> MUST all use the names from the key (e.g., <code>value</code>, <code>order.amount</code>, <code>recipients[0]</code>).</p> <p>Paths are relative to the matched function parameters unless prefixed by another root node; for example, <code>to</code>, <code>order.price</code>, and <code>recipients[0]</code> point to decoded arguments, while <code>@.value</code> references the transaction container.</p> <p>Placeholders in strings MUST use <code>{&lt;path&gt;}</code> with the same path semantics.</p> <p><strong>Unknown selectors</strong></p> <p>If no key matches the calldata selector, wallets SHOULD display a safe fallback (for example, "Unknown function" alongside raw arguments) and MUST NOT attempt to apply any unrelated format specifications.</p> <p><em>Minimal contract examples</em></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">display</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">formats</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">transfer(address to,uint256 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">intent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Send</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Send {value} to {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">fields</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">path</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 class="z-support"> &quot;</span><span class="z-support">label</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 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">tokenAmount</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">path</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 class="z-support"> &quot;</span><span class="z-support">label</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 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">addressName</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></code></pre><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">display</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">formats</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">submitOrder((address token,uint256 amount,uint256 price) order,bytes32 salt)</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">intent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Place order</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Buy {order.amount} @ {order.price}</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">fields</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">order.token</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">label</span><span class="z-support">&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-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">addressName</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">order.amount</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">label</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 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">number</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">order.price</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Price</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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">number</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">path</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 class="z-support"> &quot;</span><span class="z-support">label</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 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">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> }</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="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">display</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">formats</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">airdrop(address[] recipients,uint256[3] values)</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">intent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Airdrop</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Airdrop to {recipients[0]} (+{recipients.length} total)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">fields</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">recipients[0]</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">First recipient</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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">addressName</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">values[0]</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Tier 1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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">tokenAmount</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></code></pre> <p><strong>EIP-712 keys</strong></p> <p>For EIP-712, the key names MUST be the string returned by the <code>encodeType</code> function defined in EIP-712 specification applied to the primary type of the message.</p> <p>During the EIP-712 signature process, wallets will compute the type hash from the message. This type hash MUST match the hash computed from the <code>display.formats</code> key in use: <code>keccak256(encodeType(typeOf(s))) == keccak256(TYPE_KEY)</code></p> <p><em>Example</em></p> <p>In the sample EIP-712 message included in the specification <a href="../assets/eip-712/Example.js">here</a>, the key used to describe the message would be the string <code>Mail(Person from,Person to,string contents)Person(string name,address wallet)</code>.</p> <h4 id="structured-data-format-specification">Structured data format specification</h4> <p>A <em>Structured data format specification</em> is used to describe how to format all the fields of a single function or EIP-712 message. It is contained in a single json object under each sub-keys of <code>display.formats</code>.</p> <p><strong><code>$id</code></strong></p> <p>This key is purely internal and used to specify a human-readable identifier for this specification.</p> <p><strong><code>intent</code></strong></p> <p>Use to specify the <em>intent</em> of the function call or message signature in a user-friendly way.</p> <p>An intent can take two forms:</p> <ul> <li>A simple string with human-readable content</li> <li>A json object with a flat list of string key-value pairs, representing more complex intents. Both keys and values should be human-readable and user-friendly.</li> </ul> <p>Wallets SHOULD use this <code>intent</code> value to display a clear intent when reviewing the structured data before signature. When displaying a complex json intent, it is expected that keys represent labels, and values should be displayed after their label.</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">display</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">formats</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">withdraw(uint256)</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">intent</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">Native Staking</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Withdraw</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Rewards</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Consensus &amp; Exec</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> <p>This snippet defines an intent for a withdrawal function on a contract, with an expectation that the intent would be displayed in a structured way on the wallet screen.</p> <p><strong><code>interpolatedIntent</code></strong></p> <p>A string containing an intent description with embedded field values using <a href="https://wg-eips.ritovision.com/7730/#value-interpolation">interpolation syntax</a>.</p> <p>Wallets MUST display either <code>interpolatedIntent</code> strings or screens generated from <code>intent</code> and individual <code>fields</code>.</p> <p>Wallets MAY display both fields, with <code>interpolatedIntent</code> as the primary description.</p> <p>Interpolated paths MUST reference fields that have corresponding format specifications in the <code>fields</code> array. The formatting applied during interpolation MUST match the formatting that would be applied if the field were displayed separately.</p> <p><em>Example with complex intent:</em></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">intent</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">Action</span><span class="z-support">&quot;</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 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">Batch</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">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Approve {spender} to spend up to {amount} on your behalf until {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">fields</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">path</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 class="z-support"> &quot;</span><span class="z-support">label</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 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">addressName</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">path</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 class="z-support"> &quot;</span><span class="z-support">label</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 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">tokenAmount</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">path</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 class="z-support"> &quot;</span><span class="z-support">label</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 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</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> <p><strong><code>fields</code></strong></p> <p>The <code>fields</code> key defines formatting information for individual fields of the structured data (function or message).</p> <p><code>fields</code> is an array of elements, each element being either:</p> <ul> <li>A single <a href="https://wg-eips.ritovision.com/7730/#field-format-specification"><em>field format specification</em></a></li> <li>A reference to a format specification in the <code>definitions</code> section: by declaring an object with two keys, a <code>path</code> key with the <a href="https://wg-eips.ritovision.com/7730/#path-references">path</a> to the field being formatted, and a <code>$ref</code> key with a path to the internal definition. <ul> <li>A reference object can override a field format specification <code>params</code> by including its own <code>params</code> sub-key, whose values will take precedence over the common definition</li> </ul> </li> <li>A group of fields, defined in <a href="https://wg-eips.ritovision.com/7730/#group-format-specification"><em>Group format specification</em></a></li> </ul> <p><em>Grouping</em> fields allows for both control of the way wallets should order the display of fields and <em>recursivity</em> of fields definitions, which can be a more readable form for the 7730 file itself.</p> <p><em>Examples</em></p> <p>Let's assume the following solidity 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.8.0</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"> MyContract</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"> MyParamType</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> 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-comment"> Function declaration</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> myFunction</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"> amount</span><span>,</span><span class="z-storage z-type"> MyParamType</span><span class="z-storage z-type"> memory</span><span class="z-variable"> param</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"> Function logic here</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The following ERC-7730 shows examples for the three kinds of <code>fields</code> options</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">display</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">formats</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">myFunction(address account,uint256 amount,(string name,uint256 value) param)</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">fields</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">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">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">$.display.definitions.sendTo</span><span class="z-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 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">eoa</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> {</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 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">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Number of items</span><span class="z-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">raw</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">param</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">fields</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">path</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 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">$.display.definitions.itemName</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">path</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 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">$.display.definitions.itemReference</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 class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li>The <code>account</code> field is an example of an internal reference (reference not included in the example), overriding the reference <code>type</code> parameter with another value.</li> <li>The <code>amount</code> field shows an example of a simple formatter, displaying an int in its natural representation with a label.</li> <li>The <code>param</code> field shows an example of defining formatters with a recursive structure, ending up defining two embedded formatters for paths <code>#.param.name</code> and <code>#.param.value</code></li> </ul> <p>Note that the recursive definition is equivalent to the following definition, which is the preferred form:</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">display</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">formats</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">myFunction(address account,uint256 amount,MyParamType param)</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">fields</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">param.name</span><span class="z-punctuation z-definition z-string">&quot;</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">$.display.definitions.itemName</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">param.value</span><span class="z-punctuation z-definition z-string">&quot;</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">$.display.definitions.itemReference</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></code></pre><h4 id="field-format-specification">Field format specification</h4> <p>A <em>field format specification</em> is a json object defining how to format a single field of the structured data.</p> <p><strong><code>path</code> / <code>value</code></strong></p> <p>The path is the absolute or relative location of the field in the structured data, following the rules in the <a href="https://wg-eips.ritovision.com/7730/#path-references">path section</a>. Instead of <code>path</code>, a literal <code>value</code> may be provided to display a constant without looking up a field.</p> <p><strong><code>label</code></strong></p> <p>A displayable string shown before the formatted field value.</p> <p><strong><code>format</code></strong></p> <p>Indicates how the field value must be transformed for display. Supported format identifiers are listed in the <a href="https://wg-eips.ritovision.com/7730/#field-formats">Reference</a> section.</p> <p><strong><code>params</code></strong></p> <p>Optional object containing formatter-specific parameters. Available parameters are described alongside each format in the <a href="https://wg-eips.ritovision.com/7730/#field-formats">Reference</a> section.</p> <p><em>Array references in parameters</em></p> <p>When a formatter applies to an array, the parameters CAN also reference a path to an array. In that case, wallets should format each element of the array using the parameter value at the same index as the current element being formatted. Parameter arrays should be the same length as the formatted array else the wallet SHOULD raise an error.</p> <p>See <a href="https://wg-eips.ritovision.com/7730/./assets/example-array-iteration.json">example-array-iteration.json</a> for examples on array iteration.</p> <p><strong><code>$id</code></strong></p> <p>Optional internal identifier to help authors distinguish or reference the field definition; not intended for end-user display.</p> <p><strong><code>visible</code></strong></p> <p>Optional rule to apply before displaying a field. Rules allow defining under which conditions a field should be displayed. If not specified, the field is assumed to be always visible (ie, default value is <code>"visible"="always"</code>). Current supported rules are:</p> <ul> <li>A simple string with values among <code>[never,always,optional]</code>, with the following meaning <ul> <li><code>never"</code>: Never display this field to users (this field should be <em>excluded</em> from the UI).</li> <li><code>always</code>: Always display this field to users (this field is <em>required</em>).</li> <li><code>optional</code>: Wallets MAY display this field if possible or sensible.</li> </ul> </li> <li>An object with keys representing complex rules, with the following complex rules supported: <ul> <li><code>ifNotIn</code> key with an array of values to make the field visible only when the field value does NOT match any of the specified values</li> <li><code>mustMatch</code> key with an array of values to make the field always hidden AND check its value against the list. Wallet should raise an error if the value does not match the list.</li> </ul> </li> </ul> <p><strong><code>separator</code></strong></p> <p>Optional separator string to display before each element of an array. Can only be used be used for formatters that are applied to a path pointing to an array. Each element of the array is formatted using the provided formatter, and the <code>separator</code> value is displayed before each element. <code>separator</code> is a string using the interpolated syntax with one specific replacement <code>{index}</code> that gets replaced with the index of current element being displayed.</p> <p><strong><code>encryption</code></strong></p> <p>Optional object indicating the field value is encrypted. When present, it provides all the relevant information on how to handle the decryption process, in particular the encryption scheme used to produce the encrypted value.</p> <p>An <code>encryption</code> key is a json object with:</p> <ul> <li>A <code>scheme</code> key, providing the wallet an hint on encryption scheme used. Refer to <a href="https://wg-eips.ritovision.com/7730/#encryption-schemes">encryption schemes</a> for reference values.</li> <li>A <code>plaintextType</code> key providing the solidity type of the decrypted field. The wallet SHOULD verify that the formatter is applicable to the <code>plaintextType</code>.</li> <li>An optional <code>fallbackLabel</code> to display when the wallet cannot decrypt the field.</li> </ul> <p>Fields MAY declare an <code>encryption</code> object to indicate that the on-chain value is an encrypted amount (or a pointer to an encrypted amount), typically a <code>bytes32</code>. When decryption is available, wallets SHOULD decrypt first and then apply the field <code>format</code> to the plaintext. When decryption is not available, wallets SHOULD display a clear encrypted placeholder (optionally using <code>fallbackLabel</code>) and are RECOMMENDED to also show the raw encrypted value (or its pointer), either fully or partially.</p> <p>Because encrypted values do not reveal their underlying type on-chain, authors SHOULD provide <code>plaintextType</code> so wallets can correctly format decrypted values.</p> <p><em>Example</em></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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">encryptedAmount</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">label</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">format</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">tokenAmount</span><span class="z-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 class="z-support"> &quot;</span><span class="z-support">tokenPath</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">encryption</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">scheme</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">fhevm</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">plaintextType</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">fallbackLabel</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">[Encrypted Amount]</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="group-format-specification">Group format specification</h4> <p>A <em>Group format specification</em> is a json object defining how to format a group of fields of the structured data.</p> <p><strong><code>path</code></strong></p> <p>The absolute or relative path to the field location in the structured data, as described in the <a href="https://wg-eips.ritovision.com/7730/#path-references">path section</a>.</p> <p><code>path</code> is optional, in which case the group refer to the path of the embedding <code>fields</code> definition.</p> <p><strong><code>label</code></strong></p> <p>Optional displayable string that should be shown before displaying the fields described in this group.</p> <p><strong><code>iteration</code></strong></p> <p>Key controlling how arrays in the group should be iterated over when formatting the group. It can only be applied to groups containing arrays.</p> <p>It supports two modes <code>sequential</code> and <code>bundled</code>:</p> <ul> <li>In <code>sequential</code> mode, arrays are displayed fully one after the other - array_0[0] array_0[1] .. array_0[N] array_1[0] array_1[1] .. array_1[M]</li> <li>In <code>bundled</code> mode, elements of the arrays gets bundled together - array_0[0] array_1[0] array_0[1] array_1[1] .. array_0[N] array_1[N] <ul> <li>In this mode, the arrays of the group MUST be the same size else the wallet SHOULD return an error</li> </ul> </li> </ul> <p>Defining groups of fields allows for controlling the <em>order</em> in which wallets should display fields. Wallets SHOULD display fields in the order in which they appear in the group defintion. For this grouping purpose, the top level <a href="https://wg-eips.ritovision.com/7730/#structured-data-format-specification">Structured data format specification</a> is also considered a group.</p> <p>Recursive path references work by concatenating the paths of the parents <em>structured data format specification</em>, all the way to the leaf, to build a full reference path to the field being described. The leaf should be either a <em>field format specification</em>, or a reference to a <em>field format specification</em> in the <code>definitions</code> section.</p> <p>This recursivity allows structuring the ERC-7730 file itself, but is NOT RECOMMENDED. It is expected that resource limited wallets will only support very limited recursivity in the ERC-7730 file itself, so the initial intent of the spec is to "flatten" the list of fields to display using the <em>path</em> mechanics.</p> <p>See <a href="https://wg-eips.ritovision.com/7730/./assets/example-array-iteration.json">example-array-iteration.json</a> for examples on grouping and group iteration control.</p> <h4 id="slices-in-paths">Slices in paths</h4> <p>A slice can be applied at the end of paths.</p> <p>A slice on a primitive type like uint256, bytes and string means that the associated <a href="https://wg-eips.ritovision.com/7730/#field-format-specification">field format specification</a> MUST only be applied to the corresponding slice of bytes of the underlying data.</p> <p>A slice on an array type means that the associated <a href="https://wg-eips.ritovision.com/7730/#field-format-specification">field format specification</a> or recursive <a href="https://wg-eips.ritovision.com/7730/#structured-data-format-specification">structured data format specification</a> MUST be applied to ALL the array elements part of the slice.</p> <p><em>Example</em></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">display</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">formats</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">exactOutput((bytes path, address recipient, uint256 deadline, uint256 amountOut, uint256 amountInMaximum) 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">fields</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">params.amountInMaximum</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Maximum Amount to Send</span><span class="z-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">tokenAmount</span><span class="z-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">tokenPath</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">params.path.[0:20]</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> <p>The <code>tokenPath</code> parameter uses a slice on a <code>bytes</code> value, indicating only the first 20 bytes should be taken as the address and used as the reference for the formatting of the corresponding token amount.</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">display</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">formats</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">buyOnMySwap(address router,uint256 amountIn,uint256 amountOutMin,address tokenPathStart,uint256[] pools)</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">fields</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">pools.[-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">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Last pool</span><span class="z-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">raw</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></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This examples uses an array slice to indicate that only the last element of the <code>pools</code> array should be displayed using the <code>raw</code> format.</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">display</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">formats</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">PermitBatch(PermitDetails[] details,address spender,uint256 sigDeadline) PermitDetails(address token,uint160 amount,uint48 expiration,uint48 nonce)</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">intent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Approve token spending</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Approve {spender} to spend multiple tokens until {sigDeadline}</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">fields</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">details.[]</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">fields</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">path</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">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Amount allowance</span><span class="z-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">tokenAmount</span><span class="z-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">tokenPath</span><span class="z-support">&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 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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">expiration</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Approval expires</span><span class="z-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</span><span class="z-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">encoding</span><span class="z-support">&quot;</span><span>:</span><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 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">path</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">label</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">format</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">addressName</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">sigDeadline</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Signature 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">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</span><span class="z-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">encoding</span><span class="z-support">&quot;</span><span>:</span><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 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>This example uses a full array selector <code>details.[]</code> to apply the list of the underlying two underlying formats to ALL the elements of the <code>details</code> array.</p> <h4 id="embedded-calldata">Embedded Calldata</h4> <p>Embedded calldata is used when a parameter of a smart contract function contains the calldata for another function call to a smart contract. This pattern is common in contract interactions where one function call triggers another function call as part of its execution. For example, the <code>permitAndCall</code> function verifies a permit and then executes another function within the same contract using the provided embedded calldata. Here is an example of how to format embedded calldata:"</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">display</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">formats</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">permitAndCall(bytes permit,bytes action)</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">intent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Execute with 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">fields</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">action</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Swap</span><span class="z-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">calldata</span><span class="z-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">calleePath</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> }</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">action</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">excluded</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">permit</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> <p>In this example, the <code>permitAndCall</code> function accepts two parameters: <code>permit</code> and <code>action</code>. The <code>action</code> parameter contains the calldata for a subsequent function call. The <code>format</code> field is set to <code>calldata</code>, instructing the wallet to interpret the action parameter as embedded calldata. The <code>calleePath</code> parameter defines the path to the address of the target contract, while the optional <code>selector</code> parameter specifies the function selector if it is not the first 4 bytes of the calldata. When displaying the transaction, the wallet will attempt to resolve an ERC-7730 descriptor for the embedded calldata using the callee address and the selector. In some cases, embedded calldata may require a transaction value and/or a spender to be properly clear-signed, as the underlying function might rely on a value passed from the parent transaction (e.g., for swaps or staking). To handle this, the <code>amountPath</code> and/or <code>spenderPath</code> parameters can be used to specify these values explicitly.</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">display</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">formats</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">permitAndCall(bytes permit,address target,bytes action)</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">intent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Execute with 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">fields</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">path</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">action</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Swap</span><span class="z-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">calldata</span><span class="z-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">calleePath</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">target</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">amountPath</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">spenderPath</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 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">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">action</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">target</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">excluded</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">permit</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><h3 id="reference">Reference</h3> <h3 id="container-structure-values">Container structure values</h3> <p>This section describes all container structure supported by this specification and possible references path to relevant values.</p> <h4 id="evm-transaction-container">EVM Transaction container</h4> <table><thead><tr><th>Value reference</th><th>Value Description</th></tr></thead><tbody> <tr><td>@.from</td><td>The address of the sender of the transaction</td></tr> <tr><td>@.value</td><td>The native currency value of the transaction</td></tr> <tr><td>@.to</td><td>The destination address of the containing transaction, ie the target smart contract address</td></tr> <tr><td>@.chainId</td><td>The chainId of the transaction</td></tr> </tbody></table> <h4 id="eip-712-container">EIP-712 container</h4> <table><thead><tr><th>Value reference</th><th>Value Description</th></tr></thead><tbody> <tr><td>@.from</td><td>The address of the signer of the message</td></tr> <tr><td>@.value</td><td>EIP-712 have no underlying currency value transferred, so a wallet MAY interpret it as 0</td></tr> <tr><td>@.to</td><td>The verifying contract address, when known. If not known a wallet SHOULD reject using the ERC-7730 file to clear sign the message</td></tr> <tr><td>@.chainId</td><td>The chainId of the verifying contract, when known. If not known a wallet SHOULD reject using the ERC-7730 file to clear sign the message.</td></tr> </tbody></table> <h3 id="field-formats">Field formats</h3> <p>In the following references, the format title is the value to use under the <code>format</code> key of a <a href="https://wg-eips.ritovision.com/7730/#field-format-specification"><em>field format specification</em></a>.</p> <h4 id="integer-formats">Integer formats</h4> <p>Formats applicable to <code>uint</code>/<code>int</code> solidity types.</p> <table><thead><tr><th><strong><code>raw</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Display the integer as a raw int in natural, localized representation</td></tr> <tr><td><em>Parameters</em></td><td>None</td></tr> <tr><td><em>Examples</em></td><td>Value 1000 displayed as <code>1000</code></td></tr> </tbody></table> <table><thead><tr><th><strong><code>amount</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Display as an amount in native currency, using best ticker / magnitude match</td></tr> <tr><td><em>Parameters</em></td><td>None</td></tr> <tr><td><em>Examples</em></td><td>Value 0x2c1c986f1c48000 is displayed as <code>0.19866144 ETH</code></td></tr> </tbody></table> <table><thead><tr><th><strong><code>tokenAmount</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Convert value using token decimals, and append token ticker name. If value is above optional <code>threshold</code>, display instead <code>message</code> with ticker.</td></tr> <tr><td><em>Parameters</em></td><td>---</td></tr> <tr><td><code>tokenPath</code> or <code>token</code></td><td>Path reference, or constant value for the address of the token contract. Used to associate correct ticker. If ticker is not found or <code>tokenPath</code>/<code>token</code> is not set, the wallet SHOULD display the raw value instead with an "Unknown token" warning</td></tr> <tr><td><code>nativeCurrencyAddress</code></td><td>Either a string or an array of strings. If the address pointed to by <code>tokenPath</code> is equal to one of the addresses in <code>nativeCurrencyAddress</code>, the tokenAmount is interpreted as expressed in native currency</td></tr> <tr><td><code>threshold</code></td><td>integer value, above which value is displayed as a special message. Optional</td></tr> <tr><td><code>message</code></td><td>message to display above threshold. Optional, defaults to "Unlimited"</td></tr> <tr><td><code>chainIdPath</code> or <code>chainId</code></td><td>Optional. The chain on which the token is deployed (constant or path). When present, the wallet SHOULD resolve token metadata (ticker, decimals) for this chain. Useful for cross-chain swap clear signing where the same token address may refer to different chains. At most one of <code>chainId</code> and <code>chainIdPath</code> may be set.</td></tr> <tr><td><em>Examples</em></td><td>---</td></tr> <tr><td><code>1 DAI</code></td><td>Field value = 1000000 <br> <code>tokenPath</code> =0x6B17...1d0F (DAI, 6 decimals)</td></tr> <tr><td><code>Unlimited DAI</code></td><td>Field value = 0xFFFFFFFF <br> <code>token</code> =0x6B17...1d0F (DAI, 6 decimals) <br> <code>threshold</code> "0xFFFFFFFF"</td></tr> <tr><td><code>Max DAI</code></td><td>Field value = 0xFFFFFFFF <br> <code>tokenPath</code> =0x6B17...1d0F (DAI, 6 decimals) <br> <code>threshold</code> "0xFFFFFFFF" <br> <code>message</code> = "Max"</td></tr> <tr><td><code>0.002 ETH</code></td><td>Field value = 2000000000000000 <br> <code>tokenPath</code> = 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE <br> <code>nativeCurrencyAddress</code> = ["0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE"]</td></tr> </tbody></table> <table><thead><tr><th><strong><code>nftName</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Display value as a specific NFT in a collection, if found by wallet, or fallback to a raw int token ID if not</td></tr> <tr><td><em>Parameters</em></td><td>---</td></tr> <tr><td><code>collectionPath</code> or <code>collection</code></td><td>A path reference, or constant value for the collection address</td></tr> <tr><td><em>Examples</em></td><td>---</td></tr> <tr><td><code>Collection Name: BoredApeYachtClub</code> <br> <code>Token ID: 1036</code></td><td>Field Value = 1036 <br> <code>collectionPath</code> = ""0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D</td></tr> </tbody></table> <table><thead><tr><th><strong><code>date</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Display int as a date, using specified encoding. Date display RECOMMENDED use of RFC 3339</td></tr> <tr><td><em>Parameters</em></td><td>---</td></tr> <tr><td><code>"encoding": "timestamp"</code></td><td>value is encoded as a unix timestamp</td></tr> <tr><td><code>"encoding": "blockheight"</code></td><td>value is a blockheight and is converted to an approximate unix timestamp</td></tr> <tr><td><em>Examples</em></td><td>---</td></tr> <tr><td><code>2024-02-29T08:27:12</code></td><td>Field Value = 1709191632 <br> <code>encoding</code> = "timestamp"</td></tr> <tr><td><code>2024-02-29T09:00:35</code></td><td>Field Value = 19332140 <br> <code>encoding</code> = "blockheight"</td></tr> </tbody></table> <table><thead><tr><th><strong><code>duration</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Display int as a duration interpreted in seconds and represented as a duration HH:MM:ss</td></tr> <tr><td><em>Parameters</em></td><td>None</td></tr> <tr><td><em>Examples</em></td><td>---</td></tr> <tr><td><code>02:17:30</code></td><td>Field Value = 8250</td></tr> </tbody></table> <table><thead><tr><th><strong><code>unit</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Value is converted to a float using <code>decimals</code> (<code>value / 10^decimals</code>) and displayed appending the corresponding unit. If <code>prefix</code> is true, the value is further converted to scientific representation, minimizing the significand and converting the exponent to an SI prefix added in front of the unit symbol</td></tr> <tr><td><em>Parameters</em></td><td>---</td></tr> <tr><td><code>base</code></td><td>The symbol of the base unit, an SI unit or other acceptable symbols like "%", "bps"</td></tr> <tr><td><code>decimals</code></td><td>Number of decimals in integer representation, defaults to 0</td></tr> <tr><td><code>prefix</code></td><td>A boolean indicating whether an SI prefix should be appended, defaults to <code>False</code></td></tr> <tr><td><em>Examples</em></td><td>---</td></tr> <tr><td><code>10h</code></td><td>Field Value = 10 <br> <code>base</code> = "h"</td></tr> <tr><td><code>1.5d</code></td><td>Field Value = 15 <br> <code>base</code> = "d" <br> <code>decimals</code> = 1</td></tr> <tr><td><code>36ks</code></td><td>Field Value = 36000 <br> <code>base</code> = "s" <br> <code>prefix</code> = True</td></tr> </tbody></table> <table><thead><tr><th><strong><code>enum</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Value is converted using referenced constant enumeration values</td></tr> <tr><td><em>Parameters</em></td><td>---</td></tr> <tr><td><code>$ref</code></td><td>An internal path (starting with root node <code>$.</code>) to an enumerations in <code>metadata.constants</code></td></tr> <tr><td><em>Examples</em></td><td></td></tr> </tbody></table> <table><thead><tr><th><strong><code>chainId</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Value is converted to a Blockchain name using EIP-155 reference values</td></tr> <tr><td><em>Parameters</em></td><td>None</td></tr> <tr><td><em>Examples</em></td><td></td></tr> <tr><td><code>Ethereum Mainnet</code></td><td>Field Value = 1</td></tr> </tbody></table> <h4 id="string-formats">String formats</h4> <p>Formats applicable to for <code>string</code> solidity type.</p> <table><thead><tr><th><strong><code>raw</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Display as an UTF-8 encoded string</td></tr> <tr><td><em>Parameters</em></td><td>None</td></tr> <tr><td><em>Examples</em></td><td>---</td></tr> <tr><td><code>Ledger</code></td><td>Field Value = ['4c','65','64','67','65','72']</td></tr> </tbody></table> <h4 id="bytes-formats">Bytes formats</h4> <p>Formats applicable to <code>bytes</code> solidity type.</p> <table><thead><tr><th><strong><code>raw</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Display byte array as an hex-encoded string</td></tr> <tr><td><em>Parameters</em></td><td>None</td></tr> <tr><td><em>Examples</em></td><td>---</td></tr> <tr><td><code>123456789A</code></td><td>Field Value = Value ['12','34','56','78','9a']</td></tr> </tbody></table> <table><thead><tr><th><strong><code>calldata</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Contains a call to another smart contract or to another function within the same contract. To resolve an ERC-7730 descriptor for this embedded calldata, use the <code>callee</code> and <code>selector</code> parameters. If no matching ERC-7730 descriptor is found or if the wallet does not support embedded calldata, it MAY display a hash of the embedded calldata instead, with target <code>calleePath</code> resolved to a trusted name if possible.</td></tr> <tr><td><em>Parameters</em></td><td>---</td></tr> <tr><td><code>calleePath</code> or <code>callee</code></td><td>A path reference or a constant value specifying the address of the contract being called.</td></tr> <tr><td><code>selectorPath</code> or <code>selector</code></td><td>Optional. If omitted, the first 4 bytes of the calldata are used as the selector.</td></tr> <tr><td><code>chainIdPath</code> or <code>chainId</code></td><td>Optional. Specifies the chain ID if it differs from the current contract’s chain.</td></tr> <tr><td><code>amountPath</code> or <code>amount</code></td><td>Optional. Specifies the native currency amount associated with the calldata, if applicable. If provided, the ERC-7730 descriptor for this embedded calldata MAY reference this value using the <code>@.value</code> container path.</td></tr> <tr><td><code>spenderPath</code> or <code>spender</code></td><td>Optional. Specifies the spender address associated with the calldata, if applicable. If provided, the ERC-7730 descriptor for this embedded calldata MAY reference this value using the <code>@.from</code> container path.</td></tr> <tr><td><em>Examples</em></td><td>---</td></tr> </tbody></table> <h4 id="address">Address</h4> <p>Formats applicable to <code>address</code> solidity type.</p> <table><thead><tr><th><strong><code>raw</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Display address as an <a href="https://wg-eips.ritovision.com/55/">EIP-55</a> formatted string. Truncation is device dependent</td></tr> <tr><td><em>Parameters</em></td><td>None</td></tr> <tr><td><em>Examples</em></td><td>---</td></tr> <tr><td><code>0x5aAe...eAed</code></td><td>Field Value 0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed</td></tr> </tbody></table> <table><thead><tr><th><strong><code>addressName</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Display address as a trusted name if a trusted source exists, an EIP-55 formatted address otherwise. See <a href="https://wg-eips.ritovision.com/7730/#address-types-and-sources">next section</a> for a reference of trusted sources</td></tr> <tr><td><em>Parameters</em></td><td>---</td></tr> <tr><td><code>types</code></td><td>An array of expected types of the address (see <a href="https://wg-eips.ritovision.com/7730/#address-types-and-sources">next section</a>). If set, the wallet SHOULD check that the address matches one of the types provided</td></tr> <tr><td><code>sources</code></td><td>An array of acceptable sources for names (see <a href="https://wg-eips.ritovision.com/7730/#address-types-and-sources">next section</a>). If set, the wallet SHOULD restrict name lookup to relevant sources</td></tr> <tr><td><code>senderAddress</code></td><td>Either a string or an array of strings. If the address pointed to by <code>addressName</code> is equal to one of the addresses in <code>senderAddress</code>, the addressName is interpreted as the sender referenced by <code>@.from</code></td></tr> <tr><td><em>Examples</em></td><td>---</td></tr> <tr><td><code>vitalik.eth</code></td><td>Field Value 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 <br> <code>types</code> = ["eoa"] (Externally Owned Account) <br> <code>sources</code> = ["ens"] (Ethereum Name Service)</td></tr> <tr><td><code>Uniswap V3: WBTC-USDC</code></td><td>Field Value 0x99ac8cA7087fA4A2A1FB6357269965A2014ABc35 <br> <code>types</code> = ["contract"]</td></tr> <tr><td><code>Sender</code></td><td>Field Value 0x0000000000000000000000000000000000000000 <br> <code>senderAddress</code> = ["0x0000000000000000000000000000000000000000"] <br> <code>types</code> = ["eoa"]</td></tr> </tbody></table> <hr /> <table><thead><tr><th><strong><code>tokenTicker</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Display address as an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token ticker</td></tr> <tr><td><em>Parameters</em></td><td>---</td></tr> <tr><td><code>chainIdPath</code> or <code>chainId</code></td><td>Optional. The chain on which the token is deployed (constant or path). When present, the wallet SHOULD resolve the token ticker for this chain. Useful for cross-chain swap clear signing. At most one of <code>chainId</code> and <code>chainIdPath</code> may be set.</td></tr> <tr><td><em>Examples</em></td><td>---</td></tr> <tr><td><code>MYTOKEN</code></td><td>Field Value 0xaabbccddeeff....</td></tr> </tbody></table> <h4 id="interoperable-addresses">Interoperable addresses</h4> <p>Interoperable address format applicable to solidity type <code>bytes</code>.</p> <table><thead><tr><th><strong><code>interoperableAddressName</code></strong></th><th></th></tr></thead><tbody> <tr><td><em>Description</em></td><td>Display bytes as an <a href="https://wg-eips.ritovision.com/7930/">ERC-7930</a> Interoperable Name. The wallet SHOULD parse the binary format, extract the target address and chain, and display it in the standard <code>&lt;address&gt; @ &lt;chain&gt; # &lt;checksum&gt;</code> format.</td></tr> <tr><td><em>Parameters</em></td><td>---</td></tr> <tr><td><code>types</code></td><td>An array of expected types of the address (see <a href="https://wg-eips.ritovision.com/7730/#address-types-and-sources">next section</a>). If set, the wallet SHOULD check that the address matches one of the types provided</td></tr> <tr><td><code>sources</code></td><td>An array of acceptable sources for names (see <a href="https://wg-eips.ritovision.com/7730/#address-types-and-sources">next section</a>). If set, the wallet SHOULD restrict name lookup to relevant sources</td></tr> <tr><td><code>senderAddress</code></td><td>Either a string or an array of strings. If the address pointed to by <code>addressName</code> is equal to one of the addresses in <code>senderAddress</code>, the addressName is interpreted as the sender referenced by <code>@.from</code></td></tr> <tr><td><em>Examples</em></td><td>---</td></tr> <tr><td><code>0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045@eip155:1#4CA88C9C</code></td><td>Field Value = <code>0x00010000010114D8DA6BF26964AF9D7EED9E03E53415D37AA96045</code></td></tr> </tbody></table> <h4 id="address-types-and-sources">Address types and sources</h4> <p>Address names trusted sources specify which type and source of trusted names SHOULD be used to replace an address with a human-readable names.</p> <p>When specified a wallet MUST only use specified sources to resolve address names. Wallet MUST verify the type of the address if able to.</p> <p>When omitted, a wallet MAY use any source to resolve an address.</p> <table><thead><tr><th>Address type</th><th>Description</th></tr></thead><tbody> <tr><td>wallet</td><td>Address is an account controlled by the wallet</td></tr> <tr><td>eoa</td><td>Address is an Externally Owned Account</td></tr> <tr><td>contract</td><td>Address is a well known smart contract</td></tr> <tr><td>token</td><td>Address is a well known ERC-20 token</td></tr> <tr><td>collection</td><td>Address is a well known NFT collection</td></tr> </tbody></table> <p>A wallet MAY verify that a <code>wallet</code> address is in fact controlled by the wallet, and reject signing if not the case.</p> <p>Sources values are wallet manufacturer specific. Some example values could be:</p> <table><thead><tr><th>Source type</th><th>Description</th></tr></thead><tbody> <tr><td>local</td><td>Address MAY be replaced with a local name trusted by user. Wallets MAY consider that <code>local</code> setting for <code>sources</code> is always valid</td></tr> <tr><td>ens</td><td>Address MAY be replaced with an associated ENS domain</td></tr> </tbody></table> <h3 id="encryption-schemes">Encryption schemes</h3> <p>List of currently supported encryption schemes hints for fields</p> <table><thead><tr><th>Scheme</th><th>Description</th></tr></thead><tbody> <tr><td>fhevm</td><td>FHEVM full homomorphic encryption</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <h3 id="human-readability">Human readability</h3> <p>It is expected that the main limitation to adoption of ERC-7730 will be the complexity of writing this interface description file compared to interest of writing it.</p> <p>This drove a few choices when introducing this ERC specification:</p> <ul> <li>The form of an ERC itself will allow usage of these file by any wallets (Hardware or Software, without restrictions), and in turn drive up the benefits for app developers to provide their own ERC-7730 description</li> <li>The specification is intended to be directly readable by developers, in order to facilitate direct edition by developers.</li> <li>In addition, a set of edition tools will be created and open sourced to ease visualization of the results for end users</li> </ul> <h3 id="wallet-limitations">Wallet limitations</h3> <p>Wide support by wallets is key for adoption of this specification.</p> <p>Hardware wallets tend to have more limited capabilities that will impact what they can display securely, especially since the intention of the specification is to create a strong security binding between the spec and the data being reviewed.</p> <p>This consideration is driving a few choices done for ERC-7730:</p> <ul> <li>Complex UI constructs like layouts, grouping and re-ordering of fields have been left to a wallet specific section, yet unspecified. After a time, we may see patterns emerge between wallets in terms of minimal features.</li> <li>Representation of fields has been created to allow "flattening" the list of fields, when handling complex message structures. This flattened representation is expected to work better with Hardware wallets in particular, and is recommended at first.</li> <li>Some formatters that require recursive constructs, like <code>calldata</code> are expected to work with restrictions at first, especially on Hardware wallets.</li> </ul> <h3 id="internationalization">Internationalization</h3> <p>This specification intentionally does not address internationalization or localization of displayable strings.</p> <p>All display strings in ERC-7730 files—including intents, labels, field names, and enumeration values—are expected to be authored in English.</p> <p>Future versions of this specification may consider standardized internationalization support once the base standard achieves wider adoption and the ecosystem can better assess the need for multilingual support.</p> <h3 id="user-operations-eip-4337">User Operations (EIP-4337)</h3> <p>Clear signing <a href="https://wg-eips.ritovision.com/4337/">EIP-4337</a> User Operations is supported using the <code>PackedUserOperation</code> EIP-712 signature format. See <a href="https://wg-eips.ritovision.com/7730/./assets/example-userops-eip712.json">example-userops-eip-712.json</a> for a reference implementation.</p> <p>The inner calldata typically contains an <code>execute</code> call to interact with other contracts. This can be clear signed using a separate ERC-7730 file - see <a href="https://wg-eips.ritovision.com/7730/./assets/example-account-execute.json">example-account-execute.json</a>. Since execute functions are implementation-specific, each smart wallet will need its own ERC-7730 file.</p> <p>Smart wallets commonly use a proxy pattern. Refer to the <a href="https://wg-eips.ritovision.com/7730/#proxy-support">Proxy support</a> section for guidance.</p> <h3 id="batch-transactions-eip-5792">Batch transactions (EIP-5792)</h3> <p>When displaying batch transactions as defined in <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a>, wallets SHOULD either:</p> <ul> <li>Concatenate the <code>interpolatedIntent</code> strings of individual operations using " and " as a separator to create a single, human-readable description of the entire batch.</li> <li>Concatenate screens generated using <code>intent</code> and required <code>fields</code>, clearly separating individual transactions</li> </ul> <p>The <code>interpolatedIntent</code> approach provides users with a clear, natural language summary of complex multi-step operations without requiring them to mentally piece together separate transaction descriptions. The <code>intent</code> approach provide a more controllable wallet UI for space limited wallets.</p> <p><em>Permit + Swap example:</em></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">function</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">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Approve {spender} to spend {value} USDC</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">function</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">swapExactTokensForTokens</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Swap {amountIn} for at least {amountOutMin}</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>Combined display: <strong>"Approve Uniswap Router to spend 1000 USDC and Swap 1000 USDC for at least 0.25 WETH"</strong></p> <p><em>Approve + Swap example:</em></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">function</span><span class="z-support">&quot;</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 class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Approve {_spender} to spend {_value}</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">function</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">exactInputSingle</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Swap {amountIn} for at least {amountOutMinimum}</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>Combined display: <strong>"Approve Uniswap V3 Router to spend 5000 DAI and Swap 5000 DAI for at least 1.2 ETH"</strong></p> <p><em>Approve + Swap + Mint NFT example:</em></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">function</span><span class="z-support">&quot;</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 class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Approve {_spender} to spend {_value}</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">function</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">swapExactTokensForETH</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Swap {amountIn} for at least {amountOutMin} ETH</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">function</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">mint</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interpolatedIntent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Mint {quantity} NFT(s) from {collection}</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>Combined display: <strong>"Approve DEX Router to spend 2000 USDC and Swap 2000 USDC for at least 0.5 ETH and Mint 2 NFT(s) from NftProject"</strong></p> <p><strong>Implementation guidance for batch transactions using interpolatedIntents</strong></p> <p>Wallets implementing batch transaction display SHOULD:</p> <ol> <li>Process each transaction in the batch to generate its <code>interpolatedIntent</code></li> <li>Join the resulting intent strings with " and " (note the spaces)</li> <li>Display the combined string as a single transaction summary</li> <li>Provide a way for users to view individual transaction details if needed</li> <li>Fall back to displaying individual <code>intent</code> fields if any <code>interpolatedIntent</code> processing fails</li> </ol> <p>Wallets MAY:</p> <ul> <li>Apply additional formatting (e.g., capitalizing the first letter, adding a period at the end)</li> <li>Truncate very long combined intents and provide expansion UI</li> <li>Group related operations visually while still showing the combined intent</li> </ul> <h3 id="extensibility-to-other-structured-data-formats">Extensibility to other structured data formats</h3> <p>In the future, this specification could be extended to structured data like Meta Transaction in <a href="https://wg-eips.ritovision.com/2771/">EIP-2771</a>, User Operations in <a href="https://wg-eips.ritovision.com/4337/">EIP-4337</a>, and batch transaction payloads in <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a>.</p> <p>The <code>interpolatedIntent</code> field is particularly well-suited for <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> batch transactions, as it enables wallets to concatenate multiple operation descriptions into a single, natural language sentence. By joining individual <code>interpolatedIntent</code> strings with " and ", wallets can provide users with clear, readable summaries of complex multi-step operations like "Approve Uniswap Router to spend 1000 USDC and Swap 1000 USDC for at least 0.25 WETH". This significantly improves the user experience when reviewing batch transactions compared to displaying separate, disconnected operation descriptions. See the <a href="https://wg-eips.ritovision.com/7730/#value-interpolation">Value Interpolation</a> section for detailed implementation guidance and examples.</p> <h3 id="common-keywords">Common keywords</h3> <p>The DeFi ecosystem has matured and has some repeating usecases with well defined terms for different actions. While this ERC does not define specific standards for DEX or Lending protocol intents, for the sake of easier user readibility, teams with similar products should align on similar terminology to describe actions and actors. We encourage the creation of another layer of standardization on top of ERC-7730 to be recommeneded and even enforced in clear signing registries for improved user security.</p> <h2 id="test-cases">Test Cases</h2> <p>More examples can be found in the asset folder.</p> <table><thead><tr><th>File name</th><th>Description</th></tr></thead><tbody> <tr><td><a href="https://wg-eips.ritovision.com/7730/./assets/example-main.json">example-main.json</a></td><td>Simple example of a basic ERC-7730 file</td></tr> <tr><td><a href="https://wg-eips.ritovision.com/7730/./assets/example-erc20.json">example-erc-20.json</a></td><td>Simple example of defining an interface for ERC-20 contracts</td></tr> <tr><td><a href="https://wg-eips.ritovision.com/7730/./assets/example-include.json">example-include.json</a></td><td>Example of including an interface into another ERC-7730 file</td></tr> <tr><td><a href="https://wg-eips.ritovision.com/7730/./assets/example-eip712.json">example-eip-712.json</a></td><td>Clear signing EIP-712 example</td></tr> <tr><td><a href="https://wg-eips.ritovision.com/7730/./assets/example-array-iteration.json">example-array-iteration.json</a></td><td>Examples of various array iteration modes and field grouping features</td></tr> <tr><td><a href="https://wg-eips.ritovision.com/7730/./assets/example-maps.json">example-maps.json</a></td><td>Example of maps of constants</td></tr> <tr><td><a href="https://wg-eips.ritovision.com/7730/./assets/example-maps-pools.json">example-maps-pools.json</a></td><td>Example of maps of constants</td></tr> <tr><td><a href="https://wg-eips.ritovision.com/7730/./assets/example-visibility-rules.json">example-visibility-rules.json</a></td><td>Example of controlling the visibility of fields</td></tr> <tr><td><a href="https://wg-eips.ritovision.com/7730/./assets/example-account-execute.json">example-account-execute.json</a></td><td>Example of EIP-4337 smart wallet execute function clear signing</td></tr> <tr><td><a href="https://wg-eips.ritovision.com/7730/./assets/example-userops-eip712.json">example-userops-eip-712.json</a></td><td>Example of EIP-4337 User Operation clear signing</td></tr> </tbody></table> <h2 id="security-considerations">Security Considerations</h2> <p>ERC-7730 creates a risk surface where malicious actors could abuse formatting to make unsafe transactions appear benign. In addition to misapplied or malformed files, implementers should anticipate phishing techniques such as (a) parameter injection using legitimate, high-profile contract formats, (b) registry poisoning with well-formed but misleading entries, and (c) front-end/CDN compromise that prompts signatures for unexpected contracts or parameters.</p> <h3 id="binding-context">Binding context</h3> <p>The binding <code>context</code> mitigates misuse by specifying exactly which structured data a given ERC-7730 file may format. app developers MUST set restrictive constraints; wallets MUST verify all constraints and ensure formatting is cryptographically bound to the reviewed data and not tamperable in transit (including on resource-constrained hardware wallets).</p> <h3 id="registry-poisoning">Registry poisoning</h3> <p>Curation and registry of ERC-7730 files are out of scope for this specification, but any external registry or wallet ecosystem MUST assume it will be targeted. A secure registry should (a) require cryptographically verifiable provenance and attestations for each ERC-7730 file and its maintainer, (b) keep a public, tamper-evident history of submissions, approvals, and revocations, (c) implement a mechanism to credibly link contract ownership or authority to the submitted file, and (d) adopt a clear governance model with multi-party sign-off and automated monitoring to detect anomalies or mass poisoning attempts. These measures mitigate attacks on ERC-7730 files in transit and make registry compromise significantly harder without constraining this ERC itself.</p> <h3 id="external-data-resolution">External data resolution</h3> <p>ERC-7730 formatting relies on resolving various external data sources to provide human-readable information. This resolution introduces trust assumptions that wallets must understand when showing ERC-7730 information.</p> <p><strong>Trust assumptions</strong></p> <p>The transition from transaction data to human readable data requires trust in external data sources to resolve some parts of the presentation layer. Without the resolution, it's not readable and missed the whole point of the ERC, with the resolution it adds a risk factor:</p> <ul> <li><strong>Token metadata</strong> (tickers, decimals) A token address translated to a token ticker and proper decimals applied to the <code>tokenAmount</code>.</li> <li><strong>NFT collection names</strong> and token metadata for the <code>nftName</code> format</li> <li><strong>Address resolution</strong> when formatting <code>addressName</code> using ENS or similar tools</li> </ul> <p>Malicious or compromised data sources could:</p> <ul> <li>Display incorrect token names, leading users to believe they are approving transactions for legitimate tokens when they are not</li> <li>Display malicious addresses as if it is a trusted address name</li> <li>Present fake NFT collection names to obscure the true nature of transactions</li> <li>Provide misleading enumeration values that misrepresent transaction parameters</li> <li>Supply modified ABIs that change how transaction data is interpreted</li> </ul> <p><strong>Example attack scenarios</strong></p> <ol> <li> <p><strong>Token name spoofing</strong>: A malicious ERC-7730 file references a fake token contract at address <code>0x1234...</code> that returns "USDT" as its ticker and 6 decimals, making a transaction appear to transfer legitimate USDT when it actually transfers a worthless token.</p> </li> <li> <p><strong>Address name substitution</strong>: A compromised ENS resolver returns a malicious address naming resolution causing a send to an address not anticipated</p> </li> </ol> <p><strong>Mitigations</strong></p> <p>Wallets SHOULD:</p> <ul> <li>Maintain curated lists of well-known addresses (tokens, contracts, collections) and warn users when encountering unknown entities</li> <li>Display full addresses alongside resolved names in some form</li> <li>Clearly indicate the source and trust level of resolved names and metadata</li> </ul> <p>Wallets MUST:</p> <ul> <li>Display clear warnings when external data cannot be resolved or verified (e.g., "Unknown token")</li> <li>Never fallback to presenting untrusted information as if it was trusted and verified</li> </ul> <h3 id="proxy-support">Proxy support</h3> <p>The proxy pattern is widely use in Ethereum in multiple scenarios to provide flexibility to essentially immutable contracts:</p> <ul> <li>Making smart contracts <em>upgradable</em></li> <li>Making smart contracts <em>composable</em></li> <li>Creating multiple <em>instances</em> of a reference implementation</li> </ul> <p>These patterns are often used in conjunction. Supporting those patterns require some considerations from both smart contract developers and wallets.</p> <p><strong>Upgradeable proxy contracts</strong></p> <p>Upgradeable proxy contracts (such as Transparent Proxies or UUPS proxies as defined in <a href="https://wg-eips.ritovision.com/1822/">EIP-1822</a>) use a fixed proxy address that delegates calls to a replaceable implementation contract. For these contracts, the ERC-7730 file SHOULD be bound to the <em>proxy</em> address, since this is the stable address users interact with.</p> <p>When an upgrade introduces breaking ABI changes (new functions, modified signatures, or removed functions), developers SHOULD update the ERC-7730 file in the registry accordingly. Since the old implementation is no longer callable after the upgrade, the previous ERC-7730 definitions can be safely replaced.</p> <p>Wallets need to ensure they use the latest version of the registry and match the transaction target against the <em>proxy</em> address.</p> <p><strong>Composable contracts</strong></p> <p>Composable contracts, like Diamond proxies, aggregate through a single <em>proxy</em> address, multiple implementation facets. Each facet has its own ABI.</p> <p>A good pattern to support diamond proxies is to introduce an ERC-7730 file for each facet, without any context info, and use the composability of ERC-7730 files to create an overarching ERC-7730 file that includes all implemented facets of a proxy and bound to the final <em>proxy</em> address.</p> <p>Similarly wallets just need to ensure they have the latest version of the registry and that the target address is the <em>proxy</em> address.</p> <p><strong>Multi-instanciation</strong></p> <p>This pattern is typically used by smart wallet factories to efficiently deploy many smart wallets relying on a single, secure implementation.</p> <p>It is not efficient nor advisable to deploy an ERC-7730 for <em>each</em> smart wallet address. In this case, it is recommended to bind the ERC-7730 file to the <em>implementation</em> address of the smart wallet and rely on the user's wallet to detect that the target address is actually a proxy to a well known implementation address.</p> <h3 id="interpolated-intent-security">Interpolated intent security</h3> <p>The <code>interpolatedIntent</code> feature introduces additional attack surfaces that wallets MUST mitigate:</p> <p><strong>Injection attacks</strong></p> <p>Malicious contracts could craft parameter values that, when interpolated, create misleading intent descriptions. For example:</p> <ul> <li>A token name containing "to vitalik.eth" could make "Send {amount} to {recipient}" appear as "Send 100 USDT to vitalik.eth to 0x123..."</li> <li>Addresses with misleading ENS names could obscure the true destination</li> <li>Very long formatted values could push critical information off-screen</li> </ul> <p><em>Mitigations:</em></p> <ul> <li>Wallets MUST apply the same formatting and validation to interpolated values as they would for separately displayed fields</li> <li>Wallets MUST validate that ENS names and other address labels are verified before interpolation</li> <li>Wallets SHOULD display field values separately in addition to the interpolated intent, or provide easy access to detailed field view</li> </ul> <p><strong>Format consistency</strong></p> <p>Wallets MUST ensure that the formatting applied during interpolation exactly matches the formatting that would be applied if the field were displayed separately. This prevents attackers from exploiting differences in formatting to hide malicious values.</p> <p><em>Implementation requirement:</em></p> <ul> <li>The interpolation engine MUST use the same formatter functions and parameters specified in the corresponding field format specification</li> <li>If a path in <code>interpolatedIntent</code> does not have a corresponding field format specification, interpolation MUST fail and fall back to <code>intent</code></li> </ul> <p><strong>Path validation</strong></p> <p>Wallets MUST validate that all paths in interpolation expressions:</p> <ol> <li>Follow the <a href="https://wg-eips.ritovision.com/7730/#path-references">path reference rules</a></li> <li>Reference fields that exist in the structured data being signed</li> <li>Have corresponding field format specifications in the <code>fields</code> array</li> <li>Do not create circular references or unbounded recursion</li> </ol> <p><strong>Fallback behavior</strong></p> <p>If interpolation fails for any reason (invalid path, formatting error, missing field specification, validation failure), wallets MUST:</p> <ol> <li>Fall back to displaying the static <code>intent</code> field</li> <li>Display all fields separately according to their field format specifications</li> <li>NOT attempt to partially process the interpolated intent</li> <li>Optionally warn the user that the dynamic description could not be generated</li> </ol> <p><strong>Resource constraints</strong></p> <p>Hardware wallets and other resource-constrained devices MAY choose not to implement <code>interpolatedIntent</code> support. The <code>intent</code> field MUST always be present as a fallback for such devices.</p> <p><strong>Testing and validation</strong></p> <p>ERC-7730 file authors SHOULD test <code>interpolatedIntent</code> strings with:</p> <ul> <li>Minimum and maximum expected values for each interpolated field</li> <li>Edge cases like zero amounts, maximum allowances, expired dates</li> <li>Long addresses, token names, and other string fields to ensure proper truncation</li> </ul> <h3 id="encryption-support">Encryption support</h3> <p><strong>Display pointers to encrypted values</strong></p> <p>Pointers to encrypted values MAY NOT be fully opaque handles, e.g. they MAY use meaningful prefixes or suffixes containing metadata about the encrypted value. When only partially displaying pointers, wallets SHOULD NOT display these structured parts so that users can discriminate different encrypted values.</p> <h3 id="future-work">Future work</h3> <p>Future improvements could bind frontends to verified contract manifests so that a compromised UI cannot silently substitute a different contract. Clear, auditable registry governance (multi-party signoff, monitoring, and revocation) can further raise the cost of phishing, parameter injection, and front-end compromise 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> 2024-02-04T00:00:00+00:00 2026-02-11T14:48:25+00:00 Igor Żukhttps://github.com/CodeSandwich https://wg-eips.ritovision.com/7613/

A proxy that, if called by its deployer, delegates to an implementation specified in calldata.

<h2 id="abstract">Abstract</h2> <p>A puppet is a contract that, when called, acts like an empty account. It doesn't do anything and it has no API, except when it is called by the address that deployed it. In that case, it delegates the call to the address passed to it in calldata. This gives the deployer the ability to execute any logic they want in the context of the puppet.</p> <h2 id="motivation">Motivation</h2> <p>A puppet can be used as an alternative account of its deployer. It has a different address, so it has a separate set of asset balances. This enables sophisticated accounting, e.g. each user of a protocol can get their own address where assets can be sent and stored. The user may call the protocol contract, which in turn will deploy a new puppet and consider it assigned to the user. If the puppet is deployed under a predictable address, e.g. by using the user's address as the CREATE2 salt, the puppet may not even need to be deployed before funds are sent to its address. From now on the protocol will consider all the assets sent to the puppet as owned by the user. If the protocol needs to move the funds out from the puppet address, it can call the puppet ordering it to delegate to a function transferring the assets to arbitrary addresses, or making arbitrary calls triggering approved transfers to other contracts.</p> <p>Puppets can be used as an alternative to approved transfers when loading funds into the protocol. Any contract and any wallet can transfer the funds to the puppet address assigned to the user without making any approvals or calling the protocol contracts. Funds can be loaded across multiple transactions and potentially from multiple sources. To funnel funds from another protocol, there's no need for integration in the 3rd party contracts as long as they are capable of transferring funds to an arbitrary address. Wallets limited to plain <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> transfers and stripped of any web3 functionality can be used to load funds into the protocol. The users of the fully featured wallets don't need to sign opaque calldata blobs that may be harmful or approve the protocol to take their tokens, they only need to make a transfer, which is a simple process with a familiar UX. When the funds are already stored in the puppet assigned to the user, somebody needs to call the protocol so it's notified that the funds were loaded. Depending on the protocol and its API this call may or may not be permissionless potentially making the UX even more convenient with gasless transactions or 3rd parties covering the gas cost. Some protocols don't need the users to specify what needs to be done with the loaded funds or they allow the users to configure that in advance. Most of the protocols using approved transfers to load funds may benefit from using the puppets.</p> <p>The puppet's logic doesn't need to be ever upgraded. To change its behavior the deployer needs to change the address it passes to the puppet to delegate to or the calldata it passes for delegation. The entire fleet of puppets deployed by a single contract can be upgraded by upgrading the contract that deployed them, without using beacons. A nice trick is that the deployer can make the puppet delegate to the address holding the deployer's own logic, so the puppet's logic is encapsulated in the deployer's.</p> <p>A puppet is unable to expose any API to any caller except the deployer. If a 3rd party needs to be able to somehow make the puppet execute some logic, it can't be requested by directly calling the puppet. Instead, the deployer needs to expose a function that if called by the 3rd parties, will call the puppet, and make it execute the desired logic. Mechanisms expecting contracts to expose some APIs don't work with puppet, e.g. <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>'s <code>safeTransfer</code>s.</p> <p>This standard defines the puppet as a blob of bytes used as creation code, which enables integration with many frameworks and codebases written in variety of languages. The specific tooling is outside of the scope of this standard, but it should be easy to create the libraries and helpers necessary for usage in practice. All the implementations will be interoperable because they will be creating identical puppets and if CREATE2 is used, they will have deterministic addresses predictable by all implementations.</p> <p>Because the puppet can be deployed under a predictable address despite having no fixed logic, in some cases it can be used as a CREATE3 alternative. It can be also used as a full replacement of the CREATE3 factory by using a puppet deployed using CREATE2 to deploy arbitrary code using plain CREATE.</p> <p>Deploying a new puppet is almost as cheap as deploying a new clone proxy. Its whole deployed bytecode is 66 bytes, and its creation code is 62 bytes. Just like clone proxy, it can be deployed using just the Solidity scratch space in memory. The cost to deploy a puppet is 45K gas, only 4K more than a clone. Because the bytecode is not compiled, it can be reliably deployed under a predictable CREATE2 address regardless of the compiler version.</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>To delegate, the deployer must prepend the calldata with an ABI-encoded address to delegate to. All the data after the address will be passed verbatim as the delegation calldata. If the caller isn't the deployer, the calldata is shorter than 32 bytes, or it doesn't start with an address left-padded with zeros, the puppet doesn't do anything. This lets the deployer make a plain native tokens transfer to the puppet, it will have an empty calldata, and the puppet will accept the transfer without delegating.</p> <p>The puppet is deployed with this creation code:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x604260126D60203D3D3683113D3560A01C17733D3360147F331817604057823603803D943D373D3D355AF43D82803E903D91604057FD5BF36034525252F3</span></span></code></pre> <p>The bytecode breakdown:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// The creation code.</span></span> <span class="giallo-l"><span>// [code 1] and [code 2] are parts of the deployed code,</span></span> <span class="giallo-l"><span>// placed respectively before and after the deployer&#39;s address.</span></span> <span class="giallo-l"><span>// | Opcode used | Hex value | Stack content after executing</span></span> <span class="giallo-l"><span>// Code size and offset in memory</span></span> <span class="giallo-l"><span>// | PUSH1 | 60 42 | 66</span></span> <span class="giallo-l"><span>// | PUSH1 | 60 12 | 18 66</span></span> <span class="giallo-l"><span>// The code before the deployer&#39;s address and where it&#39;s stored in memory</span></span> <span class="giallo-l"><span>// | PUSH14 | 6D [code 1] | [code 1] 18 66</span></span> <span class="giallo-l"><span>// | RETURNDATASIZE | 3D | 0 [code 1] 18 66</span></span> <span class="giallo-l"><span>// The deployer&#39;s address and where it&#39;s stored in memory</span></span> <span class="giallo-l"><span>// | CALLER | 33 | [deployer] 0 [code 1] 18 66</span></span> <span class="giallo-l"><span>// | PUSH1 | 60 14 | 20 [deployer] 0 [code 1] 18 66</span></span> <span class="giallo-l"><span>// The code after the deployer&#39;s address and where it&#39;s stored in memory</span></span> <span class="giallo-l"><span>// | PUSH32 | 7F [code 2] | [code 2] 20 [deployer] 0 [code 1] 18 66</span></span> <span class="giallo-l"><span>// | PUSH1 | 60 34 | 52 [code 2] 20 [deployer] 0 [code 1] 18 66</span></span> <span class="giallo-l"><span>// Return the entire code</span></span> <span class="giallo-l"><span>// | MSTORE | 52 | 20 [deployer] 0 [code 1] 18 66</span></span> <span class="giallo-l"><span>// | MSTORE | 52 | 0 [code 1] 18 66</span></span> <span class="giallo-l"><span>// | MSTORE | 52 | 18 66</span></span> <span class="giallo-l"><span>// | RETURN | F3 |</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// The deployed code.</span></span> <span class="giallo-l"><span>// `deployer` is the deployer&#39;s address.</span></span> <span class="giallo-l"><span>// | Opcode used | Hex value | Stack content after executing</span></span> <span class="giallo-l"><span>// Push some constants</span></span> <span class="giallo-l"><span>// | PUSH1 | 60 20 | 32</span></span> <span class="giallo-l"><span>// | RETURNDATASIZE | 3D | 0 32</span></span> <span class="giallo-l"><span>// | RETURNDATASIZE | 3D | 0 0 32</span></span> <span class="giallo-l"><span>// Do not delegate if calldata shorter than 32 bytes</span></span> <span class="giallo-l"><span>// | CALLDATASIZE | 36 | [calldata size] 0 0 32</span></span> <span class="giallo-l"><span>// | DUP4 | 83 | 32 [calldata size] 0 0 32</span></span> <span class="giallo-l"><span>// | GT | 11 | [do not delegate] 0 0 32</span></span> <span class="giallo-l"><span>// Do not delegate if the first word of calldata is not a zero-padded address</span></span> <span class="giallo-l"><span>// | RETURNDATASIZE | 3D | 0 [do not delegate] 0 0 32</span></span> <span class="giallo-l"><span>// | CALLDATALOAD | 35 | [first word] [do not delegate] 0 0 32</span></span> <span class="giallo-l"><span>// | PUSH1 | 60 A0 | 160 [first word] [do not delegate] 0 0 32</span></span> <span class="giallo-l"><span>// | SHR | 1C | [first word upper bits] [do not delegate] 0 0 32</span></span> <span class="giallo-l"><span>// | OR | 17 | [do not delegate] 0 0 32</span></span> <span class="giallo-l"><span>// Do not delegate if not called by the deployer</span></span> <span class="giallo-l"><span>// | PUSH20 | 73 [deployer] | [deployer] [do not delegate] 0 0 32</span></span> <span class="giallo-l"><span>// | CALLER | 33 | [sender] [deployer] [do not delegate] 0 0 32</span></span> <span class="giallo-l"><span>// | XOR | 18 | [sender not deployer] [do not delegate] 0 0 32</span></span> <span class="giallo-l"><span>// | OR | 17 | [do not delegate] 0 0 32</span></span> <span class="giallo-l"><span>// Skip to the return if should not delegate</span></span> <span class="giallo-l"><span>// | PUSH1 | 60 40 | [success branch] [do not delegate] 0 0 32</span></span> <span class="giallo-l"><span>// | JUMPI | 57 | 0 0 32</span></span> <span class="giallo-l"><span>// Calculate the payload size</span></span> <span class="giallo-l"><span>// | DUP3 | 82 | 32 0 0 32</span></span> <span class="giallo-l"><span>// | CALLDATASIZE | 36 | [calldata size] 32 0 0 32</span></span> <span class="giallo-l"><span>// | SUB | 03 | [payload size] 0 0 32</span></span> <span class="giallo-l"><span>// Copy the payload from calldata</span></span> <span class="giallo-l"><span>// | DUP1 | 80 | [payload size] [payload size] 0 0 32</span></span> <span class="giallo-l"><span>// | RETURNDATASIZE | 3D | 0 [payload size] [payload size] 0 0 32</span></span> <span class="giallo-l"><span>// | SWAP5 | 94 | 32 [payload size] [payload size] 0 0 0</span></span> <span class="giallo-l"><span>// | RETURNDATASIZE | 3D | 0 32 [payload size] [payload size] 0 0 0</span></span> <span class="giallo-l"><span>// | CALLDATACOPY | 37 | [payload size] 0 0 0</span></span> <span class="giallo-l"><span>// Delegate call</span></span> <span class="giallo-l"><span>// | RETURNDATASIZE | 3D | 0 [payload size] 0 0 0</span></span> <span class="giallo-l"><span>// | RETURNDATASIZE | 3D | 0 0 [payload size] 0 0 0</span></span> <span class="giallo-l"><span>// | CALLDATALOAD | 35 | [delegate to] 0 [payload size] 0 0 0</span></span> <span class="giallo-l"><span>// | GAS | 5A | [gas] [delegate to] 0 [payload size] 0 0 0</span></span> <span class="giallo-l"><span>// | DELEGATECALL | F4 | [success] 0</span></span> <span class="giallo-l"><span>// Copy return data</span></span> <span class="giallo-l"><span>// | RETURNDATASIZE | 3D | [return size] [success] 0</span></span> <span class="giallo-l"><span>// | DUP3 | 82 | 0 [return size] [success] 0</span></span> <span class="giallo-l"><span>// | DUP1 | 80 | 0 0 [return size] [success] 0</span></span> <span class="giallo-l"><span>// | RETURNDATACOPY | 3E | [success] 0</span></span> <span class="giallo-l"><span>// Return</span></span> <span class="giallo-l"><span>// | SWAP1 | 90 | 0 [success]</span></span> <span class="giallo-l"><span>// | RETURNDATASIZE | 3D | [return size] 0 [success]</span></span> <span class="giallo-l"><span>// | SWAP2 | 91 | [success] 0 [return size]</span></span> <span class="giallo-l"><span>// | PUSH1 | 60 40 | [success branch] [success] 0 [return size]</span></span> <span class="giallo-l"><span>// | JUMPI | 57 | 0 [return size]</span></span> <span class="giallo-l"><span>// | REVERT | FD |</span></span> <span class="giallo-l"><span>// | JUMPDEST | 5B | 0 [return size]</span></span> <span class="giallo-l"><span>// | RETURN | F3 |</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The main goals of the puppet design are low cost and modularity. It should be cheap to deploy and cheap to interact with. The contract should be self-contained, simple to reason about, and easy to use as an architectural building block.</p> <p>The puppet behavior could be implemented fairly easily in Solidity with some inline Yul for delegation. This would make the bytecode much larger and more expensive to deploy. It would also be different depending on the compiler version and configuration, so deployments under predictable addresses using CREATE2 would be trickier.</p> <p>A workaround for the problems with the above solution could be to use the clone proxy pattern to deploy copies of the puppet implementation. It would make the cost to deploy each puppet a little lower than deploying the bytecode proposed in this document, and the addresses of the clones would be predictable when deploying using CREATE2. The downside is that now there would be 1 extra delegation for each call, from the clone proxy to the puppet implementation address, which costs gas. The architecture of such solution is also more complicated with more contracts involved, and it requires the initialization step of deploying the puppet implementation before any clone can be deployed. The initialization step limits the CREATE2 address predictability because the creation code of the clone proxy includes the implementation address, which affects the deployment address.</p> <p>Another alternative is to use the beacon proxy pattern. Making a Solidity API call safely is a relatively complex procedure that takes up a non-trivial space in the bytecode. To lower the cost of the puppets, the beacon proxy probably should be used with the clone proxy, which would be even more complicated and more expensive to use than the above solutions. Querying a beacon for the delegation address is less flexible than passing it in calldata, it requires updating the state of the beacon to change the address.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <p>The puppet bytecode doesn't use PUSH0, because many chains don't support it yet.</p> <h2 id="test-cases">Test Cases</h2> <p>Here are the tests verifying that the bytecode and the reference implementation library are working as expected, using the Foundry test tools:</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-keyword">import</span><span> {</span><span class="z-entity z-name">Test</span><span>}</span><span class="z-keyword"> from</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> {</span><span class="z-entity z-name">Puppet</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;src/Puppet.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"> Logic</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> ERROR </span><span class="z-keyword">=</span><span class="z-string"> &quot;Failure called&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> fallback</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span> data</span><span>)</span><span class="z-storage z-type"> external</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 class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span><span>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"> success</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> arg</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">address</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 class="z-support">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> arg</span><span>,</span><span class="z-variable z-language"> msg</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"> failure</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span>ERROR</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"> PuppetTest</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-support"> address</span><span> puppet </span><span class="z-keyword">=</span><span> Puppet</span><span>.</span><span class="z-entity z-name">deploy</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> logic </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span class="z-keyword">new</span><span class="z-entity z-name"> Logic</span><span>(</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"> logicFailurePayload</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">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> Puppet</span><span>.</span><span class="z-entity z-name">delegationCalldata</span><span>(</span><span>logic</span><span>,</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span>Logic</span><span>.</span><span>failure</span><span>.</span><span>selector</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"> call</span><span>(</span><span class="z-support">address</span><span class="z-variable"> target</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"> internal</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 class="z-entity z-name"> call</span><span>(</span><span>target</span><span>,</span><span> data</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"> call</span><span>(</span><span class="z-support">address</span><span class="z-variable"> target</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-support"> uint256</span><span class="z-variable"> value</span><span>)</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-support">bytes</span><span class="z-storage z-type"> memory</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 class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> returned</span><span>)</span><span class="z-keyword"> =</span><span> target</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span> value</span><span>}</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"> &quot;Unexpected revert&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> returned</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"> testDeployDeterministic</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> salt </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;Puppet&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> newPuppet </span><span class="z-keyword">=</span><span> Puppet</span><span>.</span><span class="z-entity z-name">deployDeterministic</span><span>(</span><span>salt</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> assertEq</span><span>(</span></span> <span class="giallo-l"><span> newPuppet</span><span>,</span><span> Puppet</span><span>.</span><span class="z-entity z-name">predictDeterministicAddress</span><span>(</span><span>salt</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 class="z-string"> &quot;Invalid address&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> assertEq</span><span>(</span></span> <span class="giallo-l"><span> newPuppet</span><span>,</span><span> Puppet</span><span>.</span><span class="z-entity z-name">predictDeterministicAddress</span><span>(</span><span>salt</span><span>)</span><span>,</span><span class="z-string"> &quot;Invalid address when no deployer&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> assertEq</span><span>(</span><span>newPuppet</span><span>.</span><span>code</span><span>,</span><span> puppet</span><span>.</span><span>code</span><span>,</span><span class="z-string"> &quot;Invalid code&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"> testPuppetDelegates</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> arg </span><span class="z-keyword">=</span><span class="z-constant"> 1234</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> data </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span>Logic</span><span>.</span><span>success</span><span>.</span><span>selector</span><span>,</span><span> arg</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> payload </span><span class="z-keyword">=</span><span> Puppet</span><span>.</span><span class="z-entity z-name">delegationCalldata</span><span>(</span><span>logic</span><span>,</span><span> data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> value </span><span class="z-keyword">=</span><span class="z-constant"> 5678</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> returned </span><span class="z-keyword">=</span><span class="z-entity z-name"> call</span><span>(</span><span>puppet</span><span>,</span><span> payload</span><span>,</span><span> value</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> (</span><span class="z-support">address</span><span> thisAddr</span><span>,</span><span class="z-support"> uint256</span><span> receivedArg</span><span>,</span><span class="z-support"> uint256</span><span> receivedValue</span><span>)</span><span class="z-keyword"> =</span></span> <span class="giallo-l"><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>returned</span><span>,</span><span> (</span><span class="z-support">address</span><span>,</span><span class="z-support"> uint256</span><span>,</span><span class="z-support"> uint256</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> assertEq</span><span>(</span><span>thisAddr</span><span>,</span><span> puppet</span><span>,</span><span class="z-string"> &quot;Invalid delegation context&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> assertEq</span><span>(</span><span>receivedArg</span><span>,</span><span> arg</span><span>,</span><span class="z-string"> &quot;Invalid argument&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> assertEq</span><span>(</span><span>receivedValue</span><span>,</span><span> value</span><span>,</span><span class="z-string"> &quot;Invalid value&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"> testPuppetDelegatesWithEmptyCalldata</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> payload </span><span class="z-keyword">=</span><span> Puppet</span><span>.</span><span class="z-entity z-name">delegationCalldata</span><span>(</span><span>logic</span><span>,</span><span class="z-string"> &quot;&quot;</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> returned </span><span class="z-keyword">=</span><span class="z-entity z-name"> call</span><span>(</span><span>puppet</span><span>,</span><span> payload</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> data </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>returned</span><span>,</span><span> (</span><span class="z-support">bytes</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> assertEq</span><span>(</span><span>data</span><span>.</span><span>length</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Delegated with non-empty calldata&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"> testPuppetBubblesRevertPayload</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-support">bytes</span><span>(</span><span class="z-entity z-name">Logic</span><span>(</span><span>logic</span><span>)</span><span>.</span><span class="z-entity z-name">ERROR</span><span>(</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> call</span><span>(</span><span>puppet</span><span>,</span><span class="z-entity z-name"> logicFailurePayload</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"> testPuppetDoesNothingForNonDeployer</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 class="z-support">address</span><span>(</span><span class="z-constant">1234</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> call</span><span>(</span><span>puppet</span><span>,</span><span class="z-entity z-name"> logicFailurePayload</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"> testCallingWithCalldataShorterThan32BytesDoesNothing</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> delegateTo </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span class="z-support">uint160</span><span>(</span><span class="z-constant">1234</span><span>)</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 8</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> payload </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span class="z-support">bytes31</span><span>(</span><span class="z-support">bytes32</span><span>(</span><span class="z-support">uint256</span><span>(</span><span class="z-support">uint160</span><span>(</span><span>delegateTo</span><span>)</span><span>)</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> vm</span><span>.</span><span class="z-entity z-name">mockCallRevert</span><span>(</span><span>delegateTo</span><span>,</span><span class="z-string"> &quot;&quot;</span><span>,</span><span class="z-string"> &quot;Logic called&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> call</span><span>(</span><span>puppet</span><span>,</span><span> payload</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"> testCallingWithDelegationAddressOver20BytesDoesNothing</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> payload </span><span class="z-keyword">=</span><span class="z-entity z-name"> logicFailurePayload</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> payload</span><span>[</span><span class="z-constant">11</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> 0x01</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> call</span><span>(</span><span>puppet</span><span>,</span><span> payload</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"> testCallingPuppetDoesNothing</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"> Forge the calldata, so if puppet uses it to delegate, it will run `Logic.failure`</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> forged </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span class="z-support">uint160</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 class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 32</span><span>;</span></span> <span class="giallo-l"><span> forged </span><span class="z-keyword">|</span><span class="z-keyword">=</span><span class="z-support"> uint32</span><span>(</span><span>Logic</span><span>.</span><span>failure</span><span>.</span><span>selector</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> payload </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSignature</span><span>(</span><span class="z-string">&quot;abc(uint)&quot;</span><span>,</span><span> forged</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> call</span><span>(</span><span>puppet</span><span>,</span><span> payload</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"> testTransferFromDeployerToPuppet</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> amt </span><span class="z-keyword">=</span><span class="z-constant"> 123</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> payable</span><span>(</span><span>puppet</span><span>)</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>amt</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> assertEq</span><span>(</span><span>puppet</span><span>.</span><span>balance</span><span>,</span><span> amt</span><span>,</span><span class="z-string"> &quot;Invalid balance&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"> testTransferToPuppet</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> amt </span><span class="z-keyword">=</span><span class="z-constant"> 123</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> sender </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span class="z-constant">456</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> payable</span><span>(</span><span>sender</span><span>)</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>amt</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>sender</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> payable</span><span>(</span><span>puppet</span><span>)</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>amt</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> assertEq</span><span>(</span><span>puppet</span><span>.</span><span>balance</span><span>,</span><span> amt</span><span>,</span><span class="z-string"> &quot;Invalid balance&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="reference-implementation">Reference Implementation</h2> <p>The puppet bytecode is explained in the specification section. Here's the example helper library:</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"> Puppet</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> constant</span><span> CREATION_CODE </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span> hex</span><span class="z-string">&quot;604260126D60203D3D3683113D3560A01C17733D3360147F33181760405782&quot;</span></span> <span class="giallo-l"><span> hex</span><span class="z-string">&quot;3603803D943D373D3D355AF43D82803E903D91604057FD5BF36034525252F3&quot;</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> CREATION_CODE_HASH </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span>CREATION_CODE</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"> Deploy a new puppet.</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"> instance</span><span class="z-comment"> The address of the puppet.</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>)</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> instance</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> creationCode </span><span class="z-keyword">=</span><span> CREATION_CODE</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> instance </span><span class="z-keyword">:=</span><span class="z-entity z-name"> create</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>creationCode</span><span>,</span><span class="z-constant"> 32</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>creationCode</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>instance </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;Failed to deploy the puppet&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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Deploy a new puppet under a 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"> salt</span><span class="z-comment"> The salt to use for the deterministic deployment.</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"> instance</span><span class="z-comment"> The address of the puppet.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> deployDeterministic</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> salt</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> instance</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> creationCode </span><span class="z-keyword">=</span><span> CREATION_CODE</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> instance </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>creationCode</span><span>,</span><span class="z-constant"> 32</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>creationCode</span><span>)</span><span>,</span><span> salt</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>instance </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;Failed to deploy the puppet&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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Calculate the deterministic address for a puppet deployment made by this 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"> salt</span><span class="z-comment"> The salt to use for the deterministic deployment.</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"> predicted</span><span class="z-comment"> The address of the puppet.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> predictDeterministicAddress</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> salt</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"> predicted</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> predictDeterministicAddress</span><span>(</span><span>salt</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> <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"> Calculate the deterministic address for a puppet deployment.</span></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"> The salt to use for the deterministic deployment.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> deployer</span><span class="z-comment"> The address of the deployer of the puppet.</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"> predicted</span><span class="z-comment"> The address of the puppet.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> predictDeterministicAddress</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> salt</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> deployer</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> internal</span></span> <span class="giallo-l"><span class="z-storage z-type"> pure</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> predicted</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> hash </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>hex</span><span class="z-string">&quot;ff&quot;</span><span>,</span><span> deployer</span><span>,</span><span> salt</span><span>,</span><span> CREATION_CODE_HASH</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-support">uint160</span><span>(</span><span class="z-support">uint256</span><span>(</span><span>hash</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"> delegationCalldata</span><span>(</span><span class="z-support">address</span><span class="z-variable"> delegateTo</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 class="z-storage z-type"> internal</span></span> <span class="giallo-l"><span class="z-storage z-type"> pure</span></span> <span class="giallo-l"><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"> payload</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"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span class="z-support">bytes32</span><span>(</span><span class="z-support">uint256</span><span>(</span><span class="z-support">uint160</span><span>(</span><span>delegateTo</span><span>)</span><span>)</span><span>)</span><span>,</span><span> data</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 bytecode is made to resemble clone proxy's wherever it makes sense to simplify auditing.</p> <p>ABI-encoding the delegation address protects the deployer from being tricked by a 3rd party into calling the puppet and making it delegate to an arbitrary address. Such scenario would only be possible if the deployer called on the puppet a function with the selector <code>0x00000000</code>, which as of now doesn't come from any reasonably named function.</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-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Elaine Zhanghttps://github.com/lanyinzlylz8aj@virginia.edu Jerryjerrymindflow@gmail.com Amandafannyamandafanny200@gmail.com Shouhao Wonghttps://github.com/wangshouhwongshouhao@outlook.com Doris Chehttps://github.com/Cheyukjdorischeyy@gmail.com Henry Yuanhttps://github.com/onehumanbeinghy2878@nyu.edu https://wg-eips.ritovision.com/7615/

An Atomic Mechanism to Allow Publisher Contract Push Data to Subcriber Contracts

<h2 id="abstract">Abstract</h2> <p>This ERC proposes a push-based mechanism for sending data, allowing publisher contract to automatically push certain data to subscriber contracts during a call. The specific implementation relies on two interfaces: one for publisher contract to push data, and another for the subscriber contract to receive data. When the publisher contract is called, it checks if the called function corresponds to subscriber addresses. If it does, the publisher contract push data to the subscriber contracts.</p> <h2 id="motivation">Motivation</h2> <p>Currently, there are many keepers rely on off-chain data or seperate data collection process to monitor the events on chain. This proposal aims to establish a system where the publisher contract can atomicly push data to inform subscriber contracts about the updates. The direct on-chain interaction bewteen the publisher and the subscriber allows the system to be more trustless and efficient.</p> <p>This proposal will offer significant advantages across a range of applications, such as enabling the boundless and permissionless expansion of DeFi, as well as enhancing DAO governance, among others.</p> <h3 id="lending-protocol">Lending Protocol</h3> <p>An example of publisher contract could be an oracle, which can automatically push the price update through initiating a call to the subscriber protocol. The lending protocol, as the subscriber, can automatically liquidate the lending positions based on the received price.</p> <h3 id="automatic-payment">Automatic Payment</h3> <p>A service provider can use a smart contract as a publisher contract, so that when a user call this contract, it can push the information to the subsriber contracts, such as, the users' wallets like NFT bound accounts that follows <a href="https://wg-eips.ritovision.com/6551/">ERC-6551</a> or other smart contract wallets. The user's smart contract wallet can thus perform corresponding payment operations automatically. Compared to traditional <code>approve</code> needed approach, this solution allows more complex logic in implementation, such as limited payment, etc.</p> <h3 id="pos-without-transferring-assets">PoS Without Transferring Assets</h3> <p>For some staking scenarios, especially NFT staking, the PoS contract can be set as the subscriber and the NFT contracts can be set as the publisher. Staking can thus achieved through contracts interation, allowing users to earn staking rewards without transferring assets.</p> <p>When operations like <code>transfer</code> of NFT occur, the NFT contract can push this information to the PoS contract, which can then perform unstaking or other functions.</p> <h3 id="dao-voting">DAO Voting</h3> <p>The DAO governance contract as a publisher could automatically triggers the push mechanism after the vote is completed, calling relevant subscriber contracts to directly implement the voting results, such as injecting funds into a certain account or pool.</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="overview">Overview</h3> <p>The push mechanism can be divided into the following four steps:</p> <ol> <li>The publisher contract is called.</li> <li>The publisher contract query the subscriber list from the <code>selector</code> of the function called. The subscriber contract can put the selected data into <code>inbox</code>.</li> <li>The publisher contract push <code>selector</code> and data through calling <code>exec</code> function of the subscriber contract.</li> <li>The subscriber contract executes based on pushed <code>selector</code> and data, or it may request information from the publisher contract's inbox function as needed.</li> </ol> <p>In the second step, the relationship between a called function and the corresponding subscriber can be configured in the publisher contract. Two configuration schemes are proposed:</p> <ol> <li>Unconditional Push: Any call to the configured <code>selector</code> triggers a push</li> <li>Conditional Push: Only the conditioned calls to the configured <code>selector</code> trigger a push based on the configuration.</li> </ol> <p>It's allowed to configure multiple, different types of subscriber contracts for a single <code>selector</code>. The publisher contract will call the <code>exec</code> function of each subscriber contract to push the request.</p> <p>When unsubscribing a contract from a <code>selector</code>, publisher contract MUST check whether <code>isLocked</code> function of the subscriber contract returns <code>true</code>.</p> <p>It is OPTIONAL for a publisher contract to use the <code>inbox</code> mechanism to store data.</p> <p>In the fourth step, the subscriber contract SHOULD handle all possible <code>selector</code> requests and data in the implementation of <code>exec</code> function. In some cases, <code>exec</code> MAY call <code>inbox</code> function of publisher contract to obtain the pushed data in full.</p> <p><img src="https://wg-eips.ritovision.com/7615/./assets/ERC7615.svg" alt="Workflow" /></p> <h3 id="contract-interface">Contract interface</h3> <p>As mentioned above, there are Unconditional Push and Conditional Push two types of implementation. To implement Unconditional Push, the publisher contract SHOULD implement the following interface:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>interface IPushForce {</span></span> <span class="giallo-l"><span> event ForceApprove(bytes4 indexed selector, address indexed target);</span></span> <span class="giallo-l"><span> event ForceCancel(bytes4 indexed selector, address indexed target);</span></span> <span class="giallo-l"><span> event RenounceForceApprove();</span></span> <span class="giallo-l"><span> event RenounceForceCancel();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> error MustRenounce();</span></span> <span class="giallo-l"><span> error ForceApproveRenounced();</span></span> <span class="giallo-l"><span> error ForceCancelRenounced();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function isForceApproved(bytes4 selector, address target) external returns (bool);</span></span> <span class="giallo-l"><span> function forceApprove(bytes4 selector, address target) external;</span></span> <span class="giallo-l"><span> function forceCancel(bytes4 selector, address target) external;</span></span> <span class="giallo-l"><span> function isRenounceForceApprove() external returns (bool);</span></span> <span class="giallo-l"><span> function isRenounceForceCancel() external returns (bool);</span></span> <span class="giallo-l"><span> function renounceForceApprove(bytes memory) external;</span></span> <span class="giallo-l"><span> function renounceForceCancel(bytes memory) external;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>isForceApproved</code> is to query whether <code>selector</code> has already unconditionally bound to the subscriber contract with the address <code>target</code>. <code>forceApprove</code> is to bind <code>selector</code> to the subscriber contract <code>target</code>. <code>forceCancel</code> is to cancel the binding relationship between <code>selector</code> and <code>target</code>, where <code>isLocked</code> function of <code>target</code> returns <code>true</code> is REQUIRED.</p> <p><code>renounceForceApprove</code> is used to relinquish the <code>forceApprove</code> permission. After calling the <code>renounceForceApprove</code> function, <code>forceApprove</code> can no longer be called. Similarly, <code>renounceForceCancel</code> is used to relinquish the <code>forceCancel</code> permission. After calling the <code>renounceForceCancel</code> function, <code>forceCancel</code> can no longer be called.</p> <p>To implement Conditional Push, the publisher contract SHOULD implement the following interface:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>interface IPushFree {</span></span> <span class="giallo-l"><span> event Approve(bytes4 indexed selector, address indexed target, bytes data);</span></span> <span class="giallo-l"><span> event Cancel(bytes4 indexed selector, address indexed target, bytes data);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function inbox(bytes4 selector) external returns (bytes memory);</span></span> <span class="giallo-l"><span> function isApproved(bytes4 selector, address target, bytes calldata data) external returns (bool);</span></span> <span class="giallo-l"><span> function approve(bytes4 selector, address target, bytes calldata data) external;</span></span> <span class="giallo-l"><span> function cancel(bytes4 selector, address target, bytes calldata data) external;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>isApproved</code>, <code>approve</code>, and <code>cancel</code> have functionalities similar to the corresponding functions in <code>IPushForce</code>. However, an additional <code>data</code> parameter is introduced here for checking whether a push is needed. The <code>inbox</code> here is used to store data in case of being called from the subscriber contract.</p> <p>The publisher contract SHOULD implement <code>_push(bytes4 selector, bytes calldata data)</code> function, which acts as a hook. Any function within the publisher contract that needs to implement push mechanism must call this internal function. The function MUST include querying both unconditional and conditional subscription contracts based on <code>selector</code> and <code>data</code>, and then calling corresponding <code>exec</code> function of the subscribers.</p> <p>A subscriber need to 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"> IExec</span><span> {</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">bytes4</span><span class="z-variable"> selector</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-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"> exec</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> selector</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>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>exec</code> is to receive requests from the publisher contracts and further proceed to execute. <code>isLocked</code> is to check the status of whether the subscriber contract can unsubscribe the publisher contract based on <code>selector</code> and <code>data</code>. It is triggered when a request to unsubscribe is received.</p> <h2 id="rationale">Rationale</h2> <h3 id="unconditional-and-conditional-configuration">Unconditional and Conditional Configuration</h3> <p>When the sending contract is called, it is possible to trigger a push, requiring the caller to pay the resulting gas fees. In some cases, an Unconditional Push is necessary, such as pushing price changes to a lending protocol. While, Conditional Push will reduce the unwanted gas consumption.</p> <h3 id="check-islocked-before-unsubscribing">Check <code>isLocked</code> Before Unsubscribing</h3> <p>Before <code>forceCancel</code> or <code>cancel</code>, the publisher contract MUST call the <code>isLocked</code> function of the subscriber contract to avoid unilateral unsubscribing. The subscriber contract may have a significant logical dependence on the publisher contract, and thus unsubscription could lead to severe issues within the subscriber contract. Therefore, the subscriber contract should implement <code>isLocked</code> function with thorough consideration.</p> <h3 id="inbox-mechanism"><code>inbox</code> Mechanism</h3> <p>In certain scenarios, the publisher contract may only push essential data with <code>selector</code> to the subscriber contracts, while the full data might be stored within <code>inbox</code>. Upon receiving the push from the publisher contract, the subscriber contract is optional to call <code>inbox</code>. <code>inbox</code> mechanism simplifies the push information while still ensuring the availability of complete data, thereby reducing gas consumption.</p> <h3 id="using-function-selectors-as-parameters">Using Function Selectors as Parameters</h3> <p>Using function selectors to retrieve the addresses of subscriber contracts allows more detailed configuration. For the subscriber contract, having the specific function of the request source based on the push information enables more accurate handling of the push information.</p> <h3 id="renounce-safety-enhancement">Renounce Safety Enhancement</h3> <p>Both <code>forceApprove</code> and <code>forceCancel</code> permissions can be relinquished using their respective renounce functions. When both <code>renounceForceApprove</code> and <code>renounceForceCancel</code> are called, the registered push targets can longer be changed, greatly enhancing security.</p> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pragma solidity ^0.8.24;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>import {EnumerableSet} from &quot;@openzeppelin/contracts/utils/structs/EnumerableSet.sol&quot;;</span></span> <span class="giallo-l"><span>import {IPushFree, IPushForce} from &quot;./interfaces/IPush.sol&quot;;</span></span> <span class="giallo-l"><span>import {IExec} from &quot;./interfaces/IExec.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>contract Foo is IPushFree, IPushForce {</span></span> <span class="giallo-l"><span> using EnumerableSet for EnumerableSet.AddressSet;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> bool public override isRenounceForceApprove;</span></span> <span class="giallo-l"><span> bool public override isRenounceForceCancel;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> mapping(bytes4 selector =&gt; mapping(uint256 tokenId =&gt; EnumerableSet.AddressSet targets)) private _registry;</span></span> <span class="giallo-l"><span> mapping(bytes4 selector =&gt; EnumerableSet.AddressSet targets) private _registryOfAll;</span></span> <span class="giallo-l"><span> // mapping(bytes4 =&gt; bytes) public inbox;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> modifier notLock(bytes4 selector, address target, bytes memory data) {</span></span> <span class="giallo-l"><span> require(!IExec(target).isLocked(selector, data), &quot;Foo: lock&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 inbox(bytes4 selector) public view returns (bytes memory data) {</span></span> <span class="giallo-l"><span> uint256 loadData;</span></span> <span class="giallo-l"><span> assembly {</span></span> <span class="giallo-l"><span> loadData := tload(selector)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> data = abi.encode(loadData);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function isApproved(bytes4 selector, address target, bytes calldata data) external view override returns (bool) {</span></span> <span class="giallo-l"><span> uint256 tokenId = abi.decode(data, (uint256));</span></span> <span class="giallo-l"><span> return _registry[selector][tokenId].contains(target);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function isForceApproved(bytes4 selector, address target) external view override returns (bool) {</span></span> <span class="giallo-l"><span> return _registryOfAll[selector].contains(target);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function approve(bytes4 selector, address target, bytes calldata data) external override {</span></span> <span class="giallo-l"><span> uint256 tokenId = abi.decode(data, (uint256));</span></span> <span class="giallo-l"><span> _registry[selector][tokenId].add(target);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function cancel(bytes4 selector, address target, bytes calldata data)</span></span> <span class="giallo-l"><span> external</span></span> <span class="giallo-l"><span> override</span></span> <span class="giallo-l"><span> notLock(selector, target, data)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> uint256 tokenId = abi.decode(data, (uint256));</span></span> <span class="giallo-l"><span> _registry[selector][tokenId].remove(target);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function forceApprove(bytes4 selector, address target) external override {</span></span> <span class="giallo-l"><span> if (isRenounceForceApprove) revert ForceApproveRenounced();</span></span> <span class="giallo-l"><span> _registryOfAll[selector].add(target);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function forceCancel(bytes4 selector, address target) external override notLock(selector, target, &quot;&quot;) {</span></span> <span class="giallo-l"><span> if (isRenounceForceCancel) revert ForceCancelRenounced();</span></span> <span class="giallo-l"><span> _registryOfAll[selector].remove(target);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function renounceForceApprove(bytes memory data) external override {</span></span> <span class="giallo-l"><span> (bool burn) = abi.decode(data, (bool));</span></span> <span class="giallo-l"><span> if (burn != true) {</span></span> <span class="giallo-l"><span> revert MustRenounce();</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> isRenounceForceApprove = true;</span></span> <span class="giallo-l"><span> emit RenounceForceApprove();</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function renounceForceCancel(bytes memory data) external override {</span></span> <span class="giallo-l"><span> (bool burn) = abi.decode(data, (bool));</span></span> <span class="giallo-l"><span> if (burn != true) {</span></span> <span class="giallo-l"><span> revert MustRenounce();</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> isRenounceForceCancel = true;</span></span> <span class="giallo-l"><span> emit RenounceForceCancel();</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function send(uint256 message) external {</span></span> <span class="giallo-l"><span> _push(this.send.selector, message);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function _push(bytes4 selector, uint256 message) internal {</span></span> <span class="giallo-l"><span> assembly {</span></span> <span class="giallo-l"><span> tstore(selector, message)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> address[] memory targets = _registry[selector][message].values();</span></span> <span class="giallo-l"><span> for (uint256 i = 0; i &lt; targets.length; i++) {</span></span> <span class="giallo-l"><span> IExec(targets[i]).exec(selector, abi.encode(message));</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> targets = _registryOfAll[selector].values();</span></span> <span class="giallo-l"><span> for (uint256 i = 0; i &lt; targets.length; i++) {</span></span> <span class="giallo-l"><span> IExec(targets[i]).exec(selector, abi.encode(message));</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>contract Bar is IExec {</span></span> <span class="giallo-l"><span> event Log(bytes4 indexed selector, bytes data, bytes inboxData);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function isLocked(bytes4, bytes calldata) external pure override returns (bool) {</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> function exec(bytes4 selector, bytes calldata data) external {</span></span> <span class="giallo-l"><span> bytes memory inboxData = IPushFree(msg.sender).inbox(selector);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> emit Log(selector, data, inboxData);</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="exec-attacks"><code>exec</code> Attacks</h3> <p>The <code>exec</code> function is <code>public</code>, therefore, it is vulnerable to malicious calls where arbitrary push information can be inserted. Implementations of <code>exec</code> should carefully consider the arbitrariness of calls and should not directly use data passed by the exec function without verification.</p> <h3 id="reentrancy-attack">Reentrancy Attack</h3> <p>The publisher contract's call to the subscriber contract's <code>exec</code> function could lead to reentrancy attacks. Malicious subscription contracts might construct reentrancy attacks to the publisher contract within <code>exec</code>.</p> <h3 id="arbitrary-target-approve">Arbitrary Target Approve</h3> <p>Implementation of <code>forceApprove</code> and <code>approve</code> should have reasonable access controls; otherwise, unnecessary gas losses could be imposed on callers.</p> <p>Check the gas usage of the <code>exec</code> function.</p> <h3 id="islocked-implementation">isLocked implementation</h3> <p>Subscriber contracts should implement the <code>isLocked</code> function to avoid potential loss brought by unsubscription. This is particularly crucial for lending protocols implementing this proposal. Improper unsubscription can lead to abnormal clearing, causing considerable losses.</p> <p>Similarly, when subscribing, the publisher contract should consider whether <code>isLocked</code> is properly implemented to prevent irrevocable subscriptions.</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-02T00:00:00+00:00 2026-02-11T14:49:27+00:00 Gary Ronghttps://github.com/rjl493456442 Martin Holst Swendehttps://github.com/holiman https://wg-eips.ritovision.com/7610/

Revert contract creation if address already has the non-empty storage

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

Adds a JSON-RPC method for requesting a signature from a wallet

<h2 id="abstract">Abstract</h2> <p>Defines a new JSON-RPC method <code>wallet_sign</code> which enables apps to ask a wallet to sign <a href="https://wg-eips.ritovision.com/191/">EIP-191</a> messages.</p> <p>Applications can use this JSON-RPC method to request a signature over any version of <code>signed_data</code> as defined by <a href="https://wg-eips.ritovision.com/191/">EIP-191</a>. The new JSON-RPC method allows for support of future <a href="https://wg-eips.ritovision.com/191/">EIP-191</a> <code>signed_data</code> versions.</p> <p>The new JSON-RPC method also supports <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a>-style <code>capabilities</code>, and support for signing capabilities can be discovered using <code>wallet_getCapabilities</code> as defined in <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a>.</p> <h2 id="motivation">Motivation</h2> <p>Wallets and developer tools currently support multiple JSON-RPC methods for handling offchain signature requests. This proposal simplifies wallet &amp; tooling implementations by consolidating these requests under a single <code>wallet_sign</code> JSON-RPC method. This also leaves room for new <a href="https://wg-eips.ritovision.com/191/">EIP-191</a> <code>signed_data</code> versions without needing to introduce a new corresponding JSON-RPC method.</p> <p>Furthermore, this new <code>wallet_sign</code> method introduces new functionalities via <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a>-style <code>capabilities</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. One new JSON-RPC method is introduced.</p> <h3 id="wallet-sign"><code>wallet_sign</code></h3> <p>Requests a signature over <a href="https://wg-eips.ritovision.com/191/">EIP-191</a> <code>signed_data</code> from a wallet.</p> <p>The top-level <code>version</code> parameter is for specifying the version of <code>wallet_sign</code> should the top-level interface change.</p> <p>The <code>request.type</code> parameter is for specifying the <a href="https://wg-eips.ritovision.com/191/">EIP-191</a> <code>signed_data</code> <code>version</code> (e.g. <code>0x01</code> for structured data, <code>0x45</code> for <code>personal_sign</code> messaged). The <code>request.data</code> parameter is the corresponding data according to the <code>signed_data</code> <code>version</code>.</p> <p>The optional <code>address</code> parameter is for requesting a signature from a specified address. If included, the wallet MUST respect it and only respond with a signature from that address.</p> <p>The capabilities field is how an app can communicate with a wallet about capabilities that a wallet supports.</p> <p>This proposal defines <code>request</code> schemas for the three <code>signed_data</code> versions currently in <a href="https://wg-eips.ritovision.com/191/">EIP-191</a> (<code>0x00</code>, <code>0x01</code>, <code>0x45</code>). Any future <code>signed_data</code> versions can be supported by <code>wallet_sign</code>, and their <code>request</code> interfaces are left to future ERCs.</p> <h4 id="wallet-sign-rpc-specification"><code>wallet_sign</code> RPC Specification</h4> <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"> Capability</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span> [</span><span class="z-variable">key</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>]</span><span class="z-keyword">:</span><span class="z-support"> unknown</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 class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> SignParams</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"> address</span><span class="z-keyword">?</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> <span class="giallo-l"><span class="z-variable"> request</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> 1-byte EIP-191 version</span></span> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">:</span><span class="z-support"> any</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> data corresponding to the above version</span></span> <span class="giallo-l"><span> }</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> capabilities</span><span class="z-keyword">?</span><span class="z-keyword">:</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"> SignResult</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> signature</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> <span class="giallo-l"><span class="z-variable"> capabilities</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h5 id="request-interfaces">Request Interfaces</h5> <p>Below are <code>request</code> interfaces for the <code>signed_data</code> <code>version</code>s specified in <a href="https://wg-eips.ritovision.com/191/">EIP-191</a> at time of writing. These include:</p> <ul> <li><code>0x00</code> - Data with intended validator</li> <li><code>0x01</code> - <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> Typed Data</li> <li><code>0x45</code> - Personal Sign</li> </ul> <p>Any new <code>request</code> interfaces corresponding to new <code>signed_data</code> <code>version</code>s SHOULD be defined in their own ERCs.</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"> ValidatorRequest</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x00</span><span class="z-punctuation z-definition z-string">&#39;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> validator</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Intended validator address</span></span> <span class="giallo-l"><span class="z-variable"> data</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Data to sign</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">type</span><span class="z-entity z-name"> TypedDataRequest</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x01</span><span class="z-punctuation z-definition z-string">&#39;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> ...</span><span class="z-entity z-name">TypedData</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> TypedData as defined by EIP-712</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">type</span><span class="z-entity z-name"> PersonalSignRequest</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x45</span><span class="z-punctuation z-definition z-string">&#39;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> message</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> UTF-8 message string</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="wallet-sign-example-parameters"><code>wallet_sign</code> Example Parameters</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">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">request</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">0x45</span><span class="z-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> {</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">Hello world</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><h5 id="wallet-sign-example-return-value"><code>wallet_sign</code> Example Return Value</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">signature</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><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> <!-- TODO --> <h2 id="security-considerations">Security Considerations</h2> <!-- TODO --> <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-27T00:00:00+00:00 2026-02-11T14:48:26+00:00 calvborehttps://github.com/calvbore emiliolanzalacohttps://github.com/emiliolanzalaco https://wg-eips.ritovision.com/7604/

Permit approvals for ERC-1155 tokens

<h2 id="abstract">Abstract</h2> <p>The "permit" approval flow for both <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> are large improvements for the existing UX of the token underlying each ERC. This ERC extends the "permit" pattern to <a href="https://wg-eips.ritovision.com/20/">ERC-1155</a> tokens, borrowing heavily upon both <a href="https://wg-eips.ritovision.com/4494/">ERC-4494</a> and <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a>.</p> <p>The structure of <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> tokens requires a new ERC to account for the token standard's use of both token IDs and balances (also why this ERC requires <a href="https://wg-eips.ritovision.com/5216/">ERC-5216</a>).</p> <h2 id="motivation">Motivation</h2> <p>The permit structures outlined in both <a href="https://wg-eips.ritovision.com/4494/">ERC-4494</a> and <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a> allows a signed message to create an approval, but are only applicable to their respective underlying tokens (<a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/20/">ERC-20</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> <p>Three new functions must be added to ERC-1155 and ERC-5216.</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"> IERC1155Permit</span><span> {</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"> owner</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-support"> uint256</span><span class="z-variable"> value</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-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-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-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>owner</code>, <code>spender</code>, uint256's <code>tokenId</code>, <code>value</code>, <code>deadline</code>, and <code>nonce</code>, bytes <code>sig</code>, a call to <code>permit(owner, spender, tokenId, value, deadline, sig)</code> MUST set <code>allowance(owner, spender, tokenId)</code> to <code>value</code>, increment <code>nonces(owner, tokenId)</code> by 1, and emit a corresponding <code>Approval</code> event defined by <a href="https://wg-eips.ritovision.com/5216/">ERC-5216</a>, 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><code>owner</code> is not the zero address</li> <li><code>nonces[owner][tokenId]</code> (before state update) is equal to <code>nonce</code></li> <li><code>sig</code> is a valid <code>secp256k1</code>, <a href="https://wg-eips.ritovision.com/2098/">ERC-2098</a>, or <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> signature from <code>owner</code> of the message:</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 owner,address spender,uint256 tokenId,uint256 value,uint256 nonce,uint256 deadline)&quot;),</span></span> <span class="giallo-l"><span> owner,</span></span> <span class="giallo-l"><span> spender,</span></span> <span class="giallo-l"><span> tokenId,</span></span> <span class="giallo-l"><span> value,</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>If any of these conditions are not met the <code>permit</code> call MUST revert.</p> <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 EIP-712 typed structure:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> &quot;types&quot;: {</span></span> <span class="giallo-l"><span> &quot;EIP712Domain&quot;: [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;name&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;version&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;chainId&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> {</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;verifyingContract&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> ],</span></span> <span class="giallo-l"><span> &quot;Permit&quot;: [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;owner&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> {</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;spender&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> {</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;tokenId&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> {</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> {</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;nonce&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> {</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;deadline&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> ],</span></span> <span class="giallo-l"><span> &quot;primaryType&quot;: &quot;Permit&quot;,</span></span> <span class="giallo-l"><span> &quot;domain&quot;: {</span></span> <span class="giallo-l"><span> &quot;name&quot;: erc1155name,</span></span> <span class="giallo-l"><span> &quot;version&quot;: version,</span></span> <span class="giallo-l"><span> &quot;chainId&quot;: chainid,</span></span> <span class="giallo-l"><span> &quot;verifyingContract&quot;: tokenAddress</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;message&quot;: {</span></span> <span class="giallo-l"><span> &quot;owner&quot;: owner,</span></span> <span class="giallo-l"><span> &quot;spender&quot;: spender,</span></span> <span class="giallo-l"><span> &quot;tokenId&quot;: tokenId,</span></span> <span class="giallo-l"><span> &quot;value&quot;: value,</span></span> <span class="giallo-l"><span> &quot;nonce&quot;: nonce,</span></span> <span class="giallo-l"><span> &quot;deadline&quot;: deadline</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}}</span></span></code></pre> <p>The <code>permit</code> function MUST check that the signer is not the zero address.</p> <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/">ERC-165</a>. ERC-165 is already required in <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>, but is further necessary here in order to register the interface of this ERC. Doing so will allow easy verification if an NFT contract has implemented this ERC or not, enabling them to interact accordingly. The ERC-165 interface of this ERC is <code>0x7409106d</code>. Contracts implementing this ERC MUST have the <code>supportsInterface</code> function return <code>true</code> when called with <code>0x7409106d</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 <code>deadline</code> argument can be set to <code>uint(-1)</code> to create Permits that effectively never expire. Likewise, the <code>value</code> argument can be set to <code>uint(-1)</code> to create Permits with effectively unlimited allowances.</p> <p>EIP-712 typed messages are included because of its use in <a href="https://wg-eips.ritovision.com/4494/">ERC-4494</a> and <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a>, which in turn cites widespread adoption in many wallet providers.</p> <p>This ERC focuses on both the <code>value</code> and <code>tokenId</code> being approved, ERC-4494 focuses only on the <code>tokenId</code>, while ERC-2612 focuses primarily on the <code>value</code>. ERC-1155 does not natively support approvals by amount, thus this ERC requires ERC-5216, otherwise a <code>permit</code> would grant approval for an account's entire <code>tokenId</code> balance.</p> <p>Whereas ERC-2612 splits signatures into their <code>v,r,s</code> components, this ERC opts to instead take a <code>bytes</code> array of variable length in order to support <a href="https://wg-eips.ritovision.com/1271/">ERC-2098</a> signatures, which may not be easily separated or reconstructed from <code>r,s,v</code> components (65 bytes).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The below considerations have been copied from ERC-4494.</p> <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 ERC-20 race condition for approvals 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> 2024-01-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Haruhttps://github.com/haruu8 https://wg-eips.ritovision.com/7603/

An interface compatible with ERC-1155 for Multi-Asset tokens with context-dependent asset type output control.

<h2 id="abstract">Abstract</h2> <p>The Multi-Asset Token standard, compatible with <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>, facilitates the development of a new fundamental component: the context-dependent data output for each collection.</p> <p>The context-dependent data output means that the asset is displayed in an appropriate format based on how the token is accessed. I.e., if the token is being opened in an e-book reader, the PDF asset is displayed; if the token is opened in the marketplace, the PNG or the SVG asset is displayed; if the token is accessed from within a game, the 3D model asset is accessed, and if the token is accessed by an Internet of Things (IoT) hub, the asset providing the necessary addressing and specification information is accessed.</p> <p>A Token Collection can have multiple assets (outputs), which can be any file to order them by priority. They do not have to match in mime-type or tokenURI, nor do they depend on one another. Assets are not standalone entities but should be considered “namespaced tokenURIs”.</p> <h2 id="motivation">Motivation</h2> <p>With ERC-1155 compatible tokens being a widespread form of tokens in the Ethereum ecosystem and being used for various use cases, it is time to standardize additional utility for them. Having multiple assets associated with a single Token Collection allows for greater utility, usability, and forward compatibility. This EIP improves upon ERC-1155 in the following areas:</p> <ul> <li><a href="https://wg-eips.ritovision.com/7603/#cross-metaverse-compatibility">Cross-metaverse compatibility</a></li> <li><a href="https://wg-eips.ritovision.com/7603/#multi-media-output">Multi-media output</a></li> <li><a href="https://wg-eips.ritovision.com/7603/#media-redundancy">Media redundancy</a></li> </ul> <h3 id="cross-metaverse-compatibility">Cross-metaverse compatibility</h3> <p>The proposal can support any number of different implementations.</p> <p>Cross-metaverse compatibility could also be referred to as cross-engine compatibility. An example is where a cosmetic item for game A is unavailable in game B because the frameworks are incompatible.</p> <p>Such Tokens can be given further utility through new assets: more games, cosmetic items, and more.</p> <p>The following is a more concrete example. One asset is a cosmetic item for game A, a file containing the cosmetic assets. Another is a cosmetic asset file for game B. A third is a generic asset intended to be shown in catalogs, marketplaces, portfolio trackers, or other generalized Token Collection viewers, containing a representation, stylized thumbnail, and animated demo/trailer of the cosmetic item.</p> <p>This EIP adds a layer of abstraction, allowing game developers to pull asset data from a user's Tokens directly instead of hard-coding it.</p> <h3 id="multi-media-output">Multi-media output</h3> <p>Tokens of an eBook can be represented as a PDF, MP3, or some other format, depending on what software loads it. If loaded into an eBook reader, a PDF should be displayed, and if loaded into an audiobook application, the MP3 representation should be used. Other metadata could be present in the Tokens (perhaps the book's cover image) for identification on various marketplaces, Search Engine Result Pages (SERPs), or portfolio trackers.</p> <h3 id="media-redundancy">Media redundancy</h3> <p>Many Tokens are minted hastily without best practices in mind. Specifically, many Tokens are minted with metadata centralized on a server somewhere or, in some cases, a hardcoded IPFS gateway which can also go down, instead of just an IPFS hash.</p> <p>By adding the same metadata file as different assets, e.g., one asset of metadata and its linked image on Arweave, one asset of this same combination on Sia, another of the same combination on IPFS, etc., the resilience of the metadata and its referenced information increases exponentially as the chances of all the protocols going down at once become less likely.</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> <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-7603 Context-Dependent Multi-Asset Tokens, ERC-1155 Execution</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/erc-7603</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.23</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"> IERC7603</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">@notice</span><span class="z-comment"> Used to notify listeners that an asset object is initialised at `assetId`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assetId</span><span class="z-comment"> ID of the asset that was initialised</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"> AssetSet</span><span>(</span><span class="z-support">uint64</span><span class="z-variable"> assetId</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"> Used to notify listeners that an asset object at `assetId` is added to token&#39;s asset</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> tokenId</span><span class="z-comment"> An ID of the token that received a new asset</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assetId</span><span class="z-comment"> ID of the asset that has been added to the token&#39;s assets 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"> replacesId</span><span class="z-comment"> ID of the asset that would be replaced</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"> AssetAddedToToken</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> assetId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> replacesId</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"> Used to notify listeners that token&#39;s priority array is reordered.</span></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 token that had the asset priority array updated</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"> AssetPrioritySet</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">@notice</span><span class="z-comment"> Sets a new priority array for a given token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The priority array is a non-sequential list of `uint16`s, where the lowest value is considered highest</span></span> <span class="giallo-l"><span class="z-comment"> * priority.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Value `0` of a priority is a special case equivalent to uninitialised.</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"> * - `tokenId` must exist.</span></span> <span class="giallo-l"><span class="z-comment"> * - The length of `priorities` must be equal the length of the assets array.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {AssetPrioritySet} 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"> tokenId</span><span class="z-comment"> ID of the token to set the priorities 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"> priorities</span><span class="z-comment"> An array of priorities of assets. The succession of items in the priorities array</span></span> <span class="giallo-l"><span class="z-comment"> * matches that of the succession of items in 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"> setPriority</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</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"> priorities</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to retrieve IDs of assets of given token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Asset data is stored by reference, in order to access the data corresponding to the ID, call</span></span> <span class="giallo-l"><span class="z-comment"> * `getAssetMetadata(tokenId, assetId)`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> You can safely get 10k</span></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 token to retrieve the IDs of the assets</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">[] An array of the asset IDs of the given 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"> getAssets</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">uint64</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to retrieve the priorities of the assets of a given token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Asset priorities are a non-sequential array of uint16 values with an array size equal to asset</span></span> <span class="giallo-l"><span class="z-comment"> * priorites.</span></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 token for which to retrieve the priorities of the assets</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"> uint16</span><span class="z-comment">[] An array of priorities of the assets of the given 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"> getAssetPriorities</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">uint64</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to fetch the asset metadata of the specified token&#39;s asset with the given index.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Can be overridden to implement enumerate, fallback or other custom logic.</span></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 token from which to retrieve the asset 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"> assetId</span><span class="z-comment"> Asset Id, must be in the assets 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"> string</span><span class="z-comment"> The metadata of the asset belonging to the specified index in the token&#39;s assets 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"> getAssetMetadata</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"> assetId</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 class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h2 id="rationale">Rationale</h2> <p>TBD <!-- TODO --></p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The MultiAsset token standard has been made compatible with ERC-1155 in order to take advantage of the robust tooling available for implementations of ERC-1155 and to ensure compatibility with existing ERC-1155 infrastructure.</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-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-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Yvonne Zhanghttps://github.com/yvonnezhangc Aloysius Chanhttps://github.com/circle-aloychan https://wg-eips.ritovision.com/7597/

An ERC to extend ERC-2612 Permit to support ERC-1271-based signature validation.

<h1 id="eip-contract-signature-validation-extension-for-erc-2612-permit">EIP: Contract signature validation extension for <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a> Permit</h1> <h2 id="abstract">Abstract</h2> <p>This proposal aims to extend the functionality of the existing <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a> Permit to support gasless <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> approval operations initiated by smart contract wallets.</p> <h2 id="motivation">Motivation</h2> <p>The current signature validation scheme in <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a>, based on V, R, S parameters, restricts signature validation to EOA wallets.</p> <p>With the growing popularity of smart contract wallets and increased adoption of <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>, it is necessary to allow for flexible signature validation methods and the use of custom logic in each contract's signature verification. By accepting unstructured signature bytes as input, custom algorithms and signature schemes can be utilized, enabling a wider range of wallet types.</p> <h2 id="specification">Specification</h2> <p>Compliant contracts must implement the <code>permit</code> using the following spec</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function permit(address owner, address spender, uint value, uint deadline, bytes memory signature) external</span></span></code></pre> <p>as well as two other interfaces previously mandated by <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function nonces(address owner) external view returns (uint)</span></span> <span class="giallo-l"><span>function DOMAIN_SEPARATOR() external view returns (bytes32)</span></span></code></pre> <p>A call to <code>permit(owner, spender, value, deadline, signature)</code> will set <code>allowance[owner][spender]</code> to value, increment <code>nonces[owner]</code> by 1, and 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><code>owner</code> is not the zero address.</li> <li><code>nonces[owner]</code> (before the state update) is equal to nonce.</li> <li><code>signature</code> validation: <ul> <li>If <code>owner</code> is an EOA, <code>signature</code> is a valid secp256k1 signature in the form of <code>abi.encodePacked(r, s, v)</code>.</li> <li>If <code>owner</code> is a contract, <code>signature</code> is validated by calling <code>isValidSignature()</code> on the <code>owner</code> contract.</li> </ul> </li> </ul> <p>If any of these conditions are not met, the permit call must revert.</p> <h2 id="rationale">Rationale</h2> <p>By replacing the existing V, R, S signature validation scheme and introducing support for unstructured bytes input, contract developers can use a unified interface to validate signature from both EOAs and SC wallets. This allows for the utilization of different signature schemes and algorithms fitting the wallet type, paving the way for smart contract wallets and advanced wallet types to enhance their signature validation processes, promoting flexibility and innovation.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backward-compatible with the existing ERC-2612 standard. Contracts that currently rely on the V, R, S signature validation scheme will continue to function without any issues.</p> <p>If both V, R, S signature validation and the new unstructured bytes signature validation need to be supported for backward compatibility reasons, developers can reduce duplicates by adapting the following code block as an example:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function permit(</span></span> <span class="giallo-l"><span> address owner,</span></span> <span class="giallo-l"><span> address spender,</span></span> <span class="giallo-l"><span> uint256 value,</span></span> <span class="giallo-l"><span> uint256 deadline,</span></span> <span class="giallo-l"><span> uint8 v, </span></span> <span class="giallo-l"><span> bytes32 r, </span></span> <span class="giallo-l"><span> bytes32 s</span></span> <span class="giallo-l"><span>) external {</span></span> <span class="giallo-l"><span> _permit(owner, spender, value, deadline, abi.encodePacked(r, s, v));</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>Sample <code>permit</code> implemented with OZ's SignatureChecker</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"> Update allowance with a signed permit</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Signature bytes can be used for both EOA wallets and contract wallets.</span></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"> Token owner&#39;s address (Authorizer)</span></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"> Spender&#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"> value</span><span class="z-comment"> Amount of allowance</span></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"> The time at which the signature expires (unix 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"> signature</span><span class="z-comment"> Unstructured bytes signature signed by an EOA wallet or a contract 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"> permit</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"> address</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"> deadline</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"> signature</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>deadline </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-variable z-language"> now</span><span>,</span><span class="z-string"> &quot;Permit is expired&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>owner </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;ERC20: approve from the zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>spender </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;ERC20: approve to the zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></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> <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;Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)&quot;</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> owner</span><span>,</span></span> <span class="giallo-l"><span> spender</span><span>,</span></span> <span class="giallo-l"><span> value</span><span>,</span></span> <span class="giallo-l"><span> nonce</span><span>,</span></span> <span class="giallo-l"><span> deadline</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 class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Check for both ECDSA signature and ERC-1271 signature. A sample SignatureChecker is available at</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> https://github.com/OpenZeppelin/openzeppelin-contracts/blob/7bd2b2a/contracts/utils/cryptography/SignatureChecker.sol</span></span> <span class="giallo-l"><span> SignatureChecker</span><span>.</span><span class="z-entity z-name">isValidSignatureNow</span><span>(</span></span> <span class="giallo-l"><span> owner</span><span>,</span></span> <span class="giallo-l"><span> typedDataHash</span><span>,</span></span> <span class="giallo-l"><span> signature</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Invalid signature&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> allowed</span><span>[</span><span>owner</span><span>]</span><span>[</span><span>spender</span><span>]</span><span class="z-keyword"> =</span><span> value</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Approval</span><span>(</span><span>owner</span><span>,</span><span> spender</span><span>,</span><span> value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <ul> <li>For contract wallets, the security of <code>permit</code> relies on <code>isValidSignature()</code> to ensure the signature bytes represent the desired execution from contract wallet owner(s). Contract wallet developers must exercise caution when implementing custom signature validation logic to ensure the security of their contracts.</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> 2024-01-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Yvonne Zhanghttps://github.com/yvonnezhangc Aloysius Chanhttps://github.com/circle-aloychan https://wg-eips.ritovision.com/7598/

An ERC to extend ERC-3009 Transfer with Authorization to support ERC-1271 signature validation.

<h1 id="eip-contract-signature-validation-extension-for-erc-3009-transfer-with-authorization">EIP: Contract signature validation extension for <a href="https://wg-eips.ritovision.com/3009/">ERC-3009</a> Transfer with Authorization</h1> <h2 id="abstract">Abstract</h2> <p>This proposal aims to extend the functionality of the existing <a href="https://wg-eips.ritovision.com/3009/">ERC-3009</a> standard, "Transfer With Authorization," to support transfer operations initiated by smart contract wallets.</p> <h2 id="motivation">Motivation</h2> <p>The existing <a href="https://wg-eips.ritovision.com/3009/">ERC-3009</a> standard enables asset transfers with ECDSA signatures. However, as smart contract wallets become more prevalent in the ecosystem, the current standard is no longer sufficient.</p> <p>This proposal aims to enhance the usability and composeability of the standard by extending ERC-3009 with smart contract wallet signature validation, as defined in <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>. By incorporating this extension, users will have greater flexibility in managing their assets while ensuring a secure authorization process.</p> <h2 id="specification">Specification</h2> <p>The following events and interfaces must still be present given the initial spec defined in <a href="https://wg-eips.ritovision.com/3009/">ERC-3009</a>.</p> <ul> <li>Event <code>AuthorizationUsed</code>.</li> <li>Constants <code>TRANSFER_WITH_AUTHORIZATION_TYPEHASH</code> and <code>RECEIVE_WITH_AUTHORIZATION_TYPEHASH</code>.</li> <li>View function interface <code>authorizationState(address authorizer, bytes32 nonce)</code></li> </ul> <p>In addition, the following interfaces must be added to be compliant with the standard:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * @notice Execute a transfer with a signed authorization</span></span> <span class="giallo-l"><span> * @param from Payer&#39;s address (Authorizer)</span></span> <span class="giallo-l"><span> * @param to Payee&#39;s address</span></span> <span class="giallo-l"><span> * @param value Amount to be transferred</span></span> <span class="giallo-l"><span> * @param validAfter The time after which this is valid (unix time)</span></span> <span class="giallo-l"><span> * @param validBefore The time before which this is valid (unix time)</span></span> <span class="giallo-l"><span> * @param nonce Unique nonce</span></span> <span class="giallo-l"><span> * @param signature Unstructured bytes signature signed by an EOA wallet or a contract wallet</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>function transferWithAuthorization(</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 validAfter,</span></span> <span class="giallo-l"><span> uint256 validBefore,</span></span> <span class="giallo-l"><span> bytes32 nonce,</span></span> <span class="giallo-l"><span> bytes memory signature</span></span> <span class="giallo-l"><span>) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * @notice Receive a transfer with a signed authorization from the payer</span></span> <span class="giallo-l"><span> * @dev This has an additional check to ensure that the payee&#39;s address matches</span></span> <span class="giallo-l"><span> * the caller of this function to prevent front-running attacks. (See security</span></span> <span class="giallo-l"><span> * considerations)</span></span> <span class="giallo-l"><span> * @param from Payer&#39;s address (Authorizer)</span></span> <span class="giallo-l"><span> * @param to Payee&#39;s address</span></span> <span class="giallo-l"><span> * @param value Amount to be transferred</span></span> <span class="giallo-l"><span> * @param validAfter The time after which this is valid (unix time)</span></span> <span class="giallo-l"><span> * @param validBefore The time before which this is valid (unix time)</span></span> <span class="giallo-l"><span> * @param nonce Unique nonce</span></span> <span class="giallo-l"><span> * @param signature Unstructured bytes signature signed by an EOA wallet or a contract wallet</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>function receiveWithAuthorization(</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 validAfter,</span></span> <span class="giallo-l"><span> uint256 validBefore,</span></span> <span class="giallo-l"><span> bytes32 nonce,</span></span> <span class="giallo-l"><span> bytes memory signature</span></span> <span class="giallo-l"><span>) external;</span></span></code></pre> <p>Optional:</p> <p>The <code>AuthorizationCanceled</code> event and <code>CANCEL_AUTHORIZATION_TYPEHASH</code> constant as defined in the <a href="https://wg-eips.ritovision.com/3009/">ERC-3009</a> spec.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * @notice Attempt to cancel an authorization</span></span> <span class="giallo-l"><span> * @param authorizer Authorizer&#39;s address</span></span> <span class="giallo-l"><span> * @param nonce Nonce of the authorization</span></span> <span class="giallo-l"><span> * @param signature Unstructured bytes signature signed by an EOA wallet or a contract wallet</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>function cancelAuthorization(</span></span> <span class="giallo-l"><span> address authorizer,</span></span> <span class="giallo-l"><span> bytes32 nonce,</span></span> <span class="giallo-l"><span> bytes memory signature</span></span> <span class="giallo-l"><span>) external;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>By replacing the existing V, R, S signature validation scheme and introducing support for unstructured bytes input, contract developers can use a unified interface to validate signature from both EOAs and SC wallets. This allows for the utilization of different signature schemes and algorithms fitting the wallet type, paving the way for smart contract wallets and advanced wallet types to enhance their signature validation processes, promoting flexibility and innovation.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backward-compatible with the existing ERC-3009 standard. Contracts that currently rely on the V, R, S signature validation scheme will continue to function without any issues.</p> <p>In the event that both the existing V, R, S signature validation scheme and the new unstructured bytes signature validation need to be supported for backward compatibility, developers can reduce duplicates by adapting the following code block as an example:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function transferWithAuthorization(</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 validAfter,</span></span> <span class="giallo-l"><span> uint256 validBefore,</span></span> <span class="giallo-l"><span> bytes32 nonce,</span></span> <span class="giallo-l"><span> uint8 v,</span></span> <span class="giallo-l"><span> bytes32 r,</span></span> <span class="giallo-l"><span> bytes32 s</span></span> <span class="giallo-l"><span>) external {</span></span> <span class="giallo-l"><span> transferWithAuthorization(owner, spender, value, deadline, abi.encodePacked(r, s, v));</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * @notice Execute a transfer with a signed authorization</span></span> <span class="giallo-l"><span> * @dev EOA wallet signatures should be packed in the order of r, s, v.</span></span> <span class="giallo-l"><span> * @param from Payer&#39;s address (Authorizer)</span></span> <span class="giallo-l"><span> * @param to Payee&#39;s address</span></span> <span class="giallo-l"><span> * @param value Amount to be transferred</span></span> <span class="giallo-l"><span> * @param validAfter The time after which this is valid (unix time)</span></span> <span class="giallo-l"><span> * @param validBefore The time before which this is valid (unix time)</span></span> <span class="giallo-l"><span> * @param nonce Unique nonce</span></span> <span class="giallo-l"><span> * @param signature Signature byte array produced by an EOA wallet or a contract wallet</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>function _transferWithAuthorization(</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 validAfter,</span></span> <span class="giallo-l"><span> uint256 validBefore,</span></span> <span class="giallo-l"><span> bytes32 nonce,</span></span> <span class="giallo-l"><span> bytes memory signature</span></span> <span class="giallo-l"><span>) internal {</span></span> <span class="giallo-l"><span> require(now &gt; validAfter, &quot;Authorization is not yet valid&quot;);</span></span> <span class="giallo-l"><span> require(now &lt; validBefore, &quot;Authorization is expired&quot;);</span></span> <span class="giallo-l"><span> require(!_authorizationStates[authorizer][nonce], &quot;Authorization is used or canceled&quot;);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> bytes32 digest = 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> TRANSFER_WITH_AUTHORIZATION_TYPEHASH,</span></span> <span class="giallo-l"><span> from,</span></span> <span class="giallo-l"><span> to,</span></span> <span class="giallo-l"><span> value,</span></span> <span class="giallo-l"><span> validAfter,</span></span> <span class="giallo-l"><span> validBefore,</span></span> <span class="giallo-l"><span> nonce</span></span> <span class="giallo-l"><span> ))</span></span> <span class="giallo-l"><span> ));</span></span> <span class="giallo-l"><span> require(</span></span> <span class="giallo-l"><span> // Check for both ECDSA signature and ERC-1271 signature. A sample SignatureChecker is available at</span></span> <span class="giallo-l"><span> // https://github.com/OpenZeppelin/openzeppelin-contracts/blob/7bd2b2a/contracts/utils/cryptography/SignatureChecker.sol</span></span> <span class="giallo-l"><span> SignatureChecker.isValidSignatureNow(</span></span> <span class="giallo-l"><span> owner,</span></span> <span class="giallo-l"><span> typedDataHash,</span></span> <span class="giallo-l"><span> signature</span></span> <span class="giallo-l"><span> ),</span></span> <span class="giallo-l"><span> &quot;Invalid signature&quot;</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _authorizationStates[authorizer][nonce] = true;</span></span> <span class="giallo-l"><span> emit AuthorizationUsed(authorizer, nonce);</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> _transfer(from, to, value);</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <ul> <li>For contract wallets, the security of <code>transferWithAuthorization</code>, <code>receiveWithAuthorization</code>, and <code>cancelAuthorization</code> rely on <code>ContractWallet.isValidSignature()</code> to ensure the signature bytes represent the desired execution from contract wallet owner(s). Contract wallet developers must exercise caution when implementing custom signature validation logic to ensure the security of their contracts.</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> 2024-01-12T00:00:00+00:00 2026-02-11T14:49:27+00:00 Danny Ryanhttps://github.com/djrtwo Dankrad Feisthttps://github.com/dankrad Francesco D'Amatohttps://github.com/fradamt Hsiao-Wei Wanghttps://github.com/hwwhww Alex Stokeshttps://github.com/ralexstokes https://wg-eips.ritovision.com/7594/

Introducing simple DAS utilizing gossip distribution and peer requests

<h2 id="abstract">Abstract</h2> <p>PeerDAS (Peer Data Availability Sampling) is a networking protocol that allows nodes to perform data availability sampling (DAS) to ensure that blob data has been made available while downloading only a subset of the data. PeerDAS utilizes gossip for distribution, discovery for finding peers of particular data custody, and peer requests for sampling.</p> <h2 id="motivation">Motivation</h2> <p>DAS is a method of scaling data availability beyond the levels of <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> by not requiring all nodes to download all data while still ensuring that all of the data has been made available.</p> <p>Providing additional data availability helps bring scale to Ethereum users in the context of layer 2 systems called "roll-ups" whose dominant bottleneck is layer 1 data availability.</p> <h2 id="specification">Specification</h2> <p>We extend the blobs introduced in EIP-4844 using a one-dimensional erasure coding extension. Each row consists of the blob data combined with its erasure code. It is subdivided into cells, which are the smallest units that can be authenticated with their respective blob's KZG commitments. Each column, associated with a specific gossip subnet, consists of the cells from all rows for a specific index. Each node is responsible for maintaining a deterministic set of column subnets and custodying their data as a function of their node ID.</p> <p>Nodes find and maintain a diverse peer set and sample columns from their peers to perform DAS every slot.</p> <p>A node can reconstruct the entire data matrix if it acquires at least 50% of all the columns. If a node has less than 50%, it can request the necessary columns from its peer nodes.</p> <p>Additionally, a limit of 6 blobs per transaction is introduced. Clients MUST enforce this limit when validating blob transactions at submission time, when received from the network, and during block production and processing.</p> <p>The detailed specifications are on <a rel="external" href="https://github.com/ethereum/consensus-specs/tree/9d377fd53d029536e57cfda1a4d2c700c59f86bf/specs/fulu/">ethereum/consensus-specs</a>.</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="networking">Networking</h3> <p>This EIP introduces cell KZG proofs, which are used to prove that a KZG commitment opens to a cell at the given index. This allows downloading only specific cells from a blob, while still ensuring data integrity with respect to the corresponding KZG commitment, and is therefore a key component of data availability sampling. However, computing the cell proofs for a blob is an expensive operation, which a block producer would have to repeat for many blobs. Since proof verification is much cheaper than proof computation, and the proof size is negligible compared to cell size, we instead require blob transaction senders to compute the proofs themselves and include them in the EIP-4844 transaction pool wrapper for blob transactions.</p> <p>To this end, during transaction gossip responses (<code>PooledTransactions</code>), the wrapper is modified to:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>rlp([tx_payload_body, wrapper_version, blobs, commitments, cell_proofs])</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>cell_proofs = [cell_proof_0, cell_proof_1, ...]</span></span></code></pre> <p>The <code>tx_payload_body</code>, <code>blobs</code> and <code>commitments</code> are as in EIP-4844, while the <code>proofs</code> field is replaced by <code>cell_proofs</code>, and a <code>wrapper_version</code> is added. These are defined as follows:</p> <ul> <li><code>wrapper_version</code> - one byte indicating which version of the wrapper is used. For the current version, it is set to <strong><code>1</code></strong>.</li> <li><code>cell_proofs</code> - list of cell proofs for all <code>blobs</code>, including the proofs for the extension indices, for a total of <code>CELLS_PER_EXT_BLOB</code> proofs per blob (<code>CELLS_PER_EXT_BLOB</code> is the number of cells for an extended blob, defined <a rel="external" href="https://github.com/ethereum/consensus-specs/tree/9d377fd53d029536e57cfda1a4d2c700c59f86bf/specs/fulu/polynomial-commitments-sampling.md#cells">in the consensus specs</a>)</li> </ul> <p>Note that, while <code>cell_proofs</code> contain the proofs for all cells, including the extension cells, the blobs themselves are sent without being extended (<code>CELLS_PER_EXT_BLOB / 2</code> cells per blob). This is to avoid sending redundant data, which can quickly be computed by the receiving node. In other words, <code>cell_proofs[i * CELLS_PER_EXT_BLOB + j]</code> is the proof for cell <code>j</code> of <code>compute_cells(blobs[i])</code>, where <code>compute_cells(blob)</code> outputs all cells of <code>blob</code>, including the extension cells.</p> <p>The node MUST validate <code>tx_payload_body</code> and verify the wrapped data against it. To do so, ensure that:</p> <ul> <li>There are an equal number of <code>tx_payload_body.blob_versioned_hashes</code>, <code>blobs</code> and <code>commitments</code>.</li> <li><code>cell_proofs</code> contains exactly <code>CELLS_PER_EXT_BLOB * len(blobs)</code> cell proofs</li> <li>The KZG <code>commitments</code> hash to the versioned hashes, i.e. <code>kzg_to_versioned_hash(commitments[i]) == tx_payload_body.blob_versioned_hashes[i]</code></li> <li>The KZG <code>commitments</code> match the corresponding <code>blobs</code> and <code>cell_proofs</code>. This requires computing the extension cells for all <code>blobs</code> (e.g. via <code>compute_cells</code>), and verifying all <code>cell_proofs</code>. (Note: all cell proofs can be batch verified at once, e.g. via <code>verify_cell_kzg_proof_batch</code>)</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="why-use-das-to-scale-the-da-layer">Why use DAS to scale the DA layer?</h3> <p>PeerDAS is a DAS scheme that requires nodes to only download a small constant fraction of the data to satisfy a local availability check. With the current parameters, this is 1/8 of the total data (i.e. blobs in a block), which can in the future be decreased to 1/16 or even 1/32 by reducing the size of samples (increasing the number of columns). In this way, PeerDAS allows for securely scaling the blob throughput of the network without compromising decentralization, i.e., without increasing node's bandwidth and storage requirements.</p> <h3 id="what-does-peer-sampling-provide">What does peer sampling provide?</h3> <p>PeerDAS takes the set of peers of a node on the network as a primitive to build a DAS scheme around. A focus on peers allows for redundancy in the mechanism (as a node generally has many peers, and peer count can also be cheaply increased) which both helps with theoretical security as detailed in the "Security Considerations" section, but also practical security of the implementation (e.g. if a single peer fails, a node can likely use another peer for the same sampling task).</p> <p>PeerDAS also has the nice property that any given node may voluntarily custody more of the data than the bare minimum which increases the performance of the mechanism. Alternative schemes do not readily support this "transparent" scaling property.</p> <h3 id="why-are-these-parameters-chosen">Why are these parameters chosen?</h3> <p>The parameters of PeerDAS given in the specs support network security while keeping node requirements sufficiently low. See the security argument below for further details.</p> <h3 id="why-do-validators-have-an-additional-custody-requirement-beyond-full-nodes">Why do validators have an additional custody requirement beyond full nodes?</h3> <p>Validators are assumed to have marginally higher requirements to participate on the network. PeerDAS introduces a custody requirement that scales with the validator count so that nodes with more resources can contribute to a more stable backbone that makes the global network more robust.</p> <h3 id="column-sampling-vs-row-sampling">Column sampling vs row sampling</h3> <p>PeerDAS defines a sample as a "column" which is a cross-section across <em>all</em> blobs, rather than a "row" which would be a full blob. The sampling scheme could be defined over rows but then any reconstruction strategy would need to work over "extension" blobs that do not a priori exist on the network. Reconstruction becomes much more tractable by working over columns as nodes can be assumed to have much more of the complete data by default (e.g. because most/all of the blobs are in the public mempool).</p> <p>Another benefit is that sampling over rows requires <em>column</em> extensions which would have to be done at the time of block construction, i.e. on the "critical path". Sampling over columns requires row extensions which can be done in advance (not on the critical path), and moreover proof computation can be outsourced to senders of blob transactions.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible with <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>.</p> <h2 id="test-cases">Test Cases</h2> <p>Refer to the consensus and execution spec tests for testing of this EIP.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The primary failure mode of a DAS scheme is a "data withholding" attack, where a block producer attempts to convince the network some data is available even when the block producer fails to provide the associated data. PeerDAS resolves withholding attacks by implementing a (pseudo)randomized sampling scheme that decreases the probability of a successful attack as the size of the network grows for a sublinear amount of data that must be downloaded.</p> <p>This intuition can be formalized as follows:</p> <p>Letting <code>n</code> be the total number of sampling nodes (i.e. the size of the network), <code>m</code> be the total number of samples possible (cf. <code>NUMBER_OF_CUSTODY_GROUPS</code> in the specs) and <code>k</code> be the minimum number of samples that a node must download (cf. <code>SAMPLES_PER_SLOT</code> in the specs), we have the following bound for the probability of convincing a fraction $\epsilon$ of the nodes that some data is available when it is withheld:</p> <p><img src="https://wg-eips.ritovision.com/7594/./assets/withholding-probability.svg" alt="withholding-probability" /></p> <p>The first term is the number of possible ways to choose a subset of $n\epsilon$ nodes whose sampling queries should be satisfied (i.e. the nodes to be tricked). The second term is the number of ways to choose a maximally large subset of samples to be made available to satisfy the sampling queries of the $n\epsilon$ nodes without allowing reconstruction of the full data. Finally, for any such choices, the third term is the probability of success, i.e. the probability that the sampling queries of all chosen $n\epsilon$ nodes are satisfied by the chosen subset up to the reconstruction threshold.</p> <p>For mainnet parameters given in the specs and assuming 10,000 nodes on the network, we can compute upper bounds of attack success for varying $\epsilon$:</p> <table><thead><tr><th style="text-align: center">$\epsilon$</th><th style="text-align: center">$n\epsilon$ (target nodes)</th><th style="text-align: center">Upper bound on $\mathbb{P}$</th></tr></thead><tbody> <tr><td style="text-align: center">0.01</td><td style="text-align: center">100</td><td style="text-align: center">$1$</td></tr> <tr><td style="text-align: center">0.02</td><td style="text-align: center">200</td><td style="text-align: center">$10^{-20.04}$</td></tr> <tr><td style="text-align: center">0.03</td><td style="text-align: center">300</td><td style="text-align: center">$10^{-101.55}$</td></tr> <tr><td style="text-align: center">0.04</td><td style="text-align: center">400</td><td style="text-align: center">$10^{-198.24}$</td></tr> <tr><td style="text-align: center">0.05</td><td style="text-align: center">500</td><td style="text-align: center">$10^{-306.34}$</td></tr> </tbody></table> <p>The table shows that the chances of a successful attack quickly drop to a negligible amount and so PeerDAS is considered secure to withholding 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> 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> 2024-01-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 Steven Pinedahttps://github.com/steven2308 Jan Turkhttps://github.com/ThunderDeliverer https://wg-eips.ritovision.com/7590/

Extension to allow NFTs to receive and transfer ERC-20 tokens.

<h2 id="abstract">Abstract</h2> <p>This proposal suggests an extension to <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> to enable easy exchange of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens. By enhancing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, it allows unique tokens to manage and trade <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> fungible tokens bundled in a single NFT. This is achieved by including methods to pull <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens into the NFT contract to a specific NFT, and transferring them out by the owner of such NFT. A transfer out nonce is included to prevent front-running issues.</p> <h2 id="motivation">Motivation</h2> <p>In the ever-evolving landscape of blockchain technology and decentralized ecosystems, interoperability between diverse token standards has become a paramount concern. By enhancing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> functionality, this proposal empowers non-fungible tokens (NFTs) to engage in complex transactions, facilitating the exchange of fungible tokens, unique assets, and multi-class assets within a single protocol.</p> <p>This ERC introduces new utilities in the following areas:</p> <ul> <li>Expanded use cases</li> <li>Facilitating composite transactions</li> <li>Market liquidity and value creation</li> </ul> <h3 id="expanded-use-cases">Expanded Use Cases</h3> <p>Enabling <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens to handle various token types opens the door to a wide array of innovative use cases. From gaming and digital collectibles to decentralized finance (DeFi) and supply chain management, this extension enhances the potential of NFTs by allowing them to participate in complex, multi-token transactions.</p> <h3 id="facilitating-composite-transactions">Facilitating Composite Transactions</h3> <p>With this extension, composite transactions involving both fungible and non-fungible assets become easier. This functionality is particularly valuable for applications requiring intricate transactions, such as gaming ecosystems where in-game assets may include a combination of fungible and unique tokens.</p> <h3 id="market-liquidity-and-value-creation">Market Liquidity and Value Creation</h3> <p>By allowing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens to hold and trade different types of tokens, it enhances liquidity for markets in all types of tokens.</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-storage z-type">interface</span><span class="z-entity z-name"> IERC7590</span><span class="z-comment"> /*</span><span class="z-comment">is IERC165, 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">@notice</span><span class="z-comment"> Used to notify listeners that the token received ERC-20 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"> erc20Contract</span><span class="z-comment"> The address of the ERC-20 smart 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"> toTokenId</span><span class="z-comment"> The ID of the token receiving the ERC-20 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"> from</span><span class="z-comment"> The address of the account from which the tokens are being transferred</span></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"> The number of ERC-20 tokens received</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"> ReceivedERC20</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"> erc20Contract</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"> toTokenId</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to notify the listeners that the ERC-20 tokens have been transferred.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> erc20Contract</span><span class="z-comment"> The address of the ERC-20 smart 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"> fromTokenId</span><span class="z-comment"> The ID of the token from which the ERC-20 tokens have been transferred</span></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 receiving the ERC-20 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"> The number of ERC-20 tokens transferred</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"> TransferredERC20</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"> erc20Contract</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"> fromTokenId</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 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"> Used to retrieve the given token&#39;s specific ERC-20 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"> erc20Contract</span><span class="z-comment"> The address of the ERC-20 smart 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"> tokenId</span><span class="z-comment"> The ID of the token being checked for ERC-20 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"> The</span><span class="z-comment"> amount of the specified ERC-20 tokens owned by a given 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"> balanceOfERC20</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> erc20Contract</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 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"> Transfer ERC-20 tokens from a specific token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The balance MUST be transferred from this smart contract.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST increase the transfer-out-nonce for the tokenId</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the `msg.sender` is not the owner of the NFT or approved to manage 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"> erc20Contract</span><span class="z-comment"> The address of the ERC-20 smart 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"> tokenId</span><span class="z-comment"> The ID of the token to transfer the ERC-20 tokens from</span></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"> The number of ERC-20 tokens 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"> data</span><span class="z-comment"> Additional data with no specified format, to allow for custom logic</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"> transferHeldERC20FromToken</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> erc20Contract</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-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-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</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"> Transfer ERC-20 tokens to a specific token.</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-20 smart contract must have approval for this contract to transfer the ERC-20 tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The balance MUST be transferred from the `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"> erc20Contract</span><span class="z-comment"> The address of the ERC-20 smart 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"> tokenId</span><span class="z-comment"> The ID of the token to transfer ERC-20 tokens 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"> amount</span><span class="z-comment"> The number of ERC-20 tokens 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"> data</span><span class="z-comment"> Additional data with no specified format, to allow for custom logic</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"> transferERC20ToToken</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> erc20Contract</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"> amount</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 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"> Nonce increased every time an ERC20 token is transferred out 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"> The ID of the token to check the nonce 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"> nonce of 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"> erc20TransferOutNonce</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> <h3 id="pull-mechanism">Pull Mechanism</h3> <p>We propose using a pull mechanism, where the contract transfers the token to itself, instead of receiving it via "safe transfer" for 2 reasons:</p> <ol> <li> <p>Customizability with Hooks. By initiating the process this way, smart contract developers have the flexibility to execute specific actions before and after transferring the tokens.</p> </li> <li> <p>Lack of transfer with callback: <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens lack a standardized transfer with callback method, such as the "safeTransfer" on <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, which means there is no reliable way to notify the receiver of a successful transfer, nor to know which is the destination token is.</p> </li> </ol> <p>This has the disadvantage of requiring approval of the token to be transferred before actually transferring it into an NFT.</p> <h3 id="granular-vs-generic">Granular vs Generic</h3> <p>We considered 2 ways of presenting the proposal:</p> <ol> <li>A granular approach where there is an independent interface for each type of held token.</li> <li>A universal token holder which could also hold and transfer <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>.</li> </ol> <p>An implementation of the granular version is slightly cheaper in gas, and if you're using just one or two types, it's smaller in contract size. The generic version is smaller and has single methods to send or receive, but it also adds some complexity by always requiring Id and amount on transfer methods. Id not being necessary for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and amount not being necessary for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>.</p> <p>We also considered that due to the existence of safe transfer methods on both <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>, and the commonly used interfaces of <code>IERC721Receiver</code> and <code>IERC1155Receiver</code>, there is not much need to declare an additional interface to manage such tokens. However, this is not the case for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, which does not include a method with a callback to notify the receiver of the transfer.</p> <p>For the aforementioned reasons, we decided to go with a granular approach.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests are included in <a href="https://wg-eips.ritovision.com/7590/./assets/test/erc7590.ts"><code>erc7590.ts</code></a>.</p> <p>To run them in terminal, you can use the following commands:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cd ../assets/eip-erc7590</span></span> <span class="giallo-l"><span>npm install</span></span> <span class="giallo-l"><span>npx hardhat test</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/7590/./assets/contracts/ERC7590Mock.sol"><code>ERC7590Mock.sol</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The same security considerations as with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> apply: hidden logic may be present in any of the functions, including burn, add resource, accept resource, and more.</p> <p>Caution is advised when dealing with non-audited contracts.</p> <p>Implementations MUST use the message sender as from parameter when they are transferring tokens into an NFT. Otherwise, since the current contract needs approval, it could potentially pull the external tokens into a different NFT.</p> <p>When transferring <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens in or out of an NFT, it could be the case that the amount transferred is not the same as the amount requested. This could happen if the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> contract has a fee on transfer. This could cause a bug on your Token Holder contract if you do not manage it properly. There are 2 ways to do it, both of which are valid:</p> <ol> <li>Use the <code>IERC20</code> interface to check the balance of the contract before and after the transfer, and revert if the balance is not the expected one, hence not supporting tokens with fees on transfer.</li> <li>Use the <code>IERC20</code> interface to check the balance of the contract before and after the transfer, and use the difference to calculate the amount of tokens that were actually transferred.</li> </ol> <p>To prevent a seller from front running the sale of an NFT holding <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens to transfer out such tokens before a sale is executed, marketplaces MUST beware of the <code>erc20TransferOutNonce</code> and revert if it has changed since listed.</p> <p><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens that are transferred directly to the NFT contract will be lost.</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-04T00:00:00+00:00 2026-02-11T14:48:25+00:00 sirawthttps://github.com/MASDXI ADISAKBOONMARKhttps://github.com/ADISAKBOONMARK parametpramehttps://github.com/parametprame Nacharoenhttps://github.com/najaroen https://wg-eips.ritovision.com/7858/

Non-fungible (NFT) and soulbound (SBT) tokens with expiration, supporting time-limited use cases.

<h2 id="abstract">Abstract</h2> <p>Introduces an extension for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> Non-Fungible Tokens (NFTs) and Soulbound Tokens (SBTs) that adds an expiration mechanism, allowing tokens to become invalid after a predefined period. This additional layer of functionality ensures that the expiration mechanism does not interfere with existing NFTs or SBTs, preserving transferability for NFTs and compatibility with current DApps such as NFT Marketplace. Expiration can be defined using either block height or timestamp, offering flexibility for various use cases.</p> <h2 id="motivation">Motivation</h2> <p>Before this EIP, NFTs and SBTs implemented expiration mechanisms via custom mappings. However, this approach presents challenges, such as: inconsistent integration with other smart contracts, and the custom <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> implementations might misbehave when used in NFT marketplaces. This EIP addresses these issues by providing a built-in expiration mechanism and interfaces that are compatible with existing infrastructure. It supports both per-token and epoch-based expiry, allowing developers to choose the appropriate expiry type for their use cases, including:</p> <ul> <li>Access and Authentication <ul> <li>Authentication for Identity and Access Management (IAM)</li> <li>Membership for Membership Management System (MMS)</li> <li>Ticket and Press for Meetings, Incentive Travel, Conventions, and Exhibitions (MICE) when using with <a href="https://wg-eips.ritovision.com/2135/">ERC-2135</a> or <a href="https://wg-eips.ritovision.com/7578/">ERC-7578</a>.</li> <li>Subscription-based access for digital platforms.</li> </ul> </li> <li>Digital Certifications, Contracts, Copyrights, Documents, Licenses, Policies, etc.</li> <li>Loyalty Program voucher or coupon</li> <li>Governance and Voting Rights</li> <li>Financial Product <ul> <li>Bonds, Loans, Hedge, and Options Contract</li> </ul> </li> <li>Rental <ul> <li>Real Estate Unit, Digital Access, DePIN, etc</li> </ul> </li> </ul> <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> <p>Compatible implementations MUST implement the <code>IERC7858</code> interface and MUST inherit from <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>'s interface. All functions defined in the interface MUST be present and all function behavior MUST meet the interface specification requirements.</p> <h3 id="interface">Interface</h3> <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-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-7858: Expirable NFTs and SBTs</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> unique/granular expiry</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 class="z-comment"> import &quot;./IERC721.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> The EIP-165 identifier of this interface is `0x3ebdfa31`.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7858</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-storage z-type"> enum</span><span class="z-entity z-name"> EXPIRY_TYPE</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> BLOCKS_BASED</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> block.number</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> TIME_BASED</span><span class="z-comment"> //</span><span class="z-comment"> block.timestamp</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"> Emitted when the expiration date of a token is set or updated.</span></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 of the token ERC721 `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"> startTime</span><span class="z-comment"> The start time of the token (block number or timestamp based on `expiryType`).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> endTime</span><span class="z-comment"> The end time of the token (block number or timestamp based on `expiryType`).</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"> TokenExpiryUpdated</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-storage z-type"> indexed</span><span class="z-variable"> startTime</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"> endTime</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"> Returns the type of the expiry.</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"> EXPIRY_TYPE</span><span class="z-comment"> Enum value indicating the unit of an expiry.</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"> expiryType</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-storage z-type">EXPIRY_TYPE</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"> Checks whether a specific token 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 identifier representing the `tokenId` (ERC721).</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"> True if the token is expired, 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"> isTokenExpired</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-comment"> return depends on the type `block.timestamp` or `block.number`</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> {ERC-5007} return in uint64 MAY not suitable for `block.number` based.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> startTime</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-storage z-type"> function</span><span class="z-entity z-name"> endTime</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><h3 id="behavior-specification">Behavior Specification</h3> <ul> <li> <p><code>balanceOf</code> that inherited from <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> MUST return all tokens even if expired; they still exist but are unusable due to the limitation of tracking expired token on-chain.</p> </li> <li> <p>For NFTs <code>transferFrom</code>, and <code>safeTransferFrom</code> MUST allow transferring tokens even if they expired. This ensures that expired tokens remain transferable and tradable, preserving compatibility with existing applications already deployed. However, expired tokens MUST be considered invalid and unusable in contracts that check for token validity.</p> </li> <li> <p><code>expiryType</code> MUST return the type of expiry used by the contract, which can be either <code>BLOCK</code> or <code>TIME</code>.</p> </li> <li> <p><code>isTokenExpired</code> is used for retrieving the status of the given <code>tokenId</code>; the function MUST return <code>true</code> if the token is expired and MUST revert if the <code>tokenId</code> does not exist. Implementations that use custom errors SHOULD revert with <code>ERC721NonexistentToken</code> following the relevant <a href="https://wg-eips.ritovision.com/6093/">ERC-6093</a> and implementations using Solidity version below <code>v0.8.4</code> or those preferring to use revert with string error SHOULD revert with <code>NonexistToken</code>. If the <code>tokenId</code> exists and is not expired, the function MUST return <code>false</code>.</p> </li> <li> <p><code>startTime</code> and <code>endTime</code> of <code>tokenId</code>, can be <code>block.number</code> or <code>block.timestamp</code> depending on <code>expiryType</code>. The <code>startTime</code> MUST be less than or equal to <code>endTime</code> and <code>startTime</code> SHOULD be strictly less than <code>endTime</code> except when both are set to <code>0</code>. A <code>startTime</code> and <code>endTime</code> of <code>0</code> indicates that the <code>tokenId</code> has no expiration. Tokens with a non-zero <code>startTime</code> and a zero <code>endTime</code> are also considered to have no expiration. If the <code>tokenId</code> does not exist, this function MUST revert in the same way as <code>isTokenExpired</code>.</p> </li> <li> <p>The interface ID for <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>'s <code>supportsInterface</code> for <code>IERC7858</code> is <code>0x3ebdfa31</code>, and for <code>IERC7858Epoch</code> it is <code>0xec7ffd66</code></p> </li> <li> <p><code>TokenExpiryUpdated</code> MUST be emitted when the token is minted or when its expiration details (<code>startTime</code> or <code>endTime</code>) are updated.</p> </li> </ul> <h3 id="extension-interface">Extension Interface</h3> <p><strong>Epochs</strong> represent a specific period or block range during which certain tokens are valid borrowing concepts from <a href="https://wg-eips.ritovision.com/7818/">ERC-7818</a>, tokens are grouped under an <code>epoch</code> and share the same <code>validityDuration</code>. For implementations that require epoch-based expiration management, the <code>IERC7858Epoch</code> extension interface MUST be implemented alongside the base <code>IERC7858</code> interface, and all functions and behaviors MUST meet both <code>IERC7858</code> and <code>IERC7858Epoch</code> interface specification requirements.</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"> &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-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-7858: Expirable NFTs and SBTs</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> epoch expiry extension</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 class="z-comment"> import &quot;./IERC7858.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> The EIP-165 identifier of this interface is `0xec7ffd66`.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7858Epoch</span><span class="z-comment"> /**</span><span class="z-comment"> is IERC7858 </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"> Retrieves the current epoch of 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"> uint256</span><span class="z-comment"> The current epoch of the token contract,</span></span> <span class="giallo-l"><span class="z-comment"> * often used for determining active/expired states.</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"> currentEpoch</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">@dev</span><span class="z-comment"> Retrieves the duration of a single epoch.</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 duration of a single epoch.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> The unit of the epoch length is determined by the `validityPeriodType` function.</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"> epochLength</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">@dev</span><span class="z-comment"> Checks whether a specific `epoch` 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"> epoch</span><span class="z-comment"> The `epoch` to check.</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"> True if the token is expired, false otherwise.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Implementing contracts &quot;MUST&quot; define and document the logic for determining expiration,</span></span> <span class="giallo-l"><span class="z-comment"> * typically by comparing the latest epoch with the given `epoch` value,</span></span> <span class="giallo-l"><span class="z-comment"> * based on the `EXPIRY_TYPE` measurement (e.g., block count or time duration).</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"> isEpochExpired</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> epoch</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"> Retrieves the balance of unexpired tokens owned by an 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 address 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"> uint256</span><span class="z-comment"> The amount of unexpired tokens owned by an account.</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"> unexpiredBalanceOf</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 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"> Retrieves the balance of a specific `epoch` owned by an 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"> epoch</span><span class="z-comment"> The `epoch for which the balance is checked.</span></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 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"> uint256</span><span class="z-comment"> The balance of the specified `epoch`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> &quot;MUST&quot; return 0 if the specified `epoch` is expired.</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"> unexpiredBalanceOfAtEpoch</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> epoch</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 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"> Retrieves the validity duration of each 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"> The validity duration of each token in `epoch` unit.</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"> validityDuration</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></span></code></pre><h3 id="extension-behavior-specification">Extension Behavior Specification</h3> <ul> <li><code>unexpiredBalanceOfAtEpoch</code> MUST return the count of usable (unexpired) tokens held by an account from the specified <code>epoch</code>. If the specified <code>epoch</code> is expired, this function MUST return <code>0</code>. For example, if epoch <code>5</code> has expired, calling <code>unexpiredBalanceOfAtEpoch(5, address)</code> returns <code>0</code> even if there were tokens previously held in that epoch.</li> <li><code>unexpiredBalanceOf</code> MUST return total count of usable (unexpired) tokens owned by the account.</li> <li><code>currentEpoch</code> MUST return the current <code>epoch</code> of the contract.</li> <li><code>epochLength</code> MUST return duration between <code>epoch</code> in blocks or time in seconds.</li> <li><code>validityDuration</code> MUST return the validity duration of tokens in terms of <code>epoch</code> counts.</li> <li><code>isEpochExpired</code> MUST return true if the given <code>epoch</code> is expired, otherwise <code>false</code>.</li> </ul> <h3 id="additional-potential-useful-function">Additional Potential Useful Function</h3> <p>These OPTIONAL functions provide additional functionality that developers MAY choose to implement based on their specific requirements and use cases.</p> <h4 id="base-default">Base (default)</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"> getRemainingDurationBeforeTokenExpired</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-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span></code></pre> <ul> <li><code>getRemainingDurationBeforeTokenExpired</code> returns the remaining time or blocks before the given <code>tokenId</code> is expired.</li> </ul> <h4 id="epoch-extension">Epoch (extension)</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"> getEpochBalance</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> epoch</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> <ul> <li><code>getEpochBalance</code> returns the amount of tokens stored in a given epoch, even if the epoch has expired.</li> </ul> <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"> getEpochInfo</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> epoch</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 class="z-support">uint256</span><span>)</span><span>;</span></span></code></pre> <ul> <li><code>getEpochInfo</code> returns both the start and end of the specified <code>epoch</code>.</li> </ul> <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"> getNearestExpiryOf</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> <ul> <li><code>getNearestExpiryOf</code> returns the list of <code>tokenId</code> closest to expiration, along with an estimated expiration block number or timestamp based on <code>epochType</code>.</li> </ul> <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"> getRemainingDurationBeforeEpochChange</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> <ul> <li><code>getRemainingDurationBeforeEpochChange</code> returns the remaining time or blocks before the epoch change happens, based on the <code>epochType</code>.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="first-do-no-harm">First, do no harm</h3> <p>Introducing expirability as an additional layer of functionality ensures it doesn’t interfere with existing use cases or applications. For non-SBT tokens, transferability remains intact, maintaining compatibility with current systems. Expired tokens are simply flagged as unusable during validity checks, treating expiration as an enhancement rather than a fundamental change.</p> <h3 id="expiry-types">Expiry Types</h3> <p>Defining expiration by either block height (<code>block.number</code>) or block timestamp (<code>block.timestamp</code>) offers flexibility for various use cases. Block-based expiration suits applications that rely on network activity and require precise consistency, while time-based expiration is ideal for networks with variable block intervals.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is fully compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, <a href="https://wg-eips.ritovision.com/5484/">ERC-5484</a> and other SBTs.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>You can find our reference implementation <a href="https://wg-eips.ritovision.com/7858/assets/README/">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="burn-and-re-mint">Burn and Re-Mint</h3> <p>Implementation should ensure that burning token and re-minting it with the same <code>tokenId</code> will not introduce an unauthorized renewal.</p> <h3 id="unauthorized-update">Unauthorized Update</h3> <p>Implementation should ensure that only authorized can update <code>startTime</code> and <code>endTime</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-01-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Gavin Fuhttps://github.com/gavfu Leo Wanghttps://github.com/wanglie1986 Bova Chenhttps://github.com/appoipp Aiden Xhttps://github.com/4ever9 https://wg-eips.ritovision.com/7588/

Attaching metadata to blobs carried by blob transactions

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a standard for attaching metadata to blobs carried by blob transactions, as outlined in <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>. The metadata is represented as a JSON object adhering to a predefined schema, and its string representation is placed in the data field of the blob transaction.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> defines a new type of transaction known as a “blob transaction.” These transactions contain a list of blobs along with their KZG commitments and proofs. Blob transactions serve as a mechanism for rollups to post their layer 2 transaction data to Ethereum layer 1.</p> <p>While rollups typically manage their own posted blob transactions, third-party solutions (such as Portal Network and blobscan) may also index all blobs ever posted to Ethereum, and provide querying services for blobs. By attaching metadata to blobs, such as information about the originator, a description, or content type, we can significantly enhance the visibility and auditability of these data structures.</p> <p>Furthermore, decentralized storage applications may utilize blob transactions to post user data to Ethereum, sync and store the blobs off-chain for future retrieval. The inclusion of metadata opens up possibilities for novel applications, including inscriptions and other creative use cases.</p> <h2 id="specification">Specification</h2> <h3 id="metadata-json-schema">Metadata JSON Schema</h3> <p>The metadata is represented as a JSON object adhering 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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Blobs 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">originator</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 originator of the carried blobs</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 contents of the blobs</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">content_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></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 MIME type of the blobs. The MIME type should be defined in RFC 2046 (https://www.rfc-editor.org/rfc/rfc2046)</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">extras</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">Dynamic extra information related to the blobs</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">blobs</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">Metadata of the i&#39;th blob. This is optional and overlays the upper level properties if provided</span><span class="z-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">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 content of the i&#39;th blob</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">content_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></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 MIME type of the i&#39;th blob. The MIME type should be defined in RFC 2046 (https://www.rfc-editor.org/rfc/rfc2046)</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">extras</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">Dynamic extra information related to the i&#39;th blob</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> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>For example, suppose Vitalik wants to send a blob transaction carrying two blobs explaining “data availability sampling.” He could include a paragraph of textual explanation in the first blob and an illustration image in the second blob. The corresponding metadata JSON object would 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">originator</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Vitalik Buterin</span><span class="z-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">An illustration of data availability sampling</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">blobs</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">content_type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">text/plain</span><span class="z-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">This blob contains a description text of the illustration.</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">content_type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">image/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">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">This blob contains the illustration image data in base64 format. It&#39;s a RFC 2397 (https://www.rfc-editor.org/rfc/rfc2397) data URL.</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> }</span></span></code></pre> <p>The complete blob transaction would include this metadata in the data field, along with other relevant fields:</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">blobVersionedHashes</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">0x...</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">0x...</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">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 11155111</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Supposing the blob transaction is posted to Sepolia</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">eip4844</span><span class="z-punctuation z-definition z-string">&quot;</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">0x0000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 28236</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">0x..</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"> String representation of the above metadata JSON object</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-constant"> 18</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxFeePerBlobGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1073677089</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1213388073</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxPriorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1165808679</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sidecars</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">blob</span><span class="z-support">&quot;</span><span>:</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><span class="z-support"> &quot;</span><span class="z-support">commitment</span><span class="z-support">&quot;</span><span>:</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><span class="z-support"> &quot;</span><span class="z-support">proof</span><span class="z-support">&quot;</span><span>:</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><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-support"> &quot;</span><span class="z-support">blob</span><span class="z-support">&quot;</span><span>:</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><span class="z-support"> &quot;</span><span class="z-support">commitment</span><span class="z-support">&quot;</span><span>:</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><span class="z-support"> &quot;</span><span class="z-support">proof</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="blob-transaction-envelope">Blob Transaction Envelope</h3> <p>The blob transaction's calldata (i.e., the data field) should be set to the string representation of the metadata JSON object, encoded in UTF-8.</p> <h2 id="rationale">Rationale</h2> <p>In the Ethereum ecosystem, various types of transactions exist, each serving different purposes. The usage of the data field within these transactions varies:</p> <ul> <li><strong>Regular Funds Transfer Transactions</strong>: In these transactions, the data field is typically not used, and users may optionally include arbitrary data.</li> <li><strong>Smart Contract Deployment Transactions</strong>: For deploying smart contracts. The data field holds the contract bytecode and any encoded arguments required by the constructor.</li> <li><strong>Smart Contract Function Call Transactions</strong>: When invoking smart contract functions, the data field contains the function call data, including the function signature and any necessary parameters.</li> </ul> <p>Blob transactions are specifically designed for posting blobs, and normally, the data field remains unused. This EIP proposes a novel approach: utilizing the data field to attach metadata to the carried blobs. By doing so, we can enhance the auditability and usability of blob transactions.</p> <p>However, it’s essential to note that there are scenarios where blob transactions may also need to call smart contract functions. Consider a decentralized storage application that employs a smart contract to track blob versioned hashes and metadata like MIME types. In such cases, users could submit a blob transaction containing blobs while simultaneously using the data field to invoke smart contract functions to store versioned hashes and MIME types of those blobs. It’s important to recognize that this EIP does not cover such specific use cases.</p> <h1 id="backwards-compatibility">Backwards Compatibility</h1> <p>This EIP is backward compatible with <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>, as it does not modify the structure or functionality of blob transactions, but only adds an optional metadata field to them.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP does not introduce any new security risks or vulnerabilities, as the metadata is only an informational field that does not affect the execution or validity of blob transactions. However, users and applications should be aware of the following potential issues:</p> <ul> <li> <p>The metadata is not verified or enforced by the consensus layer, and therefore it may not be accurate or trustworthy. Users and applications should not rely on the metadata for critical or sensitive operations, and should always verify the contents and sources of the blobs themselves.</p> </li> <li> <p>The metadata may contain malicious or harmful data, such as spam, phishing, malware, etc. Users and applications should not blindly trust or execute the metadata, and should always scan and sanitize the metadata before using it.</p> </li> <li> <p>The metadata may increase the gas cost of blob transactions, as more data is included in the data field. Users and applications should balance the benefits and costs of using the metadata, and should optimize the size and format of the metadata to reduce the gas cost.</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> 2023-12-31T00:00:00+00:00 2026-02-11T14:48:26+00:00 Samuel Gwlanold Edoumouhttps://github.com/Edoumou https://wg-eips.ritovision.com/7586/

Interest rate swaps derivative contracts

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a standardized framework for on-chain interest rate swaps. The proposed standard aims to facilitate the seamless exchange of fixed and floating interest rate cash flows between parties, providing a foundation for decentralized finance (DeFi) applications.</p> <h2 id="motivation">Motivation</h2> <p>Interest Rate Swapping (IRS) denotes a derivative contract wherein two parties mutually consent to exchange a series of forthcoming interest payments based on a specified notional amount. This financial instrument serves as a strategic tool for hedging against interest rate fluctuations. The mechanism entails the utilization of a benchmark index to facilitate the exchange between a variable interest rate and a fixed rate. Despite its widespread use, there is currently an absence of a standardized framework that enables the representation of IRS contracts on blockchain platforms.</p> <p>This proposal addresses this gap by establishing a consistent and transparent methodology for representing IRS contracts within the blockchain environment. By doing so, it would enhance the interoperability, security, and efficiency of interest rate swap transactions on distributed ledger technology.</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="example-flow">Example Flow</h3> <p><img src="https://wg-eips.ritovision.com/7586/./assets/irs.jpeg" alt="alt text" title="IRS diagram" /></p> <p>Every contract compliant with this ERC MUST implement the following interface. The contract MUST inherit from <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> to tokenize the swap cash flows.</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-comment">* </span><span class="z-storage z-type">@title</span><span class="z-comment"> ERC-7586 Interest Rate Swaps</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"> IERC7586</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 class="z-comment"> events</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"> MUST be emitted when interest rates are swapped</span></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"> the interest difference to be transferred</span></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 recipient account to send the interest difference to. MUST be either the `payer` or the `receiver`</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"> Swap</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> _amount</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _account</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"> MUST be emitted when the swap contract is terminated</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _payer</span><span class="z-comment"> the swap payer</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _receiver</span><span class="z-comment"> the swap receiver</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"> TerminateSwap</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _payer</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _receiver</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> functions</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 the IRS `payer` account address. The party who agreed to pay fixed 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"> fixedRatePayer</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"> Returns the IRS `receiver` account address. The party who agreed to pay floating 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"> floatingRatePayer</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"> Returns the number of decimals the swap rate and spread use - e.g. `4` means to divide the rates by `10000`</span></span> <span class="giallo-l"><span class="z-comment"> * To express the interest rates in basis points unit, the decimal MUST be equal to `2`. This means rates MUST be divided by `100`</span></span> <span class="giallo-l"><span class="z-comment"> * 1 basis point = 0.01% = 0.0001</span></span> <span class="giallo-l"><span class="z-comment"> * ex: if interest rate = 2.5%, then swapRate() =&gt; 250 `basis points`</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"> ratesDecimals</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns the fixed interest rate. All rates MUST be multiplied by 10^(ratesDecimals)</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"> swapRate</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"> Returns the floating rate spread, i.e. the fixed part of the floating interest rate. All rates MUST be multiplied by 10^(ratesDecimals)</span></span> <span class="giallo-l"><span class="z-comment"> * floatingRate = benchmark + spread</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"> spread</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"> Returns the day count basis</span></span> <span class="giallo-l"><span class="z-comment"> * For example, 0 can denote actual/actual, 1 can denote actual/360, and so on</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"> dayCountBasis</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns the contract address of the currency for which the notional amount is denominated (Example: USDC contract address).</span></span> <span class="giallo-l"><span class="z-comment"> * Returns the zero address if the notional is expressed in FIAT currency like USD</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"> notionalCurrency</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"> Returns an array of acceptable contract address of the assets to be transferred when swapping IRS</span></span> <span class="giallo-l"><span class="z-comment"> * The two counterparties may wish to get the payment in different currencies.</span></span> <span class="giallo-l"><span class="z-comment"> * Ex: if the payer wants to receive the payment in USDC and the receiver in DAI, then the function should return [USDC, DAI] or [DAI, USDC]</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"> paymentAssets</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns the notional amount in unit of asset to be transferred when swapping IRS. This amount serves as the basis for calculating the interest payments, and may not be exchanged</span></span> <span class="giallo-l"><span class="z-comment"> * Example: If the two parties aggreed to swap interest rates in USDC, then the notional amount may be equal to 1,000,000 USDC </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"> notionalAmount</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"> Returns the number of times payments must be realized in 1 year</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"> paymentFrequency</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"> Returns an array of specific dates on which the fix interest payments are exchanged. Each date MUST be a Unix timestamp like the one returned by block.timestamp</span></span> <span class="giallo-l"><span class="z-comment"> * The length of the array returned by this function MUST equal the total number of swaps that should be realized</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * OPTIONAL</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"> fixPaymentDates</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 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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns an array of specific dates on which the floating interest payments are exchanged. Each date MUST be a Unix timestamp like the one returned by block.timestamp</span></span> <span class="giallo-l"><span class="z-comment"> * The length of the array returned by this function MUST equal the total number of swaps that should be realized</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * OPTIONAL</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"> floatingPaymentDates</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 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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns the starting date of the swap contract. This is a Unix Timestamp like the one returned by block.timestamp</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"> startingDate</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"> Returns the maturity date of the swap contract. This is a Unix Timestamp like the one returned by block.timestamp</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"> maturityDate</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"> Returns the benchmark (the reference rate). All rates MUST be multiplied by 10^(ratesDecimals)</span></span> <span class="giallo-l"><span class="z-comment"> * Example: value of one the following rates: CF BIRC, EURIBOR, HIBOR, SHIBOR, SOFR, SONIA, TONAR, etc.</span></span> <span class="giallo-l"><span class="z-comment"> * Or set manually</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"> benchmark</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"> Returns the oracle contract address for acceptable reference rates (benchmark), or the zero address when the two parties agreed to set the benchmark manually.</span></span> <span class="giallo-l"><span class="z-comment"> * This contract SHOULD be used to fetch real time benchmark rate</span></span> <span class="giallo-l"><span class="z-comment"> * Example: Contract address for `CF BIRC`</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * OPTIONAL. The two parties MAY agree to set the benchmark manually</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"> oracleContractsForBenchmark</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"> Makes swap calculation and transfers the payment to counterparties</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"> swap</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 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"> Terminates the swap contract before its maturity date. MUST be called by either the `payer`or the `receiver`.</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"> terminateSwap</span><span>(</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="tokenization-of-swap-cash-flows">Tokenization of Swap Cash Flows</h3> <p>The interest payments associated with the IRS MUST be tokenized by issuing digital <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens to the respective parties according to the terms of the swap. Each token SHOULD represent a specific interest payment. Every time a swap happens (the <code>swap</code> function is called), one token MUST be burned from each party.</p> <h2 id="rationale">Rationale</h2> <p>This standard allows parties involved in the IRS contract to define essential parameters such as notional amount, interest rates, payment frequency, and payment dates. This flexibility accommodates a diverse range of financial agreements, catering to the unique needs of different participants.</p> <p>To accommodate a wide array of use cases, the standard introduces optional features such as payment dates and manual benchmark setting. This allows parties to tailor the contract to specific requirements, while maintaining a core set of functions for essential functionality.</p> <p>To ensure real-time and accurate benchmark rates, the standard integrates with oracles. Parties have the option to use oracles for fetching benchmark rates, enhancing the reliability and accuracy of interest rate calculations.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is backward compatible with ERC-20.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The complete reference implementation can be found <a href="https://wg-eips.ritovision.com/7586/./assets/ERC7586.sol">here</a>.</p> <p>This reference implementation serves as a foundation for the implementation of more advanced types of swaps.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Security considerations of various types must be thoroughly evaluated</p> <ul> <li>Interest Rate Risk: This pertains to the potential impact of fluctuations in interest rates.</li> <li>Credit Risk: There exists the possibility that one or both parties may default on their respective responsibilities.</li> <li>ERC-20 Risks: All security aspects outlined in the ERC-20 standard must be taken into account.</li> </ul> <p>Both parties must acknowledge their awareness of these security risks before proceeding with the implementation of the 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> 2023-12-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ernani São Thiagohttps://github.com/ernanirst Daniel Limahttps://github.com/karacurt https://wg-eips.ritovision.com/7589/

Role Management for Semi-Fungible Tokens (SFTs). Enables accounts to share the utility of SFTs via expirable role assignments.

<h2 id="abstract">Abstract</h2> <p>This standard introduces role management for SFTs (Semi-Fungible Tokens). Each role assignment is granted to a single user (grantee) and expires automatically. Roles are defined as <code>bytes32</code> and feature a custom <code>_data</code> field of arbitrary size to allow customization.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> has significantly contributed to the tokenization capabilities of Ethereum by enabling developers to create fungible and non-fungible tokens with a single contract. While <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> excels at tracking ownership, it focuses solely on token balances, overlooking the nuanced aspects of how these tokens can be utilized.</p> <p>An essential aspect of token utility is access control, which determines who has permission to spend or use these tokens. In some cases, the owner has complete control over its balance. Nevertheless, in many others, the utility can be delegated (or granted) to other users, allowing for more complex use cases to be implemented.</p> <p>One example is in gaming, in-game assets can be issued with a single <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> contract and rented out via a secure role management interface.</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> <p>Compliant contracts 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-storage z-type"> @title</span><span class="z-comment"> ERC-7589 Semi-Fungible Token Roles</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-7589</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 0xc4c8a71d.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7589</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC165 </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-comment"> Events *</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"> Emitted when tokens are committed (deposited or frozen).</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _grantor</span><span class="z-comment"> The owner of the SFTs.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _commitmentId</span><span class="z-comment"> The identifier of the commitment created.</span></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"> The 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"> The token identifier.</span></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"> The token amount.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokensCommitted</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"> _grantor</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"> _commitmentId</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"> _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 class="z-storage z-type"> @notice</span><span class="z-comment"> Emitted when a role is granted.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _commitmentId</span><span class="z-comment"> The commitment identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _role</span><span class="z-comment"> The role identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _grantee</span><span class="z-comment"> The recipient the role.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _expirationDate</span><span class="z-comment"> The expiration date of the role.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _revocable</span><span class="z-comment"> Whether the role is revocable or not.</span></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"> Any additional data about the role.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RoleGranted</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"> _commitmentId</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"> _role</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"> _grantee</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> _expirationDate</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> _revocable</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"> @notice</span><span class="z-comment"> Emitted when a role is 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"> _commitmentId</span><span class="z-comment"> The commitment identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _role</span><span class="z-comment"> The role identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _grantee</span><span class="z-comment"> The recipient of the role revocation.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RoleRevoked</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _commitmentId</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _role</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _grantee</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"> Emitted when a user releases tokens from a commitment.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _commitmentId</span><span class="z-comment"> The commitment identifier.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokensReleased</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _commitmentId</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"> Emitted when a user is approved to manage roles on behalf of another 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"> _tokenAddress</span><span class="z-comment"> The 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"> _operator</span><span class="z-comment"> The user approved to grant and revoke roles.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _isApproved</span><span class="z-comment"> The approval status.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RoleApprovalForAll</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _tokenAddress</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"> _isApproved</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> External Functions *</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"> Commits tokens (deposits on a contract or freezes 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"> _grantor</span><span class="z-comment"> The owner of the SFTs.</span></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"> The 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"> The token identifier.</span></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"> The token amount.</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"> commitmentId_</span><span class="z-comment"> The unique identifier of the commitment created.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> commitTokens</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _grantor</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _tokenAddress</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"> _tokenAmount</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">uint256</span><span class="z-variable"> commitmentId_</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"> Grants a role to `_grantee`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _commitmentId</span><span class="z-comment"> The identifier of the commitment.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _role</span><span class="z-comment"> The role identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _grantee</span><span class="z-comment"> The recipient the role.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _expirationDate</span><span class="z-comment"> The expiration date of the role.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _revocable</span><span class="z-comment"> Whether the role is revocable or not.</span></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"> Any additional data about the role.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> grantRole</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _commitmentId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _role</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _grantee</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable z-parameter z-function"> _expirationDate</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _revocable</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 z-parameter z-function"> _data</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-storage z-type"> @notice</span><span class="z-comment"> Revokes a role.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _commitmentId</span><span class="z-comment"> The commitment identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _role</span><span class="z-comment"> The role identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _grantee</span><span class="z-comment"> The recipient of the role revocation.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeRole</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _commitmentId</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _role</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _grantee</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"> Releases tokens back to grantor.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _commitmentId</span><span class="z-comment"> The commitment identifier.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> releaseTokens</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _commitmentId</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"> Approves operator to grant and revoke roles on behalf of another 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"> _tokenAddress</span><span class="z-comment"> The 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"> _operator</span><span class="z-comment"> The user approved to grant and revoke roles.</span></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 approval status.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setRoleApprovalForAll</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"> 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 class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> View Functions *</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"> Returns the owner of the commitment (grantor).</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _commitmentId</span><span class="z-comment"> The commitment identifier.</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"> grantor_</span><span class="z-comment"> The commitment owner.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> grantorOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _commitmentId</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"> grantor_</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 address of the token committed.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _commitmentId</span><span class="z-comment"> The commitment identifier.</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"> tokenAddress_</span><span class="z-comment"> The token address.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenAddressOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _commitmentId</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"> tokenAddress_</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 identifier of the token committed.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _commitmentId</span><span class="z-comment"> The commitment identifier.</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 token identifier.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenIdOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _commitmentId</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"> 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"> Returns the amount of tokens committed.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _commitmentId</span><span class="z-comment"> The commitment identifier.</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"> tokenAmount_</span><span class="z-comment"> The token amount.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenAmountOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _commitmentId</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"> tokenAmount_</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 custom data of a role assignment.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _commitmentId</span><span class="z-comment"> The commitment identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _role</span><span class="z-comment"> The role identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _grantee</span><span class="z-comment"> The recipient the role.</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"> data_</span><span class="z-comment"> The custom data.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> roleData</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _commitmentId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _role</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _grantee</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">bytes</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the expiration date of a role assignment.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _commitmentId</span><span class="z-comment"> The commitment identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _role</span><span class="z-comment"> The role identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _grantee</span><span class="z-comment"> The recipient the role.</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"> expirationDate_</span><span class="z-comment"> The expiration date.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> roleExpirationDate</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _commitmentId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _role</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _grantee</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">uint64</span><span class="z-variable"> expirationDate_</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 expiration date of a role assignment.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _commitmentId</span><span class="z-comment"> The commitment identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _role</span><span class="z-comment"> The role identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _grantee</span><span class="z-comment"> The recipient the role.</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"> revocable_</span><span class="z-comment"> Whether the role is revocable or not.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isRoleRevocable</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _commitmentId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _role</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _grantee</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 class="z-variable"> revocable_</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"> Checks if the grantor approved the operator for all SFTs.</span></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"> The 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"> _grantor</span><span class="z-comment"> The user that approved the 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"> The user that can grant and revoke roles.</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"> isApproved_</span><span class="z-comment"> Whether the operator is approved or not.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isRoleApprovedForAll</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _tokenAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _grantor</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 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 class="z-variable"> isApproved_</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="single-transaction-extension">Single Transaction Extension</h3> <p>Granting roles is a two-step process that requires two transactions. The first is to commit tokens, and the second is to grant the role. This extension allows users to commit tokens and grant a role in one transaction, which is desirable for some use cases.</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-7589 Semi-Fungible Token Roles, optional single transaction 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-7589</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 0x5c3d7d74.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ICommitTokensAndGrantRoleExtension</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC7589 </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"> Commits tokens and grant role in a single 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"> _grantor</span><span class="z-comment"> The owner of the SFTs.</span></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"> The 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"> The token identifier.</span></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"> The token 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"> _role</span><span class="z-comment"> The role identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _grantee</span><span class="z-comment"> The recipient the role.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _expirationDate</span><span class="z-comment"> The expiration date of the role.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _revocable</span><span class="z-comment"> Whether the role is revocable or not.</span></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"> Any additional data about the role.</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"> commitmentId_</span><span class="z-comment"> The identifier of the commitment created.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> commitTokensAndGrantRole</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _grantor</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _tokenAddress</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"> _tokenAmount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _role</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _grantee</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable z-parameter z-function"> _expirationDate</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _revocable</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 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">uint256</span><span class="z-variable"> commitmentId_</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="role-balance-extension">Role Balance Extension</h3> <p>The core interface allows for querying a token commitment's balance but not for a specific user's balance. To determine the total amount of tokens granted to a user, the implementation needs to sum up all the roles granted to that user while filtering out any expired roles.</p> <p>This function was included in an optional extension because it's not always necessary and will likely make the implementation much more complex (increasing smart contract risk).</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-7589 Semi-Fungible Token Roles, optional role balance 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-7589</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 0x2f35b73f.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IRoleBalanceOfExtension</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC7589 </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"> Returns the sum of all tokenAmounts granted to the grantee for the given role.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _role</span><span class="z-comment"> The role identifier.</span></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"> The 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"> The token identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _grantee</span><span class="z-comment"> The user for which the balance is 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"> balance_</span><span class="z-comment"> The balance of the grantee for the given role.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> roleBalanceOf</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _role</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _tokenAddress</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"> _grantee</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">uint256</span><span class="z-variable"> balance_</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="metadata-extension">Metadata Extension</h3> <p>The Roles Metadata extension extends the traditional JSON-based metadata schema of SFTs. Therefore, DApps supporting this feature MUST also implement the metadata extension of <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>. This JSON extension is <strong>optional</strong> and allows developers to provide additional information on roles.</p> <p>Updated JSON Schema:</p> <pre class="giallo z-code"><code data-lang="json"><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"> Existing ERC-1155 Metadata *</span><span class="z-punctuation z-definition z-comment">*/</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">Token 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 token 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">decimals</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">The number of decimal places that the token amount should display - e.g. 18, means to divide the token amount by 1000000000000000000 to get its user representation.</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 token 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 token 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">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">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">Arbitrary properties. Values may be strings, numbers, object or arrays.</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-punctuation z-definition z-comment"> /**</span><span class="z-comment"> Additional fields for ERC-7589 *</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">roles</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">id</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">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">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 role</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></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">Human-readable name of the role</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 role</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">inputs</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">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">Human-readable name of the argument</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></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">Solidity type, e.g., uint256 or 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> }</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The following code snipped is an example of the additional fields described above:</p> <pre class="giallo z-code"><code data-lang="json"><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"> Existing ERC-1155 Metadata *</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"></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:</span><span class="z-constant">\/</span><span class="z-constant">\/</span><span class="z-string">s3.amazonaws.com</span><span class="z-constant">\/</span><span class="z-string">your-bucket</span><span class="z-constant">\/</span><span class="z-string">images</span><span class="z-constant">\/</span><span class="z-string">{id}.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">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">simple_property</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">example 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">rich_property</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">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">value</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">123</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">display_value</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">123 Example 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">class</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">emphasis</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">css</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">color</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#ffffff</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">font-weight</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">bold</span><span class="z-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-decoration</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">underline</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">array_property</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">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">value</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-constant">1</span><span>,</span><span class="z-constant">2</span><span>,</span><span class="z-constant">3</span><span>,</span><span class="z-constant">4</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">class</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">emphasis</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-punctuation z-definition z-comment"> /**</span><span class="z-comment"> Additional fields for ERC-7589 *</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">roles</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> keccak256(&quot;Player(uint256)&quot;)</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">0x70d2dab8c6ff873dc0b941220825d9271fdad6fdb936f6567ffde77d05491cef</span><span class="z-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">Player</span><span class="z-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 user allowed to use this item in-game.</span><span class="z-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">ProfitShare</span><span class="z-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 class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The properties of the <code>roles</code> array are SUGGESTED, and developers should add any other relevant information for their use case (e.g., an image representing the role).</p> <p>It's also important to highlight the significance of the <code>inputs</code> property. This field describes the parameters that should be encoded and passed to the <code>grantRole</code> function, and can include the properties <code>type</code> and <code>components</code> to represent the format of the data. It's RECOMMENDED to use the properties <code>type</code> and <code>components</code> as defined on the Solidity ABI Specification.</p> <h3 id="caveats">Caveats</h3> <ul> <li>Compliant contracts MUST implement the <code>IERC7589</code> interface.</li> <li>Every role is represented by a <code>bytes32</code> identifier. It's RECOMMENDED to use the keccak256 hash of the role name and its arguments (if any) as the identifier. E.g., <code>keccak256("Player(uint256)")</code>.</li> <li>The <code>commitTokens</code> function MUST revert if the <code>_tokenAmount</code> is zero or the <code>msg.sender</code> was not approved by the <code>_grantor</code>. It MAY be implemented as public or external.</li> <li>The <code>grantRole</code> function MUST revert if the <code>_expirationDate</code> is in the past or if the <code>msg.sender</code> is not approved to grant roles on behalf of the grantor. It MAY be implemented as public or external, and it is RECOMMENDED using <code>type(uint64).max</code> for a permanent roles.</li> <li>The <code>revokeRole</code> function SHOULD always allow the grantee to revoke roles and MAY be implemented as public or external, and MUST revert if: <ul> <li>The role assignment is not found (no role was granted).</li> <li>The <code>msg.sender</code> was not approved by the grantor or the grantee.</li> <li>The <code>msg.sender</code> is the grantor or was approved by the grantor, but the role is not revocable or expired.</li> </ul> </li> <li>The <code>releaseTokens</code> function MAY be implemented as public or external and MUST revert if: <ul> <li>The commitment is not found (no tokens were committed).</li> <li>The <code>msg.sender</code> is not and was not approved by the grantor.</li> <li>The commitment has at least one non-revocable role that didn't expire.</li> </ul> </li> <li>The <code>setRoleApprovalForAll</code> function MAY be implemented as public or external.</li> <li>The <code>grantorOf</code> function MAY be implemented as pure or view and MUST return the owner of the committed tokens.</li> <li>The <code>tokenAddressOf</code> function MAY be implemented as pure or view and MUST return the address of the committed tokens.</li> <li>The <code>tokenIdOf</code> function MAY be implemented as pure or view and MUST return the identifier of the committed tokens.</li> <li>The <code>tokenAmountOf</code> function MAY be implemented as pure or view and MUST return the token amount committed.</li> <li>The <code>roleData</code> function MAY be implemented as pure or view and MUST return the custom data of the role assignment.</li> <li>The <code>roleExpirationDate</code> function MAY be implemented as pure or view and MUST return the expiration date of the role assignment.</li> <li>The <code>isRoleRevocable</code> function MAY be implemented as pure or view and MUST return whether the grantor can end the role assignment before its expiration date.</li> <li>The <code>isRoleApprovedForAll</code> function MAY be implemented as pure or view and MUST return whether the <code>_operator</code> is allowed to grant and revoke roles on behalf of the <code>_grantor</code>.</li> </ul> <blockquote> <p>Please note that "approval" refers to allowing users to commit tokens and grant/revoke roles on one's behalf. An approved user either received the role approval or is the target user. Role approvals are not to be confused with <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> approvals. More information can be found in the <a href="https://wg-eips.ritovision.com/7589/#role-approvals">Role Approvals</a> section.</p> </blockquote> <h2 id="rationale">Rationale</h2> <p>The concept of "token commitments" as an abstraction serves as a powerful tool for users looking to delegate the control of their SFTs. A token commitment represents either a frozen balance or tokens deposited into a contract, offering a standardized and secure way for SFT owners to delegate the use of their assets. Through <a href="https://wg-eips.ritovision.com/7589/">ERC-7589</a>, users gain a versatile mechanism to abstract the complexities of secure delegation, enhancing the utility and interoperability of semi-fungible tokens.</p> <p><a href="https://wg-eips.ritovision.com/7589/">ERC-7589</a> IS NOT an extension of <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>. The main reason behind this decision is to keep the standard agnostic of any implementation. This approach enables the standard to be implemented externally or on the same contract as the SFT and allows dApps to use roles with immutable SFTs.</p> <h3 id="role-approvals">Role Approvals</h3> <p>Like <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>, <a href="https://wg-eips.ritovision.com/7589/">ERC-7589</a> allows users to approve operators to grant and revoke roles on their behalf. This feature is crucial for interoperability, as it enables third-party applications to manage user roles without custody-level approvals. Role approvals are part of the core interface, and compliant contracts must implement the <code>setRoleApprovalForAll</code> and <code>isRoleApprovedForAll</code> functions.</p> <h3 id="automatic-expiration">Automatic Expiration</h3> <p>Automatic expiration is implemented to save users gas. To end a role assignment, instead of requiring users always to call <code>revokeRole</code>, applications should call the <code>roleExpirationDate</code> and compare it to the current timestamp to check if the role is still valid.</p> <p>In the context of <a href="https://wg-eips.ritovision.com/7589/">ERC-7589</a>, dates are represented as <code>uint64</code>. The maximum UNIX timestamp represented by a <code>uint64</code> is about the year 584 billion, which should be enough to be considered "permanent". For this reason, using <code>type(uint64).max</code> in an assignment represents that it never expires.</p> <h3 id="revocable-roles">Revocable Roles</h3> <p>In certain scenarios, the grantor might need to revoke a role before its expiration. While in others, the grantee requires assurance that the role can't be prematurely revoked (e.g. when the grantee pays tokens to utilize them). The <code>_revocable</code> parameter was included in the <code>grantRole</code> function for this exact reason, and it specifies whether the grantor can revoke the role prior to the expiration date. Regardless of the <code>_revocable</code> value, the grantee will always be able to revoke roles, allowing recipients to eliminate undesirable assignments.</p> <h3 id="custom-data">Custom Data</h3> <p>The <code>grantRole</code> function's <code>_data</code> parameter is critical for the standardization of this EIP. SFTs have different use cases, and it's impractical to attempt to cover all of them on a solidity-level interface. Therefore, a generic parameter of type <code>bytes</code> was incorporated, allowing users to pass any custom information when granting a role.</p> <p>For example, it's common for web3 games to introduce a profit-share when delegating NFTs to players, which is represented by a <code>uint256</code>. Using <a href="https://wg-eips.ritovision.com/7589/">ERC-7589</a>, one could simply encode the <code>uint256</code> as bytes and pass it to the<code>grantRole</code> function. Data validation can happen on-chain or off-chain, and other contracts can query this information using the <code>roleData</code> function.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Many SFTs are deployed as immutable contracts, which imposes the following challenge: How can one enable role management for SFTs that can't be modified? This proposal solves this problem by requiring the <code>tokenAddress</code> parameter when committing tokens. This requirement ensures that dApps can either implement <a href="https://wg-eips.ritovision.com/7589/">ERC-7589</a> inside the SFT contract or use a standalone external contract as the authoritative source for the roles of immutable SFTs.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/7589/./assets/ERC7589.sol"><code>ERC7589.sol</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Developers integrating with Semi-Fungible Token Roles should consider the points below on their implementations:</p> <ul> <li>Ensure proper access control is in place to prevent unauthorized role assignments or revocations. This is especially important in <code>commitTokens</code> and <code>releaseTokens</code>, as they might freeze or transfer balances.</li> <li>Consider potential attack vectors such as reentrancy and ensure appropriate safeguards are in place.</li> <li>Always check the expiration date before allowing users to utilize a role assignment.</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> 2023-12-27T00:00:00+00:00 2026-02-11T14:48:26+00:00 Liu Zhiconghttps://github.com/waterflier William Entrikenhttps://github.com/fulldecent Wei Qiushihttps://github.com/weiqiushi Si Changjunhttps://github.com/photosssa https://wg-eips.ritovision.com/7585/

A design for minimum value selection Storage Proofs on Merkle trees

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a design for "minimum value selection" storage proofs on Merkle trees. The design consists of two main components:</p> <ol> <li>A hashing algorithm termed MixHash, aimed to replace the commonly used Keccak256 and SHA256 algorithms.</li> <li>Public data storage proofs. This enables anyone to present a proof to a public network, verifying their possession of a copy of specific public data marked by MixHash.</li> </ol> <p>Additionally, the proposal discusses the practical implementation of this design in various scenarios and suggests some improvements to the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> standards.</p> <h2 id="motivation">Motivation</h2> <p>The <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> standards are widely used in the NFT fields. However, the current standards do not provide a mechanism for verifying the existence of public data. This is a major obstacle to the development of many applications, such as decentralized data markets, decentralized data storage, and decentralized data oracles.</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="mixhash">MixHash</h3> <p>MixHash is a Merkle tree root hash value that incorporates data length information. Its structure is as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> +-----------256 bits MixHash-----------+</span></span> <span class="giallo-l"><span>High |-2-|----62----|----------192----------| Low</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>2 bits: Hash algorithm selection, where 0b00 represents SHA256, and 0b10 represents Keccak256. (0b01, 0b11 are reserved)</span></span> <span class="giallo-l"><span>62 bits: File size. Hence, MixHash can support file sizes up to 2^62-1.</span></span> <span class="giallo-l"><span>192 bits: The lower 192 bits of the Merkel root node value constructed by the designated hash algorithm.</span></span> <span class="giallo-l"></span></code></pre> <p>Given a file, we can construct a MixHash through the following defined steps:</p> <ol> <li> <p>File MUST Split into 1KB chunks. MUST Pad zeros to the end of the last chunk if needed.</p> </li> <li> <p>Calculate the hash for each chunk and the low 128bits is the Merkle Tree leaf value.</p> </li> <li> <p>Construct a Merkle tree , root node hash algorithm is 256bits, other node use low 128bits of the 256bits hash result.</p> </li> <li> <p>Return the combination of hash type, the file size, and the low 192 bits of the Merkle tree root node hash.</p> </li> </ol> <p>MixHash retains a length of 256 bits, so replacing the widely used Keccak256 and SHA256 with MixHash incurs no additional cost. Although including the file length in the upper 62 bits compromises security to some extent, the 192-bit hash length is already sufficient for defending against hash collisions.</p> <p>The following is the pseudo code for generating Mixhash:</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"> generateMixHash</span><span>(</span><span class="z-variable z-parameter z-function">blockHeight</span><span>,</span><span class="z-variable z-parameter z-function">hashType</span><span>,</span><span class="z-variable z-parameter z-function">file</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> chunk_hash_array</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> chunk</span><span class="z-keyword"> in</span><span class="z-variable"> file</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>chunk</span><span>)</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 1024</span><span>:</span></span> <span class="giallo-l"><span> chunk</span><span class="z-keyword"> =</span><span> chunk</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> (</span><span class="z-constant">1024</span><span class="z-keyword">-</span><span class="z-support">len</span><span>(</span><span>chunk</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> chunk_hash_array</span><span>.</span><span>append</span><span>(</span><span>getChunkHash</span><span>(</span><span>chunk</span><span>,</span><span>hashType</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> merkle_tree_root</span><span class="z-keyword"> =</span><span> getMerkleTreeRoot</span><span>(</span><span>chunk_hash_array</span><span>,</span><span>hash_type</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> mix_hash</span><span>(</span><span>hash_type</span><span>,</span><span class="z-support"> len</span><span>(</span><span class="z-variable">file</span><span>)</span><span>,</span><span> merkle_tree_root</span><span>)</span></span></code></pre><h3 id="public-data-storage-proofs">Public Data Storage Proofs</h3> <p>When MixHash is used to identify a piece of public data, anyone can construct a storage proof to demonstrate possession of a copy of that data. Here is a typical process for using a public data storage proof:</p> <ol start="0"> <li>Users eligible to submit storage proofs for rewards are referred to as Suppliers.</li> <li>A Supplier prepares a storage proof for data D (with MixHash <code>mix_hash_d</code>) based on a block at height <code>h</code>. A 256-bit <code>nonce</code> value for the proof is derived from this block (usually directly using the block's hash).</li> <li>To generate a correct storage proof, the Supplier needs to traverse every 1KB chunk of D to find the optimal leaf node <code>m</code>. This is done by attempting to append the nonce value to the end of each chunk to minimize the new Merkle tree root hash. After determining <code>m</code>, the path <code>m_path</code> and leaf node value <code>m_leaf_data</code> of <code>m</code> are extracted.</li> <li>The Supplier constructs the storage proof for data D at block time <code>h</code> using <code>{mix_hash_d, h, m, m_path, m_leaf_data}</code> and submits it to the public network.</li> <li>The public network can validate the correctness of <code>m</code>, <code>m_path</code>, and <code>m_leaf_data</code> based on <code>mix_hash_d</code>: verifying that <code>m</code> is indeed a chunk of D. The timeliness of the proof can be verified through <code>h</code>. After passing both correctness and timeliness checks, the public network calculates <code>proof_result_m</code> based on the nonce value and existing proof information, and saves it.</li> <li>The public network does not have enough information to verify the optimality of the proof, but other Suppliers with the full data set can submit a better <code>{mix_hash_d, h, better_m, better_m_path, better_m_leaf_data}</code> to challenge the published storage proof.</li> <li>The public network can determine the success of the challenge by comparing <code>proof_result_m</code> and <code>proof_result_better_m</code>. A successful challenge indicates the old storage proof was forged. If no one challenges the published storage proof within a certain timeframe, it can be considered correct from a game-theoretic perspective.</li> <li>To support healthy competition, the public network should design an appropriate economic model, rewarding users who provide correct storage proofs and penalizing those who submit false ones.</li> </ol> <p>With an understanding of the above process, let us describe the generation and verification of storage proofs more precisely using <code>Pseudocode</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"> generate proof off chain</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> generateProof</span><span>(</span><span class="z-variable z-parameter z-function">mixHash</span><span>,</span><span class="z-variable z-parameter z-function"> blockHeight</span><span>,</span><span class="z-variable z-parameter z-function">file</span><span>)</span><span> </span></span> <span class="giallo-l"><span> nonce</span><span class="z-keyword"> =</span><span> getNonce</span><span>(</span><span>blockHeight</span><span>)</span></span> <span class="giallo-l"><span> hash_type</span><span class="z-keyword"> =</span><span> getHashType</span><span>(</span><span>mixHash</span><span>)</span></span> <span class="giallo-l"><span> chunk_hash_array</span><span class="z-keyword"> =</span><span> buildChunkHashArray</span><span>(</span><span class="z-variable">file</span><span>,</span><span>hash_type</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> min_index</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> min_merkle_tree_root</span><span class="z-keyword"> =</span><span class="z-constant"> MAX_UINT256</span></span> <span class="giallo-l"><span> min_chunk</span><span class="z-keyword"> =</span><span class="z-constant"> None</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> m_index</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> chunk</span><span class="z-keyword"> in</span><span class="z-variable"> file</span><span>:</span></span> <span class="giallo-l"><span> new_chunk</span><span class="z-keyword"> =</span><span> chunk</span><span class="z-keyword"> +</span><span> nonce</span></span> <span class="giallo-l"><span> chunk_hash_array</span><span>[</span><span>m_index</span><span>]</span><span class="z-keyword"> =</span><span> getChunkHash</span><span>(</span><span>new_chunk</span><span>,</span><span>hash_type</span><span>)</span></span> <span class="giallo-l"><span> merkle_tree_root</span><span class="z-keyword"> =</span><span> getMerkleTreeRoot</span><span>(</span><span>chunk_hash_array</span><span>,</span><span>hash_type</span><span>)</span></span> <span class="giallo-l"><span> chunk_hash_array</span><span>[</span><span>m_index</span><span>]</span><span class="z-keyword"> =</span><span> getChunkHash</span><span>(</span><span>chunk</span><span>,</span><span>hash_type</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>merkle_tree_root</span><span class="z-keyword"> &lt;</span><span> min_merkle_tree_root</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> min_merkle_tree_root</span><span class="z-keyword"> =</span><span> merkle_tree_root</span></span> <span class="giallo-l"><span> min_index</span><span class="z-keyword"> =</span><span> m_index</span></span> <span class="giallo-l"><span> min_chunk</span><span class="z-keyword"> =</span><span> chunk</span></span> <span class="giallo-l"><span> m_index</span><span class="z-keyword"> =</span><span> m_index</span><span class="z-keyword"> +</span><span class="z-constant"> 1</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"> verify on chain</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> verifyDataProof</span><span>(</span><span class="z-variable">mixHash</span><span>,</span><span class="z-variable"> blockHeight</span><span>,</span><span class="z-variable"> m_index</span><span>,</span><span class="z-variable"> m_path</span><span>,</span><span class="z-variable"> m_leaf_data</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>current_block_height </span><span class="z-keyword">-</span><span> blockHeight </span><span class="z-keyword">&gt;</span><span> MAX_BLOCK_DISTANCE</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span class="z-string">&quot;proof expired&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> hash_type </span><span class="z-keyword">=</span><span class="z-entity z-name"> getHashType</span><span>(</span><span>mixHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> merkle_tree_root </span><span class="z-keyword">=</span><span class="z-entity z-name"> getMerkleTreeRootFromPath</span><span>(</span><span>m_path</span><span>,</span><span>m_leaf_data</span><span>,</span><span>hash_type</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-entity z-name">low192</span><span>(</span><span>merkle_tree_root</span><span>)</span><span class="z-keyword"> !=</span><span class="z-entity z-name"> low192</span><span>(</span><span>mixHash</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span class="z-string">&quot;invalid proof&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> nonce </span><span class="z-keyword">=</span><span class="z-entity z-name"> getNonce</span><span>(</span><span>blockHeight</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> proof_result </span><span class="z-keyword">=</span><span class="z-entity z-name"> getMerkleTreeRootFromPath</span><span>(</span><span>m_path</span><span>,</span><span>m_leaf_data</span><span>.</span><span class="z-entity z-name">append</span><span>(</span><span>nonce</span><span>)</span><span>,</span><span>hash_type</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> last_proof_result</span><span>,</span><span>last_prover </span><span class="z-keyword">=</span><span class="z-entity z-name"> getProofResult</span><span>(</span><span>mixHash</span><span>,</span><span> blockHeight</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>proof_result </span><span class="z-keyword">&lt;</span><span> last_proof_result</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ProofPunish</span><span>(</span><span>last_prover</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> updateProofResult</span><span>(</span><span>mixHash</span><span>,</span><span> blockHeight</span><span>,</span><span> proof_result</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></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>To minimize the size of the storage proof as much as possible, we have optimized the implementation of getMerkleTreeRoot: besides the RootHash, the hash values of other nodes are truncated to the lower 128 bits. This approach effectively compresses the hash value of a complete Merkle tree to half its size. The full implementation details can be found in the subsequent Reference Implementation section.</p> <h3 id="defending-sourcing-attack">Defending Sourcing Attack</h3> <p>As can be seen from the process described above, the core of constructing public data storage proofs is based on a public, non-repeating nonce value generated at a specific moment. It requires traversing the entire content of the file within a designated time to construct a correct proof. Without restrictions, this process is vulnerable to external data source attacks: Suppliers do not store data locally but obtain it through network requests when constructing storage proofs. How does our design prevent such attacks?</p> <ol> <li> <p>Time-Limited Response: Suppliers must submit storage proofs within a specified time. On a typical public network like Ethereum, the block time is about 15 seconds. A typical maximum block interval could be 2 (MAX_BLOCK_DISTANCE = 2), meaning Suppliers must complete the construction and submission of the storage proof within 30 seconds. This duration is insufficient for most data sources to complete transmission, thus Suppliers must store data locally to have a chance to construct storage proofs within the allotted time.</p> </li> <li> <p>Economic Game Theory: The economic model based on public data storage proofs usually rewards the first Supplier to submit a correct storage proof. This means that, from a game-theoretic standpoint, the inherent delay in using external data sources to construct storage proofs reduces the likelihood of successful submission. Economically, it's less profitable than the expected gains from storing data locally. The economic model incentivizes Suppliers to store data locally.</p> </li> </ol> <h3 id="success-rate-of-defending-sourcing-attack">Success Rate of Defending Sourcing Attack</h3> <p>Using a strategy combining block interval limitations and priority for first-time submissions is often effective in defending against external data source attacks. The effectiveness of this approach primarily relies on the difference in speed between reading files from local storage and retrieving files from the network. We can define the success rate `R`` of defending against external data source attacks using the following formula:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>R = (TNetwork - TLocal) / AvgProofTime</span></span></code></pre> <p>The larger the AvgProofTime, the lower the success rate of defending against Sourcing Attack. Currently, the most significant factor affecting AvgProofTime is the average time for on-chain transactions. For example, in the BTC network, the time for 2 blocks is approximately 20 minutes. With such a large AvgProofTime, the success rate `R`` decreases rapidly, making sourcing attacks more likely to succeed. We can introduce a dynamically adjustable Proof of Work (PoW) mechanism to further defend against Sourcing Attack. This modification alters the formula as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>R = (TNetwork - TLocal) / (AvgProofTime-AvgPoWTime)</span></span></code></pre> <p>With the introduction of the Proof of Work (PoW) concept, the strategy for submitting storage proofs becomes: constructing and submitting storage proofs within a specified time while endeavoring to complete as much PoW computation as possible. In the valid proof time window, the storage proof with the greater amount of PoW computation prevails. Such a mechanism can effectively defend against external data source attacks, especially when AvgProofTime is large.</p> <p>Integrating a PoW mechanism into the design of public data storage proofs is not complex. A simple implementation could modify the second step to:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>2. To generate a correct storage proof, the Supplier needs to traverse all 1KB chunks of D to find the optimal leaf node `m`. The method involves attempting to append the nonce and a self-constructed noise value to the end of each chunk to minimize the new Merkle tree root hash and, according to PoW difficulty requirements, ensuring that the last x bits of the constructed `proof_result_m` are zero. After determining `m` and the noise, the path `m_path` and the leaf node value `m_leaf_data` of `m` are extracted.</span></span></code></pre> <p>The <code>Pseudocode</code> adjusted according to the above modifications is as follows:</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"> generate proof with PoW off chain</span></span> <span class="giallo-l"><span class="z-constant">POW_DIFFICULTY</span><span class="z-keyword"> =</span><span class="z-constant"> 16</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> generateProofWithPow</span><span>(</span><span class="z-variable z-parameter z-function">mixHash</span><span>,</span><span class="z-variable z-parameter z-function"> blockHeight</span><span>,</span><span class="z-variable z-parameter z-function">file</span><span>)</span><span> </span></span> <span class="giallo-l"><span> nonce</span><span class="z-keyword"> =</span><span> getNonce</span><span>(</span><span>blockHeight</span><span>)</span></span> <span class="giallo-l"><span> hash_type</span><span class="z-keyword"> =</span><span> getHashType</span><span>(</span><span>mixHash</span><span>)</span></span> <span class="giallo-l"><span> chunk_hash_array</span><span class="z-keyword"> =</span><span> buildChunkHashArray</span><span>(</span><span class="z-variable">file</span><span>,</span><span>hash_type</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> min_index</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> min_merkle_tree_root</span><span class="z-keyword"> =</span><span class="z-constant"> MAX_UINT256</span></span> <span class="giallo-l"><span> min_chunk</span><span class="z-keyword"> =</span><span class="z-constant"> None</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> m_index</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> noise</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-keyword"> for</span><span> chunk</span><span class="z-keyword"> in</span><span class="z-variable"> file</span><span>:</span></span> <span class="giallo-l"><span> new_chunk</span><span class="z-keyword"> =</span><span> chunk</span><span class="z-keyword"> +</span><span> nonce</span><span class="z-keyword"> +</span><span> noise</span></span> <span class="giallo-l"><span> chunk_hash_array</span><span>[</span><span>m_index</span><span>]</span><span class="z-keyword"> =</span><span> getChunkHash</span><span>(</span><span>new_chunk</span><span>,</span><span>hash_type</span><span>)</span></span> <span class="giallo-l"><span> merkle_tree_root</span><span class="z-keyword"> =</span><span> getMerkleTreeRoot</span><span>(</span><span>chunk_hash_array</span><span>,</span><span>hash_type</span><span>)</span></span> <span class="giallo-l"><span> chunk_hash_array</span><span>[</span><span>m_index</span><span>]</span><span class="z-keyword"> =</span><span> getChunkHash</span><span>(</span><span>chunk</span><span>,</span><span>hash_type</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>merkle_tree_root</span><span class="z-keyword"> &lt;</span><span> min_merkle_tree_root</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> min_merkle_tree_root</span><span class="z-keyword"> =</span><span> merkle_tree_root</span></span> <span class="giallo-l"><span> min_index</span><span class="z-keyword"> =</span><span> m_index</span></span> <span class="giallo-l"><span> min_chunk</span><span class="z-keyword"> =</span><span> chunk</span></span> <span class="giallo-l"><span> m_index</span><span class="z-keyword"> =</span><span> m_index</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>last_zero_bits</span><span>(</span><span>min_merkle_tree_root</span><span>)</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> POW_DIFFICULTY</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> break</span></span> <span class="giallo-l"><span> noise</span><span class="z-keyword"> =</span><span> noise</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> m_path</span><span class="z-keyword"> =</span><span> getMerkleTreePath</span><span>(</span><span>chunk_hash_array</span><span>,</span><span> min_index</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> storage_proof</span><span>(</span><span>mixHash</span><span>,</span><span> blockHeight</span><span>,</span><span> min_index</span><span>,</span><span> m_path</span><span>,</span><span> min_chunk</span><span>,</span><span>noise</span><span>)</span><span> </span></span></code></pre> <p>Applying this mechanism increases the cost of generating storage proofs, which deviates from our initial intent to reduce the widespread effective storage of public data. Moreover, heavily relying on a PoW-based economic model may allow Suppliers with significant advantages in PoW through specialized hardware to disrupt the basic participatory nature of the game, reducing the widespread distribution of public data. Therefore, it is advised not to enable the PoW mechanism unless absolutely necessary.</p> <h3 id="limitations">Limitations</h3> <ol> <li> <p>The storage proofs discussed in this paper are not suitable for storing very small files, as small files inherently struggle to defend against external data source attacks.</p> </li> <li> <p>Public data storage proofs do not address the issue of whether the data is genuinely public. Therefore, it is important to verify the public nature of MixHash in specific scenarios (which is often not easy). Allowing Suppliers to submit storage proofs for any MixHash and receive rewards would lead to a situation where Suppliers create data only they possess and exploit this to gain rewards through constructed attacks, ultimately leading to the collapse of the entire ecosystem.</p> </li> </ol> <h3 id="erc-extension-suggestion-tracking-high-value-public-data-by-mixhash">ERC Extension Suggestion: Tracking High-Value Public Data by MixHash</h3> <p>We can use the existing Ethereum ecosystem to confirm whether a MixHash is public data and track its value. For any contracts related to unstructured data, the <code>ERCPublicDataOwner</code> interface can be implemented. This interface determines whether a specific MixHash is associated with the current contract and attempts to return an Owner address corresponding to a MixHash. Additionally, for the existing and widely recognized NFT ecosystem, we suggest that new <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> contracts implement a new extension interface <code>ERC721MixHashVerify</code>. This interface can explicitly associate an NFT with a MixHash. The specific interface definition is as follows:</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"> ERCPublicDataOwner Standard, query Owner of the specified MixHash</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 &lt;ERC-Number&gt;.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERCPublicDataOwner</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"> Queries Owner of public data determined by Mixhash</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> mixHash</span><span class="z-comment"> Mixhash you want to query</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> If</span><span class="z-comment"> it is an identified public data, return the Owner address, otherwise 0x0 will be 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"> getPublicDataOwner</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> mixHash</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>ERC721MixHashVerfiy</code> extension is OPTIONAL for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> smart contracts or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> smart contracts. This extension can help establish a relationship between specified NFT and MixHash.</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"> ERC721MixHashVerfiy Extension, optional extension</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 &lt;ERC-Number&gt;.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC721MixHashVerfiy</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"> Is the tokenId of the NFT is the Mixhash?</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 tokenId is MixHash, 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"> tokenIdIsMixHash</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></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"> Queries NFT&#39;s MixHash</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"> NFT to be querying</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"> target NFT corresponds to MixHash, if it is not Mixhash, it returns 0x0</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"> tokenDataHash</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">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Storage proofs (often referred to as space-time proofs) have long been a subject of interest, with numerous implementations and related projects existing.</p> <ol> <li>Compared to existing copy proofs based on zero-knowledge proofs, our storage proof is based on "Nash Consensus," with its core principles being: a. The public network (on-chain) cannot verify the optimality of a proof but relies on economic game theory. This significantly reduces the costs of construction and verification. b. Data without value typically lacks game value and is naturally eliminated from the system. There is no commitment to elusive perpetual storage.</li> <li>It can be fully implemented through smart contracts (although the GAS cost of the current reference implementation is somewhat high), separating storage proof from the economic model.</li> <li>For public data, we do not strictly defend against Sybil attacks. A Sybil attack refers to a Supplier using multiple identities to commit to storing multiple copies of data D (e.g., n copies) while actually storing less (like just one copy) but providing n storage proofs, thereby succeeding in the attack. Strictly preventing Sybil attacks essentially means attaching more additional costs to data storage. The core of our storage proof is to increase the probability of the existence of public data copies through a combination of storage proofs and different economic models, rather than needing to strictly define how many copies exist. Therefore, from the perspective of the design of public data storage proofs, we do not need to defend against Sybil attacks.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Using HashType allows storage proofs to be compatible with EVM-compatible public blockchain systems, as well as BTC-Like public blockchain systems. In fact, MixHash could become a new cross-chain value anchor: it can track the value of the same data represented by MixHash across different public blockchain networks using different models, achieving the aggregation of cross-chain values. Considering the need for backward compatibility, we have set the default HashType of MixHash to SHA256. Two categories of HashType remain unused, leaving ample room for future expansion.</p> <h2 id="test-cases">Test Cases</h2> <p>PublicDataProofDemo includes test cases written using Hardhat.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>PublicDataProof Demo</p> <ul> <li>A standard reference implementation</li> </ul> <p>DMC public data inscription</p> <ul> <li>Based on public data storage certification, a complete economic model and gameplay has been designed on ETH network and BTC inscription network</li> </ul> <p>Learn more background and existing attempts</p> <ul> <li>DMC Main Chain</li> <li>CYFS</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>This storage proof revolves around public data. In demonstrating storage proofs, it often involves sending 1KB segments of the data to the public network. Therefore, please do not use the storage proof design presented in this paper for private data.</p> <p>The design of MixHash can support storage proofs for private files, but this requires some adjustments in the processing of the original data and the construction of the storage proof. A detailed discussion on the design of storage proofs for private files is beyond the scope of this paper. In fact, some of the projects mentioned in the Reference Implementation section use both public data storage proofs and private data storage proofs.</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-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Shivanshi Tyagihttps://github.com/nerderlyne Ross Campbellhttps://github.com/z0r0z https://wg-eips.ritovision.com/7582/

Extends ERC-4337 interface with nonce-based plugins

<h2 id="abstract">Abstract</h2> <p>This proposal standardizes a method for adding plugins and composable logic to smart contract accounts built on existing interfaces like <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> (e.g., ERC-4337's <code>IAccount</code>). Specifically, by formalizing how applications can use the ERC-4337 Entry Point <code>NonceManager</code> and the emission of the <code>IEntryPoint</code> <code>UserOperationEvent</code> to account for plugin interactions, as well, as how to extract designated validators (in this case, by means of <code>IAccount</code>'s <code>validateUserOp</code>), accounts can specify how they call plugin contracts and grant special executory access for more advanced operations. Furthermore, this minimalist plugin approach is developer-friendly and complimentary to existing account abstraction standards by not requiring any additional functions for contracts that follow the <code>IAccount</code> interface (itself minimalist in only specifying one function, <code>validateUserOp</code>).</p> <h2 id="motivation">Motivation</h2> <p>Smart contract accounts (contract accounts) are a powerful tool for managing digital assets and executing transactions by allowing users to program their interactions with blockchains. However, they are often limited in their functionality and flexibility without sufficient consensus around secure abstraction designs (albeit, the adoption of ERC-4337 is the preferred path of this proposal). For example, contract accounts are often unable to support social recovery, payment schedules, and other features that are common in traditional financial systems without efficient and predictable schemes to delegate execution and other access rights to approximate the UX of custodial and more specialized applications.</p> <p>Account abstraction standards like ERC-4337 have achieved simplification of many core contract account concerns such as transaction fee payments, but to fully leverage the expressive capability of these systems to accomplish user intents, minimalist methods to delegate contract account access and validation to other contracts would aid their UX and extend the benefits of centering operations around the Entry Point.</p> <p>While the <code>IAccount</code> interface from ERC-4337 does not specify a way to add custom validation logic to contract accounts to support plugins and similar extensions without upgrades or migrations, it nevertheless contains sufficient information to do so efficiently. This proposal therefore offers a method for adding plugins and other composable validation logic to smart contract accounts built on existing interfaces with singleton nonce-tracking like ERC-4337's <code>IAccount</code> and <code>NonceManager</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><img src="https://wg-eips.ritovision.com/7582/./assets/base-flow.svg" alt="diagram showing proposed flow" /></p> <p>We leverage the key in ERC-4337 semi-abstracted nonce as the pointer to <code>validator</code> identifier. If a non-sequential key (<code>&gt;type(uint64).max</code>) is used as an ERC-4337 Entry Point <code>UserOperation</code> (userOp) <code>nonce</code>, the <code>validateUserOp</code> function in the <code>sender</code> contract account MUST extract the validator identifier, this MAY be the address itself or a pointer to the validator address in storage. Once the validator contract address is extracted, the proposed contract account (henceforth, shall be referred to as MADV account) MUST forward the userOp calldata to the validator. This calldata SHOULD be the entire userOp. In response to this delegated validation, the validator contract MUST return the ERC-4337 <code>validationData</code>, and the MADV <code>sender</code> account MUST return this as the <code>validationData</code> to the Entry Point.</p> <p>In all of the above validation steps, the validator contract MUST respect the ERC-4337 Entry Point conventions. Note, that while validator key data might be included elsewhere in a <code>UserOperation</code> to achieve similar contract account modularity, for example, by packing this data into the <code>signature</code> field, this proposal opts to repurpose <code>nonce</code> for this pointer to minimize calldata costs and to benefit from the EntryPoint's <code>getNonce</code> accounting, as well as the discoverability of user plugin interactions in the <code>UserOperationEvent</code> which exposes <code>nonce</code> but not other userOp data.</p> <h3 id="erc-4337-references">ERC-4337 references:</h3> <p><code>PackedUserOperation</code> interface</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"> * User Operation struct</span></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 sender account of this request.</span></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"> - Unique value the sender uses to verify it is not a replay. In MADV, the validator identifier is encoded in the high 192 bit (`key`) of the nonce 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"> initCode</span><span class="z-comment"> - If set, the account contract will be created by this constructor/</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> callData</span><span class="z-comment"> - The method call to execute on this 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"> accountGasLimits</span><span class="z-comment"> - Packed gas limits for validateUserOp and gas limit passed to the callData method call.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> preVerificationGas</span><span class="z-comment"> - Gas not calculated by the handleOps method, but added to the gas paid.</span></span> <span class="giallo-l"><span class="z-comment"> * Covers batch overhead.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> gasFees</span><span class="z-comment"> - packed gas fields maxPriorityFeePerGas and maxFeePerGas - Same as EIP-1559 gas parameters.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> paymasterAndData</span><span class="z-comment"> - If set, this field holds the paymaster address, verification gas limit, postOp gas limit and paymaster-specific extra data</span></span> <span class="giallo-l"><span class="z-comment"> * The paymaster will pay for the transaction instead 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"> signature</span><span class="z-comment"> - Sender-verified signature over the entire request, the EntryPoint address and the chain ID.</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"> PackedUserOperation</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"> uint256</span><span> nonce</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> initCode</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> callData</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> accountGasLimits</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> preVerificationGas</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> gasFees</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> paymasterAndData</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> signature</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>IAccount</code> 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"> IAccount</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * Validate user&#39;s signature and nonce</span></span> <span class="giallo-l"><span class="z-comment"> * the entryPoint will make the call to the recipient only if this validation call returns successfully.</span></span> <span class="giallo-l"><span class="z-comment"> * signature failure should be reported by returning SIG_VALIDATION_FAILED (1).</span></span> <span class="giallo-l"><span class="z-comment"> * This allows making a &quot;simulation call&quot; without a valid signature</span></span> <span class="giallo-l"><span class="z-comment"> * Other failures (e.g. nonce mismatch, or invalid signature format) should still revert to signal failure.</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 validate caller is the entryPoint.</span></span> <span class="giallo-l"><span class="z-comment"> * Must validate the signature and nonce</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> userOp</span><span class="z-comment"> - The operation that is about to be executed.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> userOpHash</span><span class="z-comment"> - Hash of the user&#39;s request data. can be used as the basis for 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"> missingAccountFunds</span><span class="z-comment"> - Missing funds on the account&#39;s deposit in the entrypoint.</span></span> <span class="giallo-l"><span class="z-comment"> * This is the minimum amount to transfer to the sender(entryPoint) to be</span></span> <span class="giallo-l"><span class="z-comment"> * able to make the call. The excess is left as a deposit in the entrypoint</span></span> <span class="giallo-l"><span class="z-comment"> * for future calls. Can be withdrawn anytime using &quot;entryPoint.withdrawTo()&quot;.</span></span> <span class="giallo-l"><span class="z-comment"> * In case there is a paymaster in the request (or the current deposit is high</span></span> <span class="giallo-l"><span class="z-comment"> * enough), this value will be zero.</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"> validationData</span><span class="z-comment"> - Packaged ValidationData structure. use `_packValidationData` and</span></span> <span class="giallo-l"><span class="z-comment"> * `_unpackValidationData` to encode and decode.</span></span> <span class="giallo-l"><span class="z-comment"> * &lt;20-byte&gt; sigAuthorizer - 0 for valid signature, 1 to mark signature failure,</span></span> <span class="giallo-l"><span class="z-comment"> * otherwise, an address of an &quot;authorizer&quot; contract.</span></span> <span class="giallo-l"><span class="z-comment"> * &lt;6-byte&gt; validUntil - Last timestamp this operation is valid. 0 for &quot;indefinite&quot;</span></span> <span class="giallo-l"><span class="z-comment"> * &lt;6-byte&gt; validAfter - First timestamp this operation is valid</span></span> <span class="giallo-l"><span class="z-comment"> * If an account doesn&#39;t use time-range, it is enough to</span></span> <span class="giallo-l"><span class="z-comment"> * return SIG_VALIDATION_FAILED value (1) for signature failure.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">Note</span><span class="z-comment"> that the validation code cannot use block.timestamp (or block.number) directly.</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"> validateUserOp</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> PackedUserOperation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> userOp</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> userOpHash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> missingAccountFunds</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">uint256</span><span class="z-variable"> validationData</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>NonceManager</code> interface</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"> * Return the next nonce for this sender.</span></span> <span class="giallo-l"><span class="z-comment"> * Within a given key, the nonce values are sequenced (starting with zero, and incremented by one on each userop)</span></span> <span class="giallo-l"><span class="z-comment"> * But UserOp with different keys can come with arbitrary order.</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"> sender</span><span class="z-comment"> the account 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"> key</span><span class="z-comment"> the high 192 bit of the nonce, in MADV the validator identifier is encoded here </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"> nonce</span><span class="z-comment"> a full nonce to pass for next UserOp with this 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"> getNonce</span><span>(</span><span class="z-support">address</span><span class="z-variable"> sender</span><span>,</span><span class="z-support"> uint192</span><span class="z-variable"> key</span><span>)</span></span> <span class="giallo-l"><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"> nonce</span><span>)</span><span>;</span></span></code></pre> <p><code>UserOperationEvent</code></p> <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"> * An event emitted after each successful request</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> userOpHash</span><span class="z-comment"> - unique identifier for the request (hash its entire content, except 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"> sender</span><span class="z-comment"> - the account that generates this request.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> paymaster</span><span class="z-comment"> - if non-null, the paymaster that pays for this request.</span></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 value from the request.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> success</span><span class="z-comment"> - true if the sender transaction succeeded, false if reverted.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> actualGasCost</span><span class="z-comment"> - actual amount paid (by account or paymaster) for this UserOperation.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> actualGasUsed</span><span class="z-comment"> - total gas used by this UserOperation (including preVerification, creation, validation and execution).</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"> UserOperationEvent</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> userOpHash</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"> paymaster</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> nonce</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> success</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> actualGasCost</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> actualGasUsed</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This proposal is designed to be a minimalist extension to ERC-4337 that allows for additional functionality without requiring changes to the existing interface. Keeping the proposal's footprint small.</p> <p>Further, by repurposing the nonce field for the validator identifier we minimize calldata costs and leverage existing <code>getNonce</code> accounting. The <code>UserOperationEvent</code> emits nonce which can be used for tracking validator invocations without additional events. Other options like packing the validator identifier into the <code>signature</code> field were considered but were rejected due to potential for conflict with other signatures schemes and increased opaqueness into validator invocation.</p> <p>This proposal allows for MADV accounts to specify their own method for extracting the validator address from the <code>nonce</code>. This provides flexibility to account developers and supports both "just in time" validators as well as a more predictable storage pattern for plugin reuse.</p> <p>The requirement is simply to use <code>nonce</code> for encoding an identifier and to return the <code>validationData</code> from the extracted validator contract to the <code>EntryPoint</code> in line with the requirements of the ERC-4337 <code>validateUserOp</code> function.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>See the <a href="https://wg-eips.ritovision.com/7582/./assets/MADVAccount.sol">MADV reference implementation</a> for a simple example of how to implement this proposal.</p> <h2 id="security-considerations">Security Considerations</h2> <p>As this proposal introduces no new functions and leaves implementation of the validator extraction method and approval logic open to developers, the surface for security issues is intentionally kept small. Nevertheless, specific validator use cases require further discussion and consideration of the overall ERC-4337 verification flow and its underlying security.</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-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 zeroknotshttps://github.com/zeroknots Konrad Kopphttps://github.com/kopy-kat Taek Leehttps://github.com/leekt Fil Makarovhttps://github.com/filmakarov Elim Poonhttps://github.com/yaonam Lyu Minhttps://github.com/rockmin216 https://wg-eips.ritovision.com/7579/

Modular smart account interfaces and behavior for interoperability with minimal restrictions for accounts and modules

<h2 id="abstract">Abstract</h2> <p>This proposal outlines the minimally required interfaces and behavior for modular smart accounts and modules to ensure interoperability across implementations. For accounts, the standard specifies execution, config and fallback interfaces as well as compliance to <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> and <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>. For modules, the standard specifies a core interface, module types and type-specific interfaces.</p> <h2 id="motivation">Motivation</h2> <p>Contract accounts are gaining adoption with many accounts being built using a modular architecture. These modular contract accounts (hereafter smart accounts) move functionality into external contracts (modules) in order to increase the speed and potential of innovation, to future-proof themselves and to allow customizability by developers and users. However, currently these smart accounts are built in vastly different ways, creating module fragmentation and vendor lock-in. There are several reasons for why standardizing smart accounts is very beneficial to the ecosystem, including:</p> <ul> <li>Interoperability for modules to be used across different smart accounts</li> <li>Interoperability for smart accounts to be used across different wallet applications and sdks</li> <li>Preventing significant vendor lock-in for smart account users</li> </ul> <p>However, it is highly important that this standardization is done with minimal impact on the implementation logic of the accounts, so that smart account vendors can continue to innovate, while also allowing a flourishing, multi-account-compatible module ecosystem. As a result, the goal of this standard is to define the smart account and module interfaces and behavior that is as minimal as possible while ensuring interoperability between accounts and modules.</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="definitions">Definitions</h3> <ul> <li><strong>Smart account</strong> - A smart contract account that has a modular architecture.</li> <li><strong>Module</strong> - A smart contract with self-contained smart account functionality. <ul> <li>Validator: A module used during the validation phase to determine if a transaction is valid and should be executed on the account.</li> <li>Executor: A module that can execute transactions on behalf of the smart account via a callback.</li> <li>Fallback Handler: A module that can extend the fallback functionality of a smart account.</li> </ul> </li> <li><strong>EntryPoint</strong> - A trusted singleton contract according to <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> specifications.</li> <li><strong>Validation</strong> - Any functionality used to determine if an execution should be made on the account. When using ERC-4337, this function will be <code>validateUserOp</code>.</li> <li><strong>Execution</strong> - Any functionality used to execute an operation from or on the users account. When using ERC-4337, this will be called by the EntryPoint using <code>userOp.callData</code>.</li> </ul> <h3 id="account">Account</h3> <h4 id="validation">Validation</h4> <p>This standard does not dictate how validator selection is implemented. However, should a smart account encode validator selection mechanisms in data fields passed to the validator (e.g. in <code>userOp.signature</code> if used with ERC-4337), the smart account MUST sanitize the affected values before invoking the validator.</p> <p>The smart account's validation function SHOULD return the return value of the validator.</p> <h4 id="execution-behavior">Execution Behavior</h4> <p>To comply with this standard, smart accounts MUST implement the execution interface 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"> IERC7579Execution</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"> Executes a transaction on behalf of the account. MAY be payable.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> mode</span><span class="z-comment"> The encoded execution mode 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"> executionCalldata</span><span class="z-comment"> The encoded execution call data.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST ensure adequate authorization control: e.g. onlyEntryPointOrSelf if used with ERC-4337</span></span> <span class="giallo-l"><span class="z-comment"> * If a mode is requested that is not supported by the Account, it MUST 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"> execute</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> mode</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> executionCalldata</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"> Executes a transaction on behalf of the account. MAY be payable.</span></span> <span class="giallo-l"><span class="z-comment"> * This function is intended to be called by Executor 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"> mode</span><span class="z-comment"> The encoded execution mode 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"> executionCalldata</span><span class="z-comment"> The encoded execution call data.</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"> returnData</span><span class="z-comment"> An array with the returned data of each executed subcall</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST ensure adequate authorization control: i.e. onlyExecutorModule</span></span> <span class="giallo-l"><span class="z-comment"> * If a mode is requested that is not supported by the Account, it MUST 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"> executeFromExecutor</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> mode</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> executionCalldata</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">bytes</span><span>[</span><span>]</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></span></code></pre> <p>The account MAY also implement the following function in accordance with ERC-4337:</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"> ERC-4337 executeUserOp according to ERC-4337 v0.7</span></span> <span class="giallo-l"><span class="z-comment"> * This function is intended to be called by ERC-4337 EntryPoint.sol</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> userOp</span><span class="z-comment"> PackedUserOperation struct (see ERC-4337 v0.7+)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> userOpHash</span><span class="z-comment"> The hash of the PackedUserOperation struct</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST ensure adequate authorization control: i.e. onlyEntryPoint</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"> executeUserOp</span><span>(</span><span class="z-storage z-type">PackedUserOperation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> userOp</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> userOpHash</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>If an account chooses to implement <code>executeUserOp</code>, this method SHOULD ensure the account executes <code>userOp.calldata</code> except 4 most significant bytes, which are reserved for <code>executeUserOp.selector</code> as per ERC-4337. Thus the <code>userOp.callData[4:]</code> should represent the calldata for a valid call to the account. It is RECOMMENDED that the account executes a <code>delegatecall</code> in order to preserve the original <code>msg.sender</code> to the account.</p> <p>Example:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(bool success, bytes memory innerCallRet) = address(this).delegatecall(userOp.callData[4:]);</span></span></code></pre> <p>The execution mode is a <code>bytes32</code> value that is structured as follows:</p> <ul> <li>callType (1 byte): <code>0x00</code> for a single <code>call</code>, <code>0x01</code> for a batch <code>call</code>, <code>0xfe</code> for <code>staticcall</code> and <code>0xff</code> for <code>delegatecall</code></li> <li>execType (1 byte): <code>0x00</code> for executions that revert on failure, <code>0x01</code> for executions that do not revert on failure but implement some form of error handling</li> <li>unused (4 bytes): this range is reserved for future standardization</li> <li>modeSelector (4 bytes): an additional mode selector that can be used to create further execution modes</li> <li>modePayload (22 bytes): additional data to be passed</li> </ul> <p>Here is a visual representation of the execution mode:</p> <table><thead><tr><th>CallType</th><th>ExecType</th><th>Unused</th><th>ModeSelector</th><th>ModePayload</th></tr></thead><tbody> <tr><td>1 byte</td><td>1 byte</td><td>4 bytes</td><td>4 bytes</td><td>22 bytes</td></tr> </tbody></table> <p>Accounts are NOT REQUIRED to implement all execution modes. The account MUST declare what modes are supported in <code>supportsExecutionMode</code> (see below) and if a mode is requested that is not supported by the account, the account MUST revert.</p> <p>The account MUST encode the execution data the following ways:</p> <ul> <li>For single calls, the <code>target</code>, <code>value</code> and <code>callData</code> are packed in this order (ie <code>abi.encodePacked</code> in Solidity).</li> <li>For delegatecalls, the <code>target</code> and <code>callData</code> are packed in this order (ie <code>abi.encodePacked</code> in Solidity).</li> <li>For batch calls, the <code>targets</code>, <code>values</code> and <code>callDatas</code> are put into an array of <code>Execution</code> structs that includes these fields in this order (ie <code>Execution(address target, uint256 value, bytes memory callData)</code>). Then, this array is encoded with padding (ie <code>abi.encode</code> in Solidity).</li> </ul> <h4 id="account-configurations">Account configurations</h4> <p>To comply with this standard, smart accounts MUST implement the account config interface 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"> IERC7579AccountConfig</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"> Returns the account id of the smart 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"> accountImplementationId</span><span class="z-comment"> the account id of the smart account</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return a non-empty string</span></span> <span class="giallo-l"><span class="z-comment"> * The accountId SHOULD be structured like so:</span></span> <span class="giallo-l"><span class="z-comment"> * &quot;vendorname.accountname.semver&quot;</span></span> <span class="giallo-l"><span class="z-comment"> * The id SHOULD be unique across all smart accounts</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"> accountId</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 class="z-variable"> accountImplementationId</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"> Function to check if the account supports a certain execution mode (see above)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> encodedMode</span><span class="z-comment"> the encoded mode</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return true if the account supports the mode and 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"> supportsExecutionMode</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> encodedMode</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"> Function to check if the account supports a certain module typeId</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> moduleTypeId</span><span class="z-comment"> the module type ID according to the ERC-7579 spec</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return true if the account supports the module type and 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"> supportsModule</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> moduleTypeId</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="module-configurations">Module configurations</h4> <p>To comply with this standard, smart accounts MUST implement the module config interface below.</p> <p>When storing an installed module, the smart account MUST ensure that there is a way to differentiate between module types. For example, the smart account should be able to implement access control that only allows installed executors, but not other installed modules, to call the <code>executeFromExecutor</code> function.</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"> IERC7579ModuleConfig</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ModuleInstalled</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> moduleTypeId</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"> ModuleUninstalled</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> moduleTypeId</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> <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"> Installs a Module of a certain type on the smart 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"> moduleTypeId</span><span class="z-comment"> the module type ID according to the ERC-7579 spec</span></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"> the module 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"> initData</span><span class="z-comment"> arbitrary data that may be required on the module during `onInstall`</span></span> <span class="giallo-l"><span class="z-comment"> * initialization.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST implement authorization control</span></span> <span class="giallo-l"><span class="z-comment"> * MUST call `onInstall` on the module with the `initData` parameter if provided</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit ModuleInstalled event</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if the module is already installed or the initialization on the module failed</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"> installModule</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> moduleTypeId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> module</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> initData</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"> Uninstalls a Module of a certain type on the smart 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"> moduleTypeId</span><span class="z-comment"> the module type ID according the ERC-7579 spec</span></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"> the module 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"> deInitData</span><span class="z-comment"> arbitrary data that may be required on the module during `onInstall`</span></span> <span class="giallo-l"><span class="z-comment"> * initialization.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST implement authorization control</span></span> <span class="giallo-l"><span class="z-comment"> * MUST call `onUninstall` on the module with the `deInitData` parameter if provided</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit ModuleUninstalled event</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if the module is not installed or the deInitialization on the module failed</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"> uninstallModule</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> moduleTypeId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> module</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> deInitData</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 whether a module is installed on the smart 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"> moduleTypeId</span><span class="z-comment"> the module type ID according the ERC-7579 spec</span></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"> the module 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"> additionalContext</span><span class="z-comment"> arbitrary data that may be required to determine if the module is installed</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return true if the module is installed and 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"> isModuleInstalled</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> moduleTypeId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> module</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> additionalContext</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="hooks">Hooks</h4> <p>Hooks are an OPTIONAL extension of this standard. Smart accounts MAY use hooks to execute custom logic and checks before and/or after the smart accounts performs a single or batched execution. To comply with this OPTIONAL extension, a smart account:</p> <ul> <li>MUST call the <code>preCheck</code> function of one or multiple hooks before any call or batch of calls going through execute or executeFromExecutor</li> <li>MUST call the <code>postCheck</code> function of one or multiple hooks after any call or batch of calls through execute or executeFromExecutor</li> <li>Is RECOMMENDED to call <code>preCheck</code> and <code>postCheck</code> before and after executing calls to <code>installModule</code> or <code>uninstallModule</code></li> <li>Is RECOMMENDED to call <code>preCheck</code> and <code>postCheck</code> before and after executing calls through other (custom) functions called execution</li> </ul> <h4 id="erc-1271-forwarding">ERC-1271 Forwarding</h4> <p>The smart account MUST implement the ERC-1271 interface. The <code>isValidSignature</code> function calls MAY be forwarded to a validator. If ERC-1271 forwarding is implemented, the validator MUST be called with <code>isValidSignatureWithSender(address sender, bytes32 hash, bytes signature)</code>, where the sender is the <code>msg.sender</code> of the call to the smart account. Should the smart account implement any validator selection encoding in the <code>bytes signature</code> parameter, the smart account MUST sanitize the parameter, before forwarding it to the validator.</p> <p>The smart account's ERC-1271 <code>isValidSignature</code> function SHOULD return the return value of the validator that the request was forwarded to.</p> <h4 id="fallback">Fallback</h4> <p>Smart accounts MAY implement a fallback function that forwards the call to a fallback handler.</p> <p>If the smart account has a fallback handler installed, it:</p> <ul> <li>MUST use <code>call</code> or <code>staticcall</code> to invoke the fallback handler</li> <li>MUST utilize <a href="https://wg-eips.ritovision.com/2771/">ERC-2771</a> to add the original <code>msg.sender</code> to the <code>calldata</code> sent to the fallback handler</li> <li>MUST route to fallback handlers based on the function selector of the calldata</li> <li>MAY implement authorization control, which SHOULD be done via hooks</li> </ul> <p>If the account adds features via fallback, these should be considered the same as if the account was implementing those features natively. ERC-165 support (see below) is one example of such an approach. Note, that it is only RECOMMENDED to implement view functions via fallback where this can lead to greater extensibility. It is NOT RECOMMENDED to implement core account logic via a fallback.</p> <h4 id="erc-165">ERC-165</h4> <p>Smart accounts MAY implement ERC-165. However, for every interface function that reverts instead of implementing the functionality, the smart account MUST return <code>false</code> for the corresponding interface id.</p> <h3 id="modules">Modules</h3> <p>This standard separates modules into the following different types that each has a unique and incremental identifier, which MUST be used by accounts, modules and other entities to identify the module type:</p> <ul> <li>Validation (type id: 1)</li> <li>Execution (type id: 2)</li> <li>Fallback (type id: 3)</li> <li>Hooks (type id: 4)</li> </ul> <p>Note: A single module can be of multiple types.</p> <p>Modules 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"> IERC7579Module</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"> This function is called by the smart account during installation of the module</span></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"> arbitrary data that may be required on the module during `onInstall` initialization</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert on error (e.g. if module is already enabled)</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"> onInstall</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>;</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"> This function is called by the smart account during uninstallation of the module</span></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"> arbitrary data that may be required on the module during `onUninstall` de-initialization</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert on error</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"> onUninstall</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>;</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 boolean value if module is a certain type</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> moduleTypeId</span><span class="z-comment"> the module type ID according the ERC-7579 spec</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return true if the module is of the given type and 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"> isModuleType</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> moduleTypeId</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>Note: A single module that is of multiple types MAY decide to pass <code>moduleTypeId</code> inside <code>data</code> to <code>onInstall</code> and/or <code>onUninstall</code> methods, so those methods are able to properly handle installation/uninstallation for various types. Example:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Module.sol</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> onInstall</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> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ...</span></span> <span class="giallo-l"><span> (</span><span class="z-support">uint256</span><span> moduleTypeId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> otherData</span><span>)</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>data</span><span>,</span><span> (</span><span class="z-support">uint256</span><span>,</span><span class="z-support"> bytes</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ...</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="validators">Validators</h4> <p>Validators MUST implement the <code>IERC7579Module</code> and the <code>IERC7579Validator</code> interface and have module type id: <code>1</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"> IERC7579Validator</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7579Module</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"> Validates a UserOperation</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> userOp</span><span class="z-comment"> the ERC-4337 PackedUserOperation</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> userOpHash</span><span class="z-comment"> the hash of the ERC-4337 PackedUserOperation</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST validate that the signature is a valid signature of the userOpHash</span></span> <span class="giallo-l"><span class="z-comment"> * SHOULD return ERC-4337&#39;s SIG_VALIDATION_FAILED (and not revert) on signature mismatch</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"> validateUserOp</span><span>(</span><span class="z-storage z-type">PackedUserOperation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> userOp</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> userOpHash</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Validates a signature using ERC-1271</span></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 that sent the ERC-1271 request to the smart 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"> hash</span><span class="z-comment"> the hash of the ERC-1271 request</span></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"> the signature of the ERC-1271 request</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return the ERC-1271 `MAGIC_VALUE` if the signature is valid</span></span> <span class="giallo-l"><span class="z-comment"> * MUST NOT modify state</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"> isValidSignatureWithSender</span><span>(</span><span class="z-support">address</span><span class="z-variable"> sender</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> hash</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 class="z-storage z-type"> view</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><h4 id="executors">Executors</h4> <p>Executors MUST implement the <code>IERC7579Module</code> interface and have module type id: <code>2</code>.</p> <h4 id="fallback-handlers">Fallback Handlers</h4> <p>Fallback handlers MUST implement the <code>IERC7579Module</code> interface and have module type id: <code>3</code>.</p> <p>Fallback handlers MAY implement authorization control. Fallback handlers that do implement authorization control, MUST NOT rely on <code>msg.sender</code> for authorization control but MUST use ERC-2771 <code>_msgSender()</code> instead.</p> <h4 id="hooks-1">Hooks</h4> <p>Hooks MUST implement the <code>IERC7579Module</code> and the <code>IERC7579Hook</code> interface and have module type id: <code>4</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"> IERC7579Hook</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7579Module</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"> Called by the smart account 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"> msgSender</span><span class="z-comment"> the address that called the smart 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"> value</span><span class="z-comment"> the value that was sent to the smart 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"> msgData</span><span class="z-comment"> the data that was sent to the smart account</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MAY return arbitrary data in the `hookData` return value</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"> preCheck</span><span>(</span><span class="z-support">address</span><span class="z-variable"> msgSender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> msgData</span><span>)</span><span class="z-storage z-type"> external</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"> hookData</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"> Called by the smart account after 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"> hookData</span><span class="z-comment"> the data that was returned by the `preCheck` function</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MAY validate the `hookData` to validate transaction context of the `preCheck` function</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"> postCheck</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> hookData</span><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="minimal-approach">Minimal approach</h3> <p>Smart accounts are a new concept and we are still learning about the best ways to build them. Therefore, we should not be too opinionated about how they are built. Instead, we should define the most minimal interfaces that allow for interoperability between smart accounts and modules to be used across different account implementations.</p> <p>Our approach has been twofold:</p> <ol> <li>Take learnings from existing smart accounts that have been used in production and from building interoperability layers between them</li> <li>Ensure that the interfaces are as minimal and open to alternative architectures as possible</li> </ol> <h3 id="extensions">Extensions</h3> <p>While we want to be minimal, we also want to allow for innovation and opinionated features. Some of these features might also need to be standardized (for similar reasons as the core interfaces) even if not all smart accounts will implement them. To ensure that this is possible, we suggest for future standardization efforts to be done as extensions to this standard. This means that the core interfaces will not change, but that new interfaces can be added as extensions. These should be proposed as separate ERCs, for example with the title "[FEATURE] Extension for <a href="https://wg-eips.ritovision.com/7579/">ERC-7579</a>".</p> <h3 id="specification-1">Specification</h3> <h4 id="execution-mode">Execution mode</h4> <p>Accounts need to be able to execute calldata in different ways. Rather than defining a separate function for each combination of execution types, we decided to encode the execution type in a single <code>bytes32</code> value. This allows for a more flexible and extensible approach, while also making the code far easier to write, read, maintain and audit. As explained above, the exeuction mode consists of two bytes that encode the call type and the execution type. The call type covers the three different methods of calls, namely single, batched and <code>delegatecall</code> (note that you can <code>delegatecall</code> to a multicall contract to batch <code>delegatecalls</code>). The execution type covers the two different types of executions, namely executions that revert on failure and executions that do not revert on failure but implement some form of error handling. This allows for accounts to batch together uncorrelated executions, such that if one execution fails, the other executions can still be executed. These two bytes are followed by 4 unused bytes that are reserved for futurre standardization, should this be required. This is followed by an item of 4 bytes which is a custom mode selector that accounts can implement. This allows for accounts to implement custom execution modes that are not covered by the standard and do not need to be standardized. This item is 4 bytes long to ensure collision resistance between different account vendors, with the same guarantees as Solidity function selectors. Finally, the last 22 bytes are reserved for custom data that can be passed to the account. This allows for accounts to pass any data up to 22 bytes, such as a 2 byte flag followed by an address, or otherwise a pointer to further data packed into the calldata for the execution. For example, this payload can be used to pass a hook address that should be executed before and/or after the execution.</p> <h4 id="differentiating-module-types">Differentiating module types</h4> <p>Not differentiating between module types could present a security issue when enforcing authorization control. For example, if a smart account treats validators and executors as the same type of module, it could allow a validator to execute arbitrary transactions on behalf of the smart account.</p> <h4 id="account-id">Account id</h4> <p>The account config interface includes a function <code>accountId</code> which can be used to identify an account. This is especially useful for frontend libraries that need to determine what account type and version is being used in order to implement the correct logic for account behavior that is not standardized. Alternate solutions include using an ERC-165-like interface to declare the exact differences and supported features of accounts or returning a keccak hash of the account id. However, the first solution is not as flexible as the account id and requires agreeing on a well-defined set of features to use, while the second solution is not as human-readable as the account id.</p> <h4 id="dependence-on-erc-4337">Dependence on ERC-4337</h4> <p>This standard has a strict dependency on ERC-4337 for the validation flow. However, it is likely that smart account builders will want to build modular accounts in the future that do not use ERC-4337 but, for example, a native account abstraction implementation on a rollup. Once this starts to happen, the proposed upgrade path for this standard is to move the ERC-4337 dependency into an extension (ie a separate ERC) and to make it optional for smart accounts to implement. If it is required to standardize the validation flow for different account abstraction implementations, then these requirements could also be moved into separate extensions.</p> <p>The reason this is not done from the start is that currently, the only modular accounts that are being built are using ERC-4337. Therefore, it makes sense to standardize the interfaces for these accounts first and to move the ERC-4337 dependency into an extension once there is a need for it. This is to maximize learnings about how modular accounts would look like when built on different account abstraction implementations.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <h3 id="already-deployed-smart-accounts">Already deployed smart accounts</h3> <p>Smart accounts that have already been deployed will most likely be able to implement this standard. If they are deployed as proxies, it is possible to upgrade to a new account implementation that is compliant with this standard. If they are deployed as non-upgradeable contracts, it might still be possible to become compliant, for example by adding a compliant adapter as a fallback handler, if this is supported.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A full interface of a smart account can be found in <a href="https://wg-eips.ritovision.com/7579/./assets/IMSA.sol"><code>IMSA.sol</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs more discussion. Some initial considerations:</p> <ul> <li>Implementing <code>delegatecall</code> executions on a smart account must be considered carefully. Note that smart accounts implementing <code>delegatecall</code> must ensure that the target contract is safe, otherwise security vulnerabilities are to be expected.</li> <li>The <code>onInstall</code> and <code>onUninstall</code> functions on modules may lead to unexpected callbacks (e.g. reentrancy). Account implementations should consider this by implementing adequate protection routines. Furthermore, modules could maliciously revert on <code>onUninstall</code> to stop the account from uninstalling a module and removing it from the account.</li> <li>For modules types where only a single module is active at one time (e.g. fallback handlers), calling <code>installModule</code> on a new module will not properly uninstall the previous module, unless this is properly implemented. This could lead to unexpected behavior if the old module is then added again with left over state.</li> <li>Insufficient authorization control in fallback handlers can lead to unauthorized executions.</li> <li>Malicious Hooks may revert on <code>preCheck</code> or <code>postCheck</code>, adding untrusted hooks may lead to a denial of service of the account.</li> <li>Currently account configuration functions (e.g. <code>installModule</code>) are designed for single operations. An account could allow these to be called from <code>address(this)</code>, creating the possibility to batch configuration operations. However, if an account implements greater authorization control for these functions since they are more sensitive, then these measures can be bypassed by nesting calls to configuration options in calls to self.</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> 2023-12-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 warthttps://github.com/wartstone https://wg-eips.ritovision.com/7580/

Interfaces for advertisement clients tracking user actions and checking proportional rewards.

<h2 id="abstract">Abstract</h2> <p>This ERC proposes a standard interface for advertisement clients to track user actions in contracts and check corresponding rewards from advertisement protocols. Contracts implementing the interface use events to define a region of interest within a transaction. A Dapp could implement this interface to join an advertisement protocol, which enable projects to fund users for specific actions in a contract. While users could benefit from project funds, dapps would also get proportional rewards once they joined the protocol.</p> <h2 id="motivation">Motivation</h2> <p>Dapps would propsper due to mass adoption and there emerges surging demands for advertisement on chain. Compared with advertisements in web2, web3 has tremendous advantages on delivery and many other fields. We do need a set of standard tracking interfaces to facilitate advertisement related developments, which could create new economic cycles on chain, further boost dapp prosperity and ultimately benefit on chain users.</p> <p>Tracking interface standard should be designed with essential &amp; universal support for tracking user actions, and minimum restriction, which could leave most innovative space for airdrop (or advertisement) protocol. The general routine would work like this:</p> <ol> <li>projects get a seed id (hash) from promotion side</li> <li>before the target promotion action starts, project contracts called the interface <code>onTrackStart(id, contract_address, function_hash)</code></li> <li>after the target promotion action ends, project contracts called the inferface <code>onTrackEnd(id, contract_address, function_hash)</code></li> <li>promotion contract collect the project action info and distribute the rewards back to projects</li> </ol> <p>For example, we have two entities holding their respective contracts: contract A and contract B. Contract A targets on users who did specific key moves(eg. commit specific functions) in contract B and would give bonus/airdrop to these users. Sure B would also get incentives in the meanwhile. To connect all these dots, B needs to identity these users, verify they're coming for the A's bonus. Hence, we need a track mechanism to facilitate such business.</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="interfaces">Interfaces</h3> <p>This protocol standardizes how to keep track of inter-dapp operations, which initially offers 2 main methods <code>onTrackStart</code> and <code>onTrackEnd</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.10</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"> IERCXXX</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Events</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"> Emits when track starts.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> track_id</span><span class="z-comment"> track 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"> contract_address</span><span class="z-comment"> the address of tracking 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"> function_hash</span><span class="z-comment"> the hash of tracking function with params</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> onTrackStartRecorded</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> track_id</span><span>, </span><span class="z-support">address</span><span class="z-variable"> contract_address</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> function_hash</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"> Emits when track starts.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> track_id</span><span class="z-comment"> track 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"> contract_address</span><span class="z-comment"> the address of tracking 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"> function_hash</span><span class="z-comment"> the hash of tracking function with params</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> onTrackEndRecorded</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> track_id</span><span>, </span><span class="z-support">address</span><span class="z-variable"> contract_address</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> function_hash</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Functions</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"> Track a specified contract function start move.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> track_id</span><span class="z-comment"> track 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"> contract_address</span><span class="z-comment"> the address of tracking 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"> function_hash</span><span class="z-comment"> the hash of tracking function with params</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> onTrackStart</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> track_id</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> contract_address</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> function_hash</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"> Track a specified contract function end move.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> track_id</span><span class="z-comment"> track 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"> contract_address</span><span class="z-comment"> the address of tracking 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"> function_hash</span><span class="z-comment"> the hash of tracking function with params</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> onTrackEnd</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> track_id</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> contract_address</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> function_hash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The core mechanism for this proposal is to provide a shared tracking interface for inter-dapp operations, to improve the efficiency and fulfill the required tracking business. We provide two interface functions <code>onTrackStart</code> and <code>onTrackEnd</code> to fill the basic required info and connect the necessary dots. Sure there're more demands for more functions and it would be updated later.</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> <!-- TODO: discuss more --> <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-11T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jeroen Offerijnshttps://github.com/hieronx Alina Sinelnikovahttps://github.com/ilinzweilin Vikram Arunhttps://github.com/vikramarun Joey Santorohttps://github.com/joeysantoro Farhaan Alihttps://github.com/0xfarhaan https://wg-eips.ritovision.com/7575/

Extended ERC-4626 Interface enabling Multi-Asset Vaults

<h2 id="abstract">Abstract</h2> <p>The following standard adapts <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> to support multiple assets or entry points for the same share token. This also enables Vaults which don't have a true share token but rather convert between two arbitrary external tokens.</p> <p>It adds a new <code>share</code> method to the Vault, to allow the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> dependency to be externalized.</p> <p>It also adds Vault-to-Share lookup to the share token.</p> <p>Lastly, it enforces <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> support for Vaults and the share token.</p> <h2 id="motivation">Motivation</h2> <p>One missing use case that is not supported by <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> is Vaults which have multiple assets or entry points such as liquidity provider (LP) Tokens. These are generally unwieldy or non-compliant due to the requirement of ERC-4626 to itself be an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>.</p> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions:</h3> <p>The existing definitions from <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> apply. In addition, this spec defines:</p> <ul> <li>Multi-Asset Vaults: A Vault which has multiple assets/entry points. The Multi-Asset Vault refers to the group of <a href="https://wg-eips.ritovision.com/7575/">ERC-7575</a> contracts with the entry points for a specific asset, linked to one common <code>share</code> token.</li> <li>Pipe: A converter from one token to another (unidirectional or bidirectional)</li> </ul> <h3 id="methods">Methods</h3> <p>All <a href="https://wg-eips.ritovision.com/7575/">ERC-7575</a> Vaults MUST implement <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> excluding the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> methods and events.</p> <h4 id="share">share</h4> <p>The address of the underlying <code>share</code> received on deposit into the Vault. MUST return an address of an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> share representation of the Vault.</p> <p><code>share</code> MAY return the address of the Vault itself.</p> <p>If the <code>share</code> returns an external token i.e. <code>share != address(this)</code>:</p> <ul> <li>entry functions MUST increase the <code>share</code> balance of the <code>receiver</code> by the <code>shares</code> amount. i.e. <code>share.balanceOf(receiver) += shares</code></li> <li>exit functions MUST decrease the <code>share</code> balance of the <code>owner</code> by the <code>shares</code> amount. i.e. <code>share.balanceOf(owner) -= shares</code></li> </ul> <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"> s</span><span class="z-string">hare</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 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">hareTokenAddress</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><h3 id="multi-asset-vaults">Multi-Asset Vaults</h3> <p>Multi-Asset Vaults share a single <code>share</code> token with multiple entry points denominated in different <code>asset</code> tokens.</p> <p>Multi-Asset Vaults MUST implement the <code>share</code> method on each entry point. The entry points SHOULD NOT be <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>.</p> <h3 id="pipes">Pipes</h3> <p>Pipes convert between a single <code>asset</code> and <code>share</code> which are both <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens outside the Vault.</p> <p>A Pipe MAY be either unidirectional or bidirectional.</p> <p>A unidirectional Pipe SHOULD implement only the entry function(s) <code>deposit</code> and/or <code>mint</code>, not <code>redeem</code> and/or <code>withdraw</code>.</p> <p>The entry points SHOULD lock or burn the <code>asset</code> from the <code>msg.sender</code> and mint or transfer the <code>share</code> to the <code>receiver</code>. For bidirectional pipes, the exit points SHOULD lock or burn the <code>share</code> from the <code>owner</code> and mint or transfer the <code>asset</code> to the <code>receiver</code>.</p> <h3 id="share-to-vault-lookup">Share-to-Vault lookup</h3> <p>The <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> implementation of <code>share</code> SHOULD implement a <code>vault</code> method, that returns the address of the Vault for a specific <code>asset</code>.</p> <p>SHOULD emit the <code>VaultUpdate</code> event when a Vault linked to the share changes.</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">ault</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 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">sset</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> <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">ault</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><h3 id="erc-165-support"><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> support</h3> <p>Vaults implementing <a href="https://wg-eips.ritovision.com/7575/">ERC-7575</a> MUST implement the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> <code>supportsInterface</code> function. The Vault contract MUST return the constant value <code>true</code> if <code>0x2f0a18c5</code> is passed through the <code>interfaceID</code> argument.</p> <p>The share contract SHOULD implement the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> <code>supportsInterface</code> function. The share token MUST return the constant value <code>true</code> if <code>0xf815c03d</code> is passed through the <code>interfaceID</code> argument.</p> <h3 id="events">Events</h3> <h4 id="vaultupdate">VaultUpdate</h4> <p>The Vault linked to the share has been updated.</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">aultUpdate</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"> a</span><span class="z-string">sset</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">ault</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></code></pre><h2 id="rationale">Rationale</h2> <p>This standard is intentionally flexible to support both existing <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> Vaults easily by the introduction of a single new method, but also flexible to support new use cases by allowing separate share tokens.</p> <h3 id="ability-to-externalize-erc-20-dependency">Ability to externalize <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> Dependency</h3> <p>By allowing <code>share != address(this)</code>, the Vault can have an external contract managing the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> functionality of the Share. In the case of Multi-Asset, this avoids the confusion that might arise if each Vault itself were required to be an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, which could confuse integrators and front-ends.</p> <p>This approach also enables the creation of new types of Vaults, such as Pipes, which facilitate the conversion between two external <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens. These Pipes could be unidirectional (i.e. only for assets to shares via deposit/mint, or shares to assets via redeem/withdraw) or bidirectional for both entry and exit flows.</p> <h3 id="including-share-to-vault-lookup-optionally">Including Share-to-Vault lookup optionally</h3> <p>The <code>vault</code> method is included to look up a Vault for a <code>share</code> by its <code>asset</code>, combined with the <code>VaultUpdate</code> event and <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> support. This enables integrations to easily query Multi-Asset Vaults.</p> <p>This is optional, to maintain backward compatibility with use cases where the <code>share</code> is an existing deployed contract.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><a href="https://wg-eips.ritovision.com/7575/">ERC-7575</a> Vaults are not fully compatible with <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> because the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> functionality has been removed.</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"> This code snippet is incomplete pseudocode used for example only and is no way intended to be used in production or guaranteed to be secure</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"> Share</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"> mapping</span><span> (</span><span class="z-support">address</span><span> asset </span><span class="z-keyword">=&gt;</span><span class="z-support"> address</span><span>)</span><span> vault</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"> updateVault</span><span>(</span><span class="z-support">address</span><span class="z-variable"> asset</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> vault_</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> vault</span><span>[</span><span>asset</span><span>]</span><span class="z-keyword"> =</span><span> vault_</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> UpdateVault</span><span>(</span><span>asset</span><span>,</span><span> vault_</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"> external</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">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-constant"> 0xf815c03d</span><span class="z-keyword"> ||</span><span> interfaceId </span><span class="z-keyword">==</span><span class="z-constant"> 0x01ffc9a7</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"> TokenAVault</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC7575</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> share </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span>Share</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> asset </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span>TokenA</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ERC4626 implementation</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"> pure</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-constant"> 0x2f0a18c5</span><span class="z-keyword"> ||</span><span> interfaceId </span><span class="z-keyword">==</span><span class="z-constant"> 0x01ffc9a7</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"> TokenBVault</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC7575</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> share </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span>Share</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> asset </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span>TokenB</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ERC4626 implementation</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"> pure</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-constant"> 0x2f0a18c5</span><span class="z-keyword"> ||</span><span> interfaceId </span><span class="z-keyword">==</span><span class="z-constant"> 0x01ffc9a7</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><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> non-compliant Vaults must take care with supporting a redeem flow where <code>owner</code> is not <code>msg.sender</code>, since the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> approval flow does not by itself work if the Vault and share are separate contracts. It can work by setting up the Vault as a Trusted Forwarder of the share token, using <a href="https://wg-eips.ritovision.com/2771/">ERC-2771</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-12-06T00:00:00+00:00 2026-02-11T14:48:25+00:00 Devin Finzerhttps://github.com/dfinzer Alex Atallahhttps://github.com/alexanderatallah Ryan Ghodshttps://github.com/ryanio https://wg-eips.ritovision.com/7572/

Specifying and updating contract-level metadata

<h2 id="abstract">Abstract</h2> <p>This specification standardizes <code>contractURI()</code> to return contract-level metadata. This is useful for dapps and offchain indexers to show rich information about a contract, such as its name, description and image, without specifying it manually or individually for each dapp.</p> <h2 id="motivation">Motivation</h2> <p>Dapps have included supported for <code>contractURI()</code> for years without an ERC to reference. This standard also introduces the event <code>ContractURIUpdated()</code> to signal when to update the metadata.</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 contract MUST implement the below 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"> IERC7572</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> contractURI</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-storage z-type"> event</span><span class="z-entity z-name"> ContractURIUpdated</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The string returned from <code>contractURI()</code> MAY be an offchain resource or onchain JSON data string (<code>data:application/json;utf8,{}</code>).</p> <p>The <code>ContractURIUpdated()</code> event SHOULD be emitted on updates to the contract metadata for offchain indexers to query the contract.</p> <p>If the underlying contract provides any methods that conflict with the <code>contractURI</code> schema such as <code>name()</code> or <code>symbol()</code>, the metadata returned by <code>contractURI()</code> is RECOMMENDED to take precedence. This enables contract creators to update their contract details with an event that notifies of the update.</p> <h3 id="schema-for-contracturi">Schema for contractURI</h3> <p>The schema for the JSON returned from <code>contractURI()</code> MUST conform to:</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 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">The name of the contract.</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">symbol</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 symbol of the contract.</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">The description of the contract.</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">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">A URI pointing to a resource with mime type image/* that represents the contract, typically displayed as a profile picture for the contract.</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">banner_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">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">A URI pointing to a resource with mime type image/* that represents the contract, displayed as a banner image for the contract.</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">featured_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">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">A URI pointing to a resource with mime type image/* that represents the featured image for the contract, typically used for a highlight section.</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">external_link</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">The external link of the contract.</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">collaborators</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">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">An Ethereum address representing an authorized editor of the contract.</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">An array of Ethereum addresses representing collaborators (authorized editors) of the 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></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 class="giallo-l"><span>}</span></span></code></pre> <p>Example:</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 Contract</span><span class="z-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">EC</span><span class="z-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">Your description here</span><span class="z-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://QmTNgv3jx2HHfBjQX9RnKtxj2xv2xQCtbDXoRi5rJ3a46e</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">banner_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://QmdChMVnMSq4U7oVKhud7wUSEZGnwuMuTY5rUQx57Ayp6H</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">featured_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://QmS9m6e1E1NfioMM8dy1WMZNN2FRh2WDjeqJFWextqXCT8</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">external_link</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://project-website.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">collaborators</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">0x388C818CA8B9251b393131C08a736A67ccB19297</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Future ERCs MAY inherit this one to add more properties to the schema for standardization.</p> <h2 id="rationale">Rationale</h2> <p>The method name <code>contractURI()</code> was chosen based on its existing implementation in dapps. The event <code>ContractURIUpdated()</code> is specified to help offchain indexers to know when to refetch the metadata.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As a new ERC, no backwards compatibility issues are present.</p> <h2 id="reference-implementation">Reference 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"> MyCollectible</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">IERCXXXX</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> _contractURI </span><span class="z-keyword">=</span><span class="z-string"> &quot;ipfs://QmTNgv3jx2HHfBjQX9RnKtxj2xv2xQDtbVXoRi5rJ3a46e&quot;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> or e.g. &quot;https://external-link-url.com/my-contract-metadata.json&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"> contractURI</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> _contractURI</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> or e.g. for onchain:</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span> json </span><span class="z-keyword">=</span><span class="z-string"> &#39;{&quot;name&quot;: &quot;Creatures&quot;,&quot;description&quot;:&quot;...&quot;}&#39;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> string</span><span>.</span><span class="z-entity z-name">concat</span><span>(</span><span class="z-string">&quot;data:application/json;utf8,&quot;</span><span>,</span><span> json</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"> Suggested setter, not explicitly specified as part of this ERC</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setContractURI</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> newURI</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> _contractURI </span><span class="z-keyword">=</span><span> newURI</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ContractURIUpdated</span><span>(</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>Addresses specified as <code>collaborators</code> should be expected to receive admin-level functionality for updating contract information on dapps that implement 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> 2023-12-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 Christian Frieshttps://github.com/cfries Peter Kohl-Landgrafhttps://github.com/pekola https://wg-eips.ritovision.com/7573/

A Protocol for Secure Delivery-versus-Payment across two Blockchains

<h2 id="abstract">Abstract</h2> <p>The interfaces in this proposal model a functional transaction scheme to establish a secure <em>delivery-versus-payment</em> across two blockchains, where a) no intermediary is required and b) one of the two chains can securely interact with a stateless "decryption oracle". Here, <em>delivery-versus-payment</em> refers to the exchange of, e.g., an asset against a payment; however, the concept is generic to make a transfer of one token on one chain (e.g., the payment) conditional to the successful transfer of another token on another chain (e.g., the asset).</p> <p>The scheme is realized by two smart contracts, one on each chain. One smart contract implements the <code>ILockingContract</code> interface on one chain (e.g. the "asset chain"), and another smart contract implements the <code>IDecryptionContract</code> interface on the other chain (e.g., the "payment chain"). The smart contract implementing <code>ILockingContract</code> locks a token (e.g., the asset) on its chain until a key is presented to encrypt to one of two given values. The smart contract implementing <code>IDecryptionContract</code>, decrypts one of two keys (via the decryption oracle) conditional to the success or failure of the token transfer (e.g., the payment). A stateless decryption oracle is attached to the chain running <code>IDecryptionContract</code> for the decryption.</p> <p>In addition, there are two interfaces that standardize the communication with external decryption oracle(s):</p> <ul> <li><code>IKeyDecryptionOracle.sol</code> is implemented by a decryption oracle proxy contract (on-chain router/proxy for an off-chain oracle).</li> <li><code>IKeyDecryptionOracleCallback.sol</code> is implemented by a callback receiving the decrypted key (or derived verification material).</li> </ul> <p><strong>Fulfillment semantics note:</strong> The oracle proxy may implement either (i) <strong>strict fulfillment</strong> (reverting <code>fulfill*</code> when the callback fails) or (ii) <strong>best-effort fulfillment</strong> (not reverting <code>fulfill*</code> on callback failure, but signaling failure via events). This proposal describes both modes and their operational trade-offs.</p> <h2 id="motivation">Motivation</h2> <p>Within the domain of financial transactions and distributed ledger technology (DLT), the Hash-Linked Contract (HLC) concept has been recognized as valuable and has been thoroughly investigated. The concept may help to solve the challenge of delivery-versus-payment (DvP), especially in cases where the asset chain and payment system (which may be a chain, too) are separated. A prominent application of smart contracts realizing a secure DvP is that of buying an asset, where the asset is managed on one chain (the asset chain), but the payments are executed on another chain (the payment chain). Proposed solutions are based on an API-based interaction mechanism which bridges the communication between a so-called asset chain and a corresponding payment system or requires complex and problematic time locks.<sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">1</a></sup></p> <p>Here, we propose a protocol that facilitates secure delivery-versus-payment with less overhead, especially with a stateless oracle.[^2]</p> <h2 id="specification">Specification</h2> <h3 id="methods">Methods</h3> <h4 id="smart-contract-on-the-chain-that-performs-the-locking-e-g-the-asset-chain">Smart Contract on the chain that performs the locking (e.g. the asset chain)</h4> <p>The following methods specify the functionality of the smart contract implementing the locking. For further information, please also look at the interface documentation <a href="https://wg-eips.ritovision.com/7573/./assets/contracts/ILockingContract.sol"><code>ILockingContract.sol</code></a>.</p> <h5 id="initiation-of-transfer-incepttransfer">Initiation of Transfer: <code>inceptTransfer</code></h5> <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"> inceptTransfer</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> int</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> bytes</span><span class="z-variable"> keyHashedSeller</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedSeller</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Called from the buyer of the token to initiate token transfer. Emits a <code>TransferIncepted</code> event. The parameter <code>id</code> is an identifier of the trade. The parameter <code>from</code> is the address of the seller (the address of the buyer is <code>msg.sender</code>). The parameter <code>keyHashedSeller</code> is a hash of the key that can be used by the seller to (re-)claim the token. The parameter <code>keyEncryptedSeller</code> is an encryption of the key that can be used by the buyer to claim the token. It is possible to implement the protocol in a way where the hashing method agrees with the encryption method. See below on "encryption".</p> <h5 id="initiation-of-transfer-confirmtransfer">Initiation of Transfer: <code>confirmTransfer</code></h5> <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"> confirmTransfer</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> int</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> bytes</span><span class="z-variable"> keyHashedBuyer</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedBuyer</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Called from the seller of the token to confirm token transfer. Emits a <code>TransferConfirmed</code> event. The parameter <code>id</code> is an identifier of the trade. The parameter <code>to</code> is the address of the buyer (the address of the seller is <code>msg.sender</code>). The parameter <code>keyHashedBuyer</code> is a hash of the key that can be used by the buyer to (re-)claim the token. The parameter <code>keyEncryptedBuyer</code> is an encryption of the key that can be used by the buyer to (re-)claim the token. It is possibly to implement the protocol in a way where the hashing method agrees with the encryption method. See below on "encryption".</p> <p>If the trade specification, that is, the quadruple (<code>id</code>, <code>amount</code>, <code>from</code>, <code>to</code>), in a call to <code>confirmTransfer</code> matches that of a previous call to <code>inceptTransfer</code>, and the balance is sufficient, the corresponding <code>amount</code> of tokens is locked (transferred from <code>from</code> to the smart contract) and <code>TransferConfirmed</code> is emitted.</p> <h5 id="transfer-transferwithkey">Transfer: <code>transferWithKey</code></h5> <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"> transferWithKey</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> key</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Called from either the buyer or the seller of the token of the trade with id <code>id</code>.</p> <p>If the method is called from the buyer (<code>to</code>) <em>and</em> the hashing of <code>key</code> matches <code>keyHashedBuyer</code>, then the locked tokens are transferred to the buyer (<code>to</code>). This emits <code>TokenClaimed</code>.</p> <p>If the method is called from the seller (<code>from</code>) <em>and</em> the hashing of <code>key</code> matches <code>keyHashedSeller</code>, then the locked tokens are transferred (back) to the seller (<code>to</code>). This emits <code>TokenReclaimed</code>.</p> <h5 id="summary">Summary</h5> <p>The interface <code>ILockingContract</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"> ILockingContract</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferIncepted</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>, </span><span class="z-support">int</span><span class="z-variable"> amount</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">bytes</span><span class="z-variable"> keyHashedSeller</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> keyEncryptedSeller</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferConfirmed</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>, </span><span class="z-support">int</span><span class="z-variable"> amount</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">bytes</span><span class="z-variable"> keyHashedBuyer</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> keyEncryptedBuyer</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenClaimed</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> key</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenReclaimed</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> key</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"> inceptTransfer</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> int</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyHashedSeller</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedSeller</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"> confirmTransfer</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> int</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyHashedBuyer</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedBuyer</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"> transferWithKey</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> key</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="smart-contract-on-the-other-chain-that-performs-the-conditional-decryption-e-g-the-payment-chain">Smart Contract on the other chain that performs the conditional decryption (e.g. the payment chain)</h4> <p>The following methods specify the functionality of the smart contract implementing the conditional decryption. For further information, please also look at the interface documentation <a href="https://wg-eips.ritovision.com/7573/./assets/contracts/IDecryptionContract.sol"><code>IDecryptionContract.sol</code></a>.</p> <h5 id="initiation-of-transfer-incepttransfer-1">Initiation of Transfer: <code>inceptTransfer</code></h5> <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"> inceptTransfer</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> int</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedSuccess</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedFailure</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Called from the receiver of the amount to initiate payment transfer. Emits a <code>TransferIncepted</code>. The parameter <code>id</code> is an identifier of the trade. The parameter <code>from</code> is the address of the sender of the payment (the address of the receiver is <code>msg.sender</code>). The parameter <code>keyEncryptedSuccess</code> is an encryption of a key and will be decrypted if the transfer is successful in a call to <code>transferAndDecrypt</code>. The parameter <code>keyEncryptedFailure</code> is an encryption of a key and will be decrypted if the transfer fails in a call to <code>transferAndDecrypt</code> or if <code>cancelAndDecrypt</code> is successful.</p> <h5 id="transfer-transferanddecrypt">Transfer: <code>transferAndDecrypt</code></h5> <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"> transferAndDecrypt</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> int</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedSuccess</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedFailure</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Called from the sender of the amount to initiate completion of the payment transfer. Emits a <code>TransferKeyRequested</code> with keys depending on completion success. The parameter <code>id</code> is an identifier of the trade. The parameter <code>to</code> is the address of the receiver of the payment (the sender of the payment (from) is implicitly the <code>msg.sender</code>). The parameter <code>keyEncryptedSuccess</code> is an encryption of the key and will be decrypted if the transfer is successful. The parameter <code>keyEncryptedFailure</code> is an encryption of the key and will be decrypted if the transfer fails.</p> <p>The method will not decrypt any key and not perform a transfer of a payment if the values (<code>id</code>, <code>amount</code>, <code>from</code> <code>to</code>, <code>keyEncryptedSuccess</code>, <code>keyEncryptedFailure</code>) do not match a previous call to <code>inceptTransfer</code>.</p> <h5 id="cancelation-of-transfer-cancelanddecrypt">Cancelation of Transfer: <code>cancelAndDecrypt</code></h5> <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"> cancelAndDecrypt</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"> from</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedSuccess</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedFailure</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Called from the receiver of the amount to cancel payment transfer (cancels the incept transfer).</p> <p>The method must be called from the caller of a previous call to <code>inceptTransfer</code> with the exact same arguments and cancels this specific transfer. If these preconditions are met and a valid call to <code>transferAndDecrypt</code> has not been issued before, i.e. if <code>keyEncryptedSuccess</code> has not been issued in a <code>TransferKeyRequested</code> event, then this method emits a <code>TransferKeyRequested</code> with the key <code>keyEncryptedFailure</code>.</p> <h5 id="release-of-ilockingcontract-access-key-releasekey">Release of ILockingContract Access Key: <code>releaseKey</code></h5> <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"> releaseKey</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> key</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Called from the (possibly external) decryption oracle.</p> <p>Emits the event <code>TransferKeyReleased</code> with the value of <code>key</code> if the call was eligible.</p> <h5 id="summary-1">Summary</h5> <p>The interface <code>IDecryptionContract</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"> IDecryptionContract</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferIncepted</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>, </span><span class="z-support">int</span><span class="z-variable"> amount</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">bytes</span><span class="z-variable"> keyEncryptedSuccess</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> keyEncryptedFailure</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferKeyRequested</span><span>(</span><span class="z-support">address</span><span class="z-variable"> sender</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> encryptedKey</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferKeyReleased</span><span>(</span><span class="z-support">address</span><span class="z-variable"> sender</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> id</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-variable"> key</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"> inceptTransfer</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> int</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedSuccess</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedFailure</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"> transferAndDecrypt</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> int</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedSuccess</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedFailure</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"> cancelAndDecrypt</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"> from</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedSuccess</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> keyEncryptedFailure</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"> releaseKey</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> key</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="interfaces-to-external-decryption-oracles-oracle-proxy-callback">Interfaces to External Decryption Oracles (Oracle Proxy + Callback)</h3> <p>This proposal additionally standardizes the on-chain interaction with external (off-chain) decryption oracles via:</p> <ul> <li><code>IKeyDecryptionOracle</code> (oracle proxy / router)</li> <li><code>IKeyDecryptionOracleCallback</code> (consumer callback)</li> </ul> <p>The general flow is:</p> <ol> <li>The consumer calls <code>request*</code> on the oracle proxy contract (payable).</li> <li>The oracle proxy emits a request event containing a <code>requestId</code> (correlation id).</li> <li>The off-chain oracle observes the request event, performs decryption or verification off-chain, and calls <code>fulfill*</code> on the proxy.</li> <li>The oracle proxy calls the consumer callback <code>on*</code> with the fulfillment payload.</li> </ol> <h4 id="callback-execution-semantics-strict-vs-best-effort">Callback execution semantics: strict vs best-effort</h4> <p>Implementations MAY choose one of the following fulfillment semantics. Both are compatible with this proposal.</p> <h5 id="strict-fulfillment-reverting">Strict fulfillment (reverting)</h5> <p>In <strong>strict fulfillment</strong>, the proxy MUST revert <code>fulfill*</code> if the callback call fails (including OOG).</p> <p>Properties:</p> <ul> <li>The off-chain oracle operator can treat <code>receipt.status == 1</code> as “callback succeeded”.</li> <li>If <code>receipt.status == 0</code>, the request is not fulfilled and can be retried (e.g., with higher tx gas limit).</li> <li>The proxy MUST ensure that request state is not lost on revert (e.g., by relying on revert rollback of state changes).</li> </ul> <p>This mode is operationally simple for closed deployments where the off-chain oracle and the consumer are coordinated and where failure handling/retries are primarily managed by the oracle operator.</p> <h5 id="best-effort-fulfillment-non-reverting">Best-effort fulfillment (non-reverting)</h5> <p>In <strong>best-effort fulfillment</strong>, the proxy MUST NOT revert <code>fulfill*</code> solely because the callback call fails (including OOG). Instead, it SHOULD signal callback outcome via events (e.g. <code>CallbackSucceeded</code> / <code>CallbackFailed</code>).</p> <p>Properties:</p> <ul> <li>The off-chain oracle operator MUST NOT interpret <code>receipt.status == 1</code> as “callback succeeded”; it must also evaluate the emitted outcome signal.</li> <li>Failure handling can be shifted to the callback implementer/operator: a consumer can run an off-chain watcher that subscribes to <code>CallbackFailed</code> and reacts accordingly (e.g. pull/consume flow, re-request, alerting).</li> <li>The proxy may either keep the request pending for retries or consume it and shift retry responsibility to the consumer. The chosen policy SHOULD be documented by the implementation.</li> </ul> <p>This mode is useful when the proxy wants to provide an on-chain observable audit trail for callback failures and to decouple “oracle fulfillment” from “consumer processing”.</p> <h4 id="gas-budgeting-and-forwarding">Gas budgeting and forwarding</h4> <ul> <li>The off-chain oracle controls the total cost of <code>fulfill*</code> by setting the transaction gas limit.</li> <li>The proxy MAY cap or budget the gas forwarded to the callback (e.g., by forwarding “all but a reserve”).</li> <li>Keeping a small gas reserve in the proxy can help ensure the proxy can finalize <code>fulfill*</code> and emit outcome events even if the callback consumes most forwarded gas.</li> </ul> <h4 id="calldata-fallback-retrieving-fulfillment-payload-without-logging">Calldata fallback (retrieving fulfillment payload without logging)</h4> <p>In either strict or best-effort mode, the <code>fulfill*</code> payload is present in the transaction input calldata of the <code>fulfill*</code> call.</p> <p>Implementations SHOULD document the following operational fallback:</p> <ul> <li>Off-chain systems that observe an event (e.g., <code>CallbackFailed</code>) can use the event’s <code>transactionHash</code> to fetch the corresponding transaction and decode the input calldata using the <code>IKeyDecryptionOracle</code> ABI to recover the fulfillment arguments.</li> <li>Practical caveat: Some RPC providers prune old transaction bodies; indexers SHOULD persist decoded fulfillment payload off-chain if long-term retention is required.</li> </ul> <p>This fallback can be used to support consumer-side “pull/consume” flows, or as a recovery mechanism when callback execution fails.</p> <h3 id="encryption-and-decryption">Encryption and Decryption</h3> <p>The linkage of the two smart contracts relies on use of a <code>key</code>, <code>encryptedKey</code> and <code>hashedKey</code>. The implementation is free to support several encryption methods for as long as the decryption oracle supports it.</p> <p>The encryption is performed with the public key of the decryption oracle. Either the encryption oracle offers a method performing encryption, in which case the encryption method isn't even required to be known, or both parties know the public key of the decryption oracle and can perform the generation of the key and its encryption.</p> <p>It is implicitly assumed that the two parties may check that the strings <code>keyEncryptedBuyer</code> and <code>keyEncryptedSeller</code> are in a valid format.</p> <p>To avoid on-chain encryption in the <code>ILockingContract</code>, it is possible to use a simpler hashing algorithm on the <code>ILockingContract</code>. In that case, the decryption oracle has to provide a method that allows to obtain the hash <em>H(K)</em> (<code>keyHashed</code>) for an encrypted key <em>E(K)</em> (<code>keyEncrypted</code>) without exposing the key <em>K</em> (`<code>key\</code>), cf. [^2].</p> <h3 id="sequence-diagram-of-delivery-versus-payment">Sequence diagram of delivery versus payment</h3> <p>The interplay of the two smart contracts is summarized in the following sequence diagram:</p> <p><img src="https://wg-eips.ritovision.com/7573/./assets/doc/DvP-Seq-Diag.png" alt="sequence diagram dvp" /></p> <h2 id="rationale">Rationale</h2> <p>The protocol tries to be parsimonious. The transfer is associated with a (preferably unique) <code>id</code> possibly generated by some additional interaction of the trading parties.</p> <p>The <code>key</code> and the <code>encryptedKey</code> arguments are strings to allow the flexible use of different encryption schemes. The decryption/encryption scheme should be inferable from the contents of the <code>encryptedKey</code>.</p> <h3 id="ensuring-secure-key-decryption-key-format">Ensuring Secure Key Decryption - Key Format</h3> <p>It has to be ensured that the decryption oracle decrypts a key only for the eligible contract.</p> <p>It seems as if this would require us to introduce a concept of eligibility to the description oracle, which would imply a kind of state.</p> <p>A fully stateless decryption can be realized by introducing a document format for the key and a corresponding eligibility verification protocol. We propose the following elements:</p> <ul> <li>The (unencrypted) key documents contain the address of the payment contract implementing <code>IDecryptionContract</code>.</li> <li>The decryption oracle offers a stateless function <code>verify</code> that receives an encrypted key and returns the callback address (that will be used for the <code>releaseKey</code> call) that is stored inside the decrypted key without returning the decrypted key.</li> <li>When an encrypted key is presented to the decryption oracle, the oracle decrypts the document and passes the decrypted key to <code>releaseKey</code> of the callback contract address found within the document decrypted key.</li> </ul> <p>We propose the following XML schema for the document of the decrypted key:</p> <pre class="giallo z-code"><code data-lang="xml"><span class="giallo-l"><span>&lt;?</span><span class="z-entity z-name z-tag">xml</span><span class="z-entity"> version</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 class="z-entity"> encoding</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">utf-8</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">xs</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">schema</span><span class="z-entity"> attributeFormDefault</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">unqualified</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> elementFormDefault</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">qualified</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> targetNamespace</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">http://finnmath.net/erc/ILockingContract</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> xmlns</span><span class="z-entity">:</span><span class="z-entity">xs</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">http://www.w3.org/2001/XMLSchema</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">xs</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">element</span><span class="z-entity"> name</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">releaseKey</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">xs</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">complexType</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">xs</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">simpleContent</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">xs</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">extension</span><span class="z-entity"> base</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">xs:string</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">xs</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">attribute</span><span class="z-entity"> name</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">contract</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">xs:string</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> use</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">required</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">xs</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">attribute</span><span class="z-entity"> name</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">transaction</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">xs:unsignedShort</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> use</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">required</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">xs</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">extension</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;/</span><span class="z-entity z-name z-tag">xs</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">simpleContent</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;/</span><span class="z-entity z-name z-tag">xs</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">complexType</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;/</span><span class="z-entity z-name z-tag">xs</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">element</span><span>&gt;</span></span> <span class="giallo-l"><span>&lt;/</span><span class="z-entity z-name z-tag">xs</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">schema</span><span>&gt;</span></span></code></pre> <p>A corresponding XML sample is shown below.</p> <pre class="giallo z-code"><code data-lang="xml"><span class="giallo-l"><span>&lt;?</span><span class="z-entity z-name z-tag">xml</span><span class="z-entity"> version</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 class="z-entity"> encoding</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">UTF-8</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> standalone</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">yes</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">releaseKey</span><span class="z-entity"> contract</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eip155:1:0x1234567890abcdef1234567890abcdef12345678</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> transaction</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">3141</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> xmlns</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">http://finnmath.net/erc/ILockingContract</span><span class="z-punctuation z-definition z-string">&quot;</span><span>&gt;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> &lt;!--</span><span class="z-comment"> random data </span><span class="z-punctuation z-definition z-comment">--&gt;</span></span> <span class="giallo-l"><span> zZsnePj9ZLPkelpSKUUcg93VGNOPC2oBwX1oCcVwa+U=</span></span> <span class="giallo-l"><span>&lt;/</span><span class="z-entity z-name z-tag">releaseKey</span><span>&gt;</span></span></code></pre><h3 id="multi-party-delivery-versus-payment">Multi-Party Delivery versus Payment</h3> <h4 id="locking-is-a-feature">Locking is a Feature</h4> <p>In Delivery-versus-Payment (DvP) protocols like <a href="https://wg-eips.ritovision.com/7573/">ERC-7573</a>, at least one token must be locked to ensure atomicity, even if only for a short period during the transaction.</p> <p>While locking may appear as an inconvenient necessity, it is in fact a feature that becomes valuable in the construction of conditional trades or multi-party DvPs.</p> <p>If <em>n</em> parties wish to perform bilateral transactions atomically, there are <em>at least</em> <em>m := 2 • (n - 1)</em> transactions, of which <em>m-1</em> require locking. The last one can operate directly, and its success or failure decides whether the other locks are released or reverted.</p> <p>A multi-party delivery versus payment is a valuable trade feature. Consider, for example, the case where counterparty A wishes to buy a token <em>Y</em> (e.g., a bond) from counterparty C, but in order to fund this transaction, counterparty A wishes to sell a token <em>X</em> (e.g., another bond) to counterparty B. However, A does not want to sell bond <em>X</em> if the purchase of <em>Y</em> fails. A multi-party DvP allows these two transactions to be bound into a single atomic unit.</p> <p>While for a two-party DvP with two tokens only one token requires locking—and hence a DvP can be constructed without locking on the cash chain—a three-party DvP with three tokens in general requires the ability to lock all three tokens.</p> <p>This highlights that locking is not just a constraint, but a required feature to enable advanced and economically meaningful protocols.</p> <h4 id="n-dvp-with-erc-7573">N-DvP with <a href="https://wg-eips.ritovision.com/7573/">ERC-7573</a></h4> <p>A multi-party DvP can be created elegantly by combining multiple (<em>n-1</em>) two-party DvPs, for example based on the <a href="https://wg-eips.ritovision.com/7573/">ERC-7573</a> protocol.</p> <p>The procedure is simple: instead of finalizing the respective two-party DvP by a call to <code>transferAndDecrypt</code>, the two-party DvP is first confirmed with a call to <code>confirm</code>, leaving the finalization open.</p> <p>At any time, any party can call <code>cancelAndDecrypt</code> to release the failure key and revert all lockings.</p> <p>Once all parties are linked with their respective two-party DvPs, a single call to <code>transferAndDecrypt</code> performs locking of the token implementing the <code>IDecryptionContract</code> and releases either the success key on success or the failure key on failure.</p> <h5 id="initiation-and-finalization">Initiation and Finalization</h5> <p>The counterparty that initiates the multi-party DvP by making the first call to the <code>IDecryptionContract</code> is the one that is allowed to finalize it via <code>transferAndDecrypt</code>, the other may cancel via <code>cancelAndDecrypt</code>.</p> <h5 id="sequence-diagram">Sequence Diagram</h5> <p>Below we depict the corresponding sequence diagram of a multi-party DvP via <a href="https://wg-eips.ritovision.com/7573/">ERC-7573</a>. Note that the individual DvP may come in two different flavors depending on which counterparty is the receiver of the token on the <code>IDecryptionContract</code>.</p> <p>The diagram depicts a multi-party dvp with n+1 counterparties trading n+1 tokens out of which the DvPs are bound by the contract on token 0.</p> <p><img src="https://wg-eips.ritovision.com/7573/./assets/doc/multi-party-dvp.svg" alt="sequence diagram multi party dvp" /></p> <p><em>Note: The more general case of N counterparties trading M tokens is just a special case where we enumerate all combination as new counterparties and new tokens.</em></p> <h2 id="security-considerations">Security Considerations</h2> <p>The decryption oracle does not need to be a single trusted entity. Instead, a threshold decryption scheme can be employed, where multiple oracles perform partial decryption, requiring a quorum of them to reconstruct the secret key. This enhances security by mitigating the risk associated with a single point of failure or trust.</p> <p>In such cases, each participating decryption oracle will observe the decryption request from an emitted <code>TransferKeyRequested</code> event, and subsequently call the <code>releaseKey</code> method with a partial decryption result. The following sequence diagram illustrates this.</p> <p><img src="https://wg-eips.ritovision.com/7573/./assets/doc/Distributed-Oracle.png" alt="sequence diagram distributed oracle" /></p> <p>See [^2] for details.</p> <p>Additional considerations for the oracle proxy + callback pattern:</p> <ul> <li>Callback implementations SHOULD restrict callers (e.g. <code>require(msg.sender == oracleProxy)</code>), otherwise any address could invoke <code>on*</code> directly.</li> <li>Callback implementations SHOULD be cheap and should avoid unbounded loops or expensive state changes. If heavy work is required, prefer a pull/consume pattern initiated by the consumer.</li> <li>Oracle proxy implementations SHOULD document whether they use strict or best-effort fulfillment semantics, and how retries are intended to be handled (oracle-operated retry vs consumer-operated recovery).</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> <section class="footnotes"> <ol class="footnotes-list"> <li id="fn-1"> <p>La Rocca, R., Mancini, R., Benedetti, M., Caruso, M., Cossu, S., Galano, G., Mancini, S., Marcelli, G., Martella, P., Nardelli, M., &amp; Oliviero, C. (n.d.). <span style="font-style: italic;">Integrating DLTs with Market Infrastructures: Analysis and Proof-of-Concept for Secure DvP between TIPS and DLT Platforms</span>. https://doi.org/<a href="https://doi.org/10.2139/ssrn.4386904">10.2139/ssrn.4386904</a> (Original work published 2022)[^2]: Fries, C., &amp; Kohl-Landgraf, P. (n.d.). <span style="font-style: italic;">A Proposal for a Lean and Functional Delivery versus Payment across two Blockchains</span>. https://doi.org/<a href="https://doi.org/10.2139/ssrn.4628811">10.2139/ssrn.4628811</a> (Original work published 2023) <a href="#fr-1-1">↩</a></p> </li> </ol> </section> 2023-11-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Rickeyhttps://github.com/HelloRickey https://wg-eips.ritovision.com/7566/

A communication channel that facilitates interaction between players in on-chain games.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a multiplayer game communication (MGC) interface, using <code>room</code> to match and group players, and using <code>message</code> to process actions between players. This allows one smart contract to handle multiple players playing games on the chain, preventing centralized servers from affecting the fairness of the game.</p> <h2 id="motivation">Motivation</h2> <p>Common multiplayer games are generally played on centralized servers. Players have no way of knowing whether there are forged data and cheating on the server. The owner of the game server can match players at will, modify scores and levels, and even close and pause the game. If the player's actions all occur on the chain, every message from the chain is proof of the player's instructions and actions, which further ensures the fairness of the game. The Multiplayer Game Communication framework scales vertically by adding rooms to handle and accommodate multiple players. Write on-chain game logic with custom messages for horizontal expansion, allowing game developers to build multiplayer and fully on-chain games with smart contracts.<br /> Advantages of using this standard include:</p> <ul> <li>All parties can provide comprehensive game data query services based on standard interfaces and verify the fairness of the game.</li> <li>It has a basic grouping and messaging architecture, which reduces complexity and allows developers to focus on the development of the core logic of the game.</li> <li>It is more composable, and developers can decompose a large game into several contracts that implement the standard.</li> <li>Messages have one-to-many and customized capabilities, which is more conducive to developers to expand for different games.</li> <li>The room adopts a hierarchical data structure, and each member will be assigned a new ID in each room to facilitate developers to manage the player's state.</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>The principle of Multiplayer Game Communication is to use the same game logic to change the state of different groups of players.</p> <p>It consists of two core parts:</p> <p><strong>Room</strong>: A container for players, used to match and view connected players. The game can only be played after players join the room.</p> <p><strong>Message</strong>: Actions between players, using messages to perform game behaviors and change the player's state in the room.</p> <p><img src="https://wg-eips.ritovision.com/7566/./assets/MOGFlowChart.png" alt="Multiplayer Game Communication Workflow" /></p> <h3 id="interfaces">Interfaces</h3> <h4 id="imog-sol"><code>IMOG.sol</code></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"> &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"> &quot;./Types.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"> IMOG</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * Create a new room.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The entity MUST be assigned a unique 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"> New</span><span class="z-comment"> room 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"> createRoom</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">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"> * Get the total number of rooms that have been created.</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"> Total</span><span class="z-comment"> number of rooms.</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"> getRoomCount</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"> * Player joins room.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The member MUST be assigned a unique 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"> _roomId</span><span class="z-comment"> is the id of the room.</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"> Member</span><span class="z-comment"> 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"> joinRoom</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _roomId</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> <span class="giallo-l"><span class="z-comment"> * Get the id of a member in a room.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _roomId</span><span class="z-comment"> is the id of the room.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _member</span><span class="z-comment"> is the address of a member.</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"> Member</span><span class="z-comment"> 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"> getMemberId</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _roomId</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _member</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> <span class="giallo-l"><span class="z-comment"> * Check if a member exists in the room.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _roomId</span><span class="z-comment"> is the id of the room.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _member</span><span class="z-comment"> is the address of a member.</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"> exists, false 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"> hasMember</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _roomId</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _member</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> <span class="giallo-l"><span class="z-comment"> * Get all room IDs joined by a member.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _member</span><span class="z-comment"> is the address of a member.</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"> array of room ids.</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"> getRoomIds</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _member</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 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-comment"> * Get the total number of members in a room.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _roomId</span><span class="z-comment"> is the id of the room.</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"> Total</span><span class="z-comment"> members.</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"> getMemberCount</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _roomId</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"> * A member sends a message to other members.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Define your game logic here and use the content in the message to handle the member&#39;s state. The message MUST be assigned a unique 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"> _roomId</span><span class="z-comment"> is the id of the room.</span></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"> is an array of other member ids.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _message</span><span class="z-comment"> is the content of the message, encoded by abi.encode.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _messageTypes</span><span class="z-comment"> is data type array of message content.</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"> Message</span><span class="z-comment"> 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"> sendMessage</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _roomId</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 z-parameter z-function"> _to</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 z-parameter z-function"> _message</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> Types</span><span>.</span><span class="z-support z-variable">Type</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _messageTypes</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">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"> * Get all messages received by a member in the room.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _roomId</span><span class="z-comment"> is the id of the room.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _memberId</span><span class="z-comment"> is the id of the member.</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"> array of message ids.</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"> getMessageIds</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _roomId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _memberId</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 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-comment"> * Get details of a message.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _roomId</span><span class="z-comment"> is the id of the room.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _messageId</span><span class="z-comment"> is the id of the message.</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"> content of the message.</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"> Data</span><span class="z-comment"> type array of message content.</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"> Sender</span><span class="z-comment"> 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"> An</span><span class="z-comment"> array of receiver ids.</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"> getMessage</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _roomId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _messageId</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> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> Types</span><span>.</span><span class="z-support z-variable">Type</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</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> <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></code></pre><h3 id="library">Library</h3> <p>The library <a href="https://wg-eips.ritovision.com/7566/./assets/Types.sol"><code>Types.sol</code></a> contains an enumeration of Solidity types used in the above interfaces.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-are-multiplayer-onchain-games-room-based">Why are multiplayer onchain games room-based?</h3> <p>Because the rooms are independent, each player will be assigned a new ID when entering a room. A new game round can be a room, a game task can be a room, and a game activity can be a room.</p> <h3 id="the-player-s-state-in-the-game">The player's state in the game.</h3> <p>The game state refers to the player's data changes in the game, and <code>sendMessage</code> actually plays the role of a state converter. The proposal is very flexible, you can define some data inside the room (internal) or outside the room (global) according to the game logic.</p> <h3 id="how-to-initialize-player-data">How to initialize player data?</h3> <p>You can initialize player data in <code>createRoom</code> or <code>joinRoom</code>.</p> <h3 id="how-to-check-and-handle-player-exits-from-the-game">How to check and handle player exits from the game?</h3> <p>You can use <code>block.timestamp</code> or <code>block.number</code> to record the latest <code>sendMessage</code> time of a member. And add a message type to <code>sendMessage</code>. Other players can use this message type to complain that a member is offline and punish the member.</p> <h3 id="appropriate-game-categories">Appropriate game categories.</h3> <p>This is a multiplayer on-chain game rather than a multiplayer real-time game standard. The game category depends on the network your contract is deployed on. Some layer 2 networks process blocks very quickly and can make some more real-time games. Generally, the network is more suitable for strategy, trading card, turn-based, chess, sandbox, and settlement.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/7566/./assets/MultiplayerOnchainGame.sol">Multiplayer Game Communication Example</a></p> <h2 id="security-considerations">Security Considerations</h2> <!-- TODO: Needs discussion. --> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-11-27T00:00:00+00:00 2026-02-11T14:48:26+00:00 Hyoungsung Kimhttps://github.com/HyoungsungKimhyougnsung@keti.re.kr Yong-Suk Parkyspark@keti.re.kr Hyun-Sik Kimhskim@keti.re.kr https://wg-eips.ritovision.com/7565/

Lock financial assets as NFTs and use them as collateral for borrowing funds in DeFi, facilitating liquidity provision.

<h2 id="abstract">Abstract</h2> <p>This ERC proposes a mechanism where a person (referred to as the "Asset Owner") can collateralize NFTs that represent locked deposits or assets, to borrow funds against them. These NFTs represent the right to claim the underlying assets, along with any accrued benefits, after a predefined maturity period. <sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">1</a></sup></p> <p>The rapidly evolving landscape of DeFi has introduced various mechanisms for asset locking, offering benefits like interest and voting rights. However, one of the significant challenges in this space is maintaining liquidity while these assets are locked. This ERC addresses this challenge by proposing a method to generate profit from locked assets using <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/4907/">ERC-4907</a>.</p> <p>In DeFi services, running Automated Market Maker (AMM), liquidity providers contribute assets to pools and receive NFTs representing their stake. These NFTs denote the rights to the assets and the associated benefits, but they also lock the assets in the pool, often causing liquidity challenges for the providers. The current practice requires providers to withdraw their assets for urgent liquidity needs, adversely affecting the pool's liquidity and potentially increasing slippage during asset swaps.</p> <p>Our proposal allows these NFTs, representing locked assets in liquidity pools, to be used as collateral. This approach enables liquidity providers to gain temporary liquidity without withdrawing their assets, maintaining the pool's liquidity levels. Furthermore, it extends to a broader range of DeFi services, including lending and trading, where asset locking is prevalent. By allowing the collateralization of locked asset representations through NFTs, our approach aims to provide versatile liquidity solutions across DeFi services, benefitting a diverse user base within the ecosystem.</p> <p>The concept of perpetual contract NFTs, which we introduce, exploits the idea of perpetual futures contracts in the cryptocurrency derivatives market. These NFTs represent the rights to the perpetual contract and its collateral, enabling them to be used effectively as collateral for DeFi composability. The perpetual contract NFT offers a new form of NFT that enhances the utility of locked assets, providing a significant advantage in DeFi applications by offering liquidity while retaining the benefits of asset locking.</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="contract-interface">Contract Interface</h3> <p>Solidity 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"> IPerpetualContractNFT</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Emitted when an NFT is collateralized for obtaining a loan</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Collateralized</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"> owner</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> loanAmount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> interestRate</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> loanDuration</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Emitted when a loan secured by an NFT is fully repaid, releasing the NFT from collateral</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> LoanRepaid</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"> owner</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Emitted when a loan defaults, resulting in the transfer of the NFT to the lender</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Defaulted</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>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Enables an NFT owner to collateralize their NFT in exchange for a loan</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param tokenId The NFT to be used as collateral</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param loanAmount The amount of funds to be borrowed</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param interestRate The interest rate for the loan</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param loanDuration The duration of the loan</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> collateralize</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"> loanAmount</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> interestRate</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> loanDuration</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"> Enables a borrower to repay their loan and regain ownership of the collateralized NFT</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param tokenId The NFT that was used as collateral</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param repayAmount The amount of funds to be repaid</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> repayLoan</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"> repayAmount</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"> Allows querying the loan terms for a given NFT</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param tokenId The NFT used as collateral</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @return loanAmount The amount of funds borrowed</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @return interestRate The interest rate for the loan</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @return loanDuration The duration of the loan</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @return loanDueDate The due date for the loan repayment</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getLoanTerms</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 class="z-variable"> loanAmount</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> interestRate</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> loanDuration</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> loanDueDate</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Allows querying the current owner of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param tokenId The NFT in </span><span class="z-keyword">question</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @return The address of the current owner</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> currentOwner</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-comment"> View the total amount required to repay the loan for a given NFT</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param tokenId The NFT used as collateral</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @return The total amount required to repay the loan, including interest</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> viewRepayAmount</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><h4 id="event-collateralized">Event <code>Collateralized</code></h4> <ul> <li>The <code>Collateralized</code> event MUST be emitted when the collateralize function is successfully executed.</li> <li>Usage: Logs the event of an NFT being used as collateral for a loan, capturing essential details like the loan amount, interest rate, and loan duration.</li> </ul> <h4 id="event-loanrepaid">Event <code>LoanRepaid</code></h4> <ul> <li>The <code>LoanRepaid</code> event MUST be emitted when the repayLoan function is successfully executed.</li> <li>Usage: Logs the event of a loan being repaid and the corresponding NFT being released from collateral.</li> </ul> <h4 id="event-defaulted">Event <code>Defaulted</code></h4> <ul> <li>The <code>Defaulted</code> event MUST be emitted in scenarios where the loan defaults and the NFT is transferred to the lender.</li> <li>Usage: Used to log the event of a loan default and the transfer of the NFT to the lender.</li> </ul> <h4 id="function-collateralize">Function <code>collateralize</code></h4> <ul> <li>The <code>collateralize</code> event SHOULD be implemented as <code>external</code>.</li> <li>Usage: Allows an NFT owner to collateralize their NFT to receive a loan.</li> </ul> <h4 id="function-repayloan">Function <code>repayLoan</code></h4> <ul> <li>The <code>repayLoan</code> function SHOULD be implemented as <code>external</code>.</li> <li>Usage: Enables an NFT owner to repay their loan and reclaim their NFT.</li> </ul> <h4 id="function-getloanterms">Function <code>getLoanTerms</code></h4> <ul> <li>The <code>getLoanTerms</code> function MAY be implemented as <code>external</code> <code>view</code>.</li> <li>Usage: Allows querying the loan terms for a given NFT.</li> </ul> <h4 id="function-currentowner">Function <code>currentOwner</code></h4> <ul> <li>The <code>currentOwner</code> function MAY be implemented as <code>external</code> <code>view</code>.</li> <li>Usage: Enables querying the current owner of a specific NFT.</li> </ul> <h4 id="function-viewrepayamount">Function <code>viewRepayAmount</code></h4> <ul> <li>The <code>viewRepayAmount</code> function MAY be implemented as <code>external</code> <code>view</code>.</li> <li>Usage: Enables querying the current repay amount of a specific NFT.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="design-motivation">Design Motivation</h3> <p>The design of this standard is driven by the need to address specific challenges in the DeFi sector, particularly concerning the liquidity and management of assets locked as collateral. Traditional mechanisms in DeFi often require asset holders to lock up their assets for participation in activities such as lending, staking, or yield farming, which results in a loss of liquidity. This standard aims to introduce a more flexible approach, allowing asset holders to retain some liquidity while their assets are locked, thereby enhancing the utility and appeal of DeFi products.</p> <h3 id="design-decision">Design Decision</h3> <ul> <li> <p>Dual-Role System (Asset Owner and DeFi Platform/Contract): A clear division is established between the NFT owner (asset holder) and the DeFi platform or contract utilizing the NFT as collateral. This distinction simplifies the management of rights and responsibilities, enhancing clarity and reducing potential conflicts.</p> </li> <li> <p>Enhancing Liquidity without Compromising Asset Locking Benefits: A key feature of this standard is enabling asset owners to use their NFTs, which represent locked assets, as collateral to secure loans. This approach allows asset owners to access liquidity without needing to withdraw their assets from pools or staking programs, thus preserving the associated benefits like interest accrual or voting rights.</p> </li> <li> <p>Automated Loan and Collateral Management: The integration of automated features for managing the terms and conditions of the collateralized NFT is a deliberate choice to minimize transaction costs and complexity.</p> </li> <li> <p>DeFi Composability: The strategic emphasis on DeFi composability, particularly the integration between asset-locking and collateralizing services, is pivotal for this standard. This approach aims to streamline the adoption of the standard across diverse DeFi platforms and services, fostering seamless connections within the DeFi ecosystem.</p> </li> </ul> <h3 id="alternate-designs-and-related-work">Alternate Designs and Related Work</h3> <ul> <li> <p>Comparison with <a href="https://wg-eips.ritovision.com/4907/">ERC-4907</a>: While <a href="https://wg-eips.ritovision.com/4907/">ERC-4907</a> also introduces a dual-role model for NFTs (owner and user), our standard focuses specifically on the use of NFTs for collateralization in financial transactions, diverging from <a href="https://wg-eips.ritovision.com/4907/">ERC-4907</a>’s rental-oriented approach.</p> </li> <li> <p>Improvement Over Traditional Collateralization Methods: Compared to traditional DeFi collateralization, which often requires complete asset lock-up, this standard proposes a more dynamic and flexible model that allows for continued liquidity access.</p> </li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Fully compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and integrates with <a href="https://wg-eips.ritovision.com/4907/">ERC-4907</a> for renting NFTs.</p> <h2 id="test-cases">Test Cases</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"> ^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;./PerpetualContractNFT.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"> PerpetualContractNFTDemo</span><span class="z-storage"> is</span><span class="z-entity z-name"> PerpetualContractNFT</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> <span class="giallo-l"><span class="z-entity z-name"> PerpetualContractNFT</span><span>(</span><span>name, symbol)</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"> mint</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"> to</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></code></pre><pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">expect</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;chai&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">ethers</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;hardhat&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-string">&quot;PerpetualContractNFTDemo&quot;</span><span>,</span><span class="z-entity z-name"> 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-string">&quot;should allow an owner to collateralize an NFT, rent it to a contract, and then have the owner repay the loan&quot;</span><span>,</span><span> async </span><span class="z-entity z-name">function</span><span> (</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> const </span><span>[</span><span>owner</span><span>]</span><span class="z-keyword"> =</span><span> await ethers</span><span>.</span><span class="z-entity z-name">getSigners</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> const PerpetualContractNFTDemo </span><span class="z-keyword">=</span><span> await ethers</span><span>.</span><span class="z-entity z-name">getContractFactory</span><span>(</span><span class="z-string">&quot;PerpetualContractNFTDemo&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> const demo </span><span class="z-keyword">=</span><span> await PerpetualContractNFTDemo</span><span>.</span><span class="z-entity z-name">deploy</span><span>(</span><span class="z-string">&quot;DemoNFT&quot;</span><span>,</span><span class="z-string"> &quot;DNFT&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> await demo</span><span>.</span><span class="z-entity z-name">waitForDeployment</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span>demo</span><span>.</span><span>target</span><span>)</span><span>.</span><span>to</span><span>.</span><span>be</span><span>.</span><span>properAddress</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Mint an NFT to the owner</span></span> <span class="giallo-l"><span> await demo</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span><span class="z-constant">1</span><span>,</span><span> owner</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"> Owner collateralizes the NFT for a loan</span></span> <span class="giallo-l"><span> const loanAmount </span><span class="z-keyword">=</span><span> ethers</span><span>.</span><span class="z-entity z-name">parseUnits</span><span>(</span><span class="z-string">&quot;1&quot;</span><span>,</span><span class="z-string"> &quot;ether&quot;</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 1 Ether in Wei. Use Wei to avoid precision error.</span></span> <span class="giallo-l"><span> const interest </span><span class="z-keyword">=</span><span class="z-constant"> 5</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 5% interest</span></span> <span class="giallo-l"><span> const expiration </span><span class="z-keyword">=</span><span> Math</span><span>.</span><span class="z-entity z-name">floor</span><span>(</span><span class="z-keyword">new</span><span class="z-entity z-name"> Date</span><span>(</span><span>)</span><span>.</span><span class="z-entity z-name">getTime</span><span>(</span><span>)</span><span class="z-keyword"> /</span><span class="z-constant"> 1000</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> 3600</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Expire after 60 minutes (3600 seconds), convert it to seconds because `hours` in solidity converted to seconds</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> await demo</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span>owner</span><span>)</span><span>.</span><span class="z-entity z-name">collateralize</span><span>(</span><span class="z-constant">1</span><span>,</span><span> loanAmount</span><span>,</span><span> interest</span><span>,</span><span> expiration</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> tokenId, loanAmount, interestRate, loanDuration</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Check current user of the NFT (should be the contract address)</span></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span>await demo</span><span>.</span><span class="z-entity z-name">userOf</span><span>(</span><span class="z-constant">1</span><span>)</span><span>)</span><span>.</span><span>to</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span>demo</span><span>.</span><span>target</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Borrower repays the loan to release the NFT</span></span> <span class="giallo-l"><span> const repayAmountWei </span><span class="z-keyword">=</span><span> await demo</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span>owner</span><span>)</span><span>.</span><span class="z-entity z-name">viewRepayAmount</span><span>(</span><span class="z-constant">1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> await demo</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span>owner</span><span>)</span><span>.</span><span class="z-entity z-name">repayLoan</span><span>(</span><span class="z-constant">1</span><span>,</span><span> repayAmountWei</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"> Check if the NFT is returned to the original owner after the loan is repaid</span></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span>await demo</span><span>.</span><span class="z-entity z-name">userOf</span><span>(</span><span class="z-constant">1</span><span>)</span><span>)</span><span>.</span><span>to</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-string">&quot;0x0000000000000000000000000000000000000000&quot;</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> <p>Run in Terminal：</p> <pre class="giallo z-code"><code data-lang="shellscript"><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><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"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment">import &quot;@openzeppelin/contracts/token/ERC721/ERC721.sol&quot;;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IPerpetualContractNFT.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./ERC4907/ERC4907.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"> PerpetualContractNFT</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC4907</span><span>, </span><span class="z-entity z-name">IPerpetualContractNFT</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> LoanInfo</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> borrower</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Address that borrowed against the NFT</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> loanAmount</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Amount of funds borrowed</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> interestRate</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Interest rate for the loan</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> loanDuration</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Duration of the loan</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> loanStartTime</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Timestamp when the loan starts</span></span> <span class="giallo-l"><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> LoanInfo</span><span>)</span><span class="z-storage z-type"> internal</span><span> _loans</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">Constructor to initialize the Perpetual Contract NFT contract with the given name and symbo</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> <span class="giallo-l"><span class="z-entity z-name"> ERC4907</span><span>(</span><span>name_, symbol_)</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"> collateralize</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"> loanAmount</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> interestRate</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> loanDuration</span><span>)</span><span class="z-storage z-type"> public</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">ownerOf</span><span>(</span><span>tokenId</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"> isApprovedForAll</span><span>(</span><span class="z-entity z-name">ownerOf</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span class="z-keyword"> ||</span><span class="z-entity z-name"> getApproved</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;Not owner nor approved&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> LoanInfo </span><span class="z-storage z-type">storage</span><span> info </span><span class="z-keyword">=</span><span> _loans</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> info</span><span>.</span><span>borrower </span><span class="z-keyword">=</span><span class="z-variable z-language"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The loan amount should reflect the asset&#39;s value as represented by the NFT, considering an appropriate loan-to-value (LTV) ratio.</span></span> <span class="giallo-l"><span> info</span><span>.</span><span>loanAmount </span><span class="z-keyword">=</span><span> loanAmount</span><span>;</span></span> <span class="giallo-l"><span> info</span><span>.</span><span>interestRate </span><span class="z-keyword">=</span><span> interestRate</span><span>;</span></span> <span class="giallo-l"><span> info</span><span>.</span><span>loanDuration </span><span class="z-keyword">=</span><span> loanDuration</span><span>;</span></span> <span class="giallo-l"><span> info</span><span>.</span><span>loanStartTime </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> <span class="giallo-l"><span class="z-entity z-name"> setUser</span><span>(</span><span>tokenId</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> loanDuration</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Collateralized</span><span>(</span><span>tokenId</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span> loanAmount</span><span>,</span><span> interestRate</span><span>,</span><span> loanDuration</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Further logic can be implemented here to manage the lending of assets</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"> repayLoan</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"> repayAmount</span><span>)</span><span class="z-storage z-type"> public</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>_loans</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>borrower </span><span class="z-keyword">==</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span class="z-string"> &quot;Not the borrower.&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"> Calculate the total amount due for repayment</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> totalDue </span><span class="z-keyword">=</span><span class="z-entity z-name"> viewRepayAmount</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"> Check if the repayAmount is sufficient to cover at least a part of the total due amount</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>repayAmount </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> totalDue</span><span>,</span><span class="z-string"> &quot;Repay amount exceeds total due.&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"> Calculate the remaining loan amount after repayment</span></span> <span class="giallo-l"><span> _loans</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>loanAmount </span><span class="z-keyword">=</span><span> totalDue </span><span class="z-keyword">-</span><span> repayAmount</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Resets the user of the NFT to the default state if the entire loan amount is fully repaid</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>_loans</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>loanAmount </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"> setUser</span><span>(</span><span>tokenId</span><span>,</span><span class="z-support"> address</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> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> LoanRepaid</span><span>(</span><span>tokenId</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> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getLoanTerms</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"> override</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 class="z-support"> uint256</span><span>,</span><span class="z-support"> uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> LoanInfo </span><span class="z-storage z-type">storage</span><span> info </span><span class="z-keyword">=</span><span> _loans</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>info</span><span>.</span><span>loanAmount</span><span>,</span><span> info</span><span>.</span><span>interestRate</span><span>,</span><span> info</span><span>.</span><span>loanDuration</span><span>,</span><span> info</span><span>.</span><span>loanStartTime</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"> currentOwner</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"> 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"> return</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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> viewRepayAmount</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-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_loans</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>loanAmount </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"> If the loan amount is zero, there is nothing to repay</span></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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The interest is calculated on an hourly basis, prorated based on the actual duration for which the loan was held.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If the borrower repays before the loan duration ends, they are charged interest only for the time the loan was held.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> For example, if the annual interest rate is 5% and the borrower repays in half the loan term, they pay only 2.5% interest.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> elapsed </span><span class="z-keyword">=</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp </span><span class="z-keyword">&gt;</span><span> (</span><span>_loans</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>loanStartTime </span><span class="z-keyword">+</span><span> _loans</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>loanDuration</span><span>)</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> ?</span><span> _loans</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>loanDuration </span><span class="z-keyword">/</span><span class="z-constant"> 1</span><span class="z-constant"> hours</span></span> <span class="giallo-l"><span class="z-keyword"> :</span><span> (</span><span class="z-variable z-language">block</span><span>.</span><span>timestamp </span><span class="z-keyword">-</span><span> _loans</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>loanStartTime</span><span>)</span><span class="z-keyword"> /</span><span class="z-constant"> 1</span><span class="z-constant"> hours</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Round up</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Example: 15/4 = 3.75</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> round((15 + 4 - 1)/4) = 4, round((15/4) = 3)</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> interest </span><span class="z-keyword">=</span><span> (</span><span>(</span><span>_loans</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>loanAmount </span><span class="z-keyword">*</span><span> _loans</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>interestRate </span><span class="z-keyword">/</span><span class="z-constant"> 100</span><span>)</span><span class="z-keyword"> *</span><span> elapsed </span><span class="z-keyword">+</span><span> (</span><span>_loans</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>loanDuration </span><span class="z-keyword">/</span><span class="z-constant"> 1</span><span class="z-constant"> hours</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> /</span><span> </span></span> <span class="giallo-l"><span> (</span><span>_loans</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>loanDuration </span><span class="z-keyword">/</span><span class="z-constant"> 1</span><span class="z-constant"> hours</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Calculate the total amount due</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> totalDue </span><span class="z-keyword">=</span><span> _loans</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>loanAmount </span><span class="z-keyword">+</span><span> interest</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> totalDue</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"> Additional functions and logic to handle loan defaults, transfers, and other aspects of the NFT lifecycle</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <!-- Needs discussion. --> <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>Kim, H., Kim, H.-S., &amp; Park, Y.-S. (2022). Perpetual Contract NFT as Collateral for DeFi Composability. <span style="font-style: italic;">IEEE Access</span>, <span style="font-style: italic;">10</span>, 126802–126814. https://doi.org/<a href="https://doi.org/10.1109/ACCESS.2022.3225884">10.1109/ACCESS.2022.3225884</a>## Motivation <a href="#fr-1-1">↩</a></p> </li> </ol> </section> 2023-11-21T00:00:00+00:00 2026-02-11T14:48:26+00:00 Xianghttps://github.com/wenzhenxiang Ben77https://github.com/ben2077 Mingshi S.https://github.com/newnewsms https://wg-eips.ritovision.com/7564/

Focuses on NFT management within smart contract wallets, offering enhanced transaction flexibility and security

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a smart contract wallet-based approach for managing NFTs, focusing on utilizing the programmable features of smart contract wallets for NFT asset management. Additionally, it introduces functions such as <code>nftApprove</code>, <code>nftSetApprovalForOneAll</code>, <code>nftSetApprovalForAllAll</code>, <code>nftGetApproved</code>, <code>nftIsApprovedForOneAll</code>, <code>nftIsApprovedForAllAll</code> and <code>nftTransfer</code>, which provide enhanced control over NFT transactions. This approach seeks to enhance NFT management by utilizing the built-in features of smart contract wallets, thus offering a more adaptable, secure, and efficient method for managing token transactions.</p> <h2 id="motivation">Motivation</h2> <p>An externally-owned account (EOA) wallet has no state and code storage, while the smart contract wallet does.</p> <p>Account abstraction (AA) is a direction of the smart contract wallet, which works around abstract accounts. This ERC can also be an extension based on <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> or as a plug-in for wallets.</p> <p>The smart contract wallet allows the user's own account to have state and code, bringing programmability to the wallet. We think there are more directions to expand. For example, nft asset management, functional expansion of nft transactions, etc.</p> <p>The smart contract wallet interface of this ERC is for nft asset management and nft asset approval. It supports the simplenft <!-- TODO --> ERC-X, and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> is backward compatible with <!-- TODO --> ERC-X, so it can be compatible with the management of all nfts in the existing market.</p> <p>The proposal aims to achieve the following goals:</p> <ol> <li>NFT assets are allocated and managed by the wallet itself, such as approve function, which are configured by the user’s contract wallet, rather than controlled by the nft asset contract, to avoid some existing ERC-721 contract risks.</li> <li>Add the <code>nftTransfer</code> function, the transaction initiated by the non-smart wallet itself.</li> <li>Add <code>nftApprove</code>, <code>nftSetApprovalForOneAll</code>, <code>nftSetApprovalForAllAll</code>, <code>nftGetApproved</code>, <code>nftIsApprovedForOneAll</code>, <code>nftIsApprovedForAllAll</code> functions. The user wallet itself supports approve and provides approve. for One nft, all nft of one nft smart contract, all nft assets.</li> <li>User wallet can choose batch approve and batch transfer.</li> <li>Users can choose to add hook function before and after their <code>nftTransfer</code> to increase the user's more playability.</li> <li>The user can choose to implement the <code>nftReceive</code> function.</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><strong>Compliant contract must implement the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interfaces</strong></p> <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"> @title</span><span class="z-comment"> ERC-7564</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-7564</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 ERC-165 identifier for this interface is </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.20</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"> IERC7564</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"> Used to notify listeners that owner has granted approval to the user to manage one 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"> _asset</span><span class="z-comment"> Address 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"> _owner</span><span class="z-comment"> Address of the account that has granted the approval for nft‘s assets</span></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 of the 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"> _tokenId</span><span class="z-comment"> The unique identifier 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"> event</span><span class="z-entity z-name"> NftApproval</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"> _asset</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"> _operator</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>;</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"> Used to notify listeners that owner has granted approval to the operator to manage all nft of one asset 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"> _asset</span><span class="z-comment"> Address 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"> _owner</span><span class="z-comment"> Address of the account that has granted the approval for nft‘s assets</span></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 of the 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"> _approved</span><span class="z-comment"> approve all nft of one asset 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"> NftApprovalForOneAll</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"> _asset</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"> _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 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"> Used to notify listeners that owner has granted approval to the operator to manage all 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"> _owner</span><span class="z-comment"> Address of the account that has granted the approval for nft‘s assets</span></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 of the 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"> _approved</span><span class="z-comment"> approve all nft</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"> NftApprovalForAllAll</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"> _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 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"> Approve nft</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Allows operator address to withdraw from your wallet one nft.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits an {nftApproval} 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"> _asset</span><span class="z-comment"> Address 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"> _operator</span><span class="z-comment"> Address of the 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"> _tokenId</span><span class="z-comment"> The unique identifier 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"> nftApprove</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _asset</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"> 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> </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"> Approve all nft of one asset</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Allows operator address to withdraw from your wallet all nft.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits an {nftApprovalForOneAll} 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"> _asset</span><span class="z-comment"> Address 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"> _operator</span><span class="z-comment"> Address of the 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"> _approved</span><span class="z-comment"> Approved all nfts of one 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"> nftSetApprovalForOneAll</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _asset</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 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"> Approve all nft</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Allows operator address to withdraw from your wallet all nft.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits an {nftApprovalForAllAll} 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"> _operator</span><span class="z-comment"> Address of the 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"> _approved</span><span class="z-comment"> Approved all 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"> nftSetApprovalForAllAll</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 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"> read operator approved</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _asset</span><span class="z-comment"> Address 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"> _operator</span><span class="z-comment"> Address of the 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"> _tokenId</span><span class="z-comment"> The unique identifier 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"> _approved</span><span class="z-comment"> Whether to approved operator one 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"> nftGetApproved</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _asset</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"> uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</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 class="z-variable z-parameter z-function"> _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">@notice</span><span class="z-comment"> read operator approved</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _asset</span><span class="z-comment"> Address 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"> _operator</span><span class="z-comment"> Address of the operator</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"> _approved</span><span class="z-comment"> Whether to approved operator all nfts of this one 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"> nftIsApprovedForOneAll</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _asset</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _operator</span><span>)</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 class="z-variable z-parameter z-function"> _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">@notice</span><span class="z-comment"> read operator approved</span></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 of the operator</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"> _approved</span><span class="z-comment"> Whether to approved operator all 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"> nftIsApprovedForAllAll</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _operator</span><span>)</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 class="z-variable z-parameter z-function"> _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">@notice</span><span class="z-comment"> Transfer nft</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> must call nft asset transfer() inside the function</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If the caller is not wallet self, must verify the approve and 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"> _asset</span><span class="z-comment"> Address 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"> _to</span><span class="z-comment"> Address of the receive</span></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 transaction amount</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"> The bool value returns whether the transfer is 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"> nftTransfer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _asset</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"> _tokenId</span><span>)</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-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable z-parameter z-function"> _success</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>the key technical decisions in this proposal are:</p> <p><strong>Improved Approve Mechanism</strong></p> <ul> <li><strong>Current vs. Proposed</strong>: In the existing ERC-721 system, an externally-owned account (EOA) directly interacts with nft contracts to <code>approve</code>. The new <code>nftApprove</code>, <code>nftSetApprovalForOneAll</code>, <code>nftSetApprovalForAllAll</code>, <code>nftGetApproved</code>, <code>nftIsApprovedForOneAll</code>, <code>nftIsApprovedForAllAll</code>functions in this proposed enable more precise control over nft usage within a wallet contract, a significant improvement over the traditional method.</li> <li><strong>Enhanced Security</strong>: This mechanism mitigates risks like nft over-approval by shifting approval control to the user's smart contract wallet.</li> <li><strong>Programmability</strong>: Users gain the ability to set advanced approval strategies, such as conditional or time-limited approvals, the <code>nftSetApprovalForAllAll</code> function specifically allows for a universal setting all nfts. these were not possible with traditional ERC-721 nfts.</li> </ul> <p><strong>Optimized Transfer Process</strong></p> <ul> <li><strong>Efficiency and Security</strong>: The <code>nftTransfer</code> function streamlines the nft transfer process, making transactions both more efficient and secure.</li> <li><strong>Flexibility</strong>: Allows the integration of custom logic (hooks) before and after transfers, enabling additional security checks or specific actions tailored to the user’s needs.</li> </ul> <p><strong>Support for Batch Operations</strong></p> <ul> <li><strong>Increased Efficiency</strong>: Users can simultaneously handle multiple <code>approve</code> or <code>transfer</code> operations, significantly boosting transaction efficiency.</li> <li><strong>Enhanced User Experience</strong>: Simplifies the management of numerous assets, improving the overall experience for users with large portfolios.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC can be used as an extension of <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> and is backward compatible with ERC-4337.</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> 2023-11-10T00:00:00+00:00 2026-02-11T14:48:26+00:00 Alexander Müllerhttps://github.com/alexmmueller Gregory Markouhttps://github.com/GregTheGreek Willem Oldinghttps://github.com/Wollum Belma Gutlichttps://github.com/morrigan Marin Petrunićhttps://github.com/mpetrunic Pedro Gomeshttps://github.com/pedrouid https://wg-eips.ritovision.com/7555/

Discover accounts using a signing key that do not use the secp256k1 curve.

<h2 id="abstract">Abstract</h2> <p>This proposal establishes a standardized interface and functionality for applications to discover user accounts besides the readily available EOA. Specifically discovering normal accounts and smart accounts that may have been deployed or configured using a signing key that is not the standard Ethereum secp256k1 curve. The objective is to ensure uniformity of address retrieval across applications, and domains.</p> <h2 id="motivation">Motivation</h2> <p>The recent progress in account abstraction has led to significantly increased flexibility enabling use cases such as multi-signature transactions, social recovery, contract/account whitelisting, session keys and much more. However, with increased flexibility there comes an increased complexity. One area of increased complexity is account fragmentation -both at the EOA and smart account level - following from the inability to correctly identify all existing addresses by a user. In this EIP we present a potential solution that aims to unify the discovery and handling of such accounts.</p> <p>Prior to <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a>, the standard approach to interacting with a smart contract account required a valid signature from a keypair using secp256k1. Since ERC-4337, alternative signing options have become popular, such as passkey, yubikey or ios/android secure enclaves, which do not conform to the secp256k1 curve, and require a paymaster to submit the transaction on the users behalf. Since providers implement additional logic into the key generation process (shamir, mpc, secure enclave, etc) alternative signers have no uniform way for a user to produce the same externally-owned account adresses, or smart account addresses across different applications.</p> <p>Secure hardware devices such as native passkeys, or yubikeys generate a unique keypair per domain. The implication is for application developers that natively integrate authentication methods such as those, will never be able to recover a uniform keypair. Practically, if we have the following scenario where there are two applications: a mobile app (App A), and a web based application (App B). If both implement a solution such as passkey, App A and App B would recover two different keys. This poses a hurdle to the user who would expect to have the same address across services (much like they would using a hardware wallet, or other wallets).</p> <p>With the introduction of 4337, this problem is amplified. An application that wants its users to leverage 4337 (to abstract keys away, and generally improve the onboarding experience) will not be able to detect if a user has an existing smart account deployed. This will lead to the developer (or third party service providing the onboarding experience) to deploy a smart account on behalf of the user at the given address scoped to the apps domain.</p> <p>Not being able to correctly identify existing accounts owned by a user will lead to account fragmentation. The fragmentation, as described early, exists because applications will identify them as a new user, and not one whom may already have an account. Leading to a single user having many unassociated accounts, with assets scattered amongst them, and no way to unify them.</p> <p>This standard aims to achieve:</p> <ol> <li>Standard way for applications to request a users signing address.</li> <li>Standard way for applications to provide single sign-on (SSO) functionality for alternative signing methods.</li> <li>Standard way for applications to disclose smart accounts that have been created through their own service.</li> </ol> <p>This standard <strong>does not</strong> aim to achieve:</p> <ol> <li>How a user can sign messages across domains.</li> <li>How a provider generates a keypair for a user.</li> <li>How an application handles the user interface logic.</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="definitions">Definitions</h3> <ul> <li><strong>Smart account</strong> - An ERC-4337 compliant smart contract account that has a modular architecture.</li> <li><strong>Domain</strong> - A string of text acting as an identification to a server or website (eg: <code>ethereum.org</code> or <code>ABCDE12345.com.example.app</code>).</li> <li><strong>EOA</strong> - Accounts that are controlled by a single private key.</li> <li><strong>Provider</strong> - A third party service provider that is able to authenticate a user and produce a keypair for the user.</li> </ul> <h3 id="redirects">Redirects</h3> <p>An application looking to authenticate a user must navigate the user to a given provider's URI based on the <code>URI Request Syntax</code>. The application must implement a valid redirect URI for the callback in order to receive a valid response.</p> <h4 id="available-routes">Available Routes</h4> <ul> <li><code>/auth/</code>: The route used to authenticate a user, and request credentials.</li> <li><code>/sendTransaction/</code>: The route used to send a transaction payload for a user to sign. This is more of a convenient method to allow applications to do both authentication, and plugin registration within a single redirect, instead of requiring the user to perform two redirects.</li> </ul> <h3 id="schema">Schema</h3> <p>The <code>smart_account_address</code> should be returned in the CAIP-10 format.</p> <h4 id="auth-route">Auth Route</h4> <h5 id="request-schema">Request Schema</h5> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span class="z-entity z-name z-tag"> p</span><span class="z-entity z-name z-tag">arameters</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">n</span><span>:</span><span class="z-string"> q</span><span class="z-string">uery</span></span> <span class="giallo-l"><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">edirect_uri</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">chema</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"> d</span><span class="z-entity z-name z-tag">escription</span><span>:</span><span class="z-string"> T</span><span class="z-string">he uri that the provider should redirect back to.</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">n</span><span>:</span><span class="z-string"> q</span><span class="z-string">uery</span></span> <span class="giallo-l"><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">hain_id</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">chema</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"> d</span><span class="z-entity z-name z-tag">escription</span><span>:</span><span class="z-string"> T</span><span class="z-string">he chain_id of a given network.</span></span></code></pre><h5 id="response-schema">Response Schema</h5> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span class="z-entity z-name z-tag"> p</span><span class="z-entity z-name z-tag">arameters</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">n</span><span>:</span><span class="z-string"> q</span><span class="z-string">uery</span></span> <span class="giallo-l"><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">mart_account_address</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">chema</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"> d</span><span class="z-entity z-name z-tag">escription</span><span>:</span><span class="z-string"> T</span><span class="z-string">he on-chain address for a given smart account, formatted using CAIP-10</span></span></code></pre><h5 id="request-syntax">Request Syntax</h5> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>https://&lt;PROVIDER_URI&gt;/auth/?</span></span> <span class="giallo-l"><span> redirect_uri=&lt;YOUR_REDIRECT_URI&gt;</span></span> <span class="giallo-l"><span> &amp;chain_id=&lt;CHAIN_ID&gt;</span></span></code></pre><h5 id="response-syntax">Response Syntax</h5> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>https://&lt;YOUR_REDIRECT_URI&gt;/auth/?</span></span> <span class="giallo-l"><span> smart_account_address=&lt;SMART_ACCOUNT_ADDRESS&gt;</span></span></code></pre><h4 id="sendtransaction-route">sendTransaction Route</h4> <h5 id="request-schema-1">Request Schema</h5> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span class="z-entity z-name z-tag"> p</span><span class="z-entity z-name z-tag">arameters</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">n</span><span>:</span><span class="z-string"> q</span><span class="z-string">uery</span></span> <span class="giallo-l"><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">edirect_uri</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">chema</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"> d</span><span class="z-entity z-name z-tag">escription</span><span>:</span><span class="z-string"> T</span><span class="z-string">he uri that the provider should redirect back to.</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">n</span><span>:</span><span class="z-string"> q</span><span class="z-string">uery</span></span> <span class="giallo-l"><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">hain_id</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">chema</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"> d</span><span class="z-entity z-name z-tag">escription</span><span>:</span><span class="z-string"> T</span><span class="z-string">he chain_id of a given network.</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">n</span><span>:</span><span class="z-string"> q</span><span class="z-string">uery</span></span> <span class="giallo-l"><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">ransaction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">chema</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"> d</span><span class="z-entity z-name z-tag">escription</span><span>:</span><span class="z-string"> T</span><span class="z-string">he RLP encoded transaction that needs to be signed</span></span></code></pre><h5 id="response-schema-1">Response Schema</h5> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span class="z-entity z-name z-tag"> p</span><span class="z-entity z-name z-tag">arameters</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">n</span><span>:</span><span class="z-string"> q</span><span class="z-string">uery</span></span> <span class="giallo-l"><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">mart_account_address</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">chema</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"> d</span><span class="z-entity z-name z-tag">escription</span><span>:</span><span class="z-string"> T</span><span class="z-string">he on-chain address for a given smart account, formatted using CAIP-10</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">n</span><span>:</span><span class="z-string"> q</span><span class="z-string">uery</span></span> <span class="giallo-l"><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">x_hash</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">chema</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"> d</span><span class="z-entity z-name z-tag">escription</span><span>:</span><span class="z-string"> T</span><span class="z-string">he hash of the transaction</span></span></code></pre><h5 id="request-syntax-1">Request Syntax</h5> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>https://&lt;PROVIDER_URI&gt;/sendTransaction/?</span></span> <span class="giallo-l"><span> redirect_uri=&lt;YOUR_REDIRECT_URI&gt;</span></span> <span class="giallo-l"><span> &amp;chain_id=&lt;CHAIN_ID&gt;</span></span> <span class="giallo-l"><span> &amp;transaction=&lt;TRANSACTION_DATA&gt;</span></span></code></pre><h5 id="response-syntax-1">Response Syntax</h5> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>https://&lt;YOUR_REDIRECT_URI&gt;/sendTransaction/?</span></span> <span class="giallo-l"><span> smart_account_address=&lt;SMART_ACCOUNT_ADDRESS&gt;</span></span> <span class="giallo-l"><span> &amp;tx_hash=&lt;TX_HASH&gt;</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="redirects-1">Redirects</h3> <p>Taking inspiration from how SSO functions in the web today. We implement a similar redirect pattern, consisting of a simple request/response.</p> <h4 id="application">Application</h4> <h5 id="initial-request">Initial Request</h5> <p>An application would redirect a user to a specified provider, only passing along the callback url information. This is to ensure the providers website can remain stateless, and not rely on web requests.</p> <h5 id="response-from-provider">Response from provider</h5> <p>When a user is redirected to the application, it can parse the response for a signer address, and associated smart account address.</p> <h4 id="provider">Provider</h4> <p>Upon a user navigating to the provider website, the provider would parse the redirect url and authenticate the user. The authentication method does not matter, such that it can produce a valid public address, and recover any smart accounts that may have been deployed through the provider.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Using <code>location.replace()</code> vs <code>location.href</code> is up to the application to decide how they wish the experience to be handled.</p> <p>Sample URI Request</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>https://eth-sso.ethereum.org/auth?redirect_uri=http://myapp.com/eth-sso/callback/&amp;chain_id=1</span></span></code></pre> <p>Sample Response</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>http://myapp.com/callback/?smart_account_address=0xb...c</span></span></code></pre> <p>Application logic</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"> https://myapp.com</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> User triggered authentication function</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> auth</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-variable z-other">location</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">https://eth-sso.ethereum.org/auth?redirect_uri=myapp.com&amp;chain_id=1/eth-sso/callback/</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</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-punctuation z-definition z-comment">//</span><span class="z-comment"> App level routing logic (generic router)</span></span> <span class="giallo-l"><span class="z-entity z-name">route</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">/eth-sso/callback/</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"> params</span><span class="z-keyword"> =</span><span> (</span><span class="z-keyword">new</span><span class="z-entity z-name"> URL</span><span>(</span><span class="z-variable z-other">document</span><span>.</span><span class="z-variable z-other">location</span><span>)</span><span>)</span><span>.</span><span class="z-variable z-other">searchParams</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> smartAccountAddress</span><span class="z-keyword"> =</span><span class="z-variable z-other"> params</span><span>.</span><span class="z-entity z-name">get</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">smart_account_address</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>)</span><span>;</span></span></code></pre> <p>Provider Logic</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"> eg: https://eth-sso.ethereum.org/auth</span></span> <span class="giallo-l"><span class="z-entity z-name">route</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">/eth-sso/callback/</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-storage z-type"> function</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">/auth</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"> let</span><span class="z-variable z-other"> params</span><span class="z-keyword"> =</span><span> (</span><span class="z-keyword">new</span><span class="z-entity z-name"> URL</span><span>(</span><span class="z-variable z-other">document</span><span>.</span><span class="z-variable z-other">location</span><span>)</span><span>)</span><span>.</span><span class="z-variable z-other">searchParams</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> redirectUrl</span><span class="z-keyword"> =</span><span class="z-variable z-other"> params</span><span>.</span><span class="z-entity z-name">get</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">redirect_uri</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-comment"> //</span><span class="z-comment"> Authenticate the user (eg: with passkeys)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> address</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 class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Get smart account if available</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> smartAccountAddress</span><span class="z-keyword"> =</span><span class="z-entity z-name"> getSmartAccount</span><span>(</span><span class="z-variable z-other">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> window</span><span>.</span><span class="z-variable z-other">location</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-string">http://</span><span class="z-string">${</span><span class="z-variable z-other">redirectUrl</span><span class="z-string">}</span><span class="z-string">/?smart_account_address=</span><span class="z-string">${</span><span class="z-variable z-other">smartAccountAddress</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></code></pre><h2 id="security-considerations">Security Considerations</h2> <!-- Needs discussion. --> <ul> <li>Is there a concern that a user can spoof another persons address, and that could be malicious? For example, circumventing the provider, and manually calling the redirect_url with a chosen address. A way around this would be having the user actually sign a challenge message, perhaps leveraging SIWE.</li> </ul> <p>The absence of wildcard support in the redirect URI is intended to protect users from nested open redirect vulnerabilities. Allowing wildcards could enable attackers to redirect users to different pages under the supported wildcard, creating a vulnerability to open redirects.</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-11-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 dapplionhttps://github.com/dapplion Mikhail Kalininhttps://github.com/mkalinin https://wg-eips.ritovision.com/7549/

Move committee index outside of the signed Attestation message

<h2 id="abstract">Abstract</h2> <p>Move the committee's <code>index</code> field outside of the signed Attestation message to allow aggregation of equal consensus votes.</p> <h2 id="motivation">Motivation</h2> <p>This proposal aims to make Casper FFG clients more efficient by reducing the average number of pairings needed to verify consensus rules. While all types of clients can benefit from this EIP, ZK circuits proving Casper FFG consensus will likely have the most impact.</p> <p>On a beacon chain network with at least 262144 active indices, it's necessary to verify a minimum of <code>ceil(32*64 * 2/3) = 1366</code> attestations to reach a 2/3 threshold. Participants cast two votes at once: LMD GHOST vote and Casper-FFG vote. However, the Attestation message contains three elements:</p> <ol> <li>LMD GHOST vote <code>(beacon_block_root, slot)</code>. Note: includes slot in the event (block, slot) voting is adopted.</li> <li>FFG vote <code>(source, target)</code></li> <li>Committee index <code>(index)</code></li> </ol> <p>Signing over the 3rd item causes tuples of equal votes to produce different signing roots. If the committee index is moved outside of the Attestation message, the minimum number of attestations to verify to reach a 2/3 threshold is reduced to <code>ceil(32 * 2/3) = 22</code> (a factor of 62).</p> <p>On-chain attestations can now be packed more space-efficiently into beacon blocks. This proposal allows for up to 8 slots worth of votes in a block, compared to 2 today. In other words, a chain with only 1/8 online proposers can still potentially include all votes on-chain.</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> <ul> <li>Set <code>index</code> field from <code>AttestationData</code> to a fixed value of zero</li> <li>Move committee indexing data to the outer <code>Attestation</code> container with <code>committee_bits</code></li> <li>Increase the capacity of <code>aggregation_bits</code> to all committees in a slot</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/2c1f677187e6534aec77057a7d1cc746a40d3630/specs/electra/beacon-chain.md"><code>/specs/electra/beacon-chain.md</code></a>.</p> <h2 id="rationale">Rationale</h2> <h3 id="deprecation-strategy">Deprecation strategy</h3> <p>The <code>index</code> field in <code>AttestationData</code> can be deprecated by:</p> <ol> <li>Removing the field</li> <li>Preserving the field and setting it to zero</li> <li>Changing the field type to Optional (from EIP-7495 StableContainer)</li> </ol> <p>This EIP chooses the second option to not complicate the inclusion of <code>AttesterSlashing</code> objects. While the <code>Attestation</code> container changes, <code>AttesterSlashing</code> includes indexed attestations without committee data.</p> <h3 id="max-attestations-value"><code>MAX_ATTESTATIONS</code> value</h3> <p>The maximum size of an attestation increases, with a bitfield 64 times larger on networks with maxed committees. <code>MAX_ATTESTATIONS</code> value is reduced to limit the beacon block size while still increasing the total capacity of votes. A value of 8 increases the voting capacity by 4 while having the same attestation space size with a network of 1.2M active indices. Read the details <a href="https://wg-eips.ritovision.com/7549/assets/complexity_analysis/">here</a>.</p> <h3 id="max-attester-slashings-value"><code>MAX_ATTESTER_SLASHINGS</code> value</h3> <p>On-chain <code>AttesterSlashing</code> includes a list of participants' indices. With this EIP, the worst-case size increases by 64 times, resulting in an uncompressed size of 488 KB per <code>AttesterSlashing</code> in a network of 1M validators. Snappy compression reduces it to 320 KB, which is still significant. To bound the maximum size of the block, this proposal reduces <code>MAX_ATTESTER_SLASHINGS</code> from 2 to 1, the minimum value. Read the details <a href="https://wg-eips.ritovision.com/7549/assets/complexity_analysis/">here</a>.</p> <h3 id="using-bitvector-for-committee-bits">Using <code>Bitvector</code> for <code>committee_bits</code></h3> <p>The <code>committee_bits</code> sequence has a variable length with the max size <code>MAX_COMMITTEES_PER_SLOT = 64</code>. Encoding of the <code>Bitlist</code> includes its actual length, which doubles the size of the <code>committee_bits</code> compared to the <code>Bitvector</code> type. Beacon chain state transition ensures correctness of the <code>committee_bits</code> when the effective number of committees in a slot is less than its max value.</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> <h2 id="security-considerations">Security Considerations</h2> <h3 id="first-block-after-the-fork">First block after the fork</h3> <p>Because the on-chain <code>Attestation</code> container changes, attestations from the prior fork can't be included in post-Electra blocks. Therefore, the first block after the fork may have zero attestations. LMD votes can still be applied to fork-choice via <code>on_attestation</code> handler, so there will be only a 1/32 loss of FFG votes. Attesters assigned to the last slot of the fork will incur one epoch worth of offline penalties. One possible mitigation is to change the Electra block body type to allow including attestations from both forks. However, the mitigation increases complexity for little gain, so this proposal chooses not to address the issue.</p> <h3 id="mutation-over-gossip">Mutation over gossip</h3> <p>Moving the <code>index</code> field outside of the signed message allows malicious mutation only on the p2p gossip topic <code>beacon_attestation_${subnet_id}</code>. Everywhere else, the <code>Attestation</code> message is wrapped with an outer signature that prevents mutation.</p> <p>Gossip verification rules for the <code>beacon_attestation_${subnet_id}</code> topic include:</p> <blockquote> <ul> <li>[REJECT] The attester is a member of the committee -- i.e., <code>attestation.attester_index</code> in <code>get_beacon_committee(state, attestation.data.slot, index)</code></li> </ul> </blockquote> <p>If an attacker mutates the <code>index</code> field, the above rule verification will fail, and the message will be dropped. If implementations run the above check before registering the attestation in a 'first-seen' cache, there's no risk of cache pollution.</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-31T00:00:00+00:00 2026-02-11T14:48:25+00:00 Combocombo@1combo.io Saitamahttps://github.com/saitama2009 CT29CT29@1combo.io Luigiluigi@1combo.io https://wg-eips.ritovision.com/7548/

A protocol that enables users to remix NFTs and generate new NFT derivative works, while their relationships can be traced on chain.

<h2 id="abstract">Abstract</h2> <p>This proposal aims to establish a standardized method for creating new intellectual properties (IPs) by remixing multiple existing IPs in a decentralized manner.</p> <p>The protocol is built on the foundation of NFTs (Non-Fungible Tokens). Within this protocol, each intellectual property is represented as an NFT. It extends the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard, enabling users to generate a new NFT by remixing multiple existing NFTs. To ensure transparency and traceability in the creation process, the relationships between the new NFT and the original NFTs are recorded on the blockchain and made publicly accessible.</p> <p>Furthermore, to enhance the liquidity of IP, users not only have the ability to remix NFTs they own but can also grant permission to others to participate in the creation of new NFTs using their own NFTs.</p> <h2 id="motivation">Motivation</h2> <p>The internet is flooded with fresh content every day, but with the traditional IP infrastructure, IP registration and licensing is a headache for digital creators. The rapid creation of content has eclipsed the slower pace of IP registration, leaving much of this content unprotected. This means digital creators can't fairly earn from their work's spread.</p> <table><thead><tr><th></th><th>Traditional IP Infrastructure</th><th>Open IP Infrastructure</th></tr></thead><tbody> <tr><td>IP Registration</td><td>Long waits, heaps of paperwork, and tedious back-and-forths.</td><td>An NFT represents intellectual property; the owner of the NFT holds the rights to the IP.</td></tr> <tr><td>IP Licensing</td><td>Lengthy discussions, legal jargon, and case-by-case agreements.</td><td>A one-stop global IP licensing market that supports various licensing agreements.</td></tr> </tbody></table> <p>With this backdrop, we're passionate about building an Open IP ecosystem tailored for today's digital creators. Here, with just a few clicks, creators can register, license, and monetize their content globally, without geographical or linguistic barriers.</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>Interface</strong></p> <p>This protocol standardizes how to remix multiple existing NFTs and create a new NFT derivative work (known as a combo), while their relationships can be traced on the blockchain. It contains three core modules, remix module, network module, and license module.</p> <h3 id="remix-module">Remix Module</h3> <p>This module extends the ERC-721 standard and enables users to create a new NFT by remixing multiple existing NFTs, whether they’re ERC-721 or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>.</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.10</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"> IERC721X</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Events</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"> Emits when a combo is minted.</span></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"> The owner address of the newly minted combo</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> comboId</span><span class="z-comment"> The newly minted combo identifier</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ComboMinted</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">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> comboId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Structs</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"> tokenAddress</span><span class="z-comment"> The NFT&#39;s collection 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"> The NFT identifier</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Token</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> 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"> amount</span><span class="z-comment"> The number of NFTs 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"> licenseId</span><span class="z-comment"> Which license to be used to verify this component</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Component</span><span> {</span></span> <span class="giallo-l"><span> Token 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 class="z-support"> uint256</span><span> licenseId</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</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 NFT by remixing multiple existing NFTs.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> components</span><span class="z-comment"> The NFTs remixed to mint a combo</span></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 representing the algorithm about how to generate the combo&#39;s metadata when remixing multiple existing NFTs.</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-storage z-type"> Component</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> components</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"> hash</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-storage z-type"> @dev</span><span class="z-comment"> Retrieve a combo&#39;s components.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getComponents</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> comboId</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-storage z-type">Component</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><h3 id="license-module">License Module</h3> <p>By default, users can only remix multiple NFTs they own to create new NFT derivative works. This module enables NFT holders to grant others permission to use their NFTs in the remixing process.</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.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;./IERC721X.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"> ILicense</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"> Verify the permission when minting a combo</span></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 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"> combo</span><span class="z-comment"> The new NFT to be minted by remixing multiple existing NFTs</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"> components</span><span class="z-comment"> The multiple existing NFTs used to mint the new combo</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> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> user</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> IERC721X</span><span>.</span><span class="z-support z-variable">Token</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> combo</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> IERC721X</span><span>.</span><span class="z-support z-variable">Component</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> components</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></span></code></pre><h3 id="network-module">Network Module</h3> <p>This module follows the singleton pattern and is used to track all relationships between the original NFTs and their NFT derivative works.</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.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;./IERC721X.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"> INFTNetIndexer</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"> Verify if the `child` was created by remixing the `parent` with other NFTs.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> parent</span><span class="z-comment"> Any 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"> child</span><span class="z-comment"> Any NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isParent</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> IERC721X</span><span>.</span><span class="z-support z-variable">Token</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> parent</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> IERC721X</span><span>.</span><span class="z-support z-variable">Token</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> child</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 class="z-storage z-type"> @dev</span><span class="z-comment"> Verify if `a` and `b` have common `parent`s</span></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"> Any 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"> b</span><span class="z-comment"> Any NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isSibling</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> IERC721X</span><span>.</span><span class="z-support z-variable">Token</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> a</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> IERC721X</span><span>.</span><span class="z-support z-variable">Token</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> b</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 class="z-storage z-type"> IERC721X</span><span>.</span><span class="z-support z-variable">Token</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> commonParents</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"> Return all parents 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"> token</span><span class="z-comment"> Any 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"> parents</span><span class="z-comment"> All NFTs used to mint the `token`</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getParents</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> IERC721X</span><span>.</span><span class="z-support z-variable">Token</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> token</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-storage z-type">IERC721X</span><span>.</span><span class="z-support z-variable">Token</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> parents</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The Open IP Protocol is built on the "1 premise, 2 extensions, 1 constant" principle.</p> <p>The “1 premise” means that for any IP in the Open IP ecosystem, an NFT stands for that IP. So, if you have the NFT, you own the IP. That’s why the Open IP Protocol is designed as an extended protocol compatible with ERC-721.</p> <p>The “2 extensions” refer to the diversification of IP licensing and remixing.</p> <ul> <li> <p>IP licensing methods are diverse. For example, delegating an NFT to someone else is one type of licensing, setting a price for the number of usage rights is another type of licensing, and even pricing based on auction, AMM, or other pricing mechanisms can develop different licensing methods. Therefore, the license module is designed allowing various custom licensing methods.</p> </li> <li> <p>IP remixing rules are also diverse. When remixing multiple existing NFTs, whether to support ERC-1155, whether to limit the range of NFT selection, and whether the NFT is consumed after remixing, there is no standard. So, the remix module is designed to support custom remixing rules.</p> </li> </ul> <p>The "1 constant" refers to the fact that the traceability information of IP licensing is always public and unchangeable. Regardless of how users license or remix IPs, the relationship between the original and new IPs remains consistent. Moreover, if all IP relationships are recorded in the same database, it would create a vast IP network. If other social or gaming dApps leverage this network, it can lead to entirely novel user experiences. Hence, this protocol's network module is designed as a singleton.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backwards compatible with the existing ERC-721 standard, extending the standard with new functions that do not affect the core functionality.</p> <!-- TODO: add reference implementation --> <h2 id="security-considerations">Security Considerations</h2> <p>This standard highlights several security concerns that need attention:</p> <ul> <li> <p><strong>Ownership and Permissions</strong>: Only the NFT owner or those granted by them should be allowed to remix NFTs into NFT derivative works. It's vital to have strict access controls to prevent unauthorized creations.</p> </li> <li> <p><strong>Reentrancy Risks</strong>: Creating derivative works might require interacting with multiple external contracts, like the remix, license, and network modules. This could open the door to reentrancy attacks, so protective measures are necessary.</p> </li> <li> <p><strong>Gas Usage</strong>: Remixing NFTs can be computation-heavy and involve many contract interactions, which might result in high gas fees. It's important to optimize these processes to keep costs down and maintain user-friendliness.</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> 2023-10-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Xianghttps://github.com/wenzhenxiang Ben77https://github.com/ben2077 Mingshi S.https://github.com/newnewsms https://wg-eips.ritovision.com/7561/

Designed for contract wallet, removes safeTransferFrom, approve, setApprovalForAll, getApproved, isApprovedForAll functions from ERC-721

<h2 id="abstract">Abstract</h2> <p>This ERC is a new NFT asset designed based on the user contract wallet (including account abstraction), and is forward compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. To keep NFT assets simple, this ERC removes the <code>approve</code>, <code>setApprovalForAll</code>, <code>getApproved</code>, <code>isApprovedForAll</code> and <code>safeTransferFrom</code> functions of ERC-721.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/721/">ERC-721</a> defines Ethereum-based standard NFT that can be traded and transferred, but the essence of ERC-721 is based on the externally-owned account (EOA) wallet design. An EOA wallet has no state and code storage, and the smart contract wallet is different.</p> <p>Almost all ERCs related to NFTs are add functions, but our opinion is the opposite. We think the NFT contract should be simpler, with more functions taken care of by the smart contract wallet.</p> <p>Our proposal is to design a simpler NFT asset based on the smart contract wallet.</p> <p>It aims to achieve the following goals:</p> <ol> <li>Keep the NFT contract simple, only responsible for the <code>transferFrom</code> function.</li> <li><code>approve</code>, <code>getApproved</code>, <code>setApprovalForAll</code> and <code>isApprovedForAll</code> functions are not managed by the NFT contract. Instead, these permissions are managed at the user level, offering greater flexibility and control to users. This change not only enhances user autonomy but also mitigates certain risks associated with the ERC-721 contract's implementation of these functions.</li> <li>Remove the <code>safeTransferFrom</code> function. A better way to call the other party's NFT assets is to access the other party's own contract instead of directly accessing the NFT asset contract.</li> <li>Forward compatibility with ERC-721 means that all NFT can be compatible with this proposal.</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>Compliant contracts MUST implement the following 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.20</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"> ERC7561 Simple NFT interface </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://ercs.ethereum.org/ERCS/erc-7561</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"> IERC7561</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"> Used to notify transfer 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"> from</span><span class="z-comment"> Address of the from</span></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 of the receive</span></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 transaction 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"> 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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Count all NFTs 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 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"> number of NFTs owned by `owner`, possibly zero</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"> owner</span><span>)</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> <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">@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-comment"> */</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> </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"> 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></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"> Transfer ownership 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"> from</span><span class="z-comment"> Address of the from</span></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 of the 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"> tokenId</span><span class="z-comment"> The NFT 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 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"> 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>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The proposal is to simplify NFT standards by removing <code>approve</code>, <code>setApprovalForAll</code>, <code>getApproved</code>, <code>isApprovedForAll</code> and <code>safeTransferFrom</code> functions. This simplification aims to enhance security, reduce complexity, and improve efficiency, making the standard more suitable for smart contract wallet environments while maintaining essential functionalities.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As mentioned in the beginning, this ERC is forward compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, ERC-721 is backward compatible with this ERC.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p><strong>forward compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a></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.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;./IERC7561.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;../../math/SafeMath.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"> Standard ERC7561 NFT</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 ERC-165 identifier for this interface is 0xc1b31357</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 the basic standard NFT.</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"> ERC7561</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7561</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Token name</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> private</span><span> _name</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Token symbol</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> private</span><span> _symbol</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> tokenId </span><span class="z-keyword">=&gt;</span><span class="z-support"> address</span><span>)</span><span class="z-storage z-type"> private</span><span> _owners</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> owner </span><span class="z-keyword">=&gt;</span><span class="z-support"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> _balances</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"> private</span><span> _totalSupply</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"> totalSupply</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> _totalSupply</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-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-keyword"> require</span><span> (</span><span>owner </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></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _balances</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"> ownerOf</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-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-entity z-name"> _requireOwned</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 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"> tokenId</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-keyword"> require</span><span>(</span><span>from </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> <span class="giallo-l"><span class="z-keyword"> require</span><span> (</span><span>to </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-support"> address</span><span> previousOwner </span><span class="z-keyword">=</span><span class="z-entity z-name"> _update</span><span>(</span><span>to</span><span>,</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>previousOwner </span><span class="z-keyword">==</span><span> from</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-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"> internal</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">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _owners</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"> _requireOwned</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"> 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> owner </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 class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>owner </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></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-storage z-type"> function</span><span class="z-entity z-name"> _update</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-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> from </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 class="giallo-l"></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Execute the update</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> <span class="giallo-l"><span class="z-keyword"> unchecked</span><span> {</span></span> <span class="giallo-l"><span> _balances</span><span>[</span><span>from</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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>to </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"> unchecked</span><span> {</span></span> <span class="giallo-l"><span> _balances</span><span>[</span><span>to</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></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _owners</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 class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Transfer</span><span>(</span><span>from</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> from</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>It should be noted that this ERC is not backward compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, so there will be incompatibility with existing dapps.</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-25T00:00:00+00:00 2026-02-11T14:48:26+00:00 Shogo Ochiaihttps://github.com/shogochiaishogo.ochiai@pm.me Kai Hiroihttps://github.com/KaiHiroikai.hiroi@pm.me https://wg-eips.ritovision.com/7546/

An upgradeable, cloneable, horizontally extensible proxy pattern.

<h2 id="abstract">Abstract</h2> <p>It has been a significant challenge for developers attempting to create cloneable and upgradeable contracts on the Ethereum Virtual Machine (EVM). While <a href="https://wg-eips.ritovision.com/2535/">ERC-2535</a> Diamonds and other existing proxy standards offer partial solutions, a comprehensive answer has remained elusive. Our proposal addresses this gap through the introduction of two main features.</p> <h3 id="function-level-upgradeability">Function-Level Upgradeability</h3> <p>In alignment with <a href="https://wg-eips.ritovision.com/2535/">ERC-2535</a>, this functionality permits the selective redirection of implementation contracts for individual function calls. This granular control over upgrades allows for modifications on a per-function basis. Moreover, segmenting implementation contracts by function helps mitigate the limitations posed by the contract size cap (24.576kB as of EVM version Shanghai or earlier).</p> <h3 id="factory-clone-friendly-simultaneous-upgradeability">Factory/Clone-Friendly &amp; Simultaneous Upgradeability</h3> <p>Drawing on the Beacon model from <a href="https://wg-eips.ritovision.com/1967/">ERC-1967</a>, our method aims to streamline the process of cloning and updating Proxy contracts simultaneously. This approach is designed to maintain consistent functionality across different instances, each with its own state. Typically, proxies are limited to basic upgradeability features or follow the <a href="https://wg-eips.ritovision.com/1167/">ERC-1167</a> standard. However, our solution combines both functionalities into a compact proxy.</p> <h2 id="motivation">Motivation</h2> <p>Smart contract development often encounters hurdles due to the inherent limitations of the Ethereum Virtual Machine (EVM), such as the contract size limit and stack depth. Additionally, addressing vulnerabilities in both the smart contract logic and its compiler are persistent issues. While there is a desire to minimize reliance on trusted third parties for upgradeability, introducing complex governance structures for upgrade management can significantly increase the workload for crypto DevOps, adding to the apprehension developers may feel towards advancing their projects. This apprehension can restrict the complexity and innovation within smart contract development. Our approach seeks to simplify smart contract programming, making it more accessible and enjoyable. It does so by clearly delineating DevOps concerns from business logic, thereby enhancing codebase clarity, facilitating audits, and allowing for more focused analysis through Language Model (LM) techniques, tailored to specific infrastructure and domain needs.</p> <h3 id="use-cases">Use Cases</h3> <p>Over time, various smart contract design patterns have been proposed and utilized. This <em>Upgradeable Clone Standard (UCS)</em> is intended for scenarios where these existing patterns may not suffice. To clarify it, we define some key terms:</p> <ul> <li><strong>Contract-Level Upgradeability</strong>: One Proxy contract corresponds to one Implementation contract, responsible for all logic of the Proxy.</li> <li><strong>Function-Level Upgradeability</strong>: One Proxy contract corresponds to multiple Implementation contracts, basically each responsible for a specific function.</li> <li><strong>Factory</strong>: A contract that clones Proxies with a common Implementation(s). In the context of upgradeability, it allows for the simultaneous upgrade of these cloned Proxies.</li> </ul> <p>Here are the use cases:</p> <ol> <li>For basic needs without Upgradeability or a Factory, <em>Regular smart contract deployment</em> suffices.</li> <li>When a Factory is needed without Upgradeability, <a href="https://wg-eips.ritovision.com/1167/">ERC-1167</a> is suitable.</li> <li>For Contract-Level Upgradeability without a Factory, <a href="https://wg-eips.ritovision.com/1822/">ERC-1822</a> can be used.</li> <li>For Contract-Level Upgradeability with a Factory, the Beacon from <a href="https://wg-eips.ritovision.com/1967/">ERC-1967</a> is applicable.</li> <li>For Function-Level Upgradeability without a Factory, <a href="https://wg-eips.ritovision.com/2535/">ERC-2535</a> is available.</li> <li>For Function-Level Upgradeability with a Factory, this <em><strong>Upgradeable Clone Standard</strong></em> is the ideal choice.</li> </ol> <p><img src="https://wg-eips.ritovision.com/7546/./assets/images/usecases.svg" alt="Fig. Use Cases" /></p> <h2 id="specification">Specification</h2> <blockquote> <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> </blockquote> <p>In the EVM, contract accounts are characterized by four primary fields: <em>nonce</em>, <em>balance</em>, <em>code</em>, and <em>storage</em>. This ERC's architecture modularizes these functionalities into three distinct types of contracts, each serving a specific purpose when combined to represent a single account:</p> <ol> <li><strong>Proxy Contract</strong>: Maintains the state of the contract account, such as nonce, balance, and storage. This contract delegatecalls to the <em>Function Contract</em> as registered in the <em>Dictionary Contract</em>, ensuring the state and logic are separated but effectively integrated.</li> <li><strong>Dictionary Contract</strong>: Acts as a dispatcher that routes function calls based on their selectors to the appropriate <em>Function Contract</em>. It manages the dynamic aspects of contract behavior, facilitating function upgrades and dynamic addressing. By externalizing this contract from the <em>Proxy Contract</em>, it becomes factory/clone-friendly and supports simultaneous upgradeability.</li> <li><strong>Function (Implementation) Contract</strong>: Implements the executable logic for function calls. When delegatecalled by the <em>Proxy Contract</em>, it performs the actual computations or logic as defined in the contract's code.</li> </ol> <p>This architecture not only aligns with the core attributes of an EVM contract account but also significantly enhances the modularity, upgradeability, and scalability of smart contracts by clarifying account state, function dispatching, and logic implementation.</p> <h3 id="proxy-contract">Proxy Contract</h3> <p>This contract requests the <em>Dictionary Contract</em> to retrieve the associated <em>Function Contract</em> address based on its function selector, and then delegatecall to it.</p> <h4 id="storage-events">Storage &amp; Events</h4> <p>This contract SHOULD store the <em>Dictionary Contract</em> address in the storage slot <code>0x267691be3525af8a813d30db0c9e2bad08f63baecf6dceb85e2cf3676cff56f4</code>, obtained as <code>bytes32(uint256(keccak256('erc7546.proxy.dictionary')) - 1)</code>, in accordance with the method defined in <a href="https://wg-eips.ritovision.com/1967/">ERC-1967</a>. This ensures that the address is stored in a secure and predictable slot.</p> <p>Changes to the Dictionary address SHOULD emit events. When such an event is emitted, it MUST use the signature:</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"> DictionaryUpgraded</span><span>(</span><span class="z-support">address</span><span class="z-variable"> dictionary</span><span>)</span><span>;</span></span></code></pre><h4 id="functions">Functions</h4> <p>For every invocation made via <code>CALL</code> or <code>STATICCALL</code>, this contract MUST perform a delegatecall to the corresponding <em>Function Contract</em> address retrieved from the <em>Dictionary Contract</em> using the <code>getImplementation(bytes4 functionSelector)</code> function. This contract MUST also process the return value from this delegatecall to ensure the intended functionality is executed correctly. Furthermore, to avoid potential collisions with function selectors registered in the <em>Dictionary Contract</em>, the Proxy SHOULD NOT define any external functions.</p> <h3 id="dictionary-contract">Dictionary Contract</h3> <p>This contract manages a mapping of function selectors to corresponding <em>Function Contract</em> addresses. It uses this mapping to handle requests from the <em>Proxy Contract</em>.</p> <h4 id="storage-events-1">Storage &amp; Events</h4> <p>The Dictionary MUST maintain a mapping of function selectors to <em>Function Contract</em> addresses.</p> <p>Changes to this mapping SHOULD be communicated through an event (or log).</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"> ImplementationUpgraded</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> functionSelector</span><span>, </span><span class="z-support">address</span><span class="z-variable"> implementation</span><span>)</span><span>;</span></span></code></pre><h4 id="functions-1">Functions</h4> <h5 id="getimplementation"><code>getImplementation</code></h5> <p>This contract MUST implement this function to return <em>Function Implementation Contract</em> 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"> getImplementation</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> functionSelector</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"> implementation</span><span>)</span><span>;</span></span></code></pre><h5 id="setimplementation"><code>setImplementation</code></h5> <p>This contract SHOULD implement this function to update or add new function selectors and their corresponding <em>Function Implementation Contract</em> addresses to the mapping.</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"> setImplementation</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> functionSelector</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> implementation</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre><h5 id="supportsinterface"><code>supportsInterface</code></h5> <p>This contract is RECOMMENDED to implement the <code>supportsInterface(bytes4 interfaceID)</code> function defined in <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> to indicate which interfaces are supported by the contracts referenced in the mapping.</p> <h5 id="supportsinterfaces"><code>supportsInterfaces</code></h5> <p>This contract is RECOMMENDED to implement the <code>supportsInterfaces()</code> to return a list of registered interfaceIDs.</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"> supportsInterfaces</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">bytes4</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre><h3 id="function-implementation-contract">Function (Implementation) Contract</h3> <p>This contract acts as the logic implementation contract that the <em>Proxy Contract</em> delegatecalls and it's address is registered with the function selector in the <em>Dictionary Contract</em>.</p> <h4 id="storage-events-2">Storage &amp; Events</h4> <p>This contract SHOULD NOT use its storage but SHOULD store to the <em>Proxy Contract</em> through delegatecall.</p> <p>The <em>Proxy Contract</em> shares storage layout with several <em>Function Contracts</em>. For example, using sequential slot allocation starting from slot 0, as is the default compiler option, can lead to storage conflicts.</p> <p>In order to prevent storage conflict, this contract MUST manage the storage layout properly. The matter of storage management techniques has been a subject of debate for years, both at the ERC level and the language level. However, there is still no definitive standard. Therefore, this ERC does not go into the specifics of storage management techniques.</p> <p>It is RECOMMENDED to choose the storage management method that is considered most appropriate at the time.</p> <p>For instance, the storage could be arranged according to useful storage layout patterns, such as <em><strong><a href="https://wg-eips.ritovision.com/7201/">ERC-7201</a></strong></em>.</p> <h4 id="functions-2">Functions</h4> <p>This contract MUST have the same function selector registered in the <em>Dictionary Contract</em>. If not, the Proxy's delegatecall will fail. So it is RECOMMENDED for each <em>Function Contract</em> to implement ERC-165's <code>supportsInterface(bytes4 interfaceID)</code> to ensure that it correctly implements the function selector being registered when added to the Dictionary.</p> <h2 id="rationale">Rationale</h2> <h3 id="comparison-with-erc-2535">Comparison with <a href="https://wg-eips.ritovision.com/2535/">ERC-2535</a></h3> <p>While both this ERC and ERC-2535 offer <a href="https://wg-eips.ritovision.com/7546/#function-level-upgradeability">Function-Level Upgradeability</a>, there is a key distinction in their approaches. ERC-2535 maintains a mapping of implementation contracts (referred to as Facets in ERC-2535) within the Proxy itself. In contrast, this ERC stores the mapping in an external <em>Dictionary Contract</em>. This externalization of the mapping facilitates another significant feature of this standard: <a href="https://wg-eips.ritovision.com/7546/#factory-clone-friendly-simultaneous-upgradeability">Factory/Clone-Friendly &amp; Simultaneous Upgradeability</a>. By separating the mapping from the Proxy, this design allows for easier cloning of contracts and their simultaneous upgrade, which is not as straightforward in the ERC-2535 framework.</p> <p><img src="https://wg-eips.ritovision.com/7546/./assets/images/comparison-with-diamond.svg" alt="Fig. Comparison with Diamond" /></p> <h3 id="separating-the-dictionary-and-proxy-contracts">Separating the Dictionary and Proxy contracts:</h3> <p>The separation of the Dictionary from the Proxy was driven by aligning with <a href="https://wg-eips.ritovision.com/7546/#factory-clone-friendly-simultaneous-upgradeability">Factory/Clone-Friendly &amp; Simultaneous Upgradeability</a>.</p> <p>To achieve this, the management functionality of <em>Function Implementation Contract</em> addresses were externalized as the <em>Dictionary Contract</em> instead of including them within the <em>Proxy Contract</em>, a concept akin to the Beacon Proxy approach.</p> <p>If the functionality is within the <em>Proxy Contract</em>, each proxy requires its implementation to be upgraded. By externalizing this, a common implementation can be cloned and upgraded simultaneously.</p> <p><img src="https://wg-eips.ritovision.com/7546/./assets/images/comparison-with-beacon.svg" alt="Fig. Comparison with Beacon" /></p> <h3 id="utilizing-the-mapping-of-function-selectors-and-implementation-addresses">Utilizing the mapping of function selectors and implementation addresses:</h3> <p>The utilization of the mapping of function selectors to corresponding <em>Function Implementation Contract</em> addresses of the <em>Dictionary Contract</em> by the <em>Proxy Contract</em>, followed by delegatecalling to the returned implementation address, aligns with <a href="https://wg-eips.ritovision.com/7546/#function-level-upgradeability">Function-Level Upgradeability</a>.</p> <p>By adopting this approach, the Proxy emulates the behavior of possessing a set of <em>Function Implementation Contracts</em> registered within the <em>Dictionary Contract</em>. This specification closely resembles the pattern outlined in the Diamond Standard.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>There are reference implementations and tests as a foundry project.</p> <p>It includes the following contents:</p> <ul> <li>Reference Implementations <ul> <li><a href="https://wg-eips.ritovision.com/7546/./assets/src/Proxy.sol">Proxy Contract</a></li> <li><a href="https://wg-eips.ritovision.com/7546/./assets/src/Dictionary.sol">Dictionary Contract</a></li> </ul> </li> <li>Tests <ul> <li><a href="https://wg-eips.ritovision.com/7546/./assets/test/Proxy.spec.t.sol">Proxy Spec Test</a></li> <li><a href="https://wg-eips.ritovision.com/7546/./assets/test/Dictionary.spec.t.sol">Dictionary Spec Test</a></li> <li><a href="https://wg-eips.ritovision.com/7546/./assets/test/UCS.usecase.t.sol">UCS Usecase Test</a></li> </ul> </li> </ul> <h2 id="security-considerations">Security Considerations</h2> <h3 id="delegation-of-implementation-management">Delegation of Implementation Management</h3> <p>This pattern of delegating all implementations for every call to the <em>Dictionary Contract</em> relies on the assumption that the <em>Dictionary Contract</em>'s admin acts in good faith and does not introduce vulnerabilities through negligence.</p> <p>You should not connect your proxy with the <em>Dictionary Contract</em> provided by an untrusted admin. Moreover, providing an option to switch to another <em>Dictionary Contract</em> managed by a different (or potentially more trustworthy) admin is recommended.</p> <p>While it is possible to store the <em>Dictionary Contract</em> address in the code area (e.g., using Solidity's immutable or constant), it SHOULD be designed with caution, considering the possibility that if the <em>Dictionary Contract</em>'s admin is not the same as the <em>Proxy Contract</em>'s admin, the ability to manipulate the implementation could be permanently lost.</p> <h3 id="storage-conflict">Storage Conflict</h3> <p>As mentioned in the above <a href="https://wg-eips.ritovision.com/7546/#storage-events">Storage section</a>. This design pattern involves multiple <em>Function Implementation Contracts</em> sharing a single <em>Proxy Contract</em> storage. Therefore, it's important to take care for preventing storage conflicts by using the storage management method that is considered most appropriate at the time.</p> <h3 id="mismatch-function-selector">Mismatch Function Selector</h3> <p>The <em>Dictionary Contract</em> returns the <em>Function Implementation Contract</em> address based on the <em>Proxy Contract</em>'s invoked function selector.</p> <p>If there is a mismatch between function selectors registered in the <em>Dictionary Contract</em> and those implemented in the <em>Function Implementation Contract</em>, the execution will fail. To prevent unexpected behavior, it's recommended to check that the <em>Function Implementation Contract</em> includes the function selector (interface) being registered during the process for setting implementation address to the <em>Dictionary Contract</em>.</p> <h3 id="handling-of-call-and-staticcall">Handling of CALL and STATICCALL</h3> <p>The <em>Proxy Contract</em> is designed primarily to respond to <code>CALL</code> and <code>STATICCALL</code> opcodes. Should a <code>DELEGATECALL</code> be made to this <em>Proxy Contract</em>, it will attempt to request the <em>Dictionary Contract</em> for a corresponding implementation via the <code>getImplementation(bytes4 functionSelector)</code> function, using the stored <em>Dictionary Contract</em> address within its own storage. Although this action may not lead to the intended outcome if the calling contract's storage layout does not align with expectations, it does not constitute a direct threat to the <em>Proxy Contract</em> itself. Developers are cautioned that invoking this <em>Proxy Contract</em> via <code>DELEGATECALL</code> could result in unexpected and potentially non-functional outcomes, making it an unsuitable method for interaction.</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-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ahmad Bitarhttps://github.com/smartprogrammer93smartprogrammer@windowslive.com https://wg-eips.ritovision.com/7542/

Adds more info in the handshake about available block range and adds message types to request block ranges and the send them

<h2 id="abstract">Abstract</h2> <p>The purpose of this EIP is to introduce a method that allows an Ethereum node to communicate the range of blocks it has available. By knowing the block range a node can serve, peers can make more informed decisions when choosing whom to request blocks from or whom to connect to, especially when looking for specific block ranges. This can lead to more efficient network behavior.</p> <p>This EIP proposes extending the Ethereum wire protocol (<code>eth</code>) handshake, introducing a new version, <code>eth/70</code>, which will contain information regarding the block range a node can serve. Furthermore, it extends the protocol with two new message types to share the updated block ranges when requested.</p> <h2 id="motivation">Motivation</h2> <p>In a first stage of <a href="https://wg-eips.ritovision.com/4444/">EIP-4444</a>, some nodes will still need to serve the historical data of the chain and others might be interested in starting to prune it. Currently, nodes need to connect to peers and request specific blocks to determine if a peer has the requested data. This can be inefficient, leading to unnecessary data requests and wasting both bandwidth and time. Consequently, this change empowers nodes that still want to retrieve historical data from the network to do so efficiently.</p> <p>As a bonus, This change enhances the efficiency of synchronization by allowing a node to determine if a peer, potentially still in the process of syncing, has the necessary blocks available, thereby avoiding unnecessary block requests and potential empty responses.</p> <h2 id="specification">Specification</h2> <ul> <li> <p>Advertise a new <code>eth</code> protocol capability (version) at <code>eth/70</code>.</p> <ul> <li>The old <code>eth/69</code> protocol should still be kept alive side-by-side, until <code>eth/70</code> is sufficiently adopted by implementors.</li> </ul> </li> <li> <p>Modify the <code>Status (0x00)</code> message for <code>eth/70</code> to add an additional <code>blockRange</code> field right after the <code>forkid</code>:</p> <ul> <li>Current packet for <code>eth/69</code>: <code>[version: P, networkid: P, blockhash: B_32, genesis: B_32, forkid]</code></li> <li>New packet for <code>eth/70</code>: <code>[version: P, networkid: P, blockhash: B_32, genesis: B_32, forkid blockRange]</code>, where <code>blockRange</code> is <code>[startBlock: uint64, endBlock: uint64]</code>.</li> </ul> </li> <li> <p>Introduce two new message types:</p> <ul> <li><code>RequestBlockRange (0x0b)</code> - A message from a node to request the current block range of a peer.</li> <li><code>SendBlockRange (0x0c): [startBlock: uint64, endBlock: uint64]</code> - The response to <code>RequestBlockRange</code>, informing the requesting node of the current available block range of the peer.</li> </ul> </li> </ul> <p>Upon connecting using <code>eth/70</code>, nodes should exchange the <code>Status</code> message. Afterwards, they can use the <code>RequestBlockRange</code> and <code>SendBlockRange</code> messages to keep informed about peer block range changes.</p> <p>Nodes must retain connections regardless of a peer's available block range, with an exception, if a node's peer slots are full and it lacks connections to peers with the necessary block range, it may disconnect to seek such peers.</p> <h2 id="rationale">Rationale</h2> <p>Including the available block range in the <code>eth</code> handshake allows for immediate understanding of peer capabilities. This can lead to more efficient networking as nodes can prioritize connections based on the data they need. The new message types are introduced to allow nodes to request updated available block range from other nodes since the range can change by the node syncing or pruning blocks. Maintaining connections with peers that don't have the desired range ensures network resilience, while the exception facilitates efficient block sync under full peer capacity.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP extends the <code>eth</code> protocol handshake in a backwards incompatible manner and proposes the introduction of a new version, <code>eth/70</code>. However, <code>devp2p</code> allows for multiple versions of the same wire protocol to run concurrently. Hence, nodes that have not been updated can continue using older versions like <code>eth/69</code>, <code>eth/68</code> or <code>eth/67</code>.</p> <p>This EIP doesn't affect the consensus engine and doesn't necessitate a hard fork.</p> <h2 id="test-cases">Test Cases</h2> <p>Testing will involve ensuring that nodes can correctly communicate and understand the block range information during the handshake. Additionally, it will involve ensuring nodes can correctly request and share updated block range when requested.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This change is not a standardization of not storing and serving historical blocks before the implementation of alternative historical blocks storage solutions.</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-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/7538/

Incorporates a multiplier field to ERC-20 and ERC-1155 for fractional token values

<h2 id="abstract">Abstract</h2> <p>This EIP extends <a href="https://wg-eips.ritovision.com/1046/">ERC-1046</a>-compatible token types (notably, <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> by introducing a <code>multiplier</code> field to the metadata schema, altering how user-facing balances are displayed.</p> <h2 id="motivation">Motivation</h2> <p>Many projects necessitate the creation of various types of tokens, both fungible and non-fungible. While certain standards are ideal for this purpose, they lack support for fractional tokens. Additionally, some tokens may require built-in inflation or deflation mechanisms, or may wish to allow transfers in unconventional increments, such as <code>0.5</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>The <code>MultiplierMetadata</code> interface MUST be implemented in the resolved ERC-1046 <code>tokenURI</code> of tokens that use a <code>multiplier</code>:</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"> MultiplierMetadata</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"> * The positive multiplier for generating user-facing representation.</span></span> <span class="giallo-l"><span class="z-comment"> * Defaults to 1 if undefined.</span></span> <span class="giallo-l"><span class="z-comment"> * This is an EXACT VALUE, base 10. Beware of floating-point error!</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-variable"> multiplier</span><span class="z-keyword">:</span><span class="z-support"> string</span><span class="z-keyword"> |</span><span class="z-support"> undefined</span><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"> * Decimals are no longer supported</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-variable"> decimals</span><span class="z-keyword">:</span><span class="z-support"> never</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Token contracts MUST NOT have a method named <code>decimals</code> if a <code>multiplier</code> is used.</p> <h2 id="rationale">Rationale</h2> <p>Employing strings for numerical representation offers enhanced precision when needed. The use of a multiplier instead of decimals facilitates increments other than powers of 10, and ensures seamless handling of inflation or deflation. Utilizing ERC-1046 promotes gas efficiency in the majority of cases.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is incompatible with any method named <code>decimals</code> in ERC-1046-compatible token standards or the ERC-1046 <code>decimals</code> field.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Improper handling of the <code>multiplier</code> field may lead to rounding errors, potentially exploitable by malicious actors. Contracts MUST process multipliers accurately to avoid such issues. The multiplier MUST be positive (‘0’ is not positive) to avert display issues. Particularly large or small multipliers MAY pose display challenges, yet wallets SHOULD endeavor to display the full number without causing UI/UX or additional 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> 2023-10-18T00:00:00+00:00 2026-02-11T14:48:26+00:00 Jeroen Offerijnshttps://github.com/hieronx Alina Sinelnikovahttps://github.com/ilinzweilin Vikram Arunhttps://github.com/vikramarun Joey Santorohttps://github.com/joeysantoro Farhaan Alihttps://github.com/0xfarhaan João Martinshttps://github.com/0xTimepunk https://wg-eips.ritovision.com/7540/

Extension of ERC-4626 with asynchronous deposit and redemption support

<h2 id="abstract">Abstract</h2> <p>The following standard extends <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> by adding support for asynchronous deposit and redemption flows. The async flows are called Requests.</p> <p>New methods are added to asynchronously Request a deposit or redemption, and view the status of the Request. The existing <code>deposit</code>, <code>mint</code>, <code>withdraw</code>, and <code>redeem</code> ERC-4626 methods are used for executing Claimable Requests.</p> <p>Implementations can choose whether to add asynchronous flows for deposits, redemptions, or both.</p> <h2 id="motivation">Motivation</h2> <p>The ERC-4626 Tokenized Vaults standard has helped to make yield-bearing tokens more composable across decentralized finance. The standard is optimized for atomic deposits and redemptions up to a limit. If the limit is reached, no new deposits or redemptions can be submitted.</p> <p>This limitation does not work well for any smart contract system with asynchronous actions or delays as a prerequisite for interfacing with the Vault (e.g. real-world asset protocols, undercollateralized lending protocols, cross-chain lending protocols, liquid staking tokens, or insurance safety modules).</p> <p>This standard expands the utility of ERC-4626 Vaults for asynchronous use cases. The existing Vault interface (<code>deposit</code>/<code>withdraw</code>/<code>mint</code>/<code>redeem</code>) is fully utilized to claim asynchronous Requests.</p> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions:</h3> <p>The existing definitions from <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> apply. In addition, this spec defines:</p> <ul> <li>Request: a request to enter (<code>requestDeposit</code>) or exit (<code>requestRedeem</code>) the Vault</li> <li>Pending: the state where a Request has been made but is not yet Claimable</li> <li>Claimable: the state where a Request is processed by the Vault enabling the user to claim corresponding <code>shares</code> (for async deposit) or <code>assets</code> (for async redeem)</li> <li>Claimed: the state where a Request is finalized by the user and the user receives the output token (e.g. <code>shares</code> for a deposit Request)</li> <li>Claim function: the corresponding Vault method to bring a Request to Claimed state (e.g. <code>deposit</code> or <code>mint</code> claims <code>shares</code> from <code>requestDeposit</code>). Lowercase claim always describes the verb action of calling a Claim function.</li> <li>asynchronous deposit Vault: a Vault that implements asynchronous Requests for deposit flows</li> <li>asynchronous redemption Vault: a Vault that implements asynchronous Requests for redemption flows</li> <li>fully asynchronous Vault: a Vault that implements asynchronous Requests for both deposit and redemption flows</li> <li>controller: owner of the Request, who can manage any actions related to the Request including claiming the <code>assets</code> or <code>shares</code></li> <li>operator: an account that can manage Requests on behalf of another account.</li> </ul> <h3 id="request-flows">Request Flows</h3> <p><a href="https://wg-eips.ritovision.com/7540/">ERC-7540 Vaults</a> MUST implement one or both of asynchronous deposit and redemption Request flows. If either flow is not implemented in a Request pattern, it MUST use the ERC-4626 standard synchronous interaction pattern.</p> <p>All ERC-7540 asynchronous tokenized Vaults MUST implement ERC-4626 with overrides for certain behavior described below.</p> <p>Asynchronous deposit Vaults MUST override the ERC-4626 specification as follows:</p> <ol> <li>The <code>deposit</code> and <code>mint</code> methods do not transfer <code>assets</code> to the Vault, because this already happened on <code>requestDeposit</code>.</li> <li><code>previewDeposit</code> and <code>previewMint</code> MUST revert for all callers and inputs.</li> </ol> <p>Asynchronous redeem Vaults MUST override the ERC-4626 specification as follows:</p> <ol> <li>The <code>redeem</code> and <code>withdraw</code> methods do not transfer <code>shares</code> to the Vault, because this already happened on <code>requestRedeem</code>.</li> <li>The <code>owner</code> field of <code>redeem</code> and <code>withdraw</code> SHOULD be renamed to <code>controller</code>, and the controller MUST be <code>msg.sender</code> unless the <code>controller</code> has approved the <code>msg.sender</code> as an operator.</li> <li><code>previewRedeem</code> and <code>previewWithdraw</code> MUST revert for all callers and inputs.</li> </ol> <h3 id="request-lifecycle">Request Lifecycle</h3> <p>After submission, Requests go through Pending, Claimable, and Claimed stages. An example lifecycle for a deposit Request is visualized in the table below.</p> <table><thead><tr><th><strong>State</strong></th><th><strong>User</strong></th><th><strong>Vault</strong></th></tr></thead><tbody> <tr><td>Pending</td><td><code>requestDeposit(assets, controller, owner)</code></td><td><code>asset.transferFrom(owner, vault, assets)</code>; <code>pendingDepositRequest[controller] += assets</code></td></tr> <tr><td>Claimable</td><td></td><td><em>Internal Request fulfillment</em>: <code>pendingDepositRequest[controller] -= assets</code>; <code>claimableDepositRequest[controller] += assets</code></td></tr> <tr><td>Claimed</td><td><code>deposit(assets, receiver, controller)</code></td><td><code>claimableDepositRequest[controller] -= assets</code>; <code>vault.balanceOf[receiver] += shares</code></td></tr> </tbody></table> <p>Note that <code>maxDeposit</code> increases and decreases in sync with <code>claimableDepositRequest</code>.</p> <p>Requests MUST NOT skip or otherwise short-circuit the Claim state. In other words, to initiate and claim a Request, a user MUST call both request* and the corresponding Claim function separately, even in the same block. Vaults MUST NOT "push" tokens onto the user after a Request, users MUST "pull" the tokens via the Claim function.</p> <p>For asynchronous Vaults, the exchange rate between <code>shares</code> and <code>assets</code> including fees and yield is up to the Vault implementation. In other words, pending redemption Requests MAY NOT be yield-bearing and MAY NOT have a fixed exchange rate.</p> <h3 id="request-ids">Request Ids</h3> <p>The request ID (<code>requestId</code>) of a request is returned by the corresponding <code>requestDeposit</code> and <code>requestRedeem</code> functions.</p> <p>Multiple requests may have the same <code>requestId</code>, so a given Request is discriminated by both the <code>requestId</code> and the <code>controller</code>.</p> <p>Requests of the same <code>requestId</code> MUST be fungible with each other (except in the special case <code>requestId == 0</code> described below). I.e. all Requests with the same <code>requestId</code> MUST transition from Pending to Claimable at the same time and receive the same exchange rate between <code>assets</code> and <code>shares</code>. If a Request with <code>requestId != 0</code> becomes partially claimable, all requests of the same <code>requestId</code> MUST become claimable at the same pro-rata rate.</p> <p>There are no assumptions or requirements of requests with different <code>requestId</code>. I.e. they MAY transition to Claimable at different times and exchange rates with no ordering or correlation enforced in any way.</p> <p>When <code>requestId==0</code>, the Vault MUST use purely the <code>controller</code> to discriminate the request state. The Pending and Claimable state of multiple requests from the same <code>controller</code> would be aggregated. If a Vault returns <code>0</code> for the <code>requestId</code> of any request, it MUST return <code>0</code> for all requests.</p> <h3 id="methods">Methods</h3> <h4 id="requestdeposit">requestDeposit</h4> <p>Transfers <code>assets</code> from <code>owner</code> into the Vault and submits a Request for asynchronous <code>deposit</code>. This places the Request in Pending state, with a corresponding increase in <code>pendingDepositRequest</code> for the amount <code>assets</code>.</p> <p>The output <code>requestId</code> is used to partially discriminate the request along with the <code>controller</code>. See <a href="https://wg-eips.ritovision.com/7540/#request-ids">Request Ids</a> section for more info.</p> <p>When the Request is Claimable, <code>claimableDepositRequest</code> will be increased for the <code>controller</code>. <code>deposit</code> or <code>mint</code> can subsequently be called by <code>controller</code> to receive <code>shares</code>. A Request MAY transition straight to Claimable state but MUST NOT skip the Claimable state.</p> <p>The <code>shares</code> that will be received on <code>deposit</code> or <code>mint</code> MAY NOT be equivalent to the value of <code>convertToShares(assets)</code> at the time of Request, as the price can change between Request and Claim.</p> <p>MUST support <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> <code>approve</code> / <code>transferFrom</code> on <code>asset</code> as a deposit Request flow.</p> <p><code>owner</code> MUST equal <code>msg.sender</code> unless the <code>owner</code> has approved the <code>msg.sender</code> as an operator.</p> <p>MUST revert if all of <code>assets</code> cannot be requested for <code>deposit</code>/<code>mint</code> (due to deposit limit being reached, slippage, the user not approving enough underlying tokens to the Vault contract, etc).</p> <p>Note that most implementations will require pre-approval of the Vault with the Vault's underlying <code>asset</code> token.</p> <p>MUST emit the <code>DepositRequest</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"> r</span><span class="z-string">equestDeposit</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"> c</span><span class="z-string">ontroller</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 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"> r</span><span class="z-string">equestId</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="pendingdepositrequest">pendingDepositRequest</h4> <p>The amount of requested <code>assets</code> in Pending state for the <code>controller</code> with the given <code>requestId</code> to <code>deposit</code> or <code>mint</code>.</p> <p>MUST NOT include any <code>assets</code> in Claimable state for <code>deposit</code> or <code>mint</code>.</p> <p>MUST NOT show any variations depending on the caller.</p> <p>MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</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">endingDepositRequest</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"> r</span><span class="z-string">equestId</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"> c</span><span class="z-string">ontroller</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"> 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="claimabledepositrequest">claimableDepositRequest</h4> <p>The amount of requested <code>assets</code> in Claimable state for the <code>controller</code> with the given <code>requestId</code> to <code>deposit</code> or <code>mint</code>.</p> <p>MUST NOT include any <code>assets</code> in Pending state for <code>deposit</code> or <code>mint</code>.</p> <p>MUST NOT show any variations depending on the caller.</p> <p>MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</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">laimableDepositRequest</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"> r</span><span class="z-string">equestId</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"> c</span><span class="z-string">ontroller</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"> 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="requestredeem">requestRedeem</h4> <p>Assumes control of <code>shares</code> from <code>owner</code> and submits a Request for asynchronous <code>redeem</code>. This places the Request in Pending state, with a corresponding increase in <code>pendingRedeemRequest</code> for the amount <code>shares</code>.</p> <p>The output <code>requestId</code> is used to discriminate the request along with the <code>controller</code>. See <a href="https://wg-eips.ritovision.com/7540/#request-ids">Request Ids</a> section for more info.</p> <p><code>shares</code> MAY be temporarily locked in the Vault until the Claimable or Claimed state for accounting purposes, or they MAY be burned immediately upon <code>requestRedeem</code>.</p> <p>In either case, the <code>shares</code> MUST be removed from the custody of <code>owner</code> upon <code>requestRedeem</code> and burned by the time the request is Claimed.</p> <p>Redeem Request approval of <code>shares</code> for a <code>msg.sender</code> NOT equal to <code>owner</code> may come either from ERC-20 approval over the <code>shares</code> of <code>owner</code> or if the <code>owner</code> has approved the <code>msg.sender</code> as an operator. This MUST be consistent with similar behaviour pointed out in <a href="https://wg-eips.ritovision.com/6909/">ERC-6909</a>, within "Approvals and Operators" section: "In accordance with the transferFrom method, spenders with operator permission are not subject to allowance restrictions, spenders with infinite approvals SHOULD NOT have their allowance deducted on delegated transfers, but spenders with non-infinite approvals MUST have their balance deducted on delegated transfers."</p> <p>When the Request is Claimable, <code>claimableRedeemRequest</code> will be increased for the <code>controller</code>. <code>redeem</code> or <code>withdraw</code> can subsequently be called by <code>controller</code> to receive <code>assets</code>. A Request MAY transition straight to Claimable state but MUST NOT skip the Claimable state.</p> <p>The <code>assets</code> that will be received on <code>redeem</code> or <code>withdraw</code> MAY NOT be equivalent to the value of <code>convertToAssets(shares)</code> at the time of Request, as the price can change between Pending and Claimed.</p> <p>MUST revert if all of <code>shares</code> cannot be requested for <code>redeem</code> / <code>withdraw</code> (due to withdrawal limit being reached, slippage, the owner not having enough shares, etc).</p> <p>MUST emit the <code>RedeemRequest</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"> r</span><span class="z-string">equestRedeem</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"> c</span><span class="z-string">ontroller</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 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"> r</span><span class="z-string">equestId</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"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="pendingredeemrequest">pendingRedeemRequest</h4> <p>The amount of requested <code>shares</code> in Pending state for the <code>controller</code> with the given <code>requestId</code> to <code>redeem</code> or <code>withdraw</code>.</p> <p>MUST NOT include any <code>shares</code> in Claimable state for <code>redeem</code> or <code>withdraw</code>.</p> <p>MUST NOT show any variations depending on the caller.</p> <p>MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</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">endingRedeemRequest</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"> r</span><span class="z-string">equestId</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"> c</span><span class="z-string">ontroller</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"> 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="claimableredeemrequest">claimableRedeemRequest</h4> <p>The amount of requested <code>shares</code> in Claimable state for the <code>controller</code> with the given <code>requestId</code> to <code>redeem</code> or <code>withdraw</code>.</p> <p>MUST NOT include any <code>shares</code> in Pending state for <code>redeem</code> or <code>withdraw</code>.</p> <p>MUST NOT show any variations depending on the caller.</p> <p>MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</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">laimableRedeemRequest</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"> r</span><span class="z-string">equestId</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"> c</span><span class="z-string">ontroller</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"> 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="isoperator"><code>isOperator</code></h4> <p>Returns <code>true</code> if the <code>operator</code> is approved as an operator for a <code>controller</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">sOperator</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"> c</span><span class="z-string">ontroller</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">perator</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"> s</span><span class="z-string">tatus</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="setoperator"><code>setOperator</code></h4> <p>Grants or revokes permissions for <code>operator</code> to manage Requests on behalf of the <code>msg.sender</code>.</p> <p>MUST set the operator status to the <code>approved</code> value.</p> <p>MUST log the <code>OperatorSet</code> event.</p> <p>MUST return True.</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"> s</span><span class="z-string">etOperator</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"> o</span><span class="z-string">perator</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">pproved</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 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">uccess</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="deposit-and-mint-overloaded-methods"><code>deposit</code> and <code>mint</code> overloaded methods</h4> <p>Implementations MUST support an additional overloaded <code>deposit</code> and <code>mint</code> method on the specification from <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a>, with an additional <code>controller</code> input of type <code>address</code>:</p> <ul> <li><code>deposit(uint256 assets, address receiver, address controller)</code></li> <li><code>mint(uint256 shares, address receiver, address controller)</code></li> </ul> <p>Calls MUST revert unless <code>msg.sender</code> is either equal to <code>controller</code> or an operator approved by <code>controller</code>.</p> <p>The <code>controller</code> field is used to discriminate the Request for which the <code>assets</code> should be claimed in the case where <code>msg.sender</code> is NOT <code>controller</code>.</p> <p>When the <code>Deposit</code> event is emitted, the first parameter MUST be the <code>controller</code>, and the second parameter MUST be the <code>receiver</code>.</p> <h3 id="events">Events</h3> <h4 id="depositrequest">DepositRequest</h4> <p><code>owner</code> has locked <code>assets</code> in the Vault to Request a deposit with request ID <code>requestId</code>. <code>controller</code> controls this Request. <code>sender</code> is the caller of the <code>requestDeposit</code> which may not be equal to the <code>owner</code>.</p> <p>MUST be emitted when a deposit Request is submitted using the <code>requestDeposit</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"> D</span><span class="z-string">epositRequest</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"> c</span><span class="z-string">ontroller</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"> o</span><span class="z-string">wner</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"> r</span><span class="z-string">equestId</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"> s</span><span class="z-string">ender</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"> a</span><span class="z-string">ssets</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><h4 id="redeemrequest">RedeemRequest</h4> <p><code>sender</code> has locked <code>shares</code>, owned by <code>owner</code>, in the Vault to Request a redemption. <code>controller</code> controls this Request, but is not necessarily the <code>owner</code>.</p> <p>MUST be emitted when a redemption Request is submitted using the <code>requestRedeem</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">edeemRequest</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"> c</span><span class="z-string">ontroller</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"> o</span><span class="z-string">wner</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"> r</span><span class="z-string">equestId</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"> s</span><span class="z-string">ender</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"> s</span><span class="z-string">hares</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><h4 id="operatorset"><code>OperatorSet</code></h4> <p>The <code>controller</code> has set the <code>approved</code> status to an <code>operator</code>.</p> <p>MUST be logged when the operator status is set.</p> <p>MAY be logged when the operator status is set to the same status it was before the current call.</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"> O</span><span class="z-string">peratorSet</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"> c</span><span class="z-string">ontroller</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"> o</span><span class="z-string">perator</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">pproved</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><h3 id="erc-165-support"><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> support</h3> <p>Smart contracts implementing this Vault standard MUST implement the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> <code>supportsInterface</code> function.</p> <p>All asynchronous Vaults MUST return the constant value <code>true</code> if either <code>0xe3bc4e65</code> (representing the operator methods that all ERC-7540 Vaults implement) or <code>0x2f0a18c5</code> (representing the <a href="https://wg-eips.ritovision.com/7575/">ERC-7575</a> interface) is passed through the <code>interfaceID</code> argument.</p> <p>Asynchronous deposit Vaults MUST return the constant value <code>true</code> if <code>0xce3bbe50</code> is passed through the <code>interfaceID</code> argument.</p> <p>Asynchronous redemption Vaults MUST return the constant value <code>true</code> if <code>0x620ee8e4</code> is passed through the <code>interfaceID</code> argument.</p> <h3 id="erc-7575-support"><a href="https://wg-eips.ritovision.com/7575/">ERC-7575</a> support</h3> <p>Smart contracts implementing this Vault standard MUST implement the <a href="https://wg-eips.ritovision.com/7575/">ERC-7575</a> standard (in particular the <code>share</code> method).</p> <h2 id="rationale">Rationale</h2> <h3 id="including-request-ids-but-not-including-a-claim-by-id-method">Including Request IDs but not including a Claim by ID method</h3> <p>Requests in an Asynchronous Vault have properties of NFTs or Semi-Fungible tokens due to their asynchronicity. However, trying to pigeonhole all ERC-7540 Vaults into supporting <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> for Requests would create too much interface bloat.</p> <p>Using both an id and address to discriminate Requests allows for any of these use cases to be developed at an external layer without adding too much complexity to the core interface.</p> <p>Certain Vaults, especially <code>requestId==0</code> cases, benefit from using the underlying <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> methods for claiming because there is no discrimination at the <code>requestId</code> level. This standard is written primarily with those use cases in mind. A future standard can optimize for nonzero request ID with support for claiming and transferring requests discriminated also with a <code>requestId</code>.</p> <h3 id="symmetry-and-non-inclusion-of-requestwithdraw-and-requestmint">Symmetry and Non-inclusion of requestWithdraw and requestMint</h3> <p>In ERC-4626, the spec was written to be fully symmetrical with respect to converting <code>assets</code> and <code>shares</code> by including deposit/withdraw and mint/redeem.</p> <p>Due to the nature of Requests, asynchronous Vaults can only operate with certainty on the quantity that is fully known at the time of the Request (<code>assets</code> for <code>deposit</code> and <code>shares</code> for <code>redeem</code>). Therefore the deposit Request flow cannot work with a <code>mint</code> call, because the amount of <code>assets</code> for the requested <code>shares</code> amount may fluctuate before the fulfillment of the Request. Likewise, the redemption Request flow cannot work with a <code>withdraw</code> call.</p> <h3 id="optionality-of-flows">Optionality of Flows</h3> <p>Certain use cases are only asynchronous on one side of the deposit or redeem Request flow. A good example of an asynchronous redemption Vault is a liquid staking token. The unstaking period necessitates support for asynchronous withdrawals, however, deposits can be fully synchronous.</p> <h3 id="non-inclusion-of-a-request-cancelation-flow">Non-inclusion of a Request Cancelation Flow</h3> <p>In many cases, canceling a Request may not be straightforward or even technically feasible. The state transition of cancelations could be synchronous or asynchronous, and the way to claim a cancelation interfaces with the remaining Vault functionality in complex ways.</p> <p>A separate EIP should be developed to standardize the behavior of cancelling a pending Request. Defining the cancel flow is still important for certain classes of use cases for which the fulfillment of a Request can take a considerable amount of time.</p> <h3 id="request-implementation-flexibility">Request Implementation Flexibility</h3> <p>The standard is flexible enough to support a wide range of interaction patterns for Request flows. Pending Requests can be handled via internal accounting, globally or on per-user levels, use ERC-20 or <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, etc.</p> <p>Likewise yield on redemption Requests can accrue or not, and the exchange rate of any Request may be fixed or variable depending on the implementation.</p> <h3 id="not-allowing-short-circuiting-for-claims">Not Allowing Short-circuiting for Claims</h3> <p>If claims can short-circuit, this creates ambiguity for integrators and complicates the interface with overloaded behavior on Request functions.</p> <p>An example of a short-circuiting Request flow could be as follows: user triggers a Request which enters Pending state. When the Vault fulfills the Request, the corresponding <code>assets/shares</code> are pushed straight to the user. This requires only 1 step on the user's behalf.</p> <p>This approach has a few issues:</p> <ul> <li>cost/lack of scalability: as the number of vault users grows it can become intractably expensive to offload the Claim costs to the Vault operator</li> <li>hinders integration potential: Vault integrators would need to handle both the 2-step and 1-step cases, with the 1-step pushing arbitrary tokens in from an unknown Request at an unknown time. This pushes complexity out onto integrators and reduces the standard's utility.</li> </ul> <p>The 2-step approach used in the standard may be abstracted into a 1-step approach from the user perspective through the use of routers, relayers, message signing, or account abstraction.</p> <p>In the case where a Request may become Claimable immediately in the same block, there can be router contracts that atomically check for Claimable amounts immediately upon Request. Frontends can dynamically route Requests in this way depending on the state and implementation of the Vault to handle this edge case.</p> <h3 id="no-outputs-for-request-functions">No Outputs for Request Functions</h3> <p><code>requestDeposit</code> and <code>requestRedeem</code> may not have a known exchange rate that will happen when the Request becomes Claimed. Returning the corresponding <code>assets</code> or <code>shares</code> could not work in this case.</p> <p>The Requests could also output a timestamp representing the minimum amount of time expected for the Request to become Claimable, however, not all Vaults will be able to return a reliable timestamp.</p> <h3 id="no-event-for-claimable-state">No Event for Claimable State</h3> <p>The state transition of a Request from Pending to Claimable happens at the Vault implementation level and is not specified in the standard. Requests may be batched into the Claimable state, or the state may transition automatically after a timestamp has passed. It is impractical to require an event to emit after a Request becomes Claimable at the user or batch level.</p> <h3 id="reversion-of-preview-functions-in-async-request-flows">Reversion of Preview Functions in Async Request Flows</h3> <p>The preview functions do not take an address parameter, therefore the only way to discriminate discrepancies in the exchange rate is via the <code>msg.sender</code>. However, this could lead to integration/implementation complexities where support contracts cannot determine the output of a claim on behalf of a <code>controller</code>.</p> <p>In addition, there is no on-chain benefit to previewing the Claim step as the only valid state transition is to Claim anyway. If the output of a Claim is undesirable for any reason, the calling contract can revert on the output of that function call.</p> <p>It reduces code and implementation complexity at little to no cost to simply mandate reversion for the preview functions of an async flow.</p> <h3 id="mandated-support-for-erc-165">Mandated Support for <a href="https://wg-eips.ritovision.com/165/">ERC-165</a></h3> <p>Implementing support for <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> is mandated because of the <a href="https://wg-eips.ritovision.com/7540/#optionality-of-flows">optionality of flows</a>. Integrations can use the <code>supportsInterface</code> method to check whether a vault is fully asynchronous, partially asynchronous, or fully synchronous (for which it is just following the <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a>), and use a single contract to support all cases.</p> <h3 id="not-allowing-pending-claims-to-be-fungible">Not Allowing Pending Claims to be Fungible</h3> <p>The async pending claims represent a sort of semi-fungible intermediate share class. Vaults can elect to wrap these claims in any token standard they like, for example, ERC-20, <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>, or ERC-721 depending on the use case. This is intentionally left out of the spec to provide flexibility to implementers.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The interface is fully backward compatible with <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a>. The specification of the <code>deposit</code>, <code>mint</code>, <code>redeem</code>, and <code>withdraw</code> methods is different as described in <a href="https://wg-eips.ritovision.com/7540/#specification">Specification</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"> This code snippet is incomplete pseudocode used for example only and is no way intended to be used in production or guaranteed to be secure</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> pendingDepositRequest</span><span>;</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">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> claimableDepositRequest</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> controller </span><span class="z-keyword">=&gt;</span><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span> operator </span><span class="z-keyword">=&gt;</span><span class="z-support"> bool</span><span>)</span><span>)</span><span class="z-storage z-type"> public</span><span> isOperator</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"> requestDeposit</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"> controller</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-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> requestId</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">!=</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>owner </span><span class="z-keyword">==</span><span class="z-variable z-language"> msg.sender</span><span class="z-keyword"> ||</span><span> isOperator</span><span>[</span><span>owner</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> requestId </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> no requestId associated with this request</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> asset</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span><span>owner</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> assets</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> asset here is the Vault underlying asset</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> pendingDepositRequest</span><span>[</span><span>controller</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> assets</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"> DepositRequest</span><span>(</span><span>controller</span><span>,</span><span> owner</span><span>,</span><span> requestId</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span> assets</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> requestId</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"> * Include some arbitrary transition logic here from Pending to Claimable</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"> 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"> address</span><span class="z-variable"> controller</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"> shares</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">!=</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>controller </span><span class="z-keyword">==</span><span class="z-variable z-language"> msg.sender</span><span class="z-keyword"> ||</span><span> isOperator</span><span>[</span><span>controller</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> claimableDepositRequest</span><span>[</span><span>controller</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> assets</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> underflow would revert if not enough claimable assets</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> shares </span><span class="z-keyword">=</span><span class="z-entity z-name"> convertToShares</span><span>(</span><span>assets</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> this naive example uses the instantaneous exchange rate. It may be more common to use the rate locked in upon Claimable stage.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> balanceOf</span><span>[</span><span>receiver</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> shares</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"> Deposit</span><span>(</span><span>controller</span><span>,</span><span> receiver</span><span>,</span><span> assets</span><span>,</span><span> shares</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"> setOperator</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 class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> isOperator</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>operator</span><span>]</span><span class="z-keyword"> =</span><span> approved</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> OperatorSet</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> operator</span><span>,</span><span> approved</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></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>In general, asynchronicity concerns make state transitions in the Vault much more complex and vulnerable to security risks. Access control on Vault operations, clear documentation of state transitions, and invariant checks should all be performed to mitigate these risks. For example:</p> <ul> <li>The view methods for viewing Pending and Claimable request states (e.g. pendingDepositRequest) are estimates useful for display purposes but can be outdated. The inability to know the final exchange rate on any Request requires users to trust the implementation of the asynchronous Vault in the computation of the exchange rate and fulfillment of their Request.</li> <li>Shares or assets locked for Requests can be stuck in the Pending state. Vaults may elect to allow for the fungibility of pending claims or implement some cancellation functionality to protect users.</li> </ul> <h3 id="operators">Operators</h3> <p>An operator has the ability to transfer the <code>asset</code> of the vault from the approver to any address, and simultaneously grants control over the <code>share</code> of the vault.</p> <p>Any user approving an operator must trust that operator with both the <code>asset</code> and <code>share</code> of the Vault.</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-12T00:00:00+00:00 2026-02-11T14:48:25+00:00 Joey Santorohttps://github.com/joeysantoro https://wg-eips.ritovision.com/7535/

ERC-4626 Tokenized Vaults with Ether (Native Asset) as the underlying asset

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of the <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> spec with an identical interface and behavioral overrides for handling Ether or any native asset as the underlying.</p> <h2 id="motivation">Motivation</h2> <p>A standard for tokenized ETH Vaults has the same benefits as <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a>, particularly in the case of Liquid Staking Tokens, (i.e. fungible <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> wrappers around ETH staking).</p> <p>Maintaining the same exact interface as ERC-4626 further amplifies the benefits as the standard will be maximally compatible with existing ERC-4626 tooling and protocols.</p> <h2 id="specification">Specification</h2> <p>All <a href="https://wg-eips.ritovision.com/7535/">ERC-7535</a> tokenized Vaults MUST implement ERC-4626 (and by extension ERC-20) with behavioral overrides for the methods <code>asset</code>, <code>deposit</code>, and <code>mint</code> specified below.</p> <h3 id="erc-4626-breaking-changes">ERC-4626 Breaking Changes</h3> <ul> <li>Any <code>assets</code> quantity refers to wei of Ether rather than ERC-20 balances.</li> <li>Any ERC-20 <code>transfer</code> calls are replaced by Ether transfer (<code>send</code> or <code>call</code>)</li> <li>Any ERC-20 <code>transferFrom</code> approval flows for <code>asset</code> are not implemented</li> <li><code>deposit</code> and <code>mint</code> have state mutability <code>payable</code></li> <li><code>deposit</code> uses <code>msg.value</code> as the primary input and MAY ignore <code>assets</code></li> </ul> <h3 id="methods">Methods</h3> <h4 id="asset">asset</h4> <p>MUST return <code>0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE</code> per <a href="https://wg-eips.ritovision.com/7528/">ERC-7528</a>.</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"> a</span><span class="z-string">sset</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"> a</span><span class="z-string">ssetTokenAddress</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="deposit">deposit</h4> <p>Mints <code>shares</code> Vault shares to <code>receiver</code> by depositing exactly <code>msg.value</code> of Ether.</p> <p>MUST have state mutability of <code>payable</code>.</p> <p>MUST use <code>msg.value</code> as the primary input parameter for calculating the <code>shares</code> output. I.e. MAY ignore <code>assets</code> parameter as an input.</p> <p>MUST emit the <code>Deposit</code> event.</p> <p>MUST revert if all of <code>msg.value</code> cannot be deposited (due to deposit limit being reached, slippage, etc).</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"> 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"> 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 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>Mints exactly <code>shares</code> Vault shares to <code>receiver</code> by depositing <code>assets</code> of ETH.</p> <p>MUST have state mutability of <code>payable</code>.</p> <p>MUST emit the <code>Deposit</code> event.</p> <p>MUST revert if all of <code>shares</code> cannot be minted (due to deposit limit being reached, slippage, the user not sending a large enough <code>msg.value</code> of Ether to the Vault contract, etc).</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"> 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"> 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 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><h3 id="events">Events</h3> <p>The event usage MUST be identical to ERC-4626.</p> <h3 id="wrapped-eth">Wrapped ETH</h3> <p>Any ERC-4626 Vault that uses a Wrapped ETH ERC-20 as the <code>asset</code> MUST NOT implement ERC-7535. ERC-7535 only applies to native ETH.</p> <h2 id="rationale">Rationale</h2> <p>This standard was designed to maximize compatibility with ERC-4626 while minimizing additional opinionated details on the interface. Examples of this decision rationale are described below:</p> <ul> <li>maintaining the redundant <code>assets</code> input to the <code>deposit</code> function while making its usage optional</li> <li>not enforcing a relationship between <code>msg.value</code> and <code>assets</code> in a <code>mint</code> call</li> <li>not enforcing any behaviors or lack thereof for <code>fallback</code>/<code>__default__</code> methods, payability on additional vault functions, or handling ETH forcibly sent to the contract</li> </ul> <p>All breaking implementation level changes with ERC-4626 are purely to accomodate for the usage of Ether or any native asset instead of an ERC-20 token.</p> <h3 id="allowing-assets-parameter-to-be-ignored-in-a-deposit">Allowing assets Parameter to be Ignored in a Deposit</h3> <p><code>msg.value</code> must always be passed anyway to fund a <code>deposit</code>, therefore it may as well be treated as the primary input number. Allowing <code>assets</code> to be used either forces a strict equality and extra unnecessary gas overhead for redundancy, or allows different values which could cause footguns and undefined behavior.</p> <p>The last option which could work is to require that <code>assets</code> MUST be 0, but this still requires gas to enforce at the implementation level and can more easily be left unspecified, as the input is functionally ignorable in the spec as written.</p> <h3 id="allowing-msg-value-to-not-equal-assets-output-in-a-mint">Allowing msg.value to Not Equal assets Output in a Mint</h3> <p>There may be many cases where a user deposits slightly too much Ether in a <code>mint</code> call. In these cases, enforcing <code>msg.value</code> to equal <code>assets</code> would cause unnecessary reversions. It is up to the vault implementer to decide whether to refund or absorb any excess Ether, and up to depositors to deposit as close to the exact amount as possible.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>ERC-7535 is fully backward compatible with ERC-4626 at the function interface level. Certain implementation behaviors are different due to the fact that ETH is not ERC-20 compliant, such as the priority of <code>msg.value</code> over <code>assets</code>.</p> <p>It has no known compatibility issues with other standards.</p> <h2 id="security-considerations">Security Considerations</h2> <p>In addition to all security considerations of <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a>, there are security implications of having ETH as the Vault asset.</p> <h3 id="call-vs-send"><code>call</code> vs <code>send</code></h3> <p>Contracts should take care when using <code>call</code> to transfer ETH, as this allows additional reentrancy vulnerabilities and arbitrary code execution beyond what is possible with trusted ERC-20 tokens.</p> <p>It is safer to simply <code>send</code> ETH with a small gas stipend.</p> <p>Implementers should take extra precautions when deciding how to transfer ETH.</p> <h3 id="forceful-eth-transfers">Forceful ETH transfers</h3> <p>ETH can be forced into any Vault through the <code>SELFDESTRUCT</code> opcode. Implementers should validate that this does not disrupt Vault accounting in any way.</p> <p>Similarly, any additional <code>payable</code> methods should be checked to ensure they do not disrupt Vault accounting.</p> <h3 id="wrapped-eth-1">Wrapped ETH</h3> <p>Smart contract systems which implement ERC-4626 should consider only supporting ERC-20 underlying assets, and default to using a Wrapped ETH ERC-20 instead of implementing ERC-7535 for handling ETH.</p> <p>The subtle differences between ERC-4626 and ERC-7535 can introduce code fragmentation and security concerns.</p> <p>Cleaner use cases for ERC-7535 are ETH exclusive, such as Wrapped ETH and Liquid Staking Tokens.</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-11T00:00:00+00:00 2026-02-11T14:48:25+00:00 Georgehttps://github.com/JXRow Zisuhttps://github.com/lazy1523 https://wg-eips.ritovision.com/7533/

Help bridges to connect all EVM chains

<h2 id="abstract">Abstract</h2> <p>The objective of Public Cross Port (PCP) is to securely and efficiently connect various EVM chains. It replaces the method of pushing message to multiple chains with a method of pulling messages from multiple chains, significantly reducing the number of cross-chain bridges and gas cost, as more cross-chain bridge projects are built on PCP, the overall security increases.</p> <h2 id="motivation">Motivation</h2> <p>Currently, there are official cross-chain bridges between L2 and L1, but not between L2s. If there are 10 L2 chains that need to cross-chain with each other, it would require 10 x 9 = 90 cross-chain bridges. However, if a pull mechanism is used to merge messages from the other 9 chains into one transaction synchronized to its own chain, only 10 cross-chain bridges would be needed. This significantly reduces the number of cross-chain bridges required and minimizes gas cost.</p> <p>This implementation, with the participation of multiple cross-chain bridge projects, would greatly enhance security. There is currently a considerable amount of redundant construction of cross-chain bridges, which does not contribute to improved security. By using a standardized <code>SendPort</code> contract, if the same cross-chain message is being transported by multiple redundant bridges, the validation on the target chain's <code>IReceivePort</code> should yield the same result. This result, confirmed by multiple cross-chain bridge projects, provides much higher security than relying on a single confirmation. The purpose of this EIP is to encourage more cross-chain bridge projects to participate, transforming redundant construction into enhanced security.</p> <p>To attract cross-chain bridge projects to participate, aside from reducing the number of bridges and gas cost, the use of the Hash MerkleTree data structure in the <code>SendPort</code> ensures that adding cross-chain messages does not increase the overhead of the bridges. Only a small-sized root is required for the transportation of cross-chain bridges, further saving gas.</p> <h3 id="use-case">Use case</h3> <p>This EIP divides the cross-chain ecosystem into 3 layers and defines the <code>SendPort</code> contract and <code>IReceivePort</code> interface at the foundational layer. The implementation of the other layers is left to ecosystem project participants.</p> <p><img src="https://wg-eips.ritovision.com/7533/./assets/0.png" alt="" /></p> <p>On top of cross-chain messaging, applications can use bridges as service, such like Token cross.</p> <p>Cross-chain messaging bridges can be combined with Token cross-chain functionality, as shown in the code example at Reference Implementation. Alternatively, they can be separated. Taking the example of an NFT cross-chain application, it can reuse the messaging bridge of Tokens, and even leverage multiple messaging bridges. Reusing multiple bridges for message verification can significantly enhance security without incurring additional costs for cross-chain and verification services.</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 essence of cross-chain is to inform the target chain about events happening on the source chain. This process can be divided into 3 steps. The following diagram illustrates the overall principle:</p> <p><img src="https://wg-eips.ritovision.com/7533/./assets/1.png" alt="" /></p> <h3 id="1-add-cross-chain-message">1.Add cross-chain message</h3> <p>Under this EIP, a <code>SendPort</code> contract is deployed on each chain. It is responsible for collecting cross-chain messages on that chain and packing them. <code>SendPort</code> operates as a public, permissionless, administrator-free, and automatic system. Cross-chain bridge operators retrieve cross-chain messages from <code>SendPort</code> and transport it to the target chain to complete the cross-chain messaging process.</p> <p>The <code>SendPort</code> contract can serve for multiple bridges and is responsible for collecting events (i.e., cross-chain messages) that occur on that chain and packing them into a MerkleTree. For example, let's consider a scenario where a Bridge contract receives a user's USDT deposit. It can send the hash of this event and the ID of the target chain to the <code>SendPort</code> contract. <code>SendPort</code> adds this information, along with the hash of the sender's address (i.e., the Bridge contract's address), as a leaf in an array. After collecting a certain number of leaves for a period of time (e.g., 1 minute), <code>SendPort</code> automatically packs them into a MerkleTree and begins the next collection phase. <code>SendPort</code>'s role is solely focused on event collection and packing. It operates autonomously without the need for management. So no need to repeat deploy <code>SendPort</code> on each chain, <strong>RECOMMENDED</strong> one chain one <code>SendPort</code>.</p> <p>The <code>SendPort.addMsgHash()</code> function can be called by different cross-chain bridge projects or any other contract. The function does not require permission, which means that there is a possibility of incorrect or fraudulent messages being sent. To prevent fraud, <code>SendPort</code> includes the sender's address in the packing process. This indicates that the <code>sender</code> intends to send the information <code>msgHash</code> to the <code>toChainId</code> chain. When this information is decoded on the target chain, it can help prevent fraudulent activities.</p> <h3 id="2-pull-roots-set-roots">2.Pull roots &amp; Set roots</h3> <p>Upon the completion of packing a new MerkleTree, the package carrier (usually the cross-chain bridge project) pulls the root from multiple chains and stores it in the <code>IReceivePort</code> contract of each chain.</p> <p>A root contains messages from one source chain to multiple target chains. For the package carrier, the root <strong>MAY</strong> not contain relevant messages or <strong>MAY</strong> not include messages intended for a specific target chain. Therefore, the package carrier has the discretion to decide whether or not to transport the root to a particular target chain, based on its relevance.</p> <p>Hence, the <code>IReceivePort</code> contract is not unique and is implemented by the package carrier based on the <code>IReceivePort</code> interface. With multiple package carriers, there will be multiple <code>IReceivePort</code> contracts.</p> <h3 id="3-verify-cross-chain-message">3.Verify cross-chain message</h3> <p>The <code>IReceivePort</code> contract stores the roots of each chain, allowing it to verify the authenticity of messages when provided with the complete message. It is important to note that the root itself cannot be used to decipher the message; it can only be used to validate its authenticity. The complete message can be retrieved from the <code>SendPort</code> contract of the source chain.</p> <p>Since the roots originate from the same <code>SendPort</code>, the roots in different <code>IReceivePort</code> contracts <strong>SHOULD</strong> be identical. In other words, if a message is authentic, it <strong>SHOULD</strong> be able to be verified as authentic across different <code>IReceivePort</code> contracts. This significantly enhances security. It is similar to the principle of multi-signature, where if the majority of <code>IReceivePort</code> contracts verify a message as authentic, it is likely to be true. Conversely, any <code>IReceivePort</code> contracts that verify the message as false may indicate a potential hacker attack or a failure in the corresponding cross-chain bridge. This decentralized participation model ensures that the security of the system is not compromised by single points of failure. It transforms redundant construction into an improvement in security.</p> <p>Regarding data integrity:</p> <p>The <code>SendPort</code> retains all roots and continuous index numbers without deletion or modification. The <code>IReceivePort</code> contracts of each cross-chain bridge <strong>SHOULD</strong> also follow this approach.</p> <h3 id="isendport-interface"><code>ISendPort</code> 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"> ^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"> ISendPort</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MsgHashAdded</span><span>(</span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> packageIndex</span><span>, </span><span class="z-support">address</span><span class="z-variable"> sender</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> msgHash</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> toChainId</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> leaf</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"> Packed</span><span>(</span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> packageIndex</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> packTime</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> root</span><span>)</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"> Package</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> packageIndex</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> root</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span> leaves</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> createTime</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> packTime</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"> addMsgHash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> msgHash</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> toChainId</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"> pack</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-storage z-type"> function</span><span class="z-entity z-name"> getPackage</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> packageIndex</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">Package</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"> getPendingPackage</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-storage z-type">Package</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Let:</p> <ul> <li><code>Package</code>: Collects cross-chain messages within a certain period and packs them into a single package. <ul> <li><code>packageIndex</code>: The index of the package, starting from 0.</li> <li><code>root</code>: The root generated by the MerkleTree from the <code>leaves</code>, representing the packed package.</li> <li><code>leaves</code>: Each leaf represents a cross-chain message, and it is a hash calculated from <code>msgHash</code>, <code>sender</code>, and <code>toChainId</code>. <ul> <li><code>msgHash</code>: The hash of the message, passed in from an external contract.</li> <li><code>sender</code>: The address of the external contract, no need to pass it in explicitly.</li> <li><code>toChainId</code>: The chain ID of the target chain, passed in from an external contract.</li> </ul> </li> <li><code>createTime</code>: The timestamp when the package started collecting messages. It is also the timestamp when the previous package was packed.</li> <li><code>packTime</code>: The timestamp when the package was packed. After packing, no more leaves can be added.</li> </ul> </li> <li><code>addMsgHash()</code>: The external contract sends the hash of cross-chain messages to the SendPort.</li> <li><code>pack()</code>: Manually triggers the packing process. Typically, it is automatically triggered when the last submitter submits his message. If waiting for the last submitter takes too long, the packing process can be manually triggered.</li> <li><code>getPackage()</code>: Retrieves each package in the SendPort, including both packed and pending packages.</li> <li><code>getPendingPackage()</code>: Retrieves the pending package in the SendPort.</li> </ul> <h3 id="ireceiveport-interface"><code>IReceivePort</code> 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"> ^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"> IReceivePort</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> PackageReceived</span><span>(</span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> fromChainId</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> packageIndex</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> root</span><span>)</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"> Package</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> fromChainId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> packageIndex</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> root</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"> receivePackages</span><span>(</span><span class="z-storage z-type">Package</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> packages</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"> getRoot</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> fromChainId</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> packageIndex</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-storage z-type"> function</span><span class="z-entity z-name"> verify</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> fromChainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> packageIndex</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"> proof</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> msgHash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</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></span></code></pre> <p>Let:</p> <ul> <li><code>Package</code>: Collects cross-chain messages within a certain period and bundles them into a single package. <ul> <li><code>fromChainId</code>: The chain from which the package originates.</li> <li><code>packageIndex</code>: The index of the package, starting from 0.</li> <li><code>root</code>: The root generated by the MerkleTree from the <code>leaves</code>, representing the packed package.</li> </ul> </li> <li><code>receivePackages()</code>: Receive multiple roots from different source chains's SendPort.</li> <li><code>getRoot()</code>: Retrieves a specific root from a particular chain.</li> <li><code>verify()</code>: Verifies if the message on the source chain was sent by the sender.</li> </ul> <h2 id="rationale">Rationale</h2> <p>The traditional approach involves using a push method, as depicted in the following diagram:</p> <p><img src="https://wg-eips.ritovision.com/7533/./assets/2.png" alt="" /></p> <p>If there are 6 chains, each chain needs to push to the other 5 chains, resulting in the requirement of 30 cross-chain bridges, as shown in the diagram below:</p> <p><img src="https://wg-eips.ritovision.com/7533/./assets/3.png" alt="" /></p> <p>When N chains require cross-chain communication with each other, the number of cross-chain bridges needed is calculated as: num = N * (N - 1).</p> <p>Using the pull approach allows the batch of cross-chain messages from 5 chains into 1 transaction, significantly reducing the number of required cross-chain bridges, as illustrated in the following diagram:</p> <p><img src="https://wg-eips.ritovision.com/7533/./assets/4.png" alt="" /></p> <p>If each chain pulls messages from the other 5 chains onto its own chain, only 6 cross-chain bridges are necessary. For N chains requiring cross-chain communication, the number of cross-chain bridges needed is: num = N.</p> <p>Thus, the pull approach can greatly reduce the number of cross-chain bridges.</p> <p>The MerkleTree data structure efficiently compresses the size of cross-chain messages. Regardless of the number of cross-chain messages, they can be compressed into a single root, represented as a byte32 value. The package carrier only needs to transport the root, resulting in low gas cost.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP does not change the consensus layer, so there are no backwards compatibility issues for Ethereum as a whole.</p> <p>This EIP does not change other ERC standars, so there are no backwards compatibility issues for Ethereum applications.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Below is an example contract for a cross-chain bridge:</p> <h3 id="sendport-sol"><code>SendPort.sol</code></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-keyword">import</span><span class="z-string"> &quot;./ISendPort.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"> SendPort</span><span class="z-storage"> is</span><span class="z-entity z-name"> ISendPort</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> PACK_INTERVAL </span><span class="z-keyword">=</span><span class="z-constant"> 6000</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> MAX_PACKAGE_MESSAGES </span><span class="z-keyword">=</span><span class="z-constant"> 100</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-storage z-type"> public</span><span> pendingIndex </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-storage z-type"> mapping</span><span>(</span><span class="z-support">uint</span><span class="z-keyword"> =&gt;</span><span> Package</span><span>)</span><span class="z-storage z-type"> public</span><span> packages</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> {</span></span> <span class="giallo-l"><span> packages</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Package</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-keyword"> new</span><span class="z-support"> bytes32</span><span>[](</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</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"> addMsgHash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> msgHash</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> toChainId</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> leaf </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>msgHash</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span> toChainId</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> Package </span><span class="z-storage z-type">storage</span><span> pendingPackage </span><span class="z-keyword">=</span><span> packages</span><span>[</span><span>pendingIndex</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> pendingPackage</span><span>.</span><span>leaves</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>leaf</span><span>)</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"> MsgHashAdded</span><span>(</span><span>pendingPackage</span><span>.</span><span>packageIndex</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span> msgHash</span><span>,</span><span> toChainId</span><span>,</span><span> leaf</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>pendingPackage</span><span>.</span><span>leaves</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> MAX_PACKAGE_MESSAGES</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> console</span><span>.</span><span class="z-entity z-name">log</span><span>(</span><span class="z-string">&quot;MAX_PACKAGE_MESSAGES&quot;</span><span>,</span><span> pendingPackage</span><span>.</span><span>leaves</span><span>.</span><span>length</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _pack</span><span>(</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 class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> console.log(&quot;block.timestamp&quot;, block.timestamp);</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>pendingPackage</span><span>.</span><span>createTime </span><span class="z-keyword">+</span><span> PACK_INTERVAL </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></span> <span class="giallo-l"><span> console</span><span>.</span><span class="z-entity z-name">log</span><span>(</span><span class="z-string">&quot;PACK_INTERVAL&quot;</span><span>,</span><span> pendingPackage</span><span>.</span><span>createTime</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _pack</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"> pack</span><span>(</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>packages</span><span>[</span><span>pendingIndex</span><span>]</span><span>.</span><span>createTime </span><span class="z-keyword">+</span><span> PACK_INTERVAL </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 class="z-string"> &quot;SendPort::pack: pack interval too short&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> _pack</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"> getPackage</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> packageIndex</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">Package</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> packages</span><span>[</span><span>packageIndex</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"> getPendingPackage</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">Package</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> packages</span><span>[</span><span>pendingIndex</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"> _pack</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span> Package </span><span class="z-storage z-type">storage</span><span> pendingPackage </span><span class="z-keyword">=</span><span> packages</span><span>[</span><span>pendingIndex</span><span>]</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> _leaves </span><span class="z-keyword">=</span><span> pendingPackage</span><span>.</span><span>leaves</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> (</span><span>_leaves</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 1</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> _leaves </span><span class="z-keyword">=</span><span class="z-entity z-name"> _computeLeaves</span><span>(</span><span>_leaves</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> pendingPackage</span><span>.</span><span>root </span><span class="z-keyword">=</span><span> _leaves</span><span>[</span><span class="z-constant">0</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> pendingPackage</span><span>.</span><span>packTime </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> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Packed</span><span>(</span><span>pendingPackage</span><span>.</span><span>packageIndex</span><span>,</span><span> pendingPackage</span><span>.</span><span>packTime</span><span>,</span><span> pendingPackage</span><span>.</span><span>root</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> pendingIndex </span><span class="z-keyword">=</span><span> pendingPackage</span><span>.</span><span>packageIndex </span><span class="z-keyword">+</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"><span> packages</span><span>[</span><span>pendingIndex</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Package</span><span>(</span><span>pendingIndex</span><span>,</span><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-keyword"> new</span><span class="z-support"> bytes32</span><span>[](</span><span class="z-constant">0</span><span>)</span><span>,</span><span> pendingPackage</span><span>.</span><span>packTime</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"> _computeLeaves</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 z-parameter z-function"> _leaves</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">bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _nextLeaves</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_leaves</span><span>.</span><span>length % </span><span class="z-constant">2</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> _nextLeaves </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> bytes32</span><span>[](</span><span class="z-variable z-parameter z-function">_leaves</span><span>.</span><span class="z-variable">length</span><span> / </span><span class="z-constant">2</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> computedHash</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">+</span><span class="z-constant"> 1</span><span class="z-keyword"> &lt;</span><span> _leaves</span><span>.</span><span>length</span><span>;</span><span> i </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span class="z-constant"> 2</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> computedHash </span><span class="z-keyword">=</span><span class="z-entity z-name"> _hashPair</span><span>(</span><span>_leaves</span><span>[</span><span>i</span><span>]</span><span>,</span><span> _leaves</span><span>[</span><span>i </span><span class="z-keyword">+</span><span class="z-constant"> 1</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _nextLeaves</span><span>[</span><span>i </span><span class="z-keyword">/</span><span class="z-constant"> 2</span><span>]</span><span class="z-keyword"> =</span><span> computedHash</span><span>;</span></span> <span class="giallo-l"><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-support"> bytes32</span><span> lastLeaf </span><span class="z-keyword">=</span><span> _leaves</span><span>[</span><span>_leaves</span><span>.</span><span>length </span><span class="z-keyword">-</span><span class="z-constant"> 1</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> _nextLeaves </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> bytes32</span><span>[](</span><span>(</span><span class="z-variable z-parameter z-function">_leaves</span><span>.</span><span class="z-variable">length</span><span> / </span><span class="z-constant">2</span><span> + </span><span class="z-constant">1</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> computedHash</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">+</span><span class="z-constant"> 1</span><span class="z-keyword"> &lt;</span><span> _leaves</span><span>.</span><span>length</span><span>;</span><span> i </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span class="z-constant"> 2</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> computedHash </span><span class="z-keyword">=</span><span class="z-entity z-name"> _hashPair</span><span>(</span><span>_leaves</span><span>[</span><span>i</span><span>]</span><span>,</span><span> _leaves</span><span>[</span><span>i </span><span class="z-keyword">+</span><span class="z-constant"> 1</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _nextLeaves</span><span>[</span><span>i </span><span class="z-keyword">/</span><span class="z-constant"> 2</span><span>]</span><span class="z-keyword"> =</span><span> computedHash</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> _nextLeaves</span><span>[</span><span>_nextLeaves</span><span>.</span><span>length </span><span class="z-keyword">-</span><span class="z-constant"> 1</span><span>]</span><span class="z-keyword"> =</span><span> lastLeaf</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"> _hashPair</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> a</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> b</span><span>)</span><span class="z-storage z-type"> private</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> a </span><span class="z-keyword">&lt;</span><span> b </span><span class="z-keyword">?</span><span class="z-entity z-name"> _efficientHash</span><span>(</span><span>a</span><span>,</span><span> b</span><span>)</span><span class="z-keyword"> :</span><span class="z-entity z-name"> _efficientHash</span><span>(</span><span>b</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"> _efficientHash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> a</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> b</span><span>)</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</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"> @solidity memory-safe-assembly</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 class="z-constant">0x00</span><span>,</span><span> a</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x20</span><span>,</span><span> b</span><span>)</span></span> <span class="giallo-l"><span> value </span><span class="z-keyword">:=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-constant">0x00</span><span>,</span><span class="z-constant"> 0x40</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>External featrues:</p> <ul> <li><code>PACK_INTERVAL</code>: The minimum time interval between two consecutive packing operations. If this interval is exceeded, a new packing operation can be initiated.</li> <li><code>MAX_PACKAGE_MESSAGES</code>: Once <code>MAX_PACKAGE_MESSAGES</code> messages are collected, a packing operation is triggered immediately. This takes precedence over the <code>PACK_INTERVAL</code> setting.</li> </ul> <h3 id="receiveport-sol"><code>ReceivePort.sol</code></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-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/access/Ownable.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IReceivePort.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"> ReceivePort</span><span class="z-storage"> is</span><span class="z-entity z-name"> IReceivePort</span><span>, </span><span class="z-entity z-name">Ownable</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">fromChainId =&gt; packageIndex =&gt; root</span></span> <span class="giallo-l"><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-storage z-type"> mapping</span><span>(</span><span class="z-support">uint</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bytes32</span><span>)</span><span>)</span><span class="z-storage z-type"> public</span><span> roots</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> {</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"> receivePackages</span><span>(</span><span class="z-storage z-type">Package</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> packages</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 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> packages</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> Package </span><span class="z-storage z-type">calldata</span><span> p </span><span class="z-keyword">=</span><span> packages</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>roots</span><span>[</span><span>p</span><span>.</span><span>fromChainId</span><span>]</span><span>[</span><span>p</span><span>.</span><span>packageIndex</span><span>]</span><span class="z-keyword"> ==</span><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-string"> &quot;ReceivePort::receivePackages: package already exist&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> roots</span><span>[</span><span>p</span><span>.</span><span>fromChainId</span><span>]</span><span>[</span><span>p</span><span>.</span><span>packageIndex</span><span>]</span><span class="z-keyword"> =</span><span> p</span><span>.</span><span>root</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"> PackageReceived</span><span>(</span><span>p</span><span>.</span><span>fromChainId</span><span>,</span><span> p</span><span>.</span><span>packageIndex</span><span>,</span><span> p</span><span>.</span><span>root</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"> getRoot</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> fromChainId</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> packageIndex</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 class="z-keyword"> return</span><span> roots</span><span>[</span><span>fromChainId</span><span>]</span><span>[</span><span>packageIndex</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"> verify</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> fromChainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> packageIndex</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"> proof</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> msgHash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</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">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> leaf </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>msgHash</span><span>,</span><span> sender</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>chainid</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-entity z-name"> _processProof</span><span>(</span><span>proof</span><span>,</span><span> leaf</span><span>)</span><span class="z-keyword"> ==</span><span> roots</span><span>[</span><span>fromChainId</span><span>]</span><span>[</span><span>packageIndex</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"> _processProof</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"> proof</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> leaf</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-support"> bytes32</span><span> computedHash </span><span class="z-keyword">=</span><span> leaf</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> proof</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> computedHash </span><span class="z-keyword">=</span><span class="z-entity z-name"> _hashPair</span><span>(</span><span>computedHash</span><span>,</span><span> proof</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-keyword"> return</span><span> computedHash</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"> _hashPair</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> a</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> b</span><span>)</span><span class="z-storage z-type"> private</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> a </span><span class="z-keyword">&lt;</span><span> b </span><span class="z-keyword">?</span><span class="z-entity z-name"> _efficientHash</span><span>(</span><span>a</span><span>,</span><span> b</span><span>)</span><span class="z-keyword"> :</span><span class="z-entity z-name"> _efficientHash</span><span>(</span><span>b</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"> _efficientHash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> a</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> b</span><span>)</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</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"> @solidity memory-safe-assembly</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 class="z-constant">0x00</span><span>,</span><span> a</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x20</span><span>,</span><span> b</span><span>)</span></span> <span class="giallo-l"><span> value </span><span class="z-keyword">:=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-constant">0x00</span><span>,</span><span class="z-constant"> 0x40</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="bridgeexample-sol"><code>BridgeExample.sol</code></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-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;./ISendPort.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./ReceivePort.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"> BridgeExample</span><span class="z-storage"> is</span><span class="z-entity z-name"> ReceivePort</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> ISendPort </span><span class="z-storage z-type">public</span><span> sendPort</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-support"> bool</span><span>)</span><span class="z-storage z-type"> public</span><span> usedMsgHashes</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">uint</span><span class="z-keyword"> =&gt;</span><span class="z-support"> address</span><span>)</span><span class="z-storage z-type"> public</span><span> trustBridges</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"> address</span><span>)</span><span class="z-storage z-type"> public</span><span> crossPairs</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"> sendPortAddr</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> sendPort </span><span class="z-keyword">=</span><span class="z-entity z-name"> ISendPort</span><span>(</span><span>sendPortAddr</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"> setTrustBridge</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> chainId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> bridge</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> trustBridges</span><span>[</span><span>chainId</span><span>]</span><span class="z-keyword"> =</span><span> bridge</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"> setCrossPair</span><span>(</span><span class="z-support">address</span><span class="z-variable"> fromTokenAddr</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> toTokenAddr</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> crossPairs</span><span>[</span><span>fromTokenAddr</span><span>]</span><span class="z-keyword"> =</span><span> toTokenAddr</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"> getLeaves</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> packageIndex</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> start</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> num</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>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> ISendPort</span><span>.</span><span>Package </span><span class="z-storage z-type">memory</span><span> p </span><span class="z-keyword">=</span><span> sendPort</span><span>.</span><span class="z-entity z-name">getPackage</span><span>(</span><span>packageIndex</span><span>)</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> result </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> bytes32</span><span>[](</span><span class="z-variable">num</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> p</span><span>.</span><span>leaves</span><span>.</span><span>length </span><span class="z-keyword">&amp;&amp;</span><span> i </span><span class="z-keyword">&lt;</span><span> num</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> result</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span> p</span><span>.</span><span>leaves</span><span>[</span><span>i </span><span class="z-keyword">+</span><span> start</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> result</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"> transferTo</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> toChainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> fromTokenAddr</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> amount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> receiver</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</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-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>toChainId</span><span>,</span><span> fromTokenAddr</span><span>,</span><span> amount</span><span>,</span><span> receiver</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> sendPort</span><span>.</span><span class="z-entity z-name">addMsgHash</span><span>(</span><span>msgHash</span><span>,</span><span> toChainId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> IERC20</span><span>(</span><span>fromTokenAddr</span><span>)</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</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-storage z-type"> function</span><span class="z-entity z-name"> transferFrom</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> fromChainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> packageIndex</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"> proof</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> fromTokenAddr</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> amount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> receiver</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</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-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-variable z-language">block</span><span>.</span><span>chainid</span><span>,</span><span> fromTokenAddr</span><span>,</span><span> amount</span><span>,</span><span> receiver</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-keyword"> require</span><span>(</span><span class="z-keyword">!</span><span>usedMsgHashes</span><span>[</span><span>msgHash</span><span>]</span><span>,</span><span class="z-string"> &quot;transferFrom: Used msgHash&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> verify</span><span>(</span></span> <span class="giallo-l"><span> fromChainId</span><span>,</span></span> <span class="giallo-l"><span> packageIndex</span><span>,</span></span> <span class="giallo-l"><span> proof</span><span>,</span></span> <span class="giallo-l"><span> msgHash</span><span>,</span></span> <span class="giallo-l"><span> trustBridges</span><span>[</span><span>fromChainId</span><span>]</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;transferFrom: verify failed&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> usedMsgHashes</span><span>[</span><span>msgHash</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-support"> address</span><span> toTokenAddr </span><span class="z-keyword">=</span><span> crossPairs</span><span>[</span><span>fromTokenAddr</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>toTokenAddr </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;transferFrom: fromTokenAddr is not crossPair&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC20</span><span>(</span><span>toTokenAddr</span><span>)</span><span>.</span><span class="z-entity z-name">safeTransfer</span><span>(</span><span>receiver</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></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Regarding competition and double spending among cross-chain bridges:</p> <p>The <code>SendPort</code> is responsible for one task: packing the messages to be cross-chain transferred. The transmission and verification of messages are implemented independently by each cross-chain bridge project. The objective is to ensure that the cross-chain messages obtained by different cross-chain bridges on the source chain are consistent. Therefore, there is no need for competition among cross-chain bridges for the right to transport or validate roots. Each bridge operates independently. If a cross-chain bridge has bugs in its implementation, it poses a risk to itself but does not affect other cross-chain bridges.</p> <p><strong>Suggestions</strong>:</p> <ol> <li>Don't let <code>IReceivePort.receivePackages()</code> be called by anyone.</li> <li>When performing verification, store the verified <code>msgHash</code> to avoid double spending during subsequent verifications.</li> <li>Don't trust all senders in the MerkleTree.</li> </ol> <p>Regarding the forgery of cross-chain messages:</p> <p>Since the <code>SendPort</code> is a public contract without usage restrictions, anyone can send arbitrary cross-chain messages to it. The <code>SendPort</code> includes the <code>msg.sender</code> in the packing process. If a hacker attempts to forge a cross-chain message, the hacker's address will be included in the packing along with the forged message. During verification, the hacker's address can be identified. This is why it is suggested to not trust all senders in the MerkleTree.</p> <p>Regarding the sequnce of messages:</p> <p>While the <code>SendPort</code> sorts received cross-chain messages by time, there is no guarantee of sequnce during verification. For example, if a user performs a cross-chain transfer of 10 ETH and then 20 USDT, on the target chain, he may withdraw the 20 USDT first and then the 10 ETH, or vice versa. The specific sequnce depends on the implementation of the <code>IReceivePort</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-10-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Joey Santorohttps://github.com/joeysantoro https://wg-eips.ritovision.com/7528/

An address placeholder for ETH when used in the same context as an ERC-20 token.

<h2 id="abstract">Abstract</h2> <p>The following standard proposes a convention for using the address <code>0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee</code> in all contexts where an address is used to represent ETH in the same capacity as an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token. This would apply to both events where an address field would denote ETH or an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token, as well as discriminators such as the <code>asset</code> field of an <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> vault.</p> <p>This standard generalizes to other EVM chains where the native asset is not ETH.</p> <h2 id="motivation">Motivation</h2> <p>ETH, being a fungible unit of value, often behaves similarly to <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens. Protocols tend to implement a standard interface for ERC-20 tokens, and benefit from having the ETH implementation to closely mirror the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> implementations.</p> <p>In many cases, protocols opt to use Wrapped ETH (e.g. WETH9 deployed at address 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2 on Etherum Mainnet) for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> compliance. In other cases, protocols will use native ETH due to gas considerations, or the requirement of using native ETH such as in the case of a Liquid Staking Token (LST).</p> <p>In addition, protocols might create separate events for handling ETH native cases and ERC-20 cases. This creates data fragmentation and integration overhead for off-chain infrastructure. By having a strong convention for an ETH address to use for cases where it behaves like an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token, it becomes beneficial to use one single event format for both cases.</p> <p>One intended use case for the standard is <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> compliant LSTs which use ETH as the <code>asset</code>. This extends the benefits and tooling of <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> to LSTs and integrating protocols.</p> <p>This standard allows protocols and off-chain data infrastructure to coordinate around a shared understanding that any time <code>0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee</code> is used as an address in an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> context, it means ETH.</p> <h2 id="specification">Specification</h2> <p>This standard applies for all components of smart contract systems in which an address is used to identify an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token, and where native ETH is used in certain instances in place of an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token. The usage of the term Token below means ETH or an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> in this context.</p> <p>Any fields or events where an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> address is used, yet the underlying Token is ETH, the address field MUST return <code>0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee</code></p> <p>Any fields or events where the Token is a non-enshrined wrapped ERC-20 version of ETH (i.e WETH9) MUST use that Token's address and MUST NOT use <code>0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee</code>.</p> <p>Where appropriate, the address should be checksummed. E.g. the <a href="https://wg-eips.ritovision.com/55/">EIP-55</a> checksum is <code>0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="considered-alternative-addresses">Considered alternative addresses</h3> <p>Many existing implementations of the same use case as this standard use addresses such as 0x0, 0x1, and 0xe for gas efficiency of having leading zero bytes.</p> <p>Ultimately, all of these addresses collide with potential precompile addresses and are less distinctive as identifiers for ETH.</p> <p><code>0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee</code> has the most current usage, is distinctive, and would not collide with any precompiles. These benefits outweigh the potential gas benefits of other alternatives.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard has no known compatibility issues with other standards.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Using ETH as a Token instead of WETH exposes smart contract systems to re-entrancy and similar classes of vulnerabilities. Implementers must take care to follow the industry standard development patterns (e.g. checks-effects-interactions) when the Token is ETH.</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:48:25+00:00 Francesco Sullohttps://github.com/sullof https://wg-eips.ritovision.com/7531/

Recognizing NFT ownership when staked into other contracts.

<h2 id="abstract">Abstract</h2> <p>The ownership of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens when staked in a pool presents challenges, particularly when it involves older, non-lockable NFTs like, for example, Crypto Punks or Bored Ape Yacht Club (BAYC) tokens. This proposal introduces an interface to address these challenges by allowing staked NFTs to be recognized by their original owners, even after they've been staked.</p> <h2 id="motivation">Motivation</h2> <p>Recent solutions involve retaining NFT ownership while "locking" an NFT letting the owner keeping its ownership. However, this requires the NFT contract to implement lockable functionality. Early NFTs were not originally designed as lockable and so they must be staked transferring the ownership to the staking contract.</p> <p>This prevents the original owner from accessing valuable privileges and benefits associated with their NFTs.</p> <p>For example:</p> <ul> <li>A BAYC NFT holder would lose access to the BAYC Yacht Club and member events when staked.</li> <li>A CryptoPunks holder may miss out on special airdrops or displays only available to verified owners.</li> <li>Owners of other early NFTs like EtherRocks would lose the social status of provable ownership when staked.</li> </ul> <p>By maintaining a record of the original owner, the proposed interface allows these original perks to remain accessible even when the NFT is staked elsewhere. This compatibility is critical for vintage NFT projects lacking native locking mechanisms.</p> <p>Another important right, is the right to use an asset. For example an NFT can be used to play a game. If the NFT is lent to a user, the ownership of the NFT is transferred to the lending contract. In this case, it can be hard to identify the wallet that has the right to us the NFT in the game, which should be the user.</p> <p>The interface provides a simple, elegant way to extend staking compatibility to legacy NFTs without affecting their core functionality or benefits of ownership.</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 interface is defined 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"> IERC7531</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"> MUST be emitted when the token&#39;s technical owner (the contract holding the token) is different </span></span> <span class="giallo-l"><span class="z-comment"> * from its actual owner (the entity with rights over 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"> This scenario is common in staking, where a staking contract is the technical owner. The event MUST </span></span> <span class="giallo-l"><span class="z-comment"> * be emitted in the same or any subsequent block as the Transfer event for the token. </span></span> <span class="giallo-l"><span class="z-comment"> * A later Transfer event involving the same token supersedes this RightsHolderChange event.</span></span> <span class="giallo-l"><span class="z-comment"> * To ensure authenticity, entities listening to this event MUST verify that the contract emitting</span></span> <span class="giallo-l"><span class="z-comment"> * the event matches the token&#39;s current owner as per the related Transfer event.</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"> tokenAddress</span><span class="z-comment"> The address of the token 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"> tokenId</span><span class="z-comment"> The ID of 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"> holder</span><span class="z-comment"> The address of the actual rights holder of 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"> right</span><span class="z-comment"> The type of right held by the holder. The initial supported rights are:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * 0x399d2b36 // bytes4(keccak256(&quot;ownership&quot;))</span></span> <span class="giallo-l"><span class="z-comment"> * 0x230a5961 // bytes4(keccak256(&quot;usage&quot;))</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * This allows projects to add more rights without breaking compatibility with this interface. See IERC7531Rights for more details.</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"> RightsHolderChange</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenAddress</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"> holder</span><span>, </span><span class="z-support">bytes4</span><span class="z-variable"> right</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 address of the entity with rights over the token, distinct from the current owner.</span></span> <span class="giallo-l"><span class="z-comment"> * The function MUST revert if the token does not exist or is not currently held.</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"> tokenAddress</span><span class="z-comment"> The address of the ERC-721 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"> tokenId</span><span class="z-comment"> The ID of 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"> right</span><span class="z-comment"> The type of right held by the holder.</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 entity with rights over 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"> rightsHolderOf</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"> uint256</span><span class="z-variable"> tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-variable"> right</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">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>RightsHolderChange</code> event is crucial for accurately identifying the actual owner of a held token. In scenarios where a token is staked in a contract, the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> Transfer event would incorrectly assign ownership to the staking contract itself. The <code>RightsHolderChange</code> event addresses this discrepancy by explicitly signaling the real owner of the token rights.</p> <h3 id="timing-of-event-emission">Timing of Event Emission:</h3> <p>The <code>RightsHolderChange</code> event MUST be emitted either in the same block as the corresponding <code>Transfer</code> event or in any subsequent block. This approach offers flexibility for existing pools to upgrade their systems without compromising past compatibility. Specifically, staking pools can emit this event for all previously staked tokens, or they can allow users to actively reclaim their ownership. This flexibility ensures that the system can adapt to both current and future states while accurately reflecting the actual ownership of held tokens.</p> <h3 id="invalidation-of-previous-rightsholderchange-events">Invalidation of Previous <code>RightsHolderChange</code> Events:</h3> <p>To maintain compatibility with the broader ecosystem and optimize for gas efficiency, any new <code>Transfer</code> event involving the same token invalidates any previous <code>RightsHolderChange</code> event. This approach ensures that the most recent <code>Transfer</code> event reliably reflects the current ownership status, negating the need for additional events upon unstaking.</p> <h3 id="nft-extension">NFT extension</h3> <p>The two default rights are:</p> <ul> <li>0x399d2b36 // bytes4(keccak256("ownership"))</li> <li>0x230a5961 // bytes4(keccak256("usage"))</li> </ul> <p>However, there can ben NFTs that only need to validate the ownership, others may need to validate the usage, and others may need to validate both, some other NFT may need to manage totally different rights.</p> <p>To give NFTs the necessary flexibility, we also propose the following OPTIONAL extension.</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"> IERC7531Rights</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 the list of rights supported by 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"> The</span><span class="z-comment"> list of rights supported by 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"> supportedERC7531Rights</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">bytes4</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 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 whether the NFT supports a specific right.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> right</span><span class="z-comment"> The right to check.</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 NFT supports the right.</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"> supportsERC7531Right</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> right</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>It allows NFTs to return the list of rights they support, and projects to verify it an NFT supports a specific right. Since the rights are identified by the bytes4 hash of the right name, when introducing new rights, NFT projects SHOULD make public statements about the string that corresponds to the bytes4 hash and explain the rationale for it.</p> <p>If the NFT does not support the interface (for example, if an existing NFT), project using NFTs SHOULD consider only the standard rights.</p> <p>NFT Projects SHOULD adhere to pre-existing rights, when possible, to avoid the proliferation of rights that could make the system less efficient and more complex.</p> <h2 id="rationale">Rationale</h2> <h3 id="addressing-non-lockable-nft-challenges">Addressing Non-Lockable NFT Challenges:</h3> <p>Non-lockable NFTs present a unique challenge in decentralized ecosystems, especially in scenarios involving staking or delegating usage rights. The standard <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> <code>ownerOf</code> function returns the current owner of the NFT, which, in the case of staking, would be the staking pool contract. This transfer of ownership to the staking pool, even if temporary, can disrupt the utility or privileges tied to the NFT, such as participation in governance, access to exclusive content, or utility within a specific ecosystem.</p> <h3 id="the-rightsholderof-method">The <code>rightsHolderOf</code> Method:</h3> <p>The <code>rightsHolderOf</code> method provides a solution to this challenge. By maintaining a record of the original owner or the rightful holder of certain privileges associated with the NFT, this method ensures that the underlying utility of the NFT is preserved, even when the NFT itself is held in a pool.</p> <h3 id="technical-advantages">Technical Advantages:</h3> <ol> <li> <p>Preservation of Utility: This approach allows NFT owners to leverage their assets in staking pools or other smart contracts without losing access to the benefits associated with the NFT. This is particularly important for NFTs that confer ongoing benefits or rights.</p> </li> <li> <p>Enhanced Flexibility: The method offers greater flexibility for NFT owners, allowing them to participate in staking and other DeFi activities without relinquishing the intrinsic benefits of their NFTs.</p> </li> <li> <p>Compatibility and Interoperability: By introducing a new method instead of altering the existing ownerOf function, this EIP ensures backward compatibility with existing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> contracts. This is crucial for maintaining interoperability across various platforms and applications in the NFT space.</p> </li> <li> <p>Event-Driven Updates: The <code>RightsHolderChange</code> event facilitates real-time tracking of the rights-holder of an NFT. This is particularly useful for third-party platforms and services that rely on up-to-date ownership information to provide services or privileges.</p> </li> </ol> <h3 id="addressing-potential-misuse">Addressing Potential Misuse:</h3> <p>While this approach introduces a layer of complexity, it also comes with the need for diligent implementation to prevent misuse, such as the wrongful assignment of rights. This EIP outlines security considerations and best practices to mitigate such risks.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is fully backwards compatible with existing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> contracts. It can seamlessly integrate with existing upgradeable staking pools, provided they choose to adopt it. It does not require changes to the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard but acts as an enhancement for staking pools.</p> <h2 id="security-considerations">Security Considerations</h2> <p>A potential risk with this interface is the improper assignment of ownership by a staking pool to a different wallet. This could allow that wallet to access privileges associated with the NFT, which might not be intended by the true owner. However, it is important to note that this risk is lower than transferring full legal ownership of the NFT to the staking pool, as the interface only enables recognizing the staker, not replacing the actual owner on-chain.</p> <h3 id="event-authenticity">Event Authenticity:</h3> <p>There is a concern regarding the potential emission of fake <code>RightsHolderChange</code> events. Since any contract can emit such an event, there's a risk of misinformation or misrepresentation of ownership. It is crucial for entities listening to the <code>RightsHolderChange</code> event to verify that the emitting contract is indeed the current owner of the token. This validation is essential to ensure the accuracy of ownership information and to mitigate the risks associated with deceptive event emissions.</p> <h3 id="reducing-the-risk-of-inaccurate-ownership-records">Reducing the Risk of Inaccurate Ownership Records:</h3> <p>While improper use of this interface poses some risk of inaccurate ownership records, this is an inherent issue with any staking arrangement. The risk is somewhat mitigated by the fact that the owner retains custody rather than transferring ownership.</p> <h3 id="due-diligence">Due Diligence:</h3> <p>Consumers of privilege-granting NFTs should exercise due diligence when evaluating staking providers. Signs of mismanagement or fraud should be carefully assessed. The interface itself does not enable new manipulation capabilities, but caution is always prudent when interacting with smart contracts and staking pools.</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-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 Todd Chapmanhttps://github.com/tthebc01 Charlie Sibbachcharlie@cwsoftware.com Sean Singhttps://github.com/seansing https://wg-eips.ritovision.com/7529/

Leveraging TXT Records to discover, verify and associate a smart contract with the owner of a DNS domain.

<h2 id="abstract">Abstract</h2> <p>The introduction of DNS over HTTPS (DoH) in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc8484">RFC 8484</a> has enabled tamper-resistant client-side queries of DNS records directly from a web application. This proposal describes a simple standard leveraging DoH to fetch TXT records (from traditional DNS service providers) which are used for discovering and verifying the association of a smart contract with a common DNS domain. This standard can be used as a straightforward technique to mitigate smart contract authorship spoofing and enhance the discoverability of smart contracts through standard web search mechanisms.</p> <h2 id="motivation">Motivation</h2> <p>As mainstream businesses begin to adopt public blockchain and digital asset technologies more rapidly, there is a growing need for a discovery/search mechanism (compatible with conventional web technologies) of smart contracts associated with a known business domain as well as reasonable assurance that the smart contract does indeed belong to the business owner of the DNS domain. The relatively recent introduction and widespread support of DoH means it is possible to make direct, tamper-resistant queries of DNS records straight from a web application context and thus leverage a simple TXT record as a pointer to an on-chain smart contract. Prior to the introduction of DoH, web (and mobile) applications <em>could not</em> access DNS records directly; instead they would have to relay requests through a trusted, proprietary service provider who could easily manipulate response results.</p> <p>According to Cloudflare, the two most common use cases of TXT records today are email spam prevention (via <a rel="external" href="https://www.rfc-editor.org/rfc/rfc7208">SPF</a>, <a rel="external" href="https://www.rfc-editor.org/rfc/rfc6376">DKIM</a>, and <a rel="external" href="https://www.rfc-editor.org/rfc/rfc7489">DMARC</a> TXT records) and domain name ownership verification. The use case considered here for on-chain smart contract discovery and verification is essentially analogous.</p> <p>A TXT pointer coupled with an appropriate smart contract interface (described in this proposal) yields a simple, yet flexible and robust mechanism for the client-side detection and reasonably secure verification of on-chain logic and digital assets associated with the owner of a domain name. For example, a stablecoin issuer might leverage this standard to provide a method for an end user or web-based end user client to ensure that the asset their wallet is interacting with is indeed the contract issued or controlled by the owner or administrator of a well known DNS domain.</p> <p><strong>Example 1</strong>:</p> <p>A user visits merchant.com who accepts payments via paymentprocessor.com. The business behind paymentprocessor.com has previously released a stable coin for easier cross-border payments which adheres to this ERC. On the checkout page, paymentprocessor.com is mounted as an iframe component. If the user has installed a browser-extension wallet compatible with this standard, then the wallet can detect the domain of the iframe in the context of the checkout page, discover and verify the stable coin's association with paymentprocessor.com, and automatically prompt to complete the purchase in paymentprocessor.com's stable coin.</p> <p><strong>Example 2</strong>:</p> <p>A user visits nftmarketplace.io to buy a limited release NFT from theirfavoritebrand.com. The marketplace webapp can leverage this ERC to allow the user to search by domain name and also indicate to the user that an NFT of interest is indeed an authentic asset associated with theirfavoritebrand.com.</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> <h4 id="definition-etld-1">Definition: eTLD+1</h4> <p>The term TLD stands for <em>top-level domain</em> and is always the part of a domain name which follows the final dot in a URL (e.g. <code>.com</code> or <code>.net</code>). If only domains directly under TLDs where registrable by a single organization, then it would be guaranteed that <code>myexample.com</code>, <code>abc.myexample.com</code>, and <code>def.myexample.com</code> all belonged to the same organization.</p> <p>However, this is not the case in general since many DNS registrars allow organizations to register domain names below the top level (examples include <code>sussex.ac.uk</code> and <code>aber.ac.uk</code> which are controlled by different institutions). These types of domains are referred to as eTLDs (effective top-level domains) and represent a domain under which domain names can be registered by a single organization. For example, the eTLD of <code>myexample.com</code> is <code>.com</code> and the eTLD of <code>sussex.ac.uk</code> is <code>.ac.uk</code> since individual organizations can be issued their own domain names under both <code>.com</code> and <code>.ac.uk</code>.</p> <p>Therefore, an eTLD+1 is an eTLD <em>plus</em> this next part on the domain name. Since eTLDs are by definition registerable, all domains with the same eTLD+1 are owned by the same organization, which makes them appropriate to utilize in this proposal for associating a smart contract with a single business or organization entity.</p> <h3 id="contract-pointers-in-txt-records">Contract Pointers in TXT Records</h3> <p>The owner of an eTLD+1 domain name MUST create a TXT record in their DNS settings that serves as a pointer to all relevant smart contracts they wish to associate with their domain.</p> <p><a rel="external" href="https://www.rfc-editor.org/rfc/rfc1035#section-3.3.14">TXT records</a> are not intended (nor permitted by most DNS servers) to store large amounts of data. Every DNS provider has their own vendor-specific character limits. However, an EVM-compatible address string is 42 characters, so most DNS providers will allow for dozens of contract addresses to be stored under a single record. Furthermore, a domain is allowed to have multiple TXT records associated with the same host and the content of all duplicate records can be retrieved in a single DoH query.</p> <p>A TXT record pointing to an organization's smart contracts MUST adhere to the following schema:</p> <ul> <li><code>HOST</code>: <code>ERC-7529.&lt;chain_id&gt;._domaincontracts</code> (where <code>&lt;chain_id&gt;</code> is replaced by the decimal representation of the chain id)</li> <li><code>VALUE</code>: &lt;<code>address 1</code>&gt;,&lt;<code>address 2</code>&gt;,...</li> </ul> <p>It is RECOMMENDED that EVM address strings adhere to <a href="https://wg-eips.ritovision.com/1191/">ERC-1191</a> so that the browser client can checksum the validity of the address and its target network before making an RPC call.</p> <p>A user's web application can access TXT records directly from a DNS registrar who supports DoH with <code>fetch</code>. An example query of a DoH server that supports JSON format will look like:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-keyword">await</span><span class="z-entity z-name"> fetch</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">https://example-doh-provider.com/dns-query?name=ERC-7529.1._domaincontracts.myexample.com&amp;type=TXT</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> {</span></span> <span class="giallo-l"><span> headers</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> Accept</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">application/dns-json</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></code></pre><h3 id="smart-contract-association-with-a-domain">Smart Contract Association with a Domain</h3> <p>Any smart contract MAY implement this ERC to provide a verification mechanism of smart contract addresses listed in a compatible TXT record.</p> <p>A smart contract need only store one new member variable, <code>domains</code>, which is a mapping from the keccak256 hash of all eTLD+1 domain strings associated with the business or organization which deployed (or is closely associated with) the contract to a boolean. This member variable can be written to with the external functions <code>addDomain</code> and <code>removeDomain</code>. The <code>domains</code> member variable can be queried by the <code>checkDomain</code> function which takes a string representing an eTLD+1 and returns true if the contract has been associated with the domain and false otherwise.</p> <p>Lastly, the contract MAY emit events when eTLD+1 domains are added (<code>AddDomain</code>) or removed (<code>RemoveDomain</code>) from the <code>domains</code> map. This can be useful for determining all domains associated with a contract when they are not known ahead of time by the client.</p> <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"> Optional event emitted when a domain is 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"> domain</span><span class="z-comment"> eTLD+1 associated with the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AddDomain</span><span>(</span><span class="z-support">string</span><span class="z-variable"> domain</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"> Optional event emitted when a domain is 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"> domain</span><span class="z-comment"> eTLD+1 that is no longer associated with the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RemoveDomain</span><span>(</span><span class="z-support">string</span><span class="z-variable"> domain</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"> a mapping from the keccak256 hash of eTLD+1 domains associated with this contract to a boolean</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"> bool</span><span>)</span><span> domains</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"> a getter function that takes an eTLD+1 domain string and returns true if associated with 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"> domain</span><span class="z-comment"> a string representing an eTLD+1 domain</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkDomain</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> domain</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></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 authenticated method to add an eTLD+1 domain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> domain</span><span class="z-comment"> a string representing an eTLD+1 domain associated with the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addDomain</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> domain</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"> an authenticated method to remove an eTLD+1 domain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> domain</span><span class="z-comment"> a string representing an eTLD+1 domain that is no longer associated with the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeDomain</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> domain</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span><span> </span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="client-side-verification">Client-side Verification</h3> <p>When a client detects a compatible TXT record listed on an eTLD+1, it SHOULD loop through each listed contract address and, via an appropriate RPC provider, assert that each of the smart contracts returns <code>true</code> when the eTLD+1 string is passed to the <code>checkDomain</code> function.</p> <p>Alternatively, if a client is inspecting a contract that implements this ERC, the client SHOULD inspect the <code>AddDomain</code> and <code>RemoveDomain</code> events to calculate if one or more eTLD+1 domains are actively associated with the contract. The user client SHOULD attempt to fetch TXT records from all associated eTLD+1 domains to verify its association or authenticity. The client MUST confirm that each contract address is contained in a TXT record's <code>VALUE</code> field of the eTLD+1 pointed to by the contract's <code>domains</code> mapping.</p> <h2 id="rationale">Rationale</h2> <p>In this specification, the TXT record <code>HOST</code> naming scheme is designed to mimic the DKIM naming convention. Additionally, this naming scheme makes it simple to programmatically ascertain if any smart contracts are associated with the domain on a given blockchain network. Prepending with <code>ERC-7529</code> will prevent naming collisions with other TXT records. The value of <code>&lt;chain_id&gt;</code> is simply the decimal representation of the chain id associated with the target blockchain network (i.e. <code>1</code> for Ethereum mainnet or <code>11155111</code> for Sepolia) where the smart contracts are deployed. So, a typical <code>HOST</code> might be: <code>ERC-7529.1._domainContracts</code>, <code>ERC-7529.11155111._domaincontracts</code>, etc.</p> <p>A user client working with smart contracts implementing this proposal is protected by cross-checking that two independent sources of information agree with each other (i.e. DNS and a blockchain network). As long as the <code>addDomain</code> and <code>removeDomain</code> calls on the smart contract are properly authenticated (as shown in the reference implementation), the values in the domains field must have been set by a controller of the contract. The contract addresses in the TXT records can only be set by the owner of the eTLD+1 domain. For these two values to align the same organization must control both resources.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The implementation of <code>checkDomain</code>, <code>addDomain</code> and <code>removeDomain</code> is a trivial exercise, but candidate implementations are given here for completeness:</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"> checkDomain</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"> domain</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-keyword"> return</span><span> domains</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>domain</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"> addDomain</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"> domain</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyRole</span><span>(</span><span class="z-entity z-name">DEFAULT_ADMIN_ROLE</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> domains</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>domain</span><span>)</span><span>)</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> AddDomain</span><span>(</span><span>domain</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"> removeDomain</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"> domain</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyRole</span><span>(</span><span class="z-entity z-name">DEFAULT_ADMIN_ROLE</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>domains</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>domain</span><span>)</span><span>)</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> true</span><span>,</span><span class="z-string"> &quot;ERC7529: eTLD+1 currently not associated with this contract&quot;</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"><span> domains</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>domain</span><span>)</span><span>)</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> RemoveDomain</span><span>(</span><span>domain</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <p><strong>NOTE</strong>: Appropriate account authentication MUST be applied to <code>addDomain</code> and <code>removeDomain</code> so that only authorized users may update the <code>domains</code> mapping. In the given reference implementation the <code>onlyRole</code> modifier is used to restrict call privileges to accounts with the <code>DEFAULT_ADMIN_ROLE</code> which can be added to any contract with the OpenZeppelin access control abstract class.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Due to the reliance on traditional DNS systems, this ERC is susceptible to attacks on this technology, such as domain hijacking. Additionally, it is the responsibility of the smart contract author to ensure that <code>addDomain</code> and <code>removeDomain</code> are authenticated properly, otherwise an attacker could associate their smart contract with an undesirable domain, which would simply break the ability to verify association with the proper domain.</p> <p>It is worth noting that for an attacker to falsy verify a contract against a domain would require them to compromise both the DNS settings <strong>and</strong> the smart contract itself. In this scenario, the attacker has likely also compromised the business' email domains as well.</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-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Qi Zhouhttps://github.com/qizhou Chao Pihttps://github.com/pichaoqkc Sam Wilsonhttps://github.com/SamWilsn Nicolas Deschildrehttps://github.com/nand2 https://wg-eips.ritovision.com/6860/

A translation of an HTTP-style Web3 URL to an EVM call message

<h2 id="abstract">Abstract</h2> <p>This standard translates an <a rel="external" href="https://www.rfc-editor.org/rfc/rfc3986">RFC 3986</a> URI like <code>web3://uniswap.eth/</code> to an EVM message such as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>EVMMessage {</span></span> <span class="giallo-l"><span> To: 0xaabbccddee.... // where uniswap.eth&#39;s address registered at ENS</span></span> <span class="giallo-l"><span> Calldata: 0x</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>⚠️ This proposal updates <a href="https://wg-eips.ritovision.com/4804/">ERC-4804</a> with minor corrections, clarifications and modifications.</p> <h2 id="motivation">Motivation</h2> <p>Currently, reading data from Web3 generally relies on a translation done by a Web2 proxy to Web3 blockchain. The translation is mostly done by the proxies such as dApp websites/node service provider/etherscan, which are out of the control of users. The standard here aims to provide a simple way for Web2 users to directly access the content of Web3, especially on-chain Web contents such as SVG/HTML. Moreover, this standard enables interoperability with other standards already compatible with URIs, like SVG/HTML.</p> <h2 id="specification">Specification</h2> <p>This specification only defines read-only (i.e. Solidity's <code>view</code> functions) semantics. State modifying functions may be defined as a future extension.</p> <p>This specification uses the Augmented Backus-Naur Form (ABNF) notation of <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2234">RFC 2234</a>. The complete URI syntax is listed in Appendix A.</p> <p>A Web3 URL is an ASCII string in the following form :</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3URL = schema &quot;://&quot; [ userinfo &quot;@&quot; ] contractName [ &quot;:&quot; chainid ] pathQuery [ &quot;#&quot; fragment ]</span></span> <span class="giallo-l"><span>schema = &quot;w3&quot; / &quot;web3&quot;</span></span> <span class="giallo-l"><span>userinfo = address</span></span></code></pre> <p><strong>userinfo</strong> indicates which user is calling the EVM, i.e., "From" field in EVM call message. If not specified, the protocol will use 0x0 as the sender address.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>contractName = address </span></span> <span class="giallo-l"><span> / domainName</span></span> <span class="giallo-l"><span>address = &quot;0x&quot; 20( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span>domainName = *( unreserved / pct-encoded / sub-delims ) ; As in RFC 3986</span></span></code></pre> <p><strong>contractName</strong> indicates the contract to be called, i.e., the "To" field in the EVM call message. If the <strong>contractName</strong> is an address then it will be used for the "To" field. Otherwise, <strong>contractName</strong> is a domain name from a domain name service, and it must be resolved to an address to use for the "To" field.</p> <p>The way to resolve the domain name from a domain name service to an address is specified in <a href="https://wg-eips.ritovision.com/6821/">ERC-6821</a> for the Ethereum Name service, and will be discussed in later ERCs for other name services.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>chainid = %x31-39 *DIGIT</span></span></code></pre> <p><strong>chainid</strong> indicates which chain to resolve <strong>contractName</strong> and call the message. If not specified, the protocol will use the primary chain of the name service provider used, e.g., 1 for eth. If no name service provider was used, the default chainid is 1.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pathQuery = mPathQuery ; path+query for manual mode</span></span> <span class="giallo-l"><span> / aPathQuery ; path+query for auto mode</span></span></code></pre> <p><strong>pathQuery</strong>, made of the path and optional query, will have a different structure whether the resolve mode is "manual" or "auto".</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>fragment = *VCHAR</span></span></code></pre> <p><strong>fragment</strong>, like in HTTP URLs, is a string of characters meant to refer to a resource, and is not transmitted to the smart contract.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3UrlRef = web3URL </span></span> <span class="giallo-l"><span> / relativeWeb3URL</span></span> <span class="giallo-l"><span>relativeWeb3URL = relPathQuery</span></span> <span class="giallo-l"><span>relPathQuery = relMPathQuery ; Relative URL path+query for manual mode</span></span> <span class="giallo-l"><span> / relAPathQuery ; Relative URL path+query for auto mode</span></span></code></pre> <p>Relative URLs are supported, but the support differs based on the resolve mode.</p> <h3 id="resolve-mode">Resolve Mode</h3> <p>Once the "To" address and chainid are determined, the protocol will check the resolver mode of contract by calling the <code>resolveMode</code> method of the "To" address. The Solidity signature of <code>resolveMode</code> is:</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"> resolveMode</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">bytes32</span><span>)</span><span>;</span></span></code></pre> <p>The protocol currently supports two resolve modes: auto and manual.</p> <ul> <li>The manual mode will be used if the <code>resolveMode</code> return value is <code>0x6d616e75616c0000000000000000000000000000000000000000000000000000</code>, i.e., "manual" in bytes32</li> <li>The auto mode will be used if : <ul> <li>the <code>resolveMode</code> return value is <code>0x6175746f00000000000000000000000000000000000000000000000000000000</code>, i.e, "auto" in bytes32, or</li> <li>the <code>resolveMode</code> return value is <code>0x0000000000000000000000000000000000000000000000000000000000000000</code>, or</li> <li>the call to <code>resolveMode</code> throws an error (method not implemented or error thrown from the method)</li> </ul> </li> <li>Otherwise, the protocol will fail the request with the error "unsupported resolve mode".</li> </ul> <h4 id="manual-mode">Manual Mode</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>mPathQuery = mPath [ &quot;?&quot; mQuery ]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>mPath = mPathAbempty ; begins with &quot;/&quot; or is empty</span></span> <span class="giallo-l"><span>mPathAbempty = [ *( &quot;/&quot; segment ) &quot;/&quot; segment [ &quot;.&quot; fileExtension ] ]</span></span> <span class="giallo-l"><span>segment = *pchar ; as in RFC 3986</span></span> <span class="giallo-l"><span>fileExtension = 1*( ALPHA / DIGIT )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>mQuery = *( pchar / &quot;/&quot; / &quot;?&quot; ) ; as in RFC 3986</span></span></code></pre> <p>The manual mode will use the raw <strong>mPathQuery</strong> as calldata of the message directly (no percent-encoding decoding will be done). If <strong>mPathQuery</strong> is empty, the sent calldata will be <code>/</code> (0x2f).</p> <p>The returned message data will be treated as ABI-encoded bytes and the decoded bytes will be returned to the frontend.</p> <p>The MIME type returned to the frontend is <code>text/html</code> by default, but will be overridden if a <strong>fileExtension</strong> is present. In this case, the MIME type will be deduced from the filename extension.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>relMPathQuery = relMPath [ &quot;?&quot; mQuery ]</span></span> <span class="giallo-l"><span>relMPath = mPathAbsolute ; begins with &quot;/&quot; but not &quot;//&quot;</span></span> <span class="giallo-l"><span> / mPathNoscheme ; begins with a non-colon segment</span></span> <span class="giallo-l"><span> / mPathEmpty ; zero characters</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>mPathAbsolute = &quot;/&quot; [ segmentNz *( &quot;/&quot; segment ) ] [ &quot;.&quot; fileExtension ]</span></span> <span class="giallo-l"><span>mPathNoscheme = segmentNzNc *( &quot;/&quot; segment ) [ &quot;.&quot; fileExtension ]</span></span> <span class="giallo-l"><span>mPathEmpty = 0&lt;pchar&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>segmentNz = 1*pchar ; as in RFC 3986</span></span> <span class="giallo-l"><span>segmentNzNc = 1*( unreserved / pct-encoded / sub-delims / &quot;@&quot; )</span></span> <span class="giallo-l"><span> ; as in RFC 3986: non-zero-length segment without any colon &quot;:&quot;</span></span></code></pre> <p>Support for manual mode relative URLs is similar to HTTP URLs : URLs relative to the current contract are allowed, both with an absolute path and a relative path.</p> <h4 id="auto-mode">Auto Mode</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>aPathQuery = aPath [ &quot;?&quot; aQuery ]</span></span> <span class="giallo-l"><span>aPath = [ &quot;/&quot; [ method *( &quot;/&quot; argument ) ] ]</span></span></code></pre> <p>In the auto mode, if <strong>aPath</strong> is empty or "/", then the protocol will call the target contract with empty calldata. Otherwise, the calldata of the EVM message will use standard Solidity contract ABI.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>method = ( ALPHA / &quot;$&quot; / &quot;_&quot; ) *( ALPHA / DIGIT / &quot;$&quot; / &quot;_&quot; )</span></span></code></pre> <p><strong>method</strong> is a string of the function method to be called</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>argument = boolArg</span></span> <span class="giallo-l"><span> / uintArg</span></span> <span class="giallo-l"><span> / intArg</span></span> <span class="giallo-l"><span> / addressArg</span></span> <span class="giallo-l"><span> / bytesArg</span></span> <span class="giallo-l"><span> / stringArg</span></span> <span class="giallo-l"><span>boolArg = [ &quot;bool!&quot; ] ( &quot;true&quot; / &quot;false&quot; )</span></span> <span class="giallo-l"><span>uintArg = [ &quot;uint&quot; [ intSizes ] &quot;!&quot; ] 1*DIGIT</span></span> <span class="giallo-l"><span>intArg = &quot;int&quot; [ intSizes ] &quot;!&quot; 1*DIGIT</span></span> <span class="giallo-l"><span>intSizes = &quot;8&quot; / &quot;16&quot; / &quot;24&quot; / &quot;32&quot; / &quot;40&quot; / &quot;48&quot; / &quot;56&quot; / &quot;64&quot; / &quot;72&quot; / &quot;80&quot; / &quot;88&quot; / &quot;96&quot; / &quot;104&quot; / &quot;112&quot; / &quot;120&quot; / &quot;128&quot; / &quot;136&quot; / &quot;144&quot; / &quot;152&quot; / &quot;160&quot; / &quot;168&quot; / &quot;176&quot; / &quot;184&quot; / &quot;192&quot; / &quot;200&quot; / &quot;208&quot; / &quot;216&quot; / &quot;224&quot; / &quot;232&quot; / &quot;240&quot; / &quot;248&quot; / &quot;256&quot;</span></span> <span class="giallo-l"><span>addressArg = [ &quot;address!&quot; ] ( address / domainName )</span></span> <span class="giallo-l"><span>bytesArg = [ &quot;bytes!&quot; ] bytes</span></span> <span class="giallo-l"><span> / &quot;bytes1!0x&quot; 1( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes2!0x&quot; 2( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span> / &quot;bytes32!0x&quot; 32( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span>stringArg = &quot;string!&quot; *pchar [ &quot;.&quot; fileExtension ]</span></span></code></pre> <p><strong>argument</strong> is an argument of the method with a type-agnostic syntax of <code>[ type "!" ] value</code>. If <strong>type</strong> is specified, the value will be translated to the corresponding type. The protocol currently supports these basic types: bool, int, uint, int&lt;X&gt;, uint&lt;X&gt; (with X ranging from 8 to 256 in steps of 8), address, bytes&lt;X&gt; (with X ranging from 1 to 32), bytes, and string. If <strong>type</strong> is not specified, then the type will be automatically detected using the following rule in a sequential way:</p> <ol> <li><strong>type</strong>="uint256", if <strong>value</strong> is digits; or</li> <li><strong>type</strong>="bytes32", if <strong>value</strong> is in the form of 0x+32-byte-data hex; or</li> <li><strong>type</strong>="address", if <strong>value</strong> is in the form of 0x+20-byte-data hex; or</li> <li><strong>type</strong>="bytes", if <strong>value</strong> is in the form of 0x followed by any number of bytes besides 20 or 32; or</li> <li><strong>type</strong>="bool", if <strong>value</strong> is either <code>true</code> or <code>false</code>; or</li> <li>else <strong>type</strong>="address" and parse the argument as a domain name. If unable to resolve the domain name, an unsupported name service provider error will be returned.</li> </ol> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>aQuery = attribute *( &quot;&amp;&quot; attribute )</span></span> <span class="giallo-l"><span>attribute = attrName &quot;=&quot; attrValue</span></span> <span class="giallo-l"><span>attrName = &quot;returns&quot;</span></span> <span class="giallo-l"><span> / &quot;returnTypes&quot;</span></span> <span class="giallo-l"><span>attrValue = [ &quot;(&quot; [ retTypes ] &quot;)&quot; ]</span></span> <span class="giallo-l"><span>retTypes = retType *( &quot;,&quot; retType )</span></span> <span class="giallo-l"><span>retType = retRawType *( &quot;[&quot; [ %x31-39 *DIGIT ] &quot;]&quot; )</span></span> <span class="giallo-l"><span>retRawType = &quot;(&quot; retTypes &quot;)&quot;</span></span> <span class="giallo-l"><span> / retBaseType</span></span> <span class="giallo-l"><span>retBaseType = &quot;bool&quot; / &quot;uint&quot; [ intSizes ] / &quot;int&quot; [ intSize ] / &quot;address&quot; / &quot;bytes&quot; [ bytesSizes ] / &quot;string&quot;</span></span> <span class="giallo-l"><span>bytesSizes = %x31-39 ; 1-9</span></span> <span class="giallo-l"><span> / ( &quot;1&quot; / &quot;2&quot; ) DIGIT ; 10-29</span></span> <span class="giallo-l"><span> / &quot;31&quot; / &quot;32&quot; ; 31-32</span></span></code></pre> <p>The "returns" attribute in <strong>aQuery</strong> tells the format of the returned data. It follows the syntax of the arguments part of the ethereum ABI function signature (<code>uint</code> and <code>int</code> aliases are authorized).</p> <ul> <li>If the "returns" attribute value is undefined or empty, the returned message data will be treated as ABI-encoded bytes and the decoded bytes will be returned to the frontend. The MIME type returned to the frontend will be undefined by default, but will be overridden if the last argument is of string type and has a <strong>fileExtension</strong>, in which case the MIME type will be deduced from the filename extension. (Note that <strong>fileExtension</strong> is not excluded from the string argument given to the smartcontract)</li> <li>If the "returns" attribute value is equal to "()", the raw bytes of the returned message data will be returned, encoded as a "0x"-prefixed hex string in an array in JSON format: <code>["0xXXXXX"]</code></li> <li>Otherwise, the returned message data will be ABI-decoded in the data types specified in the <strong>returns</strong> value and encoded in JSON format. The encoding of the data will follow the Ethereum JSON-RPC format: <ul> <li>Unformatted data (bytes, address) will be encoded as hex, prefixed with "0x", two hex digits per byte</li> <li>Quantities (integers) will be encoded as hex, prefix with "0x", the most compact representation (slight exception: zero should be represented as "0x0")</li> <li>Boolean and strings will be native JSON boolean and strings</li> </ul> </li> </ul> <p>If multiple "returns" attributes are present, the value of the last "returns" attribute will be applied. Note that "returnTypes" is the alias of "returns", but it is not recommended to use and is mainly for <a href="https://wg-eips.ritovision.com/4804/">ERC-4804</a> backward-compatible purpose.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>relAPathQuery = aPath [ &quot;?&quot; aQuery ]</span></span></code></pre> <p>Support for auto mode relative URLs is limited : URLs relative to the current contract are allowed and will either reference itself (empty), the <code>/</code> path or a full method and its arguments.</p> <h3 id="examples">Examples</h3> <h4 id="example-1a">Example 1a</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://w3url.eth/</span></span></code></pre> <p>where the contract of <strong>w3url.eth</strong> is in manual mode.</p> <p>The protocol will find the address of <strong>w3url.eth</strong> from ENS in chainid 1 (Mainnet). Then the protocol will call the address with "Calldata" = <code>keccak("resolveMode()")[0:4]</code> = "0xDD473FAE", which returns "manual" in ABI-type "(bytes32)". After determining the manual mode of the contract, the protocol will call the address with "To" = <strong>contractAddress</strong> and "Calldata" = "0x2F". The returned data will be treated as ABI-type "(bytes)", and the decoded bytes will be returned to the frontend, with the information that the MIME type is <code>text/html</code>.</p> <h4 id="example-1b">Example 1b</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://w3url.eth/</span></span></code></pre> <p>where the contract of <strong>w3url.eth</strong> is in auto mode.</p> <p>The protocol will find the address of <strong>w3url.eth</strong> from ENS in chainid 1 (Mainnet). Then the protocol will call the address with "Calldata" = <code>keccak("resolveMode()")[0:4]</code> = "0xDD473FAE", which returns "", i.e., the contract is in auto mode. After determining the auto mode of the contract, the protocol will call the address with "To" = <strong>contractAddress</strong> and "Calldata" = "". The returned data will be treated as ABI-type "(bytes)", and the decoded bytes will be returned to the frontend, with the information that the MIME type is undefined.</p> <h4 id="example-2">Example 2</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://cyberbrokers-meta.eth/renderBroker/9999</span></span></code></pre> <p>where the contract of <strong>cyberbrokers-meta.eth</strong> is in auto mode.</p> <p>The protocol will find the address of <strong>cyberbrokers-meta.eth</strong> from ENS on chainid 1 (Mainnet). Then the protocol will call the address with "Calldata" = <code>keccak("resolveMode()")[0:4]</code> = "0xDD473FAE", which returns "", i.e., the contract is in auto mode. After determining the auto mode of the contract, the protocol will call the address with "To" = <strong>contractAddress</strong> and "Calldata" = "0x" + <code>keccak("renderBroker(uint256)")[0:4] + abi.encode(uint256(9999))</code>. The returned data will be treated as ABI-type "(bytes)", and the decoded bytes will be returned to the frontend, with the information that the MIME type is undefined.</p> <h4 id="example-3">Example 3</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://vitalikblog.eth:5/</span></span></code></pre> <p>where the contract of <strong>vitalikblog.eth:5</strong> is in manual mode.</p> <p>The protocol will find the address of <strong>vitalikblog.eth</strong> from ENS on chainid 5 (Goerli). Then after determining the contract is in manual mode, the protocol will call the address with "To" = <strong>contractAddress</strong> and "Calldata" = "0x2F" with chainid = 5. The returned data will be treated as ABI-type "(bytes)", and the decoded bytes will be returned to the frontend, with the information that the MIME type is <code>text/html</code>.</p> <h4 id="example-4">Example 4</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://0xe4ba0e245436b737468c206ab5c8f4950597ab7f:42170/</span></span></code></pre> <p>where the contract "0xe4ba0e245436b737468c206ab5c8f4950597ab7f:42170" is in manual mode.</p> <p>After determining the contract is in manual mode, the protocol will call the address with "To" = "0xe4ba0e245436b737468c206ab5c8f4950597ab7f" and "Calldata" = "0x2F" with chainid = 42170 (Arbitrum Nova). The returned data will be treated as ABI-type "(bytes)", and the decoded bytes will be returned to the frontend, with the information that the MIME type is <code>text/html</code>.</p> <h4 id="example-5">Example 5</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/balanceOf/vitalik.eth?returns=(uint256)</span></span></code></pre> <p>where the contract "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48" is in auto mode.</p> <p>The protocol will find the addresses of <strong>vitalik.eth</strong> from ENS on chainid 1 (Mainnet) and then call the method "balanceOf(address)" of the contract with the <strong>vitalik.eth</strong>'s address. The returned data from the call of the contract will be treated as ABI-type "(uint256)", and the decoded data will be returned to the frontend in JSON format like <code>[ "0x9184e72a000" ]</code>, with the information that the MIME type is <code>application/json</code>.</p> <h4 id="example-6">Example 6</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/balanceOf/vitalik.eth?returns=()</span></span></code></pre> <p>where the contract ”0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48“ is in auto mode.</p> <p>The protocol will find the address of <strong>vitalik.eth</strong> from ENS on chainid 1 (Mainnet) and then call the method "balanceOf(address)" of the address. The returned data from the call of the contract will be treated as raw bytes and will be encoded in JSON format like <code>["0x000000000000000000000000000000000000000000000000000009184e72a000"]</code> and returned to the frontend, with the information that the MIME type is <code>application/json</code>.</p> <h3 id="appendix-a-complete-abnf-for-web3-urls">Appendix A: Complete ABNF for Web3 URLs</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3URL = schema &quot;://&quot; [ userinfo &quot;@&quot; ] contractName [ &quot;:&quot; chainid ] pathQuery [ &quot;#&quot; fragment ]</span></span> <span class="giallo-l"><span>schema = &quot;w3&quot; / &quot;web3&quot;</span></span> <span class="giallo-l"><span>userinfo = address</span></span> <span class="giallo-l"><span>contractName = address </span></span> <span class="giallo-l"><span> / domainName</span></span> <span class="giallo-l"><span>chainid = %x31-39 *DIGIT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>pathQuery = mPathQuery ; path+query for manual mode</span></span> <span class="giallo-l"><span> / aPathQuery ; path+query for auto mode</span></span> <span class="giallo-l"><span>fragment = *VCHAR</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>web3UrlRef = web3URL </span></span> <span class="giallo-l"><span> / relativeWeb3URL</span></span> <span class="giallo-l"><span>relativeWeb3URL = relPathQuery</span></span> <span class="giallo-l"><span>relPathQuery = relMPathQuery ; Relative URL path+query for manual mode</span></span> <span class="giallo-l"><span> / relAPathQuery ; Relative URL path+query for auto mode</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>mPathQuery = mPath [ &quot;?&quot; mQuery ]</span></span> <span class="giallo-l"><span>mPath = mPathAbempty ; begins with &quot;/&quot; or is empty</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>relMPathQuery = relMPath [ &quot;?&quot; mQuery ]</span></span> <span class="giallo-l"><span>relMPath = mPathAbsolute ; begins with &quot;/&quot; but not &quot;//&quot;</span></span> <span class="giallo-l"><span> / mPathNoscheme ; begins with a non-colon segment</span></span> <span class="giallo-l"><span> / mPathEmpty ; zero characters</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>mPathAbempty = [ *( &quot;/&quot; segment ) &quot;/&quot; segment [ &quot;.&quot; fileExtension ] ]</span></span> <span class="giallo-l"><span>mPathAbsolute = &quot;/&quot; [ segmentNz *( &quot;/&quot; segment ) ] [ &quot;.&quot; fileExtension ]</span></span> <span class="giallo-l"><span>mPathNoscheme = segmentNzNc *( &quot;/&quot; segment ) [ &quot;.&quot; fileExtension ]</span></span> <span class="giallo-l"><span>mPathEmpty = 0&lt;pchar&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>segment = *pchar ; as in RFC 3986</span></span> <span class="giallo-l"><span>segmentNz = 1*pchar ; as in RFC 3986</span></span> <span class="giallo-l"><span>segmentNzNc = 1*( unreserved / pct-encoded / sub-delims / &quot;@&quot; )</span></span> <span class="giallo-l"><span> ; as in RFC 3986: non-zero-length segment without any colon &quot;:&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>mQuery = *( pchar / &quot;/&quot; / &quot;?&quot; ) ; as in RFC 3986</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>aPathQuery = aPath [ &quot;?&quot; aQuery ]</span></span> <span class="giallo-l"><span>aPath = [ &quot;/&quot; [ method *( &quot;/&quot; argument ) ] ]</span></span> <span class="giallo-l"><span>relAPathQuery = aPath [ &quot;?&quot; aQuery ]</span></span> <span class="giallo-l"><span>method = ( ALPHA / &quot;$&quot; / &quot;_&quot; ) *( ALPHA / DIGIT / &quot;$&quot; / &quot;_&quot; )</span></span> <span class="giallo-l"><span>argument = boolArg</span></span> <span class="giallo-l"><span> / uintArg</span></span> <span class="giallo-l"><span> / intArg</span></span> <span class="giallo-l"><span> / addressArg</span></span> <span class="giallo-l"><span> / bytesArg</span></span> <span class="giallo-l"><span> / stringArg</span></span> <span class="giallo-l"><span>boolArg = [ &quot;bool!&quot; ] ( &quot;true&quot; / &quot;false&quot; )</span></span> <span class="giallo-l"><span>uintArg = [ &quot;uint&quot; [ intSizes ] &quot;!&quot; ] 1*DIGIT</span></span> <span class="giallo-l"><span>intArg = &quot;int&quot; [ intSizes ] &quot;!&quot; 1*DIGIT</span></span> <span class="giallo-l"><span>intSizes = &quot;8&quot; / &quot;16&quot; / &quot;24&quot; / &quot;32&quot; / &quot;40&quot; / &quot;48&quot; / &quot;56&quot; / &quot;64&quot; / &quot;72&quot; / &quot;80&quot; / &quot;88&quot; / &quot;96&quot; / &quot;104&quot; / &quot;112&quot; / &quot;120&quot; / &quot;128&quot; / &quot;136&quot; / &quot;144&quot; / &quot;152&quot; / &quot;160&quot; / &quot;168&quot; / &quot;176&quot; / &quot;184&quot; / &quot;192&quot; / &quot;200&quot; / &quot;208&quot; / &quot;216&quot; / &quot;224&quot; / &quot;232&quot; / &quot;240&quot; / &quot;248&quot; / &quot;256&quot;</span></span> <span class="giallo-l"><span>addressArg = [ &quot;address!&quot; ] ( address / domainName )</span></span> <span class="giallo-l"><span>bytesArg = [ &quot;bytes!&quot; ] bytes</span></span> <span class="giallo-l"><span> / &quot;bytes1!0x&quot; 1( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes2!0x&quot; 2( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes3!0x&quot; 3( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes4!0x&quot; 4( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes5!0x&quot; 5( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes6!0x&quot; 6( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes7!0x&quot; 7( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes8!0x&quot; 8( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes9!0x&quot; 9( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes10!0x&quot; 10( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes11!0x&quot; 11( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes12!0x&quot; 12( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes13!0x&quot; 13( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes14!0x&quot; 14( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes15!0x&quot; 15( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes16!0x&quot; 16( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes17!0x&quot; 17( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes18!0x&quot; 18( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes19!0x&quot; 19( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes20!0x&quot; 20( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes21!0x&quot; 21( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes22!0x&quot; 22( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes23!0x&quot; 23( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes24!0x&quot; 24( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes25!0x&quot; 25( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes26!0x&quot; 26( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes27!0x&quot; 27( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes28!0x&quot; 28( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes29!0x&quot; 29( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes30!0x&quot; 30( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes31!0x&quot; 31( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span> / &quot;bytes32!0x&quot; 32( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span>stringArg = &quot;string!&quot; *pchar [ &quot;.&quot; fileExtension ]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>aQuery = attribute *( &quot;&amp;&quot; attribute )</span></span> <span class="giallo-l"><span>attribute = attrName &quot;=&quot; attrValue</span></span> <span class="giallo-l"><span>attrName = &quot;returns&quot;</span></span> <span class="giallo-l"><span> / &quot;returnTypes&quot;</span></span> <span class="giallo-l"><span>attrValue = [ &quot;(&quot; [ retTypes ] &quot;)&quot; ]</span></span> <span class="giallo-l"><span>retTypes = retType *( &quot;,&quot; retType )</span></span> <span class="giallo-l"><span>retType = retRawType *( &quot;[&quot; [ %x31-39 *DIGIT ] &quot;]&quot; )</span></span> <span class="giallo-l"><span>retRawType = &quot;(&quot; retTypes &quot;)&quot;</span></span> <span class="giallo-l"><span> / retBaseType</span></span> <span class="giallo-l"><span>retBaseType = &quot;bool&quot; / &quot;uint&quot; [ intSizes ] / &quot;int&quot; [ intSize ] / &quot;address&quot; / &quot;bytes&quot; [ bytesSizes ] / &quot;string&quot;</span></span> <span class="giallo-l"><span>bytesSizes = %x31-39 ; 1-9</span></span> <span class="giallo-l"><span> / ( &quot;1&quot; / &quot;2&quot; ) DIGIT ; 10-29</span></span> <span class="giallo-l"><span> / &quot;31&quot; / &quot;32&quot; ; 31-32</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>domainName = *( unreserved / pct-encoded / sub-delims ) ; As in RFC 3986</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>fileExtension = 1*( ALPHA / DIGIT )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>address = &quot;0x&quot; 20( HEXDIG HEXDIG )</span></span> <span class="giallo-l"><span>bytes = &quot;0x&quot; *( HEXDIG HEXDIG )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>pchar = unreserved / pct-encoded / sub-delims / &quot;:&quot; / &quot;@&quot; ; As in RFC 3986</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>pct-encoded = &quot;%&quot; HEXDIG HEXDIG ; As in RFC 3986</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>unreserved = ALPHA / DIGIT / &quot;-&quot; / &quot;.&quot; / &quot;_&quot; / &quot;~&quot; ; As in RFC 3986</span></span> <span class="giallo-l"><span>sub-delims = &quot;!&quot; / &quot;$&quot; / &quot;&amp;&quot; / &quot;&#39;&quot; / &quot;(&quot; / &quot;)&quot;</span></span> <span class="giallo-l"><span> / &quot;*&quot; / &quot;+&quot; / &quot;,&quot; / &quot;;&quot; / &quot;=&quot; ; As in RFC 3986</span></span> <span class="giallo-l"></span></code></pre><h3 id="appendix-b-changes-versus-erc-4804">Appendix B: Changes versus <a href="https://wg-eips.ritovision.com/4804/">ERC-4804</a></h3> <h4 id="corrections">Corrections</h4> <ul> <li>Manual mode : <a href="https://wg-eips.ritovision.com/4804/">ERC-4804</a> stipulates that there is no interpretation of the path [ "?" query ]. This ERC indicates that there is in fact an interpretation of the path, for MIME type determination purpose.</li> <li>Auto mode : If there is no <strong>returns</strong> attribute in <strong>query</strong>, <a href="https://wg-eips.ritovision.com/4804/">ERC-4804</a> stipulates that the returned data is treated as ABI-encoded bytes32. This ERC indicates that in fact the returned data is treated as ABI-encoded bytes.</li> </ul> <h4 id="clarifications">Clarifications</h4> <ul> <li>Formal specification: This ERC add a ABNF definition of the URL format.</li> <li>Resolve mode: This ERC indicates more details on how the resolve mode is determined.</li> <li>Manual mode : This ERC indicates how to deal with URI-percent-encoding, the return data, and how the MIME type is determined.</li> <li>Auto mode : This ERC indicates in more details the encoding of the argument values, as well as the format and handling of the <strong>returns</strong> value.</li> <li>Examples : This ERC add more details to the examples.</li> </ul> <h4 id="modifications">Modifications</h4> <ul> <li>Protocol name: <a href="https://wg-eips.ritovision.com/4804/">ERC-4804</a> mentionned <code>ethereum-web3://</code> and <code>eth-web3://</code>, these are removed.</li> <li>Auto mode: Supported types: <a href="https://wg-eips.ritovision.com/4804/">ERC-4804</a> supported only uint256, bytes32, address, bytes, and string. This ERC add more types.</li> <li>Auto mode: Encoding of returned integers when a <strong>returns</strong> attribute is specified: <a href="https://wg-eips.ritovision.com/4804/">ERC-4804</a> suggested in example 5 to encode integers as strings. This ERC indicates to follow the Ethereum JSON RPC spec and encode integers as a hex string, prefixed with "0x".</li> </ul> <h2 id="rationale">Rationale</h2> <p>The purpose of the proposal is to add a decentralized presentation layer for Ethereum. With the layer, we are able to render any web content (including HTML/CSS/JPG/PNG/SVG, etc) on-chain using human-readable URLs, and thus EVM can be served as a decentralized backend. The design of the standard is based on the following principles:</p> <ul> <li> <p><strong>Human-readable</strong>. The Web3 URL should be easily recognized by human similar to Web2 URL (<code>http://</code>). As a result, we support names from name services to replace address for better readability. In addition, instead of using calldata in hex, we use human-readable method + arguments and translate them to calldata for better readability.</p> </li> <li> <p><strong>Maximum-Compatible with HTTP-URL standard</strong>. The Web3 URL should be compatible with HTTP-URL standard including relative pathing, query, fragment, percent-encoding, etc so that the support of existing HTTP-URL (e.g., by browser) can be easily extended to Web3 URL with minimal modification. This also means that existing Web2 users can easily migrate to Web3 with minimal extra knowledge of this standard.</p> </li> <li> <p><strong>Simple</strong>. Instead of providing explicit types in arguments, we use a "maximum likelihood" principle of auto-detecting the types of the arguments such as address, bytes32, and uint256. This could greatly minimize the length of URL, while avoiding confusion. In addition, explicit types are also supported to clear the confusion if necessary.</p> </li> <li> <p><strong>Flexible</strong>. The contract is able to override the encoding rule so that the contract has fine-control of understanding the actual Web resources that the users want to locate.</p> </li> </ul> <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> 2023-09-24T00:00:00+00:00 2026-02-11T14:48:25+00:00 Yush Ghttps://github.com/Divide-By-0aayushg@mit.edu Kobi Gurkanhttps://github.com/kobigurk Richard Liuhttps://github.com/rrrliu Vivek Bhupatirajuhttps://github.com/vb7401 Barry Whitehathttps://github.com/barryWhiteHat https://wg-eips.ritovision.com/7524/

A new signature scheme for Ethereum keypairs that allows for "nullifiers" to enable unique anonymity and zk voting.

<h2 id="abstract">Abstract</h2> <p>ZK-SNARKs have enabled ideation for new identity applications based on anonymous proof-of-ownership. One of the primary technologies that would enable the jump from existing apps to systems that require anonymous uniqueness is the development of verifiably deterministic signatures. Because Ethereum is based on ECDSA, there is no way right now for someone to verify that a signature is generated deterministically, even with ‘deterministic’ ECDSA signatures: a ZK-SNARK proof would need someone’s private key to do so, and some hardware wallets do not even allow viewing of a private key. Broadly, we don’t want to export/copy-paste the private key into a SNARK to be an intended user behavior, and most hardware wallets will not be able to run SNARK arithmetization inside a secure enclave for existing schemes (and nor do we want to standardize an entire proof system inside a wallet right now when they emerge and evolve almost every year). Thus we are left to select a new algorithm that offers us verifiable, deterministic nullifiers that can be SNARKed outside the enclave.</p> <p>One specific example of how such a signature can lead to unique pseudonymity is that we prove it was generated correctly in a ZK-SNARK that only reveals publicly the hash(signature), and the SNARK additionally proves some property the public key has (i.e. is in some anonymity set, has executed some set of actions on chain, etc). This proof is the only thing that is ever seen by other people, and so the hash(signature) can be used as a “nullifier”: a public commitment to a specific anonymous account, to forbid actions like double spending, or allow a consistent identity between anonymous actions. We aim to standardize a new verifiably deterministic signature algorithm that both uniquely identifies the keypair, and keeps the account identity secret, where verification does not require a secret key. The specific signature function we found (and will discuss for the rest of the post) is $hash(message, public\ key) ^ {secret\ key}$.</p> <h2 id="motivation">Motivation</h2> <ul> <li>Existing ZK applications have the advantage that there is no uniqueness constraint on the provers: that is, allowing the same wallet to prove itself as a member more than once is intended. However, many applications require a maximum of one action per user, especially protocols that desire Sybil resistance. Such protocols are not natively possible on Ethereum right now without mapping each address into an opt-in mapping that also maps a user’s private key to a new system, which adds complexity, loses atomicity, and does not benefit from the rich on-chain history of Ethereum accounts.</li> <li>Specific applications that require this tech include: <ul> <li>zk voting, where each account in some set has one vote</li> <li>pseudonymously claiming an airdrop like Stealthdrop</li> <li>moderating a pseudonymous forum, where people can prove that they are the same identity elsewhere in the forum</li> <li>zk proof of solvency — if you want two exchanges to prove they know a set of private keys that hold some balance, you need a way to ensure that two exchanges aren’t both claiming the same address, while keeping it private</li> </ul> </li> </ul> <p>As such, a deterministic value based on the Ethereum account’s ECDSA keypair is a necessary component of ensuring one action per user and enables all these applications on Ethereum.</p> <h2 id="specification">Specification</h2> <p>We propose a new signature standard that offers the following properties, to be implemented for standard ECDSA keys within wallets:</p> <ol> <li>It produces signatures that contain a deterministic component and a nondeterministic component. The deterministic component may be used as a <em>nullifier</em>.</li> <li>Signers can use existing secpk256k1 keypairs, such as those in hardware wallets that support Ethereum accounts. As a consequence, secret keys can remain in secure enclaves if there is a generator point multiplication API into the enclave (which Ledger for instance has).</li> </ol> <h3 id="parameters">Parameters</h3> <p>This scheme uses the secp256k1 curve, defined in <a href="https://wg-eips.ritovision.com/7524/./assets/sec2-v2.pdf">Standards for Efficient Cryptography 2 (SEC 2) v2</a>, page 9.</p> <p>We use the following notation to refer to the parameters of this curve:</p> <ul> <li>$g$: the base point (also called the generator) of the curve.</li> <li>$p$: the order of the curve.</li> <li>$F_p$: the finite field whose order is $p$.</li> </ul> <p>Note we use exponential notation to denote elliptic curve scalar multiplications.</p> <h3 id="public-key-encoding-functions">Public key encoding functions</h3> <h3 id="sec1">SEC1</h3> <p>This scheme uses the SEC1 elliptic curve point encoding scheme defined in <a href="https://wg-eips.ritovision.com/7524/./assets/sec1-v2.pdf">Standards for Efficient Cryptography 1 (SEC 1) v2</a>. Point compression is used. We use the notation $\mathsf{sec1}(pk)$ to denote the compressed encoding of secp256k1 curve point $pk$ as a bytestring of length 33.</p> <h3 id="hash-functions">Hash functions</h3> <p><strong>SHA256</strong></p> <p>This scheme uses the SHA256 hash function defined in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc4634">IETF RFC 4634</a>.</p> <p>In this document, we use the notation $\mathsf{sha256}(a_1,.. a_n)$ to denote the sha256 digest of the concatenation of $n$ values $a_1, ..., a_n$. The digest should then be interpreted as a big-endian value in the secp256k1 scalar field.</p> <h3 id="hash-to-curve">Hash-to-curve</h3> <p>We use the notation $\mathsf{htc}([a_1, ..., a_n])$ to denote the elliptic curve point which is the result of the <a rel="external" href="https://www.rfc-editor.org/rfc/rfc9380">IETF RFC 9380</a> <code>secp256k1_XMD:SHA-256_SSWU_RO_</code> in Appendix J.8.1. This hash-to-curve algorithm operates over the concatenation of $n$ values $a_1, ..., a_n$.</p> <h3 id="key-generation">Key generation</h3> <p>A <em>keypair</em> comprises of $(sk, pk)$, defined as such:</p> <ul> <li>$sk$: The user's secret key, which is a cryptographically secure random scalar in the field $F_p$.</li> <li>$pk$: The user's public key, defined as $g^{sk}$, which is a point on the secp256k1 curve.</li> </ul> <h3 id="signature-generation">Signature generation</h3> <p>This scheme builds upon the Chaum-Pedersen signature scheme <sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">1</a></sup>. Given a 32-byte message $m$ and a keypair $(sk, pk)$, a user may generate a signature as such:</p> <ol> <li>Compute $h = \mathsf{htc}([m, \mathsf{sec1}(pk)])$.</li> <li>Compute $z = h ^ r$.</li> <li>Compute the nullifier $\mathsf{nul} = h^{sk}$.</li> <li>Compute $c = \mathsf{sha256}([g, pk, h, \mathsf{nul}, g^r, z]])$.</li> <li>Compute $s = r + sk \cdot c$.</li> </ol> <p>The signature is $(z, s, g^r, c, \mathsf{nul})$.</p> <p>The length of the input to $\mathsf{htc}$ is always 65 bytes.</p> <p>Note that in this scheme, we compute $h$ as the hash of the message and $pk$, not the message and $r$. This is to make our scheme deterministic.</p> <h3 id="signature-verification-non-zk">Signature verification (non-ZK)</h3> <blockquote> <p>📝 <strong>Note:</strong> This section is non-normative.</p> <p>Non-ZK signature verification is not part of this proposal but relevant for an intuitive understanding of the ZK signature verification.</p> </blockquote> <p>In a situation where the verifier knows $g$, $m$, the signer's public key $pk$, and the signature $(z, s, g^r, c, \mathsf{nul})$, they may perform the following checks to determine if the signature is valid:</p> <ol> <li>Compute $h = \mathsf{htc}([m, \mathsf{sec1}(pk)])$.</li> <li>Compute $c' = \mathsf{sha256}([g, pk, h, \mathsf{nul}, g^r, z])$.</li> <li>Reject if any of the following is false: a. $g^{s} \cdot pk^{-c} \stackrel{?}{=} g^r$ b. $h^s \cdot \mathsf{nul}^{-c} \stackrel{?}{=} z$ c. $c \stackrel{?}{=} c'$</li> <li>Accept if all of the above is true.</li> </ol> <p>Now we move onto the ZK signature verification specs.</p> <h3 id="version-1-verifier-optimized">Version 1: Verifier Optimized</h3> <p>In a situation where there is a verifier who must <em>not</em> know the signer's $pk$, but the signer must nevertheless prove that they know $sk$ corresponding to the signature given $m$, a zero-knowledge proof is required.</p> <p>The following verification function may be described via a circuit as part of a non-interactive zero-knowledge proving system, such as Groth16. To create a proof, the prover supplies the following inputs:</p> <p><strong>Public</strong>: $\mathsf{nul}$, $c$ <strong>Private</strong>: $pk$, $r$, $s$, $z$, $g^r$, $hash[m, g^sk]$ (included to save constraints)</p> <p>The circuit performs the following computations:</p> <ol> <li>Compute $h = \mathsf{htc}([m, \mathsf{sec1}(pk)])$.</li> <li>Compute $pk = g^{sk}$.</li> <li>Compute $c' = \mathsf{sha256}([g, pk, h, \mathsf{nul}, g^r, z]])$.</li> <li>Compute $g^{s} \cdot pk^{-c}$.</li> <li>Compute $g^r$.</li> <li>Compute $h^s \cdot \mathsf{nul}^{-c}$.</li> </ol> <p>It also establishes the following constraints:</p> <ul> <li>$g^{s} \cdot pk^{-c} = g^r$</li> <li>$h^s \cdot \mathsf{nul}^{-c} = z$</li> <li>$c = c'$</li> </ul> <h3 id="version-2-prover-optimized">Version 2: Prover Optimized</h3> <p>Currently, SHA-256 hashing operations are particularly expensive with zk proofs in the browser. In the context of PLUME, the computation of $c$ is a bottleneck for efficient proof times, so one modification suggested by the Poseidon team was to move this hash computation outside the circuit, into the verifier.</p> <p>To do this, we make $z$ and $g^r$ public signals in the circuit and update the definition of $c$ to $c = \text{sha256}([\text{nul}, g^r, z])$. The updated protocol is as follows.</p> <p><strong>Public:</strong> $\mathsf{nul}$, $c$, $g^r$, $z$ <strong>Private:</strong> $pk$, $r$, $s$, $hash[m, g^sk]$</p> <p>The circuit performs the following computations:</p> <ol> <li>Compute $h = \mathsf{htc}([m, \mathsf{sec1}(pk)])$.</li> <li>Compute $pk = g^{sk}$.</li> <li>Compute $g^{s} \cdot pk^{-c}$.</li> <li>Compute $g^r$.</li> <li>Compute $h^s \cdot \mathsf{nul}^{-c}$.</li> </ol> <p>The circuit establishes the following constraints:</p> <ul> <li>$g^{s} \cdot pk^{-c} = g^r$</li> <li>$h^s \cdot \mathsf{nul}^{-c} = z$</li> </ul> <p>In addition to verifying the zk-SNARK, the PLUME verifier performs the following check.</p> <p>$c == \text{hash}(\text{nul}, g^r, h^r)$</p> <p>Due to SHA-256 being a native precompile on Ethereum, this operation will still be efficient for smart contract verifiers.</p> <h3 id="version-3">Version 3:</h3> <p>There may be a more efficient V3 in the future, perhaps via removing indifferentiability from hash_to_curve.</p> <h2 id="rationale">Rationale</h2> <p>We will define a few specific properties we are looking for in a candidate algorithm, then define a few other intuitive algorithms and explain why they don’t actually work.</p> <ul> <li>Noninteractivity <ul> <li>The importance of noninteractivity in ZK ID systems is that it enables a large anonymity set from the start, making it resistant to sybil attacks and spam, which would be possible if there was an interactive phase. This allows for new use cases such as ZK airdrops.</li> <li>Noninteractivity enables the full set of eligible users to be part of the anonymity set, without requiring any interaction. This is possible if the zk proof can verify the set membership in the Merkle tree, the message via the signature, and the unique nullifier. Interactive nullifiers, such as tornado.cash's, require updating the anonymity set Merkle tree with each new user,</li> </ul> </li> <li>Uniqueness <ul> <li>If we want to forbid actions like double spending or double claiming, we need them to be verifiably unique per account.</li> <li>For example: Because ECDSA signatures are nondeterministic, signatures don’t suffice; we need a new deterministic function, verifiable with only the public key. We want the nullifier to be non-interactive, to uniquely identify the keypair yet keep the account identity secret.</li> <li>The key insight is that such nullifiers can be used as a public commitment to a specific anonymous account to provide us with a uniqueness guarantee.</li> </ul> </li> <li>Deterministic <ul> <li>We want each account to only generate one such signature, and generate it exactly the same over time into the future.</li> </ul> </li> <li>Verifiable without a secret key <ul> <li>In cases where signatures are nondeterministic (like ECDSA) the signature alone is not sufficient for verification.</li> <li>We want a new, deterministic function verifiable only with the public key</li> <li>We don’t want users copy-pasting secret keys anywhere, and we need to choose a function such that the enclave calculation is simple enough for hardware wallets.</li> <li>Because the nullifier is non-interactive, we are able to uniquely identify the key pair without revealing the account identity.</li> </ul> </li> </ul> <p>We based the final design to be as simple as possible, and based off of BLS signatures, Chaum-Pederson EQDL, and Goh-Jarecki’s EDL paper, but to work on secp256k1.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are formal proofs of this specific algorithm’s cryptography in the PLUME paper <sup class="footnote-reference" id="fr-2-1"><a href="#fn-2">2</a></sup>. The theory has been published, and implementations have had one internal round of audit, but they have not end-to-end been formally verified or audited yet, although empirically they correctly conform to the spec laid out.</p> <p>Note that in the far future, once quantum computers can break ECDSA keypair security, most Ethereum keypairs will be broken, but migration to a quantum-resistant keypair in advance will keep active funds safe. Specifically, people can merely sign messages committing to new quantum-resistant keypairs (or just higher-bit keypairs on similar algorithms), and the canonical chain can fork to make such keypairs valid. ZK-SNARKs become forgeable, but there is still forward-secrecy for zk proofs. In the best case, the chain should be able to continue without a hitch.</p> <p>However, if people rely on any type of deterministic nullifier like our construction, their anonymity is immediately broken: someone can merely derive the secret keys for the whole anonymity set, calculate all the nullifiers, and see which ones match. This problem will exist for any deterministic nullifier algorithm on ECDSA, since revealing the secret key reveals the only source of “randomness” that guarantees anonymity in a deterministic protocol.</p> <p>If people want to keep post-quantum secrecy of data, they have to give up at least one of our properties: the easiest one is probably non-interactivity. For example, for the zero-knowledge airdrop, each account in the anonymity set publicly signs a commitment to a new semaphore id commitment (effectively address pk publishes $hash[randomness\ |\ external\ nullifier\ |\ pk]$). Then to claim, they reveal their external nullifier and ZK prove it came from one of the semaphore ids in the anonymity set. This considerably shrinks the anonymity set to everyone who has opted in to a semaphore commitment prior to that account claiming. As a result, there probably needs to be a separate signup phase where people commit to nullifiers in order to seed the anonymity set. This interactivity requirement makes applications such as the zk airdrop or nicer tornado cash construction (in the use cases section) much harder. However, since hashes (as far as we currently know) are still hard with quantum computers, it’s unlikely that people will be able to ever de-anonymize you.</p> <p>A recent approximation of $2n^2$ qubits needed to solve discrete log via quantum annealing that failed to work on larger than $n$ = 6-bit primes shows that we are likely several decades from this becoming a reality, and the $n^2$ qubits needed to solve RSA having predictions 10-40 years out suggest that it will likely take longer than that to solve discrete log.</p> <p>We hope that people will choose the appropriate algorithm for their chosen point on the interactivity-quantum secrecy tradeoff for their application, and hope that including this information helps folks make the right choice for themselves. Folks prioritizing shorter-term secrecy, like DAO voting or confessions of the young who will likely no longer care when they’re old, might prioritize this document’s nullifier construction, but whistleblowers or journalists might want to consider the semaphore construction instead.</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>Chaum, D., &amp; Pedersen, T. P. (1993). Wallet Databases with Observers. In E. F. Brickell (Ed.), <span style="font-style: italic;">Advances in Cryptology — CRYPTO' 92</span>. https://doi.org/<a href="https://doi.org/10.1007/3-540-48071-4_7">10.1007/3-540-48071-4_7</a>1. Pick a random $r$ from $F_p$. <a href="#fr-1-1">↩</a></p> </li> <li id="fn-2"> <p>Gupta, A., &amp; Gurkan, K. (2022). <span style="font-style: italic;">PLUME: An ECDSA Nullifier Scheme for Unique Pseudonymity within Zero Knowledge Proofs</span>. https://doi.org/<a href="https://doi.org/1721.1/147434">1721.1/147434</a><strong>The Interactivity-Quantum Secrecy Tradeoff</strong> <a href="#fr-2-1">↩</a></p> </li> </ol> </section> 2023-09-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Shu Donghttps://github.com/dongshu2013shu@hexlink.io Yudao Yandean@dauth.network Song Zs@misfit.id Kai Chenkai@dauth.network https://wg-eips.ritovision.com/7522/

A ERC-4337 compatible OIDC ZK Verifier

<h2 id="abstract">Abstract</h2> <p>Account Abstraction facilitates new use cases for smart accounts, empowering users with the ability to tailor authentication and recovery mechanisms to their specific needs. To unlock the potential for more convenient verification methods such as social login, we inevitably need to connect smart accounts and OpenID Connect(OIDC), given its status as the most widely accepted authentication protocol. In this EIP, we proposed a <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> compatible OIDC ZK verifier. Users can link their ERC-4337 accounts with OIDC identities and authorize an OIDC verifier to validate user operations by verifying the linked OIDC identity on-chain.</p> <h2 id="motivation">Motivation</h2> <p>Connecting OIDC identity and smart accounts has been a very interesting but challenging problem. Verifying an OIDC issued IdToken is simple. IdToken are usually in the form of JWT and for common JWTs, they usually consist of three parts, a header section, a claim section and a signature section. The user claimed identity shall be included in the claim section and the signature section is usually an RSA signature of a well-known public key from the issuer against the hash of the combination of the header and claim section.</p> <p>The most common way of tackling the issue is by utilizing Multi-Party Computation(MPC). However, the limitation of the MPC solution is obvious. First, it relies on a third-party service to sign and aggregate the signature which introduces centralization risk such as single point of failure and vendor lock-in. Second, it leads to privacy concerns, since the separation between the users' Web2 identity to their Web3 address can not be cryptographically guaranteed.</p> <p>All these problems could be solved by ZK verification. Privacy will be guaranteed as the connection between Web2 identity and the Web3 account will be hidden. The ZK proof generation process is completely decentralized since it can be done on the client side without involving any third-party service. ZK proofs aggregation has also proven to be viable and paves the way for cheaper verification cost at scale.</p> <p>In this EIP, we propose a new model to apply OIDC ZK verification to ERC-4337 account validation. We also define a minimal set of functions of the verifier as well as the input of the ZK proof to unify the interface for different ZK implementations. Now one can link its ERC-4337 account with an OIDC identity and use the OpenID ZK verifier to validate user operations. Due to the high cost of ZK verification, one common use case is to use the verifier as the guardian to recover the account owner if the owner key is lost or stolen. One may set multiple OIDC identities(e.g. Google Account, Facebook Account) as guardians to minimize the centralization risk introduced by the identity provider.</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="definitions">Definitions</h3> <p><strong>Identity Provider(IDP)</strong>: The service to authenticate users and provide signed ID token</p> <p><strong>User</strong>: The client to authenticate users and generate the ZK proof</p> <p><strong>ZK Aggregrator</strong>: The offchain service to aggregate ZK proof from multiple users</p> <p><strong>OpenIdZkVerifier</strong>: The on-chain contract to verify the ZK proof</p> <p>The <strong>EntryPoint</strong>, <strong>Aggregator</strong> and <strong>AA Account</strong> are defined at ERC-4337.</p> <h3 id="example-flow">Example Flow</h3> <p><img src="https://wg-eips.ritovision.com/7522/./assets/workflow.png" alt="The example workflow" /></p> <h3 id="interface">Interface</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>struct OpenIdZkProofPublicInput {</span></span> <span class="giallo-l"><span> bytes32 jwtHeaderAndPayloadHash;</span></span> <span class="giallo-l"><span> bytes32 userIdHash;</span></span> <span class="giallo-l"><span> uint256 expirationTimestamp;</span></span> <span class="giallo-l"><span> bytes jwtSignature;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>interface IOpenIdZkVerifier {</span></span> <span class="giallo-l"><span> // @notice get verification key of the open id authenticator</span></span> <span class="giallo-l"><span> function getVerificationKeyOfIdp() external view returns(bytes memory);</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> // @notice get id hash of account</span></span> <span class="giallo-l"><span> function getIdHash(address account) external view returns(bytes32);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // @notice the function verifies the proof and given a user op</span></span> <span class="giallo-l"><span> // @params op: the user operation defined by ERC-4337</span></span> <span class="giallo-l"><span> // input: the zk proof input with JWT info to prove</span></span> <span class="giallo-l"><span> // proof: the generated ZK proof for input and op</span></span> <span class="giallo-l"><span> function verify(</span></span> <span class="giallo-l"><span> UserOp memory op,</span></span> <span class="giallo-l"><span> OpenIdZkProofPublicInput input,</span></span> <span class="giallo-l"><span> bytes memory proof</span></span> <span class="giallo-l"><span> ) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // @notice the function verifies the aggregated proof give a list of user ops</span></span> <span class="giallo-l"><span> // @params ops: a list of user operations defined by ERC-4337</span></span> <span class="giallo-l"><span> // inputs: a list of zk proof input with JWT info to prove</span></span> <span class="giallo-l"><span> // aggregatedProof: the aggregated ZK proof for inputs and ops</span></span> <span class="giallo-l"><span> function verifyAggregated(</span></span> <span class="giallo-l"><span> UserOp[] memory ops,</span></span> <span class="giallo-l"><span> OpenIdZkProofPublicInput[] memory inputs,</span></span> <span class="giallo-l"><span> bytes memory aggregatedProof</span></span> <span class="giallo-l"><span> ) external;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>To verify identity ownership on-chain, <strong>IOpenIdVerifier</strong> needs at least three pieces of information:</p> <ol> <li> <p>the user ID to identify the user in the IDP. The <strong>getIdHash</strong> function returns the hash of the user id given smart account address. There may be multiple smart accounts linked to the same user ID.</p> </li> <li> <p>the public key of the key pair used by identity provider to sign ID token. It is provided by the <strong>getVerificationKeyOfIdp</strong> function.</p> </li> <li> <p>the ZK proof to verify the OIDC identity. The verification is done by the <strong>verify</strong> function. Besides the proof, the function takes two extra params: the user operation to execute and the public input to prove. The <strong>verifyAggregated</strong> is similar to the <strong>verify</strong> function but with a list of input and ops as parameters</p> </li> </ol> <p>The <strong>OpenIdZkProofPublicInput</strong> struct must contain the following fields:</p> <table><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody> <tr><td>jwtHeaderAndPayloadHash</td><td>the hash of the JWT header plus payload</td></tr> <tr><td>userIdHash</td><td>the hash of the user id, the user id should present as value of one claim</td></tr> <tr><td>expirationTimestamp</td><td>the expiration time of the JWT, which could be value of "exp" claim</td></tr> <tr><td>jwtSignature</td><td>the signature of the JWT</td></tr> </tbody></table> <p>We didn't include the verification key and the user operation hash in the struct because we assume the public key could be provided by <strong>getVerificationKeyOfIdp</strong> function and the user operation hash could be calculated from the raw user operation passed in.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The proof must verify the <em>expirationTimestamp</em> to prevent replay attacks. <strong>expirationTimestamp</strong> should be incremental and could be the <strong>exp</strong> field in JWT payload. The proof must verify the user operation to prevent front running attacks. The proof must verify the <strong>userIdHash</strong>. The verifier must verify that the sender from each user operation is linked to the user ID hash via the <strong>getIdHash</strong> function.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via CC0.</p> 2023-09-19T00:00:00+00:00 2026-02-11T14:48:25+00:00 Stephen Monnhttps://github.com/pixelcircuits Bikem Bengisuhttps://github.com/supiket https://wg-eips.ritovision.com/7521/

A generalized intent specification for smart contract wallets, allowing authorization of current and future intent structures at sign time

<h2 id="abstract">Abstract</h2> <p>A generalized intent specification entry point contract which enables support for a multitude of intent standards as they evolve over time. Instead of smart contract wallets having to constantly upgrade to provide support for new intent standards as they pop up, a single entry point contract is trusted to handle signature verification which then passes off the low level intent data handling and defining to other contracts specified by users at intent sign time. These signed messages, called a <code>UserIntent</code>, are gossipped around any host of mempool strategies for MEV searchers to look through and combine with their own <code>UserIntent</code> into an object called an <code>IntentSolution</code>. MEV searchers then package up an <code>IntentSolution</code> object they build into a transaction making a <code>handleIntents</code> call to the special contract entry point contract. This transaction then goes through the typical MEV channels to eventually be included in a block.</p> <h2 id="motivation">Motivation</h2> <p>See also <a href="https://wg-eips.ritovision.com/4337/">"ERC-4337: Account Abstraction via Entry Point Contract specification"</a> and the links therein for historical work and motivation.</p> <p>This proposal uses the same entry point contract idea to enable a single interface which smart contract wallets can support now to unlock future-proof access to an evolving intent landscape. It seeks to achieve the following goals:</p> <ul> <li><strong>Achieve the key goal of enabling intents for users</strong>: allow users to use smart contract wallets containing arbitrary verification logic to specify intent execution as described and handled by various other intent standard contracts.</li> <li><strong>Decentralization</strong> <ul> <li>Allow any MEV searcher to participate in the process of solving signed intents</li> <li>Allow any developer to add their own intent standard definitions for users to opt-in to at sign time</li> </ul> </li> <li><strong>Be forward thinking for future intent standard compatibility</strong>: Define an intent standard interface that gives future intent standard defining contracts access to as much information about the current <code>handleIntents</code> execution context as possible.</li> <li><strong>Keep gas costs down to a minimum</strong>: Include key intent handling logic, like intent segment execution order, into the entry point contract itself in order to optimize gas efficiency for the most common use cases.</li> <li><strong>Enable good user experience</strong> <ul> <li>Avoid the need for smart contract wallet upgrades when a user wants to use a newly developed intent standard.</li> <li>Enable complex intent composition that only needs a single signature.</li> </ul> </li> </ul> <h2 id="specification">Specification</h2> <p>Users package up intents they want their wallet to participate in, in an ABI-encoded struct called a <code>UserIntent</code>:</p> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td><code>sender</code></td><td><code>address</code></td><td>The wallet making the intent</td></tr> <tr><td><code>segments</code></td><td><code>bytes[]</code></td><td>Data defined by multiple segments of varying intent standards</td></tr> <tr><td><code>signature</code></td><td><code>bytes</code></td><td>Data passed into the wallet during the verification step</td></tr> </tbody></table> <p>The <code>segments</code> parameter is an array of arbitrary bytes whose use is defined by an intent standard. Each item in this array is referred to as an <strong>intent segment</strong>. The first 32 bytes of each segment is used to specify the <strong>intent standard ID</strong> to which the segment data belongs. Users send <code>UserIntent</code> objects to any mempool strategy that works best for the intent standards being used. A specialized class of MEV searchers called <strong>solvers</strong> look for these intents and ways that they can be combined with other intents (including their own) to create an ABI-encoded struct called an <code>IntentSolution</code>:</p> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td><code>timestamp</code></td><td><code>uint256</code></td><td>The time at which intents should be evaluated</td></tr> <tr><td><code>intents</code></td><td><code>UserIntent[]</code></td><td>List of intents to execute</td></tr> <tr><td><code>order</code></td><td><code>uint256[]</code></td><td>Order of execution for the included intents</td></tr> </tbody></table> <p>The solver then creates a <strong>solution transaction</strong>, which packages up an <code>IntentSolution</code> object into a single <code>handleIntents</code> call to a pre-published global <strong>entry point contract</strong>.</p> <p>The core interface of the entry point contract 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"> handleIntents</span></span> <span class="giallo-l"><span> (</span><span class="z-entity z-name">IntentSolution</span><span class="z-storage z-type"> calldata</span><span class="z-entity z-name"> solution</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-storage z-type">function</span><span class="z-entity z-name"> validateIntent</span></span> <span class="giallo-l"><span> (</span><span class="z-entity z-name">UserIntent</span><span class="z-storage z-type"> calldata</span><span class="z-entity z-name"> intent</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-storage z-type">function</span><span class="z-entity z-name"> registerIntentStandard</span></span> <span class="giallo-l"><span> (</span><span class="z-entity z-name">IIntentStandard</span><span class="z-entity z-name"> intentStandard</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">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"> verifyExecutingIntentSegmentForStandard</span></span> <span class="giallo-l"><span> (</span><span class="z-entity z-name">IIntentStandard</span><span class="z-entity z-name"> intentStandard</span><span>)</span></span> <span class="giallo-l"><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> <p>The core interface required for an intent standard to have is:</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"> validateIntentSegment</span></span> <span class="giallo-l"><span> (</span><span class="z-entity z-name">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-entity z-name"> segmentData</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>;</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"> executeIntentSegment</span></span> <span class="giallo-l"><span> (</span><span class="z-entity z-name">IntentSolution</span><span class="z-storage z-type"> calldata</span><span class="z-entity z-name"> solution</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> executionIndex</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> segmentIndex</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"> context</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">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre> <p>The core interface required for a wallet to have is:</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"> validateUserIntent</span></span> <span class="giallo-l"><span> (</span><span class="z-entity z-name">UserIntent</span><span class="z-storage z-type"> calldata</span><span class="z-entity z-name"> intent</span><span>,</span><span class="z-entity z-name"> bytes32</span><span class="z-entity z-name"> intentHash</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-storage z-type">function</span><span class="z-entity z-name"> generalizedIntentDelegateCall</span></span> <span class="giallo-l"><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> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span></code></pre><h3 id="required-entry-point-contract-functionality">Required entry point contract functionality</h3> <p>The entry point's <code>handleIntents</code> function must perform the following steps. It must make two loops, the <strong>verification loop</strong> and the <strong>execution loop</strong>.</p> <p>In the verification loop, the <code>handleIntents</code> call must perform the following steps for each <code>UserIntent</code>:</p> <ul> <li><strong>Validate <code>timestamp</code> value on the <code>IntentSolution</code></strong> by making sure it is within an acceptable range of <code>block.timestamp</code> or some time before it.</li> <li><strong>Call <code>validateUserIntent</code> on the wallet</strong>, passing in the <code>UserIntent</code> and the hash of the intent. The wallet should verify the intent's signature. If any <code>validateUserIntent</code> call fails, <code>handleIntents</code> must skip execution of at least that intent, and may revert entirely.</li> </ul> <p>In the execution loop, the <code>handleIntents</code> call must perform the following steps for all <strong>segments</strong> on the <code>segments</code> bytes array parameter on each <code>UserIntent</code>:</p> <ul> <li><strong>Call <code>executeIntentSegment</code> on the intent standard</strong>, specified by the first 32 bytes of the <code>segments</code> (the intent standard ID). This call passes in the entire <code>IntentSolution</code> as well as the current <code>executionIndex</code> (the number of times this function has already been called for any standard or intent before this), <code>segmentIndex</code> (index in the <code>segments</code> array to execute for) and <code>context</code> data. The <code>executeIntentSegment</code> function returns arbitrary bytes per intent which must be remembered and passed into the next <code>executeIntentSegment</code> call for the same intent.</li> </ul> <p>It's up to the intent standard to choose how to parse the <code>segments</code> bytes and utilize the <code>context</code> data blob that persists across intent execution.</p> <p>The order of execution for <code>UserIntent</code> segments in the <code>segments</code> array always follows the same order defined on the <code>segments</code> parameter. However, the order of execution for segments between <code>UserIntent</code> objects can be specified by the <code>order</code> parameter of the <code>IntentSolution</code> object. For example, an <code>order</code> array of <code>[1,1,0,1]</code> would result in the second intent being executed twice (segments 1 and 2 on intent 2), then the first intent would be executed (segment 1 on intent 1), followed by the second intent being executed a third time (segment 3 on intent 2). If no ordering is specified in the solution, or all segments have not been processed for all intents after getting to the end of the order array, a default ordering will be used. This default ordering loops from the first intent to the last as many times as necessary until all intents have had all their segments executed. If the ordering calls for an intent to be executed after it's already been executed for all its segments, then the <code>executeIntentSegment</code> call is simply skipped and execution across all intents continues.</p> <p>Before accepting a <code>UserIntent</code>, solvers must use an RPC method to locally call the <code>validateIntent</code> function of the entry point, which verifies that the signature and data formatting is correct; see the <a href="https://wg-eips.ritovision.com/7521/#solver-intent-validation">Intent validation section below</a> for details.</p> <h4 id="registering-new-entry-point-intent-standards">Registering new entry point intent standards</h4> <p>The entry point's <code>registerIntentStandard</code> function must allow for permissionless registration of new intent standard contracts. During the registration process, the entry point gives it a <strong>standard ID</strong> which is unique to the intent standard contract, entry point contract and chain ID.</p> <h3 id="intent-standard-behavior-executing-an-intent">Intent standard behavior executing an intent</h3> <p>The intent standard's <code>executeIntentSegment</code> function is given access to a wide set of data, including the entire <code>IntentSolution</code> in order to allow it to implement any kind of logic that may be seen as useful in the future. Each intent standard contract is expected to parse the <code>UserIntent</code> objects <code>segments</code> parameter and use that to validate any constraints or perform any actions relevant to the standard. Intent standards can also take advantage of the <code>context</code> data it can return at the end of the <code>executeIntentSegment</code> function. This data is kept by the entry point and passed in as a parameter to the <code>executeIntentSegment</code> function the next time it is called for an intent. This gives intent standards access to a persistent data store as other intents are executed in between others. One use case for this is an intent standard that is looking for a change in state during intent execution (like releasing tokens and expecting to be given other tokens).</p> <h3 id="smart-contract-wallet-behavior-executing-an-intent">Smart contract wallet behavior executing an intent</h3> <p>The entry point does not expect anything from the smart contract wallets after validation and during intent execution. However, intent standards may wish for the smart contract wallet to perform some action during execution. The smart contract wallet <code>generalizedIntentDelegateCall</code> function must perform a delegate call with the given calldata at the calling intent standard. In order for the wallet to trust making the delegate call it must call the <code>verifyExecutingIntentSegmentForStandard</code> function on the entry point contract to verify both of the following:</p> <ul> <li>The <code>msg.sender</code> for <code>generalizedIntentDelegateCall</code> on the wallet is the intent standard contract that the entry point is currently calling <code>executeIntentSegment</code> on.</li> <li>The smart contract wallet is the <code>sender</code> on the <code>UserIntent</code> that the entry point is currently calling <code>executeIntentSegment</code> for.</li> </ul> <h3 id="smart-contract-wallet-behavior-validating-an-intent">Smart contract wallet behavior validating an intent</h3> <p>The entry point calls <code>validateUserIntent</code> for each intent on the smart contract wallet specified in the <code>sender</code> field of each <code>UserIntent</code>. This function provides the entire <code>UserIntent</code> object as well as the precomputed hash of the intent. The smart contract wallet is then expected to analyze this data to ensure it was actually sent from the specified <code>sender</code>. If the intent is not valid, the smart contract wallet should throw an error in the <code>validateUserIntent</code> function. It should be noted that although <code>validateUserIntent</code> is not restricted as <code>view</code>, updates to state for things like nonce management, should be done in an individual segment on the intent itself. This allows for maximum customization in the way users define their intents while enshrining only the minimum verification within the entry point needed to ensure intents cannot be forged.</p> <h3 id="solver-intent-validation">Solver intent validation</h3> <p>To validate a <code>UserIntent</code>, the solver makes a view call to <code>validateIntent</code> on the entry point. This function checks that the signature passes validation and that the segments on the intent are properly formatted. If the call reverts with any error, the solver should reject the <code>UserIntent</code>.</p> <h3 id="simulation">Simulation</h3> <p>Solvers are expected to handle simulation in typical MEV workflows. This most likely means dry running their solutions at the current block height to determine the outcome is as expected. Successful solutions can then be submitted as a bundle to block builders to be included in the next block.</p> <h3 id="extensions">Extensions</h3> <p>The entry point contract may enable additional functionality to reduce gas costs for common scenarios.</p> <h4 id="extension-embedded-intent-standards">Extension: embedded intent standards</h4> <p>We extend the entry point logic to include the logic of several identified <strong>common intent standards</strong>. These standards are registered with their own standard ID at entry point contract creation time. The functions <code>validateUserIntent</code> and <code>executeIntentSegment</code> for these standards are included as part of the entry point contracts code in order to reduce external calls and save gas.</p> <h4 id="extension-handle-multi">Extension: handle multi</h4> <p>We add the additional function <code>handleIntentsMulti(IntentSolution[] calldata solutions)</code> to the entry point contract. This allows multiple solutions to be executed in a single transaction to enable gas saving in intents that touch similar areas of storage.</p> <h4 id="extension-nonce-management">Extension: nonce management</h4> <p>We add the functions <code>getNonce(address sender, uint256 key)</code> and <code>setNonce(uint256 key, uint256 nonce)</code> to the entry point contract. These functions allow nonce data to be stored in the entry point contracts storage. Nonces are stored at a per sender level and are available to be read by anyone. However, the entry point contract enforces that nonces can only be set for a user by a currently executing intent standard and only for the <code>sender</code> on the intent currently being executed.</p> <h4 id="extension-data-blobs">Extension: data blobs</h4> <p>We enable the entry point contract to skip the validation of <code>UserIntent</code> objects with either a <code>sender</code> field of <code>address(0)</code> or an empty <code>segments</code> field (rather than fail validation). Similarly, they are skipped during execution. The <code>segments</code> field or <code>sender</code> field is then free to be treated as a way to inject any arbitrary data into intent execution. This data could be useful in solving an intent that has an intent standard which requires some secret to be known and proven to it, or an intent whose behavior can change according to what other intents are around it. For example, an intent standard that signals a smart contract wallet to transfer some tokens to the sender of the intent that is next in line for the execution process.</p> <h2 id="rationale">Rationale</h2> <p>The main challenge with a generalized intent standard is being able to adapt to the evolving world of intents. Users need to have a way to express their intents in a seamless way without having to make constant updates to their smart contract wallets.</p> <p>In this proposal, we expect wallets to have a <code>validateUserIntent</code> function that takes as input a <code>UserIntent</code>, and verifies the signature. A trusted entry point contract uses this function to validate the signature and forwards the intent handling logic to the intent standard contracts specified in the first 32 bytes of each segment in the <code>segments</code> array field on the <code>UserIntent</code>. The wallet is then expected to have a <code>generalizedIntentDelegateCall</code> function that allows it to perform intent related actions from the intent standard contracts, using the <code>verifyExecutingIntentSegmentForStandard</code> function on the entry point for security.</p> <p>The entry point based approach allows for a clean separation between verification and intent execution, and prevents wallets from having to constantly update to support the latest intent standard composition that a user wants to use. The alternative would involve developers of new intent standards having to convince wallet software developers to support their new intent standards. This proposal moves the core definition of an intent into the hands of users at signing time.</p> <h3 id="solvers">Solvers</h3> <p>Solvers facilitate the fulfillment of a user's intent in search of their own MEV. They also act as the transaction originator for executing intents on-chain, including having to front any gas fees, removing that burden from the typical user.</p> <p>Solvers will rely on gossiping networks and solution algorithms that are to be determined by the nature of the intents themselves and the individual intent standards being used.</p> <h3 id="entry-point-upgrading">Entry point upgrading</h3> <p>Wallets are encouraged to be DELEGATECALL forwarding contracts for gas efficiency and to allow wallet upgradability. The wallet code is expected to hard-code the entry point into their code for gas efficiency. If a new entry point is introduced, whether to add new functionality, improve gas efficiency, or fix a critical security bug, users can self-call to replace their wallet's code address with a new code address containing code that points to a new entry point. During an upgrade process, it's expected that intent standard contracts will also have to be re-registered to the new entry point.</p> <p>Another option would be for wallets to not hard-code the entry point and instead validate signatures from any entry point. When a signature is validated, the wallet can note the entry point in transient storage and then use that to ensure security when accepting <code>generalizedIntentDelegateCall</code> function calls. There is an example of this in the <a href="https://wg-eips.ritovision.com/7521/#reference-implementation">reference implementation</a>.</p> <h4 id="intent-standard-upgrading">Intent standard upgrading</h4> <p>Because intent standards are not hardcoded into the wallet, users do not need to perform any operation to use any newly registered intent standards. A user can simply sign an intent with the new intent standard.</p> <h3 id="signature-aggregation">Signature aggregation</h3> <p>Signature aggregation should be handled by the smart contract wallets directly during the signature validation process. This removes complexity from the entry point and allows developers to be creative with solutions. The <a href="https://wg-eips.ritovision.com/7521/#reference-implementation">reference implementation</a> includes an example for how to accomplish this through the use of a wallet trusted aggregation contract which uses transient storage to report back to individual wallets that an intent was already validated via an aggregated signature earlier in the transaction call stack.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC does not change the consensus layer, so there are no backwards compatibility issues for Ethereum as a whole. There is a little more difficulty when trying to integrate with existing smart contract wallets. If the wallet already has support for <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a>, then implementing a <code>validateUserIntent</code> function should be very similar to the <code>validateUserOp</code> function, but would require an upgrade by the user.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <code>https://github.com/essential-contributions/ERC7521</code></p> <h2 id="security-considerations">Security Considerations</h2> <p>The entry point contract will need to be very heavily audited and formally verified, because it will serve as a central trust point for <em>all</em> <a href="https://wg-eips.ritovision.com/7521/">ERC-7521</a> supporting wallets. In total, this architecture reduces auditing and formal verification load for the ecosystem, because the amount of work that individual <em>wallets</em> have to do becomes much smaller (they need only verify the <code>validateUserIntent</code> function and its "check signature" logic) and gate any calls to <code>generalizedIntentDelegateCall</code> by checking with the entry point using the <code>verifyExecutingIntentSegmentForStandard</code> function. The concentrated security risk in the entry point contract, however, needs to be verified to be very robust since it is so highly concentrated.</p> <p>Verification would need to cover one primary claim (not including claims needed to protect solvers, and intent standard related infrastructure):</p> <ul> <li><strong>Safety against arbitrary hijacking</strong>: The entry point only returns true for <code>verifyExecutingIntentSegmentForStandard</code> when it has successfully validated the signature of the <code>UserIntent</code> and is currently in the middle of calling <code>executeIntentSegment</code> on the <code>standard</code> specified in the <code>segments</code> field of a <code>UserIntent</code> which also has the same <code>sender</code> as the <code>msg.sender</code> wallet calling the function.</li> </ul> <p>Additional heavy auditing and formal verification will also need to be done for any intent standard contracts a user decides to interact with.</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-19T00:00:00+00:00 2026-02-11T14:49:27+00:00 Peter Davieshttps://github.com/petertdavies https://wg-eips.ritovision.com/7523/

Prohibit empty accounts on post-merge networks

<h2 id="abstract">Abstract</h2> <p>This EIP prohibits the state of any post-merge network from containing empty accounts. Since no empty accounts exist outside the testsuite and no new ones can be created this requirement is already achieved in practice. An explicit ban reduces technical debt going forward.</p> <h2 id="motivation">Motivation</h2> <p>The possibility of empty accounts is a historical artifact of the early history of Ethereum. The only networks that have ever been capable of containing them are Ethereum Mainnet, the deprecated testnet Ropsten, Etheruem Classic Mainnet and various Ethereum Classic testnets. All remaining empty accounts on Mainnet were cleared in block <code>14049881</code> (transaction <code>0xf955834bfa097458a9cf6b719705a443d32e7f43f20b9b0294098c205b4bcc3d</code>) and a similar transaction was sent on Ethereum Classic. None of the other myriad EVM-compatible networks are old enough to have empty accounts and there is no realistic prospect that anyone will encounter an empty account in a production context.</p> <p>Despite empty accounts no longer existing, they still impose a legacy of technical debt. <a href="https://wg-eips.ritovision.com/161/">EIP-161</a> imposes complicated rules that require a client to delete an empty account when it is "touched". As the Ethereum specification continues to evolve new edgecases of the "touch" rules arise which must be debated, implemented, tested and documented. If a future client wishes to only support post-merge blocks it must implement unnecessary empty account support solely to pass the test suite.</p> <p>By prohibiting empty accounts on post-merge networks, this EIP frees designers and implementers of Ethereum and related blockchains from the burden of having to consider them going forward.</p> <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>An empty account is an account with has <strong>no code</strong> and <strong>zero nonce</strong> and <strong>zero balance</strong>. This is the same as the definition in <a href="https://wg-eips.ritovision.com/161/">EIP-161</a>.</p> <p>On networks that undergo the merge transition, the pre state of the merge block may not contain any empty accounts. For networks that are merged at genesis, none of the genesis accounts may be empty accounts.</p> <p>Rather than performing a scan of the state, clients MAY assume the following chains have no post-merge empty accounts:</p> <ol> <li> <p>The Mainnet chain whose merge block has hash <code>0x56a9bb0302da44b8c0b3df540781424684c3af04d0b7a38d72842b762076a664</code>.</p> </li> <li> <p>Any chain which satisfies all of the following:</p> <ul> <li> <p>has no empty accounts in the genesis.</p> </li> <li> <p>had a post Spurious Dragon fork at genesis.</p> </li> </ul> </li> </ol> <p>The Ethereum specification is declared to be undefined in the presence of an empty account in a post-merge context. Any testcase involving post-merge empty accounts is invalid.</p> <h2 id="rationale">Rationale</h2> <p>This EIP was drafted to be the simplest possible way of eliminating the long term technical debt imposed by empty accounts. The Merge was chosen as a natural easily identifiable cutoff point.</p> <p>Alternative approaches include:</p> <ul> <li> <p>Using an earlier cutoff point, such as block <code>14049881</code>.</p> </li> <li> <p>Identifying a wider range of edge case behaviour that never happened.</p> </li> </ul> <p>These approaches were rejected as being unnecessarily complicated.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As EIP does not change any behaviour that can occur outside the testsuite, it has no backwards compatibility consequences.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The validity of this EIP is dependent on the assertion that all empty accounts on Ethereum Mainnet were cleared prior to the merge. This should be subject to appropriate verification.</p> <p>Any networks artificially created with empty accounts will cause problems with tooling and 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> 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-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Abhinavhttps://github.com/abhinav-d3vabhinav@zoniqx.com Prithvish Baidyahttps://github.com/d4mrpbaidya@zoniqx.com Rajat Kumarhttps://github.com/rajatwasanrwasan@zoniqx.com Prasanth Kalangipkalangi@zoniqx.com https://wg-eips.ritovision.com/7518/

Security token framework with semi-fungible partitions for dynamic regulatory compliance management and cross-chain interoperability

<h2 id="abstract">Abstract</h2> <p>This proposal is a security token standard that extends <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> to provide a flexible framework for managing compliant real-asset security tokens. It introduces the concept of partitions, where each <code>tokenId</code> represents a distinct partition with its own set of rights and privileges. This makes it suitable for various use cases, particularly semi-fungible asset management. The standard also includes features like token locking, forced transfers for recovery, address freezing, payouts, and dynamic compliance management using off-chain vouchers.</p> <h2 id="motivation">Motivation</h2> <p>The growing demand for tokenized real-world assets necessitates a token standard that can accommodate the unique requirements of security tokens. Existing standards, while powerful, do not fully address the need for flexible partitioning and comprehensive compliance management.</p> <p>This standard builds upon <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> by introducing partitions, allowing for the creation of semi-fungible tokens representing fractional ownership, different share classes, or other distinct units within a single token contract. This flexibility is crucial for tokenizing complex real-world assets like real estate or funds.</p> <p>Furthermore, it includes features essential for security tokens, such as token locking for vesting or holding periods, forced transfers for recovery in case of lost keys, address freezing for regulatory compliance, efficient payout mechanisms, and dynamic compliance management using off-chain vouchers.</p> <p>By providing a standardized interface for these features, this proposal aims to facilitate the development of interoperable and compliant security token ecosystems.</p> <h3 id="partition-based-architecture-benefits">Partition-Based Architecture Benefits</h3> <p>The partition paradigm offers significant flexibility and power in managing security tokens:</p> <ol> <li>Dynamic Allocation : Partitions allow for dynamic allocation of tokens between different classes or categories. For example, in a real estate tokenization scenario, an issuer can initially allocate tokens to a Reg D partition for accredited U.S. investors and a "Reg S" partition for non-U.S. investors. As the offering progresses and demand shifts, the issuer can dynamically mint tokens into the appropriate partition based on the investor's eligibility, ensuring optimal distribution and compliance.</li> <li>Temporary Non-Fungibility : Partitions enable temporary non-fungibility of tokens. In some cases, securities may need to be treated as non-fungible for a certain period, such as tokens of the same underlying asset sold at different offerings. By assigning tokens to specific partitions, issuers can enforce these restrictions and maintain the necessary segregation between them, but merge them at a later point to prevent liquidity fragmentation. Merger occurs by creating a new joint partition, a deploying a merger contract where users can deposit old partitioned tokens to receive new joint partition token.</li> <li>Granular Compliance : Each partition can have its own set of compliance rules and transfer restrictions. This allows for more granular control over token transfers based on the specific characteristics of each partition. For instance, a partition representing a particular share class may have different transfer restrictions or payout rights compared to other partitions.</li> <li>Efficient Asset Management : Partitions streamline the management of complex asset structures. Instead of deploying separate contracts for each share class or asset category, issuers can manage multiple partitions within a single proposed contract, reducing deployment costs and simplifying overall asset management.</li> </ol> <h3 id="real-world-use-cases">Real World Use Cases</h3> <p><img src="https://wg-eips.ritovision.com/7518/./assets/exampleUsecase.svg" alt="image" /></p> <h4 id="use-case-1-tokenization-of-commercial-real-estate">Use Case 1: Tokenization of Commercial Real Estate</h4> <p>In this use case, a commercial real estate property with 100 floors is being tokenized using this proposal. Each floor is represented as a unique non-fungible token (NFT) partition, allowing for fractional ownership and separate management of individual floors.</p> <ol> <li> <p>Property Representation: The entire commercial property is tokenized using the proposed contract, with each floor being assigned a unique tokenId representing an NFT partition.</p> </li> <li> <p>Fractional Ownership: Each floor's NFT partition can be divided into multiple fungible tokens, enabling fractional ownership. For instance, if a floor is divided into 100 tokens, multiple investors can own portions of that floor.</p> </li> <li> <p>Dynamic Pricing: Since each floor is a separate partition, the pricing of tokens within a partition can be adjusted dynamically based on factors such as floor level, amenities, or market demand. This flexibility allows for accurate representation of the varying values of different floors.</p> </li> <li> <p>Transfer of Ownership: The ownership of each floor's NFT partition can be transferred seamlessly to token holders using the safeTransferFrom function. This enables the seamless transfer of ownership rights for specific floors.</p> </li> <li> <p>Compliance Management: Different compliance rules and transfer restrictions can be applied to each partition (floor) based on regulatory requirements or issuer-defined rules. The canTransfer function can be used to enforce these rules before allowing transfers.</p> </li> <li> <p>Payouts: The payout and batchPayout functions can be used to distribute rental income, dividends, or other payouts to token holders of specific floor partitions efficiently.</p> </li> </ol> <p>By leveraging proposal, this use case demonstrates the ability to tokenize complex real estate assets while maintaining granular control over ownership, pricing, compliance, and payouts for individual units within the property.</p> <h4 id="use-case-2-tokenization-of-securities-with-reg-s-and-reg-d-partitions">Use Case 2: Tokenization of Securities with Reg S and Reg D Partitions</h4> <p>In this use case, a company is tokenizing its securities and wants to comply with different regulations for U.S. accredited investors (Reg D) and non-U.S. investors (Reg S).</p> <ol> <li> <p>Initial Partitions: The company deploys an proposed standard and creates two partitions: one for Reg D investors (accredited U.S. investors) and another for Reg S investors (non-U.S. investors).</p> </li> <li> <p>Dynamic Allocation: As the offering progresses, the company can dynamically mint tokens into the appropriate partition based on investor eligibility. For example, if a U.S. accredited investor wants to participate, tokens can be minted in the Reg D partition, while tokens for non-U.S. investors are minted in the Reg S partition.</p> </li> <li> <p>Compliance Management: Each partition can have its own set of compliance rules and transfer restrictions. The canTransfer function can be integrated with off-chain compliance services to verify the eligibility of a transfer based on the specific rules for each partition.</p> </li> <li> <p>Temporary Non-Fungibility: During the initial offering period, tokens in the Reg D and Reg S partitions may need to be treated as non-fungible due to different regulatory requirements. However, after the holding period, the company can create a new joint partition and allow token holders to deposit their old partitioned tokens to receive the new joint partition tokens, merging the two classes.</p> </li> <li> <p>Payouts: The payout and batchPayout functions can be used to distribute dividends, interest payments, or other payouts to token holders in each partition based on their respective rights and privileges.</p> </li> </ol> <p>By utilizing the proposal, this use case demonstrates the ability to tokenize securities while maintaining compliance with different regulatory regimes, dynamically allocating tokens based on investor eligibility, and efficiently managing payouts and potential mergers of different share classes.</p> <h4 id="use-case-3-force-transfer-for-aml-kyc-compliance-violations">Use Case 3: Force Transfer for AML/KYC/Compliance Violations</h4> <p>In the world of tokenized securities, maintaining compliance with regulatory requirements is of utmost importance. This proposal provides a robust mechanism to handle situations where an investor's tokens need to be forcibly transferred due to violations of Anti-Money Laundering (AML), Know Your Customer (KYC), or other compliance-related regulations.</p> <p>Let's consider the scenario of Alice, an investor who holds tokens in the proposed token compliant security token contract. During the regular compliance checks conducted by the token issuer or a designated compliance service, it is discovered that Alice's wallet address is associated with suspicious activities related to money laundering or other financial crimes.</p> <p>In such a situation, the regulatory authorities or the contract administrators may decide to freeze Alice's account and initiate a forced transfer of her tokens to a designated address controlled by the issuer or a recovery agent. The <code>forceTransfer</code> function in this proposal enables this process.</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="interface">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"> ^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"> IERC7518</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC1155</span><span>, </span><span class="z-entity z-name">IERC165</span><span>{</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokensLocked</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 class="z-support">uint</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"> amount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> releaseTime</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"> TokenUnlocked</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 class="z-support">uint</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-storage z-type"> event</span><span class="z-entity z-name"> TokensForceTransferred</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">uint</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"> amount</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"> AddressFrozen</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 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"> AddressUnfrozen</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 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"> Emitted when the transferability of tokens with a specific ID is restricted.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferRestricted</span><span>(</span><span class="z-support">uint</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 class="z-comment"> Emitted when the transferability restriction of tokens with a specific ID is removed.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferRestrictionRemoved</span><span>(</span><span class="z-support">uint</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-storage z-type"> event</span><span class="z-entity z-name"> PayoutDelivered</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"> 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">@dev</span><span class="z-comment"> Retrieves the transferable balance of tokens for the specified account and 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"> account</span><span class="z-comment"> The address 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"> id</span><span class="z-comment"> The 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"> The</span><span class="z-comment"> transferable balance of 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"> transferableBalance</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>,</span><span class="z-support"> uint</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">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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Retrieves the locked balance of tokens for the specified account and 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"> account</span><span class="z-comment"> The address 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"> id</span><span class="z-comment"> The 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"> The</span><span class="z-comment"> locked balance of 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"> lockedBalanceOf</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"> 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">@dev</span><span class="z-comment"> Restricts the transferability of tokens with the specified 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"> id</span><span class="z-comment"> The 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"> A</span><span class="z-comment"> boolean value indicating whether 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"> restrictTransfer</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> id</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"> Removes the transferability restriction of tokens with the specified 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"> id</span><span class="z-comment"> The 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"> A</span><span class="z-comment"> boolean value indicating whether 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"> removeRestriction</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> id</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">@notice</span><span class="z-comment"> Transfers `_value` amount of an `_id` from the `_from` address to the `_to` address specified (with safety call).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><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 (see &quot;Approval&quot; section of the standard).</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> * After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size &gt; 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see &quot;Safe Transfer Rules&quot; section of the standard). </span></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 token type</span></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"> 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"> _data</span><span class="z-comment"> Additional data with no specified format, MUST be sent unaltered in call to `onERC1155Received` on `_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"> safeTransferFrom</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-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"> override</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"> Checks if a transfer is allowed.</span></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 to transfer tokens from.</span></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 transfer tokens 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"> id</span><span class="z-comment"> The 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"> amount</span><span class="z-comment"> The amount of tokens 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"> data</span><span class="z-comment"> Additional data related to the transfer.</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"> A boolean value indicating whether the transfer is allowed.</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"> canTransfer</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"> uint</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> amount</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"> view</span><span class="z-keyword"> returns</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-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 token till a particular block 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"> account</span><span class="z-comment"> The address of the account for which tokens will 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"> id</span><span class="z-comment"> The 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"> amount</span><span class="z-comment"> The amount of tokens to be locked for 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"> releaseTime</span><span class="z-comment"> The timestamp indicating when the locked tokens can be released.</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"> Returns true if the tokens are successfully locked, otherwise 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"> lockTokens</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>,</span><span class="z-support"> uint</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"> releaseTime</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"> Unlocks tokens that have crossed the release time for a specific account and 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"> account</span><span class="z-comment"> The address of the account to unlock 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"> id</span><span class="z-comment"> The token 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"> unlockToken</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"> 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"> Force transfer in cases like recovery of 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"> from</span><span class="z-comment"> The address to transfer tokens from.</span></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 transfer tokens 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"> id</span><span class="z-comment"> The 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"> amount</span><span class="z-comment"> The amount of tokens 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"> data</span><span class="z-comment"> Additional data related to the transfer.</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 value indicating whether 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"> forceTransfer</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"> 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 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"> Freezes 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"> account</span><span class="z-comment"> The address to be frozen.</span></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 related to the freeze operation.</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 value indicating whether 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"> freezeAddress</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</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-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"> Unfreezes 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"> account</span><span class="z-comment"> The address to be unfrozen.</span></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 related to the unfreeze operation.</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 value indicating whether 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"> unFreeze</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</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 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"> Sends payout to single address with corresponding amounts.</span></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 to send the payouts 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"> amount</span><span class="z-comment"> amount representing the payouts to be sent.</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 indicating whether the batch payouts were successful.</span></span> <span class="giallo-l"><span class="z-comment"> */</span><span class="z-keyword">*</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> payout</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-storage z-type"> calldata</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>)</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"> Sends batch payouts to multiple addresses with corresponding amounts.</span></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 array of addresses to send the payouts 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"> amount</span><span class="z-comment"> An array of amounts representing the payouts to be sent.</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 indicating whether the batch payouts were 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"> batchPayout</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"> 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"> 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>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="methods-for-token">Methods for token</h3> <h3 id="transferablebalance"><code>transferableBalance</code></h3> <p>Retrieves the transferable balance of tokens for the specified account and 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"> transferableBalance</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>,</span><span class="z-support">uint</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">uint</span><span>)</span></span></code></pre> <ul> <li>MUST calculate and return the transferable balance of tokens for the specified account and ID (i.e. current) <code>balanceOf(account, id) - lockedBalanceOf(account, id)</code>.</li> </ul> <h3 id="lockedbalanceof"><code>lockedBalanceOf</code></h3> <p>Retrieves the locked balance of tokens for the specified account and 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"> lockedBalanceOf</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"> 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></code></pre> <ul> <li>MUST retrieve and return the locked balance of tokens for the specified <code>account</code> and <code>id</code>.</li> </ul> <h3 id="restricttransfer"><code>restrictTransfer</code></h3> <p>Restricts the transferability of tokens with the specified 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"> restrictTransfer</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> id</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></code></pre> <ul> <li>MUST restrict the transferability of tokens with the specified <code>id</code>.</li> <li>SHOULD emit <code>TransferRestricted</code>.</li> </ul> <h3 id="removerestriction"><code>removeRestriction</code></h3> <p>Removes the transferability restriction of tokens with the specified 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"> removeRestriction</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> id</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></code></pre> <ul> <li>MUST remove the transferability restriction of tokens with the specified <code>id</code>. MUST revert if <code>id</code> was not previously restricted.</li> <li>SHOULD emit <code>TransferRestrictionRemoved</code>.</li> </ul> <h3 id="safetransferfrom"><code>safeTransferFrom</code></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"> safeTransferFrom</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-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"> override</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <ul> <li>MUST revert if <code>_to</code> is the zero address.</li> <li>MUST revert if balance of holder for token <code>_id</code> is lower than the <code>_value</code> sent.</li> <li>MUST revert on any other error.</li> <li>MUST emit the <code>TransferSingle</code> event to reflect the balance change (see "Safe Transfer Rules" section of the standard).</li> <li>MUST call <code>canTransfer</code> function to check if the transfer can proceed</li> </ul> <h3 id="cantransfer"><code>canTransfer</code></h3> <p>Determine transferring a specified amount of a token from one address to another.</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"> canTransfer</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">uint</span><span class="z-variable"> id</span><span>,</span><span class="z-support">uint</span><span class="z-variable"> amount</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"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> status</span><span>)</span><span>;</span></span></code></pre> <ul> <li>Accurately determine whether the transfer of tokens is allowed.</li> <li>MUST validate <code>to</code> and <code>from</code> are not frozen address.</li> <li>MUST validate <code>id</code> of the transfer should not be restricted</li> <li>MUST check if <code>amount</code> is a transferable balance.</li> <li>MAY call external contract to verify the transfer.</li> <li>SHOULD NOT modify any state or perform any side effects.</li> </ul> <h3 id="locktokens"><code>lockTokens</code></h3> <p>Locks a specified amount of tokens from an account for a specified duration.</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"> lockTokens</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>,</span><span class="z-support">uint</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"> releaseTime</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></code></pre> <ul> <li>MUST enforce time-based restrictions on the transfer or use of tokens.</li> <li>MUST revert if balance of holder is less than amount.</li> <li>SHOULD use proper access control measures to ensure that only authorized entities can lock tokens.</li> <li>MUST perform input validation prevent potential vulnerabilities and unauthorized locking of tokens.</li> <li>SHOULD record release time securely and ensure that locked tokens are only released after the designated time has passed.</li> <li>SHOULD emit <code>TokensLocked</code>.</li> </ul> <h3 id="unlocktoken"><code>unlockToken</code></h3> <p>Unlocks tokens that have crossed the release time for a specific account and 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"> unlockToken</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"> id</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <ul> <li>MUST unlock the tokens for the specified <code>account</code> address and <code>id</code>.</li> <li>MUST unlock all the token which has release time &lt;= <code>block.timestamp</code></li> <li>SHOULD revert if no token are unlocked to save gas.</li> <li>SHOULD emit <code>TokenUnlocked</code>.</li> </ul> <h3 id="forcetransfer"><code>forceTransfer</code></h3> <p>Force transfer in cases like recovery of tokens</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"> forceTransfer</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">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></code></pre> <ul> <li>MUST bypass normal transfer restrictions and authorization checks.</li> <li>MUST revert if the <code>from</code> address is not Frozen.</li> <li>MUST revert if <code>to</code> address is Frozen.</li> <li>MUST ensure that only authorized entities have the capability to call this function.</li> <li>Additional data related to the freeze operation.</li> <li>SHOULD emit <code>TokensForceTransferred</code>.</li> </ul> <h3 id="freeze"><code>freeze</code></h3> <p>Freezes specified address. The Freeze function takes in the <code>account address</code> to be frozen and additional data, and returns a <code>boolean</code> value indicating whether the operation was 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"> freezeAddress</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>,</span><span class="z-support">bytes</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></code></pre> <ul> <li>MUST prevent <code>account</code> to transfer and payout.</li> <li>SHOULD implement appropriate access control measures to ensure that only authorized addresses can be unfrozen.</li> <li>SHOULD emit <code>AddressFrozen</code>.</li> </ul> <h3 id="unfreeze"><code>unFreeze</code></h3> <p>The Unfreeze function takes in the <code>account address</code> to be unfrozen and additional data, and returns a <code>boolean</code> value indicating whether the operation was 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"> unFreeze</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</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></code></pre> <ul> <li>MUST unfreeze the specified <code>account</code></li> <li>SHOULD implement appropriate access control measures to ensure that only authorized addresses can be unfrozen.</li> <li>SHOULD emit <code>AddressUnfrozen</code>.</li> </ul> <h3 id="payout"><code>payout</code></h3> <p>Send payouts to single address, receiver will be receiving a specific amount of tokens.</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"> payout</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> to</span><span>,</span><span class="z-support">uint256</span><span class="z-storage z-type"> calldata</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>)</span></span></code></pre> <ul> <li>MUST revert if <code>to</code> address is frozen address.</li> <li>SHOULD have sufficient balance to transfer token from issuer address.</li> <li>SHOULD emit <code>PayoutDelivered</code>.</li> </ul> <h3 id="batchpayout"><code>batchPayout</code></h3> <p>Send payouts to multiple addresses at once, with each address receiving a specific amount of tokens. It can be used for various purposes such as distributing rewards, dividends, or interest payment.</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"> batchPayout</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"> 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"> 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> <ul> <li>MUST revert if <code>to</code> address is frozen address.</li> <li>SHOULD have sufficient balance to transfer token from issuer address.</li> <li>SHOULD emit <code>PayoutDelivered</code>.</li> </ul> <h3 id="interoperability">Interoperability</h3> <p>This proposal facilitates interoperability with non-fungible and fungible tokens through a token wrapping method. The process involves two key components: the token contracts representing the original and the proposed token contract for the wrapped version. Users seeking to wrap their tokens interact with the wrapping contract, which securely locks their original tokens and mints an equivalent amount of the proposed tokens to their address. Conversely, unwrapping is achieved by calling the contract's withdraw function, resulting in the burning of the proposed tokens and the release of the corresponding original tokens. Events are emitted for transparency, and robust security measures are implemented to safeguard user assets and address any potential vulnerabilities in the contract code. With this design, this proposal ensures the seamless conversion and compatibility with fungible and non-fungible tokens, promoting greater utility and usability across the Ethereum ecosystem.</p> <h3 id="interface-for-interoperability">Interface for Interoperability</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"> IERC1155Wrapper</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7518</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"> Emitted when a new wrapped token address is added to the set.</span></span> <span class="giallo-l"><span class="z-storage z-type">@param</span><span class="z-variable z-other"> wrappedTokenAddress</span><span class="z-comment"> The address of the wrapped token that was added.</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"> WrappedTokenAddressSet</span><span>(</span><span class="z-support">address</span><span class="z-variable"> wrappedTokenAddress</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"> Emitted when tokens are wrapped.</span></span> <span class="giallo-l"><span class="z-storage z-type">@param</span><span class="z-variable z-other"> The</span><span class="z-comment"> ERC-1155 token ID of the wrapped tokens.</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"> The amount of tokens that were wrapped.</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"> TokensWrapped</span><span>(</span><span class="z-support">uint</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"> 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-storage z-type">@dev</span><span class="z-comment"> Emitted when tokens are unwrapped.</span></span> <span class="giallo-l"><span class="z-storage z-type">@param</span><span class="z-variable z-other"> wrappedTokenId</span><span class="z-comment"> Is the ERC-1155 token ID of the wrapped tokens.</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"> The amount of tokens that were unwrapped.</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"> TokensUnwrapped</span><span>(</span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> wrappedTokenId</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">@dev</span><span class="z-comment"> Sets the wrapped token address and logic for deciding partitions.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> wrappedTokenAddress</span><span class="z-comment"> The address of the wrapped token 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"> A</span><span class="z-comment"> boolean value indicating whether 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"> setWrappedToken</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-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"> Wraps the specified amount of tokens by depositing the original tokens and receiving new standard 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"> The amount of tokens to wrap.</span></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 for partition.</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 value indicating whether 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"> wrapToken</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"> 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">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"> Wraps a specified amount of tokens from a given partition into the main balance.</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 allows users to convert tokens from a specific partition back to the main balance,making them fungible with tokens from other partitions.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> partitionId</span><span class="z-comment"> The unique identifier of the partition from which tokens will be wrapped.</span></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 unique identifier of 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"> amount</span><span class="z-comment"> The amount of tokens to be wrapped from the specified partition.</span></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 that may be used to handle the wrap process (optional).</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"> A boolean indicating whether the wrapping operation was successful or not.</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"> wrapTokenFromPartition</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> partitionId</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"> 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-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> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Unwraps the specified amount of wrapped tokens by depositing the current tokens and receiving the original 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"> wrappedTokenId</span><span class="z-comment"> internal partition 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"> amount</span><span class="z-comment"> The amount of wrapped tokens to unwrap.</span></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 for partition.</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 value indicating whether 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"> unwrapToken</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> wrappedTokenId</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"> 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">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"> Retrieves the balance of wrapped tokens for the specified account and 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"> account</span><span class="z-comment"> The address 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"> id</span><span class="z-comment"> The 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"> data</span><span class="z-comment"> Additional data for partition.</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"> balance of wrapped 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"> wrappedBalanceOf</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"> id</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"> 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">@dev</span><span class="z-comment"> Retrieves the balance of original tokens for the specified account and 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"> account</span><span class="z-comment"> The address 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"> id</span><span class="z-comment"> The 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"> data</span><span class="z-comment"> Additional data for partition.</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"> balance of original 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"> originalBalanceOf</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"> id</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"> 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="methods-for-interoperability">Methods for Interoperability</h3> <h3 id="setwrappedtokenaddress"><code>setWrappedTokenAddress</code></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"> setWrappedTokenAddress</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-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre> <ul> <li><code>token</code> address could be any security token standard i.e <a href="https://wg-eips.ritovision.com/3643/">ERC-3643</a>.</li> </ul> <h3 id="wraptoken"><code>wrapToken</code></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"> wrapToken</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"> 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">bool</span><span>)</span><span>;</span></span></code></pre> <ul> <li>MUST lock token in an on-chain vault type smart contract.</li> <li>MUST mint an equivalent amount of the proposed token.</li> <li>MUST verify mapping of <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> <code>id</code> with the corresponding <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> compatible security token.</li> </ul> <h3 id="wraptokenfrompartition"><code>wrapTokenFromPartition</code></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"> wrapTokenFromPartition</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> partitionId</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"> 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-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre> <ul> <li>MUST lock the token amount from source standard and mint an equivalent amount of the proposed token.</li> <li>SHOULD lock token in smart contract to achieve one to one mapping with the investor.</li> <li>MUST verify mapping of <code>id</code> with the corresponding partially fungible security token <code>partitionId</code>.</li> </ul> <h3 id="unwraptoken"><code>unwrapToken</code></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"> unwrapToken</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> wrappedTokenId</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"> 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">bool</span><span>)</span><span>;</span></span></code></pre> <ul> <li>MUST burn the proposed token and release the original token.</li> <li>MUST verify that the token is not subject to any of the proposal's locking functionality.</li> </ul> <h3 id="partition-management">Partition Management</h3> <p>The proposal leverages the <code>tokenId</code> feature of <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> to represent distinct partitions within a token contract. Each <code>tokenId</code> corresponds to a unique partition with its own set of rights, privileges, and compliance rules. This enables the creation of semi-fungible tokens representing fractional ownership, different share classes, or other granular units.</p> <h3 id="partition-as-the-fundamental-unit">Partition as the Fundamental Unit</h3> <ul> <li>Each partition is created by minting tokens under a unique <code>tokenId</code> value.</li> <li>All tokens with the same <code>tokenId</code> are <strong>fungible within that partition</strong> but <strong>non-fungible across partitions</strong>.</li> <li>The issuer can represent different classes, jurisdictions, or series by minting tokens under different <code>tokenId</code>s.</li> </ul> <h3 id="compliance-management">Compliance Management</h3> <p><img src="https://wg-eips.ritovision.com/7518/./assets/sequentialDiagram.svg" alt="image" /></p> <p>This standard includes functions for managing token transfers in accordance with regulatory requirements and issuer-defined rules. The <code>canTransfer</code> function checks whether a transfer is allowed based on factors such as token restrictions, frozen addresses, transferable balances, and token locking.</p> <p>To facilitate dynamic compliance management, the standard uses a voucher-based pattern. An authorized entity (e.g., the issuer or a designated compliance service) generates a signed off-chain voucher that may encapsulate results from on-chain rule evaluation, oracle responses, or other checks. The <code>canTransfer</code> verifies vouchers signature, expiry, and binding of <code>from</code>, <code>to</code>, <code>id</code>, and <code>amount</code> together with contract state to determine the eligibility of a transfer.</p> <p>Here's an example of how off-chain vouchers can be used with the proposal:</p> <ol> <li>The token issuer defines a set of compliance rules and requirements for token transfers.</li> <li>When a user initiates a transfer, they submit a request to a designated compliance service with the necessary details (sender, recipient, amount, etc.).</li> <li>The compliance service evaluates the transfer request against the predefined rules and requirements, considering factors such as investor eligibility, transfer restrictions, and regulatory compliance.</li> <li>If the transfer is deemed compliant, the compliance service generates a signed voucher containing the relevant details and returns it to the user.</li> <li>The user includes the signed voucher as an additional parameter when calling the <code>safeTransferFrom</code> function on the proposed contract.</li> <li>The <code>canTransfer</code> function verifies the authenticity and validity of the voucher by checking the signature and ensuring that the voucher details match the transfer parameters.</li> <li>If the voucher is valid and the transfer meets all other requirements, the transfer is allowed to proceed.</li> </ol> <p>Implementations MAY accept a cryptographically signed compliance voucher in the <code>data</code> argument of <code>canTransfer</code>, and state changing transfer functions defined in this standard, for example <code>safeTransferFrom</code>. Voucher schema and policy content are application defined. Implementations MAY combine on chain rules, oracle responses, and off chain verification for the voucher.</p> <h3 id="token-recovery">Token Recovery</h3> <p>In case of lost or compromised wallets, the proposal includes a <code>forceTransfer</code> function that allows authorized entities (e.g., the issuer or a designated recovery agent) to transfer tokens from one address to another. This function bypasses the usual transfer restrictions and can be used as a recovery mechanism.</p> <h3 id="payout-management">Payout Management</h3> <p>Provides functions for efficient payout distribution to token holders. The <code>payout</code> function allows sending payouts to a single address, while <code>batchPayout</code> enables sending payouts to multiple addresses in a single transaction. These functions streamline the process of distributing dividends, interest, or other payments to token holders.</p> <h2 id="rationale">Rationale</h2> <h3 id="enhancing-compliance-management">Enhancing Compliance Management</h3> <p>The <code>canTransfer</code> function facilitates compliance checks during token transfers, offering adaptability through diverse implementation methods such as on-chain storage, oracle utilization, or any off-chain methodologies. This versatility ensures seamless integration with existing compliance frameworks, particularly in enforcing regulatory standards like KYC/AML. Additionally, functionalities like <code>freezeAddress</code>, <code>restrictTransfer</code>, <code>lockToken</code> and <code>forceTransfer</code> empower entities to regulate token movements based on specified conditions or regulatory requirements. Complementing these, the <code>unlockToken</code> function enhances transparency and accountability by facilitating the release of tokens post-compliance actions.</p> <h3 id="fractionalization">Fractionalization</h3> <p>Fractionalization in this standard is realized natively through <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> balances. For a given partition identified by tokenId, each unit of amount represents a fungible fraction of that partition’s underlying security. Issuers mint and burn units to manage supply. Transfers use <code>safeTransferFrom</code> and <code>safeBatchTransferFrom</code>, and must pass canTransfer. Locks and freezes reduce the transferable portion of balances, and <code>forceTransfer</code> operates proportionally on units. Partitions can be merged by issuing a new tokenId and allowing holders to deposit old partitions for one-to-one or proportional conversion, and can be split by minting new tokenIds with defined conversion rules. All compliance rules and restrictions apply identically to every fractional unit in a partition.</p> <h3 id="interoperability-with-other-standard">Interoperability with other standard</h3> <p>This standard builds directly on <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>, which already models fractional supply, batching, and balance-based accounting with broad ecosystem support. <a href="https://wg-eips.ritovision.com/3525/">ERC-3525</a> was carefully evaluated but intentionally not adopted as a base. Its slot-and-value abstraction overlaps almost exactly with the partition and <code>amount</code> semantics defined here, yet inherits <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>’s single-token overhead and per-position statefulness, which are inefficient for large scale issuance and compliance checks. Implementers who require slot-style compatibility may optionally expose <a href="https://wg-eips.ritovision.com/3525/">ERC-3525</a> through <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> by mapping <code>slot</code> to partition and <code>value</code> to <code>amount</code>. <a href="https://wg-eips.ritovision.com/6909/">ERC-6909</a>, while a minimal multi-token variant, omits partition metadata and compliance hooks and is therefore unsuitable for regulated assets. <a href="https://wg-eips.ritovision.com/7518/">ERC-7518</a> extends this lineage by representing partitions as <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> <code>tokenId</code>s, enabling dynamic minting, merging, and voucher based dynamic compliance that can evolve without redeployment. Overall, <a href="https://wg-eips.ritovision.com/7518/">ERC-7518</a> uses <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> as its canonical substrate because it balances composability, efficiency, and regulatory flexibility, turning fractionalization into a compliance-preserving primitive rather than an auxiliary layer.</p> <p>The functions <code>wrapToken</code> and <code>wrapTokenFromPartition</code> are essential for simplifying conversions within the token system. <code>wrapToken</code> is specifically designed for wrapping ERC-20-like tokens to this protocol, on the other hand, <code>wrapTokenFromPartition</code> is used when we want to convert tokens from non-fungible tokens or any multi-standard token into proposed protocol. It allows for more specialized conversions, ensuring tokens from different standards can work together smoothly.</p> <p>The <code>unwrapToken</code> function is used to reverse the process of wrapping tokens. When tokens are wrapped, they're usually locked or held in a special way to ensure they're used correctly. users can unlock or release these tokens, returning them to their original standard, essentially, frees up tokens that were previously locked, giving users more control over their assets in the ecosystem.</p> <h3 id="payment-distribution">Payment distribution</h3> <p>The <code>payout</code> function enables direct payments to individual token holders for one-off or event-triggered distributions, facilitating targeted disbursements. Meanwhile, the <code>batchPayout</code> function processes multiple payments in a single transaction, optimizing efficiency for larger-scale or regular payouts on the blockchain</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The proposal is fully compatible with <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> , and any <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> compliant wallet or marketplace can interact with the proposal's tokens. The additional functions introduced by this proposal do not conflict with the <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> interface, ensuring seamless integration with existing ecosystem tools and infrastructure.</p> <h2 id="security-considerations">Security Considerations</h2> <ol> <li>Access Control: The proposal includes functions that can significantly impact token transfers and balances, such as <code>forceTransfer</code>, <code>freezeAddress</code>, and <code>lockTokens</code>. It is crucial to implement proper access control mechanisms, such as role-based permissions, to ensure that only authorized entities can execute these functions.</li> <li>Parameter Validation: Functions like <code>safeTransferFrom</code>, <code>lockTokens</code>, and <code>forceTransfer</code> should validate input parameters to prevent unauthorized or unintended actions. This includes checking for valid addresses, sufficient balances, and appropriate permissions.</li> <li>Reentrancy Protection: The contract should implement reentrancy guards to prevent potential vulnerabilities arising from external calls, especially in functions that transfer tokens or update balances.</li> <li>Overflow/Underflow Protection: The contract should use safe math libraries or built-in overflow protection to prevent integer overflow and underflow vulnerabilities.</li> <li>Payout Security: The <code>payout</code> and <code>batchPayout</code> functions should ensure that only authorized entities can initiate payouts and that the total payout amount does not exceed the available balance. Proper access control and input validation are essential to prevent unauthorized or fraudulent payouts.</li> <li>Off-Chain Voucher Security: When using off-chain vouchers for dynamic compliance management, it is crucial to ensure the security and integrity of the voucher generation process. The compliance service responsible for generating vouchers should have robust security measures in place to prevent unauthorized voucher creation or tampering. Additionally, the proposed contract should thoroughly validate the authenticity and validity of vouchers before allowing transfers to proceed.</li> <li>Operational considerations for unfreezing: Unfreezing restores an account's ability to transfer and receive payouts. Implementers and operators should evaluate applicable regulatory and contractual obligations before unfreezing an address.</li> </ol> <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-12T00:00:00+00:00 2026-02-11T14:48:25+00:00 Bofu Chenhttps://github.com/bafu Tammy Yanghttps://github.com/tammyyang https://wg-eips.ritovision.com/7517/

A proposal adding "dataMiningPreference" in the metadata to preserve the digital content's original intent and respect creator's rights.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a standardized approach to declaring mining preferences for digital media content on the EVM-compatible blockchains. This extends digital media metadata standards like <a href="https://wg-eips.ritovision.com/7053/">ERC-7053</a> and NFT metadata standards like <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>, allowing asset creators to specify how their assets are used in data mining, AI training, and machine learning workflows.</p> <h2 id="motivation">Motivation</h2> <p>As digital assets become increasingly utilized in AI and machine learning workflows, it is critical that the rights and preferences of asset creators and license owners are respected, and the AI/ML creators can check and collect data easily and safely. Similar to robot.txt to websites, content owners and creators are looking for more direct control over how their creativities are used.</p> <p>This proposal standardizes a method of declaring these preferences. Adding <code>dataMiningPreference</code> in the content metadata allows creators to include the information about whether the asset may be used as part of a data mining or AI/ML training workflow. This ensures the original intent of the content is maintained.</p> <p>For AI-focused applications, this information serves as a guideline, facilitating the ethical and efficient use of content while respecting the creator's rights and building a sustainable data mining and AI/ML environment.</p> <p>The introduction of the <code>dataMiningPreference</code> property in digital asset metadata covers the considerations including:</p> <ul> <li>Accessibility: A clear and easily accessible method with human-readibility and machine-readibility for digital asset creators and license owners to express their preferences for how their assets are used in data mining and AI/ML training workflows. The AI/ML creators can check and collect data systematically.</li> <li>Adoption: As Coalition for Content Provenance and Authenticity (C2PA) already outlines guidelines for indicating whether an asset may be used in data mining or AI/ML training, it's crucial that onchain metadata aligns with these standards. This ensures compatibility between in-media metadata and onchain records.</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>This EIP introduces a new property, <code>dataMiningPreference</code>, to the metadata standards which signify the choices made by the asset creators or license owners regarding the suitability of their asset for inclusion in data mining or AI/ML training workflows. <code>dataMiningPreference</code> is an object that can include one or more specific conditions.</p> <ul> <li><code>dataMining</code>: Allow the asset to be used in data mining for determining "patterns, trends, and correlations".</li> <li><code>aiInference</code>: Allow the asset to be used as input to a trained AI/ML model for inferring a result.</li> <li><code>aiGenerativeTraining</code>: Allow the asset to be used as training data for an AI/ML model that could produce derivative assets.</li> <li><code>aiGenerativeTrainingWithAuthorship</code>: Same as <code>aiGenerativeTraining</code>, but requires that the authorship is disclosed.</li> <li><code>aiTraining</code>: Allow the asset to be used as training data for generative and non-generative AI/ML models.</li> <li><code>aiTrainingWithAuthorship</code>: Same as <code>aiTraining</code>, but requires that the authorship is disclosed.</li> </ul> <p>Each category is defined by a set of permissions that can take on one of three values: <code>allowed</code>, <code>notAllowed</code>, and <code>constraint</code>.</p> <ul> <li><code>allowed</code> indicates that the asset can be freely used for the specific purpose without any limitations or restrictions.</li> <li><code>notAllowed</code> means that the use of the asset for that particular purpose is strictly prohibited.</li> <li><code>constrained</code> suggests that the use of the asset is permitted, but with certain conditions or restrictions that must be adhered to.</li> </ul> <p>For instance, the <code>aiInference</code> property indicates whether the asset can be used as input for an AI/ML model to derive results. If set to <code>allowed</code>, the asset can be utilized without restrictions. If <code>notAllowed</code>, the asset is prohibited from AI inference.</p> <p>If marked as <code>constrained</code>, certain conditions, detailed in the license document, must be met. When <code>constraint</code> is selected, parties intending to use the media files should respect the rules specified in the license. To avoid discrepancies with the content license, the specifics of these constraints are not detailed within the schema, but the license reference should be included in the content metadata.</p> <h3 id="schema">Schema</h3> <p>The JSON schema of <code>dataMiningPreference</code> is defined as follows:</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">dataMining</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">allowed</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">notAllowed</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">constrained</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">aiInference</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">allowed</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">notAllowed</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">constrained</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">aiTraining</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">allowed</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">notAllowed</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">constrained</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">aiGenerativeTraining</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">allowed</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">notAllowed</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">constrained</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">aiTrainingWithAuthorship</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">allowed</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">notAllowed</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">constrained</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">aiGenerativeTrainingWithAuthorship</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">allowed</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">notAllowed</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">constrained</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">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="examples">Examples</h3> <p>The mining preference example for not allowing generative AI training:</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">dataMiningPreference</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">dataMining</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiInference</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiTrainingWithAuthorship</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiGenerativeTraining</span><span class="z-support">&quot;</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 class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The mining preference example for only allowing for AI inference:</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">dataMiningPreference</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">aiInference</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiTraining</span><span class="z-support">&quot;</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 class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiGenerativeTraining</span><span class="z-support">&quot;</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 class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The mining preference example for allowing generative AI training if mentioning authorship and follow license:</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">dataMiningPreference</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">dataMining</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiInference</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiTrainingWithAuthorship</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiGenerativeTrainingWithAuthorship</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">constrained</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="example-usage-with-erc-721">Example Usage with ERC-721</h3> <p>The following is an example of using the <code>dataMiningPreference</code> property in <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> NFTs.</p> <p>We can put the <code>dataMiningPreference</code> field in the NFT metadata below. The <code>license</code> field is only an example for specifying how to use a constrained condition, and is not defined in this proposal. A NFT has its way to describe its license.</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">The Starry Night, revision</span><span class="z-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">Recreation of the oil-on-canvas painting by the Dutch Post-Impressionist painter Vincent van Gogh.</span><span class="z-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://bafyaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">dataMiningPreference</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">dataMining</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiInference</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiTrainingWithAuthorship</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiGenerativeTrainingWithAuthorship</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">constrained</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">license</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">CC-BY-4.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">document</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://creativecommons.org/licenses/by/4.0/legalcode</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="example-usage-with-erc-7053">Example Usage with ERC-7053</h3> <p>The example using the <code>dataMiningPreference</code> property in onchain media provenance registration defined in <a href="https://wg-eips.ritovision.com/7053/">ERC-7053</a>.</p> <p>Assuming the Decentralized Content Identifier (CID) is <code>bafyaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa</code>. We can put the <code>dataMiningPreference</code> field in the Commit data directly. After following up the CID, got the Commit data:</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">dataMiningPreference</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">dataMining</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiInference</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiTrainingWithAuthorship</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiGenerativeTrainingWithAuthorship</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">constrained</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">license</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">CC-BY-4.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">document</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://creativecommons.org/licenses/by/4.0/legalcode</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>We can also put the <code>dataMiningPreference</code> field in any custom metadata whose CID is linked in the Commit data. The <code>assetTreeCid</code> field is an example for specifying how to link a custom metadata. After following up the CID, got the Commit data:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /*</span><span class="z-comment"> custom metadata CID </span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">assetTreeCid</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">bafybbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Following up the <code>assetTreeCid</code> which describes the custom properties of the registered asset:</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">dataMiningPreference</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">dataMining</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiInference</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiTrainingWithAuthorship</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">aiGenerativeTrainingWithAuthorship</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">constrained</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">license</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">CC-BY-4.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">document</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://creativecommons.org/licenses/by/4.0/legalcode</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>The technical decisions behind this EIP have been carefully considered to address specific challenges and requirements in the digital asset landscape. Here are the clarifications for the rationale behind:</p> <ol> <li>Adoption of JSON schema: The use of JSON facilitates ease of integration and interaction, both manually and programmatically, with the metadata.</li> <li>Detailed control with training types: The different categories like <code>aiGenerativeTraining</code>, <code>aiTraining</code>, and <code>aiInference</code> let creators control in detail, considering both ethics and computer resource needs.</li> <li>Authorship options included: Options like <code>aiGenerativeTrainingWithAuthorship</code> and <code>aiTrainingWithAuthorship</code> make sure creators get credit, addressing ethical and legal issues.</li> <li>Introduction of <code>constrained</code> category: The introduction of <code>constrained</code> category serves as an intermediary between <code>allowed</code> and <code>notAllowed</code>. It signals that additional permissions or clarifications may be required, defaulting to <code>notAllowed</code> in the absence of such information.</li> <li>C2PA alignment for interoperability: The standard aligns with C2PA guidelines, ensuring seamless mapping between onchain metadata and existing offchain standards.</li> </ol> <h2 id="security-considerations">Security Considerations</h2> <p>When adopting this EIP, it’s essential to address several security aspects to ensure the safety and integrity of adoption:</p> <ul> <li>Data Integrity: Since this EIP facilitates the declaration of mining preferences for digital media assets, the integrity of the data should be assured. Any tampering with the <code>dataMiningPreference</code> property can lead to unauthorized data mining usage. Blockchain's immutability will play a significant role here, but additional security layers, such as cryptographic signatures, can further ensure data integrity.</li> <li>Verifiable Authenticity: Ensure that the individual or entity setting the <code>dataMiningPreference</code> is the legitimate owner or authorized representative of the digital asset. Unauthorized changes to preferences can lead to data misuse. Cross-checking asset provenance and ownership becomes paramount. Services or smart contracts should be implemented to verify the authenticity of assets before trusting the <code>dataMiningPreference</code>.</li> <li>Data Privacy: Ensure that the process of recording preferences doesn't inadvertently expose sensitive information about the asset creators or owners. Although the Ethereum blockchain is public, careful consideration is required to ensure no unintended data leakage.</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> 2023-09-11T00:00:00+00:00 2026-02-11T14:49:27+00:00 Carl Beekhuizenhttps://github.com/carlbeek https://wg-eips.ritovision.com/7516/

Instruction that returns the current data-blob base-fee

<h2 id="abstract">Abstract</h2> <p>Add a <code>BLOBBASEFEE (0x4a)</code> instruction that returns the value of the blob base-fee of the current block it is executing in. It is the identical to <a href="https://wg-eips.ritovision.com/3198/">EIP-3198</a> (<code>BASEFEE</code> opcode) except that it returns the blob base-fee as per <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>.</p> <h2 id="motivation">Motivation</h2> <p>The intended use case would be for contracts to get the value of the blob base-fee. This feature enables blob-data users to programmatically account for the blob gas price, eg:</p> <ul> <li>Allow rollup contracts to trustlessly account for blob data usage costs.</li> <li>Blob gas futures can be implemented based on it which allows for blob users to smooth out data blob costs.</li> </ul> <h2 id="specification">Specification</h2> <p>Add a <code>BLOBBASEFEE</code> instruction with opcode <code>0x4a</code>, with gas cost <code>2</code>.</p> <table><thead><tr><th>Op</th><th>Input</th><th>Output</th><th>Cost</th></tr></thead><tbody> <tr><td>0x4a</td><td>0</td><td>1</td><td>2</td></tr> </tbody></table> <p><code>BLOBBASEFEE</code> returns the result of the <code>get_blob_gasprice(header) -&gt; int</code> function as defined in <a href="https://wg-eips.ritovision.com/4844/#gas-accounting">EIP-4844 §Gas accounting</a>.</p> <h2 id="rationale">Rationale</h2> <h3 id="gas-cost">Gas cost</h3> <p>The value of the blob base-fee is needed to process data-blob transactions. That means its value is already available before running the EVM code. The instruction does not add extra complexity and additional read/write operations, hence the choice of <code>2</code> gas cost. This is also identical to <a href="https://wg-eips.ritovision.com/3198/">EIP-3198</a> (<code>BASEFEE</code> opcode)'s cost as it just makes available data that is in the header.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no known backward compatibility issues with this instruction.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="nominal-case">Nominal Case</h3> <p>Assume calling <code>get_blob_gasprice(header)</code> (as defined in <a href="https://wg-eips.ritovision.com/4844/#gas-accounting">EIP-4844 §Gas accounting</a>) on the current block's header returns <code>7 wei</code>: <code>BLOBBASEFEE</code> should push the value <code>7</code> (left padded byte32) to the stack.</p> <p>Bytecode: <code>0x4900</code> (<code>BLOBBASEFEE, STOP</code>)</p> <table><thead><tr><th>Pc</th><th>Op</th><th>Cost</th><th>Stack</th><th>RStack</th></tr></thead><tbody> <tr><td>0</td><td>BLOBBASEFEE</td><td>2</td><td>[]</td><td>[]</td></tr> <tr><td>1</td><td>STOP</td><td>0</td><td>[7]</td><td>[]</td></tr> </tbody></table> <p>Output: 0x Consumed gas: <code>2</code></p> <h3 id="comprehensive-test-suite">Comprehensive Test Suite</h3> <p>A complete suite of tests can be found <a rel="external" href="https://github.com/ethereum/execution-spec-tests/blob/1983444bbe1a471886ef7c0e82253ffe2a4053e1/tests/cancun/eip7516_blobgasfee/test_blobgasfee_opcode.py">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The value of the blob base-fee is not sensitive and is publicly accessible in the block header. There are no known security implications with this 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> 2023-09-07T00:00:00+00:00 2026-02-11T14:49:27+00:00 dapplionhttps://github.com/dapplion Tim Beikohttps://github.com/timbeiko https://wg-eips.ritovision.com/7514/

Modify the churn limit function to upper bound it to a max value

<h2 id="abstract">Abstract</h2> <p>Update the maximum validator growth rate from an exponential to a linear increase by capping the epoch churn limit.</p> <h2 id="motivation">Motivation</h2> <p>This proposal aims to mitigate the negative externalities of very high level of total ETH supply staked before a proper solution is implemented. In other words, this proposal accepts the complexities of changing the rewards curve and is meant only to slow down growth.</p> <p>In the event that the deposit queue stays 100% full, the share of ETH supply staked will reach 50% by May 2024, 75% by September 2024, and 100% by December 2024. While rewards decrease as the validator set size increases, at 100% of ETH supply staked, yearly consensus rewards alone (excluding MEV/transaction fees) for validators still represent ~1.6% of their stake. This small yield does not necessarily dissuade additional capital staking due to the often much higher and unpredictable yields from MEV. As such, the equilibrium point of the validator set size can be close to its maximum possible. Liquid staking tokens (LSTs) also contribute to this, given stakers can use them as they use unstaked ETH.</p> <p>As the levels of ETH staked increase, more strain is put on the consensus layer. A larger number of validators leads to an increase in gossip messages, as well as a growing Beacon state size. Additionally, as the amount of stake grows, it's unclear how much marginal security benefits come from additional economic weight.</p> <p>The Beacon Chain validator reward function was chosen before its launch in 2020. PoS research and reward curve design were performed in a pre-MEV world. Much has changed since then, including the Beacon chain achieving unprecedented success, beyond the original intended targets of stake rate. In light of this, it is worth discussing whether Beacon chain validator rewards should be adjusted to better match today's reality, potentially to discourage staking past a certain point.</p> <p>This EIP does not attempt to do this, but to allow more time for the community to have these discussions. By limiting the epoch churn limit now, the time to reach critical milestones of total ETH supply staked are significantly delayed. This allows more time for research into more comprehensive solutions, and for community consensus around them to emerge.</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_PER_EPOCH_ACTIVATION_CHURN_LIMIT</code></td><td>8</td></tr> </tbody></table> <h3 id="execution-layer">Execution layer</h3> <p>This requires no changes to the Execution Layer.</p> <h3 id="consensus-layer">Consensus layer</h3> <ul> <li>Add <code>get_validator_activation_churn_limit</code> with upper bound <code>MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT</code></li> <li>Modify <code>process_registry_updates</code> to use bounded activation churn limit</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/69d34dc4ee3d026ca437d1b6875b218e8aaf3a5c/specs/deneb/beacon-chain.md"><code>/specs/deneb/beacon-chain.md</code></a>.</p> <h2 id="rationale">Rationale</h2> <h3 id="max-per-epoch-churn-limit-value"><code>MAX_PER_EPOCH_CHURN_LIMIT</code> value</h3> <p>Depending on the specific constant selection the churn can <em>decrease</em> at the activation fork epoch. The Beacon chain spec can handle this without issues. During 2023 Q4 (projected Dencun activation) the churn value will range 14-16. The table below compares the projected validator set assuming a continuous full deposit queue.</p> <h4 id="max-per-epoch-churn-limit-activation-date-dec-01-2023"><code>MAX_PER_EPOCH_CHURN_LIMIT</code> activation date: Dec 01, 2023</h4> <table><thead><tr><th style="text-align: right">Max Churn Limit</th><th style="text-align: left">50% ETH staked</th><th style="text-align: left">75% ETH staked</th><th style="text-align: left">100% ETH staked</th></tr></thead><tbody> <tr><td style="text-align: right">inf</td><td style="text-align: left">May 28, 2024</td><td style="text-align: left">Sep 25, 2024</td><td style="text-align: left">Dec 18, 2024</td></tr> <tr><td style="text-align: right">16</td><td style="text-align: left">Jul 23, 2024</td><td style="text-align: left">Apr 10, 2025</td><td style="text-align: left">Dec 26, 2025</td></tr> <tr><td style="text-align: right">12</td><td style="text-align: left">Oct 09, 2024</td><td style="text-align: left">Sep 21, 2025</td><td style="text-align: left">Sep 04, 2026</td></tr> <tr><td style="text-align: right">8</td><td style="text-align: left">Mar 15, 2025</td><td style="text-align: left">Aug 18, 2026</td><td style="text-align: left">Jan 21, 2028</td></tr> <tr><td style="text-align: right">6</td><td style="text-align: left">Aug 19, 2025</td><td style="text-align: left">Jul 14, 2027</td><td style="text-align: left">Jun 08, 2029</td></tr> <tr><td style="text-align: right">4</td><td style="text-align: left">Jun 29, 2026</td><td style="text-align: left">May 05, 2029</td><td style="text-align: left">Mar 12, 2032</td></tr> </tbody></table> <h4 id="max-per-epoch-churn-limit-activation-date-apr-01-2024"><code>MAX_PER_EPOCH_CHURN_LIMIT</code> activation date: Apr 01, 2024</h4> <table><thead><tr><th style="text-align: right">Max Churn Limit</th><th style="text-align: left">50% ETH staked</th><th style="text-align: left">75% ETH staked</th><th style="text-align: left">100% ETH staked</th></tr></thead><tbody> <tr><td style="text-align: right">inf</td><td style="text-align: left">May 28, 2024</td><td style="text-align: left">Sep 25, 2024</td><td style="text-align: left">Dec 18, 2024</td></tr> <tr><td style="text-align: right">16</td><td style="text-align: left">Jul 01, 2024</td><td style="text-align: left">Mar 18, 2025</td><td style="text-align: left">Dec 04, 2025</td></tr> <tr><td style="text-align: right">12</td><td style="text-align: left">Aug 01, 2024</td><td style="text-align: left">Jul 14, 2025</td><td style="text-align: left">Jun 26, 2026</td></tr> <tr><td style="text-align: right">8</td><td style="text-align: left">Oct 01, 2024</td><td style="text-align: left">Mar 05, 2026</td><td style="text-align: left">Aug 08, 2027</td></tr> <tr><td style="text-align: right">6</td><td style="text-align: left">Dec 01, 2024</td><td style="text-align: left">Oct 26, 2026</td><td style="text-align: left">Sep 20, 2028</td></tr> <tr><td style="text-align: right">4</td><td style="text-align: left">Apr 02, 2025</td><td style="text-align: left">Feb 07, 2028</td><td style="text-align: left">Dec 15, 2030</td></tr> </tbody></table> <p>Assuming that the earliest the next fork can happen is at the start of 2024 Q3, a value of 8 provides a significant reduction in projected size without causing a big drop in churn at a projected Dencun fork date. A value of 8 prevents reaching a level of 50% ETH staked for at least 1 full year even with a delayed dencun fork.</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> <h2 id="test-cases">Test Cases</h2> <p>Test cases for this EIP can be found in the <a rel="external" href="https://github.com/ethereum/consensus-specs/tree/2297c09b7e457a13f7b2261a28cb45777be82f83/tests/core/pyspec/eth2spec/test/deneb"><code>deneb</code></a> test suite of the <code>consensus-specs</code> repository.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP breaks the symmetry between the validator entry and exit queues, where the former is bound by <code>MAX_PER_EPOCH_ACTIVATION_CHURN_LIMIT</code> while the latter isn't.</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-06T00:00:00+00:00 2026-02-11T14:48:25+00:00 MJ Tsenghttps://github.com/TsengMJtsngmj@gmail.com Clayhttps://github.com/Clay2018clay.uw@outlook.com Jeffery.cjeffery.c@a3sprotocol.xyz Johnny.cjohnny.c@a3sprotocol.xyz https://wg-eips.ritovision.com/7513/

This proposal defines a new type of NFT that combines smart contract execution logic, granting NFTs executable capabilities.

<h2 id="abstract">Abstract</h2> <p>Smart NFT is the fusion of Smart Contract and NFT. An NFT with the logic of a Smart Contract can be executed, enabling on-chain interactions. Transitioning from an NFT to a Smart NFT is akin to going from a regular landline telephone to a smartphone, opening up broader and more intelligent possibilities for NFTs.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum introduces smart contracts revolutionized the blockchain and paved the way for the flourishing ecosystem of decentralized applications (dApps). Also, the concept of non-fungible tokens (NFTs) was introduced through <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, offering a paradigm for ownership verification.</p> <p>However, smart contracts still present significant barriers for most users, and NFTs have largely been limited to repetitive explorations within Art, Gaming, and Real-World Assets realm.</p> <p>The widespread adoption of smart contracts and the functional applications of NFTs still face substantial challenges. Here are some facts that emerges from this contradiction:</p> <ol> <li>The strong desire for both intelligence and usability has led users to sacrifice security (sharing their private key with BOTs)</li> <li>For individual developers, the process of turning functionalities into market-ready products is hindered by a lack of sufficient resources.</li> <li>In the context of a "Code is Law" philosophy, there is a lack of on-chain infrastructure for securely transferring ownership of smart contracts/code.</li> </ol> <h3 id="usability-with-security">Usability with Security</h3> <p>IA-NFT acts as a key of a smart contract. With no private key, no risk of private key leakage.</p> <h3 id="ia-nft-as-native-on-chain-asset">IA-NFT as Native On-chain Asset</h3> <p>For years, NFT stands for the ownership of a picture, a piece of artwork, a game item, a real-world asset. All these backed assets are in fact not crypto native. IA-NFT verify the ownership of a piece of code or a smart contract.</p> <h3 id="interaction-abstraction-for-the-intent-abstraction">Interaction Abstraction for the Intent Abstraction</h3> <p>The on-chain interaction can be abstract to many functional module IA-NFTs and thus make the Interaction process more effective. Users can focus more on their intent rather than how to operate cross different dApps.</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="overview">Overview</h3> <p>The following section will define the interface specifications for three main objects: Smart-NFT, Smart-Manager, Intent-Proxy, and establish the interaction relationships between three primary roles (developer, verifier, user) and these objects.</p> <p><img src="https://wg-eips.ritovision.com/7513/./assets/workflow.png" alt="" /></p> <h3 id="smart-nft-interface">Smart-NFT Interface</h3> <p>Before sending a registration request to Smart-Manager, developers should implement the following two core interfaces in Smart-NFT.</p> <ul> <li> <p><code>execute</code>: This function <strong>MUST</strong> contain only one parameter of the "bytes" type, which encapsulates the required parameters for a specific Smart-NFT. Additionally, <strong>MUST</strong> call validatePermission during the implementation to determine if this call is legitimate.</p> </li> <li> <p><code>validatePermission</code>: This function is used to query the Smart-Manager to determine whether the Smart-NFT has been successfully verified and is callable by the caller.</p> </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"> ISmartNFT</span><span> {</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-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-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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> validatePermission</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></span></code></pre><h3 id="smart-manager-interface">Smart-Manager Interface</h3> <p>The Smart-Manager interface defines 5 possible states for Smart-NFTs:：</p> <ul> <li><strong>UNREGISTERED</strong>: Refers to Smart-NFTs that have not been registered with the Smart-Manager.</li> <li><strong>DEREGISTERED</strong>: Denotes Smart-NFTs that were previously registered but have been removed or deregistered from the Smart-Manager.</li> <li><strong>UNVERIFIED</strong>: Signifies Smart-NFTs that have been registered with the Smart-Manager but have not yet undergone the verification process.</li> <li><strong>VERIFIED</strong>: Represents Smart-NFTs that have been registered with the Smart-Manager and have successfully passed the verification process, indicating they are safe to use.</li> <li><strong>DENIED</strong>: Refers to Smart-NFTs that have been registered but failed the verification process, indicating they should not be used as they may pose security risks.</li> </ul> <p>Smart-Manager should be implemented with the following thress core interfaces.</p> <ul> <li> <p><code>register</code>: Developers can initiate a registration request for a Smart-NFT through this interface and provide the Smart-NFT's creation code. Upon successful request, the Smart-NFT <strong>MUST</strong> be marked as <em>UNVERIFIED</em>.</p> </li> <li> <p><code>auditTo</code>: <strong>Should</strong> only let trusted verifiers use this interface to audit a Smart-NFT to change its status to <em>Verified</em> or <em>Denied</em>.</p> </li> <li> <p><code>isAccessible</code>: This interface is used to ascertain whether a user can use a specific Smart-NFT. The determination <strong>MUST</strong> involves considering both the ownership of the corresponding tokenId NFT and whether the Smart-NFT has been successfully verified.</p> </li> <li> <p><code>verificationStatusOf</code>: The function <strong>MUST</strong> returns the current verification stage of the specified Smart-NFT.</p> </li> </ul> <p>Additionally, the implementation of Smart-Manager <strong>SHOULD</strong> inherit from <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</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"> ISmartManager</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> VerificationStatus</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> UNREGISTERED</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> DEREGISTERED</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> UNVERIFIED</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> VERIFIED</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> DENIED</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"> register</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"> creationCode</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> totalSupply</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">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> implAddr</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"> auditTo</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> isValid</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"> isAccessible</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> caller</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">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"> verificationStatusOf</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-storage z-type">VerificationStatus</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="intent-proxy-interface">Intent-Proxy Interface</h3> <p>Intent-Proxy interface defines an Action struct:</p> <table><thead><tr><th>name</th><th>type</th><th>defination</th></tr></thead><tbody> <tr><td>tokenId</td><td>uint256</td><td>The nft id of the target Smart-NFT to call</td></tr> <tr><td>executeParam</td><td>bytes</td><td>The param defined by the target Smart-NFT's execute encode packed input</td></tr> </tbody></table> <p>Intent-Proxy should be implemented with <code>executeIntent</code>.</p> <ul> <li>executeIntent: Users can achieve batch use of specified Smart-NFTs by calling this interface and providing an array of desired actions.</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"> IIntentProxy</span><span> {</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"> uint256</span><span> tokenId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> executeParam</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"> executeIntent</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> Action</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> actions</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 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="why-using-erc-1155">Why using ERC-1155</h3> <p>In the technical implementation aspect, we chose to use <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> as the main contract for NFTs due to the consideration of increasing the reusability of Smart-NFTs. The reason for this choice is that both <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> are based on the concept of "token IDs" that point to NFTs. The key difference is that <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> introduces the concept of "shares," meaning that having at least one share gives you the right to use the functionality of that Smart-NFT. This concept can be likened to owning multiple smartphones of the same model, where owning several smartphones doesn't grant you additional features; you can only use the features of each individual device.</p> <p>Another reason for directly using <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> instead of defining a new NFT standard is the seamless integration of Smart-NFT transaction behavior into the existing market. This approach benefits both developers and users, as it simplifies the adoption of Smart-NFTs into the current ecosystem.</p> <h3 id="verifier">Verifier</h3> <p>In this protocol, Verifiers play a crucial role, responsible for auditing and verifying Smart-NFT code. However, decentralized Verifiers face some highly challenging issues, with one of the primary concerns being the specialized expertise required for their role, which is not easily accessible to the general population.</p> <p>First, let's clarify the responsibilities of Verifiers, which include assessing the security, functionality, and compliance of smart contract code. This work demands professional programming skills, blockchain technology knowledge, and contract expertise. Verifiers must ensure the absence of vulnerabilities in the code.</p> <p>Secondly, decentralized Verifiers encounter challenges related to authority and credibility. In a centralized model, we can trust a specific auditing organization or expert to perform this task. However, in a decentralized environment, it becomes difficult to determine the expertise and integrity of Verifiers. This could potentially lead to incorrect audits and might even be abused to undermine overall stability and reliability.</p> <p>Lastly, achieving decentralized Verifiers also requires addressing coordination and management issues. In a centralized model, the responsibilities of managing and supervising Verifiers are relatively straightforward. However, in a decentralized environment, coordinating the work of various Verifiers and ensuring consistency in their audits across different contracts and code become significant challenges.</p> <h3 id="copyright-infringement-issue">Copyright infringement issue</h3> <p>Code plagiarism has always been a topic of concern, but often, such discussions seem unnecessary. We present two key points: first, overly simple code has no value, making discussions about plagiarism irrelevant. Secondly, when code is complex enough or creative, legal protection can be obtained through open-source licenses (OSI).</p> <p>The first point is that for overly simple code, plagiarism is almost meaningless. For example, consider a very basic "Hello World" program. Such code is so simple that almost anyone can independently create it. Discussing plagiarism of such code is a waste of time and resources because it lacks sufficient innovation or value and does not require legal protection.</p> <p>The second point is that when code is complex enough or creative, open-source licenses (OSI) provide legal protection for software developers. Open-source licenses are a way for developers to share their code and specify terms of use. For example, the GNU General Public License (GPL) and the Massachusetts Institute of Technology (MIT) license are common open-source licenses that ensure the original code's creators can retain their intellectual property rights while allowing others to use and modify the code. This approach protects complex and valuable code while promoting innovation and sharing.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal aims to ensure the highest possible compatibility with the existing <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> protocol. All functionalities present in <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>, including <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> detection and Smart-NFT support, are retained. This encompasses compatibility with current NFT trading platforms.</p> <p>For all Smart-NFTs, this proposla only mandates the provision of the <code>execute</code> function. This means that existing proxy contracts need to focus solely on this interface, making integration of Smart-NFTs more straightforward and streamlined.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <code>https://github.com/TsengMJ/EIP-7513_Example</code></p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="malicious-validator">Malicious Validator</h3> <p>All activities involving human intervention inherently carry the risk of malicious behavior. In this protocol, during the verification phase of Smart-NFTs, external validators provide guarantees. However, this structure raises concerns about the possibility of malicious validators intentionally endorsing Malicious Smart-NFTs. To mitigate this risk, it's necessary to implement stricter validation mechanisms, filtering of validators, punitive measures, or even more stringent consensus standards.</p> <h3 id="unexpected-verification-error">Unexpected Verification Error</h3> <p>Apart from the issue of Malicious Validators, there's the possibility of missed detection during the verification phase due to factors like overly complex Smart-NFT implementations or vulnerabilities in the Solidity compiler. This issue can only be addressed by employing additional tools to assist in contract auditing or by implementing multiple validator audits for the auditTo interface to reduce the likelihood of its occurrence.</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-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 Rickeyhttps://github.com/HelloRickey https://wg-eips.ritovision.com/7509/

Represent entities comprising components of data, with systems which operate on entities' components.

<h2 id="abstract">Abstract</h2> <p>This proposal defines a minimal Entity Component System (ECS). Entities are unique identities that are assigned to multiple components (data) and then processed using the system (logic). This proposal standardizes the interface specification for using ECS in smart contracts, providing a set of basic functions that allow users to freely combine and manage multi-contract applications.</p> <h2 id="motivation">Motivation</h2> <p>ECS is a design pattern that improves code reusability by separating data from behavior. It is often used in game development. A minimal ECS consists of<br /> <strong>Entity</strong>: a unique identifier.<br /> <strong>Component</strong>: a reusable data container attached to an entity.<br /> <strong>System</strong>: the logic for operating entity components.<br /> <strong>World</strong>: a container for an entity component system.<br /> This proposal uses smart contracts to implement an easy-to-use minimal ECS, eliminates unnecessary complexity, and makes some functional improvements that are consistent with contract interaction behavior. You can combine components and systems easily and freely. As a smart contract developer, the benefits of adopting ECS include:</p> <ul> <li>It adopts a simple design of decoupling, encapsulation, and modularization, which makes the architecture design of your game or application easier.</li> <li>It has flexible composition ability, each entity can combine different components. You can also define different systems for manipulating the data of these new entities.</li> <li>It is conducive to expansion, and two games or applications can interact by defining new components and systems.</li> <li>It can help your application add new features or upgrades, because data and behavior are separated, new features will not affect your old data.</li> <li>It is easy to manage. When your application consists of multiple contracts, it will help you effectively manage the status of each contract.</li> <li>Its components are reusable, and you can share your components with the community to help others improve development efficiency.</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>World contracts are containers for entities, component contracts, and system contracts. Its core principle is to establish the relationship between entities and component contracts, where different entities will attach different components, and use system contracts to dynamically change the data of the entity in the component.</p> <p>Usual workflow when building ECS-based programs:</p> <ol> <li>Implement the <code>IWorld</code> interface to create a world contract.</li> <li>Call <code>createEntity()</code> of the world contract to create an entity.</li> <li>Implement the <code>IComponent</code> interface to create a Component contract.</li> <li>Call <code>registerComponent()</code> of the world contract to register the component contract.</li> <li>Call <code>addComponent()</code> of the world contract to attach the component to the entity.</li> <li>Create a system contract, which is a contract without interface restrictions, and you can define any function in the system contract.</li> <li>Call <code>registerSystem()</code> of the world contract to register the system contract.</li> <li>Run the system.</li> </ol> <h3 id="interfaces">Interfaces</h3> <h4 id="iworld-sol"><code>IWorld.sol</code></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"> &gt;=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"> IWorld</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * Create a new entity.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The entity MUST be assigned a unique Id.</span></span> <span class="giallo-l"><span class="z-comment"> * If the state of the entity is true, it means it is available, and if it is false, it means it is not available.</span></span> <span class="giallo-l"><span class="z-comment"> * When the state of the entity is false, you cannot add or remove components for the entity.</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"> New</span><span class="z-comment"> entity 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"> createEntity</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">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"> * Does the entity exist in the world.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _entityId</span><span class="z-comment"> is the Id of the entity.</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"> exists, false 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"> entityExists</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _entityId</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"> * Get the total number of entities in the world.</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"> total number of entities.</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"> getEntityCount</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"> * Set the state of an entity.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Entity MUST 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"> _entityId</span><span class="z-comment"> is the Id of the entity.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _entityState</span><span class="z-comment"> is the state of the entity, true means available, false means unavailable.</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"> setEntityState</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _entityId</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _entityState</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"> * Get the state of an entity.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _entityId</span><span class="z-comment"> Id of the entity.</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"> current state of the entity.</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"> getEntityState</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _entityId</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"> * Register a component to the world.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> A component MUST be registered with the world before it can be attached to an entity.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST NOT register the same component to the world repeatedly.</span></span> <span class="giallo-l"><span class="z-comment"> * It SHOULD be checked that the contract address returned by world() of the component contract is the same as the current world contract.</span></span> <span class="giallo-l"><span class="z-comment"> * The state of the component is true means it is available, and false means it is not available. When the component state is set to false, it cannot be attached to the entity.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _componentAddress</span><span class="z-comment"> is the contract address of the component.</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"> registerComponent</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _componentAddress</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"> * Does the component exist in the world.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _componentAddress</span><span class="z-comment"> is the contract address of the component.</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"> exists, false 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"> componentExists</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _componentAddress</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> <span class="giallo-l"><span class="z-comment"> * Get the contract addresses of all components registered in the world.</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"> of contract 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"> getComponents</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> <span class="giallo-l"><span class="z-comment"> * Set component state.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Component MUST 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"> _componentAddress</span><span class="z-comment"> is the contract address of the component.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _componentState</span><span class="z-comment"> is the state of the component, true means available, false means unavailable.</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"> setComponentState</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _componentAddress</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _componentState</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> <span class="giallo-l"><span class="z-comment"> * Get the state of a component.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _componentAddress</span><span class="z-comment"> is the contract address of the component.</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"> means available, false means unavailable.</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"> getComponentState</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _componentAddress</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> <span class="giallo-l"><span class="z-comment"> * Attach a component to the entity.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Entity MUST be available.Component MUST be available.A component MUST NOT be added to an entity repeatedly.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _entityId</span><span class="z-comment"> is the Id of the entity.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _componentAddress</span><span class="z-comment"> is the address of the component to be attached.</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"> addComponent</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _entityId</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _componentAddress</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> <span class="giallo-l"><span class="z-comment"> * Whether the entity has a component attached,</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Entity MUST exist.Component MUST be registered.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _entityId</span><span class="z-comment"> is the Id of the entity.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _componentAddress</span><span class="z-comment"> is the component 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"> is attached, false is not attached</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"> hasComponent</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _entityId</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _componentAddress</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> <span class="giallo-l"><span class="z-comment"> * Remove a component from the entity.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Entity MUST be available.The component MUST have been added to the entity before.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _entityId</span><span class="z-comment"> is the Id of the entity.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _componentAddress</span><span class="z-comment"> is the address of the component to be removed.</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"> removeComponent</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _entityId</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _componentAddress</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> <span class="giallo-l"><span class="z-comment"> * Get the contract addresses of all components attached to the entity.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Entity MUST 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"> _entityId</span><span class="z-comment"> is the Id of the entity.</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"> array of contract addresses of the components owned by this entity.</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"> getEntityComponents</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _entityId</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>)</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"> * Register a system to the world.</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 register the same system to the world repeatedly.The system state is true means available, false means unavailable.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _systemAddress</span><span class="z-comment"> is the contract address 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"> registerSystem</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _systemAddress</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"> * Does the system exist in the world.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _systemAddress</span><span class="z-comment"> is the contract address of the system.</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"> exists, false 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"> systemExists</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _systemAddress</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"> * Get the contract addresses of all systems registered in the world.</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"> of contract 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"> getSystems</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> <span class="giallo-l"><span class="z-comment"> * Set the system State.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> System MUST 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"> _systemAddress</span><span class="z-comment"> is the contract address 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"> _systemState</span><span class="z-comment"> is the state 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"> setSystemState</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _systemAddress</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _systemState</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"> * Get the state of a 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"> _systemAddress</span><span class="z-comment"> is the contract address of the system.</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"> state 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"> getSystemState</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _systemAddress</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><h4 id="icomponent-sol"><code>IComponent.sol</code></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"> &gt;=0.8.0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./Types.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"> IComponent</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * The world contract address registered by the component.</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"> world</span><span class="z-comment"> 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"> world</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"> *Get the data type and get() parameter type of the component</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> SHOULD Import Types Library, which is an enumeration Library containing all data types.</span></span> <span class="giallo-l"><span class="z-comment"> * Entity data can be stored according to the data type.</span></span> <span class="giallo-l"><span class="z-comment"> * The get() parameter data type can be used to get entity data.</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"> data type array of the entity</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"> get</span><span class="z-comment"> parameter data type 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"> types</span><span>(</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">Types</span><span>.</span><span class="z-support z-variable">Type</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>,</span><span class="z-storage z-type"> Types</span><span>.</span><span class="z-support z-variable">Type</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-comment"> *Store entity data.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> entity MUST be available. The system that operates on it MUST be available.</span></span> <span class="giallo-l"><span class="z-comment"> * The entity has the component attached.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _entityId</span><span class="z-comment"> is the Id of the entity.</span></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"> is the data to be stored.</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"> set</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _entityId</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"> _data</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"> *Get the data of the entity according to the entity 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"> _entityId</span><span class="z-comment"> is the Id of the entity.</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"> Entity</span><span class="z-comment"> data.</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"> get</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _entityId</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> <span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> Get the data of the entity according to the entity Id and parameters.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _entityId</span><span class="z-comment"> is the Id of the entity.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _params</span><span class="z-comment"> is an extra parameter, it SHOULD depend on whether you need it.</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"> Entity</span><span class="z-comment"> data.</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"> get</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _entityId</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"> _params</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">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="library">Library</h3> <p>The library <a href="https://wg-eips.ritovision.com/7509/./assets/Types.sol"><code>Types.sol</code></a> contains an enumeration of Solidity types used in the above interfaces.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-include-type-information-instead-of-simple-byte-arrays">Why include type information instead of simple byte arrays?</h3> <p>This is to ensure the correctness of types when using components, in order to avoid potential errors and inconsistencies. External developers can clearly set and get based on the type.</p> <h3 id="why-differentiate-between-a-non-existent-entity-and-an-entity-with-false-state">Why differentiate between a non-existent entity and an entity with false state?</h3> <p>We cannot judge whether an entity actually exists based on its state alone. External contributors can create components based on entities. If the entities he uses don't exist, the components he creates may not make sense. Component creators should first check if the entity exists, and if the entity does exist, it makes sense even if the entity's state is false. Because he can wait for the entity state to be true before attaching the component to the entity.</p> <h3 id="why-getentitycomponents-function-returns-all-addresses-of-components-instead-of-all-component-ids">Why <code>getEntityComponents</code> function returns all addresses of components instead of all component ids?</h3> <p>There are two designs for <code>getEntityComponents</code>. The other design is to add an additional mapping for the storage of component id and component address. Every time we call <code>addComponent</code>, the parameters of the function are the entity id and component id. When the user calls <code>getEntityComponents</code>, it will returning an array of component ids, they query the component address with each component id, and then query the data based on each component address. Because a entity may contain many component ids, this will cause the user to request the component address multiple times. In the end, we chose to use <code>getEntityComponents</code> directly for all addresses owned by the entity.</p> <h3 id="can-registercomponent-and-registersystem-provide-external-permissions">Can <code>registerComponent</code> and <code>registerSystem</code> provide external permissions?</h3> <p>It depends on the openness of your application or game. If you encourage developers to participate, the state of the component and system they submit for registration should be <code>false</code>, and you need to check whether they have submitted malicious code before using <code>setComponentState</code> and <code>setSystemState</code> to enable them .</p> <h3 id="when-to-use-get-with-extra-parameters-in-component">When to use <code>get</code> with extra parameters in component?</h3> <p>The component provides two <code>get</code> functions. One <code>get</code> function only needs to pass in the entity id, and the other has more <code>_params</code> parameters, which will be used as additional parameters for obtaining data. For example, you define a component that stores the HP corresponding to the level of an entity. If you want to get the HP of an entity that matches its level, then you call the <code>get</code> function with the entity level as <code>_params</code>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/7509/assets/README/">Ethereum ECS Example</a></p> <h2 id="security-considerations">Security Considerations</h2> <p>Unless you want to implement special functions, do not provide the following methods directly to ordinary users, they should be set by the contract owner.<br /> <code>createEntity()</code>, <code>setEntityState()</code>, <code>addComponent()</code>, <code>removeComponent()</code>, <code>registerComponent()</code>, <code>setComponentState()</code>, <code>registerSystem()</code>, <code>setSystemState()</code></p> <p>Do not provide functions that modify entities other than set() in the component contract. And add a check in <code>set()</code> to check whether the entity is available and whether the operating system is available.</p> <p>After the system is registered in the world, it will be able to operate the component data of all entities in the world. It is necessary to check and audit the code security of all system contracts before registering it in the world.</p> <p>If the new version has deprecated some entities, component contracts and system contracts. They need to be disabled in time using <code>setEntityState()</code>, <code>setComponentState()</code>, and <code>setSystemState()</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-09-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 Richard Meissner - Safehttps://github.com/rmeissner Robert Chen - OtterSechttps://github.com/chen-robert Matthias Egli - ChainSecurityhttps://github.com/MatthiasEgli Jan Kalivoda - Ackee Blockchainhttps://github.com/jaczkal Michael Lewellen - OpenZeppelinhttps://github.com/cylon56 Shay Zluf - Hats Financehttps://github.com/shayzluf Alex Papageorgiou - Omnisciahttps://github.com/alex-ppg https://wg-eips.ritovision.com/7512/

Proposal to define a contract parseable representation of Audit reports.

<h2 id="abstract">Abstract</h2> <p>The proposal aims to create a standard for an onchain representation of audit reports that can be parsed by contracts to extract relevant information about the audits, such as who performed the audits and what standards have been verified.</p> <h2 id="motivation">Motivation</h2> <p>Audits are an integral part of the smart contract security framework. They are commonly used to increase the security of smart contracts and ensure that they follow best practices as well as correctly implement standards such <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, and similar ERCs. Many essential parts of the blockchain ecosystem are facilitated by the usage of smart contracts. Some examples of this are:</p> <ul> <li>Bridges: Most bridges consist of a bridgehead or a lockbox that secures the tokens that should be bridged. If any of these contracts are faulty it might be possible to bring the operation of the bridge to a halt or, in extreme circumstances, cause uncollateralized assets to be minted on satellite chains.</li> <li>Token Contracts: Every token in the Ethereum ecosystem is a smart contract. Apps that interact with these tokens rely on them adhering to known token standards, most commonly <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. Tokens that behave differently can cause unexpected behavior and might even lead to loss of funds.</li> <li>Smart Contract Accounts (SCAs): With <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> more visibility has been created for smart-contract-based accounts. They provide extreme flexibility and can cater to many different use cases whilst retaining a greater degree of control and security over each account. A concept that has been experimented with is the idea of modules that allow the extension of a smart contract account's functionality. <a href="https://wg-eips.ritovision.com/6900/">ERC-6900</a>) is a recent standard that defines how to register and design plugins that can be registered on an account.</li> <li>Interoperability (Hooks &amp; Callbacks): With more protocols supporting external-facing functions to interact with them and different token standards triggering callbacks on a transfer (i.e. <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>), it is important to make sure that these interactions are well vetted to minimize the security risks they are associated with as much as possible.</li> </ul> <p>The usage and impact smart contracts will have on the day-to-day operations of decentralized applications will steadily increase. To provide tangible guarantees about security and allow better composability it is imperative that an onchain verification method exists to validate that a contract has been audited. Creating a system that can verify that an audit has been made for a specific contract will strengthen the security guarantees of the whole smart contract ecosystem.</p> <p>While this information alone is no guarantee that there are no bugs or flaws in a contract, it can provide an important building block to create innovative security systems for smart contracts in an onchain way.</p> <h3 id="example">Example</h3> <p>Imagine a hypothetical <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> token bridge. The goal is to create a scalable system where it is possible to easily register new tokens that can be bridged. To minimize the risk of malicious or faulty tokens being registered, audits will be used and verified onchain.</p> <p><img src="https://wg-eips.ritovision.com/7512/./assets/example_use_case.png" alt="Onchain Audit Example Use Case" /></p> <p>To illustrate the flow within the diagram clearly, it separates the Bridge and the Verifier roles into distinct actors. Theoretically, both can live in the same contract.</p> <p>There are four parties:</p> <ul> <li>User: The end user that wants to bridge their token</li> <li>Bridge Operator: The operator that maintains the bridge</li> <li>Bridge: The contract the user will interact with to trigger the bridge operation</li> <li>Validator: The contract that validates that a token can be bridged</li> </ul> <p>As a first (1) step, the bridge operator should define the keys/accounts for the auditors from which audits are accepted for the token registration process.</p> <p>With this, the user (or token owner) can trigger the registration flow (2). There are two steps (3 and 6) that will be performed: verify that the provided audit is valid and has been signed by a trusted auditor (4), and check that the token contract implements the bridge's supported token standard (<a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>) (7).</p> <p>After the audit and token standard validations have been performed, it is still advisable to have some form of manual intervention in place by the operator to activate a token for bridging (10). <!-- This step could be omitted if there is strong trust in the auditor or if an ERC provides strong compatibility guarantees. --></p> <p>Once the token has been activated on the bridge, Users can start bridging it (11).</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="audit-properties">Audit Properties</h3> <ul> <li>Auditor <ul> <li><code>name</code>: Name of the auditor (i.e. for displaying to the user)</li> <li><code>uri</code>: URI to retrieve more information about the auditor</li> <li><code>authors</code>: A list of authors that contributed to this audit. This SHOULD be the persons who audited the contracts and created the audit</li> </ul> </li> <li>Audit <ul> <li><code>auditor</code>: Information on the auditor</li> <li><code>auditedContract</code>: MUST be the <code>chainId</code> as well as <code>deployment</code> of the contract the audit is related to</li> <li><code>issuedAt</code>: MUST contain the information when the original audit (identified by the <code>auditHash</code>) was issued</li> <li><code>ercs</code>: A list of ERCs that are implemented by the target contract. The ERCs listed MUST be fully implemented. This list MAY be empty</li> <li><code>auditHash</code>: MUST be the hash of the original audit. This allows onchain verification of information that may belong to a specific audit</li> <li><code>auditUri</code>: SHOULD point to a source where the audit can be retrieved</li> </ul> </li> <li>Contract <ul> <li><code>chainId</code>: MUST be a <code>bytes32</code> representation of the <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> chain ID of the blockchain that the contract has been deployed in</li> <li><code>deployment</code>: MUST be an <code>address</code> representation of a contract's deployment address</li> </ul> </li> </ul> <h3 id="auditor-verification">Auditor Verification</h3> <ul> <li>Signature <ul> <li>Type <ul> <li><code>SECP256K1</code> <ul> <li>Data is the encoded representation of <code>r</code>, <code>s</code>, and <code>v</code></li> </ul> </li> <li><code>BLS</code> <ul> <li>TBD</li> </ul> </li> <li><code>ERC1271</code> <ul> <li>Data is the ABI-encoded representation of <code>chainId</code>, <code>address</code>, <code>blocknumber</code>, and the <code>signature bytes</code></li> </ul> </li> <li><code>SECP256R1</code> <ul> <li>Data is the encoded representation of <code>r</code>, <code>s</code>, and <code>v</code></li> </ul> </li> </ul> </li> <li>Data</li> </ul> </li> </ul> <h3 id="data-types">Data types</h3> <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"> Auditor</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> uri</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span> authors</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"> Contract</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> chainId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> deployment</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"> AuditSummary</span><span> {</span></span> <span class="giallo-l"><span> Auditor auditor</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> issuedAt</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span> ercs</span><span>;</span></span> <span class="giallo-l"><span> Contract auditedContract</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> auditHash</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> auditUri</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="signing">Signing</h3> <p>For signing <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> will be used. For this the main type is the <code>AuditSummary</code> and as the <code>EIP712Domain</code> the following definition applies:</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"> 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>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>EIP712Domain auditDomain </span><span class="z-keyword">=</span><span class="z-entity z-name"> EIP712Domain</span><span>(</span><span class="z-string">&quot;ERC-7652: Onchain Audit Representation&quot;</span><span>,</span><span class="z-string"> &quot;1.0&quot;</span><span>)</span><span>;</span></span></code></pre> <p>The generated signature can then be attached to the <code>AuditSummary</code> to generate a new <code>SignedAuditSummary</code> object:</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"> SignatureType</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> SECP256K1</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> BLS</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ERC1271</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> SECP256R1</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"> Signature</span><span> {</span></span> <span class="giallo-l"><span> SignatureType </span><span class="z-variable z-language">type</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"> SignedAuditSummary</span><span> extends AuditSummary </span><span>{</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> signedAt</span><span>;</span></span> <span class="giallo-l"><span> Signature auditorSignature</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The current ERC deliberately does not define the <code>findings</code> of an audit. Such a definition would require alignment on the definition of what severities are supported, what data of a finding should be stored onchain vs off-chain, and other similar finding-related attributes that are hard to strictly describe. Given the complexity of this task, we consider it to be outside the scope of this EIP. It is important to note that this ERC proposes that a signed audit summary indicates that a specific contract instance (specified by its <code>chainId</code> and <code>deployment</code>) has undergone a security audit.</p> <p>Furthermore, it indicates that this contract instance correctly implements the listed ERCs. This normally corresponds to the final audit revision for a contract which is then connected to the deployment. As specified above, this ERC MUST NOT be considered an attestation of a contract's security but rather a methodology via which data relevant to a smart contract can be extracted; evaluation of the quality, coverage, and guarantees of the data is left up to the integrators of the ERC.</p> <h3 id="further-considerations">Further Considerations</h3> <ul> <li><code>standards</code> vs <code>ercs</code> <ul> <li>Limiting the scope to audits related to EVM-based smart contract accounts allows a better definition of parameters.</li> </ul> </li> <li><code>chainId</code> and <code>deployment</code> <ul> <li>As a contract's behavior depends on the blockchain it is deployed in, we have opted to associate a <code>chainId</code> as well as <code>deployment</code> address per contract that corresponds to an audit</li> </ul> </li> <li><code>contract</code> vs <code>contracts</code> <ul> <li>Many audits are related to multiple contracts that make up a protocol. To ensure simplicity in the initial version of this ERC, we chose to only reference one contract per audit summary. If multiple contracts have been audited in the same audit engagement, the same audit summary can be associated with different contract instances. An additional benefit of this is the ability to properly associate contract instances with the <code>ercs</code> they support. The main drawback of this approach is that it requires multiple signing passes by the auditors.</li> </ul> </li> <li>Why <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>? <ul> <li><a href="https://wg-eips.ritovision.com/712/">EIP-712</a> was chosen as a base due to its tooling compatibility (i.e. for signing)</li> </ul> </li> <li>How to assign a specific Signing Key to an Auditor? <ul> <li>Auditors should publicly share the public part of the signature, which can be done via their website, professional page, and any such social medium</li> <li>As an extension to this ERC it would be possible to build a public repository, however, this falls out-of-scope of the ERC</li> </ul> </li> <li>Polymorphic Contracts and Proxies <ul> <li>This ERC explicitly does <strong>not</strong> mention polymorphic contracts and proxies. These are important to be considered, however, their proper management is delegated to auditors as well as implementors of this ERC</li> </ul> </li> </ul> <h3 id="future-extensions">Future Extensions</h3> <ul> <li>Potential expansion of ERC to accommodate non-EVM chains</li> <li>Better support for polymorphic/upgradeable contracts and multi-contract audits</li> <li>Management of signing keys for auditors</li> <li>Definition of findings of an audit</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues have been identified in relation to current ERC standards.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>TBD.</p> <p>The following features will be implemented in a reference implementation:</p> <ul> <li>Script to trigger signing based on a JSON representing the audit summary</li> <li>Contract to verify signed audit summary</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <h3 id="auditor-key-management">Auditor Key Management</h3> <p>The premise of this ERC relies on proper key management by the auditors who partake in the system. If an auditor's key is compromised, they may be associated with seemingly audited or ERC-compliant contracts that ultimately could not comply with the standards. As a potential protection measure, the ERC may define an "association" of auditors (f.e. auditing companies) that would permit a secondary key to revoke existing signatures of auditors as a secondary security measure in case of an auditor's key compromise.</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-04T00:00:00+00:00 2026-02-11T14:48:25+00:00 0xAAhttps://github.com/AmazingAng vectorizedhttps://github.com/Vectorized 0agehttps://github.com/0age https://wg-eips.ritovision.com/7511/

Optimizes the previous Minimal Proxy Contract with the PUSH0 opcode

<h2 id="abstract">Abstract</h2> <p>With the <code>PUSH0</code> opcode (<a href="https://wg-eips.ritovision.com/3855/">EIP-3855</a>), introduced with the Shanghai upgrade, we optimized the previous Minimal Proxy Contract (<a href="https://wg-eips.ritovision.com/1167/">ERC-1167</a>) by 200 gas at deployment and 5 gas at runtime, while retaining the same functionality.</p> <h2 id="motivation">Motivation</h2> <ol> <li>Reduce the contract bytecode size by <code>1</code> byte by removing a redundant <code>SWAP</code> opcode.</li> <li>Reduce the runtime gas by replacing two <code>DUP</code> (cost <code>3</code> gas each) with two <code>PUSH0</code> (cost <code>2</code> gas each).</li> <li>Increase the readability of the proxy contract by redesigning it from first principles with <code>PUSH0</code>.</li> </ol> <h2 id="specification">Specification</h2> <h3 id="standard-proxy-contract">Standard Proxy Contract</h3> <p>The exact runtime code for the minimal proxy contract with <code>PUSH0</code> is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>365f5f375f5f365f73bebebebebebebebebebebebebebebebebebebebe5af43d5f5f3e5f3d91602a57fd5bf3</span></span></code></pre> <p>where the bytes at indices 9 - 28 (inclusive) are replaced with the 20-byte address of the master implementation contract. The length of the runtime code is <code>44</code> bytes.</p> <p>The disassembly of the new minimal proxy contract code is:</p> <table><thead><tr><th>pc</th><th>op</th><th>opcode</th><th>stack</th></tr></thead><tbody> <tr><td>[00]</td><td>36</td><td>CALLDATASIZE</td><td>cds</td></tr> <tr><td>[01]</td><td>5f</td><td>PUSH0</td><td>0 cds</td></tr> <tr><td>[02]</td><td>5f</td><td>PUSH0</td><td>0 0 cds</td></tr> <tr><td>[03]</td><td>37</td><td>CALLDATACOPY</td><td></td></tr> <tr><td>[04]</td><td>5f</td><td>PUSH0</td><td>0</td></tr> <tr><td>[05]</td><td>5f</td><td>PUSH0</td><td>0 0</td></tr> <tr><td>[06]</td><td>36</td><td>CALLDATASIZE</td><td>cds 0 0</td></tr> <tr><td>[07]</td><td>5f</td><td>PUSH0</td><td>0 cds 0 0</td></tr> <tr><td>[08]</td><td>73bebe.</td><td>PUSH20 0xbebe.</td><td>0xbebe. 0 cds 0 0</td></tr> <tr><td>[1d]</td><td>5a</td><td>GAS</td><td>gas 0xbebe. 0 cds 0 0</td></tr> <tr><td>[1e]</td><td>f4</td><td>DELEGATECALL</td><td>suc</td></tr> <tr><td>[1f]</td><td>3d</td><td>RETURNDATASIZE</td><td>rds suc</td></tr> <tr><td>[20]</td><td>5f</td><td>PUSH0</td><td>0 rds suc</td></tr> <tr><td>[21]</td><td>5f</td><td>PUSH0</td><td>0 0 rds suc</td></tr> <tr><td>[22]</td><td>3e</td><td>RETURNDATACOPY</td><td>suc</td></tr> <tr><td>[23]</td><td>5f</td><td>PUSH0</td><td>0 suc</td></tr> <tr><td>[24]</td><td>3d</td><td>RETURNDATASIZE</td><td>rds 0 suc</td></tr> <tr><td>[25]</td><td>91</td><td>SWAP2</td><td>suc 0 rds</td></tr> <tr><td>[26]</td><td>602a</td><td>PUSH1 0x2a</td><td>0x2a suc 0 rds</td></tr> <tr><td>[27]</td><td>57</td><td>JUMPI</td><td>0 rds</td></tr> <tr><td>[29]</td><td>fd</td><td>REVERT</td><td></td></tr> <tr><td>[2a]</td><td>5b</td><td>JUMPDEST</td><td>0 rds</td></tr> <tr><td>[2b]</td><td>f3</td><td>RETURN</td><td></td></tr> </tbody></table> <h3 id="minimal-creation-code">Minimal Creation Code</h3> <p>The minimal creation code of the minimal proxy contract is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>602c8060095f395ff3365f5f375f5f365f73bebebebebebebebebebebebebebebebebebebebe5af43d5f5f3e5f3d91602a57fd5bf3</span></span></code></pre> <p>where the first 9 bytes are the initcode:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>602c8060095f395ff3</span></span></code></pre> <p>And the rest are runtime/contract code of the proxy. The length of the creation code is <code>53</code> bytes.</p> <h3 id="deploy-with-solidity">Deploy with Solidity</h3> <p>The minimal proxy contract can be deployed with Solidity using the following contract:</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.20</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">: this contract requires `PUSH0`, which is available in solidity &gt; 0.8.20 and EVM version &gt; Shanghai</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Clone0Factory</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> FailedCreateClone</span><span>(</span><span>)</span><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></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"> Deploys and returns the address of a clone0 (Minimal Proxy Contract with `PUSH0`) that mimics the behaviour of `implementation`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * This function uses the create opcode, which should never 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"> clone0</span><span>(</span><span class="z-support">address</span><span class="z-variable"> impl</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> payable</span><span class="z-keyword"> returns</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 class="z-comment"> //</span><span class="z-comment"> first 18 bytes of the creation code </span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> data1 </span><span class="z-keyword">=</span><span> hex</span><span class="z-string">&quot;602c8060095f395ff3365f5f375f5f365f73&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> last 15 bytes of the creation code</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> data2 </span><span class="z-keyword">=</span><span> hex</span><span class="z-string">&quot;5af43d5f5f3e5f3d91602a57fd5bf3&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> complete the creation code of Clone0</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> _code </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>data1</span><span>,</span><span> impl</span><span>,</span><span> data2</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> deploy with create op</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> create(v, p, n)</span></span> <span class="giallo-l"><span> addr </span><span class="z-keyword">:=</span><span class="z-entity z-name"> create</span><span>(</span><span class="z-entity z-name">callvalue</span><span>(</span><span>)</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>_code</span><span>,</span><span class="z-constant"> 0x20</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>_code</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-keyword"> if</span><span> (</span><span>addr </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"> revert</span><span class="z-entity z-name"> FailedCreateClone</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="rationale">Rationale</h2> <p>The optimized contract is constructed with essential components of the proxy contract and incorporates the recently added <code>PUSH0</code> opcode. The core elements of the minimal proxy include:</p> <ol> <li>Copy the calldata with <code>CALLDATACOPY</code>.</li> <li>Forward the calldata to the implementation contract using <code>DELEGATECALL</code>.</li> <li>Copy the returned data from the <code>DELEGATECALL</code>.</li> <li>Return the results or revert the transaction based on whether the <code>DELEGATECALL</code> is successful.</li> </ol> <h3 id="step-1-copy-the-calldata">Step 1: Copy the Calldata</h3> <p>To copy the calldata, we need to provide the arguments for the <code>CALLDATACOPY</code> opcodes, which are <code>[0, 0, cds]</code>, where <code>cds</code> represents calldata size.</p> <table><thead><tr><th>pc</th><th>op</th><th>opcode</th><th>stack</th></tr></thead><tbody> <tr><td>[00]</td><td>36</td><td>CALLDATASIZE</td><td>cds</td></tr> <tr><td>[01]</td><td>5f</td><td>PUSH0</td><td>0 cds</td></tr> <tr><td>[02]</td><td>5f</td><td>PUSH0</td><td>0 0 cds</td></tr> <tr><td>[03]</td><td>37</td><td>CALLDATACOPY</td><td></td></tr> </tbody></table> <h3 id="step-2-delegatecall">Step 2: Delegatecall</h3> <p>To forward the calldata to the delegate call, we need to prepare arguments for the <code>DELEGATECALL</code> opcodes, which are <code>[gas 0xbebe. 0 cds 0 0]</code>, where <code>gas</code> represents the remaining gas, <code>0xbebe.</code> represents the address of the implementation contract, and <code>suc</code> represents whether the delegatecall is successful.</p> <table><thead><tr><th>pc</th><th>op</th><th>opcode</th><th>stack</th></tr></thead><tbody> <tr><td>[04]</td><td>5f</td><td>PUSH0</td><td>0</td></tr> <tr><td>[05]</td><td>5f</td><td>PUSH0</td><td>0 0</td></tr> <tr><td>[06]</td><td>36</td><td>CALLDATASIZE</td><td>cds 0 0</td></tr> <tr><td>[07]</td><td>5f</td><td>PUSH0</td><td>0 cds 0 0</td></tr> <tr><td>[08]</td><td>73bebe.</td><td>PUSH20 0xbebe.</td><td>0xbebe. 0 cds 0 0</td></tr> <tr><td>[1d]</td><td>5a</td><td>GAS</td><td>gas 0xbebe. 0 cds 0 0</td></tr> <tr><td>[1e]</td><td>f4</td><td>DELEGATECALL</td><td>suc</td></tr> </tbody></table> <h3 id="step-3-copy-the-returned-data-from-the-delegatecall">Step 3: Copy the Returned Data from the <code>DELEGATECALL</code></h3> <p>To copy the returndata, we need to provide the arguments for the <code>RETURNDATACOPY</code> opcodes, which are <code>[0, 0, red]</code>, where <code>rds</code> represents size of returndata from the <code>DELEGATECALL</code>.</p> <table><thead><tr><th>pc</th><th>op</th><th>opcode</th><th>stack</th></tr></thead><tbody> <tr><td>[1f]</td><td>3d</td><td>RETURNDATASIZE</td><td>rds suc</td></tr> <tr><td>[20]</td><td>5f</td><td>PUSH0</td><td>0 rds suc</td></tr> <tr><td>[21]</td><td>5f</td><td>PUSH0</td><td>0 0 rds suc</td></tr> <tr><td>[22]</td><td>3e</td><td>RETURNDATACOPY</td><td>suc</td></tr> </tbody></table> <h3 id="step-4-return-or-revert">Step 4: Return or Revert</h3> <p>Lastly, we need to return the data or revert the transaction based on whether the <code>DELEGATECALL</code> is successful. There is no <code>if/else</code> in opcodes, so we need to use <code>JUMPI</code> and <code>JUMPDEST</code> instead. The arguments for <code>JUMPI</code> is <code>[0x2a, suc]</code>, where <code>0x2a</code> is the destination of the conditional jump.</p> <p>We also need to prepare the argument <code>[0, rds]</code> for <code>REVERT</code> and <code>RETURN</code> opcodes before the <code>JUMPI</code>, otherwise we have to prepare them twice. We cannot avoid the <code>SWAP</code> operation, because we can only get <code>rds</code> after the <code>DELEGATECALL</code>.</p> <table><thead><tr><th>pc</th><th>op</th><th>opcode</th><th>stack</th></tr></thead><tbody> <tr><td>[23]</td><td>5f</td><td>PUSH0</td><td>0 suc</td></tr> <tr><td>[24]</td><td>3d</td><td>RETURNDATASIZE</td><td>rds 0 suc</td></tr> <tr><td>[25]</td><td>91</td><td>SWAP2</td><td>suc 0 rds</td></tr> <tr><td>[26]</td><td>602a</td><td>PUSH1 0x2a</td><td>0x2a suc 0 rds</td></tr> <tr><td>[27]</td><td>57</td><td>JUMPI</td><td>0 rds</td></tr> <tr><td>[29]</td><td>fd</td><td>REVERT</td><td></td></tr> <tr><td>[2a]</td><td>5b</td><td>JUMPDEST</td><td>0 rds</td></tr> <tr><td>[2b]</td><td>f3</td><td>RETURN</td><td></td></tr> </tbody></table> <p>In the end, we arrived at the runtime code for Minimal Proxy Contract with <code>PUSH0</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>365f5f375f5f365f73bebebebebebebebebebebebebebebebebebebebe5af43d5f5f3e5f3d91602a57fd5bf3</span></span></code></pre> <p>The length of the runtime code is <code>44</code> bytes, which reduced <code>1</code> byte from the previous Minimal Proxy Contract. Moreover, it replaced the <code>RETURNDATASIZE</code> and <code>DUP</code> operations with <code>PUSH0</code>, which saves gas and increases the readability of the code. In summary, the new Minimal Proxy Contract reduces <code>200</code> gas at deployment and <code>5</code> gas at runtime, while remaining the same functionalities as the old one.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Because the new minimal proxy contract uses <code>PUSH0</code> opcode, it can only be deployed after the Shanghai Upgrade. It behaves the same as the previous Minimal Proxy Contract.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The new proxy contract standard is identical to the previous one (ERC-1167). Here are the security considerations when using minimal proxy contracts:</p> <ol> <li> <p><strong>Non-Upgradability</strong>: Minimal Proxy Contracts delegate their logic to another contract (often termed the "implementation" or "logic" contract). This delegation is fixed upon deployment, meaning you can't change which implementation contract the proxy delegates to after its creation.</p> </li> <li> <p><strong>Initialization Concerns</strong>: Proxy contracts lack constructors, so you need to use an initialization function after deployment. Skipping this step could leave the contract unsafe.</p> </li> <li> <p><strong>Safety of Logic Contract</strong>: Vulnerabilities in the logic contract affect all associated proxy contracts.</p> </li> <li> <p><strong>Transparency Issues</strong>: Because of its complexity, users might see the proxy as an empty contract, making it challenging to trace back to the actual logic contract.</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> 2023-09-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Elaine Zhanghttps://github.com/lanyinzlylz8aj@virginia.edu Jerryjerrymindflow@gmail.com Amandafannyamandafanny200@gmail.com Shouhao Wonghttps://github.com/wangshouhwongshouhao@outlook.com 0xPoet0xpoets@gmail.com https://wg-eips.ritovision.com/7527/

Interfaces that wrap FT to NFT and unwrap NFT to FT based on an embedded Function Oracle AMM

<h2 id="abstract">Abstract</h2> <p>This proposal outlines interfaces for wrapping <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> or ETH to <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and unwrap ERC-721 to ERC-20 or ETH. A function oracle feeds mint/burn prices based on an embedded equation of Function Oracle Automated Market Maker(FOAMM), which executes and clears the mint and burn of NFT.</p> <h2 id="motivation">Motivation</h2> <p>Liquidity can be a significant challenge in decentralized systems, especially for unique or less commonly traded tokens like NFTs. To foster a trustless NFT ecosystem, the motivation behind Function Oracle Automated Market Maker(FOAMM) is to provide automated pricing solutions for NFTs with liquidity through transparent, smart contract mechanisms.</p> <p>This ERC provides innovative solutions for the following aspects:</p> <ul> <li>Automated Price Discovery</li> <li>Liquidity Enhancement</li> </ul> <h3 id="automated-price-discovery">Automated Price Discovery</h3> <p>Transactions under FOAMM can occur without the need for a matching counterparty. When interacting directly with the pool, FOAMM automatically feeds prices based on the oracle with predefined function.</p> <h3 id="liquidity-enhancement">Liquidity Enhancement</h3> <p>In traditional DEX models, liquidity is supplied by external parties, known as Liquidity Providers(LP). These LPs deposit tokens into liquidity pools, facilitating exchanges by providing the liquidity. The removal or withdrawal of these LPs can introduce significant volatility, as it directly impacts the available liquidity in the market.</p> <p>In a FOAMM system, the liquidity is added or removed internally through <code>wrap</code> or <code>unwrap</code>. FOAMM reduces reliance on external LPs and mitigates the risk of volatility caused by their sudden withdrawal, as the liquidity is continuously replenished and maintained through ongoing participant interactions.</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>Contract Interfaces:</p> <p>Three interfaces are included here: <code>Agency</code>, <code>App</code>, and <code>Factory</code>.</p> <p><code>Agency</code> and <code>App</code> MAY be implemented by the same contract or MAY be separately implemented. If separately implemented, they SHALL be mutually bounded and not upgradable after initialization.</p> <p><code>Agency</code> and <code>App</code> should implement <code>iconstructor</code> interface to initialize the parameters within the contract and validate the configuration parameters. If factory is used to deploy <code>Agency</code> and <code>App</code>, factory will automatically call the two functions when deploying.</p> <p><code>App</code> SHALL implement <code>onlyAgency()</code> modifier and <code>mint</code> and <code>burn</code> SHALL apply <code>onlyAgency()</code> as a modifier, which restricts calls to <code>Mint</code> and <code>Burn</code> only have effect if they are called through the corresponding <code>Agency</code>.</p> <p><code>Agency</code> is OPTIONAL to implement <code>onlyApp()</code>.</p> <p>The <code>Factory</code> interface is OPTIONAL. It is most useful if <code>Agency</code> and <code>App</code> need to be deployed repeatedly.</p> <p>Function Oracle is implemented through <code>getWrapOracle</code> and <code>getUnwrapOracle</code>, which feeds prices based on parameters and mathematical equations defined in the functions.</p> <p>FOAMM is implemented through <code>wrap</code> and <code>unwrap</code>, which calls <code>getWrapOracle</code> and <code>getUnwrapOracle</code> to get the feed and automatically clears. To perform <code>wrap</code>, FOAMM receives the premium and initiate <code>mint</code> in <code>App</code>. To perform <code>unwrap</code>, FOAMM transfer the premium and initiate <code>burn</code> in <code>App</code>.</p> <p><code>Agency</code> serves as a single entry point for all <code>mint</code> and <code>burn</code> transfer.</p> <h3 id="agency-interface">Agency Interface</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pragma solidity ^0.8.20;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * @dev The settings of the agency.</span></span> <span class="giallo-l"><span> * @param currency The address of the currency. If `currency` is 0, the currency is Ether.</span></span> <span class="giallo-l"><span> * @param basePremium The base premium of the currency.</span></span> <span class="giallo-l"><span> * @param feeRecipient The address of the fee recipient.</span></span> <span class="giallo-l"><span> * @param mintFeePercent The fee of minting.</span></span> <span class="giallo-l"><span> * @param burnFeePercent The fee of burning.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>struct Asset {</span></span> <span class="giallo-l"><span> address currency;</span></span> <span class="giallo-l"><span> uint256 basePremium;</span></span> <span class="giallo-l"><span> address feeRecipient;</span></span> <span class="giallo-l"><span> uint16 mintFeePercent;</span></span> <span class="giallo-l"><span> uint16 burnFeePercent;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>interface IERC7527Agency {</span></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Allows the account to receive Ether</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * Accounts MUST implement a `receive` function.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * Accounts MAY perform arbitrary logic to restrict conditions</span></span> <span class="giallo-l"><span> * under which Ether can be received.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> receive() external payable;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Emitted when `tokenId` token is wrapped.</span></span> <span class="giallo-l"><span> * @param to The address of the recipient of the newly created non-fungible token.</span></span> <span class="giallo-l"><span> * @param tokenId The identifier of the newly created non-fungible token.</span></span> <span class="giallo-l"><span> * @param premium The premium of wrapping.</span></span> <span class="giallo-l"><span> * @param fee The fee of wrapping.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event Wrap(address indexed to, uint256 indexed tokenId, uint256 premium, uint256 fee);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Emitted when `tokenId` token is unwrapped.</span></span> <span class="giallo-l"><span> * @param to The address of the recipient of the currency.</span></span> <span class="giallo-l"><span> * @param tokenId The identifier of the non-fungible token to unwrap.</span></span> <span class="giallo-l"><span> * @param premium The premium of unwrapping.</span></span> <span class="giallo-l"><span> * @param fee The fee of unwrapping.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event Unwrap(address indexed to, uint256 indexed tokenId, uint256 premium, uint256 fee);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Constructor of the instance contract.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function iconstructor() external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Wrap some amount of currency into a non-fungible token.</span></span> <span class="giallo-l"><span> * @param to The address of the recipient of the newly created non-fungible token.</span></span> <span class="giallo-l"><span> * @param data The data to encode into ifself and the newly created non-fungible token.</span></span> <span class="giallo-l"><span> * @return The identifier of the newly created non-fungible token.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function wrap(address to, bytes calldata data) external payable returns (uint256);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Unwrap a non-fungible token into some amount of currency.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * Todo: event</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param to The address of the recipient of the currency.</span></span> <span class="giallo-l"><span> * @param tokenId The identifier of the non-fungible token to unwrap.</span></span> <span class="giallo-l"><span> * @param data The data to encode into ifself and the non-fungible token with identifier `tokenId`.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function unwrap(address to, uint256 tokenId, bytes calldata data) external payable;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Returns the strategy of the agency.</span></span> <span class="giallo-l"><span> * @return app The address of the app.</span></span> <span class="giallo-l"><span> * @return asset The asset of the agency.</span></span> <span class="giallo-l"><span> * @return attributeData The attributeData of the agency.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getStrategy() external view returns (address app, Asset memory asset, bytes memory attributeData);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Returns the premium and fee of wrapping.</span></span> <span class="giallo-l"><span> * @param data The data to encode to calculate the premium and fee of wrapping.</span></span> <span class="giallo-l"><span> * @return premium The premium of wrapping.</span></span> <span class="giallo-l"><span> * @return fee The fee of wrapping.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getWrapOracle(bytes memory data) external view returns (uint256 premium, uint256 fee);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Returns the premium and fee of unwrapping.</span></span> <span class="giallo-l"><span> * @param data The data to encode to calculate the premium and fee of unwrapping.</span></span> <span class="giallo-l"><span> * @return premium The premium of wrapping.</span></span> <span class="giallo-l"><span> * @return fee The fee of wrapping.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getUnwrapOracle(bytes memory data) external view returns (uint256 premium, uint256 fee);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev OPTIONAL - This method can be used to improve usability and clarity of Agency, but interfaces and other contracts MUST NOT expect these values to be present.</span></span> <span class="giallo-l"><span> * @return the description of the agency, such as how `getWrapOracle()` and `getUnwrapOracle()` are calculated.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function description() external view returns (string memory);</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="app-interface">App Interface</h3> <p><code>ERC7527App</code> SHALL inherit <code>name</code> from interface <code>ERC721Metadata</code>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pragma solidity ^0.8.20;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>interface IERC7527App {</span></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Returns the maximum supply of the non-fungible token.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getMaxSupply() external view returns (uint256);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Returns the name of the non-fungible token with identifier `id`.</span></span> <span class="giallo-l"><span> * @param id The identifier of the non-fungible token.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getName(uint256 id) external view returns (string memory);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Returns the agency of the non-fungible token.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getAgency() external view returns (address payable);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Constructor of the instance contract.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function iconstructor() external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Sets the agency of the non-fungible token.</span></span> <span class="giallo-l"><span> * @param agency The agency of the non-fungible token.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function setAgency(address payable agency) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Mints a non-fungible token to `to`.</span></span> <span class="giallo-l"><span> * @param to The address of the recipient of the newly created non-fungible token.</span></span> <span class="giallo-l"><span> * @param data The data to encode into the newly created non-fungible token.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function mint(address to, bytes calldata data) external returns (uint256);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Burns a non-fungible token with identifier `tokenId`.</span></span> <span class="giallo-l"><span> * @param tokenId The identifier of the non-fungible token to burn.</span></span> <span class="giallo-l"><span> * @param data The data to encode into the non-fungible token with identifier `tokenId`.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function burn(uint256 tokenId, bytes calldata data) external;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Token ID can be specified in <code>data</code> parameter of <code>mint</code> function.</p> <h3 id="factory-interface">Factory Interface</h3> <p>OPTIONAL - This interface can be used to deploy App and Agency, but interfaces and other contracts MUST NOT expect this interface to be present.</p> <p>If a factory is needed to deploy bounded App and Agency, the factory SHALL implement the following interface:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pragma solidity ^0.8.20;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>import {Asset} from &quot;./IERC7527Agency.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * @dev The settings of the agency.</span></span> <span class="giallo-l"><span> * @param implementation The address of the agency implementation.</span></span> <span class="giallo-l"><span> * @param asset The parameter of asset of the agency.</span></span> <span class="giallo-l"><span> * @param immutableData The immutable data are stored in the code region of the created proxy contract of agencyImplementation.</span></span> <span class="giallo-l"><span> * @param initData If init data is not empty, calls proxy contract of agencyImplementation with this data.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>struct AgencySettings {</span></span> <span class="giallo-l"><span> address payable implementation;</span></span> <span class="giallo-l"><span> Asset asset;</span></span> <span class="giallo-l"><span> bytes immutableData;</span></span> <span class="giallo-l"><span> bytes initData;</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> * @dev The settings of the app.</span></span> <span class="giallo-l"><span> * @param implementation The address of the app implementation.</span></span> <span class="giallo-l"><span> * @param immutableData The immutable data are stored in the code region of the created proxy contract of appImplementation.</span></span> <span class="giallo-l"><span> * @param initData If init data is not empty, calls proxy contract of appImplementation with this data.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>struct AppSettings {</span></span> <span class="giallo-l"><span> address implementation;</span></span> <span class="giallo-l"><span> bytes immutableData;</span></span> <span class="giallo-l"><span> bytes initData;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>interface IERC7527Factory {</span></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Deploys a new agency and app clone and initializes both.</span></span> <span class="giallo-l"><span> * @param agencySettings The settings of the agency.</span></span> <span class="giallo-l"><span> * @param appSettings The settings of the app.</span></span> <span class="giallo-l"><span> * @param data The data is additional data, it has no specified format and it is sent in call to `factory`.</span></span> <span class="giallo-l"><span> * @return appInstance The address of the created proxy contract of appImplementation.</span></span> <span class="giallo-l"><span> * @return agencyInstance The address of the created proxy contract of agencyImplementation.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function deployWrap(AgencySettings calldata agencySettings, AppSettings calldata appSettings, bytes calldata data)</span></span> <span class="giallo-l"><span> external</span></span> <span class="giallo-l"><span> returns (address, address);</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="prior-interfaces">Prior Interfaces</h3> <p><a href="https://wg-eips.ritovision.com/5679/">ERC-5679</a> proposed <code>IERC5679Ext721</code> interface for introducing a consistent way to extend <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> token standards for minting and burning. To ensure the backward compatibility, considering some contracts which do not implement <code>ERC721TokenReceiver</code>, <code>IERC7527App</code> employ <code>mint</code> function instead of <code>safeMint</code>. To ensure the safety and the uniqueness of mutual bound, the <code>_from</code> parameter of the <code>burn</code> function in <code>IERC5679Ext721</code> must be the contract address of the bounded agency. Thus, <code>burn</code> function in <code>IERC7527App</code> does not contain the <code>_from</code> parameter.</p> <h3 id="mutual-bound">Mutual Bound</h3> <p>Implement contracts for <code>IERC7527App</code> and <code>IERC7527Agency</code> so that they are each other's only owner. The wrap process is to check the premium amount of the fungible token received and then mint non-fungible token in the App. Only the owner or an approver of the non-fungible token can unwrap it.</p> <h3 id="implementation-diversity">Implementation Diversity</h3> <p>Users can customize function and fee percentage when implement the Agency and the App interfaces.</p> <p>Different Agency implementations have distinct wrap, unwrap function logic, and different oracleFunction. Users can customize the currency, initial price, fee receiving address, fee rate, etc., to initialize the Agency contract.</p> <p>Different App implementations cater to various use cases. Users can initialize the App contract.</p> <p>Factory is not required. Factory implementation is need-based. Users can deploy their own contracts by selecting different Agency implementations and different App implementations through the Factory, combining them to create various products.</p> <h3 id="currency-types">Currency types</h3> <p><code>currency</code> in <code>IERC7527Agency</code> is the address of fungible token. <code>Asset</code> can only define one type of <code>currency</code> as the fungible token in the system. <code>currency</code> supports various kinds of fungible tokens including ETH and <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>.</p> <h3 id="token-id">Token id</h3> <p>For each wrap process, a unique <code>tokenId</code> should be generated. This <code>tokenId</code> is essential for verification during the unwrap process. It also serves as the exclusive credential for the token. This mechanism ensures the security of assets in contracts.</p> <h3 id="wrap-and-mint">Wrap and Mint</h3> <p>The <code>strategy</code> is set while implementing the Agency interface, and it should be ensured not upgradable once deployed.</p> <p>When executing the <code>wrap</code> function, the predetermined strategy parameters are passed into the <code>getWrapOracle</code> function to fetch the current premium and fee. The respective premium is then transferred to the Agency instance; the fee, according to <code>mintFeePercent</code> is transferred to <code>feeRecipient</code>. Subsequently, the App mints the NFT to the user's address.</p> <p>Premium(tokens) transferred into the Agency cannot be moved, except through the unwrap process. The act of executing wrap is the sole trigger for the mint process.</p> <h3 id="unwrap-and-burn">Unwrap and Burn</h3> <p>When executing the <code>unwrap</code> function, predetermined strategy parameters are passed into the <code>getUnwrapOracle</code> function to read the current premium and fee. The App burns the NFT. Then, the corresponding premium, subtracting the fee according to <code>burnFeePercent</code>, is then transferred to the user's address; the fee is transferred to <code>feeRecipient</code>. The act of executing 'unwrap' is the sole trigger for the 'burn' process.</p> <h3 id="two-interfaces-use-together">Two interfaces use together</h3> <p><code>IERC7527App</code> and <code>IERC7527Agency</code> can be implemented together for safety, but they can be independently implemented before initialization for flexibiliy.</p> <h3 id="pricing">Pricing</h3> <p><code>getWrapOracle</code> and <code>getUnwrapOracle</code> are used to fetch the current premium and fee. They implement on-chain price fetching through oracle functions. They not only support fetching the premium and fee during the wrap and unwrap processes but also support other contracts calling them to obtain the premium and fee, such as lending contracts.</p> <p>They can support function oracle based on on-chain and off-chain parameters, but on-chain parameters are suggested only for consensus of on-chain reality.</p> <h3 id="initdata-and-iconstructor"><code>initData</code> and <code>iconstructor</code></h3> <p>During the deployment of <code>App</code> and <code>Agency</code> by the Factory, the Factory uses <code>initData</code> as Calldata to call the <code>Agency</code> and <code>App</code> contracts and also invokes the <code>iconstructor</code> functions within <code>App</code> and <code>Agency</code>.</p> <p>The initData is mainly used to call the parameterized initialization functions, while <code>iconstructor</code> is often used to validate configuration parameters and non-parameterized initialization functions.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pragma solidity ^0.8.20;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>import {</span></span> <span class="giallo-l"><span> ERC721Enumerable,</span></span> <span class="giallo-l"><span> ERC721,</span></span> <span class="giallo-l"><span> IERC721Enumerable</span></span> <span class="giallo-l"><span>} from &quot;@openzeppelin/contracts/token/ERC721/extensions/ERC721Enumerable.sol&quot;;</span></span> <span class="giallo-l"><span>import {IERC20} from &quot;@openzeppelin/contracts/token/ERC20/IERC20.sol&quot;;</span></span> <span class="giallo-l"><span>import {Address} from &quot;@openzeppelin/contracts/utils/Address.sol&quot;;</span></span> <span class="giallo-l"><span>import {ClonesWithImmutableArgs} from &quot;clones-with-immutable-args/ClonesWithImmutableArgs.sol&quot;;</span></span> <span class="giallo-l"><span>import {IERC7527App} from &quot;./interfaces/IERC7527App.sol&quot;;</span></span> <span class="giallo-l"><span>import {IERC7527Agency, Asset} from &quot;./interfaces/IERC7527Agency.sol&quot;;</span></span> <span class="giallo-l"><span>import {IERC7527Factory, AgencySettings, AppSettings} from &quot;./interfaces/IERC7527Factory.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>contract ERC7527Agency is IERC7527Agency {</span></span> <span class="giallo-l"><span> using Address for address payable;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> receive() external payable {}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function iconstructor() external override pure {</span></span> <span class="giallo-l"><span> (, Asset memory _asset,) = getStrategy();</span></span> <span class="giallo-l"><span> require(_asset.basePremium != 0, &quot;LnModule: zero basePremium&quot;);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function unwrap(address to, uint256 tokenId, bytes calldata data) external payable override {</span></span> <span class="giallo-l"><span> (address _app, Asset memory _asset,) = getStrategy();</span></span> <span class="giallo-l"><span> require(_isApprovedOrOwner(_app, msg.sender, tokenId), &quot;LnModule: not owner&quot;);</span></span> <span class="giallo-l"><span> IERC7527App(_app).burn(tokenId, data);</span></span> <span class="giallo-l"><span> uint256 _sold = IERC721Enumerable(_app).totalSupply();</span></span> <span class="giallo-l"><span> (uint256 premium, uint256 burnFee) = getUnwrapOracle(abi.encode(_sold));</span></span> <span class="giallo-l"><span> _transfer(address(0), payable(to), premium - burnFee);</span></span> <span class="giallo-l"><span> _transfer(address(0), _asset.feeRecipient, burnFee);</span></span> <span class="giallo-l"><span> emit Unwrap(to, tokenId, premium, burnFee);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function wrap(address to, bytes calldata data) external payable override returns (uint256) {</span></span> <span class="giallo-l"><span> (address _app, Asset memory _asset,) = getStrategy();</span></span> <span class="giallo-l"><span> uint256 _sold = IERC721Enumerable(_app).totalSupply();</span></span> <span class="giallo-l"><span> (uint256 premium, uint256 mintFee) = getWrapOracle(abi.encode(_sold));</span></span> <span class="giallo-l"><span> require(msg.value &gt;= premium + mintFee, &quot;ERC7527Agency: insufficient funds&quot;);</span></span> <span class="giallo-l"><span> _transfer(address(0), _asset.feeRecipient, mintFee);</span></span> <span class="giallo-l"><span> if (msg.value &gt; premium + mintFee) {</span></span> <span class="giallo-l"><span> _transfer(address(0), payable(msg.sender), msg.value - premium - mintFee);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> uint256 id_ = IERC7527App(_app).mint(to, data);</span></span> <span class="giallo-l"><span> require(_sold + 1 == IERC721Enumerable(_app).totalSupply(), &quot;ERC7527Agency: Reentrancy&quot;);</span></span> <span class="giallo-l"><span> emit Wrap(to, id_, premium, mintFee);</span></span> <span class="giallo-l"><span> return id_;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function getStrategy() public pure override returns (address app, Asset memory asset, bytes memory attributeData) {</span></span> <span class="giallo-l"><span> uint256 offset = _getImmutableArgsOffset();</span></span> <span class="giallo-l"><span> address currency;</span></span> <span class="giallo-l"><span> uint256 basePremium;</span></span> <span class="giallo-l"><span> address payable feeRecipient;</span></span> <span class="giallo-l"><span> uint16 mintFeePercent;</span></span> <span class="giallo-l"><span> uint16 burnFeePercent;</span></span> <span class="giallo-l"><span> assembly {</span></span> <span class="giallo-l"><span> app := shr(0x60, calldataload(add(offset, 0)))</span></span> <span class="giallo-l"><span> currency := shr(0x60, calldataload(add(offset, 20)))</span></span> <span class="giallo-l"><span> basePremium := calldataload(add(offset, 40))</span></span> <span class="giallo-l"><span> feeRecipient := shr(0x60, calldataload(add(offset, 72)))</span></span> <span class="giallo-l"><span> mintFeePercent := shr(0xf0, calldataload(add(offset, 92)))</span></span> <span class="giallo-l"><span> burnFeePercent := shr(0xf0, calldataload(add(offset, 94)))</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> asset = Asset(currency, basePremium, feeRecipient, mintFeePercent, burnFeePercent);</span></span> <span class="giallo-l"><span> attributeData = &quot;&quot;;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function getUnwrapOracle(bytes memory data) public pure override returns (uint256 premium, uint256 fee) {</span></span> <span class="giallo-l"><span> uint256 input = abi.decode(data, (uint256));</span></span> <span class="giallo-l"><span> (, Asset memory _asset,) = getStrategy();</span></span> <span class="giallo-l"><span> premium = _asset.basePremium + input * _asset.basePremium / 100;</span></span> <span class="giallo-l"><span> fee = premium * _asset.burnFeePercent / 10000;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function getWrapOracle(bytes memory data) public pure override returns (uint256 premium, uint256 fee) {</span></span> <span class="giallo-l"><span> uint256 input = abi.decode(data, (uint256));</span></span> <span class="giallo-l"><span> (, Asset memory _asset,) = getStrategy();</span></span> <span class="giallo-l"><span> premium = _asset.basePremium + input * _asset.basePremium / 100;</span></span> <span class="giallo-l"><span> fee = premium * _asset.mintFeePercent / 10000;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function _transfer(address currency, address recipient, uint256 premium) internal {</span></span> <span class="giallo-l"><span> if (currency == address(0)) {</span></span> <span class="giallo-l"><span> payable(recipient).sendValue(premium);</span></span> <span class="giallo-l"><span> } else {</span></span> <span class="giallo-l"><span> IERC20(currency).transfer(recipient, premium);</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 _isApprovedOrOwner(address app, address spender, uint256 tokenId) internal view virtual returns (bool) {</span></span> <span class="giallo-l"><span> IERC721Enumerable _app = IERC721Enumerable(app);</span></span> <span class="giallo-l"><span> address _owner = _app.ownerOf(tokenId);</span></span> <span class="giallo-l"><span> return (spender == _owner || _app.isApprovedForAll(_owner, spender) || _app.getApproved(tokenId) == spender);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> /// @return offset The offset of the packed immutable args in calldata</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function _getImmutableArgsOffset() internal pure returns (uint256 offset) {</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> offset := sub(calldatasize(), add(shr(240, calldataload(sub(calldatasize(), 2))), 2))</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>contract ERC7527App is ERC721Enumerable, IERC7527App {</span></span> <span class="giallo-l"><span> constructor() ERC721(&quot;ERC7527App&quot;, &quot;EA&quot;) {}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> address payable private _oracle;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> modifier onlyAgency() {</span></span> <span class="giallo-l"><span> require(msg.sender == _getAgency(), &quot;only agency&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 iconstructor() external {}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function getName(uint256) external pure returns (string memory) {</span></span> <span class="giallo-l"><span> return &quot;App&quot;;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function getMaxSupply() public pure override returns (uint256) {</span></span> <span class="giallo-l"><span> return 100;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function getAgency() external view override returns (address payable) {</span></span> <span class="giallo-l"><span> return _getAgency();</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function setAgency(address payable oracle) external override {</span></span> <span class="giallo-l"><span> require(_getAgency() == address(0), &quot;already set&quot;);</span></span> <span class="giallo-l"><span> _oracle = oracle;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function mint(address to, bytes calldata data) external override onlyAgency returns (uint256 tokenId) {</span></span> <span class="giallo-l"><span> require(totalSupply() &lt; getMaxSupply(), &quot;max supply reached&quot;);</span></span> <span class="giallo-l"><span> tokenId = abi.decode(data, (uint256));</span></span> <span class="giallo-l"><span> _mint(to, tokenId);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function burn(uint256 tokenId, bytes calldata) external override onlyAgency {</span></span> <span class="giallo-l"><span> _burn(tokenId);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function _getAgency() internal view returns (address payable) {</span></span> <span class="giallo-l"><span> return _oracle;</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>contract ERC7527Factory is IERC7527Factory {</span></span> <span class="giallo-l"><span> using ClonesWithImmutableArgs for address;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function deployWrap(AgencySettings calldata agencySettings, AppSettings calldata appSettings, bytes calldata)</span></span> <span class="giallo-l"><span> external</span></span> <span class="giallo-l"><span> override</span></span> <span class="giallo-l"><span> returns (address appInstance, address agencyInstance)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> appInstance = appSettings.implementation.clone(appSettings.immutableData);</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> agencyInstance = address(agencySettings.implementation).clone(</span></span> <span class="giallo-l"><span> abi.encodePacked(</span></span> <span class="giallo-l"><span> appInstance,</span></span> <span class="giallo-l"><span> agencySettings.asset.currency,</span></span> <span class="giallo-l"><span> agencySettings.asset.basePremium,</span></span> <span class="giallo-l"><span> agencySettings.asset.feeRecipient,</span></span> <span class="giallo-l"><span> agencySettings.asset.mintFeePercent,</span></span> <span class="giallo-l"><span> agencySettings.asset.burnFeePercent,</span></span> <span class="giallo-l"><span> agencySettings.immutableData</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> IERC7527App(appInstance).setAgency(payable(agencyInstance));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> IERC7527Agency(payable(agencyInstance)).iconstructor();</span></span> <span class="giallo-l"><span> IERC7527App(appInstance).iconstructor();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if (agencySettings.initData.length != 0) {</span></span> <span class="giallo-l"><span> (bool success, bytes memory result) = agencyInstance.call(agencySettings.initData);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if (!success) {</span></span> <span class="giallo-l"><span> assembly {</span></span> <span class="giallo-l"><span> revert(add(result, 32), mload(result))</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> if (appSettings.initData.length != 0) {</span></span> <span class="giallo-l"><span> (bool success, bytes memory result) = appInstance.call(appSettings.initData);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if (!success) {</span></span> <span class="giallo-l"><span> assembly {</span></span> <span class="giallo-l"><span> revert(add(result, 32), mload(result))</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><h2 id="security-considerations">Security Considerations</h2> <h3 id="fraud-prevention">Fraud Prevention</h3> <p>Consider the following for the safety of the contracts:</p> <ul> <li> <p>Check whether modifiers <code>onlyAgency()</code> and <code>onlyApp()</code> are proporly implemented and applied.</p> </li> <li> <p>Check the function strategies.</p> </li> <li> <p>Check whether the contracts can be subject to re-entrancy attack.</p> </li> <li> <p>Check whether all non-fungible tokens can be unwrapped with the premium calculated from FOAMM.</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> 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-09-01T00:00:00+00:00 2026-02-11T14:48:26+00:00 Yoav Weisshttps://github.com/yoavw Dror Tiroshhttps://github.com/drortirosh Alex Forshtathttps://github.com/forshtat Shahaf Nacsonhttps://github.com/shahafn https://wg-eips.ritovision.com/7562/

A set of limitations on validation EVM code to protect Account Abstraction nodes from denial-of-service attacks through unpaid computation.

<h2 id="abstract">Abstract</h2> <p>This document describes the rules Account Abstraction protocols should follow, during the validation phase of Account Abstraction transactions, such as <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> <code>UserOperation</code> or RIP-7560 (Native Account Abstraction), which are enforced off-chain by a block builder or a standalone bundler, and the rationale behind each one of them.</p> <h2 id="motivation">Motivation</h2> <p>With Account-Abstraction, instead of hard-coded logic for processing a transaction (validation, gas-payment, and execution), this logic is executed by EVM code. The benefits for the account are countless -</p> <ul> <li>abstracting the validation allows the contract to use different signature schemes, multisig configuration, custom recovery, and more.</li> <li>abstracting gas payments allows easy onboarding by 3rd party payments, paying with tokens, cross-chain gas payments</li> <li>abstracting execution allows batch transactions</li> </ul> <p>All of the above are missing from the EOA account model.</p> <p>However, there is one rule a transaction must follow to preserve the decentralized network: once submitted into the network (the mempool), the transaction is guaranteed to pay. This comes to prevent denial-of-service attacks on the network.</p> <p>The EOA model implicitly follows the rule: a valid transaction can't become invalid without payment by the account: e.g. account balance can't be reduced (except with a higher paying transaction)</p> <p>This rule makes the network sustainable and DoS-protected: the network can't be cheaply attacked by a mass of transactions. An attack (sending a mass of transactions) is expensive, and gets more expensive as the network clogs. Legitimate users pay more, and can delay operations to avoid the cost, but the attacker pays a huge (and increasing) amount to keep the network clogged.</p> <p>To mimic the same incentive structure in any Account Abstraction system, we suggest the following transaction validation rules. These validation rules only apply to the validation phase of Account Abstraction transactions, not their entire executed code path.</p> <p>For the actual interfaces of those contract-based accounts see the definitions in ERC-4337 and RIP-7560.</p> <p>This documentation uses the terminology "UserOperation" for a transaction created by a smart contract account, and closely follows <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> terminology. However, the rules apply to any Account Abstraction framework that uses EVM code to perform transaction validation and makes a distinction between validation (whether the operation is eligible for inclusion on the protocol level) and execution (on-chain execution and gas payment) in a public mempool.</p> <h2 id="specification">Specification</h2> <h3 id="validation-rules-types">Validation Rules Types</h3> <p>We define two types of validation rules: <strong>network-wide rules</strong> and <strong>local rules</strong>.</p> <p>A violation of any validation rule by a UserOperation results in the UserOperation being dropped from the mempool and excluded from a bundle.</p> <p><strong>Network-wide rule</strong> is a rule, that its violation by a UserOperation validation should result in a reputation damage for the peer bundler that sent this UserOperation in the p2p mempool. A peer bundler with a critically low reputation will eventually be marked as a malicious <strong>spammer</strong> peer.</p> <p><strong>Local rule</strong> is a rule that is enforced in the context of each bundler's local state, which may be different for each bundler and different bundlers may not always be in agreement on these rules' violations. Thus, The bundler that sent the violating UserOperation should not suffer a p2p reputation damage by its peers.</p> <h3 id="constants">Constants</h3> <table><thead><tr><th>Title</th><th>Value</th><th>Comment</th></tr></thead><tbody> <tr><td><code>MIN_UNSTAKE_DELAY</code></td><td>86400</td><td>1 day, which provides a sufficient withdrawal delay to prevent most sybil attacks</td></tr> <tr><td><code>MIN_STAKE_VALUE</code></td><td>Adjustable per chain value</td><td>Equivalent to ~$1000 in native tokens, which provides a sufficient capital requirement to prevent most sybil attacks</td></tr> <tr><td><code>SAME_SENDER_MEMPOOL_COUNT</code></td><td>4</td><td>Maximum number of allowed userops in the mempool from a single sender.</td></tr> <tr><td><code>SAME_UNSTAKED_ENTITY_MEMPOOL_COUNT</code></td><td>10</td><td>Maximum number allowed in the mempool of UserOperations referencing the same unstaked entity</td></tr> <tr><td><code>THROTTLED_ENTITY_MEMPOOL_COUNT</code></td><td>4</td><td>Number of <code>UserOperations</code> with a throttled entity that can stay in the mempool</td></tr> <tr><td><code>THROTTLED_ENTITY_LIVE_BLOCKS</code></td><td>10</td><td>Number of blocks a <code>UserOperations</code> with a throttled entity can stay in mempool</td></tr> <tr><td><code>THROTTLED_ENTITY_BUNDLE_COUNT</code></td><td>4</td><td>Number of <code>UserOperations</code> with a throttled entity that can be added in a single bundle</td></tr> <tr><td><code>MIN_INCLUSION_RATE_DENOMINATOR</code></td><td>100 (client) \ 10 (bundler)</td><td>A denominator of a formula for entity reputation calculation</td></tr> <tr><td><code>THROTTLING_SLACK</code></td><td>10</td><td>Part of a reputation formula that allows entities to legitimately reject some transactions without being throttled</td></tr> <tr><td><code>BAN_SLACK</code></td><td>50</td><td>Part of a reputation formula that allows throttled entities to reject some transactions without being throttled</td></tr> <tr><td><code>BAN_OPS_SEEN_PENALTY</code></td><td>10000</td><td>A value to put into the opsSeen counter of entity to declare as banned</td></tr> <tr><td><code>MAX_OPS_ALLOWED_UNSTAKED_ENTITY</code></td><td>10000</td><td></td></tr> <tr><td><code>PRE_VERIFICATION_OVERHEAD_GAS</code></td><td>50000</td><td>Gas used by the <code>EntryPoint</code> per <code>UserOp</code> that cannot be tracked on-chain</td></tr> <tr><td><code>MAX_VERIFICATION_GAS</code></td><td>500000</td><td>Maximum gas verification functions may use</td></tr> <tr><td><code>MAX_USEROP_SIZE</code></td><td>8192</td><td>Maximum size of a single packed and ABI-encoded <code>UserOperation</code> in bytes</td></tr> <tr><td><code>MAX_CONTEXT_SIZE</code></td><td>2048</td><td>Maximum size of a <code>context</code> byte array returned by a paymaster in a single <code>UserOperation</code> in bytes</td></tr> <tr><td><code>MAX_BUNDLE_SIZE</code></td><td>262144</td><td>Maximum size of an ABI-encoded bundle call to the <code>handleOps</code> function in bytes</td></tr> <tr><td><code>MAX_BUNDLE_CONTEXT_SIZE</code></td><td>65536</td><td>Maximum total size of all <code>context</code> byte arrays returned by all paymasters in all <code>UserOperations</code> in a bundle in bytes</td></tr> <tr><td><code>VALIDATION_GAS_SLACK</code></td><td>4000</td><td>An amount of gas that must be added to the estimations of <code>verificationGasLimit</code> and <code>paymasterVerificationGasLimit</code></td></tr> </tbody></table> <h3 id="validation-rules">Validation Rules</h3> <h3 id="definitions"><strong>Definitions</strong>:</h3> <ol> <li> <p><strong>Validation Phase</strong>: there are up to three frames during the validation phase onchain</p> <ol> <li><code>sender</code> deployment frame (once per account)</li> <li><code>sender</code> validation (required)</li> <li><code>paymaster</code> validation frame (optional)</li> </ol> </li> <li> <p><strong>Execution Phase</strong>: there are up to two frames during the execution phase onchain</p> <ol> <li><code>sender</code> execution frame (required)</li> <li><code>paymaster</code> post-transaction frame (optional) The validation rules only apply during the validation phase. Once a UserOperation is validated, it is guaranteed to pay. There are no restrictions on execution, neither account (callData) nor paymaster (postOp)</li> </ol> </li> <li> <p><strong>Entity</strong>: a contract that is explicitly specified by the <code>UserOperation</code>. Includes the <code>factory</code>, <code>paymaster</code>, <code>aggregator</code>, and staked <code>account</code>, as discussed below.<br /> Each "validation frame" is attributed to a single entity.<br /> Entity contracts must have non-empty code on-chain.</p> </li> <li> <p><strong>Canonical Mempool</strong>: The rules defined in this document apply to the main mempool shared by all bundlers on the network.</p> </li> <li> <p><strong>Staked Entity:</strong> an entity that has a locked stake of at least <code>MIN_STAKE_VALUE</code> and an unstake delay of at least <code>MIN_UNSTAKE_DELAY</code>.</p> </li> <li> <p><strong>Associated storage:</strong> a storage slot of any smart contract is considered to be "associated" with address <code>A</code> if:</p> <ol> <li>The slot value is <code>A</code></li> <li>The slot value was calculated as <code>keccak(A||x)+n</code>, where <code>x</code> is a <code>bytes32</code> value, and <code>n</code> is a value in the range 0..128</li> </ol> </li> <li> <p><strong>Using an address</strong>: accessing the code of a given address in any way. This can be done by executing <code>*CALL</code> or <code>EXTCODE*</code> opcodes for a given address.</p> </li> <li> <p><strong>Spammer</strong> - a P2P peer bundler that attempts a DoS attack on the mempool by sending other peers with a large number of invalid UserOperations. Bundlers MUST detect and disconnect from such peers, as described in the <a href="https://wg-eips.ritovision.com/7562/#mempool-validation-rules">Mempool Validation Rules</a> section.</p> </li> </ol> <h3 id="reputation-definitions">Reputation Definitions</h3> <ol> <li> <p><strong>opsSeen</strong>: a per-entity counter of how many times a unique valid <code>UserOperation</code> referencing this entity was received by this bundler. This includes <code>UserOperation</code> received via incoming RPC calls or through a P2P mempool protocol.</p> </li> <li> <p><strong>opsIncluded</strong>: a per-entity counter of how many times a unique valid <code>UserOperation</code> referencing this entity appeared in an actual included <code>UserOperation</code>.<br /> Calculation of this value is based on UserOperationEvents and is only counted for <code>UserOperations</code> that were previously counted as <code>opsSeen</code> by this bundler.</p> </li> <li> <p><strong>Refresh rate</strong>: Both of the above values are updated every hour as <code>value = value * 23 // 24</code><br /> Effectively, the value is reduced to 1% after 4 days.</p> </li> <li> <p><strong>inclusionRate</strong>: Ratio of <code>opsIncluded</code> to <code>opsSeen</code></p> </li> </ol> <h3 id="reputation-calculation">Reputation Calculation</h3> <p>We define a value <code>max_seen = opsSeen // MIN_INCLUSION_RATE_DENOMINATOR</code>.</p> <p>The reputation state of each entity is determined as follows:</p> <ol> <li><strong>BANNED</strong>: <code>max_seen &gt; opsIncluded + BAN_SLACK</code></li> <li><strong>THROTTLED</strong>: <code>max_seen &gt; opsIncluded + THROTTLING_SLACK</code></li> <li><strong>OK</strong>: otherwise</li> </ol> <p>Note that new entities start with an <code>OK</code> reputation.</p> <p>Because of the reputation <code>refresh rate</code>, note that a malicious paymaster can at most cause the network (only the p2p network, not the blockchain) to process <code>BAN_SLACK * MIN_INCLUSION_RATE_DENOMINATOR / 24</code> non-paying ops per hour.</p> <h3 id="running-the-validation-rules">Running the Validation Rules</h3> <ol> <li>A block builder or a bundler should perform a full validation once before accepting a <code>UserOperation</code> into its mempool, and again before including it in a bundle/block.</li> <li>The bundler should trace the validation phase of the UserOperation and apply all the rules defined in this document.</li> <li>A bundler should also perform a full validation of the entire bundle before submission.</li> <li>The validation rules prevent an unstaked entity from altering its behavior between simulation and execution of the UserOperation. However, a malicious staked entity can detect that it is running in a bundle validation and cause a revert. Thus, a third tracing simulation of the entire bundle should be performed before submission.</li> <li>The failed <code>UserOperation</code> should be dropped from the bundle.</li> <li>The bundler should update the reputation of the staked entity that violated the rules, and consider it <code>THROTTLED</code>/<code>BANNED</code> as described below.</li> </ol> <h3 id="mempool-validation-rules">Mempool Validation Rules</h3> <ol> <li>A <code>UserOperation</code> is broadcast over the P2P protocol with the following information: <ol> <li>The <code>UserOperation</code> itself</li> <li>The blockhash this <code>UserOperation</code> was originally verified against.</li> </ol> </li> <li>Once a <code>UserOperation</code> is received from another bundler it should be verified locally by a receiving bundler.</li> <li>A received <code>UserOperation</code> may fail any of the reasonable static checks, such as: invalid format, values below minimum, submitted with a blockhash that isn't recent, etc. In this case, the bundler should drop this particular <code>UserOperation</code> but keep the connection.</li> <li>The bundler should check the <code>UserOperation</code> against the nonces of last-included bundles and silently drop <code>UserOperations</code> with <code>nonce</code> that was recently included. This invalidation is likely attributable to a network race condition and should not cause a reputation change.</li> <li>If a received <code>UserOperation</code> fails against the current block: <ol> <li>Retry the validation against the block the <code>UserOperation</code> was originally verified against.</li> <li>If it succeeds, silently drop the <code>UserOperation</code> and keep the connection.</li> <li>If it fails, mark the sender as a "spammer" (disconnect from that peer and block it permanently).</li> </ol> </li> </ol> <h3 id="opcode-rules">Opcode Rules</h3> <ul> <li>Block access from opcodes that access information outside of storage and code (aka "environment"). <ul> <li><strong>[OP-011]</strong> Blocked opcodes: <ul> <li><code>ORIGIN</code> (<code>0x32</code>)</li> <li><code>GASPRICE</code> (<code>0x3A</code>)</li> <li><code>BLOCKHASH</code> (<code>0x40</code>)</li> <li><code>COINBASE</code> (<code>0x41</code>)</li> <li><code>TIMESTAMP</code> (<code>0x42</code>)</li> <li><code>NUMBER</code> (<code>0x43</code>)</li> <li><code>PREVRANDAO</code>/<code>DIFFICULTY</code> (<code>0x44</code>)</li> <li><code>GASLIMIT</code> (<code>0x45</code>)</li> <li><code>BASEFEE</code> (<code>0x48</code>)</li> <li><code>BLOBHASH</code> (<code>0x49</code>)</li> <li><code>BLOBBASEFEE</code> (<code>0x4A</code>)</li> <li><code>CREATE</code> (<code>0xF0</code>) (except in the "Contract Creation" and "Staked factory creation" sections, below)</li> <li><code>INVALID</code> (<code>0xFE</code>)</li> <li><code>SELFDESTRUCT</code> (<code>0xFF</code>)</li> </ul> </li> <li><strong>[OP-012]</strong> <code>GAS</code> (<code>0x5A</code>) opcode is allowed, but only if followed immediately by <code>*CALL</code> instructions, else it is blocked.<br /> This is a common way to pass all remaining gas to an external call, and it means that the actual value is consumed from the stack immediately and cannot be accessed by any other opcode.</li> <li><strong>[OP-13]</strong> any "unassigned" opcode.</li> </ul> </li> <li><strong>[OP-020]</strong> Revert on "out of gas" is forbidden as it can "leak" the gas limit or the current call stack depth.</li> <li>Contract creation: <ul> <li><strong>[OP-031]</strong> <code>CREATE2</code> is allowed exactly once in the deployment frame and must deploy code for the "sender" address. (Either by the factory itself, or by a utility contract it calls)</li> <li><strong>[OP-032]</strong> If there is a <code>factory</code> (even unstaked), the <code>sender</code> contract is allowed to use <code>CREATE</code> opcode (That is, only the sender contract itself, not through utility contract)</li> </ul> </li> <li>Access to an address without a deployed code is forbidden: <ul> <li><strong>[OP-041]</strong> For <code>EXTCODE*</code> and <code>*CALL</code> opcodes.</li> <li><strong>[OP-042]</strong> Exception: access to the "sender" address is allowed. This is only possible in <code>factory</code> code during the deployment frame.</li> </ul> </li> <li>Allowed access to the <code>EntryPoint</code> address: <ul> <li><strong>[OP-051]</strong> May call <code>EXTCODESIZE ISZERO</code><br /> This pattern is used to check destination has a code before the <code>depositTo</code> function is called.</li> <li><strong>[OP-052]</strong> May call <code>depositTo(sender)</code> with any value from either the <code>sender</code> or <code>factory</code>.</li> <li><strong>[OP-053]</strong> May call the fallback function from the <code>sender</code> with any value.</li> <li><strong>[OP-054]</strong> Any other access to the <code>EntryPoint</code> (either of the <code>*CALL</code> or <code>EXT*</code> opcodes) is forbidden.</li> <li><strong>[OP-055]</strong> May call <code>incrementNonce())</code> from the <code>sender</code></li> </ul> </li> <li><code>*CALL</code> opcodes: <ul> <li><strong>[OP-061]</strong> <code>CALL</code> with <code>value</code> is forbidden. The only exception is a call to the <code>EntryPoint</code> described above.</li> <li><strong>[OP-062]</strong> Precompiles: <ul> <li>Only allow known accepted precompiles on the network, that do not access anything in the blockchain state or environment.</li> <li>The core precompiles 0x1 .. 0x11</li> <li>The RIP-7212 secp256r1 precompile, on networks that accepted it.</li> </ul> </li> </ul> </li> <li><strong>[OP-070]</strong> Transient Storage slots defined in <a href="https://wg-eips.ritovision.com/1153/">EIP-1153</a> and accessed using <code>TLOAD</code> (<code>0x5c</code>) and <code>TSTORE</code> (<code>0x5d</code>) opcodes are treated exactly like persistent storage (SLOAD/SSTORE).</li> <li><strong>[OP-080]</strong> <code>BALANCE</code> (<code>0x31</code>) and <code>SELFBALANCE</code> (<code>0x47</code>) are allowed only from a staked entity, else they are blocked.</li> </ul> <h3 id="code-rules">Code Rules</h3> <ul> <li><strong>[COD-010]</strong> Between the first and the second validations, the <code>EXTCODEHASH</code> value of any visited address, entity, or referenced library, may not be changed.<br /> If the code is modified, the UserOperation is considered invalid.</li> </ul> <h3 id="storage-rules">Storage Rules</h3> <p>The storage access with <code>SLOAD</code> and <code>SSTORE</code> (and <code>TLOAD</code>, <code>TSTORE</code>) instructions within each phase is limited as follows:</p> <ul> <li><strong>[STO-010]</strong> Access to the "account" storage is always allowed.</li> <li>Access to associated storage of the account in an external (non-entity) contract is allowed if either: <ul> <li><strong>[STO-021]</strong> The account already exists.</li> <li><strong>[STO-022]</strong> There is an <code>initCode</code> and the <code>factory</code> contract is staked.</li> </ul> </li> <li>If the entity (<code>paymaster</code>, <code>factory</code>) is staked, then it is also allowed: <ul> <li><strong>[STO-031]</strong> Access the entity's own storage.</li> <li><strong>[STO-032]</strong> Read/Write Access to storage slots that are associated with the entity, in any non-entity contract.</li> <li><strong>[STO-033]</strong> Read-only access to any storage in non-entity contract.</li> </ul> </li> </ul> <h3 id="local-rules">Local Rules</h3> <p>Local storage rules protect the bundler against denial of service at the time of bundling. They do not affect mempool propagation and cannot cause a bundler to be marked as a "spammer".</p> <ul> <li><strong>[STO-040]</strong> <code>UserOperation</code> may not use an entity address (<code>factory</code>/<code>paymaster</code>/<code>aggregator</code>) that is used as an "account" in another <code>UserOperation</code> in the mempool.<br /> This means that <code>Paymaster</code>, <code>Factory</code> or <code>Aggregator</code> contracts cannot practically be an "account" contract as well.</li> <li><strong>[STO-041]</strong> <code>UserOperation</code> may not use associated storage (of either its account or from staked entity) in a contract that is a "sender" of another UserOperation in the mempool.</li> </ul> <h3 id="general-reputation-rules">General Reputation Rules</h3> <p>The following reputation rules apply for all staked entities, and for unstaked paymasters. All rules apply to all of these entities unless specified otherwise.</p> <ul> <li><strong>[GREP-010]</strong> A <code>BANNED</code> address is not allowed into the mempool.<br /> Also, all existing <code>UserOperations</code> referencing this address are removed from the mempool.</li> <li><strong>[GREP-020]</strong> A <code>THROTTLED</code> address is limited to: <ul> <li><code>THROTTLED_ENTITY_MEMPOOL_COUNT</code> entries in the mempool.</li> <li><code>THROTTLED_ENTITY_BUNDLE_COUNT</code> <code>UserOperations</code> in a bundle.</li> <li>Can remain in the mempool only for <code>THROTTLED_ENTITY_LIVE_BLOCKS</code>.</li> </ul> </li> <li><strong>[GREP-040]</strong> If an entity fails the bundle creation after passing second validation, its <code>opsSeen</code> set to <code>BAN_OPS_SEEN_PENALTY</code>, and <code>opsIncluded</code> to zero, causing it to be <code>BANNED</code>.</li> <li><strong>[GREP-050]</strong> When a UserOperation is replaced (by submitting a new UserOperation, with higher gas fees), and an entity (e.g. a paymaster) is replaced, then the removed entity has its reputation (opsSeen counter) decremented by 1.</li> </ul> <h3 id="staked-entities-reputation-rules">Staked Entities Reputation Rules</h3> <ul> <li><strong>[SREP-010]</strong> The "canonical mempool" defines a staked entity if it has <code>MIN_STAKE_VALUE</code> and unstake delay of <code>MIN_UNSTAKE_DELAY</code></li> <li><strong>[SREP-020]</strong> MOVED TO GREP-010</li> <li><strong>[SREP-030]</strong> MOVED TO GREP-020</li> <li><strong>[SREP-040]</strong> An <code>OK</code> staked entity is unlimited by the reputation rule. <ul> <li>Allowed in unlimited numbers in the mempool.</li> <li>Allowed in unlimited numbers in a bundle.</li> </ul> </li> <li><strong>[SREP-050]</strong> MOVED TO GREP-040</li> </ul> <h3 id="entity-specific-rules">Entity-specific Rules</h3> <ul> <li><strong>[EREP-010]</strong> For each <code>paymaster</code>, the bundler must track the total gas <code>UserOperations</code> using this <code>paymaster</code> may consume. <ul> <li>Bundler should not accept a new <code>UserOperation</code> with a paymaster to the mempool if the maximum total gas cost of all userops in the mempool, including this new <code>UserOperation</code>, is above the deposit of that <code>paymaster</code> at the current gas price.</li> </ul> </li> <li><strong>[EREP-011]</strong> REMOVED</li> <li><strong>[EREP-015]</strong> A <code>paymaster</code> should not have its opsSeen incremented in case of a failure of factory or account <ul> <li>When running 2nd validation (before inclusion in a bundle), if a UserOperation fails because of factory or account error (either a FailOp revert or validation rule), then the paymaster's opsSeen valid is decremented by 1.</li> </ul> </li> <li><strong>[EREP-016]</strong> An <code>aggregator</code> should not have its opsSeen incremented in case of a failure of a factory, an account or a paymaster <ul> <li>When running 2nd validation (before inclusion in a bundle), if a UserOperation fails because of a factory, an account or a paymaster error (either a FailOp revert or validation rule), then the aggregator's opsSeen valid is decremented by 1.</li> </ul> </li> <li><strong>[EREP-020]</strong> If a staked factory is used, its reputation is updated for the account violating any of the validation rules accordingly.<br /> That is, if the <code>validateUserOp()</code> is rejected for any reason in a <code>UserOperation</code> that has an <code>initCode</code>, it is treated as if the factory caused this failure, and thus this affects its reputation.</li> <li><strong>[EREP-030]</strong> If a staked account is used, its reputation is updated for failures in other entities (<code>paymaster</code>, <code>aggregator</code>) even if they are staked.</li> <li><strong>[EREP-040]</strong> An <code>aggregator</code> must be staked, regardless of storage usage.</li> <li><strong>[EREP-050]</strong> An unstaked <code>paymaster</code> may not return a <code>context</code>.</li> <li><strong>[EREP-055]</strong> A context size may not change between validation and bundle creation.<br /> If a bundle creation reverts, and a paymaster's context size was modified, that paymaster<br /> is BANNED, regardless if the UserOperation that reverted used that paymaster or not.</li> <li>Staked factory creation rules: <ul> <li><strong>[EREP-060]</strong> If the factory is staked, either the factory itself or the sender may use the CREATE2 and CREATE opcode (the sender is allowed to use the CREATE with unstaked factory, with OP-032)</li> <li><strong>[EREP-061]</strong> A staked factory may also use a utility contract that calls the <code>CREATE</code></li> </ul> </li> <li><strong>[EREP-070]</strong> During bundle creation, if a staked entity reduce its validation gas by more than 10% compared to the second validation, that entity is throttled, even if the UserOperation itself didn't revert. (as it might affect the gas calculation based on <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> )</li> </ul> <h3 id="unstaked-entities-reputation-rules">Unstaked Entities Reputation Rules</h3> <ul> <li>Definitions: <ul> <li><strong><code>opsSeen</code>, <code>opsIncluded</code>, and reputation calculation</strong> are defined above.</li> <li><code>UnstakedReputation</code> of an entity determines the maximum number of entries using this entity allowed in the mempool.</li> <li><code>opsAllowed</code> is a reputation-based calculation for an unstaked entity, representing how many <code>UserOperations</code> it is allowed to have in the mempool.</li> <li>Rules: <ul> <li><strong>[UREP-010]</strong> An unstaked sender (that is not throttled/banned) is only allowed to have <code>SAME_SENDER_MEMPOOL_COUNT</code> <code>UserOperation</code>s in the mempool.</li> <li><strong>[UREP-020]</strong> For an unstaked paymaster only that is not throttled/banned:<br /> <code>opsAllowed = SAME_UNSTAKED_ENTITY_MEMPOOL_COUNT + inclusionRate * min(opsIncluded, MAX_OPS_ALLOWED_UNSTAKED_ENTITY)</code>.</li> <li>This is a default of <code>SAME_UNSTAKED_ENTITY_MEMPOOL_COUNT</code> for new entity</li> <li><strong>[UREP-030]</strong> REMOVED</li> </ul> </li> </ul> </li> </ul> <h3 id="alt-mempools-rules">Alt-mempools Rules</h3> <p>Alternate mempool is an agreed-upon rule that the bundlers may opt into, in addition to the canonical mempool The alt-mempool "topic" is a unique identifier. By convention, this is the IPFS hash of the document describing (in clear test and YAML file) the specifics of this alt mempool.</p> <ul> <li><strong>[ALT-010]</strong> The bundler listens to the alt-mempool "topic" over the P2P protocol</li> <li><strong>[ALT-020]</strong> The alt mempool rules MUST be checked only when a canonical rule is violated <ul> <li>That is, if validation follows the canonical rules above, it is not considered part of an alt-mempool.</li> </ul> </li> <li><strong>[ALT-021]</strong> Such a <code>UserOperation</code> (that violates the canonical rules) is checked against all the "alternate mempools", and is considered part of all those alt-mempools</li> <li><strong>[ALT-030]</strong> Bundlers SHOULD forward <code>UserOperations</code> to other bundlers only once, regardless of how many (shared) alt-mempools they have.<br /> The receiving bundler validates the <code>UserOperations</code>, and based on the above rules (and subscribed alt-mempools) decides which alt-mempools to propagate it to.</li> <li><strong>[ALT-040]</strong> opsInclude and opsSeen of entities are kept per alt-mempool. That is, an entity can be considered throttled (or banned) in one mempool, while still active on another.</li> </ul> <h3 id="alt-mempool-reputation">Alt-mempool Reputation</h3> <p>Alt-mempools are served by the same bundlers participating in the canonical mempool, but change the rules and may introduce denial-of-service attack vectors. To prevent them from taking the canonical mempool or other alt mempools down with them, a reputation is managed for each. An alt mempool that causes too many invalidations gets throttled. This limits the scope of the attack and lets the bundler continue doing its work for other mempools.</p> <ul> <li><strong>[AREP-010]</strong> each alt-mempool has "opsSeen" and "opsIncluded", much like entities. The opsSeen is incremented after <code>UserOperation</code> initial validation, where it is considered part of this mempool. The "opsIncluded" is incremented after this UserOperation is included on-chain (either by this bundler, or another)</li> <li><strong>[AREP-020]</strong> the alt-mempool becomes <code>THROTTLED</code>/<code>BANNED</code> based on the <a href="https://wg-eips.ritovision.com/7562/#reputation-calculation">Reputation Calculation</a></li> <li><strong>[AREP-030]</strong> REMOVED</li> </ul> <h3 id="authorizations">Authorizations</h3> <ul> <li><strong>[AUTH-010]</strong> A UserOperation may only contain a single <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> authorization tuple.</li> <li><strong>[AUTH-020]</strong> An account with EIP-7702 delegation can only be used as the Sender of the UserOperation. Using authorized account as any other kind of UserOperation entity is not allowed.</li> <li><strong>[AUTH-030]</strong> An account with EIP-7702 delegation can only be <strong>accessed</strong> (using <code>*CALL</code> or <code>EXTCODE*</code> opcodes) if it is the Sender of the current UserOperation.</li> <li><strong>[AUTH-040]</strong> If there are multiple UserOperations by the same sender with an authorization tuple in the mempool, they all MUST have the same delegate address.</li> </ul> <h3 id="limitations">Limitations</h3> <p>The validation rules attempt to guarantee a degree of isolation between individual <code>UserOperations</code>' validations. In order to prevent hitting the memory expansion limitations (imposed by ethereum EVM) when creating a bundle, <code>UserOperation</code>s must meet the following limitations:</p> <ul> <li><strong>[LIM-010]</strong> Maximum size of a single packed and ABI-encoded <code>UserOperation</code> in bytes MUST not exceed <code>MAX_USEROP_SIZE</code></li> <li><strong>[LIM-020]</strong> Maximum size of a <code>context</code> byte array returned by a paymaster in a single <code>UserOperation</code> in bytes MUST not exceed <code>MAX_CONTEXT_SIZE</code></li> <li><strong>[LIM-030]</strong> The <code>verificationGasLimit</code> and <code>paymasterVerificationGasLimit</code> parameters MUST exceed the actual usage during validation of the <code>UserOperation</code> by <code>VALIDATION_GAS_SLACK</code></li> <li><strong>[LIM-040]</strong> Maximum size of an ABI-encoded bundle call to the <code>handleOps</code> function in bytes SHOULD not exceed <code>MAX_BUNDLE_SIZE</code></li> <li><strong>[LIM-050]</strong> Maximum total size of all <code>context</code> byte arrays returned by all paymasters in all <code>UserOperations</code> in a bundle in bytes SHOULD not exceed <code>MAX_BUNDLE_CONTEXT_SIZE</code></li> </ul> <h2 id="rationale">Rationale</h2> <p>All transactions initiated by EOAs have an implicit validation phase where balance, nonce, and signature are checked to be valid for the current state of the Ethereum blockchain. Once the transaction is checked to be valid by a node, only another transaction by the same EOA can modify the Ethereum state in a way that makes the first transaction invalid.</p> <p>With Account Abstraction, however, the validation can also include an arbitrary EVM code and rely on storage as well, which means that unrelated <code>UserOperations</code> or transactions may invalidate each other.</p> <p>If not addressed, this would make the job of maintaining a mempool of valid <code>UserOperations</code> and producing valid bundles computationally infeasible and susceptible to DoS attacks.</p> <p>This document describes a set of validation rules that if applied by a bundler before accepting a <code>UserOperation</code> into the mempool can prevent such attacks.</p> <h3 id="the-high-level-goal">The high-level goal</h3> <p>The purpose of this specification is to define a consensus between nodes (bundlers or block-builders) when processing incoming UserOperations from an external source. This external source for UserOperations is either an end-user node (via RPC <a href="https://wg-eips.ritovision.com/7769/">ERC-7769</a>) or another node in the p2p network.</p> <p>The protocol tries to detect "spam" - which are large bursts of UserOperations that cannot be included on-chain (and thus can't pay). The network is protected by throttling down requests from such spammer nodes.</p> <p>All nodes in the network must have the same definition of "spam": otherwise, if some nodes accept some type of UserOperations and propagate them while others consider them spam, those "forgiving" nodes will be considered "spammers" by the rest of the nodes, and the network effectively gets split.</p> <h3 id="the-processing-flow-of-a-useroperation">The processing flow of a UserOperation</h3> <ul> <li>First, a UserOperation is received - either via RPC (submitted on behalf of a single application) or via the p2p protocol, from another node in the mempool.</li> <li>The node performs validation on the UserOperation, and then adds it to its in-memory mempool, and submits it to its peers.</li> <li>Lastly, when building a block, a node collects UserOperations from the mempool, performs a 2nd validation to make sure they are all still valid as a bundle and submits them into the next block.</li> </ul> <h3 id="the-need-for-2nd-validation-before-submitting-a-block">The need for 2nd validation before submitting a block</h3> <p>A normal Ethereum transaction in the mempool can be invalidated if another transaction was received with the same nonce. That other transaction had to increase the gas price in order to replace the first one, so it satisfied the rule of "must pay to get included into the mempool". With contract-based accounts, since the UserOperation validity may depend on mutable state, other transactions may invalidate a previously valid UserOperation, so we must check it before inclusion.</p> <h3 id="rationale-of-limiting-opcodes">Rationale of limiting opcodes:</h3> <ul> <li>the validation is performed off-chain, before creating a block. Some opcodes access information that is known only when creating the block.</li> <li>using those opcodes while validating a transaction can easily create a validation rule that will succeed off-chain, but always revert on-chain, and thus cause a DoS attack.</li> <li>a simple example is <code>require block.number==12345</code>. It can be valid when validating the UserOperation and adding it to the mempool but will be invalid when attempting to include it on-chain at a later block.</li> </ul> <h3 id="rationale-for-limiting-storage-access">Rationale for limiting storage access</h3> <ul> <li>We need UserOperation validations not to overlap so that a single storage change can't easily invalidate a large number of UserOperations in the mempool. By limiting UserOperations to access storage associated with the account itself, we know that we can for sure include a single UserOperation for each account in a bundle</li> <li>(A bundler MAY include multiple UserOperations of the same account in a bundle, but MUST first validate them together)</li> </ul> <h3 id="rationale-of-requiring-a-stake">Rationale of requiring a stake</h3> <p>We want to be able to allow globally-used contracts (paymasters, factories, aggregators) to use storage not associated with the account, but still prevent them from spamming the mempool. If a contract causes too many UserOperations to fail in their second validation after succeeding in their first, we can throttle its use in the mempool. By requiring such a contract to have a stake, we prevent a "Sybil attack", by making it expensive to create a large number of such paymasters to continue the spam attack.</p> <p>By following the validation rules, we can detect contracts that cause spam UserOperations, and throttle them. The stake comes to prevent the fast re-creation of malicious entities. The stake is never slashed (since it is only used for off-chain detection) but is locked for a period of time, which makes such an attack much more expensive.</p> <h3 id="definition-of-the-mass-invalidation-attack">Definition of the <code>mass invalidation attack</code></h3> <p>A possible set of actions is considered to be a <code>mass invalidation attack</code> on the network if a large number of <code>UserOperations</code> that did pass the initial validation and were accepted by nodes and propagated further into the mempool to other bundlers in the network becomes invalid and not eligible for inclusion in a block.</p> <p>There are 3 ways to perform such an attack:</p> <ol> <li>Submit <code>UserOperation</code>s that pass the initial validation, but later fail the re-validation that is performed during the bundle creation.</li> <li>Submit <code>UserOperation</code>s that are valid in isolation during validation, but when bundled together become invalid.</li> <li>Submit valid <code>UserOperation</code>s but "front-run" them by executing a state change on the network that causes them to become invalid. The "front-run" in question must be economically viable.</li> </ol> <p>To prevent such attacks, we attempt to "sandbox" the validation code. We isolate the validation code from other <code>UserOperations</code>, from external changes to the storage, and from information about the environment such as a current block timestamp.</p> <h3 id="what-is-not-considered-a-mass-invalidation-attack">What is not considered a <code>mass invalidation attack</code></h3> <p>A <code>UserOperation</code> that fails the initial validation by a receiving node without entering its mempool is not considered an attack. The node is expected to apply web2 security measures and throttle requests based on API key, source IP address, etc. RPC nodes already do that to prevent being spammed with invalid transactions which also have a validation cost. P2P nodes already have (and should apply) a scoring mechanism to determine spammer nodes.</p> <p>Also, if the invalidation of <code>N</code> UserOperations from the mempool costs <code>N*X</code> with a sufficiently large <code>X</code>, it is not considered an economically viable attack.</p> <ul> <li>The minimum change to cause an invalidation is a storage change (5k gas)</li> <li>Assuming a Node can sustain processing 2000 invalid UserOps per block, the cost of a DoS attack is 10M gas per block.</li> <li>The above value is high, but we take further measures to make such an attack more expensive.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>This document describes the security considerations bundlers must take to protect themselves (and the entire mempool network) from denial-of-service 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> 2023-08-31T00:00:00+00:00 2026-02-11T14:48:25+00:00 Philipp Boltehttps://github.com/strumswell Dennis von der Beyhttps://github.com/DennisVonDerBey Lauritz Leifermannhttps://github.com/lleifermann https://wg-eips.ritovision.com/7506/

A system for managing on-chain metadata, enabling verification of ecosystem claims.

<h2 id="abstract">Abstract</h2> <p>This EIP standardizes a system for managing on-chain metadata (hints), enabling claim interpretation, reliability, and verification. It structures these hints within defined namespaces and lists, enabling structured organization and retrieval, as well as permissioned write access. The system permits namespace owners to delegate hint management tasks, enhancing operational flexibility. It incorporates secure meta transactions via <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>-enabled signatures and offers optional ENS integration for trust verification and discoverability. The interface is equipped to emit specific events for activities like hint modifications, facilitating easy traceability of changes to hints. This setup aims to provide a robust, standardized framework for managing claim- and ecosystem-related metadata, essential for maintaining integrity and trustworthiness in decentralized environments.</p> <h2 id="motivation">Motivation</h2> <p>In an increasingly interconnected and decentralized landscape, the formation of trust among entities remains a critical concern. Ecosystems, both on-chain and off-chain—spanning across businesses, social initiatives, and other organized frameworks—frequently issue claims for or about entities within their networks. These claims serve as the foundational elements of trust, facilitating interactions and transactions in environments that are essentially untrustworthy by nature. While the decentralization movement has brought about significant improvements around trustless technologies, many ecosystems building on top of these are in need of technologies that build trust in their realm. Real-world applications have shown that verifiable claims alone are not enough for this purpose. Moreover, a supporting layer of on-chain metadata is needed to support a reliable exchange and verification of those claims.</p> <p>The absence of a structured mechanism to manage claim metadata on-chain poses a significant hurdle to the formation and maintenance of trust among participating entities in an ecosystem. This necessitates the introduction of a layer of on-chain metadata, which can assist in the reliable verification and interpretation of these claims. Termed "hints" in this specification, this metadata can be used in numerous ways, each serving to bolster the integrity and reliability of the ecosystem's claims. Hints can perform various tasks, such as providing revocation details, identifying trusted issuers, or offering timestamping hashes. These are just a few examples that enable ecosystems to validate and authenticate claims, as well as verify data integrity over time.</p> <p>The proposed "Trusted Hint Registry" aims to provide a robust, flexible, and standardized interface for managing such hints. The registry allows any address to manage multiple lists of hints, with a set of features that not only make it easier to create and manage these hints but also offer the flexibility of delegating these capabilities to trusted entities. In practice, this turns the hint lists into dynamic tools adaptable to varying requirements and use cases. Moreover, an interface has been designed with a keen focus on interoperability, taking into consideration existing W3C specifications around Decentralized Identifiers and Verifiable Credentials, as well as aligning with on-chain projects like the Ethereum Attestation Service.</p> <p>By providing a standardized smart contract interface for hint management, this specification plays an integral role in enabling and scaling trust in decentralized ecosystems. It offers a foundational layer upon which claims — both on-chain and off-chain — can be reliably issued, verified, and interpreted, thus serving as an essential building block for the credible operation of any decentralized ecosystem. Therefore, the Trusted Hint Registry is not just an addition to the ecosystem but a necessary evolution in the complex topology of decentralized trust.</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>TrustedHintRegistry</code> and standardizes a set of <strong>REQUIRED</strong> core hint functions, while also providing a common set of <strong>OPTIONAL</strong> management functions, enabling various ways for collaborative hint management. Ecosystems <strong>MAY</strong> use this specification to build their own hint registry contracts with ecosystem-specific, non-standardized features. Governance is deliberately excluded from this ERC and <strong>MAY</strong> be implemented according to an ecosystem's need.</p> <h3 id="definitions">Definitions</h3> <ul> <li><code>claim</code>: A claim is a statement about an entity made by another entity.</li> <li><code>hint</code>: A "hint" refers to a small piece of information that provides insights, aiding in the interpretation, reliability, or verifiability of decentralized ecosystem data.</li> <li><code>namespace</code>: A namespace is a representation of an Ethereum address inside the registry that corresponds to its owner’s address. A namespace contains hint lists for different use cases.</li> <li><code>hint list</code>: A hint list is identified by a unique value that contains a number of hint keys that resolve to hint values. An example of this is a revocation key that resolves to a revocation state.</li> <li><code>hint key</code>: A hint key is a unique value that resolves to a hint value. An example of this is a trusted issuer identifier, which resolves to the trust status of that identifier.</li> <li><code>hint value</code>: A hint value expresses data about an entity in an ecosystem.</li> <li><code>delegate</code>: An Ethereum address that has been granted writing permissions to a hint list by its owner.</li> </ul> <h3 id="interface">Interface</h3> <h4 id="hint-management">Hint Management</h4> <h5 id="gethint">getHint</h5> <p>A method with the following signature <strong>MUST</strong> be implemented that returns the hint value in a hint list of 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"> getHint</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _key</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></code></pre><h5 id="sethint">setHint</h5> <p>A method with the following signature <strong>MUST</strong> be implemented that changes the hint value in a hint list of a namespace. An overloaded method with an additional <code>bytes calldata _metadata</code> parameter <strong>MAY</strong> be implemented to set metadata together with the hint value.</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"> setHint</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _key</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h5 id="sethintsigned">setHintSigned</h5> <p>A method with the following signature <strong>MAY</strong> be implemented that changes the hint value in a hint list of a namespace with a raw signature. The raw signature <strong>MUST</strong> be generated following the Meta Transactions section. An overloaded method with an additional <code>bytes calldata _metadata</code> parameter <strong>MAY</strong> be implemented to set metadata together with the hint value.</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"> setHintSigned</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _key</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _value</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _signer</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"> public</span><span>;</span></span></code></pre> <p>The type hash <strong>MUST</strong> be the keccak256 hash of <code>SetHintSigned(address namespace,bytes32 list,bytes32 key,bytes32 value,address signer,uint256 nonce)</code> or <code>SetHintSigned(address namespace,bytes32 list,bytes32 key,bytes32 value,bytes metadata,address signer,uint256 nonce)</code> when calling the metadata variant.</p> <h5 id="sethints">setHints</h5> <p>A method with the following signature <strong>MUST</strong> be implemented that changes multiple hint values in a hint list of a namespace. An overloaded method with an additional <code>bytes[] calldata _metadata</code> parameter <strong>MAY</strong> be implemented to set metadata together with the hint value.</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"> setHints</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</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"> _keys</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"> _values</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h5 id="sethintssigned">setHintsSigned</h5> <p>A method with the following signature <strong>MUST</strong> be implemented that multiple hint values in a hint list of a namespace with a raw signature. The raw signature <strong>MUST</strong> be generated following the Meta Transactions section. An overloaded method with an additional <code>bytes[] calldata _metadata</code> parameter <strong>MAY</strong> be implemented to set metadata together with the hint value.</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"> setHintsSigned</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</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"> _keys</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"> _values</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _signer</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"> public</span><span>;</span></span></code></pre> <p>The type hash <strong>MUST</strong> be the keccak256 hash of <code>SetHintsSigned(address namespace,bytes32 list,bytes32[] keys,bytes32[] values,address signer,uint256 nonce)</code> or <code>SetHintsSigned(address namespace,bytes32 list,bytes32[] keys,bytes32[] values,bytes[] metadata,address signer,uint256 nonce)</code> when calling the metadata variant.</p> <h4 id="delegated-hint-management">Delegated Hint Management</h4> <p>A namespace owner can add delegate addresses to specific hint lists in their namespace. These delegates <strong>SHALL</strong> have write access to the specific lists via a specific set of methods.</p> <h5 id="sethintdelegated">setHintDelegated</h5> <p>A method with the following signature <strong>MAY</strong> be implemented that changes the hint value in a hint list of a namespace for pre-approved delegates. An overloaded method with an additional <code>bytes calldata _metadata</code> parameter <strong>MAY</strong> be implemented to set metadata together with the hint value.</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"> setHintDelegated</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _key</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h5 id="sethintdelegatedsigned">setHintDelegatedSigned</h5> <p>A method with the following signature <strong>MAY</strong> be implemented that changes the hint value in a hint list of a namespace for pre-approved delegates with a raw signature. The raw signature <strong>MUST</strong> be generated following the Meta Transactions section. An overloaded method with an additional <code>bytes calldata _metadata</code> parameter <strong>MAY</strong> be implemented to set metadata together with the hint value.</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"> setHintDelegatedSigned</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _key</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _value</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _signer</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"> public</span><span>;</span></span></code></pre> <p>The type hash <strong>MUST</strong> be the keccak256 hash of <code>SetHintDelegatedSigned(address namespace,bytes32 list,bytes32 key,bytes32 value,address signer,uint256 nonce)</code> or <code>SetHintDelegatedSigned(address namespace,bytes32 list,bytes32 key,bytes32 value,bytes metadata,address signer,uint256 nonce)</code> when calling the metadata variant.</p> <h5 id="sethintsdelegated">setHintsDelegated</h5> <p>A method with the following signature <strong>MAY</strong> be implemented that changes multiple hint values in a hint list of a namespace for pre-approved delegates. An overloaded method with an additional <code>bytes[] calldata _metadata</code> parameter <strong>MAY</strong> be implemented to set metadata together with the hint value.</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"> setHintsDelegated</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</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"> _keys</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"> _values</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h5 id="sethintsdelegatedsigned">setHintsDelegatedSigned</h5> <p>A method with the following signature <strong>MAY</strong> be implemented that has multiple hint values in a hint list of a namespace for pre-approved delegates with a raw signature. The raw signature <strong>MUST</strong> be generated following the Meta Transactions section. An overloaded method with an additional <code>bytes[] calldata _metadata</code> parameter <strong>MAY</strong> be implemented to set metadata together with the hint value.</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"> setHintsDelegatedSigned</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</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"> _keys</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"> _values</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _signer</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"> public</span><span>;</span></span></code></pre> <p>The type hash <strong>MUST</strong> be the keccak256 hash of <code>SetHintsDelegatedSigned(address namespace,bytes32 list,bytes32[] keys,bytes32[] values,address signer,uint256 nonce)</code> or <code>SetHintsDelegatedSigned(address namespace,bytes32 list,bytes32[] keys,bytes32[] values,bytes[] metadata,address signer,uint256 nonce)</code> when calling the metadata variant.</p> <h4 id="hint-list-management">Hint List Management</h4> <h5 id="setliststatus">setListStatus</h5> <p>A method with the following signature <strong>MAY</strong> be implemented that changes the validity state of a hint list. Revoking a list <strong>CAN</strong> be used to invalidate all hint values in a 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"> setListStatus</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _revoked</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h5 id="setliststatussigned">setListStatusSigned</h5> <p>A method with the following signature <strong>MAY</strong> be implemented that changes the validity state of a hint list with a raw signature. Revoking a list <strong>CAN</strong> be used to invalidate all hint values in a 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"> setListStatusSigned</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _revoked</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _signer</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"> public</span><span>;</span></span></code></pre> <p>The type hash <strong>MUST</strong> be the keccak256 hash of <code>SetListStatusSigned(address namespace,bytes32 list,bool revoked,address signer,uint256 nonce)</code> when generating the signature.</p> <h5 id="setlistowner">setListOwner</h5> <p>A method with the following signature <strong>MAY</strong> be implemented that transfers the ownership of a trust list to another address. Changing the owner of a list <strong>SHALL NOT</strong> change the namespace the hint list resides in, to retain references of paths to a hint value.</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"> setListOwner</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</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"> public</span><span>;</span></span></code></pre><h5 id="setlistownersigned">setListOwnerSigned</h5> <p>A method with the following signature <strong>MAY</strong> be implemented that transfers the ownership of a trust list to another address with a raw signature. The raw signature <strong>MUST</strong> be generated following the Meta Transactions section. Changing the owner of a list <strong>SHALL NOT</strong> change the namespace the hint list resides in, to retain references to paths to a hint value.</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"> setListOwnerSigned</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _newOwner</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _signer</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"> public</span><span>;</span></span></code></pre> <p>The type hash <strong>MUST</strong> be the keccak256 hash of <code>SetListOwnerSigned(address namespace,bytes32 list,address newOwner,address signer,uint256 nonce)</code> when generating the signature.</p> <h5 id="addlistdelegate">addListDelegate</h5> <p>A method with the following signature <strong>MAY</strong> be implemented to add a delegate to an owner’s hint 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 z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _delegate</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _untilTimestamp</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h5 id="addlistdelegatesigned">addListDelegateSigned</h5> <p>A method with the following signature <strong>MAY</strong> be implemented to add a delegate to an owner’s hint list in a namespace with a raw signature. The raw signature <strong>MUST</strong> be generated following the Meta Transactions section.</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 z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _delegate</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _untilTimestamp</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _signer</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"> public</span><span>;</span></span></code></pre> <p>The type hash <strong>MUST</strong> be the keccak256 hash of <code>AddListDelegateSigned(address namespace,bytes32 list,address delegate,uint256 untilTimestamp,address signer,uint256 nonce)</code> when generating the signature.</p> <h5 id="removelistdelegate">removeListDelegate</h5> <p>A method with the following signature <strong>MAY</strong> be implemented to remove a delegate from an owner’s hint 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 z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _delegate</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h5 id="removelistdelegatesigned">removeListDelegateSigned</h5> <p>A method with the following signature <strong>MAY</strong> be implemented to remove a delegate from an owner’s hint list in a namespace with a raw signature. The raw signature <strong>MUST</strong> be generated following the Meta Transactions section.</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 z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _delegate</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _signer</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"> public</span><span>;</span></span></code></pre> <p>The type hash <strong>MUST</strong> be the keccak256 hash of <code>RemoveListDelegateSigned(address namespace,bytes32 list,address delegate,address signer,uint256 nonce)</code> when generating the signature.</p> <h4 id="metadata-management">Metadata Management</h4> <h5 id="getmetadata">getMetadata</h5> <p>A method with the following signature <strong>MAY</strong> be implemented to retrieve metadata for a hint.</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"> getMetadata</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _key</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _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-support">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre><h5 id="setmetadata">setMetadata</h5> <p>A method with the following signature <strong>MAY</strong> be implemented to set metadata for a hint.</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"> setMetadata</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _key</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _value</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"> _metadata</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h5 id="setmetadatasigned">setMetadataSigned</h5> <p>A method with the following signature <strong>MAY</strong> be implemented to set metadata for a hint with a raw signature. The raw signature <strong>MUST</strong> be generated following the Meta Transactions section.</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"> setMetadataSigned</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _key</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _value</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"> _metadata</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _signer</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"> public</span><span>;</span></span></code></pre> <p>The type hash <strong>MUST</strong> be the keccak256 hash of <code>SetMetadataSigned(address namespace,bytes32 list,bytes32 key,bytes32 value,bytes metadata,address signer,uint256 nonce)</code> when generating the signature.</p> <h4 id="setmetadatadelegated">setMetadataDelegated</h4> <p>A method with the following signature <strong>MAY</strong> be implemented to set metadata for a hint as a pre-approved delegate of the hint 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"> setMetadataDelegated</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _key</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _value</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"> _metadata</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h5 id="setmetadatadelegatedsigned">setMetadataDelegatedSigned</h5> <p>A method with the following signature <strong>MAY</strong> be implemented to set metadata for a hint as a pre-approved delegate of the hint list with a raw signature. The raw signature <strong>MUST</strong> be generated following the Meta Transactions section.</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"> setMetadataDelegatedSigned</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _list</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _key</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _value</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"> _metadata</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _signer</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"> public</span><span>;</span></span></code></pre> <p>The type hash <strong>MUST</strong> be the keccak256 hash of <code>SetMetadataDelegatedSigned(address namespace,bytes32 list,bytes32 key,bytes32 value,bytes metadata,address signer,uint256 nonce)</code> when generating the signature.</p> <h4 id="events">Events</h4> <h5 id="hintvaluechanged">HintValueChanged</h5> <p><strong>MUST</strong> be emitted when a hint value has changed.</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"> HintValueChanged</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"> list</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> value</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h5 id="hintlistownerchanged">HintListOwnerChanged</h5> <p><strong>MUST</strong> be emitted when the owner of a list has changed.</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"> HintListOwnerChanged</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"> list</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><h5 id="hintlistdelegateadded">HintListDelegateAdded</h5> <p><strong>MUST</strong> be emitted when a delegate has been added to a hint list.</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"> HintListDelegateAdded</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"> list</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"> newDelegate</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h5 id="hintlistdelegateremoved">HintListDelegateRemoved</h5> <p><strong>MUST</strong> be emitted when a delegate has been removed from a hint list.</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"> HintListDelegateRemoved</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"> list</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"> oldDelegate</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h5 id="hintliststatuschanged">HintListStatusChanged</h5> <p><strong>MUST</strong> be emitted when the validity status of the hint list has been changed.</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"> HintListStatusChanged</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"> list</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-storage z-type"> indexed</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</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 as part of the method call in a transaction to the smart contract.</li> </ul> <p>A <strong>transaction signer</strong> <strong>MAY</strong> be able to deliver a signed payload off-band to a <strong>transaction sender</strong> that initiates the Ethereum interaction with the smart contract. The signed payload <strong>MUST</strong> be limited to being used only once (see Signed Hash and Nonce).</p> <h4 id="signed-hash">Signed Hash</h4> <p>The signature of the <strong>transaction signer</strong> <strong>MUST</strong> conform to <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>. This helps users understand what the payload they are signing consists of, and it provides protection against replay attacks.</p> <h4 id="nonce">Nonce</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 the <strong>transaction signer</strong>. This effectively removes the possibility for any other sender to execute the same transaction again with another wallet.</p> <h3 id="trust-anchor-via-ens">Trust Anchor via ENS</h3> <p>Ecosystems that use an Ethereum Name Service (ENS) domain can increase trust by using ENS entries to share information about a hint list registry. This method takes advantage of the ENS domain's established credibility to make it easier to find a hint registry contract of the domain's entity, as well as the appropriate namespace and hint list customized for particular ecosystem needs. Implementing a trust anchor through ENS is <strong>OPTIONAL</strong>.</p> <p>For each use case, a specific or set of ENS subdomain <strong>SHALL</strong> be created. Each subdomain should be treated as an atomic entity for a singular set of namespace-list-key-value TEXT records. The following records <strong>SHALL</strong> be set:</p> <ul> <li>ADDRESS ETH - address of the trusted hint registry contract</li> <li>TEXT - key: “hint.namespace”; value: owner address of namespace</li> </ul> <p>The following records <strong>MAY</strong> be set:</p> <ul> <li>TEXT - key: “hint.list”; value: bytes32 key of hint list</li> <li>TEXT - key: “hint.key”; value: bytes32 key of hint key</li> <li>TEXT - key: “hint.value”; value: bytes32 key of hint value</li> <li>ABI - ABI of trusted hint registry contract</li> </ul> <p>To create a two-way connection, a namespace owner <strong>SHALL</strong> set metadata referencing the complete ENS subdomain hash. Metadata <strong>SHALL</strong> be set in the owners namespace with a hint list and hint key value of <code>0x0</code> where the hint value is the ENS subdomain keccak256 hash.</p> <p>By establishing this connection, a robust foundation for trust and discovery within an ecosystem is created.</p> <h2 id="rationale">Rationale</h2> <p>Examining the method signatures reveals a deliberate architecture and data hierarchy within this ERC: A namespace address maps to a hint list, which in turn maps to a hint key, which then reveals the hint value.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> namespace hint list hint key hint value</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">bytes32</span><span class="z-keyword"> =&gt;</span><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"> bytes32</span><span>)</span><span>)</span><span>)</span><span> hints</span><span>;</span></span></code></pre> <p>This structure is designed to implicitly establish the initial ownership of all lists under a given namespace, eliminating the need for subsequent claiming actions. As a result, it simplifies the process of verifying and enforcing write permissions, thereby reducing potential attack surfaces. Additional data structures must be established and validated for features like delegate management and ownership transfer of hint lists. These structures won't affect the main namespace layout; rather, they serve as a secondary mechanism for permission checks.</p> <p>One of the primary objectives of this ERC is to include management features, as these significantly influence the ease of collaboration and maintainability of hint lists. These features also enable platforms to hide complexities while offering user-friendly interfaces. Specifically, the use of meta-transactions allows users to maintain control over their private keys while outsourcing the technical heavy lifting to platforms, which is achieved simply by signing an <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> payload.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues 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 hint list owner should always be in complete control over its hint list and who has writing access to it.</p> <h3 id="governance">Governance</h3> <p>It is recognized that ecosystems might have processes in place that might also apply to changes in hint lists. This ERC explicitly leaves room for implementers or users of the registry to apply a process that fits the requirements of their ecosystem. Possible solutions can be an extension of the contract with governance features around specific methods, the usage of multi-sig wallets, or off-chain processes enforced by an entity.</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-24T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ming Jianghttps://github.com/minkyn Zheng Hanhttps://github.com/hanbsd Fan Yanghttps://github.com/fayang https://wg-eips.ritovision.com/7507/

An extension of ERC-721 to allow multiple users to a token with restricted permissions.

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. It proposes a new role <code>user</code> in addition to <code>owner</code> for a token. A token can have multiple users under separate expiration time. It allows the subscription model where an NFT can be subscribed non-exclusively by different users.</p> <h2 id="motivation">Motivation</h2> <p>Some NFTs represent IP assets, and IP assets have the need to be licensed for access without transferring ownership. The subscription model is a very common practice for IP licensing where multiple users can subscribe to an NFT to obtain access. Each subscription is usually time limited and will thus be recorded with an expiration time.</p> <p>Existing <a href="https://wg-eips.ritovision.com/4907/">ERC-4907</a> introduces a similar feature, but does not allow for more than one user. It is more suitable in the rental scenario where a user gains an exclusive right of use to an NFT before the next user. This rental model is common for NFTs representing physical assets like in games, but not very useful for shareable IP assets.</p> <h2 id="specification">Specification</h2> <p>Solidity interface available at <a href="https://wg-eips.ritovision.com/7507/./assets/contracts/IERC7507.sol"><code>IERC7507.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"> IERC7507</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"> Emitted when the expires of a user for an NFT is </span><span class="z-keyword">changed</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>;</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"> @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"> @param</span><span class="z-variable z-other"> user</span><span class="z-comment"> The user to get the 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-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 class="z-storage z-type"> @notice</span><span class="z-comment"> Set 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"> The NFT to set the user expires 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"> The user to set the expires 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"> expires</span><span class="z-comment"> The user could use the NFT before expires in UNIX timestamp</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-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>This standard complements <a href="https://wg-eips.ritovision.com/4907/">ERC-4907</a> to support multi-user feature. Therefore the proposed interface tries to keep consistent using the same naming for functions and parameters.</p> <p>However, we didn't include the corresponding <code>usersOf(uint256 tokenId)</code> function as that would imply the implemention has to support enumerability over multiple users. It is not always necessary, for example, in the case of open subscription. So we decide not to add it to the interface and leave the choice up to the implementers.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backwards compatibility issues found.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases available at: <a href="https://wg-eips.ritovision.com/7507/./assets/test/ERC7507.test.ts"><code>ERC7507.test.ts</code></a>:</p> <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-toolbox/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-storage z-type">const</span><span class="z-variable z-other z-constant"> NAME</span><span class="z-keyword"> =</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-storage z-type">const</span><span class="z-variable z-other z-constant"> SYMBOL</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">SYMBOL</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> TOKEN_ID</span><span class="z-keyword"> =</span><span class="z-constant"> 1234</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> EXPIRATION</span><span class="z-keyword"> =</span><span class="z-constant"> 2000000000</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> YEAR</span><span class="z-keyword"> =</span><span class="z-constant"> 31536000</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">ERC7507</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-storage"> async</span><span class="z-storage z-type"> function</span><span class="z-entity z-name"> deployContractFixture</span><span>(</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">deployer</span><span>,</span><span class="z-variable z-other z-constant"> owner</span><span>,</span><span class="z-variable z-other z-constant"> user1</span><span>,</span><span class="z-variable z-other z-constant"> user2</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> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> contract</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">deployContract</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ERC7507</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> [</span><span class="z-variable z-other z-constant">NAME</span><span>,</span><span class="z-variable z-other z-constant"> SYMBOL</span><span>]</span><span>,</span><span class="z-variable z-other"> deployer</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span><span class="z-variable z-other">owner</span><span>,</span><span class="z-variable z-other z-constant"> TOKEN_ID</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> {</span><span class="z-variable z-other"> contract</span><span>,</span><span class="z-variable z-other"> owner</span><span>,</span><span class="z-variable z-other"> user1</span><span>,</span><span class="z-variable z-other"> user2</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"> describe</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Functions</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 not set user if not owner or approved</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"> const</span><span> {</span><span class="z-variable z-other z-constant"> contract</span><span>,</span><span class="z-variable z-other z-constant"> user1</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> loadFixture</span><span>(</span><span class="z-variable z-other">deployContractFixture</span><span>)</span><span>;</span></span> <span class="giallo-l"></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">contract</span><span>.</span><span class="z-entity z-name">setUser</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other"> user1</span><span>,</span><span class="z-variable z-other z-constant"> EXPIRATION</span><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">revertedWith</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ERC7507: caller is not owner or approved</span><span class="z-punctuation z-definition z-string">&quot;</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 return zero expiration for nonexistent user</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"> const</span><span> {</span><span class="z-variable z-other z-constant"> contract</span><span>,</span><span class="z-variable z-other z-constant"> user1</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> loadFixture</span><span>(</span><span class="z-variable z-other">deployContractFixture</span><span>)</span><span>;</span></span> <span class="giallo-l"></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"> contract</span><span>.</span><span class="z-entity z-name">userExpires</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other"> user1</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-constant">0</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 users and then update</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"> const</span><span> {</span><span class="z-variable z-other z-constant"> contract</span><span>,</span><span class="z-variable z-other z-constant"> owner</span><span>,</span><span class="z-variable z-other z-constant"> user1</span><span>,</span><span class="z-variable z-other z-constant"> user2</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> loadFixture</span><span>(</span><span class="z-variable z-other">deployContractFixture</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span class="z-variable z-other">owner</span><span>)</span><span>.</span><span class="z-entity z-name">setUser</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other"> user1</span><span>,</span><span class="z-variable z-other z-constant"> EXPIRATION</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span class="z-variable z-other">owner</span><span>)</span><span>.</span><span class="z-entity z-name">setUser</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other"> user2</span><span>,</span><span class="z-variable z-other z-constant"> EXPIRATION</span><span>)</span><span>;</span></span> <span class="giallo-l"></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"> contract</span><span>.</span><span class="z-entity z-name">userExpires</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other"> user1</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 z-constant">EXPIRATION</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"> contract</span><span>.</span><span class="z-entity z-name">userExpires</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other"> user2</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 z-constant">EXPIRATION</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span class="z-variable z-other">owner</span><span>)</span><span>.</span><span class="z-entity z-name">setUser</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other"> user1</span><span>,</span><span class="z-variable z-other z-constant"> EXPIRATION</span><span class="z-keyword"> +</span><span class="z-variable z-other z-constant"> YEAR</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span class="z-variable z-other">owner</span><span>)</span><span>.</span><span class="z-entity z-name">setUser</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other"> user2</span><span>,</span><span class="z-constant"> 0</span><span>)</span><span>;</span></span> <span class="giallo-l"></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"> contract</span><span>.</span><span class="z-entity z-name">userExpires</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other"> user1</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 z-constant">EXPIRATION</span><span class="z-keyword"> +</span><span class="z-variable z-other z-constant"> YEAR</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"> contract</span><span>.</span><span class="z-entity z-name">userExpires</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other"> user2</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-constant">0</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 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">Events</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 emit event when set user</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"> const</span><span> {</span><span class="z-variable z-other z-constant"> contract</span><span>,</span><span class="z-variable z-other z-constant"> owner</span><span>,</span><span class="z-variable z-other z-constant"> user1</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> loadFixture</span><span>(</span><span class="z-variable z-other">deployContractFixture</span><span>)</span><span>;</span></span> <span class="giallo-l"></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">contract</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span class="z-variable z-other">owner</span><span>)</span><span>.</span><span class="z-entity z-name">setUser</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other"> user1</span><span>,</span><span class="z-variable z-other z-constant"> EXPIRATION</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> .</span><span class="z-variable z-other">to</span><span>.</span><span class="z-entity z-name">emit</span><span>(</span><span class="z-variable z-other">contract</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">UpdateUser</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>.</span><span class="z-entity z-name">withArgs</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other"> user1</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-variable z-other z-constant"> EXPIRATION</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 class="giallo-l"><span>}</span><span>)</span><span>;</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>Reference implementation available at: <a href="https://wg-eips.ritovision.com/7507/./assets/contracts/ERC7507.sol"><code>ERC7507.sol</code></a>:</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.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/ERC721.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC7507.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"> ERC7507</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">IERC7507</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-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint64</span><span>)</span><span>)</span><span class="z-storage z-type"> private</span><span> _expires</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 class="giallo-l"><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 class="giallo-l"><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"> supportsInterface</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-variable"> interfaceId</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-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>IERC7507</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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> userExpires</span><span>(</span></span> <span class="giallo-l"><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 class="giallo-l"><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">uint256</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;ERC7507: query for nonexistent token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _expires</span><span>[</span><span>tokenId</span><span>]</span><span>[</span><span>user</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"> setUser</span><span>(</span></span> <span class="giallo-l"><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 class="giallo-l"><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">_isApprovedOrOwner</span><span>(</span><span class="z-entity z-name">_msgSender</span><span>(</span><span>)</span><span>,</span><span> tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC7507: caller is not owner or approved&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _expires</span><span>[</span><span>tokenId</span><span>]</span><span>[</span><span>user</span><span>]</span><span class="z-keyword"> =</span><span> expires</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> UpdateUser</span><span>(</span><span>tokenId</span><span>,</span><span> user</span><span>,</span><span> expires</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>No security considerations 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-08-24T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ming Jianghttps://github.com/minkyn Zheng Hanhttps://github.com/hanbsd Fan Yanghttps://github.com/fayang https://wg-eips.ritovision.com/7510/

An extension of ERC-721 to maintain hierarchical relationship between tokens from different contracts.

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. It proposes a way to maintain hierarchical relationship between tokens from different contracts. This standard provides an interface to query the parent tokens of an NFT or whether the parent relation exists between two NFTs.</p> <h2 id="motivation">Motivation</h2> <p>Some NFTs want to generate derivative assets as new NFTs. For example, a 2D NFT image would like to publish its 3D model as a new derivative NFT. An NFT may also be derived from multiple parent NFTs. Such cases include a movie NFT featuring multiple characters from other NFTs. This standard is proposed to record such hierarchical relationship between derivative NFTs.</p> <p>Existing <a href="https://wg-eips.ritovision.com/6150/">ERC-6150</a> introduces a similar feature, but it only builds hierarchy between tokens within the same contract. More than often we need to create a new NFT collection with the derivative tokens, which requires cross-contract relationship establishment. In addition, deriving from multiple parents is very common in the scenario of IP licensing, but the existing standard doesn't support that either.</p> <h2 id="specification">Specification</h2> <p>Solidity interface available at <a href="https://wg-eips.ritovision.com/7510/./assets/contracts/IERC7510.sol"><code>IERC7510.sol</code></a>:</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"> @notice</span><span class="z-comment"> The struct used to reference a token in an NFT contract</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Token</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> collection</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> id</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"> IERC7510</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"> Emitted when the parent tokens for an NFT is updated</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UpdateParentTokens</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Get the parent tokens 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"> The NFT to get the parent tokens 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"> An</span><span class="z-comment"> array of parent tokens for this NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> parentTokensOf</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-storage z-type">Token</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"> Check if another token is a parent 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"> The NFT to check its parent 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"> otherToken</span><span class="z-comment"> Another token to check as a parent or 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"> Whether</span><span class="z-comment"> `otherToken` is a parent of `tokenId`</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isParentToken</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-storage z-type"> Token</span><span class="z-storage z-type"> memory</span><span class="z-variable"> otherToken</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"> Set the parent tokens for 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"> The NFT to set the parent 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"> parentTokens</span><span class="z-comment"> The parent tokens to set</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setParentTokens</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-storage z-type"> Token</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> parentTokens</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>This standard differs from <a href="https://wg-eips.ritovision.com/6150/">ERC-6150</a> in mainly two aspects: supporting cross-contract token reference, and allowing multiple parents. But we try to keep the naming consistent overall.</p> <p>In addition, we didn't include <code>child</code> relation in the interface. An original NFT exists before its derivative NFTs. Therefore we know what parent tokens to include when minting derivative NFTs, but we wouldn't know the children tokens when minting the original NFT. If we have to record the children, that means whenever we mint a derivative NFT, we need to call on its original NFT to add it as a child. However, those two NFTs may belong to different contracts and thus require different write permissions, making it impossible to combine the two operations into a single transaction in practice. As a result, we decide to only record the <code>parent</code> relation from the derivative NFTs.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backwards compatibility issues found.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases available at: <a href="https://wg-eips.ritovision.com/7510/./assets/test/ERC7510.test.ts"><code>ERC7510.test.ts</code></a>:</p> <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-toolbox/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-storage z-type">const</span><span class="z-variable z-other z-constant"> NAME</span><span class="z-keyword"> =</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-storage z-type">const</span><span class="z-variable z-other z-constant"> SYMBOL</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">SYMBOL</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> TOKEN_ID</span><span class="z-keyword"> =</span><span class="z-constant"> 1234</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"> PARENT_1_COLLECTION</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xDEAdBEEf00000000000000000123456789ABCdeF</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> PARENT_1_ID</span><span class="z-keyword"> =</span><span class="z-constant"> 8888</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> PARENT_1_TOKEN</span><span class="z-keyword"> =</span><span> {</span><span> collection</span><span>:</span><span class="z-variable z-other z-constant"> PARENT_1_COLLECTION</span><span>,</span><span> id</span><span>:</span><span class="z-variable z-other z-constant"> PARENT_1_ID</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"> PARENT_2_COLLECTION</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xBaDc0ffEe0000000000000000123456789aBCDef</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> PARENT_2_ID</span><span class="z-keyword"> =</span><span class="z-constant"> 9999</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> PARENT_2_TOKEN</span><span class="z-keyword"> =</span><span> {</span><span> collection</span><span>:</span><span class="z-variable z-other z-constant"> PARENT_2_COLLECTION</span><span>,</span><span> id</span><span>:</span><span class="z-variable z-other z-constant"> PARENT_2_ID</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">ERC7510</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-storage"> async</span><span class="z-storage z-type"> function</span><span class="z-entity z-name"> deployContractFixture</span><span>(</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">deployer</span><span>,</span><span class="z-variable z-other z-constant"> owner</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> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> contract</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">deployContract</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ERC7510</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> [</span><span class="z-variable z-other z-constant">NAME</span><span>,</span><span class="z-variable z-other z-constant"> SYMBOL</span><span>]</span><span>,</span><span class="z-variable z-other"> deployer</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span><span class="z-variable z-other">owner</span><span>,</span><span class="z-variable z-other z-constant"> TOKEN_ID</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> {</span><span class="z-variable z-other"> contract</span><span>,</span><span class="z-variable z-other"> 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-entity z-name"> describe</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Functions</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 not set parent tokens if not owner or approved</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"> const</span><span> {</span><span class="z-variable z-other z-constant"> contract</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> loadFixture</span><span>(</span><span class="z-variable z-other">deployContractFixture</span><span>)</span><span>;</span></span> <span class="giallo-l"></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">contract</span><span>.</span><span class="z-entity z-name">setParentTokens</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span> [</span><span class="z-variable z-other z-constant">PARENT_1_TOKEN</span><span>]</span><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">revertedWith</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ERC7510: caller is not owner or approved</span><span class="z-punctuation z-definition z-string">&quot;</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 correctly query token without parents</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"> const</span><span> {</span><span class="z-variable z-other z-constant"> contract</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> loadFixture</span><span>(</span><span class="z-variable z-other">deployContractFixture</span><span>)</span><span>;</span></span> <span class="giallo-l"></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"> contract</span><span>.</span><span class="z-entity z-name">parentTokensOf</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>)</span><span>)</span><span>.</span><span class="z-variable z-other">to</span><span>.</span><span class="z-variable z-other">have</span><span>.</span><span class="z-entity z-name">lengthOf</span><span>(</span><span class="z-constant">0</span><span>)</span><span>;</span></span> <span class="giallo-l"></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"> contract</span><span>.</span><span class="z-entity z-name">isParentToken</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other z-constant"> PARENT_1_TOKEN</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-constant">false</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 parent tokens and then update</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"> const</span><span> {</span><span class="z-variable z-other z-constant"> contract</span><span>,</span><span class="z-variable z-other z-constant"> owner</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> loadFixture</span><span>(</span><span class="z-variable z-other">deployContractFixture</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span class="z-variable z-other">owner</span><span>)</span><span>.</span><span class="z-entity z-name">setParentTokens</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span> [</span><span class="z-variable z-other z-constant">PARENT_1_TOKEN</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> parentTokens</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">parentTokensOf</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</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">parentTokens</span><span>)</span><span>.</span><span class="z-variable z-other">to</span><span>.</span><span class="z-variable z-other">have</span><span>.</span><span class="z-entity z-name">lengthOf</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">parentTokens</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span class="z-variable z-other">collection</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 z-constant">PARENT_1_COLLECTION</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">parentTokens</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span class="z-variable z-other">id</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 z-constant">PARENT_1_ID</span><span>)</span><span>;</span></span> <span class="giallo-l"></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"> contract</span><span>.</span><span class="z-entity z-name">isParentToken</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other z-constant"> PARENT_1_TOKEN</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-constant">true</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"> contract</span><span>.</span><span class="z-entity z-name">isParentToken</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other z-constant"> PARENT_2_TOKEN</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-constant">false</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span class="z-variable z-other">owner</span><span>)</span><span>.</span><span class="z-entity z-name">setParentTokens</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span> [</span><span class="z-variable z-other z-constant">PARENT_2_TOKEN</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> parentTokens</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">parentTokensOf</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</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">parentTokens</span><span>)</span><span>.</span><span class="z-variable z-other">to</span><span>.</span><span class="z-variable z-other">have</span><span>.</span><span class="z-entity z-name">lengthOf</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">parentTokens</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span class="z-variable z-other">collection</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 z-constant">PARENT_2_COLLECTION</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">parentTokens</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span class="z-variable z-other">id</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 z-constant">PARENT_2_ID</span><span>)</span><span>;</span></span> <span class="giallo-l"></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"> contract</span><span>.</span><span class="z-entity z-name">isParentToken</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other z-constant"> PARENT_1_TOKEN</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-constant">false</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"> contract</span><span>.</span><span class="z-entity z-name">isParentToken</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other z-constant"> PARENT_2_TOKEN</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-constant">true</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 burn and clear parent tokens</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"> const</span><span> {</span><span class="z-variable z-other z-constant"> contract</span><span>,</span><span class="z-variable z-other z-constant"> owner</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> loadFixture</span><span>(</span><span class="z-variable z-other">deployContractFixture</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span class="z-variable z-other">owner</span><span>)</span><span>.</span><span class="z-entity z-name">setParentTokens</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span> [</span><span class="z-variable z-other z-constant">PARENT_1_TOKEN</span><span>,</span><span class="z-variable z-other z-constant"> PARENT_2_TOKEN</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">burn</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>)</span><span>;</span></span> <span class="giallo-l"></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">contract</span><span>.</span><span class="z-entity z-name">parentTokensOf</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>)</span><span>)</span><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">revertedWith</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ERC7510: query for nonexistent token</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</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">contract</span><span>.</span><span class="z-entity z-name">isParentToken</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other z-constant"> PARENT_1_TOKEN</span><span>)</span><span>)</span><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">revertedWith</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ERC7510: query for nonexistent token</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</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">contract</span><span>.</span><span class="z-entity z-name">isParentToken</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other z-constant"> PARENT_2_TOKEN</span><span>)</span><span>)</span><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">revertedWith</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ERC7510: query for nonexistent token</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"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span><span class="z-variable z-other">owner</span><span>,</span><span class="z-variable z-other z-constant"> TOKEN_ID</span><span>)</span><span>;</span></span> <span class="giallo-l"></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"> contract</span><span>.</span><span class="z-entity z-name">parentTokensOf</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>)</span><span>)</span><span>.</span><span class="z-variable z-other">to</span><span>.</span><span class="z-variable z-other">have</span><span>.</span><span class="z-entity z-name">lengthOf</span><span>(</span><span class="z-constant">0</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"> contract</span><span>.</span><span class="z-entity z-name">isParentToken</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other z-constant"> PARENT_1_TOKEN</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-constant">false</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"> contract</span><span>.</span><span class="z-entity z-name">isParentToken</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span class="z-variable z-other z-constant"> PARENT_2_TOKEN</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-constant">false</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 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">Events</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 emit event when set parent tokens</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"> const</span><span> {</span><span class="z-variable z-other z-constant"> contract</span><span>,</span><span class="z-variable z-other z-constant"> owner</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> loadFixture</span><span>(</span><span class="z-variable z-other">deployContractFixture</span><span>)</span><span>;</span></span> <span class="giallo-l"></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">contract</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span class="z-variable z-other">owner</span><span>)</span><span>.</span><span class="z-entity z-name">setParentTokens</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</span><span>,</span><span> [</span><span class="z-variable z-other z-constant">PARENT_1_TOKEN</span><span>,</span><span class="z-variable z-other z-constant"> PARENT_2_TOKEN</span><span>]</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> .</span><span class="z-variable z-other">to</span><span>.</span><span class="z-entity z-name">emit</span><span>(</span><span class="z-variable z-other">contract</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">UpdateParentTokens</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>.</span><span class="z-entity z-name">withArgs</span><span>(</span><span class="z-variable z-other z-constant">TOKEN_ID</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 class="giallo-l"><span>}</span><span>)</span><span>;</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>Reference implementation available at: <a href="https://wg-eips.ritovision.com/7510/./assets/contracts/ERC7510.sol"><code>ERC7510.sol</code></a>:</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.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/ERC721.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC7510.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"> ERC7510</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">IERC7510</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> Token</span><span>[</span><span>]</span><span>)</span><span class="z-storage z-type"> private</span><span> _parentTokens</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-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>)</span><span class="z-storage z-type"> private</span><span> _isParentToken</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 class="giallo-l"><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 class="giallo-l"><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"> supportsInterface</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-variable"> interfaceId</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-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>IERC7510</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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> parentTokensOf</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"> 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-storage z-type">Token</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-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;ERC7510: query for nonexistent token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _parentTokens</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"> isParentToken</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-storage z-type"> Token</span><span class="z-storage z-type"> memory</span><span class="z-variable"> otherToken</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-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;ERC7510: query for nonexistent token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _isParentToken</span><span>[</span><span>tokenId</span><span>]</span><span>[</span><span>otherToken</span><span>.</span><span>collection</span><span>]</span><span>[</span><span>otherToken</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-storage z-type"> function</span><span class="z-entity z-name"> setParentTokens</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-storage z-type"> Token</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> parentTokens</span></span> <span class="giallo-l"><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">_isApprovedOrOwner</span><span>(</span><span class="z-entity z-name">_msgSender</span><span>(</span><span>)</span><span>,</span><span> tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC7510: caller is not owner or approved&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _clear</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> parentTokens</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> _parentTokens</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>parentTokens</span><span>[</span><span>i</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _isParentToken</span><span>[</span><span>tokenId</span><span>]</span><span>[</span><span>parentTokens</span><span>[</span><span>i</span><span>]</span><span>.</span><span>collection</span><span>]</span><span>[</span><span>parentTokens</span><span>[</span><span>i</span><span>]</span><span>.</span><span>id</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 class="z-keyword"> emit</span><span class="z-entity z-name"> UpdateParentTokens</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"> _burn</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-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 class="z-entity z-name"> _clear</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"> _clear</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"> private</span><span> {</span></span> <span class="giallo-l"><span> Token</span><span>[</span><span>]</span><span class="z-storage z-type"> storage</span><span> parentTokens </span><span class="z-keyword">=</span><span> _parentTokens</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> parentTokens</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-keyword"> delete</span><span> _isParentToken</span><span>[</span><span>tokenId</span><span>]</span><span>[</span><span>parentTokens</span><span>[</span><span>i</span><span>]</span><span>.</span><span>collection</span><span>]</span><span>[</span><span>parentTokens</span><span>[</span><span>i</span><span>]</span><span>.</span><span>id</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> _parentTokens</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></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Parent tokens of an NFT may point to invalid data for two reasons. First, parent tokens could be burned later. Second, a contract implementing <code>setParentTokens</code> might not check the validity of <code>parentTokens</code> arguments. For security consideration, applications that retrieve parent tokens of an NFT need to verify they exist as valid tokens.</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-18T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status Caymanhttps://github.com/wemeetagain https://wg-eips.ritovision.com/7495/

SSZ type for forward-compatible containers

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a new <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md">Simple Serialize (SSZ)</a> type to represent containers with forward-compatible Merkleization: A given field is always assigned the same stable <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/merkle-proofs.md#generalized-merkle-tree-index">generalized index (gindex)</a> even when different container versions append new fields or drop existing fields.</p> <h2 id="motivation">Motivation</h2> <p>SSZ containers are frequently versioned, for example across fork boundaries. When the number of fields reaches a new power of two, or a field is removed or replaced with one of a different type, the shape of the underlying Merkle tree changes, breaking verifiers of Merkle proofs for these containers. Deploying a new verifier may involve security councils to upgrade smart contract logic, or require firmware updates for embedded devices. This effort is needed even when no semantic changes apply to the fields that the verifier is interested in.</p> <p>Progressive containers address these shortcomings by:</p> <ul> <li>Using the <a href="https://wg-eips.ritovision.com/7916/">progressive Merkle tree</a> structure to progressively grow to the actual field count with minimal overhead, ensuring provers remain valid as the field count changes.</li> <li>Assigning stable gindices for each field across all versions by allowing gaps in the Merkle tree where a field is absent.</li> <li>Serializing in a compact form where absent fields do not consume space.</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> <h3 id="progressivecontainer-active-fields"><code>ProgressiveContainer(active_fields)</code></h3> <p>A new <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md#composite-types">SSZ composite types</a> is defined:</p> <ul> <li> <p><strong>progressive container</strong>: ordered heterogeneous collection of values with stable Merkleization</p> <ul> <li>python dataclass notation with key-type pairs, e.g.</li> </ul> <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"> Square</span><span>(</span><span class="z-entity">ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> side</span><span>:</span><span> uint16</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Merkleized at field index #0 (location of first 1 in `active_fields`)</span></span> <span class="giallo-l"><span> color</span><span>:</span><span> uint8</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Merkleized at field index #2 (location of second 1 in `active_fields`)</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"> Circle</span><span>(</span><span class="z-entity">ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> radius</span><span>:</span><span> uint16</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Merkleized at field index #1 (location of first 1 in `active_fields`)</span></span> <span class="giallo-l"><span> color</span><span>:</span><span> uint8</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Merkleized at field index #2 (location of second 1 in `active_fields`)</span></span></code></pre></li> </ul> <p>The <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md#default-values">default value</a> is defined as:</p> <table><thead><tr><th>Type</th><th>Default Value</th></tr></thead><tbody> <tr><td><code>ProgressiveContainer(active_fields)</code></td><td><code>[default(type) for type in progressive_container]</code></td></tr> </tbody></table> <p>The following types are considered <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md#illegal-types">illegal</a>:</p> <ul> <li><code>ProgressiveContainer</code> with no fields are illegal.</li> <li><code>ProgressiveContainer</code> with an <code>active_fields</code> configuration of more than 256 entries are illegal.</li> <li><code>ProgressiveContainer</code> with an <code>active_fields</code> configuration ending in <code>0</code> are illegal.</li> <li><code>ProgressiveContainer</code> with an <code>active_fields</code> configuration with a different count of <code>1</code> than fields are illegal.</li> </ul> <h4 id="serialization">Serialization</h4> <p>Serialization of <code>ProgressiveContainer(active_fields)</code> is identical to <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md#vectors-containers-lists"><code>Container</code></a>.</p> <h4 id="deserialization">Deserialization</h4> <p>Deserialization of <code>ProgressiveContainer(active_fields)</code> is identical to <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md#deserialization"><code>Container</code></a>.</p> <h4 id="json-mapping">JSON mapping</h4> <p>The canonical <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md#json-mapping">JSON mapping</a> is updated:</p> <table><thead><tr><th>SSZ</th><th>JSON</th><th>Example</th></tr></thead><tbody> <tr><td><code>ProgressiveContainer(active_fields)</code></td><td>object</td><td><code>{ "field": ... }</code></td></tr> </tbody></table> <h4 id="merkleization">Merkleization</h4> <p>The <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/ad36024441cf910d428d03f87f331fbbd2b3e5f1/ssz/simple-serialize.md#merkleization">SSZ Merkleization specification</a> is extended with two helper functions:</p> <ul> <li><code>get_active_fields(value)</code>, where <code>value</code> is of type <code>ProgressiveContainer(active_fields)</code>: return <code>active_fields</code>.</li> <li><code>mix_in_active_fields</code>: Given a Merkle root <code>root</code> and an <code>active_fields</code> configuration return <code>hash(root, pack_bits(active_fields))</code>. Note that <code>active_fields</code> is restricted to ≤ 256 bits.</li> </ul> <p>The Merkleization definitions are extended.</p> <ul> <li><code>mix_in_active_fields(merkleize_progressive([hash_tree_root(element) for element in value]), get_active_fields(value))</code> if <code>value</code> is a progressive container.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="why-is-active-fields-limited-to-256-bits">Why is <code>active_fields</code> limited to 256 bits?</h3> <p>256 bits (1 word) allows the mix-in to be simple, consistent with the length mix-in for lists, and is practically sufficient. An alternate design with a <code>ProgressiveBitlist</code> mix-in was explored, however deemed too over-engineered as it would effectively require introducing caches to pre-compute the mix-in's <code>hash_tree_root</code> to avoid repeated computations, and also makes verifier logic more complex than necessary.</p> <p>Even though the 256 field limit includes all fields (including deprecated ones), it is unlikely that many progressive containers come close to reach 256 fields (<code>BeaconState</code> currently reaches around 40 fields). If that happens, one can add a <code>more</code> field with a nested <code>ProgressiveContainer</code>.</p> <h3 id="why-is-empty-progressivecontainer-an-illegal-type">Why is empty <code>ProgressiveContainer</code> an illegal type?</h3> <p>It would result in 0-length serialization, meaning that the length of a list of such a container cannot be determined from the serialization.</p> <h3 id="optional-type"><code>Optional[type]</code>?</h3> <p>Introducing <code>Optional</code> is not required by any current functionality and is deferred to a future EIP.</p> <p>The <code>active_fields</code> bitvector can be updated to also indicate optionality. Further, serialization for sparse lists should be explored.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><code>ProgressiveContainer(active_fields)</code> is a new SSZ type and does not conflict with existing types.</p> <h2 id="test-cases">Test Cases</h2> <ul> <li><code>ethereum/remerkleable</code> contains static tests in <code>test_impl.py</code> and <code>test_typing.py</code>.</li> <li><code>ethereum/consensus-specs</code> releases contain random tests in <code>tests/general/phase0/ssz_generic</code>, generated according to a format defined in <code>tests/format/ssz_generic</code>.</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <code>ethereum/remerkleable</code>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Light client based verifiers and smart contracts (e.g., based on <a href="https://wg-eips.ritovision.com/4788/">EIP-4788</a>) do not update at the same cadence as Ethereum. If a future fork removes a field from a <code>ProgressiveContainer(active_fields)</code>, the <code>active_fields</code> mix-in enables such verifiers to distinguish absent fields from <code>0</code> values. Without <code>active_fields</code>, the <code>hash_tree_root</code> for these cases would collide.</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-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Steven Pinedahttps://github.com/steven2308 Jan Turkhttps://github.com/ThunderDeliverer https://wg-eips.ritovision.com/7508/

Dynamic on-chain storage of token attributes in a public-good repository.

<h2 id="abstract">Abstract</h2> <p>The Public On-Chain Non-Fungible Token Attributes Repository standard provides the ability for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> compatible tokens to store their attributes on-chain available to any external smart contract interacting with them.</p> <p>This proposal introduces the ability to assign attributes to NFTs in a public non-gated repository smart contract that is accessible at the same address in all of the networks. The repository smart contract is designed to be a common-good repository, meaning that it can be used by any ERC-721 or ERC-1155 compatible token.</p> <h2 id="motivation">Motivation</h2> <p>With NFTs being a widespread form of tokens in the Ethereum ecosystem and being used for a variety of use cases, it is time to standardize additional utility for them. Having the ability to store token's attributes on chain allows for greater utility of tokens as it fosters cross-collection interactivity and provides perpetual store of attributes.</p> <p>This ERC introduces new utilities for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> based tokens in the following areas:</p> <ul> <li><a href="https://wg-eips.ritovision.com/7508/#cross-collection-interactivity">Cross-Collection interactivity</a></li> <li><a href="https://wg-eips.ritovision.com/7508/#perpetual-store-of-attributes">Perpetual Store of Attributes</a></li> <li><a href="https://wg-eips.ritovision.com/7508/#token-evolution">Token Evolution</a></li> <li><a href="https://wg-eips.ritovision.com/7508/#dynamic-state-tracking">Dynamic State Tracking</a></li> </ul> <h3 id="cross-collection-interactivity">Cross-Collection Interactivity</h3> <p>Storing attributes on-chain in a predictable format allows for cross-collection interactivity. This means that the attributes of a token can be used by any external smart contract without the need for the token to be aware of the external smart contract.</p> <p>For example, a token can represent a game character with its set of attributes and can be used in an unrelated game with the same stats without the need for retrieving these attributes from an off-chain source. This ensures that the data the game is using is legitimate and not tampered with in order to gain an advantage.</p> <h3 id="perpetual-store-of-attributes">Perpetual Store of Attributes</h3> <p>Standardized on-chain token attributes allow for their perpetual storage.</p> <p>With off-chain attributes storage, the attributes are only available as long as the off-chain storage is available. If the storage is taken down, the attributes are lost. With on-chain attributes storage, the attributes are available as long as the blockchain is available. This increases the value of the token as it ensures that the attributes are available for as long as the token exists.</p> <h3 id="token-evolution">Token Evolution</h3> <p>On-Chain storage of token attributes allows for the token to evolve over time. Owner's actions can impact the attributes of the token. Since the attributes are stored on chain, the smart contract has the ability to modify the attribute once certain thresholds are met. This allows for token to become more interactive and reflect owner's dedication and effort.</p> <h3 id="dynamic-state-tracking">Dynamic State Tracking</h3> <p>On-Chain storage of token attributes allows for dynamic state tracking. The attributes can be used to track the state of the token and its owner. This allows for the token to be used in a variety of use cases. One such use case is supply chains; the token can represent a product and its attributes can be used to track the state of the product as it transitions from pending, shipped, delivered, etc.</p> <h2 id="specification">Specification</h2> <h3 id="interface">Interface</h3> <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-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-7508 Public On-Chain NFT Attributes Repository</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-7508</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 ERC-165 identifier for this interface is 0x212206a8.</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.21</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"> IERC7508</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"> A list of supported access types.</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"> `Owner` type, where only the owner can manage the parameter.</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"> `Collaborator` type, where only the collaborators can manage the parameter.</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"> `OwnerOrCollaborator` type, where only the owner or collaborators can manage the parameter.</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"> `TokenOwner` type, where only the token owner can manage the parameters of their 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"> The</span><span class="z-comment"> `SpecificAddress` type, where only specific addresses can manage the parameter.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> AccessType</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Owner</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Collaborator</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> OwnerOrCollaborator</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> TokenOwner</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> SpecificAddress</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"> Structure used to represent an address attribute.</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"> key</span><span class="z-comment"> The key of the attribute</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"> The value of the attribute</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"> AddressAttribute</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> key</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Structure used to represent a boolean attribute.</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"> key</span><span class="z-comment"> The key of the attribute</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"> The value of the attribute</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"> BoolAttribute</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> key</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Structure used to represent a bytes attribute.</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"> key</span><span class="z-comment"> The key of the attribute</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"> The value of the attribute</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"> BytesAttribute</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> key</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Structure used to represent an int attribute.</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"> key</span><span class="z-comment"> The key of the attribute</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"> The value of the attribute</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"> IntAttribute</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> key</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> int256</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Structure used to represent a string attribute.</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"> key</span><span class="z-comment"> The key of the attribute</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"> The value of the attribute</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"> StringAttribute</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> key</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 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"> Structure used to represent an uint attribute.</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"> key</span><span class="z-comment"> The key of the attribute</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"> The value of the attribute</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"> UintAttribute</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> key</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> }</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"> Used to notify listeners that a new collection has been registered to use the repository.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collection</span><span class="z-comment"> Address of the collection</span></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 of the owner of the collection; the addess authorized to manage the access control</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> registeringAddress</span><span class="z-comment"> Address that registered the collection</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> useOwnable</span><span class="z-comment"> A boolean value indicating whether the collection uses the Ownable extension to verify the</span></span> <span class="giallo-l"><span class="z-comment"> * owner (`true`) or not (`false`)</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"> AccessControlRegistration</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"> collection</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"> registeringAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> useOwnable</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"> Used to notify listeners that the access control settings for a specific parameter have been updated.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collection</span><span class="z-comment"> Address of the collection</span></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"> The name of the parameter for which the access control settings have been updated</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> accessType</span><span class="z-comment"> The AccessType of the parameter for which the access control settings have been updated</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> specificAddress</span><span class="z-comment"> The specific addresses that has been updated</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"> AccessControlUpdate</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"> collection</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> AccessType</span><span class="z-variable"> accessType</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> specificAddress</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"> Used to notify listeners that the metadata URI for a collection has been updated.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collection</span><span class="z-comment"> Address of the collection</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> attributesMetadataURI</span><span class="z-comment"> The new attributes metadata URI</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"> MetadataURIUpdated</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"> collection</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> attributesMetadataURI</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"> Used to notify listeners that a new collaborator has been added or 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"> collection</span><span class="z-comment"> Address of the collection</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collaborator</span><span class="z-comment"> Address of the collaborator</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> isCollaborator</span><span class="z-comment"> A boolean value indicating whether the collaborator has been added (`true`) or removed</span></span> <span class="giallo-l"><span class="z-comment"> * (`false`)</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"> CollaboratorUpdate</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"> collection</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"> collaborator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> isCollaborator</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"> Used to notify listeners that an address attribute has been updated.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collection</span><span class="z-comment"> The collection 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"> The 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"> key</span><span class="z-comment"> The key of the 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"> value</span><span class="z-comment"> The new value of the attribute</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"> AddressAttributeUpdated</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"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> value</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"> Used to notify listeners that a boolean attribute has been updated.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collection</span><span class="z-comment"> The collection 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"> The 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"> key</span><span class="z-comment"> The key of the 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"> value</span><span class="z-comment"> The new value of the attribute</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"> BoolAttributeUpdated</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"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> value</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"> Used to notify listeners that a bytes attribute has been updated.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collection</span><span class="z-comment"> The collection 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"> The 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"> key</span><span class="z-comment"> The key of the 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"> value</span><span class="z-comment"> The new value of the attribute</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"> BytesAttributeUpdated</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"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> value</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"> Used to notify listeners that an int attribute has been updated.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collection</span><span class="z-comment"> The collection 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"> The 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"> key</span><span class="z-comment"> The key of the 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"> value</span><span class="z-comment"> The new value of the attribute</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"> IntAttributeUpdated</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"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> int256</span><span class="z-variable"> value</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"> Used to notify listeners that a string attribute has been updated.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collection</span><span class="z-comment"> The collection 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"> The 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"> key</span><span class="z-comment"> The key of the 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"> value</span><span class="z-comment"> The new value of the attribute</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"> StringAttributeUpdated</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"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> value</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"> Used to notify listeners that an uint attribute has been updated.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collection</span><span class="z-comment"> The collection 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"> The 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"> key</span><span class="z-comment"> The key of the 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"> value</span><span class="z-comment"> The new value of the attribute</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"> UintAttributeUpdated</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"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> value</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"> ------------------- ACCESS CONTROL -------------------</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"> Used to check if the specified address is listed as a collaborator of the given collection&#39;s 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"> collaborator</span><span class="z-comment"> Address to be checked.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collection</span><span class="z-comment"> Address of the collection.</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"> isCollaborator_</span><span class="z-comment"> Boolean value indicating if the address is a collaborator of the given collection&#39;s (`true`) or not</span></span> <span class="giallo-l"><span class="z-comment"> * (`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"> isCollaborator</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collaborator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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 class="z-variable"> isCollaborator_</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"> Used to check if the specified address is listed as a specific address of the given collection&#39;s</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> specificAddress</span><span class="z-comment"> Address to be checked.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collection</span><span class="z-comment"> Address of the collection.</span></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"> The key of the attribute</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"> isSpecificAddress_</span><span class="z-comment"> Boolean value indicating if the address is a specific address of the given collection&#39;s parameter</span></span> <span class="giallo-l"><span class="z-comment"> * (`true`) or not (`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"> isSpecificAddress</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> specificAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</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 class="z-variable"> isSpecificAddress_</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"> Used to register a collection to use the RMRK token attributes repository.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If the collection does not implement the Ownable interface, the `useOwnable` value must be set to `false`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits an {AccessControlRegistration} 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"> collection</span><span class="z-comment"> The address of the collection that will use the RMRK token attributes repository.</span></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"> The address of the owner of the collection.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> useOwnable</span><span class="z-comment"> The boolean value to indicate if the collection implements the Ownable interface and whether it</span></span> <span class="giallo-l"><span class="z-comment"> * should be used to validate that the caller is the owner (`true`) or to use the manually set owner address</span></span> <span class="giallo-l"><span class="z-comment"> * (`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"> registerAccessControl</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> bool</span><span class="z-variable"> useOwnable</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"> Used to manage the access control settings for a specific parameter.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Only the `owner` of the collection can call this function.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The possible `accessType` values are:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * Owner,</span></span> <span class="giallo-l"><span class="z-comment"> * Collaborator,</span></span> <span class="giallo-l"><span class="z-comment"> * OwnerOrCollaborator,</span></span> <span class="giallo-l"><span class="z-comment"> * TokenOwner,</span></span> <span class="giallo-l"><span class="z-comment"> * SpecificAddress,</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"> Emits an {AccessControlUpdated} 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"> collection</span><span class="z-comment"> The address of the collection being managed.</span></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"> The key of the 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"> accessType</span><span class="z-comment"> The type of access control to be applied to 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"> specificAddress</span><span class="z-comment"> The address to be added as a specific addresses allowed to manage the given</span></span> <span class="giallo-l"><span class="z-comment"> * parameter.</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"> manageAccessControl</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> AccessType</span><span class="z-variable"> accessType</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> specificAddress</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"> Used to manage the collaborators of a collection.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The `collaboratorAddresses` and `collaboratorAddressAccess` arrays must be of the same length.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {CollaboratorUpdate} 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"> collection</span><span class="z-comment"> The address of the collection</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collaboratorAddresses</span><span class="z-comment"> The array of collaborator addresses being managed</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collaboratorAddressAccess</span><span class="z-comment"> The array of boolean values indicating if the collaborator address should</span></span> <span class="giallo-l"><span class="z-comment"> * receive the permission (`true`) or not (`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"> manageCollaborators</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> collaboratorAddresses</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> collaboratorAddressAccess</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"> ------------------- METADATA URI -------------------</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"> Used to retrieve the attributes metadata URI for a collection, which contains all the information about the collection 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"> collection</span><span class="z-comment"> Address of the collection</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"> attributesMetadataURI</span><span class="z-comment"> The URI of the attributes metadata</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"> getAttributesMetadataURIForCollection</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributesMetadataURI</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"> Used to set the metadata URI for a collection, which contains all the information about the collection attributes.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {MetadataURIUpdated} 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"> collection</span><span class="z-comment"> Address of the collection</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> attributesMetadataURI</span><span class="z-comment"> The URI of the attributes metadata</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"> setAttributesMetadataURIForCollection</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> attributesMetadataURI</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"> ------------------- GETTERS -------------------</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"> Used to retrieve the address type token 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"> collection</span><span class="z-comment"> The collection 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"> The 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"> key</span><span class="z-comment"> The key of the attribute</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"> attribute</span><span class="z-comment"> The value of the address attribute</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"> getAddressAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</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">address</span><span class="z-variable"> attribute</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"> Used to retrieve the bool type token 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"> collection</span><span class="z-comment"> The collection 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"> The 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"> key</span><span class="z-comment"> The key of the attribute</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"> attribute</span><span class="z-comment"> The value of the bool attribute</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"> getBoolAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</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 class="z-variable"> attribute</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"> Used to retrieve the bytes type token 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"> collection</span><span class="z-comment"> The collection 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"> The 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"> key</span><span class="z-comment"> The key of the attribute</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"> attribute</span><span class="z-comment"> The value of the bytes attribute</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"> getBytesAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</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">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attribute</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"> Used to retrieve the uint type token 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"> collection</span><span class="z-comment"> The collection 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"> The 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"> key</span><span class="z-comment"> The key of the attribute</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"> attribute</span><span class="z-comment"> The value of the uint attribute</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"> getUintAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</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"> attribute</span><span>)</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"> Used to retrieve the string type token 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"> collection</span><span class="z-comment"> The collection 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"> The 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"> key</span><span class="z-comment"> The key of the attribute</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"> attribute</span><span class="z-comment"> The value of the string attribute</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"> getStringAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</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">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attribute</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"> Used to retrieve the int type token 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"> collection</span><span class="z-comment"> The collection 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"> The 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"> key</span><span class="z-comment"> The key of the attribute</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"> attribute</span><span class="z-comment"> The value of the uint attribute</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"> getIntAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</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">int256</span><span class="z-variable"> attribute</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ------------------- BATCH GETTERS -------------------</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"> Used to get multiple address parameter values 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"> The `AddressAttribute` struct contains the following fields:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * string key,</span></span> <span class="giallo-l"><span class="z-comment"> * address value</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"> collections</span><span class="z-comment"> Addresses of the collections, in the same order as the attribute keys. If all tokens are from the same collection the array can contain a single element with the collection 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"> tokenIds</span><span class="z-comment"> IDs of the tokens, in the same order as the attribute keys. If all attributes are for the same token the array can contain a single element with the 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"> attributeKeys</span><span class="z-comment"> An array of address keys to retrieve</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"> attributes</span><span class="z-comment"> An array of addresses, in the same order as the attribute keys</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"> getAddressAttributes</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"> collections</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"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributeKeys</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">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributes</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"> Used to get multiple bool parameter values 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"> The `BoolAttribute` struct contains the following fields:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * string key,</span></span> <span class="giallo-l"><span class="z-comment"> * bool value</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"> collections</span><span class="z-comment"> Addresses of the collections, in the same order as the attribute keys. If all tokens are from the same collection the array can contain a single element with the collection 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"> tokenIds</span><span class="z-comment"> IDs of the tokens, in the same order as the attribute keys. If all attributes are for the same token the array can contain a single element with the 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"> attributeKeys</span><span class="z-comment"> An array of bool keys to retrieve</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"> attributes</span><span class="z-comment"> An array of bools, in the same order as the attribute keys</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"> getBoolAttributes</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"> collections</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"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributeKeys</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 class="z-storage z-type"> memory</span><span class="z-variable"> attributes</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"> Used to get multiple bytes parameter values 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"> The `BytesAttribute` struct contains the following fields:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * string key,</span></span> <span class="giallo-l"><span class="z-comment"> * bytes value</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"> collections</span><span class="z-comment"> Addresses of the collections, in the same order as the attribute keys. If all tokens are from the same collection the array can contain a single element with the collection 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"> tokenIds</span><span class="z-comment"> IDs of the tokens, in the same order as the attribute keys. If all attributes are for the same token the array can contain a single element with the 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"> attributeKeys</span><span class="z-comment"> An array of bytes keys to retrieve</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"> attributes</span><span class="z-comment"> An array of bytes, in the same order as the attribute keys</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"> getBytesAttributes</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"> collections</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"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributeKeys</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">bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributes</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"> Used to get multiple int parameter values for 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"> collections</span><span class="z-comment"> Addresses of the collections, in the same order as the attribute keys. If all tokens are from the same collection the array can contain a single element with the collection 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"> tokenIds</span><span class="z-comment"> IDs of the tokens, in the same order as the attribute keys. If all attributes are for the same token the array can contain a single element with the 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"> attributeKeys</span><span class="z-comment"> An array of int keys to retrieve</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"> attributes</span><span class="z-comment"> An array of ints, in the same order as the attribute keys</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"> getIntAttributes</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"> collections</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"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributeKeys</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">int256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributes</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"> Used to get multiple sting parameter values for 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"> collections</span><span class="z-comment"> Addresses of the collections, in the same order as the attribute keys. If all tokens are from the same collection the array can contain a single element with the collection 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"> tokenIds</span><span class="z-comment"> IDs of the tokens, in the same order as the attribute keys. If all attributes are for the same token the array can contain a single element with the 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"> attributeKeys</span><span class="z-comment"> An array of string keys to retrieve</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"> attributes</span><span class="z-comment"> An array of strings, in the same order as the attribute keys</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"> getStringAttributes</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"> collections</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"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributeKeys</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">string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributes</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"> Used to get multiple uint parameter values for 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"> collections</span><span class="z-comment"> Addresses of the collections, in the same order as the attribute keys. If all tokens are from the same collection the array can contain a single element with the collection 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"> tokenIds</span><span class="z-comment"> IDs of the tokens, in the same order as the attribute keys. If all attributes are for the same token the array can contain a single element with the 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"> attributeKeys</span><span class="z-comment"> An array of uint keys to retrieve</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"> attributes</span><span class="z-comment"> An array of uints, in the same order as the attribute keys</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"> getUintAttributes</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"> collections</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"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributeKeys</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 class="z-storage z-type"> memory</span><span class="z-variable"> attributes</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"> Used to retrieve multiple token attributes of any type at once.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The `StringAttribute`, `UintAttribute`, `IntAttribute`, `BoolAttribute`, `AddressAttribute` and `BytesAttribute` structs consists</span></span> <span class="giallo-l"><span class="z-comment"> * to the following fields (where `value` is of the appropriate type):</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * key,</span></span> <span class="giallo-l"><span class="z-comment"> * value,</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"> collection</span><span class="z-comment"> The collection 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"> The 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"> addressKeys</span><span class="z-comment"> An array of address type attribute keys to retrieve</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> boolKeys</span><span class="z-comment"> An array of bool type attribute keys to retrieve</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> bytesKeys</span><span class="z-comment"> An array of bytes type attribute keys to retrieve</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> intKeys</span><span class="z-comment"> An array of int type attribute keys to retrieve</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> stringKeys</span><span class="z-comment"> An array of string type attribute keys to retrieve</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> uintKeys</span><span class="z-comment"> An array of uint type attribute keys to retrieve</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"> addressAttributes</span><span class="z-comment"> An array of addresses, in the same order as the addressKeys</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"> boolAttributes</span><span class="z-comment"> An array of bools, in the same order as the boolKeys</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"> bytesAttributes</span><span class="z-comment"> An array of bytes, in the same order as the bytesKeys</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"> intAttributes</span><span class="z-comment"> An array of ints, in the same order as the intKeys</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"> stringAttributes</span><span class="z-comment"> An array of strings, in the same order as the stringKeys</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"> uintAttributes</span><span class="z-comment"> An array of uints, in the same order as the uintKeys</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"> getAttributes</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> addressKeys</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> boolKeys</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> bytesKeys</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> intKeys</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> stringKeys</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> uintKeys</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-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>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> addressAttributes</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> boolAttributes</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> bytesAttributes</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> int256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> intAttributes</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> stringAttributes</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"> uintAttributes</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"> ------------------- PREPARE PRESIGNED MESSAGES -------------------</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"> Used to retrieve the message to be signed for submitting a presigned address attribute 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"> collection</span><span class="z-comment"> The address of the collection smart contract of the token receiving the 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"> tokenId</span><span class="z-comment"> The ID of the token receiving the 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"> key</span><span class="z-comment"> The attribute key</span></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 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"> deadline</span><span class="z-comment"> The deadline timestamp for the presigned transaction after which the message is invalid</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"> message</span><span class="z-comment"> Raw message to be signed by the authorized account</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"> prepareMessageToPresignAddressAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</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">bytes32</span><span class="z-variable"> message</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"> Used to retrieve the message to be signed for submitting a presigned bool attribute 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"> collection</span><span class="z-comment"> The address of the collection smart contract of the token receiving the 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"> tokenId</span><span class="z-comment"> The ID of the token receiving the 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"> key</span><span class="z-comment"> The attribute key</span></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 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"> deadline</span><span class="z-comment"> The deadline timestamp for the presigned transaction after which the message is invalid</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"> message</span><span class="z-comment"> Raw message to be signed by the authorized account</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"> prepareMessageToPresignBoolAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</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">bytes32</span><span class="z-variable"> message</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"> Used to retrieve the message to be signed for submitting a presigned bytes attribute 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"> collection</span><span class="z-comment"> The address of the collection smart contract of the token receiving the 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"> tokenId</span><span class="z-comment"> The ID of the token receiving the 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"> key</span><span class="z-comment"> The attribute key</span></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 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"> deadline</span><span class="z-comment"> The deadline timestamp for the presigned transaction after which the message is invalid</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"> message</span><span class="z-comment"> Raw message to be signed by the authorized account</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"> prepareMessageToPresignBytesAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</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"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</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">bytes32</span><span class="z-variable"> message</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"> Used to retrieve the message to be signed for submitting a presigned int attribute 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"> collection</span><span class="z-comment"> The address of the collection smart contract of the token receiving the 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"> tokenId</span><span class="z-comment"> The ID of the token receiving the 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"> key</span><span class="z-comment"> The attribute key</span></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 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"> deadline</span><span class="z-comment"> The deadline timestamp for the presigned transaction after which the message is invalid</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"> message</span><span class="z-comment"> Raw message to be signed by the authorized account</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"> prepareMessageToPresignIntAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> int256</span><span class="z-variable"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</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">bytes32</span><span class="z-variable"> message</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"> Used to retrieve the message to be signed for submitting a presigned string attribute 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"> collection</span><span class="z-comment"> The address of the collection smart contract of the token receiving the 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"> tokenId</span><span class="z-comment"> The ID of the token receiving the 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"> key</span><span class="z-comment"> The attribute key</span></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 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"> deadline</span><span class="z-comment"> The deadline timestamp for the presigned transaction after which the message is invalid</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"> message</span><span class="z-comment"> Raw message to be signed by the authorized account</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"> prepareMessageToPresignStringAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</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"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</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">bytes32</span><span class="z-variable"> message</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"> Used to retrieve the message to be signed for submitting a presigned uint attribute 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"> collection</span><span class="z-comment"> The address of the collection smart contract of the token receiving the 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"> tokenId</span><span class="z-comment"> The ID of the token receiving the 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"> key</span><span class="z-comment"> The attribute key</span></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 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"> deadline</span><span class="z-comment"> The deadline timestamp for the presigned transaction after which the message is invalid</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"> message</span><span class="z-comment"> Raw message to be signed by the authorized account</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"> prepareMessageToPresignUintAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</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"> deadline</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">bytes32</span><span class="z-variable"> message</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ------------------- SETTERS -------------------</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"> Used to set an address attribute.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {AddressAttributeUpdated} 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"> collection</span><span class="z-comment"> Address of the collection receiving the 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"> tokenId</span><span class="z-comment"> The 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"> key</span><span class="z-comment"> The attribute key</span></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 attribute value</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"> setAddressAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> value</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"> Used to set a boolean attribute.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {BoolAttributeUpdated} 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"> collection</span><span class="z-comment"> Address of the collection receiving the 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"> tokenId</span><span class="z-comment"> The 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"> key</span><span class="z-comment"> The attribute key</span></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 attribute value</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"> setBoolAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> value</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"> Used to set an bytes attribute.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {BytesAttributeUpdated} 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"> collection</span><span class="z-comment"> Address of the collection receiving the 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"> tokenId</span><span class="z-comment"> The 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"> key</span><span class="z-comment"> The attribute key</span></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 attribute value</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"> setBytesAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</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"> value</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"> Used to set a signed number attribute.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {IntAttributeUpdated} 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"> collection</span><span class="z-comment"> Address of the collection receiving the 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"> tokenId</span><span class="z-comment"> The 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"> key</span><span class="z-comment"> The attribute key</span></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 attribute value</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"> setIntAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> int256</span><span class="z-variable"> value</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"> Used to set a string attribute.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {StringAttributeUpdated} 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"> collection</span><span class="z-comment"> Address of the collection receiving the 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"> tokenId</span><span class="z-comment"> The 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"> key</span><span class="z-comment"> The attribute key</span></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 attribute value</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"> setStringAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</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"> value</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"> Used to set an unsigned number attribute.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {UintAttributeUpdated} 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"> collection</span><span class="z-comment"> Address of the collection receiving the 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"> tokenId</span><span class="z-comment"> The 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"> key</span><span class="z-comment"> The attribute key</span></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 attribute value</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"> setUintAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> value</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"> ------------------- BATCH SETTERS -------------------</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"> Sets multiple address attributes for a token at once.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The `AddressAttribute` struct contains the following fields:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * string key,</span></span> <span class="giallo-l"><span class="z-comment"> * address value</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"> collections</span><span class="z-comment"> Addresses of the collections, in the same order as the attributes. If all tokens are from the same collection the array can contain a single element with the collection 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"> tokenIds</span><span class="z-comment"> IDs of the tokens, in the same order as the attributes. If all attributes are for the same token the array can contain a single element with the 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"> attributes</span><span class="z-comment"> An array of `AddressAttribute` structs to be assigned to the given 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"> setAddressAttributes</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"> collections</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-storage z-type"> AddressAttribute</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributes</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"> Sets multiple bool attributes for a token at once.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The `BoolAttribute` struct contains the following fields:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * string key,</span></span> <span class="giallo-l"><span class="z-comment"> * bool value</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"> collections</span><span class="z-comment"> Addresses of the collections, in the same order as the attributes. If all tokens are from the same collection the array can contain a single element with the collection 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"> tokenIds</span><span class="z-comment"> IDs of the tokens, in the same order as the attributes. If all attributes are for the same token the array can contain a single element with the 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"> attributes</span><span class="z-comment"> An array of `BoolAttribute` structs to be assigned to the given 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"> setBoolAttributes</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"> collections</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-storage z-type"> BoolAttribute</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributes</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"> Sets multiple bytes attributes for a token at once.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The `BytesAttribute` struct contains the following fields:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * string key,</span></span> <span class="giallo-l"><span class="z-comment"> * bytes value</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"> collections</span><span class="z-comment"> Addresses of the collections, in the same order as the attributes. If all tokens are from the same collection the array can contain a single element with the collection 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"> tokenIds</span><span class="z-comment"> IDs of the tokens, in the same order as the attributes. If all attributes are for the same token the array can contain a single element with the 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"> attributes</span><span class="z-comment"> An array of `BytesAttribute` structs to be assigned to the given 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"> setBytesAttributes</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"> collections</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-storage z-type"> BytesAttribute</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributes</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"> Sets multiple int attributes for a token at once.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The `UintAttribute` struct contains the following fields:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * string key,</span></span> <span class="giallo-l"><span class="z-comment"> * int value</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"> collections</span><span class="z-comment"> Addresses of the collections, in the same order as the attributes. If all tokens are from the same collection the array can contain a single element with the collection 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"> tokenIds</span><span class="z-comment"> IDs of the tokens, in the same order as the attributes. If all attributes are for the same token the array can contain a single element with the 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"> attributes</span><span class="z-comment"> An array of `IntAttribute` structs to be assigned to the given 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"> setIntAttributes</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"> collections</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-storage z-type"> IntAttribute</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributes</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"> Sets multiple string attributes for a token at once.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The `StringAttribute` struct contains the following fields:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * string key,</span></span> <span class="giallo-l"><span class="z-comment"> * string value</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"> collections</span><span class="z-comment"> Addresses of the collections, in the same order as the attributes. If all tokens are from the same collection the array can contain a single element with the collection 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"> tokenIds</span><span class="z-comment"> IDs of the tokens, in the same order as the attributes. If all attributes are for the same token the array can contain a single element with the 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"> attributes</span><span class="z-comment"> An array of `StringAttribute` structs to be assigned to the given 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"> setStringAttributes</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"> collections</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-storage z-type"> StringAttribute</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributes</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"> Sets multiple uint attributes for a token at once.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The `UintAttribute` struct contains the following fields:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * string key,</span></span> <span class="giallo-l"><span class="z-comment"> * uint value</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"> collections</span><span class="z-comment"> Addresses of the collections, in the same order as the attributes. If all tokens are from the same collection the array can contain a single element with the collection 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"> tokenIds</span><span class="z-comment"> IDs of the tokens, in the same order as the attributes. If all attributes are for the same token the array can contain a single element with the 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"> attributes</span><span class="z-comment"> An array of `UintAttribute` structs to be assigned to the given 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"> setUintAttributes</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"> collections</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-storage z-type"> UintAttribute</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attributes</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"> Sets multiple attributes of multiple types for a token at the same time.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a separate event for each attribute set.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The `StringAttribute`, `UintAttribute`, `BoolAttribute`, `AddressAttribute` and `BytesAttribute` structs consists</span></span> <span class="giallo-l"><span class="z-comment"> * to the following fields (where `value` is of the appropriate type):</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * key,</span></span> <span class="giallo-l"><span class="z-comment"> * value,</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"> collection</span><span class="z-comment"> The address of the collection</span></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</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> addressAttributes</span><span class="z-comment"> An array of `AddressAttribute` structs containing address attributes to 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"> boolAttributes</span><span class="z-comment"> An array of `BoolAttribute` structs containing bool attributes to 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"> bytesAttributes</span><span class="z-comment"> An array of `BytesAttribute` structs containing bytes attributes to 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"> intAttributes</span><span class="z-comment"> An array of `IntAttribute` structs containing int attributes to 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"> stringAttributes</span><span class="z-comment"> An array of `StringAttribute` structs containing string attributes to 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"> uintAttributes</span><span class="z-comment"> An array of `UintAttribute` structs containing uint attributes 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"> setAttributes</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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-storage z-type"> AddressAttribute</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> addressAttributes</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> BoolAttribute</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> boolAttributes</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> BytesAttribute</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> bytesAttributes</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> IntAttribute</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> intAttributes</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> StringAttribute</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> stringAttributes</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> UintAttribute</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> uintAttributes</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"> ------------------- PRESIGNED SETTERS -------------------</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"> Used to set the address attribute on behalf of an authorized account.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {AddressAttributeUpdated} 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"> setter</span><span class="z-comment"> Address of the account that presigned the attribute 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"> collection</span><span class="z-comment"> Address of the collection receiving the 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"> tokenId</span><span class="z-comment"> The ID of the token receiving the 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"> key</span><span class="z-comment"> The attribute key</span></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 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"> deadline</span><span class="z-comment"> The deadline timestamp for the presigned 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"> v</span><span class="z-comment"> `v` value of an ECDSA signature of the presigned message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> r</span><span class="z-comment"> `r` value of an ECDSA signature of the presigned message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> s</span><span class="z-comment"> `s` value of an ECDSA signature of the presigned message</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"> presignedSetAddressAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> setter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</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"> Used to set the bool attribute on behalf of an authorized account.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {BoolAttributeUpdated} 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"> setter</span><span class="z-comment"> Address of the account that presigned the attribute 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"> collection</span><span class="z-comment"> Address of the collection receiving the 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"> tokenId</span><span class="z-comment"> The ID of the token receiving the 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"> key</span><span class="z-comment"> The attribute key</span></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 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"> deadline</span><span class="z-comment"> The deadline timestamp for the presigned 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"> v</span><span class="z-comment"> `v` value of an ECDSA signature of the presigned message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> r</span><span class="z-comment"> `r` value of an ECDSA signature of the presigned message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> s</span><span class="z-comment"> `s` value of an ECDSA signature of the presigned message</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"> presignedSetBoolAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> setter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</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"> Used to set the bytes attribute on behalf of an authorized account.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {BytesAttributeUpdated} 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"> setter</span><span class="z-comment"> Address of the account that presigned the attribute 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"> collection</span><span class="z-comment"> Address of the collection receiving the 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"> tokenId</span><span class="z-comment"> The ID of the token receiving the 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"> key</span><span class="z-comment"> The attribute key</span></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 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"> deadline</span><span class="z-comment"> The deadline timestamp for the presigned 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"> v</span><span class="z-comment"> `v` value of an ECDSA signature of the presigned message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> r</span><span class="z-comment"> `r` value of an ECDSA signature of the presigned message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> s</span><span class="z-comment"> `s` value of an ECDSA signature of the presigned message</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"> presignedSetBytesAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> setter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</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"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</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"> Used to set the int attribute on behalf of an authorized account.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {IntAttributeUpdated} 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"> setter</span><span class="z-comment"> Address of the account that presigned the attribute 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"> collection</span><span class="z-comment"> Address of the collection receiving the 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"> tokenId</span><span class="z-comment"> The ID of the token receiving the 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"> key</span><span class="z-comment"> The attribute key</span></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 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"> deadline</span><span class="z-comment"> The deadline timestamp for the presigned 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"> v</span><span class="z-comment"> `v` value of an ECDSA signature of the presigned message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> r</span><span class="z-comment"> `r` value of an ECDSA signature of the presigned message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> s</span><span class="z-comment"> `s` value of an ECDSA signature of the presigned message</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"> presignedSetIntAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> setter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> int256</span><span class="z-variable"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</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"> Used to set the string attribute on behalf of an authorized account.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {StringAttributeUpdated} 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"> setter</span><span class="z-comment"> Address of the account that presigned the attribute 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"> collection</span><span class="z-comment"> Address of the collection receiving the 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"> tokenId</span><span class="z-comment"> The ID of the token receiving the 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"> key</span><span class="z-comment"> The attribute key</span></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 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"> deadline</span><span class="z-comment"> The deadline timestamp for the presigned 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"> v</span><span class="z-comment"> `v` value of an ECDSA signature of the presigned message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> r</span><span class="z-comment"> `r` value of an ECDSA signature of the presigned message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> s</span><span class="z-comment"> `s` value of an ECDSA signature of the presigned message</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"> presignedSetStringAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> setter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</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"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</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"> Used to set the uint attribute on behalf of an authorized account.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {UintAttributeUpdated} 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"> setter</span><span class="z-comment"> Address of the account that presigned the attribute 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"> collection</span><span class="z-comment"> Address of the collection receiving the 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"> tokenId</span><span class="z-comment"> The ID of the token receiving the 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"> key</span><span class="z-comment"> The attribute key</span></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 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"> deadline</span><span class="z-comment"> The deadline timestamp for the presigned 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"> v</span><span class="z-comment"> `v` value of an ECDSA signature of the presigned message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> r</span><span class="z-comment"> `r` value of an ECDSA signature of the presigned message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> s</span><span class="z-comment"> `s` value of an ECDSA signature of the presigned message</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"> presignedSetUintAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> setter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> key</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"> deadline</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</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><h3 id="schema">Schema</h3> <p>In addition to the interface we propose that collection owers SHOULD be able to set the schema for the attributes of their collection. We distinguish between 2 types: token attributes and collection attributes. The latter are the attributes that are shared by all tokens in the collection, they can be retrieved and set by using the max uint256 value as tokenId.</p> <p>For each attribute we specify the following fields: name, description, type, display_name, display_type, decimals, min_value, max_value, conditional_value, modifiers and multi_storage. Only name and type are required. For more details on the fields, please refer to the [JSON schema] available <a href="https://wg-eips.ritovision.com/7508/./assets/collection-metadata-schema.json"><code>collection-metadata-schema.json</code></a>, with an example available at <a href="https://wg-eips.ritovision.com/7508/./assets/collection-metadata-example.json"><code>collection-metadata-example.json</code></a>.</p> <p>The reasoning for conditional_value, modifiers and multi_storage will be discussed in the rationale section.</p> <h3 id="message-format-for-presigned-attribute">Message format for presigned attribute</h3> <p>The message to be signed by the <code>setter</code> in order for the attribute setting to be submitted by someone else is formatted 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">encode</span><span>(</span></span> <span class="giallo-l"><span> DOMAIN_SEPARATOR</span><span>,</span></span> <span class="giallo-l"><span> METHOD_TYPEHASH</span><span>,</span></span> <span class="giallo-l"><span> collection</span><span>,</span></span> <span class="giallo-l"><span> tokenId</span><span>,</span></span> <span class="giallo-l"><span> key</span><span>,</span></span> <span class="giallo-l"><span> value</span><span>,</span></span> <span class="giallo-l"><span> deadline</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> )</span><span>;</span></span></code></pre> <p>The values passed when generating the message to be signed are:</p> <ul> <li><code>DOMAIN_SEPARATOR</code> - The domain separator of the Attribute repository smart contract</li> <li><code>METHOD_TYPEHASH</code> - The typehash of the method being called. The supported values, depending on the method are: <ul> <li><code>SET_UINT_ATTRIBUTE_TYPEHASH</code> - Used for setting uint attributes</li> <li><code>SET_STRING_ATTRIBUTE_TYPEHASH</code> - Used for setting string attributes</li> <li><code>SET_BOOL_ATTRIBUTE_TYPEHASH</code> - Used for setting bool attributes</li> <li><code>SET_BYTES_ATTRIBUTE_TYPEHASH</code> - Used for setting bytes attributes</li> <li><code>SET_ADDRESS_ATTRIBUTE_TYPEHASH</code> - Used for setting address attributes</li> </ul> </li> <li><code>collection</code> - Address of the collection containing the token receiving the attribute</li> <li><code>tokenId</code> - ID of the token receiving the attribute</li> <li><code>key</code> - The attribute key</li> <li><code>value</code> - The attribute value of the appropriate type</li> <li><code>deadline</code> - UNIX timestamp of the deadline for the signature to be submitted. The signed message submitted after the deadline MUST be rejected</li> </ul> <p>The <code>DOMAIN_SEPARATOR</code> is generated 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">encode</span><span>(</span></span> <span class="giallo-l"><span class="z-string"> &quot;ERC-7508: Public Non-Fungible Token Attributes Repository&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;1&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-language"> block</span><span>.</span><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 class="giallo-l"><span>)</span><span>;</span></span></code></pre> <p>The <code>SET_UINT_ATTRIBUTE_TYPEHASH</code> is generated 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-string"> &quot;setUintAttribute(address collection,uint256 tokenId,string memory key,uint256 value)&quot;</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre> <p>The <code>SET_STRING_ATTRIBUTE_TYPEHASH</code> is generated 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-string"> &quot;setStringAttribute(address collection,uint256 tokenId,string memory key,string memory value)&quot;</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre> <p>The <code>SET_BOOL_ATTRIBUTE_TYPEHASH</code> is generated 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-string"> &quot;setBoolAttribute(address collection,uint256 tokenId,string memory key,bool value)&quot;</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre> <p>The <code>SET_BYTES_ATTRIBUTE_TYPEHASH</code> is generated 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-string"> &quot;setBytesAttribute(address collection,uint256 tokenId,string memory key,bytes memory value)&quot;</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre> <p>The <code>SET_ADDRESS_ATTRIBUTE_TYPEHASH</code> is generated 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-string"> &quot;setAddressAttribute(address collection,uint256 tokenId,string memory key,address value)&quot;</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre> <p>Each chain, that the Attributes repository smart contract is deployed in, will have a different <code>DOMAIN_SEPARATOR</code> value due to chain IDs being different.</p> <h3 id="pre-determined-address-of-the-attributes-repository">Pre-determined address of the Attributes repository</h3> <p>The address of the Emotable repository smart contract is designed to resemble the function it serves. It starts with <code>0xA77B75</code> which is the abstract representation of <code>ATTBTS</code>. The address is TBD.</p> <h2 id="rationale">Rationale</h2> <p>Designing the proposal, we considered the following questions:</p> <ol> <li><strong>Should we refer to the values stored by the repository as propertiers or attributes?</strong><br /> Historically values defining characteristics of tokens have been called properties, but have evolved in to being called attributes. Referring to the dictionary, the property is defined as a quality or characteristic that something has, and the attribute is defined as a quality or feature of somebody/something. We felt that using the term attribute fits better and decided to use it.</li> <li><strong>Should the proposal specify access control?</strong><br /> Designing the proposal, we had two options: either to include the access control within the specification of the proposal or to leave the access control up to the implementers that desire to use the attributes repository. While considering this we also had to consider the usability and compatibility aspects of the repository.<br /> On one hand, including access control narrows down the freedom of implementation and requires the implementers to configure it before being able to use the repository. On the other hand, leaving access control up to implementers requires dedicated design of attributes access control within their smart contracts, increasing their size, complexity and deployment costs.<br /> Another important thing to note is that including access control in the proposal makes it compatible with collections existing prior to the deployment of the repository and thus powers backwards-compatibility.</li> <li><strong>Should the proposal establish an attributes extension or a common-good repository?</strong><br /> Initially we set out to create an attributes extension to be used with any ERC-721 compliant tokens. However, we realized that the proposal would be more useful if it was a common-good repository of token attributes. This way, the tokens that can utilize it are not only the new ones but also the old ones that have been around since before the proposal.<br /> An additional benefit of this course-correction is the compatibility with ERC-1155 tokens.</li> <li><strong>Should we include only single-action operations, only multi-action operations, or both?</strong><br /> We've considered including only single-action operations, where the user is only able to assign a single attribute to a single token, but we decided to include both single-action and multi-action operations. This way, the users can choose whether they want to assign an attribute to a single token or on multiple tokens at once.<br /> This decision was made for the long-term viability of the proposal. Based on the gas cost of the network and the number of tokens in the collection, the user can choose the most cost-effective way of attribute assigning.</li> <li><strong>Should we add the ability to assign attributes on someone else's behalf?</strong><br /> While we did not intend to add this as part of the proposal when drafting it, we realized that it would be a useful feature for it. This way, the users can assign attributes on behalf of someone else, for example, if they are not able to do it themselves or if the attribute is earned through an off-chain activity.</li> <li><strong>How do we ensure that attribute assignment on someone else's behalf is legitimate?</strong><br /> We could add delegates to the proposal; when a user delegates their right to assign attributes to someone else, but having the ability to do so opens up the possibility for abuse and improper setting of attributes.<br /> Using ECDSA signatures, we can ensure that the user has given their consent to assign attribute on their behalf. This way, the user can sign a message with the parameters of the attribute and the signature can be submitted by someone else.</li> <li><strong>Should we add chain ID as a parameter when assigning attribute to a token?</strong><br /> We decided against this as we feel that additional parameter would rarely be used and would add additional cost to the attribute assignment transactions. If the collection smart contract wants to utilize on-chain token attributes, it requires the reactions to be recorded on the same chain. Marketplaces and wallets integrating this proposal will rely on attributes to reside in the same chain as well, because if chain ID parameter was supported this would mean that they would need to query the repository smart contract on all of the chains the repository is deployed in order to get the attributes of a given token.<br /> Additionally, if the collection creator wants users to record their reactions on a different chain, they can still direct the users to do just that. The repository does not validate the existence of the token being reacted to (except in an instance where the attribute can be modified by the token's owner), which in theory means that you can assign an attribute to non-existent token or to a token that does not exist yet.</li> <li><strong>How should we reduce the cost of string usage in the repository?</strong> One fo the main issues we were dealing with while designing the proposal is the cost of string usage. We considered using bytes instead of strings, but decided against it as it would require the users to encode and decode the strings themselves.<br /> The solution for reducing the cost was to use a string indices. This means that the cost of setting a new string attribute or key will only be paid by the first user to do so. The subsequent users will only pay the cost of setting the index of the string attribute or key.<br /> We also extended this gas-saving approach to be applicable across the entire repository. This means that if the string was already set by one collection, any other collection using the same string will not have to pay the cost of setting the string again.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The Attributes repository standard is fully compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> and with the robust tooling available for implementations of ERC-721 as well as with the existing ERC-721 infrastructure.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests are included in <a href="https://wg-eips.ritovision.com/7508/./assets/test/attributesRepository.ts"><code>attributesRepository.ts</code></a>.</p> <p>To run them in terminal, you can use the following commands:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cd ../assets/eip-7508</span></span> <span class="giallo-l"><span>pnpm i</span></span> <span class="giallo-l"><span>pnpm hardhat test</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/7508/./assets/contracts/AttributesRepository.sol"><code>AttributesRepository.sol</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The proposal does not envision handling any form of assets from the user, so the assets should not be at risk when interacting with an Attributes repository.</p> <p>The ability to use ECDSA signatures to set attributes on someone else's behalf introduces the risk of a replay attack, which the format of the message to be signed guards against. The <code>DOMAIN_SEPARATOR</code> used in the message to be signed is unique to the repository smart contract of the chain it is deployed on. This means that the signature is invalid on any other chain and the attributes repositories deployed on them should revert the operation if a replay attack is attempted.</p> <p>Another thing to consider is the ability of presigned message reuse. Since the message includes the signature validity deadline, the message can be reused any number of times before the deadline is reached. The proposal only allows for a single value for a given key to be set, so the presigned message can not be abused to further modify the attribute value. However, if the service using the repository relies on the ability to revert or modify the attribute after certain actions, a valid presigned message can be used to re-assign the attribute of the token. We suggest that the services using the repository in cnjunction with presigned messages use deadlines that invalidate presigned messages after a reasonalby short period of time.</p> <p>Caution is advised when dealing with non-audited 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> 2023-08-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Konrad Kopphttps://github.com/kopy-kat zeroknotshttps://github.com/zeroknots https://wg-eips.ritovision.com/7484/

Adapters that allow modular smart accounts to verify the security of modules using a Module Registry

<h2 id="abstract">Abstract</h2> <p>This proposal standardizes the interface and functionality of Module Registries, allowing modular smart accounts to verify the security of modules using a Registry Adapter. It also provides a reference implementation of a Singleton Module Registry.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> standardizes the execution flow of contract accounts and <a href="https://wg-eips.ritovision.com/7579/">ERC-7579</a> standardizes the modular implementation of these accounts, allowing any developer to build modules for these modular accounts (hereafter Smart Accounts). However, adding third-party modules into Smart Accounts unchecked opens up a wide range of attack vectors.</p> <p>One solution to this security issue is to create a Module Registry that stores security attestations on Modules and allows Smart Accounts to query these attestations before using a module. This standard aims to achieve two things:</p> <ol> <li>Standardize the interface and required functionality of Module Registries.</li> <li>Standardize the functionality of Adapters that allow Smart Accounts to query Module Registries.</li> </ol> <p>This ensures that Smart Accounts can securely query Module Registries and handle the Registry behavior correctly, irrespective of their architecture, execution flows and security assumptions. This standard also provides a reference implementation of a Singleton Module Registry that is ownerless and can be used by any Smart Account. While we see many benefits of the entire ecosystem using this single Module Registry (see <code>Rationale</code>), we acknowledge that there are tradeoffs to using a singleton and thus this standard does not require Smart Accounts to use the reference implementation. Hence, this standard ensures that Smart Accounts can query any Module Registry that implements the required interface and functionality, reducing integration overhead and ensuring interoperability for Smart Accounts.</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="definitions">Definitions</h3> <ul> <li><strong>Smart account</strong> - An ERC-7579 modular smart account.</li> <li><strong>Module</strong> - Self-contained smart account functionality.</li> <li><strong>Attestation</strong> - Onchain assertions made about the security of a module.</li> <li><strong>Attester</strong> - The entity that makes an attestation about a module.</li> <li><strong>(Module) Registry</strong> - A contract that stores an onchain list of attestations about modules.</li> <li><strong>Adapter</strong> - Smart account functionality that handles the fetching and validation of attestations from the Registry.</li> </ul> <h3 id="required-registry-functionality">Required Registry functionality</h3> <p>The core interface for a Registry is 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"> IERC7484Registry</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment">´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> Check with internal attester(s) </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><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"> check</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>;</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"> checkForAccount</span><span>(</span><span class="z-support">address</span><span class="z-variable"> smartAccount</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>;</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"> check</span><span>(</span><span class="z-support">address</span><span class="z-variable"> module</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> moduleType</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-storage z-type"> function</span><span class="z-entity z-name"> checkForAccount</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> smartAccount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> module</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> moduleType</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-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-comment">´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> Set internal attester(s) </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><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"> trustAttesters</span><span>(</span><span class="z-support">uint8</span><span class="z-variable"> threshold</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"> attesters</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 class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment">´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> Check with external attester(s) </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><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"> check</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> module</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"> attesters</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> threshold</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-storage z-type"> view</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"> check</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> module</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> moduleType</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"> attesters</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> threshold</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-storage z-type"> view</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The Registry MUST also implement the following functionality:</p> <ul> <li>Verify that an attester is the creator of an attestation, for example by checking <code>msg.sender</code> or by using signatures, before storing it.</li> <li>Allow attesters to revoke attestations that they have made.</li> <li>Store either the attestation data or a reference to the attestation data.</li> </ul> <p>The Registry SHOULD also implement the following additional functionality:</p> <ul> <li>Allow attesters to specify an expiry date for their attestations and revert during a check if an attestation is expired.</li> <li>Implement a view function that allows an adapter or offchain client to read the data for a specific attestation.</li> </ul> <h4 id="check-functions"><code>check</code> functions</h4> <ul> <li>The Registry MUST revert if the number of <code>attesters</code> that have made an attestation on the <code>module</code> is smaller than the <code>threshold</code>.</li> <li>The Registry MUST revert if any <code>attester</code> has revoked their attestation on the <code>module</code>.</li> <li>The <code>attesters</code> provided MUST be unique and sorted and the Registry MUST revert if they are not.</li> </ul> <h4 id="check-functions-with-moduletype"><code>check</code> functions with moduleType</h4> <ul> <li>The Registry MUST revert if the module type of the <code>module</code> stored is not the provided <code>moduleType</code>.</li> </ul> <h4 id="functions-with-internal-attester-s">Functions with internal attester(s)</h4> <ul> <li>The Registry MUST use the stored attester(s) for the <code>smartAccount</code> or <code>msg.sender</code> (if the former is not an argument).</li> <li>The Registry MUST revert if no attester(s) are stored for the <code>smartAccount</code> or <code>msg.sender</code> (if the former is not an argument).</li> </ul> <h4 id="trustattesters"><code>trustAttesters</code></h4> <ul> <li>The Registry MUST store the <code>threshold</code> and <code>attesters</code> for the <code>msg.sender</code>.</li> <li>The <code>attesters</code> provided MUST be unique and sorted and the Registry MUST revert if they are not.</li> </ul> <h3 id="adapter-behavior">Adapter behavior</h3> <p>A Smart Account MUST implement the following Adapter functionality either natively in the account or as a module. This Adapter functionality MUST ensure that:</p> <ul> <li>The Registry is queried about module <code>A</code> at least once before or during the transaction in which <code>A</code> is called for the first time.</li> <li>The Registry reverting is treated as a security risk.</li> </ul> <p>Additionally, the Adapter SHOULD implement the following functionality:</p> <ul> <li>Revert the transaction flow when the Registry reverts.</li> <li>Query the Registry about module <code>A</code> on installation of <code>A</code>.</li> <li>Query the Registry about module <code>A</code> on execution of <code>A</code>.</li> </ul> <p>Example: Adapter flow using <code>check</code> <img src="https://wg-eips.ritovision.com/7484/./assets/check-sequence.jpg" alt="Adapter flow using check()" /></p> <h2 id="rationale">Rationale</h2> <h3 id="attestations">Attestations</h3> <p>Attestations are onchain assertions made about a module. These assertions could pertain to the security of a module (similar to a regular smart contract audit), whether a module adheres to a certain standard or any other kinds of statements about these modules. While some of these assertions can feasibly be verified onchain, the majority of them cannot be.</p> <p>One example of this would be determining what storage slots a specific module can write to, which might be useful if a smart account uses DELEGATECALL to invoke the module. This assertion is practically infeasible to verify onchain, but can easily be verified off-chain. Thus, an attester could perform this check off-chain and publish an attestation onchain that attests to the fact that a given module can only write to its designated storage slots.</p> <p>While attestations are always certain kinds of assertions made about a module, this proposal purposefully allows the attestation data to be any kind of data or pointer to data. This ensures that any kind of data can be used as an assertion, from a simple boolean flag specifying that a module is secure to a complex proof of runtime module behaviour.</p> <h3 id="singleton-registry">Singleton Registry</h3> <p>In order for attestations to be queryable onchain, they need to be stored in some sort of list in a smart contract. This proposal includes the reference implementation of an ownerless Singleton Registry that functions as the source of truth for attestations.</p> <p>The reasons for proposing a Singleton Registry are the following:</p> <p><strong>Security</strong>: A Singleton Registry creates greater security by focusing account integrations into a single source of truth where a maximum number of security entities are attesting. This has a number of benefits: a) it increases the maximum potential quantity and type of attestations per module and b) removes the need for accounts to verify the authenticity and security of different registries, focusing trust delegation to the onchain entities making attestations. The result is that accounts are able to query multiple attesters with lower gas overhead in order to increase security guarantees and there is no additional work required by accounts to verify the security of different registries.</p> <p><strong>Interoperability</strong>: A Singleton Registry not only creates a greater level of “attestation liquidity”, but it also increases module liquidity and ensures a greater level of module interoperability. Developers need only deploy their module to one place to receive attestations and maximise module distribution to all integrated accounts. Attesters can also benefit from previous auditing work by chaining attestations and deriving ongoing security from these chains of dependencies. This allows for benefits such as traversing through the history of attestations or version control by the developer.</p> <p>However, there are obviously tradeoffs for using a singleton. A Singleton Registry creates a single point of failure that, if exploited, could lead to serious consequences for smart accounts. The most serious attack vector of these would be the ability for an attacker to attest to a malicious module on behalf of a trusted attester. One tradeoff here is that using multiple registries, changes in security attestations (for example a vulnerability is found and an attestation is revoked) are slower to propagate across the ecosystem, giving attackers an opportunity to exploit vulnerabilities for longer or even find and exploit them after seeing an issue pointed out in a specific Registry but not in others.</p> <p>Due to being a singleton, the Registry needs to be very flexible and thus likely less computationally efficient in comparison to a narrow, optimised Registry. This means that querying a Singleton Registry is likely to be more computationally (and by extension gas) intensive than querying a more narrow Registry. The tradeoff here is that a singleton makes it cheaper to query attestations from multiple parties simultaneously. So, depending on the Registry architectures, there is an amount of attestations to query (N) after which using a flexible singleton is actually computationally cheaper than querying N narrow registries. However, the reference implementation has also been designed with gas usage in mind and it is unlikely that specialised registries will be able to significantly decrease gas beyond the reference implementations benchmarks.</p> <h3 id="module-types">Module Types</h3> <p>Modules can be of different types and it can be important for an account to ensure that a module is of a certain type. For example, if an account wants to install a module that handles the validation logic of the account, then it might want to ensure that attesters have confirmed that the module is indeed capable of performing this validation logic. Otherwise, the account might be at risk of installing a module that is not capable of performing the validation logic, which could lead to an account being rendered unusable.</p> <p>Nonetheless, the Registry itself does not need to care what specific module types mean. Instead, attesters can provide these types and the Registry can store them.</p> <h3 id="related-work">Related work</h3> <p>The reference implementation of the Registry is heavily inspired by the Ethereum Attestation Service. The specific use-case of this proposal, however, required some custom modifications and additions to EAS, meaning that using the existing EAS contracts as the Module Registry was sub-optimal. However, it would be possible to use EAS as a Module Registry with some modifications.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="adapter-sol">Adapter.sol</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"> Adapter</span><span> {</span></span> <span class="giallo-l"><span> IRegistry registry</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"> checkModule</span><span>(</span><span class="z-support">address</span><span class="z-variable"> module</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Check module attestation on Registry</span></span> <span class="giallo-l"><span> registry</span><span>.</span><span class="z-entity z-name">check</span><span>(</span><span>module</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"> checkModuleWithModuleTypeAndAttesters</span><span>(</span><span class="z-support">address</span><span class="z-variable"> module</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"> attesters</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> threshold</span><span>,</span><span class="z-support"> uint16</span><span class="z-variable"> moduleType</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Check list of module attestations on Registry</span></span> <span class="giallo-l"><span> registry</span><span>.</span><span class="z-entity z-name">check</span><span>(</span><span>module</span><span>,</span><span> attesters</span><span>,</span><span> threshold</span><span>,</span><span> moduleType</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><h3 id="account-sol">Account.sol</h3> <p><strong>Note</strong>: This is a specific example that complies to the <code>Specification</code> above, but this implementation is not binding.</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"> Account</span><span class="z-storage"> is</span><span class="z-entity z-name"> Adapter</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-comment"> //</span><span class="z-comment"> installs a module</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> installModule</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> moduleTypeId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> module</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"> initData</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-storage z-type"> payable</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> checkModule</span><span>(</span><span>module</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 class="z-comment"> //</span><span class="z-comment"> executes a module</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> executeFromExecutor</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> ModeCode</span><span class="z-variable"> mode</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"> executionCalldata</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-storage z-type"> payable</span></span> <span class="giallo-l"><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"> returnData</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> checkModule</span><span>(</span><span>module</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><span>.</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="registry">Registry</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"> this implementation is unoptimized in order to make the reference implementation shorter to read</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> some function implementations are missing for brevity</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"> Registry</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7484Registry</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-comment"> /*</span><span class="z-comment">´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> Check with internal attester(s) </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><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"> check</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> {</span></span> <span class="giallo-l"><span> (</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span> attesters</span><span>,</span><span class="z-support"> uint256</span><span> threshold</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> _getAttesters</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validCount </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> attesters</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"> bool</span><span> isValid </span><span class="z-keyword">=</span><span class="z-entity z-name"> _check</span><span>(</span><span>module</span><span>,</span><span> attesters</span><span>[</span><span>i</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>isValid</span><span>)</span><span> validCount</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"> if</span><span> (</span><span>validCount </span><span class="z-keyword">&lt;</span><span> threshold</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> AttestationThresholdNotMet</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"> checkForAccount</span><span>(</span><span class="z-support">address</span><span class="z-variable"> smartAccount</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> {</span></span> <span class="giallo-l"><span> (</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span> attesters</span><span>,</span><span class="z-support"> uint256</span><span> threshold</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> _getAttesters</span><span>(</span><span>smartAccount</span><span>)</span><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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> check</span><span>(</span><span class="z-support">address</span><span class="z-variable"> module</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> moduleType</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><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span> attesters</span><span>,</span><span class="z-support"> uint256</span><span> threshold</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> _getAttesters</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validCount </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> attesters</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"> bool</span><span> isValid </span><span class="z-keyword">=</span><span class="z-entity z-name"> _check</span><span>(</span><span>module</span><span>,</span><span> attesters</span><span>[</span><span>i</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>isValid</span><span>)</span><span> validCount</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> AttestationRecord </span><span class="z-storage z-type">storage</span><span> attestation </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAttestation</span><span>(</span><span>module</span><span>,</span><span> attester</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>attestation</span><span>.</span><span>moduleType </span><span class="z-keyword">!=</span><span> moduleType</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> ModuleTypeMismatch</span><span>(</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>validCount </span><span class="z-keyword">&lt;</span><span> threshold</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> AttestationThresholdNotMet</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"> checkForAccount</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> smartAccount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> module</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> moduleType</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-storage z-type"> view</span><span> {</span></span> <span class="giallo-l"><span> (</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span> attesters</span><span>,</span><span class="z-support"> uint256</span><span> threshold</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> _getAttesters</span><span>(</span><span>smartAccount</span><span>)</span><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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment">´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> Set internal attester(s) </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><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"> trustAttesters</span><span>(</span><span class="z-support">uint8</span><span class="z-variable"> threshold</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"> attesters</span><span>)</span><span class="z-storage z-type"> external</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 class="z-comment">´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> Check with external attester(s) </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><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"> check</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> module</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"> attesters</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> threshold</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-storage z-type"> view</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validCount </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> attesters</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"> bool</span><span> isValid </span><span class="z-keyword">=</span><span class="z-entity z-name"> _check</span><span>(</span><span>module</span><span>,</span><span> attesters</span><span>[</span><span>i</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>isValid</span><span>)</span><span> validCount</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"> if</span><span> (</span><span>validCount </span><span class="z-keyword">&lt;</span><span> threshold</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> AttestationThresholdNotMet</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"> check</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> module</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> moduleType</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"> attesters</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> threshold</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-storage z-type"> view</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validCount </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> attesters</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"> bool</span><span> isValid </span><span class="z-keyword">=</span><span class="z-entity z-name"> _check</span><span>(</span><span>module</span><span>,</span><span> attesters</span><span>[</span><span>i</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>isValid</span><span>)</span><span> validCount</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> AttestationRecord </span><span class="z-storage z-type">storage</span><span> attestation </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAttestation</span><span>(</span><span>module</span><span>,</span><span> attester</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>attestation</span><span>.</span><span>moduleType </span><span class="z-keyword">!=</span><span> moduleType</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> ModuleTypeMismatch</span><span>(</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>validCount </span><span class="z-keyword">&lt;</span><span> threshold</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> AttestationThresholdNotMet</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">´:°•.°+.*•´.*:˚.°*.˚•´.°:°•.°•.*•´.*:˚.°*.˚•´.°:°•.°+.*•´.*:</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> Internal </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><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"> _check</span><span>(</span><span class="z-support">address</span><span class="z-variable"> module</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> attester</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"> isValid</span><span>)</span><span>{</span></span> <span class="giallo-l"><span> AttestationRecord </span><span class="z-storage z-type">storage</span><span> attestation </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getAttestation</span><span>(</span><span>module</span><span>,</span><span> attester</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint48</span><span> expirationTime </span><span class="z-keyword">=</span><span> attestation</span><span>.</span><span>expirationTime</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint48</span><span> attestedAt </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span> expirationTime </span><span class="z-keyword">!=</span><span class="z-constant"> 0</span><span class="z-keyword"> &amp;&amp;</span><span> expirationTime </span><span class="z-keyword">&lt;</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp </span><span class="z-keyword">?</span><span class="z-constant"> 0</span><span class="z-keyword"> :</span><span> attestation</span><span>.</span><span>time</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>attestedAt </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span class="z-keyword"> return</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint48</span><span> revokedAt </span><span class="z-keyword">=</span><span> attestation</span><span>.</span><span>revocationTime</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>revokedAt </span><span class="z-keyword">!=</span><span class="z-constant"> 0</span><span>)</span><span class="z-keyword"> return</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> isValid </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"> _getAttestation</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> module</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> attester</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-storage z-type"> internal</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-keyword"> returns</span><span> (</span><span class="z-storage z-type">AttestationRecord</span><span class="z-storage z-type"> storage</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _moduleToAttesterToAttestations</span><span>[</span><span>module</span><span>]</span><span>[</span><span>attester</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"> _getAttesters</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> account</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-storage z-type"> internal</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-keyword"> returns</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"> attesters</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> threshold</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> .</span><span>.</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> 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-08-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Lee Vidorhttps://github.com/V1d0r David Tandavid@emergentx.org Lee Smithlee@emergentx.org Gabriel Stoicahttps://github.com/gabrielstoica https://wg-eips.ritovision.com/7578/

Provides the holder of physical asset backed NFTs readily available real-world information on the underlying physical asset.

<h2 id="abstract">Abstract</h2> <p>This proposal is an extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and implements additional functionality and information pertaining to the NFT’s underlying physical asset by capturing information that enables the holder of physical asset backed NFTs to verify authenticity and facilitate redemption of the underlying physical assets. This proposal is primarily aimed at providing transparency by disclosing details of involved parties and provides opportunity to define and make readily available relevant legal relationship between NFT holder and the owner/holder of the respective underlying physical asset. This proposal makes the token issuer accountable to embed accurate information on a set of standardized information about the underlying physical asset and the involved key parties.</p> <h2 id="motivation">Motivation</h2> <p>The first wave of NFT use cases encompass predominately the representation of ownership of digital assets. In view of the anticipated trend to tokenize any real-world asset, it is to be expected that the use cases of NFTs will rapidly grow and expand around physical assets. The absence of an embedded standardized set of information pertaining to the underlying physical asset together with lack of transparency of involved key parties, creates an unnecessary hurdle for NFT holders and potential users which might, as a result, hinder mass adoption of NFTs that are used as ownership representation of a specific physical asset.</p> <p>Addressing the lack of readily available information and paving the way for mass adoption for a tokenized economy, this proposal requires that each minted token includes a defined number of predefined variables enabling verification of authenticity and facilitating redemption of the underlying physical asset.</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>When a token is minted, its properties SHOULD be initialized beforehand, with each field being defined as follows:</p> <ul> <li> <p><strong>Token issuer</strong>: identification of an individual or entity minting the NFT <br> <em>The token issuer is the key person connecting the physical asset and the digital representation. By identifying and disclosing the token issuer, a reference point is made instantly available to the NFT holder which allows them to conduct a due diligence on the NFT issuer and assessment of the NFT issuer’s trustworthiness. At the same time, it creates accountability for the token issuer which leads to overall improvement and standardisation of the NFT minting process. Token issuers will compete for best practices and recognition to gain advantages over competitors. A reputable NFT issuer will e.g. keep information on the legal owner of the physical asset prior to the minting of the underlying physical asset to satisfy any AML and KYC concerns. Ideally the NFT issuer is identified by a name but may also be identifiable via unique identification number or network ID that is issued by a service provider who stores relevant information on the NFT issuer.</em></p> </li> <li> <p><strong>Asset holder</strong>: identification of legal owner of underlying physical asset <br> <em>In view of a redemption of the underlying physical asset and enforcing of legal rights, it is (from a legal perspective) essential for the NFT holder to identify the legal owner of the underlying physical asset. It allows the NFT holder to consider the legal counterparty risk. It cannot be assumed that the NFT issuer is the legal owner of the underlying physical asset, therefore it is vital for the NFT holder to have instant access to this additional information. Same as with the NFT issuer’s identity, the legal owner is ideally identified by a name but may also be identifiable via unique identification number or network ID that is issued by a service provider who stores relevant information on the legal owner.</em></p> </li> <li> <p><strong>Storage location</strong>: identification of storage location of underlying physical asset <br> <em>Certain physical assets require specific storage conditions. A digital representation of an inappropriately stored physical asset may impact the value of the NFT significantly. Disclosing the storage location and making it directly accessible to the NFT holder, allows them to evaluate the storage risk of the underlying physical asset. In addition, it provides the NFT holder with a second point of contact for the enforcement of the redemption of the underlying physical asset.</em></p> </li> <li> <p><strong>Terms</strong>: identification of legal relationship <br> <em>The disclosure and accessibility of the legal basis of the relationship between NFT holder and legal owner of the underlying physical asset promotes token issuers to stipulate and define the legal rights of the involved key parties. It furthermore allows the NFT Holder to conduct a legal risk and enforcement assessment. Ideally, the information is provided by embedding a link to the actual legal documentation such as an agreement or terms. The more information is accessible via the NFT, the better the NFT holder can assess the legal risks associated with enforcement of the redemption of the underlying physical asset.</em></p> </li> <li> <p><strong>Jurisdiction</strong>: governing law and jurisdiction <br> <em>The applicable law is an extension of the legal contract disclosure and makes instantly available to the NFT holder or smart contract under what jurisdiction an enforcement would be governed without the need to review the details legal contract. This allows for an instant assessment of jurisdiction risk.</em></p> </li> <li> <p><strong>Declared value</strong>: value of the underlying asset <br> <em>Certain auxiliary services such as insurance are tied to a value of the NFT and underlying physical asset. By defining a declared value, NFTs are able to be categorised in certain ways while the declared value provides an indication regarding the underlying asset’s value. The declared value of the underlying physical asset does not necessarily represent the market value.</em></p> </li> </ul> <p>The <code>terms</code> parameter SHOULD be an HTTP link to a document that is stored on IPFS. This is to ensure that the document is immutable and can be verified by the NFT holder.</p> <p>When a token with valid properties is to be burned, the properties MUST be removed.</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"> ^0.8.21</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 encapsulating fields required to by the ERC-7578 standard to represent the physical asset</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenIssuer</span><span class="z-comment"> The network or entity minting 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"> assetHolder</span><span class="z-comment"> The legal owner of the physical asset</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> storageLocation</span><span class="z-comment"> The physical location where the asset is stored</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> terms</span><span class="z-comment"> Link to IPFS contract, agreement or 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"> jurisdiction</span><span class="z-comment"> The legal justification set out in the 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"> declaredValue</span><span class="z-comment"> The declared value at time of token minting</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"> Properties</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> tokenIssuer</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> assetHolder</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> storageLocation</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> terms</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> jurisdiction</span><span>;</span></span> <span class="giallo-l"><span> Amount declaredValue</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 encapsulating fields describing the declared value of the physical asset</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> currency</span><span class="z-comment"> The currency of the 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"> value</span><span class="z-comment"> The value of the amount</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"> Amount</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> currency</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>}</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"> Required interface of an ERC-7578 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"> IERC7578</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 properties of the `tokenId` token are 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"> The ID of 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"> properties</span><span class="z-comment"> The properties of the 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"> PropertiesSet</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-variable">Properties</span><span class="z-variable"> properties</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 the properties of the `tokenId` token are 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"> tokenId</span><span class="z-comment"> The ID of the 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"> PropertiesRemoved</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">@notice</span><span class="z-comment"> Retrieves all properties of the `tokenId` token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Does NOT revert if token doesn&#39;t 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"> The token ID 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"> getPropertiesOf</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-storage z-type">Properties</span><span class="z-storage z-type"> memory</span><span class="z-variable"> properties</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>When <code>properties</code> are set, the <code>PropertiesSet(uint256 indexed tokenId, Properties properties)</code> event is emitted.</p> <p>When <code>properties</code> are removed, the <code>PropertiesRemoved(uint256 indexed tokenId)</code> event is emitted.</p> <p>The <code>getPropertiesOf(uint256 tokenId)</code> function MUST return the unique <code>properties</code> of a token. If the ERC-721 token is burned or has no properties set, it SHOULD return an empty <code>Properties</code> struct.</p> <h2 id="rationale">Rationale</h2> <p>By not initializing a token's properties before minting, one risks that the asset's provenance represented by the token cannot be established.</p> <p>Contract level validation is not used on the properties as we believe the accuracy of the data declared is the responsibility of the token issuer. This builds trust on the token issuer and the token itself.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with ERC-721.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>An example of an <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> that includes this proposal using the OpenZeppelin ERC-721 v5 library:</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.21</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">ERC721</span><span> }</span><span class="z-keyword"> from</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> { </span><span class="z-entity z-name">IERC7578</span><span>, </span><span class="z-entity z-name">Properties</span><span>, </span><span class="z-entity z-name">Amount</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./interfaces/IERC7578.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"> ERC7578</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@author</span><span class="z-comment"> DESAT</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Implementation of the ERC-7578: Physical Asset Redemption standard</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">contract</span><span class="z-entity z-name"> ERC7578</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">IERC7578</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"> Thrown when the properties of a token are not initialized</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"> PropertiesUninitialized</span><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"> Retrieves the properties of 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"> mapping</span><span>(</span><span class="z-support">uint256</span><span> tokenId </span><span class="z-keyword">=&gt;</span><span> Properties</span><span>)</span><span class="z-storage z-type"> private</span><span> _properties</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"> Initializes the name and symbol of the ERC-721 collection</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">string</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _name</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"> _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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@inheritdoc</span><span class="z-comment"> IERC7578</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"> getPropertiesOf</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"> override</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">Properties</span><span class="z-storage z-type"> memory</span><span class="z-variable"> properties</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> properties </span><span class="z-keyword">=</span><span> _properties</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">@notice</span><span class="z-comment"> Initializes the ERC-7578 properties of the `tokenId` token</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * WARNING: This method should only be called within a function that has appropriate access control</span></span> <span class="giallo-l"><span class="z-comment"> * It is recommended to restrict access to trusted Externally Owned Accounts (EOAs),</span></span> <span class="giallo-l"><span class="z-comment"> * authorized contracts, or implement a Role-Based Access Control (RBAC) mechanism</span></span> <span class="giallo-l"><span class="z-comment"> * Failure to properly secure this method could lead to unauthorized modification of token properties</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {PropertiesSet} 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"> _setPropertiesOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-storage z-type"> Properties</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> properties</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span> _properties</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Properties</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> tokenIssuer</span><span class="z-keyword">:</span><span> properties</span><span>.</span><span>tokenIssuer</span><span>,</span></span> <span class="giallo-l"><span> assetHolder</span><span class="z-keyword">:</span><span> properties</span><span>.</span><span>assetHolder</span><span>,</span></span> <span class="giallo-l"><span> storageLocation</span><span class="z-keyword">:</span><span> properties</span><span>.</span><span>storageLocation</span><span>,</span></span> <span class="giallo-l"><span> terms</span><span class="z-keyword">:</span><span> properties</span><span>.</span><span>terms</span><span>,</span></span> <span class="giallo-l"><span> jurisdiction</span><span class="z-keyword">:</span><span> properties</span><span>.</span><span>jurisdiction</span><span>,</span></span> <span class="giallo-l"><span> declaredValue</span><span class="z-keyword">:</span><span class="z-entity z-name"> Amount</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> currency</span><span class="z-keyword">:</span><span> properties</span><span>.</span><span>declaredValue</span><span>.</span><span>currency</span><span>,</span></span> <span class="giallo-l"><span> value</span><span class="z-keyword">:</span><span> properties</span><span>.</span><span>declaredValue</span><span>.</span><span>value</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 class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> PropertiesSet</span><span>(</span><span>tokenId</span><span>,</span><span> _properties</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> <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"> Removes the properties of the `tokenId` 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"> The unique identifier of the token whose properties are to be removed</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {PropertiesRemoved} 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"> _removePropertiesOf</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> {</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> _properties</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"> PropertiesRemoved</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">@notice</span><span class="z-comment"> Override of the {_update} function to remove the properties of the `tokenId` token or</span></span> <span class="giallo-l"><span class="z-comment"> * to check if they are set before minting</span></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 unique identifier of the token being minted or burned</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"> _update</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"> address</span><span class="z-variable"> auth</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 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> from </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 class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>to </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"> _removePropertiesOf</span><span>(</span><span>tokenId</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>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 class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-support">bytes</span><span>(</span><span>_properties</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>tokenIssuer</span><span>)</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> PropertiesUninitialized</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-keyword"> return</span><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">_update</span><span>(</span><span>to</span><span>,</span><span> tokenId</span><span>,</span><span> auth</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>To ensure authenticity, token properties must be set only via a method that is restricted to a trusted Externally Owned Account (EOA) or contract. This trusted entity must verify that the properties accurately reflect the real physical attributes of the represented asset. Additionally, proper access control mechanisms should be implemented to prevent unauthorized modifications of token properties after they are set.</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-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 LeadBest Consulting Groupservice@getoken.io Sandy Sunghttps://github.com/sandy-sung-lb Mars Pengmars.peng@getoken.io Taien Wangtaien.wang@getoken.io https://wg-eips.ritovision.com/7439/

An interface for customers to resell their tickets via authorized ticket resellers.

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and defines standard functions outlining a scope for ticketing agents or event organizers to take preventative actions to stop audiences being exploited in the ticket scalping market and allow customers to resell their tickets via authorized ticket resellers.</p> <h2 id="motivation">Motivation</h2> <p>Industrial-scale ticket touting has been a longstanding issue, with its associated fraud and criminal problems leading to unfortunate incidents and waste of social resources. It is also hugely damaging to artists at all levels of their careers and to related businesses across the board. Although the governments of various countries have begun to legislate to restrict the behavior of scalpers, the effect is limited. They still sold tickets for events at which resale was banned or did not yet own then obtained substantial illegal profits from speculative selling. We consulted many opinions to provide a consumer-friendly resale interface, enabling buyers to resell or reallocate a ticket at the price they initially paid or less is the efficient way to rip off “secondary ticketing”.that enables ticketing agents to utilize</p> <p>The typical ticket may be a "piece of paper" or even a voucher in your email inbox, making it easy to counterfeit or circulate. To restrict the transferability of these tickets, we have designed a mechanism that prohibits ticket transfers for all parties, including the ticket owner, except for specific accounts that are authorized to transfer tickets. The specific accounts may be ticketing agents, managers, promoters and authorized resale platforms. Therefore, the ticket touts are unable to transfer tickets as they wish. Furthermore, to enhance functionality, we have implemented a token info schema to each ticket, allowing only authorized accounts(excluding the owner) to modify these records.</p> <p>This standard defines a framework that enables ticketing agents to utilize <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens as event tickets and restricts token transferability to prevent ticket touting. By implementing this standard, we aim to protect customers from scams and fraudulent activities.</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="interface">Interface</h3> <p>The interface and structure referenced here are as follows:</p> <ul> <li>TokenInfo <ul> <li><code>signature</code>: Recommend that the adapter self-defines what to sign using the user's private key or agent's private key to prove the token validity.</li> <li><code>status</code>: Represent token current status.</li> <li><code>expireTime</code>: Recommend set to the event due time.</li> </ul> </li> <li>TokenStatus <ul> <li><code>Sold</code>: When a token is sold, it MUST change to <code>Sold</code>. The token is valid in this status.</li> <li><code>Resell</code>: When a token is in the secondary market, it MUST be changed to Resell. The token is valid in this status.</li> <li><code>Void</code>: When the token owner engages in an illegal transaction, the token status MUST be set to Void, and the token is invalid in this status.</li> <li><code>Redeemed</code>: When the token is used, it is RECOMMENDED to change the token status to <code>Redeemed</code>.</li> </ul> </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"> IERC7439 Prevent Ticket Touting Interface</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7439</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC721 </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"> TokenStatus represent the token current status, only specific role can change status</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> TokenStatus</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Sold</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> 0</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Resell</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> 1</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Void</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> 2</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Redeemed</span><span class="z-comment"> //</span><span class="z-comment"> 3</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"> signature</span><span class="z-comment"> Data signed by user&#39;s private key or agent&#39;s private key</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenStatus</span><span class="z-comment"> Token status changing 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"> expireTime</span><span class="z-comment"> Event due time</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> TokenInfo</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> signature</span><span>;</span></span> <span class="giallo-l"><span> TokenStatus tokenStatus</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> expireTime</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"> @notice</span><span class="z-comment"> Used to notify listeners that the token with the specified ID has been </span><span class="z-keyword">changed</span><span class="z-comment"> 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"> tokenId</span><span class="z-comment"> The token has been </span><span class="z-keyword">changed</span><span class="z-comment"> 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"> tokenStatus</span><span class="z-comment"> Token status has been </span><span class="z-keyword">changed</span><span class="z-comment"> 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"> signature</span><span class="z-comment"> Data signed by user&#39;s private key or agent&#39;s private key</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenStatusChanged</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-variable"> TokenStatus</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenStatus</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> signature</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"> Used to mint token with token status</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 the `TokenStatusChanged` event if the token status is </span><span class="z-keyword">changed</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"> to</span><span class="z-comment"> The receiptent 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"> signature</span><span class="z-comment"> Data signed by user&#39;s private key or agent&#39;s private key</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeMint</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Used to change token status and can only be invoked by a specific role</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 the `TokenStatusChanged` event if the token status is </span><span class="z-keyword">changed</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"> tokenId</span><span class="z-comment"> The token need to change 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"> signature</span><span class="z-comment"> Data signed by user&#39;s private key or agent&#39;s private key</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenStatus</span><span class="z-comment"> Token status changing 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"> newExpireTime</span><span class="z-comment"> New event due time</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> changeState</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"> memory</span><span class="z-variable"> signature</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> TokenStatus</span><span class="z-variable"> tokenStatus</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> newExpireTime</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> <p>The <code>supportsInterface</code> method MUST return <code>true</code> when called with <code>0x15fbb306</code>.</p> <h2 id="rationale">Rationale</h2> <p>Designing the proposal, we considered the following questions:</p> <ol> <li> <p>What is the most crucial for ticketing agents, performers, and audiences?</p> <ul> <li> <p>For ticketing companies, selling out all tickets is crucial. Sometimes, to create a vibrant sales environment, ticketing companies may even collaborate with scalpers. This practice can be detrimental to both the audience and performers. To prevent such situations, there must be an open and transparent primary sales channel, as well as a fair secondary sales mechanism. In the <code>safeMint</code> function, which is a public function, we hope that everyone can mint tickets transparently at a listed price by themselves. At that time, <code>TokenInfo</code> adds a signature that only the buyer account or agent can resolve depending on the mechanism, to prove the ticket validity. And the token <code>status</code> is <code>Sold</code>. Despite this, we must also consider the pressures on ticketing companies. They aim to maximize the utility of every valid ticket, meaning selling out each one. In the traditional mechanism, ticketing companies only benefit from the initial sale, implying that they do not enjoy the excess profits from secondary sales. Therefore, we have designed a secondary sales process that is manageable for ticketing companies. In the <code>_beforeTokenTransfer()</code> function, you can see that it is an accessControl function, and only the <code>PARTNER_ROLE</code> <code>mint</code> or <code>burn</code> situation can transfer the ticket. The <code>PARTNER_ROLE</code> can be the ticket agency or a legal secondary ticket selling platform, which may be a state supervision or the ticket agency designated platform. To sustain the fair ticketing market, we cannot allow them to transfer tickets themselves, because we can’t distinguish whether the buyer is a scalper.</p> </li> <li> <p>For performers or event holder, they aren't willing to see bad news during ticket selling. A smooth ticketing process or no news that may damage their performers’ reputation is what they want. Other than that, what really matters is all the audience true fans who come. Tickets ending up in the hands of scalpers or entering a chaotic secondary market doesn't really appeal to genuine fans. We believe performers wouldn't be pleased with such a situation. Through the transparant mechanism, performers or event holder can control the real sales status at all times form cross-comparison of token mint amount and <code>TokenInfo</code>-<code>TokenStatus</code>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>enum TokenStatus {</span></span> <span class="giallo-l"><span> Sold, // 0</span></span> <span class="giallo-l"><span> Resell, // 1</span></span> <span class="giallo-l"><span> Void, // 2</span></span> <span class="giallo-l"><span> Redeemed // 3</span></span> <span class="giallo-l"><span>}</span></span></code></pre></li> <li> <p>For audiences, the only thing they need is to get a valid ticket. In the traditional mechanism,fans encounter many obstacles. At hot concerts, fans who try to snag tickets can run into some foes, like scalpers and ticketing companies. These scalpers are like pros, all organized and strategic in grabbing up tickets. Surprisingly, ticketing companies might actually team up with these scalpers. Or, they might just keep a bunch of freebies or VIP tickets to themselves. A transparent mechanism is equally important for the audiences.</p> </li> </ul> </li> <li> <p>How to establish a healthy ticketing ecosystem?</p> <ul> <li> <p>Clear ticketing rules are key to making sure the supply and demand stay in balance.</p> </li> <li> <p>An open pricing system is a must to make sure consumers are protected.</p> </li> <li> <p>Excellent liquidity. In the initial market, users can mint tickets themselves. If needed, purchased tickets can also be transferred in a transparent and open secondary market. Audiences who didn’t buy tickets during the initial sale can also confidently purchase tickets in a legal secondary market. The <code>changeState</code> function is to help the ticket have good liquidity. Only <code>PARTNER_ROLE</code> can change the ticket status. Once the sold ticket needs to be sold in the secondary market, it needs to ask the secondary market to help it change to resell status. The process of changing status is a kind of official verification of the secondary sale ticket. It is a protection mechanism to the second hand buyer.</p> </li> </ul> </li> <li> <p>How to design a smooth ticketing process？</p> <ul> <li> <p>Easy to buy/sell. Audiences can buy ticket as mint NFT. This is a well-known practice.</p> </li> <li> <p>Easy to refund. When something extreme happens and you need to cancel the show. Handling ticket refunds can be a straightforward process.</p> </li> <li> <p>Easy to redeem. Before the show, the ticket agency can verify the ticket by the signature to confirm if the audience is genuine. <code>TokenStatus</code> needs to be equal to <code>sold</code>, and <code>expireTime</code> can distinguish whether the audience has arrived at the correct session. After verification is passed, the ticket agency can change the <code>TokenStatus</code> to <code>Redeemed</code>.</p> </li> <li> <p>Normal Flow <img src="https://wg-eips.ritovision.com/7439/./assets/normal.png" alt="Alt text" /></p> </li> <li> <p>Void Flow <img src="https://wg-eips.ritovision.com/7439/./assets/void.png" alt="Alt text" /></p> </li> <li> <p>Resell Flow <img src="https://wg-eips.ritovision.com/7439/./assets/resell.png" alt="Alt text" /></p> </li> </ul> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>.</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"> expectRevert</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">@openzeppelin/test-helpers</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"> 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 class="z-variable z-other z-constant"> ERC7439</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">&quot;</span><span class="z-string">ERC7439</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-entity z-name">contract</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ERC7439</span><span class="z-punctuation z-definition z-string">&quot;</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> [</span><span class="z-variable z-other z-constant">deployer</span><span>,</span><span class="z-variable z-other z-constant"> partner</span><span>,</span><span class="z-variable z-other z-constant"> userA</span><span>,</span><span class="z-variable z-other z-constant"> userB</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-other"> accounts</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> expireTime</span><span class="z-keyword"> =</span><span class="z-constant"> 19999999</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> tokenId</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"> const</span><span class="z-variable z-other z-constant"> signature</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x993dab3dd91f5c6dc28e17439be475478f5635c92a56e17e82349d3fb2f166196f466c0b4e0c146f285204f0dcb13e5ae67bc33f4b888ec32dfe0a063e8f3f781b</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> zeroHash</span><span class="z-keyword"> =</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></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-language"> this</span><span>.</span><span class="z-variable z-other">erc7439</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other z-constant"> ERC7439</span><span>.</span><span class="z-entity z-name">new</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> from</span><span>:</span><span class="z-variable z-other"> deployer</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">erc7439</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span><span class="z-variable z-other">userA</span><span>,</span><span class="z-variable z-other"> signature</span><span>,</span><span> {</span><span> from</span><span>:</span><span class="z-variable z-other"> deployer</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 mint a token</span><span class="z-punctuation z-definition z-string">&quot;</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"> const</span><span class="z-variable z-other z-constant"> tokenInfo</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">erc7439</span><span>.</span><span class="z-entity z-name">tokenInfo</span><span>(</span><span class="z-variable z-other">tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></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-language"> this</span><span>.</span><span class="z-variable z-other">erc7439</span><span>.</span><span class="z-entity z-name">ownerOf</span><span>(</span><span class="z-variable z-other">tokenId</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">userA</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">tokenInfo</span><span>.</span><span class="z-variable z-other">signature</span><span>)</span><span>.</span><span class="z-entity z-name">equal</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"> expect</span><span>(</span><span class="z-variable z-other">tokenInfo</span><span>.</span><span class="z-variable z-other">status</span><span>)</span><span>.</span><span class="z-entity z-name">equal</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><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Sold</span></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">tokenInfo</span><span>.</span><span class="z-variable z-other">expireTime</span><span>)</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-variable z-other">expireTime</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 ordinary users cannot transfer successfully</span><span class="z-punctuation z-definition z-string">&quot;</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-entity z-name"> expectRevert</span><span>(</span><span class="z-keyword">await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">erc7439</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-variable z-other">userA</span><span>,</span><span class="z-variable z-other"> userB</span><span>,</span><span class="z-variable z-other"> tokenId</span><span>,</span><span> {</span><span> from</span><span>:</span><span class="z-variable z-other"> userA</span><span> }</span><span>)</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC7439: You cannot transfer this NFT!</span><span class="z-punctuation z-definition z-string">&quot;</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 partner can transfer successfully and chage the token info to resell status</span><span class="z-punctuation z-definition z-string">&quot;</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"> const</span><span class="z-variable z-other z-constant"> tokenStatus</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"> Resell</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">erc7439</span><span>.</span><span class="z-entity z-name">changeState</span><span>(</span><span class="z-variable z-other">tokenId</span><span>,</span><span class="z-variable z-other"> zeroHash</span><span>,</span><span class="z-variable z-other"> tokenStatus</span><span>,</span><span> {</span><span> from</span><span>:</span><span class="z-variable z-other"> partner</span><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">erc7439</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-variable z-other">userA</span><span>,</span><span class="z-variable z-other"> partner</span><span>,</span><span class="z-variable z-other"> tokenId</span><span>,</span><span> {</span><span> from</span><span>:</span><span class="z-variable z-other"> partner</span><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">tokenInfo</span><span>.</span><span class="z-variable z-other">tokenHash</span><span>)</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-variable z-other">zeroHash</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">tokenInfo</span><span>.</span><span class="z-variable z-other">status</span><span>)</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-variable z-other">tokenStatus</span><span>)</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Resell</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-language"> this</span><span>.</span><span class="z-variable z-other">erc7439</span><span>.</span><span class="z-entity z-name">ownerOf</span><span>(</span><span class="z-variable z-other">tokenId</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">partner</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 partner can change the token status to void</span><span class="z-punctuation z-definition z-string">&quot;</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"> const</span><span class="z-variable z-other z-constant"> tokenStatus</span><span class="z-keyword"> =</span><span class="z-constant"> 2</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Void</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">erc7439</span><span>.</span><span class="z-entity z-name">changeState</span><span>(</span><span class="z-variable z-other">tokenId</span><span>,</span><span class="z-variable z-other"> zeroHash</span><span>,</span><span class="z-variable z-other"> tokenStatus</span><span>,</span><span> {</span><span> from</span><span>:</span><span class="z-variable z-other"> partner</span><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">tokenInfo</span><span>.</span><span class="z-variable z-other">tokenHash</span><span>)</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-variable z-other">zeroHash</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">tokenInfo</span><span>.</span><span class="z-variable z-other">status</span><span>)</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-variable z-other">tokenStatus</span><span>)</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Void</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 partner can change the token status to redeemed</span><span class="z-punctuation z-definition z-string">&quot;</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"> const</span><span class="z-variable z-other z-constant"> tokenStatus</span><span class="z-keyword"> =</span><span class="z-constant"> 3</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Redeemed</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">erc7439</span><span>.</span><span class="z-entity z-name">changeState</span><span>(</span><span class="z-variable z-other">tokenId</span><span>,</span><span class="z-variable z-other"> zeroHash</span><span>,</span><span class="z-variable z-other"> tokenStatus</span><span>,</span><span> {</span><span> from</span><span>:</span><span class="z-variable z-other"> partner</span><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">tokenInfo</span><span>.</span><span class="z-variable z-other">tokenHash</span><span>)</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-variable z-other">zeroHash</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">tokenInfo</span><span>.</span><span class="z-variable z-other">status</span><span>)</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-variable z-other">tokenStatus</span><span>)</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Redeemed</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 partner can resell the token and change status from resell to sold</span><span class="z-punctuation z-definition z-string">&quot;</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></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> tokenStatus</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"> Resell</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">erc7439</span><span>.</span><span class="z-entity z-name">changeState</span><span>(</span><span class="z-variable z-other">tokenId</span><span>,</span><span class="z-variable z-other"> zeroHash</span><span>,</span><span class="z-variable z-other"> tokenStatus</span><span>,</span><span> {</span><span> from</span><span>:</span><span class="z-variable z-other"> partner</span><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">erc7439</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-variable z-other">userA</span><span>,</span><span class="z-variable z-other"> partner</span><span>,</span><span class="z-variable z-other"> tokenId</span><span>,</span><span> {</span><span> from</span><span>:</span><span class="z-variable z-other"> partner</span><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">tokenInfo</span><span>.</span><span class="z-variable z-other">status</span><span>)</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-variable z-other">tokenStatus</span><span>)</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Resell</span></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">tokenInfo</span><span>.</span><span class="z-variable z-other">tokenHash</span><span>)</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-variable z-other">zeroHash</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> tokenStatus</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Sold</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> newSignature</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x113hqb3ff45f5c6ec28e17439be475478f5635c92a56e17e82349d3fb2f166196f466c0b4e0c146f285204f0dcb13e5ae67bc33f4b888ec32dfe0a063w7h2f742f</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">erc7439</span><span>.</span><span class="z-entity z-name">changeState</span><span>(</span><span class="z-variable z-other">tokenId</span><span>,</span><span class="z-variable z-other"> newSignature</span><span>,</span><span class="z-variable z-other"> tokenStatus</span><span>,</span><span> {</span><span> from</span><span>:</span><span class="z-variable z-other"> partner</span><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">erc7439</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-variable z-other">partner</span><span>,</span><span class="z-variable z-other"> userB</span><span>,</span><span class="z-variable z-other"> tokenId</span><span>,</span><span> {</span><span> from</span><span>:</span><span class="z-variable z-other"> partner</span><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">tokenInfo</span><span>.</span><span class="z-variable z-other">status</span><span>)</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-variable z-other">tokenStatus</span><span>)</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Sold</span></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">tokenInfo</span><span>.</span><span class="z-variable z-other">tokenHash</span><span>)</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-variable z-other">newSignature</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-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.19</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-comment">//</span><span class="z-comment"> If you need additional metadata, you can import ERC721URIStorage</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> import &quot;@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol&quot;;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/access/AccessControl.sol&quot;</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;./IERC7439.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"> ERC7439</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">AccessControl</span><span>, </span><span class="z-entity z-name">IERC7439</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> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> PARTNER_ROLE </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;PARTNER_ROLE&quot;</span><span>)</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> _tokenIdCounter</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> expireTime</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> TokenInfo</span><span>)</span><span class="z-storage z-type"> public</span><span> tokenInfo</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">uint256</span><span class="z-variable z-parameter z-function"> _expireTime</span><span>)</span><span class="z-entity z-name"> ERC721</span><span>(</span><span>&quot;MyToken&quot;, &quot;MTK&quot;) </span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> _grantRole</span><span>(</span><span>DEFAULT_ADMIN_ROLE</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"> _grantRole</span><span>(</span><span>PARTNER_ROLE</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> expireTime </span><span class="z-keyword">=</span><span> _expireTime</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"> safeMint</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</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"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> tokenId </span><span class="z-keyword">=</span><span> _tokenIdCounter</span><span>.</span><span class="z-entity z-name">current</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _tokenIdCounter</span><span>.</span><span class="z-entity z-name">increment</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _safeMint</span><span>(</span><span>to</span><span>,</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> tokenInfo</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> TokenInfo</span><span>(</span><span>signature</span><span>,</span><span> TokenStatus</span><span>.</span><span>Sold</span><span>,</span><span> expireTime</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> TokenStatusChanged</span><span>(</span><span>tokenId</span><span>,</span><span> TokenStatus</span><span>.</span><span>Sold</span><span>,</span><span> signature</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"> changeState</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"> memory</span><span class="z-variable"> signature</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> TokenStatus</span><span class="z-variable"> tokenStatus</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> newExpireTime</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyRole</span><span>(</span><span class="z-entity z-name">PARTNER_ROLE</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> tokenInfo</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> TokenInfo</span><span>(</span><span>signature</span><span>,</span><span> tokenStatus</span><span>,</span><span> newExpireTime</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> TokenStatusChanged</span><span>(</span><span>tokenId</span><span>,</span><span> tokenStatus</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 class="z-storage z-type"> function</span><span class="z-entity z-name"> _burn</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 class="z-entity z-name">ERC721</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">_burn</span><span>(</span><span>tokenId</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-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"> delete</span><span> tokenInfo</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If you import ERC721URIStorage</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> delete _tokenURIs[tokenId];</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"> supportsInterface</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-variable"> interfaceId</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-storage z-type"> virtual</span><span class="z-storage z-type"> override</span><span>(</span><span class="z-entity z-name">AccessControl</span><span>,</span><span class="z-entity z-name"> ERC721</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>IERC7439</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"> _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 class="z-entity z-name">ERC721</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">hasRole</span><span>(</span><span>PARTNER_ROLE</span><span>,</span><span class="z-entity z-name"> _msgSender</span><span>(</span><span>)</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><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 class="z-keyword"> ||</span><span> to </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 class="z-string"> &quot;ERC7439: You cannot transfer this NFT!&quot;</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-variable z-language"> super</span><span>.</span><span class="z-entity z-name">_beforeTokenTransfer</span><span>(</span><span>from</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>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> 2023-07-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Adam Montgomeryhttps://github.com/montasaurus Ryan Ghodshttps://github.com/ryanio 0agehttps://github.com/0age James Wenzelhttps://github.com/emo-eth Stephan Minhttps://github.com/stephankmin https://wg-eips.ritovision.com/7496/

Extension to ERC-721 and ERC-1155 for dynamic onchain traits

<h2 id="abstract">Abstract</h2> <p>This specification introduces a new interface that extends <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> that defines methods for setting and getting dynamic onchain traits associated with non-fungible tokens. These dynamic traits can be used to represent properties, characteristics, redeemable entitlements, or other attributes that can change over time. By defining these traits onchain, they can be used and modified by other onchain contracts.</p> <h2 id="motivation">Motivation</h2> <p>Trait values for non-fungible tokens are often stored offchain. This makes it difficult to query and mutate these values in contract code. Specifying the ability to set and get traits onchain allows for new use cases like redeeming onchain entitlements and transacting based on a token's traits.</p> <p>Onchain traits can be used by contracts in a variety of different scenarios. For example, a contract that wants to entitle a token to a consumable benefit (e.g. a redeemable) can robustly reflect that onchain. Marketplaces can allow bidding on these tokens based on the trait value without having to rely on offchain state and exposing users to frontrunning attacks. The motivating use case behind this proposal is to protect users from frontrunning attacks on marketplaces where users can list NFTs with certain traits where they are expected to be upheld during fulfillment.</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>Contracts implementing this EIP MUST include the events, getters, and setters as defined below, and MUST return <code>true</code> for <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> <code>supportsInterface</code> for <code>0xaf332f3e</code>, the 4 byte <code>interfaceId</code> for this ERC.</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"> IERC7496</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> Errors </span><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 trying to set a trait that does not exist.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> TraitDoesNotExist</span><span>(</span><span class="z-support">bytes32</span><span> traitKey</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"> Thrown when the token does not exist.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> TokenDoesNotExist</span><span>(</span><span class="z-support">uint256</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"> Events </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"> TraitUpdated</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> traitKey</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"> traitValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TraitUpdatedRange</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> traitKey</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> fromTokenId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> toTokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TraitUpdatedRangeUniformValue</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> traitKey</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> fromTokenId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> toTokenId</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> traitValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TraitUpdatedList</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> traitKey</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> tokenIds</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TraitUpdatedListUniformValue</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> traitKey</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> tokenIds</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> traitValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TraitMetadataURIUpdated</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"> Getters </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"> getTraitValue</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"> traitKey</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 class="z-variable"> traitValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTraitValues</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</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"> traitKeys</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-variable"> traitValues</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTraitMetadataURI</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 class="z-variable"> uri</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> Setters </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"> setTrait</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"> traitKey</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> newValue</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="keys-names">Keys &amp; Names</h3> <p>The <code>traitKey</code> is used to identify a trait. The <code>traitKey</code> MUST be a unique <code>bytes32</code> value identifying a single trait.</p> <p>The <code>traitKey</code> SHOULD be a <code>keccak256</code> hash of a human readable trait name.</p> <h3 id="errors">Errors</h3> <p>If a <code>traitKey</code> is not defined in the contract (i.e., not present in the trait metadata schema), the contract MUST revert with <code>TraitDoesNotExist(traitKey)</code>. This allows applications to detect when they have queried an invalid or unsupported trait key.</p> <p>If a <code>traitKey</code> is defined in the contract but a specific token does not have a value set for that trait, the contract MUST return <code>bytes32(0)</code> as the default value instead of reverting. This enables batch querying of all defined trait keys across multiple tokens without failures due to unset values.</p> <p>If a <code>tokenId</code> does not exist, the contract MUST revert with <code>TokenDoesNotExist(tokenId)</code>. If the token contract already defines a custom error for non-existent tokens (e.g. from <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>), that error MAY be used instead.</p> <h3 id="metadata">Metadata</h3> <p>Trait metadata is necessary to provide information about which traits are present in a contract, how to display trait names and values, and other optional features.</p> <p>The trait metadata must be compliant with the <a href="https://wg-eips.ritovision.com/7496/./assets/DynamicTraitsSchema.json">specified schema</a>.</p> <p>The trait metadata URI MAY be a data URI or point to an offchain resource.</p> <p>The keys in the <code>traits</code> object MUST be unique trait names. If the trait name is 32 byte hex string starting with <code>0x</code> then it is interpreted as a literal <code>traitKey</code>. Otherwise, the <code>traitKey</code> is defined as the <code>keccak256</code> hash of the trait name. A literal <code>traitKey</code> MUST NOT collide with the <code>keccak256</code> hash of any other traits defined in the metadata.</p> <p>The <code>displayName</code> values MUST be unique and MUST NOT collide with the <code>displayName</code> of any other traits defined in the metadata.</p> <p>The <code>validateOnSale</code> value provides a signal to marketplaces on how to validate the trait value when a token is being sold. If the validation criteria is not met, the sale MUST not be permitted by the marketplace contract. If specified, the value of <code>validateOnSale</code> MUST be one of the following (or it is assumed to be <code>none</code>):</p> <ul> <li><code>none</code>: No validation is necessary.</li> <li><code>requireEq</code>: The <code>bytes32</code> <code>traitValue</code> MUST be equal to the value at the time the offer to purchase was made.</li> <li><code>requireNeq</code>: The <code>bytes32</code> <code>traitValue</code> MUST NOT be equal to the value at the time the offer to purchase was made.</li> <li><code>requireUintLt</code>: The <code>bytes32</code> <code>traitValue</code> MUST be less than the value at the time the offer to purchase was made. This comparison is made using the <code>uint256</code> representation of the <code>bytes32</code> value.</li> <li><code>requireUintLte</code>: The <code>bytes32</code> <code>traitValue</code> MUST be less than or equal to the value at the time the offer to purchase was made. This comparison is made using the <code>uint256</code> representation of the <code>bytes32</code> value.</li> <li><code>requireUintGt</code>: The <code>bytes32</code> <code>traitValue</code> MUST be greater than the value at the time the offer to purchase was made. This comparison is made using the <code>uint256</code> representation of the <code>bytes32</code> value.</li> <li><code>requireUintGte</code>: The <code>bytes32</code> <code>traitValue</code> MUST be greater than or equal to the value at the time the offer to purchase was made. This comparison is made using the <code>uint256</code> representation of the <code>bytes32</code> value.</li> </ul> <p>Note that even though this specification requires marketplaces to validate the required trait values, buyers and sellers cannot fully rely on marketplaces to do this and must also take their own precautions to research the current trait values prior to initiating the transaction.</p> <p>Here is an example of the specified 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">traits</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">color</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">displayName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Color</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">dataType</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">points</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">displayName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Total Score</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">dataType</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">decimal</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">signed</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">decimals</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">validateOnSale</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">requireUintGte</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">displayName</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">dataType</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">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"> 32</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">valueMappings</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">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Unnamed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">0x92e75d5e42b80de937d204558acf69c8ea586a244fe88bc0181323fe3b9e3ebf</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-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">tokenOwnerCanUpdateValue</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 class="z-support"> &quot;</span><span class="z-support">birthday</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">displayName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Birthday</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">dataType</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">epochSeconds</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">valueMappings</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">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</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">0x77c2fd45bd8bdef5b5bc773f46759bb8d169f3468caab64d7d5f2db16bb867a8</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">displayName</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-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">dataType</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">epochSeconds</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">valueMappings</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">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1696702201</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="string-metadata-type"><code>string</code> Metadata Type</h4> <p>The <code>string</code> metadata type allows for a string value to be set for a trait.</p> <p>The <code>dataType</code> object MAY have a <code>minLength</code> and <code>maxLength</code> value defined. If <code>minLength</code> is not specified, it is assumed to be 0. If <code>maxLength</code> is not specified, it is assumed to be a reasonable length.</p> <p>The <code>dataType</code> object MAY have a <code>valueMappings</code> object defined. If the <code>valueMappings</code> object is defined, the <code>valueMappings</code> object MUST be a mapping of <code>bytes32</code> values to <code>string</code> or unset <code>null</code> values. The <code>bytes32</code> values SHOULD be the <code>keccak256</code> hash of the <code>string</code> value. The <code>string</code> values MUST be unique. If the trait for a token is updated to <code>null</code>, it is expected that offchain indexers will delete the trait for the token.</p> <h4 id="decimal-metadata-type"><code>decimal</code> Metadata Type</h4> <p>The <code>decimal</code> metadata type allows for a numeric value to be set for a trait in decimal form.</p> <p>The <code>dataType</code> object MAY have a <code>signed</code> value defined. If <code>signed</code> is not specified, it is assumed to be <code>false</code>. This determines whether the <code>traitValue</code> returned is interpreted as a signed or unsigned integer.</p> <p>The <code>dataType</code> object MAY have <code>minValue</code> and <code>maxValue</code> values defined. These should be formatted with the decimals specified. If <code>minValue</code> is not specified, it is assumed to be the minimum value of <code>signed</code> and <code>decimals</code>. If <code>maxValue</code> is not specified, it is assumed to be the maximum value of the <code>signed</code> and <code>decimals</code>.</p> <p>The <code>dataType</code> object MAY have a <code>decimals</code> value defined. The <code>decimals</code> value MUST be a non-negative integer. The <code>decimals</code> value determines the number of decimal places included in the <code>traitValue</code> returned onchain. If <code>decimals</code> is not specified, it is assumed to be 0.</p> <p>The <code>dataType</code> object MAY have a <code>valueMappings</code> object defined. If the <code>valueMappings</code> object is defined, the <code>valueMappings</code> object MUST be a mapping of <code>bytes32</code> values to numeric or unset <code>null</code> values.</p> <h4 id="boolean-metadata-type"><code>boolean</code> Metadata Type</h4> <p>The <code>boolean</code> metadata type allows for a boolean value to be set for a trait.</p> <p>The <code>dataType</code> object MAY have a <code>valueMappings</code> object defined. If the <code>valueMappings</code> object is defined, the <code>valueMappings</code> object MUST be a mapping of <code>bytes32</code> values to <code>boolean</code> or unset <code>null</code> values. The <code>boolean</code> values MUST be unique.</p> <p>If <code>valueMappings</code> is not used, the default trait values for <code>boolean</code> should be <code>bytes32(0)</code> for <code>false</code> and <code>bytes32(uint256(1))</code> (<code>0x0000000000000000000000000000000000000000000000000000000000000001</code>) for <code>true</code>.</p> <h4 id="epochseconds-metadata-type"><code>epochSeconds</code> Metadata Type</h4> <p>The <code>epochSeconds</code> metadata type allows for a numeric value to be set for a trait in seconds since the Unix epoch.</p> <p>The <code>dataType</code> object MAY have a <code>valueMappings</code> object defined. If the <code>valueMappings</code> object is defined, the <code>valueMappings</code> object MUST be a mapping of <code>bytes32</code> values to integer or unset <code>null</code> values.</p> <h3 id="events">Events</h3> <p>Updating traits MUST emit one of:</p> <ul> <li><code>TraitUpdated</code></li> <li><code>TraitUpdatedRange</code></li> <li><code>TraitUpdatedRangeUniformValue</code></li> <li><code>TraitUpdatedList</code></li> <li><code>TraitUpdatedListUniformValue</code></li> </ul> <p>For the <code>Range</code> events, the <code>fromTokenId</code> and <code>toTokenId</code> MUST be a consecutive range of tokens IDs and MUST be treated as an inclusive range.</p> <p>For the <code>List</code> events, the <code>tokenIds</code> MAY be in any order.</p> <p>It is RECOMMENDED to use the <code>UniformValue</code> events when the trait value is uniform across all token ids, so offchain indexers can more quickly process bulk updates rather than fetching each trait value individually.</p> <p>Updating the trait metadata MUST emit the event <code>TraitMetadataURIUpdated</code> so offchain indexers can be notified to query the contract for the latest changes via <code>getTraitMetadataURI()</code>.</p> <p>Note that dynamic trait values MUST NOT be based on time-dependent factors (e.g. block timestamp) or other implicit state changes. All trait changes MUST be the result of an explicit onchain action that emits a corresponding <code>TraitUpdated</code> event. This requirement ensures that offchain indexers can remain synchronized with the current trait values by processing emitted events, rather than needing to continuously poll or re-evaluate trait values.</p> <h3 id="settrait"><code>setTrait</code></h3> <p>If a trait defines <code>tokenOwnerCanUpdateValue</code> as <code>true</code>, then the trait value MUST be updatable by the token owner by calling <code>setTrait</code>.</p> <p>If the value the token owner is attempting to set is not valid, the transaction MUST revert. If the value is valid, the trait value MUST be updated and one of the <code>TraitUpdated</code> events MUST be emitted.</p> <p>If the trait has a <code>valueMappings</code> entry defined for the desired value being set, <code>setTrait</code> MUST be called with the corresponding <code>traitValue</code>.</p> <h2 id="rationale">Rationale</h2> <p>The design of this specification is primarily a key-value mapping for maximum flexibility. This interface for traits was chosen instead of relying on using regular <code>getFoo()</code> and <code>setFoo()</code> style functions to allow for brevity in defining, setting, and getting traits. Otherwise, contracts would need to know both the getter and setter function selectors including the parameters that go along with it. In defining general but explicit get and set functions, the function signatures are known and only the trait key and values are needed to query and set the values. Contracts can also add new traits in the future without needing to modify contract code.</p> <p>The traits metadata allows for customizability of both display and behavior. The <code>valueMappings</code> property can define human-readable values to enhance the traits, for example, the default label of the <code>0</code> value (e.g. if the key was "redeemed", "0" could be mapped to "No", and "1" to "Yes"). The <code>validateOnSale</code> property lets the token creator define which traits should be protected on order creation and fulfillment, to protect end users against frontrunning.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As a new EIP, no backwards compatibility issues are present, except for the point in the specification above that it is explicitly required that the onchain traits MUST override any conflicting values specified by the ERC-721 or ERC-1155 metadata URIs.</p> <h2 id="test-cases">Test Cases</h2> <p>Authors have included Foundry tests covering functionality of the specification in the <a href="https://wg-eips.ritovision.com/7496/./assets/ERC721DynamicTraits.t.sol">assets folder</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Authors have included reference implementations of the specification in the <a href="https://wg-eips.ritovision.com/7496/./assets/DynamicTraits.sol">assets folder</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The set* methods exposed externally MUST be permissioned so they are not callable by everyone but only by select roles or addresses.</p> <p>Marketplaces SHOULD NOT trust offchain state of traits as they can be frontrunned. Marketplaces SHOULD check the current state of onchain traits at the time of transfer. Marketplaces MAY check certain traits that change the value of the NFT (e.g. redemption status, defined by metadata values with <code>validateOnSale</code> property) or they MAY hash all the trait values to guarantee the same state at the time of order creation.</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-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ryan Ghodshttps://github.com/ryanio 0agehttps://github.com/0age Adam Montgomeryhttps://github.com/montasaurus Stephan Minhttps://github.com/stephankmin https://wg-eips.ritovision.com/7498/

Extension to ERC-721 and ERC-1155 for onchain and offchain redeemables

<h2 id="abstract">Abstract</h2> <p>This specification introduces a new interface that extends <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> to enable the discovery and use of onchain and offchain redeemables for NFTs. Onchain getters and events facilitate discovery of redeemable campaigns and their requirements. New onchain mints use an interface that gives context to the minting contract of what was redeemed. For redeeming physical products and goods (offchain redeemables) a <code>redemptionHash</code> and <code>signer</code> can tie onchain redemptions with offchain order identifiers that contain chosen product and shipping information.</p> <h2 id="motivation">Motivation</h2> <p>Creators frequently use NFTs to create redeemable entitlements for digital and physical goods. However, without a standard interface, it is challenging for users and apps to discover and interact with these NFTs in a predictable and standard way. This standard aims to encompass enabling broad functionality for:</p> <ul> <li>discovery: events and getters that provide information about the requirements of a redemption campaign</li> <li>onchain: token mints with context of items spent</li> <li>offchain: the ability to associate with ecommerce orders (through <code>redemptionHash</code>)</li> <li>trait redemptions: improving the burn-to-redeem experience with <a href="https://wg-eips.ritovision.com/7496/">ERC-7496</a> Dynamic Traits.</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>The token MUST have the following interface and MUST return <code>true</code> for <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> supportsInterface for <code>0x1ac61e13</code>, the 4 byte interfaceId of the 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"> IERC7498</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> Events </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"> CampaignUpdated</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> campaignId</span><span>, </span><span class="z-variable">Campaign</span><span class="z-variable"> campaign</span><span>, </span><span class="z-support">string</span><span class="z-variable"> metadataURI</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Redemption</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> campaignId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> requirementsIndex</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> redemptionHash</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> considerationTokenIds</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> traitRedemptionTokenIds</span><span>, </span><span class="z-support">address</span><span class="z-variable"> redeemedBy</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> Structs </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Campaign</span><span> {</span></span> <span class="giallo-l"><span> CampaignParams params</span><span>;</span></span> <span class="giallo-l"><span> CampaignRequirements</span><span>[</span><span>]</span><span> requirements</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> one requirement must be fully satisfied for a successful redemption</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"> CampaignParams</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> startTime</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> endTime</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> maxCampaignRedemptions</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> manager</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> the address that can modify the campaign</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> signer</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> null address means no EIP-712 signature required</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"> CampaignRequirements</span><span> {</span></span> <span class="giallo-l"><span> OfferItem</span><span>[</span><span>]</span><span> offer</span><span>;</span></span> <span class="giallo-l"><span> ConsiderationItem</span><span>[</span><span>]</span><span> consideration</span><span>;</span></span> <span class="giallo-l"><span> TraitRedemption</span><span>[</span><span>]</span><span> traitRedemptions</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"> TraitRedemption</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> substandard</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"> bytes32</span><span> traitKey</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> traitValue</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> substandardValue</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"> Getters </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"> getCampaign</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> campaignId</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">Campaign</span><span class="z-storage z-type"> memory</span><span class="z-variable"> campaign</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> metadataURI</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> totalRedemptions</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> Setters </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"> createCampaign</span><span>(</span><span class="z-storage z-type">Campaign</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> campaign</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> metadataURI</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"> campaignId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateCampaign</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> campaignId</span><span>,</span><span class="z-storage z-type"> Campaign</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> campaign</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> metadataURI</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"> redeem</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"> considerationTokenIds</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-storage z-type"> calldata</span><span class="z-variable"> extraData</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">-</span><span class="z-keyword">-</span><span class="z-keyword">-</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/*</span><span class="z-comment"> Seaport structs, for reference, used in offer/consideration above </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"> ItemType</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> NATIVE</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ERC20</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ERC721</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ERC1155</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"> OfferItem</span><span> {</span></span> <span class="giallo-l"><span> ItemType itemType</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> identifierOrCriteria</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> startAmount</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> endAmount</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"> ConsiderationItem</span><span> extends OfferItem </span><span>{</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> payable</span><span> recipient</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> (</span><span class="z-keyword">note</span><span class="z-comment">: psuedocode above, as of this writing can&#39;t extend structs in solidity)</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"> SpentItem</span><span> {</span></span> <span class="giallo-l"><span> ItemType itemType</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> identifier</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></code></pre><h3 id="creating-campaigns">Creating campaigns</h3> <p>When creating a new campaign, <code>createCampaign</code> MUST be used and MUST return the newly created <code>campaignId</code> along with the <code>CampaignUpdated</code> event. The <code>campaignId</code> MUST be a counter incremented with each new campaign. The first campaign MUST have an id of <code>1</code>.</p> <h3 id="updating-campaigns">Updating campaigns</h3> <p>Updates to campaigns MAY use <code>updateCampaign</code> and MUST emit the <code>CampaignUpdated</code> event. If an address other than the <code>manager</code> tries to update the campaign, it MUST revert with <code>NotManager()</code>. If the manager wishes to make the campaign immutable, the <code>manager</code> MAY be set to the null address.</p> <h3 id="offer">Offer</h3> <p>If tokens are set in the params <code>offer</code>, the tokens MUST implement the <code>IRedemptionMintable</code> interface in order to support minting new items. The implementation SHOULD be however the token mechanics are desired. The implementing token MUST return true for ERC-165 <code>supportsInterface</code> for the interfaceId of <code>IRedemptionMintable</code>, <code>0x81fe13c2</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"> IRedemptionMintable</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mintRedemption</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> campaignId</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-storage z-type"> OfferItem</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> offer</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> ConsiderationItem</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> consideration</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> TraitRedemption</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> traitRedemptions</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> <p>When <code>mintRedemption</code> is called, it is RECOMMENDED to replace the token identifiers in the consideration items and trait redemptions with the items actually being redeemed.</p> <h3 id="consideration">Consideration</h3> <p>Any token may be specified in the campaign requirement <code>consideration</code>. This will ensure the token is transferred to the <code>recipient</code>. If the token is meant to be burned, the recipient SHOULD be <code>0x000000000000000000000000000000000000dEaD</code>. If the token can internally handle burning its own tokens and reducing totalSupply, the token MAY burn the token instead of transferring to the recipient <code>0x000000000000000000000000000000000000dEaD</code>.</p> <h3 id="dynamic-traits">Dynamic traits</h3> <p>Including trait redemptions is optional, but if the token would like to enable trait redemptions the token MUST include <a href="https://wg-eips.ritovision.com/7496/">ERC-7496</a> Dynamic Traits.</p> <h3 id="signer">Signer</h3> <p>A signer MAY be specified to provide a signature to process the redemption. If the signer is not the null address, the signature MUST recover to the signer address via <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> or <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>.</p> <p>The EIP-712 struct for signing MUST be as follows: <code>SignedRedeem(address owner,uint256[] considerationTokenIds,uint256[] traitRedemptionTokenIds,uint256 campaignId,uint256 requirementsIndex, bytes32 redemptionHash, uint256 salt)"</code></p> <h3 id="redeem-function">Redeem function</h3> <p>The <code>redeem</code> function MUST use the <code>consideration</code>, <code>offer</code>, and <code>traitRedemptions</code> specified by the <code>requirements</code> determined by the <code>campaignId</code> and <code>requirementsIndex</code>:</p> <ul> <li>Execute the transfers in the <code>consideration</code></li> <li>Mutate the traits specified by <code>traitRedemptions</code> according to ERC-7496 Dynamic Traits</li> <li>Call <code>mintRedemption()</code> on every <code>offer</code> item</li> </ul> <p>The <code>Redemption</code> event MUST be emitted for every valid redemption that occurs.</p> <h4 id="redemption-extradata">Redemption extraData</h4> <p>The extraData layout MUST conform to the below:</p> <table><thead><tr><th>bytes</th><th>value</th><th>description / notes</th></tr></thead><tbody> <tr><td>0-32</td><td>campaignId</td><td></td></tr> <tr><td>32-64</td><td>requirementsIndex</td><td>index of the campaign requirements met</td></tr> <tr><td>64-96</td><td>redemptionHash</td><td>hash of offchain order ids</td></tr> <tr><td>96-*</td><td>uint256[] traitRedemptionTokenIds</td><td>token ids for trait redemptions, MUST be in same order of campaign TraitRedemption[]</td></tr> <tr><td>*-(+32)</td><td>salt</td><td>if signer != address(0)</td></tr> <tr><td>*-(+*)</td><td>signature</td><td>if signer != address(0). can be for EIP-712 or ERC-1271</td></tr> </tbody></table> <p>The <code>requirementsIndex</code> MUST be the index in the <code>requirements</code> array that satisfies the redemption. This helps reduce gas to find the requirement met.</p> <p>The <code>traitRedemptionTokenIds</code> specifies the token IDs required for the trait redemptions in the requirements array. The order MUST be the same order of the token addresses expected in the array of <code>TraitRedemption</code> structs in the campaign requirement used.</p> <p>If the campaign <code>signer</code> is the null address the <code>salt</code> and <code>signature</code> MUST be omitted.</p> <p>The <code>redemptionHash</code> is designated for offchain redemptions to reference offchain order identifiers to track the redemption to.</p> <p>The function MUST check that the campaign is active (using the same boundary check as Seaport, <code>startTime &lt;= block.timestamp &lt; endTime</code>). If it is not active, it MUST revert with <code>NotActive()</code>.</p> <h3 id="trait-redemptions">Trait redemptions</h3> <p>The token MUST respect the TraitRedemption substandards as follows:</p> <table><thead><tr><th>substandard ID</th><th>description</th><th>substandard value</th></tr></thead><tbody> <tr><td>1</td><td>set value to <code>traitValue</code></td><td>prior required value. if blank, cannot be the <code>traitValue</code> already</td></tr> <tr><td>2</td><td>increment trait by <code>traitValue</code></td><td>max value</td></tr> <tr><td>3</td><td>decrement trait by <code>traitValue</code></td><td>min value</td></tr> <tr><td>4</td><td>check value is <code>traitValue</code></td><td>n/a</td></tr> </tbody></table> <h3 id="max-campaign-redemptions">Max campaign redemptions</h3> <p>The token MUST check that the <code>maxCampaignRedemptions</code> is not exceeded. If the redemption does exceed <code>maxCampaignRedemptions</code>, it MUST revert with <code>MaxCampaignRedemptionsReached(uint256 total, uint256 max)</code></p> <h3 id="metadata-uri">Metadata URI</h3> <p>The metadata URI MUST conform to the below 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 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">campaigns</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">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">campaignId</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">number</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></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">A one-line summary of the redeemable. Markdown is not supported.</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">details</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 multi-line or multi-paragraph description of the details of the redeemable. Markdown is supported.</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">imageUrls</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">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">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 image URLs for the redeemable. The first image will be used as the thumbnail. Will rotate in a carousel if multiple images are provided. Maximum 5 images.</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">bannerUrl</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 banner image for the redeemable.</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">faq</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">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">question</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">answer</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">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">question</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">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 class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">contentLocale</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 language tag for the content provided by this metadata. https://www.rfc-editor.org/rfc/rfc9110.html#name-language-tags</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">maxRedemptionsPerToken</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 maximum number of redemptions per token. When isBurn is true should be 1, else can be a number based on the trait redemptions limit.</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">isBurn</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">If the redemption burns the token.</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">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">An optional unique identifier for the campaign, for backends to identify when draft campaigns are published onchain.</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">productLimitForRedemption</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">number</span><span class="z-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 number of products which are able to be chosen from the products array for a single redemption.</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">products</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://schema.org/Product</span><span class="z-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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">url</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">description</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">campaignId</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">description</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">imageUrls</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">isBurn</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> <p>Future EIPs MAY inherit this one and add to the above metadata to add more features and functionality.</p> <h3 id="erc-1155-semi-fungibles">ERC-1155 (Semi-fungibles)</h3> <p>This standard MAY be applied to ERC-1155 but the redemptions would apply to all token amounts for specific token identifiers. If the ERC-1155 contract only has tokens with amount of 1, then this specification MAY be used as written.</p> <h2 id="rationale">Rationale</h2> <p>The "offer" and "consideration" structs from Seaport were used to create a similar language for redeemable campaigns. The "offer" is what is being offered, e.g. a new onchain token, and the "consideration" is what must be satisfied to complete the redemption. The "consideration" field has a "recipient", who the token should be transferred to. For trait updates that do not require moving of a token, <code>traitRedemptionTokenIds</code> is specified instead.</p> <p>The "salt" and "signature" fields are provided primarily for offchain redemptions where a provider would want to sign approval for a redemption before it is conducted onchain, to prevent the need for irregular state changes. For example, if a user lives outside a region supported by the shipping of an offchain redeemable, during the offchain order creation process the signature would not be provided for the onchain redemption when seeing that the user's shipping country is unsupported. This prevents the user from redeeming the NFT, then later finding out the shipping isn't supported after their NFT is already burned or trait is mutated.</p> <p><a href="https://wg-eips.ritovision.com/7496/">ERC-7496</a> Dynamic Traits is used for trait redemptions to support onchain enforcement of trait values for secondary market orders.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As a new EIP, no backwards compatibility issues are present.</p> <h2 id="test-cases">Test Cases</h2> <p>Authors have included Foundry tests covering functionality of the specification in the <a href="https://wg-eips.ritovision.com/7498/./assets/ERC721ShipyardRedeemable.t.sol">assets folder</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Authors have included reference implementations of the specification in the <a href="https://wg-eips.ritovision.com/7498/./assets/ERC7498NFTRedeemables.sol">assets folder</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>If trait redemptions are desired, tokens implementing this EIP must properly implement <a href="https://wg-eips.ritovision.com/7496/">ERC-7496</a> Dynamic Traits.</p> <p>For tokens to be minted as part of the params <code>offer</code>, the <code>mintRedemption</code> function contained as part of <code>IRedemptionMintable</code> MUST be permissioned and ONLY allowed to be called by specified addresses.</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-27T00:00:00+00:00 2026-02-11T14:48:25+00:00 Dexaranhttps://github.com/Dexarandexaran@ethereumclassic.org https://wg-eips.ritovision.com/7417/

Smart-contract service that converts token of one ERC version to another

<h2 id="abstract">Abstract</h2> <p>There are multiple token standards on Ethereum chain currently. This EIP introduces a concept of cross-standard interoperability by creating a service that allows <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens to be upgraded to <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> tokens anytime. <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> tokens can be converted back to <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> version without any restrictions to avoid any problems with backwards compatibility and allow different standards to co-exist and become interoperable and interchangeable.</p> <p>In order to perform the conversion, a user must deposit tokens of one standard to the Converter contract and it will automatically send tokens of another standard back.</p> <h2 id="motivation">Motivation</h2> <p>This proposal introduces a concept of a token standard upgrading procedure driven by a specialized smart-contract which can convert tokens of one standard to another at any time.</p> <p>Currently some tokens are available on different chains in different standards, for example most exchanges support <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> USDT, TRX USDT, BEP-20 USDT and all this tokens are in fact the same USDT token. This proposal is intended to introduce a concept where there can be a <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> USDT and <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> USDT available on Ethereum mainnet at the same time and these would be freely interchangeable.</p> <p>The address of the deployed Token Converter must be described here as to solve the trust issues for the token developers and help them figure out a proper way of interacting with the Converter.</p> <p>As Ethereum already has an established ecosystem of tokens and <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> is the most adopted standard at the moment the lack of defined migration processes can be a bottleneck for newer standards adoption. This proposal addresses the problem of coordinating the upgrading process and addresses the backwards compatibility problems for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> tokens.</p> <p>The Token Converter is supposed to allow anyone to create an alternative version of an existing token implemented in a different standard. This proposal focuses on <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> standards and takes into account the specifics of this particular token standards. It is assumed that the most common case would be creation of <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> version for an existing <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token.</p> <p>The implementation of this service is an alternative to convincing each token developer to choose an alternative standard at the moment of the token deployment or during the development stage of their project. With this service there will be no need to choose one standard and stick with it as every token can be available in both concurrently.</p> <p>The implementation of this Token Converter service is supposed to be a contract deployed on Ethereum mainnet once and forever. It's address will be provided in the text of this proposal as to avoid any potential trust issues and assure the developers that the service they are interacting with is exactly the one which drives the conversion process of existing tokens.</p> <p>All the <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> tokens created by the Token Converter will be identical in a way that they all implement the same functions, which return the same values and there is no ambiguity there. This helps to avoid problems where a token deployed during the early stage of a token standard adoption may implement it improperly or there can be an ambiguity in the standard itself that would allow developers to implement tokens of one standard in different ways.</p> <p>For example it was a common case with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> where developers could implement custom logic of the <code>transfer</code> function and mess the return values. The <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> specification declares that a <code>transfer</code> function MUST return a <code>bool</code> value, however in practice we have three different types of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens which are not compatible with each other:</p> <ol> <li><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens that return <code>true</code> on success and revert on an error.</li> <li><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens that return <code>true</code> on success and <code>false</code> on an error without reverting the transaction.</li> <li><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens that don't have return values and revert on an error.</li> </ol> <p>Technically the third category of tokens is not compatible with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard. However, USDT token deployed on Ethereum mainnet at <code>0xdac17f958d2ee523a2206206994597c13d831ec7</code> address does not implement return values and it is one of the most used tokens and it is not an option to deny supporting USDT due to it's improper implementation of the standard.</p> <p>The Token Converter eliminates the issue where different development teams may implement the standard with slight modifications and result in a situation where we would have different versions of the same standard on the mainnet.</p> <p>At the same time the Converter enables the concurrent token support in other smart-contracts, such as decentralized exchanges. The Converter can guarantee that a pair of two tokens one of which is a wrapper for another is in fact the same token that can be converted from one standard to another at any time. This enables the creation of liquidity pools where two different tokens are dealt with as if they were one token.</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 Token Converter system comprises two main components:</p> <ul> <li> <p>Converter contract.</p> </li> <li> <p>Wrapper contracts. Each original token can have exactly one wrapper of each standard.</p> </li> </ul> <p>Converter contract can deploy new <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper contracts for any <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token that does not have a <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper currently. There MUST be exactly one <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper for each <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token.</p> <p>Converter contract MUST accept deposits of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens and send <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> tokens to the depositor at 1:1 ratio. Upon depositing 1234 units of <code>ERC20 token_A</code> the depositor MUST receive exactly 1234 units of <code>ERC223 token_A</code>. This is done by issuing new <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> tokens at the moment of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> deposit. The original <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens MUST be frozen in the Converter contract and available for claiming back.</p> <p>Converter contract MUST accept deposits of <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> tokens and send <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens to the depositor at 1:1 ratio. This is done by releasing the original <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens at the moment of <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> deposit. The deposited <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> tokens must be burned.</p> <h3 id="token-converter">Token Converter</h3> <h4 id="conver-contract-methods">Conver contract methods</h4> <h5 id="geterc20wrapperfor"><code>getERC20WrapperFor</code></h5> <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"> getERC20WrapperFor</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-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span></span></code></pre> <p>Returns the address of the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> wrapper for a given token address. Returns <code>0x0</code> if there is no <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> version for the provided token address. There can be exactly one wrapper for any given <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> token address created by the Token Converter contract.</p> <h5 id="geterc223wrapperfor"><code>getERC223WrapperFor</code></h5> <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"> getERC223WrapperFor</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-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span></span></code></pre> <p>Returns the address of the <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper for a given token address. Returns <code>0x0</code> if there is no <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> version for the provided token address. There can be exactly one <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper for any given <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token address created by the Token Converter contract.</p> <h5 id="geterc20originfor"><code>getERC20OriginFor</code></h5> <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"> getERC20OriginFor</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _erc223Token</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></code></pre> <p>Returns the address of the original <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token for the provided <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper. Returns <code>0x0</code> if the provided <code>_erc223Token</code> is not an address of any <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper created by the Token Converter contract.</p> <h5 id="geterc223originfor"><code>getERC223OriginFor</code></h5> <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"> getERC223OriginFor</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _erc20Token</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></code></pre> <p>Returns the address of the original <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> token for the provided <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> wrapper. Returns <code>0x0</code> if the provided <code>_erc20Token</code> is not an address of any wrapper created by the Token Converter contract.</p> <h5 id="predictwrapperaddress"><code>predictWrapperAddress</code></h5> <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"> predictWrapperAddress</span><span>(</span><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"> bool</span><span class="z-variable z-parameter z-function"> _isERC20</span><span class="z-comment"> //</span><span class="z-comment"> Is the provided _token a ERC-20 or not?</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If it is set as ERC-20 then we will predict the address of a </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ERC-223 wrapper for that token.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Otherwise we will predict ERC-20 wrapper address.</span></span> <span class="giallo-l"><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></code></pre> <p>Wrapper contracts are deployed via <code>CREATE2</code> opcode and it is possible to predict the address of a wrapper which is not yet deployed. The address of a wrapper contract depends on the bytecode therefore it is necessary to specify if the address of wrapper <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> or wrapper <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> must be predicted.</p> <p>Providing <code>_token</code> address and <code>_isERC20 = false</code> will result in <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> wrapper address being predicted.</p> <p>Providing <code>_token</code> address and <code>_isERC20 = true</code> will result in <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper address being predicted.</p> <h5 id="createerc223wrapper"><code>createERC223Wrapper</code></h5> <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"> createERC223Wrapper</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _erc20Token</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></code></pre> <p>Creates a new <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper for a given <code>_erc20Token</code> if it does not exist yet. Reverts the transaction if the wrapper already exist. Returns the address of the new wrapper token contract on success. Reverts if <code>_erc223Token</code> is a wrapper created by the Converter.</p> <p>The deployed contract will be a standard <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> token with <code>approve</code> and <code>transferFrom</code> functions implemented for backwards compatibility.</p> <p>All <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrappers deployed by the Converter will have <code>standard() pure returns (bytes32)</code> function implemented which returns <code>223</code>. This serves further token standard introspection as <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> may not be reliable when dealing with identifying the internal logic implemented within <code>transfer</code> function of a token.</p> <p>NOTE: This function does not verify the standard of <code>_erc20Token</code> because there is no reliable method of introspection available which could guarantee that the provided token implements a particular standard. As the result it is possible to create a <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper for an original <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> token.</p> <h5 id="createerc20wrapper"><code>createERC20Wrapper</code></h5> <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"> createERC20Wrapper</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _erc223Token</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></code></pre> <p>Creates a new <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> wrapper for a given <code>_erc223Token</code> if it does not exist yet. Reverts the transaction if the wrapper already exist. Returns the address of the new wrapper token contract on success. Reverts if <code>_erc223Token</code> is a wrapper created by the Converter.</p> <p>NOTE: This function does not verify the standard of <code>_erc223Token</code> because there is no reliable method of introspection available which could guarantee that the provided token implements a particular standard. As the result it is possible to create a <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> wrapper for an original <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token.</p> <h5 id="wraperc20toerc223"><code>wrapERC20toERC223</code></h5> <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"> wrapERC20toERC223</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _ERC20token</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> <p>Withdraws <code>_amount</code> of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens from the transaction sender with <code>transferFrom</code> function. Delivers the <code>_amount</code> of <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper tokens to the sender of the transaction. Stores the original tokens at the balance of the Token Converter contract for future claims. Returns <code>true</code> on success. The Token Converter must keep record of the amount of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens that were deposited with <code>wrapERC20toERC223</code> function because it is possible to deposit <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens to any contract by directly sending them with <code>transfer</code> function.</p> <p>If there is no <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper for the <code>_ERC20token</code> then creates it by calling a <code>createERC223Wrapper(_erc20toke)</code> function.</p> <p>There is no special function to unwrap <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrappers to <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> origin as this logic is implemented in the <code>tokenReceived</code> function of the Converter.</p> <h5 id="unwraperc20toerc223"><code>unwrapERC20toERC223</code></h5> <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"> unwrapERC20toERC223</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _ERC20token</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> <p>Withdraws <code>_amount</code> of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens from the transaction sender with <code>transferFrom</code> function. Delivers the <code>_amount</code> of <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper tokens to the sender of the transaction. Stores the original tokens at the balance of the Token Converter contract for future claims. Returns <code>true</code> on success. The Token Converter must keep record of the amount of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens that were deposited with <code>wrapERC20toERC223</code> function because it is possible to deposit <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens to any contract by directly sending them with <code>transfer</code> function.</p> <p>If there is no <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper for the <code>_ERC20token</code> then creates it by calling a <code>createERC223Wrapper(_erc20toke)</code> function.</p> <h5 id="converterc20"><code>convertERC20</code></h5> <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"> convertERC20</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _token</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> <p>Automatically determines if the provided <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token is a wrapper or not. If it is a wrapper then executes <code>unwrapERC20toERC223</code> function. If the provided token is an origin then executes <code>wrapERC20toERC223</code> function.</p> <p>This function is implemented to significantly simplify the workflow of services that integrate both versions of one token in the same contract and need to automatically convert tokens through the Converter.</p> <h5 id="iswrapper"><code>isWrapper</code></h5> <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"> isWrapper</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-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>Returns <code>true</code> if the provided <code>_token</code> address is an address of a wrapper created by the Converter.</p> <p>NOTE: This function does not identify the standard of a <code>_token</code>. There can be exactly one origin for any wrapper created by the Converter. However an original token can have two wrappers, one of each standard.</p> <h5 id="tokenreceived"><code>tokenReceived</code></h5> <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"> tokenReceived</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"> uint</span><span class="z-variable z-parameter z-function"> _value</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"> _data</span><span>)</span><span class="z-storage z-type"> public</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></code></pre> <p>This is a standard <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> transaction handler function and it is called by the <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> token contract when <code>_from</code> is sending <code>_value</code> of <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> tokens to <code>address(this)</code> address. In the scope of this function <code>msg.sender</code> is the address of the <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> token contract and <code>_from</code> is the sender of the token transfer.</p> <p>Automatically determines</p> <p>If <code>msg.sender</code> is an address of <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper created by the Token Converter then <code>_value</code> of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> original token must be sent to the <code>_from</code> address.</p> <p>If <code>msg.sender</code> is not an address of any <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper known to the Token Converter then it is considered a <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> origin and <code>_value</code> amount of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> wrapper tokens must be sent to the <code>_from</code> address. If the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> wrapper for the <code>msg.sender</code> token does not exist then create it first.</p> <p>Returns <code>0x8943ec02</code>.</p> <h5 id="extractstuckerc20"><code>extractStuckERC20</code></h5> <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"> extractStuckERC20</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _token</span><span>)</span></span></code></pre> <p>This function allows to extract the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens that were directly deposited to the contract with <code>transfer</code> function to prevent users who may send tokens by mistake from permanently losing their tokens. Since the Token Converter calculates the amount of tokens that were deposited legitimately with <code>convertERC20toERC223</code> function it is always possible to calculate the amount of "accidentally deposited tokens" by subtracting the recorded amount from the returned value of the <code>balanceOf( address(this) )</code> function called on the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token contract.</p> <h3 id="converting-erc-20-tokens-to-erc-223">Converting <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens to <a href="https://wg-eips.ritovision.com/223/">ERC-223</a></h3> <p>In order to convert <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens to <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> the token holder should:</p> <ol> <li>Call the <code>approve</code> function of the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token and allow Token Converter to withdraw tokens from the token holders address via <code>transferFrom</code> function.</li> <li>Wait for the transaction with <code>approve</code> to be submitted to the blockchain.</li> <li>Call the <code>convertERC20toERC223</code> function of the Token Converter contract.</li> </ol> <h3 id="converting-erc-223-wrapper-tokens-back-to-erc-20">Converting <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper tokens back to <a href="https://wg-eips.ritovision.com/20/">ERC-20</a></h3> <p>In order to convert <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens to <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> the token holder should:</p> <ol> <li>Send <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> tokens to the address of the Token Converter contract via <code>transfer</code> function of the <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> token contract.</li> </ol> <h2 id="rationale">Rationale</h2> <h3 id="support-of-erc-223-original-tokens">Support of <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> original tokens</h3> <p>Two methods of implementing a Token Converter service were considered: (1) a converter that can only create <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> versions of the existing <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens, and (2) a converter that can create both versions (<a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/223/">ERC-223</a>) of any original token.</p> <p>The first approach would encourage developers to always deploy an original token as <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and then create it's <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> version in the converter. If it would happen that some developers may consider <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> as their original standard then they would be left with the problem of creating their custom <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> version of the token. In addition, if any third party contracts like liquidity pools are using the proposed Token Converter to ensure that a token can be listed on a DEX with two versions and both can be combined within one pool - then such contract would not be able to recognize any original <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> token and it's <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> version as a valid pair of contracts that represent one token available in two standards.</p> <p>For that reason it was decided to go with the second approach where the Converter can create <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> wrappers for original <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> tokens.</p> <h3 id="support-of-approve-transferfrom-functions-in-the-erc-223-wrapper-tokens">Support of <code>approve</code> &amp; <code>transferFrom</code> functions in the <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper tokens</h3> <p>This functions are superfluous for a <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> token since the <code>transfer</code> function can be used to deposit tokens of this standard to contracts. The current ecosystem is built for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens however and there are plenty of multisig contracts that rely on accepting tokens deposited without any callback with an assumption that it is not necessary for a multisig to count the amount of tokens it stores.</p> <p>There can be any other contracts and scenarios where it would be necessary to deposit a token to a contract which is relying on an assumption that tokens are deposited without invoking a callback in the recipient. As the result we can expect that any original deployed <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> tokens will support this functions, as token developers strive for backward compatibility with the existing ecosystem. In order to make tokens deployed by the converter a reference implementation for developers that can be used without any modifications it was decided to support this functions in the <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper contracts.</p> <p><code>transferFrom</code> function does not support error handling and this needs to be taken into account. It is possible to deposit tokens to a contract which is not designed to receive them by approving X tokens to your own address and then calling a <code>transferFrom(self, contract, X)</code>. The tokens will be deposited regardless of whether the recipient contract is designed to hold/receive tokens or not. The tokens may get permanently stuck if the recipient contract did not implement the extraction functions. The <code>approve</code> &amp; <code>transferFrom</code> function is not the default method of token transferring however and it is not directly used by any wallets and any other software that manages tokens. The <code>transfer</code> function (which is safe) is used instead. The <code>transferFrom</code> function is supposed to be invoked by a contract to pull tokens from the approver.</p> <p>As the result, the <code>approve</code> &amp; <code>transferFrom</code> transferring method must be avoided with <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> tokens whenever possible.</p> <h3 id="modified-transfer-events-of-the-erc-223-token">Modified transfer events of the <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> token</h3> <p>The pure <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> token implementation has the following event emitted on a token transfer: <code>event Transfer(address indexed _from, address indexed _to, uint256 _value, bytes _data)</code>. This events are different from ones emitted by <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens and may not be properly recognized by existing blockchain explorers, wallets and other services that browse token transfers history.</p> <p>It was considered that events are not an important part of the standard as these do not affect the logic of the token, it's workflow and it's security. When developing the Converter it was decided to prioritize compatibility with existing ecosystem.</p> <h3 id="standard-function-usage-for-the-introspection"><code>standard()</code> function usage for the introspection</h3> <p>The main existing method of introspection is currently <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> which inspects the signatures of functions implemented in a contract. It is not possible to differentiate an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token from an <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> token by just browsing functions that they implement without digging their internal logic.</p> <p>Here is a token and it is not possible to identify if it should be dealt with as <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> or <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> because it depends on the actual implemenation of it's <code>transfer</code> function logic.</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"> Token</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"> virtual</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"> virtual</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"> decimals</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> virtual</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"> function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-support">address</span><span>,</span><span class="z-support"> uint256</span><span>)</span><span class="z-storage z-type"> external</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-storage z-type"> function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-support">address</span><span>,</span><span class="z-support"> uint256</span><span>)</span><span class="z-storage z-type"> external</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-storage z-type"> function</span><span class="z-entity z-name"> transferFrom</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-storage z-type"> external</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>}</span></span></code></pre> <p>In case of this implementation the token will behave as <a href="https://wg-eips.ritovision.com/20/">ERC-20</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"> 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"> _amount</span><span>)</span><span class="z-storage z-type"> external</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 class="giallo-l"><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 class="z-keyword">=</span><span> _amount</span><span>;</span></span> <span class="giallo-l"><span> balances</span><span>[</span><span>_to</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> _amount</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>In case of this implementation the token will behave as <a href="https://wg-eips.ritovision.com/223/">ERC-223</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"> 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"> _amount</span><span>)</span><span class="z-storage z-type"> external</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 class="giallo-l"><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 class="z-keyword">=</span><span> _amount</span><span>;</span></span> <span class="giallo-l"><span> balances</span><span>[</span><span>_to</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> _amount</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>_to</span><span>.</span><span class="z-entity z-name">isContract</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC223Recipient</span><span>(</span><span>_to</span><span>)</span><span>.</span><span class="z-entity z-name">tokenReceived</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> _amount</span><span>,</span><span> hex</span><span class="z-string">&quot;000000&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></span></code></pre> <p>Also, there are plenty of tokens that do not implement <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> introspection at all. As the result it was decided to implement a special <code>standard() returns (uint32)</code> function in all <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrappers created by the Converter and assume that original <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> tokens may explicityly declare themselves as <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> by implementing the same function too. It is assumed that if a token does not implement this function then it is <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>.</p> <p>This method of token standard introspection is more precise than <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is supposed to eliminate the backwards compatibility concerns for different token standards making them interchangeable and interoperable.</p> <p>This service is the first of its kind and therefore does not have any backwards compatibility issues as it does not have any predecessors.</p> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></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.19</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"> Address</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isContract</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</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-comment"> //</span><span class="z-comment"> This method relies on extcodesize, which returns 0 for contracts in</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> construction, since the code is only stored at the end of the</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> constructor execution.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> size</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-keyword"> solhint-disable</span><span class="z-comment">-next-line no-inline-assembly</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span><span> size </span><span class="z-keyword">:=</span><span class="z-entity z-name"> extcodesize</span><span>(</span><span>account</span><span>)</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> size </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> <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"> totalSupply</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"> balanceOf</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"> transfer</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"> 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"> 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"> 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"> 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"> 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"> transferFrom</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"> 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"> 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">interface</span><span class="z-entity z-name"> IERC20Metadata</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-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 token</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"> The</span><span class="z-comment"> symbol of the token</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"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> number of decimal places the token has</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"> 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></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"> IERC223Recipient</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenReceived</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"> uint</span><span class="z-variable z-parameter z-function"> _value</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"> _data</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">bytes4</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"> 0x8943ec02</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">abstract</span><span class="z-storage z-type"> contract</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"> * bytes4(keccak256(&#39;supportsInterface(bytes4)&#39;)) == 0x01ffc9a7</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_ERC165 </span><span class="z-keyword">=</span><span class="z-constant"> 0x01ffc9a7</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes4</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bool</span><span>)</span><span class="z-storage z-type"> private</span><span> _supportedInterfaces</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> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Derived contracts need only register support for their own interfaces,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> we register support for ERC165 itself here</span></span> <span class="giallo-l"><span class="z-entity z-name"> _registerInterface</span><span>(</span><span>_INTERFACE_ID_ERC165</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"> 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-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> _supportedInterfaces</span><span>[</span><span>interfaceId</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"> _registerInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceId</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>interfaceId </span><span class="z-keyword">!=</span><span class="z-constant"> 0xffffffff</span><span>,</span><span class="z-string"> &quot;ERC165: invalid interface id&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _supportedInterfaces</span><span>[</span><span>interfaceId</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> <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"> IERC223</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"> 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">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"> 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">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"> 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-storage z-type"> virtual</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 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-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-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"> virtual</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 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"> uint</span><span class="z-variable"> value</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-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"> uint</span><span class="z-variable"> value</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"> public</span><span class="z-storage z-type"> payable</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-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">uint</span><span class="z-variable"> value</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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> standardERC20</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"> 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 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"> 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"> balanceOf</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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Interface of the ERC20 standard.</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"> IERC223WrapperToken</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> <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"> 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 class="z-storage z-type"> function</span><span class="z-entity z-name"> standard</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"> origin</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-storage z-type"> function</span><span class="z-entity z-name"> totalSupply</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"> balanceOf</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"> 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"> 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 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-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-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"> 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"> 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"> 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"> 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"> 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"> mint</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"> uint256</span><span class="z-variable z-parameter z-function"> _quantity</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"> burn</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"> uint256</span><span class="z-variable z-parameter z-function"> _quantity</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"> IERC20WrapperToken</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> <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"> 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 class="z-storage z-type"> function</span><span class="z-entity z-name"> standard</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"> origin</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-storage z-type"> function</span><span class="z-entity z-name"> totalSupply</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"> balanceOf</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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> 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"> mint</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"> uint256</span><span class="z-variable z-parameter z-function"> _quantity</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"> burn</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"> uint256</span><span class="z-variable z-parameter z-function"> _quantity</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">contract</span><span class="z-entity z-name"> ERC20Rescue</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ERC20 tokens can get stuck on a contracts balance due to lack of error handling.</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"> The author of the ERC7417 can extract ERC20 tokens if they are mistakenly sent</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> to the wrapper-contracts balance.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Contact dexaran@ethereumclassic.org</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> extractor </span><span class="z-keyword">=</span><span class="z-constant"> 0x01000B5fE61411C466b70631d7fF070187179Bbf</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"> safeTransfer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token</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"> value</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> bytes4(keccak256(bytes(&#39;transfer(address,uint256)&#39;)));</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bool</span><span> success</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> data</span><span>)</span><span class="z-keyword"> =</span><span> token</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span class="z-constant">0xa9059cbb</span><span>,</span><span> to</span><span>,</span><span> value</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>success </span><span class="z-keyword">&amp;&amp;</span><span> (</span><span>data</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span class="z-keyword"> ||</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>data</span><span>,</span><span> (</span><span class="z-support">bool</span><span>)</span><span>)</span><span>)</span><span>,</span><span class="z-string"> &#39;TransferHelper: TRANSFER_FAILED&#39;</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"> rescueERC20</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _token</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"> external</span><span> </span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> safeTransfer</span><span>(</span><span>_token</span><span>,</span><span> extractor</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> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC223WrapperToken</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC223</span><span>, </span><span class="z-entity z-name">ERC165</span><span>, </span><span class="z-entity z-name">ERC20Rescue</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> creator </span><span class="z-keyword">=</span><span class="z-variable z-language"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> private</span><span> wrapper_for</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> account </span><span class="z-keyword">=&gt;</span><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span> spender </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> allowances</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"> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferData</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"> 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"> amount</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"> set</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _wrapper_for</span><span>)</span><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><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> creator</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> wrapper_for </span><span class="z-keyword">=</span><span> _wrapper_for</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> _totalSupply</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"> private</span><span> balances</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> List of user balances.</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"> 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-storage z-type"> override</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span><span class="z-keyword"> return</span><span> _totalSupply</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-storage z-type"> override</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span><span class="z-keyword"> return</span><span> balances</span><span>[</span><span>_owner</span><span>]</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The ERC165 introspection function.</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"> 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> <span class="giallo-l"><span> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC20</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>standardERC20</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>IERC223WrapperToken</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>IERC223</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Standard ERC223 transfer function.</span></span> <span class="giallo-l"><span class="z-comment"> * Calls _to if it is a contract. Does not transfer tokens to contracts</span></span> <span class="giallo-l"><span class="z-comment"> * which do not explicitly declare the tokenReceived function.</span></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"> - transfer recipient. Can be contract or EOA.</span></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 quantity of tokens 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"> _data</span><span class="z-comment"> - metadata to send alongside the transaction. Can be used to encode subsequent calls in the recipient.</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"> uint</span><span class="z-variable z-parameter z-function"> _value</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"> public</span><span class="z-storage z-type"> payable</span><span class="z-storage z-type"> override</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 class="giallo-l"><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 class="z-keyword"> -</span><span> _value</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 class="z-keyword"> +</span><span> _value</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-language">msg</span><span>.</span><span>value </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 class="z-support">bool</span><span> sent</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> data</span><span>)</span><span class="z-keyword"> =</span><span> _to</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span class="z-variable z-language"> msg</span><span>.</span><span>value</span><span>}</span><span>(</span><span class="z-string">&quot;&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>sent</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>Address</span><span>.</span><span class="z-entity z-name">isContract</span><span>(</span><span>_to</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC223Recipient</span><span>(</span><span>_to</span><span>)</span><span>.</span><span class="z-entity z-name">tokenReceived</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> _value</span><span>,</span><span> _data</span><span>)</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> _value</span><span>,</span><span> _data</span><span>)</span><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> _value</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Old ERC20 compatible event. Added for backwards compatibility reasons.</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 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"> Standard ERC223 transfer function without _data parameter. It is supported for </span></span> <span class="giallo-l"><span class="z-comment"> * backwards compatibility with ERC20 services.</span></span> <span class="giallo-l"><span class="z-comment"> * Calls _to if it is a contract. Does not transfer tokens to contracts</span></span> <span class="giallo-l"><span class="z-comment"> * which do not explicitly declare the tokenReceived function.</span></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"> - transfer recipient. Can be contract or EOA.</span></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 quantity of tokens 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"> 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"> uint</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> override</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 class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> _empty </span><span class="z-keyword">=</span><span> hex</span><span class="z-string">&quot;00000000&quot;</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 class="z-keyword"> -</span><span> _value</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 class="z-keyword"> +</span><span> _value</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>Address</span><span>.</span><span class="z-entity z-name">isContract</span><span>(</span><span>_to</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC223Recipient</span><span>(</span><span>_to</span><span>)</span><span>.</span><span class="z-entity z-name">tokenReceived</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> _value</span><span>,</span><span> _empty</span><span>)</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> _value</span><span>,</span><span> _empty</span><span>)</span><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> _value</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Old ERC20 compatible event. Added for backwards compatibility reasons.</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 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"> public</span><span class="z-storage z-type"> view</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 class="z-keyword"> return</span><span class="z-entity z-name"> IERC20Metadata</span><span>(</span><span>wrapper_for</span><span>)</span><span>.</span><span class="z-entity z-name">name</span><span>(</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"> symbol</span><span>(</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 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 class="z-keyword"> return</span><span class="z-support"> string</span><span>.</span><span class="z-entity z-name">concat</span><span>(</span><span class="z-entity z-name">IERC20Metadata</span><span>(</span><span>wrapper_for</span><span>)</span><span>.</span><span class="z-entity z-name">symbol</span><span>(</span><span>)</span><span>,</span><span class="z-string"> &quot;223&quot;</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"> 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-storage z-type"> override</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint8</span><span>)</span><span> {</span><span class="z-keyword"> return</span><span class="z-entity z-name"> IERC20Metadata</span><span>(</span><span>wrapper_for</span><span>)</span><span>.</span><span class="z-entity z-name">decimals</span><span>(</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"> standard</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">uint32</span><span>)</span><span> {</span><span class="z-keyword"> return</span><span class="z-constant"> 223</span><span>;</span><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> origin</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 class="z-keyword"> return</span><span> wrapper_for</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Minting function which will only be called by the converter 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"> _recipient</span><span class="z-comment"> - the address which will receive 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"> _quantity</span><span class="z-comment"> - the number of tokens to create.</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 class="z-support">address</span><span class="z-variable z-parameter z-function"> _recipient</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _quantity</span><span>)</span><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><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> creator</span><span>,</span><span class="z-string"> &quot;Wrapper Token: Only the creator contract can mint wrapper tokens.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> balances</span><span>[</span><span>_recipient</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> _quantity</span><span>;</span></span> <span class="giallo-l"><span> _totalSupply </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span> _quantity</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"> Burning function which will only be called by the converter 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"> _quantity</span><span class="z-comment"> - the number of tokens to destroy. TokenConverter can only destroy tokens on it&#39;s own address.</span></span> <span class="giallo-l"><span class="z-comment"> * Only the token converter is allowed to burn wrapper-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"> burn</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _quantity</span><span>)</span><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><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> creator</span><span>,</span><span class="z-string"> &quot;Wrapper Token: Only the creator contract can destroy wrapper tokens.&quot;</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 class="z-keyword">=</span><span> _quantity</span><span>;</span></span> <span class="giallo-l"><span> _totalSupply </span><span class="z-keyword">-</span><span class="z-keyword">=</span><span> _quantity</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"> ERC20 functions for backwards compatibility.</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"> 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-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> allowances</span><span>[</span><span>owner</span><span>]</span><span>[</span><span>spender</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-support">address</span><span class="z-variable z-parameter z-function"> _spender</span><span>,</span><span class="z-support"> uint</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-keyword"> require</span><span>(</span><span>_spender </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;ERC223: Spender error.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> allowances</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> _value</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><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> _value</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 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"> uint</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-keyword"> require</span><span>(</span><span>allowances</span><span>[</span><span>_from</span><span>]</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> _value</span><span>,</span><span class="z-string"> &quot;ERC223: Insufficient allowance.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> balances</span><span>[</span><span>_from</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> _value</span><span>;</span></span> <span class="giallo-l"><span> allowances</span><span>[</span><span>_from</span><span>]</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> _value</span><span>;</span></span> <span class="giallo-l"><span> balances</span><span>[</span><span>_to</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> _value</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"> Transfer</span><span>(</span><span>_from</span><span>,</span><span> _to</span><span>,</span><span> _value</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> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC20WrapperToken</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC20</span><span>, </span><span class="z-entity z-name">ERC165</span><span>, </span><span class="z-entity z-name">ERC20Rescue</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> creator </span><span class="z-keyword">=</span><span class="z-variable z-language"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> wrapper_for</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> account </span><span class="z-keyword">=&gt;</span><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span> spender </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> allowances</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"> set</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _wrapper_for</span><span>)</span><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><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> creator</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> wrapper_for </span><span class="z-keyword">=</span><span> _wrapper_for</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> _totalSupply</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"> private</span><span> balances</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> List of user balances.</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"> 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-storage z-type"> override</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span><span class="z-keyword"> return</span><span> balances</span><span>[</span><span>_owner</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"> name</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">string</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span><span class="z-keyword"> return</span><span class="z-entity z-name"> IERC20Metadata</span><span>(</span><span>wrapper_for</span><span>)</span><span>.</span><span class="z-entity z-name">name</span><span>(</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"> symbol</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">string</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span><span class="z-keyword"> return</span><span class="z-support"> string</span><span>.</span><span class="z-entity z-name">concat</span><span>(</span><span class="z-entity z-name">IERC223</span><span>(</span><span>wrapper_for</span><span>)</span><span>.</span><span class="z-entity z-name">symbol</span><span>(</span><span>)</span><span>,</span><span class="z-string"> &quot;20&quot;</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"> 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 class="z-keyword"> return</span><span class="z-entity z-name"> IERC20Metadata</span><span>(</span><span>wrapper_for</span><span>)</span><span>.</span><span class="z-entity z-name">decimals</span><span>(</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"> 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-storage z-type"> override</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span><span class="z-keyword"> return</span><span> _totalSupply</span><span>;</span><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> origin</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 class="z-keyword"> return</span><span> wrapper_for</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"> 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> <span class="giallo-l"><span> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC20</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>IERC20WrapperToken</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"> 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"> uint</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> override</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 class="giallo-l"><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 class="z-keyword"> -</span><span> _value</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 class="z-keyword"> +</span><span> _value</span><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> _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 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 z-parameter z-function"> _recipient</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _quantity</span><span>)</span><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><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> creator</span><span>,</span><span class="z-string"> &quot;Wrapper Token: Only the creator contract can mint wrapper tokens.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> balances</span><span>[</span><span>_recipient</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> _quantity</span><span>;</span></span> <span class="giallo-l"><span> _totalSupply </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span> _quantity</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"> burn</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"> _quantity</span><span>)</span><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><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> creator</span><span>,</span><span class="z-string"> &quot;Wrapper Token: Only the creator contract can destroy wrapper tokens.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> balances</span><span>[</span><span>_from</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> _quantity</span><span>;</span></span> <span class="giallo-l"><span> _totalSupply </span><span class="z-keyword">-</span><span class="z-keyword">=</span><span> _quantity</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"> 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-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> allowances</span><span>[</span><span>owner</span><span>]</span><span>[</span><span>spender</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-support">address</span><span class="z-variable z-parameter z-function"> _spender</span><span>,</span><span class="z-support"> uint</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-comment"> //</span><span class="z-comment"> Safety checks.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_spender </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;ERC20: Spender error.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> allowances</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> _value</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><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> _value</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 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"> uint</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-keyword"> require</span><span>(</span><span>allowances</span><span>[</span><span>_from</span><span>]</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> _value</span><span>,</span><span class="z-string"> &quot;ERC20: Insufficient allowance.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> balances</span><span>[</span><span>_from</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> _value</span><span>;</span></span> <span class="giallo-l"><span> allowances</span><span>[</span><span>_from</span><span>]</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> _value</span><span>;</span></span> <span class="giallo-l"><span> balances</span><span>[</span><span>_to</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> _value</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"> Transfer</span><span>(</span><span>_from</span><span>,</span><span> _to</span><span>,</span><span> _value</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> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> TokenStandardConverter</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC223Recipient</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"> ERC223WrapperCreated</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">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _ERC223Wrapper</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ERC20WrapperCreated</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">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _ERC20Wrapper</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">address</span><span class="z-keyword"> =&gt;</span><span> ERC223WrapperToken</span><span>)</span><span class="z-storage z-type"> public</span><span> erc223Wrappers</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> A list of token wrappers. First one is ERC20 origin, second one is ERC223 version.</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> ERC20WrapperToken</span><span>)</span><span class="z-storage z-type"> public</span><span> erc20Wrappers</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"> address</span><span>)</span><span class="z-storage z-type"> public</span><span> erc223Origins</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> erc20Origins</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> erc20Supply</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Token =&gt; how much was deposited.</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"> getERC20WrapperFor</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-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> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> address</span><span>(</span><span>erc20Wrappers</span><span>[</span><span>_token</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"> getERC223WrapperFor</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-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> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> address</span><span>(</span><span>erc223Wrappers</span><span>[</span><span>_token</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"> getERC20OriginFor</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-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> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-support">address</span><span>(</span><span>erc20Origins</span><span>[</span><span>_token</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"> getERC223OriginFor</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-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> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-support">address</span><span>(</span><span>erc223Origins</span><span>[</span><span>_token</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"> predictWrapperAddress</span><span>(</span><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"> bool</span><span class="z-variable z-parameter z-function"> _isERC20</span><span class="z-comment"> //</span><span class="z-comment"> Is the provided _token a ERC20 or not?</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If it is set as ERC20 then we will predict the address of a </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ERC223 wrapper for that token.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Otherwise we will predict ERC20 wrapper address.</span></span> <span class="giallo-l"><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 class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> _bytecode</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>_isERC20</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> _bytecode </span><span class="z-keyword">=</span><span class="z-variable z-language"> type</span><span>(</span><span>ERC223WrapperToken</span><span>)</span><span>.</span><span>creationCode</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> else</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> _bytecode </span><span class="z-keyword">=</span><span class="z-variable z-language"> type</span><span>(</span><span>ERC20WrapperToken</span><span>)</span><span>.</span><span>creationCode</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> hash </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-support"> bytes1</span><span>(</span><span class="z-constant">0xff</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-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>_token</span><span>)</span><span>)</span><span>,</span><span class="z-support"> keccak256</span><span>(</span><span>_bytecode</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"> return</span><span class="z-support"> address</span><span>(</span><span class="z-support">uint160</span><span>(</span><span class="z-support">uint</span><span>(</span><span>hash</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"> tokenReceived</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"> uint</span><span class="z-variable z-parameter z-function"> _value</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-comment"> /*</span><span class="z-comment"> _data </span><span class="z-comment">*/</span><span>)</span><span class="z-storage z-type"> public</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 class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>erc223Origins</span><span>[</span><span class="z-variable z-language">msg.sender</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;Error: creating wrapper for a wrapper token.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> There are two possible cases:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 1. A user deposited ERC223 origin token to convert it to ERC20 wrapper</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 2. A user deposited ERC223 wrapper token to unwrap it to ERC20 origin.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>erc20Origins</span><span>[</span><span class="z-variable z-language">msg.sender</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 class="z-comment"> //</span><span class="z-comment"> Origin for deposited token exists.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Unwrap ERC-223 wrapper.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> erc20Supply</span><span>[</span><span>erc20Origins</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> _value</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> safeTransfer</span><span>(</span><span>erc20Origins</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>,</span><span> _from</span><span>,</span><span> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> ERC223WrapperToken</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span>.</span><span class="z-entity z-name">burn</span><span>(</span><span>_value</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> this</span><span>.</span><span>tokenReceived</span><span>.</span><span>selector</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Otherwise origin for the sender token doesn&#39;t exist</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> There are two possible cases:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 1. ERC20 wrapper for the deposited token exists</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 2. ERC20 wrapper for the deposited token doesn&#39;t exist and must be created.</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span class="z-keyword"> if</span><span>(</span><span class="z-support">address</span><span>(</span><span>erc20Wrappers</span><span>[</span><span class="z-variable z-language">msg.sender</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 class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Create ERC-20 wrapper if it doesn&#39;t exist.</span></span> <span class="giallo-l"><span class="z-entity z-name"> createERC20Wrapper</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-comment"> //</span><span class="z-comment"> Mint ERC-20 wrapper tokens for the deposited ERC-223 token</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> if the ERC-20 wrapper didn&#39;t exist then it was just created in the above statement.</span></span> <span class="giallo-l"><span> erc20Wrappers</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span><span>_from</span><span>,</span><span> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> this</span><span>.</span><span>tokenReceived</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"> createERC223Wrapper</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">address</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-support">address</span><span>(</span><span>erc223Wrappers</span><span>[</span><span>_token</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 class="z-string"> &quot;ERROR: Wrapper exists&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 class="z-entity z-name">isWrapper</span><span>(</span><span>_token</span><span>)</span><span>,</span><span class="z-string"> &quot;Error: Creating wrapper for a wrapper token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> ERC223WrapperToken _newERC223Wrapper </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span> ERC223WrapperToken</span><span>{</span><span>salt</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>_token</span><span>)</span><span>)</span><span>}</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _newERC223Wrapper</span><span>.</span><span class="z-entity z-name">set</span><span>(</span><span>_token</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> erc223Wrappers</span><span>[</span><span>_token</span><span>]</span><span class="z-keyword"> =</span><span> _newERC223Wrapper</span><span>;</span></span> <span class="giallo-l"><span> erc20Origins</span><span>[</span><span class="z-support">address</span><span>(</span><span>_newERC223Wrapper</span><span>)</span><span>]</span><span class="z-keyword"> =</span><span> _token</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"> ERC223WrapperCreated</span><span>(</span><span>_token</span><span>,</span><span class="z-support"> address</span><span>(</span><span>_newERC223Wrapper</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>_newERC223Wrapper</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"> createERC20Wrapper</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">address</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-support">address</span><span>(</span><span>erc20Wrappers</span><span>[</span><span>_token</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 class="z-string"> &quot;ERROR: Wrapper already exists.&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 class="z-entity z-name">isWrapper</span><span>(</span><span>_token</span><span>)</span><span>,</span><span class="z-string"> &quot;Error: Creating wrapper for a wrapper token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> ERC20WrapperToken _newERC20Wrapper </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span> ERC20WrapperToken</span><span>{</span><span>salt</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>_token</span><span>)</span><span>)</span><span>}</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _newERC20Wrapper</span><span>.</span><span class="z-entity z-name">set</span><span>(</span><span>_token</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> erc20Wrappers</span><span>[</span><span>_token</span><span>]</span><span class="z-keyword"> =</span><span> _newERC20Wrapper</span><span>;</span></span> <span class="giallo-l"><span> erc223Origins</span><span>[</span><span class="z-support">address</span><span>(</span><span>_newERC20Wrapper</span><span>)</span><span>]</span><span class="z-keyword"> =</span><span> _token</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"> ERC20WrapperCreated</span><span>(</span><span>_token</span><span>,</span><span class="z-support"> address</span><span>(</span><span>_newERC20Wrapper</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>_newERC20Wrapper</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"> wrapERC20toERC223</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _ERC20token</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> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If there is no active wrapper for a token that user wants to wrap</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> then create it.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-support">address</span><span>(</span><span>erc223Wrappers</span><span>[</span><span>_ERC20token</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 class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> createERC223Wrapper</span><span>(</span><span>_ERC20token</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> _converterBalance </span><span class="z-keyword">=</span><span class="z-entity z-name"> IERC20</span><span>(</span><span>_ERC20token</span><span>)</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 class="z-comment"> //</span><span class="z-comment"> Safety variable.</span></span> <span class="giallo-l"><span class="z-entity z-name"> safeTransferFrom</span><span>(</span><span>_ERC20token</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> _amount</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _amount </span><span class="z-keyword">=</span><span class="z-entity z-name"> IERC20</span><span>(</span><span>_ERC20token</span><span>)</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 class="z-keyword"> -</span><span> _converterBalance</span><span>;</span></span> <span class="giallo-l"><span> erc20Supply</span><span>[</span><span>_ERC20token</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> _amount</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> erc223Wrappers</span><span>[</span><span>_ERC20token</span><span>]</span><span>.</span><span class="z-entity z-name">mint</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 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"> unwrapERC20toERC223</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _ERC20token</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> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">IERC20</span><span>(</span><span>_ERC20token</span><span>)</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-keyword">=</span><span> _amount</span><span>,</span><span class="z-string"> &quot;Error: Insufficient balance.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>erc223Origins</span><span>[</span><span>_ERC20token</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;Error: provided token is not a ERC-20 wrapper.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> ERC20WrapperToken</span><span>(</span><span>_ERC20token</span><span>)</span><span>.</span><span class="z-entity z-name">burn</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 class="giallo-l"><span class="z-entity z-name"> safeTransfer</span><span>(</span><span>erc223Origins</span><span>[</span><span>_ERC20token</span><span>]</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 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"> convertERC20</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _token</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> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-entity z-name">isWrapper</span><span>(</span><span>_token</span><span>)</span><span>)</span><span class="z-keyword"> return</span><span class="z-entity z-name"> unwrapERC20toERC223</span><span>(</span><span>_token</span><span>,</span><span> _amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span class="z-keyword"> return</span><span class="z-entity z-name"> wrapERC20toERC223</span><span>(</span><span>_token</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-storage z-type"> function</span><span class="z-entity z-name"> isWrapper</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-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 class="z-keyword"> return</span><span> erc20Origins</span><span>[</span><span>_token</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> erc223Origins</span><span>[</span><span>_token</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-storage z-type"> function</span><span class="z-entity z-name"> extractStuckERC20</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"> external</span><span> </span></span> <span class="giallo-l"><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">0x01000B5fE61411C466b70631d7fF070187179Bbf</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> safeTransfer</span><span>(</span><span>_token</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0x01000B5fE61411C466b70631d7fF070187179Bbf</span><span>)</span><span>,</span><span class="z-entity z-name"> IERC20</span><span>(</span><span>_token</span><span>)</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 class="z-keyword"> -</span><span> erc20Supply</span><span>[</span><span>_token</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-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"> token</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"> value</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> bytes4(keccak256(bytes(&#39;transfer(address,uint256)&#39;)));</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bool</span><span> success</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> data</span><span>)</span><span class="z-keyword"> =</span><span> token</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span class="z-constant">0xa9059cbb</span><span>,</span><span> to</span><span>,</span><span> value</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>success </span><span class="z-keyword">&amp;&amp;</span><span> (</span><span>data</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span class="z-keyword"> ||</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>data</span><span>,</span><span> (</span><span class="z-support">bool</span><span>)</span><span>)</span><span>)</span><span>,</span><span class="z-string"> &#39;TransferHelper: TRANSFER_FAILED&#39;</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"> safeTransferFrom</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token</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"> uint</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> bytes4(keccak256(bytes(&#39;transferFrom(address,address,uint256)&#39;)));</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bool</span><span> success</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> data</span><span>)</span><span class="z-keyword"> =</span><span> token</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span class="z-constant">0x23b872dd</span><span>,</span><span> from</span><span>,</span><span> to</span><span>,</span><span> value</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>success </span><span class="z-keyword">&amp;&amp;</span><span> (</span><span>data</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span class="z-keyword"> ||</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>data</span><span>,</span><span> (</span><span class="z-support">bool</span><span>)</span><span>)</span><span>)</span><span>,</span><span class="z-string"> &#39;TransferHelper: TRANSFER_FROM_FAILED&#39;</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> <ol> <li>While it is possible to implement a service that converts any token standard to any other standard - it is better to keep different standard convertors separate from one another as different standards may contain specific logic and therefore require different conversion approach. This proposal focuses on <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> upgradeability.</li> <li><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens can be deposited to any contract directly with <code>transfer</code> function. This may result in a permanent loss of tokens because it is not possible to recognize this transaction on the recipients side. Therefore wrapper-ERC-20 tokens are prone to this problem as they are compatible with the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard. <code>rescueERC20</code> function is implemented to address this problem.</li> <li>Token Converter relies on <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> <code>approve</code> &amp; <code>transferFrom</code> method of depositing assets. Any related issues must be taken into account. <code>approve</code> and <code>transferFrom</code> are two separate transactions so it is required to make sure <code>approval</code> was successful before relying on <code>transferFrom</code>.</li> <li>This is a common practice for UI services to prompt a user to issue unlimited <code>approval</code> on any contract that may withdraw tokens from the user. This puts users funds at risk and therefore is not recommended.</li> <li>There is no reliable token standard introspection method available that could guarantee that a token implements a particular token standard. It is possible to artificially construct a token that will pretend it is a <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token that implements <code>approve &amp; transferFrom</code> but at the same time implements <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> logic of transferring via <code>transfer</code> function. It can be possible to create a <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper for this <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>-<a href="https://wg-eips.ritovision.com/223/">ERC-223</a> hybrid implementation in the Token Converter. This doesn't pose any threat for the workflow of the Token Converter itself but it must be taken into account that if a token has <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper in the Token Converter it does not automatically mean the origin is fully compatible with the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard and methods of introspection must be used to determine the origins compatibility with any existing standard.</li> <li>Token Converter does not verify the standard of a provided token when it is asked to create a wrapper for it due to the lack of reliable standard introspection method. It is possible to call <code>createERC20Wrapper</code> function and provide an address of an existing <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token. The Token Converter will successfully create a <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> wrapper for that <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> original token. It is also possible to create a <a href="https://wg-eips.ritovision.com/223/">ERC-223</a> wrapper for that exact original <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token. This doesn't pose any threat to the workflow of the Converter but it must be taken into account that any token regardless of it's original standard may have up to two wrappers created by the Converter, one for each standard. Any wrapper token must have exactly one origin. It is not possible to create a wrapper for a wrapper.</li> <li>The Token Converter only holds the original tokens that were deposited during the conversion process and it assumes that tokens do not decay over time and the token balance of the Converter does not decrease on its own. If some token implements burning logic or decaying supply and it may impact the balance of the Converter then the Converter must not be used to deploy an alternative version of that token as it will not be able to guarantee that there is enough tokens for the conversion at any time.</li> </ol> <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-26T00:00:00+00:00 2026-02-11T14:48:25+00:00 Bruno Škvorchttps://github.com/Swader Cicadahttps://github.com/CicadaNCR Steven Pinedahttps://github.com/steven2308 Stevan Bogosavljevichttps://github.com/stevyhacker Jan Turkhttps://github.com/ThunderDeliverer https://wg-eips.ritovision.com/7401/

An interface for Non-Fungible Tokens Nesting with emphasis on parent token's control over the relationship.

<h2 id="abstract">Abstract</h2> <p>❗️ <strong><a href="https://wg-eips.ritovision.com/7401/">ERC-7401</a> supersedes <a href="https://wg-eips.ritovision.com/6059/">ERC-6059</a>.</strong> ❗️</p> <p>The Parent-Governed NFT Nesting standard extends <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> by allowing for a new inter-NFT relationship and interaction.</p> <p>At its core, the idea behind the proposal is simple: the owner of an NFT does not have to be an Externally Owned Account (EOA) or a smart contract, it can also be an NFT.</p> <p>The process of nesting an NFT into another is functionally identical to sending it to another user. The process of sending a token out of another one involves issuing a transaction from the account owning the parent token.</p> <p>An NFT can be owned by a single other NFT, but can in turn have a number of NFTs that it owns. This proposal establishes the framework for the parent-child relationships of NFTs. A parent token is the one that owns another token. A child token is a token that is owned by another token. A token can be both a parent and child at the same time. Child tokens of a given token can be fully managed by the parent token's owner, but can be proposed by anyone.</p> <p><img src="https://wg-eips.ritovision.com/7401/./assets/img/eip-7401-nestable-tokens.png" alt="Nestable tokens" /></p> <p>The graph illustrates how a child token can also be a parent token, but both are still administered by the root parent token's owner.</p> <h2 id="motivation">Motivation</h2> <p>With NFTs being a widespread form of tokens in the Ethereum ecosystem and being used for a variety of use cases, it is time to standardize additional utility for them. Having the ability for tokens to own other tokens allows for greater utility, usability and forward compatibility.</p> <p>In the four years since <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> was published, the need for additional functionality has resulted in countless extensions. This ERC improves upon ERC-721 in the following areas:</p> <ul> <li><a href="https://wg-eips.ritovision.com/7401/#bundling">Bundling</a></li> <li><a href="https://wg-eips.ritovision.com/7401/#collecting">Collecting</a></li> <li><a href="https://wg-eips.ritovision.com/7401/#membership">Membership</a></li> <li><a href="https://wg-eips.ritovision.com/7401/#delegation">Delegation</a></li> </ul> <p>This proposal fixes the inconsistency in the <a href="https://wg-eips.ritovision.com/6059/">ERC-6059</a> interface specification, where interface ID doesn't match the interface specified as the interface evolved during the proposal's lifecycle, but one of the parameters was not added to it. The missing parameter is, however, present in the interface ID. Apart from this fix, this proposal is functionally equivalent to <a href="https://wg-eips.ritovision.com/6059/">ERC-6059</a>.</p> <h3 id="bundling">Bundling</h3> <p>One of the most frequent uses of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> is to disseminate the multimedia content that is tied to the tokens. In the event that someone wants to offer a bundle of NFTs from various collections, there is currently no easy way of bundling all of these together and handle their sale as a single transaction. This proposal introduces a standardized way of doing so. Nesting all of the tokens into a simple bundle and selling that bundle would transfer the control of all of the tokens to the buyer in a single transaction.</p> <h3 id="collecting">Collecting</h3> <p>A lot of NFT consumers collect them based on countless criteria. Some aim for utility of the tokens, some for the uniqueness, some for the visual appeal, etc. There is no standardized way to group the NFTs tied to a specific account. By nesting NFTs based on their owner's preference, this proposal introduces the ability to do it. The root parent token could represent a certain group of tokens and all of the children nested into it would belong to it.</p> <p>The rise of soulbound, non-transferable, tokens, introduces another need for this proposal. Having a token with multiple soulbound traits (child tokens), allows for numerous use cases. One concrete example of this can be drawn from supply chains use case. A shipping container, represented by an NFT with its own traits, could have multiple child tokens denoting each leg of its journey.</p> <h3 id="membership">Membership</h3> <p>A common utility attached to NFTs is a membership to a Decentralised Autonomous Organization (DAO) or to some other closed-access group. Some of these organizations and groups occasionally mint NFTs to the current holders of the membership NFTs. With the ability to nest mint a token into a token, such minting could be simplified, by simply minting the bonus NFT directly into the membership one.</p> <h3 id="delegation">Delegation</h3> <p>One of the core features of DAOs is voting and there are various approaches to it. One such mechanic is using fungible voting tokens where members can delegate their votes by sending these tokens to another member. Using this proposal, delegated voting could be handled by nesting your voting NFT into the one you are delegating your votes to and transferring it when the member no longer wishes to delegate their votes.</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-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> EIP-7401 Parent-Governed Nestable Non-Fungible Tokens</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-7401</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 ERC-165 identifier for this interface is 0x42b0e56f.</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.16</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"> IERC7059</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">@notice</span><span class="z-comment"> The core struct of ownership.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The `DirectOwner` struct is used to store information of the next immediate owner, be it the parent token,</span></span> <span class="giallo-l"><span class="z-comment"> * an `ERC721Receiver` contract or an externally owned account.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If the token is not owned by an NFT, the `tokenId` MUST equal `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"> ID of the parent 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"> ownerAddress</span><span class="z-comment"> Address of the owner of the token. If the owner is another token, then the address MUST be</span></span> <span class="giallo-l"><span class="z-comment"> * the one of the parent token&#39;s collection smart contract. If the owner is externally owned account, the address</span></span> <span class="giallo-l"><span class="z-comment"> * MUST be the address of this account</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"> DirectOwner</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 class="z-support"> address</span><span> ownerAddress</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"> The core child token struct, holding the information about the child 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"> tokenId</span><span class="z-comment"> ID of the child token in the child token&#39;s collection smart 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"> contractAddress</span><span class="z-comment"> Address of the child token&#39;s smart 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"> Child</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 class="z-support"> address</span><span> contractAddress</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"> Used to notify listeners that the token is being transferred.</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 transferred from `from` 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"> Address of the previous immediate owner, which is a smart contract if the token was nested.</span></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 of the new immediate owner, which is a smart contract if the token is being nested.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> fromTokenId</span><span class="z-comment"> ID of the previous parent token. If the token was not nested before, the value 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"> toTokenId</span><span class="z-comment"> ID of the new parent token. If the token is not being nested, the value 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"> tokenId</span><span class="z-comment"> ID of the token being transferred</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"> NestTransfer</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"> fromTokenId</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"> 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"> Used to notify listeners that a new token has been added to a given token&#39;s pending children array.</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 child NFT is added to a token&#39;s pending 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"> tokenId</span><span class="z-comment"> ID of the token that received a new pending child 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"> childIndex</span><span class="z-comment"> Index of the proposed child token in the parent token&#39;s pending children 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"> childAddress</span><span class="z-comment"> Address of the proposed child token&#39;s collection smart 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"> childId</span><span class="z-comment"> ID of the child token in the child token&#39;s collection smart 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"> ChildProposed</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"> childIndex</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"> childAddress</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"> childId</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"> Used to notify listeners that a new child token was accepted by the parent token.</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 parent token accepts a token from its pending array, migrating it to the active 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"> tokenId</span><span class="z-comment"> ID of the token that accepted a new child 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"> childIndex</span><span class="z-comment"> Index of the newly accepted child token in the parent token&#39;s active children 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"> childAddress</span><span class="z-comment"> Address of the child token&#39;s collection smart 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"> childId</span><span class="z-comment"> ID of the child token in the child token&#39;s collection smart 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"> ChildAccepted</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"> childIndex</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"> childAddress</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"> childId</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"> Used to notify listeners that all pending child tokens of a given token have been rejected.</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 removes all child tokens from its pending 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"> tokenId</span><span class="z-comment"> ID of the token that rejected all of the pending children</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"> AllChildrenRejected</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">@notice</span><span class="z-comment"> Used to notify listeners a child token has been transferred from parent token.</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 transfers a child from itself, transferring ownership.</span></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 token that transferred a child 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"> childIndex</span><span class="z-comment"> Index of a child in the array from which it is being transferred</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> childAddress</span><span class="z-comment"> Address of the child token&#39;s collection smart 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"> childId</span><span class="z-comment"> ID of the child token in the child token&#39;s collection smart 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"> fromPending</span><span class="z-comment"> A boolean value signifying whether the token was in the pending child tokens array (`true`) or</span></span> <span class="giallo-l"><span class="z-comment"> * in the active child tokens array (`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"> toZero</span><span class="z-comment"> A boolean value signifying whether the token is being transferred to the `0x0` address (`true`) or</span></span> <span class="giallo-l"><span class="z-comment"> * not (`false`)</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"> ChildTransferred</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"> childIndex</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"> childAddress</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"> childId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> fromPending</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> toZero</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"> Used to retrieve the *root* owner of a given token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The *root* owner of the token is the top-level owner in the hierarchy which is not 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"> If the token is owned by another NFT, it MUST recursively look up the parent&#39;s root 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"> ID of the token for which the *root* owner has been retrieved</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"> owner</span><span class="z-comment"> The *root* owner of 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"> 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 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"> Used to retrieve the immediate owner of the given token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If the immediate owner is another token, the address returned, MUST be the one of the parent token&#39;s</span></span> <span class="giallo-l"><span class="z-comment"> * collection smart 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"> tokenId</span><span class="z-comment"> ID of the token for which the direct owner is being retrieved</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"> Address of the given token&#39;s 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"> uint256</span><span class="z-comment"> The ID of the parent token. MUST be `0` if the owner is not 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"> bool</span><span class="z-comment"> The boolean value signifying whether the owner is an NFT or 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"> directOwnerOf</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> <span class="giallo-l"><span class="z-support"> address</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</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"> Used to burn a given token.</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 token is burned, all of its child tokens are recursively burned as well.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> When specifying the maximum recursive burns, the execution MUST be reverted if there are more children to be</span></span> <span class="giallo-l"><span class="z-comment"> * burned.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Setting the `maxRecursiveBurn` value to 0 SHOULD only attempt to burn the specified token and MUST revert if</span></span> <span class="giallo-l"><span class="z-comment"> * there are any child tokens 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"> tokenId</span><span class="z-comment"> ID of the token to burn</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> maxRecursiveBurns</span><span class="z-comment"> Maximum number of tokens to recursively burn</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"> Number of recursively burned children</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 class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> maxRecursiveBurns</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">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"> Used to add a child token to a given parent token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This adds the child token into the given parent token&#39;s pending child tokens array.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The destination token MUST NOT be a child token of the token being transferred or one of its downstream</span></span> <span class="giallo-l"><span class="z-comment"> * child tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This method MUST NOT be called directly. It MUST only be called from an instance of `IERC7059` as part of a </span></span> <span class="giallo-l"><span class="z-comment"> `nestTransfer` or `transferChild` to 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"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - `directOwnerOf` on the child contract MUST resolve to the called contract.</span></span> <span class="giallo-l"><span class="z-comment"> * - the pending array of the parent contract MUST not be full.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> parentId</span><span class="z-comment"> ID of the parent token to receive the new child 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"> childId</span><span class="z-comment"> ID of the new proposed child 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"> addChild</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parentId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> childId</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"> Used to accept a pending child token for a given parent token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This moves the child token from parent token&#39;s pending child tokens array into the active child tokens</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> parentId</span><span class="z-comment"> ID of the parent token for which the child token is being accepted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> childIndex</span><span class="z-comment"> Index of the child token to accept in the pending children array of a given 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"> childAddress</span><span class="z-comment"> Address of the collection smart contract of the child token expected to be at the specified</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> childId</span><span class="z-comment"> ID of the child token expected to be located at the specified index</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"> acceptChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> parentId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> childIndex</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> childAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> childId</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"> Used to reject all pending children of a given parent token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Removes the children from the pending array mapping.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The children&#39;s ownership structures are not updated.</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"> * - `parentId` MUST 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"> parentId</span><span class="z-comment"> ID of the parent token for which to reject all of the pending 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"> maxRejections</span><span class="z-comment"> Maximum number of expected children to reject, used to prevent from</span></span> <span class="giallo-l"><span class="z-comment"> * rejecting children which arrive just before this operation.</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"> rejectAllChildren</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parentId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> maxRejections</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"> Used to transfer a child token from a given parent token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST remove the child from the parent&#39;s active or pending children.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> When transferring a child token, the owner of the token MUST be set to `to`, or not updated in the event of `to`</span></span> <span class="giallo-l"><span class="z-comment"> * being the `0x0` 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"> ID of the parent token from which the child token is being transferred</span></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 to which to transfer the token 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"> destinationId</span><span class="z-comment"> ID of the token to receive this child token (MUST be 0 if the destination is not 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"> childIndex</span><span class="z-comment"> Index of a token we are transferring, in the array it belongs to (can be either active array or</span></span> <span class="giallo-l"><span class="z-comment"> * pending 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"> childAddress</span><span class="z-comment"> Address of the child token&#39;s collection smart 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"> childId</span><span class="z-comment"> ID of the child token in its own collection smart 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"> isPending</span><span class="z-comment"> A boolean value indicating whether the child token being transferred is in the pending array of the</span></span> <span class="giallo-l"><span class="z-comment"> * parent token (`true`) or in the active array (`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"> data</span><span class="z-comment"> Additional data with no specified format, sent in call to `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"> transferChild</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-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> destinationId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> childIndex</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> childAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> childId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> isPending</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 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"> Used to retrieve the active child tokens of a given parent token.</span></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 Child structs existing for parent token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The Child struct consists of the following values:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * tokenId,</span></span> <span class="giallo-l"><span class="z-comment"> * contractAddress</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"> parentId</span><span class="z-comment"> ID of the parent token for which to retrieve the active child 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"> struct</span><span class="z-comment">[] An array of Child structs containing the parent token&#39;s active child 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"> childrenOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parentId</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">Child</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to retrieve the pending child tokens of a given parent token.</span></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 pending Child structs existing for given parent.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The Child struct consists of the following values:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * tokenId,</span></span> <span class="giallo-l"><span class="z-comment"> * contractAddress</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"> parentId</span><span class="z-comment"> ID of the parent token for which to retrieve the pending child 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"> struct</span><span class="z-comment">[] An array of Child structs containing the parent token&#39;s pending child 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"> pendingChildrenOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parentId</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">Child</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to retrieve a specific active child token for a given parent token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns a single Child struct locating at `index` of parent token&#39;s active child tokens array.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The Child struct consists of the following values:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * tokenId,</span></span> <span class="giallo-l"><span class="z-comment"> * contractAddress</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"> parentId</span><span class="z-comment"> ID of the parent token for which the child is being retrieved</span></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 child token in the parent token&#39;s active child tokens 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"> struct</span><span class="z-comment"> A Child struct containing data about the specified child</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"> childOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parentId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> index</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">Child</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to retrieve a specific pending child token from a given parent token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns a single Child struct locating at `index` of parent token&#39;s active child tokens array.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The Child struct consists of the following values:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * tokenId,</span></span> <span class="giallo-l"><span class="z-comment"> * contractAddress</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"> parentId</span><span class="z-comment"> ID of the parent token for which the pending child token is being retrieved</span></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 child token in the parent token&#39;s pending child tokens 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"> struct</span><span class="z-comment"> A Child struct containing data about the specified child</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"> pendingChildOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parentId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> index</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">Child</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to transfer the token into another token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The destination token MUST NOT be a child token of the token being transferred or one of its downstream</span></span> <span class="giallo-l"><span class="z-comment"> * child 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"> from</span><span class="z-comment"> Address of the direct owner of the token to be transferred</span></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 of the receiving token&#39;s collection smart 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"> tokenId</span><span class="z-comment"> ID of the token being transferred</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> destinationId</span><span class="z-comment"> ID of the token to receive the token being transferred</span></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-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> nestTransferFrom</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></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> destinationId</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 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> <p>ID MUST never be a <code>0</code> value, as this proposal uses <code>0</code> values do signify that the token/destination is not an NFT.</p> <h2 id="rationale">Rationale</h2> <p>Designing the proposal, we considered the following questions:</p> <ol> <li><strong>How to name the proposal?</strong><br /> In an effort to provide as much information about the proposal we identified the most important aspect of the proposal; the parent centered control over nesting. The child token's role is only to be able to be <code>Nestable</code> and support a token owning it. This is how we landed on the <code>Parent-Centered</code> part of the title.</li> <li><strong>Why is automatically accepting a child using <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> permit-style signatures not a part of this proposal?</strong><br /> For consistency. This proposal extends ERC-721 which already uses 1 transaction for approving operations with tokens. It would be inconsistent to have this and also support signing messages for operations with assets.</li> <li><strong>Why use indexes?</strong><br /> To reduce the gas consumption. If the token ID was used to find which token to accept or reject, iteration over arrays would be required and the cost of the operation would depend on the size of the active or pending children arrays. With the index, the cost is fixed. Lists of active and pending children per token need to be maintained, since methods to get them are part of the proposed interface.<br /> To avoid race conditions in which the index of a token changes, the expected token ID as well as the expected token's collection smart contract is included in operations requiring token index, to verify that the token being accessed using the index is the expected one.<br /> Implementation that would internally keep track of indices using mapping was attempted. The minimum cost of accepting a child token was increased by over 20% and the cost of minting has increased by over 15%. We concluded that it is not necessary for this proposal and can be implemented as an extension for use cases willing to accept the increased transaction cost this incurs. In the sample implementation provided, there are several hooks which make this possible.</li> <li><strong>Why is the pending children array limited instead of supporting pagination?</strong><br /> The pending child tokens array is not meant to be a buffer to collect the tokens that the root owner of the parent token wants to keep, but not enough to promote them to active children. It is meant to be an easily traversable list of child token candidates and should be regularly maintained; by either accepting or rejecting proposed child tokens. There is also no need for the pending child tokens array to be unbounded, because active child tokens array is.<br /> Another benefit of having bounded child tokens array is to guard against spam and griefing. As minting malicious or spam tokens could be relatively easy and low-cost, the bounded pending array assures that all of the tokens in it are easy to identify and that legitimate tokens are not lost in a flood of spam tokens, if one occurs.<br /> A consideration tied to this issue was also how to make sure, that a legitimate token is not accidentally rejected when clearing the pending child tokens array. We added the maximum pending children to reject argument to the clear pending child tokens array call. This assures that only the intended number of pending child tokens is rejected and if a new token is added to the pending child tokens array during the course of preparing such call and executing it, the clearing of this array SHOULD result in a reverted transaction.</li> <li><strong>Should we allow tokens to be nested into one of its children?</strong><br /> The proposal enforces that a parent token can't be nested into one of its child token, or downstream child tokens for that matter. A parent token and its children are all managed by the parent token's root owner. This means that if a token would be nested into one of its children, this would create the ownership loop and none of the tokens within the loop could be managed anymore.</li> <li><strong>Why is there not a "safe" nest transfer method?</strong><br /> <code>nestTransfer</code> is always "safe" since it MUST check for <code>IERC7059</code> compatibility on the destination.</li> <li><strong>How does this proposal differ from the other proposals trying to address a similar problem?</strong><br /> This interface allows for tokens to both be sent to and receive other tokens. The propose-accept and parent governed patterns allow for a more secure use. The backward compatibility is only added for ERC-721, allowing for a simpler interface. The proposal also allows for different collections to inter-operate, meaning that nesting is not locked to a single smart contract, but can be executed between completely separate NFT collections.<br /> Additionally this proposal addresses the inconsistencies between <code>interfaceId</code>, interface specification and example implementation of <a href="https://wg-eips.ritovision.com/6059/">ERC-6059</a>.</li> </ol> <h3 id="propose-commit-pattern-for-child-token-management">Propose-Commit pattern for child token management</h3> <p>Adding child tokens to a parent token MUST be done in the form of propose-commit pattern to allow for limited mutability by a 3rd party. When adding a child token to a parent token, it is first placed in a <em>"Pending"</em> array, and MUST be migrated to the <em>"Active"</em> array by the parent token's root owner. The <em>"Pending"</em> child tokens array SHOULD be limited to 128 slots to prevent spam and griefing.</p> <p>The limitation that only the root owner can accept the child tokens also introduces a trust inherent to the proposal. This ensures that the root owner of the token has full control over the token. No one can force the user to accept a child if they don't want to.</p> <h3 id="parent-governed-pattern">Parent Governed pattern</h3> <p>The parent NFT of a nested token and the parent's root owner are in all aspects the true owners of it. Once you send a token to another one you give up ownership.</p> <p>We continue to use ERC-721's <code>ownerOf</code> functionality which will now recursively look up through parents until it finds an address which is not an NFT, this is referred to as the <em>root owner</em>. Additionally we provide the <code>directOwnerOf</code> which returns the most immediate owner of a token using 3 values: the owner address, the tokenId which MUST be 0 if the direct owner is not an NFT, and a flag indicating whether or not the parent is an NFT.</p> <p>The root owner or an approved party MUST be able to do the following operations on children: <code>acceptChild</code>, <code>rejectAllChildren</code> and <code>transferChild</code>.</p> <p>The root owner or an approved party MUST also be allowed to do these operations only when token is not owned by an NFT: <code>transferFrom</code>, <code>safeTransferFrom</code>, <code>nestTransferFrom</code>, <code>burn</code>.</p> <p>If the token is owned by an NFT, only the parent NFT itself MUST be allowed to execute the operations listed above. Transfers MUST be done from the parent token, using <code>transferChild</code>, this method in turn SHOULD call <code>nestTransferFrom</code> or <code>safeTransferFrom</code> in the child token's smart contract, according to whether the destination is an NFT or not. For burning, tokens must first be transferred to an EOA and then burned.</p> <p>We add this restriction to prevent inconsistencies on parent contracts, since only the <code>transferChild</code> method takes care of removing the child from the parent when it is being transferred out of it.</p> <h3 id="child-token-management">Child token management</h3> <p>This proposal introduces a number of child token management functions. In addition to the permissioned migration from <em>"Pending"</em> to <em>"Active"</em> child tokens array, the main token management function from this proposal is the <code>transferChild</code> function. The following state transitions of a child token are available with it:</p> <ol> <li>Reject child token</li> <li>Abandon child token</li> <li>Unnest child token</li> <li>Transfer the child token to an EOA or an <code>ERC721Receiver</code></li> <li>Transfer the child token into a new parent token</li> </ol> <p>To better understand how these state transitions are achieved, we have to look at the available parameters passed to <code>transferChild</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"> transferChild</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-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> destinationId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> childIndex</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> childAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> childId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> isPending</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 class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Based on the desired state transitions, the values of these parameters have to be set accordingly (any parameters not set in the following examples depend on the child token being managed):</p> <ol> <li><strong>Reject child token</strong><br /> <img src="https://wg-eips.ritovision.com/7401/./assets/img/eip-7401-reject-child.png" alt="Reject child token" /></li> <li><strong>Abandon child token</strong><br /> <img src="https://wg-eips.ritovision.com/7401/./assets/img/eip-7401-abandon-child.png" alt="Abandon child token" /></li> <li><strong>Unnest child token</strong><br /> <img src="https://wg-eips.ritovision.com/7401/./assets/img/eip-7401-unnest-child.png" alt="Unnest child token" /></li> <li><strong>Transfer the child token to an EOA or an <code>ERC721Receiver</code></strong><br /> <img src="https://wg-eips.ritovision.com/7401/./assets/img/eip-7401-transfer-child-to-eoa.png" alt="Transfer child token to EOA" /></li> <li><strong>Transfer the child token into a new parent token</strong><br /> <img src="https://wg-eips.ritovision.com/7401/./assets/img/eip-7401-transfer-child-to-token.png" alt="Transfer child token to parent token" /><br /> This state change places the token in the pending array of the new parent token. The child token still needs to be accepted by the new parent token's root owner in order to be placed into the active array of that token.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The Nestable token standard has been made compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> in order to take advantage of the robust tooling available for implementations of ERC-721 and to ensure compatibility with existing ERC-721 infrastructure.</p> <p>The only incompatibility with ERC-721 is that Nestable tokens cannot use a token ID of 0.</p> <p>There is some differentiation of how the <code>ownerOf</code> method behaves compared to ERC-721. The <code>ownerOf</code> method will now recursively look up through parent tokens until it finds an address that is not an NFT; this is referred to as the <em>root owner</em>. Additionally, we provide the <code>directOwnerOf</code>, which returns the most immediate owner of a token using 3 values: the owner address, the <code>tokenId</code>, which MUST be 0 if the direct owner is not an NFT, and a flag indicating whether or not the parent is an NFT. In case the token is owned by an EoA or an ERC-721 Receiver, the <code>ownerOf</code> method will behave the same as in ERC-721.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests are included in <a href="https://wg-eips.ritovision.com/7401/./assets/test/nestable.ts"><code>nestable.ts</code></a>.</p> <p>To run them in terminal, you can use the following commands:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cd ../assets/eip-7401</span></span> <span class="giallo-l"><span>npm install</span></span> <span class="giallo-l"><span>npx hardhat test</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/7401/./assets/contracts/NestableToken.sol"><code>NestableToken.sol</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The same security considerations as with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> apply: hidden logic may be present in any of the functions, including burn, add child, accept child, and more.</p> <p>Since the current owner of the token is allowed to manage the token, there is a possibility that after the parent token is listed for sale, the seller might remove a child token just before before the sale and thus the buyer would not receive the expected child token. This is a risk that is inherent to the design of this standard. Marketplaces should take this into account and provide a way to verify the expected child tokens are present when the parent token is being sold or to guard against such a malicious behaviour in another way.</p> <p>It is worth noting that <code>balanceOf</code> method only accounts for immediate tokens owned by the address; the tokens that are nested into a token owned by this address will not be reflected in this value as the recursive lookup needed in order to calculate this value is potentially too deep and might break the method.</p> <p>Caution is advised when dealing with non-audited 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> 2023-07-26T00:00:00+00:00 2026-02-11T14:48:25+00:00 Aaron Yeehttps://github.com/aaronyee-eth https://wg-eips.ritovision.com/7405/

Migrating smart contract accounts at the Proxy (ERC-1967) layer.

<h2 id="abstract">Abstract</h2> <p>Portable Smart Contract Accounts (PSCA) address the lack of portability and compatibility faced by Smart Contract Accounts (SCA) across different wallet providers. Based on <a href="https://wg-eips.ritovision.com/1967/">ERC-1967</a>, the PSCA system allows users to easily migrate their SCAs between different wallets using new, randomly generated migration keys. This provides a similar experience to exporting an externally owned account (EOA) with a private key or mnemonic. The system ensures security by employing signatures and time locks, allowing users to verify and cancel migration operations during the lock period, thereby preventing potential malicious actions. PSCA offers a non-intrusive and cost-effective approach, enhancing the interoperability and composability within the Account Abstraction (AA) ecosystem.</p> <h2 id="motivation">Motivation</h2> <p>With the introduction of the <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> standard, AA related infrastructure and SCAs have been widely adopted in the community. However, unlike EOAs, SCAs have a more diverse code space, leading to varying contract implementations across different wallet providers. Consequently, the lack of portability for SCAs has become a significant issue, making it challenging for users to migrate their accounts between different wallet providers. While some proposed a modular approach for SCA accounts, it comes with higher implementation costs and specific prerequisites for wallet implementations.</p> <p>Considering that different wallet providers tend to prefer their own implementations or may expect their contract systems to be concise and robust, a modular system may not be universally applicable. The community currently lacks a more general SCA migration standard.</p> <p>This proposal describes a solution working at the Proxy (ERC-1967) layer, providing a user experience similar to exporting an EOA account (using private keys or mnemonics). A universal SCA migration mechanism is shown in the following diagram:</p> <p><img src="https://wg-eips.ritovision.com/7405/./assets/overview-diagram.jpg" alt="Overview Diagram" /></p> <p>Considering that different wallet providers may have their own implementations, this solution imposes almost no requirements on the SCA implementation, making it more universally applicable and less intrusive with lower operational costs. Unlike a modular system operating at the "implementation" layer, both approaches can complement each other to further improve the interoperability and composability of the AA 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> <h3 id="terms">Terms</h3> <ul> <li>Wallet Provider: A service provider that offers wallet services. SCA implementations among wallet providers are typically different, lacking compatibility with each other.</li> <li>Random Operator: A new, randomly generated migration mnemonic or private key used for each migration. The corresponding address of its public key is the random operator's address. <ul> <li>If using a mnemonic, the derived migration private key follows the <a rel="external" href="https://github.com/bitcoin/bips/blob/55566a73f9ddf77b4512aca8e628650c913067bf/bip-0044.mediawiki">BIP 44</a> specification with the path <strong><code>m/44'/60'/0'/0/0'</code></strong>.</li> </ul> </li> </ul> <h3 id="interfaces">Interfaces</h3> <p>A Portable Smart Contract Account <strong>MUST</strong> implement the <strong><code>IERC7405</code></strong> 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"> IERC7405</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 account finishes the migration</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> oldImplementation</span><span class="z-comment"> old implementation 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"> newImplementation</span><span class="z-comment"> new implementation address</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"> AccountMigrated</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> oldImplementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> newImplementation</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> prepare the account for migration</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> randomOperator</span><span class="z-comment"> public key (in address format) of the random 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"> signature</span><span class="z-comment"> signature signed by the random operator</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * **MUST** check the authenticity of the account</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"> prepareAccountMigration</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> randomOperator</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"> signature</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">@dev</span><span class="z-comment"> cancel the account migration</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * **MUST** check the authenticity of the account</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"> cancelAccountMigration</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">@dev</span><span class="z-comment"> handle the account migration</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> newImplementation</span><span class="z-comment"> new implementation 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"> initData</span><span class="z-comment"> init data for the new 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"> signature</span><span class="z-comment"> signature signed by the random operator</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * **MUST NOT** check the authenticity to make it accessible by the new implementation</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"> handleAccountMigration</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> newImplementation</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"> initData</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"> signature</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><h3 id="signatures">Signatures</h3> <p>The execution of migration operations <strong>MUST</strong> use the migration private key to sign the <code>MigrationOp</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"> MigrationOp</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"> bytes4</span><span> selector</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></code></pre> <p>When the <strong><code>selector</code></strong> corresponds to <strong><code>prepareAccountMigration(address,bytes)</code></strong> (i.e., <strong><code>0x50fe70bd</code></strong>), the <strong><code>data</code></strong> is <strong><code>abi.encode(randomOperator)</code></strong>. When the <strong><code>selector</code></strong> corresponds to <strong><code>handleAccountMigration(address,bytes,bytes)</code></strong> (i.e., <strong><code>0xae2828ba</code></strong>), the <strong><code>data</code></strong> is <strong><code>abi.encode(randomOperator, setupCalldata)</code></strong>.</p> <p>The signature is created using <strong><a href="https://wg-eips.ritovision.com/191/">ERC-191</a></strong>, signing the <strong><code>MigrateOpHash</code></strong> (calculated as <strong><code>abi.encode(chainID, selector, data)</code></strong>).</p> <h3 id="registry">Registry</h3> <p>To simplify migration credentials and enable direct addressing of the SCA account with only the migration mnemonic or private key, this proposal requires a shared registry deployed at the protocol layer.</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"> IERC7405Registry</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> MigrationData</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 class="z-support"> uint48</span><span> createTime</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint48</span><span> lockUntil</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"> check if the migration data for the random operator 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"> randomOperator</span><span class="z-comment"> public key (in address format) of the random 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"> migrationDataExists</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> randomOperator</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">@dev</span><span class="z-comment"> get the migration data for the random 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"> randomOperator</span><span class="z-comment"> public key (in address format) of the random 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"> getMigrationData</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> randomOperator</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-storage z-type">MigrationData</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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> set the migration data for the random 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"> randomOperator</span><span class="z-comment"> public key (in address format) of the random 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"> lockUntil</span><span class="z-comment"> the timestamp until which the account is locked for migration</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * **MUST** validate `migrationDataMap[randomOperator]` 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"> setMigrationData</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> randomOperator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint48</span><span class="z-variable"> lockUntil</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">@dev</span><span class="z-comment"> delete the migration data for the random 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"> randomOperator</span><span class="z-comment"> public key (in address format) of the random operator</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * **MUST** validate `migrationDataMap[randomOperator].account` is `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"> deleteMigrationData</span><span>(</span><span class="z-support">address</span><span class="z-variable"> randomOperator</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-behavior">Expected behavior</h3> <p>When performing account migration (i.e., migrating an SCA from Wallet A to Wallet B), the following steps <strong>MUST</strong> be followed:</p> <ol> <li>Wallet A generates a new migration mnemonic or private key (<strong>MUST</strong> be new and random) and provides it to the user. The address corresponding to its public key is used as the <strong><code>randomOperator</code></strong>.</li> <li>Wallet A signs the <strong><code>MigrateOpHash</code></strong> using the migration private key and calls the <strong><code>prepareAccountMigration</code></strong> method, which <strong>MUST</strong> performs the following operations: <ul> <li>Calls the internal method <strong><code>_requireAccountAuth()</code></strong> to verify the authenticity of the SCA account. For example, in ERC-4337 account implementation, it may require <strong><code>msg.sender == address(entryPoint)</code></strong>.</li> <li>Performs signature checks to confirm the validity of the <strong><code>randomOperator</code></strong>.</li> <li>Calls <strong><code>IERC7405Registry.migrationDataExists(randomOperator)</code></strong> to ensure that the <strong><code>randomOperator</code></strong> does not already exist.</li> <li>Sets the SCA account's lock status to true and adds a record by calling <strong><code>IERC7405Registry.setMigrationData(randomOperator, lockUntil)</code></strong>.</li> <li>After calling <strong><code>prepareAccountMigration</code></strong>, the account remains locked until a successful call to either <strong><code>cancelAccountMigration</code></strong> or <strong><code>handleAccountMigration</code></strong>.</li> </ul> </li> <li>To continue the migration, Wallet B initializes authentication data and imports the migration mnemonic or private key. Wallet B then signs the <strong><code>MigrateOpHash</code></strong> using the migration private key and calls the <strong><code>handleWalletMigration</code></strong> method, which <strong>MUST</strong> performs the following operations: <ul> <li><strong>MUST NOT</strong> perform SCA account authentication checks to ensure public accessibility.</li> <li>Performs signature checks to confirm the validity of the <strong><code>randomOperator</code></strong>.</li> <li>Calls <strong><code>IERC7405Registry.getMigrationData(randomOperator)</code></strong> to retrieve <strong><code>migrationData</code></strong>, and requires <strong><code>require(migrationData.account == address(this) &amp;&amp; block.timestamp &gt; migrationData.lockUntil)</code></strong>.</li> <li>Calls the internal method <strong><code>_beforeWalletMigration()</code></strong> to execute pre-migration logic from Wallet A (e.g., data cleanup).</li> <li>Modifies the Proxy (ERC-1967) implementation to the implementation contract of Wallet B.</li> <li>Calls <strong><code>address(this).call(initData)</code></strong> to initialize the Wallet B contract.</li> <li>Calls <strong><code>IERC7405Registry.deleteMigrationData(randomOperator)</code></strong> to remove the record.</li> <li>Emits the <strong><code>AccountMigrated</code></strong> event.</li> </ul> </li> <li>If the migration needs to be canceled, Wallet A can call the <strong><code>cancelAccountMigration</code></strong> method, which <strong>MUST</strong> performs the following operations: <ul> <li>Calls the internal method <strong><code>_requireAccountAuth()</code></strong> to verify the authenticity of the SCA account.</li> <li>Sets the SCA account's lock status to false and deletes the record by calling <strong><code>IERC7405Registry.deleteMigrationData(randomOperator)</code></strong>.</li> </ul> </li> </ol> <h3 id="storage-layout">Storage Layout</h3> <p>To prevent conflicts in storage layout during migration across different wallet implementations, a Portable Smart Contract Account implementation contract:</p> <ul> <li><strong>MUST NOT</strong> directly define state variables in the contract header.</li> <li><strong>MUST</strong> encapsulate all state variables within a struct and store that struct in a specific slot. The slot index <strong>SHOULD</strong> be unique across different wallet implementations.</li> </ul> <p>For slot index, we recommend calculating it based on the namespace and slot ID:</p> <ul> <li>The namespace <strong>MUST</strong> contain only [A-Za-z0-9_].</li> <li>Wallet providers' namespaces are <strong>RECOMMENDED</strong> to use snake_case, incorporating the wallet name and major version number, such as <strong><code>foo_wallet_v1</code></strong>.</li> <li>The slot ID for slot index <strong>SHOULD</strong> follow the format <strong><code>{namespace}.{customDomain}</code></strong>, for example, <strong><code>foo_wallet_v1.config</code></strong>.</li> <li>The calculation of the slot index is performed as <strong><code>bytes32(uint256(keccak256(slotID) - 1))</code></strong>.</li> </ul> <h2 id="rationale">Rationale</h2> <p>The main challenge addressed by this EIP is the lack of portability in Smart Contract Accounts (SCAs). Currently, due to variations in SCA implementations across wallet providers, moving between wallets is a hassle. Proposing a modular approach, though beneficial in some respects, comes with its own costs and compatibility concerns.</p> <p>The PSCA system, rooted in ERC-1967, introduces a migration mechanism reminiscent of exporting an EOA with a private key or mnemonic. This approach is chosen for its familiarity to users, ensuring a smoother user experience.</p> <p>Employing random, migration-specific keys further fortifies security. By mimicking the EOA exportation process, we aim to keep the process recognizable, while addressing the unique challenges of SCA portability.</p> <p>The decision to integrate with a shared registry at the protocol layer simplifies migration credentials. This system enables direct addressing of the SCA account using only the migration key, enhancing efficiency.</p> <p>Storage layout considerations were paramount to avoid conflicts during migrations. Encapsulating state variables within a struct, stored in a unique slot, ensures that migrations don't lead to storage overlaps or overwrites.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is backward compatible with all SCA based on ERC-1967 Proxy, including non-ERC-4337 SCAs. Furthermore, this proposal does not have specific prerequisites for SCA implementation contracts, making it broadly applicable to various SCAs.</p> <!-- ## Reference Implementation [WIP] --> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>Each migration must generate a new, randomly generated migration mnemonic or private key and its corresponding random operator address to prevent replay attacks or malicious signing.</li> <li>Different wallet implementations must consider the independence of storage layout to avoid conflicts in storage after migration.</li> <li>To prevent immediate loss of access for the account owner due to malicious migration, we introduce a "time lock" to make migrations detectable and reversible. When a malicious operation attempts an immediate migration of an SCA, the account enters a lock state and waits for a lock period. During this time, users can use the original account authentication to cancel the migration and prevent asset loss. Accounts in the lock state <strong>SHOULD NOT</strong> allow the following operations: <ul> <li>Any form of asset transfer operations</li> <li>Any form of external contract call operations</li> <li>Any attempts to modify account authentication factors</li> <li>Any operations that could potentially impact the above three</li> </ul> </li> <li>When performing migration operations, the wallet provider <strong>SHOULD</strong> attempt to notify the account owner of the migration details through all available messaging channels.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <strong><a href="https://wg-eips.ritovision.com/license/">CC0</a></strong>.</p> 2023-07-26T00:00:00+00:00 2026-02-11T14:48:25+00:00 Bruno Škvorchttps://github.com/Swader Steven Pinedahttps://github.com/steven2308 Stevan Bogosavljevichttps://github.com/stevyhacker Jan Turkhttps://github.com/ThunderDeliverer https://wg-eips.ritovision.com/7409/

React to any Non-Fungible Tokens using Unicode emojis.

<h2 id="abstract">Abstract</h2> <p>❗️ <strong><a href="https://wg-eips.ritovision.com/7409/">ERC-7409</a> supersedes <a href="https://wg-eips.ritovision.com/6381/">ERC-6381</a>.</strong> ❗️</p> <p>The Public Non-Fungible Tokens Emote Repository standard provides an enhanced interactive utility for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> by allowing NFTs to be emoted at.</p> <p>This proposal introduces the ability to react to NFTs using Unicode standardized emoji in a public non-gated repository smart contract that is accessible at the same address in all of the networks.</p> <h2 id="motivation">Motivation</h2> <p>With NFTs being a widespread form of tokens in the Ethereum ecosystem and being used for a variety of use cases, it is time to standardize additional utility for them. Having the ability for anyone to interact with an NFT introduces an interactive aspect to owning an NFT and unlocks feedback-based NFT mechanics.</p> <p>This ERC introduces new utilities for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> based tokens in the following areas:</p> <ul> <li><a href="https://wg-eips.ritovision.com/7409/#interactivity">Interactivity</a></li> <li><a href="https://wg-eips.ritovision.com/7409/#feedback-based-evolution">Feedback based evolution</a></li> <li><a href="https://wg-eips.ritovision.com/7409/#valuation">Valuation</a></li> </ul> <p>This proposal fixes the compatibility issue in the <a href="https://wg-eips.ritovision.com/6381/">ERC-6381</a> interface specification, where emojis are represented using <code>bytes4</code> values. The introduction of variation flags and emoji skin tones has rendered the <code>bytes4</code> namespace insufficient for representing all possible emojis, so the new standard used <code>string</code> instead. Apart from this fix, this proposal is functionally equivalent to <a href="https://wg-eips.ritovision.com/6381/">ERC-6381</a>.</p> <h3 id="interactivity">Interactivity</h3> <p>The ability to emote on an NFT introduces the aspect of interactivity to owning an NFT. This can either reflect the admiration for the emoter (person emoting to an NFT) or can be a result of a certain action performed by the token's owner. Accumulating emotes on a token can increase its uniqueness and/or value.</p> <h3 id="feedback-based-evolution">Feedback based evolution</h3> <p>Standardized on-chain reactions to NFTs allow for feedback based evolution.</p> <p>Current solutions are either proprietary or off-chain and therefore subject to manipulation and distrust. Having the ability to track the interaction on-chain allows for trust and objective evaluation of a given token. Designing the tokens to evolve when certain emote thresholds are met incentivizes interaction with the token collection.</p> <h3 id="valuation">Valuation</h3> <p>Current NFT market heavily relies on previous values the token has been sold for, the lowest price of the listed token and the scarcity data provided by the marketplace. There is no real time indication of admiration or desirability of a specific token. Having the ability for users to emote to the tokens adds the possibility of potential buyers and sellers gauging the value of the token based on the impressions the token has collected.</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-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-7409 Emotable Extension for Non-Fungible Tokens</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-7409</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 ERC-165 identifier for this interface is 0x1b3327ab.</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.16</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"> IERC7409</span><span class="z-comment"> /*</span><span class="z-comment">is IERC165</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"> Used to notify listeners that the token with the specified ID has been emoted to or that the reaction has been revoked.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The event MUST only be emitted if the state of the emote is </span><span class="z-keyword">changed</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"> emoter</span><span class="z-comment"> Address of the account that emoted or revoked the reaction to 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"> collection</span><span class="z-comment"> Address of the collection smart contract containing the token being emoted to or having the reaction 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"> ID of 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"> emoji</span><span class="z-comment"> Unicode identifier of the emoji</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> on</span><span class="z-comment"> Boolean value signifying whether the token was emoted to (`true`) or if the reaction has been revoked (`false`)</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"> Emoted</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"> emoter</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"> collection</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"> emoji</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> on</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"> Used to get the number of emotes for a specific emoji on 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"> collection</span><span class="z-comment"> Address of the collection containing the token being checked for emoji count</span></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 token to check for emoji count</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emoji</span><span class="z-comment"> Unicode identifier of the emoji</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 emotes with the emoji 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"> emoteCountOf</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> emoji</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"> Used to get the number of emotes for a specific emoji on a set of 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"> collections</span><span class="z-comment"> An array of addresses of the collections containing the tokens being checked for emoji count</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> An array of IDs of the tokens to check for emoji count</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emojis</span><span class="z-comment"> An array of unicode identifiers of the emojis</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"> array of numbers of emotes with the emoji on 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"> bulkEmoteCountOf</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"> collections</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"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> emojis</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 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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to get the information on whether the specified address has used a specific emoji on a specific</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> emoter</span><span class="z-comment"> Address of the account we are checking for a reaction to 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"> collection</span><span class="z-comment"> Address of the collection smart contract containing the token being checked for emoji reaction</span></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 token being checked for emoji reaction</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emoji</span><span class="z-comment"> The ASCII emoji code being checked for reaction</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 value indicating whether the `emoter` has used the `emoji` on the token (`true`) or not</span></span> <span class="giallo-l"><span class="z-comment"> * (`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"> hasEmoterUsedEmote</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> emoter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> emoji</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"> Used to get the information on whether the specified addresses have used specific emojis on specific</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> emoters</span><span class="z-comment"> An array of addresses of the accounts we are checking for reactions to 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"> collections</span><span class="z-comment"> An array of addresses of the collection smart contracts containing the tokens being checked</span></span> <span class="giallo-l"><span class="z-comment"> * for emoji reactions</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> An array of IDs of the tokens being checked for emoji reactions</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emojis</span><span class="z-comment"> An array of the ASCII emoji codes being checked for reactions</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"> array of boolean values indicating whether the `emoter`s has used the `emoji`s on the tokens (`true`)</span></span> <span class="giallo-l"><span class="z-comment"> * or not (`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"> haveEmotersUsedEmotes</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"> emoters</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"> collections</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"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> emojis</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 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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to get the message to be signed by the `emoter` in order for the reaction to be submitted by someone</span></span> <span class="giallo-l"><span class="z-comment"> * else.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collection</span><span class="z-comment"> The address of the collection smart contract containing the token being emoted at</span></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 token being emoted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emoji</span><span class="z-comment"> Unicode identifier of the emoji</span></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"> Boolean value signifying whether to emote (`true`) or undo (`false`) emote</span></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"> UNIX timestamp of the deadline for the signature to be submitted</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"> message to be signed by the `emoter` in order for the reaction to be submitted by someone else</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"> prepareMessageToPresignEmote</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> emoji</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> state</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</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">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">@notice</span><span class="z-comment"> Used to get multiple messages to be signed by the `emoter` in order for the reaction to be submitted by someone</span></span> <span class="giallo-l"><span class="z-comment"> * else.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collections</span><span class="z-comment"> An array of addresses of the collection smart contracts containing the tokens being emoted at</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> An array of IDs of the tokens being emoted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emojis</span><span class="z-comment"> An array of unicode identifiers of the emojis</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> states</span><span class="z-comment"> An array of boolean values signifying whether to emote (`true`) or undo (`false`) emote</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> deadlines</span><span class="z-comment"> An array of UNIX timestamps of the deadlines for the signatures to be submitted</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"> array of messages to be signed by the `emoter` in order for the reaction to be submitted by someone else</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"> bulkPrepareMessagesToPresignEmote</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"> collections</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"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> emojis</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> states</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"> deadlines</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">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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to emote or undo an emote on 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"> Does nothing if attempting to set a pre-existent state.</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 the `Emoted` event is the state of the emote is </span><span class="z-keyword">changed</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"> collection</span><span class="z-comment"> Address of the collection containing the token being emoted at</span></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 token being emoted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emoji</span><span class="z-comment"> Unicode identifier of the emoji</span></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"> Boolean value signifying whether to emote (`true`) or undo (`false`) emote</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"> emote</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> emoji</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> state</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"> Used to emote or undo an emote on 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"> Does nothing if attempting to set a pre-existent state.</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 the `Emoted` event is the state of the emote is </span><span class="z-keyword">changed</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"> MUST revert if the lengths of the `collections`, `tokenIds`, `emojis` and `states` arrays are not equal.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collections</span><span class="z-comment"> An array of addresses of the collections containing the tokens being emoted at</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> An array of IDs of the tokens being emoted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emojis</span><span class="z-comment"> An array of unicode identifiers of the emojis</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> states</span><span class="z-comment"> An array of boolean values signifying whether to emote (`true`) or undo (`false`) emote</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"> bulkEmote</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"> collections</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"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> emojis</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> states</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"> Used to emote or undo an emote on someone else&#39;s behalf.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Does nothing if attempting to set a pre-existent state.</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 the `Emoted` event is the state of the emote is </span><span class="z-keyword">changed</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"> MUST revert if the lengths of the `collections`, `tokenIds`, `emojis` and `states` arrays are not equal.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the `deadline` has passed.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the recovered address is 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"> emoter</span><span class="z-comment"> The address that presigned the emote</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collection</span><span class="z-comment"> The address of the collection smart contract containing the token being emoted at</span></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"> IDs of the token being emoted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emoji</span><span class="z-comment"> Unicode identifier of the emoji</span></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"> Boolean value signifying whether to emote (`true`) or undo (`false`) emote</span></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"> UNIX timestamp of the deadline for the signature to be submitted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> v</span><span class="z-comment"> `v` value of an ECDSA signature of the message obtained via `prepareMessageToPresignEmote`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> r</span><span class="z-comment"> `r` value of an ECDSA signature of the message obtained via `prepareMessageToPresignEmote`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> s</span><span class="z-comment"> `s` value of an ECDSA signature of the message obtained via `prepareMessageToPresignEmote`</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"> presignedEmote</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> emoter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> emoji</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> state</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</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"> Used to bulk emote or undo an emote on someone else&#39;s behalf.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Does nothing if attempting to set a pre-existent state.</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 the `Emoted` event is the state of the emote is </span><span class="z-keyword">changed</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"> MUST revert if the lengths of the `collections`, `tokenIds`, `emojis` and `states` arrays are not equal.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the `deadline` has passed.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the recovered address is 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"> emoters</span><span class="z-comment"> An array of addresses of the accounts that presigned the emotes</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collections</span><span class="z-comment"> An array of addresses of the collections containing the tokens being emoted at</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> An array of IDs of the tokens being emoted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emojis</span><span class="z-comment"> An array of unicode identifiers of the emojis</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> states</span><span class="z-comment"> An array of boolean values signifying whether to emote (`true`) or undo (`false`) emote</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> deadlines</span><span class="z-comment"> UNIX timestamp of the deadline for the signature to be submitted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> v</span><span class="z-comment"> An array of `v` values of an ECDSA signatures of the messages obtained via `prepareMessageToPresignEmote`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> r</span><span class="z-comment"> An array of `r` values of an ECDSA signatures of the messages obtained via `prepareMessageToPresignEmote`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> s</span><span class="z-comment"> An array of `s` values of an ECDSA signatures of the messages obtained via `prepareMessageToPresignEmote`</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"> bulkPresignedEmote</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"> emoters</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"> collections</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"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> emojis</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> states</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"> deadlines</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"> v</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"> r</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"> s</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><h3 id="message-format-for-presigned-emotes">Message format for presigned emotes</h3> <p>The message to be signed by the <code>emoter</code> in order for the reaction to be submitted by someone else is formatted 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">encode</span><span>(</span></span> <span class="giallo-l"><span> DOMAIN_SEPARATOR</span><span>,</span></span> <span class="giallo-l"><span> collection</span><span>,</span></span> <span class="giallo-l"><span> tokenId</span><span>,</span></span> <span class="giallo-l"><span> emoji</span><span>,</span></span> <span class="giallo-l"><span> state</span><span>,</span></span> <span class="giallo-l"><span> deadline</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> )</span><span>;</span></span></code></pre> <p>The values passed when generating the message to be signed are:</p> <ul> <li><code>DOMAIN_SEPARATOR</code> - The domain separator of the Emotable repository smart contract</li> <li><code>collection</code> - Address of the collection containing the token being emoted at</li> <li><code>tokenId</code> - ID of the token being emoted</li> <li><code>emoji</code> - Unicode identifier of the emoji</li> <li><code>state</code> - Boolean value signifying whether to emote (<code>true</code>) or undo (<code>false</code>) emote</li> <li><code>deadline</code> - UNIX timestamp of the deadline for the signature to be submitted</li> </ul> <p>The <code>DOMAIN_SEPARATOR</code> is generated 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">encode</span><span>(</span></span> <span class="giallo-l"><span class="z-string"> &quot;ERC-7409: Public Non-Fungible Token Emote Repository&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;1&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-language"> block</span><span>.</span><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 class="giallo-l"><span> )</span><span>;</span></span></code></pre> <p>Each chain, that the Emotable repository smart contract is deployed on, will have a different <code>DOMAIN_SEPARATOR</code> value due to chain IDs being different.</p> <h3 id="pre-determined-address-of-the-emotable-repository">Pre-determined address of the Emotable repository</h3> <p>The address of the Emotable repository smart contract is designed to resemble the function it serves. It starts with <code>0x3110735</code> which is the abstract representation of <code>EMOTES</code>. The address is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x3110735F0b8e71455bAe1356a33e428843bCb9A1</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Designing the proposal, we considered the following questions:</p> <ol> <li><strong>Does the proposal support custom emotes or only the Unicode specified ones?</strong><br /> The proposal only accepts the Unicode identifier which is a <code>string</code> value. This means that while we encourage implementers to add the reactions using standardized emojis, the values not covered by the Unicode standard can be used for custom emotes. The only drawback being that the interface displaying the reactions will have to know what kind of image to render and such additions will probably be limited to the interface or marketplace in which they were made.</li> <li><strong>Should the proposal use emojis to relay the impressions of NFTs or some other method?</strong><br /> The impressions could have been done using user-supplied strings or numeric values, yet we decided to use emojis since they are a well established mean of relaying impressions and emotions.</li> <li><strong>Should the proposal establish an emotable extension or a common-good repository?</strong><br /> Initially we set out to create an emotable extension to be used with any ERC-721 compliant tokens. However, we realized that the proposal would be more useful if it was a common-good repository of emotable tokens. This way, the tokens that can be reacted to are not only the new ones but also the old ones that have been around since before the proposal.<br /> In line with this decision, we decided to calculate a deterministic address for the repository smart contract. This way, the repository can be used by any NFT collection without the need to search for the address on the given chain.</li> <li><strong>Should we include only single-action operations, only multi-action operations, or both?</strong><br /> We've considered including only single-action operations, where the user is only able to react with a single emoji to a single token, but we decided to include both single-action and multi-action operations. This way, the users can choose whether they want to emote or undo emote on a single token or on multiple tokens at once.<br /> This decision was made for the long-term viability of the proposal. Based on the gas cost of the network and the number of tokens in the collection, the user can choose the most cost-effective way of emoting.</li> <li><strong>Should we add the ability to emote on someone else's behalf?</strong><br /> While we did not intend to add this as part of the proposal when drafting it, we realized that it would be a useful feature for it. This way, the users can emote on behalf of someone else, for example, if they are not able to do it themselves or if the emote is earned through an off-chain activity.</li> <li><strong>How do we ensure that emoting on someone else's behalf is legitimate?</strong><br /> We could add delegates to the proposal; when a user delegates their right to emote to someone else, the delegate can emote on their behalf. However, this would add a lot of complexity and additional logic to the proposal.<br /> Using ECDSA signatures, we can ensure that the user has given their consent to emote on their behalf. This way, the user can sign a message with the parameters of the emote and the signature can be submitted by someone else.</li> <li><strong>Should we add chain ID as a parameter when reacting to a token?</strong><br /> During the course of discussion of the proposal, a suggestion arose that we could add chain ID as a parameter when reacting to a token. This would allow the users to emote on the token of one chain on another chain.<br /> We decided against this as we feel that additional parameter would rarely be used and would add additional cost to the reaction transactions. If the collection smart contract wants to utilize on-chain emotes to tokens they contain, they require the reactions to be recorded on the same chain. Marketplaces and wallets integrating this proposal will rely on reactions to reside in the same chain as well, because if chain ID parameter was supported this would mean that they would need to query the repository smart contract on all of the chains the repository is deployed in order to get the reactions for a given token.<br /> Additionally, if the collection creator wants users to record their reactions on a different chain, they can still direct the users to do just that. The repository does not validate the existence of the token being reacted to, which in theory means that you can react to non-existent token or to a token that does not exist yet. The likelihood of a different collection existing at the same address on another chain is significantly low, so the users can react using the collection's address on another chain and it is very unlikely that they will unintentionally react to another collection's token.</li> <li><strong>Should we use <code>bytes4</code> or <code>strings</code> to represent emotes?</strong><br /> Initially the proposal used <code>bytes4</code>. This was due to the assumption that all of the emojis use UTF-4 encoding, which is not the case.<br /> The emojis usually use up to 8 bytes, but the personalized emojis with skin tones use much more. This is why we decided to use <code>strings</code> to represent the emotes. This allows the repository to be forward compatible with any future emojis that might be added to the Unicode standard.<br /> This is how this proposal fixes the forward compatibility issue of the <a href="https://wg-eips.ritovision.com/6381/">ERC-6381</a>.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The Emote repository standard is fully compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and with the robust tooling available for implementations of ERC-721 as well as with the existing ERC-721 infrastructure.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests are included in <a href="https://wg-eips.ritovision.com/7409/./assets/test/emotableRepository.ts"><code>emotableRepository.ts</code></a>.</p> <p>To run them in terminal, you can use the following commands:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cd ../assets/eip-7409</span></span> <span class="giallo-l"><span>npm install</span></span> <span class="giallo-l"><span>npx hardhat test</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/7409/./assets/contracts/EmotableRepository.sol"><code>EmotableRepository.sol</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The proposal does not envision handling any form of assets from the user, so the assets should not be at risk when interacting with an Emote repository.</p> <p>The ability to use ECDSA signatures to emote on someone else's behalf introduces the risk of a replay attack, which the format of the message to be signed guards against. The <code>DOMAIN_SEPARATOR</code> used in the message to be signed is unique to the repository smart contract of the chain it is deployed on. This means that the signature is invalid on any other chain and the Emote repositories deployed on them should revert the operation if a replay attack is attempted.</p> <p>Another thing to consider is the ability of presigned message reuse. Since the message includes the signature validity deadline, the message can be reused any number of times before the deadline is reached. The proposal only allows for a single reaction with a given emoji to a specific token to be active, so the presigned message can not be abused to increase the reaction count on the token. However, if the service using the repository relies on the ability to revoke the reaction after certain actions, a valid presigned message can be used to re-react to the token. We suggest that the services using the repository in conjunction with presigned messages use deadlines that invalidate presigned messages after a reasonably short period of time.</p> <p>Caution is advised when dealing with non-audited 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> 2023-07-26T00:00:00+00:00 2026-02-11T14:48:25+00:00 Mohammad Zakeri Radhttps://github.com/zakrad Adam Boudjemaahttps://github.com/aboudjem Mohamad Hammoudhttps://github.com/mohamadhammoud https://wg-eips.ritovision.com/7410/

Extension to enable revoking and decreasing allowance approval by spender for ERC-20

<h2 id="abstract">Abstract</h2> <p>This extension adds a <code>decreaseAllowanceBySpender</code> function to decrease <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> allowances, in which a spender can revoke or decrease a given allowance by a specific address. This ERC extends <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>.</p> <h2 id="motivation">Motivation</h2> <p>Currently, <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens offer allowances, enabling token owners to authorize spenders to use a designated amount of tokens on their behalf. However, the process of decreasing an allowance is limited to the owner's side, which can be problematic if the token owner is a treasury wallet or a multi-signature wallet that has granted an excessive allowance to a spender. In such cases, reducing the allowance from the owner's perspective can be time-consuming and challenging.</p> <p>To address this issue and enhance security measures, this ERC proposes allowing spenders to decrease or revoke the granted allowance from their end. This feature provides an additional layer of security in the event of a potential hack in the future. It also eliminates the need for a consensus or complex procedures to decrease the allowance from the token owner's side.</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>Contracts using this ERC MUST implement the <code>IERC7410</code> interface.</p> <h3 id="interface-implementation">Interface implementation</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-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> IERC-7410 Update Allowance By Spender Extension</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 0x12860fba</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"> IERC7410</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Decreases any allowance by `owner` address for caller.</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {IERC20-Approval} event.</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"> * - when `subtractedValue` is equal or higher than current allowance of spender the new allowance is set to 0.</span></span> <span class="giallo-l"><span class="z-comment"> * Nullification also MUST be reflected for current allowance being type(uint256).max.</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"> decreaseAllowanceBySpender</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"> subtractedValue</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> <p>The <code>decreaseAllowanceBySpender(address owner, uint256 subtractedValue)</code> function MUST be either <code>public</code> or <code>external</code>.</p> <p>The <code>Approval</code> event MUST be emitted when <code>decreaseAllowanceBySpender</code> is called.</p> <p>The <code>supportsInterface</code> method MUST return <code>true</code> when called with <code>0x12860fba</code>.</p> <h2 id="rationale">Rationale</h2> <p>The technical design choices within this ERC are driven by the following considerations:</p> <ul> <li>The introduction of the <code>decreaseAllowanceBySpender</code> function empowers spenders by allowing them to autonomously revoke or decrease allowances. This design choice aligns with the goal of providing more direct control to spenders over their authorization levels.</li> <li>The requirement for the <code>subtractedValue</code> to be lower than the current allowance ensures a secure implementation. Additionally, nullification is achieved by setting the new allowance to 0 when <code>subtractedValue</code> is equal to or exceeds the current allowance. This approach adds an extra layer of security and simplifies the process of decreasing allowances.</li> <li>The decision to maintain naming patterns similar to <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>'s approvals is rooted in promoting consistency and ease of understanding for developers familiar with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>An minimal implementation is included <a href="https://wg-eips.ritovision.com/7410/./assets/ERC7410.sol">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Users of this ERC must thoroughly consider the amount of tokens they decrease from their allowance for an <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> 2023-07-26T00:00:00+00:00 2026-02-11T14:48:25+00:00 Noah Litvinhttps://github.com/noahlitvin dbhttps://github.com/dbeal-eth https://wg-eips.ritovision.com/7412/

A method to construct multicalls with prepended verifiable off-chain data

<h2 id="abstract">Abstract</h2> <p>Contracts may require off-chain data during execution. A smart contract function could implement the standard proposed here by reverting with <code>error OracleDataRequired(address oracleContract, bytes oracleQuery, uint256 feeRequired)</code>. Clients supporting this standard would recognize this error message during a simulation of the request, query the specified decentralized oracle network for signed data, and instead stage a transaction with a multicall that prepends the verification of the required off-chain data. The data would be written on-chain during verification to a smart contract for the subsequent call to read, avoiding the error.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum's scaling roadmap involves a series of separate execution contexts for smart contract code (including layer two and layer three scaling solutions). This makes the ability to read data across multiple chains crucial to the construction of scalable applications. Also, for decentralized finance protocols that rely on price data, it is not reasonable to expect oracle networks will be able to continuously push fresh data to every layer two and layer three network for an arbitrary number of price feeds.</p> <p>Cross-chain bridges are being developed where smart contract functions can write data to other chains. There is a need for a similar standard that enables reading data from other chains. This standard can be generalized for reading any off-chain data from a decentralized oracle network, including price feeds.</p> <p>With standards for both writing and reading cross-chain data, protocol developers will be able to create abstractions for asynchronicity (a topic thoroughly explored in other software engineering contexts). This will enable the development of highly sophisticated protocols that do not suffer from scaling constraints.</p> <p><a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a> introduced the use of reverts for requiring off-chain data, but there are various challenges introduced by the specifics of that standard which are outlined in the <em>Rationale</em> section below. By leveraging multicalls rather than callback functions, the standard proposed here is able to overcome some of these constraints.</p> <h2 id="specification">Specification</h2> <p>A contract implementing this standard MUST revert with the following error whenever off-chain data is required:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> OracleDataRequired</span><span>(</span><span class="z-support">address</span><span> oracleContract</span><span>,</span><span class="z-support"> bytes</span><span> oracleQuery</span><span>,</span><span class="z-support"> uint256</span><span> feeRequired</span><span>)</span></span></code></pre> <p><code>oracleQuery</code> specifies the off-chain data that is being required. Valid data formats for this parameter are specific to the oracle ID specified by the oracle contract. This might include chain id, contract address, function signature, payload, and timestamp/"latest" for cross-chain reads. For price feeds, it could include a ticker symbol and timestamp/"latest".</p> <p><code>oracleContract</code> is the address of the contract which can verify the off-chain data and provide it to the contract to avoid the <code>OracleDataRequired</code> error. This contract 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"> IERC7412</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> oracleId</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 class="z-support">bytes32</span><span class="z-variable"> oracleId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> fulfillOracleQuery</span><span>(</span><span class="z-support">bytes</span><span class="z-variable"> signedOffchainData</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> <p><code>oracleId</code> is a unique identifier that references the decentralized oracle network that generates the desired signed off-chain data. Oracle IDs would be analogous to Chain IDs in the Ethereum ecosystem. Clients are expected to resolve a gateway that corresponds to an Oracle ID, similar to how clients are expected to resolve an RPC endpoint based on a Chain ID.</p> <p>It should be possible to derive the <code>oracleQuery</code> from the <code>signedOffchainData</code>, such that the oracle contract is able to provide the verified offchain data based on the <code>oracleQuery</code>.</p> <p>The contract implementing the <code>IERC7412</code> interface MUST revert with the following error message if it requires payment to fulfill the oracle data query:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> FeeRequired</span><span>(</span><span class="z-support">uint</span><span> amount</span><span>)</span></span></code></pre> <p><code>amount</code> specifies the amount of native gas tokens required to execute the <code>fulfillOracleQuery</code> function, denominated in wei. This error MUST be resolved if the caller provides sufficient <code>msg.value</code> such that the fee amount can be collected by the oracle contract. The contract MAY NOT return gas tokens if they are provided in excess of the <code>amount</code>. In practice, we would expect the fee amount to remain relatively stable, if not constant.</p> <p>Additionally, to optimize for scenarios where multiple oracle data requests are needed (such as protocols requiring many price feeds simultaneously), the interface MAY include an error for batching multiple errors:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> Errors</span><span>(</span><span class="z-support">bytes</span><span>[</span><span>]</span><span> errors</span><span>)</span><span>;</span></span></code></pre> <p>This allows clients to efficiently handle multiple <code>OracleDataRequired</code> errors in a single transaction simulation, reducing the number of separate requests needed. When encountering this error, clients should parse each error in the array and handle them accordingly, potentially using recursion for nested error objects.</p> <p>It is the responsibility of the client to decide how to construct the multicall, where necessary the <code>fulfillOracleQuery</code> functions are being called before the intended function call in an atomic transaction. Wallets that support account abstraction (per <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a>) should already have the ability to generate atomic multi-operations. For EOA support, protocols could implement <a href="https://wg-eips.ritovision.com/2771/">ERC-2771</a>. A standard multicall contract can only be used to construct multicalls including functions which do not reference <code>msg.sender</code> or <code>msg.data</code>.</p> <p>Note that <code>URI</code> could be used as the <code>oracleId</code> with a URI specified as the <code>oracleQuery</code>. This would allow this standard to be compliant with arbitrary on-chain URIs without requiring updates to a client library, similar to <a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a>.</p> <h2 id="rationale">Rationale</h2> <p>This proposal is essentially an alternative to <a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a> with a couple notable distinctions:</p> <ul> <li>The error is very simple to construct. Developers implementing this standard only need to have awareness of the oracle network they choose to rely on, the form of the query accepted by this network, and the contract from which they expect to retrieve the data.</li> <li>By relying on a multicall rather than callbacks, it is much simpler to handle situations in which nested calls require different off-chain data. By the standard proposed here, end users (including those using clients that implement account abstraction) always need to simply sign a transaction, regardless of the complexity of the internal structure of the call being executed. The client can automatically prepend any necessary off-chain data to the transaction for the call to succeed.</li> </ul> <p>With this standard, not only can oracle providers scalably support an unlimited number of networks but they can also be compatible with local/forked networks for protocol development.</p> <p>Another major advantage of this standard is that oracles can charge fees in the form of native gas tokens during the on-chain verification of the data. This creates an economic incentive where fees can be collected from data consumers and provided to node operators in the decentralized oracle network.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The following pseudocode illustrates an oversimplified version of the client SDK. Ideally, this could be implemented in wallets, but it could also be built into the application layer. This function takes a desired transaction and converts it into a multicall with the required data verification transactions prepended such that the <code>OracleDataRequired</code> errors would be avoided:</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"> prepareTransaction</span><span>(</span><span class="z-variable">originalTx</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> multicallTx</span><span class="z-keyword"> =</span><span> [</span><span class="z-variable z-other">originalTx</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> (</span><span class="z-constant">true</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> try</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> simulationResult</span><span class="z-keyword"> =</span><span class="z-entity z-name"> simulateTx</span><span>(</span><span class="z-variable z-other">multicallTx</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> multicallTx</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-keyword"> if</span><span> (</span><span class="z-variable z-other">error</span><span class="z-keyword"> instanceof</span><span class="z-entity z-name"> OracleDataRequired</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"> signedRequiredData</span><span class="z-keyword"> =</span><span class="z-entity z-name"> fetchOffchainData</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> error</span><span>.</span><span class="z-variable z-other">oracleContract</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> error</span><span>.</span><span class="z-variable z-other">oracleQuery</span></span> <span class="giallo-l"><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"> dataVerificationTx</span><span class="z-keyword"> =</span><span class="z-entity z-name"> generateDataVerificationTx</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> error</span><span>.</span><span class="z-variable z-other">oracleContract</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> signedRequiredData</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> multicallTx</span><span>.</span><span class="z-entity z-name">unshift</span><span>(</span><span class="z-variable z-other">dataVerificationTx</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> <p>An oracle provider could create a contract (that might also perform some pre-processing) that would automatically trigger a request for off-chain data 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"> OracleContract</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7412</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> VERIFIER_CONTRACT </span><span class="z-keyword">=</span><span class="z-constant"> 0x0000</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> STALENESS_TOLERANCE </span><span class="z-keyword">=</span><span class="z-constant"> 86400</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> One day</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"> bytes</span><span>)</span><span class="z-storage z-type"> public</span><span> latestVerifiedData</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"> oracleId</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">bytes32</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> bytes32</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;MY_ORACLE_ID&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 class="z-storage z-type"> function</span><span class="z-entity z-name"> fulfillOracleQuery</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> signedOffchainData</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 class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> oracleQuery </span><span class="z-keyword">=</span><span class="z-entity z-name"> _verify</span><span>(</span><span>signedOffchainData</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> latestVerifiedData</span><span>[</span><span class="z-support">keccak256</span><span>(</span><span>oracleQuery</span><span>)</span><span>]</span><span class="z-keyword"> =</span><span> signedOffchainData</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"> retrieveCrossChainData</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> chainId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> contractAddress</span><span>,</span><span class="z-support"> bytes</span><span class="z-variable"> payload</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes</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> oracleQuery </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span><span>chainId</span><span>,</span><span> contractAddress</span><span>,</span><span> payload</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> (</span><span class="z-support">uint</span><span> timestamp</span><span>,</span><span class="z-support"> bytes</span><span> response</span><span>)</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>latestVerifiedData</span><span>[</span><span>oracleQuery</span><span>]</span><span>,</span><span> (</span><span class="z-support">uint</span><span>,</span><span class="z-support"> bytes</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>timestamp </span><span class="z-keyword">&lt;</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp </span><span class="z-keyword">-</span><span> STALENESS_TOLERANCE</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> OracleDataRequired</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> oracleQuery</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-keyword"> return</span><span> response</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"> _verify</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> signedOffchainData</span><span>)</span><span class="z-storage z-type"> payable</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes</span><span class="z-variable"> oracleQuery</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Insert verification code here</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> This may revert with error FeeRequired(uint amount)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Now a top-level protocol smart contract could implement a cross-chain function like so:</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"> ICrosschainContract</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> functionA</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> x</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 class="z-variable"> y</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> functionB</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> x</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 class="z-variable"> y</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"> CrosschainAdder</span><span> {</span></span> <span class="giallo-l"><span> IERC7412 oracleContract </span><span class="z-keyword">=</span><span class="z-constant"> 0x0000</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"> add</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> chainIdA</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> contractAddressA</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> chainIdB</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> contractAddressB</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 class="z-variable"> sum</span><span>)</span><span>{</span></span> <span class="giallo-l"><span> sum </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>oracleContract</span><span>.</span><span class="z-entity z-name">retrieveCrossChainData</span><span>(</span><span>chainIdA</span><span>,</span><span> contractAddressA</span><span>,</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span>ICrosschainContract</span><span>.</span><span>functionA</span><span>.</span><span>selector</span><span>,</span><span class="z-constant">1</span><span>)</span><span>)</span><span>,</span><span> (</span><span class="z-support">uint</span><span>)</span><span>)</span><span class="z-keyword"> +</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>oracleContract</span><span>.</span><span class="z-entity z-name">retrieveCrossChainData</span><span>(</span><span>chainIdB</span><span>,</span><span> contractAddressB</span><span>,</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span>ICrosschainContract</span><span>.</span><span>functionB</span><span>.</span><span>selector</span><span>,</span><span class="z-constant">2</span><span>)</span><span>)</span><span>,</span><span>(</span><span class="z-support">uint</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>Note that the developer of the <code>CrosschainAdder</code> function does not need to be concerned with the implementation of this standard. The <code>add</code> function can simply call the function on the oracle contract as if it were retrieving on-chain data normally.</p> <p>Cross-chain functions like this could also be leveraged to avoid O(n) (and greater) loops on-chain. For example, <code>chainIdA</code> and <code>chainIdB</code> could reference the same chain that the <code>CrosschainAdder</code> contract is deployed on with <code>functionA</code> and <code>functionB</code> as view functions with computationally intensive loops.</p> <h2 id="security-considerations">Security Considerations</h2> <p>One potential risk introduced by this standard is that its reliance on multicalls could obfuscate transaction data in wallet applications that do not have more sophisticated transaction decoding functionality. This is an existing challenge being addressed by wallet application developers, as multicalls are increasingly common in protocol development outside of this standard.</p> <p>Note that it is the responsibility of the verifier contract to confirm the validity of the data provided from the oracle network. This standard does not create any new opportunities for invalid data to be provided to a smart 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> 2023-07-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Alberto Cuesta Cañadahttps://github.com/alcueca Michael Amadihttps://github.com/AmadiMichaels Devtooliganhttps://github.com/devtooligan Ultrasecr.ethhttps://github.com/ultrasecreth Sam Bachahttps://github.com/sambacha https://wg-eips.ritovision.com/7399/

Interfaces and processes for flash loans

<h2 id="abstract">Abstract</h2> <p>A flash loan is a loan between lender and borrower smart contracts that must be repaid, plus an optional fee, before the end of the transaction. This ERC specifies interfaces for lenders to accept flash loan requests, and for borrowers to take temporary control of the transaction within the lender execution. The process for the safe execution of flash loans is also specified.</p> <h2 id="motivation">Motivation</h2> <p>The current state of the flash loan ecosystem is fragmented and lacks standardization, leading to several challenges for both lenders and borrowers. The absence of a common interface results in increased integration efforts, as each flash loan provider implements its own unique approach. This lack of standardization is expected to become more problematic as the ecosystem grows, requiring more resources to maintain compatibility.</p> <p>A comprehensive analysis of the existing flash loan protocols reveals significant differences in their implementations, including:</p> <ul> <li>Inconsistent syntax for initiating flash loans across different platforms.</li> <li>Variations in the relationship between the loan receiver and the callback receiver, with some protocols allowing different addresses for each role while others do not.</li> <li>Divergent repayment mechanisms, with some lenders pulling the principal and fee from the loan receiver and others requiring the loan receiver to manually return the funds.</li> <li>Disparities in the treatment of flash minting, where some lenders allow the creation of any amount of their native asset without charging a fee, effectively permitting flash loans bounded by computational constraints rather than asset ownership limitations.</li> </ul> <p>To address these inconsistencies and promote a more efficient and accessible flash loan ecosystem, this ERC specifies a standardized interface that encompasses the maximum flexibility required by both lenders and borrowers. By consolidating the various approaches into a unified standard, this proposal aims to streamline the integration process, enabling borrowers to seamlessly switch between flash lenders without the need for code modifications.</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>Under this standard a flash loan is a loan of an <code>amount</code> of an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> <code>asset</code> from a <code>lender</code>. This loan can remain open for the span of a single <code>flash</code> call in the <code>lender</code>.</p> <p>This <code>amount</code> plus a <code>fee</code> defined by the <code>lender</code> in the same <code>asset</code> must be repaid before the end of <code>flash</code> call at a <em>repayment receiver</em> address defined by the <code>lender</code>.</p> <p>The <code>flash</code> function is called by the <code>initiator</code>, who defines the <em>loan receiver</em>, the <em>callback receiver</em>, the <em>callback function</em>, the <code>asset</code> and the <code>amount</code>.</p> <p>When the <code>initiator</code> calls <code>flash</code> in a <code>lender</code>. The <code>lender</code> will then transfer the <code>amount</code> of <code>asset</code> to the <em>loan receiver</em>.</p> <p>The <code>lender</code>, after transferring <code>amount</code> of <code>asset</code> to the <em>loan receiver</em>, will execute the <em>callback function</em> on the <em>callback receiver</em>. The <code>lender</code> will include in this <em>callback function</em> call a number of parameters related to the loan as defined in this standard.</p> <p>The <code>amount</code> and <code>fee</code> need to be transferred to a <code>repayment receiver</code> before the end of the <code>flash</code> call. The <code>fee</code> can be set to zero <code>asset</code>.</p> <p>The <em>callback function</em> can return any arbitrary data which will be received by the <code>initiator</code> as the return value of the <code>flash</code> call.</p> <p>The lender decides which <code>assets</code> to support. The lender can decide to support all possible assets.</p> <h3 id="lender-specification">Lender Specification</h3> <p>A <code>lender</code> MUST implement the <a href="https://wg-eips.ritovision.com/7399/">ERC-7399</a> 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: 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.6.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> { </span><span class="z-entity z-name">IERC20</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./IERC20.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"> IERC7399</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"> The amount of currency available to be lent.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> asset</span><span class="z-comment"> The loan currency.</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 `asset` that can be borrowed.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> maxFlashLoan</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> asset</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 class="z-storage z-type"> @dev</span><span class="z-comment"> The fee to be charged for a given loan. Returns type(uint256).max if the loan is not possible.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> asset</span><span class="z-comment"> The loan currency.</span></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"> The amount of assets lent.</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 `asset` to be charged for the loan, on top of the returned principal.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> flashFee</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> IERC20</span><span class="z-variable"> asset</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-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"> @dev</span><span class="z-comment"> Initiate a flash loan.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> loanReceiver</span><span class="z-comment"> The address receiving the flash loan</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> asset</span><span class="z-comment"> The asset to be loaned</span></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"> The amount to loaned</span></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 ABI encoded user 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"> callback</span><span class="z-comment"> The address and signature of the callback 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"> result</span><span class="z-comment"> ABI encoded result of the callback</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> flash</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> loanReceiver</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> ERC20</span><span class="z-variable"> asset</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"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> data</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ @dev callback. This is a combination of the callback receiver address, and the signature of callback</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ function. It is encoded packed as 20 bytes + 4 bytes.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ @dev the return of the callback function is not encoded in the parameter, but must be `returns (bytes</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ memory)` for compliance with the standard.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ @param initiator The address that called this function</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ @param paymentReceiver The address that needs to receive the amount plus fee at the end of the callback</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ @param asset The asset to be loaned</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ @param amount The amount to loaned</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ @param fee The fee to be paid</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ @param data The ABI encoded data to be passed to the callback</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ @return result ABI encoded result of the callback</span></span> <span class="giallo-l"><span class="z-variable"> function</span><span>(</span><span class="z-support">address</span><span>,</span><span class="z-support"> address</span><span>,</span><span class="z-storage z-type"> IERC20</span><span>,</span><span class="z-support"> uint256</span><span>,</span><span class="z-support"> uint256</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span class="z-storage z-type"> external</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 class="z-entity z-name"> callback</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-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>}</span></span> <span class="giallo-l"></span></code></pre> <p>The <code>maxFlashLoan</code> function MUST return the maximum available loan for <code>asset</code>. The <code>maxFlashLoan</code> function MUST NOT revert. If no flash loans for the specified <code>asset</code> are possible, the value returned MUST be zero.</p> <p>The <code>flashFee</code> function MUST return the fee charged for a loan of <code>amount</code> <code>asset</code>. The <code>flashFee</code> function MUST NOT revert. If a flash loan for the specified <code>asset</code> and <code>amount</code> is not possible, the value returned MUST be <code>type(uint256).max</code>.</p> <p>The <code>flash</code> function MUST execute the callback passed on as an argument.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> result </span><span class="z-keyword">=</span><span class="z-entity z-name"> callback</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> asset</span><span>,</span><span> amount</span><span>,</span><span> _fee</span><span>,</span><span> data</span><span>)</span><span>;</span></span></code></pre> <p>The <code>flash</code> function MUST transfer <code>amount</code> of <code>asset</code> to <em>loan receiver</em> before executing the callback.</p> <p>The <code>flash</code> function MUST include <code>msg.sender</code> as the <code>initiator</code> in the callback.</p> <p>The <code>flash</code> function MUST NOT modify the <code>asset</code>, <code>amount</code> and <code>data</code> parameter received, and MUST pass them on to the callback.</p> <p>The <code>flash</code> function MUST include a <code>fee</code> argument in the callback with the fee to pay for the loan on top of the principal, ensuring that <code>fee == flashFee(asset, amount)</code>.</p> <p>Before the end of the callback, the <code>asset</code> balance of <code>payment receiver</code> MUST have increased by <code>amount + fee</code> from the amount at the beginning of the callback, or revert if this is not true.</p> <p>The return of the <code>flash</code> function MUST be the same as the return from the callback.</p> <h3 id="receiver-specification">Receiver Specification</h3> <p>A <em>callback receiver</em> of flash loans MUST implement one or more external functions with the following arguments and return value:</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"> This function can have any name and be overloaded.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> initiator</span><span class="z-comment"> The address that called this function</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> paymentReceiver</span><span class="z-comment"> The address that needs to receive the amount plus fee at the end of the callback</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> asset</span><span class="z-comment"> The asset to be loaned</span></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"> The amount to loaned</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> fee</span><span class="z-comment"> The fee to be paid</span></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 ABI encoded data to be passed to the callback</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"> ABI encoded result of the callback</span></span> <span class="giallo-l"><span class="z-entity z-name">function</span><span>(</span><span class="z-support">address</span><span>,</span><span class="z-support"> address</span><span>,</span><span> IERC20</span><span>,</span><span class="z-support"> uint256</span><span>,</span><span class="z-support"> uint256</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span class="z-storage z-type"> external</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> callback</span><span>;</span></span></code></pre><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>maxFlashLoan</code> and <code>flashFee</code> return numerical values on impossible loans to allow sorting lenders without having to deal with reverts.</p> <p><code>maxFlashLoan</code> returns a value that is consistent with an impossible loan when the <code>lender</code> is not able to serve the loan.</p> <p><code>flashFee</code> returns a value that is consistent with an impossible loan when the <code>lender</code> is not able to serve the loan.</p> <p><code>flash</code> has been chosen as a function name as a verb which is descriptive enough, unlikely to clash with other functions in the <code>lender</code>, and including both the use cases in which the assets lent are held or minted by the <code>lender</code>.</p> <p>Existing flash lenders all provide flash loans of several asset types from the same contract. Providing a <code>asset</code> parameter in both the <code>flash</code> and callback functions matches closely the observed functionality.</p> <p>A <code>bytes calldata data</code> parameter is included for the <code>initiator</code> to pass arbitrary information to the <code>receiver</code>. The <code>receiver</code> can pass arbitrary information back to the <code>initiator</code> using the <code>bytes memory</code> return value.</p> <p>A <code>initiator</code> will often be required in the callback function, which the <code>lender</code> 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>A <em>loan receiver</em> is taken as a parameter to allow flexibility on the implementation of separate loan initiators, loan receivers, and callback receivers. This parameter is not passed on to the <em>callback receiver</em> on the grounds that it will be often the same as <em>callback receiver</em> and when not, it can be encoded in the <code>data</code> by the <code>initiator</code>.</p> <p>A <code>payment receiver</code> allows for the same flexibility on repayments as in borrows. Control flow and asset flow are independent.</p> <p>The <code>amount</code> will be required in the callback function, which the <code>lender</code> took as a parameter. An alternative implementation which would embed the <code>amount</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>A <code>fee</code> will often be calculated in the callback function, which the callback receiver must be aware of for repayment. Passing the <code>fee</code> as a parameter instead of appended to <code>data</code> is simple and effective.</p> <p>Arbitrary callback functions on callback receivers allows to implement different behaviours to flash loans on callback receivers without the need for encoding a function router using the <code>data</code> argument. A function call type is 24 bytes of which the first 20 bytes are the target address and the last 4 bytes are the function signature.</p> <p>The <code>amount + fee</code> are pushed to the <code>payment receiver</code> to allow for the segregation of asset and control flows. While a "pull" architecture is more prevalent, "push" architectures are also common. For those cases where the <code>lender</code> can't implement a "push" architecture, a simple wrapper contract can offer this proposal's external interface, while using liquidity from the <code>lender</code> using a "pull" architecture.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is a successor of <a href="https://wg-eips.ritovision.com/3156/">ERC-3156</a>. While not directly backwards compatible, a wrapper contract offering this proposal's external interface with liquidity obtained from an ERC-3156 flash <code>lender</code> is trivial to implement.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="verification-of-callback-arguments">Verification of callback arguments</h3> <p>The arguments of the flash loan callbacks are expected to reflect the conditions of the flash loan, but cannot be trusted unconditionally. They can be divided in two groups, that require different checks before they can be trusted to be genuine.</p> <ol> <li>No arguments can be assumed to be genuine without some kind of verification. <code>initiator</code>, <code>asset</code> and <code>amount</code> refer to a past transaction that might not have happened if the caller of the callback decides to lie. <code>fee</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>asset</code>, <code>amount</code> and <code>fee</code> are genuine a reasonable pattern is to verify that the callback caller is in a whitelist of verified flash lenders. Since often the caller of <code>flash</code> will also be receiving the callback this will be trivial. In all other cases flash lenders will need to be approved if the arguments in the callback are to be trusted.</li> <li>To trust that the value of <code>data</code> is genuine, in addition to the check in point 1, it is recommended to verify that the <code>initiator</code> belongs to a group 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">Automatic approvals</h4> <p>Any <code>receiver</code> that repays the <code>amount</code> and <code>fee</code> received as arguments needs to include in the callback a mechanism to verify that the initiator and <code>lender</code> are trusted.</p> <p>Alternatively, the callback receiver can implement permissioned functions that set state variables indicating that a flash loan has been initiated and what to expect as <code>amount</code> and <code>fee</code>.</p> <p>Alternatively, the callback receiver can verify that <code>amount</code> was received by the <code>loanReceiver</code> and use its own heuristics to determine if a <code>fee</code> is fair and the loan repaid, or the transaction reverted.</p> <h3 id="flash-minting-external-security-considerations">Flash minting external security considerations</h3> <p>The typical quantum of assets involved in flash mint transactions will give rise to new innovative attack vectors.</p> <h4 id="spot-oracle-manipulation">Spot Oracle Manipulation</h4> <p>The supply of a flash-mintable asset can be easily manipulated, so oracles that take the supply of the flash-mintable asset into account must either discount amounts that were flash-minted, produce data that is averaged over time, or find some other solution to the varying supply.</p> <h4 id="arithmetic-overflow-and-underflow">Arithmetic Overflow and Underflow</h4> <p>If the flash mint provider does not place any limits on the amount of flash mintable assets in a transaction, then anyone can flash mint $2^256-1$ amount of assets.</p> <p>The protocols on the receiving end of the flash mints will need to ensure their contracts can handle this, either by using a compiler that embeds overflow protection in the smart contract bytecode, or by setting explicit checks.</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="treasury-draining">Treasury Draining</h4> <p>Assume a smart contract that flash lends its native asset. The same smart contract borrows from a third party when users burn the native asset. This pattern would be used to aggregate in the smart contract the collateralized debt of several users into a single account in the third party. The flash mint could be used to cause the <code>lender</code> to borrow to its limit, and then pushing interest rates in the underlying <code>lender</code>, liquidate the flash <code>lender</code>:</p> <ol> <li>Flash mint from <code>lender</code> a very large amount of FOO.</li> <li>Redeem FOO for BAR, causing <code>lender</code> to borrow from <code>underwriter</code> all the way to its borrowing limit.</li> <li>Trigger a debt rate increase in <code>underwriter</code>, making <code>lender</code> undercollateralized.</li> <li>Liquidate the <code>lender</code> for profit.</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> 2023-07-23T00:00:00+00:00 2026-02-11T14:48:25+00:00 Mengshi Zhanghttps://github.com/MengshiZhang Zihao Chenhttps://github.com/zihaoccc https://wg-eips.ritovision.com/7406/

An universally accepted multi-namespace registry with mapping structures on the Ethereum

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a universally accepted description for onchain registry entries with support for multi-namespaces, where each entry is structured as a mapping type. The multi-namespace registry enables the storage of a collection of key-value mappings within the blockchain, serving as a definitive source of information with a traceable history of changes. These mapping records act as pointers combined with onchain assets, offering enhanced versatility in various use cases by encapsulating extensive details. The proposed solution introduces a general mapping data structure that is flexible enough to support and be compatible with different situations, providing a more scalable and powerful alternative to current ENS-like registries.</p> <h2 id="motivation">Motivation</h2> <p>Blockchain-based registries are fundamental components for decentralized applications, enabling the storage and retrieval of essential information. Existing solutions, like the ENS registry, serve specific use cases but may lack the necessary flexibility to accommodate more complex scenarios. The need for a more general mapping data structure with multi-namespace support arises to empower developers with a single registry capable of handling diverse use cases efficiently.</p> <p>The proposed multi-namespace registry offers several key advantages:</p> <ul> <li><strong>Versatility</strong>: Developers can define and manage multiple namespaces, each with its distinct set of keys, allowing for more granular control and organization of data. For instance, single same key can derive as different pointers to various values based on difference namespaces, which a namespace can be specified as a session type, if this registry stores sessions, or short URL -&gt; full URL mapping is registry stores such type of data.</li> <li><strong>Traceable History</strong>: By leveraging multi-namespace capabilities, the registry can support entry versioning by using multi-namespace distinct as version number, enabling tracking of data change history, reverting data, or data tombstoning. This facilitates data management and governance within a single contract.</li> <li><strong>Enhanced Compatibility</strong>: The proposed structure is designed to be compatible with various use cases beyond the scope of traditional ENS-like registries, promoting its adoption in diverse decentralized applications.</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="registry-specification"><strong>Registry specification</strong></h3> <p>The multi namespace registry contract exposes the following functions:</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"> owner</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> key</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> <ul> <li>Returns the owner of the specified <strong>key</strong> under the given <strong>namespace</strong>.</li> </ul> <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"> resolver</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> key</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> <ul> <li>Returns the resolver address for the specified <strong>key</strong> under the given <strong>namespace</strong>.</li> </ul> <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"> setOwner</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> key</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> newOwner</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <ul> <li>Transfers ownership of the <strong>key</strong> under the specified <strong>namespace</strong> to another owner. This function may only be called by the current owner of the <strong>key</strong> under a specific <strong>namespace</strong>. The same <strong>key</strong> under different <strong>namespaces</strong> may have different owners. A successful call to this function logs the event <strong>Transfer(bytes32 namespace, bytes32 key, address newOwner)</strong>.</li> </ul> <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"> createNamespace</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> namespace</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <ul> <li>Create a new <strong>namespace</strong> such as a new version or a new type of protocol in current registry. A successful call to this function logs the event <strong>NewNamespace(bytes32 namespace)</strong>.</li> </ul> <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"> setResolver</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> key</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> newResolver</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <ul> <li>Sets the resolver address for the <strong>key</strong> under the given <strong>namespace</strong>. This function may only be called by the owner of the key under a specific <strong>namespace</strong>. The same key under different namespaces may have different resolvers. A successful call to this function logs the event <strong>NewResolver(bytes32 namespace, bytes32 key, address newResolver)</strong>.</li> </ul> <h3 id="resolver-specification"><strong>Resolver specification</strong></h3> <p>The multi-namespace resolver contract can utilize the same specification as defined in <a href="https://wg-eips.ritovision.com/137/">ERC-137</a>.</p> <h2 id="rationale">Rationale</h2> <p>By supporting multiple namespaces, the registry caters to various use cases, including but not limited to identity management, session management, record tracking, and decentralized content publishing. This flexibility enables developers to design and implement more complex decentralized applications with ease.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As this EIP introduces a new feature and does not modify any existing behaviors, there are no backwards compatibility issues.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="appendix-a-registry-implementation"><em>Appendix A: Registry Implementation</em></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.12</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC7406Interface.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"> ERC7406</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Record</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> owner</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> }</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"> A map is used to record namespace existence</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span>byte32</span><span class="z-keyword">=&gt;</span><span class="z-support">uint</span><span>)</span><span> namespaces</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">bytes32</span><span class="z-keyword">=&gt;</span><span>Record</span><span>)</span><span>)</span><span> records</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"> NewOwner</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> namespace</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> key</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 class="z-storage z-type"> event</span><span class="z-entity z-name"> Transfer</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> namespace</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> key</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 class="z-storage z-type"> event</span><span class="z-entity z-name"> NewResolver</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> namespace</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> key</span><span>, </span><span class="z-support">address</span><span class="z-variable"> resolver</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> NewNamespace</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> namespace</span><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"> only_owner</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> key</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>records</span><span>[</span><span>namespace</span><span>]</span><span>[</span><span>key</span><span>]</span><span>.</span><span>owner </span><span class="z-keyword">!=</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span class="z-keyword"> throw</span><span>;</span></span> <span class="giallo-l"><span class="z-constant"> _</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"> only_approver</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>records</span><span>[</span><span class="z-constant">0</span><span>]</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span>owner </span><span class="z-keyword">!=</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span class="z-keyword"> throw</span><span>;</span></span> <span class="giallo-l"><span class="z-constant"> _</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"> ERC7406</span><span>(</span><span class="z-support">address</span><span class="z-variable"> approver</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> records</span><span>[</span><span class="z-constant">0</span><span>]</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span>owner </span><span class="z-keyword">=</span><span> approver</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"> owner</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> key</span><span>)</span><span class="z-entity z-name"> constant</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> records</span><span>[</span><span>namespace</span><span>]</span><span>[</span><span>key</span><span>]</span><span>.</span><span>owner</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"> createNamespace</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> namespace</span><span>)</span><span class="z-entity z-name"> only_approver</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>status </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span class="z-keyword"> throw</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> NewNamespace</span><span>(</span><span>namespace</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>namespaces</span><span>[</span><span>namespace</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>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> namespaces</span><span>[</span><span>namespace</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 class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> resolver</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> key</span><span>)</span><span class="z-entity z-name"> constant</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>namespaces</span><span>[</span><span>namespace</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>)</span><span class="z-keyword"> throw</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> records</span><span>[</span><span>namespace</span><span>]</span><span>[</span><span>key</span><span>]</span><span>.</span><span>resolver</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"> setOwner</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> key</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> owner</span><span>)</span><span class="z-entity z-name"> only_owner</span><span>(</span><span class="z-entity z-name">namespace</span><span>,</span><span class="z-entity z-name"> key</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> Transfer</span><span>(</span><span>key</span><span>,</span><span> namespace</span><span>,</span><span> owner</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> records</span><span>[</span><span>namespace</span><span>]</span><span>[</span><span>key</span><span>]</span><span>.</span><span>owner </span><span class="z-keyword">=</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-storage z-type"> function</span><span class="z-entity z-name"> setResolver</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> key</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> resolver</span><span>)</span><span class="z-entity z-name"> only_approver</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>namespaces</span><span>[</span><span>namespace</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-variable z-language"> this</span><span>.</span><span class="z-entity z-name">createNamespace</span><span>(</span><span>namespace</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"> NewResolver</span><span>(</span><span>key</span><span>,</span><span> namespace</span><span>,</span><span> resolver</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> records</span><span>[</span><span>namespace</span><span>]</span><span>[</span><span>key</span><span>]</span><span>.</span><span>resolver </span><span class="z-keyword">=</span><span> resolver</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 proposed multi-namespace registry introduces several security considerations due to its ability to manage various namespaces and access controls. Thorough testing, auditing, and peer reviews will be conducted to identify and mitigate potential attack vectors and vulnerabilities. Security-conscious developers are encouraged to contribute to the audit process.</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-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ernani São Thiagohttps://github.com/ernanirst Daniel Limahttps://github.com/karacurt https://wg-eips.ritovision.com/7432/

Role Management for NFTs. Enables accounts to share the utility of NFTs via expirable role assignments.

<h2 id="abstract">Abstract</h2> <p>This standard introduces role management for NFTs. Each role assignment is associated with a single NFT and expires automatically at a given timestamp. Roles are defined as <code>bytes32</code> and feature a custom <code>data</code> field of arbitrary size to allow customization.</p> <h2 id="motivation">Motivation</h2> <p>The NFT Roles interface aims to establish a standard for role management in NFTs. Tracking on-chain roles enables decentralized applications (dApps) to implement access control for privileged actions, e.g., minting tokens with a role (airdrop claim rights).</p> <p>NFT roles can be deeply integrated with dApps to create a utility-sharing mechanism. A good example is in digital real estate. A user can create a digital property NFT and grant a <code>keccak256("PropertyManager()")</code> role to another user, allowing them to delegate specific utility without compromising ownership. The same user could also grant a <code>keccak256("PropertyTenant(uint256)")</code> role to other users, allowing the recipient to access and interact with the digital property.</p> <p>There are also interesting use cases in decentralized finance (DeFi). Insurance policies could be issued as NFTs, and the beneficiaries, insured, and insurer could all be on-chain roles tracked using this standard.</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> <p>Compliant contracts 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-storage z-type"> @title</span><span class="z-comment"> ERC-7432 Non-Fungible Token Roles</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-7432</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 0xd00ca5cf.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7432</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-storage z-type"> struct</span><span class="z-entity z-name"> Role</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> roleId</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> tokenId</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"> uint64</span><span> expirationDate</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> revocable</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-comment"> Events *</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"> Emitted when an NFT is locked (deposited or frozen).</span></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"> The owner 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"> _tokenAddress</span><span class="z-comment"> The 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"> The token identifier.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenLocked</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"> _tokenAddress</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"> Emitted when a role is granted.</span></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"> The 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"> The token identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _roleId</span><span class="z-comment"> The role identifier.</span></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"> The user assigning the role.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _recipient</span><span class="z-comment"> The user receiving the role.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _expirationDate</span><span class="z-comment"> The expiration date of the role.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _revocable</span><span class="z-comment"> Whether the role is revocable or not.</span></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"> Any additional data about the role.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RoleGranted</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"> bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _roleId</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"> address</span><span class="z-variable"> _recipient</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> _expirationDate</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> _revocable</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"> @notice</span><span class="z-comment"> Emitted when a role is 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"> _tokenAddress</span><span class="z-comment"> The 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"> The token identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _roleId</span><span class="z-comment"> The role identifier.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RoleRevoked</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _tokenAddress</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-storage z-type"> indexed</span><span class="z-variable"> _roleId</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"> Emitted when an NFT is unlocked (withdrawn or unfrozen).</span></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"> The original owner 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"> _tokenAddress</span><span class="z-comment"> The 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"> The token identifier.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenUnlocked</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"> _tokenAddress</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Emitted when a user is approved to manage roles on behalf of another 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"> _tokenAddress</span><span class="z-comment"> The 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"> _operator</span><span class="z-comment"> The user approved to grant and revoke roles.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _isApproved</span><span class="z-comment"> The approval status.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RoleApprovalForAll</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _tokenAddress</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-storage z-type"> indexed</span><span class="z-variable"> _isApproved</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> External Functions *</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"> Grants a role 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 sender is not approved or the 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"> _role</span><span class="z-comment"> The role attributes.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> grantRole</span><span>(</span><span class="z-storage z-type">Role</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _role</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"> Revokes a role from 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 sender is not approved or the original 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"> The 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"> The token identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _roleId</span><span class="z-comment"> The role identifier.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeRole</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"> _tokenId</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _roleId</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"> Unlocks NFT (transfer back to original owner or unfreeze it).</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 sender is not approved or the original 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"> The 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"> The token identifier.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unlockToken</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"> _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 class="z-storage z-type"> @notice</span><span class="z-comment"> Approves operator to grant and revoke roles on behalf of another 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"> _tokenAddress</span><span class="z-comment"> The 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"> _operator</span><span class="z-comment"> The user approved to grant and revoke roles.</span></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 approval status.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setRoleApprovalForAll</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"> 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 class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> View Functions *</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"> Retrieves the original owner 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"> _tokenAddress</span><span class="z-comment"> The 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"> The token identifier.</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"> owner_</span><span class="z-comment"> 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"> ownerOf</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"> _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"> owner_</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"> Retrieves the recipient of an NFT role.</span></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"> The 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"> The token identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _roleId</span><span class="z-comment"> The role identifier.</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"> recipient_</span><span class="z-comment"> The user that received the role.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> recipientOf</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _tokenAddress</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"> bytes32</span><span class="z-variable z-parameter z-function"> _roleId</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">address</span><span class="z-variable"> recipient_</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"> Retrieves the custom data of a role assignment.</span></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"> The 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"> The token identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _roleId</span><span class="z-comment"> The role identifier.</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"> data_</span><span class="z-comment"> The custom data of the role.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> roleData</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _tokenAddress</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"> bytes32</span><span class="z-variable z-parameter z-function"> _roleId</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">bytes</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieves the expiration date of a role assignment.</span></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"> The 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"> The token identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _roleId</span><span class="z-comment"> The role identifier.</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"> expirationDate_</span><span class="z-comment"> The expiration date of the role.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> roleExpirationDate</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _tokenAddress</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"> bytes32</span><span class="z-variable z-parameter z-function"> _roleId</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">uint64</span><span class="z-variable"> expirationDate_</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"> Verifies whether the role is revocable.</span></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"> The 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"> The token identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _roleId</span><span class="z-comment"> The role identifier.</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"> revocable_</span><span class="z-comment"> Whether the role is revocable.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isRoleRevocable</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _tokenAddress</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"> bytes32</span><span class="z-variable z-parameter z-function"> _roleId</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 class="z-variable"> revocable_</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"> Verifies if the owner approved the 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"> _tokenAddress</span><span class="z-comment"> The 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"> The user that approved the 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"> The user that can grant and revoke roles.</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 operator is approved.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isRoleApprovedForAll</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _tokenAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _owner</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 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></span></code></pre><h3 id="metadata-extension">Metadata Extension</h3> <p>The Roles Metadata extension extends the traditional JSON-based metadata schema of NFTs. Therefore, DApps supporting this feature MUST also implement the metadata extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. This extension is <strong>optional</strong> and allows developers to provide additional information for roles.</p> <p>Updated Metadata Schema:</p> <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-comment"> /**</span><span class="z-comment"> Existing NFT Metadata *</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><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>: </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-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">object</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">properties</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> {</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></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">description</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">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-punctuation z-definition z-string"> &quot;</span><span class="z-string">description</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">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></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">description</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">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-punctuation z-definition z-string"> &quot;</span><span class="z-string">image</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">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></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">description</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">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></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"> Additional fields for Roles *</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">roles</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">id</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">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">bytes32</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">description</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">Identifies the role</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-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-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></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">description</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">Human-readable name of the role</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">description</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">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></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">description</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">Describes the role</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">inputs</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> {</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></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">description</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">Human-readable name of the argument</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-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></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></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">description</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">Solidity type, e.g., uint256 or 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 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>The following JSON is an example of <a href="https://wg-eips.ritovision.com/7432/">ERC-7432</a> Metadata:</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-comment"> //</span><span class="z-comment"> ... Existing NFT Metadata</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">roles</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-comment"> //</span><span class="z-comment"> keccak256(&quot;PropertyManager()&quot;)</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x76be0ffb73d8cd9e8fa76c28632ebbc3865a8ec7a0b6acab6ac589a1c88dd301</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">Property Manager</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">description</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 manager of the property is responsible for furnishing it and ensuring its good condition.</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">inputs</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></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"> keccak256(&quot;PropertyTenant(uint256)&quot;)</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x17dfc8ea82661b71bd62ce0bd9db3858dd8f3e8ab9799d6ab468ec64f1be21a5</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">Property Tenant</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">description</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 tenant of the property is responsible for paying the rent and keeping the property in good condition.</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">inputs</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">rent</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 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>The <code>roles</code> array properties are SUGGESTED, and developers should add any other relevant information as necessary (e.g., an image for the role). It's also important to highlight the importance of the <code>inputs</code> property. This field describes the parameters that should be encoded and passed to the <code>grantRole</code> function. It's RECOMMENDED to use the properties <code>type</code> and <code>components</code> defined on the Solidity ABI Specification, where <code>type</code> is the canonical type of the parameter, and <code>components</code> is used for complex tuple types.</p> <h3 id="caveats">Caveats</h3> <ul> <li>Compliant contracts MUST implement the <code>IERC7432</code> interface.</li> <li>A role is represented by a <code>bytes32</code>, and it's RECOMMENDED to use the <code>keccak256</code> of the role's name with its inputs: <code>bytes32 roleId = keccak256("RoleName(input_type)")</code>.</li> <li>The <code>grantRole</code> function MUST revert if the <code>expirationDate</code> is in the past or if the <code>msg.sender</code> is not approved to grant roles on behalf of the NFT owner. It MAY be implemented as <code>public</code> or <code>external</code>.</li> <li>In addition to emitting the <code>RoleGranted</code> event, the <code>grantRole</code> function MUST emit a <code>TokenLocked</code> event if the token is frozen or transferred to an escrow account.</li> <li>The <code>revokeRole</code> function MUST revert if the <code>msg.sender</code> is not approved to revoke roles on behalf of the original NFT owner or the <code>recipient</code>. It MAY be implemented as <code>public</code> or <code>external</code>.</li> <li>If <code>revocable</code> is false, only the <code>recipient</code> can revoke the role. If <code>revocable</code> is true, both the <code>recipient</code> and the original NFT owner can revoke the role.</li> <li>The <code>unlockToken</code> function MUST revert if the <code>msg.sender</code> is not approved, or if there is at least one non-revocable role not expired. It MAY be implemented as <code>public</code> or <code>external</code>.</li> <li>The <code>setRoleApprovalForAll</code> function MAY be implemented as <code>public</code> or <code>external</code>.</li> <li>The <code>ownerOf</code> function MAY be implemented as <code>pure</code> or <code>view</code>, and MUST return the address of the original owner of the NFT.</li> <li>The <code>recipientOf</code> function MAY be implemented as <code>pure</code> or <code>view</code>, and MUST return the address of the account that received the role.</li> <li>The <code>roleData</code> function MAY be implemented as <code>pure</code> or <code>view</code>, and MUST return the encoded data passed to the <code>grantRole</code> function.</li> <li>The <code>roleExpirationDate</code> function MAY be implemented as <code>pure</code> or <code>view</code>, and MUST return the expiration date of a given role.</li> <li>The <code>isRoleRevocable</code> function MAY be implemented as <code>pure</code> or <code>view</code>, and MUST return whether the role is revocable.</li> <li>The <code>isRoleApprovedForAll</code> function MAY be implemented as <code>pure</code> or <code>view</code>, and SHOULD only return <code>true</code> if the <code>_operator</code> is approved to grant and revoke roles on behalf of the original NFT owner.</li> <li>Compliant contracts SHOULD implement <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>.</li> </ul> <h2 id="rationale">Rationale</h2> <p><a href="https://wg-eips.ritovision.com/7432/">ERC-7432</a> IS NOT an extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. The main reason behind this decision is to enable it to be implemented externally or on the same contract as the NFT, allowing dApps to implement roles with immutable assets. This standard covers many crucial features, such as automatic expiration and custom data, but perhaps the most important one is its flexibility in implementation. ERC-7432 can be implemented in many ways, and for this reason, the neutral term "lock" is employed. This term can refer to an NFT being frozen (preventing transfers until roles expire) or deposited in an escrow contract. Developers should decide which implementation to use based on their use cases.</p> <h3 id="automatic-expiration">Automatic Expiration</h3> <p>Automatic expiration is implemented via the <code>grantRole</code> and <code>roleExpirationDate</code> functions. <code>grantRole</code> is responsible for setting the expiration date, and <code>roleExpirationDate</code> allow developers to check whether the role is expired. Since <code>uint256</code> is not natively supported by most programming languages, dates are represented as <code>uint64</code> on this standard. The maximum UNIX timestamp represented by a <code>uint64</code> is about the year <code>584,942,417,355</code>, which should be enough to be considered "permanent". For this reason, it's recommended using <code>type(uint64).max</code> to support use cases that require a role never to expire.</p> <h3 id="revocable-roles">Revocable Roles</h3> <p>In certain scenarios, the original owner of the NFT may need to revoke a role before its expiration date, while in others, the recipient may require assurance that the role cannot be revoked. The <code>revocable</code> parameter was introduced to the <code>grantRole</code> function to specify whether a role can be revoked prematurely, enabling the standard to support both use cases.</p> <p>Regardless of the value of <code>revocable</code>, it's recommended always to enable the <code>recipient</code> to revoke roles, allowing them to eliminate undesirable assignments.</p> <h3 id="custom-data">Custom Data</h3> <p>DApps can customize roles using the <code>data</code> parameter of the <code>grantRole</code> function. <code>data</code> is implemented using the generic type <code>bytes</code> to enable dApps to encode any role-specific information when granting a role. The custom data is retrievable using the <code>roleData</code> function and is emitted with the <code>RoleGranted</code> event. With this approach, developers can integrate this information into their applications, both on-chain and off-chain.</p> <h3 id="role-approval">Role Approval</h3> <p>Similar to <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, this standard enable other accounts to manage roles on behalf of the NFT owner. This functionality was introduced to allow third-parties to interact with ERC-7432 without requiring NFT ownership. Compliant contracts MUST implement the functions <code>setRoleApprovalForAll</code> and <code>isRoleApprovedForAll</code> to deliver this feature.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>On all functions and events, the standard requires both the <code>tokenAddress</code> and <code>tokenId</code> to be provided. This requirement enables dApps to use a standalone <a href="https://wg-eips.ritovision.com/7432/">ERC-7432</a> contract as the authoritative source for the roles of immutable NFTs.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/7432/./assets/ERC7432.sol">ERC-7432.sol</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Developers integrating the Non-Fungible Token Roles interface should consider the following on their implementations:</p> <ul> <li>Ensure proper access controls are in place to prevent unauthorized role assignments or revocations.</li> <li>Take into account potential attack vectors such as reentrancy and ensure appropriate safeguards are in place.</li> <li>Approved accounts should be able to manage roles on behalf of another user. However, ensure that the NFT can only be transferred to an escrow contract, and back to its original owner (not to the approved account).</li> <li>Always check the expiration date before allowing users to access the utility of an NFT.</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> 2023-07-09T00:00:00+00:00 2026-02-11T14:48:26+00:00 Ko Fujimurahttps://github.com/kofujimura https://wg-eips.ritovision.com/7303/

Access control scheme based on token ownership.

<h2 id="abstract">Abstract</h2> <p>This ERC introduces an access control scheme termed Token-Controlled Token Circulation (TCTC). By representing the privileges associated with a role as an <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> token (referred to as a <code>control token</code>), the processes of granting or revoking a role can be facilitated through the minting or burning of the corresponding <code>control token</code>.</p> <h2 id="motivation">Motivation</h2> <p>There are numerous methods to implement access control for privileged actions. A commonly utilized pattern is "role-based" access control as specified in <a href="https://wg-eips.ritovision.com/5982/">ERC-5982</a>. This method, however, necessitates the use of an off-chain management tool to grant or revoke required roles through its interface. Additionally, as many wallets lack a user interface that displays the privileges granted by a role, users are often unable to comprehend the status of their privileges through the wallet.</p> <h3 id="use-cases">Use Cases</h3> <p>This ERC is applicable in many scenarios where role-based access control as described in <a href="https://wg-eips.ritovision.com/5982/">ERC-5982</a> is used. Specific use cases include:</p> <p><strong>Mint/Burn Permission:</strong> In applications that circulate items such as tickets, coupons, membership cards, and site access rights as tokens, it is necessary to provide the system administrator with the authority to mint or burn these tokens. These permissions can be realized as <code>control tokens</code> in this scheme.</p> <p><strong>Transfer Permission:</strong> In some situations within these applications, it may be desirable to limit the ability to transfer tokens to specific agencies. In these cases, an agency certificate is issued as a <code>control token</code>. The ownership of this <code>control token</code> then provides the means to regulate token transfers.</p> <p><strong>Address Verification:</strong> Many applications require address verification to prevent errors in the recipient's address when minting or transferring target tokens. A <code>control token</code> is issued as proof of address verification to users, which is required by the recipient when a mint or transfer transaction is executed, thus preventing misdeliveries. In some instances, this <code>control token</code> for address verification may be issued by a government agency or specific company after an identity verification process.</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>Smart contracts implementing the <a href="https://wg-eips.ritovision.com/7303/">ERC-7303</a> standard MUST represent the privilege required by the role as an ERC-721 token or ERC-1155 token. The tokens that represent privileges are called <code>control tokens</code> in this ERC. The <code>control token</code> can be any type of token, and its transactions may be recursively controlled by another <code>control token</code>.</li> <li>To associate the required <code>control token</code> with the role, the address of the previously deployed contract for the <code>control token</code> MUST be used.</li> <li>To ascertain whether an account possesses the necessary role, it SHOULD be confirmed that the balance of the <code>control token</code> exceeds 0, utilizing the <code>balanceOf</code> method defined in ERC-721 or ERC-1155. Note that the <code>typeId</code> must be specified if an ERC-1155 token is used for the <code>balanceOf</code> method.</li> <li>To grant a role to an account, a <code>control token</code> representing the privilege SHOULD be minted to the account using <code>safeMint</code> method defined in <a href="https://wg-eips.ritovision.com/5679/">ERC-5679</a>.</li> <li>To revoke a role from an account, the <code>control token</code> representing the privilege SHOULD be burned using the <code>burn</code> method defined in ERC-5679.</li> <li>A role in a compliant smart contract is represented in the format of <code>bytes32</code>. It's RECOMMENDED the value of such role is computed as a <code>keccak256</code> hash of a string of the role name, in this format: <code>bytes32 role = keccak256("&lt;role_name&gt;")</code> such as <code>bytes32 role = keccak256("MINTER")</code>.</li> </ol> <h2 id="rationale">Rationale</h2> <p>The choice to utilize ERC-721 or ERC-1155 token as the control token for privileges enhances visibility of such privileges within wallets, thus simplifying privilege management for users.</p> <p>Generally, when realizing privileges as tokens, specifications like Soulbound Token (e.g., <a href="https://wg-eips.ritovision.com/5192/">ERC-5192</a>) are used. Given that ERC-5192 inherits from ERC-721, this ERC has choiced ERC-721 as the requirement for the control token.</p> <p>Employing a transferable control token can cater to scenarios where role delegation is necessary. For example, when an authority within an organization is replaced or on vacation, the ability to transfer their privileges to another member becomes possible. The decision to designate the control token as transferable will depend on the specific needs of the application.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC is designed to be compatible for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>, and <a href="https://wg-eips.ritovision.com/5679/">ERC-5679</a> respectively.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>ERC-7303 provides a modifier to facilitate the implementation of TCTC access control in applications.　This modifier checks if an account possesses the necessary role. ERC-7303 also includes a function that grants a specific role to a designated account.</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: Apache-2.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.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/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/token/ERC1155/ERC1155.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"> ERC7303</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> ERC721Token</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> contractId</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"> ERC1155Token</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> contractId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> typeId</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"> mapping</span><span> (</span><span class="z-support">bytes32</span><span class="z-keyword"> =&gt;</span><span> ERC721Token</span><span>[</span><span>]</span><span>)</span><span class="z-storage z-type"> private</span><span> _ERC721_Contracts</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> ERC1155Token</span><span>[</span><span>]</span><span>)</span><span class="z-storage z-type"> private</span><span> _ERC1155_Contracts</span><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"> onlyHasToken</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> role</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> account</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_checkHasToken</span><span>(</span><span>role</span><span>,</span><span> account</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC7303: not has a required token&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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Grant a role to user who owns a control token specified by the ERC-721 contractId. </span></span> <span class="giallo-l"><span class="z-comment"> * Multiple calls are allowed, in this case the user must own at least one of the specified 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"> role</span><span class="z-comment"> byte32 The role which you want to grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> contractId</span><span class="z-comment"> address The address of contractId of which token the user required to own.</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"> _grantRoleByERC721</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> role</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> contractId</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> <span class="giallo-l"><span class="z-entity z-name"> IERC165</span><span>(</span><span>contractId</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>IERC721</span><span>)</span><span>.</span><span>interfaceId</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;ERC7303: provided contract does not support ERC721 interface&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> _ERC721_Contracts</span><span>[</span><span>role</span><span>]</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-entity z-name">ERC721Token</span><span>(</span><span>contractId</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">@notice</span><span class="z-comment"> Grant a role to user who owns a control token specified by the ERC-1155 contractId. </span></span> <span class="giallo-l"><span class="z-comment"> * Multiple calls are allowed, in this case the user must own at least one of the specified 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"> role</span><span class="z-comment"> byte32 The role which you want to grant.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> contractId</span><span class="z-comment"> address The address of contractId of which token the user required to own.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> typeId</span><span class="z-comment"> uint256 The token type id that the user required to own.</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"> _grantRoleByERC1155</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> role</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> contractId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> typeId</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> <span class="giallo-l"><span class="z-entity z-name"> IERC165</span><span>(</span><span>contractId</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>IERC1155</span><span>)</span><span>.</span><span>interfaceId</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;ERC7303: provided contract does not support ERC1155 interface&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> _ERC1155_Contracts</span><span>[</span><span>role</span><span>]</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-entity z-name">ERC1155Token</span><span>(</span><span>contractId</span><span>,</span><span> typeId</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"> _checkHasToken</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> role</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> account</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> ERC721Token</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> ERC721Tokens </span><span class="z-keyword">=</span><span> _ERC721_Contracts</span><span>[</span><span>role</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> ERC721Tokens</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-keyword"> if</span><span> (</span><span class="z-entity z-name">IERC721</span><span>(</span><span>ERC721Tokens</span><span>[</span><span>i</span><span>]</span><span>.</span><span>contractId</span><span>)</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>(</span><span>account</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span>)</span><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> ERC1155Token</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> ERC1155Tokens </span><span class="z-keyword">=</span><span> _ERC1155_Contracts</span><span>[</span><span>role</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> ERC1155Tokens</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-keyword"> if</span><span> (</span><span class="z-entity z-name">IERC1155</span><span>(</span><span>ERC1155Tokens</span><span>[</span><span>i</span><span>]</span><span>.</span><span>contractId</span><span>)</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>(</span><span>account</span><span>,</span><span> ERC1155Tokens</span><span>[</span><span>i</span><span>]</span><span>.</span><span>typeId</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span>)</span><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-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>The following is a simple example of utilizing <code>ERC7303</code> within an ERC-721 token to define "minter" and "burner" roles. Accounts possessing these roles are allowed to create new tokens and destroy existing tokens, facilitated by specifying ERC-721 or ERC-1155 control tokens:</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: Apache-2.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.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/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/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;./ERC7303.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"> MyToken</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">ERC7303</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> MINTER_ROLE </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;MINTER_ROLE&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> BURNER_ROLE </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;BURNER_ROLE&quot;</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>)</span><span class="z-entity z-name"> ERC721</span><span>(</span><span>&quot;MyToken&quot;, &quot;MTK&quot;) </span><span>{</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Specifies the deployed contractId of ERC721 control token.</span></span> <span class="giallo-l"><span class="z-entity z-name"> _grantRoleByERC721</span><span>(</span><span>MINTER_ROLE</span><span>,</span><span class="z-constant"> 0</span><span>x</span><span>.</span><span>.</span><span>.</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _grantRoleByERC721</span><span>(</span><span>BURNER_ROLE</span><span>,</span><span class="z-constant"> 0</span><span>x</span><span>.</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-comment"> Specifies the deployed contractId and typeId of ERC1155 control token.</span></span> <span class="giallo-l"><span class="z-entity z-name"> _grantRoleByERC1155</span><span>(</span><span>MINTER_ROLE</span><span>,</span><span class="z-constant"> 0</span><span>x</span><span>.</span><span>.</span><span>.</span><span>,</span><span> .</span><span>.</span><span>.</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _grantRoleByERC1155</span><span>(</span><span>BURNER_ROLE</span><span>,</span><span class="z-constant"> 0</span><span>x</span><span>.</span><span>.</span><span>.</span><span>,</span><span> .</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"> safeMint</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> <span class="giallo-l"><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyHasToken</span><span>(</span><span class="z-entity z-name">MINTER_ROLE</span><span>,</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 class="z-entity z-name"> _safeMint</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"> burn</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 class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyHasToken</span><span>(</span><span class="z-entity z-name">BURNER_ROLE</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 class="z-entity z-name"> _burn</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>The security of tokens subject to circulation depends significantly on the security of the control tokens. Careful consideration must be given to the settings regarding the administrative privileges, mint/transfer/burn permissions, and the possibility of contract updates of control tokens.</p> <p>In particular, making control tokens transferable allows for flexible operations, such as the temporary delegation of administrative rights. However, it also raises the possibility that the rights to circulate tokens could fall into the hands of inappropriate third parties. Therefore, control tokens should generally be made non-transferable. If control tokens are to be made transferable, at the very least, the authority to burn these tokens should be retained by a trusted administrator.</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-04T00:00:00+00:00 2026-02-11T14:48:25+00:00 Yohei Nishikubohttps://github.com/yoheinishikubo https://wg-eips.ritovision.com/7280/

Let NFT metadata have a feature equivalent to JSON-LD to be semantic.

<h2 id="abstract">Abstract</h2> <p>This proposal expands the metadata format for Non-Fungible Tokens (<a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>, <a href="https://wg-eips.ritovision.com/3525/">ERC-3525</a>, and others), adding support for linked data like JSON-LD format. The additional data is stored under the linked_data key in the metadata JSON.</p> <h2 id="motivation">Motivation</h2> <p>The existing metadata format for Non-Fungible Tokens is limited and doesn't support the inclusion of structured and semantically meaningful data. By integrating JSON-LD (Linked Data), we can enhance the richness and interoperability of the metadata associated with NFTs.</p> <p>This allows for complex metadata structures that can link to external schemas and data, improving the contextual relevance and usability of NFTs across various applications.</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 JSON-LD based metadata is stored under a new <code>linked_data</code> key in the metadata JSON. The <code>linked_data</code> key is an array of objects, where each object contains two keys: <code>schema</code> and <code>data</code>.</p> <table><thead><tr><th>name</th><th>compliance level</th><th>type</th><th>description</th></tr></thead><tbody> <tr><td>schema</td><td>MUST</td><td>object</td><td>The schema of the linked data.</td></tr> <tr><td>data</td><td>MUST</td><td>object</td><td>The data of the linked data.</td></tr> </tbody></table> <h3 id="schema">Schema</h3> <table><thead><tr><th>name</th><th>compliance level</th><th>type</th><th>description</th></tr></thead><tbody> <tr><td>uri</td><td>MUST</td><td>string</td><td>The URI of the schema.</td></tr> <tr><td>name</td><td>MUST</td><td>string</td><td>The name of the schema.</td></tr> <tr><td>description</td><td>OPTIONAL</td><td>string</td><td>The description of the schema.</td></tr> </tbody></table> <h3 id="data">Data</h3> <table><thead><tr><th>name</th><th>compliance level</th><th>type</th><th>description</th></tr></thead><tbody> <tr><td>uri</td><td>MUST</td><td>string</td><td>The URI of the data.</td></tr> <tr><td>lang</td><td>OPTIONAL</td><td>string</td><td>The language of the data. IETF language tag like <code>en-US</code>.</td></tr> <tr><td>name</td><td>OPTIONAL</td><td>string</td><td>The name of the data.</td></tr> <tr><td>description</td><td>OPTIONAL</td><td>string</td><td>The description of the data.</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <p>For providing typical webpage for an NFT, it's much simple to include JSON-LD in HTML header tag with this extension. Just looking for JSON-LD compliant value's uri from <code>linked_data</code> array, fetch it and embed its content in HTML header tag. This means the minter of NFT can control the appearance in the search result of Google, for example. In more common case for interoperability, the NFT metadata can include any schema and data with this extension. This means the NFT metadata can be used as a data source for any application. With the schema, the implementation is much easier.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The proposed expansion to the NFT metadata format is backward compatible with existing implementations. NFTs that do not include the <code>linked_data</code> key will continue to function as before, and existing applications consuming NFT metadata will not be affected.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Here is an example metadata JSON demonstrating the new linked_data 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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">NFT 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">This NFT represents...</span><span class="z-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://example.org/images/nft.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">linked_data</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">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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">VideoObject</span><span class="z-punctuation z-definition z-string">&quot;</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://example.org/schemas/VideoObject.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">data</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://example.org/data/video1.json</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">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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">MusicRecording</span><span class="z-punctuation z-definition z-string">&quot;</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://example.org/schemas/MusicRecording.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">data</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://example.org/data/music1.json</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">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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">GoogleTravelImpactModel</span><span class="z-punctuation z-definition z-string">&quot;</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://example.org/schemas/GoogleTravelImpactModel.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">data</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://example.org/data/gtim1.json</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>In the example above, the NFT metadata contains three linked data objects, each with a different schema and data: First one. VideoObject data can be used as JSON-LD in HTML header tag and realize rich snippet in Google search result. Second one. MusicRecording data is based on a schema from <code>schema.org</code>. However this one cannot realize rich snippet. Third one. GoogleTravelImpactModel data is a dedicated schema for Google Travel Impact Model. The most important point is that any schema and data can be included with this standard like above.</p> <h3 id="sample-files">Sample files</h3> <ul> <li><a href="https://wg-eips.ritovision.com/7280/./assets/samples/schemas/VideoObject.json">VideoObject.json</a></li> <li><a href="https://wg-eips.ritovision.com/7280/./assets/samples/schemas/MusicRecording.json">MusicRecording.json</a></li> <li><a href="https://wg-eips.ritovision.com/7280/./assets/samples/schemas/GoogleTravelImpactModel.json">GoogleTravelImpactModel.json</a></li> <li><a href="https://wg-eips.ritovision.com/7280/./assets/samples/data/video1.json">video1.json</a></li> <li><a href="https://wg-eips.ritovision.com/7280/./assets/samples/data/music1.json">music1.json</a></li> <li><a href="https://wg-eips.ritovision.com/7280/./assets/samples/data/gtim1.json">gtim1.json</a></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>The proposed expansion does not introduce any additional security considerations beyond those already associated with NFTs and linked data. Implementations should adhere to best practices for secure handling and validation of metadata from external sources.</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-07-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Chris Chunghttps://github.com/0xpApaSmURf Raphael Roullethttps://github.com/ra-phael https://wg-eips.ritovision.com/7272/

A protocol for authorizing function calls from an off-chain service

<h2 id="abstract">Abstract</h2> <p>An Ethereum Access Token (EAT) is an <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> conformant, signed message, used by off-chain services to grant Ethereum accounts access to specific on-chain resources. EATs share similarities with JSON Web Tokens (JWTs); both are used for short-lived authorizations. However Ethereum Access Tokens are specifically designed to be verified on-chain and tailored to authorize smart contract function calls.</p> <h2 id="motivation">Motivation</h2> <p>While other proposals tackle authentication or authorization in a more narrow way, this specification allows developers to add a layer of access control to any function they create with minimal changes. It is best suited for use cases where end users should only be able to access specific on-chain resources themselves directly, by way of sending a transaction, provided they have been granted authorization by an off-chain service first. Examples of such scenarios include an off-chain verifier assessing eligibility requirements (e.g by verifying verifiable credentials) to mint a token or to interact with a smart contract that requires a certain compliance status. Therefore, this proposal enables off-chain systems to authenticate the controller of an Ethereum account in any way they want, before granting an authorization bound to said account.</p> <p>This specification is intended to improve interoperability in the Ethereum ecosystem, by providing a consistent machine-readable message format to achieve improved user experiences.</p> <p>EATs fill a void where access control requirements differ from current standard access control mechanisms (role-based access modifiers or checking that an address owns an NFT):</p> <ul> <li>Desired acccess is short-lived</li> <li>Criteria needs to be flexible/dynamic: updating the requirements for granting access doesn't require any update on chain</li> <li>When Soulbound or other on-chain token semantics are not desired. Using any kind of "on-chain registry" to grant authorization places a burden on the owner of such registry to keep it up-to-date at all time. Otherwise, someone might be wrongly granted access in the lapse of time where their on-chain status is incorrect. With EATs, on the contrary, users come to ask for an authorization which gives EAT issuers the opportunity to perform some checks and update their records before granting authorization. Additionally, relying purely on on-chain data comes with privacy concerns due to the public nature of most of current chains. When authorization needs to be granted based on sensitive or personally identifiable information, it is not recommended to store that information on-chain and perform a lookup. Ethereum Access Tokens provide an alternative which doesn't leak any PII on-chain.</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> <h3 id="overview">Overview</h3> <p>An example flow integrated in a DeFi application is the following:</p> <ol> <li>A user interacts with the DeFi's off-chain service, providing sufficient input for the off-chain service to ensure the user meets its criteria (for example, authenticates the user and/or make sure they possess valid credentials)</li> <li>If authorization is granted, an EAT is issued to the user</li> <li>The user then interacts with the gated smart contract function within the specified period of time passing the EAT as part of the transaction</li> <li>The EAT is verified on-chain</li> </ol> <p><img src="https://wg-eips.ritovision.com/7272/./assets/EAT_transaction_auth_flow.png" alt="Transaction authorization flow using an EAT" /></p> <p>An Ethereum Access Token MUST guarantee granular access control by binding it to specific parameters upon issuance. Then, on-chain EAT verification ensures that:</p> <ul> <li>The function being called is the expected one</li> <li>The function parameters are the expected ones</li> <li>The function caller is the expected one</li> <li>The function is being called in the authorized timeframe (i.e checking that the EAT is not expired)</li> <li>The smart contract being called is the expected one</li> <li>The authorization has been given by a valid issuer, i.e the EAT has been signed by one of the expected issuers</li> </ul> <h3 id="structure-of-an-ethereum-access-token">Structure of an Ethereum Access Token</h3> <p>An Ethereum Access Token is composed of a signature and expiry.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> uint8 v,</span></span> <span class="giallo-l"><span> bytes32 r,</span></span> <span class="giallo-l"><span> bytes32 s,</span></span> <span class="giallo-l"><span> uint256 expiry</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The signature is obtained using the typed structured data hashing and signing standard (EIP-712), signing over the following EAT payload:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>struct AccessToken {</span></span> <span class="giallo-l"><span> uint256 expiry;</span></span> <span class="giallo-l"><span> FunctionCall functionCall;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>struct FunctionCall {</span></span> <span class="giallo-l"><span> bytes4 functionSignature;</span></span> <span class="giallo-l"><span> address target;</span></span> <span class="giallo-l"><span> address caller;</span></span> <span class="giallo-l"><span> bytes parameters;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li><strong>expiry</strong>: unix timestamp, expected to be before <code>block.timestamp</code></li> </ul> <p><code>FunctionCall</code> parameters correspond to the following:</p> <ul> <li><strong>functionSignature</strong>: identifier for the function being called, expected to match <code>msg.sig</code></li> <li><strong>target</strong>: address of the target contract being called</li> <li><strong>caller</strong>: address of the current caller - expected to match <code>msg.sender</code></li> <li><strong>parameters</strong>: <code>calldata</code> after stripping off the first parameters, namely <code>v</code>,<code>r</code>, <code>s</code> and <code>expiry</code></li> </ul> <h3 id="eat-verification">EAT Verification</h3> <p>On chain, the reference implementation uses two contracts: an <code>AccessTokenConsumer</code> which is inherited by contracts needing to permission some of its functions and an <code>AccessTokenVerifier</code> which is responsible for verifying EATs.</p> <p>The <code>AccessTokenConsumer</code> contract calls the <code>AccessTokenVerifier</code> to verify the integrity of an EAT.</p> <p>The <code>verify()</code> function of the <code>AccessTokenVerifier</code> takes a signature and an <code>AccessToken</code> as input, verifies that the token is not expired, attempts to recover the signer from the signature and the reconstructed EIP-712 digest, and verifies that the signer is a valid, expected signer.</p> <p>Please see the <a href="https://wg-eips.ritovision.com/7272/./assets/AccessTokenVerifier.sol">reference implementation</a> for an example of how this can be performed.</p> <h2 id="rationale">Rationale</h2> <ul> <li> <p>Single-use. The reference implementation guarantees non-replayability of EATs. But other implementations might favor a different approach.</p> </li> <li> <p>Use of EIP-712. By conforming to EIP-712, EATs are interoperable with existing Ethereum infrastructure, and developers can use them to create access controls with minimal modifications to their existing code. It also ensures that EATs issued are bound to a specific chain.</p> </li> <li> <p>Zero-knowledge proofs. Using ZKPs comes at a cost, including added complexity. EATs are not much more than signed messages which are simpler to reason around. While <code>ecrecover</code> is available in any Ethereum smart contract out of the box, ZKPs come in different flavors which hinders interoperability.</p> </li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Any function can be gated with an EAT, apart from the special <code>receive</code> and <code>fallback</code> functions.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Here's a reference implementation of the different smart contracts making up the EAT system onchain:</p> <ul> <li><a href="https://wg-eips.ritovision.com/7272/./assets/IAccessTokenVerifier.sol">IAccessTokenVerifier.sol</a></li> <li><a href="https://wg-eips.ritovision.com/7272/./assets/AccessTokenVerifier.sol">AccessTokenVerifier.sol</a></li> <li><a href="https://wg-eips.ritovision.com/7272/./assets/AccessTokenConsumer.sol">AccessTokenConsumer.sol</a></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>The security of the Ethereum Access Token (EAT) proposal depends on several factors:</p> <h3 id="replay-attacks">Replay Attacks</h3> <p>The implementation MAY ensure that an EAT cannot be reused after it has been consumed. This is achieved by marking the EAT as consumed in the <code>_consumeAccessToken</code> function.</p> <h3 id="off-chain-issuance">Off-Chain Issuance</h3> <p>The security of the off-chain service issuing EATs is critical since the security of EAT-gated functions depends on it. If this service is compromised, malicious actors could be granted EATs giving them access to on-chain resources that they should not have access to.</p> <h3 id="expiry-time-considerations">Expiry Time Considerations</h3> <p>The expiry time of the EAT must be set judiciously to balance usability and security. If the expiry time is set too long, it might increase the risk of EAT misuse. If it's too short, it might compromise the usability of the application.</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 Erick Pacheco Pedrazahttps://github.com/eum602 Marcos Allendemallende@lacnet.com Diego Lopez Leóndieguitoll@gmail.com https://wg-eips.ritovision.com/7619/

Add precompiled contract that allows generic signature verifications using Falcon512 postquantum algorithm

<h2 id="abstract">Abstract</h2> <p>Include a precompiled signature verification function using Falcon-512. Falcon-512 is a candidate for standardization by the National Institute of Standards and Technology (NIST) and is quantum resistant with security level I.</p> <h2 id="motivation">Motivation</h2> <p>The advent of quantum computing threatens blockchain protocols and networks because they utilize non-quantum resistant cryptographic algorithms. When quantum computers become robust enough to run Shor’s algorithm (a quantum algorithm to find the prime factors of an integer) on a large scale, the most used asymmetric algorithms, utilized for digital signatures and message encryption, such as RSA, (EC)DSA, and (EC)DH, will be no longer secure. Quantum computers will be able to break them within a short period of time. Today, there are hundreds of billions of dollars denominated in cryptocurrencies and other digital assets that rely on blockchain ledgers as well as thousands of blockchain-based applications storing value in blockchain networks. Cryptocurrencies and blockchain-based applications require solutions that guarantee quantum resistance in order to preserve the integrity of data and assets in these public and immutable ledgers. Most proposals for quantum-resistant blockchain networks are theoretical, require large QKD (quantum key distribution, a secure communication method that implements a cryptographic protocol involving components of quantum mechanics) networks, or propose new quantum-resistant blockchain protocols to be built from scratch. This EIP is pioneer in proposing a solution compatible with current EVM blockchain protocols. It presents a simple mechanism to add a NIST-compliant post-quantum signature to blockchain transactions, making them quantum-resistant even when ECC (elliptic curve cryptography) cryptography becomes vulnerable against attacks by quantum computers. We have developed a Solidity implementation for the on-chain verification of this signatures, which does not scale due to the required high amount of gas. This is why <strong>this EIP is proposing a pre-compiled smart contract</strong> that allows to verify post-quantum signatures in a scalable manner.</p> <h2 id="specification">Specification</h2> <p>A clean implementation for Falcon-512 algorithm was brought from the PQClean project.</p> <p>The precompiled signature verification function runs at address <code>0x65</code>. The required inputs are:</p> <ul> <li><code>public key</code> - Falcon Public key of 897 bytes</li> <li><code>signature</code> - 666 bytes (max size)</li> <li><code>message</code> - an arbitrary number of bytes representing the message that was signed</li> </ul> <p>Those inputs are encoded according to:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[pubkey:897 bytes][signature:666 bytes][message: remainder]</span></span></code></pre> <p>Output is:</p> <ul> <li><code>result</code> - A successful signature verification returns <code>0000000000000000000000000000000000000000000000000000000000000001</code>, otherwise <code>0000000000000000000000000000000000000000000000000000000000000000</code> indicating all other failure cases where sufficient gas has been provided.</li> </ul> <p>The precompile will only revert in the case where insufficient gas has been provided. Data format errors, size errors, and invalid signatures will not cause the precompile to revert.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> Input: &quot;&quot;,</span></span> <span class="giallo-l"><span> Gas: 10,</span></span> <span class="giallo-l"><span> ExpectedError: &quot;out of gas&quot;,</span></span> <span class="giallo-l"><span> Name: &quot;empty input, too little gas&quot;,</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> Input: &quot;111111110000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000032000000000000000000000000000000000000000000000000000000000000006e0&quot;,</span></span> <span class="giallo-l"><span> Gas: 1000000,</span></span> <span class="giallo-l"><span> Result: &quot;000000000000000000000000000000000000000000000000000000000000000000000000&quot;,</span></span> <span class="giallo-l"><span> Name: &quot;garbled input&quot;,</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h3 id="example-usage-in-solidity">Example Usage in Solidity</h3> <p>The precompile can be wrapped in Solidity to provide a more development-friendly interface to <code>Falcon-512</code> signature verification.</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"> verify</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"> publicKey</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"> signature</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"> message</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-support">bool</span><span class="z-variable"> isValid</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-support"> bytes</span><span class="z-storage z-type"> memory</span><span> verifies</span><span>)</span><span class="z-keyword"> =</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0x0000000000000000000000000000000000000065</span><span>)</span></span> <span class="giallo-l"><span> .</span><span class="z-entity z-name">staticcall</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> publicKey</span><span>,</span></span> <span class="giallo-l"><span> signature</span><span>,</span></span> <span class="giallo-l"><span> message</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>success </span><span class="z-keyword">&amp;&amp;</span><span> verifies</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 32</span><span>,</span><span class="z-string"> &quot;Invalid signature&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> verifies</span><span>[</span><span class="z-constant">31</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h3 id="gas-costs">Gas costs</h3> <p>Since data size is variable, each operation to execute the precompiled call will require:</p> <ul> <li>1465 base units of gas for each operation.</li> <li>6 units of gas for each word contained in the payload. These values are based on results presented at the <a href="https://wg-eips.ritovision.com/7619/#benchmarks">benchmarks</a> section.</li> </ul> <h2 id="rationale">Rationale</h2> <p>Falcon-512 is a good candidate for a new signature implementation. Key sizes in Falcon-512 are relatively small compared to other post-quantum signature algorithms.</p> <p>The following table shows a summary of the typical values for keys and the approximate amount of time taken per second to execute signature verifications as specified by the authors of Falcon algorithm:</p> <table><thead><tr><th><strong>variant</strong></th><th><strong>verify/s</strong></th><th><strong>pub size(bytes)</strong></th><th><strong>sig size(bytes)</strong></th></tr></thead><tbody> <tr><td>Falcon512</td><td>27933.0</td><td>897</td><td>666</td></tr> </tbody></table> <p>Falcon uses shake256 under the hood, an implementation made in solidity showed it is not viable to implement this algorithm at that layer, on the other hand the implementation of falcon-512 by using precompiles turned to be the best approach since the gas cost (as shown in the previous section) is relatively low.</p> <p>Implementing just the signature verification is sufficiently enough to open a wide range of use cases at the smart contract level. To give an example, this method can perfectly work with the Account Abstraction concept, where the authentication process would rely on Falcon and the account is a smart contract.</p> <h3 id="benchmarks">benchmarks</h3> <p>Assuming ecRecover precompile is perfectly priced, a set of benchmarks were executed comparing Falcon-512 signature verification function precompile with ecRecover precompile. For benchmarks, it was used 2.6 GHz Intel Core i7 64-bit machine.</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"> cat</span><span class="z-string"> /proc/cpuinfo</span><span class="z-keyword"> |</span><span class="z-entity z-name"> grep</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">model name</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name">Intel(R</span><span>) Core(</span><span class="z-entity z-name">TM</span><span>) i7-10750H CPU @ 2.60GHz</span></span></code></pre><h4 id="5-seconds-benchmark">5 seconds benchmark</h4> <p>Based on <a href="https://wg-eips.ritovision.com/7619/assets/bench_vectors/">100 test vectors with valid signatures</a> a benchmark of 5 seconds, for each test vector, was performed, considering the following:</p> <ul> <li>the average time per operation (ns/op),</li> <li>each vector size increases in 33 bytes</li> <li>Ecrecover is well tested</li> </ul> <p>Benchmark results <a href="https://wg-eips.ritovision.com/7619/assets/benchmark_results/">here</a></p> <p>Then the 100 BenchmarkPrecompiledFalcon512 results were approximated to a linear equation dependent on the number of bytes in each test vector. From the approximation it was concluded that 1465 units of gas is the base requirement for any falcon-512 signature validation and 6 gas per word is additionally required.</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>0x65</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> <ul> <li> <p>A set of test vectors, with valid signatures, for benchmarking on new implementations is located in a separate <a href="https://wg-eips.ritovision.com/7619/assets/bench_vectors/">file</a></p> </li> <li> <p>A set of test vectors, with invalid data, to verify some invalid signature cases is located in a separate <a href="https://wg-eips.ritovision.com/7619/assets/invalid_signature_test_vectors/">file</a></p> </li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>Since the scope of this proposal is encapsulated at the contract level for verifying signatures it doesn't represent issues in regards to security.</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-06-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jimmy Debehttps://github.com/jimstir https://wg-eips.ritovision.com/7425/

Transparent reserve fund on-chain with stakeholder participation.

<h2 id="abstract">Abstract</h2> <p>This specification explains a tokenized reserve mechanism standard. Current smart contracts record transactions and are made public. The reserve will implement added functionality allowing stakeholders proactively to audit a contract. Using <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a>, stakeholders can create shares to show support for actions in the contract.</p> <h2 id="motivation">Motivation</h2> <p>Tokenized vaults store <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens that are represented by shares within vault contracts. Implementations can follow the <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> standard to provide basic functionality for depositing, withdrawing, and reading balances for a vault. As tokenization becomes increasingly popular, applications should use a form of tokenized vaults to store assets and allow all parties to track performance.</p> <p>This specification introduces a standard for an on-chain reserve that uses tokenized vaults to represent reserve stakeholders. Core functionality, which is an extension of <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a>, will provide stakeholders representation by depositing and withdrawing from the vault. The record of transactions for other <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> assets should be easily accessible to any party for auditing.</p> <p>In a tokenized reserve, stakeholders are represented by minting shares from the vault. The goal is to create a reserve similar to a real-world reserve fund used as a contingency for an entity. In most cases, an entity would follow criteria like running low on regular funds, to utilize the reserve fund. In a decentralized environment, an entity should incorporate stakeholders as criteria. Assets associated with the reserve as well as its origin will vary in decentralized environments, so transparent auditing is needed.</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="definitions">Definitions:</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>- owner: The creator of the reserve</span></span> <span class="giallo-l"><span>- user: Stakeholders participating in policies</span></span> <span class="giallo-l"><span>- reserve: The assets held on the contract other than underlying token</span></span> <span class="giallo-l"><span>- policies: Created by reserve owners to encourage stakeholder participation</span></span></code></pre><h3 id="constructor">Constructor:</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>- name: ERC-20 token name</span></span> <span class="giallo-l"><span>- ticker: ERC-20 ticker</span></span> <span class="giallo-l"><span>- asset: ERC-4626 underlying ERC-20 address</span></span> <span class="giallo-l"><span>- rAuth: Authorized user, for cases utilizing more than one owner/ limiting owner withdrawals</span></span> <span class="giallo-l"><span>- rOwner: Owner of the Reserve</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-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">import</span><span class="z-string"> &quot;./ERC4626.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> TokenReserve</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC4626</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"> Event emitted after a new policy is created</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"> policies</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"> token</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"> policyNum</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"> amount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> recipient</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"> Event emitted after a new deposit is made by the owner</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"> depositR</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"> token</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"> amount</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"> time</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> count</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"> </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Get time a deposit/withdrawal was made by 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"> count</span><span class="z-comment"> Number for deposit count</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"> block</span><span class="z-comment">.timestamp format</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"> ownerTime</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> count</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 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"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Get amount deposited to reserve by 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"> count</span><span class="z-comment"> Number for deposit count</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> policy</span><span class="z-comment"> The policy number to deposit to</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"> Amount of an asset that was deposited</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> ownerDeposit</span><span>(</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> count</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> policy</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 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"> Amount withdrawn for a opened policy by 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"> policy</span><span class="z-comment"> The policy number</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 ERC20</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> ownerWithdrawals</span><span>(</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> policy</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 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"> Token type deposited to reserve by owner</span></span> <span class="giallo-l"><span class="z-comment"> * - MUST be an address of ERC20 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"> count</span><span class="z-comment"> Number of deposit count</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"> Address of ERC20 token</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> tokenDeposit</span><span>(</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> count</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 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"> Amount deposited to a policy for shares</span></span> <span class="giallo-l"><span class="z-comment"> * - MUST be an ERC20 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"> user</span><span class="z-comment"> Address of 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"> policy</span><span class="z-comment"> The policy number the user deposited to</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"> Amount of ERC20 deposited</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> userDeposit</span><span>(</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> user</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> policy</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 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"> Amount withdrawn from a policy by 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"> user</span><span class="z-comment"> The address of 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"> policy</span><span class="z-comment"> The policy number for user withdrawal</span></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"> Amount of ERC20</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> userWithdrawals</span><span>(</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> user</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> policy</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> <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"> Token type withdrawn for an opened policy by the owner</span></span> <span class="giallo-l"><span class="z-comment"> * - MUST be ERC20 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"> policy</span><span class="z-comment"> The policy number for the token used</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"> Token</span><span class="z-comment"> ERC20 address</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> policyToken</span><span>(</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> policy</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 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"> Make a deposit to a policy creating new shares using deposit function from ERC4626</span></span> <span class="giallo-l"><span class="z-comment"> * - MUST be opened policy</span></span> <span class="giallo-l"><span class="z-comment"> * - MUST NOT be opened policy that was closed</span></span> <span class="giallo-l"><span class="z-comment"> * - SHOULD be only method to deposit to ERC4626 vault</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">NOTE</span><span class="z-comment">: using the deposit() will cause assets to not be accounted for in a policy (see Security Considerations section)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assets</span><span class="z-comment"> Amount being deposited</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> receiver</span><span class="z-comment"> Address of depositor</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> policy</span><span class="z-comment"> The number associated policy</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 shares minted </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> policyDeposit</span><span>(</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> assets</span><span>,</span><span class="z-entity z-name"> address</span><span class="z-entity z-name"> receiver</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> policy</span><span>)</span><span class="z-storage z-type"> external</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Burn shares, receive 1 to 1 value of shares using withdraw function from ERC4626</span></span> <span class="giallo-l"><span class="z-comment"> * - MUST have userDeposit greater than or equal to userWithdrawal</span></span> <span class="giallo-l"><span class="z-comment"> * - SHOULD be only method for withdrawing from ERC4626 vault</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assets</span><span class="z-comment"> Amount being deposited</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> receiver</span><span class="z-comment"> Address of 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"> owner</span><span class="z-comment"> Address of 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"> policy</span><span class="z-comment"> Number associated policy</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 asset</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> withdrawPolicy</span><span>(</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> assets</span><span>,</span><span class="z-entity z-name"> address</span><span class="z-entity z-name"> receiver</span><span>,</span><span class="z-entity z-name"> address</span><span class="z-entity z-name"> owner</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> policy</span><span>)</span><span class="z-storage z-type">external</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Issue new policy</span></span> <span class="giallo-l"><span class="z-comment"> * - MUST create new policy number</span></span> <span class="giallo-l"><span class="z-comment"> * - MUST account for amount withdrawn</span></span> <span class="giallo-l"><span class="z-comment"> * - MUST be only method to withdraw ERC20 tokens (excluding underlying ERC4626 token)</span></span> <span class="giallo-l"><span class="z-comment"> * - MUST be owner</span></span> <span class="giallo-l"><span class="z-comment"> * - SHOULD emit policies 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"> token</span><span class="z-comment"> Address of ERC-20 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"> Token amount being 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"> receiver</span><span class="z-comment"> Address of token recipient</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"> policy number</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> openPolicy</span><span>(</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> token</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> amount</span><span>,</span><span class="z-entity z-name"> address</span><span class="z-entity z-name"> receiver</span><span>)</span><span class="z-storage z-type"> external</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Make a deposit and/or close an opened policy</span></span> <span class="giallo-l"><span class="z-comment"> * - MUST be owner</span></span> <span class="giallo-l"><span class="z-comment"> * - MUST account for amount received</span></span> <span class="giallo-l"><span class="z-comment"> * - SHOULD emit policies 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"> token</span><span class="z-comment"> Address of ERC-20 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"> policy</span><span class="z-comment"> Number of the desired policy</span></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"> Token amount being deposited to the reserve</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> close</span><span class="z-comment"> Choose to close the policy</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 closed policy </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> closePolicy</span><span>(</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> token</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> policy</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> amount</span><span>,</span><span class="z-entity z-name"> bool</span><span class="z-entity z-name"> close</span><span>)</span><span class="z-storage z-type"> external</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 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"> Accounting for tokens deposited by owner</span></span> <span class="giallo-l"><span class="z-comment"> * - MUST be reserve owner</span></span> <span class="giallo-l"><span class="z-comment"> * - SHOULD emit depositR event</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">NOTE</span><span class="z-comment">: No shares are issued, funds can not be redeemed and no policy is opened. Withdrawnal made with openPolicy function.</span></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 ERC-20 token being deposited</span></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"> Address of token 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"> amount</span><span class="z-comment"> Token amount being deposited </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> depositReserve</span><span>(</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> token</span><span>,</span><span class="z-entity z-name"> address</span><span class="z-entity z-name"> sender</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> amount</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> virtual</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 proposed standard is designed to be a core implementation of a tokenized reserve interface. Other non-specified conditions should be addressed on a case-by-case basis. Each reserve uses <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard for shares, and <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> for the creation of shares. The reserve token SHOULD be considered as either the underlying <code>asset</code> for the <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> vault or the shares that are created when depositing to the vault. <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> is used to create a transparent creation of stakeholders of the reserve. There MUST be a representation of interested parties in the reserve. The implementer can decide how to treat representation based on users entering and leaving the vault. For example, a user could be forced not to use the same tokens in multiple policies to allow shares to be distributed fairly.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Tokenized reserves are made compatible with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Tokenized reserves share the same security considerations as <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a>.</p> <ol> <li>Assests withdrawn by owner are not secured by vaults.</li> </ol> <ul> <li>Stakeholders SHOULD be aware that the underlying <code>asset</code> can be withdrawn by the owner with no restrictions or authorizing party, like requiring an <code>rAuth</code>. Depending on the authorizing implementation, <code>asset</code> may still be withdrawn by the owner.</li> </ul> <p>A RECOMMENDED implementation:</p> <ul> <li>The <code>openPolicy</code> MUST explictly restrict the transfer of the underlying <code>asset</code>.</li> <li>If the underlying asset is apart of the reserve and not the vault, the reserve MUST provide a method to avoid user <code>asset</code> loss.</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> 2023-06-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Quy Phanhttps://github.com/quyphandang Quy Phanquy.phan@cryptoviet.info https://wg-eips.ritovision.com/7254/

Revenue token is a token that shares rewards for holders.

<h2 id="abstract">Abstract</h2> <p>With the aspiration of bringing forth unique functionality and enhancing value for holders of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens, our project aims to effortlessly reward token holders without necessitating users to lock, stake, or farm their tokens. Whenever the project generates profits, these profits can be distributed to the token holders.</p> <p>Revenue Sharing is an extended version of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. It proposes an additional payment method for token holders.</p> <p>This standard includes updating rewards for holders and allowing token holders to withdraw rewards.</p> <p>Potential use cases encompass:</p> <ul> <li>Companies distributing dividends to token holders.</li> <li>Direct sharing of revenue derived from business activities, such as marketplaces, Automated Market Makers (AMMs), and games.</li> </ul> <h2 id="specification">Specification</h2> <h3 id="methods">Methods</h3> <h4 id="maxtokenreward">maxTokenReward</h4> <p>Returns max token reward.</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"> maxTokenReward</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></code></pre><h4 id="informationof">informationOf</h4> <p>Returns the account information of another account with the address <code>token</code> and <code>account</code>, including: inReward, outReward and withdraw.</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"> informationOf</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> account</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">UserInformation</span><span class="z-variable"> memory</span><span>)</span></span></code></pre><h4 id="informationofbatch">informationOfBatch</h4> <p>Returns the list account information of another account with the <code>account</code>, including: inReward, outReward and withdraw.</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"> informationOfBatch</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> account</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">UserInformation</span><span>[</span><span>]</span><span class="z-variable"> memory</span><span>)</span></span></code></pre><h4 id="userinformation">UserInformation</h4> <p><code>inReward</code>: when user's balance decreases, inReward will be updated <code>outReward</code>: when user's balance increases, outReward will be updated <code>withdraw</code>: total amount of reward tokens withdrawn</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"> UserInformation</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> inReward</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> outReward</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> withdraw</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="tokenreward">tokenReward</h4> <p>Returns the list token reward address of the token.</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"> tokenReward</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">address</span><span>[</span><span>]</span><span class="z-variable"> memory</span><span>)</span></span></code></pre><h4 id="updatereward">updateReward</h4> <p>Updates rewardPerShare of token reward. rewardPerShare = rewardPerShare + amount / totalSupply()</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"> updateReward</span><span>(</span><span class="z-variable">address</span><span>[</span><span>]</span><span class="z-variable"> memory</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> uint256</span><span>[</span><span>]</span><span class="z-variable"> memory</span><span class="z-variable"> amount</span><span>)</span><span class="z-entity z-name"> public</span></span></code></pre><h4 id="viewreward">viewReward</h4> <p>Returns the list amount of reward for an 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"> viewReward</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> account</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 class="z-variable"> memory</span><span>)</span></span></code></pre><h4 id="getreward">getReward</h4> <p>Gets and returns reward with list token reward.</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"> getReward</span><span>(</span><span class="z-variable">address</span><span>[</span><span>]</span><span class="z-variable"> memory</span><span class="z-variable"> token</span><span>)</span><span class="z-entity z-name"> public</span></span></code></pre><h4 id="getrewardpershare">getRewardPerShare</h4> <p>Returns the reward per share of token reward.</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"> getRewardPerShare</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> token</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></code></pre><h4 id="existstokenreward">existsTokenReward</h4> <p>Returns the status of token reward.</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"> existsTokenReward</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> token</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></code></pre><h2 id="rationale">Rationale</h2> <p>TBD</p> <h2 id="reference-implementation">Reference Implementation</h2> <ul> <li><a href="https://wg-eips.ritovision.com/7254/./assets/ERC7254.sol">ERC-7254</a></li> <li><a href="https://wg-eips.ritovision.com/7254/./assets/IERC7254.sol">IERC-7254</a></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-06-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 mikehttps://github.com/michaelneuder Francescohttps://github.com/fradamt dapplionhttps://github.com/dapplion Mikhailhttps://github.com/mkalinin Adityahttps://github.com/adiasg Justinhttps://github.com/justindrake lightclienthttps://github.com/lightclient Felix Langehttps://github.com/fjl https://wg-eips.ritovision.com/7251/

Allow validators to have larger effective balances, while maintaining the 32 ETH lower bound.

<h2 id="abstract">Abstract</h2> <p>Increases the constant <code>MAX_EFFECTIVE_BALANCE</code>, while keeping the minimum staking balance <code>32 ETH</code>. This permits large node operators to consolidate into fewer validators while also allowing solo-stakers to earn compounding rewards and stake in more flexible increments.</p> <h2 id="motivation">Motivation</h2> <p>As of October 3, 2023, there are currently over 830,000 validators participating in the consensus layer. The size of this set continues to grow due, in part, to the <code>MAX_EFFECTIVE_BALANCE</code>, which limits the stake of a single validator to <code>32 ETH</code>. This leads to large amounts of "redundant validators", which are controlled by a single entity, possibly running on the same beacon node, but with distinct BLS signing keys. The limit on the <code>MAX_EFFECTIVE_BALANCE</code> is technical debt from the original sharding design, in which subcommittees (not the attesting committee but the committee calculated in <code>is_aggregator</code>) needed to be majority honest. As a result, keeping the weights of subcommittee members approximately equal reduced the risk of a single large validator containing too much influence. Under the current design, these subcommittees are only used for attestation aggregation, and thus only have a <code>1/N</code> honesty assumption.</p> <p>With the security model of the protocol no longer dependent on a low value for <code>MAX_EFFECTIVE_BALANCE</code>, we propose raising this value while keeping the minimum validator threshold of <code>32 ETH</code>. This increase aims to reduce the validator set size, thereby reducing the number of P2P messages over the network, the number of BLS signatures that need to be aggregated each epoch, and the <code>BeaconState</code> memory footprint. This change adds value for both small and large validators. Large validators can consolidate to run fewer validators and thus fewer beacon nodes. Small validators now benefit from compounding rewards and the ability to stake in more flexible increments (e.g., the ability to stake <code>40 ETH</code> instead of needing to accumulate <code>64 ETH</code> to run two validators today).</p> <h2 id="specification">Specification</h2> <h3 id="constants">Constants</h3> <h4 id="execution-layer">Execution layer</h4> <table><thead><tr><th>Name</th><th>Value</th><th>Comment</th></tr></thead><tbody> <tr><td><code>CONSOLIDATION_REQUEST_TYPE</code></td><td><code>0x02</code></td><td>The <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> type prefix for consolidation request</td></tr> <tr><td><code>CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</code></td><td><code>0x0000BBdDc7CE488642fb579F8B00f3a590007251</code></td><td>Where to call and store relevant details about consolidation request mechanism</td></tr> <tr><td><code>SYSTEM_ADDRESS</code></td><td><code>0xfffffffffffffffffffffffffffffffffffffffe</code></td><td>Address used to invoke system operation on contract</td></tr> <tr><td><code>EXCESS_CONSOLIDATION_REQUESTS_STORAGE_SLOT</code></td><td><code>0</code></td><td></td></tr> <tr><td><code>CONSOLIDATION_REQUEST_COUNT_STORAGE_SLOT</code></td><td><code>1</code></td><td></td></tr> <tr><td><code>CONSOLIDATION_REQUEST_QUEUE_HEAD_STORAGE_SLOT</code></td><td><code>2</code></td><td>Pointer to the head of the consolidation request message queue</td></tr> <tr><td><code>CONSOLIDATION_REQUEST_QUEUE_TAIL_STORAGE_SLOT</code></td><td><code>3</code></td><td>Pointer to the tail of the consolidation request message queue</td></tr> <tr><td><code>CONSOLIDATION_REQUEST_QUEUE_STORAGE_OFFSET</code></td><td><code>4</code></td><td>The start memory slot of the in-state consolidation request message queue</td></tr> <tr><td><code>MAX_CONSOLIDATION_REQUESTS_PER_BLOCK</code></td><td><code>2</code></td><td>Maximum number of consolidation requests that can be dequeued into a block</td></tr> <tr><td><code>TARGET_CONSOLIDATION_REQUESTS_PER_BLOCK</code></td><td><code>1</code></td><td></td></tr> <tr><td><code>MIN_CONSOLIDATION_REQUEST_FEE</code></td><td><code>1</code></td><td></td></tr> <tr><td><code>CONSOLIDATION_REQUEST_FEE_UPDATE_FRACTION</code></td><td><code>17</code></td><td></td></tr> <tr><td><code>EXCESS_INHIBITOR</code></td><td><code>2**256-1</code></td><td>Excess value used to compute the fee before the first system call</td></tr> </tbody></table> <h4 id="consensus-layer">Consensus layer</h4> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><code>COMPOUNDING_WITHDRAWAL_PREFIX</code></td><td><code>Bytes1('0x02')</code></td></tr> <tr><td><code>MIN_ACTIVATION_BALANCE</code></td><td><code>Gwei(2**5 * 10**9)</code> (32 ETH)</td></tr> <tr><td><code>MAX_EFFECTIVE_BALANCE_ELECTRA</code></td><td><code>Gwei(2**11 * 10**9)</code> (2048 ETH)</td></tr> </tbody></table> <h3 id="execution-layer-1">Execution layer</h3> <h4 id="consolidation-request">Consolidation request</h4> <p>The new consolidation request is an <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> request with type <code>0x02</code> consisting of the following fields:</p> <ol> <li><code>source_address</code>: <code>Bytes20</code></li> <li><code>source_pubkey</code>: <code>Bytes48</code></li> <li><code>target_pubkey</code>: <code>Bytes48</code></li> </ol> <p>The <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> encoding of a consolidation request is as follows. Note we simply return the encoded request value as returned by the contract.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>request_type</span><span class="z-keyword"> =</span><span class="z-constant"> CONSOLIDATION_REQUEST_TYPE</span></span> <span class="giallo-l"><span>request_data</span><span class="z-keyword"> =</span><span> dequeue_consolidation_requests</span><span>(</span><span>)</span></span></code></pre><h4 id="consolidation-request-contract">Consolidation request contract</h4> <p>The contract has three different code paths, which can be summarized at a high level as follows:</p> <ol> <li>Add consolidation request - requires a <code>96</code> byte input, concatenated public keys of the source and the target validators.</li> <li>Fee getter - if the input length is zero, return the current fee required to add a consolidation request.</li> <li>System process - if called by system address, pop off the consolidation requests for the current block from the queue.</li> </ol> <h5 id="add-consolidation-request">Add Consolidation Request</h5> <p>If call data input to the contract is exactly <code>96</code> bytes, perform the following:</p> <ol> <li>Ensure enough ETH was sent to cover the current consolidation request fee (<code>msg.value &gt;= get_fee()</code>)</li> <li>Increase consolidation request count by <code>1</code> for the current block (<code>increment_count()</code>)</li> <li>Insert a consolidation request into the queue for the source address and pubkeys of the source and the target (<code>insert_consolidation_request_into_queue()</code>)</li> </ol> <p>Specifically, the functionality is defined in pseudocode as the function <code>add_consolidation_request()</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"> add_consolidation_request</span><span>(</span><span class="z-variable z-parameter z-function">Bytes48</span><span>:</span><span> source_pubkey</span><span>,</span><span class="z-variable z-parameter z-function"> Bytes48</span><span>:</span><span> target_pubkey</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"> Add consolidation request adds new request to the consolidation request queue, so long as a sufficient fee is provided.</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify sufficient fee was provided.</span></span> <span class="giallo-l"><span> fee</span><span class="z-keyword"> =</span><span> get_fee</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> require</span><span>(</span><span>msg</span><span>.</span><span>value</span><span class="z-keyword"> &gt;=</span><span> fee</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Insufficient value for fee</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-punctuation z-definition z-comment"> #</span><span class="z-comment"> Increment consolidation request count.</span></span> <span class="giallo-l"><span> count</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> CONSOLIDATION_REQUEST_COUNT_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> CONSOLIDATION_REQUEST_COUNT_STORAGE_SLOT</span><span>,</span><span> count</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-punctuation z-definition z-comment"> #</span><span class="z-comment"> Insert into queue.</span></span> <span class="giallo-l"><span> queue_tail_index</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> CONSOLIDATION_REQUEST_QUEUE_TAIL_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> queue_storage_slot</span><span class="z-keyword"> =</span><span class="z-constant"> CONSOLIDATION_REQUEST_QUEUE_STORAGE_OFFSET</span><span class="z-keyword"> +</span><span> queue_tail_index</span><span class="z-keyword"> *</span><span class="z-constant"> 4</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span>,</span><span> msg</span><span>.</span><span>sender</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>,</span><span> source_pubkey</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">32</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span>,</span><span> source_pubkey</span><span>[</span><span class="z-constant">32</span><span>:</span><span class="z-constant">48</span><span>]</span><span class="z-invalid z-illegal"> ++</span><span> target_pubkey</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">16</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 3</span><span>,</span><span> target_pubkey</span><span>[</span><span class="z-constant">16</span><span>:</span><span class="z-constant">48</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> CONSOLIDATION_REQUEST_QUEUE_TAIL_STORAGE_SLOT</span><span>,</span><span> queue_tail_index</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span></span></code></pre><h6 id="fee-calculation">Fee calculation</h6> <p>The following pseudocode can compute the cost of an individual consolidation request, given a certain number of excess consolidation requests.</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_fee</span><span>(</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span></span> <span class="giallo-l"><span> excess</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> EXCESS_CONSOLIDATION_REQUESTS_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> require</span><span>(</span><span>excess</span><span class="z-keyword"> !=</span><span class="z-constant"> EXCESS_INHIBITOR</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Inhibitor still active</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> fake_exponential</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> MIN_CONSOLIDATION_REQUEST_FEE</span><span>,</span></span> <span class="giallo-l"><span> excess</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> CONSOLIDATION_REQUEST_FEE_UPDATE_FRACTION</span></span> <span class="giallo-l"><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"> fake_exponential</span><span>(</span><span class="z-variable z-parameter z-function">factor</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> numerator</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> denominator</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> i</span><span class="z-keyword"> =</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> output</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> numerator_accum</span><span class="z-keyword"> =</span><span> factor</span><span class="z-keyword"> *</span><span> denominator</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> numerator_accum</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> output</span><span class="z-keyword"> +=</span><span> numerator_accum</span></span> <span class="giallo-l"><span> numerator_accum</span><span class="z-keyword"> =</span><span> (</span><span>numerator_accum</span><span class="z-keyword"> *</span><span> numerator</span><span>)</span><span class="z-keyword"> //</span><span> (</span><span>denominator</span><span class="z-keyword"> *</span><span> i</span><span>)</span></span> <span class="giallo-l"><span> i</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> output</span><span class="z-keyword"> //</span><span> denominator</span></span></code></pre><h5 id="fee-getter">Fee Getter</h5> <p>When the input to the contract is length zero, interpret this as a get request for the current fee, i.e. the contract returns the result of <code>get_fee()</code>.</p> <h5 id="system-call">System Call</h5> <p>At the end of processing any execution block where this EIP is active (i.e. after processing all transactions and after performing the block body consolidation requests validations), call the contract at <code>CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</code> as <code>SYSTEM_ADDRESS</code> with no calldata. The invocation triggers the following:</p> <ul> <li>The contract's queue is updated based on consolidation requests dequeued and the consolidation requests queue head/tail are reset if the queue has been cleared (<code>dequeue_consolidation_requests()</code>)</li> <li>The contract's excess consolidation requests are updated based on usage in the current block (<code>update_excess_consolidation_requests()</code>)</li> <li>The contract's consolidation requests count is reset to <code>0</code> (<code>reset_consolidation_requests_count()</code>)</li> </ul> <p>Each consolidation request must appear in the EIP-7685 requests list in the exact order returned by <code>dequeue_consolidation_requests()</code>.</p> <p>Additionally, the system call and the processing of that block must conform to the following:</p> <ul> <li>The call has a dedicated gas limit of <code>30_000_000</code>.</li> <li>Gas consumed by this call does not count against the block’s overall gas usage.</li> <li>Both the gas limit assigned to the call and the gas consumed are excluded from any checks against the block’s gas limit.</li> <li>The call does not follow <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fee burn semantics — no value should be transferred as part of this call.</li> <li>If there is no code at <code>CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</code>, the corresponding block <strong>MUST</strong> be marked invalid.</li> <li>If the call to the contract fails or returns an error, the block <strong>MUST</strong> be invalidated.</li> </ul> <p>The functionality triggered by the system call is defined in pseudocode as the function <code>process_consolidation_requests()</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">##################</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Public function #</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> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> process_consolidation_requests</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> reqs</span><span class="z-keyword"> =</span><span> dequeue_consolidation_requests</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> update_excess_consolidation_requests</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> reset_consolidation_requests_count</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> ssz</span><span>.</span><span>serialize</span><span>(</span><span>reqs</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"> Helpers #</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> <span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> ConsolidationRequest</span><span>(</span><span class="z-support">object</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> source_address</span><span>:</span><span> Bytes20</span></span> <span class="giallo-l"><span> source_pubkey</span><span>:</span><span> Bytes48</span></span> <span class="giallo-l"><span> target_pubkey</span><span>:</span><span> Bytes48</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"> dequeue_consolidation_requests</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> queue_head_index</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> CONSOLIDATION_REQUEST_QUEUE_HEAD_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> queue_tail_index</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> CONSOLIDATION_REQUEST_QUEUE_TAIL_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> num_in_queue</span><span class="z-keyword"> =</span><span> queue_tail_index</span><span class="z-keyword"> -</span><span> queue_head_index</span></span> <span class="giallo-l"><span> num_dequeued</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span>num_in_queue</span><span>,</span><span class="z-constant"> MAX_CONSOLIDATION_REQUESTS_PER_BLOCK</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> reqs</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span>num_dequeued</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> queue_storage_slot</span><span class="z-keyword"> =</span><span class="z-constant"> CONSOLIDATION_REQUEST_QUEUE_STORAGE_OFFSET</span><span class="z-keyword"> +</span><span> (</span><span>queue_head_index</span><span class="z-keyword"> +</span><span> i</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> 4</span></span> <span class="giallo-l"><span> source_address</span><span class="z-keyword"> =</span><span> address</span><span>(</span><span>sload</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span>)</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">20</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> source_pubkey</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> sload</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">32</span><span>]</span><span class="z-keyword"> +</span><span> sload</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span>)</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">16</span><span>]</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> target_pubkey</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> sload</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span>)</span><span>[</span><span class="z-constant">16</span><span>:</span><span class="z-constant">32</span><span>]</span><span class="z-keyword"> +</span><span> sload</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 3</span><span>)</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">32</span><span>]</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> req</span><span class="z-keyword"> =</span><span> ConsolidationRequest</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> source_address</span><span class="z-keyword">=</span><span>Bytes20</span><span>(</span><span>source_address</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> source_pubkey</span><span class="z-keyword">=</span><span>Bytes48</span><span>(</span><span>source_pubkey</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> target_pubkey</span><span class="z-keyword">=</span><span>Bytes48</span><span>(</span><span>target_pubkey</span><span>)</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> reqs</span><span>.</span><span>append</span><span>(</span><span>req</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> new_queue_head_index</span><span class="z-keyword"> =</span><span> queue_head_index</span><span class="z-keyword"> +</span><span> num_dequeued</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> new_queue_head_index</span><span class="z-keyword"> ==</span><span> queue_tail_index</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Queue is empty, reset queue pointers</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> CONSOLIDATION_REQUEST_QUEUE_HEAD_STORAGE_SLOT</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> CONSOLIDATION_REQUEST_QUEUE_TAIL_STORAGE_SLOT</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> sstore</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> CONSOLIDATION_REQUEST_QUEUE_HEAD_STORAGE_SLOT</span><span>,</span><span> new_queue_head_index</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> reqs</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"> update_excess_consolidation_requests</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> previous_excess</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> EXCESS_CONSOLIDATION_REQUESTS_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Check if excess needs to be reset to 0 for first iteration after activation</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> previous_excess</span><span class="z-keyword"> ==</span><span class="z-constant"> EXCESS_INHIBITOR</span><span>:</span></span> <span class="giallo-l"><span> previous_excess</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> count</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> CONSOLIDATION_REQUEST_COUNT_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> new_excess</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> previous_excess</span><span class="z-keyword"> +</span><span> count</span><span class="z-keyword"> &gt;</span><span class="z-constant"> TARGET_CONSOLIDATION_REQUESTS_PER_BLOCK</span><span>:</span></span> <span class="giallo-l"><span> new_excess</span><span class="z-keyword"> =</span><span> previous_excess</span><span class="z-keyword"> +</span><span> count</span><span class="z-keyword"> -</span><span class="z-constant"> TARGET_CONSOLIDATION_REQUESTS_PER_BLOCK</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> EXCESS_CONSOLIDATION_REQUESTS_STORAGE_SLOT</span><span>,</span><span> new_excess</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"> reset_consolidation_requests_count</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> CONSOLIDATION_REQUEST_COUNT_STORAGE_SLOT</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span></code></pre><h5 id="bytecode">Bytecode</h5> <pre class="giallo z-code"><code data-lang="asm"><span class="giallo-l"><span>caller</span></span> <span class="giallo-l"><span>push20 </span><span class="z-constant">0xfffffffffffffffffffffffffffffffffffffffe</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0xd3</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x11</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push32 </span><span class="z-constant">0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x019a</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span>gt</span></span> <span class="giallo-l"><span>iszero</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x68</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>dup4</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>dup5</span></span> <span class="giallo-l"><span>dup4</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span class="z-keyword">div</span></span> <span class="giallo-l"><span>swap2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>swap2</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x4d</span></span> <span class="giallo-l"><span>jump</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>swap4</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span class="z-keyword">div</span></span> <span class="giallo-l"><span>swap3</span></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span>calldatasize</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x60</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x88</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>calldatasize</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x019a</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>callvalue</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x019a</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x20</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>callvalue</span></span> <span class="giallo-l"><span>lt</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x019a</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x04</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x04</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>caller</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>calldataload</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x20</span></span> <span class="giallo-l"><span>calldataload</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x40</span></span> <span class="giallo-l"><span>calldataload</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>caller</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x60</span></span> <span class="giallo-l"><span class="z-keyword">shl</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x60</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x14</span></span> <span class="giallo-l"><span>calldatacopy</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x74</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>log0</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>stop</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span class="z-keyword">sub</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span>gt</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0xe7</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x0129</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x04</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x04</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x74</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x60</span></span> <span class="giallo-l"><span class="z-keyword">shl</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x14</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x20</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x20</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0xe9</span></span> <span class="giallo-l"><span>jump</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>swap2</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>swap3</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x013b</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x0146</span></span> <span class="giallo-l"><span>jump</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push32 </span><span class="z-constant">0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span>iszero</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x0173</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>gt</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x0188</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x018e</span></span> <span class="giallo-l"><span>jump</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span class="z-keyword">sub</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x74</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>revert</span></span></code></pre><h5 id="deployment">Deployment</h5> <p>The consolidation requests contract is deployed like any other smart contract. A special synthetic address is generated by working backwards from the desired deployment transaction:</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">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">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">to</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x3d090</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasPrice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe8d4a51000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxPriorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</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">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">input</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff5f5561019e80602d5f395ff33373fffffffffffffffffffffffffffffffffffffffe1460d35760115f54807fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff1461019a57600182026001905f5b5f82111560685781019083028483029004916001019190604d565b9093900492505050366060146088573661019a573461019a575f5260205ff35b341061019a57600154600101600155600354806004026004013381556001015f358155600101602035815560010160403590553360601b5f5260605f60143760745fa0600101600355005b6003546002548082038060021160e7575060025b5f5b8181146101295782810160040260040181607402815460601b815260140181600101548152602001816002015481526020019060030154905260010160e9565b910180921461013b5790600255610146565b90505f6002555f6003555b5f54807fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff141561017357505f5b6001546001828201116101885750505f61018e565b01600190035b5f555f6001556074025ff35b5f5ffd</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">v</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">r</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x539</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">s</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xc0730f92dc275b663d377a7cbb141b6600052</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x379269d571beff3ed1d8eba3abb24076a7267b0eaf0cc66d728fb0544f5a690d</span><span class="z-punctuation z-definition z-string">&quot;</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>Sender: 0x13d1913d623E6a9D8811736359E50fD31Fe54fCA</span></span> <span class="giallo-l"><span>Address: 0x0000BBdDc7CE488642fb579F8B00f3a590007251</span></span></code></pre><h3 id="consensus-layer-1">Consensus layer</h3> <p>The defining features of this EIP are:</p> <ol> <li><em><strong>Increasing the <code>MAX_EFFECTIVE_BALANCE</code>, while creating a <code>MIN_ACTIVATION_BALANCE</code>.</strong></em> The core feature of allowing variable size validators.</li> <li><em><strong>Allowing for multiple validator indices to be combined through the protocol.</strong></em> A mechanism by which large node operators can combine validators without cycling through the exit and activation queues.</li> <li><em><strong>Adding execution layer partial withdrawals (part of <a href="https://wg-eips.ritovision.com/7002/">EIP-7002</a>).</strong></em> Allowing Execution Layer messages to trigger partial withdrawals in addition to full exits (e.g., a <code>100 ETH</code> validator can remove up to <code>68 ETH</code> without exiting the validator).</li> <li><em><strong>Making the initial slashing penalty negligible.</strong></em> This reduces the risk of consolidation for large validators.</li> </ol> <p>The <a href="https://wg-eips.ritovision.com/7251/#rationale">Rationale</a> section contains an explanation for each of these proposed core features. A sketch of the resulting changes to the consensus layer is included below.</p> <ol> <li>Add <code>COMPOUNDING_WITHDRAWAL_PREFIX</code> and <code>MIN_ACTIVATION_BALANCE</code> constants, while introducing the updated value of <code>MAX_EFFECTIVE_BALANCE</code> (<code>MAX_EFFECTIVE_BALANCE_ELECTRA</code>).</li> <li>Create the <code>PendingDeposit</code> container, which is used to track incoming deposits in the weight-based rate limiting mechanism.</li> <li>Update the <code>BeaconState</code> with deposit and partial withdrawal queues, fields needed for deposit, and exit queue weight-based rate limiting.</li> <li>Modify <code>is_eligible_for_activation_queue</code> to check against <code>MIN_ACTIVATION_BALANCE</code> rather than <code>MAX_EFFECTIVE_BALANCE</code>.</li> <li>Modify <code>get_validator_churn_limit</code> to depend on the validator weight rather than the validator count.</li> <li>Create a helper <code>compute_exit_epoch_and_update_churn</code> to calculate the exit epoch based on the current pending withdrawals.</li> <li>Modify <code>initiate_validator_exit</code> to rate limit the exit queue by balance rather than the number of validators.</li> <li>Modify <code>initialize_beacon_state_from_eth1</code> to use <code>MIN_ACTIVATION_BALANCE</code>.</li> <li>Modify <code>process_registry_updates</code> to activate all eligible validators.</li> <li>Add a per-epoch helper, <code>process_pending_deposits</code>, to consume some of the pending deposits.</li> <li>Modify <code>get_validator_from_deposit</code> to initialize the effective balance to zero (it's updated by the pending deposit flow).</li> <li>Modify <code>process_deposit</code> to store incoming deposits in <code>state.pending_deposits</code>.</li> <li>Modify <code>compute_weak_subjectivity_period</code> to use the new churn limit function.</li> <li>Add <code>has_compounding_withdrawal_credential</code> to check for the <code>0x02</code> credential.</li> <li>Modify <code>is_fully_withdrawable_validator</code> to check for compounding credentials.</li> <li>Add <code>get_validator_excess_balance</code> to calculate the excess balance of validators.</li> <li>Modify <code>is_partially_withdrawable_validator</code> to check for excess balance.</li> <li>Modify <code>get_expected_withdrawals</code> to use excess balance and process pending partial withdrawals.</li> <li>Add <code>process_consolidation</code> to initiate in-protocol validator consolidation and switch a validator to compounding withdrawal credentials.</li> <li>Limits the usage of exit churn to 256 ETH (equivalent to 8 validators with 32 ETH effective balance), and defers the surplus of the churn to process consolidations.</li> </ol> <p>Full consensus layer specification can be found in <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/834e40604ae4411e565bd6540da50b008b2496dc/specs/electra/beacon-chain.md"><code>./electra/beacon-chain.md</code></a></p> <h2 id="rationale">Rationale</h2> <p>This EIP aims to reduce the total number of validators without changing anything about the economic security of the protocol. It provides a mechanism by which large node operators who control significant amounts of stake can consolidate into fewer validators. We analyze the reasoning behind each of the core features.</p> <h3 id="increasing-the-max-effective-balance-while-creating-a-min-activation-balance">Increasing the <code>MAX_EFFECTIVE_BALANCE</code>, while creating a <code>MIN_ACTIVATION_BALANCE</code></h3> <p>While increasing the <code>MAX_EFFECTIVE_BALANCE</code> to allow larger-stake validators, it is important to keep the lower bound of <code>32 ETH</code> (by introducing a new constant – <code>MIN_ACTIVATION_BALANCE</code>) to encourage solo-staking.</p> <h3 id="allowing-for-multiple-validator-indices-to-be-combined-through-the-protocol">Allowing for multiple validator indices to be combined through the protocol</h3> <p>For large staking pools that already control thousands of validators, exiting and re-entering would be extremely slow and costly. The adoption of the EIP will be much higher by allowing in-protocol consolidation.</p> <h3 id="adding-execution-layer-partial-withdrawals-part-of-eip-7002">Adding execution layer partial withdrawals (part of <a href="https://wg-eips.ritovision.com/7002/">EIP-7002</a>)</h3> <p>For validators that choose to raise their effective balance ceiling, allowing for custom partial withdrawals triggered from the execution layer increases the flexibility of the staking configurations. Validators can choose when and how much they withdraw but will have to pay gas for the EL transaction.</p> <h3 id="making-the-initial-slashing-penalty-negligible">Making the initial slashing penalty negligible</h3> <p>To encourage consolidation, we could modify the slashing penalties. The biggest hit comes from the initial penalty of <code>1/32</code> of the validator's effective balance. Since this scales linearly on the effective balance, the higher-stake validators directly incur higher risk. By changing the scaling properties, we could make consolidation more attractive.</p> <h3 id="consolidation-contract-parameter-values">Consolidation contract parameter values</h3> <p>The consolidation smart contract uses a fee mechanism to rate limit the number of requests per block. Details of the fee mechanism are available in <a href="https://wg-eips.ritovision.com/7002/#fee-update-rule">EIP-7002</a>.</p> <p><code>TARGET_CONSOLIDATION_REQUESTS_PER_BLOCK</code> is chosen to be <code>1</code> to rate limit consolidation requests as much as possible. <code>MAX_CONSOLIDATION_REQUESTS_PER_BLOCK</code> is chosen to be <code>2</code> to allow for switching a validator to compounding credentials and requesting a consolidation in the same block.</p> <p>One consolidation per block is still higher than the size of consolidation churn which can lead to unbounded growth of the consolidation queue. Thus, there is a hard limit on the consolidation queue size equal to 262,144 requests which is <code>4 MB</code> of data in the beacon state.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces backward incompatible changes to the block validation rule set 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>This change modifies committees and churn, but doesn't significantly impact the security properties.</p> <h3 id="security-of-attestation-committees">Security of attestation committees</h3> <p>Given full consolidation as the worst case, the probability of an adversarial takeover of a committee remains low. Even in a high consolidation scenario, the required share of honest validators remains well below the 2/3 supermajority needed for finality.</p> <h3 id="aggregator-selection">Aggregator selection</h3> <p>In the original sharding roadmap, subcommittees were required to be secure with extremely high probability. Now with the sole responsibility of attestation aggregation, we only require each committee to have at least one honest aggregator. Currently, aggregators are selected through a VRF lottery, targeting several validator units that can be biased by non-consolidated attackers. This proposal changes the VRF lottery to consider weight, so the probability of having at least one honest aggregator is not worse.</p> <h3 id="proposer-selection-probability">Proposer selection probability</h3> <p>Proposer selection is already weighted by the ratio of their effective balance to <code>MAX_EFFECTIVE_BALANCE</code>. Due to the lower probabilities, this change will slightly increase the time it takes to calculate the next proposer index.</p> <h3 id="sync-committee-selection-probability">Sync committee selection probability</h3> <p>Sync committee selection is also already weighted by effective balance, so this proposal does not require modifications to the sync protocol. Light clients can still check that a super-majority of participants have signed an update irrespective of their weights since we maintain a weight-based selection probability.</p> <h3 id="churn-invariants">Churn invariants</h3> <p>This proposal maintains the activation and exit churn invariants limiting active weight instead of validator count. Balance top-ups are now handled explicitly, being subject to the same activation queue as full deposits.</p> <h3 id="fee-overpayment">Fee Overpayment</h3> <p>Calls to the system contract require a fee payment defined by the current contract state. Overpaid fees are not returned to the caller. It is not generally possible to compute the exact required fee amount ahead of time. When adding a consolidation request from a contract, the contract can perform a read operation to check for the current fee and then pay exactly the required amount. Here is an example in Solidity:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function addConsolidation(bytes memory srcPubkey, bytes memory targetPubkey, uint64 requestFeeLimit) private {</span></span> <span class="giallo-l"><span> assert(srcPubkey.length == 48);</span></span> <span class="giallo-l"><span> assert(targetPubkey.length == 48);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Read current fee from the contract.</span></span> <span class="giallo-l"><span> (bool readOK, bytes memory feeData) = ConsolidationsContract.staticcall(&#39;&#39;);</span></span> <span class="giallo-l"><span> if (!readOK) {</span></span> <span class="giallo-l"><span> revert(&#39;reading fee failed&#39;);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> uint256 fee = uint256(bytes32(feeData));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Check the fee is not too high.</span></span> <span class="giallo-l"><span> if (fee &gt; requestFeeLimit) {</span></span> <span class="giallo-l"><span> revert(&#39;fee is too high&#39;);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Add the request.</span></span> <span class="giallo-l"><span> bytes memory callData = bytes.concat(srcPubkey, targetPubkey);</span></span> <span class="giallo-l"><span> (bool writeOK,) = ConsolidationsContract.call{value: fee}(callData);</span></span> <span class="giallo-l"><span> if (!writeOK) {</span></span> <span class="giallo-l"><span> revert(&#39;adding request failed&#39;);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Note: the system contract uses the EVM <code>CALLER</code> operation (Solidity: <code>msg.sender</code>) to get the address used in the consolidation request, i.e. the address that calls the system contract must match the 0x01 withdrawal credential recorded in the beacon state.</p> <p>Note: the above code reverts if the fee is too high, the fee can change significantly between the creation of a consolidation request transaction and its inclusion into a block, thus, this check is very important to avoid overpayments.</p> <p>Using an EOA to request consolidations will always result in overpayment of fees. There is no way for an EOA to use a wrapper contract to request a consolidation. And even if a way existed, the gas cost of returning the overage would likely be higher than the overage itself. If requesting consolidations from an EOA to the system contract is desired, we recommend that users perform transaction simulations to estimate a reasonable fee amount to send.</p> <h3 id="consolidation-queue-hard-limit">Consolidation queue hard limit</h3> <p>Consolidations exceeding the hard limit of the consolidation queue (262,144 requests) will be discarded by the consensus layer and will need to be re-submitted, note that the fee is not refunded in this case.</p> <h3 id="system-call-failure">System Call failure</h3> <p>Although the likelihood of a failed system call to <code>CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</code> is extremely low, the behavior in such cases is well-defined: the block is marked as invalid. This consideration directly follows from <a href="https://wg-eips.ritovision.com/7002/#system-call-failure">EIP-7002</a></p> <h3 id="empty-code-failure">Empty Code failure</h3> <p>This EIP should not have been activated if there is no code present at <code>CONSOLIDATION_REQUEST_PREDEPLOY_ADDRESS</code> (i.e., if the chain is not "ready"). This is also similar to the consideration in <a href="https://wg-eips.ritovision.com/7002/#empty-code-failure">EIP-7002</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-06-27T00:00:00+00:00 2026-02-11T14:48:25+00:00 Coburn Berryhttps://github.com/coburncoburn Mykel Pereirahttps://github.com/mykelp Scott Silverhttps://github.com/scott-silver https://wg-eips.ritovision.com/7246/

A token interface to allow pledging tokens without transferring ownership.

<h2 id="abstract">Abstract</h2> <p>This ERC proposes an extension to the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token standard by adding Encumber—the ability for an account to grant another account exclusive right to move some portion of their balance. Encumber is a stronger version of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> allowances. While <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> approve grants another account the permission to transfer a specified token amount, encumber grants the same permission while ensuring that the tokens will be available when needed.</p> <h2 id="motivation">Motivation</h2> <p>This extension adds flexibility to the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token standard and caters to use cases where token locking is required, but it is preferential to maintain actual ownership of tokens. This interface can also be adapted to other token standards, such as <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, in a straightforward manner</p> <p>Token holders commonly transfer their tokens to smart contracts which will return the tokens under specific conditions. In some cases, smart contracts do not actually need to hold the tokens, but need to guarantee they will be available if necessary. Since allowances do not provide a strong enough guarantee, the only way to do guarantee token availability presently is to transfer the token to the smart contract. Locking tokens without moving them gives more clear indication of the rights and ownership of the tokens. This allows for airdrops and other ancillary benefits of ownership to reach the true owner. It also adds another layer of safety, where draining a pool of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens can be done in a single transfer, iterating accounts to transfer encumbered tokens would be significantly more prohibitive in gas usage.</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 compliant token 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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Interface of the ERC-7246 standard.</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"> IERC7246</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 `amount` tokens are encumbered from `owner` to `taker`.</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"> Encumber</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"> taker</span><span>, </span><span class="z-support">uint</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">@dev</span><span class="z-comment"> Emitted when the encumbrance of a `taker` to an `owner` is reduced by `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 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"> taker</span><span>, </span><span class="z-support">uint</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">@dev</span><span class="z-comment"> Returns the total amount of tokens owned by `owner` that are currently encumbered.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST never exceed `balanceOf(owner)`</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Any function which would reduce balanceOf(owner) below encumberedBalanceOf(owner) MUST 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"> encumberedBalanceOf</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-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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the number of tokens that `owner` has encumbered to `taker`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * This value increases when {encumber} or {encumberFrom} are called by the `owner` or by another permitted account.</span></span> <span class="giallo-l"><span class="z-comment"> * This value decreases when {release} and {transferFrom} are called by `taker`.</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"> encumbrances</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"> taker</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 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"> Increases the amount of tokens that the caller has encumbered to `taker` by `amount`.</span></span> <span class="giallo-l"><span class="z-comment"> * Grants to `taker` a guaranteed right to transfer `amount` from the caller&#39;s balance by using `transferFrom`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if caller does not have `amount` tokens available</span></span> <span class="giallo-l"><span class="z-comment"> * (e.g. if `balanceOf(caller) - encumberedBalanceOf(caller) &lt; amount`).</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {Encumber} 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"> encumber</span><span>(</span><span class="z-support">address</span><span class="z-variable"> taker</span><span>,</span><span class="z-support"> uint</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">@dev</span><span class="z-comment"> Increases the amount of tokens that `owner` has encumbered to `taker` by `amount`.</span></span> <span class="giallo-l"><span class="z-comment"> * Grants to `taker` a guaranteed right to transfer `amount` from `owner` using transferFrom</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * The function SHOULD revert unless the owner account has deliberately authorized the sender of the message via some mechanism.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if `owner` does not have `amount` tokens available</span></span> <span class="giallo-l"><span class="z-comment"> * (e.g. if `balanceOf(owner) - encumberedBalanceOf(owner) &lt; amount`).</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {Encumber} 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"> encumberFrom</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"> taker</span><span>,</span><span class="z-support"> uint</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">@dev</span><span class="z-comment"> Reduces amount of tokens encumbered from `owner` to caller by `amount`</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {Release} 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"> release</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>,</span><span class="z-support"> uint</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> <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"> Convenience function for reading the unencumbered balance of an address.</span></span> <span class="giallo-l"><span class="z-comment"> * Trivially implemented as `balanceOf(owner) - encumberedBalanceOf(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"> availableBalanceOf</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">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The specification was designed to complement and mirror the ERC-20 specification to ease adoption and understanding. The specification is intentionally minimally proscriptive of this joining, where the only true requirement is that an owner cannot transfer encumbered tokens. However, the example implementation includes some decisions about where to connect with ERC-20 functions worth noting. It was designed for minimal invasiveness of standard ERC-20 definitions.</p> <ul> <li>The example has a dependency on <code>approve</code> to facilitate <code>encumberFrom</code>. This proposal allows for an implementer to define another mechanism, such as an <code>approveEncumber</code> which would mirror ERC-20 allowances, if desired.</li> <li><code>transferFrom(src, dst, amount)</code> is written to first reduce the <code>encumbrances(src, amount)</code>, and then subsequently spend from <code>allowance(src, msg.sender)</code>. Alternatively, <code>transferFrom</code> could be implemented to spend from allowance simultaneously to spending encumbrances. This would require <code>approve</code> to check that the approved balance does not decrease beneath the amount required by encumbered balances, and also make creating the approval a prerequisite to calling <code>encumber</code>.</li> </ul> <p>It is possible to stretch the Encumber interface to cover ERC-721 tokens by using the <code>tokenId</code> in place of <code>amount</code> param since they are both <code>uint</code>. The interface opts for clarity with the most likely use case (ERC-20), even if it is compatible with other formats.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is backwards compatible with the existing <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard. Implementations must add the functionality to block transfer of tokens that are encumbered to another account.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>This can be implemented as an extension of any base <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> contract by modifying the transfer function to block the transfer of encumbered tokens and to release encumbrances when spent via transferFrom.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> An erc-20 token that implements the encumber interface by blocking transfers.</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 class="z-keyword">import</span><span> {</span><span class="z-entity z-name">ERC20</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;../lib/openzeppelin-contracts/contracts/token/ERC20/ERC20.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> { </span><span class="z-entity z-name">IERC7246</span><span> }</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./IERC7246.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"> EncumberableERC20</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC20</span><span>, </span><span class="z-entity z-name">IERC7246</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Owner -&gt; Taker -&gt; Amount that can be taken</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">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> encumbrances</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The encumbered balance of the token owner. encumberedBalance must not exceed balanceOf for a user</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-keyword"> Note</span><span class="z-comment"> this means rebasing tokens pose a risk of diminishing and violating this prototocol</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"> public</span><span> encumberedBalanceOf</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"> public</span><span> minter</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"> ERC20</span><span>(</span><span>name, symbol) </span><span>{</span></span> <span class="giallo-l"><span> minter </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 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"> recipient</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> {</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> minter</span><span>,</span><span class="z-string"> &quot;only minter&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _mint</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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> encumber</span><span>(</span><span class="z-support">address</span><span class="z-variable"> taker</span><span>,</span><span class="z-support"> uint</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 class="z-entity z-name"> _encumber</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> taker</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-storage z-type"> function</span><span class="z-entity z-name"> encumberFrom</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"> taker</span><span>,</span><span class="z-support"> uint</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 class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">allowance</span><span>(</span><span>owner</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> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _encumber</span><span>(</span><span>owner</span><span>,</span><span> taker</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-storage z-type"> function</span><span class="z-entity z-name"> release</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>,</span><span class="z-support"> uint</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 class="z-entity z-name"> _release</span><span>(</span><span>owner</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 class="z-comment"> If bringing balance and encumbrances closer to equal, must check</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> availableBalanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> a</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 class="z-keyword"> return</span><span> (</span><span class="z-entity z-name">balanceOf</span><span>(</span><span>a</span><span>)</span><span class="z-keyword"> -</span><span> encumberedBalanceOf</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-storage z-type"> function</span><span class="z-entity z-name"> _encumber</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"> taker</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> amount</span><span>)</span><span class="z-storage z-type"> private</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">availableBalanceOf</span><span>(</span><span>owner</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-keyword">=</span><span> amount</span><span>,</span><span class="z-string"> &quot;insufficient balance&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> encumbrances</span><span>[</span><span>owner</span><span>]</span><span>[</span><span>taker</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span> encumberedBalanceOf</span><span>[</span><span>owner</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Encumber</span><span>(</span><span>owner</span><span>,</span><span> taker</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-storage z-type"> function</span><span class="z-entity z-name"> _release</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"> taker</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> amount</span><span>)</span><span class="z-storage z-type"> private</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>encumbrances</span><span>[</span><span>owner</span><span>]</span><span>[</span><span>taker</span><span>]</span><span class="z-keyword"> &lt;</span><span> amount</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> amount </span><span class="z-keyword">=</span><span> encumbrances</span><span>[</span><span>owner</span><span>]</span><span>[</span><span>taker</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> encumbrances</span><span>[</span><span>owner</span><span>]</span><span>[</span><span>taker</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span> encumberedBalanceOf</span><span>[</span><span>owner</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Release</span><span>(</span><span>owner</span><span>,</span><span> taker</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-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"> dst</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-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-comment"> //</span><span class="z-comment"> check but dont spend encumbrance</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">availableBalanceOf</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> amount</span><span>,</span><span class="z-string"> &quot;insufficient balance&quot;</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-language">msg.sender</span><span>,</span><span> dst</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> <span class="giallo-l"></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"> src</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> dst</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-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-support"> uint</span><span> encumberedToTaker </span><span class="z-keyword">=</span><span> encumbrances</span><span>[</span><span>src</span><span>]</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"> bool</span><span> exceedsEncumbrance </span><span class="z-keyword">=</span><span> amount </span><span class="z-keyword">&gt;</span><span> encumberedToTaker</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>exceedsEncumbrance</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> excessAmount </span><span class="z-keyword">=</span><span> amount </span><span class="z-keyword">-</span><span> encumberedToTaker</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> check that enough unencumbered tokens exist to spend from allowance</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">availableBalanceOf</span><span>(</span><span>src</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-keyword">=</span><span> excessAmount</span><span>,</span><span class="z-string"> &quot;insufficient balance&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"> Exceeds Encumbrance , so spend all of it</span></span> <span class="giallo-l"><span class="z-entity z-name"> _spendEncumbrance</span><span>(</span><span>src</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span> encumberedToTaker</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> _spendAllowance</span><span>(</span><span>src</span><span>,</span><span> dst</span><span>,</span><span> excessAmount</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"> _spendEncumbrance</span><span>(</span><span>src</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-entity z-name"> _transfer</span><span>(</span><span>src</span><span>,</span><span> dst</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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _spendEncumbrance</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"> taker</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amount</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-support"> uint256</span><span> currentEncumbrance </span><span class="z-keyword">=</span><span> encumbrances</span><span>[</span><span>owner</span><span>]</span><span>[</span><span>taker</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>currentEncumbrance </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> amount</span><span>,</span><span class="z-string"> &quot;insufficient encumbrance&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> newEncumbrance </span><span class="z-keyword">=</span><span> currentEncumbrance </span><span class="z-keyword">-</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span> encumbrances</span><span>[</span><span>owner</span><span>]</span><span>[</span><span>taker</span><span>]</span><span class="z-keyword"> =</span><span> newEncumbrance</span><span>;</span></span> <span class="giallo-l"><span> encumberedBalanceOf</span><span>[</span><span>owner</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> amount</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"> Release</span><span>(</span><span>owner</span><span>,</span><span> taker</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></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Parties relying on <code>balanceOf</code> to determine the amount of tokens available for transfer should instead rely on <code>balanceOf(account) - encumberedBalance(account)</code>, or, if implemented, <code>availableBalanceOf(account)</code>.</p> <p>The property that encumbered balances are always backed by a token balance can be accomplished in a straightforward manner by altering <code>transfer</code> and <code>transferFrom</code> to block . If there are other functions that can alter user balances, such as a rebasing token or an admin burn function, additional guards must be added by the implementer to likewise ensure those functions prevent reducing <code>balanceOf(account)</code> below <code>encumberedBalanceOf(account)</code> for any given 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-06-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Chloe Guchloe@carv.io Navid X.https://github.com/xuxinlai2002 Victor Yuvictor@carv.io Archer H. https://wg-eips.ritovision.com/7231/

The aggregation of web2 & web3 identities to NFTs, authorized by individuals, gives attributes of ownerships, relationships, experiences.

<h2 id="abstract">Abstract</h2> <p>This standard extends <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> by binding individuals' Web2 and Web3 identities to non-fungible tokens (NFTs) and soulbound tokens (SBTs). By binding multiple identities, aggregated and composible identity infomation can be verified, resulting in more beneficial onchain scenarios for individuals, such as self-authentication, social overlapping, commercial value generation from user targetting, etc. By adding a custom schema in the metadata, and updating and verifying the schema hash in the contract, the binding of NFT and identity information is completed.</p> <h2 id="motivation">Motivation</h2> <p>One of the most interesting aspects of Web3 is the ability to bring an individual's own identity to different applications. Even more powerful is the fact that individuals truly own their accounts without relying on centralized gatekeepers, disclosing to different apps components necessary for authentication and approved by individuals. Exisiting solutions such as ENS, although open, decentralized, and more convenient for Ethereum-based applications, suffer from a lack of data standardization and authentication of identity due to inherent anominity. Other solutions such as SBTs rely on centralized attestors, can not prevent data tampering, and do not inscribe data into the ledger itself in a privacy enabling way.<br /> The proposed pushes the boundaries of solving identity problems with Identity Aggregated NFT, i.e., the individual-authenticated aggregation of web2 and web3 identities to NFTs (SBTs included).</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="every-compliant-contract-must-implement-the-interface">Every compliant contract must implement the Interface</h3> <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.15</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"> IERC7231</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"> emit the use binding information</span></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"> nft 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"> identitiesRoot</span><span class="z-comment"> new identity root</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"> SetIdentitiesRoot</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"> bytes32</span><span class="z-variable"> identitiesRoot</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"> </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 user ID binding information of NFT with identitiesRoot</span></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"> nft 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"> identitiesRoot</span><span class="z-comment"> multi UserID Root data hash</span></span> <span class="giallo-l"><span class="z-comment"> * MUST allow external calls</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"> setIdentitiesRoot</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"> bytes32</span><span class="z-variable"> identitiesRoot</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"> </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> get the multi-userID root by NFTID</span></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"> nft id </span></span> <span class="giallo-l"><span class="z-comment"> * MUST return the bytes32 multiUserIDsRoot</span></span> <span class="giallo-l"><span class="z-comment"> * MUST NOT modify the state</span></span> <span class="giallo-l"><span class="z-comment"> * MUST allow external calls</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"> getIdentitiesRoot</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">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">@notice</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"> verify the userIDs binding </span></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"> nft 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"> userIDs</span><span class="z-comment"> userIDs for check</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> identitiesRoot</span><span class="z-comment"> msg hash to verify</span></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"> ECDSA signature </span></span> <span class="giallo-l"><span class="z-comment"> * MUST If the verification is passed, return true, otherwise return false</span></span> <span class="giallo-l"><span class="z-comment"> * MUST NOT modify the state</span></span> <span class="giallo-l"><span class="z-comment"> * MUST allow external calls</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"> verifyIdentitiesBinding</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support">address</span><span class="z-variable"> nftOwnerAddress</span><span>,</span><span class="z-support">string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> userIDs</span><span>,</span><span class="z-support">bytes32</span><span class="z-variable"> identitiesRoot</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 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></span></code></pre> <p>This is the “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">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 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</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">MultiIdentities</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">userID</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">User ID of Web2 and web3(DID)</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">verifierUri</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">Verifier Uri of the userID</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">memo</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">Memo of the userID</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">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">properties of the user ID information</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><h2 id="rationale">Rationale</h2> <p>Designing the proposal, we considered the following problems that are solved by this standard: <img src="https://wg-eips.ritovision.com/7231/./assets/img/Identity-aggregated-NFT-flow.png" alt="EIP Flow Diagram" /></p> <ol> <li>Resolve the issue of multiple ID bindings for web2 and web3. By incorporating the MultiIdentities schema into the metadata file, an authorized bond is established between user identity information and NFTs. This schema encompasses a userID field that can be sourced from a variety of web2 platforms or a decentralized identity (DID) created on blockchain. By binding the NFT ID with the UserIDInfo array, it becomes possible to aggregate multiple identities seamlessly.</li> <li>Users have full ownership and control of their data Once the user has set the metadata, they can utilize the setIdentitiesRoot function to establish a secure binding between hashed userIDs objects and NFT ID. As only the user holds the authority to carry out this binding, it can be assured that the data belongs solely to the user.</li> <li>Verify the binding relationship between data on-chain and off-chain data through signature based on <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> Through the signature method based on the <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> protocol, the verifyIdentiesBinding function of this EIP realizes the binding of the userID and NFT owner address between on-chain and off-chain. <ol> <li>NFT ownership validation</li> <li>UserID format validation</li> <li>IdentitiesRoot Consistency verification</li> <li>Signature validation from nft owner</li> </ol> </li> </ol> <p>As for how to verify the authenticity of the individuals' identities, wallets, accounts, there are various methods, such as zk-based DID authentication onchain, and offchain authentication algorithms, such as auth2, openID2, etc.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As mentioned in the specifications section, this standard can be fully <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> compatible by adding an extension function set. In addition, new functions introduced in this standard have many similarities with the existing functions in <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. This allows developers to easily adopt the standard quickly.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests are included in <a href="https://wg-eips.ritovision.com/7231/./assets/test/erc7231.ts"><code>erc7231.ts</code></a>.</p> <p>To run them in terminal, you can use the following commands:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cd ../assets/eip-7231</span></span> <span class="giallo-l"><span>npm install</span></span> <span class="giallo-l"><span>npx hardhat test</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p><code>ERC7231.sol</code> Implementation: <a href="https://wg-eips.ritovision.com/7231/./assets/contracts/ERC7231.sol"><code>ERC7231.sol</code></a></p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP standard can comprehensively empower individuals to have ownership and control of their identities, wallets, and relevant data by themselves adding or removing the NFTs and identity bound information.</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-06-24T00:00:00+00:00 2026-02-11T14:48:25+00:00 Orchid-Devhttps://github.com/proj-orchid-straitsx Victor Liewhttps://github.com/alcedo Wong Tse Jianhttps://github.com/wongtsejian Jacob Shanhttps://github.com/Jacobshan429 Chin Sin Onghttps://github.com/chinsinong Praveen Kumarhttps://github.com/veenkumarr https://wg-eips.ritovision.com/7291/

An extension to ERC-1155 implementing a hybrid form of programmable payment and money.

<h2 id="abstract">Abstract</h2> <p>A Purpose Bound Money (PBM) token is a wrapper around an <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> token that can be used for a limited activity. This proposal outlines a smart contract interface that builds upon the ERC-1155 standard to implement the purpose bound money (PBM) concept:</p> <ul> <li>A PBM consists of a PBM wrapper and the digital money token it wraps. A digital money token (e.g., stablecoins, central bank digital currencies, tokenized bank deposits, and similar instruments) serves as a store of value (abbreviated as "sov"). Thus, a digital money token (also referred to as "sovToken") <strong>SHOULD</strong> be: <ul> <li>a good store of value;</li> <li>a suitable unit of account; and</li> <li>a medium of exchange.</li> </ul> </li> <li>PBMs are bearer instruments, with self-contained programming logic, and can be transferred between two parties without involving intermediaries. It combines the concept of: <ul> <li>programmable payment - automatic execution of payments once a pre-defined set of conditions are met; and</li> <li>programmable money - the possibility of embedding rules within the medium of exchange itself that define or constrain its usage.</li> </ul> </li> <li>Once the conditions are met, sovToken is released, and it becomes unbounded once again. A PBM can be thought of as a digital cash voucher, because it places constraints on how a payer can use the PBM but does not impose any constraints on the merchant/redeemer because the PBM unwraps and releases the underlying digital money upon payment to the merchant/redeemer. This is akin to a physical cash voucher: the payer is restricted to purchases from the merchants specified by the issuer but the merchants accepting the vouchers can exchange the physical vouchers with the issuer for fiat money.</li> </ul> <p>In this EIP, we propose a modular structure consisting of a sovToken compatible with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> as the digital money, an ERC-1155 compatible smart contract as the PBM wrapper, a compliance guard smart contract as a component of the PBM Wrapper logic, and a PBM token manager smart contract to manage token registration and retrieval.</p> <h2 id="motivation">Motivation</h2> <p>Purpose Bound Money (PBM) enables digital currencies to carry conditions on how they can be spent, making them especially useful in real-world scenarios such as:</p> <ul> <li><strong>Government vouchers</strong> (e.g. CDC vouchers in Singapore), where funds should only be redeemable at approved heartland merchants;</li> <li><strong>Conditional disbursements</strong>, such as SkillsFuture learning accounts, where funds are released only after course participation is verified;</li> <li><strong>Escrow-style payments</strong>, like homebuyer milestones, where payouts to developers are tied to the completion of specific construction stages;</li> </ul> <p>This proposal intends to forestall technology fragmentation and consequently a lack of interoperability. By making the PBM specification open, it gives new participants easy and free access to the pre-existing market standards, enabling interoperability across different platforms, wallets, payment systems and rails. This would lower cost of entry for new participants, foster a vibrant payment landscape and prevent the development of walled gardens and monopolies, ultimately leading to more efficient, affordable services and better user experiences.</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="definitions">Definitions</h3> <ul> <li> <p><strong>sovToken</strong> - an ERC-20 or ERC-20 compatible digital currency (e.g. <a href="https://wg-eips.ritovision.com/777/">ERC-777</a>, <a href="https://wg-eips.ritovision.com/1363/">ERC-1363</a>) serving as the store of value token (i.e. collateral backing the PBM Token).</p> </li> <li> <p><strong>PBM Wrapper</strong> - an ERC-1155 compliant smart contract, which wraps the sovToken by specifying one or more conditions that have to be met (referred to as PBM business logic in subsequent section of this proposal). The PBM wrapper can be designed to be modular in nature, with core, plug-ins and hooks components (see section on PBM Architecture for elaboration). The PBM wrapper smart contract, together with adopted hooks smart contracts verifies that condition(s) has/have been met before unwrapping the underlying sovToken.</p> </li> <li> <p><strong>PBM Token</strong> - the sovToken and its PBM wrapper are collectively referred to as a PBM Token. PBM Tokens are represented as ERC-1155 tokens.</p> </li> <li> <p><strong>PBM Creator</strong> defines the conditions of the PBM Wrapper to create PBM Tokens.</p> </li> <li> <p><strong>Merchant / Redeemer</strong> - In the context of this proposal, a Merchant or a Redeemer is broadly defined as the ultimate recipient, or endpoint, for PBM tokens, to which these tokens are intrinsically directed or purpose-bound to. The identity of merchant/redeemer will be one of the validations performed by the compliance guard, which may be implemented as part of the PBM Wrapper smart contract or as a standalone compliance guard contract registered as a PBM hook.</p> </li> </ul> <h3 id="overview">Overview</h3> <ul> <li> <p>PBM <strong>SHALL</strong> adhere to the definition of "wrap" or "wrapping" to mean binding a token in accordance with PBM business logic throughout its lifecycle.</p> </li> <li> <p>PBM <strong>SHALL</strong> adhere to the definition of "unwrap" or "unwrapping" to mean the release of a token in accordance with the PBM business logic during its lifecycle stage.</p> </li> <li> <p>A valid PBM Token <strong>MUST</strong> consist of an underlying sovToken and a PBM Wrapper.</p> <ul> <li> <p>The sovToken can be wrapped either upon the creation of the PBM Token or at a later date.</p> </li> <li> <p>A sovToken can be implemented as any widely accepted ERC-20 compatible token, such as ERC-20, ERC-777, or ERC-1363.</p> </li> </ul> </li> <li> <p>PBM Wrapper <strong>MUST</strong> provide a mechanism for all transacting parties to verify that all necessary condition(s) have been met before allowing the PBM Token to be unwrapped. Refer to Auditability section for elaborations. The necessary conditions can be implemented within the PBM wrapper, or in a separate PBM hook(s) smart contract(s).</p> </li> <li> <p>PBM Wrapper <strong>MUST</strong> ensure the destination address for unwrapped sovToken is in a whitelist of Merchant/Redeemer addresses and not in a blacklist of banned addresses prior to unwrapping the underlying sovToken.</p> </li> <li> <p>The PBM Token <strong>MUST</strong> be burnt upon being fully unwrapped and used.</p> </li> <li> <p>A PBM Token <strong>SHOULD</strong> have an expiry time that is decided by the PBM Creator.</p> <ul> <li>For cases where an expiry time is not needed, the expiry time <strong>SHOULD</strong> be set to infinity (typically represented as the maximum value of uint256 or type(uint256).max).</li> </ul> </li> <li> <p>This proposal defines a base specification of what a PBM should entail. Extensions to this base specification can be implemented as separate specifications.</p> </li> </ul> <h3 id="pbm-architecture">PBM Architecture</h3> <p>In this EIP, we propose a modular PBM architecture that has three distinct components (the core, the plugins and the hooks):</p> <ul> <li>The <strong>core components</strong> contains basic functionalities and validation checks that all PBMs should have. Core components includes sovToken and PBM wrapper containing the core logic (e.g. logic to whitelist the merchant/redeemer address, logic to unwrap upon transfer to a whitelisted address, logic for minting and burning the PBM) and a token manager which allows for token registration, retrieval. In addition, the PBM wrapper <strong>MAY</strong> include logic to interface with plugins and hooks.</li> <li>The <strong>plugin components</strong> implement additional functionality that only specific PBMs may require (e.g. logic to call external application programming interfaces to verify specific PBM condition was met, logic to track PBM usage patterns).</li> <li>The <strong>hook components</strong> implement additional validation checks that some PBMs may need (e.g. checks for expiration, daily spending limit, goods &amp; services limit etc).</li> </ul> <p>For example, a PBM creator may want to ensure that only 50% of PBM Series A can be spent in supermarkets, while there are no restrictions on the proportion of PBM Series B that can be spent in supermarkets. The creator can implement a plugin smart contract to keep track of supermarket spending by PBM users and a hook to validate that less than 50% of the PBM Series A issued to a user is spent in a supermarket. This approach allows the same generic PBM wrapper and sovToken to be used for both PBM Series A and B. In addition, PBM Series A will register the plugin module and hook module for additional data tracking and validations.</p> <h3 id="auditability">Auditability</h3> <p>PBM Wrapper <strong>SHOULD</strong> provide the public easily accessible mechanism(s) to verify the smart contract logic for unwrapping a PBM. Such mechanisms could be leveraged by automated validation or asynchronous user verifications from transacting parties and/or whitelisted third parties attestations.</p> <p>As the fulfilment of PBM conditions is likely to be subjected to audits to ensure trust amongst all transacting parties, the following evidence shall be documented to support audits:</p> <ul> <li>The interface/events emitted <strong>SHOULD</strong> allow a fine-grained recreation of the transaction history, token types and token balances</li> <li>The source code <strong>SHOULD</strong> be verified and formally published on a blockchain explorer.</li> </ul> <h3 id="fungibility">Fungibility</h3> <p>A PBM Wrapper <strong>SHOULD</strong> be able to wrap multiple types of compatible sovTokens (e.g. the same PBM Wrapper should be able to wrap USDC and XSGD). sovTokens wrapped by the same PBM wrapper may or may not be fungible to one another. The standard does NOT mandate how an implementation must do this.</p> <h3 id="pbm-token-details">PBM token details</h3> <p>The ERC-1155 Multi Token Standard enables each token ID to correspond to a unique, configurable token type. All essential details facilitating the business or display logic for a PBM <strong>MUST</strong> be defined for each token type. The mandatory fields for this purpose are outlined in the <code>struct PBMToken</code> (below). Future proposals may define additional, optional state variables as needed. Once a token detail has been defined, it <strong>MUST</strong> be immutable.</p> <p>Example of token details:</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"> IPBMRC1_TokenManager</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 PBM token MUST include compulsory state variables (name, faceValue, expiry, and uri) to adhere to this standard.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Represents all the details corresponding to a PBM tokenId.</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> PBMToken</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Name of the token.</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> name</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Value of the underlying wrapped ERC20-compatible sovToken. Additional information on the `faceValue` can be specified by</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> adding the optional variables: `currencySymbol` or `tokenSymbol` as indicated below</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> faceValue</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Time after which the token will be rendered useless (expressed in Unix Epoch time).</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> expiry</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Metadata URI for ERC-1155 display purposes.</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> uri</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>An implementer of the standard can enhance their PBM tokens with additional functionality by implementing the <code>IPBMRC1_TokenManagerExt</code> interface. This extension provides optional properties that can be used to support a variety of use cases beyond the core requirements.</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"> IPBMRC1_TokenManagerExt</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"> Optional properties that a PBM token MAY include for extended functionality.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Represents additional optional fields that can be implemented for a PBM tokenId.</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> PBMTokenExt</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Indicates if the PBM token can be transferred to a non merchant/redeemer wallet.</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isTransferable</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Determines whether the PBM will be burned or revoked upon expiry, under certain predefined conditions, or at the owner&#39;s discretion.</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> burnable</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Number of decimal places for the token.</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> decimals</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The address of the creator of this PBM type on this smart contract. This field is optional because the creator is msg.sender by default.</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> creator</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The smart contract address of the sovToken.</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> tokenAddress</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The running balance of the PBM Token type that has been minted.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> totalSupply</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> An ISO4217 three-character alphabetic code may be needed for the faceValue in multicurrency PBM use cases.</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> currencySymbol</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> An abbreviation for the PBM token name may be assigned.</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> tokenSymbol</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Add other optional state variables below...</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>An implementer has the option to define all token types upon PBM contract deployment. If needed, they can also expose an external function to create new PBM tokens at a later time. All token types created <strong>SHOULD</strong> emit a <code>NewPBMTypeCreated</code> event.</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"> @notice</span><span class="z-comment"> Creates a new PBM Token type with the provided data.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The caller of createPBMTokenType shall be responsible for setting the creator address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Example of uri can be found in [`sample-uri`](./assets/sample-uri/stx-10-static)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST Emit the {NewPBMTypeCreated} 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"> _name</span><span class="z-comment"> Name of 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"> _faceValue</span><span class="z-comment"> Value of the underlying wrapped ERC20-compatible sovToken.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _tokenExpiry</span><span class="z-comment"> Time after which the token will be rendered useless (expressed in Unix Epoch 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"> _tokenURI</span><span class="z-comment"> Metadata URI for ERC-1155 display purposes</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createPBMTokenType</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 class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _faceValue</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _tokenExpiry</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"> _tokenURI</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">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"> Emitted when a new Purpose-Bound Token (PBM) type is created within 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"> tokenId</span><span class="z-comment"> The unique identifier for the newly created PBM token type.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenName</span><span class="z-comment"> A human-readable string representing the name of the newly created PBM token type.</span></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"> The initial supply of the newly created PBM token type.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> expiry</span><span class="z-comment"> The timestamp at which the newly created PBM token type will expire.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> creator</span><span class="z-comment"> The address of the account that created the new PBM token type.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> NewPBMTypeCreated</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"> tokenName</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"> expiry</span><span>, </span><span class="z-support">address</span><span class="z-variable"> creator</span><span>)</span><span>;</span></span> <span class="giallo-l"></span></code></pre> <p>Implementors of the standard <strong>MUST</strong> define a method to retrieve a PBM token detail</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"> @notice</span><span class="z-comment"> Retrieves the details of a PBM Token type given its tokenId.</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 fetches the PBMToken struct associated with the tokenId and returns 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"> tokenId</span><span class="z-comment"> The identifier of the PBM token type.</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"> pbmToken_</span><span class="z-comment"> A PBMToken struct containing all the details of the specified PBM token type.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTokenDetails</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-storage z-type">PBMToken</span><span class="z-storage z-type"> memory</span><span class="z-variable"> pbmToken_</span><span>)</span><span>;</span></span></code></pre><h3 id="compliance-guard">Compliance Guard</h3> <p>A compliance guard should have logic to store and retrieve whitelisted merchants/redeemers and blacklisted addresses to fulfill the basic premise of a PBM. Additional logic can be added to fulfill other compliance goals.</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"> Compliance Guard Interface.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> The compliance guard stores and manages whitelisted merchants/redeemers and blacklisted addresses for the PBMs</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IComplianceGuard</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 if the address is one of the blacklisted addresses</span></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 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"> bool_</span><span class="z-comment"> True if address is blacklisted, else false</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isBlacklisted</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-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> 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"> Checks if the address is one of the whitelisted merchant/redeemer addresses</span></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 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"> bool_</span><span class="z-comment"> True if the address is in merchant/redeemer whitelist and is NOT a blacklisted address, otherwise false.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isMerchant</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-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> 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"> Event emitted when the Merchant/Redeemer List is edited</span></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"> Tags &quot;add&quot; or &quot;remove&quot; for action type</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> addresses</span><span class="z-comment"> An array of merchant wallet addresses that was just added or removed from Merchant/Redeemer whitelist</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> metadata</span><span class="z-comment"> Optional comments or notes about the added or removed addresses.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MerchantList</span><span>(</span><span class="z-support">string</span><span class="z-variable"> action</span><span>, </span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-variable"> addresses</span><span>, </span><span class="z-support">string</span><span class="z-variable"> metadata</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 emitted when the Blacklist is edited</span></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"> Tags &quot;add&quot; or &quot;remove&quot; for action type</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> addresses</span><span class="z-comment"> An array of wallet addresses that was just added or removed from address blacklist</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> metadata</span><span class="z-comment"> Optional comments or notes about the added or removed addresses.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Blacklist</span><span>(</span><span class="z-support">string</span><span class="z-variable"> action</span><span>, </span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-variable"> addresses</span><span>, </span><span class="z-support">string</span><span class="z-variable"> metadata</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h3 id="pbmrc1-base-interface">PBMRC1 - Base Interface</h3> <p>This interface contains the essential functions required to implement a pre-loaded PBM.</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-comment"> LIST OF EVENTS TO BE EMITTED</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> A database or explorer may listen to events and be able to provide indexed and categorized searches</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> PBM Specification interface</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> The PBM (purpose bound money) allows us to add logical requirements on the use of sovTokens.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> The PBM acts as wrapper around the sovTokens and implements the necessary business logic.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> PBM deployer must assign an overall owner to the smart contract. If fine grain access controls are required, EIP-5982 can be used on top of ERC173</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IPBMRC1</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC173</span><span>, </span><span class="z-entity z-name">IERC5679Ext1155</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"> Initialise the contract by specifying an underlying ERC20-compatible token address,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> contract expiry and PBM Wrapper Logic smart contract&#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"> _sovToken</span><span class="z-comment"> The address of the underlying sovToken.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _expiry</span><span class="z-comment"> The contract-wide expiry timestamp (in Unix epoch 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"> _pbmWrapperLogic</span><span class="z-comment"> This address should point to a smart contract that contains conditions governing a PBM;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> such as purpose-bound conditions (e.g., a compliance guard determining whether a PBM is permitted to be transferred or to be unwrapped)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and other relevant business logic, effectively implementing an inversion of control.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> initialise</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _sovToken</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _expiry</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _pbmWrapperLogic</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"> Returns the Uniform Resource Identifier (URI) metadata information for the PBM with the corresponding tokenId.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> URIs are defined in RFC 3986.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The URI MUST point to a JSON file that conforms to the &quot;ERC-1155 Metadata URI JSON Schema&quot;.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Developers may choose to adhere to the ERC1155Metadata_URI extension interface if necessary.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The URI is not expected to be immutable.</span></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 id for the PBM in 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"> Returns</span><span class="z-comment"> the metadata URI string for the PBM</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> uri</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 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"> Creates a PBM copy ( ERC1155 NFT ) of an existing PBM token type.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> See {IERC5679Ext1155} for further implementation notes</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> receiver</span><span class="z-comment"> The wallet address to which the created PBMs need to be transferred to</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 identifier of the PBM token type to be copied.</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"> The number of the PBMs that are to be created</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, based on EIP-5750</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> This function transfers the underlying token from the caller into the PBM smart contract.</span></span> <span class="giallo-l"><span class="z-comment"> IMPT: Before minting, the caller should approve the contract address to spend sovTokens on behalf of the caller.</span></span> <span class="giallo-l"><span class="z-comment"> This can be done by calling the `approve` or `increaseMinterAllowance` functions of the ERC-20 contract and specifying `_spender` to be the PBM contract address.</span></span> <span class="giallo-l"><span class="z-comment"> Ref : https://eips.ethereum.org/EIPS/eip-20</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> WARNING: Any contracts that externally call these safeMint() and safeMintBatch() functions should implement some sort of reentrancy guard procedure</span></span> <span class="giallo-l"><span class="z-comment"> (such as OpenZeppelin&#39;s ReentrancyGuard) or a Checks-effects-interactions pattern.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> As per ERC-5679 standard: When the token is being minted, the transfer events MUST be emitted as if the token in the `amount` for EIP-1155</span></span> <span class="giallo-l"><span class="z-comment"> and `tokenId` being _id for EIP-1155 were transferred from address 0x0 to the recipient address identified by receiver.</span></span> <span class="giallo-l"><span class="z-comment"> The total supply MUST increase accordingly.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> MUST Emit the {TokenWrap} event as the underlying sovToken is wrapped by the PBM wrapper smart contract during minting.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> - contract must not be paused</span></span> <span class="giallo-l"><span class="z-comment"> - tokens must not be expired</span></span> <span class="giallo-l"><span class="z-comment"> - `tokenId` should be a valid id that has already been created</span></span> <span class="giallo-l"><span class="z-comment"> - caller should have the necessary amount of the sovTokens required to mint</span></span> <span class="giallo-l"><span class="z-comment"> - caller should have approved the PBM contract to spend the sovTokens</span></span> <span class="giallo-l"><span class="z-comment"> - receiver should not be blacklisted</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"> safeMint</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"> tokenId</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"> calldata</span><span class="z-variable"> data</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"> Creates multiple PBM copies (ERC1155 NFT) of an existing PBM token type.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> See {IERC5679Ext1155}.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> receiver</span><span class="z-comment"> The wallet address to which the created PBMs need to be transferred to</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> The identifier of the PBM token type</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"> The number of the PBMs that are to be created</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, based on eip-5750</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> This function will transfer the underlying token from the caller into the PBM smart contract.</span></span> <span class="giallo-l"><span class="z-comment"> IMPT: Before minting, the caller should approve the contract address to spend sovTokens on behalf of the caller.</span></span> <span class="giallo-l"><span class="z-comment"> This can be done by calling the `approve` or `increaseMinterAllowance` functions of the ERC-20 contract and specifying `_spender` to be the PBM contract address.</span></span> <span class="giallo-l"><span class="z-comment"> Ref : https://eips.ethereum.org/EIPS/eip-20</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> WARNING: Any contracts that externally call these safeMint() and safeMintBatch() functions should implement some sort of reentrancy guard procedure</span></span> <span class="giallo-l"><span class="z-comment"> (such as OpenZeppelin&#39;s ReentrancyGuard) or a Checks-effects-interactions pattern.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> As per ERC-5679 standard: When the token is being minted, the transfer events MUST be emitted as if the token in the `amount` for EIP-1155</span></span> <span class="giallo-l"><span class="z-comment"> and `tokenId` being _id for EIP-1155 were transferred from address 0x0 to the recipient address identified by receiver.</span></span> <span class="giallo-l"><span class="z-comment"> The total supply MUST increase accordingly.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> MUST Emit the {TokenWrap} event as the underlying sovToken is wrapped by PBM wrapper smart contract during minting.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> - contract must not be paused</span></span> <span class="giallo-l"><span class="z-comment"> - tokens must not be expired</span></span> <span class="giallo-l"><span class="z-comment"> - `tokenIds` should all be valid ids that have already been created</span></span> <span class="giallo-l"><span class="z-comment"> - `tokenIds` and `amounts` list need to have the same number of values</span></span> <span class="giallo-l"><span class="z-comment"> - caller should have the necessary amount of the sovTokens required to mint</span></span> <span class="giallo-l"><span class="z-comment"> - caller should have approved the PBM contract to spend the sovTokens</span></span> <span class="giallo-l"><span class="z-comment"> - receiver should not be blacklisted</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"> safeMintBatch</span><span>(</span><span class="z-support">address</span><span class="z-variable"> receiver</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"> tokenIds</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"> amounts</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>;</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"> Burns a PBM token. Upon burning of the tokens, the underlying wrapped token (if any) should be handled.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> Destroys `amount` tokens of token type `tokenId` from `from`</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> See {IERC5679Ext1155}</span></span> <span class="giallo-l"></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 originating wallet address of the PBMs to be burned</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 identifier of the PBM token type</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"> The amount of the PBMs that are to be burned</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, based on EIP-5750</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> MUST Emit the {TransferSingle} event.</span></span> <span class="giallo-l"><span class="z-comment"> MUST Emit the {TokenUnwrapForPBMBurn} event if the underlying wrapped token is moved out of the PBM smart contract.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> - `from` cannot be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> - `from` must have at least `amount` tokens of token type `tokenId`.</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"> burn</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"> tokenId</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"> calldata</span><span class="z-variable"> data</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"> Burns multiple PBM token. Upon burning of the tokens, the underlying wrapped token (if any) should be handled.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> Destroys `amount` tokens of token type `tokenId` from `from`</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> See {IERC5679Ext1155}</span></span> <span class="giallo-l"></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 originating wallet address of the PBMs to be burned</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> The identifier of the PBM token types</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"> The amount of the PBMs that are to be burned for each tokenId in _tokenIds</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, based on eip-5750</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> MUST Emit the {TransferSingle} event.</span></span> <span class="giallo-l"><span class="z-comment"> MUST Emit the {TokenUnwrapForPBMBurn} event if the underlying wrapped token is moved out of the PBM smart contract.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> - `from` cannot be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> - `from` must have at least amount specified in `_amounts` of the corresponding token type tokenId in `_tokenIds` 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"> burnBatch</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</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"> tokenIds</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"> amounts</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>;</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"> Transfers the PBM(NFT) from one wallet to another.</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 extends the ERC-1155 standard in order to allow the PBM token to be freely transferred between wallet addresses due to</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> widespread support across wallet providers. Specific conditions and restrictions on whether a pbm can be moved across addresses can be incorporated in this function.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Unwrap logic MAY also be placed within this function to be called.</span></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 account from which the PBM (NFT) is moving from</span></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 which is receiving the PBM (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"> id</span><span class="z-comment"> The identifier of the PBM token type</span></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"> The number of (quantity) the PBM type that are to be transferred of the PBM type</span></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"> To record any data associated with the transaction, can be left blank if none</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"> id</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>;</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"> Transfers the PBM(NFT)(s) from one wallet to another.</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 extends the ERC-1155 standard in order to allow the PBM token to be freely transferred between wallet addresses due to</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> widespread support across wallet providers. Specific conditions and restrictions on whether a pbm can be moved across addresses can be incorporated in this function.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Unwrap logic MAY also be placed within this function to be called.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If the receiving wallet is a whitelisted /redeemer wallet address, the PBM(NFT)(s) will be burnt and the underlying sovTokens will be transferred to the merchant/redeemer wallet instead.</span></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 account from which the PBM (NFT)(s) is moving from</span></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 which is receiving the PBM (NFT)(s)</span></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 identifiers of the different PBM token type</span></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"> The number of (quantity) the different PBM types that are to be created</span></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"> To record any data associated with the transaction, can be left blank if none.</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-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>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> ids</span><span>,</span><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 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>;</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"> Unwraps the underlying ERC-20 compatible tokens to an intended end point (ie: merchant/redeemer) upon fulfilling the required PBM conditions.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Add implementation specific logic for the conditions under which a PBM processes and transfers the underlying tokens here.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> e.g. If the receiving wallet is a whitelisted merchant/redeemer wallet address, the PBM (NFT) MUST be burnt and the underlying sovTokens</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> will unwrapped to be transferred to the merchant/redeemer wallet.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST Emit the {TokenUnwrapForTarget} event on success</span></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 account currently holding the PBM</span></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 the PBM (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 identifier of the PBM token type</span></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"> The quantity of the PBM type involved in this 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"> Additional data without a specified format, based on EIP-5750</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unwrap</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"> tokenId</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"> internal</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"> Allows the creator of a PBM token type to retrieve all locked-up underlying sovTokens within that PBM.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Ensure that only the creator of the PBM token type or the contract owner can call this function.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Validate the token state and existence, handle PBM token burning if necessary, safely transfer the remaining sovTokens to the originator,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST Emit the {PBMrevokeWithdraw} event upon a successful revoke.</span></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 of the PBM token type</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `tokenId` should be a valid identifier for an existing PBM token type.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - The caller must be either the creator of the token type or the smart contract owner.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokePBM</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Emitted when a PBM type creator withdraws the underlying sovTokens from all the remaining expired PBMs</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> beneficiary</span><span class="z-comment"> the address ( PBM type creator ) which receives the sovToken</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> PBMTokenId</span><span class="z-comment"> The identifiers of the different PBM token type</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sovToken</span><span class="z-comment"> The address of the underlying sovToken</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sovTokenValue</span><span class="z-comment"> The number of underlying sovTokens transferred</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> PBMrevokeWithdraw</span><span>(</span><span class="z-support">address</span><span class="z-variable"> beneficiary</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> PBMTokenId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> sovToken</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> sovTokenValue</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"> Emitted when the underlying tokens are unwrapped and transferred to a specific purpose-bound address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This event signifies the end of the PBM lifecycle, as all necessary conditions have been met to release the underlying tokens to the recipient (whitelisted merchant/redeemer with non-blacklisted wallet address).</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If there are multiple different underlying tokens involved in a single unwrap operation, this event should be emitted for each underlying 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"> from</span><span class="z-comment"> The address from which the PBM tokens are being unwrapped.</span></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 purpose-bound address receiving the unwrapped underlying 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"> tokenIds</span><span class="z-comment"> An array containing the identifiers of the unwrapped PBM token types.</span></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"> An array containing the quantities of the corresponding unwrapped PBM 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"> sovToken</span><span class="z-comment"> The address of the underlying sovToken.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sovTokenValue</span><span class="z-comment"> The amount of unwrapped underlying sovTokens transferred.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenUnwrapForTarget</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>[</span><span>]</span><span class="z-variable"> tokenIds</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">address</span><span class="z-variable"> sovToken</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> sovTokenValue</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"> Emitted when PBM tokens are burned, resulting in the unwrapping of the underlying tokens for the designated recipient.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This event is required if there is an unwrapping of the underlying tokens during the PBM (NFT) burning process.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If there are multiple different underlying tokens involved in a single unwrap operation, this event should be emitted for each underlying 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"> from</span><span class="z-comment"> The address from which the PBM tokens are being burned.</span></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 receiving the unwrapped underlying 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"> tokenIds</span><span class="z-comment"> An array containing the identifiers of the burned PBM token types.</span></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"> An array containing the quantities of the corresponding burned PBM 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"> sovToken</span><span class="z-comment"> The address of the underlying sovToken.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sovTokenValue</span><span class="z-comment"> The amount of unwrapped underlying sovTokens transferred.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenUnwrapForPBMBurn</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>[</span><span>]</span><span class="z-variable"> tokenIds</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">address</span><span class="z-variable"> sovToken</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> sovTokenValue</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Indicates the wrapping of a token into the PBM smart contract.</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 underlying tokens are wrapped within the PBM smart contract.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If there are multiple different underlying tokens involved in a single wrap operation, this event should be emitted for each underlying token.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This event signifies the beginning of the PBM lifecycle, as tokens are now managed by the conditions within the PBM 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"> from</span><span class="z-comment"> The address initiating the token wrapping process, and</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> An array containing the identifiers of the token types being wrapped.</span></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"> An array containing the quantities of the corresponding wrapped 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"> sovToken</span><span class="z-comment"> The address of the underlying sovToken.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sovTokenValue</span><span class="z-comment"> The amount of wrapped underlying sovTokens transferred.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenWrap</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> tokenIds</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">address</span><span class="z-variable"> sovToken</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> sovTokenValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h3 id="extensions">Extensions</h3> <h4 id="pbmrc1-token-receiver">PBMRC1 - Token Receiver</h4> <p>Smart contracts MUST implement all of the functions in the PBMRC1_TokenReceiver interface to subscribe to PBM unwrap callbacks.</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"> @notice</span><span class="z-comment"> Smart contracts MUST implement the ERC-165 `supportsInterface` function and signify support for the `PBMRC1_TokenReceiver` interface to accept callbacks.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> It is optional for a receiving smart contract to implement the `PBMRC1_TokenReceiver` interface</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> WARNING: Reentrancy guard procedure, Non delegate call, or the check-effects-interaction pattern must be adhere to when calling an external smart contract.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> The interface functions MUST only be called at the end of the `unwrap` function.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> PBMRC1_TokenReceiver</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"> Handles the callback from a PBM smart contract upon unwrapping</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> An PBM smart contract MUST call this function on the token recipient contract, at the end of a `unwrap` if the</span></span> <span class="giallo-l"><span class="z-comment"> receiver smart contract supports type(PBMRC1_TokenReceiver).interfaceId</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 initiated the transfer (either the address which previously owned the token or the address authorised to make transfers on the owner&#39;s behalf) (i.e. msg.sender)</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"> _id</span><span class="z-comment"> The ID of the token being unwrapped</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"> The amount of tokens 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;onPBMRC1Unwrap(address,address,uint256,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"> onPBMRC1Unwrap</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"> _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-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-keyword"> returns</span><span>(</span><span class="z-support">bytes4</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"> Handles the callback from a PBM smart contract upon unwrapping a batch of tokens</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> A PBM smart contract MUST call this function on the token recipient contract at the end of an `unwrap` if the</span></span> <span class="giallo-l"><span class="z-comment"> receiver smart contract supports type(PBMRC1_TokenReceiver).interfaceId</span></span> <span class="giallo-l"></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 initiated the transfer (either the address which previously owned the token or the address authorised to make transfers on the owner&#39;s behalf) (i.e. msg.sender)</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"> _id</span><span class="z-comment"> The ID of the token being unwrapped</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"> The amount of tokens 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;onPBMRC1BatchUnwrap(address,address,uint256,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"> onPBMRC1BatchUnwrap</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>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _ids</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"> _values</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-keyword"> returns</span><span>(</span><span class="z-support">bytes4</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h4 id="pbmrc2-non-preloaded-pbm-interface">PBMRC2 - Non preloaded PBM Interface</h4> <p>The <strong>Non Preloaded</strong> PBM extension is OPTIONAL for compliant smart contracts. This allows contracts to bind an underlying sovToken to the PBM at a later date instead of during a minting process.</p> <p>Compliant contract <strong>MUST</strong> implement the following 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-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 interface extends IPBMRC1, adding functions for working with non-preloaded PBMs.</span></span> <span class="giallo-l"><span class="z-comment"> * Non-preloaded PBMs are minted as empty containers without any underlying tokens of value,</span></span> <span class="giallo-l"><span class="z-comment"> * allowing the loading of the underlying token to happen at a later stage.</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"> PBMRC2_NonPreloadedPBM</span><span class="z-storage"> is</span><span class="z-entity z-name"> IPBMRC1</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"> This function extends IPBMRC1 to mint PBM tokens as empty containers without underlying tokens 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"> The loading of the underlying token of value can be done by calling the `load` function. The function parameters should be identical to IPBMRC1</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeMint</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"> tokenId</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"> calldata</span><span class="z-variable"> data</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"> This function extends IPBMRC1 to mint PBM tokens as empty containers without underlying tokens 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"> The loading of the underlying token of value can be done by calling the `load` function. The function parameters should be identical to IPBMRC1</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeMintBatch</span><span>(</span><span class="z-support">address</span><span class="z-variable"> 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"> ids</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"> amounts</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>;</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"> Wrap an amount of sovTokens into the PBM</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> function will pull sovTokens from msg.sender</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Approval must be given to the PBM smart contract in order to for the pbm to pull money from msg.sender</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> underlying data structure must record how much the msg.sender has been loaded into the PBM.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Emits {TokenLoad} 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"> amount</span><span class="z-comment"> The amount of sovTokens to be loaded</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> load</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieves the balance of the underlying sovToken associated with a specific PBM token type and user address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This function provides a way to check the amount of the underlying token that a user has loaded into a particular PBM 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"> user</span><span class="z-comment"> The address of the user whose underlying token balance is being 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"> The</span><span class="z-comment"> balance of the underlying sovToken associated with the specified PBM token type and user address.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> underlyingBalanceOf</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Unloads all of the underlying token belonging to the caller from the PBM smart contract.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The underlying token that belongs to the caller (msg.sender) will be removed and transferred</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> back to the caller.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Emits {TokenUnload} 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"> amount</span><span class="z-comment"> The quantity of the corresponding tokens to be unloaded.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Amount should not exceed the amount that the caller has originally loaded into the PBM smart contract.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unload</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Emitted when an underlying token is loaded into a PBM</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> caller</span><span class="z-comment"> Address by which sovToken is taken from.</span></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 by which the token is loaded and assigned 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"> amount</span><span class="z-comment"> The quantity of tokens to be loaded</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sovToken</span><span class="z-comment"> The address of the underlying sovToken.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sovTokenValue</span><span class="z-comment"> The amount of underlying sovTokens loaded</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenLoad</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"> to</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>, </span><span class="z-support">address</span><span class="z-variable"> sovToken</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> sovTokenValue</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"> Emitted when an underlying token is unloaded from a PBM.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This event indicates the process of releasing the underlying token from the PBM smart 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"> caller</span><span class="z-comment"> The address initiating the token unloading process.</span></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 token is being unloaded and removed from.</span></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"> The quantity of the corresponding unloaded 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"> sovToken</span><span class="z-comment"> The address of the underlying sovToken.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sovTokenValue</span><span class="z-comment"> The amount of unloaded underlying sovTokens transferred.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenUnload</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"> from</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>, </span><span class="z-support">address</span><span class="z-variable"> sovToken</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> sovTokenValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="why-sovtoken-must-be-erc-20-compatible">Why sovToken <strong>MUST</strong> be ERC-20 compatible?</h3> <p>As PBM is envisioned to have functionality of money, it has to be a fungible token with stable value. Currently, the major stablecoins in the market are mainly based on the ERC-20 interface. ERC-20 or ERC-20 compatible tokens are the most widely supported by existing wallets, defi apps, and used also by protocol design such as <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> and more importantly they are the de facto standard for fungible tokens.</p> <p>With regards to <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and ERC-1155 compatible tokens:</p> <ul> <li>ERC-721 is not suitable given that it is a standard for non-fungible tokens, which cannot fulfill the functions of money.</li> <li>While ERC-1155 tokens could be used for fungible tokens, we decided not to include it because there is a lack of ERC-1155 stablecoins in the market. Requiring the PBM interface to support both ERC-20 compatible and ERC-1155 compatible sovToken would complicate PBM interface without adding much practical utility. Furthermore, the base ERC-1155 does not support decimals, but this is not a dealbreaker as there can be workarounds. However, should there be changes in the stablecoin market in future, a revision can be considered.</li> </ul> <h3 id="why-pbm-wrapper-must-be-erc-1155-compatible">Why PBM Wrapper <strong>MUST</strong> be ERC-1155 compatible?</h3> <p>This paper extends the ERC-1155 standards in order to enable easy adoption by existing wallet providers. Currently, most wallet providers are able to support and display ERC-20, ERC-1155 and ERC-721 standards. An implementation which doesn't extend these standards will require the wallet provider to build a custom user interface and interfacing logic which increases the implementation cost and lengthen the time-to-market.</p> <p>The core aim of our proposal is to standardize the implementation of PBM. Hence, we have surveyed existing interface standards and decided to build upon ERC-1155 standard for the PBM tokens for the following reasons:</p> <ul> <li>ERC-1155 allows a single contract to support multiple tokens. This is very useful for the PBM use cases as a single contract can support issuance of tokens with different denominations, expiry dates, business logics.</li> <li>ERC-1155 also has batch transfer support, which is absent in ERC-20, which could lead to gas savings when tokens have to be airdropped to a large number of recipients.</li> <li>ERC-1155 is able to support semi-fungible tokens which could be very useful for PBM use cases as a PBM can be converted into a collectible after its expiry.</li> <li>ERC-1155 allows for a visualisation of a PBM token on the UI of a wallet issuer.</li> </ul> <h3 id="why-pbm-must-ensure-the-destination-address-for-unwrapped-sovtoken-is-in-a-whitelist-of-merchant-redeemer-addresses-and-not-in-a-blacklist-of-banned-addresses-prior-to-unwrapping-the-underlying-sovtoken">Why PBM <strong>MUST</strong> ensure the destination address for unwrapped sovToken is in a whitelist of Merchant/Redeemer addresses and not in a blacklist of banned addresses prior to unwrapping the underlying sovToken?</h3> <p>Why do we need a whitelist?</p> <ul> <li>The whitelist is a compulsory requirement because a PBM is purpose-bound, i.e., it should be unwrapped only if all conditions are fulfilled and it is transferred to someone in the predefined whitelist.</li> <li>In some implementations, developers can define a whitelisted address dynamically at runtime, such as requiring the presence of an NFT in a wallet address or relying on an oracle, etc.</li> </ul> <p>Why do we need a blacklist?</p> <ul> <li>The blacklist is a compulsory requirement to ensure that accounts which were banned for various reasons (e.g., address owner has re-registered a new account, address owner suspended, withdrawn, or expelled due to complaints or law enforcement reasons, etc.) are excluded.</li> </ul> <p>Why we can't have either a whitelist or a blacklist?</p> <ul> <li>While the same effect can be obtained by only having a whitelist, repeatedly redeploying the whitelist to the blockchain to ban one person is not gas efficient.</li> <li>Using only a blacklist to implement purpose-bound money is not practical as it would require maintaining a list of all addresses to be excluded and updating it whenever a new account is created.</li> </ul> <p>Why is there a need for destination?</p> <ul> <li>This forms the core of our proposal: a PBM can be unwrapped when only it is transferred to pre-approved destinations.</li> <li>PBMs can be transferred freely, but only the target is allowed to unwrap the PBM and take delivery of the underlying sovToken must be limited to differentiate it from plain vanilla stablecoins that are wrapped by smart contracts.</li> </ul> <h3 id="what-does-business-logic-encompass">What does business logic encompass?</h3> <ul> <li>In general, business logic can be categorized into core, plugin, and hook logic: <ul> <li>Core logic contains essential functionalities and validation checks and should be included in the PBM Wrapper contract.</li> <li>Plugin and hook logic can be implemented as standalone smart contract modules and are registered by the PBM Wrapper contract. Plugin logic extends the core logic by adding functionality, e.g., custom data collection, additional administrative functions, etc.</li> <li>Hook logic implements additional validation checks which are only applicable for a subset of PBMs.</li> </ul> </li> <li>"PBM business logic" can contain access control logic, PBM unwrapping logic, API logic to integrate with non-blockchain IT systems.</li> <li>As PBM can be used for a wide variety of use cases, ranging from government disbursement tokens, shopping vouchers, prepaid tokens, rewards points tokens, purpose-bound donation tokens, school allowance tokens, etc., with each use case having separate business logic, it was intentionally left undefined so that implementation authors can have maximum flexibility.</li> </ul> <h3 id="why-was-a-push-transaction-model-chosen">Why was a push transaction model chosen?</h3> <ul> <li>This standard sticks to the push transaction model where the transfer of PBM is initiated on the sender's side. Modern wallets can support the required PBM logic by embedding the unwrapping logic within the ERC-1155 <code>safeTransfer</code> function.</li> </ul> <h3 id="customisability">Customisability</h3> <p>Each ERC-1155 PBM Token would map to an underlying <code>PBMToken</code> data structure that implementers are free to customize in accordance to the business logic.</p> <p>By mapping the underlying ERC-1155 token model with an additional data structure, implementers gain flexibility in the management of multiple token types within the same smart contract with multiple conditional unwrapping logic attached to each token type, reducing gas costs as there is no need to deploy multiple smart contracts for each token type.</p> <ol> <li> <p>To keep it simple, this standard <em>intentionally</em> omits functions or events that doesn't add to definition and concept of a PBM.</p> </li> <li> <p>This EIP makes no assumptions about access control or the conditions under which a function can be executed. It is the responsibility of the PBM creator to determine the various roles involved in each specific PBM business flow.</p> </li> <li> <p>The proposed PBM Architecture <em>intentionally</em> modular to enable greater customisability and reusability of smart contracts.</p> </li> <li> <p>Metadata associated to the PBM standard is not included the standard. If necessary, related metadata can be created with a separate metadata extension interface, e.g. <code>ERC721Metadata</code> from ERC-721. Refer to Opensea's metadata-standards for an implementation example.</p> </li> <li> <p>To allow for future extensibility, it is <strong>RECOMMENDED</strong> that developers read and adopt the specifications for building general extensibility for method behaviours (<a href="https://wg-eips.ritovision.com/5750/">ERC-5750</a>).</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This interface is designed to be compatible with ERC-1155.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Reference implementations can be found in <a href="https://wg-eips.ritovision.com/7291/assets/README/"><code>README.md</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li> <p>Malicious users may attempt to:</p> <ul> <li>Double spend through reentrancy.</li> <li>clone existing PBM Tokens to perform double-spending;</li> <li>create invalid PBM Token with no underlying sovToken; or</li> <li>falsifying the face value of PBM token through wrapping of fraudulent/invalid/worthless sovTokens.</li> </ul> </li> <li> <p>For consistency, when the contract is suspended or a user's token transfer is restricted due to suspected fraudulent activity or erroneous transfers, corresponding restrictions <strong>MUST</strong> be applied to the user's unwrap requests for the PBM Token.</p> </li> <li> <p>Security audits and tests should be performed to verify that unwrap logic behaves as expected or if any complex business logic is being implemented that involves calling an external smart contract to prevent re-entrancy attacks and other forms of call chain attacks.</p> </li> <li> <p>This EIP relies on the secure and accurate bookkeeping behavior of the token implementation.</p> <ul> <li> <p>Contracts adhering to this standard should closely monitor balance changes for each user during token consumption or minting.</p> </li> <li> <p>The PBM Wrapper must be meticulously designed to ensure effective control over the permission to mint new tokens. Failure to secure the minting permission can lead to fraudulent issuance and unauthorized inflation of the total token supply.</p> </li> <li> <p>The mapping of each PBM Token to the corresponding amount of underlying sovToken held by the smart contract requires careful accounting and auditing.</p> </li> <li> <p>The access control over permission to burn tokens should be carefully designed. Typically, only the following two roles are entitled to burn a token:</p> <ul> <li>Role 1. Prior to a PBM's expiry, only whitelisted merchants/redeemers with non-blacklisted wallet addresses are allowed to unwrap and burn tokens that they hold.</li> <li>Role 2. After a PBM has expired: <ul> <li>whitelisted merchants/redeemers with non-blacklisted wallet addresses are allowed to unwrap and burn tokens that they hold; and</li> <li>PBM owners are allowed to burn unused PBM Tokens remaining in the hands of non-whitelisted merchants/redeemers to retrieve underlying sovTokens.</li> </ul> </li> </ul> </li> <li> <p>Nevertheless, we do recognize there are potentially other use cases where a third type of role may be entitled to burning. Implementors should be cautious when designing access control over burning of PBM Tokens.</p> </li> </ul> </li> <li> <p>It is recommended to adopt a sovToken standard that is compatible with ERC-20. Examples of such compatible tokens include those implementing ERC-777 or ERC-1363. However, ERC-20 remains the most widely accepted due to its simplicity and there is a high degree of confidence in its security.</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> 2023-06-24T00:00:00+00:00 2026-02-11T14:48:25+00:00 msfewhttps://github.com/fewwwww https://wg-eips.ritovision.com/7729/

An ERC-20 extension for tokens with metadata.

<h2 id="abstract">Abstract</h2> <p>This standard extends the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard to include a <code>metadata</code> function interface and a JSON schema for metadata.</p> <h2 id="motivation">Motivation</h2> <p>Memecoins have demonstrated the value of associating tokens with visual metadata. By standardizing a way to include metadata in ERC-20 tokens, developers can create more engaging and interactive tokens, fostering community engagement.</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> <p><strong>Every compliant contract must implement the <code>IERC7729</code>, and <a href="https://wg-eips.ritovision.com/20/"><code>ERC20</code></a> interfaces.</strong></p> <p>This standard includes the following 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"> IERC20Metadata</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-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Returns the metadata URI associated with the token.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The URI may point to a JSON file that conforms to the &quot;ERCX Metadata JSON Schema&quot;.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> metadata</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></code></pre> <p>This is the "<a href="https://wg-eips.ritovision.com/7729/">ERC-7729</a> 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">Token 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 token 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 token 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 token 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><h2 id="rationale">Rationale</h2> <p>The <code>metadata</code> function was chosen based on existing implementations in standards and applications.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is backward compatible with the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> as it extends the existing functionality with new interfaces.</p> <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.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/ERC20/ERC20.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"> IERC7729</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"> metadata</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 class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC7729</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC20</span><span>, </span><span class="z-entity z-name">IERCX</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> _metadata </span><span class="z-keyword">=</span><span class="z-string"> &quot;ipfs://QmakTsyRRmvihYwiAstYPYAeHBfaPYz3v9z2mkA1tYLA4w&quot;</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"> metadata</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> _metadata</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 metadata URI could be manipulated to point to malicious content or phishing sites. Off-chain indexers should perform validation checks to ensure the security and integrity of the metadata URIs for 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> 2023-06-21T00:00:00+00:00 2026-02-11T14:48:25+00:00 Xianghttps://github.com/wenzhenxiang Ben77https://github.com/ben2077 Mingshi S.https://github.com/newnewsms https://wg-eips.ritovision.com/7196/

Designed for smart contract wallets, this removes the transferFrom, approve, and allowance functions from ERC-20 tokens.

<h2 id="abstract">Abstract</h2> <p>This ERC is a new asset designed based on the user contract wallet (including account abstraction), and is forward compatible with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. To keep token assets simple, this ERC removes the <code>transferFrom</code>, <code>approve</code> and <code>allowance</code> functions of ERC-20.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> defines Ethereum-based standard tokens that can be traded and transferred, but the essence of ERC-20 is based on the externally-owned account (EOA) wallet design. An EOA wallet has no state and code storage, and the smart contract wallet is different.</p> <p>Almost all ERCs related to tokens add functions, but our opinion is the opposite. We think the token contract should be simpler, with more functions taken care of by the smart contract wallet.</p> <p>Our proposal is to design a simpler token asset based on the smart contract wallet.</p> <p>It aims to achieve the following goals:</p> <ol> <li>Keep the asset contract simple: only responsible for the <code>transfer</code> functions.</li> <li><code>approve</code> and <code>allowance</code> functions are not managed by the token contract, Instead, these permissions are managed at the user level, offering greater flexibility and control to users. This change not only enhances user autonomy but also mitigates certain risks associated with the ERC-20 contract's implementation of these functions.</li> <li>Remove the <code>transferFrom</code> function. A better way to call the other party's token assets is to access the other party's own contract instead of directly accessing the token asset contract.</li> <li>Forward compatibility with ERC-20 means that all fungible tokens can be compatible with this proposal.</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>Compliant contracts MUST implement the following 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.20</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"> ERC7196 Simple token interface </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://ercs.ethereum.org/ERCS/erc-7196</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"> IERC7196</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"> Used to notify transfer 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"> from</span><span class="z-comment"> Address of the from</span></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 of the receive</span></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 transaction 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"> 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-variable"> value</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get the total supply</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"> total</span><span class="z-comment"> The total supply 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"> totalSupply</span><span>(</span><span>)</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"> 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"> total</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"> get the balance of owenr 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 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"> balance</span><span class="z-comment"> The balance of the owenr 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"> balanceOf</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 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"> balance</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"> Transfer 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"> to</span><span class="z-comment"> Address of the 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"> value</span><span class="z-comment"> The transaction amount </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"> The bool value returns whether the transfer is 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"> 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> <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>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The proposal is to simplify token standards by removing <code>transferFrom</code>, <code>approve</code> and <code>allowance</code> functions. This simplification aims to enhance security, reduce complexity, and improve efficiency, making the standard more suitable for smart contract wallet environments while maintaining essential functionalities.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As mentioned in the beginning, this ERC is forward compatible with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, ERC-20 is backward compatible with this ERC.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p><strong>forward compatible with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a></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.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;./IERC7196.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;../../math/SafeMath.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"> Standard ERC7196 token</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 ERC-165 identifier for this interface is 0xc1b31357</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 the basic standard token.</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"> ERC7196</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7196</span><span> {</span></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-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> _balances</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"> private</span><span> _totalSupply</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"> totalSupply</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> _totalSupply</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-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 class="z-keyword"> return</span><span> _balances</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"> 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"> 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-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 class="z-keyword"> require</span><span>(</span><span>to </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> _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> _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"> Transfer</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> to</span><span>,</span><span> 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 class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>It should be noted that this ERC is not backward compatible with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, so there will be incompatibility with existing dapps.</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-06-21T00:00:00+00:00 2026-02-11T14:48:25+00:00 Xianghttps://github.com/wenzhenxiang Ben77https://github.com/ben2077 Mingshi S.https://github.com/newnewsms https://wg-eips.ritovision.com/7204/

Focuses on fungible token management within smart contract wallets, offering enhanced transaction flexibility and security

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a smart contract wallet-based approach for managing tokens, focusing on utilizing the programmable features of smart contract wallets for asset management. Additionally, it introduces functions such as <code>tokenTransfer</code>, <code>tokenApprove</code>, <code>tokenApproveForAll</code>, <code>tokenIsApproveForAll</code> and <code>tokenAllowance</code>, which provide enhanced control over token transactions. This approach seeks to enhance token management by utilizing the built-in features of smart contract wallets, thus offering a more adaptable, secure, and efficient method for managing token transactions.</p> <h2 id="motivation">Motivation</h2> <p>An externally-owned account (EOA) wallet has no state and code storage, while the smart contract wallet does.</p> <p>Account abstraction (AA) is a direction of the smart contract wallet, which works around abstract accounts. This ERC can also be an extension based on <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> or as a plug-in for wallets.</p> <p>The smart contract wallet allows the user's own account to have state and code, bringing programmability to the wallet. We think there are more directions to expand. For example, token asset management, functional expansion of token transactions, etc.</p> <p>The smart contract wallet interface of this ERC is for asset management and asset approval. It supports the simpletoken <!-- TODO --> ERC-X, and <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> is backward compatible with <!-- TODO --> ERC-X, so it can be compatible with the management of all fungible tokens in the existing market.</p> <p>The proposal aims to achieve the following goals:</p> <ol> <li>Assets are allocated and managed by the wallet itself, such as <code>approve</code> and <code>allowance</code>, which are configured by the user’s contract wallet, rather than controlled by the token asset contract, to avoid some existing ERC-20 contract risks.</li> <li>Add the <code>tokenTransfer</code> function, the transaction initiated by the non-smart wallet itself or will verify the allowance amount.</li> <li>Add <code>tokenApprove</code>, <code>tokenAllowance</code>, <code>tokenApproveForAll</code>, <code>tokenIsApproveForAll</code> functions. The user wallet itself supports approve and provides approve. for single token assets and all token assets.</li> <li>user wallet can choose batch approve and batch transfer.</li> <li>Users can choose to add hook function before and after their <code>tokenTransfer</code> to increase the user's more playability.</li> <li>The user can choose to implement the <code>tokenReceive</code> function.</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>** Compliant contract must implement the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> 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-7204 </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-7204</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 ERC-165 identifier for this interface is 0xf73edcda</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.20</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"> IERC7204</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to notify listeners that owner has granted approval to the user to manage assets 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"> asset</span><span class="z-comment"> Address of 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"> owner</span><span class="z-comment"> Address of the account that has granted the approval for token‘s assets</span></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"> Address of the 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"> value</span><span class="z-comment"> The amount allowed to spend</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"> TokenApproval</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"> asset</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 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"> Used to notify listeners that owner has granted approval to the spender to manage all 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"> asset</span><span class="z-comment"> Address of 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"> owner</span><span class="z-comment"> Address of the account that has granted the approval for token‘s assets</span></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"> approve all 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"> TokenApprovalForAll</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"> 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"> Approve token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Allows spender address to withdraw from your account multiple times, up to the value amount.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If this function is called again it overwrites the current allowance with value.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits an {TokenApproval} 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"> asset</span><span class="z-comment"> Address of 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"> spender</span><span class="z-comment"> Address of the 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"> value</span><span class="z-comment"> The amount allowed to spend</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"> The bool value returns whether the approve is 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"> tokenApprove</span><span>(</span><span class="z-support">address</span><span class="z-variable"> asset</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> </span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span> </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"> read token allowance 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"> asset</span><span class="z-comment"> Address of 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"> spender</span><span class="z-comment"> Address of the 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"> remaining</span><span class="z-comment"> The asset 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"> tokenAllowance</span><span>(</span><span class="z-support">address</span><span class="z-variable"> asset</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> spender</span><span>)</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 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"> Approve all token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Allows spender address to withdraw from your wallet all token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits an {TokenApprovalForAll} 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"> Address of the 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"> approved</span><span class="z-comment"> Approved all 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"> success</span><span class="z-comment"> The bool value returns whether the approve is 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"> tokenApproveForAll</span><span>(</span><span class="z-support">address</span><span class="z-variable"> spender</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"> external</span><span> </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"> read spender approved 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"> spender</span><span class="z-comment"> Address of the 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"> approved</span><span class="z-comment"> Whether to approved spender all 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"> tokenIsApproveForAll</span><span>(</span><span class="z-support">address</span><span class="z-variable"> spender</span><span>)</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 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">@notice</span><span class="z-comment"> Transfer token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> must call asset.transfer() inside the function</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If the caller is not wallet self, must verify the allowance and update the allowance 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"> asset</span><span class="z-comment"> Address of 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"> to</span><span class="z-comment"> Address of the receive</span></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 transaction amount</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"> The bool value returns whether the transfer is 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"> tokenTransfer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> asset</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> </span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span> </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></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>the key technical decisions in this proposal are:</p> <p><strong>Improved Approve Mechanism</strong></p> <ul> <li><strong>Current vs. Proposed</strong>: In the existing ERC-20 system, an externally-owned account (EOA) directly interacts with token contracts to <code>approve</code>. The new <code>tokenApprove</code> and <code>tokenApproveForAll</code> functions in this proposed enable more precise control over token usage within a wallet contract, a significant improvement over the traditional method.</li> <li><strong>Enhanced Security</strong>: This mechanism mitigates risks like token over-approval by shifting approval control to the user's smart contract wallet.</li> <li><strong>Programmability</strong>: Users gain the ability to set advanced approval strategies, such as conditional or time-limited approvals, the <code>tokenApproveForAll</code> function specifically allows for a universal setting all tokens. these were not possible with traditional ERC-20 tokens.</li> </ul> <p><strong>Optimized Transfer Process</strong></p> <ul> <li><strong>Efficiency and Security</strong>: The <code>tokenTransfer</code> function streamlines the token transfer process, making transactions both more efficient and secure.</li> <li><strong>Flexibility</strong>: Allows the integration of custom logic (hooks) before and after transfers, enabling additional security checks or specific actions tailored to the user’s needs.</li> </ul> <p><strong>Support for Batch Operations</strong></p> <ul> <li><strong>Increased Efficiency</strong>: Users can simultaneously handle multiple <code>approve</code> or <code>transfer</code> operations, significantly boosting transaction efficiency.</li> <li><strong>Enhanced User Experience</strong>: Simplifies the management of numerous assets, improving the overall experience for users with large portfolios.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC can be used as an extension of <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> and is backward compatible with ERC-4337.</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> 2023-06-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Francisco Giordanohttps://github.com/frangio Hadrien Crouboishttps://github.com/Amxx Ernesto Garcíahttps://github.com/ernestognw Eric Lauhttps://github.com/ericglau https://wg-eips.ritovision.com/7201/

Conventions for the storage location of structs in the namespaced storage pattern.

<h2 id="abstract">Abstract</h2> <p>We define the NatSpec annotation <code>@custom:storage-location</code> to document storage namespaces and their location in storage in Solidity or Vyper source code. Additionally, we define a formula to derive a location from an arbitrary identifier. The formula is chosen to be safe against collisions with the storage layouts used by Solidity and Vyper.</p> <h2 id="motivation">Motivation</h2> <p>Smart contract languages such as Solidity and Vyper rely on tree-shaped storage layout. This tree starts at slot 0 and is composed of sequential chunks for consecutive variables. Hashes are used to ensure the chunks containing values of mappings and dynamic arrays do not collide. This is sufficient for most contracts. However, it presents a challenge for various design patterns used in smart contract development. One example is a modular design where using <code>DELEGATECALL</code> a contract executes code from multiple contracts, all of which share the same storage space, and which have to carefully coordinate on how to use it. Another example is upgradeable contracts, where it can be difficult to add state variables in an upgrade given that they may affect the assigned storage location for the preexisting variables.</p> <p>Rather than using this default storage layout, these patterns can benefit from laying out state variables across the storage space, usually at pseudorandom locations obtained by hashing. Each value may be placed in an entirely different location, but more frequently values that are used together are put in a Solidity struct and co-located in storage. These pseudorandom locations can be the root of new storage trees that follow the same rules as the default one. Provided that this pseudorandom root is constructed so that it is not part of the default tree, this should result in the definition of independent spaces that do not collide with one another or with the default one.</p> <p>These storage usage patterns are invisible to the Solidity and Vyper compilers because they are not represented as Solidity state variables. Smart contract tools like static analyzers or blockchain explorers often need to know the storage location of contract data. Standardizing the location for storage layouts will allow these tools to correctly interpret contracts where these design patterns are used.</p> <h2 id="specification">Specification</h2> <h3 id="preliminaries">Preliminaries</h3> <p>A <em>namespace</em> consists of a set of ordered variables, some of which may be dynamic arrays or mappings, with its values laid out following the same rules as the default storage layout but rooted in some location that is not necessarily slot 0. A contract using namespaces to organize storage is said to use <em>namespaced storage</em>.</p> <p>A <em>namespace id</em> is a string that identifies a namespace in a contract. It should not contain any whitespace characters.</p> <h3 id="custom-storage-location"><code>@custom:storage-location</code></h3> <p>A namespace in a contract should be implemented as a struct type. These structs should be annotated with the NatSpec tag <code>@custom:storage-location &lt;FORMULA_ID&gt;:&lt;NAMESPACE_ID&gt;</code>, where <code>&lt;FORMULA_ID&gt;</code> identifies a formula used to compute the storage location where the namespace is rooted, based on the namespace id. <em>(Note: The Solidity compiler includes this annotation in the AST since v0.8.20, so this is recommended as the minimum compiler version when using this pattern.)</em> Structs with this annotation found outside of contracts are not considered to be namespaces for any contract in the source code.</p> <h3 id="formula">Formula</h3> <p>The formula identified by <code>erc7201</code> is defined as <code>erc7201(id: string) = keccak256(keccak256(id) - 1) &amp; ~0xff</code>. In Solidity, this corresponds to the expression <code>keccak256(abi.encode(uint256(keccak256(bytes(id))) - 1)) &amp; ~bytes32(uint256(0xff))</code>. When using this formula the annotation becomes <code>@custom:storage-location erc7201:&lt;NAMESPACE_ID&gt;</code>. For example, <code>@custom:storage-location erc7201:foobar</code> annotates a namespace with id <code>"foobar"</code> rooted at <code>erc7201("foobar")</code>.</p> <p>Future EIPs may define new formulas with unique formula identifiers. It is recommended to follow the convention set in this EIP and use an identifier of the format <code>erc1234</code>.</p> <h2 id="rationale">Rationale</h2> <p>The tree-shaped storage layout used by Solidity and Vyper follows the following grammar (with root=0):</p> <p>$L_{root} := \mathit{root} \mid L_{root} + n \mid \texttt{keccak256}(L_{root}) \mid \texttt{keccak256}(H(k) \oplus L_{root}) \mid \texttt{keccak256}(L_{root} \oplus H(k))$</p> <p>A requirement for the root is that it shouldn't overlap with any storage location that would be part of the standard storage tree used by Solidity and Vyper (root = 0), nor should it be part of the storage tree derived from any other namespace (another root). This is so that multiple namespaces may be used alongside each other and alongside the standard storage layout, either deliberately or accidentally, without colliding. The term <code>keccak256(id) - 1</code> in the formula is chosen as a location that is unused by Solidity, but this is not used as the final location because namespaces can be larger than 1 slot and would extend into <code>keccak256(id) + n</code>, which is potentially used by Solidity. A second hash is added to prevent this and guarantee that namespaces are completely disjoint from standard storage, assuming keccak256 collision resistance and that arrays are not unreasonably large.</p> <p>Additionally, namespace locations are aligned to 256 as a potential optimization, in anticipation of gas schedule changes after the Verkle state tree migration, which may cause groups of 256 storage slots to become warm all at once.</p> <h3 id="naming">Naming</h3> <p>This pattern has sometimes been referred to as "diamond storage". This causes it to be conflated with the "diamond proxy pattern", even though they can be used independently of each other. This EIP has chosen to use a different name to clearly differentiate it from the proxy pattern.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <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.20</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"> Example</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @custom:storage</span><span class="z-comment">-location erc7201:example.main</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> MainStorage</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> x</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> y</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"> keccak256(abi.encode(uint256(keccak256(&quot;example.main&quot;)) - 1)) &amp; ~bytes32(uint256(0xff));</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> MAIN_STORAGE_LOCATION </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-constant"> 0x183a6125c38840424c4a85fa12bab2ab606c4b6d0e7cc73c0c06ba5300eab500</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"> _getMainStorage</span><span>(</span><span>)</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">MainStorage</span><span class="z-storage z-type"> storage</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> $</span><span>.</span><span>slot </span><span class="z-keyword">:=</span><span> MAIN_STORAGE_LOCATION</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"> _getXTimesY</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">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> MainStorage </span><span class="z-storage z-type">storage</span><span> $ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getMainStorage</span><span>(</span><span>)</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> $</span><span>.</span><span>y</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>Namespaces should avoid collisions with other namespaces or with standard Solidity or Vyper storage layout. The formula defined in this ERC guarantees this property for arbitrary namespace ids under the assumption of keccak256 collision resistance, as discussed in Rationale.</p> <p><code>@custom:storage-location</code> is a NatSpec annotation that current compilers don't enforce any rules for or ascribe any meaning to. The contract developer is responsible for implementing the pattern and using the namespace as claimed in the annotation.</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-06-09T00:00:00+00:00 2026-02-11T14:48:25+00:00 0xGhttps://github.com/0xGh Marco Peyfusshttps://github.com/mpeyfuss https://wg-eips.ritovision.com/7160/

Multiple metadata URIs per token, with the option to pin a primary URI.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes an extension to the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard to support multiple metadata URIs per token. It introduces a new interface, <code>IERC721MultiMetadata</code>, which provides methods for accessing the metadata URIs associated with a token, including a pinned URI index and a list of all metadata URIs. The extension is designed to be backward compatible with existing <code>ERC721Metadata</code> implementations.</p> <h2 id="motivation">Motivation</h2> <p>The current <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard allows for a single metadata URI per token with the <code>ERC721Metadata</code> implementation. However, there are use cases where multiple metadata URIs are desirable. Some example use cases are listed below:</p> <ul> <li>A token represents a collection of (cycling) assets with individual metadata</li> <li>An on-chain history of revisions to token metadata</li> <li>Appending metadata with different aspect ratios so that it can be displayed properly on all screens</li> <li>Dynamic and evolving metadata</li> <li>Collaborative and multi-artist tokens</li> </ul> <p>This extension enables such use cases by introducing the concept of multi-metadata support.</p> <p>The primary reason for having a multi-metadata standard in addition to the existing <code>ERC721Metadata</code> standard is that dapps and marketplaces don't have a mechanism to infer and display all the token URIs. Giving a standard way for marketplaces to offer collectors a way to pin/unpin one of the metadata choices also enables quick and easy adoption of this functionality.</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>The multi-metadata extension is OPTIONAL for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> contracts and it is RECOMMENDED to be used in conjunction with the <a href="https://wg-eips.ritovision.com/4906/">ERC-4906</a> standard if implemented</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"> EIP-721 Multi-Metdata Extension</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 0x06e1bc5b.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC7160</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 event emits when a token uri is pinned and is</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> useful for indexing purposes.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenUriPinned</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-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-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This event emits when a token uri is unpinned and is</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> useful for indexing purposes.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenUriUnpinned</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Get all token uris associated with a particular token</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 uri is pinned, the index returned SHOULD be the index in the string array</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This call MUST revert if the token 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"> The identifier for 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"> index</span><span class="z-comment"> An unisgned integer that specifies which uri is pinned for a token (or the default uri if unpinned)</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"> uris</span><span class="z-comment"> A string array of all uris associated with a 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"> pinned</span><span class="z-comment"> A boolean showing if the token has pinned metadata or not</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenURIs</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 class="z-variable"> index</span><span>,</span><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> uris</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> pinned</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"> Pin a specific token uri for a particular token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This call MUST revert if the token does not exist</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This call MUST emit a `TokenUriPinned` event</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This call MAY emit a `MetadataUpdate` event from ERC-4096</span></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 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"> index</span><span class="z-comment"> The index in the string array returned from the `tokenURIs` function that should be pinned for the token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> pinTokenURI</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"> index</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"> Unpin metadata for a particular token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This call MUST revert if the token does not exist</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This call MUST emit a `TokenUriUnpinned` event</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This call MAY emit a `MetadataUpdate` event from ERC-4096</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> It is up to the developer to define what this function does and is intentionally left open-ended</span></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 of the nft</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unpinTokenURI</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Check on-chain if a token id has a pinned uri or not</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This call MUST revert if the token does not exist</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Useful for on-chain mechanics that don&#39;t require the tokenURIs themselves</span></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 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"> pinned</span><span class="z-comment"> A bool specifying if a token has metadata pinned or not</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hasPinnedTokenURI</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 class="z-variable"> pinned</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>TokenUriPinned</code> event MUST be emitted when pinning a token uri with the <code>pinTokenUri</code> function.</p> <p>The <code>TokenUriUnpinned</code> event MUST be emitted when unpinning a token uri with the <code>unpinTokenUri</code> function.</p> <p>The <code>tokenURI</code> function defined in the ERC-721 Metadata extension MUST return the pinned URI when a token has a pinned uri.</p> <p>The <code>tokenURI</code> function defined in the ERC-721 Metadata extension MUST return a default uri when a token has an unpinned uri.</p> <p>The <code>supportsInterface</code> method MUST return <code>true</code> when called with <code>0x06e1bc5b</code>.</p> <p>Implementing functionality to add or remove uris to a token MUST be implemented separately from this standard. It is RECOMMENDED that one of the event defined in <a href="https://wg-eips.ritovision.com/4906/">ERC-4906</a> are emitted whenever uris are added or removed.</p> <p>See the <a href="https://wg-eips.ritovision.com/7160/#reference-implementation">Implementation</a> section for an example.</p> <h2 id="rationale">Rationale</h2> <p>Similar terminology to <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> was used in order to keep fetching metadata familiar. The concept of pinning and unpinning metadata is introduced as it is clear that NFT owners might want to choose which piece of metadata to display. At first, we considered leaving the pinning and unpinning actions up to each developer, but realized that a standard interface for pinning and unpinning allows for dApps to easily implement universal support for multi-metadata tokens.</p> <p>We first considered whether the <code>tokenURIs</code> function should return just a string array, but added the extra information so that you could get all info desired in one call instead of potentially three calls. The pinned URI should be used as the primary URI for the token, while the list of metadata URIs can be used to access individual assets' metadata within the token. dApps could present these as a gallery or media carousels.</p> <p>The <code>TokenUriPinned</code> and <code>TokenUriUnpinned</code> events included in this specification can be used by dApps to index what metadata to show. This can eliminate on-chain calls and event driven architecture can be used instead.</p> <p>The reason why this standard recommends the use of <a href="https://wg-eips.ritovision.com/4906/">ERC-4906</a> when adding or removing uris from a token is that there is already wide dApp support for this event and it already is what is needed - an alert to dApps that metadata for a token has been updated. We did not want to potentially cause dApp issues with duplicate events. A third party listening to this event could then call the <code>tokenURIs</code> function to get the updated metadata.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This extension is designed to be backward compatible with existing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> contracts. The implementation of the <code>tokenURI</code> method must either return the pinned token uri (if pinned) or some default uri (if unpinned).</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>An open-source reference implementation of the <code>IERC721MultiMetadata</code> interface can be provided, demonstrating how to extend an existing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> contract to support multi-metadata functionality. This reference implementation can serve as a guide for developers looking to implement the extension in their own contracts.</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.19</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">ERC721</span><span>}</span><span class="z-keyword"> from</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> {</span><span class="z-entity z-name">Ownable</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/access/Ownable.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IERC4906</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/interfaces/IERC4906.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IERC7160</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./IERC7160.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"> MultiMetadata</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">Ownable</span><span>, </span><span class="z-entity z-name">IERC7160</span><span>, </span><span class="z-entity z-name">IERC4906</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"> string</span><span>[</span><span>]</span><span>)</span><span class="z-storage z-type"> private</span><span> _tokenURIs</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"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> _pinnedURIIndices</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"> bool</span><span>)</span><span class="z-storage z-type"> private</span><span> _hasPinnedTokenURI</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 z-parameter z-function"> _name</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"> _symbol</span><span>)</span><span class="z-entity z-name"> ERC721</span><span>(</span><span>_name, _symbol) </span><span class="z-entity z-name">Ownable</span><span>(</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> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @notice Returns the pinned URI index or the last token URI index (length - 1).</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _getTokenURIIndex</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"> 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> _hasPinnedTokenURI</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> ?</span><span> _pinnedURIIndices</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> :</span><span> _tokenURIs</span><span>[</span><span>tokenId</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> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @notice Implementation of ERC721.tokenURI for backwards compatibility.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @inheritdoc ERC721.tokenURI</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"> 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">string</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _requireMinted</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> index </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getTokenURIIndex</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> uris </span><span class="z-keyword">=</span><span> _tokenURIs</span><span>[</span><span>tokenId</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> uri </span><span class="z-keyword">=</span><span> uris</span><span>[</span><span>index</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Revert if no URI is found for the token.</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-support">bytes</span><span>(</span><span>uri</span><span>)</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;ERC721: not URI found&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> uri</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"> @inheritdoc</span><span class="z-comment"> IERC721MultiMetadata.tokenURIs</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenURIs</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 class="z-variable"> index</span><span>,</span><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> uris</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> pinned</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _requireMinted</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-entity z-name">_getTokenURIIndex</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span> _tokenURIs</span><span>[</span><span>tokenId</span><span>]</span><span>,</span><span> _hasPinnedTokenURI</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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @inheritdoc</span><span class="z-comment"> IERC721MultiMetadata.pinTokenURI</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> pinTokenURI</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"> index</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 class="z-string"> &quot;Unauthorized&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _pinnedURIIndices</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span> index</span><span>;</span></span> <span class="giallo-l"><span> _hasPinnedTokenURI</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> TokenUriPinned</span><span>(</span><span>tokenId</span><span>,</span><span> index</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"> @inheritdoc</span><span class="z-comment"> IERC721MultiMetadata.unpinTokenURI</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unpinTokenURI</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 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 class="z-string"> &quot;Unauthorized&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _pinnedURIIndices</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> _hasPinnedTokenURI</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> TokenUriUnpinned</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-storage z-type"> @inheritdoc</span><span class="z-comment"> IERC721MultiMetadata.hasPinnedTokenURI</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hasPinnedTokenURI</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 class="z-variable"> pinned</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _hasPinnedTokenURI</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-storage z-type"> @notice</span><span class="z-comment"> Sets a specific metadata URI for a token at the given index.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setUri</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"> index</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-entity z-name"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_tokenURIs</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span> index</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> _tokenURIs</span><span>[</span><span>tokenId</span><span>]</span><span>[</span><span>index</span><span>]</span><span class="z-keyword"> =</span><span> uri</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span> _tokenURIs</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>uri</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-keyword"> emit</span><span class="z-entity z-name"> MetadataUpdate</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"> Overrides supportsInterface to include IERC721MultiMetadata interface support.</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"> 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">IERC165</span><span>,</span><span class="z-entity z-name"> ERC721</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></span> <span class="giallo-l"><span> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC7160</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 class="giallo-l"><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>Care should be taken when specifying access controls for state changing events, such as those that allow uris to be added to tokens and those specified in this standard: the <code>pinTokenUri</code> and <code>unpinTokenUri</code> functions. This is up to the developers to specify as each application may have different requirements to allow for pinning and unpinning.</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-06-09T00:00:00+00:00 2026-02-11T14:48:25+00:00 Rachid Ajajahttps://github.com/abrajaja Matthijs de Vrieshttps://github.com/sudomati Alexandros Athanasopuloshttps://github.com/Xaleee Pavel Rubinhttps://github.com/pash7ka Sebastian Galimberti Romanohttps://github.com/galimba Daniel Berbesihttps://github.com/berbex Apostolos Mavropouloshttps://github.com/ApostolosMavro Barbara Marcanohttps://github.com/Barbara-Marcano Daniel Ortegahttps://github.com/xdaniortega https://wg-eips.ritovision.com/7208/

Interoperability by abstracting logic away from storage

<h2 id="abstract">Abstract</h2> <p>This ERC defines a series of interfaces for the abstraction of storage of on-chain data by implementing the logic functions that govern such data on independent smart contracts. "On-chain Data Containers" (ODCs) refer to the separation and indexing of data storage away from data management. We propose that on-chain data can be abstracted and stored in smart contracts called "Data Objects" (DO), which answer to external data indexing mechanisms named "Data Points" (DP). This data can be accessed and modified by implementing (one or many) separate smart contracts identified as "Data Managers" (DM). We introduce two mechanisms for access management: first, through a "Data Index" (DI) implementation, the "Data Managers" (DM) can be gated from accessing "Data Objects" (DO); second, a "Data Point Registry" (DPR) implementation manages the issuance of "Data Points" (DP). Lastly, we introduce the concept of data portability (horizontal data mobility) between implementations of "Data Index" (DI), enabling massive updates to the logic without affecting the underlying data storage.</p> <h2 id="motivation">Motivation</h2> <p>As the Ethereum ecosystem grows, so does the demand for on-chain functionalities. The market encourages a desire for broader adoption through more complex systems and there is a constant need for improved efficiency. We have seen times when an explosion of new standard token proposals was solely driven by market hype. While ultimately each standard serves its purpose, most of them require more flexibility to manage interoperability with other standards. A standard adapter mechanism is needed to enhance interoperability by driving the interactions between assets issued under different ERCs.</p> <p>Without such mechanisms, most projects have implemented bespoke solutions for interoperability. This is an inefficient approach and leads to a fragmented ecosystem. We recognize there is no “one size fits all” solution to solve the standardization and interoperability challenges. Most assets - Fungible, Non-Fungible, Digital Twins, Real-world Assets, DePin, etc - have multiple mechanisms for representing them as on-chain tokens through the use of different standard interfaces and the diversity of standards spurs innovation.</p> <p>However, for these assets to be exchanged, traded, or otherwise interacted with, protocols must implement compatibility with the relevant interfaces to access and modify on-chain data. This is especially challenging when considering the previously mentioned bespoke solutions for interoperability. Additionally, the immutability of smart contracts complicates the ability of already deployed protocols to adapt to new tokenization standards, which is critical for future-proofing implementations. A collaborative effort must be made to enable interaction between assets tokenized under different standards. The current ERC provides the tools for developing such on-chain adapters.</p> <p>We aim to abstract the on-chain data handling from the logical implementation, exposing the underlying data independently of the ERC interface. We propose a series of interfaces for storing and accessing data on-chain in contracts called "Data Objects" (DO), grouping the underlying assets as generic "Data Points" (DP) that may be associated with multiple interoperable and even concurrent "Data Manager" (DM) contracts. This proposal is designed to work by coexisting with previous and future token standards, providing a flexible, efficient, and coherent mechanism to manage asset interoperability.</p> <ul> <li> <p><strong>Data Abstraction</strong>: We propose a standardized interface for enabling developers to separate the data storage code from the underlying token utility logic, reducing the need for supporting and implementing multiple inherited -and often clashing- interfaces to achieve asset compatibility. The data (and therefore the assets) can be stored independently of the logic that governs such data.</p> </li> <li> <p><strong>Standard Neutrality</strong>: A neutral approach must enable the underlying data of any tokenized asset to transition seamlessly between different token standards. This will significantly improve interoperability among other standards, reducing fragmentation in the landscape. Our proposal aims to separate the storage of data representing an underlying asset from the standard interface used for representing the token.</p> </li> <li> <p><strong>Consistent Interface</strong>: A uniform interface of primitive functions abstracts the data storage from the use case, irrespective of the underlying token's standard or the interface exposing such data. Data and metadata can be stored on-chain, and exposed through the same primitives.</p> </li> <li> <p><strong>Data Portability</strong>: We provide a mechanism for the Horizontal Mobility of data between implementations of this standard, incentivizing the implementation of interoperable solutions and standard adapters.</p> </li> </ul> <h2 id="specification">Specification</h2> <h3 id="terms">Terms</h3> <p><strong>Data Point</strong>: A uniquely identifiable reference to an on-chain data structure stored within one or many <strong>Data Objects</strong> and managed by one or many <strong>Data Managers</strong>. <strong>Data Points</strong> are issued by a <strong>Data Point Registry</strong>.</p> <p><strong>Data Object</strong>: A Smart Contract implementing the low-level storage management of information indexed through <strong>Data Points</strong>.</p> <p><strong>Data Manager</strong>: One or many Smart Contracts implementing the high-level logic and end-user interfaces for managing Data Objects.</p> <p><strong>Data Point Registry</strong>: One or many Smart Contracts used for managing the issuance of <strong>Data Points</strong>. Additionally, a <strong>Data Point Registry</strong> defines a space of compatible or interoperable <strong>Data Points</strong>.</p> <p><strong>Data Index</strong>: One or many Smart Contracts used for managing the access of <strong>Data Managers</strong> to <strong>Data Objects</strong>.</p> <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="data-point-structure">Data Point Structure</h3> <ul> <li>Data Point MUST be <code>bytes32</code> storage units.</li> <li>Data Point SHOULD NOT be used for storing asset data.</li> <li>Data Point SHOULD be used for indexing data.</li> <li>Data Point SHOULD use a 4 bytes prefix for storing information relevant to the compatibility with other Data Points.</li> <li>Data Point MUST use 4 bytes for storing the Chain ID</li> <li>Data Point SHOULD use the last 20 bytes for identifying which Registry allocated them.</li> <li>The RECOMMENDED internal structure of the Data Point is as follows:</li> </ul> <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"> * RECOMMENDED internal DataPoint structure on the Reference Implementation:</span></span> <span class="giallo-l"><span class="z-comment"> * 0xPPPPVVRRIIIIIIIIHHHHHHHHAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA</span></span> <span class="giallo-l"><span class="z-comment"> * - Prefix (bytes4)</span></span> <span class="giallo-l"><span class="z-comment"> * -- PPPP - Type prefix (i.e. 0x4450 - ASCII representation of letters &quot;DP&quot;)</span></span> <span class="giallo-l"><span class="z-comment"> * -- VV - Version of DataPoint specification (i.e. 0x00 for the reference implementation)</span></span> <span class="giallo-l"><span class="z-comment"> * -- RR - Reserved</span></span> <span class="giallo-l"><span class="z-comment"> * - Registry-local identifier</span></span> <span class="giallo-l"><span class="z-comment"> * -- IIIIIIII - 32 bit implementation-specific id of the DataPoint</span></span> <span class="giallo-l"><span class="z-comment"> * - Chain ID (bytes4)</span></span> <span class="giallo-l"><span class="z-comment"> * -- HHHHHHHH - 32 bit of chain identifier</span></span> <span class="giallo-l"><span class="z-comment"> * - REGISTRY Address (bytes20)</span></span> <span class="giallo-l"><span class="z-comment"> * -- AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA - Address of Registry which allocated the DataPoint</span></span> <span class="giallo-l"><span class="z-comment">*</span><span class="z-comment">*/</span></span></code></pre> <p><strong>Data Points</strong> are a low-level structure abstracting and indexing information. <strong>Data Points</strong> act as pointers to information stored within data structures in <strong>Data Objects</strong>. <strong>Data Points</strong> are allocated by a <strong>Data Point Registry</strong>. The <strong>Data Point</strong> SHOULD store which <strong>Data Point Registry</strong> initialized it within its internal structure. Each <strong>Data Point</strong> SHOULD have a unique identifier provided by the <strong>Data Point Registry</strong> when instantiated.</p> <h3 id="data-object-interface">Data Object Interface</h3> <ul> <li>Data Object SHOULD be used for storing asset data.</li> <li>Data Object SHOULD use <strong>Data Points</strong> for indexing the structure storing the data.</li> <li>Data Object SHOULD implement the logic directly related to handling the data structure.</li> <li>Data Object SHOULD implement the logic for transferring management of its <strong>Data Points</strong> to a different <strong>Data Index</strong> implementation.</li> <li>Data Object MUST use the IDataObject interface:</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"> IDataObject</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"> Reads stored 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"> dp</span><span class="z-comment"> Identifier of the DataPoint</span></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"> Read operation to run on the 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"> data</span><span class="z-comment"> Operation-specific data</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"> Operation</span><span class="z-comment">-specific data</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"> read</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> dp</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable"> operation</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"> 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> <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"> Store 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"> dp</span><span class="z-comment"> Identifier of the DataPoint</span></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"> Write operation to execute on the 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"> data</span><span class="z-comment"> Operation-specific data</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"> Operation</span><span class="z-comment">-specific data (can be 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"> write</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> dp</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable"> operation</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-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> <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"> Sets DataIndex 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"> dp</span><span class="z-comment"> Identifier of the DataPoint</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> newImpl</span><span class="z-comment"> address of the new DataIndex implementation</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"> setDIImplementation</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> dp</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> newImpl</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>Data Objects</strong> are entrusted with the storage and management of data. <strong>Data Objects</strong> SHOULD implement the logic for managing the storage of on-chain data. <strong>Data Object</strong> internal data structure SHOULD use <strong>Data Points</strong> for indexing information.</p> <p><strong>Data Objects</strong> CAN receive <code>read()</code>, <code>write()</code>, or any other custom requests from a <strong>Data Manager</strong> requesting access to a storage structure indexed by a <strong>Data Point</strong>.</p> <p>As such, <strong>Data Objects</strong> respond to a gating mechanism given by a single <strong>Data Index</strong>. The function <code>setDIImplementation()</code> SHOULD enable the delegation of the management function to an <code>IDataIndex</code> implementation.</p> <h3 id="data-manager-contract">Data Manager Contract</h3> <ul> <li>Data Manager SHOULD use <code>IDataIndex.read()</code> or <code>IDataObject.read()</code> to read data from <strong>Data Objects</strong></li> <li>Data Manager MUST use <code>IDataIndex.write()</code> to write data to <strong>Data Objects</strong></li> <li>Data Manager MAY share <strong>Data Point</strong> with other <strong>Data Managers</strong></li> <li>Data Manager MAY use multiple <strong>Data Points</strong></li> <li>Data Manager SHOULD implement the logic for requesting <strong>Data Points</strong> from a <strong>Data Point Registry</strong>.</li> </ul> <p><strong>Data Managers</strong> are independent smart contracts that implement the business logic or "high-level" data management. They can <code>read()</code> from a <strong>Data Object</strong> address and <code>write()</code> through a <strong>Data Index</strong> implementation managing the delegated storage of the <strong>Data Points</strong>.</p> <h3 id="data-point-registry-interface">Data Point Registry Interface</h3> <ul> <li>Data Point Registry SHOULD define functions to manage the creation, transfer, and access control of <strong>Data Points</strong></li> <li>Data Point Registry SHOULD manage <strong>Data Point</strong> access management for <strong>Data Managers</strong></li> <li>Data Point Registry MUST use the IDataPointRegistry interface:</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"> IDataPointRegistry</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"> Verifies if an address has an Admin role for a DataPoint</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> dp</span><span class="z-comment"> DataPoint</span></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"> Account to verify</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"> isAdmin</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> dp</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">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"> Allocates a DataPoint 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"> Owner of the new DataPoint</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Owner should be granted Admin role during allocation</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"> allocate</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"> payable</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">DataPoint</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 a DataPoint 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"> dp</span><span class="z-comment"> Data Point to be transferred</span></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 the new DataPoint</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"> transferOwnership</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> dp</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> newOwner</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"> Grant permission to grant/revoke other roles on the DataPoint inside a Data Index Implementation</span></span> <span class="giallo-l"><span class="z-comment"> * This is useful if DataManagers are deployed during lifecycle of the application.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> dp</span><span class="z-comment"> DataPoint</span></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"> New admin</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 role was granted (otherwise account already had the 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"> grantAdminRole</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> dp</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-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"> Revoke permission to grant/revoke other roles on the DataPoint inside a Data Index 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"> dp</span><span class="z-comment"> DataPoint</span></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"> Old admin</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If an owner revokes Admin role from himself, he can add it again</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 role was revoked (otherwise account didn&#39;t have the 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"> revokeAdminRole</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> dp</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-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>Data Point Registry</strong> is a smart contract entrusted with <strong>Data Point</strong> access control. <strong>Data Managers</strong> may request the allocation of <strong>Data Points</strong> to the <strong>Data Point Registry</strong>.</p> <h3 id="data-index-interface">Data Index Interface</h3> <ul> <li>DataIndex SHOULD manage the access of <strong>Data Managers</strong> to <strong>Data Objects</strong>.</li> <li>DataIndex SHOULD manage internal IDs for each user.</li> <li>DataIndex MUST use the IDataIndex interface:</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"> IDataIndex</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"> Verifies if DataManager is allowed to write specific DataPoint on specific DataObject</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> dp</span><span class="z-comment"> Identifier of the DataPoint</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> dm</span><span class="z-comment"> Address of DataManager</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"> write access is allowed</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"> isApprovedDataManager</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> dp</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> dm</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">@notice</span><span class="z-comment"> Defines if DataManager is allowed to write specific DataPoint</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> dp</span><span class="z-comment"> Identifier of the DataPoint</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> dm</span><span class="z-comment"> Address of DataManager</span></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"> if DataManager should be approved for the DataPoint</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Function should be restricted to DataPoint maintainer only</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"> allowDataManager</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> dp</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> dm</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">@notice</span><span class="z-comment"> Reads stored 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"> dobj</span><span class="z-comment"> Identifier of DataObject</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> dp</span><span class="z-comment"> Identifier of the datapoint</span></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"> Read operation to execute on the 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"> data</span><span class="z-comment"> Operation-specific data</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"> Operation</span><span class="z-comment">-specific data</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"> read</span><span>(</span><span class="z-support">address</span><span class="z-variable"> dobj</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> dp</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable"> operation</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"> 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> <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"> Store 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"> dobj</span><span class="z-comment"> Identifier of DataObject</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> dp</span><span class="z-comment"> Identifier of the datapoint</span></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"> Read operation to execute on the 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"> data</span><span class="z-comment"> Operation-specific data</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"> Operation</span><span class="z-comment">-specific data (can be empty)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Function should be restricted to allowed DMs only</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"> write</span><span>(</span><span class="z-support">address</span><span class="z-variable"> dobj</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> dp</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable"> operation</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-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>}</span></span></code></pre> <p>The <strong>Data Index</strong> is a smart contract entrusted with access control. It is a gating mechanism for <strong>Data Managers</strong> to access <strong>Data Objects</strong>. If a <strong>Data Manager</strong> intends to access a <strong>Data Point</strong> (either by <code>read()</code>, <code>write()</code>, or any other method), the <strong>Data Index</strong> SHOULD be used for validating access to the data.</p> <p>The mechanism for ID management determines a space of compatibility between implementations.</p> <h2 id="rationale">Rationale</h2> <p>The decision to encode <strong>Data Points</strong> as <code>bytes32</code> data pointers is primarily driven by flexibility and future-proofing. The use <code>bytes32</code> allows for a wide range of data encodings. This provides the developer with many options to accommodate diverse use cases. Furthermore, as Ethereum and its standards continue to evolve, encoding as <code>bytes32</code> ensures that the Standard Adapters built with the current ERC can reference future data types or structures without requiring significant changes to the adapter itself. The <strong>Data Point</strong> encoding should have a prefix so that the <strong>Data Object</strong> can efficiently identify compatibility issues when accessing the data storage. Additionally, the prefix should be used to find the <strong>Data Point Registry</strong> and verify admin access to the <strong>Data Point</strong>. The use of a suffix for identifying the <strong>Data Point Registry</strong> is also required, for the <strong>Data Object</strong> to quickly discard badly formed transactions that aim to use a <strong>Data Point</strong> from an unmatching <strong>Data Point Registry</strong>.</p> <p><strong>Data Manager</strong> implementations decide which <strong>Data Points</strong> they will be using. Their allocation is managed through a <strong>Data Point Registry</strong>, and the <code>write()</code> access to the <strong>Data Point</strong> is managed by passing through the <strong>Data Index</strong> implementation.</p> <p><strong>Data Objects</strong> are independent separate Smart Contracts that implement the same <code>read</code>/<code>write</code> interface for communicating with <strong>Data Managers</strong>. This is a decision mainly driven by the scalability of the system. Offering a simple interface for this layered structure enables different applications to have their addresses for storage of data independently from the asset's interface. It is up to each implementation to manage access to their <strong>Data Point</strong> storage space. This enables a wide array of complex, dynamic, and interactive use cases to be implemented with multiple ERCs as well as other smart contracts, including the embedding of cross-chain and rollup logic for asset management.</p> <p><strong>Data Objects</strong> offer flexibility in storing mutable on-chain data that can be modified as per the requirements of each specific use case. This enables the <strong>Data Managers</strong> to hold mutable states in delegated storage and reflect changes over time, providing a dynamic layer to the otherwise static nature of storage through most other standardized interfaces.</p> <p><strong>Data Managers</strong> can decide to migrate the complete storage management of a <strong>Data Object</strong> from one <strong>Data Index</strong> implementation to another. As the <strong>Data Index</strong> implements user ID management, this mechanism enables a <strong>Data Manager</strong> to upgrade its internal access control mechanisms without affecting the underlying storage of value, as it is located elsewere (in the <strong>Data Object</strong>). We call this mechanism "Horizontal Data Mobility/Portability".</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC is intended to augment the functionality of existing token standards without introducing breaking changes. As such, it does not present any backward compatibility issues. Already deployed tokens under other ERCs can be wrapped and indexed as <strong>Data Points</strong> and managed by <strong>Data Objects</strong>, and later exposed through any implementation of <strong>Data Managers</strong>. All interoperability integrations will require a compatibility analysis, depending on the use case. However, the interfaces defined in this ERC define a framework for adapting one standard to another through storage abstraction.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>We present an <em>educational example</em> implementation of a Standard Adapter showcasing two types of tokens (Fungible and Semi-Fungible) with shared data storage. The end user can interact with this implementation through one of two types of interfaces: The semi-fungible one (represented through a single <strong>Data Manager</strong>), and the fungible interface (represented by many <strong>Data Managers</strong>). The abstraction of the storage from the logic is achieved through the use of a single <em>Fungible Fractions</em> <strong>Data Object</strong>. A factory is used for deploying the Fungible token interfaces that share storage with each semi-fungible collection. Note that if a <code>transfer()</code> is called by either interface (Fungible or Semi-Fungible), both interfaces are emitting an event.</p> <p><strong>This example has not been audited and should not be used in production environments.</strong></p> <p>See <a href="https://wg-eips.ritovision.com/7208/assets/contracts/README/">contracts</a></p> <h2 id="security-considerations">Security Considerations</h2> <p>The access control is separated into three layers:</p> <ul> <li><strong>Layer 1</strong>: The <strong>Data Point Registry</strong> allocates for <strong>Data Managers</strong> and manages ownership (admin/write rights) of <strong>Data Points</strong>.</li> <li><strong>Layer 2</strong>: The <strong>Data Index</strong> smart contract implements Access Control by managing Approvals of <strong>Data Managers</strong> to <strong>Data Points</strong>. It uses the <strong>Data Point Registry</strong> to verify who can grant/revoke this access.</li> <li><strong>Layer 3</strong>: The <strong>DataObject</strong> manages trust relationship between the <strong>DataPoint</strong> and a <strong>DataIndex</strong> implementation and allows a trusted <strong>DataIndex</strong> to execute <code>write</code> operations.</li> </ul> <p>A common task for a <strong>Data Object</strong> is to store user-related data, while the <strong>Data Manager</strong> implements the logic for managing such data. Both <strong>Data Objects</strong> and <strong>Data Managers</strong> often require the management of user IDs. A <strong>Data Index</strong> can offer logic for user management (i.e. IDs based on <code>address</code>) that are independent of any particular implementation, but care must be taken in selecting these identifiers. If chosen improperly, they could hinder a <strong>Data Manager</strong>'s ability to migrate between different <strong>Data Indexes</strong>.</p> <p>No further security considerations are derived specifically from this ERC.</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-06-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 Thanh Trinhhttps://github.com/thanhtrinh2003thanh@revest.finance Joshua Weintraubhttps://github.com/jhweintraubjosh@revest.finance Rob Montgomeryhttps://github.com/RobAnonrob@revest.finance https://wg-eips.ritovision.com/7444/

Interface for conveying the date upon which a time-locked system becomes unlocked

<h2 id="abstract">Abstract</h2> <p>This EIP defines a standardized method to communicate the date on which a time-locked system will become unlocked. This allows for the determination of maturities for a wide variety of asset classes and increases the ease with which these assets may be valued.</p> <h2 id="motivation">Motivation</h2> <p>Time-locks are ubiquitous, yet no standard on how to determine the date upon which they unlock exists. Time-locked assets experience theta-decay, where the time remaining until they become unlocked dictates their value. Providing a universal standard to view what date they mature on allows for improved on-chain valuations of the rights to these illiquid assets, particularly useful in cases where the rights to these illiquid assets may be passed between owners through semi-liquid assets such as <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</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> <p><strong>Every <a href="https://wg-eips.ritovision.com/7444/">ERC-7444</a> compliant contract must implement <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface detection</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.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"> ERC</span><span class="z-keyword">-</span><span class="z-constant">7444</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> /</span></span> <span class="giallo-l"><span class="z-keyword"> *</span><span> @notice This </span><span class="z-storage z-type">function</span><span class="z-entity z-name"> returns</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> timestamp</span><span class="z-entity z-name"> that</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> time</span><span class="z-entity z-name"> lock</span><span class="z-entity z-name"> specified</span><span class="z-entity z-name"> by</span><span> `</span><span class="z-entity z-name">id</span><span>` </span><span class="z-entity z-name">unlocks</span><span class="z-entity z-name"> at</span></span> <span class="giallo-l"><span> * @</span><span class="z-entity z-name">param</span><span class="z-entity z-name"> id</span><span class="z-entity z-name"> The</span><span class="z-entity z-name"> identifier</span><span class="z-entity z-name"> which</span><span class="z-entity z-name"> describes</span><span class="z-entity z-name"> a</span><span class="z-entity z-name"> specific</span><span class="z-entity z-name"> time</span><span class="z-entity z-name"> lock</span></span> <span class="giallo-l"><span> * @</span><span class="z-keyword">return</span><span class="z-entity z-name"> maturity</span><span class="z-entity z-name"> The</span><span class="z-entity z-name"> timestamp</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> time</span><span class="z-entity z-name"> lock</span><span class="z-entity z-name"> when</span><span class="z-entity z-name"> it</span><span class="z-entity z-name"> unlocks</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> getMaturity</span><span>(</span><span class="z-entity z-name">bytes32</span><span class="z-entity z-name"> id</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"> maturity</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The maturity return parameter should be implemented in the Unix timestamp standard, which has been used widely in solidity. For example, <code>block.timestamp</code> represents the Unix timestamp when a block is mined in 256-bit value.</p> <p>For singleton implementations on fungible assets, values passed to <code>id</code> SHOULD be ignored, and queries to such implementations should pass in <code>0x0</code></p> <h2 id="rationale">Rationale</h2> <h3 id="universal-maturities-on-locked-assets">Universal Maturities on Locked Assets</h3> <p>Locked Assets have become increasingly popular and used in different parts of defi, such as yield farming and vested escrow concept. This has increased the need to formalize and define an universal interface for all these timelocked assets.</p> <h3 id="valuation-of-locked-assets-via-the-black-scholes-model">Valuation of Locked Assets via the Black-Scholes Model</h3> <p>Locked Assets cannot be valued normally since the value of these assets can be varied through time and many other different factors throughout the locking time. For instance, The Black-Scholes Model or Black-Scholes-Merton model is an example of a suitable model to estimate the theoretical value of asset with the consideration of impact of time and other potential risks.</p> <p><img src="https://wg-eips.ritovision.com/7444/./assets/equation.png" alt="Black-Sholes Model" /></p> <ul> <li>$C=\text{call option price}$</li> <li>$N=\text{CDF of the normal distribution}$</li> <li>$S_t=\text{spot price of an asset}$</li> <li>$K=\text{strike price}$</li> <li>$r=\text{risk-free interest rate}$</li> <li>$t=\text{time to maturity}$</li> <li>$\sigma=\text{volatility of the asset}$</li> </ul> <p>Time to maturity plays an important role in evaluating the price of timelocked assets, thus the demand to have a common interface for retrieving the data is inevitable.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard can be implemented as an extension to <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and/or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> tokens with time-locked functionality, many of which can be retrofitted with a designated contract to determine the point at which their time locks release.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="locked-erc-20-implementation">Locked <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> implementation</h3> <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-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/token/ERC20/ERC20.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"> LockedERC20ExampleContract</span><span> implements ERC</span><span class="z-keyword">-</span><span class="z-constant">7444</span><span>{</span></span> <span class="giallo-l"><span> ERC20 </span><span class="z-storage z-type">public</span><span class="z-storage z-type"> immutable</span><span> token</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> public</span><span> totalLocked</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">Timelock struct</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> TimeLock</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> owner</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 class="z-support"> uint256</span><span> maturity</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> lockId</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">maps lockId to balance of the lock</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> TimeLock</span><span>)</span><span class="z-storage z-type"> public</span><span> idToLock</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"> constructor</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> )</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> token </span><span class="z-keyword">=</span><span class="z-entity z-name"> ERC20</span><span>(</span><span>_token</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">Maturity is not appropriate</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> LockPeriodOngoing</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> InvalidReceiver</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> TransferFailed</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"> @dev</span><span class="z-comment"> Deposit tokens to be locked in the requested locking period</span></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"> The amount of tokens to deposit</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> lockingPeriod</span><span class="z-comment"> length of locking period for the tokens to be locked</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-support"> uint256</span><span class="z-variable"> lockingPeriod</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"> lockId</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> maturity </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> lockingPeriod</span><span>;</span></span> <span class="giallo-l"><span> lockId </span><span class="z-keyword">=</span><span class="z-entity z-name"> keccack256</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">msg.sender</span><span>,</span><span> amount</span><span>,</span><span> maturity</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>idToLock</span><span>[</span><span>lockId</span><span>]</span><span>.</span><span>maturity </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;lock already exists&quot;</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>token</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> amount</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> TransferFailed</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> TimeLock </span><span class="z-storage z-type">memory</span><span> newLock </span><span class="z-keyword">=</span><span class="z-entity z-name"> TimeLock</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> amount</span><span>,</span><span> maturity</span><span>,</span><span> lockedId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> totalLocked </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> idToLock</span><span>[</span><span>lockId</span><span>]</span><span class="z-keyword"> =</span><span> newLock</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-storage z-type"> @dev</span><span class="z-comment"> Withdraw tokens in the lock after the end of the locking period</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> lockId</span><span class="z-comment"> id of the lock that user have deposited in</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">bytes32</span><span class="z-variable"> lockId</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span> TimeLock </span><span class="z-storage z-type">memory</span><span> lock </span><span class="z-keyword">=</span><span> idToLock</span><span>[</span><span>lockId</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-language">msg.sender</span><span class="z-keyword"> !=</span><span> lock</span><span>.</span><span>owner</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> InvalidReceiver</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-keyword"> if</span><span> (</span><span class="z-variable z-language">block</span><span>.</span><span>timestamp </span><span class="z-keyword">&gt;</span><span> lock</span><span>.</span><span>maturity</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> LockPeriodOngoing</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> totalLocked </span><span class="z-keyword">-</span><span class="z-keyword">=</span><span> lock</span><span>.</span><span>amount</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">State cleanup</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> idToLock</span><span>[</span><span>lockId</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>token</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> lock</span><span>.</span><span>amount</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> TransferFailed</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> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getMaturity</span><span>(</span><span class="z-support">bytes32</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 class="z-variable"> maturity</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> idToLock</span><span>[</span><span>id</span><span>]</span><span>.</span><span>maturity</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> <h3 id="extendable-time-locks">Extendable Time Locks</h3> <p>Users or developers should be aware of potential extendable timelocks, where the returned timestamp can be modified through protocols. Users or protocols should check the timestamp carefully before trading or lending with others.</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-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 John Zhanghttps://github.com/johnz1019 Davis Xianghttps://github.com/xcshuan Kyle Xuhttps://github.com/kylexyxu George Zhanghttps://github.com/odysseus0 https://wg-eips.ritovision.com/7093/

Interfaces for social recovery account supporting various guardian types and customizable recovery policies.

<h2 id="abstract">Abstract</h2> <p>This ERC proposes a standard interface for social recovery of smart contract accounts. It separates identity and policy verification from the recovery process, allowing more ways to authenticate (known as Guardians) than just on-chain accounts. It also lets users customize recovery policies without changing the account’s smart contract.</p> <h2 id="motivation">Motivation</h2> <p>Vitalik Buterin has long advocated for social recovery as an essential tool for user protection within the crypto space. He posits that the value of this system rests in its ability to offer users, especially those less acquainted with the technicalities of cryptography, a robust safety net when access credentials are lost. By entrusting account recovery to a network of selected individuals or entities, dubbed "Guardians," users gain a safeguard against the risk of losing access to their digital assets.</p> <p>In essence, social recovery operates by verifying the identity of the user and the chosen Guardians, and then considering a set of their signatures. Should the validated signatures reach a specified threshold, account access is reestablished. This system is equipped to enforce complex policies, such as necessitating signatures from particular Guardians or reaching signature thresholds from different Guardian categories.</p> <p>To overcome these limitations, this Ethereum Improvement Proposal (EIP) introduces a novel, customizable social recovery interface standard. This standard decouples identity and recovery policy verification from the recovery procedure itself, thereby enabling an independent, versatile definition and extension of both. This strategy accommodates a wider range of Guardian types and recovery policies, thereby offering users the following benefits:</p> <ol> <li>Appoint friends or family members, who do not have blockchain accounts, as Guardians for social recovery.</li> <li>Use NFTs/SBTs as Guardians for their accounts.</li> <li>Personalize and implement adaptable recovery policies.</li> <li>Support novel types of Guardians and recovery policies without needing to upgrade their account contracts.</li> <li>Enable multiple recovery mechanism support, thereby eliminating single points of failure.</li> </ol> <p>This approach enables users to customize recovery policies without the need to change the smart contract of the account itself.</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 consists of four key concepts:</p> <ul> <li><strong>Identity</strong>: This denotes the representation of a Guardian's identity on the blockchain. It encapsulates traditional on-chain account types such as Externally Owned Accounts (EOA) and Smart Contract Accounts (SCA). More importantly, it extends to include any identity construct capable of producing construct able to be verified on-chain, like signatures and proofs. This could range from <a rel="external" href="https://www.w3.org/TR/2021/REC-webauthn-2-20210408/">Webauthn</a>/Passkey R1 keys to Email DomainKeys Identified Mail (DKIM) signatures <a rel="external" href="https://www.rfc-editor.org/rfc/rfc6376">RFC 6376</a>, OpenID tokens, Zero-Knowledge Proofs (ZKP), Non-Fungible Tokens (NFTs), SoulBound Tokens (SBTs), and even types yet to be developed. This comprehensive approach ensures a broad, forward-compatible support for various identity types.</li> <li><strong>PermissionVerifier</strong>: This component defines how to verify the signature or proof provided by the Guardian. Regardless of whether the Guardian's account is on-chain or off-chain, the PermissionVerifier is invoked during the recovery process of smart contract accounts that incorporate a social recovery system. Its primary role is to confirm the validity of the Guardian's signature or proof, thereby ensuring the authenticity of the Guardian during the recovery process.</li> <li><strong>RecoveryPolicyVerifier</strong>: This component offers a flexible interface for validating recovery policies. The flexibility stems from allowing account holders or authorized parties to define and store their recovery policies. During the recovery process, the verification logic is implemented by invoking the specific function of the contract instance adopting this interface. Thus, a wide array of customizable social recovery scenarios can be catered to through different contract instances and policy configurations. This contract is optional, because sometimes the contract designer may not need the policy abstraction.</li> <li><strong>RecoveryAccount</strong>: This component encapsulates the core of the social recovery functionality. It is designed to be flexible, composable, and extensible to adapt to various recovery needs. Each RecoveryAccount is defined by an instance contract, crafted by smart contract developers, which embeds the essential logic for the recovery process.</li> <li><strong>RecoveryModule</strong>: In some contract designs, many functions are not directly added to the account contract, but are implemented in the form of Module, which is a contract outside the account contract. This component encapsulates the core of the social recovery functionality. It is designed to be flexible, composable, and extensible to adapt to various recovery needs.</li> </ul> <p><img src="https://wg-eips.ritovision.com/7093/./assets/social-recovery-flow.svg" alt="social_recovery_flow" /></p> <h3 id="datatypes">DataTypes</h3> <h3 id="typesanddecoders"><code>TypesAndDecoders</code></h3> <p>This defines the necessary data types required by this interface standard.</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"> Structure representing an identity with its signature/proof verification logic.</span></span> <span class="giallo-l"><span class="z-comment"> * Represents an EOA/CA account when signer is empty, use `guardianVerifier`as the actual signer for signature verification.</span></span> <span class="giallo-l"><span class="z-comment"> * OtherWise execute IPermissionVerifier(guardianVerifier).isValidPermission(hash, signer, signature).</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"> Identity</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> guardianVerifier</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> signer</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"> Structure representing a guardian with a property</span></span> <span class="giallo-l"><span class="z-comment"> * The property of Guardian are defined by the associated RecoveryPolicyVerifier 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"> GuardianInfo</span><span> {</span></span> <span class="giallo-l"><span> Identity guardian</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> property</span><span>;</span><span class="z-comment"> //</span><span class="z-comment">eg.,Weight,Percentage,Role with weight,etc.</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"> Structure representing a threshold configuration</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"> ThresholdConfig</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> threshold</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Threshold value</span></span> <span class="giallo-l"><span class="z-support"> int48</span><span> lockPeriod</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Lock period for the threshold</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"> Structure representing a recovery configuration</span></span> <span class="giallo-l"><span class="z-comment"> * A RecoveryConfig can have multiple threshold configurations for different threshold values and their lock periods, and the policyVerifier is optional.</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"> RecoveryConfigArg</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> policyVerifier</span><span>;</span></span> <span class="giallo-l"><span> GuardianInfo</span><span>[</span><span>]</span><span> guardianInfos</span><span>;</span></span> <span class="giallo-l"><span> ThresholdConfig</span><span>[</span><span>]</span><span> thresholdConfigs</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"> Permission</span><span> {</span></span> <span class="giallo-l"><span> Identity guardian</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> signature</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre> <p>The <code>Identity</code> structure represents various types of guardians. The process of identity verification is as follows:</p> <ul> <li>When the <code>signer</code> value in the declared entity is empty, this implies that the <code>Identity</code> entity is of EOA/SCA account type. In this case, <code>guardianVerifier</code> address should be the address of EOA/SCA (the actual signer). For permission verification of this <code>Identity</code> entity, it is recommended to utilize a secure library or built-in function capable of validating both ECDSA and <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> signatures. This helps in preventing potential security vulnerabilities, such as signature malleability attacks.</li> <li>When the <code>signer</code> value in the declared entity is non-empty, this suggests that the <code>Identity</code> entity is of non-account type. In this case, permission verification can be accomplished by calling <code>guardianVerifier</code> address contract instance through <code>IPermissionVerifier</code> interface.</li> </ul> <h3 id="interfaces">Interfaces</h3> <h3 id="ipermissionverifier"><code>IPermissionVerifier</code></h3> <p>The Guardian Permission Verification Interface. Implementations MUST conform to this interface to enable identity verification of non-account type guardians.</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"> Interface for no-account type identity signature/proof verification</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"> IPermissionVerifier</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"> Check if the signer key format is correct</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"> isValidSigners</span><span>(</span><span class="z-support">bytes</span><span>[</span><span>]</span><span class="z-variable"> signers</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"> Validate permission</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"> isValidPermission</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> hash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> signer</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> signature</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">@dev</span><span class="z-comment"> Validate permissions</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"> isValidPermissions</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> hash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-variable"> signers</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-variable"> signatures</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">@dev</span><span class="z-comment"> Return supported signer key information, format, signature format, hash algorithm, etc.</span></span> <span class="giallo-l"><span class="z-comment"> * MAY </span><span class="z-keyword">TODO</span><span class="z-comment">:using ERC-3668: ccip-read</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"> getGuardianVerifierInfo</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">bytes</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></code></pre><h3 id="irecoverypolicyverifier"><code>IRecoveryPolicyVerifier</code></h3> <p>The Recovery Policy Verification Interface. Implementations MAY conform to this interface to support verification of varying recovery policies. RecoveryPolicyVerifier is optional for SocialRecoveryInterface.</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"> Interface for recovery policy verification</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"> IRecoveryPolicyVerifier</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"> Verify recovery policy and return verification success and lock period</span></span> <span class="giallo-l"><span class="z-comment"> * Verification includes checking if guardians exist in the Guardians List</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"> verifyRecoveryPolicy</span><span>(</span><span class="z-storage z-type"> Permission</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> permissions</span><span>,</span><span class="z-support"> uint64</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> properties</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 class="z-variable"> succ</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> weight</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 supported policy settings and accompanying property definitions for Guardian.</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"> getPolicyVerifierInfo</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">bytes</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></code></pre> <p>The <code>verifyRecoveryPolicy()</code> function is designed to validate whether the provided list of <code>Permissions</code> abides by the specified recovery properties (<code>properties</code>). This function has the following constraints and effects: For each matched <code>guardian</code>, calculations are made according to the corresponding <code>property</code> in the <code>properties</code> list (e.g., accumulating weight, distinguishing role while accumulating, etc.).</p> <p>These constraints ensure that the provided <code>guardians</code> and <code>properties</code> comply with the requirements of the recovery policy, maintaining the security and integrity of the recovery process.</p> <h3 id="irecoveryaccount"><code>IRecoveryAccount</code></h3> <p>The Smart Contract Account MAY implement the <code>IRecoveryAccount</code> interface to support social recovery functionality, enabling users to customize configurations of different types of Guardians and recovery policies. In the contract design based on Module, the implementation of <code>RecoveryModule</code> is very similar to <code>RecoveryAccount</code>, except that different accounts need to be distinguished and isolated.</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"> IRecoveryAccount</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> onlySelf</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 class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span class="z-string"> &quot;onlySelf: NOT_AUTHORIZED&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"> modifier</span><span class="z-entity z-name"> InRecovering</span><span>(</span><span class="z-support">address</span><span class="z-variable"> policyVerifyAddress</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bool</span><span> isRecovering</span><span>,</span><span> )</span><span class="z-keyword"> =</span><span class="z-entity z-name"> getRecoveryStatus</span><span>(</span><span>policyVerifierAddress</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>isRecovering</span><span>,</span><span class="z-string"> &quot;InRecovering: no ongoing recovery&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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Events for updating guardians, starting for recovery, executing recovery, and canceling recovery</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"> RecoveryStarted</span><span>(</span><span class="z-support">bytes</span><span class="z-variable"> newOwners</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> nonce</span><span>, </span><span class="z-support">uint48</span><span class="z-variable"> expiryTime</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RecoveryExecuted</span><span>(</span><span class="z-support">bytes</span><span class="z-variable"> newOwners</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> nonce</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RecoveryCanceled</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> nonce</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"> Return the domain separator name and version for signatures</span></span> <span class="giallo-l"><span class="z-comment"> * Also return the domainSeparator for EIP-712 signature</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Domain separator name for signatures</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> DOMAIN_SEPARATOR_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"> @notice</span><span class="z-comment"> Domain separator version for signatures</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> DOMAIN_SEPARATOR_VERSION</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"> returns the domainSeparator for EIP-712 signature</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 domainSeparator for EIP-712 signature</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> domainSeparatorV4</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Update /replace guardians and recovery policies</span></span> <span class="giallo-l"><span class="z-comment"> * Multiple recovery policies can be set using an array of RecoveryConfigArg</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"> updateGuardians</span><span>(</span><span class="z-storage z-type">RecoveryConfigArg</span><span>[</span><span>]</span><span class="z-variable"> recoveryConfigArgs</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlySelf</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Generate EIP-712 message hash,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Iterate over signatures for verification,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Verify recovery policy,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Store temporary state or recover immediately based on the result returned by verifyRecoveryPolicy.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> startRecovery</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> configIndex</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> newOwner</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> Permission</span><span>[</span><span>]</span><span class="z-variable"> permissions</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">@dev</span><span class="z-comment"> Execute recovery</span></span> <span class="giallo-l"><span class="z-comment"> * temporary state -&gt; ownerKey rotation</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"> executeRecovery</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> configIndex</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"> cancelRecovery</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> configIndex</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlySelf</span><span class="z-entity z-name"> InRecovering</span><span>(</span><span class="z-entity z-name">policyVerifier</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"> cancelRecoveryByGuardians</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> configIndex</span><span>,</span><span class="z-storage z-type"> Permission</span><span>[</span><span>]</span><span class="z-variable"> permissions</span><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"> InRecovering</span><span>(</span><span class="z-entity z-name">policyVerifier</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"> Get wallet recovery config, check if an identity is a guardian, get the nonce of social recovery, and get the recovery status of the 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"> isGuardian</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> configIndex</span><span>,</span><span class="z-variable"> identity</span><span class="z-variable"> guardian</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"> getRecoveryConfigs</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">RecoveryConfigArg</span><span>[</span><span>]</span><span class="z-variable"> recoveryConfigArgs</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"> getRecoveryNonce</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"> nonce</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"> getRecoveryStatus</span><span>(</span><span class="z-support">address</span><span class="z-variable"> policyVerifier</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"> isRecovering</span><span>,</span><span class="z-support"> uint48</span><span class="z-variable"> expiryTime</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre> <ul> <li>For the <code>Guardian</code>'s signable message, it SHOULD employ <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> type signature to ensure the content of the signature is readable and can be confirmed accurately during the Guardian signing process.</li> <li><code>getRecoveryNonce()</code> SHOULD be separated from nonces associated with account asset operations, as social recovery is a function at the account layer.</li> </ul> <h3 id="recovery-account-workflow"><strong>Recovery Account Workflow</strong></h3> <p>Note: This workflow is presented as an illustrative example to clarify the coordinated usage of the associated interface components. It does not imply a mandatory adherence to this exact process.</p> <ol> <li> <p>A user sets up a <code>recoveryPolicyConfigA</code> within his <code>RecoveryAccount</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">recoveryConfigA</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">RecoveryConfig</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">policyVerifier</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">guardians</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">Identity</span><span class="z-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">A</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">guardianVerifier</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">guardianVerifier1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">signer</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">signerA</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">property</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 30</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">Identity</span><span class="z-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">B</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">guardianVerifier</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">guardianVerifier2</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">signer</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 class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">property</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 30</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">Identity</span><span class="z-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">C</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">guardianVerifier</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">guardianVerifier3</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">signer</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">signerC</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">property</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 40</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">thresholdConfigs</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">threshold</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 50</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">lockPeriod</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">24hours</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">threshold</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 100</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">lockPeriod</span><span class="z-support">&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> ]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span></code></pre></li> <li> <p>When GuardianA and GuardianB assist the user in performing account recovery, they are to confirm the <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> structured data for signing, which might 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">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 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 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></span> <span class="giallo-l"><span> {</span><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 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></span> <span class="giallo-l"><span> {</span><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 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><span>,</span></span> <span class="giallo-l"><span> {</span><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 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></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">StartRecovery</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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">configIndex</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span></span> <span class="giallo-l"><span> {</span><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">newOwners</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span></span> <span class="giallo-l"><span> {</span><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 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></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">StartRecovery</span><span class="z-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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Recovery Account Contract</span><span class="z-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-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">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">verifyingContract</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC</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">policyVerifier</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">newOwners</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcd</span><span class="z-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-constant"> 10</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>In this step, the guardians need to confirm that the domain separator's <code>verifyingContract</code> is the correct <code>RecoveryAccount</code> address for the user, the contract name, version, and chainId are correct, and the <code>policyVerifier</code> and <code>newOwners</code> fields in the <code>message</code> part match the user's provided data.</p> <p>The <code>msgHash</code> is then composed of:</p> <ul> <li> <p><code>msgHash</code> = <code>keccak256("\\x19\\x01" + domainSeparatorV4() + dataHash)</code> Where,</p> </li> <li> <p><code>dataHash</code> = <code>keccak256(EXECUTE_RECOVERY_TYPEHASH + configIndex + keccak256(bytes(newOwners)) + getRecoveryNonce())</code></p> </li> <li> <p><code>EXECUTE_RECOVERY_TYPEHASH</code> = <code>keccak256("StartRecovery(address configIndex, bytes newOwners, uint256 nonce)")</code> The guardians sign this hash to obtain the signature:</p> </li> <li> <p><code>signature</code> = <code>sign(msgHash)</code> The <code>permission</code> is then constructed as:</p> </li> <li> <p><code>permission</code> = <code>guardian + signature</code> Once each Guardian has generated their unique <code>permission</code>, all these individual permissions are collected to form <code>permissions</code>:</p> </li> </ul> <p><code>permissions</code>= [<code>guardianA+signature</code>, <code>guardianB+signature</code>, ...]</p> <p>The <code>permissions</code> is an array that consists of all the permissions of the Guardians who are participating in the recovery process.</p> </li> <li> <p>A bundler or another relayer service calls the <code>RecoveryAccount.startRecovery(0xA, newOwners, permissions)</code> function.</p> </li> <li> <p><code>startRecovery()</code> function's processing logic is as follows:</p> <ul> <li>Generate a message hash (<code>msgHash</code>) from the input parameters <code>0xA</code>, <code>newOwners</code> and internally generated <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> signature parameters and <code>RecoveryNonce</code>.</li> <li>Extract <code>guardian</code> and corresponding <code>signature</code> from the input parameters <code>permissions</code> and process them as follows: <ul> <li>If <code>guardianA.signer</code> is non-empty (Identity A), call <code>IPermissionVerifier(guardianVerifier1).isValidPermissions(signerA, msgHash, permissionA.signature)</code> to validate the signature.</li> <li>If <code>guardianA.signer</code> is empty (Identity B), call the internal function <code>SignatureChecker.isValidSignatureNow(guardianVerifier2, msgHash, permissionB.signature)</code> to validate the signature.</li> </ul> </li> </ul> </li> <li> <p>After successful verification of all <code>guardians</code> signatures, fetch the associated <code>config</code> data for policyVerifier address <code>0xA</code> and call <code>IRecoveryPolicyVerifier(0xA).verifyRecoveryPolicy(permissions, properties)</code>. The function <code>verifyRecoveryPolicy()</code> performs the following checks:</p> <p>Note that the <code>guardians</code> parameter in the function refers to the guardians whose signatures have been successfully verified.</p> <ul> <li>Verify that <code>guardians</code> (Identity A and B) are present in <code>config.guardianInfos</code> list and are unique.</li> <li>Accumulate the <code>property</code> values of <code>guardians</code> (30 + 30 = 60).</li> <li>Compare the calculated result (60) with the <code>config.thresholdConfigs.threshold</code> ,the result is more than the first element (<code>threshold: 50, lockPeriod: 24 hours</code>) but less than the second element (<code>threshold: 100, lockPeriod: ""</code>), the validation is successful, and the lock period of 24 hours is returned.</li> </ul> </li> <li> <p>The <code>RecoveryAccount</code> saves a temporary state <code>{newOwners, block.timestamp + 24 hours}</code> and increments <code>RecoveryNonce</code>. A <code>RecoveryStarted</code> event is emitted.</p> </li> <li> <p>After the expiry time, anyone (usually a relayer) can call <code>RecoveryAccount.executeRecovery()</code> to replace <code>newOwners</code>, remove the temporary state, complete the recovery, and emit a <code>RecoveryExecuteed</code> event.</p> </li> </ol> <h2 id="rationale">Rationale</h2> <p>A primary design rationale for this proposal is to extend a greater diversity of Guardian types and more flexible, customizable recovery policies for a RecoveryAccount. This is achieved by separating the verification logic from the social recovery process, ensuring that the basic logic of the account contract remains unaltered.</p> <p>The necessity of incorporating <code>Verifiers</code> from external contracts arises from the importance of maintaining the inherent recovery logic of the <code>RecoveryAccount</code>. The <code>Verifiers</code>'s logic is designed to be simple and clear, and its fixed invocation format means that any security risks posed by integrating external contracts can be effectively managed.</p> <p>The <code>recoveryConfigs</code> are critical to the <code>RecoveryAccount</code> and should be securely and effectively stored. The access and modification permissions associated with these configurations must be carefully managed and isolated to maintain security. The storage and quantity of <code>recoveryConfigs</code> are not limited to ensure the maximum flexibility of the <code>RecoveryAccount</code>'s implementation.</p> <p>The introduction of <code>recoveryNonce</code> into the <code>RecoveryAccount</code> serves to prevent potential replay attacks arising from the malicious use of Guardian's <code>permissions</code>. The <code>recoveryNonce</code> ensures each recovery process is unique, reducing the likelihood of past successful recovery attempts being maliciously reused.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues are introduced by this standard.</p> <h2 id="reference-implementation">Reference Implementation</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-05-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Qi Zhouhttps://github.com/qizhou Nicolas Deschildrehttps://github.com/nand2 https://wg-eips.ritovision.com/7087/

Add ability to indicate or determine the MIME type of the data returned by a Web3 URL in auto mode

<h2 id="abstract">Abstract</h2> <p>This standard extends the <a href="https://wg-eips.ritovision.com/6860/">ERC-6860</a> <code>web3://</code> standard: in smart contracts not designed for <code>web3://</code> (thus using auto mode), the MIME type of the returned data is either implicit (not advertised by the smart contract) or included within the returned data (<a rel="external" href="https://www.rfc-editor.org/rfc/rfc2397">RFC 2397</a> data URLs). This standard defines additional query parameters so that a MIME type can be returned when fetching a <code>web3://</code> URL in these scenarios.</p> <h2 id="motivation">Motivation</h2> <p>When returning data to the web browser, a <code>Content-Type</code> header indicating the MIME type of the data is strongly recommended, or the data may be incorrectly interpreted and displayed by the web browser.</p> <p>The <code>web3://</code> protocol has 2 modes: manual and auto.</p> <ul> <li>The manual mode is used on smart contracts explicitly requesting this mode (via an interface), so they are expected to signal the MIME type of the returned data, with the mechanism described in <a href="https://wg-eips.ritovision.com/6860/">ERC-6860</a>.</li> <li>On the other hand, the auto mode is used on both smart contracts specifically requesting the mode, and for all the others not signalling anything. While we can expect smart contracts explicitly requesting auto mode to signal the MIME type of the returned data, we cannot expect it for the others contracts.</li> </ul> <p>This standard aims at filling this gap: with the introduction of additional query parameters, it will allow the URL to specify the MIME type of the returned data. Additionally, when the returned data is a <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2397">RFC 2397</a> data URL, it will allow the URL to flag the returned data as data URL, so that the protocol can return the decoded data, and accompany it with the MIME type advertised in the data URL.</p> <h2 id="specification">Specification</h2> <p>The standard introduces three query parameters to determine the MIME type.</p> <ul> <li><code>mime.content=&lt;contentType&gt;</code>, where <code>&lt;contentType&gt;</code> is a MIME type defined in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc6838">RFC 6838</a>. If the <code>&lt;contentType&gt;</code> does not follow the structure of a MIME type, the URL is not fetched and an error message is displayed to the user. After URL decoding, <code>&lt;contentType&gt;</code> is set as the value of the <code>Content-Type</code> header of the response; or</li> <li><code>mime.type=&lt;fileType&gt;</code>, where <code>&lt;fileType&gt;</code> is a filename extension from which a MIME type is determined. If the filename extension is not recognized, the URL is not fetched and an error message is displayed to the user. The MIME type is then set as the value of the <code>Content-Type</code> header of the response; or</li> <li><code>mime.dataurl</code>, which indicates to decode the returned bytes as a <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2397">RFC 2397</a> data URL. After decoding, the decoded body will be returned as the main output, and the MIME type specified in the data URL will be used. If the data cannot be parsed as data URL, an error will be returned.</li> </ul> <p>If multiple query parameters are present, the last query parameter will be applied. If none of the query parameter is specified, <code>Content-Type</code> is defined by <a href="https://wg-eips.ritovision.com/6860/">ERC-6860</a>. If the <code>returns</code> query parameter is specified, the <code>mime.xxx</code> parameters will be ignored and the <code>Content-Type</code> will be defined by <a href="https://wg-eips.ritovision.com/6860/">ERC-6860</a>.</p> <p>In <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2234">RFC 2234</a> ABNF notation, the <a href="https://wg-eips.ritovision.com/6860/">ERC-6860</a> syntax is :</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>attribute = attrName &quot;=&quot; attrValue</span></span> <span class="giallo-l"><span>attrName = &quot;returns&quot;</span></span> <span class="giallo-l"><span> / &quot;returnTypes&quot;</span></span> <span class="giallo-l"><span>attrValue = [ &quot;(&quot; [ retTypes ] &quot;)&quot; ]</span></span></code></pre> <p>This standard evolves it into:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>attribute = retAttr / mimeCAttr / mimeTAttr / mimeDAttr</span></span> <span class="giallo-l"><span>retAttr = retAttrName &quot;=&quot; retAttrValue</span></span> <span class="giallo-l"><span>retAttrName = &quot;returns&quot;</span></span> <span class="giallo-l"><span> / &quot;returnTypes&quot;</span></span> <span class="giallo-l"><span>retAttrValue = [ &quot;(&quot; [ retTypes ] &quot;)&quot; ]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>mimeCAttr = &quot;mime.content=&quot; mimeCAttrVal</span></span> <span class="giallo-l"><span>mimeCAttrVal = # ABNF of MIME type as in RFC 6838 </span></span> <span class="giallo-l"><span>mimeTAttr = &quot;mime.type=&quot; 1*( ALPHA / DIGIT )</span></span> <span class="giallo-l"><span>mimeDAttr = &quot;mime.dataurl&quot;</span></span></code></pre><h3 id="examples">Examples</h3> <h4 id="example-1">Example 1</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://0x91cf36c92feb5c11d3f5fe3e8b9e212f7472ec14/accessorizedImageOf/1289?mime.content=image/svg%2Bxml</span></span></code></pre> <p>where the contract is in auto mode.</p> <p>The protocol will call the contract <code>0x91cf36c92feb5c11d3f5fe3e8b9e212f7472ec14</code> with the message defined in <a href="https://wg-eips.ritovision.com/6860/">ERC-6860</a> and the returned <code>Content-Type</code> header will be set to <code>image/svg+xml</code>.</p> <h4 id="example-2">Example 2</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://0x91cf36c92feb5c11d3f5fe3e8b9e212f7472ec14/accessorizedImageOf/1289?mime.type=svg</span></span></code></pre> <p>where the contract is in auto mode.</p> <p>The protocol will call the contract <code>0x91cf36c92feb5c11d3f5fe3e8b9e212f7472ec14</code> with the message defined in <a href="https://wg-eips.ritovision.com/6860/">ERC-6860</a> and the returned <code>Content-Type</code> header will be set to <code>image/svg+xml</code>.</p> <h4 id="example-3">Example 3</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://0xff9c1b15b16263c61d017ee9f65c50e4ae0113d7/tokenURI/100?mime.dataurl</span></span></code></pre> <p>where the contract is in auto mode, and the returned data is <code>data:application/json,["xx"]</code>.</p> <p>The protocol will call the contract <code>0xff9c1b15b16263c61d017ee9f65c50e4ae0113d7</code> with the message defined in <a href="https://wg-eips.ritovision.com/6860/">ERC-6860</a> and decode the data according to the <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2397">RFC 2397</a> data URL standard. The returned output will be <code>["xx"]</code> and the returned <code>Content-Type</code> header will be set to <code>application/json</code>.</p> <h2 id="rationale">Rationale</h2> <p>The standard uses three different query parameters rather than a single query parameter to avoid confusion - an implementer or a user can easily tell the expected returned MIME of a link. Further, in auto mode, the query parameters are not used to form the EVM message (e.g., calldata) and thus it is safe to introduce new query parameters.</p> <h2 id="security-considerations">Security Considerations</h2> <p>These new query parameters introduce Cross Site Scripting attack vectors : an attacker could exploit string or bytes returning methods he can influence by making them return unfiltered data injected by him, and then craft a URL to make the returned data interpreted as HTML, and then send the URL to victims. If the web3 hostname is well known, the victim may get a false sense of security.</p> <p>Malicious actions using javascript are broad and can include :</p> <ul> <li>Extraction of data of web storage APIs (cookies, localStorage, sessionStorage, indexedDB), sent to the attacker</li> <li>Triggering a signature request or transaction confirmation request (via a wallet javascript interface)</li> </ul> <p>Cross Site Scripting is a classical attack vector in HTTP websites, we expect developers to be wary of this. Nonetheless; the ability to specify the MIME type is unusual. <code>auto</code> mode websites should be discouraged and the attack vectors well documented.</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-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Samuel Gwlanold Edoumouhttps://github.com/Edoumou https://wg-eips.ritovision.com/7092/

Represents debt issued by entities to investors.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces fixed-income financial bonds with key characteristics defined to facilitate bond issuance in the primary market and enable buying or selling bonds in the secondary market. The standard also provides cross-chain functionalities for bonds operations and management across multiple blockchains.</p> <h2 id="motivation">Motivation</h2> <p>Fixed-income instruments are a widely utilized asset class for corporations and other entities raising funds. However, transitioning to tokenized bonds is challenging due to existing standards like <a href="https://wg-eips.ritovision.com/3475/">ERC-3475</a>, which introduces unfamiliar concepts and leads to unnecessary gas consumption. Additionally, the lack of named variables like coupon, maturity date, and principal, makes it difficult to implement ERC-3475 since developers need to remember which metadata is assigned to each parameter.</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><strong>Every contract compliant with this ERC MUST implement the following Token Interface as well as the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> 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 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">@title</span><span class="z-comment"> ERC-7092 Financial Bonds Standard</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"> IERC7092</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-comment"> events</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"> MUST be emitted when bond tokens are transferred, issued or redeemed, except during contract creation</span></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 account that owns bonds</span></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 that receives the bond</span></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 bond tokens to be transferred</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-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"> MUST be emitted when an account is approved or when the allowance is decreased</span></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"> bond token&#39;s 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"> _spender</span><span class="z-comment"> the account to be allowed to spend bonds</span></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 bond tokens allowed by _owner to be spent by `_spender`</span></span> <span class="giallo-l"><span class="z-comment"> * Or amount of bond tokens to decrease allowance from `_spender`</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-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"> MUST be emitted when multiple bond tokens are transferred, issued or redeemed, with the exception being during contract creation</span></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"> array of bondholders accounts</span></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"> array of accounts to transfer bonds 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"> _amount</span><span class="z-comment"> array of amounts of bond tokens to be transferred</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> ** OPTIONAL - interfaces and other contracts MUST NOT expect this function to be present. MUST be emitted in `batchTransfer` and `batchTransferFrom` functions</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"> TransferBatch</span><span>(</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</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"> MUST be emitted when multiple accounts are approved or when the allowance is decreased from multiple accounts</span></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"> bondholder 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"> _spender</span><span class="z-comment"> array of accounts to be allowed to spend bonds, or to decrase the allowance from</span></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"> array of amounts of bond tokens allowed by `_owner` to be spent by multiple accounts in `_spender`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> ** OPTIONAL - interfaces and other contracts MUST NOT expect this function to be present. MUST be emitted in `batchApprove` and `batchDecreaseAllowance` functions</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"> ApprovalBatch</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>[</span><span>]</span><span class="z-variable"> _spender</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</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-comment"> getter functions</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 the bond isin</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"> isin</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns the bond name</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns the bond symbol</span></span> <span class="giallo-l"><span class="z-comment"> * It is RECOMMENDED to represent the symbol as a combination of the issuer Issuer&#39;shorter name and the maturity date</span></span> <span class="giallo-l"><span class="z-comment"> * Ex: If a company named Green Energy issues bonds that will mature on october 25, 2030, the bond symbol could be `GE30` or `GE2030` or `GE102530`</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns the bond currency. This is the contract address of the token used to pay and return the bond principal</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"> 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">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"> Returns the bond denominiation. This is the minimum amount in which the Bonds may be issued. It must be expressend in unit of the principal currency</span></span> <span class="giallo-l"><span class="z-comment"> * ex: If the denomination is equal to 1,000 and the currency is USDC, then the bond denomination is equal to 1,000 USDC</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"> denomination</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"> Returns the issue volume (total debt amount). It is RECOMMENDED to express the issue volume in denomination unit.</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"> issueVolume</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"> Returns the bond interest rate. It is RECOMMENDED to express the interest rate in basis point unit.</span></span> <span class="giallo-l"><span class="z-comment"> * 1 basis point = 0.01% = 0.0001</span></span> <span class="giallo-l"><span class="z-comment"> * ex: if interest rate = 5%, then coupon() =&gt; 500 basis points</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"> couponRate</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"> Returns the date when bonds were issued to investors. This is a Unix Timestamp like the one returned by block.timestamp</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"> issueDate</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"> Returns the bond maturity date, i.e, the date when the principal is repaid. This is a Unix Timestamp like the one returned by block.timestamp</span></span> <span class="giallo-l"><span class="z-comment"> * The maturity date MUST be greater than the issue date</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"> maturityDate</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"> Returns the principal of an account. It is RECOMMENDED to express the principal in the bond currency unit (USDC, DAI, 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"> _account</span><span class="z-comment"> account 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"> principalOf</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _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 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 the amount of tokens the `_spender` account has been authorized by the `_owner``</span></span> <span class="giallo-l"><span class="z-comment"> * account to manage their bonds</span></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"> the bondholder 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"> _spender</span><span class="z-comment"> the address that has been authorized by the bondholder</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-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-comment"> setter functions</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"> Authorizes `_spender` account to manage `_amount`of their bond 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"> _spender</span><span class="z-comment"> the address to be authorized by the bondholder</span></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 bond tokens to approve</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"> _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> <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"> Lowers the allowance of `_spender` by `_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"> _spender</span><span class="z-comment"> the address to be authorized by the bondholder</span></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 bond tokens to remove from allowance</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"> decreaseAllowance</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"> _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> <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` bonds to address `_to`. This methods also allows to attach data to the token that is being transferred</span></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 send the bonds 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"> _amount</span><span class="z-comment"> amount of bond tokens 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"> _data</span><span class="z-comment"> additional information provided by the token holder</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"> _amount</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-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"> Moves `_amount` bonds from an account that has authorized the caller through the approve function</span></span> <span class="giallo-l"><span class="z-comment"> * This methods also allows to attach data to the token that is being transferred</span></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 bondholder 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"> the address to transfer bonds 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"> _amount</span><span class="z-comment"> amount of bond tokens 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"> _data</span><span class="z-comment"> additional information provided by the token holder</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 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"> _amount</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-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"> batch functions</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"> Authorizes multiple spender accounts to manage a specified `_amount` of the bondholder 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"> _spender</span><span class="z-comment"> array of accounts to be authorized by the bondholder</span></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"> array of amounts of bond tokens to approve</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * OPTIONAL - interfaces and other contracts MUST NOT expect these values to be present. The method is used to improve usability.</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"> batchApprove</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"> _spender</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"> _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> <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"> Decreases the allowance of multiple spenders by corresponding amounts in `_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"> _spender</span><span class="z-comment"> array of accounts to be authorized by the bondholder</span></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"> array of amounts of bond tokens to decrease the allowance from</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * OPTIONAL - interfaces and other contracts MUST NOT expect this function to be present. The method is used to decrease token allowance.</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"> batchDecreaseAllowance</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"> _spender</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"> _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> <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 multiple bonds with amounts specified in the array `_amount` to the corresponding accounts in the array `_to`, with the option to attach additional 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"> _to</span><span class="z-comment"> array of accounts to send the bonds 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"> _amount</span><span class="z-comment"> array of amounts of bond tokens 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"> _data</span><span class="z-comment"> array of additional information provided by the token holder</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * OPTIONAL - interfaces and other contracts MUST NOT expect this function to be present.</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"> batchTransfer</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"> _amount</span><span>,</span><span class="z-support"> bytes</span><span>[</span><span>]</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-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"> Transfers multiple bonds with amounts specified in the array `_amount` to the corresponding accounts in the array `_to` from an account that have been authorized by the `_from` account</span></span> <span class="giallo-l"><span class="z-comment"> * This method also allows to attach data to tokens that are being transferred</span></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"> array of bondholder accounts</span></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"> array of accounts to transfer bond tokens 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"> _amount</span><span class="z-comment"> array of amounts of bond tokens 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"> _data</span><span class="z-comment"> array of additional information provided by the token holder</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> ** OPTIONAL - interfaces and other contracts MUST NOT expect this function to be present.</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"> batchTransferFrom</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"> _from</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"> _amount</span><span>,</span><span class="z-support"> bytes</span><span>[</span><span>]</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-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><h3 id="additional-bond-parameters-interface">Additional bond parameters Interface</h3> <p>The <code>IERC7092ESG</code> interface is OPTIONAL for contracts implementing this proposal. This interface MAY be used to improve the standard usability.</p> <ul> <li>The <code>currencyOfCoupon</code> The currency used for coupon payment may be different from the currency used to repay the principal</li> <li>The <code>couponType</code> MAY be employed to signify the interest rate that the issuer has committed to paying to investors, which may take various forms such as zero coupon, fixed rate, floating rate, and more.</li> <li>The <code>couponFrequency</code> refers to how often the bond pays interest to its bondholders, and is typically expressed in terms of time periods, such as: Annual, Semi-Annual, Quarterly, or Monthly.</li> <li>The <code>dayCountBasis</code> is used to calculate the accrued interest on a bond between two coupon payment dates or other specific periods. Some of the day count basis are: Actual/Actual, 30/360, Actual/360, Actual/365, or 30/365</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: 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"> IERC7092ESG</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">@notice</span><span class="z-comment"> Returns the number of decimals used by the bond. For example, if it returns `10`, it means that the token amount MUST be multiplied by 10000000000 to get the standard representation.</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"> decimals</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Rreturns the coupon currency, which is represented by the contract address of the token used to pay coupons. It can be the same as the one used for the principal</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"> currencyOfCoupon</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"> Returns the coupon type</span></span> <span class="giallo-l"><span class="z-comment"> * For example, 0 can denote Zero coupon, 1 can denote Fixed Rate, 2 can denote Floating Rate, and so on</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"> couponType</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns the coupon frequency, i.e. the number of times coupons are paid in a year.</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"> couponFrequency</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"> Returns the day count basis</span></span> <span class="giallo-l"><span class="z-comment"> * For example, 0 can denote actual/actual, 1 can denote actual/360, and so on</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"> dayCountBasis</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></span></code></pre><h3 id="cross-chain-interface">Cross-chain Interface</h3> <p>The standard permits the implementation of the <code>IERC7092CrossChain</code> interface for cross-chain management of bond tokens. This interface is OPTIONAL and may be used by applications to allow cross-chain transactions. Any function initiating a cross-chain transaction MUST explicitly define the destination chain identifier <code>destinationChainID</code> and specify the target smart contract <code>destinationContract</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.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"> IERC7092CrossChain</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-comment"> events</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"> MUST be emitted when bond tokens are transferred or redeemed in a cross-chain 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"> _from</span><span class="z-comment"> bondholder 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"> account the transfer bond tokens 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"> _amount</span><span class="z-comment"> amount of bond tokens to be transferred</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _destinationChainID</span><span class="z-comment"> The unique ID that identifies the destination Chain</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"> CrossChainTransfer</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"> _amount</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> _destinationChainID</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"> MUST be emitted when several bond tokens are transferred or redeemed in a cross-chain 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"> _from</span><span class="z-comment"> array of bondholders accounts</span></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"> array of accounts that receive the bond</span></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"> array of amount of bond tokens to be transferred</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _destinationChainID</span><span class="z-comment"> array of unique IDs that identify the destination Chain</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"> CrossChainTransferBatch</span><span>(</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> _amount</span><span>, </span><span class="z-support">bytes32</span><span>[</span><span>]</span><span class="z-variable"> _destinationChainID</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"> MUST be emitted when an account is approved to spend the bondholder&#39;s tokens in a different chain than the current chain</span></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"> the bondholder 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"> _spender</span><span class="z-comment"> the account to be allowed to spend bonds</span></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 bond tokens allowed by `_owner` to be spent by `_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"> _destinationChainID</span><span class="z-comment"> The unique ID that identifies the destination Chain</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"> CrossChainApproval</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"> _amount</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> _destinationChainID</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"> MUST be emitted when multiple accounts in the array `_spender` are approved or when the allowances of multiple accounts in the array `_spender` are reduced on the destination chain which MUST be different than the current chain</span></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"> bond token&#39;s 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"> _spender</span><span class="z-comment"> array of accounts to be allowed to spend bonds</span></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"> array of amount of bond tokens allowed by _owner to be spent by _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"> _destinationChainID</span><span class="z-comment"> array of unique IDs that identify the destination Chain</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"> CrossChainApprovalBatch</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>[</span><span>]</span><span class="z-variable"> _spender</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> _amount</span><span>, </span><span class="z-support">bytes32</span><span>[</span><span>]</span><span class="z-variable"> _destinationChainID</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> functions</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"> Authorizes the `_spender` account to manage a specified `_amount`of the bondholder bond tokens on the destination Chain</span></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"> account to be authorized by the bondholder</span></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 bond tokens 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"> _destinationChainID</span><span class="z-comment"> The unique ID that identifies the destination Chain.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _destinationContract</span><span class="z-comment"> The smart contract to interact with in the destination Chain</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"> crossChainApprove</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"> _amount</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _destinationChainID</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _destinationContract</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">@notice</span><span class="z-comment"> Authorizes multiple spender accounts in `_spender` to manage specified amounts in `_amount` of the bondholder tokens on the destination chain</span></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"> array of accounts to be authorized by the bondholder</span></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"> array of amounts of bond tokens 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"> _destinationChainID</span><span class="z-comment"> array of unique IDs that identifies the destination Chain.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _destinationContract</span><span class="z-comment"> array of smart contracts to interact with in the destination Chain in order to Deposit or Mint tokens that are transferred.</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"> crossChainBatchApprove</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"> _spender</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"> _amount</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"> _destinationChainID</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"> _destinationContract</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">@notice</span><span class="z-comment"> Decreases the allowance of `_spender` by a specified `_amount` on the destination Chain</span></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 be authorized by the bondholder</span></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 bond tokens to remove from allowance</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _destinationChainID</span><span class="z-comment"> The unique ID that identifies the destination Chain.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _destinationContract</span><span class="z-comment"> The smart contract to interact with in the destination Chain in order to Deposit or Mint tokens that are transferred.</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"> crossChainDecreaseAllowance</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"> _amount</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _destinationChainID</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _destinationContract</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">@notice</span><span class="z-comment"> Decreases the allowance of multiple spenders in `_spender` by corresponding amounts specified in the array `_amount` on the destination chain</span></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"> array of accounts to be authorized by the bondholder</span></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"> array of amounts of bond tokens to decrease the allowance from</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _destinationChainID</span><span class="z-comment"> array of unique IDs that identifies the destination Chain.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _destinationContract</span><span class="z-comment"> array of smart contracts to interact with in the destination Chain in order to Deposit or Mint tokens that are transferred.</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"> crossChainBatchDecreaseAllowance</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"> _spender</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"> _amount</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"> _destinationChainID</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"> _destinationContract</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">@notice</span><span class="z-comment"> Moves `_amount` bond tokens to the address `_to` from the current chain to another chain (e.g., moving tokens from Ethereum to Polygon).</span></span> <span class="giallo-l"><span class="z-comment"> * This methods also allows to attach data to the token that is being transferred</span></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"> account to send bond tokens 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"> _amount</span><span class="z-comment"> amount of bond tokens 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"> _data</span><span class="z-comment"> additional information provided by the bondholder</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _destinationChainID</span><span class="z-comment"> The unique ID that identifies the destination Chain.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _destinationContract</span><span class="z-comment"> The smart contract to interact with in the destination Chain in order to Deposit or Mint bond tokens that are transferred.</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"> crossChainTransfer</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"> _amount</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-support"> bytes32</span><span class="z-variable z-parameter z-function"> _destinationChainID</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _destinationContract</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">@notice</span><span class="z-comment"> Transfers multiple bond tokens with amounts specified in the array `_amount` to the corresponding accounts in the array `_to` from the current chain to another chain (e.g., moving tokens from Ethereum to Polygon).</span></span> <span class="giallo-l"><span class="z-comment"> * This methods also allows to attach data to the token that is being transferred</span></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"> array of accounts to send the bonds 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"> _amount</span><span class="z-comment"> array of amounts of bond tokens 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"> _data</span><span class="z-comment"> array of additional information provided by the bondholder</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _destinationChainID</span><span class="z-comment"> array of unique IDs that identify the destination Chains.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _destinationContract</span><span class="z-comment"> array of smart contracts to interact with in the destination Chains in order to Deposit or Mint bond tokens that are transferred.</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"> crossChainBatchTransfer</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"> _amount</span><span>,</span><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _data</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"> _destinationChainID</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"> _destinationContract</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">@notice</span><span class="z-comment"> Transfers `_amount` bond tokens from the `_from`account to the `_to` account from the current chain to another chain. The caller must be approved by the `_from` address.</span></span> <span class="giallo-l"><span class="z-comment"> * This methods also allows to attach data to the token that is being transferred</span></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 bondholder 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"> the account to transfer bonds 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"> _amount</span><span class="z-comment"> amount of bond tokens 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"> _data</span><span class="z-comment"> additional information provided by the token 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"> _destinationChainID</span><span class="z-comment"> The unique ID that identifies the destination Chain.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _destinationContract</span><span class="z-comment"> The smart contract to interact with in the destination Chain in order to Deposit or Mint tokens that are transferred.</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"> crossChainTransferFrom</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"> _amount</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-support"> bytes32</span><span class="z-variable z-parameter z-function"> _destinationChainID</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _destinationContract</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">@notice</span><span class="z-comment"> Transfers several bond tokens with amounts specified in the array `_amount` from accounts in the array `_from` to accounts in the array `_to` from the current chain to another chain.</span></span> <span class="giallo-l"><span class="z-comment"> * The caller must be approved by the `_from` accounts to spend the corresponding amounts specified in the array `_amount`</span></span> <span class="giallo-l"><span class="z-comment"> * This methods also allows to attach data to the token that is being transferred</span></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"> array of bondholder addresses</span></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"> array of accounts to transfer bonds 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"> _amount</span><span class="z-comment"> array of amounts of bond tokens 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"> _data</span><span class="z-comment"> array of additional information provided by the token 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"> _destinationChainID</span><span class="z-comment"> array of unique IDs that identifies the destination Chain.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _destinationContract</span><span class="z-comment"> array of smart contracts to interact with in the destination Chain in order to Deposit or Mint tokens that are transferred.</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"> crossChainBatchTransferFrom</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"> _from</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"> _amount</span><span>,</span><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _data</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"> _destinationChainID</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"> _destinationContract</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><h2 id="rationale">Rationale</h2> <p>The design of this ERC aims to simplify the migration to tokenized bonds by maintaining consistency with traditional bond standards. This approach allows fixed-income instruments to be represented as on-chain tokens, manageable through wallets, and utilized by applications like decentralized exchanges, while avoiding the complexities and inefficiencies associated with other standards. This ERC facilitates the creation of new bond tokens with characteristics akin to traditional bonds, enhancing accessibility, liquidity, and cost-efficiency in bond trading and management.</p> <p>The use of traditional finance terminology, like <code>issueVolume</code> and <code>principalOf</code>, is aimed at maintaining consistency with traditional bond language, which eases the adaptation for traditional entities.</p> <h3 id="total-supply-and-account-balance">Total Supply and Account Balance</h3> <p>The <code>totalSupply</code> and <code>balanceOf</code> functions are not defined as they can be derived from <code>issueVolume</code> and <code>principalOf</code>, and <code>denomination</code>. However, these functions can be be added in any contract implementing this standard, ensuring the proper relationship between these values.</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"> 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 class="z-entity z-name"> issueVolume</span><span>(</span><span>)</span><span class="z-keyword"> /</span><span class="z-entity z-name"> denomination</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"> balance0f</span><span>(</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-keyword"> return</span><span class="z-entity z-name"> principal</span><span>(</span><span>account</span><span>)</span><span class="z-keyword"> /</span><span class="z-entity z-name"> denomination</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC is not backwards compatible with existing standards like <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> due to the absence of certain functions like <code>totalSupply</code> or <code>balanceOf</code>. A pure implementation of this standard is RECOMMENDED for issuing tokenized bonds, as any hybrid solution with other mentioned standards SHOULD fail.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The complete Reference Implementation can be found <a href="https://wg-eips.ritovision.com/7092/./assets/ERC7092.sol">here</a>.</p> <p>Bonds with embedded options like callable, puttable, or convertible bonds can be created by inheriting from the reference <a href="https://wg-eips.ritovision.com/7092/./assets/ERC7092.sol"><code>ERC7092.sol</code></a> that integrates the proposed interface.</p> <h3 id="callable-bonds">CALLABLE BONDS:</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-keyword">import</span><span class="z-string"> &#39;ERC7092.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"> ERC7092Callable</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC7092</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> WRITE THE LOGIC TO ALLOW THE ISSUER TO CALL BONDS</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> STATE VARIABLES AND FUNCTIONS NEEDED</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"> call bonds owned by `_investor`</span></span> <span class="giallo-l"><span class="z-comment"> * MUST be called by the issuer only</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"> call</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _investor</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-variable z-language">msg.sender</span><span class="z-keyword"> ==</span><span> _issuer</span><span>[</span><span>bondISIN</span><span>]</span><span>.</span><span>issuerAddress</span><span>,</span><span class="z-string"> &quot;ERC7092Callable: ONLY_ISSUER&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_principals</span><span>[</span><span>_investor</span><span>]</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;ERC7092Callable: NO_BONDS&quot;</span><span>)</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>timestamp </span><span class="z-keyword">&lt;</span><span> _bond</span><span>[</span><span>bondISIN</span><span>]</span><span>.</span><span>maturityDate</span><span>,</span><span class="z-string"> &quot;ERC7092Callable: BOND_MATURED&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> principal </span><span class="z-keyword">=</span><span> _principals</span><span>[</span><span>_investor</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> _principals</span><span>[</span><span>_investor</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 class="z-comment"> //</span><span class="z-comment"> ADD LOGIC HERE</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="puttable-bonds">PUTTABLE BONDS:</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-keyword">import</span><span class="z-string"> &#39;ERC7092.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"> ERC7092Puttable</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC7092</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> WRITE THE LOGIC TO ALLOW INVESTORS TO PUT BONDS</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> STATE VARIABLES AND FUNCTIONS NEEDED</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"> put bonds</span></span> <span class="giallo-l"><span class="z-comment"> * MUST be called by investors who own bonds</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"> put</span><span>(</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>_principals</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;ERC7092Puttable: ONLY_INVESTORS&quot;</span><span>)</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>timestamp </span><span class="z-keyword">&lt;</span><span> _bond</span><span>[</span><span>bondISIN</span><span>]</span><span>.</span><span>maturityDate</span><span>,</span><span class="z-string"> &quot;ERC7092Puttable: BOND_MATURED&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> principal </span><span class="z-keyword">=</span><span> _principals</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> _principals</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 class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ADD LOGIC</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="convertible-bonds">CONVERTIBLE BONDS:</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-keyword">import</span><span class="z-string"> &#39;ERC7092.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"> ERC7092Convertible</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC7092</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> WRITE THE LOGIC TO ALLOW INVESTOR OR ISSUER TO CONVERT BONDS TO EQUITY</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> STATE VARIABLES AND FUNCTIONS NEEDED</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"> convert bonds to equity. Here we assumed that the investors must convert their bonds to equity</span></span> <span class="giallo-l"><span class="z-comment"> * Issuer can also convert invetsors bonds to equity.</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"> convert</span><span>(</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>_principals</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;ERC7092Convertible: ONLY_INVESTORS&quot;</span><span>)</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>timestamp </span><span class="z-keyword">&lt;</span><span> _bond</span><span>[</span><span>bondISIN</span><span>]</span><span>.</span><span>maturityDate</span><span>,</span><span class="z-string"> &quot;ERC7092Convertible: BOND_MATURED&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> principal </span><span class="z-keyword">=</span><span> _principals</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> _principals</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 class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ADD LOGIC HERE</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="identity-registry">Identity Registry</h3> <p>This standard is designed specifically for tokenizing bonds. It does not inherently manage information pertaining to bondholders' identities. However, to enhance compliance with regulatory requirements and improve transparency, an identity registry can be added on top of this standard to store the identity of all authorized investors.</p> <p>By maintaining an identity registry, issuers can ensure that bond tokens issued under the <code>ERC7092</code> standard are transferred only to registered and authorized entities. This practice aligns with regulatory compliance measures and provides a structured way to manage and verify the identity of bondholders. It also helps prevent unauthorized or non-compliant transfers of bond tokens.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Implementing this ERC requires careful consideration of security risks related to functions approving operators to manage owner's bonds and functions allowing bond transfers. The use of these functions necessitates robust validation to ensure only the bond owner or approved accounts can call 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-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/5615/

A simple mechanism to fetch token supply data from ERC-1155 tokens

<h2 id="abstract">Abstract</h2> <p>This ERC standardizes an existing mechanism to fetch token supply data from <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> tokens. It adds a <code>totalSupply</code> function, which fetches the number of tokens with a given <code>id</code>, and an <code>exists</code> function, which checks for the existence of a given <code>id</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> <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"> ERC1155Supply</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC1155</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @notice This function MUST return whether the given token id exists, previously existed, or may exist</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param id The token id of which to check the existence</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @return Whether the given token id exists, previously existed, or may exist</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> exists</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 class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @notice This function MUST return the number of tokens with a given id. If the token id does not exist, it MUST return 0.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param id The token id of which fetch the total supply</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @return The total supply of the given token id</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></span></code></pre> <p>Implementations MAY support <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface discovery, but consumers MUST NOT rely on it.</p> <h2 id="rationale">Rationale</h2> <p>This ERC does not implement <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>, as this interface is simple enough that the extra complexity is unnecessary and would cause incompatibilities with pre-existing implementations.</p> <p>The <code>totalSupply</code> and <code>exists</code> functions were modeled after <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>.</p> <p><code>totalSupply</code> does not revert if the token ID does not exist, since contracts that care about that case should use <code>exists</code> instead (which might return false even if <code>totalSupply</code> is zero).</p> <p><code>exists</code> is included to differentiate between the two ways that <code>totalSupply</code> could equal zero (either no tokens with the given ID have been minted yet, or no tokens with the given ID will ever be minted).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC is designed to be backward compatible with the OpenZeppelin <code>ERC1155Supply</code>.</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-05-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Piyush Chittarahttps://github.com/piyush-chittara StreamNFThttps://github.com/streamnft-tech Srinivas Joshihttps://github.com/SrinivasJoshi https://wg-eips.ritovision.com/7066/

Interface for enabling locking of ERC-721 using locker and approved

<h2 id="abstract">Abstract</h2> <p>An extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, this standard incorporates <code>locking</code> features into NFTs, allowing for various uses while preventing sale or transfer. The token's <code>owner</code> can <code>lock</code> it, setting up locker address (either an EOA or a contract) that exclusively holds the power to unlock the token. Owner can also provide approval for <code>tokenId</code>, enabling ability to lock asset while address holds the token approval. Token can also be locked by <code>approved</code>, assigning locker to itself. Upon token transfer, these rights get purged.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/721/">ERC-721</a> has sparked an unprecedented surge in demand for NFTs. However, despite this tremendous success, the NFT economy suffers from secondary liquidity where it remains illiquid in owner’s wallet. There are projects which aim to address the liquidity challenge, but they entail the below mentioned inconveniences and risks for owners as they necessitate transferring the participating NFTs to the projects' contracts.</p> <ul> <li>Loss of utility: The utility value of NFTs diminishes when they are transferred to an escrow account, no longer remaining under the direct custody of the owners.</li> <li>Lack of composability: The market could benefit from increased liquidity if NFT owners had access to multiple financial tools, such as leveraging loans and renting out their assets for maximum returns. Composability serves as the missing piece in creating a more efficient market.</li> <li>Smart contract vulnerabilities: NFTs are susceptible to loss or theft due to potential bugs or vulnerabilities present in the smart contracts they rely on.</li> </ul> <p>The aforementioned issues contribute to a poor user experience (UX), and we propose enhancing the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard by implementing a native locking mechanism: Rather than being transferred to a smart contract, an NFT remains securely stored in self-custody but is locked. During the lock period, the NFT's transfer is restricted while its other properties remain unchanged. NFT Owner retains the ability to use or distribute it’s utility.</p> <p>NFTs have numerous use cases where the NFT must remain within the owner's wallet, even when it serves as collateral for a loan. Whether it's authorizing access to a Discord server, or utilizing NFT within a play-to-earn (P2E) game, owner should have the freedom to do so throughout the lending period. Just as real estate owner can continue living in their mortgaged house, take personal loan or keep tenants to generate passive income, these functionalities should be available to NFT owners to bring more investors in NFT economy.</p> <p>Lockable NFTs enable the following use cases :</p> <ul> <li>NFT-collateralized loans: Utilize NFT as collateral for a loan without locking it on the lending protocol contract. Instead, lock it within owner’s wallet while still enjoying all the utility of NFT.</li> <li>No collateral rentals of NFTs: Borrow an NFT for a fee without the need for significant collateral. Renter can use the NFT but not transfer it, ensuring the lender's safety. The borrowing service contract automatically returns the NFT to the lender once the borrowing period expires.</li> <li>Buy Now Pay Later (BNPL): The buyer receives the locked NFT and can immediately begin using it. However, they are unable to sell the NFT until all installments are paid. Failure to complete the full payment results in the NFT returning to the seller, along with a fee.</li> <li>Composability: Maximize liquidity by having access to multiple financial tools. Imagine taking a loan against NFT and putting it on rentals to generate passive income.</li> <li>Primary sales: Mint an NFT for a partial payment and settle the remaining amount once owner is satisfied with the collection's progress.</li> <li>Soulbound: Organization can mint and self-assign <code>locker</code>, send token to user and lock the asset.</li> <li>Safety: Safely and conveniently use exclusive blue chip NFTs. Lockable extension allows owner to lock NFT and designate secure cold wallet as the unlocker. This way, owner can keep NFT on MetaMask and easily use it, even if a hacker gains access to MetaMask account. Without access to the cold wallet, the hacker cannot transfer NFT, ensuring its safety.</li> </ul> <p>This proposal is different from other locking proposals in number of ways:</p> <ul> <li>This implementation provides a minimal implementation of <code>lock</code> and <code>unlock</code> and believes other conditions like time-bound are great ideas but can be achieved without creating a specific implementation. Locking and Unlocking can be based on any conditions (e.g. repayment, expiry). Therefore time-bound unlocks a relatively specific use case that can be achieved via smart-contracts themselves without that being a part of the token contract.</li> <li>This implementation proposes a separation of rights between locker and approver. Token can be locked with approval and approved can unlock and withdraw tokens (opening up opportunities like renting, lending, BNPL etc), and token can be locked lacking the rights to revoke token, yet can unlock if required (opening up opportunities like account-bound NFTs).</li> <li>Our proposal implement ability to <code>transferAndLock</code> which can be used to transfer, lock and optionally approve token. Enabling the possibility of revocation after transfer.</li> </ul> <p>By extending the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard, the proposed standard enables secure and convenient management of underlying NFT assets. It natively supports prevalent NFTFi use cases such as staking, lending, and renting. We anticipate that this proposed standard will foster increased engagement of NFT owners in NFTFi projects, thereby enhancing the overall vitality of the NFT ecosystem.</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="overview">Overview</h3> <p><a href="https://wg-eips.ritovision.com/721/">ERC-721</a> compliant contracts MAY implement this EIP to provide standard methods of locking and unlocking the token at its current owner address.</p> <p>Token owner MAY <code>lock</code> the token and assign <code>locker</code> to some <code>address</code> using <code>lock(uint256 tokenId, address _locker)</code> function, this MUST set <code>locker</code> to <code>_locker</code>. Token owner or approved MAY <code>lock</code> the token using <code>lock(uint256 tokenId)</code> function, this MUST set <code>locker</code> to <code>msg.sender</code>. Token MAY be <code>unlocked</code> by <code>locker</code> using <code>unlock</code> function. <code>unlock</code> function MUST delete <code>locker</code> mapping and default to <code>address(0)</code>.</p> <p>If the token is <code>locked</code>, the <code>lockerOf</code> function MUST return an address that is <code>locker</code> and can <code>unlock</code> the token. For tokens that are not <code>locked</code>, the <code>lockerOf</code> function MUST return <code>address(0)</code>.</p> <p><code>lock</code> function MUST revert if token is already <code>locked</code>. <code>unlock</code> function MUST revert if token is not <code>locked</code>. ERC-721 <code>approve</code> function MUST revert if token is <code>locked</code>. ERC-721 functions that transfer ownership of a token MUST revert if token is <code>locked</code>, unless <code>msg.sender</code> is <code>approved</code> and <code>locker</code> both. After ERC-721 token transfer function call, values of <code>locker</code> and <code>approved</code> MUST be purged.</p> <p>Token MAY be transferred and <code>locked</code>, also assign <code>approval</code> to <code>locker</code> using <code>transferAndLock</code> function. This is RECOMMENDED for use-cases where Token transfer and subsequent revocation is REQUIRED.</p> <h3 id="interface">Interface</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>pragma solidity &gt;=0.7.0 &lt;0.9.0;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/// @title Lockable Extension for ERC721</span></span> <span class="giallo-l"><span>/// @dev Interface for the Lockable extension</span></span> <span class="giallo-l"><span>/// @author StreamNFT </span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>interface IERC7066{</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Emitted when tokenId is locked</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event Lock (uint256 indexed tokenId, address _locker);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Emitted when tokenId is unlocked</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event Unlock (uint256 indexed tokenId);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Lock the tokenId if msg.sender is owner or approved and set locker to msg.sender</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function lock(uint256 tokenId) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Lock the tokenId if msg.sender is owner and set locker to _locker</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function lock(uint256 tokenId, address _locker) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Unlocks the tokenId if msg.sender is locker</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function unlock(uint256 tokenId) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Tranfer and lock the token if the msg.sender is owner or approved. </span></span> <span class="giallo-l"><span> * Lock the token and set locker to caller</span></span> <span class="giallo-l"><span> * Optionally approve caller if bool setApprove flag is true</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function transferAndLock(uint256 tokenId, address from, address to, bool setApprove) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Returns the wallet, that is stated as unlocking wallet for the tokenId.</span></span> <span class="giallo-l"><span> * If address(0) returned, that means token is not locked. Any other result means token is locked.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function lockerOf(uint256 tokenId) external view returns (address);</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This proposal set <code>locker[tokenId]</code> to <code>address(0)</code> when token is <code>unlocked</code> because we delete mapping on <code>locker[tokenId]</code> freeing up space. Also, this assertion helps our contract to validate if token is <code>locked</code> or <code>unlocked</code> for internal function calls.</p> <p>This proposal exposes <code>transferAndLock(uint256 tokenId, address from, address to, bool setApprove)</code> which can be used to transfer token and lock at the receiver's address. This additionally accepts input <code>bool setApprove</code> which on <code>true</code> assign <code>approval</code> to <code>locker</code>, hence enabling <code>locker</code> to revoke the token (revocation conditions can be defined in contracts and <code>approval</code> provided to contract). This provides conditional ownership to receiver, without the privilege to <code>transfer</code> token.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standards.</p> <p>Existing Upgradedable <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> can upgrade to this standard, enabling locking capability inherently and unlock underlying liquidity features.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases can be found <a href="https://wg-eips.ritovision.com/7066/./assets/test/test.js">here</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Reference Interface can be found <a href="https://wg-eips.ritovision.com/7066/./assets/IERC7066.sol">here</a>.</p> <p>Reference Implementation can be found <a href="https://wg-eips.ritovision.com/7066/./assets/ERC7066.sol">here</a>.</p> <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/">ERC-721</a>.</p> <h3 id="considerations-for-the-contracts-that-work-with-lockable-tokens">Considerations for the contracts that work with lockable tokens</h3> <ul> <li>Once <code>locked</code>, token can not be further <code>approved</code> or <code>transfered</code>.</li> <li>If token is <code>locked</code> and caller is <code>locker</code> and <code>approved</code> both, caller can transfer the token.</li> <li><code>locked</code> token with <code>locker</code> as in-accesible account or un-verified contract address can lead to permanent lock of the token.</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> 2023-05-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Piyush Chittarahttps://github.com/piyush-chittara https://wg-eips.ritovision.com/7721/

Interface for enabling locking of ERC-1155 using locker and token id based approvals

<h2 id="abstract">Abstract</h2> <p>The Lockable Extension for <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> introduces a robust locking mechanism for specific Non-Fungible Tokens (NFTs) within the ERC-1155 token standard, allowing for various uses while preventing sale or transfer. The token's <code>owner</code> can <code>lock</code> it, setting up locker address (either an EOA or a contract) that exclusively holds the power to unlock the token. Owner can also provide approval for <code>tokenId</code>, enabling ability to lock asset while address holds the token approval. Token can also be locked by <code>approved</code>, assigning locker to itself. Upon token transfer, these rights get purged.</p> <p>Inspired by the need for enhanced security and control over tokenized assets, this extension enables token owners to lock individual NFTs with <code>tokenId</code>, ensuring that only approved users can withdraw predetermined amounts of locked tokens. Thus, offering a safer approach by allowing token owners to specify approved token IDs and amounts for withdrawal.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> has sparked an unprecedented surge in demand for NFTs. However, despite this tremendous success, the NFT economy suffers from secondary liquidity where it remains illiquid in owner’s wallet. There are projects which aim to address the liquidity challenge, but they entail the below mentioned inconveniences and risks for owners as they necessitate transferring the participating NFTs to the projects' contracts.</p> <ul> <li>Loss of utility: The utility value of NFTs diminishes when they are transferred to an escrow account, no longer remaining under the direct custody of the owners.</li> <li>Lack of composability: The market could benefit from increased liquidity if NFT owners had access to multiple financial tools, such as leveraging loans and renting out their assets for maximum returns. Composability serves as the missing piece in creating a more efficient market.</li> <li>Smart contract vulnerabilities: NFTs are susceptible to loss or theft due to potential bugs or vulnerabilities present in the smart contracts they rely on.</li> </ul> <p>The aforementioned issues contribute to a poor user experience (UX), and we propose enhancing the <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> standard by implementing a native locking mechanism: Rather than being transferred to a smart contract, an NFT remains securely stored in self-custody but is locked. During the lock period, the NFT's transfer is restricted while its other properties remain unchanged. NFT Owner retains the ability to use or distribute it’s utility.</p> <p>NFTs have numerous use cases where the NFT must remain within the owner's wallet, even when it serves as collateral for a loan. Whether it's authorizing access to a Discord server, or utilizing NFT within a play-to-earn (P2E) game, owner should have the freedom to do so throughout the lending period. Just as real estate owner can continue living in their mortgaged house, take personal loan or keep tenants to generate passive income, these functionalities should be available to NFT owners to bring more investors in NFT economy.</p> <p>Lockable NFTs enable the following use cases :</p> <ul> <li>NFT-collateralized loans: Utilize NFT as collateral for a loan without locking it on the lending protocol contract. Instead, lock it within owner’s wallet while still enjoying all the utility of NFT.</li> <li>No collateral rentals of NFTs: Borrow an NFT for a fee without the need for significant collateral. Renter can use the NFT but not transfer it, ensuring the lender's safety. The borrowing service contract automatically returns the NFT to the lender once the borrowing period expires.</li> <li>Buy Now Pay Later (BNPL): The buyer receives the locked NFT and can immediately begin using it. However, they are unable to sell the NFT until all installments are paid. Failure to complete the full payment results in the NFT returning to the seller, along with a fee.</li> <li>Composability: Maximize liquidity by having access to multiple financial tools. Imagine taking a loan against NFT and putting it on rentals to generate passive income.</li> <li>Primary sales: Mint an NFT for a partial payment and settle the remaining amount once owner is satisfied with the collection's progress.</li> <li>Soulbound: Organization can mint and self-assign <code>locker</code>, send token to user and lock the asset.</li> <li>Safety: Safely and conveniently use exclusive blue chip NFTs. Lockable extension allows owner to lock NFT and designate secure cold wallet as the unlocker. This way, owner can keep NFT on MetaMask and easily use it, even if a hacker gains access to MetaMask account. Without access to the cold wallet, the hacker cannot transfer NFT, ensuring its safety.</li> </ul> <p>This proposal is different from other locking proposals in number of ways:</p> <ul> <li>This implementation provides a minimal implementation of <code>lock</code> and <code>unlock</code> and believes other conditions like time-bound are great ideas but can be achieved without creating a specific implementation. Locking and Unlocking can be based on any conditions (e.g. repayment, expiry). Therefore time-bound unlocks a relatively specific use case that can be achieved via smart-contracts themselves without that being a part of the token contract.</li> <li>This implementation proposes a separation of rights between locker and approver. Token can be locked with approval and approved can unlock and withdraw tokens (opening up opportunities like renting, lending, BNPL etc), and token can be locked lacking the rights to revoke token, yet can unlock if required (opening up opportunities like account-bound NFTs).</li> <li>Our proposal implement ability to <code>transferAndLock</code> which can be used to transfer, lock and optionally approve token. Enabling the possibility of revocation after transfer.</li> </ul> <p>By extending the <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> standard, the proposed standard enables secure and convenient management of underlying NFT assets. It natively supports prevalent NFTFi use cases such as staking, lending, and renting. We anticipate that this proposed standard will foster increased engagement of NFT owners in NFTFi projects, thereby enhancing the overall vitality of the NFT ecosystem.</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="overview">Overview</h3> <p><a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> compliant contracts MAY implement this EIP to provide standard methods of locking and unlocking the token at its current owner address.</p> <p>Token owner MAY <code>lock</code> the token and assign <code>locker</code> to some <code>address</code> using <code>lock(uint256 tokenId, address account, address _locker, uint256 amount)</code> function, this MUST set <code>locker</code> to <code>_locker</code>. Token owner or approved MAY <code>lock</code> the token using <code>lock(uint256 tokenId, address account, uint256 amount</code> function, this MUST set <code>locker</code> to <code>msg.sender</code>. Token MAY be <code>unlocked</code> by <code>locker</code> using <code>unlock(uint256 tokenId, address account, uint256 amount)</code> function.</p> <p>Token owner MAY <code>approve</code> specific for specific <code>tokenId</code> using <code>setApprovalForId(uint256 tokenId, address operator, uint256 amount)</code> ensuring only approved tokenId could be spent by operator. <code>getApprovalForId(uint256 tokenId, address account, address operator)</code> SHALL return <code>amount</code> approved on <code>account</code> by <code>operator</code>.</p> <p>If the token is <code>locked</code>, the <code>getLocked(uint256 tokenId, address account, address operator)</code> function MUST return an amount that is <code>locked</code> by <code>operator</code> on <code>account</code>. For tokens that are not <code>locked</code>, the <code>getLocked(uint256 tokenId, address account, address operator)</code> function MUST return <code>0</code>.</p> <p><code>lock</code> function MUST revert if <code>account</code> has insufficient balance or not <code>owner</code> or <code>approved</code> of <code>tokenId</code>. <code>unlock</code> function MUST revert if provided <code>amount</code> of <code>tokenId</code> is not <code>locked</code>. ERC-1155 <code>safeTransferFrom</code> of a token MUST revert if <code>account</code> transfer <code>locked</code> amount, maximum transferable amount MUST be <code>balance - getLocked</code>.</p> <p>Token MAY be transferred and <code>locked</code>, also assign <code>approval</code> to <code>locker</code> using <code>transferAndLock</code> function. This is RECOMMENDED for use-cases where Token transfer and subsequent revocation is REQUIRED.</p> <h3 id="interface">Interface</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>pragma solidity &gt;=0.7.0 &lt;0.9.0;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/// @title Lockable Extension for ERC1155</span></span> <span class="giallo-l"><span>/// @dev Interface for the Lockable extension</span></span> <span class="giallo-l"><span>/// @author piyush-chittara </span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>interface IERCLockable1155 is IERC1155{</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Emitted when tokenId is locked</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event Lock(uint256 indexed tokenId, address account, address _locker, uint256 amount);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Emitted when tokenId is unlocked</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event Unlock (uint256 indexed tokenId, address account, address _locker, uint256 amount);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Lock the tokenId if msg.sender is owner or approved and set locker to msg.sender</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function lock(uint256 tokenId, address account, uint256 amount) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Lock the tokenId if msg.sender is owner and set locker to _locker</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function lock(uint256 tokenId, address account, address _locker, uint256 amount) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Unlocks the tokenId if msg.sender is locker</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function unlock(uint256 tokenId, address account, uint256 amount) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Tranfer and lock the token if the msg.sender is owner or approved. </span></span> <span class="giallo-l"><span> * Lock the token and set locker to caller</span></span> <span class="giallo-l"><span> * Optionally approve caller if bool setApprove flag is true</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function transferAndLock(address from, address to, uint256 tokenId, uint256 amount, bool setApprove) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Returns the wallet, that is stated as unlocking wallet for the tokenId.</span></span> <span class="giallo-l"><span> * If (0) returned, that means token is not locked. Any other result means token is locked.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getLocked(uint256 tokenId, address account, address operator) external view returns (uint256);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function setApprovalForId(uint256 tokenId, address operator, uint256 amount) external;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This proposal exposes <code>transferAndLock(address from, address to, uint256 tokenId, uint256 amount, bool setApprove)</code> which can be used to transfer token and lock at the receiver's address. This additionally accepts input <code>bool setApprove</code> which on <code>true</code> assign <code>approval</code> to <code>locker</code>, hence enabling <code>locker</code> to revoke the token (revocation conditions can be defined in contracts and <code>approval</code> provided to contract). This provides conditional ownership to receiver, without the privilege to <code>transfer</code> token.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> standards.</p> <p>Existing Upgradeable <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> can upgrade to this standard, enabling locking capability inherently and unlock underlying liquidity features.</p> <h2 id="test-cases">Test Cases</h2> <h2 id="reference-implementation">Reference Implementation</h2> <p>Reference Interface can be found <a href="https://wg-eips.ritovision.com/7721/./assets/IERC7721.sol">here</a>.</p> <p>Reference Implementation can be found <a href="https://wg-eips.ritovision.com/7721/./assets/ERC7721.sol">here</a>.</p> <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/1155/">ERC-1155</a>.</p> <h3 id="considerations-for-the-contracts-that-work-with-lockable-tokens">Considerations for the contracts that work with lockable tokens</h3> <ul> <li>Once a certain <code>amount</code> is <code>locked</code>, specified <code>amount</code> can not be transferred from locked <code>account</code>.</li> <li>If token is <code>locked</code> and caller is <code>locker</code> and <code>approved</code> both, caller can transfer the token.</li> <li><code>locked</code> token with <code>locker</code> as in-accesible account or un-verified contract address can lead to permanent lock of the token.</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> 2023-05-22T00:00:00+00:00 2026-02-11T14:48:25+00:00 Bofu Chenhttps://github.com/bafu Tammy Yanghttps://github.com/tammyyang https://wg-eips.ritovision.com/7053/

A universal indexing method to record, discover and retrieve the history of digital media on EVM-compatible blockchains.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes an interoperable indexing strategy designed to enhance the organization and retrieval of digital media information across multiple smart contracts and EVM-compatible blockchains. This system enhances the traceability and verification of cross-contract and cross-chain data, facilitating a more efficient discovery of storage locations and crucial information related to media assets. The major purpose is to foster an integrated digital media environment on the blockchain.</p> <h2 id="motivation">Motivation</h2> <p>Given the significant role digital media files play on the Internet, it's crucial to have a robust and efficient method for indexing immutable information. Existing systems encounter challenges due to the absence of a universal, interoperable identifier for digital media content. This leads to fragmentation and complications in retrieving metadata, storage information, or the provenance of specific media assets. The issues become increasingly critical as the volume of digital media continues to expand.</p> <p>The motivation behind this EIP is to establish a standardized, decentralized, and interoperable approach to index digital media across EVM-compatible networks. By integrating Decentralized Content Identifiers (CIDs) and Commit events, this EIP puts forward a mechanism enabling unique identification and indexing of each digital media file. Moreover, this system suggests a way for users to access a complete history of data associated with digital media assets, from creation to the current status. This full view enhances transparency, thereby providing users with the necessary information for future interactions with digital media.</p> <p>This method creates a common interface that any digital media system can use to provide a standard way of indexing and searching their content.</p> <table><thead><tr><th style="text-align: center"></th></tr></thead><tbody> <tr><td style="text-align: center"><img src="https://wg-eips.ritovision.com/7053/./assets/digital-media-indexing-system-and-metadata-lookup.jpg" alt="" /></td></tr> <tr><td style="text-align: center">Figure 1: Digital Media Indexing Relationships and Lookup</td></tr> </tbody></table> <p>This EIP aims to create an interoperable indexing system to associate all data of the same digital content together (Figure 1). This will make it easier for users to find and trust digital media content, and it will also make it easier for systems to share and exchange information about this digital media content.</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="content-identifier">Content Identifier</h3> <p>Content Identifier in this EIP is the content address generated by passing the content of a digital media through a cryptographic hash function. Before the indexing process for digital media can begin, it is REQUIRED to generate unique Content Identifiers for each file. This identifier should the same as the Content Identifiers on the decentralized storage, ensuring each identifier provides access to the metadata, media information, and the content file itself.</p> <h3 id="commit-function">Commit Function</h3> <p>To index digital media, we shall call the commit function and generate Commit event:</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"> Emitted when a new commit is made.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> recorder</span><span class="z-comment"> The address of the account making the commit.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assetCid</span><span class="z-comment"> The content identifier of the asset being committed.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> commitData</span><span class="z-comment"> The data associated with the commit.</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"> Commit</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> recorder</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> assetCid</span><span>, </span><span class="z-support">string</span><span class="z-variable"> commitData</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"> Registers a commit for an asset.</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a Commit event and records the block number of the commit in the recordLogs mapping for the provided assetCid.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a Commit event and logs the block number of the commit 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"> assetCid</span><span class="z-comment"> The content identifier of the asset being committed.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> commitData</span><span class="z-comment"> The data associated with the commit.</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"> block number at which the commit was made.</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"> commit</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> assetCid</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> commitData</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"> blockNumber</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The design decisions in this EIP prioritize the effectiveness and efficiency of the indexing method. To achieve this, Decentralized Content Identifiers (CIDs) are utilized to uniquely identify digital media content across all systems. This approach offers accurate and precise searching of media, along with the following benefits:</p> <ol> <li> <p>Strengthened data integrity: CIDs serve as cryptographic hashes of the content, ensuring their uniqueness and preventing forgery. With the content in hand, obtaining the CID allows for searching relevant information associated with that content.</p> </li> <li> <p>Streamlined data portability: CIDs enable the seamless transfer of digital media content across different systems, eliminating the need for re-encoding or reconfiguration of protocols. This promotes a more interoperable and open indexing system. For example, in cases where Non-Fungible Tokens (NFTs) are created prior to Commit events, the digital media content can still be indexed by converting the file referenced by the tokenURI using the same mechanism. This conversion process ensures that the digital media content associated with NFT tokens can be indexed with a consistent identification approach.</p> </li> </ol> <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"> ^0.8.4</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/utils/cryptography/ECDSA.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.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"> CommitRegister</span><span class="z-storage"> is</span><span class="z-entity z-name"> Initializable</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> ECDSA</span><span class="z-keyword"> for</span><span class="z-entity z-name"> bytes32</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">string</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint</span><span>[</span><span>]</span><span>)</span><span class="z-storage z-type"> public</span><span> commitLogs</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"> Commit</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> recorder</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> assetCid</span><span>, </span><span class="z-support">string</span><span class="z-variable"> commitData</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"> initialize</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> initializer</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"> commit</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> assetCid</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> commitData</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"> blockNumber</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Commit</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> assetCid</span><span>,</span><span> commitData</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> commitLogs</span><span>[</span><span>assetCid</span><span>]</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-variable z-language">block</span><span>.</span><span>number</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> block</span><span>.</span><span>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"> function</span><span class="z-entity z-name"> getCommits</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> assetCid</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 class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> commitLogs</span><span>[</span><span>assetCid</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>When implementing this EIP, it's essential to address several security aspects to ensure the safety and integrity of the digital media index:</p> <ol> <li> <p>Input Validation: Given that commit function accepts string parameters, it's important to validate these inputs to avoid potential injection attacks. Although such attacks are less common in smart contracts than traditional web development, caution should be exercised.</p> </li> <li> <p>Data Integrity: The commit function relies on CIDs, which are assumed to be correct and point to the right data. It's important to note that this EIP doesn't validate the content behind the CIDs and the commit data, which remains a responsibility of the users or implementing applications.</p> </li> <li> <p>Event Listening: Systems relying on listening to the Commit events for changes need to be aware of potential missed events or incorrect ordering, especially during periods of network congestion or reorganizations.</p> </li> </ol> <p>Implementers should consider these security aspects in the context of their specific use case and deployment scenario. It is strongly recommended to perform a comprehensive security audit before deploying any implementation of this EIP to a live 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> 2023-05-18T00:00:00+00:00 2026-02-11T14:49:27+00:00 Lionhttps://github.com/dapplion https://wg-eips.ritovision.com/7044/

Lock voluntary exit signature domain on capella for perpetual validity

<h2 id="abstract">Abstract</h2> <p>Lock validator voluntary exit signature domain on Capella for perpetual validity. Currently, signed voluntary exits are only valid for two upgrades.</p> <h2 id="motivation">Motivation</h2> <p>Currently, signed voluntary exits are valid up-to only two upgrades for block inclusion due to the Beacon Chain state considering only the current and previous fork version. This limitation increases the complexity of some staking operations, specifically those in which the staking operator (holder of active key) is distinct from the owner of the funds (holder of the withdrawal credential). Because voluntary exits can only be signed by the active key, such a relationship requires the exchange of signed exits ahead of time for an unbounded number of forks.</p> <p>The limited validity of voluntary exits was originally motivated to isolate them in the event of a hard fork that results in two maintained chains. If fork A and B exist and a validator operates on both, if they send an exit, it will be replayable on both. However, this possibility is not sufficient to justify the UX degradation exposed above, as no funds are at risk and the staker can re-stake on one or both of the chains.</p> <h2 id="specification">Specification</h2> <h3 id="consensus-layer">Consensus Layer</h3> <p>Specification changes are built into the Consensus Specs Deneb upgrade.</p> <p>The specific makes one change to the state transition function:</p> <ul> <li>Modify <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/75971a8c218b1d76d605dd8b88a08d39c42de221/specs/deneb/beacon-chain.md#modified-process_voluntary_exit"><code>process_voluntary_exit</code></a> to compute the signing domain and root fixed on <code>CAPELLA_FORK_VERSION</code>.</li> </ul> <p>Additionally, the <code>voluntary_exit</code> gossip conditions are implicitly modified to support this change.</p> <p>To make the change backwards compatible the signature domain is locked on the Capella fork</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>Perpetually valid signed voluntary exits allow simpler staking operation designs. It also aligns the UX of such objects to <code>BLSToExecutionChanges</code> and deposits, such that downstream tooling does not need to be updated with fork version information.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is backwards compatible to the Consensus Layer of Ethereum block processing logic.</p> <p>The expectation of future validity of exits is not forward compatible. Specifically, users who have already pre-signed exits utilizing the Deneb fork domain with an expectation of their validity should be aware that these pre-signed exits will no longer be recognized as valid. Consequently, users should adjust their approach moving forward. For continued validity across forks, including Deneb and subsequent forks, users should ensure that their exits are signed using the Capella fork domain.</p> <p>There are no forwards/backwards compatibility issues with the Execution Layer.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases for this EIP can be found in the <a rel="external" href="https://github.com/ethereum/consensus-specs/tree/2297c09b7e457a13f7b2261a28cb45777be82f83/tests/core/pyspec/eth2spec/test/deneb"><code>deneb</code></a> test suite of the <code>consensus-specs</code> repository.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The divergent signature domains across forked networks would previously have prevented the replay of VoluntaryExits after two hard forks. This specification change causes the replay protection to no longer exist. These potential replays could impact individual stakers on both sides of a fork, but does not put funds at risk and does not impact the security of the chain.</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-18T00:00:00+00:00 2026-02-11T14:49:27+00:00 Danny Ryanhttps://github.com/djrtwo https://wg-eips.ritovision.com/7045/

Increases max attestation inclusion slot to the last slot in `N+1` where `N` is the epoch containing the attestation's slot.

<h2 id="abstract">Abstract</h2> <p>Increases max attestation inclusion slot from <code>attestation.slot + SLOTS_PER_EPOCH</code> to the last slot of epoch <code>N+1</code> where <code>N</code> is the epoch containing the attestation slot.</p> <p>This increase is critical to the current LMD-GHOST security analysis as well as the confirmation rule.</p> <h2 id="motivation">Motivation</h2> <p>Attestations can currently be included after some minimum delay (<code>1</code> slot on mainnet) up until <code>SLOTS_PER_EPOCH</code> slots after the slot the attestation was created in. This rolling window of one epoch was decided upon during Phase 0 because the equal inclusion window for any attestation was assessed as "fair". The alternative considered path was to allow inclusion during the current and next epoch which means attestations created during the start of an epoch have more potential slots of inclusion than those at the end of the epoch.</p> <p>Since this decision, it has become apparent that the alternative design is critical for current LMD-GHOST security proofs as well as a new confirmation rule (which will allow for block confirmations in approximately 3-4 slots in normal mainnet conditions).</p> <p>This specification thus increases the max inclusion slot for attestations in accordance with the learned security proof and confirmation rule needs.</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>FORK_TIMESTAMP</code></td><td><code>1710338135</code></td><td>Mainnet</td></tr> </tbody></table> <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>Specification changes are built into the Consensus Specs Deneb upgrade.</p> <p>The specification makes two minor changes to the state transition function:</p> <ul> <li>Modify <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/95f36d99cf4aa59974da06af24ef9a7c12d3c301/specs/deneb/beacon-chain.md#modified-process_attestation"><code>process_attestation</code></a> to not have an upper bound on the slot check and instead define the inclusion range via the minimum slot as well as the target epoch being in either current or previous epoch.</li> <li>Modify <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/95f36d99cf4aa59974da06af24ef9a7c12d3c301/specs/deneb/beacon-chain.md#modified-get_attestation_participation_flag_indices"><code>get_attestation_participation_flag_indices</code></a> to set the <code>TIMELY_TARGET_FLAG</code> without consideration of <code>inclusion_delay</code> to ensure that the extended inclusion attestations have a non-zero reward.</li> </ul> <p>Additionally, the specification modifies the <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/95f36d99cf4aa59974da06af24ef9a7c12d3c301/specs/deneb/p2p-interface.md#beacon_attestation_subnet_id">attestation</a> and <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/95f36d99cf4aa59974da06af24ef9a7c12d3c301/specs/deneb/p2p-interface.md#beacon_aggregate_and_proof">aggregate attestation</a> gossip conditions to allow for gossip during this extended range.</p> <h2 id="rationale">Rationale</h2> <h3 id="extended-max-inclusion-slot">Extended max inclusion slot</h3> <p>As discussed in the Motivation, extending this max inclusion slot to the end of the next epoch is critical for LMD-GHOST security proofs and confirmation rule.</p> <h3 id="removal-of-inclusion-delay-consideration-for-target-reward">Removal of <code>inclusion_delay</code> consideration for target reward</h3> <p>Previously, <code>get_attestation_participation_flag_indices</code> would only set the <code>TIMELY_TARGET_FLAG</code> (and thus reward for an attestation with correct target vote) if the attestation was included within a <code>SLOTS_PER_EPOCH</code> window.</p> <p>The <code>inclusion_delay</code> consideration for this flag is removed to ensure that whatever the valid inclusion window is for an attestation, it can receive a baseline non-zero reward for correct target. This ensures that clients will still attempt to pack such attestations into blocks which is important for the security analysis.</p> <p>Note, this was the intended behavior with the previously defined range which was equivalent to the max.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces backwards incompatible changes to the block validation rule set on the consensus layer and must be accompanied by a hard fork.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases for this EIP can be found in the <a rel="external" href="https://github.com/ethereum/consensus-specs/tree/2297c09b7e457a13f7b2261a28cb45777be82f83/tests/core/pyspec/eth2spec/test/deneb"><code>deneb</code></a> test suite of the <code>consensus-specs</code> repository.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This improves LMD-GHOST security as well as enables a fast confirmation rule.</p> <p>There are no known negative impacts to security.</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-11T00:00:00+00:00 2026-02-11T14:48:25+00:00 indreamshttps://github.com/strollinghome https://wg-eips.ritovision.com/7015/

Extending NFTs with cryptographically secured creator attribution.

<h2 id="abstract">Abstract</h2> <p>This Ethereum Improvement Proposal aims to solve the issue of creator attribution for Non-Fungible Token (NFT) standards (<a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>). To achieve this, this EIP proposes a mechanism where the NFT creator signs the required parameters for the NFT creation, including the NFT metadata in a hash along with any other relevant information. The signed parameters and the signature are then validated and emitted during the deployment transaction, which allows the NFT to validate the creator and NFT platforms to attribute creatorship correctly. This method ensures that even if a different wallet sends the deployment transaction, the correct account is attributed as the creator.</p> <h2 id="motivation">Motivation</h2> <p>Current NFT platforms assume that the wallet deploying the smart contract is the creator of the NFT, leading to a misattribution in cases where a different wallet sends the deployment transaction. This happens often when working with smart wallet accounts, and new contract deployment strategies such as the first collector deploying the NFT contract. This proposal aims to solve the problem by allowing creators to sign the parameters required for NFT creation so that any wallet can send the deployment transaction with an signal in a verifiable way who is the creator.</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>ERC-721 and ERC-1155 compliant contracts MAY implement this NFT Creator Attribution extension to provide a standard event to be emitted that defines the NFT creator at the time of contract creation.</p> <p>This EIP takes advantage of the fact that contract addresses can be precomputed before a contract is deployed. Whether the NFT contract is deployed through another contract (a factory) or through an EOA, the creator can be correctly attributed using this specification.</p> <p><strong>Signing Mechanism</strong></p> <p>Creator consent is given by signing an <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> compatible message; all signatures compliant with this EIP MUST include all fields defined. The struct signed can be any arbitrary data that defines how to create the token; it must hashed in an EIP-712 compatible format with a proper EIP-712 domain.</p> <p>The following shows some examples of structs that could be encoded into <code>structHash</code> (defined below):</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> example struct that can be encoded in `structHash`; defines that a token can be created with a metadataUri and price:</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"> TokenCreation</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> metadataUri</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> price</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>}</span></span></code></pre> <p><strong>Signature Validation</strong></p> <p>Creator attribution is given through a signature verification that MUST be verified by the NFT contract being deployed and an event that MUST be emitted by the NFT contract during the deployment transaction. The event includes all the necessary fields for reconstructing the signed digest and validating the signature to ensure it matches the specified creator. The event name is <code>CreatorAttribution</code> and includes the following fields:</p> <ul> <li><code>structHash</code>: hashed information for deploying the NFT contract (e.g. name, symbol, admins etc). This corresponds to the value <code>hashStruct</code> as defined in the <a href="https://wg-eips.ritovision.com/712/#definition-of-hashstruct">EIP-712 definition of hashStruct</a> standard.</li> <li><code>domainName</code>: the domain name of the contract verifying the signature (for EIP-712 signature validation).</li> <li><code>version</code>: the version of the contract verifying the signature (for EIP-712 signature validation)</li> <li><code>creator</code>: the creator's account</li> <li><code>signature</code>: the creator’s signature</li> </ul> <p>The event is defined as follows:</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"> CreatorAttribution</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> structHash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> domainName</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"> address</span><span class="z-variable"> creator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> signature</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre> <p>Note that although the <code>chainId</code> parameters is necessary for <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> signatures, we omit the parameter from the event as it can be inferred through the transaction data. Similarly, the <code>verifyingContract</code> parameter for signature verification is omitted since it MUST be the same as the <code>emitter</code> field in the transaction. <code>emitter</code> MUST be the token.</p> <p>A platform can verify the validity of the creator attribution by reconstructing the signature digest with the parameters emitted and recovering the signer from the <code>signature</code> parameter. The recovered signer MUST match the <code>creator</code> emitted in the event. If <code>CreatorAttribution</code> event is present creator and the signature is validated correctly, attribution MUST be given to the <code>creator</code> instead of the account that submitted the transaction.</p> <h3 id="reference-implementation">Reference Implementation</h3> <h4 id="example-signature-validator">Example signature validator</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.8.20</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/cryptography/EIP712.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 class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/interfaces/IERC1271.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"> ERC7015</span><span class="z-storage"> is</span><span class="z-entity z-name"> EIP712</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> Invalid_Signature</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"> CreatorAttribution</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> structHash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> domainName</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"> address</span><span class="z-variable"> creator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> signature</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"> Define magic value to verify smart contract signatures (ERC1271).</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> constant</span><span> MAGIC_VALUE </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-string">&quot;isValidSignature(bytes32,bytes)&quot;</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"> _validateSignature</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> structHash</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"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> signature</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> internal</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">_isValid</span><span>(</span><span>structHash</span><span>,</span><span> creator</span><span>,</span><span> signature</span><span>)</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> Invalid_Signature</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> CreatorAttribution</span><span>(</span><span>structHash</span><span>,</span><span class="z-string"> &quot;ERC7015&quot;</span><span>,</span><span class="z-string"> &quot;1&quot;</span><span>,</span><span> creator</span><span>,</span><span> signature</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"> _isValid</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> structHash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> signer</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"> signature</span></span> <span class="giallo-l"><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-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 class="z-string"> &quot;cannot validate&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></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"> _hashTypedDataV4</span><span>(</span><span>structHash</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 smart contract is the signer, verify using ERC-1271 smart-contract</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> signature verification method</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>signer</span><span>.</span><span>code</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"> try</span><span class="z-entity z-name"> IERC1271</span><span>(</span><span>signer</span><span>)</span><span>.</span><span class="z-entity z-name">isValidSignature</span><span>(</span><span>digest</span><span>,</span><span> signature</span><span>)</span><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-variable"> magicValue</span></span> <span class="giallo-l"><span> )</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> MAGIC_VALUE </span><span class="z-keyword">==</span><span> magicValue</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 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 class="z-comment"> otherwise, recover signer and validate that it matches the expected</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> signer</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> recoveredSigner </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"> return</span><span> recoveredSigner </span><span class="z-keyword">==</span><span> signer</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>By standardizing the <code>CreatorAttribution</code> event, this EIP enables platforms to ascertain creator attribution without relying on implicit assumptions. Establishing a standard for creator attribution empowers platforms to manage the complex aspects of deploying contracts while preserving accurate onchain creator information. This approach ensures a more reliable and transparent method for identifying NFT creators, fostering trust among participants in the NFT ecosystem.</p> <p><a href="https://wg-eips.ritovision.com/5375/">ERC-5375</a> attempts to solve the same issue and although offchain data offers improved backward compatibility, ensuring accurate and immutable creator attribution is vital for NFTs. A standardized onchain method for creator attribution is inherently more reliable and secure.</p> <p>In contrast to this proposal, ERC-5375 does not facilitate specifying creators for all tokens within an NFT collection, which is a prevalent practice, particularly in emerging use cases.</p> <p>Both this proposal and ERC-5375 share similar limitations regarding address-based creator attribution:</p> <blockquote> <p>The standard defines a protocol to verify that a certain <em>address</em> provided consent. However, it does not guarantee that the address corresponds to the expected creator […]. Proving a link between an address and the entity behind it is beyond the scope of this document.</p> </blockquote> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Since the standard requires an event to be emitted during the NFTs deployment transaction, existing NFTs cannot implement this standard.</p> <h2 id="security-considerations">Security Considerations</h2> <p>A potential attack exploiting this proposal could involve deceiving creators into signing creator attribution consent messages unintentionally. Consequently, creators MUST ensure that all signature fields correspond to the necessary ones before signing.</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-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Cathie Sohttps://github.com/socathie Xiaohang Yuhttps://github.com/xhyumiracle Conwayhttps://github.com/0x1cc Lee Ting Tinghttps://github.com/tina1998612 Kartinkartin@hyperoracle.io https://wg-eips.ritovision.com/7007/

An ERC-721 extension for verifiable AI-generated content tokens using Zero-Knowledge and Optimistic Machine Learning techniques

<h2 id="abstract">Abstract</h2> <p>The verifiable AI-generated content (AIGC) non-fungible token (NFT) standard is an extension of the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> token standard for AIGC. It proposes a set of interfaces for basic interactions and enumerable interactions for AIGC-NFTs. The standard includes an <code>addAigcData</code> and <code>verify</code> function interface, a new <code>AigcData</code> event, optional <code>Enumerable</code> and <code>Updatable</code> extensions, and a JSON schema for AIGC-NFT metadata. Additionally, it incorporates Zero-Knowledge Machine Learning (zkML) and Optimistic Machine Learning (opML) capabilities to enable verification of AIGC data correctness. In this standard, the <code>tokenId</code> is indexed by the <code>prompt</code>.</p> <h2 id="motivation">Motivation</h2> <p>The verifiable AIGC-NFT standard aims to extend the existing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> token standard to accommodate the unique requirements of AI-generated content NFTs representing models in a collection. This standard provides interfaces to use zkML or opML to verify whether or not the AIGC data for an NFT is generated from a certain ML model with a certain input (prompt). The proposed interfaces allow for additional functionality related to adding AIGC data, verifying, and enumerating AIGC-NFTs. Additionally, the metadata schema provides a structured format for storing information related to AIGC-NFTs, such as the prompt used to generate the content and the proof of ownership.</p> <p>This standard supports two primary types of proofs: validity proofs and fraud proofs. In practice, zkML and opML are commonly employed as the prevailing instances for these types of proofs. Developers can choose their preferred ones.</p> <p>In the zkML scenario, this standard enables model owners to publish their trained model and its ZKP verifier to Ethereum. Any user can claim an input (prompt) and publish the inference task. Any node that maintains the model and the proving circuit can perform the inference and proving, and submit the output of inference and the ZK proof for the inference trace to the verifier. The user that initiates the inference task will own the output for the inference of that model and input (prompt).</p> <p>In the opML scenario, this standard enables model owners to publish their trained model to Ethereum. Any user can claim an input (prompt) and publish the inference task. Any node that maintains the model can perform the inference and submit the inference output. Other nodes can challenge this result within a predefined challenge period. At the end of the challenge period, the user can verify that they own the output for the inference of that model and prompt, and update the AIGC data as needed.</p> <p>This capability is especially beneficial for AI model authors and AI content creators seeking to capitalize on their creations. With this standard, every input prompt and its resulting content can be securely verified on the blockchain. This opens up opportunities for implementing revenue-sharing mechanisms for all AI-generated content (AIGC) NFT sales. AI model authors can now share their models without concerns that open-sourcing will diminish their financial value.</p> <p>An example workflow of a zkML AIGC NFT project compliant with this proposal is as follows:</p> <p><img src="https://wg-eips.ritovision.com/7007/./assets/workflow.png" alt="zkML Suggested Workflow" /></p> <p>There are 4 components in this workflow:</p> <ul> <li>ML model - contains weights of a pre-trained model; given an inference input, generates the output</li> <li>zkML prover - given an inference task with input and output, generates a ZK proof</li> <li>AIGC-NFT smart contract - contract compliant with this proposal, with full <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> functionalities</li> <li>Verifier smart contract - implements a <code>verify</code> function, given an inference task and its ZK proof, returns the verification result as a boolean</li> </ul> <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> <p><strong>Every compliant contract must implement the <code>IERC7007</code>, <a href="https://wg-eips.ritovision.com/721/"><code>ERC721</code></a>, and <a href="https://wg-eips.ritovision.com/165/"><code>ERC165</code></a> interfaces.</strong></p> <p>The verifiable AIGC-NFT standard includes the following interfaces:</p> <p><code>IERC7007</code>: Defines an <code>addAigcData</code> function and an <code>AigcData</code> event for adding AIGC data to AIGC-NFTs. Defines a <code>verify</code> function to check the validity of the combination of prompt and aigcData using zkML/opML techniques.</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.18</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 ERC7007 compliant contract.</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 0x702c55a6.</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"> IERC7007</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span>, </span><span class="z-entity z-name">IERC721</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&#39;s AIGC data is added.</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"> AigcData</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"> bytes</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> prompt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> aigcData</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> proof</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"> Add AIGC data to token at `tokenId` given `prompt`, `aigcData`, and `proof`.</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"> addAigcData</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"> prompt</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"> aigcData</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"> proof</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">@dev</span><span class="z-comment"> Verify the `prompt`, `aigcData`, and `proof`.</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"> verify</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"> prompt</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"> aigcData</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"> proof</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 class="z-variable"> success</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="optional-extension-enumerable">Optional Extension: Enumerable</h3> <p>The <strong>enumeration extension</strong> is OPTIONAL for <a href="https://wg-eips.ritovision.com/7007/">ERC-7007</a> smart contracts. This allows your contract to publish its full list of mapping between <code>tokenId</code> and <code>prompt</code> and make them discoverable.</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.18</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"> ERC7007 Token Standard, optional enumeration extension</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 0xfa1a557a.</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"> IERC7007Enumerable</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7007</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"> Returns the token ID given `prompt`.</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"> tokenId</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> prompt</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">@dev</span><span class="z-comment"> Returns the prompt given `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"> prompt</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"> calldata</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="optional-extension-updatable">Optional Extension: Updatable</h3> <p>The <strong>updatable extension</strong> is OPTIONAL for <a href="https://wg-eips.ritovision.com/7007/">ERC-7007</a> smart contracts. This allows your contract to update a token's <code>aigcData</code> in the case of opML, where <code>aigcData</code> content might change over the challenge period.</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.18</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"> ERC7007 Token Standard, optional updatable extension</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 0x3f37dce2.</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"> IERC7007Updatable</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7007</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"> Update the `aigcData` of `prompt`.</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"> update</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"> prompt</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"> aigcData</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">@dev</span><span class="z-comment"> Emitted when `tokenId` token is updated.</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"> Update</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"> bytes</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> prompt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> aigcData</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="erc-7007-metadata-json-schema-for-reference">ERC-7007 Metadata JSON Schema for reference</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">AIGC 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">prompt</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 prompt from which this AIGC NFT generated</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">aigc_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></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">image/video/audio...</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">aigc_data</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 AIGC 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">proof_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></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">validity (zkML) or fraud (opML)</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="ml-model-publication">ML Model Publication</h3> <p>While this standard does not describe the Machine Learning model publication stage, it is natural and recommended to publish the commitment of the Model to Ethereum separately, before any actual <code>addAigcData</code> actions. The model commitment schema choice lies on the AIGC-NFT project issuer party. The commitment should be checked inside the implementation of the <code>verify</code> function.</p> <h2 id="rationale">Rationale</h2> <h3 id="unique-token-identification">Unique Token Identification</h3> <p>This specification sets the <code>tokenId</code> to be the hash of its corresponding <code>prompt</code>, creating a deterministic and collision-resistant way to associate tokens with their unique content generation parameters. This design decision ensures that the same prompt (which corresponds to the same AI-generated content under the same model seed) cannot be minted more than once, thereby preventing duplication and preserving the uniqueness of each NFT within the ecosystem.</p> <h3 id="generalization-to-different-proof-types">Generalization to Different Proof Types</h3> <p>This specification accommodates two proof types: validity proofs for zkML and fraud proofs for opML. Function arguments in <code>addAigcData</code> and <code>verify</code> are designed for generality, allowing for compatibility with both proof systems. Moreover, the specification includes an updatable extension that specifically serves the requirements of opML.</p> <h3 id="verify-interface"><code>verify</code> interface</h3> <p>We specify a <code>verify</code> interface to enforce the correctness of <code>aigcData</code>. It is defined as a view function to reduce gas cost. <code>verify</code> should return true if and only if <code>aigcData</code> is finalized in both zkML and opML. In zkML, it must verify the ZK proof, i.e. <code>proof</code>; in opML, it must make sure that the challenging period is finalized, and that the <code>aigcData</code> is up-to-date, i.e. has been updated after finalization. Additionally, <code>proof</code> can be <em>empty</em> in opML.</p> <h3 id="addaigcdata-interface"><code>addAigcData</code> interface</h3> <p>We specify an <code>addAigcData</code> interface to bind the prompt and <code>aigcData</code> with <code>tokenId</code>. This function provides flexibility for different minting implementations. Notably, it acts differently in zkML and opML cases. In zkML, <code>addAigcData</code> should make sure <code>verify</code> returns <code>true</code>. While in opML, it can be called before finalization. The consideration here is that, limited by the proving difficulty, zkML usually targets simple model inference tasks in practice, making it possible to provide a proof within an acceptable time frame. On the other hand, opML enables large model inference tasks, with a cost of longer confirmation time to achieve the approximate same security level. Mint until opML finalization may not be the best practice considering the existing optimistic protocols.</p> <h3 id="naming-choice-on-update">Naming Choice on <code>update</code></h3> <p>We adopt "update" over "finalize" because a successful challenge happens rarely in practice. Using <code>update</code> could avoid calling it for every <code>tokenId</code> and save gas.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is backward compatible with the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> as it extends the existing functionality with new interfaces.</p> <h2 id="test-cases">Test Cases</h2> <p>The reference implementation includes sample implementations of the <a href="https://wg-eips.ritovision.com/7007/">ERC-7007</a> interfaces under <code>contracts/</code> and corresponding unit tests under <code>test/</code>. This repo can be used to test the functionality of the proposed interfaces and metadata schema.</p> <h2 id="reference-implementation">Reference Implementation</h2> <ul> <li>ERC-7007 for <a href="https://wg-eips.ritovision.com/7007/./assets/contracts/ERC7007Zkml.sol">zkML</a> and <a href="https://wg-eips.ritovision.com/7007/./assets/contracts/ERC7007Opml.sol">opML</a></li> <li><a href="https://wg-eips.ritovision.com/7007/./assets/contracts/ERC7007Enumerable.sol">ERC-7007 Enumerable Extension</a></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <h3 id="frontrunning-risk">Frontrunning Risk</h3> <p>To address the risk of frontrunning, where an actor could potentially observe and preemptively claim a prompt during the minting process, implementers of this proposal must incorporate a secure prompt-claiming mechanism. Implementations could include time-locks, commit-reveal schemes, or other anti-frontrunning techniques to ensure equitable and secured claim processes for AIGC-NFTs.</p> <h3 id="aigc-data-change-during-challenge-period">AIGC Data Change During Challenge Period</h3> <p>In the opML scenario, it is important to consider that the <code>aigcData</code> might change during the challenge period due to disputes or updates. The updatable extension defined here provides a way to handle these updates. Implementations must ensure that updates to <code>aigcData</code> are treated as critical state changes that require adherence to the same security and validation protocols as the initial minting process. Indexers should always check for any <code>Update</code> event emission.</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-09T00:00:00+00:00 2026-02-11T14:49:27+00:00 Danny Ryanhttps://github.com/djrtwo Mikhail Kalininhttps://github.com/mkalinin Ansgar Dietrichshttps://github.com/adietrichs Hsiao-Wei Wanghttps://github.com/hwwhww lightclienthttps://github.com/lightclient Felix Langehttps://github.com/fjl https://wg-eips.ritovision.com/7002/

Allow validators to trigger exits and partial withdrawals via their execution layer (0x01) withdrawal credentials

<h2 id="abstract">Abstract</h2> <p>Adds a new mechanism to allow validators to trigger withdrawals and exits from their execution layer (0x01) withdrawal credentials.</p> <p>These new execution layer exit messages are appended to the execution layer block and then processed by the consensus layer.</p> <h2 id="motivation">Motivation</h2> <p>Validators have two keys -- an active key and a withdrawal credential. The active key takes the form of a BLS key, whereas the withdrawal credential can either be a BLS key (0x00) or an execution layer address (0x01). The active key is "hot", actively signing and performing validator duties, whereas the withdrawal credential can remain "cold", only performing limited operations in relation to withdrawing and ownership of the staked ETH. Due to this security relationship, the withdrawal credential ultimately is the key that owns the staked ETH and any rewards.</p> <p>As currently specified, only the active key can initiate a validator exit. This means that in any non-standard custody relationship (i.e., the active key is a separate entity from the withdrawal credentials), the ultimate owner of the funds -- the possessor of the withdrawal credentials -- cannot independently choose to exit and begin the withdrawal process. This leads to either trust issues (e.g. ETH can be "held hostage" by the active key owner) or insufficient work-arounds such as pre-signed exits. Additionally, in the event that active keys are lost, a user should still be able to recover their funds by using their cold withdrawal credentials.</p> <p>To ensure that the withdrawal credentials (owned by both EOAs and smart contracts) can trustlessly control the destiny of the staked ETH, this specification enables exits triggerable by 0x01 withdrawal credentials.</p> <p>Note, 0x00 withdrawal credentials can be changed into 0x01 withdrawal credentials with a one-time signed message. Thus any functionality enabled for 0x01 credentials is defacto enabled for 0x00 credentials.</p> <h2 id="specification">Specification</h2> <h3 id="configuration">Configuration</h3> <table><thead><tr><th>Name</th><th>Value</th><th>Comment</th></tr></thead><tbody> <tr><td><code>WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</code></td><td><code>0x00000961Ef480Eb55e80D19ad83579A64c007002</code></td><td>Where to call and store relevant details about exit / partial withdrawal mechanism</td></tr> <tr><td><code>WITHDRAWAL_REQUEST_TYPE</code></td><td><code>0x01</code></td><td>The <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> type prefix for withdrawal request</td></tr> <tr><td><code>SYSTEM_ADDRESS</code></td><td><code>0xfffffffffffffffffffffffffffffffffffffffe</code></td><td>Address used to invoke system operation on contract</td></tr> <tr><td><code>EXCESS_WITHDRAWAL_REQUESTS_STORAGE_SLOT</code></td><td>0</td><td></td></tr> <tr><td><code>WITHDRAWAL_REQUEST_COUNT_STORAGE_SLOT</code></td><td>1</td><td></td></tr> <tr><td><code>WITHDRAWAL_REQUEST_QUEUE_HEAD_STORAGE_SLOT</code></td><td>2</td><td>Pointer to head of the withdrawal request message queue</td></tr> <tr><td><code>WITHDRAWAL_REQUEST_QUEUE_TAIL_STORAGE_SLOT</code></td><td>3</td><td>Pointer to the tail of the withdrawal request message queue</td></tr> <tr><td><code>WITHDRAWAL_REQUEST_QUEUE_STORAGE_OFFSET</code></td><td>4</td><td>The start memory slot of the in-state withdrawal request message queue</td></tr> <tr><td><code>MAX_WITHDRAWAL_REQUESTS_PER_BLOCK</code></td><td>16</td><td>Maximum number of withdrawal requests that can be dequeued into a block</td></tr> <tr><td><code>TARGET_WITHDRAWAL_REQUESTS_PER_BLOCK</code></td><td>2</td><td></td></tr> <tr><td><code>MIN_WITHDRAWAL_REQUEST_FEE</code></td><td>1</td><td></td></tr> <tr><td><code>WITHDRAWAL_REQUEST_FEE_UPDATE_FRACTION</code></td><td>17</td><td></td></tr> <tr><td><code>EXCESS_INHIBITOR</code></td><td><code>2**256-1</code></td><td>Excess value used to compute the fee before the first system call</td></tr> </tbody></table> <h3 id="execution-layer">Execution layer</h3> <h4 id="definitions">Definitions</h4> <ul> <li><strong><code>FORK_BLOCK</code></strong> -- the first block in a blockchain after this EIP has been activated.</li> </ul> <h4 id="withdrawal-request-operation">Withdrawal request operation</h4> <p>The new withdrawal request operation is an <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> request with type <code>0x01</code> and consists of the following fields:</p> <ol> <li><code>source_address</code>: <code>Bytes20</code></li> <li><code>validator_pubkey</code>: <code>Bytes48</code></li> <li><code>amount</code>: <code>uint64</code></li> </ol> <p>The <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> encoding of a withdrawal request is computed as follows. Note that <code>amount</code> is returned by the contract little-endian, and must be encoded as such.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>request_type</span><span class="z-keyword"> =</span><span class="z-constant"> WITHDRAWAL_REQUEST_TYPE</span></span> <span class="giallo-l"><span>request_data</span><span class="z-keyword"> =</span><span> read_withdrawal_requests</span><span>(</span><span>)</span></span></code></pre><h4 id="withdrawal-request-contract">Withdrawal Request Contract</h4> <p>The contract has three different code paths, which can be summarized at a high level as follows:</p> <ol> <li>Add withdrawal request - requires a <code>56</code> byte input, the validator's public key concatenated with a big-endian <code>uint64</code> amount value.</li> <li>Fee getter - if the input length is zero, return the current fee required to add a withdrawal request.</li> <li>System process - if called by system address, pop off the withdrawal requests for the current block from the queue.</li> </ol> <h5 id="add-withdrawal-request">Add Withdrawal Request</h5> <p>If call data input to the contract is exactly <code>56</code> bytes, perform the following:</p> <ul> <li>Ensure enough ETH was sent to cover the current withdrawal request fee (<code>check_fee()</code>)</li> <li>Increase withdrawal request count by 1 for the current block (<code>increment_count()</code>)</li> <li>Insert a withdrawal request into the queue for the source address and validator pubkey (<code>insert_withdrawal_request_into_queue()</code>)</li> </ul> <p>Specifically, the functionality is defined in pseudocode as the function <code>add_withdrawal_request()</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"> add_withdrawal_request</span><span>(</span><span class="z-variable z-parameter z-function">Bytes48</span><span>:</span><span> validator_pubkey</span><span>,</span><span class="z-variable z-parameter z-function"> uint64</span><span>:</span><span> amount</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"> Add withdrawal request adds new request to the withdrawal request queue, so long as a sufficient fee is provided.</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify sufficient fee was provided.</span></span> <span class="giallo-l"><span> fee</span><span class="z-keyword"> =</span><span> get_fee</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> require</span><span>(</span><span>msg</span><span>.</span><span>value</span><span class="z-keyword"> &gt;=</span><span> fee</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Insufficient value for fee</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-punctuation z-definition z-comment"> #</span><span class="z-comment"> Increment withdrawal request count.</span></span> <span class="giallo-l"><span> count</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> WITHDRAWAL_REQUEST_COUNT_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> WITHDRAWAL_REQUEST_COUNT_STORAGE_SLOT</span><span>,</span><span> count</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-punctuation z-definition z-comment"> #</span><span class="z-comment"> Insert into queue.</span></span> <span class="giallo-l"><span> queue_tail_index</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> WITHDRAWAL_REQUEST_QUEUE_TAIL_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> queue_storage_slot</span><span class="z-keyword"> =</span><span class="z-constant"> WITHDRAWAL_REQUEST_QUEUE_STORAGE_OFFSET</span><span class="z-keyword"> +</span><span> queue_tail_index</span><span class="z-keyword"> *</span><span class="z-constant"> 3</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span>,</span><span> msg</span><span>.</span><span>sender</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>,</span><span> validator_pubkey</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">32</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span>,</span><span> validator_pubkey</span><span>[</span><span class="z-constant">32</span><span>:</span><span class="z-constant">48</span><span>]</span><span class="z-invalid z-illegal"> ++</span><span> uint64_to_little_endian</span><span>(</span><span>amount</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> WITHDRAWAL_REQUEST_QUEUE_TAIL_STORAGE_SLOT</span><span>,</span><span> queue_tail_index</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span></span></code></pre><h6 id="fee-calculation">Fee calculation</h6> <p>The following pseudocode can compute the cost of an individual withdrawal request, given a certain number of excess withdrawal requests.</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_fee</span><span>(</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span></span> <span class="giallo-l"><span> excess</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> EXCESS_WITHDRAWAL_REQUESTS_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> require</span><span>(</span><span>excess</span><span class="z-keyword"> !=</span><span class="z-constant"> EXCESS_INHIBITOR</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Inhibitor still active</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> fake_exponential</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> MIN_WITHDRAWAL_REQUEST_FEE</span><span>,</span></span> <span class="giallo-l"><span> excess</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> WITHDRAWAL_REQUEST_FEE_UPDATE_FRACTION</span></span> <span class="giallo-l"><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"> fake_exponential</span><span>(</span><span class="z-variable z-parameter z-function">factor</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> numerator</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> denominator</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> i</span><span class="z-keyword"> =</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> output</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> numerator_accum</span><span class="z-keyword"> =</span><span> factor</span><span class="z-keyword"> *</span><span> denominator</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> numerator_accum</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> output</span><span class="z-keyword"> +=</span><span> numerator_accum</span></span> <span class="giallo-l"><span> numerator_accum</span><span class="z-keyword"> =</span><span> (</span><span>numerator_accum</span><span class="z-keyword"> *</span><span> numerator</span><span>)</span><span class="z-keyword"> //</span><span> (</span><span>denominator</span><span class="z-keyword"> *</span><span> i</span><span>)</span></span> <span class="giallo-l"><span> i</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> output</span><span class="z-keyword"> //</span><span> denominator</span></span></code></pre><h5 id="fee-getter">Fee Getter</h5> <p>When the input to the contract is length zero, interpret this as a get request for the current fee, i.e. the contract returns the result of <code>get_fee()</code>.</p> <h5 id="system-call">System Call</h5> <p>At the end of processing any execution block starting from the <code>FORK_BLOCK</code> (i.e. after processing all transactions and after performing the block body withdrawal requests validations), call <code>WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</code> as <code>SYSTEM_ADDRESS</code> with no calldata. The invocation triggers the following:</p> <ul> <li>The contract's queue is updated based on withdrawal requests dequeued and the withdrawal requests queue head/tail are reset if the queue has been cleared (<code>dequeue_withdrawal_requests()</code>)</li> <li>The contract's excess withdrawal requests are updated based on usage in the current block (<code>update_excess_withdrawal_requests()</code>)</li> <li>The contract's withdrawal requests count is reset to 0 (<code>reset_withdrawal_requests_count()</code>)</li> </ul> <p>Each withdrawal request must appear in the EIP-7685 requests list in the exact order returned by <code>dequeue_withdrawal_requests()</code>.</p> <p>Additionally, the system call and the processing of that block must conform to the following:</p> <ul> <li>The call has a dedicated gas limit of <code>30_000_000</code>.</li> <li>Gas consumed by this call does not count against the block’s overall gas usage.</li> <li>Both the gas limit assigned to the call and the gas consumed are excluded from any checks against the block’s gas limit.</li> <li>The call does not follow <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fee burn semantics — no value should be transferred as part of this call.</li> <li>If there is no code at <code>WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</code>, the corresponding block <strong>MUST</strong> be marked invalid.</li> <li>If the call to the contract fails or returns an error, the block <strong>MUST</strong> be invalidated.</li> </ul> <p>The functionality triggered by the system call is defined in pseudocode as the function <code>read_withdrawal_requests()</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">##################</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Public function #</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> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> read_withdrawal_requests</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> reqs</span><span class="z-keyword"> =</span><span> dequeue_withdrawal_requests</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> update_excess_withdrawal_requests</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> reset_withdrawal_requests_count</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> ssz</span><span>.</span><span>serialize</span><span>(</span><span>reqs</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"> Helpers #</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> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> little_endian_to_uint64</span><span>(</span><span class="z-variable z-parameter z-function">data</span><span>:</span><span class="z-support"> bytes</span><span>)</span><span> -&gt;</span><span> uint64</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> uint64</span><span>(</span><span class="z-support">int</span><span>.</span><span>from_bytes</span><span>(</span><span>data</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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> uint64_to_little_endian</span><span>(</span><span class="z-variable z-parameter z-function">num</span><span>:</span><span> uint64</span><span>)</span><span> -&gt;</span><span class="z-support"> bytes</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> num</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">little</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-storage z-type">class</span><span class="z-entity z-name"> ValidatorWithdrawalRequest</span><span>(</span><span class="z-support">object</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> source_address</span><span>:</span><span> Bytes20</span></span> <span class="giallo-l"><span> validator_pubkey</span><span>:</span><span> Bytes48</span></span> <span class="giallo-l"><span> amount</span><span>:</span><span> uint64</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"> dequeue_withdrawal_requests</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> queue_head_index</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> WITHDRAWAL_REQUEST_QUEUE_HEAD_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> queue_tail_index</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> WITHDRAWAL_REQUEST_QUEUE_TAIL_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span> num_in_queue</span><span class="z-keyword"> =</span><span> queue_tail_index</span><span class="z-keyword"> -</span><span> queue_head_index</span></span> <span class="giallo-l"><span> num_dequeued</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span>num_in_queue</span><span>,</span><span class="z-constant"> MAX_WITHDRAWAL_REQUESTS_PER_BLOCK</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> reqs</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span>num_dequeued</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> queue_storage_slot</span><span class="z-keyword"> =</span><span class="z-constant"> WITHDRAWAL_REQUEST_QUEUE_STORAGE_OFFSET</span><span class="z-keyword"> +</span><span> (</span><span>queue_head_index</span><span class="z-keyword"> +</span><span> i</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> 3</span></span> <span class="giallo-l"><span> source_address</span><span class="z-keyword"> =</span><span> address</span><span>(</span><span>sload</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span>)</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">20</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> validator_pubkey</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> sload</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">32</span><span>]</span><span class="z-keyword"> +</span><span> sload</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span>)</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">16</span><span>]</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> amount</span><span class="z-keyword"> =</span><span> little_endian_to_uint64</span><span>(</span><span>sload</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span> queue_storage_slot</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span>)</span><span>[</span><span class="z-constant">16</span><span>:</span><span class="z-constant">24</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> req</span><span class="z-keyword"> =</span><span> ValidatorWithdrawalRequest</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> source_address</span><span class="z-keyword">=</span><span>Bytes20</span><span>(</span><span>source_address</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> validator_pubkey</span><span class="z-keyword">=</span><span>Bytes48</span><span>(</span><span>validator_pubkey</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> amount</span><span class="z-keyword">=</span><span>uint64</span><span>(</span><span>amount</span><span>)</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> reqs</span><span>.</span><span>append</span><span>(</span><span>req</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> new_queue_head_index</span><span class="z-keyword"> =</span><span> queue_head_index</span><span class="z-keyword"> +</span><span> num_dequeued</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> new_queue_head_index</span><span class="z-keyword"> ==</span><span> queue_tail_index</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Queue is empty, reset queue pointers</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> WITHDRAWAL_REQUEST_QUEUE_HEAD_STORAGE_SLOT</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> WITHDRAWAL_REQUEST_QUEUE_TAIL_STORAGE_SLOT</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> sstore</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> WITHDRAWAL_REQUEST_QUEUE_HEAD_STORAGE_SLOT</span><span>,</span><span> new_queue_head_index</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> reqs</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"> update_excess_withdrawal_requests</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> previous_excess</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> EXCESS_WITHDRAWAL_REQUESTS_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> previous_excess</span><span class="z-keyword"> ==</span><span class="z-constant"> EXCESS_INHIBITOR</span><span>:</span></span> <span class="giallo-l"><span> previous_excess</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> count</span><span class="z-keyword"> =</span><span> sload</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> WITHDRAWAL_REQUEST_COUNT_STORAGE_SLOT</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> new_excess</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> previous_excess</span><span class="z-keyword"> +</span><span> count</span><span class="z-keyword"> &gt;</span><span class="z-constant"> TARGET_WITHDRAWAL_REQUESTS_PER_BLOCK</span><span>:</span></span> <span class="giallo-l"><span> new_excess</span><span class="z-keyword"> =</span><span> previous_excess</span><span class="z-keyword"> +</span><span> count</span><span class="z-keyword"> -</span><span class="z-constant"> TARGET_WITHDRAWAL_REQUESTS_PER_BLOCK</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> EXCESS_WITHDRAWAL_REQUESTS_STORAGE_SLOT</span><span>,</span><span> new_excess</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"> reset_withdrawal_requests_count</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> sstore</span><span>(</span><span class="z-constant">WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</span><span>,</span><span class="z-constant"> WITHDRAWAL_REQUEST_COUNT_STORAGE_SLOT</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span></code></pre><h5 id="bytecode">Bytecode</h5> <pre class="giallo z-code"><code data-lang="asm"><span class="giallo-l"><span>caller</span></span> <span class="giallo-l"><span>push20 </span><span class="z-constant">0xfffffffffffffffffffffffffffffffffffffffe</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0xcb</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x11</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push32 </span><span class="z-constant">0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01f4</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span>gt</span></span> <span class="giallo-l"><span>iszero</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x68</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>dup4</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>dup5</span></span> <span class="giallo-l"><span>dup4</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span class="z-keyword">div</span></span> <span class="giallo-l"><span>swap2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>swap2</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x4d</span></span> <span class="giallo-l"><span>jump</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>swap4</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span class="z-keyword">div</span></span> <span class="giallo-l"><span>swap3</span></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span>calldatasize</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x38</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x88</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>calldatasize</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01f4</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>callvalue</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01f4</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x20</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>callvalue</span></span> <span class="giallo-l"><span>lt</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01f4</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x04</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>caller</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>calldataload</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x20</span></span> <span class="giallo-l"><span>calldataload</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>caller</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x60</span></span> <span class="giallo-l"><span class="z-keyword">shl</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x38</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x14</span></span> <span class="giallo-l"><span>calldatacopy</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x4c</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>log0</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>stop</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span class="z-keyword">sub</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x10</span></span> <span class="giallo-l"><span>gt</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0xdf</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x10</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x0183</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x04</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x4c</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x60</span></span> <span class="giallo-l"><span class="z-keyword">shl</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x14</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x20</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push32 </span><span class="z-constant">0xffffffffffffffffffffffffffffffff00000000000000000000000000000000</span></span> <span class="giallo-l"><span class="z-keyword">and</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x10</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x40</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x38</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x07</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x30</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x06</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x28</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x05</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x20</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x04</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x18</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x10</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x08</span></span> <span class="giallo-l"><span class="z-keyword">shr</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>mstore8</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0xe1</span></span> <span class="giallo-l"><span>jump</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>swap2</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>swap3</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x0195</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01a0</span></span> <span class="giallo-l"><span>jump</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x03</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>push32 </span><span class="z-constant">0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span>iszero</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01cd</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span>dup3</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>gt</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01e2</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span class="z-keyword">pop</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span class="z-keyword">push2</span><span class="z-constant"> 0x01e8</span></span> <span class="giallo-l"><span>jump</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x02</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span class="z-keyword">sub</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x01</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x4c</span></span> <span class="giallo-l"><span class="z-keyword">mul</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>revert</span></span></code></pre><h5 id="deployment">Deployment</h5> <p>The withdrawal requests contract is deployed like any other smart contract. A special synthetic address is generated by working backwards from the desired deployment transaction:</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">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">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">to</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x3d090</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasPrice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe8d4a51000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxPriorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</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">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">input</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff5f556101f880602d5f395ff33373fffffffffffffffffffffffffffffffffffffffe1460cb5760115f54807fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff146101f457600182026001905f5b5f82111560685781019083028483029004916001019190604d565b909390049250505036603814608857366101f457346101f4575f5260205ff35b34106101f457600154600101600155600354806003026004013381556001015f35815560010160203590553360601b5f5260385f601437604c5fa0600101600355005b6003546002548082038060101160df575060105b5f5b8181146101835782810160030260040181604c02815460601b8152601401816001015481526020019060020154807fffffffffffffffffffffffffffffffff00000000000000000000000000000000168252906010019060401c908160381c81600701538160301c81600601538160281c81600501538160201c81600401538160181c81600301538160101c81600201538160081c81600101535360010160e1565b910180921461019557906002556101a0565b90505f6002555f6003555b5f54807fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff14156101cd57505f5b6001546002828201116101e25750505f6101e8565b01600290035b5f555f600155604c025ff35b5f5ffd</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">v</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">r</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x539</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">s</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x5feeb084551e4e03a3581e269bc2ea2f8d0008</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x8ded54be89448d78d4bc97782c0187b099e45380ab681742f9d3754e405c2572</span><span class="z-punctuation z-definition z-string">&quot;</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>Sender: 0x8646861A7cF453dDD086874d622b0696dE5b9674</span></span> <span class="giallo-l"><span>Address: 0x00000961Ef480Eb55e80D19ad83579A64c007002</span></span></code></pre><h3 id="consensus-layer">Consensus layer</h3> <p><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/7bf43d1bc4fdb91059f0e6f4f7f0f3349b144950/specs/electra/beacon-chain.md">Full specification</a></p> <p>Sketch of spec:</p> <ul> <li>New operation <code>ExecutionLayerWithdrawalRequest</code></li> <li>Will show up in <code>ExecutionPayload</code> as an SSZ List bound by length <code>MAX_WITHDRAWAL_REQUESTS_PER_BLOCK</code></li> <li>New function that has similar functionality to <code>process_voluntary_exit</code> but can fail validations (e.g. validator is already exited) without the block failing (similar to deposit coming from EL)</li> <li>This function is called in <code>process_operations</code> for each <code>ExecutionLayerWithdrawalRequest</code> found in the <code>ExecutionPayload</code></li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="validator-pubkey-field"><code>validator_pubkey</code> field</h3> <p>Multiple validators can utilize the same execution layer withdrawal credential, thus the <code>validator_pubkey</code> field is utilized to disambiguate which validator is being exited.</p> <p>Note, <code>validator_index</code> also disambiguates validators. The problem is that smart contracts of some staking pools are not aware of the indices, because the index becomes known only after the validator has been created on the beacon chain, while the pubkey is available in advance.</p> <h3 id="message-queue">Message queue</h3> <p>The contract maintains an in-state queue of withdrawal request messages to be dequeued each block into the block and thus into the execution layer.</p> <p>The number of withdrawal requests that can be passed into the consensus layer are bound by <code>MAX_WITHDRAWAL_REQUESTS_PER_BLOCK</code> to bound the load both on the block size as well as on the consensus layer processing. <code>16</code> has been chosen for <code>MAX_WITHDRAWAL_REQUESTS_PER_BLOCK</code> to be in line with the bounds of similar operations on the beacon chain -- e.g. <code>VoluntaryExit</code> and <code>Deposit</code>.</p> <p>Although there is a maximum number of withdrawal requests that can be passed to the consensus layer each block, the execution layer gas limit can provide for far more calls to the withdrawal request predeploy contract at each block. The queue then allows for these calls to successfully be made while still maintaining a system rate limit.</p> <p>The alternative design considered was to have calls to the contract fail after <code>MAX_WITHDRAWAL_REQUESTS_PER_BLOCK</code> successful calls were made within the context of a single block. This would eliminate the need for the message queue, but would come at the cost of a bad UX of contract call failures in times of high exiting. The complexity to mitigate this bad UX is relatively low and is currently favored.</p> <h3 id="rate-limiting-using-a-fee">Rate limiting using a fee</h3> <p>Transactions are naturally rate-limited in the execution layer via the gas limit, but an adversary willing to pay market-rate gas fees (and potentially utilize builder markets to pay for front-of-block transaction inclusion) can fill up the exit operation limits for relatively cheap, thus griefing honest validators that want to make a withdrawal request.</p> <p>There are two general approaches to combat this griefing -- (a) only allow validators to send such messages and with a limit per time period or (b) utilize an economic method to make such griefing increasingly costly.</p> <p>Method (a) (not used in this EIP) would require <a href="https://wg-eips.ritovision.com/4788/">EIP-4788</a> (the <code>BEACON_ROOT</code> opcode) against which to prove withdrawal credentials in relation to validator pubkeys as well as a data-structure to track requests per-unit-time (e.g. 4 months) to ensure that a validator cannot grief the mechanism by submitting many requests. The downsides of this method are that it requires another cross-layer EIP and that it is of higher cross-layer complexity (e.g. care that might need to be taken in future upgrades if, for example, the shape of the merkle tree of <code>BEACON_ROOT</code> changes, then the contract and proof structure might need to be updated).</p> <p>Method (b) has been utilized in this EIP to eliminate additional EIP requirements and to reduce cross-layer complexity to allow for correctness of this EIP (now and in the future) to be easier to analyze. The <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a>-style mechanism with a dynamically adjusting fee mechanism allows for users to pay <code>MIN_WITHDRAWAL_REQUEST_FEE</code> for withdrawal requests in the normal case (fewer than 2 per block on average), but scales the fee up exponentially in response to high usage (i.e. potential abuse).</p> <h3 id="target-withdrawal-requests-per-block-configuration-value"><code>TARGET_WITHDRAWAL_REQUESTS_PER_BLOCK</code> configuration value</h3> <p><code>TARGET_WITHDRAWAL_REQUESTS_PER_BLOCK</code> has been selected as <code>2</code> such that the growth of the partial withdrawal queue in the beacon state is negligible under extreme scenarios of the exit churn congestion.</p> <h3 id="fee-update-rule">Fee update rule</h3> <p>The fee update rule is intended to approximate the formula <code>fee = MIN_WITHDRAWAL_REQUEST_FEE * e**(excess / WITHDRAWAL_REQUEST_FEE_UPDATE_FRACTION)</code>, where <code>excess</code> is the total "extra" amount of withdrawal requests that the chain has processed relative to the "targeted" number (<code>TARGET_WITHDRAWAL_REQUESTS_PER_BLOCK</code> per block).</p> <p>Like EIP-1559, it’s a self-correcting formula: as the excess goes higher, the <code>fee</code> increases exponentially, reducing usage and eventually forcing the excess back down.</p> <p>The block-by-block behavior is roughly as follows. If block <code>N</code> processes <code>X</code> requests, then at the end of block <code>N</code> <code>excess</code> increases by <code>X - TARGET_WITHDRAWAL_REQUESTS_PER_BLOCK</code>, and so the <code>fee</code> in block <code>N+1</code> increases by a factor of <code>e**((X - TARGET_WITHDRAWAL_REQUESTS_PER_BLOCK) / WITHDRAWAL_REQUEST_FEE_UPDATE_FRACTION)</code>. Hence, it has a similar effect to the existing EIP-1559, but is more "stable" in the sense that it responds in the same way to the same total withdrawal requests regardless of how they are distributed over time.</p> <p>The parameter <code>WITHDRAWAL_REQUEST_FEE_UPDATE_FRACTION</code> controls the maximum downwards rate of change of the blob gas price. It is chosen to target a maximum downwards change rate of <code>e(TARGET_WITHDRAWAL_REQUESTS_PER_BLOCK / WITHDRAWAL_REQUEST_FEE_UPDATE_FRACTION) ≈ 1.125</code> per block.</p> <p>More detailed analysis of the fee mechanism is available <a href="https://wg-eips.ritovision.com/7002/assets/fee_analysis/">here</a>.</p> <h3 id="withdrawal-requests-inside-of-the-block">Withdrawal requests inside of the block</h3> <p>Withdrawal requests are placed into the actual body of the beacon block.</p> <p>There is a strong design requirement that the consensus layer and execution layer can execute independently of each other. This means, in this case, that the consensus layer cannot rely upon a synchronous call to the execution layer to get the required withdrawal requests for the current block. Instead, the requests must be embedded in the beacon block such that if the execution layer is offline, the consensus layer still has the requisite data to fully execute the consensus portion of the state transition function.</p> <h3 id="submitting-requests-via-execution-layer">Submitting requests via execution layer</h3> <p>Verifying <code>secp256k1</code> signatures from the consensus layer via Engine API is one of the alternatives to the proposed requests mechanism which engineering complexity is much lower. However, this approach would limit usage of withdrawal requests to a large extent by making it impossible for smart contracts owning validator withdrawal credentials to benefit from this functionality.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces backwards incompatible changes to the block structure and block validation rule set. But neither of these changes break anything related to current user activity and experience.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="impact-on-existing-custody-relationships">Impact on existing custody relationships</h3> <p>There might be existing custody relationships and/or products that rely upon the assumption that the withdrawal credentials <em>cannot</em> trigger a withdrawal request. We are currently confident that the additional withdrawal credentials feature does not impact the security of existing validators because:</p> <ol> <li>The withdrawal credentials ultimately own the funds so allowing them to exit staking is natural with respect to ownership.</li> <li>We are currently not aware of any such custody relationships and/or products that do rely on the lack of this feature.</li> </ol> <p>In the event that existing validators/custodians rely on this, then the validators can be exited and restaked utilizing 0x01 withdrawal credentials pointing to a smart contract that simulates this behaviour.</p> <h3 id="fee-overpayment">Fee Overpayment</h3> <p>Calls to the system contract require a fee payment defined by the current contract state. Overpaid fees are not returned to the caller. It is not generally possible to compute the exact required fee amount ahead of time. When adding a withdrawal request from a contract, the contract can perform a read operation to check for the current fee and then pay exactly the required amount. Here is an example in Solidity:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function addWithdrawal(bytes memory pubkey, uint64 amount, uint64 requestFeeLimit) private {</span></span> <span class="giallo-l"><span> assert(pubkey.length == 48);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Read current fee from the contract.</span></span> <span class="giallo-l"><span> (bool readOK, bytes memory feeData) = WithdrawalsContract.staticcall(&#39;&#39;);</span></span> <span class="giallo-l"><span> if (!readOK) {</span></span> <span class="giallo-l"><span> revert(&#39;reading fee failed&#39;);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> uint256 fee = uint256(bytes32(feeData));</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Check the fee is not too high.</span></span> <span class="giallo-l"><span> if (fee &gt; requestFeeLimit) {</span></span> <span class="giallo-l"><span> revert(&#39;fee is too high&#39;);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Add the request.</span></span> <span class="giallo-l"><span> bytes memory callData = abi.encodePacked(pubkey, amount);</span></span> <span class="giallo-l"><span> (bool writeOK,) = WithdrawalsContract.call{value: fee}(callData);</span></span> <span class="giallo-l"><span> if (!writeOK) {</span></span> <span class="giallo-l"><span> revert(&#39;adding request failed&#39;);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Note: the system contract uses the EVM <code>CALLER</code> operation (Solidity: <code>msg.sender</code>) as the target address for withdrawals, i.e. the address that calls the system contract must match the 0x01 withdrawal credential recorded in the beacon state.</p> <p>Note: the above code reverts if the fee is too high, the fee can change significantly between creation of a withdrawal request transaction and its inclusion into a block, thus, this check is very important to avoid overpayments.</p> <p>Using an EOA to request withdrawals will always result in overpayment of fees. There is no way for an EOA to use a wrapper contract to request a withdrawal. And even if a way existed, the gas cost of returning the overage would likely be higher than the overage itself. If requesting withdrawals to an EOA through the system contract is desired, we recommend that users perform transaction simulations to estimate a reasonable fee amount to send.</p> <h3 id="system-call-failure">System Call failure</h3> <p>Although the likelihood of a failed system call to <code>WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</code> is extremely low, the behavior in such cases is well-defined: the block is marked as invalid. However, if the failure results from processing a transaction within the block, the public mempool may still retain the transaction even after the block is invalidated. This can result in the offending transaction being included again, potentially causing one or more subsequent slots to go without valid blocks. To mitigate this, we recommend that the block producer implementation shuffle their transaction set to increase the chances of producing a valid block, without the offending transaction(s). The block producer implementation and/or the mempool should be aware of system call failure scenarios to enable this behavior.</p> <h3 id="empty-code-failure">Empty Code failure</h3> <p>This EIP should not have been activated if there is no code present at <code>WITHDRAWAL_REQUEST_PREDEPLOY_ADDRESS</code> (i.e., if the chain is not "ready"). Doing so would cause the first and all subsequent blocks after <code>FORK_BLOCK</code> to be marked invalid.</p> <p>If this situation occurs on a live chain, the following are two potential recovery strategies:</p> <ul> <li>Deploy the contract code via a transaction and include it in a block. This block would become the first valid block, provided the system call to the contract does not fail. This works because the empty code validation occurs after block-transactions execution.</li> <li>Postpone the <code>FORK_BLOCK</code> activation point by updating the consensual fork timestamp or block number in the client implementation(s), then deploy the contract before the fork activates.</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> 2023-05-07T00:00:00+00:00 2026-02-11T14:48:25+00:00 Eduard López i Finahttps://github.com/eduardfina https://wg-eips.ritovision.com/6997/

A new validation step for transfer and approve calls, achieving a security step in case of stolen wallet.

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. It defines new validation functionality to avoid wallet draining: every <code>transfer</code> or <code>approve</code> will be locked waiting for validation.</p> <h2 id="motivation">Motivation</h2> <p>The power of the blockchain is at the same time its weakness: giving the user full responsibility for their data.</p> <p>Many cases of NFT theft currently exist, and current NFT anti-theft schemes, such as transferring NFTs to cold wallets, make NFTs inconvenient to use.</p> <p>Having a validation step before every <code>transfer</code> and <code>approve</code> would give Smart Contract developers the opportunity to create secure NFT anti-theft schemes.</p> <p>An implementation example would be a system where a validator address is responsible for validating all Smart Contract transactions.</p> <p>This address would be connected to a dApp where the user could see the validation requests of his NFTs and accept the correct ones.</p> <p>Giving this address only the power to validate transactions would make a much more secure system where to steal an NFT the thief would have to have both the user's address and the validator address simultaneously.</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><a href="https://wg-eips.ritovision.com/721/">ERC-721</a> compliant contracts MAY implement this EIP.</p> <p>All the operations that change the ownership of an NFT, like a <code>transferFrom</code>/<code>safeTransferFrom</code>, SHALL create a <code>TransferValidation</code> pending to be validated and emit a <code>ValidateTransfer</code>, and SHALL NOT transfer the ownership of an NFT.</p> <p>All the operations that enable an approval to manage an NFT, like an <code>approve</code>/<code>setApprovalForAll</code>, SHALL create an <code>ApprovalValidation</code> pending to be validated and emit a <code>ValidateApproval</code>, and SHALL NOT enable an approval.</p> <p>When the transfer is called by an approved account and not the owner, it MUST be executed directly without the need for validation. This is in order to adapt to all current marketplaces that require approve to directly move your NFTs.</p> <p>When validating a <code>TransferValidation</code> or <code>ApprovalValidation</code> the valid field MUST be set to true and MUST NOT be validated again.</p> <p>The operations that validate a <code>TransferValidation</code> SHALL change the ownership of the NFT or enable the approval.</p> <p>The operations that validate an <code>ApprovalValidation</code> SHALL enable the approval.</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"> IERC6997</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"> TransferValidation</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The address of the owner.</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> from</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The address of the receiver.</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-comment"> //</span><span class="z-comment"> The token Id.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> tokenId</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Whether is a valid transfer.</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> valid</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"> ApprovalValidation</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The address of the owner.</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> owner</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The approved address.</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> approve</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The token Id.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> tokenId</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Whether it is a total approval.</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> approveAll</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Whether it is a valid approval.</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> valid</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"> Emitted when a new transfer validation has been requested.</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"> ValidateTransfer</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 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-storage z-type"> indexed</span><span class="z-variable"> transferValidationId</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 a new approval validation has been requested.</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"> ValidateApproval</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-variable"> approve</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>, </span><span class="z-support">bool</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> approveAll</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> approvalValidationId</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 this contract is a validator ERC721.</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"> isValidatorContract</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the transfer validation struct using the transfer ID.</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"> transferValidation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> transferId</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">TransferValidation</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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the approval validation struct using the approval ID.</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"> approvalValidation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> approvalId</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">ApprovalValidation</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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Return the total amount of transfer validations created.</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"> totalTransferValidations</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">@dev</span><span class="z-comment"> Return the total amount of transfer validations created.</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"> totalApprovalValidations</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></span></code></pre> <p>The <code>isValidatorContract()</code> function MUST be implemented as <code>public</code>.</p> <p>The <code>transferValidation(uint256 transferId)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>approvalValidation(uint256 approveId)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>totalTransferValidations()</code> function MAY be implemented as <code>pure</code> or <code>view</code>.</p> <p>The <code>totalApprovalValidations()</code> function MAY be implemented as <code>pure</code> or <code>view</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="universality">Universality</h3> <p>The standard only defines the validation functions, but not how they should be used. It defines the validations as internal and lets the user decide how to manage them.</p> <p>An example could be to have an address validator connected to a dApp so that users could manage their validations.</p> <p>This validator could be used for all NFTs or only for some users.</p> <p>It could also be used as a wrapped Smart Contract for existing ERC-721, allowing 1/1 conversion with existing NFTs.</p> <h3 id="extensibility">Extensibility</h3> <p>This standard only defines the validation function, but does not define the system with which it has to be validated. A third-party protocol can define how it wants to call these functions as it wishes.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, compatible with all the operations except <code>transferFrom</code>/<code>safeTransferFrom</code>/<code>approve</code>/<code>setApprovalForAll</code>.</p> <p>This operations will be overridden to create a validation petition instead of transfer ownership of an NFT or enable an approval.</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> <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;./IERC6997.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> <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 ERC6997</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"> ERC6997</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6997</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-comment"> //</span><span class="z-comment"> Mapping from transfer ID to transfer validation</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> TransferValidation</span><span>)</span><span class="z-storage z-type"> private</span><span> _transferValidations</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Mapping from approval ID to approval validation</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> ApprovalValidation</span><span>)</span><span class="z-storage z-type"> private</span><span> _approvalValidations</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Total number of transfer validations</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> _totalTransferValidations</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Total number of approval validations</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> _totalApprovalValidations</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"> Initializes the contract by setting a `name` and a `symbol` to the token collection.</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">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-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 this contract is a validator ERC721.</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"> isValidatorContract</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 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"> Returns the transfer validation struct using the transfer ID.</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"> transferValidation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> transferId</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 class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">TransferValidation</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>transferId </span><span class="z-keyword">&lt;</span><span> _totalTransferValidations</span><span>,</span><span class="z-string"> &quot;ERC6997: invalid transfer ID&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> TransferValidation </span><span class="z-storage z-type">memory</span><span> v </span><span class="z-keyword">=</span><span class="z-entity z-name"> _transferValidation</span><span>(</span><span>transferId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> v</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 approval validation struct using the approval ID.</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"> approvalValidation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> approvalId</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 class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">ApprovalValidation</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>approvalId </span><span class="z-keyword">&lt;</span><span> _totalApprovalValidations</span><span>,</span><span class="z-string"> &quot;ERC6997: invalid approval ID&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> ApprovalValidation </span><span class="z-storage z-type">memory</span><span> v </span><span class="z-keyword">=</span><span class="z-entity z-name"> _approvalValidation</span><span>(</span><span>approvalId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> v</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"> Return the total amount of transfer validations created.</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"> totalTransferValidations</span><span>(</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 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> _totalTransferValidations</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"> Return the total amount of approval validations created.</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"> totalApprovalValidations</span><span>(</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 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> _totalApprovalValidations</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 transfer validation of the `transferId`. Does NOT revert if transfer doesn&#39;t 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"> _transferValidation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> transferId</span><span>)</span><span class="z-storage z-type"> internal</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-storage z-type">TransferValidation</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> _transferValidations</span><span>[</span><span>transferId</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 approval validation of the `approvalId`. Does NOT revert if transfer doesn&#39;t 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"> _approvalValidation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> approvalId</span><span>)</span><span class="z-storage z-type"> internal</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-storage z-type">ApprovalValidation</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> _approvalValidations</span><span>[</span><span>approvalId</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"> Validate the transfer using the transfer ID.</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"> _validateTransfer</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> transferId</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> TransferValidation </span><span class="z-storage z-type">memory</span><span> v </span><span class="z-keyword">=</span><span class="z-entity z-name"> transferValidation</span><span>(</span><span>transferId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-keyword">!</span><span>v</span><span>.</span><span>valid</span><span>,</span><span class="z-string"> &quot;ERC6997: the transfer is already validated&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> address</span><span> from </span><span class="z-keyword">=</span><span> v</span><span>.</span><span>from</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> to </span><span class="z-keyword">=</span><span> v</span><span>.</span><span>to</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> tokenId </span><span class="z-keyword">=</span><span> v</span><span>.</span><span>tokenId</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">_transfer</span><span>(</span><span>from</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _transferValidations</span><span>[</span><span>transferId</span><span>]</span><span>.</span><span>valid </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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Validate the approval using the approval ID.</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"> _validateApproval</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> approvalId</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> ApprovalValidation </span><span class="z-storage z-type">memory</span><span> v </span><span class="z-keyword">=</span><span class="z-entity z-name"> approvalValidation</span><span>(</span><span>approvalId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-keyword">!</span><span>v</span><span>.</span><span>valid</span><span>,</span><span class="z-string"> &quot;ERC6997: the approval is already validated&quot;</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>v</span><span>.</span><span>approveAll</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>v</span><span>.</span><span>owner </span><span class="z-keyword">==</span><span class="z-entity z-name"> ownerOf</span><span>(</span><span>v</span><span>.</span><span>tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC6997: The token have a new owner&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>v</span><span>.</span><span>approve</span><span>,</span><span> v</span><span>.</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">_setApprovalForAll</span><span>(</span><span>v</span><span>.</span><span>owner</span><span>,</span><span> v</span><span>.</span><span>approve</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 class="giallo-l"><span> _approvalValidations</span><span>[</span><span>approvalId</span><span>]</span><span>.</span><span>valid </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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Create a transfer petition of `tokenId` from `from` to `to`.</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"> * - `to` cannot be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * - `tokenId` token must be owned by `from`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {TransferValidate} 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"> _transfer</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-keyword"> require</span><span>(</span><span>ERC721</span><span>.</span><span class="z-entity z-name">ownerOf</span><span>(</span><span>tokenId</span><span>)</span><span class="z-keyword"> ==</span><span> from</span><span>,</span><span class="z-string"> &quot;ERC6997: transfer from incorrect owner&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>to </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;ERC6997: transfer to the zero address&quot;</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-entity z-name">_msgSender</span><span>(</span><span>)</span><span class="z-keyword"> ==</span><span> from</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> TransferValidation </span><span class="z-storage z-type">memory</span><span> v</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> v</span><span>.</span><span>from </span><span class="z-keyword">=</span><span> from</span><span>;</span></span> <span class="giallo-l"><span> v</span><span>.</span><span>to </span><span class="z-keyword">=</span><span> to</span><span>;</span></span> <span class="giallo-l"><span> v</span><span>.</span><span>tokenId </span><span class="z-keyword">=</span><span> tokenId</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _transferValidations</span><span>[</span><span>_totalTransferValidations</span><span>]</span><span class="z-keyword"> =</span><span> v</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"> ValidateTransfer</span><span>(</span><span>from</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>,</span><span> _totalTransferValidations</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _totalTransferValidations</span><span class="z-keyword">+</span><span class="z-keyword">+</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-language"> super</span><span>.</span><span class="z-entity z-name">_transfer</span><span>(</span><span>from</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Create an approval petition from `to` to operate on `tokenId`</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {ValidateApproval} 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"> _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"> internal</span><span class="z-storage z-type"> override</span><span class="z-storage z-type"> virtual</span><span> {</span></span> <span class="giallo-l"><span> ApprovalValidation </span><span class="z-storage z-type">memory</span><span> v</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> v</span><span>.</span><span>owner </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 class="giallo-l"><span> v</span><span>.</span><span>approve </span><span class="z-keyword">=</span><span> to</span><span>;</span></span> <span class="giallo-l"><span> v</span><span>.</span><span>tokenId </span><span class="z-keyword">=</span><span> tokenId</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _approvalValidations</span><span>[</span><span>_totalApprovalValidations</span><span>]</span><span class="z-keyword"> =</span><span> v</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"> ValidateApproval</span><span>(</span><span>v</span><span>.</span><span>owner</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>,</span><span class="z-constant"> false</span><span>,</span><span> _totalApprovalValidations</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _totalApprovalValidations</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 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"> If approved is true create an approval petition from `operator` to operate on</span></span> <span class="giallo-l"><span class="z-comment"> * all of `owner` tokens, if not remove `operator` from operate on all of `owner` tokens</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {ValidateApproval} 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"> _setApprovalForAll</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"> address</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 class="z-storage z-type"> internal</span><span class="z-storage z-type"> override</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>owner </span><span class="z-keyword">!=</span><span> operator</span><span>,</span><span class="z-string"> &quot;ERC6997: approve to caller&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>approved</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> ApprovalValidation </span><span class="z-storage z-type">memory</span><span> v</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> v</span><span>.</span><span>owner </span><span class="z-keyword">=</span><span> owner</span><span>;</span></span> <span class="giallo-l"><span> v</span><span>.</span><span>approve </span><span class="z-keyword">=</span><span> operator</span><span>;</span></span> <span class="giallo-l"><span> v</span><span>.</span><span>approveAll </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> _approvalValidations</span><span>[</span><span>_totalApprovalValidations</span><span>]</span><span class="z-keyword"> =</span><span> v</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"> ValidateApproval</span><span>(</span><span>v</span><span>.</span><span>owner</span><span>,</span><span> operator</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> true</span><span>,</span><span> _totalApprovalValidations</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _totalApprovalValidations</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"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">_setApprovalForAll</span><span>(</span><span>owner</span><span>,</span><span> operator</span><span>,</span><span> approved</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> <p>As is defined in the Specification the operations that change the ownership of an NFT or enable an approval to manage the NFT SHALL create a <code>TransferValidation</code> or an <code>ApprovalValidation</code> pending to be validated and SHALL NOT transfer the ownership of an NFT or enable an approval.</p> <p>With this premise in mind, the operations in charge of validating a <code>TransferValidation</code> or an <code>ApprovalValidation</code> must be protected with the maximum security required by the applied system.</p> <p>For example, a valid system would be one where there is a validator address in charge of validating the transactions.</p> <p>To give another example, a system where each user could choose his validator address would also be correct.</p> <p>In any case, the importance of security resides in the fact that no address can validate a <code>TransferValidation</code> or an <code>ApprovalValidation</code> without the permission of the chosen system.</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-07T00:00:00+00:00 2026-02-11T14:48:25+00:00 Eduard López i Finahttps://github.com/eduardfina https://wg-eips.ritovision.com/7144/

A new validation step for transfer and approve calls, achieving a security step in case of stolen wallet.

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. It defines new validation functionality to avoid wallet draining: every <code>transfer</code> or <code>approve</code> will be locked waiting for validation.</p> <h2 id="motivation">Motivation</h2> <p>The power of the blockchain is at the same time its weakness: giving the user full responsibility for their data.</p> <p>Many cases of Token theft currently exist, and current Token anti-theft schemes, such as transferring Tokens to cold wallets, make Tokens inconvenient to use.</p> <p>Having a validation step before every <code>transfer</code> and <code>approve</code> would give Smart Contract developers the opportunity to create secure Token anti-theft schemes.</p> <p>An implementation example would be a system where a validator address is responsible for validating all Smart Contract transactions.</p> <p>This address would be connected to a dApp where the user could see the validation requests of his Tokens and accept the correct ones.</p> <p>Giving this address only the power to validate transactions would make a much more secure system where to steal a Token the thief would have to have both the user's address and the validator address simultaneously.</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><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> compliant contracts MAY implement this EIP.</p> <p>All the operations that change the ownership of Tokens, like a <code>transfer</code>/<code>transferFrom</code>, SHALL create a <code>TransferValidation</code> pending to be validated and emit a <code>ValidateTransfer</code>, and SHALL NOT transfer the Tokens.</p> <p>All the operations that enable an approval to manage a Token, like an <code>approve</code>, SHALL create an <code>ApprovalValidation</code> pending to be validated and emit a <code>ValidateApproval</code>, and SHALL NOT enable an approval.</p> <p>When the transfer is called by an approved account and not the owner, it MUST be executed directly without the need for validation. This is in order to adapt to all current projects that require approve to directly move your Tokens.</p> <p>When validating a <code>TransferValidation</code> or <code>ApprovalValidation</code> the valid field MUST be set to true and MUST NOT be validated again.</p> <p>The operations that validate a <code>TransferValidation</code> SHALL change the ownership of the Tokens.</p> <p>The operations that validate an <code>ApprovalValidation</code> SHALL enable the approval.</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"> IERC7144</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"> TransferValidation</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The address of the owner.</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> from</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The address of the receiver.</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-comment"> //</span><span class="z-comment"> The token amount.</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"> Whether is a valid transfer.</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> valid</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"> ApprovalValidation</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The address of the owner.</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> owner</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The spender address.</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> spender</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The token amount approved.</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"> Whether is a valid approval.</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> valid</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"> Emitted when a new transfer validation has been requested.</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"> ValidateTransfer</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"> amount</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> transferValidationId</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 a new approval validation has been requested.</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"> ValidateApproval</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"> amount</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> approvalValidationId</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 this contract is a validator ERC20.</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"> isValidatorContract</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the transfer validation struct using the transfer ID.</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"> transferValidation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> transferId</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">TransferValidation</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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the approval validation struct using the approval ID.</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"> approvalValidation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> approvalId</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">ApprovalValidation</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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Return the total amount of transfer validations created.</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"> totalTransferValidations</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">@dev</span><span class="z-comment"> Return the total amount of transfer validations created.</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"> totalApprovalValidations</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></span></code></pre> <p>The <code>isValidatorContract()</code> function MUST be implemented as <code>public</code>.</p> <p>The <code>transferValidation(uint256 transferId)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>approvalValidation(uint256 approveId)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>totalTransferValidations()</code> function MAY be implemented as <code>pure</code> or <code>view</code>.</p> <p>The <code>totalApprovalValidations()</code> function MAY be implemented as <code>pure</code> or <code>view</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="universality">Universality</h3> <p>The standard only defines the validation functions, but not how they should be used. It defines the validations as internal and lets the user decide how to manage them.</p> <p>An example could be to have an address validator connected to a dApp so that users could manage their validations.</p> <p>This validator could be used for all Tokens or only for some users.</p> <p>It could also be used as a wrapped Smart Contract for existing ERC-20, allowing 1/1 conversion with existing Tokens.</p> <h3 id="extensibility">Extensibility</h3> <p>This standard only defines the validation function, but does not define the system with which it has to be validated. A third-party protocol can define how it wants to call these functions as it wishes.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, compatible with all the operations except <code>transfer</code>/<code>transferFrom</code>/<code>approve</code>.</p> <p>This operations will be overridden to create a validation petition instead of transfer the Tokens or enable an approval.</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> <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/ERC20/ERC20.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC7144.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"> Implementation of ERC7144</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"> ERC7144</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC7144</span><span>, </span><span class="z-entity z-name">ERC20</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Mapping from transfer ID to transfer validation</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> TransferValidation</span><span>)</span><span class="z-storage z-type"> private</span><span> _transferValidations</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Mapping from approval ID to approval validation</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> ApprovalValidation</span><span>)</span><span class="z-storage z-type"> private</span><span> _approvalValidations</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Total number of transfer validations</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> _totalTransferValidations</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Total number of approval validations</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> _totalApprovalValidations</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"> Initializes the contract by setting a `name` and a `symbol` to the token collection.</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">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"> ERC20</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-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 this contract is a validator ERC721.</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"> isValidatorContract</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 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"> Returns the transfer validation struct using the transfer ID.</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"> transferValidation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> transferId</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 class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">TransferValidation</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>transferId </span><span class="z-keyword">&lt;</span><span> _totalTransferValidations</span><span>,</span><span class="z-string"> &quot;ERC7144: invalid transfer ID&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> TransferValidation </span><span class="z-storage z-type">memory</span><span> v </span><span class="z-keyword">=</span><span class="z-entity z-name"> _transferValidation</span><span>(</span><span>transferId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> v</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 approval validation struct using the approval ID.</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"> approvalValidation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> approvalId</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 class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">ApprovalValidation</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>approvalId </span><span class="z-keyword">&lt;</span><span> _totalApprovalValidations</span><span>,</span><span class="z-string"> &quot;ERC7144: invalid approval ID&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> ApprovalValidation </span><span class="z-storage z-type">memory</span><span> v </span><span class="z-keyword">=</span><span class="z-entity z-name"> _approvalValidation</span><span>(</span><span>approvalId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> v</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"> Return the total amount of transfer validations created.</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"> totalTransferValidations</span><span>(</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 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> _totalTransferValidations</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"> Return the total amount of approval validations created.</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"> totalApprovalValidations</span><span>(</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 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> _totalApprovalValidations</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 transfer validation of the `transferId`. Does NOT revert if transfer doesn&#39;t 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"> _transferValidation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> transferId</span><span>)</span><span class="z-storage z-type"> internal</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-storage z-type">TransferValidation</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> _transferValidations</span><span>[</span><span>transferId</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 approval validation of the `approvalId`. Does NOT revert if transfer doesn&#39;t 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"> _approvalValidation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> approvalId</span><span>)</span><span class="z-storage z-type"> internal</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-storage z-type">ApprovalValidation</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> _approvalValidations</span><span>[</span><span>approvalId</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"> Validate the transfer using the transfer ID.</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"> _validateTransfer</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> transferId</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> TransferValidation </span><span class="z-storage z-type">memory</span><span> v </span><span class="z-keyword">=</span><span class="z-entity z-name"> transferValidation</span><span>(</span><span>transferId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-keyword">!</span><span>v</span><span>.</span><span>valid</span><span>,</span><span class="z-string"> &quot;ERC721V: the transfer is already validated&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">_transfer</span><span>(</span><span>v</span><span>.</span><span>from</span><span>,</span><span> v</span><span>.</span><span>to</span><span>,</span><span> v</span><span>.</span><span>amount</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _transferValidations</span><span>[</span><span>transferId</span><span>]</span><span>.</span><span>valid </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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Validate the approval using the approval ID.</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"> _validateApproval</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> approvalId</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> ApprovalValidation </span><span class="z-storage z-type">memory</span><span> v </span><span class="z-keyword">=</span><span class="z-entity z-name"> approvalValidation</span><span>(</span><span>approvalId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-keyword">!</span><span>v</span><span>.</span><span>valid</span><span>,</span><span class="z-string"> &quot;ERC7144: the approval is already validated&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></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>v</span><span>.</span><span>owner</span><span>,</span><span> v</span><span>.</span><span>spender</span><span>,</span><span> v</span><span>.</span><span>amount</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _approvalValidations</span><span>[</span><span>approvalId</span><span>]</span><span>.</span><span>valid </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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Create a transfer petition of `tokenId` from `from` to `to`.</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"> * - `from` cannot be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * - `to` 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"> * Emits a {ValidateTransfer} 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"> _transfer</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"> 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>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 class="z-string"> &quot;ERC7144: transfer from the zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>to </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;ERC7144: transfer to the zero address&quot;</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-entity z-name">_msgSender</span><span>(</span><span>)</span><span class="z-keyword"> ==</span><span> from</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> TransferValidation </span><span class="z-storage z-type">memory</span><span> v</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> v</span><span>.</span><span>from </span><span class="z-keyword">=</span><span> from</span><span>;</span></span> <span class="giallo-l"><span> v</span><span>.</span><span>to </span><span class="z-keyword">=</span><span> to</span><span>;</span></span> <span class="giallo-l"><span> v</span><span>.</span><span>amount </span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _transferValidations</span><span>[</span><span>_totalTransferValidations</span><span>]</span><span class="z-keyword"> =</span><span> v</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"> ValidateTransfer</span><span>(</span><span>from</span><span>,</span><span> to</span><span>,</span><span> amount</span><span>,</span><span> _totalTransferValidations</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _totalTransferValidations</span><span class="z-keyword">+</span><span class="z-keyword">+</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-language"> super</span><span>.</span><span class="z-entity z-name">_transfer</span><span>(</span><span>from</span><span>,</span><span> to</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> <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"> Create an approval petition from `owner` to operate the `amount`</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {ValidateApproval} 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"> _approve</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"> address</span><span class="z-variable"> spender</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"> 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>owner </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;ERC7144: approve from the zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>spender </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;ERC7144: approve to the zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> ApprovalValidation </span><span class="z-storage z-type">memory</span><span> v</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> v</span><span>.</span><span>owner </span><span class="z-keyword">=</span><span> owner</span><span>;</span></span> <span class="giallo-l"><span> v</span><span>.</span><span>spender </span><span class="z-keyword">=</span><span> spender</span><span>;</span></span> <span class="giallo-l"><span> v</span><span>.</span><span>amount </span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _approvalValidations</span><span>[</span><span>_totalApprovalValidations</span><span>]</span><span class="z-keyword"> =</span><span> v</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"> ValidateApproval</span><span>(</span><span>v</span><span>.</span><span>owner</span><span>,</span><span> spender</span><span>,</span><span> amount</span><span>,</span><span> _totalApprovalValidations</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _totalApprovalValidations</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></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>As is defined in the Specification the operations that change the ownership of Tokens or enable an approval to manage the Tokens SHALL create a <code>TransferValidation</code> or an <code>ApprovalValidation</code> pending to be validated and SHALL NOT transfer the Tokens or enable an approval.</p> <p>With this premise in mind, the operations in charge of validating a <code>TransferValidation</code> or an <code>ApprovalValidation</code> must be protected with the maximum security required by the applied system.</p> <p>For example, a valid system would be one where there is a validator address in charge of validating the transactions.</p> <p>To give another example, a system where each user could choose his validator address would also be correct.</p> <p>In any case, the importance of security resides in the fact that no address can validate a <code>TransferValidation</code> or an <code>ApprovalValidation</code> without the permission of the chosen system.</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-02T00:00:00+00:00 2026-02-11T14:48:26+00:00 Francesco Sullohttps://github.com/sullof Alexe Spataruhttps://github.com/urataps https://wg-eips.ritovision.com/6982/

A gas-efficient approach to lockable ERC-721 tokens

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a lockable interface for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens that optimizes gas usage by eliminating unnecessary events. This interface forms the foundation for the creation and management of lockable <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens. It provides a gas-efficient approach by emitting a <code>DefaultLocked(bool locked)</code> event upon deployment, setting the initial lock status for all tokens, while individual <code>Locked(uint256 indexed tokenId, bool locked)</code> events handle subsequent status changes for specific tokens. The interface also includes a view function <code>locked(uint256 tokenId)</code> to return the current lock status of a token, and a view function <code>defaultLocked()</code> to query the default status of a newly minted token.</p> <h2 id="motivation">Motivation</h2> <p>Existing lockable token proposals often mandate the emission of an event each time a token is minted. This results in unnecessary gas consumption, especially in cases where tokens are permanently locked from inception to destruction (e.g., soulbounds or non-transferable badges). This proposal offers a more gas-efficient solution that only emits events upon contract deployment and status changes of individual 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>The interface is defined as follows:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ERC165 interfaceId 0x6b61a747</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6982</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 be emitted when the contract is deployed to establish the default lock status </span></span> <span class="giallo-l"><span class="z-comment"> * for all tokens. Also, MUST be emitted again if the default lock status changes, </span></span> <span class="giallo-l"><span class="z-comment"> * to ensure the default status for all tokens (without a specific `Locked` event) is updated.</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"> DefaultLocked</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> locked</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 be emitted when the lock status of a specific token changes.</span></span> <span class="giallo-l"><span class="z-comment"> * This status overrides the default lock status for that specific 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"> Locked</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">bool</span><span class="z-variable"> locked</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 current default lock status for tokens. </span></span> <span class="giallo-l"><span class="z-comment"> * The returned value MUST reflect the status indicated by the most recent `DefaultLocked` 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"> defaultLocked</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the lock status of a specific token. </span></span> <span class="giallo-l"><span class="z-comment"> * If no `Locked` event has been emitted for the token, it MUST return the current default lock status. </span></span> <span class="giallo-l"><span class="z-comment"> * The function MUST revert if the 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"> locked</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 <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interfaceId is <code>0x6b61a747</code>.</p> <h2 id="rationale">Rationale</h2> <p>This standard seeks to optimize gas consumption by minimizing the frequency of event emission. The <code>DefaultLocked</code> event is designed to establish the lock status for all tokens, thereby circumventing the need to emit an event each time a new token is minted. It's crucial to note that the <code>DefaultLocked</code> event can be emitted at any point in time, and is not restricted to only before the <code>Locked</code> events are emitted.</p> <p>Tokens may alter their behavior under certain circumstances (such as after a reveal), prompting the re-emission of the <code>DefaultLocked</code> event to reflect the new default status. The primary objective here is to economize on gas usage by avoiding the need to emit a <code>Locked</code> event for each token when the default status changes.</p> <p>The <code>Locked</code> event is utilized to document changes in the lock status of individual tokens.</p> <p>The <code>defaultLocked</code> function returns the prevailing default lock status of a token. This function is beneficial as it fosters interaction with other contracts and averts potential conflicts with <a href="https://wg-eips.ritovision.com/5192/">ERC-5192</a>, which is in its final stage.</p> <p>The <code>locked</code> function gives the current lock status of a particular token, further facilitating interaction with other contracts. If no changes have been made to a specific token ID, this function should return the value provided by the <code>defaultLocked</code> function.</p> <p>Bear in mind that a token being designated as "locked" doesn't necessarily imply that it is entirely non-transferable. There might be certain conditions under which a token can still be transferred despite its locked status. Primarily, the locked status relates to a token's transferability on marketplaces and external exchanges.</p> <p>To illustrate, let's consider the Cruna protocol. In this system, an NFT owner has the ability to activate what is termed an 'protector'. This is essentially a secondary wallet with the unique privilege of initiating key transactions. Upon setting an initiator, the token's status is rendered 'locked'. However, this does not impede the token's transferability if the initiation for the transfer comes from the designated protector.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is fully backwards compatible with existing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> contracts. It can be easily integrated into existing contracts and will not cause any conflicts or disruptions.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>An example implementation is located in the <a href="https://wg-eips.ritovision.com/6982/assets/README/">assets</a>.</p> <p>It solves a specific use case: token's owners losing the ownership when staking the asset in a pool. The implementation allow the pool to lock the asset, leaving the ownership to the owner. In the <a href="https://wg-eips.ritovision.com/6982/assets/README/">README</a> you can find more details about how to compile and test the contracts.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP does not introduce any known security considerations. However, as with any smart contract standard, it is crucial to employ rigorous security measures in the implementation of 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> 2023-05-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Guanghttps://github.com/xg1990 https://wg-eips.ritovision.com/7085/

Establish relationships between NFTs and setting quantifiable attributes for those relationships.

<h2 id="abstract">Abstract</h2> <p>This proposal builds on <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> and creates a standard for referring relationships and quantifiable attributes between non-isolated <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> non-fungible tokens (NFTs). It enables users to build a graph of NFTs and set quantifiable attributes for each NFT, facilitating more complex NFT ecosystems. While a similar proposal exists for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens, it does not provide a way to establish quantifiable relationships or object attributes.</p> <h2 id="motivation">Motivation</h2> <p>The current standard for NFTs lacks the ability to establish relationships and attributes between tokens. This limitation makes it difficult for users to build more complex NFT ecosystems that require referring relationships and quantifiable attributes between tokens. For example, a user may create a derivative NFT that refers to the original NFT and sets a quantifiable attribute for the relationship between the two NFTs, but without a standardized way to establish relationships and attributes between NFTs, managing these ecosystems becomes increasingly difficult and inefficient.</p> <p>This proposal aims to address this issue by extending the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> standards to include the ability to establish referring relationships and quantifiable attributes between NFTs.</p> <p>By enabling users to build more complex NFT ecosystems, this proposal will enhance the NFT ecosystem and open up new possibilities for NFT use cases. However, it's important to consider potential drawbacks such as increased complexity and gas cost, and carefully design rules to mitigate these issues.</p> <h2 id="specification">Specification</h2> <p>This EIP proposes the addition of five new functions to the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> standards: <code>setRelationship</code>, <code>setAttribute</code>, <code>getRelationship</code>, <code>getAttribute</code>, and <code>getAttributeNames</code>. These functions allow users to establish referring relationships and set quantifiable attributes between NFTs.</p> <h3 id="setrelationship"><code>setRelationship</code></h3> <p>The <code>setRelationship</code> function establishes a referring relationship between two NFTs. It takes the following parameters:</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"> setRelationship</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _originalID</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _derivativeID</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _attribute</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <ul> <li><code>_originalID</code>: the ID of the original NFT</li> <li><code>_derivativeID</code>: the ID of the derivative NFT that refers to the original NFT</li> <li><code>_attribute</code>: the quantifiable attribute for this relationship, which defaults to 1 if not specified</li> </ul> <p>When called, this function establishes a referring relationship between the two NFTs.</p> <h3 id="setattribute"><code>setAttribute</code></h3> <p>The <code>setAttribute</code> function sets a quantifiable attribute for an NFT. It takes the following parameters:</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"> setAttribute</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"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _name</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>;</span></span></code></pre> <ul> <li><code>_id</code>: the ID of the NFT</li> <li><code>_name</code>: the name of the attribute to be set</li> <li><code>_value</code>: the value of the attribute to be set</li> </ul> <p>When called, this function sets a quantifiable attribute for the NFT.</p> <h3 id="getattribute"><code>getAttribute</code></h3> <p>The <code>getAttribute</code> function allows anyone to retrieve the value of a specific attribute associated with an NFT. It takes the following parameters:</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"> getAttribute</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"> string</span><span class="z-storage z-type"> calldata</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></code></pre> <ul> <li><code>_id</code>: The ID of the NFT for which you want to retrieve the attribute.</li> <li><code>_name</code>: The name of the attribute you wish to retrieve.</li> </ul> <p>This function returns the value of the specified attribute as a bytes32 data type.</p> <h3 id="getattributenames"><code>getAttributeNames</code></h3> <p>The getAttributeNames function allows anyone to retrieve the names of all attributes associated with an NFT. It takes the following parameter:</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"> getAttributeNames</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">bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre> <ul> <li><code>_id</code>: The ID of the NFT for which you want to retrieve the attribute names.</li> </ul> <p>This function returns an array of bytes32 values representing the names of all attributes associated with the specified NFT.</p> <h3 id="getrelationship"><code>getRelationship</code></h3> <p>The <code>getRelationship</code> function allows anyone to retrieve the value of a referring relationship between two NFTs. It takes the following parameters:</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"> getRelationship</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _originalID</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _derivativeID</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> <ul> <li><code>_originalID</code>: The ID of the original NFT.</li> <li><code>_derivativeID</code>: The ID of the derivative NFT that refers to the original NFT.</li> </ul> <p>This function returns the value of the referring relationship between the two NFTs as a uint256 data type.</p> <h3 id="example-usage">Example Usage</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>NFTGraph nftContract </span><span class="z-keyword">=</span><span class="z-entity z-name"> NFTGraph</span><span>(</span><span>addressOfContract</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Retrieve the value of an attribute named &quot;Color&quot; for NFT with ID 123</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span> colorValue </span><span class="z-keyword">=</span><span> nftContract</span><span>.</span><span class="z-entity z-name">getAttribute</span><span>(</span><span class="z-constant">123</span><span>,</span><span class="z-string"> &quot;Color&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"> Retrieve the names of all attributes associated with NFT with ID 456</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> attributeNames </span><span class="z-keyword">=</span><span> nftContract</span><span>.</span><span class="z-entity z-name">getAttributeNames</span><span>(</span><span class="z-constant">456</span><span>)</span><span>;</span></span></code></pre> <p>By including these functions and methods in the specification, you establish a clear and standardized way for users and developers to read attributes associated with NFTs.</p> <h2 id="rationale">Rationale</h2> <p>In developing this EIP, some key design decisions were made. For example, we limited the complexity of the relationship graph that can be created by only allowing for one referring relationship between two NFTs. This helps to ensure that the graph remains manageable and does not become too complex to be useful. Additionally, we kept the gas cost of setting attributes to a minimum by only allowing for one attribute to be set at a time.</p> <p>While there are currently no similar features in other blockchain languages or standards, we drew inspiration from the concept of Graph Theory, which is a branch of mathematics that studies the relationships between objects. By adding the ability to establish relationships between NFTs and set quantifiable attributes for those relationships, we believe that the extended NFT standard will become even more useful and versatile for NFT creators and users.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is designed to be fully backward-compatible with existing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> contracts and tokens. Existing NFT contracts and tokens will continue to function as they did before, and the new <code>setRelationship</code> and <code>setAttribute</code> functions will only be available to contracts that explicitly implement this EIP.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>To assist in understanding and implementing this proposal, we provide a reference Solidity interface and contract that define the functions for establishing relationships and reading attributes. Developers can use this interface as a foundation for integrating the NFT Relationship Enhancement into their own contracts.</p> <h3 id="erc-165-interface-support"><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> Interface Support</h3> <p>The NFT Relationship Enhancement contract implements the ERC-165 standard interface to allow for interface detection. This enables smart contracts and applications to check if a given contract supports the functions defined in this proposal before interacting with it.</p> <h3 id="inftgraph-interface">INFTGraph Interface</h3> <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 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/ERC165/IERC165.sol&quot;</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Import IERC165 for interface detection</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"> INFTGraph</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"> setRelationship: Establishes relationships between NFTs.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setRelationship</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _originalID</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _derivativeID</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _attribute</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"> setAttribute: Sets quantifiable attributes for NFTs.</span></span> <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-support">uint256</span><span class="z-variable z-parameter z-function"> _id</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"> _name</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>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> getRelationship: Retrieves relationship values between NFTs.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getRelationship</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _originalID</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _derivativeID</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"> getAttribute: Retrieves the value of specific attributes associated with NFTs.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAttribute</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"> string</span><span class="z-storage z-type"> calldata</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> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> getAttributeNames: Retrieves all attribute names associated with an NFT.</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 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">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></span></code></pre> <p>The INFTGraph interface specifies the functions for setting relationships and attributes, as well as retrieving attribute information and relationship values.</p> <h3 id="nftgraph-contract">NFTGraph Contract</h3> <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 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/introspection/ERC165.sol&quot;</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Import ERC165 for interface detection</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./INFTGraph.sol&quot;</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Import INFTGraph interface</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"> NFTGraph</span><span class="z-storage"> is</span><span class="z-entity z-name"> INFTGraph</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-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"> public</span><span> relationship</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-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes32</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bytes32</span><span>)</span><span>)</span><span class="z-storage z-type"> public</span><span> attributes</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Implement the setRelationship and setAttribute functions as described in the EIP specification.</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"> Implement the supportsInterface function for ERC-165.</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"> public</span><span class="z-storage z-type"> view</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>INFTGraph</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 class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Additional implementation details...</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getRelationship</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _originalID</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _derivativeID</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> relationship</span><span>[</span><span>_originalID</span><span>]</span><span>[</span><span>_derivativeID</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"> getAttribute</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"> string</span><span class="z-storage z-type"> calldata</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> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> bytes32</span><span>(</span><span>attributes</span><span>[</span><span>_id</span><span>]</span><span>[</span><span>_name</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"> getAttributeNames</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">bytes32</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"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> names </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> bytes32</span><span>[](</span><span class="z-variable">attributes</span><span>[</span><span class="z-variable z-parameter z-function">_id</span><span>]</span><span>.</span><span class="z-variable">length</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> attributes</span><span>[</span><span>_id</span><span>]</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> names</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span class="z-support"> bytes32</span><span>(</span><span>attributes</span><span>[</span><span>_id</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-keyword"> return</span><span> names</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"> setRelationship</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> originalNFT</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> derivativeNFT</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> relationshipValue</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>originalNFT </span><span class="z-keyword">!=</span><span> derivativeNFT</span><span>,</span><span class="z-string"> &quot;Original and derivative NFTs must be different&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> relationship</span><span>[</span><span>originalNFT</span><span>]</span><span>[</span><span>derivativeNFT</span><span>]</span><span class="z-keyword"> =</span><span> relationshipValue</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"> setAttribute</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> nft</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> attributeName</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> attributeValue</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> attributes</span><span>[</span><span>nft</span><span>]</span><span>[</span><span>attributeName</span><span>]</span><span class="z-keyword"> =</span><span> attributeValue</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> <p>The NFTGraph contract implements the functions specified in the INFTGraph interface and provides storage for relationships and attributes.</p> <p>Developers can use this reference interface and contract as a starting point for integrating the NFT Relationship Enhancement functionality into their own projects. The interface provides a clear and standardized way to interact with the contract, promoting consistency and ease of integration.</p> <h2 id="security-considerations">Security Considerations</h2> <p>When implementing this proposal, contract developers should consider the following security aspects:</p> <ol> <li><strong>Validation of Relationships</strong>: Contracts utilizing the setRelationship function must ensure that the relationships being established are valid and authorized by the relevant parties. Unauthorized or malicious relationships could lead to unintended consequences.</li> <li><strong>Attribute Validation</strong>: Contracts implementing the setAttribute function should carefully validate attributes to prevent malicious or harmful values. Invalid or unvalidated attributes could disrupt the functionality of the NFT ecosystem.</li> <li><strong>Access Control</strong>: Contracts should implement appropriate access control mechanisms to restrict who can call critical functions, especially those that modify relationships or attributes. Unauthorized access can lead to misuse or exploitation.</li> <li><strong>Reentrancy Protection</strong>: Consider adding reentrancy protection mechanisms to functions that modify relationships or attributes. Reentrancy attacks could otherwise be exploited to manipulate contract behavior.</li> </ol> <p>By addressing these considerations, developers can enhance the security of their contracts and protect the integrity of the NFT ecosystem.</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:28+00:00 Pedro Gomeshttps://github.com/pedrouid Kosala Hemachandrahttps://github.com/kvhnuke Richard Moorehttps://github.com/ricmoo Gregory Markouhttps://github.com/GregTheGreek Kyle Den Hartoghttps://github.com/kdenhartog Glitchhttps://github.com/glitch-txs Jake Moxeyhttps://github.com/jxom Pierre Bertethttps://github.com/bpierre Darryl Yeohttps://github.com/darrylyeo Yaroslav Sergievskyhttps://github.com/everdimension https://wg-eips.ritovision.com/6963/

Using window events to announce injected Wallet Providers

<h2 id="abstract">Abstract</h2> <p>An alternative discovery mechanism to <code>window.ethereum</code> for <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a> providers which supports discovering multiple injected Wallet Providers in a web page using Javascript's <code>window</code> events.</p> <h2 id="motivation">Motivation</h2> <p>Currently, Wallet Provider that offer browser extensions must inject their Ethereum providers (<a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a>) into the same window object <code>window.ethereum</code>; however, this creates conflicts for users that may install more than one browser extension.</p> <p>Browser extensions are loaded in the web page in an unpredictable and unstable order, resulting in a race condition where the user does not have control over which Wallet Provider is selected to expose the Ethereum interface under the <code>window.ethereum</code> object. Instead, the last wallet to load usually wins.</p> <p>This results not only in a degraded user experience but also increases the barrier to entry for new browser extensions as users are forced to only install one browser extension at a time.</p> <p>Some browser extensions attempt to counteract this problem by delaying their injection to overwrite the same <code>window.ethereum</code> object which creates an unfair competition for Wallet Providers and lack of interoperability.</p> <p>In this proposal, we present a solution that focuses on optimizing the interoperability of multiple Wallet Providers. This solution aims to foster fairer competition by reducing the barriers to entry for new Wallet Providers, along with enhancing the user experience on Ethereum networks.</p> <p>This is achieved by introducing a set of window events to provide a two-way communication protocol between Ethereum libraries and injected scripts provided by browser extensions thus enabling users to select their wallet of choice.</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.rfc-editor.org/rfc/rfc2119">RFC-2119</a>.</p> <h3 id="definitions">Definitions</h3> <p>Wallet Provider: A user agent that manages keys and facilitates transactions with Ethereum.</p> <p>Decentralized Application (DApp): A web page that relies upon one or many Web3 platform APIs which are exposed to the web page via the Wallet.</p> <p>Provider Discovery Library: A library or piece of software that assists a DApp to interact with the Wallet.</p> <h3 id="provider-info">Provider Info</h3> <p>Each Wallet Provider will be announced with the following interface <code>EIP6963ProviderInfo</code>. The values in the <code>EIP6963ProviderInfo</code> MUST be included within the <code>EIP6963ProviderInfo</code> object. The <code>EIP6963ProviderInfo</code> MAY also include extra extensible properties within the object. If a DApp does not recognize the additional properties, it SHOULD ignore them.</p> <ul> <li><strong><code>uuid</code></strong> - a globally unique identifier the Wallet Provider that MUST be (<a rel="external" href="https://www.rfc-editor.org/rfc/rfc4122">UUIDv4</a> compliant) to uniquely distinguish different <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a> provider sessions that have matching properties defined below during the lifetime of the page. The cryptographic uniqueness provided by <a rel="external" href="https://www.rfc-editor.org/rfc/rfc4122">UUIDv4</a> guarantees that two independent <code>EIP6963ProviderInfo</code> objects can be separately identified.</li> <li><strong><code>name</code></strong> - a human-readable local alias of the Wallet Provider to be displayed to the user on the DApp. (e.g. <code>Example Wallet Extension</code> or <code>Awesome Example Wallet</code>)</li> <li><strong><code>icon</code></strong> - a <a rel="external" href="https://www.rfc-editor.org/rfc/rfc3986">URI</a> pointing to an image. The image SHOULD be a square with 96x96px minimum resolution. See the <a href="https://wg-eips.ritovision.com/6963/#images-icons">Images/Icons</a> below for further requirements of this property.</li> <li><strong><code>rdns</code></strong> - The Wallet MUST supply the <code>rdns</code> property which is intended to be a domain name from the Domain Name System in reverse syntax ordering such as <code>com.example.subdomain</code>. It's up to the Wallet to determine the domain name they wish to use, but it's generally expected the identifier will remain the same throughout the development of the Wallet. It's also worth noting that similar to a user agent string in browsers, there are times where the supplied value could be unknown, invalid, incorrect, or attempt to imitate a different Wallet. Therefore, the DApp SHOULD be able to handle these failure cases with minimal degradation to the functionality of the DApp.</li> </ul> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * Represents the assets needed to display a wallet</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">interface</span><span class="z-entity z-name"> EIP6963ProviderInfo</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> uuid</span><span class="z-keyword">:</span><span class="z-support"> string</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 class="z-variable"> rdns</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="images-icons">Images/Icons</h4> <p>A URI-encoded image was chosen to enable flexibility for multiple protocols for fetching and rendering icons, for example:</p> <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"> svg (data uri)</span></span> <span class="giallo-l"><span class="z-entity z-name">data:image/svg+xml,</span><span>&lt;svg</span><span class="z-string"> version=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">1.1</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string"> xmlns=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">http://www.w3.org/2000/svg</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string"> width=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">32px</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string"> height=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">32px</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string"> viewBox=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0 0 32 32</span><span class="z-punctuation z-definition z-string">&quot;</span><span>&gt;&lt;</span><span class="z-string">circle</span><span class="z-string"> fill=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">red</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string"> cx=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">16</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string"> cy=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">16</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string"> r=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">12</span><span class="z-punctuation z-definition z-string">&quot;</span><span>/&gt;&lt;</span><span class="z-string">/sv</span><span>g</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"> png (data uri)</span></span> <span class="giallo-l"><span class="z-entity z-name">data:image/png</span><span>;</span><span class="z-entity z-name">base64,iVBORw0KGgoAAAANSUhEUgAAAAUAAAAFCAYAAACNbyblAAAAHElEQVQI12P4//8/w38GIAXDIBKE0DHxgljNBAAO9TXL0Y4OHwAAAABJRU5ErkJggg</span><span class="z-string">=</span><span class="z-string">=</span></span></code></pre> <p>The <code>icon</code> string MUST be a data URI as defined in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2397">RFC-2397</a>. The image SHOULD be a square with 96x96px minimum resolution. The image format is RECOMMENDED to be either lossless or vector based such as PNG, WebP or SVG to make the image easy to render on the DApp. Since SVG images can execute Javascript, applications and libraries MUST render SVG images using the <code>&lt;img&gt;</code> tag to ensure no untrusted Javascript execution can occur.</p> <h4 id="rdns">RDNS</h4> <p>The <strong><code>rdns</code></strong> (Reverse-DNS) property serves to provide an identifier which DApps can rely on to be stable between sessions. The Reverse Domain Name Notation is chosen to prevent namespace collisions. The Reverse-DNS convention implies that the value should start with a reversed DNS domain name controlled by the Provider. The domain name should be followed by a subdomain or a product name. Example: <code>com.example.MyBrowserWallet</code>.</p> <ul> <li>The <code>rdns</code> value MUST BE a valid <a rel="external" href="https://www.rfc-editor.org/rfc/rfc1034">RFC-1034</a> Domain Name;</li> <li>The DNS part of the <code>rdns</code> value SHOULD BE an active domain controlled by the Provider;</li> <li>DApps MAY reject the Providers which do not follow the Reverse-DNS convention correctly;</li> <li>DApps SHOULD NOT use the <code>rnds</code> value for feature detection as these are self-attested and prone to impersonation or bad incentives without an additional verification mechanism; feature-discovery and verification are both out of scope of this interface specification.</li> </ul> <h3 id="provider-detail">Provider Detail</h3> <p>The <code>EIP6963ProviderDetail</code> is used as a composition interface to announce a Wallet Provider and related metadata about the Wallet Provider. The <code>EIP6963ProviderDetail</code> MUST contain an <code>info</code> property of type <code>EIP6963ProviderInfo</code> and a <code>provider</code> property of type <code>EIP1193Provider</code> defined by <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a>.</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"> EIP6963ProviderDetail</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> info</span><span class="z-keyword">:</span><span class="z-entity z-name"> EIP6963ProviderInfo</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> provider</span><span class="z-keyword">:</span><span class="z-entity z-name"> EIP1193Provider</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="window-events">Window Events</h3> <p>In order to prevent provider collisions, the DApp and the Wallet are expected to emit an event and instantiate an eventListener to discover the various Wallets. This forms an Event concurrency loop.</p> <p>Since the DApp code and Wallet code aren't guaranteed to run in a particular order, the events are designed to handle such race conditions.</p> <p>To emit events, both DApps and Wallets MUST use the <code>window.dispatchEvent</code> function to emit events and MUST use the <code>window.addEventListener</code> function to observe events. There are two Event interfaces used for the DApp and Wallet to discover each other.</p> <h4 id="announce-and-request-events">Announce and Request Events</h4> <p>The <code>EIP6963AnnounceProviderEvent</code> interface MUST be a <code>CustomEvent</code> object with a <code>type</code> property containing a string value of <code>eip6963:announceProvider</code> and a <code>detail</code> property with an object value of type <code>EIP6963ProviderDetail</code>. The <code>EIP6963ProviderDetail</code> object SHOULD be frozen by calling <code>Object.freeze()</code> on the value of the <code>detail</code> property.</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Announce Event dispatched by a Wallet</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> EIP6963AnnounceProviderEvent</span><span class="z-storage"> extends</span><span class="z-entity"> CustomEvent</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eip6963:announceProvider</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> detail</span><span class="z-keyword">:</span><span class="z-entity z-name"> EIP6963ProviderDetail</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>EIP6963RequestProviderEvent</code> interface MUST be an <code>Event</code> object with a <code>type</code> property containing a string value of <code>eip6963:requestProvider</code>.</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Request Event dispatched by a DApp</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> EIP6963RequestProviderEvent</span><span class="z-storage"> extends</span><span class="z-entity"> Event</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eip6963:requestProvider</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The Wallet MUST announce the <code>EIP6963AnnounceProviderEvent</code> to the DApp via a <code>window.dispatchEvent()</code> function call. The Wallet MUST add an EventListener to catch an <code>EIP6963RequestProviderEvent</code> dispatched from the DApp. This EventListener MUST use a handler that will re-dispatch an <code>EIP6963AnnounceProviderEvent</code>. This re-announcement by the Wallet is useful for when a Wallet's initial Event announcement may have been delayed or fired before the DApp had initialized its EventListener. This allows the various Wallet Providers to react to the DApp without the need to pollute the <code>window.ethereum</code> namespace which can produce non-deterministic wallet behavior such as different wallets connecting each time.</p> <p>The Wallet dispatches the <code>"eip6963:announceProvider"</code> event with immutable contents and listens to the <code>"eip6963:requestProvider"</code> event:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage z-type">let</span><span class="z-variable z-other"> info</span><span class="z-keyword">:</span><span class="z-entity z-name"> EIP6963ProviderInfo</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">let</span><span class="z-variable z-other"> provider</span><span class="z-keyword">:</span><span class="z-entity z-name"> EIP1193Provider</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"> announceEvent</span><span class="z-keyword">:</span><span class="z-entity z-name"> EIP6963AnnounceProviderEvent</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-entity z-name"> CustomEvent</span><span>(</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eip6963:announceProvider</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> {</span><span> detail</span><span>:</span><span class="z-variable z-other"> Object</span><span>.</span><span class="z-entity z-name">freeze</span><span>(</span><span>{</span><span class="z-variable z-other"> info</span><span>,</span><span class="z-variable z-other"> provider</span><span> }</span><span>)</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-punctuation z-definition z-comment">//</span><span class="z-comment"> The Wallet dispatches an announce event which is heard by</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> the DApp code that had run earlier</span></span> <span class="giallo-l"><span class="z-variable z-other">window</span><span>.</span><span class="z-entity z-name">dispatchEvent</span><span>(</span><span class="z-variable z-other">announceEvent</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 Wallet listens to the request events which may be</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> dispatched later and re-dispatches the `EIP6963AnnounceProviderEvent`</span></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">eip6963:requestProvider</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</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"> window</span><span>.</span><span class="z-entity z-name">dispatchEvent</span><span>(</span><span class="z-variable z-other">announceEvent</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>)</span><span>;</span></span></code></pre> <p>The DApp MUST listen for the <code>EIP6963AnnounceProviderEvent</code> dispatched by the Wallet via a <code>window.addEventListener()</code> method and MUST NOT remove the Event Listener for the lifetime of the page so that the DApp can continue to handle Events beyond the initial page load interaction. The DApp MUST dispatch the <code>EIP6963RequestProviderEvent</code> via a <code>window.dispatchEvent()</code> function call after the <code>EIP6963AnnounceProviderEvent</code> handler has been initialized.</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> The DApp listens to announced providers</span></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> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eip6963:announceProvider</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> (</span><span class="z-variable">event</span><span class="z-keyword">:</span><span class="z-entity z-name"> EIP6963AnnounceProviderEvent</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span> {</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-punctuation z-definition z-comment">//</span><span class="z-comment"> The DApp dispatches a request event which will be heard by </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Wallets&#39; code that had run earlier</span></span> <span class="giallo-l"><span class="z-variable z-other">window</span><span>.</span><span class="z-entity z-name">dispatchEvent</span><span>(</span><span class="z-keyword">new</span><span class="z-entity z-name"> Event</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eip6963:requestProvider</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>)</span><span>;</span></span></code></pre> <p>The DApp MAY elect to persist various <code>EIP6963ProviderDetail</code> objects contained in the announcement events sent by multiple wallets. Thus, if the user wishes to utilize a different Wallet over time, the user can express this within the DApp's interface and the DApp can immediately elect to send transactions to that new Wallet. Otherwise, the DApp MAY re-initiate the wallet discovery flow via dispatching a new <code>EIP6963RequestProviderEvent</code>, potentially discovering a different set of wallets.</p> <p>The described orchestration of events guarantees that the DApp is able to discover the Wallet, regardless of which code executes first, the Wallet code or the DApp code.</p> <h2 id="rationale">Rationale</h2> <p>The previous proposal introduced mechanisms that relied on a single, mutable window object that could be overwritten by multiple parties. We opted for an event-based approach to avoid the race conditions, the namespace collisions, and the potential for "pollution" attacks on a shared mutable object; the event-based orchestration creates a bidirectional communication channel between wallet and dapp that can be re-orchestrated over time.</p> <p>To follow the Javascript event name conventions, the names are written in present tense and are prefixed with the number of this document (<code>EIP6963</code>).</p> <h3 id="interfaces">Interfaces</h3> <p>Standardizing an interface for provider information (<code>EIP6963ProviderInfo</code>) allows a DApp to determine all information necessary to populate a user-friendly wallet selection modal. This is particularly useful for DApps that rely on libraries such as Web3Modal, RainbowKit, Web3-Onboard, or ConnectKit to programmatically generate such selection modals.</p> <p>Regarding the announced provider interface (<code>EIP6963ProviderDetail</code>), it was important to leave the <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a> provider interface untouched for backwards compatibility; this allows conformant DApps to interface with wallets conforming to either, and for Wallets conformant to this spec to still inject <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a> providers for legacy DApps. Note that a legacy dapp or a DApp conformant with this spec connecting to a legacy wallet cannot guarantee the correct wallet will be selected if multiple are present.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP doesn't require supplanting <code>window.ethereum</code>, so it doesn't directly break existing applications that cannot update to this method of Wallet discovery. However, it is RECOMMENDED DApps implement this EIP to ensure discovery of multiple Wallet Providers and SHOULD disable <code>window.ethereum</code> usage except as a fail-over when discovery fails. Similarly, Wallets SHOULD keep compatibility of <code>window.ethereum</code> to ensure backwards compatibility for DApps that have not implemented this EIP. In order to prevent the previous issues of namespace collisions, it's also RECOMMENDED that wallets inject their provider object under a wallet specific namespace then proxy the object into the <code>window.ethereum</code> namespace.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="wallet-provider">Wallet Provider</h3> <p>Here is a reference implementation for an injected script by a Wallet Provider to support this new interface in parallel with the existing pattern.</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> onPageLoad</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"> provider</span><span class="z-keyword">:</span><span class="z-entity z-name"> EIP1193Provider</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">ethereum</span><span class="z-keyword"> =</span><span class="z-variable z-other"> provider</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"> announceProvider</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"> info</span><span class="z-keyword">:</span><span class="z-entity z-name"> EIP6963ProviderInfo</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span> uuid</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">350670db-19fa-4704-a166-e52e178b59d2</span><span class="z-punctuation z-definition z-string">&quot;</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">Example Wallet</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> icon</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">data:image/svg+xml,&lt;svg xmlns=&#39;http://www.w3.org/2000/svg&#39;/&gt;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> rdns</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">com.example.wallet</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"> window</span><span>.</span><span class="z-entity z-name">dispatchEvent</span><span>(</span></span> <span class="giallo-l"><span class="z-keyword"> new</span><span class="z-entity z-name"> CustomEvent</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eip6963:announceProvider</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> {</span></span> <span class="giallo-l"><span> detail</span><span>:</span><span class="z-variable z-other"> Object</span><span>.</span><span class="z-entity z-name">freeze</span><span>(</span><span>{</span><span class="z-variable z-other"> info</span><span>,</span><span class="z-variable z-other"> provider</span><span> }</span><span>)</span><span>,</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> }</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> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eip6963:requestProvider</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> (</span><span class="z-variable">event</span><span class="z-keyword">:</span><span class="z-entity z-name"> EIP6963RequestProviderEvent</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> announceProvider</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 class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> announceProvider</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="dapp-implementation">DApp implementation</h3> <p>Here is a reference implementation for a DApp to display and track multiple Wallet Providers that are injected by browser extensions.</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"> providers</span><span class="z-keyword">:</span><span class="z-entity z-name"> EIP6963ProviderDetail</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"> onPageLoad</span><span>(</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> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eip6963:announceProvider</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> (</span><span class="z-variable">event</span><span class="z-keyword">:</span><span class="z-entity z-name"> EIP6963AnnounceProviderEvent</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> providers</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-variable z-other">event</span><span>.</span><span class="z-variable z-other">detail</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-variable z-other"> window</span><span>.</span><span class="z-entity z-name">dispatchEvent</span><span>(</span><span class="z-keyword">new</span><span class="z-entity z-name"> Event</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eip6963:requestProvider</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><h2 id="security-considerations">Security Considerations</h2> <h3 id="eip-1193-security-considerations">EIP-1193 Security considerations</h3> <p>The security considerations of <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a> apply to this EIP. Implementers are expected to consider and follow the guidance of the providers they're utilizing as well.</p> <h3 id="prototype-pollution-of-wallet-provider-objects">Prototype Pollution of Wallet Provider objects</h3> <p>Browser extensions, and therefore Wallet extensions, are able to modify the contents of the page and the Provider object by design. The provider objects of various Wallets are considered a highly trusted interface to communicate transaction data. In order to prevent the page or various other extensions from modifying the interaction between the DApp and the Wallet in an unexpected way, the best practice is to "freeze" the provider discovery object by utilizing <code>object.freeze()</code> on the <code>EIP1193Provider</code> object before the wallet dispatches it in the <code>eip6963:announceProvider</code> Event. However, there are difficulties that can occur around web compatibility where pages need to monkey patch the object. In scenarios like this there's a tradeoff that needs to be made between security and web compatibility that Wallet implementers are expected to consider.</p> <h3 id="wallet-imitation-and-manipulation">Wallet Imitation and Manipulation</h3> <p>Similarly so, DApps are expected to actively detect for misbehavior of properties or functions being modified in order to tamper with or modify other wallets. One way this can be easily achieved is to look for when the <code>uuid</code> property within two <code>EIP6963ProviderInfo</code> objects match. DApps and DApp discovery libraries are expected to consider other potential methods that the <code>EIP6963ProviderInfo</code> objects are being tampered with and consider additional mitigation techniques to prevent this as well in order to protect the user.</p> <h3 id="prevent-svg-javascript-execution">Prevent SVG Javascript Execution</h3> <p>The use of SVG images introduces a cross-site scripting risk as they can include JavaScript code. This Javascript executes within the context of the page and can therefore modify the page or the contents of the page. So when considering the experience of rendering the icons, DApps need to take into consideration how they'll approach handling these concerns in order to prevent an image being used as an obfuscation technique to hide malicious modifications to the page or to other wallets.</p> <h3 id="prevent-wallet-fingerprinting">Prevent Wallet Fingerprinting</h3> <p>One advantage to the concurrency Event loop utilized by this design is that it operates in a manner where either the DApp or the Wallet can initiate the flow to announce a provider. For this reason, Wallet implementers can now consider whether or not they wish to announce themselves to all pages or attempt alternative means in order to reduce the ability for a user to be fingerprinted by the injection of the <code>window.ethereum</code> object. Some examples, of alternative flows to consider would be to wait to inject the provider object until the DApp has announced the <code>eip6963:requestProvider</code>. At that point, the wallet can initiate a UI consent flow to ask the user if they would like to share their wallet address. This allows for the Wallet to enable the option of a "private connect" feature. However, if this approach is taken, Wallets must also consider how they intend to support backwards compatibility with a DApp that does not support 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> 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-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 Adam Boudjemaahttps://github.com/aboudjem Mohamad Hammoudhttps://github.com/mohamadhammoud Nawar Hissohttps://github.com/nawar-hisso Khawla Hassanhttps://github.com/khawlahssn Mohammad Zakeri Radhttps://github.com/zakrad Ashish Soodsoodgen@gmail.com https://wg-eips.ritovision.com/6960/

Token with a two-level classification system using mainId and subId

<h2 id="abstract">Abstract</h2> <p>The dual-layer token combines the functionalities of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> while adding a classification layer that uses <code>mainId</code> as the main asset type identifier and <code>subId</code> as the unique attributes or variations of the main asset. <img src="https://wg-eips.ritovision.com/6960/./assets/eip-6960-dual-layer-token-dlt.png" alt="Dual Layer Token" /></p> <p>The proposed token aims to offer more granularity in token management, facilitating a well-organized token ecosystem and simplifying the process of tracking tokens within a contract. This standard is particularly useful for tokenizing and enabling the fractional ownership of Real World Assets (RWAs). It also allows for efficient and flexible management of both fungible and non-fungible assets.</p> <p>The following are examples of assets that the DLT standard can represent fractional ownership of:</p> <ul> <li>Invoices</li> <li>Company stocks</li> <li>Digital collectibles</li> <li>Real estate</li> </ul> <h2 id="motivation">Motivation</h2> <p>The <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> standard has experienced considerable adoption within the Ethereum ecosystem; however, its design exhibits constraints when handling tokens with multiple classifications, particularly in relation to Real World Assets (RWAs) and fractionalization of assets.</p> <p>This EIP strives to overcome this limitation by proposing a token standard incorporating a dual-layer classification system, allowing for enhanced organization and management of tokens, especially in situations where additional sub-categorization of token types is necessary.</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="dlt-interface">DLT Interface</h3> <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.17</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"> DLT token standard interface</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 any contract that wants to implement the DLT standard</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"> IDLT</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 `subId` token is transferred from `sender` to `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"> sender</span><span class="z-comment"> is the address of the previous holder whose balance is decreased</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> recipient</span><span class="z-comment"> is the address of the new holder whose balance is increased</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> mainId</span><span class="z-comment"> is the main token type ID to be transferred</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> subId</span><span class="z-comment"> is the token subtype ID to be transferred</span></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"> is the amount to be transferred of the token subtype</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> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> sender</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"> recipient</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"> mainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> subId</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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST emit when `subIds` token array is transferred from `sender` to `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"> sender</span><span class="z-comment"> is the address of the previous holder whose balance is decreased</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> recipient</span><span class="z-comment"> is the address of the new holder whose balance is increased</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> mainIds</span><span class="z-comment"> is the main token type ID array to be transferred</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> subIds</span><span class="z-comment"> is the token subtype ID array to be transferred</span></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"> is the amount array to be transferred of the token subtype </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"> TransferBatch</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"> sender</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"> recipient</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> mainIds</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> subIds</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> amounts</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"> MUST emit when `owner` enables `operator` to manage the `subId` 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"> is the address of the 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"> operator</span><span class="z-comment"> is the authorized address to manage the allocated amount for an 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"> mainId</span><span class="z-comment"> is the main token type ID to be approved</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> subId</span><span class="z-comment"> is the token subtype ID to be approved</span></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"> is the amount to be approved of the token subtype</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> <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"> operator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> mainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> subId</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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST emit when `owner` enables or disables (`approved`) `operator` to manage all of its assets</span></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"> is the address of the 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"> operator</span><span class="z-comment"> is the authorized address to manage all tokens for an 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"> 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"> event</span><span class="z-entity z-name"> ApprovalForAll</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"> 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 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 the URI is updated for a main token type ID.</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 to a JSON file that conforms to the &quot;DLT Metadata URI JSON Schema&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"> oldValue</span><span class="z-comment"> is the old URI 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"> newValue</span><span class="z-comment"> is the new URI 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"> mainId</span><span class="z-comment"> is the main token type 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"> URI</span><span>(</span><span class="z-support">string</span><span class="z-variable"> oldValue</span><span>, </span><span class="z-support">string</span><span class="z-variable"> newValue</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> mainId</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"> Approve or remove `operator` as an operator for the caller.</span></span> <span class="giallo-l"><span class="z-comment"> * Operators can call {transferFrom} or {safeTransferFrom} for any subId owned by the caller.</span></span> <span class="giallo-l"><span class="z-comment"> * The `operator` MUST NOT be the caller.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit an {ApprovalForAll} 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"> operator</span><span class="z-comment"> is the authorized address to manage all tokens for an 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"> 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"> 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"> 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"> Moves `amount` tokens from `sender` to `recipient` using the</span></span> <span class="giallo-l"><span class="z-comment"> * allowance mechanism. `amount` is then deducted from the caller&#39;s</span></span> <span class="giallo-l"><span class="z-comment"> * allowance.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if `sender` or `recipient` is the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if balance of holder for token `subId` is lower than the `amount` sent.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit a {Transfer} 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"> sender</span><span class="z-comment"> is the address of the previous holder whose balance is decreased</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> recipient</span><span class="z-comment"> is the address of the new holder whose balance is increased</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> mainId</span><span class="z-comment"> is the main token type ID to be transferred</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> subId</span><span class="z-comment"> is the token subtype ID to be transferred</span></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"> is the amount to be transferred of the token subtype</span></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"> is additional data with no specified format</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 operation succeeded, false if operation failed</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"> safeTransferFrom</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</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"> mainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> subId</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"> 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-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"> Sets `amount` as the allowance of `spender` over the caller&#39;s tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * The `operator` MUST NOT be the caller.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if `operator` is the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit an {Approval} 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"> operator</span><span class="z-comment"> is the authorized address to manage tokens for an 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"> mainId</span><span class="z-comment"> is the main token type ID to be approved</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> subId</span><span class="z-comment"> is the token subtype ID to be approved</span></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"> is the amount to be approved of the token subtype</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 operation succeeded, false if operation failed</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> <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"> mainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> subId</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"> Get the token with a particular subId balance of an `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"> is the address of the token 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"> mainId</span><span class="z-comment"> is the main token type 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"> subId</span><span class="z-comment"> is the token subtype 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"> The</span><span class="z-comment"> amount of tokens owned by `account` in subId</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"> subBalanceOf</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"> mainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> subId</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"> Get the tokens with a particular subIds balance of an `accounts` 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"> accounts</span><span class="z-comment"> is the address array of the token 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"> mainIds</span><span class="z-comment"> is the main token type ID 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"> subIds</span><span class="z-comment"> is the token subtype ID 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"> amount of tokens owned by `accounts` in subIds</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"> balanceOfBatch</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"> accounts</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"> mainIds</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"> subIds</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 class="z-storage z-type"> calldata</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"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get the allowance allocated to an `operator`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This value changes when {approve} or {transferFrom} are called</span></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"> is the address of the 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"> operator</span><span class="z-comment"> is the authorized address to manage assets for an 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"> mainId</span><span class="z-comment"> is the main token type 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"> subId</span><span class="z-comment"> is the token subtype 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"> The</span><span class="z-comment"> remaining number of tokens that `operator` will be</span></span> <span class="giallo-l"><span class="z-comment"> * allowed to spend on behalf of `owner` through {transferFrom}. This is</span></span> <span class="giallo-l"><span class="z-comment"> * zero by 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"> allowance</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"> 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"> mainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> subId</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"> Get the approval status of an `operator` to manage assets</span></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"> is the address of the 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"> operator</span><span class="z-comment"> is the authorized address to manage assets for an owner 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 `operator` is allowed to manage all of the assets of `owner`, false if approval is revoked</span></span> <span class="giallo-l"><span class="z-comment"> * See {setApprovalForAll}</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"> isApprovedForAll</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"> address</span><span class="z-variable"> operator</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></span></code></pre><h3 id="dltreceiver-interface"><code>DLTReceiver</code> Interface</h3> <p>Smart contracts MUST implement all the functions in the <code>DLTReceiver</code> interface to accept transfers.</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.17</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"> DLT token receiver interface</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 any contract that wants to support safeTransfers</span></span> <span class="giallo-l"><span class="z-comment"> * from DLT asset contracts.</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"> IDLTReceiver</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"> Handle the receipt of a single DLT token type.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Whenever an {DLT} `subId` token is transferred to this contract via {IDLT-safeTransferFrom}</span></span> <span class="giallo-l"><span class="z-comment"> * by `operator` from `sender`, this function is called.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return its Solidity selector to confirm the token transfer.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if any other value is returned or the interface is not implemented by the recipient.</span></span> <span class="giallo-l"><span class="z-comment"> * The selector can be obtained in Solidity with `IDLTReceiver.onDLTReceived.selector`.</span></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"> is the address which initiated the 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"> from</span><span class="z-comment"> is the address which previously owned 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"> mainId</span><span class="z-comment"> is the main token type ID being transferred</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> subId</span><span class="z-comment"> subId is the token subtype ID being transferred</span></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"> is the amount of tokens being transferred</span></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"> is additional data with no specified format</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-comment"> `IDLTReceiver.onDLTReceived.selector`</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"> onDLTReceived</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-variable"> from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> mainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> subId</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"> 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-keyword"> returns</span><span> (</span><span class="z-support">bytes4</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"> Handle the receipts of a DLT token type array.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Whenever an {DLT} `subIds` token is transferred to this contract via {IDLT-safeTransferFrom}</span></span> <span class="giallo-l"><span class="z-comment"> * by `operator` from `sender`, this function is called.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return its Solidity selector to confirm the token transfers.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if any other value is returned or the interface is not implemented by the recipient.</span></span> <span class="giallo-l"><span class="z-comment"> * The selector can be obtained in Solidity with `IDLTReceiver.onDLTReceived.selector`.</span></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"> is the address which initiated the 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"> from</span><span class="z-comment"> is the address which previously owned 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"> mainIds</span><span class="z-comment"> is the main token type ID being transferred</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> subIds</span><span class="z-comment"> subId is the token subtype ID being transferred</span></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"> is the amount of tokens being transferred</span></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"> is additional data with no specified format</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-comment"> `IDLTReceiver.onDLTReceived.selector`</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"> onDLTBatchReceived</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-variable"> from</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"> mainIds</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"> subIds</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></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-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>The two-level classification system introduced in this EIP allows for a more organized token ecosystem, enabling users to manage and track tokens with greater granularity. It is particularly useful for projects that require token classifications beyond the capabilities of the current ERC-1155 standard.</p> <p>As assets can have various properties or variations, our smart contract design reflects this by assigning a mainId to each asset category and a unique subId to each derivative or sub-category. This approach expands the capabilities of ERC-1155 to support a broader range of assets with complex requirements. Additionally, it enables tracking of mainBalance for the main asset and subBalance for its sub-assets individual accounts.</p> <p>The contract can be extended to support the use of subIds in two ways:</p> <ul> <li>Shared SubIds: where all mainIds share the same set of subIds.</li> <li>Mixed SubIds: where mainIds have unique sets of subIds.</li> </ul> <p>DLT provides a more versatile solution compared to other token standards such as ERC-20, ERC-721, and ERC-1155 by effectively managing both fungible and non-fungible assets within the same contract.</p> <p>The following are questions that we considered during the design process:</p> <ul> <li>How to name the proposal? The standard introduces a two-level classification to tokens where one main asset (layer 1) can be further sub-divided into several sub-assets (layer 2) hence we decided to name it as "Dual-layer" token to reflect the hierarchical structure of the token classification.</li> <li>Should we limit the classification to two levels? The standard’s implementation maintains a mapping to track the total supply of each sub-asset. If we allow sub-assets to have their own children, it would be necessary to introduce additional methods to track each sub-asset, which would be impractical and increases the complexity of the contract.</li> <li>Should we extend the ERC-1155 standard? As the ERC-1155 standard is not designed to support a layered classification and requires significant modifications to do so, we concluded that it would not be appropriate to extend it for the dual-layer token standard. Hence, a standalone implementation would be a more suitable approach.</li> </ul> <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> <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-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Thomas Bergmuellerhttps://github.com/tbergmueller Lukas Meyerhttps://github.com/ibex-technology https://wg-eips.ritovision.com/6956/

Asset-bound NFTs anchor a token 1-1 to an asset and operations are authorized through oracle-attestation of control over the asset

<h2 id="abstract">Abstract</h2> <p>This standard allows integrating physical and digital ASSETS without signing capabilities into dApps/web3 by extending <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>.</p> <p>An ASSET, for example a physical object, is marked with a uniquely identifiable ANCHOR. The ANCHOR is bound in a secure and inseparable manner 1:1 to an NFT on-chain - over the complete life cycle of the ASSET.</p> <p>Through an ATTESTATION, an ORACLE testifies that a particular ASSET associated with an ANCHOR has been CONTROLLED when defining the <code>to</code>-address for certain operations (mint, transfer, burn, approve, ...). The ORACLE signs the ATTESTATION off-chain. The operations are authorized through verifying on-chain that ATTESTATION has been signed by a trusted ORACLE. Note that authorization is solely provided through the ATTESTATION, or in other words, through PROOF-OF-CONTROL over the ASSET. The controller of the ASSET is guaranteed to be the controller of the Asset-Bound NFT.</p> <p>The proposed ATTESTATION-authorized operations such as <code>transferAnchor(attestation)</code> are permissionless, meaning neither the current owner (<code>from</code>-address) nor the receiver (<code>to</code>-address) need to sign.</p> <p>Figure 1 shows the data flow of an ASSET-BOUND NFT transfer. The simplified system is utilizing a smartphone as user-device to interact with a physical ASSET and specify the <code>to</code>-address.</p> <p><img src="https://wg-eips.ritovision.com/6956/./assets/img/erc6956_concept.svg" alt="Figure 1: Sample system" /></p> <h2 id="motivation">Motivation</h2> <p>The well-known <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> establishes that NFTs may represent "ownership over physical properties [...] as well as digital collectables and even more abstract things such as responsibilities" - in a broader sense, we will refer to all those things as ASSETS, which typically have value to people.</p> <h3 id="the-problem">The Problem</h3> <p>ERC-721 outlines that "NFTs can represent ownership over digital or physical assets". ERC-721 excels in this task when used to represent ownership over digital, on-chain assets, that is when the asset is "holding a token of a specific contract" or the asset is an NFT's metadata. Today, people commonly treat an NFT's metadata (images, traits, ...) as asset-class, with their rarity often directly defining the value of an individual NFT.</p> <p>However, we see integrity issues not solvable with ERC-721, primarily when NFTS are used to represent off-chain ASSETS ("ownership over physical products", "digital collectables", "in-game assets", "responsibilities", ...). Over an ASSET's lifecycle, the ASSET's ownership and possession state changes multiple, sometimes thousands, of times. Each of those state changes may result in shifting obligations and privileges for the involved parties. Therefore tokenization of an ASSET <em>without</em> enforcably anchoring the ASSET's associated obligation and properties to the token is not complete. Nowadays, off-chain ASSETs are often "anchored" through adding an ASSET-identifier to a NFT's metadata.</p> <p><strong>NFT-ASSET integrity:</strong> Contrary to a popular belief among NFT-investors, metadata is data that is, more often than not, mutable and off-chain. Therefore the link between an ASSET through an asset-identifier stored in mutable metadata, which is only linked to the NFT through tokenURI, can be considered weak at best.</p> <p>Approaches to ensure integrity between metadata (=reference to ASSET) and a token exist. This is most commonly achieved by storing metadata-hashes onchain. Additional problems arise through hashing; For many applications, metadata (besides the asset-identifier) should be update-able. Therefore making metadata immutable through storing a hash is problematic. Further the offchain metadata-resource specified via tokenURI must be made available until eternity, which has historically been subject to failure (IPFS bucket disappears, central tokenURI-provider has downtimes, ...)</p> <p><strong>Off-chain-on-chain-integrity:</strong> There are approaches where off-chain ASSET ownership is enforced or conditioned through having ownership over the on-chain representation. A common approach is to burn tokens in order to get the (physical) ASSET, as the integrity cannot be maintained. However, there are no approaches known, where on-chain ownership is enforced through having off-chain ownership of the ASSET. Especially when the current owner of an NFT is incooperative or incapacitated, integrity typically fail due to lack of signing-power from the current NFT owner.</p> <p>Metadata is off-chain. The majority of implementations completely neglect that metadata is mutable. More serious implementations strive to preserve integrity by for example hashing metadata and storing the hash mapped to the tokenId on-chain. However, this approach does not allow for use-case, where metadata besides the asset-identifier, for example traits, "hours played", ... shall be mutable or evolvable.</p> <h3 id="asset-bound-non-fungible-tokens">ASSET-BOUND NON-FUNGIBLE TOKENS</h3> <p>In this standard we propose to</p> <ol> <li>Elevate the concept of representing physical or digital off-chain ASSETS by on-chain ANCHORING the ASSET inseperably into an NFT.</li> <li>Being off-chain in control over the ASSET must mean being on-chain in control over the anchored NFT.</li> <li>(Related) A change in off-chain ownership over the ASSET inevitably should be reflected by a change in on-chain ownership over the anchored NFT, even if the current owner is uncooperative or incapacitated.</li> </ol> <p>As 2. and 3. indicate, the control/ownership/possession of the ASSET should be the single source of truth, <em>not</em> the possession of an NFT. Hence, we propose an ASSET-BOUND NFT, where off-chain CONTROL over the ASSET enforces on-chain CONTROL over the anchored NFT. Also the proposed ASSET-BOUND NFTs allow to anchor digital metadata inseperably to the ASSET. When the ASSET is a physical asset, this allows to design "phygitals" in their purest form, namely creating a "phygital" asset with a physical and digital component that are inseparable. Note that metadata itself can still change, for instance for "Evolvable NFT".</p> <p>We propose to complement the existing transfer control mechanisms of a token according to <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> by another mechanism; ATTESTATION. An ATTESTATION is signed off-chain by the ORACLE and must only be issued when the ORACLE verified that whoever specifies the <code>to</code> address or beneficiary address has simultaneously been in control over the ASSET. The <code>to</code> address of an attestation may be used for Transfers as well as for approvals and other authorizations.</p> <p>Transactions authorized via ATTESTATION shall not require signature or approval from neither the <code>from</code> (donor, owner, sender) nor <code>to</code> (beneficiary, receiver) account, namely making transfers permissionless. Ideally, transaction are signed independent from the ORACLE as well, allowing different scenarios in terms of gas-fees.</p> <p>Lastly we want to mention two major side-benefits of using the proposed standard, which drastically lowers hurdles in onboarding web2 users and increase their security;</p> <ul> <li>New users, e.g <code>0xaa...aa</code> (Fig.1), can use gasless wallets, hence participate in Web3/dApps/DeFi and mint+transfer tokens without ever owning crypto currency. Gas-fees may be paid through a third-party account <code>0x..gasPayer</code> (Fig.1). The gas is typically covered by the ASSET issuer, who signs <code>transferAnchor()</code> transactions</li> <li>Users cannot get scammed. Common attacks (for example wallet-drainer scams) are no longer possible or easily reverted, since only the anchored NFT can be stolen, not the ASSET itself. Also mishaps like transferring the NFT to the wrong account, losing access to an account etc can be mitigated by executing another <code>transferAnchor()</code> transaction based on proofing control over the ASSET, namely the physical object.</li> </ul> <h3 id="related-work">Related work</h3> <p>We primarily aim to onboard physical or digital ASSETS into dApps, which do not signing-capabilities of their own (contrary to other proposals relying on crypto-chips). Note that we do not see any restrictions preventing to use such solutions in combination with this standard, as the address of the crypto-chip qualifies as an ANCHOR.</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="definitions-alphabetical">Definitions (alphabetical)</h3> <ul> <li> <p><strong>ANCHOR</strong> uniquely identifies the off-chain ASSET, whether it is physical or digital.</p> </li> <li> <p><strong>ANCHOR-TECHNOLOGY</strong> MUST ensure that</p> <ul> <li>the ANCHOR is inseparable from the ASSET (physically or otherwise)</li> <li>an ORACLE can establish PROOF-OF-CONTROL over the ASSET beyond reasonable doubt</li> <li>For physical ASSETS, additional <a href="https://wg-eips.ritovision.com/6956/#security-considerations-for-physical-assets">Security considerations for Physical Assets</a> MUST be taken into account</li> </ul> </li> <li> <p><strong>ASSET</strong> refers to the "thing", being it physical or digital, which is represented through NFTs according to the proposed standard. Typically, an ASSET does not have signing capabilities.</p> </li> <li> <p><strong>ATTESTATION</strong> is the confirmation that PROOF OF CONTROL was established when specifying the <code>to</code> (receiver, beneficiary) address.</p> </li> <li> <p><strong>PROOF-OF-CONTROL</strong> over the ASSET means owning or otherwise controlling an ASSET. How Proof of Control is established depends on the ASSET and may be implemented using technical, legal or other means. For physical ASSETS, CONTROL is typically verified by proofing physical proximity between a physical ASSET and an input device (for example a smartphone) used to specify the <code>to</code> address.</p> </li> <li> <p>An <strong>ORACLE</strong> has signing capabilities. MUST be able to sign ATTESTATIONS off-chain in a way such that signatures can be verified on-chain.</p> </li> </ul> <h3 id="base-interface">Base Interface</h3> <p>Every contract compliant to this standard MUST implement the <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/IERC6956.sol">the proposed standard interface</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interfaces and is subject to <a href="https://wg-eips.ritovision.com/6956/#caveats-for-base-interface">Caveats</a> below:</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 OR 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.18</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"> IERC6956 Asset-Bound Non-Fungible Tokens </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Asset-bound Non-Fungible Tokens anchor a token 1:1 to a (physical or digital) asset and token transfers are authorized through attestation of control over the asset</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-6956</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 0xa9cf7635</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"> IERC6956</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"> Authorization, typically mapped to authorizationMaps, where each bit indicates whether a particular ERC6956Role is authorized </span></span> <span class="giallo-l"><span class="z-comment"> * Typically used in constructor (hardcoded or params) to set burnAuthorization and approveAuthorization</span></span> <span class="giallo-l"><span class="z-comment"> * Also used in optional updateBurnAuthorization, updateApproveAuthorization, I</span></span> <span class="giallo-l"><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"> Authorization</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> NONE</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> = 0, // None of the above</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> OWNER</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> = (1&lt;&lt;OWNER), // The owner of the token, i.e. the digital representation</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ISSUER</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> = (1&lt;&lt;ISSUER), // The issuer of the tokens, i.e. this smart contract</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ASSET</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> = (1&lt;&lt;ASSET), // The asset, i.e. via attestation</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> OWNER_AND_ISSUER</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> = (1&lt;&lt;OWNER) | (1&lt;&lt;ISSUER),</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> OWNER_AND_ASSET</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> = (1&lt;&lt;OWNER) | (1&lt;&lt;ASSET),</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ASSET_AND_ISSUER</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> = (1&lt;&lt;ASSET) | (1&lt;&lt;ISSUER),</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ALL</span><span class="z-comment"> //</span><span class="z-comment"> = (1&lt;&lt;OWNER) | (1&lt;&lt;ISSUER) | (1&lt;&lt;ASSET) // Owner + Issuer + Asset</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">@notice</span><span class="z-comment"> This emits when approved address for an anchored tokenId is </span><span class="z-keyword">changed</span><span class="z-comment"> or reaffirmed via attestation</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 approveAnchor() is called and corresponds to ERC-721 behavior</span></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"> The owner of the anchored 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"> approved</span><span class="z-comment"> The approved address, address(0) indicates there is no approved 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"> anchor</span><span class="z-comment"> The anchor, for which approval has been </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"> tokenId</span><span class="z-comment"> ID (&gt;0) of the anchored 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"> AnchorApproval</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-variable"> approved</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> anchor</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> <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 ownership of any anchored NFT changes by any mechanism</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 together with tokenId-based ERC-721.Transfer and provides an anchor-perspective on transfers</span></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 previous owner, address(0) indicate there was none.</span></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 new owner, address(0) indicates the token is burned</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> anchor</span><span class="z-comment"> The anchor which is bound to 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"> tokenId</span><span class="z-comment"> ID (&gt;0) of the anchored 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"> AnchorTransfer</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">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> anchor</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 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 an attestation has been used indicating no second attestation with the same attestationHash will be accepted</span></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 to address specified in the attestation</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> anchor</span><span class="z-comment"> The anchor specified in the attestation</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> attestationHash</span><span class="z-comment"> The hash of the attestation, see ERC-6956 for 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"> totalUsedAttestationsForAnchor</span><span class="z-comment"> The total number of attestations already used for the particular anchor</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"> AttestationUse</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">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> anchor</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> attestationHash</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> totalUsedAttestationsForAnchor</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 trust-status of an oracle changes. </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Trusted oracles must explicitly be specified. </span></span> <span class="giallo-l"><span class="z-comment"> * If the last event for a particular oracle-address indicates it&#39;s trusted, attestations from this oracle are 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"> oracle</span><span class="z-comment"> Address of the oracle signing attestations</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> trusted</span><span class="z-comment"> indicating whether this address is trusted (true). Use (false) to no longer trust from an oracle.</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"> OracleUpdate</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> oracle</span><span>, </span><span class="z-support">bool</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> trusted</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 the 1:1 mapped anchor for a 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"> tokenId</span><span class="z-comment"> ID (&gt;0) of the anchored 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"> anchor</span><span class="z-comment"> The anchor bound to tokenId, 0x0 if tokenId does not represent an anchor</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"> anchorByToken</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 class="z-variable"> anchor</span><span>)</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 the ID of the 1:1 mapped token of an anchor.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> anchor</span><span class="z-comment"> The anchor (&gt;0x0)</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"> ID of the anchored token, 0 if no anchored token exists</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"> tokenByAnchor</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> anchor</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"> 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">@notice</span><span class="z-comment"> The number of attestations already used to modify the state of an anchor or its bound 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"> anchor</span><span class="z-comment"> The anchor(&gt;0)</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"> attestationUses</span><span class="z-comment"> The number of attestation uses for a particular anchor, 0 if anchor is invalid.</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"> attestationsUsedByAnchor</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> anchor</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">uint256</span><span class="z-variable"> attestationUses</span><span>)</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"> Decodes and returns to-address, anchor and the attestation hash, if the attestation is valid</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST throw when</span></span> <span class="giallo-l"><span class="z-comment"> * - Attestation has already been used (an AttestationUse-Event with matching attestationHash was emitted)</span></span> <span class="giallo-l"><span class="z-comment"> * - Attestation is not signed by trusted oracle (the last OracleUpdate-Event for the signer-address does not indicate trust)</span></span> <span class="giallo-l"><span class="z-comment"> * - Attestation is not valid yet or expired</span></span> <span class="giallo-l"><span class="z-comment"> * - [if IERC6956AttestationLimited is implemented] attestationUsagesLeft(attestation.anchor) &lt;= 0</span></span> <span class="giallo-l"><span class="z-comment"> * - [if IERC6956ValidAnchors is implemented] validAnchors(data) does not return true. </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> attestation</span><span class="z-comment"> The attestation subject to the format specified in ERC-6956</span></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"> Optional additional data, may contain proof as the first abi-encoded argument when IERC6956ValidAnchors 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"> to</span><span class="z-comment"> Address where the ownership of an anchored token or approval shall be </span><span class="z-keyword">changed</span><span class="z-comment"> to</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"> anchor</span><span class="z-comment"> The anchor (&gt;0)</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"> attestationHash</span><span class="z-comment"> The attestation hash computed on-chain as `keccak256(attestation)`</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"> decodeAttestationIfValid</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attestation</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-storage z-type"> view</span><span class="z-keyword"> returns</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"> anchor</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> attestationHash</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"> Indicates whether any of ASSET, OWNER, ISSUER is authorized to burn</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"> burnAuthorization</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-storage z-type">Authorization</span><span class="z-variable"> burnAuth</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"> Indicates whether any of ASSET, OWNER, ISSUER is authorized to approve</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"> approveAuthorization</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-storage z-type">Authorization</span><span class="z-variable"> approveAuth</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"> Corresponds to transferAnchor(bytes,bytes) without additional 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"> attestation</span><span class="z-comment"> Attestation, refer ERC-6956 for details</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"> transferAnchor</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attestation</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"> Changes the ownership of an NFT mapped to attestation.anchor to attestation.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"> Permissionless, i.e. anybody invoke and sign a transaction. The transfer is authorized through the oracle-signed attestation.</span></span> <span class="giallo-l"><span class="z-comment"> * - Uses decodeAttestationIfValid()</span></span> <span class="giallo-l"><span class="z-comment"> * - When using a centralized &quot;gas-payer&quot; recommended to implement IERC6956AttestationLimited.</span></span> <span class="giallo-l"><span class="z-comment"> * - Matches the behavior of ERC-721.safeTransferFrom(ownerOf[tokenByAnchor(attestation.anchor)], attestation.to, tokenByAnchor(attestation.anchor), ..) and mint an NFT if `tokenByAnchor(anchor)==0`.</span></span> <span class="giallo-l"><span class="z-comment"> * - Throws when attestation.to == ownerOf(tokenByAnchor(attestation.anchor))</span></span> <span class="giallo-l"><span class="z-comment"> * - Emits AnchorTransfer </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"> attestation</span><span class="z-comment"> Attestation, refer ERC-6956 for 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"> data</span><span class="z-comment"> Additional data, may be used for additional transfer-conditions, may be sent partly or in full in a call to safeTransferFrom</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"> transferAnchor</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attestation</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>;</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"> Corresponds to approveAnchor(bytes,bytes) without additional 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"> attestation</span><span class="z-comment"> Attestation, refer ERC-6956 for details</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"> approveAnchor</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attestation</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"> Approves attestation.to the token bound to attestation.anchor. .</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Permissionless, i.e. anybody invoke and sign a transaction. The transfer is authorized through the oracle-signed attestation.</span></span> <span class="giallo-l"><span class="z-comment"> * - Uses decodeAttestationIfValid()</span></span> <span class="giallo-l"><span class="z-comment"> * - When using a centralized &quot;gas-payer&quot; recommended to implement IERC6956AttestationLimited.</span></span> <span class="giallo-l"><span class="z-comment"> * - Matches the behavior of ERC-721.approve(attestation.to, tokenByAnchor(attestation.anchor)).</span></span> <span class="giallo-l"><span class="z-comment"> * - Throws when ASSET is not authorized to approve.</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"> attestation</span><span class="z-comment"> Attestation, refer ERC-6956 for details </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"> approveAnchor</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attestation</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>;</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"> Corresponds to burnAnchor(bytes,bytes) without additional 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"> attestation</span><span class="z-comment"> Attestation, refer ERC-6956 for details</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"> burnAnchor</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attestation</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Burns the token mapped to attestation.anchor. Uses ERC-721._burn.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Permissionless, i.e. anybody invoke and sign a transaction. The transfer is authorized through the oracle-signed attestation.</span></span> <span class="giallo-l"><span class="z-comment"> * - Uses decodeAttestationIfValid()</span></span> <span class="giallo-l"><span class="z-comment"> * - When using a centralized &quot;gas-payer&quot; recommended to implement IERC6956AttestationLimited.</span></span> <span class="giallo-l"><span class="z-comment"> * - Throws when ASSET is not authorized to burn</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"> attestation</span><span class="z-comment"> Attestation, refer ERC-6956 for details</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"> burnAnchor</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> attestation</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>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="caveats-for-base-interface">Caveats for Base Interface</h4> <ul> <li> <p>MUST implement ERC-721 and ERC-165</p> </li> <li> <p>MUST have bidirectional mapping <code>tokenByAnchor(anchor)</code> and <code>anchorByToken(tokenId)</code>. This implies that a maximum of one token per ANCHOR exists.</p> </li> <li> <p>MUST have a mechanism to determine whether an ANCHOR is valid for the contract. RECOMMENDED to implement the proposed <a href="https://wg-eips.ritovision.com/6956/#validanchors-interface">ValidAnchors-Interface</a></p> </li> <li> <p>MUST implement <code>decodeAttestationIfValid(attestation, data)</code> to validate and decode ATTESTATIONS as specified in the <a href="https://wg-eips.ritovision.com/6956/#oracle">ORACLE-Section</a></p> <ul> <li>MUST return <code>attestation.to</code>, <code>attestation.anchor</code>, <code>attestation.attestationHash</code>.</li> <li>MUST not modify state, as this function can be used to check an ATTESTATION's validity without redeeming it.</li> <li>MUST throw when <ul> <li>ATTESTATION is not signed from a trusted ORACLE.</li> <li>ATTESTATION has expired or is not valid yet</li> <li>ATTESTATION has not been redeemed. "Redeemed" being defined in at least one state-changing operation has been authorized through a particular ATTESTATION.</li> <li>If <a href="https://wg-eips.ritovision.com/6956/#attestationlimited-interface">AttestationLimited-Interface</a> implemented: When <code>attestationUsagesLeft(attestation.to) &lt;= 0</code></li> <li>If <a href="https://wg-eips.ritovision.com/6956/#validanchors-interface">ValidAnchors-Interface</a> implemented: When <code>validAnchor() != true</code>.</li> </ul> </li> <li>If <a href="https://wg-eips.ritovision.com/6956/#validanchors-interface">ValidAnchors-Interface</a> implemented: MUST call <code>validAnchor(attestation.to, abi.decode('bytes32[]',data))</code>, meaning the first abi-encoded value in the <code>data</code> parameter corresponds to <code>proof</code>.</li> </ul> </li> <li> <p>MUST have a ANCHOR-RELEASED mechanism, indicating whether the anchored NFT is released/transferable.</p> <ul> <li>Any ANCHOR MUST NOT be released by default.</li> </ul> </li> <li> <p>MUST extend any ERC-721 token transfer mechanism by:</p> <ul> <li>MUST throw when <code>ANCHOR</code> is not released.</li> <li>MUST throw when batchSize &gt; 1, namely no batch transfers are supported with this contract.</li> <li>MUST emit <code>AnchorTransfer(from, to, anchorByToken[tokenId], tokenId)</code></li> </ul> </li> <li> <p>MUST implement <code>attestationsUsedByAnchor(anchor)</code>, returning how many attestations have already been used for a specific anchor.</p> </li> <li> <p>MUST implement the state-changing <code>transferAnchor(..)</code>, <code>burnAnchor(..)</code>, <code>approveAnchor(..)</code> and OPTIONAL MAY implement additional state-changing operations which</p> <ul> <li>MUST use the <code>decodeAttestationIfValid()</code> to determine <code>to</code>, <code>anchor</code> and <code>attestationHash</code></li> <li>MUST redeem each ATTESTATION in the same transaction as any authorized state-changing operation. RECOMMENDED by storing each used <code>attestationHash</code></li> <li>MUST increment <code>attestationsUsedByAnchor[anchor]</code></li> <li>MUST emit <code>AttestationUsed</code></li> <li><code>transferAnchor(attestation)</code> MUST behave and emit events like <code>ERC-721.safeTransferFrom(ownerOf[tokenByAnchor(attestation.anchor)], attestation.to, tokenByAnchor(attestation.anchor), ..)</code> and mint an NFT if <code>tokenByAnchor(anchor)==0</code>.</li> </ul> </li> <li> <p>RECOMMENDED to implement <code>tokenURI(tokenId)</code> to return an anchorBased-URI, namely <code>baseURI/anchor</code>. This anchoring metadata to ASSET. Before an anchor is not used for the first time, the ANCHOR's mapping to tokenId is unknown. Hence, using the anchor in instead of the tokenId is preferred.</p> </li> </ul> <h3 id="oracle">ORACLE</h3> <ul> <li>MUST provide an ATTESTATION. Below we define the format how an ORACLE testifies that the <code>to</code> address of a transfer has been specified under the pre-condition of PROOF-OF-CONTROL associated with the particular ANCHOR being transferred to <code>to</code>.</li> <li>The ATTESTATION MUST abi-encode the following: <ul> <li><code>to</code>, MUST be address, specifying the beneficiary, for example the to-address, approved account etc.</li> <li>ANCHOR, aka the ASSET identifier, MUST have a 1:1 relation to the ASSET</li> <li><code>attestationTime</code>, UTC seconds, time when attestation was signed by ORACLE,</li> <li><code>validStartTime</code> UTC seconds, start time of the ATTESTATION's validity timespan</li> <li><code>validEndTime</code>, UTC seconds, end time of the ATTESTATION's validity timespan</li> <li><code>signature</code>, ETH-signature (65 bytes). Output of an ORACLE signing the <code>attestationHash = keccak256([to, anchor, attestationTime, validStartTime, validEndTime])</code>.</li> </ul> </li> <li>How PROOF-OF-CONTROL is establish in detail through an ANCHOR-TECHNOLOGY is not subject to this standard. Some ORACLE requirements and ANCHOR-TECHNOLOGY requirements when using PHYSICAL ASSETS are outlined in <a href="https://wg-eips.ritovision.com/6956/#security-considerations-for-physical-assets">Security considerations for Physical Assets</a>.</li> </ul> <p>A Minimal Typescript sample to generate an ATTESTATION is available in the <a href="https://wg-eips.ritovision.com/6956/#reference-implementation">Reference Implementation section</a> of this proposal.</p> <h3 id="attestationlimited-interface">AttestationLimited-Interface</h3> <p>Every contract compliant to this standard MAY implement the <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/IERC6956AttestationLimited.sol">proposed AttestationLimited interface</a> and is subject to <a href="https://wg-eips.ritovision.com/6956/#caveats-for-attestationlimited-interface">Caveats</a> below:</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 OR 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.18</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC6956.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"> Attestation-limited Asset-Bound NFT</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-6956</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 0x75a2e933</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"> IERC6956AttestationLimited</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6956</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> AttestationLimitPolicy</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> IMMUTABLE</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> INCREASE_ONLY</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> DECREASE_ONLY</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> FLEXIBLE</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-storage z-type"> @notice</span><span class="z-comment"> Returns the attestation limit for a particular anchor</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST return the global attestation limit per default</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and override the global attestation limit in case an anchor-based limit is set</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> attestationLimit</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> anchor</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"> limit</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 number of attestations left for a particular anchor</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Is computed by comparing the attestationsUsedByAnchor(anchor) and the current attestation limit </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (current limited emitted via GlobalAttestationLimitUpdate or AttestationLimit events)</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> attestationUsagesLeft</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> anchor</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"> nrTransfersLeft</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"> Indicates the policy, in which direction attestation limits can be updated (globally or per anchor)</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> attestationLimitPolicy</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-storage z-type">AttestationLimitPolicy</span><span class="z-variable"> policy</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"> This emits when the global attestation limit is updated</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> GlobalAttestationLimitUpdate</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> transferLimit</span><span>, </span><span class="z-support">address</span><span class="z-variable"> updatedBy</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"> This emits when an anchor-specific attestation limit is updated</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AttestationLimitUpdate</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> anchor</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-storage z-type"> indexed</span><span class="z-variable"> transferLimit</span><span>, </span><span class="z-support">address</span><span class="z-variable"> updatedBy</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 in the transaction, where attestationUsagesLeft becomes 0</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AttestationLimitReached</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> anchor</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-storage z-type"> indexed</span><span class="z-variable"> transferLimit</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="caveats-for-attestationlimited-interface">Caveats for AttestationLimited-Interface</h4> <ul> <li>MUST extend the proposed standard interface</li> <li>MUST define one of the above listed AttestationLimit update policies and expose it via <code>attestationLimitPolicy()</code> <ul> <li>MUST support different update modes, namely FIXED, INCREASE_ONLY, DECREASE_ONLY, FLEXIBLE (= INCREASABLE and DECREASABLE)</li> <li>RECOMMENDED to have a global transfer limit, which can be overwritten on a token-basis (when <code>attestationLimitPolicy() != FIXED</code>)</li> </ul> </li> <li>MUST implement <code>attestationLimit(anchor)</code>, specifying how often an ANCHOR can be transferred in total. Changes in the return value MUST reflect the AttestationLimit-Policy.</li> <li>MUST implement <code>attestationUsagesLeft(anchor)</code>, returning the number of usages left (namely <code>attestationLimit(anchor)-attestationsUsedByAnchor[anchor]</code>) for a particular anchor</li> </ul> <h3 id="floatable-interface">Floatable-Interface</h3> <p>Every contract compliant to this extension MAY implement the proposed <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/IERC6956Floatable.sol">Floatable interface</a> and is subject to <a href="https://wg-eips.ritovision.com/6956/#caveats-for-floatable-interface">Caveats</a> below:</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 OR 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.18</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC6956.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"> Floatable Asset-Bound NFT</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> A floatable Asset-Bound NFT can (temporarily) be transferred without attestation</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-6956</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 0xf82773f7</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"> IERC6956Floatable</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6956</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> FloatState</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Default</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> 0, inherits from floatAll</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Floating</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> 1</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Anchored</span><span class="z-comment"> //</span><span class="z-comment"> 2</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"> @notice</span><span class="z-comment"> Indicates that an anchor-specific floating state </span><span class="z-keyword">changed</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FloatingStateChange</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> anchor</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-variable">FloatState</span><span class="z-variable"> isFloating</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Emits when FloatingAuthorization is </span><span class="z-keyword">changed</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"> FloatingAuthorizationChange</span><span>(</span><span class="z-variable">Authorization</span><span class="z-variable"> startAuthorization</span><span>, </span><span class="z-variable">Authorization</span><span class="z-variable"> stopAuthorization</span><span>, </span><span class="z-support">address</span><span class="z-variable"> maintainer</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"> Emits, when the default floating state is </span><span class="z-keyword">changed</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FloatingAllStateChange</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> areFloating</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Indicates whether an anchored token is floating, namely can be transferred without attestation</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> floating</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> anchor</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Indicates whether any of OWNER, ISSUER, (ASSET) is allowed to start floating</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> floatStartAuthorization</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-storage z-type">Authorization</span><span class="z-variable"> canStartFloating</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"> Indicates whether any of OWNER, ISSUER, (ASSET) is allowed to stop floating</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> floatStopAuthorization</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-storage z-type">Authorization</span><span class="z-variable"> canStartFloating</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"> Allows to override or reset to floatAll-behavior per anchor</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Must throw when newState == Floating and floatStartAuthorization does not authorize 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 throw when newState == Anchored and floatStopAuthorization does not authorize 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"> anchor</span><span class="z-comment"> The anchor, whose anchored token shall override default behavior</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> newState</span><span class="z-comment"> Override-State. If set to Default, the anchor will behave like floatAll</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"> float</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> anchor</span><span>,</span><span class="z-storage z-type"> FloatState</span><span class="z-variable"> newState</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span><span> </span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="caveats-for-floatable-interface">Caveats for Floatable-Interface</h4> <p>If <code>floating(anchor)</code> returns true, the token identified by <code>tokenByAnchor(anchor)</code> MUST be transferable without attestation, typically authorized via <code>ERC721.isApprovedOrOwner(msg.sender, tokenId)</code></p> <h3 id="validanchors-interface">ValidAnchors-Interface</h3> <p>Every contract compliant to this extension MAY implement the proposed <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/IERC6956ValidAnchors.sol">ValidAnchors interface</a> and is subject to <a href="https://wg-eips.ritovision.com/6956/#caveats-for-validanchors-interface">Caveats</a> below:</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 OR 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.18</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC6956.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"> Anchor-validating Asset-Bound NFT</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-6956</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 0x051c9bd8</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"> IERC6956ValidAnchors</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6956</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"> Emits when the valid anchors for the contract are updated.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> validAnchorHash</span><span class="z-comment"> Hash representing all valid anchors. Typically Root of Merkle-Tree</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> maintainer</span><span class="z-comment"> msg.sender when updating the hash</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"> ValidAnchorsUpdate</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> validAnchorHash</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> maintainer</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"> Indicates whether an anchor is valid in the present contract</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Typically implemented via MerkleTrees, where proof is used to verify anchor is part of the MerkleTree </span></span> <span class="giallo-l"><span class="z-comment"> * MUST return false when no ValidAnchorsUpdate-event has been emitted yet</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> anchor</span><span class="z-comment"> The anchor in </span><span class="z-keyword">question</span></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"> Proof that the anchor is valid, typically MerkleProof</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"> isValid</span><span class="z-comment"> True, when anchor and proof can be verified against validAnchorHash (emitted via ValidAnchorsUpdate-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"> anchorValid</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> anchor</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"> proof</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"> isValid</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="caveats-for-validanchors-interface">Caveats for ValidAnchors-Interface</h4> <ul> <li>MUST implement <code>validAnchor(anchor, proof)</code> which returns true when anchor is valid, namely MerkleProof is correct, false otherwise.</li> </ul> <h2 id="rationale">Rationale</h2> <p><strong>Why do you use an anchor&lt;&gt;tokenId mapping and not simply use tokenIds directly?</strong> Especially for collectable use-cases, special or sequential tokenIds (for example low numbers), have value. Holders may be proud to have claimed tokenId=1 respectively the off-chain ASSET with tokenId=1 may increase in value, because it was the first ever claimed. Or an Issuer may want to address the first 100 owners who claimed their ASSET-BOUND NFT. While these use-cases technically can certainly be covered by observing the blockchain state-changes, we consider reflecting the order in the tokenIds to be the user-friendly way. Please refer <a href="https://wg-eips.ritovision.com/6956/#security-considerations">Security considerations</a> on why sequential anchors shall be avoided.</p> <p><strong>Why is tokenId=0 and anchor=0x0 invalid?</strong> For gas efficiency. This allows to omit checks and state-variables for the existence of a token or anchor, since mappings of a non-existent key return 0 and cannot be easily distinguished from anchor=0 or tokenId=0.</p> <p><strong>ASSETS are often batch-produced with the goal of identical properties, for example a batch of automotive spare parts. Why should do you extend ERC-721 and not Multi-Token standards?</strong> Even if a (physical) ASSET is mass produced with fungible characteristics, each ASSET has an individual property/ownership graph and thus shall be represented in a non-fungible way. Hence this EIP follows the design decision that ASSET (represented via a unique asset identifier called ANCHOR) and token are always mapped 1-1 and not 1-N, so that a token represents the individual property graph of the ASSET.</p> <p><strong>Why is there a burnAnchor() and approveAnchor()?</strong> Due to the permissionless nature ASSET-BOUND NFTs can even be transferred to or from any address. This includes arbitrary and randomly generated accounts (where the private key is unknown) and smart-contracts which would traditionally not support ERC-721 NFTs. Following that owning the ASSET must be equivalent to owning the NFT, this means that we also need to support ERC-721 operations like approval and burning in such instances through authorizing the operations with an attestation.</p> <p><strong>Implementation alternatives considered</strong> Soulbound burn+mint combination, for example through Consensual Soulbound Tokens (<a href="https://wg-eips.ritovision.com/5484/">ERC-5484</a>). Disregarded because appearance is highly dubious, when the same asset is represented through multiple tokens over time. An predecessor of this EIP has used this approach and can be found deployed to Mumbai Testnet under address <code>0xd04c443913f9ddcfea72c38fed2d128a3ecd719e</code>.</p> <p><strong>When should I implement AttestationLimited-Interface</strong> Naturally, when your use-case requires each ASSET being transferable only a limited number of times. But also for security reasons, see <a href="https://wg-eips.ritovision.com/6956/#security-considerations">Security Considerations</a></p> <p><strong>Why is there the <code>IERC6956Floatable.FloatState</code> enum?</strong> In order to allow gas-efficient implementation of floatAll(), which can be overruled by anchor-based floatability in all combinations. (See rationale for tokenId=0 above).</p> <p><strong>Why is there no <code>floating(tokenId)</code> function?</strong> This would behave identically to an <code>isTransferable(tokenId,...)</code> mechanism proposed in many other EIPs (refer e.g. <a href="https://wg-eips.ritovision.com/6454/">ERC-6454</a>). Further, the proposed <code>floating(anchorByToken(tokenId))</code> can be used.</p> <p><strong>Why are there different FloatingAuthorizations for start and stop?</strong> Depending on the use-case, different roles should be able to start or stop floating. Note that for many applications the ISSUER may want to have control over the floatability of the collection.</p> <h3 id="example-use-cases-and-recommended-combination-of-interfaces">Example Use Cases and recommended combination of interfaces</h3> <p>Possession based use cases are covered by the standard interface <code>IERC6956</code>: The holder of ASSET is in possession of ASSET. Possession is an important social and economical tool: In many sports games possession of ASSET, commonly referred to as "the ball", is of essence. Possession can come with certain obligations and privileges. Ownership over an ASSET can come with rights and benefits as well as being burdened with liens and obligations. For example, an owned ASSET can be used for collateral, can be rented or can even yield a return. Example use-cases are</p> <ul> <li> <p><strong>Possession based token gating:</strong> Club guest in possession of limited T-Shirt (ASSET) gets a token which allows him to open the door to the VIP lounge.</p> </li> <li> <p><strong>Possession based digital twin:</strong> A gamer is in possession of a pair of physical sneakers (ASSET), and gets a digital twin (NFT) to wear them in metaverse.</p> </li> <li> <p><strong>Scarce possession based digital twin:</strong> The producer of the sneakers (ASSET) decided that the product includes a limit of 5 digital twins (NFTs), to create scarcity.</p> </li> <li> <p><strong>Lendable digital twin:</strong> The gamer can lend his sneaker-tokens (NFT) to a friend in the metaverse, so that the friend can run faster.</p> </li> <li> <p><strong>Securing ownership from theft:</strong> If ASSET is owned off-chain, the owner wants to secure the anchored NFT, namely not allow transfers to prevent theft or recover the NFT easily through the ASSET.</p> </li> <li> <p><strong>Selling a house with a mortgage:</strong> The owner holds NFT as proof of ownership. The DeFi-Bank finances the house and puts a lock on the transfer of NFT. Allow Transfers of the NFT require the mortgage to be paid off. Selling the ASSET (house) off-chain will be impossible, as it's no longer possible to finance the house.</p> </li> <li> <p><strong>Selling a house with a lease:</strong> A lease contract puts a lien on an ASSET's anchored NFT. The old owner removes the lock, the new owner buys and refinances the house. Transfer of NFT will also transfer the obligations and benefits of the lien to the new owner.</p> </li> <li> <p><strong>Buying a brand new car with downpayment:</strong> A buyer configures a car and provides a downpayment, for a car that will have an ANCHOR. As long as the car is not produced, the NFT can float and be traded on NFT market places. The owner of the NFT at time of delivery of the ASSET has the permission to pick up the car and the obligation to pay full price.</p> </li> <li> <p><strong>Buying a barrel of oil by forward transaction:</strong> A buyer buys an oil option on a forward contract for one barrel of oil (ASSET). On maturity date the buyer has the obligation to pick up the oil.</p> </li> </ul> <p>The use case matrix below shows which extensions and settings must (additionally to <code>IERC6956</code>!) be implemented for the example use-cases together with relevant configurations.</p> <p>Note that for <code>Lockable</code> listed in the table below, the proposed EIP can be extended with any Lock- or Lien-Mechanism known to extend for ERC-721, for example <a href="https://wg-eips.ritovision.com/5192/">ERC-5192</a> or <a href="https://wg-eips.ritovision.com/6982/">ERC-6982</a>. We recommend to verify whether a token is locked in the <code>_beforeTokenTransfer()</code>-hook, as this is called from <code>safeTransferFrom()</code> as well as <code>transferAnchor()</code>, hence suitable to block "standard" ERC-721 transfers as well as the proposed attestation-based transfers.</p> <table><thead><tr><th>Use Case</th><th>approveAuthorization</th><th>burnAuthorization</th><th><code>IERC6956Floatable</code></th><th><code>IERC6956AttestationLimited</code></th><th>Lockable</th></tr></thead><tbody> <tr><td><strong>Managing Possession</strong></td><td></td><td></td><td></td><td></td><td></td></tr> <tr><td>Token gating</td><td>ASSET</td><td>ANY</td><td>incompatible</td><td>-</td><td>-</td></tr> <tr><td>Digital twin</td><td>ASSET</td><td>ANY</td><td>incompatible</td><td>-</td><td>-</td></tr> <tr><td>Scarce digital twin</td><td>ASSET</td><td>ANY</td><td>incompatible</td><td>required</td><td>-</td></tr> <tr><td>Lendable digital twin</td><td>OWNER_AND_ASSET</td><td>ASSET</td><td>required</td><td>-</td><td>-</td></tr> <tr><td><strong>Managing Ownership</strong></td><td></td><td></td><td></td><td></td><td></td></tr> <tr><td>Securing ownership from theft</td><td>OWNER or OWNER_AND_ASSET</td><td>ANY</td><td>optional</td><td>-</td><td>required</td></tr> <tr><td>Selling an house with a mortgage</td><td>ASSET or OWNER_AND_ASSET</td><td>ANY</td><td>optional</td><td>optional</td><td>required</td></tr> <tr><td>Selling a house with a lease</td><td>ASSET or OWNER_AND_ASSET</td><td>ANY</td><td>optional</td><td>optional</td><td>required</td></tr> <tr><td>Buying a brand new car with downpayment</td><td>ASSET or OWNER_AND_ASSET</td><td>ANY</td><td>optional</td><td>optional</td><td>required</td></tr> <tr><td>Buying a barrel of oil by forward transaction</td><td>ASSET or OWNER_AND_ASSET</td><td>ANY</td><td>optional</td><td>optional</td><td>required</td></tr> </tbody></table> <p>Legend:</p> <ul> <li>required ... we don't see a way how to implement the use-case without it</li> <li>incompatible ... this MUSTN'T be implemented, as it is a security risk for the use-case</li> <li>optional ... this MAY optionally be implemented</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <p>This EIP is fully compatible with ERC-721 and (when extended with the <code>IERC6956Floatable</code>-interface) corresponds to the well-known ERC-721 behavior with an additional authorization-mechanism via attestations. Therefore we recommend - especially for physical assets - to use the present EIP instead of ERC-721 and amend it with extensions designed for ERC-721.</p> <p>However, it is RECOMMENDED to extend implementations of the proposed standard with an interface indicating transferability of NFTs for market places. Examples include <a href="https://wg-eips.ritovision.com/6454/">ERC-6454</a> and <a href="https://wg-eips.ritovision.com/5484/">ERC-5484</a>.</p> <p>Many ERC-721 extensions suggest to add additional throw-conditions to transfer methods. This standard is fully compatible, as</p> <ul> <li>The often-used ERC-721 <code>_beforeTokenTransfer()</code> hook must be called for all transfers including attestation-authorized transfers.</li> <li>A <code>_beforeAnchorUse()</code> hook is suggested in the reference implementation, which only is called when using attestation as authorization.</li> </ul> <h2 id="test-cases">Test Cases</h2> <p>Test cases are available:</p> <ul> <li>For only implementing <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/IERC6956.sol">the proposed standard interface</a> can be found <a href="https://wg-eips.ritovision.com/6956/./assets/test/ERC6956.ts">here</a></li> <li>For implementing <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/IERC6956.sol">the proposed standard interface</a>, <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/IERC6956Floatable.sol">the Floatable extension</a>, <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/IERC6956ValidAnchors.sol">the ValidAnchors extension</a> and <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/IERC6956AttestationLimited.sol">the AttestationLimited extension</a> can be found <a href="https://wg-eips.ritovision.com/6956/./assets/test/ERC6956Full.ts">here</a></li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <ul> <li>Minimal implementation, only supporting <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/IERC6956.sol">the proposed standard interface</a> can be found <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/ERC6956.sol">here</a></li> <li>Full implementation, with support for <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/IERC6956.sol">the proposed standard interface</a>, <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/IERC6956Floatable.sol">the Floatable extension</a>, <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/IERC6956ValidAnchors.sol">the ValidAnchors extension</a> and <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/IERC6956AttestationLimited.sol">the AttestationLimited extension</a> can be found <a href="https://wg-eips.ritovision.com/6956/./assets/contracts/ERC6956Full.sol">here</a></li> <li>A Minimal Typescript sample to generate an ATTESTATION using ethers library is available <a href="https://wg-eips.ritovision.com/6956/./assets/minimalAttestationSample.ts">here</a></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p><strong>If the asset is stolen, does this mean the thief has control over the NFT?</strong> Yes.The standard aims to anchor an NFT to the asset inseperably and unconditionally. This includes reflecting theft, as the ORACLE will testify that PROOF-OF-CONTROL over the ASSET is established. The ORACLE does not testify whether the controller is the legitimate owner, Note that this may even be a benefit. If the thief (or somebody receiving the asset from the thief) should interact with the anchor, an on-chain address of somebody connected to the crime (directly or another victim) becomes known. This can be a valuable starting point for investigation. Also note that the proposed standard can be combined with any lock-mechanism, which could lock attestation-based action temporarily or permanently (after mint).</p> <p><strong>How to use AttestationLimits to avoid fund-draining</strong> A central security mechanism in blockchain applications are gas fees. Gas fees ensure that executing a high number of transactions get penalized, hence all DoS or other large-scale attacks are discouraged. Due to the permissionless nature of attestation-authorized operations, many use-cases will arise, where the issuer of the ASSET (which normally is also the issuer of the ASSET-BOUND NFT) will pay for all transactions - contrary to the well-known ERC-721 behavior, where either from- or to-address are paying. So a user with malicious intent may just let the ORACLE approve PROOF-OF-CONTROL multiple times with specifying alternating account addresses. These ATTESTATIONS will be handed to the central gas-payer, who will execute them in a permissionless way, paying gas-fees for each transactions. This effectively drains the funds from the gas-payer, making the system unusable as soon as the gas-payer can no longer pay for transactions.</p> <p><strong>Why do you recommend hashing serial numbers over using them plain?</strong> Using any sequential identifier allows to at least conclude of the number between the lowest and highest ever used serial number. This therefore provides good indication over the total number of assets on the market. While a limited number of assets is often desirable for collectables, publishing exact production numbers of assets is undesirable for most industries, as it equals to publishing sales/revenue numbers per product group, which is often considered confidential. Within supply chains, serial numbers are often mandatory due to their range-based processing capability. The simplest approach to allow using physical serial numbers and still obfuscating the actual number of assets is through hashing/encryption of the serial number.</p> <p><strong>Why is anchor-validation needed, why not simply trust the oracle to attest only valid anchors?</strong> The oracle testifies PROOF-OF-CONTROL. As the ORACLE has to know the merkle-tree of valid anchors, it could also modify the merkle-tree with malicious intent. Therefore, having an on-chain verification, whether the original merkle-tree has been used, is needed. Even if the oracle gets compromised, it should not have the power to introduce new anchors. This is achieved by requiring that the oracle knows the merkle-tree, but updateValidAnchors() can only be called by a maintainer. Note that the oracle must not be the maintainer. As a consequence, care shall be taken off-chain, in order to ensure that compromising one system-part not automatically compromises oracle and maintainer accounts.</p> <p><strong>Why do you use merkle-trees for anchor-validation?</strong> For security- and gas-reasons. Except for limited collections, anchors will typically be added over time, e.g. when a new batch of the asset is produced or issued. While it is already ineffective to store all available anchors on-chain gas-wise, publishing all anchors would also expose the total number of assets. When using the data from anchor-updates one could even deduce the production capabilities of that asset, which is usually considered confidential information.</p> <p><strong>Assume you have N anchors. If all anchored NFTs are minted, what use is a merkle-tree?</strong> If all anchored NFTs are minted this implies that all anchors have been published and could be gathered on-chain. Consequently, the merkle-tree can be reconstructed. While this may not be an issue for many use cases (all supported anchors are minted anyway), we still recommend to add one "salt-leave" to the merkle-tree, characterized in that the ORACLE will never issue an attestation for an ANCHOR matching that salt-leave. Therefore, even if all N anchors are</p> <h3 id="security-considerations-for-physical-assets">Security Considerations for PHYSICAL ASSETS</h3> <p>In case the ASSET is a physical object, good or property, the following ADDITIONAL specifications MUST be satisfied:</p> <h4 id="oracle-for-physical-anchors">ORACLE for Physical Anchors</h4> <ul> <li>Issuing an ATTESTATION requires that the ORACLE <ul> <li>MUST proof physical proximity between an input device (for example smartphone) specifying the <code>to</code> address and a particular physical ANCHOR and it's associated physical object. Typical acceptable proximity is ranges between some millimeters to several meters.</li> <li>The physical presence MUST be verified beyond reasonable doubt, in particular the employed method <ul> <li>MUST be robust against duplication or reproduction attempts of the physical ANCHOR,</li> <li>MUST be robust against spoofing (for example presentation attacks) etc.</li> </ul> </li> <li>MUST be implemented under the assumption that the party defining the <code>to</code> address has malicious intent and to acquire false ATTESTATION, without currently or ever having access to the physical object comprising the physical ANCHOR.</li> </ul> </li> </ul> <h4 id="physical-asset">Physical ASSET</h4> <ul> <li>MUST comprise an ANCHOR, acting as the unique physical object identifier, typically a serial number (plain (NOT RECOMMENDED) or hashed (RECOMMENDED))</li> <li>MUST comprise a physical security device, marking or any other feature that enables proofing physical presence for ATTESTATION through the ORACLE</li> <li>Is RECOMMENDED to employ ANCHOR-TECHNOLOGIES featuring irreproducible security features.</li> <li>In general it is NOT RECOMMENDED to employ ANCHOR-TECHNOLOGIES that can easily be replicated (for example barcodes, "ordinary" NFC chips, .. ). Replication includes physical and digital replication.</li> </ul> <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-27T00:00:00+00:00 2026-02-11T14:48:25+00:00 Gavin Johnhttps://github.com/Pandapip1 Qi Zhouhttps://github.com/qizhou https://wg-eips.ritovision.com/6944/

Adds an ERC-4804 resolveMode to support ERC-5219 requests

<h2 id="abstract">Abstract</h2> <p>This EIP adds a new <a href="https://wg-eips.ritovision.com/4804/">ERC-4804</a> <code>resolveMode</code> to resolve <a href="https://wg-eips.ritovision.com/5219/">ERC-5219</a> contract resource requests.</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>Contracts wishing to use ERC-5219 as their ERC-4804 resolve mode 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-storage z-type"> @dev</span><span class="z-comment"> IDecentralizedApp is the ERC-5219 interface</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5219Resolver</span><span class="z-storage"> is</span><span class="z-entity z-name"> IDecentralizedApp</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @notice The ERC-4804 resolve mode</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev This MUST return &quot;5219&quot; (0x3532313900000000000000000000000000000000000000000000000000000000) for ERC-5219 resolution (case-insensitive). The other options, as of writing this, are &quot;auto&quot; for automatic resolution, or &quot;manual&quot; for manual resolution.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> resolveMode</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">bytes32</span><span class="z-variable"> mode</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> was not used because interoperability can be checked by calling <code>resolveMode</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="reference-implementation">Reference Implementation</h2> <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"> ERC5219Resolver</span><span class="z-storage"> is</span><span class="z-entity z-name"> IDecentralizedApp</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> resolveMode</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">bytes32</span><span class="z-variable"> mode</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-string"> &quot;5219&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>The security considerations of <a href="https://wg-eips.ritovision.com/4804/#security-considerations">ERC-4804</a> and <a href="https://wg-eips.ritovision.com/5219/#security-considerations">ERC-5219</a> 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> 2023-04-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 360 Corehello@360coreinc.com Robin Rajputhttps://github.com/0xRobinR https://wg-eips.ritovision.com/6932/

ERC-20 extension providing access to a service or product that requires recurring payments.

<h2 id="abstract">Abstract</h2> <p>This subscription-based <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token extends the basic <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token standard with a <code>subscribe</code> and <code>unsubscribe</code> function, which allow users to subscribe or unsubscribe from the subscription service. The <code>subscriptionFee</code> and <code>subscriptionFrequency</code> variables define the cost and frequency of the subscription. The <code>nextPaymentDate</code> mapping keeps track of the next payment date for each subscriber.</p> <p>This token standard will enable automatic periodic deductions from user balances as determined by the merchant subscriber. Simplify and streamline subscription-based services on the Ethereum network, offering enhanced convenience and efficiency for users and merchants alike.</p> <p>A <code>renewSubscription</code> method, that will be used by token holders to renew their subscription to a service or product that requires recurring payments in the form of the token.</p> <h2 id="motivation">Motivation</h2> <p>The rise of subscription-based business models necessitates a standardized approach to handle recurring payments on the Ethereum blockchain. Currently, users often manually initiate subscription payments, resulting in inconvenience and potential disruptions in service delivery. By introducing a Subscription Token, users can seamlessly authorize periodic deductions, enabling uninterrupted access to subscribed services.</p> <p>The subscription-based <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token provides a more flexible and convenient way to manage recurring payments. It can be used for a wide range of services and products that require regular payments, such as subscription-based content platforms, gaming services, and more.</p> <p>The Subscription Token ensures consistency and interoperability across different implementations. Key features include:</p> <ul> <li> <p>Auto Deduction: Merchants, acting as subscribers, can set the subscription interval and associated payment amount for their services. This information is encoded within the Subscription Token contract, enabling automatic deductions from user balances at regular intervals without requiring manual intervention.</p> </li> <li> <p>Balance Check: Users can verify the remaining balance of their subscription tokens at any given time. This transparency empowers users to monitor their subscriptions and make informed decisions regarding their ongoing commitment to the service.</p> </li> <li> <p>Flexibility: The Subscription Token framework accommodates various subscription models, such as monthly, quarterly, or annual billing cycles. Additionally, merchants have the option to define trial periods, upgrade/downgrade plans, and cancellation policies, providing a versatile foundation for a wide range of subscription-based businesses.</p> </li> <li> <p>Security: The Subscription Token employs established security measures, including the use of cryptographic signatures, to ensure the integrity and authenticity of subscription-related transactions. This protects both users and merchants from unauthorized access and potential malicious activities.</p> </li> </ul> <h2 id="specification">Specification</h2> <p>Below are the implementations required by the standard:</p> <h3 id="subscriptiontoken"><code>SubscriptionToken</code></h3> <h4 id="subscribers"><code>subscribers</code></h4> <p>Returns the list of <code>addresses</code> subscribed to the subscription token contract.</p> <h4 id="subscriptioninfo"><code>subscriptionInfo</code></h4> <p>Metadata information of the subscription, like - <code>subscriptionID</code>, <code>subscriptionName</code>, <code>subscriptionDesc</code> and <code>subscriptionTandC</code>.</p> <h4 id="subscriptionfee"><code>subscriptionFee</code></h4> <p>The subscription amount specified that will be deducted in <code>subscriptionFrequency</code> interval, when an address subscribes to the subscription token contract.</p> <h4 id="subscriptionfrequency"><code>subscriptionFrequency</code></h4> <p>Frequency of subscription, interval at which the <code>subscriptionFee</code> will be charged. for example, every 1 day, 1 week or 1 month, denoted in seconds.</p> <h4 id="subscribe"><code>subscribe</code></h4> <p>Method for subscribing an address to the subscription token contract.</p> <h4 id="unsubscribe"><code>unsubscribe</code></h4> <p>Revoke subscription from the subscription token contract, by the subscribed address.</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"> ISubscriptionERC20</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 subscribers address, returns address(0) if `idx` is not found</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> idx</span><span class="z-comment">: the key of the map values</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 at key `idx` of subscribers map</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> subscribers</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> idx</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"> @dev</span><span class="z-comment"> information of the subscription token 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"> subscriptionID</span><span class="z-comment">, subscriptionName, subscriptionDesc, subscriptionTandC</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> subscriptionInfo</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"> string</span><span class="z-storage z-type"> memory</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</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"> subscribes to the subscription, can be payable</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> subscribe</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"> @dev</span><span class="z-comment"> unsubscribe the subscription</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unsubscribe</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"> @dev</span><span class="z-comment"> view or pure can be used</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"> subscription fee</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> subscriptionFee</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"> @dev</span><span class="z-comment"> view or pure can be used</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"> get</span><span class="z-comment"> the subscription frequency</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> subscriptionFrequency</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><h2 id="rationale">Rationale</h2> <p>The subscription token contract inherits the fundamentals of subscription by deducting payments from subscribed addresses on a regular interval using mathematical formulas.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>uint256 intervals = ( block.timestamp - info.start ) / info.frequency;</span></span> <span class="giallo-l"><span>uint256 amount = info.amount * intervals;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>uint256 localEffectiveBalance = effectiveBalance[account];</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>if ( (totalAmount + amount) &gt; localEffectiveBalance ) {</span></span> <span class="giallo-l"><span> amount = localEffectiveBalance;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>totalAmount += ( localEffectiveBalance - amount );</span></span></code></pre> <p>Here, the token balance of the address is calculated using, the locked balances from ongoing subscripitons and the effective balance of the address (updates whenever a transfer is made).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Subscription Tokens may require users to sign transactions or provide cryptographic proofs for subscription-related actions. Proper key management practices should be followed to protect users' private keys and prevent unauthorized access. Encouraging the use of hardware wallets or secure key storage solutions can mitigate the risk of key compromise.</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-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Paul Sullivanhttps://github.com/sullivphpaul.sullivan@manifold.xyz Wilkins Chunghttps://github.com/wwchungwilkins@manifold.xyz Kartik Patelhttps://github.com/Slokhkartik@manifold.xyz https://wg-eips.ritovision.com/6981/

A registry for generating future-deployed smart contract accounts owned by users on external services

<h2 id="abstract">Abstract</h2> <p>The following specifies a system for services to link their users to a claimable Ethereum address. Services can provide a signed message and unique salt to their users which can be used to deploy a smart contract wallet to the deterministic address through a registry contract using the <code>create2</code> opcode.</p> <h2 id="motivation">Motivation</h2> <p>It is common for web services to allow their users to hold on-chain assets via custodial wallets. These wallets are typically EOAs, deployed smart contract wallets or omnibus contracts, with private keys or asset ownership information stored on a traditional database. This proposal outlines a solution that avoids the security concerns associated with historical approaches, and rids the need and implications of services controlling user assets</p> <p>Users on external services that choose to leverage the following specification can be given an Ethereum address to receive assets without the need to do any on-chain transaction. These users can choose to attain control of said addresses at a future point in time. Thus, on-chain assets can be sent to and owned by a user beforehand, therefore enabling the formation of an on-chain identity without requiring the user to interact with the underlying blockchain.</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="overview">Overview</h3> <p>The system for creating reserved ownership accounts consists of:</p> <ol> <li>An Account Registry which provides deterministic addresses based on the service users' identifying salts, and implements a signature verified function that enables claiming of Account Instances by the service's end users.</li> <li>Account Instances created through the Account Registry by end users which allow access to the assets received at the deterministic address prior to Account Instance deployment.</li> </ol> <p>External services wishing to provide their users with reserved ownership accounts MUST maintain a relationship between a user's identifying credentials and a salt. The external service SHALL refer to an Account Registry Instance to retrieve the deterministic account address for a given salt. Users of a given service MUST be able to create an Account Instance by validating their identifying credentials via the external service, which SHOULD give the user a signed message for their salt. Signatures SHOULD be generated by the external service using an signing address known to the Account Registry Instance. Users SHALL pass this message and signature to the service's Account Registry Instance in a call to <code>claimAccount</code> to deploy and claim an Account Instance at the deterministic address.</p> <h3 id="account-registry">Account Registry</h3> <p>The Account Registry 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"> IAccountRegistry</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"> Registry instances emit the AccountCreated event upon successful account creation</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"> AccountCreated</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>, </span><span class="z-support">address</span><span class="z-variable"> accountImplementation</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> salt</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"> Registry instances emit the AccountClaimed event upon successful claim of account by owner</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"> AccountClaimed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</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> <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 a smart contract account.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * If account has already been created, returns the account address without calling create2.</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"> salt</span><span class="z-comment"> - The identifying salt for which the user wishes to deploy an Account Instance</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits AccountCreated event</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 for which the Account Instance 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"> createAccount</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> salt</span><span>)</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Allows an owner to claim a smart contract account created by this registry.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * If the account has not already been created, the account will be created first using `createAccount`</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"> owner</span><span class="z-comment"> - The initial owner of the new Account Instance</span></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"> - The identifying salt for which the user wishes to deploy an Account Instance</span></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"> - If expiration &gt; 0, represents expiration time for the signature. Otherwise</span></span> <span class="giallo-l"><span class="z-comment"> * signature does not expire.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> message</span><span class="z-comment"> - The keccak256 message which validates the owner, salt, expiration</span></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"> - The signature which validates the owner, salt, expiration</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits AccountClaimed event</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 claimed Account Instance</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"> claimAccount</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"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> expiration</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> message</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"> signature</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">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">@dev</span><span class="z-comment"> Returns the computed address of a smart contract account for a given identifying salt</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"> the</span><span class="z-comment"> computed address of the account</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"> account</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> salt</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">@dev</span><span class="z-comment"> Fallback signature verification for unclaimed accounts</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"> isValidSignature</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> hash</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 class="z-storage z-type"> view</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><h4 id="createaccount">createAccount</h4> <p><code>createAccount</code> is used to deploy the Account Instance for a given salt.</p> <ul> <li>This function MUST deploy a new Account Instance as a <a href="https://wg-eips.ritovision.com/1167/">ERC-1167</a> proxy pointing to the account implementation.</li> <li>This function SHOULD set the initial owner of the Account Instance to the Account Registry Instance.</li> <li>The account implementation address MUST be immutable, as it is used to compute the deterministic address for the Account Instance.</li> <li>Upon successful deployment of the Account Instance, the registry SHOULD emit an <code>AccountCreated</code> event.</li> </ul> <h4 id="claimaccount">claimAccount</h4> <p><code>claimAccount</code> is used to claim ownership of the Account Instance for a given salt.</p> <ul> <li>This function MUST create a new Account Instance if one does not already exist for the given salt.</li> <li>This function SHOULD verify that the msg.sender has permission to claim ownership over the Account Instance for the identifying salt and initial owner. Verification SHOULD be done by validating the message and signature against the owner, salt and expiration using ECDSA for EOA signers, or <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> for smart contract signers.</li> <li>This function SHOULD verify that the block.timestamp &lt; expiration or that expiration == 0.</li> <li>Upon successful signature verification on calls to <code>claimAccount</code>, the registry MUST completely relinquish control over the Account Instance, and assign ownership to the initial owner by calling <code>setOwner</code> on the Account Instance.</li> <li>Upon successful claim of the Account Instance, the registry SHOULD emit an <code>AccountClaimed</code> event.</li> </ul> <h4 id="isvalidsignature">isValidSignature</h4> <p><code>isValidSignature</code> is a fallback signature verification function used by unclaimed accounts. Valid signatures SHALL be generated by the registry signer by signing a composite hash of the original message hash, and the Account Instance address (e.g. <code>bytes32 compositeHash = keccak256(abi.encodePacked(originalHash, accountAddress))</code>). The function MUST reconstruct the composite hash, where <code>originalHash</code> is the hash passed to the function, and <code>accountAddress</code> is <code>msg.sender</code> (the unclaimed Account Instance). The function MUST verify the signature against the composite hash and registry signer.</p> <h3 id="account-instance">Account Instance</h3> <p>The Account Instance 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"> IAccount</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC1271</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"> Sets the owner of the Account Instance.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Only callable by the current owner of the instance, or by the registry if the Account</span></span> <span class="giallo-l"><span class="z-comment"> * Instance has not yet been claimed.</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"> owner</span><span class="z-comment"> - The new owner of the Account Instance</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"> setOwner</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></span></code></pre> <ul> <li>All Account Instances MUST be created using an Account Registry Instance.</li> <li>Account Instances SHOULD provide access to assets previously sent to the address at which the Account Instance is deployed to.</li> <li><code>setOwner</code> SHOULD update the owner and SHOULD be callable by the current owner of the Account Instance.</li> <li>If an Account Instance is deployed, but not claimed, the owner of the Account Instance MUST be initialized to the Account Registry Instance.</li> <li>An Account Instance SHALL determine if it has been claimed by checking if the owner is the Account Registry Instance.</li> </ul> <h4 id="account-instance-signatures">Account Instance Signatures</h4> <p>Account Instances MUST support <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> by implementing an <code>isValidSignature</code> function. When the owner of an Account Instance wants to sign a message (e.g. to log in to a dApp), the signature MUST be generated in one of the following ways, depending the state of the Account Instance:</p> <ol> <li>If the Account instance is deployed and claimed, the owner should generate the signature, and <code>isValidSignature</code> SHOULD verify that the message hash and signature are valid for the current owner of the Account Instance.</li> <li>If the Account Instance is deployed, but unclaimed, the registry signer should generate the signature using a composite hash of the original message and address of the Account Instance described <a href="https://wg-eips.ritovision.com/6981/#isvalidsignature">above</a>, and <code>isValidSignature</code> SHOULD forward the message hash and signature to the Account Registry Instance's <code>isValidSignature</code> function.</li> <li>If the Account Instance is not deployed, the registry signer should generate a signature on the composite hash as done in situation 2, and wrap the signature according to <a href="https://wg-eips.ritovision.com/6492/#signer-side">ERC-6492</a> (e.g. <code>concat(abi.encode((registryAddress, createAccountCalldata, compositeHashSignature), (address, bytes, bytes)), magicBytes)</code>).</li> </ol> <p>Signature validation for Account Instances should be done according to <a href="https://wg-eips.ritovision.com/6492/#verifier-side">ERC-6492</a>.</p> <h2 id="rationale">Rationale</h2> <h3 id="service-owned-registry-instances">Service-Owned Registry Instances</h3> <p>While it might seem more user-friendly to implement and deploy a universal registry for reserved ownership accounts, we believe that it is important for external service providers to have the option to own and control their own Account Registry. This provides the flexibility of implementing their own permission controls and account deployment authorization frameworks.</p> <p>We are providing a reference Registry Factory which can deploy Account Registries for an external service, which comes with:</p> <ul> <li>Immutable Account Instance implementation</li> <li>Validation for the <code>claimAccount</code> method via ECDSA for EOA signers, or <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> validation for smart contract signers</li> <li>Ability for the Account Registry deployer to change the signing addressed used for <code>claimAccount</code> validation</li> </ul> <h3 id="account-registry-and-account-implementation-coupling">Account Registry and Account Implementation Coupling</h3> <p>Since Account Instances are deployed as <a href="https://wg-eips.ritovision.com/1167/">ERC-1167</a> proxies, the account implementation address affects the addresses of accounts deployed from a given Account Registry. Requiring that registry instances be linked to a single, immutable account implementation ensures consistency between a user's salt and linked address on a given Account Registry Instance.</p> <p>This also allows services to gain the trust of users by deploying their registries with a reference to a trusted account implementation address.</p> <p>Furthermore, account implementations can be designed as upgradeable, so users are not necessarily bound to the implementation specified by the Account Registry Instance used to create their account.</p> <h3 id="separate-createaccount-and-claimaccount-operations">Separate <code>createAccount</code> and <code>claimAccount</code> Operations</h3> <p>Operations to create and claim Account Instances are intentionally separate. This allows services to provide users with valid <a href="https://wg-eips.ritovision.com/6492/">ERC-6492</a> signatures before their Account Instance has been deployed.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The following is an example of an Account Registry Factory which can be used by external service providers to deploy their own Account Registry Instance.</p> <h3 id="account-registry-factory">Account Registry Factory</h3> <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-comment">///</span><span class="z-storage z-type"> @author</span><span class="z-comment">: manifold.xyz</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Create2</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/utils/Create2.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Address</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;../../lib/Address.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">ERC1167ProxyBytecode</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;../../lib/ERC1167ProxyBytecode.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IAccountRegistryFactory</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./IAccountRegistryFactory.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"> AccountRegistryFactory</span><span class="z-storage"> is</span><span class="z-entity z-name"> IAccountRegistryFactory</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> Address</span><span class="z-keyword"> for</span><span class="z-entity z-name"> address</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> InitializationFailed</span><span>(</span><span>)</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 class="z-storage z-type"> immutable</span><span> registryImplementation </span><span class="z-keyword">=</span><span class="z-constant"> 0x076B08EDE2B28fab0c1886F029cD6d02C8fF0E94</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"> createRegistry</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint96</span><span class="z-variable"> index</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> accountImplementation</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"> accountInitData</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">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> salt </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getSalt</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> index</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> code </span><span class="z-keyword">=</span><span> ERC1167ProxyBytecode</span><span>.</span><span class="z-entity z-name">createCode</span><span>(</span><span>registryImplementation</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> _registry </span><span class="z-keyword">=</span><span> Create2</span><span>.</span><span class="z-entity z-name">computeAddress</span><span>(</span><span>salt</span><span>,</span><span class="z-support"> keccak256</span><span>(</span><span>code</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>_registry</span><span>.</span><span class="z-entity z-name">isDeployed</span><span>(</span><span>)</span><span>)</span><span class="z-keyword"> return</span><span> _registry</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _registry </span><span class="z-keyword">=</span><span> Create2</span><span>.</span><span class="z-entity z-name">deploy</span><span>(</span><span class="z-constant">0</span><span>,</span><span> salt</span><span>,</span><span> code</span><span>)</span><span>;</span></span> <span class="giallo-l"></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> _registry</span><span>.</span><span class="z-entity z-name">call</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSignature</span><span>(</span></span> <span class="giallo-l"><span class="z-string"> &quot;initialize(address,address,bytes)&quot;</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> accountImplementation</span><span>,</span></span> <span class="giallo-l"><span> accountInitData</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-keyword">!</span><span>success</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> InitializationFailed</span><span>(</span><span>)</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"> AccountRegistryCreated</span><span>(</span><span>_registry</span><span>,</span><span> accountImplementation</span><span>,</span><span> index</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _registry</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"> registry</span><span>(</span><span class="z-support">address</span><span class="z-variable"> deployer</span><span>,</span><span class="z-support"> uint96</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-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-support"> bytes32</span><span> salt </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getSalt</span><span>(</span><span>deployer</span><span>,</span><span> index</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> code </span><span class="z-keyword">=</span><span> ERC1167ProxyBytecode</span><span>.</span><span class="z-entity z-name">createCode</span><span>(</span><span>registryImplementation</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> Create2</span><span>.</span><span class="z-entity z-name">computeAddress</span><span>(</span><span>salt</span><span>,</span><span class="z-support"> keccak256</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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _getSalt</span><span>(</span><span class="z-support">address</span><span class="z-variable"> deployer</span><span>,</span><span class="z-support"> uint96</span><span class="z-variable"> index</span><span>)</span><span class="z-storage z-type"> private</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"> bytes32</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>deployer</span><span>,</span><span> index</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="account-registry-1">Account Registry</h3> <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-comment">///</span><span class="z-storage z-type"> @author</span><span class="z-comment">: manifold.xyz</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Create2</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/utils/Create2.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">ECDSA</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/utils/cryptography/ECDSA.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Ownable</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/access/Ownable.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Initializable</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/proxy/utils/Initializable.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IERC1271</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/interfaces/IERC1271.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">SignatureChecker</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/utils/cryptography/SignatureChecker.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Address</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;../../lib/Address.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IAccountRegistry</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;../../interfaces/IAccountRegistry.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">ERC1167ProxyBytecode</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;../../lib/ERC1167ProxyBytecode.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"> AccountRegistryImplementation</span><span class="z-storage"> is</span><span class="z-entity z-name"> Ownable</span><span>, </span><span class="z-entity z-name">Initializable</span><span>, </span><span class="z-entity z-name">IAccountRegistry</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> Address</span><span class="z-keyword"> for</span><span class="z-entity z-name"> address</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> ECDSA</span><span class="z-keyword"> for</span><span class="z-entity z-name"> bytes32</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"> Signer</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 class="z-support"> bool</span><span> isContract</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"> error</span><span class="z-entity z-name"> InitializationFailed</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ClaimFailed</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> Unauthorized</span><span>(</span><span>)</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"> public</span><span> accountImplementation</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> public</span><span> accountInitData</span><span>;</span></span> <span class="giallo-l"><span> Signer </span><span class="z-storage z-type">public</span><span> signer</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> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _disableInitializers</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"> initialize</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"> address</span><span class="z-variable"> accountImplementation_</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"> accountInitData_</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> initializer</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _transferOwnership</span><span>(</span><span>owner</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> accountImplementation </span><span class="z-keyword">=</span><span> accountImplementation_</span><span>;</span></span> <span class="giallo-l"><span> accountInitData </span><span class="z-keyword">=</span><span> accountInitData_</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 {IAccountRegistry-createAccount}</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"> createAccount</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> salt</span><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">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> code </span><span class="z-keyword">=</span><span> ERC1167ProxyBytecode</span><span>.</span><span class="z-entity z-name">createCode</span><span>(</span><span>accountImplementation</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> _account </span><span class="z-keyword">=</span><span> Create2</span><span>.</span><span class="z-entity z-name">computeAddress</span><span>(</span><span class="z-support">bytes32</span><span>(</span><span>salt</span><span>)</span><span>,</span><span class="z-support"> keccak256</span><span>(</span><span>code</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>_account</span><span>.</span><span class="z-entity z-name">isDeployed</span><span>(</span><span>)</span><span>)</span><span class="z-keyword"> return</span><span> _account</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _account </span><span class="z-keyword">=</span><span> Create2</span><span>.</span><span class="z-entity z-name">deploy</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-support"> bytes32</span><span>(</span><span>salt</span><span>)</span><span>,</span><span> code</span><span>)</span><span>;</span></span> <span class="giallo-l"></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> _account</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span>accountInitData</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>success</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> InitializationFailed</span><span>(</span><span>)</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"> AccountCreated</span><span>(</span><span>_account</span><span>,</span><span> accountImplementation</span><span>,</span><span> salt</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _account</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 {IAccountRegistry-claimAccount}</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"> claimAccount</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"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> expiration</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> message</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"> signature</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">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _verify</span><span>(</span><span>owner</span><span>,</span><span> salt</span><span>,</span><span> expiration</span><span>,</span><span> message</span><span>,</span><span> signature</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> _account </span><span class="z-keyword">=</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">createAccount</span><span>(</span><span>salt</span><span>)</span><span>;</span></span> <span class="giallo-l"></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> _account</span><span>.</span><span class="z-entity z-name">call</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSignature</span><span>(</span><span class="z-string">&quot;transferOwnership(address)&quot;</span><span>,</span><span> owner</span><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-keyword">!</span><span>success</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> ClaimFailed</span><span>(</span><span>)</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"> AccountClaimed</span><span>(</span><span>_account</span><span>,</span><span> owner</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _account</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 {IAccountRegistry-account}</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"> account</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> salt</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"> 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-support"> bytes</span><span class="z-storage z-type"> memory</span><span> code </span><span class="z-keyword">=</span><span> ERC1167ProxyBytecode</span><span>.</span><span class="z-entity z-name">createCode</span><span>(</span><span>accountImplementation</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> Create2</span><span>.</span><span class="z-entity z-name">computeAddress</span><span>(</span><span class="z-support">bytes32</span><span>(</span><span>salt</span><span>)</span><span>,</span><span class="z-support"> keccak256</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 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 {IAccountRegistry-isValidSignature}</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"> isValidSignature</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> hash</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 class="z-storage z-type"> view</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-support"> bytes32</span><span> expectedHash </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>hash</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-support"> bool</span><span> isValid </span><span class="z-keyword">=</span><span> SignatureChecker</span><span>.</span><span class="z-entity z-name">isValidSignatureNow</span><span>(</span></span> <span class="giallo-l"><span> signer</span><span>.</span><span>account</span><span>,</span></span> <span class="giallo-l"><span> expectedHash</span><span>,</span></span> <span class="giallo-l"><span> signature</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>isValid</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> IERC1271</span><span>.</span><span>isValidSignature</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-keyword"> return</span><span class="z-string"> &quot;&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"> updateSigner</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newSigner</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-support"> uint32</span><span> signerSize</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> signerSize </span><span class="z-keyword">:=</span><span class="z-entity z-name"> extcodesize</span><span>(</span><span>newSigner</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> signer</span><span>.</span><span>account </span><span class="z-keyword">=</span><span> newSigner</span><span>;</span></span> <span class="giallo-l"><span> signer</span><span>.</span><span>isContract </span><span class="z-keyword">=</span><span> signerSize </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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _verify</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"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> expiration</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> message</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"> signature</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> view</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> signatureAccount</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>signer</span><span>.</span><span>isContract</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>SignatureChecker</span><span>.</span><span class="z-entity z-name">isValidSignatureNow</span><span>(</span><span>signer</span><span>.</span><span>account</span><span>,</span><span> message</span><span>,</span><span> signature</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> Unauthorized</span><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> signatureAccount </span><span class="z-keyword">=</span><span> message</span><span>.</span><span class="z-entity z-name">recover</span><span>(</span><span>signature</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-support"> bytes32</span><span> expectedMessage </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-string">&quot;\x19Ethereum Signed Message:\n84&quot;</span><span>,</span><span> owner</span><span>,</span><span> salt</span><span>,</span><span> expiration</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-keyword"> if</span><span> (</span></span> <span class="giallo-l"><span> message </span><span class="z-keyword">!=</span><span> expectedMessage </span><span class="z-keyword">||</span></span> <span class="giallo-l"><span> (</span><span class="z-keyword">!</span><span>signer</span><span>.</span><span>isContract </span><span class="z-keyword">&amp;&amp;</span><span> signatureAccount </span><span class="z-keyword">!=</span><span> signer</span><span>.</span><span>account</span><span>)</span><span class="z-keyword"> ||</span></span> <span class="giallo-l"><span> (</span><span>expiration </span><span class="z-keyword">!=</span><span class="z-constant"> 0</span><span class="z-keyword"> &amp;&amp;</span><span> expiration </span><span class="z-keyword">&lt;</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</span><span>)</span></span> <span class="giallo-l"><span> )</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> Unauthorized</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="example-account-implementation">Example Account Implementation</h3> <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-comment">///</span><span class="z-storage z-type"> @author</span><span class="z-comment">: manifold.xyz</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IERC1271</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/interfaces/IERC1271.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">SignatureChecker</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/utils/cryptography/SignatureChecker.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IERC165</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/utils/introspection/IERC165.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">ERC165Checker</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/utils/introspection/ERC165Checker.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IERC721</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/token/ERC721/IERC721.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IERC721Receiver</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/token/ERC721/IERC721Receiver.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IERC1155Receiver</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/token/ERC1155/IERC1155Receiver.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Initializable</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/proxy/utils/Initializable.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Ownable</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;openzeppelin/access/Ownable.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IERC1967Account</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./IERC1967Account.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IAccount</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;../../interfaces/IAccount.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"> ERC1967AccountImplementation</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> A lightweight, upgradeable smart contract wallet 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"> ERC1967AccountImplementation</span><span class="z-storage"> is</span></span> <span class="giallo-l"><span class="z-entity z-name"> IAccount</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC165</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC721Receiver</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC1155Receiver</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC1967Account</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> Initializable</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> Ownable</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> registry</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> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _disableInitializers</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"> initialize</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> initializer</span><span> {</span></span> <span class="giallo-l"><span> registry </span><span class="z-keyword">=</span><span class="z-variable z-language"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _transferOwnership</span><span>(</span><span>registry</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"> 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> (</span><span>interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IAccount</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>IERC1967Account</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>IERC1155Receiver</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 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>IERC165</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 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>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span></span> <span class="giallo-l"><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"> this</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"> onERC1155Received</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>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span></span> <span class="giallo-l"><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"> this</span><span>.</span><span>onERC1155Received</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"> onERC1155BatchReceived</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>,</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>,</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>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span></span> <span class="giallo-l"><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"> this</span><span>.</span><span>onERC1155BatchReceived</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-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 IERC1967Account-executeCall}</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"> executeCall</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _target</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"> bytes</span><span class="z-storage z-type"> calldata</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-storage z-type"> payable</span><span class="z-storage z-type"> override</span><span class="z-entity z-name"> onlyOwner</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 z-parameter z-function"> _result</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> success</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-keyword"> solhint-disable</span><span class="z-comment">-next-line avoid-low-level-calls</span></span> <span class="giallo-l"><span> (</span><span>success</span><span>,</span><span> _result</span><span>)</span><span class="z-keyword"> =</span><span> _target</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span> _value</span><span>}</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-support"> string</span><span>(</span><span>_result</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> TransactionExecuted</span><span>(</span><span>_target</span><span>,</span><span> _value</span><span>,</span><span> _data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _result</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 IAccount-setOwner}</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"> setOwner</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-storage z-type"> override</span><span class="z-entity z-name"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _transferOwnership</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-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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isValidSignature</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> hash</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 class="z-storage z-type"> view</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"> if</span><span> (</span><span class="z-entity z-name">owner</span><span>(</span><span>)</span><span class="z-keyword"> ==</span><span> registry</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> IERC1271</span><span>(</span><span>registry</span><span>)</span><span>.</span><span class="z-entity z-name">isValidSignature</span><span>(</span><span>hash</span><span>,</span><span> signature</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-support"> bool</span><span> isValid </span><span class="z-keyword">=</span><span> SignatureChecker</span><span>.</span><span class="z-entity z-name">isValidSignatureNow</span><span>(</span><span class="z-entity z-name">owner</span><span>(</span><span>)</span><span>,</span><span> hash</span><span>,</span><span> signature</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>isValid</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> IERC1271</span><span>.</span><span>isValidSignature</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-keyword"> return</span><span class="z-string"> &quot;&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> <h3 id="front-running">Front-running</h3> <p>Deployment of reserved ownership accounts through an Account Registry Instance through calls to <code>createAccount</code> could be front-run by a malicious actor. However, if the malicious actor attempted to alter the <code>owner</code> parameter in the calldata, the Account Registry Instance would find the signature to be invalid, and revert the transaction. Thus, any successful front-running transaction would deploy an identical Account Instance to the original transaction, and the original owner would still gain control over the address.</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-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 William Morrisshttps://github.com/wjmelements https://wg-eips.ritovision.com/6913/

new instruction to replace code in-place

<h2 id="abstract">Abstract</h2> <p>Introduce the <code>SETCODE</code> (<code>0xfc</code>) instruction, which replaces the code of the executing account from memory.</p> <h2 id="motivation">Motivation</h2> <p>Many contracts are upgradeable in order to facilitate improvement or defer decisions without migrating to a new address. Contracts presently do this in several ways:</p> <p>The oldest method uses <code>CALL</code>. The limitation of this method is that internal state must be modifiable by all future implementations.</p> <p>Second, <code>DELEGATECALL</code> can proxy the implementation. Some proxies are minimal while others branch to many separate implementation accounts. This method can also bypass account code size limits.</p> <p>A third method uses <code>SELFDESTRUCT</code> and <code>CREATE2</code> to replace code in-place. This method improves upon the prior methods by removing the need to call into external contracts. One limitation of this method is that any internal state is removed by <code>SELFDESTRUCT</code>. Another limitation is that <code>SELFDESTRUCT</code> does not remove code until the end of the transaction, sacrificing availability until <code>CREATE2</code> can complete the upgrade.</p> <p>Given the upcoming deprecation of <code>SELFDESTRUCT</code>, <code>SETCODE</code> introduces a better method for replacing code in-place.</p> <h2 id="specification">Specification</h2> <p>When within a read-only execution scope like the recursive kind created by <code>STATICCALL</code>, <code>SETCODE</code> causes an exceptional abort.</p> <p>When the currently executing code does not equal the code of the executing account, such as can happen inside of <code>DELEGATECALL</code> or <code>CREATE</code>, <code>SETCODE</code> causes an exceptional abort.</p> <p>Otherwise, <code>SETCODE</code> consumes two words from the stack: offset and length. These specify a range of memory containing the new code. Any validations that would be performed on the result of <code>CREATE</code> or <code>CREATE2</code> occur immediately, potentially causing failure with exceptional abort. The operations <code>EXTCODESIZE</code> and <code>EXTCODECOPY</code> now query the updated code, and message-calls such as <code>DELEGATECALL</code>, <code>CALLCODE</code>, <code>CALL</code>, and <code>STATICCALL</code> now execute the updated code. Any execution scopes already executing replaced code, including the one that <code>SETCODE</code>, will continue executing the prior code. Inside such scopes, <code>CODESIZE</code> and <code>CODECOPY</code> continue to query the executing code.</p> <p>Like <code>SSTORE</code>, this account modification will be reverted if the current scope or any parent scope reverts or aborts.</p> <p>Unlike <code>SELFDESTRUCT</code>, <code>SETCODE</code> does not clear account balance, nonce, or storage.</p> <h3 id="gas">Gas</h3> <p>The gas cost of this operation is the sum of <code>Gselfdestruct</code> and the product of <code>Gcodedeposit</code> and the number of bytes in the new code.</p> <h2 id="rationale">Rationale</h2> <p>The behavior of <code>CODECOPY</code>, <code>CODESIZE</code>, <code>EXTCODESIZE</code>, and <code>EXTCODECOPY</code> match the behavior of <code>DELEGATECALL</code> and <code>CREATE</code>, where it is also possible for executing code to differ from the code of the executing account.</p> <p>The gas cost of <code>SETCODE</code> is comparable to <code>CREATE</code> but excludes <code>Gcreate</code> because no execution context is created, nor any new account. Other account modification costs are accounted for outside of execution gas.</p> <p>Unlike <code>SELFDESTRUCT</code>, execution proceeds normally after <code>SETCODE</code> in order to allow validation and return data. Post-update validation can undo a <code>SETCODE</code> operation with <code>REVERT</code>, or with a recursive <code>SETCODE</code>, but <code>REVERT</code> uses less gas.</p> <p>Preventing <code>SETCODE</code> within most <code>DELEGATECALL</code> allows static analysis to easily identify mutable code. Account code not containing the <code>SETCODE</code> operation can be safely assumed to be immutable. Code observed in a non-reverting context to be immutable will remain immutable, allowing on-chain static analysis for immutability.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The only prior operation changing code is <code>SELFDESTRUCT</code>. As code modification via <code>SELFDESTRUCT</code> is deferred until the end of the transaction, its interactions with <code>SETCODE</code> are well-defined.</p> <h2 id="test-cases">Test Cases</h2> <table><thead><tr><th>CodeStart</th><th>CallData</th><th>CodeResult</th><th>Gas</th></tr></thead><tbody> <tr><td>365f5f37365ffc00</td><td>365f5f37365ffc00</td><td>365f5f37365ffc00</td><td>6613</td></tr> <tr><td>365f5f37365ffc00</td><td>00</td><td>00</td><td>5213</td></tr> <tr><td>365f5f37365ffc00</td><td></td><td></td><td>5013</td></tr> <tr><td>365f5f37365ffc595ffd</td><td>365f5f37365ffc00</td><td>365f5f37365ffc595ffd</td><td>6617</td></tr> <tr><td>365f5f37365ffcfe</td><td>365f5f37365ffc00</td><td>365f5f37365ffcfe</td><td>all</td></tr> </tbody></table> <h2 id="security-considerations">Security Considerations</h2> <p>Risks related to <code>SETCODE</code> similarly apply to other upgrade patterns.</p> <p>Most contracts should never be replaced and should not be upgradeable. Any upgrade mechanism can risk permanent failure. The possibility of upgrade perpetuates such risk.</p> <p>Access to upgrade operations should be restricted. Upgrades should never be performed in a hurry or when tired. Upgrades should be tested under as similar conditions to production as possible; discrepancies are sources of unexpected results. When possible, multiple engineers should preview and independently verify pending upgrade procedures.</p> <p>Block explorers, wallets, and other interfaces should flag upgradeable code. Client software should warn against approving <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> or <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens for upgradeable accounts.</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:48:25+00:00 JT Rileyhttps://github.com/jtriley2p Dillonhttps://github.com/d1ll0n Sarahttps://github.com/snreynolds Vectorizedhttps://github.com/Vectorized Neodaoisthttps://github.com/neodaoist https://wg-eips.ritovision.com/6909/

A minimal specification for managing multiple tokens by their id in a single contract.

<h2 id="abstract">Abstract</h2> <p>The following specifies a multi-token contract as a simplified alternative to the <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> Multi-Token Standard. In contrast to ERC-1155, callbacks and batching have been removed from the interface and the permission system is a hybrid operator-approval scheme for granular and scalable permissions. Functionally, the interface has been reduced to the bare minimum required to manage multiple tokens under the same contract.</p> <h2 id="motivation">Motivation</h2> <p>The ERC-1155 standard includes unnecessary features such as requiring recipient accounts with code to implement callbacks returning specific values and batch-calls in the specification. In addition, the single operator permission scheme grants unlimited allowance on every token ID in the contract. Backwards compatibility is deliberately removed only where necessary. Additional features such as batch calls, increase and decrease allowance methods, and other user experience improvements are deliberately omitted in the specification to minimize the required external interface.</p> <p>According to ERC-1155, callbacks are required for each transfer and batch transfer to contract accounts. This requires potentially unnecessary external calls to the recipient when the recipient account is a contract account. While this behavior may be desirable in some cases, there is no option to opt-out of this behavior, as is the case for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> having both <code>transferFrom</code> and <code>safeTransferFrom</code>. In addition to runtime performance of the token contract itself, it also impacts the runtime performance and codesize of recipient contract accounts, requiring multiple callback functions and return values to receive the tokens.</p> <p>Batching transfers, while useful, are excluded from this standard to allow for opinionated batch transfer operations on different implementations. For example, a different ABI encoding may provide different benefits in different environments such as calldata size optimization for rollups with calldata storage commitments or runtime performance for environments with expensive gas fees.</p> <p>A hybrid allowance-operator permission scheme enables granular yet scalable controls on token approvals. Allowances enable an external account to transfer tokens of a single token ID on a user's behalf w by their ID while operators are granted full transfer permission for all token IDs for the user.</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>Every <a href="https://wg-eips.ritovision.com/6909/">ERC-6909</a> compliant contract must implement the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface in addition to the following interface.</p> <h3 id="definitions">Definitions</h3> <ul> <li>infinite: The maximum value for a uint256 (<code>2 ** 256 - 1</code>).</li> <li>caller: The caller of the current context (<code>msg.sender</code>).</li> <li>spender: An account that transfers tokens on behalf of another account.</li> <li>operator: An account that has unlimited transfer permissions on all token ids for another account.</li> <li>mint: The creation of an amount of tokens. This MAY happen in a mint method or as a transfer from the zero address.</li> <li>burn: The removal an amount of tokens. This MAY happen in a burn method or as a transfer to the zero address.</li> </ul> <h3 id="methods">Methods</h3> <h4 id="balanceof"><code>balanceOf</code></h4> <p>The total <code>amount</code> of a token <code>id</code> that an <code>owner</code> owns.</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">alanceOf</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"> 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"> i</span><span class="z-string">d</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">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></code></pre><h4 id="allowance"><code>allowance</code></h4> <p>The total <code>amount</code> of a token <code>id</code> that a <code>spender</code> is permitted to transfer on behalf of an <code>owner</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"> a</span><span class="z-string">llowance</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"> 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"> s</span><span class="z-string">pender</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">d</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">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></code></pre><h4 id="isoperator"><code>isOperator</code></h4> <p>Returns <code>true</code> if the <code>spender</code> is approved as an operator for an <code>owner</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">sOperator</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"> 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"> s</span><span class="z-string">pender</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"> s</span><span class="z-string">tatus</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="transfer"><code>transfer</code></h4> <p>Transfers an <code>amount</code> of a token <code>id</code> from the caller to the <code>receiver</code>.</p> <p>MUST revert when the caller's balance for the token <code>id</code> is insufficient.</p> <p>MUST log the <code>Transfer</code> event.</p> <p>MUST return True.</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"> 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"> 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"> 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"> i</span><span class="z-string">d</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"> 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> <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">uccess</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="transferfrom"><code>transferFrom</code></h4> <p>Transfers an <code>amount</code> of a token <code>id</code> from a <code>sender</code> to a <code>receiver</code> by the caller.</p> <p>MUST revert when the caller is neither the <code>sender</code> nor an operator for the <code>sender</code> and the caller's allowance for the token <code>id</code> for the <code>sender</code> is insufficient.</p> <p>MUST revert when the <code>sender</code>'s balance for the token id is insufficient.</p> <p>MUST log the <code>Transfer</code> event.</p> <p>MUST decrease the caller's <code>allowance</code> by the same <code>amount</code> of the <code>sender</code>'s balance decrease if the caller is not an operator for the <code>sender</code> and the caller's <code>allowance</code> is not infinite.</p> <p>SHOULD NOT decrease the caller's <code>allowance</code> for the token <code>id</code> for the <code>sender</code> if the <code>allowance</code> is infinite.</p> <p>SHOULD NOT decrease the caller's <code>allowance</code> for the token <code>id</code> for the <code>sender</code> if the caller is an operator or the <code>sender</code>.</p> <p>MUST return True.</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"> t</span><span class="z-string">ransferFrom</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">ender</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"> 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"> i</span><span class="z-string">d</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"> 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> <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">uccess</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="approve"><code>approve</code></h4> <p>Approves an <code>amount</code> of a token <code>id</code> that a <code>spender</code> is permitted to transfer on behalf of the caller.</p> <p>MUST set the <code>allowance</code> of the <code>spender</code> of the token <code>id</code> for the caller to the <code>amount</code>.</p> <p>MUST log the <code>Approval</code> event.</p> <p>MUST return True.</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"> a</span><span class="z-string">pprove</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">pender</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">d</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"> 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> <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">uccess</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="setoperator"><code>setOperator</code></h4> <p>Grants or revokes unlimited transfer permissions for a <code>spender</code> for any token <code>id</code> on behalf of the caller.</p> <p>MUST set the operator status to the <code>approved</code> value.</p> <p>MUST log the <code>OperatorSet</code> event.</p> <p>MUST return True.</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"> s</span><span class="z-string">etOperator</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">pender</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">pproved</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 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">uccess</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="transfer-1"><code>Transfer</code></h4> <p>The <code>caller</code> initiates a transfer of an <code>amount</code> of a token <code>id</code> from a <code>sender</code> to a <code>receiver</code>.</p> <p>MUST be logged when an <code>amount</code> of a token <code>id</code> is transferred from one account to another.</p> <p>MUST be logged with the <code>sender</code> address as the zero address when an <code>amount</code> of a token <code>id</code> is minted.</p> <p>MUST be logged with the <code>receiver</code> address as the zero address when an <code>amount</code> of a token <code>id</code> is burned.</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"> 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"> 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"> c</span><span class="z-string">aller</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"> s</span><span class="z-string">ender</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"> r</span><span class="z-string">eceiver</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">d</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"> 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><h4 id="operatorset"><code>OperatorSet</code></h4> <p>The <code>owner</code> has set the <code>approved</code> status to a <code>spender</code>.</p> <p>MUST be logged when the operator status is set.</p> <p>MAY be logged when the operator status is set to the same status it was before the current call.</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"> O</span><span class="z-string">peratorSet</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"> o</span><span class="z-string">wner</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"> s</span><span class="z-string">pender</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">pproved</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="approval"><code>Approval</code></h4> <p>The <code>owner</code> has approved a <code>spender</code> to transfer an <code>amount</code> of a token <code>id</code> to be transferred on the owner's behalf.</p> <p>MUST be logged when the <code>allowance</code> is set by an <code>owner</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"> A</span><span class="z-string">pproval</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"> o</span><span class="z-string">wner</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"> s</span><span class="z-string">pender</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">d</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"> 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><h3 id="interface-id">Interface ID</h3> <p>The interface ID is <code>0x0f632fb3</code>.</p> <h3 id="metadata-extension">Metadata Extension</h3> <h4 id="methods-1">Methods</h4> <h5 id="name">name</h5> <p>The <code>name</code> for a token <code>id</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"> n</span><span class="z-string">ame</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">d</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"> n</span><span class="z-string">ame</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></code></pre><h5 id="symbol">symbol</h5> <p>The ticker <code>symbol</code> for a token <code>id</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"> s</span><span class="z-string">ymbol</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">d</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">ymbol</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></code></pre><h5 id="decimals">decimals</h5> <p>The <code>amount</code> of decimals for a token <code>id</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">ecimals</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">d</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">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">int8</span></span></code></pre><h3 id="content-uri-extension">Content URI Extension</h3> <h4 id="methods-2">Methods</h4> <h5 id="contracturi">contractURI</h5> <p>The <code>URI</code> for the contract.</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">ontractURI</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">ri</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></code></pre><h5 id="tokenuri">tokenURI</h5> <p>The <code>URI</code> for a token <code>id</code>.</p> <p>MAY revert if the token <code>id</code> does not exist.</p> <p>MUST replace occurrences of <code>{id}</code> in the returned URI string by the client.</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"> t</span><span class="z-string">okenURI</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">d</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">ri</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></code></pre><h4 id="metadata-structure">Metadata Structure</h4> <h5 id="contract-uri">Contract URI</h5> <p>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">Contract 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">The name of the contract.</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">The description of the contract.</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_url</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">The URL of the image representing the contract.</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">banner_image_url</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">The URL of the banner image of the contract.</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">external_link</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">The external link of the contract.</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">editors</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">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">An Ethereum address representing an authorized editor of the contract.</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">An array of Ethereum addresses representing editors (authorized editors) of the contract.</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">animation_url</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">An animation URL for the 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></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 class="giallo-l"><span>}</span></span></code></pre> <p>JSON Example (Minimal):</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 Contract Name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="token-uri">Token URI</h5> <p>MUST replace occurrences of <code>{id}</code> in the returned URI string by the client.</p> <p>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 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 token</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 token</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 an image resource.</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">animation_url</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">An animation URL for the token.</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">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">description</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">image</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>JSON Example (Minimal):</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 Token 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">Example Token Description</span><span class="z-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">exampleurl/{id}</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="token-supply-extension">Token Supply Extension</h3> <h4 id="methods-3">Methods</h4> <h5 id="totalsupply">totalSupply</h5> <p>The <code>totalSupply</code> for a token <code>id</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"> t</span><span class="z-string">otalSupply</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">d</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">upply</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> <h3 id="granular-approvals">Granular Approvals</h3> <p>While the "operator model" from the ERC-1155 standard allows an account to set another account as an operator, giving full permissions to transfer any amount of any token id on behalf of the owner, this may not always be the desired permission scheme. The "allowance model" from <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> allows an account to set an explicit amount of the token that another account can spend on the owner's behalf. This standard requires both be implemented, with the only modification being to the "allowance model" where the token id must be specified as well. This allows an account to grant specific approvals to specific token ids, infinite approvals to specific token ids, or infinite approvals to all token ids.</p> <h3 id="removal-of-batching">Removal of Batching</h3> <p>While batching operations is useful, its place should not be in the standard itself, but rather on a case-by-case basis. This allows for different tradeoffs to be made in terms of calldata layout, which may be especially useful for specific applications such as roll-ups that commit calldata to global storage.</p> <h3 id="removal-of-required-callbacks">Removal of Required Callbacks</h3> <p>Requiring callbacks unnecessarily encumbers implementors that either have no particular use case for callbacks or prefer a bespoke callback mechanism. Minimization of such requirements saves contract size, gas efficiency and complexity.</p> <h3 id="removal-of-safe-naming">Removal of "Safe" Naming</h3> <p>The <code>safeTransfer</code> and <code>safeTransferFrom</code> naming conventions are misleading, especially in the context of the ERC-1155 and ERC-721 standards, as they require external calls to receiver accounts with code, passing the execution flow to an arbitrary contract, provided the receiver contract returns a specific value. The combination of removing mandatory callbacks and removing the word "safe" from all method names improves the safety of the control flow by default.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is not backwards compatible with ERC-1155 as some methods are removed. However, wrappers can be implemented for the ERC-20, ERC-721, and ERC-1155 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"> 0.8.19</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"> ERC6909 Multi-Token Reference Implementation</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @author</span><span class="z-comment"> jtriley.eth</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC6909</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"> Thrown when owner balance for id is 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"> owner</span><span class="z-comment"> The address of 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"> id</span><span class="z-comment"> The id of the token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> InsufficientBalance</span><span>(</span><span class="z-support">address</span><span> owner</span><span>,</span><span class="z-support"> uint256</span><span> 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"> @dev</span><span class="z-comment"> Thrown when spender allowance for id is 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"> spender</span><span class="z-comment"> The address of the 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"> id</span><span class="z-comment"> The id of the token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> InsufficientPermission</span><span>(</span><span class="z-support">address</span><span> spender</span><span>,</span><span class="z-support"> uint256</span><span> 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"> The event emitted when a transfer occurs.</span></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 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"> receiver</span><span class="z-comment"> The address of the 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"> id</span><span class="z-comment"> The id of 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"> amount</span><span class="z-comment"> The amount of the token.</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-variable"> caller</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"> receiver</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"> 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"> @notice</span><span class="z-comment"> The event emitted when an operator is 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"> owner</span><span class="z-comment"> The address of 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"> spender</span><span class="z-comment"> The address of the 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"> approved</span><span class="z-comment"> The approval status.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> OperatorSet</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">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 class="z-storage z-type"> @notice</span><span class="z-comment"> The event emitted when an approval occurs.</span></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"> The address of 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"> spender</span><span class="z-comment"> The address of the 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"> id</span><span class="z-comment"> The id of 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"> amount</span><span class="z-comment"> The amount of the token.</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"> 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"> @notice</span><span class="z-comment"> Owner balance of an id.</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span> owner </span><span class="z-keyword">=&gt;</span><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint256</span><span> id </span><span class="z-keyword">=&gt;</span><span class="z-support"> uint256</span><span> amount</span><span>)</span><span>)</span><span class="z-storage z-type"> public</span><span> balanceOf</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"> Spender allowance of an id.</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span> owner </span><span class="z-keyword">=&gt;</span><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span> spender </span><span class="z-keyword">=&gt;</span><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint256</span><span> id </span><span class="z-keyword">=&gt;</span><span class="z-support"> uint256</span><span> amount</span><span>)</span><span>)</span><span>)</span><span class="z-storage z-type"> public</span><span> allowance</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"> Checks if a spender is approved by an owner as an operator.</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span> owner </span><span class="z-keyword">=&gt;</span><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span> spender </span><span class="z-keyword">=&gt;</span><span class="z-support"> bool</span><span>)</span><span>)</span><span class="z-storage z-type"> public</span><span> isOperator</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"> Transfers an amount of an id from the caller to a 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"> receiver</span><span class="z-comment"> The address of the 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"> id</span><span class="z-comment"> The id of 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"> amount</span><span class="z-comment"> The amount of the token.</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"> receiver</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-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"> if</span><span> (</span><span>balanceOf</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> &lt;</span><span> amount</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> InsufficientBalance</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> id</span><span>)</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>[</span><span>id</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span> balanceOf</span><span>[</span><span>receiver</span><span>]</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> amount</span><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 class="z-variable z-language"> msg.sender</span><span>,</span><span> receiver</span><span>,</span><span> id</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> <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"> Transfers an amount of an id from a sender to a 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"> sender</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"> receiver</span><span class="z-comment"> The address of the 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"> id</span><span class="z-comment"> The id of 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"> amount</span><span class="z-comment"> The amount of the token.</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"> sender</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"> id</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-keyword"> returns</span><span> (</span><span class="z-support">bool</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-variable z-language"> msg.sender</span><span class="z-keyword"> &amp;&amp;</span><span class="z-keyword"> !</span><span>isOperator</span><span>[</span><span>sender</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-support"> uint256</span><span> senderAllowance </span><span class="z-keyword">=</span><span> allowance</span><span>[</span><span>sender</span><span>]</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>id</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>senderAllowance </span><span class="z-keyword">&lt;</span><span> amount</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> InsufficientPermission</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> id</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>senderAllowance </span><span class="z-keyword">!=</span><span class="z-variable z-language"> type</span><span>(</span><span class="z-support">uint256</span><span>)</span><span>.</span><span>max</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> allowance</span><span>[</span><span>sender</span><span>]</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> =</span><span> senderAllowance </span><span class="z-keyword">-</span><span> amount</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>balanceOf</span><span>[</span><span>sender</span><span>]</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> &lt;</span><span> amount</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> InsufficientBalance</span><span>(</span><span>sender</span><span>,</span><span> id</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> balanceOf</span><span>[</span><span>sender</span><span>]</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span> balanceOf</span><span>[</span><span>receiver</span><span>]</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> amount</span><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> sender</span><span>,</span><span> receiver</span><span>,</span><span> id</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> <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"> Approves an amount of an id to a 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"> spender</span><span class="z-comment"> The address of the 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"> id</span><span class="z-comment"> The id of 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"> amount</span><span class="z-comment"> The amount of the token.</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"> id</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-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> allowance</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>spender</span><span>]</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> =</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><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> id</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> <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"> Sets or removes a spender as an operator for the caller.</span></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 of the 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"> approved</span><span class="z-comment"> The approval status.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setOperator</span><span>(</span><span class="z-support">address</span><span class="z-variable"> spender</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 class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> isOperator</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> approved</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> OperatorSet</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> spender</span><span>,</span><span> approved</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-storage z-type"> @notice</span><span class="z-comment"> Checks 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"> @return</span><span class="z-variable z-other"> supported</span><span class="z-comment"> True if the contract implements `interfaceId`.</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"> 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 class="z-variable"> supported</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-constant"> 0x0f632fb3</span><span class="z-keyword"> ||</span><span> interfaceId </span><span class="z-keyword">==</span><span class="z-constant"> 0x01ffc9a7</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"> receiver</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-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> WARNING: important safety checks should precede calls to this method.</span></span> <span class="giallo-l"><span> balanceOf</span><span>[</span><span>receiver</span><span>]</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> amount</span><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 class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span> receiver</span><span>,</span><span> id</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-storage z-type"> function</span><span class="z-entity z-name"> _burn</span><span>(</span><span class="z-support">address</span><span class="z-variable"> sender</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-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> WARNING: important safety checks should precede calls to this method.</span></span> <span class="giallo-l"><span> balanceOf</span><span>[</span><span>sender</span><span>]</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> amount</span><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> sender</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span> id</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></code></pre><h2 id="security-considerations">Security Considerations</h2> <h3 id="approvals-and-operators">Approvals and Operators</h3> <p>The specification includes two token transfer permission systems, the "allowance" and "operator" models. There are two security considerations in regards to delegating permission to transfer.</p> <p>The first consideration is consistent with all delegated permission models. Any account with an allowance may transfer the full allowance for any reason at any time until the allowance is revoked. Any account with operator permissions may transfer any amount of any token id on behalf of the owner until the operator permission is revoked.</p> <p>The second consideration is unique to systems with both delegated permission models. If an account has both operator permissions and an insufficient allowance for a given transfer, performing the allowance check before the operator check would result in a revert while performing the operator check before the allowance check would not. The specification intentionally leaves this unconstrained for cases where implementors may track allowances despite the operator status. Nonetheless, this is a notable consideration.</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"> ERC6909OperatorPrecedence</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> -- snip --</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"> transferFrom</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"> receiver</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-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> check if `isOperator` first</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> sender </span><span class="z-keyword">&amp;&amp;</span><span class="z-keyword"> !</span><span>isOperator</span><span>[</span><span>sender</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"> require</span><span>(</span><span>allowance</span><span>[</span><span>sender</span><span>]</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> &gt;</span><span class="z-keyword">=</span><span> amount</span><span>,</span><span class="z-string"> &quot;insufficient allowance&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> allowance</span><span>[</span><span>sender</span><span>]</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> amount</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"> -- snip --</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"> ERC6909AllowancePrecedence</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> -- snip --</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"> transferFrom</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"> receiver</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-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> check if allowance is sufficient first</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> sender </span><span class="z-keyword">&amp;&amp;</span><span> allowance</span><span>[</span><span>sender</span><span>]</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> &lt;</span><span> amount</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>isOperator</span><span>[</span><span>sender</span><span>]</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>,</span><span class="z-string"> &quot;insufficient allowance&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-comment"> //</span><span class="z-comment"> ERROR: when allowance is insufficient, this panics due to arithmetic underflow, regardless of</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> whether the caller has operator permissions.</span></span> <span class="giallo-l"><span> allowance</span><span>[</span><span>sender</span><span>]</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> amount</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> -- snip</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> 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-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Adam Egyedhttps://github.com/adamegyed Fangting Liuhttps://github.com/trinity-0111 Jay Paikhttps://github.com/jaypaik Yoav Weisshttps://github.com/yoavw Huawei Guhttps://github.com/huaweigu Daniel Limhttps://github.com/dlim-circle Ruben Kochhttps://github.com/0xrubes David Philipsonhttps://github.com/dphilipson Howy Hohttps://github.com/howydev Nikita Belenkovhttps://github.com/nikita-quantstamp zer0dothttps://github.com/zer0dot David Kimhttps://github.com/PowerStream3604 https://wg-eips.ritovision.com/6900/

Interfaces for smart contract accounts and modules, optionally supporting upgradability and introspection

<h2 id="abstract">Abstract</h2> <p>This proposal standardizes smart contract accounts and account modules, which are smart contracts that allow for composable logic within smart contract accounts. This proposal is compliant with <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a>. This standard emphasizes secure permissioning of modules, and maximal interoperability between all spec-compliant accounts and modules.</p> <p>This modular approach splits account functionality into three categories, implements them in external contracts, and defines an expected execution flow from accounts.</p> <h2 id="motivation">Motivation</h2> <p>One of the goals that ERC-4337 accomplishes is abstracting the logic for execution and validation to each smart contract account.</p> <p>Many new features of accounts can be built by customizing the logic that goes into the validation and execution steps. Examples of such features include session keys, subscriptions, spending limits, and role-based access control. Currently, some of these features are implemented natively by specific smart contract accounts, and others are able to be implemented by proprietary module systems like Safe modules.</p> <p>However, managing multiple account implementations provides a poor user experience, fragmenting accounts across supported features and security configurations. Additionally, it requires module developers to choose which platforms to support, causing either platform lock-in or duplicated development effort.</p> <p>We propose a standard that coordinates the implementation work between module developers and account developers. This standard defines a modular smart contract account capable of supporting all standard-conformant modules. This allows users to have greater portability of their data, and for module developers to not have to choose specific account implementations to support.</p> <p><img src="https://wg-eips.ritovision.com/6900/./assets/MSCA_Shared_Components_Diagram.svg" alt="diagram showing relationship between accounts and modules with modular functions" /></p> <p>These modules can contain execution logic, validation functions, and hooks. Validation functions define the circumstances under which the smart contract account will approve actions taken on its behalf, while hooks allow for pre and post execution controls.</p> <p>Accounts adopting this standard will support modular, upgradable execution and validation logic. Defining this as a standard for smart contract accounts will make modules easier to develop securely and will allow for greater interoperability.</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="terms">Terms</h3> <ul> <li>An <strong>account</strong> (or <strong>smart contract account, SCA</strong>) is a smart contract that can be used to send transactions and hold digital assets. It implements the <code>IAccount</code> interface from ERC-4337.</li> <li>A <strong>modular account</strong> (or <strong>modular smart contract account, MSCA</strong>) is an account that supports modular functions. There are three types of modular functions: <ul> <li><strong>Validation functions</strong> validate authorization on behalf of the account.</li> <li><strong>Execution functions</strong> execute custom logic allowed by the account.</li> <li><strong>Hooks</strong> execute custom logic and checks before and/or after an execution function or validation function. There are two types of hooks: <ul> <li><strong>Validation hooks</strong> run before a validation function. These can enforce permissions on actions authorized by a validation function.</li> <li><strong>Execution hooks</strong> can run before and/or after an execution function. Execution hooks can be attached either to a specific execution function or a validation function. A pre execution hook may optionally return data to be consumed by a post execution hook.</li> </ul> </li> </ul> </li> <li>A <strong>native function</strong> refers to a function implemented by the modular account, as opposed to a function added by a module.</li> <li>A <strong>module</strong> is a deployed smart contract that hosts any amount of the above three kinds of modular functions.</li> <li>A module's <strong>manifest</strong> describes the execution functions, interface IDs, and hooks that should be installed on the account.</li> </ul> <h3 id="overview">Overview</h3> <p>A modular account handles two kinds of calls: either from the <code>EntryPoint</code> through ERC-4337, or through direct calls from externally owned accounts (EOAs) and other smart contracts. This standard supports both use cases.</p> <p>A call to the modular account can be broken down into the steps as shown in the diagram below. The validation steps validate if the caller is allowed to perform the call. The pre execution hook step can be used to do any pre execution checks or updates. It can also be used along with the post execution hook step to perform additional actions or verification. The execution step performs a defined task or collection of tasks.</p> <p><img src="https://wg-eips.ritovision.com/6900/./assets/Modular_Account_Call_Flow.svg" alt="diagram showing call flow within a modular account" /></p> <p>Each step is modular, supporting different implementations, which allows for open-ended programmable accounts.</p> <h3 id="interfaces">Interfaces</h3> <p>Modular accounts MUST implement:</p> <ul> <li><code>IAccount.sol</code> and <code>IAccountExecute.sol</code> from <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a>.</li> <li><code>IERC6900Account.sol</code> to support module management and usage, and account identification.</li> <li>The function <code>isValidSignature</code> from <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a></li> </ul> <p>Modular accounts MAY implement:</p> <ul> <li><code>IERC6900AccountView.sol</code> to support visibility in account states on-chain.</li> <li><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> for interfaces installed from modules.</li> </ul> <p>Modules MUST implement:</p> <ul> <li><code>IERC6900Module.sol</code> described below and implement ERC-165 for <code>IERC6900Module</code>.</li> </ul> <p>Modules MAY implement any of the following module types:</p> <ul> <li><code>IERC6900ValidationModule</code> to support validation functions for the account.</li> <li><code>IERC6900ValidationHookModule</code> to support hooks for validation functions.</li> <li><code>IERC6900ExecutionModule</code> to support execution functions and their installations on the account.</li> <li><code>IERC6900ExecutionHookModule</code> to support pre &amp; post execution hooks for execution functions.</li> </ul> <h4 id="ierc6900account-sol"><code>IERC6900Account.sol</code></h4> <p>Module execution and management interface. Modular accounts MUST implement this interface to support installing and uninstalling modules, and open-ended execution.</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 packed representation of a module function.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Consists of the following, left-aligned:</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Module address: 20 bytes</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Entity ID: 4 bytes</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> ModuleEntity</span><span class="z-storage"> is</span><span class="z-support"> bytes24</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"> A packed representation of a validation function and its associated flags.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Consists of the following, left-aligned:</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Module address: 20 bytes</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Entity ID: 4 bytes</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> ValidationFlags: 1 byte</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> ValidationConfig</span><span class="z-storage"> is</span><span class="z-support"> bytes25</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ValidationFlags layout:</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> 0b00000___ // unused</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> 0b_____A__ // isGlobal</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> 0b______B_ // isSignatureValidation</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> 0b_______C // isUserOpValidation</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> ValidationFlags</span><span class="z-storage"> is</span><span class="z-support"> uint8</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"> A packed representation of a hook function and its associated flags.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Consists of the following, left-aligned:</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Module address: 20 bytes</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Entity ID: 4 bytes</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Flags: 1 byte</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"> Hook flags layout:</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> 0b00000___ // unused</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> 0b_____A__ // hasPre (exec only)</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> 0b______B_ // hasPost (exec only)</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> 0b_______C // hook type (0 for exec, 1 for validation)</span></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> HookConfig</span><span class="z-storage"> is</span><span class="z-support"> bytes25</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"> Call</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The target address for the account to call.</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> target</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The value to send with the call.</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-comment"> //</span><span class="z-comment"> The calldata for the call.</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">interface</span><span class="z-entity z-name"> IERC6900Account</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ExecutionInstalled</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 class="z-variable">ExecutionManifest</span><span class="z-variable"> manifest</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ExecutionUninstalled</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 class="z-support">bool</span><span class="z-variable"> onUninstallSucceeded</span><span>, </span><span class="z-variable">ExecutionManifest</span><span class="z-variable"> manifest</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ValidationInstalled</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 class="z-support">uint32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> entityId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ValidationUninstalled</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 class="z-support">uint32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> entityId</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> onUninstallSucceeded</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"> Standard execute method.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> target</span><span class="z-comment"> The target address for the account to call.</span></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 value to send with the call.</span></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 calldata for the call.</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"> return data from the call.</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-support">address</span><span class="z-variable"> target</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</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-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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Standard executeBatch method.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> If the target is a module, the call SHOULD revert. If any of the calls revert, the entire batch MUST</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 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"> calls</span><span class="z-comment"> The array of calls.</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"> array containing the return data from the calls.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> executeBatch</span><span>(</span><span class="z-storage z-type">Call</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> calls</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">bytes</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"> Execute a call using the specified runtime validation.</span></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 calldata to send to 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"> authorization</span><span class="z-comment"> The authorization data to use for the call. The first 24 bytes is a ModuleEntity which</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> specifies which runtime validation to use, and the rest is sent as a parameter to runtime validation.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> executeWithRuntimeValidation</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-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> authorization</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 class="giallo-l"><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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Install a module to the modular 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"> module</span><span class="z-comment"> The module to install.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> manifest</span><span class="z-comment"> the manifest describing functions to install.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> installData</span><span class="z-comment"> Optional data to be used by the account to handle the initial execution setup. Data encoding</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> is implementation-specific.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> installExecution</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> module</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> ExecutionManifest</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> manifest</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"> installData</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-storage z-type"> @notice</span><span class="z-comment"> Uninstall a module from the modular 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"> module</span><span class="z-comment"> The module to uninstall.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> manifest</span><span class="z-comment"> The manifest describing functions to uninstall.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> uninstallData</span><span class="z-comment"> Optional data to be used by the account to handle the execution uninstallation. Data</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> encoding is implementation-specific.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> uninstallExecution</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> module</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> ExecutionManifest</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> manifest</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"> uninstallData</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-storage z-type"> @notice</span><span class="z-comment"> Installs a validation function across a set of execution selectors, and optionally mark it as a</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> global validation function.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> validationConfig</span><span class="z-comment"> The validation function to install, along with configuration flags.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> selectors</span><span class="z-comment"> The selectors to install the validation function 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"> installData</span><span class="z-comment"> Optional data to be used by the account to handle the initial validation setup. Data</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> encoding is implementation-specific.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> hooks</span><span class="z-comment"> Optional hooks to install and associate with the validation function. Data encoding is</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> implementation-specific.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> installValidation</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> ValidationConfig</span><span class="z-variable"> validationConfig</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> selectors</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"> installData</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> hooks</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-storage z-type"> @notice</span><span class="z-comment"> Uninstall a validation function from a set of execution selectors.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> validationFunction</span><span class="z-comment"> The validation function to uninstall.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> uninstallData</span><span class="z-comment"> Optional data to be used by the account to handle the validation uninstallation. Data</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> encoding is implementation-specific.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> hookUninstallData</span><span class="z-comment"> Optional data to be used by the account to handle hook uninstallation. Data encoding</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> is implementation-specific.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> uninstallValidation</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> ModuleEntity</span><span class="z-variable"> validationFunction</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"> uninstallData</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> hookUninstallData</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-storage z-type"> @notice</span><span class="z-comment"> Return a unique identifier for the account implementation.</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 string in the format &quot;vendor.account.semver&quot;. The vendor and account</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> names MUST NOT contain a period character.</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"> account ID.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> accountId</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></code></pre><h4 id="ierc6900accountview-sol"><code>IERC6900AccountView.sol</code></h4> <p>Module inspection interface. Modular accounts MAY implement this interface to support visibility in module configuration.</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"> Represents data associated with a specific function selector.</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> ExecutionDataView</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The module that implements this execution function.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If this is a native function, the address must be the address of the account.</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> module</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Whether or not the function needs runtime validation, or can be called by anyone. The function can still be</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> state changing if this flag is set to true.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-keyword"> Note</span><span class="z-comment"> that even if this is set to true, user op validation will still be required, otherwise anyone could</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> drain the account of native tokens by wasting gas.</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> skipRuntimeValidation</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Whether or not a global validation function may be used to validate this function.</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> allowGlobalValidation</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The execution hooks for this function selector.</span></span> <span class="giallo-l"><span> HookConfig</span><span>[</span><span>]</span><span> executionHooks</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"> ValidationDataView</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ValidationFlags layout:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 0b00000___ // unused</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 0b_____A__ // isGlobal</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 0b______B_ // isSignatureValidation</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 0b_______C // isUserOpValidation</span></span> <span class="giallo-l"><span> ValidationFlags validationFlags</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The validation hooks for this validation function.</span></span> <span class="giallo-l"><span> HookConfig</span><span>[</span><span>]</span><span> validationHooks</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Execution hooks to run with this validation function.</span></span> <span class="giallo-l"><span> HookConfig</span><span>[</span><span>]</span><span> executionHooks</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The set of selectors that may be validated by this validation function.</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span>[</span><span>]</span><span> selectors</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"> IERC6900AccountView</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 execution data for a selector.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> If the selector is a native function, the module address will be the address 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"> selector</span><span class="z-comment"> The selector to get the 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"> execution data for this selector.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getExecutionData</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> selector</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">ExecutionDataView</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"> Get the validation data for a validation function.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> If the selector is a native function, the module address will be the address 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"> validationFunction</span><span class="z-comment"> The validation function to get the 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"> validation data for this validation function.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getValidationData</span><span>(</span><span class="z-storage z-type">ModuleEntity</span><span class="z-variable"> validationFunction</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">ValidationDataView</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="ierc6900module-sol"><code>IERC6900Module.sol</code></h4> <p>Module interface. Modules MUST implement this interface to support module management and interactions with <a href="https://wg-eips.ritovision.com/6900/">ERC-6900</a> modular accounts.</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"> IERC6900Module</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"> @notice</span><span class="z-comment"> Initialize module data for the modular account.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Called by the modular account during `installExecution`.</span></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"> Optional bytes array to be decoded and used by the module to setup initial module data for the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> modular account.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> onInstall</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>;</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"> Clear module data for the modular account.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Called by the modular account during `uninstallExecution`.</span></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"> Optional bytes array to be decoded and used by the module to clear module data for the modular</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> account.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> onUninstall</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>;</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"> Return a unique identifier for the module.</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 string in the format &quot;vendor.module.semver&quot;. The vendor and module</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> names MUST NOT contain a period character.</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"> module ID.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> moduleId</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></code></pre><h4 id="ierc6900validationmodule-sol"><code>IERC6900ValidationModule.sol</code></h4> <p>Validation module interface. Modules MAY implement this interface to provide validation functions for the account.</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"> IERC6900ValidationModule</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6900Module</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"> Run the user operation validation function specified by the `entityId`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> entityId</span><span class="z-comment"> An identifier that routes the call to different internal implementations, should there</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> be more than one.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> userOp</span><span class="z-comment"> The user 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"> userOpHash</span><span class="z-comment"> The user operation hash.</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"> Packed</span><span class="z-comment"> validation data for validAfter (6 bytes), validUntil (6 bytes), and authorizer (20 bytes).</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> validateUserOp</span><span>(</span><span class="z-support">uint32</span><span class="z-variable"> entityId</span><span>,</span><span class="z-storage z-type"> PackedUserOperation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> userOp</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> userOpHash</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">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"> Run the runtime validation function specified by the `entityId`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> To indicate the entire call should revert, the function MUST 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"> account</span><span class="z-comment"> The account to validate 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"> entityId</span><span class="z-comment"> An identifier that routes the call to different internal implementations, should there</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> be more than one.</span></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 caller 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"> value</span><span class="z-comment"> The call 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"> data</span><span class="z-comment"> The calldata sent.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> authorization</span><span class="z-comment"> Additional data for the validation function to use.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> validateRuntime</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"> uint32</span><span class="z-variable"> entityId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</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"> calldata</span><span class="z-variable"> data</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"> authorization</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-storage z-type"> @notice</span><span class="z-comment"> Validates a signature using ERC-1271.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> To indicate the entire call should revert, the function MUST 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"> account</span><span class="z-comment"> The account to validate 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"> entityId</span><span class="z-comment"> An identifier that routes the call to different internal implementations, should there</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> be more than one.</span></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 that sent the ERC-1271 request to the smart 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"> hash</span><span class="z-comment"> The hash of the ERC-1271 request.</span></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"> The signature of the ERC-1271 request.</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"> ERC-1271 `MAGIC_VALUE` if the signature is valid, or 0xFFFFFFFF if invalid.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> validateSignature</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"> uint32</span><span class="z-variable"> entityId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> hash</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"> signature</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">bytes4</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="ierc6900validationhookmodule-sol"><code>IERC6900ValidationHookModule.sol</code></h4> <p>Validation hook module interface. Modules MAY implement this interface to provide hooks for validation functions for the account.</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"> IERC6900ValidationHookModule</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6900Module</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"> Run the pre user operation validation hook specified by the `entityId`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Pre user operation validation hooks MUST NOT return an authorizer value other than 0 or 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"> entityId</span><span class="z-comment"> An identifier that routes the call to different internal implementations, should there</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> be more than one.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> userOp</span><span class="z-comment"> The user 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"> userOpHash</span><span class="z-comment"> The user operation hash.</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"> Packed</span><span class="z-comment"> validation data for validAfter (6 bytes), validUntil (6 bytes), and authorizer (20 bytes).</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> preUserOpValidationHook</span><span>(</span><span class="z-support">uint32</span><span class="z-variable"> entityId</span><span>,</span><span class="z-storage z-type"> PackedUserOperation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> userOp</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> userOpHash</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">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"> Run the pre runtime validation hook specified by the `entityId`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> To indicate the entire call should revert, the function MUST 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"> entityId</span><span class="z-comment"> An identifier that routes the call to different internal implementations, should there</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> be more than one.</span></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 caller 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"> value</span><span class="z-comment"> The call 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"> data</span><span class="z-comment"> The calldata sent.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> authorization</span><span class="z-comment"> Additional data for the hook to use.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> preRuntimeValidationHook</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span class="z-variable"> entityId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</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"> calldata</span><span class="z-variable"> data</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"> authorization</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-storage z-type"> @notice</span><span class="z-comment"> Run the pre signature validation hook specified by the `entityId`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> To indicate the call should revert, the function MUST 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"> entityId</span><span class="z-comment"> An identifier that routes the call to different internal implementations, should there</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> be more than one.</span></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 caller 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"> hash</span><span class="z-comment"> The hash of the message being signed.</span></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"> The signature of the message.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> preSignatureValidationHook</span><span>(</span><span class="z-support">uint32</span><span class="z-variable"> entityId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> sender</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> hash</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> <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></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="ierc6900executionmodule-sol"><code>IERC6900ExecutionModule.sol</code></h4> <p>Execution module interface. Modules MAY implement this interface to provide execution functions for the account.</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"> ManifestExecutionFunction</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The selector to install.</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span> executionSelector</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If true, the function won&#39;t need runtime validation, and can be called by anyone.</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> skipRuntimeValidation</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If true, the function can be validated by a global validation function.</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> allowGlobalValidation</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"> ManifestExecutionHook</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span> executionSelector</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> entityId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isPreHook</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isPostHook</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 struct describing how the module should be installed on a modular account.</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> ExecutionManifest</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Execution functions defined in this module to be installed on the MSCA.</span></span> <span class="giallo-l"><span> ManifestExecutionFunction</span><span>[</span><span>]</span><span> executionFunctions</span><span>;</span></span> <span class="giallo-l"><span> ManifestExecutionHook</span><span>[</span><span>]</span><span> executionHooks</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> List of ERC-165 interface IDs to add to account to support introspection checks. This MUST NOT include</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> IERC6900Module&#39;s interface ID.</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span>[</span><span>]</span><span> interfaceIds</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"> IERC6900ExecutionModule</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6900Module</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"> Describe the contents and intended configuration of the module.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This manifest MUST stay constant over 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"> A</span><span class="z-comment"> manifest describing the contents and intended configuration of the module.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> executionManifest</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-storage z-type">ExecutionManifest</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="ierc6900executionhookmodule-sol"><code>IERC6900ExecutionHookModule.sol</code></h4> <p>Execution hook module interface. Modules MAY implement this interface to provide hooks for execution functions for the account.</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"> IERC6900ExecutionHookModule</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6900Module</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"> Run the pre execution hook specified by the `entityId`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> To indicate the entire call should revert, the function MUST 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"> entityId</span><span class="z-comment"> An identifier that routes the call to different internal implementations, should there</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> be more than one.</span></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 caller 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"> value</span><span class="z-comment"> The call 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"> data</span><span class="z-comment"> The calldata sent. For `executeUserOp` calls of validation-associated hooks, hook modules</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> should receive the full calldata.</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"> Context</span><span class="z-comment"> to pass to a post execution hook, if present. An empty bytes array MAY be returned.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> preExecutionHook</span><span>(</span><span class="z-support">uint32</span><span class="z-variable"> entityId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> sender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</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> <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">bytes</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"> Run the post execution hook specified by the `entityId`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> To indicate the entire call should revert, the function MUST 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"> entityId</span><span class="z-comment"> An identifier that routes the call to different internal implementations, should there</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> be more than one.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> preExecHookData</span><span class="z-comment"> The context returned by its associated pre execution hook.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> postExecutionHook</span><span>(</span><span class="z-support">uint32</span><span class="z-variable"> entityId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> preExecHookData</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="validation-functions">Validation Functions</h3> <h4 id="installation">Installation</h4> <ul> <li>The account MUST install all validation hooks specified by the user and SHOULD call <code>onInstall</code> with the user-provided data on the hook module to initialize state if specified by the user.</li> <li>The account MUST install all execution hooks specified by the user and SHOULD call <code>onInstall</code> with the user-provided data on the hook module to initialize state if specified by the user.</li> <li>The account MUST configure the validation function to validate all of the selectors specified by the user.</li> <li>The account MUST set all flags as specified, like <code>isGlobal</code>, <code>isSignatureValidation</code>, and <code>isUserOpValidation</code>.</li> <li>The account SHOULD call <code>onInstall</code> on the validation module to initialize state if specified by the user.</li> <li>The account MUST emit <code>ValidationInstalled</code> as defined in the interface for all installed validation functions.</li> </ul> <h4 id="uninstallation">Uninstallation</h4> <p>During validation uninstallation, the account MUST correctly clear flags and other fields based on the incoming data provided by the user.</p> <ul> <li>The account MUST clear all flags for the validation function, like <code>isGlobal</code>, <code>isSignatureValidation</code>, and <code>isUserOpValidation</code>.</li> <li>The account MUST remove all hooks and SHOULD clear hook module states by calling <code>onUninstall</code> with the user-provided data for each hook, including both validation hooks and execution hooks, if specified by the user. <ul> <li>The account MAY ignore the revert from <code>onUninstall</code> with try/catch depending on the design principle of the account.</li> </ul> </li> <li>The account MUST clear the configuration for the selectors that the validation function can validate.</li> <li>The account SHOULD call <code>onUninstall</code> on the validation module to clean up state if specified by the user.</li> <li>The account MUST emit <code>ValidationUninstalled</code> as defined in the interface for all uninstalled validation functions.</li> </ul> <h3 id="execution-functions">Execution Functions</h3> <h4 id="installation-1">Installation</h4> <ul> <li>The account MUST install all execution functions and set flags and fields as specified in the manifest. <ul> <li>An execution function selector MUST be unique in the account.</li> <li>An execution function selector MUST not conflict with native ERC-4337 and ERC-6900 functions.</li> </ul> </li> <li>The account MUST add all execution hooks as specified in the manifest.</li> <li>The account SHOULD add all supported interfaces as specified in the manifest.</li> <li>The account SHOULD call <code>onInstall</code> on the execution module to initialize state if specified by the user.</li> <li>The account MUST emit <code>ExecutionInstalled</code> as defined in the interface for all installed executions.</li> </ul> <h4 id="uninstallation-1">Uninstallation</h4> <p>During execution uninstallation, the account MUST correctly clear flags and other fields based on the incoming data and module manifest provided by the user.</p> <ul> <li>The account MUST remove all execution functions and clear flags and fields as specified in the manifest.</li> <li>The account MUST remove all execution hooks as specified in the manifest.</li> <li>The account SHOULD remove all supported interfaces as specified in the manifest.</li> <li>The account SHOULD call <code>onUninstall</code> on the execution module to clean up state and track call success if specified by the user.</li> <li>The account MUST emit <code>ExecutionUninstalled</code> as defined in the interface for all uninstalled executions.</li> </ul> <h3 id="hooks">Hooks</h3> <h4 id="execution-hooks-data-format">Execution Hooks Data Format</h4> <p>For accounts that implement execution hooks, accounts MUST conform to these execution hook formats:</p> <ol> <li>For <code>executeUserOp</code> calls, for execution hooks associated with a validation function, accounts MUST send the full calldata (<code>msg.data</code> in solidity), including the <code>executeUserOp</code> selector.</li> <li>For <code>executeUserOp</code> calls, for execution hooks associated with a selector, accounts MUST send <code>PackedUserOperation.callData</code> for <code>executeUserOp</code> calls, excluding <code>executeUserOp.selector</code> and the rest of the <code>PackedUserOperation</code>.</li> <li>For <code>executeWithRuntimeValidation</code> calls, for all execution hooks, accounts MUST send the inner <code>data</code> field.</li> <li>For all other calls, for execution hooks associated with a selector, accounts MUST send over the full calldata (<code>msg.data</code> in solidity).</li> </ol> <h4 id="hook-execution-order">Hook Execution Order</h4> <p>It is RECOMMENDED that an account implementer runs hooks in first installed first executed order. However, an account MAY implement a different execution order.</p> <h3 id="validation-call-flow">Validation Call Flow</h3> <p>Modular accounts support three different calls flows for validation: user op validation, runtime validation, and signature validation. User op validation happens within the account's implementation of the function <code>validateUserOp</code>, defined in the ERC-4337 interface <code>IAccount</code>. Runtime validation happens through the dispatcher function <code>executeWithRuntimeValidation</code>, or when using <a href="https://wg-eips.ritovision.com/6900/#direct-call-validation">direct call validation</a>. Signature validation happens within the account's implementation of the function <code>isValidSignature</code>, defined in ERC-1271.</p> <p>For each of these validation types, an account implementation MAY specify its own format for selecting which validation function to use, as well as any per-hook data for validation hooks.</p> <p>Within the implementation of each type of validation function, the modular account MUST check that the provided validation function applies to the given function selector intended to be run (See <a href="https://wg-eips.ritovision.com/6900/#checking-validation-applicability">Checking Validation Applicability</a>). Then, the account MUST execute all validation hooks of the corresponding type associated with the validation function in use. After the execution of validation hooks, the account MUST invoke the validation function of the corresponding type. If any of the validation hooks or the validation function reverts, the account MUST revert. It SHOULD include the module's revert data within its revert data.</p> <p>The account MUST define a way to pass data separately for each validation hook and the validation function itself. This data SHOULD be sent as the <code>userOp.signature</code> field for user op validation, the <code>authorization</code> field for runtime validation, and the <code>signature</code> field for signature validation.</p> <p>The result of user op validation MUST be the intersection of time bounds returned by the validation hooks and the validation function. If any validation hooks or the validation functions returns a value of <code>1</code> for the authorizer field, indicating a signature verification failure by the ERC-4337 standard, the account MUST return a value of <code>1</code> for the authorizer portion of the validation data.</p> <p>The set of validation hooks run MUST be the hooks specified by account state at the start of validation. In other words, if the set of applicable hooks changes during validation, the original set of hooks MUST still run, and only future invocations of the same validation should reflect the changed set of hooks.</p> <h4 id="checking-validation-applicability">Checking Validation Applicability</h4> <p>To enforce module permission isolation, the modular account MUST check validation function applicability as part of each validation function implementation.</p> <p>User op validation and runtime validation functions have a configurable range of applicability to functions on the account. This can be configured with selectors installed to a validation. Alternatively, a validation installation MAY specify the <code>isGlobal</code> flag as true, which means the account MUST consider it applicable to any module execution function with the <code>allowGlobalValidation</code> flag set to true, or for any account native function that the account MAY allow for global validation.</p> <p>If the selector being checked is <code>execute</code> or <code>executeBatch</code>, the modular account MUST perform additional checking. If the target of <code>execute</code> is the modular account's own address, or if the target of any <code>Call</code> within <code>executeBatch</code> is the account, validation MUST either revert or check that validation applies to the selector(s) being called.</p> <p>Installed validation functions have two additional flag variables indicating what they may be used for. If a validation function is attempted to be used for user op validation and the flag <code>isUserOpValidation</code> is set to false, validation MUST revert. If the validation function is attempted to be used for signature validation and the flag <code>isSignatureValidation</code> is set to false, validation MUST revert.</p> <h4 id="direct-call-validation">Direct Call Validation</h4> <p>If a validation function is installed with the entity ID of <code>0xffffffff</code>, it may be used as direct call validation. This occurs when a module or other address calls a function on the modular account, without wrapping its call in the dispatcher function <code>executeWithRuntimeValidation</code> to use as a selection mechanism for a runtime validation function.</p> <p>To implement direct call validation, the modular account MUST treat direct function calls that are not from the modular account itself or the <code>EntryPoint</code> as an attempt to validate using the caller's address and the entity ID of <code>0xffffffff</code>. If such a validation function is installed, and applies to the function intended to be called, the modular account MUST allow it to continue, without performing runtime validation. Any validation hooks and execution hooks installed to this validation function MUST still run.</p> <h3 id="execution-call-flow">Execution Call Flow</h3> <p>For all non-view functions within <code>IERC6900Account</code> except <code>executeWithRuntimeValidation</code>, all module-defined execution functions, and any additional native functions that the modular account MAY wish to include, the modular account MUST adhere to these steps during execution:</p> <p>If the caller is not the <code>EntryPoint</code> or the account, the account MUST check access control for direct call validation.</p> <p>Prior to running the target function, the modular account MUST run all pre execution hooks that apply for the current function call. Pre execution hooks apply if they have been installed to the currently running function selector, or if they are installed as an execution hook to the validation function that was used for the current execution. Pre execution hooks MUST run validation-associated hooks first, then selector-associated hooks second.</p> <p>Next, the modular account MUST run the target function, either an account native function or a module-defined execution function.</p> <p>After the execution of the target function, the modular account MUST run any post execution hooks. These MUST be run in the reverse order of the pre execution hooks. If a hook is defined to be both a pre and a post execution hook, and the pre execution hook returned a non-empty <code>bytes</code> value to the account, the account MUST pass that data to the post execution hook.</p> <p>The set of hooks run for a given target function MUST be the hooks specified by account state at the start of the execution phase. In other words, if the set of applicable hooks changes during execution, the original set of hooks MUST still run, and only future invocations of the same target function should reflect the changed set of hooks.</p> <p>Module execution functions where the field <code>skipRuntimeValidation</code> is set to true, as well as native functions without access control, SHOULD omit the runtime validation step, including any runtime validation hooks. Native functions without access control MAY also omit running execution hooks.</p> <h3 id="extension">Extension</h3> <h4 id="semi-modular-account">Semi-Modular Account</h4> <p>Account implementers MAY choose to design a semi-modular account, where certain features, such as default validation, are integrated into the core account. This approach SHOULD ensure compatibility with fully modular accounts, as defined in this proposal, to maintain interoperability across different implementations.</p> <h2 id="rationale">Rationale</h2> <p>ERC-4337 compatible accounts must implement the <code>IAccount</code> interface, which consists of only one method that bundles validation with execution: <code>validateUserOp</code>. A primary design rationale for this proposal is to extend the possible functions for a smart contract account beyond this single method by unbundling these and other functions, while retaining the benefits of account abstraction.</p> <p>This proposal includes several interfaces that build on ERC-4337. First, we standardize a set of modular functions that allow smart contract developers greater flexibility in bundling validation, execution, and hook logic. We also propose interfaces that provide methods for querying execution functions, validation functions, and hooks on a modular account. The rest of the interfaces describe a module's methods for exposing its modular functions and desired configuration, and the modular account's methods for installing and removing modules and allowing execution across modules and external addresses.</p> <h3 id="erc-4337-dependency">ERC-4337 Dependency</h3> <p>ERC-6900's main objective is to create a secure and interoperable foundation through modular accounts and modules to increase the velocity and security of the smart account ecosystem, and ultimately the wallet ecosystem. Currently, the standard prescribes ERC-4337 for one of its <a href="https://wg-eips.ritovision.com/6900/#overview">modular account call flows</a>. However, this does not dictate that ERC-6900 will continue to be tied to ERC-4337. It is likely that smart account builders will want to develop modular accounts that do not use ERC-4337 in the future (e.g., native account abstraction on rollups). Moreover, it is expected that ERC-4337 and its interfaces and contracts will continue to evolve until there is a protocol-level account abstraction.</p> <p>In the current state of the AA ecosystem, it is tough to predict the direction the builders and industry will take, so ERC-6900 will evolve together with the space's research, development, and adoption. The standard will do its best to address the objectives and create a secure foundation for modular accounts that may eventually be abstracted away from the infrastructure mechanism used.</p> <h3 id="community-consensus">Community Consensus</h3> <p>While this standard has largely been the result of collaboration among the coauthors, there have been noteworthy contributions from others in the community with respect to improvements, education, and experimentation. Thank you to the contributors:</p> <ul> <li>Gerard Persoon (@gpersoon)</li> <li>Harry Jeon (@sm-stack)</li> <li>Zhiyu Zhang (@ZhiyuCircle)</li> <li>Danilo Neves Cruz (@cruzdanilo)</li> <li>Iván Alberquilla (@ialberquilla)</li> </ul> <p>We host community calls and working groups to discuss standard improvements and invite anyone with questions or contributions into our discussion.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Existing accounts that are deployed as proxies may have the ability to upgrade account implementations to one that supports this standard for modularity. Depending on implementation logic, existing modules may be wrapped in an adapter contract to adhere to the standard.</p> <p>The standard also allows for flexibility in account implementations, including accounts that have certain features implemented without modules, so usage of modules may be gradually introduced.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <code>https://github.com/erc6900/reference-implementation</code></p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="wallet-sdk-developers">Wallet/SDK Developers</h3> <p>From the wallet side, there are certain checks that the wallet/SDK should perform on the UI/UX side.</p> <p>The standard introduces a concept of the execution manifest, which describes the execution functions, interface IDs, and hooks that should be installed on the account from an execution manifest. As part of constructing parameters to <code>installExecution()</code>, the SDK creates an <code>executionManifest</code> parameter that will specify the actions of the execution module being installed. SDKs will process the provided <code>executionManifest()</code> function of the underlying module, but the finished parameter will not necessarily be identical to the module’s return value of <code>executionManifest()</code>. Furthermore, this parameter is only going through very limited checks on-chain as part of the installation process. Therefore, the <code>executionManifest</code> parameter needs to be carefully constructed and verified before being used for installations. Furthermore, the <code>executionManifest</code> parameter of uninstallation should ideally be the same used in installation to not leave residual data.</p> <p>The standard supports a <code>isGlobalValidation</code> flag for validation functions, which means that this function is added to a global validation pool and can validate any of the execution functions that expose themselves to global validation via <code>allowGlobalValidation</code> flag. Depending on the implementation, some, all or none of the native execution functions could be globally validated. Therefore, the wallets should be careful about what validation functions they allow to be installed with global validation enabled, as that would allow these functions to validate the exposed native functions and hence bypass any restrictions that may have been added to protect these native/execution functions. In a sense, these global validation functions could gain root access to the exposed native execution functions and potentially the whole account.</p> <h3 id="module-developers">Module Developers</h3> <p>The standard does not enforce any rules surrounding what data needs to be installed or uninstalled when a module is added/deleted from the account. Hence the <code>onUninstall()</code> function in various modules may leave behind residual state data, especially since the external call may not be performed all. Furthermore, execution hooks linked to an uninstalled function may remain configured. This could pose security risks or lead to unexpected behavior in the case where the module is reinstalled with the same <code>entityId</code>. The danger is that previously set permissions or data may be unintentionally reused. Hence it is a good idea to fully uninstall all data linked to the smart module account including execution hooks.</p> <h3 id="users">Users</h3> <p>The modular smart contract accounts themselves are trusted components. Installed modules are trusted to varying degrees, as modules can interact with an arbitrarily large or small set of resources on an account. For example, a wide-reaching malicious module could add reverting hooks to native function selectors, bricking the account, or add execution functions that may drain the funds of the account. However, it is also possible to install a module with a very narrow domain, and depend on the correctness of the account behavior to enforce its limited access. Users should, therefore be careful in what modules to add to their 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-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-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Abderrahmen Hanafihttps://github.com/a6-dou https://wg-eips.ritovision.com/6865/

Visualize structured data highlighting the potential consequences for users' assets

<h2 id="abstract">Abstract</h2> <p>Numerous protocols employ distinct <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> schemas, leading to unavoidable inconsistencies across the ecosystem. To address this issue, we propose a standardized approach for dApps to implement an on-chain view function called <code>visualizeEIP712Message</code>. This function takes an abi encoded EIP-712 payload message as input and returns a universally agreed-upon structured data format that emphasizes the potential impact on users' assets. Wallets can then display this structured data in a user-friendly manner, ensuring a consistent experience for end-users when interacting with various dApps and protocols.</p> <h2 id="motivation">Motivation</h2> <p>The rapid expansion of the web3.0 ecosystem has unlocked numerous opportunities and innovations. However, this growth has also heightened users' vulnerability to security threats, such as phishing scams. Ensuring that users have a comprehensive understanding of the transactions they sign is crucial for mitigating these risks.</p> <p>In an attempt to address this issue, we developed an in-house, open-source off-chain SDK for wallets to visualize various protocols. However, we encountered several challenges along the way:</p> <ul> <li>Scalability: Identifying and understanding all protocols that utilize EIP-712 and their respective business logic is a daunting task, particularly with limited resources. Crafting an off-chain solution for all these protocols is nearly impossible.</li> <li>Reliability: Grasping each protocol's business logic is difficult and may lead to misunderstandings of the actual implementation. This can result in inaccurate visualizations, which could be more detrimental than providing no visualization at all.</li> <li>Maintainability: Offering support for protocols with an off-chain solution is insufficient in a rapidly evolving ecosystem. Protocols frequently upgrade their implementations by extending features or fixing bugs, further complicating the maintenance process.</li> </ul> <p>To overcome these challenges, we propose a standardized, on-chain solution that can accommodate the diverse and ever-changing web3.0 ecosystem. This approach would enhance scalability, reliability, and maintainability by shifting the responsibility of visualizing EIP-712 payloads from the wallets to the protocols themselves. Consequently, wallets can use a consistent and effective approach to EIP-712 message visualization.</p> <p>The adoption of a universal solution will not only streamline the efforts and reduce the maintenance burden for wallet providers, but it will also allow for faster and more extensive coverage across the ecosystem. This will ultimately result in users gaining a clearer understanding of the transactions they're signing, leading to increased security and an improved overall user experience within the crypto space.</p> <p>Currently, most of the wallets display something similar to image below</p> <p><img src="https://wg-eips.ritovision.com/6865/./assets/current-EIP-712-signature-wallet-interface.png" alt="" /></p> <p>With visualization we can achieve something similar to image below where more insightful details are revealed to user thanks to the structured data returned from the EIP</p> <p><img src="https://wg-eips.ritovision.com/6865/./assets/vision-EIP-712-signature-wallet-interface.png" alt="" /></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>Contracts implementing this proposal MUST include the <code>visualizeEIP712Message</code> function in the <code>verifyingContract</code> implementation so that wallets upon receiving a request to sign an EIP-712 message(<code>eth_signTypedData</code>) MAY call the function <code>visualizeEIP712Message</code> at the smart contract and chain specified in the EIP-712 message domain separator <code>verifyingContract</code> and <code>chainId</code> fields, respectively.</p> <p>Wallets SHOULD ignore this proposal if the domain separator does not include the <code>verifyingContract</code> and <code>chainId</code> fields.</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"> This function processes an EIP-712 payload message and returns a structured data format emphasizing the potential impact on users&#39; assets.</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 returns assetsOut (assets the user is offering), assetsIn (assets the user would receive), and liveness (validity duration of the EIP-712 message).</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> encodedMessage</span><span class="z-comment"> The ABI-encoded EIP-712 message (abi.encode(types, params)).</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> domainHash</span><span class="z-comment"> The hash of the EIP-712 domain separator as defined in the EIP-712 proposal; see https://eips.ethereum.org/EIPS/eip-712#definition-of-domainseparator.</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"> struct containing the user&#39;s assets impact and message liveness.</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"> visualizeEIP712Message</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"> encodedMessage</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> domainHash</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-storage z-type">Result</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre><h3 id="params">Params</h3> <p><code>encodedMessage</code> is bytes that represents the encoded EIP-712 message with <code>abi.encode</code> and it can be decoded using <code>abi.decode</code></p> <p><code>domainHash</code> is the bytes32 hash of the EIP-712 domain separator as defined in the EIP-712 proposal</p> <h3 id="outputs">Outputs</h3> <p>The function MUST return <code>Result</code>, a struct that contains information's about user’s assets impact and the liveness of such a message if it gets signed.</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"> Liveness</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> from</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> to</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"> UserAssetMovement</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> assetTokenAddress</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> id</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span> amounts</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"> Result</span><span> {</span></span> <span class="giallo-l"><span> UserAssetMovement</span><span>[</span><span>]</span><span> assetsIn</span><span>;</span></span> <span class="giallo-l"><span> UserAssetMovement</span><span>[</span><span>]</span><span> assetsOut</span><span>;</span></span> <span class="giallo-l"><span> Liveness liveness</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="liveness"><code>Liveness</code></h4> <p><code>Liveness</code> is a struct that defines the timestamps which the message is valid where:</p> <ul> <li><code>from</code> is the starting timestamp.</li> <li><code>to</code> is the expiry timestamp</li> <li><code>from</code> MUST be less than <code>to</code></li> </ul> <h4 id="userassetmovement"><code>UserAssetMovement</code></h4> <p><code>UserAssetMovement</code> defines the user’s asset where:</p> <ul> <li><code>assetTokenAddress</code> is the token (<a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>) smart contract address where the zero address MUST represents the Native coin (Native ETH in the case of Ethereum network).</li> <li><code>id</code> is the NFT ID, this item MUST ignored if the asset is not an NFT <ul> <li>if token with <code>id</code> doesn’t exist in an NFT collection, this SHOULD be considered as any token within that collection</li> </ul> </li> <li><code>amounts</code> is an Array of <code>uint256</code> where items MUST define the amount per time curve, with time defined within liveness boundaries <ul> <li>the first amount in <code>amounts</code> Array (amounts[0]) MUST be the amount of the asset at <code>liveness.from</code> timestamp</li> <li>the last amount in <code>amounts</code> Array (amounts[amounts.length-1]) MUST be the amount of the asset at <code>liveness.to</code> timestamp</li> <li>in most of the cases, <code>amounts</code> will be an Array with a single item which is MUST be the minimum amount of the asset.</li> </ul> </li> </ul> <h4 id="assetsin"><code>assetsIn</code></h4> <p><code>assetsIn</code> are the minimum assets which the user MUST get if the message is signed and fulfilled</p> <h4 id="assetsout"><code>assetsOut</code></h4> <p><code>assetsOut</code> are the maximum assets which the user MUST offer if the message is signed and fulfilled</p> <h2 id="rationale">Rationale</h2> <h3 id="on-chain">on-chain</h3> <p>One might argue that certain processes can be done off-chain, which is true, but our experience building an off-chain TypeScript SDK to solve this matter revealed some issues:</p> <ul> <li>Reliability: Protocols developers are the ones responsible for developing the protocol itself, thus crafting the visualization is much more accurate when done by them.</li> <li>Scalability: Keeping up with the rapidly expanding ecosystem is hard. Wallets or 3rd party entities must keep an eye on each new protocol, understand it carefully (which poses the reliability issues mentioned above), and then only come up with an off-chain implementation.</li> <li>Maintainability: Many protocols implement smart contracts in an upgradable manner. This causes the off-chain visualization to differ from the real protocol behaviors (if updated), making the solution itself unreliable and lacking the scalability to handle various protocols.</li> </ul> <h3 id="domainhash"><code>DomainHash</code></h3> <p>The <code>domainHash</code> is much needed by protocols to revert against unsupported versions of its EIP-712 implementation. It identifies the needed implementation in case the protocol implements various EIP-712 implementations (<code>name</code>) or to revert if the <code>domainHash</code> belongs to a different protocol.</p> <p>In the future, if there is a registry that reroutes this EIP implementation for already deployed protocols that can't upgrade the existing deployed smart contract, <code>domainHash</code> can be used to identify protocols.</p> <h3 id="amounts-array">Amounts Array</h3> <p>We suggest using an array of amounts (uint256[]) instead of a single uint256 to cover auctions, which are common in NFT protocols.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>openSea Seaport NFT marketplace implementation example is available <a href="https://wg-eips.ritovision.com/6865/./assets/contracts/SeaPortEIP712Visualizer.sol">here</a></p> <h2 id="security-considerations">Security Considerations</h2> <p><code>visualizeEIP712Message</code> function should be reliable and accurately represent the potential impact of the EIP-712 message on users' assets. Wallet providers and users must trust the protocol's implementation of this function to provide accurate and up-to-date information.</p> <p><code>visualizeEIP712Message</code> function results should be treated based on the reputation of its <code>verifyingContract</code>, if the <code>verifyingContract</code> is trusted it means the <code>visualizeEIP712Message</code> function results are trusted as the this proposal implementation lives at the same address of <code>verifyingContract</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-04-10T00:00:00+00:00 2026-02-11T14:49:27+00:00 Mário Havelhttps://github.com/taxmeifyoucan pk910https://github.com/pk910 Rémy Royhttps://github.com/remyroy Holly Atkinsonhttps://github.com/atkinsonholly Tereza Burianovahttps://github.com/T-ess https://wg-eips.ritovision.com/6916/

A testnet network that periodically rolls back to genesis

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a specification for an automatically reset testnet, a novel approach to testnets that can be implemented within Ethereum clients. It enables a single testing infrastructure consisting of ephemeral networks with deterministic parameters. Each network iteration is created by a specified function which deterministically generates genesis states.</p> <h2 id="motivation">Motivation</h2> <p>A testnet which automatically resets can provide an alternative environment for short-term testing of applications, validators and also breaking changes in client implementations. It avoids issues of long running testnets which suffer from state bloat, lack of testnet funds or consensus issues. Periodically resetting the network back to genesis cleans the validator set and returns funds back to faucets while keeping the network reasonably small for easy bootstrapping.</p> <h2 id="specification">Specification</h2> <p>The testnet is set to always reset after a predefined time period. The reset means the generation of the next genesis, discarding the old one and starting a new network. This is possible by introducing functions for the genesis generation and the client reset.</p> <h3 id="genesis">Genesis</h3> <p>To connect to the current instance of the network, the client must implement the genesis function. This function defines how the client stores information about the testnet and generates the current genesis. With each reset, the network starts from a new genesis which needs to be built based on given parameters and correspond in EL and CL clients.</p> <p>The network always starts from a genesis which is deterministically created based on the original one - this very first genesis is hardcoded and we can call it <code>genesis 0</code>. Terminal time, the expiration of each genesis, is the addition of the start time of that genesis <code>MIN_GENESIS_TIME</code> and the testnet lifetime <code>period</code>, where <code>period</code> is a constant defining the length of time a single ephemeral network runs. Therefore, once the current slot timestamp reaches the terminal time of the ephemeral network, it has to switch to a new genesis. The main changes in each new genesis iteration are chainId, genesis time and the withdrawal credentials of the first validator.</p> <p>Clients shall include a hardcoded <code>genesis 0</code> parameters, much like other networks predefined in clients. However, this genesis shall be used directly, only at the very beginning of the testnet's existence, in its first iteration where <code>i</code> equals <code>0</code>. Later on, with iteration <code>i</code> equal to <code>1</code> and above, the client does not initialize this genesis but uses it to derive the current one. When <code>i&gt;0</code>, given a known <code>period</code> and current slot timestamp, the client always calculates the number of lifecycle iterations from <code>genesis 0</code> and creates a new genesis with the latest parameters.</p> <p>When the client starts with the option of an ephemeral testnet, it checks whether a genesis for the network is present. If it doesn't exist or the current slot timestamp is older than <code>current_genesis.genesis_time + period</code>, it triggers the generation of a new genesis. This new genesis, derived from <code>genesis 0</code>, will be written to the database and used to run the current network.</p> <h4 id="execution-client">Execution client</h4> <p>The EL client includes the hardcoded <code>genesis 0</code> serving as a preimage for generating the current one. Iteration of variables is done as follows:</p> <ul> <li>Number of iterations: <ul> <li><code>i</code> = <code>int((current_slot_timestamp</code> - <code>genesis_0.genesis_time) / period)</code></li> </ul> </li> <li>Genesis time of current genesis: <ul> <li><code>current_genesis.genesis_time</code> = <code>period</code> * <code>i</code> + <code>genesis_0.genesis_time</code></li> </ul> </li> <li>Current EL ChainId: <ul> <li><code>chainId</code> = <code>genesis_0.chainId</code> + <code>i</code></li> </ul> </li> </ul> <h4 id="consensus-client">Consensus client</h4> <p>Genesis generation in the CL client includes config with iterated values, similarly to EL, but also requires the updated genesis state. The state in SSZ format can be either generated by the client or downloaded from an external source. It includes validators with deposits ready to launch a merged network with the validator set created by trusted entities within the community.</p> <p><code>MIN_GENESIS_TIME</code> is set to the latest genesis time and defines when the current period starts. It is recommended to add a small <code>GENESIS_DELAY</code>, for example 15 minutes, to avoid issues while infrastructure is restarting with the new genesis.</p> <p>To ensure a successful reset, <code>ForkDigest</code> needs to be unique for each iteration. In order to keep the <code>ForkVersions</code> of the network static for better tooling support, the withdrawal credentials of the first validator in the validator set need to be overridden by a calculated value.</p> <ul> <li><code>genesis.validators[0].withdrawal_credentials</code> = <code>0x0100000000000000000000000000000000000000000000000000000000000000</code> + <code>i</code></li> <li><code>genesis.genesis_validators_root</code> = <code>hash_tree_root(genesis.validators)</code></li> </ul> <p>The update of <code>genesis.validators[0]</code> changes the state, therefore, clients have to be able to generate or download the latest genesis state. Generating the genesis ssz is not considered a standard client feature and adding it enables to trustlessly create the latest genesis state at the price of certain complexity. An alternative solution is to obtain it from a third party, either by downloading the ssz file from a server or using the checkpoint sync feature with an endpoint serving the genesis state. This became an accepted practice with Holešky testnet and existing features of checkpoint sync can be used for obtaining genesis states for automatically reset testnets. It also allows maintainers to update the genesis validator set without requiring new client releases. The full implementation of the recommended practice for obtaining the latest CL state should behave as follows:</p> <ul> <li>When the testnet flag is provided and client supports checkpoint sync of genesis, automatically use the hardcoded checkpoint endpoint to download the latest genesis state using the checkpoint sync feature <ul> <li>If user provides a custom checkpoint sync flag, override the default option and use the endpoint provided by user</li> </ul> </li> <li>Include a backup download option pointing to an url with the latest testnet release, a publicly distributed ssz file, and trigger this option if the checkpoint state sync fails or make it the default if client doesn't support genesis checkpoint sync</li> <li>If the client includes a feature for generating the genesis or some of its parameters, use it to verify parameters in the downloaded state and issue an error if values or checksum don't correspond</li> </ul> <p>It's important to note that <code>genesis_validators_root</code> is normally predefined in the client but in this case it's not known in advance which can potentially break certain architectures. For example light clients which are relying on hardcoded <code>genesis_validators_root</code> won't work.</p> <h3 id="reset">Reset</h3> <p>The reset function defines an automatic process of throwing away the old data and starting with a new genesis. It depends on the previously defined function for genesis generation which the client must implement in order to be able to automatically follow the latest network iteration.</p> <p>For the reset function, we can introduce the <code>terminal_timestamp</code> value which defines the network expiry time of an iteration. It can be the same as the genesis time of the next iteration (without the genesis delay) or can be calculated simply as <code>terminal_timestamp = current_genesis.genesis_time + period</code>.</p> <p>When the network reaches a slot with a timestamp <code>&gt;= terminal_timestamp</code>:</p> <ul> <li>Client stops accepting/creating new blocks <ul> <li>Shutdown client services running the network, e.g. p2p communication, beacon service, execution environment</li> <li>This feature should be implemented alongside Genesis even without further reset functions just to create a basic support which is always safe from forking</li> </ul> </li> <li>Client calls a function which discards the current genesis, all chain or beacon data <ul> <li>Clients already include db tools including for purging the database which could be used here</li> <li>It might be beneficial to include an additional flag, e.g. <code>--retain-ephemeral-data</code>, which would first export the existing data in a standard format before removing the database</li> </ul> </li> <li>Client triggers the Genesis function (as defined above): <ul> <li>Behaves like a regular client startup when genesis is not present</li> <li>New genesis is written into db and initialized</li> </ul> </li> <li>Main network services are started again pointing to the updated genesis</li> <li>After the new genesis time is reached, the network starts again from the new genesis</li> </ul> <p>For a full reset implementation, clients should be able to perform the above actions without requiring manual restart, operating the network fully independently and with minimal downtime.</p> <p>Note that depending on the client architecture, it may not be feasible to fully implement such an internal reset mechanism, e.g. if the client doesn't support a graceful shutdown. The reset feature is considered an advanced level of support and is mainly needed by infrastructure providers and genesis validators. The assumption is that even if the client doesn't implement reset, advanced users can achieve similar behavior with external scripts handling the client by system tools.</p> <h2 id="rationale">Rationale</h2> <p>Ephemeral testnets with deterministic parameters provide a sustainable alternative to traditional testnets, with the same infrastructure. At each reset, the validator set is cleared, faucets are filled again and the database is kept small.</p> <p>Upon reset the whole state is purged, which, on the one hand keeps the network small and easy to bootstrap but introduces problems for testing longer term / advanced applications. However, basic contract infrastructure can be automatically deployed after each reset by any user. Generally, using the network is recommended for short term testing, deploying <code>Hello World</code> kinds of contracts that don't need to stay forever on a long term testnet. However, there can be an offchain mechanism that automatically deploys standard contract primitives after each reset so application developers can also utilize the network more.</p> <p>By defining two mechanisms for Genesis and Reset, this EIP enables two levels of how a client implementation can support the testnet;</p> <ul> <li>Basic support requires the client to determine the current network specs and enables only connecting to the network. <ul> <li>This means support of the Genesis mechanism defined above</li> <li>Enough to participate in the network for short term testing</li> <li>To follow the latest iteration, the user has to manually shut down the client and delete the database</li> <li>It's still recommended to add a feature for terminating the network</li> </ul> </li> <li>Full support enables the client to follow the reset process and always sync the latest chain iteration <ul> <li>This also requires the client to implement an inherent Reset feature</li> <li>Needed for running persistent infrastructure, genesis validators and bootnodes</li> <li>It might be more complex to implement due to client architecture of clients</li> </ul> </li> </ul> <p>The design is also compatible with nodes managed by external tooling, i.e. even if the client doesn't implement these features, it can run on the same network as other nodes which are automatically reset by scripts. Any client supporting a custom network can be used for the testnet.</p> <h3 id="network-parameters">Network parameters</h3> <p>Constants and variables defining testnet properties are arbitrary but need to be crafted considering certain limitations and security properties set out below.</p> <h4 id="reset-period">Reset Period</h4> <p>The <code>period</code> is a constant, hardcoded in the client defining the period of time after which the network resets.</p> <p>It can be defined based on users' needs but for security reasons, it also depends on the number of validators in genesis. Considering the time to activate a validator, the number of trusted validators should be high enough so the network cannot be overtaken by a malicious actor.</p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">Genesis</span><span class="z-string"> Validators</span><span> =</span><span class="z-keyword">&gt;</span><span class="z-string"> Epochs</span><span class="z-string"> until</span><span class="z-keyword"> &lt;</span><span class="z-string"> 66%</span><span class="z-string"> majority</span></span> <span class="giallo-l"><span class="z-entity z-name">10k</span><span> =</span><span class="z-keyword">&gt;</span><span class="z-constant"> 1289</span><span class="z-string"> Epochs</span><span> (5,7</span><span class="z-string"> days</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name">50k</span><span> =</span><span class="z-keyword">&gt;</span><span class="z-constant"> 6441</span><span class="z-string"> Epochs</span><span> (28,6</span><span class="z-string"> days</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name">75k</span><span> =</span><span class="z-keyword">&gt;</span><span class="z-constant"> 9660</span><span class="z-string"> Epochs</span><span> (42,9</span><span class="z-string"> days</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name">100k</span><span> =</span><span class="z-keyword">&gt;</span><span class="z-constant"> 12877</span><span class="z-string"> Epochs</span><span> (57,2</span><span class="z-string"> days</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name">150k</span><span> =</span><span class="z-keyword">&gt;</span><span class="z-constant"> 19323</span><span class="z-string"> Epochs</span><span> (85,9</span><span class="z-string"> days</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name">200k</span><span> =</span><span class="z-keyword">&gt;</span><span class="z-constant"> 25764</span><span class="z-string"> Epochs</span><span> (114,5</span><span class="z-string"> days</span><span>)</span></span></code></pre><h4 id="chainid">ChainId</h4> <p>ChainId is a variable because it needs to keep changing with each new genesis to avoid replay attack. The function for the new ChainId value is a simple incrementation (+1). The ChainId in <code>genesis 0</code> is a hardcoded constant. This constant is used by the client with each new genesis to derive a new ChainId for that network iteration.</p> <p>New ChainIds shouldn't collide with any other existing public EVM chain even after many iterations. Consequently, low ChainId values are discouraged.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The network itself is providing a secure environment thanks to regular resets. Even if some sort of vulnerability is exploited, it will be cleared on the next reset. This is also a reason to keep periods relatively short (weeks/months opposed to months/years) with a big enough genesis validator set to keep an honest majority.</p> <p>Changes in clients caused by the implementation of features for resetting networks need to be reviewed together with standard security procedures. Especially the mechanism for triggering reset which must be separated from other networks that are not configured as ephemeral.</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-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jeff Huanghttps://github.com/jeffishjeff https://wg-eips.ritovision.com/6864/

Upgradable fungible token, a simple extension to ERC-20

<h2 id="abstract">Abstract</h2> <p>This proposal outlines a smart contract interface for upgrading/downgrading existing <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> smart contracts while maintaining user balances. The interface itself is an extension to the ERC-20 standard so that other smart contracts can continue to interact with the upgraded smart contract without changing anything other than the address.</p> <h2 id="motivation">Motivation</h2> <p>By design, smart contracts are immutable and token standards like ERC-20 are minimalistic. While these design principles are fundamental in decentalized applications, there are sensible and practical situations where the ability to upgrade an ERC-20 token is desirable, such as:</p> <ul> <li>to address bugs and remove limitations</li> <li>to adopt new features and standards</li> <li>to comply w/ changing regulations</li> </ul> <p>Proxy pattern using <code>delegatecall</code> opcode offers a reasonable, generalized solution to reconcile the immutability and upgradability features but has its own shortcomings:</p> <ul> <li>the smart contracts must support proxy pattern from the get go, i.e. it cannot be used on contracts that were not deployed with proxies</li> <li>upgrades are silent and irreversible, i.e. users do not have the option to opt-out</li> </ul> <p>In contrast, by reducing the scope to specifically ERC-20 tokens, this proposal standardizes an ERC-20 extension that works with any existing or future ERC-20 smart contracts, is much simpler to implement and to maintain, can be reversed or nested, and offers a double confirmation opportunity for any and all users to explicitly opt-in on the upgrade.</p> <p><a href="https://wg-eips.ritovision.com/4931/">ERC-4931</a> attepts to address the same problem by introducing a third "bridge" contract to help facilitate the upgrade/downgrade operations. While this design decouples upgrade/downgrade logic from token logic, ERC-4931 would require tokens to be pre-minted at the destination smart contract and owned by the bridge contrtact rather then just-in-time when upgrade is invoked. It also would not be able to support upgrade-while-transfer and see-through functions as described below.</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> <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"> Upgradable Fungible Token</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-6864</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"> IERC6864</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST be emitted when tokens are upgraded</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"> Previous owner of base ERC-20 tokens</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"> New owner of ERC-6864 tokens</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"> The amount that is upgraded</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"> 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"> 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-storage z-type"> @dev</span><span class="z-comment"> MUST be emitted when tokens are downgraded</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"> Previous owner of ERC-6864 tokens</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"> New owner of base ERC-20 tokens</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"> The amount that is downgraded</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"> 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"> 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-storage z-type"> @notice</span><span class="z-comment"> Upgrade `amount` of base ERC-20 tokens owned by `msg.sender` to ERC-6864 tokens under `to`</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> `msg.sender` must directly own sufficient base ERC-20 tokens</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 `msg.sender` does not directly own `amount` or more of base ERC-20 tokens</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"> The address to receive ERC-6864 tokens</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"> The amount of base ERC-20 tokens to upgrade</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"> upgrade</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Downgrade `amount` of ERC-6864 tokens owned by `from` to base ERC-20 tokens under `to`</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> `msg.sender` must either directly own or be approved to spend sufficient ERC-6864 tokens for `from`</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 `from` does not directly own `amount` or more of ERC-6864 tokens</span></span> <span class="giallo-l"><span class="z-comment"> MUST revret if `msg.sender` is not `from` and is not approved to spend `amount` or more of ERC-6864 tokens for `from`</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 to release ERC-6864 tokens</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"> The address to receive base ERC-20 tokens</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"> The amount of ERC-6864 tokens to downgrade</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"> downgrade</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>;</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 base ERC-20 smart contract address</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"> address of the base ERC-20 smart 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"> 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><h3 id="see-through-extension">See-through Extension</h3> <p>The <strong>see-through extension</strong> is OPTIONAL. It allows for easy viewing of combined states between this <a href="https://wg-eips.ritovision.com/6864/">ERC-6864</a> and base ERC-20 smart contracts.</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"> IERC6864SeeThrough</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6864</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"> Get the combined total token supply between this ERC-6864 and base ERC-20 smart contracts</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"> combined 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"> combinedTotalSupply</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-storage z-type"> @notice</span><span class="z-comment"> Get the combined token balance of `account` between this ERC-6864 and base ERC-20 smart contracts</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> account</span><span class="z-comment"> The address that owns the tokens</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"> combined 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"> combinedBalanceOf</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 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 combined allowance that `spender` is allowed to spend for `owner` between this ERC-6864 and base ERC-20 smart contracts</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 that owns the tokens</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 that is approve to spend the tokens</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"> combined spending allowance</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"> combinedAllowance</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"> 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></code></pre><h2 id="rationale">Rationale</h2> <h3 id="extending-erc-20-standard">Extending ERC-20 standard</h3> <p>The goal of this proposal is to upgrade without affecting user balances, therefore leveraging existing data structure and methods is the path of the least engineering efforts as well as the most interoperability.</p> <h3 id="supporting-downgrade">Supporting downgrade</h3> <p>The ability to downgrade makes moving between multiple IERC-6864 implementations on the same base ERC-20 smart contract possible. It also allows a way out should bugs or limitations discovered on ERC-6864 smart contract, or the user simply changes his or her mind.</p> <h3 id="optional-see-through-extension">Optional see-through extension</h3> <p>While these functions are useful in many situations, they are trivial to implement and results can be calculated via other public functions, hence the decision to include them in an optional extension rather than the core interface.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>ERC-6864 is generally compatible with the ERC-20 standard. The only caveat is that some smart contracts may opt to implement <code>transfer</code> to work with the entire combined balance (this reduces user friction, see reference implementation) rather than the standard <code>balanceOf</code> amount. In this case it is RECOMMENDED that such contract to implement <code>totalSupply</code> and <code>balanceOf</code> to return combined amount between this ERC-6864 and base ERC-20 smart contracts</p> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">IERC20</span><span>, </span><span class="z-entity z-name">ERC20</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin-contracts/token/ERC20/ERC20.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"> ERC6864</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6864</span><span>, </span><span class="z-entity z-name">ERC20</span><span> {</span></span> <span class="giallo-l"><span> IERC20 </span><span class="z-storage z-type">private</span><span class="z-storage z-type"> immutable</span><span> s_baseToken</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"> address</span><span class="z-variable"> baseToken_</span><span>)</span><span class="z-entity z-name"> ERC20</span><span>(</span><span>name, symbol) </span><span>{</span></span> <span class="giallo-l"><span> s_baseToken </span><span class="z-keyword">=</span><span class="z-entity z-name"> IERC20</span><span>(</span><span>baseToken_</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"> baseToken</span><span>(</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"> return</span><span class="z-support"> address</span><span>(</span><span>s_baseToken</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">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"> 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-support"> address</span><span> from </span><span class="z-keyword">=</span><span class="z-entity z-name"> _msgSender</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> s_baseToken</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span>from</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> amount</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> amount</span><span>)</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"> Upgrade</span><span>(</span><span>from</span><span>,</span><span> to</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-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"> 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"> 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-support"> address</span><span> spender </span><span class="z-keyword">=</span><span class="z-entity z-name"> _msgSender</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>from </span><span class="z-keyword">!=</span><span> spender</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _spendAllowance</span><span>(</span><span>from</span><span>,</span><span> spender</span><span>,</span><span> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity z-name"> _burn</span><span>(</span><span>from</span><span>,</span><span> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> s_baseToken</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>to</span><span>,</span><span> amount</span><span>)</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"> Downgrade</span><span>(</span><span>from</span><span>,</span><span> to</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-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"> amount</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 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> from </span><span class="z-keyword">=</span><span class="z-entity z-name"> _msgSender</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> balance </span><span class="z-keyword">=</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span>from</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>balance </span><span class="z-keyword">&lt;</span><span> amount</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> upgrade</span><span>(</span><span>from</span><span>,</span><span> amount </span><span class="z-keyword">-</span><span> balance</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"> _transfer</span><span>(</span><span>from</span><span>,</span><span> to</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> <span class="giallo-l"></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-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">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-keyword"> return</span><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">totalSupply</span><span>(</span><span>)</span><span class="z-keyword"> +</span><span> s_baseToken</span><span>.</span><span class="z-entity z-name">totalSupply</span><span>(</span><span>)</span><span class="z-keyword"> -</span><span> s_baseToken</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> <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-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-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">uint256</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">balanceOf</span><span>(</span><span>account</span><span>)</span><span class="z-keyword"> +</span><span> s_baseToken</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>(</span><span>account</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> <ul> <li>User who opts to upgrade base ERC-20 tokens must first <code>approve</code> the ERC-6864 smart contract to spend them. Therefore it's the user's responsibility to verify that the ERC-6864 smart contract is sound and secure, and the amount that he or she is approving is approperiate. This represents the same security considerations as with any <code>approve</code> operation.</li> <li>The ERC-6864 smart contract may implement any conversion function for upgrade/downgrade as approperiate: 1-to-1, linear, non-linear. In the case of a non-linear conversion function, <code>upgrade</code> and <code>downgrade</code> may be vulnerable for front running or sandwich attacks (whether or not to the attacker's benefit). This represents the same security considerations as with any automated market maker (AMM) that uses a similar non-linear curve for conversion.</li> <li>The ERC-6864 smart contract may ask user to approve unlimited allowance and/or attempt to automatically upgrade during <code>transfer</code> (see reference implementation). This removes the chance for user to triple confirm his or her intension to upgrade (<code>approve</code> being the double confirmation).</li> <li>Multiple IERC-6864 implementations can be applied to the same base ERC-20 token, and ERC-6864 smart contracts can be nested. This would increase token complexity and may cause existing dashboards to report incorrect or inconsistent results.</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> 2023-04-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Qi Zhouhttps://github.com/qizhou Qiang Zhuhttps://github.com/qzhodl https://wg-eips.ritovision.com/6821/

A mapping from an ENS name to the contract address in Web3 URL

<h2 id="abstract">Abstract</h2> <p>This standard defines the mapping from an Ethereum name service (ENS) name to an Ethereum address for <a href="https://wg-eips.ritovision.com/4804/">ERC-4804</a>.</p> <h2 id="motivation">Motivation</h2> <p>ERC-4804 defines a <code>web3://</code>-scheme RFC 2396 URI to call a smart contract either by its address or a <strong>name</strong> from name service. If a <strong>name</strong> is specified, the standard specifies a way to resolve the contract address from the name.</p> <h2 id="specification">Specification</h2> <p>Given <strong>contractName</strong> and <strong>chainid</strong> from a <code>web3://</code> URI defined in ERC-4804, the protocol will find the address of the contract using the following steps:</p> <ol> <li>Find the <code>contentcontract</code> text record on ENS resolver on chain <strong>chainid</strong>. Return an error if the chain does not have ENS or the record is an invalid ETH address.</li> <li>If the <code>contentcontract</code> text record does not exist, the protocol will use the resolved address of <strong>name</strong> from <a href="https://wg-eips.ritovision.com/137/#contract-address-interface">ERC-137</a>.</li> <li>If the resolved address of <strong>name</strong> is the zero address, then return an "address not found" error.</li> </ol> <p>Note that <code>contentcontract</code> text record may return an Ethereum address in hexadecimal with a <code>0x</code> prefix or an <a href="https://wg-eips.ritovision.com/3770/">ERC-3770</a> chain-specific address. If the address is an ERC-3770 chain-specific address, then the <strong>chainid</strong> to call the message will be overridden by the <strong>chainid</strong> specified by the ERC-3770 address.</p> <h2 id="rationale">Rationale</h2> <p>The standard uses <code>contentcontract</code> text record with ERC-3770 chain-specific address instead of <code>contenthash</code> so that the record is human-readable - a design principle of ERC-4804. Further, we can use the text record to add additional fields such as time to live (TTL).</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> 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-31T00:00:00+00:00 2026-02-11T14:48:25+00:00 Mihai Onilahttps://github.com/MihaiORO Nick Zemanhttps://github.com/NickZCZ Narcis Cotaiehttps://github.com/NarcisCRO https://wg-eips.ritovision.com/6808/

An interface for Fungible Key Bound Tokens, also known as a FKBT.

<h2 id="abstract">Abstract</h2> <p>A standard interface for Fungible Key Bound Tokens (<strong>FKBT/s</strong>), a subset of the more general Key Bound Tokens (<strong>KBT/s</strong>).</p> <p>The following standardizes an API for tokens within smart contracts and provides basic functionality to the <a href="https://wg-eips.ritovision.com/6808/#addbindings-function">addBindings</a> function. This function designates <strong>Key Wallets</strong><sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">1</a></sup>, which are responsible for conducting a <strong>Safe Transfer</strong><sup class="footnote-reference" id="fr-2-1"><a href="#fn-2">2</a></sup>. During this process, <strong>FKBT's</strong> are safely approved so they can be spent by the user or an on-chain third-party entity.</p> <p>The premise of <strong>FKBT's</strong> is to provide fully optional security features built directly into the fungible asset, via the concept of <em>allow</em> found in the <a href="https://wg-eips.ritovision.com/6808/#allowtransfer-function">allowTransfer</a> and <a href="https://wg-eips.ritovision.com/6808/#allowapproval-function">allowApproval</a> functions. These functions are called by one of the <strong>Key Wallets</strong><sup class="footnote-reference" id="fr-1-2"><a href="#fn-1">1</a></sup> and <em>allow</em> the <strong>Holding Wallet</strong><sup class="footnote-reference" id="fr-3-1"><a href="#fn-3">3</a></sup> to either call the already familiar <code>transfer</code> and <code>approve</code> function found in <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. Responsibility for the <strong>FKBT</strong> is therefore split. The <strong>Holding Wallet</strong> contains the asset and <strong>Key Wallets</strong> have authority over how the assets can be spent or approved. <strong>Default Behaviors</strong><sup class="footnote-reference" id="fr-4-1"><a href="#fn-4">4</a></sup> of a traditional fungible ERC-20 can be achieved by simply never using the <a href="https://wg-eips.ritovision.com/6808/#addbindings-function">addBindings</a> function.</p> <p>We considered <strong>FKBTs</strong> being used by every individual who wishes to add additional security to their fungible assets, as well as consignment to third-party wallets/brokers/banks/insurers. <strong>FKBTs</strong> are resilient to attacks/thefts, by providing additional protection to the asset itself on a self-custodial level.</p> <h2 id="motivation">Motivation</h2> <p>In this fast-paced technologically advancing world, people learn and mature at different speeds. The goal of global adoption must take into consideration the target demographic is of all ages and backgrounds. Unfortunately for self-custodial assets, one of the greatest pros is also one of its greatest cons. The individual is solely responsible for their actions and adequately securing their assets. If a mistake is made leading to a loss of funds, no one is able to guarantee their return.</p> <p>From January 2021 through March 2022, the United States Federal Trade Commission received more than 46,000<sup class="footnote-reference" id="fr-5-1"><a href="#fn-5">5</a></sup> crypto scam reports. This directly impacted crypto users and resulted in a net consumer loss exceeding $1 Billion<sup class="footnote-reference" id="fr-6-1"><a href="#fn-6">6</a></sup>. Theft and malicious scams are an issue in any financial sector and oftentimes lead to stricter regulation. However, government-imposed regulation goes against one of this space’s core values. Efforts have been made to increase security within the space through centralized and decentralized means. Up until now, no one has offered a solution that holds onto the advantages of both whilst eliminating their disadvantages.</p> <p>We asked ourselves the same question as many have in the past, “How does one protect the wallet?”. After a while, realizing the question that should be asked is “How does one protect the asset?”. Creating the wallet is free, the asset is what has value and is worth protecting. This question led to the development of <strong>KBT's</strong>. A solution that is fully optional and can be tailored so far as the user is concerned. Individual assets remain protected even if the seed phrase or private key is publicly released, as long as the security feature was activated.</p> <p><strong>FKBTs</strong> saw the need to improve on the widely used fungible ERC-20 token standard. The security of fungible assets is a topic that concerns every entity in the crypto space, as their current and future use cases are continuously explored. <strong>FKBTs</strong> provide a scalable decentralized security solution that takes security one step beyond wallet security, focusing on the token's ability to remain secure. The security is on the blockchain itself, which allows every demographic that has access to the internet to secure their assets without the need for current hardware or centralized solutions. Made to be a promising alternative, <strong>FKBTs</strong> inherit all the characteristics of an ERC-20. This was done so <strong>FKBTs</strong> could be used on every dApp that is configured to use traditional fungible tokens.</p> <p>During the development process, the potential advantages <strong>KBT's</strong> explored were the main motivation factors leading to their creation;</p> <ol> <li> <p><strong>Completely Decentralized:</strong> The security features are fully decentralized meaning no third-party will have access to user funds when activated. This was done to truly stay in line with the premise of self-custodial assets, responsibility and values.</p> </li> <li> <p><strong>Limitless Scalability:</strong> Centralized solutions require the creation of an account and their availability may be restricted based on location. <strong>FKBT's</strong> do not face regional restrictions or account creation. Decentralized security solutions such as hardware options face scalability issues requiring transport logistics, secure shipping and vendor. <strong>FKBT's</strong> can be used anywhere around the world by anyone who so wishes, provided they have access to the internet.</p> </li> <li> <p><strong>Fully Optional Security:</strong> Security features are optional, customizable and removable. It’s completely up to the user to decide the level of security they would like when using <strong>FKBT's</strong>.</p> </li> <li> <p><strong>Default Functionality:</strong> If the user would like to use <strong>FKBT's</strong> as a traditional ERC-20, the security features do not have to be activated. As the token inherits all of the same characteristics, it results in the token acting with traditional fungible <strong>Default Behaviors</strong><sup class="footnote-reference" id="fr-4-2"><a href="#fn-4">4</a></sup>. However, even when the security features are activated, the user will still have the ability to customize the functionality of the various features based on their desired outcome. The user can pass a set of custom and or <strong>Default Values</strong><sup class="footnote-reference" id="fr-7-1"><a href="#fn-7">7</a></sup> manually or through a dApp.</p> </li> <li> <p><strong>Unmatched Security:</strong> By calling the <a href="https://wg-eips.ritovision.com/6808/#addbindings-function">addBindings</a> function a <strong>Key Wallet</strong><sup class="footnote-reference" id="fr-1-3"><a href="#fn-1">1</a></sup> is now required for the <a href="https://wg-eips.ritovision.com/6808/#allowtransfer-function">allowTransfer</a> or <a href="https://wg-eips.ritovision.com/6808/#allowapproval-function">allowApproval</a> function. The <a href="https://wg-eips.ritovision.com/6808/#allowtransfer-function">allowTransfer</a> function requires 4 parameters, <code>_amount</code><sup class="footnote-reference" id="fr-8-1"><a href="#fn-8">8</a></sup>, <code>_time</code><sup class="footnote-reference" id="fr-9-1"><a href="#fn-9">9</a></sup>, <code>_address</code><sup class="footnote-reference" id="fr-10-1"><a href="#fn-10">10</a></sup>, and <code>_allFunds</code><sup class="footnote-reference" id="fr-11-1"><a href="#fn-11">11</a></sup>, where as the <a href="https://wg-eips.ritovision.com/6808/#allowapproval-function">allowApproval</a> function has 2 parameters, <code>_time</code><sup class="footnote-reference" id="fr-12-1"><a href="#fn-12">12</a></sup> and <code>_numberOfTransfers</code><sup class="footnote-reference" id="fr-13-1"><a href="#fn-13">13</a></sup>. In addition to this, <strong>FKBT's</strong> have a <a href="https://wg-eips.ritovision.com/6808/#safefallback-function">safeFallback</a> and <a href="https://wg-eips.ritovision.com/6808/#resetbindings-function">resetBindings</a> function. The combination of all these prevent and virtually cover every single point of failure that is present with a traditional ERC-20, when properly used.</p> </li> <li> <p><strong>Security Fail-Safes:</strong> With <strong>FKBTs</strong>, users can be confident that their tokens are safe and secure, even if the <strong>Holding Wallet</strong><sup class="footnote-reference" id="fr-3-2"><a href="#fn-3">3</a></sup> or one of the <strong>Key Wallets</strong><sup class="footnote-reference" id="fr-1-4"><a href="#fn-1">1</a></sup> has been compromised. If the owner suspects that the <strong>Holding Wallet</strong> has been compromised or lost access, they can call the <a href="https://wg-eips.ritovision.com/6808/#safefallback-function">safeFallback</a> function from one of the <strong>Key Wallets</strong>. This moves the assets to the other <strong>Key Wallet</strong> preventing a single point of failure. If the owner suspects that one of the <strong>Key Wallets</strong> has been comprised or lost access, the owner can call the <a href="https://wg-eips.ritovision.com/6808/#resetbindings-function">resetBindings</a> function from <code>_keyWallet1</code><sup class="footnote-reference" id="fr-15-1"><a href="#fn-15">14</a></sup> or <code>_keyWallet2</code><sup class="footnote-reference" id="fr-16-1"><a href="#fn-16">15</a></sup>. This resets the <strong>FKBT's</strong> security feature and allows the <strong>Holding Wallet</strong> to call the <a href="https://wg-eips.ritovision.com/6808/#addbindings-function">addBindings</a> function again. New <strong>Key Wallets</strong> can therefore be added and a single point of failure can be prevented.</p> </li> <li> <p><strong>Anonymous Security:</strong> Frequently, centralized solutions ask for personal information that is stored and subject to prying eyes. Purchasing decentralized hardware solutions are susceptible to the same issues e.g. a shipping address, payment information, or a camera recording during a physical cash pick-up. This may be considered by some as infringing on their privacy and asset anonymity. <strong>FKBT's</strong> ensure user confidentially as everything can be done remotely under a pseudonym on the blockchain.</p> </li> <li> <p><strong>Low-Cost Security:</strong> The cost of using <strong>FKBT's</strong> security features correlate to on-chain fees, the current <em>GWEI</em> at the given time. As a standalone solution, they are a viable cost-effective security measure feasible to the majority of the population.</p> </li> <li> <p><strong>Environmentally Friendly:</strong> Since the security features are coded into the <strong>FKBT</strong>, there is no need for centralized servers, shipping, or the production of physical object/s. Thus leading to a minimal carbon footprint by the use of <strong>FKBT's</strong>, working hand in hand with Ethereum’s change to a <em>PoS</em><sup class="footnote-reference" id="fr-14-1"><a href="#fn-14">16</a></sup> network.</p> </li> <li> <p><strong>User Experience:</strong> The security feature can be activated by a simple call to the <a href="https://wg-eips.ritovision.com/6808/#addbindings-function">addBindings</a> function. The user will only need two other wallets, which will act as <code>_keyWallet1</code><sup class="footnote-reference" id="fr-15-2"><a href="#fn-15">14</a></sup> and <code>_keyWallet2</code><sup class="footnote-reference" id="fr-16-2"><a href="#fn-16">15</a></sup>, to gain access to all of the benefits <strong>FKBT's</strong> offer. The optional security features improve the overall user experience and Ethereum ecosystem by ensuring a safety net for those who decide to use it. Those that do not use the security features are not hindered in any way. This safety net can increase global adoption as people can remain confident in the security of their assets, even in the scenario of a compromised wallet.</p> </li> </ol> <h2 id="specification">Specification</h2> <h3 id="ikbt20-token-contract"><code>IKBT20</code> (Token Contract)</h3> <p><strong>NOTES</strong>:</p> <ul> <li>The following specifications use syntax from Solidity <code>0.8.0</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> <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"> IKBT20</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AccountSecured</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"> _amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AccountResetBinding</span><span>(</span><span class="z-support">address</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"> SafeFallbackActivated</span><span>(</span><span class="z-support">address</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"> AccountEnabledTransfer</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"> _amount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _time</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"> bool</span><span class="z-variable"> _allFunds</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"> AccountEnabledApproval</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"> _time</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _numberOfTransfers</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"> Ingress</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"> _amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Egress</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"> _amount</span><span>)</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"> AccountHolderBindings</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> firstWallet</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> secondWallet</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"> FirstAccountBindings</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> accountHolderWallet</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> secondWallet</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"> SecondAccountBindings</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> accountHolderWallet</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> firstWallet</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"> TransferConditions</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 class="z-support"> uint256</span><span> time</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"> bool</span><span> allFunds</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"> ApprovalConditions</span><span> {</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-support"> uint256</span><span> numberOfTransfers</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"> addBindings</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _keyWallet1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _keyWallet2</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-storage z-type"> function</span><span class="z-entity z-name"> getBindings</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 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-storage z-type">AccountHolderBindings</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"> resetBindings</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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeFallback</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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> allowTransfer</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"> uint256</span><span class="z-variable z-parameter z-function"> _time</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"> bool</span><span class="z-variable z-parameter z-function"> _allFunds</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-storage z-type"> function</span><span class="z-entity z-name"> getTransferableFunds</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 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-storage z-type">TransferConditions</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"> allowApproval</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _time</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _numberOfTransfers</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-storage z-type"> function</span><span class="z-entity z-name"> getApprovalConditions</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> account</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-storage z-type">ApprovalConditions</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"> getNumberOfTransfersAllowed</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"> address</span><span class="z-variable z-parameter z-function"> _spender</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-storage z-type"> function</span><span class="z-entity z-name"> isSecureWallet</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _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">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="events">Events</h3> <h4 id="accountsecured-event"><code>AccountSecured</code> event</h4> <p>Emitted when the <code>_account</code> is securing his account by calling the <code>addBindings</code> function.</p> <p><code>_amount</code> is the current balance of the <code>_account</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"> AccountSecured</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"> _amount</span><span>)</span></span></code></pre><h4 id="accountresetbinding-event"><code>AccountResetBinding</code> event</h4> <p>Emitted when the holder is resetting his <code>keyWallets</code> by calling the <code>resetBindings</code> function.</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"> AccountResetBinding</span><span>(</span><span class="z-support">address</span><span class="z-variable"> _account</span><span>)</span></span></code></pre><h4 id="safefallbackactivated-event"><code>SafeFallbackActivated</code> event</h4> <p>Emitted when the holder is choosing to move all the funds to one of the <code>keyWallets</code> by calling the <code>safeFallback</code> function.</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"> SafeFallbackActivated</span><span>(</span><span class="z-support">address</span><span class="z-variable"> _account</span><span>)</span></span></code></pre><h4 id="accountenabledtransfer-event"><code>AccountEnabledTransfer</code> event</h4> <p>Emitted when the <code>_account</code> has allowed for transfer an <code>_amount</code> of tokens for the <code>_time</code> amount of <code>block</code> seconds for <code>_to</code> address (or if the <code>_account</code> has allowed for transfer all funds though <code>_allFunds</code> set to <code>true</code>) by calling the <code>allowTransfer</code> function.</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"> AccountEnabledTransfer</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"> _amount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _time</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> _allFunds</span><span>)</span></span></code></pre><h4 id="accountenabledapproval-event"><code>AccountEnabledApproval</code> event</h4> <p>Emitted when <code>_account</code> has allowed approval, for the <code>_time</code> amount of <code>block</code> seconds and set a <code>_numberOfTransfers</code> allowed, by calling the <code>allowApproval</code> function.</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"> AccountEnabledApproval</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"> _time</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _numberOfTransfers</span><span>)</span></span></code></pre><h4 id="ingress-event"><code>Ingress</code> event</h4> <p>Emitted when <code>_account</code> becomes a holder. <code>_amount</code> is the current balance of the <code>_account</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"> Ingress</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"> _amount</span><span>)</span></span></code></pre><h4 id="egress-event"><code>Egress</code> event</h4> <p>Emitted when <code>_account</code> transfers all his tokens and is no longer a holder. <code>_amount</code> is the previous balance of the <code>_account</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"> Egress</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"> _amount</span><span>)</span></span></code></pre><h3 id="interface-functions"><strong>Interface functions</strong></h3> <p>The functions detailed below MUST be implemented.</p> <h4 id="addbindings-function"><code>addBindings</code> function</h4> <p>Secures the sender account with other two wallets called <code>_keyWallet1</code> and <code>_keyWallet2</code> and MUST fire the <code>AccountSecured</code> event.</p> <p>The function SHOULD <code>revert</code> if:</p> <ul> <li>the sender account is not a holder</li> <li>or the sender is already secured</li> <li>or the keyWallets are the same</li> <li>or one of the keyWallets is the same as the sender</li> <li>or one or both keyWallets are zero address (<code>0x0</code>)</li> <li>or one or both keyWallets are already keyWallets to another holder account</li> </ul> <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"> addBindings</span><span> (</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _keyWallet1</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _keyWallet2</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></code></pre><h4 id="getbindings-function"><code>getBindings</code> function</h4> <p>The function returns the <code>keyWallets</code> for the <code>_account</code> in a <code>struct</code> 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"> AccountHolderBindings</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> firstWallet</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> secondWallet</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-storage z-type">function</span><span class="z-entity z-name"> getBindings</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _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-storage z-type">AccountHolderBindings</span><span class="z-storage z-type"> memory</span><span>)</span></span></code></pre><h4 id="resetbindings-function"><code>resetBindings</code> function</h4> <p><strong>Note:</strong> This function is helpful when one of the two <code>keyWallets</code> is compromised.</p> <p>Called from a <code>keyWallet</code>, the function resets the <code>keyWallets</code> for the <code>holder</code> account. MUST fire the <code>AccountResetBinding</code> event.</p> <p>The function SHOULD <code>revert</code> if the sender is not a <code>keyWallet</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"> resetBindings</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></code></pre><h4 id="safefallback-function"><code>safeFallback</code> function</h4> <p><strong>Note:</strong> This function is helpful when the <code>holder</code> account is compromised.</p> <p>Called from a <code>keyWallet</code>, this function transfers all the tokens from the <code>holder</code> account to the other <code>keyWallet</code> and MUST fire the <code>SafeFallbackActivated</code> event.</p> <p>The function SHOULD <code>revert</code> if the sender is not a <code>keyWallet</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"> safeFallback</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></code></pre><h4 id="allowtransfer-function"><code>allowTransfer</code> function</h4> <p>Called from a <code>keyWallet</code>, this function is called before a <code>transfer</code> function is called.</p> <p>It allows to transfer a maximum amount, for a specific time frame, to a specific address.</p> <p>If the amount is 0 then there will be no restriction on the amount. If the time is 0 then there will be no restriction on the time. If the to address is zero address then there will be no restriction on the to address. Or if <code>_allFunds</code> is <code>true</code>, regardless of the other params, it allows all funds, whenever, to anyone to be transferred.</p> <p>The function MUST fire <code>AccountEnabledTransfer</code> event.</p> <p>The function SHOULD <code>revert</code> if the sender is not a <code>keyWallet</code> or if the <code>_amount</code> is greater than the <code>holder</code> account balance.</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"> allowTransfer</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-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _allFunds</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></code></pre><h4 id="gettransferablefunds-function"><code>getTransferableFunds</code> function</h4> <p>The function returns the transfer conditions for the <code>_account</code> in a <code>struct</code> 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"> TransferConditions</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 class="z-support"> uint256</span><span> time</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"> bool</span><span> allFunds</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-storage z-type">function</span><span class="z-entity z-name"> getTransferableFunds</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _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-storage z-type">TransferConditions</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre><h4 id="allowapproval-function"><code>allowApproval</code> function</h4> <p>Called from a <code>keyWallet</code>, this function is called before one of the <code>approve</code>, <code>increaseAllowance</code> or <code>decreaseAllowance</code> function are called.</p> <p>It allows the <code>holder</code> for a specific amount of <code>_time</code> to do an <code>approve</code>, <code>increaseAllowance</code> or <code>decreaseAllowance</code> and limit the number of transfers the spender is allowed to do through <code>_numberOfTransfers</code> (0 - unlimited number of transfers in the allowance limit).</p> <p>The function MUST fire <code>AccountEnabledApproval</code> event.</p> <p>The function SHOULD <code>revert</code> if the sender is not a <code>keyWallet</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"> allowApproval</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _time</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _numberOfTransfers</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></code></pre><h4 id="getapprovalconditions-function"><code>getApprovalConditions</code> function</h4> <p>The function returns the approval conditions in a struct format. Where <code>time</code> is the <code>block.timestamp</code> until the <code>approve</code>, <code>increaseAllowance</code> or <code>decreaseAllowance</code> functions can be called, and <code>numberOfTransfers</code> is the number of transfers the spender will be allowed.</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"> ApprovalConditions</span><span> {</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-support"> uint256</span><span> numberOfTransfers</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-storage z-type">function</span><span class="z-entity z-name"> getApprovalConditions</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _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-storage z-type">ApprovalConditions</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre><h4 id="transfer-function"><code>transfer</code> function</h4> <p>The function transfers <code>_amount</code> of tokens to address <code>_to</code>.</p> <p>The function MUST fire the <code>Transfer</code> event.</p> <p>The function SHOULD <code>revert</code> if the sender’s account balance does not have enough tokens to spend, or if the sender is a secure account and it has not allowed the transfer of funds through <code>allowTransfer</code> function.</p> <p><strong>Note:</strong> Transfers of <code>0</code> values MUST be treated as normal transfers and fire the <code>Transfer</code> 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"> 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"> _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></code></pre><h4 id="approve-function"><code>approve</code> function</h4> <p>The function allows <code>_spender</code> to transfer from the <code>holder</code> account multiple times, up to the <code>_value</code> amount.</p> <p>The function also limits the <code>_spender</code> to the specific number of transfers set in the <code>ApprovalConditions</code> for that <code>holder</code> account. If the value is <code>0</code> then the <code>_spender</code> can transfer multiple times, up to the <code>_value</code> amount.</p> <p>The function MUST fire an <code>Approval</code> event.</p> <p>If this function is called again it overrides the current allowance with <code>_value</code> and also overrides the number of transfers allowed with <code>_numberOfTransfers</code>, set in <code>allowApproval</code> function.</p> <p>The function SHOULD <code>revert</code> if:</p> <ul> <li>the sender account is secured and has not called <code>allowApproval</code> function</li> <li>or if the <code>_time</code>, set in the <code>allowApproval</code> function, has elapsed.</li> </ul> <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"> _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></code></pre><h4 id="increaseallowance-function"><code>increaseAllowance</code> function</h4> <p>The function increases the allowance granted to <code>_spender</code> to withdraw from your account.</p> <p>The function Emits an <code>Approval</code> event indicating the updated allowance.</p> <p>The function SHOULD <code>revert</code> if:</p> <ul> <li>the sender account is secured and has not called <code>allowApproval</code> function</li> <li>or if the <code>_spender</code> is a zero address (<code>0x0</code>)</li> <li>or if the <code>_time</code>, set in the <code>allowApproval</code> function, has elapsed.</li> </ul> <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"> increaseAllowance</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"> _addedValue</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></code></pre><h4 id="decreaseallowance-function"><code>decreaseAllowance</code> function</h4> <p>The function decreases the allowance granted to <code>_spender</code> to withdraw from your account.</p> <p>The function Emits an <code>Approval</code> event indicating the updated allowance.</p> <p>The function SHOULD <code>revert</code> if:</p> <ul> <li>the sender account is secured and has not called <code>allowApproval</code> function</li> <li>or if the <code>_spender</code> is a zero address (<code>0x0</code>)</li> <li>or if the <code>_time</code>, set in the <code>allowApproval</code> function, has elapsed.</li> <li>or if the <code>_subtractedValue</code> is greater than the current allowance</li> </ul> <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"> decreaseAllowance</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"> _subtractedValue</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></code></pre><h4 id="transferfrom-function"><code>transferFrom</code> function</h4> <p>The function transfers <code>_amount</code> of tokens from address <code>_from</code> to address <code>_to</code>.</p> <p>The function MUST fire the <code>Transfer</code> event.</p> <p>The <code>transferFrom</code> method is used for a withdraw workflow, allowing contracts to transfer tokens on your behalf. The function SHOULD <code>revert</code> unless the <code>_from</code> account has deliberately authorized the sender. Each time the spender calls the function the contract subtracts and checks if the number of allowed transfers has reached 0, and when that happens the approval is revoked using an approve of 0 amount.</p> <p><strong>Note:</strong> Transfers of 0 values MUST be treated as normal transfers and fire the <code>Transfer</code> 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"> 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"> _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></code></pre><h2 id="rationale">Rationale</h2> <p>The intent from individual technical decisions made during the development of <strong>FKBTs</strong> focused on maintaining consistency and backward compatibility with ERC-20s, all the while offering self-custodial security features to the user. It was important that <strong>FKBT's</strong> inherited all of ERC-20s characteristics to comply with requirements found in dApps which use fungible tokens on their platform. In doing so, it allowed for flawless backward compatibility to take place and gave the user the choice to decide if they want their <strong>FKBTs</strong> to act with <strong>Default Behaviors</strong><sup class="footnote-reference" id="fr-4-3"><a href="#fn-4">4</a></sup>. We wanted to ensure that wide-scale implementation and adoption of <strong>FKBTs</strong> could take place immediately, without the greater collective needing to adapt and make changes to the already flourishing decentralized ecosystem.</p> <p>For developers and users alike, the <a href="https://wg-eips.ritovision.com/6808/#allowtransfer-function">allowTransfer</a> and <a href="https://wg-eips.ritovision.com/6808/#allowapproval-function">allowApproval</a> functions both return bools on success and revert on failures. This decision was done purposefully, to keep consistency with the already familiar ERC-20. Additional technical decisions related to self-custodial security features are broken down and located within the <a href="https://wg-eips.ritovision.com/6808/#security-considerations">Security Considerations</a> section.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><strong>KBT's</strong> are designed to be backward-compatible with existing token standards and wallets. Existing tokens and wallets will continue to function as normal, and will not be affected by the implementation of <strong>FKBT's</strong>.</p> <h2 id="test-cases">Test Cases</h2> <p>The <a href="https://wg-eips.ritovision.com/6808/assets/README/">assets</a> directory has all the <a href="https://wg-eips.ritovision.com/6808/./assets/test/kbt20.js">tests</a>.</p> <p>Average Gas used (<em>GWEI</em>):</p> <ul> <li><code>addBindings</code> - 154,991</li> <li><code>resetBindings</code> - 30,534</li> <li><code>safeFallback</code> - 51,013</li> <li><code>allowTransfer</code> - 49,887</li> <li><code>allowApproval</code> - 44,971</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>The implementation is located in the <a href="https://wg-eips.ritovision.com/6808/assets/README/">assets</a> directory. There's also a <a href="https://wg-eips.ritovision.com/6808/./assets/Contract%20Interactions%20diagram.svg">diagram</a> with the contract interactions.</p> <h2 id="security-considerations">Security Considerations</h2> <p><strong>FKBT's</strong> were designed with security in mind every step of the way. Below are some design decisions that were rigorously discussed and thought through during the development process.</p> <p><strong>Key Wallets</strong><sup class="footnote-reference" id="fr-1-5"><a href="#fn-1">1</a></sup>: When calling the <a href="https://wg-eips.ritovision.com/6808/#addbindings-function">addBindings</a> function for an <strong>FKBT</strong>, the user must input 2 wallets that will then act as <code>_keyWallet1</code><sup class="footnote-reference" id="fr-15-3"><a href="#fn-15">14</a></sup> and <code>_keyWallet2</code><sup class="footnote-reference" id="fr-16-3"><a href="#fn-16">15</a></sup>. They are added simultaneously to reduce user fees, minimize the chance of human error and prevent a pitfall scenario. If the user had the ability to add multiple wallets it would not only result in additional fees and avoidable confusion but would enable a potentially disastrous <a href="https://wg-eips.ritovision.com/6808/#safefallback-function">safeFallback</a> situation to occur. For this reason, all <strong>KBT's</strong> work under a 3-wallet system when security features are activated.</p> <p>Typically if a wallet is compromised, the fungible assets within are at risk. With <strong>FKBT's</strong> there are two different functions that can be called from a <strong>Key Wallet</strong><sup class="footnote-reference" id="fr-1-6"><a href="#fn-1">1</a></sup> depending on which wallet has been compromised.</p> <p>Scenario: <strong>Holding Wallet</strong><sup class="footnote-reference" id="fr-3-3"><a href="#fn-3">3</a></sup> has been compromised, call <a href="https://wg-eips.ritovision.com/6808/#safefallback-function">safeFallback</a>.</p> <p><a href="https://wg-eips.ritovision.com/6808/#safefallback-function">safeFallback</a>: This function was created in the event that the owner believes the <strong>Holding Wallet</strong><sup class="footnote-reference" id="fr-3-4"><a href="#fn-3">3</a></sup> has been compromised. It can also be used if the owner losses access to the <strong>Holding Wallet</strong>. In this scenario, the user has the ability to call <a href="https://wg-eips.ritovision.com/6808/#safefallback-function">safeFallback</a> from one of the <strong>Key Wallets</strong><sup class="footnote-reference" id="fr-1-7"><a href="#fn-1">1</a></sup>. <strong>FKBT's</strong> are then redirected from the <strong>Holding Wallet</strong> to the other <strong>Key Wallet</strong>.</p> <p>By redirecting the <strong>FKBT's</strong> it prevents a single point of failure. If an attacker were to call <a href="https://wg-eips.ritovision.com/6808/#safefallback-function">safeFallback</a> and the <strong>FKBT's</strong> redirected to the <strong>Key Wallet</strong><sup class="footnote-reference" id="fr-1-8"><a href="#fn-1">1</a></sup> that called the function, they would gain access to all the <strong>FKBT's</strong>.</p> <p>Scenario: <strong>Key Wallet</strong><sup class="footnote-reference" id="fr-1-9"><a href="#fn-1">1</a></sup> has been compromised, call <a href="https://wg-eips.ritovision.com/6808/#resetbindings-function">resetBindings</a>.</p> <p><a href="https://wg-eips.ritovision.com/6808/#resetbindings-function">resetBindings</a>: This function was created in the event that the owner believes <code>_keyWallet1</code><sup class="footnote-reference" id="fr-15-4"><a href="#fn-15">14</a></sup> or <code>_keyWallet2</code><sup class="footnote-reference" id="fr-16-4"><a href="#fn-16">15</a></sup> has been compromised. It can also be used if the owner losses access to one of the <strong>Key Wallets</strong><sup class="footnote-reference" id="fr-1-10"><a href="#fn-1">1</a></sup>. In this instance, the user has the ability to call <a href="https://wg-eips.ritovision.com/6808/#resetbindings-function">resetBindings</a>, removing the bound <strong>Key Wallets</strong> and resetting the security features. The <strong>FKBT's</strong> will now function as a traditional ERC-20 until <a href="https://wg-eips.ritovision.com/6808/#addbindings-function">addBindings</a> is called again and a new set of <strong>Key Wallets</strong> are added.</p> <p>The reason why <code>_keyWallet1</code><sup class="footnote-reference" id="fr-15-5"><a href="#fn-15">14</a></sup> or <code>_keyWallet2</code><sup class="footnote-reference" id="fr-16-5"><a href="#fn-16">15</a></sup> are required to call the <a href="https://wg-eips.ritovision.com/6808/#resetbindings-function">resetBindings</a> function is because a <strong>Holding Wallet</strong><sup class="footnote-reference" id="fr-3-5"><a href="#fn-3">3</a></sup> having the ability to call <a href="https://wg-eips.ritovision.com/6808/#resetbindings-function">resetBindings</a> could result in an immediate loss of <strong>FKBT's</strong>. The attacker would only need to gain access to the <strong>Holding Wallet</strong> and call <a href="https://wg-eips.ritovision.com/6808/#resetbindings-function">resetBindings</a>.</p> <p>In the scenario that 2 of the 3 wallets have been compromised, there is nothing the owner of the <strong>FKBT's</strong> can do if the attack is malicious. However, by allowing 1 wallet to be compromised, holders of fungible tokens built using the <strong>FKBT</strong> standard are given a second chance, unlike other current standards.</p> <p>The <a href="https://wg-eips.ritovision.com/6808/#allowtransfer-function">allowTransfer</a> function is in place to guarantee a <strong>Safe Transfer</strong><sup class="footnote-reference" id="fr-2-2"><a href="#fn-2">2</a></sup>, but can also have <strong>Default Values</strong><sup class="footnote-reference" id="fr-7-2"><a href="#fn-7">7</a></sup> set by a dApp to emulate <strong>Default Behaviors</strong><sup class="footnote-reference" id="fr-3-6"><a href="#fn-3">3</a></sup> of a traditional ERC-20. It enables the user to highly specify the type of transfer they are about to conduct, whilst simultaneously allowing the user to unlock all the <strong>FKBT's</strong> to anyone for an unlimited amount of time. The desired security is completely up to the user.</p> <p>This function requires 4 parameters to be filled and different combinations of these result in different levels of security;</p> <p>Parameter 1 <code>_amount</code><sup class="footnote-reference" id="fr-8-2"><a href="#fn-8">8</a></sup>: This is the number of <strong>FKBT's</strong> that will be spent on a transfer.</p> <p>Parameter 2 <code>_time</code><sup class="footnote-reference" id="fr-9-2"><a href="#fn-9">9</a></sup>: The number of blocks the <strong>FKBT's</strong> can be transferred starting from the current block timestamp.</p> <p>Parameter 3 <code>_address</code><sup class="footnote-reference" id="fr-10-2"><a href="#fn-10">10</a></sup>: The destination the <strong>FKBT's</strong> will be sent to.</p> <p>Parameter 4 <code>_allFunds</code><sup class="footnote-reference" id="fr-11-2"><a href="#fn-11">11</a></sup>: This is a boolean value. When false, the <code>transfer</code> function takes into consideration Parameters 1, 2 and 3. If the value is true, the <code>transfer</code> function will revert to a <strong>Default Behavior</strong><sup class="footnote-reference" id="fr-4-4"><a href="#fn-4">4</a></sup>, the same as a traditional ERC-20.</p> <p>The <a href="https://wg-eips.ritovision.com/6808/#allowtransfer-function">allowTransfer</a> function requires <code>_keyWallet1</code><sup class="footnote-reference" id="fr-15-6"><a href="#fn-15">14</a></sup> or <code>_keyWallet2</code><sup class="footnote-reference" id="fr-16-6"><a href="#fn-16">15</a></sup> and enables the <strong>Holding Wallet</strong><sup class="footnote-reference" id="fr-3-7"><a href="#fn-3">3</a></sup> to conduct a <code>transfer</code> within the previously specified parameters. These parameters were added in order to provide additional security by limiting the <strong>Holding Wallet</strong> in case it was compromised without the user's knowledge.</p> <p>The <a href="https://wg-eips.ritovision.com/6808/#allowapproval-function">allowApproval</a> function provides extra security when allowing on-chain third parties to use your <strong>FKBT's</strong> on your behalf. This is especially useful when a user is met with common malicious attacks e.g. draining dApp.</p> <p>This function requires 2 parameters to be filled and different combinations of these result in different levels of security;</p> <p>Parameter 1 <code>_time</code><sup class="footnote-reference" id="fr-12-2"><a href="#fn-12">12</a></sup>: The number of blocks that the approval of a third-party service can take place, starting from the current block timestamp.</p> <p>Parameter 2 <code>_numberOfTransfers_</code><sup class="footnote-reference" id="fr-13-2"><a href="#fn-13">13</a></sup>: The number of transactions a third-party service can conduct on the user's behalf.</p> <p>The <a href="https://wg-eips.ritovision.com/6808/#allowapproval-function">allowApproval</a> function requires <code>_keyWallet1</code><sup class="footnote-reference" id="fr-15-7"><a href="#fn-15">14</a></sup> or <code>_keyWallet2</code><sup class="footnote-reference" id="fr-16-7"><a href="#fn-16">15</a></sup> and enables the <strong>Holding Wallet</strong><sup class="footnote-reference" id="fr-3-8"><a href="#fn-3">3</a></sup> to allow a third-party service by using the <code>approve</code> function. These parameters were added to provide extra security when granting permission to a third-party that uses assets on the user's behalf. Parameter 1, <code>_time</code><sup class="footnote-reference" id="fr-12-3"><a href="#fn-12">12</a></sup>, is a limitation to when the <strong>Holding Wallet</strong> can <code>approve</code> a third-party service. Parameter 2, <code>_numberOfTransfers</code><sup class="footnote-reference" id="fr-13-3"><a href="#fn-13">13</a></sup>, is a limitation to the number of transactions the approved third-party service can conduct on the user's behalf before revoking approval.</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>The <strong>Key Wallet/s</strong> refers to <code>_keyWallet1</code> or <code>_keyWallet2</code> which can call the <code>safeFallback</code>, <code>resetBindings</code>, <code>allowTransfer</code> and <code>allowApproval</code> functions. <a href="#fr-1-1">↩</a> <a href="#fr-1-2">↩2</a> <a href="#fr-1-3">↩3</a> <a href="#fr-1-4">↩4</a> <a href="#fr-1-5">↩5</a> <a href="#fr-1-6">↩6</a> <a href="#fr-1-7">↩7</a> <a href="#fr-1-8">↩8</a> <a href="#fr-1-9">↩9</a> <a href="#fr-1-10">↩10</a></p> </li> <li id="fn-2"> <p>A <strong>Safe Transfer</strong> is when 1 of the <strong>Key Wallets</strong> safely approved the use of the <strong>FKBT's</strong>. <a href="#fr-2-1">↩</a> <a href="#fr-2-2">↩2</a></p> </li> <li id="fn-3"> <p>The <strong>Holding Wallet</strong> refers to the wallet containing the <strong>FKBT's</strong>. <a href="#fr-3-1">↩</a> <a href="#fr-3-2">↩2</a> <a href="#fr-3-3">↩3</a> <a href="#fr-3-4">↩4</a> <a href="#fr-3-5">↩5</a> <a href="#fr-3-6">↩6</a> <a href="#fr-3-7">↩7</a> <a href="#fr-3-8">↩8</a></p> </li> <li id="fn-4"> <p>A <strong>Default Behavior/s</strong> refers to behavior/s present in the preexisting non-fungible ERC-20 standard. <a href="#fr-4-1">↩</a> <a href="#fr-4-2">↩2</a> <a href="#fr-4-3">↩3</a> <a href="#fr-4-4">↩4</a></p> </li> <li id="fn-5"> <p>The number of crypto scam reports the United States Federal Trade Commission received, from January 2021 through March 2022. <a href="#fr-5-1">↩</a></p> </li> <li id="fn-6"> <p>The amount stolen via crypto scams according to the United States Federal Trade Commission, from January 2021 through March 2022. <a href="#fr-6-1">↩</a></p> </li> <li id="fn-7"> <p>A <strong>Default Value/s</strong> refer to a value/s that emulates the non-fungible ERC-20 <strong>Default Behavior/s</strong>. <a href="#fr-7-1">↩</a> <a href="#fr-7-2">↩2</a></p> </li> <li id="fn-8"> <p>The <code>_amount</code> represents the amount of the <strong>FKBT's</strong> intended to be spent. <a href="#fr-8-1">↩</a> <a href="#fr-8-2">↩2</a></p> </li> <li id="fn-9"> <p>The <code>_time</code> in <code>allowTransfer</code> represents the number of blocks a <code>transfer</code> can take place in. <a href="#fr-9-1">↩</a> <a href="#fr-9-2">↩2</a></p> </li> <li id="fn-10"> <p>The <code>_address</code> represents the address that the <strong>FKBT's</strong> will be sent to. <a href="#fr-10-1">↩</a> <a href="#fr-10-2">↩2</a></p> </li> <li id="fn-11"> <p>The <code>_allFunds</code> is a bool that can be set to true or false. <a href="#fr-11-1">↩</a> <a href="#fr-11-2">↩2</a></p> </li> <li id="fn-12"> <p>The <code>_time</code> in <code>allowApproval</code> represents the number of blocks an <code>approve</code> can take place in. <a href="#fr-12-1">↩</a> <a href="#fr-12-2">↩2</a> <a href="#fr-12-3">↩3</a></p> </li> <li id="fn-13"> <p>The <code>_numberOfTransfers</code> is the number of transfers a third-party entity can conduct via <code>transfer</code> on the user's behalf. <a href="#fr-13-1">↩</a> <a href="#fr-13-2">↩2</a> <a href="#fr-13-3">↩3</a></p> </li> <li id="fn-15"> <p>The <code>_keyWallet1</code> is 1 of the 2 <strong>Key Wallets</strong> set when calling the <code>addBindings</code> function. <a href="#fr-15-1">↩</a> <a href="#fr-15-2">↩2</a> <a href="#fr-15-3">↩3</a> <a href="#fr-15-4">↩4</a> <a href="#fr-15-5">↩5</a> <a href="#fr-15-6">↩6</a> <a href="#fr-15-7">↩7</a></p> </li> <li id="fn-16"> <p>The <code>_keyWallet2</code> is 1 of the 2 <strong>Key Wallets</strong> set when calling the <code>addBindings</code> function. <a href="#fr-16-1">↩</a> <a href="#fr-16-2">↩2</a> <a href="#fr-16-3">↩3</a> <a href="#fr-16-4">↩4</a> <a href="#fr-16-5">↩5</a> <a href="#fr-16-6">↩6</a> <a href="#fr-16-7">↩7</a></p> </li> <li id="fn-14"> <p>A <em>PoS</em> protocol, Proof-of-Stake protocol, is a cryptocurrency consensus mechanism for processing transactions and creating new blocks in a blockchain. <a href="#fr-14-1">↩</a></p> </li> </ol> </section> 2023-03-31T00:00:00+00:00 2026-02-11T14:48:25+00:00 Mihai Onilahttps://github.com/MihaiORO Nick Zemanhttps://github.com/NickZCZ Narcis Cotaiehttps://github.com/NarcisCRO https://wg-eips.ritovision.com/6809/

An interface for Non-Fungible Key Bound Tokens, also known as a NFKBT.

<h2 id="abstract">Abstract</h2> <p>A standard interface for Non-Fungible Key Bound Tokens (<strong>NFKBT/s</strong>), a subset of the more general Key Bound Tokens (<strong>KBT/s</strong>).</p> <p>The following standardizes an API for tokens within smart contracts and provides basic functionality to the <a href="https://wg-eips.ritovision.com/6809/#addbindings-function">addBindings</a> function. This function designates <strong>Key Wallets</strong><sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">1</a></sup>, which are responsible for conducting a <strong>Safe Transfer</strong><sup class="footnote-reference" id="fr-2-1"><a href="#fn-2">2</a></sup>. During this process, <strong>NFKBT's</strong> are safely approved so they can be spent by the user or an on-chain third-party entity.</p> <p>The premise of <strong>NFKBT's</strong> is to provide fully optional security features built directly into the non-fungible asset, via the concept of <em>allow</em> found in the <a href="https://wg-eips.ritovision.com/6809/#allowtransfer-function">allowTransfer</a> and <a href="https://wg-eips.ritovision.com/6809/#allowapproval-function">allowApproval</a> functions. These functions are called by one of the <strong>Key Wallets</strong><sup class="footnote-reference" id="fr-1-2"><a href="#fn-1">1</a></sup> and <em>allow</em> the <strong>Holding Wallet</strong><sup class="footnote-reference" id="fr-3-1"><a href="#fn-3">3</a></sup> to either call the already familiar <code>transferFrom</code> and <code>approve</code> function found in <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. Responsibility for the <strong>NFKBT</strong> is therefore split. The <strong>Holding Wallet</strong> contains the asset and <strong>Key Wallets</strong> have authority over how the assets can be spent or approved. <strong>Default Behaviors</strong><sup class="footnote-reference" id="fr-4-1"><a href="#fn-4">4</a></sup> of a traditional non-fungible ERC-721 can be achieved by simply never using the <a href="https://wg-eips.ritovision.com/6809/#addbindings-function">addBindings</a> function.</p> <p>We considered <strong>NFKBTs</strong> being used by every individual who wishes to add additional security to their non-fungible assets, as well as consignment to third-party wallets/brokers/banks/insurers/galleries. <strong>NFKBTs</strong> are resilient to attacks/thefts, by providing additional protection to the asset itself on a self-custodial level.</p> <h2 id="motivation">Motivation</h2> <p>In this fast-paced technologically advancing world, people learn and mature at different speeds. The goal of global adoption must take into consideration the target demographic is of all ages and backgrounds. Unfortunately for self-custodial assets, one of the greatest pros is also one of its greatest cons. The individual is solely responsible for their actions and adequately securing their assets. If a mistake is made leading to a loss of funds, no one is able to guarantee their return.</p> <p>From January 2021 through March 2022, the United States Federal Trade Commission received more than 46,000<sup class="footnote-reference" id="fr-5-1"><a href="#fn-5">5</a></sup> crypto scam reports. This directly impacted crypto users and resulted in a net consumer loss exceeding $1 Billion<sup class="footnote-reference" id="fr-6-1"><a href="#fn-6">6</a></sup>. Theft and malicious scams are an issue in any financial sector and oftentimes lead to stricter regulation. However, government-imposed regulation goes against one of this space’s core values. Efforts have been made to increase security within the space through centralized and decentralized means. Up until now, no one has offered a solution that holds onto the advantages of both whilst eliminating their disadvantages.</p> <p>We asked ourselves the same question as many have in the past, “How does one protect the wallet?”. After a while, realizing the question that should be asked is “How does one protect the asset?”. Creating the wallet is free, the asset is what has value and is worth protecting. This question led to the development of <strong>KBT's</strong>. A solution that is fully optional and can be tailored so far as the user is concerned. Individual assets remain protected even if the seed phrase or private key is publicly released, as long as the security feature was activated.</p> <p><strong>NFKBTs</strong> saw the need to improve on the widely used non-fungible ERC-721 token standard. The security of non-fungible assets is a topic that concerns every entity in the crypto space, as their current and future use cases are continuously explored. <strong>NFKBTs</strong> provide a scalable decentralized security solution that takes security one step beyond wallet security, focusing on the token's ability to remain secure. The security is on the blockchain itself, which allows every demographic that has access to the internet to secure their assets without the need for current hardware or centralized solutions. Made to be a promising alternative, <strong>NFKBTs</strong> inherit all the characteristics of an ERC-721. This was done so <strong>NFKBTs</strong> could be used on every dApp that is configured to use traditional non-fungible tokens.</p> <p>During the development process, the potential advantages <strong>KBT's</strong> explored were the main motivation factors leading to their creation;</p> <ol> <li> <p><strong>Completely Decentralized:</strong> The security features are fully decentralized meaning no third-party will have access to user funds when activated. This was done to truly stay in line with the premise of self-custodial assets, responsibility and values.</p> </li> <li> <p><strong>Limitless Scalability:</strong> Centralized solutions require the creation of an account and their availability may be restricted based on location. <strong>NFKBT's</strong> do not face regional restrictions or account creation. Decentralized security solutions such as hardware options face scalability issues requiring transport logistics, secure shipping and vendor. <strong>NFKBT's</strong> can be used anywhere around the world by anyone who so wishes, provided they have access to the internet.</p> </li> <li> <p><strong>Fully Optional Security:</strong> Security features are optional, customizable and removable. It’s completely up to the user to decide the level of security they would like when using <strong>NFKBT's</strong>.</p> </li> <li> <p><strong>Default Functionality:</strong> If the user would like to use <strong>NFKBT's</strong> as a traditional ERC-721, the security features do not have to be activated. As the token inherits all of the same characteristics, it results in the token acting with traditional non-fungible <strong>Default Behaviors</strong><sup class="footnote-reference" id="fr-4-2"><a href="#fn-4">4</a></sup>. However, even when the security features are activated, the user will still have the ability to customize the functionality of the various features based on their desired outcome. The user can pass a set of custom and or <strong>Default Values</strong><sup class="footnote-reference" id="fr-7-1"><a href="#fn-7">7</a></sup> manually or through a dApp.</p> </li> <li> <p><strong>Unmatched Security:</strong> By calling the <a href="https://wg-eips.ritovision.com/6809/#addbindings-function">addBindings</a> function a <strong>Key Wallet</strong><sup class="footnote-reference" id="fr-1-3"><a href="#fn-1">1</a></sup> is now required for the <a href="https://wg-eips.ritovision.com/6809/#allowtransfer-function">allowTransfer</a> or <a href="https://wg-eips.ritovision.com/6809/#allowapproval-function">allowApproval</a> function. The <a href="https://wg-eips.ritovision.com/6809/#allowtransfer-function">allowTransfer</a> function requires 4 parameters, <code>_tokenId</code><sup class="footnote-reference" id="fr-8-1"><a href="#fn-8">8</a></sup>, <code>_time</code><sup class="footnote-reference" id="fr-9-1"><a href="#fn-9">9</a></sup>, <code>_address</code><sup class="footnote-reference" id="fr-10-1"><a href="#fn-10">10</a></sup>, and <code>_anyToken</code><sup class="footnote-reference" id="fr-11-1"><a href="#fn-11">11</a></sup>, where as the <a href="https://wg-eips.ritovision.com/6809/#allowapproval-function">allowApproval</a> function has 2 parameters, <code>_time</code><sup class="footnote-reference" id="fr-12-1"><a href="#fn-12">12</a></sup> and <code>_numberOfTransfers</code><sup class="footnote-reference" id="fr-13-1"><a href="#fn-13">13</a></sup>. In addition to this, <strong>NFKBT's</strong> have a <a href="https://wg-eips.ritovision.com/6809/#safefallback-function">safeFallback</a> and <a href="https://wg-eips.ritovision.com/6809/#resetbindings-function">resetBindings</a> function. The combination of all these prevent and virtually cover every single point of failure that is present with a traditional ERC-721, when properly used.</p> </li> <li> <p><strong>Security Fail-Safes:</strong> With <strong>NFKBTs</strong>, users can be confident that their tokens are safe and secure, even if the <strong>Holding Wallet</strong><sup class="footnote-reference" id="fr-3-2"><a href="#fn-3">3</a></sup> or one of the <strong>Key Wallets</strong><sup class="footnote-reference" id="fr-1-4"><a href="#fn-1">1</a></sup> has been compromised. If the owner suspects that the <strong>Holding Wallet</strong> has been compromised or lost access, they can call the <a href="https://wg-eips.ritovision.com/6809/#safefallback-function">safeFallback</a> function from one of the <strong>Key Wallets</strong>. This moves the assets to the other <strong>Key Wallet</strong> preventing a single point of failure. If the owner suspects that one of the <strong>Key Wallets</strong> has been comprised or lost access, the owner can call the <a href="https://wg-eips.ritovision.com/6809/#resetbindings-function">resetBindings</a> function from <code>_keyWallet1</code><sup class="footnote-reference" id="fr-15-1"><a href="#fn-15">14</a></sup> or <code>_keyWallet2</code><sup class="footnote-reference" id="fr-16-1"><a href="#fn-16">15</a></sup>. This resets the <strong>NFKBT's</strong> security feature and allows the <strong>Holding Wallet</strong> to call the <a href="https://wg-eips.ritovision.com/6809/#addbindings-function">addBindings</a> function again. New <strong>Key Wallets</strong> can therefore be added and a single point of failure can be prevented.</p> </li> <li> <p><strong>Anonymous Security:</strong> Frequently, centralized solutions ask for personal information that is stored and subject to prying eyes. Purchasing decentralized hardware solutions are susceptible to the same issues e.g. a shipping address, payment information, or a camera recording during a physical cash pick-up. This may be considered by some as infringing on their privacy and asset anonymity. <strong>NFKBT's</strong> ensure user confidentially as everything can be done remotely under a pseudonym on the blockchain.</p> </li> <li> <p><strong>Low-Cost Security:</strong> The cost of using <strong>NFKBT's</strong> security features correlate to on-chain fees, the current <em>GWEI</em> at the given time. As a standalone solution, they are a viable cost-effective security measure feasible to the majority of the population.</p> </li> <li> <p><strong>Environmentally Friendly:</strong> Since the security features are coded into the <strong>NFKBT</strong>, there is no need for centralized servers, shipping, or the production of physical object/s. Thus leading to a minimal carbon footprint by the use of <strong>NFKBT's</strong>, working hand in hand with Ethereum’s change to a <em>PoS</em><sup class="footnote-reference" id="fr-14-1"><a href="#fn-14">16</a></sup> network.</p> </li> <li> <p><strong>User Experience:</strong> The security feature can be activated by a simple call to the <a href="https://wg-eips.ritovision.com/6809/#addbindings-function">addBindings</a> function. The user will only need two other wallets, which will act as <code>_keyWallet1</code><sup class="footnote-reference" id="fr-15-2"><a href="#fn-15">14</a></sup> and <code>_keyWallet2</code><sup class="footnote-reference" id="fr-16-2"><a href="#fn-16">15</a></sup>, to gain access to all of the benefits <strong>NFKBT's</strong> offer. The optional security features improve the overall user experience and Ethereum ecosystem by ensuring a safety net for those who decide to use it. Those that do not use the security features are not hindered in any way. This safety net can increase global adoption as people can remain confident in the security of their assets, even in the scenario of a compromised wallet.</p> </li> </ol> <h2 id="specification">Specification</h2> <h3 id="ikbt721-token-contract"><code>IKBT721</code> (Token Contract)</h3> <p><strong>NOTES</strong>:</p> <ul> <li>The following specifications use syntax from Solidity <code>0.8.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> <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"> IKBT721</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AccountSecured</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 class="z-support">uint256</span><span class="z-variable"> _noOfTokens</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AccountResetBinding</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"> SafeFallbackActivated</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"> AccountEnabledTransfer</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"> _tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _time</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"> bool</span><span class="z-variable"> _anyToken</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"> AccountEnabledApproval</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"> _time</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _numberOfTransfers</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"> Ingress</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"> _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"> Egress</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"> _tokenId</span><span>)</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"> AccountHolderBindings</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> firstWallet</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> secondWallet</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"> FirstAccountBindings</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> accountHolderWallet</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> secondWallet</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"> SecondAccountBindings</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> accountHolderWallet</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> firstWallet</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"> TransferConditions</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 class="z-support"> uint256</span><span> time</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"> bool</span><span> anyToken</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"> ApprovalConditions</span><span> {</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-support"> uint256</span><span> numberOfTransfers</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"> addBindings</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _keyWallet1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _keyWallet2</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-storage z-type"> function</span><span class="z-entity z-name"> getBindings</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 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-storage z-type">AccountHolderBindings</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"> resetBindings</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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeFallback</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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> allowTransfer</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"> _time</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"> bool</span><span class="z-variable z-parameter z-function"> _allTokens</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-storage z-type"> function</span><span class="z-entity z-name"> getTransferableFunds</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 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-storage z-type">TransferConditions</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"> allowApproval</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _time</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _numberOfTransfers</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-storage z-type"> function</span><span class="z-entity z-name"> getApprovalConditions</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> account</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-storage z-type">ApprovalConditions</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"> getNumberOfTransfersAllowed</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"> address</span><span class="z-variable z-parameter z-function"> _spender</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-storage z-type"> function</span><span class="z-entity z-name"> isSecureWallet</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _account</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"> isSecureToken</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-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><h3 id="events">Events</h3> <h4 id="accountsecured-event"><code>AccountSecured</code> event</h4> <p>Emitted when the <code>_account</code> is securing his account by calling the <code>addBindings</code> function.</p> <p><code>_amount</code> is the current balance of the <code>_account</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"> AccountSecured</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"> _amount</span><span>)</span></span></code></pre><h4 id="accountresetbinding-event"><code>AccountResetBinding</code> event</h4> <p>Emitted when the holder is resetting his <code>keyWallets</code> by calling the <code>resetBindings</code> function.</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"> AccountResetBinding</span><span>(</span><span class="z-support">address</span><span class="z-variable"> _account</span><span>)</span></span></code></pre><h4 id="safefallbackactivated-event"><code>SafeFallbackActivated</code> event</h4> <p>Emitted when the holder is choosing to move all the funds to one of the <code>keyWallets</code> by calling the <code>safeFallback</code> function.</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"> SafeFallbackActivated</span><span>(</span><span class="z-support">address</span><span class="z-variable"> _account</span><span>)</span></span></code></pre><h4 id="accountenabledtransfer-event"><code>AccountEnabledTransfer</code> event</h4> <p>Emitted when the <code>_account</code> has allowed for transfer <code>_amount</code> of tokens for the <code>_time</code> amount of <code>block</code> seconds for <code>_to</code> address (or if the <code>_account</code> has allowed for transfer all funds though <code>_anyToken</code> set to <code>true</code>) by calling the <code>allowTransfer</code> function.</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"> AccountEnabledTransfer</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"> _amount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _time</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> _allFunds</span><span>)</span></span></code></pre><h4 id="accountenabledapproval-event"><code>AccountEnabledApproval</code> event</h4> <p>Emitted when <code>_account</code> has allowed approval for the <code>_time</code> amount of <code>block</code> seconds by calling the <code>allowApproval</code> function.</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"> AccountEnabledApproval</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"> _time</span><span>)</span></span></code></pre><h4 id="ingress-event"><code>Ingress</code> event</h4> <p>Emitted when <code>_account</code> becomes a holder. <code>_amount</code> is the current balance of the <code>_account</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"> Ingress</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"> _amount</span><span>)</span></span></code></pre><h4 id="egress-event"><code>Egress</code> event</h4> <p>Emitted when <code>_account</code> transfers all his tokens and is no longer a holder. <code>_amount</code> is the previous balance of the <code>_account</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"> Egress</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"> _amount</span><span>)</span></span></code></pre><h3 id="interface-functions"><strong>Interface functions</strong></h3> <p>The functions detailed below MUST be implemented.</p> <h4 id="addbindings-function"><code>addBindings</code> function</h4> <p>Secures the sender account with other two wallets called <code>_keyWallet1</code> and <code>_keyWallet2</code> and MUST fire the <code>AccountSecured</code> event.</p> <p>The function SHOULD <code>revert</code> if:</p> <ul> <li>the sender account is not a holder</li> <li>or the sender is already secured</li> <li>or the keyWallets are the same</li> <li>or one of the keyWallets is the same as the sender</li> <li>or one or both keyWallets are zero address (<code>0x0</code>)</li> <li>or one or both keyWallets are already keyWallets to another holder account</li> </ul> <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"> addBindings</span><span> (</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _keyWallet1</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _keyWallet2</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></code></pre><h4 id="getbindings-function"><code>getBindings</code> function</h4> <p>The function returns the <code>keyWallets</code> for the <code>_account</code> in a <code>struct</code> 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"> AccountHolderBindings</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> firstWallet</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> secondWallet</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-storage z-type">function</span><span class="z-entity z-name"> getBindings</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _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-storage z-type">AccountHolderBindings</span><span class="z-storage z-type"> memory</span><span>)</span></span></code></pre><h4 id="resetbindings-function"><code>resetBindings</code> function</h4> <p><strong>Note:</strong> This function is helpful when one of the two <code>keyWallets</code> is compromised.</p> <p>Called from a <code>keyWallet</code>, the function resets the <code>keyWallets</code> for the <code>holder</code> account. MUST fire the <code>AccountResetBinding</code> event.</p> <p>The function SHOULD <code>revert</code> if the sender is not a <code>keyWallet</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"> resetBindings</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></code></pre><h4 id="safefallback-function"><code>safeFallback</code> function</h4> <p><strong>Note:</strong> This function is helpful when the <code>holder</code> account is compromised.</p> <p>Called from a <code>keyWallet</code>, this function transfers all the tokens from the <code>holder</code> account to the other <code>keyWallet</code> and MUST fire the <code>SafeFallbackActivated</code> event.</p> <p>The function SHOULD <code>revert</code> if the sender is not a <code>keyWallet</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"> safeFallback</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></code></pre><h4 id="allowtransfer-function"><code>allowTransfer</code> function</h4> <p>Called from a <code>keyWallet</code>, this function is called before a <code>transferFrom</code> or <code>safeTransferFrom</code> functions are called.</p> <p>It allows to transfer a tokenId, for a specific time frame, to a specific address.</p> <p>If the tokenId is 0 then there will be no restriction on the tokenId. If the time is 0 then there will be no restriction on the time. If the to address is zero address then there will be no restriction on the to address. Or if <code>_anyToken</code> is <code>true</code>, regardless of the other params, it allows any token, whenever, to anyone to be transferred of the holder.</p> <p>The function MUST fire <code>AccountEnabledTransfer</code> event.</p> <p>The function SHOULD <code>revert</code> if the sender is not a <code>keyWallet</code> for a holder or if the owner of the <code>_tokenId</code> is different than the <code>holder</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"> allowTransfer</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"> _time</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"> bool</span><span class="z-variable z-parameter z-function"> _anyToken</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></code></pre><h4 id="gettransferablefunds-function"><code>getTransferableFunds</code> function</h4> <p>The function returns the transfer conditions for the <code>_account</code> in a <code>struct</code> 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"> TransferConditions</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 class="z-support"> uint256</span><span> time</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"> bool</span><span> anyToken</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-storage z-type">function</span><span class="z-entity z-name"> getTransferableFunds</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _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-storage z-type">TransferConditions</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre><h4 id="allowapproval-function"><code>allowApproval</code> function</h4> <p>Called from a <code>keyWallet</code>, this function is called before <code>approve</code> or <code>setApprovalForAll</code> functions are called.</p> <p>It allows the <code>holder</code> for a specific amount of <code>_time</code> to do an <code>approve</code> or <code>setApprovalForAll</code> and limit the number of transfers the spender is allowed to do through <code>_numberOfTransfers</code> (0 - unlimited number of transfers in the allowance limit).</p> <p>The function MUST fire <code>AccountEnabledApproval</code> event.</p> <p>The function SHOULD <code>revert</code> if the sender is not a <code>keyWallet</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"> allowApproval</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"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span></span></code></pre><h4 id="getapprovalconditions-function"><code>getApprovalConditions</code> function</h4> <p>The function returns the approval conditions in a struct format. Where <code>time</code> is the <code>block.timestamp</code> until the <code>approve</code> or <code>setApprovalForAll</code> functions can be called, and <code>numberOfTransfers</code> is the number of transfers the spender will be allowed.</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"> ApprovalConditions</span><span> {</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-support"> uint256</span><span> numberOfTransfers</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-storage z-type">function</span><span class="z-entity z-name"> getApprovalConditions</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _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-storage z-type">ApprovalConditions</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre><h4 id="transferfrom-function"><code>transferFrom</code> function</h4> <p>The function transfers from <code>_from</code> address to <code>_to</code> address the <code>_tokenId</code> token.</p> <p>Each time a spender calls the function the contract subtracts and checks if the number of allowed transfers of that spender has reached 0, and when that happens, the approval is revoked using a set approval for all to <code>false</code>.</p> <p>The function MUST fire the <code>Transfer</code> event.</p> <p>The function SHOULD <code>revert</code> if:</p> <ul> <li>the sender is not the owner or is not approved to transfer the <code>_tokenId</code></li> <li>or if the <code>_from</code> address is not the owner of the <code>_tokenId</code></li> <li>or if the sender is a secure account and it has not allowed for transfer this <code>_tokenId</code> through <code>allowTransfer</code> function.</li> </ul> <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"> _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>)</span></span></code></pre><h4 id="safetransferfrom-function"><code>safeTransferFrom</code> function</h4> <p>The function transfers from <code>_from</code> address to <code>_to</code> address the <code>_tokenId</code> token.</p> <p>The function MUST fire the <code>Transfer</code> event.</p> <p>The function SHOULD <code>revert</code> if:</p> <ul> <li>the sender is not the owner or is not approved to transfer the <code>_tokenId</code></li> <li>or if the <code>_from</code> address is not the owner of the <code>_tokenId</code></li> <li>or if the sender is a secure account and it has not allowed for transfer this <code>_tokenId</code> through <code>allowTransfer</code> function.</li> </ul> <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"> safeTransferFrom</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"> _tokenId</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></code></pre><h4 id="safetransferfrom-function-with-data-parameter"><code>safeTransferFrom</code> function, with data parameter</h4> <p>This works identically to the other function with an extra data parameter, except this function just sets data to "".</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"> safeTransferFrom</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"> _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>)</span></span></code></pre><h4 id="approve-function"><code>approve</code> function</h4> <p>The function allows <code>_to</code> account to transfer the <code>_tokenId</code> from the sender account.</p> <p>The function also limits the <code>_to</code> account to the specific number of transfers set in the <code>ApprovalConditions</code> for that <code>holder</code> account. If the value is <code>0</code> then the <code>_spender</code> can transfer multiple times.</p> <p>The function MUST fire an <code>Approval</code> event.</p> <p>If the function is called again it overrides the number of transfers allowed with <code>_numberOfTransfers</code>, set in <code>allowApproval</code> function.</p> <p>The function SHOULD <code>revert</code> if:</p> <ul> <li>the sender is not the current NFT owner, or an authorized operator of the current owner</li> <li>the NFT owner is secured and has not called <code>allowApproval</code> function</li> <li>or if the <code>_time</code>, set in the <code>allowApproval</code> function, has elapsed.</li> </ul> <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"> _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 class="z-entity z-name">ERC721</span><span>,</span><span class="z-entity z-name"> IERC721</span><span>)</span></span></code></pre><h4 id="setapprovalforall-function"><code>setApprovalForAll</code> function</h4> <p>The function enables or disables approval for another account <code>_operator</code> to manage all of sender assets.</p> <p>The function also limits the <code>_to</code> account to the specific number of transfers set in the <code>ApprovalConditions</code> for that <code>holder</code> account. If the value is <code>0</code> then the <code>_spender</code> can transfer multiple times.</p> <p>The function Emits an <code>Approval</code> event indicating the updated allowance.</p> <p>If the function is called again it overrides the number of transfers allowed with <code>_numberOfTransfers</code>, set in <code>allowApproval</code> function.</p> <p>The function SHOULD <code>revert</code> if:</p> <ul> <li>the sender account is secured and has not called <code>allowApproval</code> function</li> <li>or if the <code>_spender</code> is a zero address (<code>0x0</code>)</li> <li>or if the <code>_time</code>, set in the <code>allowApproval</code> function, has elapsed.</li> </ul> <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"> setApprovalForAll</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"> public</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"> IERC721</span><span>)</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The intent from individual technical decisions made during the development of <strong>NFKBTs</strong> focused on maintaining consistency and backward compatibility with ERC-721s, all the while offering self-custodial security features to the user. It was important that <strong>NFKBT's</strong> inherited all of ERC-721s characteristics to comply with requirements found in dApps which use non-fungible tokens on their platform. In doing so, it allowed for flawless backward compatibility to take place and gave the user the choice to decide if they want their <strong>NFKBTs</strong> to act with <strong>Default Behaviors</strong><sup class="footnote-reference" id="fr-4-3"><a href="#fn-4">4</a></sup>. We wanted to ensure that wide-scale implementation and adoption of <strong>NFKBTs</strong> could take place immediately, without the greater collective needing to adapt and make changes to the already flourishing decentralized ecosystem.</p> <p>For developers and users alike, the <a href="https://wg-eips.ritovision.com/6809/#allowtransfer-function">allowTransfer</a> and <a href="https://wg-eips.ritovision.com/6809/#allowapproval-function">allowApproval</a> functions both return bools on success and revert on failures. This decision was done purposefully, to keep consistency with the already familiar ERC-721. Additional technical decisions related to self-custodial security features are broken down and located within the <a href="https://wg-eips.ritovision.com/6809/#security-considerations">Security Considerations</a> section.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><strong>KBT's</strong> are designed to be backward-compatible with existing token standards and wallets. Existing tokens and wallets will continue to function as normal, and will not be affected by the implementation of <strong>NFKBT's</strong>.</p> <h2 id="test-cases">Test Cases</h2> <p>The <a href="https://wg-eips.ritovision.com/6809/assets/README/">assets</a> directory has all the <a href="https://wg-eips.ritovision.com/6809/./assets/test/kbt721.js">tests</a>.</p> <p>Average Gas used (<em>GWEI</em>):</p> <ul> <li><code>addBindings</code> - 155,096</li> <li><code>resetBindings</code> - 30,588</li> <li><code>safeFallback</code> - 72,221 (depending on how many NFTs the holder has)</li> <li><code>allowTransfer</code> - 50,025</li> <li><code>allowApproval</code> - 44,983</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>The implementation is located in the <a href="https://wg-eips.ritovision.com/6809/assets/README/">assets</a> directory. There's also a <a href="https://wg-eips.ritovision.com/6809/./assets/Contract%20Interactions%20diagram.svg">diagram</a> with the contract interactions.</p> <h2 id="security-considerations">Security Considerations</h2> <p><strong>NFKBT's</strong> were designed with security in mind every step of the way. Below are some design decisions that were rigorously discussed and thought through during the development process.</p> <p><strong>Key Wallets</strong><sup class="footnote-reference" id="fr-1-5"><a href="#fn-1">1</a></sup>: When calling the <a href="https://wg-eips.ritovision.com/6809/#addbindings-function">addBindings</a> function for an <strong>NFKBT</strong>, the user must input 2 wallets that will then act as <code>_keyWallet1</code><sup class="footnote-reference" id="fr-15-3"><a href="#fn-15">14</a></sup> and <code>_keyWallet2</code><sup class="footnote-reference" id="fr-16-3"><a href="#fn-16">15</a></sup>. They are added simultaneously to reduce user fees, minimize the chance of human error and prevent a pitfall scenario. If the user had the ability to add multiple wallets it would not only result in additional fees and avoidable confusion but would enable a potentially disastrous <a href="https://wg-eips.ritovision.com/6809/#safefallback-function">safeFallback</a> situation to occur. For this reason, all <strong>KBT's</strong> work under a 3-wallet system when security features are activated.</p> <p>Typically if a wallet is compromised, the non-fungible assets within are at risk. With <strong>NFKBT's</strong> there are two different functions that can be called from a <strong>Key Wallet</strong><sup class="footnote-reference" id="fr-1-6"><a href="#fn-1">1</a></sup> depending on which wallet has been compromised.</p> <p>Scenario: <strong>Holding Wallet</strong><sup class="footnote-reference" id="fr-3-3"><a href="#fn-3">3</a></sup> has been compromised, call <a href="https://wg-eips.ritovision.com/6809/#safefallback-function">safeFallback</a>.</p> <p><a href="https://wg-eips.ritovision.com/6809/#safefallback-function">safeFallback</a>: This function was created in the event that the owner believes the <strong>Holding Wallet</strong><sup class="footnote-reference" id="fr-3-4"><a href="#fn-3">3</a></sup> has been compromised. It can also be used if the owner losses access to the <strong>Holding Wallet</strong>. In this scenario, the user has the ability to call <a href="https://wg-eips.ritovision.com/6809/#safefallback-function">safeFallback</a> from one of the <strong>Key Wallets</strong><sup class="footnote-reference" id="fr-1-7"><a href="#fn-1">1</a></sup>. <strong>NFKBT's</strong> are then redirected from the <strong>Holding Wallet</strong> to the other <strong>Key Wallet</strong>.</p> <p>By redirecting the <strong>NFKBT's</strong> it prevents a single point of failure. If an attacker were to call <a href="https://wg-eips.ritovision.com/6809/#safefallback-function">safeFallback</a> and the <strong>NFKBT's</strong> redirected to the <strong>Key Wallet</strong><sup class="footnote-reference" id="fr-1-8"><a href="#fn-1">1</a></sup> that called the function, they would gain access to all the <strong>NFKBT's</strong>.</p> <p>Scenario: <strong>Key Wallet</strong><sup class="footnote-reference" id="fr-1-9"><a href="#fn-1">1</a></sup> has been compromised, call <a href="https://wg-eips.ritovision.com/6809/#resetbindings-function">resetBindings</a>.</p> <p><a href="https://wg-eips.ritovision.com/6809/#resetbindings-function">resetBindings</a>: This function was created in the event that the owner believes <code>_keyWallet1</code><sup class="footnote-reference" id="fr-15-4"><a href="#fn-15">14</a></sup> or <code>_keyWallet2</code><sup class="footnote-reference" id="fr-16-4"><a href="#fn-16">15</a></sup> has been compromised. It can also be used if the owner losses access to one of the <strong>Key Wallets</strong><sup class="footnote-reference" id="fr-1-10"><a href="#fn-1">1</a></sup>. In this instance, the user has the ability to call <a href="https://wg-eips.ritovision.com/6809/#resetbindings-function">resetBindings</a>, removing the bound <strong>Key Wallets</strong> and resetting the security features. The <strong>NFKBT's</strong> will now function as a traditional ERC-721 until <a href="https://wg-eips.ritovision.com/6809/#addbindings-function">addBindings</a> is called again and a new set of <strong>Key Wallets</strong> are added.</p> <p>The reason why <code>_keyWallet1</code><sup class="footnote-reference" id="fr-15-5"><a href="#fn-15">14</a></sup> or <code>_keyWallet2</code><sup class="footnote-reference" id="fr-16-5"><a href="#fn-16">15</a></sup> are required to call the <a href="https://wg-eips.ritovision.com/6809/#resetbindings-function">resetBindings</a> function is because a <strong>Holding Wallet</strong><sup class="footnote-reference" id="fr-3-5"><a href="#fn-3">3</a></sup> having the ability to call <a href="https://wg-eips.ritovision.com/6809/#resetbindings-function">resetBindings</a> could result in an immediate loss of <strong>NFKBT's</strong>. The attacker would only need to gain access to the <strong>Holding Wallet</strong> and call <a href="https://wg-eips.ritovision.com/6809/#resetbindings-function">resetBindings</a>.</p> <p>In the scenario that 2 of the 3 wallets have been compromised, there is nothing the owner of the <strong>NFKBT's</strong> can do if the attack is malicious. However, by allowing 1 wallet to be compromised, holders of non-fungible tokens built using the <strong>NFKBT</strong> standard are given a second chance, unlike other current standards.</p> <p>The <a href="https://wg-eips.ritovision.com/6809/#allowtransfer-function">allowTransfer</a> function is in place to guarantee a <strong>Safe Transfer</strong><sup class="footnote-reference" id="fr-2-2"><a href="#fn-2">2</a></sup>, but can also have <strong>Default Values</strong><sup class="footnote-reference" id="fr-7-2"><a href="#fn-7">7</a></sup> set by a dApp to emulate <strong>Default Behaviors</strong><sup class="footnote-reference" id="fr-3-6"><a href="#fn-3">3</a></sup> of a traditional ERC-721. It enables the user to highly specify the type of transfer they are about to conduct, whilst simultaneously allowing the user to unlock all the <strong>NFKBT's</strong> to anyone for an unlimited amount of time. The desired security is completely up to the user.</p> <p>This function requires 4 parameters to be filled and different combinations of these result in different levels of security;</p> <p>Parameter 1 <code>_tokenId</code><sup class="footnote-reference" id="fr-8-2"><a href="#fn-8">8</a></sup>: This is the ID of the <strong>NFKBT</strong> that will be spent on a transfer.</p> <p>Parameter 2 <code>_time</code><sup class="footnote-reference" id="fr-9-2"><a href="#fn-9">9</a></sup>: The number of blocks the <strong>NFKBT</strong> can be transferred starting from the current block timestamp.</p> <p>Parameter 3 <code>_address</code><sup class="footnote-reference" id="fr-10-2"><a href="#fn-10">10</a></sup>: The destination the <strong>NFKBT</strong> will be sent to.</p> <p>Parameter 4 <code>_anyToken</code><sup class="footnote-reference" id="fr-11-2"><a href="#fn-11">11</a></sup>: This is a boolean value. When false, the <code>transferFrom</code> function takes into consideration Parameters 1, 2 and 3. If the value is true, the <code>transferFrom</code> function will revert to a <strong>Default Behavior</strong><sup class="footnote-reference" id="fr-4-4"><a href="#fn-4">4</a></sup>, the same as a traditional ERC-721.</p> <p>The <a href="https://wg-eips.ritovision.com/6809/#allowtransfer-function">allowTransfer</a> function requires <code>_keyWallet1</code><sup class="footnote-reference" id="fr-15-6"><a href="#fn-15">14</a></sup> or <code>_keyWallet2</code><sup class="footnote-reference" id="fr-16-6"><a href="#fn-16">15</a></sup> and enables the <strong>Holding Wallet</strong><sup class="footnote-reference" id="fr-3-7"><a href="#fn-3">3</a></sup> to conduct a <code>transferFrom</code> within the previously specified parameters. These parameters were added in order to provide additional security by limiting the <strong>Holding Wallet</strong> in case it was compromised without the user's knowledge.</p> <p>The <a href="https://wg-eips.ritovision.com/6809/#allowapproval-function">allowApproval</a> function provides extra security when allowing on-chain third parties to use your <strong>NFKBT's</strong> on your behalf. This is especially useful when a user is met with common malicious attacks e.g. draining dApp.</p> <p>This function requires 2 parameters to be filled and different combinations of these result in different levels of security;</p> <p>Parameter 1 <code>_time</code><sup class="footnote-reference" id="fr-12-2"><a href="#fn-12">12</a></sup>: The number of blocks that the approval of a third-party service can take place, starting from the current block timestamp.</p> <p>Parameter 2 <code>_numberOfTransfers_</code><sup class="footnote-reference" id="fr-13-2"><a href="#fn-13">13</a></sup>: The number of transactions a third-party service can conduct on the user's behalf.</p> <p>The <a href="https://wg-eips.ritovision.com/6809/#allowapproval-function">allowApproval</a> function requires <code>_keyWallet1</code><sup class="footnote-reference" id="fr-15-7"><a href="#fn-15">14</a></sup> or <code>_keyWallet2</code><sup class="footnote-reference" id="fr-16-7"><a href="#fn-16">15</a></sup> and enables the <strong>Holding Wallet</strong><sup class="footnote-reference" id="fr-3-8"><a href="#fn-3">3</a></sup> to allow a third-party service by using the <code>approve</code> function. These parameters were added to provide extra security when granting permission to a third-party that uses assets on the user's behalf. Parameter 1, <code>_time</code><sup class="footnote-reference" id="fr-12-3"><a href="#fn-12">12</a></sup>, is a limitation to when the <strong>Holding Wallet</strong> can <code>approve</code> a third-party service. Parameter 2, <code>_numberOfTransfers</code><sup class="footnote-reference" id="fr-13-3"><a href="#fn-13">13</a></sup>, is a limitation to the number of transactions the approved third-party service can conduct on the user's behalf before revoking approval.</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>The <strong>Key Wallet/s</strong> refers to <code>_keyWallet1</code> or <code>_keyWallet2</code> which can call the <code>safeFallback</code>, <code>resetBindings</code>, <code>allowTransfer</code> and <code>allowApproval</code> functions. <a href="#fr-1-1">↩</a> <a href="#fr-1-2">↩2</a> <a href="#fr-1-3">↩3</a> <a href="#fr-1-4">↩4</a> <a href="#fr-1-5">↩5</a> <a href="#fr-1-6">↩6</a> <a href="#fr-1-7">↩7</a> <a href="#fr-1-8">↩8</a> <a href="#fr-1-9">↩9</a> <a href="#fr-1-10">↩10</a></p> </li> <li id="fn-2"> <p>A <strong>Safe Transfer</strong> is when 1 of the <strong>Key Wallets</strong> safely approved the use of the <strong>NFKBT's</strong>. <a href="#fr-2-1">↩</a> <a href="#fr-2-2">↩2</a></p> </li> <li id="fn-3"> <p>The <strong>Holding Wallet</strong> refers to the wallet containing the <strong>NFKBT's</strong>. <a href="#fr-3-1">↩</a> <a href="#fr-3-2">↩2</a> <a href="#fr-3-3">↩3</a> <a href="#fr-3-4">↩4</a> <a href="#fr-3-5">↩5</a> <a href="#fr-3-6">↩6</a> <a href="#fr-3-7">↩7</a> <a href="#fr-3-8">↩8</a></p> </li> <li id="fn-4"> <p>A <strong>Default Behavior/s</strong> refers to behavior/s present in the preexisting non-fungible ERC-721 standard. <a href="#fr-4-1">↩</a> <a href="#fr-4-2">↩2</a> <a href="#fr-4-3">↩3</a> <a href="#fr-4-4">↩4</a></p> </li> <li id="fn-5"> <p>The number of crypto scam reports the United States Federal Trade Commission received, from January 2021 through March 2022. <a href="#fr-5-1">↩</a></p> </li> <li id="fn-6"> <p>The amount stolen via crypto scams according to the United States Federal Trade Commission, from January 2021 through March 2022. <a href="#fr-6-1">↩</a></p> </li> <li id="fn-7"> <p>A <strong>Default Value/s</strong> refer to a value/s that emulates the non-fungible ERC-721 <strong>Default Behavior/s</strong>. <a href="#fr-7-1">↩</a> <a href="#fr-7-2">↩2</a></p> </li> <li id="fn-8"> <p>The <code>_tokenId</code> represents the ID of the <strong>NFKBT</strong> intended to be spent. <a href="#fr-8-1">↩</a> <a href="#fr-8-2">↩2</a></p> </li> <li id="fn-9"> <p>The <code>_time</code> in <code>allowTransfer</code> represents the number of blocks a <code>transferFrom</code> can take place in. <a href="#fr-9-1">↩</a> <a href="#fr-9-2">↩2</a></p> </li> <li id="fn-10"> <p>The <code>_address</code> represents the address that the <strong>NFKBT</strong> will be sent to. <a href="#fr-10-1">↩</a> <a href="#fr-10-2">↩2</a></p> </li> <li id="fn-11"> <p>The <code>_anyToken</code> is a bool that can be set to true or false. <a href="#fr-11-1">↩</a> <a href="#fr-11-2">↩2</a></p> </li> <li id="fn-12"> <p>The <code>_time</code> in <code>allowApproval</code> represents the number of blocks an <code>approve</code> can take place in. <a href="#fr-12-1">↩</a> <a href="#fr-12-2">↩2</a> <a href="#fr-12-3">↩3</a></p> </li> <li id="fn-13"> <p>The <code>_numberOfTransfers</code> is the number of transfers a third-party entity can conduct via <code>transferFrom</code> on the user's behalf. <a href="#fr-13-1">↩</a> <a href="#fr-13-2">↩2</a> <a href="#fr-13-3">↩3</a></p> </li> <li id="fn-15"> <p>The <code>_keyWallet1</code> is 1 of the 2 <strong>Key Wallets</strong> set when calling the <code>addBindings</code> function. <a href="#fr-15-1">↩</a> <a href="#fr-15-2">↩2</a> <a href="#fr-15-3">↩3</a> <a href="#fr-15-4">↩4</a> <a href="#fr-15-5">↩5</a> <a href="#fr-15-6">↩6</a> <a href="#fr-15-7">↩7</a></p> </li> <li id="fn-16"> <p>The <code>_keyWallet2</code> is 1 of the 2 <strong>Key Wallets</strong> set when calling the <code>addBindings</code> function. <a href="#fr-16-1">↩</a> <a href="#fr-16-2">↩2</a> <a href="#fr-16-3">↩3</a> <a href="#fr-16-4">↩4</a> <a href="#fr-16-5">↩5</a> <a href="#fr-16-6">↩6</a> <a href="#fr-16-7">↩7</a></p> </li> <li id="fn-14"> <p>A <em>PoS</em> protocol, Proof-of-Stake protocol, is a cryptocurrency consensus mechanism for processing transactions and creating new blocks in a blockchain. <a href="#fr-14-1">↩</a></p> </li> </ol> </section> 2023-03-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 Saitamahttps://github.com/saitama2009 Combocombo@1combo.io Luigiluigi@1combo.io https://wg-eips.ritovision.com/6806/

Add holding time information to ERC-721 tokens

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. It adds an interface that tracks and describes the holding time of a Non-Fungible Token (NFT) by an account.</p> <h2 id="motivation">Motivation</h2> <p>In some use cases, it is valuable to know the duration for which a NFT has been held by an account. This information can be useful for rewarding long-term holders, determining access to exclusive content, or even implementing specific business logic based on holding time. However, the current ERC-721 standard does not have a built-in mechanism to track NFT holding time.</p> <p>This proposal aims to address these limitations by extending the ERC-721 standard to include holding time tracking functionality.</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>Interface</strong></p> <p>The following interface extends the existing ERC-721 standard:</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 class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6806</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getHoldingInfo</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">address</span><span class="z-variable"> holder</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> holdingTime</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>Functions</strong></p> <h3 id="getholdinginfo">getHoldingInfo</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function getHoldingInfo(uint256 tokenId) external view returns (address holder, uint256 holdingTime);</span></span></code></pre> <p>This function returns the current holder of the specified NFT and the length of time (in seconds) the NFT has been held by the current account.</p> <ul> <li><code>tokenId</code>: The unique identifier of the NFT.</li> <li>Returns: A tuple containing the current holder's address and the holding time (in seconds).</li> </ul> <h2 id="rationale">Rationale</h2> <p>The addition of the <code>getHoldingInfo</code> function to an extension of the ERC-721 standard enables developers to implement NFT-based applications that require holding time information. This extension maintains compatibility with existing ERC-721 implementations while offering additional functionality for new use cases.</p> <p>The <code>getHoldingInfo</code> function provides a straightforward method for retrieving the holding time and holder address of an NFT. By using seconds as the unit of time for holding duration, it ensures precision and compatibility with other time-based functions in smart contracts.</p> <p><code>getHoldingInfo</code> returns both <code>holder</code> and <code>holdingTime</code> so that some token owners (as decided by the implementation) can be ignored for the purposes of calculating holding time. For example, a contract may take ownership of an NFT as collateral for a loan. Such a loan contract could be ignored, so the real owner's holding time increases properly.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backwards compatible with the existing ERC-721 standard, as it extends the standard with new functions that do not affect the core functionality.</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"> ^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/access/Ownable.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;./IERC6806.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"> ERC6806</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">Ownable</span><span>, </span><span class="z-entity z-name">IERC6806</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"> address</span><span>)</span><span class="z-storage z-type"> private</span><span> _holder</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"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> _holdStart</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> _holdingTimeWhitelist</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 class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> name_</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"> symbol_</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></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"> firstotTokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> override</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_holdingTimeWhitelist</span><span>[</span><span>from</span><span>]</span><span class="z-keyword"> ||</span><span> _holdingTimeWhitelist</span><span>[</span><span>to</span><span>]</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 class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_holder</span><span>[</span><span>firstotTokenId</span><span>]</span><span class="z-keyword"> !=</span><span> to</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> _holder</span><span>[</span><span>firstotTokenId</span><span>]</span><span class="z-keyword"> =</span><span> to</span><span>;</span></span> <span class="giallo-l"><span> _holdStart</span><span>[</span><span>firstotTokenId</span><span>]</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> }</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"> getHoldingInfo</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"> 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"> holder</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> holdingTime</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>_holder</span><span>[</span><span>tokenId</span><span>]</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp </span><span class="z-keyword">-</span><span> _holdStart</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> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setHoldingTimeWhitelistedAddress</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"> bool</span><span class="z-variable"> ignoreReset</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></span> <span class="giallo-l"><span> _holdingTimeWhitelist</span><span>[</span><span>account</span><span>]</span><span class="z-keyword"> =</span><span> ignoreReset</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> HoldingTimeWhitelistSet</span><span>(</span><span>account</span><span>,</span><span> ignoreReset</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 introduces additional state management for tracking holding times, which may have security implications. Implementers should be cautious of potential vulnerabilities related to holding time manipulation, especially during transfers.</p> <p>When implementing this EIP, developers should be mindful of potential attack vectors, such as reentrancy and front-running attacks, as well as general security best practices for smart contracts. Adequate testing and code review should be performed to ensure the safety and correctness of the implementation.</p> <p>Furthermore, developers should consider the gas costs associated with maintaining and updating holding time information. Optimizations may be necessary to minimize the impact on contract execution costs.</p> <p>It is also important to note that the accuracy of holding time information depends on the accuracy of the underlying blockchain's timestamp. While block timestamps are generally reliable, they can be manipulated by miners to some extent. As a result, holding time data should not be relied upon as a sole source of truth in situations where absolute precision is required.</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-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 qdqdhttps://github.com/qd-qdqdqdqdqdqd@protonmail.com https://wg-eips.ritovision.com/6823/

Approach to enhance precision of off-chain transaction simulations by accessing mapping storage slot in ERC-20/721/1155 contracts.

<h2 id="abstract">Abstract</h2> <p>The aim of this proposal is to enhance the precision of off-chain simulations for transactions that involve contracts complying with the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> standards. To achieve this, a method is proposed for obtaining the reserved storage slot of the mapping responsible to track ownership of compliant tokens. The proposed extension offers a standardized entry point that allows for identifying the reserved storage slot of a mapping in a compatible manner. This not only facilitates capturing state changes more precisely but also enables external tools and services to do so without requiring expertise in the particular implementation details.</p> <h2 id="motivation">Motivation</h2> <p>To understand the rationale behind this proposal, it's important to remember how values and mapping are stored in the storage layout. This procedure is language-agnostic; it can be applied to multiple programming languages beyond Solidity, including Vyper.</p> <p>The storage layout is a way to persistently store data in Ethereum smart contracts. In the EVM, storage is organized as a key-value store, where each key is a 32-byte location, and each value is a 32-byte word. When you define a state variable in a contract, it is assigned to a storage location. The location is determined by the variable's position in the contract's storage structure. The first variable in the contract is assigned to location 0, the second to location 1, and so on. Multiple values less than 32 bytes can be grouped to fit in a single slot if possible.</p> <p>Due to their indeterminate size, mappings utilize a specialized storage arrangement. Instead of storing mappings "in between" state variables, they are allocated to occupy 32 bytes only, and their elements are stored in a distinct storage slot computed through a keccak-256 hash. The location of the value corresponding to a mapping key <code>k</code> is determined by concatenating <code>h(k)</code> and <code>p</code> and performing a keccak-256 hash. The value of <code>p</code> is the position of the mapping in the storage layout, which depends on the order and the nature of the variables initialized before the mapping. It can't be determined in a universal way as you have to know how the implementation of the contract is done.</p> <p>Due to the nature of the mapping type, it is challenging to simulate transactions that involve smart contracts because the storage layout for different contracts is unique to their specific implementation, etched by their variable requirements and the order of their declaration. Since the storage location of a value in a mapping variable depends on this implementation-sensitive storage slot, we cannot guarantee similarity on the off-chain simulation version that an on-chain attempted interaction will result in.</p> <p>This hurdle prevents external platforms and tools from capturing/validating changes made to the contract's state with certainty.</p> <p>That's why transaction simulation relies heavily on events. However, this approach has limitations, and events should only be informative and not relied upon as the single source of truth. The state is and must be the only source of truth. Furthermore, it is impossible to know the shape of the storage deterministically and universally, which prevents us from verifying the source of truth that is storage, forcing us to rely on information emitted from the application layer.</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> <p>The proposal suggests an extension to the ERC-20/ERC-721/ERC-1155 standards that allows retrieving the reserved storage slot for the mapping type in any compliant smart-contract implementation in a deterministic manner. This method eliminates the reliance on events and enhances the precision of the data access from storage. The proposed extension therefore enables accurate off-chain simulations. The outcome is greater transparency and predictability at no extra cost for the caller, and a negigleable increase in the deployment cost of the contract.</p> <p>The proposed extension is a single function that returns the reserved storage slot for the mapping type in any ERC-20/ERC-721/ERC-1155 compliant smart-contract implementation. The function is named <code>getTokenLocationRoot</code> and is declared as follows:</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"> ERC20Extension</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"> getTokenLocationRoot</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> slot</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> slot </span><span class="z-keyword">:=</span><span class="z-keyword"> &lt;</span><span>mapping_name</span><span class="z-keyword">&gt;</span><span>.</span><span>slot</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">abstract</span><span class="z-storage z-type"> contract</span><span class="z-entity z-name"> ERC721Extension</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-storage z-type"> function</span><span class="z-entity z-name"> getTokenLocationRoot</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> slot</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> slot </span><span class="z-keyword">:=</span><span class="z-keyword"> &lt;</span><span>mapping_name</span><span class="z-keyword">&gt;</span><span>.</span><span>slot</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">abstract</span><span class="z-storage z-type"> contract</span><span class="z-entity z-name"> ERC1155Extension</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC1155</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTokenLocationRoot</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> slot</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> slot </span><span class="z-keyword">:=</span><span class="z-keyword"> &lt;</span><span>mapping_name</span><span class="z-keyword">&gt;</span><span>.</span><span>slot</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 these contracts, off-chain callers can use the <code>getTokenLocationRoot()</code> function to find the reserved storage slot for the mapping type. This function returns the reserved storage slot for the mapping type in the contract. This location is used to calculate where all the values of the mapping will be stored. Knowing this value makes it possible to determine precisely where each value of the mapping will be stored, regardless of the contract's implementation. The caller can use this slot to calculate the storage slot for a specific token ID and compare the value to the expected one to verify the action stated by the event. In the case of a ERC-721 mint, the caller can compare the value of the storage slot to the address of the token's owner. In the case of a ERC-20 transfer, the caller can compare the value of the storage slot to the address of the token's new owner. In the case of a ERC-1155 burn, the caller can compare the value of the storage slot to the zero address. The off-chain comparison can be performed with any of the many tools available. In addition, it could perhaps allow storage to be proven atomically by not proving the entire state but only a location -- to track ownership of a specific token, for example.</p> <p>The name of the function is intentionally generic to allow the same implementation for all the different token standards. Once implemented universally, the selector derived from the signature of this function will be a single, universal entry point that can be used to directly read the slots in the storage responsible of the ownership, of any token contract. This will make off-chain simulations significantly more accurate, and the events will be used for informational purposes only.</p> <p>Contract implementers MUST implement the <code>getTokenLocationRoot()</code> function in their contracts. The function MUST return the reserved storage slot for the mapping type in the contract. The function SHOULD be declared as <code>external pure</code>.</p> <h2 id="rationale">Rationale</h2> <p>The idea behind the implementation was to find an elegant and concise way that avoided any breaking changes with the current standard. Moreover, since gas consumption is crucial, it was inconceivable to find an implementation that would cost gas to the final user. In this case, the addition of a function increases the deployment cost of the contract in a minimal way, but its use is totally free for the external actors.</p> <p>The implementation is minimalist in order to be as flexible as possible while being directly compatible with the main programming languages used today to develop smart-contracts for the EVM.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues have been found.</p> <h2 id="reference-implementation">Reference Implementation</h2> <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"> ERC20Extension</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"> getTokenLocationRoot</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> slot</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> slot </span><span class="z-keyword">:=</span><span class="z-keyword"> &lt;</span><span>mapping_name</span><span class="z-keyword">&gt;</span><span>.</span><span>slot</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">abstract</span><span class="z-storage z-type"> contract</span><span class="z-entity z-name"> ERC721Extension</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-storage z-type"> function</span><span class="z-entity z-name"> getTokenLocationRoot</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> slot</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> slot </span><span class="z-keyword">:=</span><span class="z-keyword"> &lt;</span><span>mapping_name</span><span class="z-keyword">&gt;</span><span>.</span><span>slot</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">abstract</span><span class="z-storage z-type"> contract</span><span class="z-entity z-name"> ERC1155Extension</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC1155</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTokenLocationRoot</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> slot</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> slot </span><span class="z-keyword">:=</span><span class="z-keyword"> &lt;</span><span>mapping_name</span><span class="z-keyword">&gt;</span><span>.</span><span>slot</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>No security issues are raised by the implementation of this extension.</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:48:25+00:00 Otniel Nicolahttps://github.com/OT-kthd Bogdan Popahttps://github.com/BogdanKTHD https://wg-eips.ritovision.com/6785/

Provide easy access to information about the `utility` of an NFT via functions and the NFT's metadata

<h2 id="abstract">Abstract</h2> <p>This specification defines standard functions and an extension of the metadata schema that outlines what a token's utility entails and how the utility may be used and/or accessed. This specification is an optional extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>.</p> <h2 id="motivation">Motivation</h2> <p>This specification aims to clarify what the utility associated with an NFT is and how to access this utility. Relying on third-party platforms to obtain information regarding the utility of the NFT that one owns can lead to scams, phishing or other forms of fraud.</p> <p>Currently, utilities that are offered with NFTs are not captured on-chain. We want the utility of an NFT to be part of the metadata of an NFT. The metadata information would include: a) type of utility, b) description of utility, c) frequency and duration of utility, and d) expiration of utility. This will provide transparency as to the utility terms, and greater accountability on the creator to honor these utilities.</p> <p>As the instructions on how to access a given utility may change over time, there should be a historical record of these changes for transparency.</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>Every contract compliant with <a href="https://wg-eips.ritovision.com/6785/">ERC-6785</a> MUST implement the interface defined as follows:</p> <h3 id="contract-interface">Contract Interface</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> @title NFT Utility description</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-keyword"> Note</span><span class="z-comment">: the EIP-165 identifier for this interface is ed231d73</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"> IERC6785</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 utility description URL of an NFT 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 utilityURL of an NFT is </span><span class="z-keyword">changed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The empty string for `utilityUri` indicates that there is no utility associated</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UpdateUtility</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">string</span><span class="z-variable"> utilityUri</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 new utilityUri - remember the date it was set on</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The empty string indicates there is no utility</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"> utilityUri</span><span class="z-comment"> The new utility description of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 4a048176</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setUtilityUri</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"> utilityUri</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 utilityUri 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 empty string for `utilityUri` indicates that there is no utility associated</span></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"> utility uri for this NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 5e470cbc</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> utilityUriOf</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the changes made to utilityUri</span></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"> history of changes to `utilityUri` for this NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> f96090b9</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> utilityHistoryOf</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>[</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> <p>All functions defined as view MAY be implemented as pure or view</p> <p>Function <code>setUtilityUri</code> MAY be implemented as public or external. Also, the ability to set the <code>utilityUri</code> SHOULD be restricted to the one who's offering the utility, whether that's the NFT creator or someone else.</p> <p>The event <code>UpdateUtility</code> MUST be emitted when the <code>setUtilityUri</code> function is called or any other time that the utility of the token is changed, like in batch updates.</p> <p>The method <code>utilityHistoryOf</code> MUST reflect all changes made to the <code>utilityUri</code> of a tokenId, whether that's done through <code>setUtilityUri</code> or by any other means, such as bulk updates</p> <p>The <code>supportsInterface</code> method MUST return true when called with <code>ed231d73</code></p> <p>The original metadata SHOULD conform to the “ERC-6785 Metadata with utilities JSON Schema” which is a compatible extension of the “ERC-721 Metadata JSON Schema” defined in ERC-721.</p> <p>“ERC-6785 Metadata with utilities 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 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">utilities</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> <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">description</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">t&amp;c</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">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></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 what type of utility this is</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">A brief description of the utility</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">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">An array of possible properties describing the utility, defined as key-value pairs</span><span class="z-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 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">expiry</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">number</span><span class="z-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 period of time for the validity of the utility, since the minting of the NFT. Expressed in seconds</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">t&amp;c</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-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><h2 id="rationale">Rationale</h2> <p>Since the <code>utilityUri</code> could contain information that has to be restricted to some level and could be dependent on an off-chain tool for displaying said information, the creator needs the ability to modify it in the event the off-chain tool or platform becomes unavailable or inaccessible.</p> <p>For transparency purposes, having a <code>utilityHistoryOf</code> method will make it clear how the <code>utilityUri</code> has changed over time.</p> <p>For example, if a creator sells an NFT that gives holders a right to a video call with the creator, the metadata for this utility NFT would read as follows:</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">...</span><span class="z-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">...</span><span class="z-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">...</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">utilities</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">Video call</span><span class="z-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">I will enter a private video call with whoever owns the NFT</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sessions</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 2</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">duration</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 30</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">time_unit</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">minutes</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">expiry</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1.577e+7</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">t&amp;c</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://....</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 order to get access to the details needed to enter the video call, the owner would access the URI returned by the <code>getUtilityUri</code> method for the NFT that they own. Additionally, access to the details could be conditioned by the authentication with the wallet that owns the NFT.</p> <p>The current status of the utility would also be included in the URI (eg: how many sessions are still available, etc.)</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with current ERC-721 standard. There are no other standards that define similar methods for NFTs and the method names are not used by other ERC-721 related standards.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases are available <a href="https://wg-eips.ritovision.com/6785/./assets/test/ERC6785.test.js">here</a></p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation can be found <a href="https://wg-eips.ritovision.com/6785/./assets/contracts/ERC6785.sol">here</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-1.0</a>.</p> 2023-03-27T00:00:00+00:00 2026-02-11T14:48:25+00:00 Otniel Nicolahttps://github.com/OT-kthd Bogdan Popahttps://github.com/BogdanKTHD https://wg-eips.ritovision.com/6786/

A registry used for paying royalties for any NFT with information about the creator

<h2 id="abstract">Abstract</h2> <p>This standard allows anyone to pay royalties for a certain NFT and also to keep track of the royalties amount paid. It will cumulate the value each time a payment is executed through it and make the information public.</p> <h2 id="motivation">Motivation</h2> <p>There are many marketplaces which do not enforce any royalty payment to the NFT creator every time the NFT is sold or re-sold and/or providing a way for doing it. There are some marketplaces which use specific system of royalties, however that system is applicable for the NFTs creates on their platform.</p> <p>In this context, there is a need of a way for paying royalties, as it is a strong incentive for creators to keep contributing to the NFTs ecosystem.</p> <p>Additionally, this standard will provide a way of computing the amount of royalties paid to a creator for a certain NFT. This could be useful in the context of categorising NFTs in terms of royalties. The term “debt“ is used because the standard aims to provide a way of knowing if there are any royalties left unpaid for the NFTs trades that took place in a marketplace that does not support them and, in that case, expose a way of paying them.</p> <p>With a lot of places made for trading NFTs dropping down the royalty payment or having a centralised approach, we want to provide a way for anyone to pay royalties to the creators.</p> <p>Not only the owner of it, but anyone could pay royalties for a certain NFT. This could be a way of supporting a creator for his work.</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>Every contract compliant with <a href="https://wg-eips.ritovision.com/6786/">ERC-6786</a> MUST implement the interface defined as follows:</p> <h3 id="contract-interface">Contract Interface</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> @title Royalty Debt Registry</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 0x253b27b0</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"> IERC6786</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Logged when royalties were paid for a NFT</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 royalties are paid for the NFT with address tokenAddress and id tokenId</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RoyaltiesPaid</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenAddress</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"> 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"> @notice</span><span class="z-comment"> sends msg.value to the creator 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"> Reverts if there are no on-chain informations about the 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"> tokenAddress</span><span class="z-comment"> The address of NFT 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"> tokenId</span><span class="z-comment"> The NFT id</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> payRoyalties</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 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"> Get the amount of royalties which was paid for 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"> </span></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"> The address of NFT 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"> tokenId</span><span class="z-comment"> The NFT 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"> The</span><span class="z-comment"> amount of royalties paid for the NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getPaidRoyalties</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 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>All functions defined as view MAY be implemented as pure or view</p> <p>Function <code>payRoyalties</code> MAY be implemented as public or external</p> <p>The event <code>RoyaltiesPaid</code> MUST be emitted when the payRoyalties function is called</p> <p>The <code>supportsInterface</code> function MUST return true when called with <code>0x253b27b0</code></p> <h2 id="rationale">Rationale</h2> <p>The payment can be made in native coins, so it is easy to aggregate the amount of paid royalties. We want this information to be public, so anyone could tell if a creator received royalties in case of under the table trading or in case of marketplaces which don’t support royalties.</p> <p>The function used for payment can be called by anyone (not only the NFTs owner) to support the creator at any time. There is a way of seeing the amount of paid royalties in any token, also available for anyone.</p> <p>For fetching creator on-chain data we will use <a href="https://wg-eips.ritovision.com/2981/">ERC-2981</a>, but any other on-chain method of getting the creator address is accepted.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC is not introducing any backward incompatibilities.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests are included in <a href="https://wg-eips.ritovision.com/6786/./assets/test/ERC6786.test.js"><code>ERC6786.test.js</code></a>.</p> <p>To run them in terminal, you can use the following commands:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cd ../assets/eip-6786</span></span> <span class="giallo-l"><span>npm install</span></span> <span class="giallo-l"><span>npx hardhat test</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/6786/./assets/contracts/ERC6786.sol"><code>ERC6786.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> 2023-03-27T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jessicahttps://github.com/qizheng09 Royhttps://github.com/royshang Junhttps://github.com/SniperUsopp https://wg-eips.ritovision.com/6787/

An order book-based DEX Interface that ensures the asset security of both users and the exchange

<h2 id="abstract">Abstract</h2> <p>The Order Book DEX Standard is a proposed set of interface specifications that define a decentralized exchange (DEX) protocol for trading assets using order books. This standard provides a set of functions that allow users to deposit, withdraw, and trade assets on a decentralized exchange. Additionally, it proposes a novel two-phase withdrawal scheme to ensure the asset security of both users and the exchange, addressing users' trust issues with the exchange.</p> <h2 id="motivation">Motivation</h2> <p>Decentralized exchanges (DEXs) have become increasingly popular in recent years due to their ability to provide users with greater control over their assets and reduce reliance on centralized intermediaries. However, many existing DEX protocols suffer from issues such as low liquidity and inefficient price discovery. Order book-based DEXs based Layer2 have emerged as a popular alternative, but there is currently no standardized interface for implementing such exchanges.</p> <p>The Order Book DEX Standard aims to provide developers with a common interface for building interoperable order book-based DEXs that can benefit from network effects. By establishing a standard set of functions for depositing, withdrawing, and forced withdrawals, the Order Book DEX Standard can fully ensure the security of user assets. At the same time, the two-phase forced withdrawal mechanism can also prevent malicious withdrawals from users targeting the exchange.</p> <p>The two phase commit protocol is an important distributed consistency protocol, aiming to ensure data security and consistency in distributed systems. In the Layer2 order book DEX system, to enhance user experience and ensure financial security, we adopt a 1:1 reserve strategy, combined with a decentralized clearing and settlement interface, and a forced withdrawal function to fully guarantee users' funds.</p> <p>However, such design also faces potential risks. When users engage in perpetual contract transactions, they may incur losses. In this situation, malicious users might exploit the forced withdrawal function to evade losses. To prevent this kind of attack, we propose a two-phase forced withdrawal mechanism.</p> <p>By introducing the two phase forced withdrawal function, we can protect users' financial security while ensuring the security of the exchange's assets. In the first phase, the system will conduct a preliminary review of the user's withdrawal request to confirm the user's account status. In the second phase, after the forced withdrawal inspection period, users can directly submit the forced withdrawal request to complete the forced withdrawal process. In this way, we can not only prevent users from exploiting the forced withdrawal function to evade losses but also ensure the asset security for both the exchange and the users.</p> <p>In conclusion, by adopting the two phase commit protocol and the two phase forced withdrawal function, we can effectively guard against malicious behaviors and ensure data consistency and security in distributed systems while ensuring user experience and financial security.</p> <h2 id="specification">Specification</h2> <h3 id="interfaces">Interfaces</h3> <p>The Order Book DEX Standard defines the following Interfaces:</p> <h4 id="deposit"><code>deposit</code></h4> <p><code>function deposit(address token, uint256 amount) external;</code></p> <p>The <strong>deposit</strong> function allows a user to deposit a specified amount of a particular token to the exchange. The <em>token</em> parameter specifies the address of the token contract, and the <em>amount</em> parameter specifies the amount of the token to be deposited.</p> <h4 id="withdraw"><code>withdraw</code></h4> <p><code>function withdraw(address token, uint256 amount) external;</code></p> <p>The <strong>withdraw</strong> function allows a user to withdraw a specified amount of a particular token from the exchange. The <em>token</em> parameter specifies the address of the token contract, and the <em>amount</em> parameter specifies the amount of the token to be withdrawn.</p> <h4 id="prepareforcewithdraw"><code>prepareForceWithdraw</code></h4> <p><code>function prepareForceWithdraw(address token, uint256 amount) external returns (uint256 requestID);</code></p> <p>The assets deposited by users will be stored in the exchange contract's account, and the exchange can achieve real-time 1:1 reserve proof. The <strong>prepareForceWithdraw</strong> function is used for users to initiate a forced withdrawal of a certain amount of a specified token. This function indicates that the user wants to perform a forced withdrawal and can submit the withdrawal after the default timeout period. Within the timeout period, the exchange needs to confirm that the user's order status meets the expected criteria, and forcibly cancel the user's order and settle the trade to avoid malicious attacks by the user. This function takes the following parameters:</p> <ol> <li><em>token</em>: the address of the token to be withdrawn</li> <li><em>amount</em>: the amount of the token to be withdrawn</li> </ol> <p>Since an account may initiate multiple two phase forced withdrawals in parallel, each forced withdrawal needs to return a unique <em>requestID</em>. The function returns a unique <em>requestID</em> that can be used to submit the forced withdrawal using the commitForceWithdraw function.</p> <h4 id="commitforcewithdraw"><code>commitForceWithdraw</code></h4> <p><code>function commitForceWithdraw(uint256 requestID) external;</code></p> <ol> <li><em>requestID</em>: the request ID of the two phase Withdraw</li> </ol> <p>The <strong>commitForceWithdraw</strong> function is used to execute a forced withdrawal operation after the conditions are met. The function takes a <em>requestID</em> parameter, which specifies the ID of the forced withdrawal request to be executed. The request must have been previously initiated using the prepareForceWithdraw function.</p> <h3 id="events">Events</h3> <h4 id="prepareforcewithdraw-1"><code>PrepareForceWithdraw</code></h4> <p>MUST trigger when user successful call to PrepareForceWithdraw.</p> <p><code>event PrepareForceWithdraw(address indexed user, address indexed tokenAddress, uint256 amount);</code></p> <h2 id="rationale">Rationale</h2> <p>The flow charts for two-phase withdrawal are shown below:</p> <p><img src="https://wg-eips.ritovision.com/6787/./assets/image1.png" alt="" /></p> <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> <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-25T00: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/6780/

SELFDESTRUCT will recover all funds to the target but not delete the account, except when called in the same transaction as creation

<h2 id="abstract">Abstract</h2> <p>This EIP changes the functionality of the <code>SELFDESTRUCT</code> opcode. The new functionality will be only to send all Ether in the account to the target, except that the current behaviour is preserved when <code>SELFDESTRUCT</code> is called in the same transaction a contract was created.</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. Applications that only use <code>SELFDESTRUCT</code> in the same transaction as they created a contract will also continue to work without any changes.</p> <h2 id="specification">Specification</h2> <p>The behaviour of <code>SELFDESTRUCT</code> is changed in the following way:</p> <ol> <li> <p>When <code>SELFDESTRUCT</code> is executed in a transaction that is not the same as the contract calling <code>SELFDESTRUCT</code> was created:</p> <ul> <li>The current execution frame halts.</li> <li><code>SELFDESTRUCT</code> does not delete any data (including storage keys, code, or the account itself).</li> <li><code>SELFDESTRUCT</code> transfers the entire account balance to the target.</li> <li>Note that if the target is the same as the contract calling <code>SELFDESTRUCT</code> there is no net change in balances. Unlike the prior specification, Ether will not be burnt in this case.</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> </li> <li> <p>When <code>SELFDESTRUCT</code> is executed in the same transaction as the contract was created:</p> <ul> <li><code>SELFDESTRUCT</code> continues to behave as it did prior to this EIP, this includes the following actions <ul> <li>The current execution frame halts.</li> <li><code>SELFDESTRUCT</code> deletes data as previously specified.</li> <li><code>SELFDESTRUCT</code> transfers the entire account balance to the target</li> <li>The account balance of the contact calling <code>SELFDESTRUCT</code> is set to <code>0</code>.</li> </ul> </li> <li>Note that if the target is the same as the contract calling <code>SELFDESTRUCT</code> that Ether will be burnt.</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> </li> </ol> <p>A contract is considered created at the beginning of a create transaction or when a CREATE series operation begins execution (CREATE, CREATE2, and other operations that deploy contracts in the future). If a balance exists at the contract's new address it is still considered to be a contract creation.</p> <p>The <code>SELFDESTRUCT</code> opcode remains deprecated as specified in <a href="https://wg-eips.ritovision.com/6049/">EIP-6049</a>. Any use in newly deployed contracts is strongly discouraged even if this new behaviour is taken into account, and future changes to the EVM might further reduce the functionality of the opcode.</p> <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. This EIP implements a behavior that will attempt to leave some common uses of <code>SELFDESTRUCT</code> working, while reducing the complexity of the change on EVM implementations that would come from contract versioning.</p> <p>Handling the account creation and contract creation as two distinct and possibly separate events is needed for use cases such as counterfactual accounts. By allowing the <code>SELFDESTRUCT</code> to delete the account at contract creation time it will not result in stubs of counterfactually instantiated contracts that never had any on-chain state other than a balance prior to the contract creation. These accounts would never have any storage and thus the trie updates to delete the account would be limited to the account node, which is the same impact a regular transfer of ether would have.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a hard fork, since it modifies consensus rules.</p> <p>Contracts that depended on re-deploying contracts at the same address using <code>CREATE2</code> (after a <code>SELFDESTRUCT</code>) will no longer function properly if the created contract does not call <code>SELFDESTRUCT</code> within the same transaction.</p> <p>Previously it was possible to burn ether by calling <code>SELFDESTRUCT</code> targeting the executing contract as the beneficiary. If the contract existed prior to the transaction the ether will not be burned. If the contract was newly created in the transaction the ether will be burned, as before.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases for this EIP can be found in the Execution Spec Tests suite <a rel="external" href="https://github.com/ethereum/execution-spec-tests/tree/1983444bbe1a471886ef7c0e82253ffe2a4053e1/tests/cancun/eip6780_selfdestruct"><code>eip6780_selfdestruct</code></a>.</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>Where <code>CREATE2</code> is used to redeploy a contract in the same place in order to make a contract upgradable. This is not supported anymore and <a href="https://wg-eips.ritovision.com/2535/">ERC-2535</a> or other types of proxy contracts should be used instead.</p> </li> <li> <p>Where a contract depended on burning Ether via a <code>SELFDESTRUCT</code> with the contract as beneficiary, in a contract not created within the same transaction.</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> 2023-03-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Kelvin Fichterhttps://github.com/smartcontracts Andreas Freundhttps://github.com/Therecanbeonlyone1969 Pavel Sinelnikovhttps://github.com/psinelnikov https://wg-eips.ritovision.com/6734/

Token List that ensures the correct identification of tokens from different Layer 1, Layer 2, or Sidechains.

<h2 id="abstract">Abstract</h2> <p>The document describes a JSON token list that ensures that two or more Layer 1, Layer 2, or Sidechains can identify tokens from a different Layer 1, Layer 2, or Sidechain.</p> <h2 id="motivation">Motivation</h2> <p>This particular work by the L2 WG of the EEA Communities Projects managed by OASIS, an open-source initiative, is motivated by a significant challenge around the definition and listing of tokens on Layer 1 (L1), Layer 2 (L2), and Sidechain systems. Note that for simplicity, this document we will collectively refer to L1, L2 and Sidechain systems as chains below since the challenge described below is valid across all such systems:</p> <ul> <li>Consensus on the "canonical" token on chain B that corresponds to some token on chain A. When one wants to bridge token X from chain A to chain B, one must create some new representation of the token on chain B. It is worth noting that this problem is not limited to L2s -- every chain connected via bridges must deal with the same issue.</li> </ul> <p>Related to the above challenge is the standardization around lists of bridges and their routes across different chains. This will be addressed in a separate document.</p> <p>Note that both of these issues are fundamental problems for the current multi-chain world.</p> <p>Therefore, the goal of this document is to help token users to operationalize and disambiguate the usage of a token in their systems.</p> <p>For lists of canonical tokens, L2s currently maintain their own customized versions of the Uniswap token list. For example, Arbitrum maintains a token list with various custom extensions. Optimism also maintains a custom token list, but with different extensions. It should be noted that both of these custom extensions refer to the bridge that these tokens can be carried through. However, these are not the only bridges that the tokens can be carried through, which means that bridges and token lists should be separated. Also note that currently, both Optimism and Arbitrum base "canonicity" on the token name + symbol pair.</p> <p>An example of an Arbitrum token entry is given below:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span>logoURI: &quot;https://assets.coingecko.com/coins/images/13469/thumb/1inch-token.png?1608803028&quot;,</span></span> <span class="giallo-l"><span>chainId: 42161,</span></span> <span class="giallo-l"><span>address: &quot;0x6314C31A7a1652cE482cffe247E9CB7c3f4BB9aF&quot;,</span></span> <span class="giallo-l"><span>name: &quot;1INCH Token&quot;,</span></span> <span class="giallo-l"><span>symbol: &quot;1INCH&quot;,</span></span> <span class="giallo-l"><span>decimals: 18,</span></span> <span class="giallo-l"><span>extensions: {</span></span> <span class="giallo-l"><span> bridgeInfo: {</span></span> <span class="giallo-l"><span> 1: {</span></span> <span class="giallo-l"><span> tokenAddress: &quot;0x111111111117dc0aa78b770fa6a738034120c302&quot;,</span></span> <span class="giallo-l"><span> originBridgeAddress: &quot;0x09e9222e96e7b4ae2a407b98d48e330053351eee&quot;,</span></span> <span class="giallo-l"><span> destBridgeAddress: &quot;0xa3A7B6F88361F48403514059F1F16C8E78d60EeC&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 standard will build upon the current framework and augment it with concepts from <a rel="external" href="https://www.w3.org/TR/2022/REC-did-core-20220719/">Decentralized Identifiers (DIDs)</a> based on the JSON linked data model <a rel="external" href="https://www.w3.org/TR/2020/REC-json-ld11-20200716/">JSON-LD</a> such as resolvable unique resource identifiers (URIs) and JSON-LD schemas which enable easier schema verification using existing tools.</p> <p>Note that a standard for defining tokens is beyond the scope of this document.</p> <h2 id="specification">Specification</h2> <h3 id="keywords">Keywords:</h3> <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 [<a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC2119</a>] when, and only when, they appear in all capitals, as shown here.</p> <h3 id="typographical-convention-requirement-ids">Typographical Convention: Requirement Ids</h3> <p>A requirement is uniquely identified by a unique ID composed of its requirement level followed by a requirement number, as per convention <strong>[RequirementLevelRequirementNumber]</strong>. There are four requirement levels that are coded in requirement ids as per below convention:</p> <p><strong>[R]</strong> - The requirement level for requirements which IDs start with the letter <em>R</em> is to be interpreted as <strong>MUST</strong> as described in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC2119</a>.<br /> <strong>[D]</strong> - The requirement level for requirements which IDs start with the letter <em>D</em> is to be interpreted as <strong>SHOULD</strong> as described in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC2119</a>.<br /> <strong>[O]</strong> - The requirement level for requirements which IDs start with the letter <em>O</em> is to be interpreted as <strong>MAY</strong> as described in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC2119</a>.</p> <p>Note that requirements are uniquely numbered in ascending order within each requirement level.</p> <p>Example : It should be read that [R1] is an absolute requirement of the specification whereas [D1] is a recommendation and [O1] is truly optional.</p> <p><a name="r1"> <strong>[R1]</strong> </a> The following data elements MUST be present in a canonical token list:</p> <ul> <li>type</li> <li>tokenListId</li> <li>name</li> <li>createdAt</li> <li>updatedAt</li> <li>versions</li> <li>tokens</li> </ul> <p>Note, that the detailed definition of the data elements in <a href="https://wg-eips.ritovision.com/6734/#r1">[R1]</a> along with descriptions and examples are given in the schema itself below.</p> <p><a href="https://wg-eips.ritovision.com/6734/#r1">[R1]</a> testability: See suggested test fixtures for the data schema below.</p> <p><a name="r2"> <strong>[R2]</strong> </a> The tokens data element is a composite which MUST minimally contain the following data elements:</p> <ul> <li>chainId</li> <li>chainURI</li> <li>tokenId</li> <li>tokenType</li> <li>address</li> <li>name</li> <li>symbol</li> <li>decimals</li> <li>createdAt</li> <li>updatedAt</li> </ul> <p>Note, that the detailed definition of the data elements in <a href="https://wg-eips.ritovision.com/6734/#r2">[R2]</a> along with descriptions and examples are given in the schema itself below.</p> <p><a href="https://wg-eips.ritovision.com/6734/#r2">[R2]</a> testability: See suggested test fixtures for this documents' data schema below.</p> <p><a name="d1"> <strong>[D1]</strong> </a> All other data elements of the schema SHOULD be included in a representation of a canonical token list.</p> <p><a href="https://wg-eips.ritovision.com/6734/#d1">[D1]</a> testability: See suggested test fixtures for this documents' data schema below.</p> <p><a name="cr1d1"> <strong>[CR1]&gt;[D1]</strong> </a> If the extension data elements is used, the following data elements MUST be present in the schema representation:</p> <ul> <li>rootChainId</li> <li>rootChainURI</li> <li>rootAddress</li> </ul> <p>Note, that the detailed definition of the data elements in <a href="https://wg-eips.ritovision.com/6734/#d1">[D1]</a> and <a href="https://wg-eips.ritovision.com/6734/#cr1d1">[CR1]&gt;[D1]</a> along with descriptions and examples are given in the schema itself below.</p> <p><a href="https://wg-eips.ritovision.com/6734/#cr1d1">[CR1]&gt;[D1]</a> testability: See suggested test fixtures for this documents' data schema below.</p> <p><a name="r3"> <strong>[R3]</strong> </a> All properties in the schema identified in the description to be a Universal Resource Identifier (URI) MUST follow in their semantics <a rel="external" href="https://www.rfc-editor.org/rfc/rfc3986">RFC 3986</a>.</p> <p><a href="https://wg-eips.ritovision.com/6734/#r3">[R3]</a> testability: All requirements for <a rel="external" href="https://www.rfc-editor.org/rfc/rfc3986">RFC 3986</a> are testable.</p> <p><a name="r4"> <strong>[R4]</strong> </a> The chainId property utilized MUST allow for the requirements of the <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> standard to be met.</p> <p>Namely, transaction replay protection on the network that is identified by the chainId property value. Note, that for replay protection to be guaranteed, the chainId should be unique. Ensuring a unique chainId is beyond the scope of this document.</p> <p><a href="https://wg-eips.ritovision.com/6734/#r4">[R4]</a> testability: EIP-155 requires that a transaction hash is derived from the keccak256 hash of the following nine RLP encoded elements <code>(nonce, gasprice, startgas, to, value, data, chainid, 0, 0)</code> which can be tested easily with existing cryptographic libraries. EIP-155 further requires that the <code>v</code> value of the secp256k1 signature must be set to <code>{0,1} + CHAIN_ID * 2 + 35</code> where <code>{0,1}</code> is the parity of the <code>y</code> value of the curve point for which the signature <code>r</code>-value is the <code>x</code>-value in the secp256k1 signing process. This requirement is testable with available open-source secp256k1 digital signature suites. Therefore, <a href="https://wg-eips.ritovision.com/6734/#r4">[R4]</a> is testable.</p> <p><a name="o1"> <strong>[O1]</strong> </a> The <code>humanReadableTokenSymbol</code> property MAY be used.</p> <p><a href="https://wg-eips.ritovision.com/6734/#o1">[O1]</a> testability: A data property is always implementable in a schema.</p> <p><a name="cr2o1"> <strong>[CR2]&gt;[O1]</strong> </a> The <code>humanReadableTokenSymbol</code> property MUST be constructed as the hyphenated concatenation of first the <code>tokenSymbol</code> and then the <code>chainId</code>.</p> <p>An example would be:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&quot;tokenSymbol&quot; = ETH;</span></span> <span class="giallo-l"><span>&quot;chainId&quot; = 1;</span></span> <span class="giallo-l"><span>&quot;humanReadableTokenSymbol&quot; = ETH-1;</span></span></code></pre> <p><a href="https://wg-eips.ritovision.com/6734/#cr2o1">[CR2]&gt;[O1]</a> testability: <code>humanReadableTokenSymbol</code> can be parsed and split based on existing open source packages and the result compared to the <code>tokenSymbol</code> and <code>chainId</code> used in the data schema.</p> <p>The schema for a canonical token list is given below as follows and can be utilized as a JSON-LD schema if a JSON-LD context file is utilized (see <a rel="external" href="https://www.w3.org/TR/2022/REC-did-core-20220719/">[W3C-DID]</a> for a concrete example in the context of a standard):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> &quot;$id&quot;: &quot;https://github.com/eea-oasis/l2/schemas/CanonicalTokenList.json&quot;,</span></span> <span class="giallo-l"><span> &quot;$schema&quot;: &quot;https://json-schema.org/draft-07/schema#&quot;,</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;CanonicalTokenList\&quot;, \&quot;@id\&quot;: \&quot;https://github.com/eea-oasis/l2#CanonicalTokenList\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;CanonicalTokenList&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Canonical Token List&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;object&quot;,</span></span> <span class="giallo-l"><span> &quot;required&quot;: [</span></span> <span class="giallo-l"><span> &quot;type&quot;,</span></span> <span class="giallo-l"><span> &quot;tokenListId&quot;,</span></span> <span class="giallo-l"><span> &quot;name&quot;,</span></span> <span class="giallo-l"><span> &quot;createdAt&quot;,</span></span> <span class="giallo-l"><span> &quot;updatedAt&quot;,</span></span> <span class="giallo-l"><span> &quot;versions&quot;,</span></span> <span class="giallo-l"><span> &quot;tokens&quot;</span></span> <span class="giallo-l"><span> ],</span></span> <span class="giallo-l"><span> &quot;properties&quot;: {</span></span> <span class="giallo-l"><span> &quot;@context&quot;: {</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;array&quot;</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;type&quot;: {</span></span> <span class="giallo-l"><span> &quot;oneOf&quot;: [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;array&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ],</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;CanonicalTokenList&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;tokenListId&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;tokenListId\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/identifier\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;tokenListId&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;A resolvable URI to the publicly accessible place where this list can be found following the RFC 3986 standard.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;https://ipfs.io/ipns/k51qzi5uqu5dkkciu33khkzbcmxtyhn376i1e83tya8kuy7z9euedzyr5nhoew&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;name&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;name\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/name\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;name&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Token List name&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;Aggregate Canonical Token List&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;logoURI&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;logoURI\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/identifier\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;logoURI&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;URI or URL of the token list logo following the RFC 3986 standard&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;https://ipfs.io/ipns/k51qzi5uqu5dh5kbbff1ucw3ksphpy3vxx4en4dbtfh90pvw4mzd8nfm5r5fnl&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;keywords&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;keywords\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/DefinedTerm\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;keywords&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;List of key words for the token list&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;array&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [Aggregate Token List]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;createdAt&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;createdAt\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/datePublished\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;createdAt&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Date and time token list was created&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;2022-05-08&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;updatedAt&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;updatedAt\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/dateModified\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;updatedAt&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Date and time token list was updated&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;2022-05-09&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;versions&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;versions\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/version\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;versions&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Versions of the canonical token list&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;array&quot;,</span></span> <span class="giallo-l"><span> &quot;items&quot;: {</span></span> <span class="giallo-l"><span> &quot;type&quot;:&quot;object&quot;,</span></span> <span class="giallo-l"><span> &quot;required&quot;:[</span></span> <span class="giallo-l"><span> &quot;major&quot;,</span></span> <span class="giallo-l"><span> &quot;minor&quot;,</span></span> <span class="giallo-l"><span> &quot;patch&quot;</span></span> <span class="giallo-l"><span> ],</span></span> <span class="giallo-l"><span> &quot;properties&quot;: {</span></span> <span class="giallo-l"><span> &quot;major&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;major\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/Number\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;major&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Major Version Number of the Token List&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;integer&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [1]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;minor&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;minor\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/Number\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;minor&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Minor Version Number of the Token List&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;integer&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [1]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;patch&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;patch\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/Number\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;patch&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Patch Number of the Token List&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;integer&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [1]</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> &quot;tokens&quot;: {</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;Listed Token Entry&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Listed Token Entry&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;array&quot;,</span></span> <span class="giallo-l"><span> &quot;items&quot;: {</span></span> <span class="giallo-l"><span> &quot;type&quot;:&quot;object&quot;,</span></span> <span class="giallo-l"><span> &quot;required&quot;: [</span></span> <span class="giallo-l"><span> &quot;chainId&quot;,</span></span> <span class="giallo-l"><span> &quot;chainURI&quot;,</span></span> <span class="giallo-l"><span> &quot;tokenId&quot;,</span></span> <span class="giallo-l"><span> &quot;tokenType&quot;,</span></span> <span class="giallo-l"><span> &quot;address&quot;,</span></span> <span class="giallo-l"><span> &quot;name&quot;,</span></span> <span class="giallo-l"><span> &quot;symbol&quot;,</span></span> <span class="giallo-l"><span> &quot;decimals&quot;,</span></span> <span class="giallo-l"><span> &quot;createdAt&quot;,</span></span> <span class="giallo-l"><span> &quot;updatedAt&quot;</span></span> <span class="giallo-l"><span> ],</span></span> <span class="giallo-l"><span> &quot;properties&quot;: {</span></span> <span class="giallo-l"><span> &quot;chainId&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;chainId\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/identifier\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;chainId&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;The typically used number identifier for the chain on which the token was issued.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;number&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [137]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;chainURI&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;chainURI\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/identifier\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;chainURI&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;A resolvable URI to the genesis block of the chain on which the token was issued following the RFC 3986 standard.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;https://polygonscan.com/block/0&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;genesisBlockHash&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;genesisBlockHash\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/sha256\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;genesisBlockHash&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;The hash of the genesis block of the chain on which the token was issued.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;0xa9c28ce2141b56c474f1dc504bee9b01eb1bd7d1a507580d5519d4437a97de1b&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;tokenIssuerId&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;tokenIssuerId\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/identifier\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;tokenIssuerId&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;A resolvable URI identifying the token issuer following the RFC 3986 standard.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;https://polygonscan.com/address/0xa9c28ce2141b56c474f1dc504bee9b01eb1bd7d1a507580d5519d4437a97de1b&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;tokenIssuerName&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;tokenIssuerName\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/name\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;tokenIssuerName&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;The name oof the token issuer.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;Matic&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;tokenId&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;tokenId\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/identifier\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;tokenId&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;A resolvable URI of the token following the RFC 3986 standard to for example the deployment transaction of the token, or a DID identifying the token and its issuer.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;example&quot;: [&quot;https://polygonscan.com/address/0x0000000000000000000000000000000000001010&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;tokenType&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;tokenType\&quot;, \&quot;@id\&quot;: \https://schema.org/StructuredValue\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;tokenType&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Describes the type of token.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;array&quot;</span></span> <span class="giallo-l"><span> &quot;examples&quot;[[&quot;fungible&quot;,&quot;transferable&quot;]]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;tokenDesc&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;tokenDesc\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/description\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;tokenDesc&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Brief description of the token and its functionality.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;Protocol Token for the Matic Network&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;standard&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;standard\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/citation\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;standard&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;A resolvable URI to the description of the token standard.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;https://github.com/ethereum/EIPs/blob/master/EIPS/./00020.md&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;address&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;address\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/identifier\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;address&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Address of the token smart contract.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;0x0000000000000000000000000000000000001010&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;addressType&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;address\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/Intangible\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;addressType&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;AddressType of the token smart contract.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;MaticNameSpace&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;addressAlg&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;addressAlg\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/algorithm\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;addressAlg&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Algorithm used to create the address e.g. CREATE2 or the standard ethereum address construction which is the last 40 characters/20 bytes of the Keccak-256 hash of a secp256k1 public key.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;CREATE2&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;name&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;name\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/name\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;name&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Token name.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;Matic&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;symbol&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;symbol\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/currency\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;symbol&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Token symbol e.g. ETH.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;MATIC&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;humanReadableTokenSymbol&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;humanReadableTokenSymbol\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/currency\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;humanReadableTokenSymbol&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;A Token symbol e.g. ETH, concatenated with the `chainId` the token was issued on or bridged to, e.g. ETH-1&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;MATIC-137&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;decimals&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;decimals\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/Number\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;decimals&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Allowed number of decimals for the listed token. This property may be named differently by token standards e.g. granularity for ERC-777&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;integer&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [18]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;logoURI&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;logoURI\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/identifier\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;logoURI&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;URI or URL of the token logo following the RFC 3986 standard.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;https://polygonscan.com/token/images/matic_32.png&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;createdAt&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;createdAt\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/datePublished\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;createdAt&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Date and time token was created&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;2020-05-31&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;updatedAt&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;updatedAt\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/dateModified\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;updatedAt&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Date and time token was updated&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;2020-05-31&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;extensions&quot;: {</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;extensions&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Extension to the token list entry to specify an origin chain if the token entry refers to another chain other than the origin chain of the token&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;array&quot;,</span></span> <span class="giallo-l"><span> &quot;items&quot;: {</span></span> <span class="giallo-l"><span> &quot;type&quot;:&quot;object&quot;,</span></span> <span class="giallo-l"><span> &quot;required&quot;: [</span></span> <span class="giallo-l"><span> &quot;rootChainId&quot;,</span></span> <span class="giallo-l"><span> &quot;rootChainURI&quot;,</span></span> <span class="giallo-l"><span> &quot;rootAddress&quot;,</span></span> <span class="giallo-l"><span> ],</span></span> <span class="giallo-l"><span> &quot;properties&quot;: {</span></span> <span class="giallo-l"><span> &quot;rootChainId&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;rootChainId\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/identifier\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;rootChainId&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;The typically used number identifier for the root chain on which the token was originally issued.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;number&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [137]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;rootChainURI&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;rootChainURI\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/identifier\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;rootChainURI&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;A resolvable URI to the genesis block of the root chain on which the token was originally issued following the RFC 3986 standard.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;https://polygonscan.com/block/0&quot;]</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;rootAddress&quot;: {</span></span> <span class="giallo-l"><span> &quot;$comment&quot;: &quot;{\&quot;term\&quot;: \&quot;rootAddress\&quot;, \&quot;@id\&quot;: \&quot;https://schema.org/identifier\&quot;}&quot;,</span></span> <span class="giallo-l"><span> &quot;title&quot;: &quot;rootAddress&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;Root address of the token smart contract.&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;examples&quot;: [&quot;0x0000000000000000000000000000000000001010&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> &quot;additionalProperties&quot;: false,</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Data Schema Testability: As the above data schema follows a JSON/JSON-LD schema format, and since such formats are known to be testable for schema conformance (see for example the W3C CCG Traceability Work Item), the above data schema is testable.</p> <h3 id="conformance">Conformance</h3> <p>This section describes the conformance clauses and tests required to achieve an implementation that is provably conformant with the requirements in this document.</p> <h4 id="conformance-targets">Conformance Targets</h4> <p>This document does not yet define a standardized set of test-fixtures with test inputs for all MUST, SHOULD, and MAY requirements with conditional MUST or SHOULD requirements.</p> <p>A standardized set of test-fixtures with test inputs for all MUST, SHOULD, and MAY requirements with conditional MUST or SHOULD requirements is intended to be published with the next version of the standard.</p> <h4 id="conformance-levels">Conformance Levels</h4> <p>This section specifies the conformance levels of this standard. The conformance levels offer implementers several levels of conformance. These can be used to establish competitive differentiation.</p> <p>This document defines the conformance levels of a canonical token list as follows:</p> <ul> <li><strong>Level 1:</strong> All MUST requirements are fulfilled by a specific implementation as proven by a test report that proves in an easily understandable manner the implementation's conformance with each requirement based on implementation-specific test-fixtures with implementation-specific test-fixture inputs.</li> <li><strong>Level 2:</strong> All MUST and SHOULD requirements are fulfilled by a specific implementation as proven by a test report that proves in an easily understandable manner the implementation's conformance with each requirement based on implementation-specific test-fixtures with implementation-specific test-fixture inputs.</li> <li><strong>Level 3:</strong> All MUST, SHOULD, and MAY requirements with conditional MUST or SHOULD requirements are fulfilled by a specific implementation as proven by a test report that proves in an easily understandable manner the implementation's conformance with each requirement based on implementation-specific test-fixtures with implementation-specific test-fixture inputs.</li> </ul> <p><a name="d2"> <strong>[D2]</strong> </a> A claim that a canonical token list implementation conforms to this specification SHOULD describe a testing procedure carried out for each requirement to which conformance is claimed, that justifies the claim with respect to that requirement.</p> <p><a href="https://wg-eips.ritovision.com/6734/#d2">[D2]</a> testability: Since each of the non-conformance-target requirements in this documents is testable, so must be the totality of the requirements in this document. Therefore, conformance tests for all requirements can exist, and can be described as required in <a href="https://wg-eips.ritovision.com/6734/#d2">[D2]</a>.</p> <p><a name="r5"> <strong>[R5]</strong> </a> A claim that a canonical token list implementation conforms to this specification at <strong>Level 2</strong> or higher MUST describe the testing procedure carried out for each requirement at <strong>Level 2</strong> or higher, that justifies the claim to that requirement.</p> <p><a href="https://wg-eips.ritovision.com/6734/#r5">[R5]</a> testability: Since each of the non-conformance-target requirements in this documents is testable, so must be the totality of the requirements in this document. Therefore, conformance tests for all requirements can exist, be described, be built and implemented and results can be recorded as required in <a href="https://wg-eips.ritovision.com/6734/#r5">[R5]</a>.</p> <h2 id="rationale">Rationale</h2> <p>This specification is extending and clarifying current custom lists such as from Arbitrum and Optimism as referenced in the <a href="https://wg-eips.ritovision.com/6734/#motivation">Motivation</a> or the Uniswap Tokenlist Project to improve clarity, security and encourage adoption by non-Web3 native entities.</p> <p>The specification is utilizing the current JSON-LD standard to describe a token list to allow for easy integrations with Self-Sovereign-Identity frameworks such as W3C DID and W3C Verifiable Credential standards that allow for interoperability across L2s, Sidechains and L1s when identifying token list relevant entities such as Token Issuers. In addition, being compatible to W3C utilized frameworks allows implementers to use existing tooling around JSON-LD, W3C DIDs and W3C Verifiable Credentials. The choice of referencing known data property definitions from schema.org further disambiguates the meaning and usage of terms.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no additional security requirements apart from the warnings that URIs utilized in implementations of this standard might be direct to malicious resources such as websites, and that implementers should ensure that data utilized for a canonical token list is secure and correct. Since this standard is focused on a data schema and its data properties there are no additional security considerations from for example homoglyph attacks (see <a rel="external" href="https://nvd.nist.gov/vuln/detail/CVE-2021-42574">CVE-2021-42574 (2021-10-25T12:38:28)</a>).</p> <h3 id="security-considerations-data-privacy">Security Considerations: Data Privacy</h3> <p>The standard does not set any requirements for compliance to jurisdiction legislation/regulations. It is the responsibility of the implementer to comply with applicable data privacy laws.</p> <h3 id="security-considerations-production-readiness">Security Considerations: Production Readiness</h3> <p>The standard does not set any requirements for the use of specific applications/tools/libraries etc. The implementer should perform due diligence when selecting specific applications/tools/libraries.</p> <h3 id="security-considerations-internationalization-and-localization">Security Considerations: Internationalization and Localization</h3> <p>The standard encourages implementers to follow the <a rel="external" href="https://www.w3.org/TR/2022/DNOTE-string-meta-20220804/">W3C "Strings on the Web: Language and Direction Metadata" best practices guide</a> for identifying language and base direction for strings used on the Web wherever appropriate.</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-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin Renan Rodrigues de Souzahttps://github.com/RenanSouza2 https://wg-eips.ritovision.com/684/

Revert contract creation if address already has code

<h2 id="abstract">Abstract</h2> <p>This EIP causes contract creation to throw an error when attempted at an address with pre-existing code. This prevents an attack consisting of deploying contract code and later changing the code arbitrarily by "creating" an account at that existing address.</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>If a contract creation is attempted due to a creation transaction, the <code>CREATE</code> opcode, the <code>CREATE2</code> opcode, or any other reason, and the destination address already has either a nonzero nonce, or a nonzero code length, then the creation MUST throw as if the first byte in the init code were an invalid opcode. This change MUST apply retroactively for all existing blocks.</p> <h2 id="rationale">Rationale</h2> <p>One of the core tenets of smart contracts is that their code will not change. However with sufficient computing power an attacker can change the code stored in an address to any other code, steal funds or execute other malicious activity.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is an execution layer upgrade, and so it requires a hard fork.</p> <h2 id="test-cases">Test Cases</h2> <p>Given a genesis allocation of</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Address : 0xd0bBEc6D2c628b7e2E6D5556daA14a5181b604C5,</span></span> <span class="giallo-l"><span>Balance : 1000000000000000000, // 1 ether</span></span> <span class="giallo-l"><span>Nonce : 0,</span></span> <span class="giallo-l"><span>code : &quot;&quot;,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Address : 0x7658771dc6Af74a3d2F8499D349FF9c1a0DF8826,</span></span> <span class="giallo-l"><span>Balance : 0,</span></span> <span class="giallo-l"><span>Nonce : 1,</span></span> <span class="giallo-l"><span>Code : &quot;0xB0B0FACE&quot;,</span></span></code></pre> <p>A contract created in the first transaction from EOA <code>0xd0bBEc6...</code> (<code>227bcc6959669226360814723ed739f1214201584b6a27409dfb8228b8be5f59</code>), with no salt, should revert.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP is a security upgrade: it enforces the immutability of deployed 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-03-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 571nKYhttps://github.com/571nKY Cosmoshttps://github.com/Cosmos4k f4t50https://github.com/f4t50 Harpocrateshttps://github.com/harpocrates555 https://wg-eips.ritovision.com/7595/

ERC-721 Extension to enable collateralization with ERC-20 based tokens.

<h2 id="abstract">Abstract</h2> <p>This proposal recommends an extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> to allow for collateralization using a list of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> based tokens. The proprietor of this ERC collection could hold both the native coin and <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> based tokens, with the <code>ownerOf</code> tokenId being able to unlock the associated portion of the underlying <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> balance.</p> <h2 id="motivation">Motivation</h2> <p>The emerging trend of NFT finance focuses on the NFT floor price to enable the market value of the NFT serve as a collateral in lending protocols. The NFT floor price is susceptible to the supply-demand dynamics of the NFT market, characterized by higher volatility compared to the broader crypto market. Furthermore, potential price manipulation in specific NFT collections can artificially inflate NFT market prices, impacting the floor price considered by lending protocols. Relying solely on the NFT floor price based on market value is both unpredictable and unreliable.</p> <p>This ERC addresses various challenges encountered by the crypto community with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> based collections and assets. This ERC brings forth advantages such as sustainable NFT royalties supported by tangible assets, an on-chain verifiable floor price, and the introduction of additional monetization avenues for NFT collection creators.</p> <h3 id="presets">Presets</h3> <ul> <li> <p>The Basic Preset allows for the evaluation of an on-chain verifiable price floor for a specified NFT asset.</p> </li> <li> <p>The Dynamic Preset facilitates on-chain modification of tokenURI based on predefined collateral rules for a specified NFT asset.</p> </li> <li> <p>With the Royalty Preset, NFT collection creators can receive royalty payments for each transaction involving asset owners and Externally Owned Accounts (EOA), as well as transactions with smart contracts.</p> </li> <li> <p>The VRF Preset enables the distribution of collateral among multiple NFT asset holders using the Verifiable Random Function (VRF) by Chainlink.</p> </li> </ul> <h3 id="extension-to-existing-erc-721-based-collections">Extension to Existing ERC-721 Based Collections</h3> <p>For numerous <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> based collections that cannot be redeployed, we propose the implementation of an abstraction layer embodied by a smart contract. This smart contract would replicate all the functionalities of this ERC standard and grant access to collateral through mapping.</p> <h2 id="specification">Specification</h2> <h3 id="erc-standard-for-new-nft-collections">ERC standard for new NFT collections</h3> <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"> IERC721Envious</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"> event</span><span class="z-entity z-name"> Collateralized</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"> amount</span><span>, </span><span class="z-support">address</span><span class="z-variable"> tokenAddress</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Uncollateralized</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"> amount</span><span>, </span><span class="z-support">address</span><span class="z-variable"> tokenAddress</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Dispersed</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenAddress</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 class="z-storage z-type"> event</span><span class="z-entity z-name"> Harvested</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenAddress</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"> scaledAmount</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"> An array with two elements. Each of them represents percentage from collateral</span></span> <span class="giallo-l"><span class="z-comment"> * to be taken as a commission. First element represents collateralization commission.</span></span> <span class="giallo-l"><span class="z-comment"> * Second element represents uncollateralization commission. There should be 3 </span></span> <span class="giallo-l"><span class="z-comment"> * decimal buffer for each of them, e.g. 1000 = 1%.</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"> uint</span><span class="z-comment"> 256 index of value in 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"> commissions</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> &#39;Black hole&#39; is any address that guarantees that tokens sent to it will not be </span></span> <span class="giallo-l"><span class="z-comment"> * retrieved from it. </span><span class="z-keyword">Note</span><span class="z-comment">: some tokens revert on transfer to 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">@return</span><span class="z-variable z-other"> address</span><span class="z-comment"> address of black hole.</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"> blackHole</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">@dev</span><span class="z-comment"> Token that will be used to harvest collected commissions.</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"> address</span><span class="z-comment"> address of 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"> communityToken</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">@dev</span><span class="z-comment"> Pool of available tokens for harvesting.</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"> uint256</span><span class="z-comment"> index in 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"> address</span><span class="z-comment"> address of 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"> communityPool</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">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">@dev</span><span class="z-comment"> Token balance available for harvesting.</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"> address</span><span class="z-comment"> address 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"> uint256</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"> communityBalance</span><span>(</span><span class="z-support">address</span><span class="z-variable"> tokenAddress</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">@dev</span><span class="z-comment"> Array of tokens that have been dispersed.</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"> uint256</span><span class="z-comment"> index in 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"> address</span><span class="z-comment"> address of dispersed 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"> disperseTokens</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">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">@dev</span><span class="z-comment"> Amount of tokens that has been dispersed.</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"> address</span><span class="z-comment"> address 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"> uint256</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"> disperseBalance</span><span>(</span><span class="z-support">address</span><span class="z-variable"> tokenAddress</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">@dev</span><span class="z-comment"> Amount of tokens that was already taken from the disperse.</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"> address</span><span class="z-comment"> address 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"> uint256</span><span class="z-comment"> total amount of tokens already taken.</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"> disperseTotalTaken</span><span>(</span><span class="z-support">address</span><span class="z-variable"> tokenAddress</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">@dev</span><span class="z-comment"> Amount of disperse already taken by each 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"> unique identifier of unit.</span></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"> address 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"> uint256</span><span class="z-comment"> amount of tokens already taken.</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"> disperseTaken</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"> tokenAddress</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">@dev</span><span class="z-comment"> Mapping of `tokenId`s to token addresses that have collateralized before.</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"> unique identifier of unit.</span></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"> in 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"> address</span><span class="z-comment"> address of 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"> collateralTokens</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"> 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">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">@dev</span><span class="z-comment"> Token balances that are stored under `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"> unique identifier of unit.</span></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"> address 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"> uint256</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"> collateralBalances</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"> tokenAddress</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">@dev</span><span class="z-comment"> Calculator function for harvesting.</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"> amount</span><span class="z-comment"> of `communityToken`s to spend</span></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"> address of token to be harvested</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"> to harvest based on inputs</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"> getAmount</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> tokenAddress</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">@dev</span><span class="z-comment"> Collect commission fees gathered in exchange for `communityToken`.</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"> amounts</span><span class="z-comment">[] array of amounts to collateralize</span></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">[] array of token 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"> harvest</span><span>(</span><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 class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tokenAddresses</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"> Collateralize NFT with different tokens and amounts.</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"> unique identifier for specific 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"> amounts</span><span class="z-comment">[] array of amounts to collateralize</span></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">[] array of token 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"> collateralize</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>[</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"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tokenAddresses</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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Withdraw underlying collateral.</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"> * - only owner of 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">@param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> unique identifier for specific 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"> amounts</span><span class="z-comment">[] array of amounts to collateralize</span></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">[] array of token 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"> uncollateralize</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenId</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"> amounts</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 class="z-variable"> tokenAddresses</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">@dev</span><span class="z-comment"> Split collateral among all existent tokens.</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"> amounts</span><span class="z-comment">[] to be dispersed among all NFT 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"> address</span><span class="z-comment">[] address of token to be dispersed</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"> disperse</span><span>(</span><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 class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tokenAddresses</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></code></pre><h3 id="abstraction-layer-for-already-deployed-nft-collections">Abstraction layer for already deployed NFT collections</h3> <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"> IEnviousHouse</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Collateralized</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"> collection</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"> amount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> tokenAddress</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"> Uncollateralized</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"> collection</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"> amount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> tokenAddress</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"> Dispersed</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"> collection</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"> 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"> Harvested</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"> collection</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"> amount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> scaledAmount</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"> totalCollections function returns the total count of registered collections.</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"> uint256</span><span class="z-comment"> number of registered collections.</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"> totalCollections</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">@dev</span><span class="z-comment"> &#39;Black hole&#39; is any address that guarantees that tokens sent to it will not be </span></span> <span class="giallo-l"><span class="z-comment"> * retrieved from it. </span><span class="z-keyword">Note</span><span class="z-comment">: some tokens revert on transfer to 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"> address</span><span class="z-comment"> collection 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"> address</span><span class="z-comment"> address of black hole.</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"> blackHole</span><span>(</span><span class="z-support">address</span><span class="z-variable"> collection</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">@dev</span><span class="z-comment"> collections function returns the collection address based on the collection index input.</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"> uint256</span><span class="z-comment"> index of a registered collection.</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"> address 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"> collections</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">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">@dev</span><span class="z-comment"> collectionIds function returns the collection index based on the collection address input.</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"> address</span><span class="z-comment"> collection 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"> uint256</span><span class="z-comment"> collection index.</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"> collectionIds</span><span>(</span><span class="z-support">address</span><span class="z-variable"> collection</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> specificCollections function returns whether a particular collection follows the ERC721 standard or not.</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"> address</span><span class="z-comment"> collection 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"> bool</span><span class="z-comment"> specific collection or 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"> specificCollections</span><span>(</span><span class="z-support">address</span><span class="z-variable"> collection</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> An array with two elements. Each of them represents percentage from collateral</span></span> <span class="giallo-l"><span class="z-comment"> * to be taken as a commission. First element represents collateralization commission.</span></span> <span class="giallo-l"><span class="z-comment"> * Second element represents uncollateralization commission. There should be 3 </span></span> <span class="giallo-l"><span class="z-comment"> * decimal buffer for each of them, e.g. 1000 = 1%.</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"> address</span><span class="z-comment"> collection 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"> uint256</span><span class="z-comment"> index of value in 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"> uint256</span><span class="z-comment"> collected commission.</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"> commissions</span><span>(</span><span class="z-support">address</span><span class="z-variable"> collection</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 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"> Token that will be used to harvest collected commissions.</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"> address</span><span class="z-comment"> collection 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"> address</span><span class="z-comment"> address of 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"> communityToken</span><span>(</span><span class="z-support">address</span><span class="z-variable"> collection</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">@dev</span><span class="z-comment"> Pool of available tokens for harvesting.</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"> address</span><span class="z-comment"> collection 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"> uint256</span><span class="z-comment"> index in 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"> address</span><span class="z-comment"> address of 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"> communityPool</span><span>(</span><span class="z-support">address</span><span class="z-variable"> collection</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">address</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">@dev</span><span class="z-comment"> Token balance available for harvesting.</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"> address</span><span class="z-comment"> collection 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"> address</span><span class="z-comment"> address 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"> uint256</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"> communityBalance</span><span>(</span><span class="z-support">address</span><span class="z-variable"> collection</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> tokenAddress</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">@dev</span><span class="z-comment"> Array of tokens that have been dispersed.</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"> address</span><span class="z-comment"> collection 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"> uint256</span><span class="z-comment"> index in 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"> address</span><span class="z-comment"> address of dispersed 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"> disperseTokens</span><span>(</span><span class="z-support">address</span><span class="z-variable"> collection</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">address</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">@dev</span><span class="z-comment"> Amount of tokens that has been dispersed.</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"> address</span><span class="z-comment"> collection 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"> address</span><span class="z-comment"> address 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"> uint256</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"> disperseBalance</span><span>(</span><span class="z-support">address</span><span class="z-variable"> collection</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> tokenAddress</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Amount of tokens that was already taken from the disperse.</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"> address</span><span class="z-comment"> collection 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"> address</span><span class="z-comment"> address 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"> uint256</span><span class="z-comment"> total amount of tokens already taken.</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"> disperseTotalTaken</span><span>(</span><span class="z-support">address</span><span class="z-variable"> collection</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> tokenAddress</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Amount of disperse already taken by each 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"> address</span><span class="z-comment"> collection 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"> unique identifier of unit.</span></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"> address 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"> uint256</span><span class="z-comment"> amount of tokens already taken.</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"> disperseTaken</span><span>(</span><span class="z-support">address</span><span class="z-variable"> collection</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"> tokenAddress</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Mapping of `tokenId`s to token addresses that have collateralized before.</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"> address</span><span class="z-comment"> collection 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"> unique identifier of unit.</span></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"> in 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"> address</span><span class="z-comment"> address of 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"> collateralTokens</span><span>(</span><span class="z-support">address</span><span class="z-variable"> collection</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"> 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">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">@dev</span><span class="z-comment"> Token balances that are stored under `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"> address</span><span class="z-comment"> collection 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"> unique identifier of unit.</span></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"> address 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"> uint256</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"> collateralBalances</span><span>(</span><span class="z-support">address</span><span class="z-variable"> collection</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"> tokenAddress</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Calculator function for harvesting.</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"> address</span><span class="z-comment"> collection 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"> of `communityToken`s to spend.</span></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"> address of token to be harvested.</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"> to harvest based on inputs.</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"> getAmount</span><span>(</span><span class="z-support">address</span><span class="z-variable"> collection</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> tokenAddress</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> setSpecificCollection function enables the addition of any collection that is not compatible with the ERC721 standard to the list of exceptions.</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"> address</span><span class="z-comment"> collection 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"> setSpecificCollection</span><span>(</span><span class="z-support">address</span><span class="z-variable"> collection</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> registerCollection function grants Envious functionality to any ERC721-compatible collection and streamlines</span></span> <span class="giallo-l"><span class="z-comment"> * the distribution of an initial minimum disbursement to all NFT holders.</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"> address</span><span class="z-comment"> collection 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"> address</span><span class="z-comment"> address of `communityToken`.</span></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"> collateralization fee, incoming / 1e5 * 100%.</span></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"> uncollateralization fee, incoming / 1e5 * 100%.</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"> registerCollection</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> token</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> incoming</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> outcoming</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></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"> Collect commission fees gathered in exchange for `communityToken`.</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"> address</span><span class="z-comment"> collection 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">[] array of amounts to collateralize.</span></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">[] array of token 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"> harvest</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tokenAddresses</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> <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"> Collateralize NFT with different tokens and amounts.</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"> address</span><span class="z-comment"> collection 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"> unique identifier for specific 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"> amounts</span><span class="z-comment">[] array of amounts to collateralize.</span></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">[] array of token 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"> collateralize</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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>[</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"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tokenAddresses</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></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"> Withdraw underlying collateral.</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"> * - only owner of 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">@param</span><span class="z-variable z-other"> address</span><span class="z-comment"> collection 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"> unique identifier for specific 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"> amounts</span><span class="z-comment">[] array of amounts to collateralize.</span></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">[] array of token 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"> uncollateralize</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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>[</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"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tokenAddresses</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> <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"> Split collateral among all existent tokens.</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"> address</span><span class="z-comment"> collection 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">[] to be dispersed among all NFT 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"> address</span><span class="z-comment">[] address of token to be dispersed.</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"> disperse</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tokenAddresses</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></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="envious-term-choice">“Envious” Term Choice</h3> <p>We propose adopting the term "Envious" to describe any NFT collection minted using this ERC standard or any <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> based NFT collection that utilized the EnviousHouse abstraction layer.</p> <h3 id="nft-collateralization-with-multiple-tokens">NFT Collateralization with Multiple Tokens</h3> <p>Some Web3 projects primarily collateralize a specific NFT asset with one <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> based token, resulting in increased gas fees and complications in User Experience (UX).</p> <p>This ERC has been crafted to enable the collateralization of a designated NFT asset with multiple <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> based tokens within a single transaction.</p> <h3 id="nft-collateralization-with-the-native-coin">NFT Collateralization with the Native Coin</h3> <p>Each <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> based token possesses a distinct address. However, a native coin does not carry an address. To address this, we propose utilizing a null address (<code>0x0000000000000000000000000000000000000000</code>) as an identifier for the native coin during collateralization, as it eliminates the possibility of collisions with smart contract addresses.</p> <h3 id="disperse-functionality">Disperse Functionality</h3> <p>We have implemented the capability to collateralize all assets within a particular NFT collection in a single transaction. The complete collateral amount is deposited into a smart contract, enabling each user to claim their respective share of the collateral when they add or redeem collateral for that specific asset.</p> <h3 id="harvest-functionality">Harvest Functionality</h3> <p>Each Envious NFT collection provides an option to incorporate a community <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> based token, which can be exchanged for commissions accrued from collateralization and uncollateralization activities.</p> <h3 id="blackhole-instance">BlackHole Instance</h3> <p>Some <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> based token implementations forbid transfers to the null address, it is necessary to have a reliable burning mechanism in the harvest transactions. <code>blackHole</code> smart contract removes <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> communityTokens from the circulating supply in exchange for commission fees withdrawn.</p> <p><code>blackHole</code> has been designed to prevent the transfer of any tokens from itself and can only perform read operations. It is intended to be used with the Envious extension in implementations related to commission harvesting.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>EnviousHouse abstraction layer is suggested for already deployed <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> based NFT collections.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Envious may share security concerns similar to those found in <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, such as hidden logic within functions like burn, add resource, accept resource, etc.</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-12T00:00:00+00:00 2026-02-11T14:48:25+00:00 out.ethhttps://github.com/outdoteth https://wg-eips.ritovision.com/6682/

Minimal interface for ERC-721 NFT flashloans

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of the existing flashloan standard (<a href="https://wg-eips.ritovision.com/3156/">ERC-3156</a>) to support <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> NFT flashloans. It proposes a way for flashloan providers to lend NFTs to contracts, with the condition that the loan is repaid in the same transaction along with some fee.</p> <h2 id="motivation">Motivation</h2> <p>The current flashloan standard, <a href="https://wg-eips.ritovision.com/3156/">ERC-3156</a>, only supports <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens. ERC-721 tokens are sufficiently different from ERC-20 tokens that they require an extension of this existing standard to support them.</p> <p>An NFT flash loan could be useful in any action where NFT ownership is checked. For example, claiming airdrops, claiming staking rewards, or taking an in-game action such as claiming farmed resources.</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="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"> ^0.8.19</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"> IERC6682</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"> The address of the token used to pay flash loan fees.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> flashFeeToken</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"> @dev</span><span class="z-comment"> Whether or not the NFT is available for a flash loan.</span></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"> The address of the NFT 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"> tokenId</span><span class="z-comment"> The ID of the NFT.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> availableForFlashLoan</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token</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>flashFeeToken</code> function MUST return the address of the token used to pay flash loan fees.</p> <p>If the token used to pay the flash loan fees is ETH then <code>flashFeeToken</code> MUST return <code>address(0)</code>.</p> <p>The <code>availableForFlashLoan</code> function MUST return whether or not the <code>tokenId</code> of <code>token</code> is available for a flashloan. If the <code>tokenId</code> is not currently available for a flashloan <code>availableForFlashLoan</code> MUST return <code>false</code> instead of reverting.</p> <p>Implementers <code>MUST</code> also implement <code>IERC3156FlashLender</code>.</p> <h2 id="rationale">Rationale</h2> <p>The above modifications are the simplest possible additions to the existing flashloan standard to support NFTs.</p> <p>We choose to extend as much of the existing flashloan standard (<a href="https://wg-eips.ritovision.com/3156/">ERC-3156</a>) as possible instead of creating a wholly new standard because the flashloan standard is already widely adopted and few changes are required to support NFTs.</p> <p>In most cases, the handling of fee payments will be desired to be paid in a separate currency to the loaned NFTs because NFTs themselves cannot always be fractionalized. Consider the following example where the flashloan provider charges a 0.1 ETH fee on each NFT that is flashloaned; The interface must provide methods that allow the borrower to determine the fee rate on each NFT and also the currency that the fee should be paid in.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible with <a href="https://wg-eips.ritovision.com/3156/">ERC-3156</a> with the exception of the <code>maxFlashLoan</code> method. This method does not make sense within the context of NFTs because NFTs are not fungible. However it is part of the existing flashloan standard and so it is not possible to remove it without breaking backwards compatibility. It is RECOMMENDED that any contract implementing this EIP without the intention of supporting ERC-20 flashloans should always return <code>1</code> from <code>maxFlashLoan</code>. The <code>1</code> reflects the fact that only one NFT can be flashloaned per <code>flashLoan</code> call. For example:</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"> maxFlashLoan</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token</span><span>)</span><span class="z-storage z-type"> public</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">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> if a contract also supports flash loans for ERC20 tokens then it can</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> return some value here instead of 1</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"><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-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.19</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;../interfaces/IERC20.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;../interfaces/IERC721.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;../interfaces/IERC3156FlashBorrower.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;../interfaces/IERC3156FlashLender.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;../interfaces/IERC6682.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"> ExampleFlashLender</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6682</span><span>, </span><span class="z-entity z-name">IERC3156FlashLender</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> internal</span><span> _feePerNFT</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> internal</span><span> _flashFeeToken</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">uint256</span><span class="z-variable"> feePerNFT_</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> flashFeeToken_</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> _feePerNFT </span><span class="z-keyword">=</span><span> feePerNFT_</span><span>;</span></span> <span class="giallo-l"><span> _flashFeeToken </span><span class="z-keyword">=</span><span> flashFeeToken_</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"> flashFeeToken</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-keyword"> return</span><span> _flashFeeToken</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"> availableForFlashLoan</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token</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-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 if the NFT is owned by this contract</span></span> <span class="giallo-l"><span class="z-keyword"> try</span><span class="z-entity z-name"> IERC721</span><span>(</span><span>token</span><span>)</span><span>.</span><span class="z-entity z-name">ownerOf</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"> result</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> result </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> }</span><span class="z-keyword"> catch</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-storage z-type"> function</span><span class="z-entity z-name"> flashFee</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token</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-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> _feePerNFT</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"> flashLoan</span><span>(</span><span class="z-storage z-type">IERC3156FlashBorrower</span><span class="z-variable"> receiver</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> token</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</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> <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">bool</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> check that the NFT is available for a flash loan</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">availableForFlashLoan</span><span>(</span><span>token</span><span>,</span><span> tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;IERC6682: NFT not available for flash loan&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"> transfer the NFT to the borrower</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC721</span><span>(</span><span>token</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 class="z-support"> address</span><span>(</span><span>receiver</span><span>)</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"> calculate the fee</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> fee </span><span class="z-keyword">=</span><span class="z-entity z-name"> flashFee</span><span>(</span><span>token</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"> call the borrower</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> success </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span> receiver</span><span>.</span><span class="z-entity z-name">onFlashLoan</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> token</span><span>,</span><span> tokenId</span><span>,</span><span> fee</span><span>,</span><span> data</span><span>)</span><span class="z-keyword"> ==</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;ERC3156FlashBorrower.onFlashLoan&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"> check that flashloan was successful</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>success</span><span>,</span><span class="z-string"> &quot;IERC6682: Flash loan failed&quot;</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"> check that the NFT was returned by the borrower</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">IERC721</span><span>(</span><span>token</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 class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span class="z-string"> &quot;IERC6682: NFT not returned by borrower&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"> transfer the fee from the borrower</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC20</span><span>(</span><span class="z-entity z-name">flashFeeToken</span><span>(</span><span>)</span><span>)</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> fee</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> success</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"> maxFlashLoan</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token</span><span>)</span><span class="z-storage z-type"> public</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">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> if a contract also supports flash loans for ERC20 tokens then it can</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> return some value here instead of 1</span></span> <span class="giallo-l"><span class="z-keyword"> return</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"> 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"> memory</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> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> this</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></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>It's possible that the <code>flashFeeToken</code> method could return a malicious contract. Borrowers who intend to call the address that is returned from the <code>flashFeeToken</code> method should take care to ensure that the contract is not malicious. One way they could do this is by verifying that the returned address from <code>flashFeeToken</code> matches that of a user input.</p> <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-09T00:00:00+00:00 2026-02-11T14:48:25+00:00 Shu Donghttps://github.com/dongshu2013 Zihao Chenhttps://github.com/zihaoccc Peter Chenhttps://github.com/pette1999 https://wg-eips.ritovision.com/6662/

An ERC-4337 extension to define a new authentication model

<h2 id="abstract">Abstract</h2> <p>This ERC proposes a new <strong>IAccountMetadata</strong> interface as an extension for <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> to store authentication data on-chain to support a more user-friendly authentication model.</p> <h2 id="motivation">Motivation</h2> <p>In this proposal, we propose a new <strong>IAccountMetadata</strong> interface as an extension for ERC-4337 <strong>IAccount</strong> interface. With this new interface, users can store authentication data on-chain through one-time publishing, allowing dApps to proactively fetch it from the chain to support a more flexible and user-friendly authentication model. This will serve as an alternative to the current authentication model where users need to log in with a wallet every time and push account-related information to dApps by connecting the wallet in advance.</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="authentication-flow">Authentication Flow</h3> <p><img src="https://wg-eips.ritovision.com/6662/./assets/auth-flow.png" alt="Authentication Flow" /></p> <p>In the new authentication workflow, users use AA compatible smart contract accounts as their wallet addresses. <strong>Authenticator</strong> could be anything but holding the private key to sign users' operations. For example, it can be an offline authenticator mobile app or an online cloud service. <strong>Relay</strong> is an online service responsible for forwarding requests from dApps to the Authenticator. If the authenticator is online, it can play the role of Relay service and listen to dApps directly.</p> <h3 id="interface">Interface</h3> <p>To support the new authentication workflow, this ERC proposes a new <strong>IAccountMetadata</strong> interface as an extension of <strong>IAccount</strong> interface defined by ERC-4337.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>interface IAccountMetadata {</span></span> <span class="giallo-l"><span> struct AuthenticatorInfo {</span></span> <span class="giallo-l"><span> // a list of service URIs to relay message from dApps to authenticators</span></span> <span class="giallo-l"><span> string[] relayURI;</span></span> <span class="giallo-l"><span> // a JSON string or URI pointing to a JSON file describing the</span></span> <span class="giallo-l"><span> // schema of AuthenticationRequest. The URI should follow ERC-4804</span></span> <span class="giallo-l"><span> // if the schema file is stored on-chain</span></span> <span class="giallo-l"><span> string schema;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function getAuthenticationInfo() external view returns(AuthenticatorInfo[] memory);</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The relay endpoint should accept an AuthenticationRequest object as input. The format of the AuthenticationRequest object is defined by the schema field at AuthenticationInfo.</p> <p>Following is a schema example which supports end to end encryption, where we pack all encrypted fields into an encryptedData field. Here we only list basic fields but there may be more fields per schema definition. A special symbol, such as "$e2ee", could be used to indicate the field is encrypted.</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">AuthenticationRequest</span><span class="z-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">entrypoint</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 entrypoint contract address</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">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">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 chain id represented as hex string, e.g. 0x5 for goerli testnet</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">userOp</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">UserOp struct defined by ERC-4337 without signature</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">encryptedData</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">contains all encrypted fields</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>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>To enable the new authentication workflow we described above, dApp needs to know two things:</p> <ol> <li> <p><strong>Where is the authenticator?</strong> This is solved by the <strong>relayURI</strong> field in struct <strong>AuthenticationInfo</strong>. Users can publish the uri as the account metadata which will be pulled by dApp to do service discovery.</p> </li> <li> <p><strong>What’s the format of AuthenticationRequest?</strong> This is solved by the <strong>schema</strong> field in struct <strong>AuthenticationInfo</strong>. The schema defines the structure of the AuthenticationRequest object which is consumed by the authenticator. It can also be used to define extra fields for the relay service to enable flexible access control.</p> </li> </ol> <h3 id="relay-service-selection">Relay Service Selection</h3> <p>Each authenticator can provide a list of relay services. dApp should pull through the list of relay services in order to find the first workable one. All relay services under each authenticator must follow the same schema.</p> <h3 id="signature-aggregation">Signature Aggregation</h3> <p>Multisig authentication could be enabled if multiple AuthenticatorInfos are provided under each smart contract account. Each authenticator can sign and submit signed user operations to bundler independently. These signatures will be aggregated by the Aggregator defined in ERC-4337.</p> <h3 id="future-extension">Future Extension</h3> <p>The <strong>IAccountMetadata</strong> interface could be extended per different requirements. For example, a new alias or avatar field could be defined for profile displaying.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The new interface is fully backward compatible with ERC-4337.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="end-to-end-encryption">End to End Encryption</h3> <p>To protect the user’s privacy and prevent front-running attacks, it's better to keep the data from dApps to authenticators encrypted during transmission. This could be done by adopting the JWE (JSON Web Encryption, RFC-7516) method. Before sending out AuthenticationRequest, a symmetric CEK(Content Encryption Key) is generated to encrypt fields with end to end encryption enabled, then the CEK is encrypted with the signer's public key. dApp will pack the request into a JWE object and send it to the authenticator through the relay service. Relay service has no access to the end to end encrypted data since only the authenticator has the key to decrypt the CEK.</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-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Chris Walkerhttps://github.com/cr-walkerchris@ckwalker.com https://wg-eips.ritovision.com/6604/

move tokens on- and off-chain as desired, enabling zero-cost minting while preserving on-chain composability

<h2 id="abstract">Abstract</h2> <p>Abstract tokens provide a standard interface to:</p> <ul> <li>Mint tokens off-chain as messages</li> <li>Reify tokens on-chain via smart contract</li> <li>Dereify tokens back into messages</li> </ul> <p>Abstract tokens can comply with existing standards like <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>. The standard allows wallets and other applications to better handle <em>potential</em> tokens before any consensus-dependent events occur on-chain.</p> <h2 id="motivation">Motivation</h2> <p>Abstract tokens enable zero-cost token minting, facilitating high-volume applications by allowing token holders to reify tokens (place the tokens on-chain) as desired. Example use cases:</p> <ul> <li>airdrops</li> <li>POAPs / receipts</li> <li>identity / access credentials</li> </ul> <p>Merkle trees are often used for large token distributions to spread mint/claim costs to participants, but they require participants to provide a markle proof when claiming tokens. This standard aims to improve the claims proces for similar distributions:</p> <ul> <li>Generic: compatible with merkle trees, digital signatures, or other eligibility proofs</li> <li>Legible: users can query an abstract token contract to understand their potential tokens (e.g. token id, quantity, or uri)</li> <li>Contained: users do not need to understand the proof mechanism used by the particular token implementation contract</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> <h3 id="data-types">Data Types</h3> <h4 id="token-messages">Token Messages</h4> <p>A token message defines one or more tokens along with the context needed to reify the token(s) using a smart contract.</p> <p><code>chainId</code> &amp; <code>implementation</code>: set the domain of the token message to a specific chain and contract: this is where the token can be reified <code>owner</code>: the address that owns the tokens defined in the messages when reified <code>meta</code>: implementation-specific context necessary to reify the defined token(s), such as id, amount, or uri. <code>proof</code>: implementation-specific authorization to reify the defined token(s). <code>nonce</code>: counter that may be incremented when multiple otherwise-identical abstract token messages are needed</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"> AbstractTokenMessage</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> implementation</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> owner</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> meta</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"> bytes</span><span> proof</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="message-status">Message Status</h4> <p>A message status may be defined for every (abstract token contract, abstract token message) pair. <code>invalid</code>: the contract cannot interact with the message <code>valid</code>: the contract can interact with the message <code>used</code>: the contract has already interacted with the message</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"> AbstractTokenMessageStatus</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> invalid</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> valid</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> used</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="methods">Methods</h3> <h4 id="reify">reify</h4> <p>Moves token(s) from a message to a contract <code>function reify(AbstractTokenMessage calldata message) external;</code></p> <p>The token contract MUST reify a valid token message.</p> <p>Reification MUST be idempotent: a particular token message may be used to reify tokens at most once. Calling <code>reify</code> with an already used token message MAY succeed or revert.</p> <h4 id="status">status</h4> <p>Returns the status of a particular message <code>function status(AbstractTokenMessage calldata message) external view returns (AbstractTokenMessageStatus status);</code></p> <h4 id="dereify">dereify</h4> <p>Moves token(s) from a contract to a message intended for another contract and/or chain. <code>function dereify(AbstractTokenMessage calldata message) external;</code></p> <p>OPTIONAL - allows tokens to be moved between contracts and/or chains by dereifying them from one context and reifying them in another. Dereification MUST be idempotent: a particular token message must be used to dereify tokens at most once.</p> <p>If implemented, dereification:</p> <ul> <li>MUST burn the exact tokens from the holder as defined in the token message</li> <li>MUST NOT dereify token messages scoped to the same contract and chain.</li> <li>MAY succeed or revert if the token message is already used.</li> <li>MUST emit the <code>Reify</code> event on only the first <code>reify</code> call with a specific token message</li> </ul> <h4 id="id">id</h4> <p>Return the id of token(s) defined in a token message. <code>function id(AbstractTokenMessage calldata message) external view returns (uint256);</code></p> <p>OPTIONAL - abstract token contracts without a well-defined token ID (e.g. ERC-20) MAY return <code>0</code> or not implement this method.</p> <h4 id="amount">amount</h4> <p>Return the amount of token(s) defined in a token message. <code>function amount(AbstractTokenMessage calldata message) external view returns (uint256);</code></p> <p>OPTIONAL - abstract token contracts without a well-defined token amount (e.g. ERC-721) MAY return <code>0</code> or not implement this method.</p> <h4 id="uri">uri</h4> <p>Return the amount of token(s) defined in a token message. <code>function uri(AbstractTokenMessage calldata message) external view returns (string memory);</code></p> <p>OPTIONAL - abstract token contracts without a well-defined uri (e.g. ERC-20) MAY return <code>""</code> or not implement this method.</p> <h4 id="supportsinterface">supportsInterface</h4> <p>All abstract token contracts must support <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> and include the Abstract Token interface ID in their supported interfaces.</p> <h3 id="events">Events</h3> <h4 id="reify-1">Reify</h4> <p>The Reify event MUST be emitted when a token message is reified into tokens <code>event Reify(AbstractTokenMessage);</code></p> <h4 id="dereify-1">Dereify</h4> <p>The Dereify event MUST be emitted when tokens are dereified into a message <code>event Dereify(AbstractTokenMessage);</code></p> <h3 id="application-to-existing-token-standards">Application to existing token standards</h3> <p>Abstract tokens compatible with existing token standards MUST overload existing token transfer functions to allow transfers from abstract token messages.</p> <h3 id="abstract-erc-20">Abstract ERC-20</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"> IAbstractERC20</span><span class="z-storage"> is</span><span class="z-entity z-name"> IAbstractToken</span><span>, </span><span class="z-entity z-name">IERC20</span><span>, </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"> reify the message and then transfer tokens</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> <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></span> <span class="giallo-l"><span class="z-storage z-type"> AbstractTokenMessage</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> message</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-comment"> reify the message and then transferFrom tokens</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></span> <span class="giallo-l"><span class="z-storage z-type"> AbstractTokenMessage</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> message</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></span></code></pre><h3 id="abstract-erc-721">Abstract ERC-721</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"> IAbstractERC721</span><span class="z-storage"> is</span><span class="z-entity z-name"> IAbstractToken</span><span>, </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"> safeTransferFrom</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></span> <span class="giallo-l"><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> <span class="giallo-l"><span class="z-storage z-type"> AbstractTokenMessage</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> message</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"> 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"> tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> AbstractTokenMessage</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> message</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><h3 id="abstract-erc-1155">Abstract ERC-1155</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>interface IAbstractERC1155 is IAbstractToken, IERC1155 {</span></span> <span class="giallo-l"><span> function safeTransferFrom(</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 id,</span></span> <span class="giallo-l"><span> uint256 amount,</span></span> <span class="giallo-l"><span> bytes calldata data,</span></span> <span class="giallo-l"><span> AbstractTokenMessage calldata message</span></span> <span class="giallo-l"><span> ) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function safeBatchTransferFrom(</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[] calldata ids,</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> AbstractTokenMessage[] calldata messages</span></span> <span class="giallo-l"><span> ) external;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="meta-format">Meta format</h3> <p>The abstract token message <code>meta</code> field is simply a byte array to preserve the widest possible accesibility.</p> <ul> <li>Applications handling abstract tokens can interact with the implementation contract for token metadata rather than parsing this field, so legibility is of secondary importance</li> <li>A byte array can be decoded as a struct and checked for errors within the implementation contract</li> <li>Future token standards will include unpredictable metadata</li> </ul> <h3 id="proof-format">Proof format</h3> <p>Similar considerations went into defining the <code>proof</code> field as a plain byte array:</p> <ul> <li>The contents of this field may vary, e.g. an array of <code>bytes32</code> merkle tree nodes or a 65 byte signature.</li> <li>a byte array handles all potential use cases at the expense of increased message size.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/6604/assets/README/">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Several concerns are highlighted.</p> <h3 id="message-loss">Message Loss</h3> <p>Because token messages are not held on-chain, loss of the message may result in loss of the token. Applications that issue abstract tokens to their users can store the messages themselves, but ideally users would be able to store and interact with abstract token messages within their crypto wallets.</p> <h3 id="authorizing-reification">Authorizing Reification</h3> <p>Token messages may only be reified if they include a validity proof. While the proof mechanism itself is out of scope for this standard, those designing proof mechanisms should consider:</p> <ul> <li>Does total supply need to audited on-chain and/or off-chain?</li> <li>Does the mechanism require ongoing access to a secret (e.g. digital signature) or is it immutable (e.g. merkle proof)?</li> <li>Is there any way for an attacker to prevent the reification of an otherwise valid token message?</li> </ul> <h3 id="non-owner-de-reification">Non-owner (De)Reification</h3> <p>Can non-owners (de)reify a token message on behalf of the owner?</p> <p>Pro: supporting apps should be able to handle this because once a valid message exists, the owner could (de)reify the message at any time Con: if the token contract reverts upon (de)reification of a used message, an attacker could grief the owner by front-running the transaction</p> <h3 id="abstract-token-bridge-double-spend">Abstract Token Bridge Double Spend</h3> <p>Abstract tokens could be used for a token-specific bridge:</p> <ul> <li>Dereify the token from chain A to with message M</li> <li>Reify the token on chain B with message M</li> </ul> <p>Because the abstract token standard does not specify any cross-chain message passing, the abstract token contracts on chains A and B cannot know whether a (de)reification of message M has occurred on the other chain.</p> <p>A naive bridge would be subject to double spend attacks:</p> <ul> <li>An attacker requests bridging tokens they hold on chain A to chain B</li> <li>A bridging mechanism creates an abstract token message M</li> <li>The attacker reifies message M on chain B but <em>does not</em> dereify message M on chain A</li> <li>The attacker continues to use tokens</li> </ul> <p>Some oracle mechanism is necessary to prevent the reification of message M on chain B until the corresponding tokens on chain A are dereified.</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-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Phillip Ponphillip@artifactlabs.com Gary Liugary@artifactlabs.com Henry Chanhenry@artifactlabs.com Joey Liujoey@artifactlabs.com Lauren Holauren@artifactlabs.com Jeff Leungjeff@artifactlabs.com Brian Liangbrian@artifactlabs.com Joyce Lijoyce@artifactlabs.com Avir Mahtaniavir@artifactlabs.com Antoine Cotehttps://github.com/acote88 David Leunghttps://github.com/dhl https://wg-eips.ritovision.com/6596/

Metadata extension to enhance the discoverability, connectivity, and collectability of culturally and historically significant NFTs.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes the establishment of a comprehensive metadata standard for Cultural and Historical Asset Tokens (CHATs) on the Ethereum platform. These tokens represent cultural and historical assets such as artwork, artifacts, collectibles, and rare items, providing crucial context and provenance to substantiate their significance and value.</p> <p>While existing NFT standards ensure the immutability and decentralized ownership of assets on the blockchain, based on our research they do not adequately capture the cultural and historical importance and value of such assets needed for widespread adoption by institutions such as museums. The CHAT standard aims to overcome these limitations by preserving the provenance, history, and evolving context of cultural and historical assets, thus substantiating their value. Furthermore, it incentivises museums, institutions, and asset owners to create tamper-proof records on the blockchain, ensuring transparency and accountability and accelerating adoption of web3 protocols. Additionally, the CHAT standard promotes interoperability with existing metadata standards in the arts and cultural sector, facilitating the search, discovery, and connection of distributed assets.</p> <h2 id="motivation">Motivation</h2> <p><strong>Preserving context and significance</strong> - Provenance and context are crucial for cultural and historical assets. The CHAT standard captures and preserves the provenance and history of these assets, as well as the changing contexts that emerge from new knowledge and information. This context and provenance substantiate the significance and value of cultural and historical assets.</p> <p><strong>Proof-based preservation</strong> - The recent incidents of lost artifacts and data breaches at a number of significant international museums points to a need in reassessing our current record keeping mechanisms. While existing systems mostly operate on trust, blockchain technology offers opportunities to establish permanent and verifiable records in a proof-based environment. Introducing the CHAT standard on the Ethereum platform enables museums, institutions, and owners of significant collections to create tamper-proof records on the blockchain. By representing these valuable cultural and historical assets as tokens on the blockchain, permanent and tamper-proof records can be established whenever amendments are made, ensuring greater transparency and accountability.</p> <p><strong>Interoperability</strong> - The proposed standard addresses the multitude of existing metadata standards used in the arts and cultural sector. The vision is to create a metadata structure specifically built for preservation on the blockchain that is interoperable with these existing standards and compliant with the Open Archives Initiative (OAI) as well as the International Image Interoperability Framework protocol (IIIF).</p> <p><strong>Search and Discovery</strong> - Ownership and history of artworks, artifacts, and historical intellectual properties are often distributed. Although there may never be a fully consolidated archive, a formalized blockchain-based metadata structure enables consolidation for search and discovery of the assets, without consolidating the ownership. For example, an artifact from an archaeological site of the Silk Road can be connected with Buddhist paintings, statues, and texts about the ancient trade route across museum and institutional collections internationally. The proposed CHAT metadata structure will facilitate easy access to these connections for the general public, researchers, scholars, other cultural professionals, brands, media, and any other interested parties.</p> <p>Currently, the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard includes a basic metadata extension, which optionally provides functions for identifying NFT collections ("name" and "symbol") and attributes for representing assets ("name," "description," and "image"). However, to provide comprehensive context and substantiate the value of tokenized assets, NFT issuers often create their own metadata structures. We believe that the basic extension alone is insufficient to capture the context and significance of cultural and historical assets. The lack of interoperable and consistent rich metadata hinders users' ability to search, discover, and connect tokenized assets on the blockchain. While connectivity among collections may not be crucial for NFTs designed for games and memberships, it is of utmost importance for cultural and historical assets. As the number and diversity of tokenized assets on the blockchain increase, it becomes essential to establish a consistent and comprehensive metadata structure that provides context, substantiates value, and enables connected search and discovery at scale.</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 extends <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> with 48 additional properties to capture the cultural and historical significance of the underlying asset.</p> <p>Compatible contracts, besides implementing the relevant metadata schemas ("Metadata JSON Schema" for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> contracts or "Metadata URI JSON Schema" for <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> contracts), must implement the following metadata interface.</p> <h3 id="cultural-and-historical-asset-metadata-extension-typescript-interface">Cultural and Historical Asset Metadata Extension TypeScript Interface</h3> <p>The following TypeScript interface defines the Metadata JSON Schema compatible tokens must conform to:</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"> HistoricalAssetMetadata</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> name</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Name of the CHAT</span></span> <span class="giallo-l"><span class="z-variable"> description</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Full description of the CHAT to provide the cultural and historical</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> context</span></span> <span class="giallo-l"><span class="z-variable"> image</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> A URI pointing to a resource with mime type image/* to serve as the</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> cover image of the CHAT</span></span> <span class="giallo-l"><span class="z-variable"> attributes</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-entity z-name"> CHATAttribute</span><span>[</span><span>]</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> A list of attributes to describe the CHAT. Attribute object may be</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> repeated if a field has multiple values</span></span> <span class="giallo-l"><span class="z-variable"> attributesExt</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-entity z-name"> ExtendedCHATAttribute</span><span>[</span><span>]</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> A list of extended attributes to describe the CHAT, not to be</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> displayed. Attribute object may be repeated if a field has</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> multiple values</span></span> <span class="giallo-l"><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"> CHATAttribute</span><span class="z-keyword"> =</span></span> <span class="giallo-l"><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Catalogue Level</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Publication / Creation Date</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Creator Name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Creator Bio</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Asset Type</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Classification</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Materials and Technology</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Subject Matter</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Edition</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Series name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Dimensions Unit</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Dimensions (height)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> number</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Dimensions (width)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> number</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Dimensions (depth)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> number</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Inscriptions / Marks</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Credit Line</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Current Owner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Provenance</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Acquisition Date</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Citation</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Keyword</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Copyright Holder</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Bibliography</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Issuer</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Issue Timestamp</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Issuer Description</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Asset File Size</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> number</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Asset File Format</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Copyright / Restrictions</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Asset Creation Geo</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Asset Creation Location</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Asset Creation Coordinates</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Relevant Date</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Relevant Geo</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Relevant Location</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Relevant Person</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Relevant Entity</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Asset Language</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Is Physical Asset</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> boolean</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"> ExtendedCHATAttribute</span><span class="z-keyword"> =</span></span> <span class="giallo-l"><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Asset Full Text</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Exhibition / Loan History</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Copyright Document</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Provenance Document</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Asset URL</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> |</span><span> {</span><span class="z-variable"> trait_type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Copyright Document of Underlying Asset</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> }</span></span></code></pre><h4 id="chatattribute-description">CHATAttribute Description</h4> <table><thead><tr><th>trait_type</th><th>description</th></tr></thead><tbody> <tr><td>Catalogue Level</td><td>An indication of the level of cataloging represented by the record, based on the physical form or intellectual content of the material</td></tr> <tr><td>Publication / Creation Date</td><td>Earliest possible creation date of the underlying asset in ISO 8601 date format</td></tr> <tr><td>Creator Name</td><td>The name, brief biographical information, and roles (if necessary) of the named or anonymous individuals or corporate bodies responsible for the design, production, manufacture, or alteration of the work, presented in a syntax suitable for display to the end-user and including any necessary indications of uncertainty, ambiguity, and nuance. If there is no known creator, make a reference to the presumed culture or nationality of the unknown creator</td></tr> <tr><td>Creator Bio</td><td>The brief biography or description of creator</td></tr> <tr><td>Asset Type</td><td>The type of the underlying asset</td></tr> <tr><td>Classification</td><td>Classification terms or codes are used to place a work of art or architecture in a useful organizational scheme that has been devised by a repository, collector, or other person or entity. Formal classification systems are used to relate a work of art or architecture to broader, narrower, and related objects. Classification terms group similar works together according to varying criteria</td></tr> <tr><td>Materials and Technology</td><td>The materials and/or techniques used to create the physical underlying asset</td></tr> <tr><td>Subject Matter</td><td>Indexing terms that characterize in general terms what the work depicts or what is depicted in it. This subject analysis is the minimum required. It is recommended to also list specific subjects, if possible</td></tr> <tr><td>Edition</td><td>Edition of the original work</td></tr> <tr><td>Series Name</td><td>The name of the series the asset is a part of</td></tr> <tr><td>Dimensions Unit</td><td>Unit of the measurement of the dimension of the asset</td></tr> <tr><td>Dimensions (height)</td><td>Height of the underlying asset</td></tr> <tr><td>Dimensions (width)</td><td>Width of the underlying asset</td></tr> <tr><td>Dimensions (depth)</td><td>Depth of the underlying asset</td></tr> <tr><td>Credit Line</td><td>Crediting details of the source or origin of an image or content being used publicly. The credit line typically includes important details such as the name of the museum, the title or description of the artwork or object, the artist's name (if applicable), the date of creation, and any other relevant information that helps identify and contextualize the work</td></tr> <tr><td>Inscriptions / Marks</td><td>A description of distinguishing or identifying physical markings, lettering, annotations, texts, or labels that are a part of a work or are affixed, applied, stamped, written, inscribed, or attached to the work, excluding any mark or text inherent in materials (record watermarks in MATERIALS AND TECHNIQUES)</td></tr> <tr><td>Current Owner</td><td>Name of the current owner</td></tr> <tr><td>Provenance</td><td>Provenance provides crucial information about the artwork's authenticity, legitimacy, and historical significance. It includes details such as the names of previous owners, dates of acquisition, locations where the artwork or artifact resided, and any significant events or transactions related to its ownership</td></tr> <tr><td>Acquisition Date</td><td>The date on which the acquirer obtained the asset</td></tr> <tr><td>Citation</td><td>Citations of the asset in publications, journals, and any other medium</td></tr> <tr><td>Keyword</td><td>Keywords that are relevant for researchers</td></tr> <tr><td>Copyright Holder</td><td>Copyright holder of the underlying asset</td></tr> <tr><td>Bibliography</td><td>Information on where this asset has been referenced, cited, consulted, and for what purpose</td></tr> <tr><td>Issuer</td><td>Issuer of the token</td></tr> <tr><td>Issue Timestamp</td><td>Date of token creation</td></tr> <tr><td>Issuer Description</td><td>Brief description of the issuing party</td></tr> <tr><td>Asset File Size</td><td>Size of the digital file of the underlying asset in bytes</td></tr> <tr><td>Asset File Format</td><td>The physical form or the digital format of the underlying asset. For digital format, a MIME type should be specified</td></tr> <tr><td>Copyright / Restrictions</td><td>The copyright status the work is under</td></tr> <tr><td>Asset Creation Geo</td><td>Country, subdivision, and city where the underlying asset was created. Reference to ISO 3166-2 standard for the short name of the country and subdivision. Utilize the official name for the city if it is not covered in the ISO subdivision</td></tr> <tr><td>Asset Creation Location</td><td>Specific cities and named locations where the underlying asset was created</td></tr> <tr><td>Asset Creation Coordinates</td><td>Coordinates of the location where the underlying asset was created</td></tr> <tr><td>Relevant Date</td><td>Dates, in ISO 8601 date format, referenced in, and important to the significance of the CHAT</td></tr> <tr><td>Relevant Geo</td><td>Country, subdivision, and city CHATs are referenced and important to the significance of the CHAT. Reference to ISO 3166-2 standard for the short name of the country and subdivision. Utilize the official name for the city if it is not covered in the ISO subdivision</td></tr> <tr><td>Relevant Location</td><td>Specific cities and named locations referenced in, and important to the significance of the CHAT</td></tr> <tr><td>Relevant Person</td><td>Individuals referenced in, and important to the significance of the CHAT</td></tr> <tr><td>Relevant Entity</td><td>Entities referenced in, and important to the significance of the CHAT</td></tr> <tr><td>Asset Language</td><td>Languages used in the underlying asset. Reference to ISO 639 for code or macrolanguage names</td></tr> <tr><td>Is Physical Asset</td><td>Flags whether the asset is tied to a physical asset</td></tr> </tbody></table> <h4 id="extendedchatattribute-description">ExtendedCHATAttribute Description</h4> <table><thead><tr><th>trait_type</th><th>description</th></tr></thead><tbody> <tr><td>Asset Full Text</td><td>The full text in the underlying asset of the CHAT</td></tr> <tr><td>Exhibition / Loan History</td><td>Including exhibition/loan description, dates, title, type, curator, organizer, sponsor, venue</td></tr> <tr><td>Copyright Document</td><td>A URI pointing to the legal contract CHATs outlines the copyright of the underlying asset</td></tr> <tr><td>Provenance Document</td><td>A URI pointing to the existing provenance record documents of the underlying asset</td></tr> <tr><td>Asset URL</td><td>A URI pointing to a high-quality file of the underlying asset</td></tr> <tr><td>Copyright Document of Underlying Asset</td><td>A URI pointing to legal document outlining the rights of the token owner. Specific dimensions include the right to display a work via digital and physical mediums, present the work publicly, create or sell copies of the work, and create or sell derivations from the underlying asset</td></tr> </tbody></table> <h4 id="example">Example</h4> <p>To illustrate the use of the CHAT metadata extension, we provide an example of a CHAT metadata JSON file for the famous Japanese woodblock print "Under the Wave off Kanagawa" by Katsushika Hokusai, which is currently held by the Art Institute of Chicago.</p> <p>The metadata format is compatible with the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and OpenSea style metadata format.</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">Under the Wave off Kanagawa (Kanagawa oki nami ura), also known as The Great Wave, from the series “Thirty-Six Views of Mount Fuji (Fugaku sanjūrokkei)</span><span class="z-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">Katsushika Hokusai’s much celebrated series, Thirty-Six Views of Mount Fuji (Fugaku sanjûrokkei), was begun in 1830, when the artist was 70 years old. This tour-de-force series established the popularity of landscape prints, which continues to this day. Perhaps most striking about the series is Hokusai’s copious use of the newly affordable Berlin blue pigment, featured in many of the compositions in the color for the sky and water. Mount Fuji is the protagonist in each scene, viewed from afar or up close, during various weather conditions and seasons, and from all directions.</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string">The most famous image from the set is the “Great Wave” (Kanagawa oki nami ura), in which a diminutive Mount Fuji can be seen in the distance under the crest of a giant wave. The three impressions of Hokusai’s Great Wave in the Art Institute are all later impressions than the first state of the design.</span><span class="z-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://bafybeiav6sqcgzxk5h5afnmb3iisgma2kpnyj5fa5gnhozwaqwzlayx6se</span><span class="z-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">Publication / Creation Date</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">1826/1836</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">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">Creator Name</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Katsushika Hokusai</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">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">Creator Bio</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Katsushika Hokusai’s woodblock print The Great Wave is one of the most famous and recognizable works of art in the world. Hokusai spent the majority of his life in the capital of Edo, now Tokyo, and lived in a staggering 93 separate residences. Despite this frenetic movement, he produced tens of thousands of sketches, prints, illustrated books, and paintings. He also frequently changed the name he used to sign works of art, and each change signaled a shift in artistic style and intended audience.</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">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">Asset Type</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Painting</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">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">Classification</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Arts of Asia</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">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">Materials and Technology</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Color woodblock print, oban</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">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">Subject Matter</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Asian Art</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">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">Subject Matter</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Edo Period (1615-1868)</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">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">Subject Matter</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Ukiyo-e Style</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">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">Subject Matter</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Woodblock Prints</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">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">Subject Matter</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Japan 1800-1900 A.D.</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">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">Edition</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-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> <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">Series name</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Thirty-Six Views of Mount Fuji (Fugaku sanjûrokkei)</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">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">Dimensions Unit</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">cm</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">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">Dimensions (height)</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"> 25.4</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">Dimensions (width)</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"> 37.6</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">Inscriptions / Marks</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Signature: Hokusai aratame Iitsu fude</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">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">Inscriptions / Marks</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Publisher: Nishimura-ya Yohachi</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">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">Credit Line</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Clarence Buckingham Collection</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">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">Current Owner</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Art Institute of Chicago</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">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">Provenance</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Yamanaka, New York by 1905</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">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">Provenance</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Sold to Clarence Buckingham, Chicago by 1925</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">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">Provenance</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Kate S. Buckingham, Chicago, given to the Art Institute of Chicago, 1925.</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">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">Acquisition Date</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">1925</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">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">Citation</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">James Cuno, The Art Institute of Chicago: The Essential Guide, rev. ed. (Art Institute of Chicago, 2009) p. 100.</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">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">Citation</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">James N. Wood, The Art Institute of Chicago: The Essential Guide, rev. ed. (Art Institute of Chicago, 2003), p. 86.</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">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">Citation</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Jim Ulak, Japanese Prints (Art Institute of Chicago, 1995), p. 268.</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">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">Citation</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Ukiyo-e Taikei (Tokyo, 1975), vol. 8, 29; XIII, I.</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">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">Citation</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Matthi Forrer, Hokusai (Royal Academy of Arts, London 1988), p. 264.</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">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">Citation</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Richard Lane, Hokusai: Life and Work (London, 1989), pp. 189, 192.</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">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">Copyright Holder</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Public domain</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">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">Copyright / Restrictions</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">CC0</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">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">Asset Creation Geo</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Japan</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">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">Asset Creation Location</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Tokyo (Edo)</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">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">Asset Creation Coordinates</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">36.2048° N, 138.2529° E</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">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">Relevant Date</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">18th Century</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">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">Relevant Geo</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Japan, Chicago</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">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">Relevant Location</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Art Institute of Chicago</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">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">Relevant Person</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Katsushika Hokusai</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">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">Relevant Person</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Yamanaka</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">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">Relevant Person</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Clarence Buckingham</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">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">Relevant Person</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Kate S. Buckingham</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">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">Relevant Entity</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Art Institute of Chicago, Clarence Buckingham Collection</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">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">Asset Language</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">Japanese</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">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">Is Physical Asset</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"> true</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> <h3 id="choosing-to-extend-off-chain-metadata-json-schema-over-on-chain-interface">Choosing to Extend Off-Chain Metadata JSON Schema over On-Chain Interface</h3> <p>Both the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> provide natural extension points in the metadata JSON file associated with NFTs to supply enriched datasets about the underlying assets.</p> <p>Providing enriched datasets through off-chain metadata JSON files allows existing NFT contracts to adopt the new metadata structure proposed in this EIP without upgrading or migrating. The off-chain design enables flexible and progressive enhancement of any NFT collections to adopt this standard gradually. This approach allows NFT collections to be deployed using already-audited and battle-tested smart contract code without creating or adapting new smart contracts, reducing the risk associated with adopting and implementing a new standard.</p> <h3 id="capturing-attributes-extensions-in-attributes-and-attributesext-properties">Capturing Attributes Extensions in <code>attributes</code> and <code>attributesExt</code> properties</h3> <p>In the design of the Cultural and Historical Asset Token (CHAT) metadata extension, we have made a deliberate choice to capture the metadata attributes between two main properties: <code>attributes</code> and <code>attributesExt</code>. This division serves two distinct purposes while ensuring maximum compatibility with existing NFT galleries and marketplaces.</p> <p><strong>1. <code>attributes</code> Property</strong></p> <p>The <code>attributes</code> property contains core metadata attributes that are integral to the identity and categorization of CHATs. These attributes are meant to be readily accessible, displayed, and searchable by NFT galleries and marketplaces. By placing fundamental details such as the CHAT's name, description, image, and other key characteristics in <code>attributes</code>, we ensure that these essential elements can be easily presented to users, collectors, and researchers. This approach allows CHATs to seamlessly integrate with existing NFT platforms and marketplaces without requiring major modifications.</p> <p><strong>2. <code>attributesExt</code> Property</strong></p> <p>The <code>attributesExt</code> property, on the other hand, is dedicated to extended attributes that provide valuable, in-depth information about a CHAT but are not typically intended for display or search within NFT galleries and marketplaces. These extended attributes serve purposes such as archival documentation, provenance records, and additional context that may not be immediately relevant to a casual observer or collector. By isolating these extended attributes in <code>attributesExt</code>, we strike a balance between comprehensiveness and user-friendliness. This approach allows CHAT creators to include rich historical and contextual data without overwhelming the typical user interface, making the extended information available for scholarly or specialized use cases.</p> <p>This division of attributes into <code>attributes</code> and <code>attributesExt</code> ensures that the CHAT standard remains highly compatible with existing NFT ecosystems, while still accommodating the specific needs of cultural and historical assets. Users can enjoy a seamless experience in browsing and collecting CHATs, while researchers and historians have access to comprehensive information when required, all within a framework that respects the practicalities of both user interfaces and extended data documentation.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backward compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>NFT platforms and systems working with Cultural and Historical Asset Metadata JSON files are recommended to treat the files as client-supplied data and follow the appropriate best practices for processing such data.</p> <p>Specifically, when processing the URI fields, backend systems should take extra care to prevent a malicious issuer from exploiting these fields to perform Server-Side Request Forgery (SSRF).</p> <p>Frontend or client-side systems are recommended to escape all control characters that may be exploited to perform Cross-Site Scripting (XSS).</p> <p>Processing systems should manage resource allocation to prevent the systems from being vulnerable to Denial of Service ( DOS) attacks or circumventing security protection through arbitrary code exceptions. Improper processing of variable data, such as strings, arrays, and JSON objects, may result in a buffer overflow. Therefore, it is crucial to allocate resources carefully to avoid such vulnerabilities.</p> <p>The metadata JSON files and the digital resources representing both the token and underlying assets should be stored in a decentralized storage network to preserve the integrity and to ensure the availability of data for long-term preservation.</p> <p>Establishing the authenticity of the claims made in the Metadata JSON file is beyond the scope of this EIP, and is left to future EIPs to propose an appropriate protocol.</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-27T00:00:00+00:00 2026-02-11T14:48:25+00:00 Chirohttps://github.com/chiro-hiro Victor Dusarthttps://github.com/vdusart https://wg-eips.ritovision.com/6617/

A permission and role system based on bits

<h2 id="abstract">Abstract</h2> <p>This EIP offers a standard for building a bit-based permission and role system. Each permission is represented by a single bit. By using an <code>uint256</code>, up to $256$ permissions and $2^{256}$ roles can be defined. We are able to specify the importance of each permission based on the order of the bits.</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><em>Note</em> The following specifications use syntax from Solidity <code>0.8.7</code> (or above)</p> <p>Interface of reference is described as followed:</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.7</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"> EIP-6617 Bit Based Permission</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-6617</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"> IEIP6617</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 when a permission is granted.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _grantor</span><span class="z-comment"> Grantor of the permission</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _permission</span><span class="z-comment"> Permission that is granted</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"> User who received the permission</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"> PermissionGranted</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _grantor</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _permission</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>;</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 when a permission is revoked.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _revoker</span><span class="z-comment"> Revoker of the permission</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _permission</span><span class="z-comment"> Permission that is revoked</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"> User who lost the permission</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"> PermissionRevoked</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">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _permission</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>;</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"> Check if user has permission</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"> Address of the user whose permission we need to check</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _requiredPermission</span><span class="z-comment"> The required permission</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 _permission is a superset of the _requiredPermission else 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"> hasPermission</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"> _requiredPermission</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> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Add permission to user</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"> Address of the user to whom we are going to add a permission</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _permissionToAdd</span><span class="z-comment"> The permission that will be added</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"> new permission with the _permissionToAdd</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"> grantPermission</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"> _permissionToAdd</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>)</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 permission from user</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"> Address of the user to whom we are going to revoke a permission</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _permissionToRevoke</span><span class="z-comment"> The permission that will be revoked</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"> new permission without the _permissionToRevoke</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"> revokePermission</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"> _permissionToRevoke</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>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li>Compliant contracts MUST implement <code>IEIP6617</code></li> <li>A permission in a compliant contract is represented as an <code>uint256</code>. A permission MUST take only one bit of an <code>uint256</code> and therefore MUST be a power of 2. Each permission MUST be unique and the <code>0</code> MUST be used for none permission.</li> </ul> <h3 id="metadata-interface">Metadata Interface</h3> <p>It is RECOMMENDED for compliant contracts to implement the optional extension <code>IEIP6617Meta</code>.</p> <ul> <li> <p>They SHOULD define a name and description for the base permissions and main combinaison.</p> </li> <li> <p>They SHOULD NOT define a description for every subcombinaison of permissions possible.</p> </li> </ul> <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"> Defined the interface of the metadata of EIP6617, MAY NOT be implemented</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"> IEIP6617Meta</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"> Structure of permission description</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _permission</span><span class="z-comment"> Permission</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"> Name of the permission</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _description</span><span class="z-comment"> Description of the permission</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"> PermissionDescription</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> permission</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> description</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"> MUST trigger when the description is updated.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _permission</span><span class="z-comment"> Permission</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"> Name of the permission</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _description</span><span class="z-comment"> Description of the permission</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"> UpdatePermissionDescription</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _permission</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _name</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _description</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"> Returns the description of a given `_permission`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _permission</span><span class="z-comment"> Permission</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"> getPermissionDescription</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _permission</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">PermissionDescription</span><span class="z-storage z-type"> memory</span><span class="z-variable"> description</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"> Return `true` if the description was set otherwise return `false`. It MUST emit `UpdatePermissionDescription` event.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _permission</span><span class="z-comment"> Permission</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"> Name of the permission</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _description</span><span class="z-comment"> Description of the permission</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"> setPermissionDescription</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _permission</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"> _name</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"> _description</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></span></code></pre><h2 id="rationale">Rationale</h2> <p>Currently permission and access control is performed using a single owner (<a href="https://wg-eips.ritovision.com/173/">ERC-173</a>) or with <code>bytes32</code> roles (<a href="https://wg-eips.ritovision.com/5982/">ERC-5982</a>). However, using bitwise and bitmask operations allows for greater gas-efficiency and flexibility.</p> <h3 id="gas-cost-efficiency">Gas cost efficiency</h3> <p>Bitwise operations are very cheap and fast. For example, doing an <code>AND</code> bitwise operation on a permission bitmask is significantly cheaper than calling any number of <code>LOAD</code> opcodes.</p> <h3 id="flexibility">Flexibility</h3> <p>With the 256 bits of the <code>uint256</code>, we can create up to 256 different permissions which leads to $2^{256}$ unique combinations (a.k.a. roles). <em>(A role is a combination of multiple permissions).</em> Not all roles have to be predefined.</p> <p>Since permissions are defined as unsigned integers, we can use the binary OR operator to create new role based on multiple permissions.</p> <h3 id="ordering-permissions-by-importance">Ordering permissions by importance</h3> <p>We can use the most significant bit to represent the most important permission, the comparison between permissions can then be done easily since they all are <code>uint256</code>s.</p> <h3 id="associate-a-meaning">Associate a meaning</h3> <p>Compared with access control managed via ERC-5982, this EIP does not provide a direct and simple understanding of the meaning of a permission or role.</p> <p>To deal with this problem, you can set up the metadata interface, which associates a name and description to each permission or role.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>First implementation could be found here:</p> <ul> <li><a href="https://wg-eips.ritovision.com/6617/./assets/contracts/EIP6617.sol">Basic ERC-6617 implementation</a></li> </ul> <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> 2023-02-24T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status Gajinder Singhhttps://github.com/g11tech Matt Garnetthttps://github.com/lightclient Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/6493/

Signature scheme for native SSZ transactions

<h2 id="abstract">Abstract</h2> <p>This EIP defines a signature scheme for native <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/ssz/simple-serialize.md">Simple Serialize (SSZ)</a> encoded transactions.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/6404/">EIP-6404</a> introduces SSZ transactions by converting from RLP transactions. Defining a signature scheme for native SSZ transactions further reduces required conversions and unlocks the forward compatibility benefits of SSZ <a href="https://wg-eips.ritovision.com/7495/"><code>ProgressiveContainer</code></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="transaction-signature-scheme">Transaction signature scheme</h3> <p>Native SSZ transactions are based on the <code>TransactionPayload</code> defined in <a href="https://wg-eips.ritovision.com/6404/">EIP-6404</a> and emit an <a href="https://wg-eips.ritovision.com/6466/">EIP-6466</a> <code>Receipt</code>. To distinguish native SSZ transactions from those converted from RLP, native SSZ transactions do not contain the RLP <code>TransactionType</code> field in their <code>TransactionPayload</code>.</p> <p>All native SSZ transactions follow a scheme 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> to compute their signing hash (<code>sig_hash</code>). Likewise, native SSZ authorizations use such a scheme to derive their signing hash (<code>auth_hash</code>).</p> <p>Additional information is mixed into <code>sig_hash</code> and <code>auth_hash</code> to uniquely identify the underlying specification and avoid hash collisions across different signature kinds. Vendor-defined networks MUST use a different <code>DomainType</code> for signing custom transaction or authorization types.</p> <table><thead><tr><th>Name</th><th>Value</th><th>Description</th></tr></thead><tbody> <tr><td><code>DOMAIN_TX_SSZ</code></td><td><code>DomainType('0x01000008')</code></td><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/specs/phase0/beacon-chain.md#custom-types"><code>DomainType</code></a> for signing native SSZ transactions compatible with this EIP</td></tr> <tr><td><code>DOMAIN_AUTH_SSZ</code></td><td><code>DomainType('0x02000008')</code></td><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/specs/phase0/beacon-chain.md#custom-types"><code>DomainType</code></a> for signing native SSZ authorizations compatible with this EIP</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"> ExecutionSigningData</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> object_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> domain_type</span><span>:</span><span> DomainType</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"> compute_ssz_sig_hash</span><span>(</span><span class="z-variable z-parameter z-function">payload</span><span>:</span><span> SszTransactionPayload</span><span>)</span><span> -&gt;</span><span> Hash32</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> Hash32</span><span>(</span><span>ExecutionSigningData</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> object_root</span><span class="z-keyword">=</span><span>payload</span><span>.</span><span>hash_tree_root</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> domain_type</span><span class="z-keyword">=</span><span class="z-constant">DOMAIN_TX_SSZ</span><span>,</span></span> <span class="giallo-l"><span> )</span><span>.</span><span>hash_tree_root</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"> compute_ssz_auth_hash</span><span>(</span><span class="z-variable z-parameter z-function">payload</span><span>:</span><span> SszAuthorizationPayload</span><span>)</span><span> -&gt;</span><span> Hash32</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> Hash32</span><span>(</span><span>ExecutionSigningData</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> object_root</span><span class="z-keyword">=</span><span>payload</span><span>.</span><span>hash_tree_root</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> domain_type</span><span class="z-keyword">=</span><span class="z-constant">DOMAIN_AUTH_SSZ</span><span>,</span></span> <span class="giallo-l"><span> )</span><span>.</span><span>hash_tree_root</span><span>(</span><span>)</span><span>)</span></span></code></pre><h3 id="native-transactions">Native transactions</h3> <p>New <a href="https://wg-eips.ritovision.com/7495/">EIP-6404</a> <code>TransactionPayload</code> definitions are introduced to represent native SSZ transactions:</p> <ul> <li><code>BasicTransactionPayload</code> and <code>CreateTransactionPayload</code> share the functionality of <a href="https://wg-eips.ritovision.com/1559/#specification">EIP-1559</a> fee market transactions</li> <li><code>BlobTransactionPayload</code> shares the functionality of <a href="https://wg-eips.ritovision.com/4844/#parameters">EIP-4844</a> blob transactions</li> <li><code>SetCodeTransactionPayload</code> shares the functionality of <a href="https://wg-eips.ritovision.com/7702/#parameters">EIP-7702</a> set code transactions; native SSZ types are introduced for authorizations</li> </ul> <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"> BasicTransactionPayload</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span> ChainId</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> max_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> gas</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> to</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> value</span><span>:</span><span> uint256</span></span> <span class="giallo-l"><span> input_</span><span>:</span><span> ProgressiveByteList</span></span> <span class="giallo-l"><span> access_list</span><span>:</span><span> ProgressiveList</span><span>[</span><span>AccessTuple</span><span>]</span></span> <span class="giallo-l"><span> max_priority_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</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"> CreateTransactionPayload</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span> ChainId</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> max_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> gas</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> value</span><span>:</span><span> uint256</span></span> <span class="giallo-l"><span> input_</span><span>:</span><span> ProgressiveByteList</span></span> <span class="giallo-l"><span> access_list</span><span>:</span><span> ProgressiveList</span><span>[</span><span>AccessTuple</span><span>]</span></span> <span class="giallo-l"><span> max_priority_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</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"> BlobTransactionPayload</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span> ChainId</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> max_fees_per_gas</span><span>:</span><span> BlobFeesPerGas</span></span> <span class="giallo-l"><span> gas</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> to</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> value</span><span>:</span><span> uint256</span></span> <span class="giallo-l"><span> input_</span><span>:</span><span> ProgressiveByteList</span></span> <span class="giallo-l"><span> access_list</span><span>:</span><span> ProgressiveList</span><span>[</span><span>AccessTuple</span><span>]</span></span> <span class="giallo-l"><span> max_priority_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> blob_versioned_hashes</span><span>:</span><span> ProgressiveList</span><span>[</span><span>VersionedHash</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"> ReplayableBasicAuthorizationPayload</span><span>(</span><span class="z-entity">ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> address</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</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"> BasicAuthorizationPayload</span><span>(</span><span class="z-entity">ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span> ChainId</span></span> <span class="giallo-l"><span> address</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</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"> SetCodeAuthorizationPayload</span><span>(</span><span class="z-entity">CompatibleUnion</span><span>(</span><span>{</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">01</span><span>:</span><span> RlpReplayableBasicAuthorizationPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">02</span><span>:</span><span> RlpBasicAuthorizationPayload</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"> [New in EIP-6493]</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">11</span><span>:</span><span> ReplayableBasicAuthorizationPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">12</span><span>:</span><span> BasicAuthorizationPayload</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span><span>)</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-storage z-type">class</span><span class="z-entity z-name"> SetCodeAuthorization</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> payload</span><span>:</span><span> SetCodeAuthorizationPayload</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span> ExecutionSignature</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"> SetCodeTransactionPayload</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span> ChainId</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> max_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> gas</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> to</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> value</span><span>:</span><span> uint256</span></span> <span class="giallo-l"><span> input_</span><span>:</span><span> ProgressiveByteList</span></span> <span class="giallo-l"><span> access_list</span><span>:</span><span> ProgressiveList</span><span>[</span><span>AccessTuple</span><span>]</span></span> <span class="giallo-l"><span> max_priority_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> authorization_list</span><span>:</span><span> ProgressiveList</span><span>[</span><span>SetCodeAuthorization</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>SszTransactionPayload</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> BasicTransactionPayload</span><span class="z-keyword"> |</span></span> <span class="giallo-l"><span> CreateTransactionPayload</span><span class="z-keyword"> |</span></span> <span class="giallo-l"><span> BlobTransactionPayload</span><span class="z-keyword"> |</span></span> <span class="giallo-l"><span> SetCodeTransactionPayload</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>SszAuthorizationPayload</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> ReplayableBasicAuthorizationPayload</span><span class="z-keyword"> |</span></span> <span class="giallo-l"><span> BasicAuthorizationPayload</span></span> <span class="giallo-l"><span>)</span></span></code></pre><h4 id="transaction-helpers">Transaction helpers</h4> <p>The helpers from <a href="https://wg-eips.ritovision.com/6404/">EIP-6404</a> are updated to support native SSZ transactions.</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"> TransactionPayload</span><span>(</span><span class="z-entity">CompatibleUnion</span><span>(</span><span>{</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">01</span><span>:</span><span> RlpLegacyReplayableBasicTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">02</span><span>:</span><span> RlpLegacyReplayableCreateTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">03</span><span>:</span><span> RlpLegacyBasicTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">04</span><span>:</span><span> RlpLegacyCreateTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">05</span><span>:</span><span> RlpAccessListBasicTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">06</span><span>:</span><span> RlpAccessListCreateTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">07</span><span>:</span><span> RlpBasicTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">08</span><span>:</span><span> RlpCreateTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">09</span><span>:</span><span> RlpBlobTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">0a</span><span>:</span><span> RlpSetCodeTransactionPayload</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"> [New in EIP-6493]</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">11</span><span>:</span><span> BasicTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">12</span><span>:</span><span> CreateTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">13</span><span>:</span><span> BlobTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">14</span><span>:</span><span> SetCodeTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> pass</span></span></code></pre><h3 id="json-rpc">JSON-RPC</h3> <table><thead><tr><th>Name</th><th>Value</th><th>Description</th></tr></thead><tbody> <tr><td><code>SSZ_TX_TYPE</code></td><td><code>TransactionType(0x1f)</code></td><td>Endpoint specific SSZ object</td></tr> </tbody></table> <p>Certain JSON-RPC endpoints such as <code>eth_getTransactionByHash</code> indicate the corresponding <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> envelope type prefix in a <code>type</code> field.</p> <p>When representing native SSZ transactions on such endpoints, <code>SSZ_TX_TYPE</code> SHOULD be indicated as their <code>type</code>. Omitting the <code>type</code> is NOT RECOMMENDED as certain client applications could confuse the omission with untyped <code>LegacyTransaction</code>.</p> <h3 id="unique-transaction-identifier">Unique transaction identifier</h3> <p>The unique RPC transaction identifier <code>tx_hash</code> for native SSZ transactions is defined to match the <a href="https://wg-eips.ritovision.com/6404/#unique-transaction-identifier">EIP-6404</a> <code>tx_root</code> value.</p> <h2 id="rationale">Rationale</h2> <p>The SSZ signature scheme reduces hashing overhead and ensures that <code>tx_hash</code> commitments are available on-chain. It also provides a flexible basis for future transaction functionality.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The new transaction signature scheme is solely used for native SSZ transactions and is representable using a unique <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> envelope type prefix (<code>SSZ_TX_TYPE</code>) different from existing RLP transactions.</p> <h2 id="security-considerations">Security Considerations</h2> <p>SSZ signatures MUST NOT collide with RLP transaction and message hashes.</p> <p>As RLP messages are hashed using keccak256, and all SSZ objects are hashed using SHA256. These two hashing algorithms are both considered cryptographically secure and are based on fundamentally different approaches, minimizing the risk of hash collision between those two hashing algorithms.</p> <p>Furthermore, RLP messages are hashed linearly across their serialization, while SSZ objects are hashed using a recursive Merkle tree. Having a different mechanism further reduces the risk of hash collisions.</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-23T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jayden Windlehttps://github.com/jaydenwindle Benny Giangbg@futureprimitive.xyz Steve Jang Druzy Downshttps://github.com/druzydowns Raymond Huynhhttps://github.com/huynhr Alanah Lamalanah@futureprimitive.xyz Wilkins Chunghttps://github.com/wwhchungwilkins@manifold.xyz Paul Sullivanhttps://github.com/sullivphpaul.sullivan@manifold.xyz Auryn Macmillanhttps://github.com/auryn-macmillan Jan-Felix Schwarzhttps://github.com/jfschwarz Anton Bukovhttps://github.com/k06a Mikhail Melnikhttps://github.com/ZumZoom Josh Weintraubhttps://github.com/jhweintraubjhweintraub@gmail.com Rob Montgomeryhttps://github.com/RobAnonrob@revest.finance vectorizedhttps://github.com/vectorized Víctor Martínezhttps://github.com/vnmrtz Adrián Pajareshttps://github.com/0xadrii https://wg-eips.ritovision.com/6551/

An interface and registry for smart contract accounts owned by non-fungible tokens

<h2 id="abstract">Abstract</h2> <p>This proposal defines a system which assigns Ethereum accounts to all non-fungible tokens. These token bound accounts allow NFTs to own assets and interact with applications, without requiring changes to existing smart contracts or infrastructure.</p> <h2 id="motivation">Motivation</h2> <p>The <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard enabled an explosion of non-fungible token applications. Some notable use cases have included breedable cats, generative artwork, and exchange liquidity positions.</p> <p>However, NFTs cannot act as agents or associate with other on-chain assets. This limitation makes it difficult to represent many real-world non-fungible assets as NFTs. For example:</p> <ul> <li>A character in a role-playing game that accumulates assets and abilities over time based on actions they have taken</li> <li>An automobile composed of many fungible and non-fungible components</li> <li>An investment portfolio composed of multiple fungible assets</li> <li>A punch pass membership card granting access to an establishment and recording a history of past interactions</li> </ul> <p>This proposal aims to give every NFT the same rights as an Ethereum user. This includes the ability to self-custody assets, execute arbitrary operations, control multiple independent accounts, and use accounts across multiple chains. By doing so, this proposal allows complex real-world assets to be represented as NFTs using a common pattern that mirrors Etherem's existing ownership model.</p> <p>This is accomplished by defining a singleton registry which assigns unique, deterministic smart contract account addresses to all existing and future NFTs. Each account is permanently bound to a single NFT, with control of the account granted to the holder of that NFT.</p> <p>The pattern defined in this proposal does not require any changes to existing NFT smart contracts. It is also compatible out of the box with nearly all existing infrastructure that supports Ethereum accounts, from on-chain protocols to off-chain indexers. Token bound accounts are compatible with every existing on-chain asset standard, and can be extended to support new asset standards created in the future.</p> <p>By giving every NFT the full capabilities of an Ethereum account, this proposal enables many novel use cases for existing and future NFTs.</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="overview">Overview</h3> <p>The system outlined in this proposal has two main components:</p> <ul> <li>A singleton registry for token bound accounts</li> <li>A common interface for token bound account implementations</li> </ul> <p>The following diagram illustrates the relationship between NFTs, NFT holders, token bound accounts, and the Registry: <img src="https://wg-eips.ritovision.com/6551/./assets/diagram.png" alt="" /></p> <h3 id="registry">Registry</h3> <p>The registry is a singleton contract that serves as the entry point for all token bound account address queries. It has two functions:</p> <ul> <li><code>createAccount</code> - creates the token bound account for an NFT given an <code>implementation</code> address</li> <li><code>account</code> - computes the token bound account address for an NFT given an <code>implementation</code> address</li> </ul> <p>The registry is permissionless, immutable, and has no owner. The complete source code for the registry can be found in the <a href="https://wg-eips.ritovision.com/6551/#registry-implementation">Registry Implementation</a> section. The registry MUST be deployed at address <code>0x000000006551c19487814612e58FE06813775758</code> using Nick's Factory (<code>0x4e59b44847b379578588920cA78FbF26c0B4956C</code>) with salt <code>0x0000000000000000000000000000000000000000fd8eb4e1dca713016c518e31</code>.</p> <p>The registry can be deployed to any EVM-compatible chain using the following transaction:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> &quot;to&quot;: &quot;0x4e59b44847b379578588920ca78fbf26c0b4956c&quot;,</span></span> <span class="giallo-l"><span> &quot;value&quot;: &quot;0x0&quot;,</span></span> <span class="giallo-l"><span> &quot;data&quot;: &quot;0x0000000000000000000000000000000000000000fd8eb4e1dca713016c518e31608060405234801561001057600080fd5b5061023b806100206000396000f3fe608060405234801561001057600080fd5b50600436106100365760003560e01c8063246a00211461003b5780638a54c52f1461006a575b600080fd5b61004e6100493660046101b7565b61007d565b6040516001600160a01b03909116815260200160405180910390f35b61004e6100783660046101b7565b6100e1565b600060806024608c376e5af43d82803e903d91602b57fd5bf3606c5285605d52733d60ad80600a3d3981f3363d3d373d3d3d363d7360495260ff60005360b76055206035523060601b60015284601552605560002060601b60601c60005260206000f35b600060806024608c376e5af43d82803e903d91602b57fd5bf3606c5285605d52733d60ad80600a3d3981f3363d3d373d3d3d363d7360495260ff60005360b76055206035523060601b600152846015526055600020803b61018b578560b760556000f580610157576320188a596000526004601cfd5b80606c52508284887f79f19b3655ee38b1ce526556b7731a20c8f218fbda4a3990b6cc4172fdf887226060606ca46020606cf35b8060601b60601c60005260206000f35b80356001600160a01b03811681146101b257600080fd5b919050565b600080600080600060a086880312156101cf57600080fd5b6101d88661019b565b945060208601359350604086013592506101f46060870161019b565b94979396509194608001359291505056fea2646970667358221220ea2fe53af507453c64dd7c1db05549fa47a298dfb825d6d11e1689856135f16764736f6c63430008110033&quot;,</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The registry MUST deploy each token bound account as an <a href="https://wg-eips.ritovision.com/1167/">ERC-1167</a> minimal proxy with immutable constant data appended to the bytecode.</p> <p>The deployed bytecode of each token bound account MUST have the following structure:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>ERC-1167 Header (10 bytes)</span></span> <span class="giallo-l"><span>&lt;implementation (address)&gt; (20 bytes)</span></span> <span class="giallo-l"><span>ERC-1167 Footer (15 bytes)</span></span> <span class="giallo-l"><span>&lt;salt (bytes32)&gt; (32 bytes)</span></span> <span class="giallo-l"><span>&lt;chainId (uint256)&gt; (32 bytes)</span></span> <span class="giallo-l"><span>&lt;tokenContract (address)&gt; (32 bytes)</span></span> <span class="giallo-l"><span>&lt;tokenId (uint256)&gt; (32 bytes)</span></span></code></pre> <p>For example, the token bound account with implementation address <code>0xbebebebebebebebebebebebebebebebebebebebe</code>, salt <code>0</code>, chain ID <code>1</code>, token contract <code>0xcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcf</code> and token ID <code>123</code> would have the following deployed bytecode:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>363d3d373d3d3d363d73bebebebebebebebebebebebebebebebebebebebe5af43d82803e903d91602b57fd5bf300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000cfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcfcf000000000000000000000000000000000000000000000000000000000000007b</span></span></code></pre> <p>Each token bound account proxy MUST delegate execution to a contract that implements the <code>IERC6551Account</code> interface.</p> <p>The registry MUST deploy all token bound accounts using the <code>create2</code> opcode so that each account address is deterministic. Each token bound account address SHALL be derived from the unique combination of its implementation address, token contract address, token ID, chain ID, and salt.</p> <p>The registry 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"> IERC6551Registry</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"> The registry MUST emit the ERC6551AccountCreated event upon successful account creation.</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"> ERC6551AccountCreated</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"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> implementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> chainId</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"> tokenContract</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">@dev</span><span class="z-comment"> The registry MUST revert with AccountCreationFailed error if the create2 operation fails.</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"> AccountCreationFailed</span><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">@dev</span><span class="z-comment"> Creates a token bound account for a non-fungible token.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * If account has already been created, returns the account address without calling create2.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits ERC6551AccountCreated event.</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"> account</span><span class="z-comment"> The address of the token bound account</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"> createAccount</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> implementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> chainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</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 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">address</span><span class="z-variable"> account</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 computed token bound account address for a non-fungible token.</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"> account</span><span class="z-comment"> The address of the token bound account</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"> account</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> implementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> chainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</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 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">address</span><span class="z-variable"> account</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="account-interface">Account Interface</h3> <p>All token bound accounts SHOULD be created via the singleton registry.</p> <p>All token bound account implementations MUST implement <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface detection.</p> <p>All token bound account implementations MUST implement <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> signature validation.</p> <p>All token bound account implementations 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-storage z-type"> @dev</span><span class="z-comment"> the ERC-165 identifier for this interface is `0x6faff5f1`</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6551Account</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"> Allows the account to receive Ether.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Accounts MUST implement a `receive` function.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Accounts MAY perform arbitrary logic to restrict conditions</span></span> <span class="giallo-l"><span class="z-comment"> * under which Ether can be received.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></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> <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 identifier of the non-fungible token which owns the account.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * The return value of this function MUST be constant - it MUST NOT change over 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">@return</span><span class="z-variable z-other"> chainId</span><span class="z-comment"> The chain ID of the chain the token exists on</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"> tokenContract</span><span class="z-comment"> The contract address 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"> The ID of 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"> token</span><span>(</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"> chainId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> tokenContract</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns a value that SHOULD be modified each time the account changes state.</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"> The</span><span class="z-comment"> current account state</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"> state</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">@dev</span><span class="z-comment"> Returns a magic value indicating whether a given signer is authorized to act on behalf</span></span> <span class="giallo-l"><span class="z-comment"> * of the account.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return the bytes4 magic value 0x523e3260 if the given signer is valid.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * By default, the holder of the non-fungible token the account is bound to MUST be considered</span></span> <span class="giallo-l"><span class="z-comment"> * a valid signer.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Accounts MAY implement additional authorization logic which invalidates the holder as a</span></span> <span class="giallo-l"><span class="z-comment"> * signer or grants signing permissions to other non-holder accounts.</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"> signer</span><span class="z-comment"> The address to check signing authorization 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"> context</span><span class="z-comment"> Additional data used to determine whether the signer is valid</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"> magicValue</span><span class="z-comment"> Magic value indicating whether the signer is valid</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"> isValidSigner</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"> context</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">bytes4</span><span class="z-variable"> magicValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h3 id="execution-interface">Execution Interface</h3> <p>All token bound accounts MUST implement an execution interface which allows valid signers to execute arbitrary operations on behalf of the account. Support for an execution interface MUST be signaled by the account using ERC-165 interface detection.</p> <p>Token bound accounts MAY support the following execution interface:</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 ERC-165 identifier for this interface is `0x51945447`</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6551Executable</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"> Executes a low-level operation if the caller is a valid signer on the account.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Reverts and bubbles up error if operation fails.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Accounts implementing this interface MUST accept the following operation parameter values:</span></span> <span class="giallo-l"><span class="z-comment"> * - 0 = CALL</span></span> <span class="giallo-l"><span class="z-comment"> * - 1 = DELEGATECALL</span></span> <span class="giallo-l"><span class="z-comment"> * - 2 = CREATE</span></span> <span class="giallo-l"><span class="z-comment"> * - 3 = CREATE2</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Accounts implementing this interface MAY support additional operations or restrict a signer&#39;s</span></span> <span class="giallo-l"><span class="z-comment"> * ability to execute certain operations.</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"> to</span><span class="z-comment"> The target address of the 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"> value</span><span class="z-comment"> The Ether value to be sent to the target</span></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 encoded operation calldata</span></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"> A value indicating the type of operation to perform</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"> result of the operation</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-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-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> data</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> operation</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 class="giallo-l"><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>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="singleton-registry">Singleton Registry</h3> <p>This proposal specifies a single, canonical registry that can be permissionlessly deployed to any chain at a known address. It purposefully does not specify a common interface that can be implemented by multiple registry contracts. This approach enables several critical properties.</p> <h4 id="counterfactual-accounts">Counterfactual Accounts</h4> <p>All token bound accounts are created using the create2 opcode, enabling accounts to exist in a counterfactual state prior to their creation. This allows token bound accounts to receive assets prior to contract creation. A singleton account registry ensures a common addressing scheme is used for all token bound account addresses.</p> <h4 id="trustless-deployments">Trustless Deployments</h4> <p>A single ownerless registry ensures that the only trusted contract for any token bound account is the implementation. This guarantees the holder of a token access to all assets stored within a counterfactual account using a trusted implementation.</p> <p>Without a canonical registry, some token bound accounts may be deployed using an owned or upgradable registry. This may lead to loss of assets stored in counterfactual accounts, and increases the scope of the security model that applications supporting this proposal must consider.</p> <h4 id="cross-chain-compatibility">Cross-chain Compatibility</h4> <p>A singleton registry with a known address enables each token bound account to exist on multiple chains. The inclusion of <code>chainId</code> as a parameter to <code>createAccount</code> allows the contract for a token bound account to be deployed at the same address on any supported chain. Account implementations are therefore able to support cross-chain account execution, where an NFT on one chain can control its token bound account on another chain.</p> <h4 id="single-entry-point">Single Entry Point</h4> <p>A single entry point for querying account addresses and <code>AccountCreated</code> events simplifies the complex task of indexing token bound accounts in applications which support this proposal.</p> <h4 id="implementation-diversity">Implementation Diversity</h4> <p>A singleton registry allows diverse account implementations to share a common addressing scheme. This gives developers significant freedom to implement both account-specific features (e.g. delegation) as well as alternative account models (e.g. ephemeral accounts) in a way that can be easily supported by client applications.</p> <h3 id="registry-vs-factory">Registry vs Factory</h3> <p>The term "registry" was chosen instead of "factory" to highlight the canonical nature of the contract and emphasize the act of querying account addresses (which occurs regularly) over the creation of accounts (which occurs only once per account).</p> <h3 id="variable-execution-interface">Variable Execution Interface</h3> <p>This proposal does not require accounts to implement a specific execution interface in order to be compatible, so long as they signal support for at least one execution interface via ERC-165 interface detection. Allowing account developers to choose their own execution interface allows this proposal to support the wide variety of existing execution interfaces and maintain forward compatibility with likely future standardized interfaces.</p> <h3 id="account-ambiguity">Account Ambiguity</h3> <p>The specification proposed above allows NFTs to have multiple token bound accounts. During the development of this proposal, alternative architectures were considered which would have assigned a single token bound account to each NFT, making each token bound account address an unambiguous identifier.</p> <p>However, these alternatives present several trade offs.</p> <p>First, due to the permissionless nature of smart contracts, it is impossible to enforce a limit of one token bound account per NFT. Anyone wishing to utilize multiple token bound accounts per NFT could do so by deploying an additional registry contract.</p> <p>Second, limiting each NFT to a single token bound account would require a static, trusted account implementation to be included in this proposal. This implementation would inevitably impose specific constraints on the capabilities of token bound accounts. Given the number of unexplored use cases this proposal enables and the benefit that diverse account implementations could bring to the non-fungible token ecosystem, it is the authors' opinion that defining a canonical and constrained implementation in this proposal is premature.</p> <p>Finally, this proposal seeks to grant NFTs the ability to act as agents on-chain. In current practice, on-chain agents often utilize multiple accounts. A common example is individuals who use a "hot" account for daily use and a "cold" account for storing valuables. If on-chain agents commonly use multiple accounts, it stands to reason that NFTs ought to inherit the same ability.</p> <h3 id="proxy-implementation">Proxy Implementation</h3> <p>ERC-1167 minimal proxies are well supported by existing infrastructure and are a common smart contract pattern. This proposal deploys each token bound account using a custom ERC-1167 proxy implementation that stores the salt, chain id, token contract address, and token ID as ABI-encoded constant data appended to the contract bytecode. This allows token bound account implementations to easily query this data while ensuring it remains constant. This approach was taken to maximize compatibility with existing infrastructure while also giving smart contract developers full flexibility when creating custom token bound account implementations.</p> <h3 id="chain-identifier">Chain Identifier</h3> <p>This proposal uses the chain ID to identify each NFT along with its contract address and token ID. Token identifiers are globally unique on a single Ethereum chain, but may not be unique across multiple Ethereum chains.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal seeks to be maximally backwards compatible with existing non-fungible token contracts. As such, it does not extend the ERC-721 standard.</p> <p>Additionally, this proposal does not require the registry to perform an ERC-165 interface check for ERC-721 compatibility prior to account creation. This maximizes compatibility with non-fungible token contracts that pre-date the ERC-721 standard (such as CryptoKitties) or only implement a subset of the ERC-721 interface (such as ENS NameWrapper names). It also allows the system described in this proposal to be used with semi-fungible or fungible tokens, although these use cases are outside the scope of the proposal.</p> <p>Smart contract authors may optionally choose to enforce interface detection for ERC-721 in their account implementations.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="example-account-implementation">Example Account Implementation</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-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;@openzeppelin/contracts/token/ERC721/IERC721.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/interfaces/IERC1271.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/SignatureChecker.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"> IERC6551Account</span><span> {</span></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> <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> <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"> chainId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> tokenContract</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-storage z-type"> function</span><span class="z-entity z-name"> state</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"> isValidSigner</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"> context</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">bytes4</span><span class="z-variable"> magicValue</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"> IERC6551Executable</span><span> {</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-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-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> data</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> operation</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 class="giallo-l"><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>}</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"> ERC6551Account</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span>, </span><span class="z-entity z-name">IERC1271</span><span>, </span><span class="z-entity z-name">IERC6551Account</span><span>, </span><span class="z-entity z-name">IERC6551Executable</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> immutable</span><span> deploymentChainId </span><span class="z-keyword">=</span><span class="z-variable z-language"> block</span><span>.</span><span>chainid</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> state</span><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></span> <span class="giallo-l"></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-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-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> data</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> operation</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 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">bytes</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> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_isValidSigner</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span>,</span><span class="z-string"> &quot;Invalid signer&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>operation </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Only call operations are supported&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>state</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bool</span><span> success</span><span>;</span></span> <span class="giallo-l"><span> (</span><span>success</span><span>,</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span> to</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span> value</span><span>}</span><span>(</span><span>data</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>success</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-keyword"> revert</span><span>(</span><span class="z-entity z-name">add</span><span>(</span><span>result</span><span>,</span><span class="z-constant"> 32</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>result</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"> isValidSigner</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>)</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">bytes4</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-entity z-name">_isValidSigner</span><span>(</span><span>signer</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> IERC6551Account</span><span>.</span><span>isValidSigner</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-keyword"> return</span><span class="z-support"> bytes4</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"> isValidSignature</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> hash</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> <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"> virtual</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes4</span><span class="z-variable"> magicValue</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isValid </span><span class="z-keyword">=</span><span> SignatureChecker</span><span>.</span><span class="z-entity z-name">isValidSignatureNow</span><span>(</span><span class="z-entity z-name">owner</span><span>(</span><span>)</span><span>,</span><span> hash</span><span>,</span><span> signature</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>isValid</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> IERC1271</span><span>.</span><span>isValidSignature</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-keyword"> return</span><span class="z-support"> bytes4</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"> 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"> pure</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-keyword"> return</span><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 class="giallo-l"><span class="z-keyword"> ||</span><span> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC6551Account</span><span>)</span><span>.</span><span>interfaceId</span></span> <span class="giallo-l"><span class="z-keyword"> ||</span><span> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC6551Executable</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"> 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-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>,</span><span class="z-support"> address</span><span>,</span><span class="z-support"> uint256</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> footer </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> bytes</span><span>(</span><span class="z-constant">0x60</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> extcodecopy</span><span>(</span><span class="z-support">address</span><span>(</span><span>)</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>footer</span><span>,</span><span class="z-constant"> 0x20</span><span>)</span><span>,</span><span class="z-constant"> 0x4d</span><span>,</span><span class="z-constant"> 0x60</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 class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>footer</span><span>,</span><span> (</span><span class="z-support">uint256</span><span>,</span><span class="z-support"> address</span><span>,</span><span class="z-support"> uint256</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"> owner</span><span>(</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">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> (</span><span class="z-support">uint256</span><span> chainId</span><span>,</span><span class="z-support"> address</span><span> tokenContract</span><span>,</span><span class="z-support"> uint256</span><span> tokenId</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> token</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>chainId </span><span class="z-keyword">!=</span><span> deploymentChainId</span><span>)</span><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 class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> IERC721</span><span>(</span><span>tokenContract</span><span>)</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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _isValidSigner</span><span>(</span><span class="z-support">address</span><span class="z-variable"> signer</span><span>)</span><span class="z-storage z-type"> internal</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-keyword"> return</span><span> signer </span><span class="z-keyword">==</span><span class="z-entity z-name"> owner</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="registry-implementation">Registry Implementation</h3> <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 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-storage z-type">interface</span><span class="z-entity z-name"> IERC6551Registry</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"> The registry MUST emit the ERC6551AccountCreated event upon successful account creation.</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"> ERC6551AccountCreated</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"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> implementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> chainId</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"> tokenContract</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">@dev</span><span class="z-comment"> The registry MUST revert with AccountCreationFailed error if the create2 operation fails.</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"> AccountCreationFailed</span><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">@dev</span><span class="z-comment"> Creates a token bound account for a non-fungible token.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * If account has already been created, returns the account address without calling create2.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits ERC6551AccountCreated event.</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"> account</span><span class="z-comment"> The address of the token bound account</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"> createAccount</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> implementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> chainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</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 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">address</span><span class="z-variable"> account</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 computed token bound account address for a non-fungible token.</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"> account</span><span class="z-comment"> The address of the token bound account</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"> account</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> implementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> chainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</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 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">address</span><span class="z-variable"> account</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"> ERC6551Registry</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6551Registry</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createAccount</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> implementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> chainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</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 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">address</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-comment"> //</span><span class="z-comment"> Memory Layout:</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"> //</span><span class="z-comment"> 0x00 0xff (1 byte)</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 0x01 registry (address) (20 bytes)</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 0x15 salt (bytes32) (32 bytes)</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 0x35 Bytecode Hash (bytes32) (32 bytes)</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"> //</span><span class="z-comment"> 0x55 ERC-1167 Constructor + Header (20 bytes)</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 0x69 implementation (address) (20 bytes)</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 0x5D ERC-1167 Footer (15 bytes)</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 0x8C salt (uint256) (32 bytes)</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 0xAC chainId (uint256) (32 bytes)</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 0xCC tokenContract (address) (32 bytes)</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 0xEC tokenId (uint256) (32 bytes)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Silence unused variable warnings</span></span> <span class="giallo-l"><span class="z-entity z-name"> pop</span><span>(</span><span>chainId</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Copy bytecode + constant data to memory</span></span> <span class="giallo-l"><span class="z-entity z-name"> calldatacopy</span><span>(</span><span class="z-constant">0x8c</span><span>,</span><span class="z-constant"> 0x24</span><span>,</span><span class="z-constant"> 0x80</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> salt, chainId, tokenContract, tokenId</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x6c</span><span>,</span><span class="z-constant"> 0x5af43d82803e903d91602b57fd5bf3</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> ERC-1167 footer</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x5d</span><span>,</span><span> implementation</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> implementation</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x49</span><span>,</span><span class="z-constant"> 0x3d60ad80600a3d3981f3363d3d373d3d3d363d73</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> ERC-1167 constructor + header</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Copy create2 computation data to memory</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x35</span><span>,</span><span class="z-support"> keccak256</span><span>(</span><span class="z-constant">0x55</span><span>,</span><span class="z-constant"> 0xb7</span><span>)</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> keccak256(bytecode)</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x15</span><span>,</span><span> salt</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> salt</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x01</span><span>,</span><span class="z-entity z-name"> shl</span><span>(</span><span class="z-constant">96</span><span>,</span><span class="z-support"> address</span><span>(</span><span>)</span><span>)</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> registry address</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore8</span><span>(</span><span class="z-constant">0x00</span><span>,</span><span class="z-constant"> 0xff</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> 0xFF</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Compute account address</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> computed </span><span class="z-keyword">:=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-constant">0x00</span><span>,</span><span class="z-constant"> 0x55</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If the account has not yet been deployed</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">extcodesize</span><span>(</span><span>computed</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Deploy account contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> deployed </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-constant"> 0x55</span><span>,</span><span class="z-constant"> 0xb7</span><span>,</span><span> salt</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Revert if the deployment fails</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-entity z-name"> iszero</span><span>(</span><span>deployed</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x00</span><span>,</span><span class="z-constant"> 0x20188a59</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> `AccountCreationFailed()`</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span class="z-constant">0x1c</span><span>,</span><span class="z-constant"> 0x04</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"> Store account address in memory before salt and chainId</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x6c</span><span>,</span><span> deployed</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Emit the ERC6551AccountCreated event</span></span> <span class="giallo-l"><span class="z-entity z-name"> log4</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> 0x6c</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 0x60</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> `ERC6551AccountCreated(address,address,bytes32,uint256,address,uint256)`</span></span> <span class="giallo-l"><span class="z-constant"> 0x79f19b3655ee38b1ce526556b7731a20c8f218fbda4a3990b6cc4172fdf88722</span><span>,</span></span> <span class="giallo-l"><span> implementation</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 class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Return the account address</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span>(</span><span class="z-constant">0x6c</span><span>,</span><span class="z-constant"> 0x20</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"> Otherwise, return the computed account address</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x00</span><span>,</span><span class="z-entity z-name"> shr</span><span>(</span><span class="z-constant">96</span><span>,</span><span class="z-entity z-name"> shl</span><span>(</span><span class="z-constant">96</span><span>,</span><span> computed</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span>(</span><span class="z-constant">0x00</span><span>,</span><span class="z-constant"> 0x20</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"> account</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> implementation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> chainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</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 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">address</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-comment"> //</span><span class="z-comment"> Silence unused variable warnings</span></span> <span class="giallo-l"><span class="z-entity z-name"> pop</span><span>(</span><span>chainId</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> pop</span><span>(</span><span>tokenContract</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> pop</span><span>(</span><span>tokenId</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Copy bytecode + constant data to memory</span></span> <span class="giallo-l"><span class="z-entity z-name"> calldatacopy</span><span>(</span><span class="z-constant">0x8c</span><span>,</span><span class="z-constant"> 0x24</span><span>,</span><span class="z-constant"> 0x80</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> salt, chainId, tokenContract, tokenId</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x6c</span><span>,</span><span class="z-constant"> 0x5af43d82803e903d91602b57fd5bf3</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> ERC-1167 footer</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x5d</span><span>,</span><span> implementation</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> implementation</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x49</span><span>,</span><span class="z-constant"> 0x3d60ad80600a3d3981f3363d3d373d3d3d363d73</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> ERC-1167 constructor + header</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Copy create2 computation data to memory</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x35</span><span>,</span><span class="z-support"> keccak256</span><span>(</span><span class="z-constant">0x55</span><span>,</span><span class="z-constant"> 0xb7</span><span>)</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> keccak256(bytecode)</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x15</span><span>,</span><span> salt</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> salt</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x01</span><span>,</span><span class="z-entity z-name"> shl</span><span>(</span><span class="z-constant">96</span><span>,</span><span class="z-support"> address</span><span>(</span><span>)</span><span>)</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> registry address</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore8</span><span>(</span><span class="z-constant">0x00</span><span>,</span><span class="z-constant"> 0xff</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> 0xFF</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Store computed account address in memory</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">0x00</span><span>,</span><span class="z-entity z-name"> shr</span><span>(</span><span class="z-constant">96</span><span>,</span><span class="z-entity z-name"> shl</span><span>(</span><span class="z-constant">96</span><span>,</span><span class="z-support"> keccak256</span><span>(</span><span class="z-constant">0x00</span><span>,</span><span class="z-constant"> 0x55</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-comment"> Return computed account address</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span>(</span><span class="z-constant">0x00</span><span>,</span><span class="z-constant"> 0x20</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="fraud-prevention">Fraud Prevention</h3> <p>In order to enable trustless sales of token bound accounts, decentralized marketplaces will need to implement safeguards against fraudulent behavior by malicious account owners.</p> <p>Consider the following potential scam:</p> <ul> <li>Alice owns an ERC-721 token X, which owns token bound account Y.</li> <li>Alice deposits 10ETH into account Y</li> <li>Bob offers to purchase token X for 11ETH via a decentralized marketplace, assuming he will receive the 10ETH stored in account Y along with the token</li> <li>Alice withdraws 10ETH from the token bound account, and immediately accepts Bob's offer</li> <li>Bob receives token X, but account Y is empty</li> </ul> <p>To mitigate fraudulent behavior by malicious account owners, decentralized marketplaces SHOULD implement protection against these sorts of scams at the marketplace level. Contracts which implement this EIP MAY also implement certain protections against fraudulent behavior.</p> <p>Here are a few mitigations strategies to be considered:</p> <ul> <li>Attach the current token bound account state to the marketplace order. If the state of the account has changed since the order was placed, consider the offer void. This functionality would need to be supported at the marketplace level.</li> <li>Attach a list of asset commitments to the marketplace order that are expected to remain in the token bound account when the order is fulfilled. If any of the committed assets have been removed from the account since the order was placed, consider the offer void. This would also need to be implemented by the marketplace.</li> <li>Submit the order to the decentralized market via an external smart contract which performs the above logic before validating the order signature. This allows for safe transfers to be implemented without marketplace support.</li> <li>Implement a locking mechanism on the token bound account implementation that prevents malicious owners from extracting assets from the account while locked</li> </ul> <p>Preventing fraud is outside the scope of this proposal.</p> <h3 id="ownership-cycles">Ownership Cycles</h3> <p>All assets held in a token bound account may be rendered inaccessible if an ownership cycle is created. The simplest example is the case of an ERC-721 token being transferred to its own token bound account. If this occurs, both the ERC-721 token and all of the assets stored in the token bound account would be permanently inaccessible, since the token bound account is incapable of executing a transaction which transfers the ERC-721 token.</p> <p>Ownership cycles can be introduced in any graph of n&gt;0 token bound accounts. On-chain prevention of cycles with depth&gt;1 is difficult to enforce given the infinite search space required, and as such is outside the scope of this proposal. Application clients and account implementations wishing to adopt this proposal are encouraged to implement measures that limit the possibility of ownership cycles.</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-21T00:00:00+00:00 2026-02-11T14:48:25+00:00 RE:DREAMER Labdev@redreamer.io Archie Changhttps://github.com/ArchieR7archie@redreamer.io Kai Yuhttps://github.com/chihkaiyukai@redreamer.io Yonathan Randyantohttps://github.com/Randyantorandy@redreamer.io Boyu Chuhttps://github.com/chuboyuboyu@redreamer.io Boxi Lihttps://github.com/boxi79boxi@redreamer.io Jason Chenghttps://github.com/JasonCheng0729jason@redreamer.io https://wg-eips.ritovision.com/6672/

An extension of ERC-721 which enables an NFT to be redeemed in multiple scenarios for either a physical or digital object

<h2 id="abstract">Abstract</h2> <p>This EIP proposes an extension to the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard for Non-Fungible Tokens (NFTs) to enable multi-redeemable NFTs. Redemption provides a means for NFT holders to demonstrate ownership and eligibility of their NFT, which in turn enables them to receive a physical or digital item. This extension would allow an NFT to be redeemed in multiple scenarios and maintain a record of its redemption status on the blockchain.</p> <h2 id="motivation">Motivation</h2> <p>The motivation behind our proposed NFT standard is to provide a more versatile and flexible solution compared to existing standards, allowing for multi-redeemable NFTs. Our proposed NFT standard enables multi-redeemable NFTs, allowing them to be redeemed in multiple scenarios for different campaigns or events, thus unlocking new possibilities for commerce use cases and breaking the limitation of one-time redemption per NFT.</p> <p>One use case for an NFT that can be redeemed multiple times in various scenarios is a digital concert ticket. The NFT could be redeemed for access to the online concert and then again for exclusive merchandise, a meet and greet with the artist, or any exclusive commerce status that is bound to the NFT. Each redemption could represent a unique experience or benefit for the NFT holder.</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="redeem-and-cancel-functions">Redeem and Cancel Functions</h3> <p>An operator SHALL only make an update to the redemption created by itself. Therefore, the <code>redeem()</code> and <code>cancel()</code> functions do not have an <code>_operator</code> parameter, and the <code>msg.sender</code> address MUST be used as the <code>_operator</code>.</p> <h3 id="redemption-flag-key-value-pairs">Redemption Flag Key-Value Pairs</h3> <p>The combination of <code>_operator</code>, <code>_tokenId</code>, and <code>_redemptionId</code> MUST be used as the key in the redemption flag key-value pairs, whose value can be accessed from the <code>isRedeemed()</code> function.</p> <p><strong>Every contract compliant with this EIP MUST implement <code>ERC6672</code> and <code>ERC721</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.16</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-6672 Multi-Redeemable NFT 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-6672</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 0x4dddf83f.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6672</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 class="z-storage z-type"> @dev</span><span class="z-comment"> This event emits when an NFT 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> <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"> address</span><span class="z-variable"> redeemer</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> _redemptionId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> _memo</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 event emits when a redemption is canceled.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Cancel</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"> bytes32</span><span class="z-variable"> _redemptionId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> _memo</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"> Check whether an NFT is already used for redemption or not.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</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"> _operator</span><span class="z-comment"> The address of the operator of the redemption platform.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _redemptionId</span><span class="z-comment"> The identifier for a redemption.</span></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"> Whether</span><span class="z-comment"> an NFT is already redeemed or not.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isRedeemed</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"> _redemptionId</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"> List the redemptions created by the given operator for the given NFT.</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-storage z-type"> @param</span><span class="z-variable z-other"> _operator</span><span class="z-comment"> The address of the operator of the redemption platform.</span></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"> List</span><span class="z-comment"> of redemptions of speficic `_operator` and `_tokenId`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getRedemptionIds</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"> 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">bytes32</span><span>[</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-storage z-type"> @notice</span><span class="z-comment"> Redeem an NFT</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-storage z-type"> @param</span><span class="z-variable z-other"> _redemptionId</span><span class="z-comment"> The identifier created by the operator for a redemption.</span></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 redeem.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _memo</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">bytes32</span><span class="z-variable z-parameter z-function"> _redemptionId</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"> string</span><span class="z-variable z-parameter z-function"> _memo</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"> Cancel a redemption</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-storage z-type"> @param</span><span class="z-variable z-other"> _redemptionId</span><span class="z-comment"> The redemption to cancel.</span></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 redemption.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _memo</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> cancel</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _redemptionId</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"> string</span><span class="z-variable z-parameter z-function"> _memo</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="metadata-extension">Metadata Extension</h3> <p>The key format for the <code>redemptions</code> key-value pairs MUST be standardized as <code>operator-tokenId-redemptionId</code>, where <code>operator</code> is the operator wallet address, <code>tokenId</code> is the identifier of the token that has been redeemed, and <code>redemptionId</code> is the redemption identifier. The value of the key <code>operator-tokenId-redemptionId</code> is an object that contains the <code>status</code> and <code>description</code> of the redemption.</p> <ul> <li> <p>Redemption status, i.e. <code>status</code></p> <p>The redemption status can have a more granular level, rather than just being a flag with a <code>true</code> or <code>false</code> value. For instance, in cases of physical goods redemption, we may require the redemption status to be either <code>redeemed</code>, <code>paid</code>, or <code>shipping</code>. It is RECOMMENDED to use a string enum that is comprehensible by both the operator and the marketplace or any other parties that want to exhibit the status of the redemption.</p> </li> <li> <p>Description of the redemption, i.e. <code>description</code></p> <p>The <code>description</code> SHOULD be used to provide more details about the redemption, such as information about the concert ticket, a detailed description of the action figures, and more.</p> </li> </ul> <p>The <strong>metadata extension</strong> is OPTIONAL for <a href="https://wg-eips.ritovision.com/6672/">ERC-6672</a> smart contracts (see "caveats", below). This allows your smart contract to be interrogated for its name and for details about the assets which your NFTs 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-6672 Multi-Redeemable 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://eips.ethereum.org/EIPS/eip-6672</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6672Metadata</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC721Metadata </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 distinct Uniform Resource Identifier (URI) for a given asset.</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. URIs are defined in RFC</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 3986. The URI may point to a JSON file that conforms to the &quot;ERC-6672</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Metadata JSON Schema&quot;.</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 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">string</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This is the "<a href="https://wg-eips.ritovision.com/6672/">ERC-6672</a> 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">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 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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">redemptions</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">operator-tokenId-redemptionId</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">status</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 status of a redemption. Enum type can be used to represent the redemption status, such as redeemed, shipping, paid.</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 object that has been redeemed for an NFT, such as the name of an action figure series name or the color of the product.</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> <h3 id="key-choices-for-redemption-flag-and-status">Key Choices for Redemption Flag and Status</h3> <p>The combination of <code>_operator</code>, <code>_tokenId</code>, and <code>_redemptionId</code> is chosen as the key because it provides a clear and unique identifier for each redemption transaction.</p> <ul> <li> <p>Operator wallet address, i.e. <code>_operator</code></p> <p>It's possible that there are more than one party who would like to use the same NFT for redemption. For example, MisterPunks NFTs are eligible to be redeemed for both Event-X and Event-Y tickets, and each event's ticket redemption is handled by a different operator.</p> </li> <li> <p>Token identifier, i.e. <code>_tokenId</code></p> <p>Each NFT holder will have different redemption records created by the same operator. Therefore, it's important to use token identifier as one of the keys.</p> </li> <li> <p>Redemption identifier, i.e. <code>_redemptionId</code></p> <p>Using <code>_redemptionId</code> as one of the keys enables NFT holders to redeem the same NFT to the same operator in multiple campaigns. For example, Operator-X has 2 campaigns, i.e. campaign A and campaign B, and both campaigns allow for MisterPunks NFTs to be redeemed for physical action figures. Holder of MisterPunk #7 is eligible for redemption in both campaigns and each redemption is recorded with the same <code>_operator</code> and <code>_tokenId</code>, but with different <code>_redemptionId</code>.</p> </li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation of Multi-Redeemable NFT can be found <a href="https://wg-eips.ritovision.com/6672/./assets/contracts/ERC6672.sol">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>An incorrect implementation of <a href="https://wg-eips.ritovision.com/6672/">ERC-6672</a> could potentially allow an unauthorized operator to access redemption flags owned by other operators, creating a security risk. As a result, an unauthorized operator could cancel the redemption process managed by other operators. Therefore, it is crucial for <a href="https://wg-eips.ritovision.com/6672/">ERC-6672</a> implementations to ensure that only the operator who created the redemption, identified using <code>msg.sender</code>, can update the redemption flag using the <code>redeem()</code> and <code>cancel()</code> functions. It is also recommended to isolate the <code>redeem()</code> and <code>cancel()</code> functions from <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> approval models.</p> <p>This <a href="https://wg-eips.ritovision.com/6672/">ERC-6672</a> token is compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, so wallets and smart contracts capable of storing and handling standard <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens will not face the risk of asset loss caused by incompatible standard 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> 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-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ivo Georgievhttps://github.com/Ivshti Agustin Aguilarhttps://github.com/Agusx1211 https://wg-eips.ritovision.com/6492/

A way to verify a signature when the account is a smart contract that has not been deployed yet

<h2 id="abstract">Abstract</h2> <p>Contracts can sign verifiable messages via <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>.</p> <p>However, if the contract is not deployed yet, <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> verification is impossible, as you can't call the <code>isValidSignature</code> function on said contract.</p> <p>We propose a standard way for any contract or off-chain actor to verify whether a signature on behalf of a given counterfactual contract (that is not deployed yet) is valid. This standard way extends <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>.</p> <h2 id="motivation">Motivation</h2> <p>With the rising popularity of account abstraction, we often find that the best user experience for contract wallets is to defer contract deployment until the first user transaction, therefore not burdening the user with an additional deploy step before they can use their account. However, at the same time, many dApps expect signatures, not only for interactions, but also just for logging in.</p> <p>As such, contract wallets have been limited in their ability to sign messages before their de-facto deployment, which is often done on the first transaction.</p> <p>Furthermore, not being able to sign messages from counterfactual contracts has always been a limitation of <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>.</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 "validation" and "verification" are used interchangeably.</p> <p>Quoting <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>,</p> <blockquote> <p><code>isValidSignature</code> can call arbitrary methods to validate a given signature, which could be context dependent (e.g. time based or state based), EOA dependent (e.g. signers authorization level within smart wallet), signature scheme Dependent (e.g. ECDSA, multisig, BLS), etc.</p> <p>This function should be implemented by contracts which desire to sign messages (e.g. smart contract wallets, DAOs, multisignature wallets, etc.) Applications wanting to support contract signatures should call this method if the signer is a contract.</p> </blockquote> <p>We use the same <code>isValidSignature</code> function, but we add a new wrapper signature format, that signing contracts MAY use before they're deployed, in order to allow support for verification.</p> <p>The signature verifier MUST perform a contract deployment before attempting to call <code>isValidSignature</code> if the wrapper signature format is detected.</p> <p>The wrapper format is detected by checking if the signature ends in <code>magicBytes</code>, which MUST be defined as <code>0x6492649264926492649264926492649264926492649264926492649264926492</code>.</p> <p>It is RECOMMENDED to use this ERC with CREATE2 contracts, as their deploy address is always predictable.</p> <h3 id="signer-side">Signer side</h3> <p>The signing contract will normally be a contract wallet, but it could be any contract that implements <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> and is deployed counterfactually.</p> <ul> <li>If the contract is deployed, produce a normal <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> signature</li> <li>If the contract is not deployed yet, wrap the signature as follows: <code>concat(abi.encode((create2Factory, factoryCalldata, originalERC1271Signature), (address, bytes, bytes)), magicBytes)</code></li> <li>If the contract is deployed but not ready to verify using <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>, wrap the signature as follows: <code>concat(abi.encode((prepareTo, prepareData, originalERC1271Signature), (address, bytes, bytes)), magicBytes)</code>; <code>prepareTo</code> and <code>prepareData</code> must contain the necessary transaction that will make the contract ready to verify using <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> (e.g. a call to <code>migrate</code> or <code>update</code>)</li> </ul> <p>Note that we're passing <code>factoryCalldata</code> instead of <code>salt</code> and <code>bytecode</code>. We do this in order to make verification compliant with any factory interface. We do not need to calculate the address based on <code>create2Factory</code>/<code>salt</code>/<code>bytecode</code>, because <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> verification presumes we already know the account address we're verifying the signature for.</p> <h3 id="verifier-side">Verifier side</h3> <p>Full signature verification MUST be performed in the following order:</p> <ul> <li>check if the signature ends with magic bytes, in which case do an <code>eth_call</code> to a multicall contract that will call the factory first with the <code>factoryCalldata</code> and deploy the contract if it isn't already deployed; Then, call <code>contract.isValidSignature</code> as usual with the unwrapped signature</li> <li>check if there's contract code at the address. If so perform <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> verification as usual by invoking <code>isValidSignature</code></li> <li>if the <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> verification fails, and the deploy call to the <code>factory</code> was skipped due to the wallet already having code, execute the <code>factoryCalldata</code> transaction and try <code>isValidSignature</code> again</li> <li>if there is no contract code at the address, try <code>ecrecover</code> verification</li> </ul> <h2 id="rationale">Rationale</h2> <p>We believe that wrapping the signature in a way that allows to pass the deploy data is the only clean way to implement this, as it's completely contract agnostic, but also easy to verify.</p> <p>The wrapper format ends in <code>magicBytes</code>, which ends with a <code>0x92</code>, which makes it is impossible for it to collide with a valid <code>ecrecover</code> signature if packed in the <code>r,s,v</code> format, as <code>0x92</code> is not a valid value for <code>v</code>. To avoid collisions with normal <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>, <code>magicBytes</code> itself is also quite long (<code>bytes32</code>).</p> <p>The order to ensure correct verification is based on the following rules:</p> <ul> <li>checking for <code>magicBytes</code> MUST happen before the usual <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> check in order to allow counterfactual signatures to be valid even after contract deployment</li> <li>checking for <code>magicBytes</code> MUST happen before <code>ecrecover</code> in order to avoid trying to verify a counterfactual contract signature via <code>ecrecover</code> if such is clearly identifiable</li> <li>checking <code>ecrecover</code> MUST NOT happen before <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> verification, because a contract may use a signature format that also happens to be a valid <code>ecrecover</code> signature for an EOA with a different address. One such example is a contract that's a wallet controlled by said EOA.</li> </ul> <p>We can't determine the reason why a signature was encoded with a "deploy prefix" when the corresponding wallet already has code. It could be due to the signature being created before the contract was deployed, or it could be because the contract was deployed but not ready to verify signatures yet. As such, we need to try both options.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC is backward compatible with previous work on signature validation, including <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> and allows for easy verification of all signature types, including EOA signatures and typed data (<a href="https://wg-eips.ritovision.com/712/">EIP-712</a>).</p> <h3 id="using-erc-6492-for-regular-contract-signatures">Using <a href="https://wg-eips.ritovision.com/6492/">ERC-6492</a> for regular contract signatures</h3> <p>The wrapper format described in this ERC can be used for all contract signatures, instead of plain <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>. This provides several advantages:</p> <ul> <li>allows quick recognition of the signature type: thanks to the magic bytes, you can immediately know whether the signature is a contract signature without checking the blockchain</li> <li>allows recovery of address: you can get the address only from the signature using <code>create2Factory</code> and <code>factoryCalldata</code>, just like <code>ecrecover</code></li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>Below you can find an implementation of a universal verification contract that can be used both on-chain and off-chain, intended to be deployed as a singleton. It can validate signatures signed with this ERC, <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> and traditional <code>ecrecover</code>. <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> is also supported by extension, as we validate the final digest (<code>_hash</code>).</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> As per ERC-1271</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC1271Wallet</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isValidSignature</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> hash</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 class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes4</span><span class="z-variable"> magicValue</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">error</span><span class="z-entity z-name"> ERC1271Revert</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> error</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> ERC6492DeployFailed</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> error</span><span>)</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"> UniversalSigValidator</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> ERC6492_DETECTION_SUFFIX </span><span class="z-keyword">=</span><span class="z-constant"> 0x6492649264926492649264926492649264926492649264926492649264926492</span><span>;</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> ERC1271_SUCCESS </span><span class="z-keyword">=</span><span class="z-constant"> 0x1626ba7e</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"> isValidSigImpl</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _signer</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _hash</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 z-parameter z-function"> _signature</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> allowSideEffects</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> tryPrepare</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-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> contractCodeLen </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span>_signer</span><span>)</span><span>.</span><span>code</span><span>.</span><span>length</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> sigToValidate</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The order here is strictly defined in https://eips.ethereum.org/EIPS/eip-6492</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - ERC-6492 suffix check and verification first, while being permissive in case the contract is already deployed; if the contract is deployed we will check the sig against the deployed version, this allows 6492 signatures to still be validated while taking into account potential key rotation</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - ERC-1271 verification if there&#39;s contract code</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> - finally, ecrecover</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isCounterfactual </span><span class="z-keyword">=</span><span class="z-support"> bytes32</span><span>(</span><span>_signature</span><span>[</span><span>_signature</span><span>.</span><span>length</span><span class="z-keyword">-</span><span class="z-constant">32</span><span class="z-keyword">:</span><span>_signature</span><span>.</span><span>length</span><span>]</span><span>)</span><span class="z-keyword"> ==</span><span> ERC6492_DETECTION_SUFFIX</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>isCounterfactual</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> create2Factory</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> factoryCalldata</span><span>;</span></span> <span class="giallo-l"><span> (</span><span>create2Factory</span><span>,</span><span> factoryCalldata</span><span>,</span><span> sigToValidate</span><span>)</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>_signature</span><span>[</span><span class="z-constant">0</span><span class="z-keyword">:</span><span>_signature</span><span>.</span><span>length</span><span class="z-keyword">-</span><span class="z-constant">32</span><span>]</span><span>,</span><span> (</span><span class="z-support">address</span><span>,</span><span class="z-support"> bytes</span><span>,</span><span class="z-support"> bytes</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>contractCodeLen </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span class="z-keyword"> ||</span><span> tryPrepare</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-support"> bytes</span><span class="z-storage z-type"> memory</span><span> err</span><span>)</span><span class="z-keyword"> =</span><span> create2Factory</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span>factoryCalldata</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>success</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> ERC6492DeployFailed</span><span>(</span><span>err</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> sigToValidate </span><span class="z-keyword">=</span><span> _signature</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"> Try ERC-1271 verification</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>isCounterfactual </span><span class="z-keyword">||</span><span> contractCodeLen </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"> try</span><span class="z-entity z-name"> IERC1271Wallet</span><span>(</span><span>_signer</span><span>)</span><span>.</span><span class="z-entity z-name">isValidSignature</span><span>(</span><span>_hash</span><span>,</span><span> sigToValidate</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes4</span><span class="z-variable"> magicValue</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isValid </span><span class="z-keyword">=</span><span> magicValue </span><span class="z-keyword">==</span><span> ERC1271_SUCCESS</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> retry, but this time assume the prefix is a prepare call</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>isValid </span><span class="z-keyword">&amp;&amp;</span><span class="z-keyword"> !</span><span>tryPrepare </span><span class="z-keyword">&amp;&amp;</span><span> contractCodeLen </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"> return</span><span class="z-entity z-name"> isValidSigImpl</span><span>(</span><span>_signer</span><span>,</span><span> _hash</span><span>,</span><span> _signature</span><span>,</span><span> allowSideEffects</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 class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>contractCodeLen </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span class="z-keyword"> &amp;&amp;</span><span> isCounterfactual </span><span class="z-keyword">&amp;&amp;</span><span class="z-keyword"> !</span><span>allowSideEffects</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> if the call had side effects we need to return the</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> result using a `revert` (to undo the state changes)</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 class="z-constant">0</span><span>,</span><span> isValid</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span class="z-constant">31</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> <span class="giallo-l"><span class="z-keyword"> return</span><span> isValid</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> catch</span><span> (</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> err</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> retry, but this time assume the prefix is a prepare call</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>tryPrepare </span><span class="z-keyword">&amp;&amp;</span><span> contractCodeLen </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"> return</span><span class="z-entity z-name"> isValidSigImpl</span><span>(</span><span>_signer</span><span>,</span><span> _hash</span><span>,</span><span> _signature</span><span>,</span><span> allowSideEffects</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 class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> ERC1271Revert</span><span>(</span><span>err</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 class="z-comment"> ecrecover verification</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_signature</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 65</span><span>,</span><span class="z-string"> &#39;SignatureValidator#recoverSigner: invalid signature length&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> r </span><span class="z-keyword">=</span><span class="z-support"> bytes32</span><span>(</span><span>_signature</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-support"> bytes32</span><span> s </span><span class="z-keyword">=</span><span class="z-support"> bytes32</span><span>(</span><span>_signature</span><span>[</span><span class="z-constant">32</span><span class="z-keyword">:</span><span class="z-constant">64</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> v </span><span class="z-keyword">=</span><span class="z-support"> uint8</span><span>(</span><span>_signature</span><span>[</span><span class="z-constant">64</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>v </span><span class="z-keyword">!=</span><span class="z-constant"> 27</span><span class="z-keyword"> &amp;&amp;</span><span> v </span><span class="z-keyword">!=</span><span class="z-constant"> 28</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span class="z-string">&#39;SignatureValidator: invalid signature v value&#39;</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-support"> ecrecover</span><span>(</span><span>_hash</span><span>,</span><span> v</span><span>,</span><span> r</span><span>,</span><span> s</span><span>)</span><span class="z-keyword"> ==</span><span> _signer</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"> isValidSigWithSideEffects</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _signer</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"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _signature</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">bool</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"> this</span><span>.</span><span class="z-entity z-name">isValidSigImpl</span><span>(</span><span>_signer</span><span>,</span><span> _hash</span><span>,</span><span> _signature</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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isValidSig</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _signer</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"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _signature</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">bool</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> try</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">isValidSigImpl</span><span>(</span><span>_signer</span><span>,</span><span> _hash</span><span>,</span><span> _signature</span><span>,</span><span class="z-constant"> false</span><span>,</span><span class="z-constant"> false</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> isValid</span><span>)</span><span> {</span><span class="z-keyword"> return</span><span> isValid</span><span>;</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> catch</span><span> (</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-storage z-type"> error</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> in order to avoid side effects from the contract getting deployed, the entire call will revert with a single byte result</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> len </span><span class="z-keyword">=</span><span class="z-storage z-type"> error</span><span>.</span><span>length</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>len </span><span class="z-keyword">==</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> return</span><span class="z-storage z-type"> error</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> 0x01</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> all other errors are simply forwarded, but in custom formats so that nothing else can revert with a single byte in the call</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span class="z-keyword"> assembly</span><span> {</span><span class="z-keyword"> revert</span><span>(</span><span class="z-storage z-type">error</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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> this is a helper so we can perform validation in a single eth_call without pre-deploying a singleton</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ValidateSigOffchain</span><span> {</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"> _signer</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"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _signature</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> UniversalSigValidator validator </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-entity z-name"> UniversalSigValidator</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isValidSig </span><span class="z-keyword">=</span><span> validator</span><span>.</span><span class="z-entity z-name">isValidSigWithSideEffects</span><span>(</span><span>_signer</span><span>,</span><span> _hash</span><span>,</span><span> _signature</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 class="z-constant">0</span><span>,</span><span> isValidSig</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span>(</span><span class="z-constant">31</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>}</span></span></code></pre><h3 id="on-chain-validation">On-chain validation</h3> <p>For on-chain validation, you could use two separate methods:</p> <ul> <li><code>UniversalSigValidator.isValidSig(_signer, _hash, _signature)</code>: returns a bool of whether the signature is valid or not; this is reentrancy-safe</li> <li><code>UniversalSigValidator.isValidSigWithSideEffects(_signer, _hash, _signature)</code>: this is equivalent to the former - it is not reentrancy-safe but it is more gas-efficient in certain cases</li> </ul> <p>Both methods may revert if the underlying calls revert.</p> <h3 id="off-chain-validation">Off-chain validation</h3> <p>The <code>ValidateSigOffchain</code> helper allows you to perform the universal validation in one <code>eth_call</code>, without any pre-deployed contracts.</p> <p>Here's example of how to do this with the <code>ethers</code> library:</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"> isValidSignature</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x01</span><span class="z-punctuation z-definition z-string">&#39;</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">call</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> data</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">concat</span><span>(</span><span>[</span></span> <span class="giallo-l"><span class="z-variable z-other"> validateSigOffchainBytecode</span><span>,</span></span> <span class="giallo-l"><span> (</span><span class="z-keyword">new</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">AbiCoder</span><span>(</span><span>)</span><span>)</span><span>.</span><span class="z-entity z-name">encode</span><span>(</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 class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">bytes32</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">bytes</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>,</span><span> [</span><span class="z-variable z-other">signer</span><span>,</span><span class="z-variable z-other"> hash</span><span>,</span><span class="z-variable z-other"> signature</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> ]</span><span>)</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre> <p>You may also use a library to perform the universal signature validation, such as Ambire's <code>signature-validator</code>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The same considerations as <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> apply.</p> <p>However, deploying a contract requires a <code>CALL</code> rather than a <code>STATICCALL</code>, which introduces reentrancy concerns. This is mitigated in the reference implementation by having the validation method always revert if there are side-effects, and capturing its actual result from the revert data. For use cases where reentrancy is not a concern, we have provided the <code>isValidSigWithSideEffects</code> method.</p> <p>Furthermore, it is likely that this ERC will be more frequently used for off-chain validation, as in many cases, validating a signature on-chain presumes the wallet has been already deployed.</p> <p>One out-of-scope security consideration worth mentioning is whether the contract is going to be set-up with the correct permissions at deploy time, in order to allow for meaningful signature verification. By design, this is up to the implementation, but it's worth noting that thanks to how CREATE2 works, changing the bytecode or contructor callcode in the signature will not allow you to escalate permissions as it will change the deploy address and therefore make verification fail.</p> <p>It must be noted that contract accounts can dynamically change their methods of authentication. This issue is mitigated by design in this EIP - even when validating counterfactual signatures, if the contract is already deployed, we will still call it, checking against the current live version of the contract.</p> <p>As per usual with signatures, replay protection should be implemented in most use cases. This proposal adds an extra dimension to this, because it may be possible to validate a signature that has been rendered invalid (by changing the authorized keys) on a different network as long as 1) the signature was valid at the time of deployment 2) the wallet can be deployed with the same factory address/bytecode on this different 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> 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-08T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status Mikhail Kalininhttps://github.com/mkalinin https://wg-eips.ritovision.com/6465/

Migration of withdrawals MPT commitment to SSZ

<h2 id="abstract">Abstract</h2> <p>This EIP defines a migration process of the existing Merkle Patricia Trie (MPT) commitment for withdrawals to <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/simple-serialize.md">Simple Serialize (SSZ)</a>.</p> <h2 id="motivation">Motivation</h2> <p>While the consensus <code>ExecutionPayloadHeader</code> and the execution block header map to each other conceptually, they are encoded differently. This EIP aims to align the encoding of the <code>withdrawals_root</code>, taking advantage of the more modern SSZ format. This brings several advantages:</p> <ol> <li> <p><strong>Reducing complexity:</strong> The proposed design reduces the number of use cases that require support for Merkle Patricia Trie (MPT).</p> </li> <li> <p><strong>Reducing ambiguity:</strong> The name <code>withdrawals_root</code> is currently used to refer to different roots. While the execution block header refers to a Merkle Patricia Trie (MPT) root, the consensus <code>ExecutionPayloadHeader</code> instead refers to an SSZ root. With these changes, <code>withdrawals_root</code> consistently refers to the same SSZ root.</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="existing-definitions">Existing definitions</h3> <p>Definitions from existing specifications that are used throughout this document are replicated here for reference.</p> <table><thead><tr><th>Name</th><th>SSZ equivalent</th></tr></thead><tbody> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#custom-types"><code>ValidatorIndex</code></a></td><td><code>uint64</code></td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#custom-types"><code>Gwei</code></a></td><td><code>uint64</code></td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/bellatrix/beacon-chain.md#custom-types"><code>ExecutionAddress</code></a></td><td><code>Bytes20</code></td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/capella/beacon-chain.md#custom-types"><code>WithdrawalIndex</code></a></td><td><code>uint64</code></td></tr> </tbody></table> <h3 id="withdrawals">Withdrawals</h3> <p>New withdrawals use a normalized SSZ representation. The existing consensus <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/capella/beacon-chain.md#withdrawal"><code>Withdrawal</code></a> SSZ container is migrated to <a href="https://wg-eips.ritovision.com/7495/">EIP-7495 <code>ProgressiveContainer</code></a>.</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"> Withdrawal</span><span>(</span><span class="z-entity">ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> index</span><span>:</span><span> WithdrawalIndex</span></span> <span class="giallo-l"><span> validator_index</span><span>:</span><span> ValidatorIndex</span></span> <span class="giallo-l"><span> address</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> amount</span><span>:</span><span> Gwei</span></span></code></pre><h3 id="execution-block-header-changes">Execution block header changes</h3> <p>The <a rel="external" href="https://github.com/ethereum/devp2p/blob/bc76b9809a30e6dc5c8dcda996273f0f9bcf7108/caps/eth.md#block-encoding-and-validity">execution block header's <code>withdrawals-root</code></a> is transitioned from MPT to SSZ.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>withdrawals</span><span class="z-keyword"> =</span><span> ProgressiveList</span><span>[</span><span>Withdrawal</span><span>]</span><span>(</span></span> <span class="giallo-l"><span> withdrawal_0</span><span>,</span><span> withdrawal_1</span><span>,</span><span> withdrawal_2</span><span>,</span><span class="z-constant"> ...</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>block_header</span><span>.</span><span>withdrawals_root</span><span class="z-keyword"> =</span><span> withdrawals</span><span>.</span><span>hash_tree_root</span><span>(</span><span>)</span></span></code></pre><h3 id="consensus-executionpayload-changes">Consensus <code>ExecutionPayload</code> changes</h3> <p>When building a consensus <code>ExecutionPayload</code>, the <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/deneb/beacon-chain.md#executionpayload"><code>withdrawals</code></a> list is based on the new progressive container type.</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"> ExecutionPayload</span><span>(</span><span class="z-constant">...</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"><span> withdrawals</span><span>:</span><span> ProgressiveList</span><span>[</span><span>Withdrawal</span><span>]</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre> <p>The state transition function is updated to limit withdrawals to <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/capella/beacon-chain.md#execution"><code>MAX_WITHDRAWALS_PER_PAYLOAD</code></a>.</p> <h2 id="rationale">Rationale</h2> <p>This change was originally a candidate for inclusion in Shanghai, but was postponed to accelerate the rollout of withdrawals.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Applications that rely on the replaced MPT <code>withdrawals_root</code> in the block header require migration to the SSZ <code>withdrawals_root</code>.</p> <p>RLP and SSZ withdrawals may clash when encoded. It is essential to use only a single format within one channel. The block header corresponding to the withdrawals can be consulted to identify the underlying fork.</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-02-08T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status Gajinder Singhhttps://github.com/g11tech Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/6466/

Migration of RLP receipts to SSZ

<h2 id="abstract">Abstract</h2> <p>This EIP defines a migration process of <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> Recursive-Length Prefix (RLP) receipts to <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/ssz/simple-serialize.md">Simple Serialize (SSZ)</a></p> <h2 id="motivation">Motivation</h2> <p>RLP receipts have a number of shortcomings:</p> <ol> <li> <p><strong>Limited proving support:</strong> Due to receipt data being linearly hashed as part of the <code>receipts_root</code> Merkle-Patricia Trie (MPT), it is not possible to efficiently proof individual parts of receipts, such as logs. Requiring the full receipt data to be present can be prohibitive for smart contract based applications such as L2 fraud proofs or client applications verifying log data.</p> </li> <li> <p><strong>Incomplete data:</strong> JSON-RPC provides <code>from</code>, <code>gasUsed</code>, and <code>contractAddress</code> fields for receipts, but the on-chain receipt does not contain the required information to verify them.</p> </li> </ol> <p>This EIP defines a universal receipt format based on SSZ to address these concerns.</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="existing-definitions">Existing definitions</h3> <p>Definitions from existing specifications that are used throughout this document are replicated here for reference.</p> <table><thead><tr><th>Name</th><th>SSZ equivalent</th></tr></thead><tbody> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/specs/phase0/beacon-chain.md#custom-types"><code>Root</code></a></td><td><code>Bytes32</code></td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/specs/bellatrix/beacon-chain.md#custom-types"><code>ExecutionAddress</code></a></td><td><code>Bytes20</code></td></tr> <tr><td><a href="https://wg-eips.ritovision.com/6404/#normalized-transactions"><code>GasAmount</code></a></td><td><code>uint64</code></td></tr> </tbody></table> <h3 id="logs">Logs</h3> <p>Logs are represented as an SSZ <code>Container</code>.</p> <table><thead><tr><th>Name</th><th>Value</th><th>Description</th></tr></thead><tbody> <tr><td><code>MAX_TOPICS_PER_LOG</code></td><td><code>4</code></td><td><code>LOG0</code> through <code>LOG4</code> opcodes allow 0-4 topics per log</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"> Log</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> address</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> topics</span><span>:</span><span> List</span><span>[</span><span>Bytes32</span><span>,</span><span class="z-constant"> MAX_TOPICS_PER_LOG</span><span>]</span></span> <span class="giallo-l"><span> data</span><span>:</span><span> ProgressiveByteList</span></span></code></pre><h3 id="receipts">Receipts</h3> <p>New receipts use a normalized SSZ representation.</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"> Receipt</span><span>(</span><span class="z-entity">CompatibleUnion</span><span>(</span><span>{</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">01</span><span>:</span><span> BasicReceipt</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">02</span><span>:</span><span> CreateReceipt</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">03</span><span>:</span><span> SetCodeReceipt</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> pass</span></span></code></pre><h4 id="basic-receipts">Basic receipts</h4> <p>This receipt is emitted for these transactions:</p> <ul> <li><a href="https://wg-eips.ritovision.com/6404/#normalized-transactions"><code>RlpLegacyReplayableBasicTransaction</code></a></li> <li><a href="https://wg-eips.ritovision.com/6404/#normalized-transactions"><code>RlpLegacyBasicTransaction</code></a></li> <li><a href="https://wg-eips.ritovision.com/6404/#normalized-transactions"><code>RlpAccessListBasicTransaction</code></a></li> <li><a href="https://wg-eips.ritovision.com/6404/#normalized-transactions"><code>RlpBasicTransaction</code></a></li> <li><a href="https://wg-eips.ritovision.com/6404/#normalized-transactions"><code>RlpBlobTransaction</code></a></li> </ul> <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"> BasicReceipt</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> from_</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> gas_used</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> logs</span><span>:</span><span> ProgressiveList</span><span>[</span><span>Log</span><span>]</span></span> <span class="giallo-l"><span> status</span><span>:</span><span> boolean</span></span></code></pre><h4 id="create-receipts">Create receipts</h4> <p>This receipt is emitted for these transactions:</p> <ul> <li><a href="https://wg-eips.ritovision.com/6404/#normalized-transactions"><code>RlpLegacyReplayableCreateTransaction</code></a></li> <li><a href="https://wg-eips.ritovision.com/6404/#normalized-transactions"><code>RlpLegacyCreateTransaction</code></a></li> <li><a href="https://wg-eips.ritovision.com/6404/#normalized-transactions"><code>RlpAccessListCreateTransaction</code></a></li> <li><a href="https://wg-eips.ritovision.com/6404/#normalized-transactions"><code>RlpCreateTransaction</code></a></li> </ul> <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"> CreateReceipt</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> from_</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> gas_used</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> contract_address</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> logs</span><span>:</span><span> ProgressiveList</span><span>[</span><span>Log</span><span>]</span></span> <span class="giallo-l"><span> status</span><span>:</span><span> boolean</span></span></code></pre><h4 id="eip-7702-set-code-receipts">EIP-7702 set code receipts</h4> <p>This receipt is emitted for these transactions:</p> <ul> <li><a href="https://wg-eips.ritovision.com/6404/#normalized-transactions"><code>RlpSetCodeTransaction</code></a></li> </ul> <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"> SetCodeReceipt</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> from_</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> gas_used</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> logs</span><span>:</span><span> ProgressiveList</span><span>[</span><span>Log</span><span>]</span></span> <span class="giallo-l"><span> status</span><span>:</span><span> boolean</span></span> <span class="giallo-l"><span> authorities</span><span>:</span><span> ProgressiveList</span><span>[</span><span>ExecutionAddress</span><span>]</span></span></code></pre><h3 id="receipt-construction"><code>Receipt</code> construction</h3> <p>Receipts are constructed as follows.</p> <table><thead><tr><th>Field</th><th>Description</th></tr></thead><tbody> <tr><td><code>from</code></td><td>The transaction sender's address</td></tr> <tr><td><code>gas_used</code></td><td>How much gas this individual transaction used</td></tr> <tr><td><code>contract_address</code></td><td>For transactions deploying a contract, the new contract address. Present only in <code>CreateReceipt</code></td></tr> <tr><td><code>logs</code></td><td>Logs emitted during transaction execution</td></tr> <tr><td><code>status</code></td><td><a href="https://wg-eips.ritovision.com/658/">EIP-658</a> transaction status code</td></tr> <tr><td><code>authorities</code></td><td>For transactions with an authorization list, the list of <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> <code>authority</code> addresses. Non-successful authorizations are represented with an all-zero address</td></tr> </tbody></table> <p>The <code>logs_bloom</code>, intermediate state <code>root</code> (Homestead scheme), and <code>cumulative_gas_used</code> (pre <a href="https://wg-eips.ritovision.com/8116/">EIP-8116</a>) fields are not present in SSZ receipts.</p> <h3 id="execution-block-header-changes">Execution block header changes</h3> <p>The <a rel="external" href="https://github.com/ethereum/devp2p/blob/bc76b9809a30e6dc5c8dcda996273f0f9bcf7108/caps/eth.md#block-encoding-and-validity">execution block header's <code>receipts-root</code></a> is transitioned from MPT to SSZ.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>receipts</span><span class="z-keyword"> =</span><span> ProgressiveList</span><span>[</span><span>Receipt</span><span>]</span><span>(</span></span> <span class="giallo-l"><span> receipt_0</span><span>,</span><span> receipt_1</span><span>,</span><span> receipt_2</span><span>,</span><span class="z-constant"> ...</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>block_header</span><span>.</span><span>receipts_root</span><span class="z-keyword"> =</span><span> receipts</span><span>.</span><span>hash_tree_root</span><span>(</span><span>)</span></span></code></pre><h3 id="json-rpc-api">JSON-RPC API</h3> <p>Transaction receipt objects in the context of the JSON-RPC API are extended to include:</p> <ul> <li><code>authorities</code>: <code>Array of DATA|null</code> - Array of <code>DATA</code> entries each containing 20 Bytes, corresponding to the receipt's <code>authorities</code> field</li> </ul> <p>The <code>logsBloom</code> field is no longer returned for new receipts. It continues to be returned for historical receipts conforming to earlier schemes.</p> <p><code>from</code>, <code>gasUsed</code>, and <code>contractAddress</code> are already provided via JSON-RPC and are left unchanged. For <code>BasicReceipt</code> and <code>SetCodeReceipt</code>, <code>contractAddress</code> will be <code>null</code> as these receipt types do not contain the <code>contract_address</code> field. <code>logIndex</code> indicates the log index position in the individual receipt (rather than the entire block), as defined in <a href="https://wg-eips.ritovision.com/8116/">EIP-8116</a>.</p> <h3 id="consensus-executionpayload-changes">Consensus <code>ExecutionPayload</code> changes</h3> <p>When building a consensus <code>ExecutionPayload</code>, the <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/specs/deneb/beacon-chain.md#executionpayload"><code>receipts_root</code></a> is now based on the <code>Receipt</code> type, changing the type of <code>receipts_root</code> from an MPT <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/specs/phase0/beacon-chain.md#custom-types"><code>Hash32</code></a> to an SSZ <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/specs/phase0/beacon-chain.md#custom-types"><code>Root</code></a>.</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"> ExecutionPayload</span><span>(</span><span class="z-constant">...</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"><span> receipts_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span class="z-constant"> ...</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"> ExecutionPayloadHeader</span><span>(</span><span class="z-constant">...</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"><span> receipts_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre><pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>payload_header</span><span>.</span><span>receipts_root</span><span class="z-keyword"> =</span><span> payload</span><span>.</span><span>receipts_root</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="forward-compatibility">Forward compatibility</h3> <p>All receipts share the same Merkle tree shape with a stable <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/merkle-proofs.md#generalized-merkle-tree-index">generalized index (gindex)</a> assigned to each field. Future transaction features can introduce additional receipt fields or drop existing fields without breaking verifiers.</p> <h3 id="verifier-improvements">Verifier improvements</h3> <p>Committing to <code>from</code>, <code>contract_address</code> and <code>authorities</code> in the receipt allows efficient verification without the expensive <code>ecrecover</code> mechanism. This allows future EIPs to change how these addresses are computed without breaking verifiers, e.g., when future signature schemes are introduced.</p> <h3 id="execution-client-improvements">Execution client improvements</h3> <p>Execution Layer implementations no longer need access to the transaction and additional indices when serving receipts based on SSZ.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Applications that rely on the replaced MPT <code>receipts_root</code> in the block header require migration to the SSZ <code>receipts_root</code>.</p> <p>RLP and SSZ receipts may clash when encoded. It is essential to use only a single format within one channel. When requesting receipts by hash over the network, the block header corresponding to the containing receipts root can be consulted to identify the underlying fork.</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-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-31T00:00:00+00:00 2026-02-11T14:48:25+00:00 Bruno Škvorchttps://github.com/Swader Francesco Sullohttps://github.com/sullof Steven Pinedahttps://github.com/steven2308 Stevan Bogosavljevichttps://github.com/stevyhacker Jan Turkhttps://github.com/ThunderDeliverer https://wg-eips.ritovision.com/6454/

A minimal extension to identify the transferability of Non-Fungible Tokens.

<h2 id="abstract">Abstract</h2> <p>The Minimalistic Transferable interface for Non-Fungible Tokens standard extends <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> by introducing the ability to identify whether an NFT can be transferred or not.</p> <p>This proposal introduces the ability to prevent a token from being transferred from their owner, making them bound to the externally owned account, abstracted account, smart contract or token that owns it.</p> <h2 id="motivation">Motivation</h2> <p>With NFTs being a widespread form of tokens in the Ethereum ecosystem and being used for a variety of use cases, it is time to standardize additional utility for them. Having the ability to prevent the tokens from being transferred introduces new possibilities of NFT utility and evolution.</p> <p>This proposal is designed in a way to be as minimal as possible in order to be compatible with any usecases that wish to utilize this proposal.</p> <p>This EIP introduces new utilities for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> based tokens in the following areas:</p> <ul> <li><a href="https://wg-eips.ritovision.com/6454/#verifiable-attribution">Verifiable attribution</a></li> <li><a href="https://wg-eips.ritovision.com/6454/#immutable-properties">Immutable properties</a></li> </ul> <h3 id="verifiable-attribution">Verifiable attribution</h3> <p>Personal achievements can be represented by non-fungible tokens. These tokens can be used to represent a wide range of accomplishments, including scientific advancements, philanthropic endeavors, athletic achievements, and more. However, if these achievement-indicating NFTs can be easily transferred, their authenticity and trustworthiness can be called into question. By binding the NFT to a specific account, it can be ensured that the account owning the NFT is the one that actually achieved the corresponding accomplishment. This creates a secure and verifiable record of personal achievements that can be easily accessed and recognized by others in the network. The ability to verify attribution helps to establish the credibility and value of the achievement-indicating NFT, making it a valuable asset that can be used as a recognition of the holder's accomplishments.</p> <h3 id="immutable-properties">Immutable properties</h3> <p>NFT properties are a critical aspect of non-fungible tokens, serving to differentiate them from one another and establish their scarcity. Centralized control of NFT properties by the issuer, however, can undermine the uniqueness of these properties.</p> <p>By tying NFTs to specific properties, the original owner is ensured that the NFT will always retain these properties and its uniqueness.</p> <p>In a blockchain game that employs non-transferable NFTs to represent skills or abilities, each skill would be a unique and permanent asset tied to a specific player or token. This would ensure that players retain ownership of the skills they have earned and prevent them from being traded or sold to other players. This can increase the perceived value of these skills, enhancing the player experience by allowing for greater customization and personalization of characters.</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-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> EIP-6454 Minimalistic Non-Transferable interface for NFTs</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-6454</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 ERC-165 identifier for this interface is 0x91a6262f.</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.16</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"> IERC6454</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC165 </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"> Used to check whether the given token is transferable or not.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If this function returns `false`, the transfer of the token MUST revert execution.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If the tokenId does not exist, this method MUST revert execution, unless the token is being checked for</span></span> <span class="giallo-l"><span class="z-comment"> * minting.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The `from` parameter MAY be used to also validate the approval of the token for transfer, but anyone</span></span> <span class="giallo-l"><span class="z-comment"> * interacting with this function SHOULD NOT rely on it as it is not mandated by the 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"> tokenId</span><span class="z-comment"> ID of the token being checked</span></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"> Address from which the token is being transferred</span></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 to which the token is being transferred</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"> Boolean</span><span class="z-comment"> value indicating whether the given token is transferable</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"> isTransferable</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"> 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"> 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>In order to determine whether a token is transferable or not in general, the function SHOULD return the appropriate boolean value when passing the <code>0x0000000000000000000000000000000000000000</code> address as the <code>to</code> and <code>from</code> parameter.</p> <p>The general transferability of a token should not be affected by the ability to mint the token (value of <code>from</code> parameter is <code>0x0000000000000000000000000000000000000000</code>) and the ability to burn the token (value of <code>to</code> parameter is <code>0x0000000000000000000000000000000000000000</code>).</p> <p>If the general transferability of token is <code>false</code>, any kind of transfer of the token, save minting and burning, MUST revert execution.</p> <p>In order to determine whether a token is mintable, the exception SHOULD be made to allow the <code>tokenId</code> parameter for a token that does not exist. Additionally the <code>from</code> parameter SHOULD be <code>0x0000000000000000000000000000000000000000</code> and the <code>to</code> parameter SHOULD NOT be <code>0x0000000000000000000000000000000000000000</code>.</p> <p>In order to determine whether a token is burnable, the <code>from</code> parameter SHOULD NOT be <code>0x0000000000000000000000000000000000000000</code> and the <code>to</code> parameter SHOULD be <code>0x0000000000000000000000000000000000000000</code>.</p> <p>Implementers MAY choose to validate the approval of the token for transfer by the <code>from</code> parameter, but anyone interacting with this function SHOULD NOT rely on it as it is not mandated by the proposal. This means that the <code>from</code> parameter in such implementations validates the initiator of the transaction rather than the owner from which the token is being transferred (which can either be the owner of the token or the operator allowed to transfer the token).</p> <h2 id="rationale">Rationale</h2> <p>Designing the proposal, we considered the following questions:</p> <ol> <li><strong>Should we propose another (Non-)Transferable NFT proposal given the existence of existing ones, some even final, and how does this proposal compare to them?</strong><br /> This proposal aims to provide the minimum necessary specification for the implementation of non-transferable NFTs, we feel none of the existing proposals have presented the minimal required interface. Unlike other proposals that address the same issue, this proposal requires fewer methods in its specification, providing a more streamlined solution.</li> <li><strong>Why is there no event marking the token as Non-Transferable in this interface?</strong><br /> The token can become non-transferable either at its creation, after being marked as non-transferable, or after a certain condition is met. This means that some cases of tokens becoming non-transferable cannot emit an event, such as if the token becoming non-transferable is determined by a block number. Requiring an event to be emitted upon the token becoming non-transferable is not feasible in such cases.</li> <li><strong>Should the transferability state management function be included in this proposal?</strong><br /> A function that marks a token as non-transferable or releases the binding is referred to as the transferability management function. To maintain the objective of designing an agnostic minimal transferable proposal, we have decided not to specify the transferability management function. This allows for a variety of custom implementations that require the tokens to be non-transferable.</li> <li><strong>Why should this be an EIP if it only contains one method?</strong><br /> One could argue that since the core of this proposal is to only prevent ERC-721 tokens to be transferred, this could be done by overriding the transfer function. While this is true, the only way to assure that the token is non-transferable before the smart contract execution, is for it to have the transferable interface.<br /> This also allows for smart contract to validate whether the token is not transferable and not attempt transferring it as this would result in failed transactions and wasted gas.</li> <li><strong>Should we include the most straightforward method possible that only accepts a <code>tokenId</code> parameter?</strong><br /> The initial version of the proposal contained a method that only accepted a <code>tokenId</code> parameter. This method would return a boolean value indicating whether the token is transferable. However, the fact that the token can be non-transferable for different reasons was brought up throughout the discussion. This is why the method was changed to accept additional parameters, allowing for a more flexible implementation. Additionally, we kept the original method’s functionality by specifying the methodology on how to achieve the same result (by passing the <code>0x0000000000000000000000000000000000000000</code> address as the <code>to</code> and <code>from</code> parameters).</li> <li><strong>What is the best user experience for frontend?</strong><br /> The best user experience for the front end is having a single method that checks whether the token is transferable. This method should handle both cases of transferability, general and conditional.<br /> The front end should also be able to handle the case where the token is not transferable and the transfer is attempted. This can be done by checking the return value of the transfer function, which will be false if the token is not transferable. If the token would just be set as non-transferable, without a standardized interface to check whether the token is transferable, the only way to validate transferability would be to attempt a gas calculation and check whether the transaction would revert. This is a bad user experience and should be avoided.</li> <li><strong>Should we mandate that the <code>isTransferable</code> validates approvals as well?</strong><br /> We considered specifying that the <code>from</code> parameter represents the initiator of the token transfer. This would mean that the <code>from</code> would validate whether the address is the owner of the token or approved to transfer it. While this might be beneficial, we ultimately decided to make it optional.<br /> As this proposal aims to be the minimal possible implementation and the approvals are already standardized, we feel that <code>isTransferable</code> can be used in conjunction with the approvals to validate whether the given address can initiate the transfer or not.<br /> Additionally, mandating the validation of approvals would incur higher gas consumption as additional checks would be required to validate the transferability.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The Minimalistic Non-Transferable token standard is fully compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and with the robust tooling available for implementations of ERC-721 as well as with the existing ERC-721 infrastructure.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests are included in <a href="https://wg-eips.ritovision.com/6454/./assets/test/transferable.ts"><code>transferable.ts</code></a>.</p> <p>To run them in terminal, you can use the following commands:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cd ../assets/eip-6454</span></span> <span class="giallo-l"><span>npm install</span></span> <span class="giallo-l"><span>npx hardhat test</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/6454/./assets/contracts/mocks/ERC721TransferableMock.sol"><code>ERC721TransferableMock.sol</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The same security considerations as with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> apply: hidden logic may be present in any of the functions, including burn, add asset, accept asset, and more.</p> <p>A smart contract can implement the proposal interface but returns fraudulent values, i.e., returning <code>false</code> for <code>isTransferable</code> when the token is transferable. Such a contract would trick other contracts into thinking that the token is non-transferable when it is transferable. If such a contract exists, we suggest not interacting with it. Much like fraudulent <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> or <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> smart contracts, it is not possible to prevent such contracts from existing. We suggest that you verify all of the external smart contracts you interact with and not interact with contracts you do not trust.</p> <p>Since the transferability state can change over time, verifying that the state of the token is transferable before interacting with it is essential. Therefore, a dApp, marketplace, or wallet implementing this interface should verify the state of the token every time the token is displayed.</p> <p>Caution is advised when dealing with non-audited 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> 2023-01-30T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status Gajinder Singhhttps://github.com/g11tech Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/6404/

Migration of RLP transactions to SSZ

<h2 id="abstract">Abstract</h2> <p>This EIP defines a migration process of <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> Recursive-Length Prefix (RLP) transactions to <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/ssz/simple-serialize.md">Simple Serialize (SSZ)</a>.</p> <h2 id="motivation">Motivation</h2> <p>RLP transactions have a number of shortcomings:</p> <ol> <li> <p><strong>Linear hashing:</strong> The signing hash (<code>sig_hash</code>) and unique identifier (<code>tx_hash</code>) of an RLP transaction are computed by linear keccak256 hashes across its serialization. Even if only partial data is of interest, linear hashes require the full transaction data to be present, including potentially large calldata or access lists. This also applies when computing the <code>from</code> address of a transaction based on the <code>sig_hash</code>.</p> </li> <li> <p><strong>Inefficient inclusion proofs:</strong> The Merkle-Patricia Trie (MPT) backing the execution block header's <code>transactions_root</code> is constructed from the serialized transactions, internally prepending a prefix to the transaction data before it is keccak256 hashed into the MPT. Due to this prefix, there is no on-chain commitment to the <code>tx_hash</code> and inclusion proofs require the full transaction data to be present.</p> </li> <li> <p><strong>Incompatible representation:</strong> As part of the consensus <code>ExecutionPayload</code>, the RLP serialization of transactions is hashed using SSZ merkleization. These SSZ hashes are incompatible with both the <code>tx_hash</code> and the MPT <code>transactions_root</code>.</p> </li> <li> <p><strong>Technical debt:</strong> All client applications and smart contracts handling RLP transactions have to correctly deal with caveats such as <code>LegacyTransaction</code> lacking a prefix byte, the inconsistent <code>chain_id</code> and <code>v</code> / <code>y_parity</code> semantics, and the introduction of <code>max_priority_fee_per_gas</code> between other fields instead of at the end. As existing transaction types tend to remain valid perpetually, this technical debt builds up over time.</p> </li> <li> <p><strong>Inappropriate opaqueness:</strong> The Consensus Layer treats RLP transaction data as opaque, but requires validation of consensus <code>blob_kzg_commitments</code> against transaction <code>blob_versioned_hashes</code>, resulting in a more complex than necessary engine API.</p> </li> </ol> <p>This EIP addresses these by defining a lossless conversion mechanism to normalize transaction representation across both Consensus Layer and Execution Layer while retaining support for processing RLP transaction types.</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="existing-definitions">Existing definitions</h3> <p>Definitions from existing specifications that are used throughout this document are replicated here for reference.</p> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/deneb/polynomial-commitments.md#constants"><code>BYTES_PER_FIELD_ELEMENT</code></a></td><td><code>uint64(32)</code></td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/deneb/polynomial-commitments.md#blob"><code>FIELD_ELEMENTS_PER_BLOB</code></a></td><td><code>uint64(4096)</code></td></tr> </tbody></table> <table><thead><tr><th>Name</th><th>SSZ equivalent</th></tr></thead><tbody> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/phase0/beacon-chain.md#custom-types"><code>Hash32</code></a></td><td><code>Bytes32</code></td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/bellatrix/beacon-chain.md#custom-types"><code>ExecutionAddress</code></a></td><td><code>Bytes20</code></td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/deneb/beacon-chain.md#custom-types"><code>VersionedHash</code></a></td><td><code>Bytes32</code></td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/deneb/polynomial-commitments.md#custom-types"><code>KZGCommitment</code></a></td><td><code>Bytes48</code></td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/deneb/polynomial-commitments.md#custom-types"><code>KZGProof</code></a></td><td><code>Bytes48</code></td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/deneb/polynomial-commitments.md#custom-types"><code>Blob</code></a></td><td><code>ByteVector[BYTES_PER_FIELD_ELEMENT * FIELD_ELEMENTS_PER_BLOB]</code></td></tr> </tbody></table> <h3 id="signatures">Signatures</h3> <p>Transaction signatures are represented by their native, opaque representation, prefixed by a value indicating their algorithm.</p> <table><thead><tr><th>Name</th><th>SSZ equivalent</th></tr></thead><tbody> <tr><td><code>ExecutionSignature</code></td><td><code>ProgressiveByteList</code></td></tr> <tr><td><code>ExecutionSignatureAlgorithm</code></td><td><code>uint8</code></td></tr> </tbody></table> <h4 id="secp256k1">Secp256k1</h4> <table><thead><tr><th>Name</th><th>Value</th><th>Description</th></tr></thead><tbody> <tr><td><code>SECP256K1_ALGORITHM</code></td><td><code>uint8(0xFF)</code></td><td>Defined from <a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a></td></tr> </tbody></table> <h4 id="verification">Verification</h4> <p>The following functions are imported from <a href="https://wg-eips.ritovision.com/7932/">EIP-7932</a>:</p> <ul> <li><code>calculate_penalty</code></li> <li><code>validate_signature</code></li> <li><code>verify_signature</code></li> <li><code>pubkey_to_address</code></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"> get_signature_gas_cost</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> signature</span><span>:</span><span> ExecutionSignature</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> sig_hash</span><span>:</span><span> Hash32</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> expected_algorithm</span><span>:</span><span> Optional</span><span>[</span><span>ExecutionSignatureAlgorithm</span><span>]</span><span class="z-keyword">=</span><span class="z-constant">None</span></span> <span class="giallo-l"><span>)</span><span> -&gt;</span><span> uint</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>signature</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 class="z-keyword"> if</span><span> expected_algorithm</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"> assert</span><span> signature</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> ==</span><span> expected_algorithm</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> calculate_penalty</span><span>(</span><span>signature</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span> sig_hash</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"> validate_execution_signature</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> signature</span><span>:</span><span> ExecutionSignature</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> expected_algorithm</span><span>:</span><span> Optional</span><span>[</span><span>ExecutionSignatureAlgorithm</span><span>]</span><span class="z-keyword">=</span><span class="z-constant">None</span><span>,</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>signature</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 class="z-keyword"> if</span><span> expected_algorithm</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"> assert</span><span> signature</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> ==</span><span> expected_algorithm</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> validate_signature</span><span>(</span><span>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"> recover_execution_signer</span><span>(</span><span class="z-variable z-parameter z-function">signature</span><span>:</span><span> ExecutionSignature</span><span>,</span><span class="z-variable z-parameter z-function"> sig_hash</span><span>:</span><span> Hash32</span><span>)</span><span> -&gt;</span><span> ExecutionAddress</span><span>:</span></span> <span class="giallo-l"><span> public_key</span><span class="z-keyword"> =</span><span> verify_signature</span><span>(</span><span>sig_hash</span><span>,</span><span> signature</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> pubkey_to_address</span><span>(</span><span>public_key</span><span>,</span><span> signature</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span></span></code></pre><h3 id="gas-fees">Gas fees</h3> <p>The different kinds of gas fees are combined into a single structure.</p> <table><thead><tr><th>Name</th><th>SSZ equivalent</th><th>Description</th></tr></thead><tbody> <tr><td><code>FeePerGas</code></td><td><code>uint256</code></td><td>Fee per unit of gas</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"> BasicFeesPerGas</span><span>(</span><span class="z-entity">ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>]</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> regular</span><span>:</span><span> FeePerGas</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"> BlobFeesPerGas</span><span>(</span><span class="z-entity">ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> regular</span><span>:</span><span> FeePerGas</span></span> <span class="giallo-l"><span> blob</span><span>:</span><span> FeePerGas</span></span></code></pre><h3 id="normalized-transactions">Normalized transactions</h3> <p>RLP transactions are converted to a normalized SSZ representation. Their original RLP <code>TransactionType</code> is retained to enable recovery of their original RLP representation and associated <code>sig_hash</code> and historical <code>tx_hash</code> values.</p> <table><thead><tr><th>Name</th><th>SSZ equivalent</th><th>Description</th></tr></thead><tbody> <tr><td><code>TransactionType</code></td><td><code>uint8</code></td><td><a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction type, range <code>[0x00, 0x7F]</code></td></tr> <tr><td><code>ChainId</code></td><td><code>uint256</code></td><td><a href="https://wg-eips.ritovision.com/155/">EIP-155</a> chain ID</td></tr> <tr><td><code>GasAmount</code></td><td><code>uint64</code></td><td>Amount in units of gas</td></tr> </tbody></table> <h4 id="replayable-legacy-transactions">Replayable legacy transactions</h4> <p>The original RLP representation of these transactions is replayable across networks with different chain ID.</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"> RlpLegacyReplayableBasicTransactionPayload</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> type_</span><span>:</span><span> TransactionType</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 0x00</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> max_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> gas</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> to</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> value</span><span>:</span><span> uint256</span></span> <span class="giallo-l"><span> input_</span><span>:</span><span> ProgressiveByteList</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"> RlpLegacyReplayableCreateTransactionPayload</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> type_</span><span>:</span><span> TransactionType</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 0x00</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> max_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> gas</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> value</span><span>:</span><span> uint256</span></span> <span class="giallo-l"><span> input_</span><span>:</span><span> ProgressiveByteList</span></span></code></pre><h4 id="eip-155-legacy-transactions">EIP-155 legacy transactions</h4> <p>These transactions are locked to a single <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> chain ID.</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"> RlpLegacyBasicTransactionPayload</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> type_</span><span>:</span><span> TransactionType</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 0x00</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span> ChainId</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> max_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> gas</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> to</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> value</span><span>:</span><span> uint256</span></span> <span class="giallo-l"><span> input_</span><span>:</span><span> ProgressiveByteList</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"> RlpLegacyCreateTransactionPayload</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> type_</span><span>:</span><span> TransactionType</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 0x00</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span> ChainId</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> max_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> gas</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> value</span><span>:</span><span> uint256</span></span> <span class="giallo-l"><span> input_</span><span>:</span><span> ProgressiveByteList</span></span></code></pre><h4 id="legacy-transactions">Legacy transactions</h4> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>RlpLegacyTransactionPayload</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> RlpLegacyReplayableBasicTransactionPayload</span><span class="z-keyword"> |</span></span> <span class="giallo-l"><span> RlpLegacyReplayableCreateTransactionPayload</span><span class="z-keyword"> |</span></span> <span class="giallo-l"><span> RlpLegacyBasicTransactionPayload</span><span class="z-keyword"> |</span></span> <span class="giallo-l"><span> RlpLegacyCreateTransactionPayload</span></span> <span class="giallo-l"><span>)</span></span></code></pre><h4 id="eip-2930-access-list-transactions">EIP-2930 access list transactions</h4> <p>These transactions support specifying an <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> access list.</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"> AccessTuple</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> address</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> storage_keys</span><span>:</span><span> ProgressiveList</span><span>[</span><span>Hash32</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"> RlpAccessListBasicTransactionPayload</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> type_</span><span>:</span><span> TransactionType</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 0x01</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span> ChainId</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> max_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> gas</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> to</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> value</span><span>:</span><span> uint256</span></span> <span class="giallo-l"><span> input_</span><span>:</span><span> ProgressiveByteList</span></span> <span class="giallo-l"><span> access_list</span><span>:</span><span> ProgressiveList</span><span>[</span><span>AccessTuple</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"> RlpAccessListCreateTransactionPayload</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> type_</span><span>:</span><span> TransactionType</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 0x01</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span> ChainId</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> max_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> gas</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> value</span><span>:</span><span> uint256</span></span> <span class="giallo-l"><span> input_</span><span>:</span><span> ProgressiveByteList</span></span> <span class="giallo-l"><span> access_list</span><span>:</span><span> ProgressiveList</span><span>[</span><span>AccessTuple</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>RlpAccessListTransactionPayload</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> RlpAccessListBasicTransactionPayload</span><span class="z-keyword"> |</span></span> <span class="giallo-l"><span> RlpAccessListCreateTransactionPayload</span></span> <span class="giallo-l"><span>)</span></span></code></pre><h4 id="eip-1559-fee-market-transactions">EIP-1559 fee market transactions</h4> <p>These transactions support specifying <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> priority fees.</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"> RlpBasicTransactionPayload</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> type_</span><span>:</span><span> TransactionType</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 0x02</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span> ChainId</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> max_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> gas</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> to</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> value</span><span>:</span><span> uint256</span></span> <span class="giallo-l"><span> input_</span><span>:</span><span> ProgressiveByteList</span></span> <span class="giallo-l"><span> access_list</span><span>:</span><span> ProgressiveList</span><span>[</span><span>AccessTuple</span><span>]</span></span> <span class="giallo-l"><span> max_priority_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</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"> RlpCreateTransactionPayload</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> type_</span><span>:</span><span> TransactionType</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 0x02</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span> ChainId</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> max_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> gas</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> value</span><span>:</span><span> uint256</span></span> <span class="giallo-l"><span> input_</span><span>:</span><span> ProgressiveByteList</span></span> <span class="giallo-l"><span> access_list</span><span>:</span><span> ProgressiveList</span><span>[</span><span>AccessTuple</span><span>]</span></span> <span class="giallo-l"><span> max_priority_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>RlpFeeMarketTransactionPayload</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> RlpBasicTransactionPayload</span><span class="z-keyword"> |</span></span> <span class="giallo-l"><span> RlpCreateTransactionPayload</span></span> <span class="giallo-l"><span>)</span></span></code></pre><h4 id="eip-4844-blob-transactions">EIP-4844 blob transactions</h4> <p>These transactions support specifying <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> blobs.</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"> RlpBlobTransactionPayload</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> type_</span><span>:</span><span> TransactionType</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 0x03</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span> ChainId</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> max_fees_per_gas</span><span>:</span><span> BlobFeesPerGas</span></span> <span class="giallo-l"><span> gas</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> to</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> value</span><span>:</span><span> uint256</span></span> <span class="giallo-l"><span> input_</span><span>:</span><span> ProgressiveByteList</span></span> <span class="giallo-l"><span> access_list</span><span>:</span><span> ProgressiveList</span><span>[</span><span>AccessTuple</span><span>]</span></span> <span class="giallo-l"><span> max_priority_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> blob_versioned_hashes</span><span>:</span><span> ProgressiveList</span><span>[</span><span>VersionedHash</span><span>]</span></span></code></pre><h4 id="eip-7702-set-code-transactions">EIP-7702 set code transactions</h4> <p>These transactions support specifying an <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> authorization list.</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"> RlpReplayableBasicAuthorizationPayload</span><span>(</span><span class="z-entity">ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> magic</span><span>:</span><span> TransactionType</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 0x05</span></span> <span class="giallo-l"><span> address</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</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"> RlpBasicAuthorizationPayload</span><span>(</span><span class="z-entity">ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> magic</span><span>:</span><span> TransactionType</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 0x05</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span> ChainId</span></span> <span class="giallo-l"><span> address</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</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"> RlpSetCodeAuthorizationPayload</span><span>(</span><span class="z-entity">CompatibleUnion</span><span>(</span><span>{</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">01</span><span>:</span><span> RlpReplayableBasicAuthorizationPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">02</span><span>:</span><span> RlpBasicAuthorizationPayload</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span><span>)</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-storage z-type">class</span><span class="z-entity z-name"> RlpSetCodeAuthorization</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> payload</span><span>:</span><span> RlpSetCodeAuthorizationPayload</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span> ExecutionSignature</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"> RlpSetCodeTransactionPayload</span><span>(</span></span> <span class="giallo-l"><span class="z-entity"> ProgressiveContainer</span><span>(</span><span class="z-variable">active_fields</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>:</span></span> <span class="giallo-l"><span> type_</span><span>:</span><span> TransactionType</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 0x04</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span> ChainId</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> max_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> gas</span><span>:</span><span> GasAmount</span></span> <span class="giallo-l"><span> to</span><span>:</span><span> ExecutionAddress</span></span> <span class="giallo-l"><span> value</span><span>:</span><span> uint256</span></span> <span class="giallo-l"><span> input_</span><span>:</span><span> ProgressiveByteList</span></span> <span class="giallo-l"><span> access_list</span><span>:</span><span> ProgressiveList</span><span>[</span><span>AccessTuple</span><span>]</span></span> <span class="giallo-l"><span> max_priority_fees_per_gas</span><span>:</span><span> BasicFeesPerGas</span></span> <span class="giallo-l"><span> authorization_list</span><span>:</span><span> ProgressiveList</span><span>[</span><span>RlpSetCodeAuthorization</span><span>]</span></span></code></pre><h4 id="transaction-helpers">Transaction helpers</h4> <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"> TransactionPayload</span><span>(</span><span class="z-entity">CompatibleUnion</span><span>(</span><span>{</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">01</span><span>:</span><span> RlpLegacyReplayableBasicTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">02</span><span>:</span><span> RlpLegacyReplayableCreateTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">03</span><span>:</span><span> RlpLegacyBasicTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">04</span><span>:</span><span> RlpLegacyCreateTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">05</span><span>:</span><span> RlpAccessListBasicTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">06</span><span>:</span><span> RlpAccessListCreateTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">07</span><span>:</span><span> RlpBasicTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">08</span><span>:</span><span> RlpCreateTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">09</span><span>:</span><span> RlpBlobTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">0a</span><span>:</span><span> RlpSetCodeTransactionPayload</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span><span>)</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-storage z-type">class</span><span class="z-entity z-name"> Transaction</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> payload</span><span>:</span><span> TransactionPayload</span></span> <span class="giallo-l"><span> signature</span><span>:</span><span> ExecutionSignature</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"> RlpTxType</span><span>(</span><span class="z-entity">IntEnum</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> LEGACY</span><span class="z-keyword"> =</span><span class="z-storage z-type"> 0x</span><span class="z-constant">00</span></span> <span class="giallo-l"><span class="z-constant"> ACCESS_LIST</span><span class="z-keyword"> =</span><span class="z-storage z-type"> 0x</span><span class="z-constant">01</span></span> <span class="giallo-l"><span class="z-constant"> FEE_MARKET</span><span class="z-keyword"> =</span><span class="z-storage z-type"> 0x</span><span class="z-constant">02</span></span> <span class="giallo-l"><span class="z-constant"> BLOB</span><span class="z-keyword"> =</span><span class="z-storage z-type"> 0x</span><span class="z-constant">03</span></span> <span class="giallo-l"><span class="z-constant"> SET_CODE</span><span class="z-keyword"> =</span><span class="z-storage z-type"> 0x</span><span class="z-constant">04</span></span> <span class="giallo-l"><span class="z-constant"> SET_CODE_MAGIC</span><span class="z-keyword"> =</span><span class="z-storage z-type"> 0x</span><span class="z-constant">05</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"> calculate_transaction_intrinsic_gas</span><span>(</span><span class="z-variable z-parameter z-function">tx</span><span>:</span><span> Transaction</span><span>)</span><span> -&gt;</span><span> uint</span><span>:</span></span> <span class="giallo-l"><span> tx_data</span><span class="z-keyword"> =</span><span> tx</span><span>.</span><span>payload</span><span>.</span><span>data</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> gas_cost</span><span class="z-keyword"> =</span><span class="z-constant"> TX_BASE_COST</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-keyword"> FIXME</span><span class="z-comment">: Should this be defined from another EIP?</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> hasattr</span><span>(</span><span>tx_data</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">authorization_list</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> auth</span><span class="z-keyword"> in</span><span> tx_data</span><span>.</span><span>authorization_list</span><span>:</span></span> <span class="giallo-l"><span> gas_cost</span><span class="z-keyword"> +=</span><span> get_signature_gas_cost</span><span>(</span><span>auth</span><span>.</span><span>signature</span><span>,</span><span class="z-variable"> expected_algorithm</span><span class="z-keyword">=</span><span>expected_signature_algorithm</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> gas_cost</span><span class="z-keyword"> +=</span><span> get_signature_gas_cost</span><span>(</span><span>tx</span><span>.</span><span>signature</span><span>,</span><span class="z-variable"> expected_algorithm</span><span class="z-keyword">=</span><span>expected_signature_algorithm</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> gas_cost</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_transaction</span><span>(</span><span class="z-variable z-parameter z-function">tx</span><span>:</span><span> Transaction</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> tx_data</span><span class="z-keyword"> =</span><span> tx</span><span>.</span><span>payload</span><span>.</span><span>data</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> expected_signature_algorithm</span><span class="z-keyword"> =</span><span class="z-constant"> None</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> hasattr</span><span>(</span><span>tx_data</span><span>,</span><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></span> <span class="giallo-l"><span> expected_signature_algorithm</span><span class="z-keyword"> =</span><span class="z-constant"> SECP256K1_ALGORITHM</span></span> <span class="giallo-l"><span class="z-keyword"> match</span><span> tx_data</span><span>.</span><span>type_</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span> RlpTxType</span><span>.</span><span class="z-constant">LEGACY</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> isinstance</span><span>(</span><span>tx_data</span><span>,</span><span> RlpLegacyTransactionPayload</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span> RlpTxType</span><span>.</span><span class="z-constant">ACCESS_LIST</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> isinstance</span><span>(</span><span>tx_data</span><span>,</span><span> RlpAccessListTransactionPayload</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span> RlpTxType</span><span>.</span><span class="z-constant">FEE_MARKET</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> isinstance</span><span>(</span><span>tx_data</span><span>,</span><span> RlpFeeMarketTransactionPayload</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span> RlpTxType</span><span>.</span><span class="z-constant">BLOB</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> isinstance</span><span>(</span><span>tx_data</span><span>,</span><span> RlpBlobTransactionPayload</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span> RlpTxType</span><span>.</span><span class="z-constant">SET_CODE</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> isinstance</span><span>(</span><span>tx_data</span><span>,</span><span> RlpSetCodeTransactionPayload</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span> _</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-constant"> False</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> hasattr</span><span>(</span><span>tx_data</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">authorization_list</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> auth</span><span class="z-keyword"> in</span><span> tx_data</span><span>.</span><span>authorization_list</span><span>:</span></span> <span class="giallo-l"><span> auth_data</span><span class="z-keyword"> =</span><span> auth</span><span>.</span><span>payload</span><span>.</span><span>data</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> hasattr</span><span>(</span><span>auth_data</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">magic</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> auth_data</span><span>.</span><span>magic</span><span class="z-keyword"> ==</span><span> RlpTxType</span><span>.</span><span class="z-constant">SET_CODE_MAGIC</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> hasattr</span><span>(</span><span>auth_data</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">chain_id</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> auth_data</span><span>.</span><span>chain_id</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> validate_execution_signature</span><span>(</span><span>auth</span><span>.</span><span>signature</span><span>,</span><span> compute_auth_hash</span><span>(</span><span>auth</span><span>)</span><span>,</span><span class="z-variable"> expected_algorithm</span><span class="z-keyword">=</span><span>expected_signature_algorithm</span><span>)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> validate_execution_signature</span><span>(</span><span>tx</span><span>.</span><span>signature</span><span>,</span><span> compute_sig_hash</span><span>(</span><span>tx</span><span>)</span><span>,</span><span class="z-variable"> expected_algorithm</span><span class="z-keyword">=</span><span>expected_signature_algorithm</span><span>)</span></span> <span class="giallo-l"></span></code></pre><h3 id="execution-block-header-changes">Execution block header changes</h3> <p>The <a rel="external" href="https://github.com/ethereum/devp2p/blob/bc76b9809a30e6dc5c8dcda996273f0f9bcf7108/caps/eth.md#block-encoding-and-validity">execution block header's <code>txs-root</code></a> is transitioned from MPT to SSZ.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>transactions</span><span class="z-keyword"> =</span><span> ProgressiveList</span><span>[</span><span>Transaction</span><span>]</span><span>(</span></span> <span class="giallo-l"><span> tx_0</span><span>,</span><span> tx_1</span><span>,</span><span> tx_2</span><span>,</span><span class="z-constant"> ...</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>block_header</span><span>.</span><span>transactions_root</span><span class="z-keyword"> =</span><span> transactions</span><span>.</span><span>hash_tree_root</span><span>(</span><span>)</span></span></code></pre><h3 id="engine-api">Engine API</h3> <p>In the engine API, the semantics of the <code>transactions</code> field in <code>ExecutionPayload</code> versions adopting this EIP are changed to emit transactions using SSZ serialization.</p> <ul> <li><code>transactions</code> - <code>Array</code> of <code>DATA</code> - Array of transaction objects, each object is a byte list (<code>DATA</code>) representing <code>ssz.serialize(tx)</code></li> </ul> <h3 id="consensus-executionpayload-changes">Consensus <code>ExecutionPayload</code> changes</h3> <p>When building a consensus <code>ExecutionPayload</code>, the <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b5c3b619887c7850a8c1d3540b471092be73ad84/specs/deneb/beacon-chain.md#executionpayload"><code>transactions</code></a> list is no longer opaque and uses the new <code>Transaction</code> type, aligning the <code>transactions_root</code> across execution blocks and execution payloads.</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"> ExecutionPayload</span><span>(</span><span class="z-constant">...</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"><span> transactions</span><span>:</span><span> ProgressiveList</span><span>[</span><span>Transaction</span><span>]</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre><h3 id="unique-transaction-identifier">Unique transaction identifier</h3> <p>For each transaction, an additional identifier <code>tx_root</code> SHALL be assigned:</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_tx_root</span><span>(</span><span class="z-variable z-parameter z-function">tx</span><span>:</span><span> Transaction</span><span>)</span><span> -&gt;</span><span> Hash32</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> Hash32</span><span>(</span><span>tx</span><span>.</span><span>hash_tree_root</span><span>(</span><span>)</span><span>)</span></span></code></pre> <p>Note that this <code>tx_root</code> differs from the existing <code>tx_hash</code>. Existing APIs based on <code>tx_hash</code> remain available.</p> <h2 id="rationale">Rationale</h2> <h3 id="forward-compatibility">Forward compatibility</h3> <p>The proposed transaction design is extensible with new fee types, new signature types, and entirely new transaction features (e.g., CREATE2), while retaining compatibility with the proposed transactions.</p> <h3 id="verifier-improvements">Verifier improvements</h3> <p>The <code>transactions_root</code> is effectively constructed from the list of <code>tx_root</code>, enabling transaction inclusion proofs. Further, partial data becomes provable, such as destination / amount without requiring the full calldata. This can reduce gas cost or zk proving cost when verifying L2 chain data in an L1 smart contract.</p> <h3 id="consensus-client-improvements">Consensus client improvements</h3> <p>Consensus Layer implementations may drop invalid blocks early if consensus <code>blob_kzg_commitments</code> do not validate against transaction <code>blob_versioned_hashes</code> and no longer need to query the Execution Layer for that validation. Future versions of the engine API could be simplified to drop the transfers of <code>blob_kzg_commitments</code> to the EL.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Applications that rely on the replaced MPT <code>transactions_root</code> in the block header require migration to the SSZ <code>transactions_root</code>.</p> <p>While there is no on-chain commitment of the <code>tx_hash</code>, it is widely used in JSON-RPC and the <a rel="external" href="https://github.com/ethereum/devp2p/blob/bc76b9809a30e6dc5c8dcda996273f0f9bcf7108/caps/eth.md">Ethereum Wire Protocol</a> to uniquely identify transactions. The conversion from RLP transactions to SSZ is lossless. The original RLP <code>sig_hash</code> and <code>tx_hash</code> can be recovered from the SSZ representation.</p> <p>RLP and SSZ transactions may clash when encoded. It is essential to use only a single format within one channel.</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-01-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Hadrien Crouboishttps://github.com/Amxx Francisco Giordanohttps://github.com/frangio https://wg-eips.ritovision.com/6372/

An interface for exposing a contract's clock value and details

<h2 id="abstract">Abstract</h2> <p>Many contracts rely on some clock for enforcing delays and storing historical data. While some contracts rely on block numbers, others use timestamps. There is currently no easy way to discover which time-tracking function a contract internally uses. This EIP proposes to standardize an interface for contracts to expose their internal clock and thus improve composability and interoperability.</p> <h2 id="motivation">Motivation</h2> <p>Many contracts check or store time-related information. For example, timelock contracts enforce a delay before an operation can be executed. Similarly, DAOs enforce a voting period during which stakeholders can approve or reject a proposal. Last but not least, voting tokens often store the history of voting power using timed snapshots.</p> <p>Some contracts do time tracking using timestamps while others use block numbers. In some cases, more exotic functions might be used to track time.</p> <p>There is currently no interface for an external observer to detect which clock a contract uses. This seriously limits interoperability and forces devs to make risky assumptions.</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>Compliant contracts MUST implement the <code>clock</code> and <code>CLOCK_MODE</code> functions as specified 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"> IERC6372</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> clock</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">uint48</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> CLOCK_MODE</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><h3 id="methods">Methods</h3> <h4 id="clock">clock</h4> <p>This function returns the current timepoint according to the mode the contract is operating on. It MUST be a <strong>non-decreasing</strong> function of the chain, such as <code>block.timestamp</code> or <code>block.number</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"> c</span><span class="z-string">lock</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><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 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">int48</span></span></code></pre><h4 id="clock-mode">CLOCK_MODE</h4> <p>This function returns a machine-readable string description of the clock the contract is operating on.</p> <p>This string MUST be formatted like a URL query string (a.k.a. <code>application/x-www-form-urlencoded</code>), decodable in standard JavaScript with <code>new URLSearchParams(CLOCK_MODE)</code>.</p> <ul> <li>If operating using <strong>block number</strong>: <ul> <li>If the block number is that of the <code>NUMBER</code> opcode (<code>0x43</code>), then this function MUST return <code>mode=blocknumber&amp;from=default</code>.</li> <li>If it is any other block number, then this function MUST return <code>mode=blocknumber&amp;from=&lt;CAIP-2-ID&gt;</code>, where <code>&lt;CAIP-2-ID&gt;</code> is a CAIP-2 Blockchain ID such as <code>eip155:1</code>.</li> </ul> </li> <li>If operating using <strong>timestamp</strong>, then this function MUST return <code>mode=timestamp</code>.</li> <li>If operating using any other mode, then this function SHOULD return a unique identifier for the encoded <code>mode</code> field.</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"> C</span><span class="z-string">LOCK_MODE</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><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 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">escriptor</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></code></pre><h3 id="expected-properties">Expected properties</h3> <ul> <li>The <code>clock()</code> function MUST be non-decreasing.</li> </ul> <h2 id="rationale">Rationale</h2> <p><code>clock</code> returns <code>uint48</code> as it is largely sufficient for storing realistic values. In timestamp mode, <code>uint48</code> will be enough until the year 8921556. Even in block number mode, with 10,000 blocks per second, it would be enough until the year 2861. Using a type smaller than <code>uint256</code> allows storage packing of timepoints with other associated values, greatly reducing the cost of writing and reading from storage.</p> <p>Depending on the evolution of the blockchain (particularly layer twos), using a smaller type, such as <code>uint32</code> might cause issues fairly quickly. On the other hand, anything bigger than <code>uint48</code> appears wasteful.</p> <p>In addition to timestamps, it is sometimes necessary to define durations or delays, which are a difference between timestamps. In the general case, we would expect these values to be represented with the same type than timepoints (<code>uint48</code>). However, we believe that in most cases <code>uint32</code> is a good alternative, as it represents over 136 years if the clock operates using seconds. In most cases, we recommend using <code>uint48</code> for storing timepoints and using <code>uint32</code> for storing durations. That recommendation applies to "reasonable" durations (delay for a timelock, voting or vesting duration, ...) when operating with timestamps or block numbers that are more than 1 second apart.</p> <h2 id="security-considerations">Security Considerations</h2> <p>No known 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> 2023-01-24T00:00:00+00:00 2026-02-11T14:48:25+00:00 Matt Solomonhttps://github.com/mds1 Toni Wahrstätterhttps://github.com/nerolation Ben DiFrancescohttps://github.com/apbendi Vitalik Buterinhttps://github.com/vbuterin Gary Ghayrathttps://github.com/garyghayrat https://wg-eips.ritovision.com/6538/

A canonical contract for entities to register stealth meta-addresses directly or through a third party using signatures.

<h2 id="abstract">Abstract</h2> <p>This specification defines a standardized way of storing and retrieving an entity's stealth meta-address, by extending <a href="https://wg-eips.ritovision.com/5564/">ERC-5564</a>. An entity may register their stealth meta-address directly. A third party can also register on behalf of an entity using a valid <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> or <a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a> signature. Once registered, the stealth meta-address for the entity can be retrieved by any smart contract or user. One can use the stealth meta-address with <code>generateStealthAddress</code> specified in <a href="https://wg-eips.ritovision.com/5564/">ERC-5564</a> to send assets to the generated stealth address without revealing the entity's address.</p> <h2 id="motivation">Motivation</h2> <p>The standardization of stealth address generation holds the potential to greatly enhance the privacy capabilities of Ethereum by enabling the recipient of a transfer to remain anonymous when receiving an asset. By introducing a central smart contract for users to store their stealth meta-addresses, EOAs and contracts can programmatically engage in stealth interactions using a variety of stealth address schemes.</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 contract defines an <code>ERC6538Registry</code> that stores the stealth meta-address for entities. These entities may be identified by an address, ENS name, or other identifier. This MUST be a singleton contract, with one instance per chain.</p> <p>The contract is specified below. A one byte integer is used to identify the stealth address scheme. This integer is used to differentiate between different stealth address schemes. This ERC outlines schemeId <code>1</code> as the SECP256k1 curve cryptographic scheme with view tags, as specified in <a href="https://wg-eips.ritovision.com/5564/">ERC-5564</a>.</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.23</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"> `ERC6538Registry` contract to map accounts to their stealth meta-address. See</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> [ERC-6538](https://eips.ethereum.org/EIPS/eip-6538) to learn more.</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC6538Registry</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 an invalid signature is provided to `registerKeysOnBehalf`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC6538Registry__InvalidSignature</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"> Next nonce expected from `user` to use when signing for `registerKeysOnBehalf`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `registrant` may be a standard 160-bit address or any other identifier.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `schemeId` is an integer identifier for the stealth address scheme.</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span> registrant </span><span class="z-keyword">=&gt;</span><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint256</span><span> schemeId </span><span class="z-keyword">=&gt;</span><span class="z-support"> bytes</span><span>)</span><span>)</span><span class="z-storage z-type"> public</span><span> stealthMetaAddressOf</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"> A nonce used to ensure a signature can only be used once.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `registrant` is the user address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `nonce` will be incremented after each valid `registerKeysOnBehalf` call.</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span> registrant </span><span class="z-keyword">=&gt;</span><span class="z-support"> uint256</span><span>)</span><span class="z-storage z-type"> public</span><span> nonceOf</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 EIP-712 type hash used in `registerKeysOnBehalf`.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> ERC6538REGISTRY_ENTRY_TYPE_HASH </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;Erc6538RegistryEntry(uint256 schemeId,bytes stealthMetaAddress,uint256 nonce)&quot;</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 chain ID where this contract is initially deployed.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> immutable</span><span> INITIAL_CHAIN_ID</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 domain separator used in this contract.</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"> immutable</span><span> INITIAL_DOMAIN_SEPARATOR</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"> Emitted when a registrant updates their stealth meta-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"> registrant</span><span class="z-comment"> The account that registered the stealth meta-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"> schemeId</span><span class="z-comment"> Identifier corresponding to the applied stealth address scheme, e.g. 1 for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> secp256k1, as specified in ERC-5564.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> stealthMetaAddress</span><span class="z-comment"> The stealth meta-address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> [ERC-5564](https://eips.ethereum.org/EIPS/eip-5564) bases the format for stealth</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> meta-addresses on [ERC-3770](https://eips.ethereum.org/EIPS/eip-3770) and specifies them as:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> st:&lt;shortName&gt;:0x&lt;spendingPubKey&gt;:&lt;viewingPubKey&gt;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The chain (`shortName`) is implicit based on the chain the `ERC6538Registry` is deployed on,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> therefore this `stealthMetaAddress` is just the compressed `spendingPubKey` and</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `viewingPubKey` concatenated.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> StealthMetaAddressSet</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"> registrant</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> schemeId</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> stealthMetaAddress</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"> Emitted when a registrant increments their nonce.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> registrant</span><span class="z-comment"> The account that incremented the nonce.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> newNonce</span><span class="z-comment"> The new nonce value.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> NonceIncremented</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> registrant</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> newNonce</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>)</span><span> {</span></span> <span class="giallo-l"><span> INITIAL_CHAIN_ID </span><span class="z-keyword">=</span><span class="z-variable z-language"> block</span><span>.</span><span>chainid</span><span>;</span></span> <span class="giallo-l"><span> INITIAL_DOMAIN_SEPARATOR </span><span class="z-keyword">=</span><span class="z-entity z-name"> _computeDomainSeparator</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-storage z-type"> @notice</span><span class="z-comment"> Sets the caller&#39;s stealth meta-address for the given scheme 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"> schemeId</span><span class="z-comment"> Identifier corresponding to the applied stealth address scheme, e.g. 1 for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> secp256k1, as specified in ERC-5564.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> stealthMetaAddress</span><span class="z-comment"> The stealth meta-address to register.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerKeys</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> schemeId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> stealthMetaAddress</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span> stealthMetaAddressOf</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>schemeId</span><span>]</span><span class="z-keyword"> =</span><span> stealthMetaAddress</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> StealthMetaAddressSet</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> schemeId</span><span>,</span><span> stealthMetaAddress</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"> @notice</span><span class="z-comment"> Sets the `registrant`&#39;s stealth meta-address for the given scheme 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"> registrant</span><span class="z-comment"> Address of the registrant.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> schemeId</span><span class="z-comment"> Identifier corresponding to the applied stealth address scheme, e.g. 1 for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> secp256k1, as specified in ERC-5564.</span></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"> A signature from the `registrant` authorizing the registration.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> stealthMetaAddress</span><span class="z-comment"> The stealth meta-address to register.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Supports both EOA signatures and EIP-1271 signatures.</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 the signature is invalid.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerKeysOnBehalf</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> registrant</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> schemeId</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"> signature</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"> stealthMetaAddress</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-support"> bytes32</span><span> dataHash</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> recoveredAddress</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> dataHash </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 class="z-entity z-name"> DOMAIN_SEPARATOR</span><span>(</span><span>)</span><span>,</span></span> <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">encode</span><span>(</span></span> <span class="giallo-l"><span> ERC6538REGISTRY_ENTRY_TYPE_HASH</span><span>,</span></span> <span class="giallo-l"><span> schemeId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span>stealthMetaAddress</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> nonceOf</span><span>[</span><span>registrant</span><span>]</span><span class="z-keyword">+</span><span class="z-keyword">+</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></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>signature</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-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"> uint8</span><span> v</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> assembly</span><span> (</span><span class="z-string">&quot;memory-safe&quot;</span><span>)</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>signature</span><span>,</span><span class="z-constant"> 0x20</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>signature</span><span>,</span><span class="z-constant"> 0x40</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>signature</span><span>,</span><span class="z-constant"> 0x60</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> recoveredAddress </span><span class="z-keyword">=</span><span class="z-support"> ecrecover</span><span>(</span><span>dataHash</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-keyword"> if</span><span> (</span></span> <span class="giallo-l"><span> (</span></span> <span class="giallo-l"><span> (</span><span>recoveredAddress </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> recoveredAddress </span><span class="z-keyword">!=</span><span> registrant</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> &amp;&amp;</span><span> (</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC1271</span><span>(</span><span>registrant</span><span>)</span><span>.</span><span class="z-entity z-name">isValidSignature</span><span>(</span><span>dataHash</span><span>,</span><span> signature</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> !=</span><span> IERC1271</span><span>.</span><span>isValidSignature</span><span>.</span><span>selector</span></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"> revert</span><span class="z-entity z-name"> ERC6538Registry__InvalidSignature</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> stealthMetaAddressOf</span><span>[</span><span>registrant</span><span>]</span><span>[</span><span>schemeId</span><span>]</span><span class="z-keyword"> =</span><span> stealthMetaAddress</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> StealthMetaAddressSet</span><span>(</span><span>registrant</span><span>,</span><span> schemeId</span><span>,</span><span> stealthMetaAddress</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"> @notice</span><span class="z-comment"> Increments the nonce of the sender to invalidate existing signatures.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> incrementNonce</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> unchecked</span><span> {</span></span> <span class="giallo-l"><span> nonceOf</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 class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> NonceIncremented</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> nonceOf</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></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 domain separator used in this contract.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The domain separator is re-computed if there&#39;s a chain fork.</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"> 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 class="z-keyword"> return</span><span class="z-variable z-language"> block</span><span>.</span><span>chainid </span><span class="z-keyword">==</span><span> INITIAL_CHAIN_ID </span><span class="z-keyword">?</span><span> INITIAL_DOMAIN_SEPARATOR </span><span class="z-keyword">:</span><span class="z-entity z-name"> _computeDomainSeparator</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-storage z-type"> @notice</span><span class="z-comment"> Computes the domain separator for this contract.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _computeDomainSeparator</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">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> <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> <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 class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;ERC6538Registry&quot;</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;1.0&quot;</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-language"> block</span><span>.</span><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 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-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Interface of the ERC1271 standard signature validation method for contracts as defined</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> in https://eips.ethereum.org/EIPS/eip-1271[ERC-1271].</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC1271</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"> Should return whether the signature provided is valid for the provided 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"> hash</span><span class="z-comment"> Hash of the data to be signed</span></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 byte array associated with _data</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isValidSignature</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> hash</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> <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">bytes4</span><span class="z-variable"> magicValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre> <p>The interface for this contract is defined below:</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.23</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 calling the `ERC6538Registry` contract to map accounts to their stealth</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> meta-address. See [ERC-6538](https://eips.ethereum.org/EIPS/eip-6538) to learn more.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6538Registry</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 an invalid signature is provided to `registerKeysOnBehalf`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC6538Registry__InvalidSignature</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"> @dev</span><span class="z-comment"> Emitted when a registrant updates their stealth meta-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"> registrant</span><span class="z-comment"> The account that registered the stealth meta-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"> schemeId</span><span class="z-comment"> Identifier corresponding to the applied stealth address scheme, e.g. 1 for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> secp256k1, as specified in ERC-5564.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> stealthMetaAddress</span><span class="z-comment"> The stealth meta-address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> [ERC-5564](https://eips.ethereum.org/EIPS/eip-5564) bases the format for stealth</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> meta-addresses on [ERC-3770](https://eips.ethereum.org/EIPS/eip-3770) and specifies them as:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> st:&lt;shortName&gt;:0x&lt;spendingPubKey&gt;:&lt;viewingPubKey&gt;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The chain (`shortName`) is implicit based on the chain the `ERC6538Registry` is deployed on,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> therefore this `stealthMetaAddress` is just the `spendingPubKey` and `viewingPubKey`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> concatenated.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> StealthMetaAddressSet</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"> registrant</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> schemeId</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> stealthMetaAddress</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"> Emitted when a registrant increments their nonce.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> registrant</span><span class="z-comment"> The account that incremented the nonce.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> newNonce</span><span class="z-comment"> The new nonce value.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> NonceIncremented</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> registrant</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> newNonce</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"> Sets the caller&#39;s stealth meta-address for the given scheme 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"> schemeId</span><span class="z-comment"> Identifier corresponding to the applied stealth address scheme, e.g. 1 for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> secp256k1, as specified in ERC-5564.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> stealthMetaAddress</span><span class="z-comment"> The stealth meta-address to register.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerKeys</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> schemeId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> stealthMetaAddress</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"> Sets the `registrant`&#39;s stealth meta-address for the given scheme 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"> registrant</span><span class="z-comment"> Address of the registrant.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> schemeId</span><span class="z-comment"> Identifier corresponding to the applied stealth address scheme, e.g. 1 for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> secp256k1, as specified in ERC-5564.</span></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"> A signature from the `registrant` authorizing the registration.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> stealthMetaAddress</span><span class="z-comment"> The stealth meta-address to register.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Supports both EOA signatures and EIP-1271 signatures.</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 the signature is invalid.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerKeysOnBehalf</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> registrant</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> schemeId</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"> signature</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"> stealthMetaAddress</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-storage z-type"> @notice</span><span class="z-comment"> Increments the nonce of the sender to invalidate existing signatures.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> incrementNonce</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"> Returns the domain separator used in this contract.</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the stealth meta-address for the given `registrant` and `schemeId`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> stealthMetaAddressOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> registrant</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> schemeId</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">bytes</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 EIP-712 type hash used in `registerKeysOnBehalf`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> ERC6538REGISTRY_ENTRY_TYPE_HASH</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"> Returns the nonce of the given `registrant`.</span></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"> registrant</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></code></pre><h3 id="deployment-method">Deployment Method</h3> <p>The <code>ERC6538Registry</code> contract is deployed at <code>0x6538E6bf4B0eBd30A8Ea093027Ac2422ce5d6538</code> using <code>CREATE2</code> via the deterministic deployer at <code>0x4e59b44847b379578588920ca78fbf26c0b4956c</code> with a salt of <code>0x7cac4e512b1768c627c9e711c7a013f1ad0766ef5125c59fb7161dade58da078</code>.</p> <h2 id="rationale">Rationale</h2> <p>Having a central smart contract for registering stealth meta-addresses has several benefits:</p> <ol> <li> <p>It guarantees interoperability with other smart contracts, as they can easily retrieve and utilize the registered stealth meta-addresses. This enables applications such as ENS or Gnosis Safe to use that information and integrate stealth addresses into their services.</p> </li> <li> <p>It ensures that users are not dependent on off-chain sources to retrieve a user's stealth meta-address.</p> </li> <li> <p>Registration of a stealth meta-address in this contract provides a standard way for users to communicate that they're ready to participate in stealth interactions.</p> </li> <li> <p>By deploying the registry as a singleton contract, multiple projects can access the same set of stealth meta-addresses, contributing to improved standardization.</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backward compatible.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>You can find an implementation of the <code>ERC6538Registry</code> contract <a href="https://wg-eips.ritovision.com/6538/./assets/contracts/ERC6538Registry.sol">here</a> and the interface <code>IERC6538Registry.sol</code> <a href="https://wg-eips.ritovision.com/6538/./assets/contracts/interfaces/IERC6538Registry.sol">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>In the event of a compromised private key, the registrant should promptly un-register from the stealth key registry to prevent loss of future funds sent to the compromised 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-01-22T00:00:00+00:00 2026-02-11T14:48:25+00:00 Bruno Škvorchttps://github.com/Swader Steven Pinedahttps://github.com/steven2308 Stevan Bogosavljevichttps://github.com/stevyhacker Jan Turkhttps://github.com/ThunderDeliverer https://wg-eips.ritovision.com/6381/

React to any Non-Fungible Tokens using Unicode emojis.

<h2 id="abstract">Abstract</h2> <p>The Public Non-Fungible Token Emote Repository standard provides an enhanced interactive utility for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> by allowing NFTs to be emoted at.</p> <p>This proposal introduces the ability to react to NFTs using Unicode standardized emoji in a public non-gated repository smart contract that is accessible at the same address in all of the networks.</p> <h2 id="motivation">Motivation</h2> <p>With NFTs being a widespread form of tokens in the Ethereum ecosystem and being used for a variety of use cases, it is time to standardize additional utility for them. Having the ability for anyone to interact with an NFT introduces an interactive aspect to owning an NFT and unlocks feedback-based NFT mechanics.</p> <p>This ERC introduces new utilities for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> based tokens in the following areas:</p> <ul> <li><a href="https://wg-eips.ritovision.com/6381/#interactivity">Interactivity</a></li> <li><a href="https://wg-eips.ritovision.com/6381/#feedback-based-evolution">Feedback based evolution</a></li> <li><a href="https://wg-eips.ritovision.com/6381/#valuation">Valuation</a></li> </ul> <h3 id="interactivity">Interactivity</h3> <p>The ability to emote on an NFT introduces the aspect of interactivity to owning an NFT. This can either reflect the admiration for the emoter (person emoting to an NFT) or can be a result of a certain action performed by the token's owner. Accumulating emotes on a token can increase its uniqueness and/or value.</p> <h3 id="feedback-based-evolution">Feedback based evolution</h3> <p>Standardized on-chain reactions to NFTs allow for feedback based evolution.</p> <p>Current solutions are either proprietary or off-chain and therefore subject to manipulation and distrust. Having the ability to track the interaction on-chain allows for trust and objective evaluation of a given token. Designing the tokens to evolve when certain emote thresholds are met incentivizes interaction with the token collection.</p> <h3 id="valuation">Valuation</h3> <p>Current NFT market heavily relies on previous values the token has been sold for, the lowest price of the listed token and the scarcity data provided by the marketplace. There is no real time indication of admiration or desirability of a specific token. Having the ability for users to emote to the tokens adds the possibility of potential buyers and sellers gauging the value of the token based on the impressions the token has collected.</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-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-6381 Emotable Extension for Non-Fungible Tokens</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-6381</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 ERC-165 identifier for this interface is 0xd9fac55a.</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.16</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"> IERC6381</span><span class="z-comment"> /*</span><span class="z-comment">is IERC165</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"> Used to notify listeners that the token with the specified ID has been emoted to or that the reaction has been revoked.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The event MUST only be emitted if the state of the emote is </span><span class="z-keyword">changed</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"> emoter</span><span class="z-comment"> Address of the account that emoted or revoked the reaction to 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"> collection</span><span class="z-comment"> Address of the collection smart contract containing the token being emoted to or having the reaction 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"> ID of 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"> emoji</span><span class="z-comment"> Unicode identifier of the emoji</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> on</span><span class="z-comment"> Boolean value signifying whether the token was emoted to (`true`) or if the reaction has been revoked (`false`)</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"> Emoted</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"> emoter</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"> collection</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"> bytes4</span><span class="z-variable"> emoji</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> on</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"> Used to get the number of emotes for a specific emoji on 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"> collection</span><span class="z-comment"> Address of the collection containing the token being checked for emoji count</span></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 token to check for emoji count</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emoji</span><span class="z-comment"> Unicode identifier of the emoji</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 emotes with the emoji 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"> emoteCountOf</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> bytes4</span><span class="z-variable"> emoji</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"> Used to get the number of emotes for a specific emoji on a set of 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"> collections</span><span class="z-comment"> An array of addresses of the collections containing the tokens being checked for emoji count</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> An array of IDs of the tokens to check for emoji count</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emojis</span><span class="z-comment"> An array of unicode identifiers of the emojis</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"> array of numbers of emotes with the emoji on 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"> bulkEmoteCountOf</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"> collections</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"> bytes4</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> emojis</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 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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to get the information on whether the specified address has used a specific emoji on a specific</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> emoter</span><span class="z-comment"> Address of the account we are checking for a reaction to 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"> collection</span><span class="z-comment"> Address of the collection smart contract containing the token being checked for emoji reaction</span></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 token being checked for emoji reaction</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emoji</span><span class="z-comment"> The ASCII emoji code being checked for reaction</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 value indicating whether the `emoter` has used the `emoji` on the token (`true`) or not</span></span> <span class="giallo-l"><span class="z-comment"> * (`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"> hasEmoterUsedEmote</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> emoter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> bytes4</span><span class="z-variable"> emoji</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"> Used to get the information on whether the specified addresses have used specific emojis on specific</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> emoters</span><span class="z-comment"> An array of addresses of the accounts we are checking for reactions to 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"> collections</span><span class="z-comment"> An array of addresses of the collection smart contracts containing the tokens being checked</span></span> <span class="giallo-l"><span class="z-comment"> * for emoji reactions</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> An array of IDs of the tokens being checked for emoji reactions</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emojis</span><span class="z-comment"> An array of the ASCII emoji codes being checked for reactions</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"> array of boolean values indicating whether the `emoter`s has used the `emoji`s on the tokens (`true`)</span></span> <span class="giallo-l"><span class="z-comment"> * or not (`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"> haveEmotersUsedEmotes</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"> emoters</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"> collections</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"> bytes4</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> emojis</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 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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to get the message to be signed by the `emoter` in order for the reaction to be submitted by someone</span></span> <span class="giallo-l"><span class="z-comment"> * else.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collection</span><span class="z-comment"> The address of the collection smart contract containing the token being emoted at</span></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 token being emoted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emoji</span><span class="z-comment"> Unicode identifier of the emoji</span></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"> Boolean value signifying whether to emote (`true`) or undo (`false`) emote</span></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"> UNIX timestamp of the deadline for the signature to be submitted</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"> message to be signed by the `emoter` in order for the reaction to be submitted by someone else</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"> prepareMessageToPresignEmote</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> bytes4</span><span class="z-variable"> emoji</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> state</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</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">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">@notice</span><span class="z-comment"> Used to get multiple messages to be signed by the `emoter` in order for the reaction to be submitted by someone</span></span> <span class="giallo-l"><span class="z-comment"> * else.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collections</span><span class="z-comment"> An array of addresses of the collection smart contracts containing the tokens being emoted at</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> An array of IDs of the tokens being emoted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emojis</span><span class="z-comment"> An arrau of unicode identifiers of the emojis</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> states</span><span class="z-comment"> An array of boolean values signifying whether to emote (`true`) or undo (`false`) emote</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> deadlines</span><span class="z-comment"> An array of UNIX timestamps of the deadlines for the signatures to be submitted</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"> array of messages to be signed by the `emoter` in order for the reaction to be submitted by someone else</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"> bulkPrepareMessagesToPresignEmote</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"> collections</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"> bytes4</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> emojis</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> states</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"> deadlines</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">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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to emote or undo an emote on 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"> Does nothing if attempting to set a pre-existent state.</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 the `Emoted` event is the state of the emote is </span><span class="z-keyword">changed</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"> collection</span><span class="z-comment"> Address of the collection containing the token being emoted at</span></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 token being emoted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emoji</span><span class="z-comment"> Unicode identifier of the emoji</span></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"> Boolean value signifying whether to emote (`true`) or undo (`false`) emote</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"> emote</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> bytes4</span><span class="z-variable"> emoji</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> state</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"> Used to emote or undo an emote on 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"> Does nothing if attempting to set a pre-existent state.</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 the `Emoted` event is the state of the emote is </span><span class="z-keyword">changed</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"> MUST revert if the lengths of the `collections`, `tokenIds`, `emojis` and `states` arrays are not equal.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collections</span><span class="z-comment"> An array of addresses of the collections containing the tokens being emoted at</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> An array of IDs of the tokens being emoted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emojis</span><span class="z-comment"> An array of unicode identifiers of the emojis</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> states</span><span class="z-comment"> An array of boolean values signifying whether to emote (`true`) or undo (`false`) emote</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"> bulkEmote</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"> collections</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"> bytes4</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> emojis</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> states</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"> Used to emote or undo an emote on someone else&#39;s behalf.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Does nothing if attempting to set a pre-existent state.</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 the `Emoted` event is the state of the emote is </span><span class="z-keyword">changed</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"> MUST revert if the lengths of the `collections`, `tokenIds`, `emojis` and `states` arrays are not equal.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the `deadline` has passed.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the recovered address is 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"> emoter</span><span class="z-comment"> The address that presigned the emote</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collection</span><span class="z-comment"> The address of the collection smart contract containing the token being emoted at</span></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"> IDs of the token being emoted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emoji</span><span class="z-comment"> Unicode identifier of the emoji</span></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"> Boolean value signifying whether to emote (`true`) or undo (`false`) emote</span></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"> UNIX timestamp of the deadline for the signature to be submitted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> v</span><span class="z-comment"> `v` value of an ECDSA signature of the message obtained via `prepareMessageToPresignEmote`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> r</span><span class="z-comment"> `r` value of an ECDSA signature of the message obtained via `prepareMessageToPresignEmote`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> s</span><span class="z-comment"> `s` value of an ECDSA signature of the message obtained via `prepareMessageToPresignEmote`</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"> presignedEmote</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> emoter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> collection</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"> bytes4</span><span class="z-variable"> emoji</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> state</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> deadline</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</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"> Used to bulk emote or undo an emote on someone else&#39;s behalf.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Does nothing if attempting to set a pre-existent state.</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 the `Emoted` event is the state of the emote is </span><span class="z-keyword">changed</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"> MUST revert if the lengths of the `collections`, `tokenIds`, `emojis` and `states` arrays are not equal.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the `deadline` has passed.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the recovered address is 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"> emoters</span><span class="z-comment"> An array of addresses of the accounts that presigned the emotes</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> collections</span><span class="z-comment"> An array of addresses of the collections containing the tokens being emoted at</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> An array of IDs of the tokens being emoted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> emojis</span><span class="z-comment"> An array of unicode identifiers of the emojis</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> states</span><span class="z-comment"> An array of boolean values signifying whether to emote (`true`) or undo (`false`) emote</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> deadlines</span><span class="z-comment"> UNIX timestamp of the deadline for the signature to be submitted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> v</span><span class="z-comment"> An array of `v` values of an ECDSA signatures of the messages obtained via `prepareMessageToPresignEmote`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> r</span><span class="z-comment"> An array of `r` values of an ECDSA signatures of the messages obtained via `prepareMessageToPresignEmote`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> s</span><span class="z-comment"> An array of `s` values of an ECDSA signatures of the messages obtained via `prepareMessageToPresignEmote`</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"> bulkPresignedEmote</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"> emoters</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"> collections</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"> bytes4</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> emojis</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> states</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"> deadlines</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"> v</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"> r</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"> s</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><h3 id="message-format-for-presigned-emotes">Message format for presigned emotes</h3> <p>The message to be signed by the <code>emoter</code> in order for the reaction to be submitted by someone else is formatted 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">encode</span><span>(</span></span> <span class="giallo-l"><span> DOMAIN_SEPARATOR</span><span>,</span></span> <span class="giallo-l"><span> collection</span><span>,</span></span> <span class="giallo-l"><span> tokenId</span><span>,</span></span> <span class="giallo-l"><span> emoji</span><span>,</span></span> <span class="giallo-l"><span> state</span><span>,</span></span> <span class="giallo-l"><span> deadline</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> )</span><span>;</span></span></code></pre> <p>The values passed when generating the message to be signed are:</p> <ul> <li><code>DOMAIN_SEPARATOR</code> - The domain separator of the Emotable repository smart contract</li> <li><code>collection</code> - Address of the collection containing the token being emoted at</li> <li><code>tokenId</code> - ID of the token being emoted</li> <li><code>emoji</code> - Unicode identifier of the emoji</li> <li><code>state</code> - Boolean value signifying whether to emote (<code>true</code>) or undo (<code>false</code>) emote</li> <li><code>deadline</code> - UNIX timestamp of the deadline for the signature to be submitted</li> </ul> <p>The <code>DOMAIN_SEPARATOR</code> is generated 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">encode</span><span>(</span></span> <span class="giallo-l"><span class="z-string"> &quot;ERC-6381: Public Non-Fungible Token Emote Repository&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;1&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-language"> block</span><span>.</span><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 class="giallo-l"><span> )</span><span>;</span></span></code></pre> <p>Each chain, that the Emotable repository smart contract is deployed on, will have a different <code>DOMAIN_SEPARATOR</code> value due to chain IDs being different.</p> <h3 id="pre-determined-address-of-the-emotable-repository">Pre-determined address of the Emotable repository</h3> <p>The address of the Emotable repository smart contract is designed to resemble the function it serves. It starts with <code>0x311073</code> which is the abstract representation of <code>EMOTE</code>. The address is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x31107354b61A0412E722455A771bC462901668eA</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Designing the proposal, we considered the following questions:</p> <ol> <li><strong>Does the proposal support custom emotes or only the Unicode specified ones?</strong><br /> The proposal only accepts the Unicode identifier which is a <code>bytes4</code> value. This means that while we encourage implementers to add the reactions using standardized emojis, the values not covered by the Unicode standard can be used for custom emotes. The only drawback being that the interface displaying the reactions will have to know what kind of image to render and such additions will probably be limited to the interface or marketplace in which they were made.</li> <li><strong>Should the proposal use emojis to relay the impressions of NFTs or some other method?</strong><br /> The impressions could have been done using user-supplied strings or numeric values, yet we decided to use emojis since they are a well established mean of relaying impressions and emotions.</li> <li><strong>Should the proposal establish an emotable extension or a common-good repository?</strong><br /> Initially we set out to create an emotable extension to be used with any ERC-721 compliant tokens. However, we realized that the proposal would be more useful if it was a common-good repository of emotable tokens. This way, the tokens that can be reacted to are not only the new ones but also the old ones that have been around since before the proposal.<br /> In line with this decision, we decided to calculate a deterministic address for the repository smart contract. This way, the repository can be used by any NFT collection without the need to search for the address on the given chain.</li> <li><strong>Should we include only single-action operations, only multi-action operations, or both?</strong><br /> We've considered including only single-action operations, where the user is only able to react with a single emoji to a single token, but we decided to include both single-action and multi-action operations. This way, the users can choose whether they want to emote or undo emote on a single token or on multiple tokens at once.<br /> This decision was made for the long-term viability of the proposal. Based on the gas cost of the network and the number of tokens in the collection, the user can choose the most cost-effective way of emoting.</li> <li><strong>Should we add the ability to emote on someone else's behalf?</strong><br /> While we did not intend to add this as part of the proposal when drafting it, we realized that it would be a useful feature for it. This way, the users can emote on behalf of someone else, for example, if they are not able to do it themselves or if the emote is earned through an off-chain activity.</li> <li><strong>How do we ensure that emoting on someone else's behalf is legitimate?</strong><br /> We could add delegates to the proposal; when a user delegates their right to emote to someone else, the delegate can emote on their behalf. However, this would add a lot of complexity and additional logic to the proposal.<br /> Using ECDSA signatures, we can ensure that the user has given their consent to emote on their behalf. This way, the user can sign a message with the parameters of the emote and the signature can be submitted by someone else.</li> <li><strong>Should we add chain ID as a parameter when reacting to a token?</strong><br /> During the course of discussion of the proposal, a suggestion arose that we could add chain ID as a parameter when reacting to a token. This would allow the users to emote on the token of one chain on another chain.<br /> We decided against this as we feel that additional parameter would rarely be used and would add additional cost to the reaction transactions. If the collection smart contract wants to utilize on-chain emotes to tokens they contain, they require the reactions to be recorded on the same chain. Marketplaces and wallets integrating this proposal will rely on reactions to reside in the same chain as well, because if chain ID parameter was supported this would mean that they would need to query the repository smart contract on all of the chains the repository is deployed in order to get the reactions for a given token.<br /> Additionally, if the collection creator wants users to record their reactions on a different chain, they can still direct the users to do just that. The repository does not validate the existence of the token being reacted to, which in theory means that you can react to non-existent token or to a token that does not exist yet. The likelihood of a different collection existing at the same address on another chain is significantly low, so the users can react using the collection's address on another chain and it is very unlikely that they will unintentionally react to another collection's token.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The Emote repository standard is fully compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and with the robust tooling available for implementations of ERC-721 as well as with the existing ERC-721 infrastructure.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests are included in <a href="https://wg-eips.ritovision.com/6381/./assets/test/emotableRepository.ts"><code>emotableRepository.ts</code></a>.</p> <p>To run them in terminal, you can use the following commands:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cd ../assets/eip-6381</span></span> <span class="giallo-l"><span>npm install</span></span> <span class="giallo-l"><span>npx hardhat test</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/6381/./assets/contracts/EmotableRepository.sol"><code>EmotableRepository.sol</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The proposal does not envision handling any form of assets from the user, so the assets should not be at risk when interacting with an Emote repository.</p> <p>The ability to use ECDSA signatures to emote on someone else's behalf introduces the risk of a replay attack, which the format of the message to be signed guards against. The <code>DOMAIN_SEPARATOR</code> used in the message to be signed is unique to the repository smart contract of the chain it is deployed on. This means that the signature is invalid on any other chain and the Emote repositories deployed on them should revert the operation if a replay attack is attempted.</p> <p>Another thing to consider is the ability of presigned message reuse. Since the message includes the signature validity deadline, the message can be reused any number of times before the deadline is reached. The proposal only allows for a single reaction with a given emoji to a specific token to be active, so the presigned message can not be abused to increase the reaction count on the token. However, if the service using the repository relies on the ability to revoke the reaction after certain actions, a valid presigned message can be used to re-react to the token. We suggest that the services using the repository in cnjunction with presigned messages use deadlines that invalidate presigned messages after a reasonalby short period of time.</p> <p>Caution is advised when dealing with non-audited 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> 2023-01-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/6357/

Allows an EOA to call multiple functions of a smart contract in a single transaction

<h2 id="abstract">Abstract</h2> <p>This EIP standardizes an interface containing a single function, <code>multicall</code>, allowing EOAs to call multiple functions of a smart contract in a single transaction, and revert all calls if any call fails.</p> <h2 id="motivation">Motivation</h2> <p>Currently, in order to transfer several <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> NFTs, one needs to submit a number of transactions equal to the number of NFTs being tranferred. This wastes users' funds by requiring them to pay 21000 gas fee for every NFT they transfer.</p> <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>Contracts implementing this EIP must implement the following 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"> IMulticall</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"> Takes an array of abi-encoded call data, delegatecalls itself with each calldata, and returns the abi-encoded result</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 any delegatecall reverts</span></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 abi-encoded data</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> @returns results The abi-encoded return values</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> multicall</span><span>(</span><span class="z-support">bytes</span><span>[</span><span>]</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"> virtual</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"> results</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"> OPTIONAL. Takes an array of abi-encoded call data, delegatecalls itself with each calldata, and returns the abi-encoded result</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 any delegatecall reverts</span></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 abi-encoded 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"> values</span><span class="z-comment"> The effective msg.values. These must add up to at most msg.value</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> @returns results The abi-encoded return values</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> multicallPayable</span><span>(</span><span class="z-support">bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> data</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> values</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span class="z-storage z-type"> virtual</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"> results</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p><code>multicallPayable</code> is optional because it isn't always feasible to implement, due to the <code>msg.value</code> splitting.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is compatible with most existing multicall functions.</p> <h2 id="test-cases">Test Cases</h2> <p>The following JavaScript code, using the Ethers library, should atomically transfer <code>amt</code> units of an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token to both <code>addressA</code> and <code>addressB</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-keyword">await</span><span class="z-variable z-other"> token</span><span>.</span><span class="z-entity z-name">multicall</span><span>(</span><span class="z-keyword">await</span><span class="z-support"> Promise</span><span>.</span><span class="z-entity z-name">all</span><span>(</span><span>[</span></span> <span class="giallo-l"><span class="z-variable z-other"> token</span><span>.</span><span class="z-variable z-other">interface</span><span>.</span><span class="z-entity z-name">encodeFunctionData</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">transfer</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> [</span><span class="z-variable z-other"> addressA</span><span>,</span><span class="z-variable z-other"> amt</span><span> ]</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> token</span><span>.</span><span class="z-variable z-other">interface</span><span>.</span><span class="z-entity z-name">encodeFunctionData</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">transfer</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> [</span><span class="z-variable z-other"> addressB</span><span>,</span><span class="z-variable z-other"> amt</span><span> ]</span><span>)</span><span>,</span></span> <span class="giallo-l"><span>]</span><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.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Derived from OpenZeppelin&#39;s implementation</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"> Multicall</span><span class="z-storage"> is</span><span class="z-entity z-name"> IMulticall</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> multicall</span><span>(</span><span class="z-support">bytes</span><span>[</span><span>]</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"> virtual</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"> results</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> results </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> bytes</span><span>[](</span><span class="z-variable">data</span><span>.</span><span class="z-variable">length</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> data</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><span class="z-support">bool</span><span> success</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> returndata</span><span>)</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 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>;</span></span> <span class="giallo-l"><span> results</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span> returndata</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> results</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><code>multicallPayable</code> should only be used if the contract is able to support it. A naive attempt at implementing it could allow an attacker to call a payable function multiple times with the same ether.</p> <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-17T00:00:00+00:00 2026-02-11T14:48:26+00:00 Shawn Zhenghttps://github.com/xiyu1984 Jason Chengchengjingxx@gmail.com George Huanghttps://github.com/virgil2019 Kay Linhttps://github.com/kay404 https://wg-eips.ritovision.com/6358/

A paradigm to synchronize token states over multiple existing public chains

<h2 id="abstract">Abstract</h2> <p>This ERC standardizes an interface for contract-layer consensus-agnostic verifiable cross-chain bridging, through which we can define a new global token inherited from <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>/<a href="https://wg-eips.ritovision.com/721/">ERC-721</a> over multi-chains.</p> <h3 id="figure-1-architecture">Figure.1 Architecture</h3> <p><img src="https://wg-eips.ritovision.com/6358/./assets/img/o-dlt.png" alt="img" /></p> <p>With this ERC, we can create a global token protocol, that leverages smart contracts or similar mechanisms on existing blockchains to record the token states synchronously. The synchronization could be made by trustless off-chain synchronizers.</p> <h2 id="motivation">Motivation</h2> <ul> <li>The current paradigm of token bridges makes assets fragment.</li> <li>If ETH was transferred to another chain through the current token bridge, if the chain broke down, ETH will be lost for users.</li> </ul> <p>The core of this ERC is synchronization instead of transferring, even if all the other chains break down, as long as Ethereum is still running, user’s assets will not be lost.</p> <ul> <li>The fragment problem will be solved.</li> <li>The security of users' multi-chain assets can be greatly enhanced.</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> <h3 id="omniverse-account">Omniverse Account</h3> <p>There SHOULD be a global user identifier of this ERC, which is RECOMMENDED to be referred to as Omniverse Account (<code>o-account</code> for short) in this article.<br /> The <code>o-account</code> is RECOMMENDED to be expressed as a public key created by the elliptic curve <code>secp256k1</code>. A <a href="https://wg-eips.ritovision.com/6358/#mapping-mechanism-for-different-environments">mapping mechanism</a> is RECOMMENDED for different environments.</p> <h3 id="data-structure">Data Structure</h3> <p>An Omniverse Transaction (<code>o-transaction</code> for short) MUST be described with the following data structure:</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"> Omniverse transaction data structure</span></span> <span class="giallo-l"><span class="z-comment"> * @member nonce: The number of the o-transactions. If the current nonce of an omniverse account is `k`, the valid nonce of this o-account in the next o-transaction is `k+1`. </span></span> <span class="giallo-l"><span class="z-comment"> * @member chainId: The chain where the o-transaction is initiated</span></span> <span class="giallo-l"><span class="z-comment"> * @member initiateSC: The contract address from which the o-transaction is first initiated</span></span> <span class="giallo-l"><span class="z-comment"> * @member from: The Omniverse account which signs the o-transaction</span></span> <span class="giallo-l"><span class="z-comment"> * @member payload: The encoded business logic data, which is maintained by the developer</span></span> <span class="giallo-l"><span class="z-comment"> * @member signature: The signature of the above informations. </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"> ERC6358TransactionData</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint128</span><span> nonce</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> chainId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> initiateSC</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> from</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> payload</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> signature</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li> <p>The data structure <code>ERC6358TransactionData</code> MUST be defined as above.</p> </li> <li> <p>The member <code>nonce</code> MUST be defined as <code>uint128</code> due to better compatibility for more tech stacks of blockchains.</p> </li> <li> <p>The member <code>chainId</code> MUST be defined as <code>uint32</code>.</p> </li> <li> <p>The member <code>initiateSC</code> MUST be defined as <code>bytes</code>.</p> </li> <li> <p>The member <code>from</code> MUST be defined as <code>bytes</code>.</p> </li> <li> <p>The member <code>payload</code> MUST be defined as <code>bytes</code>. It is encoded from a user-defined data related to the o-transaction. For example:</p> <ul> <li> <p>For fungible tokens it is RECOMMENDED 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">@notice</span><span class="z-comment"> Fungible token data structure, from which the field `payload` in `ERC6358TransactionData` will be encoded</span></span> <span class="giallo-l"><span class="z-comment">*</span></span> <span class="giallo-l"><span class="z-comment">* @member op: The operation type</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-keyword">NOTE</span><span class="z-comment"> op: 0-31 are reserved values, 32-255 are custom values</span></span> <span class="giallo-l"><span class="z-comment">* op: 0 - omniverse account `from` transfers `amount` tokens to omniverse account `exData`, `from` have at least `amount` tokens</span></span> <span class="giallo-l"><span class="z-comment">* op: 1 - omniverse account `from` mints `amount` tokens to omniverse account `exData`</span></span> <span class="giallo-l"><span class="z-comment">* op: 2 - omniverse account `from` burns `amount` tokens from his own, `from` have at least `amount` tokens</span></span> <span class="giallo-l"><span class="z-comment">* @member exData: The operation data. This sector could be empty and is determined by `op`. For example: </span></span> <span class="giallo-l"><span class="z-comment"> when `op` is 0 and 1, `exData` stores the omniverse account that receives.</span></span> <span class="giallo-l"><span class="z-comment"> when `op` is 2, `exData` is empty.</span></span> <span class="giallo-l"><span class="z-comment">* @member amount: The amount of tokens being operated</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"> Fungible</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> op</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> exData</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></code></pre> <ul> <li>The related raw data for <code>signature</code> in <code>o-transaction</code> is RECOMMENDED to be the concatenation of the raw bytes of <code>op</code>, <code>exData</code>, and <code>amount</code>.</li> </ul> </li> <li> <p>For non-fungible tokens it is RECOMMENDED 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">@notice</span><span class="z-comment"> Non-Fungible token data structure, from which the field `payload` in `ERC6358TransactionData` will be encoded</span></span> <span class="giallo-l"><span class="z-comment">*</span></span> <span class="giallo-l"><span class="z-comment">* @member op: The operation type</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-keyword">NOTE</span><span class="z-comment"> op: 0-31 are reserved values, 32-255 are custom values</span></span> <span class="giallo-l"><span class="z-comment">* op: 0 omniverse account `from` transfers token `tokenId` to omniverse account `exData`, `from` have the token with `tokenId`</span></span> <span class="giallo-l"><span class="z-comment">* op: 1 omniverse account `from` mints token `tokenId` to omniverse account `exData`</span></span> <span class="giallo-l"><span class="z-comment">* op: 2 omniverse account `from` burns token `tokenId`, `from` have the token with `tokenId`</span></span> <span class="giallo-l"><span class="z-comment">* @member exData: The operation data. This sector could be empty and is determined by `op`</span></span> <span class="giallo-l"><span class="z-comment">* when `op` is 0 and 1, `exData` stores the omniverse account that receives.</span></span> <span class="giallo-l"><span class="z-comment"> when `op` is 2, `exData` is empty.</span></span> <span class="giallo-l"><span class="z-comment">* @member tokenId: The tokenId of the non-fungible token being operated</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"> NonFungible</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> op</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> exData</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></code></pre> <ul> <li>The related raw data for <code>signature</code> in <code>o-transaction</code> is RECOMMENDED to be the concatenation of the raw bytes of <code>op</code>, <code>exData</code>, and <code>tokenId</code>.</li> </ul> </li> </ul> </li> <li> <p>The member <code>signature</code> MUST be defined as <code>bytes</code>. It is RECOMMENDED to be created as follows.</p> <ul> <li> <p>It is OPTIONAL that concating the sectors in <code>ERC6358TransactionData</code> as below (take Fungible token for example) and calculate the hash with <code>keccak256</code>:</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"> Decode `_data` from bytes to Fungible</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"> `Fungible` instance</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"> decodeData</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"> _data</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-storage z-type">Fungible</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> (</span><span class="z-support">uint8</span><span> op</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> exData</span><span>,</span><span class="z-support"> uint256</span><span> amount</span><span>)</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>_data</span><span>,</span><span> (</span><span class="z-support">uint8</span><span>,</span><span class="z-support"> bytes</span><span>,</span><span class="z-support"> uint256</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> Fungible</span><span>(</span><span>op</span><span>,</span><span> exData</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">@notice</span><span class="z-comment"> Get the hash of a 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"> Hash</span><span class="z-comment"> value of the raw data of an `ERC6358TransactionData` instance</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"> getTransactionHash</span><span>(</span><span class="z-storage z-type">ERC6358TransactionData</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _data</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> Fungible </span><span class="z-storage z-type">memory</span><span> fungible </span><span class="z-keyword">=</span><span class="z-entity z-name"> decodeData</span><span>(</span><span>_data</span><span>.</span><span>payload</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> payload </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>fungible</span><span>.</span><span>op</span><span>,</span><span> fungible</span><span>.</span><span>exData</span><span>,</span><span> fungible</span><span>.</span><span>amount</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> rawData </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>_data</span><span>.</span><span>nonce</span><span>,</span><span> _data</span><span>.</span><span>chainId</span><span>,</span><span> _data</span><span>.</span><span>initiateSC</span><span>,</span><span> _data</span><span>.</span><span>from</span><span>,</span><span> payload</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>rawData</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre></li> <li> <p>It is OPTIONAL that encapsulating the sectors in <code>ERC6358TransactionData</code> according to <code>EIP-712</code>.</p> </li> <li> <p>Sign the hash value.</p> </li> </ul> </li> </ul> <h3 id="smart-contract-interface">Smart Contract Interface</h3> <ul> <li> <p>Every <a href="https://wg-eips.ritovision.com/6358/">ERC-6358</a> compliant contract MUST implement the <code>IERC6358</code></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"> Interface of the ERC-6358</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"> IERC6358</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 a o-transaction which has nonce `nonce` and was signed by user `pk` is sent by calling {sendOmniverseTransaction}</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"> TransactionSent</span><span>(</span><span class="z-support">bytes</span><span class="z-variable"> pk</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> nonce</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"> Sends an `o-transaction` </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><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">: MUST implement the validation of the `_data.signature`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">Note</span><span class="z-comment">: A map maintaining the `o-account` and the related transaction nonce is RECOMMENDED </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">Note</span><span class="z-comment">: MUST implement the validation of the `_data.nonce` according to the current account nonce</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">Note</span><span class="z-comment">: MUST implement the validation of the `_data. payload`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">Note</span><span class="z-comment">: This interface is just for sending an `o-transaction`, and the execution MUST NOT be within this interface </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">Note</span><span class="z-comment">: The actual execution of an `o-transaction` is RECOMMENDED to be in another function and MAY be delayed for a 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"> _data</span><span class="z-comment">: the `o-transaction` data with type {ERC6358TransactionData}</span></span> <span class="giallo-l"><span class="z-comment"> * See more information in the definition of {ERC6358TransactionData}</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emit a {TransactionSent} 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"> sendOmniverseTransaction</span><span>(</span><span class="z-storage z-type">ERC6358TransactionData</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>;</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 number of omniverse transactions sent by user `_pk`, </span></span> <span class="giallo-l"><span class="z-comment"> * which is also the valid `nonce` of a new omniverse transactions of user `_pk` </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _pk</span><span class="z-comment">: Omniverse account to be 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"> The</span><span class="z-comment"> number of omniverse transactions sent by user `_pk`</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"> getTransactionCount</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"> _pk</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 transaction data `txData` and timestamp `timestamp` of the user `_use` at a specified nonce `_nonce`</span></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"> Omniverse account to be 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"> _nonce</span><span class="z-comment"> The nonce to be 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"> Returns</span><span class="z-comment"> the transaction data `txData` and timestamp `timestamp` of the user `_use` at a specified nonce `_nonce`</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"> getTransactionData</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"> _user</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-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">ERC6358TransactionData</span><span class="z-storage z-type"> memory</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 chain 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"> Returns</span><span class="z-comment"> the chain 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"> getChainId</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">uint32</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li>The <code>sendOmniverseTransaction</code> function MAY be implemented as <code>public</code> or <code>external</code></li> <li>The <code>getTransactionCount</code> function MAY be implemented as <code>public</code> or <code>external</code></li> <li>The <code>getTransactionData</code> function MAY be implemented as <code>public</code> or <code>external</code></li> <li>The <code>getChainId</code> function MAY be implemented as <code>pure</code> or <code>view</code></li> <li>The <code>TransactionSent</code> event MUST be emitted when <code>sendOmniverseTransaction</code> function is called</li> </ul> </li> <li> <p>Optional Extension: Fungible Token</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> import &quot;{IERC6358.sol}&quot;;</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 the ERC-6358 fungible token, which inherits {IERC6358}</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"> IERC6358Fungible</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6358</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"> Get the omniverse balance of a user `_pk`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _pk</span><span class="z-comment"> `o-account` to be 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"> Returns</span><span class="z-comment"> the omniverse balance of a user `_pk`</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"> omniverseBalanceOf</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"> _pk</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> <ul> <li>The <code>omniverseBalanceOf</code> function MAY be implemented as <code>public</code> or <code>external</code></li> </ul> </li> <li> <p>Optional Extension: NonFungible Token</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;{IERC6358.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 the ERC-6358 non fungible token, which inherits {IERC6358}</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"> IERC6358NonFungible</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6358</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"> Get the number of omniverse NFTs in account `_pk`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _pk</span><span class="z-comment"> `o-account` to be 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"> Returns</span><span class="z-comment"> the number of omniverse NFTs in account `_pk`</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"> omniverseBalanceOf</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"> _pk</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 owner of an omniverse NFT with `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"> _tokenId</span><span class="z-comment"> Omniverse NFT id to be 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"> Returns</span><span class="z-comment"> the owner of an omniverse NFT with `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"> omniverseOwnerOf</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">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li>The <code>omniverseBalanceOf</code> function MAY be implemented as <code>public</code> or <code>external</code></li> <li>The <code>omniverseOwnerOf</code> function MAY be implemented as <code>public</code> or <code>external</code></li> </ul> </li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="architecture">Architecture</h3> <p>As shown in <a href="https://wg-eips.ritovision.com/6358/#figure-1-architecture">Figure.1</a>, smart contracts deployed on multi-chains execute <code>o-transactions</code> of ERC-6358 tokens synchronously through the trustless off-chain synchronizers.</p> <ul> <li>The ERC-6358 smart contracts are referred to as <strong>Abstract Nodes</strong>. The states recorded by the Abstract Nodes that are deployed on different blockchains respectively could be considered as copies of the global state, and they are ultimately consistent.</li> <li><strong>Synchronizer</strong> is an off-chain execution program responsible for carrying published <code>o-transactions</code> from the ERC-6358 smart contracts on one blockchain to the others. The synchronizers work trustless as they just deliver <code>o-transactions</code> with others' signatures, and details could be found in the <a href="https://wg-eips.ritovision.com/6358/#workflow">workflow</a>.</li> </ul> <h3 id="principle">Principle</h3> <ul> <li> <p>The <code>o-account</code> has been mentioned <a href="https://wg-eips.ritovision.com/6358/#omniverse-account">above</a>.</p> </li> <li> <p>The synchronization of the <code>o-transactions</code> guarantees the ultimate consistency of token states across all chains. The related data structure is <a href="https://wg-eips.ritovision.com/6358/#data-structure">here</a>.</p> <ul> <li>A <code>nonce</code> mechanism is brought in to make the states consistent globally.</li> <li>The <code>nonce</code> appears in two places, the one is <code>nonce in o-transaction</code> data structure, and the other is <code>account nonce</code> maintained by on-chain ERC-6358 smart contracts.</li> <li>When synchronizing, the <code>nonce in o-transaction</code> data will be checked by comparing it to the <code>account nonce</code>.</li> </ul> </li> </ul> <h4 id="workflow">Workflow</h4> <ul> <li>Suppose a common user <code>A</code> and her related operation <code>account nonce</code> is $k$.</li> <li><code>A</code> initiates an <code>o-transaction</code> on Ethereum by calling <code>IERC6358::sendOmniverseTransaction</code>. The current <code>account nonce</code> of <code>A</code> in the ERC-6358 smart contracts deployed on Ethereum is $k$ so the valid value of <code>nonce in o-transaction</code> needs to be $k+1$.</li> <li>The ERC-6358 smart contracts on Ethereum verify the signature of the <code>o-transaction</code> data. If the verification succeeds, the <code>o-transaction</code> data will be published by the smart contracts on the Ethereum side. The verification includes: <ul> <li>whether the balance (FT) or the ownership (NFT) is valid</li> <li>and whether the <code>nonce in o-transaction</code> is $k+1$</li> </ul> </li> <li>The <code>o-transaction</code> SHOULD NOT be executed on Ethereum immediately, but wait for a time.</li> <li>Now, <code>A</code>'s latest submitted <code>nonce in o-transaction</code> on Ethereum is $k+1$, but still $k$ on other chains.</li> <li>The off-chain synchronizers will find a newly published <code>o-transaction</code> on Ethereum but not on other chains.</li> <li>Next synchronizers will rush to deliver this message because of a rewarding mechanism. (The strategy of the reward could be determined by the deployers of ERC-6358 tokens. For example, the reward could come from the service fee or a mining mechanism.)</li> <li>Finally, the ERC-6358 smart contracts deployed on other chains will all receive the <code>o-transaction</code> data, verify the signature and execute it when the <strong>waiting time is up</strong>.</li> <li>After execution, the <code>account nonce</code> on all chains will add 1. Now all the <code>account nonce</code> of account <code>A</code> will be $k+1$, and the state of the balances of the related account will be the same too.</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="omniverse-account-1">Omniverse Account</h3> <ul> <li>An Omniverse Account example: <code>3092860212ceb90a13e4a288e444b685ae86c63232bcb50a064cb3d25aa2c88a24cd710ea2d553a20b4f2f18d2706b8cc5a9d4ae4a50d475980c2ba83414a796</code> <ul> <li>The Omniverse Account is a public key of the elliptic curve <code>secp256k1</code></li> <li>The related private key of the example is: <code>cdfa0e50d672eb73bc5de00cc0799c70f15c5be6b6fca4a1c82c35c7471125b6</code></li> </ul> </li> </ul> <h4 id="mapping-mechanism-for-different-environments">Mapping Mechanism for Different Environments</h4> <p>In the simplest implementation, we can just build two mappings to get it. One is like <code>pk based on sece256k1 =&gt; account address in the special environment</code>, and the other is the reverse mapping.</p> <p>The <code>Account System</code> on <code>Flow</code> is a typical example.</p> <ul> <li><code>Flow</code> has a built-in mechanism for <code>account address =&gt; pk</code>. The public key can be bound to an account (a special built-in data structure) and the public key can be got from the <code>account address</code> directly.</li> <li>A mapping from <code>pk</code> to the <code>account address</code> on Flow can be built by creating a mapping <code>{String: Address}</code>, in which <code>String</code> denotes the data type to express the public key and the <code>Address</code> is the data type of the <code>account address</code> on Flow.</li> </ul> <h3 id="erc-6358-token">ERC-6358 Token</h3> <p>The ERC-6358 Token could be implemented with the <a href="https://wg-eips.ritovision.com/6358/#smart-contract-interface">interfaces mentioned above</a>. It can also be used with the combination of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>/<a href="https://wg-eips.ritovision.com/721/">ERC-721</a>.</p> <ul> <li> <p>The implementation examples of the interfaces can be found at:</p> <ul> <li><a href="https://wg-eips.ritovision.com/6358/./assets/src/contracts/interfaces/IERC6358.sol">Interface <code>IERC6358</code></a>, the basic ERC-6358 interface mentioned <a href="https://wg-eips.ritovision.com/6358/#smart-contract-interface">above</a></li> <li><a href="https://wg-eips.ritovision.com/6358/./assets/src/contracts/interfaces/IERC6358Fungible.sol">Interface <code>IERC6358Fungible</code></a>, the interface for ERC-6358 fungible token</li> <li><a href="https://wg-eips.ritovision.com/6358/./assets/src/contracts/interfaces/IERC6358NonFungible.sol">Interface <code>IERC6358NonFungible</code></a>, the interface for ERC-6358 non-fungible token</li> </ul> </li> <li> <p>The implementation example of some common tools to operate ERC-6358 can be found at:</p> <ul> <li><a href="https://wg-eips.ritovision.com/6358/./assets/src/contracts/libraries/OmniverseProtocolHelper.sol">Common Tools</a>.</li> </ul> </li> <li> <p>The implementation examples of ERC-6358 Fungible Token and ERC-6358 Non-Fungible Token can be found at:</p> <ul> <li><a href="https://wg-eips.ritovision.com/6358/./assets/src/contracts/ERC6358FungibleExample.sol">ERC-6358 Fungible Token Example</a></li> <li><a href="https://wg-eips.ritovision.com/6358/./assets/src/contracts/ERC6358NonFungibleExample.sol">ERC-6358 Non-Fungible Token Example</a></li> </ul> </li> </ul> <h2 id="security-considerations">Security Considerations</h2> <h3 id="attack-vector-analysis">Attack Vector Analysis</h3> <p>According to the above, there are two roles:</p> <ul> <li><strong>common users</strong> are who initiate an <code>o-transaction</code></li> <li><strong>synchronizers</strong> are who just carry the <code>o-transaction</code> data if they find differences between different chains.</li> </ul> <p>The two roles might be where the attack happens:</p> <h4 id="will-the-synchronizers-cheat"><strong>Will the <em>synchronizers</em> cheat?</strong></h4> <ul> <li> <p>Simply speaking, it's none of the <strong>synchronizer</strong>'s business as <strong>they cannot create other users' signatures</strong> unless some <strong>common users</strong> tell him, but at this point, we think it's a problem with the role <strong>common user</strong>.</p> </li> <li> <p>The <strong>synchronizer</strong> has no will and cannot do evil because the <code>o-transaction</code> data that they deliver is verified by the related <strong>signature</strong> of other <strong>common users</strong>.</p> </li> <li> <p>The <strong>synchronizers</strong> would be rewarded as long as they submit valid <code>o-transaction</code> data, and <em>valid</em> only means that the signature and the amount are both valid. This will be detailed and explained later when analyzing the role of <strong>common user</strong>.</p> </li> <li> <p>The <strong>synchronizers</strong> will do the delivery once they find differences between different chains:</p> <ul> <li>If the current <code>account nonce</code> on one chain is smaller than a published <code>nonce in o-transaction</code> on another chain</li> <li>If the transaction data related to a specific <code>nonce in o-transaction</code> on one chain is different from another published <code>o-transaction</code> data with the same <code>nonce in o-transaction</code> on another chain</li> </ul> </li> <li> <p><strong>Conclusion: The <em>synchronizers</em> won't cheat because there are no benefits and no way for them to do so.</strong></p> </li> </ul> <h4 id="will-the-common-user-cheat"><strong>Will the <em>common user</em> cheat?</strong></h4> <ul> <li> <p>Simply speaking, <strong>maybe they will</strong>, but fortunately, <strong>they can't succeed</strong>.</p> </li> <li> <p>Suppose the current <code>account nonce</code> of a <strong>common user</strong> <code>A</code> is $k$ on all chains. <code>A</code> has 100 token <code>X</code>, which is an instance of the ERC-6358 token.</p> </li> <li> <p>Common user <code>A</code> initiates an <code>o-transaction</code> on a Parachain of Polkadot first, in which <code>A</code> transfers <code>10</code> <code>X</code>s to an <code>o-account</code> of a <strong>common user</strong> <code>B</code>. The <code>nonce in o-transaction</code> needs to be $k+1$. After signature and data verification, the <code>o-transaction</code> data(<code>ot-P-ab</code> for short) will be published on Polkadot.</p> </li> <li> <p>At the same time, <code>A</code> initiates an <code>o-transaction</code> with the <strong>same nonce</strong> $k+1$ but <strong>different data</strong>(transfer <code>10</code> <code>X</code>s to another <code>o-account</code> <code>C</code> for example) on Ethereum. This <code>o-transaction</code> (named <code>ot-E-ac</code> for short) will pass the verification on Ethereum first, and be published.</p> </li> <li> <p>At this point, it seems <code>A</code> finished a <em><strong>double spend attack</strong></em> and the states on Polkadot and Ethereum are different.</p> </li> <li> <p><strong>Response strategy</strong>:</p> <ul> <li>As we mentioned above, the synchronizers will deliver <code>ot-P-ab</code> to Ethereum and deliver <code>ot-E-ac</code> to Polkadot because they are different although with the same nonce. The synchronizer who submits the <code>o-transaction</code> first will be rewarded as the signature is valid.</li> <li>Both the ERC-6358 smart contracts or similar mechanisms on Polkadot and Ethereum will find that <code>A</code> did cheating after they received both <code>ot-E-ac</code> and <code>ot-P-ab</code> respectively as the signature of <code>A</code> is non-deniable.</li> <li>We have mentioned that the execution of an <code>o-transaction</code> will not be done immediately and instead there needs to be a fixed waiting time. So the <code>double spend attack</code> caused by <code>A</code> won't succeed.</li> <li>There will be many synchronizers waiting for delivering o-transactions to get rewards. So although it's almost impossible that a <strong>common user</strong> can submit two <code>o-transactions</code> to two chains, but none of the synchronizers deliver the <code>o-transactions</code> successfully because of a network problem or something else, we still provide a solution: <ul> <li>The synchronizers will connect to several native nodes of every public chain to avoid the malicious native nodes.</li> <li>If it indeed happened that all synchronizers' network break, the <code>o-transactions</code> will be synchronized when the network recovered. If the waiting time is up and the cheating <code>o-transaction</code> has been executed, we are still able to revert it from where the cheating happens according to the <code>nonce in o-transaction</code> and <code>account nonce</code>.</li> </ul> </li> </ul> </li> <li> <p><code>A</code> couldn't escape punishment in the end (For example, lock his account or something else, and this is about the certain tokenomics determined by developers according to their own situation).</p> </li> <li> <p><strong>Conclusion: The <em>common user</em> maybe cheat but won't succeed.</strong></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> 2023-01-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Georgehttps://github.com/JXRow https://wg-eips.ritovision.com/6327/

Use password to sign data as private key

<h2 id="abstract">Abstract</h2> <p>Elastic signature (ES) aims to sign data with a human friendly secret. The secret will be verified fully on-chain and is not stored anywhere. A user can change the secret as often as they need to. The secret does not have a fixed length. The secret will be like a password, which is a better understood concept than private key. This is specifically true for non-technical users. This EIP defines a smart contract interface to verify and authorize operations with ES.</p> <h2 id="motivation">Motivation</h2> <p>What would a changeable "private key" enable us? For years, we have been looking for ways to lower on-boarding barrier for users, especially those with less technical experiences. Private key custody solutions seem to provide an user friendly on-boarding experience, but it is vendor dependent and is not decentralized. ES makes a breakthrough with Zero-knowledge technology. Users generate proof of knowing the secret and a smart contract will verify the proof.</p> <h3 id="use-case">Use case</h3> <p>ES is an alternative signing algorithm. It is not an either-or solution to the private key. It is designed to serve as an additional signing mechanism on top of the private key signature.</p> <ul> <li>A DeFi app can utilize ES into their transfer fund process. Users will be required to provide their passwords to complete the transaction. This gives an extra protection even if the private key is compromised.</li> <li>ES can also be used as a plugin to a smart contract wallet, like Account Abstraction <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a>. A decentralized password is picked instead of the private key. This could lead to a smooth onboarding experiences for new Ethereum Dapp users.</li> </ul> <h2 id="specification">Specification</h2> <p>Let:</p> <ul> <li><code>pwdhash</code> represents the hash of the private secret (password).</li> <li><code>datahash</code> represents the hash of an intended transaction data.</li> <li><code>fullhash</code> represents the hash of <code>datahash</code> and all the well-known variables.</li> <li><code>expiration</code> is the timestamp after which the intended transaction expires.</li> <li><code>allhash</code> represents the hash of <code>fullhash</code> and <code>pwdhash</code>.</li> </ul> <p>There are three parties involved, Verifier, Requester and Prover.</p> <ul> <li>A verifier, <ul> <li>SHOULD compute <code>fullhash</code> from a <code>datahash</code>, which is provided by the requester.</li> <li>SHOULD derive <code>pwdhash</code> for a given address. The address can be an EOA or a smart contract wallet.</li> <li>SHOULD verify the proof with the derived <code>pwdhash</code>, the computed <code>fullhash</code> and a <code>allhash</code>, which is submitted by the requester.</li> </ul> </li> <li>A requester <ul> <li>SHOULD generate <code>datahash</code> and decide an <code>expiration</code>.</li> <li>SHALL request a verification from the verifier with, <ul> <li><code>proof</code> and <code>allhash</code> which are provided by the prover;</li> <li><code>datahash</code>;</li> <li><code>expiration</code>.</li> </ul> </li> </ul> </li> <li>A prover <ul> <li>SHOULD generate the <code>proof</code> and <code>allhash</code> from, <ul> <li><code>datahash</code> and <code>expiration</code> which are agreed with the requester;</li> <li><code>nonce</code> and other well-known variables.</li> </ul> </li> </ul> </li> </ul> <p>There are also some requirements.</p> <ul> <li>well-known variable SHOULD be available to all parties. <ul> <li>SHOULD include a <code>nonce</code>.</li> <li>SHOULD include a <code>chainid</code>.</li> <li>MAY include any variable that is specific to the verifier.</li> </ul> </li> <li>public statements SHOULD include, <ul> <li>one reflecting the <code>pwdhash</code>;</li> <li>one reflecting the <code>fullhash</code>;</li> <li>one reflecting the <code>allhash</code>.</li> </ul> </li> <li>The computation of <code>fullhash</code> SHOULD be agreed by both the verifier and the prover.</li> <li>The computation of <code>datahash</code></li> </ul> <h3 id="ielasticsignature-interface"><code>IElasticSignature</code> Interface</h3> <p>This is the verifier 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"> IElasticSignature</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * Event emitted after user set/reset their password</span></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 user&#39;s address, for whom the password hash is set. It could be a smart contract wallet address</span></span> <span class="giallo-l"><span class="z-comment"> * or an EOA wallet 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"> pwdhash</span><span class="z-comment"> - a password hash</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"> SetPassword</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-storage z-type"> indexed</span><span class="z-variable"> pwdhash</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"> * Event emitted after a successful verification performed for an 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"> user</span><span class="z-comment"> - an user&#39;s address, for whom the submitted `proof` is verified. It could be a smart contract wallet</span></span> <span class="giallo-l"><span class="z-comment"> * address or an EOA wallet 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"> nonce</span><span class="z-comment"> - a new nonce, which is newly generated to replace the last used nonce. </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"> Verified</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-storage z-type"> indexed</span><span class="z-variable"> nonce</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"> * Get `pwdhash` for a 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"> user</span><span class="z-comment"> - a user&#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-comment"> - the `pwdhash` for the given 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"> pwdhashOf</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>;</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"> * Update an user&#39;s `pwdhash`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> proof1</span><span class="z-comment"> - proof generated by the old password</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> expiration1</span><span class="z-comment"> - old password signing expiry seconds</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> allhash1</span><span class="z-comment"> - allhash generated with the old password</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> proof2</span><span class="z-comment"> - proof generated by the new password</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> pwdhash2</span><span class="z-comment"> - hash of the new password</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> expiration2</span><span class="z-comment"> - new password signing expiry seconds</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> allhash2</span><span class="z-comment"> - allhash generated with the new password</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"> resetPassword</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span>[</span><span class="z-variable">8</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> proof1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> expiration1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> allhash1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span>[</span><span class="z-variable">8</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> proof2</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> pwdhash2</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> expiration2</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> allhash2</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"> * Verify a proof for a given user</span></span> <span class="giallo-l"><span class="z-comment"> * It should be invoked by other contracts. The other contracts provide the `datahash`. The `proof` is generated by</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> user</span><span class="z-comment"> - a user&#39;s address, for whom the verification will be carried out.</span></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 proof generated by the password</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> datahash</span><span class="z-comment"> - the data what user signing, this is the hash of the 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"> expiration</span><span class="z-comment"> - number of seconds from now, after which the proof 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"> allhash</span><span class="z-comment"> - public statement, generated along with the `proof`</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"> verify</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> user</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span>[</span><span class="z-variable">8</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> proof</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> datahash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> expiration</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> allhash</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> <p><code>verify</code> function SHOULD be called by another contract. The other contract SHOULD generate the <code>datahash</code> to call this. The function SHOULD verify if the <code>allhash</code> is computed correctly and honestly with the password.</p> <h2 id="rationale">Rationale</h2> <p>The contract will store everyone's <code>pwdhash</code>.</p> <p><img src="https://wg-eips.ritovision.com/6327/./assets/zkpass-1.png" alt="verifier-contract" /></p> <p>The chart below shows ZK circuit logic.</p> <p><img src="https://wg-eips.ritovision.com/6327/./assets/zkpass-2.png" alt="circuit-logic" /></p> <p>To verify the signature, it needs <code>proof</code>, <code>allhash</code>, <code>pwdhash</code> and <code>fullhash</code>.</p> <p><img src="https://wg-eips.ritovision.com/6327/./assets/zkpass-3.png" alt="workflow" /></p> <p>The prover generates <code>proof</code> along with the public outputs. They will send all of them to a third-party requester contract. The requester will generate the <code>datahash</code>. It sends <code>datahash</code>, <code>proof</code>, <code>allhash</code>, <code>expiration</code> and prover's address to the verifier contract. The contract verifies that the <code>datahash</code> is from the prover, which means the withdrawal operation is signed by the prover's password.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is backward compatible with previous work on signature validation since this method is specific to password based signatures and not EOA signatures.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Example implementation of a signing 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.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;../interfaces/IElasticSignature.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./verifier.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"> ZKPass</span><span class="z-storage"> is</span><span class="z-entity z-name"> IElasticSignature</span><span> {</span></span> <span class="giallo-l"><span> Verifier verifier </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-entity z-name"> Verifier</span><span>(</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">address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint</span><span>)</span><span class="z-storage z-type"> public</span><span> pwdhashOf</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"> uint</span><span>)</span><span class="z-storage z-type"> public</span><span> nonceOf</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> {</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"> resetPassword</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span>[</span><span class="z-variable">8</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> proof1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> expiration1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> allhash1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span>[</span><span class="z-variable">8</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> proof2</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> pwdhash2</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> expiration2</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> allhash2</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> override</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> nonce </span><span class="z-keyword">=</span><span> nonceOf</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>nonce </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">init password</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> pwdhashOf</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> =</span><span> pwdhash2</span><span>;</span></span> <span class="giallo-l"><span> nonceOf</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> verify</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> proof2</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span> expiration2</span><span>,</span><span> allhash2</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-comment"> //</span><span class="z-comment">reset password</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> check old pwdhash</span></span> <span class="giallo-l"><span class="z-entity z-name"> verify</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> proof1</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span> expiration1</span><span>,</span><span> allhash1</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> check new pwdhash</span></span> <span class="giallo-l"><span> pwdhashOf</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> =</span><span> pwdhash2</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> verify</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> proof2</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span> expiration2</span><span>,</span><span> allhash2</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-keyword"> emit</span><span class="z-entity z-name"> SetPassword</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> pwdhash2</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"> verify</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> user</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span>[</span><span class="z-variable">8</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> proof</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> datahash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> expiration</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> allhash</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</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> <span class="giallo-l"><span class="z-variable z-language"> block</span><span>.</span><span>timestamp </span><span class="z-keyword">&lt;</span><span> expiration</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;ZKPass::verify: expired&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"> uint</span><span> pwdhash </span><span class="z-keyword">=</span><span> pwdhashOf</span><span>[</span><span>user</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> pwdhash </span><span class="z-keyword">!=</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;ZKPass::verify: user not exist&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"> uint</span><span> nonce </span><span class="z-keyword">=</span><span> nonceOf</span><span>[</span><span>user</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> fullhash </span><span class="z-keyword">=</span><span class="z-support"> uint</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>expiration</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>chainid</span><span>,</span><span> nonce</span><span>,</span><span> datahash</span><span>)</span><span>)</span><span>)</span><span class="z-keyword"> /</span><span class="z-constant"> 8</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 256b-&gt;254b</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"> verifyProof</span><span>(</span><span>proof</span><span>,</span><span> pwdhash</span><span>,</span><span> fullhash</span><span>,</span><span> allhash</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;ZKPass::verify: verify proof fail&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> nonceOf</span><span>[</span><span>user</span><span>]</span><span class="z-keyword"> =</span><span> nonce </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"> emit</span><span class="z-entity z-name"> Verified</span><span>(</span><span>user</span><span>,</span><span> nonce</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">//////// util ////////////</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"> verifyProof</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span>[</span><span class="z-variable">8</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> proof</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> pwdhash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> fullhash</span><span>,</span><span class="z-comment"> //</span><span class="z-comment">254b</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> allhash</span></span> <span class="giallo-l"><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-keyword"> return</span></span> <span class="giallo-l"><span> verifier</span><span>.</span><span class="z-entity z-name">verifyProof</span><span>(</span></span> <span class="giallo-l"><span> [</span><span>proof</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span> proof</span><span>[</span><span class="z-constant">1</span><span>]</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>[</span><span>proof</span><span>[</span><span class="z-constant">2</span><span>]</span><span>,</span><span> proof</span><span>[</span><span class="z-constant">3</span><span>]</span><span>]</span><span>,</span><span> [</span><span>proof</span><span>[</span><span class="z-constant">4</span><span>]</span><span>,</span><span> proof</span><span>[</span><span class="z-constant">5</span><span>]</span><span>]</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>proof</span><span>[</span><span class="z-constant">6</span><span>]</span><span>,</span><span> proof</span><span>[</span><span class="z-constant">7</span><span>]</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>pwdhash</span><span>,</span><span> fullhash</span><span>,</span><span> allhash</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></code></pre> <p>verifier.sol is auto generated by snarkjs, the source code circuit.circom is below</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"> circom</span><span class="z-constant"> 2</span><span class="z-constant">.</span><span class="z-constant">0</span><span>.</span><span class="z-constant">0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">include</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">../../node_modules/circomlib/circuits/poseidon.circom</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">template</span><span class="z-entity z-name"> Main</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> signal</span><span class="z-variable z-other"> input</span><span class="z-keyword"> in</span><span>[</span><span class="z-constant">3</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> signal</span><span class="z-variable z-other"> output</span><span class="z-variable z-other"> out</span><span>[</span><span class="z-constant">3</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> component</span><span class="z-variable z-other"> poseidon1</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Poseidon</span><span>(</span><span class="z-constant">2</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> component</span><span class="z-variable z-other"> poseidon2</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Poseidon</span><span>(</span><span class="z-constant">2</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> poseidon1</span><span>.</span><span class="z-variable z-other">inputs</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> &lt;=</span><span class="z-keyword">=</span><span class="z-keyword"> in</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">pwd</span></span> <span class="giallo-l"><span class="z-variable z-other"> poseidon1</span><span>.</span><span class="z-variable z-other">inputs</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> &lt;=</span><span class="z-keyword">=</span><span class="z-keyword"> in</span><span>[</span><span class="z-constant">1</span><span>]</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">address</span></span> <span class="giallo-l"><span class="z-variable z-other"> out</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> &lt;=</span><span class="z-keyword">=</span><span class="z-variable z-other"> poseidon1</span><span>.</span><span class="z-variable z-other">out</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">pwdhash</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> poseidon2</span><span>.</span><span class="z-variable z-other">inputs</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> &lt;=</span><span class="z-keyword">=</span><span class="z-variable z-other"> poseidon1</span><span>.</span><span class="z-variable z-other">out</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> poseidon2</span><span>.</span><span class="z-variable z-other">inputs</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> &lt;=</span><span class="z-keyword">=</span><span class="z-keyword"> in</span><span>[</span><span class="z-constant">2</span><span>]</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">fullhash</span></span> <span class="giallo-l"><span class="z-variable z-other"> out</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> &lt;=</span><span class="z-keyword">=</span><span class="z-keyword"> in</span><span>[</span><span class="z-constant">2</span><span>]</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">fullhash</span></span> <span class="giallo-l"><span class="z-variable z-other"> out</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-keyword"> &lt;=</span><span class="z-keyword">=</span><span class="z-variable z-other"> poseidon2</span><span>.</span><span class="z-variable z-other">out</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">allhash</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">component</span><span class="z-variable z-other"> main</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Main</span><span>(</span><span>)</span><span>;</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Since the pwdhash is public, it is possible to be crack the password. We estimate the Poseidon hash rate of RTX3090 would be 100Mhash/s, this is the estimate of crack time:</p> <p>8 chars (number) : 1 secs</p> <p>8 chars (number + english) : 25 days</p> <p>8 chars (number + english + symbol) : 594 days</p> <p>12 chars (number) : 10000 secs</p> <p>12 chars (number + english) : 1023042 years</p> <p>12 chars (number + english + symbol) : 116586246 years</p> <p>The crack difficulty of private key is 2^256, the crack difficulty of 40 chars (number + english + symbol) is 92^40, 92^40 &gt; 2^256, so when password is 40 chars , it is more difficult to be crack than private 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> 2023-01-11T00:00:00+00:00 2026-02-11T14:48:25+00:00 Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/6315/

Introducing per-forwarder namespaced addresses to facilitate meta-transactions under a namespacing framework

<h2 id="abstract">Abstract</h2> <p><a href="https://wg-eips.ritovision.com/2771/">ERC-2771</a> is a prevalent standard for handling meta-transactions via trusted forwarders. This EIP proposes an extension to <a href="https://wg-eips.ritovision.com/2771/">ERC-2771</a> to introduce a namespacing mechanism, facilitating trustless account abstraction through per-forwarder namespaced addresses.</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 key words "Forwarder" and "Recipient" in this document are to be interpreted as described in <a href="https://wg-eips.ritovision.com/2771/">ERC-2771</a>.</p> <h3 id="namespaced-forwarder-interface">Namespaced Forwarder 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"> ^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"> INamespacedForwarder</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isNamespacedTransaction</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></span></code></pre><h3 id="determining-the-sender-and-forwarder">Determining the Sender and Forwarder</h3> <p>Upon function invocation on a Recipient, the Recipient MUST execute a <code>STATICCALL</code> to the <code>isNamespacedTransaction()</code> method of the caller. If this operation reverts or returns the boolean value <code>false</code>, the transaction MUST proceed normally, identifying the caller as the sender, and the Forwarder as the zero address. However, if the boolean value <code>true</code> is returned, the transaction is acknowledged as a namespaced transaction, with the sender identified using the procedure outlined in <a href="https://wg-eips.ritovision.com/2771/#extracting-the-transaction-signer-address">ERC-2771</a>, and the Forwarder identified as the caller.</p> <h3 id="recipient-extensions">Recipient Extensions</h3> <p>Whenever a Recipient contract has a function with one or more function parameters of type address, it MUST also provide a new function, mirroring the name of the original function but appending <code>Namespaced</code> at the end, which accepts two addresses instead. The initial address denotes the Forwarder, while the latter represents the address managed by that Forwarder. If a function accepts multiple address parameters (e.g., <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>'s <code>transferFrom</code>), a version of the function accepting two addresses per original address parameter MUST be provided. The original function MUST exhibit identical behavior to the new function when Forwarder addresses are the zero address.</p> <p>For instance, <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> would be extended with these functions:</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"> transferNamespaced</span><span>(</span><span class="z-support">address</span><span class="z-variable"> toForwarder</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> toAddress</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 class="z-storage z-type">function</span><span class="z-entity z-name"> approveNamespaced</span><span>(</span><span class="z-support">address</span><span class="z-variable"> spenderForwarder</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> spenderAddress</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 class="z-storage z-type">function</span><span class="z-entity z-name"> transferFromNamespaced</span><span>(</span><span class="z-support">address</span><span class="z-variable"> fromForwarder</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> fromAddress</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> toForwarder</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> toAddress</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amount</span><span>)</span><span>;</span></span></code></pre><h4 id="erc-165"><a href="https://wg-eips.ritovision.com/165/">ERC-165</a></h4> <p>Recipient contracts MUST implement ERC-165. When an ERC-165 interface ID is registered, a second interface ID corresponding to the XOR of the Namespaced function selectors of the original interface must also be registered.</p> <h2 id="rationale">Rationale</h2> <p>The approach of simply augmenting existing EIP functions with new <code>address</code> parameters, rather than crafting new interfaces for the most commonly used EIPs, is employed to ensure broader applicability of this namespacing proposal.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Contracts already deployed cannot not benefit from this namespacing proposal. This limitation also extends to ERC-2771.</p> <h3 id="using-this-eip-in-standards">Using this EIP in standards</h3> <p>When using this EIP in another standard, both the original and the Namespaced interface IDs SHOULD be provided. Interfaces MUST NOT include namespaced versions of functions in their interfaces.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This proposal alters trust dynamics: Forwarders no longer require Recipient trust, but instead require the trust of 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> 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-30T00:00:00+00:00 2026-02-11T14:48:26+00:00 Jessica Changhttps://github.com/JessicaChg https://wg-eips.ritovision.com/6239/

Adding RDF triples to ERC-5192 token metadata to capture social meaning

<h2 id="abstract">Abstract</h2> <p>This proposal extends <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/5192/">ERC-5192</a> by introducing Resource Description Framework (RDF) triples to Soulbound Tokens' (‘SBTs‘) metadata.</p> <h2 id="motivation">Motivation</h2> <p>A Soulbound Token represents the commitments, credentials, and affiliations of accounts. RDF is a standard data model developed by the World Wide Web Consortium (‘W3C’) and is used to represent information in a structured format. Semantic SBTs are built on existing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/5192/">ERC-5192</a> standards to include RDF triples in metadata to capture and store the meaning of social metadata as a network of accounts and attributes.</p> <p>Semantic SBT provides a foundation for publishing, linking, and integrating data from multiple sources, and enables the ability to query and retrieve information across these sources, using inference to uncover new insights from existing social relations. For example, form the on-chain united social graph, assign trusted contacts for social recovery, and supports fair governance.</p> <p>While the existence of SBTs can create a decentralized social framework, there still needs to specify a common data model to manage the social metadata on-chain in a trustless manner, describing social metadata in an interconnected way, make it easy to be exchanged, integrated and discovered. And to further fuel the boom of the SBTs ecosystem, we need a bottom-up and decentralized way to maintain people’s social identity related information.</p> <p>Semantic SBTs address this by storing social metadata, attestations, and access permissions on-chain to bootstrap the social identity layer and a linked data layer natively on Ethereum, and bring semantic meanings to the tons of bits of on-chain data.</p> <h3 id="connectedness">Connectedness</h3> <p>Semantic SBTs store social data as RDF triples in the Subject-Predicate-Object format, making it easy to create relationships between accounts and attributes. RDF is a standard for data interchange used to represent highly interconnected data. Representing data in RDF triples makes it simpler for automated systems to identify, clarify, and connect information.</p> <h3 id="linked-data">Linked Data</h3> <p>Semantic SBTs allow the huge amount of social data on-chain to be available in a standard format (RDF) and be reachable and manageable. The interrelated datasets on-chain can create the linked data layer that allows social data to be mixed, exposed, and shared across different applications, providing a convenient, cheap, and reliable way to retrieve data, regardless of the number of users.</p> <h3 id="social-identity">Social Identity</h3> <p>Semantic SBTs allow people to publish or attest their own identity-related data in a bottom-up and decentralized way, without reliance on any centralized intermediaries while setting every party free. The data is fragmentary in each Semantic SBT and socially interrelated. RDF triples enable various community detection algorithms to be built on top.</p> <p>This proposal outlines the semantic data modeling of SBTs that allows implementers to model the social relations among Semantic SBTs, especially in the social sector.</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> <ul> <li>The token <strong>MUST</strong> implement the following interfaces: <ol> <li><a href="https://wg-eips.ritovision.com/165/">ERC-165</a>’s <code>ERC165</code> (<code>0x01ffc9a7</code>)</li> <li><a href="https://wg-eips.ritovision.com/721/">ERC-721</a>’s <code>ERC721</code> (<code>0x80ac58cd</code>)</li> <li><a href="https://wg-eips.ritovision.com/721/">ERC-721</a>’s <code>ERC721Metadata</code> (<code>0x5b5e139f</code>)</li> <li><a href="https://wg-eips.ritovision.com/5192/">ERC-5192</a>’s <code>ERC5192</code> (<code>0xb45a3c0e</code>)</li> </ol> </li> </ul> <h3 id="rdf-statement">RDF Statement</h3> <p>RDF statements come in various formats, we have selected the six most commonly used formats: <code>nt(N-Triples)</code>,<code>ttl(Turtle)</code>,<code>rdf(RDF/XML)</code>,<code>rj(RDF/JSON)</code>,<code>nq(N-Quads)</code> and <code>trig(TriG)</code>.</p> <p>The complete format of an RDF statement:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>rdfStatements = {[format]}&lt;statements&gt;</span></span></code></pre> <p>In the following section, fragments surrounded by <code>{}</code> characters are OPTIONAL.</p> <p>In the following section, fragments surrounded by <code>&lt;&gt;</code> characters are REQUIRED.</p> <p>format: nt/ttl/rdf/rj/nq/trig</p> <p>When no format is selected: statements = [ttl]statements</p> <ul> <li><code>nt(n-triples)</code></li> </ul> <p><code>nt</code> uses space to separate the subject, predicate, object of a triple, and a period . to indicate the end of a triple.</p> <p>The basic structure is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>subject predicate object .</span></span></code></pre> <p>In this format, the subject is in the format of IRIREF or BLANK_NODE_LABEL, the predicate is in the format of IRIREF, and the object is in the format of IRIREF, BLANK_NODE_LABEL, or STRING_LITERAL_QUOTE.</p> <p>For example:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&lt;http://example.org/entity/user1&gt; &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://example.org/entity/User&gt; .</span></span> <span class="giallo-l"><span>&lt;http://example.org/entity/user1&gt; &lt;http://example.org/property/name&gt; &quot;Alice&quot; .</span></span></code></pre> <ul> <li><code>ttl(Turtle)</code></li> </ul> <p>Compared to <code>nt</code>, <code>ttl</code> uses prefixes to simplify the IRIREF format, and the same predicate under the same subject can be merged without repeating it. "a" can be used to represent <code>&lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt;</code>.</p> <p>For example:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>@prefix : &lt;http://example.org/entity/&gt; .</span></span> <span class="giallo-l"><span>@prefix p: &lt;http://example.org/property/&gt; .</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>:user1 a :User;</span></span> <span class="giallo-l"><span> p:name ”Alice” .</span></span></code></pre> <ul> <li><code>rdf(RDF/XML)</code></li> </ul> <p><code>rdf</code> describes RDF in XML format, using rdf:RDF as the top-level element, and xmlns to describe prefixes. rdf:Description begins describing a node, rdf:about defines the node to be described, and rdf:resource fills in the property value in the format of IRI. If the property value is a string, the property value can be directly written as the text of the property node.</p> <p>The basic structure is:</p> <pre class="giallo z-code"><code data-lang="xml"><span class="giallo-l"><span>&lt;?</span><span class="z-entity z-name z-tag">xml</span><span class="z-entity"> version</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>?&gt;</span></span> <span class="giallo-l"><span>&lt;</span><span class="z-entity z-name z-tag">rdf</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">RDF</span><span class="z-entity"> xmlns</span><span class="z-entity">:</span><span class="z-entity">rdf</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">http://www.w3.org/1999/ 02/22-rdf-syntax-ns#</span><span class="z-punctuation z-definition z-string">&quot;</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">rdf</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">Description</span><span class="z-entity"> rdf</span><span class="z-entity">:</span><span class="z-entity">about</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">subject</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">predicate</span><span class="z-entity"> rdf</span><span class="z-entity">:</span><span class="z-entity">resource</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>/&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">predicate</span><span> &gt;</span><span>object</span><span>&lt;/</span><span class="z-entity z-name z-tag">predicate</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;/</span><span class="z-entity z-name z-tag">rdf</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">Description</span><span>&gt;</span></span> <span class="giallo-l"><span>&lt;/</span><span class="z-entity z-name z-tag">rdf</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">RDF</span><span>&gt;</span></span></code></pre> <p>For example:</p> <pre class="giallo z-code"><code data-lang="xml"><span class="giallo-l"><span>&lt;?</span><span class="z-entity z-name z-tag">xml</span><span class="z-entity"> version</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>?&gt;</span></span> <span class="giallo-l"><span>&lt;</span><span class="z-entity z-name z-tag">rdf</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">RDF</span><span class="z-entity"> xmlns</span><span class="z-entity">:</span><span class="z-entity">rdf</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">http://www.w3.org/1999/ 02/22-rdf-syntax-ns#</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-entity"> xmlns</span><span class="z-entity">:</span><span class="z-entity">p</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">http://example.org/property/</span><span class="z-punctuation z-definition z-string">&quot;</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">rdf</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">Description</span><span class="z-entity"> rdf</span><span class="z-entity">:</span><span class="z-entity">about</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">http://example.org/entity/user1</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">rdf</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">type</span><span class="z-entity"> rdf</span><span class="z-entity">:</span><span class="z-entity">resource</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">http://example.org/entity/</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">p</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">name</span><span> &gt;</span><span>Alice</span><span>&lt;/</span><span class="z-entity z-name z-tag">p</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">name</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;/</span><span class="z-entity z-name z-tag">rdf</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">Description</span><span>&gt;</span></span> <span class="giallo-l"><span>&lt;/</span><span class="z-entity z-name z-tag">rdf</span><span class="z-entity z-name z-tag">:</span><span class="z-entity z-name z-tag">RDF</span><span>&gt;</span></span></code></pre> <ul> <li><code>rj(RDF/JSON)</code></li> </ul> <p><code>rj</code> describes RDF in JSON format. A triple is described as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> {&quot;subject&quot;:{&quot;predicate&quot;:[object]}}</span></span></code></pre> <p>Note that each root object is a unique primary key and duplicates are not allowed. There will be no duplicate subjects as keys, and there will be no duplicate predicates under a single subject.</p> <p>For example:</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">http://example.org/entity/user1</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">http://www.w3.org/1999/02/22-rdf-syntax-ns#type</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">http://example.org/entity/User</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">http://example.org/property/name</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">Alice</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> <ul> <li><code>nq(N-Quads)</code></li> </ul> <p><code>nq</code> is based on <code>nt</code> but includes a graph label that describes the dataset to which an RDF triple belongs. The graph label can be in the format of IRIREF or BLANK_NODE_LABEL.</p> <p>The basic structure is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>subject predicate object graphLabel.</span></span></code></pre> <p>For example:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&lt;http://example.org/entity/user1&gt; &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#type&gt; &lt;http://example.org/entity/User&gt; &lt;http://example.org/graphs/example&gt; .</span></span> <span class="giallo-l"><span>&lt;http://example.org/entity/user1&gt; &lt;http://example.org/property/name&gt; &quot;Alice&quot; &lt;http://example.org/graphs/example&gt; .</span></span></code></pre> <ul> <li><code>trig(TriG)</code></li> </ul> <p><code>trig</code> is an extension of <code>ttl</code> that includes a graph label to describe the dataset to which an RDF triple belongs. The triple statements are enclosed in curly braces {}.</p> <p>For example:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>@prefix : &lt;http://example.org/entity/&gt; .</span></span> <span class="giallo-l"><span>@prefix p: &lt;http://example.org/property/&gt; .</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>&lt;http://example.org/graphs/example&gt;</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> :user1 a :User;</span></span> <span class="giallo-l"><span> p:name ”Alice” .</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> }</span></span></code></pre> <p>In the contract events: <code>CreateRDF</code>, <code>UpdateRDF</code>, <code>RemoveRDF</code>, and the <code>rdfOf method</code>, the <code>rdfStatements</code> is used in <code>ttl</code> format by default. If other formats listed above are used, a format identifier needs to be added for identification.</p> <p>The format identifier starts with <code>[</code> and ends with <code>]</code> with the format in the middle, i.e., <code>[format]</code>.</p> <p>For example, the <code>rdfStatements</code> in <code>nt</code> format should include the prefix <code>[nt]</code>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[nt]subject predicate object .</span></span></code></pre><h3 id="contract-interface">Contract Interface</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">@title</span><span class="z-comment"> Semantic Soulbound Token</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 0xfbafb698</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"> ISemanticSBT</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"> This emits when minting a Semantic Soulbound 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"> The identifier for the Semantic Soulbound 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"> rdfStatements</span><span class="z-comment"> The RDF statements for the Semantic Soulbound 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"> CreateRDF</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"> rdfStatements</span></span> <span class="giallo-l"><span> )</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"> This emits when updating the RDF data of Semantic Soulbound Token. RDF data is a collection of RDF statements that are used to represent information about resources.</span></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 Semantic Soulbound 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"> rdfStatements</span><span class="z-comment"> The RDF statements for the semantic soulbound 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"> UpdateRDF</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"> rdfStatements</span></span> <span class="giallo-l"><span> )</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"> This emits when burning or revoking Semantic Soulbound 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"> The identifier for the Semantic Soulbound 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"> rdfStatements</span><span class="z-comment"> The RDF statements for the Semantic Soulbound 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"> RemoveRDF</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"> rdfStatements</span></span> <span class="giallo-l"><span> )</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"> Returns the RDF statements of the Semantic Soulbound 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"> The identifier for the Semantic Soulbound 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"> rdfStatements</span><span class="z-comment"> The RDF statements for the Semantic Soulbound 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"> rdfOf</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 class="z-variable"> rdfStatements</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>ISemanticRDFSchema</code>, an extension of ERC-721 Metadata, is <strong>OPTIONAL</strong> for this standard, it is used to get the Schema URI for the RDF data.</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"> ISemanticRDFSchema</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"> Get the URI of schema for this 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"> The</span><span class="z-comment"> URI of the contract which point to a configuration profile.</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"> schemaURI</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></code></pre><h3 id="method-specification">Method Specification</h3> <p><code>rdfOf (uint256 tokenId)</code>: Query the RDF data for the Semantic Soulbound Token by <code>tokenId</code>. The returned RDF data format conforms to the W3C RDF standard. RDF data is a collection of RDF statements that are used to represent information about resources. An RDF statement, also known as a triple, is a unit of information in the RDF data model. It consists of three parts: a subject, a predicate, and an object.</p> <p><code>schemaURI()</code>: This <strong>OPTIONAL</strong> method is used to query the URIs of the schema for the RDF data. RDF Schema is an extension of the basic RDF vocabulary and provides a data-modelling vocabulary for RDF data. It is <strong>RECOMMENDED</strong> to store the RDF Schema in decentralized storage such as Arweave or IPFS. The URIs are then stored in the contract and can be queried by this method.</p> <h3 id="event-specification">Event Specification</h3> <p><code>CreateRDF</code>: When minting a Semantic Soulbound Token, this event <strong>MUST</strong> be triggered to notify the listener to perform operations with the created RDF data. When calling the event, the input RDF data <strong>MUST</strong> be RDF statements, which are units of information consisting of three parts: a subject, a predicate, and an object.</p> <p><code>UpdateRDF</code>: When updating RDF data for a Semantic Soulbound Token, this event <strong>MUST</strong> be triggered to notify the listener to perform update operations accordingly with the updated RDF data. When calling the event, the input RDF data <strong>MUST</strong> be RDF statements, which are units of information consisting of three parts: a subject, a predicate, and an object.</p> <p><code>RemoveRDF</code>: When burning or revoking a Semantic Soulbound Token, this event <strong>MUST</strong> be triggered to notify the listener to perform operations with the removed RDF data for the Semantic SBT. When calling the event, the input RDF data <strong>MUST</strong> be RDF statements, which are units of information consisting of three parts: a subject, a predicate, and an object.</p> <h2 id="rationale">Rationale</h2> <p>RDF is a flexible and extensible data model based on creating subject-predicate-object relationships, often used to model graph data due to its semantic web standards, Linked Data concept, flexibility, and query capabilities. RDF allows graph data to be easily integrated with other data sources on the web, making it possible to create more comprehensive and interoperable models. The advantage of using RDF for semantic description is that it can describe richer information, including terms, categories, properties, and relationships. RDF uses standard formats and languages to describe metadata, making the expression of semantic information more standardized and unified. This helps to establish more accurate and reliable semantic networks, promoting interoperability between different systems. Additionally, RDF supports semantic reasoning, which allows the system to automatically infer additional relationships and connections between nodes in the social graph based on the existing data.</p> <p>There are multiple formats for RDF statements. We list six most widely adopted RDF statement formats in the EIP: <code>Turtle</code>, <code>N-Triples</code>, <code>RDF/XML</code>, <code>RDF/JSON</code>,<code>N-Quads</code>, and <code>TriG</code>. These formats have different advantages and applicability in expressing, storing, and parsing RDF statements. Among these, <code>Turtle</code> is a popular format in RDF statements, due to its good human-readability and concision. It is typically used as the default format in this EIP for RDF statements. Using the Turtle format can make RDF statements easier to understand and maintain, while reducing the need for storage, suitable for representing complex RDF graphs.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backward compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/5192/">ERC-5192</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-12-27T00:00:00+00:00 2026-02-11T14:48:25+00:00 Artem Chystiakovhttps://github.com/arvolear https://wg-eips.ritovision.com/6224/

A registry for managing smart contracts with their dependencies.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces an on-chain registry system that a decentralized protocol may use to manage its smart contracts.</p> <p>The proposed system consists of two components: <code>ContractsRegistry</code> and <code>Dependant</code>. The <code>ContractsRegistry</code> contract stores references to every smart contract used within a protocol, optionally making them upgradeable by deploying self-managed proxies on top, and acts as a hub the <code>Dependant</code> contracts query to fetch their required dependencies from.</p> <h2 id="motivation">Motivation</h2> <p>In the ever-growing Ethereum ecosystem, projects tend to become more and more complex. Modern protocols require portability and agility to satisfy customer needs by continuously delivering new features and staying on pace with the industry. However, the requirement is hard to achieve due to the immutable nature of blockchains and smart contracts. Moreover, the increased complexity and continuous delivery bring bugs and entangle the dependencies between the contracts, making systems less supportable.</p> <p>Applications that have a clear architectural facade; which are designed with forward compatibility in mind; which dependencies are transparent and clean are easier to develop and maintain. The given EIP tries to solve the aforementioned problems by presenting two smart contracts: the <code>ContractsRegistry</code> and the <code>Dependant</code>.</p> <p>The advantages of using the provided system might be:</p> <ul> <li>Structured smart contracts management via specialized contracts.</li> <li>Ad-hoc upgradeability provision of a protocol.</li> <li>Runtime addition, removal, and substitution of smart contracts.</li> <li>Dependency injection mechanism to keep smart contracts' dependencies under control.</li> <li>Ability to specify custom access control rules to maintain the protocol.</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> <h3 id="overview">Overview</h3> <p>The system consists of two smart contracts:</p> <ul> <li><code>ContractsRegistry</code> that is a singleton registry to manage and upgrade a protocol's smart contracts.</li> <li><code>Dependant</code> that is a mix-in which enables a dependency injection mechanism.</li> </ul> <p>The following diagram depicts the relationship between the registry and its dependants:</p> <p><img src="https://wg-eips.ritovision.com/6224/./assets/diagram.svg" alt="" /></p> <h3 id="contractsregistry">ContractsRegistry</h3> <p>The <code>ContractsRegistry</code> is the main contract of the proposed system. It MUST store the references to every standalone contract used within a protocol. The <code>ContractRegistry</code> MAY be configured to deploy a proxy contract of choice on top of the registered contracts.</p> <p>Additionally, the <code>ContractsRegistry</code> MUST reject the registration of zero addresses.</p> <p>The <code>ContractsRegistry</code> MUST implement the following 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"> IContractsRegistry</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"> The event that is emitted when the contract gets added to the 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"> name</span><span class="z-comment"> the name 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"> contractAddress</span><span class="z-comment"> the address of the added 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"> ContractAdded</span><span>(</span><span class="z-support">string</span><span class="z-variable"> name</span><span>, </span><span class="z-support">address</span><span class="z-variable"> contractAddress</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"> The event that is emitted when the proxy contract gets added to the 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"> name</span><span class="z-comment"> the name 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"> contractAddress</span><span class="z-comment"> the address of the proxy 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"> implementation</span><span class="z-comment"> the address of the implementation 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"> ProxyContractAdded</span><span>(</span><span class="z-support">string</span><span class="z-variable"> name</span><span>, </span><span class="z-support">address</span><span class="z-variable"> contractAddress</span><span>, </span><span class="z-support">address</span><span class="z-variable"> implementation</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"> The event that is emitted when the proxy contract gets upgraded through the 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"> name</span><span class="z-comment"> the name 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"> newImplementation</span><span class="z-comment"> the address of the new implementation 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"> ProxyContractUpgraded</span><span>(</span><span class="z-support">string</span><span class="z-variable"> name</span><span>, </span><span class="z-support">address</span><span class="z-variable"> newImplementation</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"> The event that is emitted when the contract gets removed from the 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"> name</span><span class="z-comment"> the name of the removed 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"> ContractRemoved</span><span>(</span><span class="z-support">string</span><span class="z-variable"> name</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"> The function that returns an associated contract by the name. </span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if the requested contract is `address(0)`</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"> name</span><span class="z-comment"> the name of 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"> the</span><span class="z-comment"> address of 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"> getContract</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"> 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-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 function that checks if a contract with a given name has been 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"> name</span><span class="z-comment"> the name of 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"> true</span><span class="z-comment"> if the contract is present in the registry</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"> hasContract</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"> 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-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 function that injects dependencies into the given contract.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST call the `setDependencies()` with `address(this)` and `bytes(&quot;&quot;)` as arguments on the provided 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-storage z-type">@param</span><span class="z-variable z-other"> name</span><span class="z-comment"> the name of 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"> injectDependencies</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"> external</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"> The function that injects dependencies into the given contract with extra data.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST call the `setDependencies()` with `address(this)` and `data` as arguments on the provided 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-storage z-type">@param</span><span class="z-variable z-other"> name</span><span class="z-comment"> the name 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"> data</span><span class="z-comment"> the extra context data that will be passed to the dependant 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"> injectDependenciesWithData</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"> name</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 class="giallo-l"><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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> The function that upgrades added proxy contract with a new implementation.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * It is the Owner&#39;s responsibility to ensure the compatibility between implementations.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit `ProxyContractUpgraded` event</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"> name</span><span class="z-comment"> the name of the proxy 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"> newImplementation</span><span class="z-comment"> the new implementation the proxy will be upgraded 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"> upgradeContract</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"> address</span><span class="z-variable"> newImplementation</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> The function that upgrades added proxy contract with a new implementation, providing data</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * It is the Owner&#39;s responsibility to ensure the compatibility between implementations.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit `ProxyContractUpgraded` event</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"> name</span><span class="z-comment"> the name of the proxy 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"> newImplementation</span><span class="z-comment"> the new implementation the proxy will be upgraded 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"> data</span><span class="z-comment"> the data that the proxy will be called with after upgrade. This can be an ABI encoded function call</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"> upgradeContractAndCall</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"> name</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> newImplementation</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 class="giallo-l"><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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> The function that adds pure (non-proxy) contracts to the `ContractsRegistry`. The contracts MAY either be</span></span> <span class="giallo-l"><span class="z-comment"> * the ones the system does not have direct upgradeability control over or those that are not upgradeable by design.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit `ContractAdded` event. Reverts if the provided address is `address(0)`</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"> name</span><span class="z-comment"> the name to associate the contract with</span></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"> the address of the contract to be added</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"> addContract</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"> address</span><span class="z-variable"> contractAddress</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> The function that adds the proxy contracts to the registry by deploying them above the provided implementation.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * The function may be used to add a contract that the `ContractsRegistry` has to be able to upgrade.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit `ProxyContractAdded` event. Reverts if implementation address is `address(0)`</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"> name</span><span class="z-comment"> the name to associate the contract with</span></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"> the address of the implementation to point the proxy 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"> addProxyContract</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"> address</span><span class="z-variable"> contractAddress</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> The function that adds the proxy contracts to the registry by deploying them above the provided implementation,</span></span> <span class="giallo-l"><span class="z-comment"> * providing data.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * The function may be used to add a contract that the `ContractsRegistry` has to be able to upgrade.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit `ProxyContractAdded` event. Reverts if implementation address is `address(0)`</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"> name</span><span class="z-comment"> the name to associate the contract with</span></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"> the address of the 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"> data</span><span class="z-comment"> the data that the proxy will be called with. This can be an ABI encoded initialization call</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"> addProxyContractAndCall</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"> name</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> contractAddress</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 class="giallo-l"><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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> The function that adds an already deployed proxy to the `ContractsRegistry`. It MAY be used</span></span> <span class="giallo-l"><span class="z-comment"> * when the system migrates to the new `ContractRegistry`. In that case, the new registry MUST have the</span></span> <span class="giallo-l"><span class="z-comment"> * credentials to upgrade the newly added proxies.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit `ProxyContractAdded` event. Reverts if implementation address is `address(0)`</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"> name</span><span class="z-comment"> the name to associate the contract with</span></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"> the address of the proxy</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"> justAddProxyContract</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"> address</span><span class="z-variable"> contractAddress</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> The function to remove contracts from the ContractsRegistry.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit `ContractRemoved` event. Reverts if the contract is already removed</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"> name</span><span class="z-comment"> the associated name with 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"> removeContract</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"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="dependant">Dependant</h3> <p>The <code>ContractsRegistry</code> works together with the <code>Dependant</code> contract. Every standalone contract of a protocol MUST inherit <code>Dependant</code> in order to support the dependency injection mechanism.</p> <p>The required dependencies MUST be set in the overridden <code>setDependencies</code> method, not in the <code>constructor</code> or <code>initializer</code> methods.</p> <p>Only the injector MUST be able to call the <code>setDependencies</code> and <code>setInjector</code> methods. The initial injector will be a zero address, in that case, the call MUST NOT revert on access control checks.</p> <p>The <code>Dependant</code> contract MUST implement the following 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"> IDependant</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"> The function that is called from the `ContractsRegistry` to inject dependencies.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * The contract MUST perform a proper access check of `msg.sender`. The calls should only be possible from `ContractsRegistry`</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"> contractsRegistry</span><span class="z-comment"> the registry to pull dependencies from</span></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 extra data that might provide additional application-specific context</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"> setDependencies</span><span>(</span><span class="z-support">address</span><span class="z-variable"> contractsRegistry</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>;</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"> The function that sets the new dependency injector.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * The contract MUST perform a proper access check of `msg.sender`</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"> injector</span><span class="z-comment"> the new dependency injector</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"> setInjector</span><span>(</span><span class="z-support">address</span><span class="z-variable"> injector</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> The function that gets the current dependency injector</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"> current dependency injector</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"> getInjector</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> <ul> <li>The <code>Dependant</code> contract MAY store the dependency injector (usually <code>ContractsRegistry</code>) address in the special slot <code>0x3d1f25f1ac447e55e7fec744471c4dab1c6a2b6ffb897825f9ea3d2e8c9be583</code> (obtained as <code>bytes32(uint256(keccak256("eip6224.dependant.slot")) - 1)</code>).</li> </ul> <h2 id="rationale">Rationale</h2> <p>There are a few design decisions that have to be explicitly specified:</p> <h3 id="contractsregistry-rationale">ContractsRegistry Rationale</h3> <h4 id="contracts-identifier">Contracts Identifier</h4> <p>The <code>string</code> contracts identifier is chosen over the <code>uint256</code> and <code>bytes32</code> to maintain code readability and reduce the human error chances when interacting with the <code>ContractsRegistry</code>. Being the topmost smart contract of a protocol, it MAY be typical for the users to interact with it via block explorers or DAOs. Clarity was prioritized over gas usage.</p> <p>Due to the <code>string</code> identifier, the event parameters are not indexed. The <code>string indexed</code> parameter will become the <code>keccak256</code> hash of the contract name if it is larger than 32 bytes. This fact reduces readability, which was prioritized.</p> <h4 id="reverts">Reverts</h4> <p>The <code>getContract</code> view function reverts if the requested contract is <code>address(0)</code>. This is essential to minimize the risks of misinitialization of a protocol. Correct contracts SHOULD be added to the registry prior to any dependency injection actions.</p> <p>The <code>addContract</code>, <code>addProxyContract</code>, <code>addProxyContractAndCall</code>, and <code>justAddProxyContract</code> methods revert if the provided address is <code>address(0)</code> for the same risk minimization reason.</p> <h3 id="dependant-rationale">Dependant Rationale</h3> <h4 id="dependencies">Dependencies</h4> <p>The <code>data</code> parameter is provided to carry additional application-specific context. It MAY be used to extend the method's behavior.</p> <h4 id="injector">Injector</h4> <p>The <code>setInjector</code> function is made <code>external</code> to support the dependency injection mechanism for factory-made contracts. However, the method SHOULD be used with extra care.</p> <h2 id="reference-implementation">Reference Implementation</h2> <blockquote> <p>Note that the reference implementation depends on OpenZeppelin contracts <code>4.9.2</code>.</p> </blockquote> <h3 id="contractsregistry-implementation">ContractsRegistry Implementation</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-keyword">import</span><span> {</span><span class="z-entity z-name">Address</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/Address.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">TransparentUpgradeableProxy</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts/proxy/transparent/TransparentUpgradeableProxy.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">OwnableUpgradeable</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-entity z-name">Dependant</span><span>}</span><span class="z-keyword"> from</span><span class="z-string"> &quot;./Dependant.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"> IContractsRegistry</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ContractAdded</span><span>(</span><span class="z-support">string</span><span class="z-variable"> name</span><span>, </span><span class="z-support">address</span><span class="z-variable"> contractAddress</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ProxyContractAdded</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"> address</span><span class="z-variable"> contractAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> implementation</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"> ProxyContractUpgraded</span><span>(</span><span class="z-support">string</span><span class="z-variable"> name</span><span>, </span><span class="z-support">address</span><span class="z-variable"> newImplementation</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ContractRemoved</span><span>(</span><span class="z-support">string</span><span class="z-variable"> name</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"> getContract</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"> 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-storage z-type"> function</span><span class="z-entity z-name"> hasContract</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"> 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"> function</span><span class="z-entity z-name"> injectDependencies</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"> 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"> injectDependenciesWithData</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"> 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"> 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"> upgradeContract</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"> address</span><span class="z-variable"> newImplementation</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-storage z-type"> function</span><span class="z-entity z-name"> upgradeContractAndCall</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"> name</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> newImplementation</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 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"> addContract</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"> address</span><span class="z-variable"> contractAddress</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"> addProxyContract</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"> address</span><span class="z-variable"> contractAddress</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-storage z-type"> function</span><span class="z-entity z-name"> addProxyContractAndCall</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"> name</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> contractAddress</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 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"> justAddProxyContract</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"> address</span><span class="z-variable"> contractAddress</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-storage z-type"> function</span><span class="z-entity z-name"> removeContract</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"> 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">contract</span><span class="z-entity z-name"> ProxyUpgrader</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> Address</span><span class="z-keyword"> for</span><span class="z-entity z-name"> address</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 class="z-storage z-type"> immutable</span><span> _OWNER</span><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"> onlyOwner</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _onlyOwner</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"> constructor</span><span>(</span><span>)</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 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"> what_</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to_</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"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>data_</span><span>.</span><span>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"> TransparentUpgradeableProxy</span><span>(</span><span class="z-storage z-type">payable</span><span>(</span><span>what_</span><span>)</span><span>)</span><span>.</span><span class="z-entity z-name">upgradeToAndCall</span><span>(</span><span>to_</span><span>,</span><span> data_</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"> TransparentUpgradeableProxy</span><span>(</span><span class="z-storage z-type">payable</span><span>(</span><span>what_</span><span>)</span><span>)</span><span>.</span><span class="z-entity z-name">upgradeTo</span><span>(</span><span>to_</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"> getImplementation</span><span>(</span><span class="z-support">address</span><span class="z-variable"> what_</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"> onlyOwner</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"> bytes4(keccak256(&quot;implementation()&quot;)) == 0x5c60da1b</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bool</span><span> success_</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> returndata_</span><span>)</span><span class="z-keyword"> =</span><span class="z-support"> address</span><span>(</span><span>what_</span><span>)</span><span>.</span><span class="z-entity z-name">staticcall</span><span>(</span><span>hex</span><span class="z-string">&quot;5c60da1b&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>success_</span><span>,</span><span class="z-string"> &quot;ProxyUpgrader: not a proxy&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-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>returndata_</span><span>,</span><span> (</span><span class="z-support">address</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"> _onlyOwner</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> view</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_OWNER </span><span class="z-keyword">==</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span class="z-string"> &quot;ProxyUpgrader: not an owner&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">contract</span><span class="z-entity z-name"> ContractsRegistry</span><span class="z-storage"> is</span><span class="z-entity z-name"> IContractsRegistry</span><span>, </span><span class="z-entity z-name">OwnableUpgradeable</span><span> {</span></span> <span class="giallo-l"><span> ProxyUpgrader </span><span class="z-storage z-type">private</span><span> _proxyUpgrader</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">string</span><span class="z-keyword"> =&gt;</span><span class="z-support"> address</span><span>)</span><span class="z-storage z-type"> private</span><span> _contracts</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> _isProxy</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"> __ContractsRegistry_init</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> initializer</span><span> {</span></span> <span class="giallo-l"><span> _proxyUpgrader </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-entity z-name"> ProxyUpgrader</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> __Ownable_init</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"> getContract</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"> 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 class="z-keyword">=</span><span> _contracts</span><span>[</span><span>name_</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> contractAddress_ </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 class="z-string"> &quot;ContractsRegistry: this mapping doesn&#39;t exist&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> contractAddress_</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"> hasContract</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"> 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> _contracts</span><span>[</span><span>name_</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-storage z-type"> function</span><span class="z-entity z-name"> getProxyUpgrader</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>_proxyUpgrader</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"> injectDependencies</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"> 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 class="z-entity z-name"> injectDependenciesWithData</span><span>(</span><span>name_</span><span>,</span><span class="z-support"> bytes</span><span>(</span><span class="z-string">&quot;&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 class="z-storage z-type"> function</span><span class="z-entity z-name"> injectDependenciesWithData</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"> 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"> public</span></span> <span class="giallo-l"><span class="z-storage z-type"> virtual</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-support"> address</span><span> contractAddress_ </span><span class="z-keyword">=</span><span> _contracts</span><span>[</span><span>name_</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> contractAddress_ </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 class="z-string"> &quot;ContractsRegistry: this mapping doesn&#39;t exist&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> Dependant dependant_ </span><span class="z-keyword">=</span><span class="z-entity z-name"> Dependant</span><span>(</span><span>contractAddress_</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> dependant_</span><span>.</span><span class="z-entity z-name">setDependencies</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> 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"> upgradeContract</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"> address</span><span class="z-variable"> newImplementation_</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"> virtual</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"> upgradeContractAndCall</span><span>(</span><span>name_</span><span>,</span><span> newImplementation_</span><span>,</span><span class="z-support"> bytes</span><span>(</span><span class="z-string">&quot;&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 class="z-storage z-type"> function</span><span class="z-entity z-name"> upgradeContractAndCall</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"> name_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> newImplementation_</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 class="giallo-l"><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 class="z-support"> address</span><span> contractToUpgrade_ </span><span class="z-keyword">=</span><span> _contracts</span><span>[</span><span>name_</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> contractToUpgrade_ </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 class="z-string"> &quot;ContractsRegistry: this mapping doesn&#39;t exist&quot;</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> _isProxy</span><span>[</span><span>contractToUpgrade_</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;ContractsRegistry: not a proxy contract&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _proxyUpgrader</span><span>.</span><span class="z-entity z-name">upgrade</span><span>(</span><span>contractToUpgrade_</span><span>,</span><span> newImplementation_</span><span>,</span><span> data_</span><span>)</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"> ProxyContractUpgraded</span><span>(</span><span>name_</span><span>,</span><span> newImplementation_</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"> addContract</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"> address</span><span class="z-variable"> contractAddress_</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"> virtual</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-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> contractAddress_ </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 class="z-string"> &quot;ContractsRegistry: zero address is forbidden&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _contracts</span><span>[</span><span>name_</span><span>]</span><span class="z-keyword"> =</span><span> contractAddress_</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"> ContractAdded</span><span>(</span><span>name_</span><span>,</span><span> contractAddress_</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"> addProxyContract</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"> address</span><span class="z-variable"> contractAddress_</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"> virtual</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"> addProxyContractAndCall</span><span>(</span><span>name_</span><span>,</span><span> contractAddress_</span><span>,</span><span class="z-support"> bytes</span><span>(</span><span class="z-string">&quot;&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 class="z-storage z-type"> function</span><span class="z-entity z-name"> addProxyContractAndCall</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"> name_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> contractAddress_</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 class="giallo-l"><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 class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> contractAddress_ </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 class="z-string"> &quot;ContractsRegistry: zero address is forbidden&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"> address</span><span> proxyAddr_ </span><span class="z-keyword">=</span><span class="z-entity z-name"> _deployProxy</span><span>(</span></span> <span class="giallo-l"><span> contractAddress_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>(</span><span>_proxyUpgrader</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> data_</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _contracts</span><span>[</span><span>name_</span><span>]</span><span class="z-keyword"> =</span><span> proxyAddr_</span><span>;</span></span> <span class="giallo-l"><span> _isProxy</span><span>[</span><span>proxyAddr_</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-keyword"> emit</span><span class="z-entity z-name"> ProxyContractAdded</span><span>(</span><span>name_</span><span>,</span><span> proxyAddr_</span><span>,</span><span> contractAddress_</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"> justAddProxyContract</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"> address</span><span class="z-variable"> contractAddress_</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"> virtual</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-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> contractAddress_ </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 class="z-string"> &quot;ContractsRegistry: zero address is forbidden&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _contracts</span><span>[</span><span>name_</span><span>]</span><span class="z-keyword"> =</span><span> contractAddress_</span><span>;</span></span> <span class="giallo-l"><span> _isProxy</span><span>[</span><span>contractAddress_</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-keyword"> emit</span><span class="z-entity z-name"> ProxyContractAdded</span><span>(</span></span> <span class="giallo-l"><span> name_</span><span>,</span></span> <span class="giallo-l"><span> contractAddress_</span><span>,</span></span> <span class="giallo-l"><span> _proxyUpgrader</span><span>.</span><span class="z-entity z-name">getImplementation</span><span>(</span><span>contractAddress_</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"> removeContract</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"> 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 class="z-support"> address</span><span> contractAddress_ </span><span class="z-keyword">=</span><span> _contracts</span><span>[</span><span>name_</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> contractAddress_ </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 class="z-string"> &quot;ContractsRegistry: this mapping doesn&#39;t exist&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> _isProxy</span><span>[</span><span>contractAddress_</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> _contracts</span><span>[</span><span>name_</span><span>]</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"> ContractRemoved</span><span>(</span><span>name_</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"> _deployProxy</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> contractAddress_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> admin_</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 class="giallo-l"><span> )</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> virtual</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> <span class="giallo-l"><span class="z-support"> address</span><span>(</span></span> <span class="giallo-l"><span class="z-keyword"> new</span><span class="z-entity z-name"> TransparentUpgradeableProxy</span><span>(</span><span>contractAddress_</span><span>,</span><span> admin_</span><span>,</span><span> data_</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></code></pre><h3 id="dependant-implementation">Dependant Implementation</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">interface</span><span class="z-entity z-name"> IDependant</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setDependencies</span><span>(</span><span class="z-support">address</span><span class="z-variable"> contractsRegistry</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>;</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"> setInjector</span><span>(</span><span class="z-support">address</span><span class="z-variable"> injector</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"> getInjector</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> <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"> Dependant</span><span class="z-storage"> is</span><span class="z-entity z-name"> IDependant</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"> bytes32(uint256(keccak256(&quot;eip6224.dependant.slot&quot;)) - 1)</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> _INJECTOR_SLOT </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-constant"> 0x3d1f25f1ac447e55e7fec744471c4dab1c6a2b6ffb897825f9ea3d2e8c9be583</span><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"> dependant</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _checkInjector</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 class="z-entity z-name"> _setInjector</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"> function</span><span class="z-entity z-name"> setDependencies</span><span>(</span><span class="z-support">address</span><span class="z-variable"> contractsRegistry_</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"> 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"> setInjector</span><span>(</span><span class="z-support">address</span><span class="z-variable"> injector_</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _checkInjector</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setInjector</span><span>(</span><span>injector_</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"> getInjector</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"> injector_</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> slot_ </span><span class="z-keyword">=</span><span> _INJECTOR_SLOT</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> injector_ </span><span class="z-keyword">:=</span><span class="z-entity z-name"> sload</span><span>(</span><span>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"> _setInjector</span><span>(</span><span class="z-support">address</span><span class="z-variable"> injector_</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> slot_ </span><span class="z-keyword">=</span><span> _INJECTOR_SLOT</span><span>;</span></span> <span class="giallo-l"></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>slot_</span><span>,</span><span> injector_</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"> _checkInjector</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> view</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> injector_ </span><span class="z-keyword">=</span><span class="z-entity z-name"> getInjector</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>injector_ </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> injector_ </span><span class="z-keyword">==</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span class="z-string"> &quot;Dependant: not an injector&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>It is crucial for the owner of <code>ContractsRegistry</code> to keep their keys in a safe place. The loss/leakage of credentials to the <code>ContractsRegistry</code> will lead to the application's point of no return. The <code>ContractRegistry</code> is a cornerstone of a protocol, access must be granted to the trusted parties only.</p> <h3 id="contractsregistry-security">ContractsRegistry Security</h3> <ul> <li>The <code>ContractsRegistry</code> does not perform any upgradeability checks between the proxy upgrades. It is the user's responsibility to make sure that the new implementation is compatible with the old one.</li> </ul> <h3 id="dependant-security">Dependant Security</h3> <ul> <li>The <code>Dependant</code> contract MUST set its dependency injector no later than the first call to the <code>setDependencies</code> function is made. That being said, it is possible to front-run the first dependency injection.</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-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-21T00:00:00+00:00 2026-02-11T14:48:25+00:00 Anderson Chenhttps://github.com/Ankarrr Martinet Leemartinetlee@gmail.com Anton Chengantonassocareer@gmail.com https://wg-eips.ritovision.com/6229/

ERC-4626 Tokenized Vaults with Lock-in Period.

<h2 id="abstract">Abstract</h2> <p>This standard extends <a href="https://wg-eips.ritovision.com/4626/">EIP-4626</a> to support lock-in periods.</p> <h2 id="motivation">Motivation</h2> <p>The <a href="https://wg-eips.ritovision.com/4626/">EIP-4626</a> standard defines a tokenized vault allowing users (contracts or EOAs) to deposit and withdraw underlying tokens at any time. However, there exist cases where the vault needs to lock the underlying tokens (perhaps to execute certain strategies). During the lock-in period, neither withdrawals nor deposits should be allowed. This standard extends the EIP-4626 to support lock-in periods and handle scheduled deposits and withdrawals during them.</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 vaults that follow this EIP MUST implement <a href="https://wg-eips.ritovision.com/4626/">EIP-4626</a> to provide basic vault functions and <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> to represent shares.</p> <h3 id="definitions">Definitions</h3> <ul> <li>asset: The underlying <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> token that the vault accepts and manages.</li> <li>share: The EIP-20 token that the vault issued.</li> <li>locked: A status of the vault. When the vault is locked, user can’t withdraw or deposit assets from the vault.</li> <li>unlocked: A status of the vault. When the vault is unlocked, user can withdraw or deposit assets from the vault.</li> <li>round: The period that the vault is locked.</li> </ul> <h3 id="view-methods">View Methods</h3> <h4 id="islocked">isLocked</h4> <p>The current state of the vault.</p> <p><code>true</code> represents a vault is in the locked state, and <code>false</code> represents a vault is in the unlocked state.</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">sLocked</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 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"> i</span><span class="z-string">sLocked</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="vaultround">vaultRound</h4> <p>The current round of the vault.</p> <p>MUST start with <code>0</code>.</p> <p>MUST add <code>1</code> each time a new round starts, that is, when the <code>isLocked</code> becomes true. MUST NOT be modified in any other circumstances.</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">aultRound</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"> 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"> v</span><span class="z-string">aultRound</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="methods">Methods</h3> <h4 id="scheduledeposit">scheduleDeposit</h4> <p>Schedule the intent to deposit <code>assets</code> when the <code>isLocked</code> is true.</p> <p>MUST only be callable when the <code>isLocked</code> is true.</p> <p>MUST transfer the <code>assets</code> from the caller to the vault. MUST not issue new shares.</p> <p>MUST revert if <code>assets</code> cannot be deposited.</p> <p>MUST revert if the <code>isLocked</code> is false.</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"> s</span><span class="z-string">cheduleDeposit</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></code></pre><h4 id="scheduleredeem">scheduleRedeem</h4> <p>Schedule the intent to redeem <code>shares</code> from the vault when the <code>isLocked</code> is true.</p> <p>MUST only be callable when the <code>isLocked</code> is true.</p> <p>MUST transfer the <code>shares</code> from the caller to the vault. MUST not transfer assets to caller.</p> <p>MUST revert if <code>shares</code> cannot be redeemed.</p> <p>MUST revert if the <code>isLocked</code> is false.</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"> s</span><span class="z-string">cheduleRedeem</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></code></pre><h4 id="settledeposits">settleDeposits</h4> <p>Process all scheduled deposits for <code>depositor</code> and minting <code>newShares</code>.</p> <p>MUST only be callable when the <code>isLocked</code> is false.</p> <p>MUST issue <code>newShares</code> according to the current share price for the scheduled <code>depositor</code>.</p> <p>MUST revert if there is no scheduled deposit for <code>depositor</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"> s</span><span class="z-string">ettleDeposits</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"> d</span><span class="z-string">epositor</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"> 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"> n</span><span class="z-string">ewShares</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"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="settleredemptions">settleRedemptions</h4> <p>Process all scheduled redemptions for <code>redeemer</code> by burning <code>burnShares</code> and transferring <code>redeemAssets</code> to the <code>redeemer</code>.</p> <p>MUST only be callable when the <code>isLocked</code> is false.</p> <p>MUST burn the <code>burnShares</code> and transfer <code>redeemAssets</code> back to the <code>redeemer</code> according to the current share price.</p> <p>MUST revert if no scheduled redemption for <code>redeemer</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"> s</span><span class="z-string">ettleRedemptions</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"> r</span><span class="z-string">edeemer</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"> 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"> b</span><span class="z-string">urnShares</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"> 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">edeemAssets</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"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="getscheduleddeposits">getScheduledDeposits</h4> <p>Get the <code>totalAssets</code> of scheduled deposits for <code>depositor</code>.</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"> g</span><span class="z-string">etScheduledDeposits</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"> d</span><span class="z-string">epositor</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"> 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"> t</span><span class="z-string">otalAssets</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"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="getscheduledredemptions">getScheduledRedemptions</h4> <p>Get the <code>totalShares</code> of scheduled redemptions for <code>redeemer</code>.</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"> g</span><span class="z-string">etScheduledRedemptions</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"> r</span><span class="z-string">edeemer</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"> 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"> t</span><span class="z-string">otalShares</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"> u</span><span class="z-string">int256</span></span></code></pre><h3 id="events">Events</h3> <h4 id="scheduledeposit-1">ScheduleDeposit</h4> <p><code>sender</code> schedules a deposit with <code>assets</code> in this <code>round</code>.</p> <p>MUST be emitted via <code>scheduleDeposit</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"> S</span><span class="z-string">cheduleDeposit</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"> s</span><span class="z-string">ender</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">ssets</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"> r</span><span class="z-string">ound</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><h4 id="scheduleredeem-1">ScheduleRedeem</h4> <p><code>sender</code> schedules a redemption with <code>shares</code> in this <code>round</code>.</p> <p>MUST be emitted via <code>scheduleRedeem</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"> S</span><span class="z-string">cheduleRedeem</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"> s</span><span class="z-string">ender</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"> s</span><span class="z-string">hares</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"> r</span><span class="z-string">ound</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">int2</span></span></code></pre><h4 id="settledeposits-1">SettleDeposits</h4> <p>Settle scheduled deposits for <code>depositor</code> in this <code>round</code>. Issue <code>newShares</code> and transfer them to the <code>depositor</code>.</p> <p>MUST be emitted via <code>settleDeposits</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"> S</span><span class="z-string">ettleDeposits</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"> d</span><span class="z-string">epositor</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"> n</span><span class="z-string">ewShares</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">ound</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="settleredemptions-1">SettleRedemptions</h4> <p>Settle scheduled redemptions for <code>redeemer</code> in this <code>round</code>. Burn <code>burnShares</code> and transfer <code>redeemAssets</code> back to the <code>redeemer</code>.</p> <p>MUST be emitted via <code>settleRedemptions</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"> S</span><span class="z-string">ettleRedemptions</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">edeemer</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"> b</span><span class="z-string">urnShares</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">edeemAssets</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">ound</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 standard is designed to be a minimal interface. Details such as the start and end of a lock-in period, and how the underlying tokens are being used during the lock-in period are not specified.</p> <p>There is no function for scheduling a withdrawal, since during the lock-in period, the share price is undetermined, so it is impossible to determine how many underlying tokens can be withdrawn.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The <code>deposit</code>, <code>mint</code>, <code>withdraw</code>, <code>redeem</code> methods for <a href="https://wg-eips.ritovision.com/4626/">EIP-4626</a> should revert when the <code>isLocked</code> is true to prevent issuing or burning shares with an undefined share price.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Implementors need to be aware of unsettled scheduled deposits and redemptions. If a user has scheduled a deposit or redemption but does not settle when the <code>isLocked</code> is false, and then settles it after several rounds, the vault will process it with an incorrect share price. We didn’t specify the solution in the standard since there are many possible ways to solve this issue and we think implementors should decide the solution according to their use cases. For example:</p> <ul> <li>Not allow the <code>isLocked</code> to become true if there is any unsettled scheduled deposit or redemption</li> <li>Force settling the scheduled deposits or redemptions when the <code>isLocked</code> becomes true</li> <li>Memorize the ending share price for each round and let the users settle according to the share prices</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-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-12-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Bruno Škvorchttps://github.com/Swader Cicadahttps://github.com/CicadaNCR Steven Pinedahttps://github.com/steven2308 Stevan Bogosavljevichttps://github.com/stevyhacker Jan Turkhttps://github.com/ThunderDeliverer https://wg-eips.ritovision.com/6220/

An interface for Composable non-fungible tokens through fixed and slot parts equipping.

<h2 id="abstract">Abstract</h2> <p>The Composable NFTs utilizing equippable parts standard extends <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> by allowing the NFTs to selectively add parts to themselves via equipping.</p> <p>Tokens can be composed by cherry picking the list of parts from a Catalog for each NFT instance, and are able to equip other NFTs into slots, which are also defined within the Catalog. Catalogs contain parts from which NFTs can be composed.</p> <p>This proposal introduces two types of parts; slot type of parts and fixed type of parts. The slot type of parts allow for other NFT collections to be equipped into them, while fixed parts are full components with their own metadata.</p> <p>Equipping a part into an NFT doesn't generate a new token, but rather adds another component to be rendered when retrieving the token.</p> <h2 id="motivation">Motivation</h2> <p>With NFTs being a widespread form of tokens in the Ethereum ecosystem and being used for a variety of use cases, it is time to standardize additional utility for them. Having the ability for tokens to equip other tokens and be composed from a set of available parts allows for greater utility, usability and forward compatibility.</p> <p>In the four years since <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> was published, the need for additional functionality has resulted in countless extensions. This EIP improves upon ERC-721 in the following areas:</p> <ul> <li><a href="https://wg-eips.ritovision.com/6220/#composing">Composing</a></li> <li><a href="https://wg-eips.ritovision.com/6220/#token-progression">Token progression</a></li> <li><a href="https://wg-eips.ritovision.com/6220/#merit-tracking">Merit tracking</a></li> <li><a href="https://wg-eips.ritovision.com/6220/#provable-digital-scarcity">Provable Digital Scarcity</a></li> </ul> <h3 id="composing">Composing</h3> <p>NFTs can work together to create a greater construct. Prior to this proposal, multiple NFTs could be composed into a single construct either by checking all of the compatible NFTs associated with a given account and used indiscriminately (which could result in unexpected result if there was more than one NFT intended to be used in the same slot), or by keeping a custom ledger of parts to compose together (either in a smart contract or an off-chain database). This proposal establishes a standardized framework for composable NFTs, where a single NFT can select which parts should be a part of the whole, with the information being on chain. Composing NFTs in such a way allows for virtually unbounded customization of the base NFT. An example of this could be a movie NFT. Some parts, like credits, should be fixed. Other parts, like scenes, should be interchangeable, so that various releases (base version, extended cuts, anniversary editions,...) can be replaced.</p> <h3 id="token-progression">Token progression</h3> <p>As the token progresses through various stages of its existence, it can attain or be awarded various parts. This can be explained in terms of gaming. A character could be represented by an NFT utilizing this proposal and would be able to equip gear acquired through the gameplay activities and as it progresses further in the game, better items would be available. In stead of having numerous NFTs representing the items collected through its progression, equippable parts can be unlocked and the NFT owner would be able to decide which items to equip and which to keep in the inventory (not equipped) without need of a centralized party.</p> <h3 id="merit-tracking">Merit tracking</h3> <p>An equippable NFT can also be used to track merit. An example of this is academic merit. The equippable NFT in this case would represent a sort of digital portfolio of academic achievements, where the owner would be able to equip their diplomas, published articles and awards for all to see.</p> <h3 id="provable-digital-scarcity">Provable Digital Scarcity</h3> <p>The majority of current NFT projects are only mock-scarce. Even with a limited supply of tokens, the utility of these (if any) is uncapped. As an example, you can log into 500 different instances of the same game using the same wallet and the same NFT. You can then equip the same hat onto 500 different in-game avatars at the same time, because its visual representation is just a client-side mechanic.</p> <p>This proposal adds the ability to enforce that, if a hat is equipped on one avatar (by being sent into it and then equipped), it cannot be equipped on another. This provides real digital scarcity.</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="equippable-tokens">Equippable tokens</h3> <p>The interface of the core smart contract of the equippable tokens.</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"> EIP-6220 Composable NFTs utilizing Equippable Parts</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-6220</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 ERC-165 identifier for this interface is 0x28bc9ae4.</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.16</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC5773.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"> IERC6220</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC5773</span><span> /*, </span><span class="z-entity z-name">ERC165</span><span> */ </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"> Used to store the core structure of the `Equippable` component.</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"> assetId</span><span class="z-comment"> The ID of the asset equipping a child</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"> childAssetId</span><span class="z-comment"> The ID of the asset used as equipment</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"> childId</span><span class="z-comment"> The ID of token that is equipped</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"> childEquippableAddress</span><span class="z-comment"> Address of the collection to which the child asset belongs 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"> Equipment</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> assetId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> childAssetId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> childId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> childEquippableAddress</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"> Used to provide a struct for inputing equip data.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Only used for input and not storage of data.</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"> ID of the token we are managing</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"> childIndex</span><span class="z-comment"> Index of a child in the list of token&#39;s active children</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"> assetId</span><span class="z-comment"> ID of the asset that we are equipping into</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"> slotPartId</span><span class="z-comment"> ID of the slot part that we are using to equip</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"> childAssetId</span><span class="z-comment"> ID of the asset that we are equipping</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"> IntakeEquip</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 class="z-support"> uint256</span><span> childIndex</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> assetId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> slotPartId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> childAssetId</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"> Used to notify listeners that a child&#39;s asset has been equipped into one of its parent assets.</span></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 token that had an asset equipped</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assetId</span><span class="z-comment"> ID of the asset associated with the token we are equipping into</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> slotPartId</span><span class="z-comment"> ID of the slot we are using to equip</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> childId</span><span class="z-comment"> ID of the child token we are equipping into the slot</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> childAddress</span><span class="z-comment"> Address of the child token&#39;s collection</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> childAssetId</span><span class="z-comment"> ID of the asset associated with the token we are equipping</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"> ChildAssetEquipped</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"> uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> assetId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> slotPartId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> childId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> childAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> childAssetId</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"> Used to notify listeners that a child&#39;s asset has been unequipped from one of its parent assets.</span></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 token that had an asset unequipped</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assetId</span><span class="z-comment"> ID of the asset associated with the token we are unequipping out 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"> slotPartId</span><span class="z-comment"> ID of the slot we are unequipping from</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> childId</span><span class="z-comment"> ID of the token being unequipped</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> childAddress</span><span class="z-comment"> Address of the collection that a token that is being unequipped belongs 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"> childAssetId</span><span class="z-comment"> ID of the asset associated with the token we are unequipping</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"> ChildAssetUnequipped</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"> uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> assetId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> slotPartId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> childId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> childAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> childAssetId</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"> Used to notify listeners that the assets belonging to a `equippableGroupId` have been marked as</span></span> <span class="giallo-l"><span class="z-comment"> * equippable into a given slot and parent</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> equippableGroupId</span><span class="z-comment"> ID of the equippable group being marked as equippable into the slot associated with</span></span> <span class="giallo-l"><span class="z-comment"> * `slotPartId` of the `parentAddress` collection</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> slotPartId</span><span class="z-comment"> ID of the slot part of the catalog into which the parts belonging to the equippable group</span></span> <span class="giallo-l"><span class="z-comment"> * associated with `equippableGroupId` can be equipped</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> parentAddress</span><span class="z-comment"> Address of the collection into which the parts belonging to `equippableGroupId` can be</span></span> <span class="giallo-l"><span class="z-comment"> * equipped</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"> ValidParentEquippableGroupIdSet</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> equippableGroupId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> slotPartId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> parentAddress</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"> Used to equip a child into 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"> The `IntakeEquip` struct contains the following data:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * tokenId,</span></span> <span class="giallo-l"><span class="z-comment"> * childIndex,</span></span> <span class="giallo-l"><span class="z-comment"> * assetId,</span></span> <span class="giallo-l"><span class="z-comment"> * slotPartId,</span></span> <span class="giallo-l"><span class="z-comment"> * childAssetId</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"> data</span><span class="z-comment"> An `IntakeEquip` struct specifying the equip data</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"> equip</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> IntakeEquip</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</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"> Used to unequip child from parent token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This can only be called by the owner of the token or by an account that has been granted permission to</span></span> <span class="giallo-l"><span class="z-comment"> * manage the given token by the current 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"> ID of the parent from which the child is being unequipped</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assetId</span><span class="z-comment"> ID of the parent&#39;s asset that contains the `Slot` into which the child is equipped</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> slotPartId</span><span class="z-comment"> ID of the `Slot` from which to unequip the child</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"> unequip</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"> uint64</span><span class="z-variable"> assetId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> slotPartId</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"> Used to check whether the token has a given child equipped.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This is used to prevent from transferring a child that is equipped.</span></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 parent token for which we are querying 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"> childAddress</span><span class="z-comment"> Address of the child token&#39;s smart 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"> childId</span><span class="z-comment"> ID of the child 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"> bool</span><span class="z-comment"> The boolean value indicating whether the child token is equipped into the given token or 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"> isChildEquipped</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-variable"> childAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> childId</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"> Used to verify whether a token can be equipped into a given parent&#39;s slot.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> parent</span><span class="z-comment"> Address of the parent token&#39;s smart 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"> tokenId</span><span class="z-comment"> ID of the token we want to equip</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assetId</span><span class="z-comment"> ID of the asset associated with the token we want to equip</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> slotId</span><span class="z-comment"> ID of the slot that we want to equip the token into</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"> The boolean indicating whether the token with the given asset can be equipped into the desired</span></span> <span class="giallo-l"><span class="z-comment"> * slot</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"> canTokenBeEquippedWithAssetIntoSlot</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> parent</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"> uint64</span><span class="z-variable"> assetId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> slotId</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"> Used to get the Equipment object equipped into the specified slot of the desired token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The `Equipment` struct consists of the following data:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * assetId,</span></span> <span class="giallo-l"><span class="z-comment"> * childAssetId,</span></span> <span class="giallo-l"><span class="z-comment"> * childId,</span></span> <span class="giallo-l"><span class="z-comment"> * childEquippableAddress</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"> ID of the token for which we are retrieving the equipped 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"> targetCatalogAddress</span><span class="z-comment"> Address of the `Catalog` associated with the `Slot` part of 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"> slotPartId</span><span class="z-comment"> ID of the `Slot` part that we are checking for equipped objects</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"> struct</span><span class="z-comment"> The `Equipment` struct containing data about the equipped object</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"> getEquipment</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-variable"> targetCatalogAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> slotPartId</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-storage z-type">Equipment</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to get the asset and equippable data associated with given `assetId`.</span></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 token for which to retrieve the asset</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assetId</span><span class="z-comment"> ID of the asset of which we are retrieving</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"> metadataURI</span><span class="z-comment"> The metadata URI of the asset</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"> equippableGroupId</span><span class="z-comment"> ID of the equippable group this asset belongs to</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"> catalogAddress</span><span class="z-comment"> The address of the catalog the part belongs to</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"> partIds</span><span class="z-comment"> An array of IDs of parts included in the 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"> getAssetAndEquippableData</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"> assetId</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> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> metadataURI</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> equippableGroupId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> catalogAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> partIds</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="catalog">Catalog</h3> <p>The interface of the Catalog containing the equippable parts. Catalogs are collections of equippable fixed and slot parts and are not restricted to a single collection, but can support any number of NFT collections.</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"> ICatalog</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> An interface Catalog for equippable module.</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 ERC-165 identifier for this interface is 0xd912401f.</span></span> <span class="giallo-l"><span class="z-comment"> */</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.16</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"> ICatalog</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC165 </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"> Event to announce addition of a new part.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> It is emitted when a new part is 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"> partId</span><span class="z-comment"> ID of the part that was 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"> itemType</span><span class="z-comment"> Enum value specifying whether the part is `None`, `Slot` and `Fixed`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> zIndex</span><span class="z-comment"> An uint specifying the z value of the part. It is used to specify the depth which the part should</span></span> <span class="giallo-l"><span class="z-comment"> * be rendered at</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> equippableAddresses</span><span class="z-comment"> An array of addresses that can equip this part</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> metadataURI</span><span class="z-comment"> The metadata URI of the part</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"> AddedPart</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> partId</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> ItemType</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> itemType</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> zIndex</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-variable"> equippableAddresses</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 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"> Event to announce new equippables to the part.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> It is emitted when new addresses are marked as equippable for `partId`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> partId</span><span class="z-comment"> ID of the part that had new equippable addresses 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"> equippableAddresses</span><span class="z-comment"> An array of the new addresses that can equip this part</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"> AddedEquippables</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> partId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-variable"> equippableAddresses</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"> Event to announce the overriding of equippable addresses of the part.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> It is emitted when the existing list of addresses marked as equippable for `partId` is overwritten by a new</span></span> <span class="giallo-l"><span class="z-comment"> * one.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> partId</span><span class="z-comment"> ID of the part whose list of equippable addresses was overwritten</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> equippableAddresses</span><span class="z-comment"> The new, full, list of addresses that can equip this part</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"> SetEquippables</span><span>(</span><span class="z-support">uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> partId</span><span>, </span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-variable"> equippableAddresses</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"> Event to announce that a given part can be equipped by 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"> It is emitted when a given part is marked as equippable by 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"> partId</span><span class="z-comment"> ID of the part marked as equippable by any address</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"> SetEquippableToAll</span><span>(</span><span class="z-support">uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> partId</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"> Used to define a type of the item. Possible values are `None`, `Slot` or `Fixed`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Used for fixed and slot parts.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> ItemType</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> None</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Slot</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Fixed</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"> The integral structure of a standard RMRK catalog item defining it.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Requires a minimum of 3 storage slots per catalog item, equivalent to roughly 60,000 gas as of Berlin hard fork</span></span> <span class="giallo-l"><span class="z-comment"> * (April 14, 2021), though 5-7 storage slots is more realistic, given the standard length of an IPFS URI. This</span></span> <span class="giallo-l"><span class="z-comment"> * will result in between 25,000,000 and 35,000,000 gas per 250 assets--the maximum block size of Ethereum</span></span> <span class="giallo-l"><span class="z-comment"> * mainnet is 30M at peak usage.</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"> itemType</span><span class="z-comment"> The item type of the part</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"> z</span><span class="z-comment"> The z value of the part defining how it should be rendered when presenting the full 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"> equippable</span><span class="z-comment"> The array of addresses allowed to be equipped in this part</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"> metadataURI</span><span class="z-comment"> The metadata URI of the part</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"> Part</span><span> {</span></span> <span class="giallo-l"><span> ItemType itemType</span><span>;</span><span class="z-comment"> //</span><span class="z-comment">1 byte</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> z</span><span>;</span><span class="z-comment"> //</span><span class="z-comment">1 byte</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span> equippable</span><span>;</span><span class="z-comment"> //</span><span class="z-comment">n Collections that can be equipped into this slot</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> metadataURI</span><span>;</span><span class="z-comment"> //</span><span class="z-comment">n bytes 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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> The structure used to add a new `Part`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The part is added with specified ID, so you have to make sure that you are using an unused `partId`,</span></span> <span class="giallo-l"><span class="z-comment"> * otherwise the addition of the part vill be reverted.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The full `IntakeStruct` looks like this:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * partID,</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * itemType,</span></span> <span class="giallo-l"><span class="z-comment"> * z,</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * permittedCollectionAddress0,</span></span> <span class="giallo-l"><span class="z-comment"> * permittedCollectionAddress1,</span></span> <span class="giallo-l"><span class="z-comment"> * permittedCollectionAddress2</span></span> <span class="giallo-l"><span class="z-comment"> * ],</span></span> <span class="giallo-l"><span class="z-comment"> * metadataURI</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 class="z-storage z-type">@return</span><span class="z-variable z-other"> partId</span><span class="z-comment"> ID to be assigned to the `Part`</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"> part</span><span class="z-comment"> A `Part` to be added</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"> IntakeStruct</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> partId</span><span>;</span></span> <span class="giallo-l"><span> Part part</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"> Used to return the metadata URI of the associated catalog.</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"> string</span><span class="z-comment"> Base metadata URI</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"> getMetadataURI</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to return the `itemType` of the associated catalog</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"> string</span><span class="z-comment"> `itemType` of the associated catalog</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"> getType</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to check whether the given address is allowed to equip the desired `Part`.</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 collection may equip asset with `partId`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> partId</span><span class="z-comment"> The ID of the part that we are checking</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> targetAddress</span><span class="z-comment"> The address that we are checking for whether the part can be equipped into it or 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"> bool</span><span class="z-comment"> The status indicating whether the `targetAddress` can be equipped into `Part` with `partId` or 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"> checkIsEquippable</span><span>(</span><span class="z-support">uint64</span><span class="z-variable"> partId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> targetAddress</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to check if the part is equippable by all addresses.</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 part is equippable to all.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> partId</span><span class="z-comment"> ID of the part that we are checking</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"> The status indicating whether the part with `partId` can be equipped by any address or 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"> checkIsEquippableToAll</span><span>(</span><span class="z-support">uint64</span><span class="z-variable"> partId</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">@notice</span><span class="z-comment"> Used to retrieve a `Part` with id `partId`</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> partId</span><span class="z-comment"> ID of the part that we are retrieving</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"> struct</span><span class="z-comment"> The `Part` struct associated with given `partId`</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"> getPart</span><span>(</span><span class="z-support">uint64</span><span class="z-variable"> partId</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">Part</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to retrieve multiple parts at the same 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"> partIds</span><span class="z-comment"> An array of part IDs that we want to retrieve</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"> struct</span><span class="z-comment"> An array of `Part` structs associated with given `partIds`</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"> getParts</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"> partIds</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">Part</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> <p>Designing the proposal, we considered the following questions:</p> <ol> <li><strong>Why are we using a Catalog in stead of supporting direct NFT equipping?</strong><br /> If NFTs could be directly equipped into other NFTs without any oversight, the resulting composite would be unpredictable. Catalog allows for parts to be pre-verified in order to result in a composite that composes as expected. Another benefit of Catalog is the ability of defining reusable fixed parts.</li> <li><strong>Why do we propose two types of parts?</strong><br /> Some parts, that are the same for all of the tokens, don't make sense to be represented by individual NFTs, so they can be represented by fixed parts. This reduces the clutter of the owner's wallet as well as introduces an efficient way of disseminating repetitive assets tied to NFTs.<br /> The slot parts allow for equipping NFTs into them. This provides the ability to equip unrelated NFT collections into the base NFT after the unrelated collection has been verified to compose properly.<br /> Having two parts allows for support of numerous use cases and, since the proposal doesn't enforce the use of both it can be applied in any configuration needed.</li> <li><strong>Why is a method to get all of the equipped parts not included?</strong><br /> Getting all parts might not be an operation necessary for all implementers. Additionally, it can be added either as an extension, doable with hooks, or can be emulated using an indexer.</li> <li><strong>Should Catalog be limited to support one NFT collection at a time or be able to support any nunmber of collections?</strong><br /> As the Catalog is designed in a way that is agnostic to the use case using it. It makes sense to support as wide reusability as possible. Having one Catalog supporting multiple collections allows for optimized operation and reduced gas prices when deploying it and setting fixed as well as slot parts.</li> </ol> <h3 id="fixed-parts">Fixed parts</h3> <p>Fixed parts are defined and contained in the Catalog. They have their own metadata and are not meant to change through the lifecycle of the NFT.</p> <p>A fixed part cannot be replaced.</p> <p>The benefit of fixed parts is that they represent equippable parts that can be equipped by any number of tokens in any number of collections and only need to be defined once.</p> <h3 id="slot-parts">Slot parts</h3> <p>Slot parts are defined and contained in the Catalog. They don't have their own metadata, but rather support equipping of selected NFT collections into them. The tokens equipped into the slots however, contain their own metadata. This allows for an equippable modifialbe content of the base NFT controlled by its owner. As they can be equipped into any number of tokens of any number of collections, they allow for reliable composing of the final tokens by vetting which NFTs can be equipped by a given slot once and then reused any number of times.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The Equippable token standard has been made compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> in order to take advantage of the robust tooling available for implementations of ERC-721 and to ensure compatibility with existing ERC-721 infrastructure.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests are included in <a href="https://wg-eips.ritovision.com/6220/./assets/test/equippableFixedParts.ts"><code>equippableFixedParts.ts</code></a> and <a href="https://wg-eips.ritovision.com/6220/./assets/test/equippableSlotParts.ts"><code>equippableSlotParts.ts</code></a>.</p> <p>To run them in terminal, you can use the following commands:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cd ../assets/eip-6220</span></span> <span class="giallo-l"><span>npm install</span></span> <span class="giallo-l"><span>npx hardhat test</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/6220/./assets/contracts/EquippableToken.sol"><code>EquippableToken.sol</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The same security considerations as with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> apply: hidden logic may be present in any of the functions, including burn, add resource, accept resource, and more.</p> <p>Caution is advised when dealing with non-audited 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> 2022-12-19T00:00:00+00:00 2026-02-11T14:48:25+00:00 Sujith Somraajhttps://github.com/sujithsomraaj https://wg-eips.ritovision.com/6170/

A common smart contract interface for interacting with messaging protocols.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a common interface for cross-chain arbitrary message bridges (AMBs) to send and receive a cross-chain message (state).</p> <h2 id="motivation">Motivation</h2> <p>Currently, cross-chain arbitrary message bridges lack standardization, resulting in complex competing implementations: Layerzero, Hyperlane, Axelar, Wormhole, Matic State Tunnel and others. Either chain native (or) seperate message bridge, the problem prevails. Adding a common standardized interface to the arbitrary message bridges provides these benefits:</p> <ul> <li> <p><strong>Ease Of Development:</strong> A common standard interface would help developers build scalable cross-chain applications with ease.</p> </li> <li> <p><strong>Improved Scalability:</strong> Cross-chain applications can efficiently use multiple message bridges.</p> </li> <li> <p><strong>Improved Security:</strong> Confronting security to specific parameters. At present, every message bridge has its diverse security variable. E.g., In Layerzero, the nonce is used to prevent a replay attack, whereas Hyperlane uses the Merkle root hash.</p> </li> <li> <p><strong>Improved Robustness:</strong> Message bridges involving off-chain components are not censorship-resistant and are prone to downtimes. Hence, apps built on top of them have no choice but to migrate their entire state (which is highly impossible for large complex applications).</p> </li> </ul> <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>Every compliant cross-chain arbitrary message bridge 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: Apache-3.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"> &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"> @title</span><span class="z-comment"> Cross-Chain Messaging interface</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Allows seamless interchain messaging.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @author</span><span class="z-comment"> Sujith Somraaj</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-keyword"> Note</span><span class="z-comment">: Bytes are used throughout the implementation to support non-evm chains.</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"> IEIP6170</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 cross-chain message is sent.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-keyword"> Note</span><span class="z-comment">: MessageSent MUST trigger when a message is sent, including zero bytes transfers.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MessageSent</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> toChainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> message</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</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-storage z-type"> @dev</span><span class="z-comment"> This emits when a cross-chain message is received.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MessageReceived MUST trigger on any successful call to receiveMessage(bytes chainId, bytes sender, bytes message) function.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MessageReceived</span><span>(</span><span class="z-support">bytes</span><span class="z-variable"> from</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> fromChainId</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> message</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"> Sends a message to a receiving address on a different blockchain.</span></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"> is the unique identifier of receiving blockchain.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> receiver_</span><span class="z-comment"> is the address of the 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"> message_</span><span class="z-comment"> is the arbitrary message to be delivered.</span></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"> is a bridge-specific encoded data for off-chain relayer infrastructure.</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 process on the sending chain.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-keyword"> Note</span><span class="z-comment">: this function is designed to support both evm and non-evm chains</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-keyword"> Note</span><span class="z-comment">: proposing chain-ids be the bytes encoding their native token name string. For eg., abi.encode(&quot;ETH&quot;), abi.encode(&quot;SOL&quot;) imagining they cannot override.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> sendMessage</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"> chainId_</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"> receiver_</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"> message_</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 class="giallo-l"><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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Receives a message from a sender on a different blockchain.</span></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"> is the unique identifier of the sending blockchain.</span></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"> is 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"> message_</span><span class="z-comment"> is the arbitrary message sent by 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"> data_</span><span class="z-comment"> is an additional parameter to be used for security purposes. E.g, can send nonce in layerzero.</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 message processing/storage.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-keyword"> Note</span><span class="z-comment">: sender validation (or) message validation should happen before processing the message.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> receiveMessage</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"> chainId_</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"> sender_</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"> message_</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 class="giallo-l"><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><h2 id="rationale">Rationale</h2> <p>The cross-chain arbitrary messaging interface will optimize the interoperability layer between blockchains with a feature-complete yet minimal interface. The light-weighted approach also provides arbitrary message bridges, and the freedom of innovating at the relayer level, to show their technical might.</p> <p>The EIP will make blockchains more usable and scalable. It opens up the possibilities for building cross-chain applications by leveraging any two blockchains, not just those limited to Ethereum and compatible L2s. To put this into perspective, an easy-to-communicate mechanism will allow developers to build cross-chain applications across Ethereum and Solana, leveraging their unique advantages.</p> <p>The interface also aims to reduce the risks of a single point of failure (SPOF) for applications/protocols, as they can continue operating by updating their AMB address.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Fully permissionless messaging could be a security threat to the protocol. It is recommended that all the integrators review the implementation of messaging tunnels before integrating.</p> <p>Without sender authentication, anyone could write arbitrary messages into the receiving smart contract.</p> <p>This EIP focuses only on how the messages should be sent and received with a specific standard. But integrators can implement any authentication (or) message tunnel-specific operations inside the receive function leveraging <code>data_</code> parameter.</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-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Keegan Leehttps://github.com/keeganlee msfewmsfew@hyperoracle.io Kartinkartin@hyperoracle.io qizhouhttps://github.com/qizhou https://wg-eips.ritovision.com/6150/

Hierarchical NFTs, an extension to EIP-721.

<h2 id="abstract">Abstract</h2> <p>This standard is an extension to <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>. It proposes a multi-layer filesystem-like hierarchical NFTs. This standard provides interfaces to get parent NFT or children NFTs and whether NFT is a leaf node or root node, maintaining the hierarchical relationship among them.</p> <h2 id="motivation">Motivation</h2> <p>This EIP standardizes the interface of filesystem-like hierarchical NFTs and provides a reference implementation.</p> <p>Hierarchy structure is commonly implemented for file systems by operating systems such as Linux Filesystem Hierarchy (FHS).</p> <p><img src="https://wg-eips.ritovision.com/6150/./assets/linux-hierarchy.png" alt="Linux Hierarchical File Structure" /></p> <p>Websites often use a directory and category hierarchy structure, such as eBay (Home -&gt; Electronics -&gt; Video Games -&gt; Xbox -&gt; Products), and Twitter (Home -&gt; Lists -&gt; List -&gt; Tweets), and Reddit (Home -&gt; r/ethereum -&gt; Posts -&gt; Hot).</p> <p><img src="https://wg-eips.ritovision.com/6150/./assets/website-hierarchy.png" alt="Website Hierarchical Structure" /></p> <p>A single smart contract can be the <code>root</code>, managing every directory/category as individual NFT and hierarchy relations of NFTs. Each NFT's <code>tokenURI</code> may be another contract address, a website link, or any form of metadata.</p> <p>The advantages and the advancement of the Ethereum ecosystem of using this standard include:</p> <ul> <li>Complete on-chain storage of hierarchy, which can also be governed on-chain by additional DAO contract</li> <li>Only need a single contract to manage and operate the hierarchical relations</li> <li>Transferrable directory/category ownership as NFT, which is great for use cases such as on-chain forums</li> <li>Easy and permissionless data access to the hierarchical structure by front-end</li> <li>Ideal structure for traditional applications such as e-commerce, or forums</li> <li>Easy-to-understand interfaces for developers, which are similar to Linux filesystem commands in concept</li> </ul> <p>The use cases can include:</p> <ul> <li>On-chain forum, like Reddit</li> <li>On-chain social media, like Twitter</li> <li>On-chain corporation, for managing organizational structures</li> <li>On-chain e-commerce platforms, like eBay or individual stores</li> <li>Any application with tree-like structures</li> </ul> <p>In the future, with the development of the data availability solutions of Ethereum and an external permissionless data retention network, the content (posts, listed items, or tweets) of these platforms can also be entirely stored on-chain, thus realizing fully decentralized applications.</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>Every compliant contract must implement this proposal, <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and <a href="https://wg-eips.ritovision.com/165/">EIP-165</a> interfaces.</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 0x897e2c73.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6150</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC721, IERC165 </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"> Emitted when `tokenId` token under `parentId` is minted.</span></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 of 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"> to</span><span class="z-comment"> The address received 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"> parentId</span><span class="z-comment"> The id of parent token, if it&#39;s zero, it means minted `tokenId` is a root 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"> The id of minted token, required to be greater than zero</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"> Minted</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"> minter</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"> parentId</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>;</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 parent token of `tokenId` 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"> The child 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"> parentId</span><span class="z-comment"> The Parent token found</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"> parentOf</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 class="z-variable"> parentId</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 children tokens of `tokenId` 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"> The parent 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"> childrenIds</span><span class="z-comment"> The array of children 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"> childrenOf</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 class="z-storage z-type"> memory</span><span class="z-variable"> childrenIds</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"> Check the `tokenId` token if it is a root 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"> The token want to be checked</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"> Return</span><span class="z-comment"> `true` if it is a root token; if not, 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"> isRoot</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">@notice</span><span class="z-comment"> Check the `tokenId` token if it is a leaf 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"> The token want to be checked</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"> Return</span><span class="z-comment"> `true` if it is a leaf token; if not, 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"> isLeaf</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>Optional Extension: Enumerable</p> <pre class="giallo z-code"><code data-lang="solidity"><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 0xba541a2e.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6150Enumerable</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6150</span><span> /* </span><span class="z-entity z-name">IERC721Enumerable</span><span> */ </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"> Get total amount of children tokens under `parentId` token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If `parentId` is zero, it means get total amount of root 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"> The</span><span class="z-comment"> total amount of children tokens under `parentId` 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"> childrenCountOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parentId</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 token at the specified index of all children tokens under `parentId` token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If `parentId` is zero, it means get root 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"> The</span><span class="z-comment"> token ID at `index` of all chlidren tokens under `parentId` 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"> childOfParentByIndex</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> parentId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> index</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"> Get the index position of specified token in the children enumeration under specified parent 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 the `tokenId` is not found in the children enumeration.</span></span> <span class="giallo-l"><span class="z-comment"> * If `parentId` is zero, means get root token 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"> parentId</span><span class="z-comment"> The parent 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"> The specified token to be found</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 position of `tokenId` found in the children enumeration</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"> indexInChildrenEnumeration</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> parentId</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> <p>Optional Extension: Burnable</p> <pre class="giallo z-code"><code data-lang="solidity"><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 0x4ac0aa46.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6150Burnable</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6150</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"> Burn the `tokenId` 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 `tokenId` is not a leaf token.</span></span> <span class="giallo-l"><span class="z-comment"> * Throws if `tokenId` is not a valid NFT.</span></span> <span class="giallo-l"><span class="z-comment"> * Throws if `owner` is not the owner of `tokenId` token.</span></span> <span class="giallo-l"><span class="z-comment"> * Throws unless `msg.sender` is the current owner, an authorized operator, or the approved address for this 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"> The token to be burnt</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"> safeBurn</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"> Batch burn tokens.</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 one of `tokenIds` is not a leaf token.</span></span> <span class="giallo-l"><span class="z-comment"> * Throws if one of `tokenIds` is not a valid NFT.</span></span> <span class="giallo-l"><span class="z-comment"> * Throws if `owner` is not the owner of all `tokenIds` tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * Throws unless `msg.sender` is the current owner, an authorized operator, or the approved address for all `tokenIds`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> The tokens to be burnt</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"> safeBatchBurn</span><span>(</span><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 class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Optional Extension: ParentTransferable</p> <pre class="giallo z-code"><code data-lang="solidity"><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 0xfa574808.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6150ParentTransferable</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6150</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 parent of `tokenId` token </span><span class="z-keyword">changed</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"> tokenId</span><span class="z-comment"> The token </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"> oldParentId</span><span class="z-comment"> Previous parent 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"> newParentId</span><span class="z-comment"> New parent 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"> ParentTransferred</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"> oldParentId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> newParentId</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"> Transfer parentship of `tokenId` token to a new parent 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"> newParentId</span><span class="z-comment"> New parent 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"> tokenId</span><span class="z-comment"> The token to be </span><span class="z-keyword">changed</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"> transferParent</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> newParentId</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"> Batch transfer parentship of `tokenIds` to a new parent 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"> newParentId</span><span class="z-comment"> New parent 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"> tokenIds</span><span class="z-comment"> Array of token ids to be </span><span class="z-keyword">changed</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"> batchTransferParent</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> newParentId</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 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> <p>Optional Extension: Access Control</p> <pre class="giallo z-code"><code data-lang="solidity"><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 0x1d04f0b3.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6150AccessControl</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6150</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 the account whether a admin of `tokenId` token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Each token can be set more than one admin. Admin have permission to do something to the token, like mint child token,</span></span> <span class="giallo-l"><span class="z-comment"> * or burn token, or transfer parentship.</span></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 specified 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"> account</span><span class="z-comment"> The account to be checked</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 account has admin permission, return true; otherwise, 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"> isAdminOf</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"> account</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Check whether the specified parent token and account can mint children tokens</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If the `parentId` is zero, check whether account can mint root nodes</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> parentId</span><span class="z-comment"> The specified parent token to be checked</span></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 specified account to be checked</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 token and account has mint permission, return true; otherwise, 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"> canMintChildren</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> parentId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> account</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"> Check whether the specified token can be burnt by specified 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"> tokenId</span><span class="z-comment"> The specified token to be checked</span></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 specified account to be checked</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 tokenId can be burnt by account, return true; otherwise, 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"> canBurnTokenByAccount</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"> account</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> <p>As mentioned in the abstract, this EIP's goal is to have a simple interface for supporting Hierarchical NFTs. Here are a few design decisions and why they were made:</p> <h3 id="relationship-between-nfts">Relationship between NFTs</h3> <p>All NFTs will make up a hierarchical relationship tree. Each NFT is a node of the tree, maybe as a root node or a leaf node, as a parent node or a child node.</p> <p>This proposal standardizes the event <code>Minted</code> to indicate the parent and child relationship when minting a new node. When a root node is minted, parentId should be zero. That means a token id of zero could not be a real node. So a real node token id must be greater than zero.</p> <p>In a hierarchical tree, it's common to query upper and lower nodes. So this proposal standardizes function <code>parentOf</code> to get the parent node of the specified node and standardizes function <code>childrenOf</code> to get all children nodes.</p> <p>Functions <code>isRoot</code> and <code>isLeaf</code> can check if one node is a root node or a leaf node, which would be very useful for many cases.</p> <h3 id="enumerable-extension">Enumerable Extension</h3> <p>This proposal standardizes three functions as an extension to support enumerable queries involving children nodes. Each function all have param <code>parentId</code>, for compatibility, when the <code>parentId</code> specified zero means query root nodes.</p> <h3 id="parenttransferable-extension">ParentTransferable Extension</h3> <p>In some cases, such as filesystem, a directory or a file could be moved from one directory to another. So this proposal adds ParentTransferable Extension to support this situation.</p> <h3 id="access-control">Access Control</h3> <p>In a hierarchical structure, usually, there is more than one account has permission to operate a node, like mint children nodes, transfer node, burn node. This proposal adds a few functions as standard to check access control permissions.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backward compatible with <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Implementation: <a href="https://wg-eips.ritovision.com/6150/./assets/contracts/ERC6150.sol">EIP-6150</a></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-12-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Marius van der Wijdenhttps://github.com/MariusVanDerWijden https://wg-eips.ritovision.com/6122/

Modifies the forkid checks to work with timestamps and block numbers

<h2 id="abstract">Abstract</h2> <p><a href="https://wg-eips.ritovision.com/2124/">EIP-2124</a> proposed a way of identifying nodes on the p2p network based on their chain configuration via the forkid parameter. It allows nodes to cut incompatible nodes off quickly which makes the P2P network more reliable. After the merge, forks are scheduled by block time instead of block number. This EIP updates the forkid calculation with block time.</p> <h2 id="motivation">Motivation</h2> <p>While in proof-of-work forks were scheduled by block number, the proof-of-stake consensus layer schedules forks by slot number. The slot number is a time based measurement. In order to schedule forks at the same time on the consensus and execution layer, the execution layer is forced to also schedule forks by timestamp after the merge.</p> <p>The forkid calculation allows peers to quickly determine the configuration of peers and disconnect peers that are misconfigured or configured for other networks.</p> <h2 id="specification">Specification</h2> <p>Each node maintains the following values:</p> <ul> <li><strong><code>FORK_HASH</code></strong>: IEEE CRC32 checksum (<code>[4]byte</code>) of the genesis hash and fork blocks numbers or timestamps that already passed. <ul> <li>The fork block numbers or timestamps are fed into the CRC32 checksum in ascending order.</li> <li>If multiple forks are applied at the same block or time, the block number or timestamp is checksummed only once.</li> <li>Block numbers are regarded as <code>uint64</code> integers, encoded in big endian format when checksumming.</li> <li>Block timestamps are regarded as <code>uint64</code> integers, encoded in big endian format when checksumming.</li> <li>If a chain is configured to start with a non-Frontier ruleset already in its genesis, that is NOT considered a fork.</li> </ul> </li> <li><strong><code>FORK_NEXT</code></strong>: Block number or timestamp (<code>uint64</code>) of the next upcoming fork, or <code>0</code> if no next fork is known. <ul> <li>Note that it is not important to distinguish between a timestamp or a block for <code>FORK_NEXT</code>.</li> </ul> </li> </ul> <p>A <code>FORK_HASH</code> for a timestamp based fork at <code>1668000000</code> on top of homestead would be:</p> <ul> <li>forkhash₁ = <code>0xcb37b2ee</code> (homestead+fictional fork) = <code>CRC32(&lt;genesis-hash&gt; || uint64(1150000) || uint64(1668000000))</code></li> </ul> <h3 id="additional-rules">Additional rules</h3> <p>The following additional rules are applied:</p> <ul> <li>Forks by timestamp MUST be scheduled at or after the forks by block (on mainnet as well as on private networks).</li> <li>An implementation of forkid verification of remote peer needs to filter the incoming forkids first by block then by timestamp.</li> </ul> <h2 id="rationale">Rationale</h2> <p>Shanghai will be scheduled by timestamp thus the forkid calculations need to be updated to work with timestamps and blocks. Since all block number based forks are before time based forks, nodes need to check the block based forks before the time based forks.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change modifies the forkid calculation slightly. As a consequence nodes applying this change will drop peers who are not applying this change as soon as timestamp-scheduled fork occurs. This is not only expected, but actually the purpose of the forkid in the first place.</p> <h2 id="test-cases">Test Cases</h2> <p>Here's a suite of tests with mainnet config and withdrawals enabled at time <code>1668000000</code> and merge netsplit block at block <code>18000000</code></p> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span class="z-keyword">type</span><span class="z-entity z-name"> testcase</span><span class="z-keyword"> struct</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> head</span><span class="z-storage z-type"> uint64</span></span> <span class="giallo-l"><span class="z-variable z-other"> want</span><span class="z-entity z-name"> ID</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span class="z-variable z-other">tests</span><span class="z-keyword"> :=</span><span> [</span><span>]</span><span class="z-keyword">struct</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> config</span><span class="z-keyword"> *</span><span class="z-entity z-name">params</span><span>.</span><span class="z-entity z-name">ChainConfig</span></span> <span class="giallo-l"><span class="z-variable z-other"> genesis</span><span class="z-entity z-name"> common</span><span>.</span><span class="z-entity z-name">Hash</span></span> <span class="giallo-l"><span class="z-variable z-other"> cases</span><span> [</span><span>]</span><span class="z-entity z-name">testcase</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"> Withdrawal test cases</span></span> <span class="giallo-l"><span class="z-keyword"> &amp;</span><span class="z-variable z-other">withdrawalConfig</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> params</span><span>.</span><span class="z-variable z-other">MainnetGenesisHash</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>]</span><span class="z-entity z-name">testcase</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">fc64ec04</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1150000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Unsynced</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">1149999</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">fc64ec04</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1150000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Frontier block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">1150000</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">97c2c34c</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1920000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Homestead block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">1919999</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">97c2c34c</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1920000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Homestead block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">1920000</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">91d1f948</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 2463000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First DAO block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">2462999</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">91d1f948</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 2463000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last DAO block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">2463000</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">7a64da13</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 2675000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Tangerine block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">2674999</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">7a64da13</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 2675000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Tangerine block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">2675000</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">3edd5b10</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 4370000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Spurious block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">4369999</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">3edd5b10</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 4370000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Spurious block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">4370000</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">a00bc324</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 7280000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Byzantium block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7279999</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">a00bc324</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 7280000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Byzantium block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7280000</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">668db0af</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 9069000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First and last Constantinople, first Petersburg block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">9068999</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">668db0af</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 9069000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Petersburg block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">9069000</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">879d6e30</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 9200000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Istanbul and first Muir Glacier block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">9199999</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">879d6e30</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 9200000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Istanbul and first Muir Glacier block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">9200000</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">e029e991</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 12244000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Muir Glacier block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">12243999</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">e029e991</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 12244000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Muir Glacier block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">12244000</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">0eb440f6</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 12965000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Berlin block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">12964999</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">0eb440f6</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 12965000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Berlin block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">12965000</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">b715077d</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 13773000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First London block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">13772999</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">b715077d</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 13773000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last London block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">13773000</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">20c327fc</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 15050000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Arrow Glacier block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">15049999</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">20c327fc</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 15050000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Arrow Glacier block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">15050000</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">f0afd0e3</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 18000000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Gray Glacier block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">18000000</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">4fb8a872</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1668000000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Merge Start block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">20000000</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">4fb8a872</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1668000000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Merge Start block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">20000000</span><span>,</span><span class="z-constant"> 1668000000</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">c1fdf181</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Shanghai block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">20100000</span><span>,</span><span class="z-constant"> 2669000000</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">c1fdf181</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Future Shanghai block</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Here's a suite of tests of the different states a Mainnet node might be in and the different remote fork identifiers it might be required to validate and decide to accept or reject:</p> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span class="z-variable z-other">tests</span><span class="z-keyword"> :=</span><span> [</span><span>]</span><span class="z-keyword">struct</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> head</span><span class="z-storage z-type"> uint64</span></span> <span class="giallo-l"><span class="z-variable z-other"> id</span><span class="z-entity z-name"> ID</span></span> <span class="giallo-l"><span class="z-variable z-other"> err</span><span class="z-storage z-type"> error</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">/ Local is mainnet Withdrawals, remote announces the same. No future fork is announced.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">20000000</span><span>,</span><span class="z-constant"> 1668000001</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">c1fdf181</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet Withdrawals, remote announces the same also announces a next fork</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> at block/time 0xffffffff, but that is uncertain.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">20000000</span><span>,</span><span class="z-constant"> 1668000001</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">c1fdf181</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-variable z-other"> math</span><span>.</span><span class="z-variable z-other">MaxUint64</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet currently in Byzantium only (so it&#39;s aware of Petersburg &amp; Withdrawals), remote announces</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> also Byzantium, but it&#39;s not yet aware of Petersburg (e.g. non updated node before the fork).</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> In this case we don&#39;t know if Petersburg passed yet or not.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7279999</span><span>,</span><span class="z-constant"> 1667999999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">a00bc324</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet currently in Byzantium only (so it&#39;s aware of Petersburg &amp; Withdrawals), remote announces</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> also Byzantium, and it&#39;s also aware of Petersburg (e.g. updated node before the fork). We</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> don&#39;t know if Petersburg passed yet (will pass) or not.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7279999</span><span>,</span><span class="z-constant"> 1667999999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">a00bc324</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 7280000</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet currently in Byzantium only (so it&#39;s aware of Petersburg &amp; Withdrawals), remote announces</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> also Byzantium, and it&#39;s also aware of some random fork (e.g. misconfigured Petersburg). As</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> neither forks passed at neither nodes, they may mismatch, but we still connect for now.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7279999</span><span>,</span><span class="z-constant"> 1667999999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">a00bc324</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-variable z-other"> math</span><span>.</span><span class="z-variable z-other">MaxUint64</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet exactly on Withdrawals, remote announces Byzantium + knowledge about Petersburg. Remote</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> is simply out of sync, accept.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">20000000</span><span>,</span><span class="z-constant"> 1668000000</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">a00bc324</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 7280000</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet Withdrawals, remote announces Byzantium + knowledge about Petersburg. Remote</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> is simply out of sync, accept.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">20000000</span><span>,</span><span class="z-constant"> 1668000001</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">a00bc324</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 7280000</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet Withdrawals, remote announces Spurious + knowledge about Byzantium. Remote</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> is definitely out of sync. It may or may not need the Petersburg update, we don&#39;t know yet.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">20000000</span><span>,</span><span class="z-constant"> 1668000001</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">3edd5b10</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 4370000</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet Byzantium &amp; pre-withdrawals, remote announces Petersburg. Local is out of sync, accept.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7279999</span><span>,</span><span class="z-constant"> 1667999999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">668db0af</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet Spurious, remote announces Byzantium, but is not aware of Petersburg. Local</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> out of sync. Local also knows about a future fork, but that is uncertain yet.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">4369999</span><span>,</span><span class="z-constant"> 1667999999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">a00bc324</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet Withdrawals. remote announces Byzantium but is not aware of further forks.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Remote needs software update.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">20000000</span><span>,</span><span class="z-constant"> 1668000001</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">a00bc324</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-variable z-other"> ErrRemoteStale</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"> Local is mainnet Withdrawals, and isn&#39;t aware of more forks. Remote announces Petersburg +</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 0xffffffff. Local needs software update, reject.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">20000000</span><span>,</span><span class="z-constant"> 1668000001</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">5cddc0e1</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-variable z-other"> ErrLocalIncompatibleOrStale</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"> Local is mainnet Withdrawals, and is aware of Petersburg. Remote announces Petersburg +</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 0xffffffff. Local needs software update, reject.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">20000000</span><span>,</span><span class="z-constant"> 1668000001</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">5cddc0e1</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-variable z-other"> ErrLocalIncompatibleOrStale</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"> Local is mainnet Withdrawals, remote is Rinkeby Petersburg.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">20000000</span><span>,</span><span class="z-constant"> 1668000001</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">afec6b27</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-variable z-other"> ErrLocalIncompatibleOrStale</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"> Local is mainnet Withdrawals, far in the future. Remote announces Gopherium (non existing fork)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> at some future block 88888888, for itself, but past block for local. Local is incompatible.</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"> This case detects non-upgraded nodes with majority hash power (typical Ropsten mess).</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">88888888</span><span>,</span><span class="z-constant"> 1668000001</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">f0afd0e3</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 88888888</span><span>}</span><span>,</span><span class="z-variable z-other"> ErrRemoteStale</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"> Local is mainnet Withdrawals. Remote is in Byzantium, but announces Gopherium (non existing</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> fork) at block 7279999, before Petersburg. Local is incompatible.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">20000000</span><span>,</span><span class="z-constant"> 1668000001</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-entity z-name"> checksumToBytes</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">a00bc324</span><span>)</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 7279999</span><span>}</span><span>,</span><span class="z-variable z-other"> ErrRemoteStale</span><span>}</span><span>,</span></span></code></pre><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 href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-12-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Christian Frieshttps://github.com/cfries Peter Kohl-Landgrafhttps://github.com/pekola Alexandros Korpishttps://github.com/kourouta https://wg-eips.ritovision.com/6123/

A deterministic protocol for frictionless trade processing of financial contracts

<h2 id="abstract">Abstract</h2> <p>The Smart Derivative Contract (SDC) allows fully automizing and securing a financial product's - e.g. a financial derivative or bond - complete trade life cycle.<sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">1</a></sup> The SDC leverages the advantages of smart contracts to remove many of the frictions associated with the classical derivative life cycle. Most notably, the protocol allows the removal of counterpart risk essentially. The SDC can be implemented using a pre-agreed valuation oracle and valuation model, removing ambiguity in the settlement amounts. The SDC provides methods and callbacks to enable fully automated and fully transactional settlements (delivery-versus-payment, payment-vs-payment). Token-based settlement can be realized by any contract implementation implementing an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token. Proof of concepts in terms of two legally binding digital Interest Rate Swaps were conducted in 2021 and 2022.</p> <h2 id="motivation">Motivation</h2> <h3 id="rethinking-financial-derivatives">Rethinking Financial Derivatives</h3> <p>By their very nature, so-called "over-the-counter (OTC)" financial contracts are bilateral contractual agreements on exchanging long-dated cash flow schedules. Since these contracts change their intrinsic market value due to changing market environments, they are subject to counterparty credit risk when one counterparty is subject to default. The initial white paper describes the concept of a Smart Derivative Contract (SDC) with the central aim to detach bilateral financial transactions from counterparty credit risk and to remove complexities in bilateral post-trade processing by a complete redesign.</p> <h3 id="concept-of-a-smart-derivative-contract">Concept of a Smart Derivative Contract</h3> <p>A Smart Derivative Contract is a deterministic settlement protocol with the same economic behaviour as a Financial Contract - e.g. an OTC-Derivative or a Bond. Every process state is specified; therefore, the trade and post-trade process is known in advance and is deterministic over the trade's life cycle. An <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token can be used for frictionless decentralized settlement, see reference implementation. We do provide a separate interface and implementation for a specific "Settlement Token" derived from <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. These features enable two or multiple trade parties to process their financial contracts fully decentralized without relying on a third central intermediary agent. The process logic of SDC can be implemented as a finite state machine on solidity.</p> <h3 id="applications">Applications</h3> <p>The interface's life cycle functionality applies to several use cases.</p> <h4 id="settle-to-market-otc-derivative">Settle-to-Market OTC Derivative</h4> <p>In the case of a settle-to-market OTC derivative, an SDC settles the outstanding net present value of the underlying financial contract on a frequent (e.g. daily) basis. With each settlement cycle, the net present value of the underlying contract is exchanged, and the value of the contract is reset to zero. Pre-agreed margin buffers are locked at the beginning of each settlement cycle so that settlement will be guaranteed up to a certain amount. If a counterparty fails to obey contract rules, e.g. not providing sufficient pre-funding, SDC will terminate automatically with the guaranteed transfer of a termination fee by the causing party. We provide a reference implementation for this case.</p> <h4 id="callateralized-otc-derivative">Callateralized OTC Derivative</h4> <p>An implementation variante of the protocol can be used to realize a collateralized OTC derivative.[^2] Here the contract manages separate collateral and cash tokens. The constructions allows to eliminate the risk of under-collateralization. Thus, a separate initial margin is not required.</p> <h4 id="defaultable-otc-derivative">Defaultable OTC Derivative</h4> <p>A defaultable OTC Derivative has no Collateral Process in place. In that case, a smart derivative will settle the according cash flows as determined in the derivative contract specification. A defaultable OTC derivative might end in a state 'Failure to Pay' if a settlement cannot be conducted.</p> <h4 id="smart-bond-contract">Smart Bond Contract</h4> <p>The life cycle of a bond can also make use of the function catalogue below. The interface enables the issuer to allocate and redeem the bond as well as settle coupon payments. On the other hand, it allows bondholders to interact with each other, conducting secondary market trades. It all boils down to a settlement phase, which needs to be pre-agreed by both parties or triggered by the issuer which can be processed in a completely frictionless way.</p> <h2 id="specification">Specification</h2> <p>The methods and event are separated into different interfaces:</p> <ul> <li><code>ISDCTrade</code> - events and functions related to trade inception, confirmation and termination.</li> <li><code>ISDCSettlement</code> - events and functions related to the settlement life-cycle of a trade.</li> <li><code>IAsyncTransferCallback</code> - events and the callback function <code>afterTransfer</code> for settlements that utilize and external payment system.</li> <li><code>IAsyncTransfer</code> - events and functions related to async transfer (e.g., for external payment systems).</li> </ul> <p>The <code>ISDC</code> interface is the aggregation of <code>ISDCTrade</code>, <code>ISDCSettlement</code> and <code>IAsyncTransferCallback</code>.</p> <h3 id="methods-of-isdctrade">Methods of <code>ISDCTrade</code></h3> <p>The following methods specify a Smart Derivative Contract's trade initiation, trade termination and settlement life cycle. For further information, please also look at the interface documentation <code>ISDC.sol</code>.</p> <h4 id="trade-initiation-phase-incepttrade">Trade Initiation Phase: <code>inceptTrade</code></h4> <p>A party can initiate a trade by providing the party address to trade with, trade data, trade position, payment amount for the trade and initial settlement data. Only registered counterparties are allowed to use that 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"> inceptTrade</span><span>(</span><span class="z-support">address</span><span class="z-variable"> withParty</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tradeData</span><span>,</span><span class="z-support"> int</span><span class="z-variable"> position</span><span>,</span><span class="z-support"> int256</span><span class="z-variable"> paymentAmount</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> initialSettlementData</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>;</span></span></code></pre> <p>The position and the paymentAmount are viewed from the incepter. The function will return a generated unique <code>tradeId</code>. The trade id will also be emitted by an event.</p> <h4 id="trade-initiation-phase-confirmtrade">Trade Initiation Phase: <code>confirmTrade</code></h4> <p>A counterparty can confirm a trade by providing its trade specification data, which then gets matched against the data stored from <code>inceptTrade</code> call.</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"> confirmTrade</span><span>(</span><span class="z-support">address</span><span class="z-variable"> withParty</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tradeData</span><span>,</span><span class="z-support"> int</span><span class="z-variable"> position</span><span>,</span><span class="z-support"> int256</span><span class="z-variable"> paymentAmount</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> initialSettlementData</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Here, the position and the paymentAmount is viewed from the confimer (opposite sign compared to the call to <code>inceptTrade</code>).</p> <h4 id="trade-initiation-phase-canceltrade">Trade Initiation Phase: <code>cancelTrade</code></h4> <p>The counterparty that called <code>inceptTrade</code> has the option to cancel the trade, e.g., in the case where the trade is not confirmed in a timely manner.</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"> cancelTrade</span><span>(</span><span class="z-support">address</span><span class="z-variable"> withParty</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tradeData</span><span>,</span><span class="z-support"> int</span><span class="z-variable"> position</span><span>,</span><span class="z-support"> int256</span><span class="z-variable"> paymentAmount</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> initialSettlementData</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre><h4 id="trade-termination-requesttermination">Trade Termination: <code>requestTermination</code></h4> <p>Allows an eligible party to request a mutual termination of the trade with the corresponding <code>tradeId</code> with a termination amount she is willing to pay and provide further termination terms (e.g. an XML)</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"> requestTradeTermination</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tradeId</span><span>,</span><span class="z-support"> int256</span><span class="z-variable"> terminationPayment</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> terminationTerms</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre><h4 id="trade-termination-confirmtradetermination">Trade Termination: <code>confirmTradeTermination</code></h4> <p>Allows an eligible party to confirm a previously requested (mutual) trade termination, including termination payment value and termination terms</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"> confirmTradeTermination</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tradeId</span><span>,</span><span class="z-support"> int256</span><span class="z-variable"> terminationPayment</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> terminationTerms</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre><h4 id="trade-termination-canceltradetermination">Trade Termination: <code>cancelTradeTermination</code></h4> <p>The party that initiated <code>requestTradeTermination</code> has the option to withdraw the request, e.g., in the case where the termination is not confirmed in a timely manner.</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"> cancelTradeTermination</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tradeId</span><span>,</span><span class="z-support"> int256</span><span class="z-variable"> terminationPayment</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> terminationTerms</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre><h3 id="methods-of-isdcsettlement">Methods of <code>ISDCSettlement</code></h3> <h4 id="settlement-phase-initiatesettlement">Settlement Phase: <code>initiateSettlement</code></h4> <p>Allows eligible participants (such as counterparties or a delegated agent) to trigger a settlement phase.</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"> initiateSettlement</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre><h4 id="settlement-phase-performsettlement">Settlement Phase: <code>performSettlement</code></h4> <p>Valuation may be provided on-chain or off-chain via an external oracle service that calculates the settlement or coupon amounts and uses external market data. This method serves as a callback called from an external oracle providing settlement amount and used settlement data, which also get stored. The settlement amount will be checked according to contract terms, resulting in either a regular settlement or a termination of the trade.</p> <p>The method may perform a synchonous transfer of the settlement or make use of an <code>IAsyncTransfer</code>, which will finalize the transfer though the callback <code>afterTransfer</code>.</p> <p>The transactionData is emitted as part of the corresponding event: <code>SettlementTransferred</code> or <code>SettlementFailed</code> This might result in a termination or start of the next settlement phase, depending on the provided success flag.</p> <p>The parameter <code>settlementData</code> will be ussed as <code>lastSettlementData</code> as part of the <code>SettlementRequested</code> event (see there) and may contain updates to the determination of the next settlement, e.g., data to determine the reference value for margining or the specification of updated margin buffer values.</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"> performSettlement</span><span>(</span><span class="z-support">int256</span><span class="z-variable"> settlementAmount</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> settlementData</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre><h4 id="settlement-phase-aftersettlement">Settlement Phase: <code>afterSettlement</code></h4> <p>The method is called to verify and prepare the next settlement and move to that phase. The method may trigger optional checks (e.g. pre-funding check).</p> <p>Depending on the implementation, this method may be called automatically at the end of performSettlement or called externally (e.g. from a time-oracle to allow for a time-period to prepare the next settlement).</p> <ul> <li>An implementation that uses adjusting of pre-funding can check the pre-funding within this method.</li> <li>An implementation that checked a static pre-funding upon confirmation of the trade might not require this step.</li> </ul> <p>In any case, the method may trigger termination if the settlement failed.</p> <p>Emits a <code>SettlementTransferred</code> or a <code>SettlementFailed</code> event. May emit a <code>TradeTerminated</code> 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"> afterSettlement</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre><h3 id="methods-of-iasynctransfercallback">Methods of <code>IAsyncTransferCallback</code></h3> <h4 id="settlement-phase-aftertransfer">Settlement Phase: <code>afterTransfer</code></h4> <p>This method is called back from a settlement token or from an eligible address if the transfer of the settlement amount was successful. - completes the settlement transfer. The transactionData is emitted as part of the corresponding event: <code>SettlementTransferred</code> or <code>SettlementFailed</code> This might result in a termination or start of the next settlement phase, depending on the provided success flag.</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"> afterTransfer</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> transactionID</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> transactionData</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre><h3 id="trade-events">Trade Events</h3> <p>The following events are emitted during an SDC Trade life-cycle.</p> <h4 id="tradeincepted">TradeIncepted</h4> <p>Emitted on trade inception - method 'inceptTrade'</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"> TradeIncepted</span><span>(</span><span class="z-support">address</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">string</span><span class="z-variable"> tradeId</span><span>, </span><span class="z-support">string</span><span class="z-variable"> tradeData</span><span>)</span><span>;</span></span></code></pre><h4 id="tradeconfirmed">TradeConfirmed</h4> <p>Emitted on trade confirmation - method 'confirmTrade'</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"> TradeConfirmed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> confirmer</span><span>, </span><span class="z-support">string</span><span class="z-variable"> tradeId</span><span>)</span><span>;</span></span></code></pre><h4 id="tradecanceled">TradeCanceled</h4> <p>Emitted on trade cancellation - method 'cancelTrade'</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"> TradeCanceled</span><span>(</span><span class="z-support">address</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">string</span><span class="z-variable"> tradeId</span><span>)</span><span>;</span></span></code></pre><h4 id="tradeactivated">TradeActivated</h4> <p>Emitted when a Trade is activated</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"> TradeActivated</span><span>(</span><span class="z-support">string</span><span class="z-variable"> tradeId</span><span>)</span><span>;</span></span></code></pre><h4 id="tradeterminationrequest">TradeTerminationRequest</h4> <p>Emitted when termination request is initiated by a counterparty</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"> TradeTerminationRequest</span><span>(</span><span class="z-support">address</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">string</span><span class="z-variable"> tradeId</span><span>, </span><span class="z-support">int256</span><span class="z-variable"> terminationPayment</span><span>, </span><span class="z-support">string</span><span class="z-variable"> terminationTerms</span><span>)</span><span>;</span></span></code></pre><h4 id="tradeterminationconfirmed">TradeTerminationConfirmed</h4> <p>Emitted when termination request is confirmed by a counterparty</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"> TradeTerminationConfirmed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> confirmer</span><span>, </span><span class="z-support">string</span><span class="z-variable"> tradeId</span><span>, </span><span class="z-support">int256</span><span class="z-variable"> terminationPayment</span><span>, </span><span class="z-support">string</span><span class="z-variable"> terminationTerms</span><span>)</span><span>;</span></span></code></pre><h4 id="tradeterminationcanceled">TradeTerminationCanceled</h4> <p>Emitted when termination request is canceled by the requesting counterparty</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"> TradeTerminationCanceled</span><span>(</span><span class="z-support">address</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">string</span><span class="z-variable"> tradeId</span><span>, </span><span class="z-support">string</span><span class="z-variable"> terminationTerms</span><span>)</span><span>;</span></span></code></pre><h4 id="tradeterminated">TradeTerminated</h4> <p>Emitted when trade is terminated</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"> TradeTerminated</span><span>(</span><span class="z-support">string</span><span class="z-variable"> cause</span><span>)</span><span>;</span></span></code></pre><h3 id="settlement-events">Settlement Events</h3> <p>The following events are emitted during the settlement phases.</p> <h4 id="settlementrequested">SettlementRequested</h4> <p>Emitted when a settlement is requested (via <code>initiateSettlement</code>). May trigger the settlement phase.</p> <p>The argument <code>lastSettlementData</code> is the one that was passed upon a previous settlement in <code>performSettlement</code> (under the name <code>settlementData</code>). It may be used to pass updated settlement specific information calculated during the previous settlement, e.g., when margin buffer amounts are a function of market parameters. In case of an external oracle it can pass the <code>settlementData</code> via <code>performSettlement</code> and pick it up in the <code>SettlementRequested</code> event (allows for stateless external oracles).</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"> SettlementRequested</span><span>(</span><span class="z-support">address</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">string</span><span class="z-variable"> tradeData</span><span>, </span><span class="z-support">string</span><span class="z-variable"> lastSettlementData</span><span>)</span><span>;</span></span></code></pre><h4 id="settlementdetermined">SettlementDetermined</h4> <p>Emitted when the settlement phase is started (via <code>performSettlement</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"> SettlementDetermined</span><span>(</span><span class="z-support">address</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">int256</span><span class="z-variable"> settlementAmount</span><span>, </span><span class="z-support">string</span><span class="z-variable"> settlementData</span><span>)</span><span>;</span></span></code></pre><h4 id="settlementtransferred">SettlementTransferred</h4> <p>Emitted when the settlement succeeded.</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"> SettlementTransferred</span><span>(</span><span class="z-support">string</span><span class="z-variable"> transactionData</span><span>)</span><span>;</span></span></code></pre><h4 id="settlementfailed">SettlementFailed</h4> <p>Emitted when the settlement failed.</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"> SettlementFailed</span><span>(</span><span class="z-support">string</span><span class="z-variable"> transactionData</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The interface design and reference implementation are based on the following considerations:</p> <ul> <li>An SDC protocol enables interacting parties to initiate and process a financial transaction in a bilateral and deterministic manner. Settlement and Counterparty Risk is managed by the contract.</li> <li>The provided interface specification is supposed to completely reflect the entire trade life cycle.</li> <li>The interface specification is generic enough to handle the case that parties process one or even multiple financial transactions (on a netted base)</li> <li>Usually, the valuation of financial trades (e.g. OTC Derivatives) will require advanced valuation methodology to determine the market value. This is why the concept might rely on an external market data source and hosted valuation algorithms</li> <li>A pull-based valuation-based oracle pattern can be implemented by using the provided callback pattern (methods: <code>initiateSettlement</code>, <code>performSettlement</code>)</li> <li>The reference implementation <code>SDCSingleTrade.sol</code> considers a single trade and is based on a state-machine pattern where the states also serve as guards (via modifiers) to check which method is allowed to be called at a particular given process and trade state</li> <li>The interface allows the extension to multiple trades with common (netted) settlement.</li> </ul> <h3 id="state-diagram-of-trade-and-process-states">State diagram of trade and process states</h3> <p><img src="https://wg-eips.ritovision.com/6123/./assets/doc/sdc_trade_states.svg" alt="image info" /></p> <p>The diagram shows the trade states of a single trade SDC as in <code>SDCSingleTrade.sol</code>.</p> <h3 id="sequence-diagram-of-reference-implementation-sdcpledgedbalance-sol">Sequence diagram of reference implementation 'SDCPledgedBalance.sol'</h3> <p>The following sequence diagram shows the function calls that create the trade and stellement state transitions and the emitted events. Shown is the implementation variante that</p> <ul> <li>utilizes an asynchronous settlement through a settlement token (see the interface <code>IAsyncTransfer</code>, <code>IAsyncTransferCallback</code>)</li> <li>receives the trigger <code>afterSettlement</code> to perfrom checks of settlement pre-conditions (see the corresponding method description <code>afterSettlement</code>)</li> </ul> <p><img src="https://wg-eips.ritovision.com/6123/./assets/doc/sequence.svg" alt="image info" /></p> <h3 id="sequence-diagram-of-an-implementation-variant-with-a-separate-collateral-account">Sequence diagram of an implementation variant with a separate collateral account</h3> <p>The following sequence diagram shows the implementation variant with a separate collateral account. This diagram show the settlement phase.</p> <p><img src="https://wg-eips.ritovision.com/6123/./assets/doc/sequence-sdc-collateral-settlement.svg" alt="image info" /></p> <h2 id="test-cases">Test Cases</h2> <p>Life-cycle unit tests based on the sample implementation and usage of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token is provided. See file <a href="https://wg-eips.ritovision.com/6123/./assets/test/SDCTests.js">test/SDCTests.js</a> ).</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>An abstract contract class <code>SDCSingleTrade.sol</code> for single trade SDCs as well as a full reference implementation SDCPledgedBalance.sol for an OTC-Derivative is provided and is based on the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token standard. See folder <code>/assets/contracts</code>, more explanation on the implementation is provided inline.</p> <h3 id="trade-data-specification-suggestion">Trade Data Specification (suggestion)</h3> <p>Please take a look at the provided xml file as a suggestion on how trade parameters could be stored.</p> <h2 id="security-considerations">Security Considerations</h2> <p>No known security issues up to 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> <section class="footnotes"> <ol class="footnotes-list"> <li id="fn-1"> <p>Fries, C. P., &amp; Kohl-Landgraf, P. (2018). Smart Derivative Contracts (Detaching Transactions from Counterparty Credit Risk: Specification, Parametrisation, Valuation). <span style="font-style: italic;">SSRN Electronic Journal</span>. https://doi.org/<a href="https://doi.org/10.2139/ssrn.3163074">10.2139/ssrn.3163074</a> (Original work published 2018)[^2]: Fries, C. P., Kohl-Landgraf, P., Prandtl, R., &amp; Schütte, W. (2025). A Smart Derivative Contract with Collateral. <span style="font-style: italic;">SSRN Electronic Journal</span>. https://doi.org/<a href="https://doi.org/10.2139/ssrn.5454714">10.2139/ssrn.5454714</a> (Original work published 2025) <a href="#fr-1-1">↩</a></p> </li> </ol> </section> 2022-12-12T00:00:00+00:00 2026-02-11T14:48:25+00:00 Derionhttps://github.com/derion-io Zergityhttps://github.com/Zergity Ngo Quang Anhhttps://github.com/anhnq82 BerlinPhttps://github.com/BerlinP Khanh Phamhttps://github.com/blackskin18 Hal Blackburnhttps://github.com/h4l https://wg-eips.ritovision.com/6120/

A singleton router contract allows tokens to be spent in the transfer-and-call pattern instead of approve-then-call.

<h2 id="abstract">Abstract</h2> <p>The default transaction behavior of ETH is <em>transfer-and-call</em>, but the widely used <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard isn't compatible with this pattern. This incompatibility forces applications to use an inefficient and risky two-step <em>approve-then-call</em> process. This approach is costly, creates a poor user experience, and introduces significant security vulnerabilities, as users must approve unaudited and often upgradable contracts. This has led to numerous allowance-related bugs and exploits.</p> <p>The <strong>Universal Token Router</strong> (<strong>UTR</strong>) addresses this issue by separating the token allowance from the application logic. This allows any token to be spent in a single contract call, similar to how ETH is handled, without needing to approve individual application contracts. When tokens are approved to the <strong>UTR</strong>, they can only be spent in transactions signed directly by the token owner. The <strong>UTR</strong>'s transaction data clearly shows key details like token types, amounts, and the recipient.</p> <p>The <strong>UTR</strong> promotes the <strong>security-by-result</strong> model over the <strong>security-by-process</strong> model. By allowing applications to verify the output of a transaction (e.g., checking token balance changes), users' funds can be secure even when interacting with potentially flawed or malicious contracts.</p> <p>The <strong>UTR</strong> contract is deployed at <code>0x69c4620b62D99f524c5B4dE45442FE2D7dD59576</code> on all EVM-compatible networks using the <a href="https://wg-eips.ritovision.com/1014/">EIP-1014</a> SingletonFactory. This allows new token contracts to pre-configure it as a trusted spender, eliminating the need for approval transactions entirely for their interactive usage.</p> <h2 id="motivation">Motivation</h2> <p>When users approve their tokens to a contract, they expect that:</p> <ul> <li>it only spends the tokens with their permission (from <code>msg.sender</code> or <code>ecrecover</code>)</li> <li>it does not use <code>delegatecall</code> (e.g. upgradable proxies)</li> </ul> <p>The <strong>UTR</strong> ensures these same security conditions, allowing all interactive applications to share a single, secure token allowance. This saves most approval transactions for existing tokens and <strong>all</strong> approval transactions for new ones.</p> <p>Before the <strong>UTR</strong>, users had to blindly trust the front-end code of applications to construct transactions honestly. This made them highly vulnerable to phishing. The <strong>UTR</strong>'s function arguments act as a manifest that wallets can display to users, allowing them to review the expected token behavior before signing, making phishing attacks much easier to detect.</p> <p>Most existing application contracts are already compatible with the <strong>UTR</strong> and can integrate it to gain several benefits:</p> <ul> <li>Securely share a user's token allowance across all applications.</li> <li>Update their own peripheral contracts as often as needed without requiring new user approvals.</li> <li>Save development and security audit costs on their own router contracts.</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>The main interface of the UTR 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"> IUniversalTokenRouter</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> exec</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> Output</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> outputs</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> Action</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> actions</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> payable</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="output-verification">Output Verification</h3> <p><code>Output</code> defines the expected token balance change for verification.</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"> Output</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> eip</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> token standard: 0 for ETH or EIP number</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> token</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> token contract address</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> id</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> token id for ERC-721 and ERC-1155</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> amountOutMin</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Token balances of the <code>recipient</code> address are recorded at the beginning and the end of the <code>exec</code> function for each item in <code>outputs</code>. Transaction will revert with <code>INSUFFICIENT_OUTPUT_AMOUNT</code> if any of the balance changes are less than its <code>amountOutMin</code>.</p> <p>A special id <code>ERC_721_BALANCE</code> is reserved for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, which can be used in output actions to verify the total amount of all ids owned by the <code>recipient</code> address.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>ERC_721_BALANCE </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&#39;UniversalTokenRouter.ERC_721_BALANCE&#39;</span><span>)</span></span></code></pre><h3 id="action">Action</h3> <p><code>Action</code> defines the token inputs and the contract call.</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"> Action</span><span> {</span></span> <span class="giallo-l"><span> Input</span><span>[</span><span>]</span><span> inputs</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> code</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> contract code address</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> data</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> contract input data</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The action code contract MUST implement the <code>NotToken</code> contract or the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface with the ID <code>0x61206120</code> in order to be called by the UTR. This interface check prevents the direct invocation of token <em>allowance-spending</em> functions (e.g., <code>transferFrom</code>) by the UTR. Therefore, new token contracts MUST NOT implement this interface ID.</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"> * This contract will conflict with the ERC20, ERC721, and ERC1155 standards,</span></span> <span class="giallo-l"><span class="z-comment"> * preventing token contracts from accidentally implementing it.</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"> NotToken</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>,</span><span class="z-support"> address</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 class="z-keyword"> return</span><span class="z-string"> &quot;THIS IS NOT A TOKEN&quot;</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>,</span><span class="z-support"> address</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 class="z-keyword"> return</span><span class="z-string"> &quot;THIS IS NOT A TOKEN&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 class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Application</span><span class="z-storage"> is</span><span class="z-entity z-name"> NotToken</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> this contract can be used with the UTR</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="input">Input</h3> <p><code>Input</code> defines the input token to transfer or prepare before the action contract is executed.</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"> Input</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> mode</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> eip</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> token standard: 0 for ETH or EIP number</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> token</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> token contract address</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> id</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> token id for ERC-721 and ERC-1155</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> amountIn</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>mode</code> takes one of the following values:</p> <ul> <li><code>PAYMENT = 0</code>: pend a payment for the token to be transferred from <code>msg.sender</code> to the <code>recipient</code> by calling <code>UTR.pay</code> from anywhere in the same transaction.</li> <li><code>TRANSFER = 1</code>: transfer the token directly from <code>msg.sender</code> to the <code>recipient</code>.</li> <li><code>CALL_VALUE = 2</code>: record the <code>ETH</code> amount to pass to the action as the call <code>value</code>.</li> </ul> <p>Each input in the <code>inputs</code> argument is processed sequentially. For simplicity, duplicated <code>PAYMENT</code> and <code>CALL_VALUE</code> inputs are valid, but only the last <code>amountIn</code> value is used.</p> <h4 id="payment-input">Payment Input</h4> <p><code>PAYMENT</code> is the recommended mode for application contracts that use the <em>transfer-in-callback</em> pattern. E.g., flashloan contracts, Uniswap/v3-core, Derion, etc.</p> <p>For each <code>Input</code> with <code>PAYMENT</code> mode, at most <code>amountIn</code> of the token can be transferred from <code>msg.sender</code> to the <code>recipient</code> by calling <code>UTR.pay</code> from anywhere in the same transaction.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>UTR</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | PAYMENT</span></span> <span class="giallo-l"><span> | (payments pended for UTR.pay)</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | Application Contracts</span></span> <span class="giallo-l"><span>action.code.call ---------------------&gt; |</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span>UTR.pay &lt;----------------------- (call) |</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | &lt;-------------------------- (return) |</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | (clear all pending payments)</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span>END</span></span></code></pre> <p>Token's allowance and <code>PAYMENT</code> are essentially different as:</p> <ul> <li>allowance: allow a specific <code>spender</code> to transfer the token to anyone at any time.</li> <li><code>PAYMENT</code>: allow anyone to transfer the token to a specific <code>recipient</code> only in that transaction.</li> </ul> <h5 id="spend-payment">Spend Payment</h5> <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"> IUniversalTokenRouter</span><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-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> payment</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>To call <code>pay</code>, the <code>payment</code> param must be encoded as follows:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>payment </span><span class="z-keyword">=</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> payer</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> address</span></span> <span class="giallo-l"><span> recipient</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> address</span></span> <span class="giallo-l"><span> eip</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><span> token</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> address</span></span> <span class="giallo-l"><span> id </span><span class="z-comment">//</span><span class="z-comment"> uint256</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre> <p>The <code>payment</code> bytes can also be used by adapter UTR contracts to pass contexts and payloads for performing custom payment logic.</p> <h5 id="discard-payment">Discard Payment</h5> <p>Sometimes, it's useful to discard the payment instead of performing the transfer, for example, when the application contract wants to burn its own token from <code>payment.payer</code>. The following function can be used to verify the payment to the caller's address and discard a portion of it.</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"> IUniversalTokenRouter</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> discard</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> payment</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Please refer to the <a href="https://wg-eips.ritovision.com/6120/#discard-payment-1">Discard Payment</a> section in the <strong>Security Considerations</strong> for an important security note.</p> <h5 id="sender-authentication">Sender Authentication</h5> <p>Discarding payment also makes sender authentication possible with a router, which is never achievable with regular routers. By inputting a pseudo payment (not a token payment), the UTR allows the target contract to verify the sender's address for authentication, along with normal token transfers and payments.</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"> AuthChecker</span><span class="z-storage"> is</span><span class="z-entity z-name"> NotToken</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> must be trusted with a proper implementation of discard function</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> immutable</span><span> UTR</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"> actionMustSentBySender</span><span>(</span><span class="z-support">address</span><span class="z-variable"> sender</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> payment </span><span class="z-keyword">=</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 class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-support"> address</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-entity z-name"> IUniversalTokenRouter</span><span>(</span><span>UTR</span><span>)</span><span>.</span><span class="z-entity z-name">discard</span><span>(</span><span>payment</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></span></code></pre><pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-keyword">await</span><span class="z-variable z-other"> utr</span><span>.</span><span class="z-entity z-name">exec</span><span>(</span><span>[</span><span>]</span><span>,</span><span> [</span><span>{</span></span> <span class="giallo-l"><span> inputs</span><span>:</span><span> [</span><span>{</span></span> <span class="giallo-l"><span> mode</span><span>:</span><span class="z-variable z-other z-constant"> PAYMENT</span><span>,</span></span> <span class="giallo-l"><span> eip</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span> token</span><span>:</span><span class="z-variable z-other"> AddressZero</span><span>,</span></span> <span class="giallo-l"><span> id</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span> amountIn</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span> recipient</span><span>:</span><span class="z-variable z-other"> paymentTest</span><span>.</span><span class="z-variable z-other">address</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> code</span><span>:</span><span class="z-variable z-other"> authChecker</span><span>.</span><span class="z-variable z-other">address</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span> (</span><span class="z-keyword">await</span><span class="z-variable z-other"> authChecker</span><span>.</span><span class="z-variable z-other">populateTransaction</span><span>.</span><span class="z-entity z-name">actionMustSentBySender</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><span class="z-variable z-other">data</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>]</span><span>)</span></span></code></pre> <p>Please refer to the <a href="https://wg-eips.ritovision.com/6120/#discard-payment-1">Discard Payment</a> section in the <strong>Security Considerations</strong> for an important security note.</p> <h5 id="payment-lifetime">Payment Lifetime</h5> <p>Payments are recorded in the UTR storage and intended to be spent by <code>input.action</code> external calls only within that transaction. All payment storages will be cleared before the <code>UTR.exec</code> ends.</p> <h3 id="native-token-tranfer">Native Token Tranfer</h3> <p>The <code>UTR</code> SHOULD have a <code>receive()</code> function for user execution logic that requires transferring ETH in. The <code>msg.value</code> transferred into the router can be spent in multiple inputs across different actions. While the caller takes full responsibility for the movement of <code>ETH</code> in and out of the router, the <code>exec</code> function SHOULD refund any remaining <code>ETH</code> before the function ends.</p> <p>Please refer to the <a href="https://wg-eips.ritovision.com/6120/#reentrancy">Reentrancy</a> section in the <strong>Security Considerations</strong> for information on reentrancy risks and mitigation.</p> <h3 id="usage-examples">Usage Examples</h3> <h4 id="uniswap-v2-router">Uniswap V2 Router</h4> <p>Legacy function:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>UniswapV2Router01</span><span>.</span><span class="z-entity z-name">swapExactTokensForTokens</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> amountIn</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> amountOutMin</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> path</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"> uint</span><span> deadline</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p><code>UniswapV2Helper01.swapExactTokensForTokens</code> is a modified version of it without the token transfer part.</p> <p>This transaction is signed by users to execute the swap instead of the legacy function:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">UniversalTokenRouter</span><span>.</span><span class="z-entity z-name">exec</span><span>(</span><span>[</span><span>{</span></span> <span class="giallo-l"><span> recipient</span><span>:</span><span class="z-variable z-other"> to</span><span>,</span></span> <span class="giallo-l"><span> eip</span><span>:</span><span class="z-constant"> 20</span><span>,</span></span> <span class="giallo-l"><span> token</span><span>:</span><span class="z-variable z-other"> path</span><span>[</span><span class="z-variable z-other">path</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>,</span></span> <span class="giallo-l"><span> id</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> amountOutMin</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>]</span><span>,</span><span> [</span><span>{</span></span> <span class="giallo-l"><span> inputs</span><span>:</span><span> [</span><span>{</span></span> <span class="giallo-l"><span> mode</span><span>:</span><span class="z-variable z-other z-constant"> TRANSFER</span><span>,</span></span> <span class="giallo-l"><span> recipient</span><span>:</span><span class="z-variable z-other"> UniswapV2Library</span><span>.</span><span class="z-entity z-name">pairFor</span><span>(</span><span class="z-variable z-other">factory</span><span>,</span><span class="z-variable z-other"> path</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other"> path</span><span>[</span><span class="z-constant">1</span><span>]</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> eip</span><span>:</span><span class="z-constant"> 20</span><span>,</span></span> <span class="giallo-l"><span> token</span><span>:</span><span class="z-variable z-other"> path</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> id</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span> amountIn</span><span>:</span><span class="z-variable z-other"> amountIn</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> code</span><span>:</span><span class="z-variable z-other"> UniswapV2Helper01</span><span>.</span><span class="z-variable z-other">address</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span class="z-entity z-name"> encodeFunctionData</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">swapExactTokensForTokens</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"> amountIn</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> amountOutMin</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> path</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"> deadline</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><h4 id="uniswap-v3-router">Uniswap V3 Router</h4> <p>Legacy router contract:</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"> SwapRouter</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> this function is called by pool to pay the input tokens</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> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> token</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> payer</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 class="giallo-l"><span> )</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span> .</span><span>.</span><span>.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> pull payment</span></span> <span class="giallo-l"><span> TransferHelper</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span><span>token</span><span>,</span><span> payer</span><span>,</span><span> recipient</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></code></pre> <p>The helper contract to use with the <code>UTR</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"> SwapHelper</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> this function is called by pool to pay the input tokens</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> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> token</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> payer</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 class="giallo-l"><span> )</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span> .</span><span>.</span><span>.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> pull payment</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> payment </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span><span>payer</span><span>,</span><span> recipient</span><span>,</span><span class="z-constant"> 20</span><span>,</span><span> token</span><span>,</span><span class="z-constant"> 0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> UTR</span><span>.</span><span class="z-entity z-name">pay</span><span>(</span><span>payment</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></code></pre> <p>This transaction is signed by users to execute the <code>exactInput</code> functionality using <code>PAYMENT</code> mode:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">UniversalTokenRouter</span><span>.</span><span class="z-entity z-name">exec</span><span>(</span><span>[</span><span>{</span></span> <span class="giallo-l"><span> eip</span><span>:</span><span class="z-constant"> 20</span><span>,</span></span> <span class="giallo-l"><span> token</span><span>:</span><span class="z-variable z-other"> tokenOut</span><span>,</span></span> <span class="giallo-l"><span> id</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span> amountOutMin</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span> recipient</span><span>:</span><span class="z-variable z-other"> to</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>]</span><span>,</span><span> [</span><span>{</span></span> <span class="giallo-l"><span> inputs</span><span>:</span><span> [</span><span>{</span></span> <span class="giallo-l"><span> mode</span><span>:</span><span class="z-variable z-other z-constant"> PAYMENT</span><span>,</span></span> <span class="giallo-l"><span> eip</span><span>:</span><span class="z-constant"> 20</span><span>,</span></span> <span class="giallo-l"><span> token</span><span>:</span><span class="z-variable z-other"> tokenIn</span><span>,</span></span> <span class="giallo-l"><span> id</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span> amountIn</span><span>:</span><span class="z-variable z-other"> amountIn</span><span>,</span></span> <span class="giallo-l"><span> recipient</span><span>:</span><span class="z-variable z-other"> pool</span><span>.</span><span class="z-variable z-other">address</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> code</span><span>:</span><span class="z-variable z-other"> SwapHelper</span><span>.</span><span class="z-variable z-other">address</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span class="z-entity z-name"> encodeFunctionData</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">exactInput</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> [</span><span class="z-keyword">...</span><span>]</span><span>)</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>]</span><span>)</span></span></code></pre><h4 id="allowance-adapter">Allowance Adapter</h4> <p>A simple non-reentrancy ERC-20 adapter for aplication and router contracts that use direct allowance.</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"> AllowanceAdapter</span><span class="z-storage"> is</span><span class="z-entity z-name"> ReentrancyGuard</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Input</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"> uint</span><span> amountIn</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"> approveAndCall</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> Input</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> inputs</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> spender</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-support"> address</span><span class="z-variable"> leftOverRecipient</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 class="z-entity z-name"> nonReentrant</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> inputs</span><span>.</span><span>length</span><span>;</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>i</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> Input </span><span class="z-storage z-type">memory</span><span> input </span><span class="z-keyword">=</span><span> inputs</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC20</span><span>(</span><span>input</span><span>.</span><span>token</span><span>)</span><span>.</span><span class="z-entity z-name">approve</span><span>(</span><span>spender</span><span>,</span><span> input</span><span>.</span><span>amountIn</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 class="z-support">bool</span><span> success</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span> spender</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span class="z-variable z-language"> msg</span><span>.</span><span>value</span><span>}</span><span>(</span><span>data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>success</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-keyword"> revert</span><span>(</span><span class="z-entity z-name">add</span><span>(</span><span>result</span><span>,</span><span class="z-constant"> 32</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>result</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-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> inputs</span><span>.</span><span>length</span><span>;</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>i</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> Input </span><span class="z-storage z-type">memory</span><span> input </span><span class="z-keyword">=</span><span> inputs</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> clear all allowance</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC20</span><span>(</span><span>input</span><span>.</span><span>token</span><span>)</span><span>.</span><span class="z-entity z-name">approve</span><span>(</span><span>spender</span><span>,</span><span class="z-constant"> 0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> leftOver </span><span class="z-keyword">=</span><span class="z-entity z-name"> IERC20</span><span>(</span><span>input</span><span>.</span><span>token</span><span>)</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 class="z-keyword"> if</span><span> (</span><span>leftOver </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> TransferHelper</span><span>.</span><span class="z-entity z-name">safeTransfer</span><span>(</span><span>input</span><span>.</span><span>token</span><span>,</span><span> leftOverRecipient</span><span>,</span><span> leftOver</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> <p>This transaction is constructed to utilize the <code>UTR</code> to interact with Uniswap V2 Router without approving any token to it:</p> <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"> data</span><span>:</span><span class="z-variable z-other z-constant"> routerData</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> uniswapRouter</span><span>.</span><span class="z-variable z-other">populateTransaction</span><span>.</span><span class="z-entity z-name">swapExactTokensForTokens</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> amountIn</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> amountOutMin</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> path</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"> deadline</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">const</span><span> {</span><span class="z-variable"> data</span><span>:</span><span class="z-variable z-other z-constant"> adapterData</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> adapter</span><span>.</span><span class="z-variable z-other">populateTransaction</span><span>.</span><span class="z-entity z-name">approveAndCall</span><span>(</span></span> <span class="giallo-l"><span> [</span><span>{</span></span> <span class="giallo-l"><span> token</span><span>:</span><span class="z-variable z-other"> path</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> amountIn</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"> uniswapRouter</span><span>.</span><span class="z-variable z-other">address</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> routerData</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> leftOverRecipient</span><span>,</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">await</span><span class="z-variable z-other"> utr</span><span>.</span><span class="z-entity z-name">exec</span><span>(</span><span>[</span><span>]</span><span>,</span><span> [</span><span>{</span></span> <span class="giallo-l"><span> inputs</span><span>:</span><span> [</span><span>{</span></span> <span class="giallo-l"><span> mode</span><span>:</span><span class="z-variable z-other z-constant"> TRANSFER</span><span>,</span></span> <span class="giallo-l"><span> recipient</span><span>:</span><span class="z-variable z-other"> adapter</span><span>.</span><span class="z-variable z-other">address</span><span>,</span></span> <span class="giallo-l"><span> eip</span><span>:</span><span class="z-constant"> 20</span><span>,</span></span> <span class="giallo-l"><span> token</span><span>:</span><span class="z-variable z-other"> path</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> id</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> amountIn</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> code</span><span>:</span><span class="z-variable z-other"> adapter</span><span>.</span><span class="z-variable z-other">address</span><span>,</span></span> <span class="giallo-l"><span> data</span><span>:</span><span class="z-variable z-other"> adapterData</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>]</span><span>)</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The <code>Permit</code> type signature is not supported since the purpose of the Universal Token Router is to eliminate all interactive <code>approve</code> signatures for new tokens, and <em>most</em> for old tokens.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <h3 id="tokens">Tokens</h3> <p>Old token contracts (ERC-20, ERC-721 and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>) require approval for the Universal Token Router once for each account.</p> <p>New token contracts can pre-configure the Universal Token Router as a trusted spender, and no approval transaction is required for interactive usage.</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/token/ERC20/ERC20.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"> Implementation of the {ERC20} token standard that support a trusted ERC6120 contract as an unlimited spender.</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"> ERC20WithUTR</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-support"> address</span><span class="z-storage z-type"> immutable</span><span> UTR</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 the values for {name}, {symbol} and ERC6120&#39;s {utr} address.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * All three of these values are immutable: they can only be set once during</span></span> <span class="giallo-l"><span class="z-comment"> * construction.</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"> utr</span><span class="z-comment"> can be zero to disable trusted ERC6120 support.</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">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"> address</span><span class="z-variable"> utr</span><span>)</span><span class="z-entity z-name"> ERC20</span><span>(</span><span>name, symbol) </span><span>{</span></span> <span class="giallo-l"><span> UTR </span><span class="z-keyword">=</span><span> utr</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 {IERC20-allowance}.</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"> 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-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">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>spender </span><span class="z-keyword">==</span><span> UTR </span><span class="z-keyword">&amp;&amp;</span><span> spender </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-variable z-language"> type</span><span>(</span><span class="z-support">uint256</span><span>)</span><span>.</span><span>max</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">allowance</span><span>(</span><span>owner</span><span>,</span><span> spender</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"> * Does not check or update the allowance if `spender` is the UTR.</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"> _spendAllowance</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-support"> uint256</span><span class="z-variable"> amount</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"> if</span><span> (</span><span>spender </span><span class="z-keyword">==</span><span> UTR </span><span class="z-keyword">&amp;&amp;</span><span> spender </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>;</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">_spendAllowance</span><span>(</span><span>owner</span><span>,</span><span> spender</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></code></pre><h3 id="applications">Applications</h3> <p>The only application contracts <strong>INCOMPATIBLE</strong> with the UTR are contracts that use <code>msg.sender</code> as the beneficiary address in their internal storage without any function for ownership transfer.</p> <p>All application contracts that accept <code>recipient</code> (or <code>to</code>) argument as the beneficiary address are compatible with the UTR out of the box.</p> <p>Application contracts that transfer tokens (ERC-20, ERC-721, and ERC-1155) to <code>msg.sender</code> need additional adapters to add a <code>recipient</code> to their functions.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> sample adapter contract for WETH</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> WethAdapter</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">address</span><span class="z-variable"> recipient</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"> IWETH</span><span>(</span><span>WETH</span><span>)</span><span>.</span><span class="z-entity z-name">deposit</span><span>(</span><span>)</span><span>{</span><span>value</span><span class="z-keyword">:</span><span class="z-variable z-language"> msg</span><span>.</span><span>value</span><span>}</span><span>;</span></span> <span class="giallo-l"><span> TransferHelper</span><span>.</span><span class="z-entity z-name">safeTransfer</span><span>(</span><span>WETH</span><span>,</span><span> recipient</span><span>,</span><span class="z-variable z-language"> msg</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></code></pre> <p>Additional helper and adapter contracts might be needed, but they're mostly peripheral and non-intrusive. They don't hold any tokens or allowances, so they can be frequently updated and have little to no security impact on the core application contracts.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A reference implementation by Derion Labs and audited by Hacken.</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"> The implementation of the EIP-6120.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @author</span><span class="z-comment"> Derion Labs</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> UniversalTokenRouter</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC165</span><span>, </span><span class="z-entity z-name">IUniversalTokenRouter</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> constant</span><span> PAYMENT </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"> constant</span><span> TRANSFER </span><span class="z-keyword">=</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> constant</span><span> CALL_VALUE </span><span class="z-keyword">=</span><span class="z-constant"> 2</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> EIP_ETH </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-support"> uint256</span><span class="z-storage z-type"> constant</span><span> ERC_721_BALANCE </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-string">&#39;UniversalTokenRouter.ERC_721_BALANCE&#39;</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"> The main entry point of the router</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> outputs</span><span class="z-comment"> token behavior for output verification</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> actions</span><span class="z-comment"> router actions and inputs for execution</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> exec</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> Output</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> outputs</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> Action</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> actions</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 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"> unchecked</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> track the expected balances before any action is executed</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> outputs</span><span>.</span><span>length</span><span>;</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>i</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> Output </span><span class="z-storage z-type">memory</span><span> output </span><span class="z-keyword">=</span><span> outputs</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> balance </span><span class="z-keyword">=</span><span class="z-entity z-name"> _balanceOf</span><span>(</span><span>output</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> expected </span><span class="z-keyword">=</span><span> output</span><span>.</span><span>amountOutMin </span><span class="z-keyword">+</span><span> balance</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>expected </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> balance</span><span>,</span><span class="z-string"> &#39;UTR: OUTPUT_BALANCE_OVERFLOW&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> output</span><span>.</span><span>amountOutMin </span><span class="z-keyword">=</span><span> expected</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> actions</span><span>.</span><span>length</span><span>;</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>i</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> Action </span><span class="z-storage z-type">memory</span><span> action </span><span class="z-keyword">=</span><span> actions</span><span>[</span><span>i</span><span>]</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-keyword"> for</span><span> (</span><span class="z-support">uint256</span><span> j </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> j </span><span class="z-keyword">&lt;</span><span> action</span><span>.</span><span>inputs</span><span>.</span><span>length</span><span>;</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>j</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> Input </span><span class="z-storage z-type">memory</span><span> input </span><span class="z-keyword">=</span><span> action</span><span>.</span><span>inputs</span><span>[</span><span>j</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> mode </span><span class="z-keyword">=</span><span> input</span><span>.</span><span>mode</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>mode </span><span class="z-keyword">==</span><span> CALL_VALUE</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> eip and id are ignored</span></span> <span class="giallo-l"><span> value </span><span class="z-keyword">=</span><span> input</span><span>.</span><span>amountIn</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>mode </span><span class="z-keyword">==</span><span> PAYMENT</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> key </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 class="z-variable z-language"> msg.sender</span><span>,</span><span> input</span><span>.</span><span>recipient</span><span>,</span><span> input</span><span>.</span><span>eip</span><span>,</span><span> input</span><span>.</span><span>token</span><span>,</span><span> input</span><span>.</span><span>id</span></span> <span class="giallo-l"><span> )</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> amountIn </span><span class="z-keyword">=</span><span> input</span><span>.</span><span>amountIn</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"> tstore</span><span>(</span><span>key</span><span>,</span><span> amountIn</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>mode </span><span class="z-keyword">==</span><span> TRANSFER</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _transferToken</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> input</span><span>.</span><span>recipient</span><span>,</span><span> input</span><span>.</span><span>eip</span><span>,</span><span> input</span><span>.</span><span>token</span><span>,</span><span> input</span><span>.</span><span>id</span><span>,</span><span> input</span><span>.</span><span>amountIn</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"> revert</span><span>(</span><span class="z-string">&#39;UTR: INVALID_MODE&#39;</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-keyword"> if</span><span> (</span><span>action</span><span>.</span><span>code </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> action</span><span>.</span><span>data</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span class="z-keyword"> ||</span><span> value </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> <span class="giallo-l"><span> TokenChecker</span><span>.</span><span class="z-entity z-name">isNotToken</span><span>(</span><span>action</span><span>.</span><span>code</span><span>)</span><span class="z-keyword"> ||</span></span> <span class="giallo-l"><span> ERC165Checker</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span>action</span><span>.</span><span>code</span><span>,</span><span class="z-constant"> 0x61206120</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;UTR: NOT_CALLABLE&quot;</span></span> <span class="giallo-l"><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-support"> bytes</span><span class="z-storage z-type"> memory</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span> action</span><span>.</span><span>code</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span> value</span><span>}</span><span>(</span><span>action</span><span>.</span><span>data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>success</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-keyword"> revert</span><span>(</span><span class="z-entity z-name">add</span><span>(</span><span>result</span><span>,</span><span class="z-constant">32</span><span>)</span><span>,</span><span class="z-entity z-name">mload</span><span>(</span><span>result</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-comment"> //</span><span class="z-comment"> clear all transient storages</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</span><span> j </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> j </span><span class="z-keyword">&lt;</span><span> action</span><span>.</span><span>inputs</span><span>.</span><span>length</span><span>;</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>j</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> Input </span><span class="z-storage z-type">memory</span><span> input </span><span class="z-keyword">=</span><span> action</span><span>.</span><span>inputs</span><span>[</span><span>j</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>input</span><span>.</span><span>mode </span><span class="z-keyword">==</span><span> PAYMENT</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> transient storages</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> key </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 class="z-variable z-language"> msg.sender</span><span>,</span><span> input</span><span>.</span><span>recipient</span><span>,</span><span> input</span><span>.</span><span>eip</span><span>,</span><span> input</span><span>.</span><span>token</span><span>,</span><span> input</span><span>.</span><span>id</span></span> <span class="giallo-l"><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"> tstore</span><span>(</span><span>key</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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> refund any left-over ETH</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> leftOver </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>balance</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>leftOver </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> TransferHelper</span><span>.</span><span class="z-entity z-name">safeTransferETH</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> leftOver</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"> verify balance changes</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> outputs</span><span>.</span><span>length</span><span>;</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>i</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> Output </span><span class="z-storage z-type">memory</span><span> output </span><span class="z-keyword">=</span><span> outputs</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> balance </span><span class="z-keyword">=</span><span class="z-entity z-name"> _balanceOf</span><span>(</span><span>output</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-keyword"> NOTE</span><span class="z-comment">: output.amountOutMin is reused as `expected`</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>balance </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> output</span><span>.</span><span>amountOutMin</span><span>,</span><span class="z-string"> &#39;UTR: INSUFFICIENT_OUTPUT_AMOUNT&#39;</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></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Spend the pending payment. Intended to be called from the input.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"> payment</span><span class="z-comment"> encoded payment 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"> amount</span><span class="z-comment"> token amount to pay with payment</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-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> payment</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"> virtual</span><span class="z-storage z-type"> override</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> discard</span><span>(</span><span>payment</span><span>,</span><span> amount</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"> address</span><span> recipient</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> eip</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> id</span></span> <span class="giallo-l"><span> )</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>payment</span><span>,</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"> address</span><span>,</span><span class="z-support"> uint256</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _transferToken</span><span>(</span><span>sender</span><span>,</span><span> recipient</span><span>,</span><span> eip</span><span>,</span><span> token</span><span>,</span><span> id</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 class="z-comment"> Discard a part of a pending payment. Can be called from the input.action</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> to verify the payment without transferring any 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"> payment</span><span class="z-comment"> encoded payment 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"> amount</span><span class="z-comment"> token amount to pay with payment</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> discard</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> payment</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-storage z-type"> override</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> key </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span>payment</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> remain</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> remain </span><span class="z-keyword">:=</span><span class="z-entity z-name"> tload</span><span>(</span><span>key</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>remain </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> amount</span><span>,</span><span class="z-string"> &#39;UTR: INSUFFICIENT_PAYMENT&#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"> tstore</span><span>(</span><span>key</span><span>,</span><span class="z-entity z-name"> sub</span><span>(</span><span>remain</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> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> IERC165-supportsInterface</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"> 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> <span class="giallo-l"><span> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IUniversalTokenRouter</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"> _transferToken</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</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"> eip</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> token</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"> internal</span><span class="z-storage z-type"> virtual</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>eip </span><span class="z-keyword">==</span><span class="z-constant"> 20</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> TransferHelper</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span><span>token</span><span>,</span><span> sender</span><span>,</span><span> recipient</span><span>,</span><span> amount</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>eip </span><span class="z-keyword">==</span><span class="z-constant"> 1155</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC1155</span><span>(</span><span>token</span><span>)</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span><span>sender</span><span>,</span><span> recipient</span><span>,</span><span> id</span><span>,</span><span> amount</span><span>,</span><span class="z-string"> &quot;&quot;</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>eip </span><span class="z-keyword">==</span><span class="z-constant"> 721</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC721</span><span>(</span><span>token</span><span>)</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span><span>sender</span><span>,</span><span> recipient</span><span>,</span><span> id</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"> revert</span><span>(</span><span class="z-string">&quot;UTR: INVALID_EIP&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"> _balanceOf</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> Output</span><span class="z-storage z-type"> memory</span><span class="z-variable"> output</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> internal</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 class="z-variable"> balance</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> eip </span><span class="z-keyword">=</span><span> output</span><span>.</span><span>eip</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>eip </span><span class="z-keyword">==</span><span class="z-constant"> 20</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> IERC20</span><span>(</span><span>output</span><span>.</span><span>token</span><span>)</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>(</span><span>output</span><span>.</span><span>recipient</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>eip </span><span class="z-keyword">==</span><span class="z-constant"> 1155</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> IERC1155</span><span>(</span><span>output</span><span>.</span><span>token</span><span>)</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>(</span><span>output</span><span>.</span><span>recipient</span><span>,</span><span> output</span><span>.</span><span>id</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>eip </span><span class="z-keyword">==</span><span class="z-constant"> 721</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>output</span><span>.</span><span>id </span><span class="z-keyword">==</span><span> ERC_721_BALANCE</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> IERC721</span><span>(</span><span>output</span><span>.</span><span>token</span><span>)</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>(</span><span>output</span><span>.</span><span>recipient</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> try</span><span class="z-entity z-name"> IERC721</span><span>(</span><span>output</span><span>.</span><span>token</span><span>)</span><span>.</span><span class="z-entity z-name">ownerOf</span><span>(</span><span>output</span><span>.</span><span>id</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> currentOwner</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> currentOwner </span><span class="z-keyword">==</span><span> output</span><span>.</span><span>recipient </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 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 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 class="z-keyword"> if</span><span> (</span><span>eip </span><span class="z-keyword">==</span><span> EIP_ETH</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> output</span><span>.</span><span>recipient</span><span>.</span><span>balance</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span class="z-string">&quot;UTR: INVALID_EIP&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> <h3 id="erc-165-tokens">ERC-165 Tokens</h3> <p>Token contracts must <strong>NEVER</strong> support the ERC-165 interface with the ID <code>0x61206120</code>, as it is reserved for non-token contracts to be called with the UTR. Any token with the interface ID <code>0x61206120</code> approved to the UTR can be spent by anyone, without any restrictions.</p> <h3 id="reentrancy">Reentrancy</h3> <p>Tokens transferred to the UTR contract will be permanently lost, as there is no way to transfer them out. Applications that require an intermediate address to hold tokens should use their own Helper contract with a reentrancy guard for secure execution.</p> <p>ETH must be transferred to the UTR contracts before the value is spent in an action call (using <code>CALL_VALUE</code>). This ETH value can be siphoned out of the UTR using a re-entrant call inside an action code or rogue token functions. This exploit will not be possible if users don't transfer more ETH than they will spend in that transaction.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> transfer 100 in, but spend only 60,</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> so at most 40 wei can be exploited in this transaction</span></span> <span class="giallo-l"><span>UniversalTokenRouter</span><span>.</span><span class="z-entity z-name">exec</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></span> <span class="giallo-l"><span> inputs</span><span class="z-keyword">:</span><span> [</span><span>{</span></span> <span class="giallo-l"><span> mode</span><span class="z-keyword">:</span><span> CALL_VALUE</span><span>,</span></span> <span class="giallo-l"><span> eip</span><span class="z-keyword">:</span><span class="z-constant"> 20</span><span>,</span></span> <span class="giallo-l"><span> token</span><span class="z-keyword">:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span> id</span><span class="z-keyword">:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span> amountIn</span><span class="z-keyword">:</span><span class="z-constant"> 60</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> spend 60</span></span> <span class="giallo-l"><span> recipient</span><span class="z-keyword">:</span><span> AddressZero</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> {</span></span> <span class="giallo-l"><span> value</span><span class="z-keyword">:</span><span class="z-constant"> 100</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> transfer 100 in</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre><h3 id="discard-payment-1">Discard Payment</h3> <p>The result of the <code>pay</code> function can be checked by querying the balance after the call, allowing the UTR contract to be called in a trustless manner. However, due to the inability to verify the execution of the <code>discard</code> function, it should only be used with a trusted UTR 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-09T00:00:00+00:00 2026-02-11T14:49:27+00:00 Mikhail Kalininhttps://github.com/mkalinin Danny Ryanhttps://github.com/djrtwo Peter Davieshttps://github.com/petertdavies https://wg-eips.ritovision.com/6110/

Provides validator deposits as a list of deposit operations added to the Execution Layer block

<h2 id="abstract">Abstract</h2> <p>Appends validator deposits to the Execution Layer block structure. This shifts responsibility of deposit inclusion and validation to the Execution Layer and removes the need for deposit (or <code>eth1data</code>) voting from the Consensus Layer.</p> <p>Validator deposits list supplied in a block is obtained by parsing deposit contract log events emitted by each deposit transaction included in a given block.</p> <h2 id="motivation">Motivation</h2> <p>Validator deposits are a core component of the proof-of-stake consensus mechanism. This EIP allows for an in-protocol mechanism of deposit processing on the Consensus Layer and eliminates the proposer voting mechanism utilized currently. This proposed mechanism relaxes safety assumptions and reduces complexity of client software design, contributing to the security of the deposits flow. It also improves validator UX.</p> <p>Advantages of in-protocol deposit processing consist of, but are not limited to, the following:</p> <ul> <li>Significant increase of deposits security by supplanting proposer voting. With the proposed in-protocol mechanism, an honest online node can't be convinced to process fake deposits even when more than 2/3 portion of stake is adversarial.</li> <li>Decrease of delay between submitting deposit transaction on Execution Layer and its processing on Consensus Layer. That is, ~13 minutes with in-protocol deposit processing compared to ~12 hours with the existing mechanism.</li> <li>Eliminate beacon block proposal dependency on JSON-RPC API data polling that suffers from failures caused by inconsistencies between JSON-RPC API implementations and dependency of API calls processing on the inner state (e.g. syncing) of client software.</li> <li>Eliminate requirement to maintain and distribute deposit contract snapshots (<a href="https://wg-eips.ritovision.com/4881/">EIP-4881</a>).</li> <li>Reduction of design and engineering complexity of Consensus Layer client software on a component that has proven to be brittle.</li> </ul> <h2 id="specification">Specification</h2> <h3 id="execution-layer">Execution Layer</h3> <h4 id="constants">Constants</h4> <table><thead><tr><th>Name</th><th>Value</th><th>Comment</th></tr></thead><tbody> <tr><td><code>DEPOSIT_REQUEST_TYPE</code></td><td><code>b'0'</code></td><td>The <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> request type byte for deposit operation</td></tr> </tbody></table> <h4 id="configuration">Configuration</h4> <table><thead><tr><th>Name</th><th>Value</th><th>Comment</th></tr></thead><tbody> <tr><td><code>DEPOSIT_CONTRACT_ADDRESS</code></td><td><code>0x00000000219ab540356cbb839cbe05303d7705fa</code></td><td>Mainnet</td></tr> <tr><td><code>DEPOSIT_EVENT_SIGNATURE_HASH</code></td><td><code>0x649bbc62d0e31342afea4e5cd82d4049e7e1ee912fc0889aa790803be39038c5</code></td><td></td></tr> </tbody></table> <p><code>DEPOSIT_CONTRACT_ADDRESS</code>, <code>DEPOSIT_EVENT_SIGNATURE_HASH</code> parameters <strong>MUST</strong> be included into client software binary distribution.</p> <h4 id="definitions">Definitions</h4> <ul> <li><strong><code>FORK_BLOCK</code></strong> -- the first block in a blockchain after this EIP has been activated.</li> </ul> <h4 id="deposit-request">Deposit request</h4> <p>The structure denoting the new deposit request consists of the following fields:</p> <ol> <li><code>pubkey: Bytes48</code></li> <li><code>withdrawal_credentials: Bytes32</code></li> <li><code>amount: uint64</code></li> <li><code>signature: Bytes96</code></li> <li><code>index: uint64</code></li> </ol> <p>Deposits are a type of <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> request, with the following encoding:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>request_type</span><span class="z-keyword"> =</span><span class="z-constant"> DEPOSIT_REQUEST_TYPE</span></span> <span class="giallo-l"><span>request_data</span><span class="z-keyword"> =</span><span> get_deposit_request_data</span><span>(</span><span>block</span><span>.</span><span>receipts</span><span>)</span></span></code></pre><h4 id="block-validity">Block validity</h4> <p>Beginning with the <code>FORK_BLOCK</code>, each deposit accumulated in the block <strong>MUST</strong> appear in the EIP-7685 requests list in the order they appear in the logs. To illustrate:</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"> parse_deposit_data</span><span>(</span><span class="z-variable z-parameter z-function">deposit_event_data</span><span>)</span><span> -&gt;</span><span> bytes</span><span>[</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"> Parses deposit data from DepositContract.DepositEvent data</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-keyword"> pass</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_deposit_event_data</span><span>(</span><span class="z-variable z-parameter z-function">deposit_event_data</span><span>:</span><span class="z-support"> bytes</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-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string"> Verifies the layout of the DepositEvent. Returns `False` if the layout is unsupported,</span></span> <span class="giallo-l"><span class="z-string"> `True` if the layout is of the expected format.</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-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>deposit_event_data</span><span>)</span><span class="z-keyword"> !=</span><span class="z-constant"> 576</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> pubkey_offset</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>deposit_event_data</span><span>[</span><span class="z-constant">0</span><span>:</span><span class="z-constant">32</span><span>]</span><span>,</span><span class="z-variable"> byteorder</span><span class="z-keyword">=</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 class="z-variable"> signed</span><span class="z-keyword">=</span><span class="z-constant">False</span><span>)</span></span> <span class="giallo-l"><span> withdrawal_credentials_offset</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>deposit_event_data</span><span>[</span><span class="z-constant">32</span><span>:</span><span class="z-constant">64</span><span>]</span><span>,</span><span class="z-variable"> byteorder</span><span class="z-keyword">=</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 class="z-variable"> signed</span><span class="z-keyword">=</span><span class="z-constant">False</span><span>)</span></span> <span class="giallo-l"><span> amount_offset</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>deposit_event_data</span><span>[</span><span class="z-constant">64</span><span>:</span><span class="z-constant">96</span><span>]</span><span>,</span><span class="z-variable"> byteorder</span><span class="z-keyword">=</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 class="z-variable"> signed</span><span class="z-keyword">=</span><span class="z-constant">False</span><span>)</span></span> <span class="giallo-l"><span> signature_offset</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>deposit_event_data</span><span>[</span><span class="z-constant">96</span><span>:</span><span class="z-constant">128</span><span>]</span><span>,</span><span class="z-variable"> byteorder</span><span class="z-keyword">=</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 class="z-variable"> signed</span><span class="z-keyword">=</span><span class="z-constant">False</span><span>)</span></span> <span class="giallo-l"><span> index_offset</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>deposit_event_data</span><span>[</span><span class="z-constant">128</span><span>:</span><span class="z-constant">160</span><span>]</span><span>,</span><span class="z-variable"> byteorder</span><span class="z-keyword">=</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 class="z-variable"> signed</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-keyword"> if</span><span> (</span></span> <span class="giallo-l"><span> pubkey_offset</span><span class="z-keyword"> !=</span><span class="z-constant"> 160</span></span> <span class="giallo-l"><span class="z-keyword"> or</span><span> withdrawal_credentials_offset</span><span class="z-keyword"> !=</span><span class="z-constant"> 256</span></span> <span class="giallo-l"><span class="z-keyword"> or</span><span> amount_offset</span><span class="z-keyword"> !=</span><span class="z-constant"> 320</span></span> <span class="giallo-l"><span class="z-keyword"> or</span><span> signature_offset</span><span class="z-keyword"> !=</span><span class="z-constant"> 384</span></span> <span class="giallo-l"><span class="z-keyword"> or</span><span> index_offset</span><span class="z-keyword"> !=</span><span class="z-constant"> 512</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"> These sizes are the sizes of the relevant data</span></span> <span class="giallo-l"><span> pubkey_size</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>deposit_event_data</span><span>[</span><span>pubkey_offset</span><span>:</span><span>pubkey_offset</span><span class="z-keyword">+</span><span class="z-constant">32</span><span>]</span><span>,</span><span class="z-variable"> byteorder</span><span class="z-keyword">=</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 class="z-variable"> signed</span><span class="z-keyword">=</span><span class="z-constant">False</span><span>)</span></span> <span class="giallo-l"><span> withdrawal_credentials_size</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>deposit_event_data</span><span>[</span><span>withdrawal_credentials_offset</span><span>:</span><span>withdrawal_credentials_offset</span><span class="z-keyword">+</span><span class="z-constant">32</span><span>]</span><span>,</span><span class="z-variable"> byteorder</span><span class="z-keyword">=</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 class="z-variable"> signed</span><span class="z-keyword">=</span><span class="z-constant">False</span><span>)</span></span> <span class="giallo-l"><span> amount_size</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>deposit_event_data</span><span>[</span><span>amount_offset</span><span>:</span><span>amount_offset</span><span class="z-keyword">+</span><span class="z-constant">32</span><span>]</span><span>,</span><span class="z-variable"> byteorder</span><span class="z-keyword">=</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 class="z-variable"> signed</span><span class="z-keyword">=</span><span class="z-constant">False</span><span>)</span></span> <span class="giallo-l"><span> signature_size</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>deposit_event_data</span><span>[</span><span>signature_offset</span><span>:</span><span>signature_offset</span><span class="z-keyword">+</span><span class="z-constant">32</span><span>]</span><span>,</span><span class="z-variable"> byteorder</span><span class="z-keyword">=</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 class="z-variable"> signed</span><span class="z-keyword">=</span><span class="z-constant">False</span><span>)</span></span> <span class="giallo-l"><span> index_size</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>deposit_event_data</span><span>[</span><span>index_offset</span><span>:</span><span>index_offset</span><span class="z-keyword">+</span><span class="z-constant">32</span><span>]</span><span>,</span><span class="z-variable"> byteorder</span><span class="z-keyword">=</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 class="z-variable"> signed</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-keyword"> return</span><span> (</span></span> <span class="giallo-l"><span> pubkey_size</span><span class="z-keyword"> ==</span><span class="z-constant"> 48</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> withdrawal_credentials_size</span><span class="z-keyword"> ==</span><span class="z-constant"> 32</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> amount_size</span><span class="z-keyword"> ==</span><span class="z-constant"> 8</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> signature_size</span><span class="z-keyword"> ==</span><span class="z-constant"> 96</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> index_size</span><span class="z-keyword"> ==</span><span class="z-constant"> 8</span></span> <span class="giallo-l"><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"> event_data_to_deposit_request</span><span>(</span><span class="z-variable z-parameter z-function">deposit_event_data</span><span>)</span><span> -&gt;</span><span class="z-support"> bytes</span><span>:</span></span> <span class="giallo-l"><span> deposit_data</span><span class="z-keyword"> =</span><span> parse_deposit_data</span><span>(</span><span>deposit_event_data</span><span>)</span></span> <span class="giallo-l"><span> pubkey</span><span class="z-keyword"> =</span><span> Bytes48</span><span>(</span><span>deposit_data</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> withdrawal_credentials</span><span class="z-keyword"> =</span><span> Bytes32</span><span>(</span><span>deposit_data</span><span>[</span><span class="z-constant">1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> amount</span><span class="z-keyword"> =</span><span> deposit_data</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 8 bytes uint64 LE</span></span> <span class="giallo-l"><span> signature</span><span class="z-keyword"> =</span><span> Bytes96</span><span>(</span><span>deposit_data</span><span>[</span><span class="z-constant">3</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> index</span><span class="z-keyword"> =</span><span> deposit_data</span><span>[</span><span class="z-constant">4</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> 8 bytes uint64 LE</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> pubkey</span><span class="z-keyword"> +</span><span> withdrawal_credentials</span><span class="z-keyword"> +</span><span> amount</span><span class="z-keyword"> +</span><span> signature</span><span class="z-keyword"> +</span><span> index</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_deposit_request_data</span><span>(</span><span class="z-variable z-parameter z-function">receipts</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Retrieve all deposits made in the block</span></span> <span class="giallo-l"><span> deposit_requests</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> receipt</span><span class="z-keyword"> in</span><span> receipts</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> log</span><span class="z-keyword"> in</span><span> receipt</span><span>.</span><span>logs</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> log</span><span>.</span><span>address</span><span class="z-keyword"> ==</span><span class="z-constant"> DEPOSIT_CONTRACT_ADDRESS</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>log</span><span>.</span><span>topics</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span class="z-keyword"> and</span><span> log</span><span>.</span><span>topics</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> DEPOSIT_EVENT_SIGNATURE_HASH</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> is_valid_deposit_event_data</span><span>(</span><span>log</span><span>.</span><span>data</span><span>)</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">invalid deposit log: unsupported data layout</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span> deposit_request</span><span class="z-keyword"> =</span><span> event_data_to_deposit_request</span><span>(</span><span>log</span><span>.</span><span>data</span><span>)</span></span> <span class="giallo-l"><span> deposit_requests</span><span>.</span><span>append</span><span>(</span><span>deposit_request</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"> Concatenate list of deposit request data</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">&#39;</span><span class="z-punctuation z-definition z-string">&#39;</span><span>.</span><span>join</span><span>(</span><span>deposit_requests</span><span>)</span></span></code></pre><h3 id="consensus-layer">Consensus layer</h3> <p>Consensus layer changes can be summarized into the following list:</p> <ol> <li><code>ExecutionRequests</code> is extended with a new <code>deposit_requests</code> field to accommodate deposit requests list.</li> <li><code>BeaconState</code> is appended with <code>deposit_requests_start_index</code> used to switch from the former deposit mechanism to the new one.</li> <li>As a part of transition logic a new beacon block validity condition is added to constrain the usage of <code>Eth1Data</code> poll.</li> <li>A new <code>process_deposit_request</code> function is added to the block processing routine to handle <code>deposit_requests</code> processing.</li> <li>Validator guide provides a logic switching off <code>Eth1Data</code> poll once transition is completed.</li> </ol> <p>Detailed consensus layer specification can be found in following documents:</p> <ul> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/eba62dbf00132dfdc97fbfab663a99cb23b9e8f1/specs/electra/beacon-chain.md"><code>electra/beacon-chain.md</code></a> -- state transition.</li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/eba62dbf00132dfdc97fbfab663a99cb23b9e8f1/specs/electra/validator.md"><code>electra/validator.md</code></a> -- validator guide.</li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/eba62dbf00132dfdc97fbfab663a99cb23b9e8f1/specs/electra/fork.md"><code>electra/fork.md</code></a> -- EIP activation.</li> </ul> <h4 id="validator-index-invariant">Validator index invariant</h4> <p>Due to the large follow distance of <code>Eth1Data</code> poll an index of a new validator assigned during deposit processing remains the same across different branches of a block tree, i.e. with existing mechanism <code>(pubkey, index)</code> cache utilized by consensus layer clients is re-org resilient. The new deposit machinery breaks this invariant and consensus layer clients will have to deal with a fact that a validator index becomes fork dependent, i.e. a validator with the same <code>pubkey</code> can have different indexes in different block tree branches.</p> <p>Detailed <a href="https://wg-eips.ritovision.com/6110/assets/pubkey_to_index_cache_analysis/">analysis</a> shows that <code>process_deposit</code> function is <em>the only</em> place requiring a fork dependent <code>(pubkey, index)</code> cache.</p> <h4 id="eth1data-poll-deprecation"><code>Eth1Data</code> poll deprecation</h4> <p>Consensus layer clients will be able to remove <code>Eth1Data</code> poll mechanism in an uncoordinated fashion once transition period is finished. The transition period is considered as finished when a network reaches the point where <code>state.eth1_deposit_index == state.deposit_requests_start_index</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="index-field"><code>index</code> field</h3> <p>Deposit <code>index</code> is used to deterministically initialize <code>deposit_requests_start_index</code> in the <code>BeaconState</code>, this prevents same deposit from being applied twice during <code>Eth1Data</code> poll deprecation.</p> <h3 id="not-limiting-the-size-of-deposit-operations-list">Not limiting the size of deposit operations list</h3> <p>The list is unbounded because of negligible data complexity and absence of potential DoS vectors. See <a href="https://wg-eips.ritovision.com/6110/#security-considerations">Security Considerations</a> for more details.</p> <h3 id="filtering-events-by-deposit-contract-address-and-deposit-event-signature-hash">Filtering events by <code>DEPOSIT_CONTRACT_ADDRESS</code> and <code>DEPOSIT_EVENT_SIGNATURE_HASH</code></h3> <p>Depending on the design, Deposit smart contract can emit different type of events when deposit is being processed. For instance, Deposit smart contract on Sepolia emits <code>Transfer</code> in addition to <code>DepositEvent</code>. Thus it is important to filter out irrelevant events.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces backwards incompatible changes to the block structure and block validation rule set. But neither of these changes break anything related to user activity and experience.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="data-complexity">Data complexity</h3> <p>At the time of the latest update of this document, the total number of submitted deposits is 1,899,120 which is 348MB of deposit data. Assuming frequency of deposit transactions remains the same, historic chain data complexity induced by this EIP can be estimated as 84MB per year which is negligible in comparison to other historical data.</p> <p>After the beacon chain launch in December 2020, the biggest observed spike in a number of submitted deposits was on June 1, 2023. More than 12,000 deposit transactions were submitted during 24 hours which on average is less than 2 deposit, or 384 bytes of data, per block.</p> <p>Considering the above, we conclude that data complexity introduced by this proposal is negligible.</p> <h3 id="dos-vectors">DoS vectors</h3> <p>The code in the deposit contract costs 15,650 gas to run in the cheapest case (when all storage slots are hot and only a single leaf has to be modified). Some deposits in a batch deposit are more expensive, but those costs, when amortized over a large number of deposits, are small at around ~1,000 gas per deposit. Under current gas pricing rules an extra 6,900 gas is charged to make a <code>CALL</code> that transfers ETH, this is a case of inefficient gas pricing and may be reduced in the future. For future robustness the beacon chain needs to be able to withstand 1,916 deposits in a 30M gas block (15,650 gas per deposit). The limit under current rules is less than 1,271 deposits in a 30M gas block.</p> <h4 id="execution-layer-1">Execution layer</h4> <p>With 1 ETH as a minimum deposit amount, the lowest cost of a byte of deposit data is 1 ETH/192 ~ 5,208,333 Gwei. This is several orders of magnitude higher than the cost of a byte of transaction's calldata, thus adding deposit operations to a block does not increase DoS attack surface of the execution layer.</p> <h4 id="consensus-layer-1">Consensus layer</h4> <p>The most consuming computation of deposit processing is signature verification. Its complexity is bounded by a maximum number of deposits per block which is around 1,271 with 30M gas block at the moment. So, it is ~1,271 signature verifications which is roughly ~1.2 seconds of processing (without optimisations like batched signatures verification). An attacker would need to spend 1,000 ETH to slow down block processing by a second which isn't sustainable and viable attack long term.</p> <p>An optimistically syncing node may be susceptible to a more severe attack scenario. Such a node can't validate a list of deposits provided in a payload which makes it possible for attacker to include as many deposits as the limitation allows to. Currently, it is 8,192 deposits (1.5MB of data) with rough processing time of 8s. Considering an attacker would need to sign off on this block with its crypto economically viable signature (which requires building an alternative chain and feeding it to a syncing node), this attack vector is not considered as viable as it can't result in a significant slow down of a sync process.</p> <h3 id="optimistic-sync">Optimistic sync</h3> <p>An optimistically syncing node has to rely on the honest majority assumption. That is, if adversary is powerful enough to finalize a deposit sequence, a syncing node will have to apply these deposits disregarding the validity of deposit requests with respect to the execution of a given block. Thus, an adversary that can finalize an invalid chain can also convince an honest node to accept fake deposits. The same is applicable to the validity of execution layer world state today and a new deposit processing design is within boundaries of the existing security model in that regard.</p> <p>Online nodes can't be tricked into this situation because their execution layer validates supplied deposits with respect to the block execution.</p> <h3 id="weak-subjectivity-period">Weak subjectivity period</h3> <p>This EIP removes a hard limit on a number of deposits per epoch and makes a block gas limit the only limitation on this number. That is, the limit on deposits per epoch shifts from <code>MAX_DEPOSITS * SLOTS_PER_EPOCH = 512</code> to <code>max_deposits_per_30m_gas_block * SLOTS_PER_EPOCH ~ 32,768</code> at 30M gas block (we consider <code>max_deposits_per_30m_gas_block = 1,024</code> for simplicity).</p> <p>This change affects a number of top ups per epoch which is one of the inputs to the weak subjectivity period computation. One can top up own validators to instantly increase a portion of stake it owns with respect to those validators that are leaking. <a href="https://wg-eips.ritovision.com/6110/assets/ws_period_analysis/">The analysis</a> does not demonstrate significant reduction of a weak subjectivity period sizes. Moreover, such an attack is not considered as viable because it requires a decent portion of stake to be burned as one of preliminaries.</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-07T00:00:00+00:00 2026-02-11T14:48:25+00:00 5660-ethhttps://github.com/5660-eth Wizard Wang https://wg-eips.ritovision.com/6147/

A new management role with an expiration date of NFT/SBT is defined, achieving the separation of transfer right and holding right.

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. It separates the holding right and transfer right of non-fungible tokens (NFTs) and Soulbound Tokens (SBTs) and defines a new role, <code>guard</code> with <code>expires</code>. The flexibility of the <code>guard</code> setting enables the design of NFT anti-theft, NFT lending, NFT leasing, SBT, etc.</p> <h2 id="motivation">Motivation</h2> <p>NFTs are assets that possess both use and financial value.</p> <p>Many cases of NFT theft currently exist, and current NFT anti-theft schemes, such as transferring NFTs to cold wallets, make NFTs inconvenient to be used.</p> <p>In current NFT lending, the NFT owner needs to transfer the NFT to the NFT lending contract, and the NFT owner no longer has the right to use the NFT while he has obtained the loan. In the real world, for example, if a person takes out a mortgage on his own house, he still has the right to use that house.</p> <p>For SBT, the current mainstream view is that an SBT is not transferable, which makes an SBT bound to an Ether address. However, when the private key of the user address is leaked or lost, retrieving SBT will become a complicated task and there is no corresponding standard. The SBTs essentially realizes the separation of NFT holding right and transfer right. When the wallet where SBT is located is stolen or unavailable, SBT should be able to be recoverable.</p> <p>In addition, SBTs still need to be managed in use. For example, if a university issues diploma-based SBTs to its graduates, and if the university later finds that a graduate has committed academic misconduct or jeopardized the reputation of the university, it should have the ability to retrieve the diploma-based SBTs.</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>ERC-721 compliant contracts MAY implement this EIP.</p> <p>A guard Must be valid only before expires.</p> <p>When a token has no guard or the guard is expired, <code>guardInfo</code> MUST return <code>(address(0), 0)</code>.</p> <p>When a token has no guard or the guard is expired, owner, authorised operators and approved address of the token MUST have permission to set guard and expires.</p> <p>When a token has a valid guard, owner, authorised operators and approved address of the token MUST NOT be able to change guard and expires, and they MUST NOT be able to transfer the token.</p> <p>When a token has a valid guard, <code>guardInfo</code> MUST return the address and expires of the guard.</p> <p>When a token has a valid guard, the guard MUST be able to remove guard and expires, change guard and expires, and transfer the token.</p> <p>When a token has a valid guard, if the token burns, the guard MUST be deleted.</p> <p>If issuing or minting SBTs, the guard MAY be uniformly set to the designated address to facilitate management.</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"> IERC6147</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 guard of an NFT is </span><span class="z-keyword">changed</span><span class="z-comment"> or expires 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 `guard` is </span><span class="z-keyword">changed</span><span class="z-comment"> or the `expires` 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 `newGuard` indicates that there currently is no guard address</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UpdateGuardLog</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"> newGuard</span><span>, </span><span class="z-support">address</span><span class="z-variable"> oldGuard</span><span>, </span><span class="z-support">uint64</span><span class="z-variable"> expires</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"> Owner, authorised operators and approved address of the NFT can set guard and expires of the NFT and</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> valid guard can modifiy guard and expires of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If the NFT has a valid guard role, the owner, authorised operators and approved address of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> cannot modify guard and expires</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The `newGuard` can not be zero address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The `expires` need to be valid</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"> tokenId</span><span class="z-comment"> The NFT to get the guard 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"> newGuard</span><span class="z-comment"> The new guard address 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 guard could manage the token before expires</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> changeGuard</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"> newGuard</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> expires</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 the guard and expires of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Only guard can remove its own guard role and expires</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The guard address is set to 0 address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The expires is set to 0</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"> tokenId</span><span class="z-comment"> The NFT to remove the guard and expires for</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeGuard</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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer the NFT and remove its guard and expires</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The NFT is transferred to `to` and the guard address is set to 0 address</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"> from</span><span class="z-comment"> The address of the previous owner 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"> to</span><span class="z-comment"> The address of NFT 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"> tokenId</span><span class="z-comment"> The NFT to get transferred for</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferAndRemove</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"> 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 class="z-storage z-type"> @notice</span><span class="z-comment"> Get the guard address and expires of the 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 guard</span></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 guard address and 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"> guard address and expires for the NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> guardInfo</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 class="z-support"> uint64</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>changeGuard(uint256 tokenId, address newGuard, uint64 expires)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>removeGuard(uint256 tokenId)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>transferAndRemove(address from,address to,uint256 tokenId)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>guardInfo(uint256 tokenId)</code> function MAY be implemented as <code>pure</code> or <code>view</code>.</p> <p>The <code>UpdateGuardLog</code> event MUST be emitted when a guard is changed.</p> <p>The <code>supportsInterface</code> method MUST return <code>true</code> when called with <code>0xb61d1057</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="universality">Universality</h3> <p>There are many application scenarios for NFT/SBT, and there is no need to propose a dedicated EIP for each one, which would make the overall number of EIPS inevitably increase and add to the burden of developers. The standard is based on the analysis of the right attached to assets in the real world, and abstracts the right attached to NFT/SBT into holding right and transfer right making the standard more universal.</p> <p>For example, the standard has more than the following use cases:</p> <p>SBTs. The SBTs issuer can assign a uniform role of <code>guard</code> to the SBTs before they are minted, so that the SBTs cannot be transferred by the corresponding holders and can be managed by the SBTs issuer through the <code>guard</code>.</p> <p>NFT anti-theft. If an NFT holder sets a <code>guard</code> address of an NFT as his or her own cold wallet address, the NFT can still be used by the NFT holder, but the risk of theft is greatly reduced.</p> <p>NFT lending. The borrower sets the <code>guard</code> of his or her own NFT as the lender's address, the borrower still has the right to use the NFT while obtaining the loan, but at the same time cannot transfer or sell the NFT. If the borrower defaults on the loan, the lender can transfer and sell the NFT.</p> <p>Additionally, by setting an <code>expires</code> for the <code>guard</code>, the scalability of the protocol is further enhanced, as demonstrated in the following examples:</p> <p>More flexible NFT issuance. During NFT minting, discounts can be offered for NFTs that are locked for a certain period of time, without affecting the NFTs' usability.</p> <p>More secure NFT management. Even if the <code>guard</code> address becomes inaccessible due to lost private keys, the <code>owner</code> can still retrieve the NFT after the <code>guard</code> has expired.</p> <p>Valid SBTs. Some SBTs have a period of use. More effective management can be achieved through <code>guard</code> and <code>expires</code>.</p> <h3 id="extensibility">Extensibility</h3> <p>This standard only defines a <code>guard</code> and its <code>expires</code>. For complex functions needed by NFTs and SBTs, such as social recovery and multi-signature, the <code>guard</code> can be set as a third-party protocol address. Through the third-party protocol, more flexible and diverse functions can be achieved based on specific application scenarios.</p> <h3 id="naming">Naming</h3> <p>The alternative names are <code>guardian</code> and <code>guard</code>, both of which basically match the permissions corresponding to the role: protection of NFT or necessary management according to its application scenarios. The <code>guard</code> has fewer characters than the <code>guardian</code> and is more concise.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard can be fully ERC-721 compatible by adding an extension function set.</p> <p>If an NFT issued based on the above standard does not set a <code>guard</code>, then it is no different in the existing functions from the current NFT issued based on the ERC-721 standard.</p> <h2 id="reference-implementation">Reference Implementation</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-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.8</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;./IERC6147.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"> ERC6147</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">IERC6147</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"> A structure representing a token of guard address and 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"> guard</span><span class="z-comment"> address of guard role</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> expirs</span><span class="z-comment"> UNIX timestamp, the guard could manage the token before expires</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> GuardInfo</span><span>{</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> guard</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> expires</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"> mapping</span><span>(</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span> GuardInfo</span><span>)</span><span class="z-storage z-type"> internal</span><span> _guardInfo</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, authorised operators and approved address of the NFT can set guard and expires of the NFT and</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> valid guard can modifiy guard and expires of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If the NFT has a valid guard role, the owner, authorised operators and approved address of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> cannot modify guard and expires</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The `newGuard` can not be zero address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The `expires` need to be valid</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"> tokenId</span><span class="z-comment"> The NFT to get the guard 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"> newGuard</span><span class="z-comment"> The new guard address 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 guard could manage the token before expires</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> changeGuard</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"> newGuard</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> expires</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>expires </span><span class="z-keyword">&gt;</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</span><span>,</span><span class="z-string"> &quot;ERC6147: invalid expires&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _updateGuard</span><span>(</span><span>tokenId</span><span>,</span><span> newGuard</span><span>,</span><span> expires</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Remove the guard and expires of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Only guard can remove its own guard role and expires</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The guard address is set to 0 address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The expires is set to 0</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"> tokenId</span><span class="z-comment"> The NFT to remove the guard and expires for</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeGuard</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> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _updateGuard</span><span>(</span><span>tokenId</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-constant"> 0</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer the NFT and remove its guard and expires</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The NFT is transferred to `to` and the guard address is set to 0 address</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"> from</span><span class="z-comment"> The address of the previous owner 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"> to</span><span class="z-comment"> The address of NFT 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"> tokenId</span><span class="z-comment"> The NFT to get transferred for</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferAndRemove</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"> tokenId</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-entity z-name"> safeTransferFrom</span><span>(</span><span>from</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"> removeGuard</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Get the guard address and expires of the 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 guard</span></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 guard address and 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"> guard address and expires for the NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> guardInfo</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-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>,</span><span class="z-support"> uint64</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>_guardInfo</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>expires </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>{</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>_guardInfo</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>guard</span><span>,</span><span> _guardInfo</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>expires</span><span>)</span><span>;</span></span> <span class="giallo-l"><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-support">address</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> }</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"> @notice</span><span class="z-comment"> Update the guard of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Delete function: set guard to 0 address and set expires to 0; </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and update function: set guard to new address and set expires</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"> tokenId</span><span class="z-comment"> The NFT to update the guard 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"> newGuard</span><span class="z-comment"> The newGuard 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"> expires</span><span class="z-comment"> UNIX timestamp, the guard could manage the token 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"> allowNull</span><span class="z-comment"> Allow 0 address</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _updateGuard</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"> newGuard</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"> allowNull</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span> (</span><span class="z-support">address</span><span> guard</span><span>,</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> guardInfo</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>allowNull</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>newGuard </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;ERC6147: new guard can not be null&quot;</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>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></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>guard </span><span class="z-keyword">==</span><span class="z-entity z-name"> _msgSender</span><span>(</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC6147: only guard can change it self&quot;</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</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-entity z-name">_msgSender</span><span>(</span><span>)</span><span>,</span><span> tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC6147: caller is not owner nor approved&quot;</span><span>)</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-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 class="z-keyword"> ||</span><span> newGuard </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> _guardInfo</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> GuardInfo</span><span>(</span><span>newGuard</span><span>,</span><span>expires</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> UpdateGuardLog</span><span>(</span><span>tokenId</span><span>,</span><span> newGuard</span><span>,</span><span> guard</span><span>,</span><span> expires</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Check the guard 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 zero address indicates there is no guard</span></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 check the guard 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"> guard address</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _checkGuard</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"> 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 class="z-support">address</span><span> guard</span><span>,</span><span> )</span><span class="z-keyword"> =</span><span class="z-entity z-name"> guardInfo</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> sender </span><span class="z-keyword">=</span><span class="z-entity z-name"> _msgSender</span><span>(</span><span>)</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"> require</span><span>(</span><span>guard </span><span class="z-keyword">==</span><span> sender</span><span>,</span><span class="z-string"> &quot;ERC6147: sender is not guard of the token&quot;</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 class="z-keyword">else</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> }</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"> Before transferring the NFT, need to check the gurard address</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"> 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-support"> address</span><span> guard</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> new_from </span><span class="z-keyword">=</span><span> from</span><span>;</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 class="giallo-l"><span> guard </span><span class="z-keyword">=</span><span class="z-entity z-name"> _checkGuard</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> new_from </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 class="giallo-l"><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"> require</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> _isApprovedOrOwner</span><span>(</span><span class="z-entity z-name">_msgSender</span><span>(</span><span>)</span><span>,</span><span> tokenId</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;ERC721: transfer caller is not owner nor approved&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-entity z-name"> _transfer</span><span>(</span><span>new_from</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-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Before safe transferring the NFT, need to check the gurard address</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"> tokenId</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"> _data</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-support"> address</span><span> guard</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> new_from </span><span class="z-keyword">=</span><span> from</span><span>;</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 class="giallo-l"><span> guard </span><span class="z-keyword">=</span><span class="z-entity z-name"> _checkGuard</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> new_from </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 class="giallo-l"><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"> require</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> _isApprovedOrOwner</span><span>(</span><span class="z-entity z-name">_msgSender</span><span>(</span><span>)</span><span>,</span><span> tokenId</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;ERC721: transfer caller is not owner nor approved&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-entity z-name"> _safeTransfer</span><span>(</span><span>from</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>,</span><span> _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-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> When burning, delete `token_guard_map[tokenId]`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This is an internal function that does not check if the sender is authorized to operate on the token.</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 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> (</span><span class="z-support">address</span><span> guard</span><span>,</span><span> )</span><span class="z-keyword">=</span><span class="z-entity z-name">guardInfo</span><span>(</span><span>tokenId</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">_burn</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> _guardInfo</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"> UpdateGuardLog</span><span>(</span><span>tokenId</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span> guard</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-storage z-type"> @dev</span><span class="z-comment"> See {IERC165-supportsInterface}.</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"> 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>IERC6147</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> <span class="giallo-l"></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Make sure to set an appropriate <code>expires</code> for the <code>guard</code>, based on the specific application scenario.</p> <p>When an NFT has a valid guard, even if an address is authorized as an operator through <code>approve</code> or <code>setApprovalForAll</code>, the operator still has no right to transfer the NFT.</p> <p>When an NFT has a valid guard, the <code>owner</code> cannot sell the NFT. Some trading platforms list NFTs through <code>setApprovalForAll</code> and owners' signature. It is recommended to prevent listing these NFTs by checking <code>guardInfo</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-12-06T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ernesto Garcíahttps://github.com/ernestognw Francisco Giordanohttps://github.com/frangio Hadrien Crouboishttps://github.com/Amxx https://wg-eips.ritovision.com/6093/

Lists custom errors for common token implementations

<h2 id="abstract">Abstract</h2> <p>This EIP defines a standard set of custom errors for commonly-used tokens, which are defined as <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> tokens.</p> <p>Ethereum applications and wallets have historically relied on revert reason strings to display the cause of transaction errors to users. Recent Solidity versions offer rich revert reasons with error-specific decoding (sometimes called "custom errors"). This EIP defines a standard set of errors designed to give at least the same relevant information as revert reason strings, but in a structured and expected way that clients can implement decoding for.</p> <h2 id="motivation">Motivation</h2> <p>Since the introduction of Solidity custom errors in v0.8.4, these have provided a way to show failures in a more expressive and gas efficient manner with dynamic arguments, while reducing deployment costs.</p> <p>However, <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> were already finalized when custom errors were released, so no errors are included in their specification.</p> <p>Standardized errors allow users to expect more consistent error messages across applications or testing environments, while exposing pertinent arguments and overall reducing the need of writing expensive revert strings in the deployment bytecode.</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 following errors were designed according to the criteria described in <a href="https://wg-eips.ritovision.com/6093/#rationale">Rationale</a>.</p> <p>This EIP defines standard errors that may be used by implementations in certain scenarios but it does not specify whether implementations should revert in those scenarios, which remains up to the implementers unless a revert is mandated by the corresponding EIPs.</p> <p>The names of the error arguments are defined in the <a href="https://wg-eips.ritovision.com/6093/#parameter-glossary">Parameter Glossary</a> and MUST be used according to those definitions.</p> <h3 id="erc-20"><a href="https://wg-eips.ritovision.com/20/">ERC-20</a></h3> <h4 id="erc20insufficientbalance-address-sender-uint256-balance-uint256-needed"><code>ERC20InsufficientBalance(address sender, uint256 balance, uint256 needed)</code></h4> <p>Indicates an error related to the current <code>balance</code> of a <code>sender</code>. Used in transfers.</p> <p>Usage guidelines:</p> <ul> <li><code>balance</code> MUST be less than <code>needed</code>.</li> </ul> <h4 id="erc20invalidsender-address-sender"><code>ERC20InvalidSender(address sender)</code></h4> <p>Indicates a failure with the token <code>sender</code>. Used in transfers.</p> <p>Usage guidelines:</p> <ul> <li>RECOMMENDED for disallowed transfers from the zero address.</li> <li>MUST NOT be used for approval operations.</li> <li>MUST NOT be used for balance or allowance requirements. <ul> <li>Use <code>ERC20InsufficientBalance</code> or <code>ERC20InsufficientAllowance</code> instead.</li> </ul> </li> </ul> <h4 id="erc20invalidreceiver-address-receiver"><code>ERC20InvalidReceiver(address receiver)</code></h4> <p>Indicates a failure with the token <code>receiver</code>. Used in transfers.</p> <p>Usage guidelines:</p> <ul> <li>RECOMMENDED for disallowed transfers to the zero address.</li> <li>RECOMMENDED for disallowed transfers to non-compatible addresses (eg. contract addresses).</li> <li>MUST NOT be used for approval operations.</li> </ul> <h4 id="erc20insufficientallowance-address-spender-uint256-allowance-uint256-needed"><code>ERC20InsufficientAllowance(address spender, uint256 allowance, uint256 needed)</code></h4> <p>Indicates a failure with the <code>spender</code>'s <code>allowance</code>. Used in transfers.</p> <p>Usage guidelines:</p> <ul> <li><code>allowance</code> MUST be less than <code>needed</code>.</li> </ul> <h4 id="erc20invalidapprover-address-approver"><code>ERC20InvalidApprover(address approver)</code></h4> <p>Indicates a failure with the <code>approver</code> of a token to be approved. Used in approvals.</p> <p>Usage guidelines:</p> <ul> <li>RECOMMENDED for disallowed approvals from the zero address.</li> <li>MUST NOT be used for transfer operations.</li> </ul> <h4 id="erc20invalidspender-address-spender"><code>ERC20InvalidSpender(address spender)</code></h4> <p>Indicates a failure with the <code>spender</code> to be approved. Used in approvals.</p> <p>Usage guidelines:</p> <ul> <li>RECOMMENDED for disallowed approvals to the zero address.</li> <li>RECOMMENDED for disallowed approvals to the owner itself.</li> <li>MUST NOT be used for transfer operations. <ul> <li>Use <code>ERC20InsufficientAllowance</code> instead.</li> </ul> </li> </ul> <h3 id="erc-721"><a href="https://wg-eips.ritovision.com/721/">ERC-721</a></h3> <h4 id="erc721invalidowner-address-owner"><code>ERC721InvalidOwner(address owner)</code></h4> <p>Indicates that an address can't be an owner. Used in balance queries.</p> <p>Usage guidelines:</p> <ul> <li>RECOMMENDED for addresses whose ownership is disallowed (eg. ERC-721 explicitly disallows <code>address(0)</code> to be an owner).</li> <li>MUST NOT be used for transfers. <ul> <li>Use <code>ERC721IncorrectOwner</code> instead.</li> </ul> </li> </ul> <h4 id="erc721nonexistenttoken-uint256-tokenid"><code>ERC721NonexistentToken(uint256 tokenId)</code></h4> <p>Indicates a <code>tokenId</code> whose <code>owner</code> is the zero address.</p> <p>Usage guidelines:</p> <ul> <li>The <code>tokenId</code> MUST BE a non-minted or burned token.</li> </ul> <h4 id="erc721incorrectowner-address-sender-uint256-tokenid-address-owner"><code>ERC721IncorrectOwner(address sender, uint256 tokenId, address owner)</code></h4> <p>Indicates an error related to the ownership over a particular token. Used in transfers.</p> <p>Usage guidelines:</p> <ul> <li><code>sender</code> MUST NOT be <code>owner</code>.</li> <li>MUST NOT be used for approval operations.</li> </ul> <h4 id="erc721invalidsender-address-sender"><code>ERC721InvalidSender(address sender)</code></h4> <p>Indicates a failure with the token <code>sender</code>. Used in transfers.</p> <p>Usage guidelines:</p> <ul> <li>RECOMMENDED for disallowed transfers from the zero address.</li> <li>MUST NOT be used for approval operations.</li> <li>MUST NOT be used for ownership or approval requirements. <ul> <li>Use <code>ERC721IncorrectOwner</code> or <code>ERC721InsufficientApproval</code> instead.</li> </ul> </li> </ul> <h4 id="erc721invalidreceiver-address-receiver"><code>ERC721InvalidReceiver(address receiver)</code></h4> <p>Indicates a failure with the token <code>receiver</code>. Used in transfers.</p> <p>Usage guidelines:</p> <ul> <li>RECOMMENDED for disallowed transfers to the zero address.</li> <li>RECOMMENDED for disallowed transfers to non-<code>ERC721TokenReceiver</code> contracts or those that reject a transfer. (eg. returning an invalid response in <code>onERC721Received</code>).</li> <li>MUST NOT be used for approval operations.</li> </ul> <h4 id="erc721insufficientapproval-address-operator-uint256-tokenid"><code>ERC721InsufficientApproval(address operator, uint256 tokenId)</code></h4> <p>Indicates a failure with the <code>operator</code>'s approval. Used in transfers.</p> <p>Usage guidelines:</p> <ul> <li><code>isApprovedForAll(owner, operator)</code> MUST be false for the <code>tokenId</code>'s owner and <code>operator</code>.</li> <li><code>getApproved(tokenId)</code> MUST not be <code>operator</code>.</li> </ul> <h4 id="erc721invalidapprover-address-approver"><code>ERC721InvalidApprover(address approver)</code></h4> <p>Indicates a failure with the <code>owner</code> of a token to be approved. Used in approvals.</p> <p>Usage guidelines:</p> <ul> <li>RECOMMENDED for disallowed approvals from the zero address.</li> <li>MUST NOT be used for transfer operations.</li> </ul> <h4 id="erc721invalidoperator-address-operator"><code>ERC721InvalidOperator(address operator)</code></h4> <p>Indicates a failure with the <code>operator</code> to be approved. Used in approvals.</p> <p>Usage guidelines:</p> <ul> <li>RECOMMENDED for disallowed approvals to the zero address.</li> <li>The <code>operator</code> MUST NOT be the owner of the approved token.</li> <li>MUST NOT be used for transfer operations. <ul> <li>Use <code>ERC721InsufficientApproval</code> instead.</li> </ul> </li> </ul> <h3 id="erc-1155"><a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a></h3> <h4 id="erc1155insufficientbalance-address-sender-uint256-balance-uint256-needed-uint256-tokenid"><code>ERC1155InsufficientBalance(address sender, uint256 balance, uint256 needed, uint256 tokenId)</code></h4> <p>Indicates an error related to the current <code>balance</code> of a <code>sender</code>. Used in transfers.</p> <p>Usage guidelines:</p> <ul> <li><code>balance</code> MUST be less than <code>needed</code> for a <code>tokenId</code>.</li> </ul> <h4 id="erc1155invalidsender-address-sender"><code>ERC1155InvalidSender(address sender)</code></h4> <p>Indicates a failure with the token <code>sender</code>. Used in transfers.</p> <p>Usage guidelines:</p> <ul> <li>RECOMMENDED for disallowed transfers from the zero address.</li> <li>MUST NOT be used for approval operations.</li> <li>MUST NOT be used for balance or allowance requirements. <ul> <li>Use <code>ERC1155InsufficientBalance</code> or <code>ERC1155MissingApprovalForAll</code> instead.</li> </ul> </li> </ul> <h4 id="erc1155invalidreceiver-address-receiver"><code>ERC1155InvalidReceiver(address receiver)</code></h4> <p>Indicates a failure with the token <code>receiver</code>. Used in transfers.</p> <p>Usage guidelines:</p> <ul> <li>RECOMMENDED for disallowed transfers to the zero address.</li> <li>RECOMMENDED for disallowed transfers to non-<code>ERC1155TokenReceiver</code> contracts or those that reject a transfer. (eg. returning an invalid response in <code>onERC1155Received</code>).</li> <li>MUST NOT be used for approval operations.</li> </ul> <h4 id="erc1155missingapprovalforall-address-operator-address-owner"><code>ERC1155MissingApprovalForAll(address operator, address owner)</code></h4> <p>Indicates a failure with the <code>operator</code>'s approval in a transfer. Used in transfers.</p> <p>Usage guidelines:</p> <ul> <li><code>isApprovedForAll(owner, operator)</code> MUST be false for the <code>tokenId</code>'s owner and <code>operator</code>.</li> </ul> <h4 id="erc1155invalidapprover-address-approver"><code>ERC1155InvalidApprover(address approver)</code></h4> <p>Indicates a failure with the <code>approver</code> of a token to be approved. Used in approvals.</p> <p>Usage guidelines:</p> <ul> <li>RECOMMENDED for disallowed approvals from the zero address.</li> <li>MUST NOT be used for transfer operations.</li> </ul> <h4 id="erc1155invalidoperator-address-operator"><code>ERC1155InvalidOperator(address operator)</code></h4> <p>Indicates a failure with the <code>operator</code> to be approved. Used in approvals.</p> <p>Usage guidelines:</p> <ul> <li>RECOMMENDED for disallowed approvals to the zero address.</li> <li>MUST be used for disallowed approvals to the owner itself.</li> <li>MUST NOT be used for transfer operations. <ul> <li>Use <code>ERC1155InsufficientApproval</code> instead.</li> </ul> </li> </ul> <h4 id="erc1155invalidarraylength-uint256-idslength-uint256-valueslength"><code>ERC1155InvalidArrayLength(uint256 idsLength, uint256 valuesLength)</code></h4> <p>Indicates an array length mismatch between <code>ids</code> and <code>values</code> in a <code>safeBatchTransferFrom</code> operation. Used in batch transfers.</p> <p>Usage guidelines:</p> <ul> <li><code>idsLength</code> MUST NOT be <code>valuesLength</code>.</li> </ul> <h3 id="parameter-glossary">Parameter Glossary</h3> <table><thead><tr><th>Name</th><th>Description</th></tr></thead><tbody> <tr><td><code>sender</code></td><td>Address whose tokens are being transferred.</td></tr> <tr><td><code>balance</code></td><td>Current balance for the interacting account.</td></tr> <tr><td><code>needed</code></td><td>Minimum amount required to perform an action.</td></tr> <tr><td><code>receiver</code></td><td>Address to which tokens are being transferred.</td></tr> <tr><td><code>spender</code></td><td>Address that may be allowed to operate on tokens without being their owner.</td></tr> <tr><td><code>allowance</code></td><td>Amount of tokens a <code>spender</code> is allowed to operate with.</td></tr> <tr><td><code>approver</code></td><td>Address initiating an approval operation.</td></tr> <tr><td><code>tokenId</code></td><td>Identifier number of a token.</td></tr> <tr><td><code>owner</code></td><td>Address of the current owner of a token.</td></tr> <tr><td><code>operator</code></td><td>Same as <code>spender</code>.</td></tr> <tr><td><code>*Length</code></td><td>Array length for the prefixed parameter.</td></tr> </tbody></table> <h3 id="error-additions">Error additions</h3> <p>Any addition to this EIP or implementation-specific errors (such as extensions) SHOULD follow the guidelines presented in the <a href="https://wg-eips.ritovision.com/6093/#rationale">rationale</a> section to keep consistency.</p> <h2 id="rationale">Rationale</h2> <p>The chosen objectives for a standard for token errors are to provide context about the error, and to make moderate use of meaningful arguments (to maintain the code size benefits with respect to strings).</p> <p>Considering this, the error names are designed following a basic grammatical structure based on the standard actions that can be performed on each token and the <a href="https://wg-eips.ritovision.com/6093/#actions-and-subjects">subjects</a> involved.</p> <h3 id="actions-and-subjects">Actions and subjects</h3> <p>An error is defined based on the following <strong>actions</strong> that can be performed on a token and its involved <em>subjects</em>:</p> <ul> <li><strong>Transfer</strong>: An operation in which a <em>sender</em> moves to a <em>receiver</em> any number of tokens (fungible <em>balance</em> and/or non-fungible <em>token ids</em>).</li> <li><strong>Approval</strong>: An operation in which an <em>approver</em> grants any form of <em>approval</em> to an <em>operator</em>.</li> </ul> <p>These attempt to exhaustively represent what can go wrong in a token operation. Therefore, the errors can be constructed by specifying which <em>subject</em> failed during an <strong>action</strong> execution, and prefixing with an <a href="https://wg-eips.ritovision.com/6093/#error-prefixes">error prefix</a>.</p> <p>Note that the action is never seen as the subject of an error.</p> <p>If a subject is called different on a particular token standard, the error should be consistent with the standard's naming convention.</p> <h3 id="error-prefixes">Error prefixes</h3> <p>An error prefix is added to a subject to derive a concrete error condition. Developers can think about an error prefix as the <em>why</em> an error happened.</p> <p>A prefix can be <code>Invalid</code> for general incorrectness, or more specific like <code>Insufficient</code> for amounts.</p> <h3 id="domain">Domain</h3> <p>Each error's arguments may vary depending on the token domain. If there are errors with the same name and different arguments, the Solidity compiler currently fails with a <code>DeclarationError</code>.</p> <p>An example of this is:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name">InsufficientApproval</span><span>(</span><span class="z-support">address</span><span> spender</span><span>,</span><span class="z-support"> uint256</span><span> allowance</span><span>,</span><span class="z-support"> uint256</span><span> needed</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">InsufficientApproval</span><span>(</span><span class="z-support">address</span><span> operator</span><span>,</span><span class="z-support"> uint256</span><span> tokenId</span><span>)</span><span>;</span></span></code></pre> <p>For that reason, a domain prefix is proposed to avoid declaration clashing, which is the name of the ERC and its corresponding number appended at the beginning.</p> <p>Example:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name">ERC20InsufficientApproval</span><span>(</span><span class="z-support">address</span><span> spender</span><span>,</span><span class="z-support"> uint256</span><span> allowance</span><span>,</span><span class="z-support"> uint256</span><span> needed</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">ERC721InsufficientApproval</span><span>(</span><span class="z-support">address</span><span> operator</span><span>,</span><span class="z-support"> uint256</span><span> tokenId</span><span>)</span><span>;</span></span></code></pre><h3 id="arguments">Arguments</h3> <p>The selection of arguments depends on the subject involved, and it should follow the order presented below:</p> <ol> <li><em>Who</em> is involved with the error (eg. <code>address sender</code>)</li> <li><em>What</em> failed (eg. <code>uint256 allowance</code>)</li> <li><em>Why</em> it failed, expressed in additional arguments (eg. <code>uint256 needed</code>)</li> </ol> <p>A particular argument may fall into overlapping categories (eg. <em>Who</em> may also be <em>What</em>), so not all of these will be present but the order shouldn't be broken.</p> <p>Some tokens may need a <code>tokenId</code>. This is suggested to include at the end as additional information instead of as a subject.</p> <h3 id="error-grammar-rules">Error grammar rules</h3> <p>Given the above, we can summarize the construction of error names with a grammar that errors will follow:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&lt;Domain&gt;&lt;ErrorPrefix&gt;&lt;Subject&gt;(&lt;Arguments&gt;);</span></span></code></pre> <p>Where:</p> <ul> <li><em>Domain</em>: <code>ERC20</code>, <code>ERC721</code> or <code>ERC1155</code>. Although other token standards may be suggested if not considered in this EIP.</li> <li><em>ErrorPrefix</em>: <code>Invalid</code>, <code>Insufficient</code>, or another if it's more appropriate.</li> <li><em>Subject</em>: <code>Sender</code>, <code>Receiver</code>, <code>Balance</code>, <code>Approver</code>, <code>Operator</code>, <code>Approval</code> or another if it's more appropriate, and must make adjustments based on the domain's naming convention.</li> <li><em>Arguments</em>: Follow the <a href="https://wg-eips.ritovision.com/6093/#arguments"><em>who</em>, <em>what</em> and <em>why</em> order</a>.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Tokens already deployed rely mostly on revert strings and make use of <code>require</code> instead of custom errors. Even most of the newly deployed tokens since Solidity's v0.8.4 release inherit from implementations using revert strings.</p> <p>This EIP can not be enforced on non-upgradeable already deployed tokens, however, these tokens generally use similar conventions with small variations such as:</p> <ul> <li>including/removing the <a href="https://wg-eips.ritovision.com/6093/#domain">domain</a>.</li> <li>using different <a href="https://wg-eips.ritovision.com/6093/#error-prefixes">error prefixes</a>.</li> <li>including similar <a href="https://wg-eips.ritovision.com/6093/#actions-and-subjects">subjects</a>.</li> <li>changing the grammar order.</li> </ul> <p>Upgradeable contracts MAY be upgraded to implement this EIP.</p> <p>Implementers and DApp developers that implement special support for tokens that are compliant with this EIP, SHOULD tolerate different errors emitted by non-compliant contracts, as well as classic revert strings.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="solidity">Solidity</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.4</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"> Standard ERC20 Errors</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-20</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> https://eips.ethereum.org/EIPS/eip-6093</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC20Errors</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC20InsufficientBalance</span><span>(</span><span class="z-support">address</span><span> sender</span><span>,</span><span class="z-support"> uint256</span><span> balance</span><span>,</span><span class="z-support"> uint256</span><span> needed</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC20InvalidSender</span><span>(</span><span class="z-support">address</span><span> sender</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC20InvalidReceiver</span><span>(</span><span class="z-support">address</span><span> receiver</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC20InsufficientAllowance</span><span>(</span><span class="z-support">address</span><span> spender</span><span>,</span><span class="z-support"> uint256</span><span> allowance</span><span>,</span><span class="z-support"> uint256</span><span> needed</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC20InvalidApprover</span><span>(</span><span class="z-support">address</span><span> approver</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC20InvalidSpender</span><span>(</span><span class="z-support">address</span><span> spender</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"> @title</span><span class="z-comment"> Standard ERC721 Errors</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 class="z-comment"> https://eips.ethereum.org/EIPS/eip-6093</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC721Errors</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC721InvalidOwner</span><span>(</span><span class="z-support">address</span><span> owner</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC721NonexistentToken</span><span>(</span><span class="z-support">uint256</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC721IncorrectOwner</span><span>(</span><span class="z-support">address</span><span> sender</span><span>,</span><span class="z-support"> uint256</span><span> tokenId</span><span>,</span><span class="z-support"> address</span><span> owner</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC721InvalidSender</span><span>(</span><span class="z-support">address</span><span> sender</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC721InvalidReceiver</span><span>(</span><span class="z-support">address</span><span> receiver</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC721InsufficientApproval</span><span>(</span><span class="z-support">address</span><span> operator</span><span>,</span><span class="z-support"> uint256</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC721InvalidApprover</span><span>(</span><span class="z-support">address</span><span> approver</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC721InvalidOperator</span><span>(</span><span class="z-support">address</span><span> operator</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"> @title</span><span class="z-comment"> Standard ERC1155 Errors</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-1155</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> https://eips.ethereum.org/EIPS/eip-6093</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC1155Errors</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC1155InsufficientBalance</span><span>(</span><span class="z-support">address</span><span> sender</span><span>,</span><span class="z-support"> uint256</span><span> balance</span><span>,</span><span class="z-support"> uint256</span><span> needed</span><span>,</span><span class="z-support"> uint256</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC1155InvalidSender</span><span>(</span><span class="z-support">address</span><span> sender</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC1155InvalidReceiver</span><span>(</span><span class="z-support">address</span><span> receiver</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC1155MissingApprovalForAll</span><span>(</span><span class="z-support">address</span><span> operator</span><span>,</span><span class="z-support"> address</span><span> owner</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC1155InvalidApprover</span><span>(</span><span class="z-support">address</span><span> approver</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC1155InvalidOperator</span><span>(</span><span class="z-support">address</span><span> operator</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> ERC1155InvalidArrayLength</span><span>(</span><span class="z-support">uint256</span><span> idsLength</span><span>,</span><span class="z-support"> uint256</span><span> valuesLength</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 known signature hash collisions for the specified errors.</p> <p>Tokens upgraded to implement this EIP may break assumptions in other systems relying on revert strings.</p> <p>Offchain applications should be cautious when dealing with untrusted contracts that may revert using these custom errors. For instance, if a user interface prompts actions based on error decoding, malicious contracts could exploit this to encourage untrusted and potentially harmful operations.</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-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 5660-ethhttps://github.com/5660-eth Silvere Heraudeauhttps://github.com/lambdalf-dev Martin McConnellhttps://github.com/offgridgecko Abuteam10kuni@gmail.com Wizard Wang https://wg-eips.ritovision.com/6105/

Adds a marketplace functionality with more diverse royalty schemes to ERC-721

<h2 id="abstract">Abstract</h2> <p>This ERC adds a marketplace functionality to <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> to enable non-fungible token trading without relying on an intermediary trading platform. At the same time, creators may implement more diverse royalty schemes.</p> <h2 id="motivation">Motivation</h2> <p>Most current NFT trading relies on an NFT trading platform acting as an intermediary, which has the following problems:</p> <ol> <li>Security concerns arise from authorization via the <code>setApprovalForAll</code> function. The permissions granted to NFT trading platforms expose unnecessary risks. Should a problem occur with the trading platform contract, it would result in significant losses to the industry as a whole. Additionally, if a user has authorized the trading platform to handle their NFTs, it allows a phishing scam to trick the user into signing a message that allows the scammer to place an order at a low price on the NFT trading platform and designate themselves as the recipient. This can be difficult for ordinary users to guard against.</li> <li>High trading costs are a significant issue. On one hand, as the number of trading platforms increases, the liquidity of NFTs becomes dispersed. If a user needs to make a deal quickly, they must authorize and place orders on multiple platforms, which increases the risk exposure and requires additional gas expenditures for each authorization. For example, taking BAYC as an example, with a total supply of 10,000 and over 6,000 current holders, the average number of BAYC held by each holder is less than 2. While <code>setApprovalForAll</code> saves on gas expenditure for pending orders on a single platform, authorizing multiple platforms results in an overall increase in gas expenditures for users. On the other hand, trading service fees charged by trading platforms must also be considered as a cost of trading, which are often much higher than the required gas expenditures for authorization.</li> <li>Aggregators provide a solution by aggregating liquidity, but the decision-making process is centralized. Furthermore, as order information on trading platforms is off-chain, the aggregator's efficiency in obtaining data is affected by the frequency of the trading platform's API and, at times, trading platforms may suspend the distribution of APIs and limit their frequency.</li> <li>The project parties' royalty income is dependent on centralized decision-making by NFT trading platforms. Some trading platforms implement optional royalty without the consent of project parties, which is a violation of their interests.</li> <li>NFT trading platforms are not resistant to censorship. Some platforms have delisted a number of NFTs and the formulation and implementation of delisting rules are centralized and not transparent enough. In the past, some NFT trading platforms have failed and wrongly delisted certain NFTs, leading to market panic.</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>Compliant contracts 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"> IERC6105</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"> Emitted when a token is listed for sale or delisted</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 `salePrice` indicates that the token is not for sale</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero `expires` indicates that the token is not for sale</span></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 being listed</span></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"> - address of who is selling 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"> salePrice</span><span class="z-comment"> - the price the token is being sold 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"> expires</span><span class="z-comment"> - UNIX timestamp, the buyer could buy the token 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported token or zero address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero address indicates that the supported token is ETH</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Buyer needs to purchase item with supported 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"> benchmarkPrice</span><span class="z-comment"> - Additional price parameter, may be used when calculating royalties</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UpdateListing</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"> 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"> salePrice</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> expires</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> supportedToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> benchmarkPrice</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"> Emitted when a token is being purchased</span></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 being purchased</span></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"> - address of who is selling 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"> to</span><span class="z-comment"> - address of who is buying 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"> salePrice</span><span class="z-comment"> - the price the token is being sold 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported token or zero address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero address indicates that the supported token is ETH</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Buyer needs to purchase item with supported 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"> royalties</span><span class="z-comment"> - The amount of royalties paid on this purchase</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Purchased</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"> 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"> salePrice</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> supportedToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> royalties</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"> Create or update a listing for `tokenId`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `salePrice` MUST NOT be set to zero</span></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 being listed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> salePrice</span><span class="z-comment"> - the price the token is being sold 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"> expires</span><span class="z-comment"> - UNIX timestamp, the buyer could buy the token 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported token or zero address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero address indicates that the supported token is ETH</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Buyer needs to purchase item with supported token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `tokenId` must exist</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Caller must be owner, authorised operators or approved address of the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `salePrice` must not be zero</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `expires` must be valid</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Must emit an {UpdateListing} event.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> listItem</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"> salePrice</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> expires</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> supportedToken</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-storage z-type"> @notice</span><span class="z-comment"> Create or update a listing for `tokenId` with `benchmarkPrice`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `salePrice` MUST NOT be set to zero</span></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 being listed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> salePrice</span><span class="z-comment"> - the price the token is being sold 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"> expires</span><span class="z-comment"> - UNIX timestamp, the buyer could buy the token 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported token or zero address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero address indicates that the supported token is ETH</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Buyer needs to purchase item with supported 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"> benchmarkPrice</span><span class="z-comment"> - Additional price parameter, may be used when calculating royalties</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `tokenId` must exist</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Caller must be owner, authorised operators or approved address of the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `salePrice` must not be zero</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `expires` must be valid</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Must emit an {UpdateListing} event.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> listItem</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"> salePrice</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> expires</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> supportedToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> benchmarkPrice</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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Remove the listing for `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"> tokenId</span><span class="z-comment"> - identifier of the token being delisted</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `tokenId` must exist and be listed for sale</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Caller must be owner, authorised operators or approved address of the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Must emit an {UpdateListing} event</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> delistItem</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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Buy a token and transfer it to the caller</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `salePrice` and `supportedToken` must match the expected purchase price and token to prevent front-running attacks</span></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 being purchased</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> salePrice</span><span class="z-comment"> - the price the token is being sold 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported token or zero address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `tokenId` must exist and be listed for sale</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `salePrice` must matches the expected purchase price to prevent front-running attacks</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `supportedToken` must matches the expected purchase token to prevent front-running attacks</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Caller must be able to pay the listed price for `tokenId`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Must emit a {Purchased} event</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> buyItem</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"> salePrice</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> supportedToken</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"> Return the listing for `tokenId`</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 sale price indicates that the token is not for sale</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero expires indicates that the token is not for sale</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero supported token address indicates that the supported token is ETH</span></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 being 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"> the</span><span class="z-comment"> specified listing (sale price, expires, supported token, benchmark price)</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getListing</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 class="z-support"> uint64</span><span>,</span><span class="z-support"> address</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="optional-collection-offer-extension">Optional collection offer extension</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> The collection offer extension is OPTIONAL for ERC-6105 smart contracts. This allows smart contract to support collection offer functionality.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6105CollectionOffer</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"> Emitted when the collection receives an offer or an offer is canceled</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 `salePrice` indicates that the collection offer of the token is canceled</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero `expires` indicates that the collection offer of the token is canceled</span></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"> - address of who make collection offer</span></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"> - the amount the offerer wants to buy at `salePrice` per 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"> salePrice</span><span class="z-comment"> - the price of each token is being offered for the collection</span></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 offer could be accepted 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported ERC20 token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Buyer wants to purchase items with supported token</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UpdateCollectionOffer</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-variable"> amount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> salePrice</span><span> ,</span><span class="z-support">uint64</span><span class="z-variable"> expires</span><span>, </span><span class="z-support">address</span><span class="z-variable"> supportedToken</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"> Create or update an offer for the collection</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `salePrice` MUST NOT be set to zero</span></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"> - the amount the offerer wants to buy at `salePrice` per 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"> salePrice</span><span class="z-comment"> - the price of each token is being offered for the collection</span></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 offer could be accepted 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Buyer wants to purchase items with supported token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - The caller must have enough supported tokens, and has approved the contract a sufficient amount</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `salePrice` must not be zero</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `amount` must not be zero</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `expires` must be valid</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Must emit an {UpdateCollectionOffer} event</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> makeCollectionOffer</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"> salePrice</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> expires</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> supportedToken</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"> Accepts collection offer and transfers the token to the buyer</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `salePrice` and `supportedToken` must match the expected purchase price and token to prevent front-running attacks</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> When the trading is completed, the `amount` of NFTs the buyer wants to purchase needs to be reduced by 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"> - identifier of the token being offered</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> salePrice</span><span class="z-comment"> - the price the token is being offered 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported 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"> buyer</span><span class="z-comment"> - address of who wants to buy the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `tokenId` must exist and be offered for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Caller must be owner, authorised operators or approved address of the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Must emit a {Purchased} event</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptCollectionOffer</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"> salePrice</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> supportedToken</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> buyer</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"> Accepts collection offer and transfers the token to the buyer</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `salePrice` and `supportedToken` must match the expected purchase price and token to prevent front-running attacks</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> When the trading is completed, the `amount` of NFTs the buyer wants to purchase needs to be reduced by 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"> - identifier of the token being offered</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> salePrice</span><span class="z-comment"> - the price the token is being offered 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported 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"> buyer</span><span class="z-comment"> - address of who wants to buy 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"> benchmarkPrice</span><span class="z-comment"> - additional price parameter, may be used when calculating royalties</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `tokenId` must exist and be offered for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Caller must be owner, authorised operators or approved address of the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Must emit a {Purchased} event</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptCollectionOffer</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"> salePrice</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> supportedToken</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> buyer</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> benchmarkPrice</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"> Removes the offer for the collection</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Caller must be the offerer</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Must emit an {UpdateCollectionOffer} event</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> cancelCollectionOffer</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"> Returns the offer for `tokenId` maked by `buyer`</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 amount indicates there is no offer</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero sale price indicates there is no offer</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero expires indicates that there is no offer</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> buyer</span><span class="z-comment"> address of who wants to buy 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"> the</span><span class="z-comment"> specified offer (amount, sale price, expires, supported token)</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getCollectionOffer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> buyer</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 class="z-support"> uint64</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="optional-item-offer-extension">Optional item offer extension</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> The item offer extension is OPTIONAL for ERC-6105 smart contracts. This allows smart contract to support item offer functionality.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6105ItemOffer</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"> Emitted when a token receives an offer or an offer is canceled</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 `salePrice` indicates that the offer of the token is canceled</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero `expires` indicates that the offer of the token is canceled</span></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 being offered</span></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"> - address of who wants to buy 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"> salePrice</span><span class="z-comment"> - the price the token is being offered 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"> expires</span><span class="z-comment"> - UNIX timestamp, the offer could be accepted 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Buyer wants to purchase item with supported token</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UpdateItemOffer</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"> 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"> salePrice</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> expires</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> supportedToken</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"> Create or update an offer for `tokenId`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `salePrice` MUST NOT be set to zero</span></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 being offered</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> salePrice</span><span class="z-comment"> - the price the token is being offered 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"> expires</span><span class="z-comment"> - UNIX timestamp, the offer could be accepted 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Buyer wants to purchase item with supported token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `tokenId` must exist</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - The caller must have enough supported tokens, and has approved the contract a sufficient amount</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `salePrice` must not be zero</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `expires` must be valid</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Must emit an {UpdateItemOffer} event.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> makeItemOffer</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"> salePrice</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> expires</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> supportedToken</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 the offer for `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"> tokenId</span><span class="z-comment"> - identifier of the token being canceled offer</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `tokenId` must exist and be offered for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Caller must be the offerer</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Must emit an {UpdateItemOffer} event</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> cancelItemOffer</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Accept offer and transfer the token to the buyer</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `salePrice` and `supportedToken` must match the expected purchase price and token to prevent front-running attacks</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> When the trading is completed, the offer infomation needs to be 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"> tokenId</span><span class="z-comment"> - identifier of the token being offered</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> salePrice</span><span class="z-comment"> - the price the token is being offered 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported 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"> buyer</span><span class="z-comment"> - address of who wants to buy the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `tokenId` must exist and be offered for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Caller must be owner, authorised operators or approved address of the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Must emit a {Purchased} event</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptItemOffer</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"> salePrice</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> supportedToken</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> buyer</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"> Accepts offer and transfers the token to the buyer</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `salePrice` and `supportedToken` must match the expected purchase price and token to prevent front-running attacks</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> When the trading is completed, the offer infomation needs to be 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"> tokenId</span><span class="z-comment"> - identifier of the token being offered</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> salePrice</span><span class="z-comment"> - the price the token is being offered 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported 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"> buyer</span><span class="z-comment"> - address of who wants to buy 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"> benchmarkPrice</span><span class="z-comment"> - additional price parameter, may be used when calculating royalties</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `tokenId` must exist and be offered for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Caller must be owner, authorised operators or approved address of the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Must emit a {Purchased} event</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptItemOffer</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"> salePrice</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> supportedToken</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> buyer</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> benchmarkPrice</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"> Return the offer for `tokenId` maked by `buyer`</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 sale price indicates there is no offer</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero expires indicates that there is no offer</span></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 being 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"> buyer</span><span class="z-comment"> address of who wants to buy 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"> the</span><span class="z-comment"> specified offer (sale price, expires, supported token)</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getItemOffer</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"> buyer</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"> uint64</span><span>,</span><span class="z-support"> address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="considerations-for-some-local-variables">Considerations for some local variables</h3> <p>The <code>salePrice</code> in the <code>listItem</code> function cannot be set to zero. Firstly, it is a rare occurrence for a caller to set the price to 0, and when it happens, it is often due to an operational error which can result in loss of assets. Secondly, a caller needs to spend gas to call this function, so if he can set the token price to 0, his income would be actually negative at this time, which does not conform to the concept of 'economic man' in economics. Additionally, a token price of 0 indicates that the item is not for sale, making the reference implementation more concise.</p> <p>Setting <code>expires</code> in the <code>listItem</code> function allows callers to better manage their listings. If a listing expires automatically, the token owner will no longer need to manually <code>delistItem</code>, thus saving gas.</p> <p>Setting <code>supportedToken</code> in the <code>listItem</code> function allows the caller or contract owner to choose which tokens they want to accept, rather than being limited to a single token.</p> <p>The rationales of variable setting in the <code>acceptCollectionOffer</code> and <code>acceptItemOffer</code> functions are the same as described above.</p> <h3 id="more-diverse-royalty-schemes">More diverse royalty schemes</h3> <p>By introducing the parameter <code>benchmarkPrice</code> in the <code>listItem</code>, <code>acceptCollectionOffer</code> and <code>acceptItemOffer</code> functions, the <code>_salePrice</code> in the <code>royaltyInfo(uint256 _tokenId, uint256 _salePrice)</code> function in the <a href="https://wg-eips.ritovision.com/2981/">ERC-2981</a> interface can be changed to <code>taxablePrice</code>, making the ERC-2981 royalty scheme more diverse. Here are several examples of royalty schemes:</p> <p><code>(address royaltyRecipient, uint256 royalties) = royaltyInfo(tokenId, taxablePrice)</code></p> <ol> <li>Value-added Royalty (VAR, royalties are only charged on the part of the seller's profit）: <code>taxablePrice=max(salePrice- historicalPrice, 0)</code></li> <li>Sale Royalty (SR): <code>taxablePrice=salePrice</code></li> <li>Capped Royalty(CR): <code>taxablePrice=min(salePrice, constant)</code></li> <li>Quantitative Royalty(QR, each token trading pays a fixed royalties): <code>taxablePrice= constant</code></li> </ol> <h3 id="optional-blocklist">Optional Blocklist</h3> <p>Some viewpoints suggest that tokens should be prevented from trading on intermediary markets that do not comply with royalty schemes, but this standard only provides a functionality for non-intermediary NFT trading and does not offer a standardized interface to prevent tokens from trading on these markets. If deemed necessary to better protect the interests of the project team and community, they may consider adding a blocklist to their implementation contracts to prevent NFTs from being traded on platforms that do not comply with the project’s royalty scheme.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/2981/">ERC-2981</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: 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.8</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/token/common/ERC2981.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/IERC20.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/security/ReentrancyGuard.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC6105.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"> No Intermediary NFT Trading Protocol with Value-added Royalty</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The royalty scheme used by this reference implementation is Value-Added Royalty</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC6105</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">ERC2981</span><span>, </span><span class="z-entity z-name">IERC6105</span><span>, </span><span class="z-entity z-name">ReentrancyGuard</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"> A structure representing a listed token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero `salePrice` indicates that the token is not for sale</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero `expires` indicates that the token is not for sale</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> salePrice</span><span class="z-comment"> - the price the token is being sold 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"> expires</span><span class="z-comment"> - UNIX timestamp, the buyer could buy the token 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported ERC20 token or zero address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero address indicates that the supported token is ETH</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Buyer needs to purchase item with supported 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"> historicalPrice</span><span class="z-comment"> - The price at which the seller last bought this token</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Listing</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> salePrice</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> expires</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> supportedToken</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> historicalPrice</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"> Mapping from token Id to listing index</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> Listing</span><span>)</span><span class="z-storage z-type"> private</span><span> _listings</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> <span class="giallo-l"><span class="z-entity z-name"> ERC721</span><span>(</span><span>name_, symbol_)</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-storage z-type"> @notice</span><span class="z-comment"> Create or update a listing for `tokenId`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `salePrice` MUST NOT be set to zero</span></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 being listed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> salePrice</span><span class="z-comment"> - the price the token is being sold 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"> expires</span><span class="z-comment"> - UNIX timestamp, the buyer could buy the token 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported ERC20 token or zero address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero address indicates that the supported token is ETH</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Buyer needs to purchase item with supported token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> listItem</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"> salePrice</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> expires</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> supportedToken</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 class="z-entity z-name"> listItem</span><span>(</span><span>tokenId</span><span>,</span><span> salePrice</span><span>,</span><span> expires</span><span>,</span><span> supportedToken</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-storage z-type"> @notice</span><span class="z-comment"> Create or update a listing for `tokenId` with `historicalPrice`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `price` MUST NOT be set to zero</span></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 being listed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> salePrice</span><span class="z-comment"> - the price the token is being sold 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"> expires</span><span class="z-comment"> - UNIX timestamp, the buyer could buy the token 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported ERC20 token or zero address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero address indicates that the supported token is ETH</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Buyer needs to purchase item with supported 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"> historicalPrice</span><span class="z-comment"> - The price at which the seller last bought this token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> listItem</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"> salePrice</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> expires</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> supportedToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> historicalPrice</span></span> <span class="giallo-l"><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> <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>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>salePrice </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;ERC6105: token sale price MUST NOT be set to zero&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>expires </span><span class="z-keyword">&gt;</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</span><span>,</span><span class="z-string"> &quot;ERC6105: invalid expires&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">_isApprovedOrOwner</span><span>(</span><span class="z-entity z-name">_msgSender</span><span>(</span><span>)</span><span>,</span><span> tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC6105: caller is not owner nor approved&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _listings</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Listing</span><span>(</span><span>salePrice</span><span>,</span><span> expires</span><span>,</span><span> supportedToken</span><span>,</span><span> historicalPrice</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> UpdateListing</span><span>(</span><span>tokenId</span><span>,</span><span> tokenOwner</span><span>,</span><span> salePrice</span><span>,</span><span> expires</span><span>,</span><span> supportedToken</span><span>,</span><span> historicalPrice</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"> @notice</span><span class="z-comment"> Remove the listing for `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"> tokenId</span><span class="z-comment"> - identifier of the token being listed</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> delistItem</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"> virtual</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-entity z-name">_msgSender</span><span>(</span><span>)</span><span>,</span><span> tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC6105: caller is not owner nor approved&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">_isForSale</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC6105: invalid listing&quot;</span><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> _removeListing</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-storage z-type"> @notice</span><span class="z-comment"> Buy a token and transfers it to the caller</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> `salePrice` and `supportedToken` must match the expected purchase price and token to prevent front-running attacks</span></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 being purchased</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> salePrice</span><span class="z-comment"> - the price the token is being sold 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported token or zero address</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> buyItem</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"> salePrice</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> supportedToken</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> nonReentrant</span><span class="z-storage z-type"> payable</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>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> buyer </span><span class="z-keyword">=</span><span class="z-variable z-language"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> historicalPrice </span><span class="z-keyword">=</span><span> _listings</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>historicalPrice</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>salePrice </span><span class="z-keyword">==</span><span> _listings</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>salePrice</span><span>,</span><span class="z-string"> &quot;ERC6105: inconsistent prices&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>supportedToken </span><span class="z-keyword">==</span><span> _listings</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>supportedToken</span><span>,</span><span class="z-string">&quot;ERC6105: inconsistent tokens&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">_isForSale</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC6105: invalid listing&quot;</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"> Handle royalties</span></span> <span class="giallo-l"><span> (</span><span class="z-support">address</span><span> royaltyRecipient</span><span>,</span><span class="z-support"> uint256</span><span> royalties</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> _calculateRoyalties</span><span>(</span><span>tokenId</span><span>,</span><span> salePrice</span><span>,</span><span> historicalPrice</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> payment </span><span class="z-keyword">=</span><span> salePrice </span><span class="z-keyword">-</span><span> royalties</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>supportedToken </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 class="z-variable z-language">msg</span><span>.</span><span>value </span><span class="z-keyword">==</span><span> salePrice</span><span>,</span><span class="z-string"> &quot;ERC6105: incorrect value&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _processSupportedTokenPayment</span><span>(</span><span>royalties</span><span>,</span><span> buyer</span><span>,</span><span> royaltyRecipient</span><span>,</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"> _processSupportedTokenPayment</span><span>(</span><span>payment</span><span>,</span><span> buyer</span><span>,</span><span> tokenOwner</span><span>,</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></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>{</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> num </span><span class="z-keyword">=</span><span class="z-entity z-name"> IERC20</span><span>(</span><span>supportedToken</span><span>)</span><span>.</span><span class="z-entity z-name">allowance</span><span>(</span><span>buyer</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 class="z-keyword"> require</span><span> (</span><span>num </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> salePrice</span><span>,</span><span class="z-string"> &quot;ERC6105: insufficient allowance&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _processSupportedTokenPayment</span><span>(</span><span>royalties</span><span>,</span><span> buyer</span><span>,</span><span> royaltyRecipient</span><span>,</span><span> supportedToken</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _processSupportedTokenPayment</span><span>(</span><span>payment</span><span>,</span><span> buyer</span><span>,</span><span> tokenOwner</span><span>,</span><span> supportedToken</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"> _transfer</span><span>(</span><span>tokenOwner</span><span>,</span><span> buyer</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"> Purchased</span><span>(</span><span>tokenId</span><span>,</span><span> tokenOwner</span><span>,</span><span> buyer</span><span>,</span><span> salePrice</span><span>,</span><span> supportedToken</span><span>,</span><span> royalties</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"> @notice</span><span class="z-comment"> Return the listing for `tokenId`</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 sale price indicates that the token is not for sale</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero expires indicates that the token is not for sale</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero supported token address indicates that the supported token is ETH</span></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 being 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"> the</span><span class="z-comment"> specified listing (sale price, expires, supported token, benchmark price)</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getListing</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-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>,</span><span class="z-support"> uint64</span><span>,</span><span class="z-support"> address</span><span>,</span><span class="z-support"> uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>_listings</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>salePrice </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span class="z-keyword"> &amp;&amp;</span><span> _listings</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>expires </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>{</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> salePrice </span><span class="z-keyword">=</span><span> _listings</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>salePrice</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> expires </span><span class="z-keyword">=</span><span> _listings</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>expires</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> supportedToken </span><span class="z-keyword">=</span><span> _listings</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>supportedToken</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> historicalPrice </span><span class="z-keyword">=</span><span> _listings</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>historicalPrice</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>salePrice</span><span>,</span><span> expires</span><span>,</span><span> supportedToken</span><span>,</span><span> historicalPrice</span><span>)</span><span>;</span></span> <span class="giallo-l"><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 class="z-constant"> 0</span><span>,</span><span class="z-support"> address</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> }</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"> Remove the listing for `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"> tokenId</span><span class="z-comment"> - identifier of the token being delisted</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _removeListing</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>{</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>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> _listings</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"> UpdateListing</span><span>(</span><span>tokenId</span><span>,</span><span> tokenOwner</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-support"> address</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> }</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"> Check if the token is for sale</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _isForSale</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-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>_listings</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>salePrice </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span class="z-keyword"> &amp;&amp;</span><span> _listings</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>expires </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>{</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-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></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-storage z-type"> @dev</span><span class="z-comment"> Handle Value Added Royalty</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _calculateRoyalties</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"> price</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> historicalPrice</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-keyword"> returns</span><span>(</span><span class="z-support">address</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> taxablePrice</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>price </span><span class="z-keyword">&gt;</span><span> historicalPrice</span><span>)</span><span>{</span></span> <span class="giallo-l"><span> taxablePrice </span><span class="z-keyword">=</span><span> price </span><span class="z-keyword">-</span><span> historicalPrice</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>{</span></span> <span class="giallo-l"><span> taxablePrice </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 class="z-support">address</span><span> royaltyRecipient</span><span>,</span><span class="z-support"> uint256</span><span> royalties</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> royaltyInfo</span><span>(</span><span>tokenId</span><span>,</span><span> taxablePrice</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span>(</span><span>royaltyRecipient</span><span>,</span><span> royalties</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"> Process a `supportedToken` of `amount` payment to `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"> - the amount to send</span></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 payment payer</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> recipient</span><span class="z-comment"> - the payment 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"> supportedToken</span><span class="z-comment"> - contract addresses of supported ERC20 token or zero address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero address indicates that the supported token is ETH</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _processSupportedTokenPayment</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"> from</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"> address</span><span class="z-variable"> supportedToken</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>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>supportedToken </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><span class="z-support">bool</span><span> success</span><span>,</span><span>)</span><span class="z-keyword"> =</span><span class="z-storage z-type"> payable</span><span>(</span><span>recipient</span><span>)</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span> amount</span><span>}</span><span>(</span><span class="z-string">&quot;&quot;</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"> &quot;Ether Transfer Fail&quot;</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> else</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"> IERC20</span><span>(</span><span>supportedToken</span><span>)</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span>from</span><span>,</span><span> recipient</span><span>,</span><span> amount</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"> &quot;Supported Token Transfer Fail&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></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See {IERC165-supportsInterface}.</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"> 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"> ERC2981</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> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC6105</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Before transferring the NFT, need to delete listing</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _beforeTokenTransfer</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"> tokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> batchSize</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-variable z-language"> super</span><span>.</span><span class="z-entity z-name">_beforeTokenTransfer</span><span>(</span><span>from</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>,</span><span> batchSize</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-entity z-name">_isForSale</span><span>(</span><span>tokenId</span><span>)</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> _removeListing</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></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>The <code>buyItem</code> function, as well as the <code>acceptCollectionOffer</code> and <code>acceptItemOffer</code> functions, has a potential front-running risk. Must check that <code>salePrice</code> and <code>supportedToken</code> match the expected price and token to prevent front-running attacks</p> <p>There is a potential re-entrancy risk with the <code>acceptCollectionOffer</code> and <code>acceptItemOffer</code> functions. Make sure to obey the checks, effects, interactions pattern or use a reentrancy guard.</p> <p>If a buyer uses <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens to purchase an NFT, the buyer needs to first call the <code>approve(address spender, uint256 amount)</code> function of the ERC-20 token to grant the NFT contract access to a certain <code>amount</code> of tokens. Please make sure to authorize an appropriate <code>amount</code>. Furthermore, caution is advised when dealing with non-audited 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> 2022-11-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Alexhttps://github.com/Alex-Klasma Ben Fusekhttps://github.com/bfusek Daniel Fallon-Cyrhttps://github.com/dfalloncyr https://wg-eips.ritovision.com/6065/

An interface for real estate NFTs that extends ERC-721

<h2 id="abstract">Abstract</h2> <p>This proposal introduces an open structure for physical real estate and property to exist on the blockchain. This standard builds off of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, adding important functionality necessary for representing real world assets such as real estate. The three objectives this standard aims to meet are: universal transferability of the NFT, private property rights attached to the NFT, and atomic transfer of property rights with the transfer of the NFT. The token contains a hash of the operating agreement detailing the NFT holder’s legal right to the property, unique identifiers for the property, a debt value and foreclosure status, and a manager address.</p> <h2 id="motivation">Motivation</h2> <p>Real estate is the largest asset class in the world. By tokenizing real estate, barriers to entry are lowered, transaction costs are minimized, information asymmetry is reduced, ownership structures become more malleable, and a new building block for innovation is formed. However, in order to tokenize this asset class, a common standard is needed that accounts for its real world particularities while remaining flexible enough to adapt to various jurisdictions and regulatory environments.</p> <p>Ethereum tokens involving real world assets (RWAs) are notoriously tricky. This is because Ethereum tokens exist on-chain, while real estate exists off-chain. As such, the two are subject to entirely different consensus environments. For Ethereum tokens, consensus is reached through a formalized process of distributed validators. When a purely-digital NFT is transferred, the new owner has a cryptographic guarantee of ownership. For real estate, consensus is supported by legal contracts, property law, and enforced by the court system. With existing asset-backed ERC-721 tokens, a transfer of the token to another individual does not necessarily have any impact on the legal ownership of the physical asset.</p> <p>This standard attempts to solve the real world reconciliation issue, enabling real estate NFTs to function seamlessly on-chain, just like their purely-digital counterparts.</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>In order to meet the above objectives and create an open standard for on-chain property ownership we have created a token structure that builds on the widely-used ERC-721 standard.</p> <h3 id="token-components">Token Components:</h3> <ol> <li>Inherits ERC-721 - Allows for backwards compatibility with the most widely accepted NFT token standard.</li> <li>operatingAgreementHashOf - immutable hash of the legal agreement detailing the right to ownership and conditions of use with regard to the property</li> <li>Property Unique Identifiers - legal description (from physical deed), street address, GIS coordinates, parcel/tax ID, legal owning entity (on deed)</li> <li>debtOf - readable debt value, currency, and foreclosure status of the NFT</li> <li>managerOf - readable Ethereum address with managing control of property</li> </ol> <h3 id="interfaces">Interfaces</h3> <p>This EIP inherits the ERC-721 NFT token standard for all transfer and approval logic. All transfer and approval functions are inherited from this token standard without changes. Additionally, this EIP also inherits the ERC-721 Metadata standards for name, symbol, and metadata URI lookup. This allows an NFT under this EIP to become interoperable with preexisting NFT exchanges and services, however, some care must be taken. Please refer to <a href="https://wg-eips.ritovision.com/6065/#backwards-compatibility">Backwards Compatibility</a> and <a href="https://wg-eips.ritovision.com/6065/#security-considerations">Security Considerations</a>.</p> <h4 id="solidity-interface">Solidity Interface</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pragma solidity ^0.8.13;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>import &quot;forge-std/interfaces/IERC721.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>interface IERC6065 is IERC721 {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // This event MUST emit if the asset is ever foreclosed.</span></span> <span class="giallo-l"><span> event Foreclosed(uint256 id);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /* </span></span> <span class="giallo-l"><span> Next getter functions return immutable data for NFT.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function legalDescriptionOf(uint256 _id) external view returns (string memory);</span></span> <span class="giallo-l"><span> function addressOf(uint256 _id) external view returns (string memory);</span></span> <span class="giallo-l"><span> function geoJsonOf(uint256 _id) external view returns (string memory);</span></span> <span class="giallo-l"><span> function parcelIdOf(uint256 _id) external view returns (string memory);</span></span> <span class="giallo-l"><span> function legalOwnerOf(uint256 _id) external view returns (string memory);</span></span> <span class="giallo-l"><span> function operatingAgreementHashOf(uint256 _id) external view returns (bytes32);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /*</span></span> <span class="giallo-l"><span> Next getter function returns the debt denomination token of the NFT, the amount of debt (negative debt == credit), and if the underlying </span></span> <span class="giallo-l"><span> asset backing the NFT has been foreclosed on. This should be utilized specifically for off-chain debt and required payments on the RWA asset.</span></span> <span class="giallo-l"><span> It&#39;s recommended that administrators only use a single token type to denominate the debt. It&#39;s unrealistic to require integrating smart</span></span> <span class="giallo-l"><span> contracts to implement possibly unbounded tokens denominating the off-chain debt of an asset.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> If the foreclosed status == true, then the RWA can be seen as severed from the NFT. The NFT is now &quot;unbacked&quot; by the RWA.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function debtOf(uint256 _id) external view returns (address debtToken, int256 debtAmt, bool foreclosed);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Get the managerOf an NFT. The manager can have additional rights to the NFT or RWA on or off-chain.</span></span> <span class="giallo-l"><span> function managerOf(uint256 _id) external view returns (address);</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="introduction">Introduction</h3> <p>Real world assets operate in messy, non-deterministic environments. Because of this, validating the true state of an asset can be murky, expensive, or time-consuming. For example, in the U.S., change of property ownership is usually recorded at the County Recorder’s office, sometimes using pen and paper. It would be infeasible to continuously update this manual record every time an NFT transaction occurs on the blockchain. Additionally, since real world property rights are enforced by the court of law, it is essential that property ownership be documented in such a way that courts are able to interpret and enforce ownership if necessary.</p> <p>For these reasons, it is necessary to have a trusted party tasked with the responsibility of ensuring the state of the on-chain property NFT accurately mirrors its physical counterpart. By having an Administrator for the property who issues a legally-binding digital representation of the physical property, we are able to solve for both the atomic transfer of the property rights with the transfer of the NFT, as well as institute a seamless process for making the necessary payments and filings associated with property ownership. This is made possible by eliminating the change in legal ownership each time the NFT changes hands. An example Administrator legal structure implemented for property tokenization in the U.S. is provided in the <a href="https://wg-eips.ritovision.com/6065/#reference-implementation">Reference Implementation</a>. While a token that implements this standard must have a legal entity to conduct the off-chain dealings for the property, this implementation is not mandatory.</p> <h3 id="guiding-objectives">Guiding Objectives</h3> <p>We have designed this EIP to achieve three primary objectives necessary for creating an NFT representation of physical real estate:</p> <h4 id="1-real-estate-nfts-are-universally-transferable">1. Real Estate NFTs are universally transferable</h4> <p>A key aspect to private property is the right to transfer ownership to any legal person or entity that has the capacity to own that property. Therefore, an NFT representation of physical property should maintain that universal freedom of transfer.</p> <h4 id="2-all-rights-associated-with-property-ownership-are-able-to-be-maintained-and-guaranteed-by-the-nft">2. All rights associated with property ownership are able to be maintained and guaranteed by the NFT</h4> <p>The rights associated with private property ownership are the right to hold, occupy, rent, alter, resell, or transfer the property. It is essential that these same rights are able to be maintained and enforced with an NFT representation of real estate.</p> <h4 id="3-property-rights-are-transferred-atomically-with-the-transfer-of-the-nft">3. Property rights are transferred atomically with the transfer of the NFT</h4> <p>Token ownership on any blockchain is atomic with the transfer of the digital token. To ensure the digital representation of a physical property is able to fully integrate the benefits of blockchain technology, it is essential the rights associated with the property are passed atomically with the transfer of the digital token.</p> <p>The following section specifies the technological components required to meet these three objectives.</p> <h3 id="operatingagreementhashof">operatingAgreementHashOf</h3> <p>An immutable hash of the legal document issued by the legal entity that owns the property. The agreement is unique and contains the rights, terms, and conditions for the specific property represented by the NFT. The hash of the agreement attached to the NFT must be immutable to ensure the legitimacy and enforceability of these rights in the future for integrators or transferees. Upon transfer of the NFT, these legal rights are immediately enforceable by the new owner. For changes to the legal structure or rights and conditions with regard to the property the original token must be burned and a new token with the new hash must be minted.</p> <h3 id="property-unique-identifiers">Property Unique Identifiers</h3> <p>The following unique identifiers of the property are contained within the NFT and are immutable:</p> <p><code>legalDescriptionOf</code>: written description of the property taken from the physical property deed <code>addressOf</code>: street address of the property <code>geoJsonOf</code>: the GeoJSON format of the property’s geospatial coordinates <code>parcelIdOf</code>: ID number used to identify the property by the local authority <code>legalOwnerOf</code>: the legal entity that is named on the verifiable physical deed</p> <p>These unique identifiers ensure the physical property in question is clear and identifiable. These strings must be immutable to make certain that the identity of the property can not be changed in the future. This is necessary to provide confidence in the NFT holder in the event a dispute about the property arises.</p> <p>These identifiers, especially <code>legalOwnerOf</code>, allow for individuals to verify off-chain ownership and legitimacy of the legal agreement. These verification checks could be integrated with something like Chainlink functions in the future to be simplified and automatic.</p> <h3 id="debtof">debtOf</h3> <p>A readable value of debt and denoted currency that is accrued to the property. A positive balance signifies a debt against the property, while a negative balance signifies a credit which can be claimed by the NFT owner. This is a way for the property administrator to charge the NFT holder for any necessary payments towards the property, like property tax, or other critical repairs or maintenance in the "real world". A credit might be given to the NFT holder via this same function, perhaps the administrator and the NFT holder had worked out a property management or tenancy revenue-sharing agreement.</p> <p>The <code>debtOf</code> function also returns the boolean foreclosure status of the asset represented by the NFT. A true result indicates the associated property is no longer backing the NFT, a false result indicates the associated property is still backing the NFT. An administrator can foreclose an asset for any reason as specified in the <code>Operating Agreement</code>, an example would be excessive unpaid debts. Smart contracts can check the foreclosure state by calling this function. If the asset is foreclosed, it should be understood that the RWA backing the NFT has been removed, and smart contracts should take this into account when doing any valuations or other calculations.</p> <p>There are no standard requirements for how these values are updated as those details will be decided by the implementor. This EIP does however standardize how these values are indicated and read for simplicity of integration.</p> <h3 id="managerof">managerOf</h3> <p>A readable Ethereum address that can be granted a right to action on the property without being the underlying owner of the NFT.</p> <p>This function allows the token to be owned by one Ethereum address while granting particular rights to another. This enables protocols and smart contracts to own the underlying asset, such as a lending protocol, but still allow another Ethereum address, such as a depositor, to action on the NFT via other integrations, for example the Administrator management portal. The standard does not require a specific implementation of the manager role, only the value is required. In many instances the managerOf value will be the same as the owning address of the NFT.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is backwards compatible with ERC-721. However, it is important to note that there are potential implementation considerations to take into account before any smart contract integration. See <a href="https://wg-eips.ritovision.com/6065/#security-considerations">Security Considerations</a> for more details.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Klasma Labs offers a work in progress <a href="https://wg-eips.ritovision.com/6065/./assets/Implementation.sol">reference implementation</a>. The technical implementation includes the following additional components for reference, this implementation is not required.</p> <p>Summary of this implementation:</p> <ul> <li>NFT burn and mint function</li> <li>Immutable NFT data (unique identifiers and operating agreement hash)</li> <li>Simple debt tracking by Administrator</li> <li>Blocklist function to freeze asset held by fraudulent addresses (NOTE: to be implemented in the future)</li> <li>Simple foreclosure logic initiated by Administrator</li> <li><code>managerOf</code> function implementation to chain this call to other supported smart contracts</li> </ul> <h3 id="legal-structure-implementation">Legal Structure Implementation</h3> <p>This section explains the legal structure and implementation a company may employ as an Administrator of this token. The structure detailed below is specific to property tokenization in the U.S. in the 2023 regulatory environment.</p> <p>This section details an implementation of the legal standard that could be used by a company specifically for property tokenization in the U.S. in the 2022 regulatory environment.</p> <p><img src="https://wg-eips.ritovision.com/6065/./assets/corporate-structure.png" alt="Corporate Structure Image" /></p> <p>The legal structure for this token is as follows:</p> <ul> <li> <p>A parent company and property Administrator, owns a bankruptcy remote LLC for each individual property they act as Administrator for.</p> </li> <li> <p>The bankruptcy remote LLC is the owner and manager of a DAO LLC. The DAO LLC is on the title and deed and issues the corresponding NFT and operating agreement for the property.</p> </li> <li> <p>This structure enables the following three outcomes:</p> <ol> <li>Homeowners are shielded from any financial stress or bankruptcy their physical asset Administrator encounters. In the event of an Administrator bankruptcy or dissolution the owner of the NFT is entitled to transfer of the DAO LLC, or the sale and distribution of proceeds from the property.</li> <li>Transfer of the rights to the property are atomic with the transfer of the NFT. The NFT represents a right to claim the asset and have the title transferred to the NFT owner, as well as the right to use the asset. This ensures the rights to the physical property are passed digitally with the transfer of the NFT, without having to update the legal owner of the property after each transfer.</li> </ol> </li> </ul> <p>Security note: In the event of a private key hack the company will likely not be able to reissue a Home NFT. Home NFT owners who are not confident in their ability to safely store their home NFT will have varying levels of security options (multi-sigs, custodians, etc.). For public, large protocol hacks, the company may freeze the assets using the Blocklist function and reissue the home NFTs to the original owners. Blocklist functionality is to-be-implemented in the reference implementation above.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The following are checks and recommendations for protocols integrating NFTs under this standard. These are of particular relevance to applications which lend against any asset utilizing this standard.</p> <ul> <li>Protocol integrators are recommended to check that the unique identifiers for the property and the hash of the operating agreement are immutable for the specific NFTs they wish to integrate. For correct implementation of this standard these values must be immutable to ensure legitimacy for future transferees.</li> <li>Protocol integrators are recommended to check the debtOf value for an accurate representation of the value of this token.</li> <li>Protocol integrators are recommended to check the foreclose status to ensure this token is still backed by the asset it was originally tied to.</li> <li>For extra risk mitigation protocol integrators can implement a time-delay before performing irreversible actions. This is to protect against potential asset freezes if a hacked NFT is deposited into the protocol. Asset freezes are non-mandatory and subject to the implementation of the asset Administrator.</li> </ul> <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-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jack Boyuan Xuhttps://github.com/boyuanx https://wg-eips.ritovision.com/6066/

A way to verify signatures when the signing entity is an ERC-721 or ERC-1155 NFT

<h2 id="abstract">Abstract</h2> <p>While <strong>E</strong>xternally <strong>O</strong>wned <strong>A</strong>ccounts can validate signed messages with <code>ecrecover()</code> and smart contracts can validate signatures using specifications outlined in <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>, currently there is no standard method to create or validate signatures made by NFTs. We propose a standard way for anyone to validate whether a signature made by an NFT is valid. This is possible via a modified signature validation function originally found in <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>: <code>isValidSignature(tokenId, hash, data)</code>.</p> <h2 id="motivation">Motivation</h2> <p>With billions of ETH in trading volume, the <strong>N</strong>on-<strong>F</strong>ungible <strong>T</strong>oken standard has exploded into tremendous popularity in recent years. Despite the far-reaching implications of having unique tokenized items on-chain, NFTs have mainly been used to represent artwork in the form of avatars or profile pictures. While this is certainly not a trivial use case for the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> &amp; <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> token standards, we reckon more can be done to aid the community in discovering alternative uses for NFTs.</p> <p>One of the alternative use cases for NFTs is using them to represent offices in an organization. In this case, tying signatures to transferrable NFTs instead of EOAs or smart contracts becomes crucial. Suppose there exists a DAO that utilizes NFTs as badges that represent certain administrative offices (i.e., CEO, COO, CFO, etc.) with a quarterly democratic election that potentially replaces those who currently occupy said offices. If the sitting COO has previously signed agreements or authorized certain actions, their past signatures would stay with the EOA who used to be the COO instead of the COO's office itself once they are replaced with another EOA as the new COO-elect. Although a multisig wallet for the entire DAO is one way to mitigate this problem, often it is helpful to generate signatures on a more intricate level so detailed separation of responsibilities are established and maintained. It is also feasible to appoint a smart contract instead of an EOA as the COO, but the complexities this solution brings are unnecessary. If a DAO uses ENS to establish their organizational hierarchy, this proposal would allow wrapped ENS subdomains (which are NFTs) to generate signatures.</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> <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 IERC6066 {</span></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev MUST return if the signature provided is valid for the provided tokenId and hash</span></span> <span class="giallo-l"><span> * @param tokenId Token ID of the signing NFT</span></span> <span class="giallo-l"><span> * @param hash Hash of the data to be signed</span></span> <span class="giallo-l"><span> * @param data OPTIONAL arbitrary data that may aid verification</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * MUST return the bytes4 magic value 0x12edb34f when function passes.</span></span> <span class="giallo-l"><span> * MUST NOT modify state (using STATICCALL for solc &lt; 0.5, view modifier for solc &gt; 0.5)</span></span> <span class="giallo-l"><span> * MUST allow external calls</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function isValidSignature(</span></span> <span class="giallo-l"><span> uint256 tokenId,</span></span> <span class="giallo-l"><span> bytes32 hash,</span></span> <span class="giallo-l"><span> bytes calldata data</span></span> <span class="giallo-l"><span> ) external view returns (bytes4 magicValue);</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>isValidSignature</code> can call arbitrary methods to validate a given signature.</p> <p>This function MAY be implemented by <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> compliant contracts that desire to enable its token holders to sign messages using their NFTs. Compliant callers wanting to support contract signatures MUST call this method if the signer is the holder of an NFT (<a href="https://wg-eips.ritovision.com/721/">ERC-721</a> or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>).</p> <h2 id="rationale">Rationale</h2> <p>We have purposefully decided to not include a signature generation standard in this proposal as it would restrict flexibility of such mechanism, just as <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> does not enforce a signing standard for smart contracts. We also decided to reference Gnosis Safe's contract signing approach as it is both simplistic and proven to be adequate. The <code>bytes calldata data</code> parameter is considered optional if extra data is needed for signature verification, also conforming this EIP to <a href="https://wg-eips.ritovision.com/5750/">ERC-5750</a> for future-proofing purposes.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is incompatible with previous work on signature validation as it does not validate any cryptographically generated signatures. Instead, signature is merely a boolean flag indicating consent. This is consistent with Gnosis Safe's contract signature implementation.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Example implementation of an <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> compliant contract that conforms to <a href="https://wg-eips.ritovision.com/6066/">ERC-6066</a> with a custom signing function:</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>import &quot;@openzeppelin/contracts/token/ERC721/ERC721.sol&quot;;</span></span> <span class="giallo-l"><span>import &quot;./interfaces/IERC6066.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>contract ERC6066Reference is ERC721, IERC6066 {</span></span> <span class="giallo-l"><span> // type(IERC6066).interfaceId</span></span> <span class="giallo-l"><span> bytes4 public constant MAGICVALUE = 0x12edb34f;</span></span> <span class="giallo-l"><span> bytes4 public constant BADVALUE = 0xffffffff;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> mapping(uint256 =&gt; mapping(bytes32 =&gt; bool)) internal _signatures;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> error ENotTokenOwner();</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Checks if the sender owns NFT with ID tokenId</span></span> <span class="giallo-l"><span> * @param tokenId Token ID of the signing NFT</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> modifier onlyTokenOwner(uint256 tokenId) {</span></span> <span class="giallo-l"><span> if (ownerOf(tokenId) != _msgSender()) revert ENotTokenOwner();</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> constructor(string memory name_, string memory symbol_)</span></span> <span class="giallo-l"><span> ERC721(name_, symbol_)</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> * @dev SHOULD sign the provided hash with NFT of tokenId given sender owns said NFT</span></span> <span class="giallo-l"><span> * @param tokenId Token ID of the signing NFT</span></span> <span class="giallo-l"><span> * @param hash Hash of the data to be signed</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function sign(uint256 tokenId, bytes32 hash)</span></span> <span class="giallo-l"><span> external</span></span> <span class="giallo-l"><span> onlyTokenOwner(tokenId)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> _signatures[tokenId][hash] = 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> * @dev MUST return if the signature provided is valid for the provided tokenId, hash, and optionally data</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function isValidSignature(uint256 tokenId, bytes32 hash, bytes calldata data)</span></span> <span class="giallo-l"><span> external</span></span> <span class="giallo-l"><span> view</span></span> <span class="giallo-l"><span> override</span></span> <span class="giallo-l"><span> returns (bytes4 magicValue)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> // The data parameter is unused in this example</span></span> <span class="giallo-l"><span> return _signatures[tokenId][hash] ? MAGICVALUE : BADVALUE;</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> * @dev ERC-165 support</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function supportsInterface(</span></span> <span class="giallo-l"><span> bytes4 interfaceId</span></span> <span class="giallo-l"><span> ) public view virtual override returns (bool) {</span></span> <span class="giallo-l"><span> return</span></span> <span class="giallo-l"><span> interfaceId == type(IERC6066).interfaceId ||</span></span> <span class="giallo-l"><span> super.supportsInterface(interfaceId);</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 revokable nature of contract-based signatures carries over to this EIP. Developers and users alike should take it into consideration.</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:48:25+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv https://wg-eips.ritovision.com/5982/

An interface for role-based access control for smart contracts.

<h2 id="abstract">Abstract</h2> <p>This EIP defines an interface for role-based access control for smart contracts. Roles are defined as <code>byte32</code>. The interface specifies how to read, grant, create and destroy roles. It specifies the sense of role power in the format of its ability to call a given method identified by <code>bytes4</code> method selector. It also specifies how metadata of roles are represented.</p> <h2 id="motivation">Motivation</h2> <p>There are many ways to establish access control for privileged actions. One common pattern is "role-based" access control, where one or more users are assigned to one or more "roles," which grant access to privileged actions. This pattern is more secure and flexible than ownership-based access control since it allows for many people to be granted permissions according to the principle of least privilege.</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>Interfaces of reference is described as followed:</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"> IERC_ACL_CORE</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hasRole</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> role</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">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"> grantRole</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> role</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>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeRole</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> role</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>;</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-storage z-type">interface</span><span class="z-entity z-name"> IERC_ACL_GENERAL</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RoleGranted</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> grantor</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> role</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> grantee</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"> RoleRevoked</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">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> role</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> revokee</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"> RoleCreated</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> roleGrantor</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> role</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> adminOfRole</span><span>, </span><span class="z-support">string</span><span class="z-variable"> name</span><span>, </span><span class="z-support">string</span><span class="z-variable"> desc</span><span>, </span><span class="z-support">string</span><span class="z-variable"> uri</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> calldata</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"> RoleDestroyed</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> roleDestroyer</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> role</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> calldata</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"> RolePowerSet</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> rolePowerSetter</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> role</span><span>, </span><span class="z-support">bytes4</span><span class="z-variable"> methods</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> calldata</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"> grantRole</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> role</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> account</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>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeRole</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> role</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> account</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>;</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"> createRole</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> role</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> adminOfRole</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> name</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> desc</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> uri</span><span>,</span><span class="z-support"> bytes32</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>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> destroyRole</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> role</span><span>,</span><span class="z-support"> bytes32</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>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setRolePower</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> role</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable"> methods</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"> 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>)</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"> hasRole</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> role</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> account</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"> 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"> canGrantRole</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> grantor</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> grantee</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"> 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>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canRevokeRole</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> revoker</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revokee</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> account</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"> 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>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canExecute</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> executor</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable"> methods</span><span>,</span><span class="z-support"> bytes32</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> payload</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"> 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>)</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-storage z-type">interface</span><span class="z-entity z-name"> IERC_ACL_METADATA</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> roleName</span><span>(</span><span class="z-support">bytes32</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 class="z-storage z-type"> function</span><span class="z-entity z-name"> roleDescription</span><span>(</span><span class="z-support">bytes32</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 class="z-storage z-type"> function</span><span class="z-entity z-name"> roleURI</span><span>(</span><span class="z-support">bytes32</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> <ol> <li>Compliant contracts MUST implement <code>IERC_ACL_CORE</code></li> <li>It is RECOMMENDED for compliant contracts to implement the optional extension <code>IERC_ACL_GENERAL</code>.</li> <li>Compliant contracts MAY implement the optional extension <code>IERC_ACL_METADATA</code>.</li> <li>A role in a compliant smart contract is represented in the format of <code>bytes32</code>. It's RECOMMENDED the value of such role is computed as a <code>keccak256</code> hash of a string of the role name, in this format: <code>bytes32 role = keccak256("&lt;role_name&gt;")</code>. such as <code>bytes32 role = keccak256("MINTER")</code>.</li> <li>Compliant contracts SHOULD implement <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> identifier.</li> </ol> <h2 id="rationale">Rationale</h2> <ol> <li>The names and parameters of methods in <code>IERC_ACL_CORE</code> are chosen to allow backward compatibility with OpenZeppelin's implementation.</li> <li>The methods in <code>IERC_ACL_GENERAL</code> conform to <a href="https://wg-eips.ritovision.com/5750/">ERC-5750</a> to allow extension.</li> <li>The method of <code>renounceRole</code> was not adopted, consolidating with <code>revokeRole</code> to simplify interface.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Needs discussion.</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-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-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Bruno Škvorchttps://github.com/Swader Cicadahttps://github.com/CicadaNCR Steven Pinedahttps://github.com/steven2308 Stevan Bogosavljevichttps://github.com/stevyhacker Jan Turkhttps://github.com/ThunderDeliverer https://wg-eips.ritovision.com/6059/

An interface for Nestable Non-Fungible Tokens with emphasis on parent token's control over the relationship.

<h2 id="abstract">Abstract</h2> <p>The Parent-Governed Nestable NFT standard extends <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> by allowing for a new inter-NFT relationship and interaction.</p> <p>At its core, the idea behind the proposal is simple: the owner of an NFT does not have to be an Externally Owned Account (EOA) or a smart contract, it can also be an NFT.</p> <p>The process of nesting an NFT into another is functionally identical to sending it to another user. The process of sending a token out of another one involves issuing a transaction from the account owning the parent token.</p> <p>An NFT can be owned by a single other NFT, but can in turn have a number of NFTs that it owns. This proposal establishes the framework for the parent-child relationships of NFTs. A parent token is the one that owns another token. A child token is a token that is owned by another token. A token can be both a parent and child at the same time. Child tokens of a given token can be fully managed by the parent token's owner, but can be proposed by anyone.</p> <p><img src="https://wg-eips.ritovision.com/6059/./assets/img/eip-6059-nestable-tokens.png" alt="Nestable tokens" /></p> <p>The graph illustrates how a child token can also be a parent token, but both are still administered by the root parent token's owner.</p> <h2 id="motivation">Motivation</h2> <p>With NFTs being a widespread form of tokens in the Ethereum ecosystem and being used for a variety of use cases, it is time to standardize additional utility for them. Having the ability for tokens to own other tokens allows for greater utility, usability and forward compatibility.</p> <p>In the four years since <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> was published, the need for additional functionality has resulted in countless extensions. This ERC improves upon ERC-721 in the following areas:</p> <ul> <li><a href="https://wg-eips.ritovision.com/6059/#bundling">Bundling</a></li> <li><a href="https://wg-eips.ritovision.com/6059/#collecting">Collecting</a></li> <li><a href="https://wg-eips.ritovision.com/6059/#membership">Membership</a></li> <li><a href="https://wg-eips.ritovision.com/6059/#delegation">Delegation</a></li> </ul> <h3 id="bundling">Bundling</h3> <p>One of the most frequent uses of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> is to disseminate the multimedia content that is tied to the tokens. In the event that someone wants to offer a bundle of NFTs from various collections, there is currently no easy way of bundling all of these together and handle their sale as a single transaction. This proposal introduces a standardized way of doing so. Nesting all of the tokens into a simple bundle and selling that bundle would transfer the control of all of the tokens to the buyer in a single transaction.</p> <h3 id="collecting">Collecting</h3> <p>A lot of NFT consumers collect them based on countless criteria. Some aim for utility of the tokens, some for the uniqueness, some for the visual appeal, etc. There is no standardized way to group the NFTs tied to a specific account. By nesting NFTs based on their owner's preference, this proposal introduces the ability to do it. The root parent token could represent a certain group of tokens and all of the children nested into it would belong to it.</p> <p>The rise of soulbound, non-transferable, tokens, introduces another need for this proposal. Having a token with multiple soulbound traits (child tokens), allows for numerous use cases. One concrete example of this can be drawn from supply chains use case. A shipping container, represented by an NFT with its own traits, could have multiple child tokens denoting each leg of its journey.</p> <h3 id="membership">Membership</h3> <p>A common utility attached to NFTs is a membership to a Decentralised Autonomous Organization (DAO) or to some other closed-access group. Some of these organizations and groups occasionally mint NFTs to the current holders of the membership NFTs. With the ability to nest mint a token into a token, such minting could be simplified, by simply minting the bonus NFT directly into the membership one.</p> <h3 id="delegation">Delegation</h3> <p>One of the core features of DAOs is voting and there are various approaches to it. One such mechanic is using fungible voting tokens where members can delegate their votes by sending these tokens to another member. Using this proposal, delegated voting could be handled by nesting your voting NFT into the one you are delegating your votes to and transferring it when the member no longer wishes to delegate their votes.</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-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> EIP-6059 Parent-Governed Nestable Non-Fungible Tokens</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-6059</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 ERC-165 identifier for this interface is 0x42b0e56f.</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.16</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"> IERC6059</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">@notice</span><span class="z-comment"> The core struct of ownership.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The `DirectOwner` struct is used to store information of the next immediate owner, be it the parent token,</span></span> <span class="giallo-l"><span class="z-comment"> * an `ERC721Receiver` contract or an externally owned account.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If the token is not owned by an NFT, the `tokenId` MUST equal `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"> ID of the parent 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"> ownerAddress</span><span class="z-comment"> Address of the owner of the token. If the owner is another token, then the address MUST be</span></span> <span class="giallo-l"><span class="z-comment"> * the one of the parent token&#39;s collection smart contract. If the owner is externally owned account, the address</span></span> <span class="giallo-l"><span class="z-comment"> * MUST be the address of this account</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"> DirectOwner</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 class="z-support"> address</span><span> ownerAddress</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"> Used to notify listeners that the token is being transferred.</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 transferred from `from` 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"> Address of the previous immediate owner, which is a smart contract if the token was nested.</span></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 of the new immediate owner, which is a smart contract if the token is being nested.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> fromTokenId</span><span class="z-comment"> ID of the previous parent token. If the token was not nested before, the value 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"> toTokenId</span><span class="z-comment"> ID of the new parent token. If the token is not being nested, the value 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"> tokenId</span><span class="z-comment"> ID of the token being transferred</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"> NestTransfer</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"> fromTokenId</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"> 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"> Used to notify listeners that a new token has been added to a given token&#39;s pending children array.</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 child NFT is added to a token&#39;s pending 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"> tokenId</span><span class="z-comment"> ID of the token that received a new pending child 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"> childIndex</span><span class="z-comment"> Index of the proposed child token in the parent token&#39;s pending children 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"> childAddress</span><span class="z-comment"> Address of the proposed child token&#39;s collection smart 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"> childId</span><span class="z-comment"> ID of the child token in the child token&#39;s collection smart 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"> ChildProposed</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"> childIndex</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"> childAddress</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"> childId</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"> Used to notify listeners that a new child token was accepted by the parent token.</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 parent token accepts a token from its pending array, migrating it to the active 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"> tokenId</span><span class="z-comment"> ID of the token that accepted a new child 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"> childIndex</span><span class="z-comment"> Index of the newly accepted child token in the parent token&#39;s active children 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"> childAddress</span><span class="z-comment"> Address of the child token&#39;s collection smart 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"> childId</span><span class="z-comment"> ID of the child token in the child token&#39;s collection smart 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"> ChildAccepted</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"> childIndex</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"> childAddress</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"> childId</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"> Used to notify listeners that all pending child tokens of a given token have been rejected.</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 removes all a child tokens from its pending 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"> tokenId</span><span class="z-comment"> ID of the token that rejected all of the pending children</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"> AllChildrenRejected</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">@notice</span><span class="z-comment"> Used to notify listeners a child token has been transferred from parent token.</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 transfers a child from itself, transferring ownership.</span></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 token that transferred a child 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"> childIndex</span><span class="z-comment"> Index of a child in the array from which it is being transferred</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> childAddress</span><span class="z-comment"> Address of the child token&#39;s collection smart 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"> childId</span><span class="z-comment"> ID of the child token in the child token&#39;s collection smart 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"> fromPending</span><span class="z-comment"> A boolean value signifying whether the token was in the pending child tokens array (`true`) or</span></span> <span class="giallo-l"><span class="z-comment"> * in the active child tokens array (`false`)</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"> ChildTransferred</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"> childIndex</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"> childAddress</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"> childId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> fromPending</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"> The core child token struct, holding the information about the child 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"> tokenId</span><span class="z-comment"> ID of the child token in the child token&#39;s collection smart 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"> contractAddress</span><span class="z-comment"> Address of the child token&#39;s smart 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"> Child</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 class="z-support"> address</span><span> contractAddress</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"> Used to retrieve the *root* owner of a given token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The *root* owner of the token is the top-level owner in the hierarchy which is not 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"> If the token is owned by another NFT, it MUST recursively look up the parent&#39;s root 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"> ID of the token for which the *root* owner has been retrieved</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"> owner</span><span class="z-comment"> The *root* owner of 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"> 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 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"> Used to retrieve the immediate owner of the given token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If the immediate owner is another token, the address returned, MUST be the one of the parent token&#39;s</span></span> <span class="giallo-l"><span class="z-comment"> * collection smart 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"> tokenId</span><span class="z-comment"> ID of the token for which the direct owner is being retrieved</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"> Address of the given token&#39;s 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"> uint256</span><span class="z-comment"> The ID of the parent token. MUST be `0` if the owner is not 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"> bool</span><span class="z-comment"> The boolean value signifying whether the owner is an NFT or 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"> directOwnerOf</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> <span class="giallo-l"><span class="z-support"> address</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</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"> Used to burn a given token.</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 token is burned, all of its child tokens are recursively burned as well.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> When specifying the maximum recursive burns, the execution MUST be reverted if there are more children to be</span></span> <span class="giallo-l"><span class="z-comment"> * burned.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Setting the `maxRecursiveBurn` value to 0 SHOULD only attempt to burn the specified token and MUST revert if</span></span> <span class="giallo-l"><span class="z-comment"> * there are any child tokens 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"> tokenId</span><span class="z-comment"> ID of the token to burn</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> maxRecursiveBurns</span><span class="z-comment"> Maximum number of tokens to recursively burn</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"> Number of recursively burned children</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 class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> maxRecursiveBurns</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">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"> Used to add a child token to a given parent token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This adds the child token into the given parent token&#39;s pending child tokens array.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The destination token MUST NOT be a child token of the token being transferred or one of its downstream</span></span> <span class="giallo-l"><span class="z-comment"> * child tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This method MUST NOT be called directly. It MUST only be called from an instance of `IERC6059` as part of a </span></span> <span class="giallo-l"><span class="z-comment"> `nestTransfer` or `transferChild` to 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"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - `directOwnerOf` on the child contract MUST resolve to the called contract.</span></span> <span class="giallo-l"><span class="z-comment"> * - the pending array of the parent contract MUST not be full.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> parentId</span><span class="z-comment"> ID of the parent token to receive the new child 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"> childId</span><span class="z-comment"> ID of the new proposed child 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"> addChild</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parentId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> childId</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"> Used to accept a pending child token for a given parent token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This moves the child token from parent token&#39;s pending child tokens array into the active child tokens</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> parentId</span><span class="z-comment"> ID of the parent token for which the child token is being accepted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> childIndex</span><span class="z-comment"> Index of the child token to accept in the pending children array of a given 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"> childAddress</span><span class="z-comment"> Address of the collection smart contract of the child token expected to be at the specified</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> childId</span><span class="z-comment"> ID of the child token expected to be located at the specified index</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"> acceptChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> parentId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> childIndex</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> childAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> childId</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"> Used to reject all pending children of a given parent token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Removes the children from the pending array mapping.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The children&#39;s ownership structures are not updated.</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"> * - `parentId` MUST 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"> parentId</span><span class="z-comment"> ID of the parent token for which to reject all of the pending 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"> maxRejections</span><span class="z-comment"> Maximum number of expected children to reject, used to prevent from</span></span> <span class="giallo-l"><span class="z-comment"> * rejecting children which arrive just before this operation.</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"> rejectAllChildren</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parentId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> maxRejections</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"> Used to transfer a child token from a given parent token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST remove the child from the parent&#39;s active or pending children.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> When transferring a child token, the owner of the token MUST be set to `to`, or not updated in the event of `to`</span></span> <span class="giallo-l"><span class="z-comment"> * being the `0x0` 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"> ID of the parent token from which the child token is being transferred</span></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 to which to transfer the token 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"> destinationId</span><span class="z-comment"> ID of the token to receive this child token (MUST be 0 if the destination is not 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"> childIndex</span><span class="z-comment"> Index of a token we are transferring, in the array it belongs to (can be either active array or</span></span> <span class="giallo-l"><span class="z-comment"> * pending 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"> childAddress</span><span class="z-comment"> Address of the child token&#39;s collection smart 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"> childId</span><span class="z-comment"> ID of the child token in its own collection smart 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"> isPending</span><span class="z-comment"> A boolean value indicating whether the child token being transferred is in the pending array of the</span></span> <span class="giallo-l"><span class="z-comment"> * parent token (`true`) or in the active array (`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"> data</span><span class="z-comment"> Additional data with no specified format, sent in call to `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"> transferChild</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-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> destinationId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> childIndex</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> childAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> childId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> isPending</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 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"> Used to retrieve the active child tokens of a given parent token.</span></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 Child structs existing for parent token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The Child struct consists of the following values:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * tokenId,</span></span> <span class="giallo-l"><span class="z-comment"> * contractAddress</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"> parentId</span><span class="z-comment"> ID of the parent token for which to retrieve the active child 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"> struct</span><span class="z-comment">[] An array of Child structs containing the parent token&#39;s active child 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"> childrenOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parentId</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">Child</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to retrieve the pending child tokens of a given parent token.</span></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 pending Child structs existing for given parent.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The Child struct consists of the following values:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * tokenId,</span></span> <span class="giallo-l"><span class="z-comment"> * contractAddress</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"> parentId</span><span class="z-comment"> ID of the parent token for which to retrieve the pending child 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"> struct</span><span class="z-comment">[] An array of Child structs containing the parent token&#39;s pending child 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"> pendingChildrenOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parentId</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">Child</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to retrieve a specific active child token for a given parent token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns a single Child struct locating at `index` of parent token&#39;s active child tokens array.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The Child struct consists of the following values:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * tokenId,</span></span> <span class="giallo-l"><span class="z-comment"> * contractAddress</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"> parentId</span><span class="z-comment"> ID of the parent token for which the child is being retrieved</span></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 child token in the parent token&#39;s active child tokens 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"> struct</span><span class="z-comment"> A Child struct containing data about the specified child</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"> childOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parentId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> index</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">Child</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to retrieve a specific pending child token from a given parent token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns a single Child struct locating at `index` of parent token&#39;s active child tokens array.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The Child struct consists of the following values:</span></span> <span class="giallo-l"><span class="z-comment"> * [</span></span> <span class="giallo-l"><span class="z-comment"> * tokenId,</span></span> <span class="giallo-l"><span class="z-comment"> * contractAddress</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"> parentId</span><span class="z-comment"> ID of the parent token for which the pending child token is being retrieved</span></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 child token in the parent token&#39;s pending child tokens 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"> struct</span><span class="z-comment"> A Child struct containing data about the specified child</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"> pendingChildOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> parentId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> index</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">Child</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to transfer the token into another token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The destination token MUST NOT be a child token of the token being transferred or one of its downstream</span></span> <span class="giallo-l"><span class="z-comment"> * child 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"> from</span><span class="z-comment"> Address of the direct owner of the token to be transferred</span></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 of the receiving token&#39;s collection smart 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"> tokenId</span><span class="z-comment"> ID of the token being transferred</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> destinationId</span><span class="z-comment"> ID of the token to receive the token being transferred</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"> nestTransferFrom</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></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> destinationId</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> <p>ID MUST never be a <code>0</code> value, as this proposal uses <code>0</code> values do signify that the token/destination is not an NFT.</p> <h2 id="rationale">Rationale</h2> <p>Designing the proposal, we considered the following questions:</p> <ol> <li><strong>How to name the proposal?</strong><br /> In an effort to provide as much information about the proposal we identified the most important aspect of the proposal; the parent centered control over nesting. The child token's role is only to be able to be <code>Nestable</code> and support a token owning it. This is how we landed on the <code>Parent-Centered</code> part of the title.</li> <li><strong>Why is automatically accepting a child using <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> permit-style signatures not a part of this proposal?</strong><br /> For consistency. This proposal extends ERC-721 which already uses 1 transaction for approving operations with tokens. It would be inconsistent to have this and also support signing messages for operations with assets.</li> <li><strong>Why use indexes?</strong><br /> To reduce the gas consumption. If the token ID was used to find which token to accept or reject, iteration over arrays would be required and the cost of the operation would depend on the size of the active or pending children arrays. With the index, the cost is fixed. Lists of active and pending children per token need to be maintained, since methods to get them are part of the proposed interface.<br /> To avoid race conditions in which the index of a token changes, the expected token ID as well as the expected token's collection smart contract is included in operations requiring token index, to verify that the token being accessed using the index is the expected one.<br /> Implementation that would internally keep track of indices using mapping was attempted. The minimum cost of accepting a child token was increased by over 20% and the cost of minting has increased by over 15%. We concluded that it is not necessary for this proposal and can be implemented as an extension for use cases willing to accept the increased transaction cost this incurs. In the sample implementation provided, there are several hooks which make this possible.</li> <li><strong>Why is the pending children array limited instead of supporting pagination?</strong><br /> The pending child tokens array is not meant to be a buffer to collect the tokens that the root owner of the parent token wants to keep, but not enough to promote them to active children. It is meant to be an easily traversable list of child token candidates and should be regularly maintained; by either accepting or rejecting proposed child tokens. There is also no need for the pending child tokens array to be unbounded, because active child tokens array is.<br /> Another benefit of having bounded child tokens array is to guard against spam and griefing. As minting malicious or spam tokens could be relatively easy and low-cost, the bounded pending array assures that all of the tokens in it are easy to identify and that legitimate tokens are not lost in a flood of spam tokens, if one occurs.<br /> A consideration tied to this issue was also how to make sure, that a legitimate token is not accidentally rejected when clearing the pending child tokens array. We added the maximum pending children to reject argument to the clear pending child tokens array call. This assures that only the intended number of pending child tokens is rejected and if a new token is added to the pending child tokens array during the course of preparing such call and executing it, the clearing of this array SHOULD result in a reverted transaction.</li> <li><strong>Should we allow tokens to be nested into one of its children?</strong><br /> The proposal enforces that a parent token can't be nested into one of its child token, or downstream child tokens for that matter. A parent token and its children are all managed by the parent token's root owner. This means that if a token would be nested into one of its children, this would create the ownership loop and none of the tokens within the loop could be managed anymore.</li> <li><strong>Why is there not a "safe" nest transfer method?</strong><br /> <code>nestTransfer</code> is always "safe" since it MUST check for <code>IERC6059</code> compatibility on the destination.</li> <li><strong>How does this proposal differ from the other proposals trying to address a similar problem?</strong><br /> This interface allows for tokens to both be sent to and receive other tokens. The propose-accept and parent governed patterns allow for a more secure use. The backward compatibility is only added for ERC-721, allowing for a simpler interface. The proposal also allows for different collections to inter-operate, meaning that nesting is not locked to a single smart contract, but can be executed between completely separate NFT collections.</li> </ol> <h3 id="propose-commit-pattern-for-child-token-management">Propose-Commit pattern for child token management</h3> <p>Adding child tokens to a parent token MUST be done in the form of propose-commit pattern to allow for limited mutability by a 3rd party. When adding a child token to a parent token, it is first placed in a <em>"Pending"</em> array, and MUST be migrated to the <em>"Active"</em> array by the parent token's root owner. The <em>"Pending"</em> child tokens array SHOULD be limited to 128 slots to prevent spam and griefing.</p> <p>The limitation that only the root owner can accept the child tokens also introduces a trust inherent to the proposal. This ensures that the root owner of the token has full control over the token. No one can force the user to accept a child if they don't want to.</p> <h3 id="parent-governed-pattern">Parent Governed pattern</h3> <p>The parent NFT of a nested token and the parent's root owner are in all aspects the true owners of it. Once you send a token to another one you give up ownership.</p> <p>We continue to use ERC-721's <code>ownerOf</code> functionality which will now recursively look up through parents until it finds an address which is not an NFT, this is referred to as the <em>root owner</em>. Additionally we provide the <code>directOwnerOf</code> which returns the most immediate owner of a token using 3 values: the owner address, the tokenId which MUST be 0 if the direct owner is not an NFT, and a flag indicating whether or not the parent is an NFT.</p> <p>The root owner or an approved party MUST be able do the following operations on children: <code>acceptChild</code>, <code>rejectAllChildren</code> and <code>transferChild</code>.</p> <p>The root owner or an approved party MUST also be allowed to do these operations only when token is not owned by an NFT: <code>transferFrom</code>, <code>safeTransferFrom</code>, <code>nestTransferFrom</code>, <code>burn</code>.</p> <p>If the token is owned by an NFT, only the parent NFT itself MUST be allowed to execute the operations listed above. Transfers MUST be done from the parent token, using <code>transferChild</code>, this method in turn SHOULD call <code>nestTransferFrom</code> or <code>safeTransferFrom</code> in the child token's smart contract, according to whether the destination is an NFT or not. For burning, tokens must first be transferred to an EOA and then burned.</p> <p>We add this restriction to prevent inconsistencies on parent contracts, since only the <code>transferChild</code> method takes care of removing the child from the parent when it is being transferred out of it.</p> <h3 id="child-token-management">Child token management</h3> <p>This proposal introduces a number of child token management functions. In addition to the permissioned migration from <em>"Pending"</em> to <em>"Active"</em> child tokens array, the main token management function from this proposal is the <code>tranferChild</code> function. The following state transitions of a child token are available with it:</p> <ol> <li>Reject child token</li> <li>Abandon child token</li> <li>Unnest child token</li> <li>Transfer the child token to an EOA or an <code>ERC721Receiver</code></li> <li>Transfer the child token into a new parent token</li> </ol> <p>To better understand how these state transitions are achieved, we have to look at the available parameters passed to <code>transferChild</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"> transferChild</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-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> destinationId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> childIndex</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> childAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> childId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> isPending</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 class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Based on the desired state transitions, the values of these parameters have to be set accordingly (any parameters not set in the following examples depend on the child token being managed):</p> <ol> <li><strong>Reject child token</strong><br /> <img src="https://wg-eips.ritovision.com/6059/./assets/img/eip-6059-reject-child.png" alt="Reject child token" /></li> <li><strong>Abandon child token</strong><br /> <img src="https://wg-eips.ritovision.com/6059/./assets/img/eip-6059-abandon-child.png" alt="Abandon child token" /></li> <li><strong>Unnest child token</strong><br /> <img src="https://wg-eips.ritovision.com/6059/./assets/img/eip-6059-unnest-child.png" alt="Unnest child token" /></li> <li><strong>Transfer the child token to an EOA or an <code>ERC721Receiver</code></strong><br /> <img src="https://wg-eips.ritovision.com/6059/./assets/img/eip-6059-transfer-child-to-eoa.png" alt="Transfer child token to EOA" /></li> <li><strong>Transfer the child token into a new parent token</strong><br /> <img src="https://wg-eips.ritovision.com/6059/./assets/img/eip-6059-transfer-child-to-token.png" alt="Transfer child token to parent token" /><br /> This state change places the token in the pending array of the new parent token. The child token still needs to be accepted by the new parent token's root owner in order to be placed into the active array of that token.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The Nestable token standard has been made compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> in order to take advantage of the robust tooling available for implementations of ERC-721 and to ensure compatibility with existing ERC-721 infrastructure.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests are included in <a href="https://wg-eips.ritovision.com/6059/./assets/test/nestable.ts"><code>nestable.ts</code></a>.</p> <p>To run them in terminal, you can use the following commands:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cd ../assets/eip-6059</span></span> <span class="giallo-l"><span>npm install</span></span> <span class="giallo-l"><span>npx hardhat test</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/6059/./assets/contracts/NestableToken.sol"><code>NestableToken.sol</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The same security considerations as with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> apply: hidden logic may be present in any of the functions, including burn, add child, accept child, and more.</p> <p>Since the current owner of the token is allowed to manage the token, there is a possibility that after the parent token is listed for sale, the seller might remove a child token just before before the sale and thus the buyer would not receive the expected child token. This is a risk that is inherent to the design of this standard. Marketplaces should take this into account and provide a way to verify the expected child tokens are present when the parent token is being sold or to guard against such a malicious behaviour in another way.</p> <p>Caution is advised when dealing with non-audited 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> 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:49:27+00:00 Marius van der Wijdenhttps://github.com/MariusVanDerWijden https://wg-eips.ritovision.com/5793/

Adds the transaction type and transaction size to tx announcement messages in the wire protocol

<h2 id="abstract">Abstract</h2> <p>The Ethereum Wire Protocol defines request and response messages for exchanging data between clients. The <code>NewPooledTransactionHashes</code> message announces transactions available in the node. This EIP extends this announcement message such that beside the transaction hashes, the node sends the transaction types and their sizes (as defined in <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a>) as well.</p> <h2 id="motivation">Motivation</h2> <p>The <code>NewPooledTransactionHashes</code> message announces transaction hashes, allowing the peer to selectively fetch transactions it does not yet have.</p> <p><a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> introduces a new transaction type for blob transactions. Since these blob transactions are large, naively broadcasting them to <code>sqrt(peers)</code> could significantly increase bandwidth requirements. Adding the transaction type and the size to the announcement message will allow nodes to select which transactions they want to fetch and also allow them to load balance or throttle peers based on past behavior.</p> <p>The added metadata fields will also enable future - upgradeless - protocol tweaks to prevent certain transaction type (e.g. blob transactions) or certain transaction sizes (e.g. 128KB+) from being blindly broadcast to many peers. Enforcing announcements only and retrieval on demand would ensure a much more predictable networking behavior, limiting the amplification effect of transaction propagation DoS attack.</p> <h2 id="specification">Specification</h2> <p>Modify the <code>NewPooledTransactionHashes (0x08)</code> message:</p> <ul> <li><strong>(eth/67)</strong>: <code>[hash_0: B_32, hash_1: B_32, ...]</code></li> <li><strong>(eth/68)</strong>: <code>[types: B, [size_0: P, size_1: P, ...], [hash_0: B_32, hash_1: B_32, ...]]</code></li> </ul> <p>The new <code>types</code> element refers to the transaction types of the announced hashes. Note the transaction types are packed as a 'byte array' instead of a list.</p> <p>The <code>size_0</code>, <code>size_1</code> etc. elements refer to the transaction sizes of the announced hashes.</p> <h2 id="rationale">Rationale</h2> <p>This change will make the <code>eth</code> protocol future-proof for new transaction types that might not be relevant for all nodes. It gives the receiving node better control over the data it fetches from the peer as well as allow throttling the download of specific types.</p> <p>The <code>types</code> message element is a byte array because early implementations of this EIP erroneously implemented it that way. It was later decided to keep this behavior in order to minimize work.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP changes the <code>eth</code> protocol and requires rolling out a new version, <code>eth/68</code>. Supporting multiple versions of a wire protocol is possible. Rolling out a new version does not break older clients immediately, since they can keep using protocol version <code>eth/67</code>.</p> <p>This EIP does not change consensus rules of the EVM and does not require a hard fork.</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-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-17T00:00:00+00:00 2026-02-11T14:48:25+00:00 2pmflowhttps://github.com/2pmflow locationtbahttps://github.com/locationtba Cameron Robertsonhttps://github.com/ccamrobertson cygaarhttps://github.com/cygaar Brian Weickhttps://github.com/bweick vectorizedhttps://github.com/vectorized djdabshttps://github.com/djdabs https://wg-eips.ritovision.com/5791/

Minimal interface for linking ownership of ERC-721 NFTs to a physical chip

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. It proposes a minimal interface for a <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> NFT to be "physically backed" and owned by whoever owns the NFT's physical counterpart.</p> <h2 id="motivation">Motivation</h2> <p>NFT collectors enjoy collecting digital assets and sharing them with others online. However, there is currently no such standard for showcasing physical assets as NFTs with verified authenticity and ownership. Existing solutions are fragmented and tend to be susceptible to at least one of the following:</p> <ul> <li> <p>The ownership of the physical item and the ownership of the NFT are decoupled.</p> </li> <li> <p>Verifying the authenticity of the physical item requires action from a trusted 3rd party (e.g. StockX).</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="requirements">Requirements</h3> <p>This approach requires that the physical item must have a chip attached to it that should be secure and signal authenticity:</p> <ul> <li>The chip can securely generate and store an asymmetric key pair;</li> <li>The chip can sign messages using the private key of the previously-generated asymmetric key pair;</li> <li>The chip exposes the public key; and</li> <li>The private key cannot be extracted or duplicated by design</li> </ul> <p>The approach also requires that the contract uses an account-bound implementation of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> (where all <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> functions that transfer must throw, e.g. the "read only NFT registry" implementation referenced in <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>). This ensures that ownership of the physical item is required to initiate transfers and manage ownership of the NFT, through a new function introduced in this interface described below.</p> <h3 id="approach">Approach</h3> <p>Each NFT is conceptually linked to a physical chip.</p> <p>When the chipId is paired to a tokenId, an event will be emitted. This lets downstream indexers know which chip addresses are mapped to which tokens for the NFT collection. The NFT cannot be minted without its token id being linked to a specific chip.</p> <p>The interface includes a function called <code>transferToken</code> that transfers the NFT to the function caller if a valid signature signed by the chip is passed in. A valid signature must follow the schemes set forth in <a href="https://wg-eips.ritovision.com/191/">ERC-191</a> and <a href="https://wg-eips.ritovision.com/2/">EIP-2</a> (s-value restrictions), where the data to sign consists of the target recipient address (the function caller), the chip address, a block timestamp, and any extra params used for additional custom logic in the implementation.</p> <p>The interface also includes other functions that let anyone validate whether the chip in the physical item is backing an existing NFT in the collection.</p> <h3 id="interface">Interface</h3> <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"> IERC5791</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"> Returns the ERC-721 `tokenId` for a given chip address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Reverts if `chipId` has not been paired to a `tokenId`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> For minimalism, this will NOT revert if the `tokenId` does not exist.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If there is a need to check for token existence, external contracts can</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> call `ERC721.ownerOf(uint256 tokenId)` and check if it passes or reverts.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> chipId</span><span class="z-comment"> The address for the chip embedded in the physical item</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (computed from the chip&#39;s public key).</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenIdFor</span><span>(</span><span class="z-support">address</span><span class="z-variable"> chipId</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"> 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"> @dev</span><span class="z-comment"> Returns true if `signature` is signed by the chip assigned to `tokenId`, else false.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Reverts if `tokenId` has not been paired to a chip.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> For minimalism, this will NOT revert if the `tokenId` does not exist.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If there is a need to check for token existence, external contracts can</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> call `ERC721.ownerOf(uint256 tokenId)` and check if it passes or reverts.</span></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"> ERC-721 `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"> data</span><span class="z-comment"> Arbitrary bytes string that is signed by the chip to produce `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"> signature</span><span class="z-comment"> EIP-191 signature by the chip to check.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isChipSignatureForToken</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</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-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> signature</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"> Transfers the token into the address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Returns the `tokenId` transferred.</span></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 recipient. Dynamic to allow easier transfers to vaults.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> chipId</span><span class="z-comment"> Chip ID (address) of chip being transferred.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> chipSignature</span><span class="z-comment"> EIP-191 signature by the chip to authorize the 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"> signatureTimestamp</span><span class="z-comment"> Timestamp used in `chipSignature`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> useSafeTransferFrom</span><span class="z-comment"> Whether ERC-721&#39;s `safeTransferFrom` should be used,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> instead of `transferFrom`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> extras</span><span class="z-comment"> Additional data that can be used for additional logic/context</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> when the PBT is transferred.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferToken</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"> address</span><span class="z-variable"> chipId</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"> chipSignature</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> signatureTimestamp</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> useSafeTransferFrom</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"> extras</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">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"> @dev</span><span class="z-comment"> Emitted when `chipId` is paired to `tokenId`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `tokenId` may not necessarily exist during assignment.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Indexers can combine this event with the {ERC721.Transfer} event to</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> infer which tokens exists and are paired with a chip ID.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ChipSet</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"> chipId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre> <p>To aid recognition that an <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> token implements physical binding via this EIP: upon calling <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>’s <code>function supportsInterface(bytes4 interfaceID) external view returns (bool)</code> with <code>interfaceID=0x4901df9f</code>, a contract implementing this EIP must return true.</p> <p>The mint interface is up to the implementation. The minted NFT's owner should be the owner of the physical chip (this authentication could be implemented using the signature scheme defined for <code>transferToken</code>).</p> <h2 id="rationale">Rationale</h2> <p>This solution's intent is to be the simplest possible path towards linking physical items to digital NFTs without a centralized authority.</p> <p>The interface includes a <code>transferToken</code> function that's opinionated with respect to the signature scheme, in order to enable a downstream aggregator-like product that supports transfers of any NFTs that implement this EIP in the future.</p> <p>The chip address is included in <code>transferToken</code> to allow signature verification by a smart contract. This ensures that chips in physically backed tokens are not strictly tied to implementing secp256k1 signatures, but instead may use a variety of signature schemes such as P256 or BabyJubJub.</p> <h3 id="out-of-scope">Out of Scope</h3> <p>The following are some peripheral problems that are intentionally not within the scope of this EIP:</p> <ul> <li>trusting that a specific NFT collection's chip addresses actually map to physical chips embedded in items, instead of arbitrary EOAs that purport to be chips</li> <li>ensuring that the chip does not deteriorate or get damaged</li> <li>ensuring that the chip stays attached to the physical item</li> <li>etc.</li> </ul> <p>Work is being done on these challenges in parallel.</p> <p>Mapping token ids to chip addresses is also out of scope. This can be done in multiple ways, e.g. by having the contract owner preset this mapping pre-mint, or by having a <code>(tokenId, chipId)</code> tuple passed into a mint function that's pre-signed by an address trusted by the contract, or by doing a lookup in a trusted registry, or by assigning token ids at mint time first come first served, etc.</p> <p>Additionally, it's possible for the owner of the physical item to transfer the NFT to a wallet owned by somebody else (by sending a chip signature to that other person for use). We still consider the NFT physical backed, as ownership management is tied to the physical item. This can be interpreted as the item's owner temporarily lending the item to somebody else, since (1) the item's owner must be involved for this to happen as the one signing with the chip, and (2) the item's owner can reclaim ownership of the NFT at any time.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is backward compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> on an API level. As mentioned above, for the token to be physical-backed, the contract must use a account-bound implementation of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> (all <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> functions that transfer must throw) so that transfers go through the new function introduced here, which requires a chip signature.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The following is a snippet on how to validate a chip signature in a transfer event.</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/cryptography/ECDSA.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"> @dev</span><span class="z-comment"> Transfers the `tokenId` assigned to `chipId` to `to`.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> transferToken</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"> address</span><span class="z-variable"> chipId</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"> chipSignature</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> signatureTimestamp</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> useSafeTransfer</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"> extras</span></span> <span class="giallo-l"><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 class="z-variable"> tokenId</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> tokenId </span><span class="z-keyword">=</span><span class="z-entity z-name"> tokenIdFor</span><span>(</span><span>chipId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _validateSigAndUpdateNonce</span><span>(</span><span>to</span><span>,</span><span> chipId</span><span>,</span><span> chipSignature</span><span>,</span><span> signatureTimestamp</span><span>,</span><span> extras</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>useSafeTransfer</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _safeTransfer</span><span>(</span><span class="z-entity z-name">ownerOf</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>,</span><span class="z-string"> &quot;&quot;</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"> _transfer</span><span>(</span><span class="z-entity z-name">ownerOf</span><span>(</span><span>tokenId</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> <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"> Validates the `chipSignature` and update the nonce for the future signature of `chipId`.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> _validateSigAndUpdateNonce</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"> address</span><span class="z-variable"> chipId</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"> chipSignature</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> signatureTimestamp</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"> extras</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> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> hash </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getSignatureHash</span><span>(</span><span>signatureTimestamp</span><span>,</span><span> chipId</span><span>,</span><span> to</span><span>,</span><span> extras</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>SignatureCheckerLib</span><span>.</span><span class="z-entity z-name">isValidSignatureNow</span><span>(</span><span>chipId</span><span>,</span><span> hash</span><span>,</span><span> chipSignature</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> InvalidSignature</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> chipNonce</span><span>[</span><span>chipId</span><span>]</span><span class="z-keyword"> =</span><span class="z-support"> bytes32</span><span>(</span><span class="z-support">uint256</span><span>(</span><span>hash</span><span>)</span><span class="z-keyword"> ^</span><span class="z-support"> uint256</span><span>(</span><span class="z-variable z-language">blockhash</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"> 1</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-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Returns the digest to be signed by the `chipId`.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> _getSignatureHash</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> signatureTimestamp</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> chipId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> extras</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> internal</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">bytes32</span><span>)</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>signatureTimestamp </span><span class="z-keyword">&gt;</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> SignatureTimestampInFuture</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>signatureTimestamp </span><span class="z-keyword">+</span><span> maxDurationWindow </span><span class="z-keyword">&lt;</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</span><span>)</span><span class="z-keyword"> revert</span><span class="z-entity z-name"> SignatureTimestampTooOld</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> hash </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 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"> block</span><span>.</span><span>chainid</span><span>,</span><span> chipNonce</span><span>[</span><span>chipId</span><span>]</span><span>,</span><span> to</span><span>,</span><span> signatureTimestamp</span><span>,</span><span class="z-support"> keccak256</span><span>(</span><span>extras</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> ECDSA</span><span>.</span><span class="z-entity z-name">toEthSignedMessageHash</span><span>(</span><span>hash</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>The <a href="https://wg-eips.ritovision.com/191/">ERC-191</a> signature passed to <code>transferToken</code> requires the function caller's address in its signed data so that the signature cannot be used in a replay attack. It also requires a recent block timestamp so that a malicious chip owner cannot pre-generate signatures to use after a short time window (e.g. after the owner of the physical item changes). It's recommended to use a non-deterministic <code>chipNonce</code> when generating signatures.</p> <p>Additionally, the level of trust that one has for whether the token is physically-backed is dependent on the security of the physical chip, which is out of scope for this EIP as mentioned 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> 2022-10-17T00:00:00+00:00 2026-02-11T14:49:28+00:00 Moody Salemhttps://github.com/moodysalem Lukas Rosariohttps://github.com/lukasrosario Wilson Cusackhttps://github.com/wilsoncusack Dror Tiroshhttps://github.com/drortirosh Jake Moxeyhttps://github.com/jxom Derek Reinhttps://github.com/arein Alex Forshtathttps://github.com/forshtat Sam Wilsonhttps://github.com/SamWilsnsam@binarycake.ca Borislav Itskovhttps://github.com/Oxbobby Joao Tavareshttps://github.com/cryptotavares Adam Fullerhttps://github.com/azf20 Philip Liaohttps://github.com/phil-ociraptor bumblefudgehttps://github.com/bumblefudge https://wg-eips.ritovision.com/5792/

Adds JSON-RPC methods for sending multiple calls from the user's wallet, and checking their status

<h2 id="abstract">Abstract</h2> <p>Defines new JSON-RPC methods which enable apps to ask a wallet to process a batch of onchain write calls and to check on the status of those calls. Applications can specify that these onchain calls be executed taking advantage of specific capabilities previously expressed by the wallet; an additional, novel wallet RPC is defined to enable apps to query the wallet for those capabilities.</p> <h2 id="motivation">Motivation</h2> <p>The current methods used to send transactions from the user wallet and check their status are <code>eth_sendTransaction</code> and <code>eth_getTransactionReceipt</code>.</p> <p>The current methods used to send transactions from the user wallet and check their status do not meet modern developer demands and cannot accommodate new transaction formats. Even the name–- <code>eth_sendTransaction</code>-– is an artifact of a time when nodes served as wallets.</p> <p>Today, developers want to send multiple calls batched together in a single RPC call, which many smart accounts can, in turn, execute atomically in a single transaction. Developers also want to make use of features afforded by new transaction formats, like paymasters in <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> transactions. <code>eth_sendTransaction</code> offers no way to do these things.</p> <p>In updating to a new set of <code>wallet_</code> RPCs, our main goals are to enforce a clean separation of wallet and app concerns, enable developers to make use of things like paymasters and batch transactions, and to create a clear way for more safely discoverable features to be added over time with minimal coordination.</p> <h2 id="specification">Specification</h2> <p>Four new JSON-RPC methods are added: three are for handling batches of onchain calls, and one is for querying support for wallet capabilities, such as to make better use of the three batching methods. Apps may begin using these first three methods immediately, falling back to <code>eth_sendTransaction</code> and <code>eth_getTransactionReceipt</code> when they are not available.</p> <h3 id="wallet-sendcalls"><code>wallet_sendCalls</code></h3> <p>Requests that a wallet submits a batch of calls. <code>from</code> and <code>chainId</code> are identified by <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> integers expressed in hexadecimal notation, with <code>0x</code> prefix and no leading zeroes for the <code>chainId</code> value. The items in the <code>calls</code> field are simple <code>{to, data, value}</code> tuples.</p> <p>The capabilities field is how an app can communicate with a wallet about capabilities a wallet supports. For example, this is where an app can specify a paymaster service URL from which an <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> wallet can request a <code>paymasterAndData</code> input for a user operation.</p> <p>Each capability defined in the "capabilities" member can define global or call specific fields. These fields are set inside this capability's entry in the <code>capabilities</code> object. Each entity in the <code>calls</code> field may contain an optional <code>capabilities</code> object. This object allows the applications to attach a capability-specific metadata to individual calls.</p> <p>The <code>atomicRequired</code> field specifies if a wallet is required to handle the batch of calls atomically or not. The wallet capacity to execute batch calls atomically is exposed through the built in <code>atomic</code> capability and can be sourced via <code>wallet_getCapabilities</code>..</p> <p>Unless these requirements are explicitly overridden by a certain <code>capability</code>, the wallet must adhere to the following rules. Note that such a <code>capability</code> is not in the scope of this EIP and should be defined in its own ERC.</p> <p>The wallet:</p> <ul> <li> <p>MUST send the calls in the order specified in the request</p> </li> <li> <p>MUST send the calls on the same chain identified by the request's <code>chainId</code> property</p> </li> <li> <p>MUST send the calls from the address specified in the request's <code>from</code> property, if provided</p> <ul> <li>If <code>from</code> is not provided the wallet SHOULD present the user with an opportunity to view and select the <code>from</code> address during confirmation</li> </ul> </li> <li> <p>MUST NOT await for any calls to be finalized to complete the batch</p> </li> <li> <p>MUST NOT send any calls from the request if the user rejects the request</p> </li> <li> <p>When <code>atomicRequired</code> is set to <code>true</code>:</p> <ul> <li>MUST execute all calls atomically, meaning that either all calls execute successfully or no material effects appear on chain.</li> <li>MUST execute all calls contiguously, meaning no other transactions/calls may be interleaved with the calls from this batch.</li> <li>If a wallet is able to upgrade its atomicity guarantees from <code>ready</code> to <code>supported</code> but has not yet done so, it MUST upgrade before proceeding to submit the calls with the above guarantees.</li> </ul> </li> <li> <p>When <code>atomicRequired</code> is set to <code>false</code>:</p> <ul> <li>MAY execute all calls sequentially without any atomicity/contiguity guarantees.</li> <li>If a wallet is capable of providing atomicity guarantees, it MAY execute the batch atomically.</li> <li>If a wallet is able to upgrade its atomicity guarantees to <code>supported</code> (see <code>atomic</code> capability definition below), it MAY do so and then execute the batch atomically.</li> </ul> </li> <li> <p>MAY reject the request if the from address does not match the enabled account</p> </li> <li> <p>MAY reject the request if one or more calls in the batch is expected to fail, when simulated sequentially</p> </li> <li> <p>MUST reject the request if it contains a <code>capability</code> (either top-level or call-level) that is not supported by the wallet and the <code>capability</code> is not explicitly marked as optional.</p> <ul> <li>Applications may mark a capability as optional by setting <code>optional</code> to <code>true</code>. See the RPC Specification section below for details.</li> </ul> </li> </ul> <p>If provided, the wallet MUST respect the <code>id</code> field and return it in the response.</p> <p>Identifiers, whether provided by the app or generated by the wallet, MUST be a unique string up to 4096 bytes (8194 characters including leading <code>0x</code>).</p> <p>App-provided <code>id</code>s MUST be unique per sender per app, where each "app" SHOULD be identified by their domain.</p> <p>Wallets MUST reject requests with duplicate <code>id</code>s.</p> <p>Within 24 hours from the corresponding <code>wallet_sendCalls</code>, wallets SHOULD return a call-batch status when <code>wallet_getCallsStatus</code> is called with the same <code>id</code>.</p> <p>The <code>capabilities</code> response object allows the wallets to attach a capability-specific metadata to the response.</p> <h4 id="wallet-sendcalls-rpc-specification"><code>wallet_sendCalls</code> RPC Specification</h4> <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"> Capability</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span> [</span><span class="z-variable">key</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>]</span><span class="z-keyword">:</span><span class="z-support"> unknown</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 class="giallo-l"></span> <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> <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"> id</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"> from</span><span class="z-keyword">?</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> <span class="giallo-l"><span class="z-variable"> chainId</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex chain id</span></span> <span class="giallo-l"><span class="z-variable"> atomicRequired</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> calls</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> to</span><span class="z-keyword">?</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> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">?</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> <span class="giallo-l"><span class="z-variable"> value</span><span class="z-keyword">?</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex value</span></span> <span class="giallo-l"><span class="z-variable"> capabilities</span><span class="z-keyword">?</span><span class="z-keyword">:</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><span>;</span></span> <span class="giallo-l"><span class="z-variable"> capabilities</span><span class="z-keyword">?</span><span class="z-keyword">:</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"> SendCallsResult</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> id</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> capabilities</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h5 id="wallet-sendcalls-example-parameters"><code>wallet_sendCalls</code> Example Parameters</h5> <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">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">from</span><span class="z-support">&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-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">atomicRequired</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">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">0xd46e8dd67c5d32be8058bb8eb970870f07244567</span><span class="z-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">0x9184e72a</span><span class="z-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">0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675</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">to</span><span class="z-support">&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-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">0x182183</span><span class="z-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">0xfbadbaf01</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">paymasterService</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">url</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://...</span><span class="z-punctuation z-definition z-string">&quot;</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 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>Note that since the <code>paymasterService</code> <code>capability</code> is marked as optional, wallets that do not support it will still process and handle the request as if the capability had not been present. If this <code>optional</code> field were set to <code>false</code> or absent from the request, wallets that do not support the <code>capability</code> MUST reject the request.</p> <h5 id="wallet-sendcalls-example-return-value"><code>wallet_sendCalls</code> Example Return Value</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</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="wallet-getcallsstatus"><code>wallet_getCallsStatus</code></h3> <p>Returns the status of a call batch that was sent via <code>wallet_sendCalls</code>. The identifier of the batch is the value returned from the <code>wallet_sendCalls</code> RPC. Note that the <code>receipts</code> objects of this method's response is a strict subset of the object returned by <code>eth_getTransactionReceipt</code>.</p> <p>The <code>capabilities</code> object allows the wallets to attach a capability-specific metadata to the response.</p> <p>The <code>atomic</code> field specifies how the wallet handled the batch of calls, which influences the structure of the <code>receipts</code> field.</p> <ul> <li>The receipts in the <code>receipts</code> field MUST be in the order that they are included onchain.</li> <li>If a wallet executes multiple calls <strong>atomically</strong>, <code>wallet_getCallsStatus</code> MAY return an object with a <code>receipts</code> field that contains a single transaction receipt or an array of receipts, corresponding to how the batch of transactions were included onchain. It also MUST be explicit and return an <code>atomic</code> field set to <code>true</code>.</li> <li>If a wallet executes multiple calls <strong>non-atomically</strong>, <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. It also MUST be explicit and return a <code>atomic</code> field set to <code>false</code>.</li> <li>The <code>logs</code> in the receipt objects MUST only include logs relevant to the calls submitted using <code>wallet_sendCalls</code>. For example, in the case of a transaction submitted onchain by an <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> bundler, the logs must only include those relevant to the user operation constructed using the calls submitted via <code>wallet_sendCalls</code>. I.e. the logs should not include those from other unrelated user operations submitted in the same bundle. <ul> <li>Similarly, if a user upgrades their wallet to support atomicity before submitting a batch of calls from an app, the logs MUST NOT include those emitted as part of the upgrade process.</li> </ul> </li> </ul> <h4 id="wallet-getcallsstatus-rpc-specification"><code>wallet_getCallsStatus</code> RPC Specification</h4> <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"> GetCallsParams</span><span class="z-keyword"> =</span><span> [</span><span class="z-support">string</span><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"> GetCallsResult</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"> id</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> <span class="giallo-l"><span class="z-variable"> chainId</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> <span class="giallo-l"><span class="z-variable"> status</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> See &quot;Status Codes&quot;</span></span> <span class="giallo-l"><span class="z-variable"> atomic</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> receipts</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> logs</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> address</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> <span class="giallo-l"><span class="z-variable"> data</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> <span class="giallo-l"><span class="z-variable"> topics</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>]</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>[</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> status</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Hex 1 or 0 for success or failure, respectively</span></span> <span class="giallo-l"><span class="z-variable"> blockHash</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> <span class="giallo-l"><span class="z-variable"> blockNumber</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> <span class="giallo-l"><span class="z-variable"> gasUsed</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> <span class="giallo-l"><span class="z-variable"> transactionHash</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> <span class="giallo-l"><span> }</span><span>[</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> capabilities</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h5 id="status-codes-for-status-field">Status Codes for <code>status</code> field</h5> <p>The purpose of the <code>status</code> field is to provide a short summary of the current status of the batch. It provides some off-chain context to the array of inner transaction <code>receipts</code>.</p> <p>Status codes follow these categories:</p> <ul> <li>1xx: Pending states</li> <li>2xx: Confirmed states</li> <li>4xx: Offchain failures</li> <li>5xx: Chain rules failures</li> </ul> <table><thead><tr><th>Code</th><th>Description</th></tr></thead><tbody> <tr><td>100</td><td>Batch has been received by the wallet but has not completed execution onchain (pending)</td></tr> <tr><td>200</td><td>Batch has been included onchain without reverts, receipts array contains info of all calls (confirmed)</td></tr> <tr><td>400</td><td>Batch has not been included onchain and wallet will not retry (offchain failure)</td></tr> <tr><td>500</td><td>Batch reverted <strong>completely</strong> and only changes related to gas charge may have been included onchain (chain rules failure)</td></tr> <tr><td>600</td><td>Batch reverted <strong>partially</strong> and some changes related to batch calls may have been included onchain (partial chain rules failure)</td></tr> </tbody></table> <p>More specific status codes within these categories should be proposed and agreed upon in separate ERCs.</p> <h5 id="wallet-getcallsstatus-example-parameters"><code>wallet_getCallsStatus</code> Example Parameters</h5> <p>The <code>id</code> batch identifier is a unique 64 bytes represented as a hex encoded string returned from <code>wallet_sendCalls</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>]</span></span></code></pre><h5 id="wallet-getcallsstatus-example-return-value"><code>wallet_getCallsStatus</code> Example Return Value</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">version</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.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">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">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000000000000000000000000000000000000000000000000000000000000e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">status</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 200</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">atomic</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">receipts</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">logs</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">0xa922b54716264130634d6ff183747a8ead91a40b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">topics</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">0x5a2a90727cc9d000dd060b1132a5c977c9702bb3a52afe360c9c22f0e9451a68</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">data</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xabcd</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">status</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 class="z-support"> &quot;</span><span class="z-support">blockHash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf19bbafd9fd0124ec110b848e8de4ab4f62bf60c189524e54213285e7f540d4a</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">blockNumber</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xabcd</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasUsed</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xdef</span><span class="z-punctuation z-definition z-string">&quot;</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">0x9b7bb827c2e5e3c1a0a44dc53e573aa0b3af3bd1f9f5ed03071b100bb039eaff</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="wallet-showcallsstatus"><code>wallet_showCallsStatus</code></h3> <p>Requests that a wallet shows information about a given call bundle that was sent with <code>wallet_sendCalls</code>. Note that this method does not return anything for a known <code>id</code> batch identifier. If the identifier is not known, or in case of any other failure to execute <code>wallet_showCallsStatus</code> returns an RPC call error.</p> <h4 id="wallet-showcallsstatus-rpc-specification"><code>wallet_showCallsStatus</code> RPC Specification</h4> <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"> ShowCallsParams</span><span class="z-keyword"> =</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Call bundle identifier returned by wallet_sendCalls</span></span></code></pre><h5 id="wallet-showcallsstatus-example-parameters"><code>wallet_showCallsStatus</code> Example Parameters</h5> <p>This method accepts a call bundle identifier returned by a <code>wallet_sendCalls</code> call.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>[</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></span></code></pre><h3 id="wallet-getcapabilities"><code>wallet_getCapabilities</code></h3> <p>This RPC allows an application to request capabilities from a wallet (e.g. batch transactions, paymaster communication), without distinct discovery and permission requests. For more on the difference between requesting capabilities and discovering features, see the <a href="https://wg-eips.ritovision.com/5792/#privacy-considerations">"Privacy Considerations" section</a>.</p> <p>This method SHOULD return an <code>4100 Unauthorized</code> error if the user has not already authorized a connection between the application and the requested address.</p> <p>We expect the community to align on the definition of additional capabilities in separate ERCs over time.</p> <p>Note that in addition to, or instead of, querying the wallet directly for capabilities, the same capability objects MAY be exposed out-of-band, such as in a <code>sessionProperties</code> and/or <code>scopedProperties</code> collections persisted in a <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/c599f7601d0ce83e6dd9f350c6c21d158d56fd6d/CAIPs/caip-25.md">CAIP-25</a>-conformant wallet provider interface (see the ethereum usage profile for CAIP-25 for an example request and response), or in some other a well-known location (such as a URL derived from an <a href="https://wg-eips.ritovision.com/6963/">EIP-6963</a> <code>rdns</code> identifier). Provider abstractions MAY also cache capabilities from previous requests or otherwise inject them from out-of-band to facilitate better user experience. If any of these supplemental expressions of capabilities are contradicted by capabilities expressed in live wallet RPC responses, these latter values SHOULD be taken as the canonical and current expression of capabilities.</p> <h4 id="wallet-getcapabilities-rpc-specification"><code>wallet_getCapabilities</code> RPC Specification</h4> <p>Capabilities are returned in key/value pairs, with the key naming a capability and a value conforming to a shape defined for that name, in an object keyed to the relevant <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> <code>chainId</code> expressed in hexadecimal notation. Capabilities are nested in per-chain objects because wallets may support different capabilities across multiple chains authorized in a given session. Capabilities that the wallet supports on all the chains SHOULD be included only once, using a special <code>chainID</code> value <code>"0x0"</code>, and SHOULD NOT be repeated in nested per-chain objects. If a wallet does not support a chain that is requested in the <code>wallet_getCapabilities</code> method, the wallet MUST NOT respond with an error, and MUST instead not include a key for the unsupported chain(s) in the response.</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"> GetCapabilitiesParams</span><span class="z-keyword"> =</span><span> [</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> [</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>]</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Wallet address, array of queried chain ids (optional)</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"> GetCapabilitiesResult</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Record</span><span>&lt;</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> &lt;</span><span class="z-entity z-name">Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-support"> any</span><span>&gt;</span><span>&gt;</span><span>; </span><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Hex chain id</span></span></code></pre><h5 id="wallet-getcapabilities-example-parameters"><code>wallet_getCapabilities</code> Example Parameters</h5> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><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><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x2105</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">0x14A34</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>]</span></span></code></pre><h5 id="wallet-getcapabilities-example-return-value"><code>wallet_getCapabilities</code> Example Return Value</h5> <p>The capabilities below are for illustrative purposes.</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">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">flow-control</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 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">0x2105</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">paymasterService</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 class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sessionKeys</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 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">0x14A34</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">auxiliaryFunds</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 class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="atomic-capability"><code>atomic</code> Capability</h3> <p>Like the illustrative examples given above and other capabilities to be defined in future EIPs, the <code>atomic</code> capability specifies how the wallet will execute the batches of transactions requested through <code>wallet_sendCalls</code> method.</p> <p>The valid JSON-RPC values for this <code>atomic</code> capability's only property, <code>status</code>, are <code>supported</code>, <code>ready</code>, and <code>unsupported</code>:</p> <ul> <li><code>supported</code> means that the wallet will execute the calls atomically and contiguously.</li> <li><code>ready</code> means that the wallet is able to upgrade to <code>supported</code> pending user approval.</li> <li><code>unsupported</code> means that the wallet does not provide any atomicity or contiguity guarantees, nor will it suggest an upgrade to the user.</li> </ul> <p>This capability is expressed separately on each chain and should be interpreted as a guarantee only for batches of transactions on that chain.</p> <p>If the <code>atomic</code> capability is not present for a given chain, and unless it is explicitly overridden by another <code>capability</code> (not in scope of this EIP), it means that the wallet does not support batching for that given chain.</p> <h4 id="atomic-capability-specification"><code>atomic</code> Capability Specification</h4> <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"> AtomicCapability</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> status</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">supported</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> |</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">ready</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> |</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">unsupported</span><span class="z-punctuation z-definition z-string">&#39;</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre><h4 id="wallet-getcapabilities-example-return-value-including-atomic"><code>wallet_getCapabilities</code> Example Return Value including <code>atomic</code></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">0x2105</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">atomic</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">status</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">supported</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">0x14A34</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">atomic</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">status</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">unsupported</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="error-codes">Error Codes</h3> <p>The following error codes are defined for the methods specified in this EIP. These errors follow the JSON-RPC 2.0 specification for error objects, which require a <code>code</code> and <code>message</code> field.</p> <table><thead><tr><th>Code</th><th>Message</th><th>Description</th><th>Related RPCs</th></tr></thead><tbody> <tr><td>-32602</td><td>Invalid params</td><td>The wallet cannot parse this request (e.g., missing 0x prefix, leading zeros in chain id, request fails schema validation)</td><td><code>wallet_sendCalls</code>, <code>wallet_getCallsStatus</code>, <code>wallet_showCallsStatus</code>, <code>wallet_getCapabilities</code></td></tr> <tr><td>4001</td><td>User Rejected Request</td><td>The user rejected submitting the batch of calls (from <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a>)</td><td><code>wallet_sendCalls</code></td></tr> <tr><td>4100</td><td>Unauthorized</td><td>The specified address is not connected or not in the wallet (from <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a>)</td><td><code>wallet_sendCalls</code>, <code>wallet_getCapabilities</code></td></tr> <tr><td>5700</td><td>Unsupported non-optional capability</td><td>This wallet does not support a capability that was not marked as optional</td><td><code>wallet_sendCalls</code></td></tr> <tr><td>5710</td><td>Unsupported chain id</td><td>This wallet does not support the specified chain id</td><td><code>wallet_sendCalls</code></td></tr> <tr><td>5720</td><td>Duplicate ID</td><td>There is already a bundle submitted with this id</td><td><code>wallet_sendCalls</code></td></tr> <tr><td>5730</td><td>Unknown bundle id</td><td>This bundle id is unknown / has not been submitted</td><td><code>wallet_getCallsStatus</code>, <code>wallet_showCallsStatus</code></td></tr> <tr><td>5740</td><td>Bundle too large</td><td>The call bundle is too large for the wallet to process</td><td><code>wallet_sendCalls</code></td></tr> <tr><td>5750</td><td>Atomic-ready wallet rejected upgrade</td><td>The wallet can support atomicity after an upgrade, but the user rejected the upgrade</td><td><code>wallet_sendCalls</code></td></tr> <tr><td>5760</td><td>Atomicity not supported</td><td>The wallet does not support atomic execution but the request requires it</td><td><code>wallet_sendCalls</code></td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <h3 id="on-naming">On Naming</h3> <p>We considered modifying <code>eth_sendTransaction</code> to add support for these new capabilities, but the method is ultimately an artifact of when nodes were used to sign transactions. We decided it is better to move forward with <code>wallet_</code>-namespaced methods that better describe what they are used for.</p> <p>We also debated whether the methods should be called <code>wallet_sendTransaction</code>, <code>wallet_sendCalls</code>, or something else. We ultimately landed on <code>wallet_sendCalls</code> because in the case of EOA wallets the <code>wallet_send*</code> method might send more than one transaction. Similarly, we decided against <code>wallet_sendTransactions</code> because in the case of other wallet implementations (e.g. <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a>) multiple calls could result in a single transaction.</p> <h3 id="call-execution-atomicity">Call Execution Atomicity</h3> <p>The <code>wallet_sendCalls</code> method accepts an array of <code>calls</code>. However, this proposal does not require that these calls be executed as part of a single transaction. It enables EOA wallets to express their ability to execute calls as part of a single transaction or as part of multiple transactions. It also enables Apps to express their minimum atomicity requirements for how calls must be executed.</p> <p>The <code>atomic</code> special capability was made an integral part of this specification in order promote expressiveness and facilitate adoption (from both wallets and apps). And due to its importance to reduce ambiguity between the App and the Wallet, the capability is expressed as a top-level field in the <code>wallet_sendCalls</code> request (through the <code>atomicRequired</code> parameter) and the <code>wallet_getCallsStatus</code> response (through the <code>atomic</code> field).</p> <p>We initially proposed that multiple calls must be executed atomically, but after some debate we ultimately decided this was too opinionated. Instead, we are including a specification for an <code>atomic</code> capability. This allows for EOA wallets to accept multiple calls and still gives developers the option to only submit batched calls if they are executed atomically.</p> <h3 id="call-gas-limit">Call Gas Limit</h3> <p>Our initial proposal included an optional <code>gas</code> field for each call in the <code>calls</code> field accepted by the <code>walletSendCalls</code> method. However, we realized this could be misleading because in the case of <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> wallets you cannot specify a gas limit per call, only a single gas limit for all calls in the user operation. We then proposed a single <code>gas</code> value that would apply to all of the calls. This works for <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> wallets, but not for EOA wallets. When we decided that EOA wallets should be able to handle multiple calls, the common <code>gas</code> field became untenable across use cases and we removed it altogether.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Wallets that do not support the methods defined here SHOULD return error responses when these new JSON-RPC methods are called. Apps MAY attempt to send the same batch of calls serially via <code>eth_sendTransaction</code> when a call to these methods fails for lack of wallet support, or they MAY indicate to the user that their wallet is not supported and the request was not processed.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Regardless of the <code>atomic</code> value specified, App developers MUST NOT assume that all calls will be sent in a single transaction. An example could be an L2 resistant to reorgs that implements a sendBundle or similar functionality.</p> <p>Wallets MUST ensure that batch identifiers returned by <code>wallet_sendCalls</code> are unpredictable to prevent malicious apps from inferring information about other users' transactions.</p> <p>Wallets MUST NOT leak sensitive information in <code>wallet_getCallsStatus</code> <code>capabilities</code> responses.</p> <h3 id="privacy-considerations">Privacy Considerations</h3> <p>Progressive authorization and progressive consent paradigms are important to modern user experience, as well as to preserving the anonymity of user agents. To protect these patterns from the cross-incentives of feature-discovery that enables better user experiences, capability semantics are used and the difference between lack of feature support and lack of feature permission explicitly occluded in the design of the <code>wallet_</code> RPC for querying capabilities.</p> <p>Furthermore, wallets are recommended to avoid exposing capabilities to untrusted callers or to more callers than necessary, as this may allow their "user-agent" (i.e. client software) to be "fingerprinted" or probabilistically identified, which combined with other deanonymization vectors inherent to the web platform could contribute to the deanonymization of the individual user or to the deanonymization of all users of a given client in aggregate. Similarly, applications over-querying capabilities or incentivizing capability oversharing (including third-party capability oversharing) is an anti-pattern to be avoided in the implementation of capability exchanges serving to discover features.</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-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Bruno Škvorchttps://github.com/Swader Cicadahttps://github.com/CicadaNCR Steven Pinedahttps://github.com/steven2308 Stevan Bogosavljevichttps://github.com/stevyhacker Jan Turkhttps://github.com/ThunderDeliverer https://wg-eips.ritovision.com/5773/

An interface for Multi-Asset tokens with context dependent asset type output controlled by owner's preference.

<h2 id="abstract">Abstract</h2> <p>The Multi-Asset NFT standard allows for the construction of a new primitive: context-dependent output of information per single NFT.</p> <p>The context-dependent output of information means that the asset in an appropriate format is displayed based on how the token is being accessed. I.e. if the token is being opened in an e-book reader, the PDF asset is displayed, if the token is opened in the marketplace, the PNG or the SVG asset is displayed, if the token is accessed from within a game, the 3D model asset is accessed and if the token is accessed by the (Internet of Things) IoT hub, the asset providing the necessary addressing and specification information is accessed.</p> <p>An NFT can have multiple assets (outputs), which can be any kind of file to be served to the consumer, and orders them by priority. They do not have to match in mimetype or tokenURI, nor do they depend on one another. Assets are not standalone entities, but should be thought of as “namespaced tokenURIs” that can be ordered at will by the NFT owner, but only modified, updated, added, or removed if agreed on by both the owner of the token and the issuer of the token.</p> <h2 id="motivation">Motivation</h2> <p>With NFTs being a widespread form of tokens in the Ethereum ecosystem and being used for a variety of use cases, it is time to standardize additional utility for them. Having multiple assets associated with a single NFT allows for greater utility, usability and forward compatibility.</p> <p>In the four years since <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> was published, the need for additional functionality has resulted in countless extensions. This EIP improves upon ERC-721 in the following areas:</p> <ul> <li><a href="https://wg-eips.ritovision.com/5773/#cross-metaverse-compatibility">Cross-metaverse compatibility</a></li> <li><a href="https://wg-eips.ritovision.com/5773/#multi-media-output">Multi-media output</a></li> <li><a href="https://wg-eips.ritovision.com/5773/#media-redundancy">Media redundancy</a></li> <li><a href="https://wg-eips.ritovision.com/5773/#nft-evolution">NFT evolution</a></li> </ul> <h3 id="cross-metaverse-compatibility">Cross-metaverse compatibility</h3> <p>At the time of writing this proposal, the metaverse is still a fledgling, not full defined, term. No matter how the definition of metaverse evolves, the proposal can support any number of different implementations.</p> <p>Cross-metaverse compatibility could also be referred to as cross-engine compatibility. An example of this is where a cosmetic item for game A is not available in game B because the frameworks are incompatible.</p> <p>Such NFT can be given further utility by means of new additional assets: more games, more cosmetic items, appended to the same NFT. Thus, a game cosmetic item as an NFT becomes an ever-evolving NFT of infinite utility.</p> <p>The following is a more concrete example. One asset is a cosmetic item for game A, a file containing the cosmetic assets. Another is a cosmetic asset file for game B. A third is a generic asset intended to be shown in catalogs, marketplaces, portfolio trackers, or other generalized NFT viewers, containing a representation, stylized thumbnail, and animated demo/trailer of the cosmetic item.</p> <p>This EIP adds a layer of abstraction, allowing game developers to directly pull asset data from a user's NFTs instead of hard-coding it.</p> <h3 id="multi-media-output">Multi-media output</h3> <p>An NFT of an eBook can be represented as a PDF, MP3, or some other format, depending on what software loads it. If loaded into an eBook reader, a PDF should be displayed, and if loaded into an audiobook application, the MP3 representation should be used. Other metadata could be present in the NFT (perhaps the book's cover image) for identification on various marketplaces, Search Engine Result Pages (SERPs), or portfolio trackers.</p> <h3 id="media-redundancy">Media redundancy</h3> <p>Many NFTs are minted hastily without best practices in mind - specifically, many NFTs are minted with metadata centralized on a server somewhere or, in some cases, a hardcoded IPFS gateway which can also go down, instead of just an IPFS hash.</p> <p>By adding the same metadata file as different assets, e.g., one asset of a metadata and its linked image on Arweave, one asset of this same combination on Sia, another of the same combination on IPFS, etc., the resilience of the metadata and its referenced information increases exponentially as the chances of all the protocols going down at once become less likely.</p> <h3 id="nft-evolution">NFT evolution</h3> <p>Many NFTs, particularly game related ones, require evolution. This is especially the case in modern metaverses where no metaverse is actually a metaverse - it is just a multiplayer game hosted on someone's server which replaces username/password logins with reading an account's NFT balance.</p> <p>When the server goes down or the game shuts down, the player ends up with nothing (loss of experience) or something unrelated (assets or accessories unrelated to the game experience, spamming the wallet, incompatible with other “verses” - see <a href="https://wg-eips.ritovision.com/5773/#cross-metaverse-compatibility">cross-metaverse</a> compatibility above).</p> <p>With Multi-Asset NFTs, a minter or another pre-approved entity is allowed to suggest a new asset to the NFT owner who can then accept it or reject it. The asset can even target an existing asset which is to be replaced.</p> <p>Replacing an asset could, to some extent, be similar to replacing an ERC-721 token's URI. When an asset is replaced a clear line of traceability remains; the old asset is still reachable and verifiable. Replacing an asset's metadata URI obscures this lineage. It also gives more trust to the token owner if the issuer cannot replace the asset of the NFT at will. The propose-accept asset replacement mechanic of this proposal provides this assurance.</p> <p>This allows level-up mechanics where, once enough experience has been collected, a user can accept the level-up. The level-up consists of a new asset being added to the NFT, and once accepted, this new asset replaces the old one.</p> <p>As a concrete example, think of Pokemon™️ evolving - once enough experience has been attained, a trainer can choose to evolve their monster. With Multi-Asset NFTs, it is not necessary to have centralized control over metadata to replace it, nor is it necessary to airdrop another NFT into the user's wallet - instead, a new Raichu asset is minted onto Pikachu, and if accepted, the Pikachu asset is gone, replaced by Raichu, which now has its own attributes, values, etc.</p> <p>Alternative example of this, could be version control of an IoT device's firmware. An asset could represent its current firmware and once an update becomes available, the current asset could be replaced with the one containing the updated firmware.</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-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-5773 Context-Dependent Multi-Asset Tokens</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-5773</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 ERC-165 identifier for this interface is 0x06b4329a.</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.16</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"> IERC5773</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">@notice</span><span class="z-comment"> Used to notify listeners that an asset object is initialised at `assetId`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assetId</span><span class="z-comment"> ID of the asset that was initialised</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"> AssetSet</span><span>(</span><span class="z-support">uint64</span><span class="z-variable"> assetId</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"> Used to notify listeners that an asset object at `assetId` is added to token&#39;s pending asset</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> tokenIds</span><span class="z-comment"> An array of IDs of the tokens that received a new pending asset</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assetId</span><span class="z-comment"> ID of the asset that has been added to the token&#39;s pending assets 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"> replacesId</span><span class="z-comment"> ID of the asset that would be replaced</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"> AssetAddedToTokens</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> tokenIds</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> assetId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> replacesId</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"> Used to notify listeners that an asset object at `assetId` is accepted by the token and migrated</span></span> <span class="giallo-l"><span class="z-comment"> * from token&#39;s pending assets array to active assets array of 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"> tokenId</span><span class="z-comment"> ID of the token that had a new asset accepted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assetId</span><span class="z-comment"> ID of the asset that was accepted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> replacesId</span><span class="z-comment"> ID of the asset that was replaced</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"> AssetAccepted</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"> uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> assetId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> replacesId</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"> Used to notify listeners that an asset object at `assetId` is rejected from token and is dropped</span></span> <span class="giallo-l"><span class="z-comment"> * from the pending assets array of 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"> tokenId</span><span class="z-comment"> ID of the token that had an asset rejected</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assetId</span><span class="z-comment"> ID of the asset that was rejected</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"> AssetRejected</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-storage z-type"> indexed</span><span class="z-variable"> assetId</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"> Used to notify listeners that token&#39;s priority array is reordered.</span></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 token that had the asset priority array updated</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"> AssetPrioritySet</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">@notice</span><span class="z-comment"> Used to notify listeners that owner has granted an approval to the user to manage the assets of a</span></span> <span class="giallo-l"><span class="z-comment"> * given token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Approvals must be cleared on 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 of the account that has granted the approval for all token&#39;s assets</span></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"> Address of the account that has been granted approval to manage the token&#39;s assets</span></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 token on which the approval was granted</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"> ApprovalForAssets</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"> approved</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"> Used to notify listeners that owner has granted approval to the user to manage assets of all of their</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> owner</span><span class="z-comment"> Address of the account that has granted the approval for all assets on all of their 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"> operator</span><span class="z-comment"> Address of the account that has been granted the approval to manage the token&#39;s assets on all of the</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> approved</span><span class="z-comment"> Boolean value signifying whether the permission has been granted (`true`) or revoked (`false`)</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"> ApprovalForAllForAssets</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"> 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 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"> Accepts an asset at from the pending array of given token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Migrates the asset from the token&#39;s pending asset array to the token&#39;s active asset array.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Active assets cannot be removed by anyone, but can be replaced by a new asset.</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"> * - The caller must own the token or be approved to manage the token&#39;s assets</span></span> <span class="giallo-l"><span class="z-comment"> * - `tokenId` must exist.</span></span> <span class="giallo-l"><span class="z-comment"> * - `index` must be in range of the length of the pending asset array.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits an {AssetAccepted} 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"> tokenId</span><span class="z-comment"> ID of the token for which to accept the pending asset</span></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 asset in the pending array to accept</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assetId</span><span class="z-comment"> Id of the asset expected to be in the index</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"> acceptAsset</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"> index</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> assetId</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"> Rejects an asset from the pending array of given token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Removes the asset from the token&#39;s pending asset array.</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"> * - The caller must own the token or be approved to manage the token&#39;s assets</span></span> <span class="giallo-l"><span class="z-comment"> * - `tokenId` must exist.</span></span> <span class="giallo-l"><span class="z-comment"> * - `index` must be in range of the length of the pending asset array.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {AssetRejected} 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"> tokenId</span><span class="z-comment"> ID of the token that the asset is being rejected from</span></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 asset in the pending array to be rejected</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> assetId</span><span class="z-comment"> Id of the asset expected to be in the index</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"> rejectAsset</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"> index</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> assetId</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"> Rejects all assets from the pending array of a given token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Effectively deletes the pending array.</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"> * - The caller must own the token or be approved to manage the token&#39;s assets</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 class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {AssetRejected} event with assetId = 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"> ID of the token of which to clear the pending 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"> maxRejections</span><span class="z-comment"> to prevent from rejecting assets which arrive just before this operation.</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"> rejectAllAssets</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"> maxRejections</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"> Sets a new priority array for a given token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The priority array is a non-sequential list of `uint16`s, where the lowest value is considered highest</span></span> <span class="giallo-l"><span class="z-comment"> * priority.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Value `0` of a priority is a special case equivalent to uninitialised.</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"> * - The caller must own the token or be approved to manage the token&#39;s assets</span></span> <span class="giallo-l"><span class="z-comment"> * - `tokenId` must exist.</span></span> <span class="giallo-l"><span class="z-comment"> * - The length of `priorities` must be equal the length of the active assets array.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits a {AssetPrioritySet} 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"> tokenId</span><span class="z-comment"> ID of the token to set the priorities 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"> priorities</span><span class="z-comment"> An array of priorities of active assets. The succession of items in the priorities array</span></span> <span class="giallo-l"><span class="z-comment"> * matches that of the succession of items in the active 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"> setPriority</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</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"> priorities</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to retrieve IDs of the active assets of given token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Asset data is stored by reference, in order to access the data corresponding to the ID, call</span></span> <span class="giallo-l"><span class="z-comment"> * `getAssetMetadata(tokenId, assetId)`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> You can safely get 10k</span></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 token to retrieve the IDs of the active assets</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">[] An array of active asset IDs of the given 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"> getActiveAssets</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">uint64</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to retrieve IDs of the pending assets of given token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Asset data is stored by reference, in order to access the data corresponding to the ID, call</span></span> <span class="giallo-l"><span class="z-comment"> * `getAssetMetadata(tokenId, assetId)`.</span></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 token to retrieve the IDs of the pending assets</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">[] An array of pending asset IDs of the given 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"> getPendingAssets</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">uint64</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to retrieve the priorities of the active assets of a given token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Asset priorities are a non-sequential array of uint16 values with an array size equal to active asset</span></span> <span class="giallo-l"><span class="z-comment"> * priorites.</span></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 token for which to retrieve the priorities of the active assets</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"> uint16</span><span class="z-comment">[] An array of priorities of the active assets of the given 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"> getActiveAssetPriorities</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">uint64</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to retrieve the asset that will be replaced if a given asset from the token&#39;s pending array</span></span> <span class="giallo-l"><span class="z-comment"> * is accepted.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Asset data is stored by reference, in order to access the data corresponding to the ID, call</span></span> <span class="giallo-l"><span class="z-comment"> * `getAssetMetadata(tokenId, assetId)`.</span></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 token to check</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> newAssetId</span><span class="z-comment"> ID of the pending asset which will be accepted</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"> ID of the asset which will be replaced</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"> getAssetReplacements</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"> newAssetId</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">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"> Used to fetch the asset metadata of the specified token&#39;s active asset with the given index.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Can be overridden to implement enumerate, fallback or other custom logic.</span></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 token from which to retrieve the asset 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"> assetId</span><span class="z-comment"> Asset Id, must be in the active assets 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"> string</span><span class="z-comment"> The metadata of the asset belonging to the specified index in the token&#39;s active assets</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> getAssetMetadata</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"> assetId</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 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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to grant permission to the user to manage token&#39;s assets.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This differs from transfer approvals, as approvals are not cleared when the approved party accepts or</span></span> <span class="giallo-l"><span class="z-comment"> * rejects an asset, or sets asset priorities. This approval is cleared on token transfer.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Only a single account can be approved at a time, so approving the `0x0` address clears previous approvals.</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"> * - The caller must own the token or be an approved 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 class="z-storage z-type">@dev</span><span class="z-comment"> Emits an {ApprovalForAssets} 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"> Address of the account to grant the approval 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"> tokenId</span><span class="z-comment"> ID of the token for which the approval to manage the assets is granted</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"> approveForAssets</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">@notice</span><span class="z-comment"> Used to retrieve the address of the account approved to manage assets of a given token.</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"> * - `tokenId` must 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"> ID of the token for which to retrieve the approved 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"> address</span><span class="z-comment"> Address of the account that is approved to manage the specified token&#39;s assets</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"> getApprovedForAssets</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"> Used to add or remove an operator of assets for the caller.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Operators can call {acceptAsset}, {rejectAsset}, {rejectAllAssets} or {setPriority} for any token</span></span> <span class="giallo-l"><span class="z-comment"> * owned by the caller.</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"> * - The `operator` cannot be the caller.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emits an {ApprovalForAllForAssets} 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"> operator</span><span class="z-comment"> Address of the account to which the operator role is granted or revoked from</span></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 boolean value indicating whether the operator role is being granted (`true`) or revoked</span></span> <span class="giallo-l"><span class="z-comment"> * (`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"> setApprovalForAllForAssets</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> <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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Used to check whether the address has been granted the operator role by a given address or not.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> See {setApprovalForAllForAssets}.</span></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 of the account that we are checking for whether it has granted the operator role</span></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 of the account that we are checking whether it has the operator role or 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"> bool</span><span class="z-comment"> The boolean value indicating whether the account we are checking has been granted the operator 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"> isApprovedForAllForAssets</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> <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> <p>The <code>getAssetMetadata</code> function returns the asset's metadata URI. The metadata, to which the metadata URI of the asset points, MAY contain a JSON response with the following fields:</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">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">The description of the token or asset</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">mediaUri</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ipfs://mediaOfTheAssetOrToken</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">thumbnailUri</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ipfs://thumbnailOfTheAssetOrToken</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">externalUri</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://uriToTheProjectWebsite</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">license</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">License 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">licenseUri</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://uriToTheLicense</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">tags</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">tags</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">used</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">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">help</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">marketplaces</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">categorize</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</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">asset</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">or</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>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">preferThumb</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> A boolean flag indicating to UIs to prefer thumbnailUri instead of mediaUri wherever applicable</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> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">rarity</span><span class="z-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">value</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">epic</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-comment"> //</span><span class="z-comment"> For backward compatibility</span></span> <span class="giallo-l"><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">rarity</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">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">color</span><span class="z-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">value</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">red</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-comment"> //</span><span class="z-comment"> For backward compatibility</span></span> <span class="giallo-l"><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">color</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">label</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">height</span><span class="z-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">float</span><span class="z-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-constant"> 192.4</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> For backward compatibility</span></span> <span class="giallo-l"><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">height</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">display_type</span><span class="z-support">&quot;</span><span>:</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 class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>While this is the suggested JSON schema for the asset metadata, it is not enforced and MAY be structured completely differently based on implementer's preference.</p> <h2 id="rationale">Rationale</h2> <p>Designing the proposal, we considered the following questions:</p> <ol> <li><strong>Should we use Asset or Resource when referring to the structure that comprises the token?</strong><br /> The original idea was to call the proposal Multi-Resource, but while this denoted the broadness of the structures that could be held by a single token, the term <em>asset</em> represents it better.<br /> An asset is defined as something that is owned by a person, company, or organization, such as money, property, or land. This is the best representation of what an asset of this proposal can be. An asset in this proposal can be a multimedia file, technical information, a land deed, or anything that the implementer has decided to be an asset of the token they are implementing.</li> <li><strong>Why are <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> permit-style signatures to manage approvals not used?</strong><br /> For consistency. This proposal extends ERC-721 which already uses 1 transaction for approving operations with tokens. It would be inconsistent to have this and also support signing messages for operations with assets.</li> <li><strong>Why use indexes?</strong><br /> To reduce the gas consumption. If the asset ID was used to find which asset to accept or reject, iteration over arrays would be required and the cost of the operation would depend on the size of the active or pending assets arrays. With the index, the cost is fixed. A list of active and pending assets arrays per token need to be maintained, since methods to get them are part of the proposed interface.<br /> To avoid race conditions in which the index of an asset changes, the expected asset ID is included in operations requiring asset index, to verify that the asset being accessed using the index is the expected asset.<br /> Implementation that would internally keep track of indices using mapping was attempted. The average cost of adding an asset to a token increased by over 25%, costs of accepting and rejecting assets also increased 4.6% and 7.1% respectively. We concluded that it is not necessary for this proposal and can be implemented as an extension for use cases willing to accept this cost. In the sample implementation provided, there are several hooks which make this possible.</li> <li><strong>Why is a method to get all the assets not included?</strong><br /> Getting all assets might not be an operation necessary for all implementers. Additionally, it can be added either as an extension, doable with hooks, or can be emulated using an indexer.</li> <li><strong>Why is pagination not included?</strong><br /> Asset IDs use <code>uint64</code>, testing has confirmed that the limit of IDs you can read before reaching the gas limit is around 30.000. This is not expected to be a common use case so it is not a part of the interface. However, an implementer can create an extension for this use case if needed.</li> <li><strong>How does this proposal differ from the other proposals trying to address a similar problem?</strong><br /> After reviewing them, we concluded that each contains at least one of these limitations: <ul> <li>Using a single URI which is replaced as new assets are needed, this introduces a trust issue for the token owner.</li> <li>Focusing only on a type of asset, while this proposal is asset type agnostic.</li> <li>Having a different token for each new use case, this means that the token is not forward-compatible.</li> </ul> </li> </ol> <h3 id="multi-asset-storage-schema">Multi-Asset Storage Schema</h3> <p>Assets are stored within a token as an array of <code>uint64</code> identifiers.</p> <p>In order to reduce redundant on-chain string storage, multi asset tokens store assets by reference via inner storage. An asset entry on the storage is stored via a <code>uint64</code> mapping to asset data.</p> <p>An asset array is an array of these <code>uint64</code> asset ID references.</p> <p>Such a structure allows that, a generic asset can be added to the storage one time, and a reference to it can be added to the token contract as many times as we desire. Implementers can then use string concatenation to procedurally generate a link to a content-addressed archive based on the base <em>SRC</em> in the asset and the <em>token ID</em>. Storing the asset in a new token will only take 16 bytes of storage in the asset array per token for recurrent as well as <code>tokenId</code> dependent assets.</p> <p>Structuring token's assets in such a way allows for URIs to be derived programmatically through concatenation, especially when they differ only by <code>tokenId</code>.</p> <h3 id="propose-commit-pattern-for-asset-addition">Propose-Commit pattern for asset addition</h3> <p>Adding assets to an existing token MUST be done in the form of a propose-commit pattern to allow for limited mutability by a 3rd party. When adding an asset to a token, it is first placed in the <em>"Pending"</em> array, and MUST be migrated to the <em>"Active"</em> array by the token's owner. The <em>"Pending"</em> assets array SHOULD be limited to 128 slots to prevent spam and griefing.</p> <h3 id="asset-management">Asset management</h3> <p>Several functions for asset management are included. In addition to permissioned migration from "Pending" to "Active", the owner of a token MAY also drop assets from both the active and the pending array -- an emergency function to clear all entries from the pending array MUST also be included.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The MultiAsset token standard has been made compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> in order to take advantage of the robust tooling available for implementations of ERC-721 and to ensure compatibility with existing ERC-721 infrastructure.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests are included in <a href="https://wg-eips.ritovision.com/5773/./assets/test/multiasset.ts"><code>multiasset.ts</code></a>.</p> <p>To run them in terminal, you can use the following commands:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>cd ../assets/eip-5773</span></span> <span class="giallo-l"><span>npm install</span></span> <span class="giallo-l"><span>npx hardhat test</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/5773/./assets/contracts/MultiAssetToken.sol"><code>MultiAssetToken.sol</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The same security considerations as with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> apply: hidden logic may be present in any of the functions, including burn, add asset, accept asset, and more.</p> <p>Caution is advised when dealing with non-audited 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> 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-10-04T00:00:00+00:00 2026-02-11T14:49:27+00:00 Kosala Hemachandrahttps://github.com/kvhnuke https://wg-eips.ritovision.com/5749/

Add 'window.evmproviders' and suggest the eventual removal of 'window.ethereum'

<h2 id="abstract">Abstract</h2> <p>A Javascript Ethereum Provider interface injection that will allow for the interoperability of multiple browser wallets at the same time. Replacing <code>window.ethereum</code> with <code>window.evmproviders</code> is a simple solution that will provide multiple benefits including: improving user experience, encouraging innovation in the space, removing race conditions and a 'winner-takes-most' environment as well as lowering barriers for user adoption.</p> <h2 id="motivation">Motivation</h2> <p>At present, <code>window.ethereum</code> is the prevailing method by which Ethereum-compatible applications interact with injected wallets. This originated with Mist Wallet in 2015 to interact with other applications. With the proliferation of both applications and wallets, <code>window.ethereum</code> has unintended negative consequences:</p> <ul> <li><code>window.ethereum</code> only permits one wallet to be injected at a time, resulting in a race condition between two or more wallets. This creates an inconsistent connection behavior that makes having and using more than one browser wallet unpredictable and impractical. The current solution is for wallets to inject their own namespaces, but this is not feasible as every application would need to be made aware of any wallet that might be used.</li> <li>The aforementioned race condition means users are disincentivized to experiment with new wallets. This creates a 'winner-takes-most' wallet market across EVM chains which forces application developers to optimize for a particular wallet experience.</li> <li>The 'winner-takes-most' wallet environment that results from the <code>window.ethereum</code> standard hinders innovation because it creates a barrier to adoption. New entrants into the space have difficulty gaining traction against legacy players because users can have no more than one injected wallet. With new entrants crowded out, legacy wallet providers are put under little pressure to innovate.</li> <li>Wallets continue to be the most fundamental tool for interacting with blockchains. A homogeneous wallet experience in Ethereum and EVM chains risks stunting UX improvement across the ecosystem and will allow other ecosystems that are more encouraging of competition and innovation to move ahead.</li> <li>Some wallets that currently use <code>window.ethereum</code> as of August, 2022. Currently a user will have inconsistent behavior if they use multiple of these wallets in a single browser. <ul> <li>Metamask</li> <li>Coinbase wallet</li> <li>Enkrypt</li> <li>Trust wallet</li> <li>Rainbow</li> </ul> </li> </ul> <p>Replacing <code>window.ethereum</code> with <code>window.evmproviders</code> will allow solutions such as web3modal and web3onboard to display all injected wallets the user has installed. This will simplify the UX and remove race conditions between wallet providers in case multiple wallets are installed. Over time, as <code>window.evmproviders</code> supplants the current standard and removes barriers to choice, we can hope to see a wallet landscape more reflective of user preference.</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="window-evmproviders"><code>window.evmproviders={}</code></h3> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * Represents the assets needed to display a wallet</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">interface</span><span class="z-entity z-name"> ProviderInfo</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"> * A UUIDv4 unique to the wallet provider.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * This must remain the same across versions but must be different across channels. For example, MetaMask, Trust wallet and Enkrypt should each have different UUIDs, but MetaMask 10.22.2 and MetaMask 9.8.1 should have the same UUID.</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">readonly</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-variable"> uuid</span><span class="z-keyword">:</span><span class="z-support"> string</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"> * The name of the wallet provider (e.g. `MetaMask` or `Enkrypt`)</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">readonly</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</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-punctuation z-definition z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * A base64 encoded SVG image.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Base64 is defined in RFC 4648.</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">readonly</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-variable"> icon</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> `</span><span class="z-string">data:image/svg+xml;base64,</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * A description of the wallet provider.</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">readonly</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-variable"> description</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * Represents the new Provider with info type that extends the EIP1193 provider</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">interface</span><span class="z-entity z-name"> ProviderWithInfo</span><span class="z-storage"> extends</span><span class="z-entity"> EIP1193Provider</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> info</span><span class="z-keyword">:</span><span class="z-entity z-name"> ProviderInfo</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Type <code>EIP1193Provider</code> is documented at <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a></p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * The type of `window.evmproviders`</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">interface</span><span class="z-entity z-name"> EVMProviders</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"> * The key is RECOMMENDED to be the name of the extension in snake_case. It MUST contain only lowercase letters, numbers, and underscores.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span> [</span><span class="z-variable">index</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>]</span><span class="z-keyword">:</span><span class="z-entity z-name"> ProviderWithInfo</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Standardizing a <code>ProviderInfo</code> type allows determining the necessary information to populate a wallet selection popup. This is particularly useful for web3 onboarding libraries such as Web3Modal, Web3React, and Web3Onboard.</p> <p>The name <code>evmproviders</code> was chosen to include other EVM-compliant chains.</p> <p>The SVG image format was chosen for its flexibility, lightweight nature, and dynamic resizing capabilities.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP doesn't require supplanting <code>window.ethereum</code>, so it doesn't directly break existing applications. However, the recommended behavior of eventually supplanting <code>window.ethereum</code> would break existing applications that rely on it.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="injection">Injection</h3> <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"> provider</span><span class="z-keyword">:</span><span class="z-entity z-name"> ProviderWithInfo</span><span class="z-keyword"> =</span><span> [</span><span class="z-variable z-other">your</span><span class="z-variable z-other"> wallet</span><span>]</span></span> <span class="giallo-l"><span class="z-variable z-other">window</span><span>.</span><span class="z-variable z-other">evmproviders</span><span class="z-keyword"> =</span><span class="z-variable z-other"> window</span><span>.</span><span class="z-variable z-other">evmproviders</span><span class="z-keyword"> ||</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-variable z-other">evmproviders</span><span>[</span><span class="z-variable z-other">name</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-other"> provider</span></span></code></pre><h3 id="retrieving-all-evm-providers">Retrieving all EVM providers</h3> <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"> allproviders</span><span class="z-keyword"> =</span><span class="z-variable z-other"> Object</span><span>.</span><span class="z-entity z-name">values</span><span>(</span><span class="z-variable z-other">window</span><span>.</span><span class="z-variable z-other">evmproviders</span><span>)</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>The security considerations of EIP-1193 apply to this EIP.</p> <p>The use of SVG images introduces a cross-site scripting risk as they can include JavaScript code. Applications and libraries must render SVG images using the <code>&lt;img&gt;</code> tag to ensure no JS executions can happen.</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-04T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv https://wg-eips.ritovision.com/5750/

Designating last param of dynamically sized bytes to be used for behavior extensions of methods.

<h2 id="abstract">Abstract</h2> <p>This EIP standardizes the passing of unstructured call data to functions to enable future extensibility.</p> <h2 id="motivation">Motivation</h2> <p>The purpose of having extra data in a method is to allow further extensions to existing method interfaces.</p> <p>It is it useful to make methods extendable. Any methods complying with this EIP, such as overloaded <code>transfer</code> and <code>vote</code> could use string reasons as the extra data. Existing EIPs that have exported methods compliant with this EIP can be extended for behaviors such as using the extra data to prove endorsement, as a salt, as a nonce, or as a commitment for a reveal/commit scheme. Finally, data can be passed forward to callbacks.</p> <p>There are two ways to achieve extensibility for existing functions. Each comes with their set of challenges:</p> <ol> <li>Add a new method</li> </ol> <ul> <li>What will the method name be?</li> <li>What will the parameters be?</li> <li>How many use-cases does a given method signature support?</li> <li>Does this support off-chain signatures?</li> </ul> <ol start="2"> <li>Use one or more existing parameters, or add one or more new ones</li> </ol> <ul> <li>Should existing parameters be repurposed, or should more be added?</li> <li>How many parameters should be used?</li> <li>What are their sizes and types?</li> </ul> <p>Standardizing how methods can be extended helps to answer these questions.</p> <p>Finally, this EIP aims to achieve maximum backward and future compatibility. Many EIPs already partially support this EIP, 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>. This EIP supports many use cases, from commit-reveal schemes (<a href="https://wg-eips.ritovision.com/5732/">EIP-5732</a>), to adding digital signatures alongside with a method call. Other implementers and EIPs should be able to depend on the compatibility granted by this EIP so that all compliant method interfaces are eligible for future new behaviors.</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> <p>When used in this EIP, the term <code>bytes</code> MUST be interpreted as the dynamically-sized byte array in Solidity data types.</p> <ol> <li> <p>Unlike many other ERCs which is compliant at the <code>contract</code> level, this ERC's specification specify compliance at <code>method</code> level.</p> </li> <li> <p>Any method with a bytes as this method's last parameter is an <em>eligible</em> method. It looks like this <code>function methodName(type1 value1, type2 value2, ... bytes data)</code>.</p> </li> <li> <p>A <em>compliant</em> method MUST be an <em>eligible</em> method and MUST also designate that last <code>bytes</code> field in its method parameter for behaviors extensions.</p> </li> <li> <p>If an <em>eligible</em> method has an overloaded sibling method that has the exact same method name and exact same preceding parameters except for not having the last <code>bytes</code> parameter, the behavior of the compliant method MUST be identical to its overloaded sibling method when last <code>bytes</code> is an empty array.</p> </li> </ol> <h3 id="examples-of-compliant-and-non-compliant-methods">Examples of compliant and non-compliant methods</h3> <ol> <li>Here is a compliant method <code>methodName1</code> in a <code>Foo</code> contract</li> </ol> <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"> Foo</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev This method allows extension behavior via `_data` field;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> methodName1</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _param1</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _param2</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>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> firstNonRelatedMethod</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> someValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> secondNonRelatedMethod</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> someValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ol start="2"> <li>Here is a compliant method <code>methodName2</code> in a <code>Bar</code> contract which is an overloaded method for another <code>methodName2</code>.</li> </ol> <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"> Foo</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev This is a sibling method to `methodName2(uint256 _param1, address _param2, bytes calldata _data);`</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> methodName2</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _param1</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _param2</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev This method allows extension behavior via `_data` field;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> When passed in an empty array for `_data` field, this method</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> MUST behave IDENTICAL to</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> its overloaded sibling `methodName2(uint256 _param1, address _param2);`</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> methodName2</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _param1</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _param2</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>;</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"> firstNonRelatedMethod</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> someValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> secondNonRelatedMethod</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> someValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ol start="3"> <li>Here is a non-compliant method <code>methodName1</code> because it do not allow extending behavior</li> </ol> <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"> Foo</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev This method DO NOT allow extension behavior via `_data` field;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> methodName1</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _param1</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _param2</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>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> firstNonRelatedMethod</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> someValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> secondNonRelatedMethod</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> someValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ol start="4"> <li>Here is a non-compliant method <code>methodName2(uint256 _param1, address _param2, bytes calldata _data);</code> because it behaves differently to its overloaded sibling method <code>methodName2(uint256 _param1, address _param2);</code> when <code>_data</code> is empty array.</li> </ol> <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"> Foo</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev This is a sibling method to `methodName2(uint256 _param1, address _param2, bytes calldata _data);`</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> methodName2</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _param1</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _param2</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev This method allows extension behavior via `_data` field;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> When passed in an empty array for `_data` field, this method</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> behave DIFFERENTLY to</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> its overloaded sibling `methodName2(uint256 _param1, address _param2);`</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> methodName2</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _param1</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _param2</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>;</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"> firstNonRelatedMethod</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> someValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> secondNonRelatedMethod</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> someValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <ol> <li>Using the dynamically-sized <code>bytes</code> type allows for maximum flexibility by enabling payloads of arbitrary types.</li> <li>Having the bytes specified as the last parameter makes this EIP compatible with the calldata layout of solidity.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Many existing EIPs already have compliant methods as part of their specification. All contracts compliant with those EIPs are either fully or partially compliant with this EIP.</p> <p>Here is an incomplete list:</p> <ul> <li>In <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>, the following method is already compliant: <ul> <li><code>function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes data) external payable;</code> is already compliant</li> </ul> </li> <li>In <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>, the following methods are already compliant <ul> <li><code>function safeTransferFrom(address _from, address _to, uint256 _id, uint256 _value, bytes calldata _data) external;</code></li> <li><code>function safeBatchTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values, bytes calldata _data) external;</code></li> </ul> </li> <li>In <a href="https://wg-eips.ritovision.com/777/">EIP-777</a>, the following methods are already compliant <ul> <li><code>function burn(uint256 amount, bytes calldata data) external;</code></li> <li><code>function send(address to, uint256 amount, bytes calldata data) external;</code></li> </ul> </li> </ul> <p>However, not all functions that have a <code>bytes</code> as the last parameter are compliant. The following functions are not compliant without an overload since their last parameter is involved in functionality:</p> <ul> <li>In <a href="https://wg-eips.ritovision.com/2535/">EIP-2535</a>, the following methods is not compliant: <ul> <li><code>function diamondCut(FacetCut[] calldata _diamondCut, address _init, bytes calldata _calldata) external;</code></li> <li><strong>Either</strong> of the following can be done to create a compliance. <ol> <li>An overload MUST be created: <code>function diamondCut(FacetCut[] calldata _diamondCut, address _init, bytes calldata _calldata, bytes calldata _data) external;</code> which adds a new <code>_data</code> after all parameters of original method.</li> <li>The use of <code>bytes memory _calldata</code> MUST be relaxed to allow for extending behaviors.</li> </ol> </li> </ul> </li> <li>In <a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a>, the following method is not compliant: <ul> <li><code>function isValidSignature(bytes32 _hash, bytes memory _signature) public view returns (bytes4 magicValue);</code></li> <li><strong>Either</strong> of the following can be done to create a compliance: <ol> <li>An new overload MUST be created: <code>function isValidSignature(bytes32 _hash, bytes memory _signature, bytes calldata _data) public view returns (bytes4 magicValue);</code> which adds a new <code>_data</code> after all parameters of original method.</li> <li>The use of <code>bytes memory _signature</code> MUST be relaxed to allow for extending behaviors.</li> </ol> </li> </ul> </li> </ul> <h2 id="security-considerations">Security Considerations</h2> <ol> <li>If using the extra data for extended behavior, such as supplying signature for onchain verification, or supplying commitments in a commit-reveal scheme, best practices should be followed for those particular extended behaviors.</li> <li>Compliant contracts must also take into consideration that the data parameter will be publicly revealed when submitted into the mempool or included in a block, so one must consider the risk of replay and transaction ordering attacks. <strong>Unencrypted personally identifiable information must never be included in the data parameter.</strong></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-09-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv Matt Stamhttps://github.com/mattstam https://wg-eips.ritovision.com/5732/

A simple but general commit interface to support commit-reveal scheme.

<h2 id="abstract">Abstract</h2> <p>A simple commit interface to support commit-reveal scheme which provides <strong>only</strong> a commit method but no reveal method, allowing implementations to integrate this interface with arbitrary reveal methods such as <code>vote</code> or <code>transfer</code>.</p> <h2 id="motivation">Motivation</h2> <ol> <li>support commit-reveal privacy for applications such as voting.</li> <li>make it harder for attackers for front-running, back-running or sandwich attacks.</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>Interfaces referenced in this specification are as follows:</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"> &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-comment"> The EIP-165 identifier of this interface is 0xf14fcbc8</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC_COMMIT_CORE</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> commit</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _commitment</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> <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-comment">//</span><span class="z-comment"> The EIP-165 identifier of this interface is 0x67b2ec2c</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC_COMMIT_GENERAL</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Commit</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"> _timePoint</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"> bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _commitment</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> _extraData</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> commitFrom</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"> bytes32</span><span class="z-variable z-parameter z-function"> _commitment</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 z-parameter z-function"> _extraData</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> payable</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"> timePoint</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ol> <li> <p>A compliant contract MUST implement the <code>IERC_COMMIT_CORE</code> interface.</p> </li> <li> <p>A compliant contract SHOULD implement the <code>IERC_COMMIT_GENERAL</code> interface.</p> </li> <li> <p>A compliant contract that implements the <code>IERC_COMMIT_GENERAL</code> interface MUST accept <code>commit(_commitment)</code> as equivalent to <code>commitFrom(msg.sender, _commitment, [/*empty array*/])</code>.</p> </li> <li> <p>The <code>timePoint</code> return value of <code>commitFrom</code> is RECOMMENDED to use <code>block.timestamp</code> or <code>block.number</code> or a number that indicates the ordering of different commitments. When <code>commitFrom</code> is being called.</p> </li> <li> <p>A compliant contract that implements <code>IERC_COMMIT_GENERAL</code> MUST emit event <code>Commit</code> when a commitment is accepted and recorded. In the parameter of both <code>Commit</code> and the <code>commitFrom</code> method, the <code>_timePoint</code> is a time-point-representing value that represents ordering of commitments in which a latter commitment will always have a <em>greater or equal value</em> than a former commitment, such as <code>block.timestamp</code> or <code>block.number</code> or other time scale chosen by implementing contracts.</p> </li> <li> <p>The <code>extraData</code> is reserved for future behavior extension. If the <code>_from</code> is different from the TX signer, it is RECOMMENDED that compliant contract SHOULD validate signature for <code>_from</code>. For EOAs this will be validating its ECDSA signatures on chain. For smart contract accounts, it is RECOMMENDED to use <a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a> to validate the signatures.</p> </li> <li> <p>One or more methods of a compliant contract MAY be used for reveal.</p> </li> </ol> <p>But there MUST be a way to supply an extra field of <code>secret_salt</code>, so that committer can later open the <code>secret_salt</code> in the reveal TX that exposes the <code>secret_salt</code>. The size and location of <code>secret_salt</code> is intentionally unspecified in this EIP to maximize flexibility for integration.</p> <ol start="8"> <li>It is RECOMMENDED for compliant contracts to implement <a href="https://wg-eips.ritovision.com/165/">EIP-165</a>.</li> </ol> <h2 id="rationale">Rationale</h2> <ol> <li> <p>One design options is that we can attach a Commit Interface to any individual ERCs such as voting standards or token standards. We choose to have a simple and generalize commit interface so all ERCs can be extended to support commit-reveal without changing their basic method signatures.</p> </li> <li> <p>The key derived design decision we made is we will have a standardized <code>commit</code> method without a standardized <code>reveal</code> method, making room for customized reveal method or using <code>commit</code> with existing standard.</p> </li> <li> <p>We chose to have a simple one parameter method of <code>commit</code> in our Core interface to make it fully backward compatible with a few prior-adoptions e.g. ENS</p> </li> <li> <p>We also add a <code>commitFrom</code> to easy commitment being generated off-chain and submitted by some account on behalf by another account.</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is backward compatible with all existing ERCs method signature that has extraData. New EIPs can be designed with an extra field of "salt" to make it easier to support this EIP, but not required.</p> <p>The <code>IERC_COMMIT_CORE</code> is backward compatible with ENS implementations and other existing prior-art.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="commit-with-ens-register-as-reveal">Commit with ENS Register as Reveal</h3> <p>In ENS registering process, currently inside of <code>ETHRegistrarController</code> contract a commit function is being used to allow registerer fairly register a desire domain to avoid being front-run.</p> <p>Here is how ENS uses commitment in its registration logic:</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"> commit</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> commitment</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>commitments</span><span>[</span><span>commitment</span><span>]</span><span class="z-keyword"> +</span><span> maxCommitmentAge </span><span class="z-keyword">&lt;</span><span class="z-variable z-language"> now</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> commitments</span><span>[</span><span>commitment</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-language"> now</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>With this EIP it can be updated to</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"> commit</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> commitment</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"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>commitments</span><span>[</span><span>commitment</span><span>]</span><span class="z-keyword"> +</span><span> maxCommitmentAge </span><span class="z-keyword">&lt;</span><span class="z-variable z-language"> now</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> commitments</span><span>[</span><span>commitment</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-language"> now</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Commit</span><span>(</span><span>.</span><span>.</span><span>.</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <ol> <li>Do not use the reference implementation in production. It is just for demonstration purposes.</li> <li>The reveal transactions and parameters, especially <code>secret_salt</code>, MUST be kept secret before they are revealed.</li> <li>The length of <code>secret_salt</code> must be cryptographically long enough and the random values used to generate <code>secret_salt</code> must be cryptographically safe.</li> <li>Users must NEVER reuse a used <code>secret_salt</code>. It's recommended for client applications to warn users who attempt to do so.</li> <li>Contract implementations should consider deleting the commitment of a given sender immediately to reduce the chances of a replay attack or re-entry attack.</li> <li>Contract implementations may consider including the ordering of commitment received to add restrictions on the order of reveal transactions.</li> <li>There is potential for replay attacks across different chainIds or chains resulting from forks. In these cases, the chainId must be included in the generation of commitment. For applications with a higher risk of replay attacks, implementors should consider battle-tested and cryptographically-secure solutions such as <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> to compose commitments before creating their own new solution.</li> <li>Proper time gaps are suggested if the purpose is to avoid frontrunning attacks.</li> <li>For compliant contract that requires the <code>_timePoint</code> from the next transaction to be <em>strictly greater</em> than that of any previous transaction, <code>block.timestamp</code> and <code>block.number</code> are not reliable as two transactions could co-exist in the same block resulting in the same <code>_timePoint</code> value. In such case, extra measures to enforce this strict monotonicity are required, such as the use of a separate sate variable in the contract to keep track of number of commits it receives, or to reject any second/other TX that shares the same <code>block.timestamp</code> or <code>block.number</code>.</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-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-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Austin Zhuhttps://github.com/AustinZhu Terry Chenterry.chen@phaneroz.io https://wg-eips.ritovision.com/5727/

An interface for soulbound tokens, also known as badges or account-bound tokens, that can be both fungible and non-fungible.

<h2 id="abstract">Abstract</h2> <p>An interface for soulbound tokens (SBT), which are non-transferable tokens representing a person's identity, credentials, affiliations, and reputation.</p> <p>Our interface can handle a combination of fungible and non-fungible tokens in an organized way. It provides a set of core methods that can be used to manage the lifecycle of soulbound tokens, as well as a rich set of extensions that enables DAO governance, delegation, token expiration, and account recovery.</p> <p>This interface aims to provide a flexible and extensible framework for the development of soulbound token systems.</p> <h2 id="motivation">Motivation</h2> <p>The current Web3 ecosystem is heavily focused on financialized, transferable tokens. However, there's a growing need for non-transferable tokens to represent unique personal attributes and rights. Existing attempts within the Ethereum community to create such tokens lack the necessary flexibility and extensibility. Our interface addresses this gap, offering a versatile and comprehensive solution for SBTs.</p> <p>Our interface can be used to represent non-transferable ownerships, and provides features for common use cases including but not limited to:</p> <ul> <li>Lifecycle Management: Robust tools for minting, revocation, and managing the subscription and expiration of SBTs.</li> <li>DAO Governance and Delegation: Empower community-driven decisions and operational delegation for SBT management.</li> <li>Account Recovery: Advanced mechanisms for account recovery and key rotation, ensuring security and continuity.</li> <li>Versatility in Tokens: Support for both fungible and non-fungible SBTs, catering to a wide range of use cases like membership cards and loyalty programs.</li> <li>Token Grouping: Innovative slot-based system for organizing SBTs, ideal for complex reward structures including vouchers, points, and badges.</li> <li>Claimable SBTs: Streamlined distribution of SBTs for airdrops, giveaways, and referral programs.</li> </ul> <p>This interface not only enriches the Web3 landscape but also paves the way for a more decentralized and personalized digital society.</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 is identified by its <code>tokenId</code>, which is a 256-bit unsigned integer. A token can also have a value denoting its denomination.</p> <p>A slot is identified by its <code>slotId</code>, which is a 256-bit unsigned integer. Slots are used to group fungible and non-fungible tokens together, thus make tokens semi-fungible. A token can only belong to one slot at a time.</p> <h3 id="core">Core</h3> <p>The core methods are used to manage the lifecycle of SBTs. They MUST be supported by all semi-fungible SBT implementations.</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"> ERC5727 Soulbound Token Interface</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The core interface of the ERC5727 standard.</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"> IERC5727</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC3525</span><span>, </span><span class="z-entity z-name">IERC5192</span><span>, </span><span class="z-entity z-name">IERC5484</span><span>, </span><span class="z-entity z-name">IERC4906</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 token is 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"> from</span><span class="z-comment"> The address of 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"> tokenId</span><span class="z-comment"> The 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"> Revoked</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"> MUST emit when a token is verified.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> by</span><span class="z-comment"> The address that initiated the verification</span></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</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> result</span><span class="z-comment"> The result of the verification</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"> Verified</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> by</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">bool</span><span class="z-variable"> result</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 verifier of 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"> MUST revert if the `tokenId` 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"> the token for which to query the verifier</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 verifier 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"> verifierOf</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> <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">@dev</span><span class="z-comment"> MUST revert if the `tokenId` 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"> the token for which to query the issuer</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 issuer 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"> 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 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"> Issue a token in a specified slot to an address.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the `to` address is the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if the `verifier` address is 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"> The address to issue the token 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"> tokenId</span><span class="z-comment"> The 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"> slot</span><span class="z-comment"> The slot to issue the token in</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> burnAuth</span><span class="z-comment"> The burn authorization of 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"> verifier</span><span class="z-comment"> The address of the verifier</span></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 used to issue 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"> issue</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></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> slot</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> BurnAuth</span><span class="z-variable"> burnAuth</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> verifier</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"> 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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Issue credit to 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"> MUST revert if the `tokenId` 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"> The 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"> amount</span><span class="z-comment"> The amount of the credit</span></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 additional data used to issue the credit</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"> issue</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"> amount</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"> 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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Revoke a token from an address.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the `tokenId` 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"> The 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"> data</span><span class="z-comment"> The additional data used to revoke 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"> revoke</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</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>;</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"> Revoke credit from 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"> MUST revert if the `tokenId` 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"> The 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"> amount</span><span class="z-comment"> The amount of the credit</span></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 additional data used to revoke the credit</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 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"> amount</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"> 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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Verify if a token is valid.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the `tokenId` 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"> The 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"> data</span><span class="z-comment"> The additional data used to verify 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"> A</span><span class="z-comment"> boolean indicating whether the token is successfully verified</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"> verify</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-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><h3 id="extensions">Extensions</h3> <p>All extensions below are OPTIONAL for <a href="https://wg-eips.ritovision.com/5727/">ERC-5727</a> implementations. An implementation MAY choose to implement some, none, or all of them.</p> <h4 id="enumerable">Enumerable</h4> <p>This extension provides methods to enumerate the tokens of a owner. It is recommended to be implemented together with the core interface.</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"> ERC5727 Soulbound Token Enumerable Interface</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This extension allows querying the tokens of a owner.</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"> IERC5727Enumerable</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC3525SlotEnumerable</span><span>, </span><span class="z-entity z-name">IERC5727</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"> Get the number of slots of a 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"> The owner whose number of slots is queried 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"> number of slots of the `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"> slotCountOfOwner</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get the slot with `index` of the `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 revert if the `index` exceed the number of slots of 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"> The owner whose slot is queried 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"> index</span><span class="z-comment"> The index of the slot queried 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"> slot is queried 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"> slotOfOwnerByIndex</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"> index</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"> Get the balance of a owner in a slot.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the slot 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"> owner</span><span class="z-comment"> The owner whose balance is queried 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"> slot</span><span class="z-comment"> The slot whose balance is queried 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"> balance of the `owner` in the `slot`</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"> ownerBalanceInSlot</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"> slot</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><h4 id="metadata">Metadata</h4> <p>This extension provides methods to fetch the metadata of a token, a slot and the contract itself. It is recommended to be implemented if you need to specify the appearance and properties of tokens, slots and the contract (i.e. the SBT collection).</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"> ERC5727 Soulbound Token Metadata Interface</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This extension allows querying the metadata of soulbound tokens.</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"> IERC5727Metadata</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC3525Metadata</span><span>, </span><span class="z-entity z-name">IERC5727</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="governance">Governance</h4> <p>This extension provides methods to manage the mint and revocation permissions through voting. It is useful if you want to rely on a group of voters to decide the issuance a particular SBT.</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"> ERC5727 Soulbound Token Governance Interface</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This extension allows issuing of tokens by community voting.</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"> IERC5727Governance</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC5727</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> ApprovalStatus</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Pending</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Approved</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"> Removed</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"> Emitted when a token issuance approval is </span><span class="z-keyword">changed</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"> approvalId</span><span class="z-comment"> The id of the approval</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> creator</span><span class="z-comment"> The creator of the approval, zero address if the approval is 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"> status</span><span class="z-comment"> The status of the approval</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"> ApprovalUpdate</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"> approvalId</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"> creator</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> ApprovalStatus</span><span class="z-variable"> status</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 a voter approves an approval.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> voter</span><span class="z-comment"> The voter who approves the approval</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> approvalId</span><span class="z-comment"> The id of the approval</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"> Approve</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"> voter</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"> approvalId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> approve</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"> Create an approval of issuing 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"> MUST revert if the caller is not a voter.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if the `to` address is 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"> The owner which the token to mint 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"> tokenId</span><span class="z-comment"> The id of the token 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"> amount</span><span class="z-comment"> The amount of the token 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"> slot</span><span class="z-comment"> The slot of the token 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"> burnAuth</span><span class="z-comment"> The burn authorization of the token 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"> data</span><span class="z-comment"> The additional data used to mint 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"> requestApproval</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></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"> slot</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> BurnAuth</span><span class="z-variable"> burnAuth</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> verifier</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>;</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 `approvalId` approval request.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the caller is not the creator of the approval request.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if the approval request is already approved or rejected or non-existent.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> approvalId</span><span class="z-comment"> The approval to remove</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"> removeApprovalRequest</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> approvalId</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"> Approve `approvalId` approval request.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the caller is not a voter.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if the approval request is already approved or rejected or non-existent.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> approvalId</span><span class="z-comment"> The approval 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"> approve</span><span class="z-comment"> True if the approval is approved, false if the approval is rejected</span></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 additional data used to approve the approval (e.g. the signature, voting power)</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"> voteApproval</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> approvalId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> approve</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>;</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 URI of the approval.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the `approvalId` 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"> approvalId</span><span class="z-comment"> The approval whose URI is queried 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"> URI of the 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"> approvalURI</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> approvalId</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">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="delegate">Delegate</h4> <p>This extension provides methods to delegate (undelegate) mint right in a slot to (from) an operator. It is useful if you want to allow an operator to mint tokens in a specific slot on your behalf.</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"> ERC5727 Soulbound Token Delegate Interface</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This extension allows delegation of issuing and revocation of tokens to an operator.</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"> IERC5727Delegate</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC5727</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 a token issuance is delegated to an 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"> The owner to which the issuing right is delegated</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> slot</span><span class="z-comment"> The slot to issue the token in</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"> Delegate</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">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> slot</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 a token issuance is revoked from an 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"> The owner to which the issuing right is delegated</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> slot</span><span class="z-comment"> The slot to issue the token in</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"> UnDelegate</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">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> slot</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"> Delegate rights to `operator` for a slot.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the caller does not have the right to delegate.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if the `operator` address is the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if the `slot` is not a valid slot.</span></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 owner to which the issuing right is delegated</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> slot</span><span class="z-comment"> The slot to issue the token in</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"> delegate</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"> slot</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"> Revoke rights from `operator` for a slot.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the caller does not have the right to delegate.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if the `operator` address is the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if the `slot` is not a valid slot.</span></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 owner to which the issuing right is delegated</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> slot</span><span class="z-comment"> The slot to issue the token in</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"> undelegate</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"> slot</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"> Check if an operator has the permission to issue or revoke tokens in a slot.</span></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 operator to check</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> slot</span><span class="z-comment"> The slot to check</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"> isOperatorFor</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"> slot</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></span> <span class="giallo-l"></span></code></pre><h4 id="recovery">Recovery</h4> <p>This extension provides methods to recover tokens from a stale owner. It is recommended to use this extension so that users are able to retrieve their tokens from a compromised or old wallet in certain situations. The signing scheme SHALL be compatible with <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> for readability and usability.</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"> ERC5727 Soulbound Token Recovery Interface</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This extension allows recovering soulbound tokens from an address provided its signature.</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"> IERC5727Recovery</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC5727</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 tokens of `owner` are recovered.</span></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 owner whose tokens are recovered</span></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 new owner of the 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"> Recovered</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>;</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"> Recover the tokens of `owner` with `signature`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert if the signature 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"> owner</span><span class="z-comment"> The owner whose tokens are recovered</span></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"> The signature signed by the `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"> recover</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><h4 id="expirable">Expirable</h4> <p>This extension provides methods to manage the expiration of tokens. It is useful if you want to expire/invalidate tokens after a certain period of time.</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"> ERC5727 Soulbound Token Expirable Interface</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This extension allows soulbound tokens to be expirable and renewable.</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"> IERC5727Expirable</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC5727</span><span>, </span><span class="z-entity z-name">IERC5643</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"> Set the expiry date of 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"> MUST revert if the `tokenId` token does not exist.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if the `date` is in the past.</span></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 whose expiry date is 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"> expiration</span><span class="z-comment"> The expire date to 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"> isRenewable</span><span class="z-comment"> Whether the token is renewable</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"> setExpiration</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"> uint64</span><span class="z-variable"> expiration</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> isRenewable</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="token-storage-model">Token storage model</h3> <p>We adopt semi-fungible token storage models designed to support both fungible and non-fungible tokens, inspired by the semi-fungible token standard. We found that such a model is better suited to the representation of SBT than the model used in <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>.</p> <p>Firstly, each slot can be used to represent different categories of SBTs. For instance, a DAO can have membership SBTs, role badges, reputations, etc. in one SBT collection.</p> <p>Secondly, unlike <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>, in which each unit of fungible tokens is exactly the same, our interface can help differentiate between similar tokens. This is justified by that credential scores obtained from different entities differ not only in value but also in their effects, validity periods, origins, etc. However, they still share the same slot as they all contribute to a person's credibility, membership, etc.</p> <h3 id="recovery-mechanism">Recovery mechanism</h3> <p>To prevent the loss of SBTs, we propose a recovery mechanism that allows users to recover their tokens by providing a signature signed by their owner address. This mechanism is inspired by <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a>.</p> <p>Since SBTs are bound to an address and are meant to represent the identity of the address, which cannot be split into fractions. Therefore, each recovery should be considered as a transfer of all the tokens of the owner. This is why we use the <code>recover</code> function instead of <code>transferFrom</code> or <code>safeTransferFrom</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP proposes a new token interface which is compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, <a href="https://wg-eips.ritovision.com/3525/">ERC-3525</a>, <a href="https://wg-eips.ritovision.com/4906/">ERC-4906</a>, <a href="https://wg-eips.ritovision.com/5192/">ERC-5192</a>, <a href="https://wg-eips.ritovision.com/5484/">ERC-5484</a>.</p> <p>This EIP is also compatible with <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>.</p> <h2 id="test-cases">Test Cases</h2> <p>Our sample implementation includes test cases written using Hardhat.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>You can find our reference implementation <a href="https://wg-eips.ritovision.com/5727/./assets/ERC5727.sol">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP does not involve the general transfer of tokens, and thus there will be no security issues related to token transfer generally.</p> <p>However, users should be aware of the security risks of using the recovery mechanism. If a user loses his/her private key, all his/her soulbound tokens will be exposed to potential theft. The attacker can create a signature and restore all SBTs of the victim. Therefore, users should always keep their private keys safe. We recommend developers implement a recovery mechanism that requires multiple signatures to restore SBTs.</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-22T00:00:00+00:00 2026-02-11T14:48:25+00:00 Leerenhttps://github.com/leeren https://wg-eips.ritovision.com/5700/

Interface for binding fungible and non-fungible tokens to assets.

<h2 id="abstract">Abstract</h2> <p>This standard defines an interface for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> or <a href="https://wg-eips.ritovision.com/155/">ERC-1155</a> tokens, known as "bindables", to "bind" to <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> NFTs.</p> <p>When bindable tokens "bind" to an NFT, even though their ownership is transferred to the NFT, the NFT owner may "unbind" the tokens and claim their ownership. This enables bindable tokens to transfer with their bound NFTs without extra cost, offering a more effective way to create and transfer N:1 token-to-NFT bundles. Until an NFT owner decides to unbind them, bound tokens stay locked and resume their base token functionalities after unbinding.</p> <p>This standard supports various use-cases such as:</p> <ul> <li>NFT-bundled physical assets like microchipped streetwear, digitized car collections, and digitally twinned real estate.</li> <li>NFT-bundled digital assets such as accessorizable virtual wardrobes, composable music tracks, and customizable metaverse land.</li> </ul> <h2 id="motivation">Motivation</h2> <p>A standard interface for NFT binding offers a seamless and efficient way to bundle and transfer tokens with NFTs, ensuring compatibility with wallets, marketplaces, and other NFT applications. It eliminates the need for rigid, implementation-specific strategies for token ownership.</p> <p>In contrast with other standards that deal with token ownership at the account level, this standard aims to address token ownership at the NFT level. Its objective is to build a universal interface for token bundling, compatible with existing <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> 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> <h3 id="erc-721-bindable">ERC-721 Bindable</h3> <p><strong>Smart contracts implementing the ERC-721 bindable standard MUST implement the <code>IERC721Bindable</code> interface.</strong></p> <p><strong>Implementers of the <code>IER721Bindable</code> interface MUST return <code>true</code> if <code>0x82a34a7d</code> is passed as the identifier to the <code>supportsInterface</code> function.</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-721 Bindable Token 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/ERCS/eip-5700</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 0x82a34a7d.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC721Bindable</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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> This event emits when an unbound token is bound to 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"> operator</span><span class="z-comment"> The address approved to perform the binding.</span></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 of the unbound 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"> bindAddress</span><span class="z-comment"> The contract address of the NFT being bound 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"> bindId</span><span class="z-comment"> The identifier of the NFT being bound 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"> tokenId</span><span class="z-comment"> The identifier of binding token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Bind</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"> 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"> bindAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> bindId</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>;</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"> This event emits when an NFT-bound token is unbound.</span></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 approved to perform the unbinding.</span></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 owner of the NFT the token is bound 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"> The address of the new unbound 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"> bindAddress</span><span class="z-comment"> The contract address of the NFT being unbound from.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> bindId</span><span class="z-comment"> The identifier of the NFT being unbound from.</span></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 of the unbinding token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Unbind</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"> 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-variable"> to</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"> bindAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> bindId</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>;</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"> Binds token `tokenId` to NFT `bindId` at address `bindAddress`.</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 MUST throw unless `msg.sender` is the current owner, </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> an authorized operator, or the approved address for the token. It also</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST throw if the token is already bound or if `from` is not the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> owner. Finally, it MUST throw if the NFT contract does not support the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ERC-721 interface or if the NFT being bound to does not exist. Before </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> binding, token ownership MUST be transferred to the contract address of</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the NFT. On bind completion, the function MUST emit `Transfer` &amp; `Bind` </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> events to reflect the implicit token transfer and subsequent bind.</span></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 of the unbound 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"> bindAddress</span><span class="z-comment"> The contract address of the NFT being bound 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"> bindId</span><span class="z-comment"> The identifier of the NFT being bound 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"> tokenId</span><span class="z-comment"> The identifier of the binding token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> bind</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"> bindAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> bindId</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>;</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"> Unbinds token `tokenId` from NFT `bindId` at address `bindAddress`.</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 MUST throw unless `msg.sender` is the current owner, </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> an authorized operator, or the approved address for the NFT the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> is bound to. It also MUST throw if the token is unbound, if `from` is</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> not the owner of the bound NFT, or if `to` is the zero address. After</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> unbinding, token ownership MUST be transferred to `to`, during which</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the function MUST check if `to` is a valid contract (code size &gt; 0),</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and if so, call `onERC721Received`, throwing if the wrong identifier is</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> returned. On unbind completion, the function MUST emit `Unbind` &amp;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `Transfer` events to reflect the unbind and subsequent 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"> from</span><span class="z-comment"> The address of the owner of the NFT the token is bound 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"> The address of the unbound token new 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"> bindAddress</span><span class="z-comment"> The contract address of the NFT being unbound from.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> bindId</span><span class="z-comment"> The identifier of the NFT being unbound from.</span></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 of the unbinding token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unbind</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"> address</span><span class="z-variable"> bindAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> bindId</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>;</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 NFT address and identifier token `tokenId` is bound to.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> When the token is unbound, this function MUST return the zero</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> address for the address portion to indicate no binding 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 of the token being 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"> The</span><span class="z-comment"> token-bound NFT contract address and numerical identifier.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> binderOf</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 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"> Gets total tokens bound to NFT `bindId` at address `bindAddress`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> bindAddress</span><span class="z-comment"> The contract address of the NFT being 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"> bindId</span><span class="z-comment"> The identifier of the NFT being 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"> The</span><span class="z-comment"> total number of tokens bound to the queried NFT.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> boundBalanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> bindAddress</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> bindId</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></code></pre><h3 id="erc-1155-bindable">ERC-1155 Bindable</h3> <p><strong>Smart contracts implementing the ERC-1155 Bindable standard MUST implement the <code>IERC1155Bindable</code> interface.</strong></p> <p><strong>Implementers of the <code>IER1155Bindable</code> interface MUST return <code>true</code> if <code>0xd0d55c6</code> is passed as the identifier to the <code>supportsInterface</code> function.</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-1155 Bindable Token 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/ERCS/eip-5700</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 0xd0d555c6.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC1155Bindable</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC1155 </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"> This event emits when token(s) are bound to 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"> operator</span><span class="z-comment"> The address approved to perform the binding.</span></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 owner address of the unbound 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"> bindAddress</span><span class="z-comment"> The contract address of the NFT being bound 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"> bindId</span><span class="z-comment"> The identifier of the NFT being bound 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"> tokenId</span><span class="z-comment"> The identifier of the binding token type.</span></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"> The number of tokens binding to the NFT.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Bind</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"> 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"> bindAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> bindId</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"> 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 class="z-storage z-type"> @notice</span><span class="z-comment"> This event emits when token(s) of different types are bound to 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"> operator</span><span class="z-comment"> The address approved to perform the batch binding.</span></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 owner address of the unbound 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"> bindAddress</span><span class="z-comment"> The contract address of the NFTs being bound 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"> bindId</span><span class="z-comment"> The identifier of the NFT being bound 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"> tokenIds</span><span class="z-comment"> The identifiers of the binding token types.</span></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"> The number of tokens per type binding to the NFTs.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> BindBatch</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"> 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"> bindAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> bindId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> tokenIds</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> amounts</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"> This event emits when token(s) are unbound from 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"> operator</span><span class="z-comment"> The address approved to perform the unbinding.</span></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 owner address of the NFT the tokens are bound 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"> The address of the unbound tokens&#39; new 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"> bindAddress</span><span class="z-comment"> The contract address of the NFT being unbound from.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> bindId</span><span class="z-comment"> The identifier of the NFT being unbound from.</span></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 of the unbinding token type.</span></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"> The number of tokens unbinding from the NFT.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Unbind</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"> 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-variable"> to</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"> bindAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> bindId</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"> 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 class="z-storage z-type"> @notice</span><span class="z-comment"> This event emits when token(s) of different types are unbound from 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"> operator</span><span class="z-comment"> The address approved to perform the batch binding.</span></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 owner address of the unbound 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 of the unbound tokens&#39; new 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"> bindAddress</span><span class="z-comment"> The contract address of the NFTs being unbound from.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> bindId</span><span class="z-comment"> The identifier of the NFT being unbound from.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> The identifiers of the unbinding token types.</span></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"> The number of tokens per type unbinding from the NFTs.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UnbindBatch</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"> 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-variable"> to</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"> bindAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> bindId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> tokenIds</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> amounts</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"> Binds `amount` tokens of `tokenId` to NFT `bindId` at address `bindAddress`.</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 MUST throw unless `msg.sender` is an approved operator</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> for `from`. It also MUST throw if the `from` owns fewer than `amount`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> tokens. Finally, it MUST throw if the NFT contract does not support the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ERC-721 interface or if the NFT being bound to does not exist. Before </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> binding, tokens MUST be transferred to the contract address of the NFT. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> On bind completion, the function MUST emit `Transfer` &amp; `Bind` events </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> to reflect the implicit token transfers and subsequent bind.</span></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 owner address of the unbound 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"> bindAddress</span><span class="z-comment"> The contract address of the NFT being bound 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"> bindId</span><span class="z-comment"> The identifier of the NFT being bound 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"> tokenId</span><span class="z-comment"> The identifier of the binding token type.</span></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"> The number of tokens binding to the NFT.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> bind</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"> bindAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> bindId</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"> 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 class="z-storage z-type"> @notice</span><span class="z-comment"> Binds `amounts` tokens of `tokenIds` to NFT `bindId` at address `bindAddress`.</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 MUST throw unless `msg.sender` is an approved operator</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> for `from`. It also MUST throw if the length of `amounts` is not the </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> same as `tokenIds`, or if any balances of `tokenIds` for `from` is less</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> than that of `amounts`. Finally, it MUST throw if the NFT contract does </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> not support the ERC-721 interface or if the bound NFT does not exist. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Before binding, tokens MUST be transferred to the contract address of </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the NFT. On bind completion, the function MUST emit `TransferBatch` and</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `BindBatch` events to reflect the batch token transfers and bind.</span></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 owner address of the unbound 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"> bindAddress</span><span class="z-comment"> The contract address of the NFTs being bound 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"> bindId</span><span class="z-comment"> The identifier of the NFT being bound 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"> tokenIds</span><span class="z-comment"> The identifiers of the binding token types.</span></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"> The number of tokens per type binding to the NFTs.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> batchBind</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"> bindAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> bindId</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"> tokenIds</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Unbinds `amount` tokens of `tokenId` from NFT `bindId` at address `bindAddress`.</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 MUST throw unless `msg.sender` is an approved operator</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> for `from`. It also MUST throw if `from` is not the owner of the bound</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> NFT, if the NFT&#39;s token balance is fewer than `amount`, or if `to` is </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the zero address. After unbinding, tokens MUST be transferred to `to`,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> during which the function MUST check if `to` is a valid contract (code </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> size &gt; 0), and if so, call `onERC1155Received`, throwing if the wrong \</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> identifier is returned. On unbind completion, the function MUST emit </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `Unbind` &amp; `Transfer` events to reflect the unbind and transfers.</span></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 owner address of the NFT the tokens are bound 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"> The address of the unbound tokens&#39; new 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"> bindAddress</span><span class="z-comment"> The contract address of the NFT being unbound from.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> bindId</span><span class="z-comment"> The identifier of the NFT being unbound from.</span></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 of the unbinding token type.</span></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"> The number of tokens unbinding from the NFT.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unbind</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"> address</span><span class="z-variable"> bindAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> bindId</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"> 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 class="z-storage z-type"> @notice</span><span class="z-comment"> Unbinds `amount` tokens of `tokenId` from NFT `bindId` at address `bindAddress`.</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 MUST throw unless `msg.sender` is an approved operator</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> for `from`. It also MUST throw if the length of `amounts` is not the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> same as `tokenIds`, if any balances of `tokenIds` for the NFT is less </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> than that of `amounts`, or if `to` is the zero addresss. After </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> unbinding, tokens MUST be transferred to `to`, during which the </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> function MUST check if `to` is a valid contract (code size &gt; 0), and if </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> so, call `onERC1155BatchReceived`, throwing if the wrong identifier is </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> returned. On unbind completion, the function MUST emit `UnbindBatch` &amp; </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `TransferBatch` events to reflect the batch unbind and transfers.</span></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 owner address of the unbound 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 of the unbound tokens&#39; new 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"> bindAddress</span><span class="z-comment"> The contract address of the NFTs being unbound from.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> bindId</span><span class="z-comment"> The identifier of the NFT being unbound from.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> The identifiers of the unbinding token types.</span></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"> The number of tokens per type unbinding from the NFTs.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> batchUnbind</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"> address</span><span class="z-variable"> bindAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> bindId</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"> tokenIds</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Gets the number of tokens of type `tokenId` bound to NFT `bindId` at address `bindAddress`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> bindAddress</span><span class="z-comment"> The contract address of the bound 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"> bindId</span><span class="z-comment"> The identifier of the bound 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 identifier of the token type bound to 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"> The</span><span class="z-comment"> number of tokens of type `tokenId` bound to the NFT.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> boundBalanceOf</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> bindAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> bindId</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Gets the number of tokens of types `bindIds` bound to NFTs `bindIds` at address `bindAddress`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> bindAddress</span><span class="z-comment"> The contract address of the bound NFTs.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> bindIds</span><span class="z-comment"> The identifiers of the bound NFTs.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> The identifiers of the token types bound to the NFTs.</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"> balances</span><span class="z-comment"> The bound balances for each token type / NFT pair.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> boundBalanceOfBatch</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> bindAddress</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"> bindIds</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"> tokenIds</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 class="z-storage z-type"> memory</span><span class="z-variable"> balances</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>A standard for token binding unlocks a new layer of composability for allowing wallets, applications, and protocols to interact with, trade, and display bundled NFTs. One example use-case of this is at Dopamine, where streetwear garments may be bundled with digital assets such as music, avatars, or digital-twins of the garments, by representing these assets as bindable tokens and binding them to microchips represented as NFTs.</p> <h3 id="binding-mechanism">Binding Mechanism</h3> <p>During binding, a bindable token's technical ownership is conferred to its bound NFT, while allowing the NFT owner to unbind at any time. A caveat of this lightweight design is that applications that have yet to adopt this standard will not show the bundled tokens as owned by the NFT owner.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The bindable token interface is designed to be compatible with existing ERC-721 and ERC-1155 standards.</p> <h2 id="reference-implementation">Reference Implementation</h2> <ul> <li><a href="https://wg-eips.ritovision.com/5700/./assets/erc721/ERC721Bindable.sol">ERC-721 Bindable</a>.</li> <li><a href="https://wg-eips.ritovision.com/5700/./assets/erc1155/ERC1155Bindable.sol">ERC-1155 Bindable</a>.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>During binding, because ownership is conferred to the bound NFT contract, implementations should take caution in ensuring unbinding may only be performed by the designated NFT owner.</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-17T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv https://wg-eips.ritovision.com/5679/

An extension for minting and burning EIP-20, EIP-721, and EIP-1155 tokens

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a consistent way to extend token standards for minting and burning.</p> <h2 id="motivation">Motivation</h2> <p>Minting and Burning are typical actions for creating and destroying tokens. By establishing a consistent way to mint and burn a token, we complete the basic lifecycle.</p> <p>Some implementations of <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> have been able to use <code>transfer</code> methods or the-like to mint and burn tokens. However, minting and burning change token supply. The access controls of minting and burning also usually follow different rules than transfer. Therefore, creating separate methods for burning and minting simplifies implementations and reduces security error.</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> <ol> <li>Any contract complying with <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> when extended with this EIP, <strong>MUST</strong> implement the following interface:</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> The EIP-165 identifier of this interface is 0xd0017968</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5679Ext20</span><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">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"> _amount</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>;</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 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"> _amount</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>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ol start="2"> <li>Any contract complying with <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> when extended with this EIP, <strong>MUST</strong> implement the following interface:</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> The EIP-165 identifier of this interface is 0xcce39764</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5679Ext721</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeMint</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"> 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>;</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 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"> _id</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>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ol start="3"> <li>Any contract complying with <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> when extended with this EIP, <strong>MUST</strong> implement the following interface:</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> The EIP-165 identifier of this interface is 0xf4cedd5a</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5679Ext1155</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeMint</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"> _amount</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>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeMintBatch</span><span>(</span><span class="z-support">address</span><span class="z-variable"> 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"> ids</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"> amounts</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>;</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 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"> _id</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"> bytes</span><span>[</span><span>]</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>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> burnBatch</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>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> ids</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"> amounts</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>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ol start="4"> <li> <p>When the token is being minted, the transfer events <strong>MUST</strong> be emitted as if the token in the <code>_amount</code> for EIP-20 and EIP-1155 and token id being <code>_id</code> for EIP-721 and EIP-1155 were transferred from address <code>0x0</code> to the recipient address identified by <code>_to</code>. The total supply <strong>MUST</strong> increase accordingly.</p> </li> <li> <p>When the token is being burned, the transfer events <strong>MUST</strong> be emitted as if the token in the <code>_amount</code> for EIP-20 and EIP-1155 and token id being <code>_id</code> for EIP-721 and EIP-1155 were transferred from the recipient address identified by <code>_to</code> to the address of <code>0x0</code>. The total supply <strong>MUST</strong> decrease accordingly.</p> </li> <li> <p><code>safeMint</code> MUST implement the same receiver restrictions as <code>safeTransferFrom</code> as defined in <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>.</p> </li> <li> <p>It's RECOMMENDED for the client to implement <a href="https://wg-eips.ritovision.com/165/">EIP-165</a> identifiers as specified above.</p> </li> </ol> <h2 id="rationale">Rationale</h2> <ol> <li> <p>It's possible that the interface be consolidated to the same as EIP-1155 which is always bearing <code>_amount</code> field, regardless of whether it's a EIP-20, EIP-721 or EIP-1155. But we choose that each ERC token should have their own standard way of representing the amount of token to follow the same way of <code>_id</code> and <code>_amount</code> in their original token standard.</p> </li> <li> <p>We have chosen to identify the interface with <a href="https://wg-eips.ritovision.com/165/">EIP-165</a> identifiers each individually, instead of having a single identifier because the signatures of interface are different.</p> </li> <li> <p>We have chosen NOT to create new events but to require the usage of existing transfer event as required by EIP-20 EIP-721 and EIP-1155 for maximum compatibility.</p> </li> <li> <p>We have chosen to add <code>safeMintBatch</code> and <code>burnBatch</code> methods for EIP-1155 but not for EIP-721 to follow the convention of EIP-721 and EIP-1155 respectively.</p> </li> <li> <p>We have not add extension for <a href="https://wg-eips.ritovision.com/777/">EIP-777</a> because it already handles Minting and Burning.</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is designed to be compatible for EIP-20, EIP-721 and EIP-1155 respectively.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP depends on the security soundness of the underlying book keeping behavior of the token implementation. In particular, a token contract should carefully design the access control for which role is granted permission to mint a new token. Failing to safe guard such behavior can cause fraudulent issuance and an elevation of total supply.</p> <p>The burning should also carefully design the access control. Typically only the following two roles are entitled to burn a token:</p> <ul> <li>Role 1. The current token holder</li> <li>Role 2. An role with special privilege.</li> </ul> <p>Either Role 1 OR Role 2 or a consensus between the two are entitled to conduct the burning action. However as author of this EIP we do recognize there are potentially other use case where a third type of role shall be entitled to burning. We keep this EIP less opinionated in such restriction but implementors should be cautious about designing the restriction.</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-11T00:00:00+00:00 2026-02-11T14:48:25+00:00 Naim Ashhabhttps://github.com/ashhanai https://wg-eips.ritovision.com/5646/

Unambiguous token state identifier

<h2 id="abstract">Abstract</h2> <p>This specification defines the minimum interface required to unambiguously identify the state of a mutable token without knowledge of implementation details.</p> <h2 id="motivation">Motivation</h2> <p>Currently, protocols need to know about tokens' state properties to create the unambiguous identifier. Unfortunately, this leads to an obvious bottleneck in which protocols need to support every new token specifically.</p> <p><img src="https://wg-eips.ritovision.com/5646/./assets/support-per-abi.png" alt="" /></p> <h2 id="specification">Specification</h2> <p>The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" 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"> ERC5646</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC165</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 to return current token state fingerprint.</span></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 a token state 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"> Current</span><span class="z-comment"> token state fingerprint.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getStateFingerprint</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>}</span></span></code></pre> <ul> <li><code>getStateFingerprint</code> MUST return a different value when the token state changes.</li> <li><code>getStateFingerprint</code> MUST NOT return a different value when the token state remains the same.</li> <li><code>getStateFingerprint</code> MUST include all state properties that might change during the token lifecycle (are not immutable).</li> <li><code>getStateFingerprint</code> MAY include computed values, such as values based on a current timestamp (e.g., expiration, maturity).</li> <li><code>getStateFingerprint</code> MAY include token metadata URI.</li> <li><code>supportsInterface(0xf5112315)</code> MUST return <code>true</code>.</li> </ul> <h2 id="rationale">Rationale</h2> <p>Protocols can use state fingerprints as a part of a token identifier and support mutable tokens without knowing any state implementation details.</p> <p><img src="https://wg-eips.ritovision.com/5646/./assets/support-per-eip.png" alt="" /></p> <p>State fingerprints don't have to factor in state properties that are immutable, because they can be safely identified by a token id.</p> <p>This standard is not for use cases where token state property knowledge is required, as these cases cannot escape the bottleneck problem described earlier.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is not introducing any backward incompatibilities.</p> <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.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"> Example of a mutable token implementing state fingerprint.</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> LPToken</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">ERC5646</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"> Stored token states (token id =&gt; state).</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> State</span><span>)</span><span class="z-storage z-type"> internal</span><span> states</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"> State</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> asset1</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> asset2</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> amount1</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> amount2</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> fee</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Immutable</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> operator</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Immutable</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> expiration</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Parameter dependent on a block.timestamp</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-storage z-type"> @dev</span><span class="z-comment"> State fingerprint getter.</span></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 a token state 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"> Current</span><span class="z-comment"> token state fingerprint.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getStateFingerprint</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</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">bytes32</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> State </span><span class="z-storage z-type">storage</span><span> state </span><span class="z-keyword">=</span><span> states</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</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> state</span><span>.</span><span>asset1</span><span>,</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>asset2</span><span>,</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>amount1</span><span>,</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>amount2</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> state.fee don&#39;t need to be part of the fingerprint computation as it is immutable</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> state.operator don&#39;t need to be part of the fingerprint computation as it is immutable</span></span> <span class="giallo-l"><span class="z-variable z-language"> block</span><span>.</span><span>timestamp </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> state</span><span>.</span><span>expiration</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 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 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 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>ERC5646</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>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Token state fingerprints from two different contracts may collide. Because of that, they should be compared only in the context of one token contract.</p> <p>If the <code>getStateFingerprint</code> implementation does not include all parameters that could change the token state, a token owner would be able to change the token state without changing the token fingerprint. It could break the trustless assumptions of several protocols, which create, e.g., buy offers for tokens. The token owner would be able to change the state of the token before accepting an offer.</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-09T00:00:00+00:00 2026-02-11T14:48:25+00:00 foobarhttps://github.com/0xfoobar Wilkins Chunghttps://github.com/wwhchungwilkins@manifold.xyz ryley-ohttps://github.com/ryley-o Jake Rocklandhttps://github.com/jakerockland andy8052https://github.com/andy8052 https://wg-eips.ritovision.com/5639/

Delegation of permissions for safer and more convenient signing operations.

<h2 id="abstract">Abstract</h2> <p>This EIP describes the details of the Delegation Registry, a proposed protocol and ABI definition that provides the ability to link one or more delegate wallets to a vault wallet in a manner which allows the linked delegate wallets to prove control and asset ownership of the vault wallet.</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 delegate 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> <h3 id="proposal-use-of-a-delegation-registry">Proposal: Use of a Delegation Registry</h3> <p>This proposal aims to provide a mechanism which allows a vault wallet to grant wallet, contract or token level permissions to a delegate wallet. This would achieve a safer and more convenient way to sign and authenticate, and provide 'read only' access to a vault wallet via one or more secondary wallets.</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>vault</code> represent the vault address we are trying to authenticate or prove asset ownership for.</li> <li><code>delegate</code> represent the address we want to use for signing in lieu of <code>vault</code>.</li> </ul> <p><strong>A Delegation Registry must implement IDelegationRegistry</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"> An immutable registry contract to be deployed as a standalone primitive</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> New project launches can read previous cold wallet -&gt; hot wallet delegations</span></span> <span class="giallo-l"><span class="z-comment"> * from here and integrate those permissions into their flow</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"> IDelegationRegistry</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"> Delegation type</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> DelegationType</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> NONE</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ALL</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> CONTRACT</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> TOKEN</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"> @notice</span><span class="z-comment"> Info about a single delegation, used for onchain enumeration</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> DelegationInfo</span><span> {</span></span> <span class="giallo-l"><span> DelegationType type_</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> vault</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> delegate</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> contract_</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"> @notice</span><span class="z-comment"> Info about a single contract-level delegation</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> ContractDelegation</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> contract_</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> delegate</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"> @notice</span><span class="z-comment"> Info about a single token-level delegation</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> TokenDelegation</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> contract_</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 class="z-support"> address</span><span> delegate</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"> @notice</span><span class="z-comment"> Emitted when a user delegates their entire wallet</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DelegateForAll</span><span>(</span><span class="z-support">address</span><span class="z-variable"> vault</span><span>, </span><span class="z-support">address</span><span class="z-variable"> delegate</span><span>, </span><span class="z-support">bool</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"> @notice</span><span class="z-comment"> Emitted when a user delegates a specific contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DelegateForContract</span><span>(</span><span class="z-support">address</span><span class="z-variable"> vault</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"> contract_</span><span>, </span><span class="z-support">bool</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"> @notice</span><span class="z-comment"> Emitted when a user delegates a specific token</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DelegateForToken</span><span>(</span><span class="z-support">address</span><span class="z-variable"> vault</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"> contract_</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>, </span><span class="z-support">bool</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"> @notice</span><span class="z-comment"> Emitted when a user revokes all delegations</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RevokeAllDelegates</span><span>(</span><span class="z-support">address</span><span class="z-variable"> vault</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"> Emitted when a user revoes all delegations for a given delegate</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RevokeDelegate</span><span>(</span><span class="z-support">address</span><span class="z-variable"> vault</span><span>, </span><span class="z-support">address</span><span class="z-variable"> delegate</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"> * ----------- WRITE -----------</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"> Allow the delegate to act on your behalf for all contracts</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> delegate</span><span class="z-comment"> The hotwallet to act on your behalf</span></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"> Whether to enable or disable delegation for this address, true for setting and false for revoking</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"> delegateForAll</span><span>(</span><span class="z-support">address</span><span class="z-variable"> delegate</span><span>,</span><span class="z-support"> bool</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 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"> Allow the delegate to act on your behalf for a specific 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"> delegate</span><span class="z-comment"> The hotwallet to act on your behalf</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> contract_</span><span class="z-comment"> The address for the contract you&#39;re delegating</span></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"> Whether to enable or disable delegation for this address, true for setting and false for revoking</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"> delegateForContract</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"> contract_</span><span>,</span><span class="z-support"> bool</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 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"> Allow the delegate to act on your behalf for 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"> delegate</span><span class="z-comment"> The hotwallet to act on your behalf</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> contract_</span><span class="z-comment"> The address for the contract you&#39;re delegating</span></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 for the token you&#39;re delegating</span></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"> Whether to enable or disable delegation for this address, true for setting and false for revoking</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"> delegateForToken</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"> contract_</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> bool</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 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"> Revoke all delegates</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"> revokeAllDelegates</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"> Revoke a specific delegate for all their permissions</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> delegate</span><span class="z-comment"> The hotwallet to revoke</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"> revokeDelegate</span><span>(</span><span class="z-support">address</span><span class="z-variable"> delegate</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 yourself as a delegate for a specific vault</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> vault</span><span class="z-comment"> The vault which delegated to the msg.sender, and should be removed</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"> revokeSelf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> vault</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"> * ----------- READ -----------</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"> Returns all active delegations a given delegate is able to claim on behalf 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"> delegate</span><span class="z-comment"> The delegate that you would like to retrieve delegations 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"> info</span><span class="z-comment"> Array of DelegationInfo structs</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"> getDelegationsByDelegate</span><span>(</span><span class="z-support">address</span><span class="z-variable"> delegate</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">DelegationInfo</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns an array of wallet-level delegates for a given vault</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> vault</span><span class="z-comment"> The cold wallet who issued the delegation</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"> Array of wallet-level delegates for a given vault</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"> getDelegatesForAll</span><span>(</span><span class="z-support">address</span><span class="z-variable"> vault</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns an array of contract-level delegates for a given vault and 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"> vault</span><span class="z-comment"> The cold wallet who issued the delegation</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> contract_</span><span class="z-comment"> The address for the contract you&#39;re delegating</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"> Array of contract-level delegates for a given vault and 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"> getDelegatesForContract</span><span>(</span><span class="z-support">address</span><span class="z-variable"> vault</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> contract_</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns an array of contract-level delegates for a given vault&#39;s 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"> vault</span><span class="z-comment"> The cold wallet who issued the delegation</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> contract_</span><span class="z-comment"> The address for the contract holding 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"> tokenId</span><span class="z-comment"> The token id for the token you&#39;re delegating</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"> Array of contract-level delegates for a given vault&#39;s 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"> getDelegatesForToken</span><span>(</span><span class="z-support">address</span><span class="z-variable"> vault</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> contract_</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 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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns all contract-level delegations for a given vault</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> vault</span><span class="z-comment"> The cold wallet who issued the delegations</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"> delegations</span><span class="z-comment"> Array of ContractDelegation structs</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"> getContractLevelDelegations</span><span>(</span><span class="z-support">address</span><span class="z-variable"> vault</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">ContractDelegation</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> delegations</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 all token-level delegations for a given vault</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> vault</span><span class="z-comment"> The cold wallet who issued the delegations</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"> delegations</span><span class="z-comment"> Array of TokenDelegation structs</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"> getTokenLevelDelegations</span><span>(</span><span class="z-support">address</span><span class="z-variable"> vault</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">TokenDelegation</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> delegations</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 true if the address is delegated to act on the entire vault</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> delegate</span><span class="z-comment"> The hotwallet to act on your behalf</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> vault</span><span class="z-comment"> The cold wallet who issued the delegation</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"> checkDelegateForAll</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"> vault</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">@notice</span><span class="z-comment"> Returns true if the address is delegated to act on your behalf for a token contract or an entire vault</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> delegate</span><span class="z-comment"> The hotwallet to act on your behalf</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> contract_</span><span class="z-comment"> The address for the contract you&#39;re delegating</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> vault</span><span class="z-comment"> The cold wallet who issued the delegation</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"> checkDelegateForContract</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"> vault</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> contract_</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns true if the address is delegated to act on your behalf for a specific token, the token&#39;s contract or an entire vault</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> delegate</span><span class="z-comment"> The hotwallet to act on your behalf</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> contract_</span><span class="z-comment"> The address for the contract you&#39;re delegating</span></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 for the token you&#39;re delegating</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> vault</span><span class="z-comment"> The cold wallet who issued the delegation</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"> checkDelegateForToken</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"> vault</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> contract_</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><h3 id="checking-delegation">Checking Delegation</h3> <p>A dApp or smart contract would check whether or not a delegate is authenticated for a vault by checking the return value of checkDelegateForAll.</p> <p>A dApp or smart contract would check whether or not a delegate can authenticated for a contract associated with a by checking the return value of checkDelegateForContract.</p> <p>A dApp or smart contract would check whether or not a delegate can authenticated for a specific token owned by a vault by checking the return value of checkDelegateForToken.</p> <p>A delegate can act on a token if they have a token level delegation, contract level delegation (for that token's contract) or vault level delegation.</p> <p>A delegate can act on a contract if they have contract level delegation or vault level delegation.</p> <p>For the purposes of saving gas, it is expected if delegation checks are performed at a smart contract level, the dApp would provide a hint to the smart contract which level of delegation the delegate has so that the smart contract can verify with the Delegation Registry using the most gas efficient check method.</p> <h2 id="rationale">Rationale</h2> <h3 id="allowing-for-vault-contract-or-token-level-delegation">Allowing for vault, contract or token level delegation</h3> <p>In order to support a wide range of delegation use cases, the proposed specification allows a vault to delegate all assets it controls, assets of a specific contract, or a specific token. This ensures that a vault has fine grained control over the security of their assets, and allows for emergent behavior around granting third party wallets limited access only to assets relevant to them.</p> <h3 id="on-chain-enumeration">On-chain enumeration</h3> <p>In order to support ease of integration and adoption, this specification has chosen to include on-chain enumeration of delegations and incur the additional gas cost associated with supporting enumeration. On-chain enumeration allows for dApp frontends to identify the delegations that any connected wallet has access to, and can provide UI selectors.</p> <p>Without on-chain enumeration, a dApp would require the user to manually input the vault, or would need a way to index all delegate events.</p> <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-09-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Gavin Fuhttps://github.com/gavfu Leo Wanghttps://github.com/wanglie1986 Bova Chenhttps://github.com/appoipp Guang Hanhttps://github.com/pangwa Brian Wuhttps://github.com/wuhaixian1984 https://wg-eips.ritovision.com/5625/

Add a dStorage property to non-fungible tokens (NFTs) metadata JSON schema to provide decentralized storage information of NFT assets

<h2 id="abstract">Abstract</h2> <p>This EIP extends the NFT metadata JSON schema defined in <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>, adding a <code>dStorage</code> key that provides information about how the NFT data is stored.</p> <h2 id="motivation">Motivation</h2> <p>As highly valuable crypto properties, NFT assets intrinsically demand guaranteed storage to assure their <strong>immutability</strong>, <strong>reliability</strong>, and <strong>durability</strong>. NFT ownership is tracked by <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> or <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> smart contracts, hence persisted in blockchain, which is not a problem. But how about the mime-type assets that NFT tokens represent? Ideally, they should also be stored in some reliable and verifiable decentralized storage system that is designed to store larger amounts of data than the blockchain itself. As an effort to promote <strong>decentralized storage</strong> adoption in NFT world, we propose to add additional <strong>dStorage</strong> information into NFT metadata JSON schema.</p> <p>As a refresher, let's review existing NFT metadata JSON schema standards. <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> defines a standard contract method <code>tokenURI</code> to return a given NFT's metadata JSON file, conforming to the <em><a href="https://wg-eips.ritovision.com/721/">EIP-721</a> Metadata JSON Schema</em>, which defines three properties: <code>name</code>, <code>description</code> and <code>image</code>.</p> <p>Similarly, <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> also defines a standard contract method <code>uri</code> to return NFT metadata JSON files conforming to the <em><a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> Metadata JSON Schema</em>, which defines properties like <code>name</code>, <code>decimals</code>, <code>description</code>, <code>image</code>, <code>properties</code>, <code>localization</code>, etc.</p> <p>Besides, as the world's largest NFT marketplace nowadays, OpenSea defines their own <em>Metadata Standards</em>, including a few more properties like <code>image_data</code>, <code>external_url</code>, <code>attributes</code>, <code>background_color</code>, <code>animation_url</code>, <code>youtube_url</code>, etc. This standard is de facto respected and followed by other NFT marketplaces like LooksRare.</p> <p>None of these standards conveys storage information about the mime-type asset that the NFT token represents. This proposal is an effort to fill the missing part.</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 addition to the existing properties, the Metadata JSON file returned by <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 (via <code>tokenURI</code> and <code>uri</code> methods, respectively), should OPTIONALLY contains one more <code>dStorage</code> property.</p> <p>For <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> smart contracts, the Metadata JSON file schema is:</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 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">dStorage</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">platform</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">description</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">persistence_mechanism</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">challenge_mechanism</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">consensus</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">dstorage_note</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">platform</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">dStorage platform name like Swarm, Arweave, Filecoin, Crust, etc</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">A brief description of the dStorage platform</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">persistence_mechanism</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">Persistence mechanism or incentive structure of the dStorage platform, like &#39;blockchain-based&#39;, &#39;contract-based&#39;, etc</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">challenge_mechanism</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">Challenge mechanism of the dStorage platform, like Arweave&#39;s proof-of-access, etc</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">consensus</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">Consensus mechanism of the dStorage platform, like PoW, PoS, etc</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">dstorage_note</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 note to prove the storage of the NFT asset on the dStorage platform, like a Filecoin deal id, a Crust place_storage_order transaction hash, etc</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> <p>For <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> smart contracts, the Metadata JSON file schema is:</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">Token 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 token 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">decimals</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">The number of decimal places that the token amount should display - e.g. 18, means to divide the token amount by 1000000000000000000 to get its user representation.</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 token 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 token 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">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">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">Arbitrary properties. Values may be strings, numbers, object or arrays.</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">dStorage</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">platform</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">description</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">persistence_mechanism</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">challenge_mechanism</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">consensus</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">dstorage_note</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">platform</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">dStorage platform name like Swarm, Arweave, Filecoin, Crust, etc</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">A brief description of the dStorage platform</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">persistence_mechanism</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">Persistence mechanism or incentive structure of the dStorage platform, like &#39;blockchain-based&#39;, &#39;contract-based&#39;, etc</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">challenge_mechanism</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">Challenge mechanism of the dStorage platform, like Arweave&#39;s proof-of-access, etc</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">consensus</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">Consensus mechanism of the dStorage platform, like PoW, PoS, etc</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">dstorage_note</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 note to prove the storage of the NFT asset on the dStorage platform, like a Filecoin deal id, a Crust place_storage_order transaction hash, etc</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><h2 id="rationale">Rationale</h2> <h3 id="choice-between-interface-and-json-schema-extension">Choice between Interface and JSON Schema Extension</h3> <p>An extension of the EIP-721 or EIP-1155 contract interfaces would unnecessarily require additional code to implement, and would not be available for use by NFT projects that already have their NFT smart contracts finalized and deployed. An optional JSON schema extension is noninvasive, and more easily adopted.</p> <h1 id="backwards-compatibility">Backwards Compatibility</h1> <p>This EIP is backward compatible with <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="security-considerations">Security Considerations</h2> <p>This EIP does not introduce any new security risks or vulnerabilities, as the <code>dStorage</code> property is only an informational field of the Metadata JSON file returned by <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. It does not affect the execution or validity of NFT 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> 2022-09-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Apeguruhttps://github.com/Apegurus Marco De Vriesmarco@paladinsec.co Mariomario@paladinsec.co DeFiFoFumhttps://github.com/DeFiFoFum Elliott Greenhttps://github.com/elliott-green https://wg-eips.ritovision.com/5725/

An interface for transferable vesting NFTs which release underlying tokens over time.

<h2 id="abstract">Abstract</h2> <p>A <strong>Non-Fungible Token</strong> (NFT) standard used to vest tokens (<a href="https://wg-eips.ritovision.com/20/">ERC-20</a> or otherwise) over a vesting release curve.</p> <p>The following standard allows for the implementation of a standard API for NFT based contracts that hold and represent the vested and locked properties of any underlying token (<a href="https://wg-eips.ritovision.com/20/">ERC-20</a> or otherwise) that is emitted to the NFT holder. This standard is an extension of the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> token that provides basic functionality for creating vesting NFTs, claiming the tokens and reading vesting curve properties.</p> <h2 id="motivation">Motivation</h2> <p>Vesting contracts, including timelock contracts, lack a standard and unified interface, which results in diverse implementations of such contracts. Standardizing such contracts into a single interface would allow for the creation of an ecosystem of on- and off-chain tooling around these contracts. In addition, liquid vesting in the form of non-fungible assets can prove to be a huge improvement over traditional <strong>Simple Agreement for Future Tokens</strong> (SAFTs) or <strong>Externally Owned Account</strong> (EOA)-based vesting as it enables transferability and the ability to attach metadata similar to the existing functionality offered by with traditional NFTs.</p> <p>Such a standard will not only provide a much-needed <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token lock standard, but will also enable the creation of secondary marketplaces tailored for semi-liquid SAFTs.</p> <p>This standard also allows for a variety of different vesting curves to be implement easily.</p> <p>These curves could represent:</p> <ul> <li>linear vesting</li> <li>cliff vesting</li> <li>exponential vesting</li> <li>custom deterministic vesting</li> </ul> <h3 id="use-cases">Use Cases</h3> <ol> <li>A framework to release tokens over a set period of time that can be used to build many kinds of NFT financial products such as bonds, treasury bills, and many others.</li> <li>Replicating SAFT contracts in a standardized form of semi-liquid vesting NFT assets. <ul> <li>SAFTs are generally off-chain, while today's on-chain versions are mainly address-based, which makes distributing vesting shares to many representatives difficult. Standardization simplifies this convoluted process.</li> </ul> </li> <li>Providing a path for the standardization of vesting and token timelock contracts. <ul> <li>There are many such contracts in the wild and most of them differ in both interface and implementation.</li> </ul> </li> <li>NFT marketplaces dedicated to vesting NFTs. <ul> <li>Whole new sets of interfaces and analytics could be created from a common standard for token vesting NFTs.</li> </ul> </li> <li>Integrating vesting NFTs into services like Safe Wallet. <ul> <li>A standard would mean services like Safe Wallet could more easily and uniformly support interactions with these types of contracts inside of a multisig contract.</li> </ul> </li> <li>Enable standardized fundraising implementations and general fundraising that sell vesting tokens (eg. SAFTs) in a more transparent manner.</li> <li>Allows tools, front-end apps, aggregators, etc. to show a more holistic view of the vesting tokens and the properties available to users. <ul> <li>Currently, every project needs to write their own visualization of the vesting schedule of their vesting assets. If this is standardized, third-party tools could be developed to aggregate all vesting NFTs from all projects for the user, display their schedules and allow the user to take aggregated vesting actions.</li> <li>Such tooling can easily discover compliance through the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> <code>supportsInterface(InterfaceID)</code> check.</li> </ul> </li> <li>Makes it easier for a single wrapping implementation to be used across all vesting standards that defines multiple recipients, periodic renting of vesting tokens etc.</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> <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 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"> Non-Fungible Vesting Token Standard.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> A non-fungible token standard used to vest ERC-20 tokens over a vesting release curve </span></span> <span class="giallo-l"><span class="z-comment"> * scheduled using timestamps.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Because this standard relies on timestamps for the vesting schedule, it&#39;s important to keep track of the </span></span> <span class="giallo-l"><span class="z-comment"> * tokens claimed per Vesting NFT so that a user cannot withdraw more tokens than allotted for a specific Vesting NFT.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@custom:interface</span><span class="z-comment">-id 0xbd3a202b</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"> IERC5725</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * This event is emitted when the payout is claimed through the claim function.</span></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 tokenId of the assets being claimed.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> recipient</span><span class="z-comment"> The address which is receiving the payout.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> claimAmount</span><span class="z-comment"> The amount of tokens being claimed.</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"> PayoutClaimed</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"> recipient</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> claimAmount</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"> * This event is emitted when an `owner` sets an address to manage token claims for all 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"> owner</span><span class="z-comment"> The address setting a manager to manage all 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"> spender</span><span class="z-comment"> The address being permitted to manage all 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"> approved</span><span class="z-comment"> A boolean indicating whether the spender is approved to claim for all 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"> ClaimApprovalForAll</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">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"> * This event is emitted when an `owner` sets an address to manage token claims for a `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"> owner</span><span class="z-comment"> The `owner` of `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"> spender</span><span class="z-comment"> The address being permitted to manage a 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"> tokenId</span><span class="z-comment"> The unique identifier of the token being managed.</span></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"> A boolean indicating whether the spender is approved to claim for `tokenId`.</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"> ClaimApproval</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"> tokenId</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">@notice</span><span class="z-comment"> Claim the pending payout for the NFT.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST grant the claimablePayout value at the time of claim being called to `msg.sender`. </span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if not called by the token owner or approved users. </span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit PayoutClaimed. </span></span> <span class="giallo-l"><span class="z-comment"> * SHOULD revert if there is nothing to claim.</span></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 token 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"> claim</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"> Number of tokens for the NFT which have been claimed at the current 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"> tokenId</span><span class="z-comment"> The NFT 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"> payout</span><span class="z-comment"> The total amount of payout tokens claimed 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"> claimedPayout</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 class="z-variable"> payout</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"> Number of tokens for the NFT which can be claimed at the current timestamp.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> It is RECOMMENDED that this is calculated as the `vestedPayout()` subtracted from `payoutClaimed()`.</span></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 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"> payout</span><span class="z-comment"> The amount of unlocked payout tokens for the NFT which have not yet been claimed.</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"> claimablePayout</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 class="z-variable"> payout</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"> Total amount of tokens which have been vested at the current timestamp. </span></span> <span class="giallo-l"><span class="z-comment"> * This number also includes vested tokens which have been claimed.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> It is RECOMMENDED that this function calls `vestedPayoutAtTime` </span></span> <span class="giallo-l"><span class="z-comment"> * with `block.timestamp` as the `timestamp` 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"> tokenId</span><span class="z-comment"> The NFT 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"> payout</span><span class="z-comment"> Total amount of tokens which have been vested at the current timestamp.</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"> vestedPayout</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 class="z-variable"> payout</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"> Total amount of vested tokens at the provided timestamp. </span></span> <span class="giallo-l"><span class="z-comment"> * This number also includes vested tokens which have been claimed.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> `timestamp` MAY be both in the future and in the past. </span></span> <span class="giallo-l"><span class="z-comment"> * Zero MUST be returned if the timestamp is before the token was minted.</span></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 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"> timestamp</span><span class="z-comment"> The timestamp to check on, can be both in the past and the future.</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"> payout</span><span class="z-comment"> Total amount of tokens which have been vested at the provided timestamp.</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"> vestedPayoutAtTime</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"> timestamp</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"> payout</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"> Number of tokens for an NFT which are currently vesting.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The sum of vestedPayout and vestingPayout SHOULD always be the total payout.</span></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 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"> payout</span><span class="z-comment"> The number of tokens for the NFT which are vesting until a future date.</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"> vestingPayout</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 class="z-variable"> payout</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"> The start and end timestamps for the vesting of the provided NFT. </span></span> <span class="giallo-l"><span class="z-comment"> * MUST return the timestamp where no further increase in vestedPayout occurs for `vestingEnd`.</span></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 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"> vestingStart</span><span class="z-comment"> The beginning of the vesting as a unix 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"> vestingEnd</span><span class="z-comment"> The ending of the vesting as a unix timestamp.</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"> vestingPeriod</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 class="z-variable"> vestingStart</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> vestingEnd</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"> Token which is used to pay out the vesting 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"> tokenId</span><span class="z-comment"> The NFT 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"> token</span><span class="z-comment"> The token which is used to pay out the vesting claims.</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"> payoutToken</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"> token</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"> Sets a global `operator` with permission to manage all tokens owned by the current `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"> operator</span><span class="z-comment"> The address to let manage all 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"> approved</span><span class="z-comment"> A boolean indicating whether the spender is approved to claim for all 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"> setClaimApprovalForAll</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">@notice</span><span class="z-comment"> Sets a tokenId `operator` with permission to manage a single `tokenId` owned by the `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"> operator</span><span class="z-comment"> The address to let manage a single `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"> tokenId</span><span class="z-comment"> the `tokenId` to be managed.</span></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"> A boolean indicating whether the spender is approved to claim for all 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"> setClaimApproval</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-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"> Returns true if `owner` has set `operator` to manage all `tokenId`s.</span></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"> The owner allowing `operator` to manage all `tokenId`s.</span></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 who is given permission to spend tokens on behalf of the `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"> isClaimApprovedForAll</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 class="z-variable"> isClaimApproved</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 the operating address for a `tokenId`. </span></span> <span class="giallo-l"><span class="z-comment"> * If `tokenId` is not managed, then returns 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"> tokenId</span><span class="z-comment"> The NFT `tokenId` to query for a `tokenId` manager.</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"> getClaimApproved</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></span> <span class="giallo-l"></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="terms">Terms</h3> <p>These are base terms used around the specification which function names and definitions are based on.</p> <ul> <li><em>vesting</em>: Tokens which a vesting NFT is vesting until a future date.</li> <li><em>vested</em>: Total amount of tokens a vesting NFT has vested.</li> <li><em>claimable</em>: Amount of vested tokens which can be unlocked.</li> <li><em>claimed</em>: Total amount of tokens unlocked from a vesting NFT.</li> <li><em>timestamp</em>: The unix <code>timestamp</code> (seconds) representation of dates used for vesting.</li> </ul> <h3 id="vesting-functions">Vesting Functions</h3> <p><strong><code>vestingPayout</code> + <code>vestedPayout</code></strong></p> <p><code>vestingPayout(uint256 tokenId)</code> and <code>vestedPayout(uint256 tokenId)</code> add up to the total number of tokens which can be claimed by the end of the vesting schedule. This is also equal to <code>vestedPayoutAtTime(uint256 tokenId, uint256 timestamp)</code> with <code>type(uint256).max</code> as the <code>timestamp</code>.</p> <p>The rationale for this is to guarantee that the tokens <code>vested</code> and tokens <code>vesting</code> are always in sync. The intent is that the vesting curves created are deterministic across the <code>vestingPeriod</code>. This creates useful opportunities for integration with these NFTs. For example: A vesting schedule can be iterated through and a vesting curve could be visualized, either on-chain or off-chain.</p> <p><strong><code>vestedPayout</code> vs <code>claimedPayout</code> &amp; <code>claimablePayout</code></strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>vestedPayout </span><span class="z-keyword">-</span><span> claimedPayout </span><span class="z-keyword">-</span><span> claimablePayout </span><span class="z-keyword">=</span><span> lockedPayout</span></span></code></pre> <ul> <li><code>vestedPayout(uint256 tokenId)</code> provides the total amount of payout tokens which have <strong>vested</strong> <em>including <code>claimedPayout(uint256 tokenId)</code></em>.</li> <li><code>claimedPayout(uint256 tokenId)</code> provides the total amount of payout tokens which have been unlocked at the current <code>timestamp</code>.</li> <li><code>claimablePayout(uint256 tokenId)</code> provides the amount of payout tokens which can be unlocked at the current <code>timestamp</code>.</li> </ul> <p>The rationale for providing three functions is to support a number of features:</p> <ol> <li>The return of <code>vestedPayout(uint256 tokenId)</code> will always match the return of <code>vestedPayoutAtTime(uint256 tokenId, uint256 timestamp)</code> with <code>block.timestamp</code> as the <code>timestamp</code>.</li> <li><code>claimablePayout(uint256 tokenId)</code> can be used to easily see the current payout unlock amount and allow for unlock cliffs by returning zero until a <code>timestamp</code> has been passed.</li> <li><code>claimedPayout(uint256 tokenId)</code> is helpful to see tokens unlocked from an NFT and it is also necessary for the calculation of vested-but-locked payout tokens: <code>vestedPayout - claimedPayout - claimablePayout = lockedPayout</code>. This would depend on how the vesting curves are configured by the an implementation of this standard.</li> </ol> <p><code>vestedPayoutAtTime(uint256 tokenId, uint256 timestamp)</code> provides functionality to iterate through the <code>vestingPeriod(uint256 tokenId)</code> and provide a visual of the release curve. The intent is that release curves are created which makes <code>vestedPayoutAtTime(uint256 tokenId, uint256 timestamp)</code> deterministic.</p> <h3 id="timestamps">Timestamps</h3> <p>Generally in Solidity development it is advised against using <code>block.timestamp</code> as a state dependent variable as the timestamp of a block can be manipulated by a miner. The choice to use a <code>timestamp</code> over a <code>block</code> is to allow the interface to work across multiple <strong>Ethereum Virtual Machine</strong> (EVM) compatible networks which generally have different block times. Block proposal with a significantly fabricated timestamp will generally be dropped by all node implementations which makes the window for abuse negligible.</p> <p>The <code>timestamp</code> makes cross chain integration easy, but internally, the reference implementation keeps track of the token payout per Vesting NFT to ensure that excess tokens allotted by the vesting terms cannot be claimed.</p> <h3 id="limitation-of-scope">Limitation of Scope</h3> <ul> <li><strong>Historical claims</strong>: While historical vesting schedules can be determined on-chain with <code>vestedPayoutAtTime(uint256 tokenId, uint256 timestamp)</code>, historical claims would need to be calculated through historical transaction data. Most likely querying for <code>PayoutClaimed</code> events to build a historical graph.</li> </ul> <h3 id="extension-possibilities">Extension Possibilities</h3> <p>These feature are not supported by the standard as is, but the standard could be extended to support these more advanced features.</p> <ul> <li><strong>Custom Vesting Curves</strong>: This standard intends on returning deterministic <code>vesting</code> values given NFT <code>tokenId</code> and a <strong>timestamp</strong> as inputs. This is intentional as it provides for flexibility in how the vesting curves work under the hood which doesn't constrain projects who intend on building a complex smart contract vesting architecture.</li> <li><strong>NFT Rentals</strong>: Further complex DeFi tools can be created if vesting NFTs could be rented.</li> </ul> <p>This is done intentionally to keep the base standard simple. These features can and likely will be added through extensions of this standard.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <ul> <li>The Vesting NFT standard is meant to be fully backwards compatible with any current <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> integrations and marketplaces.</li> <li>The Vesting NFT standard also supports <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface detection for detecting <code>EIP-721</code> compatibility, as well as Vesting NFT compatibility.</li> </ul> <h2 id="test-cases">Test Cases</h2> <p>The reference vesting NFT repository includes tests written in Hardhat.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A reference implementation of this EIP can be found in <a href="https://wg-eips.ritovision.com/5725/assets/README/">ERC-5725 assets</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p><strong>timestamps</strong></p> <ul> <li>Vesting schedules are based on timestamps. As such, it's important to keep track of the number of tokens which have been claimed and to not give out more tokens than allotted for a specific Vesting NFT. <ul> <li><code>vestedPayoutAtTime(tokenId, type(uint256).max)</code>, for example, must return the total payout for a given <code>tokenId</code></li> </ul> </li> </ul> <p><strong>approvals</strong></p> <ul> <li>When an <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> approval is made on a Vesting NFT, the operator would have the rights to transfer the Vesting NFT to themselves and then claim the vested tokens.</li> <li>When a ERC-5725 approval is made on a Vesting NFT, the operator would have the rights to claim the vested tokens, but not transfer the NFT away from the owner.</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-07T00:00:00+00:00 2026-02-11T14:48:25+00:00 Firn Protocolhttps://github.com/firnprotocol Fried L. Trout Weiji Guohttps://github.com/weijiguo https://wg-eips.ritovision.com/5630/

defines a specification for encryption and decryption using Ethereum wallets.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a new way to encrypt and decrypt using Ethereum keys. This EIP uses <em>only</em> the <code>secp256k1</code> curve, and proposes two new RPC methods: <code>eth_getEncryptionPublicKey</code> and <code>eth_performECDH</code>. These two methods, in conjunction, allow users to receive encryptions and perform decryptions (respectively). We require that the wallet <em>only</em> perform the core ECDH operation, leaving the ECIES operations up to implementers (we do suggest a standardized version of ECIES, however). In contrast, a previous EIPs used the same secret key, in both signing and encryption, on two <em>different</em> curves (namely, <code>secp256k1</code> and <code>ec25519</code>), and hardcoded a particular version of ECIES.</p> <h2 id="motivation">Motivation</h2> <p>We discuss a few motivating examples. One key motivation is direct-to-address encryption on Ethereum. Using our EIP, one can directly send encrypted messages to some desired recipient on-chain, without having a prior direct channel to that recipient. (Note that in this EIP, we standardize <em>only</em> the encryption procedure—that is, the generation of the ciphertext—and <em>not</em> how exactly the on-chain message should be sent. In practice, ideally, smart-contract infrastructure will be set up for this purpose; barring this, encryptors could make use of the raw <code>data</code> field available in each standard transfer.)</p> <p>We discuss a second sort of example. In a certain common design pattern, a dApp generates a fresh secret on behalf of a user. It is of interest if, instead of forcing this user to independently store, safeguard, and back up this latter secret, the dApp may instead encrypt this secret to a public key which the user controls—and whose secret key, crucially, resides within the user's HD wallet hierarchy—and then post the resulting ciphertext to secure storage (e.g., on-chain). This design pattern allows the dApp/user to bootstrap the security of the <em>fresh</em> secret onto the security of the user's existing HD wallet seed phrase, which the user has already gone through the trouble of safeguarding and storing. This represents a far lower UX burden than forcing the user to store and manage fresh keys directly (which can, and often does, lead to loss of funds). We note that this design pattern described above is used today by, various dApps (e.g., Tornado Cash).</p> <h2 id="specification">Specification</h2> <p>We describe our approach here; we compare our approach to prior EIPs in the <strong>Rationale</strong> section below. Throughout, we make reference to SEC 1: Elliptic Curve Cryptography, by Daniel R. L. Brown.</p> <p>We use the <code>secp256k1</code> curve for both signing and encryption. For encryption, we use ECIES. We specify that the wallet <em>only</em> perform the sensitive ECDH operation. This lets implementers select their own ECIES variants at will.</p> <p>We propose that all binary data be serialized to and from <code>0x</code>-prefixed hex strings. We moreover use <code>0x</code>-prefixed hex strings to specify private keys and public keys, and represent public keys in compressed form. We represent Ethereum accounts in the usual way (<code>0x</code>-prefixed, 20-byte hex strings). Specifically, to serialize and deserialize elliptic curve points, implementers MUST use the following standard:</p> <ul> <li> <p>to serialize a point: use [SEC 1, §2.3.3], with point compression.</p> </li> <li> <p>to deserialize a point: use [SEC 1, §2.3.3], while <em>requiring</em> point compression; that is:</p> <ul> <li>the input byte string MUST have length ⌈log₂q / 8⌉ + 1 = <code>33</code>.</li> <li>the first byte MUST be <code>0x02</code> or <code>0x03</code>.</li> <li>the integer represented by the remaining 32 bytes (as in [SEC 1, §2.3.8]) MUST reside in {0, ..., <em>p</em> - 1}, and moreover MUST yield a quadratic residue modulo <em>p</em> under the Weierstrass expression X^3 + 7 (modulo <em>p</em>).</li> </ul> </li> </ul> <p>For application-level implementers actually implementing ECIES, we propose the following variant. Unless they have a reason to do otherwise, implementers SHOULD use the following standardized choices:</p> <ul> <li>the KDF <code>ANSI-X9.63-KDF</code>, where the hash function <code>SHA-512</code> is used,</li> <li>the HMAC <code>HMAC–SHA-256–256 with 32 octet or 256 bit keys</code>,</li> <li>the symmetric encryption scheme <code>AES–256 in CBC mode</code>.</li> </ul> <p>We propose that the binary, <em>concatenated</em> serialization mode for ECIES ciphertexts be used, both for encryption and decryption, where moreover elliptic curve points are <em>compressed</em>.</p> <p>Thus, on the request:</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_getEncryptionPublicKey</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">account</span><span>]</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre> <p>where <code>account</code> is a standard 20-byte, <code>0x</code>-prefixed, hex-encoded Ethereum account, the client should operate as follows:</p> <ul> <li>find the secret signing key <code>sk</code> corresponding to the Ethereum account <code>account</code>, or else return an error if none exists.</li> <li>compute the <code>secp256k1</code> public key corresponding to <code>sk</code>.</li> <li>return this public key in compressed, <code>0x</code>-prefixed, hex-encoded form, following [SEC 1, §2.3.3].</li> </ul> <p>On the request</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_performECDH</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">account</span><span>,</span><span class="z-variable z-other"> ephemeralKey</span><span>]</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre> <p>where <code>account</code> is as above, and <code>ephemeralKey</code> is an elliptic curve point encoded as above:</p> <ul> <li>find the secret key <code>sk</code> corresponding to the Ethereum account <code>account</code>, or else return an error if none exists.</li> <li>deserialize <code>ephemeralKey</code> to an elliptic curve point using [SEC 1, §2.3.3] (where compression is required), throwing an error if deserialization fails.</li> <li>compute the elliptic curve Diffie–Hellman secret, following [SEC 1, §3.3.1].</li> <li>return the resulting field element as an 0x-prefixed, hex-encoded, 32-byte string, using [SEC 1, §2.3.5].</li> </ul> <p>Test vectors are given below.</p> <h3 id="encrypting-to-a-smart-contract">Encrypting to a smart contract</h3> <p>In light of account abstraction, <a href="https://wg-eips.ritovision.com/4337/">EIP-4337</a>, and the advent of smart-contract wallets, we moreover specify a way to encrypt to a contract. More precisely, we specify a way for a contract to <em>advertise</em> how it would like encryptions to it to be constructed. This should be viewed as an analogue of <a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a>, but for encryption, as opposed to signing.</p> <p>Our specification is as follows.</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">contract</span><span class="z-entity z-name"> ERC5630</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"> Should return an encryption of the provided plaintext, using the provided randomness.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> plaintext</span><span class="z-comment"> Plaintext to be encrypted</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> randomness</span><span class="z-comment"> Entropy to be used during encryption</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"> encryptTo</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> plaintext</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> randomness</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">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> ciphertext</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Each contract MAY implement <code>encryptTo</code> as it desires. Unless it has a good reason to do otherwise, it SHOULD use the ECIES variant we propose above.</p> <h2 id="rationale">Rationale</h2> <p>There is <em>no security proof</em> for a scheme which simultaneously invokes signing on the <code>secp256k1</code> curve and encryption on the <code>ec25519</code> curve, and where <em>the same secret key is moreover used in both cases</em>. Though no attacks are known, it is not desirable to use a scheme which lacks a proof in this way. We, instead, propose the reuse of the same key in signing and encryption, but where <em>the same curve is used in both</em>. This very setting has been studied in prior work; see, e.g., Degabriele, Lehmann, Paterson, Smart and Strefler, <em>On the Joint Security of Encryption and Signature in EMV</em>, 2011. That work found this joint scheme to be secure in the generic group model. We note that this very joint scheme (i.e., using ECDSA and ECIES on the same curve) is used live in production in EMV payments.</p> <p>We now discuss a few further aspects of our approach.</p> <p><strong>On-chain public key discovery.</strong> Our proposal has an important feature whereby an encryption <em>to</em> some account can be constructed whenever that account has signed at least one transaction. Indeed, it is possible to recover an account's <code>secp256k1</code> public key directly from any signature on behalf of that account.</p> <p><strong>ECDH vs. ECIES.</strong> We specify that the wallet <em>only</em> perform the sensitive ECDH operation, and let application-level implementers perform the remaining steps of ECIES. This has two distinct advantages:</p> <ul> <li><strong>Flexibility.</strong> It allows implementers to select arbitrary variants of ECIES, without having to update what the wallet does.</li> <li><strong>Bandwidth.</strong> Our approach requires that only small messages (on the order of 32 bytes) be exchanged between the client and the wallet. This could be material in settings in which the plaintexts and ciphertexts at play are large, and when the client and the wallet are separated by an internet connection.</li> </ul> <p><strong>Twist attacks.</strong> A certain GitHub post by Christian Lundkvist warns against "twist attacks" on the <code>secp256k1</code> curve. These attacks are not applicable to this EIP, for multiple <em>distinct</em> reasons, which we itemize:</p> <ul> <li><strong>Only applies to classical ECDH, not ECIES.</strong> This attack only applies to classical ECDH (i.e., in which both parties use persistent, authenticated public keys), and not to ECIES (in which one party, the encryptor, uses an ephemeral key). Indeed, it only applies to a scenario in which an attacker can induce a victim to exponentiate an attacker-supplied point by a sensitive scalar, and then moreover send the result back to the attacker. But this pattern only happens in classical Diffie–Hellman, and never in ECIES. Indeed, in ECIES, we recall that the only sensitive Diffie–Hellman operation happens during decryption, but in this case, the victim (who would be the decryptor) never sends the resulting DH point back to the attacker (rather, the victim merely uses it locally to attempt an AES decryption). During <em>encryption</em>, the exponentiation is done by the encryptor, who has no secret at all (sure enough, the exponentiation is by an ephemeral scalar), so here there would be nothing for the attacker to learn.</li> <li><strong>Only applies to uncompressed points.</strong> Indeed, we use compressed points in this EIP. When compressed points are used, each 33-byte string <em>necessarily</em> either resolves to a point on the correct curve, or else has no reasonable interpretation. There is no such thing as "a point not on the curve" (which, in particular, can pass undetectedly as such).</li> <li><strong>Only applies when you fail to check a point is on the curve.</strong> But this is inapplicable for us anyway, since we use compressed points (see above). We also require that all validations be performed.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Our <code>eth_performECDH</code> method is new, and so doesn't raise any backwards compatibility issues.</p> <p>A previous proposal proposed an <code>eth_getEncryptionPublicKey</code> method (together with an <code>eth_decrypt</code> method unrelated to this EIP). Our proposal overwrites the previous behavior of <code>eth_getEncryptionPublicKey</code>. It is unlikely that this will be an issue, since encryption keys need be newly retrieved <em>only</em> upon the time of encryption; on the other hand, <em>new</em> ciphertexts will be generated using our new approach. (In particular, our modification will not affect the ability of ciphertexts generated using the old EIP to be <code>eth_decrypt</code>ed.)</p> <p>In any case, the previous EIP was never standardized, and is <em>not</em> (to our knowledge) implemented in a non-deprecated manner in <em>any</em> production code today.</p> <h3 id="test-cases">Test Cases</h3> <p>The secret <em>signing key</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> 0x439047a312c8502d7dd276540e89fe6639d39da1d8466f79be390579d7eaa3b2</span></span></code></pre> <p>with Ethereum address <code>0x72682F2A3c160947696ac3c9CC48d290aa89549c</code>, has <code>secp256k1</code> public key</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> 0x03ff5763a2d3113229f2eda8305fae5cc1729e89037532a42df357437532770010</span></span></code></pre> <p>Thus, the request:</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_getEncryptionPublicKey</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-punctuation z-definition z-string">&quot;</span><span class="z-string">0x72682F2A3c160947696ac3c9CC48d290aa89549c</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre> <p>should return:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x03ff5763a2d3113229f2eda8305fae5cc1729e89037532a42df357437532770010</span><span class="z-punctuation z-definition z-string">&quot;</span></span></code></pre> <p>If an encryptor were to encrypt a message—say, <code>I use Firn Protocol to gain privacy on Ethereum.</code>—under the above public key, using the above ECIES variant, he could obtain, for example:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x036f06f9355b0e3f7d2971da61834513d5870413d28a16d7d68ce05dc78744daf850e6c2af8fb38e3e31d679deac82bd12148332fa0e34aecb31981bd4fe8f7ac1b74866ce65cbe848ee7a9d39093e0de0bd8523a615af8d6a83bbd8541bf174f47b1ea2bd57396b4a950a0a2eb77af09e36bd5832b8841848a8b302bd816c41ce</span><span class="z-punctuation z-definition z-string">&quot;</span></span></code></pre> <p>Upon obtaining this ciphertext, the decryptor would extract the relevant ephemeral public key, namely:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x036f06f9355b0e3f7d2971da61834513d5870413d28a16d7d68ce05dc78744daf8</span><span class="z-punctuation z-definition z-string">&quot;</span></span></code></pre> <p>And submit the request:</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_performECDH</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x72682F2A3c160947696ac3c9CC48d290aa89549c</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">0x036f06f9355b0e3f7d2971da61834513d5870413d28a16d7d68ce05dc78744daf8</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></code></pre> <p>which in turn would return the Diffie–Hellman secret:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x4ad782e7409702101abe6d0279f242a2c545c46dd50a6704a4b9e3ae2730522e</span><span class="z-punctuation z-definition z-string">&quot;</span></span></code></pre> <p>Upon proceeding with the above ECIES variant, the decryptor would then obtain the string <code>I use Firn Protocol to gain privacy on Ethereum.</code>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Our proposal uses heavily standardized algorithms and follows all best practices.</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-06T00:00:00+00:00 2026-02-11T14:48:25+00:00 Gaurang Torvekarhttps://github.com/gaurangtorvekar Khemraj Adhawadehttps://github.com/akhemraj Nikhil Asranihttps://github.com/nikhilasrani https://wg-eips.ritovision.com/5606/

A universal representation of multiple related NFTs as a single digital asset across various platforms

<h2 id="abstract">Abstract</h2> <p>This specification defines a minimal interface to create a multiverse NFT standard for digital assets such as wearables and in-game items that, in turn, index the delegate NFTs on each platform where this asset exists. These platforms could be metaverses, play-to-earn games or NFT marketplaces. This proposal depends on and extends <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>. The standard also allows for the ‘bundling’ and ‘unbundling’ of these delegate NFTs within the multiverse NFT so holders can trade them individually or as a bundle.</p> <h2 id="motivation">Motivation</h2> <p>Several metaverses and blockchain games ("platforms") exist that use NFT standards such as ERC-721 and ERC-1155 for creating in-universe assets like avatar wearables, in-game items including weapons, shields, potions and much more. The biggest shortcoming while using these standards is that there is no interoperability between these platforms. As a publisher, you must publish the same digital asset (for example, a shirt) on various platforms as separate ERC-721 or ERC-1155 tokens. Moreover, there is no relationship between these, although they represent the same digital asset in reality. Hence, it is very difficult to prove the scarcity of these items on-chain.</p> <p>Since their inception, NFTs were meant to be interoperable and prove the scarcity of digital assets. Although NFTs can arguably prove the scarcity of items, the interoperability aspect hasn’t been addressed yet. Creating a multiverse NFT standard that allows for indexing and ownership of a digital asset across various platforms would be the first step towards interoperability and true ownership across platforms.</p> <p>In the web3 ecosystem, NFTs have evolved to represent multiple types of unique and non-fungible assets. One type of asset includes a set of NFTs related to one another. For instance, if a brand releases a new sneaker across various metaverses, it would be minted as a separate NFT on each platform. However, it is, in reality, the same sneaker. There is a need to represent the relationship and transferability of these types of NFTs as metaverses and blockchain games gain more mainstream adoption. The ecosystem needs a better framework to address this issue rather than relying on the application level. This framework should define the relationship between these assets and the nature of their association. There is more value in the combined recognition, use and transferability of these individual NFTs as a bundle rather than their selves.</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 multiverse NFT contract represents a digital asset across multiple platforms. This contract can own one or more delegate NFT tokens of the digital asset on the various platforms through bundling or unbundling.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span>* @dev Interface of the Multiverse NFT standard as defined in the EIP.</span></span> <span class="giallo-l"><span>*/</span></span> <span class="giallo-l"><span>interface IMultiverseNFT {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev struct to store delegate token details</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> struct DelegateData {</span></span> <span class="giallo-l"><span> address contractAddress;</span></span> <span class="giallo-l"><span> uint256 tokenId;</span></span> <span class="giallo-l"><span> uint256 quantity;</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> * @dev Emitted when one or more new delegate NFTs are added to a Multiverse NFT</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event Bundled(uint256 multiverseTokenID, DelegateData[] delegateData, address ownerAddress);</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Emitted when one or more delegate NFTs are removed from a Multiverse NFT</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event Unbundled(uint256 multiverseTokenID, DelegateData[] delegateData);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Accepts the tokenId of the Multiverse NFT and returns an array of delegate token data</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function delegateTokens(uint256 multiverseTokenID) external view returns (DelegateData[] memory);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Removes one or more delegate NFTs from a Multiverse NFT</span></span> <span class="giallo-l"><span> * This function accepts the delegate NFT details and transfers those NFTs out of the Multiverse NFT contract to the owner&#39;s wallet</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function unbundle(DelegateData[] memory delegateData, uint256 multiverseTokenID) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Adds one or more delegate NFTs to a Multiverse NFT</span></span> <span class="giallo-l"><span> * This function accepts the delegate NFT details and transfers those NFTs to the Multiverse NFT contract</span></span> <span class="giallo-l"><span> * Need to ensure that approval is given to this Multiverse NFT contract for the delegate NFTs so that they can be transferred programmatically</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function bundle(DelegateData[] memory delegateData, uint256 multiverseTokenID) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Initialises a new bundle, mints a Multiverse NFT and assigns it to msg.sender</span></span> <span class="giallo-l"><span> * Returns the token ID of a new Multiverse NFT</span></span> <span class="giallo-l"><span> * Note - When a new Multiverse NFT is initialised, it is empty; it does not contain any delegate NFTs</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function initBundle(DelegateData[] memory delegateData) external;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Any dapp implementing this standard would initialise a bundle by calling the function <code>initBundle</code>. This mints a new multiverse NFT and assigns it to msg.sender. While creating a bundle, the delegate token contract addresses and the token IDs are set during the initialisation and cannot be changed after that. This avoids unintended edge cases where non-related NFTs could be bundled together by mistake.</p> <p>Once a bundle is initialised, the delegate NFT tokens can then be transferred to this Multiverse NFT contract by calling the function <code>bundle</code> and passing the token ID of the multiverse NFT. It is essential for a dapp to get the delegate NFTs ‘approved’ from the owner to this Multiverse NFT contract before calling the bundle function. After that, the Multiverse NFT owns one or more versions of this digital asset across the various platforms.</p> <p>If the owner of the multiverse NFT wants to sell or use the individual delegate NFTs across any of the platforms, they can do so by calling the function <code>unbundle</code>. This function transfers the particular delegate NFT token(s) to msg.sender (only if <code>msg.sender</code> is the owner of the multiverse NFT).</p> <h2 id="rationale">Rationale</h2> <p>The <code>delegateData</code> struct contains information about the delegate NFT tokens on each platform. It contains variables such as <code>contractAddress</code>, <code>tokenId</code>, <code>quantity</code> to differentiate the NFTs. These NFTs could be following either the ERC-721 standard or the ERC-1155 standard.</p> <p>The <code>bundle</code> and <code>unbundle</code> functions accept an array of DelegateData struct because of the need to cater to partial bundling and unbundling. For instance, a user could initialise a bundle with three delegate NFTs, but they should be able to bundle and unbundle less than three at any time. They can never bundle or unbundle more than three. They also need the individual token IDs of the delegate NFTs to bundle and unbundle selectively.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is fully compatible with ERC-721 and ERC-1155. Third-party applications that don’t support this EIP will still be able to use the original NFT standards without any problems.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p><a href="https://wg-eips.ritovision.com/5606/./assets/contracts/MultiverseNFT.sol">MultiverseNFT.sol</a></p> <h2 id="security-considerations">Security Considerations</h2> <p>The bundle function involves calling an external contract(s). So reentrancy prevention measures should be applied while implementing this function.</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-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv Allen Zhouallen@ubiloan.io Alex Qinalex@ubiloan.io https://wg-eips.ritovision.com/5604/

Extend ERC-721 to support putting liens on NFT

<h2 id="abstract">Abstract</h2> <p>This ERC introduces NFT liens, a form of security interest over an item of property to secure the recovery of liability or performance of some other obligation. It introduces an interface to place and removes a lien, plus an event.</p> <h2 id="motivation">Motivation</h2> <p>Liens are widely used for finance use cases, such as car and property liens. An example use case for an NFT lien is for a deed. This ERC provides an interface to implement an interface that performs the lien holding relationships.</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> <ol> <li> <p>Any compliant contract MUST implement <code>ERC-721</code>, and <code>ERC-165</code>.</p> </li> <li> <p>Any compliant contract MUST implement the following interface:</p> </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_LIEN</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">ERC165</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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> MUST be emitted when new lien is successfully placed.</span></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 a lien is placed 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"> holder</span><span class="z-comment"> the holder of the lien.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> extraParams</span><span class="z-comment"> of the original request to add the lien.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> OnLienPlaced</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"> holder</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> extraParams</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"> MUST be emitted when an existing lien is successfully 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"> tokenId</span><span class="z-comment"> the token a lien was removed from.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> holder</span><span class="z-comment"> the holder of the lien.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> extraParams</span><span class="z-comment"> of the original request to remove the lien.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> OnLienRemoved</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"> holder</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> extraParams</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> === CRUD ===</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 method to place a lien on a token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> it MUST throw an error if the same holder already has a lien on the same 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"> the token a lien is placed 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"> holder</span><span class="z-comment"> the holder of the lien</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> extraParams</span><span class="z-comment"> extra data for future extension.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addLienHolder</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"> holder</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> extraParams</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-storage z-type"> @notice</span><span class="z-comment"> The method to remove a lien on a token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> it MUST throw an error if the holder already has a lien.</span></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 a lien is being removed from.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> holder</span><span class="z-comment"> the holder of the lien</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> extraParams</span><span class="z-comment"> extra data for future extension.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeLienHolder</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"> holder</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> extraParams</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-storage z-type"> @notice</span><span class="z-comment"> The method to query if an active lien exists on a token.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> it MUST throw an error if the tokenId doesn&#39;t exist or is not owned.</span></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 a lien is being queried 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"> holder</span><span class="z-comment"> the holder about whom the method is querying about lien holding.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> extraParams</span><span class="z-comment"> extra data for future extension.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hasLien</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"> holder</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> extraParams</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="rationale">Rationale</h2> <ol> <li> <p>We only support <code>ERC-721</code> NFTs for simplicity and gas efficiency. We have not considered other ERCs, which can be left for future extensions. For example, <code>ERC-20</code> and <code>ERC-1155</code> were not considered.</p> </li> <li> <p>We choose separate "addLienHolder" and "removeLienHolder" instead of use a single <code>changeLienholder</code> with amount because we believe the add or remove action are significantly different and usually require different Access Control, for example, the token holder shall be able to add someone else as a lien holder but the lien holder of that token.</p> </li> <li> <p>We have not specified the "amount of debt" in this interface. We believe this is complex enough and worthy of an individual ERC by itself.</p> </li> <li> <p>We have not specified how endorsement can be applied to allow holder to signal their approval for transfer or swapping. We believe this is complex enough and worthy of an individual ERC by itself.</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The ERC is designed as an extension of <code>ERC-721</code> and therefore compliant contracts need to fully comply with <code>ERC-721</code>.</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-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-09-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ewan Humberthttps://github.com/Xewayxeway@protonmail.com Lassi Maksimainenhttps://github.com/mlalmalassi.maksimainen@gmail.com https://wg-eips.ritovision.com/7390/

An interface for creating, managing, and executing simple time-limited call/put (vanilla) options.

<h2 id="abstract">Abstract</h2> <p>This standard defines a comprehensive set of functions and events facilitating seamless interactions (creation, management, exercising, etc.) for vanilla options.</p> <p>Vanilla options grant the right, without obligation, to buy or sell an asset at a set price within a specified timeframe.</p> <p>This standard doesn't represent a simple option that would be useless after the expiration date. Instead, it can store as many issuance as needed. Each issuance is identified by an id, and can be bought, exercised, cancelled, etc., independently of the other issuances.<br /> Every issuance is collateralized, meaning that the writer has to provide the collateral to the contract before the buyer can buy the option. The writer can retrieve the collateral if the buyer hasn't exercised in the exercise window.<br /> A buyer can decide to buy only a fraction of the issuance (meaning multiple buyers is possible), and will receive accordingly tokens (<a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>) that represent the fraction of the issuance. From now, we will call these tokens <em>redeem tokens</em>. These tokens can be exchanged between users, and are used for exercising the option. With this mechanism, a buyer can decide to exercise only a fraction of what he bought.<br /> Also, the writer can decide to cancel the issuance if no option has been bought yet. He also has the right to update the premium price at any time. This doesn't affect the already bought options.<br /> The underlying token, strike token and premium token are <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens.</p> <p>In the following, the plural term option<strong>s</strong> will sometimes be used. This can refer to the amount of redeem tokens a buyer purchased and can exercise.</p> <h2 id="motivation">Motivation</h2> <p>Options are widely used financial instruments, and have a true usefulness for investors and traders. It offers versatile risk management tools and speculative opportunities.<br /> In the decentralized finance, many options-selling platform emerged, but each of these protocols implements their own definition of an option. This leads to incompatibilities, which is a pity because options should be interoperable like fungible/non-fungible tokens are.<br /> By introducing a standard interface for vanilla options contracts, we aim to foster a more inclusive and interoperable derivatives ecosystem. This standard will enhance the user experience and facilitate the development of decentralized options platforms, enabling users to seamlessly trade options across different applications. Moreover, this standard is designed to represent vanilla options, which are the most common type of options. This standard can be used as a base for more complex options, such as exotic options.</p> <h2 id="specification">Specification</h2> <p>Implementations of this proposal MUST also implement ERC-1155 to give the possibility to buy only a fraction of the issuance.</p> <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"> IERC7390</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> Side</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"> Put</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"> VanillaOptionData</span><span> {</span></span> <span class="giallo-l"><span> Side side</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> underlyingToken</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 class="z-support"> address</span><span> strikeToken</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> strike</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> premiumToken</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> premium</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> exerciseWindowStart</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> exerciseWindowEnd</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span> allowed</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"> OptionIssuance</span><span> {</span></span> <span class="giallo-l"><span> VanillaOptionData data</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> writer</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> exercisedAmount</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> soldAmount</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"> error</span><span class="z-entity z-name"> Forbidden</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> TransferFailed</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> TimeForbidden</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> AmountForbidden</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> InsufficientBalance</span><span>(</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"> Created</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 class="z-storage z-type"> event</span><span class="z-entity z-name"> Bought</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"> amount</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> buyer</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Exercised</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"> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Expired</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 class="z-storage z-type"> event</span><span class="z-entity z-name"> Canceled</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 class="z-storage z-type"> event</span><span class="z-entity z-name"> PremiumUpdated</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"> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AllowedUpdated</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>[</span><span>]</span><span class="z-variable"> allowed</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"> create</span><span>(</span><span class="z-storage z-type">VanillaOptionData</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> optionData</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-storage z-type"> function</span><span class="z-entity z-name"> buy</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-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"> exercise</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-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"> retrieveExpiredTokens</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"> receiver</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"> cancel</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"> receiver</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"> updatePremium</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-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"> updateAllowed</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</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"> allowed</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"> issuance</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">OptionIssuance</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="state-variable-descriptions">State Variable Descriptions</h3> <p>At creation time, user must provide filled instance of <code>VanillaOptionData</code> structure that contains all the key information for initializing the option issuance.</p> <h4 id="side"><code>side</code></h4> <p><strong>Type: <code>enum</code></strong></p> <p>Side of the option. Can take the value <code>Call</code> or <code>Put</code>. <code>Call</code> option gives the option buyer right to exercise any acquired option tokens to buy the <code>underlying</code> token at given <code>strike</code> price using <code>strikeToken</code> from option writer. Similarly, <code>Put</code> option gives the option buyer right to sell the <code>underlying</code> token to the option writer at <code>strike</code> price.</p> <h4 id="underlyingtoken"><code>underlyingToken</code></h4> <p><strong>Type: <code>address</code> (<a href="https://wg-eips.ritovision.com/20/">ERC-20</a> contract)</strong></p> <p>Underlying token.</p> <h4 id="amount"><code>amount</code></h4> <p><strong>Type: <code>uint256</code></strong></p> <p>Maximum amount of the underlying tokens that can be exercised.</p> <blockquote> <p>Be aware of token decimals!</p> </blockquote> <h4 id="striketoken"><code>strikeToken</code></h4> <p><strong>Type: <code>address</code> (ERC-20 contract)</strong></p> <p>Token used as a reference to determine the strike price.</p> <h4 id="strike"><code>strike</code></h4> <p><strong>Type: <code>uint256</code></strong></p> <p>Strike price. The option buyer MAY be able to exercise only fraction of the issuance and the paid strike price must be adjusted by the contract to reflect it.</p> <p>Note that <code>strike</code> is meant to represent the price in <code>strikeToken</code> for a single <code>underlyingToken</code>.</p> <blockquote> <p>Be aware of token decimals!</p> </blockquote> <h4 id="premiumtoken"><code>premiumToken</code></h4> <p><strong>Type: <code>address</code> (ERC-20 contract)</strong></p> <p>Premium token.</p> <h4 id="premium"><code>premium</code></h4> <p><strong>Type: <code>uint256</code></strong></p> <p>Premium price is the price that option buyer has to pay to option writer to compensate for the risk that the writer takes for issuing the option. Option premium changes depending on various factors, most important ones being the volatility of the underlying token, strike price and the time left for exercising the option.</p> <p><strong>Note that the premium price is set for exercising the total <code>amount</code> of the issuance. The buyer MAY be able to buy only fraction of the option tokens and the paid premium price must be adjusted by the contract to reflect it.</strong></p> <blockquote> <p>Be aware of token decimals!</p> </blockquote> <h4 id="exercisewindowstart"><code>exerciseWindowStart</code></h4> <p><strong>Type: <code>uint256</code></strong><br /> <strong>Format: <em>timestamp as seconds since unix epoch</em></strong></p> <p>Option exercising window start time. When current time is greater or equal to <code>exerciseWindowStart</code> and below or equal to <code>exerciseWindowEnd</code>, owner of option(s) can exercise them.</p> <h4 id="exercisewindowend"><code>exerciseWindowEnd</code></h4> <p><strong>Type: <code>uint256</code></strong><br /> <strong>Format: <em>timestamp as seconds since unix epoch</em></strong></p> <p>Option exercising window end time. When current time is greater or equal to <code>exerciseWindowStart</code> and below or equal to <code>exerciseWindowEnd</code>, owner of option(s) can exercise them. When current time is greater than <code>exerciseWindowEnd</code>, buyers can't exercise and writer can retrieve remaining underlying (call) or strike (put) tokens.</p> <h4 id="allowed"><code>allowed</code></h4> <p><strong>Type: <code>address[]</code></strong></p> <p>Addresses that are allowed to buy the issuance. If the array is empty, all addresses are allowed to buy the issuance.</p> <p><code>VanillaOptionData</code> is stored in the <code>OptionIssuance</code> struct, which is used to store the option issuance data. It contains other information.</p> <h4 id="writer"><code>writer</code></h4> <p><strong>Type: <code>address</code></strong></p> <p>Address of the writer meaning the address that created the option.</p> <h4 id="exercisedamount"><code>exercisedAmount</code></h4> <p><strong>Type: <code>uint256</code></strong></p> <p>Amount of underlying tokens that have been exercised.</p> <h4 id="soldamount"><code>soldAmount</code></h4> <p><strong>Type: <code>uint256</code></strong></p> <p>Amount of underlying tokens that have been bought for this issuance.</p> <h4 id="transferredexercisecost"><code>transferredExerciseCost</code></h4> <p><strong>Type: <code>uint256</code></strong></p> <p>Amount of <code>strikeToken</code> tokens that have been transferred to the writer (call) or buyers (put) of the option issuance.<br /> This is an utility variable used to not always have to calculate the total exercise cost transferred. It's updated at the same time <code>exercisedAmount</code> is updated. The calculation is <code>(amount * selectedIssuance.data.strike) / (10**underlyingToken.decimals())</code>.</p> <h4 id="exercisecost"><code>exerciseCost</code></h4> <p><strong>Type: <code>uint256</code></strong></p> <p>Exercise cost. It represents the collateral the writer has to deposit to the contract (put), or the amount of <code>strikeToken</code> tokens a writer can receive if all buyers decide to exercise (call).<br /> This is an utility variable used to not always have to calculate the exercise cost. We compute it at the creation of the option. The calculation is <code>(strike * amount) / (10 ** underlyingToken.decimals())</code>.</p> <h3 id="function-descriptions">Function Descriptions</h3> <h4 id="constructor"><code>constructor</code></h4> <p>No constructor is needed for this standard, but the contract MUST implement the ERC-1155 interface. So, the contract MUST call the ERC-1155 constructor.</p> <h4 id="create"><code>create</code></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"> create</span><span>(</span><span class="z-storage z-type">VanillaOptionData</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> optionData</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></code></pre> <p>Option writer creates new option tokens and defines the option parameters using <code>create()</code>. As an argument, option writer needs to fill <code>VanillaOptionData</code> data structure instance and pass it to the method. As a part of creating the option tokens, the function transfers the collateral from option writer to the contract.</p> <p>It is highly preferred that as a part of calling <code>create()</code> the option issuance becomes fully collateralized to prevent increased counterparty risk. For creating a call (put) option issuance, writer needs to allow the amount of <code>amount</code> (<code>strike</code>) tokens of <code>underlyingToken</code> (<code>strikeToken</code>) to be transferred to the option contract before calling <code>create()</code>.</p> <p>Note that this standard does not define functionality for option writer to "re-up" the collateral in case the option contract allows under-collateralization. The contract needs to then adjust its API and implementation accordingly.</p> <p>MUST revert if <code>underlyingToken</code> or <code>strikeToken</code> is the zero address.<br /> MUST revert if <code>premium</code> is not 0 and <code>premiumToken</code> is the zero address.<br /> MUST revert if <code>amount</code> or <code>strike</code> is 0.<br /> MUST revert if <code>exerciseWindowStart</code> is less than the current time or if <code>exerciseWindowEnd</code> is less than <code>exerciseWindowStart</code>.</p> <p><em>Returns an id value that refers to the created option issuance in option contract if option issuance was successful.</em> <em>Emits <code>Created</code> event if option issuance was successful.</em></p> <h4 id="buy"><code>buy</code></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"> buy</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-storage z-type"> external</span><span>;</span></span></code></pre> <p>Allows the buyer to buy <code>amount</code> of option tokens from option issuance with the defined <code>id</code>.</p> <p>The buyer has to allow the token contract to transfer the (fraction of total) <code>premium</code> in the specified <code>premiumToken</code> to option writer. During the call of the function, the premium is be directly transferred to the writer.</p> <p>If <code>allowed</code> array is not empty, the buyer's address MUST be included in this list.<br /> MUST revert if <code>amount</code> is 0 or greater than the remaining options available for purchase.<br /> MUST revert if the current time is greater than <code>exerciseWindowEnd</code>.</p> <p><em>Mints <code>amount</code> redeem tokens to the buyer's address if buying was successful.</em> <em>Emits <code>Bought</code> event if buying was successful.</em></p> <h4 id="exercise"><code>exercise</code></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"> exercise</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-storage z-type"> external</span><span>;</span></span></code></pre> <p>Allows the buyer to exercise <code>amount</code> of option tokens from option issuance with the defined <code>id</code>.</p> <ul> <li>If the option is a call, buyer pays writer at the specified strike price and gets the specified underlying tokens.</li> <li>If the option is a put, buyer transfers to writer the underlying tokens and gets paid at the specified strike price.</li> </ul> <p>The buyer has to allow the spend of either <code>strikeToken</code> or <code>underlyingToken</code> before calling <code>exercise()</code>.</p> <p>Exercise MUST only take place when <code>exerciseWindowStart</code> &lt;= current time &lt;= <code>exerciseWindowEnd</code>.<br /> MUST revert if <code>amount</code> is 0 or buyer hasn't the necessary redeem tokens to exercise the option.</p> <p><em>Burns <code>amount</code> redeem tokens from the buyer's address if the exercising was successful.</em> <em>Emits <code>Exercised</code> event if the option exercising was successful.</em></p> <h4 id="retrieveexpiredtokens"><code>retrieveExpiredTokens</code></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"> retrieveExpiredTokens</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"> receiver</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Allows writer to retrieve the collateral tokens that were not exercised. These tokens are transferred to <code>receiver</code>.<br /> If the option is a call, <code>receiver</code> retrieves the underlying tokens. If the option is a put, <code>receiver</code> retrieves the strike tokens.</p> <p>MUST revert if the address calling the function is not the writer of the option issuance.<br /> MUST revert if <code>exerciseWindowEnd</code> is greater or equals than the current time.<br /> If equals to the zero address, MUST set <code>receiver</code> to caller's address.</p> <p><em>Transfers the un-exercised collateral to the writer's address.</em> <em>MAY delete the option issuance from the contract if the retrieval was successful.</em> <em>Emits <code>Expired</code> event if the retrieval was successful.</em></p> <h4 id="cancel"><code>cancel</code></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"> cancel</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"> receiver</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Allows writer to cancel the option and retrieve tokens used as collateral. These tokens are transferred to <code>receiver</code>.<br /> If the option is a call, <code>receiver</code> retrieves the underlying tokens. If the option is a put, <code>receiver</code> retrieves the strike tokens.</p> <p>MUST revert if the address calling the function is not the writer of the option issuance.<br /> MUST revert if at least one option's fraction has been bought.<br /> If equals to the zero address, MUST set <code>receiver</code> to caller's address.</p> <p><em>Transfers the un-exercised collateral to the writer's address.</em> <em>MAY delete the option issuance from the contract if the cancelation was successful.</em> <em>Emits <code>Canceled</code> event if the cancelation was successful.</em></p> <h4 id="updatepremium"><code>updatePremium</code></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"> updatePremium</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-storage z-type"> external</span><span>;</span></span></code></pre> <p>Allows the writer to update the premium that buyers will need to provide for buying the options.</p> <p><strong>Note that the <code>amount</code> will be for the whole underlying amount, not only for the options that might still be available for purchase.</strong></p> <p>MUST revert if the address calling the function is not the writer of the option issuance.<br /> MUST revert if the current time is greater than <code>exerciseWindowEnd</code>.</p> <p><em>Emits <code>PremiumUpdated</code> event when the function call was handled successfully.</em></p> <h4 id="updateallowed"><code>updateAllowed</code></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"> updateAllowed</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</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"> allowed</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Allows the writer to update the list of allowed addresses that can buy the option issuance.<br /> If a buyer already bought an option and his address is not in the new list, he will still be able to exercise his purchased options.</p> <p>MUST revert if the address calling the function is not the writer of the option issuance.<br /> MUST revert if the current time is greater than <code>exerciseWindowEnd</code>.</p> <p><em>Emits <code>AllowedUpdated</code> event when the function call was handled successfully.</em></p> <h4 id="issuance"><code>issuance</code></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"> issuance</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">OptionIssuance</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre> <p>Returns all the key information for the option issuance with the given <code>id</code>.</p> <h3 id="events">Events</h3> <h4 id="created"><code>Created</code></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"> Created</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>)</span><span>;</span></span></code></pre> <p>Emitted when the writer has provided option issuance data successfully (and locked down the collateral to the contract). The given <code>id</code> identifies the particular option issuance.</p> <h4 id="bought"><code>Bought</code></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"> Bought</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"> amount</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> buyer</span><span>)</span><span>;</span></span></code></pre> <p>Emitted when options have been bought. Provides information about the option issuance <code>id</code>, the address of <code>buyer</code> and the <code>amount</code> of options bought.</p> <h4 id="exercised"><code>Exercised</code></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"> Exercised</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"> amount</span><span>)</span><span>;</span></span></code></pre> <p>Emitted when the option has been exercised from the option issuance with given <code>id</code> and the given <code>amount</code>.</p> <h4 id="expired"><code>Expired</code></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"> Expired</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></code></pre> <p>Emitted when the writer of the option issuance with <code>id</code> has retrieved the un-exercised collateral.</p> <h4 id="canceled"><code>Canceled</code></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"> Canceled</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></code></pre> <p>Emitted when the option issuance with given <code>id</code> has been cancelled by the writer.</p> <h4 id="premiumupdated"><code>PremiumUpdated</code></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"> PremiumUpdated</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"> amount</span><span>)</span><span>;</span></span></code></pre> <p>Emitted when writer updates the premium to <code>amount</code> for option issuance with given <code>id</code>. Note that the updated premium is for the total issuance.</p> <h4 id="allowedupdated"><code>AllowedUpdated</code></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"> AllowedUpdated</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>[</span><span>]</span><span class="z-variable"> allowed</span><span>)</span><span>;</span></span></code></pre> <p>Emitted when writer updates the list of allowed addresses for option issuance with given <code>id</code>.</p> <h3 id="errors">Errors</h3> <h4 id="forbidden"><code>Forbidden</code></h4> <p>Reverts when the caller is not allowed to perform some actions (general purpose).</p> <h4 id="transferfailed"><code>TransferFailed</code></h4> <p>Reverts when the transfer of tokens failed.</p> <h4 id="timeforbidden"><code>TimeForbidden</code></h4> <p>Reverts when the current time of the execution is invalid.</p> <h4 id="amountforbidden"><code>AmountForbidden</code></h4> <p>Reverts when the amount is invalid.</p> <h4 id="insufficientbalance"><code>InsufficientBalance</code></h4> <p>Reverts when the caller has insufficient balance to perform the action.</p> <h3 id="concrete-examples">Concrete Examples</h3> <h4 id="call-option">Call Option</h4> <p>Let's say Bob sells a <strong>call</strong> option.<br /> He gives the right to anyone to buy <strong>8 TokenA</strong> at <strong>25 TokenB</strong> each between <strong>14th of July 2023</strong> and <strong>16th of July 2023 (at midnight)</strong>.<br /> For such a contract, he wants to receive a premium of <strong>10 TokenC</strong>.</p> <p>Before creating the option, Bob has to transfer the collateral to the contract. This collateral corresponds to the tokens he will have to give if the option if fully exercised (<code>amount</code>). For this option, he has to give as collateral 8 TokenA. He does that by calling the function <code>approve(address spender, uint256 amount)</code> on the TokenA's contract and as parameters the contract's address (<code>spender</code>) and for <code>amount</code>: <strong>8 * 10^(TokenA's decimals)</strong>. Then Bob can execute <code>create()</code> on the contract for issuing the option, giving the following parameters:</p> <ul> <li><code>side</code>: <strong>Call</strong></li> <li><code>underlyingToken</code>: <strong>TokenA's address</strong></li> <li><code>amount</code>: <strong>8 * 10^(TokenA's decimals)</strong></li> <li><code>strikeToken</code>: <strong>TokenB's address</strong></li> <li><code>strike</code>: <strong>25 * 10^(TokenB's decimals)</strong></li> <li><code>premiumToken</code>: <strong>TokenC's address</strong></li> <li><code>premium</code>: <strong>10 * 10^(TokenC's decimals)</strong></li> <li><code>exerciseWindowStart</code>: <strong>1689292800</strong> <em>(2023-07-14 timestamp)</em></li> <li><code>exerciseWindowEnd</code>: <strong>1689465600</strong> <em>(2023-07-16 timestamp)</em></li> <li><code>allowed</code>: <code>[]</code> (open to anyone)</li> </ul> <p>The issuance has ID 88.</p> <p>Alice wants to be able to buy only <strong>4</strong> TokenA. She will first have to pay the premium (that is proportional to its share) by allowing the spending of his 10 TokenC by calling <code>approve(address spender, uint256 amount)</code> on the TokenC's contract and give as parameters the contract's address (<code>spender</code>) and for <code>amount</code>: <strong>4*10^(TokenA's decimals) * 10*10^(TokenC's decimals) / 8*10^(TokenA's decimals)</strong> (amountToBuy * <code>premium</code> / <code>amount</code>). She can then execute <code>buy(88, 4 * 10^(TokenA's decimals))</code> on the contract, and will receive 4*10^(TokenA's decimals) redeem tokens.</p> <p>John, for his part, wants to buy <strong>2</strong> TokenA. He does the same thing and receives <strong>2*10^(TokensA's decimals)</strong> redeem tokens.</p> <p>We're on the 15th of July and Alice wants to exercise his option because 1 TokenA is traded at 50 TokenB! She needs to allow the contract to transfer <strong>4*10^(TokenA's decimals) * 25*10^(TokenB's decimals) / 10^(TokenA's decimals)</strong> (amountToExercise * <code>strike</code> / 10^(<code>TokenA</code>'s decimals)) TokenBs from her account to be able to exercise. When she calls <code>exercise(88, 4 * 10^(TokenA's decimals))</code> on the contract, it will transfer 4 TokenA to Alice, and 4*25 TokenB to Bob.</p> <p>John decided to give his right to exercise to his friend Jimmy. He did that simply by transferring his <strong>2*10^(TokensA's decimals)</strong> redeem tokens to Jimmy's address.<br /> Jimmy decides to only buy <strong>1</strong> TokenA with the option. So he will give to Bob (through the contract) <strong>1*10^(TokenA's decimals) * 25*10^(TokenB's decimals) / 10^(TokenA's decimals)</strong>.</p> <h4 id="put-option">Put Option</h4> <p>Let's say Bob sells a <strong>put</strong> option.<br /> He gives the right to anyone to sell to him <strong>8 TokenA</strong> at <strong>25 TokenB</strong> each between <strong>14th of July 2023</strong> and <strong>16th of July 2023 (at midnight)</strong>.<br /> For such a contract, he wants to receive a premium of <strong>10 TokenC</strong>.</p> <p>Before creating the option, Bob has to transfer the collateral to the contract. This collateral corresponds to the tokens he will have to give if the option if fully exercised (<code>exerciseCost</code>). For this option, he has to give as collateral 200 TokenB (8 * 25). He does that by calling the function <code>approve(address spender, uint256 amount)</code> on the TokenB's contract and as parameters the contract's address (<code>spender</code>) and for <code>amount</code>: <strong>25*10^(Token B's decimals) * 8*10^(TokenB's decimals) / 10^(TokenA's decimals)</strong> (<code>strike</code> * <code>amount</code> / 10^(<code>underlyingToken</code>'s decimals)). Then Bob can execute <code>create()</code> on the contract for issuing the option, giving the following parameters:</p> <ul> <li><code>side</code>: <strong>Put</strong></li> <li><code>underlyingToken</code>: <strong>TokenA's address</strong></li> <li><code>amount</code>: <strong>8 * 10^(TokenA's decimals)</strong></li> <li><code>strikeToken</code>: <strong>TokenB's address</strong></li> <li><code>strike</code>: <strong>25 * 10^(TokenB's decimals)</strong></li> <li><code>premiumToken</code>: <strong>TokenC's address</strong></li> <li><code>premium</code>: <strong>10 * 10^(TokenC's decimals)</strong></li> <li><code>exerciseWindowStart</code>: <strong>1689292800</strong> <em>(2023-07-14 timestamp)</em></li> <li><code>exerciseWindowEnd</code>: <strong>1689465600</strong> <em>(2023-07-16 timestamp)</em></li> <li><code>allowed</code>: <code>[]</code> (open to anyone)</li> </ul> <p>The issuance has ID 88.</p> <p>Alice wants to be able to sell only <strong>4</strong> TokenA. She will first have to pay the premium (that is proportional to its share) by allowing the spending of his 10 TokenC by calling <code>approve(address spender, uint256 amount)</code> on the TokenC's contract and give as parameters the contract's address (<code>spender</code>) and for <code>amount</code>: <strong>4*10^(TokenA's decimals) * 10*10^(TokenC's decimals) / 8*10^(TokenA's decimals)</strong> (amountToSell * <code>premium</code> / <code>amount</code>). She can then execute <code>buy(88, 4 * 10^(TokenA's decimals))</code> on the contract, and will receive 4*10^(TokenA's decimals) redeem tokens.</p> <p>John, for his part, wants to sell <strong>2</strong> TokenA. He does the same thing and receives <strong>2*10^(TokensA's decimals)</strong> redeem tokens.</p> <p>We're on the 15th of July and Alice wants to exercise his option because 1 TokenA is traded at only 10 TokenB! She needs to allow the contract to transfer <strong>4 * 10^(TokenA's decimals)</strong> TokenAs from her account to be able to exercise. When she calls <code>exercise(88, 4 * 10^(TokenA's decimals))</code> on the contract, it will transfer 4*25 TokenB to Alice and 4 TokenA to Bob.</p> <p>John decided to give his right to exercise to his friend Jimmy. He did that simply by transferring his <strong>2*10^(TokensA's decimals)</strong> redeem tokens to Jimmy's address.<br /> Jimmy decides to only sell <strong>1</strong> TokenA with the option. So he will give to Bob (through the contract) <strong>1*10^(TokenA's decimals)</strong>.</p> <h4 id="retrieve-collateral">Retrieve collateral</h4> <p>Let's say Alice never exercised his option because it wasn't profitable enough for her. To retrieve his collateral, Bob would have to wait for the current time to be greater than <code>exerciseWindowEnd</code>. In the examples, this characteristic is set to 2 days, so he would be able to get back his collateral from the 16th of July by simply calling <code>retrieveExpiredTokens()</code>.</p> <h2 id="rationale">Rationale</h2> <p>This contract's concept is oracle-free, because we assume that a rational buyer will exercise his option only if it's profitable for him.</p> <p>The premium is to be determined by the option writer. writer is free to choose how to calculate the premium, e.g. by using <em>Black-Scholes model</em> or something else. writer can update the premium price at will in order to adjust it according to changes on the underlying's price, volatility, time to option expiry and other such factors. Computing the premium off-chain is better for gas costs purposes.</p> <p>This ERC is intended to represent vanilla options. However, exotic options can be built on top of this ERC.<br /> Instead of representing a single option that would be useless after the expiration date, this contract can store as many issuances as needed. Each issuance is identified by an id, and can be bought, exercised, cancelled, etc., independently of the other issuances. This is a better approach for gas costs purposes.</p> <p>It's designed so that the option can be either European or American, by introduction of the <code>exerciseWindowStart</code> and <code>exerciseWindowEnd</code> data points. A buyer can only exercise between <code>exerciseWindowStart</code> and <code>exerciseWindowEnd</code>.</p> <ul> <li>If the option writer considers the option to be European, he can set the <code>exerciseWindowStart</code> in line with the expiration date, and <code>exerciseWindowEnd</code> to the expiration date + a determined time range so that buyers have a period of time to exercise.</li> <li>If the option writer considers the option to be American, he can set the <code>exerciseWindowStart</code> to the current time, and the buyer will be able to exercise the option immediately.</li> </ul> <p>The contract inherently supports multiple buyers for a single option issuance. This is achieved by using ERC-1155 tokens for representing the options. When a buyer buys a fraction of the option issuance, he receives ERC-1155 tokens that represent the fraction of the option issuance. These tokens can be exchanged between users, and are used for exercising the option. With this mechanism, a buyer can decide to exercise only a fraction of what he bought.</p> <p>The contract implements <code>allowed</code> array, which can be used to restrict the addresses that can buy the option issuance. This can be useful if two users agreed for an option off-chain and they want to create it on-chain. This prevents the risk that between the creation of the contract and the purchase by the second user, an on-chain user has already bought the contract.</p> <p>This ERC is designed to handle ERC-20 tokens. However, this standard can be used as a good base for handling other types of tokens, such as <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens. Some attributes and functions signatures (to provide an id instead of an amount for instance) would have to be changed, but the general idea would remain the same.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Contract contains <code>exerciseWindowStart</code> and <code>exerciseWindowEnd</code> data points. These define the determined time range for the buyer to exercise options. When the current time is greater than <code>exerciseWindowEnd</code>, the buyer won't be able to exercise and the writer will be able to retrieve any remaining collateral.</p> <p>For preventing clear arbitrage cases when option writer considers the issuance to be of European options, we would strongly advice the option writer to call <code>updatePremium</code> to considerably increase the premium price when exercise window opens. This will make sure that the bots won't be able to buy any remaining options and immediately exercise them for quick profit. Of course, this standard can be customized and maybe users will find more convenient to update the premium automatically using available tools, instead of doing it manually (especially if the premium is based on specific dynamic metrics like the <em>Black-Scholes model</em>). If the option issuance is considered to be American, such adjustment is of course not needed.</p> <p>This standard implements the <code>updatePremium</code> function, which allows the writer to update the premium price at any time. This function can lead to security issues for the buyer: a buyer could buy an option, and the writer could front-run buyer's transaction by updating the premium price to a very high value. To prevent this, we advise the buyer to only allow for the agreed amount of premium to be spent by the contract, not more.</p> <p>The contract supports multiple buyers for a single option issuance, meaning fractions of the option issuance can be bought. The ecosystem doesn't really support non-integers, so fractions can sometimes lead to rounding errors. This can lead to unexpected results, especially in the <code>buy</code> function: if the premium is set, the buyer has to pay for only a fraction proportional to the amount of options he wants to buy. If that fraction is not an integer, this will truncate and therefore round to floor. This means that writer will receive less than the expected premium. We consider this risk pretty negligible given that most tokens have a high number of decimals, but it's important to be aware of it. Some buyer could exploit this by buying repeatedly small fraction, and therefore paying less than the expected premium. However, this probably wouldn't be profitable given the gas costs.</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-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Sean Darcyhttps://github.com/darcys22 https://wg-eips.ritovision.com/5570/

Non-Fungible Tokens as digital receipts for physical purchases, where the metadata represents a JSON receipt

<h2 id="abstract">Abstract</h2> <p>This ERC proposes a standard schema for digital receipts of transactions. Digital Receipt Non-Fungible Tokens are issued by a vendor when a customer makes a purchase from their store and contains transaction details necessary for record keeping. Digital Receipt Non-Fungible Tokens extend <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> which allows for the management and ownership of unique tokens.</p> <h2 id="motivation">Motivation</h2> <p>Purchases from online retailers include a receipt that is emailed and/or physically provided to the customer. These receipts are critical for many reasons but are provided in an analogue form which is difficult to parse by financial systems. Digital receipts have never gained traction dispite the fact that point of sales systems are already digital and the customers often want this information in their own digital systems. So we are left with a redundant Digital -&gt; Analogue -&gt; Digital process which requires unnecessary data entry or the use of clunky receipt-scanning applications.</p> <p>Digital receipts are relatively simple and can be specified with a schema that can be parsed into JSON or other structured formats. In addition we can prove the receipts validity by digitally signing the receipt using the vendors private keys.</p> <p>As Ethereum scales tooling will need to be developed to provide end users with features (such as receipts) already available to fiat transactions. NFTs provide a unique opportunity to link an on chain purchase with its transaction details directly through the transaction state update. If we conceptually think of a transaction as funds provided to one participant and goods provided to another, then our real life state includes two sides of a transaction, 1) Funds changing ownership and 2) goods changing ownership. NFT receipts are first class citizens of a transaction reflecting the goods changing ownership as part of the transaction state. They will bring our on chain transaction state in line with the changes happening in the real world.</p> <p>The convenience of a direct link to the transaction receipt via the transaction state is significant, other methods of distributing receipts either off chain or through smart contracts separate to the initial transaction lose this link and force the end user to manually locate the transaction details when needed. The benefit can be demonstrated by comparing a wallet that allows a user to click through a transaction to its receipt (available immediately after purchase without any further action) verses a user needing to search through a datastore to locate a receipt for a transaction that they can see in their wallet history.</p> <p>Digital receipt as NFTs can also conceptually include other important information such as item serial numbers and delivery tracking etc.</p> <p>One of the major roadblocks to fully automating our finance world has been the difficulty in tracking transaction details. Human beings physically tracking paper receipts is archaic and NFTs on the blockchain provide a pathway for these systems to be significantly improved.</p> <h2 id="specification">Specification</h2> <p>Transaction Flow:</p> <ul> <li>A customer purchases an item from an online retailer, checking out leads the customer to an option to mint a NFT.</li> <li>The smart contract provides the user with a Digital Receipt Non-Fungible Token.</li> <li>When fulfilling the order, the retailer will upload the digital receipt specified in in the JSON schema below as the metadata to the previously minted NFT.</li> </ul> <h3 id="digital-receipt-json-schema">Digital Receipt JSON Schema</h3> <p>The JSON schema is composed of 2 parts. The root schema contains high level details of the receipt (for example Date and Vendor) and another schema for the optionally recurring line items contained in the receipt.</p> <h4 id="root-schema">Root Schema</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">receipt.json#</span><span class="z-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">Receipt Schema for Digital Receipt Non-Fungible Tokens</span><span class="z-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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">description</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">image</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">receipt</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">title</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">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 token as a digital receipt</span><span class="z-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 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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Description</span><span class="z-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">Brief description of a digital receipt</span><span class="z-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 class="z-support"> &quot;</span><span class="z-support">receipt</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Receipt</span><span class="z-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">Details of the receipt</span><span class="z-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">id</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">date</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">vendor</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">items</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">id</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">title</span><span class="z-support">&quot;</span><span>:</span><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> <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">Unique ID for the receipt generated by the vendor</span><span class="z-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 class="z-support"> &quot;</span><span class="z-support">date</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Date</span><span class="z-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">Date Receipt Issued</span><span class="z-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">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</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">vendor</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Vendor</span><span class="z-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">Details of the entity issuing the receipt</span><span class="z-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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">website</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">title</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">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 vendor. E.g. Acme Corp</span><span class="z-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 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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Logo</span><span class="z-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">URL of the issuer&#39;s logo</span><span class="z-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">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">address</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">title</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">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">List of strings comprising the address of the issuer</span><span class="z-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">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 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></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"> 2</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxItems</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 6</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">website</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Website</span><span class="z-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">URL of the issuer&#39;s website</span><span class="z-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">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">contact</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Contact Details</span><span class="z-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">Details of the person to contact</span><span class="z-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>]</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">title</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">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 contact person</span><span class="z-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 class="z-support"> &quot;</span><span class="z-support">position</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Position</span><span class="z-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">Position / Role of the contact person</span><span class="z-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 class="z-support"> &quot;</span><span class="z-support">tel</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Telephone Number</span><span class="z-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">Telephone number of the contact person</span><span class="z-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 class="z-support"> &quot;</span><span class="z-support">email</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Email</span><span class="z-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">Email of the contact person</span><span class="z-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">format</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">email</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">address</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">title</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">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">List of strings comprising the address of the contact person</span><span class="z-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">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 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></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"> 2</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxItems</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 6</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">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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Items</span><span class="z-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">Items included into the receipt</span><span class="z-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">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">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">item.json#</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">comments</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Comments</span><span class="z-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">Any messages/comments the issuer wishes to convey to the customer</span><span class="z-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 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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">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">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Viewable/Printable Image of the Digital Receipt</span><span class="z-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 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">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</span><span class="z-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">Digital signature by the vendor of receipts data</span><span class="z-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 class="z-support"> &quot;</span><span class="z-support">extra</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Extra</span><span class="z-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">Extra information about the business/receipt as needed</span><span class="z-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 class="giallo-l"><span>}</span></span></code></pre><h4 id="line-items-schema">Line Items Schema</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">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">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">item.json#</span><span class="z-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">id</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">title</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">date</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-punctuation z-definition z-string"> &quot;</span><span class="z-string">tax</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">quantity</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">id</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">title</span><span class="z-support">&quot;</span><span>:</span><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> <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">Unique identifier of the goods or service</span><span class="z-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 class="z-support"> &quot;</span><span class="z-support">title</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">title</span><span class="z-support">&quot;</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>,</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">Title of the goods or service</span><span class="z-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 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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Description</span><span class="z-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 the goods or service</span><span class="z-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 class="z-support"> &quot;</span><span class="z-support">link</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Link</span><span class="z-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">URL link to the web page for the product or sevice</span><span class="z-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">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">contract</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Contract</span><span class="z-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">URL link or hash to an external contract for this product or service</span><span class="z-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 class="z-support"> &quot;</span><span class="z-support">serial_number</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Serial Number</span><span class="z-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">Serial number of the item</span><span class="z-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 class="z-support"> &quot;</span><span class="z-support">date</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Supply Date</span><span class="z-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 date the goods or service were provided</span><span class="z-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">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</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">amount</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Unit Price</span><span class="z-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">Unit Price per item (excluding tax)</span><span class="z-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">number</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">tax</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Tax</span><span class="z-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">Amount of tax charged for 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">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">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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">rate</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>,</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">title</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 Tax</span><span class="z-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">GST/PST etc</span><span class="z-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 class="z-support"> &quot;</span><span class="z-support">rate</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Tax Rate</span><span class="z-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">Tax rate as a percentage</span><span class="z-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">number</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">amount</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Tax 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">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Total amount of tax charged</span><span class="z-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">number</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">quantity</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Quantity</span><span class="z-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">Number of units</span><span class="z-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">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 class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The schema introduced complies with ERC-721's metadata extension, conveniently allowing previous tools for viewing NFTs to show our receipts. The new property "receipt" contains our newly provided receipt structure and the signature property optionally allows the vendor to digitally sign the receipt structure.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is an extension of ERC-721. It is compatible with both optional extensions, Metadata and Enumerable, mentioned in ERC-721.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The data stored in the digital receipt includes various types of personally identifying information (PII), such as the vendor's name, contact details, and the items purchased. PII is sensitive information that can be used to identify, locate, or contact an individual. Protecting the privacy of the customer is of utmost importance, as unauthorized access to PII can lead to identity theft, fraud, or other malicious activities.</p> <p>To ensure the privacy of the customer, it is crucial to encrypt the PII contained within the digital receipt. By encrypting the PII, only authorized parties with the appropriate decryption keys can access and read the information stored in the digital receipt. This ensures that the customer's privacy is maintained, and their data is protected from potential misuse.</p> <p>While encrypting PII is essential, it is important to note that defining a specific encryption standard is beyond the scope of this ERC.</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-31T00:00:00+00:00 2026-02-11T14:48:25+00:00 Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/5568/

Signal to wallets that an action is needed through a well-known function and revert reason

<h2 id="abstract">Abstract</h2> <p>This ERC introduces a minimalistic machine-readable (binary) format to signal to wallets that an action needs to be taken by the user using a well-known function and revert reason. It provides just enough data to be extendable by future ERCs and to take in arbitrary parameters (up to 64 kB of data). Example use cases could include approving a token for an exchange, sending an HTTP request, or requesting the user to rotate their keys after a certain period of time to enforce good hygiene.</p> <h2 id="motivation">Motivation</h2> <p>Oftentimes, a smart contract needs to signal to a wallet that an action needs to be taken, such as to sign a transaction or send an HTTP request to a URL. Traditionally, this has been done by hard-coding the logic into the frontend, but this ERC allows the smart contract itself to request the action.</p> <p>This means that, for example, an exchange or a market can directly tell the wallet to approve the smart contract to spend the token, vastly simplifying front-end code.</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="action-detection">Action Detection</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"> IERC5568</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> walletSignal24</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> selector</span><span>,</span><span class="z-support"> bytes</span><span class="z-variable"> function_data</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint24</span><span class="z-variable"> instruction_id</span><span>,</span><span class="z-support"> bytes</span><span class="z-variable"> instruction_data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>instruction_id</code> of an instruction defined by an ERC MUST be its ERC number unless there are exceptional circumstances (be reasonable). An ERC MUST define exactly zero or one <code>instruction_id</code>. The structure of the instruction data for any <code>instruction_id</code> MUST be defined by the ERC that defines the <code>instruction_id</code>.</p> <p>To indicate that an action needs to be taken, return the <code>instruction_id</code> and <code>instruction_data</code>. To indicate no actions need to be taken, set <code>instruction_id</code> to be <code>0</code> and <code>instruction_data</code> to any value.</p> <h3 id="custom-revert-reason">Custom Revert Reason</h3> <p>To signal an action was not taken, a compliant smart contract MUST revert with the following error:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> WalletSignal24</span><span>(</span><span class="z-support">uint24</span><span> instruction_id</span><span>,</span><span class="z-support"> bytes</span><span> instruction_data</span><span>)</span></span></code></pre> <p>The <code>instruction_id</code> of an instruction defined by an ERC MUST be its ERC number unless there are exceptional circumstances (be reasonable). An ERC MUST define exactly zero or one <code>instruction_id</code>. The structure of the instruction data for any <code>instruction_id</code> MUST be defined by the ERC that defines the <code>instruction_id</code>.</p> <h3 id="responding-to-a-revert">Responding to a Revert</h3> <p>Before submitting a transaction to the mempool, the <code>walletSignal24</code> function MUST be simulated locally. It MUST be treated as if it were a non-<code>view</code> function capable of making state changes (e.g. <code>CALLS</code> to non-<code>view</code> functions are allowed). If the resulting <code>instruction_id</code> is nonzero, an action needs to be taken.</p> <p>The <code>instruction_id</code>, and <code>instruction_data</code> MUST be taken from the <code>walletSignal24</code> simulation. The instruction SHOULD be evaluated as per the relevant ERC. If the instruction is not supported by the wallet, it MUST display an error to the user indicating that is the case. The wallet MUST then re-evaluate the transaction, except if an instruction explicitly states that the transaction MUST NOT be re-evaluated.</p> <p>If an instruction is invalid, or the <code>instruction_id</code>, and <code>instruction_data</code> cannot be parsed, then an error MUST be displayed to the user indicating that is the case. The transaction MUST NOT be re-evaluated.</p> <h2 id="rationale">Rationale</h2> <p>This ERC was explicitly optimized for deployment gas cost and simplicity. It is expected that libraries will eventually be developed that makes this more developer-friendly.</p> <p><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> is not used, since the interface is simple enough that it can be detected simply by calling the function.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <h3 id="human-readable-revert-messages">Human-Readable Revert Messages</h3> <p>See <a href="https://wg-eips.ritovision.com/5568/#revert-reason-collisions">Revert Reason Collisions</a>.</p> <h3 id="erc-3668"><a href="https://wg-eips.ritovision.com/3668/">ERC-3668</a></h3> <p>ERC-3668 can be used alongside this ERC, but it uses a different mechanism than this ERC.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="revert-reason-collisions">Revert Reason Collisions</h3> <p>It is unlikely that the signature of the custom error matches any custom errors in the wild. In the case that it does, no harm is caused unless the data happen to be a valid instruction, which is even more unlikely.</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-19T00:00:00+00:00 2026-02-11T14:48:25+00:00 elie222https://github.com/elie222 Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/5507/

Adds refund functionality to ERC-20, ERC-721, and ERC-1155 tokens

<h2 id="abstract">Abstract</h2> <p>This ERC adds refund functionality for initial token offerings to <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>. Funds are held in escrow until a predetermined time before they are claimable. Until that predetermined time passes, users can receive a refund for tokens they have purchased.</p> <h2 id="motivation">Motivation</h2> <p>The NFT and token spaces lack accountability. For the health of the ecosystem as a whole, better mechanisms to prevent rugpulls from happening are needed. Offering refunds provides greater protection for buyers and increases legitimacy for creators.</p> <p>A standard interface for this particular use case allows for certain benefits:</p> <ul> <li>Greater Compliance with EU "Distance Selling Regulations," which require a 14-day refund period for goods (such as tokens) purchased online</li> <li>Interoperability with various NFT-related applications, such as portfolio browsers, and marketplaces <ul> <li>NFT marketplaces could place a badge indicating that the NFT is still refundable on listings, and offer to refund NFTs instead of listing them on the marketplace</li> <li>DExes could offer to refund tokens if doing so would give a higher yield</li> </ul> </li> <li>Better wallet confirmation dialogs <ul> <li>Wallets can better inform the user of the action that is being taken (tokens being refunded), similar to how transfers often have their own unique dialog</li> <li>DAOs can better display the functionality of smart proposals that include refunding tokens</li> </ul> </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>All implementations MUST use and follow the directions of <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>.</p> <h3 id="erc-20-refund-extension">ERC-20 Refund Extension</h3> <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.17</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 class="z-keyword">import</span><span class="z-string"> &quot;ERC165.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"> @notice</span><span class="z-comment"> Refundable ERC-20 tokens</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 of this interface is `0xf0ca2917`</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC20Refund</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Emitted when a token is refunded</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Emitted by `refund`</span></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 account whose assets are refunded</span></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"> The amount of token (in terms of the indivisible unit) that was refunded</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Refund</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-storage z-type"> indexed</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Emitted when a token is refunded</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Emitted by `refundFrom`</span></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 account that sent the refund</span></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 account whose assets are refunded</span></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"> The amount of token (in terms of the indivisible unit) that was refunded</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RefundFrom</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"> _sender</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-storage z-type"> indexed</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 class="z-storage z-type"> @notice</span><span class="z-comment"> As long as the refund is active, refunds 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"> Make sure to check that the user has the token, and be aware of potential re-entrancy vectors</span></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"> The `amount` to refund</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-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 class="z-storage z-type"> @notice</span><span class="z-comment"> As long as the refund is active and the sender has sufficient approval, refund the tokens and send the ether to the sender</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Make sure to check that the user has the token, and be aware of potential re-entrancy vectors</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The ether goes 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"> from</span><span class="z-comment"> The user from which to refund the assets</span></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"> The `amount` to refund</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> refundFrom</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 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 refund price</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"> _wei</span><span class="z-comment"> The amount of ether (in wei) that would be refunded for a single token unit (10**decimals indivisible units)</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> refundOf</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"> _wei</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"> Gets the first block for which the refund is not active</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"> block</span><span class="z-comment"> The first block where the token cannot be refunded</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> refundDeadlineOf</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"> block</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="erc-721-refund-extension">ERC-721 Refund Extension</h3> <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.17</span><span>;</span></span> <span class="giallo-l"></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;ERC165.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"> @notice</span><span class="z-comment"> Refundable ERC-721 tokens</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 of this interface is `0xe97f3c83`</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC721Refund</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span> /* , </span><span class="z-entity z-name">ERC165</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"> Emitted when a token is refunded</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Emitted by `refund`</span></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 account whose assets are refunded</span></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 `tokenId` that was refunded</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Refund</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-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"> Emitted when a token is refunded</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Emitted by `refundFrom`</span></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 account that sent the refund</span></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 account whose assets are refunded</span></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 `tokenId` that was refunded</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RefundFrom</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"> _sender</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-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"> As long as the refund is active for the given `tokenId`, refunds 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"> Make sure to check that the user has the token, and be aware of potential re-entrancy vectors</span></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 `tokenId` to refund</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-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 class="z-storage z-type"> @notice</span><span class="z-comment"> As long as the refund is active and the sender has sufficient approval, refund the token and send the ether to the sender</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Make sure to check that the user has the token, and be aware of potential re-entrancy vectors</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The ether goes 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"> from</span><span class="z-comment"> The user from which to refund 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"> tokenId</span><span class="z-comment"> The `tokenId` to refund</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> refundFrom</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"> 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 class="z-storage z-type"> @notice</span><span class="z-comment"> Gets the refund price of the specific `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"> tokenId</span><span class="z-comment"> The `tokenId` 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"> _wei</span><span class="z-comment"> The amount of ether (in wei) that would be refunded</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> refundOf</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 class="z-variable z-parameter z-function"> _wei</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"> Gets the first block for which the refund is not active for a given `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"> tokenId</span><span class="z-comment"> The `tokenId` 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"> block</span><span class="z-comment"> The first block where token cannot be refunded</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> refundDeadlineOf</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 class="z-variable"> block</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="optional-erc-721-batch-refund-extension">Optional ERC-721 Batch Refund Extension</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> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;ERC721Refund.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"> @notice</span><span class="z-comment"> Batch Refundable ERC-721 tokens</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 of this interface is ``</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC721BatchRefund</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721Refund</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 one or more tokens are batch refunded</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Emitted by `refundBatch`</span></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 account whose assets are refunded</span></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 `tokenIds` that were refunded</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RefundBatch</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>[</span><span>]</span><span class="z-variable"> _tokenIds</span><span> // </span><span class="z-variable">This</span><span class="z-variable"> may</span><span class="z-variable"> or</span><span class="z-variable"> may</span><span class="z-variable"> not</span><span class="z-variable"> be</span><span class="z-variable"> indexed</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"> Emitted when one or more tokens are batch refunded</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Emitted by `refundFromBatch`</span></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 account that sent the refund</span></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 account whose assets are refunded</span></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 `tokenId` that was refunded</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RefundFromBatch</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"> _sender</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-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></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> As long as the refund is active for the given `tokenIds`, refunds 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"> Make sure to check that the user has the tokens, and be aware of potential re-entrancy vectors</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> These must either succeed or fail together; there are no partial refunds.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> The `tokenId`s to refund</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> refundBatch</span><span>(</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> tokenIds</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"> As long as the refund is active for the given `tokenIds` and the sender has sufficient approval, refund the tokens and send the ether to the sender</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Make sure to check that the user has the tokens, and be aware of potential re-entrancy vectors</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The ether goes to msg.sender.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> These must either succeed or fail together; there are no partial refunds.</span></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 user from which to refund 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"> tokenIds</span><span class="z-comment"> The `tokenId`s to refund</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> refundFromBatch</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> tokenIds</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="erc-1155-refund-extension">ERC-1155 Refund Extension</h3> <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.17</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;ERC165.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"> @notice</span><span class="z-comment"> Refundable ERC-1155 tokens</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 of this interface is `0x94029f5c`</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC1155Refund</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC1155</span><span> /* , </span><span class="z-entity z-name">ERC165</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"> Emitted when a token is refunded</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Emitted by `refund`</span></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 account that requested a refund</span></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 `tokenId` that was refunded</span></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"> The amount of `tokenId` that was refunded</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Refund</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-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"> _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 class="z-storage z-type"> @notice</span><span class="z-comment"> Emitted when a token is refunded</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Emitted by `refundFrom`</span></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 account that sent the refund</span></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 account whose assets are refunded</span></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 `tokenId` that was refunded</span></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"> The amount of `tokenId` that was refunded</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RefundFrom</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"> _sender</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-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"> As long as the refund is active for the given `tokenId`, refunds 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"> Make sure to check that the user has enough tokens, and be aware of potential re-entrancy vectors</span></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 `tokenId` to refund</span></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"> The amount of `tokenId` to refund</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-support">uint256</span><span class="z-variable"> tokenId</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 class="z-storage z-type"> @notice</span><span class="z-comment"> As long as the refund is active and the sender has sufficient approval, refund the tokens and send the ether to the sender</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Make sure to check that the user has enough tokens, and be aware of potential re-entrancy vectors</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The ether goes 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"> from</span><span class="z-comment"> The user from which to refund 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"> tokenId</span><span class="z-comment"> The `tokenId` to refund</span></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"> The amount of `tokenId` to refund</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> refundFrom</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"> tokenId</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Gets the refund price of the specific `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"> tokenId</span><span class="z-comment"> The `tokenId` 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"> _wei</span><span class="z-comment"> The amount of ether (in wei) that would be refunded for a single token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> refundOf</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 class="z-variable z-parameter z-function"> _wei</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 first block for which the refund is not active for a given `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"> tokenId</span><span class="z-comment"> The `tokenId` 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"> block</span><span class="z-comment"> The first block where the token cannot be refunded</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> refundDeadlineOf</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 class="z-variable"> block</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="optional-erc-1155-batch-refund-extension">Optional ERC-1155 Batch Refund Extension</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> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;ERC1155Refund.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"> @notice</span><span class="z-comment"> Batch Refundable ERC-1155 tokens</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 of this interface is ``</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC1155BatchRefund</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC1155Refund</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 one or more tokens are batch refunded</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Emitted by `refundBatch`</span></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 account that requested a refund</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _tokenIds</span><span class="z-comment"> The `tokenIds` that were refunded</span></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"> The amount of each `tokenId` that was refunded</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RefundBatch</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>[</span><span>]</span><span class="z-variable"> _tokenIds</span><span>, </span><span>// </span><span class="z-variable">This</span><span class="z-variable"> may</span><span class="z-variable"> or</span><span class="z-variable"> may</span><span class="z-variable"> not</span><span class="z-variable"> be</span><span class="z-variable"> indexed</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> _amounts</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"> Emitted when one or more tokens are batch refunded</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Emitted by `refundFromBatch`</span></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 account that sent the refund</span></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 account whose assets are refunded</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _tokenIds</span><span class="z-comment"> The `tokenIds` that was refunded</span></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"> The amount of each `tokenId` that was refunded</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RefundFromBatch</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"> _sender</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>[</span><span>]</span><span class="z-variable"> _tokenId</span><span>, </span><span>// </span><span class="z-variable">This</span><span class="z-variable"> may</span><span class="z-variable"> or</span><span class="z-variable"> may</span><span class="z-variable"> not</span><span class="z-variable"> be</span><span class="z-variable"> indexed</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> _amounts</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"> @notice</span><span class="z-comment"> As long as the refund is active for the given `tokenIds`, refunds 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"> Make sure to check that the user has enough tokens, and be aware of potential re-entrancy vectors</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> These must either succeed or fail together; there are no partial refunds.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenIds</span><span class="z-comment"> The `tokenId`s to refund</span></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"> The amount of each `tokenId` to refund</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> refundBatch</span><span>(</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> tokenIds</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> amounts</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"> As long as the refund is active for the given `tokenIds` and the sender has sufficient approval, refund the tokens and send the ether to the sender</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Make sure to check that the user has the tokens, and be aware of potential re-entrancy vectors</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The ether goes to msg.sender.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> These must either succeed or fail together; there are no partial refunds.</span></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 user from which to refund 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"> tokenIds</span><span class="z-comment"> The `tokenId`s to refund</span></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"> The amount of each `tokenId` to refund</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> refundFromBatch</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> tokenIds</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> amounts</span><span class="z-variable"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p><code>refundDeadlineOf</code> uses blocks instead of timestamps, as timestamps are less reliable than block numbers.</p> <p>The function names of <code>refund</code>, <code>refundOf</code>, and <code>refundDeadlineOf</code> were chosen to fit the naming style of ERC-20, ERC-721, and ERC-1155.</p> <p><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> is required as introspection by DApps would be made significantly harder if it were not.</p> <p>Custom ERC-20 tokens are not supported, as it needlessly increases complexity, and the <code>refundFrom</code> function allows for this functionality when combined with a DEx.</p> <p>Batch refunds are optional, as account abstraction would make atomic operations like these significantly easier. However, they might still reduce gas costs if properly implemented.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues were found.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There is a potential re-entrancy risk with the <code>refund</code> function. Make sure to perform the ether transfer <strong>after</strong> the tokens are destroyed (i.e. obey the checks, effects, interactions pattern).</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-19T00:00:00+00:00 2026-02-11T14:48:25+00:00 Lucas Martín Grasso Ramoshttps://github.com/LucasGrasso Matias Arazihttps://github.com/MatiArazi https://wg-eips.ritovision.com/5516/

An interface for non-transferable, Multi-owner NFTs binding to Ethereum accounts

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a standard interface for non-transferable, multi-owner Soulbound tokens. Previous account-bound token standards face the issue of users losing their account keys or having them rotated, thereby losing their tokens in the process. This EIP provides a solution to this issue that allows for the recycling of SBTs.</p> <h2 id="motivation">Motivation</h2> <p>This EIP was inspired by the main characteristics of the <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> token standard and by articles in which benefits and potential use cases of Soulbound/Accountbound Tokens (SBTs) were presented. This design also allows for batch token transfers, saving on transaction costs. Trading of multiple tokens can be built on top of this standard and it removes the need to approve individual token contracts separately. It is also easy to describe and mix multiple fungible or non-fungible token types in a single contract.</p> <h3 id="characteristics">Characteristics</h3> <ul> <li>The NFT will be non-transferable after the initial transfer</li> <li>Multi-Token</li> <li>Multi-Owner</li> <li>Semi-Fungible</li> </ul> <h3 id="applications">Applications</h3> <ul> <li>Academic Degrees</li> <li>Code audits</li> <li>POAPs (Proof of Attendance Protocol NFTs)</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><strong>Smart contracts implementing this EIP MUST implement all of the functions in the <a href="https://wg-eips.ritovision.com/5516/">ERC-5516</a> interface.</strong></p> <p><strong>Smart contracts implementing this EIP MUST implement the <a href="https://wg-eips.ritovision.com/165/">EIP-165</a> <code>supportsInterface</code> function and MUST return the constant value <code>true</code> if <code>0x45b253ba</code> is passed through the <code>interfaceID</code> argument.</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.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-storage z-type"> @title</span><span class="z-comment"> Soulbound, Multi-Token standard.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Interface of the EIP-5516</span></span> <span class="giallo-l"><span class="z-keyword"> Note</span><span class="z-comment">: The ERC-165 identifier for this interface is 0x45b253ba.</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"> IERC5516</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 `issuer` creates a new soulbound token and distributes it to `recipients[]`.</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 unique identifier of the newly created 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"> issuer</span><span class="z-comment"> The address of the entity that issued the credential.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> recipients</span><span class="z-comment"> Array of addresses that received the soulbound 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"> metadataURI</span><span class="z-comment"> URI pointing to the token metadata (e.g., IPFS hash).</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"> Issued</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"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> issuer</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-variable"> recipients</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 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 `who` voluntarily renounces their soulbound token under `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 unique identifier of the renounced 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"> who</span><span class="z-comment"> The address that renounced ownership of the 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"> Renounced</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"> who</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"> Issues a new soulbound token to multiple recipients.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Creates a unique token identifier and distributes it to all addresses in `recipients[]`.</span></span> <span class="giallo-l"><span class="z-comment"> * The token is non-transferable after issuance.</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"> * - `recipients[]` MUST NOT be empty.</span></span> <span class="giallo-l"><span class="z-comment"> * - All addresses in `recipients[]` MUST be non-zero.</span></span> <span class="giallo-l"><span class="z-comment"> * - All addresses in `recipients[]` MUST NOT already own a token under the generated `tokenId`.</span></span> <span class="giallo-l"><span class="z-comment"> * - Caller MUST be an authorized issuer.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {Issued} event.</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"> recipients</span><span class="z-comment"> Array of addresses that will receive the soulbound 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"> metadataURI</span><span class="z-comment"> URI pointing to the token metadata (IPFS, Arweave, HTTP, etc.).</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 unique identifier of the newly created 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"> issue</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"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> metadataURI</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">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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Allows the token holder to voluntarily renounce their soulbound token.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Once renounced, the holder no longer owns the token and cannot reclaim it.</span></span> <span class="giallo-l"><span class="z-comment"> * This action is irreversible.</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"> * - Caller MUST own the token under `tokenId`.</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 {Renounced} event.</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 unique identifier of the token to renounce.</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"> renounce</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"> Checks if a given address owns a specific soulbound token.</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"> who</span><span class="z-comment"> The address to check ownership 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"> tokenId</span><span class="z-comment"> The unique 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 `who` owns the token under `tokenId`, 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"> has</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"> 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 URI for a given token ID.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * The URI typically points to a JSON file containing token metadata.</span></span> <span class="giallo-l"><span class="z-comment"> * This may be an IPFS hash, Arweave transaction ID, or HTTP URL.</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"> * - `tokenId` MUST exist.</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 unique 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"> The</span><span class="z-comment"> complete URI string for the token metadata.</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"> uri</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><h2 id="rationale">Rationale</h2> <h3 id="erc-5516-as-certificates"><a href="https://wg-eips.ritovision.com/5516/">ERC-5516</a> as certificates</h3> <p>The original idea for this proposal aroused from a neccesity of emitting on-chain certificates to multiple people. We thought that having to emit one token per account has redundant, and we originally developed a <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> partial-compatible implementation.</p> <p>After revisiting our proposal, we thought that it would be cleaner to have a more minimal interface that just serves this purpose only, so we decided to drop the partial backwards compatibility with <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>.</p> <h3 id="sbt-as-a-spinoff-of-eip-1155">SBT as a <em>spinoff</em> of <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a></h3> <p>We saw the vision of the <a href="https://wg-eips.ritovision.com/1155/#metadata">ERC-1155</a> and tried to apply it to Soulbound/Accountbound tokens: We think that having the ability to prove that you own a token, not a particular identifier is valuable, and that it has real world use cases.</p> <h3 id="metadata">Metadata.</h3> <p>We implement a standard method of obtaining metadata (<code>uri</code>) similar to the one defined in <a href="https://wg-eips.ritovision.com/1155/#metadata">ERC-1155</a>:</p> <p>The URI value allows for ID substitution by clients. If the string <code>{id}</code> exists in any URI, clients MUST replace this with the actual token ID in hexadecimal form. This allows for a large number of tokens to use the same on-chain string by defining a URI once, for that large number of tokens.</p> <ul> <li>The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: <code>[0-9a-f]</code> with no 0x prefix.</li> <li>The string format of the substituted hexadecimal ID MUST be leading zero padded to 64 hex characters length if necessary. Example of such a URI: <code>https://token-cdn-domain/{id}.json</code> would be replaced with <code>https://token-cdn-domain/000000000000000000000000000000000000000000000000000000000004cce0.json</code> if the client is referring to token ID 314592/0x4CCE0.</li> </ul> <h3 id="guaranteed-log-trace">Guaranteed log trace</h3> <p>The <a href="https://wg-eips.ritovision.com/5516/">ERC-5516</a> standard guarantees that event logs emitted by the smart contract will provide enough data to create an accurate record of all current token balances. A database or explorer may listen to events and be able to provide indexed and categorized searches of every <a href="https://wg-eips.ritovision.com/5516/">ERC-5516</a> token in the contract.</p> <h3 id="exception-handling">Exception handling</h3> <p>Given the non-transferability property of SBTs, if a user's keys to an account get compromised or rotated, such user may lose the ability to associate themselves with the token.</p> <p><strong>Given the multi-owner characteristic of this EIP, SBTs will be able to bind to multiple accounts, providing a potential solution to the issue.</strong></p> <p>Multi-owner SBTs can also be issued to a contract account that implements a multi-signature functionality (As recommended in <a href="https://wg-eips.ritovision.com/4973/#exception-handling">EIP-4973</a>).</p> <h3 id="multi-token">Multi-token</h3> <p>The multi-token functionality permits the implementation of multiple token types in the same contract. Furthermore, all emitted tokens are stored in the same contract, preventing redundant bytecode from being deployed to the blockchain. It also facilitates transfer to token issuers, since all issued tokens are stored and can be accessed under the same contract address.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a new token type and is not meant to be backward compatible with any existing tokens other than existing viable souls (any asset that can be identified by <code>[address,id]</code>).</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>You can find an implementation of this standard <a href="https://wg-eips.ritovision.com/5516/./assets/ERC5516.sol">here</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> 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 Buzz Caihttps://github.com/buzzcai https://wg-eips.ritovision.com/5484/

Interface for special NFTs with immutable ownership and pre-determined immutable burn authorization

<h2 id="abstract">Abstract</h2> <p>This EIP defines an interface extending <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> to create soulbound tokens. Before issuance, both parties (the issuer and the receiver), have to agree on who has the authorization to burn this token. Burn authorization is immutable after declaration. After its issuance, a soulbound token can't be transferred, but can be burned based on a predetermined immutable burn authorization.</p> <h2 id="motivation">Motivation</h2> <p>The idea of soulbound tokens has gathered significant attention since its publishing. Without a standard interface, however, soulbound tokens are incompatible. It is hard to develop universal services targeting at soulbound tokens without minimal consensus on the implementation of the tokens.</p> <p>This EIP envisions soulbound tokens as specialized NFTs that will play the roles of credentials, credit records, loan histories, memberships, and many more. In order to provide the flexibility in these scenarios, soulbound tokens must have an application-specific burn authorization and a way to distinguish themselves from regular EIP-721 tokens.</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> <ul> <li> <p>The token MUST implement the following interfaces:</p> <ol> <li><a href="https://wg-eips.ritovision.com/165/">EIP-165</a>’s <code>ERC165</code> (<code>0x01ffc9a7</code>)</li> <li><a href="https://wg-eips.ritovision.com/721/">EIP-721</a>’s <code>ERC721</code> (<code>0x80ac58cd</code>)</li> </ol> </li> <li> <p><code>burnAuth</code> SHALL be presented to receiver before issuance.</p> </li> <li> <p><code>burnAuth</code> SHALL be Immutable after issuance.</p> </li> <li> <p><code>burnAuth</code> SHALL be the sole factor that determines which party has the rights to burn token.</p> </li> <li> <p>The issuer SHALL present token metadata to the receiver and acquire receiver's signature before issuance.</p> </li> <li> <p>The issuer SHALL NOT change metadata after issuance.</p> </li> </ul> <p>/// Note: the EIP-165 identifier for this interface is 0x0489b56f</p> <h3 id="contract-interface">Contract Interface</h3> <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"> IERC5484</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> A guideline to standardlize burn-authorization&#39;s number coding</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> BurnAuth</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> IssuerOnly</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> OwnerOnly</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Both</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Neither</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"> @notice</span><span class="z-comment"> Emitted when a soulbound token is issued.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emit is an add-on to nft&#39;s transfer emit in order to distinguish sbt </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> from vanilla nft while providing backward compatibility.</span></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 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"> to</span><span class="z-comment"> The 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"> tokenId</span><span class="z-comment"> The id of the issued token</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Issued</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></span> <span class="giallo-l"><span class="z-variable"> BurnAuth</span><span class="z-variable"> burnAuth</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"> provides burn authorization of the token id.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> unassigned tokenIds are invalid, and queries 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"> tokenId</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"> burnAuth</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-storage z-type">BurnAuth</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="soulbound-token-sbts-as-an-extension-to-eip-721">Soulbound Token (SBTs) as an extension to EIP-721</h3> <p>We believe that soulbound token serves as a specialized subset of the existing EIP-721 tokens. The advantage of such design is seamless compatibility of soulbound token with existing NFT services. Service providers can treat SBTs like NFTs and do not need to make drastic changes to their existing codebase.</p> <h3 id="non-transferable">Non-Transferable</h3> <p>One problem with current soulbound token implementations that extend from <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> is that all transfer implementations throw errors. A much cleaner approach would be for transfer functions to still throw, but also enable third parties to check beforehand if the contract implements the soulbound interface to avoid calling transfer.</p> <h3 id="burn-authorization">Burn Authorization</h3> <p>We want maximum freedom when it comes to interface usage. A flexible and predetermined rule to burn is crucial. Here are some sample scenarios for different burn authorizations:</p> <ul> <li><code>IssuerOnly</code>: Loan record</li> <li><code>ReceiverOnly</code>: Paid membership</li> <li><code>Both</code>: Credentials</li> <li><code>Neither</code>: Credit history</li> </ul> <p>Burn authorization is tied to specific tokens and immutable after issuance. It is therefore important to inform the receiver and gain receiver's consent before the token is issued.</p> <h3 id="issued-event">Issued Event</h3> <p>On issuing, an <code>Issued</code> event will be emitted alongside <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>'s <code>Transfer</code> event. This design keeps backward compatibility while giving clear signals to thrid-parties that this is a soulBound token issuance event.</p> <h3 id="key-rotations">Key Rotations</h3> <p>A concern Ethereum users have is that soulbound tokens having immutable ownership discourage key rotations. This is a valid concern. Having a burnable soulbound token, however, makes key rotations achievable. The owner of the soulbound token, when in need of key rotations, can inform the issuer of the token. Then the party with burn authorization can burn the token while the issuer can issue a replica to the new address.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backward compatible with <a href="https://wg-eips.ritovision.com/721/">EIP-721</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-08-17T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv https://wg-eips.ritovision.com/5485/

An interface for identifying the sovereignty status, observed jurisdiction, accreditation, and enforcement mechanisms.

<h2 id="abstract">Abstract</h2> <p>Defines a standard interface for smart contracts to declare their sovereignty status, observed jurisdiction, accreditation within that jurisdiction, and the mechanisms by which they may receive and record enforcement actions.</p> <h2 id="motivation">Motivation</h2> <p>Smart contracts are, in essence, digital agreements whose execution is enforced by network consensus. As their use increasingly expands into domains that mirror real-world legal or institutional relationships, one critical component present in traditional systems is missing on-chain: a structured way to express sovereignty, jurisdiction, accreditation, and enforcement.</p> <p>Historically, much of the smart-contract ecosystem has emphasized decentralization and self-sovereignty, implicitly assuming that contracts do not rely on any external legal or institutional framework. However, many practical use cases—especially those that interface with real-world regulations, property rights, or compliance regimes—require an explicit identification of the jurisdiction(s) a contract observes, the authority that has accredited it as a valid actor within that jurisdiction, and the mechanisms by which binding decisions may be communicated to it.</p> <p>This ERC proposes a standardized interface for representing four foundational concepts:</p> <ul> <li><strong>Sovereignty</strong> — whether a contract is self-sovereign or claims allegiance to a higher-order system;</li> <li><strong>Jurisdiction</strong> — which external authority it chooses to observe;</li> <li><strong>Accreditation</strong> — whether that authority formally recognizes the contract as a valid participant within its system; and</li> <li><strong>Enforcement</strong> — how decisions, rulings, or binding actions issued by that authority can be delivered to and acknowledged by the contract.</li> </ul> <p>In many real-world and institutional settings, an entity becomes an actionable participant only after receiving formal accreditation by the relevant authority—whether this is a state chartering a corporation, a school recognizing a student club, a platform onboarding a developer, or a DAO admitting a module into its governance structure. Conversely, some entities explicitly declare their absence of external jurisdictional alignment, operating instead as sovereign actors such as declaration of independence as newly established countries gain their sovereignty, or joining a jurisdictional system as a newly established entity. Representing both modes—subordination and self-sovereignty—is essential for accurately modeling institutional relationships on-chain.</p> <p>By standardizing how smart contracts declare sovereignty, jurisdiction, accreditation, and enforcement pathways, this ERC enables interoperability between legal systems, regulatory frameworks, institutional hierarchies, and on-chain governance models—bridging a structural gap between real-world systems and their digital counterparts.</p> <h3 id="use-cases-primary">Use Cases (Primary)</h3> <p>The primary use cases address the questions related to the status of a contract themselves.</p> <ul> <li><strong>Stablecoins (e.g., USDC):</strong> Require jurisdiction because reserve custody, redemptions, freezes, and regulatory compliance depend on a specific legal authority.</li> <li><strong>Tokenized Stocks / RWAs:</strong> Require jurisdiction because securities laws, transfer restrictions, investor rights, and enforcement vary entirely by legal venue.</li> <li><strong>Regulated Lending Protocols:</strong> Require jurisdiction to define collateral rights, default resolution, licensing requirements, and enforceability of loan agreements.</li> <li><strong>Private Company Equity for Qualified Investors:</strong> Require jurisdiction to enforce accreditation rules, transfer limits, corporate law, and cap-table validity.</li> </ul> <h3 id="use-cases-secondary">Use Cases (Secondary)</h3> <p>The secondary use cases address the questions related to the interactions between contracts.</p> <ul> <li><strong>Jurisdiction Compatibility Checks:</strong> Ensuring that interacting contracts operate under compatible or acceptable jurisdictions.</li> <li><strong>Regulatory Boundary Enforcement:</strong> Gateways, bridges, or marketplaces can restrict integration to contracts meeting specific jurisdictional or accreditation requirements.</li> <li><strong>Good-Standing Verification:</strong> Validating whether a contract is accredited and in compliance under its declared jurisdiction.</li> <li><strong>Jurisdiction-Based Access Control:</strong> Allowing or restricting participation based on jurisdiction or accreditation metadata.</li> <li><strong>Cross-Contract Legal Cohesion:</strong> Ensuring coherent jurisdictional alignment across multi-contract systems, federated DAOs, or hierarchical governance structures.</li> <li><strong>Automated Dispute-Path Selection:</strong> Determining which arbitration venue, legal process, or enforcement route applies when disputes ar</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>A contract compliant with this ERC MUST implement the interface defined below.<br /> The interface provides standardized primitives for declaring a contract’s accreditation source, its observed jurisdiction, and a mechanism for receiving structured enforcement proposals. When the jurisdiction is absent, a contract is self-sovereign.</p> <h3 id="1-data-structures">1. Data Structures</h3> <p>For backward compatibility with existing contracts that implement <a href="https://wg-eips.ritovision.com/5247/">ERC-5247</a>, the interface extends the <code>IERC5247Executable</code> and <code>IERC5247Executables</code> data structures.</p> <h4 id="ierc5247executable"><code>IERC5247Executable</code></h4> <p>Represents a single action that MAY be proposed as part of an enforcement submission.<br /> This structure follows a generic “executable call” pattern: a target address, an optional ETH value, a gas limit, and calldata for invocation.<br /> No guarantees are made regarding execution; implementations MAY ignore or reinterpret these fields.</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"> @notice</span><span class="z-comment"> A single executable action that MAY be proposed as part of an enforcement.</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> IERC5247Executable</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"> The target address to be called if this executable is processed.</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> target</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 amount of ETH (in wei) to send along with the call to `target`.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> value</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 gas limit for the call. Implementations MAY ignore this field.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> gasLimit</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 calldata to send to `target`.</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></code></pre><h4 id="ierc5247executables"><code>IERC5247Executables</code></h4> <p>A batch of <code>IERC5247Executable</code> items representing an ordered enforcement proposal.</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"> @notice</span><span class="z-comment"> A batch of executable actions forming an enforcement proposal.</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> IERC5247Executables</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"> Ordered list of executable actions included in this proposal.</span></span> <span class="giallo-l"><span> IERC5247Executable</span><span>[</span><span>]</span><span> executables</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="2-interface">2. Interface</h3> <h4 id="sourceofaccreditation"><code>sourceOfAccreditation()</code></h4> <p>Returns the address that accredited this contract as a valid participant within some jurisdiction or governance system.</p> <ul> <li>MUST return the accrediting authority’s address if one exists.</li> <li>MUST return <code>address(0)</code> if the contract does not recognize any external accreditation source (e.g., self-sovereign behavior).</li> <li>SHOULD remain stable over the contract’s lifetime or change only through a defined governance or upgrade mechanism.</li> </ul> <h4 id="jurisdiction"><code>jurisdiction()</code></h4> <p>Returns the primary jurisdiction or system whose rules this contract claims to observe.</p> <ul> <li>MAY return the same address as <code>sourceOfAccreditation()</code> when a single contract performs both roles.</li> <li>MUST return <code>address(0)</code> if the contract claims no external jurisdiction.</li> <li>Represents the higher-order system the contract aligns with, independently of accreditation.</li> </ul> <h4 id="imposeenforcement-ierc5247executables-proposal"><code>imposeEnforcement(IERC5247Executables _proposal)</code></h4> <p>A standardized entry point for submitting an enforcement proposal to the contract.</p> <ul> <li> <p>Implementations MUST define and document the access control for this function (e.g., restricted to <code>jurisdiction()</code>, <code>sourceOfAccreditation()</code>, or a curated authority list).</p> </li> <li> <p>Implementations MAY:</p> <ul> <li>immediately execute some or all proposed actions,</li> <li>record the proposal for later deliberation,</li> <li>partially honor or completely ignore the proposal based on policy.</li> </ul> </li> <li> <p>Implementations SHOULD emit events or persist state enabling verifiable on-chain acknowledgment that an enforcement attempt occurred.</p> </li> <li> <p>The function is payable to allow ETH to accompany proposals when executables specify non-zero <code>value</code> or when processing fees apply.</p> </li> </ul> <h3 id="full-interface">Full 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"> IERC5485</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 address that accredited this contract, if any.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST return address(0) if the contract does not recognize </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> an external accreditation source. SHOULD remain stable or change </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> only via defined governance.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> sourceOfAccreditation</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"> @notice</span><span class="z-comment"> Returns the jurisdiction or higher-order system this contract </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> observes.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MAY be the same as `sourceOfAccreditation()`. MUST return address(0) </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> when the contract claims no external jurisdiction (self-sovereign </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> behavior). SHOULD remain stable or change only via defined governance.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> jurisdiction</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"> @notice</span><span class="z-comment"> Submits an enforcement proposal to this contract.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Implementations MUST define access control. Implementations MAY execute,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> schedule, partially honor, reject, or only record `_proposal`. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Implementations SHOULD emit events or store state acknowledging receipt of </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> enforcement proposals. Payable to allow ETH forwarding for executables that </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> specify non-zero value.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> imposeEnforcement</span><span>(</span><span class="z-storage z-type">IERC5247Executables</span><span class="z-variable z-parameter z-function"> _proposal</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></code></pre><h2 id="rationale">Rationale</h2> <h3 id="separation-of-jurisdiction-and-accreditation">Separation of Jurisdiction and Accreditation</h3> <p>This ERC separates <strong>jurisdiction</strong> from <strong>accreditation</strong> because they represent fundamentally different relationships:</p> <ul> <li> <p><strong>Jurisdiction is voluntary.</strong><br /> A contract may unilaterally declare that it observes the rules or norms of a particular system.</p> </li> <li> <p><strong>Accreditation requires external approval.</strong><br /> Only the authority itself can grant formal recognition that a contract is an accepted participant within its system.</p> </li> <li> <p><strong>Jurisdiction expresses alignment; accreditation expresses acceptance.</strong><br /> Declaring jurisdiction does not imply the authority recognizes the contract. Accreditation establishes the reciprocal relationship.</p> </li> <li> <p><strong>Accreditation enables enforcement.</strong><br /> Authorities typically issue enforcement only to contracts they have accredited. Jurisdiction alone does not create this binding pathway.</p> </li> </ul> <p>Keeping these concepts distinct reflects how real-world institutions work: observing a system’s rules is self-declared, but gaining formal standing within that system requires an explicit action by the authority. This distinction ensures more accurate modeling of institutional relationships on-chain.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <ol> <li> <p>The absence of accreditation and jurisdiction is backward compatible with existing contracts, as it is a superset of the existing behavior. More explicitly, a contract that does not implement this interface observes no jurisdiction, by default showing no accreditation and is considered self-sovereign.</p> </li> <li> <p>Using <a href="https://wg-eips.ritovision.com/5247/">ERC-5247</a> as a base interface for enforcement proposals is backward compatible with existing contracts that implement <a href="https://wg-eips.ritovision.com/5247/">ERC-5247</a>, such as Multi-Sig wallets such as treasury of a DAO.</p> </li> </ol> <h2 id="security-considerations">Security Considerations</h2> <p>Similar to a real world scenario, when observing a jurisdiction practically gives the contract the ability to enforce rules on the contract's behavior. Simlar to "Ownable" (<a href="https://wg-eips.ritovision.com/173/">ERC-173</a>) or "AccessControl", implementations MUST be aware of the security implications of this: the security of a contract is compromised if the jurisdiction is compromised.</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-16T00:00:00+00:00 2026-02-11T14:48:25+00:00 IronMan_CHhttps://github.com/coderfengyun https://wg-eips.ritovision.com/5489/

NFT Hyperlink Extension embeds hyperlinks onto NFTs, allowing users to click any hNFT and be transported to any url set by the owner.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a new extension for NFTs (non-fungible token, aka <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>): nft-hyperlink-extention (hNFT), embedding NFTs with hyperlinks, referred to as “hNFTs”. As owners of hNFTs, users may authorize a URL slot to a specific address which can be either an externally-owned account (EOA) or a contract address and hNFT owners are entitled to revoke that authorization at any time. The address which has slot authorization can manage the URL of that slot.</p> <h2 id="motivation">Motivation</h2> <p>As NFTs attract more attention, they have the potential to become the primary medium of Web3. Currently, end users can’t attach rich texts, videos, or images to NFTs, and there’s no way to render these rich-content attachments. Many industries eagerly look forward to this kind of rich-content attachment ability. Attaching, editing, and displaying highly customized information can usefully be standardized.</p> <p>This EIP uses hyperlinks as the aforementioned form of “highly customized attachment on NFT”, and also specifies how to attach, edit, and display these attachments on 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> <h3 id="interface">Interface</h3> <h4 id="ierc5489"><code>IERC5489</code></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.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"> IERC5489</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"> this event emits when the slot on `tokenId` is authorzized to `slotManagerAddr`</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"> SlotAuthorizationCreated</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"> slotManagerAddr</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"> this event emits when the authorization on slot `slotManagerAddr` of token `tokenId` is revoked.</span></span> <span class="giallo-l"><span class="z-comment"> * So, the corresponding DApp can handle this to stop on-going incentives or rights</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"> SlotAuthorizationRevoked</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"> slotManagerAddr</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"> this event emits when the uri on slot `slotManagerAddr` of token `tokenId` has been updated to `uri`.</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"> SlotUriUpdated</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"> slotManagerAddr</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 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> <span class="giallo-l"><span class="z-comment"> * Authorize a hyperlink slot on `tokenId` to address `slotManagerAddr`.</span></span> <span class="giallo-l"><span class="z-comment"> * Indeed slot is an entry in a map whose key is address `slotManagerAddr`.</span></span> <span class="giallo-l"><span class="z-comment"> * Only the address `slotManagerAddr` can manage the specific slot.</span></span> <span class="giallo-l"><span class="z-comment"> * This method will emit SlotAuthorizationCreated 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"> authorizeSlotTo</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"> slotManagerAddr</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> <span class="giallo-l"><span class="z-comment"> * Revoke the authorization of the slot indicated by `slotManagerAddr` on token `tokenId`</span></span> <span class="giallo-l"><span class="z-comment"> * This method will emit SlotAuthorizationRevoked 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"> revokeAuthorization</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"> slotManagerAddr</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> <span class="giallo-l"><span class="z-comment"> * Revoke all authorizations of slot on token `tokenId`</span></span> <span class="giallo-l"><span class="z-comment"> * This method will emit SlotAuthorizationRevoked event for each slot</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"> revokeAllAuthorizations</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> <span class="giallo-l"><span class="z-comment"> * Set uri for a slot on a token, which is indicated by `tokenId` and `slotManagerAddr`</span></span> <span class="giallo-l"><span class="z-comment"> * Only the address with authorization through {authorizeSlotTo} can manipulate this slot.</span></span> <span class="giallo-l"><span class="z-comment"> * This method will emit SlotUriUpdated 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"> setSlotUri</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"> calldata</span><span class="z-variable"> newUri</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">@dev</span><span class="z-comment"> Throws if `tokenId` is not a valid NFT. URIs are defined in RFC 3986.</span></span> <span class="giallo-l"><span class="z-comment"> * The URI MUST point to a JSON file that conforms to the &quot;EIP5489 Metadata JSON schema&quot;.</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * returns the latest uri of an slot on a token, which is indicated by `tokenId`, `slotManagerAddr`</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"> getSlotUri</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"> slotManagerAddr</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 class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>authorizeSlotTo(uint256 tokenId, address slotManagerAddr)</code> function MAY be implemented as public or external.</p> <p>The <code>revokeAuthorization(uint256 tokenId, address slotManagerAddr)</code> function MAY be implemented as public or external.</p> <p>The <code>revokeAllAuthorizations(uint256 tokenId)</code> function MAY be implemented as public or external.</p> <p>The <code>setSlotUri(uint256 tokenId, string calldata newUri)</code> function MAY be implemented as public or external.</p> <p>The <code>getSlotUri(uint256 tokenId, address slotManagerAddr)</code> function MAY be implemented as pure or view.</p> <p>The <code>SlotAuthorizationCreated</code> event MUST be emitted when a slot is authorized to an address.</p> <p>The <code>SlotAuthorizationRevoked</code> event MUST be emitted when a slot authorization is revoked.</p> <p>The <code>SlotUriUpdated</code> event MUSt be emitted when a slot's URI is changed.</p> <p>The <code>supportInterface</code> method MUST return true when called with <code>0x8f65987b</code>.</p> <h3 id="authentication">Authentication</h3> <p>The <code>authorizeSlotTo</code>, <code>revokeAuthorization</code>, and <code>revokeAllAuthorizations</code> functions are authenticated if and only if the message sender is the owner of the token.</p> <h3 id="metadata-json-schema">Metadata JSON schema</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">AD 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">icon</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 slot&#39;s occupier. Consider making any images at a width between 48 and 1080 pixels and aspect ration between 1.91:1 and 4:5 inclusive. Suggest to show this as an thumbnail of the target resource</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">A paragraph which briefly introduce what is the target resource</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">target</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 target resource, sugguest to follow 30X status code to support more redirections, the mime type and content rely on user&#39;s setting</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>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="extends-nft-with-hyperlinks">Extends NFT with hyperlinks</h3> <p>URIs are used to represent the value of slots to ensure enough flexibility to deal with different use cases.</p> <h3 id="authorize-slot-to-address">Authorize slot to address</h3> <p>We use addresses to represent the key of slots to ensure enough flexibility to deal with all use cases.</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>You can find an implementation of this standard in <a href="https://wg-eips.ritovision.com/5489/./assets/contracts/ERC5489.sol"><code>ERC5489.sol</code></a>.</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-08-16T00:00:00+00:00 2026-02-11T14:48:25+00:00 StartfundInchttps://github.com/StartfundInc https://wg-eips.ritovision.com/5528/

Allows refunds for EIP-20 tokens by escrow smart contract

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/20/">EIP-20</a>. This specification defines a type of escrow service with the following flow:</p> <ul> <li>The seller issues tokens.</li> <li>The seller creates an escrow smart contract with detailed escrow information like contract addresses, lock period, exchange rate, additional escrow success conditions, etc.</li> <li>The seller funds seller tokens to the <em>Escrow Contract</em>.</li> <li>Buyers fund buyer tokens which are pre-defined in the <em>Escrow Contract</em>.</li> <li>When the escrow status meets success, the seller can withdraw buyer tokens, and buyers can withdraw seller tokens based on exchange rates.</li> <li>Buyers can withdraw (or refund) their funded token if the escrow process is failed or is in the middle of the escrow process.</li> </ul> <h2 id="motivation">Motivation</h2> <p>Because of the pseudonymous nature of cryptocurrencies, there is no automatic recourse to recover funds that have already been paid.</p> <p>In traditional finance, trusted escrow services solve this problem. In the world of decentralized cryptocurrency, however, it is possible to implement an escrow service without a third-party arbitrator. This standard defines an interface for smart contracts to act as an escrow service with a function where tokens are sent back to the original wallet if the escrow is not completed.</p> <h2 id="specification">Specification</h2> <p>There are two types of contract for the escrow process:</p> <ul> <li><em>Payable Contract</em>: The sellers and buyers use this token to fund the <em>Escrow Contract</em>. This contract MUST override <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> interfaces.</li> <li><em>Escrow Contract</em>: Defines the escrow policies and holds <em>Payable Contract</em>'s token for a certain period. This contract does not requires override <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> interfaces.</li> </ul> <h3 id="methods">Methods</h3> <h4 id="constructor"><code>constructor</code></h4> <p>The <em>Escrow Contract</em> demonstrates details of escrow policies as none-mutable matter in constructor implementation.</p> <p>The <em>Escrow Contract</em> MUST define the following policies:</p> <ul> <li>Seller token contract address</li> <li>Buyer token contract address</li> </ul> <p>The <em>Escrow Contract</em> MAY define the following policies:</p> <ul> <li>Escrow period</li> <li>Maximum (or minimum) number of investors</li> <li>Maximum (or minimum) number of tokens to fund</li> <li>Exchange rates of seller/buyer token</li> <li>KYC verification of users</li> </ul> <h4 id="escrowfund"><code>escrowFund</code></h4> <p>Funds <code>_value</code> amount of tokens to address <code>_to</code>.</p> <p>In the case of <em>Escrow Contract</em>:</p> <ul> <li><code>_to</code> MUST be the user address.</li> <li><code>msg.sender</code> MUST be the <em>Payable Contract</em> address.</li> <li>MUST check policy validations.</li> </ul> <p>In the case of <em>Payable Contract</em>:</p> <ul> <li>The address <code>_to</code> MUST be the <em>Escrow Contract</em> address.</li> <li>MUST call the same function of the <em>Escrow Contract</em> interface. The parameter <code>_to</code> MUST be <code>msg.sender</code> to recognize the user address in the <em>Escrow Contract</em>.</li> </ul> <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"> escrowFund</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></code></pre><h4 id="escrowrefund"><code>escrowRefund</code></h4> <p>Refunds <code>_value</code> amount of tokens from address <code>_from</code>.</p> <p>In the case of <em>Escrow Contract</em>:</p> <ul> <li><code>_from</code> MUST be the user address.</li> <li><code>msg.sender</code> MUST be the <em>Payable Contract</em> address.</li> <li>MUST check policy validations.</li> </ul> <p>In the case of <em>Payable Contract</em>:</p> <ul> <li>The address <code>_from</code> MUST be the <em>Escrow Contract</em> address.</li> <li>MUST call the same function of the <em>Escrow Contract</em> interface. The parameter <code>_from</code> MUST be <code>msg.sender</code> to recognize the user address in the <em>Escrow Contract</em>.</li> </ul> <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"> escrowRefund</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"> _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></code></pre><h4 id="escrowwithdraw"><code>escrowWithdraw</code></h4> <p>Withdraws funds from the escrow account.</p> <p>In the case of <em>Escrow Contract</em>:</p> <ul> <li>MUST check the escrow process is completed.</li> <li>MUST send the remaining balance of seller and buyer tokens to <code>msg.sender</code>'s seller and buyer contract wallets.</li> </ul> <p>In the case of <em>Payable Contract</em>, it is optional.</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"> escrowWithdraw</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></code></pre><h3 id="example-of-interface">Example of interface</h3> <p>This example demonstrates simple exchange of one seller and one buyer in one-to-one exchange rates.</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-storage z-type">interface</span><span class="z-entity z-name"> IERC5528</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"> escrowFund</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"> function</span><span class="z-entity z-name"> escrowRefund</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"> _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"> escrowWithdraw</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 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"> PayableContract</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC5528</span><span>, </span><span class="z-entity z-name">IERC20</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /*</span></span> <span class="giallo-l"><span class="z-comment"> General ERC20 implementations</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"> _transfer</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"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> fromBalance </span><span class="z-keyword">=</span><span> _balances</span><span>[</span><span>from</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>fromBalance </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> amount</span><span>,</span><span class="z-string"> &quot;ERC20: transfer amount exceeds balance&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _balances</span><span>[</span><span>from</span><span>]</span><span class="z-keyword"> =</span><span> fromBalance </span><span class="z-keyword">-</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span> _balances</span><span>[</span><span>to</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</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"> 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"> 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> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><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 class="z-entity z-name"> _transfer</span><span>(</span><span>owner</span><span>,</span><span> to</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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> escrowFund</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-support"> bool</span><span> res </span><span class="z-keyword">=</span><span class="z-entity z-name"> IERC5528</span><span>(</span><span>to</span><span>)</span><span>.</span><span class="z-entity z-name">escrowFund</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 class="z-keyword"> require</span><span>(</span><span>res</span><span>,</span><span class="z-string"> &quot;Fund Failed&quot;</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-language">msg.sender</span><span>,</span><span> to</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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> escrowRefund</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"> _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-support"> bool</span><span> res </span><span class="z-keyword">=</span><span class="z-entity z-name"> IERC5528</span><span>(</span><span>_from</span><span>)</span><span>.</span><span class="z-entity z-name">escrowRefund</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 class="z-keyword"> require</span><span>(</span><span>res</span><span>,</span><span class="z-string"> &quot;Refund Failed&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _transfer</span><span>(</span><span>_from</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 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-storage z-type">contract</span><span class="z-entity z-name"> EscrowContract</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC5528</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"> State</span><span> {</span><span class="z-variable z-other z-enummember"> Inited</span><span>,</span><span class="z-variable z-other z-enummember"> Running</span><span>,</span><span class="z-variable z-other z-enummember"> Success</span><span>,</span><span class="z-variable z-other z-enummember"> Closed</span><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> BalanceData</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> addr</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-support"> address</span><span> _addrSeller</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> _addrBuyer</span><span>;</span></span> <span class="giallo-l"><span> BalanceData _fundSeller</span><span>;</span></span> <span class="giallo-l"><span> BalanceData _fundBuyer</span><span>;</span></span> <span class="giallo-l"><span> EscrowStatus _status</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"> sellerContract</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> buyerContract</span><span>)</span><span>{</span></span> <span class="giallo-l"><span> _addrSeller </span><span class="z-keyword">=</span><span> sellerContract</span><span>;</span></span> <span class="giallo-l"><span> _addrBuyer </span><span class="z-keyword">=</span><span> buyerContract</span><span>;</span></span> <span class="giallo-l"><span> _status </span><span class="z-keyword">=</span><span> State</span><span>.</span><span>Inited</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"> escrowFund</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-keyword"> if</span><span>(</span><span class="z-variable z-language">msg.sender</span><span class="z-keyword"> ==</span><span> _addrSeller</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_status</span><span>.</span><span>state </span><span class="z-keyword">==</span><span> State</span><span>.</span><span>Running</span><span>,</span><span class="z-string"> &quot;must be running state&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _fundSeller</span><span>.</span><span>addr </span><span class="z-keyword">=</span><span> _to</span><span>;</span></span> <span class="giallo-l"><span> _fundSeller</span><span>.</span><span>amount </span><span class="z-keyword">=</span><span> _value</span><span>;</span></span> <span class="giallo-l"><span> _status </span><span class="z-keyword">=</span><span> State</span><span>.</span><span>Success</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-language">msg.sender</span><span class="z-keyword"> ==</span><span> _addrBuyer</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_status</span><span>.</span><span>state </span><span class="z-keyword">==</span><span> State</span><span>.</span><span>Inited</span><span>,</span><span class="z-string"> &quot;must be init state&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _fundBuyer</span><span>.</span><span>addr </span><span class="z-keyword">=</span><span> _to</span><span>;</span></span> <span class="giallo-l"><span> _fundBuyer</span><span>.</span><span>amount </span><span class="z-keyword">=</span><span> _value</span><span>;</span></span> <span class="giallo-l"><span> _status </span><span class="z-keyword">=</span><span> State</span><span>.</span><span>Running</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"> require</span><span>(</span><span class="z-constant">false</span><span>,</span><span class="z-string"> &quot;Invalid to address&quot;</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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> escrowRefund</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"> 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>{</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_status</span><span>.</span><span>state </span><span class="z-keyword">==</span><span> State</span><span>.</span><span>Running</span><span>,</span><span class="z-string"> &quot;refund is only available on running state&quot;</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> _addrBuyer</span><span>,</span><span class="z-string"> &quot;invalid caller for refund&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_fundBuyer</span><span>.</span><span>addr </span><span class="z-keyword">==</span><span> _from</span><span>,</span><span class="z-string"> &quot;only buyer can refund&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_fundBuyer</span><span>.</span><span>amount </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> amount</span><span>,</span><span class="z-string"> &quot;buyer fund is not enough to refund&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _fundBuyer</span><span>.</span><span>amount </span><span class="z-keyword">=</span><span> _fundBuyer</span><span>.</span><span>amount </span><span class="z-keyword">-</span><span> amount</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"> escrowWithdraw</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 class="z-keyword"> require</span><span>(</span><span>_status</span><span>.</span><span>state </span><span class="z-keyword">==</span><span> State</span><span>.</span><span>Success</span><span>,</span><span class="z-string"> &quot;withdraw is only available on success state&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> common </span><span class="z-keyword">=</span><span class="z-entity z-name"> MIN</span><span>(</span><span>_fundBuyer</span><span>.</span><span>amount</span><span>,</span><span> _fundSeller</span><span>.</span><span>amount</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>common </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>)</span><span>{</span></span> <span class="giallo-l"><span> _fundBuyer</span><span>.</span><span>amount </span><span class="z-keyword">=</span><span> _fundBuyer</span><span>.</span><span>amount </span><span class="z-keyword">-</span><span> common</span><span>;</span></span> <span class="giallo-l"><span> _fundSeller</span><span>.</span><span>amount </span><span class="z-keyword">=</span><span> _fundSeller</span><span>.</span><span>amount </span><span class="z-keyword">-</span><span> common</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Exchange</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC5528</span><span>(</span><span>_addrSeller</span><span>)</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>_fundBuyer</span><span>.</span><span>addr</span><span>,</span><span> common</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC5528</span><span>(</span><span>_addrBuyer</span><span>)</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>_fundSeller</span><span>.</span><span>addr</span><span>,</span><span> common</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> send back the remaining balances</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>_fundBuyer</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"> IERC5528</span><span>(</span><span>_addrBuyer</span><span>)</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>_fundBuyer</span><span>.</span><span>addr</span><span>,</span><span> _fundBuyer</span><span>.</span><span>amount</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>_fundSeller</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"> IERC5528</span><span>(</span><span>_addrSeller</span><span>)</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>_fundSeller</span><span>.</span><span>addr</span><span>,</span><span> _fundSeller</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> <span class="giallo-l"><span> _status </span><span class="z-keyword">=</span><span> State</span><span>.</span><span>Closed</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></code></pre><h2 id="rationale">Rationale</h2> <p>The interfaces cover the escrow operation's refundable issue.</p> <p>The suggested 3 functions (<code>escrowFund</code>, <code>escrowRefund</code> and <code>escrowWithdraw</code>) are based on <code>transfer</code> function in EIP-20.</p> <p><code>escrowFund</code> send tokens to the <em>Escrow Contract</em>. The <em>Escrow Contract</em> can hold the contract in the escrow process or reject tokens if the policy does not meet.</p> <p><code>escrowRefund</code> can be invoked in the middle of the escrow process or when the escrow process fails.</p> <p><code>escrowWithdraw</code> allows users (sellers and buyers) to transfer tokens from the escrow account. When the escrow process completes, the seller can get the buyer's token, and the buyers can get the seller's token.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The <em>Payable Contract</em> which implements this EIP is fully backward compatible with the <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> specification.</p> <h2 id="test-cases">Test Cases</h2> <p><a href="https://wg-eips.ritovision.com/5528/./assets/truffule-test.js">Unit test example by truffle</a>.</p> <p>This test case demonstrates the following conditions for exchanging seller/buyer tokens.</p> <ul> <li>The exchange rate is one-to-one.</li> <li>If the number of buyers reaches 2, the escrow process will be terminated(success).</li> <li>Otherwise (not meeting success condition yet), buyers can refund (or withdraw) their funded tokens.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>Since the <em>Escrow Contract</em> controls seller and buyer rights, flaws within the <em>Escrow Contract</em> will directly lead to unexpected behavior and potential loss of funds.</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-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Veega Labshttps://github.com/VeegaLabsOfficial Sean NGhttps://github.com/ngveega Tigerhttps://github.com/tiger0x Fredhttps://github.com/apan826 Fov Caohttps://github.com/fovcao https://wg-eips.ritovision.com/5585/

Allows NFT owners to authorize other users to use their NFTs.

<h2 id="abstract">Abstract</h2> <p>This EIP separates the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> NFT's commercial usage rights from its ownership to allow for the independent management of those rights.</p> <h2 id="motivation">Motivation</h2> <p>Most NFTs have a simplified ownership verification mechanism, with a sole owner of an NFT. Under this model, other rights, such as display, or creating derivative works or distribution, are not possible to grant, limiting the value and commercialization of NFTs. Therefore, the separation of an NFT's ownership and user rights can enhance its commercial value.</p> <p>Commercial right is a broad concept based on the copyright, including the rights of copy, display, distribution, renting, commercial use, modify, reproduce and sublicense etc. With the development of the Metaverse, NFTs are becoming more diverse, with new use cases such as digital collections, virtual real estate, music, art, social media, and digital asset of all kinds. The copyright and authorization based on NFTs are becoming a potential business form.</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"> IERC5585</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"> UserRecord</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 class="z-support"> string</span><span>[</span><span>]</span><span> rights</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> expires</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"> @notice</span><span class="z-comment"> Get all available rights of this NFT project</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"> All</span><span class="z-comment"> the rights that can be authorized to the user</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getRights</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><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"> NFT holder authorizes all the rights of the NFT to a user for a specified period of time</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-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The NFT which is authorized</span></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 to whom the NFT is authorized</span></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 period of time the authorization lasts</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> authorizeUser</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"> uint</span><span class="z-variable"> duration</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"> NFT holder authorizes specific rights to a user for a specified period of time</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. It will throw exception when the rights are not defined by this NFT project</span></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 which is authorized</span></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 to whom the NFT is authorized</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> rights</span><span class="z-comment"> Rights authorized to the user, such as renting, distribution or display 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"> duration</span><span class="z-comment"> The period of time the authorization lasts</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> authorizeUser</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"> string</span><span>[</span><span>]</span><span class="z-variable"> rights</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> duration</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"> The user of the NFT transfers his rights to the new user</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-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The rights of this NFT is transferred to 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"> newUser</span><span class="z-comment"> The new user</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferUserRights</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"> newUser</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"> NFT holder extends the duration of authorization</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. It will throw exception when the rights are not defined by this NFT project</span></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 which has been authorized</span></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 to whom the NFT has been authorized</span></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 new duration of the authorization</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> extendDuration</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"> uint</span><span class="z-variable"> duration</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"> NFT holder updates the rights of authorization</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-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The NFT which has been authorized</span></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 to whom the NFT has been authorized</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> rights</span><span class="z-comment"> New rights authorized to the user</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateUserRights</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"> string</span><span>[</span><span>]</span><span class="z-variable"> rights</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 authorization expired time of the specified NFT and user</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-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"> @param</span><span class="z-variable z-other"> user</span><span class="z-comment"> The user who has been authorized</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"> authorization expired time</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getExpires</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-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"> Get the rights of the specified NFT and user</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-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The NFT to get the 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"> user</span><span class="z-comment"> The user who has been authorized</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"> rights has been authorized</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getUserRights</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-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><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 contract owner can update the number of users that can be authorized per 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"> userLimit</span><span class="z-comment"> The number of users set by operators only</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateUserLimit</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> userLimit</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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> resetAllowed flag can be updated by contract owner to control whether the authorization can be revoked or not </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> resetAllowed</span><span class="z-comment"> It is the boolean flag</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateResetAllowed</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> resetAllowed</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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Check if the token is available for authorization</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 be checked the availability</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"> or false whether the NFT is available for authorization or not</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkAuthorizationAvailability</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-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"> Clear authorization of a specified user</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. The function works when resetAllowed is true and it will throw exception when 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"> tokenId</span><span class="z-comment"> The NFT on which the authorization based</span></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 authorization will be cleared</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> resetUser</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-storage z-type"> external</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"> Emitted when the user of a NFT is </span><span class="z-keyword">changed</span><span class="z-comment"> or the authorization expires time is updated</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> param tokenId The NFT on which the authorization based</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> param indexed user The user to whom the NFT authorized</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> rights</span><span class="z-comment"> Rights authorized 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"> expires</span><span class="z-comment"> The expires time of the authorization</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> authorizeUser</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">string</span><span>[</span><span>]</span><span class="z-variable"> rights</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> expires</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"> Emitted when the number of users that can be authorized per NFT is updated</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> userLimit</span><span class="z-comment"> The number of users set by operators only</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> updateUserLimit</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> userLimit</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>getRights()</code> function MAY be implemented as pure and view.</p> <p>The <code>authorizeUser(uint256 tokenId, address user, uint duration)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>authorizeUser(uint256 tokenId, address user, string[] rights; uint duration)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>transferUserRights(uint256 tokenId, address newUser)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>extendDuration(uint256 tokenId, address user, uint duration)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>updateUserRights(uint256 tokenId, address user, string[] rights)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>getExpires(uint256 tokenId, address user)</code> function MAY be implemented as <code>pure</code> or <code>view</code>.</p> <p>The <code>getUserRights(uint256 tokenId, address user)</code> function MAY be implemented as pure and view.</p> <p>The <code>updateUserLimit(unit256 userLimit)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>updateResetAllowed(bool resetAllowed)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>checkAuthorizationAvailability(uint256 tokenId)</code> function MAY be implemented as <code>pure</code> or <code>view</code>.</p> <p>The <code>resetUser(uint256 tokenId, address user)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>authorizeUser</code> event MUST be emitted when the user of a NFT is changed or the authorization expires time is updated.</p> <p>The <code>updateUserLimit</code> event MUST be emitted when the number of users that can be authorized per NFT is updated.</p> <h2 id="rationale">Rationale</h2> <p>First of all, NFT contract owner can set the maximum number of authorized users to each NFT and whether the NFT owner can cancel the authorization at any time to protect the interests of the parties involved.</p> <p>Secondly, there is a <code>resetAllowed</code> flag to control the rights between the NFT owner and the users for the contract owner. If the flag is set to true, then the NFT owner can disable usage rights of all authorized users at any time.</p> <p>Thirdly, the rights within the user record struct is used to store what rights has been authorized to a user by the NFT owner, in other words, the NFT owner can authorize a user with specific rights and update it when necessary.</p> <p>Finally, this design can be seamlessly integrated with third parties. It is an extension of ERC-721, therefore it can be easily integrated into a new NFT project. Other projects can directly interact with these interfaces and functions to implement their own types of transactions. For example, an announcement platform could use this EIP to allow all NFT owners to make authorization or deauthorization at any time.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> since it is an extension of it.</p> <h2 id="security-considerations">Security Considerations</h2> <p>When the <code>resetAllowed</code> flag is false, which means the authorization can not be revoked by NFT owner during the period of authorization, users of the EIP need to make sure the authorization fee can be fairly assigned if the NFT was sold to a new holder.</p> <p>Here is a solution for taking reference: the authorization fee paid by the users can be held in an escrow contract for a period of time depending on the duration of the authorization. For example, if the authorization duration is 12 months and the fee in total is 10 ETH, then if the NFT is transferred after 3 months, then only 2.5 ETH would be sent and the remaining 7.5 ETH would be refunded.</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-13T00:00:00+00:00 2026-02-11T14:48:26+00:00 Toni Wahrstätterhttps://github.com/nerolation Matt Solomonhttps://github.com/mds1 Ben DiFrancescohttps://github.com/apbendi Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/5564/

Private, non-interactive transactions

<h2 id="abstract">Abstract</h2> <p>This specification establishes a standardized method for interacting with stealth addresses, which allow senders of transactions or transfers to non-interactively generate private accounts exclusively accessible by their recipients. Moreover, this specification enables developers to create stealth address protocols based on the foundational implementation outlined in this ERC, utilizing a singleton contract deployed at <code>0x55649E01B5Df198D18D95b5cc5051630cfD45564</code> to emit the necessary information for recipients. In addition to the base implementation, this ERC also outlines the first implementation of a cryptographic scheme, specifically the SECP256k1 curve.</p> <h2 id="motivation">Motivation</h2> <p>The standardization of non-interactive stealth address generation presents the potential to significantly improve the privacy capabilities of the Ethereum network and other EVM-compatible chains by allowing recipients to remain private when receiving assets. This is accomplished through the sender generating a stealth address based on a shared secret known exclusively to the sender and recipient. The recipients alone can access the funds stored at their stealth addresses, as they are the sole possessors of the necessary private key. As a result, observers are unable to associate the recipient's stealth address with their identity, thereby preserving the recipient's privacy and leaving the sender as the only party privy to this information. By offering a foundational implementation in the form of a single contract that is compatible with multiple cryptographic schemes, recipients are granted a centralized location to monitor, ensuring they do not overlook any incoming transactions.</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>Definitions:</p> <ul> <li>A "stealth meta-address" is a set of one or two public keys that can be used to compute a stealth address for a given recipient.</li> <li>A "spending key" is a private key that can be used to spend funds sent to a stealth address. A "spending public key" is the corresponding public key.</li> <li>A "viewing key" is a private key that can be used to determine if funds sent to a stealth address belong to the recipient who controls the corresponding spending key. A "viewing public key" is the corresponding public key.</li> </ul> <p>Different stealth address schemes will have different expected stealth meta-address lengths. A scheme that uses public keys of length <code>n</code> bytes MUST define stealth meta-addresses as follows:</p> <ul> <li>A stealth meta-address of length <code>n</code> uses the same stealth meta-address for the spending public key and viewing public key.</li> <li>A stealth meta-address of length <code>2n</code> uses the first <code>n</code> bytes as the spending public key and the last <code>n</code> bytes as the viewing public key.</li> </ul> <p>Given a recipient's stealth meta-address, a sender MUST be able generate a stealth address for the recipient by calling a method with the following signature:</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"> @notice</span><span class="z-comment"> Generates a stealth address from a stealth meta 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"> stealthMetaAddress</span><span class="z-comment"> The recipient&#39;s stealth meta-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"> stealthAddress</span><span class="z-comment"> The recipient&#39;s stealth 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"> ephemeralPubKey</span><span class="z-comment"> The ephemeral public key used to generate the stealth 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"> viewTag</span><span class="z-comment"> The view tag derived from the shared secret.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> generateStealthAddress</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> stealthMetaAddress</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 class="z-variable"> stealthAddress</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> ephemeralPubKey</span><span>,</span><span class="z-support"> bytes1</span><span class="z-variable"> viewTag</span><span>)</span><span>;</span></span></code></pre> <p>A recipient MUST be able to check if a stealth address belongs to them by calling a method with the following signature:</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"> @notice</span><span class="z-comment"> Returns true if funds sent to a stealth address belong to the recipient who controls</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> the corresponding spending key.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> stealthAddress</span><span class="z-comment"> The recipient&#39;s stealth 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"> ephemeralPubKey</span><span class="z-comment"> The ephemeral public key used to generate the stealth 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"> viewingKey</span><span class="z-comment"> The recipient&#39;s viewing private key.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> spendingPubKey</span><span class="z-comment"> The recipient&#39;s spending public key.</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 funds sent to the stealth address belong to the recipient.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> checkStealthAddress</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> stealthAddress</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"> ephemeralPubKey</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"> viewingKey</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"> spendingPubKey</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></code></pre> <p>A recipient MUST be able to compute the private key for a stealth address by calling a method with the following signature:</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"> @notice</span><span class="z-comment"> Computes the stealth private key for a stealth 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"> stealthAddress</span><span class="z-comment"> The expected stealth 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"> ephemeralPubKey</span><span class="z-comment"> The ephemeral public key used to generate the stealth 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"> viewingKey</span><span class="z-comment"> The recipient&#39;s viewing private key.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> spendingKey</span><span class="z-comment"> The recipient&#39;s spending private key.</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"> stealthKey</span><span class="z-comment"> The stealth private key corresponding to the stealth 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 stealth address input is not strictly necessary, but it is included so the method</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> can validate that the stealth private key was generated correctly.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> computeStealthKey</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> stealthAddress</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"> ephemeralPubKey</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"> viewingKey</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"> spendingKey</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">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre> <p>The implementation of these methods is scheme-specific. The specification of a new stealth address scheme MUST specify the implementation for each of these methods. Additionally, although these function interfaces are specified in Solidity, they do not necessarily ever need to be implemented in Solidity, but any library or SDK conforming to this specification MUST implement these methods with compatible function interfaces.</p> <p>A 256 bit integer (<code>schemeId</code>) is used to identify stealth address schemes. A mapping from the schemeId to its specification MUST be declared in the ERC that proposes to standardize a new stealth address scheme. It is RECOMMENDED that <code>schemeId</code>s are chosen to be monotonically incrementing integers for simplicity, but arbitrary or meaningful <code>schemeId</code>s may be chosen. This ERC introduces a <code>schemeId</code> of <code>1</code> with the following extensions:</p> <ul> <li><code>1</code> is the integer identifier for the scheme,</li> <li><code>viewTags</code> MUST be included in the announcement event and is used to reduce the parsing time for the recipients.</li> <li>SECP256k1 is the algorithm for encoding a stealth meta-address (i.e. the spending public key and viewing public key) into a <code>bytes</code> array, and decoding it from <code>bytes</code> to the native key types of that scheme.</li> <li>SECP256k1 with view tags will be used in <code>generateStealthAddress</code>, <code>checkStealthAddress</code>, and <code>computeStealthKey</code> methods.</li> </ul> <p>This specification additionally defines a singleton <code>ERC5564Announcer</code> contract that emits events to announce when something is sent to a stealth address. This MUST be a singleton contract, with one instance per chain. The contract is specified as follows:</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"> @notice</span><span class="z-comment"> Interface for announcing when something is sent to a stealth address.</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> IERC5564Announcer</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 sending something to a stealth address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See the `announce` method for documentation on the parameters.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Announcement</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"> schemeId</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"> stealthAddress</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"> caller</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> ephemeralPubKey</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> metadata</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"> Called by integrators to emit an `Announcement` 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"> schemeId</span><span class="z-comment"> The integer specifying the applied stealth address scheme.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> stealthAddress</span><span class="z-comment"> The computed stealth address for the 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"> ephemeralPubKey</span><span class="z-comment"> Ephemeral public key used by 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"> metadata</span><span class="z-comment"> An arbitrary field MUST include the view tag in the first byte.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Besides the view tag, the metadata can be used by the senders however they like,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> but the below guidelines are recommended:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The first byte of the metadata MUST be the view tag.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - When sending/interacting with the native token of the blockchain (cf. ETH), the metadata SHOULD be structured as follows:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Byte 1 MUST be the view tag, as specified above.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Bytes 2-5 are `0xeeeeeeee`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Bytes 6-25 are the address 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Bytes 26-57 are the amount of ETH being sent.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - When interacting with ERC-20/ERC-721/etc. tokens, the metadata SHOULD be structured as follows:</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Byte 1 MUST be the view tag, as specified above.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Bytes 2-5 are a function identifier. When a function selector (e.g.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the first (left, high-order in big-endian) four bytes of the Keccak-256</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> hash of the signature of the function, like Solidity and Vyper use) is</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> available, it MUST be used.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Bytes 6-25 are the token contract address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - Bytes 26-57 are the amount of tokens being sent/interacted with for fungible tokens, or</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the token ID for non-fungible tokens.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> announce</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> schemeId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> stealthAddress</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"> ephemeralPubKey</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"> metadata</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> {</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Announcement</span><span>(</span><span>schemeId</span><span>,</span><span> stealthAddress</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span> ephemeralPubKey</span><span>,</span><span> metadata</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="stealth-meta-address-format">Stealth meta-address format</h3> <p>The new address format for the stealth meta-address extends the chain specific address format by adding a <code>st:</code> (<em>stealth</em>) prefix. Thus, a stealth meta-address on Ethereum has the following format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>st:eth:0x&lt;spendingPubKey&gt;&lt;viewingPubKey&gt;</span></span></code></pre> <p>Stealth meta-addresses may be managed by the user and/or registered within a publicly available <code>Registry</code> contract, as delineated in <a href="https://wg-eips.ritovision.com/6538/">ERC-6538</a>. This provides users with a centralized location for identifying stealth meta-addresses associated with other individuals while simultaneously enabling recipients to express their openness to engage via stealth addresses.</p> <p><em>Notably, the address format is used only to differentiate stealth addresses from standard addresses, as the prefix is removed before performing any computations on the stealth meta-address.</em></p> <hr /> <h3 id="initial-implementation-of-secp256k1-with-view-tags">Initial Implementation of SECP256k1 with View Tags</h3> <p>This ERC provides a foundation that is not tied to any specific cryptographic system through the <code>IERC5564Announcer</code> contract. In addition, it introduces the first implementation of a stealth address scheme that utilizes the SECP256k1 elliptic curve and view tags. The SECP256k1 elliptic curve is defined with the equation $y^2 = x^3 + 7 \pmod{p}$, where $p = 2^{256} - 2^{32} - 977$.</p> <p>The following reference is divided into three sections:</p> <ol> <li> <p>Stealth address generation</p> </li> <li> <p>Parsing announcements</p> </li> <li> <p>Stealth private key derivation</p> </li> </ol> <p>Definitions:</p> <ul> <li>$G$ represents the generator point of the curve.</li> </ul> <h4 id="generation-generate-stealth-address-from-stealth-meta-address">Generation - Generate stealth address from stealth meta-address:</h4> <ul> <li> <p>Recipient has access to the private keys $p_{spend}$, $p_{view}$ from which public keys $P_{spend}$ and $P_{view}$ are derived.</p> </li> <li> <p>Recipient has published a stealth meta-address that consists of the public keys $P_{spend}$ and $P_{view}$.</p> </li> <li> <p>Sender passes the stealth meta-address to the <code>generateStealthAddress</code> function.</p> </li> <li> <p>The <code>generateStealthAddress</code> function performs the following computations:</p> <ul> <li>Generate a random 32-byte entropy ephemeral private key $p_{ephemeral}$.</li> <li>Derive the ephemeral public key $P_{ephemeral}$ from $p_{ephemeral}$.</li> <li>Parse the spending and viewing public keys, $P_{spend}$ and $P_{view}$, from the stealth meta-address.</li> <li>A shared secret $s$ is computed as $s = p_{ephemeral} \cdot P_{view}$.</li> <li>The secret is hashed $s_{h} = \textrm{h}(s)$.</li> <li>The view tag $v$ is extracted by taking the most significant byte $s_{h}[0]$,</li> <li>Multiply the hashed shared secret with the generator point $S_h = s_h \cdot G$.</li> <li>The recipient's stealth public key is computed as $P_{stealth} = P_{spend} + S_h$.</li> <li>The recipient's stealth address $a_{stealth}$ is computed as $\textrm{pubkeyToAddress}(P_{stealth})$.</li> <li>The function returns the stealth address $a_{stealth}$, the ephemeral public key $P_{ephemeral}$ and the view tag $v$.</li> </ul> </li> </ul> <h4 id="parsing-locate-one-s-own-stealth-address-es">Parsing - Locate one's own stealth address(es):</h4> <ul> <li> <p>User has access to the viewing private key $p_{view}$ and the spending public key $P_{spend}$.</p> </li> <li> <p>User has access to a set of <code>Announcement</code> events and applies the <code>checkStealthAddress</code> function to each of them.</p> </li> <li> <p>The <code>checkStealthAddress</code> function performs the following computations:</p> <ul> <li>Shared secret $s$ is computed by multiplying the viewing private key with the ephemeral public key of the announcement $s = p_{view}$ * $P_{ephemeral}$.</li> <li>The secret is hashed $s_{h} = h(s)$.</li> <li>The view tag $v$ is extracted by taking the most significant byte $s_{h}[0]$ and can be compared to the given view tag. If the view tags do not match, this <code>Announcement</code> is not for the user and the remaining steps can be skipped. If the view tags match, continue on.</li> <li>Multiply the hashed shared secret with the generator point $S_h = s_h \cdot G$.</li> <li>The stealth public key is computed as $P_{stealth} = P_{spend} + S_h$.</li> <li>The derived stealth address $a_{stealth}$ is computed as $\textrm{pubkeyToAddress}(P_{stealth})$.</li> <li>Return <code>true</code> if the stealth address of the announcement matches the derived stealth address, else return <code>false</code>.</li> </ul> </li> </ul> <h4 id="private-key-derivation-generate-the-stealth-address-private-key-from-the-hashed-shared-secret-and-the-spending-private-key">Private key derivation - Generate the stealth address private key from the hashed shared secret and the spending private key.</h4> <ul> <li> <p>User has access to the viewing private key $p_{view}$ and spending private key $p_{spend}$.</p> </li> <li> <p>User has access to a set of <code>Announcement</code> events for which the <code>checkStealthAddress</code> function returns <code>true</code>.</p> </li> <li> <p>The <code>computeStealthKey</code> function performs the following computations:</p> <ul> <li>Shared secret $s$ is computed by multiplying the viewing private key with the ephemeral public key of the announcement $s = p_{view}$ * $P_{ephemeral}$.</li> <li>The secret is hashed $s_{h} = h(s)$.</li> <li>The stealth private key is computed as $p_{stealth} = p_{spend} + s_h$.</li> </ul> </li> </ul> <h3 id="parsing-considerations">Parsing considerations</h3> <p>Usually, the recipient of a stealth address transaction has to perform the following operations to check whether he was the recipient of a certain transaction:</p> <ul> <li> <p>2x ecMUL,</p> </li> <li> <p>2x HASH,</p> </li> <li> <p>1x ecADD,</p> </li> </ul> <p>The view tags approach is introduced to reduce the parsing time by around 6x. Users only need to perform 1x ecMUL and 1x HASH (skipping 1x ecMUL, 1x ecADD and 1x HASH) for every parsed announcement. The 1-byte view tag length is based on the maximum required space to reliably filter non-matching announcements. With a 1-byte <code>viewTag</code>, the probability for users to skip the remaining computations after hashing the shared secret $h(s)$ is $255/256$. This means that users can almost certainly skip the above three operations for any announcements that do not involve them. Since the view tag reveals one byte of the shared secret, the security margin is reduced from 128 bits to 124 bits. Notably, this only affects the privacy and not the secure generation of a stealth address.</p> <hr /> <h2 id="rationale">Rationale</h2> <p>This ERC emerged from the need for privacy-preserving ways to transfer ownership without disclosing any information about the recipients' identities. Token ownership can expose sensitive personal information. While individuals may wish to donate to a specific organization or country, they might prefer not to disclose a link between themselves and the recipient simultaneously. Standardizing stealth address generation represents a significant step towards unlinkable interactions, since such privacy-enhancing solutions require standards to achieve widespread adoption. Consequently, it is crucial to focus on developing generalizable approaches for implementing related solutions.</p> <p>The stealth address specification standardizes a protocol for generating and locating stealth addresses, facilitating the transfer of assets without requiring prior interaction with the recipient. This enables recipients to verify the receipt of a transfer without the need to interact with the blockchain and query account balances. Importantly, stealth addresses enable token transfer recipients to verify receipt while maintaining their privacy, as only the recipient can recognize themselves as the recipient of the transfer.</p> <p>The authors recognize the trade-off between on- and off-chain efficiency. Although incorporating a Monero-like view tags mechanism enables recipients to parse announcements more efficiently, it adds complexity to the announcement event.</p> <p>The recipient's address and the <code>viewTag</code> must be included in the announcement event, allowing users to quickly verify ownership without querying the chain for positive account balances.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC is fully backward compatible.</p> <h3 id="deployment-method">Deployment Method</h3> <p>The <code>ERC5564Announcer</code> contract is deployed at <code>0x55649E01B5Df198D18D95b5cc5051630cfD45564</code> using <code>CREATE2</code> via the deterministic deployer at <code>0x4e59b44847b379578588920ca78fbf26c0b4956c</code> with a salt of <code>0xd0103a290d760f027c9ca72675f5121d725397fb2f618f05b6c44958b25b4447</code>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>You can find the implementation of the <code>ERC5564Announcer</code> contract <a href="https://wg-eips.ritovision.com/5564/./assets/contracts/ERC5564Announcer.sol">here</a> and the interface <code>IERC5564Announcer.sol</code> <a href="https://wg-eips.ritovision.com/5564/./assets/contracts/interfaces/IERC5564Announcer.sol">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="dos-countermeasures">DoS Countermeasures</h3> <p>There are potential denial of service (DoS) attack vectors that are not mitigated by network transaction fees. Stealth transfer senders cause an externality for recipients, as parsing announcement events consumes computational resources that are not compensated with gas. Therefore, spamming announcement events <em>can</em> be a detriment to the user experience, as it <em>can</em> lead to longer parsing times. We consider the incentives to carry out such an attack to be low because <strong>no monetary benefit can be obtained</strong> However, to tackle potential spam, parsing providers may adopt their own anti-DoS attack methods. These may include ignoring the spamming users when serving announcements to users or, less harsh, de-prioritizing them when ordering the announcements. The indexed <code>caller</code> keyword may help parsing providers to effectively filter known spammers.</p> <p>Furthermore, parsing providers have a few options to counter spam, such as introducing staking mechanisms or requiring senders to pay a <code>toll</code> before including their <code>Announcement</code>. Moreover, a Staking mechanism may allow users to stake an unslashable amount of ETH (similarly to <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a>), to help mitigate potential spam through <em>sybil attacks</em> and enable parsing providers filtering spam more effectively. Introducing a <code>toll</code>, paid by sending users, would simply put a cost on each stealth address transaction, making spamming economically unattractive.</p> <h3 id="recipients-transaction-costs">Recipients' transaction costs</h3> <p>The funding of the stealth address wallet represents a known issue that might breach privacy. The wallet that funds the stealth address MUST NOT have any physical connection to the stealth address owner in order to fully leverage the privacy improvements.</p> <p>Thus, the sender may attach a small amount of ETH to each stealth address transaction, thereby sponsoring subsequent transactions of the recipient.</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-12T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv https://wg-eips.ritovision.com/5453/

A general protocol for approving function calls in the same transaction rely on ERC-5750.

<h2 id="abstract">Abstract</h2> <p>This EIP establish a general protocol for permitting approving function calls in the same transaction rely on <a href="https://wg-eips.ritovision.com/5750/">ERC-5750</a>. Unlike a few prior art (<a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a> for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <code>ERC-4494</code> for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> that usually only permit for a single behavior (<code>transfer</code> for ERC-20 and <code>safeTransferFrom</code> for ERC-721) and a single approver in two transactions (first a <code>permit(...)</code> TX, then a <code>transfer</code>-like TX), this EIP provides a way to permit arbitrary behaviors and aggregating multiple approvals from arbitrary number of approvers in the same transaction, allowing for Multi-Sig or Threshold Signing behavior.</p> <h2 id="motivation">Motivation</h2> <ol> <li>Support permit(approval) alongside a function call.</li> <li>Support a second approval from another user.</li> <li>Support pay-for-by another user</li> <li>Support multi-sig</li> <li>Support persons acting in concert by endorsements</li> <li>Support accumulated voting</li> <li>Support off-line signatures</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="interfaces">Interfaces</h3> <p>The interfaces and structure referenced here are as followed</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.9</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"> ValidityBound</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> functionParamStructHash</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validSince</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validBy</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>}</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"> SingleEndorsementData</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> endorserAddress</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 32</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> sig</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> dynamic = 65</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"> GeneralExtensionDataStruct</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> erc5453MagicWord</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> erc5453Type</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> validSince</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validBy</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> endorsementPayload</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"> IERC5453EndorsementCore</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> eip5453Nonce</span><span>(</span><span class="z-support">address</span><span class="z-variable"> endorser</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"> isEligibleEndorser</span><span>(</span><span class="z-support">address</span><span class="z-variable"> endorser</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"> IERC5453EndorsementDigest</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> computeValidityDigest</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _functionParamStructHash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _validSince</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _validBy</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _nonce</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">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"> computeFunctionParamHash</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"> _functionName</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 z-parameter z-function"> _functionParamPacked</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">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"> IERC5453EndorsementDataTypeA</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> computeExtensionDataTypeA</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validSince</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validBy</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> endorserAddress</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"> sig</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">bytes</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-storage z-type">interface</span><span class="z-entity z-name"> IERC5453EndorsementDataTypeB</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> computeExtensionDataTypeB</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validSince</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validBy</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"> endorserAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> sigs</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">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>See <a href="https://wg-eips.ritovision.com/5453/./assets/IERC5453.sol"><code>IERC5453.sol</code></a>.</p> <h3 id="behavior-specification">Behavior specification</h3> <p>As specified in <a href="https://wg-eips.ritovision.com/5750/">ERC-5750 General Extensibility for Method Behaviors</a>, any compliant method that has an <code>bytes extraData</code> as its last method designated for extending behaviors can conform to <a href="https://wg-eips.ritovision.com/5453/">ERC-5453</a> as the way to indicate a permit from certain user.</p> <ol> <li>Any compliant method of this EIP MUST be a <a href="https://wg-eips.ritovision.com/5750/">ERC-5750</a> compliant method.</li> <li>Caller MUST pass in the last parameter <code>bytes extraData</code> conforming a solidity memory encoded layout bytes of <code>GeneralExtensionDataStruct</code> specified in <em>Section Interfaces</em>. The following descriptions are based on when decoding <code>bytes extraData</code> into a <code>GeneralExtensionDataStruct</code></li> <li>In the <code>GeneralExtensionDataStruct</code>-decoded <code>extraData</code>, caller MUST set the value of <code>GeneralExtensionDataStruct.erc5453MagicWord</code> to be the <code>keccak256("ERC5453-ENDORSEMENT")</code>.</li> <li>Caller MUST set the value of <code>GeneralExtensionDataStruct.erc5453Type</code> to be one of the supported values.</li> </ol> <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"> constant</span><span> ERC5453_TYPE_A </span><span class="z-keyword">=</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> constant</span><span> ERC5453_TYPE_B </span><span class="z-keyword">=</span><span class="z-constant"> 2</span><span>;</span></span></code></pre> <ol start="5"> <li> <p>When the value of <code>GeneralExtensionDataStruct.erc5453Type</code> is set to be <code>ERC5453_TYPE_A</code>, <code>GeneralExtensionDataStruct.endorsementPayload</code> MUST be abi encoded bytes of a <code>SingleEndorsementData</code>.</p> </li> <li> <p>When the value of <code>GeneralExtensionDataStruct.erc5453Type</code> is set to be <code>ERC5453_TYPE_B</code>, <code>GeneralExtensionDataStruct.endorsementPayload</code> MUST be abi encoded bytes of <code>SingleEndorsementData[]</code> (a dynamic array).</p> </li> <li> <p>Each <code>SingleEndorsementData</code> MUST have a <code>address endorserAddress;</code> and a 65-bytes <code>bytes sig</code> signature.</p> </li> <li> <p>Each <code>bytes sig</code> MUST be an ECDSA (secp256k1) signature using private key of signer whose corresponding address is <code>endorserAddress</code> signing <code>validityDigest</code> which is the a hashTypeDataV4 of <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> of hashStruct of <code>ValidityBound</code> data structure as followed:</p> </li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes32</span><span> validityDigest </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-entity z-name"> eip712HashTypedDataV4</span><span>(</span></span> <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">encode</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span></span> <span class="giallo-l"><span class="z-string"> &quot;ValidityBound(bytes32 functionParamStructHash,uint256 validSince,uint256 validBy,uint256 nonce)&quot;</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span> functionParamStructHash</span><span>,</span></span> <span class="giallo-l"><span> _validSince</span><span>,</span></span> <span class="giallo-l"><span> _validBy</span><span>,</span></span> <span class="giallo-l"><span> _nonce</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></code></pre> <ol start="9"> <li>The <code>functionParamStructHash</code> MUST be computed as followed</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support"> bytes32</span><span> functionParamStructHash </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-support"> keccak256</span><span>(</span><span class="z-support">bytes</span><span>(</span><span>_functionStructure</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> _functionParamPacked</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"> return</span><span> functionParamStructHash</span><span>;</span></span></code></pre> <p>whereas</p> <ul> <li><code>_functionStructure</code> MUST be computed as <code>function methodName(type1 param1, type2 param2, ...)</code>.</li> <li><code>_functionParamPacked</code> MUST be computed as <code>enc(param1) || enco(param2) ...</code></li> </ul> <ol start="10"> <li> <p>Upon validating that <code>endorserAddress == ecrecover(validityDigest, signature)</code> or <code>EIP1271(endorserAddress).isValidSignature(validityDigest, signature) == ERC1271.MAGICVALUE</code>, the single endorsement MUST be deemed valid.</p> </li> <li> <p>Compliant method MAY choose to impose a threshold for a number of endorsements needs to be valid in the same <code>ERC5453_TYPE_B</code> kind of <code>endorsementPayload</code>.</p> </li> <li> <p>The <code>validSince</code> and <code>validBy</code> are both inclusive. Implementer MAY choose to use blocknumber or timestamp. Implementor SHOULD find away to indicate whether <code>validSince</code> and <code>validBy</code> is blocknumber or timestamp.</p> </li> </ol> <h2 id="rationale">Rationale</h2> <ol> <li> <p>We chose to have both <code>ERC5453_TYPE_A</code>(single-endorsement) and <code>ERC5453_TYPE_B</code>(multiple-endorsements, same nonce for entire contract) so we could balance a wider range of use cases. E.g. the same use cases of ERC-2612 and <code>ERC-4494</code> can be supported by <code>ERC5453_TYPE_A</code>. And threshold approvals can be done via <code>ERC5453_TYPE_B</code>. More complicated approval types can also be extended by defining new <code>ERC5453_TYPE_?</code></p> </li> <li> <p>We chose to include both <code>validSince</code> and <code>validBy</code> to allow maximum flexibility in expiration. This can be also be supported by EVM natively at if adopted <code>ERC-5081</code> but <code>ERC-5081</code> will not be adopted anytime soon, we choose to add these two numbers in our protocol to allow smart contract level support.</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The design assumes a <code>bytes calldata extraData</code> to maximize the flexibility of future extensions. This assumption is compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> and many other ERC-track EIPs. Those that aren't, such as <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, can also be updated to support it, such as using a wrapper contract or proxy upgrade.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>In addition to the specified algorithm for validating endorser signatures, we also present the following reference implementations.</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.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/utils/cryptography/SignatureChecker.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/EIP712.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC5453.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"> AERC5453Endorsible</span><span class="z-storage"> is</span><span class="z-entity z-name"> EIP712</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC5453EndorsementCore</span><span>, </span><span class="z-entity z-name">IERC5453EndorsementDigest</span><span>, </span><span class="z-entity z-name">IERC5453EndorsementDataTypeA</span><span>, </span><span class="z-entity z-name">IERC5453EndorsementDataTypeB</span><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-storage z-type"> function</span><span class="z-entity z-name"> _validate</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> msgDigest</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> SingleEndorsementData</span><span class="z-storage z-type"> memory</span><span class="z-variable"> endersement</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> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> endersement</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 class="giallo-l"><span class="z-string"> &quot;AERC5453Endorsible: wrong signature length&quot;</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> SignatureChecker</span><span>.</span><span class="z-entity z-name">isValidSignatureNow</span><span>(</span></span> <span class="giallo-l"><span> endersement</span><span>.</span><span>endorserAddress</span><span>,</span></span> <span class="giallo-l"><span> msgDigest</span><span>,</span></span> <span class="giallo-l"><span> endersement</span><span>.</span><span>sig</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;AERC5453Endorsible: invalid signature&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-comment"> //</span><span class="z-comment"> ...</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"> onlyEndorsed</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _functionParamStructHash</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 z-parameter z-function"> _extensionData</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">_isEndorsed</span><span>(</span><span>_functionParamStructHash</span><span>,</span><span> _extensionData</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"> computeExtensionDataTypeB</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validSince</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validBy</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"> endorserAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> sigs</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</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">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>endorserAddress</span><span>.</span><span>length </span><span class="z-keyword">==</span><span> sigs</span><span>.</span><span>length</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> SingleEndorsementData</span><span>[</span><span>]</span></span> <span class="giallo-l"><span class="z-storage z-type"> memory</span><span> endorsements </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span> SingleEndorsementData</span><span>[</span><span>]</span><span>(</span></span> <span class="giallo-l"><span> endorserAddress</span><span>.</span><span>length</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> endorserAddress</span><span>.</span><span>length</span><span>;</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>i</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> endorsements</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> SingleEndorsementData</span><span>(</span></span> <span class="giallo-l"><span> endorserAddress</span><span>[</span><span>i</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> sigs</span><span>[</span><span>i</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 class="z-keyword"> return</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-entity z-name"> GeneralExtensionDataStruct</span><span>(</span></span> <span class="giallo-l"><span> MAGIC_WORLD</span><span>,</span></span> <span class="giallo-l"><span> ERC5453_TYPE_B</span><span>,</span></span> <span class="giallo-l"><span> nonce</span><span>,</span></span> <span class="giallo-l"><span> validSince</span><span>,</span></span> <span class="giallo-l"><span> validBy</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>endorsements</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></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre> <p>See <a href="https://wg-eips.ritovision.com/5453/./assets/AERC5453.sol"><code>AERC5453.sol</code></a></p> <h3 id="reference-implementation-of-endorsableerc721">Reference Implementation of <code>EndorsableERC721</code></h3> <p>Here is a reference implementation of <code>EndorsableERC721</code> that achieves similar behavior of <code>ERC-4494</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.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"> EndorsableERC721</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">AERC5453Endorsible</span><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-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"> _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 z-parameter z-function"> _extraData</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"> onlyEndorsed</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> _computeFunctionParamHash</span><span>(</span></span> <span class="giallo-l"><span> &quot;</span><span class="z-entity z-name">function</span><span class="z-entity z-name"> mint</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"> _tokenId</span><span>)</span><span>&quot;</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 class="z-entity z-name">_to</span><span>,</span><span class="z-entity z-name"> _tokenId</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> _extraData</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"> _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></code></pre> <p>See <a href="https://wg-eips.ritovision.com/5453/./assets/EndorsableERC721.sol"><code>EndorsableERC721.sol</code></a></p> <h3 id="reference-implementation-of-thresholdmultisigforwarder">Reference Implementation of <code>ThresholdMultiSigForwarder</code></h3> <p>Here is a reference implementation of ThresholdMultiSigForwarder that achieves similar behavior of multi-sig threshold approval remote contract call like a Gnosis-Safe wallet.</p> <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"> ThresholdMultiSigForwarder</span><span class="z-storage"> is</span><span class="z-entity z-name"> AERC5453Endorsible</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"> function</span><span class="z-entity z-name"> forward</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _dest</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"> _gasLimit</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 z-parameter z-function"> _calldata</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 z-parameter z-function"> _extraData</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"> onlyEndorsed</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> _computeFunctionParamHash</span><span>(</span></span> <span class="giallo-l"><span> &quot;</span><span class="z-entity z-name">function</span><span class="z-entity z-name"> forward</span><span>(</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> _dest</span><span>,</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> _value</span><span>,</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> _gasLimit</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"> _calldata</span><span>)</span><span>&quot;</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 class="z-entity z-name">_dest</span><span>,</span><span class="z-entity z-name"> _value</span><span>,</span><span class="z-entity z-name"> _gasLimit</span><span>,</span><span class="z-support"> keccak256</span><span>(</span><span class="z-entity z-name">_calldata</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> _extraData</span></span> <span class="giallo-l"><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> errorMessage </span><span class="z-keyword">=</span><span class="z-string"> &quot;Fail to call remote contract&quot;</span><span>;</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bool</span><span> success</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> returndata</span><span>)</span><span class="z-keyword"> =</span><span> _dest</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span> _value</span><span>}</span><span>(</span></span> <span class="giallo-l"><span> _calldata</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> Address</span><span>.</span><span class="z-entity z-name">verifyCallResult</span><span>(</span><span>success</span><span>,</span><span> returndata</span><span>,</span><span> errorMessage</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></code></pre> <p>See <a href="https://wg-eips.ritovision.com/5453/./assets/ThresholdMultiSigForwarder.sol"><code>ThresholdMultiSigForwarder.sol</code></a></p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="replay-attacks">Replay Attacks</h3> <p>A replay attack is a type of attack on cryptography authentication. In a narrow sense, it usually refers to a type of attack that circumvents the cryptographically signature verification by reusing an existing signature for a message being signed again. Any implementations relying on this EIP must realize that all smart endorsements described here are cryptographic signatures that are <em>public</em> and can be obtained by anyone. They must foresee the possibility of a replay of the transactions not only at the exact deployment of the same smart contract, but also other deployments of similar smart contracts, or of a version of the same contract on another <code>chainId</code>, or any other similar attack surfaces. The <code>nonce</code>, <code>validSince</code>, and <code>validBy</code> fields are meant to restrict the surface of attack but might not fully eliminate the risk of all such attacks, e.g. see the <a href="https://wg-eips.ritovision.com/5453/#phishing">Phishing</a> section.</p> <h3 id="phishing">Phishing</h3> <p>It's worth pointing out a special form of replay attack by phishing. An adversary can design another smart contract in a way that the user be tricked into signing a smart endorsement for a seemingly legitimate purpose, but the data-to-designed matches the target application</p> <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 Saber Yuhttps://github.com/OniReimu Qin Wangqin.wang@data61.csiro.au Shange Fushange.fu@monash.edu Yilin Saiyilin.sai@data61.csiro.au Shiping Chenshiping.chen@data61.csiro.au Sherry Xuxiwei.xu@data61.csiro.au Jiangshan Yujiangshan.yu@monash.edu https://wg-eips.ritovision.com/5521/

An ERC-721 extension to construct reference relationships among NFTs

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. It proposes two referable indicators, referring and referred, and a time-based indicator <code>createdTimestamp</code>. The relationship between each NFT forms a directed acyclic graph (DAG). The standard allows users to query, track and analyze their relationships.</p> <p><img src="https://wg-eips.ritovision.com/5521/./assets/system-arch.png" alt="System Architecture" /></p> <h2 id="motivation">Motivation</h2> <p>Many scenarios require the inheritance, reference, and extension of NFTs. For instance, an artist may develop his NFT work based on a previous NFT, or a DJ may remix his record by referring to two pop songs, etc. A gap in existing NFT standards is the absence of established relationships between an NFT and its original creator. This void isolates NFTs, rendering the sale of each one a one-off transaction, thereby obstructing creators from accruing the full value of their intellectual property over time.</p> <p>In this sense, proposing a referable solution for existing NFTs that enables efficient queries on cross-references is necessary. By introducing a reference relationship between NFTs, a sustainable economic model can be established to incentivize continued engagement in creating, using, and promoting NFTs.</p> <p>This standard accordingly introduces a new concept, referable NFT (rNFT), which can transform static NFTs into a dynamically extensible network. We embed reference information, including <code>referring</code> and <code>referred</code> relationships, aiding in the formation of a Direct Acyclic Graph (DAG)-based NFT network. This structure provides a transparent graphical historical record and allows users to query, trace, and analyze relationships. It can enable NFT creators to build upon existing works without the need to start anew.</p> <p>An intuitive example: users can create new NFTs (C, D, E) by referencing existing ones (A, B), while the <code>referred</code> function informs the original NFTs (A, B) about their citations (e.g., A ← D; C ← E; B ← E, and A ← E). Here, the <code>createdTimestamp</code> (block-level) serves as an indicator for the creation time of NFTs (A, B, C, D, E).</p> <h3 id="key-takeaways">Key Takeaways</h3> <p>This standard provides several advantages:</p> <p><em>Clear ownership inheritance</em>: This standard extends the static NFT into a virtually extensible NFT network. Artists do not have to create work isolated from others. The ownership inheritance avoids reinventing the same wheel.</p> <p><em>Incentive Compatibility</em>: This standard clarifies the referable relationship across different NFTs, helping to integrate multiple up-layer incentive models for both original NFT owners and new creators.</p> <p><em>Easy Integration</em>: This standard makes it easier for the existing token standards or third-party protocols. For instance, the rNFT can be applied to rentable scenarios (cf. <a href="https://wg-eips.ritovision.com/5006/">ERC-5006</a> to build a hierarchical rental market, where multiple users can rent the same NFT during the same time or one user can rent multiple NFTs during the same duration).</p> <p><em>Scalable Interoperability</em>: This standard enables cross-contract references, giving a scalable adoption for the broader public with stronger interoperability.</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> <ul> <li><code>UpdateNode</code>: event emitted when <code>setNode</code> is invoked;</li> <li><code>safeMint</code>: mint a new rNFT;</li> <li><code>setNode</code>: set the referring list of an rNFT and update the referred list of each one in the referring list; <ul> <li><code>setNodeReferring</code>: set the referring list of an rNFT;</li> <li><code>setNodeReferred</code>: set the referred list of the given rNFTs sourced from different contracts; <ul> <li><code>setNodeReferredExternal</code>: set the referred list of the given rNFTs sourced from external contracts;</li> </ul> </li> </ul> </li> <li><code>referringOf</code>: get the referring list of an rNFT;</li> <li><code>referredOf</code>: get the referred list of an rNFT;</li> <li><code>createdTimestampOf</code>: get the timestamp of an rNFT when it is being created.</li> </ul> <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> <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-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"> IERC_5521</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"> Logged when a node in the rNFT gets referred and </span><span class="z-keyword">changed</span><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 `node` (i.e., an rNFT) is </span><span class="z-keyword">changed</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"> UpdateNode</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 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>[</span><span>]</span><span class="z-variable"> _address_referringList</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span>[</span><span>]</span><span class="z-variable"> _tokenIds_referringList</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-variable"> _address_referredList</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span>[</span><span>]</span><span class="z-variable"> _tokenIds_referredList</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"> set the referred list of an rNFT associated with different contract addresses and update the referring list of each one in the referred list. Checking the duplication of `addresses` and `tokenIds` is **RECOMMENDED**.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-comment"> `tokenId` of rNFT being set. `addresses` of the contracts in which rNFTs with `tokenIds` being referred accordingly. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> @requirement </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - the size of `addresses` **MUST** be the same as that of `tokenIds`;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - once the size of `tokenIds` is non-zero, the inner size **MUST** also be non-zero;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - the `tokenId` **MUST** be unique within the same contract;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - the `tokenId` **MUST NOT** be the same as `tokenIds[i][j]` if `addresses[i]` is essentially `address(this)`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setNode</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</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"> addresses</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tokenIds</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 referring list of an rNFT.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-comment"> `tokenId` of the rNFT being focused, `_address` of contract address associated with the focused rNFT.</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"> referring mapping of the rNFT.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> referringOf</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"> 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 class="z-storage z-type"> memory</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</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"> get the referred list of an rNFT.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-comment"> `tokenId` of the rNFT being focused, `_address` of contract address associated with the focused rNFT.</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"> referred mapping of the rNFT.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> referredOf</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"> 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 class="z-storage z-type"> memory</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</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"> get the timestamp of an rNFT when is being created.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-comment"> `tokenId` of the rNFT being focused, `_address` of contract address associated with the focused rNFT.</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"> timestamp of the rNFT when is being created with uint256 format.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createdTimestampOf</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"> 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 class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> check supported interfaces, adhereing to ERC165.</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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> TargetContract</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"> @notice</span><span class="z-comment"> set the referred list of an rNFT associated with external contract addresses. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-comment"> `_tokenIds` of rNFTs associated with the contract address `_address` being referred by the rNFT with `tokenId`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> @requirement</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - `_address` **MUST NOT** be the same as `address(this)` where `this` is executed by an external contract where `TargetContract` interface is implemented.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setNodeReferredExternal</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"> uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _tokenIds</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"> referringOf</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"> 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 class="z-storage z-type"> memory</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</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"> referredOf</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"> 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 class="z-storage z-type"> memory</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</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"> createdTimestampOf</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"> 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 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> <span class="giallo-l"></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="is-this-event-informative-enough">Is this event informative enough?</h3> <p><code>UpdateNode</code>: This event disseminates crucial information, including the rNFT ID, its owner, and lists of contract addresses/IDs with rNFTs referring to or referred by the subject rNFT. This data set enables stakeholders to efficiently manage and navigate the complex web of relationships inherent in the rNFT ecosystem.</p> <p>Implementers are free to choose to use a struct (a recommended struct is given in the Reference Implementation), or several separate mappings, or whatever other storage mechanism. Whichever mechanism chosen has no observable effect on the behaviour of the contract, as long as its output can fulfill the <code>UpdateNode</code> event.</p> <h3 id="why-createdtimestampof">Why <code>createdTimestampOf</code>?</h3> <p><code>createdTimestamp</code>: A key principle of this standard is that an rNFT should reference content already accepted by the community (a time-based sequence known by participants). Global timestamps for rNFTs are thus essential, serving to prevent conflicting states (akin to concurrency issues in transaction processing and block organization). We define a block-level timestamp where <code>createdTimestamp = block.timestamp</code> Note that, given that the granularity of references is tied to the block timestamp, it is impractical to discern the order of two rNFTs within the same block.</p> <h3 id="how-is-cross-contract-reference-performed">How is cross-contract reference performed?</h3> <p><code>setNodeReferredExternal</code>: This function operates conditionally, dependent on successful interface verification in external contracts. Such selective invocation ensures backward compatibility and integration with existing contracts, provided they adhere to specified interfaces.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard can be fully <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> compatible by adding an extension function set.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases are included in <a href="https://wg-eips.ritovision.com/5521/./assets/ERC_5521.test.js">ERC_5521.test.js</a></p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The recommended implementation is demonstrated as follows:</p> <ul> <li><code>Relationship</code>: a structure that contains <code>referring</code>, <code>referred</code>, <code>referringKeys</code>, <code>referredKeys</code>, <code>createdTimestamp</code>, and other customized and optional attributes (i.e., not necessarily included in the standard) such as <code>privityOfAgreement</code> recording the ownerships of referred NFTs at the time the Referable NFTs (rNFTs) were being created or <code>profitSharing</code> recording the profit sharing of <code>referring</code>.</li> <li><code>referring</code>: an out-degree indicator, used to show the users this NFT refers to;</li> <li><code>referred</code>: an in-degree indicator, used to show the users who have refereed this NFT;</li> <li><code>referringKeys</code>: a helper for mapping conversion of out-degree indicators, used for events;</li> <li><code>referredKeys</code>: a helper for mapping conversion of in-degree indicators, used for events;</li> <li><code>createdTimestamp</code>: a time-based indicator, used to compare the timestamp of mint, which should not be editable anyhow by callers.</li> <li><code>referringOf</code> and <code>referredOf</code>: First, the current <code>referringOf</code> and <code>referredOf</code> allow cross-contract looking up, while this cannot be done by directly accessing <code>_relationship</code>. Secondly, only if privacy is not a concern, making <code>_relationship</code> public simplifies the contract by relying on Solidity’s automatically generated getters. However, if you need to control the visibility of the data, keeping the state variable private and providing specific getter functions would be the best approach. For example, if <code>_relationship</code> includes details about specific users’ interactions or transactions or some private extensible parameters (in the updated version, we specifically highlight the <code>Relationship</code> can be extended to meet different requirements), always making this data public could reveal users’ behavior patterns or preferences, leading to potential privacy breaches.</li> <li><code>convertMap</code>: This function is essential for retrieving the full mapping contents within a struct. Even if <code>_relationship</code> is public, The getters only allow retrieval of individual values for specific keys. Since we need comprehensive access to all stored addresses, <code>convertMap</code> is necessary to fulfill our event emission requirements.</li> </ul> <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.4</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;./IERC_5521.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"> ERC_5521</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">IERC_5521</span><span>, </span><span class="z-entity z-name">TargetContract</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"> Relationship</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>]</span><span>)</span><span> referring</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>]</span><span>)</span><span> referred</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span> referringKeys</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span> referredKeys</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> createdTimestamp</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> unix timestamp when the rNFT is being created</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> extensible parameters</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ...</span></span> <span class="giallo-l"><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> Relationship</span><span>)</span><span class="z-storage z-type"> internal</span><span> _relationship</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> contractOwner </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 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> contractOwner </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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeMint</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</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"> addresses</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _tokenIds</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"> require(msg.sender == contractOwner, &quot;ERC_rNFT: Only contract owner can mint&quot;);</span></span> <span class="giallo-l"><span class="z-entity z-name"> _safeMint</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> setNode</span><span>(</span><span>tokenId</span><span>,</span><span> addresses</span><span>,</span><span> _tokenIds</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"> @notice</span><span class="z-comment"> set the referred list of an rNFT associated with different contract addresses and update the referring list of each one in the referred 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"> tokenIds</span><span class="z-comment"> array of rNFTs, recommended to check duplication at the caller&#39;s end</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setNode</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</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"> addresses</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tokenIds</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> <span class="giallo-l"><span> addresses</span><span>.</span><span>length </span><span class="z-keyword">==</span><span> tokenIds</span><span>.</span><span>length</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Addresses and TokenID arrays must have the same length&quot;</span></span> <span class="giallo-l"><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> tokenIds</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-keyword"> if</span><span> (</span><span>tokenIds</span><span>[</span><span>i</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"> revert</span><span>(</span><span class="z-string">&quot;ERC_5521: the referring list cannot be empty&quot;</span><span>)</span><span>;</span><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity z-name"> setNodeReferring</span><span>(</span><span>addresses</span><span>,</span><span> tokenId</span><span>,</span><span> tokenIds</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> setNodeReferred</span><span>(</span><span>addresses</span><span>,</span><span> tokenId</span><span>,</span><span> tokenIds</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"> @notice</span><span class="z-comment"> set the referring list of an rNFT associated with different contract addresses </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _tokenIds</span><span class="z-comment"> array of rNFTs associated with addresses, recommended to check duplication at the caller&#39;s end</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setNodeReferring</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"> addresses</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _tokenIds</span><span>)</span><span class="z-storage z-type"> private</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;ERC_5521: transfer caller is not owner nor approved&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> Relationship </span><span class="z-storage z-type">storage</span><span> relationship </span><span class="z-keyword">=</span><span> _relationship</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"></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> addresses</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-keyword"> if</span><span> (</span><span>relationship</span><span>.</span><span>referring</span><span>[</span><span>addresses</span><span>[</span><span>i</span><span>]</span><span>]</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span> {</span><span> relationship</span><span>.</span><span>referringKeys</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>addresses</span><span>[</span><span>i</span><span>]</span><span>)</span><span>;</span><span> }</span><span class="z-comment"> //</span><span class="z-comment"> Add the address if it&#39;s a new entry</span></span> <span class="giallo-l"><span> relationship</span><span>.</span><span>referring</span><span>[</span><span>addresses</span><span>[</span><span>i</span><span>]</span><span>]</span><span class="z-keyword"> =</span><span> _tokenIds</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> relationship</span><span>.</span><span>createdTimestamp </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-entity z-name"> emitEvents</span><span>(</span><span>tokenId</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> set the referred list of an rNFT associated with different contract addresses </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _tokenIds</span><span class="z-comment"> array of rNFTs associated with addresses, recommended to check duplication at the caller&#39;s end</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setNodeReferred</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"> addresses</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _tokenIds</span><span>)</span><span class="z-storage z-type"> private</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> addresses</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-keyword"> if</span><span> (</span><span>addresses</span><span>[</span><span>i</span><span>]</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></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint</span><span> j </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> j </span><span class="z-keyword">&lt;</span><span> _tokenIds</span><span>[</span><span>i</span><span>]</span><span>.</span><span>length</span><span>;</span><span> j</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> Relationship </span><span class="z-storage z-type">storage</span><span> relationship </span><span class="z-keyword">=</span><span> _relationship</span><span>[</span><span>_tokenIds</span><span>[</span><span>i</span><span>]</span><span>[</span><span>j</span><span>]</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>relationship</span><span>.</span><span>referred</span><span>[</span><span>addresses</span><span>[</span><span>i</span><span>]</span><span>]</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span> {</span><span> relationship</span><span>.</span><span>referredKeys</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>addresses</span><span>[</span><span>i</span><span>]</span><span>)</span><span>;</span><span> }</span><span class="z-comment"> //</span><span class="z-comment"> Add the address if it&#39;s a new entry</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>tokenId </span><span class="z-keyword">!=</span><span> _tokenIds</span><span>[</span><span>i</span><span>]</span><span>[</span><span>j</span><span>]</span><span>,</span><span class="z-string"> &quot;ERC_5521: self-reference not allowed&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>relationship</span><span>.</span><span>createdTimestamp </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> {</span><span class="z-keyword"> revert</span><span>(</span><span class="z-string">&quot;ERC_5521: the referred rNFT needs to be a predecessor&quot;</span><span>)</span><span>;</span><span> }</span><span class="z-comment"> //</span><span class="z-comment"> Make sure the reference complies with the timing sequence</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> relationship</span><span>.</span><span>referred</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 class="z-entity z-name">push</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> emitEvents</span><span>(</span><span>_tokenIds</span><span>[</span><span>i</span><span>]</span><span>[</span><span>j</span><span>]</span><span>,</span><span class="z-entity z-name"> ownerOf</span><span>(</span><span>_tokenIds</span><span>[</span><span>i</span><span>]</span><span>[</span><span>j</span><span>]</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> TargetContract targetContractInstance </span><span class="z-keyword">=</span><span class="z-entity z-name"> TargetContract</span><span>(</span><span>addresses</span><span>[</span><span>i</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isSupports </span><span class="z-keyword">=</span><span> targetContractInstance</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span class="z-variable z-language">type</span><span>(</span><span>TargetContract</span><span>)</span><span>.</span><span>interfaceId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>isSupports</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The target contract supports the interface, safe to call functions of the interface.</span></span> <span class="giallo-l"><span> targetContractInstance</span><span>.</span><span class="z-entity z-name">setNodeReferredExternal</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> tokenId</span><span>,</span><span> _tokenIds</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> }</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-storage z-type"> @notice</span><span class="z-comment"> set the referred list of an rNFT associated with different contract addresses </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _tokenIds</span><span class="z-comment"> array of rNFTs associated with addresses, recommended to check duplication at the caller&#39;s end</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setNodeReferredExternal</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"> uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _tokenIds</span><span>)</span><span class="z-storage z-type"> external</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> _tokenIds</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> Relationship </span><span class="z-storage z-type">storage</span><span> relationship </span><span class="z-keyword">=</span><span> _relationship</span><span>[</span><span>_tokenIds</span><span>[</span><span>i</span><span>]</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>relationship</span><span>.</span><span>referred</span><span>[</span><span>_address</span><span>]</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span> {</span><span> relationship</span><span>.</span><span>referredKeys</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>_address</span><span>)</span><span>;</span><span> }</span><span class="z-comment"> //</span><span class="z-comment"> Add the address if it&#39;s a new entry</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_address </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 class="z-string"> &quot;ERC_5521: this must be an external contract address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>relationship</span><span>.</span><span>createdTimestamp </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> {</span><span class="z-keyword"> revert</span><span>(</span><span class="z-string">&quot;ERC_5521: the referred rNFT needs to be a predecessor&quot;</span><span>)</span><span>;</span><span> }</span><span class="z-comment"> //</span><span class="z-comment"> Make sure the reference complies with the timing sequence</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> relationship</span><span>.</span><span>referred</span><span>[</span><span>_address</span><span>]</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> emitEvents</span><span>(</span><span>_tokenIds</span><span>[</span><span>i</span><span>]</span><span>,</span><span class="z-entity z-name"> ownerOf</span><span>(</span><span>_tokenIds</span><span>[</span><span>i</span><span>]</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the referring list of an rNFT</span></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 considered rNFT, _address The corresponding 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"> The</span><span class="z-comment"> referring mapping of an rNFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> referringOf</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"> 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-storage z-type"> virtual</span><span class="z-storage z-type"> override</span><span>(</span><span class="z-entity z-name">IERC_5521</span><span>,</span><span class="z-entity z-name"> TargetContract</span><span>)</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 class="z-support"> uint256</span><span>[</span><span>]</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> _referringKeys</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> _referringValues</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_address </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></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;ERC_5521: token ID not existed&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> (</span><span>_referringKeys</span><span>,</span><span> _referringValues</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> convertMap</span><span>(</span><span>tokenId</span><span>,</span><span class="z-constant"> true</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> TargetContract targetContractInstance </span><span class="z-keyword">=</span><span class="z-entity z-name"> TargetContract</span><span>(</span><span>_address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>targetContractInstance</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span class="z-variable z-language">type</span><span>(</span><span>TargetContract</span><span>)</span><span>.</span><span>interfaceId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC_5521: target contract not supported&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> (</span><span>_referringKeys</span><span>,</span><span> _referringValues</span><span>)</span><span class="z-keyword"> =</span><span> targetContractInstance</span><span>.</span><span class="z-entity z-name">referringOf</span><span>(</span><span>_address</span><span>,</span><span> tokenId</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"><span> }</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>_referringKeys</span><span>,</span><span> _referringValues</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"> @notice</span><span class="z-comment"> Get the referred list of an rNFT</span></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 considered rNFT, _address The corresponding 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"> The</span><span class="z-comment"> referred mapping of an rNFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> referredOf</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"> 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-storage z-type"> virtual</span><span class="z-storage z-type"> override</span><span>(</span><span class="z-entity z-name">IERC_5521</span><span>,</span><span class="z-entity z-name"> TargetContract</span><span>)</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 class="z-support"> uint256</span><span>[</span><span>]</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> _referredKeys</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> _referredValues</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_address </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></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;ERC_5521: token ID not existed&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> (</span><span>_referredKeys</span><span>,</span><span> _referredValues</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> convertMap</span><span>(</span><span>tokenId</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> TargetContract targetContractInstance </span><span class="z-keyword">=</span><span class="z-entity z-name"> TargetContract</span><span>(</span><span>_address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>targetContractInstance</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span class="z-variable z-language">type</span><span>(</span><span>TargetContract</span><span>)</span><span>.</span><span>interfaceId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC_5521: target contract not supported&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> (</span><span>_referredKeys</span><span>,</span><span> _referredValues</span><span>)</span><span class="z-keyword"> =</span><span> targetContractInstance</span><span>.</span><span class="z-entity z-name">referredOf</span><span>(</span><span>_address</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 class="z-keyword"> return</span><span> (</span><span>_referredKeys</span><span>,</span><span> _referredValues</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"> @notice</span><span class="z-comment"> Get the timestamp of an rNFT when is being created.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-comment"> `tokenId` of the rNFT being focused, `_address` of contract address associated with the focused rNFT.</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"> timestamp of the rNFT when is being created with uint256 format.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createdTimestampOf</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"> 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-support"> uint256</span><span class="z-storage z-type"> memory</span><span> createdTimestamp</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_address </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></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;ERC_5521: token ID not existed&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> Relationship </span><span class="z-storage z-type">storage</span><span> relationship </span><span class="z-keyword">=</span><span> _relationship</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> createdTimestamp </span><span class="z-keyword">=</span><span> relationship</span><span>.</span><span>createdTimestamp</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span> TargetContract targetContractInstance </span><span class="z-keyword">=</span><span class="z-entity z-name"> TargetContract</span><span>(</span><span>_address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>targetContractInstance</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span class="z-variable z-language">type</span><span>(</span><span>TargetContract</span><span>)</span><span>.</span><span>interfaceId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC_5521: target contract not supported&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> createdTimestamp </span><span class="z-keyword">=</span><span> targetContractInstance</span><span>.</span><span class="z-entity z-name">createdTimestampOf</span><span>(</span><span>_address</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 class="z-keyword"> return</span><span> createdTimestamp</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"> See {IERC165-supportsInterface}.</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"> 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"> IERC_5521</span><span>,</span><span class="z-entity z-name"> TargetContract</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> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC_5521</span><span>)</span><span>.</span><span>interfaceId</span></span> <span class="giallo-l"><span class="z-keyword"> ||</span><span> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>TargetContract</span><span>)</span><span>.</span><span>interfaceId</span></span> <span class="giallo-l"><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></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"> @notice Emit an event of UpdateNode</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> emitEvents</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"> sender</span><span>)</span><span class="z-storage z-type"> private</span><span> {</span></span> <span class="giallo-l"><span> (</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> _referringKeys</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> _referringValues</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> convertMap</span><span>(</span><span>tokenId</span><span>,</span><span class="z-constant"> true</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> (</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> _referredKeys</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> _referredValues</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> convertMap</span><span>(</span><span>tokenId</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 class="z-keyword"> emit</span><span class="z-entity z-name"> UpdateNode</span><span>(</span><span>tokenId</span><span>,</span><span> sender</span><span>,</span><span> _referringKeys</span><span>,</span><span> _referringValues</span><span>,</span><span> _referredKeys</span><span>,</span><span> _referredValues</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"> @notice Convert a specific `local` token mapping to a key array and a value array</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> convertMap</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> isReferring</span><span>)</span><span class="z-storage z-type"> private</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 class="z-support"> uint256</span><span>[</span><span>]</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> Relationship </span><span class="z-storage z-type">storage</span><span> relationship </span><span class="z-keyword">=</span><span> _relationship</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> returnKeys</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> returnValues</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>isReferring</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> returnKeys </span><span class="z-keyword">=</span><span> relationship</span><span>.</span><span>referringKeys</span><span>;</span></span> <span class="giallo-l"><span> returnValues </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span>[</span><span>]</span><span>(</span><span>returnKeys</span><span>.</span><span>length</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> returnKeys</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> returnValues</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span> relationship</span><span>.</span><span>referring</span><span>[</span><span>returnKeys</span><span>[</span><span>i</span><span>]</span><span>]</span><span>;</span></span> <span class="giallo-l"><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> returnKeys </span><span class="z-keyword">=</span><span> relationship</span><span>.</span><span>referredKeys</span><span>;</span></span> <span class="giallo-l"><span> returnValues </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span>[</span><span>]</span><span>(</span><span>returnKeys</span><span>.</span><span>length</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> returnKeys</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> returnValues</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span> relationship</span><span>.</span><span>referred</span><span>[</span><span>returnKeys</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> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>returnKeys</span><span>,</span><span> returnValues</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> <h3 id="timestamp">Timestamp</h3> <p>The <code>createdTimestamp</code> only covers the block-level timestamp (based on block headers), which does not support fine-grained comparisons such as transaction-level.</p> <h3 id="ownership-and-reference">Ownership and Reference</h3> <p>The change of ownership has nothing to do with the reference relationship. Normally, the distribution of profits complies with the agreement when the NFT was being created regardless of the change of ownership unless specified in the agreement.</p> <p>Referring a token will not refer to its descendants by default. In the case that only a specific child token gets referred, it means the privity of the contract will involve nobody other than the owner of this specific child token. Alternatively, a chain-of-reference all the way from the root token to a specific very bottom child token (from root to leaf) can be constructed and recorded in the <code>referring</code> to explicitly define the distribution of profits.</p> <h3 id="open-minting-and-relationship-risks">Open Minting and Relationship Risks</h3> <p>The <code>safeMint</code> function has been deliberately designed to allow unrestricted minting and relationship setting, akin to the open referencing system seen in platforms such as Google Scholar. This decision facilitates strong flexibility, enabling any user to create and define relationships between NFTs without centralized control. While this design aligns with the intended openness of the system, it inherently carries certain risks. Unauthorized or incorrect references can be created, mirroring the challenges faced in traditional scholarly referencing, where erroneous citations may occur. Additionally, the open nature may expose the system to potential abuse by malicious actors, who might manipulate relationships or inflate the token supply. It is important to recognize that these risks are not considered design flaws but intentional trade-offs, which balance the system's flexibility against potential reliability concerns.</p> <p>Stakeholders should be aware that the on-chain data integrity guarantees extend only to what has been recorded on the blockchain and do not preclude the possibility of off-chain errors or manipulations. Thus, users and integrators should exercise caution and judgment in interpreting and using the relationships and other data provided by this system.</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-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 Samuele Marrohttps://github.com/samuelemarro Luca Donnohttps://github.com/lucadonnoh https://wg-eips.ritovision.com/5375/

An extension of EIP-721 for NFT authorship and author consent.

<h2 id="abstract">Abstract</h2> <p>This EIP standardizes a JSON format for storing off-chain information about NFT authors. Specifically, it adds a new field which provides a list of author names, addresses, and proofs of <em>authorship consent</em>: proofs that the authors have agreed to be named as authors. Note that a proof of authorship <em>consent</em> is not a proof of authorship: an address can consent without having authored the NFT.</p> <h2 id="motivation">Motivation</h2> <p>There is currently no standard to identify authors of an NFT, and existing techniques have issues:</p> <ul> <li>Using the mint <code>tx.origin</code> or <code>msg.sender</code> <ul> <li>Assumes that the minter and the author are the same</li> <li>Does not support multiple authors</li> </ul> </li> <li>Using the first Transfer event for a given ID <ul> <li>Contract/minter can claim that someone else is the author without their consent</li> <li>Does not support multiple authors</li> </ul> </li> <li>Using a custom method/custom JSON field <ul> <li>Requires per-contract support by NFT platforms</li> <li>Contract/minter can claim that someone else is the author without their consent</li> </ul> </li> </ul> <p>The first practice is the most common. However, there are several situations where the minter and the author might not be the same, such as:</p> <ul> <li>NFTs minted by a contract</li> <li>Lazy minting</li> <li>NFTs minted by an intermediary (which can be particularly useful when the author is not tech-savvy and/or the minting process is convoluted)</li> </ul> <p>This document thus defines a standard which allows the minter to provide authorship information, while also preventing authorship claims without the author's consent.</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>All addresses used in this standard MUST follow the casing rules described in <a href="https://wg-eips.ritovision.com/55/">EIP-55</a>.</p> <h3 id="definitions">Definitions</h3> <ul> <li><strong>Authors</strong>: creators of an NFT</li> <li><strong>Minter</strong>: entity responsible for the actual minting transaction; the minter and the authors MAY be the same</li> <li><strong>Verifier</strong>: entity that wants to verify the authorship of an NFT (e.g. a user or an NFT marketplace)</li> <li><strong>Author Consent Proof (ACP)</strong>: a signed message that proves that the signer agrees to be considered the author of the NFT</li> </ul> <h3 id="authorship-support">Authorship Support</h3> <p>The standard introduces a new JSON field, named <code>authorInfo</code>. It provides a REQUIRED interface for authorship claiming, as well as an OPTIONAL interface for author consent proofs.</p> <p><code>authorInfo</code> is a top-level field of the NFT metadata. Specifically:</p> <ul> <li>If a contract supports the metadata extension for <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>, the JSON document pointed by <code>tokenURI(uint256 _tokenId)</code> MUST include the top-level field <code>authorInfo</code></li> <li>If a contract supports the metadata extension for <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>, the JSON document pointed by <code>uri(uint256 _id)</code> MUST include a top-level field <code>authorInfo</code></li> </ul> <p>The JSON schema of <code>authorInfo</code> (named <code>ERC5375AuthorInfoSchema</code>) is defined as follows:</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">consentInfo</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">Helper fields for consent verification</span><span class="z-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">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">EIP-155 chain 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 class="z-support"> &quot;</span><span class="z-support">id</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">NFT 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 class="z-support"> &quot;</span><span class="z-support">contractAddress</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">0x-prefixed address of the smart 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> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">authors</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC5375AuthorSchema</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">authors</span><span class="z-punctuation z-definition z-string">&quot;</span><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Note that <code>authors</code> MAY be an empty array.</p> <p><code>ERC5375AuthorSchema</code> is defined as follows:</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">address</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">0x-prefixed address of the author</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">consent</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">ERC5375AuthorConsentSchema</span><span class="z-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">Author consent information</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">address</span><span class="z-punctuation z-definition z-string">&quot;</span><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Moreover, if the <code>consent</code> field is present, the <code>consentInfo</code> field of <code>authorInfo</code> MUST be present.</p> <p><code>ERC5375AuthorConsentSchema</code> is defined as follows:</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">consentData</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">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">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">NFT authorship consent schema 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">issuer</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">0x-prefixed address of the author</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">metadataFields</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 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">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">issuer</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">metadataFields</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">publicKey</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">EVM public key of the author</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">EIP-712 signature of the consent message</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">consentData</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">publicKey</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">signature</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>where <code>metadataFields</code> is an object containing the JSON top-level fields (excluding <code>authorInfo</code>) that the author will certify. Note that the keys of <code>metadataFields</code> MAY be a (potentially empty) subset of the set of fields.</p> <p><code>consentData</code> MAY support additional fields as defined by other EIPs. <code>consentData</code> MUST contain all the information (which is not already present in other fields) required to verify the validity of an authorship consent proof.</p> <h3 id="author-consent">Author Consent</h3> <p>Consent is obtained by signing an <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> compatible message. Specifically, the structure is defined as follows:</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"> Author</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> tokenId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> metadata</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>where <code>subject</code> is the address of the NFT contract, <code>tokenId</code> is the id of the NFT and <code>metadata</code> is the JSON encoding of the fields listed in <code>metadataFields</code>. <code>metadata</code>:</p> <ul> <li>MUST contain exactly the same fields as the ones listed in <code>metadataFields</code>, in the same order</li> <li>MUST escape all non-ASCII characters. If the escaped character contains hexadecimal letters, they MUST be uppercase</li> <li>MUST not contain any whitespace that is not part of a field name or value</li> </ul> <p>For example, if the top-level JSON fields are:</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">The Holy Hand Grenade of Antioch</span><span class="z-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">Throw in the general direction of your favorite rabbit, et voilà</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">damage</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 500</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">authors</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-invalid z-illegal">.</span><span class="z-invalid z-illegal">.</span><span class="z-invalid z-illegal">.</span><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">.</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>and the content of <code>metadataFields</code> is <code>["name", "description"]</code>, the content of <code>metadata</code> is:</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">The Holy Hand Grenade of Antioch</span><span class="z-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">Throw in the general direction of your favorite rabbit, et voil</span><span class="z-constant">\u00E0</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Similarly to <code>consentData</code>, this structure MAY support additional fields as defined by other EIPs.</p> <p>The domain separator structure is</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"> 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>}</span></span></code></pre> <p>where <code>name</code> and <code>version</code> are the same fields described in <code>consentData</code></p> <p>This structure MAY support additional fields as defined by other EIPs.</p> <h3 id="author-consent-verification">Author Consent Verification</h3> <p>Verification is performed using EIP-712 on an author-by-author basis. Specifically, given a JSON document D1, a consent proof is valid if all of the following statements are true:</p> <ul> <li>D1 has a top-level <code>authorInfo</code> field that matches <code>ERC5375AuthorInfoSchema</code></li> <li><code>consent</code> exists and matches <code>ERC5375AuthorConsentSchema</code>;</li> <li>If calling <code>tokenURI</code> (for EIP-721) or <code>uri</code> (for EIP-1155) returns the URI of a JSON document D2, all the top-level fields listed in <code>metadataFields</code> MUST exist and have the same value;</li> <li>The EIP-712 signature in <code>signature</code> (computed using the fields specified in the JSON document) is valid;</li> </ul> <p>Verifiers MUST NOT assume that an NFT with a valid consent proof from address X means that X is the actual author. On the other hand, verifiers MAY assume that if an NFT does not provide a valid consent proof for address X, then X is not the actual author.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-provide-only-an-author-consent-proof">Why provide only an author consent proof?</h3> <p>Adding support for full authorship proofs (i.e. Alice is the author and no one else is the author) requires a protocol to prove that someone is the only author of an NFT. In other words, we need to answer the question: "Given an NFT Y and a user X claiming to be the author, is X the original author of Y?".</p> <p>For the sake of the argument, assume that there exists a protocol that, given an NFT Y, can determine the original author of Y. Even if such method existed, an attacker could slightly modify Y, thus obtaining a new NFT Y', and rightfully claim to be the author of Y', despite the fact that it is not an original work. Real-world examples include changing some pixels of an image or replacing some words of a text with synonyms. Preventing this behavior would require a general formal definition of when two NFTs are semantically equivalent. Even if defining such a concept were possible, it would still be beyond the scope of this EIP.</p> <p>Note that this issue is also present when using the minter's address as a proxy for the author.</p> <h3 id="why-off-chain">Why off-chain?</h3> <p>There are three reasons:</p> <ul> <li>Adding off-chain support does not require modifications to existing smart contracts;</li> <li>Off-chain storage is usually much cheaper than on-chain storage, thus reducing the implementation barrier;</li> <li>While there may be some use cases for full on-chain authorship proofs (e.g. a marketplace providing special features for authors), there are limited applications for on-chain author consent, due to the fact that it is mostly used by users to determine the subjective value of an NFT.</li> </ul> <h3 id="why-repeat-id-chainid-and-contractaddress">Why repeat id, chainId and contractAddress?</h3> <p>In many cases, this data can be derived from contextual information. However, requiring their inclusion in the JSON document ensures that author consent can be verified using only the JSON document.</p> <h3 id="why-not-implement-a-revocation-system">Why not implement a revocation system?</h3> <p>Authorship is usually final: either someone created an NFT or they didn't. Moreover, a revocation system would impose additional implementation requirements on smart contracts and increase the complexity of verification. Smart contracts MAY implement a revocation system, such as the one defined in other EIPs.</p> <h4 id="why-escape-non-ascii-characters-in-the-signature-message">Why escape non-ASCII characters in the signature message?</h4> <p>EIP-712 is designed with the possibility of on-chain verification in mind; while on-chain verification is not a priority for this EIP, non-ASCII characters are escaped due to the high complexity of dealing with non-ASCII strings in smart contracts.</p> <h3 id="usability-improvements-for-authors">Usability Improvements for Authors</h3> <p>Since the author only needs to sign an EIP-712 message, this protocol allows minters to handle the technical aspects of minting while still preserving the secrecy of the author's wallet. Specifically, the author only needs to:</p> <ul> <li>Obtain an EVM wallet;</li> <li>Learn how to read and sign a EIP-712 message (which can often be simplified by using a Dapp)</li> </ul> <p>without needing to:</p> <ul> <li>Obtain the chain's native token (e.g. through trading or bridging);</li> <li>Sign a transaction;</li> <li>Understand the pricing mechanism of transactions;</li> <li>Verify if a transaction has been included in a block</li> </ul> <p>This reduces the technical barrier for authors, thus increasing the usability of NFTs, without requiring authors to hand over their keys to a tech-savvy intermediary.</p> <h3 id="limitations-of-address-based-consent">Limitations of Address-Based Consent</h3> <p>The standard defines a protocol to verify that a certain <em>address</em> provided consent. However, it does not guarantee that the address corresponds to the expected author (such as the one provided in the <code>name</code> field). Proving a link between an address and the entity behind it is beyond the scope of this document.</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="attacks">Attacks</h3> <p>A potential attack that exploits this EIP involves tricking authors into signing authorship consent messages against their wishes. For this reason, authors MUST verify that all signature fields match the required ones.</p> <p>A more subtle approach involves not adding important fields to <code>metadataFields</code>. By doing so, the author signature might be valid even if the minter changes critical information.</p> <h3 id="deprecated-features">Deprecated Features</h3> <p><code>ERC5375AuthorInfoSchema</code> also originally included a field to specify a human-readable name for the author (without any kind of verification). This was scrapped due to the high risk of author spoofing, i.e.:</p> <ul> <li>Alice mints an NFT using Bob's name and Alice's address</li> <li>Charlie does not check the address and instead relies on the provided name</li> <li>Charlie buys Alice's NFT while believing that it was created by Bob</li> </ul> <p>For this reason, smart contract developers SHOULD NOT add support for unverifiable information to the JSON document. We believe that the most secure way to provide complex authorship information (e.g. the name of the author) is to prove that the information is associated with the <em>author's address</em>, instead of with the NFT itself.</p> <h3 id="replay-attack-resistance">Replay Attack Resistance</h3> <p>The chain id, the contract address and the token id uniquely identify an NFT; for this reason, there is no need to implement additional replay attack countermeasures (e.g. a nonce system).</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-30T00:00:00+00:00 2026-02-11T14:48:26+00:00 Jeremy Zhttps://github.com/wnft https://wg-eips.ritovision.com/5496/

Create shareable multi-privilege NFTs for EIP-721

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

An interface for identifying ownership of contracts

<h2 id="abstract">Abstract</h2> <p>This specification defines the minimum interface required to identify an account that controls a contract.</p> <h2 id="motivation">Motivation</h2> <p>This is a slimmed-down alternative to <a href="https://wg-eips.ritovision.com/173/">EIP-173</a>.</p> <h2 id="specification">Specification</h2> <p>The key word “MUST” in this document is to be interpreted as described in RFC 2119.</p> <p>Every contract compliant with this EIP MUST implement the <code>EIP5313</code> 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: 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.15</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-5313 Light Contract Ownership Standard</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> EIP5313</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 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"> 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></span></code></pre><h2 id="rationale">Rationale</h2> <p>Key factors influencing the standard:</p> <ul> <li>Minimize the number of functions in the interface</li> <li>Backwards compatibility with existing contracts</li> </ul> <p>This standard can be (and has been) extended by other standards to add additional ownership functionality. The smaller scope of this specification allows more and more straightforward ownership implementations, see limitations explained in EIP-173 under "other schemes that were considered".</p> <p>Implementing <a href="https://wg-eips.ritovision.com/165/">EIP-165</a> could be a valuable addition to this interface specification. However, this EIP is being written to codify existing protocols that connect contracts (often NFTs), with third-party websites (often a well-known NFT marketplace).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Every contract that implements EIP-173 already implements this specification.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Because this specification does not extend EIP-165, calling this EIP's <code>owner</code> function cannot result in complete certainty that the result is indeed the owner. For example, another function with the same function signature may return some value that is then interpreted to be the true owner. If this EIP is used solely to identify if an account is the owner of a contract, then the impact of this risk is minimized. But if the interrogator is, for example, sending a valuable NFT to the identified owner of any contract on the network, then the risk is heightened.</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-16T00:00:00+00:00 2026-02-11T14:48:25+00:00 Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/5289/

Allows Smart Contracts to be Legally Binding Off-Chain

<h2 id="abstract">Abstract</h2> <p>Currently, the real-world applications of smart contracts are limited by the fact that they aren't legally binding. This EIP proposes a standard that allows smart contracts to be legally binding by providing IPFS links to legal documents and ensuring that the users of the smart contract have privity with the relevant legal documents.</p> <p>Please note that the authors are not lawyers, and that this EIP is not legal advice.</p> <h2 id="motivation">Motivation</h2> <p>NFTs have oftentimes been branded as a way to hold and prove copyright of a specific work. However, this, in practice, has almost never been the case. Most of the time, NFTs have no legally-binding meaning, and in the rare cases that do, the NFT simply provides a limited license for the initial holder to use the work (but cannot provide any license for any future holders).</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="legal-contract-library-interface">Legal Contract Library Interface</h3> <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-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"> IERC5289Library</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"> @notice</span><span class="z-comment"> Emitted when signDocument is called</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DocumentSigned</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> signer</span><span>, </span><span class="z-support">uint16</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> documentId</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"> An immutable link to the legal document (RECOMMENDED to be hosted on IPFS). This MUST use a common file format, such as PDF, HTML, TeX, or Markdown.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> legalDocument</span><span>(</span><span class="z-support">uint16</span><span class="z-variable"> documentId</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 class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns whether or not the given user signed the document.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> documentSigned</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>,</span><span class="z-support"> uint16</span><span class="z-variable"> documentId</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"> signed</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 when the given user signed the document.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> If the user has not signed the document, the timestamp may be anything.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> documentSignedAt</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>,</span><span class="z-support"> uint16</span><span class="z-variable"> documentId</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 class="z-variable"> timestamp</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"> Sign a document</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This MUST be validated by the smart contract. This MUST emit DocumentSigned or throw.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> signDocument</span><span>(</span><span class="z-support">address</span><span class="z-variable"> signer</span><span>,</span><span class="z-support"> uint16</span><span class="z-variable"> documentId</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="requesting-a-signature">Requesting a Signature</h3> <p>To request that certain documents be signed, revert with an <a href="https://wg-eips.ritovision.com/5568/">ERC-5568</a> signal. The format of the <code>instruction_data</code> is an ABI-encoded <code>(address, uint16)</code> pair, where the address is the address of the library, and the <code>uint16</code> is the <code>documentId</code> of the document:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">throw</span><span class="z-entity z-name"> WalletSignal24</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 5289</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-constant">0xcbd99eb81b2d8ca256bb6a5b0ef7db86489778a7</span><span>,</span><span class="z-constant"> 12345</span><span>)</span><span>)</span><span>;</span></span></code></pre><h3 id="signing-a-document">Signing a Document</h3> <p>When a signature is requested, wallets MUST call <code>legalDocument</code>, display the resulting document to the user, and prompt them to either sign the document or cancel:</p> <p><img src="https://wg-eips.ritovision.com/5289/./assets/example-popup.png" alt="image" /></p> <p>If the user agrees, the wallet MUST call <code>signDocument</code>.</p> <h2 id="rationale">Rationale</h2> <ul> <li><code>uint64</code> was chosen for the timestamp return type as 64-bit time registers are standard.</li> <li><code>uint16</code> was chosen for the document ID as 65536 documents are likely sufficient for any use case, and the contract can always be re-deployed.</li> <li><code>signDocument</code> doesn't take an ECDSA signature for future compatibility with account abstraction. In addition, future extensions can supply this functionality.</li> <li>IPFS is mandatory because the authenticity of the signed document can be proven.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backwards compatibility issues found.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="legal-contract-library">Legal Contract Library</h3> <p>See <a href="https://wg-eips.ritovision.com/5289/./assets/interfaces/IERC5289Library.sol"><code>IERC5289Library</code></a>, <a href="https://wg-eips.ritovision.com/5289/./assets/ERC5289Library.sol"><code>ERC5289Library</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Users can claim that their private key was stolen and used to fraudulently "sign" contracts. As such, <strong>documents must only be permissive in nature, not restrictive.</strong> For example, a document granting a license to use the image attached to an NFT would be acceptable, as there is no reason for the signer to plausibly deny signing the document.</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-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv https://wg-eips.ritovision.com/5269/

An interface to identify if major behavior or optional behavior specified in an ERC is supported for a given caller.

<h2 id="abstract">Abstract</h2> <p>An interface for better identification and detection of ERC by numbers. It designates a field in which it's called <code>majorERCIdentifier</code> which is normally known or referred to as "ERC number". For example, <code>ERC-721</code> aka <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> has a <code>majorERCIdentifier = 721</code>. This ERC has a <code>majorERCIdentifier = 5269</code>.</p> <p>Calling it a <code>majorERCIdentifier</code> instead of <code>ERCNumber</code> makes it future-proof: anticipating there is a possibility where future ERC is not numbered or if we want to incorporate other types of standards.</p> <p>It also proposes a new concept of <code>minorERCIdentifier</code> which is left for authors of individual ERC to define. For example, ERC-721's author may define <code>ERC721Metadata</code> interface as <code>minorERCIdentifier= keccak256("ERC721Metadata")</code>.</p> <p>It also proposes an event to allow smart contracts to optionally declare the ERCs they support.</p> <h2 id="motivation">Motivation</h2> <p>This ERC is created as a competing standard for <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>.</p> <p>Here are the major differences between this ERC and <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>.</p> <ol> <li><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> uses the hash of a method's signature which declares the existence of one method or multiple methods, therefore it requires at least one method to <em>exist</em> in the first place. In some cases, some ERCs interface does not have a method, such as some ERCs related to data format and signature schemes or the "Soul-Bound-ness" aka SBT which could just revert a transfer call without needing any specific method.</li> <li><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> doesn't provide query ability based on the caller. The compliant contract of this ERC will respond to whether it supports certain ERC <em>based on</em> a given caller.</li> </ol> <p>Here is the motivation for this ERC given ERC-165 already exists:</p> <ol> <li> <p>Using ERC numbers improves human readability as well as make it easier to work with named contract such as ENS.</p> </li> <li> <p>Instead of using an ERC-165 identifier, we have seen an increasing interest to use ERC numbers as the way to identify or specify an ERC. For example</p> </li> </ol> <ul> <li><a href="https://wg-eips.ritovision.com/5267/">ERC-5267</a> specifies <code>extensions</code> to be a list of ERC numbers.</li> <li><a href="https://wg-eips.ritovision.com/600/">ERC-600</a>, and <a href="https://wg-eips.ritovision.com/601/">ERC-601</a> specify an <code>ERC</code> number in the <code>m / purpose' / subpurpose' / ERC' / wallet'</code> path.</li> <li><a href="https://wg-eips.ritovision.com/5568/">ERC-5568</a> specifies <code>The instruction_id of an instruction defined by an ERC MUST be its ERC number unless there are exceptional circumstances (be reasonable)</code></li> <li><a href="https://wg-eips.ritovision.com/6120/">ERC-6120</a> specifies <code>struct Token { uint eip; ..., }</code> where <code>uint eip</code> is an ERC number to identify ERCs.</li> <li><code>ERC-867</code>(Stagnant) proposes to create <code>erpId: A string identifier for this ERP (likely the associated ERC number, e.g. “ERC-1234”).</code></li> </ul> <ol start="3"> <li> <p>Having an ERC/ERC number detection interface reduces the need for a lookup table in smart contract to convert a function method or whole interface in any ERC in the bytes4 ERC-165 identifier into its respective ERC number and massively simplifies the way to specify ERC for behavior expansion.</p> </li> <li> <p>We also recognize a smart contract might have different behavior given different caller accounts. One of the most notable use cases is that when using Transparent Upgradable Pattern, a proxy contract gives an Admin account and Non-Admin account different treatment when they call.</p> </li> </ol> <h2 id="specification">Specification</h2> <p>In the following description, we use ERC and ERC inter-exchangeably. This was because while most of the time the description applies to an ERC category of the Standards Track of ERC, the ERC number space is a subspace of ERC number space and we might sometimes encounter ERCs that aren't recognized as ERCs but has behavior that's worthy of a query.</p> <ol> <li>Any compliant smart contract MUST implement the following interface</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> DRAFTv1</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-storage z-type">interface</span><span class="z-entity z-name"> IERC5269</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> OnSupportERC</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"> caller</span><span>, </span><span>// </span><span class="z-variable">when</span><span class="z-variable"> emitted</span><span class="z-variable"> with</span><span> `</span><span class="z-support">address</span><span>(</span><span class="z-variable">0x0</span><span>)</span><span>` means all callers</span><span>.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> indexed</span><span> majorERCIdentifier</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> indexed</span><span> minorERCIdentifier</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> 0 means the entire ERC</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> ercStatus</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> 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-storage z-type"> @dev</span><span class="z-comment"> The core method of ERC Interface Detection</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> caller</span><span class="z-comment">, a `address` value of the address of a caller being queried whether the given ERC is supported.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> majorERCIdentifier</span><span class="z-comment">, a `uint256` value and SHOULD BE the ERC number being queried. Unless superseded by future ERC, such ERC number SHOULD BE less or equal to (0, 2^32-1]. For a function call to `supportERC`, any value outside of this range is deemed unspecified and open to implementation&#39;s choice or for future ERCs to specify.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> minorERCIdentifier</span><span class="z-comment">, a `bytes32` value reserved for authors of individual ERC to specify. For example the author of [ERC-721](/ERCS/eip-721) MAY specify `keccak256(&quot;ERC721Metadata&quot;)` or `keccak256(&quot;ERC721Metadata.tokenURI&quot;)` as `minorERCIdentifier` to be quired for support. Author could also use this minorERCIdentifier to specify different versions, such as ERC-712 has its V1-V4 with different behavior.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> extraData</span><span class="z-comment">, a `bytes` for [ERC-5750](/ERCS/eip-5750) for future extensions.</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"> ercStatus</span><span class="z-comment">, a `bytes32` indicating the status of ERC the contract supports.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - For FINAL ERCs, it MUST return `keccak256(&quot;FINAL&quot;)`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> - For non-FINAL ERCs, it SHOULD return `keccak256(&quot;DRAFT&quot;)`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> During ERC procedure, ERC authors are allowed to specify their own</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ercStatus other than `FINAL` or `DRAFT` at their discretion such as `keccak256(&quot;DRAFTv1&quot;)`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> or `keccak256(&quot;DRAFT-option1&quot;)`and such value of ercStatus MUST be documented in the ERC body</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportERC</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> caller</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> majorERCIdentifier</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> minorERCIdentifier</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"> extraData</span><span>)</span></span> <span class="giallo-l"><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 class="z-variable"> ercStatus</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>In the following description, <code>ERC_5269_STATUS</code> is set to be <code>keccak256("DRAFTv1")</code>.</p> <p>In addition to the behavior specified in the comments of <code>IERC5269</code>:</p> <ol> <li>Any <code>minorERCIdentifier=0</code> is reserved to be referring to the main behavior of the ERC being queried.</li> <li>The Author of compliant ERC is RECOMMENDED to declare a list of <code>minorERCIdentifier</code> for their optional interfaces, behaviors and value range for future extension.</li> <li>When this ERC is FINAL, any compliant contract MUST return an <code>ERC_5269_STATUS</code> for the call of <code>supportERC((any caller), 5269, 0, [])</code></li> </ol> <p><em>Note</em>: at the current snapshot, the <code>supportERC((any caller), 5269, 0, [])</code> MUST return <code>ERC_5269_STATUS</code>.</p> <ol start="4"> <li>Any complying contract SHOULD emit an <code>OnSupportERC(address(0), 5269, 0, ERC_5269_STATUS, [])</code> event upon construction or upgrade.</li> <li>Any complying contract MAY declare for easy discovery any ERC main behavior or sub-behaviors by emitting an event of <code>OnSupportERC</code> with relevant values and when the compliant contract changes whether the support an ERC or certain behavior for a certain caller or all callers.</li> <li>For any <code>ERC-XXX</code> that is NOT in <code>Final</code> status, when querying the <code>supportERC((any caller), xxx, (any minor identifier), [])</code>, it MUST NOT return <code>keccak256("FINAL")</code>. It is RECOMMENDED to return <code>0</code> in this case but other values of <code>ercStatus</code> is allowed. Caller MUST treat any returned value other than <code>keccak256("FINAL")</code> as non-final, and MUST treat 0 as strictly "not supported".</li> <li>The function <code>supportERC</code> MUST be mutability <code>view</code>, i.e. it MUST NOT mutate any global state of EVM.</li> </ol> <h2 id="rationale">Rationale</h2> <ol> <li>When data type <code>uint256 majorERCIdentifier</code>, there are other alternative options such as:</li> </ol> <ul> <li>(1) using a hashed version of the ERC number,</li> <li>(2) use a raw number, or</li> <li>(3) use an ERC-165 identifier.</li> </ul> <p>The pros for (1) are that it automatically supports any evolvement of future ERC numbering/naming conventions. But the cons are it's not backward readable: seeing a <code>hash(ERC-number)</code> one usually can't easily guess what their ERC number is.</p> <p>We choose the (2) in the rationale laid out in motivation.</p> <ol start="2"> <li> <p>We have a <code>bytes32 minorERCIdentifier</code> in our design decision. Alternatively, it could be (1) a number, forcing all ERC authors to define its numbering for sub-behaviors so we go with a <code>bytes32</code> and ask the ERC authors to use a hash for a string name for their sub-behaviors which they are already doing by coming up with interface name or method name in their specification.</p> </li> <li> <p>Alternatively, it's possible we add extra data as a return value or an array of all ERC being supported but we are unsure how much value this complexity brings and whether the extra overhead is justified.</p> </li> <li> <p>Compared to <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>, we also add an additional input of <code>address caller</code>, given the increasing popularity of proxy patterns such as those enabled by <a href="https://wg-eips.ritovision.com/1967/">ERC-1967</a>. One may ask: why not simply use <code>msg.sender</code>? This is because we want to allow query them without transaction or a proxy contract to query whether interface ERC-<code>number</code> will be available to that particular sender.</p> </li> <li> <p>We reserve the input <code>majorERCIdentifier</code> greater than or equals <code>2^32</code> in case we need to support other collections of standards which is not an ERC/ERC.</p> </li> </ol> <h2 id="test-cases">Test Cases</h2> <pre class="giallo z-code"><code data-lang="typescript"><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">ERC5269</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"> async</span><span class="z-storage z-type"> function</span><span class="z-entity z-name"> deployFixture</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"> ...</span></span> <span class="giallo-l"><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">Deployment</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> ...</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 emit proper OnSupportERC events</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> {</span><span class="z-variable z-other"> txDeployErc721</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> loadFixture</span><span>(</span><span class="z-variable z-other">deployFixture</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> events</span><span class="z-keyword"> =</span><span class="z-variable z-other"> txDeployErc721</span><span>.</span><span class="z-variable z-other">events</span><span>?.</span><span class="z-entity z-name">filter</span><span>(</span><span class="z-variable">event</span><span class="z-storage z-type"> =&gt;</span><span class="z-variable z-other"> event</span><span>.</span><span class="z-variable z-other">event</span><span class="z-keyword"> ===</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">OnSupportERC</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"> expect</span><span>(</span><span class="z-variable z-other">events</span><span>)</span><span>.</span><span class="z-variable z-other">to</span><span>.</span><span class="z-variable z-other">have</span><span>.</span><span class="z-entity z-name">lengthOf</span><span>(</span><span class="z-constant">4</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> ev5269</span><span class="z-keyword"> =</span><span class="z-variable z-other"> events</span><span class="z-keyword">!</span><span>.</span><span class="z-entity z-name">filter</span><span>(</span></span> <span class="giallo-l"><span> (</span><span class="z-variable">event</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span class="z-variable z-other"> event</span><span>.</span><span class="z-variable z-other">args</span><span class="z-keyword">!</span><span>.</span><span class="z-variable z-other">majorERCIdentifier</span><span>.</span><span class="z-entity z-name">eq</span><span>(</span><span class="z-constant">5269</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-variable z-other">ev5269</span><span>)</span><span>.</span><span class="z-variable z-other">to</span><span>.</span><span class="z-variable z-other">have</span><span>.</span><span class="z-entity z-name">lengthOf</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">ev5269</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span class="z-variable z-other">args</span><span class="z-keyword">!</span><span>.</span><span class="z-variable z-other">caller</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">BigNumber</span><span>.</span><span class="z-entity z-name">from</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"> expect</span><span>(</span><span class="z-variable z-other">ev5269</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span class="z-variable z-other">args</span><span class="z-keyword">!</span><span>.</span><span class="z-variable z-other">minorERCIdentifier</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">BigNumber</span><span>.</span><span class="z-entity z-name">from</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"> expect</span><span>(</span><span class="z-variable z-other">ev5269</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span class="z-variable z-other">args</span><span class="z-keyword">!</span><span>.</span><span class="z-variable z-other">ercStatus</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">ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">id</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">DRAFTv1</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-storage z-type"> let</span><span class="z-variable z-other"> ev721</span><span class="z-keyword"> =</span><span class="z-variable z-other"> events</span><span class="z-keyword">!</span><span>.</span><span class="z-entity z-name">filter</span><span>(</span></span> <span class="giallo-l"><span> (</span><span class="z-variable">event</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span class="z-variable z-other"> event</span><span>.</span><span class="z-variable z-other">args</span><span class="z-keyword">!</span><span>.</span><span class="z-variable z-other">majorERCIdentifier</span><span>.</span><span class="z-entity z-name">eq</span><span>(</span><span class="z-constant">721</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-variable z-other">ev721</span><span>)</span><span>.</span><span class="z-variable z-other">to</span><span>.</span><span class="z-variable z-other">have</span><span>.</span><span class="z-entity z-name">lengthOf</span><span>(</span><span class="z-constant">3</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">ev721</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span class="z-variable z-other">args</span><span class="z-keyword">!</span><span>.</span><span class="z-variable z-other">caller</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">BigNumber</span><span>.</span><span class="z-entity z-name">from</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"> expect</span><span>(</span><span class="z-variable z-other">ev721</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span class="z-variable z-other">args</span><span class="z-keyword">!</span><span>.</span><span class="z-variable z-other">minorERCIdentifier</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">BigNumber</span><span>.</span><span class="z-entity z-name">from</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"> expect</span><span>(</span><span class="z-variable z-other">ev721</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span class="z-variable z-other">args</span><span class="z-keyword">!</span><span>.</span><span class="z-variable z-other">ercStatus</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">ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">id</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">FINAL</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"> expect</span><span>(</span><span class="z-variable z-other">ev721</span><span>[</span><span class="z-constant">1</span><span>]</span><span>.</span><span class="z-variable z-other">args</span><span class="z-keyword">!</span><span>.</span><span class="z-variable z-other">caller</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">BigNumber</span><span>.</span><span class="z-entity z-name">from</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"> expect</span><span>(</span><span class="z-variable z-other">ev721</span><span>[</span><span class="z-constant">1</span><span>]</span><span>.</span><span class="z-variable z-other">args</span><span class="z-keyword">!</span><span>.</span><span class="z-variable z-other">minorERCIdentifier</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">ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">id</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ERC721Metadata</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-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">ev721</span><span>[</span><span class="z-constant">1</span><span>]</span><span>.</span><span class="z-variable z-other">args</span><span class="z-keyword">!</span><span>.</span><span class="z-variable z-other">ercStatus</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">ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">id</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">FINAL</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> ...</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 return proper ercStatus value when called supportERC() for declared supported ERC/features</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> {</span><span class="z-variable z-other"> erc721ForTesting</span><span>,</span><span class="z-variable z-other"> owner</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> loadFixture</span><span>(</span><span class="z-variable z-other">deployFixture</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"> erc721ForTesting</span><span>.</span><span class="z-entity z-name">supportERC</span><span>(</span><span class="z-variable z-other">owner</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-constant"> 5269</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">hexZeroPad</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-constant"> 32</span><span>)</span><span>,</span><span> [</span><span>]</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">ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">id</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">DRAFTv1</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-entity z-name"> expect</span><span>(</span><span class="z-keyword">await</span><span class="z-variable z-other"> erc721ForTesting</span><span>.</span><span class="z-entity z-name">supportERC</span><span>(</span><span class="z-variable z-other">owner</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-constant"> 721</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">hexZeroPad</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-constant"> 32</span><span>)</span><span>,</span><span> [</span><span>]</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">ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">id</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">FINAL</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-entity z-name"> expect</span><span>(</span><span class="z-keyword">await</span><span class="z-variable z-other"> erc721ForTesting</span><span>.</span><span class="z-entity z-name">supportERC</span><span>(</span><span class="z-variable z-other">owner</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-constant"> 721</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">id</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ERC721Metadata</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>,</span><span> [</span><span>]</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">ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">id</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">FINAL</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-comment"> //</span><span class="z-comment"> ...</span></span> <span class="giallo-l"></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"> erc721ForTesting</span><span>.</span><span class="z-entity z-name">supportERC</span><span>(</span><span class="z-variable z-other">owner</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-constant"> 721</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">id</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">WRONG FEATURE</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>,</span><span> [</span><span>]</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">BigNumber</span><span>.</span><span class="z-entity z-name">from</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"> expect</span><span>(</span><span class="z-keyword">await</span><span class="z-variable z-other"> erc721ForTesting</span><span>.</span><span class="z-entity z-name">supportERC</span><span>(</span><span class="z-variable z-other">owner</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-constant"> 9999</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">hexZeroPad</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-constant"> 32</span><span>)</span><span>,</span><span> [</span><span>]</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">BigNumber</span><span>.</span><span class="z-entity z-name">from</span><span>(</span><span class="z-constant">0</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 return zero as ercStatus value when called supportERC() for non declared ERC/features</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> {</span><span class="z-variable z-other"> erc721ForTesting</span><span>,</span><span class="z-variable z-other"> owner</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> loadFixture</span><span>(</span><span class="z-variable z-other">deployFixture</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"> erc721ForTesting</span><span>.</span><span class="z-entity z-name">supportERC</span><span>(</span><span class="z-variable z-other">owner</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-constant"> 721</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">id</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">WRONG FEATURE</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>,</span><span> [</span><span>]</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">BigNumber</span><span>.</span><span class="z-entity z-name">from</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"> expect</span><span>(</span><span class="z-keyword">await</span><span class="z-variable z-other"> erc721ForTesting</span><span>.</span><span class="z-entity z-name">supportERC</span><span>(</span><span class="z-variable z-other">owner</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-constant"> 9999</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">hexZeroPad</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-constant"> 32</span><span>)</span><span>,</span><span> [</span><span>]</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">BigNumber</span><span>.</span><span class="z-entity z-name">from</span><span>(</span><span class="z-constant">0</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> <p>See <a href="https://wg-eips.ritovision.com/5269/./assets/test/TestERC5269.ts"><code>TestERC5269.ts</code></a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Here is a reference implementation for this ERC:</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"> ERC5269</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC5269</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> ERC_STATUS </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;DRAFTv1&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span> (</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> OnSupportERC</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-constant">0x0</span><span>)</span><span>,</span><span class="z-constant"> 5269</span><span>,</span><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span> ERC_STATUS</span><span>,</span><span class="z-string"> &quot;&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"> _supportERC</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-comment"> /*</span><span class="z-comment">caller</span><span class="z-comment">*/</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> majorERCIdentifier</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> minorERCIdentifier</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-comment"> /*</span><span class="z-comment">extraData</span><span class="z-comment">*/</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> internal</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">bytes32</span><span class="z-variable"> ercStatus</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>majorERCIdentifier </span><span class="z-keyword">==</span><span class="z-constant"> 5269</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>minorERCIdentifier </span><span class="z-keyword">==</span><span class="z-support"> bytes32</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> ERC_STATUS</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-support"> bytes32</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"> supportERC</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> caller</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> majorERCIdentifier</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> minorERCIdentifier</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"> extraData</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</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">bytes32</span><span class="z-variable"> ercStatus</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> _supportERC</span><span>(</span><span>caller</span><span>,</span><span> majorERCIdentifier</span><span>,</span><span> minorERCIdentifier</span><span>,</span><span> extraData</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>See <a href="https://wg-eips.ritovision.com/5269/./assets/contracts/ERC5269.sol"><code>ERC5269.sol</code></a>.</p> <p>Here is an example where a contract of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> also implement this ERC to make it easier to detect and discover:</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/token/ERC721/ERC721.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;../ERC5269.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC721ForTesting</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">ERC5269</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> ERC_FINAL </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;FINAL&quot;</span><span>)</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"> ERC721</span><span>(</span><span>&quot;ERC721ForTesting&quot;, &quot;E721FT&quot;) </span><span class="z-entity z-name">ERC5269</span><span>(</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"> 0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> OnSupportERC</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-constant">0x0</span><span>)</span><span>,</span><span class="z-constant"> 721</span><span>,</span><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span> ERC_FINAL</span><span>,</span><span class="z-string"> &quot;&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> OnSupportERC</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-constant">0x0</span><span>)</span><span>,</span><span class="z-constant"> 721</span><span>,</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;ERC721Metadata&quot;</span><span>)</span><span>,</span><span> ERC_FINAL</span><span>,</span><span class="z-string"> &quot;&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> OnSupportERC</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-constant">0x0</span><span>)</span><span>,</span><span class="z-constant"> 721</span><span>,</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;ERC721Enumerable&quot;</span><span>)</span><span>,</span><span> ERC_FINAL</span><span>,</span><span class="z-string"> &quot;&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"> supportERC</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> caller</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> majorERCIdentifier</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> minorERCIdentifier</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"> extraData</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"> override</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"> ercStatus</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>majorERCIdentifier </span><span class="z-keyword">==</span><span class="z-constant"> 721</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>minorERCIdentifier </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"> keccak256</span><span>(</span><span class="z-string">&quot;FINAL&quot;</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>minorERCIdentifier </span><span class="z-keyword">==</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;ERC721Metadata&quot;</span><span>)</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-string">&quot;FINAL&quot;</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>minorERCIdentifier </span><span class="z-keyword">==</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;ERC721Enumerable&quot;</span><span>)</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-string">&quot;FINAL&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-keyword"> return</span><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">_supportERC</span><span>(</span><span>caller</span><span>,</span><span> majorERCIdentifier</span><span>,</span><span> minorERCIdentifier</span><span>,</span><span> extraData</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> <p>See <a href="https://wg-eips.ritovision.com/5269/./assets/contracts/testing/ERC721ForTesting.sol"><code>ERC721ForTesting.sol</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Similar to <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> callers of the interface MUST assume the smart contract declaring they support such ERC interfaces doesn't necessarily correctly support 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> 2022-07-14T00:00:00+00:00 2026-02-11T14:48:26+00:00 Francisco Giordanohttps://github.com/frangio https://wg-eips.ritovision.com/5267/

A way to describe and retrieve an EIP-712 domain to securely integrate EIP-712 signatures.

<h2 id="abstract">Abstract</h2> <p>This EIP complements <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> by standardizing how contracts should publish the fields and values that describe their domain. This enables applications to retrieve this description and generate appropriate domain separators in a general way, and thus integrate EIP-712 signatures securely and scalably.</p> <h2 id="motivation">Motivation</h2> <p>EIP-712 is a signature scheme for complex structured messages. In order to avoid replay attacks and mitigate phishing, the scheme includes a "domain separator" that makes the resulting signature unique to a specific domain (e.g., a specific contract) and allows user-agents to inform end users the details of what is being signed and how it may be used. A domain is defined by a data structure with fields from a predefined set, all of which are optional, or from extensions. Notably, EIP-712 does not specify any way for contracts to publish which of these fields they use or with what values. This has likely limited adoption of EIP-712, as it is not possible to develop general integrations, and instead applications find that they need to build custom support for each EIP-712 domain. A prime example of this is <a href="https://wg-eips.ritovision.com/2612/">EIP-2612</a> (permit), which has not been widely adopted by applications even though it is understood to be a valuable improvement to the user experience. The present EIP defines an interface that can be used by applications to retrieve a definition of the domain that a contract uses to verify EIP-712 signatures.</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>Compliant contracts MUST define <code>eip712Domain</code> exactly as declared below. All specified values MUST be returned even if they are not used, to ensure proper decoding on the client side.</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"> eip712Domain</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"> bytes1</span><span class="z-variable"> fields</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"> version</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> chainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> verifyingContract</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> extensions</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre> <p>The return values of this function MUST describe the domain separator that is used for verification of EIP-712 signatures in the contract. They describe both the form of the <code>EIP712Domain</code> struct (i.e., which of the optional fields and extensions are present) and the value of each field, as follows.</p> <ul> <li><code>fields</code>: A bit map where bit <code>i</code> is set to 1 if and only if domain field <code>i</code> is present (<code>0 ≤ i ≤ 4</code>). Bits are read from least significant to most significant, and fields are indexed in the order that is specified by EIP-712, identical to the order in which they are listed in the function type.</li> <li><code>name</code>, <code>version</code>, <code>chainId</code>, <code>verifyingContract</code>, <code>salt</code>: The value of the corresponding field in <code>EIP712Domain</code>, if present according to <code>fields</code>. If the field is not present, the value is unspecified. The semantics of each field is defined in EIP-712.</li> <li><code>extensions</code>: A list of EIP numbers, each of which MUST refer to an EIP that extends EIP-712 with new domain fields, along with a method to obtain the value for those fields, and potentially conditions for inclusion. The value of <code>fields</code> does not affect their inclusion.</li> </ul> <p>The return values of this function (equivalently, its EIP-712 domain) MAY change throughout the lifetime of a contract, but changes SHOULD NOT be frequent. The <code>chainId</code> field, if used, SHOULD change to mirror the <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> id of the underlying chain. Contracts MAY emit the event <code>EIP712DomainChanged</code> defined below to signal that the domain could have changed.</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"> EIP712DomainChanged</span><span>(</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>A notable application of EIP-712 signatures is found in EIP-2612 (permit), which specifies a <code>DOMAIN_SEPARATOR</code> function that returns a <code>bytes32</code> value (the actual domain separator, i.e., the result of <code>hashStruct(eip712Domain)</code>). This value does not suffice for the purposes of integrating with EIP-712, as the RPC methods defined there receive an object describing the domain and not just the separator in hash form. Note that this is not a flaw of the RPC methods, it is indeed part of the security proposition that the domain should be validated and informed to the user as part of the signing process. On its own, a hash does not allow this to be implemented, given it is opaque. The present EIP fills this gap in both EIP-712 and EIP-2612.</p> <p>Extensions are described by their EIP numbers because EIP-712 states: "Future extensions to this standard can add new fields [...] new fields should be proposed through the EIP process."</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is an optional extension to EIP-712 that does not introduce backwards compatibility issues.</p> <p>Upgradeable contracts that make use of EIP-712 signatures MAY be upgraded to implement this EIP.</p> <p>User-agents or applications that use this EIP SHOULD additionally support those contracts that due to their immutability cannot be upgraded to implement it. The simplest way to achieve this is to hardcode common domains based on contract address and chain id. However, it is also possible to implement a more general solution by guessing possible domains based on a few common patterns using the available information, and selecting the one whose hash matches a <code>DOMAIN_SEPARATOR</code> or <code>domainSeparator</code> function in the contract.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="solidity-example">Solidity 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"> 0.8.0</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"> EIP712VerifyingContract</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> eip712Domain</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"> bytes1</span><span class="z-variable"> fields</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"> name</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"> version</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> chainId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> verifyingContract</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> salt</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"> extensions</span></span> <span class="giallo-l"><span> )</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span></span> <span class="giallo-l"><span> hex</span><span class="z-string">&quot;0d&quot;</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> 01101</span></span> <span class="giallo-l"><span class="z-string"> &quot;Example&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-language"> block</span><span>.</span><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></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-keyword"> new</span><span class="z-support"> uint256</span><span>[](</span><span class="z-constant">0</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></code></pre> <p>This contract's domain only uses the fields <code>name</code>, <code>chainId</code>, and <code>verifyingContract</code>, therefore the <code>fields</code> value is <code>01101</code>, or <code>0d</code> in hexadecimal.</p> <p>Assuming this contract is on Ethereum mainnet and its address is 0x0000000000000000000000000000000000000001, the domain it describes is:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Example</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><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 class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><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">i</span><span class="z-invalid z-illegal">f</span><span class="z-invalid z-illegal">y</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">C</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">c</span><span class="z-invalid z-illegal">t</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 class="giallo-l"><span>}</span></span></code></pre><h3 id="javascript">JavaScript</h3> <p>A domain object can be constructed based on the return values of an <code>eip712Domain()</code> invocation.</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"> Retrieves the EIP-712 domain of a contract using EIP-5267 without extensions. </span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage">async</span><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getDomain</span><span>(</span><span class="z-variable">contract</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"> fields</span><span>,</span><span class="z-variable z-other z-constant"> name</span><span>,</span><span class="z-variable z-other z-constant"> version</span><span>,</span><span class="z-variable z-other z-constant"> chainId</span><span>,</span><span class="z-variable z-other z-constant"> verifyingContract</span><span>,</span><span class="z-variable z-other z-constant"> salt</span><span>,</span><span class="z-variable z-other z-constant"> extensions</span><span> }</span><span class="z-keyword"> =</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">eip712Domain</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-variable z-other">extensions</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"> throw</span><span class="z-entity z-name"> Error</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Extensions not implemented</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-keyword"> return</span><span class="z-entity z-name"> buildBasicDomain</span><span>(</span><span class="z-variable z-other">fields</span><span>,</span><span class="z-variable z-other"> name</span><span>,</span><span class="z-variable z-other"> version</span><span>,</span><span class="z-variable z-other"> chainId</span><span>,</span><span class="z-variable z-other"> verifyingContract</span><span>,</span><span class="z-variable z-other"> salt</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">const</span><span class="z-variable z-other z-constant"> fieldNames</span><span class="z-keyword"> =</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">version</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">chainId</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">verifyingContract</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">salt</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-punctuation z-definition z-comment">/**</span><span class="z-comment"> Builds a domain object without extensions based on the return values of `eip712Domain()`. </span><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"> buildBasicDomain</span><span>(</span><span class="z-variable">fields</span><span>,</span><span class="z-variable"> name</span><span>,</span><span class="z-variable"> version</span><span>,</span><span class="z-variable"> chainId</span><span>,</span><span class="z-variable"> verifyingContract</span><span>,</span><span class="z-variable"> salt</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"> domain</span><span class="z-keyword"> =</span><span> {</span><span class="z-variable z-other"> name</span><span>,</span><span class="z-variable z-other"> version</span><span>,</span><span class="z-variable z-other"> chainId</span><span>,</span><span class="z-variable z-other"> verifyingContract</span><span>,</span><span class="z-variable z-other"> salt</span><span> }</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">const</span><span> [</span><span class="z-variable z-other z-constant">i</span><span>,</span><span class="z-variable z-other z-constant"> field</span><span>]</span><span class="z-keyword"> of</span><span class="z-variable z-other"> fieldNames</span><span>.</span><span class="z-entity z-name">entries</span><span>(</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>(</span><span class="z-variable z-other">fields</span><span class="z-keyword"> &amp;</span><span> (</span><span class="z-constant">1</span><span class="z-keyword"> &lt;&lt;</span><span class="z-variable z-other"> i</span><span>)</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span class="z-variable z-other"> domain</span><span>[</span><span class="z-variable z-other">field</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-keyword"> return</span><span class="z-variable z-other"> domain</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="extensions">Extensions</h4> <p>Suppose EIP-XYZ defines a new field <code>subdomain</code> of type <code>bytes32</code> and a function <code>getSubdomain()</code> to retrieve its value.</p> <p>The function <code>getDomain</code> from above would be extended as follows.</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"> Retrieves the EIP-712 domain of a contract using EIP-5267 with support for EIP-XYZ. </span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage">async</span><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getDomain</span><span>(</span><span class="z-variable">contract</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"> fields</span><span>,</span><span class="z-variable z-other z-constant"> name</span><span>,</span><span class="z-variable z-other z-constant"> version</span><span>,</span><span class="z-variable z-other z-constant"> chainId</span><span>,</span><span class="z-variable z-other z-constant"> verifyingContract</span><span>,</span><span class="z-variable z-other z-constant"> salt</span><span>,</span><span class="z-variable z-other z-constant"> extensions</span><span> }</span><span class="z-keyword"> =</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">eip712Domain</span><span>(</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"> domain</span><span class="z-keyword"> =</span><span class="z-entity z-name"> buildBasicDomain</span><span>(</span><span class="z-variable z-other">fields</span><span>,</span><span class="z-variable z-other"> name</span><span>,</span><span class="z-variable z-other"> version</span><span>,</span><span class="z-variable z-other"> chainId</span><span>,</span><span class="z-variable z-other"> verifyingContract</span><span>,</span><span class="z-variable z-other"> salt</span><span>)</span><span>;</span></span> <span class="giallo-l"></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"> n</span><span class="z-keyword"> of</span><span class="z-variable z-other"> extensions</span><span>)</span><span> {</span></span> <span class="giallo-l"><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 z-constant"> XYZ</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> domain</span><span>.</span><span class="z-variable z-other">subdomain</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">getSubdomain</span><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-keyword"> throw</span><span class="z-entity z-name"> Error</span><span>(</span><span class="z-punctuation z-definition z-string">`</span><span class="z-string">EIP-</span><span class="z-string">${</span><span class="z-variable z-other">n</span><span class="z-string">}</span><span class="z-string"> extension not implemented</span><span class="z-punctuation z-definition z-string">`</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-keyword"> return</span><span class="z-variable z-other"> domain</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Additionally, the type of the <code>EIP712Domain</code> struct needs to be extended with the <code>subdomain</code> field. This is left out of scope of this reference implementation.</p> <h2 id="security-considerations">Security Considerations</h2> <p>While this EIP allows a contract to specify a <code>verifyingContract</code> other than itself, as well as a <code>chainId</code> other than that of the current chain, user-agents and applications should in general validate that these do match the contract and chain before requesting any user signatures for the domain. This may not always be a valid assumption.</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-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv https://wg-eips.ritovision.com/5247/

An interface to create and execute proposals.

<h2 id="abstract">Abstract</h2> <p>This EIP presents an interface for "smart contract executable proposals": proposals that are submitted to, recorded on, and possibly executed on-chain. Such proposals include a series of information about function calls including the target contract address, ether value to be transmitted, gas limits and calldatas.</p> <h2 id="motivation">Motivation</h2> <p>It is oftentimes necessary to separate the code that is to be executed from the actual execution of the code.</p> <p>A typical use case for this EIP is in a Decentralized Autonomous Organization (DAO). A proposer will create a smart proposal and advocate for it. Members will then choose whether or not to endorse the proposal and vote accordingly (see <code>ERC-1202</code>). Finallym when consensus has been formed, the proposal is executed.</p> <p>A second typical use-case is that one could have someone who they trust, such as a delegator, trustee, or an attorney-in-fact, or any bilateral collaboration format, where a smart proposal will be first composed, discussed, approved in some way, and then put into execution.</p> <p>A third use-case is that a person could make an "offer" to a second person, potentially with conditions. The smart proposal can be presented as an offer and the second person can execute it if they choose to accept this proposal.</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-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.17</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"> IERC5247</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ProposalCreated</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"> proposer</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"> proposalId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-variable"> targets</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> values</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> gasLimits</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-variable"> calldatas</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> extraParams</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"> ProposalExecuted</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"> executor</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"> proposalId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> extraParams</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"> createProposal</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> proposalId</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"> targets</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"> values</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"> gasLimits</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> calldatas</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"> extraParams</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">uint256</span><span class="z-variable"> registeredProposalId</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"> executeProposal</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> proposalId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> extraParams</span><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> <ul> <li>Originally, this interface was part of part of <code>ERC-1202</code>. However, the proposal itself can potentially have many use cases outside of voting. It is possible that voting may not need to be upon a proposal in any particular format. Hence, we decide to <em>decouple the voting interface and proposal interface</em>.</li> <li>Arrays were used for <code>target</code>s, <code>value</code>s, <code>calldata</code>s instead of single variables, allowing a proposal to carry arbitrarily long multiple functional calls.</li> <li><code>registeredProposalId</code> is returned in <code>createProposal</code> so the standard can support implementation to decide their own format of proposal id.</li> </ul> <h2 id="test-cases">Test Cases</h2> <p>A simple test case can be found as</p> <pre class="giallo z-code"><code data-lang="typescript"><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 work for a simple case</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"> const</span><span> {</span><span class="z-variable z-other z-constant"> contract</span><span>,</span><span class="z-variable z-other z-constant"> erc721</span><span>,</span><span class="z-variable z-other z-constant"> owner</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> loadFixture</span><span>(</span><span class="z-variable z-other">deployFixture</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"> callData1</span><span class="z-keyword"> =</span><span class="z-variable z-other"> erc721</span><span>.</span><span class="z-variable z-other">interface</span><span>.</span><span class="z-entity z-name">encodeFunctionData</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">mint</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> [</span><span class="z-variable z-other">owner</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-constant"> 1</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"> callData2</span><span class="z-keyword"> =</span><span class="z-variable z-other"> erc721</span><span>.</span><span class="z-variable z-other">interface</span><span>.</span><span class="z-entity z-name">encodeFunctionData</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">mint</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> [</span><span class="z-variable z-other">owner</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-constant"> 2</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span class="z-variable z-other">owner</span><span>)</span></span> <span class="giallo-l"><span> .</span><span class="z-entity z-name">createProposal</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-variable z-other">erc721</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-variable z-other"> erc721</span><span>.</span><span class="z-variable z-other">address</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-constant">0</span><span>,</span><span class="z-constant">0</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-constant">0</span><span>,</span><span class="z-constant">0</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-variable z-other">callData1</span><span>,</span><span class="z-variable z-other"> callData2</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> [</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"> erc721</span><span>.</span><span class="z-entity z-name">balanceOf</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><span class="z-variable z-other">to</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-constant">0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span class="z-variable z-other">owner</span><span>)</span><span>.</span><span class="z-entity z-name">executeProposal</span><span>(</span><span class="z-constant">0</span><span>,</span><span> [</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"> erc721</span><span>.</span><span class="z-entity z-name">balanceOf</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><span class="z-variable z-other">to</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-constant">2</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span></code></pre> <p>See <a href="https://wg-eips.ritovision.com/5247/./assets/testProposalRegistry.ts">testProposalRegistry.ts</a> for the whole testset.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A simple reference implementation can be found.</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"> createProposal</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> proposalId</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"> targets</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"> values</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"> gasLimits</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> calldatas</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"> extraParams</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">uint256</span><span class="z-variable"> registeredProposalId</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>targets</span><span>.</span><span>length </span><span class="z-keyword">==</span><span> values</span><span>.</span><span>length</span><span>,</span><span class="z-string"> &quot;GeneralForwarder: targets and values length mismatch&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>targets</span><span>.</span><span>length </span><span class="z-keyword">==</span><span> gasLimits</span><span>.</span><span>length</span><span>,</span><span class="z-string"> &quot;GeneralForwarder: targets and gasLimits length mismatch&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>targets</span><span>.</span><span>length </span><span class="z-keyword">==</span><span> calldatas</span><span>.</span><span>length</span><span>,</span><span class="z-string"> &quot;GeneralForwarder: targets and calldatas length mismatch&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> registeredProposalId </span><span class="z-keyword">=</span><span> proposalCount</span><span>;</span></span> <span class="giallo-l"><span> proposalCount</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> proposals</span><span>[</span><span>registeredProposalId</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Proposal</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> by</span><span class="z-keyword">:</span><span class="z-variable z-language"> msg.sender</span><span>,</span></span> <span class="giallo-l"><span> proposalId</span><span class="z-keyword">:</span><span> proposalId</span><span>,</span></span> <span class="giallo-l"><span> targets</span><span class="z-keyword">:</span><span> targets</span><span>,</span></span> <span class="giallo-l"><span> values</span><span class="z-keyword">:</span><span> values</span><span>,</span></span> <span class="giallo-l"><span> calldatas</span><span class="z-keyword">:</span><span> calldatas</span><span>,</span></span> <span class="giallo-l"><span> gasLimits</span><span class="z-keyword">:</span><span> gasLimits</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ProposalCreated</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> proposalId</span><span>,</span><span> targets</span><span>,</span><span> values</span><span>,</span><span> gasLimits</span><span>,</span><span> calldatas</span><span>,</span><span> extraParams</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> registeredProposalId</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"> executeProposal</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> proposalId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> extraParams</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span> Proposal </span><span class="z-storage z-type">storage</span><span> proposal </span><span class="z-keyword">=</span><span> proposals</span><span>[</span><span>proposalId</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> targets </span><span class="z-keyword">=</span><span> proposal</span><span>.</span><span>targets</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span> errorMessage </span><span class="z-keyword">=</span><span class="z-string"> &quot;Governor: call reverted without message&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</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> targets</span><span>.</span><span>length</span><span>;</span><span class="z-keyword"> +</span><span class="z-keyword">+</span><span>i</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-support"> bytes</span><span class="z-storage z-type"> memory</span><span> returndata</span><span>)</span><span class="z-keyword"> =</span><span> proposal</span><span>.</span><span>targets</span><span>[</span><span>i</span><span>]</span><span>.</span><span>call</span><span>{</span><span>value</span><span class="z-keyword">:</span><span> proposal</span><span>.</span><span>values</span><span>[</span><span>i</span><span>]</span><span>}</span><span>(</span><span>proposal</span><span>.</span><span>calldatas</span><span>[</span><span>i</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> Address</span><span>.</span><span class="z-entity z-name">verifyCallResult</span><span>(</span><span>success</span><span>,</span><span> returndata</span><span>,</span><span> errorMessage</span><span>)</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"> ProposalExecuted</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> proposalId</span><span>,</span><span> extraParams</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <p>See <a href="https://wg-eips.ritovision.com/5247/./assets/ProposalRegistry.sol">ProposalRegistry.sol</a> for more information.</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 Iván Mañúshttps://github.com/ivanmmurciaua Juan Carlos Cantóhttps://github.com/EscuelaCryptoES https://wg-eips.ritovision.com/5216/

Extension for ERC-1155 secure approvals

<h2 id="abstract">Abstract</h2> <p>This ERC defines standard functions for granular approval of <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> tokens by both <code>id</code> and <code>amount</code>. This ERC extends <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>'s popularity means that multi-token management transactions occur on a daily basis. Although it can be used as a more comprehensive alternative to <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, ERC-1155 is most commonly used as intended: creating multiple <code>id</code>s, each with multiple tokens. While many projects interface with these semi-fungible tokens, by far the most common interactions are with NFT marketplaces.</p> <p>Due to the nature of the blockchain, programming errors or malicious operators can cause permanent loss of funds. It is therefore essential that transactions are as trustless as possible. ERC-1155 uses the <code>setApprovalForAll</code> function, which approves ALL tokens with a specific <code>id</code>. This system has obvious minimum required trust flaws. This ERC combines ideas from <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> in order to create a trust mechanism where an owner can allow a third party, such as a marketplace, to approve a limited (instead of unlimited) number of tokens of one <code>id</code>.</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>Contracts using this ERC MUST implement the <code>IERC5216</code> interface.</p> <h3 id="interface-implementation">Interface implementation</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">@title</span><span class="z-comment"> ERC-1155 Allowance Extension</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 0x1be07d74</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"> IERC5216</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC1155</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 `account` grants or revokes permission to `operator` to transfer their tokens, according to</span></span> <span class="giallo-l"><span class="z-comment"> * `id` and with an amount: `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"> Approval</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 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">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>;</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 permission to `operator` to transfer the caller&#39;s tokens, according to `id`, and an amount: `amount`.</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {Approval} event.</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"> * - `operator` cannot be the caller.</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"> operator</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-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"> Returns the amount allocated to `operator` approved to transfer `account`&#39;s tokens, according to `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"> allowance</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</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"> 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></span></code></pre> <p>The <code>approve(address operator, uint256 id, uint256 amount)</code> function MUST be either <code>public</code> or <code>external</code>.</p> <p>The <code>allowance(address account, address operator, uint256 id)</code> function MUST be either <code>public</code> or <code>external</code> and MUST be <code>view</code>.</p> <p>The <code>safeTrasferFrom</code> function (as defined by ERC-1155) MUST:</p> <ul> <li>Not revert if the user has approved <code>msg.sender</code> with a sufficient <code>amount</code></li> <li>Subtract the transferred amount of tokens from the approved amount if <code>msg.sender</code> is not approved with <code>setApprovalForAll</code></li> </ul> <p>In addition, the <code>safeBatchTransferFrom</code> MUST:</p> <ul> <li>Add an extra condition that checks if the <code>allowance</code> of all <code>ids</code> have the approved <code>amounts</code> (See <code>_checkApprovalForBatch</code> function reference implementation)</li> </ul> <p>The <code>Approval</code> event MUST be emitted when a certain number of tokens are approved.</p> <p>The <code>supportsInterface</code> method MUST return <code>true</code> when called with <code>0x1be07d74</code>.</p> <h2 id="rationale">Rationale</h2> <p>The name "ERC-1155 Allowance Extension" was chosen because it is a succinct description of this ERC. Users can approve their tokens by <code>id</code> and <code>amount</code> to <code>operator</code>s.</p> <p>By having a way to approve and revoke in a manner similar to <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, the trust level can be more directly managed by users:</p> <ul> <li>Using the <code>approve</code> function, users can approve an operator to spend an <code>amount</code> of tokens for each <code>id</code>.</li> <li>Using the <code>allowance</code> function, users can see the approval that an operator has for each <code>id</code>.</li> </ul> <p>The <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> name patterns were used due to similarities with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> approvals.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation can be found <a href="https://wg-eips.ritovision.com/5216/./assets/ERC5216.sol">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Users of this ERC must thoroughly consider the amount of tokens they give permission to <code>operators</code>, and should revoke unused authorizations.</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-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/5219/

Allows the requesting of resources from contracts

<h2 id="abstract">Abstract</h2> <p>This EIP standardizes an interface to make resource requests to smart contracts and to receive HTTP-like responses.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum is the most-established blockchain for building decentralized applications (referred to as <code>DApp</code>s). Due to this, the Ethereum DApp ecosystem is very diverse. However, one issue that plagues DApps is the fact that they are not fully decentralized. Specifically, to interface a "decentralized" application, one first needs to access a <em>centralized</em> website containing the DApp's front-end code, presenting a few issues. The following are some risks associated with using centralized websites to interface with decentralized applications:</p> <ul> <li>Trust Minimization: An unnecessarily large number of entities need to be trusted</li> <li>Censorship: A centralized website is not resistant to being censored</li> <li>Permanence: The interface may not have a mechanism that permits it to be permanently stored</li> <li>Interoperability: Smart Contracts cannot directly interact with DApp interfaces</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="name-resolution">Name Resolution</h3> <p>EIPs that propose a name resolution mechanism MAY reference this EIP and MAY recommend that clients support their mechanism. Clients MAY also support regular DNS, as defined in RFC 1034 and RFC 1035.</p> <h3 id="separation-of-concerns">Separation of Concerns</h3> <p>It is RECOMMENDED to separate the application logic from the front-end logic (the contract implementing the interface defined in <a href="https://wg-eips.ritovision.com/5219/#contract-interface">Contract Interface</a>).</p> <h3 id="contract-interface">Contract Interface</h3> <p>DApp contracts MUST implement the interface defined in the following file: <a href="https://wg-eips.ritovision.com/5219/./assets/IDecentralizedApp.sol">Contract Interface</a>.</p> <h3 id="note-to-implementers">Note to Implementers</h3> <p>To save gas costs, it is recommended to use the <code>message/external-body</code> MIME-type, which allows you to point to data that the smart contract might not have access to. For example, the following response would tell a client to fetch the data off of IPFS:</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span class="z-entity z-name z-tag">s</span><span class="z-entity z-name z-tag">tatusCode</span><span>:</span><span class="z-constant"> 200</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag">b</span><span class="z-entity z-name z-tag">ody</span><span>:</span><span class="z-string"> T</span><span class="z-string">HIS IS NOT REALLY THE BODY!</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag">h</span><span class="z-entity z-name z-tag">eaders</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> k</span><span class="z-entity z-name z-tag">ey</span><span>:</span><span class="z-string"> C</span><span class="z-string">ontent-type</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> v</span><span class="z-entity z-name z-tag">alue</span><span>:</span><span class="z-string"> m</span><span class="z-string">essage/external-body; access-type=URL; URL=&quot;ipfs://11148a173fd3e32c0fa78b90fe42d305f202244e2739&quot;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The <code>request</code> method was chosen to be readonly because all data should be sent to the contract from the parsed DApp. Here are some reasons why:</p> <ul> <li>Submitting a transaction to send a request would be costly and would require waiting for the transaction to be mined, resulting in bad user experience.</li> <li>Complicated front-end logic should not be stored in the smart contract, as it would be costly to deploy and would be better run on the end-user's machine.</li> <li>Separation of Concerns: the front-end contract shouldn't have to worry about interacting with the back-end smart contract.</li> <li>Other EIPs can be used to request state changing operations in conjunction with a <code>307 Temporary Redirect</code> status code.</li> </ul> <p>Instead of mimicking a full HTTP request, a highly slimmed version was chosen for the following reasons:</p> <ul> <li>The only particularly relevant HTTP method is <code>GET</code></li> <li>Query parameters can be encoded in the resource.</li> <li>Request headers are, for the most part, unnecessary for <code>GET</code> requests.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is backwards compatible with all standards listed in the <a href="https://wg-eips.ritovision.com/5219/#name-resolution">Name Resolution</a> section.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The normal security considerations of accessing normal URLs apply here, such as potential privacy leakage by following <code>3XX</code> redirects.</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-07-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Tim Daubenschützhttps://github.com/TimDaub Andershttps://github.com/0xanders https://wg-eips.ritovision.com/5192/

Minimal interface for soulbinding EIP-721 NFTs

<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 a minimal interface to make tokens soulbound using the feature detection functionality of <a href="https://wg-eips.ritovision.com/165/">EIP-165</a>. A soulbound token is a non-fungible token bound to a single account.</p> <h2 id="motivation">Motivation</h2> <p>The Ethereum community has expressed a need for non-transferrable, non-fungible, and socially-priced tokens similar to World of Warcraft’s soulbound items. But the lack of a token standard leads many developers to simply throw errors upon a user's invocation of transfer functionalities. Over the long term, this will lead to fragmentation and less composability.</p> <p>In this document, we outline a minimal addition to <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> that allows wallet implementers to check for a token contract's permanent (non-)transferability using <a href="https://wg-eips.ritovision.com/165/">EIP-165</a>.</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>A token with a <code>uint256 tokenId</code> may be bound to a receiving account with <code>function locked(...)</code> returning <code>true</code>. In this case, all <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> functions of the contract that transfer the token from one account to another 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"> IERC5192</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 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"> tokenId</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"> Locked</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"> Emitted 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"> tokenId</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"> Unlocked</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"> Returns the locking status of an Soulbound 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"> tokenId</span><span class="z-comment"> The identifier for an SBT.</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"> 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>To aid recognition that an <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> token implements "soulbinding" via this EIP upon calling <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>'s <code>function supportsInterface(bytes4 interfaceID) external view returns (bool)</code> with <code>interfaceID=0xb45a3c0e</code>, a contract implementing this EIP must return <code>true</code>.</p> <h2 id="rationale">Rationale</h2> <p>The above model is the simplest possible path towards a canonical interface for Soulbound tokens. It reflects upon the numerous Soulbound token implementations that simply revert upon transfers.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backward compatible with <a href="https://wg-eips.ritovision.com/721/">EIP-721</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-06-29T00:00:00+00:00 2026-02-11T14:48:26+00:00 Agustín Aguilarhttps://github.com/agusx1211 Philippe Castonguayhttps://github.com/phabc Michael Standenhttps://github.com/ScreamingHawk https://wg-eips.ritovision.com/5189/

An account abstraction proposal that avoids protocol changes while maintaining compatibility with existing smart contract wallets.

<h2 id="abstract">Abstract</h2> <p>This ERC proposes a form of account abstraction (AA) that ensures compatibility with existing smart contract wallets and provides flexibility for alternative designs while avoiding introducing changes to the consensus layer. Instead of defining a strict structure for AA transactions, this proposal introduces the figure of <code>endorser</code> contracts. These smart contract instances are tasked with determining the quality of the submitted AA transactions, thus safely helping bundlers determine if a transaction should be kept in the mempool or not. Developers that intend to make their smart contract wallet compatible with this ERC must create and deploy an instance of an <code>endorser</code> or use an existing one compatible with their wallet.</p> <h2 id="motivation">Motivation</h2> <p>This account abstraction proposal aims to implement a generalized system for executing AA transactions while maintaining the following goals:</p> <ul> <li><strong>Achieve the primary goal of account abstraction:</strong> allow users to use smart contract wallets containing arbitrary verification and execution logic instead of EOAs as their primary account.</li> <li><strong>Decentralization:</strong> <ul> <li>Allow any bundler to participate in the process of including AA transactions.</li> <li>Work with all activity happening over a public mempool without having to concentrate transactions on centralized relayers.</li> <li>Define structures that help maintain a healthy mempool without risking its participants from getting flooded with invalid or malicious payloads.</li> <li>Avoid trust assumptions between bundlers, developers, and wallets.</li> </ul> </li> <li><strong>Support existing smart contract wallet implementations:</strong> Work with all the smart contract wallets already deployed and active while avoiding forcing each wallet instance to be manually upgraded.</li> <li><strong>Provide an unrestrictive framework:</strong> Smart contract wallets are very different in design, limitations, and capabilities from one another; the proposal is designed to accommodate almost all possible variations.</li> <li><strong>No overhead:</strong> Smart contract wallets already have a cost overhead compared to EOA alternatives, the proposal does not worsen the current situation.</li> <li><strong>Support other use cases:</strong> <ul> <li>Privacy-preserving applications.</li> <li>Atomic multi-operations (similar to <a href="https://wg-eips.ritovision.com/3074/">EIP-3074</a>).</li> <li>Payment of transaction fees using tokens. (E.g. <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/777/">ERC-777</a>, etc.)</li> <li>Scheduled execution of smart contracts without any user input.</li> <li>Applications that require a generalistic relayer.</li> </ul> </li> </ul> <h2 id="specification">Specification</h2> <p>To avoid Ethereum consensus changes, we do not attempt to create new transaction types for account-abstracted transactions. Instead, AA transactions are packed up in a struct called <code>Operation</code>, operations are structs composed by the following fields:</p> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>entrypoint</td><td>address</td><td>Contract address that must be called with <code>callData</code> to execute the <code>operation</code>.</td></tr> <tr><td>callData</td><td>bytes</td><td>Data that must be passed to the <code>entrypoint</code> call to execute the <code>operation</code>.</td></tr> <tr><td>fixedGas</td><td>uint64</td><td>Amount of gas that the operation will pay for, regardless execution costs, and independent from <code>gasLimit</code>.</td></tr> <tr><td>gasLimit</td><td>uint64</td><td>Minimum gasLimit that must be passed when executing the <code>operation</code>.</td></tr> <tr><td>feeToken</td><td>address</td><td>Contract address of the token used to repay the bundler. <em>(<code>address(0)</code> for the native token)</em>.</td></tr> <tr><td>endorser</td><td>address</td><td>Address of the endorser contract that should be used to validate the <code>operation</code>.</td></tr> <tr><td>endorserCallData</td><td>bytes</td><td>Additional data that must be passed to the <code>endorser</code> when calling <code>isOperationReady()</code>.</td></tr> <tr><td>endorserGasLimit</td><td>uint64</td><td>Amount of gas that should be passed to the endorser when validating the <code>operation</code>.</td></tr> <tr><td>maxFeePerGas</td><td>uint256</td><td>Max amount of basefee that the <code>operation</code> execution is expected to pay. <em>(Similar to <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> <code>max_fee_per_gas</code>)</em>.</td></tr> <tr><td>priorityFeePerGas</td><td>uint256</td><td>Fixed amount of fees that the <code>operation</code> execution is expected to pay to the bundler. <em>(Similar to <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> <code>max_priority_fee_per_gas</code>)</em>.</td></tr> <tr><td>feeScalingFactor</td><td>uint256</td><td>Scaling factor to convert the computed fee into the <code>feeToken</code> unit.</td></tr> <tr><td>feeNormalizationFactor</td><td>uint256</td><td>Normalization factor to convert the computed fee into the <code>feeToken</code> unit.</td></tr> <tr><td>hasUntrustedContext</td><td>bool</td><td>If <code>true</code>, the operation <em>may</em> have untrusted code paths. These should be treated differently by the bundler (see untrusted environment).</td></tr> <tr><td>chainId</td><td>uint256</td><td>Chain ID of the network where the <code>operation</code> is intended to be executed.</td></tr> </tbody></table> <p>These <code>Operation</code> objects can be sent to a dedicated operations mempool. A specialized class of actors called bundlers (either block producers running special-purpose code, or just users that can relay transactions to block producers) listen for operations on the mempool and execute these transactions.</p> <p>Transactions are executed by calling the <code>entrypoint</code> with the provided <code>callData</code>. The <code>entrypoint</code> can be any contract, but most commonly it will be the wallet contract itself. Alternatively it can be an intermediary utility that deploys the wallet and then performs the transaction.</p> <h3 id="endorser-functionality">Endorser functionality</h3> <p>Mempool participants need to be able to able to filter "good operations" (operations that pay the bundler the defined fee) from "bad operations" (operations that either miss payment or revert altogether).</p> <p>This categorization is facilitated by the <code>endorser</code>; the endorser must be a deployed smart contract that implements 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"> Endorser</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Operation</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> entrypoint</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> callData</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> fixedGas</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> gasLimit</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> endorser</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> endorserCallData</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> endorserGasLimit</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> maxFeePerGas</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> priorityFeePerGas</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> feeToken</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> feeScalingFactor</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> feeNormalizationFactor</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> hasUntrustedContext</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"> GlobalDependency</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> baseFee</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> blobBaseFee</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> chainId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> coinBase</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> difficulty</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> gasLimit</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> number</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> timestamp</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> txOrigin</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> txGasPrice</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> maxBlockNumber</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> maxBlockTimestamp</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"> Constraint</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> slot</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> minValue</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> maxValue</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"> Dependency</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> addr</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> balance</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> code</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> nonce</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> allSlots</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span> slots</span><span>;</span></span> <span class="giallo-l"><span> Constraint</span><span>[</span><span>]</span><span> constraints</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"> Replacement</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> oldAddr</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> newAddr</span><span>;</span></span> <span class="giallo-l"><span> SlotReplacement</span><span>[</span><span>]</span><span> slots</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"> SlotReplacement</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> slot</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</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-storage z-type"> function</span><span class="z-entity z-name"> simulationSettings</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> Operation</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _operation</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-storage z-type"> Replacement</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> replacements</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"> isOperationReady</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> Operation</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _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> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> readiness</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> GlobalDependency</span><span class="z-storage z-type"> memory</span><span class="z-variable"> globalDependency</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> Dependency</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> dependencies</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Endorsers SHOULD be registered in the <code>EndorserRegistry</code> with an amount of burned ETH. The amount of ETH to be burned is not specified in this proposal as mempool operators are free to set their own minimum thresholds. Mempool operators MAY accept operations from endorsers without any burned ETH, but they would increase their risk exposing themselves to denial of service attacks. Mempool operators MAY publish the minimum amount of burned ETH required for each endorser.</p> <p>To check for operation status, the caller must first call <code>simulationSettings</code> to retrieve a list of on chain alterations. Then call when the <code>isOperationReady</code> method is called, the endorser must return this information:</p> <ul> <li><strong>readiness:</strong> when returning <code>true</code>, it means the transaction MUST be executed correctly and the bundler MUST be paid the offered gas fees (even if the underlying intent of the operation fails).</li> <li><strong>globalDependency:</strong> a list of possible dependencies that don't belong to a given address, defines if the execution of the transaction MAY be invalidated by a change on one of these global variables. <code>maxBlockNumber</code> and <code>maxBlockTimestamp</code> are used as global constraints.</li> <li><strong>dependencies:</strong> a comprehensive list of addresses and storage slots that must be monitored; any state change in these dependencies MUST trigger a re-evaluation of the operation's readiness.</li> </ul> <p>The information provided by the endorser helps the mempool operator maintain a pool of "good" AA transactions that behave correctly; but it only provides a soft guarantee that the transaction will be executed correctly. Bundlers must always simulate the result of the execution before including a transaction in a block.</p> <p>If the result of a simulation fails and the endorser still returns <code>readiness == true</code> with the same dependencies, then the endorser can not be trusted and it MUST be banned by the mempool operator.</p> <p>The dependency list serves as a shortcut for the bundler to know which operations are fully independent from each other. This shortcut is useful for (a) clearing the mempool from operations that are no longer valid, and (b) for bundlers to know which operations can be included in the same block.</p> <p>For efficiency, additional information MAY be provided to the endorser with <code>endorserCallData</code>. If used, the endorser MUST validate that the provided <code>endorserCallData</code> is valid and relevant to the other values provided.</p> <p>While the endorser is deployed on chain, calls to the endorser MUST NOT be submitted on chain. The bundler MUST read the results of <code>simulationSettings</code>, perform chain alterations and simulate the execution off chain.</p> <h3 id="global-dependencies">Global Dependencies</h3> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>baseFee</td><td>bool</td><td><code>true</code> if the <code>block.basefee</code> should be considered a dependency.</td></tr> <tr><td>blobBaseFee</td><td>bool</td><td><code>true</code> if the <code>block.blockbasefee</code> should be considered a dependency.</td></tr> <tr><td>chainId</td><td>bool</td><td><code>true</code> if the <code>block.chainid</code> should be considered a dependency.</td></tr> <tr><td>coinbase</td><td>bool</td><td><code>true</code> if the <code>block.coinbase</code> should be considered a dependency.</td></tr> <tr><td>difficulty</td><td>bool</td><td><code>true</code> if the <code>block.difficulty</code> should be considered a dependency.</td></tr> <tr><td>gasLimit</td><td>bool</td><td><code>true</code> if the <code>block.gaslimit</code> should be considered a dependency.</td></tr> <tr><td>number</td><td>bool</td><td><code>true</code> if the <code>block.number</code> should be considered a dependency.</td></tr> <tr><td>timestamp</td><td>bool</td><td><code>true</code> if the <code>block.timestamp</code> should be considered a dependency.</td></tr> <tr><td>txOrigin</td><td>bool</td><td><code>true</code> if the <code>tx.origin</code> should be considered a dependency.</td></tr> <tr><td>txGasPrice</td><td>bool</td><td><code>true</code> if the <code>tx.gasprice</code> should be considered a dependency.</td></tr> <tr><td>maxBlockNumber</td><td>uint256</td><td>The maximum value of <code>block.number</code> that <code>readiness</code> applies to.</td></tr> <tr><td>maxBlockTimestamp</td><td>uint256</td><td>The maximum value of <code>block.timestamp</code> that <code>readiness</code> applies to.</td></tr> </tbody></table> <p>The <code>endorser</code> MUST use the <code>maxBlockNumber</code> and <code>maxBlockTimestamp</code> fields to limit the validity of the <code>readiness</code> result. This is useful for operations that are only valid for a certain period of time.</p> <p>Note that all values are <strong>inclusive</strong>. If the <code>endorser</code> determines the validity of the <code>operation</code> is indefinite, the <code>maxBlockNumber</code> and <code>maxBlockTimestamp</code> fields MUST be set to <code>type(uint256).max</code>.</p> <h3 id="dependencies">Dependencies</h3> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>addr</td><td>address</td><td>Contract address of the dependencies entry. <em>(Only one entry per address is allowed)</em>.</td></tr> <tr><td>balance</td><td>bool</td><td><code>true</code> if the balance of <code>addr</code> should be considered a dependency of the <code>operation</code>.</td></tr> <tr><td>code</td><td>bool</td><td><code>true</code> if the code of <code>addr</code> should be considered a dependency of the <code>operation</code>.</td></tr> <tr><td>nonce</td><td>bool</td><td><code>true</code> if the nonce of <code>addr</code> should be considered a dependency of the <code>operation</code>.</td></tr> <tr><td>allSlots</td><td>bool</td><td><code>true</code> if all storage slots of <code>addr</code> should be considered a dependency of the <code>operation</code>.</td></tr> <tr><td>slots</td><td>bytes32[]</td><td>List of all storage slots of <code>addr</code> that should be considered dependencies of <code>operation</code>.</td></tr> <tr><td>constraints</td><td>Constraint[]</td><td>List of storage slots of <code>addr</code> that have a range of specific values as dependencies.</td></tr> </tbody></table> <p>The <code>endorser</code> does not need to include all accessed storage slots on the dependencies list, it only needs to include storage slots that after a change may also result in a change of readiness.</p> <p>Note that <code>allSlots</code>, <code>constraints</code> and <code>slots</code> are mutually exclusive. If <code>allSlots</code> is set to <code>true</code>, then <code>constraints</code> and <code>slots</code> MUST be empty arrays. If a slot is listed in <code>constraints</code>, it MUST NOT be listed in <code>slots</code>. The <code>endorser</code> should prefer to use <code>constraints</code> over <code>slots</code>, and <code>slots</code> over <code>allSlots</code> whenever possible to limit reevaluation requirements of the bundler.</p> <blockquote> <p>E.g. A wallet may pay fees using funds stored as WETH. During <code>isOperationReady()</code>, the endorser contract may call the <code>balanceOf</code> method of the <code>WETH</code> contract to determine if the wallet has enough <code>WETH</code> balance. Even though the ETH balance of the WETH contract and the code of the WETH contract are being accessed, the endorser only cares about the user's WETH balance for this operation and hence does not include these as dependencies.</p> </blockquote> <h4 id="constraints">Constraints</h4> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>slot</td><td>bytes32</td><td>Storage slot of <code>addr</code> that has a range of specific values as dependencies.</td></tr> <tr><td>minValue</td><td>bytes32</td><td>Minimum value (inclusive) of <code>slot</code> that <code>readiness</code> applies to.</td></tr> <tr><td>maxValue</td><td>bytes32</td><td>Maximum value (inclusive) of <code>slot</code> that <code>readiness</code> applies to.</td></tr> </tbody></table> <p>The <code>endorser</code> can use the <code>minValue</code> and <code>maxValue</code> fields to limit the validity of the <code>readiness</code> result. This allows the endorser to fully validate an operation, even when this operation depends on storage values that are not directly accessible by the endorser.</p> <p>Note that all values are <strong>inclusive</strong>. When an exact value is required, <code>minValue</code> and <code>maxValue</code> should be set to the same value.</p> <h3 id="simulation-settings">Simulation settings</h3> <p>The <code>simulationSettings</code> method returns a list of replacements that the bundler should apply to the operation before simulating the <code>isOperationReady</code>. Note that these replacements are only used for <code>isOperationReady</code> simulation and are not applied when simulating the operation itself.</p> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>oldAddr</td><td>address</td><td>The on chain address where contract code is currently located.</td></tr> <tr><td>newAddr</td><td>address</td><td>The address the contract code should be located when performing simulation.</td></tr> <tr><td>slots.slot</td><td>bytes32</td><td>The slot location to be changed.</td></tr> <tr><td>slots.value</td><td>bytes32</td><td>The value of the slot to be set before performing simulation.</td></tr> </tbody></table> <p>The <code>endorser</code> MAY use the <code>simulationSettings</code> method to provide a list of replacements that the bundler should apply to the network before simulating <code>isOperationReady</code>. This is useful for operations that must be called from specific contract addresses or that depend on specific storage values (e.g. <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a>'s EntryPoint).</p> <p>The <code>endorser</code> MAY provide it's own address for replacement. In this event, the bundler should update the <code>endorser</code> address used when calling <code>isOperationReady</code>.</p> <h3 id="misbehavior-detection">Misbehavior detection</h3> <p>It is possible for <code>endorser</code> contracts to behave maliciously or erratically in the following ways:</p> <ul> <li>(1) It considers an operation "ready", but when the operation is executed it transfers less than the agreed-upon fees to the bundler.</li> <li>(2) It considers an operation "ready", but when the operation is executed the top-level call fails.</li> <li>(3) It changes the readiness from <code>true</code> to <code>false</code> while none of the dependencies register any change.</li> </ul> <p>The bundler MUST discard and re-evaluate the readiness status after a change on any of the dependencies of the <code>operation</code>, meaning that only operations considered <code>ready</code> are candidates for constructing the next block.</p> <p>If, when simulating the final inclusion of the operation, the bundler discovers that it does not result in correct payment (either because the transaction fails, or transferred amount is below the defined fee), then it MUST ban the <code>endorser</code>.</p> <p>When an <code>endorser</code> is banned, the mempool operator MUST drop all <code>operations</code> related to the endorser.</p> <h3 id="untrusted-environment">Untrusted environment</h3> <p>In some scenarios, the <code>endorser</code> may not be able to fully validate the <code>operation</code> but may be able to infer that a given code path <em>should</em> be safe. In these cases, the endorser can mark a section of the operation as <code>untrusted</code>. Any storage slots (balance, code, nonce, or specific slots) accessed in this untrusted context should be automatically considered as dependencies.</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"> Endorser</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UntrustedStarted</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"> UntrustedEnded</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The endorser can use the <code>UntrustedStarted</code> and <code>UntrustedEnded</code> events to signal the start and end of an untrusted context. The bundler should listen to these events and extend the dependencies list accordingly.</p> <p>Only the top-level <code>endorser</code> can signal an untrusted context; any other events with the same signature but emitted by a different contract should be ignored.</p> <p>Untrusted contexts can be opened and closed multiple times and can be nested. If multiple events are emitted, the bundler MUST count the number of <code>UntrustedStarted</code> and <code>UntrustedEnded</code> events and only consider the untrusted context as ended when the number of <code>UntrustedEnded</code> events is equal to the number of <code>UntrustedStarted</code> events.</p> <p>If <code>hasUntrustedContext</code> is set to <code>false</code>, the bundler should ignore any <code>UntrustedStarted</code> and <code>UntrustedEnded</code> events.</p> <h4 id="automatic-dependency-graph-construction">Automatic dependency graph construction</h4> <p>All code executed within the untrusted context must be monitored. If the code executes any of the following opcodes, the dependency graph must be extended accordingly.</p> <table><thead><tr><th>Opcode</th><th>Dependency</th></tr></thead><tbody> <tr><td>BALANCE</td><td><code>dependencies[addr].balance = true</code></td></tr> <tr><td>ORIGIN</td><td><code>global.txOrigin = true</code></td></tr> <tr><td>CODESIZE</td><td>None</td></tr> <tr><td>CODECOPY</td><td>None</td></tr> <tr><td>GASPRICE</td><td><code>global.txGasPrice = true</code></td></tr> <tr><td>EXTCODESIZE</td><td><code>dependencies[addr].code = true</code></td></tr> <tr><td>EXTCODECOPY</td><td><code>dependencies[addr].code = true</code></td></tr> <tr><td>EXTCODEHASH</td><td><code>dependencies[addr].code = true</code></td></tr> <tr><td>COINBASE</td><td><code>global.coinbase = true</code></td></tr> <tr><td>TIMESTAMP</td><td><code>global.timestamp = true</code></td></tr> <tr><td>NUMBER</td><td><code>global.number = true</code></td></tr> <tr><td>DIFFICULTY</td><td><code>global.difficulty = true</code></td></tr> <tr><td>PREVRANDAO</td><td><code>global.difficulty = true</code></td></tr> <tr><td>CHAINID</td><td><code>global.chainId = true</code></td></tr> <tr><td>SELFBALANCE</td><td><code>dependencies[self].balance = true</code></td></tr> <tr><td>BASEFEE</td><td><code>global.baseFee = true</code></td></tr> <tr><td>SLOAD</td><td><code>dependencies[addr].slots[slot] = true</code></td></tr> <tr><td>CREATE</td><td><code>dependencies[addr].nonce = true</code></td></tr> <tr><td>CREATE2</td><td><code>dependencies[contract].code = true</code></td></tr> </tbody></table> <p>Notice that untrusted contexts generate a lot of dependencies and may generate many false positives. This may lead to numerous re-evaluations and thus to the operation being dropped from the mempool. A bundler MAY choose to drop operations if the number of dependencies exceeds a certain threshold.</p> <p>Block-level dependencies are specially sensitive as they will be shared with a large number of operations.</p> <p>It is recommended to use untrusted contexts only when necessary, like when an <code>endorser</code> needs to validate a nested signature to a wallet that is not under its control.</p> <h3 id="fee-payment">Fee payment</h3> <p>The <code>endorser</code> MUST guarantee that the operation will repay at least the spent gas to <code>tx.origin</code>.</p> <p>The payment is always made in the <code>feeToken</code>, which can be any token standard (E.g. <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>). If <code>feeToken</code> is <code>address(0)</code>, then payment is made in the native currency. When <code>feeToken</code> is <code>address(0)</code>, <code>feeScalingFactor</code> and <code>feeNormalizationFactor</code> MUST be equal to <code>1</code>.</p> <p>All units are expressed in the native token unit. The result of the fee calculation is then converted to the <code>feeToken</code> unit using the <code>feeScalingFactor</code> and <code>feeNormalizationFactor</code>.</p> <p>The gas units consider a fixed amount of gas (<code>fixedGas</code>) and a variable amount of gas (<code>gasLimit</code>). Allowing fixed costs caters for gas overheads which may be outside the scope of the on chain execution, such as calldata fees. This also allows repayment to be reduced when execution is cheaper than expected (such as when an inner call fails without reverting the top-level transaction), while still repaying the bundler.</p> <p>The expected gas repayment is calculated as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>gasUnits = op.fixedGas + Min(gasUsed, op.gasLimit)</span></span> <span class="giallo-l"><span>feePerGas = Min(op.maxFeePerGas, block.baseFee + op.priorityFeePerGas)</span></span> <span class="giallo-l"><span>expectedRepayment = (gasUnits * feePerGas * op.feeScalingFactor) / op.feeNormalizationFactor</span></span></code></pre> <p>While the <code>endorser</code> MUST guarantee the repayment of <code>expectedRepayment</code>, the actual repayment amount MAY exceed this fee. E.g. For ease of development, a bundler MAY choose to only endorse operations that repay the maximum values provided by the operation.</p> <h3 id="operation-identification">Operation identification</h3> <p>Operations can be identified by their operation hash, which is calculated as a CIDv1 multihash of a <code>raw</code> file, containing the canonical JSON representation of the operation. This hash is never used on-chain, but it serves as a unique pointer to the operation that can be shared across systems.</p> <p>The operation MAY be pinned on the IPFS network; this would allow other participants to retrieve the content of the operation after the operation has been removed from the mempool. This pinning is not mandatory, and it may be performed by the mempool operator or by the wallet itself if visibility of the operation is desired.</p> <h3 id="bundler-behavior-upon-receiving-an-operation">Bundler behavior upon receiving an operation</h3> <p>Bundlers can add their own rules for how to ensure the successful relaying of AA transactions and for getting paid for relaying these transactions. However, we propose here a baseline specification that should be sufficient.</p> <p>When a bundler receives an <code>operation</code>, it SHOULD perform these sanity checks:</p> <ul> <li>The <code>endorserGasLimit</code> is sufficiently low (&lt;= <code>MAX_ENDORSER_GAS</code>).</li> <li>The endorser (i) is registered and has enough burn (&gt;= <code>MIN_ENDORSER_BURN</code>), and (ii) it has not been internally flagged as banned.</li> <li>The <code>fixedGas</code> is large enough to cover the cost associated with submitting the transaction (i.e. calldata gas costs).</li> <li>The <code>gasLimit</code> is at least the cost of a <code>CALL</code> with a non-zero value.</li> <li>The <code>feeToken</code> is <code>address(0)</code> or a known token address that the bundler is willing to accept.</li> <li>The <code>feeScalingFactor</code> and <code>feeNormalizationFactor</code> are <code>1</code> for a <code>feeToken</code> value of <code>address(0)</code> or values the bundler is willing to accept.</li> <li>The <code>maxFeePerGas</code> and <code>priorityPerGas</code> are above a configurable minimum value the bundler is willing to accept.</li> <li>If another operation exists in the mempool with the exact same dependency set AND the same endorser address, the <code>maxFeePerGas</code> and <code>priorityFeePerGas</code> of the newly received operation MUST be 12% higher than the one on the mempool to replace it. (Similar with how EOA with same nonce work)</li> </ul> <p>The bundler should then perform evaluation of the operation.</p> <h3 id="evaluation">Evaluation</h3> <p>To evaluate the <code>operation</code>, the bundler MUST call <code>simulationSettings()</code> on the <code>endorser</code> to obtain simulation setting values. The bundler MUST apply the settings and <strong>simulate</strong> a call to <code>isOperationReady()</code> on the <code>endorser</code>. If the endorser considers the operation ready, and the constraints are within bounds, then the client MUST add the operation to the mempool. Otherwise, the operation MUST be dropped.</p> <p>The <code>endorser</code> result SHOULD be invalidated and its readiness SHOULD be re-evaluated if any of the values of the provided dependencies change. If the operation readiness changes to <code>false</code>, the operation MUST be discarded.</p> <p>Before including the operation in a block, a last simulation MUST be performed, this time by constructing the block and probing the result. All transactions in the block listed <strong>before</strong> the operation must be simulated and then the <code>endorser</code> must be queried for readiness in-case some dependencies changed. Then constraints MUST be re-evaluated for correctness. Finally, the <strong>operation</strong> MUST be simulated.</p> <p>If the <strong>operation</strong> fails during the final simulation, the <code>endorser</code> MUST be banned because (i) it returned a bad readiness state or (ii) it changed the operation readiness independently from the dependencies.</p> <h3 id="optional-rules">Optional rules</h3> <p>Mempool clients MAY implement additional rules to further protect against maliciously constructed transactions.</p> <ul> <li>Limit the size of accepted dependencies to <code>MAX_OPERATION_DEPENDENCIES</code>, dropping operations that cross the boundary.</li> <li>Limit the number of times an operation may trigger a re-evaluation to <code>MAX_OPERATION_REEVALS</code>, dropping operations that cross the boundary.</li> <li>Limit the number of operations in the mempool that depend on the same dependency slots.</li> </ul> <p>If these rules are widely adopted, wallet developers should keep usage of dependencies to the lowest possible levels and avoid shared dependency slots that are frequently updated.</p> <h3 id="after-operation-inclusion">After operation inclusion</h3> <p>There is no limit in-place that defines that an operation can only be executed once.</p> <p>The bundler SHOULD NOT drop an <code>operation</code> after successfully including such operation in a block, the bundler MAY perform evaluation.</p> <p>If the <code>endorser</code> still returns <code>readiness == true</code> (after inclusion) then the operation SHOULD be treated as any other healthy operation, and thus it MAY be kept in the mempool.</p> <h3 id="endorser-registry">Endorser registry</h3> <p>The endorser registry serves as a place to register the burn of each endorser, anyone can increase the burn of any endorser by calling the <code>addBurn()</code> function.</p> <p>All burn is effectively locked forever; slashing can't be reliably proved on-chain without protocol alterations, so it remains a virtual event on which mempool operators will ignore the deposited ETH.</p> <h4 id="implementation">Implementation</h4> <p>(EXAMPLE)</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: UNLICENSED</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.15</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"> EndorserRegistry</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Burned</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"> _endorser</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"> _sender</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _new</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _total</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"> 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> burn</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"> addBurn</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _endorser</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">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> total </span><span class="z-keyword">=</span><span> burn</span><span>[</span><span>_endorser</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> burn</span><span>[</span><span>_endorser</span><span>]</span><span class="z-keyword"> =</span><span> total</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"> Burned</span><span>(</span><span>_endorser</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span class="z-variable z-language"> msg</span><span>.</span><span>value</span><span>,</span><span> total</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> total</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> <h3 id="griefing-protection">Griefing protection</h3> <p>The main challenge with a purely smart contract wallet-based account abstraction system is DoS safety: how can a bundler that includes an operation make sure it will be paid without executing the entire operation?</p> <p>Bundlers could execute the entire operation to determine if it is healthy or not, but this operation may be expensive and complex for the following reasons:</p> <ul> <li>The bundler does not have a way to simulate the transaction with a reduced amount of gas; it has to use the whole <code>gasLimit</code>, exposing itself to a higher level of griefing.</li> <li>The bundler does not have a way to know if a change to the state will affect the operation or not, and thus it has to re-evaluate the operation after every single change.</li> <li>The bundler does not have a way to know if a change to the state will invalidate a large portion of the mempool.</li> </ul> <p>In this proposal, we add the <code>endorser</code> as a tool for the bundlers to validate arbitrary operations in a controlled manner, without the bundler having to know any of the inner workings of such operation.</p> <p>In effect, we move the responsibility from the wallet to the wallet developer; the developer must code, deploy and burn ETH for the <code>endorser</code>; this is a nearly ideal scenario because developers know how their wallet operations work, and thus they can build tools to evaluate these operations efficiently.</p> <p>Additionally, the specification is kept as simple as possible as enforcing a highly structured behavior and schema for smart contract wallet transactions may stagnate the adoption of more innovative types of wallets and the adoption of a shared standard among them.</p> <h3 id="burned-eth">Burned ETH</h3> <p>Anyone can deploy a endorser contract and wallet clients are the one providing which endorser contract should be used for the given transaction. Instead of having each bundler rely on an off-chain registry that they need to maintain, the endorser registry can be called to see if the requested endorser contract is present and how much ETH was burned for it. Bundlers can then decide a minimum treshshold for how much ETH burnt is required for an endorser contract to be accepted. Bundlers are also free to support endorsers contract that are not part of the registry or are part of it but have no ETH burned associated.</p> <h3 id="minimum-overhead">Minimum overhead</h3> <p>Since the validation of an AA transactions is done off-chain by the bundler rather than at execution time, there is no additional gas fee overhead for executing transactions. The bundler bears the risk rather than all users having to pay for that security.</p> <h3 id="differences-with-alternative-proposals">Differences with alternative proposals</h3> <ol> <li>This proposal does not require monitoring for forbidden opcodes or storage access boundaries. Wallets have complete freedom to use any EVM capabilities during validation and execution.</li> <li>This proposal does not specify any replay protection logic since all existing smart contract wallets already have their own, and designs can vary among them. Nonces can be communicated to the bundler using a <code>dependency</code>.</li> <li>This proposal does not specify a pre-deployment logic because it can be handled directly by the entrypoint.</li> <li>This proposal does not require wallets to accept <code>execution</code> transactions from a trusted entrypoint contract, reducing overhead and allowing existing wallets to be compatible with the proposal.</li> <li>This proposal does not distinguish between <code>execution</code> and <code>signature</code> payloads, this distinction remains implementation-specific.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC does not change he consensus layer, nor does impose changes on existing smart contract wallets, so there are no backwards compatibility issues.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This ERC does not make changes to on-chain interactions. Endorsers are explicitly for off-chain validations.</p> <p>Bundlers are responsible for managing their own security and for ensuring that they are paid for the transactions they include in blocks.</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:25+00:00 Charles Cooperhttps://github.com/charles-cooper Edward Amorhttps://github.com/skellet0r https://wg-eips.ritovision.com/5202/

Define a bytecode container format for indexing and utilizing blueprint contracts

<h2 id="abstract">Abstract</h2> <p>Define a standard for "blueprint" contracts, or contracts which represent initcode that is stored on-chain.</p> <h2 id="motivation">Motivation</h2> <p>To decrease deployer contract size, a useful pattern is to store initcode on chain as a "blueprint" contract, and then use <code>EXTCODECOPY</code> to copy the initcode into memory, followed by a call to <code>CREATE</code> or <code>CREATE2</code>. However, this comes with the following problems:</p> <ul> <li>It is hard for external tools and indexers to detect if a contract is a "regular" runtime contract or a "blueprint" contract. Heuristically searching for patterns in bytecode to determine if it is initcode poses maintenance and correctness problems.</li> <li>Storing initcode byte-for-byte on-chain is a correctness and security problem. Since the EVM does not have a native way to distinguish between executable code and other types of code, unless the initcode explicitly implements ACL rules, <em>anybody</em> can call such a "blueprint" contract and execute the initcode directly as ordinary runtime code. This is particularly problematic if the initcode stored by the blueprint contract has side effects such as writing to storage or calling external contracts. If the initcode stored by the blueprint contract executes a <code>SELFDESTRUCT</code> opcode, the blueprint contract could even be removed, preventing the correct operation of downstream deployer contracts that rely on the blueprint existing. For this reason, it would be good to prefix blueprint contracts with a special preamble to prevent execution.</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>A blueprint contract MUST use the preamble <code>0xFE71&lt;version bits&gt;&lt;length encoding bits&gt;</code>. 6 bits are allocated to the version, and 2 bits to the length encoding. The first version begins at 0 (<code>0b000000</code>), and versions increment by 1. The value <code>0b11</code> for <code>&lt;length encoding bits&gt;</code> is reserved. In the case that the length bits are <code>0b11</code>, the third byte is considered a continuation byte (that is, the version requires multiple bytes to encode). The exact encoding of a multi-byte version is left to a future ERC.</p> <p>A blueprint contract MUST contain at least one byte of initcode.</p> <p>A blueprint contract MAY insert any bytes (data or code) between the version byte(s) and the initcode. If such variable length data is used, the preamble must be <code>0xFE71&lt;version bits&gt;&lt;length encoding bits&gt;&lt;length bytes&gt;&lt;data&gt;</code>. The <code>&lt;length encoding bits&gt;</code> represent a number between 0 and 2 (inclusive) describing how many bytes <code>&lt;length bytes&gt;</code> takes, and <code>&lt;length bytes&gt;</code> is the big-endian encoding of the number of bytes that <code>&lt;data&gt;</code> takes.</p> <h2 id="rationale">Rationale</h2> <ul> <li> <p>To save gas and storage space, the preamble should be as minimal as possible.</p> </li> <li> <p>It is considered "bad" behavior to try to CALL a blueprint contract directly, therefore the preamble starts with <code>INVALID (0xfe)</code> to end execution with an exceptional halting condition (rather than a "gentler" opcode like <code>STOP (0x00)</code>).</p> </li> <li> <p>To help distinguish a blueprint contract from other contracts that may start with <code>0xFE</code>, a "magic" byte is used. The value <code>0x71</code> was arbitrarily chosen by taking the last byte of the keccak256 hash of the bytestring "blueprint" (i.e.: <code>keccak256(b"blueprint")[-1]</code>).</p> </li> <li> <p>An empty initcode is disallowed by the spec to prevent what might be a common mistake.</p> </li> <li> <p>Users may want to include arbitrary data or code in their preamble. To allow indexers to ignore these bytes, a variable length encoding is proposed. To allow the length to be only zero or one bytes (in the presumably common case that <code>len(data bytes)</code> is smaller than 256), two bits of the third byte are reserved to specify how many bytes the encoded length takes.</p> </li> <li> <p>In case we need an upgrade path, version bits are included. While we do not expect to exhaust the version bits, in case we do, a continuation sequence is reserved. Since only two bytes are required for <code>&lt;length bytes&gt;</code> (as <a href="https://wg-eips.ritovision.com/170/">EIP-170</a> restricts contract length to 24KB), a <code>&lt;length encoding bits&gt;</code> value of 3 would never be required to describe <code>&lt;length bytes&gt;</code>. For that reason, the special <code>&lt;length encoding bits&gt;</code> value of <code>0b11</code> is reserved as a continuation sequence marker.</p> </li> <li> <p>The length of the initcode itself is not included by default in the preamble because it takes space, and it can be trivially determined using <code>EXTCODESIZE</code>.</p> </li> <li> <p>The Ethereum Object Format (EOF) could provide another way of specifying blueprint contracts, by adding another section kind (3 - initcode). However, it is not yet in the EVM, and we would like to be able to standardize blueprint contracts today, without relying on EVM changes. If, at some future point, section kind 3 becomes part of the EOF spec, and the EOF becomes part of the EVM, this ERC will be considered to be obsolesced since the EOF validation spec provides much stronger guarantees than this ERC.</p> </li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No known issues</p> <h2 id="test-cases">Test Cases</h2> <ul> <li>An example (and trivial!) blueprint contract with no data section, whose initcode is just the <code>STOP</code> instruction:</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0xFE710000</span></span></code></pre> <ul> <li>An example blueprint contract whose initcode is the trivial <code>STOP</code> instruction and whose data section contains the byte <code>0xFF</code> repeated seven times:</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0xFE710107FFFFFFFFFFFFFF00</span></span></code></pre> <p>Here, 0xFE71 is the magic header, <code>0x01</code> means version 0 + 1 length bit, <code>0x07</code> encodes the length in bytes of the data section. These are followed by the data section, and then the initcode. For illustration, the above code with delimiters would be <code>0xFE71|01|07|FFFFFFFFFFFFFF|00</code>.</p> <ul> <li>An example blueprint whose initcode is the trivial <code>STOP</code> instruction and whose data section contains the byte <code>0xFF</code> repeated 256 times:</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0xFE71020100FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF00</span></span></code></pre> <p>Delimited, that would be <code>0xFE71|02|0100|FF...FF|00</code>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">from</span><span> typing</span><span class="z-keyword"> import</span><span> Optional</span><span>,</span><span> Tuple</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"> parse_blueprint_preamble</span><span>(</span><span class="z-variable z-parameter z-function">bytecode</span><span>:</span><span class="z-support"> bytes</span><span>)</span><span> -&gt;</span><span> Tuple</span><span>[</span><span class="z-support">int</span><span>,</span><span> Optional</span><span>[</span><span class="z-support">bytes</span><span>]</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-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string"> Given bytecode as a sequence of bytes, parse the blueprint preamble and</span></span> <span class="giallo-l"><span class="z-string"> deconstruct the bytecode into:</span></span> <span class="giallo-l"><span class="z-string"> the ERC version, preamble data and initcode.</span></span> <span class="giallo-l"><span class="z-string"> Raises an exception if the bytecode is not a valid blueprint contract</span></span> <span class="giallo-l"><span class="z-string"> according to this ERC.</span></span> <span class="giallo-l"><span class="z-string"> arguments:</span></span> <span class="giallo-l"><span class="z-string"> bytecode: a `bytes` object representing the bytecode</span></span> <span class="giallo-l"><span class="z-string"> returns:</span></span> <span class="giallo-l"><span class="z-string"> (version,</span></span> <span class="giallo-l"><span class="z-string"> None if &lt;length encoding bits&gt; is 0, otherwise the bytes of the data section,</span></span> <span class="giallo-l"><span class="z-string"> the bytes of the initcode,</span></span> <span class="giallo-l"><span class="z-string"> )</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-keyword"> if</span><span> bytecode</span><span>[</span><span>:</span><span class="z-constant">2</span><span>]</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">\xFE</span><span class="z-constant">\x71</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span class="z-support"> Exception</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Not a blueprint!</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> erc_version</span><span class="z-keyword"> =</span><span> (</span><span>bytecode</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-keyword"> &amp;</span><span class="z-storage z-type"> 0b</span><span class="z-constant">11111100</span><span>)</span><span class="z-keyword"> &gt;&gt;</span><span class="z-constant"> 2</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> n_length_bytes</span><span class="z-keyword"> =</span><span> bytecode</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-keyword"> &amp;</span><span class="z-storage z-type"> 0b</span><span class="z-constant">11</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> n_length_bytes</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> 0b</span><span class="z-constant">11</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span class="z-support"> Exception</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Reserved bits are set</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> data_length</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>bytecode</span><span>[</span><span class="z-constant">3</span><span>:</span><span class="z-constant">3</span><span class="z-keyword"> +</span><span> n_length_bytes</span><span>]</span><span>,</span><span class="z-variable"> byteorder</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">big</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-keyword"> if</span><span> n_length_bytes</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> preamble_data</span><span class="z-keyword"> =</span><span class="z-constant"> None</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> data_start</span><span class="z-keyword"> =</span><span class="z-constant"> 3</span><span class="z-keyword"> +</span><span> n_length_bytes</span></span> <span class="giallo-l"><span> preamble_data</span><span class="z-keyword"> =</span><span> bytecode</span><span>[</span><span>data_start</span><span>:</span><span>data_start</span><span class="z-keyword"> +</span><span> data_length</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> initcode</span><span class="z-keyword"> =</span><span> bytecode</span><span>[</span><span class="z-constant">3</span><span class="z-keyword"> +</span><span> n_length_bytes</span><span class="z-keyword"> +</span><span> data_length</span><span>:</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>initcode</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"> raise</span><span class="z-support"> Exception</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Empty initcode!</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-keyword"> return</span><span> erc_version</span><span>,</span><span> preamble_data</span><span>,</span><span> initcode</span></span></code></pre> <p>The following reference function takes the desired initcode for a blueprint as a parameter, and returns EVM code which will deploy a corresponding blueprint contract (with no data section):</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"> blueprint_deployer_bytecode</span><span>(</span><span class="z-variable z-parameter z-function">initcode</span><span>:</span><span class="z-support"> bytes</span><span>)</span><span> -&gt;</span><span class="z-support"> bytes</span><span>:</span></span> <span class="giallo-l"><span> blueprint_preamble</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">\xFE</span><span class="z-constant">\x71</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"> ERC5202 preamble</span></span> <span class="giallo-l"><span> blueprint_bytecode</span><span class="z-keyword"> =</span><span> blueprint_preamble</span><span class="z-keyword"> +</span><span> initcode</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 length of the deployed code in bytes</span></span> <span class="giallo-l"><span> len_bytes</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span>blueprint_bytecode</span><span>)</span><span>.</span><span>to_bytes</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">big</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"> copy &lt;blueprint_bytecode&gt; to memory and `RETURN` it per EVM creation semantics</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> PUSH2 &lt;len&gt; RETURNDATASIZE DUP2 PUSH1 10 RETURNDATASIZE CODECOPY RETURN</span></span> <span class="giallo-l"><span> deploy_bytecode</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">\x61</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword"> +</span><span> len_bytes</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">\x3d</span><span class="z-constant">\x81</span><span class="z-constant">\x60</span><span class="z-constant">\x0a</span><span class="z-constant">\x3d</span><span class="z-constant">\x39</span><span class="z-constant">\xf3</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"> return</span><span> deploy_bytecode</span><span class="z-keyword"> +</span><span> blueprint_bytecode</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>There could be contracts on-chain already which happen to start with the same prefix as proposed in this ERC. However, this is not considered a serious risk, because the way it is envisioned that indexers will use this is to verify source code by compiling it and prepending the preamble.</p> <p>As of 2022-07-08, no contracts deployed on the Ethereum mainnet have a bytecode starting with <code>0xFE71</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-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-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Brendan Asselstinehttps://github.com/asselstine Pierrick Turelierhttps://github.com/PierrickGT Chris Whinfreyhttps://github.com/cwhinfrey https://wg-eips.ritovision.com/5164/

Defines an interface that supports execution across EVM networks.

<h2 id="abstract">Abstract</h2> <p>This specification defines a cross-chain execution interface for EVM-based blockchains. Implementations of this specification will allow contracts on one chain to call contracts on another by sending a cross-chain message.</p> <p>The specification defines two components: the "Message Dispatcher" and the "Message Executor". The Message Dispatcher lives on the calling side, and the executor lives on the receiving side. When a message is sent, a Message Dispatcher will move the message through a transport layer to a Message Executor, where they are executed. Implementations of this specification must implement both components.</p> <h2 id="motivation">Motivation</h2> <p>Many Ethereum protocols need to coordinate state changes across multiple EVM-based blockchains. These chains often have native or third-party bridges that allow Ethereum contracts to execute code. However, bridges have different APIs so bridge integrations are custom. Each one affords different properties; with varying degrees of security, speed, and control. Defining a simple, common specification will increase code re-use and allow us to use common bridge implementations.</p> <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 specification allows contracts on one chain to send messages to contracts on another chain. There are two key interfaces that needs to be implemented:</p> <ul> <li><code>MessageDispatcher</code></li> <li><code>MessageExecutor</code></li> </ul> <p>The <code>MessageDispatcher</code> lives on the origin chain and dispatches messages to the <code>MessageExecutor</code> for execution. The <code>MessageExecutor</code> lives on the destination chain and executes dispatched messages.</p> <h3 id="messagedispatcher">MessageDispatcher</h3> <p>The <code>MessageDispatcher</code> lives on the chain from which messages are sent. The Dispatcher's job is to broadcast messages through a transport layer to one or more <code>MessageExecutor</code> contracts.</p> <p>A unique <code>messageId</code> MUST be generated for each message or message batch. The message identifier MUST be unique across chains and dispatchers. This can be achieved by hashing a tuple of <code>chainId, dispatcherAddress, messageNonce</code> where messageNonce is a monotonically increasing integer per message.</p> <h4 id="messagedispatcher-methods">MessageDispatcher Methods</h4> <p><strong>dispatchMessage</strong></p> <p>Will dispatch a message to be executed by the <code>MessageExecutor</code> on the destination chain specified by <code>toChainId</code>.</p> <p><code>MessageDispatcher</code>s MUST emit the <code>MessageDispatched</code> event when a message is dispatched.</p> <p><code>MessageDispatcher</code>s MUST revert if <code>toChainId</code> is not supported.</p> <p><code>MessageDispatcher</code>s MUST forward the message to a <code>MessageExecutor</code> on the <code>toChainId</code>.</p> <p><code>MessageDispatcher</code>s MUST use a unique <code>messageId</code> for each message.</p> <p><code>MessageDispatcher</code>s MUST return the <code>messageId</code> to allow the message sender to track the message.</p> <p><code>MessageDispatcher</code>s MAY require payment.</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"> MessageDispatcher</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> dispatchMessage</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> toChainId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</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-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> messageId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><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">ispatchMessage</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 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"> t</span><span class="z-string">oChainId</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"> d</span><span class="z-string">ata</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> <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">essageId</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></code></pre><h4 id="messagedispatcher-events">MessageDispatcher Events</h4> <p><strong>MessageDispatched</strong></p> <p>The <code>MessageDispatched</code> event MUST be emitted by the <code>MessageDispatcher</code> when an individual message is dispatched.</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"> MessageDispatcher</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MessageDispatched</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"> messageId</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-storage z-type"> indexed</span><span class="z-variable"> toChainId</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"> bytes</span><span class="z-variable"> data</span><span>,</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><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">essageDispatched</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"> m</span><span class="z-string">essageId</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"> 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">oChainId</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"> 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"> d</span><span class="z-string">ata</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><h3 id="messageexecutor">MessageExecutor</h3> <p>The <code>MessageExecutor</code> executes dispatched messages and message batches. Developers must implement a <code>MessageExecutor</code> in order to execute messages on the receiving chain.</p> <p>The <code>MessageExecutor</code> will execute a messageId only once, but may execute messageIds in any order. This specification makes no ordering guarantees, because messages and message batches may travel non-sequentially through the transport layer.</p> <h4 id="execution">Execution</h4> <p><code>MessageExecutor</code>s SHOULD verify all message data with the bridge transport layer.</p> <p><code>MessageExecutor</code>s MUST NOT successfully execute a message more than once.</p> <p><code>MessageExecutor</code>s MUST revert the transaction when a message fails to be executed allowing the message to be retried at a later time.</p> <p><strong>Calldata</strong></p> <p><code>MessageExecutor</code>s MUST append the ABI-packed (<code>messageId</code>, <code>fromChainId</code>, <code>from</code>) to the calldata for each message being executed. This allows the receiver of the message to verify the cross-chain sender and the chain that the message is coming from.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>to</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>data</span><span>,</span><span> messageId</span><span>,</span><span> fromChainId</span><span>,</span><span> from</span><span>)</span><span>)</span><span>;</span></span></code></pre><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">alldata</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> <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">ata</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> <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">essageId</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"> f</span><span class="z-string">romChainId</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"> 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></code></pre><h4 id="messageexecutor-events">MessageExecutor Events</h4> <p><strong>MessageIdExecuted</strong></p> <p><code>MessageIdExecuted</code> MUST be emitted once a message or message batch has been executed.</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"> MessageExecutor</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MessageIdExecuted</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"> fromChainId</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"> messageId</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><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">essageIdExecuted</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"> f</span><span class="z-string">romChainId</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"> m</span><span class="z-string">essageId</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></code></pre><h4 id="messageexecutor-errors">MessageExecutor Errors</h4> <p><strong>MessageAlreadyExecuted</strong></p> <p><code>MessageExecutor</code>s MUST revert if a messageId has already been executed and SHOULD emit a <code>MessageIdAlreadyExecuted</code> custom error.</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"> MessageExecutor</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> MessageIdAlreadyExecuted</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> messageId</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>MessageFailure</strong></p> <p><code>MessageExecutor</code>s MUST revert if an individual message fails and SHOULD emit a <code>MessageFailure</code> custom error.</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"> MessageExecutor</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> MessageFailure</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> messageId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> errorData</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The <code>MessageDispatcher</code> can be coupled to one or more <code>MessageExecutor</code>. It is up to bridges to decide how to couple the two. Users can easily bridge a message by calling <code>dispatchMessage</code> without being aware of the <code>MessageExecutor</code> address. Messages can also be traced by a client using the data logged by the <code>MessageIdExecuted</code> event.</p> <p>Some bridges may require payment in the native currency, so the <code>dispatchMessage</code> function is payable.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This specification is compatible with existing governance systems as it offers simple cross-chain execution.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Bridge trust profiles are variable, so users must understand that bridge security depends 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-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-06-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Tomasz Kajetan Stanczakhttps://github.com/tkstanczak Eric Marti Hayneshttps://github.com/ericmartihaynes Josh Klopfensteinhttps://github.com/joshklop Abhimanyu Naghttps://github.com/AbhiMan1601 https://wg-eips.ritovision.com/5133/

Delays the difficulty bomb by a further 700000 blocks, to the middle of September 2022.

<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 11,400,000 blocks later than the actual block number.</p> <h2 id="motivation">Motivation</h2> <p>To avoid network degradation due to a premature activation of the difficulty bomb.</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="python"><span class="giallo-l"><span>fake_block_number</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span class="z-constant">0</span><span>,</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> -</span><span class="z-constant"> 11_400_000</span><span>)</span><span class="z-keyword"> if</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> FORK_BLOCK_NUMBER</span><span class="z-keyword"> else</span><span> block</span><span>.</span><span>number</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The following script predicts the bomb will go off at block 15530314, which is expected to be mined around mid-September.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">import</span><span> math</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> predict_bomb_block</span><span>(</span><span class="z-variable z-parameter z-function">current_difficulty</span><span>,</span><span class="z-variable z-parameter z-function"> diff_adjust_coeff</span><span>,</span><span class="z-variable z-parameter z-function"> block_adjustment</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;&#39;&#39;</span></span> <span class="giallo-l"><span class="z-string"> Predicts the block number at which the difficulty bomb will become noticeable.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-string"> current_difficulty: the current difficulty</span></span> <span class="giallo-l"><span class="z-string"> diff_adjust_coeff: intuitively, the percent increase in work that miners have to exert to find a PoW</span></span> <span class="giallo-l"><span class="z-string"> block_adjustment: the number of blocks to delay the bomb by</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;&#39;&#39;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> round</span><span>(</span><span>block_adjustment</span><span class="z-keyword"> +</span><span class="z-constant"> 100000</span><span class="z-keyword"> *</span><span> (</span><span class="z-constant">2</span><span class="z-keyword"> +</span><span> math</span><span>.</span><span>log2</span><span>(</span><span>diff_adjust_coeff</span><span class="z-keyword"> *</span><span> current_difficulty</span><span class="z-keyword"> //</span><span class="z-constant"> 2048</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"> current_difficulty = 13891609586928851 (Jun 01, 2022)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> diff_adjust_coeff = 0.1 (historically, the bomb is noticeable when the coefficient is &gt;= 0.1)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> block_adjustment = 11400000</span></span> <span class="giallo-l"><span class="z-support">print</span><span>(</span><span>predict_bomb_block</span><span>(</span><span class="z-constant">13891609586928851</span><span>,</span><span class="z-constant"> 0.1</span><span>,</span><span class="z-constant"> 11400000</span><span>)</span><span>)</span></span></code></pre> <p>Precise increases in block times are very difficult to predict (especially after the bomb is noticeable). However, based on past manifestations of the bomb, we can anticipate 0.1s delays by mid-September and 0.6-1.2s delays by early October.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No known backward compatibility issues.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Misjudging the effects of the difficulty can mean longer blocktimes than anticipated until a hardfork is released. Wild shifts in difficulty can affect this number severely. Also, gradual changes in blocktimes due to longer-term adjustments in difficulty can affect the timing of difficulty bomb epochs. This affects the usability of the network but unlikely to have security ramifications.</p> <p>In this specific instance, it is possible that the network hashrate drops considerably before The Merge, which could accelerate the timeline by which the bomb is felt in block times. The offset value chosen aims to take this into 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> 2022-05-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 Micah Zoltuhttps://github.com/MicahZoltu https://wg-eips.ritovision.com/5114/

A token that is attached to a "soul" at mint time and cannot be transferred after that.

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

Interface for wrapped yield-bearing tokens.

<h2 id="abstract">Abstract</h2> <p>This standard proposes an API for wrapped yield-bearing tokens within smart contracts. It is an extension on the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token that provides basic functionality for transferring, depositing, withdrawing tokens, as well as reading balances.</p> <h2 id="motivation">Motivation</h2> <p>Yield generating mechanisms are built in all shapes and sizes, necessitating a manual integration every time a protocol builds on top of another protocol’s yield generating mechanism.</p> <p><a href="https://wg-eips.ritovision.com/4626/">ERC-4626</a> tackled a significant part of this fragmentation by standardizing the interfaces for vaults, a major category among various yield generating mechanisms.</p> <p>In this ERC, we’re extending the coverage to include assets beyond ERC-4626’s reach, namely:</p> <ul> <li>yield-bearing assets that have different input tokens used for minting vs accounting for the pool value. <ul> <li>This category includes AMM liquidity tokens (which are yield-bearing assets that yield swap fees) since the value of the pool is measured in “liquidity units” (for example, $\sqrt k$ in UniswapV2, as defined in UniswapV2 whitepaper) which can’t be deposited in (as they are not tokens).</li> <li>This extends the flexibility in minting the yield-bearing assets. For example, there could be an ETH vault that wants to allow users to deposit cETH directly instead of ETH, for gas efficiency or UX reasons.</li> </ul> </li> <li>Assets with reward tokens by default (e.g. COMP rewards for supplying in Compound). The reward tokens are expected to be sold to compound into the same asset.</li> <li>This ERC can be extended further to include the handling of rewards, such as the claiming of accrued multiple rewards tokens.</li> </ul> <p>While ERC-4626 is a well-designed and suitable standard for most vaults, there will inevitably be some yield generating mechanisms that do not fit into their category (LP tokens for instance). A more flexible standard is required to standardize the interaction with all types of yield generating mechanisms.</p> <p>Therefore, we are proposing Standardized Yield (SY), a flexible standard for wrapped yield-bearing tokens that could cover most mechanisms in DeFi. We foresee that:</p> <ul> <li>ERC-4626 will still be a popular vault standard, that most vaults should adopt.</li> <li>SY tokens can wrap over most yield generating mechanisms in DeFi, including ERC-4626 vaults for projects built on top of yield-bearing tokens.</li> <li>Whoever needs the functionalities of SY could integrate with the existing SY tokens or write a new SY (to wrap over the target yield-bearing token).</li> <li>Reward handling can be extended from the SY token.</li> </ul> <h3 id="use-cases">Use Cases</h3> <p>This ERC is designed for flexibility, aiming to accommodate as many yield generating mechanisms as possible. Particularly, this standard aims to be generalized enough that it supports the following use cases and more:</p> <ul> <li>Money market supply positions <ul> <li>Lending DAI in Compound, getting DAI interests and COMP rewards</li> <li>Lending ETH in BenQi, getting ETH interests and QI + AVAX rewards</li> <li>Lending USDC in Aave, getting USDC interests and stkAAVE rewards</li> </ul> </li> <li>AMM liquidity provision <ul> <li>Provide ETH + USDC to ETHUSDC pool in SushiSwap, getting swap fees in more ETH+USDC</li> <li>Provide ETH + USDC to ETHUSDC pool in SushiSwap and stake it in Sushi Onsen, getting swap fees and SUSHI rewards</li> <li>Provide USDC+DAI+USDT to 3crv pool and stake it in Convex, getting 3crv swap fees and CRV + CVX rewards</li> </ul> </li> <li>Vault positions <ul> <li>Provide ETH into Yearn ERC-4626 vault, where the vault accrues yield from Yearn’s ETH strategy</li> <li>Provide DAI into Harvest and staking it, getting DAI interests and FARM rewards</li> </ul> </li> <li>Liquid staking positions <ul> <li>Holding stETH (in Lido), getting yields in more stETH</li> </ul> </li> <li>Liquidity mining programs <ul> <li>Provide USDC in Stargate, getting STG rewards</li> <li>Provide LOOKS in LooksRare, getting LOOKS yield and WETH rewards</li> </ul> </li> <li>Rebasing tokens <ul> <li>Stake OHM into sOHM/gOHM, getting OHM rebase yield</li> </ul> </li> </ul> <p>The ERC hopes to minimize, if not possibly eliminate, the use of customized adapters in order to interact with many different forms of yield-bearing token mechanisms.</p> <h2 id="specification">Specification</h2> <h3 id="generic-yield-generating-pool">Generic Yield Generating Pool</h3> <p>We will first introduce Generic Yield Generating Pool (GYGP), a model to describe most yield generating mechanisms in DeFi. In every yield generating mechanism, there is a pool of funds, whose value is measured in <strong>assets</strong>. There are a number of users who contribute liquidity to the pool, in exchange for <strong>shares</strong> of the pool, which represents units of ownership of the pool. Over time, the value (measured in <strong>assets</strong>) of the pool grows, such that each <strong>share</strong> is worth more <strong>assets</strong> over time. The pool could earn a number of <strong>reward tokens</strong> over time, which are distributed to the users according to some logic (for example, proportionally the number of <strong>shares</strong>).</p> <p>Here are the more concrete definitions of the terms:</p> <h4 id="gygp-definitions">GYGP Definitions:</h4> <ul> <li><strong>asset</strong>: Is a unit to measure the value of the pool. At time <em>t</em>, the pool has a total value of <em>TotalAsset(t)</em> <strong>assets</strong>.</li> <li><strong>shares</strong>: Is a unit that represents ownership of the pool. At time <em>t</em>, there are <em>TotalShares(t)</em> <strong>shares</strong> in total.</li> <li><strong>reward tokens</strong>: Over time, the pool earns $n_{rewards}$ types of reward tokens $(n_{rewards} \ge 0)$. At time <em>t</em>, $TotalRewards_i(t)$ is the amount of <strong>reward token <em>i</em></strong> that has accumulated for the pool up until time <em>t</em>.</li> <li><strong>exchange rate</strong>: At time <em>t</em>, the <strong>exchange rate</strong> <em>ExchangeRate(t)</em> is simply how many <strong>assets</strong> each <strong>shares</strong> is worth $ExchangeRate(t) = \frac{TotalAsset(t)}{TotalShares(t)}$</li> <li><strong>users</strong>: At time <em>t</em>, each user <em>u</em> has $shares_u(t)$ <strong>shares</strong> in the pool, which is worth $asset_u(t) = shares_u(t) \cdot ExchangeRate(t)$ <strong>assets</strong>. Until time <em>t</em>, user <em>u</em> is entitled to receive a total of $rewards_{u_i}(t)$ <strong>reward token <em>i</em></strong>. The sum of all users’ shares, assets and rewards should be the same as the total shares, assets and rewards of the whole pool.</li> </ul> <h4 id="state-changes">State changes:</h4> <ol> <li>A user deposits $d_a$ <strong>assets</strong> into the pool at time $t$ ($d_a$ could be negative, which means a withdraw from the pool). $d_s = d_a / ExchangeRate(t)$ new <strong>shares</strong> will be created and given to user (or removed and burned from the user when $d_a$ is negative).</li> <li>The pool earns $d_a$ (or loses $−d_a$ if $d_a$ is negative) <strong>assets</strong> at time $t$. The <strong>exchange rate</strong> simply increases (or decreases if $d_a$ is negative) due to the additional assets.</li> <li>The pool earns $d_r$ <strong>reward token</strong> $i$. Every user will receive a certain amount of <strong>reward token</strong> $i$.</li> </ol> <h4 id="examples-of-gygps-in-defi">Examples of GYGPs in DeFi:</h4> <table><thead><tr><th>Yield generating mechanism</th><th>Asset</th><th>Shares</th><th>Reward tokens</th><th>Exchange rate</th></tr></thead><tbody> <tr><td>Supply USDC in Compound</td><td>USDC</td><td>cUSDC</td><td>COMP</td><td>USDC value per cUSDC, increases with USDC supply interests</td></tr> <tr><td>ETH liquid staking in Lido</td><td>stETH</td><td>wstETH</td><td>None</td><td>stETH value per wstETH, increases with ETH staking rewards</td></tr> <tr><td>Stake LOOKS in LooksRare Compounder</td><td>LOOKS</td><td>shares (in contract)</td><td>WETH</td><td>LOOKS value per shares, increases with LOOKS rewards</td></tr> <tr><td>Stake APE in $APE Compounder</td><td>sAPE</td><td>shares (in contract)</td><td>APE</td><td>sAPE value per shares, increases with APE rewards</td></tr> <tr><td>Provide ETH+USDC liquidity on Sushiswap</td><td>ETHUSDC liquidity (a pool of x ETH + y USDC has sqrt(xy) ETHUSDC liquidity)</td><td>ETHUSDC Sushiswap LP (SLP) token</td><td>None</td><td>ETHUSDC liquidity value per ETHUSDC SLP, increases due to swap fees</td></tr> <tr><td>Provide ETH+USDC liquidity on Sushiswap and stake into Onsen</td><td>ETHUSDC liquidity (a pool of x ETH + y USDC has sqrt(xy) ETHUSDC liquidity)</td><td>ETHUSDC Sushiswap LP (SLP) token</td><td>SUSHI</td><td>ETHUSDC liquidity value per ETHUSDC SLP, increases due to swap fees</td></tr> <tr><td>Provide BAL+WETH liquidity in Balancer (80% BAL, 20% WETH)</td><td>BALWETH liquidity (a pool of x BAL + y WETH has x^0.8*y^0.2 BALWETH liquidity)</td><td>BALWETH Balancer LP token</td><td>None</td><td>BALWETH liquidity per BALWETH Balancer LP token, increases due to swap fees</td></tr> <tr><td>Provide USDC+USDT+DAI liquidity in Curve</td><td>3crv pool’s liquidity (amount of D per 3crv token)</td><td>3crv token</td><td>CRV</td><td>3crv pool’s liquidity per 3crv token, increases due to swap fees</td></tr> <tr><td>Provide FRAX+USDC liquidity in Curve then stake LP in Convex</td><td>BALWETH liquidity (a pool of x BAL + y WETH has x^0.8*y^0.2 BALWETH liquidity)</td><td>BALWETH Balancer LP token</td><td>None</td><td>BALWETH liquidity per BALWETH Balancer LP token, increases due to swap fees</td></tr> </tbody></table> <h3 id="standardized-yield-token-standard">Standardized Yield Token Standard</h3> <h4 id="overview">Overview:</h4> <p>Standardized Yield (SY) is a token standard for any yield generating mechanism that conforms to the GYGP model. Each SY token represents <strong>shares</strong> in a GYGP and allows for interacting with the GYGP via a standard interface.</p> <p>All SY tokens:</p> <ul> <li><strong>MUST</strong> implement <strong><code>ERC-20</code></strong> to represent shares in the underlying GYGP.</li> <li><strong>MUST</strong> implement ERC-20’s optional metadata extensions <code>name</code>, <code>symbol</code>, and <code>decimals</code>, which <strong>SHOULD</strong> reflect the underlying GYGP’s accounting asset’s <code>name</code>, <code>symbol</code>, and <code>decimals</code>.</li> <li><strong>MAY</strong> implement <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a> to improve the UX of approving SY tokens on various integrations.</li> <li><strong>MAY</strong> revert on calls to <code>transfer</code> and <code>transferFrom</code> if a SY token is to be non-transferable.</li> <li>The ERC-20 operations <code>balanceOf</code>, <code>transfer</code>, <code>totalSupply</code>, etc. <strong>SHOULD</strong> operate on the GYGP “shares”, which represent a claim to ownership on a fraction of the GYGP’s underlying holdings.</li> </ul> <h4 id="sy-definitions">SY Definitions:</h4> <p>On top of the definitions above for GYGPs, we need to define 2 more concepts:</p> <ul> <li> <p><strong>input tokens</strong>: Are tokens that can be converted into assets to enter the pool. Each SY can accept several possible input tokens $tokens_{in_{i}}$</p> </li> <li> <p><strong>output tokens</strong>: Are tokens that can be redeemed from assets when exiting the pool. Each SY can have several possible output tokens $tokens_{out_{i}}$</p> </li> </ul> <h4 id="interface">Interface</h4> <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"> IStandardizedYield</span><span> {</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"> caller</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"> receiver</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"> tokenIn</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amountDeposited</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amountSyOut</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"> Redeem</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"> caller</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"> receiver</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"> tokenOut</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amountSyToRedeem</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amountTokenOut</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"> deposit</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> receiver</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> tokenIn</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amountTokenToDeposit</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> minSharesOut</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> depositFromInternalBalance</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">uint256</span><span class="z-variable"> amountSharesOut</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"> redeem</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> receiver</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amountSharesToRedeem</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> tokenOut</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> minTokenOut</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> burnFromInternalBalance</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">uint256</span><span class="z-variable"> amountTokenOut</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"> exchangeRate</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"> res</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"> getTokensIn</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 class="z-variable"> res</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"> getTokensOut</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 class="z-variable"> res</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"> yieldToken</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-storage z-type"> function</span><span class="z-entity z-name"> previewDeposit</span><span>(</span><span class="z-support">address</span><span class="z-variable"> tokenIn</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amountTokenToDeposit</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"> amountSharesOut</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"> previewRedeem</span><span>(</span><span class="z-support">address</span><span class="z-variable"> tokenOut</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amountSharesToRedeem</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"> amountTokenOut</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"> 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-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-storage z-type"> function</span><span class="z-entity z-name"> decimals</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></span></code></pre><h4 id="methods">Methods</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"> deposit</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> receiver</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> tokenIn</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amountTokenToDeposit</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> minSharesOut</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> depositFromInternalBalance</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">uint256</span><span class="z-variable"> amountSharesOut</span><span>)</span><span>;</span></span></code></pre> <p>This function will deposit <em>amountTokenToDeposit</em> of input token $i$ (<em>tokenIn</em>) to mint new SY shares.</p> <p>If <em>depositFromInternalBalance</em> is set to <em>false</em>, msg.sender will need to initially deposit <em>amountTokenToDeposit</em> of input token $i$ (<em>tokenIn</em>) into the SY contract, then this function will convert the <em>amountTokenToDeposit</em> of input token $i$ into $d_a$ worth of <strong>asset</strong> and deposit this amount into the pool for the <em>receiver</em>, who will receive <em>amountSharesOut</em> of SY tokens (<strong>shares</strong>). If <em>depositFromInternalBalance</em> is set to <em>true</em>, then <em>amountTokenToDeposit</em> of input token $i$ (<em>tokenIn</em>) will be taken from receiver directly (as msg.sender), and will be converted and shares returned to the receiver similarly to the first case.</p> <p>This function should revert if $amountSharesOut \lt minSharesOut$.</p> <ul> <li><strong>MUST</strong> emit the <code>Deposit</code> event.</li> <li><strong>MUST</strong> support ERC-20’s <code>approve</code> / <code>transferFrom</code> flow where <code>tokenIn</code> are taken from receiver directly (as msg.sender) or if the msg.sender has ERC-20 approved allowance over the input token of the receiver.</li> <li><strong>MUST</strong> revert if $amountSharesOut \lt minSharesOut$ (due to deposit limit being reached, slippage, or the user not approving enough <code>tokenIn</code> **to the SY contract, etc).</li> <li><strong>MAY</strong> be payable if the <code>tokenIn</code> depositing asset is the chain's native currency (e.g. ETH).</li> </ul> <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> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> receiver</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amountSharesToRedeem</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> tokenOut</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> minTokenOut</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> burnFromInternalBalance</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">uint256</span><span class="z-variable"> amountTokenOut</span><span>)</span><span>;</span></span></code></pre> <p>This function will redeem the $d_s$ shares, which is equivalent to $d_a = d_s \times ExchangeRate(t)$ assets, from the pool. The $d_a$ assets is converted into exactly <em>amountTokenOut</em> of output token $i$ (<em>tokenOut</em>).</p> <p>If <em>burnFromInternalBalance</em> is set to <em>false</em>, the user will need to initially deposit <em>amountSharesToRedeem</em> into the SY contract, then this function will burn the floating amount $d_s$ of SY tokens (<strong>shares</strong>) in the SY contract to redeem to output token $i$ (<em>tokenOut</em>). This pattern is similar to UniswapV2 which allows for more gas efficient ways to interact with the contract. If <em>burnFromInternalBalance</em> is set to <em>true</em>, then this function will burn <em>amountSharesToRedeem</em> $d_s$ of SY tokens directly from the user to redeem to output token $i$ (<em>tokenOut</em>).</p> <p>This function should revert if $amountTokenOut \lt minTokenOut$.</p> <ul> <li><strong>MUST</strong> emit the <code>Redeem</code> event.</li> <li><strong>MUST</strong> support ERC-20’s <code>approve</code> / <code>transferFrom</code> flow where the shares are burned from receiver directly (as msg.sender) or if the msg.sender has ERC-20 approved allowance over the shares of the receiver.</li> <li><strong>MUST</strong> revert if $amountTokenOut \lt minTokenOut$ (due to redeem limit being reached, slippage, or the user not approving enough <code>amountSharesToRedeem</code> to the SY contract, etc).</li> </ul> <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"> exchangeRate</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"> res</span><span>)</span><span>;</span></span></code></pre> <p>This method updates and returns the latest <strong>exchange rate</strong>, which is the <strong>exchange rate</strong> from SY token amount into asset amount, scaled by a fixed scaling factor of 1e18.</p> <ul> <li><strong>MUST</strong> return $ExchangeRate(t_{now})$ such that $ExchangeRate(t_{now}) \times syBalance / 1e18 = assetBalance$.</li> <li><strong>MUST NOT</strong> include fees that are charged against the underlying yield token in the SY contract.</li> </ul> <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"> getTokensIn</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 class="z-variable"> res</span><span>)</span><span>;</span></span></code></pre> <p>This read-only method returns the list of all input tokens that can be used to deposit into the SY contract.</p> <ul> <li><strong>MUST</strong> return ERC-20 token addresses.</li> <li><strong>MUST</strong> return at least one address.</li> <li><strong>MUST NOT</strong> revert.</li> </ul> <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"> getTokensOut</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 class="z-variable"> res</span><span>)</span><span>;</span></span></code></pre> <p>This read-only method returns the list of all output tokens that can be converted into when exiting the SY contract.</p> <ul> <li><strong>MUST</strong> return ERC-20 token addresses.</li> <li><strong>MUST</strong> return at least one address.</li> <li><strong>MUST NOT</strong> revert.</li> </ul> <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"> yieldToken</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></code></pre> <p>This read-only method returns the underlying yield-bearing token (representing a GYGP) address.</p> <ul> <li><strong>MUST</strong> return a token address that conforms to the ERC-20 interface, or zero address</li> <li><strong>MUST NOT</strong> revert.</li> <li><strong>MUST</strong> reflect the exact underlying yield-bearing token address if the SY token is a wrapped token.</li> <li><strong>MAY</strong> return 0x or zero address if the SY token is natively implemented, and not from wrapping.</li> </ul> <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"> previewDeposit</span><span>(</span><span class="z-support">address</span><span class="z-variable"> tokenIn</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amountTokenToDeposit</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"> amountSharesOut</span><span>)</span><span>;</span></span></code></pre> <p>This read-only method returns the amount of shares that a user would have received if they deposit <em>amountTokenToDeposit</em> of <em>tokenIn</em>.</p> <ul> <li><strong>MUST</strong> return less than or equal of <em>amountSharesOut</em> to the actual return value of the <code>deposit</code> method, and <strong>SHOULD NOT</strong> return greater than the actual return value of the <code>deposit</code> method.</li> <li><strong>SHOULD ONLY</strong> revert if minting SY token with the entered parameters is forbidden (e.g. exceeding supply cap).</li> </ul> <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"> previewRedeem</span><span>(</span><span class="z-support">address</span><span class="z-variable"> tokenOut</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amountSharesToRedeem</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"> amountTokenOut</span><span>)</span><span>;</span></span></code></pre> <p>This read-only method returns the amount of <em>tokenOut</em> that a user would have received if they redeem <em>amountSharesToRedeem</em> of <em>tokenOut</em>.</p> <ul> <li><strong>MUST</strong> return less than or equal of <em>amountTokenOut</em> to the actual return value of the <code>redeem</code> method, and <strong>SHOULD NOT</strong> return greater than the actual return value of the <code>redeem</code> method.</li> <li><strong>SHOULD ONLY</strong> revert if burning SY token with the entered parameters is forbidden.</li> </ul> <h4 id="events">Events</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"> 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"> caller</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"> receiver</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"> tokenIn</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amountDeposited</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amountSyOut</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre> <p><code>caller</code> has converted exact <em>tokenIn</em> tokens into SY (shares) and transferred those SY to <code>receiver</code>.</p> <ul> <li><strong>MUST</strong> be emitted when input tokens are deposited into the SY contract via <code>deposit</code> method.</li> </ul> <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> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> caller</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"> receiver</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"> tokenOut</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amountSyToRedeem</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amountTokenOut</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre> <p><code>caller</code> has converted exact SY (shares) into input tokens and transferred those input tokens to <code>receiver</code>.</p> <ul> <li><strong>MUST</strong> be emitted when input tokens are redeemed from the SY contract via <code>redeem</code> method.</li> </ul> <p><strong>"SY" Word Choice:</strong></p> <p>"SY" (pronunciation: <em>/sʌɪ/</em>), an abbreviation of Standardized Yield, was found to be appropriate to describe a broad universe of standardized composable yield-bearing digital assets.</p> <h2 id="rationale">Rationale</h2> <p><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> is enforced because implementation details such as transfer, token approvals, and balance calculation directly carry over to the SY tokens. This standardization makes the SY tokens immediately compatible with all ERC-20 use cases.</p> <p><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> can optionally be implemented should you want integrations to detect the IStandardizedYield interface implementation.</p> <p><a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a> can optionally be implemented in order to improve the UX of approving SY tokens on various integrations.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC is fully backwards compatible as its implementation extends the functionality of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, however the optional metadata extensions, namely <code>name</code>, <code>decimals</code>, and <code>symbol</code> semantics MUST be implemented for all SY token implementations.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Malicious implementations which conform to the interface can put users at risk. It is recommended that all integrators (such as wallets, aggregators, or other smart contract protocols) review the implementation to avoid possible exploits and users losing funds.</p> <p><code>yieldToken</code> must strongly reflect the address of the underlying wrapped yield-bearing token. For a native implementation wherein the SY token does not wrap a yield-bearing token, but natively represents a GYGP share, then the address returned MAY be a zero address. Otherwise, for wrapped tokens, you may introduce confusion on what the SY token represents, or may be deemed malicious.</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-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Yale ReiSoleilhttps://github.com/longnshort dRadianthttps://github.com/dRadiant D Wang PhDdavid@iob.fi https://wg-eips.ritovision.com/5173/

A multigenerational reward mechanism that rewards‌ all ‌owners of non-fungible tokens (NFT).

<h2 id="abstract">Abstract</h2> <p>This proposal introduces the Non-Fungible Future Rewards (nFR) framework, extending <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens (NFTs) features to let token holders benefit from value appreciation after transferring ownership. By integrating cooperative game theory, it aligns stakeholder incentives, addressing inefficiencies in asset transactions. The framework fosters collaboration, transparency, and equitable profit sharing. It improves equity and efficiency, recognizes all ownership stages, and establishes a cooperative asset transaction model.</p> <h2 id="motivation">Motivation</h2> <p>Traditional financial markets are often characterized by inefficiencies, opaque practices, and systemic imbalances, resulting in significant disadvantages for the majority of participants. Although blockchain technology offers transaction transparency, current implementations do not adequately facilitate equitable value sharing or participant alignment. This proposal addresses these gaps by introducing structured collaboration and a fair compensation system, ensuring equitable rewards for contributions to asset value.</p> <h3 id="framework-components">Framework Components</h3> <h4 id="the-flow-mechanism">The Flow mechanism</h4> <p>Each <a href="https://wg-eips.ritovision.com/5173/">ERC-5173</a> token maintains an immutable record of ownership and price transitions, creating a dedicated network of historical token owners. This unique community collaborates to generate additional value and maintains vested interest in the project or token even after selling, ensuring contributors benefit from the asset's appreciation. This mechanism promotes collaborative value creation, equitable profit sharing, and a connected financial ecosystem, distinct from traditional financial market systems.</p> <h4 id="cooperative-value-future-rewards-distribution">Cooperative Value (Future Rewards) Distribution</h4> <p>The nFR framework transforms the zero-sum financial equation:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>P(A) + P(B) + F ≤ 0</span></span></code></pre> <p>Where:</p> <ul> <li>P(A): Profit of trader A</li> <li>P(B): Profit of trader B</li> <li>F: Transaction fees, friction costs, and operational expenses</li> </ul> <p>into a collaborative model:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>P(A) + P(B) + F + FR &gt; 0</span></span></code></pre> <p>Where:</p> <ul> <li>FR: Shared value creation through cooperative mechanisms</li> </ul> <p>This model incentivizes fairness and rewards contributions throughout the asset lifecycle.</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 following is an extension of the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard.</p> <p><a href="https://wg-eips.ritovision.com/721/">ERC-721</a>-compliant contracts MAY implement this EIP for rewards to provide a standard method of rewarding future buyers and previous owners with realized profits in the future.</p> <p>Implementers of this standard MUST have all of the following functions:</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.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/utils/introspection/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-comment"> * @dev Interface for the Future Rewards Token Standard.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * A standardized way to receive future rewards for non-fungible tokens (NFTs.)</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"> IERC5173</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-storage z-type"> event</span><span class="z-entity z-name"> FRClaimed</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 class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> amount</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"> FRDistributed</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-storage z-type"> indexed</span><span class="z-variable"> soldPrice</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> allocatedFR</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"> Listed</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-storage z-type"> indexed</span><span class="z-variable"> salePrice</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"> Unlisted</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-storage z-type"> event</span><span class="z-entity z-name"> Bought</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-storage z-type"> indexed</span><span class="z-variable"> salePrice</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"> list</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"> salePrice</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"> unlist</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-storage z-type"> function</span><span class="z-entity z-name"> buy</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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> releaseFR</span><span>(</span><span class="z-support">address</span><span class="z-variable"> payable</span><span class="z-variable"> account</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"> retrieveFRInfo</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">uint8</span><span>,</span><span class="z-support"> uint256</span><span>,</span><span class="z-support"> uint256</span><span>,</span><span class="z-support"> uint256</span><span>,</span><span class="z-support"> uint256</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-storage z-type"> function</span><span class="z-entity z-name"> retrieveAllottedFR</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-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"> retrieveListInfo</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">uint256</span><span>,</span><span class="z-support"> address</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></span> <span class="giallo-l"></span></code></pre> <p>An nFR contract MUST implement and update for each Token ID. The data in the <code>FRInfo</code> struct MAY either be stored wholly in a single mapping, or MAY be broken down into several mappings. The struct MUST either be exposed in a public mapping or mappings, or MUST have public functions that access the private data. This is for client-side data fetching and verification.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> FRInfo</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> numGenerations</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Number of generations corresponding to that Token ID</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> percentOfProfit</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Percent of profit allocated for FR, scaled by 1e18</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> successiveRatio</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> The common ratio of successive in the geometric sequence, used for distribution calculation</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> lastSoldPrice</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Last sale price in ETH mantissa</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> ownerAmount</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Amount of owners the Token ID has seen</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span> addressesInFR</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> The addresses currently in the FR cycle</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"> ListInfo</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> salePrice</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> ETH mantissa of the listed selling price</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> lister</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Owner/Lister of the Token</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> isListed</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Boolean indicating whether the Token is listed or not</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre> <p>Additionally, an nFR smart contract MUST store the corresponding <code>ListInfo</code> for each Token ID in a mapping. A method to retrieve a Token ID’s corresponding <code>ListInfo</code> MUST also be accessible publicly.</p> <p>An nFR smart contract MUST also store and update the amount of Ether allocated to a specific address using the <code>_allotedFR</code> mapping. The <code>_allottedFR</code> mapping MUST either be public or have a function to fetch the FR payment allotted to a specific address.</p> <h3 id="percent-fixed-point">Percent Fixed Point</h3> <p>The <code>allocatedFR</code> MUST be calculated using a percentage fixed point with a scaling factor of 1e18 (X/1e18) - such as "5e16" - for 5%. This is REQUIRED to maintain uniformity across the standard. The max and min values would be - 1e18 - 1.</p> <h3 id="default-fr-info">Default FR Info</h3> <p>A default <code>FRInfo</code> MUST be stored in order to be backward compatible with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> mint functions. It MAY also have a function to update the <code>FRInfo</code>, assuming it has not been hard-coded.</p> <h3 id="erc-721-overrides">ERC-721 Overrides</h3> <p>An nFR-compliant smart contract MUST override the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> <code>_mint</code>, <code>_transfer</code>, and <code>_burn</code> functions. When overriding the <code>_mint</code> function, a default FR model is REQUIRED to be established if the mint is to succeed when calling the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> <code>_mint</code> function and not the nFR <code>_mint</code> function. It is also to update the owner amount and directly add the recipient address to the FR cycle. When overriding the <code>_transfer</code> function, the smart contract SHALL consider the NFT as sold for 0 ETH, and update the state accordingly after a successful transfer. This is to prevent FR circumvention. Additionally, the <code>_transfer</code> function SHALL prevent the caller from transferring the token to themselves or an address that is already in the FR sliding window, this can be done through a require statement that ensures that the sender or an address in the FR sliding window is not the recipient, otherwise, it’d be possible to fill up the FR sequence with one’s own address or duplicate addresses. Finally, when overriding the <code>_burn</code> function, the smart contract SHALL delete the <code>FRInfo</code> and <code>ListInfo</code> corresponding to that Token ID after a successful burn.</p> <p>Additionally, the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> <code>_checkOnERC721Received</code> function MAY be explicitly called after mints and transfers if the smart contract aims to have safe transfers and mints.</p> <h3 id="safe-transfers">Safe Transfers</h3> <p>If the wallet/broker/auction application will accept safe transfers, then it MUST implement the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> wallet interface.</p> <h3 id="listing-unlisting-and-buying">Listing, Unlisting, and Buying</h3> <p>The <code>list</code>, <code>unlist</code>, and <code>buy</code> functions MUST be implemented, as they provide the capability to sell a token.</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"> list</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"> salePrice</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-comment"> //</span><span class="z-comment">...</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">function</span><span class="z-entity z-name"> unlist</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-comment"> //</span><span class="z-comment">...</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"> buy</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 class="z-storage z-type"> payable</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">...</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre> <p>The <code>list</code> function accepts a <code>tokenId</code> and a <code>salePrice</code> and updates the corresponding <code>ListInfo</code> for that given <code>tokenId</code> after ensuring that the <code>msg.sender</code> is either approved or the owner of the token. The <code>list</code> function SHOULD emit the <code>Listed</code> event. The function signifies that the token is listed and at what price it is listed for.</p> <p>The <code>unlist</code> function accepts a <code>tokenId</code> and it deletes the corresponding <code>ListInfo</code> after the owner verifications have been met. The <code>unlist</code> function SHOULD emit the <code>Unlisted</code> event.</p> <p>The <code>buy</code> function accepts a <code>tokenId</code> and MUST be payable. It MUST verify that the <code>msg.value</code> matches the token’s <code>salePrice</code> and that the token is listed, before proceeding and calling the FR <code>_transferFrom</code> function. The function MUST also verify that the buyer is not already in the FR sliding window. This is to ensure the values are valid and will also allow for the necessary FR to be held in the contract. The <code>buy</code> function SHOULD emit the <code>Bought</code> event.</p> <h3 id="future-rewards-transferfrom-function">Future Rewards <code>_transferFrom</code> Function</h3> <p>The FR <code>_transferFrom</code> function MUST be called by all nFR-supporting smart contracts, though the accommodations for non-nFR-supporting contracts MAY also be implemented to ensure backwards compatibility.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></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"> tokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> soldPrice</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 class="z-storage z-type"> payable</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">...</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre> <p>Based on the stored <code>lastSoldPrice</code>, the smart contract will determine whether the sale was profitable after calling the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> transfer function and transferring the NFT. If it was not profitable, the smart contract SHALL update the last sold price for the corresponding Token ID, increment the owner amount, shift the generations, and transfer all of the <code>msg.value</code> to the <code>lister</code> depending on the implementation. Otherwise, if the transaction was profitable, the smart contract SHALL call the <code>_distributeFR</code> function, then update the <code>lastSoldPrice</code>, increment the owner amount, and finally shift generations. The <code>_distributeFR</code> function or the FR <code>_transferFrom</code> MUST return the difference between the allocated FR that is to be distributed amongst the <code>_addressesInFR</code> and the <code>msg.value</code> to the <code>lister</code>. Once the operations have completed, the function MUST clear the corresponding <code>ListInfo</code>. Similarly to the <code>_transfer</code> override, the FR <code>_transferFrom</code> SHALL ensure that the recipient is not the sender of the token or an address in the FR sliding window.</p> <h3 id="future-rewards-calculation">Future Rewards Calculation</h3> <p>Marketplaces that support this standard MAY implement various methods of calculating or transferring Future Rewards to the previous owners.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> _calculateFR</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> totalProfit</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> buyerReward</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> successiveRatio</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> ownerAmount</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> windowSize</span><span>)</span><span class="z-storage z-type"> pure</span><span class="z-storage z-type"> internal</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 class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">... </span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre> <p>In this example (<em>Figure 1</em>), a seller is REQUIRED to share a portion of their net profit with 10 previous holders of the token. Future Rewards will also be paid to the same seller as the value of the token increases from up to 10 subsequent owners.</p> <p>When an owner loses money during their holding period, they MUST NOT be obligated to share Future Rewards distributions, since there is no profit to share. However, he SHALL still receive a share of Future Rewards distributions from future generations of owners, if they are profitable.</p> <p><img src="https://wg-eips.ritovision.com/5173/./assets/Total_FR_Payout_Distribution-geo.png" alt="Figure 1: Geometric sequence distribution" /></p> <p><em>Figure 1: Geometric sequence distribution</em></p> <p>The buyers/owners receive a portion ( r ) of the realized profit (P ) from an NFT transaction. The remaining proceeds go to the seller.</p> <p>As a result of defining a sliding window mechanism ( n ), we can determine which previous owners will receive distributions. The owners are arranged in a queue, starting with the earliest owner and ending with the owner immediately before the current owner (the Last Generation). The First Generation is the last of the next n generations. There is a fixed-size profit distribution window from the First Generation to the Last Generation.</p> <p>The profit distribution SHALL be only available to previous owners who fall within the window.</p> <p>In this example, there SHALL be a portion of the proceeds awarded to the Last Generation owner (the owner immediately prior to the current seller) based on the geometric sequence in which profits are distributed. The larger portion of the proceeds SHALL go to the Mid-Gen owners, the earlier the greater, until the last eligible owner is determined by the sliding window, the First Generation. Owners who purchase earlier SHALL receive a greater reward, with first-generation owners receiving the greatest reward.</p> <h3 id="future-rewards-distribution">Future Rewards Distribution</h3> <p><img src="https://wg-eips.ritovision.com/5173/./assets/nFR_Standard_Outline.jpeg" alt="Figure 2: NFT Owners&#39; Future Rewards (nFR)" /></p> <p><em>Figure 2: NFT Owners' Future Rewards (nFR)</em></p> <p><em>Figure 2</em> illustrates an example of a five-generation Future Rewards Distribution program based on an owner's realized profit.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> _distributeFR</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"> soldPrice</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-comment"> //</span><span class="z-comment">...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> FRDistributed</span><span>(</span><span>tokenId</span><span>,</span><span> soldPrice</span><span>,</span><span> allocatedFR</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span></code></pre> <p>The <code>_distributeFR</code> function MUST be called in the FR <code>_transferFrom</code> function if there is a profitable sale. The function SHALL determine the addresses eligible for FR, which would essentially be, excluding the last address in <code>addressesInFR</code> in order to prevent any address from paying itself. If the function determines there are no addresses eligible, i.e., it is the first sale, then it SHALL either <code>return 0</code> if <code>_transferFrom</code> is handling FR payment or send <code>msg.value</code> to the <code>lister</code>. The function SHALL calculate the difference between the current sale price and the <code>lastSoldPrice</code>, then it SHALL call the <code>_calculateFR</code> function to receive the proper distribution of FR. Then it SHALL distribute the FR accordingly, making order adjustments as necessary. Then, the contract SHALL calculate the total amount of FR that was distributed (<code>allocatedFR</code>), in order to return the difference of the <code>soldPrice</code> and <code>allocatedFR</code> to the <code>lister</code>. Finally, it SHALL emit the <code>FRDistributed</code> event. Additionally, the function MAY return the allocated FR, which would be received by the FR <code>_transferFrom</code> function, if the <code>_transferFrom</code> function is sending the <code>allocatedFR</code> to the <code>lister</code>.</p> <h3 id="future-rewards-claiming">Future Rewards Claiming</h3> <p>The future Rewards payments SHOULD utilize a pull-payment model, similar to that demonstrated by OpenZeppelin with their PaymentSplitter contract. The event FRClaimed would be triggered after a successful claim has been made.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> releaseFR</span><span>(</span><span class="z-support">address</span><span class="z-variable"> payable</span><span class="z-variable"> account</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-comment"> //</span><span class="z-comment">...</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h3 id="owner-generation-shifting">Owner Generation Shifting</h3> <p>The <code>_shiftGenerations</code> function MUST be called regardless of whether the sale was profitable or not. As a result, it will be called in the <code>_transfer</code> <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> override function and the FR <code>transferFrom</code> function. The function SHALL remove the oldest account from the corresponding <code>_addressesInFR</code> array. This calculation will take into account the current length of the array versus the total number of generations for a given token ID.</p> <h2 id="rationale">Rationale</h2> <h3 id="fixed-percentage-to-10-18">Fixed Percentage to 10^18</h3> <p>Considering Fixed-Point Arithmetic is to be enforced, it is logical to have 1e18 represent 100% and 1e16 represent 1% for Fixed-Point operations. This method of handling percents is also commonly seen in many Solidity libraries for Fixed-Point operations.</p> <h3 id="emitting-event-for-payment">Emitting Event for Payment</h3> <p>Since each NFT contract is independent, and while a marketplace contract can emit events when an item is sold, choosing to emit an event for payment is important. As the royalty and FR recipient may not be aware of/watching for a secondary sale of their NFT, they would never know that they received a payment except that their ETH wallet has been increased randomly.</p> <p>The recipient of the secondary sale will therefore be able to verify that the payment has been received by calling the parent contract of the NFT being sold, as implemented in <a href="https://wg-eips.ritovision.com/2981/">ERC-2981</a>.</p> <h3 id="number-of-generations-of-all-owners-n-vs-number-of-generations-of-only-profitable-owners">Number of Generations of All Owners ( n ) vs Number of Generations of Only Profitable Owners</h3> <p>It is the number of generations of all owners, not just those who are profitable, that determines the number of owners from which the subsequent owners' profits will be shared, see <em>Figure 3</em>. As part of the effort to discourage "ownership hoarding," Future Rewards distributions will not be made to the current owner/purchaser if all the owners lose money holding the NFT. Further information can be found under Security Considerations.</p> <p><img src="https://wg-eips.ritovision.com/5173/./assets/Losing_owners.jpeg" alt="Figure 3: Losing owners" /></p> <p><em>Figure 3: Losing owners</em></p> <h3 id="single-vs-multigenerations">Single vs Multigenerations</h3> <p>In a single generation reward, the new buyer/owner receives a share of the next single generation's realized profit only. In a multigenerational reward system, buyers will have future rewards years after their purchase. The NFT should have a long-term growth potential and a substantial dividend payout would be possible in this case.</p> <p>We propose that the marketplace operator can choose between a single generational distribution system and a multigenerational distribution system.</p> <h3 id="direct-fr-payout-by-the-seller-vs-smart-contract-managed-payout">Direct FR Payout by the Seller vs Smart Contract-managed Payout</h3> <p>FR payouts directly derived from the sale proceeds are immediate and final. As part of the fraud detection detailed later in the Security Considerations section, we selected a method in which the smart contract calculates all the FR amounts for each generation of previous owners, and handles payout according to other criteria set by the marketplace, such as reduced or delayed payments for wallet addresses with low scores, or a series of consecutive orders detected using a time-heuristic analysis.</p> <h3 id="equal-vs-linear-reward-distributions">Equal vs Linear Reward Distributions</h3> <h4 id="equal-fr-payout">Equal FR Payout</h4> <p><img src="https://wg-eips.ritovision.com/5173/./assets/Total_FR_Payout_Distribution-flat.png?raw=true" alt="Figure 4: Equal, linear reward distribution" /></p> <p><em>Figure 4: Equal, linear reward distribution</em></p> <p>FR distributions from the realization of profits by later owners are distributed equally to all eligible owners (<em>Figure 4</em>). The exponential reward curve, however, may be more desirable, as it gives a slightly larger share to the newest buyer. Additionally, this distribution gives the earliest generations the largest portions as their FR distributions near the end, so they receive higher rewards for their early involvement, but the distribution is not nearly as extreme as one based on arithmetic sequences (<em>Figure 5</em>).</p> <p>This system does not discriminate against any buyer because each buyer will go through the same distribution curve.</p> <h4 id="straight-line-arithmetic-sequence-fr-payout">Straight line arithmetic sequence FR payout</h4> <p><img src="https://wg-eips.ritovision.com/5173/./assets/Arithmetic_Sequence_FR_Payout_Distribution.png?raw=true" alt="Figure 5: Arithmetic sequence distribution" /></p> <p><em>Figure 5: Arithmetic sequence distribution</em></p> <p>The profit is distributed according to the arithmetic sequence, which is 1, 2, 3, ... and so on. The first owner will receive 1 portion, the second owner will receive 2 portions, the third owner will receive 3 portions, etc.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully compatible with current <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standards and <a href="https://wg-eips.ritovision.com/2981/">ERC-2981</a>. It can also be easily adapted to work with <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>.</p> <h2 id="test-cases">Test Cases</h2> <p><a href="https://wg-eips.ritovision.com/5173/./assets/Implementation/nFRImplementation.sol">This contract</a> contains the reference implementation for this proposal.</p> <p><a href="https://wg-eips.ritovision.com/5173/./assets/animate-1920x1080-1750-frames.gif?raw=true">Here is a visualization of the test case</a>.</p> <p>As a result of implementing ERC-5173, a new project has been launched called untrading.org.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>This implementation uses OpenZeppelin contracts and the PRB Math library created by Paul R Berg for fixed-point arithmetic. It demonstrates the interface for the nFR standard, an nFR standard-compliant extension, and an <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> implementation using the extension.</p> <p>The code for the reference implementation is <a href="https://wg-eips.ritovision.com/5173/./assets/Implementation/nFRImplementation.sol">here</a>.</p> <h3 id="distribution-of-nft-royalties-to-artists-and-creators">Distribution of NFT Royalties to Artists and Creators</h3> <p>We agree that artists’ royalties should be uniform and on-chain. We support <a href="https://wg-eips.ritovision.com/2981/">ERC-2981</a> NFT royalty Standard proposal.</p> <p>All platforms can support royalty rewards for the same NFT based on on-chain parameters and functions:</p> <ul> <li>No profit, no profit sharing, no cost;</li> <li>The question of "who owned it" is often crucial to the provenance and value of a collectible;</li> <li>The previous owner should be re-compensated for their ownership;</li> <li>And the buyer/owner incentive in FR eliminates any motive to circumvent the royalty payout schemes;</li> </ul> <h3 id="distribution-of-nft-owners-future-rewards-frs">Distribution of NFT Owners’ Future Rewards (FRs)</h3> <h4 id="future-rewards-calculation-1">Future Rewards calculation</h4> <p>Any realized profits (P) when an NFT is sold are distributed among the buyers/owners. The previous owners will take a fixed portion of the profit (P), and this portion is called Future Rewards (FRs). The seller takes the rest of the profits.</p> <p>We define a sliding window mechanism to decide which previous owners will be involved in the profit distribution. Let's imagine the owners as a queue starting from the first hand owner to the current owner. The profit distribution window starts from the previous owner immediately to the current owner and extends towards the first owner, and the size of the windows is fixed. Only previous owners located inside the window will join the profit distribution.</p> <p><img src="https://wg-eips.ritovision.com/5173/./assets/nFR_distribution_formula.jpg?raw=true" alt="Future Rewards calculation formula" /></p> <p>In this equation:</p> <ul> <li>P is the total profit, the difference between the selling price minus the buying price;</li> <li><em>R</em> is buyer reward ratio of the total P;</li> <li><em>g</em> is the common ratio of successive in the geometric sequence;</li> <li><em>n</em> is the actual number of owners eligible and participating in the future rewards sharing. To calculate <em>n</em>, we have <em>n</em> = min(<em>m</em>, <em>w</em>), where <em>m</em> is the current number of owners for a token, and <em>w</em> is the window size of the profit distribution sliding window algorithm</li> </ul> <h4 id="converting-into-code">Converting into Code</h4> <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.0</span><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"> Assumes usage of a Fixed Point Arithmetic library (prb-math) for both int256 and uint256, and OpenZeppelin Math utils for Math.min. </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"> _calculateFR</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> p</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> g</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> m</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> w</span><span>)</span><span class="z-storage z-type"> pure</span><span class="z-storage z-type"> internal</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 class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> n </span><span class="z-keyword">=</span><span> Math</span><span>.</span><span class="z-entity z-name">min</span><span>(</span><span>m</span><span>,</span><span> w</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> FR </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> uint256</span><span>[](</span><span class="z-variable">n</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint256</span><span> i </span><span class="z-keyword">=</span><span class="z-constant"> 1</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> n </span><span class="z-keyword">+</span><span class="z-constant"> 1</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"> uint256</span><span> pi </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-keyword"> if</span><span> (</span><span>successiveRatio </span><span class="z-keyword">!=</span><span class="z-constant"> 1e18</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> int256</span><span> v1 </span><span class="z-keyword">=</span><span class="z-constant"> 1e18</span><span class="z-keyword"> -</span><span class="z-support"> int256</span><span>(</span><span>g</span><span>)</span><span>.</span><span class="z-entity z-name">powu</span><span>(</span><span>n</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> int256</span><span> v2 </span><span class="z-keyword">=</span><span class="z-support"> int256</span><span>(</span><span>g</span><span>)</span><span>.</span><span class="z-entity z-name">powu</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-support"> int256</span><span> v3 </span><span class="z-keyword">=</span><span class="z-support"> int256</span><span>(</span><span>p</span><span>)</span><span>.</span><span class="z-entity z-name">mul</span><span>(</span><span class="z-support">int256</span><span>(</span><span>r</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> int256</span><span> v4 </span><span class="z-keyword">=</span><span> v3</span><span>.</span><span class="z-entity z-name">mul</span><span>(</span><span class="z-constant">1e18</span><span class="z-keyword"> -</span><span class="z-support"> int256</span><span>(</span><span>g</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> pi </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span>v4 </span><span class="z-keyword">*</span><span> v2 </span><span class="z-keyword">/</span><span> v1</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> pi </span><span class="z-keyword">=</span><span> p</span><span>.</span><span class="z-entity z-name">mul</span><span>(</span><span>r</span><span>)</span><span>.</span><span class="z-entity z-name">div</span><span>(</span><span>n</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> FR</span><span>[</span><span>i </span><span class="z-keyword">-</span><span class="z-constant"> 1</span><span>]</span><span class="z-keyword"> =</span><span> pi</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> FR</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre> <p>The complete implementation code can be found <a href="https://wg-eips.ritovision.com/5173/./assets/Implementation/nFRImplementation.sol">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="payment-attacks">Payment Attacks</h3> <p>As this ERC introduces royalty and realized profit rewards collection, distribution, and payouts to the ERC-721 standard, the attack vectors increase. As discussed by Andreas Freund regarding mitigations to phishing attacks, we recommend reentrancy protection for all payment functions to reduce the most significant attack vectors for payments and payouts.</p> <h3 id="royalty-circumventing">Royalty Circumventing</h3> <p>Many methods are being used to avoid paying royalties to creators under the current <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard. Through an under-the-table transaction, the new buyer's cost basis will be reduced to zero, increasing their FR liability to the full selling price. Everyone, either the buyer or seller, would pay a portion of the previous owner's net realized profits ( P x r ). Acting in his or her own interests, the buyer rejects any loyalty circumventing proposal.</p> <h3 id="fr-hoarding-through-wash-sales">FR Hoarding through Wash Sales</h3> <p>Quantexa blog and beincrypto articles have reported widespread wash trading on all unregulated cryptocurrency trading platforms and NFT marketplaces. The use of wash trading by dishonest actors can lead to an unfair advantage, as well as inflated prices and money laundering. When a single entity becomes multiple generations of owners to accumulate more rewards in the future, the validity of the system is undermined.</p> <h4 id="wash-trading-by-users">Wash trading by users</h4> <p>Using a different wallet address, an attacker can "sell" the NFT to themselves at a loss. It is possible to repeat this process n times in order to maximize their share of the subsequent FR distributions (<em>Figure 6</em>). A wallet ranking score can partially alleviate this problem. It is evident that a brand new wallet is a red flag, and the marketplace may withhold FR distribution from it if it has a short transaction history (i.e. fewer than a certain number of transactions).</p> <p>We do not want a large portion of future rewards to go to a small number of wash traders. Making such practices less profitable is one way to discourage wash trading and award hoarding. It can be partially mitigated, for example, by implementing a wallet-score and holding period-based incentive system. The rewards for both parties are reduced if a new wallet is used or if a holding period is less than a certain period.</p> <p><img src="https://wg-eips.ritovision.com/5173/./assets/Same_owner_using_different_wallets.jpeg" alt="Figure 6: Same owner using different wallets" /></p> <p><em>Figure 6: Same owner using different wallets</em></p> <h4 id="wash-trading-by-the-marketplace-operator">Wash trading by the marketplace operator</h4> <p>However, the biggest offender appears to be the marketplace, which engages heavily in wash trading, or simply does not care about it, according to Decrypt. The authors have personally experienced this phenomenon. A senior executive of a top-5 cryptocurrency exchange boasted during a mid-night drinking session in 2018, that they had "brushed" (wash-traded) certain newly listed tokens, which they called "marketmaking." The exchange is still ranked among the top five crypto exchanges today.</p> <p>Many of these companies engage in wash trading on their own or collude with certain users, and royalties and FR payments are reimbursed under the table. It is crucial that all exchanges have robust features to prevent self-trading. Users should be able to observe watchers transparently. Marketplaces should provide their customers with free access to an on-chain transaction monitoring service like Chainalysis Reactor.</p> <h3 id="long-cyclical-fr-entitled-owner-generations">Long/Cyclical FR-Entitled Owner Generations</h3> <p>In most cases, malicious actors will create excessively long or cyclical Future Rewards Owner Generations that will result in applications that attempt to distribute FR or shift generations running out of gas and not functioning. Therefore, clients are responsible for verifying that the contract with which they interact has an appropriate number of generations, so that looping over will not deplete the gas.</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-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jameshttps://github.com/JamesSmartCell Weiwuhttps://github.com/weiwu-zhang https://wg-eips.ritovision.com/5169/

Add a scriptURI to point to an executable script associated with the functionality of the token.

<h2 id="abstract">Abstract</h2> <p>This EIP provides a contract interface adding a <code>scriptURI()</code> function for locating executable scripts associated with the token.</p> <h2 id="motivation">Motivation</h2> <p>Often, smart contract authors want to provide some user functionality to their tokens through client scripts. The idea is made popular with function-rich NFTs. It's important that a token's contract is linked to its client script, since the client script may carry out trusted tasks such as creating transactions for the user.</p> <p>This EIP allows users to be sure they are using the correct script through the contract by providing a URI to an official script, made available with a call to the token contract itself (<code>scriptURI</code>). This URI can be any RFC 3986-compliant URI, such as a link to an IPFS multihash, GitHub gist, or a cloud storage provider. Each contract implementing this EIP implements a <code>scriptURI</code> function which returns the download URI to a client script. The script provides a client-side executable to the hosting token. Examples of such a script could be:</p> <ul> <li>A 'miniDapp', which is a cut-down DApp tailored for a single token.</li> <li>A 'TokenScript' which provides TIPS from a browser wallet.</li> <li>A 'TokenScript' that allows users to interact with contract functions not normally provided by a wallet, eg 'mint' function.</li> <li>An extension that is downloadable to the hardware wallet with an extension framework, such as Ledger.</li> <li>JavaScript instructions to operate a smartlock, after owner receives authorization token in their wallet.</li> </ul> <h3 id="overview">Overview</h3> <p>With the discussion above in mind, we outline the solution proposed by this EIP. For this purpose, we consider the following variables:</p> <ul> <li> <p><code>SCPrivKey</code>: The private signing key to administrate a smart contract implementing this EIP. Note that this doesn't have to be a new key especially added for this EIP. Most smart contracts made today already have an administration key to manage the tokens issued. It can be used to update the <code>scriptURI</code>.</p> </li> <li> <p><code>newScriptURI</code>: an array of URIs for different ways to find the client script.</p> </li> </ul> <p>We can describe the life cycle of the <code>scriptURI</code> functionality:</p> <ul> <li>Issuance</li> </ul> <ol> <li>The token issuer issues the tokens and a smart contract implementing this EIP, with the admin key for the smart contract being <code>SCPrivKey</code>.</li> <li>The token issuer calls <code>setScriptURI</code> with the <code>scriptURI</code>.</li> </ol> <ul> <li>Update <code>scriptURI</code></li> </ul> <ol> <li>The token issuer stores the desired <code>script</code> at all the new URI locations and constructs a new <code>scriptURI</code> structure based on this.</li> <li>The token issuer calls <code>setScriptURI</code> with the new <code>scriptURI</code> structure.</li> </ol> <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>We define a scriptURI element using the <code>string[]</code>. Based on this, we define the smart contract interface 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"> IERC5169</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 event emits when the scriptURI is updated, </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> so wallets implementing this interface can update a cached script</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ScriptUpdate</span><span>(</span><span class="z-support">string</span><span>[</span><span>]</span><span class="z-variable"> newScriptURI</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 scriptURI for 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"> The</span><span class="z-comment"> scriptURI</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> scriptURI</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"> Update the scriptURI </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> emits event ScriptUpdate(scriptURI memory newScriptURI);</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setScriptURI</span><span>(</span><span class="z-support">string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> newScriptURI</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 interface MUST be implemented under the following constraints:</p> <ul> <li> <p>The smart contract implementing <code>IERC5169</code> MUST store variables <code>address owner</code> in its state.</p> </li> <li> <p>The smart contract implementing <code>IERC5169</code> MUST set <code>owner=msg.sender</code> in its constructor.</p> </li> <li> <p>The <code>ScriptUpdate(...)</code> event MUST be emitted when the <code>setScriptURI</code> function updates the <code>scriptURI</code>.</p> </li> <li> <p>The <code>setScriptURI(...)</code> function MUST validate that <code>owner == msg.sender</code> <em>before</em> executing its logic and updating any state.</p> </li> <li> <p>The <code>setScriptURI(...)</code> function MUST update its internal state such that <code>currentScriptURI = newScriptURI</code>.</p> </li> <li> <p>The <code>scriptURI()</code> function MUST return the <code>currentScriptURI</code> state.</p> </li> <li> <p>The <code>scriptURI()</code> function MAY be implemented as pure or view.</p> </li> <li> <p>Any user of the script learned from <code>scriptURI</code> MUST validate the script is either at an immutable location, its URI contains its hash digest, or it implements the separate <code>Authenticity for Client Script</code> EIP, which asserts authenticity using signatures instead of a digest.</p> </li> </ul> <h2 id="rationale">Rationale</h2> <p>This method avoids the need for building secure and certified centralized hosting and allows scripts to be hosted anywhere: IPFS, GitHub or cloud storage.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is backwards-compatible with most existing token standards, including the following commonly-used ones:</p> <ul> <li><a href="https://wg-eips.ritovision.com/20/">ERC-20</a></li> <li><a href="https://wg-eips.ritovision.com/721/">ERC-721</a></li> <li><a href="https://wg-eips.ritovision.com/777/">ERC-777</a></li> <li><a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a></li> </ul> <h2 id="test-cases">Test Cases</h2> <h3 id="test-contract">Test Contract</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></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 class="z-keyword">import</span><span class="z-string"> &quot;./IERC5169.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC5169</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC5169</span><span>, </span><span class="z-entity z-name">Ownable</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> private</span><span> _scriptURI</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> scriptURI</span><span>(</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"> override</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 class="z-keyword"> return</span><span> _scriptURI</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"> setScriptURI</span><span>(</span><span class="z-support">string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> newScriptURI</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyOwner</span><span class="z-storage z-type"> override</span><span> {</span></span> <span class="giallo-l"><span> _scriptURI </span><span class="z-keyword">=</span><span> newScriptURI</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"> ScriptUpdate</span><span>(</span><span>newScriptURI</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><h3 id="test-cases-1">Test Cases</h3> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"></span> <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">&#39;</span><span class="z-string">chai</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> {</span><span class="z-variable z-other z-constant"> BigNumber</span><span>,</span><span class="z-variable z-other z-constant"> Wallet</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">&#39;</span><span class="z-string">ethers</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> {</span><span class="z-variable z-other z-constant"> ethers</span><span>,</span><span class="z-variable z-other z-constant"> network</span><span>,</span><span class="z-variable z-other z-constant"> getChainId</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">&#39;</span><span class="z-string">hardhat</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">describe</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">ERC5169</span><span class="z-punctuation z-definition z-string">&#39;</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"> before</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-language"> this</span><span>.</span><span class="z-variable z-other z-constant">ERC5169</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">&#39;</span><span class="z-string">ERC5169</span><span class="z-punctuation z-definition z-string">&#39;</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"> 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-punctuation z-definition z-comment"> //</span><span class="z-comment"> targetNFT</span></span> <span class="giallo-l"><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">erc5169</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other z-constant">ERC5169</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"> it</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">Should set script URI</span><span class="z-punctuation z-definition z-string">&#39;</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"> const</span><span class="z-variable z-other z-constant"> scriptURI</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">uri1</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">uri2</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">uri3</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 class="giallo-l"><span class="z-keyword"> await</span><span class="z-entity z-name"> expect</span><span>(</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">erc5169</span><span>.</span><span class="z-entity z-name">setScriptURI</span><span>(</span><span class="z-variable z-other">scriptURI</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> .</span><span class="z-entity z-name">emit</span><span>(</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">erc5169</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">ScriptUpdate</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">withArgs</span><span>(</span><span class="z-variable z-other">scriptURI</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"> currentScriptURI</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">erc5169</span><span>.</span><span class="z-entity z-name">scriptURI</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">currentScriptURI</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">to</span><span>.</span><span class="z-variable z-other">be</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-variable z-other">scriptURI</span><span>.</span><span class="z-entity z-name">toString</span><span>(</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></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>An intuitive implementation is the STL office door token. This NFT is minted and transferred to STL employees. The TokenScript attached to the token contract via the <code>scriptURI()</code> function contains instructions on how to operate the door interface. This takes the form of:</p> <ol> <li> <p>Query for challenge string (random message from IoT interface eg 'Apples-5E3FA1').</p> </li> <li> <p>Receive and display challenge string on Token View, and request 'Sign Personal'.</p> </li> <li> <p>On obtaining the signature of the challenge string, send back to IoT device.</p> </li> <li> <p>IoT device will unlock door if ec-recovered address holds the NFT.</p> </li> </ol> <p>With <code>scriptURI()</code> the experience is greatly enhanced as the flow for the user is:</p> <ol> <li> <p>Receive NFT.</p> </li> <li> <p>Use authenticated NFT functionality in the wallet immediately.</p> </li> </ol> <p>The project with contract, TokenScript and IoT firmware is in use by Smart Token Labs office door and numerous other installations. An example implementation contract: <a href="https://wg-eips.ritovision.com/5169/./assets/contract/ExampleContract.sol">ERC-5169 Contract Example</a> and TokenScript: <a href="https://wg-eips.ritovision.com/5169/./assets/tokenscript/ExampleScript.xml">ERC-5169 TokenScript Example</a>. Links to the firmware and full sample can be found in the associated discussion linked in the header. The associated TokenScript can be read from the contract using <code>scriptURI()</code>.</p> <h3 id="script-location">Script location</h3> <p>While the most straightforward solution to facilitate specific script usage associated with NFTs, is clearly to store such a script on the smart contract. However, this has several disadvantages:</p> <ol> <li> <p>The smart contract signing key is needed to make updates, causing the key to become more exposed, as it is used more often.</p> </li> <li> <p>Updates require smart contract interaction. If frequent updates are needed, smart contract calls can become an expensive hurdle.</p> </li> <li> <p>Storage fee. If the script is large, updates to the script will be costly. A client script is typically much larger than a smart contract.</p> </li> </ol> <p>For these reasons, storing volatile data, such as token enhancing functionality, on an external resource makes sense. Such an external resource can be either be hosted centrally, such as through a cloud provider, or privately hosted through a private server, or decentralized hosted, such as the interplanetary filesystem.</p> <p>While centralized storage for a decentralized functionality goes against the ethos of web3, fully decentralized solutions may come with speed, price or space penalties. This EIP handles this by allowing the function <code>ScriptURI</code> to return multiple URIs, which could be a mix of centralized, individually hosted and decentralized locations.</p> <p>While this EIP does not dictate the format of the stored script, the script itself could contain pointers to multiple other scripts and data sources, allowing for advanced ways to expand token scripts, such as lazy loading. The handling of integrity of such secondary data sources is left dependent on the format of the script.</p> <h2 id="security-considerations">Security Considerations</h2> <p><strong>When a server is involved</strong></p> <p>When the client script does not purely rely on connection to a blockchain node, but also calls server APIs, the trustworthiness of the server API is called into question. This EIP does not provide any mechanism to assert the authenticity of the API access point. Instead, as long as the client script is trusted, it's assumed that it can call any server API in order to carry out token functions. This means the client script can mistrust a server API access point.</p> <p><strong>When the scriptURI doesn't contain integrity (hash) information</strong></p> <p>We separately authored <code>Authenticity for Client Script</code> EIP to guide on how to use digital signatures efficiently and concisely to ensure authenticity and integrity of scripts not stored at a URI which is a digest of the script itself.</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-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-13T00:00:00+00:00 2026-02-11T14:48:26+00:00 Andershttps://github.com/0xanders Lancehttps://github.com/LanceSnow Shrugshrug@emojidao.org https://wg-eips.ritovision.com/5007/

Add start time and end time to ERC-721 tokens.

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. It proposes some additional functions (<code>startTime</code>, <code>endTime</code>) to help with on-chain time management.</p> <h2 id="motivation">Motivation</h2> <p>Some NFTs have a defined usage period and cannot be used outside of that period. With traditional NFTs that do not include time information, if you want to mark a token as invalid or enable it at a specific time, you need to actively submit a transaction—a process both cumbersome and expensive.</p> <p>Some existing NFTs contain time functions, but their interfaces are not consistent, so it is difficult to develop third-party platforms for them.</p> <p>By introducing these functions (<code>startTime</code>, <code>endTime</code>), it is possible to enable and disable NFTs automatically on chain.</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> <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"> the ERC-165 identifier for this interface is 0xf140be0d.</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"> IERC5007</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"> Returns the start time of the NFT as a UNIX timestamp.</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"> startTime</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></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 end time of the NFT as a UNIX timestamp.</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"> endTime</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>}</span></span></code></pre> <p>The <strong>composable extension</strong> is OPTIONAL for this standard. This allows your NFT to be minted from an existing NFT or to merge two NFTs into one NFT.</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"> the ERC-165 identifier for this interface is 0x75cf3842.</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"> IERC5007Composable</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC5007 </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"> Returns the asset id of the time NFT.</span></span> <span class="giallo-l"><span class="z-comment"> * Only NFTs with same asset id can be merged.</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"> assetId</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Split an old token to two new tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * The assetId of the new token is the same as the assetId of the old 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"> * - `oldTokenId` must exist.</span></span> <span class="giallo-l"><span class="z-comment"> * - `newToken1Id` must not exist.</span></span> <span class="giallo-l"><span class="z-comment"> * - `newToken1Owner` cannot be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * - `newToken2Id` must not exist.</span></span> <span class="giallo-l"><span class="z-comment"> * - `newToken2Owner` cannot be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * - `splitTime` require(oldToken.startTime &lt;= splitTime &amp;&amp; splitTime &lt; oldToken.EndTime)</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"> split</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> oldTokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> newToken1Id</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> newToken1Owner</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> newToken2Id</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> newToken2Owner</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> splitTime</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">@dev</span><span class="z-comment"> Merge the first token and second token into the new 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"> * - `firstTokenId` must exist.</span></span> <span class="giallo-l"><span class="z-comment"> * - `secondTokenId` must exist.</span></span> <span class="giallo-l"><span class="z-comment"> * - require((firstToken.endTime + 1) == secondToken.startTime)</span></span> <span class="giallo-l"><span class="z-comment"> * - require((firstToken.assetId()) == secondToken.assetId())</span></span> <span class="giallo-l"><span class="z-comment"> * - `newTokenOwner` cannot be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * - `newTokenId` must 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"> merge</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> firstTokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> secondTokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> newTokenOwner</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> newTokenId</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="time-data-type">Time Data Type</h3> <p>The max value of <code>uint64</code> is 18,446,744,073,709,551,615. As a timestamp, 18,446,744,073,709,551,615 is about year 584,942,419,325. <code>uint256</code> is too big for C, C++, Java, Go, etc, and <code>uint64</code> is natively supported by mainstream programming languages.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is fully ERC-721 compatible.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases are included in <a href="https://wg-eips.ritovision.com/5007/./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-5007</span></span> <span class="giallo-l"><span class="z-entity z-name">npm</span><span class="z-string"> install</span><span class="z-string"> truffle</span><span class="z-constant"> -</span><span class="z-constant">g</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">truffle</span><span class="z-string"> test</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/5007/./assets/contracts/ERC5007.sol"><code>ERC5007.sol</code></a>.</p> <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-04-12T00:00:00+00:00 2026-02-11T14:48:25+00:00 Lancehttps://github.com/LanceSnow Andershttps://github.com/0xanders Shrugshrug@emojidao.org https://wg-eips.ritovision.com/5006/

Add a user role with restricted permissions to ERC-1155 tokens

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>. It proposes an additional role (<code>user</code>) which can be granted to addresses that represent a <code>user</code> of the assets rather than an <code>owner</code>.</p> <h2 id="motivation">Motivation</h2> <p>Like <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> tokens may have utility of some kind. The people who “use” the token may be different than the people who own it (such as in a rental). Thus, it would be useful to have separate roles for the “owner” and the “user” so that the “user” would not be able to take actions that the owner could (for example, transferring ownership).</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> <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-storage z-type">interface</span><span class="z-entity z-name"> IERC5006</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> UserRecord</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 class="z-support"> address</span><span> owner</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> amount</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 class="z-support"> uint64</span><span> expiry</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"> Emitted when permission for `user` to use `amount` of `tokenId` token owned by `owner`</span></span> <span class="giallo-l"><span class="z-comment"> * until `expiry` are given.</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"> CreateUserRecord</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> recordId</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"> uint64</span><span class="z-variable"> amount</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"> address</span><span class="z-variable"> user</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> expiry</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"> Emitted when record of `recordId` are deleted. </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"> DeleteUserRecord</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> recordId</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 usable amount of `tokenId` tokens by `account`.</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"> usableBalanceOf</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"> 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">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">@dev</span><span class="z-comment"> Returns the amount of frozen tokens of token type `id` by `account`.</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"> frozenBalanceOf</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"> 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">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">@dev</span><span class="z-comment"> Returns the `UserRecord` of `recordId`.</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"> userRecordOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> recordId</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">UserRecord</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-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Gives permission to `user` to use `amount` of `tokenId` token owned by `owner` until `expiry`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {CreateUserRecord} event.</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"> * - If the caller is not `owner`, it must be have been approved to spend ``owner``&#39;s tokens</span></span> <span class="giallo-l"><span class="z-comment"> * via {setApprovalForAll}.</span></span> <span class="giallo-l"><span class="z-comment"> * - `owner` must have a balance of tokens of type `id` of at least `amount`.</span></span> <span class="giallo-l"><span class="z-comment"> * - `user` cannot be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * - `amount` must be greater than 0.</span></span> <span class="giallo-l"><span class="z-comment"> * - `expiry` must after the block timestamp.</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"> createUserRecord</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"> address</span><span class="z-variable"> user</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"> uint64</span><span class="z-variable"> amount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable"> expiry</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">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">@dev</span><span class="z-comment"> Atomically delete `record` of `recordId` by the caller.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {DeleteUserRecord} event.</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 have allowance.</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"> deleteUserRecord</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> recordId</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> <p>The <code>supportsInterface</code> method MUST return <code>true</code> when called with <code>0xc26d96cc</code>.</p> <h2 id="rationale">Rationale</h2> <p>This model is intended to facilitate easy implementation. The following are some 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).  For example, for the right to transfer ownership, the project simply needs to check whether the address taking the action represents the owner or the user and prevent the transaction if it is the user.  Additionally, owners can control who the user is and it is easy for other projects to assign their own rights to either the owners or the users.</p> <h3 id="easy-third-party-integration">Easy Third-Party Integration</h3> <p>In the spirit of permissionless 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, 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="backwards-compatibility">Backwards Compatibility</h2> <p>As mentioned in the specifications section, this standard can be fully ERC compatible by adding an extension function set, and there are no conflicts between <a href="https://wg-eips.ritovision.com/5006/">ERC-5006</a> and ERC-1155.</p> <p>In addition, new functions introduced in this standard have many similarities with the existing functions in ERC-1155. This allows developers to easily adopt the standard quickly.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases are included in <a href="https://wg-eips.ritovision.com/5006/./assets/test/test.ts">test.js</a>.</p> <p>Run in terminal:</p> <ol> <li><code>cd ../assets/eip-5006</code></li> <li><code>npm install</code></li> <li><code>npx hardhat test</code></li> </ol> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/5006/./assets/contracts/ERC5006.sol"><code>ERC5006.sol</code></a>.</p> <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, the user can not transfer the 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-04-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Andershttps://github.com/0xanders Lancehttps://github.com/LanceSnow Shrugshrug@emojidao.org https://wg-eips.ritovision.com/5008/

Add a `nonce` function to ERC-721.

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. It proposes adding a <code>nonce</code> function to ERC-721 tokens.</p> <h2 id="motivation">Motivation</h2> <p>Some orders of NFT marketplaces have been attacked and the NFTs sold at a lower price than the current market floor price. This can happen when users transfer an NFT to another wallet and, later, back to the original wallet. This reactivates the order, which may list the token at a much lower price than the owner would have intended.</p> <p>This EIP proposes adding a <code>nonce</code> property to ERC-721 tokens, and the <code>nonce</code> will be changed when a token is transferred. If a <code>nonce</code> is added to an order, the order can be checked to avoid attacks.</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> <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"> the ERC-165 identifier for this interface is 0xce03fdab.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5008</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC165 </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"> Emitted when the `nonce` of an NFT is </span><span class="z-keyword">changed</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> NonceChanged</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"> nonce</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 nonce of 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 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"> The</span><span class="z-comment"> nonce of the NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> nonce</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>nonce(uint256 tokenId)</code> function MUST be implemented as <code>view</code>.</p> <p>The <code>supportsInterface</code> method MUST return <code>true</code> when called with <code>0xce03fdab</code>.</p> <h2 id="rationale">Rationale</h2> <p>At first <code>transferCount</code> was considered as function name, but there may some case to change the <code>nonce</code> besides transfer, such as important properties changed, then we changed <code>transferCount</code> to <code>nonce</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with ERC-721.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases are included in <a href="https://wg-eips.ritovision.com/5008/./assets/test/test.ts">test.js</a>.</p> <p>Run:</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-5008</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">npm</span><span class="z-string"> run</span><span class="z-string"> test</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/5008/./assets/contracts/ERC5008.sol"><code>ERC5008.sol</code></a>.</p> <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-04-04T00:00:00+00:00 2026-02-11T14:48:25+00:00 Shu Donghttps://github.com/dongshu2013 Qi Zhouhttps://github.com/qizhou Zihao Chenhttps://github.com/zihaoccc https://wg-eips.ritovision.com/4972/

Name-Owned Account for Social Identity

<h2 id="abstract">Abstract</h2> <p>The ERC suggests expanding the capabilities of the name service, such as ENS, by enabling each human-readable identity to be linked to a single smart contract account that can be controlled by the owner of the name identity.</p> <h2 id="motivation">Motivation</h2> <p>Name itself cannot hold any context. We want to build an extension of name service to give name rich context by offering each name owner an extra ready to use smart contract account, which may help the general smart contract account adoption. With NOA, it is possible to hold assets and information for its name node, opening up new use cases such as name node transfers, which involve transferring ownership of the name node as well as the NOA, including any assets and information it holds.</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="name-owned-account">Name-Owned Account</h3> <p>An NOA has</p> <ul> <li>a human readable name defined by <a href="https://wg-eips.ritovision.com/137/">ERC-137</a>; and</li> <li>an owned account(NOA), which is an smart contract account whose address is derived from the name; and</li> <li>owner(s) of the name that can deploy and manipulate the owned account.</li> </ul> <p>The following diagram illustrates the relationship between NOA, name node, and name owner, with the ownership being guaranteed by the name service.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> ┌───────────────┐ ┌───────────┐ ┌───────────────┐</span></span> <span class="giallo-l"><span> │ Owned Account ◄──own───┤ Name Node ◄───own───┤ Name Owner │</span></span> <span class="giallo-l"><span> └───────────────┘ └───────────┘ └───────────────┘</span></span></code></pre><h3 id="interface">Interface</h3> <p>The core interface required for a name service to have is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>interface INameServiceRegistry {</span></span> <span class="giallo-l"><span> /// @notice get account address owned by the name node</span></span> <span class="giallo-l"><span> /// @params node represents a name node</span></span> <span class="giallo-l"><span> /// @return the address of an account</span></span> <span class="giallo-l"><span> function ownedAccount(</span></span> <span class="giallo-l"><span> bytes32 node</span></span> <span class="giallo-l"><span> ) external view returns(address);</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The core interface required for the name owned account is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>interface INameOwnedAccount {</span></span> <span class="giallo-l"><span> /// @notice get the name node is mapped to this account address</span></span> <span class="giallo-l"><span> /// @return return a name node</span></span> <span class="giallo-l"><span> function name() external view returns(bytes32);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice get the name service contract address where</span></span> <span class="giallo-l"><span> /// the name is registered</span></span> <span class="giallo-l"><span> /// @return return the name service the name registered at</span></span> <span class="giallo-l"><span> function nameService() external view returns(address);</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>To achieve a one-to-one mapping from the name to the NOA, where each NOA's address is derived from the name node, we must include the name node information in each NOA to reflect its name node ownership. The "name()" function can be used to retrieve this property of each NOA and enable reverse tracking to its name node. The "nameService()" function can get the name service contract address where the name is registered, to perform behaviors such as validation checks. Through these two methods, the NOA has the ability to track back to its actual owner who owns the name node.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The name registry interface is compatible with ERC-137.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="name-owned-account-creation">Name Owned Account Creation</h3> <p>The NOA creation is done by a “factory” contract. The factory could be the name service itself and is expected to use CREATE2 (not CREATE) to create the NOA. NOAs should have identical initcode and factory contract in order to achieve deterministic preservation of address. The name node can be used as the salt to guarantee the bijection from name to its owned account.</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-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-04-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Tim Daubenschützhttps://github.com/TimDaub https://wg-eips.ritovision.com/4973/

An interface for non-transferrable NFTs binding to an Ethereum account like a legendary World of Warcraft item binds to a character.

<h2 id="abstract">Abstract</h2> <p>Proposes a standard API for account-bound Tokens (ABT) within smart contracts. An ABT is a non-fungible token bound to a single account. ABTs don't implement a canonical interface for transfers. This EIP defines basic functionality to mint, assign, revoke and track ABTs.</p> <h2 id="motivation">Motivation</h2> <p>In the popular MMORPG World of Warcraft, its game designers intentionally took some items out of the world's auction house market system to prevent them from having a publicly-discovered price and limit their accessibility.</p> <p>Vanilla WoW's "Thunderfury, Blessed Blade of the Windseeker" was one such legendary item, and it required a forty-person raid, among other sub-tasks, to slay the firelord "Ragnaros" to gain the "Essence of the Firelord," a material needed to craft the sword once.</p> <p>Upon voluntary pickup, the sword permanently <strong>binds</strong> to a character's "soul," making it impossible to trade, sell or even swap it between a player's characters.</p> <p>In other words, "Thunderfury"'s price was the aggregate of all social costs related to completing the difficult quest line with friends and guild members. Other players spotting Thunderfuries could be sure their owner had slain "Ragnaros," the blistering firelord.</p> <p>World of Warcraft players could <strong>trash</strong> legendary and soulbound items like the Thunderfury to permanently remove them from their account. It was their choice to visibly <strong>equip</strong> or <strong>unequip</strong> an item and hence show their achievements to everyone.</p> <p>The Ethereum community has expressed a need for non-transferrable, non-fungible, and socially-priced tokens similar to WoW's soulbound items. Popular contracts implicitly implement account-bound interaction rights today. A principled standardization helps interoperability and improves on-chain data indexing.</p> <p>The purpose of this document is to make ABTs a reality on Ethereum by creating consensus around a <strong>maximally backward-compatible</strong> but otherwise <strong>minimal</strong> interface definition.</p> <h2 id="specification">Specification</h2> <h3 id="solidity-interface">Solidity Interface</h3> <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>ABTs <em>must</em> implement the interfaces:</p> <ul> <li><a href="https://wg-eips.ritovision.com/165/">ERC-165</a>'s <code>ERC165</code> (<code>0x01ffc9a7</code>)</li> <li><a href="https://wg-eips.ritovision.com/721/">ERC-721</a>'s <code>ERC721Metadata</code> (<code>0x5b5e139f</code>)</li> </ul> <p>ABTs <em>must not</em> implement the interfaces:</p> <ul> <li><a href="https://wg-eips.ritovision.com/721/">ERC-721</a>'s <code>ERC721</code> (<code>0x80ac58cd</code>)</li> </ul> <p>An ABT receiver must be able to always call <code>function unequip(address _tokenId)</code> to take their ABT off-chain.</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.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"> Account-bound tokens</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-4973</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 0xeb72bb7c</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC4973</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 ABT changes by any mechanism.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This event emits when ABTs are given or equipped and unequipped</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (`to` == 0).</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 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"> 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"> Count all ABTs assigned to an owner</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> ABTs 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"> owner</span><span class="z-comment"> An 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"> The</span><span class="z-comment"> number of ABTs owned by `address owner`, possibly zero</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"> Find the address bound to an ERC4973 account-bound token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> ABTs 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"> tokenId</span><span class="z-comment"> The identifier for an ABT.</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 bound to the ABT.</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"> Removes the `uint256 tokenId` from an account. At any time, an</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ABT receiver must be able to disassociate themselves from an ABT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> publicly through calling this function. After successfully executing this</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> function, given the parameters for calling `function give` or</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `function take` a token must be re-equipable.</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 a `event Transfer` with the `address to` field pointing to</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 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"> tokenId</span><span class="z-comment"> The identifier for an ABT.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unequip</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Creates and transfers the ownership of an ABT from the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> transaction&#39;s `msg.sender` to `address to`.</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 `bytes signature` represents a signature of the</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> EIP-712 structured data hash</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `Agreement(address active,address passive,bytes metadata)` expressing</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `address to`&#39;s explicit agreement to be publicly associated with</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `msg.sender` and `bytes metadata`. A unique `uint256 tokenId` must be</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> generated by type-casting the `bytes32` EIP-712 structured data hash to a</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `uint256`. If `bytes signature` is empty or `address to` is a contract,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> an EIP-1271-compatible call to `function isValidSignatureNow(...)` must</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> be made to `address to`. A successful execution must result in the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `event Transfer(msg.sender, to, tokenId)`. Once an ABT exists as an</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `uint256 tokenId` in the contract, `function give(...)` must 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"> to</span><span class="z-comment"> The receiver of the ABT.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> metadata</span><span class="z-comment"> The metadata that will be associated to the ABT.</span></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"> A signature of the EIP-712 structured data hash</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `Agreement(address active,address passive,bytes metadata)` signed by</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `address to`.</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"> unique `uint256 tokenId` generated by type-casting the `bytes32`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> EIP-712 structured data hash to a `uint256`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> give</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> metadata</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> <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">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"> Creates and transfers the ownership of an ABT from an</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `address from` to the transaction&#39;s `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"> Throws unless `bytes signature` represents a signature of the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> EIP-712 structured data hash</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `Agreement(address active,address passive,bytes metadata)` expressing</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `address from`&#39;s explicit agreement to be publicly associated with</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `msg.sender` and `bytes metadata`. A unique `uint256 tokenId` must be</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> generated by type-casting the `bytes32` EIP-712 structured data hash to a</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `uint256`. If `bytes signature` is empty or `address from` is a contract,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> an EIP-1271-compatible call to `function isValidSignatureNow(...)` must</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> be made to `address from`. A successful execution must result in the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> emission of an `event Transfer(from, msg.sender, tokenId)`. Once an ABT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> exists as an `uint256 tokenId` in the contract, `function take(...)` must</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 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"> from</span><span class="z-comment"> The origin of the ABT.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> metadata</span><span class="z-comment"> The metadata that will be associated to the ABT.</span></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"> A signature of the EIP-712 structured data hash</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `Agreement(address active,address passive,bytes metadata)` signed by</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `address from`.</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"> A</span><span class="z-comment"> unique `uint256 tokenId` generated by type-casting the `bytes32`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> EIP-712 structured data hash to a `uint256`.</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 class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> metadata</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> <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">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"> Decodes the opaque metadata bytestring of an ABT into the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> URI that will be associated with it once it is created on chain.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> metadata</span><span class="z-comment"> The metadata that will be associated to an ABT.</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"> URI that represents the metadata.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> decodeURI</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> metadata</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>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>See <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> for a definition of its metadata JSON Schema.</p> <h3 id="eip-712-typed-structured-data-hashing-and-bytearray-signature-creation"><a href="https://wg-eips.ritovision.com/712/">EIP-712</a> Typed Structured Data Hashing and Bytearray Signature Creation</h3> <p>To invoke <code>function give(...)</code> and <code>function take(...)</code> a bytearray signature must be created using <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>. A tested reference implementation in Node.js is attached at <a href="https://wg-eips.ritovision.com/4973/./assets/sdk/src/index.mjs">index.mjs</a>, <a href="https://wg-eips.ritovision.com/4973/./assets/sdk/test/index_test.mjs">index_test.mjs</a> and <a href="https://wg-eips.ritovision.com/4973/./assets/package.json">package.json</a>. In Solidity, this bytearray signature can be created as follows:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes32</span><span> r </span><span class="z-keyword">=</span><span class="z-constant"> 0x68a020a209d3d56c46f38cc50a33f704f4a9a10a59377f8dd762ac66910e9b90</span><span>;</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span> s </span><span class="z-keyword">=</span><span class="z-constant"> 0x7e865ad05c4035ab5792787d4a0297a43617ae897930a6fe4d822b8faea52064</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint8</span><span> v </span><span class="z-keyword">=</span><span class="z-constant"> 27</span><span>;</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> signature </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>r</span><span>,</span><span> s</span><span>,</span><span> v</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="interface">Interface</h3> <p>ABTs shall be maximally backward-compatible but still only expose a minimal and simple to implement interface definition.</p> <p>As <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> tokens have seen widespread adoption with wallet providers and marketplaces, using its <code>ERC721Metadata</code> interface with <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> for feature-detection potentially allows implementers to support ABTs out of the box.</p> <p>If an implementer of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> properly built <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>'s <code>function supportsInterface(bytes4 interfaceID)</code> function, already by recognizing that <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>'s track and transfer interface component with the identifier <code>0x80ac58cd</code> is not implemented, transferring of a token should not be suggested as a user interface option.</p> <p>Still, since ABTs support <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>'s <code>ERC721Metadata</code> extension, wallets and marketplaces should display an account-bound token with no changes needed.</p> <p>Although other implementations of account-bound tokens are possible, e.g., by having all transfer functions revert, ABTs are superior as it supports feature detection through <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>.</p> <p>We expose <code>function unequip(address _tokenId)</code> and require it to be callable at any time by an ABT's owner as it ensures an owner's right to publicly disassociate themselves from what has been issued towards their account.</p> <h3 id="exception-handling">Exception handling</h3> <p>Given the non-transferable between accounts property of ABTs, if a user's keys to an account or a contract get compromised or rotated, a user may lose the ability to associate themselves with the token. In some cases, this can be the desired effect. Therefore, ABT implementers should build re-issuance and revocation processes to enable recourse. We recommend implementing strictly decentralized, permissionless, and censorship-resistant re-issuance processes.</p> <p>But this document is deliberately abstaining from offering a standardized form of exception handling in cases where user keys are compromised or rotated.</p> <p>In cases where implementers want to make account-bound tokens shareable among different accounts, e.g., to avoid losing access when keys get compromised, we suggest issuing the account-bound token towards a contract's account that implements a multi-signature functionality.</p> <h3 id="provenance-indexing">Provenance Indexing</h3> <p>ABTs can be indexed by tracking the emission of <code>event Transfer(address indexed from, address indexed to, uint256 indexed tokenId)</code>. As with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, transfers between two accounts are represented by <code>address from</code> and <code>address to</code> being non-zero addresses. Unequipping a token is represented through emitting a transfer with <code>address to</code> being set to the zero address. Mint operations where <code>address from</code> is set to zero don't exist. To avoid being spoofed by maliciously-implemented <code>event Transfer</code> emitting contracts, an indexer should ensure that the transaction's sender is equal to <code>event Transfer</code>'s <code>from</code> value.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>We have adopted the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> and <code>ERC721Metadata</code> functions purposefully to create a high degree of backward compatibility with <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. We have deliberately used <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> terminology such as <code>function ownerOf(...)</code>, <code>function balanceOf(...)</code> to minimize the effort of familiarization for ABT implementers already familiar with, e.g., <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> or <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. For indexers, we've re-used the widely-implemented <code>event Transfer</code> event signature.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>You can find an implementation of this standard in <a href="https://wg-eips.ritovision.com/4973/./assets/ERC4973-flat.sol">ERC-4973-flat.sol</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-03-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ignacio Mazzarahttps://github.com/nachomazzara https://wg-eips.ritovision.com/4955/

Add a new field to NFT metadata to store vendor specific data

<h2 id="abstract">Abstract</h2> <p>This EIP standardizes a schema for NFTs metadata to add new field namespaces to the JSON schema for <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> NFTs.</p> <h2 id="motivation">Motivation</h2> <p>A standardized NFT metadata schema allows wallets, marketplaces, metaverses, and similar applications to interoperate with any NFT. Applications such as NFT marketplaces and metaverses could usefully leverage NFTs by rendering them using custom 3D representations or any other new attributes.</p> <p>Some projects like Decentraland, TheSandbox, Cryptoavatars, etc. need their own 3D model in order to represent an NFT. These models are not cross-compatible because of distinct aesthetics and data formats.</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="schema">Schema</h3> <p>(subject to "caveats" below)</p> <p>A new property called <code>namespaces</code> is introduced. This property expects one object per project as shown in the example below.</p> <pre class="giallo z-code"><code data-lang="jsonc"><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 that 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 that 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 that 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">namespaces</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">Application-specific NFT properties</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="example">Example</h3> <pre class="giallo z-code"><code data-lang="jsonc"><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">My NFT</span><span class="z-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">NFT description</span><span class="z-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://QmZfmRZHuawJDtDVMaEaPWfgWFV9iXoS9SzLvwX76wm6pa</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">namespaces</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">myAwesomeCompany</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">prop1</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">value1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">prop2</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">value2</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">myAwesomeCompany2</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">prop3</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">value3</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">prop4</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">value4</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> }</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"> Or by simply using a `URI` to reduce the size of the JSON response.</span></span> <span class="giallo-l"></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">My NFT</span><span class="z-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">NFT description</span><span class="z-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://QmZfmRZHuawJDtDVMaEaPWfgWFV9iXoS9SzLvwX76wm6pa</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">namespaces</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">myAwesomeCompany</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">myAwesomeCompany2</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> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>There are many projects which need custom properties in order to display a current NFT. Each project may have its own way to render the NFTs and therefore they need different values. An example of this is the metaverses like Decentraland or TheSandbox where they need different 3d models to render the NFT based on the visual/engine of each. NFTs projects like Cryptopunks, Bored Apes, etc. can create the 3d models needed for each project and therefore be supported out of the box.</p> <p>The main differences between the projects that are rendering 3d NFTs (models) are:</p> <h3 id="armatures">Armatures</h3> <p>Every metaverse uses its own armature. There is a standard for humanoids but it is not being used for every metaverse and not all the metaverses use humanoids. For example, Decentraland has a different aesthetic than Cryptovoxels and TheSandbox. It means that every metaverse will need a different model and they may have the same extension (GLB, GLTF)</p> <p><img src="https://wg-eips.ritovision.com/4955/./assets/different-renders.jpeg" alt="" /></p> <h3 id="metadata-representations-files">Metadata (Representations Files)</h3> <p>For example, every metaverse uses its own metadata representation files to make it work inside the engine depending on its game needs.</p> <p>This is the JSON config of a wearable item in Decentraland:</p> <pre class="giallo z-code"><code data-lang="jsonc"><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>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">replaces</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">hides</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">tags</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">category</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">upper_body</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">representations</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">bodyShapes</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">urn:decentraland:off-chain:base-avatars:BaseMale</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">mainFile</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">male/Look6_Tshirt_A.glb</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">contents</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">male/Look6_Tshirt_A.glb</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">url</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://peer-ec2.decentraland.org/content/contents/QmX3yMhmx4AvGmyF3CM5ycSQB4F99zXh9rL5GvdxTTcoCR</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">overrideHides</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">overrideReplaces</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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">bodyShapes</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">urn:decentraland:off-chain:base-avatars:BaseFemale</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">mainFile</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">female/Look6_Tshirt_B (1).glb</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">contents</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">female/Look6_Tshirt_B (1).glb</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">url</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://peer-ec2.decentraland.org/content/contents/QmcgddP4L8CEKfpJ4cSZhswKownnYnpwEP4eYgTxmFdav8</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">overrideHides</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">overrideReplaces</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></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">image</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">https://peer-ec2.decentraland.org/content/contents/QmPnzQZWAMP4Grnq6phVteLzHeNxdmbRhKuFKqhHyVMqrK</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">thumbnail</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">https://peer-ec2.decentraland.org/content/contents/QmcnBFjhyFShGo9gWk2ETbMRDudiX7yjn282djYCAjoMuL</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">metrics</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">triangles</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 3400</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">materials</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">textures</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">meshes</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">bodies</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">entities</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> <p><code>replaces</code>, <code>overrides</code>, <code>hides</code>, and different body shapes representation for the same asset are needed for Decentraland in order to render the 3D asset correctly.</p> <p>Using <code>namespaces</code> instead of objects like the ones below make it easy for the specific vendor/third-parties to access and index the required models. Moreover, <code>styles</code> do not exist because there are no standards around for how an asset will be rendered. As I mentioned above, each metaverse for example uses its own armature and aesthetic. There is no Decentraland-style or TheSandbox-style that other metaverses use. Each of them is unique and specific for the sake of the platform's reason of being. Projects like Cryptoavatars are trying to push different standards but without luck for the same reasons related to the uniquity of the armature/animations/metadata.</p> <pre class="giallo z-code"><code data-lang="jsonc"><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">model</span><span class="z-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">model/gltf+json</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">style</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Decentraland</span><span class="z-punctuation z-definition z-string">&quot;</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-punctuation z-definition z-string"> &quot;</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Or</span></span> <span class="giallo-l"></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">model</span><span class="z-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">model/gltf+json</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">style</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">humanoide</span><span class="z-punctuation z-definition z-string">&quot;</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-punctuation z-definition z-string"> &quot;</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></code></pre> <p>With <code>namespaces</code>, each vendor will know how to render an asset by doing:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-entity z-name">fetch</span><span>(</span><span class="z-variable z-other">metadata</span><span>.</span><span class="z-variable z-other">namespaces</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">PROJECT_NAME</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>.</span><span class="z-variable z-other">uri</span><span>)</span><span>.</span><span class="z-entity z-name">then</span><span>(</span><span class="z-variable">res</span><span class="z-storage z-type"> =&gt;</span><span class="z-entity z-name"> render</span><span>(</span><span class="z-variable z-other">res</span><span>)</span><span>)</span></span></code></pre> <p>The idea behind extending the <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> metadata schema is for backward compatibility. Most projects on Ethereum use non-upgradeable contracts. If this EIP required new implementations of those contracts, they would have to be re-deployed. This is time-consuming and wastes money. Leveraging EIP-721's existing metadata field minimizes the number of changes necessary. Finally, the JSON metadata is already used to store representations using the <code>image</code> field. It seems reasonable to have all the representations of an asset in the same place.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Existing projects that can't modify the metadata response (schema), may be able to create a new smart contract that based on the <code>tokenId</code> returns the updated metadata schema. Of course, the projects may need to accept these linked smart contracts as valid in order to fetch the metadata by the <code>tokenURI</code> function.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The same security considerations as with <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> apply related to using http gateways or IPFS for the tokenURI method.</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-26T00:00:00+00:00 2026-02-11T14:49:27+00:00 Dan Finlayhttps://github.com/danfinlay Sam Wilsonhttps://github.com/SamWilsn https://wg-eips.ritovision.com/5003/

Allow migrating away from ECDSA by deploying code in place of an externally owned account.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a new opcode, <code>AUTHUSURP</code>, which deploys code at an <a href="https://wg-eips.ritovision.com/3074/">EIP-3074</a> authorized address. For externally owned accounts (EOAs), together with <a href="https://wg-eips.ritovision.com/3607/">EIP-3607</a>, this effectively revokes the original signing key's authority.</p> <h2 id="motivation">Motivation</h2> <p>EOAs currently hold a significant amount of user-controlled value on Ethereum blockchains, but are limited by the protocol in a variety of critical ways. These accounts do not support rotating keys for security, batching to save gas, or sponsored transactions to reduce the need to hold ether yourself. There are countless other benefits that come from having a contract account or account abstraction, like choosing one's own authentication algorithm, setting spending limits, enabling social recovery, allowing key rotation, arbitrarily and transitively delegating capabilities, and just about anything else we can imagine.</p> <p>New users have access to these benefits using smart contract wallets, and new contracts can adopt recent standards to enable app-layer account abstraction (like <a href="https://wg-eips.ritovision.com/4337/">EIP-4337</a>), but these would neglect the vast majority of existing Ethereum users' accounts. These users exist today, and they also need a path to achieving their security goals.</p> <p>Those added benefits would mostly come along with EIP-3074 itself, but with one significant shortcoming: the original signing key has ultimate authority for the account. While an EOA could delegate its authority to some <em>additional</em> contract, the key itself would linger, continuing to provide an attack vector, and a constantly horrifying question lingering: have I been leaked? In other words, EIP-3074 can only grant authority to additional actors, but never revoke it.</p> <p>Today's EOAs have no option to rotate their keys. A leaked private key (either through phishing, or accidental access) cannot be revoked. A prudent user concerned about their key security might migrate to a new secret recovery phrase but at best this requires a transaction per asset (making it extremely expensive), and at worst, some powers (like hard-coded owners in a smart contract) might not be transferable at all.</p> <p>We know that EOAs cannot provide ideal user experience or safety, and there is a desire in the community to change the norm to contract-based accounts, but if that transition is designed without regard for the vast majority of users today—for whom Ethereum has always meant EOAs—we will be continually struggling against the need to support both of these userbases. This EIP provides a path not to enshrine EOAs, but to provide a migration path off of them, once and for all.</p> <p>This proposal combines well with, but is distinct from, <a href="https://wg-eips.ritovision.com/3074/">EIP-3074</a>, which provides opcodes that could enable any externally owned account (EOA) to delegate its signing authority to an arbitrary smart contract. It allows an EOA to authorize a contract account to act on its behalf <em>without forgoing its own powers</em>, while this EIP provides a final migration path off the EOA's original signing key.</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="conventions">Conventions</h3> <ul> <li><strong><code>top - N</code></strong> - the <code>N</code>th most recently pushed value on the EVM stack, where <code>top - 0</code> is the most recent.</li> <li><strong>invalid execution</strong> - execution that is invalid and must exit the current execution frame immediately, consuming all remaining gas (in the same way as a stack underflow or invalid jump).</li> <li><strong>empty account</strong> - account where its balance is 0, its nonce is 0, and it has no code.</li> </ul> <h3 id="authusurp-0xf8"><code>AUTHUSURP</code> (<code>0xf8</code>)</h3> <p>A new opcode <code>AUTHUSURP</code> shall be created at <code>0xf8</code>. It shall take two stack elements and return one stack element.</p> <h4 id="input">Input</h4> <table><thead><tr><th>Stack</th><th>Value</th></tr></thead><tbody> <tr><td><code>top - 0</code></td><td><code>offset</code></td></tr> <tr><td><code>top - 1</code></td><td><code>length</code></td></tr> </tbody></table> <h4 id="output">Output</h4> <table><thead><tr><th>Stack</th><th>Value</th></tr></thead><tbody> <tr><td><code>top - 0</code></td><td><code>address</code></td></tr> </tbody></table> <h4 id="behavior">Behavior</h4> <p><code>AUTHUSURP</code> behaves identically to <code>CREATE</code> (<code>0xf0</code>), except as described below:</p> <ul> <li>If <code>authorized</code> (as defined in EIP-3074) is unset, execution is invalid.</li> <li>If <code>authorized</code> points to an empty account, then <code>static_gas</code> remains 32,000. Otherwise, <code>static_gas</code> shall be 7,000.</li> <li><code>AUTHUSURP</code> does not check the nonce of the <code>authorized</code> account.</li> <li>The initcode runs at the address <code>authorized</code>.</li> <li>If the initcode returns no bytes, its execution frame must be reverted, and <code>AUTHUSURP</code> returns zero.</li> <li>After executing the initcode, but before the returned code is deployed, if the account's code is non-empty, the initcode's execution frame must be reverted, and <code>AUTHUSURP</code> returns zero.</li> <li>The code is deployed into the account with the address <code>authorized</code>.</li> </ul> <h2 id="rationale">Rationale</h2> <p><code>AUTHUSURP</code> does not check the nonce of the <code>authorized</code> account because it must work with accounts that have previously sent transactions.</p> <p>When using <code>AUTHUSURP</code>, if the initcode were to deploy a zero-length contract, there would be no way to prevent using <code>AUTHUSURP</code> again later.</p> <p>The account's code must be checked immediately before deploying to catch the situation where the initcode attempts to <code>AUTHUSURP</code> at the same address. This is unnecessary with other deployment instructions because they increment and check the account's nonce.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><code>AUTHUSURP</code> with EIP-3607 revokes the authority of the original ECDSA signature to send transactions from the account. This is completely new behavior, although it is somewhat similar to the <code>CREATE2</code> opcode.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Contracts using ECDSA signatures outside of transactions will not be aware that the usurped account is no longer controlled by a private key. This means that, for example, the private key will <em>always</em> have access to the <code>permit</code> function on token contracts. This can—and should—be mitigated by modifying the <code>ecrecover</code> pre-compiled 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-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-23T00:00:00+00:00 2026-02-11T14:49:27+00:00 Marius van der Wijdenhttps://github.com/MariusVanDerWijden Felix Langefjl@ethereum.org Gary Ronggaryrong@ethereum.org https://wg-eips.ritovision.com/4938/

"Remove GetNodeData and NodeData messages from the wire protocol"

<h2 id="abstract">Abstract</h2> <p>The <a rel="external" href="https://github.com/ethereum/devp2p/blob/40ab248bf7e017e83cc9812a4e048446709623e8/caps/eth.md">Ethereum Wire Protocol</a> defines request and response messages for exchanging data between clients. The <code>GetNodeData</code> request retrieves a set of trie nodes or contract code from the state trie by hash. We propose to remove the <code>GetNodeData</code> and <code>NodeData</code> messages from the wire protocol.</p> <h2 id="motivation">Motivation</h2> <p><code>GetNodeData</code> and <code>NodeData</code> were introduced in protocol version <code>eth/63</code> to allow for a sync mode called "fast sync", which downloads the Ethereum state without executing all blocks. The sync algorithm works by requesting all state trie nodes and contract codes by their hash.</p> <p>Serving <code>GetNodeData</code> requests requires clients to store state as a mapping of hashes to trie nodes. Avoiding the need to store such a mapping in the database is the main motivation for removing this request type.</p> <p>At this time, some client implementations cannot serve <code>GetNodeData</code> requests because they do not store the state in a compatible way. The Ethereum Wire Protocol should accurately reflect the capabilities of clients, and should not contain messages which are impossible to implement in some clients.</p> <h2 id="specification">Specification</h2> <p>Remove the following message types from the <code>eth</code> protocol:</p> <ul> <li><code>GetNodeData (0x0d)</code> <ul> <li><strong>(eth/66)</strong>: <code>[request_id: P, [hash_0: B_32, hash_1: B_32, ...]]</code></li> </ul> </li> <li><code>NodeData (0x0e)</code> <ul> <li><strong>(eth/66)</strong>: <code>[request_id: P, [value_0: B, value_1: B, ...]]</code></li> </ul> </li> </ul> <h2 id="rationale">Rationale</h2> <p>A replacement for <code>GetNodeData</code> is available in the <a rel="external" href="https://github.com/ethereum/devp2p/blob/40ab248bf7e017e83cc9812a4e048446709623e8/caps/snap.md">snap protocol</a>. Specifically, clients can use the <a rel="external" href="https://github.com/ethereum/devp2p/blob/40ab248bf7e017e83cc9812a4e048446709623e8/caps/snap.md#getbytecodes-0x04">GetByteCodes</a> and <a rel="external" href="https://github.com/ethereum/devp2p/blob/40ab248bf7e017e83cc9812a4e048446709623e8/caps/snap.md#gettrienodes-0x06">GetTrieNodes</a> messages instead of <code>GetNodeData</code>. The snap protocol can be used to implement the "fast sync" algorithm, though it is recommended to use it for "snap sync".</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP changes the <code>eth</code> protocol and requires rolling out a new version, <code>eth/67</code>. Supporting multiple versions of a wire protocol is possible. Rolling out a new version does not break older clients immediately, since they can keep using protocol version <code>eth/66</code>.</p> <p>This EIP does not change consensus rules of the EVM and does not require a hard fork.</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-03-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Kelvin Fichterhttps://github.com/smartcontracts Andreas Freundhttps://github.com/Therecanbeonlyone1969 https://wg-eips.ritovision.com/6735/

Identify and translate EVM-based addresses from different Layer 1, Layer 2, or Sidechains

<h2 id="abstract">Abstract</h2> <p>The document describes the minimal set of business and technical prerequisites, functional and non-functional requirements for Aliasing of EVM based Addresses that when implemented ensures that two or more Layer 1, Layer 2, or Sidechains can identify and translate EVM based addresses from different Layer 1, Layer 2, or Sidechains.</p> <h2 id="motivation">Motivation</h2> <p>The members of the L2 WG of the EEA Communities Project managed by OASIS have recognized that the ability to deterministically derive addresses of a digital asset or an externally owned account (EOA) in EVM based execution frameworks for L1s, L2s, Sidechains based on an origin chain of an asset or EOA, known as address aliasing, simplifies interoperability between EVM based L1s, L2s, and Sidechains because:</p> <ul> <li>It allows messages from chain A (source chain) to unambiguously address asset A (smart contract) or EOA on chain Y (target chain), if asset A or EOA exists on Chain X and on Chain Y.</li> <li>It allows a user to deterministically verify the source chain of a message, and, if required, directly verify the origin chain of asset A or EOA and its state on its origin chain utilizing a canonical token list of the (message) source chain.</li> </ul> <p>The ability to unambiguously, and deterministically, relate an address for a digital asset (smart contract) or an externally owned account (EOA) between EVM based L1s, L2s, and Sidechains where this digital asset or EOA exists, also known as address aliasing, is critical prerequisite for interoperability between EVM based L1s, L2s, and Sidechains. However, there is currently no way to do so in a standardized way -- imagine every internet service provider were to define its own IP addresses.</p> <p>Hence, the L2 WG of the EEA Communities Project managed by OASIS, an open-source initiative, intends for this document to establish an unambiguous and deterministic standard for EVM based address aliasing based on the concept of root → leaf where an address alias is derived based on the address on the origin chain and an offset which is an immutable characteristic of the origin chain.</p> <p>See Figure 1 for the conceptual root → leaf design with offset.</p> <p><img src="https://wg-eips.ritovision.com/6735/./assets/address-aliasing-root-leaf-design.png" alt="Fig1" /></p> <p>Figure 1: Root → Leaf address aliasing concept using an chain immanent characteristics from L1 to L2 and L3 and back.</p> <p>Alternative Figure 1 Description: The figure describes conceptually how (interoperability) messages from source to target chain utilize address aliasing. At the bottom an EVM based L1 is uni-directionally connected to three EVM based L2s -- A, B, and C -- each with an alias of L1 address + L1 Offset. In addition, A is uni-directionally connected to B with an alias of L1 address + L1 offset + A offset. B is uni-directionally connected to an EVM-based Layer 3 or L3 with an alias of L1 address + L1 offset + B offset signaling that the address is anchored on L1 via the L2 B. And finally D is uni-directionally connected to C via the alias L1 address + L1 offset + B offset plus D offset indicating the asset chain of custody from L1 to B to D to C.</p> <p>To further clarify the connections between the different possible paths an asset can take from an L1 to different L2/L3s and the <code>relativeAddress</code> of that asset, we visually highlight in red the path from the EVM based L1 to the B L2, to the D L3, and finally to the C L2.</p> <p><img src="https://wg-eips.ritovision.com/6735/./assets/visual-Highlight-Path-Red-evm-based-aliasing..png" alt="Fig2" /></p> <p>Figure 2: Visually highlighted path in red from the EVM based L1 to the B L2, to the D L3, and finally to the C L2.</p> <p>Alternative Figure 1 Description: The figure is the same as Figure 1. However, the uni-directional connections between the EVM based L1 to the L2 B, to the L3 D, and finally to the L2 C are highlighted in red.</p> <p>Note, that address aliasing between non-EVM and EVM-based L1s, L2s, and Sidechains, and between non-EVM-based L1s, L2s, and Sidechains is out of scope of this document.</p> <h2 id="specification">Specification</h2> <h3 id="typographical-convention-requirement-ids">Typographical Convention: Requirement Ids</h3> <p>A requirement is uniquely identified by a unique ID composed of its requirement level followed by a requirement number, as per convention <strong>[RequirementLevelRequirementNumber]</strong>. There are four requirement levels that are coded in requirement ids as per below convention:</p> <p><strong>[R]</strong> - The requirement level for requirements which IDs start with the letter <em>R</em> is to be interpreted as <strong>MUST</strong> as described in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC2119</a>.<br /> <strong>[D]</strong> - The requirement level for requirements which IDs start with the letter <em>D</em> is to be interpreted as <strong>SHOULD</strong> as described in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC2119</a>.<br /> <strong>[O]</strong> - The requirement level for requirements which IDs start with the letter <em>O</em> is to be interpreted as <strong>MAY</strong> as described in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc2119">RFC2119</a>.</p> <p>Note that requirements are uniquely numbered in ascending order within each requirement level.</p> <p>Example : It should be read that [R1] is an absolute requirement of the specification whereas [D1] is a recommendation and [O1] is truly optional.</p> <p>The requirements below are only valid for EVM based L1s, L2, or Sidechains. Address aliasing for non-EVM systems is out of scope of this document.</p> <p><a name="r1"> <strong>[R1]</strong> </a> An address alias -- <code>addressAlias</code> -- to be used between Chain A and Chain B MUST be constructed as follows: <code>addressAlias (Chain A) = offsetAlias (for Chain A) relativeAddress (on Chain A) offsetAlias (for Chain A)</code></p> <p><a href="https://wg-eips.ritovision.com/6735/#r1">[R1]</a> testability: <code>addressAlias</code> can be parsed and split using existing open source packages and the result compared to known <code>addressAlias</code> and <code>relativeAddress</code> used in the construction.</p> <p><a name="r2"> <strong>[R2]</strong> </a> The <code>offsetAlias</code> of a chain MUST be <code>0xchainId00000000000000000000000000000000chainId</code></p> <p><a href="https://wg-eips.ritovision.com/6735/#r2">[R2]</a> testability: <code>offsetAlias</code> can be parsed and split using existing open source packages and the result compared to known <code>chainId</code> used in the construction.</p> <p><a name="r3"> <strong>[R3]</strong> </a> The <code>chainId</code> used in the <code>offsetAlias</code> MUST NOT be zero (0)</p> <p><a href="https://wg-eips.ritovision.com/6735/#r3">[R3]</a> testability: A <code>chainId</code> is a numerical value and can be compared to <code>0</code>.</p> <p><a name="r4"> <strong>[R4]</strong> </a> The <code>chainId</code> used in the <code>offsetAlias</code> MUST be 8 bytes.</p> <p><a href="https://wg-eips.ritovision.com/6735/#r4">[R4]</a> testability: The length of the <code>chainId</code> string can be converted to bytes and then compared to <code>8</code>.</p> <p><a name="r5"> <strong>[R5]</strong> </a> In case the <code>chainId</code> has less than 16 digits the <code>chainId</code> MUST be padded with zeros to 16 digits.</p> <p>For example the <code>chainId</code> of Polygon PoS is <code>137</code>, with the current list of EVM based <code>chainId</code>s to be found at chainlist.org, and its <code>offsetAlias</code> is <code>0x0000000000000137000000000000000000000000000000000000000000000137</code>.</p> <p><a href="https://wg-eips.ritovision.com/6735/#r5">[R5]</a> testability: <code>chainId</code> can be parsed and split using existing open source packages and the result compared to known <code>chainId</code> used in the construction. Subsequently the number of zeros used in the padding can be computed and compared to the expected number of zeros for the padding.</p> <p><a name="r6"> <strong>[R6]</strong> </a> The <code>offsetAlias</code>for Ethereum Mainnet as the primary anchor of EVM based chains MUST be <code>0x1111000000000000000000000000000000001111</code> due to current adoption of this offset by existing L2 solutions.</p> <p>An example of address alias for the USDC asset would be <code>addressAlias = 0x1111A0b86991c6218b36c1d19D4a2e9Eb0cE3606eB481111</code></p> <p><a href="https://wg-eips.ritovision.com/6735/#r6">[R6]</a> testability: This requirement is a special case of <a href="https://wg-eips.ritovision.com/6735/#r1">[R1]</a>. Hence, it is testable.</p> <p><a name="r7"> <strong>[R7]</strong> </a> The <code>relativeAddress</code> of an Externally Owned Account (EOA) or Smart Contract on a chain MUST either be the smart contract or EOA address of the origin chain or a <code>relativeAddress</code> of an EOA or Smart Contract from another chain.</p> <p>An example of the former instance would be the relative address of wrapped USDC, <code>relativeAddress = 0x1111A0b86991c6218b36c1d19D4a2e9Eb0cE3606eB481111</code>, and an example of the latter would be the relative address of wrapped USDC on Polygon, <code>relativeAddress = 0x00000000000001371111A0b86991c6218b36c1d19D4a2e9Eb0cE3606eB4811110000000000000137</code>.</p> <p>Finally, an example of an address alias for a message to another L1, L2, or Sidechain for wrapped USDC from Ethereum on Arbitrum would be:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>addressAlias = 0x00000000000421611111A0b86991c6218b36c1d19D4a2e9Eb0cE3606eB4811110000000000042161</span></span></code></pre> <p><a href="https://wg-eips.ritovision.com/6735/#r7">[R7]</a> testability: Since this document is dealing with EVM-based systems with multiple live implementations, there are multiple known methods of how to verify if an address belongs to an EOA or a smart contract.</p> <p><a name="r8"> <strong>[R8]</strong> </a> The order of the <code>offsetAlias</code>es in an <code>addressAlias</code> MUST be ordered from the <code>offSetAlias</code> of the root chain bracketing the <code>relativeAddress</code> on the root chain through the ordered sequence of <code>offsetAlias</code>es of the chains on which the digital asset exists.</p> <p>For example, a valid <code>addressAlias</code> of an asset on chain A bridged to chain B and subsequently to chain C and that is to be bridged to yet another chain from chain C would be:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>addressAlias = chainId(C) chainId(B) chainId(A) relativeAddress chainId(A) chainId(B) chainId(C)</span></span></code></pre> <p>However, the reverse order is invalid:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>addressAlias = chainId(A) chainId(B) chainId(C) relativeAddress chainId(C) chainId(B) chainId(A)</span></span></code></pre> <p><a href="https://wg-eips.ritovision.com/6735/#r8">[R8]</a> testability: Since <a href="https://wg-eips.ritovision.com/6735/#r1">[R1]</a> is testable and since <a href="https://wg-eips.ritovision.com/6735/#r8">[R8]</a> is an order rule for the construction in <a href="https://wg-eips.ritovision.com/6735/#r1">[R1]</a>, which can be tested by applying logic operations on the output of <a href="https://wg-eips.ritovision.com/6735/#r1">[R1]</a> tests, <a href="https://wg-eips.ritovision.com/6735/#r8">[R8]</a> is testable.</p> <p>Note, that a proof that a given order is provably correct is beyond the scope of this document.</p> <h3 id="conformance">Conformance</h3> <p>This section describes the conformance clauses and tests required to achieve an implementation that is provably conformant with the requirements in this document.</p> <h4 id="conformance-targets">Conformance Targets</h4> <p>This document does not yet define a standardized set of test-fixtures with test inputs for all MUST, SHOULD, and MAY requirements with conditional MUST or SHOULD requirements.</p> <p>A standardized set of test-fixtures with test inputs for all MUST, SHOULD, and MAY requirements with conditional MUST or SHOULD requirements is intended to be published with the next version of the standard.</p> <h4 id="conformance-levels">Conformance Levels</h4> <p>This section specifies the conformance levels of this standard. The conformance levels offer implementers several levels of conformance. These can be used to establish competitive differentiation.</p> <p>This document defines the conformance levels of EVM based Address Aliasing as follows:</p> <ul> <li><strong>Level 1:</strong> All MUST requirements are fulfilled by a specific implementation as proven by a test report that proves in an easily understandable manner the implementation's conformance with each requirement based on implementation-specific test-fixtures with implementation-specific test-fixture inputs.</li> <li><strong>Level 2:</strong> All MUST and SHOULD requirements are fulfilled by a specific implementation as proven by a test report that proves in an easily understandable manner the implementation's conformance with each requirement based on implementation-specific test-fixtures with implementation-specific test-fixture inputs.</li> <li><strong>Level 3:</strong> All MUST, SHOULD, and MAY requirements with conditional MUST or SHOULD requirements are fulfilled by a specific implementation as proven by a test report that proves in an easily understandable manner the implementation's conformance with each requirement based on implementation-specific test-fixtures with implementation-specific test-fixture inputs.</li> </ul> <p><a name="d1"> <strong>[D1]</strong> </a> A claim that a canonical token list implementation conforms to this specification SHOULD describe a testing procedure carried out for each requirement to which conformance is claimed, that justifies the claim with respect to that requirement.</p> <p><a href="https://wg-eips.ritovision.com/6735/#d1">[D1]</a> testability: Since each of the non-conformance-target requirements in this documents is testable, so must be the totality of the requirements in this document. Therefore, conformance tests for all requirements can exist, and can be described as required in <a href="https://wg-eips.ritovision.com/6735/#d1">[D1]</a>.</p> <p><a name="r9"> <strong>[R9]</strong> </a> A claim that a canonical token list implementation conforms to this specification at <strong>Level 2</strong> or higher MUST describe the testing procedure carried out for each requirement at <strong>Level 2</strong> or higher, that justifies the claim to that requirement.</p> <p><a href="https://wg-eips.ritovision.com/6735/#r9">[R9]</a> testability: Since each of the non-conformance-target requirements in this documents is testable, so must be the totality of the requirements in this document. Therefore, conformance tests for all requirements can exist, be described, be built and implemented and results can be recorded as required in <a href="https://wg-eips.ritovision.com/6735/#r9">[R9]</a>.</p> <h2 id="rationale">Rationale</h2> <p>The standard follows an already existing approach for address aliasing from Ethereum (L1) to EVM-based L2s such as Arbitrum and Optimism and between L2s, and extends and generalizes it to allow aliasing across any type of EVM-based network irrespective of the network type -- L1, L2 or higher layer networks.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="data-privacy">Data Privacy</h3> <p>The standard does not set any requirements for compliance to jurisdiction legislation/regulations. It is the responsibility of the implementer to comply with applicable data privacy laws.</p> <h3 id="production-readiness">Production Readiness</h3> <p>The standard does not set any requirements for the use of specific applications/tools/libraries etc. The implementer should perform due diligence when selecting specific applications/tools/libraries.</p> <p>There are security considerations as to the Ethereum-type addresses used in the construction of the <code>relativeAddress</code>.</p> <p>If the Ethereum-type address used in the <code>relativeAddress</code> is supposed to be an EOA, the target system/recipient should validate that the <code>codehash</code> of the source account is <code>NULL</code> such that no malicious code can be executed surreptitiously in an asset transfer.</p> <p>If the Ethereum-type address used in the <code>relativeAddress</code> is supposed to be a smart contract account representing an asset, the target system/recipient should validate that the <code>codehash</code> of the source account matches the <code>codehash</code> of the published smart contract solidity code to ensure that the source smart contract behaves as expected.</p> <p>Lastly, it is recommended that as part of the <code>relativeAddress</code> validation the target system performs an address checksum validation as defined in <a href="https://wg-eips.ritovision.com/55/">ERC-55</a>.</p> <h3 id="internationalization-and-localization">Internationalization and Localization</h3> <p>Given the non-language specific features of EVM-based address aliasing, there are no internationalization/localization 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-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Andreas Freundhttps://github.com/Therecanbeonlyone1969 https://wg-eips.ritovision.com/4910/

Extension of ERC-721 to correctly define, process, and pay (hierarchical) onchain NFT royalties.

<h2 id="abstract">Abstract</h2> <p>The proposal directly connects NFTs and royalties in a smart contract architecture extending the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard, with the aim of precluding central authorities from manipulating or circumventing payments to those who are legally entitled to them.</p> <p>The proposal builds upon the OpenZeppelin Smart Contract Toolbox architecture, and extends it to include royalty account management (CRUD), royalty balance and payments management, simple trading capabilities -- Listing/De-Listing/Buying -- and capabilities to trace trading on exchanges. The royalty management capabilities allow for hierarchical royalty structures, referred to herein as royalty trees, to be established by logically connecting a "parent" NFT to its "children", and recursively enabling NFT "children" to have more children.</p> <h2 id="motivation">Motivation</h2> <p>The management of royalties is an age-old problem characterized by complex contracts, opaque management, plenty of cheating and fraud.</p> <p>The above is especially true for a hierarchy of royalties, where one or more assets is derived from an original asset such as a print from an original painting, or a song is used in the creation of another song, or distribution rights and compensation are managed through a series of affiliates.</p> <p>In the example below, the artist who created the original is eligible to receive proceeds from every sale, and resale, of a print.</p> <p><img src="https://wg-eips.ritovision.com/4910/./assets/eip-4910-print-families.png" alt="Fig1" /></p> <p>The basic concept for hierarchical royalties utilizing the above "ancestry concept" is demonstrated in the figure below.</p> <p><img src="https://wg-eips.ritovision.com/4910/./assets/eip-4910-royalties.png" alt="Fig2" /></p> <p>In order to solve for the complicated inheritance problem, this proposal breaks down the recursive problem of the hierarchy tree of depth N into N separate problems, one for each layer. This allows us to traverse the tree from its lowest level upwards to its root most efficiently.</p> <p>This affords creators, and the distributors of art derived from the original, the opportunity to achieve passive income from the creative process, enhancing the value of an NFT, since it now not only has intrinsic value but also comes with an attached cash 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> <h3 id="outline">Outline</h3> <p>This proposal introduces several new concepts as extensions to the ERC-721 standard that warrant explanation:</p> <ul> <li><strong>Royalty Account (RA)</strong> <ul> <li>A Royalty Account is attached to each NFT through its <code>tokenId</code> and consists of several sub-accounts which can be accounts of individuals or other RAs. A Royalty Account is identified by an account identifier.</li> </ul> </li> <li><strong>Account Type</strong> <ul> <li>This specifies if an RA Sub Account belongs to an individual (user) or is another RA. If there is another RA as an RA Sub Account, the allocated balance needs to be reallocated to the Sub Accounts making up the referenced RA.</li> </ul> </li> <li><strong>Royalty Split</strong> <ul> <li>The percentage each Sub Account receives based on a sale of an NFT that is associated with an RA</li> </ul> </li> <li><strong>Royalty Balance</strong> <ul> <li>The royalty balance associated with an RA</li> </ul> </li> <li><strong>Sub Account Royalty Balance</strong> <ul> <li>The royalty balance associated to each RA Sub Account. Note that only individual accounts can carry a balance that can be paid out. That means that if an RA Sub Account is an RA, its final Sub Account balance must be zero, since all RA balances must be allocated to individual accounts.</li> </ul> </li> <li><strong>Token Type</strong> <ul> <li>Token Type is given as either ETH or the symbol of the supported utility tokens such as <code>DAI</code></li> </ul> </li> <li><strong>Asset ID</strong> <ul> <li>This is the <code>tokenId</code> the RA belongs to.</li> </ul> </li> <li><strong>Parent</strong> <ul> <li>This indicates which <code>tokenId</code> is the immediate parent of the <code>tokenId</code> to which an RA belongs.</li> </ul> </li> </ul> <p>Below a non-normative overview is given of the data structures and functionality that are covered by the requirements in this document.</p> <h4 id="data-structures">Data Structures</h4> <p>In order to create an interconnected data structure linking NFTs to RAs certain global data structures are required:</p> <ul> <li>A Royalty Account and associated Royalty Sub Accounts to establish the concept of a Royalty Account with sub accounts.</li> <li>Connecting a <code>tokenId</code> to a Royalty Account identifier.</li> <li>A structure mapping parent-to-child NFT relationships.</li> <li>A listing of token types and last validated balance (for trading and royalty payment purposes)</li> <li>A listing of registered payments to be made in the <code>executePayment</code> function and validated in <code>safeTransferFrom</code>. This is sufficient, because a payment once received and distributed in the <code>safeTransferFrom</code> function will be removed from the listing.</li> <li>A listing of NFTs to be sold</li> </ul> <h4 id="royalty-account-functions">Royalty Account Functions</h4> <p>Definitions and interfaces for the Royalty Account RUD (Read-Update-Delete) functions. Because the RA is created in the minting function, there is no need to have a function to create a royalty account separately.</p> <h4 id="minting-of-a-royalty-bearing-nft">Minting of a Royalty Bearing NFT</h4> <p>When an NFT is minted, an RA must be created and associated with the NFT and the NFT owner, and, if there is an ancestor, with the ancestor's RA. To this end the specification utilizes the <code>_safemint</code> function in a newly defined <code>mint</code> function and applies various business rules on the input variables.</p> <h4 id="listing-nfts-for-sale-and-removing-a-listing">Listing NFTs for Sale and removing a Listing</h4> <p>Authorized user addresses can list NFTs for sale for non-exchange mediated NFT purchases.</p> <h4 id="payment-function-from-buyer-to-seller">Payment Function from Buyer to Seller</h4> <p>To avoid royalty circumvention, a buyer will always pay the NFT contract directly and not the seller. The seller is paid through the royalty distribution and can later request a payout.</p> <p>The payment process depends on whether the payment is received in ETH or an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token:</p> <ul> <li>ERC-20 Token <ol> <li>The Buyer must <code>approve</code> the NFT contract for the purchase price, <code>payment</code> for the selected payment token (ERC-20 contract address).</li> <li>For an ERC-20 payment token, the Buyer must then call the <code>executePayment</code> in the NFT contract -- the ERC-20 is not directly involved.</li> </ol> </li> <li>For a non-ERC-20 payment, the Buyer must send a protocol token (ETH) to the NFT contract, and is required to send <code>msg.data</code> encoded as an array of purchased NFTs <code>uint256[] tokenId</code>.</li> </ul> <h4 id="modified-nft-transfer-function-including-required-trade-data-to-allocate-royalties">Modified NFT Transfer Function including required Trade data to allocate Royalties</h4> <p>The input parameters must satisfy several requirements for the NFT to be transferred AFTER the royalties have been properly distributed. Furthermore, the ability to transfer more than one token at a time is also considered.</p> <p>The proposal defines:</p> <ul> <li>Input parameter validation</li> <li>Payment Parameter Validation</li> <li>Distributing Royalties</li> <li>Update Royalty Account ownership with payout</li> <li>Transferring Ownership of the NFT</li> <li>Removing the Payment entry in <code>registeredPayment</code> after successful transfer</li> </ul> <p>Lastly, the approach to distributing royalties is to break down the hierarchical structure of interconnected Royalty Accounts into layers and then process one layer at time, where each relationship between a token and its ancestor is utilized to traverse the Royalty Account chain until the root ancestor and associated RA is reached.</p> <h4 id="paying-out-royalties-to-the-nft-owner-from-address-in-safetransferfrom-function">Paying out Royalties to the NFT Owner -- <code>from</code> address in <code>safeTransferFrom</code> Function</h4> <p>This is the final part of the proposal.</p> <p>There are two versions of the payout function -- a <code>public</code> function and an <code>internal</code> function.</p> <p>The public function has the following interface:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function royaltyPayOut (uint256 tokenId, address RAsubaccount, address payable payoutAccount, uint256 amount) public virtual nonReentrant returns (bool)</span></span></code></pre> <p>where we only need the <code>tokenId</code>, the RA Sub Account address, <code>_RAsubaccount</code> which is the <code>owner</code>, and the amount to be paid out, <code>_amount</code>. Note that the function has <code>nonReentrant</code> modifier protection, because funds are being payed out.</p> <p>To finally send a Payout payment, the following steps need to be taken:</p> <ul> <li>find the RA Sub Account based on <code>RAaccount</code> and the <code>subaccountPos</code> and extract the balance</li> <li>extract <code>tokenType</code> from the Sub Account</li> <li>based on the token type, send the payout payment (not exceeding the available balance)</li> </ul> <h3 id="data-structures-1">Data Structures</h3> <h4 id="royalty-account-and-royalty-sub-accounts">Royalty Account and Royalty Sub Accounts</h4> <p>In order to create an interconnected data structure linking NFTs to RAs that is search optimized requires to make the following additions to the global data structures of an ERC-721.</p> <p>Note, a Royalty Account is defined as a collection of Royalty Sub Accounts linked to a meta account. This meta account is comprised of general account identifiers particular to the NFT it is linked to such as asset identifier, parent identifier etc.</p> <p><a name="r1"><strong>[R1]</strong></a> <em>One or more Royalty Sub-Account MUST be linked to a Royalty Account.</em></p> <p><a name="r2"><strong>[R2]</strong></a> <em>The account identifier of a Royalty Account, <code>raAccountId</code>, MUST be unique.</em></p> <p><a name="r3"><strong>[R3]</strong></a> <em>The <code>tokenId</code> of a NFT MUST be linked to a <code>raAccountID</code> in order to connect an <code>raAccountId</code> to a <code>tokenId</code>.</em></p> <h4 id="print-child-nfts">Print (Child) NFTs</h4> <p>The set of requirement to manage Parent-Child NFT Relationships and constraints at each level of the NFT (family) tree e.g. number of children permitted, NFT parents have to be linked to their immediate NFT children are as follows.</p> <p><a name="r4"><strong>[R4]</strong></a> <em>There MUST be a link for direct parent-child relationships</em></p> <h4 id="nft-payment-tokens">NFT Payment Tokens</h4> <p>In order to capture royalties, an NFT contract must be involved in NFT trading. Therefore, the NFT contract needs to be aware of NFT payments, which in turn requires the NFT contract to be aware which tokens can be used for trading.</p> <p><a name="r5"><strong>[R5]</strong></a> <em>There MUST be a listing of supported token types</em></p> <p>Since the NFT contract is managing royalty distributions and payouts as well as sales, it needs to track the last available balances of the allowed token types owned by the contract.</p> <p><a name="r6"><strong>[R6]</strong></a> <em>There MUST be a link of the last validated balance of an allowed token type in the contract to the respective allowed token contract.</em></p> <h4 id="nft-listings-and-payments">NFT Listings and Payments</h4> <p>Since the contract is directly involved in the sales process, a capability to list one or more NFTs for sale is required.</p> <p><a name="r7"><strong>[R7]</strong></a> <em>There MUST be a list of NFTs for sale.</em></p> <p><a name="r8"><strong>[R8]</strong></a> <em>A sales listing MUST have a unique identifier.</em></p> <p>Besides listings, the contract is required to manage sales as well. This requires the capability to register a payment, either for immediate execution or for later payment such as in an auction situation.</p> <p><a name="r9"><strong>[R9]</strong></a> <em>There MUST be a listing for registered payments</em></p> <p><a name="r10"><strong>[R10]</strong></a> <em>A registered payment MUST have a unique identifier.</em></p> <h4 id="contract-constructor-and-global-variables-and-their-update-functions">Contract Constructor and Global Variables and their update functions</h4> <p>This standard extends the current ERC-721 constructor, and adds several global variables to recognize the special role of the creator of an NFT, and the fact that the contract is now directly involved in managing sales and royalties.</p> <p><a name="r11"><strong>[R11]</strong></a> <em>The minimal contract constructor MUST contain the following input elements.</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>///</span></span> <span class="giallo-l"><span>/// @dev Definition of the contract constructor</span></span> <span class="giallo-l"><span>///</span></span> <span class="giallo-l"><span>/// @param name as in ERC-721</span></span> <span class="giallo-l"><span>/// @param symbol as in ERC-721</span></span> <span class="giallo-l"><span>/// @param baseTokenURI as in ERC-721</span></span> <span class="giallo-l"><span>/// @param allowedTokenTypes is the array of allowed tokens for payment</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> string memory baseTokenURI,</span></span> <span class="giallo-l"><span> address[] memory allowedTokenTypes</span></span> <span class="giallo-l"><span> ) ERC721(name, symbol) {...}</span></span></code></pre><h3 id="royalty-account-management">Royalty Account Management</h3> <p>Below are the definitions and interfaces for the Royalty Account RUD (Read-Update-Delete) functions. Since a Royalty Account is created in the NFT minting function, there is no need to have a separate function to create a royalty account.</p> <h4 id="get-a-royalty-account">Get a Royalty Account</h4> <p>There is only one get function required because a Royalty Account and its sub accounts can be retrieved through the <code>tokenId</code> in the <code>ancestry</code> field of the Royalty Account.</p> <p><a name="r12"><strong>[R12]</strong></a> <em>The <code>getRoyaltyAccount</code> function interface MUST adhere to the definition below:</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/// @dev Function to fetch a Royalty Account for a given tokenId</span></span> <span class="giallo-l"><span>/// @param tokenId is the identifier of the NFT to which a Royalty Account is attached</span></span> <span class="giallo-l"><span>/// @param RoyaltyAccount is a data structure containing the royalty account information</span></span> <span class="giallo-l"><span>/// @param RASubAccount[] is an array of data structures containing the information of the royalty sub accounts associated with the royalty account</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function getRoyaltyAccount (uint256 tokenId) public view virtual returns (address,</span></span> <span class="giallo-l"><span> RoyaltyAccount memory,</span></span> <span class="giallo-l"><span> RASubAccount[] memory);</span></span></code></pre> <p><a name="r13"><strong>[R13]</strong></a> <em>The following business rules MUST be enforced in the <code>getRoyaltyAccount</code> function:</em></p> <ul> <li><em><code>tokenId</code> exists and is not burned</em></li> </ul> <h4 id="update-a-royalty-account">Update a Royalty Account</h4> <p>In order to update a Royalty Account, the caller must have both the 'tokenId' and the <code>RoyaltyAccount</code> itself which can be obtained from the Royalty Account getter function.</p> <p><a name="r14"><strong>[R14]</strong></a> <em>The <code>updateRoyaltyAccount</code> function interface MUST adhere to the definition below:</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/// @dev Function to update a Royalty Account and its Sub Accounts</span></span> <span class="giallo-l"><span>/// @param tokenId is the identifier of the NFT to which the Royalty Account to be updated is attached</span></span> <span class="giallo-l"><span>/// @param RoyaltyAccount is the Royalty Account and associated Royalty Sub Accounts with updated values </span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function updateRoyaltyAccount (uint256 _tokenId, `RoyaltyAccount memory _raAccount) public virtual returns (bool)</span></span></code></pre> <p>The update functionality of a Royalty Account, while straightforward, is also highly nuanced. To avoid complicated change control rules such as multi-signature rules, Royalty Account changes are kept simple.</p> <p><a name="r15"><strong>[R15]</strong></a> <em>The business rules for the update function are as follows:</em></p> <ol> <li> <p><em>An NFTs asset identifier MUST NOT be changed.</em></p> </li> <li> <p><em>An NFTs ancestor MUST NOT be updated.</em></p> </li> <li> <p><em>An NFTs token type accepted for payment MUST NOT be updated.</em></p> </li> <li> <p><em>The royalty balance in a Royalty Sub Account MUST NOT be changed.</em></p> </li> <li> <p><em>The royalty split inherited by the children from the NFT parent MUST NOT be changed.</em></p> </li> <li> <p><em>New royalty split values MUST be larger than, or less than, or equal to any established boundary value for royalty splits, if it exists.</em></p> </li> <li> <p><em>The number of existing Royalty Sub Account plus the number of new Royalty Sub Accounts to be added MUST be smaller or equal to an established boundary value, if it exists.</em></p> </li> <li> <p><em>The sum of all royalty splits across all existing and new Royalty Sub Accounts MUST equal to 1 or its equivalent numerical value at all times.</em></p> </li> <li> <p><em>'msg.sender` MUST be equal to an account identifier in the Royalty Sub Account of the Royalty Account to be modified and that royalty sub account must be identified as not belonging to the parent NFT</em></p> <p>9.1 <em>the Sub Account belonging to the account identifier MUST NOT be removed</em></p> <p>9.2 <em>A royalty split MUST only be decreased, and either the existing sub account's royalty split MUST be increased accordingly such that the sum of all royalty splits remains equal to 1 or its numerical equivalent, or one or more new Royalty Sub Accounts MUST be added according to rule 10.</em></p> <p>9.3 <em>a royalty balance MUST NOT be changed</em></p> <p>9.4 <em>an account identifier MUST NOT be NULL</em></p> </li> <li> <p><em>If <code>msg.sender</code> is equal to the account identifier of one of the Sub Account owners which is not the parent NFT, an additional Royalty Sub Accounts MAY be added</em></p> <p>10.1 <em>if the royalty split of the Royalty Sub Account belonging to <code>msg.sender</code> is reduced</em></p> <ul> <li> <p>then the royalty balance in each new Royalty Sub Account MUST be zero</p> </li> <li> <p>and the sum of the new royalty splits data MUST be equal to the royalty split of the Royalty Sub Account of <code>msg.sender</code> before it was modified</p> </li> </ul> <p>10.2 <em>new account identifier MUST not be NULL</em></p> </li> <li> <p><em>If the Royalty Account update is correct, the function returns <code>true</code>, otherwise <code>false</code>.</em></p> </li> </ol> <h4 id="deleting-a-royalty-account">Deleting a Royalty Account</h4> <p>While sometimes deleting a Royalty Account is necessary, even convenient, it is a very costly function in terms of gas, and should not be used unless one is absolutely sure that the conditions enumerated below are met.</p> <p><a name="r16"><strong>[R16]</strong></a> <em>The <code>deleteRoyaltyAccount</code> function interface MUST adhere to the definition below:</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/// @dev Function to delete a Royalty Account</span></span> <span class="giallo-l"><span>/// @param tokenId is the identifier of the NFT to which the Royalty Account to be updated is attached</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function deleteRoyaltyAccount (uint256 _tokenId) public virtual returns (bool)</span></span></code></pre> <p><a name="r17"><strong>[R17]</strong></a> <em>The business rules for this function are as follows:</em></p> <ul> <li><em><code>_tokenId</code> MUST be burned, i.e., have owner <code>address(0)</code>.</em></li> <li><em>all <code>tokenId</code> numbers genealogically related to <code>_tokenId</code> either as ancestors or offspring MUST also be burnt.</em></li> <li><em>all balances in the Royalty Sub Accounts MUST be zero.</em></li> </ul> <h3 id="nft-minting">NFT Minting</h3> <p>In extension to the ERC-721 minting capability, a Royalty Account with Royalty Sub Accounts are required to be added during the minting, besides establishing the NFT token specific data structures supporting constraints such as the maximum number of children an NFT can have.</p> <p><a name="r18"><strong>[R18]</strong></a> <em>When a new NFT is minted a Royalty Account with one or more Royalty Sub Accounts MUST be created and associated with the NFT and the NFT owner, and, if there is an ancestor, with the ancestor's Royalty Account.</em></p> <p>To this end the specification utilizes the ERC-721 <code>_safemint</code> function in a newly defined <code>mint</code> function, and applies various business rules on the function's input variables.</p> <p><a name="d1"><strong>[D1]</strong></a> <em>Note, that the <code>mint</code> function SHOULD have the ability to mint more than one NFT at a time.</em></p> <p><a name="r19"><strong>[R19]</strong></a> <em>Also, note that the <code>owner</code> of a new NFT MUST be the NFT contract itself.</em></p> <p><a name="r20"><strong>[R20]</strong></a> <em>The non-contract owner of the NFT MUST be set as <code>isApproved</code> which allows the non-contract owner to operate just like the <code>owner</code>.</em></p> <p>This strange choice in the two requirements above is necessary, because the NFT contract functions as an escrow for payments and royalties, and, hence, needs to be able to track payments received from buyers and royalties due to recipients, and to associate them with a valid <code>tokenId</code>.</p> <p><a name="r21"><strong>[R21]</strong></a> <em>For compactness of the input, and since the token meta data might vary from token to token the MUST be a minimal data structure containing:</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/// @param parent is the parent tokenId of the (child) token, and if set to 0 then there is no parent.</span></span> <span class="giallo-l"><span>/// @param canBeParent indicates if a tokenId can have children or not.</span></span> <span class="giallo-l"><span>/// @param maxChildren defines how many children an NFT can have.</span></span> <span class="giallo-l"><span>/// @param royaltySplitForItsChildren is the royalty percentage split that a child has to pay to its parent.</span></span> <span class="giallo-l"><span>/// @param uri is the unique token URI of the NFT</span></span></code></pre> <p><a name="r22"><strong>[R22]</strong></a> <em>The <code>mint</code> function interface MUST adhere to the definition below:</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/// @dev Function creates one or more new NFTs with its relevant meta data necessary for royalties, and a Royalty Account with its associated met data for `to` address. The tokenId(s) will be automatically assigned (and available on the emitted {IERC-721-Transfer} event).</span></span> <span class="giallo-l"><span>/// @param to is the address to which the NFT(s) are minted</span></span> <span class="giallo-l"><span>/// @param nfttoken is an array of struct type NFTToken for the meta data of the minted NFT(s)</span></span> <span class="giallo-l"><span>/// @param tokenType is the type of allowed payment token for the NFT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function mint(address to, NFTToken[] memory nfttoken, address tokenType) public virtual</span></span></code></pre> <p><a name="r23"><strong>[R23]</strong></a> <em>The following business rules for the <code>mint</code> function's input data MUST be fulfilled:</em></p> <ul> <li><em>The number of tokens to be minted MUST NOT be zero.</em></li> <li><em><code>msg.sender</code> MUST have either the <code>MINTER_ROLE</code> or the <code>CREATOR_Role</code> identifying the creator of the first NFT.</em></li> <li><em><code>to</code> address MUST NOT be the zero address.</em></li> <li><em><code>to</code> address MUST NOT be a contract, unless it has been whitelisted -- see <a href="https://wg-eips.ritovision.com/4910/#security-considerations">Security Considerations</a> for more details.</em></li> <li><em><code>tokenType</code> MUST be a token type supported by the contract.</em></li> <li><em><code>royaltySplitForItsChildren</code> MUST be less or equal to 100% or numerical equivalent thereof less any constraints such as platform fees</em></li> <li><em>If the new NFT(s) cannot have children, <code>royaltySplitForItsChildren</code> MUST be zero.</em></li> <li><em>If the new NFT(s) has a parent, the parent NFT <code>tokenId</code> MUST exist.</em></li> <li><em>The ancestry level of the parent MUST be less than the maximum number of allowed NFT generations, if specified.</em></li> <li><em>The number of allowed children for an NFT to be minted MUST be less than the maximum number of allowed children, if specified.</em></li> </ul> <h3 id="listing-and-de-listing-of-nfts-for-direct-sales">Listing and De-Listing of NFTs for Direct Sales</h3> <p>In the sales process, we need to minimally distinguish two types of transactions</p> <ul> <li>Exchange-mediated sales</li> <li>Direct sales</li> </ul> <p>The first type of transaction does not require that the smart contract is aware of a sales listing since the exchange contract will trigger payment and transfer transactions directly with the NFT contract as the owner. However, for the latter transaction type it is essential, since direct sales are required to be mediated at every step by the smart contract.</p> <p><a name="r24"><strong>[R24]</strong></a> <em>For direct sales, NFT listing, und de-listing, transactions MUST be executed through the NFT smart contract.</em></p> <p>Exchange-mediated sales will be discussed when this document discusses payments.</p> <p>In direct sales, authorized user addresses can list NFTs for sale, see the business rules below.</p> <p><a name="r25"><strong>[R25]</strong></a> <em>The <code>listNFT</code> function interface MUST adhere to the definition below:</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/// @dev Function to list one or more NFTs for direct sales</span></span> <span class="giallo-l"><span>/// @param tokenIds is the array of tokenIds to be included in the listing</span></span> <span class="giallo-l"><span>/// @param price is the price set by the owner for the listed NFT(s)</span></span> <span class="giallo-l"><span>/// @param tokenType is the payment token type allowed for the listing</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function listNFT (uint256[] calldata tokenIds, uint256 price, address tokenType) public virtual returns (bool)</span></span></code></pre> <p>The Boolean return value is <code>true</code> for a successful function execution, and <code>false</code> for an unsuccessful function execution.</p> <p><a name="r26"><strong>[R26]</strong></a> <em>The business rules of the <code>listNFT</code> function are as follows:</em></p> <ul> <li>there MUST NOT already be a listing for one or more NFTs in the <code>listedNFT</code> mapping of the proposed listing.</li> <li><code>seller</code> MUST be equal to <code>getApproved(tokenId[i])</code> for all NFTs in the proposed listing.</li> <li><code>tokenType</code> MUST be supported by the smart contract.</li> <li><code>price</code> MUST be larger than <code>0</code>.</li> </ul> <p><a name="r27"><strong>[R27]</strong></a> <em>If the conditions in <a href="https://wg-eips.ritovision.com/4910/#r26"><strong>[R26]</strong></a> are met, then the NFT sales list MUST be updated.</em></p> <p>Authorized user addresses can also remove a direct sale listing of NFTs.</p> <p><a name="r28"><strong>[R28]</strong></a> <em>The <code>removeNFTListing</code> function interface MUST adhere to the definition below:</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/// @dev Function to de-list one or more NFTs for direct sales</span></span> <span class="giallo-l"><span>/// @param listingId is the identifier of the NFT listing</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function removeNFTListing (uint256 listingId) public virtual returns (bool)</span></span></code></pre> <p>The Boolean return value is <code>true</code> for a successful function execution, and <code>false</code> for an unsuccessful function execution.</p> <p><a name="r29"><strong>[R29]</strong></a> <em>The business rules of the <code>removeNFTListing</code> function below MUST be adhered to:</em></p> <ul> <li><em>the registered payment entry MUST be NULL</em></li> <li><em><code>msg.sender = getApproved(tokenId)</code> for the NFT listing</em></li> </ul> <p><a name="r30"><strong>[R30]</strong></a> <em>If the conditions in <a href="https://wg-eips.ritovision.com/4910/#r29"><strong>[R29]</strong></a> are met, then the NFT sales listing MUST be removed.</em></p> <h3 id="payments-for-nft-sales">Payments for NFT Sales</h3> <p>As noted before, a buyer will always pay the NFT contract directly and not the seller. The seller is paid through the royalty distribution and can later request a payout to their wallet.</p> <p><a name="r31"><strong>[R31]</strong></a> <em>The payment process requires either one or two steps:</em></p> <ol> <li><em>For an ERC-20 token</em> <ul> <li><em>The buyer MUST <code>approve</code> the NFT contract for the purchase price, <code>payment</code>, for the selected payment token type.</em></li> <li><em>The buyer MUST call the <code>executePayment</code> function.</em></li> </ul> </li> <li><em>For a protocol token</em> <ul> <li><em>The buyer MUST call a payment fallback function with <code>msg.data</code> not NULL.</em></li> </ul> </li> </ol> <p><a name="r32"><strong>[R32]</strong></a> <em>For an ERC-20 token type, the required <code>executePayment</code> function interface MUST adhere to the definition below</em>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/// @dev Function to make a NFT direct sales or exchange-mediate sales payment</span></span> <span class="giallo-l"><span>/// @param receiver is the address of the receiver of the payment</span></span> <span class="giallo-l"><span>/// @param seller is the address of the NFT seller </span></span> <span class="giallo-l"><span>/// @param tokenIds are the tokenIds of the NFT to be bought</span></span> <span class="giallo-l"><span>/// @param payment is the amount of that payment to be made</span></span> <span class="giallo-l"><span>/// @param tokenType is the type of payment token</span></span> <span class="giallo-l"><span>/// @param trxnType is the type of payment transaction -- minimally direct sales or exchange-mediated</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function executePayment (address receiver, address seller, uint 256[] tokenIds, uint256 payment, string tokenType, int256 trxnType) public virtual nonReentrant returns (bool)</span></span></code></pre> <p>The Boolean return value is <code>true</code> for a successful function execution, and <code>false</code> for an unsuccessful function execution.</p> <p><a name="r33"><strong>[R33]</strong></a> <em>Independent of <code>trxnType</code>, the business rules for the input data are as follows:</em></p> <ul> <li><em>All purchased NFTs in the <code>tokenIds</code> array MUST exist and MUST NOT be burned.</em></li> <li><em><code>tokenType</code> MUST be a supported token.</em></li> <li><em><code>trxnType</code> MUST be set to either <code>0</code> (direct sale) or <code>1</code> (exchange-mediate sale), or another supported type.</em></li> <li><em><code>receiver</code> MAY be NULL but MUST NOT be the Zero Address.</em></li> <li><em><code>seller</code> MUST be the address in the corresponding listing.</em></li> <li><em><code>msg.sender</code> MUST not be a contract, unless it is whitelisted in the NFT contract.</em></li> </ul> <p>In the following, this document will only discuss the differences between the two minimally required transaction types.</p> <p><a name="r34"><strong>[R34]</strong></a> <em>For <code>trxnType = 0</code>, the payment data MUST to be validated against the listing, based on the following rules:</em></p> <ul> <li><em>NFT(s) MUST be listed</em></li> <li><em><code>payment</code> MUST be larger or equal to the listing price.</em></li> <li><em>The listed NFT(s) MUST match the NFT(s) in the payment data.</em></li> <li><em>The listed NFT(s) MUST be controlled by <code>seller</code>.</em></li> </ul> <p><a name="r35"><strong>[R35]</strong></a> <em>If all checks in <a href="https://wg-eips.ritovision.com/4910/#r33"><strong>[R33]</strong></a>, and in <a href="https://wg-eips.ritovision.com/4910/#r34"><strong>[R34]</strong></a> for <code>trxnType = 0</code>, are passed, the <code>executePayment</code> function MUST call the <code>transfer</code> function in the ERC-20 contract identified by <code>tokenType</code> with <code>recipient = address(this)</code> and <code>amount = payment</code>.</em></p> <p>Note the NFT contract pays itself from the available allowance set in the <code>approve</code> transaction from the buyer.</p> <p><a name="r36"><strong>[R36]</strong></a> <em>For <code>trxnType = 1</code>, and for a successful payment, the <code>registeredPayment</code> mapping MUST updated with the payment, such that it can be validated when the NFT is transferred in a separate <code>safeTransferFrom</code> call, and <code>true</code> MUST be returned as the return value of the function, if successful, <code>false</code> otherwise.</em></p> <p><a name="r37"><strong>[R37]</strong></a> <em>For <code>trxnType = 0</code>, an <code>internal</code> version of the <code>safeTransferFrom</code> function with message data MUST be called to transfer the NFTs to the buyer, and upon success, the buyer MUST be given the <code>MINTER_ROLE</code>, unless the buyer already has that role.</em></p> <p>Note, the <code>_safeTransferFrom</code> function has the same structure as <code>safeTransferFrom</code> but skips the input data validation.</p> <p><a name="r38"><strong>[R38]</strong></a> <em>For <code>trxnType = 0</code>, and if the NFT transfer is successful, the listing of the NFT MUST be removed.</em></p> <p><a name="r39"><strong>[R39]</strong></a> <em>For a protocol token as a payment token, and independent of <code>trxnType</code>, the buyer MUST send protocol tokens to the NFT contract as the escrow, and <code>msg.data</code> MUST encode the array of paid for NFTs <code>uint256[] tokenIds</code>.</em></p> <p><a name="r40"><strong>[R40]</strong></a> <em>For the NFT contract to receive a protocol token, a payable fallback function (<code>fallback() external payable</code>) MUST be implemented.</em></p> <p>Note that since the information for which NFTs the payment was for must be passed, a simple <code>receive()</code> fallback function cannot be allowed since it does not allow for <code>msg.data</code> to be sent with the transaction.</p> <p><a name="r41"><strong>[R41]</strong></a> <em><code>msg.data</code> for the fallback function MUST minimally contain the following data: <code>address memory seller, uint256[] memory _tokenId, address memory receiver, int256 memory trxnType</code></em></p> <p><a name="r42"><strong>[R42]</strong></a> <em>If <code>trxnType</code> is not equal to either '0' or '1', or another supported type, then the fallback function MUST <code>revert</code>.</em></p> <p><a name="r43"><strong>[R43]</strong></a> <em>For <code>trxnType</code> equal to either '0' or '1', the requirements <a href="https://wg-eips.ritovision.com/4910/#r33"><strong>[R33]</strong></a> through <a href="https://wg-eips.ritovision.com/4910/#r38"><strong>[R38]</strong></a> MUST be satisfied for the fallback function to successfully execute, otherwise the fallback function MUST <code>revert</code>.</em></p> <p><a name="r44"><strong>[R44]</strong></a> <em>In case of a transaction failure (for direct sales, <code>trxnType = 0</code>), or the buyer of the NFT listing changing their mind (for exchange-mediated sales, <code>trxnType = 1</code>), the submitted payment MUST be able to revert using the <code>reversePayment</code> function where the function interface is defined below:</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/// @dev Definition of the function enabling the reversal of a payment before the sale is complete</span></span> <span class="giallo-l"><span>/// @param paymentId is the unique identifier for which a payment was made</span></span> <span class="giallo-l"><span>/// @param tokenType is the type of payment token used in the payment</span></span> <span class="giallo-l"><span>function reversePayment(uint256 paymentId, string memory tokenType) public virtual returns (bool)</span></span></code></pre> <p>The Boolean return value is <code>true</code> for a successful function execution, and <code>false</code> for an unsuccessful function execution.</p> <p>Note, <code>reentrancy</code> protection through e.g. <code>nonReentrant</code> from the Open Zeppelin library is strongly advised since funds are being paid out.</p> <p><a name="r45"><strong>[R45]</strong></a> <em>The business rules for the <code>reversePayment</code> function are as follows:</em></p> <ul> <li><em>There MUST be registered payment for a given <code>paymentId</code> and <code>tokenType</code>.</em></li> <li><em><code>msg.sender</code> MUST be the buyer address in the registered payment.</em></li> <li><em>The payment amount must be larger than <code>0</code>.</em></li> <li><em>The registered payment MUST be removed when the payment has been successfully reverted, otherwise the function must fail.</em></li> </ul> <h3 id="modified-nft-transfer-function">Modified NFT Transfer function</h3> <p>This document adheres to the ERC-721 interface format for the <code>safeTransferFrom</code> function as given below:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function safeTransferFrom(address from, address to, uint256 tokenId, bytes memory _data) external virtual override</span></span></code></pre> <p>Note, that the input parameters must satisfy several requirements for the NFT(s) to be transferred AFTER royalties have been properly distributed. Note also, that the ability to transfer more than one token at a time is required. However, the standard interface only allows one token to be transferred at a time. In order to remain compliant with the ERC-721 standard, this document uses <code>tokenId</code> only for the first NFT to be transferred. All other transfer relevant data is encoded in <code>_data</code>.</p> <p>The high-level requirements are as follows:</p> <ul> <li>The payment parameters of the trade encoded in <code>_data</code> must be validated.</li> <li>The seller and the sold NFT token(s) must exist, and the seller must be the owner of the token.</li> <li><code>msg.sender</code> must be the seller address or an approved address.</li> <li>the payment of the trade received by the NFT smart contract is correctly disbursed to all Royalty Sub Account owners.</li> <li>the NFT token is transferred after all Royalty Sub Accounts and their holders associated with the NFT token(s) have been properly credited.</li> </ul> <p>Also, note that in order to avoid royalty circumvention attacks, there is only one NFT transfer function.</p> <p><a name="r46"><strong>[R46]</strong></a> <em>Therefore, <code>transferFrom</code> and <code>safeTransferFrom</code> without <code>data</code> MUST be disabled.</em></p> <p>This can be achieved through for example a <code>revert</code> statement in an <code>override</code> function.</p> <p><a name="r47"><strong>[R47]</strong></a> <em>The requirements on input parameters of the function are as follows</em>:</p> <ul> <li><em><code>from</code> MUST not be <code>address(0)</code>.</em></li> <li><em><code>from</code> MUST be the owner or <code>approved</code> for <code>tokenId</code> and the other tokens included in <code>_data</code>.</em></li> <li><em><code>from</code> MUST not be a smart contract unless whitelisted.</em></li> <li><em>a Royalty Account MUST be associated to <code>tokenId</code> and the other tokens included in <code>_data</code>.</em></li> <li><em><code>_data</code> MUST NOT be NULL.</em></li> <li><em><code>msg.sender</code> MUST be equal to <code>from</code> or an <code>approved</code> address, or a whitelisted contract.</em></li> </ul> <p>Note, that in the context of this document only the scenario where the calling contract is still being created, i.e., the constructor being executed is a possible attack vector, and should to be carefully treated in the transfer scenario.</p> <p>Turning to the <code>_data</code> object.</p> <p><a name="r48"><strong>[R48]</strong></a> <em>The <code>_data</code> object MUST minimally contain the following payment parameters:</em></p> <ul> <li><em>Seller Address as <code>address</code>.</em></li> <li><em>Buyer Address as <code>address</code>.</em></li> <li><em>Receiver Address as `address.</em></li> <li><em>Token identifiers as <code>uint256[]</code>.</em></li> <li><em>Token type used for payment.</em></li> <li><em>Payment amount paid to NFT contract as <code>uint256</code>.</em></li> <li><em>a registered payment identifier.</em></li> <li><em>blockchain ID, <code>block.chainid</code>, of the underlying blockchain.</em></li> </ul> <p><a name="r49"><strong>[R49]</strong></a> <em>The following business rules MUST be met for the payment data in '_data':</em></p> <ul> <li><em><code>seller == from</code>.</em></li> <li><em><code>tokenId[0] == tokenId</code>.</em></li> <li><em>Each token in <code>_tokenId</code> has an associated Royalty Account.</em></li> <li><em><code>chainid == block.chainid</code>.</em></li> <li><em><code>buyer</code> is equal to the buyer address in the registered payment for the given ``paymentId.</em></li> <li><em><code>receiver == to</code>.</em></li> <li><em>the receiver of the token is not the seller.</em></li> <li><em>the receiver of the token is not a contract or is a whitelisted contract</em></li> <li><em>For all NFTs in the payment, <code>tokenId[i] = registeredPayment[paymentId].boughtTokens[i]</code>.</em></li> <li><em><code>tokenType</code> is supported in the contract.</em></li> <li><em><code>allowedToken[tokenType]</code> is not NULL.</em></li> <li><em><code>tokenType = registeredPayment[paymentId].tokenType</code>.</em></li> <li><em><code>payment &gt; lastBalanceAllowedToken[allowedToken[listingId]]</code>.</em></li> <li><em><code>payment = registeredPayment[paymentId].payment</code>.</em></li> </ul> <h3 id="distributing-royalties-in-the-transfer-function">Distributing Royalties in the Transfer Function</h3> <p>The approach to distributing royalties is to break down the hierarchical structure of interconnected Royalty Accounts into layers, and then process one layer at time, where each relationship between a NFT and its ancestor is utilized to traverse the Royalty Account chain until the root ancestor and its associated Royalty Account.</p> <p>Note, that the distribution function assumes that the payment made is for ALL tokens in the requested transfer. That means, that <code>payment</code> for the distribution function is equally divided between all NFTs included in the payment.</p> <p><a name="r5"><strong>[R50]</strong></a> *The <code>distributePayment</code> function interface MUST adhere to the definition below:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/// @dev Function to distribute a payment as royalties to a chain of Royalty Accounts</span></span> <span class="giallo-l"><span>/// @param tokenId is a tokenId included in the sale and used to look up the associated Royalty Account</span></span> <span class="giallo-l"><span>/// @param payment is the payment (portion) to be distributed as royalties</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function distributePayment (uint256 tokenId, uint265 payment) internal virtual returns (bool)</span></span></code></pre> <p>The Boolean return value is <code>true</code> for a successful function execution, and <code>false</code> for an unsuccessful function execution.</p> <p>As mentioned before, the internal <code>distributePayment</code> function is called within the modified <code>safeTransferFrom</code> function.</p> <p>Note, that it is necessary to multiply two <code>uint256</code> numbers with each other -- the payment amount with the royalty split percentage expressed as a whole number e.g. <code>10000 = 100%</code>. And then divide the result by the whole number representing <code>100%</code> in order to arrive at the correct application of the royalty split percentage to the payment amount. This requires careful treatment of numbers in the implementation to prevent issues such as buffer over or under runs.</p> <p><a name="r51"><strong>[R51]</strong></a> <em>The processing logic of <code>distributePayment</code> function MUST be as follows:</em></p> <ul> <li><em>Load the Royalty Account (<code>RA</code>) and associated Royalty Sub Accounts using the passed <code>tokenId</code>.</em></li> <li><em>For each Royalty Sub Account in <code>RA</code> apply the following rules:</em> <ul> <li><em>If a Royalty Sub Account in <code>RA</code> has <code>isIndividual</code> set to <code>true</code> then</em> <ul> <li><em>apply the royalty percentage of that Royalty Sub Account to <code>payment</code> and add the calculated amount, e.g. <code>royaltyAmountTemp</code>, to the <code>royaltybalance</code> of that Royalty Sub Account.</em></li> <li><em>emit an event as a notification of payment to the <code>accountId</code> of the Royalty Sub Account containing: assetId, accountId, tokenType, royaltybalance.</em></li> <li><em>in the RA add <code>royaltyamountTemp</code> amount to <code>balance</code></em></li> </ul> </li> <li><em>If a Royalty Sub Account in <code>RA</code> has <code>isIndividual</code> set to <code>false</code> then</em> <ul> <li><em>apply the royalty percentage of that Royalty Sub Account to <code>payment</code> and store temporarily in a new variable e.g. <code>RApaymenttemp</code>, but do not update the <code>royaltybalance</code> of the Royalty Sub Account which remains <code>0</code>.</em></li> </ul> </li> <li><em>then use <code>ancestor</code> to obtain the <code>RA</code> connected to <code>ancestor</code> e.g. via a look up through a Royalty Account mapping.</em></li> <li><em>load the new RA</em> <ul> <li><em>if <code>isIndividual</code> of the Royalty Sub Account is set to <code>true</code>, pass through the Royalty Sub Accounts of the next <code>RA</code>, and apply the rule for <code>isIndividual = true</code>.</em></li> <li><em>if <code>isIndividual</code> of the Royalty Sub Account is set to <code>false</code>, pass through the Royalty Sub Accounts of the next <code>RA</code>, and apply the rule for <code>isIndividual = false</code>.</em></li> </ul> </li> <li><em>Repeat the procedures for <code>isIndividual</code> equal to <code>true</code> and <code>false</code> until a <code>RA</code> is reached that does not have an <code>ancestor</code>, and where all Royalty Sub Accounts have<code>isIndividual</code> set to <code>true</code>, and apply the rule for a Royalty Sub Account that has <code>isIndividual</code> set to <code>true</code> to all Royalty Sub Accounts in that <code>RA</code>.</em></li> </ul> </li> </ul> <h3 id="update-royalty-sub-account-ownership-with-payout-to-approved-address-from">Update Royalty Sub Account Ownership with Payout to approved Address (<code>from</code>)</h3> <p>In order to simplify the ownership transfer, first the approved address -- the non-contract NFT owner --, <code>from</code>, is paid out its share of the royalties. And then the Royalty Sub Account is updated with the new owner, <code>to</code>. This step repeats for each token to be transferred.</p> <p><a name="r52"><strong>[R52]</strong></a> <em>The business rules are as follows:</em></p> <ul> <li><em>the internal version of the<code>royaltyPayOut</code> function MUST pay out the entire royalty balance of the Royalty Sub Account owned by the <code>from</code> address to the <code>from</code> address.</em></li> <li><em>the Royalty Sub Account MUST only be updated with the new owner only once the payout function has successfully completed and the <code>royaltybalance = 0</code>.</em></li> </ul> <p>The last step in the process chain is transferring the NFTs in the purchase to the <code>to</code> address.</p> <p><a name="r53"><strong>[R53]</strong></a> <em>For every NFT (in the batch) the 'to' address MUST be `approved' (ERC-721 function) to complete the ownership transfer:</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>_approve(to, tokenId[i]);</span></span></code></pre> <p>The technical NFT owner remains the NFT contract.</p> <h3 id="removing-the-payment-entry-after-successful-transfer">Removing the Payment Entry after successful Transfer</h3> <p>Only after the real ownership of the NFT, the approved address, has been updated, the payment registry entry can be removed to allow the transferred NFTs to be sold again.</p> <p><a name="r54"><strong>[R54]</strong></a> <em>After the <code>approve</code> relationship has been successfully updated to the <code>to</code> address, the registered payment MUST be removed.</em></p> <h3 id="paying-out-royalties-to-the-from-address-in-safetransferfrom-function">Paying out Royalties to the <code>from</code> Address in <code>safeTransferFrom</code> Function</h3> <p>There are two versions of the payout function -- a <code>public</code> and an <code>internal</code> function -- depending on whether there is a payout during a purchase, or a payout is requested by a Royalty Sub Account owner.</p> <p><a name="r55"><strong>[R55]</strong></a> <em>The public <code>royaltyPayOut</code> function interface MUST adhere to the definition below:</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/// @dev Function to payout a royalty payment</span></span> <span class="giallo-l"><span>/// @param tokenId is the identifier of the NFT token</span></span> <span class="giallo-l"><span>/// @param RAsubaccount is the address of the Royalty Sub Account from which the payout should happen</span></span> <span class="giallo-l"><span>/// @param receiver is the address to receive the payout</span></span> <span class="giallo-l"><span>/// @param amount is the amount to be paid out</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function royaltyPayOut (uint256 tokenId, address RAsubaccount, address payable payoutAccount, uint256 amount) public virtual nonReentrant returns (bool)</span></span></code></pre> <p>The Boolean return value is <code>true</code> for a successful function execution, and <code>false</code> for an unsuccessful function execution.</p> <p>Note, that the function has <code>reentrancy</code> protection through <code>nonReentrant</code> from the Open Zeppelin library since funds are being paid out.</p> <p><a name="r56"><strong>[R56]</strong></a> <em>The input parameters of the <code>royaltyPayOut</code> function MUST satisfy the following requirements:</em></p> <ul> <li><em><code>msg.sender == RAsubaccount</code>.</em></li> <li><em><code>tokenId</code> must exist and must not be burned.</em></li> <li><em><code>tokenId</code> must be associated with a Royalty Account.</em></li> <li><em><code>RAsubaccount</code> must be a valid <code>accountId</code> in a Royalty Sub Account of the Royalty Account of the `tokenId'.</em></li> <li><em><code>isIndividual == true</code> for the Royalty Sub Account, <code>RAsubaccount</code>.</em></li> <li>*<code>amount &lt;= royaltybalance</code> of the Royalty Sub Account, <code>RAsubaccount.*</code></li> </ul> <p><a name="r57"><strong>[R57]</strong></a> <em>The internal <code>_royaltyPayOut</code> function interface MUST adhere to the definition below</em>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function _royaltyPayOut (uint256 tokenId, address RAsubaccount, address payable payoutAccount, uint256 amount) public virtual returns (bool)</span></span></code></pre> <p><a name="r58"><strong>[R58]</strong></a> *The internal <code>_royaltyPayOut</code> function MUST perform the following actions:</p> <ul> <li><em>send the payment to the <code>payoutaccount</code>.</em></li> <li><em>update the <code>royaltybalance</code> of the <code>RAsubaccount</code> of the Royalty Account upon successful transfer.</em></li> </ul> <p><a name="r59"><strong>[R59]</strong></a> <em>The following steps MUST be taken to send out a royalty payment to its recipient:</em></p> <ul> <li><em>find the Royalty Sub Account.</em></li> <li><em>extract <code>tokenType</code> from the Royalty Sub Account.</em></li> <li><em>based on the token type send to the <code>payoutAccount</code> either</em> <ul> <li><em>'ETH' / relevant protocol token or</em></li> <li><em>another token based on token type</em></li> </ul> </li> <li><em>and only if the payout transaction is successful, deduct <code>amount</code> from <code>royaltybalance</code> of the Royalty Sub Account,<code>RAsubaccount</code>, and then return <code>true</code> as the function return parameter, otherwise return <code>false</code>.</em></li> </ul> <h2 id="rationale">Rationale</h2> <p>Royalties for NFTs is at its core a distribution licensing problem. A buyer obtains the right to an asset/content which might or might not be reproducible, alterable etc. by the buyer or agents of the buyer. Therefore, a comprehensive specification must address a hierarchy of royalties, where one or more assets are derived from an original asset as described in the Motivation section in detail. Consequently, a design must solve for a multi-level inheritance, and thus, recursion problem.</p> <p>In order to solve for the complicated inheritance problem, this proposal design breaks down the recursive problem of the hierarchy first into a tree of depth N. And the further breaks down the tree structure into N separate problems, one for each layer. This design allows one to traverse the tree from its lowest level upwards to its root most efficiently. This is achieved with the design for the <code>distributePayment</code> function and the NFT data structures allowing for the tree structure e.g. <code>ancestry</code>,<code>royaltyAccount</code>, <code>RAsubaccount</code>.</p> <p>In order to avoid massive gas costs during the payout of royalties, possibly exceeding block gas limits for large royalty trees, the design needed to create a royalty accounting system to maintain royalty balances for recipients as done with the <code>royaltyAccount</code>, 'RAsubaccount' data structures and the associated CRUD operations, as well as require that royalty payouts are done by individual and by request, only, as is achieved with the <code>royaltyPayout</code> function design.</p> <p>Furthermore, the design had to ensure that in order to account for and payout royalties the smart contract must be in the "know" of all buying and selling of an NFT including the exchange of monies. This buying and selling can be either direct through the NFT contract or can be exchange-mediated as is most often the case today -- which is a centralizing factor! The chosen design for purchasing is accounting for those two modes.</p> <p>Keeping the NFT contract in the "know" at the beginning of the purchase process requires that authorized user addresses can list NFTs for sale for direct sales , whereas for exchange-mediated purchases, a payment must be registered with the NFT contract before the purchase can be completed.</p> <p>The design needed to avoid royalty circumvention during the purchase process, therefore, the NFT must be kept in the "know", a buyer will always have to pay the NFT contract directly and not the seller for both purchasing modes. The seller is subsequently paid through the royalty distribution function in the NFT contract. As a consequence, and a key design choice, and to stay compliant with ERC-721, the NFT contract must be the owner of the NFT, and the actual owner is an <code>approved</code> address.</p> <p>The specification design also needed to account for that the payment process depends on whether the payment is received in ETH or an ERC-20 token:</p> <ul> <li>ERC-20 Token <ol> <li>The Buyer must <code>approve</code> the NFT contract for the purchase price, <code>payment</code> for the selected payment token (ERC-20 contract address).</li> <li>For an ERC-20 payment token, the Buyer must then call the <code>executePayment</code> in the NFT contract -- the ERC-20 is not directly involved.</li> </ol> </li> <li>For a non-ERC-20 payment, the Buyer must send a protocol token (ETH) to the NFT contract, and is required to send encoded listing and payment information.</li> </ul> <p>In addition, the <code>executePayment</code> function had to be designed to handle both direct sales (through the NFT contract) and exchange-mediated sales which required the introduction of an indicator whether the purchase is direct or exchange-mediated.</p> <p>The <code>executePayment</code> function also has to handle the NFT transfer and purchase clean up -- removal of a listing, or removal of a registered payment, distribution of royalties, payment to the seller, and finally transfer to the seller.</p> <p>To stay compliant with the ERC-721 design but avoid royalty circumvention, all transfer functions must be disabled save the one that allows for additional information to be submitted with the function in order to manage the complicated purchase cleanup process -- <code>safeTransferFrom</code>. To ensure safety, the design enforces that input parameters must satisfy several requirements for the NFT to be transferred AFTER the royalties have been properly distributed, not before. The design accounts for the fact that we need to treat transfer somewhat differently for direct sales versus exchange mediated sales.</p> <p>Finally the specification needed to take into account that NFTs must be able to be <code>minted</code> and <code>burned</code> to maintain compliance with the ERC-721 specification while also having to set up all the data structures for the tree.</p> <p>The design enforces that when an NFT is minted, a royalty account for that NFT must be created and associated with the NFT and the NFT owner, and, if there is an ancestor of the NFT with the ancestor's royalty account to enforces the tree structure. To this end the specification utilizes the ERC-721 <code>_safemint</code> function in a newly defined <code>mint</code> function and applies various business rules on the input variables required to ensure proper set-up.</p> <p>An NFT with a royalty account can be burned. However, several things have to be true to avoid locking funds not only for the royalty account of the NFT but also its descendants, if they exist. That means that all royalties for the NFT and its descendants, if they exists, must be paid out. Furthermore, if descendants exist, they must have been burned before an ancestor can be burned. If those rules are not enforced the cleanly, the hierarchical royalty structure in part of the tree can break down and lead to lost funds, not paid out royalties etc.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is backwards compatible to the ERC-721 standard introducing new interfaces and functionality but retaining the core interfaces and functionality of the ERC-721 standard.</p> <h2 id="test-cases">Test Cases</h2> <p>A full test suite is part of the reference implementation.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The Treetrunk reference implementation of the standard can be found in the public treetrunkio Github repo under treetrunk-nft-reference-implementation.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Given that this EIP introduces royalty collection, distribution, and payouts to the ERC-721 standard, the number of attack vectors increases. The most important attack vector categories and their mitigation are discussed below:</p> <ul> <li><strong>Payments and Payouts</strong>: <ul> <li>Reentrancy attacks are mitigated through a reentrancy protection on all payment functions. See for example the Open Zeppelin reference implementation .</li> <li>Payouts from unauthorized accounts. Mitigation: Royalty Sub Accounts require at least that <code>msg.sender</code> is the Royalty Sub Account owner.</li> <li>Payments could get stuck in the NFT contract if the <code>executePayment</code> function fails. Mitigation: For exchange-mediated sales, a buyer can always reverse a payment with <code>reversePayment</code> if the <code>executePayment</code> function fails. For direct sales, <code>reversePayment</code> will be directly triggered in the <code>executePayment</code> function.</li> </ul> </li> <li><strong>Circumventing Royalties</strong>: <ul> <li>Offchain Key exchanges <ul> <li>Exchanging a private key for money off chain can not be prevented in any scenario.</li> </ul> </li> <li>Smart Contract Wallets as NFT owners <ul> <li>A Smart Contract Wallet controlled by multiple addresses could own an NFT and the owners could transfer the asset within the wallet with an off chain money exchange. Mitigation: Prohibit that Smart Contracts can own an NFT unless explicitly allowed to accommodate special scenarios such as collections.</li> </ul> </li> <li>Denial of Royalty Disbursement <ul> <li>An attacker who has purchased one or more NFTs in a given generation of an NFT family can cause out of gas errors or run time errors for the contract, if they add many spurious royalty sub-accounts with very low royalty split percentages, and then mint more prints of those purchased NFTs, and then repeat that step until the set <code>maxGeneration</code> limit is reached. An NFT trade at the bottom of the hierarchy will then require a lot of code cycles because of the recursive nature of the royalty distribution function. Mitigation: Limit the number of royalty sub-accounts per NFT and impose a royalty split percentage limit.</li> <li>Following the same approach as above but now targeting the <code>addListNFT</code> function, an attacker can force an out of gas error or run time errors in the <code>executePayment</code> function by listing many NFTs at a low price, and then performing a purchase from another account. Mitigation: Limit the number of NFTs that can be included in one listing.</li> <li>The creator of the NFT family could set the number of generations too high such that the royalty distribution function could incur and out of gas or run time error because of the recursive nature of the function. Mitigation: Limiting the <code>maxNumberGeneration</code> by the creator.</li> </ul> </li> <li>General Considerations: The creator of an NFT family must carefully consider the business model for the NFT family and then set the parameters such as maximum number of generations, royalty sub-accounts, number of prints per print, number of NFTs in a listing, and the maximum and minimum royalty split percentage allowed.</li> </ul> </li> <li><strong>Phishing Attacks</strong> <ul> <li>NFT phishing attacks often target the <code>approve</code> and <code>setApprovalForAll</code> functions by tricking owners of NFTs to sign transactions adding the attacker account as approved for one or all NFTs of the victim. Mitigation: This contract is not vulnerable to these type of phishing attacks because all NFT transfers are sales, and the NFT contract itself is the owner of all NFTs. This means that transfers after a purchase are achieved by setting the new owner in the <code>_approve</code> function. Calling the public <code>approve</code> function will cause the function call to error out because <code>msg.sender</code> of the malicious transaction cannot be the NFT owner.</li> <li>NFT phishing attack targeting the <code>addListNFT</code> function to trick victim to list one or more NFTs at a very low price and the attacker immediately registering a payment, and executing that payment right away. Mitigation: Implement a waiting period for a purchase can be affected giving the victim time to call the <code>removeListNFT</code> function. In addition, an implementer could require Two-Factor-Authentication either built into the contract or by utilizing an authenticator app such as Google Authenticator built into a wallet software.</li> </ul> </li> </ul> <p>Besides the usage of professional security analysis tools, it is also recommended that each implementation performs a security audit of its 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-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-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Andershttps://github.com/0xanders Lancehttps://github.com/LanceSnow Shrugshrug@emojidao.org Nathannathan.gang@gemini.com https://wg-eips.ritovision.com/4906/

Add a MetadataUpdate event to EIP-721.

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>. It adds a <code>MetadataUpdate</code> event to EIP-721 tokens.</p> <h2 id="motivation">Motivation</h2> <p>Many <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> contracts emit an event when one of its tokens' metadata are changed. While tracking changes based on these different events is possible, it is an extra effort for third-party platforms, such as an NFT marketplace, to build individualized solutions for each NFT collection.</p> <p>Having a standard <code>MetadataUpdate</code> event will make it easy for third-party platforms to timely update the metadata of many NFTs.</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>The <strong>metadata update extension</strong> is OPTIONAL for EIP-721 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"> EIP-721 Metadata Update Extension</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC4906</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span>, </span><span class="z-entity z-name">IERC721</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 event emits when the metadata of a token is </span><span class="z-keyword">changed</span><span class="z-comment">.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> So that the third-party platforms such as NFT market could</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> timely update the images and related attributes of the NFT.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MetadataUpdate</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"> @dev</span><span class="z-comment"> This event emits when the metadata of a range of tokens is </span><span class="z-keyword">changed</span><span class="z-comment">.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> So that the third-party platforms such as NFT market could</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> timely update the images and related attributes of the NFTs. </span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> BatchMetadataUpdate</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> _fromTokenId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _toTokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>MetadataUpdate</code> or <code>BatchMetadataUpdate</code> event MUST be emitted when the JSON metadata of a token, or a consecutive range of tokens, is changed.</p> <p>Not emitting <code>MetadataUpdate</code> event is RECOMMENDED when a token is minted.</p> <p>Not emitting <code>MetadataUpdate</code> event is RECOMMENDED when a token is burned.</p> <p>Not emitting <code>MetadataUpdate</code> event is RECOMMENDED when the tokenURI changes but the JSON metadata does not.</p> <p>The <code>supportsInterface</code> method MUST return <code>true</code> when called with <code>0x49064906</code>.</p> <h2 id="rationale">Rationale</h2> <p>Different NFTs have different metadata, and metadata generally has multiple fields. <code>bytes data</code> could be used to represents the modified value of metadata. It is difficult for third-party platforms to identify various types of <code>bytes data</code>, so as to avoid unnecessary complexity, arbitrary metadata is not included in the <code>MetadataUpdate</code> event.</p> <p>After capturing the <code>MetadataUpdate</code> event, a third party can update the metadata with information returned from the <code>tokenURI(uint256 _tokenId)</code> of EIP-721. When a range of token ids is specified, the third party can query each token URI individually.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backwards compatibility issues were found</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"> ^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/ERC721.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC4906.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"> ERC4906</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">IERC4906</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-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See {IERC165-supportsInterface}.</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"> 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">IERC165</span><span>,</span><span class="z-entity z-name"> ERC721</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> interfaceId </span><span class="z-keyword">==</span><span class="z-support"> bytes4</span><span>(</span><span class="z-constant">0x49064906</span><span>)</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>If there is an off-chain modification of metadata, a method that triggers <code>MetadataUpdate</code> can be added, but ensure that the function's permission controls are correct.</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-11T00:00:00+00:00 2026-02-11T14:48:25+00:00 Andershttps://github.com/0xanders Lancehttps://github.com/LanceSnow Shrugshrug@emojidao.org https://wg-eips.ritovision.com/4907/

Add a time-limited role with restricted permissions 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 role (<code>user</code>) which can be granted to addresses, and a time where the role is automatically revoked (<code>expires</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” function is introduced that would facilitate the automatic end of a usage term without the need of a second transaction.</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/4907/./assets/contracts/IERC4907.sol"><code>IERC4907.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"> IERC4907</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 an NFT is </span><span class="z-keyword">changed</span><span class="z-comment"> or expires 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> <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>;</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 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 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-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-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></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>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.</p> <p>The <code>supportsInterface</code> method MUST return <code>true</code> when called with <code>0xad092b5c</code>.</p> <h2 id="rationale">Rationale</h2> <p>This model is intended to facilitate easy implementation. 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>, 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="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="test-cases">Test Cases</h2> <h3 id="test-contract">Test Contract</h3> <p><code>ERC4907Demo</code> Implementation: <a href="https://wg-eips.ritovision.com/4907/./assets/contracts/ERC4907Demo.sol"><code>ERC4907Demo.sol</code></a></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-keyword">import</span><span class="z-string"> &quot;./ERC4907.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"> ERC4907Demo</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC4907</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> <span class="giallo-l"><span class="z-entity z-name"> ERC4907</span><span>(</span><span>name,symbol)</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"> mint</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"> to</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 class="giallo-l"><span>}</span></span></code></pre><h3 id="test-code">Test Code</h3> <p><a href="https://wg-eips.ritovision.com/4907/./assets/test/test.js">test.js</a></p> <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"> assert</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> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> ERC4907Demo</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">&quot;</span><span class="z-string">ERC4907Demo</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-entity z-name">contract</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 class="z-storage"> async</span><span class="z-variable"> accounts</span><span class="z-storage z-type"> =&gt;</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 user to Bob</span><span class="z-punctuation z-definition z-string">&quot;</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-punctuation z-definition z-comment"> //</span><span class="z-comment"> Get initial balances of first and second account.</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> Alice</span><span class="z-keyword"> =</span><span class="z-variable z-other"> accounts</span><span>[</span><span class="z-constant">0</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"> Bob</span><span class="z-keyword"> =</span><span class="z-variable z-other"> accounts</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"> const</span><span class="z-variable z-other z-constant"> instance</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> ERC4907Demo</span><span>.</span><span class="z-entity z-name">deployed</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">T</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">T</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"> demo</span><span class="z-keyword"> =</span><span class="z-variable z-other"> instance</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> demo</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other"> Alice</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> expires</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-keyword">new</span><span class="z-entity z-name"> Date</span><span>(</span><span>)</span><span>.</span><span class="z-entity z-name">getTime</span><span>(</span><span>)</span><span class="z-keyword">/</span><span class="z-constant">1000</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> 1000</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> demo</span><span>.</span><span class="z-entity z-name">setUser</span><span>(</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other"> Bob</span><span>,</span><span class="z-entity z-name"> BigInt</span><span>(</span><span class="z-variable z-other">expires</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> user_1</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> demo</span><span>.</span><span class="z-entity z-name">userOf</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-variable z-other"> assert</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> user_1</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> Bob</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">User of NFT 1 should be Bob</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-storage z-type"> let</span><span class="z-variable z-other"> owner_1</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> demo</span><span>.</span><span class="z-entity z-name">ownerOf</span><span>(</span><span class="z-constant">1</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> <span class="giallo-l"><span class="z-variable z-other"> owner_1</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> Alice</span><span> ,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Owner of NFT 1 should be Alice</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><span>;</span></span> <span class="giallo-l"><span>}</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span></code></pre> <p>run in Terminal：</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>truffle test ./test/test.js</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>Implementation: <a href="https://wg-eips.ritovision.com/4907/./assets/contracts/ERC4907.sol"><code>ERC4907.sol</code></a></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-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;./IERC4907.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"> ERC4907</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">IERC4907</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> UserInfo</span><span> </span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> user</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> address of user role</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> expires</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> unix timestamp, user expires</span></span> <span class="giallo-l"><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> UserInfo</span><span>)</span><span class="z-storage z-type"> internal</span><span> _users</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> <span class="giallo-l"><span class="z-entity z-name"> ERC721</span><span>(</span><span>name_, symbol_)</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-storage z-type"> @notice</span><span class="z-comment"> set the user and 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 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-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-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-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;ERC4907: transfer caller is not owner nor approved&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> UserInfo </span><span class="z-storage z-type">storage</span><span> info </span><span class="z-keyword">=</span><span> _users</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> info</span><span>.</span><span>user </span><span class="z-keyword">=</span><span> user</span><span>;</span></span> <span class="giallo-l"><span> info</span><span>.</span><span>expires </span><span class="z-keyword">=</span><span> expires</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> UpdateUser</span><span>(</span><span>tokenId</span><span>,</span><span> user</span><span>,</span><span> expires</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"> @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"> 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">address</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-support"> uint256</span><span>(</span><span>_users</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>expires</span><span>)</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>{</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _users</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>user</span><span>;</span></span> <span class="giallo-l"><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 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></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"> 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> _users</span><span>[</span><span>tokenId</span><span>]</span><span>.</span><span>expires</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"> See {IERC165-supportsInterface}.</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"> 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>IERC4907</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 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-variable z-language"> super</span><span>.</span><span class="z-entity z-name">_beforeTokenTransfer</span><span>(</span><span>from</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>from </span><span class="z-keyword">!=</span><span> to </span><span class="z-keyword">&amp;&amp;</span><span> _users</span><span>[</span><span>tokenId</span><span>]</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> {</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> _users</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"> UpdateUser</span><span>(</span><span>tokenId</span><span>,</span><span class="z-support"> address</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> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span><span> </span></span></code></pre><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 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-03-11T00:00:00+00:00 2026-02-11T14:48:25+00:00 Gavin Johnhttps://github.com/Pandapip1 Tim Daubenschützhttps://github.com/TimDaub https://wg-eips.ritovision.com/5380/

Allows token owners to grant the ability for others to use specific properties of those tokens

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a new interface that allows <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> token owners to grant limited usage of those tokens to other addresses.</p> <h2 id="motivation">Motivation</h2> <p>There are many scenarios in which it makes sense for the owner of a token to grant certain properties to another address. One use case is renting tokens. If the token in question represents a trading card in an on-chain TCG (trading card game), one might want to be able to use that card in the game without having to actually buy it. Therefore, the owner might grant the renter the "property" of it being able to be played in the TCG. However, this property should only be able to be assigned to one person at a time, otherwise a contract could simply "rent" the card to everybody. If the token represents usage rights instead, the property of being allowed to use the associated media does not need such a restriction, and there is no reason that the property should be as scarce as the token.</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="base">Base</h3> <p>Compliant entitlement contracts MUST implement the following Solidity 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: 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"> ERC5380Entitlement</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"> Emitted when the amount of entitlement a user has changes. If user is the zero address, then the user is the owner</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> EntitlementChanged</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"> contract</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Set the user associated with the given ERC-721 token as long as the owner is 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"> SHOULD NOT revert if the owner is not 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"> user</span><span class="z-comment"> The user to grant the entitlement 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"> contract</span><span class="z-comment"> The property to grant</span></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 tokenId to grant the properties of</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> entitle</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> contract</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Get the maximum number of users that can receive this entitlement</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> contract</span><span class="z-comment"> The contract to query</span></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 tokenId to query</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> maxEntitlements</span><span>(</span><span class="z-support">address</span><span class="z-variable"> contract</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> (</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> max</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 associated with the given contract and tokenId.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Defaults to maxEntitlements(contract, tokenId) assigned to contract.ownerOf(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"> user</span><span class="z-comment"> The user to query</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> contract</span><span class="z-comment"> The contract to query</span></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 tokenId to query</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> entitlementOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> contract</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 class="z-variable"> amt</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>supportsInterface</code> MUST return true when called with <code>ERC5380Entitlement</code>'s interface ID.</p> <h3 id="enumerable-extension">Enumerable Extension</h3> <p>This OPTIONAL Solidity interface is RECOMMENDED.</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"> ERC5380EntitlementEnumerable</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC5380Entitlement</span><span> {</span><span class="z-comment"> //</span><span class="z-comment"> Also implicitly supports ERC-165</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Enumerate tokens with nonzero entitlement 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"> Throws if the index is out of bounds or if user == 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"> user</span><span class="z-comment"> The user to query</span></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"> A counter</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> entitlementOfUserByIndex</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"> 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">address</span><span class="z-variable"> contract</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></span></code></pre> <p><code>supportsInterface</code> MUST return true when called with <code>ERC5380EntitlementEnumerable</code>'s interface ID.</p> <h3 id="metadata-extension">Metadata Extension</h3> <p>This OPTIONAL Solidity interface is RECOMMENDED.</p> <p>This extension uses <a href="https://wg-eips.ritovision.com/1046/">ERC-1046</a> for <code>tokenURI</code> compatibility.</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"> ERC5380EntitlementMetadata</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC5380Entitlement</span><span> {</span><span class="z-comment"> //</span><span class="z-comment"> Also implicitly supports ERC-165</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> ERC-1046 token URI</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See ERC-1046 and the metadata schema below</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>)</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><code>supportsInterface</code> MUST return true when called with <code>ERC5380EntitlementMetadata</code>'s interface ID.</p> <h4 id="interoperability-metadata-extension">Interoperability Metadata Extension</h4> <p>ERC-1046's <code>InteroperabilityMetadata</code> is extended with the following TypeScript interface:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * ERC-5380&#39;s extension to ERC-1046&#39;s Interoperability metadata.</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">interface</span><span class="z-entity z-name"> ERC5380InteroperabilityMetadata</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> InteroperabilityMetadata</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"> * This MUST be true if this is ERC-5380 Token Metadata, otherwise, this MUST be omitted.</span></span> <span class="giallo-l"><span class="z-comment"> * Setting this to true indicates to wallets that the address should be treated as an ERC-5380 entitlement.</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-variable"> erc5380</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span class="z-keyword"> |</span><span class="z-support"> undefined</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="tokenuri-metadata-schema"><code>tokenURI</code> Metadata Schema</h4> <p>The resolved <code>tokenURI</code> data MUST conform to the following TypeScript interface:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * ERC-5380 Asset Metadata</span></span> <span class="giallo-l"><span class="z-comment"> * Can be extended</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">interface</span><span class="z-entity z-name"> ERC5380TokenMetadata</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"> * Interoperabiliy, to differentiate between different types of tokens and their corresponding URIs.</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-variable"> interop</span><span class="z-keyword">:</span><span class="z-entity z-name"> ERC5380InteroperabilityMetadata</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> <span class="giallo-l"><span class="z-comment"> * The name of the ERC-5380 token. </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-variable"> name</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * The symbol of the ERC-5380 token. </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-variable"> symbol</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * Provides a short one-paragraph description of the ERC-5380 token, without any markup or newlines.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-variable"> description</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * One or more URIs each pointing to a resource with mime type `image/*` that represents this token.</span></span> <span class="giallo-l"><span class="z-comment"> * If an image is a bitmap, it SHOULD have a width between 320 and 1080 pixels</span></span> <span class="giallo-l"><span class="z-comment"> * Images SHOULD have an aspect ratio between 1.91:1 and 4:5 inclusive.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-variable"> images</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * One or more URIs each pointing to a resource with mime type `image/*` that represent an icon for this token.</span></span> <span class="giallo-l"><span class="z-comment"> * If an image is a bitmap, it SHOULD have a width between 320 and 1080 pixels, and MUST have a height equal to its width</span></span> <span class="giallo-l"><span class="z-comment"> * Images MUST have an aspect ratio of 1:1, and use a transparent background</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-variable"> icons</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><h2 id="rationale">Rationale</h2> <p><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> are unsupported as partial ownership is much more complex to track than boolean ownership.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues were found.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The security considerations of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1046/">ERC-1046</a> 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-03-10T00: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/4895/

Support validator withdrawals from the beacon chain to the EVM via a new "system-level" operation type.

<h2 id="abstract">Abstract</h2> <p>Introduce a system-level "operation" to support validator withdrawals that are "pushed" from the beacon chain to the EVM.</p> <p>These operations create unconditional balance increases to the specified recipients.</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 layer as soon as they are dequeued from the consensus layer.</p> <p>Withdrawals are represented as a new type of object in the execution payload -- an "operation" -- that separates the withdrawals feature from user-level transactions. This approach is more involved than the prior approach introducing a new transaction type but it cleanly separates this "system-level" operation from regular transactions. The separation simplifies testing (so facilitates security) by reducing interaction effects generated by mixing this system-level concern with user data.</p> <p>Moreover, this approach is more complex than "pull"-based alternatives with respect to the core protocol 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>1681338455</td><td></td></tr> </tbody></table> <p>Beginning with the execution timestamp <code>FORK_TIMESTAMP</code>, execution clients <strong>MUST</strong> introduce the following extensions to payload validation and processing:</p> <h3 id="system-level-operation-withdrawal">System-level operation: withdrawal</h3> <p>Define a new payload-level object called a <code>withdrawal</code> that describes withdrawals that have been validated at the consensus layer. <code>Withdrawal</code>s are syntactically similar to a user-level transaction but live in a different domain than user-level transactions.</p> <p><code>Withdrawal</code>s provide key information from the consensus layer:</p> <ol> <li>a monotonically increasing <code>index</code>, starting from 0, as a <code>uint64</code> value that increments by 1 per withdrawal to uniquely identify each withdrawal</li> <li>the <code>validator_index</code> of the validator, as a <code>uint64</code> value, on the consensus layer the withdrawal corresponds to</li> <li>a recipient for the withdrawn ether <code>address</code> as a 20-byte value</li> <li>a nonzero <code>amount</code> of ether given in Gwei (1e9 wei) as a <code>uint64</code> value.</li> </ol> <p><em>NOTE</em>: the <code>index</code> for each withdrawal is a global counter spanning the entire sequence of withdrawals.</p> <p><code>Withdrawal</code> objects are serialized as a RLP list according to the schema: <code>[index, validator_index, address, amount]</code>.</p> <h3 id="new-field-in-the-execution-payload-withdrawals">New field in the execution payload: withdrawals</h3> <p>The execution payload gains a new field for the <code>withdrawals</code> which is an RLP list of <code>Withdrawal</code> data.</p> <p>For example:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>withdrawal_0</span><span class="z-keyword"> =</span><span> [</span><span>index_0</span><span>,</span><span> validator_index_0</span><span>,</span><span> address_0</span><span>,</span><span> amount_0</span><span>]</span></span> <span class="giallo-l"><span>withdrawal_1</span><span class="z-keyword"> =</span><span> [</span><span>index_1</span><span>,</span><span> validator_index_1</span><span>,</span><span> address_1</span><span>,</span><span> amount_1</span><span>]</span></span> <span class="giallo-l"><span>withdrawals</span><span class="z-keyword"> =</span><span> [</span><span>withdrawal_0</span><span>,</span><span> withdrawal_1</span><span>]</span></span></code></pre> <p>This new field is encoded after the existing fields in the execution payload structure and is considered part of the execution payload's body.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>execution_payload_rlp</span><span class="z-keyword"> =</span><span> RLP</span><span>(</span><span>[</span><span>header</span><span>,</span><span> transactions</span><span>,</span><span> [</span><span>]</span><span>,</span><span> withdrawals</span><span>]</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>execution_payload_body_rlp</span><span class="z-keyword"> =</span><span> RLP</span><span>(</span><span>[</span><span>transactions</span><span>,</span><span> [</span><span>]</span><span>,</span><span> withdrawals</span><span>]</span><span>)</span></span></code></pre> <p>NOTE: the empty list in this schema is due to <a href="https://wg-eips.ritovision.com/3675/">EIP-3675</a> that sets the <code>ommers</code> value to a fixed constant.</p> <h3 id="new-field-in-the-execution-payload-header-withdrawals-root">New field in the execution payload header: withdrawals root</h3> <p>The execution payload header gains a new field committing to the <code>withdrawals</code> in the execution payload.</p> <p>This commitment is constructed identically to the transactions root in the existing execution payload header by inserting each withdrawal into a Merkle-Patricia trie keyed by index in the list of <code>withdrawals</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"> compute_trie_root_from_indexed_data</span><span>(</span><span class="z-variable z-parameter z-function">data</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> trie</span><span class="z-keyword"> =</span><span> Trie</span><span>.</span><span class="z-keyword">from</span><span>(</span><span>[</span><span>(</span><span>i</span><span>,</span><span> obj</span><span>)</span><span class="z-keyword"> for</span><span> i</span><span>,</span><span> obj</span><span class="z-keyword"> in</span><span class="z-support"> enumerate</span><span>(</span><span>data</span><span>)</span><span>]</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> trie</span><span>.</span><span>root</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>execution_payload_header</span><span>.</span><span>withdrawals_root</span><span class="z-keyword"> =</span><span> compute_trie_root_from_indexed_data</span><span>(</span><span>execution_payload</span><span>.</span><span>withdrawals</span><span>)</span></span></code></pre> <p>The execution payload header is extended with a new field containing the 32 byte root of the trie committing to the list of withdrawals provided in a given execution payload.</p> <p>To illustrate:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>execution_payload_header_rlp</span><span class="z-keyword"> =</span><span> RLP</span><span>(</span><span>[</span></span> <span class="giallo-l"><span> parent_hash</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> ommers hash</span></span> <span class="giallo-l"><span> coinbase</span><span>,</span></span> <span class="giallo-l"><span> state_root</span><span>,</span></span> <span class="giallo-l"><span> txs_root</span><span>,</span></span> <span class="giallo-l"><span> receipts_root</span><span>,</span></span> <span class="giallo-l"><span> logs_bloom</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 0</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> difficulty</span></span> <span class="giallo-l"><span> number</span><span>,</span></span> <span class="giallo-l"><span> gas_limit</span><span>,</span></span> <span class="giallo-l"><span> gas_used</span><span>,</span></span> <span class="giallo-l"><span> timestamp</span><span>,</span></span> <span class="giallo-l"><span> extradata</span><span>,</span></span> <span class="giallo-l"><span> prev_randao</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">0000000000000000</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> nonce</span></span> <span class="giallo-l"><span> base_fee_per_gas</span><span>,</span></span> <span class="giallo-l"><span> withdrawals_root</span><span>,</span></span> <span class="giallo-l"><span>]</span><span>)</span></span></code></pre> <p>NOTE: field names and constant value in this example reflect <a href="https://wg-eips.ritovision.com/3675/">EIP-3675</a> and <a href="https://wg-eips.ritovision.com/4399/">EIP-4399</a>. Refer to those EIPs for further information.</p> <h3 id="execution-payload-validity">Execution payload validity</h3> <p>Assuming the execution payload is well-formatted, the execution client has an additional payload validation to ensure that the <code>withdrawals_root</code> matches the expected value given the list in the payload.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">assert</span><span> execution_payload_header</span><span>.</span><span>withdrawals_root</span><span class="z-keyword"> ==</span><span> compute_trie_root_from_indexed_data</span><span>(</span><span>execution_payload</span><span>.</span><span>withdrawals</span><span>)</span></span></code></pre><h3 id="state-transition">State transition</h3> <p>The <code>withdrawals</code> in an execution payload are processed <strong>after</strong> any user-level transactions are applied.</p> <p>For each <code>withdrawal</code> in the list of <code>execution_payload.withdrawals</code>, the implementation increases the balance of the <code>address</code> specified by the <code>amount</code> given.</p> <p>Recall that the <code>amount</code> is given in units of Gwei so a conversion to units of wei must be performed when working with account balances in the execution state.</p> <p>This balance change is unconditional and <strong>MUST</strong> not fail.</p> <p>This operation has no associated gas costs.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-not-a-new-transaction-type">Why not a new transaction type?</h3> <p>This EIP suggests a new type of object -- the "withdrawal operation" -- as it has special semantics different from other existing types of EVM transactions.</p> <p>Operations are initiated by the overall system, rather than originating from end users like typical transactions.</p> <p>An entirely new type of object 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-the-withdrawal-type">Why no (gas) costs for the withdrawal type?</h3> <p>The maximum number of withdrawals that can reach the execution layer at a given time is bounded (enforced by the consensus layer) and this limit has been chosen so that any execution layer operational costs are negligible in the context of the broader payload execution.</p> <p>This bound applies to both computational cost (only a few balance updates in the state) and storage/networking cost as the additional payload footprint is kept small (current parameterizations put the additional overhead at ~1% of current average payload size).</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> <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-03-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Andrew B Coathuphttps://github.com/abcoathup Alexhttps://github.com/AlexPartyPanda Damian Martinellihttps://github.com/damianmarti blockdevhttps://github.com/0xbok Austin Griffithhttps://github.com/austintgriffith https://wg-eips.ritovision.com/4883/

Compose an SVG NFT by concatenating the SVG with the rendered SVG of another NFT.

<h2 id="abstract">Abstract</h2> <p>Compose an SVG (Scalable Vector Graphics) NFT by concatenating the SVG with the SVG of another NFT rendered as a string for a specific token ID.</p> <h2 id="motivation">Motivation</h2> <p>Onchain SVG NFTs allow for NFTs to be entirely onchain by returning artwork as SVG in a data URI of the <code>tokenUri</code> function. Composability allows onchain SVG NFTs to be crafted. e.g. adding glasses &amp; hat NFTs to a profile pic NFT or a fish NFT to a fish tank 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="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> EIP-4883 Non-Fungible Token Standard</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC4883</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> renderTokenById</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">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>renderTokenById</code> must return the SVG body for the specified token <code>id</code> and must either be an empty string or valid SVG element(s).</p> <h2 id="rationale">Rationale</h2> <p>SVG elements can be string concatenated to compose an SVG.</p> <h3 id="ordering-of-concatenation">Ordering of concatenation</h3> <p>SVG uses a "painters model" of rendering.</p> <p><strong>Scalable Vector Graphics (SVG) 1.1 (Second Edition)</strong>, section: <strong>3.3 Rendering Order</strong></p> <blockquote> <p>Elements in an SVG document fragment have an implicit drawing order, with the first elements in the SVG document fragment getting "painted" first. Subsequent elements are painted on top of previously painted elements.</p> </blockquote> <p>The ordering of the SVG concatenation determines the drawing order rather than any concept of a z-index.</p> <p>This EIP only specifies the rendering of the rendered SVG NFT and does not require any specific ordering when composing. This allows the SVG NFT to use a rendered SVG NFT as a foreground or a background as required.</p> <h3 id="alternatives-to-concatenation">Alternatives to concatenation</h3> <p>SVG specifies a <code>link</code> tag. Linking could allow for complex SVGs to be composed but would require creating a URI format and then getting ecosystem adoption. As string concatenation of SVG's is already supported, the simpler approach of concatenation is used.</p> <h3 id="sizing">Sizing</h3> <p>This EIP doesn't specify any requirements on the size of the rendered SVG. Any scaling based on sizing can be performed by the SVG NFT as required.</p> <h3 id="render-function-name">Render function name</h3> <p>The render function is named <code>renderTokenById</code> as this function name was first used by Loogies and allows existing deployed NFTs to be compatible with this EIP.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP has no backwards compatibility concerns</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>SVG uses a "painters model" of rendering. A rendered SVG body could be added and completely obscure the existing SVG NFT artwork.</li> <li>SVG is XML and can contain malicious content, and while it won't impact the contract, it could impact the use of the SVG.</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-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-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin Dankrad Feisthttps://github.com/dankrad Diederik Loerakkerhttps://github.com/protolambda George Kadianakishttps://github.com/asn-d6 Matt Garnetthttps://github.com/lightclient Mofi Taiwohttps://github.com/Inphi Ansgar Dietrichshttps://github.com/adietrichs https://wg-eips.ritovision.com/4844/

Shard Blob Transactions scale data-availability of Ethereum in a simple, forwards-compatible manner.

<h2 id="abstract">Abstract</h2> <p>Introduce a new transaction format for "blob-carrying transactions" which contain a large amount of data that cannot be accessed by EVM execution, but whose commitment can be accessed. The format is intended to be fully compatible with the format that will be used in full sharding.</p> <h2 id="motivation">Motivation</h2> <p>Rollups are in the short and medium term, and possibly in 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 data sharding, which would add ~16 MB per block of dedicated data space to the chain that rollups could use. However, data sharding will still take a considerable amount of time to finish implementing and deploying.</p> <p>This EIP provides a stop-gap solution until that point by implementing the <em>transaction format</em> that would be used in sharding, but not actually sharding those transactions. Instead, the data from this transaction format is simply part of the beacon chain and is fully downloaded by all consensus nodes (but can be deleted after only a relatively short delay). Compared to full data sharding, this EIP has a reduced cap on the number of these transactions that can be included, corresponding to a target of ~0.375 MB per block and a limit of ~0.75 MB.</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>BLOB_TX_TYPE</code></td><td><code>Bytes1(0x03)</code></td></tr> <tr><td><code>BYTES_PER_FIELD_ELEMENT</code></td><td><code>32</code></td></tr> <tr><td><code>FIELD_ELEMENTS_PER_BLOB</code></td><td><code>4096</code></td></tr> <tr><td><code>BLS_MODULUS</code></td><td><code>52435875175126190479447740508185965837690552500527637822603658699938581184513</code></td></tr> <tr><td><code>VERSIONED_HASH_VERSION_KZG</code></td><td><code>Bytes1(0x01)</code></td></tr> <tr><td><code>POINT_EVALUATION_PRECOMPILE_ADDRESS</code></td><td><code>Bytes20(0x0A)</code></td></tr> <tr><td><code>POINT_EVALUATION_PRECOMPILE_GAS</code></td><td><code>50000</code></td></tr> <tr><td><code>MAX_BLOB_GAS_PER_BLOCK</code></td><td><code>786432</code></td></tr> <tr><td><code>TARGET_BLOB_GAS_PER_BLOCK</code></td><td><code>393216</code></td></tr> <tr><td><code>MIN_BASE_FEE_PER_BLOB_GAS</code></td><td><code>1</code></td></tr> <tr><td><code>BLOB_BASE_FEE_UPDATE_FRACTION</code></td><td><code>3338477</code></td></tr> <tr><td><code>GAS_PER_BLOB</code></td><td><code>2**17</code></td></tr> <tr><td><code>HASH_OPCODE_BYTE</code></td><td><code>Bytes1(0x49)</code></td></tr> <tr><td><code>HASH_OPCODE_GAS</code></td><td><code>3</code></td></tr> <tr><td><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/4de1d156c78b555421b72d6067c73b614ab55584/configs/mainnet.yaml#L148"><code>MIN_EPOCHS_FOR_BLOB_SIDECARS_REQUESTS</code></a></td><td><code>4096</code></td></tr> </tbody></table> <h3 id="type-aliases">Type aliases</h3> <table><thead><tr><th>Type</th><th>Base type</th><th>Additional checks</th></tr></thead><tbody> <tr><td><code>Blob</code></td><td><code>ByteVector[BYTES_PER_FIELD_ELEMENT * FIELD_ELEMENTS_PER_BLOB]</code></td><td></td></tr> <tr><td><code>VersionedHash</code></td><td><code>Bytes32</code></td><td></td></tr> <tr><td><code>KZGCommitment</code></td><td><code>Bytes48</code></td><td>Perform IETF BLS signature "KeyValidate" check but do allow the identity point</td></tr> <tr><td><code>KZGProof</code></td><td><code>Bytes48</code></td><td>Same as for <code>KZGCommitment</code></td></tr> </tbody></table> <h3 id="cryptographic-helpers">Cryptographic Helpers</h3> <p>Throughout this proposal we use cryptographic methods and classes defined in the corresponding <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/86fb82b221474cc89387fa6436806507b3849d88/specs/deneb">consensus 4844 specs</a>.</p> <p>Specifically, we use the following methods from <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/86fb82b221474cc89387fa6436806507b3849d88/specs/deneb/polynomial-commitments.md"><code>polynomial-commitments.md</code></a>:</p> <ul> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/86fb82b221474cc89387fa6436806507b3849d88/specs/deneb/polynomial-commitments.md#verify_kzg_proof"><code>verify_kzg_proof()</code></a></li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/86fb82b221474cc89387fa6436806507b3849d88/specs/deneb/polynomial-commitments.md#verify_blob_kzg_proof_batch"><code>verify_blob_kzg_proof_batch()</code></a></li> </ul> <h3 id="helpers">Helpers</h3> <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"> kzg_to_versioned_hash</span><span>(</span><span class="z-variable z-parameter z-function">commitment</span><span>:</span><span> KZGCommitment</span><span>)</span><span> -&gt;</span><span> VersionedHash</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> VERSIONED_HASH_VERSION_KZG</span><span class="z-keyword"> +</span><span> sha256</span><span>(</span><span>commitment</span><span>)</span><span>[</span><span class="z-constant">1</span><span>:</span><span>]</span></span></code></pre> <p>Approximates <code>factor * e ** (numerator / denominator)</code> using Taylor expansion:</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"> fake_exponential</span><span>(</span><span class="z-variable z-parameter z-function">factor</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> numerator</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> denominator</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> i</span><span class="z-keyword"> =</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> output</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> numerator_accum</span><span class="z-keyword"> =</span><span> factor</span><span class="z-keyword"> *</span><span> denominator</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> numerator_accum</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> output</span><span class="z-keyword"> +=</span><span> numerator_accum</span></span> <span class="giallo-l"><span> numerator_accum</span><span class="z-keyword"> =</span><span> (</span><span>numerator_accum</span><span class="z-keyword"> *</span><span> numerator</span><span>)</span><span class="z-keyword"> //</span><span> (</span><span>denominator</span><span class="z-keyword"> *</span><span> i</span><span>)</span></span> <span class="giallo-l"><span> i</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> output</span><span class="z-keyword"> //</span><span> denominator</span></span></code></pre><h3 id="blob-transaction">Blob transaction</h3> <p>We introduce a new type of <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction, "blob transaction", where the <code>TransactionType</code> is <code>BLOB_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, 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>value</code>, <code>data</code>, and <code>access_list</code> follow the same semantics as <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a>.</p> <p>The field <code>to</code> deviates slightly from the semantics with the exception that it MUST NOT be <code>nil</code> and therefore must always represent a 20-byte address. This means that blob transactions cannot have the form of a create transaction.</p> <p>The field <code>max_fee_per_blob_gas</code> is a <code>uint256</code> and the field <code>blob_versioned_hashes</code> represents a list of hash outputs from <code>kzg_to_versioned_hash</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> <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(BLOB_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]))</code>.</p> <h3 id="header-extension">Header extension</h3> <p>The current header encoding is extended with two new 64-bit unsigned integer fields:</p> <ul> <li><code>blob_gas_used</code> is the total amount of blob gas consumed by the transactions within the block.</li> <li><code>excess_blob_gas</code> is a running total of blob gas consumed in excess of the target, prior to the block. Blocks with above-target blob gas consumption increase this value, blocks with below-target blob gas consumption decrease it (bounded at 0).</li> </ul> <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>])</span></span></code></pre> <p>The value of <code>excess_blob_gas</code> can be calculated using the parent header.</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 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 class="z-constant"> TARGET_BLOB_GAS_PER_BLOCK</span></span></code></pre> <p>For the first post-fork block, both <code>parent.blob_gas_used</code> and <code>parent.excess_blob_gas</code> are evaluated as <code>0</code>.</p> <h3 id="gas-accounting">Gas accounting</h3> <p>We introduce blob gas as a new type of gas. It is independent of normal gas and follows its own targeting rule, similar to EIP-1559. We use the <code>excess_blob_gas</code> header field to store persistent data needed to compute the blob gas base fee. For now, only blobs are priced in blob gas.</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_blob_fee</span><span>(</span><span class="z-variable z-parameter z-function">header</span><span>:</span><span> Header</span><span>,</span><span class="z-variable z-parameter z-function"> tx</span><span>:</span><span> Transaction</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> get_total_blob_gas</span><span>(</span><span>tx</span><span>)</span><span class="z-keyword"> *</span><span> get_base_fee_per_blob_gas</span><span>(</span><span>header</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_total_blob_gas</span><span>(</span><span class="z-variable z-parameter z-function">tx</span><span>:</span><span> Transaction</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"> GAS_PER_BLOB</span><span class="z-keyword"> *</span><span class="z-support"> len</span><span>(</span><span>tx</span><span>.</span><span>blob_versioned_hashes</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_base_fee_per_blob_gas</span><span>(</span><span class="z-variable z-parameter z-function">header</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> fake_exponential</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> MIN_BASE_FEE_PER_BLOB_GAS</span><span>,</span></span> <span class="giallo-l"><span> header</span><span>.</span><span>excess_blob_gas</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> BLOB_BASE_FEE_UPDATE_FRACTION</span></span> <span class="giallo-l"><span> )</span></span></code></pre> <p>The block validity conditions are modified to include blob gas checks (see the <a href="https://wg-eips.ritovision.com/4844/#execution-layer-validation">Execution layer validation</a> section below).</p> <p>The actual <code>blob_fee</code> as calculated via <code>calc_blob_fee</code> is deducted from the sender balance before transaction execution and burned, and is not refunded in case of transaction failure.</p> <h3 id="opcode-to-get-versioned-hashes">Opcode to get versioned hashes</h3> <p>We add an instruction <code>BLOBHASH</code> (with opcode <code>HASH_OPCODE_BYTE</code>) which reads <code>index</code> from the top of the stack as big-endian <code>uint256</code>, and replaces it on the stack with <code>tx.blob_versioned_hashes[index]</code> if <code>index &lt; len(tx.blob_versioned_hashes)</code>, and otherwise with a zeroed <code>bytes32</code> value. The opcode has a gas cost of <code>HASH_OPCODE_GAS</code>.</p> <h3 id="point-evaluation-precompile">Point evaluation precompile</h3> <p>Add a precompile at <code>POINT_EVALUATION_PRECOMPILE_ADDRESS</code> that verifies a KZG proof which claims that a blob (represented by a commitment) evaluates to a given value at a given point.</p> <p>The precompile costs <code>POINT_EVALUATION_PRECOMPILE_GAS</code> and executes the following logic:</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"> point_evaluation_precompile</span><span>(</span><span class="z-variable z-parameter z-function">input</span><span>:</span><span> Bytes</span><span>)</span><span> -&gt;</span><span> Bytes</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"> Verify p(z) = y given commitment that corresponds to the polynomial p(x) and a KZG proof.</span></span> <span class="giallo-l"><span class="z-string"> Also verify that the provided commitment matches the provided versioned_hash.</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"> The data is encoded as follows: versioned_hash | z | y | commitment | proof | with z and y being padded 32 byte big endian values</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span class="z-support">input</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 192</span></span> <span class="giallo-l"><span> versioned_hash</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span>:</span><span class="z-constant">32</span><span>]</span></span> <span class="giallo-l"><span> z</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span class="z-constant">32</span><span>:</span><span class="z-constant">64</span><span>]</span></span> <span class="giallo-l"><span> y</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span class="z-constant">64</span><span>:</span><span class="z-constant">96</span><span>]</span></span> <span class="giallo-l"><span> commitment</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span class="z-constant">96</span><span>:</span><span class="z-constant">144</span><span>]</span></span> <span class="giallo-l"><span> proof</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span class="z-constant">144</span><span>:</span><span class="z-constant">192</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"> Verify commitment matches versioned_hash</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> kzg_to_versioned_hash</span><span>(</span><span>commitment</span><span>)</span><span class="z-keyword"> ==</span><span> versioned_hash</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 KZG proof with z and y in big endian format</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> verify_kzg_proof</span><span>(</span><span>commitment</span><span>,</span><span> z</span><span>,</span><span> y</span><span>,</span><span> proof</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"> Return FIELD_ELEMENTS_PER_BLOB and BLS_MODULUS as padded 32 byte big endian values</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> Bytes</span><span>(</span><span>U256</span><span>(</span><span class="z-constant">FIELD_ELEMENTS_PER_BLOB</span><span>)</span><span>.</span><span>to_be_bytes32</span><span>(</span><span>)</span><span class="z-keyword"> +</span><span> U256</span><span>(</span><span class="z-constant">BLS_MODULUS</span><span>)</span><span>.</span><span>to_be_bytes32</span><span>(</span><span>)</span><span>)</span></span></code></pre> <p>The precompile MUST reject non-canonical field elements (i.e. provided field elements MUST be strictly less than <code>BLS_MODULUS</code>).</p> <h3 id="consensus-layer-validation">Consensus layer validation</h3> <p>On the consensus layer the blobs are referenced, but not fully encoded, in the beacon block body. Instead of embedding the full contents in the body, the blobs are propagated separately, as "sidecars".</p> <p>This "sidecar" design provides forward compatibility for further data increases by black-boxing <code>is_data_available()</code>: with full sharding <code>is_data_available()</code> can be replaced by data-availability-sampling (DAS) thus avoiding all blobs being downloaded by all beacon nodes on the network.</p> <p>Note that the consensus layer is tasked with persisting the blobs for data availability, the execution layer is not.</p> <p>The <code>ethereum/consensus-specs</code> repository defines the following consensus layer changes involved in this EIP:</p> <ul> <li>Beacon chain: process updated beacon blocks and ensure blobs are available.</li> <li>P2P network: gossip and sync updated beacon block types and new blob sidecars.</li> <li>Honest validator: produce beacon blocks with blobs; sign and publish the associated blob sidecars.</li> </ul> <h3 id="execution-layer-validation">Execution layer validation</h3> <p>On the execution layer, the block validity conditions are extended 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"> 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"> check that the excess blob gas 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>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> <span class="giallo-l"></span> <span class="giallo-l"><span> blob_gas_used</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> tx</span><span class="z-keyword"> in</span><span> block</span><span>.</span><span>transactions</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"> modify the check for sufficient balance</span></span> <span class="giallo-l"><span> max_total_fee</span><span class="z-keyword"> =</span><span> tx</span><span>.</span><span>gas</span><span class="z-keyword"> *</span><span> tx</span><span>.</span><span>max_fee_per_gas</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> get_tx_type</span><span>(</span><span>tx</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> BLOB_TX_TYPE</span><span>:</span></span> <span class="giallo-l"><span> max_total_fee</span><span class="z-keyword"> +=</span><span> get_total_blob_gas</span><span>(</span><span>tx</span><span>)</span><span class="z-keyword"> *</span><span> tx</span><span>.</span><span>max_fee_per_blob_gas</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> signer</span><span>(</span><span>tx</span><span>)</span><span>.</span><span>balance</span><span class="z-keyword"> &gt;=</span><span> max_total_fee</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"> add validity logic specific to blob txs</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> get_tx_type</span><span>(</span><span>tx</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> BLOB_TX_TYPE</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> there must be at least one blob</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>tx</span><span>.</span><span>blob_versioned_hashes</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 class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> all versioned blob hashes must start with VERSIONED_HASH_VERSION_KZG</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> h</span><span class="z-keyword"> in</span><span> tx</span><span>.</span><span>blob_versioned_hashes</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> h</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> VERSIONED_HASH_VERSION_KZG</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 that the user was willing to at least pay the current blob base fee</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> tx</span><span>.</span><span>max_fee_per_blob_gas</span><span class="z-keyword"> &gt;=</span><span> get_base_fee_per_blob_gas</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"> keep track of total blob gas spent in the block</span></span> <span class="giallo-l"><span> blob_gas_used</span><span class="z-keyword"> +=</span><span> get_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"> ensure the total blob gas spent is at most equal to the limit</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> blob_gas_used</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> MAX_BLOB_GAS_PER_BLOCK</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 blob_gas_used matches header</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> block</span><span>.</span><span>header</span><span>.</span><span>blob_gas_used</span><span class="z-keyword"> ==</span><span> blob_gas_used</span></span> <span class="giallo-l"></span></code></pre><h3 id="networking">Networking</h3> <p>Blob transactions have two network representations. During transaction gossip responses (<code>PooledTransactions</code>), the EIP-2718 <code>TransactionPayload</code> of the blob transaction is wrapped to become:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>rlp([tx_payload_body, blobs, commitments, proofs])</span></span></code></pre> <p>Each of these elements are defined as follows:</p> <ul> <li><code>tx_payload_body</code> - is the <code>TransactionPayloadBody</code> of standard EIP-2718 <a href="https://wg-eips.ritovision.com/4844/#blob-transaction">blob transaction</a></li> <li><code>blobs</code> - list of <code>Blob</code> items</li> <li><code>commitments</code> - list of <code>KZGCommitment</code> of the corresponding <code>blobs</code></li> <li><code>proofs</code> - list of <code>KZGProof</code> of the corresponding <code>blobs</code> and <code>commitments</code></li> </ul> <p>The node MUST validate <code>tx_payload_body</code> and verify the wrapped data against it. To do so, ensure that:</p> <ul> <li>There are an equal number of <code>tx_payload_body.blob_versioned_hashes</code>, <code>blobs</code>, <code>commitments</code>, and <code>proofs</code>.</li> <li>The KZG <code>commitments</code> hash to the versioned hashes, i.e. <code>kzg_to_versioned_hash(commitments[i]) == tx_payload_body.blob_versioned_hashes[i]</code></li> <li>The KZG <code>commitments</code> match the corresponding <code>blobs</code> and <code>proofs</code>. (Note: this can be optimized using <code>verify_blob_kzg_proof_batch</code>, with a proof for a random evaluation at a point derived from the commitment and blob data for each blob)</li> </ul> <p>For body retrieval responses (<code>BlockBodies</code>), the standard EIP-2718 blob transaction <code>TransactionPayload</code> is used.</p> <p>Nodes MUST NOT automatically broadcast blob transactions to their peers. Instead, those transactions are only announced using <code>NewPooledTransactionHashes</code> messages, and can then be manually requested via <code>GetPooledTransactions</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="on-the-path-to-sharding">On the path to sharding</h3> <p>This EIP introduces blob transactions in the same format in which they are expected to exist in the final sharding specification. This provides a temporary but significant scaling relief for rollups by allowing them to initially scale to 0.375 MB per slot, with a separate fee market allowing fees to be very low while usage of this system is limited.</p> <p>The core goal of rollup scaling stopgaps is to provide temporary scaling relief, without imposing extra development burdens on rollups to take advantage of this relief. Today, rollups use calldata. In the future, rollups will have no choice but to use sharded data (also called "blobs") because sharded data will be much cheaper. Hence, rollups cannot avoid making a large upgrade to how they process data at least once along the way. But what we <em>can</em> do is ensure that rollups need to <em>only</em> upgrade once. This immediately implies that there are exactly two possibilities for a stopgap: (i) reducing the gas costs of existing calldata, and (ii) bringing forward the format that will be used for sharded data, but not yet actually sharding it. Previous EIPs were all a solution of category (i); this EIP is a solution of category (ii).</p> <p>The main tradeoff in designing this EIP is that of implementing more now versus having to implement more later: do we implement 25% of the work on the way to full sharding, or 50%, or 75%?</p> <p>The work that is already done in this EIP includes:</p> <ul> <li>A new transaction type, of the exact same format that will need to exist in "full sharding"</li> <li><em>All</em> of the execution-layer logic required for full sharding</li> <li><em>All</em> of the execution / consensus cross-verification logic required for full sharding</li> <li>Layer separation between <code>BeaconBlock</code> verification and data availability sampling blobs</li> <li>Most of the <code>BeaconBlock</code> logic required for full sharding</li> <li>A self-adjusting independent base fee for blobs</li> </ul> <p>The work that remains to be done to get to full sharding includes:</p> <ul> <li>A low-degree extension of the <code>commitments</code> in the consensus layer to allow 2D sampling</li> <li>An actual implementation of data availability sampling</li> <li>PBS (proposer/builder separation), to avoid requiring individual validators to process 32 MB of data in one slot</li> <li>Proof of custody or similar in-protocol requirement for each validator to verify a particular part of the sharded data in each block</li> </ul> <p>This EIP also sets the stage for longer-term protocol cleanups. For example, its (cleaner) gas base fee update rule could be applied to the primary basefee calculation.</p> <h3 id="how-rollups-would-function">How rollups would function</h3> <p>Instead of putting rollup block data in transaction calldata, rollups would expect rollup block submitters to put the data into blobs. This guarantees availability (which is what rollups need) but would be much cheaper than calldata. Rollups need data to be available once, long enough to ensure honest actors can construct the rollup state, but not forever.</p> <p>Optimistic rollups only need to actually provide the underlying data when fraud proofs are being submitted. The fraud proof can verify the transition in smaller steps, loading at most a few values of the blob at a time through calldata. For each value it would provide a KZG proof and use the point evaluation precompile to verify the value against the versioned hash that was submitted before, and then perform the fraud proof verification on that data as is done today.</p> <p>ZK rollups would provide two commitments to their transaction or state delta data: the blob commitment (which the protocol ensures points to available data) and the ZK rollup's own commitment using whatever proof system the rollup uses internally. They would use a proof of equivalence protocol, using the point evaluation precompile, to prove that the two commitments refer to the same data.</p> <h3 id="versioned-hashes-precompile-return-data">Versioned hashes &amp; precompile return data</h3> <p>We use versioned hashes (rather than commitments) as references to blobs in the execution layer to ensure forward compatibility with future changes. For example, if we need to switch to Merkle trees + STARKs for quantum-safety reasons, then we would add a new version, allowing the point evaluation precompile to work with the new format. Rollups would not have to make any EVM-level changes to how they work; sequencers would simply have to switch over to using a new transaction type at the appropriate time.</p> <p>However, the point evaluation happens inside a finite field, and it is only well defined if the field modulus is known. Smart contracts could contain a table mapping the commitment version to a modulus, but this would not allow smart contract to take into account future upgrades to a modulus that is not known yet. By allowing access to the modulus inside the EVM, the smart contract can be built so that it can use future commitments and proofs, without ever needing an upgrade.</p> <p>In the interest of not adding another precompile, we return the modulus and the polynomial degree directly from the point evaluation precompile. It can then be used by the caller. It is also "free" in that the caller can just ignore this part of the return value without incurring an extra cost -- systems that remain upgradable for the foreseeable future will likely use this route for now.</p> <h3 id="base-fee-per-blob-gas-update-rule">Base fee per blob gas update rule</h3> <p>The base fee per blob gas update rule is intended to approximate the formula <code>base_fee_per_blob_gas = MIN_BASE_FEE_PER_BLOB_GAS * e**(excess_blob_gas / BLOB_BASE_FEE_UPDATE_FRACTION)</code>, where <code>excess_blob_gas</code> is the total "extra" amount of blob gas that the chain has consumed relative to the "targeted" number (<code>TARGET_BLOB_GAS_PER_BLOCK</code> per block). Like EIP-1559, it's a self-correcting formula: as the excess goes higher, the <code>base_fee_per_blob_gas</code> increases exponentially, reducing usage and eventually forcing the excess back down.</p> <p>The block-by-block behavior is roughly as follows. If block <code>N</code> consumes <code>X</code> blob gas, then in block <code>N+1</code> <code>excess_blob_gas</code> increases by <code>X - TARGET_BLOB_GAS_PER_BLOCK</code>, and so the <code>base_fee_per_blob_gas</code> of block <code>N+1</code> increases by a factor of <code>e**((X - TARGET_BLOB_GAS_PER_BLOCK) / BLOB_BASE_FEE_UPDATE_FRACTION)</code>. Hence, it has a similar effect to the existing EIP-1559, but is more "stable" in the sense that it responds in the same way to the same total usage regardless of how it's distributed.</p> <p>The parameter <code>BLOB_BASE_FEE_UPDATE_FRACTION</code> controls the maximum rate of change of the base fee per blob gas. It is chosen to target a maximum change rate of <code>e**(TARGET_BLOB_GAS_PER_BLOCK / BLOB_BASE_FEE_UPDATE_FRACTION) ≈ 1.125</code> per block.</p> <h3 id="throughput">Throughput</h3> <p>The values for <code>TARGET_BLOB_GAS_PER_BLOCK</code> and <code>MAX_BLOB_GAS_PER_BLOCK</code> are chosen to correspond to a target of 3 blobs (0.375 MB) and maximum of 6 blobs (0.75 MB) per block. These small initial limits are intended to minimize the strain on the network created by this EIP and are expected to be increased in future upgrades as the network demonstrates reliability under larger blocks.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <h3 id="blob-non-accessibility">Blob non-accessibility</h3> <p>This EIP introduces a transaction type that has a distinct mempool version and execution-payload version, with only one-way convertibility between the two. The blobs are in the network representation and not in the consensus representation; instead, they are coupled with the beacon block. This means that there is now a part of a transaction that will not be accessible from the web3 API.</p> <h3 id="mempool-issues">Mempool issues</h3> <p>Blob transactions have a large data size at the mempool layer, which poses a mempool DoS risk, though not an unprecedented one as this also applies to transactions with large amounts of calldata.</p> <p>By only broadcasting announcements for blob transactions, receiving nodes will have control over which and how many transactions to receive, allowing them to throttle throughput to an acceptable level. <a href="https://wg-eips.ritovision.com/5793/">EIP-5793</a> will give further fine-grained control to nodes by extending the <code>NewPooledTransactionHashes</code> announcement messages to include the transaction type and size.</p> <p>In addition, we recommend including a 1.1x base fee per blob gas bump requirement to the mempool transaction replacement rules.</p> <h2 id="test-cases">Test Cases</h2> <p>Execution layer test cases for this EIP can be found in the <a rel="external" href="https://github.com/ethereum/execution-spec-tests/tree/1983444bbe1a471886ef7c0e82253ffe2a4053e1/tests/cancun/eip4844_blobs"><code>eip4844_blobs</code></a> of the <code>ethereum/execution-spec-tests</code> repository. Consensus layer test cases can be found <a rel="external" href="https://github.com/ethereum/consensus-specs/tree/2297c09b7e457a13f7b2261a28cb45777be82f83/tests/core/pyspec/eth2spec/test/deneb">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP increases the bandwidth requirements per beacon block by a maximum of ~0.75 MB. This is 40% larger than the theoretical maximum size of a block today (30M gas / 16 gas per calldata byte = 1.875M bytes), and so it will not greatly increase worst-case bandwidth. Post-merge, block times are static rather than an unpredictable Poisson distribution, giving a guaranteed period of time for large blocks to propagate.</p> <p>The <em>sustained</em> load of this EIP is much lower than alternatives that reduce calldata costs, even if the calldata is limited, because there is no expectation that the blobs need to be stored for as long as an execution payload. This makes it possible to implement a policy that these blobs must be kept for at least a certain period. The specific value chosen is <code>MIN_EPOCHS_FOR_BLOB_SIDECARS_REQUESTS</code> epochs, which is around 18 days, a much shorter delay compared to proposed (but yet to be implemented) one-year rotation times for execution payload history.</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-22T00:00:00+00:00 2026-02-11T14:48:25+00:00 Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/4834/

Extremely generic name resolution

<h2 id="abstract">Abstract</h2> <p>This is a standard for generic name resolution with arbitrarily complex access control and resolution. It permits a contract that implements this EIP (referred to as a "domain" hereafter) to be addressable with a more human-friendly name, with a similar purpose to <a href="https://wg-eips.ritovision.com/137/">ERC-137</a> (also known as "ENS").</p> <h2 id="motivation">Motivation</h2> <p>The advantage of this EIP over existing standards is that it provides a minimal interface that supports name resolution, adds standardized access control, and has a simple architecture. ENS, although useful, has a comparatively complex architecture and does not have standard access control.</p> <p>In addition, all domains (including subdomains, TLDs, and even the root itself) are actually implemented as domains, meaning that name resolution is a simple iterative algorithm, not unlike DNS itself.</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="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"> IDomain</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 domain has a subdomain with a given 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"> name</span><span class="z-comment"> The subdomain to query, in right to left order</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 domain has a subdomain with the given name, `false` otherwise</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hasDomain</span><span>(</span><span class="z-support">string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> 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">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"> Fetch the subdomain with a given name</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This should revert if `hasDomain(name)` is `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"> name</span><span class="z-comment"> The subdomain to fetch, in right to left order</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"> subdomain with the given name</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getDomain</span><span>(</span><span class="z-support">string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> 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">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="name-resolution">Name Resolution</h3> <p>To resolve a name (like <code>"a.b.c"</code>), split it by the delimiter (resulting in something like <code>["a", "b", "c"]</code>). Set <code>domain</code> initially to the root domain, and <code>path</code> to be an empty list.</p> <p>Pop off the last element of the array (<code>"c"</code>) and add it to the path, then call <code>domain.hasDomain(path)</code>. If it's <code>false</code>, then the domain resolution fails. Otherwise, set the domain to <code>domain.getDomain(path)</code>. Repeat until the list of split segments is empty.</p> <p>There is no limit to the amount of nesting that is possible. For example, <code>0.1.2.3.4.5.6.7.8.9.a.b.c.d.e.f.g.h.i.j.k.l.m.n.o.p.q.r.s.t.u.v.w.x.y.z</code> would be valid if the root contains <code>z</code>, and <code>z</code> contains <code>y</code>, and so on.</p> <p>Here is a solidity function that resolves a name:</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"> resolve</span><span>(</span><span class="z-support">string</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> splitName</span><span>,</span><span class="z-storage z-type"> IDomain</span><span class="z-variable"> root</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> IDomain current </span><span class="z-keyword">=</span><span> root</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> path </span><span class="z-keyword">=</span><span> [</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> splitName</span><span>.</span><span>length </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-keyword">=</span><span class="z-constant"> 0</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"> Append to back of list</span></span> <span class="giallo-l"><span> path</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>splitName</span><span>[</span><span>i</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Require that the current domain has a domain</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>current</span><span>.</span><span class="z-entity z-name">hasDomain</span><span>(</span><span>path</span><span>)</span><span>,</span><span class="z-string"> &quot;Name resolution failed&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Resolve subdomain</span></span> <span class="giallo-l"><span> current </span><span class="z-keyword">=</span><span> current</span><span>.</span><span class="z-entity z-name">getDomain</span><span>(</span><span>path</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> current</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="optional-extension-registerable">Optional Extension: Registerable</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"> IDomainRegisterable</span><span class="z-storage"> is</span><span class="z-entity z-name"> IDomain</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment">/ Events</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"> Must be emitted when a new subdomain is created (e.g. through `createDomain`)</span></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"> msg.sender for createDomain</span></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 for createDomain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> subdomain</span><span class="z-comment"> subdomain in createDomain</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SubdomainCreate</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">string</span><span class="z-variable"> name</span><span>, </span><span class="z-support">address</span><span class="z-variable"> subdomain</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"> Must be emitted when the resolved address for a domain is </span><span class="z-keyword">changed</span><span class="z-comment"> (e.g. with `setDomain`)</span></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"> msg.sender for setDomain</span></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 for setDomain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> subdomain</span><span class="z-comment"> subdomain in setDomain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> oldSubdomain</span><span class="z-comment"> the old subdomain</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SubdomainUpdate</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">string</span><span class="z-variable"> name</span><span>, </span><span class="z-support">address</span><span class="z-variable"> subdomain</span><span>, </span><span class="z-support">address</span><span class="z-variable"> oldSubdomain</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"> Must be emitted when a domain is unmapped (e.g. with `deleteDomain`)</span></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"> msg.sender for deleteDomain</span></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 for deleteDomain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> subdomain</span><span class="z-comment"> the old subdomain</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SubdomainDelete</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">string</span><span class="z-variable"> name</span><span>, </span><span class="z-support">address</span><span class="z-variable"> subdomain</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment">/ CRUD</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 subdomain with a given name</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This should revert if `canCreateDomain(msg.sender, name, pointer)` is `false` or if the domain 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"> name</span><span class="z-comment"> The subdomain name to be created</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> subdomain</span><span class="z-comment"> The subdomain to create</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createDomain</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"> address</span><span class="z-variable"> subdomain</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"> Update a subdomain with a given name</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This should revert if `canSetDomain(msg.sender, name, pointer)` is `false` of if the domain doesn&#39;t 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"> name</span><span class="z-comment"> The subdomain name to be updated</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> subdomain</span><span class="z-comment"> The subdomain to set</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setDomain</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"> address</span><span class="z-variable"> subdomain</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"> Delete the subdomain with a given name</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This should revert if the domain doesn&#39;t exist or if `canDeleteDomain(msg.sender, name)` is `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"> name</span><span class="z-comment"> The subdomain to delete</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> deleteDomain</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"> external</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">/ Parent Domain Access Control</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 if an account can create a subdomain with a given name</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This must return `false` if `hasDomain(name)` is `true`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> updater</span><span class="z-comment"> The account that may or may not be able to create/update a subdomain</span></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 subdomain name that would be created/updated</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> subdomain</span><span class="z-comment"> The subdomain that would be set</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"> an account can update or create the subdomain</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canCreateDomain</span><span>(</span><span class="z-support">address</span><span class="z-variable"> updater</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"> address</span><span class="z-variable"> subdomain</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"> Get if an account can update or create a subdomain with a given name</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This must return `false` if `hasDomain(name)` is `false`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If `getDomain(name)` is also a domain implementing the subdomain access control extension, this should return `false` if `getDomain(name).canMoveSubdomain(msg.sender, this, subdomain)` is `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"> updater</span><span class="z-comment"> The account that may or may not be able to create/update a subdomain</span></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 subdomain name that would be created/updated</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> subdomain</span><span class="z-comment"> The subdomain that would be set</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"> an account can update or create the subdomain</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canSetDomain</span><span>(</span><span class="z-support">address</span><span class="z-variable"> updater</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"> address</span><span class="z-variable"> subdomain</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"> Get if an account can delete the subdomain with a given name</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This must return `false` if `hasDomain(name)` is `false`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If `getDomain(name)` is a domain implementing the subdomain access control extension, this should return `false` if `getDomain(name).canDeleteSubdomain(msg.sender, this, subdomain)` is `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"> updater</span><span class="z-comment"> The account that may or may not be able to delete a subdomain</span></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 subdomain to delete</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"> an account can delete the subdomain</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canDeleteDomain</span><span>(</span><span class="z-support">address</span><span class="z-variable"> updater</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"> 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><h3 id="optional-extension-enumerable">Optional Extension: Enumerable</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"> IDomainEnumerable</span><span class="z-storage"> is</span><span class="z-entity z-name"> IDomain</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 all subdomains. Must revert if the number of domains is unknown or infinite.</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"> subdomain with the given index.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> subdomainByIndex</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">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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the total number of subdomains. Must revert if the number of domains is unknown or infinite.</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"> total number of subdomains.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalSubdomains</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></span></code></pre><h3 id="optional-extension-access-control">Optional Extension: Access Control</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"> IDomainAccessControl</span><span class="z-storage"> is</span><span class="z-entity z-name"> IDomain</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 if an account can move the subdomain away from the current domain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> May be called by `canSetDomain` of the parent domain - implement access control here!!!</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> updater</span><span class="z-comment"> The account that may be moving the subdomain</span></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 subdomain 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"> parent</span><span class="z-comment"> The parent domain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> newSubdomain</span><span class="z-comment"> The domain that will be set next</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"> an account can update the subdomain</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canMoveSubdomain</span><span>(</span><span class="z-support">address</span><span class="z-variable"> updater</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"> IDomain</span><span class="z-variable"> parent</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> newSubdomain</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"> Get if an account can unset this domain as a subdomain</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> May be called by `canDeleteDomain` of the parent domain - implement access control here!!!</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> updater</span><span class="z-comment"> The account that may or may not be able to delete a subdomain</span></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 subdomain to delete</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> parent</span><span class="z-comment"> The parent domain</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"> an account can delete the subdomain</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canDeleteSubdomain</span><span>(</span><span class="z-support">address</span><span class="z-variable"> updater</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"> IDomain</span><span class="z-variable"> parent</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>This EIP's goal, as mentioned in the abstract, is to have a simple interface for resolving names. Here are a few design decisions and why they were made:</p> <ul> <li>Name resolution algorithm <ul> <li>Unlike ENS's resolution algorithm, this EIP's name resolution is fully under the control of the contracts along the resolution path.</li> <li>This behavior is more intuitive to users.</li> <li>This behavior allows for greater flexibility - e.g. a contract that changes what it resolves to based on the time of day.</li> </ul> </li> <li>Parent domain access control <ul> <li>A simple "ownable" interface was not used because this specification was designed to be as generic as possible. If an ownable implementation is desired, it can be implemented.</li> <li>This also gives parent domains the ability to call subdomains' access control methods so that subdomains, too, can choose whatever access control mechanism they desire</li> </ul> </li> <li>Subdomain access control <ul> <li>These methods are included so that subdomains aren't always limited to their parent domain's access control</li> <li>The root domain can be controlled by a DAO with a non-transferable token with equal shares, a TLD can be controlled by a DAO with a token representing stake, a domain of that TLD can be controlled by a single owner, a subdomain of that domain can be controlled by a single owner linked to an NFT, and so on.</li> <li>Subdomain access control functions are suggestions: an ownable domain might implement an owner override, so that perhaps subdomains might be recovered if the keys are lost.</li> </ul> </li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is general enough to support ENS, but ENS is not general enough to support this EIP.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="malicious-canmovesubdomain-black-hole">Malicious canMoveSubdomain (Black Hole)</h3> <h4 id="description-malicious-canmovesubdomain">Description: Malicious <code>canMoveSubdomain</code></h4> <p>Moving a subdomain using <code>setDomain</code> is a potentially dangerous operation.</p> <p>Depending on the parent domain's implementation, if a malicious new subdomain unexpectedly returns <code>false</code> on <code>canMoveSubdomain</code>, that subdomain can effectively lock the ownership of the domain.</p> <p>Alternatively, it might return <code>true</code> when it isn't expected (i.e. a backdoor), allowing the contract owner to take over the domain.</p> <h4 id="mitigation-malicious-canmovesubdomain">Mitigation: Malicious <code>canMoveSubdomain</code></h4> <p>Clients should help by warning if <code>canMoveSubdomain</code> or <code>canDeleteSubdomain</code> for the new subdomain changes to <code>false</code>. It is important to note, however, that since these are functions, it is possible for the value to change depending on whether or not it has already been linked. It is also still possible for it to unexpectedly return true. It is therefore recommended to <strong>always</strong> audit the new subdomain's source code before calling <code>setDomain</code>.</p> <h3 id="parent-domain-resolution">Parent Domain Resolution</h3> <h4 id="description-parent-domain-resolution">Description: Parent Domain Resolution</h4> <p>Parent domains have full control of name resolution for their subdomains. If a particular domain is linked to <code>a.b.c</code>, then <code>b.c</code> can, depending on its code, set <code>a.b.c</code> to any domain, and <code>c</code> can set <code>b.c</code> itself to any domain.</p> <h4 id="mitigation-parent-domain-resolution">Mitigation: Parent Domain Resolution</h4> <p>Before acquiring a domain that has been pre-linked, it is recommended to always have the contract <strong>and</strong> all the parents up to the root audited.</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-17T00:00:00+00:00 2026-02-11T14:48:26+00:00 Joshua Tanhttps://github.com/thelastjosh Isaac Patkahttps://github.com/ipatka Ido Gershteinido@daostack.io Eyal Eithcowicheyal@deepdao.io Michael Zarghamhttps://github.com/mzargham Sam Furterhttps://github.com/nivida https://wg-eips.ritovision.com/4824/

An API for decentralized autonomous organizations (DAOs).

<h2 id="abstract">Abstract</h2> <p>An API standard for decentralized autonomous organizations (DAOs), focused on relating on-chain and off-chain representations of membership and proposals.</p> <h2 id="motivation">Motivation</h2> <p>DAOs, since being invoked in the Ethereum whitepaper, have been vaguely defined. This has led to a wide range of patterns but little standardization or interoperability between the frameworks and tools that have emerged. Standardization and interoperability are necessary to support a variety of use-cases. In particular, a standard daoURI, similar to tokenURI in <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, will enhance DAO discoverability, legibility, proposal simulation, and interoperability between tools. More consistent data across the ecosystem is also a prerequisite for future DAO 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> <p>Every contract implementing this EIP MUST implement the <code>IERC4824</code> interface 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.8.1</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-4824 DAOs</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See &lt;https://eips.ethereum.org/EIPS/eip-4824&gt;</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC4824</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DAOURIUpdate</span><span>(</span><span class="z-support">address</span><span class="z-variable"> daoAddress</span><span>, </span><span class="z-support">string</span><span class="z-variable"> daoURI</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"> A distinct Uniform Resource Identifier (URI) pointing to a JSON object following the &quot;ERC-4824 DAO JSON-LD Schema&quot;. This JSON file splits into four subsidiary URIs: membersURI, proposalsURI, activityLogURI, and governanceURI. The membersURI SHOULD point to a JSON file that conforms to the &quot;ERC-4824 Members JSON-LD Schema&quot;. The proposalsURI SHOULD point to a JSON file that conforms to the &quot;ERC-4824 Proposals JSON-LD Schema&quot;. The activityLogURI SHOULD point to a JSON file that conforms to the &quot;ERC-4824 Activity Log JSON-LD Schema&quot;. The governanceURI SHOULD point to a flatfile, normatively a .md file. Each of the JSON files named above MAY be statically-hosted or dynamically-generated. The content of subsidiary JSON files MAY be directly embedded as a JSON object directly within the top-level DAO JSON, in which case the relevant field MUST be renamed to remove the &quot;URI&quot; suffix. For example, &quot;membersURI&quot; would be renamed to &quot;members&quot;, &quot;proposalsURI&quot; would be renamed to &quot;proposals&quot;, and so on.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> daoURI</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 class="z-variable z-parameter z-function"> _daoURI</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The DAO JSON-LD Schema mentioned 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">@context</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">http://www.daostar.org/schemas</span><span class="z-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">DAO</span><span class="z-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">&lt;name of the DAO&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">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;description&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">membersURI</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;URI&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">proposalsURI</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;URI&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">activityLogURI</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;URI&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">governanceURI</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;URI&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">contractsURI</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;URI&gt;</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>A DAO MAY inherit the <code>IERC4824</code> interface above or it MAY create an external registration contract that is compliant with this EIP. Whether the DAO inherits the above interface or it uses an external registration contract, the DAO SHOULD define a method for and implement some access control logic to enable efficient updating for daoURI. If a DAO creates an external registration contract, the registration contract MUST store the DAO’s primary address, typically the address of the primary governance contract. See the reference implementation of external registration contract in the attached assets folder to this EIP.</p> <p>When reporting information in the DAO JSON-LD Schema, if a given field has no value (for example, <code>description</code>), it SHOULD be removed rather than left with an empty or <code>null</code> value.</p> <h3 id="indexing">Indexing</h3> <p>If a DAO inherits the <code>IERC4824</code> interface from a 4824-compliant DAO factory, then the DAO factory SHOULD incorporate a call to an indexer contract as part of the DAO's initialization to enable efficient network indexing. If the DAO is <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>-compliant, the factory can do this without additional permissions. If the DAO is <em>not</em> compliant with ERC-165, the factory SHOULD first obtain access control rights to the indexer contract and then call <code>logRegistration</code> directly with the address of the new DAO and the daoURI of the new DAO. Note that any user, including the DAO itself, MAY call <code>logRegistration</code> and submit a registration for a DAO which inherits the <code>IERC4824</code> interface and which is also ERC-165-compliant.</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.1</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> ERC4824InterfaceNotSupported</span><span>(</span><span>)</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"> ERC4824Index</span><span class="z-storage"> is</span><span class="z-entity z-name"> AccessControl</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> ERC165Checker</span><span class="z-keyword"> for</span><span class="z-entity z-name"> address</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 class="z-storage z-type"> constant</span><span> REGISTRATION_ROLE </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;REGISTRATION_ROLE&quot;</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"> DAOURIRegistered</span><span>(</span><span class="z-support">address</span><span class="z-variable"> daoAddress</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>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _grantRole</span><span>(</span><span>DEFAULT_ADMIN_ROLE</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"> _grantRole</span><span>(</span><span>REGISTRATION_ROLE</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"> function</span><span class="z-entity z-name"> logRegistrationPermissioned</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> daoAddress</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyRole</span><span>(</span><span class="z-entity z-name">REGISTRATION_ROLE</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> DAOURIRegistered</span><span>(</span><span>daoAddress</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"> logRegistration</span><span>(</span><span class="z-support">address</span><span class="z-variable"> daoAddress</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 class="z-keyword">!</span><span>daoAddress</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span class="z-variable z-language">type</span><span>(</span><span>IERC4824</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"> ERC4824InterfaceNotSupported</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> DAOURIRegistered</span><span>(</span><span>daoAddress</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>If a DAO uses an external registration contract, the DAO SHOULD use a common registration factory contract linked to a common indexer to enable efficient network indexing. See the reference implementation of the factory contract in the attached assets folder to this EIP.</p> <h4 id="indexing-priority">Indexing priority</h4> <p>daoURIs may be published directly in the DAO's contract or through a call to a common registration factory contract. In cases where both occur, the daoURI (and all sub-URIs) published through a call to a registration factory contract SHOULD take precedence. If there are multiple registrations, the most recent registration SHOULD take precedence.</p> <h3 id="members">Members</h3> <p>Members JSON-LD Schema. Every contract implementing this EIP SHOULD implement a membersURI pointing to a JSON object satisfying this schema. Below, DID refers to <a rel="external" href="https://www.w3.org/TR/2022/REC-did-core-20220719/">Decentralized Identifiers</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">@context</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://www.daostar.org/schemas</span><span class="z-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">DAO</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">members</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">&lt;CAIP-10 address, DID address, or other URI identifier&gt;</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">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;CAIP-10 address, DID address, or other URI identifier&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></code></pre> <p>For example, for an address on Ethereum Mainnet, the <a rel="external" href="https://github.com/ChainAgnostic/CAIPs/blob/ad0cfebc45a4b8368628340bf22aefb2a5edcab7/CAIPs/caip-10.md">CAIP-10</a> address would be of the form <code>eip155:1:0x1234abcd</code>, while the DID address would be of the form <code>did:ethr:0x1234abcd</code>.</p> <h3 id="proposals">Proposals</h3> <p>Proposals JSON-LD Schema. Every contract implementing this EIP SHOULD implement a proposalsURI pointing to a JSON object satisfying this schema.</p> <p>In particular, any on-chain proposal MUST be associated to an id of the form CAIP10_ADDRESS + “?proposalId=” + PROPOSAL_COUNTER, where CAIP10_ADDRESS is an address following the CAIP-10 standard and PROPOSAL_COUNTER is an arbitrary identifier such as a uint256 counter or a hash that is locally unique per CAIP-10 address. Off-chain proposals MAY use a similar id format where CAIP10_ADDRESS is replaced with an appropriate URI or URL.</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">@context</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://www.daostar.org/schemas</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">proposals</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">proposal</span><span class="z-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-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;proposal ID&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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;name or title of proposal&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">contentURI</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;URI to content/text of the proposal&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">discussionURI</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;URI to discussion or thread for the proposal&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">status</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;status of proposal&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">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">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">CallDataEVM</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">operation</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;call or delegate call&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">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;EthereumAddress&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">to</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;EthereumAddress&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">&lt;value&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;call data&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> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>When deferenced, contentURI should return the content (i.e. the text) of the proposal. Similarly, discussionURI should return a discussion link, whether a forum post, Discord channel, or Twitter thread.</p> <h3 id="activity-log">Activity Log</h3> <p>Activity Log JSON-LD Schema. Every contract implementing this EIP SHOULD implement a activityLogURI pointing to a JSON object satisfying this 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">@context</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://www.daostar.org/schemas</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">activities</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">&lt;activity ID&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">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">activity</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">proposal</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">proposal</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">id</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-invalid z-illegal">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;proposal ID&gt;</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">member</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">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;CAIP-10 address, DID address, or other URI identifier&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></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="contracts">Contracts</h3> <p>Contracts JSON-LD Schema. Every contract implementing this EIP SHOULD implement a contractsURI pointing to a JSON object satisfying this schema.</p> <p>contractsURI is especially important for DAOs with distinct or decentralized governance occurring across multiple different contracts, possibly across several chains. Multiple addresses may report the same daoURI.</p> <p>To prevent spam or spoofing, all DAOs adopting this specification SHOULD publish through contractsURI the address of every contract associated to the DAO, including but not limited to those that inherit the <code>IERC4824</code> interface or those that interact with a registration factory contract. Note that this includes the contract address(es) of any actual registration contracts deployed through a registration factory.</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">@context</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://www.daostar.org/schemas</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">contracts</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">&lt;CAIP-10 address, DID address, or other URI identifier&gt;</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">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-invalid z-illegal">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;name, e.g. Treasury&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">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;description, e.g. Primary operating treasury for the DAO&gt;</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">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;CAIP-10 address, DID address, or other URI identifier&gt;</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">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-invalid z-illegal">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;name, e.g. Governance Token&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">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;description, e.g. ERC20 governance token contract&gt;</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">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;CAIP-10 address, DID address, or other URI identifier&gt;</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">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-invalid z-illegal">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;name, e.g. Registration Contract&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">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;description, e.g. ERC-4824 registration contract&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></code></pre><h3 id="uri-fields">URI fields</h3> <p>The content of subsidiary JSON files MAY be directly embedded as a JSON object directly within the top-level DAO JSON, in which case the relevant field MUST be renamed to remove the "URI" suffix. For example, <code>membersURI</code> would be renamed to <code>members</code>, <code>proposalsURI</code> would be renamed to <code>proposals</code>, and so on. In all cases, the embedded JSON object MUST conform to the relevant schema. A given field and a URI-suffixed field (e.g. <code>membersURI</code> and <code>members</code>) SHOULD NOT appear in the same JSON-LD; if they do, the field without the URI suffix MUST take precedence.</p> <p>Fields which are not appended with URI MAY be appended with a URI, for example <code>name</code> and <code>description</code> may be renamed to <code>nameURI</code> and <code>descriptionURI</code>, in which case the dereferenced URI MUST return a JSON-LD object containing the <code>"@context": "https://www.daostar.org/schemas"</code> field and the original key-value pair.</p> <p>For example, descriptionURI should return:</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">@context</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://www.daostar.org/schemas</span><span class="z-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">&lt;description&gt;</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="entities-which-are-not-daos">Entities which are not DAOs</h3> <p>Entities which are not DAOs or which do not wish to identify as DAOs MAY still publish daoURIs. If so, they SHOULD use a different value for the <code>type</code> field than "DAO", for example "Organization", "Foundation", "Person", or, most broadly, "Entity".</p> <p>Entities which are not DAOs or which do not wish to identify as DAOs MAY also publish metadata information through an off-chain orgURI or entityURI, which are aliases of daoURI. If these entities are reporting their URI through an on-chain smart contract or registration, however, they MUST retain <code>IERC4824</code>'s daoURI in order to enable network indexing.</p> <p>The Entity JSON-LD 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">@context</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://www.daostar.org/schemas</span><span class="z-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">&lt;type of entity&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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;name of the entity&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">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;description&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">membersURI</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;URI&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">proposalsURI</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;URI&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">activityLogURI</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;URI&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">governanceURI</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;URI&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">contractsURI</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;URI&gt;</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>In this standard, we assume that all DAOs possess at least two primitives: <em>membership</em> and <em>behavior</em>. <em>Membership</em> is defined by a set of addresses. <em>Behavior</em> is defined by a set of possible contract actions, including calls to external contracts and calls to internal functions. <em>Proposals</em> relate membership and behavior; they are objects that members can interact with and which, if and when executed, become behaviors of the DAO.</p> <h3 id="apis-uris-and-off-chain-data">APIs, URIs, and off-chain data</h3> <p>DAOs themselves have a number of existing and emerging use-cases. But almost all DAOs need to publish data off-chain for a number of reasons: communicating to and recruiting members, coordinating activities, powering user interfaces and governance applications such as Snapshot or Tally, or enabling search and discovery via platforms like DeepDAO, Messari, and Etherscan. Having a standardized schema for this data organized across multiple URIs, i.e. an API specification, would strengthen existing use-cases for DAOs, help scale tooling and frameworks across the ecosystem, and build support for additional forms of interoperability.</p> <p>While we considered standardizing on-chain aspects of DAOs in this standard, particularly on-chain proposal objects and proposal IDs, we felt that this level of standardization was premature given (1) the relative immaturity of use-cases, such as multi-DAO proposals or master-minion contracts, that would benefit from such standardization, (2) the close linkage between proposal systems and governance, which we did not want to standardize (see “governanceURI”, below), and (3) the prevalence of off-chain and L2 voting and proposal systems in DAOs (see “proposalsURI”, below). Further, a standard URI interface is relatively easy to adopt and has been actively demanded by frameworks (see “Community Consensus”, below).</p> <p>We added the ability to append or remove the URI suffix to make dereferenced daoURIs easier to parse, especially in certain applications that did not want to maintain several services or flatfiles. Where there is a conflict, we decided that fields without the URI suffix should take precedence since they are more directly connected to the initial publication of daoURI.</p> <p>In terms of indexing: we believe that the most trustworthy way of publishing a daoURI is through an on-chain registration contract, as it is the clearest reflection of the active will of a DAO. It is also the primary way a DAO may “overwrite” any other daoURI that has previously been published, through any means. If a DAO inherits daoURI directly through its contract, then this information is also trustworthy, though slightly less so as it often reflects the decisions of a DAO framework rather than the DAO directly.</p> <h3 id="membersuri">membersURI</h3> <p>Approaches to membership vary widely in DAOs. Some DAOs and DAO frameworks (e.g. Gnosis Safe, Tribute), maintain an explicit, on-chain set of members, sometimes called owners or stewards. But many DAOs are structured so that membership status is based on the ownership of a token or tokens (e.g. Moloch, Compound, DAOstack, 1Hive Gardens). In these DAOs, computing the list of current members typically requires some form of off-chain indexing of events.</p> <p>In choosing to ask only for an (off-chain) JSON schema of members, we are trading off some on-chain functionality for more flexibility and efficiency. We expect different DAOs to use membersURI in different ways: to serve a static copy of on-chain membership data, to contextualize the on-chain data (e.g. many Gnosis Safe stewards would not say that they are the only members of the DAO), to serve consistent membership for a DAO composed of multiple contracts, or to point at an external service that computes the list, among many other possibilities. We also expect many DAO frameworks to offer a standard endpoint that computes this JSON file, and we provide a few examples of such endpoints in the implementation section.</p> <p>We encourage extensions of the Membership JSON-LD Schema, e.g. for DAOs that wish to create a state variable that captures active/inactive status or different membership levels.</p> <h3 id="proposalsuri">proposalsURI</h3> <p>Proposals have become a standard way for the members of a DAO to trigger on-chain actions, e.g. sending out tokens as part of a grant or executing arbitrary code in an external contract. In practice, however, many DAOs are governed by off-chain decision-making systems on platforms such as Discourse, Discord, or Snapshot, where off-chain proposals may function as signaling mechanisms for an administrator or as a prerequisite for a later on-chain vote. (To be clear, on-chain votes may also serve as non-binding signaling mechanisms or as “binding” signals leading to some sort of off-chain execution.) The schema we propose is intended to support both on-chain and off-chain proposals, though DAOs themselves may choose to report only on-chain, only off-chain, or some custom mix of proposal types.</p> <p><strong>Proposal ID</strong>. In the specification, we state that every unique on-chain proposal must be associated to a proposal ID of the form CAIP10_ADDRESS + “?proposalId=” + PROPOSAL_COUNTER, where PROPOSAL_COUNTER is an arbitrary string which is unique per CAIP10_ADDRESS. Note that PROPOSAL_COUNTER may not be the same as the on-chain representation of the proposal; however, each PROPOSAL_COUNTER should be unique per CAIP10_ADDRESS, such that the proposal ID is a globally unique identifier. We endorse the CAIP-10 standard to support multi-chain / layer 2 proposals and the “?proposalId=” query syntax to suggest off-chain usage.</p> <p><strong>ContentURI</strong>. In many cases, a proposal will have some (off-chain) content such as a forum post or a description on a voting platform which predates or accompanies the actual proposal.</p> <p><strong>Status</strong>. Almost all proposals have a status or state, but the actual status is tied to the governance system, and there is no clear consensus between existing DAOs about what those statuses should be (see table below). Therefore, we have defined a “status” property with a generic, free text description field.</p> <table><thead><tr><th>Project</th><th>Proposal Statuses</th></tr></thead><tbody> <tr><td>Aragon</td><td>Not specified</td></tr> <tr><td>Colony</td><td>[‘Null’, ‘Staking’, ‘Submit’, ‘Reveal’, ‘Closed’, ‘Finalizable’, ‘Finalized’, ‘Failed’]</td></tr> <tr><td>Compound</td><td>[‘Pending’, ‘Active’, ‘Canceled’, ‘Defeated’, ‘Succeeded’, ‘Queued’, ‘Expired’, ‘Executed’]</td></tr> <tr><td>DAOstack/ Alchemy</td><td>[‘None’, ‘ExpiredInQueue’, ‘Executed’, ‘Queued’, ‘PreBoosted’, ‘Boosted’, ‘QuietEndingPeriod’]</td></tr> <tr><td>Moloch v2</td><td>[sponsored, processed, didPass, cancelled, whitelist, guildkick]</td></tr> <tr><td>Tribute</td><td>[‘EXISTS’, ‘SPONSORED’, ‘PROCESSED’]</td></tr> </tbody></table> <p><strong>ExecutionData</strong>. For on-chain proposals with non-empty execution, we include an array field to expose the call data. The main use-case for this data is execution simulation of proposals.</p> <h3 id="activityloguri">activityLogURI</h3> <p>The activity log JSON is intended to capture the interplay between a member of a DAO and a given proposal. Examples of activities include the creation/submission of a proposal, voting on a proposal, disputing a proposal, and so on.</p> <p><em>Alternatives we considered: history, interactions</em></p> <h3 id="governanceuri">governanceURI</h3> <p>Membership, to be meaningful, usually implies rights and affordances of some sort, e.g. the right to vote on proposals, the right to ragequit, the right to veto proposals, and so on. But many rights and affordances of membership are realized off-chain (e.g. right to vote on a Snapshot, gated access to a Discord). Instead of trying to standardize these wide-ranging practices or forcing DAOs to locate descriptions of those rights on-chain, we believe that a flatfile represents the easiest and most widely-acceptable mechanism for communicating what membership means and how proposals work. These flatfiles can then be consumed by services such as Etherscan, supporting DAO discoverability and legibility.</p> <p>We chose the word “governance” as an appropriate word that reflects (1) the widespread use of the word in the DAO ecosystem and (2) the common practice of emitting a governance.md file in open-source software projects.</p> <p><em>Alternative names considered: description, readme, constitution</em></p> <h3 id="contractsuri">contractsURI</h3> <p>Over the course of community conversations, multiple parties raised the need to report on, audit, and index the different contracts belonging to a given DAO. Some of these contracts are deployed as part of the modular design of a single DAO framework, e.g. the core, voting, and timelock contracts within Open Zeppelin / Compound Governor. In other cases, a DAO might deploy multiple multsigs as treasuries and/or multiple subDAOs that are effectively controlled by the DAO. contractsURI offers a generic way of declaring these many instruments so that they can be efficiently aggregated by an indexer.</p> <p>contractsURI is also important for spam prevention or spoofing. Some DAOs may spread governance power and control across multiple different governance contracts, possibly across several chains. To capture this reality, multiple addresses may wish to report the same daoURI, or different daoURIs with the same name<!-- or the same ID-->. However, unauthorized addresses may try to report the same daoURI or name<!--, or ID -->. Additional contract information can prevent attacks of this sort by allowing indexers to weed out spam information.</p> <p><em>Alternative names considered: contractsRegistry, contractsList</em></p> <h3 id="why-json-ld">Why JSON-LD</h3> <p>We chose to use JSON-LD rather than the more widespread and simpler JSON standard because (1) we want to support use-cases where a DAO wants to include members using some other form of identification than their Ethereum address and (2) we want this standard to be compatible with future multi-chain standards. Either use-case would require us to implement a context and type for addresses, which is already implemented in JSON-LD.</p> <p>Further, given the emergence of patterns such as subDAOs and DAOs of DAOs in large organizations such as Synthetix, as well as L2 and multi-chain use-cases, we expect some organizations will point multiple DAOs to the same URI, which would then serve as a gateway to data from multiple contracts and services. The choice of JSON-LD allows for easier extension and management of that data.</p> <h3 id="community-consensus"><strong>Community Consensus</strong></h3> <p>The initial draft standard was developed as part of the DAOstar roundtable series, which included representatives from all major EVM-based DAO frameworks (Aragon, Compound, DAOstack, Gnosis, Moloch, OpenZeppelin, and Tribute), a wide selection of DAO tooling developers, as well as several major DAOs. Thank you to all the participants of the roundtable. We would especially like to thank Fabien of Snapshot, Jake Hartnell, Auryn Macmillan, Selim Imoberdorf, Lucia Korpas, and Mehdi Salehi for their contributions.</p> <p>In-person events for community comment were held at Schelling Point 2022, ETHDenver 2022, ETHDenver 2023, DAO Harvard 2023, DAO Stanford 2023 (also known as the Science of Blockchains Conference DAO Workshop). The team also hosted over 50 biweekly community calls as part of the DAOstar project.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Existing contracts that do not wish to use this specification are unaffected. DAOs that wish to adopt the standard without updating or migrating contracts can do so via an external registration contract.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This standard defines the interfaces for the DAO URIs but does not specify the rules under which the URIs are set, or how the data is prepared. Developers implementing this standard should consider how to update this data in a way aligned with the DAO’s governance model, and keep the data fresh in a way that minimizes reliance on centralized service providers.</p> <p>Indexers that rely on the data returned by the URI should take caution if DAOs return executable code from the URIs. This executable code might be intended to get the freshest information on membership, proposals, and activity log, but it could also be used to run unrelated tasks.</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-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Qi Zhouhttps://github.com/qizhou Chao Pihttps://github.com/pichaoqkc Sam Wilsonhttps://github.com/SamWilsn https://wg-eips.ritovision.com/4804/

A translation of an HTTP-style Web3 URL to an EVM call message

<h2 id="abstract">Abstract</h2> <p>This standard translates an RFC 2396 URI like <code>web3://uniswap.eth/</code> to an EVM message such as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>EVMMessage {</span></span> <span class="giallo-l"><span> To: 0xaabbccddee.... // where uniswap.eth&#39;s address registered at ENS</span></span> <span class="giallo-l"><span> Calldata: 0x</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="motivation">Motivation</h2> <p>Currently, reading data from Web3 generally relies on a translation done by a Web2 proxy to Web3 blockchain. The translation is mostly done by the proxies such as dApp websites/node service provider/etherscan, which are out of the control of users. The standard here aims to provide a simple way for Web2 users to directly access the content of Web3, especially on-chain Web contents such as SVG/HTML. Moreover, this standard enables interoperability with other standards already compatible with URIs, like SVG/HTML.</p> <h2 id="specification">Specification</h2> <p>This specification only defines read-only (i.e. Solidity's <code>view</code> functions) semantics. State modifying functions may be defined as a future extension.</p> <p>A Web3 URL is in the following form</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3URL = web3Schema [userinfo &quot;@&quot;] contractName [&quot;:&quot; chainid] path [&quot;?&quot; query]</span></span> <span class="giallo-l"><span>web3Schema = [ &quot;ethereum-web3://&quot; | &quot;eth-web3://&quot; | &quot;web3://&quot; ]</span></span> <span class="giallo-l"><span>contractName = address | [name &quot;.&quot; [ subDomain0 &quot;.&quot; ... ]] nsProviderSuffix</span></span> <span class="giallo-l"><span>path = [&quot;/&quot; method [&quot;/&quot; argument_0 [&quot;/&quot; argument_1 ... ]]]</span></span> <span class="giallo-l"><span>argument = [type &quot;!&quot;] value</span></span> <span class="giallo-l"><span>query = &quot;attribute_1=value_1 [ &quot;&amp;&quot; attribute_2=value_2 ... ]</span></span> <span class="giallo-l"><span>attribute = &quot;returns&quot; | &quot;returnTypes&quot; | other_attribute</span></span></code></pre> <p>where</p> <ul> <li><strong>web3Schema</strong> indicates the schema of the URL, which is <code>web3://</code> or <code>w3://</code> for short.</li> <li><strong>userinfo</strong> indicates which user is calling the EVM, i.e., "From" field in EVM call message. If not specified, the protocol will use 0x0 as the sender address.</li> <li><strong>contractName</strong> indicates the contract to be called, i.e., "To" field in the EVM call message. If the <strong>contractName</strong> is an <strong>address</strong>, i.e., 0x + 20-byte-data hex, then "To" will be the address. Otherwise, the name is from a name service. In the second case, <strong>nsProviderSuffix</strong> will be the suffix from name service providers such as "eth", etc. The way to translate the name from a name service to an address will be discussed in later EIPs.</li> <li><strong>chainid</strong> indicates which chain to resolve <strong>contractName</strong> and call the message. If not specified, the protocol will use the same chain as the name service provider, e.g., 1 for eth. If no name service provider is available, the default chainid is 1.</li> <li><strong>query</strong> is an optional component containing a sequence of attribute-value pairs separated by "&amp;".</li> </ul> <h3 id="resolve-mode">Resolve Mode</h3> <p>Once the "To" address and chainid are determined, the protocol will check the resolver mode of contract by calling "resolveMode" method. The protocol currently supports two resolve modes:</p> <h4 id="manual-mode">Manual Mode</h4> <p>The manual mode will not do any interpretation of <strong>path</strong> and <strong>query</strong>, and put <strong>path</strong> [ "?" <strong>query</strong> ] as the calldata of the message directly.</p> <h4 id="auto-mode">Auto Mode</h4> <p>The auto mode is the default mode to resolve (also applies when the "resolveMode" method is unavailable in the target contract). In the auto mode, if <strong>path</strong> is empty, then the protocol will call the target contract with empty calldata. Otherwise, the calldata of the EVM message will use standard Solidity contract ABI, where</p> <ul> <li><strong>method</strong> is a string of function method be called</li> <li><strong>argument_i</strong> is the ith argument of the method. If <strong>type</strong> is specified, the value will be translated to the corresponding type. The protocol currently supports the basic types such as uint256, bytes32, address, bytes, and string. If <strong>type</strong> is not specified, then the type will be automatically detected using the following rule in a sequential way:</li> </ul> <ol> <li><strong>type</strong>="uint256", if <strong>value</strong> is numeric; or</li> <li><strong>type</strong>="bytes32", if <strong>value</strong> is in the form of 0x+32-byte-data hex; or</li> <li><strong>type</strong>="address", if <strong>value</strong> is in the form of 0x+20-byte-data hex; or</li> <li><strong>type</strong>="bytes", if <strong>value</strong> is in the form of 0x followed by any number of bytes besides 20 or 32; or</li> <li>else <strong>type</strong>="address" and parse the argument as a domain name in the form of <code>[name "." [ subDomain0 "." ... ]] nsProviderSuffix</code>. In this case, the actual value of the argument will be obtained from <strong>nsProviderSuffix</strong>, e.g., eth. If <strong>nsProviderSuffix</strong> is not supported, an unsupported NS provider error will be returned.</li> </ol> <p>Note that if <strong>method</strong> does not exist, i.e., <strong>path</strong> is empty or "/", then the contract will be called with empty calldata.</p> <ul> <li><strong>returns</strong> attribute in <strong>query</strong> tells the format of the returned data. If not specified, the returned message data will be parsed in "(bytes32)" and MIME will be set based on the suffix of the last argument. If <strong>returns</strong> is "()", the returned data will be parsed in raw bytes in JSON. Otherwise, the returned message will be parsed in the specified <strong>returns</strong> attribute in JSON. If multiple <strong>returns</strong> attributes are present, the value of the last <strong>returns</strong> attribute will be applied. Note that <strong>returnTypes</strong> is the alias of <strong>returns</strong>, but it is not recommended to use and is mainly for backward-compatible purpose.</li> </ul> <h3 id="examples">Examples</h3> <h4 id="example-1">Example 1</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://w3url.eth/</span></span></code></pre> <p>The protocol will find the address of <strong>w3url.eth</strong> from ENS in chainid 1 (Mainnet), and then the protocol will call the address with "From" = "0x..." and "Calldata" = "0x2F".</p> <h4 id="example-2">Example 2</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://cyberbrokers-meta.eth/renderBroker/9999</span></span></code></pre> <p>The protocol will find the address of <strong>cyberbrokers-meta.eth</strong> from ENS on chainid 1 (Mainnet), and then call the address with "To" = "0x..." and "Calldata" = "0x" + <code>keccak("view(uint256)")[0:4] + abi.encode(uint256(9999))</code>.</p> <h4 id="example-3">Example 3</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://vitalikblog.eth:5/</span></span></code></pre> <p>The protocol will find the address of <strong>vitalikblog.eth</strong> from ENS on chainid 5 (Goerli), and then call the address with "From" = "0x..." and "Calldata" = "0x2F" with chainid = 5.</p> <h4 id="example-4">Example 4</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://0xe4ba0e245436b737468c206ab5c8f4950597ab7f:42170/</span></span></code></pre> <p>The protocol will call the address with "To" = "0x9e081Df45E0D167636DB9C61C7ce719A58d82E3b" and "Calldata" = "0x" with chainid = 42170 (Arbitrum Nova).</p> <h4 id="example-5">Example 5</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/balanceOf/vitalik.eth?returns=(uint256)</span></span></code></pre> <p>The protocol will find the addresses of <strong>vitalik.eth</strong> from ENS on chainid 1 (Mainnet) and then call the method "balanceOf(address)" of the contract with the <strong>charles.eth</strong>'s address. The returned data will be parsed as uint256 like <code>[ "10000000000000" ]</code>.</p> <h4 id="example-6">Example 6</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>web3://0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48/balanceOf/vitalik.eth?returns=()</span></span></code></pre> <p>The protocol will find the address of <strong>vitalik.eth</strong> from ENS on chainid 1 (Mainnet) and then call the method "balanceOf(address)" of the address. The returned data will be parsed as raw bytes like <code>["0x000000000000000000000000000000000000000000000000000009184e72a000"]</code>.</p> <h2 id="rationale">Rationale</h2> <p>The purpose of the proposal is to add a decentralized presentation layer for Ethereum. With the layer, we are able to render any web content (including HTML/CSS/JPG/PNG/SVG, etc) on-chain using human-readable URLs, and thus EVM can be served as decentralized Backend. The design of the standard is based on the following principles:</p> <ul> <li> <p><strong>Human-readable</strong>. The Web3 URL should be easily recognized by human similar to Web2 URL (<code>http://</code>). As a result, we support names from name services to replace address for better readability. In addition, instead of using calldata in hex, we use human-readable method + arguments and translate them to calldata for better readability.</p> </li> <li> <p><strong>Maximum-Compatible with HTTP-URL standard</strong>. The Web3 URL should be compatible with HTTP-URL standard including relative pathing, query, fragment, etc so that the support of existing HTTP-URL (e.g., by browser) can be easily extended to Web3 URL with minimal modification. This also means that existing Web2 users can easily migrate to Web3 with minimal extra knowledge of this standard.</p> </li> <li> <p><strong>Simple</strong>. Instead of providing explicit types in arguments, we use a "maximum likelihood" principle of auto-detecting the types of the arguments such as address, bytes32, and uint256. This could greatly minimize the length of URL, while avoiding confusion. In addition, explicit types are also supported to clear the confusion if necessary.</p> </li> <li> <p><strong>Flexible</strong>. The contract is able to override the encoding rule so that the contract has fine-control of understanding the actual Web resources that the users want to locate.</p> </li> </ul> <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-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-10T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Stokeshttps://github.com/ralexstokes Ansgar Dietrichshttps://github.com/adietrichs Danny Ryanhttps://github.com/djrtwo Martin Holst Swendehttps://github.com/holiman lightclienthttps://github.com/lightclient https://wg-eips.ritovision.com/4788/

Expose beacon chain roots in the EVM

<h2 id="abstract">Abstract</h2> <p>Commit to the hash tree root of each beacon chain block in the corresponding execution payload header.</p> <p>Store each of these roots in a smart contract.</p> <h2 id="motivation">Motivation</h2> <p>Roots of the beacon chain blocks are cryptographic accumulators that allow proofs of arbitrary consensus state. Exposing these roots inside the EVM allows for trust-minimized access to the consensus layer. This functionality supports a wide variety of use cases that improve trust assumptions of staking pools, restaking constructions, smart contract bridges, MEV mitigations and more.</p> <h2 id="specification">Specification</h2> <table><thead><tr><th>constants</th><th>value</th></tr></thead><tbody> <tr><td><code>FORK_TIMESTAMP</code></td><td><code>1710338135</code></td></tr> <tr><td><code>HISTORY_BUFFER_LENGTH</code></td><td><code>8191</code></td></tr> <tr><td><code>SYSTEM_ADDRESS</code></td><td><code>0xfffffffffffffffffffffffffffffffffffffffe</code></td></tr> <tr><td><code>BEACON_ROOTS_ADDRESS</code></td><td><code>0x000F3df6D732807Ef1319fB7B8bB8522d0Beac02</code></td></tr> </tbody></table> <h3 id="background">Background</h3> <p>The high-level idea is that each execution block contains the parent beacon block's root. Even in the event of missed slots since the previous block root does not change, we only need a constant amount of space to represent this "oracle" in each execution block. To improve the usability of this oracle, a small history of block roots are stored in the contract.</p> <p>To bound the amount of storage this construction consumes, a ring buffer is used that mirrors a block root accumulator on the consensus layer.</p> <h3 id="block-structure-and-validity">Block structure and validity</h3> <p>Beginning at the execution timestamp <code>FORK_TIMESTAMP</code>, execution clients <strong>MUST</strong> extend the header schema with an additional field: the <code>parent_beacon_block_root</code>. This root consumes 32 bytes and is exactly the <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/fa09d896484bbe240334fa21ffaa454bafe5842e/ssz/simple-serialize.md#merkleization">hash tree root</a> of the parent beacon block for the given execution block.</p> <p>The resulting RLP encoding of the header is therefore:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>rlp</span><span>(</span><span>[</span></span> <span class="giallo-l"><span> parent_hash</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> ommers hash</span></span> <span class="giallo-l"><span> coinbase</span><span>,</span></span> <span class="giallo-l"><span> state_root</span><span>,</span></span> <span class="giallo-l"><span> txs_root</span><span>,</span></span> <span class="giallo-l"><span> receipts_root</span><span>,</span></span> <span class="giallo-l"><span> logs_bloom</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 0</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> difficulty</span></span> <span class="giallo-l"><span> number</span><span>,</span></span> <span class="giallo-l"><span> gas_limit</span><span>,</span></span> <span class="giallo-l"><span> gas_used</span><span>,</span></span> <span class="giallo-l"><span> timestamp</span><span>,</span></span> <span class="giallo-l"><span> extradata</span><span>,</span></span> <span class="giallo-l"><span> prev_randao</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">0000000000000000</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> nonce</span></span> <span class="giallo-l"><span> base_fee_per_gas</span><span>,</span></span> <span class="giallo-l"><span> withdrawals_root</span><span>,</span></span> <span class="giallo-l"><span> blob_gas_used</span><span>,</span></span> <span class="giallo-l"><span> excess_blob_gas</span><span>,</span></span> <span class="giallo-l"><span> parent_beacon_block_root</span><span>,</span></span> <span class="giallo-l"><span>]</span><span>)</span></span></code></pre> <p>Validity of the parent beacon block root 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 root value in the block header matches the one provided by the consensus client.</p> <p>For a genesis block with no existing parent beacon block root the 32 zero bytes are used as a root placeholder.</p> <h4 id="beacon-roots-contract">Beacon roots contract</h4> <p>The beacon roots contract has two operations: <code>get</code> and <code>set</code>. The input itself is not used to determine which function to execute, for that the result of <code>caller</code> is used. If <code>caller</code> is equal to <code>SYSTEM_ADDRESS</code> then the operation to perform is <code>set</code>. Otherwise, <code>get</code>.</p> <h5 id="get"><code>get</code></h5> <ul> <li>Callers provide the <code>timestamp</code> they are querying encoded as 32 bytes in big-endian format.</li> <li>If the input is not exactly 32 bytes, the contract must revert.</li> <li>If the input is equal to 0, the contract must revert.</li> <li>Given <code>timestamp</code>, the contract computes the storage index in which the timestamp is stored by computing the modulo <code>timestamp % HISTORY_BUFFER_LENGTH</code> and reads the value.</li> <li>If the <code>timestamp</code> does not match, the contract must revert.</li> <li>Finally, the beacon root associated with the timestamp is returned to the user. It is stored at <code>timestamp % HISTORY_BUFFER_LENGTH + HISTORY_BUFFER_LENGTH</code>.</li> </ul> <h5 id="set"><code>set</code></h5> <ul> <li>Caller provides the parent beacon block root as calldata to the contract.</li> <li>Set the storage value at <code>header.timestamp % HISTORY_BUFFER_LENGTH</code> to be <code>header.timestamp</code></li> <li>Set the storage value at <code>header.timestamp % HISTORY_BUFFER_LENGTH + HISTORY_BUFFER_LENGTH</code> to be <code>calldata[0:32]</code></li> </ul> <h5 id="pseudocode">Pseudocode</h5> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">if</span><span> evm</span><span>.</span><span>caller</span><span class="z-keyword"> ==</span><span class="z-constant"> SYSTEM_ADDRESS</span><span>:</span></span> <span class="giallo-l"><span class="z-support"> set</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">else</span><span>:</span></span> <span class="giallo-l"><span> get</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</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>evm</span><span>.</span><span>calldata</span><span>)</span><span class="z-keyword"> !=</span><span class="z-constant"> 32</span><span>:</span></span> <span class="giallo-l"><span> evm</span><span>.</span><span>revert</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> to_uint256_be</span><span>(</span><span>evm</span><span>.</span><span>calldata</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> evm</span><span>.</span><span>revert</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> timestamp_idx</span><span class="z-keyword"> =</span><span> to_uint256_be</span><span>(</span><span>evm</span><span>.</span><span>calldata</span><span>)</span><span class="z-keyword"> %</span><span class="z-constant"> HISTORY_BUFFER_LENGTH</span></span> <span class="giallo-l"><span> timestamp</span><span class="z-keyword"> =</span><span> storage</span><span>.</span><span>get</span><span>(</span><span>timestamp_idx</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> timestamp</span><span class="z-keyword"> !=</span><span> evm</span><span>.</span><span>calldata</span><span>:</span></span> <span class="giallo-l"><span> evm</span><span>.</span><span>revert</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> root_idx</span><span class="z-keyword"> =</span><span> timestamp_idx</span><span class="z-keyword"> +</span><span class="z-constant"> HISTORY_BUFFER_LENGTH</span></span> <span class="giallo-l"><span> root</span><span class="z-keyword"> =</span><span> storage</span><span>.</span><span>get</span><span>(</span><span>root_idx</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> evm</span><span>.</span><span class="z-keyword">return</span><span>(</span><span>root</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-support"> set</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> timestamp_idx</span><span class="z-keyword"> =</span><span> to_uint256_be</span><span>(</span><span>evm</span><span>.</span><span>timestamp</span><span>)</span><span class="z-keyword"> %</span><span class="z-constant"> HISTORY_BUFFER_LENGTH</span></span> <span class="giallo-l"><span> root_idx</span><span class="z-keyword"> =</span><span> timestamp_idx</span><span class="z-keyword"> +</span><span class="z-constant"> HISTORY_BUFFER_LENGTH</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> storage</span><span>.</span><span>set</span><span>(</span><span>timestamp_idx</span><span>,</span><span> evm</span><span>.</span><span>timestamp</span><span>)</span></span> <span class="giallo-l"><span> storage</span><span>.</span><span>set</span><span>(</span><span>root_idx</span><span>,</span><span> evm</span><span>.</span><span>calldata</span><span>)</span></span></code></pre><h5 id="bytecode">Bytecode</h5> <p>The exact contract bytecode is shared below.</p> <pre class="giallo z-code"><code data-lang="asm"><span class="giallo-l"><span>caller</span></span> <span class="giallo-l"><span>push20 </span><span class="z-constant">0xfffffffffffffffffffffffffffffffffffffffe</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x4d</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x20</span></span> <span class="giallo-l"><span>calldatasize</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x24</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>revert</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>calldataload</span></span> <span class="giallo-l"><span>dup1</span></span> <span class="giallo-l"><span>iszero</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x49</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push3 </span><span class="z-constant">0x001fff</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>mod</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x3c</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>revert</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push3 </span><span class="z-constant">0x001fff</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 </span><span class="z-constant">0x20</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>revert</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push3 </span><span class="z-constant">0x001fff</span></span> <span class="giallo-l"><span>timestamp</span></span> <span class="giallo-l"><span>mod</span></span> <span class="giallo-l"><span>timestamp</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>calldataload</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>push3 </span><span class="z-constant">0x001fff</span></span> <span class="giallo-l"><span class="z-keyword">add</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>stop</span></span></code></pre><h4 id="deployment">Deployment</h4> <p>The beacon roots contract is deployed like any other smart contract. A special synthetic address is generated by working backwards from the desired deployment transaction:</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">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">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">to</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x3d090</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasPrice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe8d4a51000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxPriorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</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">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">input</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x60618060095f395ff33373fffffffffffffffffffffffffffffffffffffffe14604d57602036146024575f5ffd5b5f35801560495762001fff810690815414603c575f5ffd5b62001fff01545f5260205ff35b5f5ffd5b62001fff42064281555f359062001fff015500</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">v</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">r</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x539</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">s</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b9b6eb1f0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xdf52c2d3bbe38820fff7b5eaab3db1b91f8e1412b56497d88388fb5d4ea1fde0</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Note, the input in the transaction has a simple constructor prefixing the desired runtime code.</p> <p>The sender of the transaction can be calculated as <code>0x0B799C86a49DEeb90402691F1041aa3AF2d3C875</code>. The address of the first contract deployed from the account is <code>rlp([sender, 0])</code> which equals <code>0x000F3df6D732807Ef1319fB7B8bB8522d0Beac02</code>. This is how <code>BEACON_ROOTS_ADDRESS</code> is determined. Although this style of contract creation is not tied to any specific initcode like create2 is, the synthetic address is cryptographically bound to the input data of the transaction (e.g. the initcode).</p> <h3 id="block-processing">Block processing</h3> <p>At the start of processing any execution block where <code>block.timestamp &gt;= FORK_TIMESTAMP</code> (i.e. before processing any transactions), call <code>BEACON_ROOTS_ADDRESS</code> as <code>SYSTEM_ADDRESS</code> with the 32-byte input of <code>header.parent_beacon_block_root</code>, a gas limit of <code>30_000_000</code>, and <code>0</code> value. This will trigger the <code>set()</code> routine of the beacon roots contract. This is a system operation and therefore:</p> <ul> <li>the call must execute to completion</li> <li>the call does not count against the block's gas limit</li> <li>the call does not follow the <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> burn semantics - no value should be transferred as part of the call</li> <li>if no code exists at <code>BEACON_ROOTS_ADDRESS</code>, the call must fail silently</li> </ul> <p>Clients may decide to omit an explicit EVM call and directly set the storage values. Note: While this is a valid optimization for Ethereum mainnet, it could be problematic on non-mainnet situations in case a different contract is used.</p> <p>If this EIP is active in a genesis block, the genesis header's <code>parent_beacon_block_root</code> must be <code>0x0</code> and no system transaction may occur.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-not-repurpose-blockhash">Why not repurpose <code>BLOCKHASH</code>?</h3> <p>The <code>BLOCKHASH</code> opcode could be repurposed to provide the beacon root instead of some execution block hash. To minimize code change, avoid breaking changes to smart contracts, and simplify deployment to mainnet, this EIP suggests leaving <code>BLOCKHASH</code> alone and adding new functionality with the desired semantics.</p> <h3 id="beacon-block-root-instead-of-state-root">Beacon block root instead of state root</h3> <p>Block roots are preferred over state roots so there is a constant amount of work to do with each new execution block. Otherwise, skipped slots would require a linear amount of work with each new payload. While skipped slots are quite rare on mainnet, it is best to not add additional load under what would already be nonfavorable conditions.</p> <p>Use of block root over state root does mean proofs will require a few additional nodes but this cost is negligible (and could be amortized across all consumers, e.g. with a singleton state root contract that caches the proof per slot).</p> <h3 id="why-two-ring-buffers">Why two ring buffers?</h3> <p>The first ring buffer only tracks <code>HISTORY_BUFFER_LENGTH</code> worth of roots and so for all possible timestamp values would consume a constant amount of storage. However, this design opens the contract to an attack where a skipped slot that has the same value modulo the ring buffer length would return an old root value, rather than the most recent one.</p> <p>To nullify this attack while retaining a fixed memory footprint, this EIP keeps track of the pair of data <code>(parent_beacon_block_root, timestamp)</code> for each index into the ring buffer and verifies the timestamp matches the one originally used to write the root data when being read. Given the fixed size of storage slots (only 32 bytes), the requirement to store a pair of values necessitates two ring buffers, rather than just one.</p> <h3 id="size-of-ring-buffers">Size of ring buffers</h3> <p>The ring buffer data structures are sized to hold 8191 roots from the consensus layer. Using a prime number as the ring buffer size ensures that no value is overwritten until the entire ring buffer has been saturated and thereafter, each value will be updated once per iteration. This also means that even if the slot times were to change, we would continue to use at most 8191 storage slots.</p> <p>Given the current mainnet values, 8191 roots provides about a day of coverage. This gives users plenty of time to make a transaction with a verification against a specific root and get the transaction included on-chain.</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> 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-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 Ignacio Hagopianhttps://github.com/jsign Tanishq Jasoriahttps://github.com/tanishqjasoria Gajinder Singhhttps://github.com/g11tech https://wg-eips.ritovision.com/4762/

Changes the gas schedule to reflect the costs of creating a witness by requiring clients update their database layout to match.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces changes in the gas schedule to reflect the costs of creating a witness. It requires clients to update their database layout to match this, so as to avoid potential DoS attacks.</p> <h2 id="motivation">Motivation</h2> <p>The introduction of Verkle trees into Ethereum requires fundamental changes and as a preparation, this EIP is targeting the fork coming right before the verkle tree fork, in order to incentivize Dapp developers to adopt the new storage model, and ample time to adjust to it. It also incentivizes client developers to migrate their database format ahead of the verkle fork.</p> <h2 id="specification">Specification</h2> <h3 id="helper-functions">Helper functions</h3> <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_storage_slot_tree_keys</span><span>(</span><span class="z-variable z-parameter z-function">storage_key</span><span>:</span><span class="z-support"> int</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 class="z-keyword"> if</span><span> storage_key</span><span class="z-keyword"> &lt;</span><span> (</span><span class="z-constant">CODE_OFFSET</span><span class="z-keyword"> -</span><span class="z-constant"> HEADER_STORAGE_OFFSET</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> =</span><span class="z-constant"> HEADER_STORAGE_OFFSET</span><span class="z-keyword"> +</span><span> storage_key</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> =</span><span class="z-constant"> MAIN_STORAGE_OFFSET</span><span class="z-keyword"> +</span><span> storage_key</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> //</span><span class="z-constant"> 256</span><span>,</span></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> %</span><span class="z-constant"> 256</span></span> <span class="giallo-l"><span> )</span></span></code></pre><h3 id="access-events">Access events</h3> <p>Whenever the state is read, one or more of the access events of the form <code>(address, sub_key, leaf_key)</code> take place, determining what data is being accessed. We define access events as follows:</p> <h4 id="access-events-for-account-headers">Access events for account headers</h4> <p>When:</p> <ol> <li>a non-precompile which is also not a system contract is the target of a <code>*CALL</code>, <code>CALLCODE</code>, <code>SELFDESTRUCT</code>, <code>EXTCODESIZE</code>, or <code>EXTCODECOPY</code> opcode,</li> <li>a non-precompile which is also not a system contract is the target address of a contract creation whose initcode starts execution,</li> <li>any address is the target of the <code>BALANCE</code> opcode</li> <li>a <em>deployed</em> contract calls <code>CODECOPY</code></li> </ol> <p>process this access event:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(address, 0, BASIC_DATA_LEAF_KEY)</span></span></code></pre> <p>Note: a non-value-bearing <code>SELFDESTRUCT</code>, <code>*CALL</code> or <code>CALLCODE</code>, targeting a precompile or a system contract, will not cause the <code>BASIC_DATA_LEAF_KEY</code> to be added to the witness.</p> <p>If a <code>*CALL</code>, <code>CALLCODE</code> or <code>SELFDESTRUCT</code> is value-bearing (ie. it transfers nonzero wei), whether or not the <code>callee</code> is a precompile or a system contract, process this additional access event:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(caller, 0, BASIC_DATA_LEAF_KEY)</span></span></code></pre> <p>Note: when checking for the existence of the <code>callee</code>, the existence check is done by validating that there is an extension-and-suffix tree at the corresponding stem, and does not rely on <code>CODEHASH_LEAF_KEY</code>.</p> <p>When calling <code>EXTCODEHASH</code>, process the access event:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(address, 0, CODEHASH_LEAF_KEY)</span></span></code></pre> <p>Note that precompiles and system contracts are excluded, as their hashes are known to the client.</p> <p>When a contract is created, process these access events:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(contract_address, 0, BASIC_DATA_LEAF_KEY)</span></span> <span class="giallo-l"><span>(contract_address, 0, CODEHASH_LEAF_KEY)</span></span></code></pre><h4 id="access-events-for-storage">Access events for storage</h4> <p><code>SLOAD</code> and <code>SSTORE</code> opcodes with a given address and key process an access event of the form</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(address, tree_key, sub_key)</span></span></code></pre> <p>Where <code>tree_key</code> and <code>sub_key</code> are computed as <code>tree_key, sub_key = get_storage_slot_tree_keys(key)</code></p> <h4 id="access-events-for-code">Access events for code</h4> <p>In the conditions below, “chunk chunk_id is accessed” is understood to mean an access event of the form</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(address, (chunk_id + 128) // 256, (chunk_id + 128) % 256)</span></span></code></pre> <ul> <li>At each step of EVM execution, if and only if <code>PC &lt; len(code)</code>, chunk <code>PC // CHUNK_SIZE</code> (where <code>PC</code> is the current program counter) of the callee is accessed. In particular, note the following corner cases: <ul> <li>The destination of a <code>JUMP</code> (or positively evaluated <code>JUMPI</code>) is considered to be accessed, even if the destination is not a jumpdest or is inside pushdata</li> <li>The destination of a <code>JUMPI</code> is not considered to be accessed if the jump conditional is <code>false</code>.</li> <li>The destination of a jump is not considered to be accessed if the execution gets to the jump opcode but does not have enough gas to pay for the gas cost of executing the <code>JUMP</code> opcode (including chunk access cost if the <code>JUMP</code> is the first opcode in a not-yet-accessed chunk)</li> <li>The destination of a jump is not considered to be accessed if it is beyond the code (<code>destination &gt;= len(code)</code>)</li> <li>If code stops execution by walking past the end of the code, <code>PC = len(code)</code> is not considered to be accessed</li> </ul> </li> <li>If the current step of EVM execution is a <code>PUSH{n}</code>, all chunks <code>(PC // CHUNK_SIZE) &lt;= chunk_index &lt;= ((PC + n) // CHUNK_SIZE)</code> of the callee are accessed.</li> <li>If a nonzero-read-size <code>CODECOPY</code> or <code>EXTCODECOPY</code> read bytes <code>x...y</code> inclusive, all chunks <code>(x // CHUNK_SIZE) &lt;= chunk_index &lt;= (min(y, code_size - 1) // CHUNK_SIZE)</code> of the accessed contract are accessed. <ul> <li>Example 1: for a <code>CODECOPY</code> with start position 100, read size 50, <code>code_size = 200</code>, <code>x = 100</code> and <code>y = 149</code></li> <li>Example 2: for a <code>CODECOPY</code> with start position 600, read size 0, no chunks are accessed</li> <li>Example 3: for a <code>CODECOPY</code> with start position 1500, read size 2000, <code>code_size = 3100</code>, <code>x = 1500</code> and <code>y = 3099</code></li> </ul> </li> <li><code>CODESIZE</code>, <code>EXTCODESIZE</code> and <code>EXTCODEHASH</code> do NOT access any chunks. When a contract is created, access chunks <code>0 ... (len(code)+30)//31</code></li> </ul> <h3 id="write-events">Write Events</h3> <p>We define <strong>write events</strong> as follows. Note that when a write takes place, an access event also takes place (so the definition below should be a subset of the definition of access events). A write event is of the form <code>(address, sub_key, leaf_key)</code>, determining what data is being written to.</p> <h4 id="write-events-for-account-headers">Write events for account headers</h4> <p>When a nonzero-balance-sending <code>CALL</code>, <code>CALLCODE</code> or <code>SELFDESTRUCT</code> with a given sender and recipient takes place, process these write events:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(caller, 0, BASIC_DATA_LEAF_KEY)</span></span> <span class="giallo-l"><span>(callee, 0, BASIC_DATA_LEAF_KEY)</span></span></code></pre> <p>if no account exists at <code>callee_address</code>, also process:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(callee, 0, CODEHASH_LEAF_KEY)</span></span></code></pre> <p>When a contract creation is initialized, process these write events:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(contract_address, 0, BASIC_DATA_LEAF_KEY)</span></span> <span class="giallo-l"><span>(contract_address, 0, CODEHASH_LEAF_KEY)</span></span></code></pre><h4 id="write-events-for-storage">Write events for storage</h4> <p><code>SSTORE</code> opcodes with a given <code>address</code> and <code>key</code> process a write event of the form</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(address, tree_key, sub_key)</span></span></code></pre> <p>Where <code>tree_key</code> and <code>sub_key</code> are computed as <code>tree_key, sub_key = get_storage_slot_tree_keys(key)</code></p> <h4 id="write-events-for-code">Write events for code</h4> <p>When a contract is created, process the write events:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>(</span></span> <span class="giallo-l"><span> address</span><span>,</span></span> <span class="giallo-l"><span> (</span><span class="z-constant">CODE_OFFSET</span><span class="z-keyword"> +</span><span> i</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> VERKLE_NODE_WIDTH</span><span>,</span></span> <span class="giallo-l"><span> (</span><span class="z-constant">CODE_OFFSET</span><span class="z-keyword"> +</span><span> i</span><span>)</span><span class="z-keyword"> %</span><span class="z-constant"> VERKLE_NODE_WIDTH</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>For <code>i</code> in <code>0 ... (len(code)+30)//31</code>.</p> <p>Note: since no access list existed for code up until this EIP, note that no warm costs are charged for code accesses.</p> <h3 id="transaction">Transaction</h3> <h4 id="access-events-1">Access events</h4> <p>For a transaction, make these access events:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(tx.origin, 0, BASIC_DATA_LEAF_KEY)</span></span> <span class="giallo-l"><span>(tx.origin, 0, CODEHASH_LEAF_KEY)</span></span> <span class="giallo-l"><span>(tx.target, 0, BASIC_DATA_LEAF_KEY)</span></span> <span class="giallo-l"><span>(tx.target, 0, CODEHASH_LEAF_KEY)</span></span></code></pre><h4 id="write-events-1">Write events</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(tx.origin, 0, BASIC_DATA_LEAF_KEY)</span></span></code></pre> <p>If <code>value</code> is non-zero:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(tx.target, 0, BASIC_DATA_LEAF_KEY)</span></span></code></pre><h3 id="witness-gas-costs">Witness gas costs</h3> <p>Remove the following gas costs:</p> <ul> <li>Increased gas cost of <code>CALL</code> if it is nonzero-value-sending</li> <li><a href="https://wg-eips.ritovision.com/2200/">EIP-2200</a> <code>SSTORE</code> gas costs except for the <code>SLOAD_GAS</code></li> <li>200 per byte contract code cost</li> <li>All <code>CALLCODE</code> costs related to nonzero-value-sending</li> </ul> <p>Reduce gas cost:</p> <ul> <li><code>CREATE</code>/<code>CREATE2</code> to 1000</li> </ul> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>WITNESS_BRANCH_COST</code></td><td>1900</td></tr> <tr><td><code>WITNESS_CHUNK_COST</code></td><td>200</td></tr> <tr><td><code>SUBTREE_EDIT_COST</code></td><td>3000</td></tr> <tr><td><code>CHUNK_EDIT_COST</code></td><td>500</td></tr> <tr><td><code>CHUNK_FILL_COST</code></td><td>6200</td></tr> </tbody></table> <p>When executing a transaction, maintain four sets:</p> <ul> <li><code>accessed_subtrees: Set[Tuple[address, int]]</code></li> <li><code>accessed_leaves: Set[Tuple[address, int, int]]</code></li> <li><code>edited_subtrees: Set[Tuple[address, int]]</code></li> <li><code>edited_leaves: Set[Tuple[address, int, int]]</code></li> </ul> <p>When an <strong>access</strong> event of <code>(address, sub_key, leaf_key)</code> occurs, perform the following checks:</p> <ul> <li>Perform the following steps unless event is a <em>Transaction access event</em>;</li> <li>If <code>(address, sub_key)</code> is not in <code>accessed_subtrees</code>, charge <code>WITNESS_BRANCH_COST</code> gas and add that tuple to <code>accessed_subtrees</code>.</li> <li>If <code>leaf_key</code> is not <code>None</code> and <code>(address, sub_key, leaf_key)</code> is not in <code>accessed_leaves</code>, charge <code>WITNESS_CHUNK_COST</code> gas and add it to <code>accessed_leaves</code></li> </ul> <p>When a <strong>write</strong> event of <code>(address, sub_key, leaf_key)</code> occurs, perform the following checks:</p> <ul> <li>If event is <em>Transaction write event</em>, skip the following steps.</li> <li>If <code>(address, sub_key)</code> is not in <code>edited_subtrees</code>, charge <code>SUBTREE_EDIT_COST</code> gas and add that tuple to <code>edited_subtrees</code>.</li> <li>If <code>leaf_key</code> is not <code>None</code> and <code>(address, sub_key, leaf_key)</code> is not in <code>edited_leaves</code>, charge <code>CHUNK_EDIT_COST</code> gas and add it to <code>edited_leaves</code> <ul> <li>Additionally, if there was no value stored at <code>(address, sub_key, leaf_key)</code> (ie. the state held <code>None</code> at that position), charge <code>CHUNK_FILL_COST</code></li> </ul> </li> </ul> <p>Note that tree keys can no longer be emptied: only the values <code>0...2**256-1</code> can be written to a tree key, and 0 is distinct from <code>None</code>. Once a tree key is changed from <code>None</code> to not-<code>None</code>, it can never go back to <code>None</code>.</p> <p>Note that values should only be added to the witness if there is sufficient gas to cover their associated event costs. If there is not enough gas to cover the event costs, all the remaining gas should be consumed.</p> <p><code>CREATE*</code> and <code>*CALL</code> reserve 1/64th of the gas before the nested execution. In order to match the behavior of this charge with the pre-fork behavior of access lists:</p> <ul> <li>this minimum 1/64th gas reservation is checked <strong>AFTER</strong> charging the witness costs when performing a <code>CALL</code>, <code>CALLCODE</code>, <code>DELEGATECALL</code> or <code>STATICCALL</code></li> <li>this 1/64th of the gas is subtracted <strong>BEFORE</strong> charging the witness costs when performing a <code>CREATE</code> or <code>CREATE2</code></li> </ul> <h3 id="block-level-operations">Block-level operations</h3> <p>None of:</p> <ul> <li>Precompile accounts, system contract accounts and slots of a system contract that are accessed during a system call,</li> <li>The coinbase account</li> <li>Withdrawal accounts</li> </ul> <p>are warm at the start of a transaction.</p> <h3 id="system-contracts">System contracts</h3> <p>When (and only when) calling a system contract either</p> <ul> <li><em>via a system call</em> or</li> <li><em>to resolve a precompile/opcode</em>,</li> </ul> <p>the system contract's <em>code chunks</em> and <em>account headers</em> accesses should not appear in the witness as these should be known/cached in the clients. However any other accesses and all writes should appear in the witness.</p> <p>Also corresponding witness costs need to be charged for <em>precompile/opcode resolution</em> but are not charged in the <em>system call</em>.</p> <h3 id="account-abstraction">Account abstraction</h3> <p>TODO : still waiting on a final decision between 7702 and 3074</p> <h2 id="rationale">Rationale</h2> <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. <code>WITNESS_CHUNK_COST</code> is set to charge 6.25 gas per byte for chunks, and <code>WITNESS_BRANCH_COST</code> 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% (suggesting 10-20% gas usage increases at a 350 gas per chunk level).</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>This EIP requires a hard fork, since it modifies consensus rules.</p> <p>The main backwards-compatibility-breaking change is the gas costs for code chunk access making some applications less economically viable. It 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="security-considerations">Security Considerations</h2> <p>This EIP will mean that certain operations, mostly reading and writing several elements in the same suffix tree, become cheaper. If clients retain the same database structure as they have now, this would result in a DOS vector.</p> <p>So some adaptation of the database is required in order to make this work:</p> <ul> <li>In all possible futures, it is important to logically separate the commitment scheme from data storage. In particular, no traversal of the commitment scheme tree should be necessary to find any given state element</li> <li>In order to make accesses to the same stem cheap as required for this EIP, the best way is probably to store each stem in the same location in the database. Basically the 256 leaves of 32 bytes each would be stored in an 8kB BLOB. The overhead of reading/writing this BLOB is small because most of the cost of disk access is seeking and not the amount transferred.</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-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-30T00:00:00+00:00 2026-02-11T14:49:27+00:00 Benjamin Chodroffhttps://github.com/benjaminchodroff Jim McDonaldhttps://github.com/mcdee https://wg-eips.ritovision.com/4736/

Additional security for BLSToExecutionChange operation when a consensus layer mnemonic may be compromised, without changing consensus

<h2 id="abstract">Abstract</h2> <p>If a consensus layer mnemonic phrase is compromised, it is impossible for the consensus layer network to differentiate the legitimate holder of the key from an illegitimate holder. However, there are signals that can be considered in a wider sense without changing core Ethereum consensus. This proposal outlines ways in which on chain evidence such as the execution layer deposit address and list of signed messages could create a social consensus that would significantly favor but not guarantee legitimate mnemonic holders would win a race condition against an attacker.</p> <h2 id="motivation">Motivation</h2> <p>The consensus layer <code>BLSToExecutionChange</code> message is secure for a single user who has certainty their keys and mnemonic have not been compromised. However, as validator withdrawals on the consensus layer are not possible until the Capella hard fork, no user can have absolute certainty that their keys are not compromised until the <code>BLSToExecutionChange</code> is on chain, and by then too late to change. All legitimate mnemonic phrase holders were originally in control of the execution layer deposit address. Beacon node clients and node operators may optionally load a list of verifiable <code>BLSToExecutionChange</code> messages to broadcasts that may create a social consensus for legitimate holders to successfully win a race condition against an attacker. If attackers compromise a significant number of consensus layer nodes, it would pose risks to the entire Ethereum community.</p> <p>Setting a withdrawal address to an execution layer address was not supported by the eth2.0-deposit-cli until v1.1.1 on March 23, 2021, leaving early adopters wishing they could force set their execution layer address to a deposit address earlier. Forcing this change is not something that can be enforced in-protocol, partly due to lack of information on the beacon chain about the execution layer deposit address and partly due to the fact that this was never listed as a requirement. It is also possible that the execution layer deposit address is no longer under the control of the legitimate holder of the withdrawal private key.</p> <p>However, it is possible for individual nodes to locally restrict the changes they wish to include in blocks they propose, and which they propagate around the network, in a way that does not change consensus. It is also possible for client nodes to help broadcast signed <code>BLSToExecutionChange</code> requests to ensure as many nodes witness this message as soon as possible in a fair manner. Further, such <code>BLSToExecutionChange</code> signed messages can be preloaded into clients in advance to further help nodes filter attacking requests.</p> <p>This proposal provides purely optional additional protection. It aims to request nodes set a priority on withdrawal credential claims that favour a verifiable execution layer deposit address in the event of two conflicting <code>BLSToExecutionChange</code> messages. It also establishes a list of <code>BLSToExecutionChange</code> signed messages to help broadcast "as soon as possible" when the network supports it, and encourage client teams to help use these lists to honour filter and prioritize accepting requests by REST and transmitting them via P2P. This will not change consensus, but may help prevent propagating an attack where a withdrawal key has been knowingly or unknowingly compromised.</p> <p>It is critical to understand that this proposal is not a consensus change. Nothing in this proposal restricts the validity of withdrawal credential operations within the protocol. It is a voluntary change by client teams to build this functionality in to their beacon nodes, and a voluntary change by node operators to accept any or all of the restrictions and broadcasting capabilities suggested by end users.</p> <p>Because of the above, even if fully implemented, it will be down to chance as to which validators propose blocks, and which voluntary restrictions those validators’ beacon nodes are running. Node operators can do what they will to help the community prevent attacks on any compromised consensus layer keys, but there are no guarantees of success this will prevent a successful attack.</p> <h2 id="specification">Specification</h2> <p>The Consensus Layer <code>BLSToExecutionChange</code> operation has the following fields:</p> <ul> <li>Validator index</li> <li>Current withdrawal BLS public key</li> <li>Proposed execution layer withdrawal address</li> <li>Signature by withdrawal private key over the prior fields</li> </ul> <p>This proposal describes OPTIONAL and RECOMMENDED mechanisms which a client beacon node MAY implement, and end users are RECOMMENDED to use in their beacon node operation.</p> <h3 id="blstoexecutionchange-broadcast-file"><code>BLSToExecutionChange</code> Broadcast File</h3> <p>Beacon node clients MAY support an OPTIONAL file of lines specifying "validator index" , "current withdrawal BLS public key" , "proposed execution layer withdrawal address", and "signature" which, if implemented and if provided, SHALL instruct nodes to automatically submit a one-time <code>BLSToExecutionChange</code> broadcast message for each valid signature at the Capella hard fork. This file SHALL give all node operators an OPTIONAL opportunity to ensure any valid <code>BLSToExecutionChange</code> messages are broadcast, heard, and shared by nodes at the Capella hard fork. This OPTIONAL file SHALL also instruct nodes to perpetually prefer accepting and repeating signatures matching the signature in the file, and SHALL reject accepting or rebroadcasting messages which do not match a signature for a given withdrawal credential.</p> <h3 id="blstoexecutionchange-handling"><code>BLSToExecutionChange</code> Handling</h3> <p>Beacon node clients are RECOMMENDED to allow accepting "<code>BLSToExecutionChange</code> Broadcast" file of verifiable signatures, and then MAY fallback to accept a "first request" via P2P. All of this proposal is OPTIONAL for beacon nodes to implement or use, but all client teams are RECOMMENDED to allow a "<code>BLSToExecutionChange</code> Broadcast File" to be loaded locally before the Capella hard fork. This OPTIONAL protection will allow a user to attempt to set a withdrawal address message as soon as the network supports it without any change to consensus.</p> <h2 id="rationale">Rationale</h2> <p>This proposal is intended to protect legitimate validator mnemonic holders where it was knowingly or unknowingly compromised. As there is no safe way to transfer ownership of a validator without exiting, it can safely be assumed that all validator holders intend to set to a withdrawal address they specify. Using the deposit address in the execution layer to determine the legitimate holder is not possible to consider in consensus as it may be far back in history and place an overwhelming burden to maintain such a list. As such, this proposal outlines optional mechanism which protect legitimate original mnemonic holders and does so in a way that does not place any mandatory burden on client node software or operators.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As there is no existing <code>BLSToExecutionChange</code> operation prior to Capella, there is no documented backwards compatibility. As all of the proposal is OPTIONAL in both implementation and operation, it is expected that client beacon nodes that do not implement this functionality would still remain fully backwards compatible with any or all clients that do implement part or all of the functionality described in this proposal. Additionally, while users are RECOMMENDED to enable these OPTIONAL features, if they decide to either disable or ignore some or all of the features, or even purposefully load content contrary to the intended purpose, the beacon node client will continue to execute fully compatible with the rest of the network as none of the proposal will change core Ethereum consensus.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="blstoexecutionchange-broadcast-file-1"><code>BLSToExecutionChange</code> Broadcast File</h3> <p>A "change-operations.json" file intended to be preloaded with all consensus layer withdrawal credential signatures and verifiable execution layer deposit addresses. This file may be generated by a script and able to be independently verified by community members using the consensus layer node, and intended to be included by all clients, enabled by default. Client nodes are encouraged to enable packaging this independently verifiable list with the client software, and enable it by default to help further protect the community from unsuspected attacks.</p> <p>The change-operations.json format is the "<code>BLSToExecutionChange</code> File - Claim" combined into a single JSON array.</p> <h3 id="blstoexecutionchange-broadcast-file-claim"><code>BLSToExecutionChange</code> Broadcast File - Claim</h3> <p>A community collected and independently verifiable list of "<code>BLSToExecutionChange</code> Broadcasts" containing verifiable claims will be collected. Node operators may verify these claims independently and are suggested to load claims in compatible beacon node clients.</p> <p>To make a verifiable claim, users MAY upload a claim to any public repository in a text file "[chain]/validatorIndex.json" such as "mainnet/123456.json".</p> <p>123456.json:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[{&quot;message&quot;:{&quot;validator_index&quot;:&quot;123456&quot;,&quot;from_bls_pubkey&quot;:&quot;0x977cc21a067003e848eb3924bcf41bd0e820fbbce026a0ff8e9c3b6b92f1fea968ca2e73b55b3908507b4df89eae6bfb&quot;,&quot;to_execution_address&quot;:&quot;0x08f2e9Ce74d5e787428d261E01b437dC579a5164&quot;},&quot;signature&quot;:&quot;0x872935e0724b31b2f0209ac408b673e6fe2f35b640971eb2e3b429a8d46be007c005431ef46e9eb11a3937f920cafe610c797820ca088543c6baa0b33797f0a38f6db3ac68ffc4fd03290e35ffa085f0bfd56b571d7b2f13c03f7b6ce141c283&quot;}]</span></span></code></pre><h4 id="claim-acceptance">Claim Acceptance</h4> <p>In order for a submission to be merged into public repository, the submission must have:</p> <ol> <li>Valid filename in the format validatorIndex.json</li> <li>Valid validator index which is active on the consensus layer</li> <li>Verifiable signature</li> <li>A single change operation for a single validator, with all required fields in the file with no other content present</li> </ol> <p>All merge requests that fail will be provided a reason from above which must be addressed prior to merge. Any future verifiable amendments to accepted claims must be proposed by the same submitter, or it will be treated as a contention.</p> <h4 id="blstoexecutionchange-broadcast"><code>BLSToExecutionChange</code> Broadcast</h4> <p>Anyone in the community will be able to independently verify the files from the claims provided using the Capella spec and command line clients such as "ethdo" which support the specification.</p> <p>A claim will be considered contested if a claim arrives where the verifiable consensus layer signatures differ between two or more submissions, where neither party has proven ownership of the execution layer deposit address. If a contested but verified "<code>BLSToExecutionChange</code> Broadcast" request arrives to a repository, all parties can be notified, and may try to convince the wider community by providing any publicly verifiable on chain evidence or off chain evidence supporting their claim to then include their claim in nodes. Node operators may decide which verifiable claims they wish to include based on social consensus.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="1-attacker-lacks-el-deposit-key-uncontested-claim">1: Attacker lacks EL deposit key, uncontested claim</h3> <ul> <li>User A: Controls the CL keys and the EL key used for the deposit</li> <li>User B: Controls the CL keys, but does not control the EL key for the deposit</li> </ul> <p>User A signs and submits a claim to the CLWP repository, clients load User A message into the "<code>BLSToExecutionChange</code> Broadcast" file. At the time of the first epoch support <code>BLSToExecutionChange</code>, many (not all) nodes begin to broadcast the message. User B also tries to submit a different but valid <code>BLSToExecutionChange</code> to an address that does not match the signature in the claim. This message is successfully received via REST API, but some (not all) nodes begin to silently drop this message as the signature does not match the signature in the "<code>BLSToExecutionChange</code> Broadcast" file. As such, these nodes do not replicate this message via P2P.</p> <h3 id="2-attacker-has-both-el-deposit-key-and-cl-keys-uncontested-claim">2: Attacker has both EL deposit key and CL keys, uncontested claim</h3> <ul> <li>User A: Controls the CL key/mnemonic and the EL key used for the deposit, and submits a claim to move to a new address</li> <li>User B: Controls the CL and EL key/mnemonic used for the EL deposit, but fails to submit a claim</li> </ul> <p>It is possible/likely that User A would notice that all their funds in the EL deposit address had been stolen. This may signal that their CL key is compromised as well, so they decide to pick a new address for the withdrawal. The story will play out the same as Scenario 1 as the claim is uncontested.</p> <h3 id="3-same-as-2-but-the-attacker-submits-a-contested-claim">3: Same as #2, but the attacker submits a contested claim</h3> <ul> <li>User A: Controls the CL keys/mnemonic and the EL key used for the deposit, and submits a claim to move to a new address</li> <li>User B: Controls the CL keys/mnemonic and the EL key used for the deposit, and submits a claim to move to a new address</li> </ul> <p>This is a contested claim and as such there is no way to prove who is in control using on chain data. Instead, either user may try to persuade the community they are the rightful owner (identity verification, social media, etc.) in an attempt to get node operators to load their contested claim into their "<code>BLSToExecutionChange</code> Broadcast" file. However, there is no way to fully prove it.</p> <h3 id="4-a-user-has-lost-either-their-cl-key-and-or-mnemonic-no-withdrawal-key">4: A user has lost either their CL key and/or mnemonic (no withdrawal key)</h3> <ul> <li>User A: Lacks the CL keys and mnemonic</li> </ul> <p>There is no way to recover this scenario with this proposal as we cannot prove a user has lost their keys, and the mnemonic is required to generate the withdrawal key.</p> <h3 id="5-end-game-attacker">5: End game - attacker</h3> <ul> <li>User A: Controls EL and CL key/mnemonic, successfully achieves a set address withdrawal</li> <li>User B: Controls CL key, decides to attack</li> </ul> <p>Upon noticing User A has submitted a successful set address withdrawal, User B may run a validator and attempt to get User A slashed. Users who suspect their validator key or seed phrase is compromised should take action to exit their validator as early as possible.</p> <h3 id="6-compromised-key-but-not-vulnerable-to-withdrawal">6: Compromised key, but not vulnerable to withdrawal</h3> <ul> <li>User A: Controls EL and CL key/mnemonic, but has a vulnerability which leaks their CL key but NOT their CL mnemonic</li> <li>User B: Controls the CL key, but lacks the CL mnemonic</li> </ul> <p>User A may generate the withdrawal key (requires the mnemonic). User B can attack User A by getting them slashed, but will be unable to generate the withdrawal key.</p> <h3 id="7-attacker-loads-a-malicious-blstoexecutionchange-broadcast-file-into-one-or-multiple-nodes-user-a-submits-claim">7: Attacker loads a malicious <code>BLSToExecutionChange</code> Broadcast file into one or multiple nodes, User A submits claim</h3> <ul> <li>User A: Submits a valid uncontested claim which is broadcast out as soon as possible by many nodes</li> <li>User B: Submits no claim, but broadcasts a valid malicious claim out through their <code>BLSToExecutionChange</code> Broadcast list, and blocks User A's claim from their node.</li> </ul> <p>User B's claim will make it into many nodes, but when it hits nodes that have adopted User A's signature they will be dropped and not rebroadcast. Statistically, User B will have a harder time achieving consensus among the entire community, but it will be down to chance.</p> <h3 id="8-same-as-7-but-user-a-submits-no-claim">8: Same as #7, but User A submits no claim</h3> <p>The attacker will statistically likely win as they will be first to have their message broadcast to many nodes and, unless User A submits a request exactly at the time of support, it is unlikely to be heard by enough nodes to gain consensus. All users are encouraged to submit claims for this reason because nobody can be certain their mnemonic has not been compromised until it is too late.</p> <h3 id="second-order-effects">Second Order Effects</h3> <ol> <li>A user who participates in the "<code>BLSToExecutionChange</code> Broadcast" may cause the attacker to give up early and instead start to slash. For some users, the thought of getting slashed is preferable to giving an adversary any funds. As the proposal is voluntary, users may choose not to participate if they fear this scenario.</li> <li>The attacker may set up their own <code>BLSToExecutionChange</code> Broadcast to reject signatures not matching their attack. This is possible with or without this proposal.</li> <li>The attacker may be the one collecting "<code>BLSToExecutionChange</code> Broadcast" claims for this proposal and may purposefully reject legitimate requests. Anyone is free to set up their own community claim collection and gather their own community support using the same mechanisms described in this proposal to form an alternative social consensus.</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-01-28T00:00:00+00:00 2026-02-11T14:48:26+00:00 Jarno Marttilahttps://github.com/yaruno Martin Moravekhttps://github.com/mmartinmo https://wg-eips.ritovision.com/5023/

An interface for creating value-holding tokens shareable by multiple owners

<h2 id="abstract">Abstract</h2> <p>This EIP standardizes an interface for non-fungible value-holding shareable tokens. Shareability is accomplished by minting copies of existing tokens for new recipients. Sharing and associated events allow the construction of a graph describing who has shared what to which party.</p> <h2 id="motivation">Motivation</h2> <p>NFT 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> have been developed to standardize scarce digital resources. However, many non-fungible digital resources need not be scarce.</p> <p>We have attempted to capture positive externalities in ecosystems with new types of incentive mechanisms that exhibit anti-rival logic, serve as an unit of accounting and function as medium of sharing. We envision that shareable tokens can work both as incentives but also as representations of items that are typically digital in their nature and gain more value as they are shared.</p> <p>These requirements have set us to define shareable NFTs and more specifically a variation of shareable NFTs called non-transferable shareable NFTs. These shareable NFTs can be “shared” in the same way digital goods can be shared, at an almost zero technical transaction cost. We have utilized them to capture anti-rival value in terms of accounting positive externalities in an economic system.</p> <p>Typical NFT standards such as EIP-721 and EIP-1155 do not define a sharing modality. Instead ERC standards define interfaces for typical rival use cases such as token minting and token transactions that the NFT contract implementations should fulfil. The ‘standard contract implementations' may extend the functionalities of these standards beyond the definition of interfaces. The shareable tokens that we have designed and developed in our experiments are designed to be token standard compatible at the interface level. However the implementation of token contracts may contain extended functionalities to match the requirements of the experiments such as the requirement of 'shareability'. In reflection to standard token definitions, shareability of a token could be thought of as re-mintability of an existing token to another party while retaining the original version of it.</p> <p>Sharing is an interesting concept as it can be thought and perceived in different ways. For example, when we talk about sharing we can think about it is as digital copying, giving a copy of a digital resource while retaining a version by ourselves. Sharing can also be fractional or sharing could be about giving rights to use a certain resource. The concept of shareability and the context of shareability can take different forms and one might use different types of implementatins for instances of shareable tokens. Hence we haven't restricted that the interface should require any specific token type.</p> <p>Shareable tokens can be made non-transferable at the contract implementation level. Doing so, makes them shareable non-transferable tokens. In the reference implementation we have distilled a general case from our use cases that defines a shareable non-transferable NFTs using the shareable NFT interface.</p> <p>We believe that the wider audience should benefit from an abstraction level higher definition for shareability, such as this interface implementation, that defines minimum amount of functions that would be implemented to satisfy the concept of shareability.</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-comment">///</span><span class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0xded6338b</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5023</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-storage z-type"> @dev</span><span class="z-comment"> This emits when a token is shared, reminted and given to another wallet that isn&#39;t function caller</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Share</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"> tokenId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> derivedFromtokenId</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"> Shares, remints an existing token, gives a newly minted token a fresh token id, keeps original token at function callers possession and transfers newly minted token to receiver which should be another address than function caller. </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> share</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"> tokenIdToBeShared</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"> newTokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span><span> </span></span></code></pre> <p>The Share event is expected to be emitted when function method share is successfully called and a new token on basis of a given token id is minted and transferred to a recipient.</p> <h2 id="rationale">Rationale</h2> <p>Current NFT standards define transferable non-fungible tokens, but not shareable non-fungible tokens. To be able to create shareable NFTs we see that existing NFT contracts could be extended with an interface which defines the basic principles of sharing, namely the Event of sharing and the function method of sharing. Definition of how transferability of tokens should be handled is left to the contract implementor. In case transferring is left enable shareable tokens behave similarly to the existing tokens, except when they are shared, a version of token is retained. In case transfering is disabled, shareable tokens become shareable non-transferable tokens, where they can be minted and given or shared to other people, but they cannot be transferred away.</p> <p>Imagine that Bob works together with Alice on a project. Bob earns an unique NFT indicating that he has made effort to the project, but Bob feels that his accomplishments are not only out of his own accord. Bob wants to share his token with Alice to indicate that also Alice deserves recognition of having put effort on their project. Bob initiates token sharing by calling <code>Share</code> method on the contract which has his token and indicates which one of his tokens he wishes to share and to whom by passing address and token id parameters. A new token is minted for Alice and a <code>Share</code> event is initiated to communicate that it was Bob whom shared his token to Alice by logging addresses who shared a token id to whose address and which token id was this new token derived from.</p> <p>Over time, a tree-like structures can be formed from the Share event information. If Bob shared to Alice, and Alice shared further to Charlie and Alice also shared to David a rudimentary tree structure forms out from sharing activity. This share event data can be later on utilized to gain more information of share activities that the tokens represent.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>B -&gt; A -&gt; C </span></span> <span class="giallo-l"><span> \</span></span> <span class="giallo-l"><span> &gt; D</span></span></code></pre> <p>These tree structures can be further aggregated and collapsed to network representations e.g. social graphs on basis of whom has shared to whom over a span of time. E.g. if Bob shared a token to Alice, and Alice has shared a different token to Charlie and Bob has shared a token to Charlie, connections form between all these parties through sharing activities.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> B----A----C </span></span> <span class="giallo-l"><span> \_______/</span></span></code></pre><h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is backwards compatible with EIP-721 and EIP-1155.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Following reference implementation demonstrates a general use case of one of our pilots. In this case a shareable non-transferable token represents a contribution done to a community that the contract owner has decided to merit with a token. Contract owner can mint a merit token and give it to a person. This token can be further shared by the receiver to other parties for example to share the received merit to others that have participated or influenced his contribution.</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-keyword">import</span><span class="z-string"> &quot;./IERC5023.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/IERC721.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 class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/Address.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/Context.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/Strings.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/ERC165.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/extensions/IERC721Metadata.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/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-storage z-type">contract</span><span class="z-entity z-name"> ShareableERC721</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 class="z-entity z-name">IERC5023</span><span> /* </span><span class="z-entity z-name">EIP165</span><span> */ </span><span>{</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> string</span><span> baseURI</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"> internal</span><span> _currentIndex</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">string</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _name</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"> _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"> mint</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"> tokenId</span></span> <span class="giallo-l"><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-entity z-name"> _mint</span><span>(</span><span>account</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"> setTokenURI</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenId</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"> tokenURI</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-entity z-name"> _setTokenURI</span><span>(</span><span>tokenId</span><span>,</span><span> tokenURI</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"> setBaseURI</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 class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span> baseURI </span><span class="z-keyword">=</span><span> baseURI_</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"> _baseURI</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> view</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> baseURI</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"> share</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"> tokenIdToBeShared</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"> newTokenId</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>to </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;ERC721: mint to the zero address&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>tokenIdToBeShared</span><span>)</span><span>,</span><span class="z-string"> &quot;ShareableERC721: token to be shared must exist&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><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>tokenIdToBeShared</span><span>)</span><span>,</span><span class="z-string"> &quot;Method caller must be the owner of token&quot;</span><span>)</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"> memory</span><span> _tokenURI </span><span class="z-keyword">=</span><span class="z-entity z-name"> tokenURI</span><span>(</span><span>tokenIdToBeShared</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> _currentIndex</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setTokenURI</span><span>(</span><span>_currentIndex</span><span>,</span><span> _tokenURI</span><span>)</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"> Share</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> to</span><span>,</span><span> _currentIndex</span><span>,</span><span> tokenIdToBeShared</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _currentIndex</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"> 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"> tokenId</span></span> <span class="giallo-l"><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"> revert</span><span>(</span><span class="z-string">&#39;In this reference implementation tokens are not transferrable&#39;</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"> safeTransferFrom</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"> 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"> revert</span><span>(</span><span class="z-string">&#39;In this reference implementation tokens are not transferrable&#39;</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>Reference implementation should not be used as is in production. There are no other security considerations related directly to 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-01-19T00:00:00+00:00 2026-02-11T14:48:25+00:00 Chirohttps://github.com/chiro-hiro Victor Dusarthttps://github.com/vdusart https://wg-eips.ritovision.com/6366/

A token that holds the permission of an address in an ecosystem

<h2 id="abstract">Abstract</h2> <p>This EIP offers an alternative to Access Control Lists (ACLs) for granting authorization and enhancing security. A <code>uint256</code> is used to store permission of given address in a ecosystem. Each permission is represented by a single bit in a <code>uint256</code> as described in <a href="https://wg-eips.ritovision.com/6617/">ERC-6617</a>. Bitwise operators and bitmasks are used to determine the access right which is much more efficient and flexible than <code>string</code> or <code>keccak256</code> comparison.</p> <h2 id="motivation">Motivation</h2> <p>Special roles like <code>Owner</code>, <code>Operator</code>, <code>Manager</code>, <code>Validator</code> are common for many smart contracts because permissioned addresses are used to administer and manage them. It is difficult to audit and maintain these system since these permissions are not managed in a single smart contract.</p> <p>Since permissions and roles are reflected by the permission token balance of the relevant account in the given ecosystem, cross-interactivity between many ecosystems will be made simpler.</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><em>Note</em> The following specifications use syntax from Solidity <code>0.8.7</code> (or above)</p> <h3 id="core-interface">Core Interface</h3> <p>Compliant contracts MUST implement <code>IEIP6366Core</code>.</p> <p>It is RECOMMENDED to define each permission as a power of <code>2</code> so that we can check for the relationship between sets of permissions using <a href="https://wg-eips.ritovision.com/6617/">ERC-6617</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"> IEIP6366Core</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * MUST trigger when `_permission` are transferred, including `zero` permission transfers.</span></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"> Permission 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"> _to</span><span class="z-comment"> Permission 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"> _permission</span><span class="z-comment"> Transferred subset permission of permission owner</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"> _permission</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 `approve(address _delegatee, uint256 _permission)`.</span></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"> Permission 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"> _delegatee</span><span class="z-comment"> Delegatee</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _permission</span><span class="z-comment"> Approved subset permission of permission owner</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"> _delegatee</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _permission</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"> * Transfers a subset `_permission` of permission to address `_to`.</span></span> <span class="giallo-l"><span class="z-comment"> * The function SHOULD revert if the message caller’s account permission does not have the subset</span></span> <span class="giallo-l"><span class="z-comment"> * of the transferring permissions. The function SHOULD revert if any of transferring permissions are</span></span> <span class="giallo-l"><span class="z-comment"> * existing on target `_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"> _to</span><span class="z-comment"> Permission 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"> _permission</span><span class="z-comment"> Subset permission of permission 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"> 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"> _permission</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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * Allows `_delegatee` to act for the permission owner&#39;s behalf, up to the `_permission`.</span></span> <span class="giallo-l"><span class="z-comment"> * If this function is called again it overwrites the current granted with `_permission`.</span></span> <span class="giallo-l"><span class="z-comment"> * `approve()` method SHOULD `revert` if granting `_permission` permission is not</span></span> <span class="giallo-l"><span class="z-comment"> * a subset of all available permissions of permission 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"> _delegatee</span><span class="z-comment"> Delegatee</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _permission</span><span class="z-comment"> Subset permission of permission 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"> approve</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _delegatee</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _permission</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> <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 permissions of the given `_owner` 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"> permissionOf</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-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> permission</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"> * Returns `true` if `_required` is a subset of `_permission` otherwise 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"> _permission</span><span class="z-comment"> Checking permission 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"> _required</span><span class="z-comment"> Required set of permission</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"> permissionRequire</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _permission</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _required</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"> isPermissioned</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"> * Returns `true` if `_required` permission is a subset of `_actor`&#39;s permissions or a subset of his delegated</span></span> <span class="giallo-l"><span class="z-comment"> * permission granted by 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"> Permission 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"> _actor</span><span class="z-comment"> Actor who acts on behalf of 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"> _required</span><span class="z-comment"> Required set of permission</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"> hasPermission</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"> _actor</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _required</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"> isPermissioned</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"> * Returns the subset permission of the `_owner` address were granted to `_delegatee` 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"> Permission 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"> _delegatee</span><span class="z-comment"> Delegatee</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"> delegated</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"> _delegatee</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"> permission</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="metadata-interface">Metadata Interface</h3> <p>It is RECOMMENDED for compliant contracts to implement the optional extension <code>IEIP6617Meta</code>.</p> <p>SHOULD define a description for the base permissions and main combinaison.</p> <p>SHOULD NOT define a description for every subcombinaison of permissions possible.</p> <h3 id="error-interface">Error Interface</h3> <p>Compatible tokens MAY implement <code>IEIP6366Error</code> as defined 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"> IEIP6366Error</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * The owner or actor does not have the required permission</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"> AccessDenied</span><span>(</span><span class="z-support">address</span><span> _owner</span><span>,</span><span class="z-support"> address</span><span> _actor</span><span>,</span><span class="z-support"> uint256</span><span> _permission</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"> * Conflict between permission set</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"> DuplicatedPermission</span><span>(</span><span class="z-support">uint256</span><span> _permission</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"> * Data out of range</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"> OutOfRange</span><span>(</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="reference-implementation">Reference Implementation</h2> <p>First implementation could be found here:</p> <ul> <li><a href="https://wg-eips.ritovision.com/6366/./assets/contracts/EIP6366Core.sol">ERC-6366 Core implementation</a></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>Need more 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-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-22T00:00:00+00:00 2026-02-11T14:48:25+00:00 Joey Santorohttps://github.com/joeysantoro t11shttps://github.com/transmissions11 Jet Jadejahttps://github.com/JetJadeja Alberto Cuesta Cañadahttps://github.com/alcueca Señor Doggohttps://github.com/fubuloubu https://wg-eips.ritovision.com/4626/

Tokenized Vaults with a single underlying EIP-20 token.

<h2 id="abstract">Abstract</h2> <p>The following standard allows for the implementation of a standard API for tokenized Vaults representing shares of a single underlying <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> token. This standard is an extension on the EIP-20 token that provides basic functionality for depositing and withdrawing tokens and reading balances.</p> <h2 id="motivation">Motivation</h2> <p>Tokenized Vaults have a lack of standardization leading to diverse implementation details. Some various examples include lending markets, aggregators, and intrinsically interest bearing tokens. This makes integration difficult at the aggregator or plugin layer for protocols which need to conform to many standards, and forces each protocol to implement their own adapters which are error prone and waste development resources.</p> <p>A standard for tokenized Vaults will lower the integration effort for yield-bearing vaults, while creating more consistent and robust implementation patterns.</p> <h2 id="specification">Specification</h2> <p>All <a href="https://wg-eips.ritovision.com/4626/">EIP-4626</a> tokenized Vaults MUST implement EIP-20 to represent shares. If a Vault is to be non-transferrable, it MAY revert on calls to <code>transfer</code> or <code>transferFrom</code>. The EIP-20 operations <code>balanceOf</code>, <code>transfer</code>, <code>totalSupply</code>, etc. operate on the Vault "shares" which represent a claim to ownership on a fraction of the Vault's underlying holdings.</p> <p>All EIP-4626 tokenized Vaults MUST implement EIP-20'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.</p> <p>EIP-4626 tokenized Vaults MAY implement <a href="https://wg-eips.ritovision.com/2612/">EIP-2612</a> to improve the UX of approving shares on various integrations.</p> <h3 id="definitions">Definitions:</h3> <ul> <li>asset: The underlying token managed by the Vault. Has units defined by the corresponding EIP-20 contract.</li> <li>share: The token of the Vault. Has a ratio of underlying assets exchanged on mint/deposit/withdraw/redeem (as defined by the Vault).</li> <li>fee: An amount of assets or shares charged to the user by the Vault. Fees can exists for deposits, yield, AUM, withdrawals, or anything else prescribed by the Vault.</li> <li>slippage: Any difference between advertised share price and economic realities of deposit to or withdrawal from the Vault, which is not accounted by fees.</li> </ul> <h3 id="methods">Methods</h3> <h4 id="asset">asset</h4> <p>The address of the underlying token used for the Vault for accounting, depositing, and withdrawing.</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"> a</span><span class="z-string">sset</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"> a</span><span class="z-string">ssetTokenAddress</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="totalassets">totalAssets</h4> <p>Total amount of the underlying asset that is "managed" by Vault.</p> <p>SHOULD include any compounding that occurs from yield.</p> <p>MUST be inclusive of any fees that are charged against assets in the Vault.</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"> t</span><span class="z-string">otalAssets</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">otalManagedAssets</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="converttoshares">convertToShares</h4> <p>The amount of shares that the Vault would exchange for the amount of assets provided, in an ideal scenario where all the conditions are met.</p> <p>MUST NOT be inclusive of any fees that are charged against assets in the Vault.</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-share, and instead should reflect the "average-user's" price-per-share, 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">onvertToShares</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"> 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 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="converttoassets">convertToAssets</h4> <p>The amount of assets that the Vault would exchange for the amount of shares provided, in an ideal scenario where all the conditions are met.</p> <p>MUST NOT be inclusive of any fees that are charged against assets in the Vault.</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-share, and instead should reflect the "average-user's" price-per-share, 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">onvertToAssets</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"> 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 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="maxdeposit">maxDeposit</h4> <p>Maximum amount of the underlying asset that can be deposited into the Vault for the <code>receiver</code>, through a <code>deposit</code> call.</p> <p>MUST return the maximum amount of assets <code>deposit</code> would allow to be deposited for <code>receiver</code> and not cause a revert, which MUST NOT be higher than the actual maximum that would be accepted (it should underestimate if necessary). This assumes that the user has infinite assets, i.e. MUST NOT rely on <code>balanceOf</code> of <code>asset</code>.</p> <p>MUST factor in both global and user-specific limits, like if deposits are entirely disabled (even temporarily) it MUST return 0.</p> <p>MUST return <code>2 ** 256 - 1</code> if there is no limit on the maximum amount of assets that may be deposited.</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">axDeposit</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"> 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 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">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></code></pre><h4 id="previewdeposit">previewDeposit</h4> <p>Allows an on-chain or off-chain user to simulate the effects of their deposit at the current block, given current on-chain conditions.</p> <p>MUST return as close to and no more than the exact amount of Vault shares that would be minted in a <code>deposit</code> call in the same transaction. I.e. <code>deposit</code> should return the same or more <code>shares</code> as <code>previewDeposit</code> if called in the same transaction.</p> <p>MUST NOT account for deposit limits like those returned from maxDeposit and should always act as though the deposit would be accepted, regardless if the user has enough tokens approved, etc.</p> <p>MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.</p> <p>MUST NOT revert due to vault specific user/global limits. MAY revert due to other conditions that would also cause <code>deposit</code> to revert.</p> <p>Note that any unfavorable discrepancy between <code>convertToShares</code> and <code>previewDeposit</code> SHOULD be considered slippage in share price or some other type of condition, meaning the depositor will lose assets by depositing.</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">reviewDeposit</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"> 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 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="deposit">deposit</h4> <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 EIP-20 <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).</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 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="maxmint">maxMint</h4> <p>Maximum amount of shares that can be minted from the Vault for the <code>receiver</code>, through a <code>mint</code> call.</p> <p>MUST return the maximum amount of shares <code>mint</code> would allow to be deposited to <code>receiver</code> and not cause a revert, which MUST NOT be higher than the actual maximum that would be accepted (it should underestimate if necessary). This assumes that the user has infinite assets, i.e. MUST NOT rely on <code>balanceOf</code> of <code>asset</code>.</p> <p>MUST factor in both global and user-specific limits, like if mints are entirely disabled (even temporarily) it MUST return 0.</p> <p>MUST return <code>2 ** 256 - 1</code> if there is no limit on the maximum amount of shares that may be minted.</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">axMint</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"> 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 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">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></code></pre><h4 id="previewmint">previewMint</h4> <p>Allows an on-chain or off-chain user to simulate the effects of their mint at the current block, given current on-chain conditions.</p> <p>MUST return as close to and no fewer than the exact amount of assets that would be deposited in a <code>mint</code> call in the same transaction. I.e. <code>mint</code> should return the same or fewer <code>assets</code> as <code>previewMint</code> if called in the same transaction.</p> <p>MUST NOT account for mint limits like those returned from maxMint and should always act as though the mint would be accepted, regardless if the user has enough tokens approved, etc.</p> <p>MUST be inclusive of deposit fees. Integrators should be aware of the existence of deposit fees.</p> <p>MUST NOT revert due to vault specific user/global limits. MAY revert due to other conditions that would also cause <code>mint</code> to revert.</p> <p>Note that any unfavorable discrepancy between <code>convertToAssets</code> and <code>previewMint</code> SHOULD be considered slippage in share price or some other type of condition, meaning the depositor will lose assets by minting.</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">reviewMint</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"> 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 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="mint">mint</h4> <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 EIP-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).</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 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="maxwithdraw">maxWithdraw</h4> <p>Maximum amount of the underlying asset that can be withdrawn from the <code>owner</code> balance in the Vault, through a <code>withdraw</code> call.</p> <p>MUST return the maximum amount of assets that could be transferred from <code>owner</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"> 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 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">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></code></pre><h4 id="previewwithdraw">previewWithdraw</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 Vault shares 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>shares</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 shares, 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 vault 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>convertToShares</code> and <code>previewWithdraw</code> SHOULD be considered slippage in share price or some other type of condition, meaning the depositor will lose assets by depositing.</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"> 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 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="withdraw">withdraw</h4> <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>.</p> <p>MUST support a withdraw flow where the shares are burned from <code>owner</code> directly where <code>msg.sender</code> has EIP-20 approval over the shares of <code>owner</code>.</p> <p>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>SHOULD check <code>msg.sender</code> can spend owner funds, assets needs to be converted to shares and shares should be checked for allowance.</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).</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 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="maxredeem">maxRedeem</h4> <p>Maximum amount of Vault shares that can be redeemed from the <code>owner</code> balance in the Vault, through a <code>redeem</code> call.</p> <p>MUST return the maximum amount of shares that could be transferred from <code>owner</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"> 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 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">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></code></pre><h4 id="previewredeem">previewRedeem</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 assets that would be withdrawn in a <code>redeem</code> call in the same transaction. I.e. <code>redeem</code> should return the same or more <code>assets</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 shares, 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 vault 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>convertToAssets</code> and <code>previewRedeem</code> SHOULD be considered slippage in share price or some other type of condition, meaning the depositor will lose assets by 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"> 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"> 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 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="redeem">redeem</h4> <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>.</p> <p>MUST support a redeem flow where the shares are burned from <code>owner</code> directly where <code>msg.sender</code> has EIP-20 approval over the shares of <code>owner</code>.</p> <p>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>SHOULD check <code>msg.sender</code> can spend owner funds using allowance.</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).</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 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><h3 id="events">Events</h3> <h4 id="deposit-1">Deposit</h4> <p><code>sender</code> has exchanged <code>assets</code> for <code>shares</code>, and transferred those <code>shares</code> to <code>owner</code>.</p> <p>MUST be emitted when tokens are deposited into the Vault via the <code>mint</code> and <code>deposit</code> methods.</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"> 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"> s</span><span class="z-string">ender</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"> o</span><span class="z-string">wner</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">ssets</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"> s</span><span class="z-string">hares</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><h4 id="withdraw-1">Withdraw</h4> <p><code>sender</code> has exchanged <code>shares</code>, owned by <code>owner</code>, for <code>assets</code>, and transferred those <code>assets</code> to <code>receiver</code>.</p> <p>MUST be emitted when shares are withdrawn from the Vault in <code>EIP-4626.redeem</code> or <code>EIP-4626.withdraw</code> methods.</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"> 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"> s</span><span class="z-string">ender</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"> r</span><span class="z-string">eceiver</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"> o</span><span class="z-string">wner</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">ssets</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"> s</span><span class="z-string">hares</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 Vault interface is designed to be optimized for integrators with a feature complete yet minimal interface. Details such as accounting and allocation of deposited tokens are intentionally not specified, as Vaults are expected to be treated as black boxes on-chain and inspected off-chain before use.</p> <p>EIP-20 is enforced because implementation details like token approval and balance calculation directly carry over to the shares accounting. This standardization makes the Vaults immediately compatible with all EIP-20 use cases in addition to EIP-4626.</p> <p>The mint method was included for symmetry and feature completeness. Most current use cases of share-based Vaults do not ascribe special meaning to the shares such that a user would optimize for a specific number of shares (<code>mint</code>) rather than specific amount of underlying (<code>deposit</code>). However, it is easy to imagine future Vault strategies which would have unique and independently useful share representations.</p> <p>The <code>convertTo</code> functions serve as rough estimates that do not account for operation specific details like withdrawal fees, etc. They were included for frontends and applications that need an average value of shares or assets, not an exact value possibly including slippage or other fees. For applications that need an exact value that attempts to account for fees and slippage we have included a corresponding <code>preview</code> function to match each mutable function. These functions must not account for deposit or withdrawal limits, to ensure they are easily composable, the <code>max</code> functions are provided for that purpose.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>EIP-4626 is fully backward compatible with the EIP-20 standard and has no known compatibility issues with other standards. For production implementations of Vaults which do not use EIP-4626, wrapper adapters can be developed and used.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <a rel="external" href="https://github.com/transmissions11/solmate/blob/main/src/tokens/ERC4626.sol">Solmate EIP-4626</a>: a minimal and opinionated implementation of the standard with hooks for developers to easily insert custom logic into deposits and withdrawals.</p> <p>See <a rel="external" href="https://github.com/fubuloubu/ERC4626">Vyper EIP-4626</a>: a demo implementation of the standard in Vyper, with hooks for share price manipulation and other testing needs.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Fully permissionless use cases could fall prey to malicious implementations which only conform to the interface but not the specification. It is recommended that all integrators review the implementation for potential ways of losing user deposits before integrating.</p> <p>If implementors intend to support EOA account access directly, they should consider adding an additional function call for <code>deposit</code>/<code>mint</code>/<code>withdraw</code>/<code>redeem</code> 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> <p>The methods <code>totalAssets</code>, <code>convertToShares</code> and <code>convertToAssets</code> are estimates 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>The <code>preview</code> methods return values that are as close as possible to exact as possible. For that reason, they are manipulable by altering the on-chain conditions and are not always safe to be used as price oracles. This specification includes <code>convert</code> methods that are allowed to be inexact and therefore can be implemented as robust price oracles. For example, it would be correct to implement the <code>convert</code> methods as using a time-weighted average price in converting between assets and shares.</p> <p>Integrators of EIP-4626 Vaults should be aware of the difference between these view methods when integrating with this standard. Additionally, note that the amount of underlying assets a user may receive from redeeming their Vault shares (<code>previewRedeem</code>) can be significantly different than the amount that would be taken from them when minting the same quantity of shares (<code>previewMint</code>). The differences may be small (like if due to rounding error), or very significant (like if a Vault implements withdrawal or deposit fees, etc). Therefore integrators should always take care to use the preview function most relevant to their use case, and never assume they are interchangeable.</p> <p>Finally, EIP-4626 Vault implementers should be aware of the need for specific, opposing rounding directions across the different mutable and view methods, as it is considered most secure to favor the Vault itself during calculations over its users:</p> <ul> <li> <p>If (1) it's calculating how many shares to issue to a user for a certain amount of the underlying tokens they provide or (2) it's determining the amount of the underlying tokens to transfer to them for returning a certain amount of shares, it should round <em>down</em>.</p> </li> <li> <p>If (1) it's calculating the amount of shares a user has to supply to receive a given amount of the underlying tokens or (2) it's calculating the amount of underlying tokens a user has to provide to receive a certain amount of shares, it should round <em>up</em>.</p> </li> </ul> <p>The only functions where the preferred rounding direction would be ambiguous are the <code>convertTo</code> functions. To ensure consistency across all EIP-4626 Vault implementations it is specified that these functions MUST both always round <em>down</em>. Integrators may wish to mimic rounding up versions of these functions themselves, like by adding 1 wei to the result.</p> <p>Although the <code>convertTo</code> functions should eliminate the need for any use of an EIP-4626 Vault's <code>decimals</code> variable, it is still 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> 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-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Javier Arceneguihttps://github.com/Hardblock-IMSE-CNM Rosario Arjonahttps://github.com/RosarioArjona Roberto Románroman@imse-cnm.csic.es Iluminada Baturonehttps://github.com/lumi2018 https://wg-eips.ritovision.com/4519/

Interface for non-fungible tokens representing physical assets that can generate or recover their own accounts and obey users.

<h2 id="abstract">Abstract</h2> <p>This EIP standardizes an interface for non-fungible tokens representing physical assets, such as Internet of Things (IoT) devices. These NFTs are tied to physical assets and can verify the authenticity of the tie. They can include an Ethereum address of the physical asset, permitting physical assets to sign messages and transactions. Physical assets can operate with an operating mode defined by its corresponding NFT.</p> <h2 id="motivation">Motivation</h2> <p>This standard was developed because <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> only tracks ownership (not usage rights) and does not track the Ethereum addresses of the asset. The popularity of smart assets, such as IoT devices, is increasing. To permit secure and traceable management, these NFTs can be used to establish secure communication channels between the physical asset, its owner, and its user.</p> <h2 id="specification">Specification</h2> <p>The attributes <code>addressAsset</code> and <code>addressUser</code> are, respectively, the Ethereum addresses of the physical asset and the user. They are optional attributes but at least one of them should be used in an NFT. In the case of using only the attribute <code>addressUser</code>, two states define if the token is assigned or not to a user. <code>Figure 1</code> shows these states in a flow chart. When a token is created, transferred or unassigned, the token state is set to <code>notAssigned</code>. If the token is assigned to a valid user, the state is set to <code>userAssigned</code>.</p> <p><img src="https://wg-eips.ritovision.com/4519/./assets/images/Figure1.jpg" alt="Figure 1 : Flow chart of the token states with addressUser defined (and addressAsset undefined)" /></p> <p>In the case of defining the attribute <code>addressAsset</code> but not the attribute <code>addressUser</code>, two states define if the token is waiting for authentication with the owner or if the authentication has finished successfully. <code>Figure 2</code> shows these states in a flow chart. When a token is created or transferred to a new owner, then the token changes its state to <code>waitingForOwner</code>. In this state, the token is waiting for the mutual authentication between the asset and the owner. Once authentication is finished successfully, the token changes its state to <code>engagedWithOwner</code>.</p> <p><img src="https://wg-eips.ritovision.com/4519/./assets/images/Figure2.jpg" alt="Figure 2 : Flow chart of the token states with addressAsset defined (and addressUser undefined)" /></p> <p>Finally, if both the attributes <code>addressAsset</code> and <code>addressUser</code> are defined, the states of the NFT define if the asset has been engaged or not with the owner or the user (<code>waitingForOwner</code>, <code>engagedWithOwner</code>, <code>waitingForUser</code> and <code>engagedWithUser</code>). The flow chart in <code>Figure 3</code> shows all the possible state changes. The states related to the owner are the same as in <code>Figure 2</code>. The difference is that, at the state <code>engagedWithOwner</code>, the token can be assigned to a user. If a user is assigned (the token being at states <code>engagedWithOwner</code>, <code>waitingForUser</code> or <code>engagedWithUser</code>), then the token changes its state to <code>waitingForUser</code>. Once the asset and the user authenticate each other, the state of the token is set to <code>engagedWithUser</code>, and the user is able to use the asset.</p> <p><img src="https://wg-eips.ritovision.com/4519/./assets/images/Figure3.jpg" alt="Figure 3 : Flow chart of the token states with addressUser and addressUser defined" /></p> <p>In order to complete the ownership transfer of a token, the new owner must carry out a mutual authentication process with the asset, which is off-chain with the asset and on-chain with the token, by using their Ethereum addresses. Similarly, a new user must carry out a mutual authentication process with the asset to complete a use transfer. NFTs define how the authentication processes start and finish. These authentication processes allow deriving fresh session cryptographic keys for secure communication between assets and owners, and between assets and users. Therefore, the trustworthiness of the assets can be traced even if new owners and users manage them.</p> <p>When the NFT is created or when the ownership is transferred, the token state is <code>waitingForOwner</code>. The asset sets its operating mode to <code>waitingForOwner</code>. The owner generates a pair of keys using the elliptic curve secp256k1 and the primitive element P used on this curve: a secret key SK_{O_A} and a Public Key PK_{O_A}, so that PK_{O_A} = SK_{O_A} * P. To generate the shared key between the owner and the asset, K_O, the public key of the asset, PK_A, is employed as follows:</p> <p>K_O = PK_A * SK_{O_A}</p> <p>Using the function <code>startOwnerEngagement</code>, PK_{O_A} is saved as the attribute <code>dataEngagement</code> and the hash of K_O as the attribute <code>hashK_OA</code>. The owner sends request engagement to the asset, and the asset calculates:</p> <p>K_A = SK_A * PK_{O_A}</p> <p>If everything is correctly done, K_O and K_A are the same since:</p> <p>K_O = PK_A * SK_{O_A} = (SK_A * P) * SK_{O_A} = SK_A * (SK_{O_A} * P) = SK_A * PK_{O_A}</p> <p>Using the function <code>ownerEngagement</code>, the asset sends the hash of K_A, and if it is the same as the data in <code>hashK_OA</code>, then the state of the token changes to <code>engagedWithOwner</code> and the event <code>OwnerEngaged</code> are sent. Once the asset receives the event, it changes its operation mode to <code>engagedWithOwner</code>. This process is shown in <code>Figure 4</code>. From this moment, the asset can be managed by the owner and they can communicate in a secure way using the shared key.</p> <p><img src="https://wg-eips.ritovision.com/4519/./assets/images/Figure4.jpg" alt="Figure 4: Steps in a successful owner and asset mutual authentication process" /></p> <p>If the asset consults Ethereum and the state of its NFT is <code>waitingForUser</code>, the asset (assuming it is an electronic physical asset) sets its operating mode to <code>waitingForUser</code>. Then, a mutual authentication process is carried out with the user, as already done with the owner. The user sends the transaction associated with the function <code>startUserEngagement</code>. As in <code>startOwnerEngagement</code>, this function saves the public key generated by the user, PK_{U_A}, as the attribute <code>dataEngagement</code> and the hash of K_U = PK_A * SK_{U_A} as the attribute <code>hashK_UA</code> in the NFT.</p> <p>The user sends request engagement and the asset calculates:</p> <p>K_A = SK_A * PK_{U_A}</p> <p>If everything is correctly done, K_U and K_A are the same since:</p> <p>K_U = PK_A * SK_{U_A} = (SK_A * P) * SK_{U_A} = SK_A * (SK_{U_A} * P) = SK_A * PK_{U_A}</p> <p>Using the function <code>userEngagement</code>, the asset sends the hash of K_A obtained and if it is the same as the data in <code>hashK_UA</code>, then the state of the token changes to <code>engagedWithUser</code> and the event <code>UserEngaged</code> is sent. Once the asset receives the event, it changes its operation mode to <code>engagedWithUser</code>. This process is shown in <code>Figure 5</code>. From this moment, the asset can be managed by the user and they can communicate in a secure way using the shared key.</p> <p><img src="https://wg-eips.ritovision.com/4519/./assets/images/Figure5.jpg" alt="Figure 5: Steps in a successful user and asset mutual authentication process" /></p> <p>Since the establishment of a shared secret key is very important for a secure communication, NFTs include the attributes <code>hashK_OA</code>, <code>hashK_UA</code> and <code>dataEngagement</code>. The first two attributes define, respectively, the hash of the secret key shared between the asset and its owner and between the asset and its user. Assets, owners and users should check they are using the correct shared secret keys. The attribute <code>dataEngagement</code> defines the public data needed for the agreement.</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 class="z-comment"> ///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> EIP-4519 NFT: Extension of EIP-721 Non-Fungible Token Standard. </span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-keyword"> Note</span><span class="z-comment">: the EIP-165 identifier for this interface is 0x8a68abe3</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">4519</span><span> NFT is EIP721</span><span class="z-comment">/*</span><span class="z-comment">,EIP165</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 the NFT is assigned as utility of a new user.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This event emits when the user of the token changes.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (`_addressUser` == 0) when no user is assigned.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UserAssigned</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"> _addressUser</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 user and asset finish mutual authentication process successfully.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This event emits when both the user and the asset prove they share a secure communication channel.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UserEngaged</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"> @dev</span><span class="z-comment"> This emits when owner and asset finish mutual authentication process successfully.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This event emits when both the owner and the asset prove they share a secure communication channel.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> OwnerEngaged</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"> @dev</span><span class="z-comment"> This emits when it is checked that the timeout has expired.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This event emits when the timestamp of the EIP-4519 NFT is not updated in timeout.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TimeoutAlarm</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 class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> This function defines how the NFT is assigned as utility of a new user (if &quot;addressUser&quot; is defined).</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Only the owner of the EIP-4519 NFT can assign a user. If &quot;addressAsset&quot; is defined, then the state of the token must be</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> &quot;engagedWithOwner&quot;,&quot;waitingForUser&quot; or &quot;engagedWithUser&quot; and this function changes the state of the token defined by &quot;_tokenId&quot; to</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> &quot;waitingForUser&quot;. If &quot;addressAsset&quot; is not defined, the state is set to &quot;userAssigned&quot;. In both cases, this function sets the parameter </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> &quot;addressUser&quot; to &quot;_addressUser&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"> _tokenId</span><span class="z-comment"> is the tokenId of the EIP-4519 NFT tied to the asset.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _addressUser</span><span class="z-comment"> is the address of the new user.</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"> _addressUser</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</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"> This function defines the initialization of the mutual authentication process between the owner and the asset.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Only the owner of the token can start this authentication process if &quot;addressAsset&quot; is defined and the state of the token is &quot;waitingForOwner&quot;.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The function does not change the state of the token and saves &quot;_dataEngagement&quot; </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and &quot;_hashK_OA&quot; in the parameters of 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"> _tokenId</span><span class="z-comment"> is the tokenId of the EIP-4519 NFT tied to the asset.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _dataEngagement</span><span class="z-comment"> is the public data proposed by the owner for the agreement of the shared key.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _hashK_OA</span><span class="z-comment"> is the hash of the secret proposed by the owner to share with the asset.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> startOwnerEngagement</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"> _dataEngagement</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _hashK_OA</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 class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> This function completes the mutual authentication process between the owner and the asset.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Only the asset tied to the token can finish this authentication process provided that the state of the token is</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> &quot;waitingForOwner&quot; and dataEngagement is different from 0. This function compares hashK_OA saved in</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the token with hashK_A. If they are equal then the state of the token changes to &quot;engagedWithOwner&quot;, dataEngagement is set to 0,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and the event &quot;OwnerEngaged&quot; is 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"> _hashK_A</span><span class="z-comment"> is the hash of the secret generated by the asset to share with the owner.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> ownerEngagement</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _hashK_A</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</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"> This function defines the initialization of the mutual authentication process between the user and the asset.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Only the user of the token can start this authentication process if &quot;addressAsset&quot; and &quot;addressUser&quot; are defined and</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the state of the token is &quot;waitingForUser&quot;. The function does not change the state of the token and saves &quot;_dataEngagement&quot; </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and &quot;_hashK_UA&quot; in the parameters of 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"> _tokenId</span><span class="z-comment"> is the tokenId of the EIP-4519 NFT tied to the asset.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _dataEngagement</span><span class="z-comment"> is the public data proposed by the user for the agreement of the shared key.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _hashK_UA</span><span class="z-comment"> is the hash of the secret proposed by the user to share with the asset.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> startUserEngagement</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"> _dataEngagement</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _hashK_UA</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 class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> This function completes the mutual authentication process between the user and the asset.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Only the asset tied to the token can finish this authentication process provided that the state of the token is</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> &quot;waitingForUser&quot; and dataEngagement is different from 0. This function compares hashK_UA saved in</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the token with hashK_A. If they are equal then the state of the token changes to &quot;engagedWithUser&quot;, dataEngagement is set to 0,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and the event &quot;UserEngaged&quot; is 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"> _hashK_A</span><span class="z-comment"> is the hash of the secret generated by the asset to share with the user.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> userEngagement</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _hashK_A</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</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"> This function checks if the timeout has expired.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Everybody can call this function to check if the timeout has expired. The event &quot;TimeoutAlarm&quot; is emitted</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> if the timeout has 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"> is the tokenId of the EIP-4519 NFT tied to the asset.</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 timeout has expired and false in other case.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkTimeout</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-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"> @notice</span><span class="z-comment"> This function sets the value of timeout.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Only the owner of the token can set this value provided that the state of the token is &quot;engagedWithOwner&quot;,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> &quot;waitingForUser&quot; or &quot;engagedWithUser&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"> _tokenId</span><span class="z-comment"> is the tokenId of the EIP-4519 NFT tied to the asset.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _timeout</span><span class="z-comment"> is the value to assign to timeout.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setTimeout</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"> _timeout</span><span>)</span><span class="z-storage z-type"> external</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"> This function updates the timestamp, thus avoiding the timeout alarm.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Only the asset tied to the token can update its own timestamp.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateTimestamp</span><span>(</span><span>)</span><span class="z-storage z-type"> external</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"> This function lets obtain the tokenId from an address. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Everybody can call this function. The code executed only reads from Ethereum.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _addressAsset</span><span class="z-comment"> is the address to obtain the tokenId from it.</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 tied to the asset that generates _addressAsset.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenFromBCA</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addressAsset</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"> This function lets know the owner of the token from the address of the asset tied to 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"> Everybody can call this function. The code executed only reads from Ethereum.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _addressAsset</span><span class="z-comment"> is the address to obtain the owner from it.</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"> owner</span><span class="z-comment"> of the token bound to the asset that generates _addressAsset.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> ownerOfFromBCA</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addressAsset</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> This function lets know the user of the token from its tokenId.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Everybody can call this function. The code executed only reads from Ethereum.</span></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"> is the tokenId of the EIP-4519 NFT tied to the asset.</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"> of the token from its _tokenId.</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></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> This function lets know the user of the token from the address of the asset tied to 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"> Everybody can call this function. The code executed only reads from Ethereum.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _addressAsset</span><span class="z-comment"> is the address to obtain the user from it.</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"> of the token tied to the asset that generates _addressAsset.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> userOfFromBCA</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addressAsset</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> This function lets know how many tokens are 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"> Everybody can call this function. The code executed only reads from Ethereum.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _addressUser</span><span class="z-comment"> is the address of the user.</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 assigned to a user.</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"> _addressUser</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"> This function lets know how many tokens of a particular owner are 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"> Everybody can call this function. The code executed only reads from Ethereum.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _addressUser</span><span class="z-comment"> is the address of 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"> _addressOwner</span><span class="z-comment"> is 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"> number</span><span class="z-comment"> of tokens assigned to a user from an owner.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> userBalanceOfAnOwner</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addressUser</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _addressOwner</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="authentication">Authentication</h3> <p>This EIP uses smart contracts to verify the mutual authentication process since smart contracts are trustless.</p> <h3 id="tie-time">Tie Time</h3> <p>This EIP proposes including the attribute timestamp (to register in Ethereum the last time that the physical asset checked the tie with its token) and the attribute timeout (to register the maximum delay time established for the physical asset to prove again the tie). These attributes avoid that a malicious owner or user could use the asset endlessly.</p> <p>When the asset calls <code>updateTimestamp</code>, the smart contract must call <code>block.timestamp</code>, which provides current block timestamp as seconds since Unix epoch. For this reason, <code>timeout</code> must be provided in seconds.</p> <h3 id="eip-721-based">EIP-721-based</h3> <p><a href="https://wg-eips.ritovision.com/721/">EIP-721</a> is the most commonly-used standard for generic NFTs. This EIP extends EIP-721 for backwards compatibility.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is an extension of EIP-721. It is fully compatible with both of the commonly used optional extensions (<code>IERC721Metadata</code> and <code>IERC721Enumerable</code>) mentioned in the EIP-721 standard.</p> <h2 id="test-cases">Test Cases</h2> <p>The test cases presented in the paper shown below are available <a href="https://wg-eips.ritovision.com/4519/assets/PoC_SmartNFT/README/">here</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A first version was presented in a paper of the Special Issue <strong>Security, Trust and Privacy in New Computing Environments</strong> of <strong>Sensors</strong> journal of <strong>MDPI</strong> editorial. The paper, entitled <a href="https://wg-eips.ritovision.com/4519/./assets/sensors-21-03119.pdf">Secure Combination of IoT and Blockchain by Physically Binding IoT Devices to Smart Non-Fungible Tokens Using PUFs</a>, was written by the same authors of this EIP.</p> <h2 id="security-considerations">Security Considerations</h2> <p>In this EIP, a generic system has been proposed for the creation of non-fungible tokens tied to physical assets. A generic point of view based on the improvements of the current EIP-721 NFT is provided, such as the implementation of the user management mechanism, which does not affect the token's ownership. The physical asset should have the ability to generate an Ethereum address from itself in a totally random way so that only the asset is able to know the secret from which the Ethereum address is generated. In this way, identity theft is avoided and the asset can be proven to be completely genuine. In order to ensure this, it is recommended that only the manufacturer of the asset has the ability to create its associated token. In the case of an IoT device, the device firmware will be unable to share and modify the secret. Instead of storing the secrets, it is recommended that assets reconstruct their secrets from non-sensitive information such as the helper data associated with Physical Unclonable Functions (PUFs). Although a secure key exchange protocol based on elliptic curves has been proposed, the token is open to coexist with other types of key exchange.</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-30T00:00:00+00:00 2026-02-11T14:49:27+00:00 Mikhail Kalininhttps://github.com/mkalinin Danny Ryanhttps://github.com/djrtwo https://wg-eips.ritovision.com/4399/

Expose beacon chain randomness in the EVM by supplanting DIFFICULTY opcode semantics

<h2 id="abstract">Abstract</h2> <p>This EIP supplants the semantics of the return value of existing <code>DIFFICULTY (0x44)</code> opcode and renames the opcode to <code>PREVRANDAO (0x44)</code>.</p> <p>The return value of the <code>DIFFICULTY (0x44)</code> instruction after this change is the output of the randomness beacon provided by the beacon chain.</p> <h2 id="motivation">Motivation</h2> <p>Applications may benefit from using the randomness accumulated by the beacon chain. Thus, randomness outputs produced by the beacon chain should be accessible in the EVM.</p> <p>At the point of <code>TRANSITION_BLOCK</code> of the Proof-of-Stake (PoS) upgrade described in <a href="https://wg-eips.ritovision.com/3675/">EIP-3675</a>, the <code>difficulty</code> block field <strong>MUST</strong> be <code>0</code> thereafter because there is no longer any Proof-of-Work (PoW) seal on the block. This means that the <code>DIFFICULTY (0x44)</code> instruction no longer has it's previous semantic meaning, nor a clear "correct" value to return.</p> <p>Given prior analysis on the usage of <code>DIFFICULTY</code>, the value returned by the instruction mixed with other values is a common pattern used by smart contracts to obtain randomness. The instruction with the same number as the <code>DIFFICULTY</code> opcode returning outputs of the beacon chain RANDAO implementation makes the upgrade to PoS backwards compatible for existing smart contracts obtaining randomness from the <code>DIFFICULTY</code> instruction.</p> <p>Additionally, changes proposed by this EIP allow for smart contracts to determine whether the upgrade to the PoS has already happened. This can be done by analyzing the return value of the <code>DIFFICULTY</code> instruction. A value greater than <code>2**64</code> indicates that the transaction is being executed in the PoS block. Decompilers and other similar tooling may also use this trick to discern the new semantics of the instruction if data of the block including the transaction in question is available.</p> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions</h3> <ul> <li><strong><code>TRANSITION_BLOCK</code></strong> The definition of this block can be found in the Definitions section of <a href="https://wg-eips.ritovision.com/3675/#definitions">EIP-3675</a>.</li> </ul> <h3 id="block-structure">Block structure</h3> <p>Beginning with <code>TRANSITION_BLOCK</code>, client software <strong>MUST</strong> set the value of the <code>mixHash</code>, i.e. the field with the number <code>13</code> (0-indexed) in a block header, to the latest RANDAO mix of the post beacon state of the previous block.</p> <h3 id="evm">EVM</h3> <p>Beginning with <code>TRANSITION_BLOCK</code>, the <code>DIFFICULTY (0x44)</code> instruction <strong>MUST</strong> return the value of the <code>mixHash</code> field.</p> <p><em>Note</em>: The gas cost of the <code>DIFFICULTY (0x44)</code> opcode remains unchanged.</p> <h3 id="renaming">Renaming</h3> <p>The <code>mixHash</code> field <strong>SHOULD</strong> further be renamed to <code>prevRandao</code>.</p> <p>The <code>DIFFICULTY (0x44)</code> opcode <strong>SHOULD</strong> further be renamed to <code>PREVRANDAO (0x44)</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="including-randao-output-in-the-block-header">Including RANDAO output in the block header</h3> <p>Including a RANDAO output in the block header provides a straightforward method of accessing it from inside of the EVM as block header data is already available in the EVM context.</p> <p>Additionally, this ensures that the execution layer can be fully executed with the block alone rather than requiring extra inputs from the PoS consensus layer.</p> <p>Mixing the randomness into a block header may contribute to uniqueness of the block hash in the case when values of other fields of the block header match the corresponding values of the header of another block.</p> <h3 id="using-mixhash-field-instead-of-difficulty">Using <code>mixHash</code> field instead of <code>difficulty</code></h3> <p>The <code>mixHash</code> header field is used instead of <code>difficulty</code> to avoid a class of hidden forkchoice bugs after the PoS upgrade.</p> <p>Client software implementing pre-EIP-3675 logic heavily depends on the <code>difficulty</code> value as total difficulty computation is the basis of the PoW fork choice rule. Setting the <code>difficulty</code> field to <code>0</code> at the PoS upgrade aims to reduce the surface of bugs related to the total difficulty value growing after the upgrade.</p> <p>Additionally, any latent total difficulty computation after the PoS upgrade would become overflow prone if the randomness output supplanted the value of the <code>difficulty</code> field.</p> <h3 id="reusing-existing-field-instead-of-appending-a-new-one">Reusing existing field instead of appending a new one</h3> <p>The <code>mixHash</code> field is deprecated at the PoS upgrade and set to zero bytes array thereafter. Reusing an existing field as a place for the randomness output saves 32 bytes per block and effectively removes the deprecation of one of the fields induced by the upgrade.</p> <h3 id="reusing-the-difficulty-opcode-instead-of-introducing-a-new-one">Reusing the <code>DIFFICULTY</code> opcode instead of introducing a new one</h3> <p>See the <a href="https://wg-eips.ritovision.com/4399/#motivation">Motivation</a>.</p> <h3 id="renaming-the-field-and-the-opcode">Renaming the field and the opcode</h3> <p>The renaming should be done to make the field and the opcode names semantically sound.</p> <h3 id="using-transition-block-rather-than-a-block-or-slot-number">Using <code>TRANSITION_BLOCK</code> rather than a block or slot number</h3> <p>By utilizing <code>TRANSITION_BLOCK</code> to trigger the change in logic defined in this EIP rather than a block or slot number, this EIP is tightly coupled to the PoS upgrade defined by <a href="https://wg-eips.ritovision.com/3675/">EIP-3675</a>.</p> <p>By tightly coupling to the PoS upgrade, we ensure that there is no discontinuity for the usecase of this opcode for randomness -- the primary <a href="https://wg-eips.ritovision.com/4399/#motivation">motivation</a> for re-using <code>DIFFICULTY</code> rather than creating a new opcode.</p> <h3 id="using-2-64-threshold-to-determine-pos-blocks">Using <code>2**64</code> threshold to determine PoS blocks</h3> <p>The probability of RANDAO value to fall into the range between <code>0</code> and <code>2**64</code> and, thus, to be mixed with PoW difficulty values, is drastically low. Though, proposed threshold might seem to have insufficient distance from difficulty values on Ethereum Mainnet (they are currently around <code>2**54</code>), it requires a thousand times increase of the hashrate to make this threshold insecure. Such an increase is considered impossible to occur before the upcoming consensus upgrade.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces backward incompatible changes to the execution and validation of EVM state transitions. As written, this EIP utilizes <code>TRANSITION_BLOCK</code> and is thus tightly coupled with the PoS upgrade introduced in <a href="https://wg-eips.ritovision.com/3675/">EIP-3675</a>. If this EIP is to be adopted, it <strong>MUST</strong> be scheduled at the same time as EIP-3675.</p> <p>Additionally, the changes proposed might be backward incompatible for the following categories of applications:</p> <ul> <li>Applications that use the value returned by the <code>DIFFICULTY</code> opcode as the PoW <code>difficulty</code> parameter</li> <li>Applications with logic that depends on the <code>DIFFICULTY</code> opcode returning a relatively small number with respect to the full 256-bit size of the field.</li> </ul> <p>The first category is already affected by switching the consensus mechanism to PoS and no additional breaking changes are introduced by this specification.</p> <p>The second category is comprised of applications that use the return value of the <code>DIFFICULTY</code> opcode in operations that might cause either overflow or underflow errors. While it is theoretically possible to author an application where a change in the range of possible values this opcode may return could lead to a security vulnerability, the chances of that are negligible.</p> <h2 id="test-cases">Test Cases</h2> <ul> <li>In one of ancestors of <code>TRANSITION_BLOCK</code> deploy a contract that stores return value of <code>DIFFICULTY (0x44)</code> to the state</li> <li>Check that value returned by <code>DIFFICULTY (0x44)</code> in transaction executed within the parent of <code>TRANSITION_BLOCK</code> equals <code>difficulty</code> field value</li> <li>Check that value returned by <code>PREVRANDAO (0x44)</code> in transaction executed within <code>TRANSITION_BLOCK</code> equals <code>prevRandao</code> field value</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>The <code>PREVRANDAO (0x44)</code> opcode in PoS Ethereum (based on the beacon chain RANDAO implementation) is a source of randomness with different properties to the randomness supplied by <code>BLOCKHASH (0x40)</code> or <code>DIFFICULTY (0x44)</code> opcodes in the PoW network.</p> <h3 id="biasability">Biasability</h3> <p>The beacon chain RANDAO implementation gives every block proposer 1 bit of influence power per slot. Proposer may deliberately refuse to propose a block on the opportunity cost of proposer and transaction fees to prevent beacon chain randomness (a RANDAO mix) from being updated in a particular slot.</p> <p>An effect of proposer's influence power is limited in time and lasts until the first honest RANDAO reveal is made afterwards. This limitation does also exist in the case when proposers of <code>n</code> consecutive slots are colluding to get <code>n</code> bits of influence power. Simply speaking, one honest block proposal is enough to unbias the RANDAO even if it was biased during several slots in a row.</p> <p>Additionally, semantics of the <code>PREVRANDAO (0x44)</code> instruction gives proposers another way to gain 1 bit of influence power on applications. Biased proposer may censor a rolling the dice transaction to force it to be included into the next block, thus, force it to use a RANDAO mix that the proposer knows in advance. The opportunity cost in this case would be negligible.</p> <h3 id="predictability">Predictability</h3> <p>Obviously, historical randomness provided by any decentralized oracle is 100% predictable. On the contrary, the randomness that is revealed in the future is predictable up to a limited extent.</p> <p>A list of inputs influencing future randomness on the beacon chain consists of but is not limited to the following items:</p> <ul> <li><strong>Accumulated randomness.</strong> A RANDAO mix produced by the beacon chain in the last slot of epoch <code>N</code> is the main input to the function defining block proposers in each slot of epoch <code>N + MIN_SEED_LOOKAHEAD + 1</code>, i.e. it is the main factor defining future RANDAO revealers.</li> <li><strong>Number of active validators.</strong> A number of active validators throughout an epoch is another input to the block proposer function.</li> <li><strong>Effective balance.</strong> All else being equal, the lower the effective balance of a validator the lower the chance this validator has to be designated as a proposer in a slot.</li> <li><strong>Accidentally missed proposals.</strong> Network conditions and other factors that are resulting in accidentally missed proposals is a source of highly qualitative entropy that impacts RANDAO mixes. Usual rate of missed proposals on the Mainnet is about <code>1%</code>.</li> </ul> <p>These inputs may be predictable and malleable on a short range of slots but the longer the attempted lookahead the more entropy is accumulated by the beacon chain.</p> <h3 id="tips-for-application-developers">Tips for application developers</h3> <p>The following tips attempt to reduce predictability and biasability of randomness outputs returned by <code>PREVRANDAO (0x44)</code>:</p> <ol> <li>Make your applications rely on the future randomness with a reasonably high lookahead. For example, an application stops accepting bids at the end of epoch <code>K</code> and uses a RANDAO mix produced in slot <code>K + N + ε</code> to roll the dice, where <code>N</code> is a lookahead in epochs and <code>ε</code> is a few slots into epoch <code>N + 1</code>.</li> <li>At least four epochs of lookahead results in the following outcome:</li> </ol> <ul> <li>A proposer set of epoch <code>N + 1</code> isn't known at the end of epoch <code>K</code> breaking a direct link between bidders and dice rollers</li> <li>A number of active validators is updated at the end of each epoch affecting a set of proposers of next epochs, thus, impacting a RANDAO mix used by the application to roll the dice</li> <li>Due to Mainnet statistics, there is about a <code>100%</code> chance for the network to accidentally miss a proposal during this period of time which reduces predictability of a RANDAO mix used to roll the dice.</li> </ul> <ol start="3"> <li>Setting <code>ε</code> to a small number, e.g. 2 or 4 slots, gives a third party a little time to gain influence power on the future randomness that is being used to roll the dice. This amount of time is defined by <code>MIN_SEED_LOOKAHEAD</code> parameter and is about 6 minutes on the Mainnet.</li> </ol> <p>A reasonably high distance between bidding and rolling the dice attempts to leave low chance for bidders controlling a subset of validators to directly exploit their influence power. Ultimately, this chance depends on the type of the game and on a number of controlled validators. For instance, a chance of a single validator to affect a one-time game is negligible, and becomes bigger for multiple validators in a repeated game scenario.</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-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 Daniel Ivanovhttps://github.com/Daniel-K-Ivanov George Spasovhttps://github.com/Perseverance https://wg-eips.ritovision.com/4400/

Interface extension for EIP-721 consumer role

<h2 id="abstract">Abstract</h2> <p>This specification defines standard functions outlining a <code>consumer</code> role for instance(s) of <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>. An implementation allows reading the current <code>consumer</code> for a given NFT (<code>tokenId</code>) along with a standardized event for when an <code>consumer</code> has changed. The proposal depends on and extends the existing <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>.</p> <h2 id="motivation">Motivation</h2> <p>Many <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> contracts introduce their own custom role that grants permissions for utilising/consuming a given NFT instance. The need for that role stems from the fact that other than owning the NFT instance, there are other actions that can be performed on an NFT. For example, various metaverses use <code>operator</code> / <code>contributor</code> roles for Land (EIP-721), so that owners of the land can authorise other addresses to deploy scenes to them (f.e. commissioning a service company to develop a scene).</p> <p>It is common for NFTs to have utility other than ownership. That being said, it requires a separate standardized consumer role, allowing compatibility with user interfaces and contracts, managing those contracts.</p> <p>Having a <code>consumer</code> role will enable protocols to integrate and build on top of dApps that issue EIP-721 tokens. One example is the creation of generic/universal NFT renting marketplaces.</p> <p>Example of kinds of contracts and applications that can benefit from this standard are:</p> <ul> <li>metaverses that have land and other types of digital assets in those metaverses (scene deployment on land, renting land / characters / clothes / passes to events etc.)</li> <li>NFT-based yield-farming. Adopting the standard enables the "staker" (owner of the NFT) to have access to the utility benefits even after transferring his NFT to the staking contract</li> </ul> <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>Every contract compliant to the <code>EIP721Consumable</code> extension MUST implement the <code>IEIP721Consumable</code> interface. The <strong>consumer extension</strong> is OPTIONAL for EIP-721 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"> EIP-721 Consumer Role extension</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-keyword"> Note</span><span class="z-comment">: the EIP-165 identifier for this interface is 0x953c8dfa</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IEIP721Consumable</span><span class="z-comment"> /*</span><span class="z-comment"> is EIP721 </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"> Emitted when `owner` changes the `consumer` of an NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero address for consumer indicates that there is no consumer address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> When a Transfer event emits, this also indicates that the consumer address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> for that NFT (if any) is set to none</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ConsumerChanged</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"> consumer</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Get the consumer 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 consumer</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 get the consumer 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"> consumer address for this NFT, or the zero address if there is none</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> consumerOf</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"> 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"> Change or reaffirm the consumer address for 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 there is no consumer address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Throws unless `msg.sender` is the current NFT owner, an authorised</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> operator of the current owner or approved address</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"> _consumer</span><span class="z-comment"> The new consumer of the NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> changeConsumer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _consumer</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>Every contract implementing the <code>EIP721Consumable</code> extension is free to define the permissions of a <code>consumer</code> (e.g. what are consumers allowed to do within their system) with only one exception - consumers MUST NOT be considered owners, authorised operators or approved addresses as per the EIP-721 specification. Thus, they MUST NOT be able to execute transfers &amp; approvals.</p> <p>The <code>consumerOf(uint256 _tokenId)</code> function MAY be implemented as <code>pure</code> or <code>view</code>.</p> <p>The <code>changeConsumer(address _consumer, uint256 _tokenId)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>ConsumerChanged</code> event MUST be emitted when a consumer is changed.</p> <p>On every <code>transfer</code>, the consumer MUST be changed to a default address. It is RECOMMENDED for implementors to use <code>address(0)</code> as that default address.</p> <p>The <code>supportsInterface</code> method MUST return <code>true</code> when called with <code>0x953c8dfa</code>.</p> <h2 id="rationale">Rationale</h2> <p>Key factors influencing the standard:</p> <ul> <li>Keeping the number of functions in the interfaces to a minimum to prevent contract bloat</li> <li>Simplicity</li> <li>Gas Efficiency</li> <li>Not reusing or overloading other already existing roles (e.g. owners, operators, approved addresses)</li> </ul> <h3 id="name">Name</h3> <p>The chosen name resonates with the purpose of its existence. Consumers can be considered entities that utilise the token instances, without necessarily having ownership rights to it.</p> <p>The other name for the role that was considered was <code>operator</code>, however it is already defined and used within the <code>EIP-721</code> standard.</p> <h3 id="restriction-on-the-permissions">Restriction on the Permissions</h3> <p>There are numerous use-cases where a distinct role for NFTs is required that MUST NOT have owner permissions. A contract that implements the consumer role and grants ownership permissions to the consumer renders this standard pointless.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with current EIP-721 standards. There are no other standards that define a similar role for NFTs and the name (<code>consumer</code>) is not used by other EIP-721 related standards.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases are available in the reference implementation <a href="https://wg-eips.ritovision.com/4400/./assets/test/erc721-consumable.ts">here</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation can be found <a href="https://wg-eips.ritovision.com/4400/./assets/contracts/ERC721Consumable.sol">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Implementors of the <code>EIP721Consumable</code> standard must consider thoroughly the permissions they give to <code>consumers</code>. Even if they implement the standard correctly and do not allow transfer/burning of NFTs, they might still provide permissions to the <code>consumers</code> that they might not want to provide otherwise and should be restricted to <code>owners</code> only.</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-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-11T00:00:00+00:00 2026-02-11T14:48:25+00:00 Wayne Changhttps://github.com/wyc Gregory Roccohttps://github.com/obstropolos Brantly Milleganhttps://github.com/brantlymillegan Nick Johnsonhttps://github.com/Arachnid Oliver Terbuhttps://github.com/awoie https://wg-eips.ritovision.com/4361/

Off-chain authentication for Ethereum accounts to establish sessions.

<h2 id="abstract">Abstract</h2> <p>Sign-In with Ethereum describes how Ethereum accounts authenticate with off-chain services by signing a standard message format parameterized by scope, session details, and security mechanisms (e.g., a nonce). The goals of this specification are to provide a self-custodied alternative to centralized identity providers, improve interoperability across off-chain services for Ethereum-based authentication, and provide wallet vendors a consistent machine-readable message format to achieve improved user experiences and consent management.</p> <h2 id="motivation">Motivation</h2> <p>When signing in to popular non-blockchain services today, users will typically use identity providers (IdPs) that are centralized entities with ultimate control over users' identifiers, for example, large internet companies and email providers. Incentives are often misaligned between these parties. Sign-In with Ethereum offers a new self-custodial option for users who wish to assume more control and responsibility over their own digital identity.</p> <p>Already, many services support workflows to authenticate Ethereum accounts using message signing, such as to establish a cookie-based web session which can manage privileged metadata about the authenticating address. This is an opportunity to standardize the sign-in workflow and improve interoperability across existing services, while also providing wallet vendors a reliable method to identify signing requests as Sign-In with Ethereum requests for improved UX.</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="overview">Overview</h3> <p>Sign-In with Ethereum (SIWE) works as follows:</p> <ol> <li>The relying party generates a SIWE Message and prefixes the SIWE Message with <code>\x19Ethereum Signed Message:\n&lt;length of message&gt;</code> as defined in <a href="https://wg-eips.ritovision.com/191/">ERC-191</a>.</li> <li>The wallet presents the user with a structured plaintext message or equivalent interface for signing the SIWE Message with the <a href="https://wg-eips.ritovision.com/191/">ERC-191</a> signed data format.</li> <li>The signature is then presented to the relying party, which checks the signature's validity and SIWE Message content.</li> <li>The relying party might further fetch data associated with the Ethereum address, such as from the Ethereum blockchain (e.g., ENS, account balances, <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>/<a href="https://wg-eips.ritovision.com/721/">ERC-721</a>/<a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> asset ownership), or other data sources that might or might not be permissioned.</li> </ol> <h3 id="message-format">Message Format</h3> <h4 id="abnf-message-format">ABNF Message Format</h4> <p>A SIWE Message MUST conform with the following Augmented Backus–Naur Form (ABNF, <a rel="external" href="https://www.rfc-editor.org/rfc/rfc5234">RFC 5234</a>) expression (note that <code>%s</code> denotes case sensitivity for a string term, as per <a rel="external" href="https://www.rfc-editor.org/rfc/rfc7405">RFC 7405</a>).</p> <pre class="giallo z-code"><code data-lang="ABNF"><span class="giallo-l"><span>sign-in-with-ethereum =</span></span> <span class="giallo-l"><span class="z-keyword"> [</span><span class="z-variable z-other"> scheme</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-variable z-other"> domain</span><span class="z-string"> %s&quot;</span><span class="z-string"> wants you to sign in with your Ethereum account:</span><span class="z-string">&quot;</span><span> LF</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span> LF</span></span> <span class="giallo-l"><span> LF</span></span> <span class="giallo-l"><span class="z-keyword"> [</span><span class="z-variable z-other"> statement</span><span> LF</span><span class="z-keyword"> ]</span></span> <span class="giallo-l"><span> LF</span></span> <span class="giallo-l"><span class="z-string"> %s&quot;</span><span class="z-string">URI: </span><span class="z-string">&quot;</span><span class="z-variable z-other"> uri</span><span> LF</span></span> <span class="giallo-l"><span class="z-string"> %s&quot;</span><span class="z-string">Version: </span><span class="z-string">&quot;</span><span class="z-variable z-other"> version</span><span> LF</span></span> <span class="giallo-l"><span class="z-string"> %s&quot;</span><span class="z-string">Chain ID: </span><span class="z-string">&quot;</span><span class="z-variable z-other"> chain-id</span><span> LF</span></span> <span class="giallo-l"><span class="z-string"> %s&quot;</span><span class="z-string">Nonce: </span><span class="z-string">&quot;</span><span class="z-variable z-other"> nonce</span><span> LF</span></span> <span class="giallo-l"><span class="z-string"> %s&quot;</span><span class="z-string">Issued At: </span><span class="z-string">&quot;</span><span class="z-variable z-other"> issued-at</span></span> <span class="giallo-l"><span class="z-keyword"> [</span><span> LF</span><span class="z-string"> %s&quot;</span><span class="z-string">Expiration Time: </span><span class="z-string">&quot;</span><span class="z-variable z-other"> expiration-time</span><span class="z-keyword"> ]</span></span> <span class="giallo-l"><span class="z-keyword"> [</span><span> LF</span><span class="z-string"> %s&quot;</span><span class="z-string">Not Before: </span><span class="z-string">&quot;</span><span class="z-variable z-other"> not-before</span><span class="z-keyword"> ]</span></span> <span class="giallo-l"><span class="z-keyword"> [</span><span> LF</span><span class="z-string"> %s&quot;</span><span class="z-string">Request ID: </span><span class="z-string">&quot;</span><span class="z-variable z-other"> request-id</span><span class="z-keyword"> ]</span></span> <span class="giallo-l"><span class="z-keyword"> [</span><span> LF</span><span class="z-string"> %s&quot;</span><span class="z-string">Resources:</span><span class="z-string">&quot;</span></span> <span class="giallo-l"><span class="z-variable z-other"> resources</span><span class="z-keyword"> ]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>scheme =</span><span> ALPHA</span><span> *</span><span class="z-keyword">(</span><span> ALPHA</span><span class="z-keyword"> /</span><span> DIGIT</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-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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> See RFC 3986 for the fully contextualized</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> definition of &quot;scheme&quot;.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>domain =</span><span class="z-variable z-other"> authority</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> From RFC 3986:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> authority = [ userinfo &quot;@&quot; ] host [ &quot;:&quot; port ]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> See RFC 3986 for the fully contextualized</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> definition of &quot;authority&quot;.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>address =</span><span class="z-string"> &quot;</span><span class="z-string">0x</span><span class="z-string">&quot;</span><span> 40*40</span><span class="z-variable z-other">HEXDIG</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> Must also conform to capitalization</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> checksum encoding specified in EIP-55</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> where applicable (EOAs).</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>statement =</span><span> *</span><span class="z-keyword">(</span><span class="z-variable z-other"> reserved</span><span class="z-keyword"> /</span><span class="z-variable z-other"> unreserved</span><span class="z-keyword"> /</span><span class="z-string"> &quot;</span><span class="z-string"> &quot;</span><span class="z-keyword"> )</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> See RFC 3986 for the definition</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> of &quot;reserved&quot; and &quot;unreserved&quot;.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> The purpose is to exclude LF (line break).</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>uri =</span><span class="z-variable z-other"> URI</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> See RFC 3986 for the definition of &quot;URI&quot;.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>version =</span><span class="z-string"> &quot;</span><span class="z-string">1</span><span class="z-string">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>chain-id =</span><span> 1*</span><span>DIGIT</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> See EIP-155 for valid CHAIN_IDs.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>nonce =</span><span> 8*</span><span class="z-keyword">(</span><span> ALPHA</span><span class="z-keyword"> /</span><span> DIGIT</span><span class="z-keyword"> )</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> See RFC 5234 for the definition</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> of &quot;ALPHA&quot; and &quot;DIGIT&quot;.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>issued-at =</span><span class="z-variable z-other"> date-time</span></span> <span class="giallo-l"><span>expiration-time =</span><span class="z-variable z-other"> date-time</span></span> <span class="giallo-l"><span>not-before =</span><span class="z-variable z-other"> date-time</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> See RFC 3339 (ISO 8601) for the</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> definition of &quot;date-time&quot;.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>request-id =</span><span> *</span><span class="z-variable z-other">pchar</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ;</span><span class="z-comment"> See RFC 3986 for the definition of &quot;pchar&quot;.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>resources =</span><span> *</span><span class="z-keyword">(</span><span> LF</span><span class="z-variable z-other"> resource</span><span class="z-keyword"> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>resource =</span><span class="z-string"> &quot;</span><span class="z-string">- </span><span class="z-string">&quot;</span><span class="z-variable z-other"> URI</span></span></code></pre><h4 id="message-fields">Message Fields</h4> <p>This specification defines the following SIWE Message fields that can be parsed from a SIWE Message by following the rules in <a href="https://wg-eips.ritovision.com/4361/#abnf-message-format">ABNF Message Format</a>:</p> <ul> <li><code>scheme</code> OPTIONAL. The URI scheme of the origin of the request. Its value MUST be an RFC 3986 URI scheme.</li> <li><code>domain</code> REQUIRED. The domain that is requesting the signing. Its value MUST be an RFC 3986 authority. The authority includes an OPTIONAL port. If the port is not specified, the default port for the provided <code>scheme</code> is assumed (e.g., 443 for HTTPS). If <code>scheme</code> is not specified, HTTPS is assumed by default.</li> <li><code>address</code> REQUIRED. The Ethereum address performing the signing. Its value SHOULD be conformant to mixed-case checksum address encoding specified in <a href="https://wg-eips.ritovision.com/55/">ERC-55</a> where applicable.</li> <li><code>statement</code> OPTIONAL. A human-readable ASCII assertion that the user will sign which MUST NOT include <code>'\n'</code> (the byte <code>0x0a</code>).</li> <li><code>uri</code> REQUIRED. An RFC 3986 URI referring to the resource that is the subject of the signing (as in the <em>subject of a claim</em>).</li> <li><code>version</code> REQUIRED. The current version of the SIWE Message, which MUST be <code>1</code> for this specification.</li> <li><code>chain-id</code> REQUIRED. The <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> Chain ID to which the session is bound, and the network where Contract Accounts MUST be resolved.</li> <li><code>nonce</code> REQUIRED. A random string typically chosen by the relying party and used to prevent replay attacks, at least 8 alphanumeric characters.</li> <li><code>issued-at</code> REQUIRED. The time when the message was generated, typically the current time. Its value MUST be an <a rel="external" href="https://www.rfc-editor.org/rfc/rfc3339">RFC 3339</a> datetime string.</li> <li><code>expiration-time</code> OPTIONAL. The time when the signed authentication message is no longer valid. Its value MUST be an <a rel="external" href="https://www.rfc-editor.org/rfc/rfc3339">RFC 3339</a> datetime string.</li> <li><code>not-before</code> OPTIONAL. The time when the signed authentication message will become valid. Its value MUST be an <a rel="external" href="https://www.rfc-editor.org/rfc/rfc3339">RFC 3339</a> datetime string.</li> <li><code>request-id</code> OPTIONAL. A system-specific identifier that MAY be used to uniquely refer to the sign-in request.</li> <li><code>resources</code> OPTIONAL. A list of information or references to information the user wishes to have resolved as part of authentication by the relying party. Every resource MUST be an RFC 3986 URI separated by <code>"\n- "</code> where <code>\n</code> is the byte <code>0x0a</code>.</li> </ul> <h4 id="informal-message-template">Informal Message Template</h4> <p>A Bash-like informal template of the full SIWE Message is presented below for readability and ease of understanding, and it does not reflect the allowed optionality of the fields. Field descriptions are provided in the following section. A full ABNF description is provided in <a href="https://wg-eips.ritovision.com/4361/#abnf-message-format">ABNF Message Format</a>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>${scheme}:// ${domain} wants you to sign in with your Ethereum account:</span></span> <span class="giallo-l"><span>${address}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>${statement}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>URI: ${uri}</span></span> <span class="giallo-l"><span>Version: ${version}</span></span> <span class="giallo-l"><span>Chain ID: ${chain-id}</span></span> <span class="giallo-l"><span>Nonce: ${nonce}</span></span> <span class="giallo-l"><span>Issued At: ${issued-at}</span></span> <span class="giallo-l"><span>Expiration Time: ${expiration-time}</span></span> <span class="giallo-l"><span>Not Before: ${not-before}</span></span> <span class="giallo-l"><span>Request ID: ${request-id}</span></span> <span class="giallo-l"><span>Resources:</span></span> <span class="giallo-l"><span>- ${resources[0]}</span></span> <span class="giallo-l"><span>- ${resources[1]}</span></span> <span class="giallo-l"><span>...</span></span> <span class="giallo-l"><span>- ${resources[n]}</span></span></code></pre><h4 id="examples">Examples</h4> <p>The following is an example SIWE Message with an implicit scheme:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>example.com wants you to sign in with your Ethereum account:</span></span> <span class="giallo-l"><span>0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>I accept the ExampleOrg Terms of Service: https://example.com/tos</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>URI: https://example.com/login</span></span> <span class="giallo-l"><span>Version: 1</span></span> <span class="giallo-l"><span>Chain ID: 1</span></span> <span class="giallo-l"><span>Nonce: 32891756</span></span> <span class="giallo-l"><span>Issued At: 2021-09-30T16:25:24Z</span></span> <span class="giallo-l"><span>Resources:</span></span> <span class="giallo-l"><span>- ipfs://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/</span></span> <span class="giallo-l"><span>- https://example.com/my-web2-claim.json</span></span></code></pre> <p>The following is an example SIWE Message with an implicit scheme and explicit port:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>example.com:3388 wants you to sign in with your Ethereum account:</span></span> <span class="giallo-l"><span>0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>I accept the ExampleOrg Terms of Service: https://example.com/tos</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>URI: https://example.com/login</span></span> <span class="giallo-l"><span>Version: 1</span></span> <span class="giallo-l"><span>Chain ID: 1</span></span> <span class="giallo-l"><span>Nonce: 32891756</span></span> <span class="giallo-l"><span>Issued At: 2021-09-30T16:25:24Z</span></span> <span class="giallo-l"><span>Resources:</span></span> <span class="giallo-l"><span>- ipfs://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/</span></span> <span class="giallo-l"><span>- https://example.com/my-web2-claim.json</span></span></code></pre> <p>The following is an example SIWE Message with an explicit scheme:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>https://example.com wants you to sign in with your Ethereum account:</span></span> <span class="giallo-l"><span>0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>I accept the ExampleOrg Terms of Service: https://example.com/tos</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>URI: https://example.com/login</span></span> <span class="giallo-l"><span>Version: 1</span></span> <span class="giallo-l"><span>Chain ID: 1</span></span> <span class="giallo-l"><span>Nonce: 32891756</span></span> <span class="giallo-l"><span>Issued At: 2021-09-30T16:25:24Z</span></span> <span class="giallo-l"><span>Resources:</span></span> <span class="giallo-l"><span>- ipfs://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq/</span></span> <span class="giallo-l"><span>- https://example.com/my-web2-claim.json</span></span></code></pre><h3 id="signing-and-verifying-messages-with-ethereum-accounts">Signing and Verifying Messages with Ethereum Accounts</h3> <ul> <li> <p>For Externally Owned Accounts (EOAs), the verification method specified in <a href="https://wg-eips.ritovision.com/191/">ERC-191</a> MUST be used.</p> </li> <li> <p>For Contract Accounts,</p> <ul> <li>The verification method specified in <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> SHOULD be used, and if it is not, the implementer MUST clearly define the verification method to attain security and interoperability for both wallets and relying parties.</li> <li>When performing <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> signature verification, the contract performing the verification MUST be resolved from the specified <code>chain-id</code>.</li> <li>Implementers SHOULD take into consideration that <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> implementations are not required to be pure functions, and can return different results for the same inputs depending on blockchain state. This can affect the security model and session validation rules. For example, a service with <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> signing enabled could rely on webhooks to receive notifications when state affecting the results is changed. When it receives a notification, it invalidates any matching sessions.</li> </ul> </li> </ul> <h3 id="resolving-ethereum-name-service-ens-data">Resolving Ethereum Name Service (ENS) Data</h3> <ul> <li>The relying party or wallet MAY additionally perform resolution of ENS data, as this can improve the user experience by displaying human-friendly information that is related to the <code>address</code>. Resolvable ENS data include: <ul> <li>The <a href="https://wg-eips.ritovision.com/181/">primary ENS name</a>.</li> <li>The ENS avatar.</li> <li>Any other resolvable resources specified in the ENS documentation.</li> </ul> </li> <li>If resolution of ENS data is performed, implementers SHOULD take precautions to preserve user privacy and consent, as their <code>address</code> could be forwarded to third party services as part of the resolution process.</li> </ul> <h3 id="relying-party-implementer-steps">Relying Party Implementer Steps</h3> <h4 id="specifying-the-request-origin">Specifying the Request Origin</h4> <ul> <li>The <code>domain</code> and, if present, the <code>scheme</code>, in the SIWE Message MUST correspond to the origin from where the signing request was made. For instance, if the signing request is made within a cross-origin iframe embedded in a parent browser window, the <code>domain</code> (and, if present, the <code>scheme</code>) have to match the origin of the iframe, rather than the origin of the parent. This is crucial to prevent the iframe from falsely asserting the origin of one of its ancestor windows for security reasons. This behavior is enforced by conforming wallets.</li> </ul> <h4 id="verifying-a-signed-message">Verifying a signed Message</h4> <ul> <li>The SIWE Message MUST be checked for conformance to the ABNF Message Format in the previous sections, checked against expected values after parsing (e.g., <code>expiration-time</code>, <code>nonce</code>, <code>request-uri</code> etc.), and its signature MUST be checked as defined in <a href="https://wg-eips.ritovision.com/4361/#signing-and-verifying-messages-with-ethereum-accounts">Signing and Verifying Messages with Ethereum Accounts</a>.</li> </ul> <h4 id="creating-sessions">Creating Sessions</h4> <ul> <li>Sessions MUST be bound to the <code>address</code> and not to further resolved resources that can change.</li> </ul> <h4 id="interpreting-and-resolving-resources">Interpreting and resolving Resources</h4> <ul> <li>Implementers SHOULD ensure that URIs in the listed <code>resources</code> are human-friendly when expressed in plaintext form.</li> <li>The interpretation of the listed <code>resources</code> in the SIWE Message is out of scope of this specification.</li> </ul> <h3 id="wallet-implementer-steps">Wallet Implementer Steps</h3> <h4 id="verifying-the-message-format">Verifying the Message Format</h4> <ul> <li>The full SIWE message MUST be checked for conformance to the ABNF defined in <a href="https://wg-eips.ritovision.com/4361/#abnf-message-format">ABNF Message Format</a>.</li> <li>Wallet implementers SHOULD warn users if the substring <code>"wants you to sign in with your Ethereum account"</code> appears anywhere in an <a href="https://wg-eips.ritovision.com/191/">ERC-191</a> message signing request unless the message fully conforms to the format defined <a href="https://wg-eips.ritovision.com/4361/#abnf-message-format">ABNF Message Format</a>.</li> </ul> <h4 id="verifying-the-request-origin">Verifying the Request Origin</h4> <ul> <li>Wallet implementers MUST prevent phishing attacks by verifying the origin of the request against the <code>scheme</code> and <code>domain</code> fields in the SIWE Message. For example, when processing the SIWE message beginning with <code>"example.com wants you to sign in..."</code>, the wallet checks that the request actually originated from <code>https://example.com</code>.</li> <li>The origin SHOULD be read from a trusted data source such as the browser window or over WalletConnect (<a href="https://wg-eips.ritovision.com/1328/">ERC-1328</a>) sessions for comparison against the signing message contents.</li> <li>Wallet implementers MAY warn instead of rejecting the verification if the origin is pointing to localhost.</li> </ul> <p>The following is a RECOMMENDED algorithm for Wallets to conform with the requirements on request origin verification defined by this specification.</p> <p>The algorithm takes the following input variables:</p> <ul> <li>fields from the SIWE message.</li> <li><code>origin</code> of the signing request - in the case of a browser wallet implementation - the origin of the page which requested the signin via the provider.</li> <li><code>allowedSchemes</code> - a list of schemes allowed by the Wallet.</li> <li><code>defaultScheme</code> - a scheme to assume when none was provided. Wallet implementers in the browser SHOULD use <code>https</code>.</li> <li>developer mode indication - a setting deciding if certain risks should be a warning instead of rejection. Can be manually configured or derived from <code>origin</code> being localhost.</li> </ul> <p>The algorithm is described as follows:</p> <ul> <li>If <code>scheme</code> was not provided, then assign <code>defaultScheme</code> as <code>scheme</code>.</li> <li>If <code>scheme</code> is not contained in <code>allowedSchemes</code>, then the <code>scheme</code> is not expected and the Wallet MUST reject the request. Wallet implementers in the browser SHOULD limit the list of <code>allowedSchemes</code> to just <code>'https'</code> unless a developer mode is activated.</li> <li>If <code>scheme</code> does not match the scheme of <code>origin</code>, the Wallet SHOULD reject the request. Wallet implementers MAY show a warning instead of rejecting the request if a developer mode is activated. In that case the Wallet continues processing the request.</li> <li>If the <code>host</code> part of the <code>domain</code> and <code>origin</code> do not match, the Wallet MUST reject the request unless the Wallet is in developer mode. In developer mode the Wallet MAY show a warning instead and continues processing the request.</li> <li>If <code>domain</code> and <code>origin</code> have mismatching subdomains, the Wallet SHOULD reject the request unless the Wallet is in developer mode. In developer mode the Wallet MAY show a warning instead and continues processing the request.</li> <li>Let <code>port</code> be the port component of <code>domain</code>, and if no port is contained in <code>domain</code>, assign <code>port</code> the default port specified for the <code>scheme</code>.</li> <li>If <code>port</code> is not empty, then the Wallet SHOULD show a warning if the <code>port</code> does not match the port of <code>origin</code>.</li> <li>If <code>port</code> is empty, then the Wallet MAY show a warning if <code>origin</code> contains a specific port. (Note 'https' has a default port of 443 so this only applies if <code>allowedSchemes</code> contain unusual schemes)</li> <li>Return request origin verification completed.</li> </ul> <h4 id="creating-sign-in-with-ethereum-interfaces">Creating Sign-In with Ethereum Interfaces</h4> <ul> <li>Wallet implementers MUST display to the user the following fields from the SIWE Message request by default and prior to signing, if they are present: <code>scheme</code>, <code>domain</code>, <code>address</code>, <code>statement</code>, and <code>resources</code>. Other present fields MUST also be made available to the user prior to signing either by default or through an extended interface.</li> <li>Wallet implementers displaying a plaintext SIWE Message to the user SHOULD require the user to scroll to the bottom of the text area prior to signing.</li> <li>Wallet implementers MAY construct a custom SIWE user interface by parsing the ABNF terms into data elements for use in the interface. The display rules above still apply to custom interfaces.</li> </ul> <h4 id="supporting-internationalization-i18n">Supporting internationalization (i18n)</h4> <ul> <li>After successfully parsing the message into ABNF terms, translation MAY happen at the UX level per human language.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="requirements">Requirements</h3> <p>Write a specification for how Sign-In with Ethereum should work. The specification should be simple and generally follow existing practices. Avoid feature bloat, particularly the inclusion of lesser-used projects who see getting into the specification as a means of gaining adoption. The core specification should be decentralized, open, non-proprietary, and have long-term viability. It should have no dependence on a centralized server except for the servers already being run by the application that the user is signing in to. The basic specification should include: Ethereum accounts used for authentication, ENS names for usernames (via reverse resolution), and data from the ENS name’s text records for additional profile information (e.g. avatar, social media handles, etc).</p> <p>Additional functional requirements:</p> <ol> <li>The user must be presented a human-understandable interface prior to signing, mostly free of machine-targeted artifacts such as JSON blobs, hex codes (aside from the Ethereum address), and baseXX-encoded strings.</li> <li>The application server must be able to implement fully usable support for its end without forcing a change in the wallets.</li> <li>There must be a simple and straightforward upgrade path for both applications and wallets already using Ethereum account-based signing for authentication.</li> <li>There must be facilities and guidelines for adequate mitigation of Man-in-the-Middle (MITM) attacks, replay attacks, and malicious signing requests.</li> </ol> <h3 id="design-goals">Design Goals</h3> <ol> <li>Human-Friendly</li> <li>Simple to Implement</li> <li>Secure</li> <li>Machine Readable</li> <li>Extensible</li> </ol> <h3 id="technical-decisions">Technical Decisions</h3> <ul> <li> <p>Why <a href="https://wg-eips.ritovision.com/191/">ERC-191</a> (Signed Data Standard) over <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> (Ethereum typed structured data hashing and signing)</p> <ul> <li> <p><a href="https://wg-eips.ritovision.com/191/">ERC-191</a> is already broadly supported across wallets UX, while <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> support for friendly user display is pending. <strong>(1, 2, 3, 4)</strong></p> </li> <li> <p><a href="https://wg-eips.ritovision.com/191/">ERC-191</a> is simple to implement using a pre-set prefix prior to signing, while <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> is more complex to implement requiring the further implementations of a bespoke Solidity-inspired type system, RLP-based encoding format, and custom keccak-based hashing scheme. <strong>(2)</strong></p> </li> <li> <p><a href="https://wg-eips.ritovision.com/191/">ERC-191</a> produces more human-readable messages, while <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> creates signing outputs for machine consumption, with most wallets not displaying the payload to be signed in a manner friendly to humans. <strong>(1)</strong><img src="https://wg-eips.ritovision.com/4361/./assets/signing.png" alt="" /></p> </li> <li> <p><a href="https://wg-eips.ritovision.com/712/">EIP-712</a> has the advantage of on-chain representation and on-chain verifiability, such as for their use in metatransactions, but this feature is not relevant for the specification's scope. <strong>(2)</strong></p> </li> </ul> </li> <li> <p>Why not use JWTs? Wallets don't support JWTs. The keccak hash function is not assigned by IANA for use as a JOSE algorithm. <strong>(2, 3)</strong></p> </li> <li> <p>Why not use YAML or YAML with exceptions? YAML is loose compared to ABNF, which can readily express character set limiting, required ordering, and strict whitespacing. <strong>(2, 3)</strong></p> </li> </ul> <h3 id="out-of-scope">Out of Scope</h3> <p>The following concerns are out of scope for this version of the specification to define:</p> <ul> <li>Additional authentication not based on Ethereum addresses.</li> <li>Authorization to server resources.</li> <li>Interpretation of the URIs in the <code>resources</code> field as claims or other resources.</li> <li>The specific mechanisms to ensure domain-binding.</li> <li>The specific mechanisms to generate nonces and evaluation of their appropriateness.</li> <li>Protocols for use without TLS connections.</li> </ul> <h3 id="considerations-for-forwards-compatibility">Considerations for Forwards Compatibility</h3> <p>The following items are considered for future support either through an iteration of this specification or new work items using this specification as a dependency.</p> <ul> <li>Possible support for Decentralized Identifiers and Verifiable Credentials.</li> <li>Possible cross-chain support.</li> <li>Possible SIOPv2 support.</li> <li>Possible future support for <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>.</li> <li>Version interpretation rules, e.g., sign with minor revision greater than understood, but not greater major version.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <ul> <li>Most wallet implementations already support <a href="https://wg-eips.ritovision.com/191/">ERC-191</a>, so this is used as a base pattern with additional features.</li> <li>Requirements were gathered from existing implementations of similar sign-in workflows, including statements to allow the user to accept a Terms of Service, nonces for replay protection, and inclusion of the Ethereum address itself in the message.</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>A reference implementation is available <a href="https://wg-eips.ritovision.com/4361/./assets/example.js">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="identifier-reuse">Identifier Reuse</h3> <ul> <li>Towards perfect privacy, it would be ideal to use a new uncorrelated identifier (e.g., Ethereum address) per digital interaction, selectively disclosing the information required and no more.</li> <li>This concern is less relevant to certain user demographics who are likely to be early adopters of this specification, such as those who manage an Ethereum address and/or ENS names intentionally associated with their public presence. These users often prefer identifier reuse to maintain a single correlated identity across many services.</li> <li>This consideration will become increasingly important with mainstream adoption. There are several ways to move towards this model, such as using HD wallets, signed delegations, and zero-knowledge proofs. However, these approaches are out of scope for this specification and better suited for follow-on specifications.</li> </ul> <h3 id="key-management">Key Management</h3> <ul> <li>Sign-In with Ethereum gives users control through their keys. This is additional responsibility that mainstream users may not be accustomed to accepting, and key management is a hard problem especially for individuals. For example, there is no "forgot password" button as centralized identity providers commonly implement.</li> <li>Early adopters of this specification are likely to be already adept at key management, so this consideration becomes more relevant with mainstream adoption.</li> <li>Certain wallets can use smart contracts and multisigs to provide an enhanced user experience with respect to key usage and key recovery, and these can be supported via <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> signing.</li> </ul> <h3 id="wallet-and-relying-party-combined-security">Wallet and Relying Party combined Security</h3> <ul> <li>Both the wallet and relying party have to implement this specification for improved security to the end user. Specifically, the wallet has to confirm that the SIWE Message is for the correct request origin or provide the user means to do so manually (such as instructions to visually confirming the correct domain in a TLS-protected website prior to connecting via QR code or deeplink), otherwise the user is subject to phishing attacks.</li> </ul> <h3 id="minimizing-wallet-and-server-interaction">Minimizing Wallet and Server Interaction</h3> <ul> <li>In some implementations of wallet sign-in workflows, the server first sends parameters of the SIWE Message to the wallet. Others generate the SIWE message for signing entirely in the client side (e.g., dapps). The latter approach without initial server interaction SHOULD be preferred when there is a user privacy advantage by minimizing wallet-server interaction. Often, the backend server first produces a <code>nonce</code> to prevent replay attacks, which it verifies after signing. Privacy-preserving alternatives are suggested in the next section on preventing replay attacks.</li> <li>Before the wallet presents the SIWE message signing request to the user, it MAY consult the server for the proper contents of the message to be signed, such as an acceptable <code>nonce</code> or requested set of <code>resources</code>. When communicating to the server, the wallet SHOULD take precautions to protect user privacy by mitigating user information revealed as much as possible.</li> <li>Prior to signing, the wallet MAY consult the user for preferences, such as the selection of one <code>address</code> out of many, or a preferred ENS name out of many.</li> </ul> <h3 id="preventing-replay-attacks">Preventing Replay Attacks</h3> <ul> <li>A <code>nonce</code> SHOULD be selected per session initiation with enough entropy to prevent replay attacks, a man-in-the-middle attack in which an attacker is able to capture the user's signature and resend it to establish a new session for themselves.</li> <li>Implementers MAY consider using privacy-preserving yet widely-available <code>nonce</code> values, such as one derived from a recent Ethereum block hash or a recent Unix timestamp.</li> </ul> <h3 id="preventing-phishing-attacks">Preventing Phishing Attacks</h3> <ul> <li>To prevent phishing attacks Wallets have to implement request origin verification as described in <a href="https://wg-eips.ritovision.com/4361/#verifying-the-request-origin">Verifying the Request Origin</a>.</li> </ul> <h3 id="channel-security">Channel Security</h3> <ul> <li>For web-based applications, all communications SHOULD use HTTPS to prevent man-in-the-middle attacks on the message signing.</li> <li>When using protocols other than HTTPS, all communications SHOULD be protected with proper techniques to maintain confidentiality, data integrity, and sender/receiver authenticity.</li> </ul> <h3 id="session-invalidation">Session Invalidation</h3> <p>There are several cases where an implementer SHOULD check for state changes as they relate to sessions.</p> <ul> <li>If an <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> implementation or dependent data changes the signature computation, the server SHOULD invalidate sessions appropriately.</li> <li>If any resources specified in <code>resources</code> change, the server SHOULD invalidate sessions appropriately. However, the interpretation of <code>resources</code> is out of scope of this specification.</li> </ul> <h3 id="maximum-lengths-for-abnf-terms">Maximum Lengths for ABNF Terms</h3> <ul> <li>While this specification does not contain normative requirements around maximum string lengths, implementers SHOULD choose maximum lengths for terms that strike a balance across the prevention of denial of service attacks, support for arbitrary use cases, and user readability.</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-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-05T00:00:00+00:00 2026-02-11T14:49:27+00:00 Tim Beikohttps://github.com/timbeiko James Hancockhttps://github.com/MadeOfTin Thomas Jay Rushhttps://github.com/tjayrush https://wg-eips.ritovision.com/4345/

Delays the difficulty bomb to be noticeable in June 2022.

<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 10,700,000 blocks later than the actual block number.</p> <h2 id="motivation">Motivation</h2> <p>Targeting for The Merge to occur before June 2022. If it is not ready by then, the bomb can be delayed further.</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="python"><span class="giallo-l"><span> fake_block_number</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span class="z-constant">0</span><span>,</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> -</span><span class="z-constant"> 10_700_000</span><span>)</span><span class="z-keyword"> if</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> FORK_BLOCK_NUMBER</span><span class="z-keyword"> else</span><span> block</span><span>.</span><span>number</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The following script predicts a ~0.1 second delay to block time by June 2022 and a ~0.5 second delay by July 2022. This gives reason to address because the effect will be seen, but not so much urgency we don't have space to work around if needed.</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"> predict_diff_bomb_effect</span><span>(</span><span class="z-variable z-parameter z-function">current_blknum</span><span>,</span><span class="z-variable z-parameter z-function"> current_difficulty</span><span>,</span><span class="z-variable z-parameter z-function"> block_adjustment</span><span>,</span><span class="z-variable z-parameter z-function"> months</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;&#39;&#39;</span></span> <span class="giallo-l"><span class="z-string"> Predicts the effect on block time (as a ratio) in a specified amount of months in the future.</span></span> <span class="giallo-l"><span class="z-string"> Vars used for predictions:</span></span> <span class="giallo-l"><span class="z-string"> current_blknum = 13423376 # Oct 15, 2021</span></span> <span class="giallo-l"><span class="z-string"> current_difficulty = 9545154427582720</span></span> <span class="giallo-l"><span class="z-string"> block adjustment = 10700000</span></span> <span class="giallo-l"><span class="z-string"> months = 7.5 # June 2022</span></span> <span class="giallo-l"><span class="z-string"> months = 8.5 # July 2022</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;&#39;&#39;</span></span> <span class="giallo-l"><span> blocks_per_month</span><span class="z-keyword"> =</span><span> (</span><span class="z-constant">86400</span><span class="z-keyword"> *</span><span class="z-constant"> 30</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> 13.3</span></span> <span class="giallo-l"><span> future_blknum</span><span class="z-keyword"> =</span><span> current_blknum</span><span class="z-keyword"> +</span><span> blocks_per_month</span><span class="z-keyword"> *</span><span> months</span></span> <span class="giallo-l"><span> diff_adjustment</span><span class="z-keyword"> =</span><span class="z-constant"> 2</span><span class="z-keyword"> **</span><span> (</span><span>(</span><span>future_blknum</span><span class="z-keyword"> -</span><span> block_adjustment</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> 100000</span><span class="z-keyword"> -</span><span class="z-constant"> 2</span><span>)</span></span> <span class="giallo-l"><span> diff_adjust_coeff</span><span class="z-keyword"> =</span><span> diff_adjustment</span><span class="z-keyword"> /</span><span> current_difficulty</span><span class="z-keyword"> *</span><span class="z-constant"> 2048</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> diff_adjust_coeff</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>diff_adjust_coeff</span><span class="z-keyword"> =</span><span> predict_diff_bomb_effect</span><span>(</span><span class="z-constant">13423376</span><span>,</span><span class="z-constant">9545154427582720</span><span>,</span><span class="z-constant">10700000</span><span>,</span><span class="z-constant">7.5</span><span>)</span></span> <span class="giallo-l"><span>diff_adjust_coeff</span><span class="z-keyword"> =</span><span> predict_diff_bomb_effect</span><span>(</span><span class="z-constant">13423376</span><span>,</span><span class="z-constant">9545154427582720</span><span>,</span><span class="z-constant">10700000</span><span>,</span><span class="z-constant">8.5</span><span>)</span></span></code></pre><h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No known backward compatibility issues.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Misjudging the effects of the difficulty can mean longer blocktimes than anticipated until a hardfork is released. Wild shifts in difficulty can affect this number severely. Also, gradual changes in blocktimes due to longer-term adjustments in difficulty can affect the timing of difficulty bomb epochs. This affects the usability of the network but unlikely to have security ramifications.</p> <p>In this specific instance, it is possible that the network hashrate drops considerably before The Merge, which could accelerate the timeline by which the bomb is felt in block times. The offset value chosen aimed to take this into 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> 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-29T00:00:00+00:00 2026-02-11T14:48:26+00:00 Vitalik Buterinhttps://github.com/vbuterin Yoav Weisshttps://github.com/yoavw Dror Tiroshhttps://github.com/drortirosh Shahaf Nacsonhttps://github.com/shahafn Alex Forshtathttps://github.com/forshtat Kristof Gazsohttps://github.com/kristofgazso Tjaden Hesshttps://github.com/tjade273 https://wg-eips.ritovision.com/4337/

Account abstraction without consensus-layer protocol changes, instead relying on higher-layer infrastructure.

<h2 id="abstract">Abstract</h2> <p>An account abstraction proposal which completely avoids the need for consensus-layer protocol changes. Instead of adding new protocol features and changing the bottom-layer transaction type, this proposal instead introduces a higher-layer pseudo-transaction object called a <code>UserOperation</code>. Users send <code>UserOperation</code> objects into a separate mempool. A special class of actor called bundlers package up a set of these objects into a transaction making a <code>handleOps</code> call to a special contract, and that transaction then gets included in a block.</p> <h2 id="motivation">Motivation</h2> <p>Historically, introducing Account Abstraction has been a long-standing goal of the Ethereum protocol. A number of proposals have been thoroughly discussed, but so far none of them have been implemented in the protocol.</p> <p>This proposal takes a different approach, avoiding any adjustments to the consensus layer. It seeks to achieve the following goals:</p> <ul> <li><strong>Achieve the key goal of Account Abstraction</strong>: allow users to use Smart Contract Accounts containing arbitrary verification logic instead of EOAs as their primary account. Completely remove any need at all for users to also have EOAs, as required by both status quo Smart Contract Accounts and <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>.</li> <li><strong>Decentralization</strong> <ul> <li>Allow any bundler (think: block builder) to participate in the process of including account-abstracted <code>UserOperations</code></li> <li>Work with all activity happening over a public mempool; users do not need to know the direct communication addresses (eg. IP, onion) of any specific actors</li> <li>Avoid trust assumptions on bundlers</li> </ul> </li> <li><strong>Do not require any Ethereum consensus changes</strong>: Ethereum consensus layer development is focusing on scalability-oriented features, and there may not be any opportunity for further protocol changes for a long time. Hence, to increase the chance of faster adoption, this proposal avoids Ethereum consensus changes.</li> <li><strong>Support other use cases</strong> <ul> <li>Privacy-preserving applications</li> <li>Atomic multi-operations (similar goal to <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>)</li> <li>Pay tx fees with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens, allow developers to pay fees for their users, and <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>-like <strong>sponsored transaction</strong> use cases more generally</li> <li>abstracting the validation allows the contract to use different signature schemes, multisig configuration, custom recovery, and more.</li> <li>abstracting gas payments allows easy onboarding by 3rd party payments, paying with tokens, cross-chain gas payments</li> <li>abstracting execution allows bundled transactions</li> </ul> </li> </ul> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions</h3> <ul> <li><strong>UserOperation</strong> - a structure that describes a transaction to be sent on behalf of a user. To avoid confusion, it is not named "transaction". <ul> <li>Like a transaction, it contains <code>to</code>, <code>calldata</code>, <code>maxFeePerGas</code>, <code>maxPriorityFeePerGas</code>, <code>nonce</code>, <code>signature</code>.</li> <li>Unlike a transaction, it contains several other fields, described below.</li> <li>Notably, the <code>signature</code> field usage is not defined by the protocol, but by the Smart Contract Account implementation.</li> </ul> </li> <li><strong>Sender</strong> - the Smart Contract Account sending a <code>UserOperation</code>.</li> <li><strong>EntryPoint</strong> - a singleton contract to execute bundles of <code>UserOperations</code>. Bundlers should whitelist the supported <code>EntryPoint</code>.</li> <li><strong>Bundler</strong> - a node (block builder) that can handle <code>UserOperations</code>, create a valid <code>entryPoint.handleOps()</code> transaction, and add it to the block while it is still valid. This can be achieved by a number of ways: <ul> <li>Bundler can act as a block builder itself.</li> <li>If the bundler is not a block builder, it should work with the block builder through an infrastructure such as <code>mev-boost</code>, or any other kind of proposer-builder separation.</li> </ul> </li> <li><strong>Paymaster</strong> - a helper contract that agrees to pay for the transaction, instead of the sender itself.</li> <li><strong>Factory</strong> - a helper contract that performs a deployment for a new <code>sender</code> contract if necessary.</li> <li><strong>Aggregator</strong> - also known as "authorizer contract" - a contract that enables multiple <code>UserOperations</code> to share a single validation. The full design of such contracts is outside the scope of this proposal.</li> <li><strong>Canonical <code>UserOperation</code> mempool</strong> - a decentralized permissionless P2P network where bundlers exchange <code>UserOperations</code> that are valid and conform with the same shared set of rules applied to the validation code. The full specification of such rules is outside the scope of this proposal.</li> <li><strong>Alternative <code>UserOperation</code> mempool</strong> - any other P2P mempool where the validity of <code>UserOperations</code> is determined by rules that are different from the shared set of rules, applied to the validation code, in any way.</li> <li><strong>Deposit</strong> - an amount of Ether (or any L2 native currency) that a <code>Sender</code> or <code>Paymaster</code> contract has transferred to the <code>EntryPoint</code> contract intended to pay gas costs of the future <code>UserOperations</code>.</li> </ul> <h3 id="the-useroperation-structure">The <code>UserOperation</code> structure</h3> <p>To avoid Ethereum consensus changes, we do not attempt to create new transaction types for account-abstracted transactions. Instead, users package up the action they want their Smart Contract Account to take in a struct named <code>UserOperation</code>:</p> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td><code>sender</code></td><td><code>address</code></td><td>The Account making the <code>UserOperation</code></td></tr> <tr><td><code>nonce</code></td><td><code>uint256</code></td><td>Anti-replay parameter (see "Semi-abstracted Nonce Support" )</td></tr> <tr><td><code>factory</code></td><td><code>address</code></td><td>Account Factory for new Accounts OR <code>0x7702</code> flag for EIP-7702 Accounts, otherwise <code>address(0)</code></td></tr> <tr><td><code>factoryData</code></td><td><code>bytes</code></td><td>data for the Account Factory if <code>factory</code> is provided OR EIP-7702 initialization data, or empty array</td></tr> <tr><td><code>callData</code></td><td><code>bytes</code></td><td>The data to pass to the <code>sender</code> during the main execution call</td></tr> <tr><td><code>callGasLimit</code></td><td><code>uint256</code></td><td>The amount of gas to allocate the main execution call</td></tr> <tr><td><code>verificationGasLimit</code></td><td><code>uint256</code></td><td>The amount of gas to allocate for the verification step</td></tr> <tr><td><code>preVerificationGas</code></td><td><code>uint256</code></td><td>Extra gas to pay the bundler</td></tr> <tr><td><code>maxFeePerGas</code></td><td><code>uint256</code></td><td>Maximum fee per gas (similar to <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> <code>max_fee_per_gas</code>)</td></tr> <tr><td><code>maxPriorityFeePerGas</code></td><td><code>uint256</code></td><td>Maximum priority fee per gas (similar to EIP-1559 <code>max_priority_fee_per_gas</code>)</td></tr> <tr><td><code>paymaster</code></td><td><code>address</code></td><td>Address of paymaster contract, (or empty, if the <code>sender</code> pays for gas by itself)</td></tr> <tr><td><code>paymasterVerificationGasLimit</code></td><td><code>uint256</code></td><td>The amount of gas to allocate for the paymaster validation code (only if paymaster exists)</td></tr> <tr><td><code>paymasterPostOpGasLimit</code></td><td><code>uint256</code></td><td>The amount of gas to allocate for the paymaster post-operation code (only if paymaster exists)</td></tr> <tr><td><code>paymasterData</code></td><td><code>bytes</code></td><td>Data for paymaster (only if paymaster exists)</td></tr> <tr><td><code>signature</code></td><td><code>bytes</code></td><td>Data passed into the <code>sender</code> to verify authorization</td></tr> </tbody></table> <p>Users send <code>UserOperation</code> objects to a dedicated <code>UserOperation</code> mempool.</p> <p>To prevent replay attacks, either cross-chain or with multiple <code>EntryPoint</code> contract versions, the <code>signature</code> MUST depend on <code>chainid</code> and the <code>EntryPoint</code> address.</p> <p>Note that one <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> "authorization tuple" value can be provided alongside the <code>UserOperation</code> struct, but "authorization tuples" are not included in the <code>UserOperation</code> itself.</p> <h3 id="entrypoint-interface"><code>EntryPoint</code> interface</h3> <p>When passed on-chain, to the <code>EntryPoint</code> contract, the <code>Account</code> and the <code>Paymaster</code>, a "packed" version of the above structure called <code>PackedUserOperation</code> is used:</p> <table><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td><code>sender</code></td><td><code>address</code></td><td></td></tr> <tr><td><code>nonce</code></td><td><code>uint256</code></td><td></td></tr> <tr><td><code>initCode</code></td><td><code>bytes</code></td><td>concatenation of factory address and factoryData (or empty), or <a href="https://wg-eips.ritovision.com/4337/#support-for-eip-7702-authorizations">EIP-7702 data</a></td></tr> <tr><td><code>callData</code></td><td><code>bytes</code></td><td></td></tr> <tr><td><code>accountGasLimits</code></td><td><code>bytes32</code></td><td>concatenation of verificationGasLimit (16 bytes) and callGasLimit (16 bytes)</td></tr> <tr><td><code>preVerificationGas</code></td><td><code>uint256</code></td><td></td></tr> <tr><td><code>gasFees</code></td><td><code>bytes32</code></td><td>concatenation of maxPriorityFeePerGas (16 bytes) and maxFeePerGas (16 bytes)</td></tr> <tr><td><code>paymasterAndData</code></td><td><code>bytes</code></td><td>concatenation of paymaster fields (or empty)</td></tr> <tr><td><code>signature</code></td><td><code>bytes</code></td><td></td></tr> </tbody></table> <p>The core interface of the <code>EntryPoint</code> contract 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"> handleOps</span><span>(</span><span class="z-storage z-type">PackedUserOperation</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> ops</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> payable</span><span class="z-variable"> beneficiary</span><span>)</span><span>;</span></span></code></pre> <p>The <code>beneficiary</code> is the address that will be paid with all the gas fees collected during the execution of the bundle.</p> <h3 id="smart-contract-account-interface">Smart Contract Account Interface</h3> <p>The core interface required for the Smart Contract Account to have is:</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"> IAccount</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> validateUserOp</span></span> <span class="giallo-l"><span> (</span><span class="z-entity z-name">PackedUserOperation</span><span class="z-storage z-type"> calldata</span><span class="z-entity z-name"> userOp</span><span>,</span><span class="z-entity z-name"> bytes32</span><span class="z-entity z-name"> userOpHash</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> missingAccountFunds</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">uint256</span><span class="z-variable"> validationData</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>userOpHash</code> is a hash over the <code>userOp</code> (except <code>signature</code>), <code>entryPoint</code> and <code>chainId</code>.</p> <p>The Smart Contract Account:</p> <ul> <li>MUST validate the caller is a trusted <code>EntryPoint</code></li> <li>MUST validate that the signature is a valid signature of the <code>userOpHash</code>, and SHOULD return <code>SIG_VALIDATION_FAILED</code> (<code>1</code>) without reverting on signature mismatch. Any other error MUST revert.</li> <li>SHOULD not return early when returning <code>SIG_VALIDATION_FAILED</code> (<code>1</code>). Instead, it SHOULD complete the normal flow to enable performing a gas estimation for the validation function.</li> <li>MUST pay the <code>EntryPoint</code> (caller) at least the <code>missingAccountFunds</code> (which might be zero, in case the current <code>sender</code>'s deposit is sufficient)</li> <li>The <code>sender</code> MAY pay more than this minimum to cover future transactions. It can also call <code>withdrawTo</code> to retrieve it later at any time.</li> <li>The return value MUST be packed of <code>aggregator</code>/<code>authorizer</code>, <code>validUntil</code> and <code>validAfter</code> timestamps. <ul> <li><code>aggregator</code>/<code>authorizer</code> - 0 for valid signature, 1 to mark signature failure. Otherwise, an address of an <code>aggregator</code>/<code>authorizer</code> contract.</li> <li><code>validUntil</code> is 6-byte timestamp value, or zero for "infinite". The <code>UserOperation</code> is valid only up to this time.</li> <li><code>validAfter</code> is 6-byte timestamp. The <code>UserOperation</code> is valid only after this time.</li> <li>In order to specify a validity range using block numbers, both the <code>validUntil</code> and <code>validAfter</code> need to set their highest bit to 1.</li> <li><strong>Note:</strong> The validity range can be expressed by two block timestamps or two block numbers, but one timestamp and one block number cannot be mixed in the same UserOperation's validity range.</li> </ul> </li> </ul> <p>The Smart Contract Account MAY implement the interface <code>IAccountExecute</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"> IAccountExecute</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> executeUserOp</span><span>(</span><span class="z-storage z-type">PackedUserOperation</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> userOp</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> userOpHash</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This method will be called by the <code>EntryPoint</code> with the current UserOperation, instead of executing the <code>callData</code> itself directly on the <code>sender</code>.</p> <h3 id="semi-abstracted-nonce-support">Semi-abstracted Nonce Support</h3> <p>In Ethereum protocol, the sequential transaction <code>nonce</code> value is used as a replay protection method as well as to determine the valid order of transaction being included in blocks.</p> <p>It also contributes to the transaction hash uniqueness, as a transaction by the same sender with the same nonce may not be included in the chain twice.</p> <p>However, requiring a single sequential <code>nonce</code> value is limiting to the senders' ability to define their custom logic with regard to transaction ordering and replay protection.</p> <p>Instead of sequential <code>nonce</code> we implement a nonce mechanism that uses a single <code>uint256</code> nonce value in the <code>UserOperation</code>, but treats it as two values:</p> <ul> <li>192-bit "key"</li> <li>64-bit "sequence"</li> </ul> <p>These values are represented on-chain in the <code>EntryPoint</code> contract. We define the following method in the <code>EntryPoint</code> interface to expose these values:</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"> getNonce</span><span>(</span><span class="z-support">address</span><span class="z-variable"> sender</span><span>,</span><span class="z-support"> uint192</span><span class="z-variable"> key</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"> nonce</span><span>)</span><span>;</span></span></code></pre> <p>For each <code>key</code> the <code>sequence</code> is validated by the <code>EntryPoint</code> for each UserOperation. If the nonce validation fails the <code>UserOperation</code> is considered invalid and the bundle is reverted. The <code>sequence</code> value is incremented sequentially and monotonically for the <code>sender</code> for each UserOperation. A new <code>key</code> can be introduced with an arbitrary value at any point, with its <code>sequence</code> starting at <code>0</code>.</p> <p>This approach maintains the guarantee of <code>UserOperation</code> hash uniqueness on-chain on the protocol level while allowing Accounts to implement any custom logic they may need operating on a 192-bit "key" field, while fitting the 32 byte word.</p> <h4 id="reading-and-validating-the-nonce">Reading and validating the nonce</h4> <p>When preparing the <code>UserOperation</code> bundlers may make a view call to this method to determine a valid value for the <code>nonce</code> field.</p> <p>Bundler's validation of a <code>UserOperation</code> SHOULD start with <code>getNonce</code> to ensure the transaction has a valid <code>nonce</code> field.</p> <p>If the bundler is willing to accept multiple <code>UserOperations</code> by the same sender into their mempool, this bundler is supposed to track the <code>key</code> and <code>sequence</code> pair of the <code>UserOperations</code> already added in the mempool.</p> <h4 id="usage-examples">Usage examples</h4> <ol> <li> <p>Classic sequential nonce.</p> <p>In order to require the Account to have classic, sequential nonce, the validation function MUST perform:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">require</span><span>(</span><span>userOp</span><span>.</span><span>nonce</span><span class="z-keyword">&lt;</span><span class="z-variable z-language">type</span><span>(</span><span class="z-support">uint64</span><span>)</span><span>.</span><span>max</span><span>)</span></span></code></pre></li> <li> <p>Ordered administrative events</p> <p>In some cases, an account may need to have an "administrative" channel of operations running in parallel to normal operations.</p> <p>In this case, the account may use a specific <code>key</code> when calling methods on the account itself:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes4</span><span> sig </span><span class="z-keyword">=</span><span class="z-support"> bytes4</span><span>(</span><span>userOp</span><span>.</span><span>callData</span><span>[</span><span class="z-constant">0</span><span class="z-keyword"> :</span><span class="z-constant"> 4</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint</span><span> key </span><span class="z-keyword">=</span><span> userOp</span><span>.</span><span>nonce </span><span class="z-keyword">&gt;&gt;</span><span class="z-constant"> 64</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">if</span><span> (</span><span>sig </span><span class="z-keyword">==</span><span> ADMIN_METHODSIG</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>key </span><span class="z-keyword">==</span><span> ADMIN_KEY</span><span>,</span><span class="z-string"> &quot;wrong nonce-key for admin operation&quot;</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"> require</span><span>(</span><span>key </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;wrong nonce-key for normal operation&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre></li> </ol> <h3 id="required-entrypoint-contract-functionality">Required <code>EntryPoint</code> contract functionality</h3> <p>The <code>EntryPoint</code> method is <code>handleOps</code>, which handles an array of <code>UserOperations</code></p> <p>The <code>EntryPoint</code>'s <code>handleOps</code> function must perform the following steps (we first describe the simpler non-paymaster case). It must make two loops, the <strong>verification loop</strong> and the <strong>execution loop</strong>. In the verification loop, the <code>handleOps</code> call must perform the following steps for each <code>UserOperation</code>:</p> <ul> <li><strong>Create the <code>sender</code> Smart Contract Account if it does not yet exist</strong>, using the <code>initcode</code> provided in the <code>UserOperation</code>. <ul> <li>If the <code>factory</code> address is "0x7702", then the sender MUST be an EOA with an <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> authorization designation. The <code>EntryPoint</code> validates the authorized address matches the one specified in the <code>UserOperation</code> signature (see <a href="https://wg-eips.ritovision.com/4337/#support-for-eip-7702-authorizations">Support for [EIP-7702] authorizations</a>).</li> <li>If the <code>sender</code> does not exist, <em>and</em> the <code>initcode</code> is empty, or does not deploy a contract at the "sender" address, the call must fail.</li> <li><strong>WARNING</strong>: If the <code>sender</code> does exist, <em>and</em> the <code>initcode</code> is <em>not</em> empty, then the <code>initcode</code> is ignored.</li> </ul> </li> <li>calculate the maximum possible fee the <code>sender</code> needs to pay based on validation and call gas limits, and current gas values.</li> <li>calculate the fee the <code>sender</code> must add to its "deposit" in the <code>EntryPoint</code></li> <li><strong>Call <code>validateUserOp</code> on the <code>sender</code> contract</strong>, passing in the <code>UserOperation</code>, its hash and the required fee. The Smart Contract Account MUST verify the <code>UserOperation</code>'s <code>signature</code> parameter, and pay the fee if the <code>sender</code> considers the <code>UserOperation</code> valid. If any <code>validateUserOp</code> call fails, <code>handleOps</code> must skip execution of at least that <code>UserOperation</code>, and may revert entirely.</li> <li>Validate the account's deposit in the <code>EntryPoint</code> is high enough to cover the max possible cost (cover the already-done verification and max execution gas)</li> </ul> <p>In the execution loop, the <code>handleOps</code> call must perform the following steps for each <code>UserOperation</code>:</p> <ul> <li><strong>Call the account with the <code>UserOperation</code>'s calldata</strong>. It's up to the account to choose how to parse the calldata; an expected workflow is for the account to have an <code>execute</code> function that parses the remaining calldata as a series of one or more calls that the account should make.</li> <li>If the calldata starts with the methodsig <code>IAccountExecute.executeUserOp</code>, then the <code>EntryPoint</code> must build a calldata by encoding <code>executeUserOp(userOp,userOpHash)</code> and call the account using that calldata.</li> <li>After the call, refund the account's deposit with the excess gas cost that was pre-charged.<br /> A penalty of <code>10%</code> (<code>UNUSED_GAS_PENALTY_PERCENT</code>) is applied on the amounts of <code>callGasLimit</code> and <code>paymasterPostOpGasLimit</code> gas that remains <strong>unused</strong>.<br /> This penalty is only applied if the amount of the remaining unused gas is greater than or equal <code>40000</code> (<code>PENALTY_GAS_THRESHOLD</code>).<br /> This penalty is necessary to prevent the <code>UserOperations</code> from reserving large parts of the gas space in the bundle but leaving it unused and preventing the bundler from including other <code>UserOperations</code>.</li> <li>After the execution of all calls, pay the collected fees from all <code>UserOperations</code> to the <code>beneficiary</code> address provided by the bundler.</li> </ul> <p><img src="https://wg-eips.ritovision.com/4337/./assets/bundle-seq.svg" alt="" /></p> <p>Before accepting a <code>UserOperation</code>, bundlers SHOULD use an RPC method to locally call the <code>handleOps</code> function on the <code>EntryPoint</code>, to verify that the signature is correct and the <code>UserOperation</code> actually pays fees; see the <a href="https://wg-eips.ritovision.com/4337/#useroperation-simulation">Simulation section below</a> for details. A node/bundler MUST reject a <code>UserOperation</code> that fails the validation, meaning not adding it to the local mempool and not propagating it to other peers.</p> <h3 id="json-rpc-api-for-erc-4337">JSON-RPC API for <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a></h3> <p>In order to support sending <code>UserOperation</code> objects to bundlers, which in turn propagate them through the P2P mempool, we introduce a set of JSON-RPC APIs including <code>eth_sendUserOperation</code> and <code>eth_getUserOperationReceipt</code>.</p> <p>The full definition of the new JSON-RPC API is outside the scope of this proposal.</p> <h3 id="support-for-eip-712-signatures">Support for <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> signatures</h3> <p>The <code>userOpHash</code> is calculated as an [EIP-712] typed message hash with the following parameters:</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"> constant</span><span> TYPE_HASH </span><span class="z-keyword">=</span></span> <span class="giallo-l"><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> PACKED_USEROP_TYPEHASH </span><span class="z-keyword">=</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span></span> <span class="giallo-l"><span class="z-string"> &quot;PackedUserOperation(address sender,uint256 nonce,bytes initCode,bytes callData,bytes32 accountGasLimits,uint256 preVerificationGas,bytes32 gasFees,bytes paymasterAndData)&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span></code></pre><h3 id="support-for-eip-7702-authorizations">Support for <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> authorizations</h3> <p>On networks with <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> enabled, the <code>eth_sendUserOperation</code> method accepts an extra <code>eip7702Auth</code> parameter. If this parameter is set, it MUST be a valid <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> authorization tuple, and signed by the <code>sender</code> address. The bundler MUST add all required <code>eip7702Auth</code> of all <code>UserOperations</code> in a bundle to the <code>authorizationList</code> and execute the bundle using a transaction type <code>SET_CODE_TX_TYPE</code>. Additionally, the <code>UserOperation</code> hash calculation is updated to include the desired <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> delegation address.</p> <p>If the <code>initCode</code> field starts with <code>0x7702</code> right-padded with 18 zeros, and this account was deployed using an EIP-7702 transaction, then the hash is calculated as follows:</p> <ul> <li>For the purpose of hash calculation, the first 20 bytes of the <code>initCode</code> field of the <code>UserOperation</code> are set to account's EIP-7702 delegate address (fetched with EXTCODECOPY)</li> <li>The <code>initCode</code> is not used to call a factory contract.</li> <li>If the <code>initCode</code> is longer than 20 bytes, then the rest of the initCode is used to call an initialization function in the account itself.</li> </ul> <p>Note that a <code>UserOperation</code> may still be executed without such <code>initCode</code>. In this case the <code>EntryPoint</code> doesn't hash the current <a href="https://wg-eips.ritovision.com/7702/">EIP-7702 delegate</a>, and can be potentially executed against a modified account.</p> <p>Additionally, EIP-7702 defines the gas cost of executing an authorization equal to <code>PER_EMPTY_ACCOUNT_COST = 25000</code>. This gas consumption is not observable on-chain by the <code>EntryPoint</code> contract and MUST be included in the <code>preVerificationGas</code> value.</p> <h3 id="extension-paymasters">Extension: paymasters</h3> <p>We extend the <code>EntryPoint</code> logic to support <strong>paymasters</strong> that can sponsor transactions for other users. This feature can be used to allow application developers to subsidize fees for their users, allow users to pay fees with [ERC-20] tokens and many other use cases. When the <code>paymasterAndData</code> field in the <code>UserOperation</code> is not empty, the <code>EntryPoint</code> implements a different flow for that UserOperation:</p> <p><img src="https://wg-eips.ritovision.com/4337/./assets/bundle-seq-pm.svg" alt="" /></p> <p>During the verification loop, in addition to calling <code>validateUserOp</code>, the <code>handleOps</code> execution also must check that the paymaster has enough ETH deposited with the <code>EntryPoint</code> to pay for the <code>UserOperation</code>, and then call <code>validatePaymasterUserOp</code> on the paymaster to verify that the paymaster is willing to pay for the <code>UserOperation</code>. Note that in this case, the <code>validateUserOp</code> is called with a <code>missingAccountFunds</code> of 0 to reflect that the account's deposit is not used for payment for this <code>UserOperation</code>.</p> <p>If the paymaster's <code>validatePaymasterUserOp</code> returns a non-empty <code>context</code> byte array, then <code>handleOps</code> must call <code>postOp</code> on the paymaster after making the main execution call. Otherwise, no call is done to the <code>postOp</code> function.</p> <p>Maliciously crafted paymasters could pose a risk of a DoS attack against the system and bundlers should take steps to mitigate it. As a mitigation, bundlers should use a reputation system for contracts they serve, and the paymaster must either limit its storage usage, or deposit a stake in a reputation system. Full specification of a reputation system is outside the scope of this proposal.</p> <h4 id="the-paymasteranddata-field-encoding-and-paymastersignature">The <code>paymasterAndData</code> field encoding and <code>paymasterSignature</code></h4> <p>The <code>paymasterAndData</code> field is a byte array that contains a non-standard encoding of the following fields:</p> <ul> <li><code>paymasterAddress</code> - 20 bytes — the address of the paymaster contract</li> <li><code>paymasterVerificationGasLimit</code> - 16 bytes - the gas limit for the verification function</li> <li><code>postOpGasLimit</code> - 16 bytes - the gas limit for the postOp function</li> <li><code>paymasterData</code> - the data that the paymaster contract will receive in the <code>validatePaymasterUserOp</code> call</li> </ul> <p>The following data can optionally be appended to the <code>paymasterAndData</code> field:</p> <ul> <li><code>paymasterSignature</code> - the "signature" value byte array to be checked by the paymaster contract; this value can be provided <strong>without affecting the UserOperation hash</strong></li> <li><code>paymasterSignatureLength</code> - 2 bytes - the exact length of the <code>paymasterSignature</code> parameter byte array</li> <li><code>PAYMASTER_SIG_MAGIC</code> (<code>0x22e325a297439656</code>) - the magic value that is appended to indicate the use of the <code>paymasterSignature</code> feature by the UserOperation</li> </ul> <p>Note that as both the <code>signature</code> and the <code>paymasterSignature</code> fields do not affect the UserOperation hash, the signing by the Sender and the Paymaster can be performed in parallel.</p> <p>The paymaster interface 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"> validatePaymasterUserOp</span></span> <span class="giallo-l"><span> (</span><span class="z-entity z-name">PackedUserOperation</span><span class="z-storage z-type"> calldata</span><span class="z-entity z-name"> userOp</span><span>,</span><span class="z-entity z-name"> bytes32</span><span class="z-entity z-name"> userOpHash</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> maxCost</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">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> context</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> validationData</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"> postOp</span></span> <span class="giallo-l"><span> (</span><span class="z-entity z-name">PostOpMode</span><span class="z-entity z-name"> mode</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"> context</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> actualGasCost</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> actualUserOpFeePerGas</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-storage z-type">enum</span><span class="z-entity z-name"> PostOpMode</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> opSucceeded</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> UserOperation succeeded</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> opReverted</span><span class="z-comment"> //</span><span class="z-comment"> UserOperation reverted. paymaster still has to pay for gas.</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>EntryPoint</code> must implement the following API to let entities like paymasters have a stake, and thus have more flexibility in their storage access.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> add a stake to the calling entity</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> addStake</span><span>(</span><span class="z-support">uint32</span><span class="z-variable z-parameter z-function"> _unstakeDelaySec</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-comment"> unlock the stake (must wait unstakeDelay before can withdraw)</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> unlockStake</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"> withdraw the unlocked stake</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> withdrawStake</span><span>(</span><span class="z-support">address</span><span class="z-variable"> payable</span><span class="z-variable"> withdrawAddress</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>The paymaster must also have a deposit, which the <code>EntryPoint</code> will charge <code>UserOperation</code> costs from. The deposit (for paying gas fees) is separate from the stake (which is locked).</p> <p>The <code>EntryPoint</code> must implement the following interface to allow Paymasters (and optionally Accounts) to manage their deposit:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> return the deposit of an account</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"> 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> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> add to the deposit of the given account</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> depositTo</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"> payable</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> add to the deposit of the calling account</span></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> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> withdraw from the deposit of the current account</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> withdrawTo</span><span>(</span><span class="z-support">address</span><span class="z-variable"> payable</span><span class="z-variable"> withdrawAddress</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> withdrawAmount</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"> get the currently executing UserOperation hash, or 0 if not called during the execution</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getCurrentUserOpHash</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><h3 id="bundler-behavior-upon-receiving-a-useroperation">Bundler behavior upon receiving a UserOperation</h3> <p><img src="https://wg-eips.ritovision.com/4337/./assets/bundle-build-full-seq.svg" alt="" /></p> <p>Similar to an Ethereum transaction, the offchain flow of a <code>UserOperation</code> can be described as follows:</p> <ol> <li>Client sends a <code>UserOperation</code> to the bundler through an RPC call <code>eth_sendUserOperation</code>.</li> <li>Before including the <code>UserOperation</code> in the mempool, the bundler runs the <em>first validation</em> of the newly received UserOperation. If the <code>UserOperation</code> fails validation, the bundler drops it and returns an error in response to <code>eth_sendUserOperation</code>.</li> <li>Later, once building a bundle, the bundler takes <code>UserOperations</code> from the mempool and runs the <em>second validation</em> of a single <code>UserOperation</code> on each of them. If it succeeds, it is scheduled for inclusion in the next bundle, and dropped otherwise.</li> <li>Before submitting the new bundle onchain, the bundler performs the <em>third validation</em> of the entire <code>UserOperations</code> bundle. If any of the <code>UserOperations</code> fail validation, the bundler drops them. The bundler should keep track of the peers' reputation. The full design of such a reputation system is outside the scope of this proposal.</li> </ol> <p>When a bundler receives a <code>UserOperation</code>, it must first run some basic sanity checks, namely that:</p> <ul> <li>Either the <code>sender</code> is an existing contract, or the <code>initCode</code> is not empty (but not both)</li> <li>If <code>initCode</code> is not empty, parse its first 20 bytes as a factory address or an <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> flag.<br /> Record whether the factory is staked, in case the later simulation indicates that it needs to be. If the factory accesses the global state, it must be staked.</li> <li>The <code>verificationGasLimit</code> and <code>paymasterVerificationGasLimits</code> are lower than <code>MAX_VERIFICATION_GAS</code> (<code>500000</code>) and the <code>preVerificationGas</code> is high enough to pay for the calldata gas cost of serializing the <code>UserOperation</code> plus <code>PRE_VERIFICATION_OVERHEAD_GAS</code> (<code>50000</code>).</li> <li>The <code>paymasterAndData</code> is either empty, or starts with the <strong>paymaster</strong> address, which is a contract that (i) currently has nonempty code on chain, (ii) has a sufficient deposit to pay for the UserOperation, and (iii) is not currently banned. During simulation, the paymaster's stake is also checked, depending on its storage usage.</li> <li>The <code>callGasLimit</code> is at least the cost of a <code>CALL</code> with non-zero value.</li> <li>The <code>maxFeePerGas</code> and <code>maxPriorityFeePerGas</code> are above a configurable minimum value that the bundler is willing to accept. At the minimum, they are sufficiently high to be included with the upcoming <code>block.basefee</code>.</li> <li>The <code>sender</code> doesn't have another <code>UserOperation</code> already present in the mempool (or it replaces an existing entry with the same sender and nonce, with a higher <code>maxPriorityFeePerGas</code> and an equally increased <code>maxFeePerGas</code>). Only one <code>UserOperation</code> per sender may be included in a single bundle. A sender is exempt from this rule and may have multiple <code>UserOperations</code> in the mempool and in a bundle if it is staked.</li> </ul> <h3 id="useroperation-simulation">UserOperation Simulation</h3> <p>We define <code>UserOperation</code> simulation, as the offchain view call (or trace call) to the <code>EntryPoint</code> contract with the <code>UserOperation</code>, and the enforcement of the shared set of rules applied to the validation code, as part of the <code>UserOperation</code> validation.</p> <h4 id="simulation-rationale">Simulation Rationale</h4> <p>To validate a normal Ethereum transaction <code>tx</code>, the bundler performs static checks, like:</p> <ol> <li><code>ecrecover(tx.v, tx.r, tx.s)</code> has to return a valid EOA</li> <li><code>tx.nonce</code> has to be the current nonce of the recovered EOA</li> <li><code>balance</code> of the recovered EOA has to be sufficient to pay for the transaction</li> <li><code>tx.gasLimit</code> has to be sufficient to cover the intrinsic gas cost of a transaction</li> <li><code>chainId</code> has to match the current chain</li> </ol> <p>All of these checks do not rely on EVM state, and cannot be affected by other Accounts' transactions.</p> <p>In contrast, <code>UserOperation</code> validation rely on EVM state (calls to <code>validateUserOp</code>, <code>validatePaymasterUserOp</code>), can be changed by other <code>UserOperations</code> (or normal Ethereum transactions). Therefore, we introduce simulation as a new mechanism to check its validity. Intuitively, the aim of the simulation is to ensure the onchain validation code of a <code>UserOperation</code> is sandboxed, isolated from other <code>UserOperations</code> in the same bundle.</p> <h4 id="simulation-specification">Simulation Specification:</h4> <p>To simulate a <code>UserOperation</code> validation, the bundler makes a view call to the <code>handleOps()</code> method with the <code>UserOperation</code> to check.</p> <p>Simulation should run only on the validation section of the <code>sender</code> and <code>paymaster</code>, and is not required for the <code>UserOperation</code>'s execution. A bundler MAY add second "always failed" <code>UserOperation</code> to the bundle, so that the simulation will end as soon as the first UserOperation's validation complete.</p> <p>The bundler MUST drop the <code>UserOperation</code> if the simulation reverts</p> <p>The simulated call performs the full validation, by calling:</p> <ol> <li>If <code>initCode</code> is present, create the <code>sender</code> Account.</li> <li><code>account.validateUserOp</code>.</li> <li>if specified a paymaster: <code>paymaster.validatePaymasterUserOp</code>.</li> </ol> <p>Either <code>sender</code> or <code>paymaster</code> may return a time-range (<code>validAfter</code>/<code>validUntil</code>). The <code>UserOperation</code> MUST be valid at the current time to be considered valid, defined as <code>validAfter&lt;=block.timestamp</code>.</p> <p>A bundler MUST drop a <code>UserOperation</code> if it expires too soon and is likely to become invalid before the next block. To decode the returned time-ranges, the bundler MUST run the validation using tracing, to decode the return value from the <code>validateUserOp</code> and <code>validatePaymasterUserOp</code> methods.</p> <p>To prevent DoS attacks on bundlers, they must make sure the validation methods above pass the validation rules, which constrain their usage of opcodes and storage. The full design of such a shared set of rules, applied to the validation code, is outside the scope of this proposal.</p> <h3 id="estimating-preverificationgas">Estimating <code>preVerificationGas</code></h3> <p>This document does not specify a canonical way to estimate this value, as it depends on non-permanent network properties such as operation and data gas pricing and the expected bundle size.</p> <p>However, the requirement is for the estimated value to be sufficient to cover the following costs:</p> <ul> <li>Base bundle transaction cost. On Ethereum, <code>21000</code> gas divided by the number of <code>UserOperations</code>.</li> <li>The calldata gas cost related to the <code>UserOperation</code> as defined in <a href="https://wg-eips.ritovision.com/2028/">EIP-2028</a>.</li> <li>Static <code>EntryPoint</code> contract code execution.</li> <li>Static memory cost when loading the fixed size fields of the <code>UserOperation</code> into EVM memory</li> <li>Memory cost (including expansion cost) due to context returned by paymaster <code>validatePaymasterUserOp</code> function, if relevant. <ul> <li>External call to the <code>innerHandleOp()</code> function which is a major part of the <code>EntryPoint</code> implementation. Note that this value is not static and depends on the <code>UserOperation</code>'s position in the bundle.</li> </ul> </li> <li>[EIP-7702] authorization cost, if any.</li> <li><a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> calldata floor price increase is estimated as follows: <ul> <li>Apply the new formula for <code>tx.gasUsed</code>, replacing the <code>execution_gas_used</code> value with an estimate for value made for this UserOperation.</li> <li>The estimate is calculated as a sum of all verification gas used during simulation (account creation, validation and paymaster validation) and 10% of the sum of execution and <code>postOp</code> gas limit.</li> </ul> </li> </ul> <p>The bundler MUST require a slack in <code>PreVerificationGas</code> value, to accommodate memory expansion costs in the future bundle, and the expected position of the <code>UserOperation</code> in it.</p> <h3 id="alternative-mempools">Alternative Mempools</h3> <p>The simulation rules above are strict and prevent the ability of paymasters to grief the system. However, there might be use cases where specific paymasters can be validated (through manual auditing) and verified that they cannot cause any problem, while still require relaxing of the opcode rules. A bundler cannot simply "whitelist" a request from a specific paymaster: if that paymaster is not accepted by all bundlers, then its support will be sporadic at best. Instead, we introduce the term "alternate mempool": a modified validation rules, and procedure of propagating them to other bundlers.</p> <p>The procedure of using alternate mempools is outside the scope of this proposal.</p> <h3 id="bundling">Bundling</h3> <p>Bundling is the process where a node/bundler collects multiple <code>UserOperations</code> and creates a single transaction to submit on-chain.</p> <p>During bundling, the bundler MUST:</p> <ul> <li>Exclude <code>UserOperations</code> that access any sender address of another <code>UserOperation</code> in the same bundle.</li> <li>Exclude <code>UserOperations</code> that access any address created by another <code>UserOperation</code> validation in the same bundle (via a factory).</li> <li>For each paymaster used in the bundle, keep track of the balance while adding <code>UserOperations</code>. Ensure that it has sufficient deposit to pay for all the <code>UserOperations</code> that use it.</li> </ul> <p>After creating the bundle, before including the transaction in a block, the bundler SHOULD:</p> <ul> <li>Run <code>debug_traceCall</code> with maximum possible gas, to enforce the validation rules on opcode and storage access, as well as to verify the entire <code>handleOps</code> bundle transaction, and use the consumed gas for the actual transaction execution.</li> <li>If the call reverted, the bundler MUST use the trace result to find the entity that reverted the call.<br /> This is the last entity that is CALL'ed by the <code>EntryPoint</code> prior to the revert.<br /> (the bundler cannot assume the revert is <code>FailedOp</code>)</li> <li>If any verification context rule was violated the bundlers MUST treat it the same as if this <code>UserOperation</code> reverted.</li> <li>Remove the offending <code>UserOperation</code> from the current bundle and from mempool.</li> <li>If the error is caused by a <code>factory</code> or a <code>paymaster</code>, and the <code>sender</code> of the <code>UserOperation</code> <strong>is not</strong> a staked entity, then issue a "ban" for the guilty factory or paymaster.</li> <li>If the error is caused by a <code>factory</code> or a <code>paymaster</code>, and the <code>sender</code> of the <code>UserOperation</code> <strong>is</strong> a staked entity, do not ban the <code>factory</code> / <code>paymaster</code> from the mempool. Instead, issue a "ban" for the staked <code>sender</code> entity.</li> <li>Repeat until <code>debug_traceCall</code> succeeds.</li> </ul> <p>As staked entries may use some kind of transient storage to communicate data between <code>UserOperations</code> in the same bundle, it is critical that the exact same opcode and precompile banning rules as well as storage access rules are enforced for the <code>handleOps</code> validation in its entirety as for individual <code>UserOperations</code>. Otherwise, attackers may be able to use the banned opcodes to detect running on-chain and trigger a <code>FailedOp</code> revert.</p> <p>When a bundler includes a bundle in a block it must ensure that earlier transactions in the block don't make any <code>UserOperation</code> fail.</p> <h3 id="error-codes">Error codes.</h3> <p>While performing validation, the <code>EntryPoint</code> must revert on failures. During simulation, the calling bundler MUST be able to determine which entity (<code>sender</code>,<code>factory</code> or <code>paymaster</code>) caused the failure. The attribution of a revert to an entity is done using call-tracing: the last entity called by the <code>EntryPoint</code> prior to the revert is the entity that caused the revert.</p> <ul> <li>For diagnostic purposes, the <code>EntryPoint</code> must only revert with explicit <code>SignatureValidationFailed()</code>, <code>FailedOp()</code> or <code>FailedOpWithRevert()</code> errors.</li> <li>The message of the error starts with event code, AA##</li> <li>Event code starting with "AA1" signifies an error during <code>sender</code> creation</li> <li>Event code starting with "AA2" signifies an error during <code>sender</code> validation (<code>validateUserOp</code>)</li> <li>Event code starting with "AA3" signifies an error during <code>paymaster</code> validation (<code>validatePaymasterUserOp</code>)</li> </ul> <h2 id="rationale">Rationale</h2> <p>The main challenge with a purely "Smart Contract Accounts" based Account Abstraction system is DoS safety: how can a block builder including an operation make sure that it will actually pay fees, without having to first execute the entire operation? Requiring the block builder to execute the entire operation opens a DoS attack vector, as an attacker could easily send many operations that pretend to pay a fee but then revert at the last moment after a long execution. Similarly, to prevent attackers from cheaply clogging the mempool, nodes in the P2P network need to check if an operation will pay a fee before they are willing to forward it.</p> <p>The first step is a clean separation between validation (acceptance of UserOperation, and acceptance to pay) and execution. In this proposal, we expect Accounts to have a <code>validateUserOp</code> method that takes as input a <code>UserOperation</code>, verifies the signature and pays the fee. Only if this method returns successfully, the execution will happen.</p> <p>The <code>EntryPoint</code>-based approach allows for a clean separation between verification and execution, and keeps Smart Contract Accounts' logic simple. It enforces the simple rule that only after validation is successful and the <code>UserOperation</code> can pay, the execution is done and only done once, and also guarantees the fee payment.</p> <h3 id="validation-rules-rationale">Validation Rules Rationale</h3> <p>The next step is protecting the bundlers from denial-of-service attacks by a mass number of <code>UserOperations</code> that appear to be valid (and pay) but that eventually revert, and thus block the bundler from processing valid <code>UserOperations</code>.</p> <p>There are two types of <code>UserOperations</code> that can fail validation:</p> <ol> <li><code>UserOperations</code> that succeed in initial validation (and accepted into the mempool), but rely on the environment state to fail later when attempting to include them in a block.</li> <li><code>UserOperations</code> that are valid when checked independently but fail when bundled together to be put on-chain. To prevent such rogue <code>UserOperations</code>, the bundler is required to follow a set of shared set of rules applied to the validation code, to prevent such denial-of-service attacks.</li> </ol> <h3 id="reputation-rationale">Reputation Rationale</h3> <p>UserOperation's storage access rules prevent them from interfering with each other. But "global" entities - paymasters and factories are accessed by multiple <code>UserOperations</code>, and thus might invalidate multiple previously valid <code>UserOperations</code>.</p> <p>To prevent abuse, we throttle down (or completely ban for a period of time) an entity that causes invalidation of a large number of <code>UserOperations</code> in the mempool. To prevent such entities from "Sybil-attack", we require them to stake with the system, and thus make such DoS attack very expensive. Note that this stake is never slashed. There is no slashing mechanism involved and the only use for the stake in sybil attack prevention. The stake can be withdrawn at any time after the specified unstake delay.</p> <p>Unstaked entities are allowed, under the rules below.</p> <p>When staked, an entity is less restricted in its use of contract storage.</p> <p>The stake value is not enforced on-chain, but specifically by each bundler while simulating a transaction.</p> <h3 id="paymasters">Paymasters</h3> <p>Paymaster contracts allow the abstraction of gas: having a contract, that is not the sender of the transaction, to pay for the transaction fees.</p> <p>Paymaster architecture allows them to follow the model of "pre-charge, and later refund". E.g. a token-paymaster may pre-charge the user with the max possible price of the transaction, and refund the user with the excess afterwards.</p> <h3 id="first-time-smart-contract-account-creation">First-time Smart Contract Account creation</h3> <p>NOTE: for contracts using EIP-7702 this flow is described in <a href="https://wg-eips.ritovision.com/4337/#support-for-eip-7702-authorizations">Support for [EIP-7702] authorizations</a>.</p> <p>It is an important design goal of this proposal to replicate the key property of EOAs that users do not need to perform some custom action or rely on an existing user to create their Smart Contract Account; they can simply generate an address locally and immediately start accepting funds.</p> <p>The Smart Contract Account creation itself is done by a "factory" contract, with some Account-specific data. The Factory is expected to use <code>CREATE2 0xF5</code> (not <code>CREATE 0xF0</code>) to create the Account, so that the order of creation of the Accounts doesn't interfere with the generated addresses. The <code>initCode</code> field (if non-zero length) is parsed as a 20-byte <code>factory</code> address, followed by <code>calldata</code> to pass to this address. This method call is expected to create the Account and return its address. If the factory does use <code>CREATE2 0xF5</code> or some other deterministic method to create the Account, it's expected to return the Account address even if it had already been created. This comes to make it easier for bundlers to query the address without knowing if the Account has already been deployed, by simulating a call to <code>entryPoint.getSenderAddress()</code>, which calls the <code>factory</code> under the hood. When <code>initCode</code> is specified, if either the <code>sender</code> address points to an existing contract or the <code>sender</code> address still does not exist after calling the <code>initCode</code>, then the operation is aborted. The <code>initCode</code> MUST NOT be called directly from the <code>EntryPoint</code>, but from another address. The contract created by this factory method MUST accept a call to <code>validateUserOp</code> to validate the <code>UserOperation</code>'s signature. For security reasons, it is important that the generated contract address will depend on the initial signature. This way, even if someone can deploy an Account at that address, he can't set different credentials to control it. The Factory has to be staked if it accesses global storage. NOTE: In order for the Wallet Application to determine the "counterfactual" address of the Account prior to its creation, it SHOULD make a static call to the <code>entryPoint.getSenderAddress()</code></p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This ERC does not change the consensus layer, so there are no backwards compatibility issues for Ethereum as a whole. Unfortunately it is not easily compatible with pre-<a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> Smart Contract Accounts, because those Accounts do not have a <code>validateUserOp</code> function. If the Smart Contract Account has a function for authorizing a trusted <code>UserOperation</code> submitter, then this could be fixed by creating an <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> compatible Account that re-implements the verification logic as a wrapper and setting it to be the original Account's trusted <code>UserOperation</code> submitter.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The <code>EntryPoint</code> contract will need to be audited and formally verified, because it will serve as a central trust point for <em>all</em> [ERC-4337]. In total, this architecture reduces auditing and formal verification load for the ecosystem, because the amount of work that individual <em>accounts</em> have to do becomes much smaller (they need only verify the <code>validateUserOp</code> function and its "check signature and pay fees" logic) and check that other functions are <code>msg.sender == ENTRY_POINT</code> gated (perhaps also allowing <code>msg.sender == self</code>), but it is nevertheless the case that this is done precisely by concentrating security risk in the <code>EntryPoint</code> contract that needs to be verified to be very robust.</p> <p>Verification would need to cover two primary claims (not including claims needed to protect paymasters, and claims needed to establish p2p-level DoS resistance):</p> <ul> <li><strong>Safety against arbitrary hijacking</strong>: The <code>EntryPoint</code> only calls to the <code>sender</code> with <code>userOp.calldata</code> and only if <code>validateUserOp</code> to that specific <code>sender</code> has passed.</li> <li><strong>Safety against fee draining</strong>: If the <code>EntryPoint</code> calls <code>validateUserOp</code> and passes, it also must make the generic call with calldata equal to <code>userOp.calldata</code></li> </ul> <h3 id="factory-contracts">Factory contracts</h3> <p>All <code>factory</code> contracts MUST check that all calls to the <code>createAccount()</code> function originate from the <code>entryPoint.senderCreator()</code> address.</p> <h3 id="paymasters-contracts">Paymasters contracts</h3> <p>All <code>paymaster</code> contracts MUST check that all calls to the <code>validatePaymasterUserOp()</code> and <code>postOp()</code> functions originate from the <code>EntryPoint</code>.</p> <h3 id="aggregator-contracts">Aggregator contracts</h3> <p>All <code>aggregator</code> contracts MUST check that all calls to the <code>validateSignatures()</code> function originates from the <code>EntryPoint</code>.</p> <h3 id="eip-7702-delegated-smart-contract-accounts">EIP-7702 delegated Smart Contract Accounts</h3> <p>All EIP-7702 delegated Smart Contract Account implementations MUST check that all calls to the initialization function originate from the <code>entryPoint.senderCreator()</code> address.</p> <p>There is no way for the <code>EntryPoint</code> contract to know whether an EIP-7702 account has been initialized or not, and therefore the EIP-7702 account initialization code, can be called multiple times through <code>EntryPoint</code>. The Account code SHOULD only allow calling it once and the Wallet Application SHOULD NOT pass the <code>initCode</code> repeatedly.</p> <h3 id="smart-contract-accounts">Smart Contract Accounts</h3> <h4 id="storage-layout-collisions">Storage layout collisions</h4> <p>It is expected that most of ERC-4337 Smart Contract Account will be upgradeable, either via on-chain delegate proxy contracts or via EIP-7702.</p> <p>When changing the underlying implementation, all Accounts MUST ensure that there are no conflicts in the storage layout of the two contracts.</p> <p>One common approach to this problem is often referred to as "diamond storage" and is fully described in <a href="https://wg-eips.ritovision.com/7201/">ERC-7201</a>.</p> <h3 id="transient-storage">Transient Storage</h3> <p>Contracts using the <a href="https://wg-eips.ritovision.com/1153/">EIP-1153</a> transient storage MUST take into account that ERC-4337 allows multiple <code>UserOperations</code> from different unrelated <code>sender</code> addresses to be included in the same underlying transaction. The transient storage MUST be cleaned up manually if contains any sensitive information or is used for access control.</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-30T00:00:00+00:00 2026-02-11T14:49:28+00:00 Greg Colvinhttps://github.com/gcolvin Greg Colvingreg@colvin.org Brooklyn Zelenkahttps://github.com/expede https://wg-eips.ritovision.com/3779/

Ensure an essential level of safety for EVM code.

<h2 id="abstract">Abstract</h2> <p>We define a safe EVM contract as one that cannot encounter an exceptional halting state. In general, we cannot prove safety for Turing-complete programs. But we can prove a useful subset.</p> <p>This EIP specifies validity rules to ensure that:</p> <blockquote> <p>Valid contracts will not halt with an exception unless they either</p> <ul> <li>throw <code>out of gas</code> or</li> <li>recursively overflow stack.</li> </ul> </blockquote> <p>This EIP does not introduce any new opcodes. Rather, it restricts the use of existing and proposed control-flow instructions. The restrictions must be validated at contract initialization time – not at runtime – by the provided algorithm or its equivalent. This algorithm must take time and space near-linear in the size of the contract, so as not to be a denial of service vulnerability.</p> <p>This specification is entirely semantic. It imposes no further syntax on bytecode, as none is required to ensure the specified level of safety. Ethereum Virtual Machine bytecode is just that -- a sequence of bytes that when executed causes a sequence of changes to the machine state. The safety we seek here is simply to not, as it were, jam up the gears.</p> <h2 id="motivation">Motivation</h2> <h3 id="safety">Safety</h3> <p>For our purposes we define a safe EVM contract as one that cannot encounter an exceptional halting state. From the standpoint of security it would be best if unsafe contracts were never placed on the blockchain. Unsafe code can attempt to overflow stack, underflow stack, execute invalid instructions, and jump to invalid locations.</p> <p>Unsafe contracts are exploits waiting to happen.</p> <p>Validating contract safety requires traversing the contract code. So in order to prevent denial of service attacks all jumps, including the existing <code>JUMP</code> and <code>JUMPI</code>, and also the other proposed jumps -- <code>RJUMP</code>, <code>RJUMPI</code>, <code>RJUMPSUB</code> and <code>RETURNSUB</code> -- must be validated at initialization time, and in time and space linear in the size of the code.</p> <h4 id="static-jumps-and-subroutines">Static Jumps and Subroutines</h4> <p>The relative jumps of <a href="https://wg-eips.ritovision.com/4200/">EIP-4200</a> and the simple subroutines of <a href="https://wg-eips.ritovision.com/2315/">EIP-2315</a> provide a complete set of static control flow instructions:</p> <blockquote> <p><code>RJUMP</code> <em>offset</em></p> </blockquote> <ul> <li>Jumps to <em>IP+offset</em>.</li> </ul> <blockquote> <p><code>RJUMPI</code> <em>offset</em></p> </blockquote> <ul> <li>Jumps if the top of stack is non-zero.</li> </ul> <blockquote> <p><code>RJUMPSUB</code> offset</p> </blockquote> <ul> <li>Pushes <em>IP+1</em> on the return stack and jumps to <em>IP+offset</em>.</li> </ul> <blockquote> <p><code>RETURNSUB</code></p> </blockquote> <ul> <li>Jumps to the address popped off the return stack.</li> </ul> <p>Note that each jump creates at most two paths of control through the code, such that the complexity of traversing the entire control-flow graph is linear in the size of the code.</p> <h4 id="dynamic-jumps"><em>Dynamic Jumps</em></h4> <p>Dynamic jumps, where the destination of a <code>JUMP</code> or <code>JUMPI</code> is not known until runtime, are an obstacle to proving validity in linear time -- any jump can be to any destination in the code, potentially requiring time quadratic in the size of code. For this reason we have two real choices.</p> <ol> <li>Deprecate dynamic jumps. This is easily done:</li> </ol> <blockquote> <p>Define <code>JUMP</code> and <code>JUMPI</code> as <code>INVALID</code> for the purposes of EOF Code Validation</p> </blockquote> <ol start="2"> <li>Constrain dynamic jumps. This requires static analysis.</li> </ol> <p>Consider the simplest and most common case.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH address</span></span> <span class="giallo-l"><span>JUMP</span></span></code></pre> <p>This is effectively a static jump.</p> <p>Another important use of <code>JUMP</code> is to implement the return jump from a subroutine. So consider this example of calling and returning from a minimal subroutine:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>TEST_SQUARE:</span></span> <span class="giallo-l"><span> jumpdest</span></span> <span class="giallo-l"><span> push RTN_SQUARE </span></span> <span class="giallo-l"><span> 0x02</span></span> <span class="giallo-l"><span> push SQUARE</span></span> <span class="giallo-l"><span> jump</span></span> <span class="giallo-l"><span>RTN_SQUARE</span></span> <span class="giallo-l"><span> jumpdest</span></span> <span class="giallo-l"><span> swap1</span></span> <span class="giallo-l"><span> jump</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>SQUARE:</span></span> <span class="giallo-l"><span> jumpdest</span></span> <span class="giallo-l"><span> dup1</span></span> <span class="giallo-l"><span> mul</span></span> <span class="giallo-l"><span> swap1</span></span> <span class="giallo-l"><span> jump</span></span></code></pre> <p>The return address -<code>RTN_SQUARE</code> - and the destination address - <code>SQUARE</code> - are pushed on the stack as constants and remain unchanged as they move on the stack, such that only those constants are passed to each <code>JUMP</code>. They are effectively static. We can track the motion of constants on the <code>data stack</code> at validation time, so <em>we do not need unconstrained dynamic jumps to implement subroutines.</em></p> <p><em>The above is the simplest analysis that suffices. A more powerful analysis that takes in more use cases is possible -- slower, but still linear-time.</em></p> <h4 id="validation">Validation</h4> <p>We can validate the safety of contracts with a static analysis that takes time and space linear in the size of the <em>code</em>, as shown below. And since we can, we should.</p> <h3 id="performance">Performance</h3> <p>Validating safe control flow at initialization time has potential performance advantages.</p> <ul> <li>Static jumps do not need to be checked at runtime.</li> <li>Stack underflow does not need to be checked for at runtime.</li> </ul> <h2 id="specification">Specification</h2> <h3 id="validity">Validity</h3> <blockquote> <p>In theory, theory and practice are the same. In practice, they're not. -- Albert Einstein</p> </blockquote> <p>We define a <em>safe</em> EVM contract as one that cannot encounter an exceptional halting state. We validate <em>safety</em> at initialization time to the extent practical.</p> <h4 id="exceptional-halting-states"><em>Exceptional Halting States</em></h4> <p>The <em>execution</em> of each instruction is defined in the Yellow Paper as a change to the EVM state that preserves the invariants of EVM state. At runtime, if the execution of an instruction would violate an invariant the EVM is in an exceptional halting state. The Yellow Paper defined five such states.</p> <ol> <li>Insufficient gas</li> <li>More than 1024 stack items</li> <li>Insufficient stack items</li> <li>Invalid jump destination</li> <li>Invalid instruction</li> </ol> <p><em>A program is safe iff no execution can lead to an exceptional halting state.</em></p> <p><em>We would like to consider EVM programs valid iff they are safe.</em></p> <p><em>In practice</em>, we must be able to validate <em>code</em> in linear time to avoid denial of service attacks. And we must support dynamically-priced instructions, loops, and recursion, which can use arbitrary amounts of gas and stack.</p> <p>Thus our validation cannot consider concrete computations -- it only performs a limited symbolic execution of the <em>code</em>. This means we will reject programs if we detect any invalid execution paths, even if those paths are not reachable at runtime. And we will count as valid programs that may not always produce correct results.</p> <p>We can detect only <em>non-recursive</em> stack overflows at <em>validation time</em>, so we must check for the first two states at <em>runtime</em>:</p> <ul> <li><code>out of gas</code> and</li> <li>stack overflow.</li> </ul> <p>The remaining three states we can check at <em>validation time</em>:</p> <ul> <li>stack underflow,</li> <li>invalid jump, and</li> <li>invalid instruction.</li> </ul> <p>That is to say:</p> <blockquote> <p>Valid contracts will not halt with an exception unless they either</p> <ul> <li>throw <code>out of gas</code> or</li> <li>recursively overflow stack.</li> </ul> </blockquote> <h4 id="constraints-on-valid-code"><em>Constraints on Valid Code</em></h4> <ul> <li>Every instruction is valid.</li> <li>Every jump is valid: <ul> <li>Every<code>JUMP</code> and <code>JUMPI</code> is <em>static</em>.</li> <li>No <code>JUMP</code>, <code>JUMPI</code>, <code>RJUMP</code>, <code>RJUMPI</code>, or <code>RJUMPSUB</code> addresses immediate data.</li> </ul> </li> <li>The stacks are always valid: <ul> <li>The <em>number</em> of items on the <code>data stack</code> is always positive, and at most 1024.</li> <li>The <em>number</em> of items on the <code>return stack</code> is always positive, and at most 1024.</li> </ul> </li> <li>The data stack is consistently aligned: <ul> <li>The <em>number</em> of items on the <code>data stack</code> between the current <code>stack pointer</code> and the <code>stack pointer</code> on entry to the most recent basic block is the same for each <em>execution</em> of a <em>byte_code</em>.</li> </ul> </li> </ul> <p>We define a <code>JUMP</code> or <code>JUMPI</code> instruction to be <em>static</em> if its <code>jumpsrc</code> argument was first placed on the stack via a <code>PUSH…</code> and that value has not changed since, though it may have been copied via a <code>DUP…</code> or <code>SWAP…</code>.</p> <p>The <code>RJUMP</code>, <code>RJUMPI</code> and <code>RJUMPSUB</code>instructions take their destination as an immediate argument, so they are <em>static</em>.</p> <p>Taken together, these rules allow for code to be validated by traversing the control-flow graph, in time and space linear in the size of the code, following each edge only once.</p> <p><em>Note: The definition of 'static' for <code>JUMP</code> and <code>JUMPI</code> is the bare minimum needed to implement subroutines. Deeper analyses could be proposed that would validate a larger and probably more useful set of jumps, at the cost of more expensive (but still linear) validation.</em></p> <h2 id="rationale">Rationale</h2> <p>Demanding <em>static</em> destinations for all jumps means that all jump destinations can be validated at initialization time, not runtime.</p> <p>Bounding the stack pointers catches all <code>data stack</code> and non-recursive<code>return stack</code> overflows.</p> <p>Requiring a consistently aligned<code>data stack</code> prevents stack underflow. It can also catch such errors as misaligned stacks due to irreducible control flows and calls to subroutines with the wrong number of arguments.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>These changes affect the semantics of EVM code – the use of <code>JUMP</code>, <code>JUMPI</code>, and the stack are restricted, such that some <em>code</em> that would otherwise run correctly will nonetheless be invalid EVM <em>code</em>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The following is a pseudo-Go implementation of an algorithm for predicating code validity. An equivalent algorithm must be run at initialization time.</p> <p>This algorithm performs a symbolic execution of the program that recursively traverses the <em>code</em>, emulating its control flow and stack use and checking for violations of the rules above.</p> <p>It runs in time equal to <code>O(vertices + edges)</code> in the program's control-flow graph, where edges represent control flow and the vertices represent <em>basic blocks</em> -- thus the algorithm takes time proportional to the size of the <em>code</em>.</p> <p><em>Note: All valid code has a control-flow graph that can be traversed in time and space linear in the length of the code. That means that some other static analyses and code transformations that might otherwise require quadratic time can also be written to run in near-linear time, including one-pass and streaming compilers.</em></p> <h3 id="validation-function">Validation Function</h3> <p><em><strong>Note:</strong> This function is a work in progress, and the version below is known to be incorrect.</em></p> <p>For simplicity's sake we assume that <em>jumpdest analysis</em> has been done and that we have some helper functions.</p> <ul> <li><code>isValidInstruction(pc)</code> returns true if <code>pc</code> points at a valid instruction</li> <li><code>isValidJumpdest(dest)</code> returns true if <code>dest</code> is a valid jumpdest</li> <li><code>immediateData(pc)</code> returns the immediate data for the instruction at <code>pc</code>.</li> <li><code>advancePC(pc)</code> returns next <code>pc</code>, skipping any immediate data.</li> <li><code>removed_items(pc)</code> returns the number of items removed from the <code>dataStack</code> by the instruction at <code>pc</code>.</li> <li><code>added_items(pc)</code> returns the number of items added to the <code>dataStack</code> by the instruction at <code>pc</code>.</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>var bytecode [codeLen]byte</span></span> <span class="giallo-l"><span>var subMin [codeLen]int</span></span> <span class="giallo-l"><span>var subMax [codeLen]int</span></span> <span class="giallo-l"><span>var subDelta [codeLen]int</span></span> <span class="giallo-l"><span>var visited [codeLen]bool</span></span> <span class="giallo-l"><span>var dataStack [1024]int</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// validate a path through the control flow of the bytecode at pc</span></span> <span class="giallo-l"><span>// and return the maximum number of stack items used down that path</span></span> <span class="giallo-l"><span>// or else the PC and an error</span></span> <span class="giallo-l"><span>//</span></span> <span class="giallo-l"><span>// by starting at pc:=0 the entire program is recursively evaluated</span></span> <span class="giallo-l"><span>//</span></span> <span class="giallo-l"><span>func validate(pc := 0, sp := 0, rp := 0) int, error {</span></span> <span class="giallo-l"><span> minStack := 0 </span></span> <span class="giallo-l"><span> maxStack := 0 </span></span> <span class="giallo-l"><span> deltaStack := 0 </span></span> <span class="giallo-l"><span> for pc &lt; codeLen {</span></span> <span class="giallo-l"><span> if !isValidInstruction(pc) {</span></span> <span class="giallo-l"><span> return 0,0,0,invalid_instruction</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> // if we have jumped here before return to break cycle</span></span> <span class="giallo-l"><span> if visited[pc] {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // stack is not aligned if deltas not the same</span></span> <span class="giallo-l"><span> if ??? {</span></span> <span class="giallo-l"><span> return 0,0,0,invalid_stack</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> return minStack, maxStack, sp</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> visited[pc] = true</span></span> <span class="giallo-l"><span> switch bytecode[pc] {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // successful termination</span></span> <span class="giallo-l"><span> case STOP:</span></span> <span class="giallo-l"><span> return minStack, maxStack, sp</span></span> <span class="giallo-l"><span> case RETURN:</span></span> <span class="giallo-l"><span> return minStack, maxStack, sp</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> case SELFDESTRUCT:</span></span> <span class="giallo-l"><span> return minStack, maxStack, sp</span></span> <span class="giallo-l"><span> case REVERT:</span></span> <span class="giallo-l"><span> return minStack, maxStack, sp</span></span> <span class="giallo-l"><span> case INVALID:</span></span> <span class="giallo-l"><span> return 0,0,0,invalid_instruction</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> case RJUMP:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // check for valid jump destination</span></span> <span class="giallo-l"><span> if !isValidJumpdest(jumpdest) {</span></span> <span class="giallo-l"><span> return 0,0,0,invalid_destination</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> // reset pc to destination of jump</span></span> <span class="giallo-l"><span> pc += immediateData(pc)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> case RJUMPI:</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> // recurse to validate true side of conditional</span></span> <span class="giallo-l"><span> jumpdest = pc + immediateData(pc)</span></span> <span class="giallo-l"><span> if !isValidJumpdest(pc + jumpdest) {</span></span> <span class="giallo-l"><span> return 0,0,0,invalid_destination</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> minRight, maxLeft, deltaRight, err =</span></span> <span class="giallo-l"><span> validate(jumpdest, sp, rp)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> err {</span></span> <span class="giallo-l"><span> return 0,0,0,err</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> // recurse to validate false side of conditional</span></span> <span class="giallo-l"><span> pc = advancePC(pc)</span></span> <span class="giallo-l"><span> minRight, maxRight, deltaRight, err =</span></span> <span class="giallo-l"><span> validate(pc, sp, rp)</span></span> <span class="giallo-l"><span> if err {</span></span> <span class="giallo-l"><span> return 0,0,0,err</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> // both paths valid, so return max</span></span> <span class="giallo-l"><span> minStack = min(minStack, min(minLeft, minRight))</span></span> <span class="giallo-l"><span> maxStack += max(maxLeft, maxRight)</span></span> <span class="giallo-l"><span> deltaStack += max(deltaLeft, deltaRight)</span></span> <span class="giallo-l"><span> return minStack, maxStack, deltaStack</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> case RJUMPSUB:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // check for valid jump destination</span></span> <span class="giallo-l"><span> jumpdest = immediateData(pc)</span></span> <span class="giallo-l"><span> if !isValidJumpdest(pc + jumpdest) {</span></span> <span class="giallo-l"><span> return 0,0,0,invalid_destination</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> pc += jumpdest</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // recurse to validate subroutine call</span></span> <span class="giallo-l"><span> minSub, maxSub, deltaSub, err = validate(jumpdest, sp, rp)</span></span> <span class="giallo-l"><span> if err {</span></span> <span class="giallo-l"><span> return 0,0,0,err</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> subMin[pc] = minSub</span></span> <span class="giallo-l"><span> subMax[pc] = maxSub</span></span> <span class="giallo-l"><span> subDelta[pc] = deltaSub</span></span> <span class="giallo-l"><span> minStack = min(minStack, sp)</span></span> <span class="giallo-l"><span> maxStack = max(maxStack, sp)</span></span> <span class="giallo-l"><span> pc = advancePC(pc)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> case RETURNSUB:</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> maxStack = max(maxStack, sp)</span></span> <span class="giallo-l"><span> return minStack, maxStack, sp, nil</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> // The following are to be included only if we take</span></span> <span class="giallo-l"><span> //</span></span> <span class="giallo-l"><span> // Option 2</span></span> <span class="giallo-l"><span> //</span></span> <span class="giallo-l"><span> // and do not deprecate JUMP and JUMPI</span></span> <span class="giallo-l"><span> //</span></span> <span class="giallo-l"><span> case JUMP:</span></span> <span class="giallo-l"><span> // pop jump destination</span></span> <span class="giallo-l"><span> jumpdest = dataStack[--sp]</span></span> <span class="giallo-l"><span> if !valid_jumpdest(jumpdest) {</span></span> <span class="giallo-l"><span> return 0,0,0,invalid_destination</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> pc = jumpdest</span></span> <span class="giallo-l"><span> case JUMPI:</span></span> <span class="giallo-l"><span> // pop jump destination and conditional</span></span> <span class="giallo-l"><span> jumpdest = dataStack[--sp]</span></span> <span class="giallo-l"><span> jumpif = dataStack[--sp]</span></span> <span class="giallo-l"><span> if sp &lt; 0 {}</span></span> <span class="giallo-l"><span> return 0,0,0,stack_underflow</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> if !valid_jumpdest(jumpdest) {</span></span> <span class="giallo-l"><span> return 0,0,0,invalid_destination</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // recurse to validate true side of conditional</span></span> <span class="giallo-l"><span> if !isValidJumpdest(jumpdest) {</span></span> <span class="giallo-l"><span> return 0,0,0,invalid_destination</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> maxLeft, err = validate(jumpdest, sp, rp)</span></span> <span class="giallo-l"><span> if err {</span></span> <span class="giallo-l"><span> return 0,0,0,err</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> // recurse to validate false side of conditional</span></span> <span class="giallo-l"><span> pc = advance_pc(pc)</span></span> <span class="giallo-l"><span> maxRight, err = validate(pc, sp, rp)</span></span> <span class="giallo-l"><span> if err {</span></span> <span class="giallo-l"><span> return 0,0,0,err</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> // both sides valid, return max</span></span> <span class="giallo-l"><span> maxStack += max(maxLeft, maxRight)</span></span> <span class="giallo-l"><span> return minStack, maxStack, sp</span></span> <span class="giallo-l"><span> case PUSH1 &lt;= bytecode[pc] &amp;&amp; bytecode[pc] &lt;= PUSH32 {</span></span> <span class="giallo-l"><span> sp++</span></span> <span class="giallo-l"><span> if (sp &gt; 1023) {</span></span> <span class="giallo-l"><span> return 0,0,0,stack_overflow</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> maxStack = max(maxStack, sp)</span></span> <span class="giallo-l"><span> dataStack[sp] = immediateData(pc)</span></span> <span class="giallo-l"><span> pc = advancePC(pc)</span></span> <span class="giallo-l"><span> case DUP1 &lt;= bytecode[pc] &amp;&amp; bytecode[pc] &lt;= DUP32 {</span></span> <span class="giallo-l"><span> dup = sp - (bytecode[pc] - DUP1)</span></span> <span class="giallo-l"><span> if dup &lt; 0 {</span></span> <span class="giallo-l"><span> return 0,0,0,stack_underflow</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> sp++</span></span> <span class="giallo-l"><span> if (sp &gt; 1023) {</span></span> <span class="giallo-l"><span> return 0,0,0,stack_overflow</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> maxStack = max(maxStack, sp)</span></span> <span class="giallo-l"><span> dataStack[sp] = dataStack[dup]</span></span> <span class="giallo-l"><span> pc = advancePC(pc)</span></span> <span class="giallo-l"><span> case SWAP1 &lt;= bytecode[pc] &amp;&amp; bytecode[pc] &lt;= SWAP32 {</span></span> <span class="giallo-l"><span> swap = sp - (bytecode[pc] - SWAP1)</span></span> <span class="giallo-l"><span> if swap &lt; 0 {</span></span> <span class="giallo-l"><span> return 0,0,0,stack_underflow</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> temp := dataStack[swap]</span></span> <span class="giallo-l"><span> dataStack[swap] = dataStack[0]</span></span> <span class="giallo-l"><span> dataStack[0] = temp</span></span> <span class="giallo-l"><span> pc = advancePC(pc)</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> default:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // apply other instructions to stack pointer</span></span> <span class="giallo-l"><span> sp -= removed_items(pc)</span></span> <span class="giallo-l"><span> if (sp &lt; 0) {</span></span> <span class="giallo-l"><span> return 0,0,0,stack_underflow</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> minStack = min(minStack, sp)</span></span> <span class="giallo-l"><span> sp += added_items(pc)</span></span> <span class="giallo-l"><span> if (sp &gt; 1023) {</span></span> <span class="giallo-l"><span> return 0,0,0,stack_overflow</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> maxStack = max(maxStack, sp)</span></span> <span class="giallo-l"><span> pc = advancePC(pc)</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> // successful termination</span></span> <span class="giallo-l"><span> return minStack, maxStack, sp</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>This EIP is intended to ensure an essential level of safety for EVM code deployed on the blockchain.</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-26T00:00:00+00:00 2026-02-11T14:48:25+00:00 Lukas Schorhttps://github.com/lukasschor Richard Meissnerhttps://github.com/rmeissner Pedro Gomeshttps://github.com/pedrouid ligiligi@ligi.de https://wg-eips.ritovision.com/3770/

Prepending chain-specific addresses with a human-readable chain identifier

<h2 id="abstract">Abstract</h2> <p><a href="https://wg-eips.ritovision.com/3770/">ERC-3770</a> introduces a new address standard to be adapted by wallets and dApps to display chain-specific addresses by using a human-readable prefix.</p> <h2 id="motivation">Motivation</h2> <p>The need for this proposal emerges from the increasing adoption of non-Ethereum Mainnet chains that use the Ethereum Virtual Machine (EVM). In this context, addresses become ambiguous, as the same address may refer to an EOA on chain X or a smart contract on chain Y. This will eventually lead to Ethereum users losing funds due to human error. For example, users sending funds to a smart contract wallet address which was not deployed on a particular chain.</p> <p>Therefore we should prefix addresses with a unique identifier that signals to Dapps and wallets on what chain the target account is. In theory, this prefix could be a <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> chainID. However, these chain IDs are not meant to be displayed to users in dApps or wallets, and they were optimized for developer interoperability, rather than human readability.</p> <h2 id="specification">Specification</h2> <p>This proposal extends addresses with a human-readable blockchain short name.</p> <h3 id="syntax">Syntax</h3> <p>A chain-specific address is prefixed with a chain shortName, separated with a colon sign (:).</p> <p>Chain-specific address = "<code>shortName</code>" "<code>:</code>" "<code>address</code>"</p> <ul> <li> <p><code>shortName</code> = STRING</p> </li> <li> <p><code>address</code> = STRING</p> </li> </ul> <h3 id="semantics">Semantics</h3> <ul> <li><code>shortName</code> is mandatory and MUST be a valid chain short name from https://github.com/ethereum-lists/chains</li> <li><code>address</code> is mandatory and MUST be a <a href="https://wg-eips.ritovision.com/55/">ERC-55</a> compatible hexadecimal address</li> </ul> <h3 id="examples">Examples</h3> <p><img src="https://wg-eips.ritovision.com/3770/./assets/examples.png" alt="Chain-specific addresses" title="Examples of chain-specific addresses" /></p> <h2 id="rationale">Rationale</h2> <p>To solve the initial problem of user-facing addresses being ambiguous in a multichain context, we need to map EIP-155 chain IDs with a user-facing format of displaying chain identifiers.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Ethereum addresses without the chain specifier will continue to require additional context to understand which chain the address refers to.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Similar looking chain short names can be used to confuse 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> 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-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 Mikhail Kalininhttps://github.com/mkalinin Danny Ryanhttps://github.com/djrtwo Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/3675/

Specification of the consensus mechanism upgrade on Ethereum Mainnet that introduces Proof-of-Stake

<h2 id="abstract">Abstract</h2> <p>This EIP deprecates Proof-of-Work (PoW) and supersedes it with the new Proof-of-Stake consensus mechanism (PoS) driven by the beacon chain. Information on the bootstrapping of the new consensus mechanism is documented in <a href="https://wg-eips.ritovision.com/2982/">EIP-2982</a>. Full specification of the beacon chain can be found in the <code>ethereum/consensus-specs</code> repository.</p> <p>This document specifies the set of changes to the block structure, block processing, fork choice rule and network interface introduced by the consensus upgrade.</p> <h2 id="motivation">Motivation</h2> <p>The beacon chain network has been up and running since December 2020. Neither safety nor liveness failures were detected during this period of time. This long period of running without failure demonstrates the sustainability of the beacon chain system and its readiness to become a security provider for the Ethereum Mainnet.</p> <p>To understand the motivation of introducing the Proof-of-Stake consensus see the Motivation section of <a href="https://wg-eips.ritovision.com/2982/#motivation">EIP-2982</a>.</p> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions</h3> <ul> <li><strong>PoW block</strong>: Block that is built and verified by the existing proof-of-work mechanism. In other words, a block of the Ethereum network before the consensus upgrade.</li> <li><strong>PoS block</strong>: Block that is built and verified by the new proof-of-stake mechanism.</li> <li><strong>Terminal PoW block</strong>: A PoW block that satisfies the following conditions -- <code>pow_block.total_difficulty &gt;= TERMINAL_TOTAL_DIFFICULTY</code> <em>and</em> <code>pow_block.parent_block.total_difficulty &lt; TERMINAL_TOTAL_DIFFICULTY</code>. There can be more than one terminal PoW block in the network, e.g. multiple children of the same pre-terminal block.</li> <li><strong><code>TERMINAL_TOTAL_DIFFICULTY</code></strong> The amount of total difficulty reached by the network that triggers the consensus upgrade. Ethereum Mainnet configuration <strong>MUST</strong> have this parameter set to the value <code>58750000000000000000000</code>.</li> <li><strong><code>TRANSITION_BLOCK</code></strong> The earliest PoS block of the canonical chain, i.e. the PoS block with the lowest block height.</li> <li><strong><code>POS_FORKCHOICE_UPDATED</code></strong> An event occurring when the state of the proof-of-stake fork choice is updated.</li> <li><strong><code>FORK_NEXT_VALUE</code></strong> A block number set to the <code>FORK_NEXT</code> parameter for the upcoming consensus upgrade.</li> <li><strong><code>TERMINAL_BLOCK_HASH</code></strong> Designates the hash of the terminal PoW block if set, i.e. if not stubbed with <code>0x0000000000000000000000000000000000000000000000000000000000000000</code>.</li> <li><strong><code>TERMINAL_BLOCK_NUMBER</code></strong> Designates the number of the terminal PoW block if <code>TERMINAL_BLOCK_HASH</code> is set.</li> </ul> <h4 id="pos-events">PoS events</h4> <p>Events having the <code>POS_</code> prefix in the name (PoS events) are emitted by the new proof-of-stake consensus mechanism. They signify the corresponding assertion that has been made regarding a block specified by the event. The underlying logic of PoS events can be found in the beacon chain specification. On the occurrence of each PoS event the corresponding action that is specified by this EIP <strong>MUST</strong> be taken.</p> <p>The details provided below must be taken into account when reading those parts of the specification that refer to the PoS events:</p> <ul> <li>Reference to a block that is contained by PoS events is provided in a form of a block hash unless another is explicitly specified.</li> <li>A <code>POS_FORKCHOICE_UPDATED</code> event contains references to the head of the canonical chain and to the most recent finalized block. Before the first finalized block occurs in the system the finalized block hash provided by this event is stubbed with <code>0x0000000000000000000000000000000000000000000000000000000000000000</code>.</li> <li><strong><code>FIRST_FINALIZED_BLOCK</code></strong> The first finalized block that is designated by <code>POS_FORKCHOICE_UPDATED</code> event and has the hash that differs from the stub.</li> </ul> <h3 id="client-software-configuration">Client software configuration</h3> <p>The following set of parameters is a part of client software configuration and <strong>MUST</strong> be included into its binary distribution:</p> <ul> <li><code>TERMINAL_TOTAL_DIFFICULTY</code></li> <li><code>FORK_NEXT_VALUE</code></li> <li><code>TERMINAL_BLOCK_HASH</code></li> <li><code>TERMINAL_BLOCK_NUMBER</code></li> </ul> <p><em>Note</em>: If <code>TERMINAL_BLOCK_HASH</code> is stubbed with <code>0x0000000000000000000000000000000000000000000000000000000000000000</code> then <code>TERMINAL_BLOCK_HASH</code> and <code>TERMINAL_BLOCK_NUMBER</code> parameters <strong>MUST NOT</strong> take an effect.</p> <h3 id="pow-block-processing">PoW block processing</h3> <p>PoW blocks that are descendants of any terminal PoW block <strong>MUST NOT</strong> be imported. This implies that a terminal PoW block will be the last PoW block in the canonical chain.</p> <h3 id="constants">Constants</h3> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><strong><code>MAX_EXTRA_DATA_BYTES</code></strong></td><td><code>32</code></td></tr> </tbody></table> <h3 id="block-structure">Block structure</h3> <p>Beginning with <code>TRANSITION_BLOCK</code>, a number of previously dynamic block fields are deprecated by enforcing these values to instead be constants. Each block field listed in the table below <strong>MUST</strong> be replaced with the corresponding constant value.</p> <table><thead><tr><th>Field</th><th>Constant value</th><th>Comment</th></tr></thead><tbody> <tr><td><strong><code>ommersHash</code></strong></td><td><code>0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347</code></td><td><code>= Keccak256(RLP([]))</code></td></tr> <tr><td><strong><code>difficulty</code></strong></td><td><code>0</code></td><td></td></tr> <tr><td><strong><code>mixHash</code></strong></td><td><code>0x0000000000000000000000000000000000000000000000000000000000000000</code></td><td></td></tr> <tr><td><strong><code>nonce</code></strong></td><td><code>0x0000000000000000</code></td><td></td></tr> <tr><td><strong><code>ommers</code></strong></td><td><code>[]</code></td><td><code>RLP([]) = 0xc0</code></td></tr> </tbody></table> <p>Beginning with <code>TRANSITION_BLOCK</code>, the validation of the block's <strong><code>extraData</code></strong> field changes: The length of the block's <strong><code>extraData</code></strong> <strong>MUST</strong> be less than or equal to <strong><code>MAX_EXTRA_DATA_BYTES</code></strong> bytes.</p> <p><em>Note</em>: Logic and validity conditions of block fields that are <em>not</em> specified here <strong>MUST</strong> remain unchanged. Additionally, the overall block format <strong>MUST</strong> remain unchanged.</p> <p><em>Note</em>: Subsequent EIPs may override the constant values specified above to provide additional functionality. For an example, see <a href="https://wg-eips.ritovision.com/4399/">EIP-4399</a>.</p> <h3 id="block-validity">Block validity</h3> <p>Beginning with <code>TRANSITION_BLOCK</code>, the block validity conditions <strong>MUST</strong> be altered by the following:</p> <ul> <li>Remove verification of the block's <strong><code>difficulty</code></strong> value with respect to the difficulty formula.</li> <li>Remove verification of the block's <strong><code>nonce</code></strong> and <strong><code>mixHash</code></strong> values with respect to the Ethash function.</li> <li>Remove all validation rules that are evaluated over the list of ommers and each member of this list.</li> <li>Add verification of the fields noted in the <a href="https://wg-eips.ritovision.com/3675/#block-structure">block structure</a> section.</li> </ul> <p><em>Note</em>: If one of the new rules fails then the block <strong>MUST</strong> be invalidated.</p> <p><em>Note</em>: Validity rules that are not specified in the list above <strong>MUST</strong> remain unchanged.</p> <h4 id="transition-block-validity">Transition block validity</h4> <p>In addition to satisfying the above conditions, <code>TRANSITION_BLOCK</code> <strong>MUST</strong> be a child of a terminal PoW block. That is, a parent of <code>TRANSITION_BLOCK</code> <strong>MUST</strong> satisfy terminal PoW block conditions.</p> <h3 id="block-and-ommer-rewards">Block and ommer rewards</h3> <p>Beginning with <code>TRANSITION_BLOCK</code>, block and ommer rewards are deprecated. Specifically, the following actions <strong>MUST</strong> be taken:</p> <ul> <li>Remove increasing the balance of the block's <strong><code>beneficiary</code></strong> account by the block reward.</li> <li>Remove increasing the balance of the block's <strong><code>beneficiary</code></strong> account by the ommer inclusion reward per each ommer.</li> <li>Remove increasing the balance of the ommer's <strong><code>beneficiary</code></strong> account by the ommer block reward per each ommer.</li> </ul> <p><em>Note</em>: Transaction fee mechanics affecting the block's <code>beneficiary</code> account <strong>MUST</strong> remain unchanged.</p> <h3 id="fork-choice-rule">Fork choice rule</h3> <p>If set, <code>TERMINAL_BLOCK_HASH</code> parameter affects the PoW heaviest chain rule in the following way:</p> <ul> <li>Canonical blockchain <strong>MUST</strong> contain a block with the hash defined by <code>TERMINAL_BLOCK_HASH</code> parameter at the height defined by <code>TERMINAL_BLOCK_NUMBER</code> parameter.</li> </ul> <p><em>Note</em>: This rule is akin to block hash whitelisting functionality already present in client software implementations.</p> <p>As of the first <code>POS_FORKCHOICE_UPDATED</code> event, the fork choice rule <strong>MUST</strong> be altered in the following way:</p> <ul> <li>Remove the existing PoW heaviest chain rule.</li> <li>Adhere to the new PoS LMD-GHOST rule.</li> </ul> <p>The new PoS LMD-GHOST fork choice rule is specified as follows. On each occurrence of a <code>POS_FORKCHOICE_UPDATED</code> event including the first one, the following actions <strong>MUST</strong> be taken:</p> <ul> <li>Consider the chain starting at genesis and ending with the head block nominated by the event as the canonical blockchain.</li> <li>Set the head of the canonical blockchain to the corresponding block nominated by the event.</li> <li>Beginning with the <code>FIRST_FINALIZED_BLOCK</code>, set the most recent finalized block to the corresponding block nominated by the event.</li> </ul> <p>Changes to the block tree store that are related to the above actions <strong>MUST</strong> be applied atomically.</p> <p><em>Note</em>: This rule <strong>MUST</strong> be strictly enforced. "Optimistic" updates to the head <strong>MUST NOT</strong> be made. That is -- if a new block is processed on top of the current head block, this new block becomes the new head if and only if an accompanying <code>POS_FORKCHOICE_UPDATED</code> event occurs.</p> <h3 id="network">Network</h3> <h4 id="fork-identifier">Fork identifier</h4> <p>For the purposes of the <a href="https://wg-eips.ritovision.com/2124/">EIP-2124</a> fork identifier, nodes implementing this EIP <strong>MUST</strong> set the <code>FORK_NEXT</code> parameter to the <code>FORK_NEXT_VALUE</code>.</p> <h4 id="devp2p">devp2p</h4> <p>The networking stack <strong>SHOULD NOT</strong> send the following messages if they advertise the descendant of any terminal PoW block:</p> <ul> <li><code>NewBlockHashes (0x01)</code></li> <li><code>NewBlock (0x07)</code></li> </ul> <p>Beginning with receiving the <code>FIRST_FINALIZED_BLOCK</code>, the networking stack <strong>MUST</strong> discard the following ingress messages:</p> <ul> <li><code>NewBlockHashes (0x01)</code></li> <li><code>NewBlock (0x07)</code></li> </ul> <p>Beginning with receiving the finalized block next to the <code>FIRST_FINALIZED_BLOCK</code>, the networking stack <strong>MUST</strong> remove the handlers corresponding to the following messages:</p> <ul> <li><code>NewBlockHashes (0x01)</code></li> <li><code>NewBlock (0x07)</code></li> </ul> <p>Peers that keep sending these messages after the handlers have been removed <strong>SHOULD</strong> be disconnected.</p> <p><em>Note:</em> The logic of message handlers that are not affected by this section <strong>MUST</strong> remain unchanged.</p> <h2 id="rationale">Rationale</h2> <p>The changes specified in this EIP target a minimal requisite set of consensus and client software modifications to safely replace the existing proof-of-work consensus algorithm with the new proof-of-stake consensus represented by the already in-production beacon chain.</p> <p>This EIP was designed to minimize the complexity of hot-swapping the live consensus of the Ethereum network. Both the safety of the operation and time to production were taken into consideration. Additionally, a minimal changeset helps ensure that <em>most</em> smart contracts and services will continue to function as intended during and after the transition with little to no required intervention.</p> <h3 id="total-difficulty-triggering-the-upgrade">Total difficulty triggering the upgrade</h3> <p>See <a href="https://wg-eips.ritovision.com/3675/#terminal-total-difficulty-vs-block-number">Security considerations</a>.</p> <h3 id="parameterizing-terminal-block-hash">Parameterizing terminal block hash</h3> <p>See <a href="https://wg-eips.ritovision.com/3675/#terminal-pow-block-overriding">Security considerations</a>.</p> <h3 id="halting-the-import-of-pow-blocks">Halting the import of PoW blocks</h3> <p>See <a href="https://wg-eips.ritovision.com/3675/#halt-the-importing-of-pow-blocks">Security considerations</a>.</p> <h3 id="replacing-block-fields-with-constants">Replacing block fields with constants</h3> <p>Deprecated block fields are replaced with constant values to ensure the block format remains backwards compatible. Preserving the block format aids existing smart contracts and services in providing uninterrupted service during and after this transition.</p> <p>Particularly, this is important for those smart contracts that verify Merkle proofs of transaction/receipt inclusion and state by validating the hash of externally provided block header against the corresponding value returned by the <code>BLOCKHASH</code> operation.</p> <p>This change introduces an additional validity rule that enforces the replacement of deprecated block fields.</p> <h3 id="replacing-difficulty-with-0">Replacing <code>difficulty</code> with <code>0</code></h3> <p>After deprecating the proof-of-work the notion of difficulty no longer exists and replacing the block header <strong><code>difficulty</code></strong> field with <code>0</code> constant is semantically sound.</p> <h3 id="changing-block-validity-rules">Changing block validity rules</h3> <p>The rule set enforcing the PoW seal validity is replaced with the corresponding PoS rules along with the consensus upgrade as the rationale behind this change.</p> <p>An additional rule validating a set of deprecated block fields is required by the block format changes introduced by this specification.</p> <h3 id="removing-block-rewards">Removing block rewards</h3> <p>Existing rewards for producing and sealing blocks are deprecated along with the PoW mechanism. The new PoS consensus becomes both responsible for sealing blocks and for issuing block rewards once this specification enters into effect.</p> <h3 id="supplanting-fork-choice-rule">Supplanting fork choice rule</h3> <p>The fork choice rule of the PoW mechanism becomes completely irrelevant after the upgrade and is replaced with the corresponding rule of the new PoS consensus mechanism.</p> <h3 id="remove-of-pos-consensus-validated">Remove of <code>POS_CONSENSUS_VALIDATED</code></h3> <p>In prior draft versions of this EIP, an additional POS event -- <code>POS_CONSENSUS_VALIDATED</code> -- was required as a validation condition for blocks. This event gave the signal to either fully incorporate or prune the block from the block tree.</p> <p>This event was removed for two reasons:</p> <ol> <li>This event was an unnecessary optimization to allow for pruning of "bad" blocks from the block tree. This optimization was unnecessary because the PoS consensus would never send <code>POS_FORKCHOICE_UPDATED</code> for any such bad blocks or their descendants, and eventually any such blocks would be able to be pruned after a PoS finality event of an alternative branch in the block tree.</li> <li>This event was dangerous in some scenarios because a block could be referenced by two <em>different</em> and conflicting PoS branches. Thus for the same block in some scenarios, both a <code>POS_CONSENSUS_VALIDATED == TRUE</code> and <code>POS_CONSENSUS_VALIDATED == FALSE</code> event could sent, entirely negating the ability to safely perform the optimization in (1).</li> </ol> <h3 id="eip-2124-fork-identifier">EIP-2124 fork identifier</h3> <p>The value of <code>FORK_NEXT</code> in EIP-2124 refers to the block number of the next fork a given node knows about and <code>0</code> otherwise.</p> <p>The number of <code>TRANSITION_BLOCK</code> cannot be known ahead of time given the dynamic nature of the transition trigger condition. As the block will not be known a priori, nodes can't use its number for <code>FORK_NEXT</code> and in light of this fact an explicitly set <code>FORK_NEXT_VALUE</code> is used instead.</p> <h3 id="removing-block-gossip">Removing block gossip</h3> <p>After the upgrade of the consensus mechanism only the beacon chain network will have enough information to validate a block. Thus, block gossip provided by the <code>eth</code> network protocol will become unsafe and is deprecated in favour of the block gossip existing in the beacon chain network.</p> <p>It is recommended for the client software to not propagate descendants of any terminal PoW block to reduce the load on processing the P2P component and stop operating in the environment with unknown security properties.</p> <h3 id="restricting-the-length-of-extradata">Restricting the length of <code>extraData</code></h3> <p>The <code>extraData</code> field is defined as a maximum of <code>32</code> bytes in the yellow paper. Thus mainnet and most PoW testnets cap the value at <code>32</code> bytes. <code>extraData</code> fields of greater length are used by clique testnets and other networks to carry special signature/consensus schemes. This EIP restricts the length of <code>extraData</code> to <code>32</code> bytes because any network that is transitioning from another consensus mechanism to a beacon chain PoS consensus mechanism no longer needs extended or unbounded <code>extraData</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces backward incompatibilities in block validity, block rewards and fork choice rule.</p> <p>The design of the consensus upgrade specified by this document does not introduce backward incompatibilities for existing applications and services built on top of Ethereum except for those that are described in the <a href="https://wg-eips.ritovision.com/3675/#evm">EVM</a> section below or heavily depends on the PoW consensus in any other way.</p> <h3 id="evm">EVM</h3> <p>Although this EIP does not introduce any explicit changes to the EVM there are a couple of places where it may affect the logic of existing smart contracts.</p> <h4 id="difficulty">DIFFICULTY</h4> <p><code>DIFFICULTY</code> operation will always return <code>0</code> after this EIP takes effect and deprecates the <strong><code>difficulty</code></strong> field by replacing it with <code>0</code> constant.</p> <p><em>Note:</em> Altering the <code>DIFFICULTY</code> semantics to return randomness accumulated by the beacon chain is under consideration but will be introduced in a separate EIP.</p> <h4 id="blockhash">BLOCKHASH</h4> <p>Pseudo-random numbers obtained as the output of <code>BLOCKHASH</code> operation become more insecure after this EIP takes effect and the PoW mechanism (which decreases the malleability of block hashes) gets supplanted by PoS.</p> <h2 id="test-cases">Test Cases</h2> <ul> <li>Block validity <ul> <li>Beginning with <code>TRANSITION_BLOCK</code>, block is invalidated if any of the following is true: <ul> <li><code>ommersHash != Keccak256(RLP([]))</code></li> <li><code>difficulty != 0</code></li> <li><code>nonce != 0x0000000000000000</code></li> <li><code>len(extraData) &gt; MAX_EXTRA_DATA_BYTES</code></li> </ul> </li> <li>Beginning with <code>TRANSITION_BLOCK</code>, block rewards aren't added to <code>beneficiary</code> account</li> </ul> </li> <li>Client software adheres to PoS LMD-GHOST rule <ul> <li>Head and finalized blocks are set according to the recent <code>POS_FORKCHOICE_UPDATED</code> event</li> <li>No fork choice state is updated unless <code>POS_FORKCHOICE_UPDATED</code> event is received</li> </ul> </li> <li>Transition process <ul> <li>Client software doesn't process any PoW block beyond a terminal PoW block</li> <li>Beginning with <code>TRANSITION_BLOCK</code>, client software applies new block validity rules</li> <li>Beginning with the first <code>POS_FORKCHOICE_UPDATED</code>, client software switches its fork choice rule to PoS LMD-GHOST</li> <li><code>TRANSITION_BLOCK</code> must be a child of a terminal PoW block</li> <li><code>NewBlockHashes (0x01)</code> and <code>NewBlock (0x07)</code> network messages are discarded after receiving the <code>FIRST_FINALIZED_BLOCK</code></li> </ul> </li> </ul> <h2 id="security-considerations">Security Considerations</h2> <h3 id="beacon-chain">Beacon chain</h3> <p>See Security Considerations section of <a href="https://wg-eips.ritovision.com/2982/#security-considerations">EIP-2982</a>.</p> <h3 id="transition-process">Transition process</h3> <p>The transition process used to take this specification into effect is a more sophisticated version of a hardfork -- the regular procedure of applying backwards incompatible changes in the Ethereum network. This process has multiple successive steps instead of the normal block-height point condition of simpler hardforks.</p> <p>The complexity of this upgrade process stems from this fork targeting the underlying consensus mechanism rather than the execution layer within the consensus mechanism. Although the design seeks simplicity where possible, safety and liveness considerations during this transition have been prioritized.</p> <h4 id="terminal-total-difficulty-vs-block-number">Terminal total difficulty vs block number</h4> <p>Using a pre-defined block number for the hardfork is unsafe in this context due to the PoS fork choice taking priority during the transition.</p> <p>An attacker may use a minority of hash power to build a malicious chain fork that would satisfy the block height requirement. Then the first PoS block may be maliciously proposed on top of the PoW block from this adversarial fork, becoming the head and subverting the security of the transition.</p> <p>To protect the network from this attack scenario, difficulty accumulated by the chain (total difficulty) is used to trigger the upgrade.</p> <h4 id="ability-to-jump-between-terminal-pow-blocks">Ability to jump between terminal PoW blocks</h4> <p>There could be the case when a terminal PoW block is not observed by the majority of network participants due to (temporal) network partitioning. In such a case, this minority would switch their fork choice to the new rule provided by the PoS rooted on the minority terminal PoW block that they observed.</p> <p>The transition process allows the network to re-org between forks with different terminal PoW blocks as long as (a) these blocks satisfy the terminal PoW block conditions and (b) the <code>FIRST_FINALIZED_BLOCK</code> has not yet been received. This provides resilience against adverse network conditions during the transition process and prevents irreparable forks/partitions.</p> <h4 id="halt-the-importing-of-pow-blocks">Halt the importing of PoW blocks</h4> <p>Suppose the part of the client software that is connected to the beacon chain network goes offline before the Ethereum network reaches the <code>TERMINAL_TOTAL_DIFFICULTY</code> and stays offline while the network meets this threshold. Such an event makes the client software unable to switch to PoS and allows it to keep following the PoW chain if this chain is being built beyond the terminal PoW block. Depending on how long the beacon chain part was offline, it could result in different adverse effects such as:</p> <ul> <li>The client has no post-state for the terminal PoW block (the state has been pruned) which prevents it from doing the re-org to the PoS chain and leaving syncing from scratch as the only option to recover.</li> <li>An application, a user or a service uses the data from the wrong fork (PoW chain that is kept being built) which can cause security issues on their side.</li> </ul> <p>Not importing PoW blocks that are beyond the terminal PoW block prevents these adverse effects on safety/re-orgs in the event of software or configuration failures <em>in favor</em> of a liveness failure.</p> <h4 id="terminal-pow-block-overriding">Terminal PoW block overriding</h4> <p>There is a mechanism allowing for accelerating the consensus upgrade in emergency cases. This EIP considers the following emergency case scenarios for the acceleration to come into effect:</p> <ul> <li>A drop of the network hashing rate which delays the upgrade significantly.</li> <li>Attacks on the PoW network before the upgrade.</li> </ul> <p>The first case can be safely accelerated by updating the following parameters:</p> <ul> <li><code>TERMINAL_TOTAL_DIFFICULTY</code> -- reset to a value that is closer in time than the original one.</li> <li><code>FORK_NEXT_VALUE</code> -- adjust accordingly.</li> </ul> <p>The second, more dire attack scenario requires a more invasive override:</p> <ul> <li><code>TERMINAL_BLOCK_HASH</code> -- set to the hash of a certain block to become the terminal PoW block.</li> <li><code>TERMINAL_BLOCK_NUMBER</code> -- set to the number of a block designated by <code>TERMINAL_BLOCK_HASH</code>.</li> <li><code>TERMINAL_TOTAL_DIFFICULTY</code> -- set to the total difficulty value of a block designated by <code>TERMINAL_BLOCK_HASH</code>.</li> <li><code>FORK_NEXT_VALUE</code> -- adjust accordingly.</li> </ul> <p><em>Note</em>: Acceleration in the second case is considered for the most extreme of scenarios because it will result in a non-trivial liveness failure on Ethereum Mainnet.</p> <h3 id="ancient-blocks-are-no-longer-a-requisite-for-a-network-security">Ancient blocks are no longer a requisite for a network security</h3> <p>Keeping historical blocks starting from genesis is essential in the PoW network. A header of every block that belongs to a particular chain is required to justify the validity of this chain with respect to the PoW seal.</p> <p>Validating the entire history of the chain is not required by the new PoS mechanism. Instead, the sync process in the PoS network relies on weak subjectivity checkpoints, which are historical snapshots shared by peers on the network. This means historical blocks beyond weak subjectivity checkpoint are no longer a requisite for determining the canonical blockchain.</p> <p>Specification of weak subjectivity checkpoints can be found in the <code>ethereum/consensus-specs</code> repository.</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-20T00:00:00+00:00 2026-02-11T14:48:26+00:00 Oliver Terbuhttps://github.com/awoie Jacob Wardhttps://github.com/cobward Charles Lehnerhttps://github.com/clehner Sam Gbafahttps://github.com/skgbafa Wayne Changhttps://github.com/wyc Charles Cunninghamhttps://github.com/chunningham https://wg-eips.ritovision.com/5573/

Mechanism on top of Sign-In with Ethereum for informed consent to delegate capabilities with an extensible scope mechanism

<h2 id="abstract">Abstract</h2> <p><a href="https://wg-eips.ritovision.com/4361/">ERC-4361</a>, or Sign-In with Ethereum (SIWE), describes how Ethereum accounts authenticate with off-chain services. This proposal, known as ReCaps, describes a mechanism on top of SIWE to give informed consent to authorize a Relying Party to exercise certain scoped capabilities. How a Relying Party authenticates against the target resource is out of scope for this specification and depends on the implementation of the target resource.</p> <h2 id="motivation">Motivation</h2> <p>SIWE ReCaps unlock integration of protocols and/or APIs for developers by reducing user friction, onchain state and increasing security by introducing informed consent and deterministic capability objects on top of Sign-In With Ethereum (ERC-4361).</p> <p>While SIWE focuses on authenticating the Ethereum account against the service (relying party or SIWE client) initiating the SIWE flow, there is no canonical way for the authenticated Ethereum account to authorize a relying party to interact with a third-party service (resource service) on behalf of the Ethereum account. A relying party may want to interact with another service on behalf of the Ethereum account, for example a service that provides data storage for the Ethereum account. This specification introduces a mechanism that allows the service (or more generally a Relying Party) to combine authentication and authorization of such while preserving security and optimizing UX.</p> <p>Note, this approach is a similar mechanism to combining OpenID Connect (SIWE auth) and OAuth2 (SIWE ReCap) where SIWE ReCap implements capabilities-based authorization on top of the authentication provided by SIWE.</p> <h2 id="specification">Specification</h2> <p>This specification has three different audiences:</p> <ul> <li>Web3 application developers that want to integrate ReCaps to authenticate with any protocols and APIs that support object capabilities.</li> <li>Protocol or API developers that want to learn how to define their own ReCaps.</li> <li>Wallet implementers that want to improve the UI for ReCaps.</li> </ul> <h3 id="terms-and-definitions">Terms and Definitions</h3> <ul> <li>ReCap - A SIWE Message complying with this specification, i.e. containing at least one ReCap URI in the <code>Resources</code> section and the corresponding human-readable ReCap Statement appended to the SIWE <code>statement</code>.</li> <li>ReCap URI - A type of URI that resolves to a ReCap Details Object.</li> <li>ReCap Details Object - A JSON object describing the actions and optionally the resources associated with a ReCap Capability.</li> <li>Resource Service (RS) - The entity that is providing third-party services for the Ethereum account.</li> <li>SIWE Client (SC) - The entity initiating the authorization (SIWE authentication and ReCap flow).</li> <li>Relying Party (RP) - same as SC in the context of authorization.</li> </ul> <h3 id="overview">Overview</h3> <p>This specification defines the following:</p> <ul> <li>ReCap SIWE Extension</li> <li>ReCap Capability <ul> <li>ReCap URI Scheme</li> <li>ReCap Details Object Schema</li> </ul> </li> <li>ReCap Translation Algorithm</li> <li>ReCap Verification</li> </ul> <h3 id="recap-siwe-extension">ReCap SIWE Extension</h3> <p>A ReCap is an ERC-4361 message following a specific format that allows an Ethereum account to delegate a set of ReCap Capabilities to a Relying Party through informed consent. ReCap Capabilities MUST be represented by the final entry in the <code>Resources</code> array of the SIWE message that MUST deterministically translate the ReCap Capability in human-readable form to the <code>statement</code> field in the SIWE message using the ReCap Translation Algorithm.</p> <p>The following SIWE message fields are used to further define (or limit) the scope of all ReCap Capabilities:</p> <ul> <li>The <code>URI</code> field MUST specify the intended Relying Party, e.g., <code>https://example.com</code>, <code>did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK</code>. It is expected that the RS authenticates the Relying Party before invoking an action for the ReCap Capability.</li> <li>The <code>Issued At</code> field MUST be used to specify the issuance date of the ReCap Capabilities.</li> <li>If present, the <code>Expiration Time</code> field MUST be used as the expiration time of the ReCap Capabilities, i.e. the time at which the RS will no longer accept an invocation of the capabilities expressed in this form.</li> <li>If present, the <code>Not Before</code> field MUST be used as the time that has to expire before the RS starts accepting invocations of the capabilities expressed in the message.</li> </ul> <p>The following is a non-normative example of a SIWE message with the SIWE ReCap Extension:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>example.com wants you to sign in with your Ethereum account:</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>I further authorize the stated URI to perform the following actions on my behalf: (1) &#39;example&#39;: &#39;append&#39;, &#39;read&#39; for &#39;https://example.com&#39;. (2) &#39;other&#39;: &#39;action&#39; for &#39;https://example.com&#39;. (3) &#39;example&#39;: &#39;append&#39;, &#39;delete&#39; for &#39;my:resource:uri.1&#39;. (4) &#39;example&#39;: &#39;append&#39; for &#39;my:resource:uri.2&#39;. (5) &#39;example&#39;: &#39;append&#39; for &#39;my:resource:uri.3&#39;.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>URI: did:key:example</span></span> <span class="giallo-l"><span>Version: 1</span></span> <span class="giallo-l"><span>Chain ID: 1</span></span> <span class="giallo-l"><span>Nonce: mynonce1</span></span> <span class="giallo-l"><span>Issued At: 2022-06-21T12:00:00.000Z</span></span> <span class="giallo-l"><span>Resources:</span></span> <span class="giallo-l"><span>- urn:recap:eyJhdHQiOnsiaHR0cHM6Ly9leGFtcGxlLmNvbSI6eyJleGFtcGxlL2FwcGVuZCI6W10sImV4YW1wbGUvcmVhZCI6W10sIm90aGVyL2FjdGlvbiI6W119LCJteTpyZXNvdXJjZTp1cmkuMSI6eyJleGFtcGxlL2FwcGVuZCI6W10sImV4YW1wbGUvZGVsZXRlIjpbXX0sIm15OnJlc291cmNlOnVyaS4yIjp7ImV4YW1wbGUvYXBwZW5kIjpbXX0sIm15OnJlc291cmNlOnVyaS4zIjp7ImV4YW1wbGUvYXBwZW5kIjpbXX19LCJwcmYiOltdfQ</span></span></code></pre><h4 id="recap-capability">ReCap Capability</h4> <p>A ReCap Capability is identified by their ReCap URI that resolves to a ReCap Details Object which defines the associated actions and optional target resources. The scope of each ReCap Capability is attenuated by common fields in the SIWE message as described in the previous chapter, e.g., <code>URI</code>, <code>Issued At</code>, <code>Expiration Time</code>, <code>Not Before</code>.</p> <h5 id="recap-uri-scheme">ReCap URI Scheme</h5> <p>A ReCap URI starts with <code>urn:recap:</code> followed by the unpadded base64url-encoded payload of the ReCap Details Object. Note, the term base64url is defined in RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet. If present, a Recap URI MUST occupy the final entry of the SIWE resource list.</p> <p>The following is a non-normative example of a ReCap Capability:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>urn:recap:eyJhdHQiOnsiaHR0cHM6Ly9leGFtcGxlLmNvbS9waWN0dXJlcy8iOnsiY3J1ZC9kZWxldGUiOlt7fV0sImNydWQvdXBkYXRlIjpbe31dLCJvdGhlci9hY3Rpb24iOlt7fV19LCJtYWlsdG86dXNlcm5hbWVAZXhhbXBsZS5jb20iOnsibXNnL3JlY2VpdmUiOlt7Im1heF9jb3VudCI6NSwidGVtcGxhdGVzIjpbIm5ld3NsZXR0ZXIiLCJtYXJrZXRpbmciXX1dLCJtc2cvc2VuZCI6W3sidG8iOiJzb21lb25lQGVtYWlsLmNvbSJ9LHsidG8iOiJqb2VAZW1haWwuY29tIn1dfX0sInByZiI6WyJ6ZGo3V2o2Rk5TNHJVVWJzaUp2amp4Y3NOcVpkRENTaVlSOHNLUVhmb1BmcFNadUF3Il19</span></span></code></pre><h5 id="ability-strings">Ability Strings</h5> <p>Ability Strings identify an action or Ability within a Namespace. They are serialized as <code>&lt;namespace&gt;/&lt;ability&gt;</code>. Namespaces and Abilities MUST contain only alphanumeric characters as well as the characters <code>.</code>, <code>*</code>, <code>_</code>, <code>+</code>, <code>-</code>, conforming to the regex <code>^[a-zA-Z0-9.*_+-]$</code>. The ability string as a whole MUST conform to <code>^[a-zA-Z0-9.*_+-]+\/[a-zA-z0-9.*_+-]+$</code>. For example, <code>crud/update</code> has an ability-namespace of <code>crud</code> and an ability-name of <code>update</code>.</p> <h5 id="recap-details-object-schema">ReCap Details Object Schema</h5> <p>The ReCap Details Object denotes which actions on which resources the Relying Party is authorized to invoke on behalf of the Ethereum account for the validity period defined in the SIWE message. It can also contain additional information that the RS may require to verify a capability invocation. A ReCap Details Object MUST follow the following JSON Schema:</p> <pre class="giallo z-code"><code data-lang="jsonc"><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">http://json-schema.org/draft-04/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">att</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">propertyNames</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">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">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">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">^[a-zA-Z0-9.*_+-]+</span><span class="z-constant">\/</span><span class="z-support">[a-zA-z0-9.*_+-]+$</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">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 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">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 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">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 class="giallo-l"><span> }</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> {</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">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">CID</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">minItems</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</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>A ReCap Details Object defines the following properties:</p> <ul> <li><code>att</code>: (CONDITIONAL) If present, <code>att</code> MUST be a JSON object where each key is a URI and each value is an object containing Ability Strings as keys and a corresponding value which is an array of qualifications to the action (i.e. a restriction or requirement). The keys of the object MUST be ordered lexicographically.</li> <li><code>prf</code>: (CONDITIONAL) If present, <code>prf</code> MUST be a JSON array of string values with at least one entry where each value is a valid Base58-encoded CID which identifies a parent capability, authorizing the Ethereum account for one or more of the entries in <code>att</code> if the SIWE <code>address</code> does not identify the controller of the <code>att</code> entries.</li> </ul> <p>Objects in the <code>att</code> field (including nested objects) MUST NOT contain duplicate keys and MUST have their keys ordered lexicographically with two steps:</p> <ol> <li>Sort by byte value.</li> <li>If a string starts with another, the shorter string comes first (e.g. <code>msg/send</code> comes before <code>msg/send-to</code>)</li> </ol> <p>This is the same as the <code>Array.sort()</code> method in JavaScript. In the example below, <code>crud/delete</code> must appear before <code>crud/update</code> and <code>other/action</code>, similarly <code>msg/receive</code> must appear before <code>msg/send</code>.</p> <p>The following is a non-normative example of a ReCap Capability Object with <code>att</code> and <code>prf</code>:</p> <pre class="giallo z-code"><code data-lang="jsonc"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">att</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">https://example.com/pictures/</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">crud/delete</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span>{</span><span>}</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">crud/update</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span>{</span><span>}</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">other/action</span><span class="z-support">&quot;</span><span>:</span><span> [</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">mailto:username@example.com</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">msg/receive</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">max_count</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 5</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">templates</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">newsletter</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">marketing</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span> }</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">msg/send</span><span class="z-support">&quot;</span><span>:</span><span> [</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">someone@email.com</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span><span>,</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">joe@email.com</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></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>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">bafybeigk7ly3pog6uupxku3b6bubirr434ib6tfaymvox6gotaaaaaaaaa</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>In the example above, the Relying Party is authorized to perform the actions <code>crud/update</code>, <code>crud/delete</code> and <code>other/action</code> on resource <code>https://example.com/pictures/</code> without limitations for any. Additionally the Relying Party is authorized to perform actions <code>msg/send</code> and <code>msg/recieve</code> on resource <code>mailto:username@example.com</code>, where <code>msg/send</code> is limited to sending to <code>someone@email.com</code> or <code>joe@email.com</code> and <code>msg/recieve</code> is limited to a maximum of 5 and templates <code>newsletter</code> or <code>marketing</code>. Note, the Relying Party can invoke each action individually and independently from each other in the RS. Additionally the ReCap Capability Object contains some additional information that the RS will need during verification. The responsibility for defining the structure and semantics of this data lies with the RS. These action and restriction semantics are examples not intended to be universally understood. The Nota Bene objects appearing in the array associated with ability strings represent restrictions on use of an ability. An empty object implies that the action can be performed with no restrictions, but an empty array with no objects implies that there is no way to use this ability in a valid way.</p> <p>It is expected that RS implementers define which resources they want to expose through ReCap Details Objects and which actions they want to allow users to invoke on them.</p> <p>This example is expected to transform into the following <code>recap-transformed-statement</code> (for <code>URI</code> of <code>https://example.com</code>):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>I further authorize the stated URI to perform the following actions on my behalf: (1) &#39;crud&#39;: &#39;delete&#39;, &#39;update&#39; for &#39;https://example.com/pictures/&#39;. (2) &#39;other&#39;: &#39;action&#39; for &#39;https://example.com/pictures/&#39;. (3) &#39;msg&#39;: &#39;receive&#39;, &#39;send&#39; for &#39;mailto:username@example.com&#39;.</span></span></code></pre> <p>This example is also expected to transform into the following <code>recap-uri</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>urn:recap:eyJhdHQiOnsiaHR0cHM6Ly9leGFtcGxlLmNvbS9waWN0dXJlcy8iOnsiY3J1ZC9kZWxldGUiOlt7fV0sImNydWQvdXBkYXRlIjpbe31dLCJvdGhlci9hY3Rpb24iOlt7fV19LCJtYWlsdG86dXNlcm5hbWVAZXhhbXBsZS5jb20iOnsibXNnL3JlY2VpdmUiOlt7Im1heF9jb3VudCI6NSwidGVtcGxhdGVzIjpbIm5ld3NsZXR0ZXIiLCJtYXJrZXRpbmciXX1dLCJtc2cvc2VuZCI6W3sidG8iOiJzb21lb25lQGVtYWlsLmNvbSJ9LHsidG8iOiJqb2VAZW1haWwuY29tIn1dfX0sInByZiI6WyJ6ZGo3V2o2Rk5TNHJVVWJzaUp2amp4Y3NOcVpkRENTaVlSOHNLUVhmb1BmcFNadUF3Il19</span></span></code></pre><h5 id="merging-capability-objects">Merging Capability Objects</h5> <p>Any two Recap objects can be merged together by recursive concatenation of their field elements as long as the ordering rules of the field contents is followed. For example, two recap objects:</p> <pre class="giallo z-code"><code data-lang="jsonc"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">att</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">https://example1.com</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">crud/read</span><span class="z-support">&quot;</span><span>:</span><span> [</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 class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">prf</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">bafyexample1</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>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">att</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">https://example1.com</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">crud/update</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">max_times</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> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">https://example2.com</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">crud/delete</span><span class="z-support">&quot;</span><span>:</span><span> [</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 class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">prf</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">bafyexample2</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>combine into:</p> <pre class="giallo z-code"><code data-lang="jsonc"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">att</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">https://example1.com</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">crud/read</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span>{</span><span>}</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">crud/update</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">max_times</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> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">https://example2.com</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">crud/delete</span><span class="z-support">&quot;</span><span>:</span><span> [</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 class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">prf</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">bafyexample1</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">bafyexample2</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="recap-translation-algorithm">ReCap Translation Algorithm</h4> <p>After applying the ReCap Translation Algorithm on a given SIWE message that MAY include a pre-defined <code>statement</code>, the <code>recap-transformed-statement</code> in a ReCap SIWE message MUST conform to the following ABNF:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>recap-transformed-statement = statement recap-preamble 1*(&quot; &quot; recap-statement-entry &quot;.&quot;)</span></span> <span class="giallo-l"><span> ; see ERC-4361 for definition of input-statement</span></span> <span class="giallo-l"><span>recap-preamble = &quot;I further authorize the stated URI to perform the following actions on my behalf:&quot;</span></span> <span class="giallo-l"><span>recap-statement-entry = &quot;(&quot; number &quot;) &quot; action-namespace &quot;: &quot; </span></span> <span class="giallo-l"><span> action-name *(&quot;,&quot; action-name) &quot;for&quot;</span></span> <span class="giallo-l"><span> recap-resource</span></span> <span class="giallo-l"><span> ; see RFC8259 for definition of number</span></span> <span class="giallo-l"><span>ability-namespace = string</span></span> <span class="giallo-l"><span> ; see RFC8259 for definition of string</span></span> <span class="giallo-l"><span>ability-name = string</span></span> <span class="giallo-l"><span> ; see RFC8259 for definition of string</span></span> <span class="giallo-l"><span>recap-resource = string</span></span> <span class="giallo-l"><span> ; see RFC8259 for definition of string</span></span></code></pre> <p>The following algorithm or an algorithm that produces the same output MUST be performed to generate the SIWE ReCap Transformed Statement.</p> <p>Inputs:</p> <ul> <li>Let <code>recap-uri</code> be a ReCap URI, which represents the ReCap Capabilities that are to be encoded in the SIWE message, and which contains a ReCap Details Object which conforms to the ReCap Details Object Schema.</li> <li>[Optional] Let <code>statement</code> be the statement field of the input SIWE message conforming to ERC-4361. Algorithm:</li> <li>Let <code>recap-transformed-statement</code> be an empty string value.</li> <li>If <code>statement</code> is present, do the following: <ul> <li>Append the value of the <code>statement</code> field of <code>siwe</code> to <code>recap-transformed-statement</code>.</li> <li>Append a single space character <code>" "</code> to <code>recap-transformed-statement</code>.</li> </ul> </li> <li>Append the following string to <code>recap-transformed-statement</code>: <code>"I further authorize the stated URI to perform the following actions on my behalf:"</code>.</li> <li>Let <code>numbering</code> be an integer starting with 1.</li> <li>Let <code>attenuations</code> be the <code>att</code> field of the ReCap Details Object</li> <li>For each key and value pair in <code>attenuations</code> (starting with the first entry), perform the following: <ul> <li>Let <code>resource</code> be the key and <code>abilities</code> be the value</li> <li>Group the keys of the <code>abilities</code> object by their <code>ability-namespace</code></li> <li>For each <code>ability-namespace</code>, perform the following: <ul> <li>Append the string concatenation of <code>" ("</code>, <code>numbering</code>, <code>")"</code> to <code>recap-transformed-statement</code>.</li> <li>Append the string concatenation of <code>'</code>, <code>ability-namespace</code>, <code>':</code> to <code>recap-transformed-statement</code>.</li> <li>For each <code>ability-name</code> in the <code>ability-namespace</code> group, perform the following: <ul> <li>Append the string concatenation of <code>'</code>, <code>ability-name</code>, <code>'</code> to <code>recap-transformed-statement</code></li> <li>If not the final <code>ability-name</code>, append <code>,</code> to <code>recap-transformed-statement</code></li> </ul> </li> <li>Append <code>for '</code>, <code>resource</code>, <code>'.</code> to <code>recap-transformed-statement</code></li> <li>Increase <code>numbering</code> by 1</li> </ul> </li> </ul> </li> <li>Return <code>recap-transformed-statement</code>.</li> </ul> <h4 id="recap-verification-algorithm">ReCap Verification Algorithm</h4> <p>The following algorithm or an algorithm that produces the same output MUST be performed to verify a SIWE ReCap.</p> <p>Inputs:</p> <ul> <li>Let <code>recap-siwe</code> be the input SIWE message conforming to ERC-4361 and this EIP.</li> <li>Let <code>siwe-signature</code> be the output of signing <code>recap-siwe</code>, as defined in ERC-4361. Algorithm:</li> <li>Perform ERC-4361 signature verification with <code>recap-siwe</code> and <code>siwe-signature</code> as inputs.</li> <li>Let <code>uri</code> be the uri field of <code>recap-siwe</code>.</li> <li>Let <code>recap-uri</code> be a recap URI taken from the last entry of the resources field of <code>recap-siwe</code>.</li> <li>Let <code>recap-transformed-statement</code> be the result of performing the above <code>ReCap Translation Algorithm</code> with <code>uri</code> and <code>recap-uri</code> as input.</li> <li>Assert that the statement field of <code>recap-siwe</code> ends with <code>recap-transformed-statement</code>.</li> </ul> <h3 id="implementer-s-guide">Implementer's Guide</h3> <p>TBD</p> <h4 id="web3-application-implementers">Web3 Application Implementers</h4> <p>TBD</p> <h4 id="wallet-implementers">Wallet Implementers</h4> <p>TBD</p> <h4 id="protocol-or-api-implementers">Protocol or API Implementers</h4> <p>TBD</p> <h2 id="rationale">Rationale</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>Resource service implementer's should not consider ReCaps as bearer tokens but instead require to authenticate the Relying Party in addition. The process of authenticating the Relying Party against the resource service is out of scope of this specification and can be done in various different ways.</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 Martin Holst Swendehttps://github.com/holiman Paweł Bylicahttps://github.com/chfast Alex Beregszaszihttps://github.com/axic Andrei Maiborodahttps://github.com/gumb0 https://wg-eips.ritovision.com/3860/

Limit the maximum size of initcode to 49152 and apply extra gas cost of 2 for every 32-byte chunk of initcode

<h2 id="abstract">Abstract</h2> <p>We extend <a href="https://wg-eips.ritovision.com/170/">EIP-170</a> by introducing a maximum size limit for <code>initcode</code> (<code>MAX_INITCODE_SIZE = 2 * MAX_CODE_SIZE = 49152</code>).</p> <p>Furthermore, we introduce a charge of <code>2</code> gas for every 32-byte chunk of <code>initcode</code> to represent the cost of jumpdest-analysis.</p> <p>Lastly, the size limit results in the nice-to-have property that EVM code size, code offset (<code>PC</code>), and jump offset fits a 16-bit value.</p> <h2 id="motivation">Motivation</h2> <p>During contract creation the client has to perform jumpdest-analysis on the <code>initcode</code> prior to execution. The work performed scales linearly with the size of the <code>initcode</code>. This work currently is not metered, nor is there a protocol enforced upper bound for the size.</p> <p>There are three costs charged today:</p> <ol> <li>Cost for calldata aka <code>initcode</code>: 4 gas for a byte with the value of zero, and 16 gas otherwise.</li> <li>Cost for the resulting deployed code: 200 gas per byte.</li> <li>Cost of address calculation (hashing of code) in case of <code>CREATE2</code> only: 6 gas per word.</li> </ol> <p>Only the first cost applies to <code>initcode</code>, but only in the case of contract creation transactions. For the case of <code>CREATE</code>/<code>CREATE2</code> there is no such cost, and it is possible to programmatically generate variations of <code>initcode</code> in a relatively cheap manner. In the past it was possible to craft malicious <code>initcode</code> due to a vulnerability fixed in 2017 by geth 1.6.5.</p> <p>Furthermore, the lack of a limit has caused lengthy discussions for some EVM proposals, influencing the design, or even causing a delay or cancellation of a feature.</p> <p>We are motivated by three reasons:</p> <ol> <li>Ensuring <code>initcode</code> is fairly charged (most importantly cost is proportional to <code>initcode</code>'s length) to minimize the risks for the future.</li> <li>To have a cost system which is extendable in the future.</li> <li>To simplify EVM engines by the explicit limits (code size, code offsets (<code>PC</code>), and jump offsets fit 16-bits).</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><code>INITCODE_WORD_COST</code></td><td><code>2</code></td></tr> <tr><td><code>MAX_INITCODE_SIZE</code></td><td><code>2 * MAX_CODE_SIZE</code></td></tr> </tbody></table> <p>Where <code>MAX_CODE_SIZE</code> is defined by <a href="https://wg-eips.ritovision.com/170/">EIP-170</a> as <code>24576</code>.</p> <p>We define <code>initcode_cost(initcode)</code> to equal <code>INITCODE_WORD_COST * ceil(len(initcode) / 32)</code>.</p> <h3 id="rules">Rules</h3> <ol> <li>If length of transaction data (<code>initcode</code>) in a create transaction exceeds <code>MAX_INITCODE_SIZE</code>, transaction is invalid. (<em>Note that this is similar to transactions considered invalid for not meeting the intrinsic gas cost requirement.</em>)</li> <li>For a create transaction, extend the transaction data cost formula to include <code>initcode_cost(initcode)</code>. (<em>Note that this is included in transaction intrinsic cost, i.e. transaction with not enough gas to cover initcode cost is invalid.</em>)</li> <li>If length of <code>initcode</code> to <code>CREATE</code> or <code>CREATE2</code> instructions exceeds <code>MAX_INITCODE_SIZE</code>, instruction execution exceptionally aborts (as if it runs out of gas).</li> <li>For the <code>CREATE</code> and <code>CREATE2</code> instructions charge an extra gas cost equaling to <code>initcode_cost(initcode)</code>. This cost is deducted before the calculation of the resulting contract address and the execution of <code>initcode</code>. (<em>Note that this means before or at the same time as the hashing cost is applied in <code>CREATE2</code>.</em>)</li> </ol> <h2 id="rationale">Rationale</h2> <h3 id="gas-cost-constant">Gas cost constant</h3> <p>The value of <code>INITCODE_WORD_COST</code> is selected based on performance benchmarks of differing worst-cases per implementation. The baseline for the benchmarks is the performance of <code>KECCAK256</code> hashing in geth 1.10.9, which matches the 70 Mgas/s gas limit target on a 4.0 GHz x86_64 CPU.</p> <table><thead><tr><th>EVM</th><th>version</th><th>MB/s</th><th>B/CPUcycle</th><th>CPUcycle/B</th><th>cost of 1 B</th><th>cost of 32 B</th></tr></thead><tbody> <tr><td>geth/KECCAK256</td><td>1.10.9</td><td>357</td><td>1.8</td><td>0.6</td><td>0.2</td><td>6.0</td></tr> <tr><td>geth</td><td>1.10.9</td><td>1091</td><td>5.5</td><td>0.2</td><td>0.1</td><td>2.0</td></tr> <tr><td>evmone/Baseline</td><td>0.8.2</td><td>727</td><td>3.7</td><td>0.3</td><td>0.1</td><td>2.9</td></tr> <tr><td>evmone/Advanced</td><td>0.8.2</td><td>155</td><td>0.8</td><td>1.3</td><td>0.4</td><td>13.8</td></tr> </tbody></table> <h3 id="gas-cost-per-word-32-byte-chunk">Gas cost per word (32-byte chunk)</h3> <p>We have chosen the cost of 2 gas per word based on Geth's implementation and comparing with <code>KECCAK256</code> performance. This means the per byte cost is <code>0.0625</code>. While fractional gas costs are not permitted in the EVM, we can approximate it by charging per-word.</p> <p>Moreover, calculating gas per word is compatible with the calculation of <code>CREATE2</code>'s <em>hashcost</em> of <a href="https://wg-eips.ritovision.com/1014/">EIP-1014</a>. Therefore, the same implementation may be used for <code>CREATE</code> and <code>CREATE2</code> with different cost constants: before activation <code>0</code> for <code>CREATE</code> and <code>6</code> for <code>CREATE2</code>, after activation <code>2</code> for <code>CREATE</code> and <code>6 + 2</code> for <code>CREATE2</code>.</p> <h3 id="reason-for-size-limit-of-initcode">Reason for size limit of initcode</h3> <p>Estimating and creating worst case scenarios is easier with an upper bound in place, given one parameter for the search is greatly reduced. This allows for selecting a much more optimistic gas per byte.</p> <p>Should there be no upper bound, the cost would need to be higher accounting for unknown unknowns. Given most <em>initcode</em> (<em>TODO: state maximum initcode size resulting in deployment seen on mainnet here</em>) does not exceed the proposed limit, penalising contracts by overly conservative costs seems unnecessary.</p> <h3 id="effect-of-size-limit-of-initcode">Effect of size limit of initcode</h3> <p>In most, if not all cases when a new contract is being created, the resulting runtime code is copied from the initcode itself. For the basic case the <code>2 * MAX_CODE_SIZE</code> limit allows <code>MAX_CODE_SIZE</code> for runtime code and another <code>MAX_CODE_SIZE</code> for contract constructor code. However, the limit may have practical implications for cases where multiple contracts are deployed in a single create transaction.</p> <h3 id="initcode-cost-for-create-transaction">Initcode cost for create transaction</h3> <p>The initcode cost for create transaction data (0.0625 gas per byte) is negligible compared to the transaction data cost (4 or 16 gas per byte). Despite that, we decided to include it in the specification for consistency, and more importantly for forward compatibility.</p> <h3 id="how-to-report-initcode-limit-violation">How to report initcode limit violation?</h3> <p>We specified that initcode size limit violation for <code>CREATE</code>/<code>CREATE2</code> results in exceptional abort of the execution. This places it in the group of early out-of-gas checks, including: stack underflow, memory expansion, static call violation, initcode hashing cost, and initcode cost introduced by this EIP. They precede the later "light" checks: call depth and balance. The choice gives consistency to the order of checks and lowers implementation complexity (out-of-gas checks can be performed in any order).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a "network upgrade", since it modifies consensus rules.</p> <p>Already deployed contracts should not be affected, but certain transactions (with <code>initcode</code> beyond the proposed limit) would still be includable in a block, but result in an exceptional abort.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests should include the following cases:</p> <ul> <li>Creation transaction with gas limit enough to cover initcode cost</li> <li>Creation transaction with gas limit enough to cover intrinsic cost except initcode cost</li> <li><code>CREATE</code>/<code>CREATE2</code>/creation transaction with <code>len(initcode)</code> at <code>MAX_INITCODE_SIZE</code></li> <li><code>CREATE</code>/<code>CREATE2</code>/creation transaction with <code>len(initcode)</code> at <code>MAX_INITCODE_SIZE+1</code></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>For client implementations, this EIP makes attacks based on jumpdest-analysis less problematic, so should increase the robustness of clients.</p> <p>For layer 2, this EIP introduces failure-modes where there previously were none. There <em>could</em> exist factory-contracts which deploy multi-level contract hierarchies, such that the code for multiple contracts are included in the initcode of the first contract. The author(s) of this EIP are not aware of any such contracts.</p> <p>Currently, on London, with <code>30M</code> gas limit, it would be possible to trigger jumpdest-analysis of a total <code>~1.3GB</code> of initcode. With this EIP, the cost for such an attack would increase by roughly <code>80M</code> gas.</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-07-12T00:00:00+00:00 2026-02-11T14:49:27+00:00 William Morrisshttps://github.com/wjmelements https://wg-eips.ritovision.com/3651/

Starts the `COINBASE` address warm

<h2 id="abstract">Abstract</h2> <p>The <code>COINBASE</code> address shall be warm at the start of transaction execution, in accordance with the actual cost of reading that account.</p> <h2 id="motivation">Motivation</h2> <p>Direct <code>COINBASE</code> payments are becoming increasingly popular because they allow conditional payments, which provide benefits such as implicit cancellation of transactions that would revert. But accessing <code>COINBASE</code> is overpriced; the address is initially cold under the access list framework introduced in <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>. This gas cost mismatch can incentivize alternative payments besides ETH, such as <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, but ETH should be the primary means of paying for transactions on Ethereum.</p> <h2 id="specification">Specification</h2> <p>At the start of transaction execution, <code>accessed_addresses</code> shall be initialized to also include the address returned by <code>COINBASE</code> (<code>0x41</code>).</p> <h2 id="rationale">Rationale</h2> <p>The addresses currently initialized warm are the addresses that should already be loaded at the start of transaction validation. The <code>ORIGIN</code> address is always loaded to check its balance against the gas limit and the gas price. The <code>tx.to</code> address is always loaded to begin execution. The <code>COINBASE</code> address should also be always be loaded because it receives the block reward and the transaction fees.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no known backward compatibility issues presented by this change.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no known 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> 2021-07-09T00:00:00+00:00 2026-02-11T14:48:25+00:00 Joachim Lebrunhttps://github.com/Joachim-Lebrun Tony Malghemhttps://github.com/TonyMalghem Kevin Thizyhttps://github.com/Nakasar Luc Falempinhttps://github.com/lfalempin Adam Boudjemaahttps://github.com/Aboudjem https://wg-eips.ritovision.com/3643/

An institutional grade security token contract that provides interfaces for the management and compliant transfer of security tokens.

<h2 id="abstract">Abstract</h2> <p>The T-REX token is an institutional grade security token standard. This standard provides a library of interfaces for the management and compliant transfer of security tokens, using an automated onchain validator system leveraging onchain identities for eligibility checks.</p> <p>The standard defines several interfaces that are described hereunder:</p> <ul> <li>Token</li> <li>Identity Registry</li> <li>Identity Registry Storage</li> <li>Compliance</li> <li>Trusted Issuers Registry</li> <li>Claim Topics Registry</li> </ul> <h2 id="motivation">Motivation</h2> <p>The advent of blockchain technology has brought about a new era of efficiency, accessibility, and liquidity in the world of asset transfer. This is particularly evident in the realm of cryptocurrencies, where users can transfer token ownership peer-to-peer without intermediaries. However, when it comes to tokenized securities or security tokens, the situation is more complex due to the need for compliance with securities laws. These tokens cannot be permissionless like utility tokens; they must be permissioned to track ownership and ensure that only eligible investors can hold tokens.</p> <p>The existing Ethereum protocol, while powerful and versatile, does not fully address the unique challenges posed by security tokens. There is a need for a standard that supports compliant issuance and management of permissioned tokens, suitable for representing a wide range of asset classes, including small businesses and real estate.</p> <p>The proposed <a href="https://wg-eips.ritovision.com/3643/">ERC-3643</a> standard is motivated by this need. It aims to provide a comprehensive framework for managing the lifecycle of security tokens, from issuance to transfers between eligible investors, while enforcing compliance rules at every stage. The standard also supports additional features such as token pausing and freezing, which can be used to manage the token in response to regulatory requirements or changes in the status of the token or its holders.</p> <p>Moreover, the standard is designed to work in conjunction with an on-chain Identity system, allowing for the validation of the identities and credentials of investors through signed attestations issued by trusted claim issuers. This ensures compliance with legal and regulatory requirements for the trading of security tokens.</p> <p>In summary, the motivation behind the proposed standard is to bring the benefits of blockchain technology to the world of securities, while ensuring compliance with existing securities laws. It aims to provide a robust, flexible, and efficient framework for the issuance and management of security tokens, thereby accelerating the evolution of capital markets.</p> <h2 id="specification">Specification</h2> <p>The proposed standard has the following requirements:</p> <ul> <li><strong>MUST</strong> be <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> compatible.</li> <li><strong>MUST</strong> be used in combination with an onchain Identity system</li> <li><strong>MUST</strong> be able to apply any rule of compliance that is required by the regulator or by the token issuer (about the factors of eligibility of an identity or about the rules of the token itself)</li> <li><strong>MUST</strong> have a standard interface to pre-check if a transfer is going to pass or fail before sending it to the blockchain</li> <li><strong>MUST</strong> have a recovery system in case an investor loses access to his private key</li> <li><strong>MUST</strong> be able to freeze tokens on the wallet of investors if needed, partially or totally</li> <li><strong>MUST</strong> have the possibility to pause the token</li> <li><strong>MUST</strong> be able to mint and burn tokens</li> <li><strong>MUST</strong> define an Agent role and an Owner (token issuer) role</li> <li><strong>MUST</strong> be able to force transfers from an Agent wallet</li> <li><strong>MUST</strong> be able to issue transactions in batch (to save gas and to have all the transactions performed in the same block)</li> </ul> <p>While this standard is backwards compatible with ERC-20 and all ERC-20 functions can be called on an ERC-3643 token, the implementation of these functions differs due to the permissioned nature of ERC-3643. Each token transfer under this standard involves a compliance check to validate the transfer and the eligibility of the stakeholder’s identities.</p> <h3 id="agent-role-interface">Agent Role Interface</h3> <p>The standard defines an Agent role, which is crucial for managing access to various functions of the smart contracts. The interface for the Agent role is 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"> IAgentRole</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"> AgentAdded</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _agent</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AgentRemoved</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _agent</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"> functions</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> setters</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addAgent</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _agent</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"> removeAgent</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _agent</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"> getters</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isAgent</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _agent</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>IAgentRole</code> interface allows for the addition and removal of agents, as well as checking if an address is an agent. In this standard, it is the owner role, as defined by <a href="https://wg-eips.ritovision.com/173/">ERC-173</a>, that has the responsibility of appointing and removing agents. Any contract that fulfills the role of a Token contract or an Identity Registry within the context of this standard must be compatible with the <code>IAgentRole</code> interface.</p> <h3 id="main-functions">Main functions</h3> <h4 id="transfer">Transfer</h4> <p>To be able to perform a transfer on T-REX you need to fulfill several conditions :</p> <ul> <li>The sender <strong>MUST</strong> hold enough free balance (total balance - frozen tokens, if any)</li> <li>The receiver <strong>MUST</strong> be whitelisted on the Identity Registry and verified (hold the necessary claims on his onchain Identity)</li> <li>The sender's wallet <strong>MUST NOT</strong> be frozen</li> <li>The receiver's wallet <strong>MUST NOT</strong> be frozen</li> <li>The token <strong>MUST NOT</strong> be paused</li> <li>The transfer <strong>MUST</strong> respect all the rules of compliance defined in the Compliance smart contract (canTransfer needs to return TRUE)</li> </ul> <p>Here is an example of <code>transfer</code> function implementation :</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"> _amount</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> override</span><span class="z-entity z-name"> whenNotPaused</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-keyword">!</span><span>_frozen</span><span>[</span><span>_to</span><span>]</span><span class="z-keyword"> &amp;&amp;</span><span class="z-keyword"> !</span><span>_frozen</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>,</span><span class="z-string"> &quot;ERC-3643: Frozen wallet&quot;</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">&lt;</span><span class="z-keyword">=</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"> -</span><span> (</span><span>_frozenTokens</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC-3643: Insufficient Balance&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span> _tokenIdentityRegistry</span><span>.</span><span class="z-entity z-name">isVerified</span><span>(</span><span>to</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC-3643: Invalid identity&quot;</span><span> )</span><span>;</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span> _tokenCompliance</span><span>.</span><span class="z-entity z-name">canTransfer</span><span>(</span><span>from</span><span>,</span><span> to</span><span>,</span><span> amount</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC-3643: Compliance failure&quot;</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-language">msg.sender</span><span>,</span><span> _to</span><span>,</span><span> _amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _tokenCompliance</span><span>.</span><span class="z-entity z-name">transferred</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> _to</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></code></pre> <p>The <code>transferFrom</code> function works the same way while the <code>mint</code> function and the <code>forcedTransfer</code> function only require the receiver to be whitelisted and verified on the Identity Registry (they bypass the compliance rules). The <code>burn</code> function bypasses all checks on eligibility.</p> <h4 id="isverified">isVerified</h4> <p>The <code>isVerified</code> function is called from within the transfer functions <code>transfer</code>, <code>transferFrom</code>, <code>mint</code> and <code>forcedTransfer</code> to instruct the <code>Identity Registry</code> to check if the receiver is a valid investor, i.e. if his wallet address is in the <code>Identity Registry</code> of the token, and if the <code>Identity</code>contract linked to his wallet contains the claims (see <a href="https://wg-eips.ritovision.com/3643/./assets/ONCHAINID/IERC735.sol">Claim Holder</a>) required in the <code>Claim Topics Registry</code> and if these claims are signed by an authorized Claim Issuer as required in the <code>Trusted Issuers Registry</code>. If all the requirements are fulfilled, the <code>isVerified</code> function returns <code>TRUE</code>, otherwise it returns <code>FALSE</code>. An implementation of this function can be found on the T-REX repository of Tokeny.</p> <h4 id="cantransfer">canTransfer</h4> <p>The <code>canTransfer</code> function is also called from within transfer functions. This function checks if the transfer is compliant with global compliance rules applied to the token, in opposition with <code>isVerified</code> that only checks the eligibility of an investor to hold and receive tokens, the <code>canTransfer</code> function is looking at global compliance rules, e.g. check if the transfer is compliant in the case there is a fixed maximum number of token holders to respect (can be a limited number of holders per country as well), check if the transfer respects rules setting a maximum amount of tokens per investor, ... If all the requirements are fulfilled, the <code>canTransfer</code> function will return <code>TRUE</code> otherwise it will return <code>FALSE</code> and the transfer will not be allowed to happen. An implementation of this function can be found on the T-REX repository of Tokeny.</p> <h4 id="other-functions">Other functions</h4> <p>Description of other functions of the ERC-3643 can be found in the <code>interfaces</code> folder. An implementation of the ERC-3643 suite of smart contracts can be found on the T-REX repository of Tokeny.</p> <h3 id="token-interface">Token interface</h3> <p>ERC-3643 permissioned tokens build upon the standard ERC-20 structure, but with additional functions to ensure compliance in the transactions of the security tokens. The functions <code>transfer</code> and <code>transferFrom</code> are implemented in a conditional way, allowing them to proceed with a transfer only if the transaction is valid. The permissioned tokens are allowed to be transferred only to validated counterparties, in order to avoid tokens being held in wallets/Identity contracts of ineligible/unauthorized investors. The ERC-3643 standard also supports the recovery of security tokens in case an investor loses access to their wallet private key. A history of recovered tokens is maintained on the blockchain for transparency reasons.</p> <p>ERC-3643 tokens implement a range of additional functions to enable the owner or their appointed agents to manage supply, transfer rules, lockups, and any other requirements in the management of a security. The standard relies on ERC-173 to define contract ownership, with the owner having the responsibility of appointing agents. Any contract that fulfills the role of a Token contract within the context of this standard must be compatible with the <code>IAgentRole</code> interface.</p> <p>A detailed description of the functions can be found in the <a href="https://wg-eips.ritovision.com/3643/./assets/interfaces/IERC3643.sol">interfaces folder</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"> IERC3643</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-comment"> events</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UpdatedTokenInformation</span><span>(</span><span class="z-support">string</span><span class="z-variable"> _newName</span><span>, </span><span class="z-support">string</span><span class="z-variable"> _newSymbol</span><span>, </span><span class="z-support">uint8</span><span class="z-variable"> _newDecimals</span><span>, </span><span class="z-support">string</span><span class="z-variable"> _newVersion</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _newOnchainID</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdentityRegistryAdded</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _identityRegistry</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ComplianceAdded</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _compliance</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RecoverySuccess</span><span>(</span><span class="z-support">address</span><span class="z-variable"> _lostWallet</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _newWallet</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _investorOnchainID</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AddressFrozen</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _userAddress</span><span>, </span><span class="z-support">bool</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _isFrozen</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 class="z-storage z-type"> event</span><span class="z-entity z-name"> TokensFrozen</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _userAddress</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 class="z-storage z-type"> event</span><span class="z-entity z-name"> TokensUnfrozen</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _userAddress</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 class="z-storage z-type"> event</span><span class="z-entity z-name"> Paused</span><span>(</span><span class="z-support">address</span><span class="z-variable"> _userAddress</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Unpaused</span><span>(</span><span class="z-support">address</span><span class="z-variable"> _userAddress</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"> functions</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> getters</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> onchainID</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-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"> 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"> identityRegistry</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-storage z-type">IIdentityRegistry</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> compliance</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-storage z-type">ICompliance</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> paused</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-storage z-type"> function</span><span class="z-entity z-name"> isFrozen</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</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"> getFrozenTokens</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</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-comment"> setters</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setName</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"> _name</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"> setSymbol</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"> _symbol</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"> setOnchainID</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _onchainID</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"> pause</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"> unpause</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"> setAddressFrozen</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _freeze</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"> freezePartialTokens</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</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"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unfreezePartialTokens</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</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"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setIdentityRegistry</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _identityRegistry</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"> setCompliance</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _compliance</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"> transfer actions</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> forcedTransfer</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"> _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"> mint</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"> _amount</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"> burn</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</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"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> recoveryAddress</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _lostWallet</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _newWallet</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _investorOnchainID</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-comment"> batch functions</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> batchTransfer</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"> _toList</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"> _amounts</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"> batchForcedTransfer</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"> _fromList</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"> _toList</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"> _amounts</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"> batchMint</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"> _toList</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"> _amounts</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"> batchBurn</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"> _userAddresses</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"> _amounts</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"> batchSetAddressFrozen</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"> _userAddresses</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"> _freeze</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"> batchFreezePartialTokens</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"> _userAddresses</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"> _amounts</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"> batchUnfreezePartialTokens</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"> _userAddresses</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"> _amounts</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="identity-registry-interface">Identity Registry Interface</h3> <p>The Identity Registry is linked to storage that contains a dynamic whitelist of identities. It establishes the link between a wallet address, an Identity smart contract, and a country code corresponding to the investor's country of residence. This country code is set in accordance with the ISO-3166 standard. The Identity Registry also includes a function called <code>isVerified()</code>, which returns a status based on the validity of claims (as per the security token requirements) in the user’s Identity contract.</p> <p>The standard relies on ERC-173 to define contract ownership, with the owner having the responsibility of appointing agents. Any contract that fulfills the role of an Identity Registry within the context of this standard must be compatible with the <code>IAgentRole</code> interface. The Identity Registry is managed by the agent wallet(s), meaning only the agent(s) can add or remove identities in the registry. Note that the agent role on the Identity Registry is set by the owner, therefore the owner could set themselves as the agent if they want to maintain full control. There is a specific identity registry for each security token.</p> <p>A detailed description of the functions can be found in the <a href="https://wg-eips.ritovision.com/3643/./assets/interfaces/IIdentityRegistry.sol">interfaces folder</a>.</p> <p>Note that <a href="https://wg-eips.ritovision.com/3643/./assets/ONCHAINID/IClaimIssuer.sol"><code>IClaimIssuer</code></a> and <a href="https://wg-eips.ritovision.com/3643/./assets/ONCHAINID/IIdentity.sol"><code>IIdentity</code></a> are needed in this interface as they are required for the Identity eligibility checks.</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"> IIdentityRegistry</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"> events</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ClaimTopicsRegistrySet</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> claimTopicsRegistry</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdentityStorageSet</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> identityStorage</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TrustedIssuersRegistrySet</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> trustedIssuersRegistry</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdentityRegistered</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> investorAddress</span><span>, </span><span class="z-variable">IIdentity</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> identity</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdentityRemoved</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> investorAddress</span><span>, </span><span class="z-variable">IIdentity</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> identity</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdentityUpdated</span><span>(</span><span class="z-variable">IIdentity</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> oldIdentity</span><span>, </span><span class="z-variable">IIdentity</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> newIdentity</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CountryUpdated</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> investorAddress</span><span>, </span><span class="z-support">uint16</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> country</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"> functions</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> identity registry getters</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> identityStorage</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-storage z-type">IIdentityRegistryStorage</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> issuersRegistry</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-storage z-type">ITrustedIssuersRegistry</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> topicsRegistry</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-storage z-type">IClaimTopicsRegistry</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 registry setters</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setIdentityRegistryStorage</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _identityRegistryStorage</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"> setClaimTopicsRegistry</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _claimTopicsRegistry</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"> setTrustedIssuersRegistry</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _trustedIssuersRegistry</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"> registry actions</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerIdentity</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</span><span>,</span><span class="z-storage z-type"> IIdentity</span><span class="z-variable z-parameter z-function"> _identity</span><span>,</span><span class="z-support"> uint16</span><span class="z-variable z-parameter z-function"> _country</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"> deleteIdentity</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</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"> updateCountry</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</span><span>,</span><span class="z-support"> uint16</span><span class="z-variable z-parameter z-function"> _country</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"> updateIdentity</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</span><span>,</span><span class="z-storage z-type"> IIdentity</span><span class="z-variable z-parameter z-function"> _identity</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"> batchRegisterIdentity</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"> _userAddresses</span><span>,</span><span class="z-storage z-type"> IIdentity</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _identities</span><span>,</span><span class="z-support"> uint16</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _countries</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"> registry consultation</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> contains</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</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"> isVerified</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</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"> identity</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</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">IIdentity</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> investorCountry</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</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">uint16</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="identity-registry-storage-interface">Identity Registry Storage Interface</h3> <p>The Identity Registry Storage stores the identity addresses of all the authorized investors in the security token(s) linked to the storage contract. These are all identities of investors who have been authorized to hold the token(s) after having gone through the appropriate KYC and eligibility checks. The Identity Registry Storage can be bound to one or several Identity Registry contract(s). The goal of the Identity Registry storage is to separate the Identity Registry functions and specifications from its storage. This way, it is possible to keep one single Identity Registry contract per token, with its own Trusted Issuers Registry and Claim Topics Registry, but with a shared whitelist of investors used by the <code>isVerifed()</code> function implemented in the Identity Registries to check the eligibility of the receiver in a transfer transaction.</p> <p>The standard relies on ERC-173 to define contract ownership, with the owner having the responsibility of appointing agents(in this case through the <code>bindIdentityRegistry</code> function). Any contract that fulfills the role of an Identity Registry Storage within the context of this standard must be compatible with the <code>IAgentRole</code> interface. The Identity Registry Storage is managed by the agent addresses (i.e. the bound Identity Registries), meaning only the agent(s) can add or remove identities in the registry. Note that the agent role on the Identity Registry Storage is set by the owner, therefore the owner could set themselves as the agent if they want to modify the storage manually. Otherwise it is the bound Identity Registries that are using the agent role to write in the Identity Registry Storage.</p> <p>A detailed description of the functions can be found in the <a href="https://wg-eips.ritovision.com/3643/./assets/interfaces/IIdentityRegistryStorage.sol">interfaces folder</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"> IIdentityRegistryStorage</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"> IdentityStored</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> investorAddress</span><span>, </span><span class="z-variable">IIdentity</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> identity</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdentityUnstored</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> investorAddress</span><span>, </span><span class="z-variable">IIdentity</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> identity</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdentityModified</span><span>(</span><span class="z-variable">IIdentity</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> oldIdentity</span><span>, </span><span class="z-variable">IIdentity</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> newIdentity</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CountryModified</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> investorAddress</span><span>, </span><span class="z-support">uint16</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> country</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdentityRegistryBound</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> identityRegistry</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdentityRegistryUnbound</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> identityRegistry</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">functions</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> storage related functions</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> storedIdentity</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</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">IIdentity</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> storedInvestorCountry</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</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">uint16</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addIdentityToStorage</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</span><span>,</span><span class="z-storage z-type"> IIdentity</span><span class="z-variable z-parameter z-function"> _identity</span><span>,</span><span class="z-support"> uint16</span><span class="z-variable z-parameter z-function"> _country</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"> removeIdentityFromStorage</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</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"> modifyStoredInvestorCountry</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</span><span>,</span><span class="z-support"> uint16</span><span class="z-variable z-parameter z-function"> _country</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"> modifyStoredIdentity</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _userAddress</span><span>,</span><span class="z-storage z-type"> IIdentity</span><span class="z-variable z-parameter z-function"> _identity</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"> role setter</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> bindIdentityRegistry</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _identityRegistry</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"> unbindIdentityRegistry</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _identityRegistry</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"> getter for bound IdentityRegistry role</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> linkedIdentityRegistries</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></span></code></pre><h3 id="compliance-interface">Compliance Interface</h3> <p>The Compliance contract is used to set the rules of the offering itself and ensures these rules are respected during the whole lifecycle of the token. For example, the Compliance contract will define the maximum amount of investors per country, the maximum amount of tokens per investor, and the accepted countries for the circulation of the token (using the country code corresponding to each investor in the Identity Registry). The Compliance smart contract can be either “tailor-made”, following the legal requirements of the token issuer, or can be deployed under a generic modular form, which can then add and remove external compliance <code>Modules</code> to fit the legal requirements of the token in the same way as a custom "tailor-made" contract would.</p> <p>This contract is triggered at every transaction by the Token and returns <code>TRUE</code> if the transaction is compliant with the rules of the offering and <code>FALSE</code> otherwise.</p> <p>The standard relies on ERC-173 to define contract ownership, with the owner having the responsibility of setting the Compliance parameters and binding the Compliance to a Token contract.</p> <p>A detailed description of the functions can be found in the <a href="https://wg-eips.ritovision.com/3643/./assets/interfaces/ICompliance.sol">interfaces folder</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"> ICompliance</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"> TokenBound</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 class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenUnbound</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"> functions</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> initialization of the compliance contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> bindToken</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"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unbindToken</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"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> check the parameters of the compliance contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isTokenBound</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"> 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"> getTokenBound</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-comment"> compliance check and state update</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canTransfer</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"> _amount</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"> transferred</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"> _amount</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"> created</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"> _amount</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"> destroyed</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"> _amount</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="trusted-issuer-s-registry-interface">Trusted Issuer's Registry Interface</h3> <p>The Trusted Issuer's Registry stores the contract addresses (<a href="https://wg-eips.ritovision.com/3643/./assets/ONCHAINID/IClaimIssuer.sol">IClaimIssuer</a>) of all the trusted claim issuers for a specific security token. The Identity contract (<a href="https://wg-eips.ritovision.com/3643/./assets/ONCHAINID/IIdentity.sol">IIdentity</a>) of token owners (the investors) must have claims signed by the claim issuers stored in this smart contract in order to be able to hold the token.</p> <p>The standard relies on ERC-173 to define contract ownership, with the owner having the responsibility of managing this registry as per their requirements. This includes the ability to add, remove, and update the list of Trusted Issuers.</p> <p>A detailed description of the functions can be found in the <a href="https://wg-eips.ritovision.com/3643/./assets/interfaces/ITrustedIssuersRegistry.sol">interfaces folder</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"> ITrustedIssuersRegistry</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"> TrustedIssuerAdded</span><span>(</span><span class="z-variable">IClaimIssuer</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> trustedIssuer</span><span>, </span><span class="z-support">uint</span><span>[</span><span>]</span><span class="z-variable"> claimTopics</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TrustedIssuerRemoved</span><span>(</span><span class="z-variable">IClaimIssuer</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> trustedIssuer</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ClaimTopicsUpdated</span><span>(</span><span class="z-variable">IClaimIssuer</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> trustedIssuer</span><span>, </span><span class="z-support">uint</span><span>[</span><span>]</span><span class="z-variable"> claimTopics</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> functions</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> setters</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addTrustedIssuer</span><span>(</span><span class="z-storage z-type">IClaimIssuer</span><span class="z-variable z-parameter z-function"> _trustedIssuer</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"> _claimTopics</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"> removeTrustedIssuer</span><span>(</span><span class="z-storage z-type">IClaimIssuer</span><span class="z-variable z-parameter z-function"> _trustedIssuer</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"> updateIssuerClaimTopics</span><span>(</span><span class="z-storage z-type">IClaimIssuer</span><span class="z-variable z-parameter z-function"> _trustedIssuer</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"> _claimTopics</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"> getters</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTrustedIssuers</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-storage z-type">IClaimIssuer</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-storage z-type"> function</span><span class="z-entity z-name"> isTrustedIssuer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _issuer</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"> getTrustedIssuerClaimTopics</span><span>(</span><span class="z-storage z-type">IClaimIssuer</span><span class="z-variable z-parameter z-function"> _trustedIssuer</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 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"> getTrustedIssuersForClaimTopic</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> claimTopic</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">IClaimIssuer</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-storage z-type"> function</span><span class="z-entity z-name"> hasClaimTopic</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _issuer</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _claimTopic</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><h3 id="claim-topics-registry-interface">Claim Topics Registry Interface</h3> <p>The Claim Topics Registry stores all the trusted claim topics for the security token. The Identity contract (<a href="https://wg-eips.ritovision.com/3643/./assets/ONCHAINID/IIdentity.sol">IIdentity</a>) of token owners must contain claims of the claim topics stored in this smart contract.</p> <p>The standard relies on ERC-173 to define contract ownership, with the owner having the responsibility of managing this registry as per their requirements. This includes the ability to add and remove required Claim Topics.</p> <p>A detailed description of the functions can be found in the <a href="https://wg-eips.ritovision.com/3643/./assets/interfaces/IClaimTopicsRegistry.sol">interfaces folder</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"> IClaimTopicsRegistry</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"> ClaimTopicAdded</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> claimTopic</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ClaimTopicRemoved</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> claimTopic</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> functions</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> setters</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addClaimTopic</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _claimTopic</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"> removeClaimTopic</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _claimTopic</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"> getter</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getClaimTopics</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 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="transfer-restrictions">Transfer Restrictions</h3> <p>Transfers of securities can fail for a variety of reasons. This is in direct contrast to utility tokens, which generally only require the sender to have a sufficient balance. These conditions can be related to the status of an investor’s wallet, the identity of the sender and receiver of the securities (i.e., whether they have been through a KYC process, whether they are accredited or an affiliate of the issuer) or for reasons unrelated to the specific transfer but instead set at the token level (i.e., the token contract enforces a maximum number of investors or a cap on the percentage held by any single investor). For ERC-20 tokens, the <code>balanceOf</code> and <code>allowance</code> functions provide a way to check that a transfer is likely to succeed before executing the transfer, which can be executed both on-chain and off-chain. For tokens representing securities, the T-REX standard introduces a function <code>canTransfer</code> which provides a more general-purpose way to achieve this. I.e., when the reasons for failure are related to the compliance rules of the token and a function <code>isVerified</code> which allows checking the eligibility status of the identity of the investor. Transfers can also fail if the address of the sender and/or receiver is frozen, or if the free balance of the sender (total balance - frozen tokens) is lower than the amount to transfer. Ultimately, the transfer could be blocked if the token is <code>paused</code>.</p> <h3 id="identity-management">Identity Management</h3> <p>Security and compliance of transfers are enforced through the management of on-chain identities. These include:</p> <ul> <li>Identity contract: A unique identifier for each investor, which is used to manage their identity and claims.</li> <li>Claim: Signed attestations issued by a trusted claim issuer that confirm certain attributes or qualifications of the token holders, such as their identity, location, investor status, or KYC/AML clearance.</li> <li>Identity Storage/Registry: A storage system for all Identity contracts and their associated wallets, which is used to verify the eligibility of investors during transfers.</li> </ul> <h3 id="token-lifecycle-management">Token Lifecycle Management</h3> <p>The T-REX standard provides a comprehensive framework for managing the lifecycle of security tokens. This includes the issuance of tokens, transfers between eligible investors, and the enforcement of compliance rules at every stage of the token's lifecycle. The standard also supports additional features such as token pausing and freezing, which can be used to manage the token in response to regulatory requirements or changes in the status of the token or its holders.</p> <h3 id="additional-compliance-rules">Additional Compliance Rules</h3> <p>The T-REX standard supports the implementation of additional compliance rules through modular compliance. These modules can be used to enforce a wide range of rules and restrictions, such as caps on the number of investors or the percentage of tokens held by a single investor, restrictions on transfers between certain types of investors, and more. This flexibility allows issuers to tailor the compliance rules of their tokens to their specific needs and regulatory environment.</p> <h3 id="inclusion-of-agent-related-functions">Inclusion of Agent-Related Functions</h3> <p>The inclusion of Agent-scoped functions within the standard interfaces is deliberate. The intent is to accommodate secure and adaptable token management practices that surpass the capabilities of EOA management. We envision scenarios where the agent role is fulfilled by automated systems or smart contracts, capable of programmatically executing operational functions like minting, burning, and freezing in response to specified criteria or regulatory triggers. For example, a smart contract might automatically burn tokens to align with redemption requests in an open-ended fund, or freeze tokens associated with wallets engaged in fraudulent activities.</p> <p>Consequently, these functions are standardized to provide a uniform interface for various automated systems interacting with different ERC-3643 tokens, allowing for standardized tooling and interfaces that work across the entire ecosystem. This approach ensures that ERC-3643 remains flexible, future-proof, and capable of supporting a wide array of operational models.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>T-REX tokens should be backwards compatible with ERC-20 and ERC-173 and should be able to interact with a <a href="https://wg-eips.ritovision.com/3643/./assets/ONCHAINID/IERC735.sol">Claim Holder contract</a> to validate the claims linked to an <a href="https://wg-eips.ritovision.com/3643/./assets/ONCHAINID/IIdentity.sol">Identity contract</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This specification has been audited by Kapersky and Hacken, and no notable security considerations were found. While the audits were primarily focused on the specific implementation by Tokeny, they also challenged and validated the core principles of the T-REX standard. The auditing teams approval of these principles provides assurance that the standard itself is robust and does not present any significant 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> 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-06-10T00:00:00+00:00 2026-02-11T14:49:27+00:00 Dankrad Feisthttps://github.com/dankrad Dmitry Khovratovichhttps://github.com/khovratovich Marius van der Wijdenhttps://github.com/MariusVanDerWijden https://wg-eips.ritovision.com/3607/

Do not allow transactions for which `tx.sender` has any code deployed.

<h2 id="abstract">Abstract</h2> <p>Ethereum addresses are currently only 160 bits long. This means it is possible to create a collision between a contract account and an Externally Owned Account (EOA) using an estimated <code>2**80</code> computing operations, which is feasible now given a large budget (ca. 10 billion USD). The fix in this EIP prevents the worst possible attack, where a safe looking contract (e.g. a token wrapper or an AMM-type contract) is deployed to attract user funds, which can then be spent using the EOA key for the same address. The fix is to never allow to use an address that already has code deployed as an EOA address.</p> <h2 id="motivation">Motivation</h2> <h3 id="generating-address-collisions">Generating address collisions</h3> <p>By creating keys for <code>2**80</code> EOAs and simulating the deployment of <code>2**80</code> contracts from these EOAs (one each), one expects to find about one collision where an EOA has the same address as one contract.</p> <p>This very simple form of the attack requires the storage of <code>2**80</code> addresses, which is a practical barrier: It would require <code>2.4*10**25</code> bytes of memory (24 Yottabyte). However, there are cycle finding algorithms that can perform the collision search without requiring large amounts of storage. An estimate for the complexity has been made <a rel="external" href="https://hackmd.io/Vzhp5YJyTT-LhWm_s0JQpA">here</a>. We estimate that a collision between a contract and an EOA could be found in about one year with an investment of ca. US$10 billion in hardware and electricity.</p> <h3 id="background">Background</h3> <p>There is currently a discussion to move to 256-bit addresses on Ethereum, which would increase collision resistance to a complexity of <code>2**128</code> which is currently thought infeasible for the foreseeable future. However, with 160 bit addresses, the collision problem can be effectively solved now, as demonstrated above.</p> <p>Most attacks that can occur via address collisions are quite impractical: They involve users sending funds to an address before a contract is deployed. This is a very rare application in practice and users can easily circumvent the attack by never sending funds to a contract until it has been safely deployed with enough confirmations.</p> <p>However, the yellow paper does not explicitly specify how a client should handle the case where a transaction is sent from an account that already has contract code deployed; presumably because this was considered infeasible at the time. The assumption is that most client would allow this transaction in their current state.</p> <p>This EIP is to specify this behaviour to always forbid such transactions. This fixes most realistic or serious attacks due to address collisions.</p> <h2 id="specification">Specification</h2> <p>Any transaction where <code>tx.sender</code> has a <code>CODEHASH != EMPTYCODEHASH</code> MUST be rejected as invalid, where <code>EMPTYCODEHASH = 0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470</code>. The invalid transaction MUST be rejected by the client and not be included in a block. A block containing such a transaction MUST be considered invalid.</p> <h2 id="rationale">Rationale</h2> <p>We note that it was always expected that a contract account's behaviour is constrained by the code in that contract -- which means that the account's funds should not suddenly be spendable by some private key. It was just implicitly assumed in the past that a 160 bit address length is enough to provide collision resistance, and thus that this case could never occur. In that sense, this EIP should be seen as a clarification of protocol behaviour in a previously undefined case rather than an explicit upgrade of consensus rules.</p> <p>This does not exclude all possible attack vectors, only the most serious one. Further possible attack vectors via address collisions between contracts and EOAs are:</p> <ol> <li>An attacker can convince a user to send funds to an account before it is deployed. Some applications require this behaviour (e.g. state channels).</li> <li>A chain reorg can happen after a contract is deployed. If the reorg removes the contract deployment transaction the funds can still be accessed using the private key.</li> <li>A contract can self destruct, with the stated intention that ERC20s (or other tokens) in the contract would be burned. However, they can now be accessed by a key for that address.</li> </ol> <p>All these scenarios are much harder to exploit for an attacker, and likely have much lower yield making the attacks unlikely to be economically viable.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>It is unlikely that an attack like this has already occurred on the Ethereum mainnet, or we would very likely have heard of it. It is inconceivable that someone would use this as a "feature" to make a contract an EOA at the same time, when they could simply do this by adding some methods to the contract instead of spending billions on building hardware to find hash collisions.</p> <p>Private networks may have deployed contracts which also work as EOAs at genesis and should check that this upgrade does not impact their workflows.</p> <p>Clients might choose to disable this rule for RPC calls like <code>eth_call</code> and <code>eth_estimateGas</code> as some Multi-Sig contracts use these calls to create transactions as if they originated from the multisig contract itself.</p> <h2 id="test-cases">Test Cases</h2> <p>Given a genesis allocation of</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Address: 0x71562b71999873DB5b286dF957af199Ec94617F7</span></span> <span class="giallo-l"><span>Balance: 1000000000000000000 // 1 ether</span></span> <span class="giallo-l"><span>Nonce: 0,</span></span> <span class="giallo-l"><span>Code: 0xB0B0FACE&quot;,</span></span></code></pre> <p>Every transaction sent by the private key corresponding to <code>0x715656...</code> ( <code>b71c71a67e1177ad4e901695e1b4b9ee17ae16c6668d313eac2f96dbcda3f291</code>) should be rejected. These transaction must be rejected and not included in a block.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The following check must be added to the state transition checks after checking that the nonce of the sender is correct. The sender is the address recovered from the signature of the transaction.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// Make sure the sender is an EOA</span></span> <span class="giallo-l"><span>Set ch to the CodeHash of the sender account</span></span> <span class="giallo-l"><span>if ch is not equal to EmptyCodeHash then</span></span> <span class="giallo-l"><span> return ErrSenderNoEOA</span></span> <span class="giallo-l"><span>end if</span></span></code></pre> <p>A diff to implement EIP-3607 in go-ethereum can be found <a href="https://wg-eips.ritovision.com/3607/./assets/geth.diff">here</a></p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP is a strict security upgrade: It simply makes some transactions that were formerly valid now invalid. There is no legitimate use for such transactions, so there should be no security downsides.</p> <p>This EIP can be implemented as a soft fork because the new validity rules are a strict superset of the previous validity rules.</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-05-06T00:00:00+00:00 2026-02-11T14:49:27+00:00 James Hancockhttps://github.com/madeoftin https://wg-eips.ritovision.com/3554/ <h2 id="simple-summary">Simple Summary</h2> <p>Delays the difficulty bomb to show effect the first week of December 2021.</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 9,700,000 blocks later than the actual block number.</p> <h2 id="motivation">Motivation</h2> <p>Targeting for the Shanghai upgrade and/or the Merge to occur before December 2021. Either the bomb can be readjusted at that time, or removed all together.</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="python"><span class="giallo-l"><span> fake_block_number</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span class="z-constant">0</span><span>,</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> -</span><span class="z-constant"> 9_700_000</span><span>)</span><span class="z-keyword"> if</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> FORK_BLOCK_NUMBER</span><span class="z-keyword"> else</span><span> block</span><span>.</span><span>number</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The following script predicts a .1 second delay to blocktime the first week of december and a 1 second delay by the end of the month. This gives reason to address because the effect will be seen, but not so much urgency we don't have space to work around if needed.</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"> predict_diff_bomb_effect</span><span>(</span><span class="z-variable z-parameter z-function">current_blknum</span><span>,</span><span class="z-variable z-parameter z-function"> current_difficulty</span><span>,</span><span class="z-variable z-parameter z-function"> block_adjustment</span><span>,</span><span class="z-variable z-parameter z-function"> months</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;&#39;&#39;</span></span> <span class="giallo-l"><span class="z-string"> Predicts the effect on block time (as a ratio) in a specified amount of months in the future.</span></span> <span class="giallo-l"><span class="z-string"> Vars used in last prediction:</span></span> <span class="giallo-l"><span class="z-string"> current_blknum = 12382958</span></span> <span class="giallo-l"><span class="z-string"> current_difficulty = 7393633000000000</span></span> <span class="giallo-l"><span class="z-string"> block adjustment = 9700000</span></span> <span class="giallo-l"><span class="z-string"> months = 6</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;&#39;&#39;</span></span> <span class="giallo-l"><span> blocks_per_month</span><span class="z-keyword"> =</span><span> (</span><span class="z-constant">86400</span><span class="z-keyword"> *</span><span class="z-constant"> 30</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> 13.3</span></span> <span class="giallo-l"><span> future_blknum</span><span class="z-keyword"> =</span><span> current_blknum</span><span class="z-keyword"> +</span><span> blocks_per_month</span><span class="z-keyword"> *</span><span> months</span></span> <span class="giallo-l"><span> diff_adjustment</span><span class="z-keyword"> =</span><span class="z-constant"> 2</span><span class="z-keyword"> **</span><span> (</span><span>(</span><span>future_blknum</span><span class="z-keyword"> -</span><span> block_adjustment</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> 100000</span><span class="z-keyword"> -</span><span class="z-constant"> 2</span><span>)</span></span> <span class="giallo-l"><span> diff_adjust_coeff</span><span class="z-keyword"> =</span><span> diff_adjustment</span><span class="z-keyword"> /</span><span> current_difficulty</span><span class="z-keyword"> *</span><span class="z-constant"> 2048</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> diff_adjust_coeff</span><span> </span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>diff_adjust_coeff</span><span class="z-keyword"> =</span><span> predict_diff_bomb_effect</span><span>(</span><span class="z-constant">12382958</span><span>,</span><span class="z-constant">7393633000000000</span><span>,</span><span class="z-constant">9700000</span><span>,</span><span class="z-constant">6</span><span>)</span></span></code></pre><h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No known backward compatibility issues.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Misjudging the effects of the difficulty can mean longer blocktimes than anticipated until a hardfork is released. Wild shifts in difficulty can affect this number severely. Also, gradual changes in blocktimes due to longer-term adjustments in difficulty can affect the timing of difficulty bomb epochs. This affects the usability of the network but unlikely to have security ramifications.</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-22T00: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/3529/ <h2 id="simple-summary">Simple Summary</h2> <p>Remove gas refunds for <code>SELFDESTRUCT</code>, and reduce gas refunds for <code>SSTORE</code> to a lower level where the refunds are still substantial, but they are no longer high enough for current "exploits" of the refund mechanism to be viable.</p> <h2 id="motivation">Motivation</h2> <p>Gas refunds for <code>SSTORE</code> and <code>SELFDESTRUCT</code> 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, the benefits of this technique have proven to be far lower than anticipated, and gas refunds have had multiple unexpected 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> <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>MAX_REFUND_QUOTIENT</code></td><td>5</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>Replace <code>SSTORE_CLEARS_SCHEDULE</code> (as defined in <a href="https://wg-eips.ritovision.com/2200/">EIP-2200</a>) with <code>SSTORE_RESET_GAS + ACCESS_LIST_STORAGE_KEY_COST</code> (4,800 gas as of <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a> + <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a>)</li> <li>Reduce the max gas refunded after a transaction to <code>gas_used // MAX_REFUND_QUOTIENT</code></li> </ol> <p>Remark: Previously <em>max gas refunded</em> was defined as <code>gas_used // 2</code>. Here we name the constant <code>2</code> as <code>MAX_REFUND_QUOTIENT</code> and change its value to <code>5</code>.</p> <h2 id="rationale">Rationale</h2> <p>In <a href="https://wg-eips.ritovision.com/2200/#specification">EIP-2200</a>, three cases for refunds were introduced:</p> <ol> <li>If the original value is nonzero, and the new value is zero, add <code>SSTORE_CLEARS_SCHEDULE</code> (currently 15,000) gas to the refund counter</li> <li>If the original value is zero, the current value is nonzero, and the new value is zero, add <code>SSTORE_SET_GAS - SLOAD_GAS</code> (currently 19,900) gas to the refund counter</li> <li>If the original value is nonzero, the current value is a different nonzero value, and the new value equals the original value, add <code>SSTORE_RESET_GAS - SLOAD_GAS</code> (currently 4,900) gas to the refund counter</li> </ol> <p>Of these three, only (1) enables gastokens and allows a block to expend more gas on execution than the block gas limit. (2) does not have this property, because for the 19,900 refund to be obtained, <em>the same storage slot</em> must have been changed from zero to nonzero previously, costing 20,000 gas. The inability to obtain gas from clearing one storage slot and use it to edit another storage slot means that it cannot be used for gas tokens. Additionally, obtaining the refund requires <em>reverting</em> the effect of the storage write and expansion, so the refunded gas does not contribute to a client's load in processing a block. (3) behaves similarly: the 4,900 refund can only be obtained when 5,000 gas had previously been spent on the same storage slot.</p> <p>This EIP deals with case (1). We can establish under what conditions a gastoken is nonviable (ie. you cannot get more gas out of a storage slot than you put in) by using a similar "pairing" argument, mapping each refund to a previous expenditure in the same transaction on the same storage slot. lf a storage slot is changed to zero when its original value is nonzero, there are two possibilities:</p> <ol> <li>This could be the first time that the storage slot is set to zero. In this case, we can pair this event with the <code>SSTORE_RESET_GAS + ACCESS_LIST_STORAGE_KEY_COST</code> minimum cost of reading and editing the storage slot for the first time.</li> <li>This could be the second or later time that the storage slot is set to zero. In this case, we can pair this event with the most recent previous time that the value was set <em>away</em> from zero, in which <code>SSTORE_CLEARS_SCHEDULE</code> gas is <em>removed</em> from the refund.</li> </ol> <p>For the second and later event, it does not matter what value <code>SSTORE_CLEARS_SCHEDULE</code> has, because every refund of that size is paired with a refund <em>removal</em> of the same size. This leaves the first event. For the total gas expended on the slot to be guaranteed to be positive, we need <code>SSTORE_CLEARS_SCHEDULE &lt;= SSTORE_RESET_GAS + ACCESS_LIST_STORAGE_KEY_COST</code>. And so this EIP simply decreases <code>SSTORE_CLEARS_SCHEDULE</code> to the sum of those two costs.</p> <p>One alternative intuition for this EIP is that there will not be a net refund for clearing data that has not yet been read (which is often "useless" data), but there will continue to be a net refund for clearing data that has been read (which is likely to be "useful" data).</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>Gas tokens 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> <p>However, fully preserving refunds in the <code>new = original = 0 != current</code> case, and keeping <em>some</em> refund in the other <code>nonzero -&gt; zero</code> cases, ensures that a few key use cases that receive (and deserve) favorable gas cost treatment continue to do so. For example, <code>zero -&gt; nonzero -&gt; zero</code> storage set patterns continue to cost only ~100 gas. Two important examples of such patterns include:</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> <h3 id="effect-on-storage-clearing-incentives">Effect on storage clearing incentives</h3> <p>A criticism of earlier refund removal EIPs (<a href="https://wg-eips.ritovision.com/3298/">EIP-3298</a> and <a href="https://wg-eips.ritovision.com/3403/">EIP-3403</a>) is that these EIPs fully remove the incentive to set a value to zero, encouraging users to not fully clear a storage slot if they expect even the smallest probability that they will want to use that storage slot again.</p> <p>For example, if you have 1 unit of an ERC20 token and you are giving away or selling your entire balance, you could instead only give away 0.999999 units and leave the remainder behind. If you ever decide to re-acquire more of that token with the same account in the future, you would only have to pay 5000 gas (2100 for the read + 2900 for nonzero-to-nonzero set) for the <code>SSTORE</code> instead of 22100 (20000 for the zero-to-nonzero set). Today, this is counterbalanced by the 15000 refund for clearing, so you only have an incentive to do this if you are more than <code>15000 / 17100 = 87.7%</code> sure that you will use the slot again; with EIP-3298 or EIP-3403 the counterbalancing incentive would not exist, so setting to nonzero is better if your chance of using the slot again is <em>any</em> value greater than 0%.</p> <p>A refund of 4800 gas remains, so there is only be an incentive to keep a storage slot nonzero if you expect a probability of more than <code>4800 / 17100 = 28.1%</code> that you will use that slot again. This is not perfect, but it is likely higher than the average person's expectations of later re-acquiring a token with the same address if they clear their entire balance of it.</p> <p>The capping of refunds to 1/5 of gas expended means that this refund can only be used to increase the amount of storage write operations needed to process a block by at most 25%, limiting the ability to use this mechanic for storage-write-focused denial-of-service attacks.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="eip-2929-gas-costs">EIP-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-reduced-refunds">With reduced refunds</h3> <p>If refunds were to be partially removed, by changing <code>SSTORE_CLEARS_SCHEDULE</code> from 15000 to 4800 (and removing selfdestruct refund) this would be the comparative table.</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>4800</td><td>1</td><td>0</td><td>0</td><td></td><td>-1788</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>4800</td><td>1</td><td>2</td><td>0</td><td></td><td>-1788</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>4800</td><td>1</td><td>1</td><td>0</td><td></td><td>-1788</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>7600</td><td>1</td><td>0</td><td>1</td><td>0</td><td>-1682</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 <code>SSTORE</code>s that were later reset back to zero. It is okay to not count those, because if such an <code>SSTORE</code> 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-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-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 Yu Liuhttps://github.com/yuliu-debond Varun Deshpandehttps://github.com/dr-chain Cedric Ngakamhttps://github.com/drikssy Dhruv Malikhttps://github.com/dhruvmalik007 Samuel Gwlanold Edoumouhttps://github.com/Edoumou Toufic Batricehttps://github.com/toufic0710 https://wg-eips.ritovision.com/3475/

Interface for creating tokenized obligations with abstract on-chain metadata storage

<h2 id="abstract">Abstract</h2> <ul> <li> <p>This EIP allows the creation of tokenized obligations with abstract on-chain metadata storage. Issuing bonds with multiple redemption data cannot be achieved with existing token standards.</p> </li> <li> <p>This EIP enables each bond class ID to represent a new configurable token type and corresponding to each class, corresponding bond nonces to represent an issuing condition or any other form of data in uint256. Every single nonce of a bond class can have its metadata, supply, and other redemption conditions.</p> </li> <li> <p>Bonds created by this EIP can also be batched for issuance/redemption conditions for efficiency on gas costs and UX side. And finally, bonds created from this standard can be divided and exchanged in a secondary market.</p> </li> </ul> <h2 id="motivation">Motivation</h2> <p>Current LP (Liquidity Provider) tokens are simple <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> tokens with no complex data structure. To allow more complex reward and redemption logic to be stored on-chain, we need a new token standard that:</p> <ul> <li>Supports multiple token IDs</li> <li>Can store on-chain metadata</li> <li>Doesn't require a fixed storage pattern</li> <li>Is gas-efficient.</li> </ul> <p>Also Some benefits:</p> <ul> <li>This EIP allows the creation of any obligation with the same interface.</li> <li>It will enable any 3rd party wallet applications or exchanges to read these tokens' balance and redemption conditions.</li> <li>These bonds can also be batched as tradeable instruments. Those instruments can then be divided and exchanged in secondary markets.</li> </ul> <h2 id="specification">Specification</h2> <p><strong>Definition</strong></p> <p>Bank: an entity that issues, redeems, or burns bonds after getting the necessary amount of liquidity. Generally, a single entity with admin access to the pool.</p> <p><strong>Functions</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-comment">* transferFrom</span></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"> argument is the address of the bond holder whose balance is about to decrease.</span></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"> argument is the address of the bond recipient whose balance is about to increase.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _transactions</span><span class="z-comment"> is the `Transaction[] calldata` (of type [&#39;classId&#39;, &#39;nonceId&#39;, &#39;_amountBonds&#39;]) structure defined in the rationale section below.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> transferFrom MUST have the `isApprovedFor(_from, _to, _transactions[i].classId)` approval to transfer `_from` address to `_to` address for given classId (i.e for Transaction tuple corresponding to all nonces).</span></span> <span class="giallo-l"><span class="z-comment">e.g:</span></span> <span class="giallo-l"><span class="z-comment">* function transferFrom(0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef, 0x82a55a613429Aeb3D01fbE6841bE1AcA4fFD5b2B, [IERC3475.Transaction(1,14,500)]);</span></span> <span class="giallo-l"><span class="z-comment">* transfer from `_from` address, to `_to` address, `500000000` bonds of type class`1` and nonce `42`.</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"> 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-storage z-type"> Transaction</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _transactions</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">* transferAllowanceFrom</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 transfer of only those bond types and nonces being allotted to the _to address using allowance().</span></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"> is the address of the holder whose balance is about to decrease.</span></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"> is the address of the recipient whose balance is about to increase.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _transactions</span><span class="z-comment"> is the `Transaction[] calldata` structure defined in the section `rationale` below.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> transferAllowanceFrom MUST have the `allowance(_from, msg.sender, _transactions[i].classId, _transactions[i].nonceId)` (where `i` looping for [ 0 ...Transaction.length - 1] ) </span></span> <span class="giallo-l"><span class="z-comment">e.g:</span></span> <span class="giallo-l"><span class="z-comment">* function transferAllowanceFrom(0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef, 0x82a55a613429Aeb3D01fbE6841bE1AcA4fFD5b2B, [IERC3475.Transaction(1,14,500)]);</span></span> <span class="giallo-l"><span class="z-comment">* transfer from `_from` address, to `_to` address, `500000000` bonds of type class`1` and nonce `42`.</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"> transferAllowanceFrom</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"> Transaction</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _transactions</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> <span class="giallo-l"><span class="z-comment">* issue </span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> allows issuing any number of bond types (defined by values in Transaction tuple as param) to an address.</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 issued by a single entity (for instance, a role-based ownable contract that has integration with the liquidity pool of the deposited collateral by `_to` address).</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-comment"> `_to` argument is the address to which the bond will be issued.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-comment"> `_transactions` is the `Transaction[] calldata` (ie array of issued bond class, bond nonce and amount of bonds to be issued).</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> transferAllowanceFrom MUST have the `allowance(_from, msg.sender, _transactions[i].classId, _transactions[i].nonceId)` (where `i` looping for [ 0 ...Transaction.length - 1] ) </span></span> <span class="giallo-l"><span class="z-comment">e.g:</span></span> <span class="giallo-l"><span class="z-comment">example: issue(0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef,[IERC3475.Transaction(1,14,500)]);</span></span> <span class="giallo-l"><span class="z-comment">issues `1000` bonds with a class of `0` to address `0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef` with a nonce of `5`.</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"> issue</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"> Transaction</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _transaction</span><span>)</span><span class="z-storage z-type"> external</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">* redeem</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> permits redemption of bond from an 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 calling of this function needs to be restricted to the bond issuer contract.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-comment"> `_from` is the address from which the bond will be redeemed.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-comment"> `_transactions` is the `Transaction[] calldata` structure (i.e., array of tuples with the pairs of (class, nonce and amount) of the bonds that are to be redeemed). Further defined in the rationale section.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> redeem function for a given class, and nonce category MUST BE done after certain conditions for maturity (can be end time, total active liquidity, etc.) are met. </span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> furthermore, it SHOULD ONLY be called by the bank or secondary market maker contract.</span></span> <span class="giallo-l"><span class="z-comment">e.g:</span></span> <span class="giallo-l"><span class="z-comment">* redeem(0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef, [IERC3475.Transaction(1,14,500)]);</span></span> <span class="giallo-l"><span class="z-comment">means “redeem from wallet address(0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef), 500000000 of bond class1 and nonce 42.</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"> redeem</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"> Transaction</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _transactions</span><span>)</span><span class="z-storage z-type"> external</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">* burn</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> permits nullifying of the bonds (or transferring given bonds to address(0)).</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> burn function for given class and nonce MUST BE called by only the 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"> _from</span><span class="z-comment"> is the address of the holder whose bonds are about to burn.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-comment"> `_transactions` is the `Transaction[] calldata` structure (i.e., array of tuple with the pairs of (class, nonce and amount) of the bonds that are to be burned). further defined in the rationale.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> burn function for a given class, and nonce category MUST BE done only after certain conditions for maturity (can be end time, total active liquidity, etc). </span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> furthermore, it SHOULD ONLY be called by the bank or secondary market maker contract.</span></span> <span class="giallo-l"><span class="z-comment">* e.g: </span></span> <span class="giallo-l"><span class="z-comment">* burn(0x82a55a613429Aeb3D01fbE6841bE1AcA4fFD5b2B,[IERC3475.Transaction(1,14,500)]);</span></span> <span class="giallo-l"><span class="z-comment">* means burning 500000000 bonds of class 1 nonce 42 owned by address 0x82a55a613429Aeb3D01fbE6841bE1AcA4fFD5b2B.</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 class="z-support">address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span><span class="z-storage z-type"> Transaction</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _transactions</span><span>)</span><span class="z-storage z-type"> external</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">* approve</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Allows `_spender` to withdraw from the msg.sender the bonds of `_amount` and type (classId and nonceId).</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If this function is called again, it overwrites the current allowance with the amount.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> `approve()` should only be callable by the bank, or the owner 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-comment"> `_spender` argument is the address of the user who is approved to transfer the bonds.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-comment"> `_transactions` is the `Transaction[] calldata` structure (ie array of tuple with the pairs of (class,nonce, and amount) of the bonds that are to be approved to be spend by _spender). Further defined in the rationale section.</span></span> <span class="giallo-l"><span class="z-comment">* e.g: </span></span> <span class="giallo-l"><span class="z-comment">* approve(0x82a55a613429Aeb3D01fbE6841bE1AcA4fFD5b2B,[IERC3475.Transaction(1,14,500)]);</span></span> <span class="giallo-l"><span class="z-comment">* means owner of address 0x82a55a613429Aeb3D01fbE6841bE1AcA4fFD5b2B is approved to manage 500 bonds from class 1 and Nonce 14.</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"> 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-storage z-type"> Transaction</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _transactions</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">* SetApprovalFor</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> enable or disable approval for a third party (“operator”) to manage all the Bonds in the given class of the caller’s bonds.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> If this function is called again, it overwrites the current allowance with the amount.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> `approve()` should only be callable by the bank or the owner 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-comment"> `_operator` is the 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-comment"> `classId` is the class id of the bond.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-comment"> `_approved` is true if the operator is approved (based on the conditions provided), false meaning approval is revoked.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> contract MUST define internal function regarding the conditions for setting approval and should be callable only by bank or owner.</span></span> <span class="giallo-l"><span class="z-comment">* e.g: setApprovalFor(0x82a55a613429Aeb3D01fbE6841bE1AcA4fFD5b2B,0,true);</span></span> <span class="giallo-l"><span class="z-comment">* means that address 0x82a55a613429Aeb3D01fbE6841bE1AcA4fFD5b2B is authorized to transfer bonds from class 0 (across all nonces).</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"> setApprovalFor</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 class="z-keyword"> returns</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">* totalSupply</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Here, total supply includes burned and redeemed supply.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> classId</span><span class="z-comment"> is the corresponding class Id of the bond.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> nonceId</span><span class="z-comment"> is the nonce Id of the given bond class.</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"> supply of the bonds</span></span> <span class="giallo-l"><span class="z-comment">* e.g:</span></span> <span class="giallo-l"><span class="z-comment">* totalSupply(0, 1);</span></span> <span class="giallo-l"><span class="z-comment">* it finds the total supply of the bonds of classid 0 and bond nonce 1.</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"> classId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> nonceId</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">* redeemedSupply</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 redeemed supply of the bond identified by (classId,nonceId).</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> classId</span><span class="z-comment"> is the corresponding class id of the bond.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> nonceId</span><span class="z-comment"> is the nonce id of the given bond class.</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"> supply of bonds redeemed.</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"> redeemedSupply</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> classId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> nonceId</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">* activeSupply</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 active supply of the bond defined by (classId,NonceId).</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> classId</span><span class="z-comment"> is the corresponding classId of the bond.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> nonceId</span><span class="z-comment"> is the nonce id of the given bond class.</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"> non-redeemed, active 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"> activeSupply</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> classId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> nonceId</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">* burnedSupply</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 burned supply of the bond in defined by (classId,NonceId).</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> classId</span><span class="z-comment"> is the corresponding classId of the bond.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> nonceId</span><span class="z-comment"> is the nonce id of the given bond class.</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"> gets</span><span class="z-comment"> the supply of bonds for given classId and nonceId that are already burned.</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"> burnedSupply</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> classId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> nonceId</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">* balanceOf</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 balance of the bonds (nonReferenced) of given classId and bond nonce held by the address `_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"> classId</span><span class="z-comment"> is the corresponding classId of the bond.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> nonceId</span><span class="z-comment"> is the nonce id of the given bond class.</span></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 of the owner whose balance is to be determined.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> this also consists of bonds that are redeemed.</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"> _account</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> classId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> nonceId</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">* classMetadata</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 JSON metadata of the classes.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The metadata SHOULD follow a set of structures explained later in the metadata.md</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> metadataId</span><span class="z-comment"> is the index-id given bond class 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"> the</span><span class="z-comment"> JSON metadata of the nonces. — e.g. `[title, type, description]`.</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"> classMetadata</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> metadataId</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">Metadata</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-comment">* nonceMetadata </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 JSON metadata of the nonces.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The metadata SHOULD follow a set of structures explained later in metadata.md</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> classId</span><span class="z-comment"> is the corresponding classId of the bond.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> nonceId</span><span class="z-comment"> is the nonce id of the given bond class.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> metadataId</span><span class="z-comment"> is the index of the JSON storage for given metadata information. more is defined in metadata.md.</span></span> <span class="giallo-l"><span class="z-comment">* @returns the JSON metadata of the nonces. — e.g. `[title, type, description]`.</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"> nonceMetadata</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> classId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> metadataId</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">Metadata</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-comment">* classValues</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> allows anyone to read the values (stored in struct Values for different class) for given bond class `classId`.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> the values SHOULD follow a set of structures as explained in metadata along with correct mapping corresponding to the given metadata structure</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> classId</span><span class="z-comment"> is the corresponding classId of the bond.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> metadataId</span><span class="z-comment"> is the index of the JSON storage for given metadata information of all values of given metadata. more is defined in metadata.md.</span></span> <span class="giallo-l"><span class="z-comment">* @returns the Values of the class metadata. — e.g. `[string, uint, 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"> classValues</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> classId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> metadataId</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">Values</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-comment">* nonceValues</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> allows anyone to read the values (stored in struct Values for different class) for given bond (`nonceId`,`classId`).</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> the values SHOULD follow a set of structures explained in metadata along with correct mapping corresponding to the given metadata structure</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> classId</span><span class="z-comment"> is the corresponding classId of the bond.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> metadataId</span><span class="z-comment"> is the index of the JSON storage for given metadata information of all values of given metadata. More is defined in metadata.md.</span></span> <span class="giallo-l"><span class="z-comment">* @returns the Values of the class metadata. — e.g. `[string, uint, 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"> nonceValues</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> classId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> nonceId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> metadataId</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">Values</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-comment">* getProgress</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 parameters to determine the current status of bonds maturity.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> the conditions of redemption SHOULD be defined with one or several internal functions. </span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> classId</span><span class="z-comment"> is the corresponding classId of the bond.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> nonceId</span><span class="z-comment"> is the nonceId of the given bond class . </span></span> <span class="giallo-l"><span class="z-comment">* @returns progressAchieved defines the metric (either related to % liquidity, time, etc.) that defines the current status of the bond.</span></span> <span class="giallo-l"><span class="z-comment">* @returns progressRemaining defines the metric that defines the remaining time/ remaining progress. </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"> getProgress</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> classId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> nonceId</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"> progressAchieved</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> progressRemaining</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">* allowance</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Authorizes to set the allowance for given `_spender` by `_owner` for all bonds identified by (classId, nonceId).</span></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 of the owner of bond(and also 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"> _spender</span><span class="z-comment"> is the address authorized to spend the bonds held by _owner of info (classId, nonceId).</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> classId</span><span class="z-comment"> is the corresponding classId of the bond.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> nonceId</span><span class="z-comment"> is the nonceId of the given bond class. </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 _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"> classId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> nonceId</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-comment"> </span></span> <span class="giallo-l"><span class="z-comment">* isApprovedFor</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 address _operator is approved for managing the account’s bonds class.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Queries the approval status of an operator for a given owner.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> _owner is the owner of bonds. </span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> _operator is the EOA /contract, whose status for approval on bond class for this approval is checked.</span></span> <span class="giallo-l"><span class="z-comment">* @returns “true” if the operator is approved, “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"> isApprovedFor</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></code></pre><h3 id="events">Events</h3> <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">* Issue</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Issue MUST trigger when Bonds are issued. This SHOULD not include zero value Issuing.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This SHOULD not include zero value issuing.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Issue MUST be triggered when the operator (i.e Bank address) contract issues bonds to the given entity.</span></span> <span class="giallo-l"><span class="z-comment">* eg: emit Issue(_operator, 0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef,[IERC3475.Transaction(1,14,500)]); </span></span> <span class="giallo-l"><span class="z-comment">* issue by address(operator) 500 Bonds(nonce14,class 1) to address 0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef.</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">event</span><span class="z-entity z-name"> Issue</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"> _to</span><span>, </span><span class="z-variable">Transaction</span><span>[</span><span>]</span><span class="z-variable"> _transactions</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"> </span></span> <span class="giallo-l"><span class="z-comment">* Redeem</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Redeem MUST trigger when Bonds are redeemed. This SHOULD not include zero value redemption.</span></span> <span class="giallo-l"><span class="z-comment">*e.g: emit Redeem(0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef,0x492Af743654549b12b1B807a9E0e8F397E44236E,[IERC3475.Transaction(1,14,500)]);</span></span> <span class="giallo-l"><span class="z-comment">* emit event when 5000 bonds of class 1, nonce 14 owned by address 0x492Af743654549b12b1B807a9E0e8F397E44236E are being redeemed by 0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef.</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">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"> _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-variable">Transaction</span><span>[</span><span>]</span><span class="z-variable"> _transactions</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"> </span></span> <span class="giallo-l"><span class="z-comment">* Burn.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> `Burn` MUST trigger when the bonds are being redeemed via staking (or being invalidated) by the bank contract.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> `Burn` MUST trigger when Bonds are burned. This SHOULD not include zero value burning.</span></span> <span class="giallo-l"><span class="z-comment">* e.g : emit Burn(0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef,0x492Af743654549b12b1B807a9E0e8F397E44236E,[IERC3475.Transaction(1,14,500)]);</span></span> <span class="giallo-l"><span class="z-comment">* emits event when 500 bonds of owner 0x492Af743654549b12b1B807a9E0e8F397E44236E of type (class 1, nonce 14) are burned by operator 0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef.</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">event</span><span class="z-entity z-name"> burn</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-variable">Transaction</span><span>[</span><span>]</span><span class="z-variable"> _transactions</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">* Transfer</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> its emitted when the bond is transferred by address(operator) from owner address(_from) to address(_to) with the bonds transferred, whose params are defined by _transactions struct array. </span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Transfer MUST trigger when Bonds are transferred. This SHOULD not include zero value transfers.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Transfer event with the _from `0x0` MUST not create this event(use `event Issued` instead). </span></span> <span class="giallo-l"><span class="z-comment">* e.g emit Transfer(0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef, 0x492Af743654549b12b1B807a9E0e8F397E44236E, _to, [IERC3475.Transaction(1,14,500)]);</span></span> <span class="giallo-l"><span class="z-comment">* transfer by address(_operator) amount 500 bonds with (Class 1 and Nonce 14) from 0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef, to address(_to).</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">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"> _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">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-variable">Transaction</span><span>[</span><span>]</span><span class="z-variable"> _transactions</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">* ApprovalFor</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> its emitted when address(_owner) approves the address(_operator) to transfer his bonds.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Approval MUST trigger when bond holders are approving an _operator. This SHOULD not include zero value approval. </span></span> <span class="giallo-l"><span class="z-comment">* eg: emit ApprovalFor(0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef, 0x492Af743654549b12b1B807a9E0e8F397E44236E, true);</span></span> <span class="giallo-l"><span class="z-comment">* this means 0x2d03B6C79B75eE7aB35298878D05fe36DC1fE8Ef gives 0x492Af743654549b12b1B807a9E0e8F397E44236E access permission for transfer of its bonds.</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">event</span><span class="z-entity z-name"> ApprovalFor</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></code></pre> <p><strong>Metadata</strong>: The metadata of a bond class or nonce is stored as an array of JSON objects, represented by the following types.</p> <p><strong>NOTE: all of the metadata schemas are referenced from <a href="https://wg-eips.ritovision.com/3475/assets/Metadata/">here</a></strong></p> <h3 id="1-description">1. Description:</h3> <p>This defines the additional information about the nature of data being stored in the nonce/class metadata structures. They are defined using the structured explained <a href="https://wg-eips.ritovision.com/3475/assets/Metadata/#1-description-metadata">here</a>. this will then be used by the frontend of the respective entities participating in the bond markets to interpret the data which is compliant with their jurisdiction.</p> <h3 id="2-nonce">2. Nonce:</h3> <p>The key value for indexing the information is the 'class' field. Following are the rules:</p> <ul> <li>The title can be any alphanumeric type that is differentiated by the description of metadata (although it can be dependent on certain jurisdictions).</li> <li>The title SHOULD not be EMPTY.</li> </ul> <p>Some specific examples of metadata can be the localization of bonds, jurisdiction details etc., and they can be found in the <a href="https://wg-eips.ritovision.com/3475/assets/Metadata/">metadata.md</a> example description.</p> <h3 id="3-class-metadata">3. Class metadata:</h3> <p>This structure defines the details of the class information (symbol, risk information, etc.). the example is explained <a href="https://wg-eips.ritovision.com/3475/assets/Metadata/">here</a> in the class metadata section.</p> <h3 id="4-decoding-data">4. Decoding data</h3> <p>First, the functions for analyzing the metadata (i.e <code>ClassMetadata</code> and <code>NonceMetadata</code>) are to be used by the corresponding frontend to decode the information of the bond.</p> <p>This is done via overriding the function interface for functions <code>classValues</code> and <code>nonceValues</code> by defining the key (which SHOULD be an index) to read the corresponding information stored as a JSON 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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">symbol</span><span class="z-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">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">defines the unique identifier name in following format: (symbol, bondType, maturity in months)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support">&quot;</span><span class="z-support">values</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">Class Name 1</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">Class Name 2</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">DBIT Fix 6M</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>e.g. In the above example, to get the <code>symbol</code> of the given class id, we can use the class id as a key to get the <code>symbol</code> value in the values, which then can be used for fetching the detail for instance.</p> <h2 id="rationale">Rationale</h2> <h3 id="metadata-structure">Metadata structure</h3> <p>Instead of storing the details about the class and their issuances to the user (ie nonce) externally, we store the details in the respective structures. Classes represent the different bond types, and nonces represent the various period of issuances. Nonces under the same class share the same metadata. Meanwhile, nonces are non-fungible. Each nonce can store a different set of metadata. Thus, upon transfer of a bond, all the metadata will be transferred to the new owner of the bond.</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 class="z-support"> bytes</span><span> bytesValue</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-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><h3 id="batch-function">Batch function</h3> <p>This EIP supports batch operations. It allows the user to transfer different bonds along with their metadata to a new address instantaneously in a single transaction. After execution, the new owner holds the right to reclaim the face value of each of the bonds. This mechanism helps with the "packaging" of bonds–helpful in use cases like trades on a secondary market.</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"> Transaction</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> classId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> nonceId</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></code></pre> <p>Where: The <code>classId</code> is the class id of the bond.</p> <p>The <code>nonceId</code> is the nonce id of the given bond class. This param is for distinctions of the issuing conditions of the bond.</p> <p>The <code>_amount</code> is the amount of the bond for which the spender is approved.</p> <h3 id="amm-optimization">AMM optimization</h3> <p>One of the most obvious use cases of this EIP is the multilayered pool. The early version of AMM uses a separate smart contract and an <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> LP token to manage a pair. By doing so, the overall liquidity inside of one pool is significantly reduced and thus generates unnecessary gas spent and slippage. Using this EIP standard, one can build a big liquidity pool with all the pairs inside (thanks to the presence of the data structures consisting of the liquidity corresponding to the given class and nonce of bonds). Thus by knowing the class and nonce of the bonds, the liquidity can be represented as the percentage of a given token pair for the owner of the bond in the given pool. Effectively, the <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> LP token (defined by a unique smart contract in the pool factory contract) is aggregated into a single bond and consolidated into a single pool.</p> <ul> <li>The reason behind the standard's name (abstract storage bond) is its ability to store all the specifications (metadata/values and transaction as defined in the following sections) without needing external storage on-chain/off-chain.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Any contract that inherits the interface of this EIP is compatible. This compatibility exists for issuer and receiver of the bonds. Also any client EOA wallet can be compatible with the standard if they are able to sign <code>issue()</code> and <code>redeem()</code> commands.</p> <p>However, any existing <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> token contract can issue its bonds by delegating the minting role to a bank contract with the interface of this standard built-in. Check out our reference implementation for the correct interface definition.</p> <p>To ensure the indexing of transactions throughout the bond lifecycle (i.e "Issue", "Redeem" and "Transfer" functions), events cited in specification section MUST be emitted when such transaction is passed.</p> <p><strong>Note that the this standard interface is also compatible with <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> and <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>interface.</strong></p> <p>However, creating a separate bank contract is recommended for reading the bonds and future upgrade needs.</p> <p>Acceptable collateral can be in the form of fungible (like <a href="https://wg-eips.ritovision.com/20/">EIP-20</a>), non-fungible (<a href="https://wg-eips.ritovision.com/721/">EIP-721</a>, <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>) , or other bonds represented by this standard.</p> <h2 id="test-cases">Test Cases</h2> <p>Test-case for the minimal reference implementation is <a href="https://wg-eips.ritovision.com/3475/./assets/ERC3475.test.ts">here</a>. Use the Truffle box to compile and test the contracts.</p> <h2 id="reference-implementation">Reference Implementation</h2> <ul> <li> <p><a href="https://wg-eips.ritovision.com/3475/./assets/interfaces/IERC3475.sol">Interface</a>.</p> </li> <li> <p><a href="https://wg-eips.ritovision.com/3475/./assets/ERC3475.sol">Basic Example</a>.</p> <ul> <li>This demonstration shows only minimalist implementation.</li> </ul> </li> </ul> <h2 id="security-considerations">Security Considerations</h2> <ul> <li> <p>The <code>function setApprovalFor(address _operatorAddress)</code> gives the operator role to <code>_operatorAddress</code>. It has all the permissions to transfer, burn and redeem bonds by default.</p> </li> <li> <p>If the owner wants to give a one-time allocation to an address for specific bonds(classId,bondsId), he should call the <code>function approve()</code> giving the <code>Transaction[]</code> allocated rather than approving all the classes using <code>setApprovalFor</code>.</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> 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 pinkiebellhttps://github.com/pinkiebell https://wg-eips.ritovision.com/3448/

A minimal bytecode implementation for creating proxy contracts with immutable metadata attached to the bytecode

<h2 id="abstract">Abstract</h2> <p>By standardizing on a known minimal bytecode proxy implementation with support for immutable metadata, this standard allows users and third party tools (e.g. Etherscan) to: (a) simply discover that a contract will always redirect in a known manner and (b) depend on the behavior of the code at the destination contract as the behavior of the redirecting contract and (c) verify/view the attached metadata.</p> <p>Tooling can interrogate the bytecode at a redirecting address to determine the location of the code that will run along with the associated metadata - and can depend on representations about that code (verified source, third-party audits, etc). This implementation forwards all calls via <code>DELEGATECALL</code> and any (calldata) input plus the metadata at the end of the bytecode to the implementation contract and then relays the return value back to the caller. In the case where the implementation reverts, the revert is passed back along with the payload data.</p> <h2 id="motivation">Motivation</h2> <p>This standard supports use-cases wherein it is desirable to clone exact contract functionality with different parameters at another address.</p> <h2 id="specification">Specification</h2> <p>The exact bytecode of the MetaProxy contract is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> 20 bytes target contract address</span></span> <span class="giallo-l"><span> ----------------------------------------</span></span> <span class="giallo-l"><span>363d3d373d3d3d3d60368038038091363936013d7300000000000000000000000000000000000000005af43d3d93803e603457fd5bf3</span></span></code></pre> <p>wherein the bytes at indices 21 - 41 (inclusive) are replaced with the 20 byte address of the master functionality contract. Additionally, everything after the MetaProxy bytecode can be arbitrary metadata and the last 32 bytes (one word) of the bytecode must indicate the length of the metadata in bytes.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&lt;54 bytes metaproxy&gt; &lt;arbitrary data&gt; &lt;length in bytes of arbitrary data (uint256)&gt;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The goals of this effort have been the following:</p> <ul> <li>a cheap way of storing immutable metadata for each child instead of using storage slots</li> <li>inexpensive deployment of clones</li> <li>handles error return bubbling for revert messages</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no backwards compatibility issues.</p> <h2 id="test-cases">Test Cases</h2> <p>Tested with:</p> <ul> <li>invocation with no arguments</li> <li>invocation with arguments</li> <li>invocation with return values</li> <li>invocation with revert (confirming reverted payload is transferred)</li> </ul> <p>A solidity contract with the above test cases can be found <a href="https://wg-eips.ritovision.com/3448/./assets/MetaProxyTest.sol">in the EIP asset directory</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A reference implementation can be found <a href="https://wg-eips.ritovision.com/3448/./assets/MetaProxyFactory.sol">in the EIP asset directory</a>.</p> <h3 id="deployment-bytecode">Deployment bytecode</h3> <p>A annotated version of the deploy bytecode:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// PUSH1 11;</span></span> <span class="giallo-l"><span>// CODESIZE;</span></span> <span class="giallo-l"><span>// SUB;</span></span> <span class="giallo-l"><span>// DUP1;</span></span> <span class="giallo-l"><span>// PUSH1 11;</span></span> <span class="giallo-l"><span>// RETURNDATASIZE;</span></span> <span class="giallo-l"><span>// CODECOPY;</span></span> <span class="giallo-l"><span>// RETURNDATASIZE;</span></span> <span class="giallo-l"><span>// RETURN;</span></span></code></pre><h3 id="metaproxy">MetaProxy</h3> <p>A annotated version of the MetaProxy bytecode:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// copy args</span></span> <span class="giallo-l"><span>// CALLDATASIZE; calldatasize</span></span> <span class="giallo-l"><span>// RETURNDATASIZE; 0, calldatasize</span></span> <span class="giallo-l"><span>// RETURNDATASIZE; 0, 0, calldatasize</span></span> <span class="giallo-l"><span>// CALLDATACOPY;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// RETURNDATASIZE; 0</span></span> <span class="giallo-l"><span>// RETURNDATASIZE; 0, 0</span></span> <span class="giallo-l"><span>// RETURNDATASIZE; 0, 0, 0</span></span> <span class="giallo-l"><span>// RETURNDATASIZE; 0, 0, 0, 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// PUSH1 54; 54, 0, 0, 0, 0</span></span> <span class="giallo-l"><span>// DUP1; 54, 54, 0, 0, 0, 0</span></span> <span class="giallo-l"><span>// CODESIZE; codesize, 54, 54, 0, 0, 0, 0</span></span> <span class="giallo-l"><span>// SUB; codesize-54, 54, 0, 0, 0, 0</span></span> <span class="giallo-l"><span>// DUP1; codesize-54, codesize-54, 54, 0, 0, 0, 0</span></span> <span class="giallo-l"><span>// SWAP2; 54, codesize-54, codesize-54, 0, 0, 0, 0</span></span> <span class="giallo-l"><span>// CALLDATASIZE; calldatasize, 54, codesize-54, codesize-54, 0, 0, 0, 0</span></span> <span class="giallo-l"><span>// CODECOPY; codesize-54, 0, 0, 0, 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// CALLDATASIZE; calldatasize, codesize-54, 0, 0, 0, 0</span></span> <span class="giallo-l"><span>// ADD; calldatasize+codesize-54, 0, 0, 0, 0</span></span> <span class="giallo-l"><span>// RETURNDATASIZE; 0, calldatasize+codesize-54, 0, 0, 0, 0</span></span> <span class="giallo-l"><span>// PUSH20 0; addr, 0, calldatasize+codesize-54, 0, 0, 0, 0 - zero is replaced with shl(96, address())</span></span> <span class="giallo-l"><span>// GAS; gas, addr, 0, calldatasize+codesize-54, 0, 0, 0, 0</span></span> <span class="giallo-l"><span>// DELEGATECALL; (gas, addr, 0, calldatasize() + metadata, 0, 0) delegatecall to the target contract;</span></span> <span class="giallo-l"><span>//</span></span> <span class="giallo-l"><span>// RETURNDATASIZE; returndatasize, retcode, 0, 0</span></span> <span class="giallo-l"><span>// RETURNDATASIZE; returndatasize, returndatasize, retcode, 0, 0</span></span> <span class="giallo-l"><span>// SWAP4; 0, returndatasize, retcode, 0, returndatasize</span></span> <span class="giallo-l"><span>// DUP1; 0, 0, returndatasize, retcode, 0, returndatasize</span></span> <span class="giallo-l"><span>// RETURNDATACOPY; (0, 0, returndatasize) - Copy everything into memory that the call returned</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// stack = retcode, 0, returndatasize # this is for either revert(0, returndatasize()) or return (0, returndatasize())</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// PUSH1 _SUCCESS_; push jumpdest of _SUCCESS_</span></span> <span class="giallo-l"><span>// JUMPI; jump if delegatecall returned `1`</span></span> <span class="giallo-l"><span>// REVERT; (0, returndatasize()) if delegatecall returned `0`</span></span> <span class="giallo-l"><span>// JUMPDEST _SUCCESS_;</span></span> <span class="giallo-l"><span>// RETURN; (0, returndatasize()) if delegatecall returned non-zero (1)</span></span></code></pre><h3 id="examples">Examples</h3> <p>The following code snippets serve only as suggestions and are not a discrete part of this standard.</p> <h4 id="proxy-construction-with-bytes-from-abi-encode">Proxy construction with bytes from abi.encode</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> MetaProxy construction via abi encoded bytes.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> createFromBytes</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> a</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> b</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"> c</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 class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> proxy</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> creates a new proxy where the metadata is the result of abi.encode()</span></span> <span class="giallo-l"><span> proxy </span><span class="z-keyword">=</span><span> MetaProxyFactory</span><span>.</span><span class="z-entity z-name">_metaProxyFromBytes</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"> abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span><span>a</span><span>,</span><span> b</span><span>,</span><span> c</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>proxy </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"> optional one-time setup, a constructor() substitute</span></span> <span class="giallo-l"><span class="z-entity z-name"> MyContract</span><span>(</span><span>proxy</span><span>)</span><span>.</span><span>init</span><span>{</span><span> value</span><span class="z-keyword">:</span><span class="z-variable z-language"> msg</span><span>.</span><span>value </span><span>}</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="proxy-construction-with-bytes-from-calldata">Proxy construction with bytes from calldata</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> MetaProxy construction via calldata.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> createFromCalldata</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> a</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> b</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"> c</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 class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> proxy</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> creates a new proxy where the metadata is everything after the 4th byte from calldata.</span></span> <span class="giallo-l"><span> proxy </span><span class="z-keyword">=</span><span> MetaProxyFactory</span><span>.</span><span class="z-entity z-name">_metaProxyFromCalldata</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 class="z-keyword"> require</span><span>(</span><span>proxy </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"> optional one-time setup, a constructor() substitute</span></span> <span class="giallo-l"><span class="z-entity z-name"> MyContract</span><span>(</span><span>proxy</span><span>)</span><span>.</span><span>init</span><span>{</span><span> value</span><span class="z-keyword">:</span><span class="z-variable z-language"> msg</span><span>.</span><span>value </span><span>}</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="retrieving-the-metadata-from-calldata-and-abi-decode">Retrieving the metadata from calldata and abi.decode</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the metadata of this (MetaProxy) contract.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Only relevant with contracts created via the MetaProxy standard.</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 aimed to be invoked with- &amp; without a call.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getMetadataWithoutCall</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> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> a</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> b</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"> c</span></span> <span class="giallo-l"><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> data</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> posOfMetadataSize </span><span class="z-keyword">:=</span><span class="z-entity z-name"> sub</span><span>(</span><span class="z-entity z-name">calldatasize</span><span>(</span><span>)</span><span>,</span><span class="z-constant"> 32</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> size </span><span class="z-keyword">:=</span><span class="z-entity z-name"> calldataload</span><span>(</span><span>posOfMetadataSize</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> dataPtr </span><span class="z-keyword">:=</span><span class="z-entity z-name"> sub</span><span>(</span><span>posOfMetadataSize</span><span>,</span><span> size</span><span>)</span></span> <span class="giallo-l"><span> data </span><span class="z-keyword">:=</span><span class="z-entity z-name"> mload</span><span>(</span><span class="z-constant">64</span><span>)</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> increment free memory pointer by metadata size + 32 bytes (length)</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-constant">64</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>data</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>size</span><span>,</span><span class="z-constant"> 32</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span>data</span><span>,</span><span> size</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> memPtr </span><span class="z-keyword">:=</span><span class="z-entity z-name"> add</span><span>(</span><span>data</span><span>,</span><span class="z-constant"> 32</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> calldatacopy</span><span>(</span><span>memPtr</span><span>,</span><span> dataPtr</span><span>,</span><span> size</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"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>data</span><span>,</span><span> (</span><span class="z-support">address</span><span>,</span><span class="z-support"> uint256</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="retrieving-the-metadata-via-a-call-to-self">Retrieving the metadata via a call to self</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the metadata of this (MetaProxy) contract.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Only relevant with contracts created via the MetaProxy standard.</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 aimed to be invoked via a call.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getMetadataViaCall</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> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> a</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> b</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"> c</span></span> <span class="giallo-l"><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-storage z-type"> let</span><span> posOfMetadataSize </span><span class="z-keyword">:=</span><span class="z-entity z-name"> sub</span><span>(</span><span class="z-entity z-name">calldatasize</span><span>(</span><span>)</span><span>,</span><span class="z-constant"> 32</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> size </span><span class="z-keyword">:=</span><span class="z-entity z-name"> calldataload</span><span>(</span><span>posOfMetadataSize</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> dataPtr </span><span class="z-keyword">:=</span><span class="z-entity z-name"> sub</span><span>(</span><span>posOfMetadataSize</span><span>,</span><span> size</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> dataPtr</span><span>,</span><span> size</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> size</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Apart from the examples above, it is also possible to use Solidity Structures or any custom data encoding.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This standard only covers the bytecode implementation and does not include any serious side effects of itself. The reference implementation only serves as a example. It is highly recommended to research side effects depending on how the functionality is used and implemented in any project.</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-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 Alexey Akhunovhttps://github.com/AlexeyAkhunov Christian Reitwiessnerhttps://github.com/chriseth Martin Swendehttps://github.com/holiman https://wg-eips.ritovision.com/3541/ <h2 id="abstract">Abstract</h2> <p>Disallow new code starting with the <code>0xEF</code> byte to be deployed. Code already existing in the account trie starting with <code>0xEF</code> byte is not affected semantically by this change.</p> <h2 id="motivation">Motivation</h2> <p>Contracts conforming to the EVM Object Format (EOF) are going to be validated at deploy time. 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 will be achieved by choosing a byte sequence for the <em>magic</em> that doesn't exist in any of the already deployed contracts. To prevent the growth of the search space and to limit the analysis to the contracts existing before this fork, we disallow the starting byte of the format (the first byte of the magic).</p> <p>Should the EVM Object Format proposal not be deployed in the future, the <em>magic</em> can be used by other features depending on versioning. In the case versioning becomes obsolete, it is simple to roll this back by allowing contracts starting with the <code>0xEF</code> byte to be deployed again.</p> <h2 id="specification">Specification</h2> <p>After <code>block.number == HF_BLOCK</code> new contract creation (via create transaction, <code>CREATE</code> or <code>CREATE2</code> instructions) results in an exceptional abort if the <em>code</em>'s first byte is <code>0xEF</code>.</p> <h3 id="remarks">Remarks</h3> <p>The <em>initcode</em> is the code executed in the context of the <em>create</em> transaction, <code>CREATE</code>, or <code>CREATE2</code> instructions. The <em>initcode</em> returns <em>code</em> (via the <code>RETURN</code> instruction), which is inserted into the account. See section 7 ("Contract Creation") in the Yellow Paper for more information.</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 <em>initcode</em> or already deployed <em>code</em> starting with this instruction will continue to abort execution.</p> <p>The exceptional abort due to <em>code</em> starting with <code>0xEF</code> behaves exactly the same as any other exceptional abort that can occur during <em>initcode</em> execution, i.e. in case of abort all gas provided to a <code>CREATE*</code> or create transaction is consumed.</p> <h2 id="rationale">Rationale</h2> <p>The <code>0xEF</code> byte was chosen because it resembles <strong>E</strong>xecutable <strong>F</strong>ormat.</p> <p>Contracts using unassigned opcodes are generally understood to be at risk of changing semantics. Hence using the unassigned <code>0xEF</code> should have lesser effects, than choosing an assigned opcode, such as <code>0xFD</code> (<code>REVERT</code>), <code>0xFE</code> (<code>INVALID)</code>, or <code>0xFF</code> (<code>SELFDESTRUCT</code>). Arguably while such contracts may not be very useful, they are still using valid opcodes.</p> <p>Analysis in May 2021, on <code>18084433</code> contracts in state, showed that there are 0 existing contracts starting with the <code>0xEF</code> byte, as opposed to 1, 4, and 12 starting with <code>0xFD</code>, <code>0xFE</code>, and <code>0xFF</code>, respectively.</p> <h2 id="test-cases">Test Cases</h2> <p>Each test case below may be executed in 3 different contexts:</p> <ul> <li>create transaction (no account code)</li> <li><code>CREATE</code>, with account code: <code>0x6000356000523660006000f0151560165760006000fd5b</code> (Yul code: <code>mstore(0, calldataload(0)) if iszero(create(0, 0, calldatasize())) { revert(0, 0) }</code>),</li> <li><code>CREATE2</code>, with account code: <code>0x60003560005260003660006000f5151560185760006000fd5b</code> (Yul code: <code>mstore(0, calldataload(0)) if iszero(create2(0, 0, calldatasize(), 0)) { revert(0, 0) }</code>)</li> </ul> <table><thead><tr><th>Case</th><th>Calldata</th><th>Expected result</th></tr></thead><tbody> <tr><td>deploy one byte <code>ef</code></td><td><code>0x60ef60005360016000f3</code></td><td>new contract not deployed, transaction fails</td></tr> <tr><td>deploy two bytes <code>ef00</code></td><td><code>0x60ef60005360026000f3</code></td><td>new contract not deployed, transaction fails</td></tr> <tr><td>deploy three bytes <code>ef0000</code></td><td><code>0x60ef60005360036000f3</code></td><td>new contract not deployed, transaction fails</td></tr> <tr><td>deploy 32 bytes <code>ef00...00</code></td><td><code>0x60ef60005360206000f3</code></td><td>new contract not deployed, transaction fails</td></tr> <tr><td>deploy one byte <code>fe</code></td><td><code>0x60fe60005360016000f3</code></td><td>new contract deployed, transaction succeeds</td></tr> </tbody></table> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a breaking change given new code starting with the <code>0xEF</code> byte will not be deployable, and contract creation will result in a failure. However, given bytecode is executed starting at its first byte, code deployed with <code>0xEF</code> as the first byte is not executable anyway.</p> <p>While this means no currently executable contract is affected, it does rejects deployment of new data contracts starting with the <code>0xEF</code> byte.</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-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-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Query0xhttps://github.com/Query0x https://wg-eips.ritovision.com/3374/ <h2 id="simple-summary">Simple Summary</h2> <p>Sets block reward to 3 and reduces it to 1 linearly over the course of about 1 year.</p> <h2 id="abstract">Abstract</h2> <p>Sets the block reward to 3 ETH and then incrementally decreases it every block for 2,362,000 blocks (approximately 1 year) until it reaches 1 ETH.</p> <h2 id="motivation">Motivation</h2> <p>Unnecessarily abrupt changes to the Ethereum ecosystem cause disruption and disharmony resulting in the disenfranchisement of community members while undermining stability and confidence. While moves from Proof-of-Work to Proof-of-Stake will undoubtedly cause friction between those community members vested in either, all benefit from a measured, predictable transition.</p> <p>This proposal:</p> <ol> <li>Is issuance neutral over 1 year, and reduces issuance beyond that.</li> <li>Sets an initial block reward of 3;</li> <li>Introduces an ongoing, predictable reduction in future mining rewards down to 1, effectively "sunsetting" POW and codifying the move to POS;</li> <li>Reduces economic incentives for continued development of ASICs;</li> <li>Allows the impacts of decreasing miner rewards to be measured and monitored rather than relying on conjecture and game theory, so adjustments can be made if necessary.</li> </ol> <h2 id="specification">Specification</h2> <h3 id="constants">Constants</h3> <ul> <li><code>TRANSITION_START_BLOCK_NUMBER: TBD</code></li> <li><code>TRANSITION_DURATION: 2_362_000</code> // (about one year)</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>Picking starting and ending block reward values that are equidistant from the current block reward rate of 2 ensures the impact of this EIP will be issuance neutral over the one year time frame. Temporarily raising the block reward to 3 blunts the initial impact of a sudden miner revenue decrease and the continual reductions thereafter codify Ethereum's move to POS by increasingly disincentivizing POW. Importantly, this approach moderates the rate of change so impacts and threats can be measured and monitored.</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-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Philippe Castonguayhttps://github.com/PhABC https://wg-eips.ritovision.com/3382/ <h2 id="simple-summary">Simple Summary</h2> <p>Hardcode the block gas limit to <code>12,500,000</code> gas per block.</p> <h2 id="abstract">Abstract</h2> <p>Updates the block validation rules such that a block is invalid if the <code>gas_limit</code> header field is not equal to <code>12,500,000</code>.</p> <h2 id="motivation">Motivation</h2> <p>Both Ethereum's Proof of Work and Proof of Stake designs assume that block producers are financially rational, but does not assume block producers to be benevolent. There is one exception however, and it is when block producers choose the gas limit of a block where it is assumed that block producers care about the long term health and decentralisation of the chain. Indeed, the block gas limit is one of the only parameters in Ethereum that is not dictated by node consensus, but instead is chosen by block producers. This decision was initially made to allow urgent changes in the block gas limit if necessary. Both drastically increasing or decreasing this parameter could have serious consequences that may not be desired. It is therefore a critical parameter that should require node consensus to avoid any sudden harmful change imposed by a small number of actors on the rest of the network.</p> <h2 id="specification">Specification</h2> <p>Refer to <code>gasLimit</code> as <code>gasTarget</code> post EIP-1559.</p> <h3 id="added-consensus-constraint">Added Consensus Constraint</h3> <p>As of <code>FORK_BLOCK_NUMBER</code>, the <code>header.gasLimit</code> <strong>MUST</strong> be equal to <code>BLOCK_GAS_LIMIT</code>, where <code>BLOCK_GAS_LIMIT</code> is a hardcoded constant set to <code>12,500,000</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="keeping-gaslimit-in-block-headers">Keeping gasLimit in Block Headers</h3> <p>While it would be possible to remove the <code>gasLimit</code> field from block headers, it would change the data structure to be hashed, which could lead to unintended consequences. It is therefore easier to leave the gasLimit as part of block headers.</p> <h3 id="chosen-gas-limit">Chosen Gas Limit</h3> <p>The <code>12,500,000</code> value is being proposed as it's the current block gas limit as of time of writing this EIP. The actual amount could be altered with a subsequent EIP to avoid deviating from the core intent of this EIP.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is backward compatible.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Rapid changes to the gas limit will likely be more difficult to execute, which could be problematic if an urgent situation arise that required changing the gas 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> 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-07T00:00:00+00:00 2026-02-11T14:49:27+00:00 Micah Zoltuhttps://github.com/MicahZoltu Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/3338/ <h2 id="abstract">Abstract</h2> <p>Limit account nonce to be between <code>0</code> and <code>2^52</code>.</p> <h2 id="motivation">Motivation</h2> <p>Account nonces are currently specified to be arbitrarily long unsigned integers. Dealing with arbitrary length data in the state witnesses is not optimal, therefore this EIP will allow proofs to represent the nonce in a more optimized way.</p> <p>Additionally it could prove beneficial to transaction formats, where some improvements are potentially sought by at least three other proposals.</p> <p>Lastly, this facilitates a minor optimisation in clients, because the nonce no longer needs to be kept as a 256-bit number.</p> <h2 id="specification">Specification</h2> <p>If <code>block.number &gt;= FORK_BLOCK</code> introduce two new restrictions:</p> <ol> <li>Consider any transaction invalid, where the nonce exceeds <code>2^52</code>.</li> <li>The <code>CREATE</code> instruction to abort with an exceptional halt, where the account nonce is <code>2^52</code>.</li> </ol> <h2 id="rationale">Rationale</h2> <ol> <li> <p>It is unlikely for any nonce to reach or exceed the proposed limit. If one would want to reach that limit via external transactions, it would cost at least <code>21000 * (2^64-1) = 387_381_625_547_900_583_915_000</code> gas.</p> </li> <li> <p>It must be noted that in the past, in the Morden testnet, each new account had a starting nonce of <code>2^20</code> in order to differentiate transactions from mainnet transactions. This mode of replay protection is out of fashion since <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> introduced a more elegant way using chain identifiers.</p> </li> <li> <p>Most clients already consider the nonce field to be 64-bit, such as go-ethereum.</p> </li> <li> <p>All integer values &lt;= 2^52 can be encoded in a 64-bit floating point without any loss of precision, making this value easy to work with in languages that only have floating point number support.</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>While this is a breaking change, no actual effect should be visible:</p> <ol> <li>There is no account in the state currently which would have a nonce exceeding that value. As of November 2020, the account <code>0xea674fdde714fd979de3edf0f56aa9716b898ec8</code> is responsible for the highest account nonce at approximately 29 million.</li> </ol> <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-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-05T00:00:00+00:00 2026-02-11T14:49:27+00:00 Justice Hudsonhttps://github.com/jchancehud https://wg-eips.ritovision.com/3332/ <h2 id="simple-summary">Simple Summary</h2> <p>An opcode for getting the median gas price of the parent block.</p> <h2 id="abstract">Abstract</h2> <p>Adds <code>MEDGASPRICE (0x46)</code> opcode that returns the median gas price for the parent block.</p> <h2 id="motivation">Motivation</h2> <p>With the emergence of rollups as core mechanisms in scaling Ethereum there are a number of common transactions that can be front-run. Optimistic rollups rely on the submission of fraud proofs to maintain the integrity of their systems. As a result actors submitting fraud proofs typically receive a financial reward for doing so. This opens a trivial front-running strategy of watching the mempool for fraud proof submissions and copying such transactions with a much higher gas price to reap the reward. Such front-runners do not perform validation independently and de-incentivize others from performing validation. Adding a mechanism enforcing an upper bound on gas prices for a transaction could be an effective defense against such front-running attacks.</p> <p>Consider a smart contract that wants to implement a first come first serve mechanism. Such a mechanism must defeat the inherently pay-to-win nature of the gas price market. Enforcing a maximum gas price for a transaction relies on the fact that transactions of the same gas price are generally processed in a first in first out way by Ethereum miners. A contract currently has few options for setting a max gas price:</p> <ul> <li>Set a constant value at a reasonable rate given the current gas prices</li> <li>Allow an individual or group of individuals to adjust a max gas price over time</li> </ul> <p>More elaborate schemes could likely be constructed but all would involve storing gas price information on chain increasing the number of transactions and costing Ether.</p> <p>Given a median gas price opcode a contract can set a maximum gas price as a function of the last blocks gas price. This can easily be implemented using a strategy such as the following:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// Assume that block.medgasprice is bound to MEDGASPRICE (0x46)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function submitFraudProof(bytes calldata proof) public {</span></span> <span class="giallo-l"><span> require(tx.gasprice &lt;= maxGasPrice());</span></span> <span class="giallo-l"><span> // process the fraud proof and provide a reward (if valid)</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function maxGasPrice() public view returns (uint) {</span></span> <span class="giallo-l"><span> return 3 * block.medgasprice;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Given the contract implementation above a client would simply call <code>maxGasPrice</code> to determine the gas price to use when submitting a fraud proof. This particular implementation allows up to 3x the median gas price of the last block to be used.</p> <h3 id="forwards-compatibility">Forwards Compatibility</h3> <p><a rel="external" href="https://eips.ethereum.org/EIPS/eip-1559">EIP-1559</a> plans to change the fee market in a number of ways. Most notably is the creation of a base fee that is burned. In this context an "inclusion fee" still exists as a part of the total fee. Consider the following two cases:</p> <h4 id="block-sizes-are-increasing-all-available-gas-is-being-consumed">Block sizes are increasing (all available gas is being consumed)</h4> <p>In this case there will be bidding contention in the inclusion fee to incentivize miners to include transactions. A median gas price operator would still be helpful as an attacker could supply a high inclusion fee to bump honest transactions.</p> <h4 id="block-sizes-are-decreasing-excess-gas-is-available">Block sizes are decreasing (excess gas is available)</h4> <p>In this case an attacker could specify a high inclusion fee to incentivize miners to include their transaction early in the block. Miners are incentivized to do so as including expensive transactions first reduces the risk of a revert (and partial refund) occurring.</p> <p>Given these two cases this EIP seems relevant in the context of EIP-1559.</p> <p>Post EIP-1559 <code>MEDGASPRICE (0x46)</code> should return the median <code>effective_gas_price</code> of the previous block.</p> <p><a rel="external" href="https://eips.ethereum.org/EIPS/eip-3198">EIP-3198</a> is required for the above strategies to be implemented. With the inclusion of <code>BASEFEE (0x48)</code> a contract can subtract the <code>base_fee_per_gas</code> from the <code>effective_gas_price</code> to determine the inclusion fee per gas being paid for the transaction and thus implement an upper bound.</p> <h2 id="specification">Specification</h2> <p>If <code>block.number &gt;= TBD</code>, add a new opcode <code>MEDGASPRICE (0x46)</code>:</p> <p>Pushes the median gas price of the parent block onto the stack.</p> <p>| Op | Input | Output | Cost | |:----: |:-----: |:------: |:----: | | 0x46 | 0 | 1 | 8 |</p> <h2 id="rationale">Rationale</h2> <p>Having access to the current gas price economy allows contracts to implement more robust and automated logic surrounding acceptable transaction gas prices.</p> <h3 id="naming-note">Naming note</h3> <p>The name <code>MEDGASPRICE</code> was chosen because the median gas price of the network can only be calculated from the latest complete block. Thus transactions being executed should expect the median gas price to be calculated from the previous block.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no known backwards incompabitility issues.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The strategy described for preventing front-running by setting an upper bound on the gas price of transactions has a few caveats:</p> <ol> <li>It relies on miners being impartial. Reordering transactions with the same gas price is a trivial means of defeating this strategy.</li> <li>The value returned by <code>MEDGASPRICE (0x46)</code> may fluctuate rapidly between blocks. If a transaction is not included immediately it may either fail (if the gas price drops) or become vulnerable to front-running (if the gas price increases).</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-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-19T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic Hugo De la cruzhttps://github.com/hugo-dc Paweł Bylicahttps://github.com/chfast https://wg-eips.ritovision.com/3855/

Introduce a new instruction which pushes the constant value 0 onto the stack

<h2 id="abstract">Abstract</h2> <p>Introduce the <code>PUSH0</code> (<code>0x5f</code>) instruction, which pushes the constant value 0 onto the stack.</p> <h2 id="motivation">Motivation</h2> <p>Many instructions expect offsets as inputs, which in a number of cases are zero. A good example is the return data parameters of <code>CALLs</code>, which are set to zeroes in case the contract prefers using <code>RETURNDATA*</code>. This is only one example, but there are many other reasons why a contract would need to push a zero value. They can achieve that today by <code>PUSH1 0</code>, which costs 3 gas at runtime, and is encoded as two bytes which means <code>2 * 200</code> gas deployment cost.</p> <p>Because of the overall cost many try to use various other instructions to achieve the same effect. Common examples include <code>PC</code>, <code>MSIZE</code>, <code>CALLDATASIZE</code>, <code>RETURNDATASIZE</code>, <code>CODESIZE</code>, <code>CALLVALUE</code>, and <code>SELFBALANCE</code>. Some of these cost only 2 gas and are a single byte long, but their value can depend on the context.</p> <p>We have conducted an analysis on Mainnet (block ranges 8,567,259…8,582,058 and 12,205,970…12,817,405), and ~11.5% of all the <code>PUSH*</code> instructions executed push a value of zero.</p> <p>The main motivations for this change include:</p> <ol> <li>Reducing contract code size.</li> <li>Reducing the risk of contracts (mis)using various instructions as an optimisation measure. Repricing/changing those instructions can be more risky.</li> <li>Reduce the need to use <code>DUP</code> instructions for duplicating zeroes.</li> </ol> <p>To put the "waste" into perspective, across existing accounts 340,557,331 bytes are wasted on <code>PUSH1 00</code> instructions, which means 68,111,466,200 gas was spent to deploy them. In practice a lot of these accounts share identical bytecode with others, so their total stored size in clients is lower, however the deploy time cost must have been paid nevertheless.</p> <p>An example for 2) is changing the behaviour of <code>RETURNDATASIZE</code> such that it may not be guaranteed to be zero at the beginning of the call frame.</p> <h2 id="specification">Specification</h2> <p>The instruction <code>PUSH0</code> is introduced at <code>0x5f</code>. It has no immediate data, pops no items from the stack, and places a single item with the value 0 onto the stack. The cost of this instruction is 2 gas (aka <code>base</code>).</p> <h2 id="rationale">Rationale</h2> <h3 id="gas-cost">Gas cost</h3> <p>The <code>base</code> gas cost is used for instructions which place constant values onto the stack, such as <code>ADDRESS</code>, <code>ORIGIN</code>, and so forth.</p> <h3 id="opcode">Opcode</h3> <p><code>0x5f</code> means it is in a "contiguous" space with the rest of the <code>PUSH</code> implementations and potentially could share the implementation.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces a new opcode which did not exist previously. Already deployed contracts using this opcode could change their behaviour after this EIP.</p> <h2 id="test-cases">Test Cases</h2> <ul> <li><code>5F</code> -- successful execution, stack consist of a single item, set to zero</li> <li><code>5F5F..5F</code> (1024 times) -- successful execution, stack consists of 1024 items, all set to zero</li> <li><code>5F5F..5F</code> (1025 times) -- execution aborts due to out of stack</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>The authors are not aware of any impact on security. Note that jumpdest-analysis is unaffected, as <code>PUSH0</code> has no immediate data 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> 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-02-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic Paul Dworzanskihttps://github.com/poemm Jared Wasingerhttps://github.com/jwasinger Casey Detriohttps://github.com/cdetrio Pawel Bylicahttps://github.com/chfast Charles Cooperhttps://github.com/charles-cooper https://wg-eips.ritovision.com/5656/

An efficient EVM instruction for copying memory areas

<h2 id="abstract">Abstract</h2> <p>Provide an efficient EVM instruction for copying memory areas.</p> <h2 id="motivation">Motivation</h2> <p>Memory copying is a basic operation, yet implementing it on the EVM comes with overhead.</p> <p>This was recognised and alleviated early on with the introduction of the "identity" precompile, which accomplishes memory copying by the use of <code>CALL</code>'s input and output memory offsets. Its cost is <code>15 + 3 * (length / 32)</code> gas, plus the call overhead. The identity precompile was rendered ineffective by the raise of the cost of <code>CALL</code> to 700, but subsequently the reduction by <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a> made it slightly more economical.</p> <p>Copying exact words can be accomplished with <code>&lt;offset&gt; MLOAD &lt;offset&gt; MSTORE</code> or <code>&lt;offset&gt; DUP1 MLOAD DUP2 MSTORE</code>, at a cost of at least 12 gas per word. This is fairly efficient if the offsets are known upfront and the copying can be unrolled. In case copying is implemented at runtime with arbitrary starting offsets, besides the control flow overhead, the offset will need to be incremented using <code>32 ADD</code>, adding at least 6 gas per word.</p> <p>Copying non-exact words is more tricky, as for the last partial word, both the source and destination needs to be loaded, masked, or'd, and stored again. This overhead is significant. One edge case is if the last "partial word" is a single byte, it can be efficiently stored using <code>MSTORE8</code>.</p> <p>As example use case, copying 256 bytes costs:</p> <ul> <li>at least 757 gas pre-EIP-2929 using the identity precompile</li> <li>at least 157 gas post-EIP-2929 using the identity precompile</li> <li>at least 96 gas using unrolled <code>MLOAD</code>/<code>MSTORE</code> instructions</li> <li>27 gas using this EIP</li> </ul> <p>According to an analysis of blocks 10537502 to 10538702, roughly 10.5% of memory copies would have had improved performance with the availability of an <code>MCOPY</code> instruction.</p> <p>Memory copying is used by languages like Solidity and Vyper, where we expect this improvement to provide efficient means of building data structures, including efficient sliced access and copies of memory objects. Having a dedicated <code>MCOPY</code> instruction would also add forward protection against future gas cost changes to <code>CALL</code> instructions in general.</p> <p>Having a special <code>MCOPY</code> instruction makes the job of static analyzers and optimizers easier, since the effects of a <code>CALL</code> in general have to be fenced, whereas an <code>MCOPY</code> instruction would be known to only have memory effects. Even if special cases are added for precompiles, a future hard fork could change <code>CALL</code> effects, and so any analysis of code using the identity precompile would only be valid for a certain range of blocks.</p> <p>Finally, we expect memory copying to be immensely useful for various computationally heavy operations, such as EVM384, where it is identified as a significant overhead.</p> <h2 id="specification">Specification</h2> <p>The instruction <code>MCOPY</code> is introduced at <code>0x5E</code>.</p> <h3 id="input-stack">Input stack</h3> <table><thead><tr><th>Stack</th><th>Value</th></tr></thead><tbody> <tr><td>top - 0</td><td><code>dst</code></td></tr> <tr><td>top - 1</td><td><code>src</code></td></tr> <tr><td>top - 2</td><td><code>length</code></td></tr> </tbody></table> <p>This ordering matches the other copying instructions, i.e. <code>CALLDATACOPY</code>, <code>RETURNDATACOPY</code>.</p> <h3 id="gas-costs">Gas costs</h3> <p>Per yellow paper terminology, it should be considered part of the <code>W_copy</code> group of opcodes, and follow the gas calculation for <code>W_copy</code> in the yellow paper. While the calculation in the yellow paper should be considered the final word, for reference, as of time of this writing, that currently means its gas cost is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>words_copied = (length + 31) // 32</span></span> <span class="giallo-l"><span>g_verylow = 3</span></span> <span class="giallo-l"><span>g_copy = 3 * words_copied + memory_expansion_cost</span></span> <span class="giallo-l"><span>gas_cost = g_verylow + g_copy</span></span></code></pre><h3 id="output-stack">Output stack</h3> <p>This instruction returns no stack items.</p> <h3 id="semantics">Semantics</h3> <p>It copies <code>length</code> bytes from the offset pointed at <code>src</code> to the offset pointed at <code>dst</code> in memory. Copying takes place as if an intermediate buffer was used, allowing the destination and source to overlap.</p> <p>If <code>length &gt; 0</code> and (<code>src + length</code> or <code>dst + length</code>) is beyond the current memory length, the memory is extended with respective gas cost applied.</p> <p>The gas cost of this instruction mirrors that of other <code>Wcopy</code> instructions and is <code>Gverylow + Gcopy * ceil(length / 32)</code>.</p> <h2 id="rationale">Rationale</h2> <p>Production implementation of exact-word memory copying and partial-word memory copying can be found in the Solidity, Vyper and Fe compilers.</p> <p>With <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a> the call overhead using the identity precompile was reduced from 700 to 100 gas. This is still prohibitive for making the precompile a reasonable alternative again.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces a new instruction which did not exist previously. Already deployed contracts using this instruction could change their behaviour after this EIP.</p> <h2 id="test-cases">Test Cases</h2> <p><code>MCOPY 0 32 32</code> - copy 32 bytes from offset 32 to offset 0.</p> <p>pre (spaces included for readability):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000000 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f</span></span></code></pre> <p>post:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f</span></span></code></pre> <p>gas used: 6</p> <p><code>MCOPY 0 0 32</code> - copy 32 bytes from offset 0 to offset 0.</p> <p>pre:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0101010101010101010101010101010101010101010101010101010101010101</span></span></code></pre> <p>post:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0101010101010101010101010101010101010101010101010101010101010101</span></span></code></pre> <p>gas used: 6</p> <p><code>MCOPY 0 1 8</code> - copy 8 bytes from offset 1 to offset 0 (overlapping).</p> <p>pre (space at byte 8):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0001020304050607 080000000000000000000000000000000000000000000000</span></span></code></pre> <p>post:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0102030405060708 080000000000000000000000000000000000000000000000</span></span></code></pre> <p>gas used: 6</p> <p><code>MCOPY 1 0 8</code> - copy 8 bytes from offset 0 to offset 1 (overlapping).</p> <p>pre (space at byte 8):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0001020304050607 080000000000000000000000000000000000000000000000</span></span></code></pre> <p>post:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0000010203040506 070000000000000000000000000000000000000000000000</span></span></code></pre> <p>gas used: 6</p> <h3 id="full-test-suite">Full test suite</h3> <p>A full suite of tests can be found in the execution spec tests: <a rel="external" href="https://github.com/ethereum/execution-spec-tests/tree/c0065176a79f89d93f4c326186fc257ec5b8d5f1/tests/cancun/eip5656_mcopy">MCOPY suite</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Clients should take care that their implementation does not use an intermediate buffer (see for instance that the C stdlib <code>memmove</code> function does not use an intermediate buffer), as this is a potential Denial of Service (DoS) vector. Most language builtins / standard library functions for moving bytes have the correct performance characteristics here.</p> <p>This aside, the analysis for Denial of Service (DoS) and memory exhaustion attacks is identical to other opcodes which touch memory, as the memory expansion follows the same pricing rules.</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-29T00:00:00+00:00 2026-02-11T14:49:27+00:00 Mark Mackeyhttps://github.com/ethDreamer https://wg-eips.ritovision.com/4881/

Establishing the format and endpoint for transmitting a snapshot of the deposit Merkle tree

<h2 id="abstract">Abstract</h2> <p>This EIP defines a standard format for transmitting the deposit contract Merkle tree in a compressed form during weak subjectivity sync. This allows newly syncing consensus clients to reconstruct the deposit tree much faster than downloading all historical deposits. The format proposed also allows clients to prune deposits that are no longer needed to participate fully in consensus (see <a href="https://wg-eips.ritovision.com/4881/#deposit-finalization-flow">Deposit Finalization Flow</a>).</p> <h2 id="motivation">Motivation</h2> <p>To reconstruct the deposit Merkle tree, most client implementations require beacon nodes to download and store every deposit log since the launch of the deposit contract. However, this approach requires beacon nodes to store far more deposits than necessary to participate in consensus. Additionally, this leads to increased sync times for new nodes, which is particularly evident during weak subjectivity sync. This simplistic approach also prevents historical contract logs from being pruned from full nodes, a prospect frequently discussed in the context of limiting state growth.</p> <h2 id="specification">Specification</h2> <p>Consensus clients MAY continue to implement the deposit Merkle tree however they choose. However, when transmitting the tree to newly syncing nodes, clients MUST use the following format:</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"> DepositTreeSnapshot</span><span>:</span></span> <span class="giallo-l"><span> finalized</span><span>:</span><span> List</span><span>[</span><span>Hash32</span><span>,</span><span class="z-constant"> DEPOSIT_CONTRACT_DEPTH</span><span>]</span></span> <span class="giallo-l"><span> deposit_root</span><span>:</span><span> Hash32</span></span> <span class="giallo-l"><span> deposit_count</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> execution_block_hash</span><span>:</span><span> Hash32</span></span> <span class="giallo-l"><span> execution_block_height</span><span>:</span><span> uint64</span></span></code></pre> <p>Where <code>finalized</code> is a variable-length list (of maximum size <code>DEPOSIT_CONTRACT_DEPTH</code>) containing the hashes defined in the <a href="https://wg-eips.ritovision.com/4881/#deposit-finalization-flow">Deposit Finalization Flow</a> section below. The fields <code>deposit_root</code>, <code>deposit_count</code>, and <code>execution_block_hash</code> store the same information as the <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/2b45496fe48fa75450ad29a05bdd48866f86528a/specs/phase0/beacon-chain.md#eth1data"><code>Eth1Data</code></a> object that corresponds to the snapshot, and <code>execution_block_height</code> is the height of the execution block with hash <code>execution_block_hash</code>. Consensus clients MUST make this structure available via the Beacon Node API endpoint:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/eth/v1/beacon/deposit_snapshot</span></span></code></pre><h3 id="deposit-finalization-flow">Deposit Finalization Flow</h3> <p>During deposit processing, the beacon chain requires deposits to be submitted along with a Merkle path to the deposit root. This is required exactly once for each deposit. When a deposit has been processed by the beacon chain and the <a href="https://wg-eips.ritovision.com/4881/#deposit-finalization-conditions">deposit finalization conditions</a> have been met, many of the hashes along the path to the deposit root will never be required again to construct Merkle proofs on chain. These unnecessary hashes MAY be pruned to save space. The image below illustrates the evolution of the deposit Merkle tree under this process alongside the corresponding <code>DepositTreeSnapshot</code> as new deposits are added and older deposits become finalized:</p> <p><img src="https://wg-eips.ritovision.com/4881/./assets/deposit_tree_evolution.svg" alt="deposit tree evolution" /></p> <h2 id="rationale">Rationale</h2> <p>The format in this specification was chosen to achieve several goals simultaneously:</p> <ol> <li>Enable reconstruction of the deposit contract Merkle tree without requiring full nodes to store all historical contract logs</li> <li>Avoid requiring consensus nodes to retain more deposits than necessary to fully participate in consensus</li> <li>Simplicity of implementation (see <a href="https://wg-eips.ritovision.com/4881/#reference-implementation">Reference Implementation</a> section)</li> <li>Increase speed of weak subjectivity sync</li> <li>Compatibility with existing implementations of this mechanism (see discussion)</li> </ol> <p>The proposed <code>DepositTreeSnapshot</code> structure includes both <code>execution_block_hash</code> and <code>execution_block_height</code> for convenience to consensus node implementors. While only one of these fields is strictly necessary, different clients may have already designed their block cache logic around one or the other. Sending only one of these would force some consensus clients to query the execution engine for the other information, but as this is happening in the context of a newly syncing consensus node, it is very likely that the execution engine will not be synced, especially post-merge. The <code>deposit_root</code> field is also not strictly necessary, but by including it, newly syncing consensus nodes can cheaply validate any received snapshot against itself (see the <code>calculate_root()</code> method in the <a href="https://wg-eips.ritovision.com/4881/#reference-implementation">Reference Implementation</a>).</p> <h3 id="why-not-reconstruct-the-tree-directly-from-the-deposit-contract">Why not Reconstruct the Tree Directly from the Deposit Contract?</h3> <p>The deposit contract can only provide the tree at the head of the chain. Because the beacon chain's view of the deposit contract lags behind the execution chain by <code>ETH1_FOLLOW_DISTANCE</code>, there are almost always deposits which haven't yet been included in the chain that need proofs constructed from an earlier version of the tree than exists at the head.</p> <h3 id="why-not-reconstruct-the-tree-from-a-deposit-in-the-beacon-chain">Why not Reconstruct the Tree from a Deposit in the Beacon Chain?</h3> <p>In principle, a node could scan backwards through the chain starting from the weak subjectivity checkpoint to locate a suitable <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/2b45496fe48fa75450ad29a05bdd48866f86528a/specs/phase0/beacon-chain.md#deposit"><code>Deposit</code></a>, and then extract the rightmost branch of the tree from that. The node would also need to extract the <code>execution_block_hash</code> from which to start syncing new deposits from the <code>Eth1Data</code> in the corresponding <code>BeaconState</code>. This approach is less desirable for a few reasons:</p> <ul> <li>More difficult to implement due to the edge cases involved in finding a suitable deposit to anchor to (the rightmost branch of the latest not-yet-included deposit is required)</li> <li>This would make backfilling beacon blocks a requirement for reconstructing the deposit tree and therefore a requirement for block production</li> <li>This is inherently slower than getting this information from the weak subjectivity checkpoint</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backwards compatible.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases are included in <a href="https://wg-eips.ritovision.com/4881/./assets/test_cases.yaml">test_cases.yaml</a>. Each case is structured as follows:</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"> DepositTestCase</span><span>:</span></span> <span class="giallo-l"><span> deposit_data</span><span>:</span><span> DepositData</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> These are all the inputs to the deposit contract&#39;s deposit() function</span></span> <span class="giallo-l"><span> deposit_data_root</span><span>:</span><span> Hash32</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> The tree hash root of this deposit (calculated for convenience)</span></span> <span class="giallo-l"><span> eth1_data</span><span>:</span><span> Eth1Data</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> An Eth1Data object that can be used to finalize the tree after pushing this deposit</span></span> <span class="giallo-l"><span> block_height</span><span>:</span><span> uint64</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> The height of the execution block with this Eth1Data</span></span> <span class="giallo-l"><span> snapshot</span><span>:</span><span> DepositTreeSnapshot</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> The resulting DepositTreeSnapshot object if the tree were finalized after this deposit</span></span></code></pre> <p>This EIP also includes other files for testing:</p> <ul> <li><a href="https://wg-eips.ritovision.com/4881/./assets/deposit_snapshot.py">deposit_snapshot.py</a> contains the same code as the <a href="https://wg-eips.ritovision.com/4881/#reference-implementation">Reference Implementation</a></li> <li><a href="https://wg-eips.ritovision.com/4881/./assets/eip_4881.py">eip_4881.py</a> contains boilerplate declarations</li> <li><a href="https://wg-eips.ritovision.com/4881/./assets/test_deposit_snapshot.py">test_deposit_snapshot.py</a> includes code for running test cases against the reference implementation</li> </ul> <p>If these files are downloaded to the same directory, the test cases can be run by executing <code>pytest</code> in that directory.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>This implementation lacks full error checking and is optimized for readability over efficiency. If <code>tree</code> is a <code>DepositTree</code>, then the <code>DepositTreeSnapshot</code> can be obtained by calling <code>tree.get_snapshot()</code> and a new instance of the tree can be recovered from the snapshot by calling <code>DepositTree.from_snapshot()</code>. See the <a href="https://wg-eips.ritovision.com/4881/#deposit-finalization-conditions">Deposit Finalization Conditions</a> section for discussion on when the tree can be pruned by calling <code>tree.finalize()</code>.</p> <p>Generating proofs for deposits against an earlier version of the tree is relatively fast in this implementation; just create a copy of the finalized tree with <code>copy = DepositTree.from_snapshot(tree.get_snapshot())</code> and then append the remaining deposits to the desired count with <code>copy.push_leaf(deposit)</code>. Proofs can then be obtained with <code>copy.get_proof(index)</code>.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">from</span><span class="z-support z-variable"> __future__</span><span class="z-keyword"> import</span><span> annotations</span></span> <span class="giallo-l"><span class="z-keyword">from</span><span> typing</span><span class="z-keyword"> import</span><span> List</span><span>,</span><span> Optional</span><span>,</span><span> Tuple</span></span> <span class="giallo-l"><span class="z-keyword">from</span><span> dataclasses</span><span class="z-keyword"> import</span><span> dataclass</span></span> <span class="giallo-l"><span class="z-keyword">from</span><span> abc</span><span class="z-keyword"> import</span><span class="z-constant"> ABC</span><span>,</span><span>abstractmethod</span></span> <span class="giallo-l"><span class="z-keyword">from</span><span> eip_4881</span><span class="z-keyword"> import</span><span class="z-constant"> DEPOSIT_CONTRACT_DEPTH</span><span>,</span><span>Hash32</span><span>,</span><span>sha256</span><span>,</span><span>to_le_bytes</span><span>,</span><span>zerohashes</span></span> <span class="giallo-l"></span> <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"> DepositTreeSnapshot</span><span>:</span></span> <span class="giallo-l"><span> finalized</span><span>:</span><span> List</span><span>[</span><span>Hash32</span><span>,</span><span class="z-constant"> DEPOSIT_CONTRACT_DEPTH</span><span>]</span></span> <span class="giallo-l"><span> deposit_root</span><span>:</span><span> Hash32</span></span> <span class="giallo-l"><span> deposit_count</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span> execution_block_hash</span><span>:</span><span> Hash32</span></span> <span class="giallo-l"><span> execution_block_height</span><span>:</span><span> uint64</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"> calculate_root</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>)</span><span> -&gt;</span><span> Hash32</span><span>:</span></span> <span class="giallo-l"><span> size</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>deposit_count</span></span> <span class="giallo-l"><span> index</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>finalized</span><span>)</span></span> <span class="giallo-l"><span> root</span><span class="z-keyword"> =</span><span> zerohashes</span><span>[</span><span class="z-constant">0</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> level</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> DEPOSIT_CONTRACT_DEPTH</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>size</span><span class="z-keyword"> &amp;</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 1</span><span>:</span></span> <span class="giallo-l"><span> index</span><span class="z-keyword"> -=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> root</span><span class="z-keyword"> =</span><span> sha256</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>finalized</span><span>[</span><span>index</span><span>]</span><span class="z-keyword"> +</span><span> root</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> root</span><span class="z-keyword"> =</span><span> sha256</span><span>(</span><span>root</span><span class="z-keyword"> +</span><span> zerohashes</span><span>[</span><span>level</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> size</span><span class="z-keyword"> &gt;&gt;=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> sha256</span><span>(</span><span>root</span><span class="z-keyword"> +</span><span> to_le_bytes</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>deposit_count</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> from_tree_parts</span><span>(</span><span class="z-variable z-parameter z-function">finalized</span><span>:</span><span> List</span><span>[</span><span>Hash32</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> deposit_count</span><span>:</span><span> uint64</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> execution_block</span><span>:</span><span> Tuple</span><span>[</span><span>Hash32</span><span>,</span><span> uint64</span><span>]</span><span>)</span><span> -&gt;</span><span> DepositTreeSnapshot</span><span>:</span></span> <span class="giallo-l"><span> snapshot</span><span class="z-keyword"> =</span><span> DepositTreeSnapshot</span><span>(</span></span> <span class="giallo-l"><span> finalized</span><span>,</span><span> zerohashes</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span> deposit_count</span><span>,</span><span> execution_block</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span> execution_block</span><span>[</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"> A real implementation should store the deposit_root from the eth1_data passed to</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> DepositTree.finalize() instead of relying on calculate_root() here. This allows</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> the snapshot to be validated using calculate_root().</span></span> <span class="giallo-l"><span> snapshot</span><span>.</span><span>deposit_root</span><span class="z-keyword"> =</span><span> snapshot</span><span>.</span><span>calculate_root</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> snapshot</span></span> <span class="giallo-l"></span> <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"> DepositTree</span><span>:</span></span> <span class="giallo-l"><span> tree</span><span>:</span><span> MerkleTree</span></span> <span class="giallo-l"><span> mix_in_length</span><span>:</span><span> uint</span></span> <span class="giallo-l"><span> finalized_execution_block</span><span>:</span><span> Optional</span><span>[</span><span>Tuple</span><span>[</span><span>Hash32</span><span>,</span><span> uint64</span><span>]</span><span>]</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> new</span><span>(</span><span>)</span><span> -&gt;</span><span> DepositTree</span><span>:</span></span> <span class="giallo-l"><span> merkle</span><span class="z-keyword"> =</span><span> MerkleTree</span><span>.</span><span>create</span><span>(</span><span>[</span><span>]</span><span>,</span><span class="z-constant"> DEPOSIT_CONTRACT_DEPTH</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> DepositTree</span><span>(</span><span>merkle</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> None</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> get_snapshot</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>)</span><span> -&gt;</span><span> DepositTreeSnapshot</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>finalized_execution_block</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> finalized</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> deposit_count</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>tree</span><span>.</span><span>get_finalized</span><span>(</span><span>finalized</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> DepositTreeSnapshot</span><span>.</span><span>from_tree_parts</span><span>(</span></span> <span class="giallo-l"><span> finalized</span><span>,</span><span> deposit_count</span><span>,</span><span class="z-variable z-language"> self</span><span>.</span><span>finalized_execution_block</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> from_snapshot</span><span>(</span><span class="z-variable z-parameter z-function">snapshot</span><span>:</span><span> DepositTreeSnapshot</span><span>)</span><span> -&gt;</span><span> DepositTree</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> decent validation check on the snapshot</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span>snapshot</span><span>.</span><span>deposit_root</span><span class="z-keyword"> ==</span><span> snapshot</span><span>.</span><span>calculate_root</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> finalized_execution_block</span><span class="z-keyword"> =</span><span> (</span><span>snapshot</span><span>.</span><span>execution_block_hash</span><span>,</span><span> snapshot</span><span>.</span><span>execution_block_height</span><span>)</span></span> <span class="giallo-l"><span> tree</span><span class="z-keyword"> =</span><span> MerkleTree</span><span>.</span><span>from_snapshot_parts</span><span>(</span></span> <span class="giallo-l"><span> snapshot</span><span>.</span><span>finalized</span><span>,</span><span> snapshot</span><span>.</span><span>deposit_count</span><span>,</span><span class="z-constant"> DEPOSIT_CONTRACT_DEPTH</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> DepositTree</span><span>(</span><span>tree</span><span>,</span><span> snapshot</span><span>.</span><span>deposit_count</span><span>,</span><span> finalized_execution_block</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> finalize</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> eth1_data</span><span>:</span><span> Eth1Data</span><span>,</span><span class="z-variable z-parameter z-function"> execution_block_height</span><span>:</span><span> uint64</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>finalized_execution_block</span><span class="z-keyword"> =</span><span> (</span><span>eth1_data</span><span>.</span><span>block_hash</span><span>,</span><span> execution_block_height</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>tree</span><span>.</span><span>finalize</span><span>(</span><span>eth1_data</span><span>.</span><span>deposit_count</span><span>,</span><span class="z-constant"> DEPOSIT_CONTRACT_DEPTH</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> get_proof</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> index</span><span>:</span><span> uint</span><span>)</span><span> -&gt;</span><span> Tuple</span><span>[</span><span>Hash32</span><span>,</span><span> List</span><span>[</span><span>Hash32</span><span>]</span><span>]</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>mix_in_length</span><span class="z-keyword"> &gt;</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"> ensure index &gt; finalized deposit index</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span>index</span><span class="z-keyword"> &gt;</span><span class="z-variable z-language"> self</span><span>.</span><span>tree</span><span>.</span><span>get_finalized</span><span>(</span><span>[</span><span>]</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span></span> <span class="giallo-l"><span> leaf</span><span>,</span><span> proof</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>tree</span><span>.</span><span>generate_proof</span><span>(</span><span>index</span><span>,</span><span class="z-constant"> DEPOSIT_CONTRACT_DEPTH</span><span>)</span></span> <span class="giallo-l"><span> proof</span><span>.</span><span>append</span><span>(</span><span>to_le_bytes</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>mix_in_length</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> leaf</span><span>,</span><span> proof</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> get_root</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>)</span><span> -&gt;</span><span> Hash32</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> sha256</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>tree</span><span>.</span><span>get_root</span><span>(</span><span>)</span><span class="z-keyword"> +</span><span> to_le_bytes</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>mix_in_length</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> push_leaf</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> leaf</span><span>:</span><span> Hash32</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>mix_in_length</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>tree</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>tree</span><span>.</span><span>push_leaf</span><span>(</span><span>leaf</span><span>,</span><span class="z-constant"> DEPOSIT_CONTRACT_DEPTH</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"> MerkleTree</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-entity z-name"> @</span><span class="z-entity z-name">abstractmethod</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> get_root</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>)</span><span> -&gt;</span><span> Hash32</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> pass</span></span> <span class="giallo-l"><span class="z-entity z-name"> @</span><span class="z-entity z-name">abstractmethod</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> is_full</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>)</span><span> -&gt;</span><span class="z-support"> bool</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> pass</span></span> <span class="giallo-l"><span class="z-entity z-name"> @</span><span class="z-entity z-name">abstractmethod</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> push_leaf</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> leaf</span><span>:</span><span> Hash32</span><span>,</span><span class="z-variable z-parameter z-function"> level</span><span>:</span><span> uint</span><span>)</span><span> -&gt;</span><span> MerkleTree</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> pass</span></span> <span class="giallo-l"><span class="z-entity z-name"> @</span><span class="z-entity z-name">abstractmethod</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> finalize</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> deposits_to_finalize</span><span>:</span><span> uint</span><span>,</span><span class="z-variable z-parameter z-function"> level</span><span>:</span><span> uint</span><span>)</span><span> -&gt;</span><span> MerkleTree</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> pass</span></span> <span class="giallo-l"><span class="z-entity z-name"> @</span><span class="z-entity z-name">abstractmethod</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> get_finalized</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> result</span><span>:</span><span> List</span><span>[</span><span>Hash32</span><span>]</span><span>)</span><span> -&gt;</span><span> uint</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> returns the number of finalized deposits in the tree</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> while populating result with the finalized hashes</span></span> <span class="giallo-l"><span class="z-keyword"> pass</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> create</span><span>(</span><span class="z-variable z-parameter z-function">leaves</span><span>:</span><span> List</span><span>[</span><span>Hash32</span><span>]</span><span>,</span><span class="z-variable z-parameter z-function"> depth</span><span>:</span><span> uint</span><span>)</span><span> -&gt;</span><span> MerkleTree</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span>(</span><span>leaves</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> Zero</span><span>(</span><span>depth</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span>(</span><span>depth</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> Leaf</span><span>(</span><span>leaves</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> split</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span class="z-constant">2</span><span class="z-keyword">**</span><span>(</span><span>depth</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span>,</span><span class="z-support"> len</span><span>(</span><span>leaves</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> left</span><span class="z-keyword"> =</span><span> MerkleTree</span><span>.</span><span>create</span><span>(</span><span>leaves</span><span>[</span><span class="z-constant">0</span><span>:</span><span>split</span><span>]</span><span>,</span><span> depth</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span></span> <span class="giallo-l"><span> right</span><span class="z-keyword"> =</span><span> MerkleTree</span><span>.</span><span>create</span><span>(</span><span>leaves</span><span>[</span><span>split</span><span>:</span><span>]</span><span>,</span><span> depth</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> Node</span><span>(</span><span>left</span><span>,</span><span> right</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> from_snapshot_parts</span><span>(</span><span class="z-variable z-parameter z-function">finalized</span><span>:</span><span> List</span><span>[</span><span>Hash32</span><span>]</span><span>,</span><span class="z-variable z-parameter z-function"> deposits</span><span>:</span><span> uint</span><span>,</span><span class="z-variable z-parameter z-function"> level</span><span>:</span><span> uint</span><span>)</span><span> -&gt;</span><span> MerkleTree</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span>(</span><span>finalized</span><span>)</span><span class="z-keyword"> or</span><span class="z-keyword"> not</span><span>(</span><span>deposits</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> empty tree</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> Zero</span><span>(</span><span>level</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> deposits</span><span class="z-keyword"> ==</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span>level</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> Finalized</span><span>(</span><span>deposits</span><span>,</span><span> finalized</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> left_subtree</span><span class="z-keyword"> =</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span>(</span><span>level</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> deposits</span><span class="z-keyword"> &lt;=</span><span> left_subtree</span><span>:</span></span> <span class="giallo-l"><span> left</span><span class="z-keyword"> =</span><span> MerkleTree</span><span>.</span><span>from_snapshot_parts</span><span>(</span><span>finalized</span><span>,</span><span> deposits</span><span>,</span><span> level</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span></span> <span class="giallo-l"><span> right</span><span class="z-keyword"> =</span><span> Zero</span><span>(</span><span>level</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> Node</span><span>(</span><span>left</span><span>,</span><span> right</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> left</span><span class="z-keyword"> =</span><span> Finalized</span><span>(</span><span>left_subtree</span><span>,</span><span> finalized</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> right</span><span class="z-keyword"> =</span><span> MerkleTree</span><span>.</span><span>from_snapshot_parts</span><span>(</span><span>finalized</span><span>[</span><span class="z-constant">1</span><span>:</span><span>]</span><span>,</span><span> deposits</span><span class="z-keyword"> -</span><span> left_subtree</span><span>,</span><span> level</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> Node</span><span>(</span><span>left</span><span>,</span><span> right</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> generate_proof</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> index</span><span>:</span><span> uint</span><span>,</span><span class="z-variable z-parameter z-function"> depth</span><span>:</span><span> uint</span><span>)</span><span> -&gt;</span><span> Tuple</span><span>[</span><span>Hash32</span><span>,</span><span> List</span><span>[</span><span>Hash32</span><span>]</span><span>]</span><span>:</span></span> <span class="giallo-l"><span> proof</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> node</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> depth</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> ith_bit</span><span class="z-keyword"> =</span><span> (</span><span>index</span><span class="z-keyword"> &gt;&gt;</span><span> (</span><span>depth</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span>)</span><span class="z-keyword"> &amp;</span><span class="z-storage z-type"> 0x</span><span class="z-constant">1</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> ith_bit</span><span class="z-keyword"> ==</span><span class="z-constant"> 1</span><span>:</span></span> <span class="giallo-l"><span> proof</span><span>.</span><span>append</span><span>(</span><span>node</span><span>.</span><span>left</span><span>.</span><span>get_root</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> node</span><span class="z-keyword"> =</span><span> node</span><span>.</span><span>right</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> proof</span><span>.</span><span>append</span><span>(</span><span>node</span><span>.</span><span>right</span><span>.</span><span>get_root</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> node</span><span class="z-keyword"> =</span><span> node</span><span>.</span><span>left</span></span> <span class="giallo-l"><span> depth</span><span class="z-keyword"> -=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> proof</span><span>.</span><span>reverse</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> node</span><span>.</span><span>get_root</span><span>(</span><span>)</span><span>,</span><span> proof</span></span> <span class="giallo-l"></span> <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"> Finalized</span><span>(</span><span class="z-entity">MerkleTree</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> deposit_count</span><span>:</span><span> uint</span></span> <span class="giallo-l"><span class="z-support"> hash</span><span>:</span><span> Hash32</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> get_root</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>)</span><span> -&gt;</span><span> Hash32</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>hash</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> is_full</span><span>(</span><span class="z-variable z-parameter z-function">self</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 class="z-constant"> True</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> finalize</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> deposits_to_finalize</span><span>:</span><span> uint</span><span>,</span><span class="z-variable z-parameter z-function"> level</span><span>:</span><span> uint</span><span>)</span><span> -&gt;</span><span> MerkleTree</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> self</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> get_finalized</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> result</span><span>:</span><span> List</span><span>[</span><span>Hash32</span><span>]</span><span>)</span><span> -&gt;</span><span> uint</span><span>:</span></span> <span class="giallo-l"><span> result</span><span>.</span><span>append</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>hash</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>deposit_count</span></span> <span class="giallo-l"></span> <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"> Leaf</span><span>(</span><span class="z-entity">MerkleTree</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-support"> hash</span><span>:</span><span> Hash32</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> get_root</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>)</span><span> -&gt;</span><span> Hash32</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>hash</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> is_full</span><span>(</span><span class="z-variable z-parameter z-function">self</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 class="z-constant"> True</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> finalize</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> deposits_to_finalize</span><span>:</span><span> uint</span><span>,</span><span class="z-variable z-parameter z-function"> level</span><span>:</span><span> uint</span><span>)</span><span> -&gt;</span><span> MerkleTree</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> Finalized</span><span>(</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-language"> self</span><span>.</span><span>hash</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> get_finalized</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> result</span><span>:</span><span> List</span><span>[</span><span>Hash32</span><span>]</span><span>)</span><span> -&gt;</span><span> uint</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-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"> Node</span><span>(</span><span class="z-entity">MerkleTree</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> left</span><span>:</span><span> MerkleTree</span></span> <span class="giallo-l"><span> right</span><span>:</span><span> MerkleTree</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> get_root</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>)</span><span> -&gt;</span><span> Hash32</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> sha256</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>left</span><span>.</span><span>get_root</span><span>(</span><span>)</span><span class="z-keyword"> +</span><span class="z-variable z-language"> self</span><span>.</span><span>right</span><span>.</span><span>get_root</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> is_full</span><span>(</span><span class="z-variable z-parameter z-function">self</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 class="z-variable z-language"> self</span><span>.</span><span>right</span><span>.</span><span>is_full</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> push_leaf</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> leaf</span><span>:</span><span> Hash32</span><span>,</span><span class="z-variable z-parameter z-function"> level</span><span>:</span><span> uint</span><span>)</span><span> -&gt;</span><span> MerkleTree</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>left</span><span>.</span><span>is_full</span><span>(</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>left</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>left</span><span>.</span><span>push_leaf</span><span>(</span><span>leaf</span><span>,</span><span> level</span><span class="z-keyword"> -</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 class="z-variable z-language"> self</span><span>.</span><span>right</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>right</span><span>.</span><span>push_leaf</span><span>(</span><span>leaf</span><span>,</span><span> level</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-variable z-language"> self</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> finalize</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> deposits_to_finalize</span><span>:</span><span> uint</span><span>,</span><span class="z-variable z-parameter z-function"> level</span><span>:</span><span> uint</span><span>)</span><span> -&gt;</span><span> MerkleTree</span><span>:</span></span> <span class="giallo-l"><span> deposits</span><span class="z-keyword"> =</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span>level</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> deposits</span><span class="z-keyword"> &lt;=</span><span> deposits_to_finalize</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> Finalized</span><span>(</span><span>deposits</span><span>,</span><span class="z-variable z-language"> self</span><span>.</span><span>get_root</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>left</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>left</span><span>.</span><span>finalize</span><span>(</span><span>deposits_to_finalize</span><span>,</span><span> level</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> deposits_to_finalize</span><span class="z-keyword"> &gt;</span><span> deposits</span><span class="z-keyword"> /</span><span class="z-constant"> 2</span><span>:</span></span> <span class="giallo-l"><span> remaining</span><span class="z-keyword"> =</span><span> deposits_to_finalize</span><span class="z-keyword"> -</span><span> deposits</span><span class="z-keyword"> /</span><span class="z-constant"> 2</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>right</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>right</span><span>.</span><span>finalize</span><span>(</span><span>remaining</span><span>,</span><span> level</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-variable z-language"> self</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> get_finalized</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> result</span><span>:</span><span> List</span><span>[</span><span>Hash32</span><span>]</span><span>)</span><span> -&gt;</span><span> uint</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>left</span><span>.</span><span>get_finalized</span><span>(</span><span>result</span><span>)</span><span class="z-keyword"> +</span><span class="z-variable z-language"> self</span><span>.</span><span>right</span><span>.</span><span>get_finalized</span><span>(</span><span>result</span><span>)</span></span> <span class="giallo-l"></span> <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"> Zero</span><span>(</span><span class="z-entity">MerkleTree</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> n</span><span>:</span><span> uint64</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> get_root</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>)</span><span> -&gt;</span><span> Hash32</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-variable z-language"> self</span><span>.</span><span>n</span><span class="z-keyword"> ==</span><span class="z-constant"> DEPOSIT_CONTRACT_DEPTH</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Handle the entirely empty tree case. This is included for</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> consistency/clarity as the zerohashes array is typically</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> only defined from 0 to DEPOSIT_CONTRACT_DEPTH - 1.</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> sha256</span><span>(</span><span>zerohashes</span><span>[</span><span class="z-variable z-language">self</span><span>.</span><span>n</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>]</span><span class="z-keyword"> +</span><span> zerohashes</span><span>[</span><span class="z-variable z-language">self</span><span>.</span><span>n</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> zerohashes</span><span>[</span><span class="z-variable z-language">self</span><span>.</span><span>n</span><span>]</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> is_full</span><span>(</span><span class="z-variable z-parameter z-function">self</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 class="z-constant"> False</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> push_leaf</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> leaf</span><span>:</span><span> Hash32</span><span>,</span><span class="z-variable z-parameter z-function"> level</span><span>:</span><span> uint</span><span>)</span><span> -&gt;</span><span> MerkleTree</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> MerkleTree</span><span>.</span><span>create</span><span>(</span><span>[</span><span>leaf</span><span>]</span><span>,</span><span> level</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> get_finalized</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> result</span><span>:</span><span> List</span><span>[</span><span>Hash32</span><span>]</span><span>)</span><span> -&gt;</span><span> uint</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 0</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <h3 id="relying-on-weak-subjectivity-sync">Relying on Weak Subjectivity Sync</h3> <p>The upcoming switch to PoS will require newly synced nodes to rely on valid weak subjectivity checkpoints because of long-range attacks. This proposal relies on the weak subjectivity assumption that clients will not bootstrap with an invalid WS checkpoint.</p> <h3 id="deposit-finalization-conditions">Deposit Finalization Conditions</h3> <p>Care must be taken not to send a snapshot which includes deposits that haven't been fully included in the finalized checkpoint. Let <code>state</code> be the <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/2b45496fe48fa75450ad29a05bdd48866f86528a/specs/phase0/beacon-chain.md#beaconstate"><code>BeaconState</code></a> at a given block in the chain. Under normal operation, the <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/2b45496fe48fa75450ad29a05bdd48866f86528a/specs/phase0/beacon-chain.md#eth1data"><code>Eth1Data</code></a> stored in <code>state.eth1_data</code> is replaced every <code>EPOCHS_PER_ETH1_VOTING_PERIOD</code> epochs. Thus, finalization of the deposit tree proceeds with increments of <code>state.eth1_data</code>. Let <code>eth1data</code> be some <code>Eth1Data</code>. Both of the following conditions MUST be met to consider <code>eth1data</code> finalized:</p> <ol> <li>A finalized checkpoint exists where the corresponding <code>state</code> has <code>state.eth1_data == eth1data</code></li> <li>A finalized checkpoint exists where the corresponding <code>state</code> has <code>state.eth1_deposit_index &gt;= eth1data.deposit_count</code></li> </ol> <p>When these conditions are met, the tree can be pruned in the <a href="https://wg-eips.ritovision.com/4881/#reference-implementation">reference implementation</a> by calling <code>tree.finalize(eth1data, execution_block_height)</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> 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> 2021-01-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Abdelhamid Bakhtahttps://github.com/abdelhamidbakhta Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/3198/ <h2 id="simple-summary">Simple Summary</h2> <p>Adds an opcode that gives the EVM access to the block's base fee.</p> <h2 id="abstract">Abstract</h2> <p>Add a <code>BASEFEE (0x48)</code> that returns the value of the base fee of the current block it is executing in.</p> <h2 id="motivation">Motivation</h2> <p>The intended use case would be for contracts to get the value of the base fee. This feature would enable or improve existing use cases, such as:</p> <ul> <li>Contracts that need to set bounties for anyone to "poke" them with a transaction could set the bounty to be <code>BASEFEE + x</code>, or <code>BASEFEE * (1 + x)</code>. This makes the mechanism more reliable, because they will always pay "enough" regardless of market conditions.</li> <li>Gas futures can be implemented based on it. This would be more precise than gastokens.</li> <li>Improve the security for state channels, plasma, optirolls and other fraud proof driven solutions. Having the <code>BASEFEE</code> as an input allows you to lengthen the challenge period automatically if you see that the <code>BASEFEE</code> is high.</li> </ul> <h2 id="specification">Specification</h2> <p>Add a <code>BASEFEE</code> opcode at <code>(0x48)</code>, with gas cost <code>G_base</code>.</p> <p>| Op | Input | Output | Cost | |:----: |:-----: |:------: |:----: | | 0x48 | 0 | 1 | 2 |</p> <h2 id="rationale">Rationale</h2> <h3 id="gas-cost">Gas cost</h3> <p>The value of the base fee is needed to process transactions. That means it's value is already available before running the EVM code. The opcode does not add extra complexity and additional read/write operations, hence the choice of <code>G_base</code> gas cost.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no known backward compatibility issues with this opcode.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="nominal-case">Nominal case</h3> <p>Assuming current block base fee is <code>7 wei</code>. This should push the value <code>7</code> (left padded byte32) to the stack.</p> <p>Bytecode: <code>0x4800</code> (<code>BASEFEE, STOP</code>)</p> <table><thead><tr><th>Pc</th><th>Op</th><th>Cost</th><th>Stack</th><th>RStack</th></tr></thead><tbody> <tr><td>0</td><td>BASEFEE</td><td>2</td><td>[]</td><td>[]</td></tr> <tr><td>1</td><td>STOP</td><td>0</td><td>[7]</td><td>[]</td></tr> </tbody></table> <p>Output: 0x Consumed gas: <code>2</code></p> <h2 id="security-considerations">Security Considerations</h2> <p>The value of the base fee is not sensitive and is publicly accessible in the block header. There are no known security implications with this 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> 2020-12-07T00:00:00+00:00 2026-02-11T14:49:27+00:00 Martin Holst Swendehttps://github.com/holiman Marius van der Wijdenhttps://github.com/MariusVanDerWijden https://wg-eips.ritovision.com/3155/

A JSON format for EVM traces

<h2 id="abstract">Abstract</h2> <p>Introduce a new JSON standard for EVM traces during execution of state tests.</p> <h2 id="motivation">Motivation</h2> <p>The Ethereum Virtual Machine executes all smart contract code on ethereum. In order to debug smart contracts and state tests better, a common format was introduced to log every execution step of the EVM. This format was implemented by Go-Ethereum, Parity-Ethereum, Nethermind and Besu. Since the common format was not well-defined, the implementations differed slightly, making it hard to develop adequate tooling which reduces the usefulness of tracing significantly.</p> <p>This EIP has multiple goals:</p> <ul> <li>Move the specification to a more visible place to encourage new clients to implement it</li> <li>Strictly define corner cases that were not addressed in the previous version</li> <li>Allow for updates to the specification in case new fields are introduced during execution</li> <li>Provide sample output</li> </ul> <p>Implementing this EIP in all major clients allows us to create meaningful differential fuzzers that fuzz EVM implementations for the mainnet and all upcoming hardforks. It also helps to find differences in execution quickly in the case of a chain split.</p> <p>This EIP will enable users to create better differential fuzzing infrastructure to compare the EVM implementations of all major Ethereum clients against each other. This could help to find bugs that are currently present in the client implementations.</p> <h2 id="specification">Specification</h2> <p>Clients should be able to execute simple transactions as well as code and return traces. In the following, we will call this client CUT (client under test) and use go-ethereum's <code>evm</code> binary for code examples.</p> <h3 id="datatypes">Datatypes</h3> <table><thead><tr><th>Type</th><th>Explanation</th><th>Example</th></tr></thead><tbody> <tr><td>Number</td><td>Plain json number</td><td>"pc":0</td></tr> <tr><td>Hex-Number</td><td>Hex-encoded number</td><td>"gas":"0x2540be400"</td></tr> <tr><td>String</td><td>Plain string</td><td>"opName":"PUSH1"</td></tr> <tr><td>Hex-String</td><td>Hex-encoded string</td><td></td></tr> <tr><td>Array of x</td><td>Array of x encoded values</td><td></td></tr> <tr><td>Key-Value</td><td>Key-Value structure with key and values encoded as hex strings</td><td></td></tr> <tr><td>Boolean</td><td>Json bool can either be true or false</td><td>"pass": true</td></tr> </tbody></table> <h3 id="output">Output</h3> <p>The CUT MUST output a <code>json</code> object for EACH operation.</p> <h4 id="required-fields">Required Fields</h4> <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>Number</td><td>OpCode</td></tr> <tr><td><code>gas</code></td><td>Hex-Number</td><td>Gas left before executing this operation</td></tr> <tr><td><code>gasCost</code></td><td>Hex-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>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>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> <h4 id="optional-fields">Optional Fields</h4> <table><thead><tr><th>Name</th><th>Type</th><th>Explanation</th></tr></thead><tbody> <tr><td><code>opName</code></td><td>String</td><td>Name of the operation</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> <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> <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> <ul> <li>The <code>stack</code>, <code>memory</code> and <code>memSize</code> are the values <em>before</em> execution of the op.</li> <li>All array attributes (<code>stack</code>, <code>memory</code>) MUST be initialized to empty arrays (<code>"stack":[]</code>) NOT to null.</li> <li>If the CUT will not be outputting values for <code>memory</code> or <code>storage</code> then the <code>memory</code> and <code>storage</code> fields are omitted. This can happen either because the CUT does not support tracing these fields or it has been configured not to trace it.</li> <li>The <code>memSize</code> field MUST be present regardless of <code>memory</code> support.</li> <li>Clients SHOULD implement a way to disable recording the storage as the stateroot includes all storage updates.</li> <li>Clients SHOULD output the fields in the same order as listed in this EIP.</li> </ul> <p>The CUT MUST NOT output a line for the <code>STOP</code> operation if an error occurred:</p> <p><em>Example:</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{&quot;pc&quot;:2,&quot;op&quot;:0,&quot;gas&quot;:&quot;0x2540be3fd&quot;,&quot;gasCost&quot;:&quot;0x0&quot;,&quot;memory&quot;:&quot;0x&quot;,&quot;memSize&quot;:0,&quot;stack&quot;:[&quot;0x40&quot;],&quot;depth&quot;:1,&quot;error&quot;:null,&quot;opName&quot;:&quot;STOP&quot;}</span></span></code></pre><h3 id="summary-and-error-handling">Summary and Error Handling</h3> <p>At the end of execution, the CUT MUST print summary info; this info SHOULD have the following fields. The summary should be a single <code>jsonl</code> object.</p> <h4 id="required-fields-1">Required Fields</h4> <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></td><td>Return values of the function</td></tr> <tr><td><code>gasUsed</code></td><td>Hex-Number</td><td>All gas used by the transaction</td></tr> <tr><td><code>pass</code></td><td>Boolean</td><td>Bool whether transaction was executed successfully</td></tr> </tbody></table> <h4 id="optional-fields-1">Optional Fields</h4> <table><thead><tr><th>Name</th><th>Type</th><th>Explanation</th></tr></thead><tbody> <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> <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 largely based on the previous non-official documentation for EVM tracing. It tries to cover as many corner cases as possible to enable true client compatibility. The datatypes and if a field is optional is chosen to be as compatible with current implementations as possible.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backward compatible with ethereum as it only introduces a better tracing infrastructure that is optional for clients to implement.</p> <h3 id="clients">Clients</h3> <p>This EIP is fully backward compatible with go-ethereum. OpenEthereum, Besu and Nethermind clients would have to change their JSON output of <code>openethereum-evm</code> <code>evmtool</code> and <code>nethtest</code> slightly do adhere to the new and stricter specs. New clients would need to implement this change if they want to be part of the differential fuzzing group.</p> <h2 id="test-cases">Test Cases</h2> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span>$</span><span>{</span><span class="z-variable z-other">BESU_HOME</span><span>}</span><span>/bin/evmtool --code 0x604080536040604055604060006040600060025afa6040f3 </span><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">op</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x2540be400</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">gasCost</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">0x3</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memSize</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">stack</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string">[</span><span class="z-string">]</span><span class="z-string">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">depth</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:1,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">refund</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">opName</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">PUSH1</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:2,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">op</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:128,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x2540be3fd</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">gasCost</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">0x3</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memSize</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">stack</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">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">],</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">depth</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:1,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">refund</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">opName</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">DUP1</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:3,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">op</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:83,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x2540be3fa</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">gasCost</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">0xc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memSize</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">stack</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">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">],</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">depth</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:1,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">refund</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">opName</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">MSTORE8</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:4,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">op</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x2540be3ee</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">gasCost</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">0x3</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memory</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">0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memSize</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">stack</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string">[</span><span class="z-string">]</span><span class="z-string">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">depth</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:1,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">refund</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">opName</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">PUSH1</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:6,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">op</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x2540be3eb</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">gasCost</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">0x3</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memory</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">0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memSize</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">stack</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">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">],</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">depth</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:1,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">refund</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">opName</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">PUSH1</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:8,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">op</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:85,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x2540be3e8</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">gasCost</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">0x4e20</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memory</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">0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memSize</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">stack</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">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">],</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">depth</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:1,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">refund</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">opName</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">SSTORE</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:9,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">op</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x2540b95c8</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">gasCost</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">0x3</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memory</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">0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memSize</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">stack</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string">[</span><span class="z-string">]</span><span class="z-string">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">depth</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:1,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">refund</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">opName</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">PUSH1</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:11,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">op</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x2540b95c5</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">gasCost</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">0x3</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memory</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">0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memSize</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">stack</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">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">],</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">depth</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:1,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">refund</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">opName</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">PUSH1</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:13,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">op</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x2540b95c2</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">gasCost</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">0x3</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memory</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">0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memSize</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">stack</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">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x0</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">],</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">depth</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:1,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">refund</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">opName</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">PUSH1</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:15,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">op</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x2540b95bf</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">gasCost</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">0x3</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memory</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">0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memSize</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">stack</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">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x0</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">],</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">depth</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:1,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">refund</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">opName</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">PUSH1</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:17,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">op</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x2540b95bc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">gasCost</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">0x3</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memory</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">0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memSize</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">stack</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">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x0</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x0</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">],</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">depth</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:1,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">refund</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">opName</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">PUSH1</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:19,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">op</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:90,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x2540b95b9</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">gasCost</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">0x2</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memory</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">0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memSize</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">stack</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">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x0</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x0</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x2</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">],</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">depth</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:1,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">refund</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">opName</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">GAS</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:20,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">op</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:250,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x2540b95b7</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">gasCost</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">0x24abb676c</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memory</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">0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memSize</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">stack</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">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x0</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x0</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x2</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x2540b95b7</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">],</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">depth</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:1,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">refund</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">opName</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">STATICCALL</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:21,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">op</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x2540b92a7</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">gasCost</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">0x3</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memory</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">0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b00000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memSize</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">stack</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">0x1</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">],</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">returnData</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">0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">depth</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:1,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">refund</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">opName</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">PUSH1</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pc</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:23,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">op</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:243,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x2540b92a4</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">gasCost</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">0x0</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memory</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">0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b00000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">memSize</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:96,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">stack</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">0x1</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">],</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">returnData</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">0xf5a5fd42d16a20302798ef6ed309979b43003d2320d9f0e8ea9831a92759fb4b</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">depth</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:1,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">refund</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:0,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">opName</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">RETURN</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span>{</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x8fa0dcc7f1d2383c89e5737c2843632db881c0946e80b71fe7175365e6538797</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">output</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">0x40</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><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-entity z-name">&quot;</span><span class="z-entity z-name">0x515c</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">pass</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">:true,</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">fork</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">Istanbul</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Tracing is expensive.</p> <p>Exposing an endpoint for creating traces publicly could open up a denial of service vector.</p> <p>Clients should consider putting trace endpoints behind a separate flag from other endpoints.</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-12-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Will Wanghttps://github.com/will42w Mike Mengmyan@solv.finance Yi Caihttps://github.com/YeeTsaiyee.tsai@gmail.com Ryan Chowryanchow@solv.finance Zhongxin Wuhttps://github.com/Nerverwind AlvisDuhttps://github.com/AlvisDu https://wg-eips.ritovision.com/3525/

Defines a specification where ERC-721 compatible tokens with the same SLOT and different IDs are fungible.

<h2 id="abstract">Abstract</h2> <p>This is a standard for semi-fungible tokens. The set of smart contract interfaces described in this document defines an <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> compatible token standard. This standard introduces an <code>&lt;ID, SLOT, VALUE&gt;</code> triple scalar model that represents the semi-fungible structure of a token. It also introduces new transfer models as well as approval models that reflect the semi-fungible nature of the tokens.</p> <p>Token contains an ERC-721 equivalent ID property to identify itself as a universally unique entity, so that the tokens can be transferred between addresses and approved to be operated in ERC-721 compatible way.</p> <p>Token also contains a <code>value</code> property, representing the quantitative nature of the token. The meaning of the 'value' property is quite like that of the 'balance' property of an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token. Each token has a 'slot' attribute, ensuring that the value of two tokens with the same slot be treated as fungible, adding fungibility to the value property of the tokens.</p> <p>This EIP introduces new token transfer models for semi-fungibility, including value transfer between two tokens of the same slot and value transfer from a token to an address.</p> <h2 id="motivation">Motivation</h2> <p>Tokenization is one of the most important trends by which to use and control digital assets in crypto. Traditionally, there have been two approaches to do so: fungible and non-fungible tokens. Fungible tokens generally use the ERC-20 standard, where every unit of an asset is identical to each other. ERC-20 is a flexible and efficient way to manipulate fungible tokens. Non-fungible tokens are predominantly ERC-721 tokens, a standard capable of distinguishing digital assets from one another based on identity.</p> <p>However, both have significant drawbacks. For example, ERC-20 requires that users create a separate ERC-20 contract for each individual data structure or combination of customizable properties. In practice, this results in an extraordinarily large amount of ERC-20 contracts that need to be created. On the other hand, ERC-721 tokens provide no quantitative feature, significantly undercutting their computability, liquidity, and manageability. For example, if one was to create financial instruments such as bonds, insurance policy, or vesting plans using ERC-721, no standard interfaces are available for us to control the value in them, making it impossible, for example, to transfer a portion of the equity in the contract represented by the token.</p> <p>A more intuitive and straightforward way to solve the problem is to create a semi-fungible token that has the quantitative features of ERC-20 and qualitative attributes of ERC-721. The backwards-compatibility with ERC-721 of such semi-fungible tokens would help utilize existing infrastructures already in use and lead to faster adoption.</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 <a href="https://wg-eips.ritovision.com/3525/">ERC-3525</a> compliant contract must implement the ERC-3525, ERC-721 and <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> 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-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> ERC-3525 Semi-Fungible Token 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 0xd5358140.</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"> IERC3525</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC165, 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"> MUST emit when value of a token is transferred to another token with the same slot,</span></span> <span class="giallo-l"><span class="z-comment"> * including zero value transfers (_value == 0) as well as transfers when tokens are created</span></span> <span class="giallo-l"><span class="z-comment"> * (`_fromTokenId` == 0) or destroyed (`_toTokenId` == 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"> _fromTokenId</span><span class="z-comment"> The token id to transfer value from</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _toTokenId</span><span class="z-comment"> The token id to transfer value 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"> _value</span><span class="z-comment"> The transferred value</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"> TransferValue</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _fromTokenId</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _toTokenId</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 the approval value of a token is set or </span><span class="z-keyword">changed</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"> _tokenId</span><span class="z-comment"> The token 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"> _operator</span><span class="z-comment"> The operator to approve 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"> _value</span><span class="z-comment"> The maximum value that `_operator` is allowed to manage</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"> ApprovalValue</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"> _operator</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 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 the slot of a token is set or </span><span class="z-keyword">changed</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"> _tokenId</span><span class="z-comment"> The token of which slot is set or </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"> _oldSlot</span><span class="z-comment"> The previous slot of 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"> _newSlot</span><span class="z-comment"> The updated slot of the token</span></span> <span class="giallo-l"><span class="z-comment"> */</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SlotChanged</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-storage z-type"> indexed</span><span class="z-variable"> _oldSlot</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _newSlot</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 number of decimals the token uses for value - e.g. 6, means the user</span></span> <span class="giallo-l"><span class="z-comment"> * representation of the value of a token can be calculated by dividing it by 1,000,000.</span></span> <span class="giallo-l"><span class="z-comment"> * Considering the compatibility with third-party wallets, this function is defined as</span></span> <span class="giallo-l"><span class="z-comment"> * `valueDecimals()` instead of `decimals()` to avoid conflict with ERC-20 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"> The</span><span class="z-comment"> number of decimals for value</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"> valueDecimals</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get the value 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"> The token 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"> The</span><span class="z-comment"> value 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"> balanceOf</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 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 slot 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"> The identifier for a 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"> The</span><span class="z-comment"> slot of 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"> slotOf</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 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"> Allow an operator to manage the value of a token, up to the `_value`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST revert unless caller is the current owner, an authorized operator, or the approved</span></span> <span class="giallo-l"><span class="z-comment"> * address for `_tokenId`.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit the ApprovalValue 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"> _tokenId</span><span class="z-comment"> The token 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"> _operator</span><span class="z-comment"> The operator to be approved</span></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 maximum value of `_toTokenId` that `_operator` is allowed to manage</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> <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"> _operator</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 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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get the maximum value of a token that an operator is allowed to manage.</span></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 for which to query the allowance</span></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 of an operator</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"> current approval value of `_tokenId` that `_operator` is allowed to manage</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">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"> _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">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"> Transfer value from a specified token to another specified token with the same slot.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Caller MUST be the current owner, an authorized operator or an operator who has been</span></span> <span class="giallo-l"><span class="z-comment"> * approved the whole `_fromTokenId` or part of it.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if `_fromTokenId` or `_toTokenId` is zero token id or does not exist.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if slots of `_fromTokenId` and `_toTokenId` do not match.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if `_value` exceeds the balance of `_fromTokenId` or its allowance to the</span></span> <span class="giallo-l"><span class="z-comment"> * operator.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit `TransferValue` 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"> _fromTokenId</span><span class="z-comment"> The token to transfer value from</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _toTokenId</span><span class="z-comment"> The token to transfer value 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"> _value</span><span class="z-comment"> The transferred value</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"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _toTokenId</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 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> <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"> Transfer value from a specified token to an address. The caller should confirm that</span></span> <span class="giallo-l"><span class="z-comment"> * `_to` is capable of receiving ERC-3525 tokens.</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 create a new ERC-3525 token with the same slot for `_to`, </span></span> <span class="giallo-l"><span class="z-comment"> * or find an existing token with the same slot owned by `_to`, to receive the transferred value.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if `_fromTokenId` is zero token id or does not exist.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if `_to` is zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert if `_value` exceeds the balance of `_fromTokenId` or its allowance to the</span></span> <span class="giallo-l"><span class="z-comment"> * operator.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit `Transfer` and `TransferValue` 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"> _fromTokenId</span><span class="z-comment"> The token to transfer value from</span></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 transfer value 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"> _value</span><span class="z-comment"> The transferred value</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"> ID</span><span class="z-comment"> of the token which receives the transferred value</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"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</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"> _value</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 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 slot's enumeration extension is OPTIONAL. This allows your contract to publish its full list of <code>SLOT</code>s and make them discoverable.</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-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> ERC-3525 Semi-Fungible Token Standard, optional extension for slot enumeration</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Interfaces for any contract that wants to support enumeration of slots as well as tokens </span></span> <span class="giallo-l"><span class="z-comment"> * with the same slot.</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 0x3b741b9e.</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"> IERC3525SlotEnumerable</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC3525</span><span> /* , </span><span class="z-entity z-name">IERC721Enumerable</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 total amount of slots stored by 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"> The</span><span class="z-comment"> total amount of slots</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"> slotCount</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 slot at the specified index of all slots stored by 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"> _index</span><span class="z-comment"> The index in the slot 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"> slot at `index` of all slots.</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"> slotByIndex</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 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 amount of tokens with the same slot.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _slot</span><span class="z-comment"> The slot to query token supply 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"> total amount of tokens with the specified `_slot`</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"> tokenSupplyInSlot</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _slot</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 token at the specified index of all tokens with the same slot.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _slot</span><span class="z-comment"> The slot to query tokens with</span></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"> The index in the token list of the slot</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 ID at `_index` of all tokens with `_slot`</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"> tokenInSlotByIndex</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _slot</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 slot level approval is OPTIONAL. This allows any contract that wants to support approval for slots, which allows an operator to manage one's tokens with the same slot.</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-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> ERC-3525 Semi-Fungible Token Standard, optional extension for approval of slot level</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Interfaces for any contract that wants to support approval of slot level, which allows an</span></span> <span class="giallo-l"><span class="z-comment"> * operator to manage one&#39;s tokens with the same slot.</span></span> <span class="giallo-l"><span class="z-comment"> * See https://eips.ethereum.org/EIPS/eip-3525</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 0xb688be58.</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"> IERC3525SlotApprovable</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC3525</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 an operator is approved or disapproved to manage all of `_owner`&#39;s</span></span> <span class="giallo-l"><span class="z-comment"> * tokens with the same slot.</span></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"> The address whose tokens are approved</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _slot</span><span class="z-comment"> The slot to approve, all of `_owner`&#39;s tokens with this slot are approved</span></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 operator being approved or 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"> Identify if `_operator` is approved or disapproved</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"> ApprovalForSlot</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">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _slot</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">@notice</span><span class="z-comment"> Approve or disapprove an operator to manage all of `_owner`&#39;s tokens with the</span></span> <span class="giallo-l"><span class="z-comment"> * specified slot.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Caller SHOULD be `_owner` or an operator who has been authorized through</span></span> <span class="giallo-l"><span class="z-comment"> * `setApprovalForAll`.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST emit ApprovalSlot 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"> _owner</span><span class="z-comment"> The address that owns the ERC-3525 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"> _slot</span><span class="z-comment"> The slot of tokens being queried approval 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"> _operator</span><span class="z-comment"> The address for whom to query approval</span></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"> Identify if `_operator` would be approved or disapproved</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"> setApprovalForSlot</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _slot</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"> bool</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-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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Query if `_operator` is authorized to manage all of `_owner`&#39;s tokens with the</span></span> <span class="giallo-l"><span class="z-comment"> * specified slot.</span></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"> The address that owns the ERC-3525 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"> _slot</span><span class="z-comment"> The slot of tokens being queried approval 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"> _operator</span><span class="z-comment"> The address for whom to query approval</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 authorized to manage all of `_owner`&#39;s tokens with `_slot`,</span></span> <span class="giallo-l"><span class="z-comment"> * 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"> isApprovedForSlot</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _slot</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 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></span></code></pre><h3 id="erc-3525-token-receiver">ERC-3525 Token Receiver</h3> <p>If a smart contract wants to be informed when they receive values from other addresses, it should implement all of the functions in the <code>IERC3525Receiver</code> interface, in the implementation it can decide whether to accept or reject the transfer. See "Transfer Rules" for further detail.</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-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> ERC-3525 token receiver interface</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 a smart contract that wants to be informed by ERC-3525 contracts when receiving values from ANY addresses or ERC-3525 tokens.</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 0x009ce20b.</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"> IERC3525Receiver</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"> Handle the receipt of an ERC-3525 token value.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> An ERC-3525 smart contract MUST check whether this function is implemented by the recipient contract, if the</span></span> <span class="giallo-l"><span class="z-comment"> * recipient contract implements this function, the ERC-3525 contract MUST call this function after a </span></span> <span class="giallo-l"><span class="z-comment"> * value transfer (i.e. `transferFrom(uint256,uint256,uint256,bytes)`).</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return 0x009ce20b (i.e. `bytes4(keccak256(&#39;onERC3525Received(address,uint256,uint256,</span></span> <span class="giallo-l"><span class="z-comment"> * uint256,bytes)&#39;))`) if the transfer is accepted.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST revert or return any value other than 0x009ce20b if the transfer is rejected.</span></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 which triggered the 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"> _fromTokenId</span><span class="z-comment"> The token id to transfer value from</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _toTokenId</span><span class="z-comment"> The token id to transfer value 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"> _value</span><span class="z-comment"> The transferred 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"> _data</span><span class="z-comment"> Additional data with no specified format</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-comment"> `bytes4(keccak256(&#39;onERC3525Received(address,uint256,uint256,uint256,bytes)&#39;))` </span></span> <span class="giallo-l"><span class="z-comment"> * unless the transfer is rejected.</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"> onERC3525Received</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"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _toTokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</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-keyword"> returns</span><span> (</span><span class="z-support">bytes4</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="token-manipulation">Token Manipulation</h3> <h4 id="scenarios">Scenarios</h4> <p><em><strong>Transfer:</strong></em></p> <p>Besides ERC-721 compatible token transfer methods, this EIP introduces two new transfer models: value transfer from ID to ID, and value transfer from ID to 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"> transferFrom</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _toTokenId</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-storage z-type"> payable</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"> transferFrom</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</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"> external</span><span class="z-storage z-type"> payable</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> toTokenId_</span><span>)</span><span>;</span></span></code></pre> <p>The first one allows value transfers from one token (specified by <code>_fromTokenId</code>) to another token (specified by <code>_toTokenId</code>) within the same slot, resulting in the <code>_value</code> being subtracted from the value of the source token and added to the value of the destination token;</p> <p>The second one allows value transfers from one token (specified by <code>_fromTokenId</code>) to an address (specified by <code>_to</code>), the value is actually transferred to a token owned by the address, and the id of the destination token should be returned. Further explanation can be found in the 'design decision' section for this method.</p> <h4 id="rules">Rules</h4> <p><em><strong>approving rules:</strong></em></p> <p>This EIP provides four kinds of approving functions indicating different levels of approvals, which can be described as full level approval, slot level approval, token ID level approval as well as value level approval.</p> <ul> <li><code>setApprovalForAll</code>, compatible with ERC-721, SHOULD indicate the full level of approval, which means that the authorized operators are capable of managing all the tokens, including their values, owned by the owner.</li> <li><code>setApprovalForSlot</code> (optional) SHOULD indicate the slot level of approval, which means that the authorized operators are capable of managing all the tokens with the specified slot, including their values, owned by the owner.</li> <li>The token ID level <code>approve</code> function, compatible with ERC-721, SHOULD indicate that the authorized operator is capable of managing only the specified token ID, including its value, owned by the owner.</li> <li>The value level <code>approve</code> function, SHOULD indicate that the authorized operator is capable of managing the specified maximum value of the specified token owned by the owner.</li> <li>For any approving function, the caller MUST be the owner or has been approved with a higher level of authority.</li> </ul> <p><em><strong>transferFrom rules:</strong></em></p> <ul> <li> <p>The <code>transferFrom(uint256 _fromTokenId, uint256 _toTokenId, uint256 _value)</code> function, SHOULD indicate value transfers from one token to another token, in accordance with the rules below:</p> <ul> <li>MUST revert unless <code>msg.sender</code> is the owner of <code>_fromTokenId</code>, an authorized operator or an operator who has been approved the whole token or at least <code>_value</code> of it.</li> <li>MUST revert if <code>_fromTokenId</code> or <code>_toTokenId</code> is zero token id or does not exist.</li> <li>MUST revert if slots of <code>_fromTokenId</code> and <code>_toTokenId</code> do not match.</li> <li>MUST revert if <code>_value</code> exceeds the value of <code>_fromTokenId</code> or its allowance to the operator.</li> <li>MUST check for the <code>onERC3525Received</code> function if the owner of _toTokenId is a smart contract, if the function exists, MUST call this function after the value transfer, MUST revert if the result is not equal to 0x009ce20b;</li> <li>MUST emit <code>TransferValue</code> event.</li> </ul> </li> <li> <p>The <code>transferFrom(uint256 _fromTokenId, address _to, uint256 _value)</code> function, which transfers value from one token ID to an address, SHOULD follow the rule below:</p> <ul> <li>MUST either find a ERC-3525 token owned by the address <code>_to</code> or create a new ERC-3525 token, with the same slot of <code>_fromTokenId</code>, to receive the transferred value.</li> <li>MUST revert unless <code>msg.sender</code> is the owner of <code>_fromTokenId</code>, an authorized operator or an operator who has been approved the whole token or at least <code>_value</code> of it.</li> <li>MUST revert if <code>_fromTokenId</code> is zero token id or does not exist.</li> <li>MUST revert if <code>_to</code> is zero address.</li> <li>MUST revert if <code>_value</code> exceeds the value of <code>_fromTokenId</code> or its allowance to the operator.</li> <li>MUST check for the <code>onERC3525Received</code> function if the _to address is a smart contract, if the function exists, MUST call this function after the value transfer, MUST revert if the result is not equal to 0x009ce20b;</li> <li>MUST emit <code>Transfer</code> and <code>TransferValue</code> events.</li> </ul> </li> </ul> <h3 id="metadata">Metadata</h3> <h4 id="metadata-extensions">Metadata Extensions</h4> <p>ERC-3525 metadata extensions are compatible ERC-721 metadata extensions.</p> <p>This optional interface can be identified with the ERC-165 Standard Interface Detection.</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-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> ERC-3525 Semi-Fungible Token Standard, optional extension for metadata</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Interfaces for any contract that wants to support query of the Uniform Resource Identifier</span></span> <span class="giallo-l"><span class="z-comment"> * (URI) for the ERC-3525 contract as well as a specified slot. </span></span> <span class="giallo-l"><span class="z-comment"> * Because of the higher reliability of data stored in smart contracts compared to data stored in </span></span> <span class="giallo-l"><span class="z-comment"> * centralized systems, it is recommended that metadata, including `contractURI`, `slotURI` and </span></span> <span class="giallo-l"><span class="z-comment"> * `tokenURI`, be directly returned in JSON format, instead of being returned with a url pointing </span></span> <span class="giallo-l"><span class="z-comment"> * to any resource stored in a centralized system. </span></span> <span class="giallo-l"><span class="z-comment"> * See https://eips.ethereum.org/EIPS/eip-3525</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 0xe1600902.</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"> IERC3525Metadata</span><span class="z-storage"> is</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC3525</span><span> /* , </span><span class="z-entity z-name">IERC721Metadata</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"> Returns the Uniform Resource Identifier (URI) for the current ERC-3525 contract.</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 SHOULD return the URI for this contract in JSON format, starting with</span></span> <span class="giallo-l"><span class="z-comment"> * header `data:application/json;`.</span></span> <span class="giallo-l"><span class="z-comment"> * See https://eips.ethereum.org/EIPS/eip-3525 for the JSON schema for contract URI.</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"> JSON formatted URI of the current ERC-3525 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"> contractURI</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-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns the Uniform Resource Identifier (URI) for the specified slot.</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 SHOULD return the URI for `_slot` in JSON format, starting with header</span></span> <span class="giallo-l"><span class="z-comment"> * `data:application/json;`.</span></span> <span class="giallo-l"><span class="z-comment"> * See https://eips.ethereum.org/EIPS/eip-3525 for the JSON schema for slot URI.</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"> JSON formatted URI of `_slot`</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"> slotURI</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _slot</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><h4 id="erc-3525-metadata-uri-json-schema">ERC-3525 Metadata URI JSON Schema</h4> <p>This is the "ERC-3525 Metadata JSON Schema for <code>contractURI()</code>" 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">Contract 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">Contract 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 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 contract</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">Optional. Either a base64 encoded imgae data or a URI pointing to a resource with mime type image/* representing what this contract 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">external_link</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">Optional. A URI pointing to an external resource.</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">valueDecimals</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">The number of decimal places that the balance should display - e.g. 18, means to divide the token value by 1000000000000000000 to get its user representation.</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>This is the "ERC-3525 Metadata JSON Schema for <code>slotURI(uint)</code>" 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">Slot 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 category to which this slot 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 category to which this slot 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">Optional. Either a base64 encoded imgae data or a URI pointing to a resource with mime type image/* representing the asset category to which this slot 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">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">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">Each item of `properties` SHOULD be organized in object format, including name, description, value, order (optional), display_type (optional), etc.</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">items</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-invalid z-illegal">:</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">The name of this property.</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 this property.</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-string"> &quot;</span><span class="z-string">value</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-invalid z-illegal">:</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 of this property, which may be a string or a number.</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">is_intrinsic</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></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">According to the definition of `slot`, one of the best practice to generate the value of a slot is utilizing the `keccak256` algorithm to calculate the hash value of multi properties. In this scenario, the `properties` field should contain all the properties that are used to calculate the value of `slot`, and if a property is used in the calculation, is_intrinsic must be TRUE.</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">order</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">Optional, related to the value of is_intrinsic. If is_intrinsic is TRUE, it must be the order of this property appeared in the calculation method of the slot.</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">display_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></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">Optional. Specifies in what form this property should be displayed.</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>This is the "ERC-3525 Metadata JSON Schema for <code>tokenURI(uint)</code>" 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">Token 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 token 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 token 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">Either a base64 encoded imgae data or a URI pointing to a resource with mime type image/* representing the asset to which this token 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">balance</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">THe value held by this token.</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">slot</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">The id of the slot that this token belongs to.</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">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">Arbitrary properties. Values may be strings, numbers, objects or arrays. Optional, you can use the same schema as the properties section of ERC-3525 Metadata JSON Schema for slotURI(uint) if you need a better description attribute.</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><h2 id="rationale">Rationale</h2> <h3 id="metadata-generation">Metadata generation</h3> <p>This token standard is designed to represent semi-fungible assets, which are most suited for financial instruments rather than collectibles or in-game items. For maximum transparency and safety of digital assets, we strongly recommend that all implementations should generate metadata directly from contract code rather than giving out an off-chain server URL.</p> <h3 id="design-decision-value-transfer-from-token-to-address">Design decision: Value transfer from token to address</h3> <p>The 'value' of a token is a property of the token and is not linked to an address, so to transfer the value to an address would be actually transferring it to a token owned by that address, not the address itself.</p> <p>From the implementation perspective, the process of transferring values from token to address could be done as follows: (1) create a new token for the recipient's address, (2) transfer the value to the new token from the 'source token'. So that this method is not fully independent from the ID-to-ID transfer method, and can be viewed as syntactic sugar that wraps the process described above.</p> <p>In a special case, if the destination address owns one or more tokens with the same slot value as the source token, this method will have an alternative implementation as follows: (1) find one token owned by the address with the same slot value of the source token, (2) transfer the value to the found token.</p> <p>Both implementations described above should be treated as compliant with this standard.</p> <p>The purpose of maintaining id-to-address transfer function is to maximize the compatibility with most wallet apps, since for most of the token standards, the destination of token transfer are addresses. This syntactic wrapping will help wallet apps easily implement the value transfer function from a token to any address.</p> <h3 id="design-decision-notification-acceptance-mechanism-instead-of-safe-transfer">Design decision: Notification/acceptance mechanism instead of 'Safe Transfer'</h3> <p>ERC-721 and some later token standards introduced 'Safe Transfer' model, for better control of the 'safety' when transferring tokens, this mechanism leaves the choice of different transfer modes (safe/unsafe) to the sender, and may cause some potential problems:</p> <ol> <li>In most situations the sender does not know how to choose between two kinds of transfer methods (safe/unsafe);</li> <li>If the sender calls the <code>safeTransferFrom</code> method, the transfer may fail if the recipient contract did not implement the callback function, even if that contract is capable of receiving and manipulating the token without issue.</li> </ol> <p>This EIP defines a simple 'Check, Notify and Response' model for better flexibility as well as simplicity:</p> <ol> <li>No extra <code>safeTransferFrom</code> methods are needed, all callers only need to call one kind of transfer;</li> <li>All ERC-3525 contracts MUST check for the existence of <code>onERC3525Received</code> on the recipient contract and call the function when it exists;</li> <li>Any smart contract can implement <code>onERC3525Received</code> function for the purpose of being notified after receiving values; this function MUST return 0x009ce20b (i.e. <code>bytes4(keccak256('onERC3525Received(address,uint256,uint256,uint256,bytes)'))</code>) if the transfer is accepted, or any other value if the transfer is rejected.</li> </ol> <p>There is a special case for this notification/acceptance mechanism: since ERC-3525 allows value transfer from an address to itself, when a smart contract which implements <code>onERC3525Received</code> transfers value to itself, <code>onERC3525Received</code> will also be called. This allows for the contract to implement different rules of acceptance between self-value-transfer and receiving value from other addresses.</p> <h3 id="design-decision-relationship-between-different-approval-models">Design decision: Relationship between different approval models</h3> <p>For semantic compatibility with ERC-721 as well as the flexibility of value manipulation of tokens, we decided to define the relationships between some of the levels of approval like that:</p> <ol> <li>Approval of an id will lead to the ability to partially transfer values from this id by the approved operator; this will simplify the value approval for an id. However, the approval of total values in a token should not lead to the ability to transfer the token entity by the approved operator.</li> <li><code>setApprovalForAll</code> will lead to the ability to partially transfer values from any token, as well as the ability to approve partial transfer of values from any token to a third party; this will simplify the value transfer and approval of all tokens owned by an address.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As mentioned in the beginning, this EIP is backward compatible with ERC-721.</p> <h2 id="reference-implementation">Reference Implementation</h2> <ul> <li><a href="https://wg-eips.ritovision.com/3525/./assets/contracts/ERC3525.sol">ERC-3525 implementation</a></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>The value level approval and slot level approval (optional) is isolated from ERC-721 approval models, so that approving value should not affect ERC-721 level approvals. Implementations of this EIP must obey this principle.</p> <p>Since this EIP is ERC-721 compatible, any wallets and smart contracts that can hold and manipulate standard ERC-721 tokens will have no risks of asset loss for ERC-3525 tokens due to incompatible standards 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> 2020-11-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Alberto Cuesta Cañadahttps://github.com/alcueca Fiona Kobayashihttps://github.com/fifikobayashi fubuloubuhttps://github.com/fubuloubu Austin Williamshttps://github.com/onewayfunction https://wg-eips.ritovision.com/3156/ <h2 id="simple-summary">Simple Summary</h2> <p>This ERC provides standard interfaces and processes for single-asset flash loans.</p> <h2 id="abstract">Abstract</h2> <p>A flash loan is a smart contract transaction in which a lender smart contract lends assets to a borrower smart contract with the condition that the assets are returned, plus an optional fee, before the end of the transaction. This ERC specifies interfaces for lenders to accept flash loan requests, and for borrowers to take temporary control of the transaction within the lender execution. The process for the safe execution of flash loans is also specified.</p> <h2 id="motivation">Motivation</h2> <p>Flash loans allow smart contracts to lend an amount of tokens without a requirement for collateral, with the condition that they must be returned within the same transaction.</p> <p>Early adopters of the flash loan pattern have produced different interfaces and different use patterns. The diversification is expected to intensify, and with it the technical debt required to integrate with diverse flash lending patterns.</p> <p>Some of the high level differences in the approaches across the protocols include:</p> <ul> <li>Repayment approaches at the end of the transaction, where some pull the principal plus the fee from the loan receiver, and others where the loan receiver needs to manually return the principal and the fee to the lender.</li> <li>Some lenders offer the ability to repay the loan using a token that is different to what was originally borrowed, which can reduce the overall complexity of the flash transaction and gas fees.</li> <li>Some lenders offer a single entry point into the protocol regardless of whether you're buying, selling, depositing or chaining them together as a flash loan, whereas other protocols offer discrete entry points.</li> <li>Some lenders allow to flash mint any amount of their native token without charging a fee, effectively allowing flash loans bounded by computational constraints instead of asset ownership constraints.</li> </ul> <h2 id="specification">Specification</h2> <p>A 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 IERC3156FlashLender 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;./IERC3156FlashBorrower.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>interface IERC3156FlashLender {</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 lent.</span></span> <span class="giallo-l"><span> * @param token The loan currency.</span></span> <span class="giallo-l"><span> * @return The amount of `token` that can be borrowed.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function maxFlashLoan(</span></span> <span class="giallo-l"><span> address token</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 fee to be charged for a given loan.</span></span> <span class="giallo-l"><span> * @param token The loan currency.</span></span> <span class="giallo-l"><span> * @param amount The amount of tokens lent.</span></span> <span class="giallo-l"><span> * @return The amount of `token` to be charged for the 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 token,</span></span> <span class="giallo-l"><span> uint256 amount</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 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 token The loan currency.</span></span> <span class="giallo-l"><span> * @param amount 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 flashLoan(</span></span> <span class="giallo-l"><span> IERC3156FlashBorrower receiver,</span></span> <span class="giallo-l"><span> address token,</span></span> <span class="giallo-l"><span> uint256 amount,</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 <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 fee charged for a loan of <code>amount</code> <code>token</code>. If the token is not supported <code>flashFee</code> MUST revert.</p> <p>The <code>flashLoan</code> function MUST include a callback to the <code>onFlashLoan</code> function in a <code>IERC3156FlashBorrower</code> contract.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function flashLoan(</span></span> <span class="giallo-l"><span> IERC3156FlashBorrower receiver,</span></span> <span class="giallo-l"><span> address token,</span></span> <span class="giallo-l"><span> uint256 amount,</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.onFlashLoan(msg.sender, token, amount, fee, data) == keccak256(&quot;ERC3156FlashBorrower.onFlashLoan&quot;),</span></span> <span class="giallo-l"><span> &quot;IERC3156: 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>flashLoan</code> function MUST transfer <code>amount</code> of <code>token</code> to <code>receiver</code> before the callback to the receiver.</p> <p>The <code>flashLoan</code> function MUST include <code>msg.sender</code> as the <code>initiator</code> to <code>onFlashLoan</code>.</p> <p>The <code>flashLoan</code> function MUST NOT modify the <code>token</code>, <code>amount</code> and <code>data</code> parameter received, and MUST pass them on to <code>onFlashLoan</code>.</p> <p>The <code>flashLoan</code> function MUST include a <code>fee</code> argument to <code>onFlashLoan</code> with the fee to pay for the loan on top of the principal, ensuring that <code>fee == flashFee(token, amount)</code>.</p> <p>The <code>lender</code> MUST verify that the <code>onFlashLoan</code> callback returns the keccak256 hash of "ERC3156FlashBorrower.onFlashLoan".</p> <p>After the callback, the <code>flashLoan</code> function MUST take the <code>amount + fee</code> <code>token</code> from the <code>receiver</code>, or revert if this is not successful.</p> <p>If successful, <code>flashLoan</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 IERC3156FlashBorrower 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 IERC3156FlashBorrower {</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 token The loan currency.</span></span> <span class="giallo-l"><span> * @param amount The amount of tokens lent.</span></span> <span class="giallo-l"><span> * @param fee 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;ERC3156FlashBorrower.onFlashLoan&quot;</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function onFlashLoan(</span></span> <span class="giallo-l"><span> address initiator,</span></span> <span class="giallo-l"><span> address token,</span></span> <span class="giallo-l"><span> uint256 amount,</span></span> <span class="giallo-l"><span> uint256 fee,</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, <code>receiver</code> MUST approve <code>amount + fee</code> of <code>token</code> to be taken by <code>msg.sender</code> before the end of <code>onFlashLoan</code>.</p> <p>If successful, <code>onFlashLoan</code> MUST return the keccak256 hash of "ERC3156FlashBorrower.onFlashLoan".</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>flashLoan</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 lent 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 all provide flash loans of several token types from the same contract. Providing a <code>token</code> parameter in both the <code>flashLoan</code> and <code>onFlashLoan</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>flashLoan</code> standard.</p> <p><code>onFlashLoan</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>A <code>initiator</code> will often be required in the <code>onFlashLoan</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>amount</code> will be required in the <code>onFlashLoan</code> function, which the lender took as a parameter. An alternative implementation which would embed the <code>amount</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>A <code>fee</code> will often be calculated in the <code>flashLoan</code> function, which the <code>receiver</code> must be aware of for repayment. Passing the <code>fee</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="backwards-compatibility">Backwards Compatibility</h2> <p>No backwards compatibility issues identified.</p> <h2 id="implementation">Implementation</h2> <h3 id="flash-borrower-reference-implementation">Flash Borrower Reference Implementation</h3> <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;./interfaces/IERC20.sol&quot;;</span></span> <span class="giallo-l"><span>import &quot;./interfaces/IERC3156FlashBorrower.sol&quot;;</span></span> <span class="giallo-l"><span>import &quot;./interfaces/IERC3156FlashLender.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>contract FlashBorrower is IERC3156FlashBorrower {</span></span> <span class="giallo-l"><span> enum Action {NORMAL, OTHER}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> IERC3156FlashLender lender;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> constructor (</span></span> <span class="giallo-l"><span> IERC3156FlashLender lender_</span></span> <span class="giallo-l"><span> ) {</span></span> <span class="giallo-l"><span> lender = lender_;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @dev ERC-3156 Flash loan callback</span></span> <span class="giallo-l"><span> function onFlashLoan(</span></span> <span class="giallo-l"><span> address initiator,</span></span> <span class="giallo-l"><span> address token,</span></span> <span class="giallo-l"><span> uint256 amount,</span></span> <span class="giallo-l"><span> uint256 fee,</span></span> <span class="giallo-l"><span> bytes calldata data</span></span> <span class="giallo-l"><span> ) external override returns(bytes32) {</span></span> <span class="giallo-l"><span> require(</span></span> <span class="giallo-l"><span> msg.sender == address(lender),</span></span> <span class="giallo-l"><span> &quot;FlashBorrower: Untrusted lender&quot;</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span> require(</span></span> <span class="giallo-l"><span> initiator == address(this),</span></span> <span class="giallo-l"><span> &quot;FlashBorrower: Untrusted loan initiator&quot;</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span> (Action action) = abi.decode(data, (Action));</span></span> <span class="giallo-l"><span> if (action == Action.NORMAL) {</span></span> <span class="giallo-l"><span> // do one thing</span></span> <span class="giallo-l"><span> } else if (action == Action.OTHER) {</span></span> <span class="giallo-l"><span> // do another</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> return keccak256(&quot;ERC3156FlashBorrower.onFlashLoan&quot;);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @dev Initiate a flash loan</span></span> <span class="giallo-l"><span> function flashBorrow(</span></span> <span class="giallo-l"><span> address token,</span></span> <span class="giallo-l"><span> uint256 amount</span></span> <span class="giallo-l"><span> ) public {</span></span> <span class="giallo-l"><span> bytes memory data = abi.encode(Action.NORMAL);</span></span> <span class="giallo-l"><span> uint256 _allowance = IERC20(token).allowance(address(this), address(lender));</span></span> <span class="giallo-l"><span> uint256 _fee = lender.flashFee(token, amount);</span></span> <span class="giallo-l"><span> uint256 _repayment = amount + _fee;</span></span> <span class="giallo-l"><span> IERC20(token).approve(address(lender), _allowance + _repayment);</span></span> <span class="giallo-l"><span> lender.flashLoan(this, token, amount, data);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="flash-mint-reference-implementation">Flash Mint Reference Implementation</h3> <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;../ERC20.sol&quot;;</span></span> <span class="giallo-l"><span>import &quot;../interfaces/IERC20.sol&quot;;</span></span> <span class="giallo-l"><span>import &quot;../interfaces/IERC3156FlashBorrower.sol&quot;;</span></span> <span class="giallo-l"><span>import &quot;../interfaces/IERC3156FlashLender.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * @author Alberto Cuesta Cañada</span></span> <span class="giallo-l"><span> * @dev Extension of {ERC20} that allows flash minting.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>contract FlashMinter is ERC20, IERC3156FlashLender {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> bytes32 public constant CALLBACK_SUCCESS = keccak256(&quot;ERC3156FlashBorrower.onFlashLoan&quot;);</span></span> <span class="giallo-l"><span> uint256 public fee; // 1 == 0.01 %.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @param fee_ The percentage of the loan `amount` that needs to be repaid, in addition to `amount`.</span></span> <span class="giallo-l"><span> */</span></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> uint256 fee_</span></span> <span class="giallo-l"><span> ) ERC20(name, symbol) {</span></span> <span class="giallo-l"><span> fee = fee_;</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> * @dev The amount of currency available to be lent.</span></span> <span class="giallo-l"><span> * @param token The loan currency.</span></span> <span class="giallo-l"><span> * @return The amount of `token` that can be borrowed.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function maxFlashLoan(</span></span> <span class="giallo-l"><span> address token</span></span> <span class="giallo-l"><span> ) external view override returns (uint256) {</span></span> <span class="giallo-l"><span> return type(uint256).max - totalSupply();</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> * @dev The fee to be charged for a given loan.</span></span> <span class="giallo-l"><span> * @param token The loan currency. Must match the address of this contract.</span></span> <span class="giallo-l"><span> * @param amount The amount of tokens lent.</span></span> <span class="giallo-l"><span> * @return The amount of `token` to be charged for the 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 token,</span></span> <span class="giallo-l"><span> uint256 amount</span></span> <span class="giallo-l"><span> ) external view override returns (uint256) {</span></span> <span class="giallo-l"><span> require(</span></span> <span class="giallo-l"><span> token == address(this),</span></span> <span class="giallo-l"><span> &quot;FlashMinter: Unsupported currency&quot;</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span> return _flashFee(token, amount);</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> * @dev Loan `amount` tokens to `receiver`, and takes it back plus a `flashFee` after the ERC3156 callback.</span></span> <span class="giallo-l"><span> * @param receiver The contract receiving the tokens, needs to implement the `onFlashLoan(address user, uint256 amount, uint256 fee, bytes calldata)` interface.</span></span> <span class="giallo-l"><span> * @param token The loan currency. Must match the address of this contract.</span></span> <span class="giallo-l"><span> * @param amount The amount of tokens lent.</span></span> <span class="giallo-l"><span> * @param data A data parameter to be passed on to the `receiver` for any custom use.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function flashLoan(</span></span> <span class="giallo-l"><span> IERC3156FlashBorrower receiver,</span></span> <span class="giallo-l"><span> address token,</span></span> <span class="giallo-l"><span> uint256 amount,</span></span> <span class="giallo-l"><span> bytes calldata data</span></span> <span class="giallo-l"><span> ) external override returns (bool){</span></span> <span class="giallo-l"><span> require(</span></span> <span class="giallo-l"><span> token == address(this),</span></span> <span class="giallo-l"><span> &quot;FlashMinter: Unsupported currency&quot;</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span> uint256 fee = _flashFee(token, amount);</span></span> <span class="giallo-l"><span> _mint(address(receiver), amount);</span></span> <span class="giallo-l"><span> require(</span></span> <span class="giallo-l"><span> receiver.onFlashLoan(msg.sender, token, amount, fee, data) == CALLBACK_SUCCESS,</span></span> <span class="giallo-l"><span> &quot;FlashMinter: Callback failed&quot;</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span> uint256 _allowance = allowance(address(receiver), address(this));</span></span> <span class="giallo-l"><span> require(</span></span> <span class="giallo-l"><span> _allowance &gt;= (amount + fee),</span></span> <span class="giallo-l"><span> &quot;FlashMinter: Repay not approved&quot;</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span> _approve(address(receiver), address(this), _allowance - (amount + fee));</span></span> <span class="giallo-l"><span> _burn(address(receiver), amount + fee);</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> /**</span></span> <span class="giallo-l"><span> * @dev The fee to be charged for a given loan. Internal function with no checks.</span></span> <span class="giallo-l"><span> * @param token The loan currency.</span></span> <span class="giallo-l"><span> * @param amount The amount of tokens lent.</span></span> <span class="giallo-l"><span> * @return The amount of `token` to be charged for the 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 token,</span></span> <span class="giallo-l"><span> uint256 amount</span></span> <span class="giallo-l"><span> ) internal view returns (uint256) {</span></span> <span class="giallo-l"><span> return amount * fee / 10000;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="flash-loan-reference-implementation">Flash Loan Reference Implementation</h3> <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;../interfaces/IERC20.sol&quot;;</span></span> <span class="giallo-l"><span>import &quot;../interfaces/IERC3156FlashBorrower.sol&quot;;</span></span> <span class="giallo-l"><span>import &quot;../interfaces/IERC3156FlashLender.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * @author Alberto Cuesta Cañada</span></span> <span class="giallo-l"><span> * @dev Extension of {ERC20} that allows flash lending.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>contract FlashLender is IERC3156FlashLender {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> bytes32 public constant CALLBACK_SUCCESS = keccak256(&quot;ERC3156FlashBorrower.onFlashLoan&quot;);</span></span> <span class="giallo-l"><span> mapping(address =&gt; bool) public supportedTokens;</span></span> <span class="giallo-l"><span> uint256 public fee; // 1 == 0.01 %.</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @param supportedTokens_ Token contracts supported for flash lending.</span></span> <span class="giallo-l"><span> * @param fee_ The percentage of the loan `amount` that needs to be repaid, in addition to `amount`.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> constructor(</span></span> <span class="giallo-l"><span> address[] memory supportedTokens_,</span></span> <span class="giallo-l"><span> uint256 fee_</span></span> <span class="giallo-l"><span> ) {</span></span> <span class="giallo-l"><span> for (uint256 i = 0; i &lt; supportedTokens_.length; i++) {</span></span> <span class="giallo-l"><span> supportedTokens[supportedTokens_[i]] = true;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> fee = fee_;</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> * @dev Loan `amount` tokens to `receiver`, and takes it back plus a `flashFee` after the callback.</span></span> <span class="giallo-l"><span> * @param receiver The contract receiving the tokens, needs to implement the `onFlashLoan(address user, uint256 amount, uint256 fee, bytes calldata)` interface.</span></span> <span class="giallo-l"><span> * @param token The loan currency.</span></span> <span class="giallo-l"><span> * @param amount The amount of tokens lent.</span></span> <span class="giallo-l"><span> * @param data A data parameter to be passed on to the `receiver` for any custom use.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function flashLoan(</span></span> <span class="giallo-l"><span> IERC3156FlashBorrower receiver,</span></span> <span class="giallo-l"><span> address token,</span></span> <span class="giallo-l"><span> uint256 amount,</span></span> <span class="giallo-l"><span> bytes calldata data</span></span> <span class="giallo-l"><span> ) external override returns(bool) {</span></span> <span class="giallo-l"><span> require(</span></span> <span class="giallo-l"><span> supportedTokens[token],</span></span> <span class="giallo-l"><span> &quot;FlashLender: Unsupported currency&quot;</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span> uint256 fee = _flashFee(token, amount);</span></span> <span class="giallo-l"><span> require(</span></span> <span class="giallo-l"><span> IERC20(token).transfer(address(receiver), amount),</span></span> <span class="giallo-l"><span> &quot;FlashLender: Transfer failed&quot;</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span> require(</span></span> <span class="giallo-l"><span> receiver.onFlashLoan(msg.sender, token, amount, fee, data) == CALLBACK_SUCCESS,</span></span> <span class="giallo-l"><span> &quot;FlashLender: Callback failed&quot;</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span> require(</span></span> <span class="giallo-l"><span> IERC20(token).transferFrom(address(receiver), address(this), amount + fee),</span></span> <span class="giallo-l"><span> &quot;FlashLender: Repay failed&quot;</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> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev The fee to be charged for a given loan.</span></span> <span class="giallo-l"><span> * @param token The loan currency.</span></span> <span class="giallo-l"><span> * @param amount The amount of tokens lent.</span></span> <span class="giallo-l"><span> * @return The amount of `token` to be charged for the 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 token,</span></span> <span class="giallo-l"><span> uint256 amount</span></span> <span class="giallo-l"><span> ) external view override returns (uint256) {</span></span> <span class="giallo-l"><span> require(</span></span> <span class="giallo-l"><span> supportedTokens[token],</span></span> <span class="giallo-l"><span> &quot;FlashLender: Unsupported currency&quot;</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span> return _flashFee(token, amount);</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> * @dev The fee to be charged for a given loan. Internal function with no checks.</span></span> <span class="giallo-l"><span> * @param token The loan currency.</span></span> <span class="giallo-l"><span> * @param amount The amount of tokens lent.</span></span> <span class="giallo-l"><span> * @return The amount of `token` to be charged for the 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 token,</span></span> <span class="giallo-l"><span> uint256 amount</span></span> <span class="giallo-l"><span> ) internal view returns (uint256) {</span></span> <span class="giallo-l"><span> return amount * fee / 10000;</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> * @dev The amount of currency available to be lent.</span></span> <span class="giallo-l"><span> * @param token The loan currency.</span></span> <span class="giallo-l"><span> * @return The amount of `token` that can be borrowed.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function maxFlashLoan(</span></span> <span class="giallo-l"><span> address token</span></span> <span class="giallo-l"><span> ) external view override returns (uint256) {</span></span> <span class="giallo-l"><span> return supportedTokens[token] ? IERC20(token).balanceOf(address(this)) : 0;</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> <h3 id="verification-of-callback-arguments">Verification of callback arguments</h3> <p>The arguments of <code>onFlashLoan</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>token</code> and <code>amount</code> refer to a past transaction that might not have happened if the caller of <code>onFlashLoan</code> decides to lie. <code>fee</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>token</code>, <code>amount</code> and <code>fee</code> are genuine a reasonable pattern is to verify that the <code>onFlashLoan</code> caller is in a whitelist of verified flash lenders. Since often the caller of <code>flashLoan</code> will also be receiving the <code>onFlashLoan</code> callback this will be trivial. In all other cases flash lenders will need to be approved if the arguments in <code>onFlashLoan</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 to verify that the <code>initiator</code> belongs to a group 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">Automatic approvals</h4> <p>The safest approach is to implement an approval for <code>amount+fee</code> before the <code>flashLoan</code> is executed.</p> <p>Any <code>receiver</code> that keeps an approval for a given <code>lender</code> needs to include in <code>onFlashLoan</code> a mechanism to verify that the initiator is trusted.</p> <p>Any <code>receiver</code> that includes in <code>onFlashLoan</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 initiator is trusted.</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>onFlashLoan</code>, then the unsuspecting contract or EOA could be drained of funds up to their allowance or balance limit. This would be executed by an <code>initiator</code> calling <code>flashLoan</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>onFlashLoan</code> doesn't return the keccak256 hash for "ERC3156FlashBorrower.onFlashLoan".</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 STAB</li> <li>Deposit the 1 quintillion STAB + $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 STAB on 0.00001% stable interest rate based on the 1.5M ETH collateral</li> <li>Withdraw and burn the 1 quint STAB to close the original flash mint</li> <li>You now have a 1 million STAB 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, either by using a compiler that embeds overflow protection in the smart contract bytecode, or by setting explicit checks.</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>Assume a smart contract that flash lends its native token. The same smart contract borrows from a third party when users burn the native token. This pattern would be used to aggregate in the smart contract the collateralized debt of several users into a single account in the third party. The flash mint could be used to cause the lender to borrow to its limit, and then pushing interest rates in the underlying lender, liquidate the flash lender:</p> <ol> <li>Flash mint from <code>lender</code> a very large amount of FOO.</li> <li>Redeem FOO for BAR, causing <code>lender</code> to borrow from <code>underwriter</code> all the way to its borrowing limit.</li> <li>Trigger a debt rate increase in <code>underwriter</code>, making <code>lender</code> undercollateralized.</li> <li>Liquidate the <code>lender</code> for profit.</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> 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-27T00:00:00+00:00 2026-02-11T14:49:28+00:00 Michael Sproulhttps://github.com/michaelsproul Sacha Saint-Legerhttps://github.com/sachayves Danny Ryanhttps://github.com/djrtwo https://wg-eips.ritovision.com/3076/

A JSON interchange format for proof of stake validators to migrate slashing protection data between clients.

<h2 id="abstract">Abstract</h2> <p>A standard format for transferring a key's signing history allows validators to easily switch between clients without the risk of signing conflicting messages. While a common keystore format provides part of the solution, it does not contain any information about a key's signing history. For a validator moving their keys from client A to client B, this could lead to scenarios in which client B inadvertently signs a message that conflicts with an earlier message signed with client A. The interchange format described here provides a solution to this problem.</p> <h2 id="motivation">Motivation</h2> <p>The proof of stake (PoS) protocol penalises validators for voting in ways that could result in two different versions of the chain being finalised. These types of penalties are called slashings.</p> <p>For a validator following the protocol correctly, there is, in principle, no risk of being slashed. However, changing clients (from client A to client B, say) can result in a slashing risk if client B is unaware of the blocks and attestations that were signed with client A.</p> <p>This can occur if client A and client B do not agree on what the present time is. For example, say client A's time is accidentally set to a day in the future (225 epochs), and a validator switches from client A to client B without giving B a record of the blocks and attestations signed with A. The validator in question now runs the risk of attesting to two different blocks in the same epoch (a slashable offence) for the next 225 epochs (since they've already voted on these epochs with client A, and now stand to vote on them again with client B). Such time-skew bugs have been observed in the wild.</p> <p>Another situation in which slashing protection is critical is in the case of re-orgs. During a re-org it is possible for a validator to be assigned new attestation duties for an epoch in which it has already signed an attestation. In this case it is essential that the record of the previous attestation is available, even if the validator just moved from one client to another in the space of a single epoch.</p> <h2 id="specification">Specification</h2> <h3 id="json-schema">JSON Schema</h3> <p>A valid interchange file is one that adheres to the following JSON schema, and is interpreted according to the <a href="https://wg-eips.ritovision.com/3076/#conditions">Conditions</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Signing history</span><span class="z-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">This schema provides a record of the blocks and attestations signed by a set of validators</span><span class="z-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">metadata</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">interchange_format_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">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 version of the interchange format that this document adheres to</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">genesis_validators_root</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">Calculated at Genesis time; serves to uniquely identify the chain</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">interchange_format_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">genesis_validators_root</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">data</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> {</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">pubkey</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 BLS public key of the validator (encoded as a 0x-prefixed hex 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">signed_blocks</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> {</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">slot</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 slot number of the block that was signed</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">signing_root</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 output of compute_signing_root(block, domain)</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">slot</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">signed_attestations</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> {</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">source_epoch</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 attestation.data.source.epoch of the signed attestation</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">target_epoch</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 attestation.data.target.epoch of the signed attestation</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">signing_root</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 output of compute_signing_root(attestation, domain)</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">source_epoch</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">target_epoch</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">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">pubkey</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">signed_blocks</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">signed_attestations</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">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">metadata</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 class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="example-json-instance">Example JSON Instance</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">metadata</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">interchange_format_version</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">genesis_validators_root</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x04700007fabc8282644aed6d1c7c9e21d38a03a0c4ba193f3afe428824b3a673</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">data</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">pubkey</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xb845089a1457f811bfc000588fbb4e713669be8ce060ea6be3c6ece09afc3794106c91ca73acda5e5457122d58723bed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">signed_blocks</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">slot</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">81952</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">signing_root</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4ff6f743a43f3b4f95350831aeaf0a122a1a392922c45d804280284a69eb850b</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">slot</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">81951</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">signed_attestations</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">source_epoch</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2290</span><span class="z-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_epoch</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">3007</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">signing_root</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x587d6a4f59a58fe24f406e0502413e77fe1babddee641fda30034ed37ecc884d</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">source_epoch</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2290</span><span class="z-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_epoch</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">3008</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="conditions">Conditions</h3> <p>After importing an interchange file with data field <code>data</code>, a signer must respect the following conditions:</p> <ol> <li> <p>Refuse to sign any block that is slashable with respect to the blocks contained in <code>data.signed_blocks</code>. For details of what constitutes a slashable block, see <code>process_proposer_slashing</code> (from <code>consensus-specs</code>). If the <code>signing_root</code> is absent from a block, a signer must assume that any new block with the same <code>slot</code> is slashable with respect to the imported block.</p> </li> <li> <p>Refuse to sign any block with <code>slot &lt;= min(b.slot for b in data.signed_blocks if b.pubkey == proposer_pubkey)</code>, except if it is a repeat signing as determined by the <code>signing_root</code>.</p> </li> <li> <p>Refuse to sign any attestation that is slashable with respect to the attestations contained in <code>data.signed_attestations</code>. For details of what constitutes a slashable attestation, see <code>is_slashable_attestation_data</code>.</p> </li> <li> <p>Refuse to sign any attestation with source epoch less than the minimum source epoch present in that signer's attestations (as seen in <code>data.signed_attestations</code>). In pseudocode:</p> </li> </ol> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>source</span><span>.</span><span>epoch</span><span class="z-keyword"> &lt;</span></span> <span class="giallo-l"><span class="z-support"> min</span><span>(</span><span>att</span><span>.</span><span>source_epoch</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> att</span><span class="z-keyword"> in</span><span> data</span><span>.</span><span>signed_attestations</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> att</span><span>.</span><span>pubkey</span><span class="z-keyword"> ==</span><span> attester_pubkey</span><span>)</span></span></code></pre> <p>{:start="5"} 5. Refuse to sign any attestation with target epoch less than or equal to the minimum target epoch present in that signer's attestations (as seen in <code>data.signed_attestations</code>), except if it is a repeat signing as determined by the <code>signing_root</code>. In pseudocode:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>target_epoch</span><span class="z-keyword"> &lt;=</span></span> <span class="giallo-l"><span class="z-support"> min</span><span>(</span><span>att</span><span>.</span><span>target_epoch</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> att</span><span class="z-keyword"> in</span><span> data</span><span>.</span><span>signed_attestations</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> att</span><span>.</span><span>pubkey</span><span class="z-keyword"> ==</span><span> attester_pubkey</span><span>)</span></span></code></pre><h3 id="additional-information">Additional Information</h3> <ul> <li> <p>The <code>interchange_format_version</code> version is set to 5.</p> </li> <li> <p>A signed block or attestation's <code>signing_root</code> refers to the message data (hash tree root) that gets signed with a BLS signature. It allows validators to re-sign and re-broadcast blocks or attestations if asked.</p> </li> <li> <p>The <code>signed_blocks</code> <code>signing_root</code>s are calculated using <code>compute_signing_root(block, domain)</code>: where <code>block</code> is the block (of type <code>BeaconBlock</code> or <code>BeaconBlockHeader</code>) that was signed, and <code>domain</code> is equal to <code>compute_domain(DOMAIN_BEACON_PROPOSER, fork, metadata.genesis_validators_root)</code>.</p> </li> <li> <p>The <code>signed_attestations</code> <code>signing_root</code>s are calculated using <code>compute_signing_root(attestation, domain)</code>: where <code>attestation</code> is the attestation (of type <code>AttestationData</code>) that was signed, and <code>domain</code> is equal to <code>compute_domain(DOMAIN_BEACON_ATTESTER, fork, metadata.genesis_validators_root)</code>.</p> </li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="supporting-different-strategies">Supporting Different Strategies</h3> <p>The interchange format is designed to be flexible enough to support the full variety of slashing protection strategies that clients may implement, which may be categorised into two main types:</p> <ol> <li><strong>Complete</strong>: a database containing every message signed by each validator.</li> <li><strong>Minimal</strong>: a database containing only the latest messages signed by each validator.</li> </ol> <p>The advantage of the minimal strategy is its simplicity and succinctness. Using only the latest messages for each validator, safe slashing protection can be achieved by refusing to sign messages for slots or epochs prior.</p> <p>On the other hand, the complete strategy can provide safe slashing protection while also avoiding false positives (meaning that it only prevents a validator from signing if doing so would guarantee a slashing).</p> <p>The two strategies are unified in the interchange format through the inclusion of <a href="https://wg-eips.ritovision.com/3076/#conditions">conditions</a> (2), (4) and (5). This allows the interchange to transfer detailed or succinct information, as desired.</p> <h3 id="integer-representation">Integer Representation</h3> <p>Most fields in the JSON schema are strings. For fields in which it is possible to encode the value as either a string or an integer, strings were chosen. This choice was made in order to avoid issues with different languages supporting different ranges of integers (specifically JavaScript, where the <code>number</code> type is a 64-bit float). If a validator is yet to sign a block or attestation, the relevant list is simply left empty.</p> <h3 id="versioning">Versioning</h3> <p>The <code>interchange_format_version</code> is set to 5 because the specification went through several breaking changes during its design, incorporating feedback from implementers.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This specification is not backwards-compatible with previous draft versions that used version numbers less than 5.</p> <h2 id="security-considerations">Security Considerations</h2> <p>In order to minimise risk and complexity, the format has been designed to map cleanly onto the internal database formats used by implementers. Nevertheless, there are a few pitfalls worth illuminating.</p> <h3 id="advice-for-complete-databases">Advice for Complete Databases</h3> <p>For implementers who use a complete record of signed messages to implement their slashing protection database, we make the following recommendations:</p> <ul> <li>You MUST ensure that, in addition to importing all of the messages from an interchange, all the <a href="https://wg-eips.ritovision.com/3076/#conditions">conditions</a> are enforced. In particular, conditions (2), (4) and (5) may not have been enforced by your implementation before adopting the interchange format. Our recommendation is to enforce these rules at all times, to keep the implementation clean and minimise the attack surface. For example: your slashing protection mechanism should not sign a block with a slot number less than, or equal to, the minimum slot number of a previously signed block, <em>irrespective</em> of whether that minimum-slot block was imported from an interchange file, or inserted as part of your database's regular operation.</li> <li>If your database records the signing roots of messages in addition to their slot/epochs, you should ensure that imported messages without signing roots are assigned a suitable dummy signing root internally. We suggest using a special "null" value which is distinct from all other signing roots, although a value like <code>0x0</code> may be used instead (as it is extremely unlikely to collide with any real signing root).</li> <li>Care must be taken to avoid signing messages within a gap in the database (an area of unknown signing activity). This could occur if two interchanges were imported with a large gap between the last entry of the first and the first entry of the second. Signing in this gap is not safe, and would violate conditions (2), (4) and (5). It can be avoided by storing an explicit low watermark in addition to the actual messages of the slashing protection database, or by pruning on import so that the oldest messages from the interchange become the oldest messages in the database.</li> </ul> <h3 id="advice-for-minimal-databases">Advice for Minimal Databases</h3> <p>For implementers who wish to implement their slashing protection database by storing only the latest block and attestation for each validator, we make the following recommendations:</p> <ul> <li>During import, make sure you take the <em>maximum</em> slot block and <em>maximum</em> source and target attestations for each validator. Although the <a href="https://wg-eips.ritovision.com/3076/#conditions">conditions</a> require the minimums to be enforced, taking the maximums from an interchange file and merging them with any existing values in the database is the recommended approach. For example, if the interchange file includes blocks for validator <code>V</code> at slots 4, 98 and 243, then the latest signed block for validator <code>V</code> should be updated to the one from slot 243. However, if the database has already included a block for this validator at a slot greater than 243, for example, slot 351, then the database's existing value should remain unchanged.</li> </ul> <h3 id="general-recommendations">General Recommendations</h3> <ul> <li>To avoid exporting an outdated interchange file -- an action which creates a slashing risk -- your implementation should only allow the slashing protection database to be exported when the validator client or signer is <em>stopped</em> -- in other words, when the client or signer is no longer adding new messages to the database.</li> <li>Similarly, your implementation should only allow an interchange file to be imported when the validator client is stopped.</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-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-15T00:00:00+00:00 2026-02-11T14:49:28+00:00 Sam Wilsonhttps://github.com/SamWilsn Ansgar Dietrichshttps://github.com/adietrichs Matt Garnetthttps://github.com/lightclient Micah Zoltuhttps://github.com/micahzoltu https://wg-eips.ritovision.com/3074/

Allow externally owned accounts to delegate control to a contract.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces two EVM instructions <code>AUTH</code> and <code>AUTHCALL</code>. The first sets a context variable <code>authorized</code> based on an ECDSA signature. The second sends a call as the <code>authorized</code> account. This essentially delegates control of the externally owned account (EOA) to a smart contract.</p> <h2 id="motivation">Motivation</h2> <p>Adding more functionality to EOAs has been a long-standing feature request. The requests have spanned from implementing batching capabilities, allowing for gas sponsoring, expirations, scripting, and beyond. These changes often mean increased complexity and rigidity of the protocol. In some cases, it also means increased attack surfaces.</p> <p>This EIP takes a different approach. Instead of enshrining these capabilities in the protocol as transaction validity requirements, it allows users to <em>delegate</em> control of their EOA to a contract. This gives developers a flexible framework for developing novel transaction schemes for EOAs. A motivating use case of this EIP is that it allows any EOA to act like a smart contract wallet <em>without</em> deploying a contract.</p> <p>Although this EIP provides great benefit to individual users, the leading motivation for this EIP is "sponsored transactions". This is where the fee for a transaction is provided by a different account than the one that originates the call.</p> <p>With the extraordinary growth of tokens on Ethereum, it has become common for EOAs to hold valuable assets without holding any ether at all. Today, these assets must be converted to ether before they can be used to pay gas fees. However, without ether to pay for the conversion, it's impossible to convert them. Sponsored transactions break the circular dependency.</p> <h2 id="specification">Specification</h2> <h3 id="conventions">Conventions</h3> <ul> <li><strong><code>top - N</code></strong> - the <code>N</code>th most recently pushed value on the EVM stack, where <code>top - 0</code> is the most recent.</li> <li><strong><code>||</code></strong> - byte concatenation operator.</li> <li><strong>invalid execution</strong> - execution that is invalid and must exit the current execution frame immediately, consuming all remaining gas (in the same way as a stack underflow or invalid jump).</li> </ul> <h3 id="constants">Constants</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>MAGIC</code></td><td><code>0x04</code></td></tr> </tbody></table> <p><code>MAGIC</code> is used for <a href="https://wg-eips.ritovision.com/3074/">EIP-3074</a> signatures to prevent signature collisions with other signing formats.</p> <h3 id="context-variables">Context Variables</h3> <table><thead><tr><th>Variable</th><th>Type</th><th style="text-align: left">Initial Value</th></tr></thead><tbody> <tr><td><code>authorized</code></td><td><code>address</code></td><td style="text-align: left">unset</td></tr> </tbody></table> <p>The context variable <code>authorized</code> shall indicate the active account for <code>AUTHCALL</code> instructions in the current frame of execution. If set, <code>authorized</code> shall only contain an account which has given the contract authorization to act on its behalf. An unset value shall indicate that no such account is set and that there is not yet an active account for <code>AUTHCALL</code> instructions in the current frame of execution.</p> <p>The variable has the same scope as the program counter -- <code>authorized</code> persists throughout a single frame of execution of the contract, but is not passed through any calls (including <code>DELEGATECALL</code>). If the same contract is being executed in separate execution frames (ex. a <code>CALL</code> to self), both frames shall have independent values for <code>authorized</code>. Initially in each frame of execution, <code>authorized</code> is always unset, even if a previous execution frame for the same contract has a value.</p> <h3 id="auth-0xf6"><code>AUTH</code> (<code>0xf6</code>)</h3> <p>A new opcode <code>AUTH</code> shall be created at <code>0xf6</code>. It shall take three stack element inputs (the last two describing a memory range), and it shall return one stack element.</p> <h4 id="input">Input</h4> <h5 id="stack">Stack</h5> <table><thead><tr><th>Stack</th><th>Value</th></tr></thead><tbody> <tr><td><code>top - 0</code></td><td><code>authority</code></td></tr> <tr><td><code>top - 1</code></td><td><code>offset</code></td></tr> <tr><td><code>top - 2</code></td><td><code>length</code></td></tr> </tbody></table> <h5 id="memory">Memory</h5> <p>The final two stack arguments (<code>offset</code> and <code>length</code>) describe a range of memory. The format of the contents of that range is:</p> <ul> <li><code>memory[offset : offset+1 ]</code> - <code>yParity</code></li> <li><code>memory[offset+1 : offset+33]</code> - <code>r</code></li> <li><code>memory[offset+33 : offset+65]</code> - <code>s</code></li> <li><code>memory[offset+65 : offset+97]</code> - <code>commit</code></li> </ul> <h4 id="output">Output</h4> <h5 id="stack-1">Stack</h5> <table><thead><tr><th>Stack</th><th>Value</th></tr></thead><tbody> <tr><td><code>top - 0</code></td><td><code>success</code></td></tr> </tbody></table> <h5 id="memory-1">Memory</h5> <p>Memory is not modified by this instruction.</p> <h4 id="behavior">Behavior</h4> <p>If <code>length</code> is greater than 97, the extra bytes are ignored for signature verification (they still incur a gas cost as defined later). Bytes outside the range (in the event <code>length</code> is less than 97) are treated as if they had been zeroes.</p> <p><code>authority</code> is the address of the account which generated the signature. If <code>EXTCODESIZE</code> of <code>authority</code> is not zero, consider the operation unsuccessful and unset <code>authorized</code>.</p> <p>The arguments (<code>yParity</code>, <code>r</code>, <code>s</code>) are interpreted as an ECDSA signature on the secp256k1 curve over the message <code>keccak256(MAGIC || chainId || nonce || invokerAddress || commit)</code>, where:</p> <ul> <li><code>chainId</code> is the current chain's <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> unique identifier padded to 32 bytes.</li> <li><code>nonce</code> is the signer's current nonce, left-padded to 32 bytes.</li> <li><code>invokerAddress</code> is the address of the contract executing <code>AUTH</code> (or the active state address in the context of <code>CALLCODE</code> or <code>DELEGATECALL</code>), left-padded with zeroes to a total of 32 bytes (ex. <code>0x000000000000000000000000AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA</code>).</li> <li><code>commit</code>, one of the arguments passed into <code>AUTH</code>, is a 32-byte value that can be used to commit to specific additional validity conditions in the invoker's pre-processing logic.</li> </ul> <p>Signature validity and signer recovery are handled analogously to transaction signatures, including the stricter <code>s</code> range for preventing ECDSA malleability. Note that <code>yParity</code> is expected to be <code>0</code> or <code>1</code>.</p> <p>If the signature is valid and the signer address is equal to <code>authority</code>, the context variable <code>authorized</code> is set to the <code>authority</code>. In particular, this is also true if <code>authority == tx.origin</code>, which used to be handled separately in earlier versions of this EIP (see Security Considerations). If the signature is instead invalid or the signer address does not equal <code>authority</code>, <code>authorized</code> is reset to an unset value.</p> <p><code>AUTH</code> returns <code>1</code> if <code>authorized</code> is set, or <code>0</code> otherwise.</p> <h4 id="gas-cost">Gas Cost</h4> <p>The gas cost for <code>AUTH</code> is equal to the sum of:</p> <ul> <li>fixed fee <code>3100</code>.</li> <li>memory expansion gas cost (<code>auth_memory_expansion_fee</code>).</li> <li><code>100</code> if <code>authority</code> is warm, <code>2600</code> if it is cold (per <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>).</li> </ul> <p>The fixed fee is equal to the cost for the <code>ecrecover</code> precompile, plus a bit extra to cover a keccak256 hash and some additional logic.</p> <p>The memory expansion gas cost (<code>auth_memory_expansion_fee</code>) shall be calculated in the same way as <code>RETURN</code>, where memory is expanded if the specified range is outside the current allocation.</p> <h3 id="authcall-0xf7"><code>AUTHCALL</code> (<code>0xf7</code>)</h3> <p>A new opcode <code>AUTHCALL</code> shall be created at <code>0xf7</code>. It shall take seven stack elements and return one stack element. It matches the behavior of the existing <code>CALL</code> (<code>0xF1</code>) instruction, except where noted below.</p> <h4 id="input-1">Input</h4> <table><thead><tr><th>Stack</th><th>Value</th></tr></thead><tbody> <tr><td><code>top - 0</code></td><td><code>gas</code></td></tr> <tr><td><code>top - 1</code></td><td><code>addr</code></td></tr> <tr><td><code>top - 2</code></td><td><code>value</code></td></tr> <tr><td><code>top - 3</code></td><td><code>argsOffset</code></td></tr> <tr><td><code>top - 4</code></td><td><code>argsLength</code></td></tr> <tr><td><code>top - 5</code></td><td><code>retOffset</code></td></tr> <tr><td><code>top - 6</code></td><td><code>retLength</code></td></tr> </tbody></table> <h4 id="output-1">Output</h4> <table><thead><tr><th>Stack</th><th>Value</th></tr></thead><tbody> <tr><td><code>top - 0</code></td><td><code>success</code></td></tr> </tbody></table> <h4 id="behavior-1">Behavior</h4> <p><code>AUTHCALL</code> is interpreted the same as <code>CALL</code>, except for (note: this list is also the order of precedence for the logical checks):</p> <ul> <li>If <code>authorized</code> is unset, execution is invalid (as defined above). Otherwise, the caller address for the call is set to <code>authorized</code>.</li> <li>The gas cost, including how much gas is available for the subcall, is specified in the Gas Cost section.</li> <li>If the <code>gas</code> operand is equal to <code>0</code>, the instruction will send all available gas as per <a href="https://wg-eips.ritovision.com/150/">EIP-150</a>.</li> <li>If the gas available for the subcall would be less than <code>gas</code>, execution is invalid.</li> <li>There is no gas stipend, even for non-zero <code>value</code>.</li> <li><code>value</code> is deducted from the balance of <code>authorized</code>. If <code>value</code> is higher than the balance of <code>authorized</code>, execution is invalid.</li> </ul> <p><code>AUTHCALL</code> must increase the call depth by one. <code>AUTHCALL</code> must not increase the call depth by two as it would if it first called into the authorized account and then into the target.</p> <p>The return data area accessed with <code>RETURNDATASIZE</code> (<code>0x3d</code>) and <code>RETURNDATACOPY</code> (<code>0x3e</code>) must be set in the same way as the <code>CALL</code> instruction.</p> <p>Importantly, <code>AUTHCALL</code> does not reset <code>authorized</code>, but leaves it unchanged.</p> <h4 id="gas-cost-1">Gas Cost</h4> <p>The gas cost for <code>AUTHCALL</code> shall be the <strong>sum</strong> of:</p> <ul> <li>static gas cost (<code>warm_storage_read</code>)</li> <li>memory expansion gas cost (<code>memory_expansion_fee</code>)</li> <li>dynamic gas cost (<code>dynamic_gas</code>)</li> <li>gas available for execution in the subcall (<code>subcall_gas</code>)</li> </ul> <p>The memory expansion gas cost (<code>memory_expansion_fee</code>) shall be calculated in the same way as <code>CALL</code>.</p> <p>The dynamic gas portion (<code>dynamic_gas</code>), and the gas available for execution in the subcall (<code>subcall_gas</code>) shall be calculated as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>dynamic_gas = 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>if addr not in accessed_addresses:</span></span> <span class="giallo-l"><span> dynamic_gas += 2500 # cold_account_access - warm_storage_read</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>if value &gt; 0:</span></span> <span class="giallo-l"><span> dynamic_gas += 6700 # NB: Not 9000, like in `CALL`</span></span> <span class="giallo-l"><span> if is_empty(addr):</span></span> <span class="giallo-l"><span> dynamic_gas += 25000</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>remaining_gas = available_gas - dynamic_gas</span></span> <span class="giallo-l"><span>all_but_one_64th = remaining_gas - (remaining_gas // 64)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>if gas == 0:</span></span> <span class="giallo-l"><span> subcall_gas = all_but_one_64th</span></span> <span class="giallo-l"><span>elif all_but_one_64th &lt; gas:</span></span> <span class="giallo-l"><span> raise # Execution is invalid.</span></span> <span class="giallo-l"><span>else:</span></span> <span class="giallo-l"><span> subcall_gas = gas</span></span></code></pre> <p>As with <code>CALL</code>, the full gas cost is charged immediately, independently of actually executing the call.</p> <h2 id="rationale">Rationale</h2> <h3 id="signature-in-memory">Signature in Memory</h3> <p>The signature format (<code>yParity</code>, <code>r</code>, and <code>s</code>) is fixed, so it might seem curious that <code>auth</code> accepts a dynamic memory range. The signature is placed in memory so that <code>auth</code> can be upgraded in the future to work with contract accounts (which might use non-ECDSA signatures) and not just EOAs.</p> <h3 id="signing-address-auth-argument">Signing Address <code>auth</code> Argument</h3> <p>Including <code>authority</code> (the signing address) as an argument to <code>auth</code> allows future upgrades to the instruction to work with contract accounts, and not just EOAs.</p> <p>If <code>authority</code> were not included and multiple signature schemes allowed, it would not be possible to compute the authorizing account's address from just the signature alone.</p> <h3 id="reserving-one-sixty-fourth-of-available-gas">Reserving One Sixty-Fourth of Available Gas</h3> <p><code>AUTHCALL</code> will not pass more than 63/64th of the available gas for the reasons enumerated in <a href="https://wg-eips.ritovision.com/150/">EIP-150</a>.</p> <h3 id="throwing-for-unset-authorized-during-authcall">Throwing for Unset <code>authorized</code> During <code>AUTHCALL</code></h3> <p>A well-behaved contract should never reach an <code>AUTHCALL</code> without having successfully set <code>authorized</code> beforehand. The safest behavior, therefore, is to exit the current frame of execution immediately. This is especially important in the context of transaction sponsoring / relaying, which is expected to be one of the main use cases for this EIP. In a sponsored transaction, the inability to distinguish between a sponsee-attributable fault (like a failing sub-call) and a sponsor-attributable fault (like a failing <code>AUTH</code>) is especially dangerous and should be prevented because it charges unfair fees to the sponsee.</p> <h3 id="another-sponsored-transaction-eip">Another Sponsored Transaction EIP</h3> <p>There are two general approaches to separating the "fee payer" from the "action originator".</p> <p>The first is introducing a new transaction type. This requires significant changes to clients to support and is generally less upgradeable than other solutions (e.g. this EIP). This approach is also not immediately compatible with account abstraction (AA). These proposals require a <em>signed</em> transaction from the sponsor's account, which is not possible from an AA contract, because it has no private key to sign with. The main advantage of new transaction types is that the validity requirements are enforced by the protocol, therefore invalid transactions do not pollute block space.</p> <p>The other main approach is to introduce a new mechanism in the EVM to masquerade as other accounts. This EIP introduces <code>AUTH</code> and <code>AUTHCALL</code> to make calls as EOAs. There are many different permutations of this mechanism. An alternative mechanism would be to add an opcode that can make arbitrary calls based on a similar address creation scheme as <code>CREATE2</code>. Although this mechanism would not benefit users today, it would immediately allow for those accounts to send and receive ether -- making it feel like a more first-class primitive.</p> <p>Besides better compatibility with AA, introducing a new mechanism into the EVM is a much less intrusive change than a new transaction type. This approach requires no changes in existing wallets, and little change in other tooling.</p> <p><code>AUTHCALL</code>'s single deviation from <code>CALL</code> is to set <code>CALLER</code>. It implements the minimal functionality to enable sender abstraction for sponsored transactions. This single mindedness makes <code>AUTHCALL</code> significantly more composable with existing Ethereum features.</p> <p>More logic can be implemented around the <code>AUTHCALL</code> instruction, giving more control to invokers and sponsors without sacrificing security or user experience for sponsees.</p> <h3 id="what-to-sign">What to Sign?</h3> <p>As originally written, this proposal specified a precompile with storage to track nonces. Since a precompile with storage is unprecedented, a revision moved replay protection into the invoker contract, necessitating a certain level of user trust in the invoker. Expanding on this idea of trusted invokers, the other signed fields were eventually eliminated, one by one, until only <code>invoker</code> and <code>commit</code> remained. To appease concerns about cross-chain replay attacks and irrevocable signatures, the <code>chainId</code> and <code>nonce</code> fields returned to the signed message.</p> <p>The <code>invoker</code> binds a particular signed message to a single invoker. If invoker was not part of the message, any invoker could reuse the signature to completely compromise the EOA. This allows users to trust that their message will be validated as they expect, particularly the values committed to in <code>commit</code>.</p> <h3 id="understanding-commit">Understanding <code>commit</code></h3> <p>Earlier iterations of this EIP included mechanisms for replay protection, and also signed over value, gas, and other arguments to <code>AUTHCALL</code>. After further investigation, we revised this EIP to its current state: explicitly delegate these responsibilities to the invoker contract.</p> <p>A user will specifically interact with an invoker they trust. Because they trust this contract to execute faithfully, they will "commit" to certain properties of a call they would like to make by computing a hash of the call values. They can be certain that the invoker will only allow the call to proceed if it is able to verify the values committed to (e.g. a nonce to protect against replay attacks). This certainty arises from the <code>commit</code> value that is signed over by the user. This is the hash of values which the invoker will validate. A safe invoker should accept the values from the user and compute the commit hash itself. This ensures that invoker operated on the same input that user authorized.</p> <p><img src="https://wg-eips.ritovision.com/3074/./assets/auth-msg.png" alt="auth message format" /></p> <p>Using <code>commit</code> as a hash of values allows for invokers to implement arbitrary constraints. For example, they could allow accounts to have <code>N</code> parallel nonces. Or, they could allow a user to commit to multiple calls with a single signature. This would allow multi-tx flows, such as <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> <code>approve</code>-<code>transfer</code> actions, to be condensed into a single transaction with a single signature verification. A commitment to multiple calls would look something like the diagram below.</p> <p><img src="https://wg-eips.ritovision.com/3074/./assets/auth-msg-multi-call.png" alt="multi-call auth message" /></p> <p>Another interesting use is to delegate control of the EOA to other key(s). This would mean the EOA signs a <code>commit</code> message with the address of the key(s) and an access policy, if applicable. When the delegate wants to make a call as the EOA it will construct a signature over the invoker-specified call format and relay it (with the actual call data) onto chain with the signature and commit that granted it access to the account. The invoker will then be able to determine that the EOA has allowed this alternative key to make calls on its behalf.</p> <p><img src="https://wg-eips.ritovision.com/3074/./assets/auth-msg-delegate.png" alt="delegate auth message" /></p> <h3 id="invoker-contracts">Invoker Contracts</h3> <p>The invoker contract is a trustless intermediary between the sponsor and sponsee. A sponsee signs over <code>invoker</code> to require the transaction to be processed only by a contract they trust. This allows them to interact with sponsors without needing to trust them.</p> <p>Choosing an invoker is similar to choosing a smart contract wallet implementation. It's important to choose one that has been thoroughly reviewed, tested, and accepted by the community as secure. We expect a few invoker designs to be utilized by most major transaction relay providers, with a few outliers that offer more novel mechanisms.</p> <p>An important note is that invoker contracts <strong>MUST NOT</strong> be upgradeable. If an invoker can be redeployed to the same address with different code, it would be possible to redeploy the invoker with code that does not properly verify <code>commit</code> and any account that signed a message over that invoker would be compromised. Although this sounds scary, it is no different than using a smart contract wallet via <code>DELEGATECALL</code>. If the wallet is redeployed with different logic, all wallets using its code could be compromised.</p> <h3 id="on-call-depth">On Call Depth</h3> <p>The EVM limits the maximum number of nested calls, and naively allowing a sponsor to manipulate the call depth before reaching the invoker would introduce a griefing attack against the sponsee. That said, with the 63/64th gas rule, and the cost of <code>AUTHCALL</code>, the stack is effectively limited to a much smaller depth than the hard maximum by the <code>gas</code> parameter.</p> <p>It is, therefore, sufficient for the invoker to guarantee a minimum amount of gas, because there is no way to reach the hard maximum call depth with any reasonable (i.e. less than billions) amount of gas.</p> <h3 id="source-of-value">Source of <code>value</code></h3> <p>In previous iterations of this EIP, it was thought that deducting value from an EOA mid-execution was problematic. This was due to an invariant of pending transactions which allows tx pools to statically determine the validity of a given transaction.</p> <p>However, after further investigation we found that breaking the invariant is safe. This is mostly due to the fact that the worst case is similar in both instances.</p> <p>Currently an attacker can queue many transactions in the tx pool, across many accounts, and invalidate them all at once with a block where each of the queued accounts send a tx moving their entire balance. This attack will become easier and cheaper after this EIP, because it will no longer require direct access to the block builder and will not cost a full 21000 gas to originate each tx. However, the attack does not have a substantial impact on the network, so reducing the difficulty and cost is not of concern.</p> <h3 id="allowing-tx-origin-as-signer">Allowing <code>tx.origin</code> as Signer</h3> <p>Allowing <code>authorized</code> to equal <code>tx.origin</code> enables simple transaction batching, where the sender of the outer transaction would be the signing account. The ERC-20 approve-then-transfer pattern, which currently requires two separate transactions, could be completed in a single transaction with this proposal.</p> <p><code>AUTH</code> allows for signatures to be signed by <code>tx.origin</code>. For any such signatures, subsequent <code>AUTHCALL</code>s have <code>msg.sender == tx.origin</code> in their first layer of execution. Without EIP-3074, this situation can only ever arise in the topmost execution layer of a transaction. This EIP breaks that invariant and so affects smart contracts containing <code>require(msg.sender == tx.origin)</code> checks. This check can be used for at least three purposes:</p> <ol> <li>Ensuring that <code>msg.sender</code> is an EOA (given that <code>tx.origin</code> always has to be an EOA). This invariant does not depend on the execution layer depth and, therefore, is not affected.</li> <li>Protecting against atomic sandwich attacks like flash loans, that rely on the ability to modify state before and after the execution of the target contract as part of the same atomic transaction. This protection would be broken by this EIP. However, relying on <code>tx.origin</code> in this way is considered bad practice, and can already be circumvented by miners conditionally including transactions in a block.</li> <li>Preventing reentrancy.</li> </ol> <p>Examples of (1) and (2) can be found in contracts deployed on Ethereum mainnet, with (1) being more common (and unaffected by this proposal.) On the other hand, use case (3) is more severely affected by this proposal, but the authors of this EIP did not find any examples of this form of reentrancy protection, though the search was non-exhaustive.</p> <p>This distribution of occurrences—many (1), some (2), and no (3)—is exactly what the authors of this EIP expect, because:</p> <ul> <li>Determining if <code>msg.sender</code> is an EOA without <code>tx.origin</code> is difficult (if not impossible.)</li> <li>The only execution context which is safe from atomic sandwich attacks is the topmost context, and <code>tx.origin == msg.sender</code> is the only way to detect that context.</li> <li>In contrast, there are many direct and flexible ways of preventing reentrancy (ex. using a storage variable.) Since <code>msg.sender == tx.origin</code> is only true in the topmost context, it would make an obscure tool for preventing reentrancy, rather than other more common approaches.</li> </ul> <p>There are other approaches to mitigate this restriction which do not break the invariant:</p> <ul> <li>Set <code>tx.origin</code> to a constant <code>ENTRY_POINT</code> address for <code>AUTHCALL</code>s.</li> <li>Set <code>tx.origin</code> to the invoker address for <code>AUTHCALL</code>s.</li> <li>Set <code>tx.origin</code> to a special address derived from any of the sender, invoker, and/or signer addresses.</li> <li>Disallow <code>authorized == tx.origin</code>. This would make the simple batching use cases impossible, but could be relaxed in the future.</li> </ul> <h3 id="authcall-cheaper-than-call-when-sending-value"><code>AUTHCALL</code> cheaper than <code>CALL</code> when sending value</h3> <p>Sending non-zero value with <code>CALL</code> increases its cost by 9,000. Of that, 6,700 covers the increased overhead of the balance transfer and 2,300 is used as a stipend into the subcall to seed its gas counter. <code>AUTHCALL</code> does not provide a stipend and thus only charges the base 6,700.</p> <h3 id="in-protocol-revocation">In-Protocol Revocation</h3> <p>This EIP has gone <a href="https://wg-eips.ritovision.com/3074/#what-to-sign">back and forth</a> on how to deal with <code>AUTH</code> message revocation. Without revocation, this EIP is a supremely powerful and flexible primitive for developers. However, it does have risk for users who use insecure and/or actively malicious invokers.</p> <p>Much of the risk is due to the new ability for users to batch many operations in a single transaction. It becomes easier for an account to be drained. This is a risk that will continue to grow, regardless of the adoption of this EIP, due to overwhelming desire for the feature and attempts to support it at the protocol level and at the app level.</p> <p>A new class of risk is introduced for insecure and buggy invokers. If an invoker has implemented replay protection, as per the authors' recommendation, this should substantially contain the blast radius. However, if the bug allows an adversary to circumvent the replay protection mechanism, it may give them full access to any EOA which has interacted with the vulnerable invoker.</p> <p>Although this is a truly catastrophic event which is not expected to be possible via reputable wallets, it is a serious consideration. Without in-protocol revocation, users have no way to remove their account from the vulnerable invoker.</p> <p>For this reason, <code>AUTH</code> requires the <code>nonce</code> in the message to be equal to the signer's current nonce. This way, a single tx from the EOA will cause the nonce to increase, invalidating all outstanding authorizations.</p> <h3 id="failing-on-extcodesize-check">Failing on <code>EXTCODESIZE</code> check</h3> <p>In <a href="https://wg-eips.ritovision.com/3607/">EIP-3607</a>, it was determined that the protocol should reject any transaction which originates from an account with code. Although this EIP focused on transaction origination, the authors of EIP-3074 feel the intention is clear: an account that has both code and a known private key should not be allowed to make arbitrary calls on behalf of said account. Therefore, the property is upheld in this EIP. For full rationale, please refer to <a href="https://wg-eips.ritovision.com/3607/">EIP-3607</a>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Although this EIP poses no issues for backwards compatibility, there are concerns that it limits future changes to accounts by further enshrining ECDSA signatures. For example, it might be desirable to eradicate the concept of EOAs altogether, and replace them with smart contract wallets that emulate the same behavior. This is fully compatible with the EIP as written, however, it gets tricky if users can then elect to "upgrade" their smart contract wallets to use other methods of authentication -- e.g. convert into a multi-sig. Without any changes, <code>AUTH</code> would not respect this new logic and continue allowing the old private key to perform actions on behalf of the account.</p> <p>A solution to this would be at the same time that EOAs are removed, to modify the logic of <code>AUTH</code> to actually call into the account with some standard message and allow the account to determine if the signature / witness is valid. Further research should be done to understand how invokers would need to change in this situation and how best to write them in a future-compatible manner.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="secure-invokers">Secure Invokers</h3> <p>The following is a non-exhaustive list of checks/pitfalls/conditions that invokers <em>should</em> be wary of:</p> <ul> <li>Replay protection (ex. a nonce) should be implemented by the invoker, and included in <code>commit</code>. Without it, a malicious actor can reuse a signature, repeating its effects.</li> <li><code>value</code> should be included in <code>commit</code>. Without it, a malicious sponsor could cause unexpected effects in the callee.</li> <li><code>gas</code> should be included in <code>commit</code>. Without it, a malicious sponsor could cause the callee to run out of gas and fail, griefing the sponsee.</li> <li><code>addr</code> and <code>calldata</code> should be included in <code>commit</code>. Without them, a malicious actor may call arbitrary functions in arbitrary contracts.</li> </ul> <p>A poorly implemented invoker can <em>allow a malicious actor to take near complete control over a signer's EOA</em>.</p> <h3 id="allowing-tx-origin-as-signer-1">Allowing <code>tx.origin</code> as Signer</h3> <p>Allowing <code>authorized</code> to equal <code>tx.origin</code> has the possibility to:</p> <ul> <li>Break atomic sandwich protections which rely on <code>tx.origin</code>;</li> <li>Break reentrancy guards of the style <code>require(tx.origin == msg.sender)</code>.</li> </ul> <p>The authors of this EIP believe the risks of allowing <code>authorized</code> to equal <code>tx.origin</code> are acceptable for the reasons outlined in the Rationale section.</p> <h3 id="sponsored-transaction-relayers">Sponsored Transaction Relayers</h3> <p>It is possible for the <code>authorized</code> account to cause sponsored transaction relayers to spend gas without being reimbursed by either invalidating the authorization (i.e. increasing the account's nonce) or by sweeping the relevant assets out of the account. Relayers should be designed with these cases in mind, possibly by requiring a bond to be deposited or by implementing a reputation system.</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-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Peter Jihoon Kimhttps://github.com/petejkim Kevin Britzhttps://github.com/kbrizzle David Knotthttps://github.com/DavidLKnott https://wg-eips.ritovision.com/3009/

Transfer fungible assets via a signed authorization

<h2 id="abstract">Abstract</h2> <p>A set of functions to enable meta-transactions and atomic interactions with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token contracts via signatures conforming to the <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> typed message signing specification.</p> <p>This enables the user to:</p> <ul> <li>delegate the gas payment to someone else,</li> <li>pay gas in the token itself rather than in ETH,</li> <li>perform one or more token transfers and other operations in a single atomic transaction,</li> <li>transfer ERC-20 tokens to another address, and have the recipient submit the transaction,</li> <li>batch multiple transactions with minimal overhead, and</li> <li>create and perform multiple transactions without having to worry about them failing due to accidental nonce-reuse or improper ordering by the miner.</li> </ul> <p>Please note that this ERC does not apply to smart contract accounts, as the <code>transfer</code> and <code>approve</code>/<code>transferFrom</code> functions from the ERC-20 standards can directly be used.</p> <!-- TODO (Editor's note): we don't permit links outside of the EIP/ERC repositories, with some exceptions noted in EIP-1 This ERC has been live in production within the USDC smart contract since 2020, and serves as a critical component of the [x402](https://www.x402.org/) standard. --> <h2 id="motivation">Motivation</h2> <p>There is an existing spec, <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a>, that also allows meta-transactions, and it is encouraged that a contract implements both for maximum compatibility. The two primary differences between this spec and ERC-2612 are that:</p> <ul> <li>ERC-2612 uses sequential nonces, but this uses random 32-byte nonces, and that</li> <li>ERC-2612 relies on the ERC-20 <code>approve</code>/<code>transferFrom</code> ("ERC-20 allowance") pattern.</li> </ul> <p>The biggest issue with the use of sequential nonces is that it does not allow users to perform more than one transaction at a time without risking their transactions failing, because:</p> <ul> <li>DApps may unintentionally reuse nonces that have not yet been processed in the blockchain.</li> <li>Miners may process the transactions in the incorrect order.</li> </ul> <p>This can be especially problematic if the gas prices are very high and transactions often get queued up and remain unconfirmed for a long time. Non-sequential nonces allow users to create as many transactions as they want at the same time.</p> <p>The ERC-20 allowance mechanism is susceptible to the <!-- TODO (Editor's note): same note as above. [multiple withdrawal attack](https://blockchain-projects.readthedocs.io/multiple_withdrawal.html) -->/<!-- TODO (Editor's note): you can copy the SWC into your assets directory because it's MIT licensed. [SWC-114](https://swcregistry.io/docs/SWC-114) -->, and encourages antipatterns such as the use of the "infinite" allowance. The wide prevalence of upgradeable contracts has made the conditions favorable for these attacks to happen in the wild.</p> <p>The deficiencies of the ERC-20 allowance pattern brought about the development of alternative token standards such as the <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> and <!-- TODO (Editor's note): if you'd like to link to ERC-677, you'll need to pull request it into the repository (i.e. upgrade it) [ERC-677](https://github.com/ethereum/EIPs/issues/677) -->. However, they haven't been able to gain much adoption due to compatibility and potential security issues.</p> <h2 id="specification">Specification</h2> <h3 id="event">Event</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"> AuthorizationUsed</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"> authorizer</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"> nonce</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"> keccak256(&quot;TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)&quot;)</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> TRANSFER_WITH_AUTHORIZATION_TYPEHASH </span><span class="z-keyword">=</span><span class="z-constant"> 0x7c7c6cdb67a18743f49ec6fa9b35f50d52ed05cbed4cc592e13b44501c1a2267</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> keccak256(&quot;ReceiveWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)&quot;)</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> RECEIVE_WITH_AUTHORIZATION_TYPEHASH </span><span class="z-keyword">=</span><span class="z-constant"> 0xd099cc98ef71107a616c4f0f941f04c322d8e254fe26b3c6668db87aae413de8</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 the state of an authorization</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Nonces are randomly generated 32-byte data unique to the authorizer&#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 class="z-storage z-type">@param</span><span class="z-variable z-other"> authorizer</span><span class="z-comment"> Authorizer&#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"> nonce</span><span class="z-comment"> Nonce of the authorization</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 nonce is used</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"> authorizationState</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> authorizer</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> nonce</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"> Execute a transfer with a signed authorization</span></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 (Authorizer)</span></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"> Payee&#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"> value</span><span class="z-comment"> Amount to be transferred</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> validAfter</span><span class="z-comment"> The time after which this is valid (unix 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"> validBefore</span><span class="z-comment"> The time before which this is valid (unix 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"> nonce</span><span class="z-comment"> Unique nonce</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> v</span><span class="z-comment"> v of the 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"> r</span><span class="z-comment"> r of the 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"> s</span><span class="z-comment"> s of the signature</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"> transferWithAuthorization</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"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validAfter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validBefore</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</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"> Receive a transfer with a signed authorization from the payer</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This has an additional check to ensure that the payee&#39;s address matches</span></span> <span class="giallo-l"><span class="z-comment"> * the caller of this function to prevent front-running attacks. (See security</span></span> <span class="giallo-l"><span class="z-comment"> * considerations)</span></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 (Authorizer)</span></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"> Payee&#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"> value</span><span class="z-comment"> Amount to be transferred</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> validAfter</span><span class="z-comment"> The time after which this is valid (unix 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"> validBefore</span><span class="z-comment"> The time before which this is valid (unix 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"> nonce</span><span class="z-comment"> Unique nonce</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> v</span><span class="z-comment"> v of the 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"> r</span><span class="z-comment"> r of the 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"> s</span><span class="z-comment"> s of the signature</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"> receiveWithAuthorization</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"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validAfter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validBefore</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</span></span> <span class="giallo-l"><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p><strong>Optional:</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>event AuthorizationCanceled(</span></span> <span class="giallo-l"><span> address indexed authorizer,</span></span> <span class="giallo-l"><span> bytes32 indexed nonce</span></span> <span class="giallo-l"><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// keccak256(&quot;CancelAuthorization(address authorizer,bytes32 nonce)&quot;)</span></span> <span class="giallo-l"><span>bytes32 public constant CANCEL_AUTHORIZATION_TYPEHASH = 0x158b0a9edf7a828aad02f63cd515c68ef2f50ba807396f6d12842833a1597429;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * @notice Attempt to cancel an authorization</span></span> <span class="giallo-l"><span> * @param authorizer Authorizer&#39;s address</span></span> <span class="giallo-l"><span> * @param nonce Nonce of the authorization</span></span> <span class="giallo-l"><span> * @param v v of the signature</span></span> <span class="giallo-l"><span> * @param r r of the signature</span></span> <span class="giallo-l"><span> * @param s s of the signature</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>function cancelAuthorization(</span></span> <span class="giallo-l"><span> address authorizer,</span></span> <span class="giallo-l"><span> bytes32 nonce,</span></span> <span class="giallo-l"><span> uint8 v,</span></span> <span class="giallo-l"><span> bytes32 r,</span></span> <span class="giallo-l"><span> bytes32 s</span></span> <span class="giallo-l"><span>) external;</span></span></code></pre> <p>The arguments <code>v</code>, <code>r</code>, and <code>s</code> must be obtained using the <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> typed message signing spec.</p> <p><strong>Example:</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>DomainSeparator := Keccak256(ABIEncode(</span></span> <span class="giallo-l"><span> Keccak256(</span></span> <span class="giallo-l"><span> &quot;EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)&quot;</span></span> <span class="giallo-l"><span> ),</span></span> <span class="giallo-l"><span> Keccak256(&quot;USD Coin&quot;), // name</span></span> <span class="giallo-l"><span> Keccak256(&quot;2&quot;), // version</span></span> <span class="giallo-l"><span> 1, // chainId</span></span> <span class="giallo-l"><span> 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 // verifyingContract</span></span> <span class="giallo-l"><span>))</span></span></code></pre> <p>With the domain separator, the typehash, which is used to identify the type of the EIP-712 message being used, and the values of the parameters, you are able to derive a Keccak-256 hash digest which can then be signed using the token holder's private key.</p> <p><strong>Example:</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// Transfer With Authorization</span></span> <span class="giallo-l"><span>TypeHash := Keccak256(</span></span> <span class="giallo-l"><span> &quot;TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)&quot;</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span>Params := { From, To, Value, ValidAfter, ValidBefore, Nonce }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// ReceiveWithAuthorization</span></span> <span class="giallo-l"><span>TypeHash := Keccak256(</span></span> <span class="giallo-l"><span> &quot;ReceiveWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)&quot;</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span>Params := { From, To, Value, ValidAfter, ValidBefore, Nonce }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// CancelAuthorization</span></span> <span class="giallo-l"><span>TypeHash := Keccak256(</span></span> <span class="giallo-l"><span> &quot;CancelAuthorization(address authorizer,bytes32 nonce)&quot;</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span>Params := { Authorizer, Nonce }</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// &quot;‖&quot; denotes concatenation.</span></span> <span class="giallo-l"><span>Digest := Keccak256(</span></span> <span class="giallo-l"><span> 0x1901 ‖ DomainSeparator ‖ Keccak256(ABIEncode(TypeHash, Params...))</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>{ v, r, s } := Sign(Digest, PrivateKey)</span></span></code></pre> <p>Smart contract functions that wrap <code>receiveWithAuthorization</code> call may choose to reduce the number of arguments by accepting the full ABI-encoded set of arguments for the <code>receiveWithAuthorization</code> call as a single argument of the type <code>bytes</code>.</p> <p><strong>Example:</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> keccak256(&quot;receiveWithAuthorization(address,address,uint256,uint256,uint256,bytes32,uint8,bytes32,bytes32)&quot;)[0:4]</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> _RECEIVE_WITH_AUTHORIZATION_SELECTOR </span><span class="z-keyword">=</span><span class="z-constant"> 0xef55bec6</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"> deposit</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> receiveAuthorization</span><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"> nonReentrant</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><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> amount</span><span>)</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span></span> <span class="giallo-l"><span> receiveAuthorization</span><span>[</span><span class="z-constant">0</span><span class="z-keyword">:</span><span class="z-constant">96</span><span>]</span><span>,</span></span> <span class="giallo-l"><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> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>to </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 class="z-string"> &quot;Recipient is not this contract&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></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> token</span><span>.</span><span class="z-entity z-name">call</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> _RECEIVE_WITH_AUTHORIZATION_SELECTOR</span><span>,</span></span> <span class="giallo-l"><span> receiveAuthorization</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>success</span><span>,</span><span class="z-string"> &quot;Failed to transfer tokens&quot;</span><span>)</span><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></code></pre><h3 id="use-with-web3-providers">Use with web3 providers</h3> <p>The signature for an authorization can be obtained using a web3 provider with the <code>eth_signTypedData{_v4}</code> method.</p> <p><strong>Example:</strong></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"> data</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> [</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>,</span></span> <span class="giallo-l"><span> TransferWithAuthorization</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">from</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">to</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">value</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">validAfter</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">validBefore</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">nonce</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></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> name</span><span>:</span><span class="z-variable z-other"> tokenName</span><span>,</span></span> <span class="giallo-l"><span> version</span><span>:</span><span class="z-variable z-other"> tokenVersion</span><span>,</span></span> <span class="giallo-l"><span> chainId</span><span>:</span><span class="z-variable z-other"> selectedChainId</span><span>,</span></span> <span class="giallo-l"><span> verifyingContract</span><span>:</span><span class="z-variable z-other"> tokenAddress</span><span>,</span></span> <span class="giallo-l"><span> }</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">TransferWithAuthorization</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> message</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> from</span><span>:</span><span class="z-variable z-other"> userAddress</span><span>,</span></span> <span class="giallo-l"><span> to</span><span>:</span><span class="z-variable z-other"> recipientAddress</span><span>,</span></span> <span class="giallo-l"><span> value</span><span>:</span><span class="z-variable z-other"> amountBN</span><span>.</span><span class="z-entity z-name">toString</span><span>(</span><span class="z-constant">10</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> validAfter</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span> validBefore</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">Date</span><span>.</span><span class="z-entity z-name">now</span><span>(</span><span>)</span><span class="z-keyword"> /</span><span class="z-constant"> 1000</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> 3600</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Valid for an hour</span></span> <span class="giallo-l"><span> nonce</span><span>:</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">randomHex</span><span>(</span><span class="z-constant">32</span><span>)</span><span>,</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> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> signature</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">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eth_signTypedData_v4</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span><span class="z-variable z-other">userAddress</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">data</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-storage z-type">const</span><span class="z-variable z-other z-constant"> v</span><span class="z-keyword"> =</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 class="z-keyword"> +</span><span class="z-variable z-other"> signature</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">130</span><span>,</span><span class="z-constant"> 132</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"> r</span><span class="z-keyword"> =</span><span class="z-variable z-other"> signature</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 66</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"> s</span><span class="z-keyword"> =</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 class="z-keyword"> +</span><span class="z-variable z-other"> signature</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">66</span><span>,</span><span class="z-constant"> 130</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="unique-random-nonce-instead-of-sequential-nonce">Unique Random Nonce, Instead of Sequential Nonce</h3> <p>One might say transaction ordering is one reason why sequential nonces are preferred. However, sequential nonces do not actually help achieve transaction ordering for meta transactions in practice:</p> <ul> <li>For native Ethereum transactions, when a transaction with a nonce value that is too-high is submitted to the network, it will stay pending until the transactions consuming the lower unused nonces are confirmed.</li> <li>However, for meta-transactions, when a transaction containing a sequential nonce value that is too high is submitted, instead of staying pending, it will revert and fail immediately, resulting in wasted gas.</li> <li>The fact that miners can also reorder transactions and include them in the block in the order they want (assuming each transaction was submitted to the network by different meta-transaction relayers) also makes it possible for the meta-transactions to fail even if the nonces used were correct. (e.g. User submits nonces 3, 4 and 5, but miner ends up including them in the block as 4,5,3, resulting in only 3 succeeding)</li> <li>Lastly, when using different applications simultaneously, in the absence of some sort of an off-chain nonce tracker, it is not possible to determine what the correct next nonce value is if there exists nonces that are used but haven't been submitted and confirmed by the network.</li> <li>Under high gas price conditions, transactions can often "get stuck" in the pool for a long time. Under such a situation, it is much more likely for the same nonce to be unintentionally reused twice. For example, if you make a meta-transaction that uses a sequential nonce from one app, and switch to another app to make another meta-transaction before the previous one confirms, the same nonce will be used if the app relies purely on the data available on-chain, resulting in one of the transactions failing.</li> <li>In conclusion, the only way to guarantee transaction ordering is for relayers to submit transactions one at a time, waiting for confirmation between each submission (and the order in which they should be submitted can be part of some off-chain metadata), rendering sequential nonce irrelevant.</li> </ul> <h3 id="valid-after-and-valid-before">Valid After and Valid Before</h3> <ul> <li>Relying on relayers to submit transactions for you means you may not have exact control over the timing of transaction submission.</li> <li>These parameters allow the user to schedule a transaction to be only valid in the future or before a specific deadline, protecting the user from potential undesirable effects that may be caused by the submission being made either too late or too early.</li> </ul> <h3 id="eip-712">EIP-712</h3> <ul> <li>EIP-712 ensures that the signatures generated are valid only for this specific instance of the token contract and cannot be replayed on a different network with a different chain ID.</li> <li>This is achieved by incorporating the contract address and the chain ID in a Keccak-256 hash digest called the domain separator. The actual set of parameters used to derive the domain separator is up to the implementing contract, but it is highly recommended that the fields <code>verifyingContract</code> and <code>chainId</code> are included.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>New contracts benefit from being able to directly utilize <a href="https://wg-eips.ritovision.com/3009/">ERC-3009</a> in order to create atomic transactions, but existing contracts may still rely on the conventional ERC-20 allowance pattern (<code>approve</code>/<code>transferFrom</code>).</p> <p>In order to add support for ERC-3009 to existing contracts ("parent contract") that use the ERC-20 allowance pattern, a forwarding contract ("forwarder") can be constructed that takes an authorization and does the following:</p> <ol> <li>Extract the user and deposit amount from the authorization</li> <li>Call <code>receiveWithAuthorization</code> to transfer specified funds from the user to the forwarder</li> <li>Approve the parent contract to spend funds from the forwarder</li> <li>Call the method on the parent contract that spends the allowance set from the forwarder</li> <li>Transfer the ownership of any resulting tokens back to the user</li> </ol> <p><strong>Example:</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"> IDeFiToken</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"> amount</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-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"> account</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amount</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>)</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"> DepositForwarder</span><span> {</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> _RECEIVE_WITH_AUTHORIZATION_SELECTOR </span><span class="z-keyword">=</span><span class="z-constant"> 0xef55bec6</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> IDeFiToken </span><span class="z-storage z-type">private</span><span> _parent</span><span>;</span></span> <span class="giallo-l"><span> IERC20 </span><span class="z-storage z-type">private</span><span> _token</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">IDeFiToken</span><span class="z-variable"> parent</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> {</span></span> <span class="giallo-l"><span> _parent </span><span class="z-keyword">=</span><span> parent</span><span>;</span></span> <span class="giallo-l"><span> _token </span><span class="z-keyword">=</span><span> token</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"> deposit</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> receiveAuthorization</span><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"> nonReentrant</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><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> amount</span><span>)</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span></span> <span class="giallo-l"><span> receiveAuthorization</span><span>[</span><span class="z-constant">0</span><span class="z-keyword">:</span><span class="z-constant">96</span><span>]</span><span>,</span></span> <span class="giallo-l"><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> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>to </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 class="z-string"> &quot;Recipient is not this contract&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></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 class="z-support"> address</span><span>(</span><span>_token</span><span>)</span><span>.</span><span class="z-entity z-name">call</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> _RECEIVE_WITH_AUTHORIZATION_SELECTOR</span><span>,</span></span> <span class="giallo-l"><span> receiveAuthorization</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>success</span><span>,</span><span class="z-string"> &quot;Failed to transfer to the forwarder&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> _token</span><span>.</span><span class="z-entity z-name">approve</span><span>(</span><span class="z-support">address</span><span>(</span><span>_parent</span><span>)</span><span>,</span><span> amount</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Failed to set the allowance&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"> uint256</span><span> tokensMinted </span><span class="z-keyword">=</span><span> _parent</span><span>.</span><span class="z-entity z-name">deposit</span><span>(</span><span>amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> _parent</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>from</span><span>,</span><span> tokensMinted</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Failed to transfer the minted tokens&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"> uint256</span><span> remainder </span><span class="z-keyword">=</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 class="z-keyword"> if</span><span> (</span><span>remainder </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> <span class="giallo-l"><span> _token</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>from</span><span>,</span><span> remainder</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Failed to refund the remainder&quot;</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-keyword"> return</span><span> tokensMinted</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><!-- TODO (Editor's note): please move your test cases into your assets directory (assuming they're under a permissive license) ## Test Cases See [EIP3009.test.ts](https://github.com/CoinbaseStablecoin/eip-3009/blob/master/test/EIP3009.test.ts). --> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="eip3009-sol"><code>EIP3009.sol</code></h3> <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"> EIP3009</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC20Transfer</span><span>, </span><span class="z-entity z-name">EIP712Domain</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> keccak256(&quot;TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)&quot;)</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> TRANSFER_WITH_AUTHORIZATION_TYPEHASH </span><span class="z-keyword">=</span><span class="z-constant"> 0x7c7c6cdb67a18743f49ec6fa9b35f50d52ed05cbed4cc592e13b44501c1a2267</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> keccak256(&quot;ReceiveWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)&quot;)</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> RECEIVE_WITH_AUTHORIZATION_TYPEHASH </span><span class="z-keyword">=</span><span class="z-constant"> 0xd099cc98ef71107a616c4f0f941f04c322d8e254fe26b3c6668db87aae413de8</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-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes32</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bool</span><span>)</span><span>)</span><span class="z-storage z-type"> internal</span><span> _authorizationStates</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"> AuthorizationUsed</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> authorizer</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> nonce</span><span>)</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"> internal</span><span class="z-storage z-type"> constant</span><span> _INVALID_SIGNATURE_ERROR </span><span class="z-keyword">=</span><span class="z-string"> &quot;EIP3009: invalid signature&quot;</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"> authorizationState</span><span>(</span><span class="z-support">address</span><span class="z-variable"> authorizer</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> 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"> 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 class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _authorizationStates</span><span>[</span><span>authorizer</span><span>]</span><span>[</span><span>nonce</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"> transferWithAuthorization</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"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validAfter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validBefore</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</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 class="z-variable z-language">now</span><span class="z-keyword"> &gt;</span><span> validAfter</span><span>,</span><span class="z-string"> &quot;EIP3009: authorization is not yet valid&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">now</span><span class="z-keyword"> &lt;</span><span> validBefore</span><span>,</span><span class="z-string"> &quot;EIP3009: authorization is expired&quot;</span><span>)</span><span>;</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>_authorizationStates</span><span>[</span><span>from</span><span>]</span><span>[</span><span>nonce</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;EIP3009: authorization is used&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"> bytes</span><span class="z-storage z-type"> memory</span><span> data </span><span class="z-keyword">=</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> TRANSFER_WITH_AUTHORIZATION_TYPEHASH</span><span>,</span></span> <span class="giallo-l"><span> from</span><span>,</span></span> <span class="giallo-l"><span> to</span><span>,</span></span> <span class="giallo-l"><span> value</span><span>,</span></span> <span class="giallo-l"><span> validAfter</span><span>,</span></span> <span class="giallo-l"><span> validBefore</span><span>,</span></span> <span class="giallo-l"><span> nonce</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> EIP712</span><span>.</span><span class="z-entity z-name">recover</span><span>(</span><span>DOMAIN_SEPARATOR</span><span>,</span><span> v</span><span>,</span><span> r</span><span>,</span><span> s</span><span>,</span><span> data</span><span>)</span><span class="z-keyword"> ==</span><span> from</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;EIP3009: invalid signature&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _authorizationStates</span><span>[</span><span>from</span><span>]</span><span>[</span><span>nonce</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> AuthorizationUsed</span><span>(</span><span>from</span><span>,</span><span> nonce</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> _transfer</span><span>(</span><span>from</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></code></pre><h3 id="ierc20transfer-sol"><code>IERC20Transfer.sol</code></h3> <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"> IERC20Transfer</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> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</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"> amount</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>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="eip712domain-sol"><code>EIP712Domain.sol</code></h3> <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"> EIP712Domain</span><span> {</span></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></code></pre><h3 id="eip712-sol"><code>EIP712.sol</code></h3> <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"> EIP712</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> keccak256(&quot;EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)&quot;)</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> EIP712_DOMAIN_TYPEHASH </span><span class="z-keyword">=</span><span class="z-constant"> 0x8b73c3c69bb8fe3d512ecc4cf759cc79239f7b179b0ffacaa9a75d522b39400f</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"> makeDomainSeparator</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"> version</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> internal</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>)</span></span> <span class="giallo-l"><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-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> chainId </span><span class="z-keyword">:=</span><span class="z-entity z-name"> chainid</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-keyword"> return</span></span> <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">encode</span><span>(</span></span> <span class="giallo-l"><span> EIP712_DOMAIN_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>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 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"> recover</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> domainSeparator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</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"> typeHashAndData</span></span> <span class="giallo-l"><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 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> domainSeparator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span>typeHashAndData</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"> address</span><span> recovered </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>recovered </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;EIP712: invalid signature&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> recovered</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>A fully working implementation of ERC-3009 can be found in <a href="https://wg-eips.ritovision.com/3009/./assets/ERC3009.sol">this repository</a>. The repository also includes <a href="https://wg-eips.ritovision.com/3009/./assets/ERC2612.sol">an implementation of ERC-2612</a> that uses the EIP-712 library code presented above.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Use <code>receiveWithAuthorization</code> instead of <code>transferWithAuthorization</code> when calling from other smart contracts. It is possible for an attacker watching the transaction pool to extract the transfer authorization and front-run the <code>transferWithAuthorization</code> call to execute the transfer without invoking the wrapper function. This could potentially result in unprocessed, locked up deposits. <code>receiveWithAuthorization</code> prevents this by performing an additional check that ensures that the caller is the payee. Additionally, if there are multiple contract functions accepting receive authorizations, the app developer could dedicate some leading bytes of the nonce as an identifier to prevent cross-use.</p> <p>When submitting multiple transfers simultaneously, be mindful of the fact that relayers and miners will decide the order in which they are processed. This is generally not a problem if the transactions are not dependent on each other, but for transactions that are highly dependent on each other, it is recommended that the signed authorizations are submitted one at a time.</p> <p>The zero address must be rejected when <code>ecrecover</code> is used to prevent unauthorized transfers and approvals of funds from the zero address. The built-in <code>ecrecover</code> returns the zero address when a malformed signature is provided.</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-28T00:00:00+00:00 2026-02-11T14:48:26+00:00 Peter Jihoon Kimhttps://github.com/petejkim Kevin Britzhttps://github.com/kbrizzle David Knotthttps://github.com/DavidLKnott Dongri Jinhttps://github.com/dongri https://wg-eips.ritovision.com/7758/

Transfer fungible assets via a signed authorization.

<h2 id="abstract">Abstract</h2> <p>A set of functions to enable meta-transactions and atomic interactions with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token contracts via signatures conforming to the <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> typed message signing specification.</p> <p>This enables the user to:</p> <ul> <li>delegate the gas payment to someone else,</li> <li>pay for gas in the token itself rather than in ETH,</li> <li>perform one or more token transfers and other operations in a single atomic transaction,</li> <li>transfer ERC-20 tokens to another address, and have the recipient submit the transaction,</li> <li>batch multiple transactions with minimal overhead, and</li> <li>create and perform multiple transactions without having to worry about them failing due to accidental nonce-reuse or improper ordering by the miner.</li> </ul> <h2 id="motivation">Motivation</h2> <p>There is an existing spec, <a href="https://wg-eips.ritovision.com/2612/">EIP-2612</a>, that also allows meta-transactions, and it is encouraged that a contract implements both for maximum compatibility. The two primary differences between this spec and EIP-2612 are that:</p> <ul> <li>EIP-2612 uses sequential nonces, but this uses random 32-byte nonces, and that</li> <li>EIP-2612 relies on the ERC-20 <code>approve</code>/<code>transferFrom</code> ("ERC-20 allowance") pattern.</li> </ul> <p>The biggest issue with the use of sequential nonces is that it does not allow users to perform more than one transaction at time without risking their transactions failing, because:</p> <ul> <li>DApps may unintentionally reuse nonces that have not yet been processed in the blockchain.</li> <li>Miners may process the transactions in the incorrect order.</li> </ul> <p>This can be especially problematic if the gas prices are very high and transactions often get queued up and remain unconfirmed for a long time. Non-sequential nonces allow users to create as many transactions as they want at the same time.</p> <p>The ERC-20 allowance mechanism is susceptible to the multiple withdrawal attack, and encourages antipatterns such as the use of the "infinite" allowance. The wide-prevalence of upgradeable contracts have made the conditions favorable for these attacks to happen in the wild.</p> <p>The deficiencies of the ERC-20 allowance pattern brought about the development of alternative token standards such as the <a href="https://wg-eips.ritovision.com/777/">ERC-777</a>. However, they haven't been able to gain much adoption due to compatibility and potential security issues.</p> <h2 id="specification">Specification</h2> <h3 id="event">Event</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"> AuthorizationUsed</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"> authorizer</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"> nonce</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"> keccak256(&quot;TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)&quot;)</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> TRANSFER_WITH_AUTHORIZATION_TYPEHASH </span><span class="z-keyword">=</span><span class="z-constant"> 0x7c7c6cdb67a18743f49ec6fa9b35f50d52ed05cbed4cc592e13b44501c1a2267</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> keccak256(&quot;ReceiveWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)&quot;)</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> RECEIVE_WITH_AUTHORIZATION_TYPEHASH </span><span class="z-keyword">=</span><span class="z-constant"> 0xd099cc98ef71107a616c4f0f941f04c322d8e254fe26b3c6668db87aae413de8</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 the state of an authorization</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Nonces are randomly generated 32-byte data unique to the authorizer&#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 class="z-storage z-type">@param</span><span class="z-variable z-other"> authorizer</span><span class="z-comment"> Authorizer&#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"> nonce</span><span class="z-comment"> Nonce of the authorization</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 nonce is used</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"> authorizationState</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> authorizer</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> nonce</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"> Execute a transfer with a signed authorization</span></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 (Authorizer)</span></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"> Payee&#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"> value</span><span class="z-comment"> Amount to be transferred</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> validAfter</span><span class="z-comment"> The time after which this is valid (unix 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"> validBefore</span><span class="z-comment"> The time before which this is valid (unix 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"> nonce</span><span class="z-comment"> Unique nonce</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> v</span><span class="z-comment"> v of the 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"> r</span><span class="z-comment"> r of the 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"> s</span><span class="z-comment"> s of the signature</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"> transferWithAuthorization</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"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validAfter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validBefore</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</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"> Receive a transfer with a signed authorization from the payer</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This has an additional check to ensure that the payee&#39;s address matches</span></span> <span class="giallo-l"><span class="z-comment"> * the caller of this function to prevent front-running attacks. (See security</span></span> <span class="giallo-l"><span class="z-comment"> * considerations)</span></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 (Authorizer)</span></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"> Payee&#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"> value</span><span class="z-comment"> Amount to be transferred</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> validAfter</span><span class="z-comment"> The time after which this is valid (unix 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"> validBefore</span><span class="z-comment"> The time before which this is valid (unix 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"> nonce</span><span class="z-comment"> Unique nonce</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> v</span><span class="z-comment"> v of the 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"> r</span><span class="z-comment"> r of the 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"> s</span><span class="z-comment"> s of the signature</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"> receiveWithAuthorization</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"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validAfter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validBefore</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</span></span> <span class="giallo-l"><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p><strong>Optional:</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>event AuthorizationCanceled(</span></span> <span class="giallo-l"><span> address indexed authorizer,</span></span> <span class="giallo-l"><span> bytes32 indexed nonce</span></span> <span class="giallo-l"><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// keccak256(&quot;CancelAuthorization(address authorizer,bytes32 nonce)&quot;)</span></span> <span class="giallo-l"><span>bytes32 public constant CANCEL_AUTHORIZATION_TYPEHASH = 0x158b0a9edf7a828aad02f63cd515c68ef2f50ba807396f6d12842833a1597429;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * @notice Attempt to cancel an authorization</span></span> <span class="giallo-l"><span> * @param authorizer Authorizer&#39;s address</span></span> <span class="giallo-l"><span> * @param nonce Nonce of the authorization</span></span> <span class="giallo-l"><span> * @param v v of the signature</span></span> <span class="giallo-l"><span> * @param r r of the signature</span></span> <span class="giallo-l"><span> * @param s s of the signature</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>function cancelAuthorization(</span></span> <span class="giallo-l"><span> address authorizer,</span></span> <span class="giallo-l"><span> bytes32 nonce,</span></span> <span class="giallo-l"><span> uint8 v,</span></span> <span class="giallo-l"><span> bytes32 r,</span></span> <span class="giallo-l"><span> bytes32 s</span></span> <span class="giallo-l"><span>) external;</span></span></code></pre> <p>The arguments <code>v</code>, <code>r</code>, and <code>s</code> must be obtained using the <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> typed message signing spec.</p> <p><strong>Example:</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>DomainSeparator := Keccak256(ABIEncode(</span></span> <span class="giallo-l"><span> Keccak256(</span></span> <span class="giallo-l"><span> &quot;EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)&quot;</span></span> <span class="giallo-l"><span> ),</span></span> <span class="giallo-l"><span> Keccak256(&quot;USD Coin&quot;), // name</span></span> <span class="giallo-l"><span> Keccak256(&quot;2&quot;), // version</span></span> <span class="giallo-l"><span> 1, // chainId</span></span> <span class="giallo-l"><span> 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 // verifyingContract</span></span> <span class="giallo-l"><span>))</span></span></code></pre> <p>With the domain separator, the typehash, which is used to identify the type of the EIP-712 message being used, and the values of the parameters, you are able to derive a Keccak-256 hash digest which can then be signed using the token holder's private key.</p> <p><strong>Example:</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// Transfer With Authorization</span></span> <span class="giallo-l"><span>TypeHash := Keccak256(</span></span> <span class="giallo-l"><span> &quot;TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)&quot;</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span>Params := { From, To, Value, ValidAfter, ValidBefore, Nonce }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// ReceiveWithAuthorization</span></span> <span class="giallo-l"><span>TypeHash := Keccak256(</span></span> <span class="giallo-l"><span> &quot;ReceiveWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)&quot;</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span>Params := { From, To, Value, ValidAfter, ValidBefore, Nonce }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// CancelAuthorization</span></span> <span class="giallo-l"><span>TypeHash := Keccak256(</span></span> <span class="giallo-l"><span> &quot;CancelAuthorization(address authorizer,bytes32 nonce)&quot;</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span>Params := { Authorizer, Nonce }</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// &quot;‖&quot; denotes concatenation.</span></span> <span class="giallo-l"><span>Digest := Keecak256(</span></span> <span class="giallo-l"><span> 0x1901 ‖ DomainSeparator ‖ Keccak256(ABIEncode(TypeHash, Params...))</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>{ v, r, s } := Sign(Digest, PrivateKey)</span></span></code></pre> <p>Smart contract functions that wrap <code>receiveWithAuthorization</code> call may choose to reduce the number of arguments by accepting the full ABI-encoded set of arguments for the <code>receiveWithAuthorization</code> call as a single argument of the type <code>bytes</code>.</p> <p><strong>Example:</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> keccak256(&quot;receiveWithAuthorization(address,address,uint256,uint256,uint256,bytes32,uint8,bytes32,bytes32)&quot;)[0:4]</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> _RECEIVE_WITH_AUTHORIZATION_SELECTOR </span><span class="z-keyword">=</span><span class="z-constant"> 0xef55bec6</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"> deposit</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> receiveAuthorization</span><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"> nonReentrant</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><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> amount</span><span>)</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span></span> <span class="giallo-l"><span> receiveAuthorization</span><span>[</span><span class="z-constant">0</span><span class="z-keyword">:</span><span class="z-constant">96</span><span>]</span><span>,</span></span> <span class="giallo-l"><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> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>to </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 class="z-string"> &quot;Recipient is not this contract&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></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> token</span><span>.</span><span class="z-entity z-name">call</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> _RECEIVE_WITH_AUTHORIZATION_SELECTOR</span><span>,</span></span> <span class="giallo-l"><span> receiveAuthorization</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>success</span><span>,</span><span class="z-string"> &quot;Failed to transfer tokens&quot;</span><span>)</span><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></code></pre><h3 id="use-with-web3-providers">Use with web3 providers</h3> <p>The signature for an authorization can be obtained using a web3 provider with the <code>eth_signTypedData{_v4}</code> method.</p> <p><strong>Example:</strong></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"> data</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> [</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>,</span></span> <span class="giallo-l"><span> TransferWithAuthorization</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">from</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">to</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">value</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">validAfter</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">validBefore</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">nonce</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></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> domain</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> name</span><span>:</span><span class="z-variable z-other"> tokenName</span><span>,</span></span> <span class="giallo-l"><span> version</span><span>:</span><span class="z-variable z-other"> tokenVersion</span><span>,</span></span> <span class="giallo-l"><span> chainId</span><span>:</span><span class="z-variable z-other"> selectedChainId</span><span>,</span></span> <span class="giallo-l"><span> verifyingContract</span><span>:</span><span class="z-variable z-other"> tokenAddress</span><span>,</span></span> <span class="giallo-l"><span> }</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">TransferWithAuthorization</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> message</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> from</span><span>:</span><span class="z-variable z-other"> userAddress</span><span>,</span></span> <span class="giallo-l"><span> to</span><span>:</span><span class="z-variable z-other"> recipientAddress</span><span>,</span></span> <span class="giallo-l"><span> value</span><span>:</span><span class="z-variable z-other"> amountBN</span><span>.</span><span class="z-entity z-name">toString</span><span>(</span><span class="z-constant">10</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> validAfter</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span> validBefore</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">Date</span><span>.</span><span class="z-entity z-name">now</span><span>(</span><span>)</span><span class="z-keyword"> /</span><span class="z-constant"> 1000</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> 3600</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Valid for an hour</span></span> <span class="giallo-l"><span> nonce</span><span>:</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">randomHex</span><span>(</span><span class="z-constant">32</span><span>)</span><span>,</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> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> signature</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">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eth_signTypedData_v4</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span><span class="z-variable z-other">userAddress</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">data</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-storage z-type">const</span><span class="z-variable z-other z-constant"> v</span><span class="z-keyword"> =</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 class="z-keyword"> +</span><span class="z-variable z-other"> signature</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">130</span><span>,</span><span class="z-constant"> 132</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"> r</span><span class="z-keyword"> =</span><span class="z-variable z-other"> signature</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 66</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"> s</span><span class="z-keyword"> =</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 class="z-keyword"> +</span><span class="z-variable z-other"> signature</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">66</span><span>,</span><span class="z-constant"> 130</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="unique-random-nonce-instead-of-sequential-nonce">Unique Random Nonce, Instead of Sequential Nonce</h3> <p>One might say transaction ordering is one reason why sequential nonces are preferred. However, sequential nonces do not actually help achieve transaction ordering for meta transactions in practice:</p> <ul> <li>For native Ethereum transactions, when a transaction with a nonce value that is too-high is submitted to the network, it will stay pending until the transactions consuming the lower unused nonces are confirmed.</li> <li>However, for meta-transactions, when a transaction containing a sequential nonce value that is too high is submitted, instead of staying pending, it will revert and fail immediately, resulting in wasted gas.</li> <li>The fact that miners can also reorder transactions and include them in the block in the order they want (assuming each transaction was submitted to the network by different meta-transaction relayers) also makes it possible for the meta-transactions to fail even if the nonces used were correct. (e.g. User submits nonces 3, 4 and 5, but miner ends up including them in the block as 4,5,3, resulting in only 3 succeeding)</li> <li>Lastly, when using different applications simultaneously, in absence of some sort of an off-chain nonce-tracker, it is not possible to determine what the correct next nonce value is if there exists nonces that are used but haven't been submitted and confirmed by the network.</li> <li>Under high gas price conditions, transactions can often "get stuck" in the pool for a long time. Under such a situation, it is much more likely for the same nonce to be unintentionally reused twice. For example, if you make a meta-transaction that uses a sequential nonce from one app, and switch to another app to make another meta-transaction before the previous one confirms, the same nonce will be used if the app relies purely on the data available on-chain, resulting in one of the transactions failing.</li> <li>In conclusion, the only way to guarantee transaction ordering is for relayers to submit transactions one at a time, waiting for confirmation between each submission (and the order in which they should be submitted can be part of some off-chain metadata), rendering sequential nonce irrelevant.</li> </ul> <h3 id="valid-after-and-valid-before">Valid After and Valid Before</h3> <ul> <li>Relying on relayers to submit transactions for you means you may not have exact control over the timing of transaction submission.</li> <li>These parameters allow the user to schedule a transaction to be only valid in the future or before a specific deadline, protecting the user from potential undesirable effects that may be caused by the submission being made either too late or too early.</li> </ul> <h3 id="eip-712">EIP-712</h3> <ul> <li>EIP-712 ensures that the signatures generated are valid only for this specific instance of the token contract and cannot be replayed on a different network with a different chain ID.</li> <li>This is achieved by incorporating the contract address and the chain ID in a Keccak-256 hash digest called the domain separator. The actual set of parameters used to derive the domain separator is up to the implementing contract, but it is highly recommended that the fields <code>verifyingContract</code> and <code>chainId</code> are included.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>New contracts benefit from being able to directly utilize this proposal in order to create atomic transactions, but existing contracts may still rely on the conventional <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> allowance pattern (<code>approve</code>/<code>transferFrom</code>).</p> <p>In order to add support for this proposal to existing contracts ("parent contract") that use the ERC-20 allowance pattern, a forwarding contract ("forwarder") can be constructed that takes an authorization and does the following:</p> <ol> <li>Extract the user and deposit amount from the authorization</li> <li>Call <code>receiveWithAuthorization</code> to transfer specified funds from the user to the forwarder</li> <li>Approve the parent contract to spend funds from the forwarder</li> <li>Call the method on the parent contract that spends the allowance set from the forwarder</li> <li>Transfer the ownership of any resulting tokens back to the user</li> </ol> <p><strong>Example:</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"> IDeFiToken</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"> amount</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-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"> account</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amount</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>)</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"> DepositForwarder</span><span> {</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> _RECEIVE_WITH_AUTHORIZATION_SELECTOR </span><span class="z-keyword">=</span><span class="z-constant"> 0xef55bec6</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> IDeFiToken </span><span class="z-storage z-type">private</span><span> _parent</span><span>;</span></span> <span class="giallo-l"><span> IERC20 </span><span class="z-storage z-type">private</span><span> _token</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">IDeFiToken</span><span class="z-variable"> parent</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> {</span></span> <span class="giallo-l"><span> _parent </span><span class="z-keyword">=</span><span> parent</span><span>;</span></span> <span class="giallo-l"><span> _token </span><span class="z-keyword">=</span><span> token</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"> deposit</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> receiveAuthorization</span><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"> nonReentrant</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><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> amount</span><span>)</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span></span> <span class="giallo-l"><span> receiveAuthorization</span><span>[</span><span class="z-constant">0</span><span class="z-keyword">:</span><span class="z-constant">96</span><span>]</span><span>,</span></span> <span class="giallo-l"><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> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>to </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 class="z-string"> &quot;Recipient is not this contract&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></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 class="z-support"> address</span><span>(</span><span>_token</span><span>)</span><span>.</span><span class="z-entity z-name">call</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> _RECEIVE_WITH_AUTHORIZATION_SELECTOR</span><span>,</span></span> <span class="giallo-l"><span> receiveAuthorization</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>success</span><span>,</span><span class="z-string"> &quot;Failed to transfer to the forwarder&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> _token</span><span>.</span><span class="z-entity z-name">approve</span><span>(</span><span class="z-support">address</span><span>(</span><span>_parent</span><span>)</span><span>,</span><span> amount</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Failed to set the allowance&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"> uint256</span><span> tokensMinted </span><span class="z-keyword">=</span><span> _parent</span><span>.</span><span class="z-entity z-name">deposit</span><span>(</span><span>amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> _parent</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>from</span><span>,</span><span> tokensMinted</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Failed to transfer the minted tokens&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"> uint256</span><span> remainder </span><span class="z-keyword">=</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 class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>remainder </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> <span class="giallo-l"><span> _token</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>from</span><span>,</span><span> remainder</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Failed to refund the remainder&quot;</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-keyword"> return</span><span> tokensMinted</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> <h3 id="eip7758-sol"><code>EIP7758.sol</code></h3> <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"> EIP7758</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC20Transfer</span><span>, </span><span class="z-entity z-name">EIP712Domain</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> keccak256(&quot;TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)&quot;)</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> TRANSFER_WITH_AUTHORIZATION_TYPEHASH </span><span class="z-keyword">=</span><span class="z-constant"> 0x7c7c6cdb67a18743f49ec6fa9b35f50d52ed05cbed4cc592e13b44501c1a2267</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> keccak256(&quot;ReceiveWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)&quot;)</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> RECEIVE_WITH_AUTHORIZATION_TYPEHASH </span><span class="z-keyword">=</span><span class="z-constant"> 0xd099cc98ef71107a616c4f0f941f04c322d8e254fe26b3c6668db87aae413de8</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-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes32</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bool</span><span>)</span><span>)</span><span class="z-storage z-type"> internal</span><span> _authorizationStates</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"> AuthorizationUsed</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> authorizer</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> nonce</span><span>)</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"> internal</span><span class="z-storage z-type"> constant</span><span> _INVALID_SIGNATURE_ERROR </span><span class="z-keyword">=</span><span class="z-string"> &quot;EIP7758: invalid signature&quot;</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"> authorizationState</span><span>(</span><span class="z-support">address</span><span class="z-variable"> authorizer</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> 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"> 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 class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _authorizationStates</span><span>[</span><span>authorizer</span><span>]</span><span>[</span><span>nonce</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"> transferWithAuthorization</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"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validAfter</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> validBefore</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</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 class="z-variable z-language">now</span><span class="z-keyword"> &gt;</span><span> validAfter</span><span>,</span><span class="z-string"> &quot;EIP7758: authorization is not yet valid&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">now</span><span class="z-keyword"> &lt;</span><span> validBefore</span><span>,</span><span class="z-string"> &quot;EIP7758: authorization is expired&quot;</span><span>)</span><span>;</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>_authorizationStates</span><span>[</span><span>from</span><span>]</span><span>[</span><span>nonce</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;EIP7758: authorization is used&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"> bytes</span><span class="z-storage z-type"> memory</span><span> data </span><span class="z-keyword">=</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> TRANSFER_WITH_AUTHORIZATION_TYPEHASH</span><span>,</span></span> <span class="giallo-l"><span> from</span><span>,</span></span> <span class="giallo-l"><span> to</span><span>,</span></span> <span class="giallo-l"><span> value</span><span>,</span></span> <span class="giallo-l"><span> validAfter</span><span>,</span></span> <span class="giallo-l"><span> validBefore</span><span>,</span></span> <span class="giallo-l"><span> nonce</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> EIP712</span><span>.</span><span class="z-entity z-name">recover</span><span>(</span><span>DOMAIN_SEPARATOR</span><span>,</span><span> v</span><span>,</span><span> r</span><span>,</span><span> s</span><span>,</span><span> data</span><span>)</span><span class="z-keyword"> ==</span><span> from</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;EIP7758: invalid signature&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _authorizationStates</span><span>[</span><span>from</span><span>]</span><span>[</span><span>nonce</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> AuthorizationUsed</span><span>(</span><span>from</span><span>,</span><span> nonce</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> _transfer</span><span>(</span><span>from</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></code></pre><h3 id="ierc20transfer-sol"><code>IERC20Transfer.sol</code></h3> <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"> IERC20Transfer</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> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> sender</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"> amount</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>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="eip712domain-sol"><code>EIP712Domain.sol</code></h3> <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"> EIP712Domain</span><span> {</span></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></code></pre><h3 id="eip712-sol"><code>EIP712.sol</code></h3> <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"> EIP712</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> keccak256(&quot;EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)&quot;)</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> constant</span><span> EIP712_DOMAIN_TYPEHASH </span><span class="z-keyword">=</span><span class="z-constant"> 0x8b73c3c69bb8fe3d512ecc4cf759cc79239f7b179b0ffacaa9a75d522b39400f</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"> makeDomainSeparator</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"> version</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> internal</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>)</span></span> <span class="giallo-l"><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-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> chainId </span><span class="z-keyword">:=</span><span class="z-entity z-name"> chainid</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-keyword"> return</span></span> <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">encode</span><span>(</span></span> <span class="giallo-l"><span> EIP712_DOMAIN_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>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 class="z-support"> bytes32</span><span>(</span><span>chainId</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 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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> recover</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> domainSeparator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</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"> typeHashAndData</span></span> <span class="giallo-l"><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 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> domainSeparator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span>typeHashAndData</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"> address</span><span> recovered </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>recovered </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;EIP712: invalid signature&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> recovered</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>Use <code>receiveWithAuthorization</code> instead of <code>transferWithAuthorization</code> when calling from other smart contracts. It is possible for an attacker watching the transaction pool to extract the transfer authorization and front-run the <code>transferWithAuthorization</code> call to execute the transfer without invoking the wrapper function. This could potentially result in unprocessed, locked up deposits. <code>receiveWithAuthorization</code> prevents this by performing an additional check that ensures that the caller is the payee. Additionally, if there are multiple contract functions accepting receive authorizations, the app developer could dedicate some leading bytes of the nonce could as the identifier to prevent cross-use.</p> <p>When submitting multiple transfers simultaneously, be mindful of the fact that relayers and miners will decide the order in which they are processed. This is generally not a problem if the transactions are not dependent on each other, but for transactions that are highly dependent on each other, it is recommended that the signed authorizations are submitted one at a time.</p> <p>The zero address must be rejected when using <code>ecrecover</code> to prevent unauthorized transfers and approvals of funds from the zero address. The built-in <code>ecrecover</code> returns the zero address when a malformed signature is provided.</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-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-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zach Burkshttps://github.com/vexycats James Morganhttps://github.com/jamesmorgan Blaine Malonehttps://github.com/blmalone James Seibelhttps://github.com/seibelj https://wg-eips.ritovision.com/2981/ <h2 id="simple-summary">Simple Summary</h2> <p>A standardized way to retrieve royalty payment information for non-fungible tokens (NFTs) to enable universal support for royalty payments across all NFT marketplaces and ecosystem participants.</p> <h2 id="abstract">Abstract</h2> <p>This standard allows contracts, such as NFTs that support <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> interfaces, to signal a royalty amount to be paid to the NFT creator or rights holder every time the NFT is sold or re-sold. This is intended for NFT marketplaces that want to support the ongoing funding of artists and other NFT creators. The royalty payment must be voluntary, as transfer mechanisms such as <code>transferFrom()</code> include NFT transfers between wallets, and executing them does not always imply a sale occurred. Marketplaces and individuals implement this standard by retrieving the royalty payment information with <code>royaltyInfo()</code>, which specifies how much to pay to which address for a given sale price. The exact mechanism for paying and notifying the recipient will be defined in future EIPs. This ERC should be considered a minimal, gas-efficient building block for further innovation in NFT royalty payments.</p> <h2 id="motivation">Motivation</h2> <p>There are many marketplaces for NFTs with multiple unique royalty payment implementations that are not easily compatible or usable by other marketplaces. Just like the early days of ERC-20 tokens, NFT marketplace smart contracts are varied by ecosystem and not standardized. This EIP enables all marketplaces to retrieve royalty payment information for a given NFT. This enables accurate royalty payments regardless of which marketplace the NFT is sold or re-sold at.</p> <p>Many of the largest NFT marketplaces have implemented bespoke royalty payment solutions that are incompatible with other marketplaces. This standard implements standardized royalty information retrieval that can be accepted across any type of NFT marketplace. This minimalist proposal only provides a mechanism to fetch the royalty amount and recipient. The actual funds transfer is something which the marketplace should execute.</p> <p>This standard allows NFTs that support <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> interfaces, to have a standardized way of signalling royalty information. More specifically, these contracts can now calculate a royalty amount to provide to the rightful recipient.</p> <p>Royalty amounts are always a percentage of the sale price. If a marketplace chooses <em>not</em> to implement this EIP, then no funds will be paid for secondary sales. It is believed that the NFT marketplace ecosystem will voluntarily implement this royalty payment standard; in a bid to provide ongoing funding for artists/creators. NFT buyers will assess the royalty payment as a factor when making NFT purchasing decisions.</p> <p>Without an agreed royalty payment standard, the NFT ecosystem will lack an effective means to collect royalties across all marketplaces and artists and other creators will not receive ongoing funding. This will hamper the growth and adoption of NFTs and demotivate NFT creators from minting new and innovative tokens.</p> <p>Enabling all NFT marketplaces to unify on a single royalty payment standard will benefit the entire NFT ecosystem.</p> <p>While this standard focuses on NFTs and compatibility with the ERC-721 and ERC-1155 standards, EIP-2981 does not require compatibility with ERC-721 and ERC-1155 standards. Any other contract could integrate with EIP-2981 to return royalty payment information. ERC-2981 is, therefore, a universal royalty standard for many asset types.</p> <p>At a glance, here's an example conversation summarizing NFT royalty payments today:</p> <blockquote> <p><strong>Artist</strong>: "Do you support royalty payments on your platform?"<br /> <strong>Marketplace</strong>: "Yes we have royalty payments, but if your NFT is sold on another marketplace then we cannot enforce this payment."<br /> <strong>Artist</strong>: "What about other marketplaces that support royalties, don't you share my royalty information to make this work?"<br /> <strong>Marketplace</strong>: "No, we do not share royalty information."</p> </blockquote> <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>ERC-721 and ERC-1155 compliant contracts MAY implement this ERC for royalties to provide a standard method of specifying royalty payment information.</strong></p> <p>Marketplaces that support this standard <strong>SHOULD</strong> implement some method of transferring royalties to the royalty recipient. Standards for the actual transfer and notification of funds will be specified in future EIPs.</p> <p>Marketplaces <strong>MUST</strong> pay the royalty in the same unit of exchange as that of the <code>_salePrice</code> passed to <code>royaltyInfo()</code>. This is equivalent to saying that the <code>_salePrice</code> parameter and the <code>royaltyAmount</code> return value <strong>MUST</strong> be denominated in the same monetary unit. For example, if the sale price is in ETH, then the royalty payment must also be paid in ETH, and if the sale price is in USDC, then the royalty payment must also be paid in USDC.</p> <p>Implementers of this standard <strong>MUST</strong> calculate a percentage of the <code>_salePrice</code> when calculating the royalty amount. Subsequent invocations of <code>royaltyInfo()</code> <strong>MAY</strong> return a different <code>royaltyAmount</code>. Though there are some important considerations for implementers if they choose to perform different percentage calculations between <code>royaltyInfo()</code> invocations.</p> <p>The <code>royaltyInfo()</code> function is not aware of the unit of exchange for the sale and royalty payment. With that in mind, implementers <strong>MUST NOT</strong> return a fixed/constant <code>royaltyAmount</code>, wherein they're ignoring the <code>_salePrice</code>. For the same reason, implementers <strong>MUST NOT</strong> determine the <code>royaltyAmount</code> based on comparing the <code>_salePrice</code> with constant numbers. In both cases, the <code>royaltyInfo()</code> function makes assumptions on the unit of exchange, which <strong>MUST</strong> be avoided.</p> <p>The percentage value used must be independent of the sale price for reasons previously mentioned (i.e. if the percentage value 10%, then 10% <strong>MUST</strong> apply whether <code>_salePrice</code> is 10, 10000 or 1234567890). If the royalty fee calculation results in a remainder, implementers <strong>MAY</strong> round up or round down to the nearest integer. For example, if the royalty fee is 10% and <code>_salePrice</code> is 999, the implementer can return either 99 or 100 for <code>royaltyAmount</code>, both are valid.</p> <p>The implementer <strong>MAY</strong> choose to change the percentage value based on other predictable variables that do not make assumptions about the unit of exchange. For example, the percentage value may drop linearly over time. An approach like this <strong>SHOULD NOT</strong> be based on variables that are unpredictable like <code>block.timestamp</code>, but instead on other more predictable state changes. One more reasonable approach <strong>MAY</strong> use the number of transfers of an NFT to decide which percentage value is used to calculate the <code>royaltyAmount</code>. The idea being that the percentage value could decrease after each transfer of the NFT. Another example could be using a different percentage value for each unique <code>_tokenId</code>.</p> <p>Marketplaces that support this standard <strong>SHOULD NOT</strong> send a zero-value transaction if the <code>royaltyAmount</code> returned is <code>0</code>. This would waste gas and serves no useful purpose in this EIP.</p> <p>Marketplaces that support this standard <strong>MUST</strong> pay royalties no matter where the sale occurred or in what currency, including on-chain sales, over-the-counter (OTC) sales and off-chain sales such as at auction houses. As royalty payments are voluntary, entities that respect this EIP must pay no matter where the sale occurred - a sale conducted outside of the blockchain is still a sale. The exact mechanism for paying and notifying the recipient will be defined in future EIPs.</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">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 for the NFT Royalty Standard</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"> IERC2981</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 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;royaltyInfo(uint256,uint256)&quot;)) == 0x2a55205a</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> bytes4 private constant _INTERFACE_ID_ERC2981 = 0x2a55205a;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> _registerInterface(_INTERFACE_ID_ERC2981);</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</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 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"> - the NFT asset queried for royalty information</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _salePrice</span><span class="z-comment"> - the sale price of the NFT asset specified by _tokenId</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"> receiver</span><span class="z-comment"> - address of who should be sent the royalty payment</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"> royaltyAmount</span><span class="z-comment"> - the royalty payment amount for _salePrice</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> royaltyInfo</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"> _salePrice</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"> receiver</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> royaltyAmount</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"> 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><h3 id="examples">Examples</h3> <p>This standard being used on an ERC-721 during deployment:</p> <h4 id="deploying-an-erc-721-and-signaling-support-for-erc-2981">Deploying an ERC-721 and signaling support for ERC-2981</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"> Royalties interface</span></span> <span class="giallo-l"><span class="z-entity z-name"> _registerInterface</span><span>(</span><span>_INTERFACE_ID_ERC2981</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-implemented-royalties">Checking if the NFT being sold on your marketplace implemented royalties</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_ERC2981 </span><span class="z-keyword">=</span><span class="z-constant"> 0x2a55205a</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"> checkRoyalties</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_ERC2981</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="rationale">Rationale</h2> <h3 id="optional-royalty-payments">Optional royalty payments</h3> <p>It is impossible to know which NFT transfers are the result of sales, and which are merely wallets moving or consolidating their NFTs. Therefore, we cannot force every transfer function, such as <code>transferFrom()</code> in ERC-721, to involve a royalty payment as not every transfer is a sale that would require such payment. We believe the NFT marketplace ecosystem will voluntarily implement this royalty payment standard to provide ongoing funding for artists/creators. NFT buyers will assess the royalty payment as a factor when making NFT purchasing decisions.</p> <h3 id="simple-royalty-payments-to-a-single-address">Simple royalty payments to a single address</h3> <p>This EIP does not specify the manner of payment to the royalty recipient. Furthermore, it is impossible to fully know and efficiently implement all possible types of royalty payments logic. With that said, it is on the royalty payment receiver to implement all additional complexity and logic for fee splitting, multiple receivers, taxes, accounting, etc. in their own receiving contract or off-chain processes. Attempting to do this as part of this standard, it would dramatically increase the implementation complexity, increase gas costs, and could not possibly cover every potential use-case. This ERC should be considered a minimal, gas-efficient building block for further innovation in NFT royalty payments. Future EIPs can specify more details regarding payment transfer and notification.</p> <h3 id="royalty-payment-percentage-calculation">Royalty payment percentage calculation</h3> <p>This EIP mandates a percentage-based royalty fee model. It is likely that the most common case of percentage calculation will be where the <code>royaltyAmount</code> is always calculated from the <code>_salePrice</code> using a fixed percent i.e. if the royalty fee is 10%, then a 10% royalty fee must apply whether <code>_salePrice</code> is 10, 10000 or 1234567890.</p> <p>As previously mentioned, implementers can get creative with this percentage-based calculation but there are some important caveats to consider. Mainly, ensuring that the <code>royaltyInfo()</code> function is not aware of the unit of exchange and that unpredictable variables are avoided in the percentage calculation. To follow up on the earlier <code>block.timestamp</code> example, there is some nuance which can be highlighted if the following events ensued:</p> <ol> <li>Marketplace sells NFT.</li> <li>Marketplace delays <code>X</code> days before invoking <code>royaltyInfo()</code> and sending payment.</li> <li>Marketplace receives <code>Y</code> for <code>royaltyAmount</code> which was significantly different from the <code>royaltyAmount</code> amount that would've been calculated <code>X</code> days prior if no delay had occurred.</li> <li>Royalty recipient is dissatisfied with the delay from the marketplace and for this reason, they raise a dispute.</li> </ol> <p>Rather than returning a percentage and letting the marketplace calculate the royalty amount based on the sale price, a <code>royaltyAmount</code> value is returned so there is no dispute with a marketplace over how much is owed for a given sale price. The royalty fee payer must pay the <code>royaltyAmount</code> that <code>royaltyInfo()</code> stipulates.</p> <h3 id="unit-less-royalty-payment-across-all-marketplaces-both-on-chain-and-off-chain">Unit-less royalty payment across all marketplaces, both on-chain and off-chain</h3> <p>This EIP does not specify a currency or token used for sales and royalty payments. The same percentage-based royalty fee must be paid regardless of what currency, or token was used in the sale, paid in the same currency or token. This applies to sales in any location including on-chain sales, over-the-counter (OTC) sales, and off-chain sales using fiat currency such as at auction houses. As royalty payments are voluntary, entities that respect this EIP must pay no matter where the sale occurred - a sale outside of the blockchain is still a sale. The exact mechanism for paying and notifying the recipient will be defined in future EIPs.</p> <h3 id="universal-royalty-payments">Universal Royalty Payments</h3> <p>Although designed specifically with NFTs in mind, this standard does not require that a contract implementing EIP-2981 is compatible with either ERC-721 or ERC-1155 standards. Any other contract could use this interface to return royalty payment information, provided that it is able to uniquely identify assets within the constraints of the interface. ERC-2981 is, therefore, a universal royalty standard for many other asset types.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with current ERC-721 and ERC-1155 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> 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-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Micah Zoltuhttps://github.com/MicahZoltu https://wg-eips.ritovision.com/2976/

Adds support for transmission of typed transactions over devp2p.

<h2 id="abstract">Abstract</h2> <p><a href="https://wg-eips.ritovision.com/2718/">Typed Transactions</a> can be sent over devp2p as <code>TransactionType || TransactionPayload</code>. The exact contents of the <code>TransactionPayload</code> are defined by the <code>TransactionType</code> in future EIPs, and clients may start supporting their gossip without incrementing the devp2p version. If a client receives a <code>TransactionType</code> that it doesn't recognize, it <strong>SHOULD</strong> disconnect from the peer who sent it. Clients <strong>MUST NOT</strong> send new transaction types before they believe the fork block is reached.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> introduced new transaction types for blocks (which presents itself in the makeup of a block header's transaction root and receipts root). However, without a mechanism for gossiping these transactions, no one can actually include them in a block. By updating devp2p to support the gossip of Typed Transactions, we can benefit from these new transaction types.</p> <p><em>Note: See <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> for additional motivations of Typed Transactions.</em></p> <h2 id="specification">Specification</h2> <p>All changes specified below apply to all protocol/versions retroactively.</p> <h3 id="definitions">Definitions</h3> <ul> <li><code>||</code> is the byte/byte-array concatenation operator.</li> <li><code>|</code> is the type union operator.</li> <li><code>DEVP2P_VERSION = TBD</code></li> <li><code>Transaction</code> is either <code>TypedTransaction</code> or <code>LegacyTransaction</code></li> <li><code>TypedTransaction</code> is a byte array containing <code>TransactionType || TransactionPayload</code></li> <li><code>TypedTransactionHash</code> is <code>keccak256(TypedTransaction)</code></li> <li><code>TransactionType</code> is a positive unsigned 8-bit number between <code>0</code> and <code>0x7f</code> that represents the type of the transaction</li> <li><code>TransactionPayload</code> is an opaque byte array whose interpretation is dependent on the <code>TransactionType</code> and defined in future EIPs</li> <li><code>LegacyTransaction</code> is an array of the form <code>[nonce, gasPrice, gasLimit, to, value, data, v, r, s]</code></li> <li><code>LegacyTransactionHash</code> is <code>keccak256(rlp(LegacyTransaction))</code></li> <li><code>TransactionId</code> is <code>keccak256(TypedTransactionHash | LegacyTransactionHash)</code></li> <li><code>Receipt</code> is either <code>TypedReceipt</code> or <code>LegacyReceipt</code></li> <li><code>TypedReceipt</code> is a byte array containing <code>TransactionType || ReceiptPayload</code></li> <li><code>ReceiptPayload</code> is an opaque byte array whose interpretation is dependent on the <code>TransactionType</code> and defined in future EIPs</li> <li><code>LegacyReceipt</code> is an array of the form <code>[status, cumulativeGasUsed, logsBloom, logs]</code></li> <li><code>LegacyReceiptHash</code> is <code>keccak256(rlp(LegacyReceipt))</code></li> </ul> <h3 id="protocol-behavior">Protocol Behavior</h3> <p>If a client receives a <code>TransactionType</code> it doesn't recognize via any message, it <strong>SHOULD</strong> disconnect the peer that sent it.</p> <p>If a client receives a <code>TransactionPayload</code> that isn't valid for the <code>TransactionType</code>, it <strong>SHOULD</strong> disconnect the peer that sent it.</p> <p>Clients <strong>MUST NOT</strong> send transactions of a new <code>TransactionType</code> until that transaction type's introductory fork block.</p> <p>Clients <strong>MAY</strong> disconnect peers who send transactions of a new <code>TransactionType</code> significantly before that transaction type's introductory fork block.</p> <h3 id="protocol-messages">Protocol Messages</h3> <p><code>Transactions (0x02)</code>: <code>[Transaction_0, Transaction_1, ..., Transaction_n]</code></p> <p><code>BlockBodies (0x06)</code>: <code>[BlockBody_0, BlockBody_1, ..., BlockBody_n]</code> where:</p> <ul> <li><code>BlockBody</code> is <code>[TransactionList, UncleList]</code></li> <li><code>TransactionList</code> is <code>[Transaction_0, Transaction_1, ..., Transaction_n]</code></li> <li><code>UnclesList</code> is defined in previous versions of the devp2p specification</li> </ul> <p><code>NewBlock (0x07)</code>: <code>[[BlockHeader, TransactionList, UncleList], TotalDifficulty]</code> where:</p> <ul> <li><code>BlockHeader</code> is defined in previous versions of the devp2 specification</li> <li><code>TransactionList</code> is <code>[Transaction_0, Transaction_1, ..., Transaction_n]</code></li> <li><code>UnclesList</code> is defined in previous versions of the devp2p specification</li> <li><code>TotalDifficulty</code> is defined in previous versions of the devp2p specification</li> </ul> <p><code>NewPooledTransactionIds (0x08)</code>: <code>[TransactionId_0, TransactionId_1, ..., TransactionId_n]</code></p> <p><code>GetPooledTransactions (0x09)</code>: <code>[TransactionId_0, TransactionId_1, ..., TransactionId_n]</code></p> <p><code>PooledTransactions (0x0a)</code>: <code>[Transaction_0, Transaction_1, ..., Transaction_n]</code></p> <p><code>Receipts (0x10)</code>: <code>[ReceiptList_0, ReceiptList_1, ..., ReceiptList_n]</code> where:</p> <ul> <li><code>ReceiptList</code> is <code>[Receipt_0, Receipt_1, ..., Receipt_n]</code></li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="why-not-specify-each-transaction-type-at-the-protocol-layer">Why not specify each transaction type at the protocol layer?</h3> <p>We could have chosen to make the protocol aware of the shape of the transaction payloads. The authors felt that it would be too much maintenance burden long term to have every new transaction type require an update to devp2p, so instead we merely define that typed transactions are supported.</p> <h3 id="why-have-peers-disconnect-if-they-receive-an-unknown-transaction-type">Why have peers disconnect if they receive an unknown transaction type?</h3> <p>We could encourage peers to remain connected to peers that submit an unknown transaction type, in case the transaction is some new transaction type that the receiver isn't aware of it. However, doing so may open clients up to DoS attacks where someone would send them transactions of an undefined <code>TransactionType</code> in order to avoid being disconnected for spamming. Also, in most cases we expect that by the time new transaction types are being sent over devp2p, a hard fork that requires all connected clients to be aware of the new transaction type is almost certainly imminent.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Legacy transactions are still supported.</p> <h2 id="security-considerations">Security Considerations</h2> <p>If a client chooses to ignore the <strong>SHOULD</strong> recommendation for disconnecting peers that send unknown transaction types they may be susceptible to DoS attacks. Ignoring this recommendation should be limited to trusted peers only, or other situations where the risk of DoS is extremely low.</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-12T00:00:00+00:00 2026-02-11T14:49:27+00:00 Micah Zoltuhttps://github.com/MicahZoltu https://wg-eips.ritovision.com/2972/ <h2 id="simple-summary">Simple Summary</h2> <p>Two new transaction types for wrapping legacy transactions with and without a chain ID.</p> <h2 id="abstract">Abstract</h2> <p>Introduces two new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transactions that are signature compatible with legacy transactions and can be automatically upgraded by any client.</p> <ul> <li><code>0x00 || ssz.serialize(yParity, r, s, rlp([nonce, gasPrice, gasLimit, to, value, data]))</code></li> <li><code>0x01 || ssz.serialize(yParity, r, s, rlp([nonce, gasPrice, gasLimit, to, value, data, chainId, 0, 0]))</code></li> </ul> <h2 id="motivation">Motivation</h2> <p>We would like to eventually deprecate legacy transactions so we no longer have to retain code in the networking and signer layer that deals with them. However, we also want to ensure that signatures for transactions that were generated prior to that deprecation are still valid and funds don't end up stuck because of an inability to sign a new style transaction. This EIP provides a mechanism for transmitting/including transactions in a way that is <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> compatible while still being signature compatible with legacy transactions.</p> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions</h3> <ul> <li><code>||</code> is the byte/byte-array concatenation operator.</li> <li><code>yParity</code> is the parity (0 for even, 1 for odd) of the <code>y</code> value of the curve point for which <code>r</code> is the <code>x</code> value in the secp256k1 signing process.</li> </ul> <h3 id="transactions">Transactions</h3> <p>As of <code>FORK_BLOCK_NUMBER</code>, <code>0x00 || ssz.serialize(yParity, r, s, rlp([nonce, gasPrice, gasLimit, to, value, data]))</code> will be a valid transaction where:</p> <ul> <li>the RLP encoded transaction portion is signed/processed/handled exactly the same as legacy transactions were signed/processed/handled, with the exception of the final encoding</li> <li>TODO: Hashing or Merkleizing for block transaction root</li> </ul> <p>As of <code>FORK_BLOCK_NUMBER</code>, <code>0x01 || ssz.serialize(yParity, r, s, rlp([nonce, gasPrice, gasLimit, to, value, data, chainId, 0, 0]))</code> will be a valid transaction where:</p> <ul> <li>the RLP encoded transaction portion is signed/processed/handled exactly the same as legacy transactions were signed/processed/handled, with the exception of the final encoding</li> <li>TODO: Hashing or Merkleizing for block transaction root</li> </ul> <p>The SSZ schema for both transaction types is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Transaction[</span></span> <span class="giallo-l"><span> yParity: boolean,</span></span> <span class="giallo-l"><span> r: bytes32,</span></span> <span class="giallo-l"><span> s: bytes32,</span></span> <span class="giallo-l"><span> signedData: bytes,</span></span> <span class="giallo-l"><span>]</span></span></code></pre> <p>Note: <code>sszencode(yParity, r, s, rlp(...))</code> is the same as <code>yParity || r || s || 0x45000000 || rlp(...)</code></p> <p>As of <code>FORK_BLOCK_NUMBER</code>, <code>rlp(nonce, gasPrice, gasLimit, to, value, data, v, r, s)</code> will no longer be a valid transaction in a block.</p> <h3 id="receipts">Receipts</h3> <p>As of <code>FORK_BLOCK_NUMBER</code>, <code>0 || ssz.serialize(status, cumulativeGasUsed, logsBloom, logs)</code> will be a valid receipt where:</p> <ul> <li>the <code>ReceiptPayload</code> will be generated/processed/handled exactly the same as legacy receipts were processed/handled with the exception of its encoding</li> <li>TODO: Hashing or Merkleizing for block receipt root</li> </ul> <p>As of <code>FORK_BLOCK_NUMBER</code>, <code>1 || ssz.serialize(status, cumulativeGasUsed, logsBloom, logs)</code> will be a valid receipt where:</p> <ul> <li>the <code>ReceiptPayload</code> will be generated/processed/handled exactly the same as legacy receipts were processed/handled with the exception of its encoding</li> <li>TODO: Hashing or Merkleizing for block receipt root</li> </ul> <p>The SSZ schema for both receipt types is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Log[</span></span> <span class="giallo-l"><span> address: bytes20,</span></span> <span class="giallo-l"><span> topics: List[bytes32, 4],</span></span> <span class="giallo-l"><span> data: List[uint8, 0xffffff],</span></span> <span class="giallo-l"><span>]</span></span> <span class="giallo-l"><span>Receipt[</span></span> <span class="giallo-l"><span> status: uint8,</span></span> <span class="giallo-l"><span> cumulativeGasUsed: uint64,</span></span> <span class="giallo-l"><span> logsBloom: BitVector[2048],</span></span> <span class="giallo-l"><span> logs: List[Log, 0xffffff],</span></span> <span class="giallo-l"><span>]</span></span></code></pre> <p>As of <code>FORK_BLOCK_NUMBER</code>, <code>rlp(status, cumulativeGasUsed, logsBloom, logs)</code> will no longer be a valid receipt in a block.</p> <h2 id="rationale">Rationale</h2> <h3 id="signature-doesn-t-include-transaction-type-as-first-signature-byte">Signature doesn't include transaction type as first signature byte</h3> <p>These transaction types are explicitly designed to be signature compatible with legacy transactions, which means we cannot change the data being signed. See Security Considerations section for more details.</p> <h3 id="two-transaction-types-instead-of-one">Two transaction types instead of one</h3> <p>With the introduction of typed transactions, we no longer need to do bit packing to avoid changing the shape of the signature. Legacy transactions introduced chain ID in <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> and wanted to avoid changing the transaction array length, so it bitpacked the chainID into the signature's <code>v</code> value. Since we no longer need to guarantee consistent payload lengths between transaction types, we have opted to have two transaction types with clear fields.</p> <h3 id="signature-separate-from-signed-data">Signature separate from signed data</h3> <p>When validating a signature, one must first separate out the signed data from the signature and then validate the signature against the signed data. In the case of legacy transactions, this was a bit of a burden since you had to first RLP decode the transaction, then extract out the signature, then RLP encode a subset of the transaction. EIP-155 made this process even worse by requiring the validator to further decode the <code>v</code> signature value to extract the chain ID (if present) and include that in the signed data payload. By having the signed data encoded exactly as it is signed, we make it so one can verify the transaction's signature without having to do any decoding before hand. By having the signature SSZ encoded up front, we can easily extract the signature without even having to use a decoder.</p> <h3 id="ssz-for-serialization">SSZ for serialization</h3> <p>There is a weak consensus that RLP is not a particularly good encoding scheme for hashed data partially due to its inability to be streamed. SSZ is almost certainly going to be included in Ethereum at some point in the future, so clients likely have access to an SSZ decoder. For this particular case, manual decoding without a full SSZ decoder isn't too complicated, though it does require doing a bit of "pointer math" since <code>logs</code> is an array of variable length items.</p> <h3 id="deprecating-legacy-transactions">Deprecating legacy transactions</h3> <p>By deprecating legacy transactions, we make it easier for clients as they can always deal with typed transactions in blocks.</p> <h3 id="max-length-of-logs-and-logs-data">Max length of logs and logs data</h3> <p><a href="https://wg-eips.ritovision.com/706/">EIP-706</a> limits devp2p messages to 24 bit length, which gives us a pragmatic cap at that for any single transaction at the moment. This number seems to far exceed what is reasonable anytime in the near future, so feels like as reasonable of a cap as any.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The new transactions are signature compatible with legacy transactions. Legacy transactions can be decoded and then encoded as type 0 or type 1 transactions. This EIP does not introduce any deprecation process for legacy encoded transactions, though the authors do encourage client developers to upgrade legacy encoded transactions to typed transactions as soon as it is reasonable.</p> <p>The signature compatibility means that a client may see the same transaction encoded both ways. In such a case the client can choose which to retain, but it is encouraged to retain the typed transaction rather than the legacy encoded transaction. Since the two transactions would share a nonce, only one will ever be valid in a chain at a time.</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>While <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> strongly recommends including the transaction type as the first byte of the signed data, we cannot accomplish that in this case because we need to remain signature compatible with legacy transactions. Luckily, <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> also excludes transaction types <code>0xc0</code> to <code>0xfe</code> from valid transaction types, and the first byte of the signature in this case is in that range so we can be sure this will not conflict with any future transaction types.</p> <p>A signature for these transaction types <strong>does</strong> collide with legacy transactions, but the transactions will be processed the same so it doesn't matter if the transaction ends up included as a legacy transaction or a typed 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> 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:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin Ansgar Dietrichshttps://github.com/adietrichs Matt Garnetthttps://github.com/lightclient Will Villanuevahttps://github.com/villanuevawill Sam Wilsonhttps://github.com/SamWilsn https://wg-eips.ritovision.com/2938/ <h2 id="simple-summary">Simple Summary</h2> <p>Account abstraction (AA) allows a contract to be the top-level account that pays fees and starts transaction execution.</p> <h2 id="abstract">Abstract</h2> <p><strong>See also: <a rel="external" href="https://ethereum-magicians.org/t/implementing-account-abstraction-as-part-of-eth1-x/4020">https://ethereum-magicians.org/t/implementing-account-abstraction-as-part-of-eth1-x/4020</a> and the links therein for historical work and motivation.</strong></p> <p>Transaction validity, as of Muir Glacier, is defined rigidly by the protocol: ECDSA signature, a simple nonce, and account balance. Account abstraction extends the validity conditions of transactions with the execution of arbitrary EVM bytecode (with some limits on what state may be accessed.) To signal validity, we propose a new EVM opcode <code>PAYGAS</code>, which also sets the gas price and gas limit the contract is willing to pay.</p> <p>We split account abstraction into two tiers: <strong>single-tenant AA</strong>, which is intended to support wallets or other use cases with few participants, and <strong>multi-tenant AA</strong>, which is intended to support applications with many participants (eg. tornado.cash, Uniswap).</p> <h2 id="motivation">Motivation</h2> <p>The existing limitations preclude innovation in a number of important areas, particularly:</p> <ol> <li>Smart contract wallets that use signature verification other than ECDSA (eg. Schnorr, BLS, post-quantum...)</li> <li>Smart contract wallets that include features such as multisig verification or social recovery, reducing the highly prevalent risk of funds being lost or stolen</li> <li>Privacy-preserving systems like <a rel="external" href="http://tornado.cash">tornado.cash</a></li> <li>Attempts to improve gas efficiency of DeFi protocols by preventing transactions that don't satisfy high-level conditions (eg. existence of a matching order) from being included on chain</li> <li>Users being able to pay for transaction fees in a token other than ETH (eg. by converting that token into the ETH needed for fees inside the transaction in real-time)</li> </ol> <p>Most of the above use cases are currently possible using intermediaries, most notably the <a rel="external" href="https://www.opengsn.org/">Gas Station Network</a> and application-specific alternatives. These implementations are (i) technically inefficient, due to the extra 21000 gas to pay for the relayer, (ii) economically inefficient, as relayers need to make a profit on top of the gas fees that they pay. Additionally, use of intermediary protocols means that these applications cannot simply rely on base Ethereum infrastructure and need to rely on extra protocols that have smaller userbases and higher risk of no longer being available at some future date.</p> <p>Out of the five use cases above, single-tenant AA approximately supports (1) and (2), and multi-tenant AA approximately supports (3) and (4). We discuss the differences between the two tiers in the specification and rationale sections below.</p> <h2 id="specification">Specification</h2> <h3 id="single-tenant">Single Tenant</h3> <p>After <code>FORK_BLOCK</code>, the following changes will be recognized by the protocol.</p> <h4 id="constants">Constants</h4> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><strong><code>AA_ENTRY_POINT</code></strong></td><td><code>0xffffffffffffffffffffffffffffffffffffffff</code></td></tr> <tr><td><strong><code>AA_TX_TYPE</code></strong></td><td><code>2</code></td></tr> <tr><td><strong><code>FORK_BLOCK</code></strong></td><td>TBD</td></tr> <tr><td><strong><code>AA_BASE_GAS_COST</code></strong></td><td>15000</td></tr> </tbody></table> <h4 id="new-transaction-type">New Transaction Type</h4> <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". Their payload should be interpreted as <code>rlp([nonce, target, data])</code>.</p> <p>The base gas cost of this transaction is set to <code>AA_BASE_GAS_COST</code> instead of 21000 to reflect the lack of "intrinsic" ECDSA and signature.</p> <p>Nonces are processed analogously to existing transactions (check <code>tx.nonce == tx.target.nonce</code>, transaction is invalid if this fails, otherwise proceed and immediately set <code>tx.nonce += 1</code>).</p> <p>Note that this transaction type has no intrinsic gas limit; when beginning execution, the gas limit is simply set to the remaining gas in the block (ie. <code>block.gas_limit</code> minus gas spent on previous transactions), and the <code>PAYGAS</code> opcode (see below) can adjust the gas limit downwards.</p> <h4 id="transaction-wide-global-variables">Transaction-wide global variables</h4> <p>Introduce some new transaction-wide global variables. These variables work similarly (in particular, have similar reversion logic) to the SSTORE refunds counter.</p> <table><thead><tr><th>Variable</th><th>Type</th><th>Initial value</th></tr></thead><tbody> <tr><td><code>globals.transaction_fee_paid</code></td><td><code>bool</code></td><td><code>False if type(tx) == AA_TX_TYPE else True</code></td></tr> <tr><td><code>globals.gas_price</code></td><td><code>int</code></td><td><code>0 if type(tx) == AA_TX_TYPE else tx.gas_price</code></td></tr> <tr><td><code>globals.gas_limit</code></td><td><code>int</code></td><td><code>0 if type(tx) == AA_TX_TYPE else tx.gas_limit</code></td></tr> </tbody></table> <h4 id="nonce-0x48-opcode"><code>NONCE (0x48)</code> Opcode</h4> <p>A new opcode <code>NONCE (0x48)</code> is introduced, with gas cost <code>G_base</code>, which pushes the <code>nonce</code> of the callee onto the stack.</p> <h4 id="paygas-0x49-opcode"><code>PAYGAS (0x49)</code> Opcode</h4> <p>A new opcode <code>PAYGAS (0x49)</code> is introduced, with gas cost <code>G_base</code>. It takes two arguments off the stack: (top) <code>version_number</code>, (second from top) <code>memory_start</code>. In the initial implementation, it will <code>assert version_number == 0</code> and read:</p> <ul> <li><code>gas_price = bytes_to_int(vm.memory[memory_start: memory_start + 32])</code></li> <li><code>gas_limit = bytes_to_int(vm.memory[memory_start + 32: memory_start + 64])</code></li> </ul> <p>Both reads use similar mechanics to MLOAD and CALL, so memory expands if needed.</p> <p>Future hard forks may add support for different version numbers, in which case the opcode may take different-sized memory slices and interpret them differently. Two particular potential use cases are <a rel="external" href="https://notes.ethereum.org/@vbuterin/BkSQmQTS8">EIP 1559</a> and <a rel="external" href="https://ethresear.ch/t/another-simple-gas-fee-model-the-escalator-algorithm-from-the-agoric-papers/6399">the escalator mechanism</a>.</p> <p>The opcode works as follows. If all three of the following conditions (in addition to the version number check above) are satisfied:</p> <ol> <li>The account's balance is <code>&gt;= gas_price * gas_limit</code></li> <li><code>globals.transaction_fee_paid == False</code></li> <li>We are in a top-level AA execution frame (ie. if the currently running EVM execution exits or reverts, the EVM execution of the entire transaction is finished)</li> </ol> <p>Then do the following:</p> <ul> <li>Subtract <code>gas_price * gas_limit</code> from the contract's balance</li> <li>Set <code>globals.transaction_fee_paid</code> to <code>True</code></li> <li>Set <code>globals.gas_price</code> to <code>gas_price</code>, and <code>globals.gas_limit</code> to <code>gas_limit</code></li> <li>Set the remaining gas in the current execution context to equal <code>gas_limit</code> minus the gas that was already consumed</li> </ul> <p>If any of the above three conditions are not satisfied, throw an exception.</p> <p>At the end of execution of an AA transaction, it is mandatory that <code>globals.transaction_fee_paid == True</code>; if it is not, then the transaction is invalid. At the end of execution, the contract is refunded <code>globals.gas_price * remaining_gas</code> for any remaining gas, and <code>(globals.gas_limit - remaining_gas) * globals.gas_price</code> is transferred to the miner.</p> <p><code>PAYGAS</code> also serves as an EVM execution <em>checkpoint</em>: if the top-level execution frame reverts after <code>PAYGAS</code> has been called, then the execution only reverts up to the point right after <code>PAYGAS</code> was called, and exits there. In that case, the contract receives no refund, and <code>globals.gas_limit * globals.gas_price</code> is transferred to the miner.</p> <h4 id="replay-protection">Replay Protection</h4> <p>One of the two following approaches must be implemented to safeguard against replay attacks.</p> <h5 id="require-set-indestructible">Require <code>SET_INDESTRUCTIBLE</code></h5> <p>Require that contracts targeted by AA transactions begin with <a href="https://wg-eips.ritovision.com/2937/">EIP-2937</a>'s <code>SET_INDESTRUCTIBLE</code> opcode. AA transactions targeting contracts that do not begin with <code>SET_INDESTRUCTIBLE</code> are invalid, and cannot be included in blocks.</p> <p><code>AA_PREFIX</code> would need to be modified to include this opcode.</p> <h5 id="preserve-nonce-on-selfdestruct">Preserve Nonce on <code>SELFDESTRUCT</code></h5> <p>The other option is to preserve contract nonces across <code>SELFDESTRUCT</code> invocations, instead of setting the nonce to zero.</p> <h4 id="miscellaneous">Miscellaneous</h4> <ul> <li>If <code>CALLER (0x33)</code> is invoked in the first frame of execution of a call initiated by an AA transaction, then it must return <code>AA_ENTRY_POINT</code>.</li> <li>If <code>ORIGIN (0x32)</code> is invoked in any frame of execution of an AA transaction it must return <code>AA_ENTRY_POINT</code>.</li> <li>The <code>GASPRICE (0x3A)</code> opcode now pushes the value <code>globals.gas_price</code></li> </ul> <p>Note that the new definition of <code>GASPRICE</code> does not lead to any changes in behavior in non-AA transactions, because <code>globals.gas_price</code> is initialized to <code>tx.gas_price</code> and cannot be changed as <code>PAYGAS</code> cannot be called.</p> <h4 id="mining-and-rebroadcasting-strategies">Mining and Rebroadcasting Strategies</h4> <p>Much of the complexity in account abstraction originates from the strategies used by miners and validating nodes to determine whether or not to accept and rebroadcast transactions. Miners need to determine if a transaction will actually pay the fee if they include it after only a small amount of processing to avoid <a rel="external" href="https://hackingdistributed.com/2016/06/28/ethereum-soft-fork-dos-vector/">DoS attacks</a>. Validating nodes need to perform an essentially identical verification to determine whether or not to rebroadcast the transaction.</p> <p>By keeping the consensus changes minimal, this EIP allows for gradual introduction of AA mempool support by miners and validating nodes. Initial support would be focused on enabling simple, single-tenant use cases, while later steps would additionally allow for more complex, multi-tenant use cases. Earlier stages are deliberately more fully fleshed-out than later stages, as there is still more time before later stages need to be implemented.</p> <h5 id="transactions-with-fixed-nonces">Transactions with Fixed Nonces</h5> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>VERIFICATION_GAS_MULTIPLIER</code></td><td><code>6</code></td></tr> <tr><td><code>VERIFICATION_GAS_CAP</code></td><td><code>= VERIFICATION_GAS_MULTIPLIER * AA_BASE_GAS_COST = 90000</code></td></tr> <tr><td><code>AA_PREFIX</code></td><td><code>if(msg.sender != shr(-1, 12)) { LOG1(msg.sender, msg.value); return }</code>; compilation to EVM TBD</td></tr> </tbody></table> <p>When a node receives an AA transaction, they process it (i.e. attempt to execute it against the current chain head's post-state) to determine its validity, continuing to execute until one of several events happens:</p> <ul> <li>If the code of the <code>target</code> is NOT prefixed with <code>AA_PREFIX</code>, exit with failure</li> <li>If the execution hits any of the following, exit with failure: <ul> <li>An environment opcode (<code>BLOCKHASH</code>, <code>COINBASE</code>, <code>TIMESTAMP</code>, <code>NUMBER</code>, <code>DIFFICULTY</code>, <code>GASLIMIT</code>)</li> <li><code>BALANCE</code> (of any account, including the <code>target</code> itself)</li> <li>An external call/create that changes the <code>callee</code> to anything but the <code>target</code> or a precompile (<code>CALL</code>, <code>CALLCODE</code>, <code>STATICCALL</code>, <code>CREATE</code>, <code>CREATE2</code>).</li> <li>An external state access that reads code (<code>EXTCODESIZE</code>, <code>EXTCODEHASH</code>, <code>EXTCODECOPY</code>, but also <code>CALLCODE</code> and <code>DELEGATECALL</code>), unless the address of the code that is read is the <code>target</code>.</li> </ul> </li> <li>If the execution consumes more gas than <code>VERIFICATION_GAS_CAP</code> (specified above), or more gas than is available in the block, exit with failure</li> <li>If the execution reaches <code>PAYGAS</code>, then exit with success or failure depending on whether or not the balance is sufficient (e.g. <code>balance &gt;= gas_price * gas_limit</code>).</li> </ul> <p>Nodes do not keep transactions with nonces higher than the current valid nonce in the mempool. If the mempool already contains a transaction with a currently valid nonce, another incoming transaction to the same contract and with the same nonce either replaces the existing one (if its gas price is sufficiently higher) or is dropped. Thus, the mempool keeps only at most one pending transaction per account.</p> <p>While processing a new block, take note of which accounts were the <code>target</code> of an AA transaction (each block currently has <code>12500000</code> gas and an AA transaction costs <code>&gt;= 15000</code> so there would be at most <code>12500000 // 15000 = 833</code> targeted accounts). Drop all pending transactions targeting those accounts. All other transactions remain in the mempool.</p> <h3 id="single-tenant-1">Single Tenant+</h3> <p>If the <a rel="external" href="http://github.com/ethereum/EIPs/pull/2937">indestructible contracts EIP</a> is added, Single Tenant AA can be adapted to allow for <code>DELEGATECALL</code> during transaction verification: during execution of a new AA transaction, external state access that reads code (<code>EXTCODESIZE</code>, <code>EXTCODEHASH</code>, <code>EXTCODECOPY</code>, <code>CALLCODE</code>, <code>DELEGATECALL</code>) of any contract whose first byte is the <code>SET_INDESTRUCTIBLE</code> opcode is no longer banned. However, calls to anything but the <code>target</code> or a precompile that change the <code>callee</code> (i.e., calls other than <code>CALLCODE</code> and <code>DELEGATECALL</code>) are still not permitted.</p> <p>If the <a rel="external" href="http://github.com/ethereum/EIPs/pull/2975">IS_STATIC EIP</a> is added, the list of allowed prefixes can be extended to allow a prefix that enables incoming static calls but not state-changing calls.</p> <p>The list of allowed prefixes can also be extended to enable other benign use cases (eg. logging incoming payments).</p> <p>External calls <em>into</em> AA accounts can be allowed as follows. We can add an opcode <code>RESERVE_GAS</code>, which takes as argument a value <code>N</code> and has simple behavior: immediately burn <code>N</code> gas and add <code>N</code> gas to the refund. We then add an allowed <code>AA_PREFIX</code> that reserves <code>&gt;= AA_BASE_GAS_COST * 2</code> gas. This ensures that at least <code>AA_BASE_GAS_COST</code> gas must be spent (as refunds can refund max 50% of total consumption) in order to call into an account and invalidate transactions targeting that account in the mempool, preserving that invariant.</p> <p>Note that accounts may also opt to set a higher <code>RESERVE_GAS</code> value in order to safely have a higher <code>VERIFICATION_GAS_CAP</code>; the goal would be to preserve a <code>VERIFICATION_GAS_MULTIPLIER</code>-to-1 ratio between the minimum gas cost to edit an account (ie. half its <code>RESERVE_GAS</code>) and the <code>VERIFICATION_GAS_CAP</code> that is permitted that account. This would also preserve invariants around maximum reverification gas consumption that are implied by the previous section.</p> <h3 id="multi-tenant-beyond">Multi-Tenant &amp; Beyond</h3> <p>In a later stage, we can add support for multiple pending transactions per account in the mempool. The main challenge here is that a single transaction can potentially cause state changes that invalidate all other transactions to that same account. Additionally, if we naively prioritize transactions by gasprice, there is an attack vector where the user willing to pay the highest gasprice publishes many (mutually exclusive) versions of their transaction with small alterations, thereby pushing everyone else's transactions out of the mempool.</p> <p>Here is a sketch of a strategy for mitigating this problem. We would require incoming transactions to contain an <a rel="external" href="https://github.com/ethereum/EIPs/blob/master/EIPS/./02930.md">EIP-2930</a>-style access list detailing the storage slots that the transaction reads or modifies, and make it binding; that is, accesses outside the access list would be invalid. A transaction would only be included in the mempool if its access list is disjoint from the access lists of other transactions in the mempool (or if its gasprice is higher). An alternative way to think about this is to have per-storage-slot mempools instead of just per-account mempools, except a transaction could be part of multiple per-storage-slot mempools (if desired it could be capped to eg. 5 storage slots).</p> <p>Note also that multi-tenant AA will almost certainly require allowing miners to edit the nonces of incoming transactions to put them into sequence, with the result that the final hash of a transaction is unpredictable at publication time. Clients will need to explicitly work around this.</p> <p>More research is required to refine these ideas, and this is left for later work.</p> <h2 id="rationale">Rationale</h2> <p>The core problem in an account abstraction setup is always that miners and network nodes need to be able to verify that a transaction that they attempt to include, or rebroadcast, will actually pay a fee. Currently, this is fairly simple, because a transaction is guaranteed to be includable and pay a fee as long as the signature and nonce are valid and the balance and gasprice are sufficient. These checks can be done quickly.</p> <p>In an account abstraction setup, the goal is to allow accounts to specify EVM code that can establish more flexible conditions for a transaction's validity, but with the requirement that this EVM code can be quickly verified, with the same safety properties as the existing setup.</p> <p>In a normal transaction, the top-level call goes from the <code>tx.sender</code> to <code>tx.to</code> and carries with it <code>tx.value</code>. In an AA transaction, the top-level call goes from the <em>entry point address</em> (<code>0xFFFF...FF</code>) to the <code>tx.target</code>.</p> <p>The top-level code execution is expected to be split into two phases: the shorter <strong>verification phase</strong> (before <code>PAYGAS</code>) and the longer <strong>execution phase</strong> (after <code>PAYGAS</code>). If execution throws an exception during the verification phase, the transaction is invalid, much like a transaction with an invalid signature in the current system. If execution throws an exception after the verification phase, the transaction pays fees, and so the miner can still include it.</p> <p>The transition between different stages of AA is entirely done through changes in miner strategy. The first stage supports <strong>single-tenant AA</strong>, where the only use cases that can be easily implemented are where the <code>tx.target</code> is a contract representing a user account (that is, a smart contract wallet, eg. multisig). Later stages improve support for eg. logs and libraries, and also move toward supporting <strong>multi-tenant AA</strong>, where the goal is to try to support cases where the <code>tx.target</code> represents an <em>application</em> that processes incoming activity from multiple users.</p> <h3 id="nonces-still-enshrined-in-single-tenant-aa">Nonces still enshrined in single-tenant AA</h3> <p>Nonces are still enforced in single-tenant AA to ensure that single-target AA does not break the invariant that each transaction (and hence each transaction hash) can only be included in the chain once. While there is some limited value in allowing arbitrary-order transaction inclusion in single-tenant AA, there is not enough value to justify breaking that invariant.</p> <p>Note that nonces in AA accounts do end up having a dual-purpose: they are both there for replay protection and for contract address generation when using the <code>CREATE</code> opcode. This does mean that a single transaction could increment the nonce by more than 1. This is deemed acceptable, as the other mechanics introduced by AA already break the ability to easily verify that a chain longer than one transaction can be processed. However, we strongly recommend that AA contracts use <code>CREATE2</code> instead of <code>CREATE</code>.</p> <p>In multi-tenant AA, as mentioned above, nonces are expected to become malleable and applications that use multi-tenant AA systems would need to manage this.</p> <h3 id="nonces-are-exposed-to-the-evm">Nonces are exposed to the EVM</h3> <p>This is done to allow signature checking done in validation code to validate the nonce.</p> <h3 id="replay-protection-1">Replay Protection</h3> <p>One of the above two approaches (requiring <code>SET_INDESTRUCTIBLE</code> or modifying <code>SELFDESTRUCT</code> behavior) must be implemented so that nonces cannot be reused. It must be a consensus change, and not simply part of <code>AA_PREFIX</code>, so that transaction hash uniqueness is maintained.</p> <h3 id="miners-refuse-transactions-that-access-external-data-or-the-target-s-own-balance-before-paygas">Miners refuse transactions that access external data or the target's own balance, before PAYGAS</h3> <p>An important property of traditional transactions is that activity happening as part of transactions that originate outside of some given account X cannot make transactions whose sender is X invalid. The only state change that an outside transaction can impose on X is increasing its balance, which cannot invalidate a transaction.</p> <p>Allowing AA contracts to access external data (both other accounts and environment variables such as GASPRICE, DIFFICULTY, etc.) before they call <code>PAYGAS</code> (ie. during the verification phase) breaks this invariant. For example, imagine someone sends many thousands of AA transactions that perform an external call <code>if FOO.get_number() != 5: throw()</code>. <code>FOO.number</code> might be set to <code>5</code> when those transactions are all sent, but a single transaction to <code>FOO</code> could set the <code>number</code> to something else, invalidating <em>all of the thousands of AA transactions</em> that depend on it. This would be a serious DoS vector.</p> <p>The one allowed exception is contracts that are indestructible (that is, whose first byte is the <code>SET_INDESTRUCTIBLE</code> opcode defined in <a rel="external" href="https://hackmd.io/@HWeNw8hNRimMm2m2GH56Cw/SyNT3Cdmw">this EIP</a>). This is a safe exception, because the data that is being read cannot be changed.</p> <p>Disallowing reading <code>BALANCE</code> blocks a milder attack vector: an attacker could force a transaction to be reprocessed at a mere cost of 6700 gas (not 15000 or 21000), in the worst case more than doubling the number of transactions that would need to be reprocessed.</p> <p>In the long term, AA could be expanded to allow reading external data, though protections such as mandatory access lists would be required.</p> <h3 id="aa-transactions-must-call-contracts-with-prefix">AA transactions must call contracts with prefix</h3> <p>The prelude is used to ensure that <em>only</em> AA transactions can call the contract. This is another measure taken to ensure the invariant described above. If this check did not occur, it would be possible for a transaction originating outside some AA account X to call into X and make a storage change, forcing transactions targeting that account to be reprocessed at the cost of a mere 5000 gas.</p> <h3 id="multi-tenant-aa">Multi-tenant AA</h3> <p>Multi-tenant AA extends single-tenant AA by <strong>better handling cases where distinct and uncoordinated users attempt to send transactions for/to the same account and those transactions may interfere with each other</strong>.</p> <p>We can understand the value of multi-tenant AA by examining two example use cases: (i) <a rel="external" href="http://tornado.cash">tornado.cash</a> and (ii) <a rel="external" href="http://uniswap.exchange">Uniswap</a>. In both of these cases, there is a single central contract that represents the application, and not any specific user. Nevertheless, there is important value in using abstraction to do application-specific validation of transactions.</p> <h4 id="tornado-cash">Tornado Cash</h4> <p>The tornado.cash workflow is as follows:</p> <ol> <li>A user sends a transaction to the TC contract, depositing some standard quantity of coins (eg. 1 ETH). A record of their deposit, containing the hash of a secret known by the user, is added to a Merkle tree whose root is stored in the TC contract.</li> <li>When that user later wants to withdraw, they generate and send a ZK-SNARK proving that they know a secret whose hash is in a leaf somewhere in the deposit tree (without revealing where). The TC contract verifies the ZK-SNARK, and also verifies that a nullifier value (also derivable from the secret) has not yet been spent. The contract sends 1 ETH to the user's desired address, and saves a record that the user's nullifier has been spent.</li> </ol> <p>The privacy provided by TC arises because when a user makes a withdrawal, they can prove that it came from <em>some</em> unique deposit, but no one other than the user knows which deposit it came from. However, implementing TC naively has a fatal flaw: the user usually does not yet have ETH in their withdrawal address, and if the user uses their deposit address to pay for gas, that creates an on-chain link between their deposit address and their withdrawal address.</p> <p>Currently, this is solved via relayers; a third-party relayer verifies the ZK-SNARK and unspent status of the nullifier, publishes the transaction using their own ETH to pay for gas, and collects the fee back from the user from the TC contract.</p> <p>AA allows this without relayers: the user could simply send an AA transaction targeting the TC contract, the ZK-SNARK verification and the nullifier checking can be done in the verification step, and PAYGAS can be called directly after that. This allows the withdrawer to pay for gas directly out of the coins going to their withdrawal address, avoiding the need for relayers or for an on-chain link to their deposit address.</p> <p>Note that fully implementing this functionality requires AA to be structured in a way that supports multiple users sending withdrawals at the same time (requiring nonces would make this difficult), and that allows a single account to support both AA transactions (the withdrawals) and externally-initiated calls (the deposits).</p> <h4 id="uniswap">Uniswap</h4> <p>A new version of Uniswap could be built that allows transactions to be sent that directly target the Uniswap contract. Users could deposit tokens into Uniswap ahead of time, and Uniswap would store their balances as well as a public key that transactions spending those balances could be verified against. An AA-initiated Uniswap trade would only be able to spend these internal balances.</p> <p>This would be useless for normal traders, as normal traders have their coins outside the Uniswap contract, but it would be a powerful boon to arbitrageurs. Arbitrageurs would deposit their coins into Uniswap, and they would be able to send transactions that perform arbitrage every time external market conditions change, and logic such as price limits could be enforced during the verification step. Hence, transactions that do not get in (eg. because some other arbitrageur made the trade first) would not be included on-chain, allowing arbitrageurs to not pay gas, and reducing the number of "junk" transactions that get included on-chain. This could significantly increase both de-facto blockchain scalability as well as market efficiency, as arbitrageurs would be able to much more finely correct for cross-exchange discrepancies between prices.</p> <p>Note that here also, Uniswap would need to support both AA transactions and externally-initiated calls.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This AA implementation preserves the existing transaction type. The use of <code>assert origin == caller</code> to verify that an account is an EOA remains sound, but is not extensible to AA accounts; AA transactions will always have <code>origin == AA_ENTRY_POINT</code>.</p> <p>Badly-designed single-tenant AA contracts will break the transaction non-malleability invariant. That is, it is possible to take an AA transaction in-flight, modify it, and have the modified version still be valid; AA account contracts can be designed in such a way as to make that not possible, but it is their responsibility. Multi-tenant AA will break the transaction non-malleability invariant much more thoroughly, making the transaction hash unpredictable even for legitimate applications that use the multi-tenant AA features (though the invariant will not further break for applications that existed before then).</p> <p>AA contracts may not have replay protection unless they build it in explicitly; this can be done with the <code>CHAINID (0x46)</code> opcode introduced in <a href="https://wg-eips.ritovision.com/1344/">EIP 1344</a>.</p> <h2 id="test-cases">Test Cases</h2> <p>See: <a rel="external" href="https://github.com/quilt/tests/tree/account-abstraction">https://github.com/quilt/tests/tree/account-abstraction</a></p> <h2 id="implementation">Implementation</h2> <p>See: <a rel="external" href="https://github.com/quilt/go-ethereum/tree/account-abstraction">https://github.com/quilt/go-ethereum/tree/account-abstraction</a></p> <h2 id="security-considerations">Security Considerations</h2> <p>See <a rel="external" href="https://ethresear.ch/t/dos-vectors-in-account-abstraction-aa-or-validation-generalization-a-case-study-in-geth/7937">https://ethresear.ch/t/dos-vectors-in-account-abstraction-aa-or-validation-generalization-a-case-study-in-geth/7937</a> for an analysis of DoS issues.</p> <h3 id="re-validation">Re-validation</h3> <p>When a transaction enters the mempool, the client is able to quickly ascertain whether the transaction is valid. Once it determines this, it can be confident that the transaction will continue to be valid unless a transaction from the same account invalidates it.</p> <p>There are, however, cases where an attacker can publish a transaction that invalidates existing transactions and requires the network to perform more recomputation than the computation in the transaction itself. The EIP maintains the invariant that recomputation is bounded to a theoretical maximum of six times the block gas limit in a single block; this is somewhat more expensive than before, but not that much more expensive.</p> <h4 id="peer-denial-of-service">Peer denial-of-service</h4> <p>Denial-of-Service attacks are difficult to defend against, due to the difficulty in identifying sybils within a peer list. At any moment, one may decide (or be bribed) to initiate an attack. This is not a problem that Account Abstraction introduces. It can be accomplished against existing clients today by inundating a target with transactions whose signatures are invalid. However, due to the increased allotment of validation work allowed by AA, it's important to bound the amount of computation an adversary can force a client to expend with invalid transactions. For this reason, it's best for the miner to follow the recommended mining 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> 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 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 Sina Mahmoodihttps://github.com/s1na https://wg-eips.ritovision.com/2935/

Store and serve last 8191 block hashes as storage slots of a system contract to allow for stateless execution

<h2 id="abstract">Abstract</h2> <p>Store last <code>HISTORY_SERVE_WINDOW</code> historical block hashes in the storage of a system contract as part of the block processing logic. Furthermore this EIP has no impact on <code>BLOCKHASH</code> resolution mechanism (and hence its range/costs etc).</p> <h2 id="motivation">Motivation</h2> <p>EVM implicitly assumes the client has the recent block (hashes) at hand. This assumption is not future-proof given the prospect of stateless clients. Including the block hashes in the state will allow bundling these hashes in the witness provided to a stateless client. This is already possible in the MPT and will become more efficient post-Verkle.</p> <p>Extending the range of blocks which <code>BLOCKHASH</code> can serve (<code>BLOCKHASH_SERVE_WINDOW</code>) would have been a semantics change. Using extending that via this contract storage would allow a soft-transition. Rollups can benefit from the longer history window through directly querying this contract.</p> <p>A side benefit of this approach could be that it allows building/validating proofs related to last <code>HISTORY_SERVE_WINDOW</code> ancestors directly against the current state.</p> <h2 id="specification">Specification</h2> <table><thead><tr><th>Parameter</th><th>Value</th></tr></thead><tbody> <tr><td><code>BLOCKHASH_SERVE_WINDOW</code></td><td><code>256</code></td></tr> <tr><td><code>HISTORY_SERVE_WINDOW</code></td><td><code>8191</code></td></tr> <tr><td><code>SYSTEM_ADDRESS</code></td><td><code>0xfffffffffffffffffffffffffffffffffffffffe</code></td></tr> <tr><td><code>HISTORY_STORAGE_ADDRESS</code></td><td><code>0x0000F90827F1C53a10cb7A02335B175320002935</code></td></tr> </tbody></table> <p>This EIP specifies for storing last <code>HISTORY_SERVE_WINDOW</code> block hashes in a ring buffer storage of <code>HISTORY_SERVE_WINDOW</code> length. Note that <code>HISTORY_SERVE_WINDOW</code> &gt; <code>BLOCKHASH_SERVE_WINDOW</code> (which remains unchanged).</p> <h3 id="block-processing">Block processing</h3> <p>At the start of processing any block where this EIP is active (ie. before processing any transactions), call to <code>HISTORY_STORAGE_ADDRESS</code> as <code>SYSTEM_ADDRESS</code> with the 32-byte input of <code>block.parent.hash</code>, a gas limit of <code>30_000_000</code>, and <code>0</code> value. This will trigger the <code>set()</code> routine of the history contract. This is a system operation following the same convention as <a href="https://wg-eips.ritovision.com/4788/">EIP-4788</a> and therefore:</p> <ul> <li>the call must execute to completion</li> <li>the call does not count against the block's gas limit</li> <li>the call does not follow the <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> burn semantics - no value should be transferred as part of the call</li> <li>if no code exists at <code>HISTORY_STORAGE_ADDRESS</code>, the call must fail silently</li> </ul> <p>Note: Alternatively clients can choose to directly write to the storage of the contract but EVM calling the contract remains preferred. Refer to the rationale for more info.</p> <p>Note that, it will take <code>HISTORY_SERVE_WINDOW</code> blocks after the EIP's activation to completely fill up the ring buffer. The contract will only contain the parent hash of the fork block and no hashes prior to that.</p> <h3 id="evm-changes">EVM Changes</h3> <p>The <code>BLOCKHASH</code> opcode semantics remains the same as before.</p> <h3 id="block-hash-history-contract">Block hash history contract</h3> <p>The history contract has two operations: <code>get</code> and <code>set</code>. The <code>set</code> operation is invoked only when the <code>caller</code> is equal to the <code>SYSTEM_ADDRESS</code> as per <a href="https://wg-eips.ritovision.com/4788/">EIP-4788</a>. Otherwise the <code>get</code> operation is performed.</p> <h4 id="get"><code>get</code></h4> <p>It is used from the EVM for looking up block hashes.</p> <ul> <li>Callers provide the block number they are querying in a big-endian encoding.</li> <li>If calldata is not 32 bytes, revert.</li> <li>For any request outside the range of [block.number-<code>HISTORY_SERVE_WINDOW</code>, block.number-1], revert.</li> </ul> <h4 id="set"><code>set</code></h4> <ul> <li>Caller provides <code>block.parent.hash</code> as calldata to the contract.</li> <li>Set the storage value at <code>block.number-1 % HISTORY_SERVE_WINDOW</code> to be <code>calldata[0:32]</code>.</li> </ul> <h4 id="bytecode">Bytecode</h4> <p>Exact evm assembly that can be used for the history contract:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// https://github.com/lightclient/sys-asm/blob/f1c13e285b6aeef2b19793995e00861bf0f32c9a/src/execution_hash/main.eas</span></span> <span class="giallo-l"><span>caller</span></span> <span class="giallo-l"><span>push20 0xfffffffffffffffffffffffffffffffffffffffe</span></span> <span class="giallo-l"><span>eq</span></span> <span class="giallo-l"><span>push1 0x46</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"><span>push1 0x20</span></span> <span class="giallo-l"><span>calldatasize</span></span> <span class="giallo-l"><span>sub</span></span> <span class="giallo-l"><span>push1 0x42</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>calldataload</span></span> <span class="giallo-l"><span>push1 0x01</span></span> <span class="giallo-l"><span>number</span></span> <span class="giallo-l"><span>sub</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>gt</span></span> <span class="giallo-l"><span>push1 0x42</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"><span>push2 0x1fff</span></span> <span class="giallo-l"><span>dup2</span></span> <span class="giallo-l"><span>number</span></span> <span class="giallo-l"><span>sub</span></span> <span class="giallo-l"><span>gt</span></span> <span class="giallo-l"><span>push1 0x42</span></span> <span class="giallo-l"><span>jumpi</span></span> <span class="giallo-l"><span>push2 0x1fff</span></span> <span class="giallo-l"><span>swap1</span></span> <span class="giallo-l"><span>mod</span></span> <span class="giallo-l"><span>sload</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>mstore</span></span> <span class="giallo-l"><span>push1 0x20</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>return</span></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>revert</span></span> <span class="giallo-l"><span>jumpdest</span></span> <span class="giallo-l"><span>push0</span></span> <span class="giallo-l"><span>calldataload</span></span> <span class="giallo-l"><span>push2 0x1fff</span></span> <span class="giallo-l"><span>push1 0x01</span></span> <span class="giallo-l"><span>number</span></span> <span class="giallo-l"><span>sub</span></span> <span class="giallo-l"><span>mod</span></span> <span class="giallo-l"><span>sstore</span></span> <span class="giallo-l"><span>stop</span></span></code></pre><h4 id="deployment">Deployment</h4> <p>A special synthetic address is generated by working backwards from the desired deployment transaction:</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">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">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">to</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x3d090</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasPrice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe8d4a51000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxPriorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> null</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">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">input</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x60538060095f395ff33373fffffffffffffffffffffffffffffffffffffffe14604657602036036042575f35600143038111604257611fff81430311604257611fff9006545f5260205ff35b5f5ffd5b5f35611fff60014303065500</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">v</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">r</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x539</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">s</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xaa12693182426612186309f02cfe8a80a0000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x67139a552b0d3fffc30c0fa7d0c20d42144138c8fe07fc5691f09c1cce632e15</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Note, the input in the transaction has a simple constructor prefixing the desired runtime code.</p> <p>The sender of the transaction can be calculated as <code>0x3462413Af4609098e1E27A490f554f260213D685</code>. The address of the first contract deployed from the account is <code>rlp([sender, 0])</code> which equals <code>0x0000F90827F1C53a10cb7A02335B175320002935</code>. This is how <code>HISTORY_STORAGE_ADDRESS</code> is determined. Although this style of contract creation is not tied to any specific initcode like create2 is, the synthetic address is cryptographically bound to the input data of the transaction (e.g. the initcode).</p> <p>Some activation scenarios:</p> <ul> <li>For the fork to be activated at genesis, no history is written to the genesis state, and at the start of block <code>1</code>, genesis hash will be written as a normal operation to slot <code>0</code>.</li> <li>for activation at block <code>1</code>, only genesis hash will be written at slot <code>0</code>.</li> <li>for activation at block <code>32</code>, block <code>31</code>'s hash will be written to slot <code>31</code>. Every other slot will be <code>0</code>.</li> </ul> <h3 id="eip-161-handling"><a href="https://wg-eips.ritovision.com/161/">EIP-161</a> handling</h3> <p>The bytecode above will be deployed à la <a href="https://wg-eips.ritovision.com/4788/">EIP-4788</a>. As such the account at <code>HISTORY_STORAGE_ADDRESS</code> will have code and a nonce of 1, and will be exempt from EIP-161 cleanup.</p> <h3 id="gas-costs">Gas costs</h3> <p>The system update at the beginning of the block, i.e. <code>process_block_hash_history</code> (or via system call to the contract with <code>SYSTEM_ADDRESS</code> caller), will not warm the <code>HISTORY_STORAGE_ADDRESS</code> account or its storage slots as per <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a> rules. As such the first call to the contract will pay for warming up the account and storage slots it accesses.To clarify further any contract call to the <code>HISTORY_STORAGE_ADDRESS</code> will follow normal EVM execution semantics.</p> <p>Since <code>BLOCKHASH</code> semantics doesn't change, this EIP has no impact on <code>BLOCKHASH</code> mechanism and costs.</p> <h2 id="rationale">Rationale</h2> <p>Very similar ideas were proposed before. This EIP is a simplification, removing two sources of needless complexity:</p> <ol> <li>Having a tree-like structure with multiple layers as opposed to a single list</li> <li>Writing the EIP in EVM code</li> <li>Serial unbounded storage of hashes for a deep access to the history</li> </ol> <p>However after weighing pros and cons, we decided to go with just a limited ring buffer to only serve the requisite <code>HISTORY_SERVE_WINDOW</code> as <a href="https://wg-eips.ritovision.com/4788/">EIP-4788</a> and beacon state accumulators allow (albeit a bit more complex) proof against any ancestor since merge.</p> <p>Second concern was how to best transition the BLOCKHASH resolution logic post fork by:</p> <ol> <li>Either waiting for <code>HISTORY_SERVE_WINDOW</code> blocks for the entire relevant history to persist</li> <li>Storing of all last <code>HISTORY_SERVE_WINDOW</code> block hashes on the fork block.</li> </ol> <p>We choose to go with the former. It simplifies the logic greatly. It will take roughly a day to bootstrap the contract. Given that this is a new way of accessing history and no contract depends on it, it is deemed a favorable tradeoff.</p> <h3 id="inserting-the-parent-block-hash">Inserting the parent block hash</h3> <p>Clients have generally two options for inserting the parent block hash into state:</p> <ol> <li>Performing a system call to <code>HISTORY_STORAGE_ADDRESS</code> and letting that handle the storing in state.</li> <li>Avoid EVM processing and directly write to the state trie.</li> </ol> <p>The latter option 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"> process_block_hash_history</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>:</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_TIMESTAMP</span><span>:</span><span class="z-keyword"> //</span><span class="z-constant"> FORK_TIMESTAMP</span><span> should</span><span> be</span><span> defined</span><span> outside</span><span> of</span><span> the</span><span class="z-constant"> EIP</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>insert_slot</span><span>(</span><span class="z-constant">HISTORY_STORAGE_ADDRESS</span><span>,</span><span> (</span><span>block</span><span>.</span><span>number</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>)</span><span class="z-keyword"> %</span><span class="z-constant"> HISTORY_SERVE_WINDOW</span><span> ,</span><span> block</span><span>.</span><span>parent</span><span>.</span><span>hash</span><span>)</span></span></code></pre> <p>The first option is recommended until the Verkle fork, to stay consistent with <a href="https://wg-eips.ritovision.com/4788/">EIP-4788</a> and to issues for misconfigured networks where this EIP is activated but history contract hasn't been deployed. The recommendation may be reconsidered at the Verkle fork if filtering the system contract code chunks is deemed too complex.</p> <h3 id="size-of-ring-buffers">Size of ring buffers</h3> <p>The ring buffer data structure is sized to hold 8191 hashes. In other system contracts a prime ring buffer size is chosen in because using a prime as the modulus ensures that no value is overwritten until the entire ring buffer has been saturated and thereafter, each value will be updated once per iteration, regardless of if some slot are missing or the slot time changes. However, in this EIP the block number is the value in the modulo operation and it only ever increases by 1 each iteration. Which means we can be confident that the ring buffer will always remain saturated.</p> <p>For consistency with other system contracts, we have decided to retain the buffer size of 8191. Given the current mainnet values, 8191 roots provides about a day of coverage. This also gives users plenty of time to make a transaction with a verification against a specific hash and get the transaction included on-chain.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces backwards incompatible changes to the block validation rule set. But neither of these changes break anything related to current user activity and experience.</p> <h2 id="test-cases">Test Cases</h2> <p><a rel="external" href="https://github.com/ethereum/execution-spec-tests/tree/3810d22f84f206866f66f4f6bf856187c2893ab1/tests/prague/eip2935_historical_block_hashes_from_state">EIP-2935 Execution Spec Tests</a></p> <h2 id="security-considerations">Security Considerations</h2> <p>Having contracts (system or otherwise) with hot update paths (branches) poses a risk of "branch" poisoning attacks where attacker could sprinkle trivial amounts of eth around these hot paths (branches). But it has been deemed that cost of attack would escalate significantly to cause any meaningful slow down of state root updates.</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 Vitalik Buterinhttps://github.com/vbuterin Martin Swendehttps://github.com/holiman https://wg-eips.ritovision.com/2929/ <h2 id="simple-summary">Simple Summary</h2> <p>Increases gas cost for <code>SLOAD</code>, <code>*CALL</code>, <code>BALANCE</code>, <code>EXT*</code> and <code>SELFDESTRUCT</code> when used for the first time in a transaction.</p> <h2 id="abstract">Abstract</h2> <p>Increase the gas cost of <code>SLOAD</code> (<code>0x54</code>) to 2100, and the <code>*CALL</code> opcode family (<code>0xf1</code>, <code>f2</code>, <code>f4</code>, <code>fA</code>), <code>BALANCE</code> <code>0x31</code> and the <code>EXT*</code> opcode family (<code>0x3b</code>, <code>0x3c</code>, <code>0x3f</code>) to 2600. Exempts (i) precompiles, and (ii) addresses and storage slots that have already been accessed in the same transaction, which get a decreased gas cost. Additionally reforms <code>SSTORE</code> metering and <code>SELFDESTRUCT</code> to ensure "de-facto storage loads" inherent in those opcodes are priced correctly.</p> <h2 id="motivation">Motivation</h2> <p>Generally, the main function of gas costs of opcodes is to be an estimate of the time needed to process that opcode, the goal being for the gas limit to correspond to a limit on the time needed to process a block. However, storage-accessing opcodes (<code>SLOAD</code>, as well as the <code>*CALL</code>, <code>BALANCE</code> and <code>EXT*</code> opcodes) have historically been underpriced. In the 2016 Shanghai DoS attacks, once the most serious client bugs were fixed, one of the more durably successful strategies used by the attacker was to simply send transactions that access or call a large number of accounts.</p> <p>Gas costs were increased to mitigate this, but recent numbers suggest they were not increased enough. Quoting <a rel="external" href="https://arxiv.org/pdf/1909.07220.pdf">https://arxiv.org/pdf/1909.07220.pdf</a>:</p> <blockquote> <p>Although by itself, this issue might seem benign, <code>EXTCODESIZE</code> forces the client to search the contract ondisk, resulting in IO heavy transactions. While replaying the Ethereum history on our hardware, the malicious transactions took around 20 to 80 seconds to execute, compared to a few milliseconds for the average transactions</p> </blockquote> <p>This proposed EIP increases the costs of these opcodes by a factor of ~3, reducing the worst-case processing time to ~7-27 seconds. Improvements in database layout that involve redesigning the client to read storage directly instead of hopping through the Merkle tree would decrease this further, though these technologies may take a long time to fully roll out, and even with such technologies the IO overhead of accessing storage would remain substantial.</p> <p>A secondary benefit of this EIP is that it also performs most of the work needed to make <a rel="external" href="https://ethereum-magicians.org/t/protocol-changes-to-bound-witness-size/3885">stateless witness sizes</a> in Ethereum acceptable. Assuming <a rel="external" href="https://ethresear.ch/t/binary-trie-format/7621">a switch to binary tries</a>, the theoretical maximum witness size not including code size (hence "most of the work" and not "all") would decrease from <code>(12500000 gas limit) / (700 gas per BALANCE) * (800 witness bytes per BALANCE) ~= 14.3M bytes</code> to <code>12500000 / 2600 * 800 ~= 3.85M bytes</code>. Pricing for code access could be changed when code merklization is implemented.</p> <p>In the further future, there are similar benefits in the case of SNARK/STARK witnesses. Recent numbers from Starkware suggest that they are able to prove 10000 Rescue hashes per second on a consumer desktop; assuming 25 hashes per Merkle branch, and a block full of state accesses, at present this would imply a witness would take <code>12500000 / 700 * 25 / 10000 ~= 44.64</code> seconds to generate, but after this EIP that would reduce to <code>12500000 / 2500 * 25 / 10000 ~= 12.5</code> seconds, meaning that a single desktop computer would be able to generate witnesses on time under any conditions. Future gains in STARK proving could be spent on either (i) using a more expensive but robust hash function or (ii) reducing proving times further, reducing the delay and hence improving user experience of stateless clients that rely on such witnesses.</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>12244000</td></tr> <tr><td><code>COLD_SLOAD_COST</code></td><td>2100</td></tr> <tr><td><code>COLD_ACCOUNT_ACCESS_COST</code></td><td>2600</td></tr> <tr><td><code>WARM_STORAGE_READ_COST</code></td><td>100</td></tr> </tbody></table> <p>For blocks where <code>block.number &gt;= FORK_BLOCK</code>, the following changes apply.</p> <p>When executing a transaction, maintain a set <code>accessed_addresses: Set[Address]</code> and <code>accessed_storage_keys: Set[Tuple[Address, Bytes32]]</code> .</p> <p>The sets are transaction-context-wide, implemented identically to other transaction-scoped constructs such as the self-destruct-list and global <code>refund</code> counter. In particular, if a scope reverts, the access lists should be in the state they were in before that scope was entered.</p> <p>When a transaction execution begins,</p> <ul> <li><code>accessed_storage_keys</code> is initialized to empty, and</li> <li><code>accessed_addresses</code> is initialized to include <ul> <li>the <code>tx.sender</code>, <code>tx.to</code> (or the address being created if it is a contract creation transaction)</li> <li>and the set of all precompiles.</li> </ul> </li> </ul> <h3 id="storage-read-changes">Storage read changes</h3> <p>When an address is either the target of a (<code>EXTCODESIZE</code> (<code>0x3B</code>), <code>EXTCODECOPY</code> (<code>0x3C</code>), <code>EXTCODEHASH</code> (<code>0x3F</code>) or <code>BALANCE</code> (<code>0x31</code>)) opcode or the target of a (<code>CALL</code> (<code>0xF1</code>), <code>CALLCODE</code> (<code>0xF2</code>), <code>DELEGATECALL</code> (<code>0xF4</code>), <code>STATICCALL</code> (<code>0xFA</code>)) opcode, the gas costs are computed as follows:</p> <ul> <li>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>.</li> <li>Otherwise, charge <code>WARM_STORAGE_READ_COST</code> gas.</li> </ul> <p>In all cases, the gas cost is charged and the map is updated at the time that the opcode is being called. When a <code>CREATE</code> or <code>CREATE2</code> opcode is called, immediately (ie. before checks are done to determine whether or not the address is unclaimed) add the address being created to <code>accessed_addresses</code>, but gas costs of <code>CREATE</code> and <code>CREATE2</code> are unchanged. Clarification: If a <code>CREATE</code>/<code>CREATE2</code> operation fails later on, e.g during the execution of <code>initcode</code> or has insufficient gas to store the code in the state, the <code>address</code> of the contract itself remains in <code>access_addresses</code> (but any additions made within the inner scope are reverted).</p> <p>For <code>SLOAD</code>, if the <code>(address, storage_key)</code> pair (where <code>address</code> is the address of the contract whose storage is being read) is not yet in <code>accessed_storage_keys</code>, charge <code>COLD_SLOAD_COST</code> gas and add the pair to <code>accessed_storage_keys</code>. If the pair is already in <code>accessed_storage_keys</code>, charge <code>WARM_STORAGE_READ_COST</code> gas.</p> <p>Note: For call-variants, the <code>100</code>/<code>2600</code> cost is applied immediately (exactly like how <code>700</code> was charged before this EIP), i.e: before calculating the <code>63/64ths</code> available for entering the call.</p> <p>Note 2: There is currently no way to perform a 'cold sload read/write' on a 'cold account', simply because in order to read/write a <code>slot</code>, the execution must already be inside the <code>account</code>. Therefore, the behaviour of cold storage reads/writes on cold accounts is undefined as of this EIP. Any future EIP which proposes to add 'remote read/write' would need to define the pricing behaviour of that change.</p> <h3 id="sstore-changes">SSTORE changes</h3> <p>When calling <code>SSTORE</code>, check if the <code>(address, storage_key)</code> pair is in <code>accessed_storage_keys</code>. If it is not, charge an additional <code>COLD_SLOAD_COST</code> gas, and add the pair to <code>accessed_storage_keys</code>. Additionally, modify the parameters defined in <a href="https://wg-eips.ritovision.com/2200/">EIP-2200</a> as follows:</p> <table><thead><tr><th>Parameter</th><th>Old value</th><th>New value</th></tr></thead><tbody> <tr><td><code>SLOAD_GAS</code></td><td>800</td><td><code>= WARM_STORAGE_READ_COST</code></td></tr> <tr><td><code>SSTORE_RESET_GAS</code></td><td>5000</td><td><code>5000 - COLD_SLOAD_COST</code></td></tr> </tbody></table> <p>The other parameters defined in EIP 2200 are unchanged. Note: The constant <code>SLOAD_GAS</code> is used in several places in EIP 2200, e.g <code>SSTORE_SET_GAS - SLOAD_GAS</code>. Implementations that are using composite definitions have to ensure to update those definitions too.</p> <h3 id="selfdestruct-changes">SELFDESTRUCT changes</h3> <p>If the ETH recipient of a <code>SELFDESTRUCT</code> is not in <code>accessed_addresses</code> (regardless of whether or not the amount sent is nonzero), charge an additional <code>COLD_ACCOUNT_ACCESS_COST</code> on top of the existing gas costs, and add the ETH recipient to the set.</p> <p>Note: <code>SELFDESTRUCT</code> does not charge a <code>WARM_STORAGE_READ_COST</code> in case the recipient is already warm, which differs from how the other call-variants work. The reasoning behind this is to keep the changes small, a <code>SELFDESTRUCT</code> already costs <code>5K</code> and is a no-op if invoked more than once.</p> <h2 id="rationale">Rationale</h2> <h3 id="opcode-costs-vs-charging-per-byte-of-witness-data">Opcode costs vs charging per byte of witness data</h3> <p>The natural alternative path to changing gas costs to reflect witness sizes is to charge per byte of witness data. However, that would take a longer time to implement, hampering the goal of providing short-term security relief. Furthermore, following that path faithfully would lead to extremely high gas costs to transactions that touch contract code, as one would need to charge for all 24576 contract code bytes; this would be an unacceptably high burden on developers. It is better to wait for <a rel="external" href="https://medium.com/ewasm/evm-bytecode-merklization-2a8366ab0c90">code merklization</a> to start trying to properly account for gas costs of accessing individual chunks of code; from a short-term DoS prevention standpoint, accessing 24 kB from disk is not much more expensive than accessing 32 bytes from disk, so worrying about code size is not necessary.</p> <h3 id="adding-the-accessed-addresses-accessed-storage-keys-sets">Adding the accessed_addresses / accessed_storage_keys sets</h3> <p>The sets of already-accessed accounts and storage slots are added to avoid needlessly charging for things that can be cached (and in all performant implementations already are cached). Additionally, it removes the current undesirable status quo where it is needlessly unaffordable to do self-calls or call precompiles, and enables contract breakage mitigations that involve pre-fetching some storage key allowing a future execution to still take the expected amount of gas.</p> <h3 id="sstore-gas-cost-change">SSTORE gas cost change</h3> <p>The change to SSTORE is needed to avoid the possibility of a DoS attack that "pokes" a randomly chosen zero storage slot, changing it from 0 to 0 at a cost of 800 gas but requiring a de-facto storage load. The <code>SSTORE_RESET_GAS</code> reduction ensures that the total cost of SSTORE (which now requires paying the <code>COLD_SLOAD_COST</code>) remains unchanged. Additionally, note that applications that do <code>SLOAD</code> followed by <code>SSTORE</code> (eg. <code>storage_variable += x</code>) <em>would actually get cheaper</em>!</p> <h3 id="change-sstore-accounting-only-minimally">Change SSTORE accounting only minimally</h3> <p>The SSTORE gas costs continue to use Wei Tang's original/current/new approach, instead of being redesigned to use a dirty map, because Wei Tang's approach correctly accounts for the actual costs of changing storage, which only care about current vs final value and not intermediate values.</p> <h3 id="how-would-gas-consumption-of-average-applications-increase-under-this-proposal">How would gas consumption of average applications increase under this proposal?</h3> <h4 id="rough-analysis-from-witness-sizes">Rough analysis from witness sizes</h4> <p>We can look at <a rel="external" href="https://medium.com/@akhounov/data-from-the-ethereum-stateless-prototype-8c69479c8abc">Alexey Akhunov's earlier work</a> for data on average-case blocks. In summary, average blocks have witness sizes of ~1000 kB, of which ~750 kB is Merkle proofs and not code. Assuming a conservative 2000 bytes per Merkle branch this implies ~375 accesses per block (SLOADs have a similar gas-increase-to-bytes ratio so there's no need to analyze them separately).</p> <p>Data on <a rel="external" href="https://etherscan.io/chart/tx">txs per day</a> and <a rel="external" href="https://etherscan.io/chart/blocks">blocks per day</a> from Etherscan gives ~160 transactions per block (reference date: Jul 1), implying a large portion of those accesses are just the <code>tx.sender</code> and <code>tx.to</code> which are excluded from gas cost increases, though likely less than 320 due to duplicate addresses.</p> <p>Hence, this implies ~50-375 chargeable accesses per block, and each access suffers a gas cost increase of 1900; <code>50 * 1900 = 95000</code> and <code>375 * 1900 = 712500</code>, implying the gas limit would need to be raised by ~1-6% to compensate. However, this analysis may be complicated further in either direction by (i) accounts / storage keys being accessed in multiple transactions, which would appear once in the witness but twice in gas cost increases, and (ii) accounts / storage keys being accessed multiple times in the same transaction, which lead to gas cost <em>decreases</em>.</p> <h4 id="goerli-analysis">Goerli analysis</h4> <p>A more precise analysis can be found by scanning Goerli transactions, as done by Martin Swende here: https://github.com/holiman/gasreprice</p> <p>The conclusion is that on average gas costs increase by ~2.36%. One major contributing factor to reducing gas costs is that a large number of contracts inefficiently read the same storage slot multiple times, which leads to this EIP giving a few transactions gas cost <em>savings</em> of over 10%.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>These gas cost increases may potentially break contracts that depend on fixed gas costs; see the security considerations section for details and arguments for why we expect the total risks to be low and how if desired they can be reduced further.</p> <h2 id="test-cases">Test Cases</h2> <p>Some test cases can be found here: https://gist.github.com/holiman/174548cad102096858583c6fbbb0649a</p> <p>Ideally we would test the following:</p> <ul> <li>SLOAD the same storage slot {1, 2, 3} times</li> <li>CALL the same address {1, 2, 3} times</li> <li>(SLOAD | CALL) in a sub-call, then revert, then (SLOAD | CALL) the same (storage slot | address) again</li> <li>Sub-call, SLOAD, sub-call again, revert the inner sub-call, SLOAD the same storage slot</li> <li>SSTORE the same storage slot {1, 2, 3} times, using all combinations of zero/nonzero for original value and the value being set</li> <li>SSTORE then SLOAD the same storage slot</li> <li><code>OP_1</code> then <code>OP_2</code> to the same address where <code>OP_1</code> and <code>OP_2</code> are all combinations of (<code>*CALL</code>, <code>EXT*</code>, <code>SELFDESTRUCT</code>)</li> <li>Try to <code>CALL</code> an address but with all possible failure modes (not enough gas, not enough ETH...), then (<code>CALL</code> | <code>EXT*</code>) that address again successfully</li> </ul> <h2 id="implementation">Implementation</h2> <p>A WIP early-draft implementation for Geth can be found here: https://github.com/holiman/go-ethereum/tree/access_lists</p> <h2 id="security-considerations">Security Considerations</h2> <p>As with any gas cost increasing EIP, there are three possible cases where it could cause applications to break:</p> <ol> <li>Fixed gas limits to sub-calls in contracts</li> <li>Applications relying on contract calls that consume close to the full gas limit</li> <li>The 2300 base limit given to the callee by ETH-transferring calls</li> </ol> <p>These risks have been studied before in the context of an earlier gas cost increase, EIP-1884. See <a rel="external" href="https://github.com/holiman/eip-1884-security">Martin Swende's earlier report</a> and <a rel="external" href="https://gist.github.com/ritzdorf/1c6bd72955391e831f8a397d3152b4e0/">Hubert Ritzdorf's analysis</a> focusing on (1) and (3). (2) has received less analysis, though one can argue that it is very unlikely both because applications tend to very rarely use close to the entire gas limit in a transaction, and because gas limits were very recently raised from 10 million to 12.5 million. EIP-1884 in practice <a rel="external" href="https://www.coindesk.com/ethereums-istanbul-upgrade-will-break-680-smart-contracts-on-aragon">did lead to a small number of contracts breaking</a> for this reason.</p> <p>There are two ways to look at these risks. First, we can note that as of today developers have had years of warning; gas cost increases on storage-accessing opcodes have been <a rel="external" href="https://ethereum-magicians.org/t/protocol-changes-to-bound-witness-size/3885">discussed for a long time</a>, with multiple statements made including to major dapp developers around the likelihood of such changes. EIP-1884 itself provided an important wake-up call. Hence, we can argue that risks this time will be significantly lower than EIP-1884.</p> <h3 id="contract-breakage-mitigations">Contract breakage mitigations</h3> <p>A second way to look at the risks is to explore mitigations. First of all, the existence of an <code>accessed_addresses</code> and <code>accessed_storage_keys</code> map (present in this EIP, absent in EIP-1884) already makes some cases recoverable: in any case where a contract A needs to send funds to some address B, where that address accepts funds from any source but leaves a storage-dependent log, one can recover by first sending a separate call to B to pull it into the cache, and then call A, knowing that the execution of B triggered by A will only charge 100 gas per SLOAD. This fact does not fix all situations, but it does reduce risks significantly.</p> <p>But there are ways to further expand the usability of this pattern. One possibility is to add a <code>POKE</code> precompile, which would take an address and a storage key as input and allow transactions that attempt to "rescue" stuck contracts by pre-poking all of the storage slots that they will access. This works even if the address only accepts transactions from the contract, and works in many other contexts with present gas limits. The only case where this will not work would be the case where a transaction call <em>must</em> go from an EOA straight into a specific contract that then sub-calls another contract.</p> <p>Another option is <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a>, which would have a similar effect to <code>POKE</code> but is more general: it also works for the EOA -&gt; contract -&gt; contract case, and generally should work for all known cases of breakage due to gas cost increases. This option is more complex, though it is arguably a stepping stone toward access lists being used for other use cases (regenesis, account abstraction, SSA all demand access lists).</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-29T00: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/2930/ <h2 id="simple-summary">Simple Summary</h2> <p>Adds a transaction type which contains an access list, a list of addresses and storage keys that the transaction plans to access. Accesses outside the list are possible, but become more expensive.</p> <h2 id="abstract">Abstract</h2> <p>We introduce a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction type, with the format <code>0x01 || rlp([chainId, nonce, gasPrice, gasLimit, to, value, data, accessList, signatureYParity, signatureR, signatureS])</code>.</p> <p>The <code>accessList</code> specifies a list of addresses and storage keys; these addresses and 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>). A gas cost is charged, though at a discount relative to the cost of accessing outside the list.</p> <h2 id="motivation">Motivation</h2> <p>This EIP serves two functions:</p> <ol> <li>Mitigates contract breakage risks introduced by <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>, as transactions could pre-specify and pre-pay for the accounts and storage slots that the transaction plans to access; as a result, in the actual execution, the SLOAD and EXT* opcodes would only cost 100 gas: low enough that it would not only prevent breakage due to that EIP but also "unstuck" any contracts that became stuck due to EIP 1884.</li> <li>Introduces the access list format and the logic for handling the format. This logic can later be repurposed for many other purposes, including block-wide witnesses, use in ReGenesis, moving toward static state access over time, and more.</li> </ol> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions</h3> <p><strong><code>TransactionType</code></strong> <code>1</code>. See <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a></p> <p><strong><code>ChainId</code></strong> The transaction only valid on networks with this <code>chainID</code>.</p> <p><strong><code>YParity</code></strong> The parity (0 for even, 1 for odd) of the y-value of a secp256k1 signature.</p> <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>12244000</td></tr> <tr><td><code>ACCESS_LIST_STORAGE_KEY_COST</code></td><td>1900</td></tr> <tr><td><code>ACCESS_LIST_ADDRESS_COST</code></td><td>2400</td></tr> </tbody></table> <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>1</code>.</p> <p>The <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> <code>TransactionPayload</code> for this transaction is <code>rlp([chainId, nonce, gasPrice, gasLimit, to, value, data, accessList, signatureYParity, signatureR, signatureS])</code>.</p> <p>The <code>signatureYParity, signatureR, signatureS</code> elements of this transaction represent a secp256k1 signature over <code>keccak256(0x01 || rlp([chainId, nonce, gasPrice, gasLimit, to, value, data, accessList]))</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, cumulativeGasUsed, logsBloom, logs])</code>.</p> <p>For the transaction to be valid, <code>accessList</code> must be of type <code>[[{20 bytes}, [{32 bytes}...]]...]</code>, where <code>...</code> means "zero or more of the thing to the left". For example, the following is a valid access list (all hex strings would in reality be in byte representation):</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> &quot;0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae&quot;,</span></span> <span class="giallo-l"><span> [</span></span> <span class="giallo-l"><span> &quot;0x0000000000000000000000000000000000000000000000000000000000000003&quot;,</span></span> <span class="giallo-l"><span> &quot;0x0000000000000000000000000000000000000000000000000000000000000007&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> &quot;0xbb9bc244d798123fde783fcc1c72d3bb8c189413&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>At the beginning of execution (ie. at the same time as the <code>21000 + 4 * zeroes + 16 * nonzeroes</code> start gas is charged according to <a href="https://wg-eips.ritovision.com/2028/">EIP-2028</a> rules), we charge additional gas for the access list: <code>ACCESS_LIST_ADDRESS_COST</code> gas per address and <code>ACCESS_LIST_STORAGE_KEY_COST</code> gas per storage key. For example, the above example would be charged <code>ACCESS_LIST_ADDRESS_COST * 2 + ACCESS_LIST_STORAGE_KEY_COST * 2</code> gas.</p> <p>Note that non-unique addresses and storage keys are not disallowed, though they will be charged for multiple times, and aside from the higher gas cost there is no other difference in execution flow or outcome from multiple-inclusion of a value as opposed to the recommended single-inclusion.</p> <p>The address and storage keys would be immediately loaded into the <code>accessed_addresses</code> and <code>accessed_storage_keys</code> global sets; this can be done using the following logic (which doubles as a specification-in-code of validation of the RLP-decoded access list)</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_access_list</span><span>(</span><span class="z-variable z-parameter z-function">access_list</span><span>)</span><span> -&gt;</span><span> Tuple</span><span>[</span><span>List</span><span>[</span><span>Set</span><span>[</span><span>Address</span><span>]</span><span>,</span><span> Set</span><span>[</span><span>Pair</span><span>[</span><span>Address</span><span>,</span><span> Bytes32</span><span>]</span><span>]</span><span>]</span><span>,</span><span class="z-support"> int</span><span>]</span><span>:</span></span> <span class="giallo-l"><span> accessed_addresses</span><span class="z-keyword"> =</span><span class="z-support"> set</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> accessed_storage_keys</span><span class="z-keyword"> =</span><span class="z-support"> set</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> gas_cost</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> isinstance</span><span>(</span><span>access_list</span><span>,</span><span class="z-support"> list</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> item</span><span class="z-keyword"> in</span><span> access_list</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> isinstance</span><span>(</span><span>item</span><span>,</span><span class="z-support"> list</span><span>)</span><span class="z-keyword"> and</span><span class="z-support"> len</span><span>(</span><span>item</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 2</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Validate and add the address</span></span> <span class="giallo-l"><span> address</span><span class="z-keyword"> =</span><span> item</span><span>[</span><span class="z-constant">0</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> isinstance</span><span>(</span><span>address</span><span>,</span><span class="z-support"> bytes</span><span>)</span><span class="z-keyword"> and</span><span class="z-support"> len</span><span>(</span><span>address</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 20</span></span> <span class="giallo-l"><span> accessed_addresses</span><span>.</span><span>add</span><span>(</span><span>address</span><span>)</span></span> <span class="giallo-l"><span> gas_cost</span><span class="z-keyword"> +=</span><span class="z-constant"> ACCESS_LIST_ADDRESS_COST</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Validate and add the storage keys</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> isinstance</span><span>(</span><span>item</span><span>[</span><span class="z-constant">1</span><span>]</span><span>,</span><span class="z-support"> list</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> key</span><span class="z-keyword"> in</span><span> item</span><span>[</span><span class="z-constant">1</span><span>]</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> isinstance</span><span>(</span><span>key</span><span>,</span><span class="z-support"> bytes</span><span>)</span><span class="z-keyword"> and</span><span class="z-support"> len</span><span>(</span><span>key</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 32</span></span> <span class="giallo-l"><span> accessed_storage_keys</span><span>.</span><span>add</span><span>(</span><span>(</span><span>address</span><span>,</span><span> key</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> gas_cost</span><span class="z-keyword"> +=</span><span class="z-constant"> ACCESS_LIST_STORAGE_KEY_COST</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span></span> <span class="giallo-l"><span> accessed_addresses</span><span>,</span></span> <span class="giallo-l"><span> accessed_storage_keys</span><span>,</span></span> <span class="giallo-l"><span> gas_cost</span></span> <span class="giallo-l"><span> )</span></span></code></pre> <p>The access list is NOT charged per-byte fees like tx data is; the per-item costs described above are meant to cover the bandwidth costs of the access list data in addition to the costs of accessing those accounts and storage keys when evaluating the transaction.</p> <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>This is done to encourage transactions to use the access list as much as possible, and because processing transactions is easier when their storage reads are predictable (because clients can pre-load the data from databases and/or ask for witnesses at the time the transaction is received, or at least load the data in parallel).</p> <h3 id="allowing-duplicates">Allowing duplicates</h3> <p>This is done because it maximizes simplicity, avoiding questions of what to prevent duplication against: just between two addresses/keys in the access list, between the access list and the tx sender/recipient/newly created contract, other restrictions? Because gas is charged per item, there is no gain and only cost in including a value in the access list twice, so this should not lead to extra chain bloat in practice.</p> <h3 id="signature-signs-over-the-transaction-type-as-well-as-the-transaction-data">Signature signs over the transaction type as well as the transaction data</h3> <p>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>This EIP does make it more gas-expensive to perform "unexpected" SLOADs and account accesses. Because gas is prepaid and so does not affect fixed-gas local calls, it does not break contracts in the way that previous gas cost increases would risk. However, it does make applications that heavily rely on storage access much less economically viable.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="access-list-generation">Access list generation</h3> <p>Access lists are difficult to construct in real-time in many situations, and this is exacerbated in environments where there is a high time lag between transaction generation and signing or simplicity of the transaction generator is highly valued (eg. either or both may apply in hardware wallets).</p> <p>However, this EIP proposes only a 10% initial discount to access lists, so there is almost no cost to not bothering with access list generation and only making a simple transaction. The cost of accessing state outside the access list is expected to be ramped up in future hard forks over time as tools are developed and access list generation becomes more mature.</p> <h3 id="transaction-size-bloating">Transaction size bloating</h3> <p>Average block size will increase as a result of access lists being used. However, the per-byte cost of access lists is <code>1900 / 32 = 59.375</code> for storage keys and <code>2400 / 20 = 120</code> for addresses, making it much more expensive than calldata; hence, worst-case block size will not increase. Additionally, increases in average block size will be partially compensated for by the ability to pre-fetch storage at time of receiving a transaction and/or load storage in parallel upon receiving a block.</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_i denotes individual productivity of the user U between the consecutive block numbers t_i-1 and t_i, ∆P_i denotes global productivity between the consecutive block numbers t_i-1 and t_i, and ∆G_i denotes gross product between the consecutive block numbers t_i-1 and t_i. 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-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 Sina Mahmoodihttps://github.com/s1na Alex Beregszaszihttps://github.com/axic Guillaume Ballethttps://github.com/gballet Jochem Brouwerhttps://github.com/jochem-brouwer Ignacio Hagopianhttps://github.com/jsign https://wg-eips.ritovision.com/2926/

Introduce code-chunking in an MPT context.

<h2 id="abstract">Abstract</h2> <p>Code merkleization, along with binarification of the trie and gas cost bump of state-accessing opcodes, are considered as the main levers for decreasing block witness sizes in stateless or partial-stateless Eth1x roadmaps. Here we specify a fixed-sized chunk approach to code merkleization and outline how the transition of existing contracts to this model would look like.</p> <h2 id="motivation">Motivation</h2> <p>Bytecode is currently the second contributor to block witness size, after the proof hashes. Transitioning the trie from hexary to binary reduces the hash section of the witness by 3x, thereby making code the first contributor. By breaking contract code into chunks and committing to those chunks in a merkle tree, stateless clients would only need the chunks that were touched during a given transaction to execute it.</p> <h2 id="specification">Specification</h2> <p>What follows is structured to have two sections:</p> <ol> <li>How a given contract code is split into chunks and then merkleized</li> <li>How to merkleize all existing contract codes during a hardfork</li> </ol> <h3 id="constants-and-definitions">Constants and Definitions</h3> <h4 id="constants">Constants</h4> <ul> <li><code>CHUNK_SIZE</code>: 31 (bytes)</li> <li><code>VERSION_KEY</code>: <code>max(u256)</code></li> <li><code>VERSION</code>: 0</li> <li><code>EMPTY_CODE_ROOT</code>: <code>0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470</code> (==<code>keccak256('')</code>)</li> <li><code>HF_TIMESTAMP</code>: to be defined</li> <li><code>ITERATOR_STRIDE</code>: <code>TBC</code> but based on verkle numbers, first devnets should use <code>50_000</code></li> </ul> <h4 id="definitions">Definitions</h4> <ul> <li><code>BE(x, N)</code>: casts <code>x</code> to an unsigned integer of <code>N</code> bytes and returns its big-endian representation</li> </ul> <h3 id="code-merkleization">Code merkleization</h3> <p>For an account record <code>A</code> with code <code>C</code>, two extra optional fields are added: <code>A.codeSize</code> and <code>A.codeRoot</code>. <code>A.codeHash</code> is retained to serve <code>EXTCODEHASH</code>.</p> <p>If <code>C</code> is empty, i.e. in the case of an EoA, <code>A.codeRoot</code> and <code>A.codeSize</code> are omitted from the account's RLP. This is intended to limit the size overhead of this change.</p> <p>If <code>C</code> is not empty:</p> <ul> <li><code>A.codeSize = len(code)</code></li> <li><code>A.codeRoot</code> contains the root of <code>codeTrie</code>, a trie with the following leaves: <ul> <li>Key: <code>VERSION_KEY</code>, value: <code>BE(VERSION, 1)</code></li> <li>A list of code <code>chunks = [(FIO_0, code_0), ..., (FIO_n, code_n)]</code> which are derived from <code>C</code> as follows: <ul> <li><code>code_0 || ... || code_n == C</code>.</li> <li><code>length(code_i) == CHUNK_SIZE</code> where <code>0 &lt;= i &lt; n</code>.</li> <li><code>length(code_n) &lt;= CHUNK_SIZE</code>.</li> <li><code>FIO_i</code> is the offset of the first instruction within the chunk. It should only be greater than zero if the last instruction in <code>code_i-1</code> is a multi-byte instruction (like <code>PUSHN</code>) crossing the chunk boundary. It is set to <code>CHUNK_SIZE</code> in the case where all bytes of a chunk are data.</li> </ul> </li> </ul> </li> </ul> <p>The <code>i</code>th element of <code>chunks</code> is stored in <code>codeTrie</code> with:</p> <ul> <li>Key: <code>BE(i, 4)</code></li> <li>Value: <code>BE(FIO_i, 1) || code_i</code>, where <code>||</code> stands for byte-wise concatenation</li> </ul> <h4 id="contract-creation-gas-cost">Contract creation gas cost</h4> <p>As of now there is a charge of 200 gas per byte of the code stored in state by contract creation operations, be it initiated via <code>CREATE</code>, <code>CREATE2</code>, or an external transaction. This per byte cost is to be increased from <code>200</code> to <code>500</code> to account for the chunking and merkleization costs. This number is inherited from <a href="https://wg-eips.ritovision.com/4762/">EIP-4762</a> and is picked for forward-compatibility.</p> <h3 id="updating-existing-code-transition-process">Updating existing code (transition process)</h3> <p>The transition process involves reading all contracts in the state and applying the above procedure to them. A process similar to <a href="https://wg-eips.ritovision.com/7612/">EIP-7612</a> is to be used, as the total code size at the time of this EIP edit is &gt;10GB and can not be processed in a single block.</p> <p>Note that:</p> <ul> <li>Because multiple accounts can share the same code hash, the whole account tree needs to be iterated over to convert each account. Only iterating over the bytecodes isn't enough.</li> <li>Nonetheless, the conversion process should take a few hours, instead of days for a full tree change.</li> </ul> <p>At <code>HF_TIMESTAMP</code> the EIP gets activated:</p> <ul> <li>any contract creation and 7702 delegation updates must use the new format. <ul> <li>for 7702 accounts, the code size is set to <code>23</code>, and <code>CODESIZE</code>/<code>CODECOPY</code> are forwarded to the delegated account. <code>EXTCODESIZE</code>/<code>EXTCODEHASH</code>/<code>EXTCODECOPY</code> behave the same as they did before the activation of this EIP.</li> <li>accounts are NOT converted in case of a balance or nonce update: accounts are converted by the iterator sweep or automatically at creation time.</li> </ul> </li> <li>at the end of block processing, and after all transactions have been executed but before recomputing the tree root hash, the client iterates over <code>ITERATOR_STRIDE</code> accounts in the tree, and for each account: <ul> <li>if the account has empty code, or is a contract using the new format, leave that account untouched,</li> <li>if the account is a "legacy" contract, convert it and write it back to the tree</li> </ul> </li> </ul> <p>The value for <code>ITERATOR_STRIDE</code> has been chosen to be safe while ensuring the transition process does not last too long. At the current state size and block time, this represents about 10000 blocks, which is about one and a half day.</p> <p>Following the transition process described in <a href="https://wg-eips.ritovision.com/8032/">EIP-8032</a>, the transition process uses a system contract to store its progress pointers. The transition process has been designed in such a way that if both EIPs are activated at the same time, their transition process can be merged. Refer to that EIP for more details.</p> <p>Note that for a bytecode used by multiple contracts, the chunking need happen only once. Such contract only need to update their code size and code root, which MAY be cached during the transition process.</p> <h2 id="rationale">Rationale</h2> <h3 id="hexary-vs-binary-trie">Hexary vs binary trie</h3> <p>The trie format is chosen to be the same as that of the account trie. If a tree conversion happens at a later stage, the chunk tree will have to be converted as well, e.g. the way it is in <a href="https://wg-eips.ritovision.com/6800/">EIP-6800</a> or <a href="https://wg-eips.ritovision.com/7864/">EIP-7864</a>.</p> <h3 id="chunk-size">Chunk size</h3> <p>The current recommended chunk size of 31 bytes has been selected based on a few observations. Smaller chunks are more efficient (i.e. have higher chunk utilization), but incur a larger hash overhead (i.e. number of hashes as part of the proof) due to a higher trie depth. Larger chunks are less efficient, but incur less hash overhead. We plan to run a larger experiment comparing various chunk sizes to arrive at a final recommendation.</p> <h3 id="first-instruction-offset">First instruction offset</h3> <p>The <code>firstInstructionOffset</code> field allows safe jumpdest analysis when a client doesn't have all the chunks, e.g. a stateless clients receiving block witnesses.</p> <p>Note: there could be an edge case when computing FIO for the chunks where the data bytes at the end of a bytecode (last chunk) resemble a multi-byte instruction. This case can be safely ignored.</p> <h3 id="gas-cost-of-code-accessing-opcodes">Gas cost of code-accessing opcodes</h3> <p>Details of how the code is stored, is left to the client implementers. However, to reflect the removal of the max code limit and the fact that larger codes will be more expensive to load, reading a non-accessed chunk will incur a 200 warming cost, and chunks written beyond the 24kb limit will cost 500 gas instead of 200.</p> <h3 id="different-chunking-logic">Different chunking logic</h3> <p>We have considered an alternative option to package chunks, where each chunk is prepended with its <code>chunkLength</code> and would only contain complete opcodes (i.e. any multi-byte opcode not fitting the <code>CHUNK_SIZE</code> would be deferred to the next chunk).</p> <p>This approach has downsides compared to the one specified:</p> <ol> <li>Requires a larger <code>CHUNK_SIZE</code> -- at least 33 bytes to accommodate the <code>PUSH32</code> instruction.</li> <li>It is more wasteful. For example, <code>DUP1 PUSH32 &lt;32-byte payload&gt;</code> would be encoded as two chunks, the first chunk contains only <code>DUP1</code>, and the second contains only the <code>PUSH32</code> instruction with its payload.</li> <li>Calculating the number of chunks is not trivial and would have to be stored explicitly in the metadata.</li> </ol> <p>Additionally we have reviewed many other options (basic block based, Solidity subroutines (requires determining the control flow), EIP-2315 subroutines). This EIP however only focuses on the chunk-based option.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>From the perspective of contracts, the design aims to be transparent, with the exception of changes in gas costs.</p> <p>Outside of the interface presented for contracts, this proposal introduces major changes to the way contract code is stored, and needs a substantial modification of the Ethereum state. Therefore it can only be introduced via a hard fork.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <p>Show the <code>codeRoot</code> for the following cases:</p> <ol> <li><code>code=''</code></li> <li><code>code='PUSH1(0) DUP1 REVERT'</code></li> <li><code>code='PUSH32(-1)'</code> (data passing through a chunk boundary)</li> </ol> <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> 2020-08-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Federico Bondhttps://github.com/federicobond Renan Rodrigues de Souzahttps://github.com/RenanSouza2 https://wg-eips.ritovision.com/838/

A proposal to extend the ABI specification to include typed errors in the REVERT reason string.

<h2 id="abstract">Abstract</h2> <p>This proposal specifies how to encode potential error conditions in the JSON ABI of a smart contract. A high-level language could then provide a syntax for declaring and throwing these errors. The compiler will encode these errors in the reason parameter of the REVERT opcode in a way that can be easily reconstructed by libraries such as web3.</p> <h2 id="motivation">Motivation</h2> <p>It's important to provide clear feedback to users (and developers) about what went wrong with their Ethereum transactions. The REVERT opcode is a step in the right direction, as it allows smart contract developers to encode a message describing the failure in the reason parameter. There is an implementation under review in Solidity that accepts a string, thus providing a low-level interface to this parameter. However, standardizing a method for passing errors from this parameter back to clients will bring many benefits to both users and developers.</p> <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> <h2 id="specification">Specification</h2> <p>To conform to this specification, compilers producing JSON ABIs SHOULD include error declarations alongside functions and events. Each error object MUST contain the keys name (string) and arguments (same types as the function’s inputs list). The value of type MUST be "error".</p> <p>Example:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{ &quot;type&quot;: &quot;error&quot;, &quot;name&quot;: &quot;InsufficientBalance&quot;, &quot;arguments&quot;: [ { &quot;name&quot;: &quot;amount&quot;, &quot;type&quot;: &quot;uint256&quot; } ] }</span></span></code></pre> <p>A selector for this error can be computed from its signature (InsufficientBalance() for the example above) in the same way that it's currently done for public functions and events. This selector MUST be included in the reason string so that clients can perform a lookup. Any arguments for the error are RLP encoded in the same way as return values from functions. The exact format in which both the selector and the arguments are encoded is to be defined. The Solidity implementation mentioned above leaves room for expansion by prefixing the free-form string with uint256(0).</p> <p>A high-level language like Solidity can then implement a syntax like this:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>contract MyToken {</span></span> <span class="giallo-l"><span> error InsufficientFunds(uint256 amount);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function transfer(address _to, uint256 _amount) {</span></span> <span class="giallo-l"><span> if (balances[msg.sender] &lt;= _amount)</span></span> <span class="giallo-l"><span> throw InsufficientFunds(_amount);</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="possible-extensions">Possible extensions</h3> <ol> <li>A NatSpec comment above the error declaration can be used to provide a default error message. Arguments to the error can be interpolated in the message string with familiar NatSpec syntax.</li> </ol> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/// @notice You don&#39;t have enough funds to transfer `amount`.</span></span> <span class="giallo-l"><span>error InsufficientFunds(uint256 amount);</span></span></code></pre> <ol start="2"> <li>A function may declare to its callers which errors it can throw. A list of these errors must be included in the JSON ABI item for that function, under the <code>errors</code> key. Example:</li> </ol> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function transfer(address _to, uint256 _amount) throws(InsufficientFunds);</span></span></code></pre> <p>Special consideration should be given to error overloading if we want to support a similar syntax in the future, as errors with same name but different arguments will produce a different selector.</p> <h2 id="rationale">Rationale</h2> <p>Needs discussion. <!-- TODO --></p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Apps and tools that have not implemented this spec can ignore the encoded reason string when it's not prefixed by zero.</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> 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-19T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Johnsonhttps://github.com/arachnid https://wg-eips.ritovision.com/3668/

CCIP Read provides a mechanism to allow a contract to fetch external data.

<h2 id="abstract">Abstract</h2> <p>Contracts wishing to support lookup of data from external sources may, instead of returning the data directly, revert using <code>OffchainLookup(address sender, string[] urls, bytes callData, bytes4 callbackFunction, bytes extraData)</code>. Clients supporting this specification then make an RPC call to a URL from <code>urls</code>, supplying <code>callData</code>, and getting back an opaque byte string <code>response</code>. Finally, clients call the function specified by <code>callbackFunction</code> on the contract, providing <code>response</code> and <code>extraData</code>. The contract can then decode and verify the returned data using an implementation-specific method.</p> <p>This mechanism allows for offchain lookups of data in a way that is transparent to clients, and allows contract authors to implement whatever validation is necessary; in many cases this can be provided without any additional trust assumptions over and above those required if data is stored onchain.</p> <h2 id="motivation">Motivation</h2> <p>Minimising storage and transaction costs on Ethereum has driven contract authors to adopt a variety of techniques for moving data offchain, including hashing, recursive hashing (eg Merkle Trees/Tries) and L2 solutions. While each solution has unique constraints and parameters, they all share in common the fact that enough information is stored onchain to validate the externally stored data when required.</p> <p>Thus far, applications have tended to devise bespoke solutions rather than trying to define a universal standard. This is practical - although inefficient - when a single offchain data storage solution suffices, but rapidly becomes impractical in a system where multiple end-users may wish to make use of different data storage and availability solutions based on what suits their needs.</p> <p>By defining a common specification allowing smart contract to fetch data from offchain, we facilitate writing clients that are entirely agnostic to the storage solution being used, which enables new applications that can operate without knowing about the underlying storage details of the contracts they interact with.</p> <p>Examples of this include:</p> <ul> <li>Interacting with 'airdrop' contracts that store a list of recipients offchain in a merkle trie.</li> <li>Viewing token information for tokens stored on an L2 solution as if they were native L1 tokens.</li> <li>Allowing delegation of data such as ENS domains to various L2 solutions, without requiring clients to support each solution individually.</li> <li>Allowing contracts to proactively request external data to complete a call, without requiring the caller to be aware of the details of that data.</li> </ul> <h2 id="specification">Specification</h2> <h3 id="overview">Overview</h3> <p>Answering a query via CCIP read takes place in three steps:</p> <ol> <li>Querying the contract.</li> <li>Querying the gateway using the URL provided in (1).</li> <li>Querying or sending a transaction to the contract using the data from (1) and (2).</li> </ol> <p>In step 1, a standard blockchain call operation is made to the contract. The contract reverts with an error that specifies the data to complete the call can be found offchain, and provides the url to a service that can provide the answer, along with additional contextual information required for the call in step (3).</p> <p>In step 2, the client calls the gateway service with the <code>callData</code> from the revert message in step (1). The gateway responds with an answer <code>response</code>, whose content is opaque to the client.</p> <p>In step 3, the client calls the original contract, supplying the <code>response</code> from step (2) and the <code>extraData</code> returned by the contract in step (1). The contract decodes the provided data and uses it to validate the response and act on it - by returning information to the client or by making changes in a transaction. The contract could also revert with a new error to initiate another lookup, in which case the protocol starts again at step 1.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>┌──────┐ ┌────────┐ ┌─────────────┐</span></span> <span class="giallo-l"><span>│Client│ │Contract│ │Gateway @ url│</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 OffchainLookup(sender, urls, callData, │ │</span></span> <span class="giallo-l"><span> │ callbackFunction, extraData) │ │</span></span> <span class="giallo-l"><span> │◄─────────────────────────────────────────────────┤ │</span></span> <span class="giallo-l"><span> │ │ │</span></span> <span class="giallo-l"><span> │ HTTP request (sender, callData) │ │</span></span> <span class="giallo-l"><span> ├──────────────────────────────────────────────────┼────────────►│</span></span> <span class="giallo-l"><span> │ │ │</span></span> <span class="giallo-l"><span> │ Response (result) │ │</span></span> <span class="giallo-l"><span> │◄─────────────────────────────────────────────────┼─────────────┤</span></span> <span class="giallo-l"><span> │ │ │</span></span> <span class="giallo-l"><span> │ callbackFunction(result, extraData) │ │</span></span> <span class="giallo-l"><span> ├─────────────────────────────────────────────────►│ │</span></span> <span class="giallo-l"><span> │ │ │</span></span> <span class="giallo-l"><span> │ answer │ │</span></span> <span class="giallo-l"><span> │◄─────────────────────────────────────────────────┤ │</span></span> <span class="giallo-l"><span> │ │ │</span></span></code></pre><h3 id="contract-interface">Contract interface</h3> <p>A CCIP read enabled contract MUST revert with the following error whenever a function that requires offchain data is called:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">error</span><span class="z-entity z-name"> OffchainLookup</span><span>(</span><span class="z-support">address</span><span> sender</span><span>,</span><span class="z-support"> string</span><span>[</span><span>]</span><span> urls</span><span>,</span><span class="z-support"> bytes</span><span> callData</span><span>,</span><span class="z-support"> bytes4</span><span> callbackFunction</span><span>,</span><span class="z-support"> bytes</span><span> extraData</span><span>)</span></span></code></pre> <p><code>sender</code> is the address of the contract that raised the error, and is used to determine if the error was thrown by the contract the client called, or 'bubbled up' from a nested call.</p> <p><code>urls</code> specifies a list of URL templates to services (known as gateways) that implement the CCIP read protocol and can formulate an answer to the query. <code>urls</code> can be the empty list <code>[]</code>, in which case the client MUST specify the URL template. The order in which URLs are tried is up to the client, but contracts SHOULD return them in order of priority, with the most important entry first.</p> <p>Each URL may include two substitution parameters, <code>{sender}</code> and <code>{data}</code>. Before a call is made to the URL, <code>sender</code> is replaced with the lowercase 0x-prefixed hexadecimal formatted <code>sender</code> parameter, and <code>data</code> is replaced by the 0x-prefixed hexadecimal formatted <code>callData</code> parameter.</p> <p><code>callData</code> specifies the data to call the gateway with. This value is opaque to the client. Typically this will be ABI-encoded, but this is an implementation detail that contracts and gateways can standardise on as desired.</p> <p><code>callbackFunction</code> is the 4-byte function selector for a function on the original contract to which a callback should be sent.</p> <p><code>extraData</code> is additional data that is required by the callback, and MUST be retained by the client and provided unmodified to the callback function. This value is opaque to the client.</p> <p>The contract MUST also implement a callback method for decoding and validating the data returned by the gateway. The name of this method is implementation-specific, but it MUST have the signature <code>(bytes response, bytes extraData)</code>, and MUST have the same return type as the function that reverted with <code>OffchainLookup</code>.</p> <p>If the client successfully calls the gateway, the callback function specified in the <code>OffchainLookup</code> error will be invoked by the client, with <code>response</code> set to the value returned by the gateway, and <code>extraData</code> set to the value returned in the contract's <code>OffchainLookup</code> error. The contract MAY initiate another CCIP read lookup in this callback, though authors should bear in mind that the limits on number of recursive invocations will vary from client to client.</p> <p>In a call context (as opposed to a transaction), the return data from this call will be returned to the user as if it was returned by the function that was originally invoked.</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"> balanceOf</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">uint</span><span class="z-variable"> balance</span><span>)</span><span>;</span></span></code></pre> <p>Data for these queries is stored offchain in some kind of hashed data structure, the details of which are not important for this example. The contract author wants the gateway to fetch the proof information for this query and call the following function with it:</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"> balanceOfWithProof</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> response</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> extraData</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"> balance</span><span>)</span><span>;</span></span></code></pre> <p>One example of a valid implementation of <code>balanceOf</code> would thus 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"> balanceOf</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">uint</span><span class="z-variable"> balance</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> OffchainLookup</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> [</span><span>url</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span>Gateway</span><span>.</span><span>getSignedBalance</span><span>.</span><span>selector</span><span>,</span><span> addr</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> ContractName</span><span>.</span><span>balanceOfWithProof</span><span>.</span><span>selector</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>addr</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Note that in this example the contract is returning <code>addr</code> in both <code>callData</code> and <code>extraData</code>, because it is required both by the gateway (in order to look up the data) and the callback function (in order to verify it). The contract cannot simply pass it to the gateway and rely on it being returned in the response, as this would give the gateway an opportunity to respond with an answer to a different query than the one that was initially issued.</p> <h4 id="recursive-calls-in-ccip-aware-contracts">Recursive calls in CCIP-aware contracts</h4> <p>When a CCIP-aware contract wishes to make a call to another contract, and the possibility exists that the callee may implement CCIP read, the calling contract MUST catch all <code>OffchainLookup</code> errors thrown by the callee, and revert with a different error if the <code>sender</code> field of the error does not match the callee address.</p> <p>The contract MAY choose to replace all <code>OffchainLookup</code> errors with a different error. Doing so avoids the complexity of implementing support for nested CCIP read calls, but renders them impossible.</p> <p>Where the possibility exists that a callee implements CCIP read, a CCIP-aware contract MUST NOT allow the default solidity behaviour of bubbling up reverts from nested calls. This is to prevent the following situation:</p> <ol> <li>Contract A calls non-CCIP-aware contract B.</li> <li>Contract B calls back to A.</li> <li>In the nested call, A reverts with <code>OffchainLookup</code>.</li> <li>Contract B does not understand CCIP read and propagates the <code>OffchainLookup</code> to its caller.</li> <li>Contract A also propagates the <code>OffchainLookup</code> to its caller.</li> </ol> <p>The result of this sequence of operations would be an <code>OffchainLookup</code> that looks valid to the client, as the <code>sender</code> field matches the address of the contract that was called, but does not execute correctly, as it only completes a nested invocation.</p> <h4 id="example-1">Example</h4> <p>The code below demonstrates one way that a contract may support nested CCIP read invocations. For simplicity this is shown using Solidity's try/catch syntax, although as of this writing it does not yet support catching custom errors.</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"> NestedLookup</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> InvalidOperation</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> OffchainLookup</span><span>(</span><span class="z-support">address</span><span> sender</span><span>,</span><span class="z-support"> string</span><span>[</span><span>]</span><span> urls</span><span>,</span><span class="z-support"> bytes</span><span> callData</span><span>,</span><span class="z-support"> bytes4</span><span> callbackFunction</span><span>,</span><span class="z-support"> bytes</span><span> extraData</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"> a</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"> 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"> try</span><span> target</span><span>.</span><span class="z-entity z-name">b</span><span>(</span><span>data</span><span>)</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"> ret</span><span>)</span><span> {</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"> catch</span><span class="z-entity z-name"> OffchainLookup</span><span>(</span><span class="z-support">address</span><span> sender</span><span>,</span><span class="z-support"> string</span><span>[</span><span>]</span><span> urls</span><span>,</span><span class="z-support"> bytes</span><span> callData</span><span>,</span><span class="z-support"> bytes4</span><span> callbackFunction</span><span>,</span><span class="z-support"> bytes</span><span> extraData</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"> address</span><span>(</span><span>target</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> InvalidOperation</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> OffchainLookup</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> urls</span><span>,</span></span> <span class="giallo-l"><span> callData</span><span>,</span></span> <span class="giallo-l"><span> NestedLookup</span><span>.</span><span>aCallback</span><span>.</span><span>selector</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 class="z-support">address</span><span>(</span><span>target</span><span>)</span><span>,</span><span> callbackFunction</span><span>,</span><span> extraData</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 class="z-storage z-type"> function</span><span class="z-entity z-name"> aCallback</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> response</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> extraData</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> (</span><span class="z-support">address</span><span> inner</span><span>,</span><span class="z-support"> bytes4</span><span> innerCallbackFunction</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> innerExtraData</span><span>)</span><span class="z-keyword"> =</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>extraData</span><span>,</span><span> (</span><span class="z-support">address</span><span>,</span><span class="z-support"> bytes4</span><span>,</span><span class="z-support"> bytes</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span>inner</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span>innerCallbackFunction</span><span>,</span><span> response</span><span>,</span><span> innerExtraData</span><span>)</span><span>)</span><span>,</span><span> (</span><span class="z-support">bytes</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="gateway-interface">Gateway Interface</h3> <p>The URLs returned by a contract may be of any schema, but this specification only defines how clients should handle HTTPS URLs.</p> <p>Given a URL template returned in an <code>OffchainLookup</code>, the URL to query is composed by replacing <code>sender</code> with the lowercase 0x-prefixed hexadecimal formatted <code>sender</code> parameter, and replacing <code>data</code> with the 0x-prefixed hexadecimal formatted <code>callData</code> parameter.</p> <p>For example, if a contract returns the following data in an <code>OffchainLookup</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>urls = [&quot;https://example.com/gateway/{sender}/{data}.json&quot;]</span></span> <span class="giallo-l"><span>sender = &quot;0xaabbccddeeaabbccddeeaabbccddeeaabbccddee&quot;</span></span> <span class="giallo-l"><span>callData = &quot;0x00112233&quot;</span></span></code></pre> <p>The request URL to query is <code>https://example.com/gateway/0xaabbccddeeaabbccddeeaabbccddeeaabbccddee/0x00112233.json</code>.</p> <p>If the URL template contains the <code>{data}</code> substitution parameter, the client MUST send a GET request after replacing the substitution parameters as described above.</p> <p>If the URL template does not contain the <code>{data}</code> substitution parameter, the client MUST send a POST request after replacing the substitution parameters as described above. The POST request MUST be sent with a Content-Type of <code>application/json</code>, and a payload matching the following schema:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;object&quot;,</span></span> <span class="giallo-l"><span> &quot;properties&quot;: {</span></span> <span class="giallo-l"><span> &quot;data&quot;: {</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;0x-prefixed hex string containing the `callData` from the contract&quot;</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &quot;sender&quot;: {</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;description&quot;: &quot;0x-prefixed hex string containing the `sender` parameter from the contract&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>Compliant gateways MUST respond with a Content-Type of <code>application/json</code>, with the body adhering to the following JSON schema:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;object&quot;,</span></span> <span class="giallo-l"><span> &quot;properties&quot;: {</span></span> <span class="giallo-l"><span> &quot;data&quot;: {</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;description: &quot;0x-prefixed hex string containing the result data.&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>Unsuccessful requests MUST return the appropriate HTTP status code - for example, 404 if the <code>sender</code> address is not supported by this gateway, 400 if the <code>callData</code> is in an invalid format, 500 if the server encountered an internal error, and so forth. If the Content-Type of a 4xx or 5xx response is <code>application/json</code>, it MUST adhere to the following JSON schema:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;object&quot;,</span></span> <span class="giallo-l"><span> &quot;properties&quot;: {</span></span> <span class="giallo-l"><span> &quot;message&quot;: {</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;string&quot;,</span></span> <span class="giallo-l"><span> &quot;description: &quot;A human-readable error message.&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><h4 id="examples">Examples</h4> <p><em><strong>GET request</strong></em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span># Client returned a URL template `https://example.com/gateway/{sender}/{data}.json`</span></span> <span class="giallo-l"><span># Request</span></span> <span class="giallo-l"><span>curl -D - https://example.com/gateway/0x226159d592E2b063810a10Ebf6dcbADA94Ed68b8/0xd5fa2b00.json</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Successful result</span></span> <span class="giallo-l"><span> HTTP/2 200</span></span> <span class="giallo-l"><span> content-type: application/json; charset=UTF-8</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> {&quot;data&quot;: &quot;0xdeadbeefdecafbad&quot;}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Error result</span></span> <span class="giallo-l"><span> HTTP/2 404</span></span> <span class="giallo-l"><span> content-type: application/json; charset=UTF-8</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> {&quot;message&quot;: &quot;Gateway address not supported.&quot;}</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><em><strong>POST request</strong></em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span># Client returned a URL template `https://example.com/gateway/{sender}.json`</span></span> <span class="giallo-l"><span># Request</span></span> <span class="giallo-l"><span>curl -D - -X POST -H &quot;Content-Type: application/json&quot; --data &#39;{&quot;data&quot;:&quot;0xd5fa2b00&quot;,&quot;sender&quot;:&quot;0x226159d592E2b063810a10Ebf6dcbADA94Ed68b8&quot;}&#39; https://example.com/gateway/0x226159d592E2b063810a10Ebf6dcbADA94Ed68b8.json</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Successful result</span></span> <span class="giallo-l"><span> HTTP/2 200</span></span> <span class="giallo-l"><span> content-type: application/json; charset=UTF-8</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> {&quot;data&quot;: &quot;0xdeadbeefdecafbad&quot;}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Error result</span></span> <span class="giallo-l"><span> HTTP/2 404</span></span> <span class="giallo-l"><span> content-type: application/json; charset=UTF-8</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> {&quot;message&quot;: &quot;Gateway address not supported.&quot;}</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Clients MUST support both GET and POST requests. Gateways may implement either or both as needed.</p> <h3 id="client-lookup-protocol">Client Lookup Protocol</h3> <p>A client that supports CCIP read MUST make contract calls using the following process:</p> <ol> <li>Set <code>data</code> to the call data to supply to the contract, and <code>to</code> to the address of the contract to call.</li> <li>Call the contract at address <code>to</code> function normally, supplying <code>data</code> as the input data. If the function returns a successful result, return it to the caller and stop.</li> <li>If the function returns an error other than <code>OffchainLookup</code>, return it to the caller in the usual fashion.</li> <li>Otherwise, decode the <code>sender</code>, <code>urls</code>, <code>callData</code>, <code>callbackFunction</code> and <code>extraData</code> arguments from the <code>OffchainLookup</code> error.</li> <li>If the <code>sender</code> field does not match the address of the contract that was called, return an error to the caller and stop.</li> <li>Construct a request URL by replacing <code>sender</code> with the lowercase 0x-prefixed hexadecimal formatted <code>sender</code> parameter, and replacing <code>data</code> with the 0x-prefixed hexadecimal formatted <code>callData</code> parameter. The client may choose which URLs to try in which order, but SHOULD prioritise URLs earlier in the list over those later in the list.</li> <li>Make an HTTP GET request to the request URL.</li> <li>If the response code from step (7) is in the range 400-499, return an error to the caller and stop.</li> <li>If the response code from step (7) is in the range 500-599, go back to step (5) and pick a different URL, or stop if there are no further URLs to try.</li> <li>Otherwise, replace <code>data</code> with an ABI-encoded call to the contract function specified by the 4-byte selector <code>callbackFunction</code>, supplying the data returned from step (7) and <code>extraData</code> from step (4), and return to step (1).</li> </ol> <p>Clients MUST handle HTTP status codes appropriately, employing best practices for error reporting and retries.</p> <p>Clients MUST handle HTTP 4xx and 5xx error responses that have a content type other than application/json appropriately; they MUST NOT attempt to parse the response body as JSON.</p> <p>This protocol can result in multiple lookups being requested by the same contract. Clients MUST implement a limit on the number of lookups they permit for a single contract call, and this limit SHOULD be at least 4.</p> <p>The lookup protocol for a client is described with the following pseudocode:</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"> httpcall</span><span>(</span><span class="z-variable">urls</span><span>,</span><span class="z-variable"> to</span><span>,</span><span class="z-variable"> callData</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"> args</span><span class="z-keyword"> =</span><span> {</span><span>sender</span><span>:</span><span class="z-variable z-other"> to</span><span>.</span><span class="z-entity z-name">toLowerCase</span><span>(</span><span>)</span><span>,</span><span> data</span><span>:</span><span class="z-variable z-other"> callData</span><span>.</span><span class="z-entity z-name">toLowerCase</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">const</span><span class="z-variable z-other z-constant"> url</span><span class="z-keyword"> of</span><span class="z-variable z-other"> urls</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"> queryUrl</span><span class="z-keyword"> =</span><span class="z-variable z-other"> url</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-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-constant z-character z-escape">\}</span><span class="z-punctuation z-definition z-string">/</span><span class="z-keyword">g</span><span>,</span><span> (</span><span class="z-variable">match</span><span>,</span><span class="z-variable"> p1</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span class="z-variable z-other"> args</span><span>[</span><span class="z-variable z-other">p1</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"> First argument is URL to fetch, second is optional data for a POST request.</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> response</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> fetch</span><span>(</span><span class="z-variable z-other">queryUrl</span><span>,</span><span class="z-variable z-other"> url</span><span>.</span><span class="z-entity z-name">includes</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">{data}</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span class="z-keyword"> ?</span><span class="z-constant"> undefined</span><span class="z-keyword"> :</span><span class="z-variable z-other"> args</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"> result</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> response</span><span>.</span><span class="z-entity z-name">text</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">result</span><span>.</span><span class="z-variable z-other">statusCode</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> 400</span><span class="z-keyword"> &amp;&amp;</span><span class="z-variable z-other"> result</span><span>.</span><span class="z-variable z-other">statusCode</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 499</span><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-variable z-other">data</span><span>.</span><span class="z-variable z-other">error</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-keyword"> if</span><span>(</span><span class="z-variable z-other">result</span><span>.</span><span class="z-variable z-other">statusCode</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> 200</span><span class="z-keyword"> &amp;&amp;</span><span class="z-variable z-other"> result</span><span>.</span><span class="z-variable z-other">statusCode</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 299</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> result</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-storage">async</span><span class="z-storage z-type"> function</span><span class="z-entity z-name"> durin_call</span><span>(</span><span class="z-variable">provider</span><span>,</span><span class="z-variable"> to</span><span>,</span><span class="z-variable"> data</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"> 0</span><span>;</span><span class="z-variable z-other"> i</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 4</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-keyword"> try</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-keyword"> await</span><span class="z-variable z-other"> provider</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span class="z-variable z-other">to</span><span>,</span><span class="z-variable z-other"> data</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-keyword"> if</span><span>(</span><span class="z-variable z-other">error</span><span>.</span><span class="z-variable z-other">code</span><span class="z-keyword"> !==</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">CALL_EXCEPTION</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> throw</span><span>(</span><span class="z-variable z-other">error</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> {</span><span class="z-variable z-other z-constant">sender</span><span>,</span><span class="z-variable z-other z-constant"> urls</span><span>,</span><span class="z-variable z-other z-constant"> callData</span><span>,</span><span class="z-variable z-other z-constant"> callbackFunction</span><span>,</span><span class="z-variable z-other z-constant"> extraData</span><span>}</span><span class="z-keyword"> =</span><span class="z-variable z-other"> error</span><span>.</span><span class="z-variable z-other">data</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">sender</span><span class="z-keyword"> !==</span><span class="z-variable z-other"> to</span><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">&quot;</span><span class="z-string">Cannot handle OffchainLookup raised inside nested call</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-storage z-type"> const</span><span class="z-variable z-other z-constant"> result</span><span class="z-keyword"> =</span><span class="z-entity z-name"> httpcall</span><span>(</span><span class="z-variable z-other">urls</span><span>,</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> callData</span><span>)</span><span>;</span></span> <span class="giallo-l"><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 class="z-variable z-other">callbackFunction</span><span>,</span><span class="z-variable z-other"> result</span><span>,</span><span class="z-variable z-other"> extraData</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"> 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">&quot;</span><span class="z-string">Too many CCIP read redirects</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Where:</p> <ul> <li><code>provider</code> is a provider object that facilitates Ethereum blockchain function calls.</li> <li><code>to</code> is the address of the contract to call.</li> <li><code>data</code> is the call data for the contract.</li> </ul> <p>If the function being called is a standard contract function, the process terminates after the original call, returning the same result as for a regular call. Otherwise, a gateway from <code>urls</code> is called with the <code>callData</code> returned by the <code>OffchainLookup</code> error, and is expected to return a valid response. The response and the <code>extraData</code> are then passed to the specified callback function. This process can be repeated if the callback function returns another <code>OffchainLookup</code> error.</p> <h3 id="use-of-ccip-read-for-transactions">Use of CCIP read for transactions</h3> <p>While the specification above is for read-only contract calls (eg, <code>eth_call</code>), it is simple to use this method for sending transactions (eg, <code>eth_sendTransaction</code> or <code>eth_sendRawTransaction</code>) that require offchain data. While 'preflighting' a transaction using <code>eth_estimateGas</code> or <code>eth_call</code>, a client that receives an <code>OffchainLookup</code> revert can follow the procedure described above in <a href="https://wg-eips.ritovision.com/3668/#client-lookup-protocol">Client lookup protocol</a>, substituting a transaction for the call in the last step. This functionality is ideal for applications such as making onchain claims supported by offchain proof data.</p> <h3 id="glossary">Glossary</h3> <ul> <li>Client: A process, such as JavaScript executing in a web browser, or a backend service, that wishes to query a blockchain for data. The client understands how to fetch data using CCIP read.</li> <li>Contract: A smart contract existing on Ethereum or another blockchain.</li> <li>Gateway: A service that answers application-specific CCIP read queries, usually over HTTPS.</li> </ul> <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>For offchain data lookup to function as desired, clients must either have some way to know that a function depends on this specification for functionality - such as a specifier in the ABI for the function - or else there must be a way for the contract to signal to the client that data needs to be fetched from elsewhere.</p> <p>While specifying the call type in the ABI is a possible solution, this makes retrofitting existing interfaces to support offchain data awkward, and either results in contracts with the same name and arguments as the original specification, but with different return data - which will cause decoding errors for clients that do not expect this - or duplicating every function that needs support for offchain data with a different name (eg, <code>balanceOf -&gt; offchainBalanceOf</code>). Neither solutions is particularly satisfactory.</p> <p>Using a revert, and conveying the required information in the revert data, allows any function to be retrofitted to support lookups via CCIP read so long as the client understands the specification, and so facilitates translation of existing specifications to use offchain data.</p> <h3 id="passing-contract-address-to-the-gateway-service">Passing contract address to the gateway service</h3> <p><code>address</code> is passed to the gateway in order to facilitate the writing of generic gateways, thus reducing the burden on contract authors to provide their own gateway implementations. Supplying <code>address</code> allows the gateway to perform lookups to the original contract for information needed to assist with resolution, making it possible to operate one gateway for any number of contracts implementing the same interface.</p> <h3 id="existence-of-extradata-argument">Existence of <code>extraData</code> argument</h3> <p><code>extraData</code> allows the original contract function to pass information to a subsequent invocation. Since contracts are not persistent, without this data a contract has no state from the previous invocation. Aside from allowing arbitrary contextual information to be propagated between the two calls, this also allows the contract to verify that the query the gateway answered is in fact the one the contract originally requested.</p> <h3 id="use-of-get-and-post-requests-for-the-gateway-interface">Use of GET and POST requests for the gateway interface</h3> <p>Using a GET request, with query data encoded in the URL, minimises complexity and enables entirely static implementations of gateways - in some applications a gateway can simply be an HTTP server or IPFS instance with a static set of responses in text files.</p> <p>However, URLs are limited to 2 kilobytes in size, which will impose issues for more complex uses of CCIP read. Thus, we provide for an option to use POST data. This is made at the contract's discretion (via the choice of URL template) in order to preserve the ability to have a static gateway operating exclusively using GET when desired.</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 CCIP read to all contract calls without introducing any new overhead or incompatibilities.</p> <p>Contracts that require CCIP read 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 propagaged to the user.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="gateway-response-data-validation">Gateway Response Data Validation</h3> <p>In order to prevent a malicious gateway from causing unintended side-effects or faulty results, contracts MUST include sufficient information in the <code>extraData</code> argument to allow them to verify the relevance and validity of the gateway's response. For example, if the contract is requesting information based on an <code>address</code> supplied to the original call, it MUST include that address in the <code>extraData</code> so that the callback can verify the gateway is not providing the answer to a different query.</p> <p>Contracts must also implement sufficient validation of the data returned by the gateway to ensure it is valid. The validation required is application-specific and cannot be specified on a global basis. Examples would include verifying a Merkle proof of inclusion for an L2 or other Merkleized state, or verifying a signature by a trusted signer over the response data.</p> <h3 id="client-extra-data-validation">Client Extra Data Validation</h3> <p>In order to prevent a malicious client from causing unintended effects when making transactions using CCIP read, contracts MUST implement appropriate checks on the <code>extraData</code> returned to them in the callback. Any sanity/permission checks performed on input data for the initial call MUST be repeated on the data passed through the <code>extraData</code> field in the callback. For example, if a transaction should only be executable by an authorised account, that authorisation check MUST be done in the callback; it is not sufficient to perform it with the initial call and embed the authorised address in the <code>extraData</code>.</p> <h3 id="http-requests-and-fingerprinting-attacks">HTTP requests and fingerprinting attacks</h3> <p>Because CCIP read can cause a user's browser to make HTTP requests to an address controlled by the contract, there is the potential for this to be used to identify users - for example, to associate their wallet address with their IP address.</p> <p>The impact of this is application-specific; fingerprinting a user when they resolve an ENS domain may have little privacy impact, as the attacker will not learn the user's wallet address, only the fact that the user is resolving a given ENS name from a given IP address - information they can also learn from running a DNS server. On the other hand, fingerprinting a user when they attempt a transaction to transfer an NFT may give an attacker everything they need to identify the IP address of a user's wallet.</p> <p>To minimise the security impact of this, we make the following recommendations:</p> <ol> <li>Client libraries should provide clients with a hook to override CCIP read 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> <li>Client libraries should disable CCIP read for transactions (but not for calls) by default, and require the caller to explicitly enable this functionality. Enablement should be possible both on a per-contract, per-domain, or global basis.</li> <li>App authors should not supply a 'from' address for contract calls ('view' operations) where the call could execute untrusted code (that is, code not authored or trusted by the application author). As a precuationary principle it is safest to not supply this parameter at all unless the author is certain that no attacker-determined smart contract code will be executed.</li> <li>Wallet authors that are responsible for fetching user information - for example, by querying token contracts - should either ensure CCIP read is disabled for transactions, and that no contract calls are made with a 'from' address supplied, or operate a proxy on their users' behalf, rewriting all CCIP read calls to take place via the proxy, or both.</li> </ol> <p>We encourage client library authors and wallet authors not to disable CCIP read by default, as many applications can be transparently enhanced with this functionality, which is quite safe if the above precautions are observed.</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-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-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Micah Zoltuhttps://github.com/MicahZoltu Erik Markshttps://github.com/rekmarks https://wg-eips.ritovision.com/2786/ <h2 id="simple-summary">Simple Summary</h2> <p>When an Ethereum Provider becomes connected or disconnected, it will emit a <code>connect</code>/<code>disconnect</code> event.</p> <h2 id="abstract">Abstract</h2> <p>The Provider is said to be “connected” when it can service RPC requests to at least one chain. The Provider is said to be “disconnected” when it cannot service RPC requests to any chain at all. When the Provider switches from a "connected" state to a "disconnected" state, it will emit a <code>connect</code> event. When the Provider switches from a "disconnected" state to a "connected" state, it will emit a <code>disconnect</code> event.</p> <h2 id="motivation">Motivation</h2> <p>When an application is hooked up to an Ethereum provider, there is value in having the application be alerted of connect/disconnect events that may occur so the application can appropriately inform the user of the situation. It is left up to the application to decide whether to listen in on these events, and how to handle them.</p> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions</h3> <h4 id="connected">Connected</h4> <p>The Provider is considered <code>connected</code> when it is able to service RPC requests to at least one chain.</p> <h4 id="disconnected">Disconnected</h4> <p>The Provider is considered <code>disconnected</code> when it is unable to service RPC requests to any chain.</p> <h3 id="events">Events</h3> <h4 id="connect"><code>connect</code></h4> <p>The Provider <strong>MUST</strong> emit a <code>connect</code> event to all attached <a href="https://wg-eips.ritovision.com/2700/">EIP-2700</a> listeners if it transitions from a <code>disconnected</code> state to a <code>connected</code> state. All attached listeners <strong>MUST</strong> be called with the parameter <code>{ chainId }</code>. <code>chainId</code> <strong>MUST</strong> specify the integer ID of the connected chain encoded as a hexadecimal string. If the Provider supports the <code>eth_chainId</code> JSON-RPC method or a derivation of it, then the <code>chainId</code> <strong>MUST</strong> match the return value of <code>eth_chainId</code>. The Provider <strong>MAY</strong> call the attached listeners in any order.</p> <h2 id="rationale">Rationale</h2> <p>This EIP is mostly a retrospective EIP meaning it codifies an already existing specification so there isn’t a lot of room for improving things such as by having a connect/disconnect event per chain.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The relationship between Ethereum Provider and client is a trusted one, where it is assumed that the user implicitly trusts the Ethereum Provider which is how it managed to get injected into the client, or the client expressly pulled in a connection 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> <h2 id="appendix-i-examples">Appendix I: Examples</h2> <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"> connect</span></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">connect</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> (</span><span>{</span><span class="z-variable"> chainId</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"> 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">Provider connected to: </span><span class="z-string">${</span><span class="z-variable z-other">chainId</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></code></pre> 2020-07-11T00:00:00+00:00 2026-02-11T14:49:27+00:00 Matt Garnetthttps://github.com/lightclient Uri Klarmanhttps://github.com/uriklarman Ben Adamshttps://github.com/benaadams Maria Inês Silvahttps://github.com/misilva73 Anders Elowssonhttps://github.com/anderselowsson Anthony Sassanohttps://github.com/sassal https://wg-eips.ritovision.com/2780/

Reduce intrinsic transaction gas and charge 25k when a value transfer creates a new account

<h2 id="abstract">Abstract</h2> <p>Reduce the intrinsic cost <code>TX_BASE_COST</code> from <code>21,000</code> to <code>4,500</code> and define a consistent gas accounting model based on actual state operations. This more granular approach makes a simple ETH transfer <code>6,000</code> from additional costs related to the <code>to</code> account.</p> <p>If a non-create transaction has <code>value &gt; 0</code> and targets a non-existent account, charge <code>GAS_NEW_ACCOUNT = 25,000</code> to align with <code>CALL</code> account creation and price in state growth. When this surcharge applies, the recipient pays exactly one cold non-code touch; no code-load cost applies.</p> <p>This EIP does not change calldata or access-list metering. It also refines related gas schedule items used in derivation and execution accounting:</p> <ul> <li>Split cold-account touches into <code>COLD_ACCOUNT_COST_CODE = 2,600</code> and <code>COLD_ACCOUNT_COST_NOCODE = 500</code>.</li> <li>Introduce <code>STATE_UPDATE = 1,000</code> as the price of a single account-leaf write.</li> <li>Reprice value-moving calls as account-leaf writes, replacing <code>CALL_VALUE_COST = 9,000</code> with <code>CALL_VALUE_COST = 2 * STATE_UPDATE = 2,000</code>.</li> <li>Specify that a <code>PAY</code>-style value-move primitive, if present, does not warm its recipient and never loads code (charged at <code>COLD_ACCOUNT_COST_NOCODE</code> if not already warmed).</li> </ul> <p>Capacity impact (illustrative):</p> <table><thead><tr><th>Metric</th><th style="text-align: right">Result</th><th style="text-align: right">Change</th><th>Description</th></tr></thead><tbody> <tr><td>Max (minimal txs)</td><td style="text-align: right">13,333 tx / block</td><td style="text-align: right">+367%</td><td>4,500-gas minimal transactions per 60 M block</td></tr> <tr><td>Max (ETH transfers)</td><td style="text-align: right">10,000 tx / block</td><td style="text-align: right">+250%</td><td>6,000-gas ETH transfers per 60 M block</td></tr> <tr><td>Thoughput (minimal txs)</td><td style="text-align: right">~1,111 TPS</td><td style="text-align: right">+367%</td><td>4,500-gas minimal transactions per 60 M block per 12sec</td></tr> <tr><td>Thoughput (ETH transfers)</td><td style="text-align: right">~833 TPS</td><td style="text-align: right">+250%</td><td>6,000-gas ETH transfers per 60 M block per 12sec</td></tr> <tr><td>Equivalent gas-limit uplift</td><td style="text-align: right">≈ +20.8%</td><td style="text-align: right">-</td><td>Effective throughput gain for ave tx usage (e.g., 60 M =&gt; ~72.5 M)</td></tr> </tbody></table> <h2 id="motivation">Motivation</h2> <p><strong>Monetary Context</strong></p> <p>Money has three basic functions: a unit of account, a medium of exchange, and a store of value. ETH already meets the last two by design. It carries value without an issuer and settles with finality. Where it falls short is in everyday exchange - the friction of use rather than the nature of the asset.</p> <p>ETH underpins most onchain liquidity. Pairs are denominated in it, and gas is paid in it - a de-facto tax base that anchors value. Bitcoin's monetary role now runs mainly through exchange pairs, hence its drift in focus to store-of-value rather than medium-of-exchange. ETH still clears real activity onchain, yet outside NFTs few people think in ETH terms. In that niche ETH already functions as both unit and medium, but only for high-value items.</p> <p>For ETH to operate fully as money, it must also handle small transactions. That was impractical when gas sat at 300 gwei, or even 90 gwei on quiet weekends. Post-4844, blobs absorb L2's "pay at any price" data and higher gaslimits ease congestion; cost, not capacity, is the bottleneck.</p> <p>EIP-2780 lowers that fixed cost. By aligning the base gas with the real work of a transaction and by correcting <code>CALL</code> value pricing, it removes the legacy penalty on simple payments. Small transfers become viable again without subsidising calldata or storage. The same logic charges properly for new-account creation, so state growth remains priced in.</p> <ul> <li> <p><strong>Unit of account:</strong> When transfers are cheap and regular, people price in ETH because they use it directly. This proposal turns that habit into equilibrium rather than idealism.</p> </li> <li> <p><strong>Medium of exchange:</strong> Reducing <code>TX_BASE_COST</code> eliminates the old friction that slowed native circulation. Settlement becomes frequent, not occasional.</p> </li> <li> <p><strong>Store of value:</strong> Honest pricing reinforces confidence that ETH's cost structure is grounded in real computation, not arbitrary constants.</p> </li> <li> <p><strong>Velocity:</strong> Lower friction raises the rate of final settlement; more frequent, smaller clears in native ETH, without altering calldata or storage economics.</p> </li> <li> <p><strong>Monetary competition:</strong> Stablecoins and LSTs are welcome, but they compete for onchain "moneyness". Making native ETH easy to spend keeps it central; not just the fuel, but the money of the system.</p> </li> </ul> <p><strong>Note:</strong> This proposal doesn't target ETH specifically, the lower base cost applies to every transaction type. However since <code>TX_BASE_COST</code> makes up nearly all of an ETH transfer's gas, while it's only a small fraction of contract calls, ETH loses the most friction and gains the most velocity.</p> <p><strong>Specifics</strong></p> <p>The legacy <code>21,000</code> base no longer matches the universal work path under warm/cold accounting. Decomposed into signature recovery, one account-leaf write for the sender (nonce + balance coalesced), and one cold non-code touch (sender), the universal path totals <code>4,500</code> gas.</p> <p>State growth is underpriced for top-level value transfers that create accounts, while <code>CALL</code> pays explicit creation. Charging <code>25,000</code> when a transfer creates an account aligns entry points and internalizes state growth.</p> <p>A lower base removes the distortion that over-incentivized batching solely to dodge <code>TX_BASE_COST</code>, without subsidizing calldata or storage. The refinement of value-transfer costs and cold-account pricing makes execution charges proportional to actual state work: account touches and leaf writes.</p> <p>We intentionally do <strong>not</strong> charge per-byte gas for the transaction envelope (<code>nonce</code>, <code>gas*</code>, <code>to</code>, <code>value</code>, <code>v</code>, <code>r</code>, <code>s</code>). Calldata pricing applies only to <code>tx.data</code>. A plain ETH payment has empty <code>tx.data</code>, so it pays zero calldata gas. Lowering <code>TX_BASE_COST</code> to the universal work path makes ETH payments cheaper without subsidizing arbitrary calldata.</p> <h3 id="throughput-payload-and-basefee-dynamics">Throughput, payload, and basefee dynamics</h3> <p>This EIP affects three independent levers:</p> <ol> <li> <p><strong>Gas-limit equivalence:</strong> Reducing the base cost from <code>21,000</code> to <code>4,500</code> increases transaction capacity at a fixed block gaslimit by approximately +20.8%.</p> </li> <li> <p><strong>Payload-size bounds:</strong> Per <a href="https://wg-eips.ritovision.com/7934/">EIP-7934</a> the execution payload cap is <code>MAX_RLP_BLOCK_SIZE = 10,485,760 - 2,097,152 = 8,388,608</code> bytes. Payload size, not gas, may become the dominant block-size constraint at high gaslimits.</p> </li> <li> <p><strong>Basefee market dynamics:</strong> Lower intrinsic gas reduces the average gas per tx, temporarily increasing utilisation and causing short-term downward adjustment in basefee. Over time, equilibrium restores as inclusion policies adapt.</p> </li> </ol> <p>These levers are independent; this proposal changes only intrinsic gas, not calldata metering or access-list pricing.</p> <h3 id="monetary-effects">Monetary Effects</h3> <p>Reducing ETH transfer cost from <code>21,000</code> =&gt; <code>6,000</code> gas increases both transaction frequency and viable payment granularity. At a fixed basefee, smaller payments become economical, raising the <strong>velocity of money</strong> - how often ETH changes hands on L1.</p> <p>Let $g$ be gas per transaction, $b$ the basefee (in gwei), and $r$ the user's tolerated fee share of payment value.</p> <p>$v_{\text{min}} = \frac{g \times b \times 10^{-9}}{r}$</p> <p>Since $g$ drops from $21,000$ to $6,000$:</p> <p>$\frac{v_{\text{min,new}}}{v_{\text{min,old}}} = \frac{6{,}000}{21{,}000} \approx 0.29$</p> <p>The minimum economical L1 payment falls by about <strong>71 %</strong>, allowing more, smaller transfers to clear directly in ETH.</p> <p>From the quantity relation $M V = P Q$, with $M$ and $P$ roughly constant over short periods:</p> <p>$V_{\text{new}} / V_{\text{old}} \approx Q_{\text{new}} / Q_{\text{old}}$</p> <p>Pure ETH-transfer capacity rises roughly <strong>3.5x</strong> (+250 %), and the lower $v_{\text{min}}$ further increases $Q$ as more small-value payments become viable.</p> <p>Together these effects lift $V$, more frequent, smaller, native settlements without changing monetary supply.</p> <p>ETH thus gains moneyness:</p> <ul> <li><strong>Medium of exchange:</strong> direct use becomes routine, not exceptional.</li> <li><strong>Unit of account:</strong> frequent native settlement encourages ETH-denominated pricing.</li> <li><strong>Store of value:</strong> workload-based fees reinforce trust in cost realism.</li> </ul> <p>Price volatility may still lead users to prefer stablecoins for predictability, but this change removes unnecessary friction, restoring ETH’s competitiveness wherever volatility is tolerable.</p> <p>The <code>25,000</code> surcharge for new-account creation continues to price state growth honestly while everyday transfers become cheaper and faster.</p> <h3 id="equivalent-gas-limit-increase">Equivalent gas-limit increase</h3> <p>Lowering <code>TX_BASE_COST</code> from <code>21,000</code> to <code>4,500</code> removes up to <code>16,500</code> gas per transaction. Using recent totals of 163 Ggas/day and 1.7 M tx/day:</p> <table><thead><tr><th>Metric</th><th style="text-align: right">Calculation</th><th style="text-align: right">Result</th><th style="text-align: right">Change</th></tr></thead><tbody> <tr><td>Avg gas per tx</td><td style="text-align: right">163Bn / 1.7M</td><td style="text-align: right">≈ 95,882 gas</td><td style="text-align: right">-</td></tr> <tr><td>New avg gas per tx</td><td style="text-align: right">95,882 − 16,500</td><td style="text-align: right">≈ 79,382 gas</td><td style="text-align: right">-</td></tr> <tr><td>Throughput at fixed gaslimit</td><td style="text-align: right">95,882 / 79,382</td><td style="text-align: right">≈ x1.208</td><td style="text-align: right">+20.08%</td></tr> <tr><td>Daily tx at same gas usage</td><td style="text-align: right">1.7M × 1.208</td><td style="text-align: right">≈ 2.053M tx/day</td><td style="text-align: right">+340k/day</td></tr> </tbody></table> <p>Perfnet measurements show EL clients handle &gt;300 MGas/s for pure ETH transfers. Expressed under a 4.5k base this corresponds to <code>300 * (4.5/21) ~ 64.3 MGas/s</code>, i.e. <code>~771 MGas</code> per 12 s slot. This indicates sufficient headroom and that the current base is significantly overcharged, so no extra engineering is required to improve performance to support this change.</p> <p>Net effect equals raising a 45 M gas limit to ~54.4 M at unchanged calldata and access-list metering. This directly advances Scaling L1.</p> <h2 id="specification">Specification</h2> <p>After <code>FORK_BLOCK</code>, set the following parameters and rules:</p> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Name</th><th style="text-align: right">Value</th><th>Description</th></tr></thead><tbody> <tr><td><code>TX_BASE_COST</code></td><td style="text-align: right">4,500</td><td>Base cost of any transaction</td></tr> <tr><td><code>GAS_NEW_ACCOUNT</code></td><td style="text-align: right">25,000</td><td>Surcharge when a value-transferring transaction creates a new account</td></tr> <tr><td><code>STATE_UPDATE</code></td><td style="text-align: right">1,000</td><td>One account-leaf write in the account trie (nonce and balance coalesce)</td></tr> <tr><td><code>COLD_ACCOUNT_COST_CODE</code></td><td style="text-align: right">2,600</td><td>Cold touch of an account with code</td></tr> <tr><td><code>COLD_ACCOUNT_COST_NOCODE</code></td><td style="text-align: right">500</td><td>Cold touch of an account known to have no code</td></tr> <tr><td><code>WARM_STATE_READ</code></td><td style="text-align: right">100</td><td>Touch of an already-warm account (same as <code>WARM_STORAGE_READ_COST</code>)</td></tr> </tbody></table> <p>The intrinsic gas accounting defined here overrides <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>'s blanket "all tx addresses are warm" rule.</p> <p>A transaction’s intrinsic base is decomposed into explicit primitives, so warmth must be priced explicitly.</p> <ul> <li> <p><code>tx.sender</code> is charged as a cold non-code account (<code>COLD_ACCOUNT_COST_NOCODE = 500</code>), representing the first access and coalesced account-leaf update.</p> </li> <li> <p><code>tx.to</code> is charged based on its type:</p> <ul> <li> <p>if a contract create, charge under those rules.</p> </li> <li> <p>if an EOA or an empty account, use <code>COLD_ACCOUNT_COST_NOCODE = 500</code>.</p> </li> <li> <p>if a contract, use <code>COLD_ACCOUNT_COST_CODE = 2,600</code>.</p> </li> <li> <p>if a precompile, it is warm at tx start and charged zero.</p> </li> </ul> </li> <li> <p>Warmth discovered through an access list still applies and overrides the cold cost.</p> </li> </ul> <p>This decomposition replaces the implicit warmth assumptions of <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a> and makes the per-account cost explicit in the base or the execution phase as appropriate.</p> <p>Notes:</p> <ul> <li><code>STATE_UPDATE</code> counts writes at the account-leaf granularity. If a single account's nonce and balance both change in one transition, charge one <code>STATE_UPDATE</code>.</li> <li><code>COLD_ACCOUNT_COST_NOCODE</code> reflects that non-code accounts do not load code or a storage trie, so have a lower warming cost.</li> <li>A regular ETH transfer additionally includes a cold touch of at least <code>COLD_ACCOUNT_COST_NOCODE</code> and a <code>STATE_UPDATE</code> of the <code>to</code> address, so the effective minimal productive tx cost is <code>6,000</code>.</li> <li>Not including the <code>to</code> cold warming and <code>STATE_UPDATE</code> in <code>TX_BASE_COST</code> means a contract-interaction transaction that does not transfer value does not unnecessarily pay these additional costs.</li> </ul> <h3 id="derivation-non-normative">Derivation (non-normative)</h3> <p>Decomposition of the base cost into universal primitives:</p> <table><thead><tr><th>Component</th><th style="text-align: right">Cost</th><th>Notes</th></tr></thead><tbody> <tr><td>ECRECOVER</td><td style="text-align: right">3,000</td><td>Elliptic curve signature recovery</td></tr> <tr><td>STATE_UPDATE</td><td style="text-align: right">1,000</td><td>One account-leaf write (nonce + balance coalesced)</td></tr> <tr><td>COLD_ACCOUNT_COST_NOCODE</td><td style="text-align: right">500</td><td>Sender is cold and has no code</td></tr> <tr><td><strong>TX_BASE_COST</strong></td><td style="text-align: right"><strong>4,500</strong></td><td>Sum of above (3,000 + 1,000 + 500)</td></tr> </tbody></table> <h3 id="new-account-surcharge">New-account surcharge</h3> <p>Apply <code>GAS_NEW_ACCOUNT</code> when <strong>all</strong> are true:</p> <ol> <li>The transaction is not a <code>CREATE</code> transaction.</li> <li><code>value &gt; 0</code>.</li> <li><code>to</code> is not a precompile.</li> <li><code>to</code> is non-existent per <a href="https://wg-eips.ritovision.com/161/">EIP-161</a> emptiness at the start of transaction execution.</li> </ol> <p>The <code>GAS_NEW_ACCOUNT = 25,000</code>charge covers state growth (new leaf creation and one <code>STATE_UPDATE</code>). An additional <code>COLD_ACCOUNT_COST_NOCODE = 500</code> applies for the initial lookup to determine that the account does not exist.</p> <p>Thus, the <strong>total</strong> intrinsic gas for a value-transferring transaction to a new account is <code>30,000</code> (<code>4,500 base + 500 lookup + 25,000 new-account surcharge</code>).</p> <p>For reference, the <strong>total</strong> charges for such transfers change from 21,000 to 30,000.</p> <table><thead><tr><th>Component</th><th style="text-align: right">Cost</th><th>Notes</th></tr></thead><tbody> <tr><td>TX_BASE_COST</td><td style="text-align: right">4,500</td><td>Base transaction cost</td></tr> <tr><td>COLD_ACCOUNT_COST_NOCODE</td><td style="text-align: right">500</td><td>Recipient cold lookup (execution charge)</td></tr> <tr><td>GAS_NEW_ACCOUNT</td><td style="text-align: right">25,000</td><td>Account creation, includes leaf write</td></tr> <tr><td><strong>Total</strong></td><td style="text-align: right"><strong>30,000</strong></td><td>Sum of above (4,500 + 500 + 25,000)</td></tr> </tbody></table> <p>Notes:</p> <ul> <li>If <code>value = 0</code> and <code>to</code> is empty per <a href="https://wg-eips.ritovision.com/161/">EIP-161</a>, no account is created and no surcharge applies.</li> <li><code>CREATE</code> transactions are unchanged; their cost already includes account creation.</li> </ul> <h3 id="intrinsic-gas-computation">Intrinsic gas computation</h3> <p>Clients compute intrinsic gas as today for each typed transaction <strong>except</strong>:</p> <ul> <li>Replace any hardcoded <code>21,000</code> with <code>TX_BASE_COST = 4,500</code>.</li> <li>Add <code>GAS_NEW_ACCOUNT</code> when the <em>New-account surcharge</em> conditions hold.</li> </ul> <h3 id="pseudocode-normative">Pseudocode (normative):</h3> <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"> CalculateIntrinsicGas</span><span>(</span><span class="z-variable z-parameter z-function">tx</span><span>,</span><span class="z-variable z-parameter z-function"> state_at_start</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> gasCost</span><span class="z-keyword"> =</span><span class="z-constant"> TX_BASE_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"> Existing rules for calldata and access lists remain unchanged by this EIP.</span></span> <span class="giallo-l"><span> gasCost</span><span class="z-keyword"> +=</span><span> GasForCalldata</span><span>(</span><span>tx</span><span>.</span><span>data</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> per active calldata pricing EIPs</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> tx</span><span>.</span><span>has_access_list</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> gasCost</span><span class="z-keyword"> +=</span><span> GasForAccessList</span><span>(</span><span>tx</span><span>.</span><span>access_list</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> per EIP-2930</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> tx</span><span>.</span><span>is_create</span><span>(</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> tx</span><span>.</span><span>value</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> is_precompile</span><span>(</span><span>tx</span><span>.</span><span>to</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> is_nonexistent_per_eip161</span><span>(</span><span>state_at_start</span><span>,</span><span> tx</span><span>.</span><span>to</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> gasCost</span><span class="z-keyword"> +=</span><span class="z-constant"> GAS_NEW_ACCOUNT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> gasCost</span></span></code></pre><h3 id="evm-gas-schedule-adjustments">EVM gas schedule adjustments</h3> <p>These changes refine execution-layer accounting to align with the primitives above.</p> <ul> <li> <p><strong>Value-moving calls.</strong> Replace the legacy <code>CALL_VALUE_COST = 9,000</code> with:</p> <ul> <li>If recipient exists: <code>CALL_VALUE_COST = 2 * STATE_UPDATE = 2,000</code>.</li> <li>If recipient is EIP-161-empty: <code>CALL_VALUE_COST = STATE_UPDATE + GAS_NEW_ACCOUNT = 26,000</code>.</li> <li>This charge is in addition to warm/cold account-touch costs per EIP-2929 and the existing <code>CALL</code> base cost. This EIP does not modify the <code>CALL</code> base cost. The <code>CALL_VALUE_COST = 2,000</code> applies for all value-carrying calls, regardless of whether the callee's account has already been updated earlier in the same transaction. This ensures the 2300-gas stipend mechanism remains safe and consistent for simple value forwarding and does not retroactively depend on account-update history.</li> </ul> </li> <li> <p><strong>Cold-account touches.</strong></p> <ul> <li>Use <code>COLD_ACCOUNT_COST_CODE = 2,600</code> when touching an account with code.</li> <li>Use <code>COLD_ACCOUNT_COST_NOCODE = 500</code> when touching an account known to have no code.</li> </ul> </li> <li> <p><strong>Warmth policy.</strong></p> <ul> <li>Access-list entries (charged via <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a>) and precompiles are warm at tx start.</li> <li><code>CALL</code> warms its <code>to</code> after charging the appropriate cold cost if cold.</li> <li>A <code>PAY</code>-style pure value-move primitive, if present, does not warm its recipient and never loads code. It pays <code>WARM_STATE_READ = 100</code> if warm for unrelated reasons, else <code>COLD_ACCOUNT_COST_NOCODE = 500</code>, plus the value-write cost above.</li> </ul> </li> <li> <p><strong>Self-transfers.</strong> If <code>from == to</code>, only one <code>STATE_UPDATE</code> occurs. The sender's nonce and balance update are coalesced into the same leaf write. No recipient lookup or separate write is charged. (Is a NOP tx other than charging gas and incrementing nonce).</p> </li> </ul> <h3 id="transaction-reference-cases">Transaction reference cases</h3> <table><thead><tr><th>Case</th><th>Formula</th><th style="text-align: right">Total Cost</th></tr></thead><tbody> <tr><td>(NOP) No-transfer to EOA</td><td><code>TX_BASE_COST</code></td><td style="text-align: right">4,500</td></tr> <tr><td>(NOP) No-transfer to empty account</td><td><code>TX_BASE_COST</code></td><td style="text-align: right">4,500</td></tr> <tr><td>(NOP) ETH transfer to self</td><td><code>TX_BASE_COST</code></td><td style="text-align: right">4,500</td></tr> <tr><td>ETH Transfer to existing EOA</td><td><code>TX_BASE_COST</code> + <code>COLD_ACCOUNT_COST_NOCODE</code> + <code>STATE_UPDATE</code></td><td style="text-align: right">6,000</td></tr> <tr><td>No-transfer to contract</td><td><code>TX_BASE_COST</code> + <code>COLD_ACCOUNT_COST_CODE</code> + <strong>execution</strong></td><td style="text-align: right">7,100 + <strong>execution</strong></td></tr> <tr><td>ETH Transfer to contract</td><td><code>TX_BASE_COST</code> + <code>COLD_ACCOUNT_COST_CODE</code> + <code>STATE_UPDATE</code> + <strong>execution</strong></td><td style="text-align: right">8,100 + <strong>execution</strong></td></tr> <tr><td>ETH Transfer creating new account</td><td><code>TX_BASE_COST</code> + <code>COLD_ACCOUNT_COST_NOCODE</code> + <code>GAS_NEW_ACCOUNT</code></td><td style="text-align: right">30,000</td></tr> </tbody></table> <p>This aligns costs with actual state work rather than legacy flat surcharges.</p> <h3 id="edits-and-interactions-with-other-eips">Edits and interactions with other EIPs</h3> <ul> <li><strong><a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> (Access List).</strong> Intrinsic gas is <code>TX_BASE_COST</code> after <code>FORK_BLOCK</code>. Access lists keep their existing per-entry charges and warming semantics.</li> <li><strong><a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a> (Gas cost increases for state access).</strong> Refined by this EIP to price non-code cold touches at <code>500</code> and code-account cold touches at <code>2,600</code>.</li> <li><strong><a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> (Set EOA Code).</strong> <code>TX_BASE_COST</code> remains <code>4,500</code> even if the sender temporarily assumes code for the transaction. Clients must not perform any disk code-load to determine sender type, since 7702 provides code inline. If the transaction executes code that reads or executes its own code, normal <code>COLD_ACCOUNT_COST_CODE</code> or <code>WARM_STATE_READ</code> costs apply at execution time as per the standard cold/warm model.</li> <li><strong>Calldata-pricing EIPs (e.g. <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a>).</strong> Unchanged. This EIP does not alter calldata pricing.</li> </ul> <h2 id="rationale">Rationale</h2> <p>Price only what every transaction always does: ECDSA recovery, warming <code>sender</code> and <code>to</code>, and one account-leaf write for the sender (nonce + balance change). That sums to <code>4,500</code> gas. Anything not universal should be metered separately.</p> <p>Calldata remains metered per byte. No calldata allowance is folded into the base. This reinforces ETH as money and payments: a plain ETH transfer carries no calldata, executes no bytecode, and touches no contract storage slots. It adds exactly one recipient touch (when not a smart contract) and one recipient leaf write, so its total is <code>6,000</code>.</p> <p><code>CREATE</code> is unchanged because its cost already includes account creation. Access-list pricing is unchanged.</p> <p>Legacy pricing undercharged top-level ETH transfers that created new accounts relative to internal <code>CALL</code>-based creations. This EIP corrects that by charging <code>GAS_NEW_ACCOUNT = 25,000</code>, identical to the <code>CALL</code> account-creation surcharge, ensuring consistent pricing for state growth regardless of entry path.</p> <p>This removes cross-subsidies, aligns charges with resources, and keeps costs equal across paths that perform the same state growth.</p> <p>Do not fold any calldata allowance into the base. The envelope RLP (<code>nonce</code>, <code>gas*</code>, <code>to</code>, <code>value</code>, <code>v</code>, <code>r</code>, <code>s</code>) is not charged as calldata and remains unmetered per byte. Only <code>tx.data</code> bytes are metered at the existing calldata schedule, and access lists keep their per-entry costs. A vanilla ETH transfer executes no bytecode and touches no contract storage slots; it performs signature recovery, warms the sender, and updates sender and recipient accounts. It therefore receives the base discount and pays only the additional recipient costs.</p> <p>Bundling multiple transfers into a single contract call avoids repeated <code>TX_BASE_COST</code>, but those transfers then execute serially inside one EVM context. That blocks parallel execution. With a lower per-tx base cost, users have less incentive to bundle, so more transfers remain independent transactions. Independent transactions can be scheduled across threads, which improves parallelism at the client and execution-layer level.</p> <p>Thus, reducing <code>TX_BASE_COST</code> not only corrects mispricing but also increases the share of transactions that are naturally parallelizable.</p> <p>This EIP composes cleanly with calldata-pricing proposals such as <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> and <a href="https://wg-eips.ritovision.com/7976/">EIP-7976</a>. Those EIPs affect <code>tx.data</code> metering, while this EIP adjusts only transaction-level intrinsic accounting. There is no overlapping scope.</p> <h3 id="why-not-charge-full-tx-data-as-calldata">Why not charge full tx data as calldata?</h3> <ul> <li> <p><strong>Intrinsic coupling to signed fields.</strong> Pricing full-transaction bytes would make intrinsic gas depend on <code>gas_limit</code> and variable-length signature elements, creating fixed-point estimation issues and incentives for signature-length selection as well as iteration unstablity as <code>gas_limit</code> depends on signiture which contains <code>gas_limit</code>.</p> </li> <li> <p><strong>Serialization neutrality.</strong> A fee rule keyed to RLP size couples costs to one encoding and weakens <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> type neutrality and future formats such as SSZ. Calldata is treated as opaque bytes so it avoids this coupling.</p> </li> <li> <p><strong>Policy targeting and market floor.</strong> Calldata floors (for example <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> or <a href="https://wg-eips.ritovision.com/7976/">EIP-7976</a>) price bytes in <code>tx.data</code> to bound EL payload and steer data to blobs; envelope bytes are control-plane. The <code>TX_BASE_COST</code> is the smallest tx size, and having a low encoding-agnostic intrinsic base keeps the minimum inclusion price coupled to the basefee market, without opening a DoS vector.</p> </li> <li> <p><strong>Native settlement and unit-of-account.</strong> Even though all transactions receive the same absolute gas reduction, it proportionally improves pristine ETH transfers more. With an ETH transfer at ~6,000 gas vs a permissioned ERC-20/LST/stablecoin transfer at ~48,000 gas, you get ~8x higher payment throughput per unit gas, which reinforces ETH as the settlement asset and reduces reliance on contract-based money (which carries smart contract risk, operator risk, governance risk and censorship risks via smart contract operator).</p> </li> </ul> <p><img src="https://wg-eips.ritovision.com/2780/./assets/1.png" alt="Figure 1" /></p> <h3 id="effects-on-transactions-per-block">Effects on transactions per block</h3> <p>For execution-payload size, use <a href="https://wg-eips.ritovision.com/7934/">EIP-7934</a>’s 8 MiB uncompressed cap: <code>8,388,608 bytes</code>. A typical EIP-1559 ETH transfer encodes at roughly <code>~110 bytes</code>, yielding a size cap of <code>floor(8,388,608 / 110) = 76,260 tx</code> per block when size, not gas, is the binding constraint.</p> <p>There are two useful ceilings to consider:</p> <ul> <li>Minimal transaction with no value and no execution: <code>TX_BASE_COST = 4,500</code> gas.</li> <li>Minimal ETH payment to an existing EOA: <code>6,000</code> gas (<code>TX_BASE_COST + COLD_ACCOUNT_COST_NOCODE + STATE_UPDATE</code>).</li> </ul> <p>Counts below are <code>floor(gaslimit / per-tx-gas)</code>, then capped by <code>76,260</code> when the 8 MiB size limit binds. TPS figures round to the nearest integer.</p> <h4 id="scenario-a-minimal-txs-at-4-500-gas">Scenario A: minimal txs at 4,500 gas</h4> <p>Binding point for size-cap dominance: <code>76,260 * 4,500 = 343,170,000</code> gas. At gaslimits above ~343.17 M, block size, not gas, limits the tx count for 4,500-gas transactions.</p> <table><thead><tr><th style="text-align: right">Block gaslimit</th><th style="text-align: right">Old tx/bk (21k)</th><th style="text-align: right">New tx/bk (4.5k)</th><th style="text-align: right">TPS @ 12s</th><th style="text-align: right">TPS @ 6s</th><th style="text-align: right">TPS @ 3s</th><th style="text-align: right">TPS @ 1.5s</th></tr></thead><tbody> <tr><td style="text-align: right">45 M</td><td style="text-align: right">2,142</td><td style="text-align: right">10,000</td><td style="text-align: right">833</td><td style="text-align: right">1,667</td><td style="text-align: right">3,333</td><td style="text-align: right">6,667</td></tr> <tr><td style="text-align: right">60 M</td><td style="text-align: right">2,857</td><td style="text-align: right">13,333</td><td style="text-align: right">1,111</td><td style="text-align: right">2,222</td><td style="text-align: right">4,444</td><td style="text-align: right">8,889</td></tr> <tr><td style="text-align: right">100 M</td><td style="text-align: right">4,761</td><td style="text-align: right">22,222</td><td style="text-align: right">1,852</td><td style="text-align: right">3,704</td><td style="text-align: right">7,407</td><td style="text-align: right">14,815</td></tr> <tr><td style="text-align: right">200 M</td><td style="text-align: right">9,523</td><td style="text-align: right">44,444</td><td style="text-align: right">3,704</td><td style="text-align: right">7,407</td><td style="text-align: right">14,815</td><td style="text-align: right">29,629</td></tr> <tr><td style="text-align: right">450 M</td><td style="text-align: right">21,428</td><td style="text-align: right">†76,260</td><td style="text-align: right">6,355</td><td style="text-align: right">12,710</td><td style="text-align: right">25,420</td><td style="text-align: right">50,840</td></tr> </tbody></table> <p>† Size cap binds at 450 M because 450 M &gt; 343.17 M.</p> <h4 id="scenario-b-eth-transfers-at-6-000-gas">Scenario B: ETH transfers at 6,000 gas</h4> <p>Binding point for size-cap dominance: <code>76,260 * 6,000 = 457,560,000</code> gas. At gaslimits below ~457.56 M, gas limits tx count; above it, the 8 MiB size cap dominates.</p> <table><thead><tr><th style="text-align: right">Block gaslimit</th><th style="text-align: right">Old tx/bk (21k)</th><th style="text-align: right">New tx/bk (6k)</th><th style="text-align: right">TPS @ 12s</th><th style="text-align: right">TPS @ 6s</th><th style="text-align: right">TPS @ 3s</th><th style="text-align: right">TPS @ 1.5s</th></tr></thead><tbody> <tr><td style="text-align: right">45 M</td><td style="text-align: right">2,142</td><td style="text-align: right">7,500</td><td style="text-align: right">625</td><td style="text-align: right">1,250</td><td style="text-align: right">2,500</td><td style="text-align: right">5,000</td></tr> <tr><td style="text-align: right">60 M</td><td style="text-align: right">2,857</td><td style="text-align: right">10,000</td><td style="text-align: right">833</td><td style="text-align: right">1,667</td><td style="text-align: right">3,333</td><td style="text-align: right">6,667</td></tr> <tr><td style="text-align: right">100 M</td><td style="text-align: right">4,761</td><td style="text-align: right">16,666</td><td style="text-align: right">1,389</td><td style="text-align: right">2,778</td><td style="text-align: right">5,555</td><td style="text-align: right">11,111</td></tr> <tr><td style="text-align: right">200 M</td><td style="text-align: right">9,523</td><td style="text-align: right">33,333</td><td style="text-align: right">2,778</td><td style="text-align: right">5,556</td><td style="text-align: right">11,111</td><td style="text-align: right">22,222</td></tr> <tr><td style="text-align: right">450 M</td><td style="text-align: right">21,428</td><td style="text-align: right">75,000</td><td style="text-align: right">6,250</td><td style="text-align: right">12,500</td><td style="text-align: right">25,000</td><td style="text-align: right">50,000</td></tr> </tbody></table> <h4 id="changes-for-common-types-of-txs">Changes for common types of txs</h4> <table><thead><tr><th>Transaction Type</th><th style="text-align: right">Old Cost</th><th style="text-align: right">New Cost</th><th style="text-align: right">Change</th></tr></thead><tbody> <tr><td>Simple ETH transfer (existing EOA)</td><td style="text-align: right">21,000</td><td style="text-align: right">6,000</td><td style="text-align: right">−71 %</td></tr> <tr><td>ETH transfer creating new EOA</td><td style="text-align: right">21,000</td><td style="text-align: right">30,000</td><td style="text-align: right">+43 %</td></tr> <tr><td>ERC-20 transfer (typical)</td><td style="text-align: right">63,200</td><td style="text-align: right">48,200</td><td style="text-align: right">−24 %</td></tr> <tr><td>ERC-20 transfer (Solady)</td><td style="text-align: right">33,400</td><td style="text-align: right">18,400</td><td style="text-align: right">−45 %</td></tr> <tr><td>Uniswap v3 swap</td><td style="text-align: right">184,500</td><td style="text-align: right">169,500</td><td style="text-align: right">−8 %</td></tr> <tr><td>Uniswap v3 add-liquidity</td><td style="text-align: right">216,900</td><td style="text-align: right">201,900</td><td style="text-align: right">−7 %</td></tr> </tbody></table> <h4 id="reference-mgas-s-for-gaslimit-vs-slot-time">Reference MGas/s for gaslimit vs slot time</h4> <table><thead><tr><th style="text-align: right">Block gaslimit</th><th style="text-align: right">MGas/s @ 12s</th><th style="text-align: right">MGas/s @ 6s</th><th style="text-align: right">MGas/s @ 3s</th><th style="text-align: right">MGas/s @ 1.5s</th></tr></thead><tbody> <tr><td style="text-align: right">45 M</td><td style="text-align: right">3.75</td><td style="text-align: right">7.50</td><td style="text-align: right">15.00</td><td style="text-align: right">30.00</td></tr> <tr><td style="text-align: right">60 M</td><td style="text-align: right">5.00</td><td style="text-align: right">10.00</td><td style="text-align: right">20.00</td><td style="text-align: right">40.00</td></tr> <tr><td style="text-align: right">100 M</td><td style="text-align: right">8.33</td><td style="text-align: right">16.67</td><td style="text-align: right">33.33</td><td style="text-align: right">66.67</td></tr> <tr><td style="text-align: right">200 M</td><td style="text-align: right">16.67</td><td style="text-align: right">33.33</td><td style="text-align: right">66.67</td><td style="text-align: right">133.33</td></tr> <tr><td style="text-align: right">450 M</td><td style="text-align: right">37.50</td><td style="text-align: right">75.00</td><td style="text-align: right">150.00</td><td style="text-align: right">300.00</td></tr> </tbody></table> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is <strong>not</strong> backward compatible. It is a consensus gas repricing that must be activated at <code>FORK_BLOCK</code>.</p> <p>Wallets, RPCs, gas estimators, and any logic that assumes a <code>21,000</code> base must update.</p> <h2 id="test-cases">Test Cases</h2> <p>While the benefits of reducing transactions' intrinsic cost are apparent, such a change should be applied if it imposes no negative externalities, or if such effects are negligible.</p> <p>Tests should be created with blocks of just ETH transfers and tested on Perfnet across all EL clients to ensure the pricing is correct.</p> <p>Add explicit test vectors (intrinsic gas only):</p> <ol> <li><code>value &gt; 0</code> to an empty EOA (non-existent per EIP-161): intrinsic <code>30,000</code> (4,500 base + 500 + 25,000 surcharge).</li> <li><code>value &gt; 0</code> to a precompile: intrinsic <code>4,500</code> (no surcharge; precompiles are warm at tx start).</li> <li><code>value = 0</code> to an empty address: intrinsic <code>4,500</code> (no creation, no surcharge).</li> <li><code>CREATE</code> transaction: unchanged from prior rules.</li> <li>EIP-7702 transaction with and without access list: intrinsic uses <code>TX_BASE_COST</code> plus unchanged access-list costs.</li> <li>Block of txs calling minimal gas contract execution with maximal contract size addresses (so VM is activated for every tx).</li> <li>Warmth and access list interplay <ul> <li>ETH transfer to existing EOA without access list: charge <code>COLD_ACCOUNT_COST_NOCODE = 500</code> for recipient lookup.</li> <li>Same transaction with recipient in access list: charge <code>WARM_STATE_READ = 100</code>.</li> </ul> </li> <li>7702 interactions <ul> <li>7702 tx where sender assumes code and calls nothing: intrinsic = 4,500, no extra cold-code cost.</li> <li>7702 tx where sender assumes code and executes self-code: charge <code>COLD_ACCOUNT_COST_CODE</code> when first loaded.</li> </ul> </li> <li>Precompile transfers <ul> <li><code>value &gt; 0</code> to <code>0x01</code>–<code>0x09</code>: intrinsic = 4,500, no surcharge.</li> </ul> </li> <li>Self-transfer <code>from == to</code>: total = 4,500.</li> <li>Internal CALL repricing <ul> <li>Internal <code>CALL</code> to existing EOA with value: <code>CALL_VALUE_COST = 2,000</code> plus cold/warm costs.</li> <li>Internal <code>CALL</code> to EIP-161-empty: <code>CALL_VALUE_COST = 26,000</code>.</li> </ul> </li> <li>Zero-value edge cases <code>value = 0</code> to empty address: intrinsic = <code>4,500</code>.</li> <li>Perfnet stress <ul> <li>Fill block with minimal 4,500-gas tx and 6,000-gas ETH transfers; confirm gas vs byte-size binding per <a href="https://wg-eips.ritovision.com/7934/">EIP-7934</a>.</li> </ul> </li> <li>SELFDESTRUCT test: Create-and-destroy in one tx; confirm normal value-transfer costs apply, no deletion repricing.</li> </ol> <h2 id="security-considerations">Security Considerations</h2> <p>As this significantly increases the max tx per block this carries risk.</p> <p>However this pricing should be the same as performing the component changes inside the transaction; and it factors in the additional costs from state growth which were not originally in the transaction base price.</p> <p>Current gaslimit testing mostly uses a block with a single transaction; so this should not cause unexpected load compared to what is already being tested.</p> <p>The semantics of <code>SELFDESTRUCT</code> remain unchanged. Following <a href="https://wg-eips.ritovision.com/6780/">EIP-6780</a>, only contracts created within the same transaction may be fully deleted. This EIP does not reprice or modify any <code>SELFDESTRUCT</code> side-effects.</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-07-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ronan Sandfordhttps://github.com/wighawag Liraz Sirihttps://github.com/lirazsiri Dror Tiroshhttps://github.com/drortirosh Yoav Weisshttps://github.com/yoavw Alex Forshtathttps://github.com/forshtat Hadrien Crouboishttps://github.com/Amxx Sachin Tomarhttps://github.com/tomarsachin2271 Patrick McCorryhttps://github.com/stonecoldpat Nicolas Venturohttps://github.com/nventuro Fabian Vogelstellerhttps://github.com/frozeman Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/2771/

A contract interface for receiving meta transactions through a trusted forwarder

<h2 id="abstract">Abstract</h2> <p>This EIP defines a contract-level protocol for <code>Recipient</code> contracts to accept meta-transactions through trusted <code>Forwarder</code> contracts. No protocol changes are made. <code>Recipient</code> contracts are sent the effective <code>msg.sender</code> (referred to as <code>_msgSender()</code>) and <code>msg.data</code> (referred to as <code>_msgData()</code>) by appending additional calldata.</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. Solutions that allow for third parties to pay for gas costs are called meta transactions. For the purposes of this EIP, meta transactions are transactions that have been authorized by a <strong>Transaction Signer</strong> and relayed by an untrusted third party that pays for the gas (the <strong>Gas Relay</strong>).</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="definitions">Definitions</h3> <p><strong>Transaction Signer</strong>: Signs &amp; sends transactions to a Gas Relay</p> <p><strong>Gas Relay</strong>: Receives signed requests off-chain from Transaction Signers and pays gas to turn it into a valid transaction that goes through a Trusted Forwarder</p> <p><strong>Trusted Forwarder</strong>: A contract trusted by the <code>Recipient</code> to correctly verify signatures and nonces before forwarding the request from Transaction Signers</p> <p><strong>Recipient</strong>: A contract that accepts meta-transactions through a Trusted Forwarder</p> <h3 id="example-flow">Example Flow</h3> <p><img src="https://wg-eips.ritovision.com/2771/./assets/example-flow.png" alt="Example flow" /></p> <h3 id="extracting-the-transaction-signer-address">Extracting The Transaction Signer address</h3> <p>The <strong>Trusted Forwarder</strong> is responsible for calling the <strong>Recipient</strong> contract and MUST append the address of the <strong>Transaction Signer</strong> (20 bytes of data) to the end of the call data.</p> <p>For example :</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>(</span><span class="z-support">bool</span><span> success</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> returnData</span><span>)</span><span class="z-keyword"> =</span><span> to</span><span>.</span><span>call</span><span>.</span><span class="z-entity z-name">value</span><span>(</span><span>value</span><span>)</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>data</span><span>,</span><span> from</span><span>)</span><span>)</span><span>;</span></span></code></pre> <p>The <strong>Recipient</strong> contract can then extract the <strong>Transaction Signer</strong> address by performing 3 operations:</p> <ol> <li>Check that the <strong>Forwarder</strong> is trusted. How this is implemented is out of the scope of this proposal.</li> <li>Extract the <strong>Transaction Signer</strong> address from the last 20 bytes of the call data and use that as the original <code>sender</code> of the transaction (instead of <code>msg.sender</code>)</li> <li>If the <code>msg.sender</code> is not a trusted forwarder (or if the <code>msg.data</code> is shorter than 20 bytes), then return the original <code>msg.sender</code> as it is.</li> </ol> <p>The <strong>Recipient</strong> MUST check that it trusts the Forwarder to prevent it from extracting address data appended from an untrusted contract. This could result in a forged address.</p> <h3 id="protocol-support-discovery-mechanism">Protocol Support Discovery Mechanism</h3> <p>Unless a <strong>Recipient</strong> contract is being used by a particular frontend that knows that this contract has support for native meta transactions, it would not be possible to offer the user the choice of using meta-transaction to interact with the contract. We thus need a mechanism by which the <strong>Recipient</strong> can let the world know that it supports meta transactions.</p> <p>This is especially important for meta transactions to be supported at the Web3 wallet level. Such wallets may not necessarily know anything about the <strong>Recipient</strong> contract users may wish to interact with.</p> <p>As a <strong>Recipient</strong> could trust forwarders with different interfaces and capabilities (e.g., transaction batching, different message signing formats), we need to allow wallets to discover which Forwarder is trusted.</p> <p>To provide this discovery mechanism a <strong>Recipient</strong> contract MUST implement 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"> isTrustedForwarder</span><span>(</span><span class="z-support">address</span><span class="z-variable"> forwarder</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> <p><code>isTrustedForwarder</code> MUST return <code>true</code> if the forwarder is trusted by the Recipient, otherwise it MUST return <code>false</code>. <code>isTrustedForwarder</code> MUST NOT revert.</p> <p>Internally, the <strong>Recipient</strong> MUST then accept a request from forwarder.</p> <p><code>isTrustedForwarder</code> function MAY be called on-chain, and as such gas restrictions MUST be put in place. It SHOULD NOT consume more than 50,000 gas</p> <h2 id="rationale">Rationale</h2> <ul> <li>Make it easy for contract developers to add support for meta transactions by standardizing the simplest viable contract interface.</li> <li>Without support for meta transactions in the recipient contract, an externally owned account can not use meta transactions to interact with the recipient contract.</li> <li>Without a standard contract interface, there is no standard way for a client to discover whether a recipient supports meta transactions.</li> <li>Without a standard contract interface, there is no standard way to send a meta transaction to a recipient.</li> <li>Without the ability to leverage a trusted forwarder every recipient contract has to internally implement the logic required to accept meta transactions securely.</li> <li>Without a discovery protocol, there is no mechanism for a client to discover whether a recipient supports a specific forwarder.</li> <li>Making the contract interface agnostic to the internal implementation details of the trusted forwarder, makes it possible for a recipient contract to support multiple forwarders with no change to code.</li> <li><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 securing <code>msg.sender</code> is insufficient. <ul> <li>The problem is that for a contract that is not natively aware of meta transactions, the <code>msg.sender</code> of the transaction will make it appear to be coming from the <strong>Gas Relay</strong> and not the <strong>Transaction Signer</strong>. A secure protocol for a contract to accept meta transactions needs to prevent the <strong>Gas Relay</strong> from forging, modifying or duplicating requests by the <strong>Transaction Signer</strong>.</li> </ul> </li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="recipient-example">Recipient Example</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"> RecipientExample</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"> purchaseItem</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> sender </span><span class="z-keyword">=</span><span class="z-entity z-name"> _msgSender</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ... perform the purchase for sender</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> immutable</span><span> _trustedForwarder</span><span>;</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"> trustedForwarder</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span> _trustedForwarder </span><span class="z-keyword">=</span><span> trustedForwarder</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"> isTrustedForwarder</span><span>(</span><span class="z-support">address</span><span class="z-variable"> forwarder</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"> return</span><span> forwarder </span><span class="z-keyword">==</span><span> _trustedForwarder</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"> _msgSender</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"> payable</span><span class="z-variable"> signer</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> signer </span><span class="z-keyword">=</span><span class="z-variable z-language"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-language">msg</span><span>.</span><span>data</span><span>.</span><span>length</span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-constant">20</span><span class="z-keyword"> &amp;&amp;</span><span class="z-entity z-name"> isTrustedForwarder</span><span>(</span><span>signer</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> signer </span><span class="z-keyword">:=</span><span class="z-entity z-name"> shr</span><span>(</span><span class="z-constant">96</span><span>,</span><span class="z-entity z-name">calldataload</span><span>(</span><span class="z-entity z-name">sub</span><span>(</span><span class="z-entity z-name">calldatasize</span><span>(</span><span>)</span><span>,</span><span class="z-constant">20</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 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>A malicious forwarder may forge the value of <code>_msgSender()</code> and effectively send transactions from any address. Therefore, <code>Recipient</code> contracts must be very careful in trusting forwarders. If a forwarder is upgradeable, then one must also trust that the contract won't perform a malicious upgrade.</p> <p>In addition, modifying which forwarders are trusted must be restricted, since an attacker could "trust" their own address to forward transactions, and therefore be able to forge transactions. It is recommended to have the list of trusted forwarders be immutable, and if this is not feasible, then only trusted contract owners should be able to modify 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> 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-06-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Matt Garnetthttps://github.com/lightclient https://wg-eips.ritovision.com/2733/ <h2 id="simple-summary">Simple Summary</h2> <p>Creates a new transaction type which executes a package of one or more transactions, while passing status information to subsequent transactions.</p> <h2 id="abstract">Abstract</h2> <p>Introduce a new transaction type which includes a list of transactions that must be executed serially by clients. Execution information (e.g. success, gas_used, etc.) will be propagated forward to the next transaction.</p> <h2 id="motivation">Motivation</h2> <p>Onboarding new users to Ethereum has been notoriously difficult due to the need for new users to acquire enough ether to pay for their transactions. This hurdle has seen a significant allocation of resources over the years to solve. Today, that solution is meta-transactions. This is, unfortunately, a brittle solution that requires signatures to be recovered within a smart contract to authenticate the message. This EIP aims to provide a flexible framework for relayers to "sponsor" many transactions at once, trustlessly.</p> <p>Meta-transactions often use relay contracts to maintain nonces and allow users to pay for gas using alternative assets. They have historically been designed to catch reversions in their inner transactions by only passing a portion of the available gas to the subcall. This allows them to be certain the outer call will have enough gas to complete any required account, like processing a gas payment. This type of subcall has been considered bad practice for a long time, but in the case of where you don't trust the subcalls, it is the only available solution.</p> <p>Transaction packages are an alternative that allow multiple transactions to be bundled into one package and executed atomically, similarly to how relay contracts operate. Transactions are able to pass their result to subsequent transactions. This allows for conditional workflows based on the outcome of previous transactions. Although this functionality is already possible as described above, workflows using transaction packages are more robust, because they are protected from future changes to the gas schedule.</p> <p>An important byproduct of this EIP is that it also facilitates bundling transactions for single users.</p> <h2 id="specification">Specification</h2> <p>Introduce a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction type where <code>id = 2</code>.</p> <h4 id="structure">Structure</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>struct TransactionPackage {</span></span> <span class="giallo-l"><span> chain_id: u256,</span></span> <span class="giallo-l"><span> children: [ChildPackage],</span></span> <span class="giallo-l"><span> nonce: u64,</span></span> <span class="giallo-l"><span> gas_price: u256,</span></span> <span class="giallo-l"><span> v: u256,</span></span> <span class="giallo-l"><span> r: u256,</span></span> <span class="giallo-l"><span> s: u256</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="hash">Hash</h5> <p><code>keccak256(rlp([2, chain_id, children, nonce, gas_price, v, r, s])</code></p> <h5 id="signature-hash">Signature Hash</h5> <p><code>keccak256(rlp([2, chain_id, children, nonce, gas_price])</code></p> <h5 id="receipt">Receipt</h5> <p>Each <code>ChildTransaction</code> transaction will generate a <code>ChildReceipt</code> after execution. Each of these receipts will be aggregated into a <code>Receipt</code>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>type Receipt = [ChildReceipt]</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>struct ChildReceipt {</span></span> <span class="giallo-l"><span> status: u256,</span></span> <span class="giallo-l"><span> cumulative_gas_used: u256,</span></span> <span class="giallo-l"><span> logs_bloom: [u8; 256],</span></span> <span class="giallo-l"><span> logs: [u8]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="child-transaction">Child Transaction</h4> <p>Let <code>ChildPackage</code> be interpreted as follows.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>struct ChildPackage {</span></span> <span class="giallo-l"><span> type: u8,</span></span> <span class="giallo-l"><span> nonce: u64,</span></span> <span class="giallo-l"><span> transactions: [ChildTransaction],</span></span> <span class="giallo-l"><span> max_gas_price: u256,</span></span> <span class="giallo-l"><span> v: u256,</span></span> <span class="giallo-l"><span> r: u256,</span></span> <span class="giallo-l"><span> s: u256</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>struct ChildTransaction {</span></span> <span class="giallo-l"><span> flags: u8,</span></span> <span class="giallo-l"><span> to: Address,</span></span> <span class="giallo-l"><span> value: u256,</span></span> <span class="giallo-l"><span> data: [u8],</span></span> <span class="giallo-l"><span> extra: [u8],</span></span> <span class="giallo-l"><span> gas_limit: u256</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="types">Types</h5> <p>The <code>type</code> field is used to denote whether the <code>Child</code> signer wishes to delegate the <code>max_gas_price</code> and <code>gas_limit</code> choice to the <code>TransactionPackage</code> signer.</p> <table><thead><tr><th>type</th><th>signature hash</th></tr></thead><tbody> <tr><td><code>0x00</code></td><td><code>keccak256(rlp([0, nonce, transactions, max_gas_price])</code></td></tr> <tr><td><code>0x01</code></td><td><code>keccak256(rlp([1, nonce, transactions_without_gas_limit])</code></td></tr> </tbody></table> <h3 id="validity">Validity</h3> <p>A <code>TransactionPackage</code> can be deemed valid or invalid as follows.</p> <pre class="giallo z-code"><code data-lang="rust"><span class="giallo-l"><span class="z-keyword">fn</span><span class="z-entity z-name"> is_valid</span><span>(</span><span class="z-variable z-other">config</span><span class="z-keyword">:</span><span class="z-keyword"> &amp;</span><span class="z-entity z-name">Config</span><span>,</span><span class="z-variable z-other"> state</span><span class="z-keyword">:</span><span class="z-keyword"> &amp;</span><span class="z-entity z-name">State</span><span>,</span><span class="z-variable z-other"> tx</span><span class="z-keyword">:</span><span class="z-entity z-name"> TransactionPackage</span><span>)</span><span class="z-entity z-name"> bool</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span></span> <span class="giallo-l"><span class="z-variable z-other"> config</span><span class="z-keyword">.</span><span class="z-entity z-name">chain_id</span><span>(</span><span>)</span><span class="z-keyword"> !=</span><span class="z-variable z-other"> tx</span><span class="z-keyword">.</span><span>chain_id </span><span class="z-keyword">|</span><span class="z-keyword">|</span></span> <span class="giallo-l"><span class="z-variable z-other"> tx</span><span class="z-keyword">.</span><span>children</span><span class="z-keyword">.</span><span class="z-entity z-name">len</span><span>(</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span class="z-keyword"> |</span><span class="z-keyword">|</span></span> <span class="giallo-l"><span class="z-variable z-other"> state</span><span class="z-keyword">.</span><span class="z-entity z-name">nonce</span><span>(</span><span class="z-variable z-other">tx</span><span class="z-keyword">.</span><span class="z-entity z-name">from</span><span>(</span><span>)</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"> tx</span><span class="z-keyword">.</span><span>nonce</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></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> cum_limit</span><span class="z-keyword"> =</span><span class="z-variable z-other"> tx</span><span class="z-keyword">.</span><span>children</span><span class="z-keyword">.</span><span class="z-entity z-name">map</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"> x</span><span class="z-keyword">.</span><span>gas_limit</span><span>)</span><span class="z-keyword">.</span><span class="z-entity z-name">sum</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-variable z-other"> state</span><span class="z-keyword">.</span><span class="z-entity z-name">balance</span><span>(</span><span class="z-variable z-other">tx</span><span class="z-keyword">.</span><span class="z-entity z-name">from</span><span>(</span><span>)</span><span>)</span><span> &lt;</span><span class="z-variable z-other"> cum_limit</span><span class="z-keyword"> *</span><span class="z-variable z-other"> tx</span><span class="z-keyword">.</span><span>gas_price </span><span class="z-keyword">+</span><span class="z-entity z-name"> intrinsic_gas</span><span>(</span><span class="z-variable z-other">tx</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> </span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span class="z-variable z-other"> child</span><span class="z-keyword"> in</span><span class="z-variable z-other"> tx</span><span class="z-keyword">.</span><span>children </span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span></span> <span class="giallo-l"><span class="z-variable z-other"> child</span><span class="z-keyword">.</span><span>nonce </span><span class="z-keyword">!=</span><span class="z-variable z-other"> state</span><span class="z-keyword">.</span><span class="z-entity z-name">nonce</span><span>(</span><span class="z-variable z-other">child</span><span class="z-keyword">.</span><span class="z-entity z-name">from</span><span>(</span><span>)</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> <span class="giallo-l"><span class="z-variable z-other"> child</span><span class="z-keyword">.</span><span>value</span><span class="z-keyword"> &gt;</span><span class="z-variable z-other"> state</span><span class="z-keyword">.</span><span class="z-entity z-name">balance</span><span>(</span><span class="z-variable z-other">child</span><span class="z-keyword">.</span><span class="z-entity z-name">from</span><span>(</span><span>)</span><span>)</span><span class="z-keyword"> |</span><span class="z-keyword">|</span></span> <span class="giallo-l"><span class="z-variable z-other"> child</span><span class="z-keyword">.</span><span>max_gas_price</span><span class="z-keyword"> &lt;</span><span class="z-variable z-other"> tx</span><span class="z-keyword">.</span><span>gas_price</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></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span class="z-variable z-other"> tx</span><span class="z-keyword"> in</span><span class="z-variable z-other"> child</span><span class="z-keyword">.</span><span>txs </span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span></span> <span class="giallo-l"><span class="z-variable z-other"> tx</span><span class="z-keyword">.</span><span>flags </span><span class="z-keyword">!=</span><span class="z-constant"> 0</span><span class="z-keyword"> |</span><span class="z-keyword">|</span></span> <span class="giallo-l"><span class="z-variable z-other"> tx</span><span class="z-keyword">.</span><span>extra</span><span class="z-keyword">.</span><span class="z-entity z-name">len</span><span>(</span><span>)</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span class="z-keyword"> |</span><span class="z-keyword">|</span></span> <span class="giallo-l"><span class="z-variable z-other"> tx</span><span class="z-keyword">.</span><span>gas_limit</span><span class="z-keyword"> &lt;</span><span class="z-entity z-name"> intrinsic_gas</span><span>(</span><span class="z-variable z-other">tx</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></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 class="z-constant"> true</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="results">Results</h3> <p>Subsequent <code>ChildTransaction</code>s will be able to receive the result of the previous <code>ChildTransaction</code> via <code>RETURNDATACOPY (0x3E)</code> in first frame of execution, before making any subcalls. Each element, except the last, will be <code>0</code>-padded left to 32 bytes.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>struct Result {</span></span> <span class="giallo-l"><span> // Status of the previous transaction</span></span> <span class="giallo-l"><span> success: bool,</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> // Total gas used by the previous transaction</span></span> <span class="giallo-l"><span> gas_used: u256,</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> // Cumulative gas used by previous transactions</span></span> <span class="giallo-l"><span> cum_gas_used: u256,</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> // The size of the return value</span></span> <span class="giallo-l"><span> return_size: u256,</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> // The return value of the previous transaction</span></span> <span class="giallo-l"><span> return_value: [u8]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="intrinsic-cost">Intrinsic Cost</h3> <p>Let the intrinsic cost of the transaction package be defined as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>fn intrinsic_gas(tx: TransactionPackage) u256 {</span></span> <span class="giallo-l"><span> let data_gas = tx.children.map(|c| c.txs.map(|t| data_cost(&amp;c.data)).sum()).sum();</span></span> <span class="giallo-l"><span> 17000 + 8000 * tx.children.len() + data_gas</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="execution">Execution</h3> <p>Transaction packages should be executed as follows:</p> <ol> <li>Deduct the cumulative cost from the outer signer's balance.</li> <li>Load the first child package, and execute the first child transaction.</li> <li>Record all state changes, logs, the receipt, and refund any unused gas.</li> <li>If there are no more child transactions, goto <code>8</code>.</li> <li>Compute <code>Result</code> for the previously executed transaction.</li> <li>Prepare <code>Result</code> to be available via return opcodes in the next transaction's first frame.</li> <li>Execute the next transaction, then goto <code>3</code>.</li> <li>Load the next child package, then goto <code>7</code>.</li> </ol> <h2 id="rationale">Rationale</h2> <h3 id="each-child-has-its-own-signature">Each <code>Child</code> has its own signature</h3> <p>For simplicity, the author has chosen to require each child package to specify its own signature, even if the signer is the same as the package signer. This choice is made to allow for maximum flexibility, with minimal client changes. This transaction can still be used by a single user at the cost of only one additional signature recovery.</p> <h3 id="childpackage-specifies-max-gas-price-instead-of-gas-price"><code>ChildPackage</code> specifies <code>max_gas_price</code> instead of <code>gas_price</code></h3> <p>Allowing child packages to specify a range of acceptable gas prices is strictly more versatile than a static price. It gives relayers more flexibility in terms of building transaction bundles, and it makes it possible for relayers to try and achieve the best price for the transaction sender. With a fixed price, the relayer may require the user to sign multiple different transactions, with varying prices. This can be avoided by specifying a max price, and communicating out-of-band how the urgency of the transaction (e.g. the relayer should package it with the max price immediately vs. slowly increasing the gas price). A future transaction type can be specified with only a single signature, if such an optimization is desired.</p> <h3 id="childpackage-is-also-typed"><code>ChildPackage</code> is also typed</h3> <p>The type element serves a modest role in the transaction type, denoting whether the transaction signer wishes to delegate control of the gas price and gas limit to the outer signer. This is a useful UX improvement when interacting with a trusted relayer, as once the user decides to make a transaction the relayer can ensure it is included on chain by choosing the best gas price and limit.</p> <h3 id="the-flags-and-extra-fields-aren-t-used">The <code>flags</code> and <code>extra</code> fields aren't used</h3> <p>These fields are included to better support future changes to the transaction type. This would likely be used in conjunction with the <code>flags</code> and <code>type</code> fields. A benefit of explicitly defining them is that specialized serialization of RLP can be avoided, simplifying clients and downstream infrastructure. The author believe the cost of 2 bytes per transaction is acceptable for smoother integration of future features.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Contracts which rely on <code>ORIGIN (0x32) == CALLER (0x33) &amp;&amp; RETURNDATASIZE (0x3D) == 0x00</code> will now always fail in transaction packages, unless they are the first executed transaction. It’s unknown if any contracts conduct this check.</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> <h3 id="managing-packages-efficiently-in-the-mempool">Managing packages efficiently in the mempool</h3> <p>The introduction of a new transaction type brings along new concerns regarding the mempool. Done naively, it could turn into a DDoS vector for clients. This EIP has been written to reduce as much validation complexity as possible.</p> <p>An existing invariant in the mempool that is desirable for new transactions to maintain, is that transactions can be validated in constant time. This is also possible for packaged transactions. There is an inherent 10Mb limit for RLPx frames, so that would be the upper bound on transactions that could be included in a package. On the other hand, clients can also just configure their own bound locally (e.g. packages must be less than 1Mb). Validity can then be determined by using the function above.</p> <p>Once a package has been validated, it must continuously be monitored for nonce invalidations within its package. One potential way to achieve this efficiently is to modify the mempool to operate on thin pointers to the underlying transaction. This will allow packages to ingest as many "single" transactions, simplifying the facilities for monitoring changes. These "parts" of the package can maintain a pointer to a structure with pointers to all the parts of the package. This way, as soon as one part becomes invalid, it can request the parent to invalidate all outstanding parts of the package.</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-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Micah Zoltuhttps://github.com/MicahZoltu https://wg-eips.ritovision.com/2718/

Defines a new transaction type that is an envelope for future transaction types.

<h2 id="abstract">Abstract</h2> <p><code>TransactionType || TransactionPayload</code> is a valid transaction and <code>TransactionType || ReceiptPayload</code> is a valid transaction receipt where <code>TransactionType</code> identifies the format of the transaction and <code>*Payload</code> is the transaction/receipt contents, which are defined in future EIPs.</p> <h2 id="motivation">Motivation</h2> <p>In the past, when we have wanted to add new transaction types we have had to ensure they were backward compatible with all other transactions, meaning that you could differentiate them based only on the encoded payload, and it was not possible to have a transaction that matched both types. This was seen in <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> where the new value was bit-packed into one of the encoded fields. There are multiple proposals in discussion that define new transaction types such as one that allows EOA accounts to execute code directly within their context, one that enables someone besides <code>msg.sender</code> to pay for gas, and proposals related to layer 1 multi-sig transactions. These all need to be defined in a way that is mutually compatible, which quickly becomes burdensome to EIP authors and to clients who now have to follow complex rules for differentiating transaction type.</p> <p>By introducing an envelope transaction type, we only need to ensure backward compatibility with existing transactions and from then on we just need to solve the much simpler problem of ensuring there is no numbering conflict between <code>TransactionType</code>s.</p> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions</h3> <ul> <li><code>||</code> is the byte/byte-array concatenation operator.</li> </ul> <h3 id="transactions">Transactions</h3> <p>As of <code>FORK_BLOCK_NUMBER</code>, the transaction root in the block header <strong>MUST</strong> be the root hash of <code>patriciaTrie(rlp(Index) =&gt; Transaction)</code> where:</p> <ul> <li><code>Index</code> is the index in the block of this transaction</li> <li><code>Transaction</code> is either <code>TransactionType || TransactionPayload</code> or <code>LegacyTransaction</code></li> <li><code>TransactionType</code> is a positive unsigned 8-bit number between <code>0</code> and <code>0x7f</code> that represents the type of the transaction</li> <li><code>TransactionPayload</code> is an opaque byte array whose interpretation is dependent on the <code>TransactionType</code> and defined in future EIPs</li> <li><code>LegacyTransaction</code> is <code>rlp([nonce, gasPrice, gasLimit, to, value, data, v, r, s])</code></li> </ul> <p>All signatures for future transaction types <strong>SHOULD</strong> include the <code>TransactionType</code> as the first byte of the signed data. This makes it so we do not have to worry about signatures for one transaction type being used as signatures for a different transaction type.</p> <h3 id="receipts">Receipts</h3> <p>As of <code>FORK_BLOCK_NUMBER</code>, the receipt root in the block header <strong>MUST</strong> be the root hash of <code>patriciaTrie(rlp(Index) =&gt; Receipt)</code> where:</p> <ul> <li><code>Index</code> is the index in the block of the transaction this receipt is for</li> <li><code>Receipt</code> is either <code>TransactionType || ReceiptPayload</code> or <code>LegacyReceipt</code></li> <li><code>TransactionType</code> is a positive unsigned 8-bit number between <code>0</code> and <code>0x7f</code> that represents the type of the transaction</li> <li><code>ReceiptPayload</code> is an opaque byte array whose interpretation is dependent on the <code>TransactionType</code> and defined in future EIPs</li> <li><code>LegacyReceipt</code> is <code>rlp([status, cumulativeGasUsed, logsBloom, logs])</code></li> </ul> <p>The <code>TransactionType</code> of the receipt <strong>MUST</strong> match the <code>TransactionType</code> of the transaction with a matching <code>Index</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="transactiontype-only-goes-up-to-0x7f">TransactionType only goes up to 0x7f</h3> <p>For the forseable future, 0x7f is plenty and it leaves open a number of options for extending the range such as using the high bit as a continuation bit. This also prevents us from colliding with legacy transaction types, which always start with a byte <code>&gt;= 0xc0</code>.</p> <h3 id="should-instead-of-must-for-the-transactiontype-being-first-byte-of-signed-data"><strong>SHOULD</strong> instead of <strong>MUST</strong> for the TransactionType being first byte of signed data</h3> <p>While it is strongly recommended that all future transactions sign the first byte to ensure that there is no problem with signature reuse, the authors acknowledge that this may not always make sense or be possible. One example where this isn't possible is wrapped legacy transactions that are signature compatible with the legacy signing scheme. Another potential situation is one where transactions don't have a signature in the traditional sense and instead have some other mechanism for determining validity.</p> <h3 id="transactiontype-selection-algorithm">TransactionType selection algorithm</h3> <p>There was discussion about defining the <code>TransactionType</code> identifier assignment/selection algorithm in this standard. While it would be nice to have a standardized mechanism for assignment, at the time of writing of this standard there is not a strong need for it so it was deemed out of scope. A future EIP may introduce a standard for TransactionType identifier assignment if it is deemed necessary.</p> <h3 id="opaque-byte-array-rather-than-an-rlp-array">Opaque byte array rather than an RLP array</h3> <p>By having the second byte on be opaque bytes, rather than an RLP (or other encoding) list, we can support different encoding formats for the transaction payload in the future such as SSZ, LEB128, or a fixed width format.</p> <h3 id="origin-and-caller">ORIGIN and CALLER</h3> <p>There was discussion about having ORIGIN and CALLER opcodes become dependent on the transaction type, so that each transaction type could define what those opcodes returned. However, there is a desire to make transaction type opaque to the contracts to discourage contracts treating different types of transactions differently. There also were concerns over backward compatibility with existing contracts which make assumptions about ORIGIN and CALLER opcodes. Going forward, we will assume that all transaction types will have an address that reasonably represents a <code>CALLER</code> of the first EVM frame and <code>ORIGIN</code> will be the same address in all cases. If a transaction type needs to supply additional information to contracts, they will need a new opcode.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Clients can differentiate between the legacy transactions and typed transactions by looking at the first byte. If it starts with a value in the range <code>[0, 0x7f]</code> then it is a new transaction type, if it starts with a value in the range <code>[0xc0, 0xfe]</code> then it is a legacy transaction type. <code>0xff</code> is not realistic for an RLP encoded transaction, so it is reserved for future use as an extension sentinel value.</p> <h2 id="security-considerations">Security Considerations</h2> <p>When designing a new 2718 transaction type, it is <strong>STRONGLY</strong> recommended to include the transaction type as the first byte of the signed payload. If you fail to do this, it is possible that your transaction may be signature compatible with transactions of another type which can introduce security vulnerabilities for 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> 2020-06-11T00:00:00+00:00 2026-02-11T14:49:27+00:00 Micah Zoltuhttps://github.com/MicahZoltu https://wg-eips.ritovision.com/2711/ <h2 id="simple-summary">Simple Summary</h2> <p>Creates a new transaction type that supports sponsored transactions (separate gas payer from sender), batch transactions (multiple transactions executed in sequence), and expiring transactions (transactions which are not valid after a certain timestamp).</p> <h2 id="abstract">Abstract</h2> <p>An EIP-2718 transaction with the type number <code>2</code> is a new type of transaction that includes support for:</p> <ol> <li><strong>Sponsored Transactions</strong>: an optional additional signature from which the account that will pay for gas (<code>GAS_PAYER</code>) can be recovered</li> <li><strong>Batch Transactions</strong>: multiple transactions from the same sender that will be executed in sequence</li> <li><strong>Expiring Transactions</strong>: an optional <code>validUntil</code> field that makes the transaction invalid after a certain point in time</li> </ol> <h2 id="motivation">Motivation</h2> <h3 id="sponsored-transactions">Sponsored Transactions</h3> <p>With the advent of tokens and especially stable coins, it has become common for users to not hold ETH in an account while they may have other assets of value in that account. Some users don't want to be exposed to the perceived volatility of ETH and instead would prefer to transact using other assets. Unfortunately, since gas <strong>MUST</strong> be paid for with ETH, this prevents the user from transacting with their assets without first acquiring some ETH using some other means, and then using that ETH to pay fees.</p> <p>This EIP proposes a mechanism by which we can allow people to transact without ever having to own any ETH by allowing someone else to cover gas costs. The arrangements that enable the covering of gas costs is out of scope for this EIP but it could be an extra-protocol monthly subscription, payment could occur as part of the transaction being submitted, the recipient may be willing to cover gas costs, or it could be a free service offered as a value-add by a company that you are working with.</p> <p>While it is possible to implement these sort of mechanisms at the individual contract layer, such solutions require integration by just about every contract and those solutions also end up depending on gas costs being stable with time in order to appropriately bake them into contracts without putting either party at risk of malicious participants in the system. For this reason, it is believed that separating out <code>GAS_PAYER</code> from <code>msg.sender</code> at the protocol layer is valuable.</p> <h3 id="batch-transactions">Batch Transactions</h3> <p>Often times an EOA may want to execute a series of transactions with a strong guarantee that they happen in order with nothing occurring between them. For example, one may want to send some tokens to a contract and then follow that up with another transaction that makes a contract call on the destination address that causes those tokens to be registered to them. By supporting transaction batching at layer 1, we can ensure that the user can get strong guarantees at signing time of cross-transaction atomicity.</p> <h3 id="expiring-transactions">Expiring Transactions</h3> <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> <h3 id="definitions">Definitions</h3> <p><strong><code>TransactionType</code></strong> 2. See <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a></p> <p><strong><code>TransactionSubtype</code></strong> is either 1, 2, 3, or 4.</p> <p><strong><code>ChainId</code></strong> The transaction is valid if this value is <code>0</code> or it is included in a block on a chain whose ID is equal to this value.</p> <p><strong><code>ValidUntil</code></strong> The transaction is valid if this value is <code>0</code> or it is included in a block whose <code>timestamp</code> is less than or equal to this value.</p> <p><strong><code>YParity</code></strong> The parity (0 for even, 1 for odd) of the y-value of a secp256k1 signature.</p> <p><strong><code>ChildTransaction</code></strong> A nested transaction consisting of <code>[to, value, data]</code>.</p> <p><strong><code>SenderPayload</code></strong> Defined based on the <code>TransactionSubtype</code> as follows:</p> <ol> <li><code>[1, ChildTransaction[], nonce, ChainId, ValidUntil, gasLimit, gasPrice]</code></li> <li><code>[2, ChildTransaction[], nonce, ChainId, ValidUntil, gasLimit, gasPrice]</code></li> <li><code>[3, ChildTransaction[], nonce, ChainId, ValidUntil, gasLimit]</code></li> <li><code>[4, ChildTransaction[], nonce, ChainId, ValidUntil]</code></li> </ol> <p><strong><code>SenderSignature</code></strong> <code>[YParity, r, s]</code> of <code>secp256k1(keccak256(rlp([TransactionType, SenderPayload])))</code></p> <p><strong><code>GasPayerPayload</code></strong> Defined based on the <code>TransactionSubtype</code> as follows:</p> <ol> <li><code>[]</code></li> <li><code>[]</code></li> <li><code>[gasPrice]</code></li> <li><code>[gasLimit, gasPrice]</code></li> </ol> <p><strong><code>GasPayerSignature</code></strong> is <code>[]</code> for <code>TransactionSubType</code> <code>1</code> or <code>[YParity, r, s]</code> of <code>secp256k1(keccak256(rlp([SenderPayload, SenderSignature, GasPayerPayload])))</code> for others.</p> <h3 id="new-transaction-type">New Transaction Type</h3> <p>As of <code>FORK_BLOCK_NUMBER</code> an <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction with a <code>TransactionType</code> of <code>2</code> will have its <code>Payload</code> interpreted as an RLP encoded tuple of:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[...SenderPayload, ...SenderSignature, ...GasPayerPayload, ...GasPayerSignature]</span></span></code></pre> <p>The address recovered from <code>SenderSignature</code> is the address...</p> <ol> <li>...returned by the <code>CALLER</code> opcode (0x33, aka <code>msg.sender</code>) during the first call frame of the transaction</li> <li>...returned by the <code>ORIGIN</code> opcode (0x32, aka <code>tx.origin</code>)</li> <li>...whose <code>nonce</code> is used</li> <li>...whose ETH balance is deducted if any value is attached to the transaction</li> <li>...whose ETH balance is deducted to pay for gas if <code>GasPayerSignature</code> is not present</li> </ol> <p>If <code>GasPayerSignature</code> is present, then the address recovered from it is the address...</p> <ol> <li>...whose ETH balance is deducted to pay for gas</li> </ol> <p>The base gas cost of transactions of this type will be <code>TRANSACTION_TYPE_2_BASE_GAS_PRICE</code> + <code>TRANSACTION_TYPE_2_CHILD_GAS_PRICE</code> * <code>n</code>, rather than the cost associated with transactions of type <code>0</code> and legacy transactions.</p> <h3 id="new-transaction-receipt">New Transaction Receipt</h3> <p>As of <code>FORK_BLOCK_NUMBER</code> an <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction receipt with a <code>TransactionType</code> of <code>2</code> will have its <code>Payload</code> interpreted as a <code>rlp([status, cumulativeGasUsed, logsBloom, logs][])</code> where each item of the array corresponds to the child-transaction at matching offset in the transaction type 2 <code>Payload</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="one-monolithic-eip">One Monolithic EIP</h3> <p>This EIP could be split up into multiple EIPs, one for each of the subtypes and one for the meta-type. Alternatively, each of the subtypes could be a unique TransactionType. The reason we chose to go with a single EIP with subtypes is because these 4 transactions all have a <em>lot</em> in common and each separate EIP would be almost identical to the previous. We felt that in this case, splitting into multiple EIPs wasn't worth the duplication of EIP content.</p> <h3 id="chainid-not-encoded-with-v">ChainID not encoded with <code>v</code></h3> <p>While we could save one byte in the common case by bundling the y-parity bit of the signature with the Chain ID like in EIP-155, this adds complexity to signing tools that the authors deem not worth it given the size of the transaction overall.</p> <h3 id="optionality-of-chainid">Optionality of ChainID</h3> <p>Sometimes it is useful to have a transaction that <em>can</em> be replayed on multiple chains. An example of this is when you construct a vanity signature for a transaction and have the <code>from</code> be whatever address that signature recovers to. With the ability to have someone else be a gas payer (setting both the gas limit and the gas price), one can have transactions that deploy contracts which live at the same address on every chain. While this can be accomplished with CREATE2 using legacy transactions, we have the opportunity here to simplify the process and enable potentially other future uses of deterministic transactions by making ChainID optional.</p> <h3 id="optionality-of-validuntil">Optionality of ValidUntil</h3> <p>A user can set <code>ValidUntil</code> to a very large number which effectively makes it non-expiring. By making <code>ValidUntil</code> optional, we can save some bytes on the wire by allowing such transactions to simply have a <code>0</code> (1 byte in RLP) value for this field.</p> <h3 id="sender-sets-gaslimit-and-gasprice"><code>SENDER</code> sets <code>gasLimit</code> and <code>gasPrice</code></h3> <p>This type of transaction is useful when the transaction may execute differently depending on what these values are set to. By having the <code>SENDER</code> set both, we ensure that the <code>SENDER</code> has full control over the transaction details.</p> <h3 id="sender-sets-gaslimit-gas-payer-sets-gasprice"><code>SENDER</code> sets <code>gasLimit</code>, <code>GAS_PAYER</code> sets <code>gasPrice</code></h3> <p>This type of transaction is useful when the transaction may execute differently depending on how much gas it is allowed (e.g., number of loops) but where the <code>SENDER</code> would like to give the <code>GAS_PAYER</code> the ability to price the transaction to maximize chances of inclusion.</p> <h3 id="gas-payer-sets-gaslimit-and-gasprice"><code>GAS_PAYER</code> sets <code>gasLimit</code> and <code>gasPrice</code></h3> <p>This type of transaction allows the <code>SENDER</code> to define what they want to do, and leaves all worry about gas to the <code>GAS_PAYER</code>. This is useful for transactions where the sender doesn't care how much gas is used or the price that is paid and also either trusts the <code>GAS_PAYER</code> to be non-malicious or doesn't care if the <code>SENDER</code>'s nonce is increased. Such situations are useful when you have extra-protocol trust between the <code>SENDER</code> and <code>GAS_PAYER</code> and you want to separate concerns (what to do vs how to get included) for security or complexity reasons.</p> <h3 id="nonces">Nonces</h3> <p>The inner transaction needs a nonce to protect themselves from replay attacks. Since the inner transaction has a nonce, we get replay protection on the outer transaction as well, so it is not critical for security to have multiple parties provide a nonce.</p> <p>We could have the <code>GAS_PAYER</code> provide a second nonce, but this would increase the payload size and require <code>GAS_PAYER</code> to do replace-by-fee (noisy for gossip) if they want to slip in a new (different inner) transaction with a higher gas price. It would also create the possibility of a deadlock if the <code>SENDER</code> nonces aren't ordered the same as the <code>GAS_PAYER</code> nonces, and if the <code>SENDER</code> nonce isn't the lowest valid nonce for the <code>SENDER</code> then the <code>GAS_PAYER</code> can't sign and submit yet. Finally, client complexity increases slightly if a transaction has two nonces because you have to protect yourself from deadlocks and do more work to determine validity.</p> <h3 id="validuntil">ValidUntil</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="validuntil-as-timestamp-instead-of-block-number">ValidUntil as timestamp instead of block number</h3> <ul> <li>The unix 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 13s 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>unix time is more user-friendly, a user can more easily decide on reasonable end-date for a transaction, rather than a suitable number of valid blocks.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No known issues.</p> <h2 id="test-cases">Test Cases</h2> <h2 id="implementation">Implementation</h2> <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> 2020-06-05T00:00:00+00:00 2026-02-11T14:49:27+00:00 Micah Zoltuhttps://github.com/MicahZoltu Erik Markshttps://github.com/rekmarks https://wg-eips.ritovision.com/2700/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard mechanism for JavaScript Ethereum Providers to notify clients about chain state changes when both are able to interface with each other via a shared JavaScript object.</p> <h2 id="abstract">Abstract</h2> <p>This standard provides the description of an object that is made available to JavaScript applications which they can use to receive notifications from an Ethereum Provider. This standard only describes the notification mechanism, it does not specify the payloads that are valid nor does it specify how the client or the provider will discover or agree on payload content.</p> <p>How/where this Ethereum Provider object is exposed is left to future standards.</p> <h2 id="motivation">Motivation</h2> <p>When working within a JavaScript runtime (such as NodeJS, Electron, Browser, etc.) it may be possible for the runtime or a runtime plugin to inject objects into the runtime. Someone authoring a runtime or a runtime plugin may choose to expose an Ethereum Provider to any JavaScript apps or scripts running within that runtime in order to provide notifications of blockchain state changes. In order to achieve maximum compatibility between the provider and the client, a standard is necessary for what the shape of that object is.</p> <h2 id="specification">Specification</h2> <h3 id="rfc-2119">RFC-2119</h3> <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="interface">Interface</h3> <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"> EthereumProvider</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> on</span><span>(</span><span class="z-variable">eventName</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>,</span><span class="z-entity z-name"> listener</span><span class="z-keyword">:</span><span> (</span><span class="z-keyword">...</span><span class="z-variable">params</span><span class="z-keyword">:</span><span class="z-support"> unknown</span><span>[</span><span>]</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span class="z-support"> void</span><span>)</span><span class="z-keyword">:</span><span class="z-support"> void</span></span> <span class="giallo-l"><span class="z-entity z-name"> removeListener</span><span>(</span><span class="z-variable">eventName</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>,</span><span class="z-entity z-name"> listener</span><span class="z-keyword">:</span><span> (</span><span class="z-keyword">...</span><span class="z-variable">params</span><span class="z-keyword">:</span><span class="z-support"> unknown</span><span>[</span><span>]</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span class="z-support"> void</span><span>)</span><span class="z-keyword">:</span><span class="z-support"> void</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The specific events that can be listened to and the shape of their listener callback functions is left to be defined in separate standards.</p> <p>If <code>on</code> is called with an <code>eventName</code> that the provider is familiar with then the provider <strong>MUST</strong> call the provided <code>listener</code> when the named event occurs. If the same <code>listener</code> is added multiple times to the same event via <code>on</code>, the provider <strong>MAY</strong> choose to either callback the listener one time or one time per call to <code>on</code>.</p> <p>If <code>removeListener</code> is called with an <code>eventName</code> and <code>listener</code> that was previously added via <code>on</code> then the provider <strong>MUST</strong> decrease the number of times it calls the <code>listener</code> per event by one.</p> <h2 id="rationale">Rationale</h2> <p>This EIP is mostly a retrospective EIP meaning it codifies an already existing specification so there isn't a lot of room for improving things such as by using a discriminated union object for listener parameters or having a tighter definition of <code>on</code>. The specific events are intentionally left out of this specification as that set will be an ever-evolving collection and having the first few listed here doesn't add value to this specification (especially if, over time, the first few end up deprecated or unused).</p> <h2 id="security-considerations">Security Considerations</h2> <p>The relationship between Ethereum Provider and client is a trusted one, where it is assumed that the user implicitly trusts the Ethereum Provider which is how it managed to get injected into the client, or the client expressly pulled in a connection 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> 2020-06-04T00:00:00+00:00 2026-02-11T14:49:27+00:00 Micah Zoltuhttps://github.com/MicahZoltu Erik Markshttps://github.com/rekmarks https://wg-eips.ritovision.com/2696/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard for remote procedure calls between an Ethereum Provider and an Ethereum Client when both are able to interface with each other via a shared JavaScript object.</p> <h2 id="abstract">Abstract</h2> <p>This standard provides the description of an object that is made available to JavaScript applications which they can use to communicate with the Ethereum blockchain through. This standard only describes the transport mechanism, it does not specify the payloads that are valid nor does it specify how the client or the provider will discover or agree on payload content.</p> <p>How/where this Ethereum object is exposed is left to future standards.</p> <h2 id="motivation">Motivation</h2> <p>When working within a JavaScript runtime (such as NodeJS, Electron, Browser, etc.) it may be possible for the runtime or a runtime plugin to inject objects into the runtime. Someone authoring a runtime or a runtime plugin may choose to expose an Ethereum Provider to any JavaScript apps or scripts running within that runtime in order to provide indirect access to an Ethereum-like blockchain and potentially signing tools. In order to achieve maximum compatibility between the provider and the client, a standard is necessary for what the shape of that object is.</p> <h2 id="specification">Specification</h2> <h3 id="rfc-2119">RFC-2119</h3> <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="interface">Interface</h3> <p>TypeScript interface definition:</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"> RequestArguments</span><span> {</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> method</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"> params</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-storage"> readonly</span><span class="z-support"> unknown</span><span>[</span><span>]</span><span class="z-keyword"> |</span><span class="z-support"> object</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"> EthereumProvider</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> request</span><span>(</span><span class="z-variable">args</span><span class="z-keyword">:</span><span class="z-entity z-name"> RequestArguments</span><span>)</span><span class="z-keyword">:</span><span class="z-entity z-name"> Promise</span><span>&lt;</span><span class="z-support">unknown</span><span>&gt;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The Provider <strong>MUST</strong> implement a <code>request</code> method on the exposed <code>EthereumProvider</code> object. The <code>request</code> method <strong>MUST</strong> be callable with a single parameter which contains the arguments for the request as defined in the TypeScript <code>interface</code> above.</p> <p>If the Provider supports a JSON-RPC (https://www.jsonrpc.org/specification) request as specified elsewhere, then it <strong>MUST</strong> accept a <code>request</code> call for that JSON-RPC method with the <code>RequestArguments.method</code> argument matching the JSON-RPC <code>method</code> string for the RPC call and the <code>RequestArguments.params</code> matching the <code>params</code> object of the RPC call. The <code>RequestArguments.params</code> should be encoded as a JavaScript object matching the specified JSON-RPC type, not encoded as a JSON string as would normally be the case when transporting JSON-RPC.</p> <h4 id="example">Example</h4> <p>If the JSON-RPC request would contain a payload like:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">{ &quot;jsonrpc&quot;: &quot;2.0&quot;, &quot;id&quot;: 1, &quot;method&quot;: &quot;do_work&quot;, &quot;params&quot;: [ 5, &quot;hello&quot; ] }</span><span class="z-punctuation z-definition z-string">&#39;</span></span></code></pre> <p>Then the matching <code>EthereumProvider.request</code> call would be:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage">declare</span><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-entity z-name"> EthereumProvider</span></span> <span class="giallo-l"><span class="z-variable z-other">provider</span><span>.</span><span class="z-entity z-name">request</span><span>(</span><span>{</span><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">method</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> params</span><span>:</span><span> [</span><span class="z-constant"> 5</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">hello</span><span class="z-punctuation z-definition z-string">&#39;</span><span> ]</span><span> }</span><span>)</span></span></code></pre><h3 id="results">Results</h3> <p>If the Provider supports a JSON-RPC request as specified elsewhere, then it <strong>MUST</strong> return an object that matches the expected <code>result</code> definition for the associated JSON-RPC request.</p> <h4 id="example-1">Example</h4> <p>If the JSON-RPC response would contain a payload like:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">{ &quot;jsonrpc&quot;: &quot;2.0&quot;, &quot;id&quot;: 1, &quot;result&quot;: { &quot;color&quot;: &quot;red&quot;, &quot;value&quot;: 5 } }</span><span class="z-punctuation z-definition z-string">&#39;</span></span></code></pre> <p>Then the matching <code>EthereumProvider.request</code> response would be:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span>{</span><span class="z-entity z-name"> color</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">red</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-entity z-name"> value</span><span>:</span><span class="z-constant"> 5</span><span> }</span></span></code></pre><h3 id="errors">Errors</h3> <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"> ProviderRpcError</span><span class="z-storage"> extends</span><span class="z-entity"> Error</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> message</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> code</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> data</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>}</span></span></code></pre><table><thead><tr><th>code</th><th>message</th><th>meaning</th></tr></thead><tbody> <tr><td>4001</td><td>User Rejected Request</td><td>The user rejected the request.</td></tr> <tr><td>4100</td><td>Unauthorized</td><td>The requested method and/or account has not been authorized by the user.</td></tr> <tr><td>4200</td><td>Unsupported Method</td><td>The Provider does not support the requested method.</td></tr> <tr><td>4900</td><td>Disconnected</td><td>The Provider is disconnected from all chains.</td></tr> <tr><td>4901</td><td>Chain Disconnected</td><td>The Provider is not connected to the requested chain.</td></tr> </tbody></table> <p>If the Provider is unable to fulfill a request for any reason, it <strong>MUST</strong> resolve the promise as an error. The resolved error <strong>MUST</strong> be shaped as a <code>ProviderRpcError</code> defined above whenever possible. <em>While it is impossible to guaranteed that a JavaScript application will never throw an out of memory or stack overflow error, care should be taken to ensure that promise rejections conform to the above shape whenever possible.</em></p> <p>If a <code>code</code> is provided that is listed in the list above, or in the JSON-RPC specification (https://www.jsonrpc.org/specification#error_object), or in the associated JSON-RPC request standard being followed, then the error reason <strong>MUST</strong> align with the established meaning of that code and the <code>message</code> <strong>MUST</strong> match the provided <code>message</code></p> <p>The <code>data</code> field <strong>MAY</strong> contain any data that is relevant to the error or would help the user understand or troubleshoot the error.</p> <h2 id="rationale">Rationale</h2> <p>While this standard is perhaps not the greatest mechanism for communicating between an application and a blockchain, it is closely aligned with established practices within the community so migration from existing systems to this one should be relatively easy. Most communication is currently done via JSON-RPC, so aligning with the JSON-RPC standard was desired to enable quick integration with existing systems.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The relationship between Ethereum Provider and client is a trusted one, where it is assumed that the user implicitly trusts the Ethereum Provider which is how it managed to get injected into the client, or the client expressly pulled in a connection 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> 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-26T00:00:00+00:00 2026-02-11T14:48:25+00:00 g. nicholas d’andreahttps://github.com/gnidan Piper Merriamhttps://github.com/pipermerriam Nick Gheorghitahttps://github.com/njgheorghita Christian Reitwiessnerhttps://github.com/chriseth Ben Hauserhttps://github.com/iamdefinitelyahuman Bryant Eisenbachhttps://github.com/fubuloubu https://wg-eips.ritovision.com/2678/ <h2 id="simple-summary">Simple Summary</h2> <p>A data format describing a smart contract software package.</p> <h2 id="abstract">Abstract</h2> <p>This EIP defines a data format for <em>package manifest</em> documents, representing a package of one or more smart contracts, optionally including source code and any/all deployed instances across multiple networks. Package manifests are minified JSON objects, to be distributed via content addressable storage networks, such as IPFS. Packages are then published to on-chain EthPM registries, defined in <a href="https://wg-eips.ritovision.com/1319/">EIP-1319</a>, from where they can be freely accessed.</p> <p>This document presents a natural language description of a formal specification for version <strong>3</strong> of this format.</p> <h2 id="motivation">Motivation</h2> <p>This standard aims to encourage the Ethereum development ecosystem towards software best practices around code reuse. By defining an open, community-driven package data format standard, this effort seeks to provide support for package management tools development by offering a general-purpose solution that has been designed with observed common practices in mind.</p> <ul> <li>Updates the schema for a <em>package manifest</em> to be compatible with the <a rel="external" href="https://solidity.readthedocs.io/en/latest/metadata.html">metadata</a> output for compilers.</li> <li>Updates the <code>"sources"</code> object definition to support a wider range of source file types and serve as <a rel="external" href="https://solidity.readthedocs.io/en/latest/using-the-compiler.html#compiler-input-and-output-json-description">JSON input</a> for a compiler.</li> <li>Moves compiler definitions to a top-level <code>"compilers"</code> array in order to: <ul> <li>Simplify the links between a compiler version, sources, and the compiled assets.</li> <li>Simplify packages that use multiple compiler versions.</li> </ul> </li> <li>Updates key formatting from <code>snake_case</code> to <code>camelCase</code> to be more consistent with <a rel="external" href="https://google.github.io/styleguide/jsoncstyleguide.xml?showone=Property_Name_Format#Property_Name_Format">JSON convention</a>.</li> </ul> <h3 id="guiding-principles">Guiding Principles</h3> <p>This specification makes the following assumptions about the document lifecycle.</p> <ol> <li> <p>Package manifests are intended to be generated programmatically by package management software as part of the release process.</p> </li> <li> <p>Package manifests will be consumed by package managers during tasks like installing package dependencies or building and deploying new releases.</p> </li> <li> <p>Package manifests will typically <strong>not</strong> be stored alongside the source, but rather by package registries <em>or</em> referenced by package registries and stored in something akin to IPFS.</p> </li> <li> <p>Package manifests can be used to verify public deployments of source contracts.</p> </li> </ol> <h3 id="use-cases">Use Cases</h3> <p>The following use cases were considered during the creation of this specification.</p> <ul> <li><strong>owned</strong>: A package which contains contracts which are not meant to be used by themselves but rather as base contracts to provide functionality to other contracts through inheritance.</li> <li><strong>transferable</strong>: A package which has a single dependency.</li> <li><strong>standard-token</strong>: A package which contains a reusable contract.</li> <li><strong>safe-math-lib</strong>: A package which contains deployed instance of one of the package contracts.</li> <li><strong>piper-coin</strong>: A package which contains a deployed instance of a reusable contract from a dependency.</li> <li><strong>escrow</strong>: A package which contains a deployed instance of a local contract which is linked against a deployed instance of a local library.</li> <li><strong>wallet</strong>: A package with a deployed instance of a local contract which is linked against a deployed instance of a library from a dependency.</li> <li><strong>wallet-with-send</strong>: A package with a deployed instance which links against a deep dependency.</li> <li><strong>simple-auction</strong>: Compiler <code>"metadata"</code> field output.</li> </ul> <h2 id="package-specification">Package Specification</h2> <h3 id="conventions">Conventions</h3> <h4 id="rfc2119">RFC2119</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 RFC 2119.</p> <ul> <li><a rel="external" href="https://www.ietf.org/rfc/rfc2119.txt">https://www.ietf.org/rfc/rfc2119.txt</a></li> </ul> <h4 id="prefixed-vs-unprefixed">Prefixed vs Unprefixed</h4> <p>A <a href="https://wg-eips.ritovision.com/2678/#prefixed">prefixed</a> hexadecimal value begins with <code>0x</code>. <a href="https://wg-eips.ritovision.com/2678/#unprefixed">Unprefixed</a> values have no prefix. Unless otherwise specified, all hexadecimal values <strong>should</strong> be represented with the <code>0x</code> prefix.</p> <ul> <li><strong>Prefixed</strong>: <code>0xdeadbeef</code></li> <li><strong>Unprefixed</strong>: <code>deadbeef</code></li> </ul> <h3 id="document-format">Document Format</h3> <p>The canonical format is a single JSON object. Packages <strong>must</strong> conform to the following serialization rules.</p> <ul> <li> <p>The document <strong>must</strong> be tightly packed, meaning no linebreaks or extra whitespace.</p> </li> <li> <p>The keys in all objects <strong>must</strong> be sorted alphabetically.</p> </li> <li> <p>Duplicate keys in the same object are invalid.</p> </li> <li> <p>The document <strong>must</strong> use <a rel="external" href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a> encoding.</p> </li> <li> <p>The document <strong>must</strong> not have a trailing newline.</p> </li> <li> <p>To ensure backwards compatibility, <code>manifest_version</code> is a forbidden top-level key.</p> </li> </ul> <h3 id="document-specification">Document Specification</h3> <p>The following fields are defined for the package. Custom fields <strong>may</strong> be included. Custom fields <strong>should</strong> be prefixed with <code>x-</code> to prevent name collisions with future versions of the specification.</p> <ul> <li><strong>See Also</strong>: Formalized (<a rel="external" href="https://json-schema.org">JSON-Schema</a>) version of this specification: <a href="https://wg-eips.ritovision.com/2678/./assets/package.spec.json">package.spec.json</a></li> <li><strong>Jump To</strong>: <a href="https://wg-eips.ritovision.com/2678/#object-definitions">Definitions</a></li> </ul> <h3 id="ethpm-manifest-version">EthPM Manifest Version</h3> <p>The <code>manifest</code> field defines the specification version that this document conforms to.</p> <ul> <li> <p>Packages <strong>must</strong> include this field.</p> </li> <li> <p><strong>Required</strong>: Yes</p> </li> <li> <p><strong>Key</strong>: <code>manifest</code></p> </li> <li> <p><strong>Type</strong>: String</p> </li> <li> <p><strong>Allowed Values</strong>: <code>ethpm/3</code></p> </li> </ul> <h3 id="package-name">Package Name</h3> <p>The <code>name</code> field defines a human readable name for this package.</p> <ul> <li> <p>Packages <strong>should</strong> include this field to be released on an EthPM registry.</p> </li> <li> <p>Package names <strong>must</strong> begin with a lowercase letter and be comprised of only the lowercase letters <code>a-z</code>, numeric characters <code>0-9</code>, and the dash character <code>-</code>.</p> </li> <li> <p>Package names <strong>must</strong> not exceed 255 characters in length.</p> </li> <li> <p><strong>Required</strong>: If <code>version</code> is included.</p> </li> <li> <p><strong>Key</strong>: <code>name</code></p> </li> <li> <p><strong>Type</strong>: String</p> </li> <li> <p><strong>Format</strong>: <strong>must</strong> match the regular expression <code>^[a-z][-a-z0-9]{0,255}$</code></p> </li> </ul> <h3 id="package-version">Package Version</h3> <p>The <code>version</code> field declares the version number of this release.</p> <ul> <li> <p>Packages <strong>should</strong> include this field to be released on an EthPM registry.</p> </li> <li> <p>This value <strong>should</strong> conform to the <a rel="external" href="http://semver.org/">semver</a> version numbering specification.</p> </li> <li> <p><strong>Required</strong>: If <code>name</code> is included.</p> </li> <li> <p><strong>Key</strong>: <code>version</code></p> </li> <li> <p><strong>Type</strong>: String</p> </li> </ul> <h3 id="package-metadata">Package Metadata</h3> <p>The <code>meta</code> field defines a location for metadata about the package which is not integral in nature for package installation, but may be important or convenient to have on-hand for other reasons.</p> <ul> <li> <p>This field <strong>should</strong> be included in all Packages.</p> </li> <li> <p><strong>Required</strong>: No</p> </li> <li> <p><strong>Key</strong>: <code>meta</code></p> </li> <li> <p><strong>Type</strong>: <a href="https://wg-eips.ritovision.com/2678/#the-package-meta-object">Package Meta Object</a></p> </li> </ul> <h3 id="sources">Sources</h3> <p>The <code>sources</code> field defines a source tree that <strong>should</strong> comprise the full source tree necessary to recompile the contracts contained in this release.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Key</strong>: <code>sources</code></li> <li><strong>Type</strong>: Object (String: <a href="https://wg-eips.ritovision.com/2678/#the-source-object">Sources Object</a>)</li> </ul> <h3 id="contract-types">Contract Types</h3> <p>The <code>contractTypes</code> field hosts the <a href="https://wg-eips.ritovision.com/2678/#contract-type">Contract Types</a> which have been included in this release.</p> <ul> <li> <p>Packages <strong>should</strong> only include contract types that can be found in the source files for this package.</p> </li> <li> <p>Packages <strong>should not</strong> include contract types from dependencies.</p> </li> <li> <p>Packages <strong>should not</strong> include abstract contracts in the contract types section of a release.</p> </li> <li> <p><strong>Required</strong>: No</p> </li> <li> <p><strong>Key</strong>: <code>contractTypes</code></p> </li> <li> <p><strong>Type</strong>: Object (String: <a href="https://wg-eips.ritovision.com/2678/#the-contract-type-object">Contract Type Object</a>)</p> </li> <li> <p><strong>Format</strong>: Keys <strong>must</strong> be valid <a href="https://wg-eips.ritovision.com/2678/#contract-alias">Contract Aliases</a>. <br> Values <strong>must</strong> conform to the <a href="https://wg-eips.ritovision.com/2678/#the-contract-type-object">Contract Type Object</a> definition.</p> </li> </ul> <h3 id="compilers">Compilers</h3> <p>The <code>compilers</code> field holds the information about the compilers and their settings that have been used to generate the various <code>contractTypes</code> included in this release.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Key</strong>: <code>compilers</code></li> <li><strong>Type</strong>: Array (<a href="https://wg-eips.ritovision.com/2678/#the-compiler-information-object">Compiler Information Object</a>)</li> </ul> <h3 id="deployments">Deployments</h3> <p>The <code>deployments</code> field holds the information for the chains on which this release has <a href="https://wg-eips.ritovision.com/2678/#contract-instance">Contract Instances</a> as well as the <a href="https://wg-eips.ritovision.com/2678/#contract-type">Contract Types</a> and other deployment details for those deployed contract instances. The set of chains defined by the <a href="https://wg-eips.ritovision.com/2678/#bip122-uri">BIP122 URI</a> keys for this object <strong>must</strong> be unique. There cannot be two different URI keys in a deployments field representing the same blockchain.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Key</strong>: <code>deployments</code></li> <li><strong>Type</strong>: Object (String: Object(String: <a href="https://wg-eips.ritovision.com/2678/#the-contract-instance-object">Contract Instance Object</a>))</li> <li><strong>Format</strong>: Keys <strong>must</strong> be a valid BIP122 URI chain definition. <br>Values <strong>must</strong> be objects which conform to the following format:<br>- Keys <strong>must</strong> be valid <a href="https://wg-eips.ritovision.com/2678/#contract-instance-name">Contract Instance Names</a><br>- Values <strong>must</strong> be a valid <a href="https://wg-eips.ritovision.com/2678/#the-contract-instance-object">Contract Instance Object</a></li> </ul> <h3 id="build-dependencies">Build Dependencies</h3> <p>The <code>buildDependencies</code> field defines a key/value mapping of EthPM packages that this project depends on.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Key</strong>: <code>buildDependencies</code></li> <li><strong>Type</strong>: Object (String: String)</li> <li><strong>Format</strong>: Keys <strong>must</strong> be valid <a href="https://wg-eips.ritovision.com/2678/#package-name">package names</a>.<br>Values <strong>must</strong> be a <a href="https://wg-eips.ritovision.com/2678/#content-addressable-uri">Content Addressable URI</a> which resolves to a valid package that conforms the same EthPM manifest version as its parent.</li> </ul> <h3 id="object-definitions">Object Definitions</h3> <p>Definitions for different objects used within the Package. All objects allow custom fields to be included. Custom fields <strong>should</strong> be prefixed with <code>x-</code> to prevent name collisions with future versions of the specification.</p> <h3 id="the-link-reference-object">The <em>Link Reference</em> Object</h3> <p>A <a href="https://wg-eips.ritovision.com/2678/#link-reference">Link Reference</a> object has the following key/value pairs. All link references are assumed to be associated with some corresponding <a href="https://wg-eips.ritovision.com/2678/#bytecode">Bytecode</a>.</p> <h4 id="offsets-offsets">Offsets: <code>offsets</code></h4> <p>The <code>offsets</code> field is an array of integers, corresponding to each of the start positions where the link reference appears in the bytecode. Locations are 0-indexed from the beginning of the bytes representation of the corresponding bytecode. This field is invalid if it references a position that is beyond the end of the bytecode.</p> <ul> <li><strong>Required</strong>: Yes</li> <li><strong>Type</strong>: Array</li> </ul> <h4 id="length-length">Length: <code>length</code></h4> <p>The <code>length</code> field is an integer which defines the length in bytes of the link reference. This field is invalid if the end of the defined link reference exceeds the end of the bytecode.</p> <ul> <li><strong>Required</strong>: Yes</li> <li><strong>Type</strong>: Integer</li> </ul> <h4 id="name-name">Name: <code>name</code></h4> <p>The <code>name</code> field is a string which <strong>must</strong> be a valid <a href="https://wg-eips.ritovision.com/2678/#identifier">Identifier</a>. Any link references which <strong>should</strong> be linked with the same link value <strong>should</strong> be given the same name.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Type</strong>: String</li> <li><strong>Format</strong>: <strong>must</strong> conform to the <a href="https://wg-eips.ritovision.com/2678/#identifier">Identifier</a> format.</li> </ul> <h3 id="the-link-value-object">The <em>Link Value</em> Object</h3> <p>Describes a single <a href="https://wg-eips.ritovision.com/2678/#link-value">Link Value</a>.</p> <p>A <strong>Link Value object</strong> is defined to have the following key/value pairs.</p> <h4 id="offsets-offsets-1">Offsets: <code>offsets</code></h4> <p>The <code>offsets</code> field defines the locations within the corresponding bytecode where the <code>value</code> for this link value was written. These locations are 0-indexed from the beginning of the bytes representation of the corresponding bytecode.</p> <ul> <li><strong>Required</strong>: Yes</li> <li><strong>Type</strong>: Integer</li> <li><strong>Format</strong>: See below.</li> </ul> <p>Format</p> <p>Array of integers, where each integer <strong>must</strong> conform to all of the following.</p> <ul> <li> <p>greater than or equal to zero</p> </li> <li> <p>strictly less than the length of the unprefixed hexadecimal representation of the corresponding bytecode.</p> </li> </ul> <h4 id="type-type">Type: <code>type</code></h4> <p>The <code>type</code> field defines the <code>value</code> type for determining what is encoded when <a href="https://wg-eips.ritovision.com/2678/#linking">linking</a> the corresponding bytecode.</p> <ul> <li><strong>Required</strong>: Yes</li> <li><strong>Type</strong>: String</li> <li><strong>Allowed Values</strong>: <code>"literal"</code> for bytecode literals.<br><code>"reference"</code> for named references to a particular <a href="https://wg-eips.ritovision.com/2678/#contract-instance">Contract Instance</a></li> </ul> <h4 id="value-value">Value: <code>value</code></h4> <p>The <code>value</code> field defines the value which should be written when <a href="https://wg-eips.ritovision.com/2678/#linking">linking</a> the corresponding bytecode.</p> <ul> <li><strong>Required</strong>: Yes</li> <li><strong>Type</strong>: String</li> <li><strong>Format</strong>: Determined based on <code>type</code>, see below.</li> </ul> <p>Format</p> <p>For static value <em>literals</em> (e.g. address), value <strong>must</strong> be a 0x-prefixed hexadecimal string representing bytes.</p> <p>To reference the address of a <a href="https://wg-eips.ritovision.com/2678/#contract-instance">Contract Instance</a> from the current package the value should be the name of that contract instance.</p> <ul> <li> <p>This value <strong>must</strong> be a valid <a href="https://wg-eips.ritovision.com/2678/#contract-instance-name">Contract Instance Name</a>.</p> </li> <li> <p>The chain definition under which the contract instance that this link value belongs to must contain this value within its keys.</p> </li> <li> <p>This value <strong>may not</strong> reference the same contract instance that this link value belongs to.</p> </li> </ul> <p>To reference a contract instance from a <a href="https://wg-eips.ritovision.com/2678/#package">Package</a> from somewhere within the dependency tree the value is constructed as follows.</p> <ul> <li> <p>Let <code>[p1, p2, .. pn]</code> define a path down the dependency tree.</p> </li> <li> <p>Each of <code>p1, p2, pn</code> <strong>must</strong> be valid package names.</p> </li> <li> <p><code>p1</code> <strong>must</strong> be present in keys of the <code>buildDependencies</code> for the current package.</p> </li> <li> <p>For every <code>pn</code> where <code>n &gt; 1</code>, <code>pn</code> <strong>must</strong> be present in the keys of the <code>buildDependencies</code> of the package for <code>pn-1</code>.</p> </li> <li> <p>The value is represented by the string <code>&lt;p1&gt;:&lt;p2&gt;:&lt;...&gt;:&lt;pn&gt;:&lt;contract-instance&gt;</code> where all of <code>&lt;p1&gt;</code>, <code>&lt;p2&gt;</code>, <code>&lt;pn&gt;</code> are valid package names and <code>&lt;contract-instance&gt;</code> is a valid <a href="https://wg-eips.ritovision.com/2678/#contract-name">Contract Name</a>.</p> </li> <li> <p>The <code>&lt;contract-instance&gt;</code> value <strong>must</strong> be a valid <a href="https://wg-eips.ritovision.com/2678/#contract-instance-name">Contract Instance Name</a>.</p> </li> <li> <p>Within the package of the dependency defined by <code>&lt;pn&gt;</code>, all of the following must be satisfiable:</p> <ul> <li> <p>There <strong>must</strong> be <em>exactly</em> one chain defined under the <code>deployments</code> key which matches the chain definition that this link value is nested under.</p> </li> <li> <p>The <code>&lt;contract-instance&gt;</code> value <strong>must</strong> be present in the keys of the matching chain.</p> </li> </ul> </li> </ul> <h3 id="the-bytecode-object">The <em>Bytecode</em> Object</h3> <p>A bytecode object has the following key/value pairs.</p> <h4 id="bytecode-bytecode">Bytecode: <code>bytecode</code></h4> <p>The <code>bytecode</code> field is a string containing the <code>0x</code> prefixed hexadecimal representation of the bytecode.</p> <ul> <li><strong>Required</strong>: Yes</li> <li><strong>Type</strong>: String</li> <li><strong>Format</strong>: <code>0x</code> prefixed hexadecimal.</li> </ul> <h4 id="link-references-linkreferences">Link References: <code>linkReferences</code></h4> <p>The <code>linkReferences</code> field defines the locations in the corresponding bytecode which require <a href="https://wg-eips.ritovision.com/2678/#linking">linking</a>.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Type</strong>: Array</li> <li><strong>Format</strong>: All values <strong>must</strong> be valid <a href="https://wg-eips.ritovision.com/2678/#the-link-reference-object">Link Reference objects</a>. See also below.</li> </ul> <p>Format</p> <p>This field is considered invalid if <em>any</em> of the <a href="https://wg-eips.ritovision.com/2678/#link-reference">Link References</a> are invalid when applied to the corresponding <code>bytecode</code> field, <em>or</em> if any of the link references intersect.</p> <p>Intersection is defined as two link references which overlap.</p> <h4 id="link-dependencies-linkdependencies">Link Dependencies: <code>linkDependencies</code></h4> <p>The <code>linkDependencies</code> defines the <a href="https://wg-eips.ritovision.com/2678/#link-value">Link Values</a> that have been used to link the corresponding bytecode.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Type</strong>: Array</li> <li><strong>Format</strong>: All values <strong>must</strong> be valid <a href="https://wg-eips.ritovision.com/2678/#the-link-value-object">Link Value objects</a>. See also below.</li> </ul> <p>Format</p> <p>Validation of this field includes the following:</p> <ul> <li> <p>Two link value objects <strong>must not</strong> contain any of the same values for <code>offsets</code>.</p> </li> <li> <p>Each <a href="https://wg-eips.ritovision.com/2678/#the-link-value-object">link value object</a> <strong>must</strong> have a corresponding <a href="https://wg-eips.ritovision.com/2678/#the-link-reference-object">link reference object</a> under the <code>linkReferences</code> field.</p> </li> <li> <p>The length of the resolved <code>value</code> <strong>must</strong> be equal to the <code>length</code> of the corresponding <a href="https://wg-eips.ritovision.com/2678/#link-reference">Link Reference</a>.</p> </li> </ul> <h3 id="the-package-meta-object">The <em>Package Meta</em> Object</h3> <p>The <em>Package Meta</em> object is defined to have the following key/value pairs.</p> <h4 id="authors">Authors</h4> <p>The <code>authors</code> field defines a list of human readable names for the authors of this package. Packages <strong>may</strong> include this field.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Key</strong>: <code>authors</code></li> <li><strong>Type</strong>: Array(String)</li> </ul> <h4 id="license">License</h4> <p>The <code>license</code> field declares the license associated with this package. This value <strong>should</strong> conform to the <a rel="external" href="https://spdx.org/licenses/">SPDX</a> format. Packages <strong>should</strong> include this field. If a file <a href="https://wg-eips.ritovision.com/2678/#the-source-object">Source Object</a> defines its own license, that license takes precedence for that particular file over this package-scoped <code>meta</code> license.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Key</strong>: <code>license</code></li> <li><strong>Type</strong>: String</li> </ul> <h4 id="description">Description</h4> <p>The <code>description</code> field provides additional detail that may be relevant for the package. Packages <strong>may</strong> include this field.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Key</strong>: <code>description</code></li> <li><strong>Type</strong>: String</li> </ul> <h4 id="keywords">Keywords</h4> <p>The <code>keywords</code> field provides relevant keywords related to this package.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Key</strong>: <code>keywords</code></li> <li><strong>Type</strong>: Array(String)</li> </ul> <h4 id="links">Links</h4> <p>The <code>links</code> field provides URIs to relevant resources associated with this package. When possible, authors <strong>should</strong> use the following keys for the following common resources.</p> <ul> <li> <p><code>website</code>: Primary website for the package.</p> </li> <li> <p><code>documentation</code>: Package Documentation</p> </li> <li> <p><code>repository</code>: Location of the project source code.</p> </li> <li> <p><strong>Required</strong>: No</p> </li> <li> <p><strong>Key</strong>: <code>links</code></p> </li> <li> <p><strong>Type</strong>: Object (String: String)</p> </li> </ul> <h3 id="the-sources-object">The <em>Sources</em> Object</h3> <p>A <em>Sources</em> object is defined to have the following fields.</p> <ul> <li><strong>Key</strong>: A unique identifier for the source file. (String)</li> <li><strong>Value</strong>: <a href="https://wg-eips.ritovision.com/2678/#the-source-object">Source Object</a></li> </ul> <h3 id="the-source-object">The <em>Source</em> Object</h3> <h4 id="checksum-checksum">Checksum: <code>checksum</code></h4> <p>Hash of the source file.</p> <ul> <li><strong>Required</strong>: Only <strong>if</strong> the <code>content</code> field is missing and none of the provided URLs contain a content hash.</li> <li><strong>Key</strong>: <code>checksum</code></li> <li><strong>Value</strong>: <a href="https://wg-eips.ritovision.com/2678/#the-checksum-object">Checksum Object</a></li> </ul> <h4 id="urls-urls">URLS: <code>urls</code></h4> <p>Array of urls that resolve to the same source file.</p> <ul> <li> <p>Urls <strong>should</strong> be stored on a content-addressable filesystem. <strong>If</strong> they are not, then either <code>content</code> or <code>checksum</code> <strong>must</strong> be included.</p> </li> <li> <p>Urls <strong>must</strong> be prefixed with a scheme.</p> </li> <li> <p>If the resulting document is a directory the key <strong>should</strong> be interpreted as a directory path.</p> </li> <li> <p>If the resulting document is a file the key <strong>should</strong> be interpreted as a file path.</p> </li> <li> <p><strong>Required</strong>: If <code>content</code> is not included.</p> </li> <li> <p><strong>Key</strong>: <code>urls</code></p> </li> <li> <p><strong>Value</strong>: Array(String)</p> </li> </ul> <h4 id="content-content">Content: <code>content</code></h4> <p>Inlined contract source. If both <code>urls</code> and <code>content</code> are provided, the <code>content</code> value <strong>must</strong> match the content of the files identified in <code>urls</code>.</p> <ul> <li><strong>Required</strong>: If <code>urls</code> is not included.</li> <li><strong>Key</strong>: <code>content</code></li> <li><strong>Value</strong>: String</li> </ul> <h4 id="install-path-installpath">Install Path: <code>installPath</code></h4> <p>Filesystem path of source file.</p> <ul> <li> <p><strong>Must</strong> be a relative filesystem path that begins with a <code>./</code>.</p> </li> <li> <p><strong>Must</strong> resolve to a path that is within the current virtual working directory.</p> </li> <li> <p><strong>Must</strong> be unique across all included sources.</p> </li> <li> <p><strong>Must not</strong> contain <code>../</code> to avoid accessing files outside of the source folder in improper implementations.</p> </li> <li> <p><strong>Required</strong>: This field <strong>must</strong> be included for the package to be writable to disk.</p> </li> <li> <p><strong>Key</strong>: <code>installPath</code></p> </li> <li> <p><strong>Value</strong>: String</p> </li> </ul> <h4 id="type-type-1">Type: <code>type</code></h4> <p>The <code>type</code> field declares the type of the source file. The field <strong>should</strong> be one of the following values: <code>solidity</code>, <code>vyper</code>, <code>abi-json</code>, <code>solidity-ast-json</code>.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Key</strong>: <code>type</code></li> <li><strong>Value</strong>: String</li> </ul> <h4 id="license-license">License: <code>license</code></h4> <p>The <code>license</code> field declares the type of license associated with this source file. When defined, this license overrides the package-scoped <a href="https://wg-eips.ritovision.com/2678/#license">meta license</a>.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Key</strong>: <code>license</code></li> <li><strong>Value</strong>: String</li> </ul> <h3 id="the-checksum-object">The <em>Checksum</em> Object</h3> <p>A <em>Checksum</em> object is defined to have the following key/value pairs.</p> <h4 id="algorithm-algorithm">Algorithm: <code>algorithm</code></h4> <p>The <code>algorithm</code> used to generate the corresponding hash. Possible algorithms include, but are not limited to <code>sha3</code>, <code>sha256</code>, <code>md5</code>, <code>keccak256</code>.</p> <ul> <li><strong>Required</strong>: Yes</li> <li><strong>Type</strong>: String</li> </ul> <h4 id="hash-hash">Hash: <code>hash</code></h4> <p>The <code>hash</code> of a source files contents generated with the corresponding algorithm.</p> <ul> <li><strong>Required</strong>: Yes</li> <li><strong>Type</strong>: String</li> </ul> <h3 id="the-contract-type-object">The <em>Contract Type</em> Object</h3> <p>A <em>Contract Type</em> object is defined to have the following key/value pairs.</p> <h4 id="contract-name-contractname">Contract Name: <code>contractName</code></h4> <p>The <code>contractName</code> field defines the <a href="https://wg-eips.ritovision.com/2678/#contract-name">Contract Name</a> for this <a href="https://wg-eips.ritovision.com/2678/#contract-type">Contract Type</a>.</p> <ul> <li><strong>Required</strong>: If the <a href="https://wg-eips.ritovision.com/2678/#contract-name">Contract Name</a> and <a href="https://wg-eips.ritovision.com/2678/#contract-alias">Contract Alias</a> are not the same.</li> <li><strong>Type</strong>: String</li> <li><strong>Format</strong>: <strong>Must</strong> be a valid <a href="https://wg-eips.ritovision.com/2678/#contract-name">Contract Name</a></li> </ul> <h4 id="source-id-sourceid">Source ID: <code>sourceId</code></h4> <p>The global source identifier for the source file from which this contract type was generated.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Type</strong>: String</li> <li><strong>Format</strong>: <strong>Must</strong> match a unique source ID included in the <a href="https://wg-eips.ritovision.com/2678/#the-sources-object">Sources Object</a> for this package.</li> </ul> <h4 id="deployment-bytecode-deploymentbytecode">Deployment Bytecode: <code>deploymentBytecode</code></h4> <p>The <code>deploymentBytecode</code> field defines the bytecode for this <a href="https://wg-eips.ritovision.com/2678/#contract-type">Contract Type</a>.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Type</strong>: Object</li> <li><strong>Format</strong>: <strong>Must</strong> conform to the <a href="https://wg-eips.ritovision.com/2678/#the-bytecode-object">Bytecode object</a> format.</li> </ul> <h4 id="runtime-bytecode-runtimebytecode">Runtime Bytecode: <code>runtimeBytecode</code></h4> <p>The <code>runtimeBytecode</code> field defines the unlinked <code>0x</code>-prefixed runtime portion of <a href="https://wg-eips.ritovision.com/2678/#bytecode">Bytecode</a> for this <a href="https://wg-eips.ritovision.com/2678/#contract-type">Contract Type</a>.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Type</strong>: Object</li> <li><strong>Format</strong>: <strong>Must</strong> conform to the <a href="https://wg-eips.ritovision.com/2678/#the-bytecode-object">Bytecode object</a> format.</li> </ul> <h4 id="abi-abi">ABI: <code>abi</code></h4> <ul> <li><strong>Required</strong>: No</li> <li><strong>Type</strong>: Array</li> <li><strong>Format</strong>: <strong>Must</strong> conform to the <a rel="external" href="https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI#json">Ethereum Contract ABI JSON</a> format.</li> </ul> <h4 id="userdoc-userdoc">UserDoc: <code>userdoc</code></h4> <ul> <li><strong>Required</strong>: No</li> <li><strong>Type</strong>: Object</li> <li><strong>Format</strong>: <strong>Must</strong> conform to the <a rel="external" href="https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format#user-documentation">UserDoc</a> format.</li> </ul> <h4 id="devdoc-devdoc">DevDoc: <code>devdoc</code></h4> <ul> <li><strong>Required</strong>: No</li> <li><strong>Type</strong>: Object</li> <li><strong>Format</strong>: <strong>Must</strong> conform to the <a rel="external" href="https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format#developer-documentation">DevDoc</a> format.</li> </ul> <h3 id="the-contract-instance-object">The <em>Contract Instance</em> Object</h3> <p>A <strong>Contract Instance Object</strong> represents a single deployed <a href="https://wg-eips.ritovision.com/2678/#contract-instance">Contract Instance</a> and is defined to have the following key/value pairs.</p> <h4 id="contract-type-contracttype">Contract Type: <code>contractType</code></h4> <p>The <code>contractType</code> field defines the <a href="https://wg-eips.ritovision.com/2678/#contract-type">Contract Type</a> for this <a href="https://wg-eips.ritovision.com/2678/#contract-instance">Contract Instance</a>. This can reference any of the contract types included in this <a href="https://wg-eips.ritovision.com/2678/#package">Package</a> <em>or</em> any of the contract types found in any of the package dependencies from the <code>buildDependencies</code> section of the <a href="https://wg-eips.ritovision.com/2678/#package-manifest">Package Manifest</a>.</p> <ul> <li><strong>Required</strong>: Yes</li> <li><strong>Type</strong>: String</li> <li><strong>Format</strong>: See below.</li> </ul> <p>Format</p> <p>Values for this field <strong>must</strong> conform to <em>one of</em> the two formats herein.</p> <p>To reference a contract type from this Package, use the format <code>&lt;contract-alias&gt;</code>.</p> <ul> <li> <p>The <code>&lt;contract-alias&gt;</code> value <strong>must</strong> be a valid <a href="https://wg-eips.ritovision.com/2678/#contract-alias">Contract Alias</a>.</p> </li> <li> <p>The value <strong>must</strong> be present in the keys of the <code>contractTypes</code> section of this Package.</p> </li> </ul> <p>To reference a contract type from a dependency, use the format <code>&lt;package-name&gt;:&lt;contract-alias&gt;</code>.</p> <ul> <li> <p>The <code>&lt;package-name&gt;</code> value <strong>must</strong> be present in the keys of the <code>buildDependencies</code> of this Package.</p> </li> <li> <p>The <code>&lt;contract-alias&gt;</code> value <strong>must</strong> be be a valid <a href="https://wg-eips.ritovision.com/2678/#contract-alias">Contract Alias</a>.</p> </li> <li> <p>The resolved package for <code>&lt;package-name&gt;</code> must contain the <code>&lt;contract-alias&gt;</code> value in the keys of the <code>contractTypes</code> section.</p> </li> </ul> <h4 id="address-address">Address: <code>address</code></h4> <p>The <code>address</code> field defines the <a href="https://wg-eips.ritovision.com/2678/#address">Address</a> of the <a href="https://wg-eips.ritovision.com/2678/#contract-instance">Contract Instance</a>.</p> <ul> <li><strong>Required</strong>: Yes</li> <li><strong>Type</strong>: String</li> <li><strong>Format</strong>: Hex encoded <code>0x</code> prefixed Ethereum address matching the regular expression <code>^0x[0-9a-fA-F]{40}$</code>.</li> </ul> <h4 id="transaction-transaction">Transaction: <code>transaction</code></h4> <p>The <code>transaction</code> field defines the transaction hash in which this <a href="https://wg-eips.ritovision.com/2678/#contract-instance">Contract Instance</a> was created.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Type</strong>: String</li> <li><strong>Format</strong>: <code>0x</code> prefixed hex encoded transaction hash.</li> </ul> <h4 id="block-block">Block: <code>block</code></h4> <p>The <code>block</code> field defines the block hash in which this the transaction which created this <em>contract instance</em> was mined.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Type</strong>: String</li> <li><strong>Format</strong>: <code>0x</code> prefixed hex encoded block hash.</li> </ul> <h4 id="runtime-bytecode-runtimebytecode-1">Runtime Bytecode: <code>runtimeBytecode</code></h4> <p>The <code>runtimeBytecode</code> field defines the runtime portion of bytecode for this <a href="https://wg-eips.ritovision.com/2678/#contract-instance">Contract Instance</a>. When present, the value from this field supersedes the <code>runtimeBytecode</code> from the <a href="https://wg-eips.ritovision.com/2678/#contract-type">Contract Type</a> for this <a href="https://wg-eips.ritovision.com/2678/#contract-instance">Contract Instance</a>.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Type</strong>: Object</li> <li><strong>Format</strong>: <strong>Must</strong> conform to the <a href="https://wg-eips.ritovision.com/2678/#the-bytecode-object">Bytecode Object</a> format.</li> </ul> <p>Every entry in the <code>linkReferences</code> for this bytecode <strong>must</strong> have a corresponding entry in the <code>linkDependencies</code> section.</p> <h3 id="the-compiler-information-object">The <em>Compiler Information</em> Object</h3> <p>The <code>compilers</code> field defines the various compilers and settings used during compilation of any <a href="https://wg-eips.ritovision.com/2678/#contract-type">Contract Types</a> or <a href="https://wg-eips.ritovision.com/2678/#contract-instance">Contract Instance</a> included in this package.</p> <p>A <em>Compiler Information</em> object is defined to have the following key/value pairs.</p> <h4 id="name-name-1">Name: <code>name</code></h4> <p>The <code>name</code> field defines which compiler was used in compilation.</p> <ul> <li><strong>Required</strong>: Yes</li> <li><strong>Key</strong>: <code>name</code></li> <li><strong>Type</strong>: String</li> </ul> <h4 id="version-version">Version: <code>version</code></h4> <p>The <code>version</code> field defines the version of the compiler. The field <strong>should</strong> be OS agnostic (OS not included in the string) and take the form of either the stable version in <a rel="external" href="http://semver.org/">semver</a> format or if built on a nightly should be denoted in the form of <code>&lt;semver&gt;-&lt;commit-hash&gt;</code> ex: <code>0.4.8-commit.60cc1668</code>.</p> <ul> <li><strong>Required</strong>: Yes</li> <li><strong>Key</strong>: <code>version</code></li> <li><strong>Type</strong>: String</li> </ul> <h4 id="settings-settings">Settings: <code>settings</code></h4> <p>The <code>settings</code> field defines any settings or configuration that was used in compilation. For the <code>"solc"</code> compiler, this <strong>should</strong> conform to the <a rel="external" href="http://solidity.readthedocs.io/en/latest/using-the-compiler.html#compiler-input-and-output-json-description">Compiler Input and Output Description</a>.</p> <ul> <li><strong>Required</strong>: No</li> <li><strong>Key</strong>: <code>settings</code></li> <li><strong>Type</strong>: Object</li> </ul> <h4 id="contract-types-contracttypes">Contract Types: <code>contractTypes</code></h4> <p>A list of the <a href="https://wg-eips.ritovision.com/2678/#contract-alias">Contract Alias</a> or <a href="https://wg-eips.ritovision.com/2678/#contract-type">Contract Types</a> in this package that used this compiler to generate its outputs.</p> <ul> <li> <p>All <code>contractTypes</code> that locally declare <code>runtimeBytecode</code> <strong>should</strong> be attributed for by a compiler object.</p> </li> <li> <p>A single <code>contractTypes</code> <strong>must</strong> not be attributed to more than one compiler.</p> </li> <li> <p><strong>Required</strong>: No</p> </li> <li> <p><strong>Key</strong>: <code>contractTypes</code></p> </li> <li> <p><strong>Type</strong>: Array(<a href="https://wg-eips.ritovision.com/2678/#contract-alias">Contract Alias</a>)</p> </li> </ul> <h3 id="bip122-uri">BIP122 URI</h3> <p>BIP122 URIs are used to define a blockchain via a subset of the <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0122.mediawiki">BIP-122</a> spec.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>blockchain://&lt;genesis_hash&gt;/block/&lt;latest confirmed block hash&gt;</span></span></code></pre> <p>The <code>&lt;genesis hash&gt;</code> represents the blockhash of the first block on the chain, and <code>&lt;latest confirmed block hash&gt;</code> represents the hash of the latest block that’s been reliably confirmed (package managers should be free to choose their desired level of confirmations).</p> <h3 id="glossary">Glossary</h3> <p>The terms in this glossary have been updated to reflect the changes made in V3.</p> <h4 id="abi">ABI</h4> <p>The JSON representation of the application binary interface. See the official <a rel="external" href="https://solidity.readthedocs.io/en/develop/abi-spec.html">specification</a> for more information.</p> <h4 id="address">Address</h4> <p>A public identifier for an account on a particular chain</p> <h4 id="bytecode">Bytecode</h4> <p>The set of EVM instructions as produced by a compiler. Unless otherwise specified this should be assumed to be hexadecimal encoded, representing a whole number of bytes, and <a href="https://wg-eips.ritovision.com/2678/#prefixed">prefixed</a> with <code>0x</code>.</p> <p>Bytecode can either be linked or unlinked. (see <a href="https://wg-eips.ritovision.com/2678/#linking">Linking</a>)</p> <ul> <li><strong>Unlinked Bytecode</strong>: The hexadecimal representation of a contract’s EVM instructions that contains sections of code that requires <a href="https://wg-eips.ritovision.com/2678/#linking">linking</a> for the contract to be functional.<br>The sections of code which are unlinked <strong>must</strong> be filled in with zero bytes.<br><strong>Example</strong>: <code>0x606060405260e06000730000000000000000000000000000000000000000634d536f</code></li> <li><strong>Linked Bytecode</strong>: The hexadecimal representation of a contract’s EVM instructions which has had all <a href="https://wg-eips.ritovision.com/2678/#link-reference">Link References</a> replaced with the desired <a href="https://wg-eips.ritovision.com/2678/#link-value">Link Values</a>. <strong>Example</strong>: <code>0x606060405260e06000736fe36000604051602001526040518160e060020a634d536f</code></li> </ul> <h4 id="chain-definition">Chain Definition</h4> <p>This definition originates from <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0122.mediawiki">BIP122 URI</a>.</p> <p>A URI in the format <code>blockchain://&lt;chain_id&gt;/block/&lt;block_hash&gt;</code></p> <ul> <li> <p><code>chain_id</code> is the unprefixed hexadecimal representation of the genesis hash for the chain.</p> </li> <li> <p><code>block_hash</code> is the unprefixed hexadecimal representation of the hash of a block on the chain.</p> </li> </ul> <p>A chain is considered to match a chain definition if the genesis block hash matches the <code>chain_id</code> and the block defined by <code>block_hash</code> can be found on that chain. It is possible for multiple chains to match a single URI, in which case all chains are considered valid matches</p> <h4 id="content-addressable-uri">Content Addressable URI</h4> <p>Any URI which contains a cryptographic hash which can be used to verify the integrity of the content found at the URI.</p> <p>The URI format is defined in RFC3986</p> <p>It is <strong>recommended</strong> that tools support IPFS and Swarm.</p> <h4 id="contract-alias">Contract Alias</h4> <p>This is a name used to reference a specific <a href="https://wg-eips.ritovision.com/2678/#contract-type">Contract Type</a>. Contract aliases <strong>must</strong> be unique within a single <a href="https://wg-eips.ritovision.com/2678/#package">Package</a>.</p> <p>The contract alias <strong>must</strong> use <em>one of</em> the following naming schemes:</p> <ul> <li> <p><code>&lt;contract-name&gt;</code></p> </li> <li> <p><code>&lt;contract-name&gt;&lt;identifier&gt;</code></p> </li> </ul> <p>The <code>&lt;contract-name&gt;</code> portion <strong>must</strong> be the same as the <a href="https://wg-eips.ritovision.com/2678/#contract-name">Contract Name</a> for this contract type.</p> <p>The <code>&lt;identifier&gt;</code> portion <strong>must</strong> match the regular expression <code>^[-a-zA-Z0-9]{1,256}$</code>.</p> <h4 id="contract-instance">Contract Instance</h4> <p>A contract instance a specific deployed version of a <a href="https://wg-eips.ritovision.com/2678/#contract-type">Contract Type</a>.</p> <p>All contract instances have an <a href="https://wg-eips.ritovision.com/2678/#address">Address</a> on some specific chain.</p> <h4 id="contract-instance-name">Contract Instance Name</h4> <p>A name which refers to a specific <a href="https://wg-eips.ritovision.com/2678/#contract-instance">Contract Instance</a> on a specific chain from the deployments of a single <a href="https://wg-eips.ritovision.com/2678/#package">Package</a>. This name <strong>must</strong> be unique across all other contract instances for the given chain. The name must conform to the regular expression <code>^[a-zA-Z_$][a-zA-Z0-9_$]{0,255}$</code></p> <p>In cases where there is a single deployed instance of a given <a href="https://wg-eips.ritovision.com/2678/#contract-type">Contract Type</a>, package managers <strong>should</strong> use the <a href="https://wg-eips.ritovision.com/2678/#contract-alias">Contract Alias</a> for that contract type for this name.</p> <p>In cases where there are multiple deployed instances of a given contract type, package managers <strong>should</strong> use a name which provides some added semantic information as to help differentiate the two deployed instances in a meaningful way.</p> <h4 id="contract-name">Contract Name</h4> <p>The name found in the source code that defines a specific <a href="https://wg-eips.ritovision.com/2678/#contract-type">Contract Type</a>. These names <strong>must</strong> conform to the regular expression <code>^[a-zA-Z_$][a-zA-Z0-9_$]{0,255}$</code>.</p> <p>There can be multiple contracts with the same contract name in a projects source files.</p> <h4 id="contract-type">Contract Type</h4> <p>Refers to a specific contract in the package source. This term can be used to refer to an abstract contract, a normal contract, or a library. Two contracts are of the same contract type if they have the same bytecode.</p> <p>Example:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>contract Wallet {</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>A deployed instance of the <code>Wallet</code> contract would be of of type <code>Wallet</code>.</p> <h4 id="identifier">Identifier</h4> <p>Refers generally to a named entity in the <a href="https://wg-eips.ritovision.com/2678/#package">Package</a>.</p> <p>A string matching the regular expression <code>^[a-zA-Z][-_a-zA-Z0-9]{0,255}$</code></p> <h4 id="link-reference">Link Reference</h4> <p>A location within a contract’s bytecode which needs to be linked. A link reference has the following properties.</p> <ul> <li><strong><code>offset</code></strong>: Defines the location within the bytecode where the link reference begins.</li> <li><strong><code>length</code></strong>: Defines the length of the reference.</li> <li><strong><code>name</code></strong>: (optional) A string to identify the reference.</li> </ul> <h4 id="link-value">Link Value</h4> <p>A link value is the value which can be inserted in place of a <a href="https://wg-eips.ritovision.com/2678/#link-reference">Link Reference</a></p> <h4 id="linking">Linking</h4> <p>The act of replacing <a href="https://wg-eips.ritovision.com/2678/#link-reference">Link References</a> with <a href="https://wg-eips.ritovision.com/2678/#link-value">Link Values</a> within some <a href="https://wg-eips.ritovision.com/2678/#bytecode">Bytecode</a>.</p> <h4 id="package">Package</h4> <p>Distribution of an application’s source or compiled bytecode along with metadata related to authorship, license, versioning, et al.</p> <p>For brevity, the term <strong>Package</strong> is often used metonymously to mean <a href="https://wg-eips.ritovision.com/2678/#package-manifest">Package Manifest</a>.</p> <h4 id="package-manifest">Package Manifest</h4> <p>A machine-readable description of a package.</p> <h4 id="prefixed">Prefixed</h4> <p><a href="https://wg-eips.ritovision.com/2678/#bytecode">Bytecode</a> string with leading <code>0x</code>.</p> <ul> <li><strong>Example</strong>: <code>0xdeadbeef</code></li> </ul> <h4 id="unprefixed">Unprefixed</h4> <p>Not <a href="https://wg-eips.ritovision.com/2678/#prefixed">Prefixed</a>.</p> <ul> <li><strong>Example</strong>: <code>deadbeef</code></li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="minification">Minification</h3> <p>EthPM packages are distributed as alphabetically-ordered &amp; minified JSON to ensure consistency. Since packages are published on content-addressable filesystems (eg. IPFS), this restriction guarantees that any given set of contract assets will always resolve to the same content-addressed URI.</p> <h3 id="package-names">Package Names</h3> <p>Package names are restricted to lower-case characters, numbers, and <code>-</code> to improve the readability of the package name, in turn improving the security properties for a package. A user is more likely to accurately identify their target package with this restricted set of characters, and not confuse a malicious package that disguises itself as a trusted package with similar but different characters (e.g. <code>O</code> and <code>0</code>).</p> <h3 id="bip122">BIP122</h3> <p>The BIP-122 standard has been used since EthPM v1 since it is an industry standard URI scheme for identifying different blockchains and distinguishing between forks.</p> <h3 id="compilers-1">Compilers</h3> <p>Compilers are now defined in a top-level array, simplifying the task for tooling to identify the compiler types needed to interact with or validate the contract assets. This also removes unnecessarily duplicated information, should multiple <code>contractTypes</code> share the same compiler type.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>To improve understanding and readability of the EthPM spec, the <code>manifest_version</code> field was updated to <code>manifest</code> in v3. To ensure backwards compatibility, v3 packages <strong>must</strong> define a top-level <code>"manifest"</code> with a value of <code>"ethpm/3"</code>. Additionally, <code>"manifest_version"</code> is a forbidden top-level key in v3 packages.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Using EthPM packages implicitly requires importing &amp;/or executing code written by others. The EthPM spec guarantees that when using a properly constructed and released EthPM package, the user will have the exact same code that was included in the package by the package author. However, it is impossible to guarantee that this code is safe to interact with. Therefore, it is critical that end users only interact with EthPM packages authored and released by individuals or organizations that they trust to include non-malicious 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-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-18T00:00:00+00:00 2026-02-11T14:49:27+00:00 Martin Holst Swendehttps://github.com/holiman Paweł Bylicahttps://github.com/chfast Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/2677/ <h2 id="simple-summary">Simple Summary</h2> <p>Enforce a maximum size limit (<code>max_initcode_size</code>) of <code>49152</code> (<code>0xc000</code>) for <code>initcode</code>.</p> <h2 id="abstract">Abstract</h2> <p>Enforce a maximum size limit (<code>max_initcode_size</code>) for <code>initcode</code>. If the size of <code>initcode</code> exceeds <code>max_initcode_size</code>, then contract creation fails with an out of gas error.</p> <p>Since <a href="https://wg-eips.ritovision.com/170/">EIP-170</a> was implemented, there has been a size limit of <code>24576</code> (<code>0x6000</code>) on contract code. We propose to also limit the size of executable code to <code>2x</code> the above limit, i.e. <code>49152</code> (<code>0xc000</code>).</p> <p>This also leads to two nice properties:</p> <ul> <li>instruction offset in code fits 16-bit value,</li> <li>code size fits 16-bit value.</li> </ul> <h2 id="motivation">Motivation</h2> <p>When a client executes <code>initcode</code>, the client has to perform a jumpdest analysis. In some cases, the client also performs a <code>hash</code> of the code:</p> <ul> <li>To use as a key in a mapping containing the result of a jumpdest analysis</li> <li>To use for address calculation within <code>CREATE2</code>.</li> </ul> <p>The work performed during a jumpdest analysis scales linearly with the size of the code. Currently, a transaction can expand the memory once, and reuse the same memory segment (with minor modifications) to force the client to perform a lot of analysis/hashing, leading to slow block processing.</p> <p>Historically, this was exploited in June 2017, precipitating the 1.6.5-patch release of <a rel="external" href="https://github.com/ethereum/go-ethereum/releases/tag/v1.6.5">geth</a></p> <p>The work performed during address calculation within <code>CREATE2</code> is charged in proportion with size of the code.</p> <h2 id="specification">Specification</h2> <p>There are three situations where this is applicable:</p> <ul> <li><code>CREATE</code>,</li> <li><code>CREATE2</code>,</li> <li>creation using a transaction with empty receiver.</li> </ul> <p>In all these (and future) cases, the EVM should fail with Out Of Gas error if the code has a length more than <code>max_initcode_size</code>.</p> <h2 id="rationale">Rationale</h2> <p>TBA</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a "network upgrade", since it modifies consensus-rules.</p> <h2 id="security-considerations">Security Considerations</h2> <p>For client implementations, this EIP makes attacks based on jumpdest-analysis or hashing of code less problematic, so should increase the robustness of clients.</p> <p>For layer 2, this EIP introduces failure-modes where there previously were none. There <em>could</em> exist factory-contracts which deploy multi-level contract hierarchies, such that the code for multiple contracts are included in the initcode of the first contract. The author(s) of this EIP are not aware of any such contracts.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases should include the following cases,</p> <ul> <li><code>CREATE</code>/<code>CREATE2</code>/<code>tx create</code> with <code>initcode_size</code> at <code>max_initcode_size</code></li> <li><code>CREATE</code>/<code>CREATE2</code>/<code>tx create</code> with <code>initcode_size</code> at <code>max_initcode_size+1</code></li> </ul> <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> 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-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/2681/ <h2 id="abstract">Abstract</h2> <p>Limit account nonce to be between <code>0</code> and <code>2^64-1</code>.</p> <h2 id="motivation">Motivation</h2> <p>Account nonces are currently specified to be arbitrarily long unsigned integers. Dealing with arbitrary length data in the state witnesses is not optimal, therefore this EIP will allow proofs to represent the nonce in a more optimized way.</p> <p>Additionally it could prove beneficial to transaction formats, where some improvements are potentially sought by at least three other proposals.</p> <p>Lastly, this facilitates a minor optimisation in clients, because the nonce no longer needs to be kept as a 256-bit number.</p> <h2 id="specification">Specification</h2> <p>Introduce two new restrictions retroactively from genesis:</p> <ol> <li>Consider any transaction invalid, where the nonce exceeds or equals to <code>2^64-1</code>.</li> <li>The <code>CREATE</code> and <code>CREATE2</code> instructions' execution ends with the result <code>0</code> pushed on stack, where the account nonce is <code>2^64-1</code>. Gas for initcode execution is not deducted in this case.</li> </ol> <h2 id="rationale">Rationale</h2> <ol> <li> <p>It is unlikely for any nonce to reach or exceed the proposed limit. If one would want to reach that limit via external transactions, it would cost at least <code>21000 * (2^64-1) = 387_381_625_547_900_583_915_000</code> gas.</p> </li> <li> <p>It must be noted that in the past, in the Morden testnet, each new account had a starting nonce of <code>2^20</code> in order to differentiate transactions from mainnet transactions. This mode of replay protection is out of fashion since <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> introduced a more elegant way using chain identifiers.</p> </li> <li> <p>Most clients already consider the nonce field to be 64-bit, such as go-ethereum.</p> </li> <li> <p>The reason a transaction with nonce <code>2^64-1</code> is invalid, because otherwise after inclusion the sender account's nonce would exceed <code>2^64-1</code>.</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>While this is a breaking change, no actual effect should be visible:</p> <ol> <li> <p>There is no account in the state currently which would have a nonce exceeding that value. As of November 2020, the account <code>0xea674fdde714fd979de3edf0f56aa9716b898ec8</code> is responsible for the highest account nonce at approximately 29 million.</p> </li> <li> <p>go-ethereum already has this restriction partially in place (<code>state.Account.Nonce</code> and <code>types.txdata.AccountNonce</code> it as a 64-bit number).</p> </li> </ol> <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-04-13T00:00:00+00:00 2026-02-11T14:48:26+00:00 Martin Lundfallhttps://github.com/Mrchico https://wg-eips.ritovision.com/2612/

EIP-20 approvals via EIP-712 secp256k1 signatures

<h2 id="abstract">Abstract</h2> <p>Arguably one of the main reasons for the success of <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> tokens lies in the interplay between <code>approve</code> and <code>transferFrom</code>, which allows for tokens to not only be transferred between externally owned accounts (EOA), but to be used in other contracts under application specific conditions by abstracting away <code>msg.sender</code> as the defining mechanism for token access control.</p> <p>However, a limiting factor in this design stems from the fact that the EIP-20 <code>approve</code> function itself is defined in terms of <code>msg.sender</code>. This means that user's <em>initial action</em> involving EIP-20 tokens must be performed by an EOA (<em>but see Note below</em>). If the user needs to interact with a smart contract, then they need to make 2 transactions (<code>approve</code> and the smart contract call which will internally call <code>transferFrom</code>). Even in the simple use case of paying another person, they need to hold ETH to pay for transaction gas costs.</p> <p>This ERC extends the EIP-20 standard with a new function <code>permit</code>, which allows users to modify the <code>allowance</code> mapping using a signed message, instead of through <code>msg.sender</code>.</p> <p>For an improved user experience, the signed data is structured following <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>, which already has wide spread adoption in major RPC providers.</p> <p><em><strong>Note:</strong></em> EIP-20 must be performed by an EOA unless the address owning the token is actually a contract wallet. Although contract wallets solves many of the same problems that motivates this EIP, they are currently only scarcely adopted in the ecosystem. Contract wallets suffer from a UX problem -- since they separate the EOA <code>owner</code> of the contract wallet from the contract wallet itself (which is meant to carry out actions on the <code>owner</code>s behalf and holds all of their funds), user interfaces need to be specifically designed to support them. The <code>permit</code> pattern reaps many of the same benefits while requiring little to no change in user interfaces.</p> <h2 id="motivation">Motivation</h2> <p>While EIP-20 tokens have become ubiquitous in the Ethereum ecosystem, their status remains that of second class tokens from the perspective of the protocol. The ability for users to interact with Ethereum without holding any ETH has been a long outstanding goal and the subject of many EIPs.</p> <p>So far, many of these proposals have seen very little adoption, and the ones that have been adopted (such as <a href="https://wg-eips.ritovision.com/777/">EIP-777</a>), introduce a lot of additional functionality, causing unexpected behavior in mainstream contracts.</p> <p>This ERC proposes an alternative solution which is designed to be as minimal as possible and to only address <em>one problem</em>: the lack of abstraction in the EIP-20 <code>approve</code> method.</p> <p>While it may be tempting to introduce <code>*_by_signature</code> counterparts for every EIP-20 function, they are intentionally left out of this EIP-20 for two reasons:</p> <ul> <li>the desired specifics of such functions, such as decision regarding fees for <code>transfer_by_signature</code>, possible batching algorithms, varies depending on the use case, and,</li> <li>they can be implemented using a combination of <code>permit</code> and additional helper contracts without loss of generality.</li> </ul> <h2 id="specification">Specification</h2> <p>Compliant contracts must implement 3 new functions in addition to EIP-20:</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"> permit</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-support"> uint</span><span class="z-variable"> value</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> deadline</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 class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> nonces</span><span>(</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> 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">uint</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name">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></code></pre> <p>The semantics of which are as follows:</p> <p>For all addresses <code>owner</code>, <code>spender</code>, uint256s <code>value</code>, <code>deadline</code> and <code>nonce</code>, uint8 <code>v</code>, bytes32 <code>r</code> and <code>s</code>, a call to <code>permit(owner, spender, value, deadline, v, r, s)</code> will set <code>allowance[owner][spender]</code> to <code>value</code>, increment <code>nonces[owner]</code> by 1, and 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><code>owner</code> is not the zero address.</li> <li><code>nonces[owner]</code> (before the state update) is equal to <code>nonce</code>.</li> <li><code>r</code>, <code>s</code> and <code>v</code> is a valid <code>secp256k1</code> signature from <code>owner</code> of the message:</li> </ul> <p>If any of these conditions are not met, the <code>permit</code> call must revert.</p> <pre class="giallo z-code"><code data-lang="solidity"><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;Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)&quot;</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> owner</span><span>,</span></span> <span class="giallo-l"><span> spender</span><span>,</span></span> <span class="giallo-l"><span> value</span><span>,</span></span> <span class="giallo-l"><span> nonce</span><span>,</span></span> <span class="giallo-l"><span> deadline</span><span>)</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>)</span></span></code></pre> <p>where <code>DOMAIN_SEPARATOR</code> is defined according to EIP-712. 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="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">Permit</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">owner</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">spender</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">value</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">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">deadline</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> }</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"> erc20name</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"> tokenAddress</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">owner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-variable z-other"> owner</span><span>,</span></span> <span class="giallo-l"><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 class="z-variable z-other"> spender</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-variable z-other"> value</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">deadline</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-variable z-other"> deadline</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Note that nowhere in this definition we refer to <code>msg.sender</code>. The caller of the <code>permit</code> function can be any address.</p> <h2 id="rationale">Rationale</h2> <p>The <code>permit</code> function is sufficient for enabling any operation involving EIP-20 tokens to be paid for using the token itself, rather than using ETH.</p> <p>The <code>nonces</code> mapping is given for replay protection.</p> <p>A common use case of <code>permit</code> has a relayer submit a <code>Permit</code> on behalf of the <code>owner</code>. In this scenario, the relaying party is essentially given a free option to submit or withhold the <code>Permit</code>. If this is a cause of concern, the <code>owner</code> can limit the time a <code>Permit</code> is valid for by setting <code>deadline</code> to a value in the near future. The <code>deadline</code> argument can be set to <code>uint(-1)</code> to create <code>Permit</code>s that effectively never expire.</p> <p>EIP-712 typed messages are included because of its wide spread adoption in many wallet providers.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are already a couple of <code>permit</code> functions in token contracts implemented in contracts in the wild, most notably the one introduced in the <code>dai.sol</code>.</p> <p>Its implementation differs slightly from the presentation here in that:</p> <ul> <li>instead of taking a <code>value</code> argument, it takes a bool <code>allowed</code>, setting approval to 0 or <code>uint(-1)</code>.</li> <li>the <code>deadline</code> argument is instead called <code>expiry</code>. This is not just a syntactic change, as it effects the contents of the signed message.</li> </ul> <p>There is also an implementation in the token <code>Stake</code> (Ethereum address <code>0x0Ae055097C6d159879521C384F1D2123D1f195e6</code>) with the same ABI as <code>dai</code> but with different semantics: it lets users issue "expiring approvals", that only allow <code>transferFrom</code> to occur while <code>expiry &gt;= block.timestamp</code>.</p> <p>The specification presented here is in line with the implementation in Uniswap V2.</p> <p>The requirement to revert if the permit is invalid was added when the EIP was already widely deployed, but at the moment it was consistent with all found implementations.</p> <h2 id="security-considerations">Security Considerations</h2> <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>owner != address(0)</code> to avoid <code>permit</code> from creating an approval to spend "zombie funds" belong to the zero address.</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 EIP-20 race condition for approvals (SWC-114) 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> 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-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Kelly Olsonhttps://github.com/ineffectualproperty Sean Gulleyhttps://github.com/sean-sn Simon Peffershttps://github.com/simonatsn Justin Drakehttps://github.com/justindrake Dankrad Feisthttps://github.com/dankrad https://wg-eips.ritovision.com/2565/ <h2 id="simple-summary">Simple Summary</h2> <p>Defines the gas cost of the <code>ModExp</code> (<code>0x00..05</code>) precompile.</p> <h2 id="abstract">Abstract</h2> <p>To accurately reflect the real world operational cost of the <code>ModExp</code> precompile, this EIP specifies an algorithm for calculating the gas cost. This algorithm approximates the multiplication complexity cost and multiplies that by an approximation of the iterations required to execute the exponentiation.</p> <h2 id="motivation">Motivation</h2> <p>Modular exponentiation is a foundational arithmetic operation for many cryptographic functions including signatures, VDFs, SNARKs, accumulators, and more. Unfortunately, the ModExp precompile is currently over-priced, making these operations inefficient and expensive. By reducing the cost of this precompile, these cryptographic functions become more practical, enabling improved security, stronger randomness (VDFs), and more.</p> <h2 id="specification">Specification</h2> <p>As of <code>FORK_BLOCK_NUMBER</code>, the gas cost of calling the precompile at address <code>0x0000000000000000000000000000000000000005</code> will be calculated as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def calculate_multiplication_complexity(base_length, modulus_length):</span></span> <span class="giallo-l"><span> max_length = max(base_length, modulus_length)</span></span> <span class="giallo-l"><span> words = math.ceil(max_length / 8)</span></span> <span class="giallo-l"><span> return words**2</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def calculate_iteration_count(exponent_length, exponent):</span></span> <span class="giallo-l"><span> iteration_count = 0</span></span> <span class="giallo-l"><span> if exponent_length &lt;= 32 and exponent == 0: iteration_count = 0</span></span> <span class="giallo-l"><span> elif exponent_length &lt;= 32: iteration_count = exponent.bit_length() - 1</span></span> <span class="giallo-l"><span> elif exponent_length &gt; 32: iteration_count = (8 * (exponent_length - 32)) + ((exponent &amp; (2**256 - 1)).bit_length() - 1)</span></span> <span class="giallo-l"><span> return max(iteration_count, 1)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def calculate_gas_cost(base_length, modulus_length, exponent_length, exponent):</span></span> <span class="giallo-l"><span> multiplication_complexity = calculate_multiplication_complexity(base_length, modulus_length)</span></span> <span class="giallo-l"><span> iteration_count = calculate_iteration_count(exponent_length, exponent)</span></span> <span class="giallo-l"><span> return max(200, math.floor(multiplication_complexity * iteration_count / 3))</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>After benchmarking the ModExp precompile, we discovered that it is ‘overpriced’ relative to other precompiles. We also discovered that the current gas pricing formula could be improved to better estimate the computational complexity of various ModExp input variables. The following changes improve the accuracy of the <code>ModExp</code> pricing:</p> <h3 id="1-modify-computational-complexity-formula-to-better-reflect-the-computational-complexity">1. Modify ‘computational complexity’ formula to better reflect the computational complexity</h3> <p>The complexity function defined in <a href="https://wg-eips.ritovision.com/198/">EIP-198</a> is as follow:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def mult_complexity(x):</span></span> <span class="giallo-l"><span> if x &lt;= 64: return x ** 2</span></span> <span class="giallo-l"><span> elif x &lt;= 1024: return x ** 2 // 4 + 96 * x - 3072</span></span> <span class="giallo-l"><span> else: return x ** 2 // 16 + 480 * x - 199680</span></span></code></pre> <p>where is <code>x</code> is <code>max(length_of_MODULUS, length_of_BASE)</code></p> <p>The complexity formula in <a href="https://wg-eips.ritovision.com/198/">EIP-198</a> was meant to approximate the difficulty of Karatsuba multiplication. However, we found a better approximation for modelling modular exponentiation. In the complexity formula defined in this EIP, <code>x</code> is divided by 8 to account for the number of limbs in multiprecision arithmetic. A comparison of the current ‘complexity’ function and the proposed function against the execution time can be seen below:</p> <p><img src="https://wg-eips.ritovision.com/2565/./assets/Complexity_Regression.png" alt="Option 1 Graph" /></p> <p>The complexity function defined here has a better fit vs. the execution time when compared to the <a href="https://wg-eips.ritovision.com/198/">EIP-198</a> complexity function. This better fit is because this complexity formula accounts for the use of binary exponentiation algorithms that are used by ‘bigint’ libraries for large exponents. You may also notice the regression line of the proposed complexity function bisects the test vector data points. This is because the run time varies depending on if the modulus is even or odd.</p> <h3 id="2-change-the-value-of-gquaddivisor">2. Change the value of GQUADDIVISOR</h3> <p>After changing the 'computational complexity' formula in <a href="https://wg-eips.ritovision.com/198/">EIP-198</a> to the one defined here it is necessary to change <code>QGUADDIVSOR</code> to bring the gas costs inline with their runtime. By setting the <code>QGUADDIVISOR</code> to <code>3</code> the cost of the ModExp precompile will have a higher cost (gas/second) than other precompiles such as ECRecover.</p> <p><img src="https://wg-eips.ritovision.com/2565/./assets/GQuad_Change.png" alt="Option 2 Graph" /></p> <h3 id="3-set-a-minimum-gas-cost-to-prevent-abuse">3. Set a minimum gas cost to prevent abuse</h3> <p>This prevents the precompile from underpricing small input values.</p> <h2 id="test-cases">Test Cases</h2> <p>There are no changes to the underlying interface or arithmetic algorithms, so the existing test vectors can be reused. Below is a table with the updated test vectors:</p> <table><thead><tr><th>Test Case</th><th>EIP-198 Pricing</th><th>EIP-2565 Pricing</th></tr></thead><tbody> <tr><td>modexp_nagydani_1_square</td><td>204</td><td>200</td></tr> <tr><td>modexp_nagydani_1_qube</td><td>204</td><td>200</td></tr> <tr><td>modexp_nagydani_1_pow0x10001</td><td>3276</td><td>341</td></tr> <tr><td>modexp_nagydani_2_square</td><td>665</td><td>200</td></tr> <tr><td>modexp_nagydani_2_qube</td><td>665</td><td>200</td></tr> <tr><td>modexp_nagydani_2_pow0x10001</td><td>10649</td><td>1365</td></tr> <tr><td>modexp_nagydani_3_square</td><td>1894</td><td>341</td></tr> <tr><td>modexp_nagydani_3_qube</td><td>1894</td><td>341</td></tr> <tr><td>modexp_nagydani_3_pow0x10001</td><td>30310</td><td>5461</td></tr> <tr><td>modexp_nagydani_4_square</td><td>5580</td><td>1365</td></tr> <tr><td>modexp_nagydani_4_qube</td><td>5580</td><td>1365</td></tr> <tr><td>modexp_nagydani_4_pow0x10001</td><td>89292</td><td>21845</td></tr> <tr><td>modexp_nagydani_5_square</td><td>17868</td><td>5461</td></tr> <tr><td>modexp_nagydani_5_qube</td><td>17868</td><td>5461</td></tr> <tr><td>modexp_nagydani_5_pow0x10001</td><td>285900</td><td>87381</td></tr> </tbody></table> <h2 id="implementations">Implementations</h2> <p><a rel="external" href="https://github.com/ethereum/go-ethereum/pull/21607">Geth</a></p> <p><a rel="external" href="https://gist.github.com/ineffectualproperty/60e34f15c31850c5b60c8cf3a28cd423">Python</a></p> <h2 id="security-considerations">Security Considerations</h2> <p>The biggest security consideration for this EIP is creating a potential DoS vector by making ModExp operations too inexpensive relative to their computation time.</p> <h2 id="references">References</h2> <p><a href="https://wg-eips.ritovision.com/198/">EIP-198</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-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-22T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Mudgehttps://github.com/mudgen https://wg-eips.ritovision.com/2535/

Create modular smart contract systems that can be extended after deployment.

<h2 id="abstract">Abstract</h2> <img align="right" src="./assets/diamond.svg" width="230" height="230" alt="Diamonds contract structure"> <p>This proposal standardizes diamonds, which are modular smart contract systems that can be upgraded/extended after deployment, and have virtually no size limit. More technically, a <strong>diamond</strong> is a contract with external functions that are supplied by contracts called <strong>facets</strong>. Facets are separate, independent contracts that can share internal functions, libraries, and state variables.</p> <h2 id="motivation">Motivation</h2> <p>There are a number of different reasons to use diamonds. Here are some of them:</p> <ol> <li><strong>A single address for unlimited contract functionality.</strong> Using a single address for contract functionality makes deployment, testing and integration with other smart contracts, software and user interfaces easier.</li> <li><strong>Your contract exceeds the 24KB maximum contract size.</strong> You may have related functionality that it makes sense to keep in a single contract, or at a single contract address. A diamond does not have a max contract size.</li> <li><strong>A diamond provides a way to organize contract code and data.</strong> You may want to build a contract system with a lot of functionality. A diamond provides a systematic way to isolate different functionality and connect them together and share data between them as needed in a gas-efficient way.</li> <li><strong>A diamond provides a way to upgrade functionality.</strong> Upgradeable diamonds can be upgraded to add/replace/remove functionality. Because diamonds have no max contract size, there is no limit to the amount of functionality that can be added to diamonds over time. Diamonds can be upgraded without having to redeploy existing functionality. Parts of a diamond can be added/replaced/removed while leaving other parts alone.</li> <li><strong>A diamond can be immutable.</strong> It is possible to deploy an immutable diamond or make an upgradeable diamond immutable at a later time.</li> <li><strong>A diamond can reuse deployed contracts.</strong> Instead of deploying contracts to a blockchain, existing already deployed, onchain contracts can be used to create diamonds. Custom diamonds can be created from existing deployed contracts. This enables the creation of on-chain smart contract platforms and libraries.</li> </ol> <p>This standard is an improvement of <a href="https://wg-eips.ritovision.com/1538/">EIP-1538</a>. The same motivations of that standard apply to this standard.</p> <p>A deployed facet can be used by any number of diamonds.</p> <p>The diagram below shows two diamonds using the same two facets.</p> <ul> <li><code>FacetA</code> is used by <code>Diamond1</code></li> <li><code>FacetA</code> is used by <code>Diamond2</code></li> <li><code>FacetB</code> is used by <code>Diamond1</code></li> <li><code>FacetB</code> is used by <code>Diamond2</code></li> </ul> <img src="./assets/facetreuse.png" alt="Facet reuse"> <h3 id="upgradeable-diamond-vs-centralized-private-database">Upgradeable Diamond vs. Centralized Private Database</h3> <p>Why have an upgradeable diamond instead of a centralized, private, mutable database?</p> <ol> <li>Decentralized Autonomous Organizations (DAOs) and other governance systems can be used to upgrade diamonds.</li> <li>Wide interaction and integration with the Ethereum ecosystem.</li> <li>With open storage data and verified source code it is possible to show a provable history of trustworthiness.</li> <li>With openness bad behavior can be spotted and reported when it happens.</li> <li>Independent security and domain experts can review the change history of contracts and vouch for their history of trustworthiness.</li> <li>It is possible for an upgradeable diamond to become immutable and trustless.</li> </ol> <h3 id="some-diamond-benefits">Some Diamond Benefits</h3> <ol> <li>A stable contract address that provides needed functionality.</li> <li>A single address with the functionality of multiple contracts (facets) that are independent from each other but can share internal functions, libraries and state variables.</li> <li>Emitting events from a single address can simplify event handling.</li> <li>A way to add, replace and remove multiple external functions atomically (in the same transaction).</li> <li>Fine-grained upgrades, so you can change just the parts of a diamond that need to be changed.</li> <li>Have greater control over when and what functions exist.</li> <li>Decentralized Autonomous Organizations (DAOs), multisig contracts and other governance systems can be used to upgrade diamonds.</li> <li>An event that shows what functions are added, replaced and removed.</li> <li>The ability to show all changes made to a diamond.</li> <li>Increase trust over time by showing all changes made to a diamond.</li> <li>A way to look at a diamond to see its current facets and functions.</li> <li>Have an immutable, trustless diamond.</li> <li>Solves the 24KB maximum contract size limitation. Diamonds can be any size.</li> <li>Separate functionality can be implemented in separate facets and used together in a diamond.</li> <li>Diamonds can be created from already deployed, existing onchain contracts.</li> <li>Larger contracts have to reduce their size by removing error messages and other things. You can keep your full functionality that you need by implementing a diamond.</li> <li>Enables zero, partial or full diamond immutability as desired, and when desired.</li> <li>The ability to develop and improve an application over time with an upgradeable diamond and then make it immutable and trustless if desired.</li> <li>Develop incrementally and let your diamond grow with your application.</li> <li>Upgrade diamonds to fix bugs, add functionality and implement new standards.</li> <li>Organize your code with a diamond and facets.</li> <li>Diamonds can be large (have many functions) but still be modular because they are compartmented with facets.</li> <li>Contract architectures that call multiple contracts in a single transaction can save gas by condensing those contracts into a single diamond and accessing state variables directly.</li> <li>Save gas by converting external functions to internal functions. This done by sharing internal functions between facets.</li> <li>Save gas by creating external functions for gas-optimized specific use cases, such as bulk transfers.</li> <li>Diamonds are designed for tooling and user-interface software.</li> </ol> <h2 id="specification">Specification</h2> <h3 id="terms">Terms</h3> <ol> <li>A <strong>diamond</strong> is a facade smart contract that <code>delegatecall</code>s into its facets to execute function calls. A diamond is stateful. Data is stored in the contract storage of a diamond.</li> <li>A <strong>facet</strong> is a stateless smart contract or Solidity library with external functions. A facet is deployed and one or more of its functions are added to one or more diamonds. A facet does not store data within its own contract storage but it can define state and read and write to the storage of one or more diamonds. The term facet comes from the diamond industry. It is a side, or flat surface of a diamond.</li> <li>A <strong>loupe facet</strong> is a facet that provides introspection functions. In the diamond industry, a loupe is a magnifying glass that is used to look at diamonds.</li> <li>An <strong>immutable function</strong> is an external function that cannot be replaced or removed (because it is defined directly in the diamond, or because the diamond's logic does not allow it to be modified).</li> <li>A <strong>mapping</strong> for the purposes of this EIP is an association between two things and does not refer to a specific implementation.</li> </ol> <p>The term <strong>contract</strong> is used loosely to mean a smart contract or deployed Solidity library.</p> <p>When this EIP uses <strong>function</strong> without specifying internal or external, it means external function.</p> <p>In this EIP the information that applies to external functions also applies to public functions.</p> <h3 id="overview">Overview</h3> <p>A diamond calls functions from its facets using <code>delegatecall</code>.</p> <p>In the diamond industry diamonds are created and shaped by being cut, creating facets. In this standard diamonds are cut by adding, replacing or removing functions from facets.</p> <h3 id="a-note-on-implementing-interfaces">A Note on Implementing Interfaces</h3> <p>Because of the nature of diamonds, a diamond can implement an interface in one of two ways: directly (<code>contract Contract is Interface</code>), or by adding functions to it from one or more facets. For the purposes of this proposal, when a diamond is said to implement an interface, either method of implementation is permitted.</p> <h3 id="fallback-function">Fallback Function</h3> <p>When an external function is called on a diamond its fallback function is executed. The fallback function determines which facet to call based on the first four bytes of the call data (known as the function selector) and executes that function from the facet using <code>delegatecall</code>.</p> <p>A diamond's fallback function and <code>delegatecall</code> enable a diamond to execute a facet's function as if it was implemented by the diamond itself. The <code>msg.sender</code> and <code>msg.value</code> values do not change and only the diamond's storage is read and written to.</p> <p>Here is an illustrative example of how a diamond's fallback function might be implemented:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Find facet for function that is called and execute the</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> function if a facet is found and return any value.</span></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-comment"> //</span><span class="z-comment"> get facet from function selector</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> facet </span><span class="z-keyword">=</span><span> selectorTofacet</span><span>[</span><span class="z-variable z-language">msg</span><span>.</span><span>sig</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>facet </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"> Execute external function from facet using delegatecall and return any value.</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> copy function selector and any arguments</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-comment"> //</span><span class="z-comment"> execute function call using the facet</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> facet</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-comment"> //</span><span class="z-comment"> get any return value</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 class="z-comment"> //</span><span class="z-comment"> return any return value or error back to the caller</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 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></span> <span class="giallo-l"><span> default </span><span>{</span><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></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This diagram shows the structure of a diamond:</p> <img src="./assets/DiamondDiagram.png" alt="Mapping facets and storage"> <h3 id="storage">Storage</h3> <p>A state variable or storage layout organizational pattern is needed because Solidity's builtin storage layout system doesn't support proxy contracts or diamonds. The particular layout of storage is not defined in this EIP, but may be defined by later proposals. Examples of storage layout patterns that work with diamonds are <a href="https://wg-eips.ritovision.com/2535/./assets/storage-examples/DiamondStorage.sol">Diamond Storage</a> and <a href="https://wg-eips.ritovision.com/2535/./assets/storage-examples/AppStorage.sol">AppStorage</a>.</p> <p>Facets can share state variables by using the same structs at the same storage positions. Facets can share internal functions and libraries by inheriting the same contracts or using the same libraries. In these ways facets are separate, independent units but can share state and functionality.</p> <p>The diagram below shows facets with their own data and data shared between them.</p> <p>Notice that all data is stored in the diamond's storage, but different facets have different access to data.</p> <p>In this diagram</p> <ul> <li>Only <code>FacetA</code> can access <code>DataA</code></li> <li>Only <code>FacetB</code> can access <code>DataB</code></li> <li>Only the diamond's own code can access <code>DataD</code>.</li> <li><code>FacetA</code> and <code>FacetB</code> share access to <code>DataAB</code>.</li> <li>The diamond's own code, <code>FacetA</code> and <code>FacetB</code> share access to <code>DataABD</code>.</li> </ul> <img src="./assets/diamondstorage1.png" alt="Mapping code, data, and facets"> <h3 id="solidity-libraries-as-facets">Solidity Libraries as Facets</h3> <p>Smart contracts or deployed Solidity libraries can be facets of diamonds.</p> <p>Only Solidity libraries that have one or more external functions can be deployed to a blockchain and be a facet.</p> <p>Solidity libraries that contain internal functions only cannot be deployed and cannot be a facet. Internal functions from Solidity libraries are included in the bytecode of facets and contracts that use them. Solidity libraries with internal functions only are useful for sharing internal functions between facets.</p> <p>Solidity library facets have a few properties that match their use as facets:</p> <ul> <li>They cannot be deleted.</li> <li>They are stateless. They do not have contract storage.</li> <li>Their syntax prevents declaring state variables outside Diamond Storage.</li> </ul> <h3 id="adding-replacing-removing-functions">Adding/Replacing/Removing Functions</h3> <h4 id="idiamond-interface"><code>IDiamond</code> Interface</h4> <p>All diamonds must implement the <code>IDiamond</code> interface.</p> <p>During the deployment of a diamond any immutable functions and any external functions added to the diamond must be emitted in the <code>DiamondCut</code> event.</p> <p><strong>A <code>DiamondCut</code> event must be emitted any time external functions are added, replaced, or removed.</strong> This applies to all upgrades, all functions changes, at any time, whether through <code>diamondCut</code> or not.</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"> IDiamond</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> FacetCutAction</span><span> {</span><span class="z-variable z-other z-enummember">Add</span><span>,</span><span class="z-variable z-other z-enummember"> Replace</span><span>,</span><span class="z-variable z-other z-enummember"> Remove</span><span>}</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Add=0, Replace=1, Remove=2</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"> FacetCut</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> facetAddress</span><span>;</span></span> <span class="giallo-l"><span> FacetCutAction action</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span>[</span><span>]</span><span> functionSelectors</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"> DiamondCut</span><span>(</span><span class="z-variable">FacetCut</span><span>[</span><span>]</span><span class="z-variable"> _diamondCut</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _init</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> _calldata</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>DiamondCut</code> event records all function changes to a diamond.</p> <h4 id="idiamondcut-interface"><code>IDiamondCut</code> Interface</h4> <p>A diamond contains within it a mapping of function selectors to facet addresses. Functions are added/replaced/removed by modifying this mapping.</p> <p>Diamonds should implement the <code>IDiamondCut</code> interface if after their deployment they allow modifications to their function selector mapping.</p> <p>The <code>diamondCut</code> function updates any number of functions from any number of facets in a single transaction. Executing all changes within a single transaction prevents data corruption which could occur in upgrades done over multiple transactions.</p> <p><code>diamondCut</code> is specified for the purpose of interoperability. Diamond tools, software and user-interfaces should expect and use the standard <code>diamondCut</code> function.</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"> IDiamondCut</span><span class="z-storage"> is</span><span class="z-entity z-name"> IDiamond</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"> Add/replace/remove any number of functions and optionally execute</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> a function with delegatecall</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _diamondCut</span><span class="z-comment"> Contains the facet addresses and function selectors</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _init</span><span class="z-comment"> The address of the contract or facet to execute _calldata</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _calldata</span><span class="z-comment"> A function call, including function selector and arguments</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> _calldata is executed with delegatecall on _init</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> diamondCut</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> FacetCut</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _diamondCut</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _init</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 z-parameter z-function"> _calldata</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> <p>The <code>_diamondCut</code> argument is an array of <code>FacetCut</code> structs.</p> <p>Each <code>FacetCut</code> struct contains a facet address and array of function selectors that are updated in a diamond.</p> <p>For each <code>FacetCut</code> struct:</p> <ul> <li>If the <code>action</code> is <code>Add</code>, update the function selector mapping for each <code>functionSelectors</code> item to the <code>facetAddress</code>. If any of the <code>functionSelectors</code> had a mapped facet, revert instead.</li> <li>If the <code>action</code> is <code>Replace</code>, update the function selector mapping for each <code>functionSelectors</code> item to the <code>facetAddress</code>. If any of the <code>functionSelectors</code> had a value equal to <code>facetAddress</code> or the selector was unset, revert instead.</li> <li>If the <code>action</code> is <code>Remove</code>, remove the function selector mapping for each <code>functionSelectors</code> item. If any of the <code>functionSelectors</code> were previously unset, revert instead.</li> </ul> <p>Any attempt to replace or remove an immutable function must revert.</p> <p>Being intentional and explicit about adding/replacing/removing functions helps catch and prevent upgrade mistakes.</p> <h5 id="executing-calldata">Executing <code>_calldata</code></h5> <p>After adding/replacing/removing functions the <code>_calldata</code> argument is executed with <code>delegatecall</code> on <code>_init</code>. This execution is done to initialize data or setup or remove anything needed or no longer needed after adding, replacing and/or removing functions.</p> <p>If the <code>_init</code> value is <code>address(0)</code> then <code>_calldata</code> execution is skipped. In this case <code>_calldata</code> can contain 0 bytes or custom information.</p> <h3 id="inspecting-facets-functions">Inspecting Facets &amp; Functions</h3> <blockquote> <p>A loupe is a small magnifying glass used to look at diamonds.</p> </blockquote> <p>Diamonds must support inspecting facets and functions by implementing the <code>IDiamondLoupe</code> interface.</p> <h4 id="idiamondloupe-interface"><code>IDiamondLoupe</code> Interface</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> A loupe is a small magnifying glass used to look at diamonds.</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> These functions look at diamonds</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IDiamondLoupe</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Facet</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> facetAddress</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span>[</span><span>]</span><span> functionSelectors</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"> @notice</span><span class="z-comment"> Gets all facet addresses and their four byte function selectors.</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"> facets_</span><span class="z-comment"> Facet</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> facets</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-storage z-type">Facet</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> facets_</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 all the function selectors supported by a specific facet.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _facet</span><span class="z-comment"> The facet 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"> facetFunctionSelectors_</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> facetFunctionSelectors</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _facet</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">bytes4</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> facetFunctionSelectors_</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 all the facet addresses used by a diamond.</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"> facetAddresses_</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> facetAddresses</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 class="z-variable"> facetAddresses_</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 facet that supports the given selector.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> If facet is not found return 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"> _functionSelector</span><span class="z-comment"> The function selector.</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"> facetAddress_</span><span class="z-comment"> The facet address.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> facetAddress</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable z-parameter z-function"> _functionSelector</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"> facetAddress_</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>See a <a href="https://wg-eips.ritovision.com/2535/#reference-implementation">reference implementation</a> to see how this can be implemented.</p> <p>The loupe functions can be used in user-interface software. A user interface calls these functions to provide information about and visualize diamonds.</p> <p>The loupe functions can be used in deployment functionality, upgrade functionality, testing and other software.</p> <h3 id="implementation-points">Implementation Points</h3> <p>A diamond must implement the following:</p> <ol> <li>A diamond contains a fallback function and zero or more immutable functions that are defined within it.</li> <li>A diamond associates function selectors with facets.</li> <li>When a function is called on a diamond it executes immediately if it is an "immutable function" defined directly in the diamond. Otherwise the diamond's fallback function is executed. The fallback function finds the facet associated with the function and executes the function using <code>delegatecall</code>. If there is no facet for the function then optionally a default function may be executed. If there is no facet for the function and no default function and no other mechanism to handle it then execution reverts.</li> <li>Each time functions are added, replaced or removed a <code>DiamondCut</code> event is emitted to record it.</li> <li>A diamond implements the DiamondLoupe interface.</li> <li>All immutable functions must be emitted in the <code>DiamondCut</code> event as new functions added. And the loupe functions must return information about immutable functions if they exist. The facet address for an immutable function is the diamond's address. Any attempt to delete or replace an immutable function must revert.</li> </ol> <p>A diamond may implement the following:</p> <ol> <li><a href="https://wg-eips.ritovision.com/165/">EIP-165</a>'s <code>supportsInterface</code>. If a diamond has the <code>diamondCut</code> function then the interface ID used for it is <code>IDiamondCut.diamondCut.selector</code>. The interface ID used for the diamond loupe interface is <code>IDiamondLoupe.facets.selector ^ IDiamondLoupe.facetFunctionSelectors.selector ^ IDiamondLoupe.facetAddresses.selector ^ IDiamondLoupe.facetAddress.selector</code>.</li> </ol> <p>The diamond address is the address that users interact with. The diamond address does not change. Only facet addresses can change by using the <code>diamondCut</code> function, or other function.</p> <h2 id="rationale">Rationale</h2> <h3 id="using-function-selectors">Using Function Selectors</h3> <p>User interface software can be used to retrieve function selectors and facet addresses from a diamond in order show what functions a diamond has.</p> <p>This standard is designed to make diamonds work well with user-interface software. Function selectors with the ABI of a contract provide enough information about functions to be useful for user-interface software.</p> <h3 id="gas-considerations">Gas Considerations</h3> <p>Delegating function calls does have some gas overhead. This is mitigated in several ways:</p> <ol> <li>Because diamonds do not have a max size limitation it is possible to add gas optimizing functions for use cases. For example someone could use a diamond to implement the <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> standard and implement batch transfer functions to reduce gas (and make batch transfers more convenient).</li> <li>Some contract architectures require calling multiple contracts in one transaction. Gas savings can be realized by condensing those contracts into a single diamond and accessing contract storage directly.</li> <li>Facets can contain few external functions, reducing gas costs. Because it costs more gas to call a function in a contract with many functions than a contract with few functions.</li> <li>The Solidity optimizer can be set to a high setting causing more bytecode to be generated but the facets will use less gas when executed.</li> </ol> <h3 id="versions-of-functions">Versions of Functions</h3> <p>Software or a user can verify what version of a function is called by getting the facet address of the function. This can be done by calling the <code>facetAddress</code> function from the <code>IDiamondLoupe</code> interface. This function takes a function selector as an argument and returns the facet address where it is implemented.</p> <h3 id="default-function">Default Function</h3> <p>Solidity provides the <code>fallback</code> function so that specific functionality can be executed when a function is called on a contract that does not exist in the contract. This same behavior can optionally be implemented in a diamond by implementing and using a default function, which is a function that is executed when a function is called on a diamond that does not exist in the diamond.</p> <p>A default function can be implemented a number of ways and this standard does not specify how it must be implemented.</p> <h3 id="loupe-functions-diamondcut-event">Loupe Functions &amp; <code>DiamondCut</code> Event</h3> <p>To find out what functions a regular contract has it is only necessary to look at its verified source code.</p> <p>The verified source code of a diamond does not include what functions it has so a different mechanism is needed.</p> <p>A diamond has four standard functions called the loupe functions that are used to show what functions a diamond has.</p> <p>The loupe functions can be used for many things including:</p> <ol> <li>To show all functions used by a diamond.</li> <li>To query services like Etherscan or files to retrieve and show all source code used by a diamond.</li> <li>To query services like Etherscan or files to retrieve ABI information for a diamond.</li> <li>To test or verify that a transaction that adds/replaces/removes functions on a diamond succeeded.</li> <li>To find out what functions a diamond has before calling functions on it.</li> <li>To be used by tools and programming libraries to deploy and upgrade diamonds.</li> <li>To be used by user interfaces to show information about diamonds.</li> <li>To be used by user interfaces to enable users to call functions on diamonds.</li> </ol> <p>Diamonds support another form of transparency which is a historical record of all upgrades on a diamond. This is done with the <code>DiamondCut</code> event which is used to record all functions that are added, replaced or removed on a diamond.</p> <h3 id="sharing-functions-between-facets">Sharing Functions Between Facets</h3> <p>In some cases it might be necessary to call a function defined in a different facet. Here are ways to do this:</p> <ol> <li>Copy internal function code in one facet to the other facet.</li> <li>Put common internal functions in a contract that is inherited by multiple facets.</li> <li>Put common internal functions in a Solidity library and use the library in facets.</li> <li>A type safe way to call an external function defined in another facet is to do this: <code>MyOtherFacet(address(this)).myFunction(arg1, arg2)</code></li> <li>A more gas-efficient way to call an external function defined in another facet is to use delegatecall. Here is an example of doing that:</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>DiamondStorage </span><span class="z-storage z-type">storage</span><span> ds </span><span class="z-keyword">=</span><span class="z-entity z-name"> diamondStorage</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support">bytes4</span><span> functionSelector </span><span class="z-keyword">=</span><span class="z-support"> bytes4</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-string">&quot;myFunction(uint256)&quot;</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> get facet address of function</span></span> <span class="giallo-l"><span class="z-support">address</span><span> facet </span><span class="z-keyword">=</span><span> ds</span><span>.</span><span>selectorToFacet</span><span>[</span><span>functionSelector</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> myFunctionCall </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span>functionSelector</span><span>,</span><span class="z-constant"> 4</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-support"> bytes</span><span class="z-storage z-type"> memory</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span class="z-support"> address</span><span>(</span><span>facet</span><span>)</span><span>.</span><span class="z-entity z-name">delegatecall</span><span>(</span><span>myFunctionCall</span><span>)</span><span>;</span></span></code></pre> <ol start="6"> <li>Instead of calling an external function defined in another facet you can instead create an internal function version of the external function. Add the internal version of the function to the facet that needs to use it.</li> </ol> <h3 id="facets-can-be-reusable-and-composable">Facets can be Reusable and Composable</h3> <p>A deployed facet can be used by any number of diamonds.</p> <p>Different combinations of facets can be used with different diamonds.</p> <p>It is possible to create and deploy a set of facets that are reused by different diamonds over time.</p> <p>The ability to use the same deployed facets for many diamonds reduces deployment costs.</p> <p>It is possible to implement facets in a way that makes them usable/composable/compatible with other facets. It is also possible to implement facets in a way that makes them not usable/composable/compatible with other facets.</p> <p>A function signature is the name of a function and its parameter types. Example function signature: <code>myfunction(uint256)</code>. A limitation is that two external functions with the same function signature can’t be added to the same diamond at the same time because a diamond, or any contract, cannot have two external functions with the same function signature.</p> <p>All the functions of a facet do not have to be added to a diamond. Some functions in a facet can be added to a diamond while other functions in the facet are not added to the diamond.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard makes upgradeable diamonds compatible with future standards and functionality because new functions can be added and existing functions can be replaced or removed.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>All the Solidity code for a complete reference implementation has been put in a single file here: <a href="https://wg-eips.ritovision.com/2535/./assets/reference/Diamond.sol">Diamond.sol</a></p> <p>The same reference implementation has been organized into multiple files and directories and also includes a deployment script and tests. Download it as a zip file: <a href="https://wg-eips.ritovision.com/2535/./assets/reference/EIP2535-Diamonds-Reference-Implementation.zip"><code>EIP2535-Diamonds-Reference-Implementation.zip</code></a></p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="ownership-and-authentication">Ownership and Authentication</h3> <blockquote> <p><strong>Note:</strong> The design and implementation of diamond ownership/authentication is <strong>not</strong> part of this standard. The examples given in this standard and in the reference implementation are just <strong>examples</strong> of how it could be done.</p> </blockquote> <p>It is possible to create many different authentication or ownership schemes with this proposal. Authentication schemes can be very simple or complex, fine grained or coarse. This proposal does not limit it in any way. For example ownership/authentication could be as simple as a single account address having the authority to add/replace/remove functions. Or a decentralized autonomous organization could have the authority to only add/replace/remove certain functions.</p> <p>Consensus functionality could be implemented such as an approval function that multiple different people call to approve changes before they are executed with the <code>diamondCut</code> function. These are just examples.</p> <p>The development of standards and implementations of ownership, control and authentication of diamonds is encouraged.</p> <h3 id="arbitrary-execution-with-diamondcut">Arbitrary Execution with <code>diamondCut</code></h3> <p>The <code>diamondCut</code> function allows arbitrary execution with access to the diamond's storage (through <code>delegatecall</code>). Access to this function must be restricted carefully.</p> <h3 id="do-not-self-destruct">Do Not Self Destruct</h3> <p>Use of <code>selfdestruct</code> in a facet is heavily discouraged. Misuse of it can delete a diamond or a facet.</p> <h3 id="function-selector-clash">Function Selector Clash</h3> <p>A function selector clash occurs when two different function signatures hash to the same four-byte hash. This has the unintended consequence of replacing an existing function in a diamond when the intention was to add a new function. This scenario is not possible with a properly implemented <code>diamondCut</code> function because it prevents adding function selectors that already exist.</p> <h3 id="transparency">Transparency</h3> <p>Diamonds emit an event every time one or more functions are added, replaced or removed. All source code can be verified. This enables people and software to monitor changes to a contract. If any bad acting function is added to a diamond then it can be seen.</p> <p>Security and domain experts can review the history of change of a diamond to detect any history of foul play.</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 Alex Vlasovhttps://github.com/shamatar Kelly Olsonhttps://github.com/ineffectualproperty Alex Stokeshttps://github.com/ralexstokes Antonio Sansohttps://github.com/asanso https://wg-eips.ritovision.com/2537/

Adds operation on BLS12-381 curve as a precompile in a set necessary to efficiently perform operations such as BLS signature verification.

<h2 id="abstract">Abstract</h2> <p>Add functionality to efficiently perform operations over the BLS12-381 curve, including those for BLS signature verification.</p> <p>Along with the curve arithmetic, multi-scalar-multiplication operations are included to efficiently aggregate public keys or individual signer's signatures during BLS signature verification.</p> <h2 id="motivation">Motivation</h2> <p>The 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.</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>BLS12_G1ADD</td><td>0x0b</td><td>precompile address</td></tr> <tr><td>BLS12_G1MSM</td><td>0x0c</td><td>precompile address</td></tr> <tr><td>BLS12_G2ADD</td><td>0x0d</td><td>precompile address</td></tr> <tr><td>BLS12_G2MSM</td><td>0x0e</td><td>precompile address</td></tr> <tr><td>BLS12_PAIRING_CHECK</td><td>0x0f</td><td>precompile address</td></tr> <tr><td>BLS12_MAP_FP_TO_G1</td><td>0x10</td><td>precompile address</td></tr> <tr><td>BLS12_MAP_FP2_TO_G2</td><td>0x11</td><td>precompile address</td></tr> </tbody></table> <p>We introduce <em>seven</em> separate precompiles to perform the following operations:</p> <ul> <li>BLS12_G1ADD - to perform point addition in G1 (curve over base prime field) with a gas cost of <code>375</code> gas</li> <li>BLS12_G1MSM - to perform multi-scalar-multiplication (MSM) in G1 (curve over base prime field) with a gas cost formula defined in the corresponding section</li> <li>BLS12_G2ADD - to perform point addition in G2 (curve over quadratic extension of the base prime field) with a gas cost of <code>600</code> gas</li> <li>BLS12_G2MSM - to perform multi-scalar-multiplication (MSM) in G2 (curve over quadratic extension of the base prime field) with a gas cost formula defined in the corresponding section</li> <li>BLS12_PAIRING_CHECK - to perform a pairing operations between a set of <em>pairs</em> of (G1, G2) points a gas cost formula defined in the corresponding section</li> <li>BLS12_MAP_FP_TO_G1 - maps base field element into the G1 point with a gas cost of <code>5500</code> gas</li> <li>BLS12_MAP_FP2_TO_G2 - maps extension field element into the G2 point with a gas cost of <code>23800</code> gas</li> </ul> <p>A mapping functions specification is included as a separate <a href="https://wg-eips.ritovision.com/2537/assets/field_to_curve/">document</a>. This mapping function does NOT perform mapping of the byte string into a field element (as it can be implemented in many different ways and can be efficiently performed in EVM), but only does field arithmetic to map a field element into a curve point. Such functionality is required for signature schemes.</p> <h3 id="curve-parameters">Curve parameters</h3> <p>The BLS12 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 = p = 0x1a0111ea397fe69a4b1ba7b6434bacd764774b84f38512bf6730d2a0f6b0f6241eabfffeb153ffffb9feffffffffaaab</span></span> <span class="giallo-l"><span>Fp - finite field of size p</span></span> <span class="giallo-l"><span>Curve Fp equation: Y^2 = X^3+B (mod p)</span></span> <span class="giallo-l"><span>B coefficient = 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004</span></span> <span class="giallo-l"><span>Main subgroup order = q = 0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001</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 = nr2 = 0x1a0111ea397fe69a4b1ba7b6434bacd764774b84f38512bf6730d2a0f6b0f6241eabfffeb153ffffb9feffffffffaaaa</span></span> <span class="giallo-l"><span>Fp2 is Fp[X]/(X^2-nr2)</span></span> <span class="giallo-l"><span>Curve Fp2 equation: Y^2 = X^3 + B*(v+1) where v is the square root of nr2</span></span> <span class="giallo-l"><span>Fp6/Fp12 construction:</span></span> <span class="giallo-l"><span>Fp2 cubic non-residue c0 = 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001</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: M</span></span> <span class="giallo-l"><span>B coefficient for twist c0 = 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004</span></span> <span class="giallo-l"><span>B coefficient for twist c1 = 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004</span></span> <span class="giallo-l"><span>Generators:</span></span> <span class="giallo-l"><span>H1:</span></span> <span class="giallo-l"><span>X = 0x17f1d3a73197d7942695638c4fa9ac0fc3688c4f9774b905a14e3a3f171bac586c55e83ff97a1aeffb3af00adb22c6bb</span></span> <span class="giallo-l"><span>Y = 0x08b3f481e3aaa0f1a09e30ed741d8ae4fcf5e095d5d00af600db18cb2c04b3edd03cc744a2888ae40caa232946c5e7e1</span></span> <span class="giallo-l"><span>H2:</span></span> <span class="giallo-l"><span>X c0 = 0x024aa2b2f08f0a91260805272dc51051c6e47ad4fa403b02b4510b647ae3d1770bac0326a805bbefd48056c8c121bdb8</span></span> <span class="giallo-l"><span>X c1 = 0x13e02b6052719f607dacd3a088274f65596bd0d09920b61ab5da61bbdc7f5049334cf11213945d57e5ac7d055d042b7e</span></span> <span class="giallo-l"><span>Y c0 = 0x0ce5d527727d6e118cc9cdc6da2e351aadfd9baa8cbdd3a76d429a695160d12c923ac9cc3baca289e193548608b82801</span></span> <span class="giallo-l"><span>Y c1 = 0x0606c4a02ea734cc32acd2b02bc28b99cb3e287e85a763af267492ab572e99ab3f370d275cec1da1aaa9075ff05f79be</span></span> <span class="giallo-l"><span>Pairing parameters:</span></span> <span class="giallo-l"><span>|x| (miller loop scalar) = 0xd201000000010000</span></span> <span class="giallo-l"><span>x is negative = true</span></span></code></pre> <p>One should note that base field modulus <code>p</code> is equal to <code>3 mod 4</code> that allows an efficient square root extraction, although as described below gas cost of decompression is larger than gas cost of supplying decompressed point data in <code>calldata</code>.</p> <h3 id="fields-and-groups">Fields and Groups</h3> <p>Field Fp is defined as the finite field of size <code>p</code> with elements represented as integers between 0 and p-1 (both inclusive).</p> <p>Field Fp2 is defined as <code>Fp[X]/(X^2-nr2)</code> with elements <code>el = c0 + c1 * v</code>, where <code>v</code> is the formal square root of <code>nr2</code> represented as integer pairs <code>(c0,c1)</code>.</p> <p>Group G1 is defined as a set of Fp pairs (points) <code>(x,y)</code> such that either <code>(x,y)</code> is <code>(0,0)</code> or <code>x,y</code> satisfy the curve Fp equation.</p> <p>Group G2 is defined as a set of Fp2 pairs (points) <code>(x',y')</code> such that either <code>(x,y)</code> is <code>(0,0)</code> or <code>(x',y')</code> satisfy the curve Fp2 equation.</p> <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>In order to produce inputs to an operation, one encodes elements of the base field and the extension field.</p> <p>A base field element (Fp) is encoded as <code>64</code> bytes by performing the BigEndian encoding of the corresponding (unsigned) integer. Due to the size of <code>p</code>, the 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> with the latter assuming the BigEndian encoding). The 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 the formal square root of a 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><em>Note on the top <code>16</code> bytes being zero</em>: it is required that an encoded element is "in a field", which means strictly <code>&lt; modulus</code>. In BigEndian encoding it automatically means that for a modulus that is just <code>381</code> bit long the top <code>16</code> bytes in <code>64</code> bytes encoding are zeroes and this <strong>must</strong> be checked even if only a subslice of input data is used for actual decoding.</p> <p>On inputs that can not be a valid encodings of field elements 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 of G1 and G2 are encoded as byte concatenation of the respective encodings of the <code>x</code> and <code>y</code> coordinates. Total encoding length for a G1 point is thus <code>128</code> bytes and for a G2 point is <code>256</code> bytes.</p> <h4 id="point-of-infinity-encoding">Point of infinity encoding:</h4> <p>Also referred to as the "zero point". For BLS12 curves, the point with coordinates <code>(0, 0)</code> (zeroes in Fp or Fp2) is <em>not</em> on the curve, so a sequence of <code>128</code> resp. <code>256</code> zero bytes, which naively would decode as <code>(0, 0)</code> is instead used by convention to encode the point of infinity of G1 resp. G2.</p> <h4 id="encoding-of-scalars-for-multiplication-operation">Encoding of scalars for multiplication operation:</h4> <p>A scalar for the multiplication operation is encoded as <code>32</code> bytes by performing BigEndian encoding of the corresponding (unsigned) integer. The corresponding integer is <strong>not</strong> required to be less than or equal to main subgroup order <code>q</code>.</p> <h4 id="behavior-on-empty-inputs">Behavior on empty inputs:</h4> <p>Certain operations have variable length input, such as MSMs (takes a list of pairs <code>(point, scalar)</code>), or pairing (takes a list of <code>(G1, G2)</code> points). While their behavior is well-defined (from an arithmetic perspective) on empty inputs, this EIP discourages such use cases and variable input length operations must return an error if the input is empty.</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>Invalid coordinate encoding</li> <li>An input is neither a point on the G1 elliptic curve nor the infinity point</li> <li>Input has invalid length</li> </ul> <p>Note:</p> <p>There is no subgroup check for the G1 addition precompile.</p> <h4 id="abi-for-g1-msm">ABI for G1 MSM</h4> <p>G1 MSM call expects <code>160*k</code> (<code>k</code> being a <strong>positive</strong> integer) 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 a G1 point (<code>128</code> bytes) and encoding of a scalar value (<code>32</code> bytes). Output is an encoding of MSM operation result - a single G1 point (<code>128</code> bytes).</p> <p>Error cases:</p> <ul> <li>Invalid coordinate encoding</li> <li>An input is neither a point on the G1 elliptic curve nor the infinity point</li> <li>An input is on the G1 elliptic curve but not in the correct subgroup</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 - a single G2 point (<code>256</code> bytes).</p> <p>Error cases:</p> <ul> <li>Invalid coordinate encoding</li> <li>An input is neither a point on the G2 elliptic curve nor the infinity point</li> <li>Input has invalid length</li> </ul> <p>Note:</p> <p>There is no subgroup check for the G2 addition precompile.</p> <h4 id="abi-for-g2-msm">ABI for G2 MSM</h4> <p>G2 MSM call expects <code>288*k</code> (<code>k</code> being a <strong>positive</strong> integer) 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 MSM operation result - a single G2 point (<code>256</code> bytes).</p> <p>Error cases:</p> <ul> <li>Invalid coordinate encoding</li> <li>An input is neither a point on the G2 elliptic curve nor the infinity point</li> <li>An input is on the G2 elliptic curve but not in the correct subgroup</li> <li>Input has invalid length</li> </ul> <h4 id="abi-for-pairing-check">ABI for pairing check</h4> <p>Pairing check call expects <code>384*k</code> (<code>k</code> being a <strong>positive</strong> integer) 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>Each point is expected to be in the subgroup of order <code>q</code>.</p> <p>It checks the equation <code>e(P1, Q1) * e(P2, Q2) * ... * e(Pk, Qk) == 1</code> in the pairing target field where <code>e</code> is the pairing operation. Output is <code>32</code> bytes where first <code>31</code> bytes are equal to <code>0x00</code> and the last byte is either <code>0x00</code> (false) or <code>0x01</code> (true).</p> <p>Error cases:</p> <ul> <li>Invalid coordinate encoding</li> <li>An input is neither a point on its respective elliptic curve nor the infinity point</li> <li>An input is on its respective elliptic curve but not in the correct subgroup</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 an input that is interpreted as an element of Fp. Output of this call is <code>128</code> bytes and is an encoded G1 point.</p> <p>Error cases:</p> <ul> <li>Input has invalid length</li> <li>Input is not correctly encoded</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 an input that is interpreted as an element of Fp2. Output of this call is <code>256</code> bytes and is an encoded G2 point.</p> <p>Error cases:</p> <ul> <li>Input has invalid length</li> <li>Input is not correctly encoded</li> </ul> <h3 id="gas-burning-on-error">Gas burning on error</h3> <p>Following the current state of all other precompiles, if a call to one of the precompiles in this EIP results in an error then all the gas supplied along with a <code>CALL</code> or <code>STATICCALL</code> is burned.</p> <h3 id="ddos-protection">DDoS protection</h3> <p>A sane implementation of this EIP <em>should not</em> contain potential infinite loops (it is possible and not even hard to implement all the functionality without <code>while</code> loops) and the gas schedule accurately reflects the time spent on computations of the corresponding function (precompiles pricing reflects an amount of gas consumed in the worst case where such a case exists).</p> <h3 id="gas-schedule">Gas schedule</h3> <p>Assuming <code>EcRecover</code> precompile as a baseline.</p> <h4 id="g1-addition">G1 addition</h4> <p><code>375</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>600</code> gas</p> <h4 id="g2-multiplication">G2 multiplication</h4> <p><code>22500</code> gas</p> <h4 id="g1-g2-msm">G1/G2 MSM</h4> <p>MSMs are expected to be performed by Pippenger's algorithm (we can also say that it <strong>must</strong> be performed by Pippenger's 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 MSM with a discount cap <code>max_discount</code> for <code>k &gt; 128</code>.</p> <p>The 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 G1/G2 multiplication cost presented above and <code>//</code> is an integer division.</p> <p>G1 and G2 are priced separately, each having their own discount table and <code>max_discount</code>.</p> <h5 id="g1-discounts">G1 discounts</h5> <p>Discounts table for G1 MSM 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, 1000], [2, 949], [3, 848], [4, 797], [5, 764], [6, 750], [7, 738], [8, 728], [9, 719], [10, 712], [11, 705], [12, 698], [13, 692], [14, 687], [15, 682], [16, 677], [17, 673], [18, 669], [19, 665], [20, 661], [21, 658], [22, 654], [23, 651], [24, 648], [25, 645], [26, 642], [27, 640], [28, 637], [29, 635], [30, 632], [31, 630], [32, 627], [33, 625], [34, 623], [35, 621], [36, 619], [37, 617], [38, 615], [39, 613], [40, 611], [41, 609], [42, 608], [43, 606], [44, 604], [45, 603], [46, 601], [47, 599], [48, 598], [49, 596], [50, 595], [51, 593], [52, 592], [53, 591], [54, 589], [55, 588], [56, 586], [57, 585], [58, 584], [59, 582], [60, 581], [61, 580], [62, 579], [63, 577], [64, 576], [65, 575], [66, 574], [67, 573], [68, 572], [69, 570], [70, 569], [71, 568], [72, 567], [73, 566], [74, 565], [75, 564], [76, 563], [77, 562], [78, 561], [79, 560], [80, 559], [81, 558], [82, 557], [83, 556], [84, 555], [85, 554], [86, 553], [87, 552], [88, 551], [89, 550], [90, 549], [91, 548], [92, 547], [93, 547], [94, 546], [95, 545], [96, 544], [97, 543], [98, 542], [99, 541], [100, 540], [101, 540], [102, 539], [103, 538], [104, 537], [105, 536], [106, 536], [107, 535], [108, 534], [109, 533], [110, 532], [111, 532], [112, 531], [113, 530], [114, 529], [115, 528], [116, 528], [117, 527], [118, 526], [119, 525], [120, 525], [121, 524], [122, 523], [123, 522], [124, 522], [125, 521], [126, 520], [127, 520], [128, 519]]</span></span></code></pre> <p><code>max_discount = 519</code></p> <h5 id="g2-discounts">G2 discounts</h5> <p>Discounts table for G2 MSM 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, 1000], [2, 1000], [3, 923], [4, 884], [5, 855], [6, 832], [7, 812], [8, 796], [9, 782], [10, 770], [11, 759], [12, 749], [13, 740], [14, 732], [15, 724], [16, 717], [17, 711], [18, 704], [19, 699], [20, 693], [21, 688], [22, 683], [23, 679], [24, 674], [25, 670], [26, 666], [27, 663], [28, 659], [29, 655], [30, 652], [31, 649], [32, 646], [33, 643], [34, 640], [35, 637], [36, 634], [37, 632], [38, 629], [39, 627], [40, 624], [41, 622], [42, 620], [43, 618], [44, 615], [45, 613], [46, 611], [47, 609], [48, 607], [49, 606], [50, 604], [51, 602], [52, 600], [53, 598], [54, 597], [55, 595], [56, 593], [57, 592], [58, 590], [59, 589], [60, 587], [61, 586], [62, 584], [63, 583], [64, 582], [65, 580], [66, 579], [67, 578], [68, 576], [69, 575], [70, 574], [71, 573], [72, 571], [73, 570], [74, 569], [75, 568], [76, 567], [77, 566], [78, 565], [79, 563], [80, 562], [81, 561], [82, 560], [83, 559], [84, 558], [85, 557], [86, 556], [87, 555], [88, 554], [89, 553], [90, 552], [91, 552], [92, 551], [93, 550], [94, 549], [95, 548], [96, 547], [97, 546], [98, 545], [99, 545], [100, 544], [101, 543], [102, 542], [103, 541], [104, 541], [105, 540], [106, 539], [107, 538], [108, 537], [109, 537], [110, 536], [111, 535], [112, 535], [113, 534], [114, 533], [115, 532], [116, 532], [117, 531], [118, 530], [119, 530], [120, 529], [121, 528], [122, 528], [123, 527], [124, 526], [125, 526], [126, 525], [127, 524], [128, 524]]</span></span></code></pre> <p><code>max_discount = 524</code></p> <h4 id="pairing-check-operation">Pairing check operation</h4> <p>The cost of the pairing check operation is <code>32600*k + 37700</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>23800</code> gas</p> <h4 id="gas-schedule-clarifications-for-the-variable-length-input">Gas schedule clarifications for the variable-length input</h4> <p>For MSM and pairing functions, the gas cost depends on the input length. The current state of how the gas schedule is implemented in major clients (at the time of writing) is that the gas cost function does <em>not</em> perform any validation of the length of the input and never returns an error. So we present a list of rules how the gas cost functions <strong>must</strong> be implemented to ensure consistency between clients and safety.</p> <h5 id="gas-schedule-clarifications-for-g1-g2-msm">Gas schedule clarifications for G1/G2 MSM</h5> <p>Define a constant <code>LEN_PER_PAIR</code> that is equal to <code>160</code> for G1 operation and to <code>288</code> for G2 operation. Define a function <code>discount(k)</code> following the rules in the corresponding section, where <code>k</code> is number of pairs.</p> <p>The following pseudofunction reflects how gas should be calculated:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>k = floor(len(input) / LEN_PER_PAIR);</span></span> <span class="giallo-l"><span>if k == 0 {</span></span> <span class="giallo-l"><span> return 0;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span>gas_cost = k * multiplication_cost * discount(k) // multiplier;</span></span> <span class="giallo-l"><span>return gas_cost;</span></span></code></pre> <p>We use floor division to get the number of pairs. If the length of the input is not divisible by <code>LEN_PER_PAIR</code> we still produce <em>some</em> result, but later on the precompile will return an error. Also, the case when <code>k = 0</code> is safe: <code>CALL</code> or <code>STATICCALL</code> cost is non-zero, and the case with formal zero gas cost is already used in <code>Blake2f</code> precompile. In any case, the main precompile routine <strong>must</strong> produce an error on such an input because it violated encoding rules.</p> <h5 id="gas-schedule-clarifications-for-pairing">Gas schedule clarifications for pairing</h5> <p>Define a constant <code>LEN_PER_PAIR = 384</code>;</p> <p>The following pseudofunction reflects how gas should be calculated:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>k = floor(len(input) / LEN_PER_PAIR);</span></span> <span class="giallo-l"><span>gas_cost = 32600*k + 37700;</span></span> <span class="giallo-l"><span>return gas_cost;</span></span></code></pre> <p>We use floor division to get the number of pairs. If the length of the input is not divisible by <code>LEN_PER_PAIR</code> we still produce <em>some</em> result, but later on the precompile will return an error (the precompile routine <strong>must</strong> produce an error on such an input because it violated encoding rules).</p> <h2 id="rationale">Rationale</h2> <p>The motivation section covers a total motivation to have operations over the BLS12-381 curves available. We also extend a rationale for more specific fine points.</p> <h3 id="msm-as-a-separate-call">MSM as a separate call</h3> <p>Explicit separate MSM operation that allows one to save execution time (so gas) by both the algorithm used (namely Pippenger's 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-negligible overhead if e.g. for MSM 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="no-dedicated-mul-call">No dedicated MUL call</h3> <p>Dedicated MUL precompiles which perform single G1/G2 point by scalar multiplication have exactly the same ABI as MSM with <code>k == 1</code>. MSM has to inspect the input length to reject inputs of invalid lengths. Therefore, it should recognize the case of <code>k == 1</code> and invoke the underlying implementation of single point multiplication to avoid the overhead of more complex multi-scalar multiplication algorithm.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no backward compatibility questions.</p> <h3 id="subgroup-checks">Subgroup checks</h3> <p>MSMs and pairings MUST perform a subgroup check. Implementations SHOULD use the optimized subgroup check method detailed in a dedicated <a href="https://wg-eips.ritovision.com/2537/assets/fast_subgroup_checks/">document</a>. On any input that fails the subgroup check, the precompile MUST return an error. As endomorphism acceleration requires input on the correct subgroup, implementers MAY use endomorphism acceleration.</p> <h3 id="field-to-curve-mapping">Field to curve mapping</h3> <p>The algorithms and set of parameters for SWU mapping method are provided by a separate <a href="https://wg-eips.ritovision.com/2537/assets/field_to_curve/">document</a></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. The generator for G1 is labeled as <code>G</code>, the generator for G2 is labeled as <code>H</code>, otherwise we assume random points on a curve in a correct subgroup. <code>0</code> means either scalar zero or point at infinity. <code>1</code> means either scalar one or multiplicative identity. <code>group_order</code> is the 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>Required properties for basic ops (add/multiply):</p> <ul> <li>Commutativity: <code>P + Q = Q + P</code></li> <li>Identity element: <code>P + 0 = 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>Bilinearity <code>e(a*P, b*Q) = e(a*b*P, Q) = e(P, a*b*Q)</code></li> <li>Non-degeneracy <code>e(P, Q) != 1</code></li> <li><code>e(P, 0*Q) = e(0*P, Q) = 1</code></li> <li><code>e(P, -Q) = e(-P, Q)</code></li> </ul> <p>Test vectors can be found <a href="https://wg-eips.ritovision.com/2537/assets/test-vectors/">in the test vectors files</a>.</p> <h3 id="benchmarking-test-cases">Benchmarking test cases</h3> <p>A set of test vectors for quick benchmarking on new implementations is located in a separate <a href="https://wg-eips.ritovision.com/2537/assets/bench_vectors/">file</a></p> <h2 id="reference-implementation">Reference Implementation</h2> <p>There are two fully spec compatible implementations on the day of writing:</p> <ul> <li>One in Rust language that is based on the <a href="https://wg-eips.ritovision.com/196/">EIP-196</a> code and integrated with OpenEthereum for this library</li> <li>One implemented specifically for Geth as a part of the current codebase</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-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-17T00:00:00+00:00 2026-02-11T14:49:27+00:00 Christoph Burgdorfhttps://github.com/cburgdorf https://wg-eips.ritovision.com/2481/

Introduces a request id for all requests of the eth protocol

<h2 id="abstract">Abstract</h2> <p>The <code>eth</code> protocol defines various request and response commands that are used to exchange data between Ethereum nodes. For example, to ask a peer node for a specific set of headers, a node sends it the <a rel="external" href="https://github.com/ethereum/devp2p/blob/40ab248bf7e017e83cc9812a4e048446709623e8/caps/eth.md#getblockheaders-0x03"><code>GetBlockHeaders</code></a> command.</p> <p><em>Citing from the <a rel="external" href="https://github.com/ethereum/devp2p/blob/40ab248bf7e017e83cc9812a4e048446709623e8/caps/eth.md#getblockheaders-0x03"><code>GetBlockHeaders</code> spec definition</a>:</em></p> <blockquote> <p><code>[block: {P, B_32}, maxHeaders: P, skip: P, reverse: P in {0, 1}]</code></p> </blockquote> <blockquote> <p>Require peer to return a <code>BlockHeaders</code> message. Reply must contain a number of block headers, of rising number when <code>reverse</code> is <code>0</code>, falling when <code>1</code>, <code>skip</code> blocks apart, beginning at block <code>block</code> (denoted by either number or hash) in the canonical chain, and with at most <code>maxHeaders</code> items.</p> </blockquote> <p>The node that receives the <code>GetBlockHeaders</code> command should answer it with the <a rel="external" href="https://github.com/ethereum/devp2p/blob/40ab248bf7e017e83cc9812a4e048446709623e8/caps/eth.md#blockheaders-0x04"><code>BlockHeaders</code></a> response command accordingly.</p> <p><em>Citing from the <a rel="external" href="https://github.com/ethereum/devp2p/blob/40ab248bf7e017e83cc9812a4e048446709623e8/caps/eth.md#blockheaders-0x04"><code>BlockHeaders</code> spec definition</a>:</em></p> <blockquote> <p><code>[blockHeader_0, blockHeader_1, ...]</code></p> </blockquote> <blockquote> <p>Reply to <code>GetBlockHeaders</code>. The items in the list (following the message ID) are block headers in the format described in the main Ethereum specification, previously asked for in a GetBlockHeaders message. This may validly contain no block headers if none of the requested block headers were found. The number of headers that can be requested in a single message may be subject to implementation-defined limits.</p> </blockquote> <p>Let's consider a client making many simultaneous requests for <code>GetBlockHeaders</code> to one of its peers. By nature it can not be guaranteed that the expected responses arrive in the same order as they were sent. For the client to associate the incoming responses to the correct requests it has to loop through all pending requests trying to match it with the incoming response based on its contents.</p> <p>This can be particular tricky for responses that are ambiguous such as empty responses.</p> <p>This EIP proposes to change the <code>GetBlockHeaders</code> and the <code>BlockHeaders</code> command to include a <code>request_id</code>.</p> <p>The <code>request_id</code> is a 64-bit integer set by the client when it makes the request. On the responding side, the exact same <code>request_id</code> from the incoming request is put back into the response object.</p> <p>This change allows the requesting client to match incoming responses <strong>directly</strong> back to their pending requests without going through all of the pending requests to check if they might match based on the response data.</p> <p>The selected request/response pair serves as an example for many similar request/response pairs in the <code>eth</code> networking protocol.</p> <h2 id="motivation">Motivation</h2> <p>The lack of request identifiers in the request / response paris of the <code>eth</code> protocol puts unnecessary burden of code complexity into every Ethereum client. It also makes the communication slightly less efficient. Another argument can be made that the addition of request identifiers makes the protocol more aligned with the <code>les</code> protocol which <strong>does</strong> already defines request identifiers for each request / response pair.</p> <h2 id="specification">Specification</h2> <p>Change the following message types in the <code>eth</code> protocol:</p> <ul> <li><code>GetBlockHeaders (0x03)</code> <ul> <li><strong>Current (eth/65):</strong> <code>[block: {P, B_32}, maxHeaders: P, skip: P, reverse: P in {0, 1}]</code></li> <li><strong>Then (eth/66)</strong>: <code>[request_id: P, [block: {P, B_32}, maxHeaders: P, skip: P, reverse: P in {0, 1}]]</code></li> </ul> </li> <li><code>BlockHeaders (0x04)</code> <ul> <li><strong>Current (eth/65):</strong> <code>[blockHeader_0, blockHeader_1, ...]</code></li> <li><strong>Then (eth/66)</strong>: <code>[request_id: P, [blockHeader_0, blockHeader_1, ...]]</code></li> </ul> </li> <li><code>GetBlockBodies (0x05)</code> <ul> <li><strong>Current (eth/65):</strong> <code>[hash_0: B_32, hash_1: B_32, ...]</code></li> <li><strong>Then (eth/66)</strong>: <code>[request_id: P, [hash_0: B_32, hash_1: B_32, ...]]</code></li> </ul> </li> <li><code>GetPooledTransactions (0x09)</code>: <ul> <li><strong>Current (eth/65)</strong><code>[hash_0: B_32, hash_1: B_32, ...]</code></li> <li><strong>Then (eth/66)</strong><code>[request_id: P, [hash_0: B_32, hash_1: B_32, ...]]</code></li> </ul> </li> <li><code>PooledTransactions (0x0a)</code>: <ul> <li><strong>Current (eth/65)</strong><code>[[nonce: P, receivingAddress: B_20, value: P, ...], ...]</code></li> <li><strong>Then (eth/66)</strong><code>[request_id: P, [[nonce: P, receivingAddress: B_20, value: P, ...], ...]]</code></li> </ul> </li> <li><code>BlockBodies (0x06)</code> <ul> <li><strong>Current (eth/65):</strong> <code>[hash_0: B_32, hash_1: B_32, ...]</code></li> <li><strong>Then (eth/66)</strong>: <code>[request_id: P, [hash_0: B_32, hash_1: B_32, ...]]</code></li> </ul> </li> <li><code>GetNodeData (0x0d)</code> <ul> <li><strong>Current (eth/65):</strong> <code>[hash_0: B_32, hash_1: B_32, ...]</code></li> <li><strong>Then (eth/66)</strong>: <code>[request_id: P, [hash_0: B_32, hash_1: B_32, ...]]</code></li> </ul> </li> <li><code>NodeData (0x0e)</code> <ul> <li><strong>Current (eth/65):</strong> <code>[value_0: B, value_1: B, ...]</code></li> <li><strong>Then (eth/66)</strong>: <code>[request_id: P, [value_0: B, value_1: B, ...]]</code></li> </ul> </li> <li><code>GetReceipts (0x0f)</code> <ul> <li><strong>Current (eth/65):</strong> <code>[blockHash_0: B_32, blockHash_1: B_32, ...]</code></li> <li><strong>Then (eth/66)</strong>: <code>[request_id: P, [blockHash_0: B_32, blockHash_1: B_32, ...]]</code></li> </ul> </li> <li><code>Receipts (0x10)</code> <ul> <li><strong>Current (eth/65):</strong> <code>[[receipt_0, receipt_1], ...]</code></li> <li><strong>Then (eth/66)</strong>: <code>[request_id: P, [[receipt_0, receipt_1], ...]]</code></li> </ul> </li> </ul> <p>To elaborate, each command is altered in the following way:</p> <ol> <li>Create a list with the <code>request_id</code> being the first element.</li> <li>Make the second element the list that defines the whole command in the current scheme.</li> </ol> <p>The <code>request_id</code> has the following characteristics:</p> <ul> <li>64 bit integer</li> <li>Doesn't need to be sequential (can be random)</li> <li>Does allow duplicates</li> </ul> <h2 id="rationale">Rationale</h2> <p><strong>Q: The efficiency gains might encourage clients to flood their peers with too many simultaneous requests</strong></p> <p>Peers can always throttle or disconnect if they don't feel treated well. This is the same as today.</p> <p><strong>Q: If <code>les</code> already defines the commands like this, why not just use the <code>les</code> protocol?</strong></p> <p>In practice, peers that serve the <code>les</code> protocol are much harder to find in the network. The reasons for this are varied but might boil down to client defaults, immature implementations or missing incentives.</p> <p><strong>Q: Networking works today, isn't this just adding bloat?</strong></p> <p>This is adding a single integer per command while at the same time reducing code complexity and improving networking efficiency. The addition seems justified.</p> <p><strong>Q: Why not demand request ids to be sequential?</strong></p> <p>Assuming request ids start always to count from <code>0</code> upon connection, things will become messy when connections are lost and clients reconnect and start over with the same request ids that they had used in the previous session.</p> <p><strong>Q: Why allow duplicate request ids?</strong></p> <p>The main benefit is flexibility and simplicity on the implementation side. Clients could decide to share the same ids across multiple different request types since they are naturally separated anyway. Clients could even decide to not rely on request ids at all, therefore using the same constant request id across all requests.</p> <p><strong>Q: Why choose a 64-bit integer for the request ids</strong></p> <p>64-bit integer were chosen to keep compatibility with the <code>les</code> protocol.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP extends the <code>eth</code> protocol in a backwards incompatible way and requires rolling out a new version, <code>eth/66</code>. However, <code>devp2p</code> supports running multiple versions of the same wire protocol side-by-side, so rolling out <code>eth/66</code> does not require client coordination, since non-updated clients can keep using <code>eth/65</code>.</p> <p>This EIP does not change the consensus engine, thus does <em>not</em> require a hard fork.</p> <h2 id="test-cases">Test Cases</h2> <p>These testcases cover RLP-encoding of all the redefined messages types, where the <code>rlp</code> portion is the rlp-encoding of the message defined in the <code>data</code> portion.</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">GetBlockHeadersPacket66</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">rlp</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe8820457e4a000000000000000000000000000000000000000000000000000000000deadc0de050580</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RequestId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1111</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Origin</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">Hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000000000000000000000000000000000000000000000000000deadc0de</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Number</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">Amount</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 5</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Skip</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 5</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Reverse</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></code></pre><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">GetBlockHeadersPacket66</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">rlp</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xca820457c682270f050580</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RequestId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1111</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Origin</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">Hash</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">Number</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 9999</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">Amount</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 5</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Skip</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 5</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Reverse</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></code></pre><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">BlockHeadersPacket66</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">rlp</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf90202820457f901fcf901f9a00000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000000940000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000000b90100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008208ae820d0582115c8215b3821a0a827788a00000000000000000000000000000000000000000000000000000000000000000880000000000000000</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RequestId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1111</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BlockHeadersPacket</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">parentHash</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">sha3Uncles</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">miner</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">stateRoot</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">transactionsRoot</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">receiptsRoot</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">logsBloom</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">difficulty</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x8ae</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">number</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd05</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasLimit</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x115c</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasUsed</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x15b3</span><span class="z-punctuation z-definition z-string">&quot;</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">0x1a0a</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">extraData</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x7788</span><span class="z-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">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-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">0x0000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x8c2f2af15b7b563b6ab1e09bed0e9caade7ed730aec98b70a993597a797579a9</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><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">GetBlockBodiesPacket66</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">rlp</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf847820457f842a000000000000000000000000000000000000000000000000000000000deadc0dea000000000000000000000000000000000000000000000000000000000feedbeef</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RequestId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1111</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">GetBlockBodiesPacket</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">0x00000000000000000000000000000000000000000000000000000000deadc0de</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">0x00000000000000000000000000000000000000000000000000000000feedbeef</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><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">BlockBodiesPacket66</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">rlp</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf902dc820457f902d6f902d3f8d2f867088504a817c8088302e2489435353535353535353535353535353535353535358202008025a064b1702d9298fee62dfeccc57d322a463ad55ca201256d01f62b45b2e1c21c12a064b1702d9298fee62dfeccc57d322a463ad55ca201256d01f62b45b2e1c21c10f867098504a817c809830334509435353535353535353535353535353535353535358202d98025a052f8f61201b2b11a78d6e866abc9c3db2ae8631fa656bfe5cb53668255367afba052f8f61201b2b11a78d6e866abc9c3db2ae8631fa656bfe5cb53668255367afbf901fcf901f9a00000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000000940000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000000a00000000000000000000000000000000000000000000000000000000000000000b90100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008208ae820d0582115c8215b3821a0a827788a00000000000000000000000000000000000000000000000000000000000000000880000000000000000</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RequestId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1111</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">BlockBodiesPacket</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">Transactions</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">nonce</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x8</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasPrice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4a817c808</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x2e248</span><span class="z-punctuation z-definition z-string">&quot;</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">0x3535353535353535353535353535353535353535</span><span class="z-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">0x200</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">input</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">v</span><span class="z-support">&quot;</span><span>:</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>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">r</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x64b1702d9298fee62dfeccc57d322a463ad55ca201256d01f62b45b2e1c21c12</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">s</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x64b1702d9298fee62dfeccc57d322a463ad55ca201256d01f62b45b2e1c21c10</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x588df025c4c2d757d3e314bd3dfbfe352687324e6b8557ad1731585e96928aed</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">nonce</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasPrice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4a817c809</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x33450</span><span class="z-punctuation z-definition z-string">&quot;</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">0x3535353535353535353535353535353535353535</span><span class="z-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">0x2d9</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">input</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">v</span><span class="z-support">&quot;</span><span>:</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>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">r</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x52f8f61201b2b11a78d6e866abc9c3db2ae8631fa656bfe5cb53668255367afb</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">s</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x52f8f61201b2b11a78d6e866abc9c3db2ae8631fa656bfe5cb53668255367afb</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf39c7dac06a9f3abf09faf5e30439a349d3717611b3ed337cd52b0d192bc72da</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">Uncles</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">parentHash</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">sha3Uncles</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">miner</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">stateRoot</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">transactionsRoot</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">receiptsRoot</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">logsBloom</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">difficulty</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x8ae</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">number</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd05</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasLimit</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x115c</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasUsed</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x15b3</span><span class="z-punctuation z-definition z-string">&quot;</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">0x1a0a</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">extraData</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x7788</span><span class="z-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">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-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">0x0000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x8c2f2af15b7b563b6ab1e09bed0e9caade7ed730aec98b70a993597a797579a9</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><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">GetNodeDataPacket66</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">rlp</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf847820457f842a000000000000000000000000000000000000000000000000000000000deadc0dea000000000000000000000000000000000000000000000000000000000feedbeef</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RequestId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1111</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">GetNodeDataPacket</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">0x00000000000000000000000000000000000000000000000000000000deadc0de</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">0x00000000000000000000000000000000000000000000000000000000feedbeef</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><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">NodeDataPacket66</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">rlp</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xce820457ca84deadc0de84feedbeef</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RequestId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1111</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">NodeDataPacket</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">0xdeadc0de</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">0xfeedbeef</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><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">GetReceiptsPacket66</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">rlp</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf847820457f842a000000000000000000000000000000000000000000000000000000000deadc0dea000000000000000000000000000000000000000000000000000000000feedbeef</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RequestId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1111</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">GetReceiptsPacket</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">0x00000000000000000000000000000000000000000000000000000000deadc0de</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">0x00000000000000000000000000000000000000000000000000000000feedbeef</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><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">ReceiptsPacket66</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">rlp</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf90172820457f9016cf90169f901668001b9010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000f85ff85d940000000000000000000000000000000000000011f842a0000000000000000000000000000000000000000000000000000000000000deada0000000000000000000000000000000000000000000000000000000000000beef830100ff</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RequestId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1111</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">ReceiptsPacket</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">root</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">status</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">cumulativeGasUsed</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 class="z-support"> &quot;</span><span class="z-support">logsBloom</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">logs</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">0x0000000000000000000000000000000000000011</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">topics</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">0x000000000000000000000000000000000000000000000000000000000000dead</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">0x000000000000000000000000000000000000000000000000000000000000beef</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">data</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0100ff</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">blockNumber</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">transactionHash</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">transactionIndex</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">blockHash</span><span class="z-support">&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-support"> &quot;</span><span class="z-support">logIndex</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">removed</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 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">0x00000000000000000000000000000000000000000000000000000000deadc0de</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">contractAddress</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000011111</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasUsed</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b207</span><span class="z-punctuation z-definition z-string">&quot;</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 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-support"> &quot;</span><span class="z-support">transactionIndex</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 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="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">GetPooledTransactionsPacket66</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">rlp</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf847820457f842a000000000000000000000000000000000000000000000000000000000deadc0dea000000000000000000000000000000000000000000000000000000000feedbeef</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RequestId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1111</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">GetPooledTransactionsPacket</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">0x00000000000000000000000000000000000000000000000000000000deadc0de</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">0x00000000000000000000000000000000000000000000000000000000feedbeef</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><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">PooledTransactionsPacket66</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">rlp</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf8d7820457f8d2f867088504a817c8088302e2489435353535353535353535353535353535353535358202008025a064b1702d9298fee62dfeccc57d322a463ad55ca201256d01f62b45b2e1c21c12a064b1702d9298fee62dfeccc57d322a463ad55ca201256d01f62b45b2e1c21c10f867098504a817c809830334509435353535353535353535353535353535353535358202d98025a052f8f61201b2b11a78d6e866abc9c3db2ae8631fa656bfe5cb53668255367afba052f8f61201b2b11a78d6e866abc9c3db2ae8631fa656bfe5cb53668255367afb</span><span class="z-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> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">RequestId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1111</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">PooledTransactionsPacket</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">nonce</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x8</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasPrice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4a817c808</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x2e248</span><span class="z-punctuation z-definition z-string">&quot;</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">0x3535353535353535353535353535353535353535</span><span class="z-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">0x200</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">input</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">v</span><span class="z-support">&quot;</span><span>:</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>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">r</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x64b1702d9298fee62dfeccc57d322a463ad55ca201256d01f62b45b2e1c21c12</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">s</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x64b1702d9298fee62dfeccc57d322a463ad55ca201256d01f62b45b2e1c21c10</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x588df025c4c2d757d3e314bd3dfbfe352687324e6b8557ad1731585e96928aed</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">nonce</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gasPrice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4a817c809</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x33450</span><span class="z-punctuation z-definition z-string">&quot;</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">0x3535353535353535353535353535353535353535</span><span class="z-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">0x2d9</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">input</span><span class="z-support">&quot;</span><span>:</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></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">v</span><span class="z-support">&quot;</span><span>:</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>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">r</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x52f8f61201b2b11a78d6e866abc9c3db2ae8631fa656bfe5cb53668255367afb</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">s</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x52f8f61201b2b11a78d6e866abc9c3db2ae8631fa656bfe5cb53668255367afb</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf39c7dac06a9f3abf09faf5e30439a349d3717611b3ed337cd52b0d192bc72da</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="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-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-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Péter Szilágyipeterke@gmail.com Péter Szilágyihttps://github.com/karalabe Gary Ronggaryrong0905@gmail.com Tim Beikohttps://github.com/timbeiko https://wg-eips.ritovision.com/2464/

Introduces `NewPooledTransactionHashes`, `GetPooledTransactions`, and `PooledTransactions`.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces three additional message types into the <code>eth</code> protocol (releasing a new version, <code>eth/65</code>): <code>NewPooledTransactionHashes (0x08)</code> to announce a set of transactions without their content; <code>GetPooledTransactions (0x09)</code> to request a batch of transactions by their announced hash; and <code>PooledTransactions (0x0a)</code> to reply to a transaction request. This permits reducing the bandwidth used for transaction propagation from linear complexity in the number of peers to square root; and also reducing the initial transaction exchange from 10s-100s MB to <code>len(pool) * 32B ~= 128KB</code>.</p> <h2 id="motivation">Motivation</h2> <p>The <code>eth</code> network protocol has two ways to propagate a newly mined block: it can be broadcast to a peer in its entirety (via <code>NewBlock (0x07)</code> in <code>eth/64</code> and prior or it can be announced only (via <code>NewBlockHashes (0x01)</code>). This duality allows nodes to do the high-bandwidth broadcasting (10s-100s KB) for a square root number of peers; and the low-bandwidth announcing (10s-100s B) for the remaining linear number of peers. The square root broadcast is enough to reach all well connected nodes, but the linear announce is needed to get across degenerate topologies. This works well.</p> <p>The <code>eth</code> protocol, however, does not have a similar dual mechanism for propagating transactions, so nodes need to rely on broadcasting (via <code>Transactions (0x02)</code>). To cater for degenerate topologies, transactions cannot be broadcast square rooted, rather they need to be transferred linearly to all peers. With N peers, each node will transfer the same transaction N times (counting both directions), whereas 1 would be enough in a perfect world. This is a significant waste.</p> <p>A similar issue arises when a new network connection is made between two nodes, as they need to sync up their transaction pools, but the pool is just a soup of dangling transactions. Without a way to deduplicate transactions remotely, each node is forced to naively transfer their entire list of transactions to the other side. With pools containing thousands of transactions, a naive transfer amounts to 10s-100s MB, most of which is useless. There is no better way, however.</p> <p>This EIP introduces three additional message types into the <code>eth</code> protocol (releasing a new version, <code>eth/65</code>): <code>NewPooledTransactionHashes (0x08)</code> to announce a set of transactions without their content; <code>GetPooledTransactions (0x09)</code> to request a batch of transactions by their announced hash; and <code>PooledTransactions (0x0a)</code> to reply to a transaction request. This permits reducing the bandwidth used for transaction propagation from linear complexity in the number of peers to square root; and also reducing the initial transaction exchange from 10s-100s MB to <code>len(pool) * 32B ~= 128KB</code>.</p> <p>With transaction throughput (and size) picking up in Ethereum, transaction propagation is the current dominant component of the used network resources. Most of these resources are however wasted, as the <code>eth</code> protocol does not have a mechanism to deduplicate transactions remotely, so the same data is transferred over and over again across all network connections.</p> <p>This EIP proposes a tiny extension to the <code>eth</code> protocol, which permits nodes to agree on the set of transactions that need to be transferred across a network connection, before doing the costly exchange. This should help reduce the global (operational) bandwidth usage of the Ethereum network by at least an order of magnitude.</p> <h2 id="specification">Specification</h2> <p>Add three new message types to the <code>eth</code> protocol:</p> <ul> <li><code>NewPooledTransactionHashes (0x08): [hash_0: B_32, hash_1: B_32, ...]</code> <ul> <li>Specify one or more transactions that have appeared in the network and which have <strong>not yet been included in a block</strong>. To be maximally helpful, nodes should inform peers of all transactions that they may not be aware of.</li> <li>There is <strong>no protocol violating hard cap</strong> on the number of hashes a node may announce to a remote peer (apart from the 10MB <code>devp2p</code> network packet limit), but 4096 seems a sane chunk (128KB) to avoid a single packet hogging a network connection.</li> <li>Nodes should only announce hashes of transactions that the remote peer could reasonably be considered not to know, but it is better to be over zealous than to have a nonce gap in the pool.</li> </ul> </li> <li><code>GetPooledTransactions (0x09): [hash_0: B_32, hash_1: B_32, ...]</code> <ul> <li>Specify one or more transactions to retrieve from a remote peer's <strong>transaction pool</strong>.</li> <li>There is <strong>no protocol violating hard cap</strong> on the number of transactions a node may request from a remote peer (apart from the 10MB <code>devp2p</code> network packet limit), but the recipient may enforce an arbitrary cap on the reply (size or serving time), which <strong>must not</strong> be considered a protocol violation. To keep wasted bandwidth down (unanswered hashes), 256 seems like a sane upper limit.</li> </ul> </li> <li><code>PooledTransactions (0x0a): [[nonce: P, receivingAddress: B_20, value: P, ...], ...]</code> <ul> <li>Specify transactions <strong>from the local transaction pool</strong> that the remote node requested via a <code>GetPooledTransactions (0x09)</code> message. The items in the list are transactions in the format described in the main Ethereum specification.</li> <li>The transactions <strong>must</strong> be in same order as in the request, but it is <strong>ok</strong> to skip transactions that are not available. This way if the response size limit is reached, requesters will know which hashes to request again (everything from the last returned transaction) and which to assume unavailable (all gaps before the last returned transaction).</li> <li>A peer may respond with an empty reply <strong>iff</strong> none of the hashes match transactions in its pool. It is allowed to announce a transaction that will not be served later if it gets included in a block in between.</li> </ul> </li> </ul> <h2 id="rationale">Rationale</h2> <p><strong>Q: Why limit <code>GetPooledTransactions (0x09)</code> to retrieving items from the pool?</strong></p> <p>Apart from the transaction pool, transactions in Ethereum are always bundled together by the hundreds in block bodies and existing network retrievals honor this data layout. Allowing direct access to individual transactions in the database has no actionable use case, but would expose costly database reads into the network.</p> <p>For transaction propagation purposes there is no reason to allow disk access, as any transaction finalized to disk will be broadcast inside a block anyway, so at worse there is a few hundred millisecond delay when a node gets the transaction.</p> <p>Block propagation may be made a bit more optimal by transferring the contained transactions on demand only, but that is a whole EIP in itself, so better relax the protocol when all the requirements are known and not in advance. It would probably be enough to maintain a set of transactions included in recent blocks in memory.</p> <p><strong>Q: Should <code>NewPooledTransactionHashes (0x08)</code> deduplicate from disk?</strong></p> <p>Similarly to <code>GetPooledTransactions (0x09)</code>, <code>NewPooledTransactionHashes (0x08)</code> should also only operate on the transaction pool and should ignore the disk altogether. During healthy network conditions, a transaction will propagate through much faster than it's included in a block, so it will essentially be non-existent that a newly announced transaction is already on disk. By avoiding disk deduplication, we can avoid a DoS griefing by remote transaction announces.</p> <p>If we want to be really correct and avoid even the slightest data race when deduplicating announcements, we can use the same recently-included-transactions trick that we discussed above to discard announcements that have recently become stale.</p> <p><strong>Q: Why not reuse <code>Transaction (0x02)</code> instead of a new <code>PooledTransactions (0x0a)</code>?</strong></p> <p>Originally this EIP reused the existing <code>Transaction (0x02)</code> message as the reply to the <code>GetPooledTransactions (0x09)</code> request. This makes client code more complicated, because nodes constantly gossip <code>Transaction (0x02)</code> messages to each other as broadcasts, so it's hard to match up which of the many messages is the actual reply to the request.</p> <p>By keeping <code>Transaction (0x02)</code> and <code>PooledTransactions (0x0a)</code> as separate messages, we can also leave the protocol more flexible for future optimizations (e.g. adding request IDs, which are meaningless for gossip broadcasts).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP extends the <code>eth</code> protocol in a backwards incompatible way and requires rolling out a new version, <code>eth/65</code>. However, <code>devp2p</code> supports running multiple versions of the same wire protocol side-by-side, so rolling out <code>eth/65</code> does not require client coordination, since non-updated clients can keep using <code>eth/64</code>.</p> <p>This EIP does not change the consensus engine, thus does <em>not</em> require a hard fork.</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-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-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Eric Connerhttps://github.com/econoar https://wg-eips.ritovision.com/2384/ <h2 id="simple-summary">Simple Summary</h2> <p>The average block times are increasing due to the difficulty bomb (also known as the "<em>ice age</em>") and slowly accelerating. This EIP proposes to delay the difficulty bomb for another 4,000,000 blocks (~611 days).</p> <h2 id="abstract">Abstract</h2> <p>Starting with <code>MUIR_GLACIER_FORK_BLKNUM</code> the client will calculate the difficulty based on a fake block number suggesting to the client that the difficulty bomb is adjusting 9 million blocks later than the Homestead fork, which is also 7 million blocks later than the Byzantium fork and 4 million blocks later than the Constantinople fork.</p> <h2 id="motivation">Motivation</h2> <p>The difficulty bomb started to become noticeable again on October 5th 2019 at block 8,600,000. Block times have been around 13.1s on average and now as of block 8,900,000 are around 14.3s. This will start to accelerate exponentially every 100,000 blocks. Estimating the added impact from the difficulty bomb on block times shows that we will see 20s block times near the end of December 2019 and 30s+ block times starting February 2020. This will start making the chain bloated and more costly to use. It's best to delay the difficulty bomb again to around the time of expected launch of the Eth2 finality gadget.</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 - 9_000_000) if block.number &gt;= MUIR_GLACIER_FORK_BLKNUM else block.number</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This will delay the ice age by 52 million seconds (approximately 611 days), so the chain would be back at 20 second block times around July 2021. It's important to note this pushes the ice age 4,000,000 blocks from ~block 8,800,000 NOT from when this EIP is activated in a fork.</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 include this EIP shortly after the Istanbul fork.</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 in it's logic does not differ from <a href="https://wg-eips.ritovision.com/649/">EIP-649</a> or <a href="https://wg-eips.ritovision.com/1234/">EIP-1234</a>; an implementation for Parity-Ethereum is available in <a rel="external" href="https://github.com/paritytech/parity-ethereum/pull/9187">parity-ethereum#9187</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-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-08T00:00:00+00:00 2026-02-11T14:49:27+00:00 Péter Szilágyipeterke@gmail.com Péter Szilágyihttps://github.com/karalabe Tim Beikohttps://github.com/timbeiko https://wg-eips.ritovision.com/2364/

Introduces validation of the `forkid` when handshaking with peers.

<h2 id="abstract">Abstract</h2> <p>This EIP specifies the inclusion of the <code>forkid</code>, originally defined in <a href="https://wg-eips.ritovision.com/2124/">(EIP-2124)</a>, as a new field in the Ethereum wire protocol (<code>eth</code>) handshake. This change is implemented as a new version of the wire protocol, <code>eth/64</code>.</p> <h2 id="motivation">Motivation</h2> <p>The <a href="https://wg-eips.ritovision.com/2124/"><code>forkid</code> (EIP-2124)</a> was designed to permit two Ethereum nodes to quickly and cheaply decide if they are compatible or not, not only at a genesis/networking level, but also from the perspective of the currently passed network updates (i.e. forks).</p> <p><a href="https://wg-eips.ritovision.com/2124/">EIP-2124</a> only defines how the <code>forkid</code> is calculated and validated, but does not specify how the <code>forkid</code> should be exchanged between peers. This EIP specifies the inclusion of the <code>forkid</code> as a new field in the Ethereum wire protocol (<code>eth</code>) handshake (releasing a new version, <code>eth/64</code>).</p> <p>By cross-validating <code>forkid</code> during the handshake, incompatible nodes can disconnect before expensive block exchanges and validations take place (PoW check, EVM execution, state reconstruction). This further prevents peer slots from being taken up by nodes that are incompatible, but have not yet been detected as such.</p> <p>From a micro perspective, cutting off incompatible nodes from one another ensures that a node only spends its resources on tasks that are genuinely useful to it. The sooner we can decide the remote peer is useless, the less time and processing we expend in vain.</p> <p>From a macro perspective, keeping incompatible nodes partitioned from one another ensures that disjoint clusters retain more resources for maintaining their own chain, thus raising the quality of service for all networks globally.</p> <h2 id="specification">Specification</h2> <ul> <li>Implement <code>forkid</code> generation and validation per <a href="https://wg-eips.ritovision.com/2124/">EIP-2124</a>.</li> <li>Advertise a new <code>eth</code> protocol capability (version) at <code>eth/64</code>. <ul> <li>The old <code>eth/63</code> protocol should still be kept alive side-by-side, until <code>eth/64</code> is sufficiently adopted by implementors.</li> </ul> </li> <li>Redefine <code>Status (0x00)</code> for <code>eth/64</code> to add a trailing <code>forkid</code> field: <ul> <li>Old packet: <code>[protocolVersion, networkId, td, bestHash, genesisHash]</code></li> <li>New packet: <code>[protocolVersion, networkId, td, bestHash, genesisHash, forkid]</code>, where <code>forkid</code> is <code>[forkHash: [4]byte, forkNext: uint64]</code> (fields per <a href="https://wg-eips.ritovision.com/2124/">EIP-2124</a> ).</li> </ul> </li> </ul> <p>Whenever two peers connect using the <code>eth/64</code> protocol, the updated <code>Status</code> message must be sent as the protocol handshake, and each peer must validate the remote <code>forkid</code>, disconnecting at a detected incompatibility.</p> <h2 id="rationale">Rationale</h2> <p>The specification is tiny since most parts are already specified in EIP-2124. <code>eth/63</code> is not specified as an EIP, but is maintained in the <a rel="external" href="https://github.com/ethereum/devp2p">ethereum/devp2p</a> Github repository.</p> <h3 id="eip-2124-mentions-advertising-the-forkid-in-the-discovery-protocol-too-how-does-that-compare-to-advertising-in-the-eth-protocol-why-is-the-redundancy-needed">EIP-2124 mentions advertising the <code>forkid</code> in the discovery protocol too. How does that compare to advertising in the <code>eth</code> protocol? Why is the redundancy needed?</h3> <p>Advertising and validating the <code>forkid</code> in the discovery protocol is a more optimal solution, as it can help avoid the cost of setting up the TCP connection and cryptographic RLPx stream, only to be torn down if <code>eth/64</code> rejects it.</p> <p>Compared to the <code>eth</code> protocol however, discovery is a bit fuzzy. The goal there is to suggest potential peers, not to be fool-proof. Information may be outdated, nodes may have changed or disappeared. Discovery can do a rough filtering, but more precision is still needed afterwards.</p> <p>Additionally, <code>forkid</code> validation via the discovery protocol requires ENR implementation (<a href="https://wg-eips.ritovision.com/778/">EIP-778</a>) and ENR extension support (<a href="https://wg-eips.ritovision.com/868/">EIP-868</a>), which is not mandated by the Ethereum network currently. Lastly, the discovery protocol is just one way to find peers, but systems that cannot use UDP or that rely on other mechanism (e.g. DNS discovery)) still need a way to filter connections.</p> <h3 id="the-forkid-implicitly-contains-the-genesis-hash-checksummed-into-the-fork-hash-field-why-doesn-t-this-proposal-remove-the-genesishash-field-from-the-eth-handshake">The <code>forkid</code> implicitly contains the genesis hash checksummed into the <code>FORK_HASH</code> field. Why doesn't this proposal remove the <code>genesisHash</code> field from the <code>eth</code> handshake?</h3> <p>Originally this EIP did remove it as redundant data, since filtering based on the <code>forkid</code> is a superset of filtering based on genesis hash. The reason for backing out of that decision was that the genesis hash may be useful for other things too, not just connection filtering (network crawlers use it currently to split nodes across networks).</p> <p>Although the <code>forkid</code> will hopefully take over all the roles of the genesis hash currently in use, there's no reason to be overly aggressive in deduplicating data. It's fine to keep both side-by-side for now, and remove in a future version when 3rd party infrastructures switch over.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP extends the <code>eth</code> protocol handshake in a backwards incompatible way and requires rolling out a new version, <code>eth/64</code>. However, <code>devp2p</code> supports running multiple versions of the same wire protocol side-by-side, so rolling out <code>eth/64</code> does not require client coordination, since non-updated clients can keep using <code>eth/63</code>.</p> <p>This EIP does not change the consensus engine, thus does <em>not</em> require a hard fork.</p> <h2 id="test-cases">Test Cases</h2> <p>For calculating and validating fork IDs, see test cases in <a href="https://wg-eips.ritovision.com/2124/">EIP-2124</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> 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-10-17T00:00:00+00:00 2026-02-11T14:49:28+00:00 Greg Colvinhttps://github.com/gcolvin Martin Holst Swendehttps://github.com/holiman Brooklyn Zelenkahttps://github.com/expede John Max Skallerskaller@internode.on.net https://wg-eips.ritovision.com/2315/

Two opcodes for efficient, safe, and static subroutines.

<h2 id="abstract">Abstract</h2> <p>This proposal provides a <em>complete</em>, <em>efficient</em>, <em>safe</em> and <em>static</em> control-flow facility.</p> <p>It introduces two new opcodes to support calling and returning from subroutines:</p> <ul> <li><code>RJUMPSUB relative_offset</code> -- relative jump to subroutine</li> <li><code>RETURNSUB</code> -- return to <code>PC</code> after most recent <code>RJUMPSUB</code>.</li> </ul> <p>It depends on the two new opcodes proposed by <a href="https://wg-eips.ritovision.com/4200/">EIP-4200</a> to support static jumps:</p> <ul> <li><code>RJUMP relative_offset</code> — relative jump to <code>PC + relative_offset</code></li> <li><code>RJUMPI relative_offset</code> — conditional relative jump</li> </ul> <p>It deprecates <code>JUMP</code> and <code>JUMPI</code>, allowing valid code to support streaming, one-pass, and other near-linear compilers.</p> <p>In concert with <a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a> and <a href="https://wg-eips.ritovision.com/3670/">EIP-3670</a> it ensures, at initialization time, that valid code will not execute invalid instructions or jump to invalid locations, will not underflow stack, will maintain consistent numbers of inputs and outputs for subroutines, and will have bounded stack height in the absence of recursion.</p> <p>This is among the simplest possible proposals that meets these requirements.</p> <h2 id="motivation">Motivation</h2> <h3 id="a-complete-control-flow-facility">A complete control-flow facility.</h3> <p>Jumps, conditional jumps and subroutines were proposed by Alan Turing in 1945 as a means of organizing the logic of the code and the design of the memory crystals for his Automatic Computing Engine:</p> <blockquote> <p>We wish to be able to arrange that sequences of orders can divide at various points, continuing in different ways according to the outcome of the calculations to date... We also wish to be able to arrange for the splitting up of operations into subsidiary operations... To start on a subsidiary operation we need only make a note of where we left off the major operation and then apply the first instruction of the subsidiary. When the subsidiary is over we look up the note and continue with the major operation.</p> <p>— Alan Turing — in B.E. Carpenter, R.W. Doran, "The other Turing machine." The Computer Journal, Volume 20, Issue 3, January 1977.</p> </blockquote> <p>In more contemporary terms, we have sequences of instructions, jumps and conditional jumps that divide sequences into blocks, subroutine calls, and a stack of addresses to return to. The details vary, but similar facilities have proven their value across a long line of important machines over the last 75 years, including most all of the machines we have programmed or implemented -- physical machines including the Burroughs 5000, CDC 7600, IBM 360, DEC PDP-11 and VAX, Motorola 68000, Sun SPARC, and Intel x86s, as well as virtual machines for Scheme, Forth, Pascal, Java, Wasm, and others.</p> <p>Unlike these machines, the Ethereum Virtual Machine <em>does not</em> provide subroutine operations. Instead, they must be synthesized using the dynamic <code>JUMP</code> instruction, which takes its destination on the stack. Further, the EVM provides <em>only</em> dynamic jumps, impeding the static analysis we need.</p> <h3 id="efficient-control-flow">Efficient control-flow.</h3> <p>Efficient to write by hand, compile from high level labguages, validate at deploy time, interpret by VMs, and compile to machine code.</p> <p>Static jumps, conditional jumps, and subroutines are sufficient and efficient in space and time, as shown by historical experience and as we will show for the EVM below.</p> <h3 id="safe-control-flow">Safe control-flow.</h3> <p>The EVM has unusually high requirements for safety. Not only do many smart contracts control inordinately large amounts of valuable Ether, but once placed on the blockchain any defects are visible to attackers and cannot be repaired. We propose to statically validate important safety constraints on code at initialization time.</p> <h3 id="static-control-flow">Static control-flow.</h3> <p>The EVM's dynamic jumps cause two major problems. First, the need to synthesize static jumps and subroutines with dynamic jumps wastes space and gas with needlessly complex code, as we will show below.</p> <p>Worse, jumps that can dynamically branch to any destination in the code can cause quadratic "path explosions" when traversing the flow of control. For Ethereum, this is a denial-of-service vulnerability that prevents us, at initialization time, from validating the safe use of EVM code and from compiling EVM code to machine code.</p> <p>We <em>need</em> static control-flow to validate program safety and to compile EVM bytecode to machine code -- in time and space linear in the size of the code.</p> <h2 id="specification">Specification</h2> <h3 id="opcodes">Opcodes</h3> <h4 id="rjumpsub-0x5f-relative-offset"><code>RJUMPSUB (0x5f) relative_offset</code></h4> <p>Transfers control to a subroutine.</p> <ol> <li>Decode the <code>relative_offset</code> from the immediate data at <code>PC</code>.</li> <li>Push the current <code>PC + 3</code> to the <code>return stack</code>.</li> <li>Set <code>PC</code> to <code>PC + relative_offset</code>.</li> </ol> <p>The <code>relative_offset</code> is relative to the current <code>PC</code>. The offset is encoded as a two-byte, twos-complement signed integer, stored MSB-first.</p> <p>The gas cost is <em>low</em>.</p> <h4 id="returnsub-0x5e"><code>RETURNSUB (0x5e)</code></h4> <p>Returns control to the caller of a subroutine.</p> <ol> <li>Pop the <code>return stack</code> to <code>PC</code>.</li> </ol> <p>The gas cost is <em>verylow</em>.</p> <p><em>Notes:</em></p> <ul> <li><em>Values popped off the <code>return stack</code> do not need to be validated, since they are alterable only by <code>RJUMPSUB</code> and <code>RETURNSUB</code>.</em></li> <li><em>The description above lays out the semantics of these instructions in terms of a <code>return stack</code>. But the actual state of the <code>return stack</code> is not observable by EVM code or consensus-critical to the protocol. (For example, a node implementer may code <code>RJUMPSUB</code> to unobservably push <code>PC</code> on the <code>return stack</code> rather than <code>PC + 1</code>, which is allowed so long as <code>RETURNSUB</code> observably returns control to the <code>PC + 3</code> location.)</em></li> </ul> <h3 id="validity">Validity</h3> <p><em>Execution</em> is defined in the Yellow Paper as 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 six such states.</p> <ol> <li>Insufficient gas</li> <li>More than 1024 stack items</li> <li>State modification during a static call</li> <li>Insufficient stack items</li> <li>Invalid jump destination</li> <li>Invalid instruction</li> </ol> <p>We would like to consider EVM code valid iff no execution of the program can lead to an exceptional halting state. In practice, we must test at runtime for the first three conditions. We don’t know how much gas there will be, we don’t know how deep a recursion may go, analysis of stack depth even for non-recursive programs is nontrivial, and we don't know whether a call will be static. All of the remaining conditions MUST be validated statically, in time and space quasi-linear in the size of the code.</p> <h4 id="static-constraints-on-valid-code">Static Constraints on Valid Code</h4> <ul> <li>Every instruction MUST be valid: <ul> <li>The <code>JUMP</code> and <code>JUMPI</code> instructions ARE NOT valid.</li> </ul> </li> <li>Every jump MUST be valid: <ul> <li>The <code>RJUMP</code>, <code>RJUMPI</code>, or <code>RJUMPSUB</code> instructions MUST NOT address immediate data or addresses outside of their code section.</li> </ul> </li> <li>The stacks MUST be valid: <ul> <li>The number of items on the <code>data stack</code> MUST always be positive.</li> <li>The number of items on the <code>return stack </code>MUST always be positive.</li> </ul> </li> <li>The data stack MUST be consistently aligned: <ul> <li>The data stack height is <ul> <li>the absolute difference between the current <code>stack pointer</code> and the <code>stack pointer</code> on entry to the current subroutine.</li> </ul> </li> <li>It MUST be the same for every reachable path through a given <code>PC</code> and</li> <li>MUST NOT exceed 1024.</li> </ul> </li> </ul> <h2 id="rationale">Rationale</h2> <p>This is a purely semantic specification, placing no constraints on the syntax of code sections beyond being a sequence of opcodes and immediate data – a subroutine is not a contiguous sequence of bytecode, it is a subgraph of the bytecode's control-flow graph. The EVM is a simple state machine. We only promise that valid code will not, as it were, jam up the gears of the machine.</p> <p>By avoiding syntactic constraints we allow for optimizations like tail call elimination, multiple-entry subroutines, moving "cold" code out of line, and other ways of reducing redundancy and keeping "hot" code in cache. Since we wish to support one-pass compilation of EVM code to machine code it is crucial that the EVM code be as well optimized as possible up front.</p> <h3 id="validation">Validation</h3> <p>Rather than enforce constraints via syntax, we enforce them via validation.</p> <p>The constraints on valid code cover all of the exceptional halting states that we can validate and allow code to be validated and compiled in time and space quasi-linear in the size of the code.</p> <p>The <code>RJUMP</code>, <code>RJUMPI</code> and <code>RJUMPSUB</code> instructions take their <em>relative_offset</em> as immediate arguments, which cannot change at runtime. Having constant destinations for all jumps means that all jump destinations can be validated at initialization time, not runtime. Dynamic jumps can branch to any destination in the code, so exploitable quadratic "path explosions" are possible when traversing the control flow graph. Deprecating <code>JUMP</code> and <code>JUMPI</code> prevents this.</p> <p>Requiring a consistently aligned <code>data stack</code></p> <ul> <li>prevents stack underflow</li> <li>ensures that all calls to a subroutine have the same number of inputs and the same number of outputs and</li> <li>ensures that stack height is bounded in the absence of recursion.</li> </ul> <p>Requiring a consistently aligned <code>data stack</code> also allows some algorithms that traverse the control-flow graph -- including code validation and compilation -- to break cycles at joins, again preventing quadratic path explosion. When a traversal gets to a <code>PC</code> it has visited before it is either at the beginning of a loop or the entry to a function. Since the stack height at that <code>PC</code> is constant we know that loops will not grow stack, and that the number of arguments to a subroutine will always be the same -- there may be no need to traverse that path again.</p> <p><em>Note: The JVM and Wasm enforce similar constraints for similar reasons.</em></p> <h3 id="alternative-designs">Alternative Designs</h3> <p>There are a few major designs for a subroutine facility, two of which are considered here. The others are mostly not appropriate for the EVM, such as the Wheeler Jump -- self-modifying code that writes return addresses into called subroutines.</p> <p><em>1. Keep return addresses on a dedicated return stack.</em> Turing's design is often used by stack machines, including those for Forth, Java, Wasm, and others. The data stack is used for computation, with a dedicated stack for return addresses. A single instruction suffices to call, and another to return from a routine.</p> <p><em>2. Keep return addresses on the data stack.</em> This design is often used by register machines, including those from CDC, IBM, DEC, Intel, and ARM. The registers are used primarily for computation, and the stack maintains call frames for return addresses, arguments, and local variables. On the EVM there are no registers for computation, so using the stack for both purposes can cause the sort of inefficiencies we see below. Pascal p-code does use this design, but as part of a complex calling convention with dedicated registers.</p> <h4 id="we-prefer-the-dedicated-return-stack">We prefer the dedicated return stack.</h4> <ul> <li>It maintains a clear separation between calculation and flow of control: <ul> <li>the data stack is free of vulnerable return addresses and</li> <li>it's impossible to overwrite the return stack.</li> </ul> </li> <li>It improves efficiency: <ul> <li>it uses native arithmetic rather than 256-bit EVM instructions for the return address,</li> <li>doesn't use up a <code>data stack</code> slot for the return address and</li> <li>needs less motion of 256-bit data on the stack.</li> </ul> </li> </ul> <h3 id="efficiency">Efficiency</h3> <p>We illustrate here how subroutine instructions can be used to reduce the complexity and gas costs of both ordinary and optimized subroutine calls compared to using <code>JUMP</code>.</p> <h4 id="simple-subroutine-call"><strong>Simple Subroutine Call</strong></h4> <p>Consider these examples of a fairly minimal subroutine, including the code to call it.</p> <p>Subroutine call, using <code>RJUMPSUB</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>SQUARE:</span></span> <span class="giallo-l"><span> dup1 ; 3 gas</span></span> <span class="giallo-l"><span> mul ; 5 gas</span></span> <span class="giallo-l"><span> returnsub ; 3 gas</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>CALL_SQUARE:</span></span> <span class="giallo-l"><span> push 0x02 ; 3 gas</span></span> <span class="giallo-l"><span> rjumpsub SQUARE ; 5 gas</span></span></code></pre> <p><em>Total gas: 19</em></p> <p>Subroutine call, using <code>JUMP</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>SQUARE:</span></span> <span class="giallo-l"><span> jumpdest ; 1 gas</span></span> <span class="giallo-l"><span> swap1 ; 3 gas</span></span> <span class="giallo-l"><span> dup1 ; 3 gas</span></span> <span class="giallo-l"><span> mul ; 5 gas</span></span> <span class="giallo-l"><span> swap1 ; 3 gas</span></span> <span class="giallo-l"><span> jump ; 8 gas</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>CALL_SQUARE:</span></span> <span class="giallo-l"><span> jumpdest ; 1 gas</span></span> <span class="giallo-l"><span> push 0x02 ; 3 gas</span></span> <span class="giallo-l"><span> push RTN_CALL: ; 3 gas</span></span> <span class="giallo-l"><span> push SQUARE ; 3 gas</span></span> <span class="giallo-l"><span> jump ; 8 gas</span></span> <span class="giallo-l"><span>RTN_CALL:</span></span> <span class="giallo-l"><span> jumpdest ; 1 gas</span></span></code></pre> <p><em>Total: 41 gas</em>.</p> <p>Using <code>RJUMPSUB</code> versus <code>JUMP</code> saves <em>41 - 19 = 22 gas</em> — a <em>54%</em> improvement.</p> <h4 id="tail-call-optimization"><strong>Tail Call Optimization</strong></h4> <p>Of course in cases like this one we can optimize the tail call, so that the return from <code>SQUARE</code> actually returns from <code>TEST_SQUARE</code>.</p> <p>Tail call optimization, using <code>RJUMPSUB</code> and <code>RETURNSUB</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>SQUARE:</span></span> <span class="giallo-l"><span> dup1 ; 3 gas</span></span> <span class="giallo-l"><span> mul ; 5 gas</span></span> <span class="giallo-l"><span> returnsub ; 3 gas</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>CALL_SQUARE:</span></span> <span class="giallo-l"><span> push 0x02 ; 3 gas</span></span> <span class="giallo-l"><span> rjump SQUARE ; 3 gas</span></span></code></pre> <p><em>Total: 17 gas</em></p> <p>Tail call optimization, using <code>JUMP</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>SQUARE:</span></span> <span class="giallo-l"><span> jumpdest ; 1 gas</span></span> <span class="giallo-l"><span> swap1 ; 3 gas</span></span> <span class="giallo-l"><span> dup1 ; 3 gas</span></span> <span class="giallo-l"><span> mul ; 5 gas</span></span> <span class="giallo-l"><span> swap2 ; 3 gas</span></span> <span class="giallo-l"><span> jump ; 8 gas</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>CALL_SQUARE:</span></span> <span class="giallo-l"><span> jumpdest ; 1 gas</span></span> <span class="giallo-l"><span> push 0x02 ; 3 gas</span></span> <span class="giallo-l"><span> push SQUARE ; 3 gas</span></span> <span class="giallo-l"><span> jump ; 8 gas</span></span></code></pre> <p><em>Total: 38 gas</em></p> <p>Using <code>RJUMPSUB</code> versus <code>JUMP</code> saves <em>38 - 17 = 21 gas</em> — a <em>55%</em> improvement.</p> <h4 id="efficiency-caveats">Efficiency Caveats</h4> <p>We can see that these instructions provide a simpler and more gas-efficient subroutine mechanism than using <code>JUMP</code> — in our examples they cut gas use by about half.</p> <p>Clearly, the benefits of this efficiency are greater for programs that have been factored into smaller subroutines. How small? Wrapping code in a subroutine costs only <em>8 gas</em> using <code>RJUMPSUB</code> and <code>RETURNSUB</code> versus <em>30 gas</em> using <code>JUMP</code>, <code>PUSH</code> and <code>SWAP</code> as above.</p> <h3 id="costs">Costs</h3> <p>The <em>low</em> cost of <code>RJUMPSUB</code> versus the <em>mid</em> cost of <code>JUMP</code> is justified by needing only to decode the immediate two byte destination to the <code>PC</code> and push the return address on the <code>return stack</code>, all using native arithmetic, versus using the data stack with emulated 256-bit instructions.</p> <p>The <em>verylow</em> cost of <code>RETURNSUB</code> is justified by needing only to pop the <code>return stack</code> into the <code>PC</code>. Benchmarking will be needed to tell if the costs are well-balanced.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>These changes affect the semantics of existing EVM code: bytes that would have been interpreted as valid jump destinations may now be interpreted as immediate data. Since this proposal depends on the Ethereum Object Format to signal the change this is not a practical issue.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="simple-routine">Simple routine</h3> <p>This should jump into a subroutine, back out and stop.</p> <p>Bytecode: <code>0x5f0003005e</code> (<code>RJUMPSUB 3, RETURNSUB, STOP</code>)</p> <table><thead><tr><th>Pc</th><th>Op</th><th>Cost</th><th>Stack</th><th>RStack</th></tr></thead><tbody> <tr><td>0</td><td>RJUMPSUB</td><td>5</td><td>[]</td><td>[]</td></tr> <tr><td>2</td><td>STOP</td><td>0</td><td>[]</td><td>[]</td></tr> <tr><td>3</td><td>RETURNSUB</td><td>3</td><td>[]</td><td>[]</td></tr> </tbody></table> <p>Output: 0x Consumed gas: <code>10</code></p> <h3 id="two-levels-of-subroutines">Two levels of subroutines</h3> <p>This should execute fine, going into one two depths of subroutines</p> <p>Bytecode: <code>0x5f00045F00025200</code> (<code>RJUMPSUB 4, RJUMPSUB 2, RETURNSUB, RETURNSUB, STOP</code>)</p> <table><thead><tr><th>Pc</th><th>Op</th><th>Cost</th><th>Stack</th><th>RStack</th></tr></thead><tbody> <tr><td>0</td><td>RJUMPSUB</td><td>5</td><td>[]</td><td>[]</td></tr> <tr><td>3</td><td>RJUMPSUB</td><td>5</td><td>[]</td><td>[]</td></tr> <tr><td>4</td><td>RETURNSUB</td><td>5</td><td>[]</td><td>[]</td></tr> <tr><td>5</td><td>RETURNSUB</td><td>5</td><td>[]</td><td>[]</td></tr> <tr><td>6</td><td>STOP</td><td>0</td><td>[]</td><td>[]</td></tr> </tbody></table> <p>Consumed gas: <code>20</code></p> <h3 id="failure-1-invalid-jump">Failure 1: invalid jump</h3> <p>This should fail, since the given location is outside of the code-range.</p> <p>Bytecode: <code>0X5fff</code>(<code>RJUMPSUB -1</code>)</p> <table><thead><tr><th>Pc</th><th>Op</th><th>Cost</th><th>Stack</th><th>RStack</th></tr></thead><tbody> <tr><td>0</td><td>RJUMPSUB</td><td>10</td><td>[]</td><td>[]</td></tr> </tbody></table> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Error: at pc=0, op=RJUMPSUB: invalid jump destination</span></span></code></pre><h3 id="failure-2-shallow-return-stack">Failure 2: shallow <code>return stack</code></h3> <p>This should fail at first opcode, due to shallow <code>return_stack</code></p> <p>Bytecode: <code>0x5e</code> (<code>RETURNSUB</code>)</p> <table><thead><tr><th>Pc</th><th>Op</th><th>Cost</th><th>Stack</th><th>RStack</th></tr></thead><tbody> <tr><td>0</td><td>RETURNSUB</td><td>5</td><td>[]</td><td>[]</td></tr> </tbody></table> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Error: at pc=0, op=RETURNSUB: invalid retsub</span></span></code></pre><h3 id="subroutine-at-end-of-code">Subroutine at end of code</h3> <p>In this example the RJUMPSUB is on the last byte of code. When the subroutine returns, it should hit the 'virtual stop' <em>after</em> the bytecode, and not exit with error</p> <p>Bytecode: <code>0x5c00045e5fffff</code> (<code>RJUMP 4, RETURNSUB, RJUMPSUB -1</code>)</p> <table><thead><tr><th>Pc</th><th>Op</th><th>Cost</th><th>Stack</th><th>RStack</th></tr></thead><tbody> <tr><td>0</td><td>RJUMP</td><td>5</td><td>[]</td><td>[]</td></tr> <tr><td>3</td><td>RETURNSUB</td><td>5</td><td>[]</td><td>[]</td></tr> <tr><td>4</td><td>RJUMPSUB</td><td>5</td><td>[]</td><td>[]</td></tr> <tr><td>7</td><td>STOP</td><td>0</td><td>[]</td><td>[]</td></tr> </tbody></table> <p>Consumed gas: <code>15</code></p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The following is a pseudo-Python implementation of an algorithm for predicating code validity. An equivalent algorithm must be run at initialization time.</p> <p>This algorithm performs a symbolic execution of the program that recursively traverses the <em>code</em>, emulating its control flow and stack use and checking for violations of the rules above.</p> <p>It runs in time equal to <code>O(vertices + edges)</code> in the program's control-flow graph, where edges represent control flow and the vertices represent <em>basic blocks</em> — thus the algorithm takes time proportional to the size of the <em>code</em>. It maintains a stack of continuations for conditional jumps, the size of which is at most proportional to the size of the <em>code</em>.</p> <h3 id="validation-function">Validation Function</h3> <p>** Note: this function is known to be incomplete and incorrect. **</p> <p>For simplicity's sake we assume that all jumpdest analysis and prior validation has been done, including EIP-3540, EIP-3670, and EIP-4200, so EOF headers and sections are well-formed, and there are no invalid instructions or jumps. In practice, all passes of validation can be folded into a single loop no recursion.</p> <p>We also assume some helper functions.</p> <ul> <li><code>is_valid(opcode)</code> returns true iff opcode is valid.</li> <li><code>is_terminator(opcode)</code> returns true iff opcode is terminator.</li> <li><code>is_valid_jumpdest(pc)</code> returns true iff <code>pc</code> is a valid jump destination.</li> <li><code>immediate_data(pc)</code> returns the immediate data for the instruction at <code>pc</code>.</li> <li><code>immediate_size(opcode)</code> returns the size of the immediate data for an opcode.</li> <li><code>removed_items(opcode)</code> returns the number of items removed from the <code>data_stack</code> by the <code>opcode</code>.</li> <li><code>added_items(opcode)</code> returns the number of items added to the <code>data_stack</code> by the <code>opcode</code>.</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span># returns true iff code is valid</span></span> <span class="giallo-l"><span>def validate_code(code: bytes, pc: int, sp: int, bp: int) -&gt; boolean:</span></span> <span class="giallo-l"><span> continuations = []</span></span> <span class="giallo-l"><span> do</span></span> <span class="giallo-l"><span> while pc &lt; len(code):</span></span> <span class="giallo-l"><span> opcode = code[pc]</span></span> <span class="giallo-l"><span> if !is_valid(opcode):</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"><span> if is_terminator(opcode):</span></span> <span class="giallo-l"><span> return true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # check stack height and return if we have been here before</span></span> <span class="giallo-l"><span> stack_height = sp - bp</span></span> <span class="giallo-l"><span> if stack_height &gt; 1024</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"><span> if pos in stack_heights:</span></span> <span class="giallo-l"><span> if stack_height != stack_heights[pos]:</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> else:</span></span> <span class="giallo-l"><span> stack_heights[pos] = stack_height</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if opcode == RJUMP:</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> jumpdest = immediate_data(pc)</span></span> <span class="giallo-l"><span> pc += jumpdest</span></span> <span class="giallo-l"><span> if !is_valid_jumpdest(pc)</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> elif opcode == RJUMPI:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> jumpdest = pc + immediate_data(pc)</span></span> <span class="giallo-l"><span> if !is_valid_jumpdest(pc)</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # continue true side of conditional later</span></span> <span class="giallo-l"><span> continations.push((jumpdest, sp, bp))</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # continue false side of conditional now</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> elif opcode == RJUMPSUB:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # will enter subroutine at destination</span></span> <span class="giallo-l"><span> bp = sp</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # push return address and reset pc to destination</span></span> <span class="giallo-l"><span> jumpdest = pc + immediate_data(pc)</span></span> <span class="giallo-l"><span> if !is_valid_jumpdest(pc)</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"><span> push(return_stack, pc + 3)</span></span> <span class="giallo-l"><span> pc = jumpdest</span></span> <span class="giallo-l"><span> continue</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> elif opcode == RETURNSUB:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # will return to subroutine at destination</span></span> <span class="giallo-l"><span> bp = sp</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # pop return address and check for preceding call</span></span> <span class="giallo-l"><span> pc = pop(return_stack)</span></span> <span class="giallo-l"><span> if code[pc - 3] != RJUMPSUB:</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # apply instructions to stack</span></span> <span class="giallo-l"><span> sp -= removed_items(opcode)</span></span> <span class="giallo-l"><span> if sp &lt; 0</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"><span> sp += added_items(opcode)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # Skip opcode and immediate data</span></span> <span class="giallo-l"><span> pc += 1 + immediate_size(opcode)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> while (pc, sp, bp) = continuations.pop()</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> return true</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>These changes introduce new flow control instructions. They do not introduce any new security considerations. This EIP is intended to improve security by validating a higher level of safety for EVM code deployed on the blockchain. The validation algorithm must be quasi-linear in time and space to not be a denial of service vulnerability. The algorithm here makes one linear-time pass of the bytecode, and uses a stack of continuations that cannot exceed the number of <code>RJUMPI</code> instructions in the 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> 2019-10-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Sean Papanikolashttps://github.com/pizzarob https://wg-eips.ritovision.com/2309/ <h2 id="simple-summary">Simple Summary</h2> <p>A standardized event emitted when creating/transferring one, or many non-fungible tokens using consecutive token identifiers.</p> <h2 id="abstract">Abstract</h2> <p>The optional ERC-721 Consecutive Transfer Extension provides a standardized event which could be emitted during the creation/transfer of one, or many non-fungible tokens. This standard does not set the expectation of how you might create/transfer many tokens it is only concerned with the event emitted after the creation, or transfer of ownership of these tokens. This extension assumes that token identifiers are in consecutive order.</p> <h2 id="motivation">Motivation</h2> <p>This extension provides even more scalibility of the <a href="https://wg-eips.ritovision.com/721/">ERC-721 specification</a>. It is possible to create, transfer, and burn 2^256 non-fungible tokens in one transaction. However, it is not possible to emit that many <code>Transfer</code> events in one transaction. The <code>Transfer</code> event is part of the original specification which states:</p> <blockquote> <p>This emits when ownership of any NFT changes by any mechanism. This event emits when NFTs are created (<code>from</code> == 0) and destroyed (<code>to</code> == 0). Exception: during contract creation, any number of NFTs may be created and assigned without emitting Transfer. At the time of any transfer, the approved address for that NFT (if any) is reset to none.</p> </blockquote> <p>This allows for the original <code>Transfer</code> event to be emitted for one token at a time, which in turn gives us O(n) time complexity. Minting one billion NFTs can be done in one transaction using efficient data structures, but in order to emit the <code>Transfer</code> event - according to the original spec - one would need a loop with one billion iterations which is bound to run out of gas, or exceed transaction timeout limits. This cannot be accomplished with the current spec. This extension solves that problem.</p> <p>Many decentralized marketplaces and block explorers utilize the <code>Transfer</code> event as a way to determine which NFTs an address owns. The Consecutive Transfer Extension provides a standard mechanism for these platforms to use to determine ownership of many tokens.</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>ERC-721 compliant contracts MAY implement this Consecutive Transfer Extension to provide a standard event to be emitted at the time of creation, burn, or transfer of one or many consecutive tokens</strong></p> <p>The address executing the transaction <strong>MUST</strong> own all the tokens within the range of <code>fromTokenId</code> and <code>toTokenId</code>, or <strong>MUST</strong> be an approved operator to act on the owners behalf.</p> <p>The <code>fromTokenId</code> and <code>toTokenId</code> <strong>MUST</strong> be a consecutive range of tokens IDs.</p> <p>The <code>fromTokenId</code>, <code>fromAddress</code>, and <code>toAddress</code> <strong>MUST</strong> be indexed parameters</p> <p>The <code>toTokenId</code> <strong>MUST NOT</strong> be an indexed parameter</p> <p>When minting/creating tokens, the <code>fromAddress</code> argument <strong>MUST</strong> be set to <code>0x0</code> (i.e. zero address).</p> <p>When burning/destroying tokens, the <code>toAddress</code> argument <strong>MUST</strong> be set to <code>0x0</code> (i.e. zero address).</p> <p>When emitting the ConsecutiveTransfer event the Transfer event <strong>MUST NOT</strong> be emitted</p> <p>Contracts that implement the <code>ConsecutiveTransfer</code> event <strong>MAY</strong> still use the original <code>Transfer</code> event, however when emitting the <code>ConsecutiveTransfer</code> event the <code>Transfer</code> event <strong>MUST NOT</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"> ConsecutiveTransfer</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> fromTokenId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> toTokenId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> fromAddress</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> toAddress</span><span>)</span><span>;</span></span></code></pre><h3 id="examples">Examples</h3> <p>The <code>ConsecutiveTransfer</code> event can be used for a single token as well as many tokens:</p> <p><strong>Single token creation</strong></p> <p><code>emit ConsecutiveTransfer(1, 1, address(0), toAddress);</code></p> <p><strong>Batch token creation</strong></p> <p><code>emit ConsecutiveTransfer(1, 100000, address(0), toAddress);</code></p> <p><strong>Batch token transfer</strong></p> <p><code>emit ConsecutiveTransfer(1, 100000, fromAddress, toAddress);</code></p> <p><strong>Burn</strong></p> <p><code>emit ConsecutiveTransfer(1, 100000, from, address(0));</code></p> <h2 id="rationale">Rationale</h2> <p>Standardizing the <code>ConsecutiveTransfer</code> event gives decentralized platforms a standard way of determining ownership of large quantities of non-fungible tokens without the need to support a new token standard. There are many ways in which the batch creation and transfer of NFTs can be implemented. The Consecutive Transfer Extension allows contract creators to implement batch creation, transfer, and burn methods however they see fit, but provides a standardized event in which all implementations can use. By specifying a range of consecutive token identifiers we can easily cover the transfer, or creation of 2^(256) tokens and decentralized platforms can react accordingly.</p> <p>Take this example. I sell magical fruit and have a farm with 10,000 magical fruit trees each with different fruit and 1,000 new trees every few years. I want to turn each tree into a non-fungible token that people can own. Each person that owns one of my non-fungible tree tokens will receive a quarterly percentage of each harvest from that tree. The problem is that I would need to create and transfer each of these tokens individually - which will cost me a lot of time and money and frankly would keep me from doing this.</p> <p>With this extension I would be able to mint my initial 10,000 tree tokens in one transaction. I would be able to quickly and cheaply mint my additional 1,000 tree tokens when a new batch is planted. I would then be able to transfer all of the 10,000+ tree tokens to a special smart contract that keeps track of the selling and distribution of funds in one transaction all while adhering to a specified standard.</p> <p><strong>Rationale to have a single event that covers minting, burning, and transferring</strong></p> <p>The <code>ConsecutiveTransfer</code> event can be used to cover minting, burning, and transferring events. While there may have been confusion in the beginning adhering to transfer to/from "0" pattern this is mitigated by checking for the <code>ConsecutiveTransfer</code> topic and verifying the emitting contract supports the ERC-721 interface by using the ERC-165 standard.</p> <p><strong>Indexed event parameters</strong></p> <p>Events in Solidity can have up to three indexed parameters which will make it possible to filter for specific values of indexed arguments. This standard sets the <code>fromAddress</code>, <code>toAddress</code>, and <code>fromTokenId</code> as the indexed parameters. The <code>toTokenId</code> can be retrieved from the data part of the log. The reason for this is that more often than not one may be searching for events to learn about the history of ownership for a given address. The <code>fromTokenId</code> can then be retrieved along with the other two indexed parameters for simplicity. Then one only needs to decode the log data which is ensured to be the <code>toTokenId</code>.</p> <p><strong>Rationale to not emit <code>Transfer</code> when <code>ConsecutiveTransfer</code> is also emitted</strong></p> <p>This can lead to bugs and unnecessary complex logic for platforms using these events to track token ownership. When transferring a single token it is acceptable to emit the original <code>Transfer</code> event, but the <code>ConsecutiveTransfer</code> event should not be emitted during the same transaction and vice-versa.</p> <p><strong>Comparing 2309 and 1155</strong></p> <p>As the NFT market continues to grow so does the need for the ability to scale the smart contracts. Users need to be able to do things like mint a massive amount of tokens at one time, transfer a massive amount of tokens, and be able to track ownership of all these assets. We need to do this in a way that is cost effective and doesn’t fail under the confines of the Ethereum blockchain. As millions of tokens are minted we need contracts with the ability to scale.</p> <p><a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> was created and added as a standard in 2019 to try to solve these problems, but it falls short when it comes to minting massive amounts of unique tokens in a cost-effective way. With ERC-1155 it’s either going to cost hundreds (or thousands) of dollars or it’s going to run out of gas. ERC-1155 works well when minting many semi-fungible tokens but falls short when minting many unique tokens. Using the 2309 standard you could mint millions of blank NFTs upfront and update the metadata for each one in a cost effective way.</p> <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 track the creation, transfer, and deletion of a massive amount of tokens. While it is a minimal change the effects on platforms that only use the original <code>Transfer</code> event to index token ownership would be severe. They would not be properly recording token ownership information that could be known by listening for the <code>ConsecutiveTransfer</code> event. For platforms that wish to support the <code>ConsecutiveTransfer</code> event it would be best to support both the original <code>Transfer</code> event and the <code>ConsecutiveTransfer</code> event to track token ownership.</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> 2019-09-30T00:00:00+00:00 2026-02-11T14:48:26+00:00 Carl Beekhuizenhttps://github.com/CarlBeekcarl@ethereum.org https://wg-eips.ritovision.com/2333/

BLS12-381 Key Generation using a hierarchical tree

<h2 id="abstract">Abstract</h2> <p>This standard is a method for deriving a tree-hierarchy of BLS12-381 keys based on an entropy seed. Starting with the aforementioned seed, a tree of keys is built out using only the parent node's private key and the index of the desired child. This allows for a practically limitless number of keys to be derived for many different purposes while only requiring knowledge of a single ancestor key in the tree. This allows for keys, or families thereof, to be provisioned for different purposes by further standards.</p> <p>In addition to the above, this method of deriving keys provides an emergency backup signature scheme that is resistant to quantum computers for in the event that BLS12-381 is ever deemed insecure.</p> <h2 id="motivation">Motivation</h2> <h3 id="deficiencies-of-the-existing-mechanism">Deficiencies of the existing mechanism</h3> <p>The curve BLS12-381 used for BLS signatures within the Beacon chain (alongside many other projects) mandates a new key derivation scheme. The most commonly used scheme for key derivation within Ethereum for secp256k1 keys is <a rel="external" href="https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0032.mediawiki">BIP32</a> (also known as HD derivation) which deems keys greater than the curve order invalid. Based on the order of the private key subgroup of BLS12-381 and the size of the entropy utilised, more than 54% of keys generated by BIP32 would be invalid. (secp256k1 keys derived by BIP32 are invalid with probability less than 1 in 2^-127.)</p> <h3 id="establishing-a-multi-chain-standard-early-on">Establishing a multi-chain standard early on</h3> <p>By establishing a standard before the first users begin to generate their keys, the hope is that a single standard is highly pervasive and therefore can be assumed to be the method by which the majority of keys are provided. This is valuable for two reasons, firstly in order for a post-quantum backup mechanism to be effective, there needs to be an enshrined mechanism whereby users can switch to a post-quantum signature scheme with pre-shared public keys (something this EIP provides at 0 extra storage cost). Secondly, this unifies the inter- and intra-chain ecosystem by having common tooling ideally allowing users to switch between key-management systems.</p> <h3 id="a-post-quantum-backup">A post-quantum backup</h3> <p>This key derivation scheme has a Lamport key pair which is generated as a intermediate step in the key generation process. This key pair can be used to provide a Lamport signature which is a useful backup in the event of BLS12-381 no longer being considered secure (in the event of quantum computing making a sudden advancement, for example). The idea is the Lamport signature will act as a bridge to a new signature scheme which is deemed to be secure.</p> <h2 id="specification">Specification</h2> <h3 id="version">Version</h3> <p>Due to the evolving BLS signatures CFRG draft (currently v4), the <code>KeyGen</code> function was updated, meaning that <code>hkdf_mod_r</code> no longer reflected what appeared in the BLS standard. This EIP was updated on the 17th of September 2020 to reflect this new method for deriving keys, <strong>if you are implementing this EIP, please make sure your version is up to date.</strong></p> <h3 id="specification-1">Specification</h3> <p>Keys are defined in terms of a tree structure where a key is determined by the tree's seed and a tree path. This is very useful as one can start with a single source of entropy and build out a practically unlimited number of keys. The specification can be broken into two sub-components: generating the master key, and constructing a child key from its parent. The master key is used as the root of the tree and then the tree is built in layers on top of this root.</p> <h3 id="the-tree-structure">The Tree Structure</h3> <p>The key tree is defined purely through the relationship between a child-node and its ancestors. Starting with the root of the tree, the <em>master key</em>, a child node can be derived by knowing the parent's private key and the index of the child. The tree is broken up into depths which are indicated by <code>/</code> and the master node is described as <code>m</code>. The first child of the master node is therefore described as <code>m / 0</code> and <code>m / 0</code>'s siblings are <code>m / i</code> for all <code>0 &lt;= i &lt; 2**32</code>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> [m / 0] - [m / 0 / 0]</span></span> <span class="giallo-l"><span> / \</span></span> <span class="giallo-l"><span> / [m / 0 / 1]</span></span> <span class="giallo-l"><span>[m] - [m / 1]</span></span> <span class="giallo-l"><span> \</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span> [m / i]</span></span></code></pre><h3 id="key-derivation">Key derivation</h3> <p>Every key generated via the key derivation process derives a child key via a set of intermediate Lamport keys. The idea behind the Lamport keys is to provide a post-quantum backup in case BLS12-381 is no longer deemed secure. At a high level, the key derivation process works by using the parent node's privkey as an entropy source for the Lamport private keys which are then hashed together into a compressed Lamport public key, this public key is then hashed into BLS12-381's private key group.</p> <h4 id="ikm-to-lamport-sk"><code>IKM_to_lamport_SK</code></h4> <h5 id="inputs">Inputs</h5> <ul> <li><code>IKM</code>, a secret octet string</li> <li><code>salt</code>, an octet string</li> </ul> <h5 id="outputs">Outputs</h5> <ul> <li><code>lamport_SK</code>, an array of 255 32-octet strings</li> </ul> <h5 id="definitions">Definitions</h5> <ul> <li><code>HKDF-Extract</code> is as defined in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc5869">RFC5869</a>, instantiated with SHA256</li> <li><code>HKDF-Expand</code> is as defined in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc5869">RFC5869</a>, instantiated with SHA256</li> <li><code>K = 32</code> is the digest size (in octets) of the hash function (SHA256)</li> <li><code>L = K * 255</code> is the HKDF output size (in octets)</li> <li><code>""</code> is the empty string</li> <li><code>bytes_split</code> is a function takes in an octet string and splits it into <code>K</code>-byte chunks which are returned as an array</li> </ul> <h5 id="procedure">Procedure</h5> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0. PRK = HKDF-Extract(salt, IKM)</span></span> <span class="giallo-l"><span>1. OKM = HKDF-Expand(PRK, &quot;&quot; , L)</span></span> <span class="giallo-l"><span>2. lamport_SK = bytes_split(OKM, K)</span></span> <span class="giallo-l"><span>3. return lamport_SK</span></span></code></pre><h4 id="parent-sk-to-lamport-pk"><code>parent_SK_to_lamport_PK</code></h4> <h5 id="inputs-1">Inputs</h5> <ul> <li><code>parent_SK</code>, the BLS Secret Key of the parent node</li> <li><code>index</code>, the index of the desired child node, an integer <code>0 &lt;= index &lt; 2^32</code></li> </ul> <h5 id="outputs-1">Outputs</h5> <ul> <li><code>lamport_PK</code>, the compressed lamport PK, a 32 octet string</li> </ul> <h5 id="definitions-1">Definitions</h5> <ul> <li><code>I2OSP</code> is as defined in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc3447">RFC3447</a> (Big endian decoding)</li> <li><code>flip_bits</code> is a function that returns the bitwise negation of its input</li> <li><code>""</code> is the empty string</li> <li><code>a | b</code> is the concatenation of <code>a</code> with <code>b</code></li> </ul> <h5 id="procedure-1">Procedure</h5> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0. salt = I2OSP(index, 4)</span></span> <span class="giallo-l"><span>1. IKM = I2OSP(parent_SK, 32)</span></span> <span class="giallo-l"><span>2. lamport_0 = IKM_to_lamport_SK(IKM, salt)</span></span> <span class="giallo-l"><span>3. not_IKM = flip_bits(IKM)</span></span> <span class="giallo-l"><span>4. lamport_1 = IKM_to_lamport_SK(not_IKM, salt)</span></span> <span class="giallo-l"><span>5. lamport_PK = &quot;&quot;</span></span> <span class="giallo-l"><span>6. for i in 1, .., 255</span></span> <span class="giallo-l"><span> lamport_PK = lamport_PK | SHA256(lamport_0[i])</span></span> <span class="giallo-l"><span>7. for i in 1, .., 255</span></span> <span class="giallo-l"><span> lamport_PK = lamport_PK | SHA256(lamport_1[i])</span></span> <span class="giallo-l"><span>8. compressed_lamport_PK = SHA256(lamport_PK)</span></span> <span class="giallo-l"><span>9. return compressed_lamport_PK</span></span></code></pre> <p><strong>Note:</strong> The indexing, <code>i</code>, in the above procedure iterates from 1 to 255 (inclusive). This is due to the limit to which HKDF can stretch the input bytes (255 times the length of the input bytes). The result of this is that the security of the lamport-backup signature is *only* 127.5 bit.</p> <h4 id="hkdf-mod-r"><code>HKDF_mod_r</code></h4> <p><code>hkdf_mod_r()</code> is used to hash 32 random bytes into the subgroup of the BLS12-381 private keys.</p> <h5 id="inputs-2">Inputs</h5> <ul> <li><code>IKM</code>, a secret octet string &gt;= 256 bits in length</li> <li><code>key_info</code>, an optional octet string (default=<code>""</code>, the empty string)</li> </ul> <h5 id="outputs-2">Outputs</h5> <ul> <li><code>SK</code>, the corresponding secret key, an integer 0 &lt;= SK &lt; r.</li> </ul> <h5 id="definitions-2">Definitions</h5> <ul> <li><code>HKDF-Extract</code> is as defined in RFC5869, instantiated with hash H.</li> <li><code>HKDF-Expand</code> is as defined in RFC5869, instantiated with hash H.</li> <li><code>L</code> is the integer given by <code>ceil((3 * ceil(log2(r))) / 16)</code>.(<code>L=48</code>)</li> <li><code>"BLS-SIG-KEYGEN-SALT-"</code> is an ASCII string comprising 20 octets.</li> <li><code>OS2IP</code> is as defined in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc3447">RFC3447</a> (Big endian encoding)</li> <li><code>I2OSP</code> is as defined in <a rel="external" href="https://www.rfc-editor.org/rfc/rfc3447">RFC3447</a> (Big endian decoding)</li> <li><code>r</code> is the order of the BLS 12-381 curve defined in the draft IETF BLS signature scheme standard.<code>r=52435875175126190479447740508185965837690552500527637822603658699938581184513</code></li> </ul> <h5 id="procedure-2">Procedure</h5> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>1. salt = &quot;BLS-SIG-KEYGEN-SALT-&quot;</span></span> <span class="giallo-l"><span>2. SK = 0</span></span> <span class="giallo-l"><span>3. while SK == 0:</span></span> <span class="giallo-l"><span>4. salt = H(salt)</span></span> <span class="giallo-l"><span>5. PRK = HKDF-Extract(salt, IKM || I2OSP(0, 1))</span></span> <span class="giallo-l"><span>6. OKM = HKDF-Expand(PRK, key_info || I2OSP(L, 2), L)</span></span> <span class="giallo-l"><span>7. SK = OS2IP(OKM) mod r</span></span> <span class="giallo-l"><span>8. return SK</span></span></code></pre><h3 id="derive-child-sk"><code>derive_child_SK</code></h3> <p>The child key derivation function takes in the parent's private key and the index of the child and returns the child private key.</p> <h5 id="inputs-3">Inputs</h5> <ul> <li><code>parent_SK</code>, the secret key of the parent node, a big endian encoded integer</li> <li><code>index</code>, the index of the desired child node, an integer <code>0 &lt;= index &lt; 2^32</code></li> </ul> <h5 id="outputs-3">Outputs</h5> <ul> <li><code>child_SK</code>, the secret key of the child node, a big endian encoded integer</li> </ul> <h5 id="procedure-3">Procedure</h5> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0. compressed_lamport_PK = parent_SK_to_lamport_PK(parent_SK, index)</span></span> <span class="giallo-l"><span>1. SK = HKDF_mod_r(compressed_lamport_PK)</span></span> <span class="giallo-l"><span>2. return SK</span></span></code></pre><h3 id="derive-master-sk"><code>derive_master_SK</code></h3> <p>The child key derivation function takes in the parent's private key and the index of the child and returns the child private key. The seed should ideally be derived from a mnemonic, with the intention being that the <a rel="external" href="https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0039.mediawiki">BIP-39 mnemonic_to_seed method</a> be used.</p> <h5 id="inputs-4">Inputs</h5> <ul> <li><code>seed</code>, the source entropy for the entire tree, a octet string &gt;= 256 bits in length</li> </ul> <h5 id="outputs-4">Outputs</h5> <ul> <li><code>SK</code>, the secret key of master node within the tree, a big endian encoded integer</li> </ul> <h5 id="procedure-4">Procedure</h5> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0. SK = HKDF_mod_r(seed)</span></span> <span class="giallo-l"><span>1. return SK</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="lamport-signatures">Lamport signatures</h3> <p>Lamport signatures are used as the backup mechanism because of their relative simplicity for a post-quantum signature scheme. Lamport signatures are very easy both to explain and implement as the sole cryptographic dependency is a secure hash function. This is important as it minimises the complexity of implementing this standard as well as the compute time for deriving a key. Lamport signatures have very large key sizes which make them impractical for many use cases, but this is not deemed to be an issue in this case as this scheme is only meant to be a once-off event to migrate to a new scheme.</p> <p>Revealing the associated Lamport public key for a corresponding BLS key is done by verifying that the Lamport public key is the pre-image of the corresponding BLS private key (which in turn is verified against the BLS public key). This means that using a key's Lamport signature reveals the BLS private key rendering the BLS key pair unsafe. This has the upside of not requiring additional storage space for backup keys alongside BLS keys but does require that the Lamport signatures be used once and that the BLS key is no longer trusted after that point.</p> <p>The Lamport signatures used within this scheme have 255 bits worth of security, not 256. This is done because HKDF-SHA256, the mechanism used to stretch a key's entropy, has a length-limit of <code>255 * hash_function_digest_size</code>. The 1-bit reduction in security is deemed preferable over increasing the complexity of the entropy stretching mechanism.</p> <h3 id="sha256">SHA256</h3> <p>SHA256 is used as the hash function throughout this standard as it is the hash function chosen by the IETF BLS signature proposed standard. Using a single hash function for everything decreases the number of cryptographic primitives required to implement the entire BLS standardised key-stack while reducing the surface for flaws in the overall system.</p> <h3 id="hkdf-mod-r-1"><code>hkdf_mod_r()</code></h3> <p>The function <code>hkdf_mod_r()</code> in this standard is the same as the <code>KeyGen</code> function described in the draft IETF signature standard and therefore the private key obtained from <code>KeyGen</code> is equal to that obtained from <code>hkdf_mod_r</code> for the same seed bytes. This means that common engineering can be done when implementing this function. Additionally because of its inclusion in an IETF standard, it has had much scrutiny by many cryptographers and cryptanalysts, thereby lending credence to its safety as a key derivation mechanism.</p> <p>While <code>hkdf_mod_r()</code> has modulo bias, the magnitude of this bias is minuscule (the output size of HKDF is set to 48 bytes which is greater 2¹²⁸ time larger than the curve order). This bias is deemed acceptable in light of the simplicity of the constant time scheme.</p> <h3 id="only-using-hardened-keys">Only using hardened keys</h3> <p>Widely accepted standards that existed before this one (<a rel="external" href="https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0032.mediawiki">BIP32</a> and <a rel="external" href="https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0044.mediawiki">BIP44</a>) utilise the notion of hardened and non-hardened keys whereas this specification only offers the former. Non-hardened keys are primarily useful in a UTXO system in which having one's balance spilt amongst many accounts does not present much additionally complexity, but such keys are much less useful outside of this context. Further complicating matters is the problem of deriving non-hardened keys using a post-quantum signature scheme as non-hardened keys are made possible by the very group arithmetic quantum computers gain an advantage over.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no major backwards compatibility issues brought upon by this EIP as it is not designed for use with secp256k1 keys. That said, this standard is not compatible with BIP32/ BIP44 style paths as paths specified by these systems make use of non-hardened keys, something that does not exist within this standard.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="test-case-0">Test Case 0</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>seed = 0xc55257c360c07c72029aebc1b53c05ed0362ada38ead3e3e9efa3708e53495531f09a6987599d18264c1e1c92f2cf141630c7a3c4ab7c81b2f001698e7463b04</span></span> <span class="giallo-l"><span>master_SK = 6083874454709270928345386274498605044986640685124978867557563392430687146096</span></span> <span class="giallo-l"><span>child_index = 0</span></span> <span class="giallo-l"><span>child_SK = 20397789859736650942317412262472558107875392172444076792671091975210932703118</span></span></code></pre> <p>This test case can be extended to test the entire mnemonic-to-<code>child_SK</code> stack, assuming <a rel="external" href="https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0039.mediawiki">BIP39</a> is used as the mnemonic generation mechanism. Using the following parameters, the above seed can be calculated:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>mnemonic = &quot;abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about&quot;</span></span> <span class="giallo-l"><span>passphrase = &quot;TREZOR&quot;</span></span></code></pre> <p>This test case can be extended to test the entire <code>mnemonic-to -child_SK</code> stack, assuming <a rel="external" href="https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0039.mediawiki">BIP39</a> is used as the mnemonic generation mechanism. Using the following parameters, the above seed can be calculated:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>mnemonic = &quot;abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about&quot;</span></span> <span class="giallo-l"><span>passphrase = &quot;TREZOR&quot;</span></span></code></pre><h3 id="test-case-1">Test Case 1</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>seed = 0x3141592653589793238462643383279502884197169399375105820974944592</span></span> <span class="giallo-l"><span>master_SK = 29757020647961307431480504535336562678282505419141012933316116377660817309383</span></span> <span class="giallo-l"><span>child_index = 3141592653</span></span> <span class="giallo-l"><span>child_SK = 25457201688850691947727629385191704516744796114925897962676248250929345014287</span></span></code></pre><h3 id="test-case-2">Test Case 2</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>seed = 0x0099FF991111002299DD7744EE3355BBDD8844115566CC55663355668888CC00</span></span> <span class="giallo-l"><span>master_SK = 27580842291869792442942448775674722299803720648445448686099262467207037398656</span></span> <span class="giallo-l"><span>child_index = 4294967295</span></span> <span class="giallo-l"><span>child_SK = 29358610794459428860402234341874281240803786294062035874021252734817515685787</span></span></code></pre><h3 id="test-case-3">Test Case 3</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>seed = 0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3</span></span> <span class="giallo-l"><span>master_SK = 19022158461524446591288038168518313374041767046816487870552872741050760015818</span></span> <span class="giallo-l"><span>child_index = 42</span></span> <span class="giallo-l"><span>child_SK = 31372231650479070279774297061823572166496564838472787488249775572789064611981</span></span></code></pre><h3 id="test-vector-with-intermediate-values">Test Vector with Intermediate values</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>seed = 0xc55257c360c07c72029aebc1b53c05ed0362ada38ead3e3e9efa3708e53495531f09a6987599d18264c1e1c92f2cf141630c7a3c4ab7c81b2f001698e7463b04</span></span> <span class="giallo-l"><span>master_SK = 6083874454709270928345386274498605044986640685124978867557563392430687146096</span></span> <span class="giallo-l"><span>child_index = 0</span></span> <span class="giallo-l"><span>lamport_0 = [0xe345d0ad7be270737de05cf036f688f385d5f99c7fddb054837658bdd2ebd519,</span></span> <span class="giallo-l"><span>0x65050bd4db9c77c051f67dcc801bf1cdf33d81131e608505bb3e4523868eb76c,</span></span> <span class="giallo-l"><span>0xc4f8e8d251fbdaed41bdd9c135b9ed5f83a614f49c38fffad67775a16575645a,</span></span> <span class="giallo-l"><span>0x638ad0feace7567255120a4165a687829ca97e0205108b8b73a204fba6a66faa,</span></span> <span class="giallo-l"><span>0xb29f95f64d0fcd0f45f265f15ff7209106ab5f5ce6a566eaa5b4a6f733139936,</span></span> <span class="giallo-l"><span>0xbcfbdd744c391229f340f02c4f2d092b28fe9f1201d4253b9045838dd341a6bf,</span></span> <span class="giallo-l"><span>0x8b9cf3531bfcf0e4acbfd4d7b4ed614fa2be7f81e9f4eaef53bedb509d0b186f,</span></span> <span class="giallo-l"><span>0xb32fcc5c4e2a95fb674fa629f3e2e7d85335f6a4eafe7f0e6bb83246a7eced5f,</span></span> <span class="giallo-l"><span>0xb4fe80f7ac23065e30c3398623b2761ac443902616e67ce55649aaa685d769ce,</span></span> <span class="giallo-l"><span>0xb99354f04cfe5f393193c699b8a93e5e11e6be40ec16f04c739d9b58c1f55bf3,</span></span> <span class="giallo-l"><span>0x93963f58802099ededb7843219efc66a097fab997c1501f8c7491991c780f169,</span></span> <span class="giallo-l"><span>0x430f3b027dbe9bd6136c0f0524a0848dad67b253a11a0e4301b44074ebf82894,</span></span> <span class="giallo-l"><span>0xd635c39b4a40ad8a54d9d49fc8111bd9d11fb65c3b30d8d3eaef7d7556aac805,</span></span> <span class="giallo-l"><span>0x1f7253a6474cf0b2c05b02a7e91269137acddedcb548144821f9a90b10eccbab,</span></span> <span class="giallo-l"><span>0x6e3bdb270b00e7b6eb8b044dbfae07b51ea7806e0d24218c59a807a7fd099c18,</span></span> <span class="giallo-l"><span>0x895488ad2169d8eaae332ce5b0fe1e60ffab70e62e1cb15a2a1487544af0a6e8,</span></span> <span class="giallo-l"><span>0x32d45a99d458c90e173a3087ea3661ab62d429b285089e92806a9663ba825342,</span></span> <span class="giallo-l"><span>0xc15c52106c3177f5848a173076a20d46600ca65958a1e3c7d45a593aaa9670ed,</span></span> <span class="giallo-l"><span>0xd8180c550fbe4cd6d5b676ff75e0728729d8e28a3b521d56152594ac6959d563,</span></span> <span class="giallo-l"><span>0x58fe153fac8f4213aaf175e458435e06304548024bcb845844212c774bdffb2a,</span></span> <span class="giallo-l"><span>0x10fff610a50f4bee5c978f512efa6ab4fafacb65929606951ba5b93eeb617b5a,</span></span> <span class="giallo-l"><span>0x78ac9819799b52eba329f13dd52cf0f6148a80bf04f93341814c4b47bb4aa5ec,</span></span> <span class="giallo-l"><span>0xa5c3339caa433fc11e74d1765bec577a13b054381a44b23c2482e750696876a9,</span></span> <span class="giallo-l"><span>0x9f716640ab5cdc2a5eb016235cddca2dc41fa4ec5acd7e58af628dade99ec376,</span></span> <span class="giallo-l"><span>0x2544364320e67577c4fed8c7c7c839deed93c24076d5343c5b8faca4cc6dc2d8,</span></span> <span class="giallo-l"><span>0x62553e782541f822c589796be5d5c83bfc814819100b2be0710b246f5aa7149c,</span></span> <span class="giallo-l"><span>0x229fb761c46c04b22ba5479f2696be0f936fded68d54dd74bcd736b8ba512afb,</span></span> <span class="giallo-l"><span>0x0af23996a65b98a0ebaf19f3ec0b3ef20177d1bfd6eb958b3bd36e0bdbe04c8c,</span></span> <span class="giallo-l"><span>0x6f0954f9deab52fd4c8d2daba69f73a80dea143dd49d9705c98db3d653adf98c,</span></span> <span class="giallo-l"><span>0xfa9221dd8823919a95b35196c1faeb59713735827f3e84298c25c83ac700c480,</span></span> <span class="giallo-l"><span>0x70c428e3ff9e5e3cda92d6bb85018fb89475c19f526461cca7cda64ebb2ff544,</span></span> <span class="giallo-l"><span>0xdcaac3413e22314f0f402f8058a719b62966b3a7429f890d947be952f2e314ba,</span></span> <span class="giallo-l"><span>0xb6b383cb5ec25afa701234824491916bfe6b09d28cf88185637e2367f0cf6edc,</span></span> <span class="giallo-l"><span>0x7b0d91488fc916aba3e9cb61a5a5645b9def3b02e4884603542f679f602afb8d,</span></span> <span class="giallo-l"><span>0xe9c20abca284acfde70c59584b9852b85c52fa7c263bb981389ff8d638429cd7,</span></span> <span class="giallo-l"><span>0x838524f798daee6507652877feb9597f5c47e9bb5f9aa52a35fb6fff796813b9,</span></span> <span class="giallo-l"><span>0xbe1ca18faf9bf322474fad1b3d9b4f1bc76ae9076e38e6dd2b16e2faf487742b,</span></span> <span class="giallo-l"><span>0xbf02d70f1a8519343a16d24bade7f7222912fd57fe4f739f367dfd99d0337e8e,</span></span> <span class="giallo-l"><span>0xc979eb67c107ff7ab257d1c0f4871adf327a4f2a69e01c42828ea27407caf058,</span></span> <span class="giallo-l"><span>0xf769123d3a3f19eb7b5c3fd4f467a042944a7c5ff8834cebe427f47dbd71460c,</span></span> <span class="giallo-l"><span>0xaefc8edc23257e1168a35999fe3832bcbc25053888cc89c38667482d6748095b,</span></span> <span class="giallo-l"><span>0x8ff399f364d3a2428b1c92213e4fdc5341e7998007da46a5a2f671929b42aaab,</span></span> <span class="giallo-l"><span>0xcf2a3d9e6963b24c5001fbba1e5ae7f45dd6cf520fd24861f745552db86bab48,</span></span> <span class="giallo-l"><span>0xb380e272d7f3091e5c887fa2e7c690c67d59f4d95f8376d150e555da8c738559,</span></span> <span class="giallo-l"><span>0xc006a749b091d91204dbb64f59059d284899de5986a7f84f8877afd5e0e4c253,</span></span> <span class="giallo-l"><span>0x818d8bb9b7da2dafa2ef059f91975e7b6257f5e199d217320de0a576f020de5c,</span></span> <span class="giallo-l"><span>0x7aabf4a1297d2e550a2ee20acb44c1033569e51b6ec09d95b22a8d131e30fd32,</span></span> <span class="giallo-l"><span>0xdd01c80964a5d682418a616fb10810647c9425d150df643c8ddbbe1bfb2768b7,</span></span> <span class="giallo-l"><span>0x1e2354e1d97d1b06eb6cfe9b3e611e8d75b5c57a444523e28a8f72a767eff115,</span></span> <span class="giallo-l"><span>0x989c9a649dca0580256113e49ea0dd232bbfd312f68c272fe7c878acc5da7a2c,</span></span> <span class="giallo-l"><span>0x14ee1efe512826fff9c028f8c7c86708b841f9dbf47ce4598298b01134ebdc1a,</span></span> <span class="giallo-l"><span>0x6f861dba4503f85762d9741fa8b652ce441373f0ef2b7ebbd5a794e48cdab51b,</span></span> <span class="giallo-l"><span>0xda110c9492ffdb87efe790214b7c9f707655a5ec08e5af19fb2ab2acc428e7dc,</span></span> <span class="giallo-l"><span>0x5576aa898f6448d16e40473fcb24c46c609a3fc46a404559faa2d0d34d7d49ce,</span></span> <span class="giallo-l"><span>0x9bd9a35675f2857792bc45893655bfdf905ffeaee942d93ad39fbcadd4ca9e11,</span></span> <span class="giallo-l"><span>0xfa95e4c37db9303d5213890fd984034089cbc9c6d754741625da0aa59cc45ccf,</span></span> <span class="giallo-l"><span>0xfef7d2079713f17b47239b76c8681bf7f800b1bfeac7a53265147579572ddf29,</span></span> <span class="giallo-l"><span>0x39aa7c0fecf9a1ed037c685144745fda16da36f6d2004844cf0e2d608ef6ed0e,</span></span> <span class="giallo-l"><span>0x5530654d502d6ba30f2b16f49cc5818279697308778fd8d40db8e84938144fb6,</span></span> <span class="giallo-l"><span>0xb1beaa36397ba1521d7bf7df16536969d8a716e63510b1b82a715940180eb29f,</span></span> <span class="giallo-l"><span>0x21abe342789f7c15a137afa373f686330c0db8c861572935a3cd8dcf9e4e1d45,</span></span> <span class="giallo-l"><span>0x27b5a1acda55b4e0658887bd884d3203696fcae0e94f19e31bfe931342b1c257,</span></span> <span class="giallo-l"><span>0x58401a02502d7708a812c0c72725f768f5a556480517258069f2d72543cda888,</span></span> <span class="giallo-l"><span>0x4b38f291548f51bee7e4cf8cc5c8aa8f4ad3ec2461dba4ccbab70f1c1bfd7feb,</span></span> <span class="giallo-l"><span>0x9b39a53fdafaaf1d23378e0aa8ae65d38480de69821de2910873eefc9f508568,</span></span> <span class="giallo-l"><span>0x932200566a3563ee9141913d12fd1812cb008cb735724e8610890e101ec10112,</span></span> <span class="giallo-l"><span>0x6a72f70b4ec5491f04780b17c4776a335fcc5bff5073d775150e08521dc74c91,</span></span> <span class="giallo-l"><span>0x86d5c60e627a4b7d5d075b0ba33e779c45f3f46d22ed51f31360afd140851b67,</span></span> <span class="giallo-l"><span>0x5ca2a736bb642abc4104faa781c9aff13d692a400d91dc961aec073889836946,</span></span> <span class="giallo-l"><span>0xa14bca5a262ac46ceac21388a763561fc85fb9db343148d786826930f3e510cd,</span></span> <span class="giallo-l"><span>0x87be03a87a9211504aa70ec149634ee1b97f7732c96377a3c04e98643dcba915,</span></span> <span class="giallo-l"><span>0x8fe283bc19a377823377e9c326374ebb3f29527c12ea77bfb809c18eef8943b0,</span></span> <span class="giallo-l"><span>0x8f519078b39a3969f7e4caeca9839d4e0eccc883b89e4a86d0e1731bfc5e33fc,</span></span> <span class="giallo-l"><span>0x33d7c28c3d26fdfc015a8c2131920e1392ef0aea55505637b54ea63069c7858e,</span></span> <span class="giallo-l"><span>0xe57de7c189fcc9170320c7acedb38798562a48dbc9943b2a8cd3441d58431128,</span></span> <span class="giallo-l"><span>0x513dac46017050f82751a07b6c890f14ec43cadf687f7d202d2369e35b1836b4,</span></span> <span class="giallo-l"><span>0xfd967d9f805bb7e78f7b7caa7692fdd3d6b5109c41ad239a08ad0a38eeb0ac4c,</span></span> <span class="giallo-l"><span>0xf2013e4da9abcc0f03ca505ed94ec097556dbfd659088cd24ec223e02ac43329,</span></span> <span class="giallo-l"><span>0xe0dcfac50633f7417f36231df2c81fa1203d358d5f57e896e1ab4b512196556b,</span></span> <span class="giallo-l"><span>0xf022848130e73fe556490754ef0ecfcdaaf3b9ff16ae1eda7d38c95c4f159ded,</span></span> <span class="giallo-l"><span>0x2147163a3339591ec7831d2412fb2d0588c38da3cd074fa2a4d3e5d21f9f1d2d,</span></span> <span class="giallo-l"><span>0x11ee2404731962bf3238dca0d9759e06d1a5851308b4e6321090886ec5190b69,</span></span> <span class="giallo-l"><span>0xf7679ecd07143f8ac166b66790fa09aed39352c09c0b4766bbe500b1ebace5a5,</span></span> <span class="giallo-l"><span>0xc7a0e95f09076472e101813a95e6ea463c35bd5ee9cfda3e5d5dbccb35888ef0,</span></span> <span class="giallo-l"><span>0xde625d3b547eb71bea5325a0191a592fa92a72e4b718a499fdba32e245ddf37e,</span></span> <span class="giallo-l"><span>0x7e5bdccd95df216e8c59665073249072cb3c9d0aef6b341afc0ca90456942639,</span></span> <span class="giallo-l"><span>0xc27f65fd9f797ede374e06b4ddb6e8aa59c7d6f36301f18b42c48b1889552fe3,</span></span> <span class="giallo-l"><span>0x8175730a52ea571677b035f8e2482239dda1cfbff6bc5cde00603963511a81af,</span></span> <span class="giallo-l"><span>0x09e440f2612dad1259012983dc6a1e24a73581feb1bd69d8a356eea16ba5fd0e,</span></span> <span class="giallo-l"><span>0x59dcc81d594cbe735a495e38953e8133f8b3825fd84767af9e4ea06c49dbabfa,</span></span> <span class="giallo-l"><span>0x6c8480b59a1a958c434b9680edea73b1207077fb9a8a19ea5f9fbbf6f47c4124,</span></span> <span class="giallo-l"><span>0x81f5c89601893b7a5a231a7d37d6ab9aa4c57f174fcfc6b40002fa808714c3a1,</span></span> <span class="giallo-l"><span>0x41ba4d6b4da141fcc1ee0f4b47a209cfd143d34e74fc7016e9956cedeb2db329,</span></span> <span class="giallo-l"><span>0x5e0b5b404c60e9892040feacfb4a84a09c2bc4a8a5f54f3dad5dca4acdc899dc,</span></span> <span class="giallo-l"><span>0xe922eebf1f5f15000d8967d16862ed274390cde808c75137d2fb9c2c0a80e391,</span></span> <span class="giallo-l"><span>0xbf49d31a59a20484f0c08990b2345dfa954509aa1f8901566ab9da052b826745,</span></span> <span class="giallo-l"><span>0xb84e07da828ae668c95d6aa31d4087504c372dbf4b5f8a8e4ded1bcf279fd52b,</span></span> <span class="giallo-l"><span>0x89288bf52d8c4a9561421ad199204d794038c5d19ae9fee765ee2b5470e68e7e,</span></span> <span class="giallo-l"><span>0xf6f618be99b85ec9a80b728454a417c647842215e2160c6fe547dd5a69bd9302,</span></span> <span class="giallo-l"><span>0xdd9adc002f98c9a47c7b704fc0ce0a5c7861a5e2795b6014749cde8bcb8a034b,</span></span> <span class="giallo-l"><span>0xd119a4b2c0db41fe01119115bcc35c4b7dbfdb42ad3cf2cc3f01c83732acb561,</span></span> <span class="giallo-l"><span>0x9c66bc84d416b9193bad9349d8c665a9a06b835f82dc93ae0cccc218f808aad0,</span></span> <span class="giallo-l"><span>0xd4b50eefcd2b5df075f14716cf6f2d26dfc8ae02e3993d711f4a287313038fde,</span></span> <span class="giallo-l"><span>0xaf72bfb346c2f336b8bc100bff4ba35d006a3dad1c5952a0adb40789447f2704,</span></span> <span class="giallo-l"><span>0xc43ca166f01dc955e7b4330227635feb1b0e0076a9c5633ca5c614a620244e5b,</span></span> <span class="giallo-l"><span>0x5efca76970629521cfa053fbbbda8d3679cadc018e2e891043b0f52989cc2603,</span></span> <span class="giallo-l"><span>0x35c57de1c788947f187051ce032ad1e899d9887d865266ec6fcfda49a8578b2b,</span></span> <span class="giallo-l"><span>0x56d4be8a65b257216eab7e756ee547db5a882b4edcd12a84ed114fbd4f5be1f1,</span></span> <span class="giallo-l"><span>0x257e858f8a4c07a41e6987aabaa425747af8b56546f2a3406f60d610bcc1f269,</span></span> <span class="giallo-l"><span>0x40bd9ee36d52717ab22f1f6b0ee4fb38b594f58399e0bf680574570f1b4b8c90,</span></span> <span class="giallo-l"><span>0xcb6ac01c21fc288c12973427c5df6eb8f6aefe64b92a6420c6388acdf36bc096,</span></span> <span class="giallo-l"><span>0xa5716441312151a5f0deb52993a293884c6c8f445054ce1e395c96adeee66c6d,</span></span> <span class="giallo-l"><span>0xe15696477f90113a10e04ba8225c28ad338c3b6bdd7bdeb95c0722921115ec85,</span></span> <span class="giallo-l"><span>0x8faeaa52ca2f1d791cd6843330d16c75eaf6257e4ba236e3dda2bc1a644aee00,</span></span> <span class="giallo-l"><span>0xc847fe595713bf136637ce8b43f9de238762953fed16798878344da909cc76ae,</span></span> <span class="giallo-l"><span>0xb5740dc579594dd110078ce430b9696e6a308078022dde2d7cfe0ef7647b904e,</span></span> <span class="giallo-l"><span>0x551a06d0771fcd3c53aea15aa8bf700047138ef1aa22265bee7fb965a84c9615,</span></span> <span class="giallo-l"><span>0x9a65397a5907d604030508d41477de621ce4a0d79b772e81112d634455e7a4da,</span></span> <span class="giallo-l"><span>0x6462d4cc2262d7faf8856812248dc608ae3d197bf2ef410f00c3ae43f2040995,</span></span> <span class="giallo-l"><span>0x6782b1bd319568e30d54b324ab9ed8fdeac6515e36b609e428a60785e15fb301,</span></span> <span class="giallo-l"><span>0x8bcdcf82c7eb2a07e14db20d80d9d2efea8d40320e121923784c92bf38250a8e,</span></span> <span class="giallo-l"><span>0x46ed84fa17d226d5895e44685747ab82a97246e97d6237014611aaaba65ed268,</span></span> <span class="giallo-l"><span>0x147e87981673326c5a2bdb06f5e90eaaa9583857129451eed6dde0c117fb061f,</span></span> <span class="giallo-l"><span>0x4141d6fe070104c29879523ba6669552f3d457c0929bb878d2751f4ff059b895,</span></span> <span class="giallo-l"><span>0xd866ce4ef226d74841f950fc28cdf2235db21e0e3f07a0c8f807704464db2210,</span></span> <span class="giallo-l"><span>0xa804f9118bf92558f684f90c2bda832a4f51ef771ffb2765cde3ec6f48124f32,</span></span> <span class="giallo-l"><span>0xc436d4a65910124e00cded9a637178914a8fbc090400f3f031c03eac4d0295a5,</span></span> <span class="giallo-l"><span>0x643fdb9243656512316528de04dcc7344ca33783580ad0c3debf8c4a6e7c8bc4,</span></span> <span class="giallo-l"><span>0x7f4a345b41706b281b2de998e91ff62d908eb29fc333ee336221757753c96e23,</span></span> <span class="giallo-l"><span>0x6bdc086a5b11de950cabea33b72d98db886b291c4c2f02d3e997edc36785d249,</span></span> <span class="giallo-l"><span>0xfb10b5b47d374078c0a52bff7174bf1cd14d872c7d20b4a009e2afd3017a9a17,</span></span> <span class="giallo-l"><span>0x1e07e605312db5380afad8f3d7bd602998102fdd39565b618ac177b13a6527e6,</span></span> <span class="giallo-l"><span>0xc3161b5a7b93aabf05652088b0e5b4803a18be693f590744c42c24c7aaaeef48,</span></span> <span class="giallo-l"><span>0xa47e4f25112a7d276313f153d359bc11268b397933a5d5375d30151766bc689a,</span></span> <span class="giallo-l"><span>0xb24260e2eff88716b5bf5cb75ea171ac030f5641a37ea89b3ac45acb30aae519,</span></span> <span class="giallo-l"><span>0x2bcacbebc0a7f34406db2c088390b92ee34ae0f2922dedc51f9227b9afb46636,</span></span> <span class="giallo-l"><span>0xc78c304f6dbe882c99c5e1354ce6077824cd42ed876db6706654551c7472a564,</span></span> <span class="giallo-l"><span>0x6e2ee19d3ee440c78491f4e354a84fa593202e152d623ed899e700728744ac85,</span></span> <span class="giallo-l"><span>0x2a3f438c5dc012aa0997b66f661b8c10f4a0cd7aa5b6e5922b1d73020561b27f,</span></span> <span class="giallo-l"><span>0xd804f755d93173408988b95e9ea0e9feae10d404a090f73d9ff84df96f081cf7,</span></span> <span class="giallo-l"><span>0xe06fda941b6936b8b33f00ffa02c8b05fd78fbec953da61da2043f5644b30a50,</span></span> <span class="giallo-l"><span>0x45ee279b465d53148850a16cc7f6bd33e7627aef554a9418ed012ca8f9717f80,</span></span> <span class="giallo-l"><span>0x9c79348c1bcd6aa2135452491d73564413a247ea8cc38fa7dcc6c43f8a2d61d5,</span></span> <span class="giallo-l"><span>0x7c91e056f89f2a77d3e3642e595bcf4973c3bca68dd2b10f51ca0d8945e4255e,</span></span> <span class="giallo-l"><span>0x669f976ebe38cbd22c5b1f785e14b76809d673d2cb1458983dbda41f5adf966b,</span></span> <span class="giallo-l"><span>0x8bc71e99ffcc119fd8bd604af54c0663b0325a3203a214810fa2c588089ed5a7,</span></span> <span class="giallo-l"><span>0x36b3f1ffeae5d9855e0965eef33f4c5133d99685802ac5ce5e1bb288d308f889,</span></span> <span class="giallo-l"><span>0x0aad33df38b3f31598e04a42ec22f20bf2e2e9472d02371eb1f8a06434621180,</span></span> <span class="giallo-l"><span>0x38c5632b81f90efbc51a729dcae03626a3063aa1f0a102fd0e4326e86a08a732,</span></span> <span class="giallo-l"><span>0x6ea721753348ed799c98ffa330d801e6760c882f720125250889f107915e270a,</span></span> <span class="giallo-l"><span>0xe700dd57ce8a653ce4269e6b1593a673d04d3de8b79b813354ac7c59d1b99adc,</span></span> <span class="giallo-l"><span>0xe9294a24b560d62649ca898088dea35a644d0796906d41673e29e4ea8cd16021,</span></span> <span class="giallo-l"><span>0xf20bb60d13a498a0ec01166bf630246c2f3b7481919b92019e2cfccb331f2791,</span></span> <span class="giallo-l"><span>0xf639a667209acdd66301c8e8c2385e1189b755f00348d614dc92da14e6866b38,</span></span> <span class="giallo-l"><span>0x49041904ee65c412ce2cd66d35570464882f60ac4e3dea40a97dd52ffc7b37a2,</span></span> <span class="giallo-l"><span>0xdb36b16d3a1010ad172fc55976d45df7c03b05eab5432a77be41c2f739b361f8,</span></span> <span class="giallo-l"><span>0x71400cdd2ea78ac1bf568c25a908e989f6d7e2a3690bc869c7c14e09c255d911,</span></span> <span class="giallo-l"><span>0xf0d920b2d8a00b88f78e7894873a189c580747405beef5998912fc9266220d98,</span></span> <span class="giallo-l"><span>0x1a2baefbbd41aa9f1cc5b10e0a7325c9798ba87de6a1302cf668a5de17bc926a,</span></span> <span class="giallo-l"><span>0x449538a20e52fd61777c45d35ff6c2bcb9d9165c7eb02244d521317f07af6691,</span></span> <span class="giallo-l"><span>0x97006755b9050b24c1855a58c4f4d52f01db4633baff4b4ef3d9c44013c5c665,</span></span> <span class="giallo-l"><span>0xe441363a27b26d1fff3288222fa8ed540f8ca5d949ddcc5ff8afc634eec05336,</span></span> <span class="giallo-l"><span>0xed587aa8752a42657fea1e68bc9616c40c68dcbbd5cb8d781e8574043e29ef28,</span></span> <span class="giallo-l"><span>0x47d896133ba81299b8949fbadef1c00313d466827d6b13598685bcbb8776c1d2,</span></span> <span class="giallo-l"><span>0x7786bc2cb2d619d07585e2ea4875f15efa22110e166af87b29d22af37b6c047d,</span></span> <span class="giallo-l"><span>0x956b76194075fe3daf3ca508a6fad161deb05d0026a652929e37c2317239cbc6,</span></span> <span class="giallo-l"><span>0xec9577cb7b85554b2383cc4239d043d14c08d005f0549af0eca6994e203cb4e7,</span></span> <span class="giallo-l"><span>0x0722d0c68d38b23b83330b972254bbf9bfcf32104cc6416c2dad67224ac52887,</span></span> <span class="giallo-l"><span>0x532b19d54fb6d77d96452d3e562b79bfd65175526cd793f26054c5f6f965df39,</span></span> <span class="giallo-l"><span>0x4d62e065e57cbf60f975134a360da29cabdcea7fcfc664cf2014d23c733ab3b4,</span></span> <span class="giallo-l"><span>0x09be0ea6b363fd746b303e482cb4e15ef25f8ae57b7143e64cbd5c4a1d069ebe,</span></span> <span class="giallo-l"><span>0x69dcddc3e05147860d8d0e90d602ac454b609a82ae7bb960ee2ecd1627d77777,</span></span> <span class="giallo-l"><span>0xa5e2ae69d902971000b1855b8066a4227a5be7234ac9513b3c769af79d997df4,</span></span> <span class="giallo-l"><span>0xc287d4bc953dcff359d707caf2ccba8cc8312156eca8aafa261fb72412a0ea28,</span></span> <span class="giallo-l"><span>0xb27584fd151fb30ed338f9cba28cf570f7ca39ebb03eb2e23140423af940bd96,</span></span> <span class="giallo-l"><span>0x7e02928194441a5047af89a6b6555fea218f1df78bcdb5f274911b48d847f5f8,</span></span> <span class="giallo-l"><span>0x9ba611add61ea6ba0d6d494c0c4edd03df9e6c03cafe10738cee8b7f45ce9476,</span></span> <span class="giallo-l"><span>0x62647ec3109ac3db3f3d9ea78516859f0677cdde3ba2f27f00d7fda3a447dd01,</span></span> <span class="giallo-l"><span>0xfa93ff6c25bfd9e17d520addf5ed2a60f1930278ff23866216584853f1287ac1,</span></span> <span class="giallo-l"><span>0x3b391c2aa79c2a42888102cd99f1d2760b74f772c207a39a8515b6d18e66888a,</span></span> <span class="giallo-l"><span>0xcc9ae3c14cbfb40bf01a09bcde913a3ed208e13e4b4edf54549eba2c0c948517,</span></span> <span class="giallo-l"><span>0xc2b8bce78dd4e876da04c54a7053ca8b2bedc8c639cee82ee257c754c0bea2b2,</span></span> <span class="giallo-l"><span>0xdb186f42871f438dba4d43755c59b81a6788cb3b544c0e1a3e463f6c2b6f7548,</span></span> <span class="giallo-l"><span>0xb7f8ba137c7783137c0729de14855e20c2ac4416c33f5cac3b235d05acbab634,</span></span> <span class="giallo-l"><span>0x282987e1f47e254e86d62bf681b0803df61340fdc9a8cf625ef2274f67fc6b5a,</span></span> <span class="giallo-l"><span>0x04aa195b1aa736bf8875777e0aebf88147346d347613b5ab77bef8d1b502c08c,</span></span> <span class="giallo-l"><span>0x3f732c559aee2b1e1117cf1dec4216a070259e4fa573a7dcadfa6aab74aec704,</span></span> <span class="giallo-l"><span>0x72699d1351a59aa73fcede3856838953ee90c6aa5ef5f1f7e21c703fc0089083,</span></span> <span class="giallo-l"><span>0x6d9ce1b8587e16a02218d5d5bed8e8d7da4ac40e1a8b46eeb412df35755c372c,</span></span> <span class="giallo-l"><span>0x4f9c19b411c9a74b8616db1357dc0a7eaf213cb8cd2455a39eb7ae4515e7ff34,</span></span> <span class="giallo-l"><span>0x9163dafa55b2b673fa7770b419a8ede4c7122e07919381225c240d1e90d90470,</span></span> <span class="giallo-l"><span>0x268ff4507b42e623e423494d3bb0bc5c0917ee24996fb6d0ebedec9ce8cd9d5c,</span></span> <span class="giallo-l"><span>0xff6e6169d233171ddc834e572024586eeb5b1bda9cb81e5ad1866dbc53dc75fe,</span></span> <span class="giallo-l"><span>0xb379a9c8279205e8753b6a5c865fbbf70eb998f9005cd7cbde1511f81aed5256,</span></span> <span class="giallo-l"><span>0x3a6b145e35a592e037c0992c9d259ef3212e17dca81045e446db2f3686380558,</span></span> <span class="giallo-l"><span>0x60fb781d7b3137481c601871c1c3631992f4e01d415841b7f5414743dcb4cfd7,</span></span> <span class="giallo-l"><span>0x90541b20b0c2ea49bca847e2db9b7bba5ce15b74e1d29194a12780e73686f3dd,</span></span> <span class="giallo-l"><span>0xe2b0507c13ab66b4b769ad1a1a86834e385b315da2f716f7a7a8ff35a9e8f98c,</span></span> <span class="giallo-l"><span>0xeefe54bc9fa94b921b20e7590979c28a97d8191d1074c7c68a656953e2836a72,</span></span> <span class="giallo-l"><span>0x8676e7f59d6f2ebb0edda746fc1589ef55e07feab00d7008a0f2f6f129b7bb3a,</span></span> <span class="giallo-l"><span>0x78a3d93181b40152bd5a8d84d0df7f2adde5db7529325c13bc24a5b388aed3c4,</span></span> <span class="giallo-l"><span>0xcc0e2d0cba7aaa19c874dbf0393d847086a980628f7459e9204fda39fad375c0,</span></span> <span class="giallo-l"><span>0x6e46a52cd7745f84048998df1a966736d2ac09a95a1c553016fef6b9ec156575,</span></span> <span class="giallo-l"><span>0x204ac2831d2376d4f9c1f5c106760851da968dbfc488dc8a715d1c764c238263,</span></span> <span class="giallo-l"><span>0xbdb8cc7b7e5042a947fca6c000c10b9b584e965c3590f92f6af3fe4fb23e1358,</span></span> <span class="giallo-l"><span>0x4a55e4b8a138e8508e7b11726f617dcf4155714d4600e7d593fd965657fcbd89,</span></span> <span class="giallo-l"><span>0xdfe064bb37f28d97b16d58b575844964205e7606dce914a661f2afa89157c45b,</span></span> <span class="giallo-l"><span>0x560e374fc0edda5848eef7ff06471545fcbdd8aefb2ecddd35dfbb4cb03b7ddf,</span></span> <span class="giallo-l"><span>0x10a66c82e146da5ec6f48b614080741bc51322a60d208a87090ad7c7bf6b71c6,</span></span> <span class="giallo-l"><span>0x62534c7dc682cbf356e6081fc397c0a17221b88508eaeff798d5977f85630d4f,</span></span> <span class="giallo-l"><span>0x0138bba8de2331861275356f6302b0e7424bbc74d88d8c534479e17a3494a15b,</span></span> <span class="giallo-l"><span>0x580c7768bf151175714b4a6f2685dc5bcfeb088706ee7ed5236604888b84d3e4,</span></span> <span class="giallo-l"><span>0xd290adb1a5dfc69da431c1c0c13da3be788363238d7b46bc20185edb45ab9139,</span></span> <span class="giallo-l"><span>0x1689879db6c78eb4d3038ed81be1bc106f8cfa70a7c6245bd4be642bfa02ebd7,</span></span> <span class="giallo-l"><span>0x6064c384002c8b1594e738954ed4088a0430316738def62822d08b2285514918,</span></span> <span class="giallo-l"><span>0x01fd23493f4f1cc3c5ff4e96a9ee386b2a144b50a428a6b5db654072bddadfe7,</span></span> <span class="giallo-l"><span>0xd5d05bb7f23ab0fa2b82fb1fb14ac29c2477d81a85423d0a45a4b7d5bfd81619,</span></span> <span class="giallo-l"><span>0xd72b9a73ae7b24db03b84e01106cea734d4b9d9850b0b7e9d65d6001d859c772,</span></span> <span class="giallo-l"><span>0x156317cb64578db93fee2123749aff58c81eae82b189b0d6f466f91de02b59df,</span></span> <span class="giallo-l"><span>0x5fba299f3b2c099edbac18d785be61852225890fc004bf6be0787d62926a79b3,</span></span> <span class="giallo-l"><span>0x004154f28f685bdbf0f0d6571e7a962a4c29b6c3ebedaaaf66097dfe8ae5f756,</span></span> <span class="giallo-l"><span>0x4b45816f9834c3b289affce7a3dc80056c2b7ffd3e3c250d6dff7f923e7af695,</span></span> <span class="giallo-l"><span>0x6ca53bc37816fff82346946d83bef87860626bbee7fd6ee9a4aeb904d893a11f,</span></span> <span class="giallo-l"><span>0xf48b2f43184358d66d5b5f7dd2b14a741c7441cc7a33ba3ebcc94a7b0192d496,</span></span> <span class="giallo-l"><span>0x3cb98f4baa429250311f93b46e745174f65f901fab4eb8075d380908aaaef650,</span></span> <span class="giallo-l"><span>0x343dfc26b4473b3a20e706a8e87e5202a4e6b96b53ed448afb9180c3f766e5f8,</span></span> <span class="giallo-l"><span>0x1ace0e8a735073bcbaea001af75b681298ef3b84f1dbab46ea52cee95ab0e7f9,</span></span> <span class="giallo-l"><span>0xd239b110dd71460cdbc41ddc99494a7531186c09da2a697d6351c116e667733b,</span></span> <span class="giallo-l"><span>0x22d6955236bd275969b8a6a30c23932670a6067f68e236d2869b6a8b4b493b83,</span></span> <span class="giallo-l"><span>0x53c1c01f8d061ac89187e5815ef924751412e6a6aa4dc8e3abafb1807506b4e0,</span></span> <span class="giallo-l"><span>0x2f56dd20c44d7370b713e7d7a1bfb1a800cac33f8a6157f278e17a943806a1f7,</span></span> <span class="giallo-l"><span>0xc99773d8a5b3e60115896a65ac1d6c15863317d403ef58b90cb89846f4715a7f,</span></span> <span class="giallo-l"><span>0x9f4b6b77c254094621cd336da06fbc6cbb7b8b1d2afa8e537ceca1053c561ef5,</span></span> <span class="giallo-l"><span>0x87944d0b210ae0a6c201cba04e293f606c42ebaed8b4a5d1c33f56863ae7e1b5,</span></span> <span class="giallo-l"><span>0xa7d116d962d03ca31a455f9cda90f33638fb36d3e3506605aa19ead554487a37,</span></span> <span class="giallo-l"><span>0x4042e32e224889efd724899c9edb57a703e63a404129ec99858048fbc12f2ce0,</span></span> <span class="giallo-l"><span>0x36759f7a0faeea1cd4cb91e404e4bf09908de6e53739603d5f0db52b664158a3,</span></span> <span class="giallo-l"><span>0xa4d50d005fb7b9fea8f86f1c92439cc9b8446efef7333ca03a8f6a35b2d49c38,</span></span> <span class="giallo-l"><span>0x80cb7c3e20f619006542edbe71837cdadc12161890a69eea8f41be2ee14c08a3,</span></span> <span class="giallo-l"><span>0xbb3c44e1df45f2bb93fb80e7f82cee886c153ab484c0095b1c18df03523629b4,</span></span> <span class="giallo-l"><span>0x04cb749e70fac3ac60dea779fceb0730b2ec5b915b0f8cf28a6246cf6da5db29,</span></span> <span class="giallo-l"><span>0x4f5189b8f650687e65a962ef3372645432b0c1727563777433ade7fa26f8a728,</span></span> <span class="giallo-l"><span>0x322eddddf0898513697599b68987be5f88c0258841affec48eb17cf3f61248e8,</span></span> <span class="giallo-l"><span>0x6416be41cda27711d9ec22b3c0ed4364ff6975a24a774179c52ef7e6de9718d6,</span></span> <span class="giallo-l"><span>0x0622d31b8c4ac7f2e30448bdadfebd5baddc865e0759057a6bf7d2a2c8b527e2,</span></span> <span class="giallo-l"><span>0x40f096513588cc19c08a69e4a48ab6a43739df4450b86d3ec2fb3c6a743b5485,</span></span> <span class="giallo-l"><span>0x09fcf7d49290785c9ea2d54c3d63f84f6ea0a2e9acfcdbb0cc3a281ce438250e,</span></span> <span class="giallo-l"><span>0x2000a519bf3da827f580982d449b5c70fcc0d4fa232addabe47bb8b1c471e62e,</span></span> <span class="giallo-l"><span>0xf4f80008518e200c40b043f34fb87a6f61b82f8c737bd784292911af3740245e,</span></span> <span class="giallo-l"><span>0x939eaab59f3d2ad49e50a0220080882319db7633274a978ced03489870945a65,</span></span> <span class="giallo-l"><span>0xadcad043d8c753fb10689280b7670f313253f5d719039e250a673d94441ee17c,</span></span> <span class="giallo-l"><span>0x58b7b75f090166b8954c61057074707d7e38d55ce39d9b2251bbc3d72be458f8,</span></span> <span class="giallo-l"><span>0xf61031890c94c5f87229ec608f2a9aa0a3f455ba8094b78395ae312cbfa04087,</span></span> <span class="giallo-l"><span>0x356a55def50139f94945e4ea432e7a9defa5db7975462ebb6ca99601c614ea1d,</span></span> <span class="giallo-l"><span>0x65963bb743d5db080005c4db59e29c4a4e86f92ab1dd7a59f69ea7eaf8e9aa79]</span></span> <span class="giallo-l"><span>lamport_1 = [0x9c0bfb14de8d2779f88fc8d5b016f8668be9e231e745640096d35dd5f53b0ae2,</span></span> <span class="giallo-l"><span>0x756586b0f3227ab0df6f4b7362786916bd89f353d0739fffa534368d8d793816,</span></span> <span class="giallo-l"><span>0x710108dddc39e579dcf0819f9ad107b3c56d1713530dd94325db1d853a675a37,</span></span> <span class="giallo-l"><span>0x8862b5f428ce5da50c89afb50aa779bb2c4dfe60e6f6a070b3a0208a4a970fe5,</span></span> <span class="giallo-l"><span>0x54a9cd342fa3a4bf685c01d1ce84f3068b0d5b6a58ee22dda8fbac4908bb9560,</span></span> <span class="giallo-l"><span>0x0fa3800efeaddd28247e114a1cf0f86b9014ccae9c3ee5f8488168b1103c1b44,</span></span> <span class="giallo-l"><span>0xbb393428b7ebfe2eda218730f93925d2e80c020d41a29f4746dcbb9138f7233a,</span></span> <span class="giallo-l"><span>0x7b42710942ef38ef2ff8fe44848335f26189c88c22a49fda84a51512ac68cd5d,</span></span> <span class="giallo-l"><span>0x90e99786a3e8b04db95ccd44d01e75558d75f3ddd12a1e9a2c2ce76258bf4813,</span></span> <span class="giallo-l"><span>0x3f6f71e40251728aa760763d25deeae54dc3a9b53807c737deee219120a2230a,</span></span> <span class="giallo-l"><span>0xe56081a7933c6eaf4ef2c5a04e21ab8a3897785dd83a34719d1b62d82cfd00c2,</span></span> <span class="giallo-l"><span>0x76cc54fa15f53e326575a9a2ac0b8ed2869403b6b6488ce4f3934f17db0f6bee,</span></span> <span class="giallo-l"><span>0x1cd9cd1d882ea3830e95162b5de4beb5ddff34fdbf7aec64e83b82a6d11b417c,</span></span> <span class="giallo-l"><span>0xb8ca8ae36d717c448aa27405037e44d9ee28bb8c6cc538a5d22e4535c8befd84,</span></span> <span class="giallo-l"><span>0x5c4492108c25f873a23d5fd7957b3229edc22858e8894febe7428c0831601982,</span></span> <span class="giallo-l"><span>0x907bcd75e7465e9791dc34e684742a2c0dc7007736313a95070a7e6b961c9c46,</span></span> <span class="giallo-l"><span>0xe7134b1511559e6b2440672073fa303ec3915398e75086149eb004f55e893214,</span></span> <span class="giallo-l"><span>0x2ddc2415e4753bfc383d48733e8b2a3f082883595edc5515514ebb872119af09,</span></span> <span class="giallo-l"><span>0xf2ad0f76b08ffa1eee62228ba76f4982fab4fbede5d4752c282c3541900bcd5b,</span></span> <span class="giallo-l"><span>0x0a84a6b15abd1cbc2da7092bf7bac418b8002b7000236dfba7c8335f27e0f1d4,</span></span> <span class="giallo-l"><span>0x97404e02b9ff5478c928e1e211850c08cc553ebac5d4754d13efd92588b1f20d,</span></span> <span class="giallo-l"><span>0xfa6ca3bcff1f45b557cdec34cb465ab06ade397e9d9470a658901e1f0f124659,</span></span> <span class="giallo-l"><span>0x5bd972d55f5472e5b08988ee4bccc7240a8019a5ba338405528cc8a38b29bc21,</span></span> <span class="giallo-l"><span>0x52952e4f96c803bb76749800891e3bfe55f7372facd5b5a587a39ac10b161bcc,</span></span> <span class="giallo-l"><span>0xf96731ae09abcad016fd81dc4218bbb5b2cb5fe2e177a715113f381814007314,</span></span> <span class="giallo-l"><span>0xe7d79e07cf9f2b52623491519a21a0a3d045401a5e7e10dd8873a85076616326,</span></span> <span class="giallo-l"><span>0xe4892f3777a4614ee6770b22098eaa0a3f32c5c44b54ecedacd69789d676dffe,</span></span> <span class="giallo-l"><span>0x20c932574779e2cc57780933d1dc6ce51a5ef920ce5bf681f7647ac751106367,</span></span> <span class="giallo-l"><span>0x057252c573908e227cc07797117701623a4835f4b047dcaa9678105299e48e70,</span></span> <span class="giallo-l"><span>0x20bad780930fa2a036fe1dea4ccbf46ac5b3c489818cdb0f97ae49d6e2f11fbf,</span></span> <span class="giallo-l"><span>0xc0d7dd26ffecdb098585a1694e45a54029bb1e31c7c5209289058efebb4cc91b,</span></span> <span class="giallo-l"><span>0x9a8744beb1935c0abe4b11812fc02748ef7c8cb650db3024dde3c5463e9d8714,</span></span> <span class="giallo-l"><span>0x8ce6eea4585bbeb657b326daa4f01f6aef34954338b3ca42074aedd1110ba495,</span></span> <span class="giallo-l"><span>0x1c85b43f5488b370721290d2faea19d9918d094c99963d6863acdfeeca564363,</span></span> <span class="giallo-l"><span>0xe88a244347e448349e32d0525b40b18533ea227a9d3e9b78a9ff14ce0a586061,</span></span> <span class="giallo-l"><span>0x352ca61efc5b8ff9ee78e738e749142dd1606154801a1449bbb278fa6bcc3dbe,</span></span> <span class="giallo-l"><span>0xa066926f9209220b24ea586fb20eb8199a05a247c82d7af60b380f6237429be7,</span></span> <span class="giallo-l"><span>0x3052337ccc990bfbae26d2f9fe5d7a4eb8edfb83a03203dca406fba9f4509b6e,</span></span> <span class="giallo-l"><span>0x343ce573a93c272688a068d758df53c0161aa7f9b55dec8beced363a38b33069,</span></span> <span class="giallo-l"><span>0x0f16b5593f133b58d706fe1793113a10750e8111eadee65301df7a1e84f782d3,</span></span> <span class="giallo-l"><span>0x808ae8539357e85b648020f1e9d255bc4114bee731a6220d7c5bcb5b85224e03,</span></span> <span class="giallo-l"><span>0x3b2bd97e31909251752ac57eda6015bb05b85f2838d475095cfd146677430625,</span></span> <span class="giallo-l"><span>0xe4f857c93b2d8b250050c7381a6c7c660bd29066195806c8ef11a2e6a6640236,</span></span> <span class="giallo-l"><span>0x23d91589b5070f443ddcefa0838c596518d54928119251ecf3ec0946a8128f52,</span></span> <span class="giallo-l"><span>0xb72736dfad52503c7f5f0c59827fb6ef4ef75909ff9526268abc0f296ee37296,</span></span> <span class="giallo-l"><span>0x80a8c66436d86b8afe87dde7e53a53ef87e057a5d4995963e76d159286de61b6,</span></span> <span class="giallo-l"><span>0xbec92c09ee5e0c84d5a8ba6ca329683ff550ace34631ea607a3a21f99cd36d67,</span></span> <span class="giallo-l"><span>0x83c97c9807b9ba6d9d914ae49dabdb4c55e12e35013f9b179e6bc92d5d62222b,</span></span> <span class="giallo-l"><span>0x8d9c79f6af3920672dc4cf97a297c186e75083d099aeb5c1051207bad0c98964,</span></span> <span class="giallo-l"><span>0x2aaa5944a2bd852b0b1be3166e88f357db097b001c1a71ba92040b473b30a607,</span></span> <span class="giallo-l"><span>0x46693d27ec4b764fbb516017c037c441f4558aebfe972cdcd03da67c98404e19,</span></span> <span class="giallo-l"><span>0x903b25d9e12208438f203c9ae2615b87f41633d5ffda9cf3f124c1c3922ba08f,</span></span> <span class="giallo-l"><span>0x3ec23dc8bc1b49f5c7160d78008f3f235252086a0a0fa3a7a5a3a53ad29ec410,</span></span> <span class="giallo-l"><span>0xa1fe74ceaf3cccd992001583a0783d7d7b7a245ea374f369133585b576b9c6d8,</span></span> <span class="giallo-l"><span>0xb2d6b0fe4932a2e06b99531232398f39a45b0f64c3d4ebeaaebc8f8e50a80607,</span></span> <span class="giallo-l"><span>0xe19893353f9214eebf08e5d83c6d44c24bffe0eceee4dc2e840d42eab0642536,</span></span> <span class="giallo-l"><span>0x5b798e4bc099fa2e2b4b5b90335c51befc9bbab31b4dd02451b0abd09c06ee79,</span></span> <span class="giallo-l"><span>0xbab2cdec1553a408cac8e61d9e6e19fb8ccfb48efe6d02bd49467a26eeeca920,</span></span> <span class="giallo-l"><span>0x1c1a544c28c38e5c423fe701506693511b3bc5f2af9771b9b2243cd8d41bebfc,</span></span> <span class="giallo-l"><span>0x704d6549d99be8cdefeec9a58957f75a2be4af7bc3dc4655fa606e7f3e03b030,</span></span> <span class="giallo-l"><span>0x051330f43fe39b08ed7d82d68c49b36a8bfa31357b546bfb32068712df89d190,</span></span> <span class="giallo-l"><span>0xe69174c7b03896461cab2dfaab33d549e3aac15e6b0f6f6f466fb31dae709b9b,</span></span> <span class="giallo-l"><span>0xe5f668603e0ddbbcde585ac41c54c3c4a681fffb7a5deb205344de294758e6ac,</span></span> <span class="giallo-l"><span>0xca70d5e4c3a81c1f21f246a3f52c41eaef9a683f38eb7c512eac8b385f46cbcd,</span></span> <span class="giallo-l"><span>0x3173a6b882b21cd147f0fc60ef8f24bbc42104caed4f9b154f2d2eafc3a56907,</span></span> <span class="giallo-l"><span>0xc71469c192bf5cc36242f6365727f57a19f924618b8a908ef885d8f459833cc3,</span></span> <span class="giallo-l"><span>0x59c596fc388afd8508bd0f5a1e767f3dda9ed30f6646d15bc59f0b07c4de646f,</span></span> <span class="giallo-l"><span>0xb200faf29368581f551bd351d357b6fa8cbf90bdc73b37335e51cad36b4cba83,</span></span> <span class="giallo-l"><span>0x275cede69b67a9ee0fff1a762345261cb20fa8191470159cc65c7885cfb8313c,</span></span> <span class="giallo-l"><span>0x0ce4ef84916efbe1ba9a0589bed098793b1ea529758ea089fd79151cc9dc7494,</span></span> <span class="giallo-l"><span>0x0f08483bb720e766d60a3cbd902ce7c9d835d3f7fdf6dbe1f37bcf2f0d4764a2,</span></span> <span class="giallo-l"><span>0xb30a73e5db2464e6da47d10667c82926fa91fceb337d89a52db5169008bc6726,</span></span> <span class="giallo-l"><span>0x6b9c50fed1cc404bf2dd6fffbfd18e30a4caa1500bfeb080aa93f78d10331aaf,</span></span> <span class="giallo-l"><span>0xf17c84286df03ce175966f560600dd562e0f59f18f1d1276b4d8aca545d57856,</span></span> <span class="giallo-l"><span>0x11455f2ef96a6b2be69854431ee219806008eb80ea38c81e45b2e58b3f975a20,</span></span> <span class="giallo-l"><span>0x9a61e03e2157a5c403dfcde690f7b7d704dd56ea1716cf14cf7111075a8d6491,</span></span> <span class="giallo-l"><span>0x30312c910ce6b39e00dbaa669f0fb7823a51f20e83eaeb5afa63fb57668cc2f4,</span></span> <span class="giallo-l"><span>0x17c18d261d94fba82886853a4f262b9c8b915ed3263b0052ece5826fd7e7d906,</span></span> <span class="giallo-l"><span>0x2d8f6ea0f5b9d0e4bc1478161f5ed2ad3d8495938b414dcaec9548adbe572671,</span></span> <span class="giallo-l"><span>0x19954625f13d9bab758074bf6dee47484260d29ee118347c1701aaa74abd9848,</span></span> <span class="giallo-l"><span>0x842ef2ad456e6f53d75e91e8744b96398df80350cf7af90b145fea51fbbcf067,</span></span> <span class="giallo-l"><span>0x34a8b0a76ac20308aa5175710fb3e75c275b1ff25dba17c04e3a3e3c48ca222c,</span></span> <span class="giallo-l"><span>0x58efcbe75f32577afe5e9ff827624368b1559c32fcca0cf4fd704af8ce019c63,</span></span> <span class="giallo-l"><span>0x411b4d242ef8f14d92bd8b0b01cb4fa3ca6f29c6f9073cfdd3ce614fa717463b,</span></span> <span class="giallo-l"><span>0xf76dbda66ede5e789314a88cff87ecb4bd9ca418c75417d4d920e0d21a523257,</span></span> <span class="giallo-l"><span>0xd801821a0f87b4520c1b003fe4936b6852c410ee00b46fb0f81621c9ac6bf6b4,</span></span> <span class="giallo-l"><span>0x97ad11d6a29c8cf3c548c094c92f077014de3629d1e9053a25dbfaf7eb55f72d,</span></span> <span class="giallo-l"><span>0xa87012090cd19886d49521d564ab2ad0f18fd489599050c42213bb960c9ee8ff,</span></span> <span class="giallo-l"><span>0x8868d8a26e758d50913f2bf228da0444a206e52853bb42dd8f90f09abe9c859a,</span></span> <span class="giallo-l"><span>0xc257fb0cc9970e02830571bf062a14540556abad2a1a158f17a18f14b8bcbe95,</span></span> <span class="giallo-l"><span>0xfe611ce27238541b14dc174b652dd06719dfbcda846a027f9d1a9e8e9df2c065,</span></span> <span class="giallo-l"><span>0xc9b25ea410f420cc2d4fc6057801d180c6cab959bce56bf6120f555966e6de6d,</span></span> <span class="giallo-l"><span>0x95437f0524ec3c04d4132c83be7f1a603e6f4743a85ede25aa97a1a4e3f3f8fc,</span></span> <span class="giallo-l"><span>0x82a12910104065f35e983699c4b9187aed0ab0ec6146f91728901efecc7e2e20,</span></span> <span class="giallo-l"><span>0x6622dd11e09252004fb5aaa39e283333c0686065f228c48a5b55ee2060dbd139,</span></span> <span class="giallo-l"><span>0x89a2879f25733dab254e4fa6fddb4f04b8ddf018bf9ad5c162aea5c858e6faaa,</span></span> <span class="giallo-l"><span>0x8a71b62075a6011fd9b65d956108fa79cc9ebb8f194d64d3105a164e01cf43a6,</span></span> <span class="giallo-l"><span>0x103f4fe9ce211b6452181371f0dc4a30a557064b684645a4495136f4ebd0936a,</span></span> <span class="giallo-l"><span>0x97914adc5d7ce80147c2f44a6b29d0b495d38dedd8cc299064abcc62ed1ddabc,</span></span> <span class="giallo-l"><span>0x825c481da6c836a8696d7fda4b0563d204a9e7d9e4c47b46ded26db3e2d7d734,</span></span> <span class="giallo-l"><span>0xf8c0637ba4c0a383229f1d730db733bc11d6a4e33214216c23f69ec965dcaaad,</span></span> <span class="giallo-l"><span>0xaed3bdaf0cb12d37764d243ee0e8acdefc399be2cabbf1e51dc43454efd79cbd,</span></span> <span class="giallo-l"><span>0xe8427f56cc5cec8554e2f5f586b57adccbea97d5fc3ef7b8bbe97c2097cf848c,</span></span> <span class="giallo-l"><span>0xba4ad0abd5c14d526357fd0b6f8676ef6126aeb4a6d80cabe1f1281b9d28246c,</span></span> <span class="giallo-l"><span>0x4cff20b72e2ab5af3fafbf9222146949527c25f485ec032f22d94567ff91b22f,</span></span> <span class="giallo-l"><span>0x0d32925d89dd8fed989912afcbe830a4b5f8f7ae1a3e08ff1d3a575a77071d99,</span></span> <span class="giallo-l"><span>0xe51a1cbeae0be5d2fdbc7941aea904d3eade273f7477f60d5dd6a12807246030,</span></span> <span class="giallo-l"><span>0xfb8615046c969ef0fa5e6dc9628c8a9880e86a5dc2f6fc87aff216ea83fcf161,</span></span> <span class="giallo-l"><span>0x64dd705e105c88861470d112c64ca3d038f67660a02d3050ea36c34a9ebf47f9,</span></span> <span class="giallo-l"><span>0xb6ad148095c97528180f60fa7e8609bf5ce92bd562682092d79228c2e6f0750c,</span></span> <span class="giallo-l"><span>0x5bae0cd81f3bd0384ca3143a72068e6010b946462a73299e746ca639c026781c,</span></span> <span class="giallo-l"><span>0xc39a0fc7764fcfc0402b12fb0bbe78fe3633cbfb33c7f849279585a878a26d7c,</span></span> <span class="giallo-l"><span>0x2b752fda1c0c53d685cc91144f78d371db6b766725872b62cc99e1234cca8c1a,</span></span> <span class="giallo-l"><span>0x40ee6b9635d87c95a528757729212a261843ecb06d975de91352d43ca3c7f196,</span></span> <span class="giallo-l"><span>0x75e2005d3726cf8a4bb97ea5287849a361e3f8fdfadc3c1372feed1208c89f6b,</span></span> <span class="giallo-l"><span>0x0976f8ab556153964b58158678a5297da4d6ad92e284da46052a791ee667aee4,</span></span> <span class="giallo-l"><span>0xdbeef07841e41e0672771fb550a5b9233ae8e9256e23fa0d34d5ae5efe067ec8,</span></span> <span class="giallo-l"><span>0xa890f412ab6061c0c5ee661e80d4edc5c36b22fb79ac172ddd5ff26a7dbe9751,</span></span> <span class="giallo-l"><span>0xb666ae07f9276f6d0a33f9efeb3c5cfcba314fbc06e947563db92a40d7a341e8,</span></span> <span class="giallo-l"><span>0x83a082cf97ee78fbd7f31a01ae72e40c2e980a6dab756161544c27da86043528,</span></span> <span class="giallo-l"><span>0xfa726a919c6f8840c456dc77b0fec5adbed729e0efbb9317b75f77ed479c0f44,</span></span> <span class="giallo-l"><span>0xa8606800c54faeab2cbc9d85ff556c49dd7e1a0476027e0f7ce2c1dc2ba7ccbf,</span></span> <span class="giallo-l"><span>0x2796277836ab4c17a584c9f6c7778d10912cb19e541fb75453796841e1f6cd1c,</span></span> <span class="giallo-l"><span>0xf648b8b3c7be06f1f8d9cda13fd6d60f913e5048a8e0b283b110ca427eeb715f,</span></span> <span class="giallo-l"><span>0xa21d00b8fdcd77295d4064e00fbc30bed579d8255e9cf3a9016911d832390717,</span></span> <span class="giallo-l"><span>0xe741afcd98cbb3bb140737ed77bb968ac60d5c00022d722f9f04f56e97235dc9,</span></span> <span class="giallo-l"><span>0xbeecc9638fac39708ec16910e5b02c91f83f6321f6eb658cf8a96353cfb49806,</span></span> <span class="giallo-l"><span>0x912eee6cabeb0fed8d6e6ca0ba61977fd8e09ea0780ff8fbec995e2a85e08b52,</span></span> <span class="giallo-l"><span>0xc665bc0bb121a1229bc56ecc07a7e234fd24c523ea14700aa09e569b5f53ad33,</span></span> <span class="giallo-l"><span>0x39501621c2bdff2f62ab8d8e3fe47fe1701a98c665697c5b750ee1892f11846e,</span></span> <span class="giallo-l"><span>0x03d32e16c3a6c913daefb139f131e1e95a742b7be8e20ee39b785b4772a50e44,</span></span> <span class="giallo-l"><span>0x4f504eb46a82d440f1c952a06f143994bc66eb9e3ed865080cd9dfc6d652b69c,</span></span> <span class="giallo-l"><span>0xad753dc8710a46a70e19189d8fc7f4c773e4d9ccc7a70c354b574fe377328741,</span></span> <span class="giallo-l"><span>0xf7f5464a2d723b81502adb9133a0a4f0589b4134ca595a82e660987c6b011610,</span></span> <span class="giallo-l"><span>0x216b60b1c3e3bb4213ab5d43e04619d13e1ecedbdd65a1752bda326223e3ca3e,</span></span> <span class="giallo-l"><span>0x763664aa96d27b6e2ac7974e3ca9c9d2a702911bc5d550d246631965cf2bd4a2,</span></span> <span class="giallo-l"><span>0x292b5c8c8431b040c04d631f313d4e6b67b5fd3d4b8ac9f2edb09d13ec61f088,</span></span> <span class="giallo-l"><span>0x80db43c2b9e56eb540592f15f5900222faf3f75ce62e78189b5aa98c54568a5e,</span></span> <span class="giallo-l"><span>0x1b5fdf8969bcd4d65e86a2cefb3a673e18d587843f4f50db4e3ee77a0ba2ef1c,</span></span> <span class="giallo-l"><span>0x11e237953fff3e95e6572da50a92768467ffdfd0640d3384aa1c486357e7c24a,</span></span> <span class="giallo-l"><span>0x1fabd4faa8dba44808cc87d0bc389654a98496745578f3d17d134adc7f7b10f3,</span></span> <span class="giallo-l"><span>0x5eca4aa96f20a56197772ae6b600762154ca9d2702cab12664ea47cbff1a440c,</span></span> <span class="giallo-l"><span>0x0b4234f5bb02abcf3b5ce6c44ea85f55ec7db98fa5a7b90abef6dd0df034743c,</span></span> <span class="giallo-l"><span>0x316761e295bf350313c4c92efea591b522f1df4211ce94b22e601f30aefa51ef,</span></span> <span class="giallo-l"><span>0xe93a55ddb4d7dfe02598e8f909ff34b3de40a1c0ac8c7fba48cb604ea60631fb,</span></span> <span class="giallo-l"><span>0xe6e6c877b996857637f8a71d0cd9a6d47fdeb03752c8965766f010073332b087,</span></span> <span class="giallo-l"><span>0xa4f95c8874e611eddd2c4502e4e1196f0f1be90bfc37db35f8588e7d81d34aeb,</span></span> <span class="giallo-l"><span>0x9351710a5633714bb8b2d226e15ba4caa6f50f56c5508e5fa1239d5cc6a7e1aa,</span></span> <span class="giallo-l"><span>0x8d0aef52ec7266f37adb572913a6213b8448caaf0384008373dec525ae6cdff1,</span></span> <span class="giallo-l"><span>0x718e24c3970c85bcb14d2763201812c43abac0a7f16fc5787a7a7b2f37288586,</span></span> <span class="giallo-l"><span>0x3600ce44cebc3ee46b39734532128eaf715c0f3596b554f8478b961b0d6e389a,</span></span> <span class="giallo-l"><span>0x50dd1db7b0a5f6bd2d16252f43254d0f5d009e59f61ebc817c4bbf388519a46b,</span></span> <span class="giallo-l"><span>0x67861ed00f5fef446e1f4e671950ac2ddae1f3b564f1a6fe945e91678724ef03,</span></span> <span class="giallo-l"><span>0x0e332c26e169648bc20b4f430fbf8c26c6edf1a235f978d09d4a74c7b8754aad,</span></span> <span class="giallo-l"><span>0x6c9901015adf56e564dfb51d41a82bde43fb67273b6911c9ef7fa817555c9557,</span></span> <span class="giallo-l"><span>0x53c83391e5e0a024f68d5ade39b7a769f10664e12e4942c236398dd5dbce47a1,</span></span> <span class="giallo-l"><span>0x78619564f0b2399a9fcb229d938bf1e298d62b03b7a37fe6486034185d7f7d27,</span></span> <span class="giallo-l"><span>0x4625f15381a8723452ec80f3dd0293c213ae35de737c508f42427e1735398c3a,</span></span> <span class="giallo-l"><span>0x69542425ddb39d3d3981e76b41173eb1a09500f11164658a3536bf3e292f8b6a,</span></span> <span class="giallo-l"><span>0x82ac4f5bb40aece7d6706f1bdf4dfba5c835c09afba6446ef408d8ec6c09300f,</span></span> <span class="giallo-l"><span>0x740f9180671091b4c5b3ca59b9515bd0fc751f48e488a9f7f4b6848602490e21,</span></span> <span class="giallo-l"><span>0x9a04b08b4115986d8848e80960ad67490923154617cb82b3d88656ec1176c24c,</span></span> <span class="giallo-l"><span>0xf9ffe528eccffad519819d9eef70cef317af33899bcaee16f1e720caf9a98744,</span></span> <span class="giallo-l"><span>0x46da5e1a14b582b237f75556a0fd108c4ea0d55c0edd8f5d06c59a42e57410df,</span></span> <span class="giallo-l"><span>0x098f3429c8ccda60c3b5b9755e5632dd6a3f5297ee819bec8de2d8d37893968a,</span></span> <span class="giallo-l"><span>0x1a5b91af6025c11911ac072a98b8a44ed81f1f3c76ae752bd28004915db6f554,</span></span> <span class="giallo-l"><span>0x8bed50c7cae549ed4f8e05e02aa09b2a614c0af8eec719e4c6f7aee975ec3ec7,</span></span> <span class="giallo-l"><span>0xd86130f624b5dcc116f2dfbb5219b1afde4b7780780decd0b42694e15c1f8d8b,</span></span> <span class="giallo-l"><span>0x4167aa9bc0075f624d25d40eb29139dd2c452ebf17739fab859e14ac6765337a,</span></span> <span class="giallo-l"><span>0xa258ce5db20e91fb2ea30d607ac2f588bdc1924b21bbe39dc881e19889a7f5c6,</span></span> <span class="giallo-l"><span>0xe5ef8b5ab3cc8894452d16dc875b69a55fd925808ac7cafef1cd19485d0bb50a,</span></span> <span class="giallo-l"><span>0x120df2b3975d85b6dfca56bb98a82025ade5ac1d33e4319d2e0105b8de9ebf58,</span></span> <span class="giallo-l"><span>0xc964291dd2e0807a468396ebba3d59cfe385d949f6d6215976fc9a0a11de209a,</span></span> <span class="giallo-l"><span>0xf23f14cb709074b79abe166f159bc52b50de687464df6a5ebf112aa953c95ad5,</span></span> <span class="giallo-l"><span>0x622c092c9bd7e30f880043762e26d8e9c73ab7c0d0806f3c5e472a4152b35a93,</span></span> <span class="giallo-l"><span>0x8a5f090662731e7422bf651187fb89812419ab6808f2c62da213d6944fccfe9f,</span></span> <span class="giallo-l"><span>0xfbea3c0d92e061fd2399606f42647d65cc54191fa46d57b325103a75f5c22ba6,</span></span> <span class="giallo-l"><span>0x2babfbcc08d69b52c3747ddc8dcad4ea5511edabf24496f3ff96a1194d6f680e,</span></span> <span class="giallo-l"><span>0x4d3d019c28c779496b616d85aee201a3d79d9eecf35f728d00bcb12245ace703,</span></span> <span class="giallo-l"><span>0xe76fcee1f08325110436f8d4a95476251326b4827399f9b2ef7e12b7fb9c4ba1,</span></span> <span class="giallo-l"><span>0x4884d9c0bb4a9454ea37926591fc3eed2a28356e0506106a18f093035638da93,</span></span> <span class="giallo-l"><span>0x74c3f303d93d4cc4f0c1eb1b4378d34139220eb836628b82b649d1deb519b1d3,</span></span> <span class="giallo-l"><span>0xacb806670b278d3f0c84ba9c7a68c7df3b89e3451731a55d7351468c7c864c1c,</span></span> <span class="giallo-l"><span>0x8660fb8cd97e585ea7a41bccb22dd46e07eee8bbf34d90f0f0ca854b93b1ebee,</span></span> <span class="giallo-l"><span>0x2fc9c89cdca71a1c0224d469d0c364c96bbd99c1067a7ebe8ef412c645357a76,</span></span> <span class="giallo-l"><span>0x8ec6d5ab6ad7135d66091b8bf269be44c20af1d828694cd8650b5479156fd700,</span></span> <span class="giallo-l"><span>0x50ab4776e8cabe3d864fb7a1637de83f8fbb45d6e49645555ffe9526b27ebd66,</span></span> <span class="giallo-l"><span>0xbf39f5e17082983da4f409f91c7d9059acd02ccbefa69694aca475bb8d40b224,</span></span> <span class="giallo-l"><span>0x3135b3b981c850cc3fe9754ec6af117459d355ad6b0915beb61e84ea735c31bf,</span></span> <span class="giallo-l"><span>0xa7971dab52ce4bf45813223b0695f8e87f64b614c9c5499faac6f842e5c41be9,</span></span> <span class="giallo-l"><span>0x9e480f5617323ab104b4087ac4ef849a5da03427712fb302ac085507c77d8f37,</span></span> <span class="giallo-l"><span>0x57a6d474654d5e8d408159be39ad0e7026e6a4c6a6543e23a63d30610dc8dfc1,</span></span> <span class="giallo-l"><span>0x09eb3e01a5915a4e26d90b4c58bf0cf1e560fdc8ba53faed9d946ad3e9bc78fa,</span></span> <span class="giallo-l"><span>0x29c6d25da80a772310226b1b89d845c7916e4a4bc94d75aa330ec3eaa14b1e28,</span></span> <span class="giallo-l"><span>0x1a1ccfee11edeb989ca02e3cb89f062612a22a69ec816a625835d79370173987,</span></span> <span class="giallo-l"><span>0x1cb63dc541cf7f71c1c4e8cabd2619c3503c0ea1362dec75eccdf1e9efdbfcfc,</span></span> <span class="giallo-l"><span>0xac9dff32a69e75b396a2c250e206b36c34c63b955c9e5732e65eaf7ccca03c62,</span></span> <span class="giallo-l"><span>0x3e1b4f0c3ebd3d38cec389720147746774fc01ff6bdd065f0baf2906b16766a8,</span></span> <span class="giallo-l"><span>0x5cc8bed25574463026205e90aad828521f8e3d440970d7e810d1b46849681db5,</span></span> <span class="giallo-l"><span>0x255185d264509bd3a768bb0d50b568e66eb1fec96d573e33aaacc716d7c8fb93,</span></span> <span class="giallo-l"><span>0xe81b86ba631973918a859ff5995d7840b12511184c2865401f2693a71b9fa07e,</span></span> <span class="giallo-l"><span>0x61e67e42616598da8d36e865b282127c761380d3a56d26b8d35fbbc7641433c5,</span></span> <span class="giallo-l"><span>0x60c62ffef83fe603a34ca20b549522394e650dad5510ae68b6e074f0cd209a56,</span></span> <span class="giallo-l"><span>0x78577f2caf4a54f6065593535d76216f5f4075af7e7a98b79571d33b1822920c,</span></span> <span class="giallo-l"><span>0xfd4cb354f2869c8650200de0fe06f3d39e4dbebf19b0c1c2677da916ea84f44d,</span></span> <span class="giallo-l"><span>0x453769cef6ff9ba2d5c917982a1ad3e2f7e947d9ea228857556af0005665e0b0,</span></span> <span class="giallo-l"><span>0xe567f93f8f88bf1a6b33214f17f5d60c5dbbb531b4ab21b8c0b799b6416891e0,</span></span> <span class="giallo-l"><span>0x7e65a39a17f902a30ceb2469fe21cba8d4e0da9740fcefd5c647c81ff1ae95fa,</span></span> <span class="giallo-l"><span>0x03e4a7eea0cd6fc02b987138ef88e8795b5f839636ca07f6665bbae9e5878931,</span></span> <span class="giallo-l"><span>0xc3558e2b437cf0347cabc63c95fa2710d3f43c65d380feb998511903f9f4dcf0,</span></span> <span class="giallo-l"><span>0xe3a615f80882fb5dfbd08c1d7a8b0a4d3b651d5e8221f99b879cb01d97037a9c,</span></span> <span class="giallo-l"><span>0xb56db4a5fea85cbffaee41f05304689ea321c40d4c108b1146fa69118431d9b2,</span></span> <span class="giallo-l"><span>0xab28e1f077f18117945910c235bc9c6f9b6d2b45e9ef03009053006c637e3e26,</span></span> <span class="giallo-l"><span>0xefcabc1d5659fd6e48430dbfcc9fb4e08e8a9b895f7bf9b3d6c7661bfc44ada2,</span></span> <span class="giallo-l"><span>0xc7547496f212873e7c3631dafaca62a6e95ac39272acf25a7394bac6ea1ae357,</span></span> <span class="giallo-l"><span>0xc482013cb01bd69e0ea9f447b611b06623352e321469f4adc739e3ee189298eb,</span></span> <span class="giallo-l"><span>0x5942f42e91e391bb44bb2c4d40da1906164dbb6d1c184f00fa62899baa0dba2c,</span></span> <span class="giallo-l"><span>0xb4bcb46c80ad4cd603aff2c1baf8f2c896a628a46cc5786f0e58dae846694677,</span></span> <span class="giallo-l"><span>0xd0a7305b995fa8c317c330118fee4bfef9f65f70b54558c0988945b08e90ff08,</span></span> <span class="giallo-l"><span>0x687f801b7f32fdfa7d50274cc7b126efedbdae8de154d36395d33967216f3086,</span></span> <span class="giallo-l"><span>0xeb19ec10ac6c15ffa619fa46792971ee22a9328fa53bd69a10ed6e9617dd1bbf,</span></span> <span class="giallo-l"><span>0xa2bb3f0367f62abdb3a9fa6da34b20697cf214a4ff14fd42826da140ee025213,</span></span> <span class="giallo-l"><span>0x070a76511f32c882374400af59b22d88974a06fbc10d786dd07ca7527ebd8b90,</span></span> <span class="giallo-l"><span>0x8f195689537b446e946b376ec1e9eb5af5b4542ab47be550a5700fa5d81440d5,</span></span> <span class="giallo-l"><span>0x10cc09778699fc8ac109e7e6773f83391eeba2a6db5226fbe953dd8d99126ca5,</span></span> <span class="giallo-l"><span>0x8cc839cb7dc84fd3b8c0c7ca637e86a2f72a8715cc16c7afb597d12da717530b,</span></span> <span class="giallo-l"><span>0xa32504e6cc6fd0ee441440f213f082fcf76f72d36b5e2a0f3b6bdd50cdd825a2,</span></span> <span class="giallo-l"><span>0x8f45151db8878e51eec12c450b69fa92176af21a4543bb78c0d4c27286e74469,</span></span> <span class="giallo-l"><span>0x23f5c465bd35bcd4353216dc9505df68324a27990df9825a242e1288e40a13bb,</span></span> <span class="giallo-l"><span>0x35f409ce748af33c20a6ae693b8a48ba4623de9686f9834e22be4410e637d24f,</span></span> <span class="giallo-l"><span>0xb962e5845c1db624532562597a99e2acc5e434b97d8db0725bdeddd71a98e737,</span></span> <span class="giallo-l"><span>0x0f8364f99f43dd52b4cfa9e426c48f7b6ab18dc40a896e96a09eceebb3363afe,</span></span> <span class="giallo-l"><span>0xa842746868da7644fccdbb07ae5e08c71a6287ab307c4f9717eadb414c9c99f4,</span></span> <span class="giallo-l"><span>0xa59064c6b7fe7d2407792d99ed1218d2dc2f240185fbd8f767997438241b92e9,</span></span> <span class="giallo-l"><span>0xb6ea0d58e8d48e05b9ff4d75b2ebe0bd9752c0e2691882f754be66cdec7628d3,</span></span> <span class="giallo-l"><span>0xf16b78c9d14c52b2b5156690b6ce37a5e09661f49674ad22604c7d3755e564d1,</span></span> <span class="giallo-l"><span>0xbfa8ef74e8a37cd64b8b4a4260c4fc162140603f9c2494b9cf4c1e13de522ed9,</span></span> <span class="giallo-l"><span>0xf4b89f1776ebf30640dc5ec99e43de22136b6ef936a85193ef940931108e408a,</span></span> <span class="giallo-l"><span>0xefb9a4555d495a584dbcc2a50938f6b9827eb014ffae2d2d0aae356a57894de8,</span></span> <span class="giallo-l"><span>0x0627a466d42a26aca72cf531d4722e0e5fc5d491f4527786be4e1b641e693ac2,</span></span> <span class="giallo-l"><span>0x7d10d21542de3d8f074dbfd1a6e11b3df32c36272891aae54053029d39ebae10,</span></span> <span class="giallo-l"><span>0x0f21118ee9763f46cc175a21de876da233b2b3b62c6f06fa2df73f6deccf37f3,</span></span> <span class="giallo-l"><span>0x143213b96f8519c15164742e2350cc66e814c9570634e871a8c1ddae4d31b6b5,</span></span> <span class="giallo-l"><span>0x8d2877120abae3854e00ae8cf5c8c95b3ede10590ab79ce2be7127239507e18d,</span></span> <span class="giallo-l"><span>0xaccd0005d59472ac04192c059ed9c10aea42c4dabec9e581f6cb10b261746573,</span></span> <span class="giallo-l"><span>0x67bc8dd5422f39e741b9995e6e60686e75d6620aa0d745b84191f5dba9b5bb18,</span></span> <span class="giallo-l"><span>0x11b8e95f6a654d4373cefbbac29a90fdd8ae098043d1969b9fa7885318376b34,</span></span> <span class="giallo-l"><span>0x431a0b8a6f08760c942eeff5791e7088fd210f877825ce4dcabe365e03e4a65c,</span></span> <span class="giallo-l"><span>0x704007f11bae513f428c9b0d23593fd2809d0dbc4c331009856135dafec23ce4,</span></span> <span class="giallo-l"><span>0xc06dee39a33a05e30c522061c1d9272381bde3f9e42fa9bd7d5a5c8ef11ec6ec,</span></span> <span class="giallo-l"><span>0x66b4157baaae85db0948ad72882287a80b286df2c40080b8da4d5d3db0a61bd2,</span></span> <span class="giallo-l"><span>0xef1983b1906239b490baaaa8e4527f78a57a0a767d731f062dd09efb59ae8e3d,</span></span> <span class="giallo-l"><span>0xf26d0d5c520cce6688ca5d51dee285af26f150794f2ea9f1d73f6df213d78338,</span></span> <span class="giallo-l"><span>0x8b28838382e6892f59c42a7709d6d38396495d3af5a8d5b0a60f172a6a8940bd,</span></span> <span class="giallo-l"><span>0x261a605fa5f2a9bdc7cffac530edcf976e7ea7af4e443b625fe01ed39dad44b6]</span></span> <span class="giallo-l"><span>compressed_lamport_PK = 0xdd635d27d1d52b9a49df9e5c0c622360a4dd17cba7db4e89bce3cb048fb721a5</span></span> <span class="giallo-l"><span>child_SK = 20397789859736650942317412262472558107875392172444076792671091975210932703118</span></span></code></pre><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> 2019-09-30T00:00:00+00:00 2026-02-11T14:48:26+00:00 Carl Beekhuizenhttps://github.com/CarlBeekcarl@ethereum.org https://wg-eips.ritovision.com/2334/

BLS12-381 Deterministic account hierarchy structure

<h2 id="abstract">Abstract</h2> <p>A standard for allocating keys generated by <a href="https://wg-eips.ritovision.com/2333/">ERC-2333</a> to a specific purpose. It defines a <code>path</code> which is a string that parses into the indices to be used when traversing the tree of keys that <a href="https://wg-eips.ritovision.com/2333/">ERC-2333</a> generates.</p> <h2 id="motivation">Motivation</h2> <p>The Beacon chain uses BLS signatures over BLS12-381. This new scheme requires a new key derivation mechanism, which is established within <a href="https://wg-eips.ritovision.com/2333/">ERC-2333</a>. This new scheme is incompatible with <a rel="external" href="https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0044.mediawiki">BIP44</a> due to the exclusive use of hardened keys, the increased number of keys per level, not using <a rel="external" href="https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0032.mediawiki">BIP32</a> for key derivation. It is therefore necessary to establish a new <em>path</em> for traversing the <a href="https://wg-eips.ritovision.com/2333/">ERC-2333</a> key-tree.</p> <p>The path structure specified in this ERC aims to be more general than <a rel="external" href="https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0044.mediawiki">BIP44</a> by not having UTXO-centric features which gave rise to the 4 different types of wallet paths being used within Ethereum in the past and gave rise to (draft) <a href="https://wg-eips.ritovision.com/600/">ERC-600</a> &amp; <a href="https://wg-eips.ritovision.com/601/">ERC-601</a></p> <h2 id="specification">Specification</h2> <h3 id="path">Path</h3> <p>The path traversed through the tree of keys is defined by integers (which indicate the sibling index) separated by <code>/</code> which denote ancestor relations. There are 4 levels (plus the master node) in the path and at least 4 (5 including the master node) MUST be used.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>m / purpose / coin_type / account / use</span></span></code></pre><h4 id="notation">Notation</h4> <p>The notation used within the path is specified within the <a href="https://wg-eips.ritovision.com/2333/">ERC-2333</a>, but is summarized again below for convenience.</p> <ul> <li><code>m</code> Denotes the master node (or root) of the tree</li> <li><code>/</code> Separates the tree into depths, thus <code>i / j</code> signifies that <code>j</code> is a child of <code>i</code></li> </ul> <h3 id="purpose">Purpose</h3> <p>The <code>purpose</code> is set to <code>12381</code> which is the name of the new curve (BLS12-381). In order to be in compliance with this standard, the <a href="https://wg-eips.ritovision.com/2333/">ERC-2333</a> MUST be implemented as the KDF and therefore, the purpose <code>12381</code> MAY NOT be used unless this is the case.</p> <h3 id="coin-type">Coin Type</h3> <p>The <code>coin_type</code> here reflects the coin number for an individual coin thereby acting as a means of separating the keys used for different chains.</p> <h3 id="account">Account</h3> <p><code>account</code> is a field that provides the ability for a user to have distinct sets of keys for different purposes, if they so choose. This is the level at which different accounts for a single user SHOULD to be implemented.</p> <h3 id="use">Use</h3> <p>This level is designed to provide a set of related keys that can be used for any purpose. The idea being that a single account has many uses which are related yet should remain separate for security reasons. It is required to support this level in the tree, although, for many purposes it will remain <code>0</code>.</p> <h3 id="beacon-chain-specific-parameters">Beacon Chain Specific Parameters</h3> <h4 id="coin-type-1">Coin type</h4> <p>The coin type used for the BLS12-381 keys in Ethereum is <code>3600</code>.</p> <h4 id="validator-keys">Validator keys</h4> <p>Each Beacon chain validator has two keys, one for withdrawals and transfers (called the <em>withdrawal key</em>), and the other for performing their duties as a validator (henceforth referred to as the <em>signing key</em>).</p> <p>The path for withdrawal keys is <code>m/12381/3600/i/0</code> where <code>i</code> indicates the <code>i</code>th set of validator keys.</p> <p>The path for the signing key is <code>m/12381/3600/i/0/0</code> where again, <code>i</code> indicates the <code>i</code>th set of validator keys. Another way of phrasing this is that the signing key is the <code>0</code>th child of the associated withdrawal key for that validator.</p> <p><strong>Note:</strong> If the above description of key paths is not feasible in a specific use case (eg. with secret-shared or custodial validators), then the affected keys may be omitted and derived via another means. Implementations of this ERC, must endeavour to use the appropriate keys for the given use case to the extent that is reasonably possible. (eg, in the case of custodial staking, the user making the deposits will follow this standard for their withdrawal keys which has no bearing on how the service provide derives the corresponding signing keys.)</p> <h2 id="rationale">Rationale</h2> <p><code>purpose</code>, <code>coin_type</code>, and <code>account</code> are widely-adopted terms as per <a rel="external" href="https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0043.mediawiki">BIP43</a> and <a rel="external" href="https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0044.mediawiki">BIP44</a> and therefore reusing these terms and their associated meanings makes sense.</p> <p>The purpose needs to be distinct from these standards as the KDF and path are not inter-compatible and <code>12381</code> is an obvious choice.</p> <p><code>account</code> separates user activity into distinct categories thereby allowing users to separate their concerns however they desire.</p> <p><code>use</code> will commonly be determined at the application level providing distinct keys for non-intersecting use cases.</p> <h3 id="beacon-chain-specific-parameters-1">Beacon Chain Specific Parameters</h3> <p>A new coin type is chosen for Beacon Chain BLS keys to help ensure a clean separation between BLS12-381 and secp256k1 keys. <code>3600</code> is chosen specifically because it is the square of the Ethereum's secp256k1 <code>coin_type</code> (<code>3600==60^2</code>).</p> <p>The primary reason validators have separate signing and withdrawal keys is to allow for the different security concerns of actions within the Beacon Chain. The signing key is given to the validator client where it signs messages as per the requirements of being a validator, it is therefore a "hot key". If this key is compromised, the worst that can happen (locally) is that a slashable message is signed, resulting in the validator being slashed and forcibly exited. The withdrawal key is only needed when a validator wishes to perform an action not related to validating and has access to the full funds at stake for that validator. The withdrawal key therefore has higher security concerns and should be handled as a "cold key". By having the signing key be a child of the withdrawal key, secure storage of the withdrawal key is sufficient to recover the signing key should the need arise.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><a rel="external" href="https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0043.mediawiki">BIP43</a> and <a rel="external" href="https://github.com/bitcoin/bips/blob/43ce3a461dfb48e62ffa0cfc70f5f54d1eb5c577/bip-0044.mediawiki">BIP44</a>. Due to the use of a new KDF within <a href="https://wg-eips.ritovision.com/2333/">ERC-2333</a>, a new path standard is required. This ERC implements this, with minor changes.</p> <p><code>purpose</code> <code>12381</code> paths do not support hardened keys and therefore the <code>'</code> character is invalid.</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> 2019-09-30T00:00:00+00:00 2026-02-11T14:48:26+00:00 Carl Beekhuizenhttps://github.com/CarlBeekcarl@ethereum.org https://wg-eips.ritovision.com/2335/

Keystore for storing BLS12-381 keys

<h2 id="abstract">Abstract</h2> <p>A keystore is a mechanism for storing private keys. It is a JSON file that encrypts a private key and is the standard for interchanging keys between devices as until a user provides their password, their key is safe.</p> <h2 id="motivation">Motivation</h2> <p>The secure storage and exchange of keys is a vital component of the user experience as people are expected to hold their own keys. It allows users to control access to individual keys and their use by applications.</p> <p>In Ethereum, Web3 Secret Storage (commonly referred to as "keystores") fulfills these requirements, however it is not perfectly suitable for these purposes moving forward. Specifically the problems with the existing standard are:</p> <ul> <li> <p><strong>The use of Keccak256.</strong> Web3 Secret Stores use Keccak for their checksum. BLS signatures, <a href="https://wg-eips.ritovision.com/2333/">keys (ERC-2333)</a>, and key-storage are inter-chain standards, the establishment and proliferation of which hinges on them being neutral to all chains, something which Keccak is not.</p> </li> <li> <p><strong>A lack of abstraction.</strong> Web3 Secret Stores are a result of an iterative design process whereby functionality was added and modified as needed without considering how abstractions could simplify the notion of different properties.</p> </li> </ul> <h2 id="specification">Specification</h2> <p>The process of decrypting the secret held within a keystore can be broken down into 3 sub-processes: obtaining the decryption key, verifying the password and decrypting the secret. Each process has its own functions which can be selected from as well as parameters required for the function all of which are specified within the keystore file itself.</p> <h3 id="password-requirements">Password requirements</h3> <p>The password is a string of arbitrary unicode characters. The password is first converted to its NFKD representation, then the control codes (specified below) are stripped from the password and finally it is UTF-8 encoded.</p> <h4 id="control-codes-removal">Control codes removal</h4> <p>The C0, C1, and <code>Delete</code> control codes are not valid characters in the password and should therefore be stripped from the password. C0 are the control codes between <code>0x00</code> - <code>0x1F</code> (inclusive) and C1 codes lie between <code>0x80</code> and <code>0x9F</code> (inclusive). <code>Delete</code>, commonly known as "backspace", is the UTF-8 character <code>7F</code> which must also be stripped. Note that space (<code>Sp</code> UTF-8 <code>0x20</code>) is a valid character in passwords despite it being a pseudo-control character.</p> <h3 id="modules">Modules</h3> <p>This standard makes use of the notion of a <em>module</em> which serves to represent, in an abstract sense, the different  cryptographic constructions and corresponding parameters for each component of the keystore. The idea being that components can be swapped out without affecting the rest of the specification should the need arise.</p> <p>A module is comprised of a <code>function</code>, which defines which cryptographic construct is being used, <code>params</code>, the parameters required by the function, and <code>message</code> the primary input to the function.</p> <h3 id="decryption-key">Decryption key</h3> <p>The decryption key is an intermediate key which is used both to verify the user-supplied password is correct, as well as for the final secret decryption. This key is simply derived from the password, the <code>function</code>, and the <code>params</code> specified by the<code>kdf</code> module as per the keystore file.</p> <table><thead><tr><th>KDF</th><th><code>"function"</code></th><th><code>"params"</code></th><th><code>"message"</code></th><th>Definition</th></tr></thead><tbody> <tr><td>PBKDF2-SHA-256</td><td><code>"pbkdf2"</code></td><td><ul><li><code>"c"</code></li><li><code>"dklen"</code></li><li><code>"prf: "hmac-sha256"</code></li><li><code>"salt"</code></li></ul></td><td></td><td><a rel="external" href="https://www.rfc-editor.org/rfc/rfc2898">RFC 2898</a></td></tr> <tr><td>scrypt</td><td><code>"scrypt"</code></td><td><ul><li><code>"dklen"</code></li><li><code>"n"</code></li><li><code>"p"</code></li><li><code>"r"</code></li><li><code>"salt"</code></li></ul></td><td></td><td><a rel="external" href="https://www.rfc-editor.org/rfc/rfc7914">RFC 7914</a></td></tr> </tbody></table> <h3 id="password-verification">Password verification</h3> <p>The password verification step verifies that the password is correct with respect to the <code>checksum.message</code>, <code>cipher.message</code>, and <code>kdf</code>. This is done by appending the <code>cipher.message</code> to the 2nd 16 bytes of the decryption key, obtaining its SHA256 hash and verifying whether it matches the <code>checksum.message</code>.</p> <h4 id="inputs">Inputs</h4> <ul> <li><code>decryption_key</code>, the octet string obtained from decryption key process</li> <li><code>cipher_message</code>, the octet string obtained from keystore file from <code>crypto.cipher.message</code></li> <li><code>checksum_message</code>, the octet string obtained from keystore file from <code>crypto.checksum.message</code></li> </ul> <h4 id="outputs">Outputs</h4> <ul> <li><code>valid_password</code>, a boolean value indicating whether the password is valid</li> </ul> <h4 id="definitions">Definitions</h4> <ul> <li><code>a[0:3]</code> returns a slice of <code>a</code> including octets 0, 1, 2</li> <li><code>a | b</code> is the concatenation of <code>a</code> with <code>b</code></li> </ul> <h4 id="procedure">Procedure</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0. DK_slice = decryption_key[16:32]</span></span> <span class="giallo-l"><span>1. pre_image = DK_slice | cipher_message</span></span> <span class="giallo-l"><span>2. checksum = SHA256(pre_image)</span></span> <span class="giallo-l"><span>3. valid_password = checksum == checksum_message</span></span> <span class="giallo-l"><span>4. return valid_password</span></span></code></pre><table><thead><tr><th>Hash</th><th><code>"function"</code></th><th><code>"params"</code></th><th><code>"message"</code></th><th>Definition</th></tr></thead><tbody> <tr><td>SHA-256</td><td><code>"sha256"</code></td><td></td><td></td><td><a rel="external" href="https://www.rfc-editor.org/rfc/rfc6234">RFC 6234</a></td></tr> </tbody></table> <h3 id="secret-decryption">Secret decryption</h3> <p>The <code>cipher.function</code> encrypts the secret using the decryption key, thus to decrypt it, the decryption key along with the <code>cipher.function</code> and <code>cipher.params</code> must be used. If the <code>decryption_key</code> is longer than the key size required by the cipher, it is truncated to the correct number of bits. In the case of aes-128-ctr, only the first 16 bytes of the <code>decryption_key</code> are used as the AES key.</p> <table><thead><tr><th>Cipher</th><th><code>"function"</code></th><th><code>"params"</code></th><th><code>"message"</code></th><th>Definition</th></tr></thead><tbody> <tr><td>AES-128 Counter Mode</td><td><code>"aes-128-ctr"</code></td><td><ul><li><code>"iv"</code></li></ul></td><td></td><td><a rel="external" href="https://www.rfc-editor.org/rfc/rfc3686">RFC 3686</a></td></tr> </tbody></table> <h3 id="description">Description</h3> <p>This field is an optional field to help explain the purpose and identify a particular keystores in a user-friendly manner. While this field can, and should, be used to help distinguish keystores from one-another, the <code>description</code> <strong>is not necessarily unique</strong>.</p> <h3 id="pubkey">PubKey</h3> <p>The <code>pubkey</code> is the public key associated with the private key secured within the keystore. It is stored here to improve user experience and security which is achieved by not requiring users to enter their password just to obtain their public keys. This field is required if the secret being stored within the keystore is a private key. The encoding of the <code>pubkey</code> is specified in the in the appropriate signature standard (eg. <a href="https://wg-eips.ritovision.com/2333/">ERC-2333</a>), but can be seen as a byte-string in the abstract and should be directly compatible with the appropriate signature library.</p> <h3 id="path">Path</h3> <p>The <code>path</code> indicates where in the key-tree a key originates from. It is a string defined by <a href="https://wg-eips.ritovision.com/2334/">ERC-2334</a>, if no path is known or the path is not relevant, the empty string, <code>""</code> indicates this. The <code>path</code> can specify an arbitrary depth within the tree and the deepest node within the tree indicates the depth of the key stored within this file.</p> <h3 id="uuid">UUID</h3> <p>The <code>uuid</code> provided in the keystore is a randomly generated UUID as specified by <a rel="external" href="https://www.rfc-editor.org/rfc/rfc4122">RFC 4122</a>. It is used as a 128-bit proxy for referring to a particular set of keys or account.</p> <h3 id="version">Version</h3> <p>The <code>version</code> is set to <code>4</code>.</p> <h3 id="json-schema">JSON schema</h3> <p>The keystore, at its core, is constructed with modules which allow for the configuration of the cryptographic constructions used password hashing, password verification and secret decryption. Each module is composed of: <code>function</code>, <code>params</code>, and <code>message</code> which corresponds with which construction is to be used, what the configuration for the construction is, and what the input is.</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/Keystore</span><span class="z-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">Keystore</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">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 class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">pubkey</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">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">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">crypto</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">path</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> ]</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">Keystore</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="security-considerations">Security Considerations</h2> <p>None.</p> <h2 id="rationale">Rationale</h2> <p>The rationale behind the design of this specification is largely the same as that behind the Ethereum Web3 Secret Storage Definition except for the lack of support for Keccak (explained in <a href="https://wg-eips.ritovision.com/2335/#motivation">motivation above</a>) and the notion of modules.</p> <p>Modules provide a very useful level of abstraction which allow the Key-Derivation-Function, Checksum, and Cipher to be thought of as instances of the same thing allowing for their substitution with minimal effort.</p> <p>The <code>version</code> is set to 4 to prevent collisions with the existing Ethereum keystore standard.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This specification is not backwards compatible with the Ethereum Web3 Secret Storage Definition due to the lack of Keccak256 checksums as explained above. While this format is capable of supporting Keccak checksums via the Checksum module, it would defeat the purpose of this standard to include it as this standard could no longer be considered neutral with respect to other projects in the industry.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="scrypt-test-vector">Scrypt Test Vector</h3> <p>Password <code>"𝔱𝔢𝔰𝔱𝔭𝔞𝔰𝔰𝔴𝔬𝔯𝔡🔑"</code> Encoded Password: <code>0x7465737470617373776f7264f09f9491</code> Secret <code>0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f</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">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">scrypt</span><span class="z-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">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">n</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 262144</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">p</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">r</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 8</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">d4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3</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 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> }</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">params</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">message</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">d2217fe5f3e9a1e34581ef8a78f7c9928e436d36dacc5e846690a5581e8ea484</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">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">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">264daa3f303d7259501c93d997d84fe6</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">06ae90d55fe0a6e9c5c3bc5b170827b2e5cce3929ed3f116c2811e6366dfe20f</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">description</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 test keystore that uses scrypt to secure the secret.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">pubkey</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">9612d7a727c9d0a22e185a1c768478dfe919cada9266988cb32359c11f2b7b27f4ae4040902382ae2910c15e2b420d07</span><span class="z-punctuation z-definition z-string">&quot;</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">m/12381/60/3141592653/589793238</span><span class="z-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">1d85ae20-35c5-4611-98e8-aa14a633906f</span><span class="z-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"> 4</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="pbkdf2-test-vector">PBKDF2 Test Vector</h3> <p>Password <code>"𝔱𝔢𝔰𝔱𝔭𝔞𝔰𝔰𝔴𝔬𝔯𝔡🔑"</code> Encoded Password: <code>0x7465737470617373776f7264f09f9491</code> Secret <code>0x000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f</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">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">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">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">c</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 262144</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">d4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3</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 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> }</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">params</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">message</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">8a9f5d9912ed7e75ea794bc5a89bca5f193721d30868ade6f73043c6ea6febf1</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">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">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">264daa3f303d7259501c93d997d84fe6</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">cee03fde2af33149775b7223e7845e4fb2c8ae1792e5f99fe9ecf474cc8c16ad</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">description</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 test keystore that uses PBKDF2 to secure the secret.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">pubkey</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">9612d7a727c9d0a22e185a1c768478dfe919cada9266988cb32359c11f2b7b27f4ae4040902382ae2910c15e2b420d07</span><span class="z-punctuation z-definition z-string">&quot;</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">m/12381/60/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">uuid</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">64625def-3331-4eea-ab6f-782f3ed16a83</span><span class="z-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"> 4</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations-1">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> 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-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 Dan Finlayhttps://github.com/danfinlay Erik Markshttps://github.com/rekmarks Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/2255/

An interface to restrict access to sensitive methods

<h2 id="abstract">Abstract</h2> <p>This EIP adds two new wallet-namespaced RPC endpoints, <code>wallet_getPermissions</code> and <code>wallet_requestPermissions</code>, providing a standard interface for requesting and checking permissions.</p> <h2 id="motivation">Motivation</h2> <p>Wallets are responsible for mediating interactions between untrusted applications and users' keys through appropriate user consent. Today, wallets always prompt the user for every action. This provides security at the cost of substantial user friction. We believe that a single permissions request can achieve the same level of security with vastly improved UX.</p> <p>The pattern of permissions requests (typically using Oauth2) is common around the web, making it a very familiar pattern:</p> <p><img src="https://wg-eips.ritovision.com/2255/./assets/facebook_permissions.png" alt="Facebook Permissions" /></p> <p><img src="https://wg-eips.ritovision.com/2255/./assets/log_in_with_apple.jpeg" alt="Log in With Apple" /></p> <p>Many web3 applications today begin their sessions with a series of repetitive requests:</p> <ul> <li>Reveal your wallet address to this site.</li> <li>Switch to a preferred network.</li> <li>Sign a cryptographic challenge.</li> <li>Grant a token allowance to our contract.</li> <li>Send a transaction to our contract.</li> </ul> <p>Many of these (and possibly all), and many more (like decryption), could be generalized into a set of human-readable permissions prompts on the original sign-in screen, and additional permissions could be requested only as needed:</p> <p><img src="https://wg-eips.ritovision.com/2255/./assets/permissions.png" alt="Sample prompt screenshot" /></p> <p>Each of these permissions could be individually rejected, or even <em>attenuated</em>--adjusted to meet the user's terms (for example, a sign-in request could have a user-added expiration date, and a token allowance could be adjusted by the user when it is requested).</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 two new methods to a wallet's web3 provider API: <code>wallet_getPermissions</code> and <code>wallet_requestPermissions</code>.</p> <h3 id="wallet-getpermissions"><code>wallet_getPermissions</code></h3> <p>The <code>wallet_getPermissions</code> method is used for getting an array of current permissions (empty by default). It takes no parameters and returns an array of <code>Permission</code> objects.</p> <h4 id="wallet-getpermissions-returns"><code>wallet_getPermissions</code> Returns</h4> <p>The format of the returned permissions MUST be an array of <code>Permission</code> objects, which are 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"> Caveat</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> any</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"> Permission</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> invoker</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> parentCapability</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> caveats</span><span class="z-keyword">:</span><span class="z-entity z-name"> Caveat</span><span>[</span><span>]</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>invoker</code> is a URI used to identify the source of the current dapp (e.g. <code>https://your-site.com/</code>). The term <code>parentCapability</code> refers to the method that is being permitted (e.g. <code>eth_accounts</code>). The <code>caveats</code> array represents the specific restrictions applied to the permitted method. The <code>type</code> of a <code>Caveat</code> is a string, and the <code>value</code> is an arbitrary JSON value. The <code>value</code> of a <code>Caveat</code> is only meaningful in the context of the <code>type</code> of the <code>Caveat</code>.</p> <h3 id="wallet-requestpermissions"><code>wallet_requestPermissions</code></h3> <p>The <code>wallet_requestPermissions</code> method is used for an application to request additional permissions. It MUST take a single parameter, a <code>PermissionRequest</code> object, and MUST return an array of <code>RequestedPermission</code> objects.</p> <h4 id="wallet-requestpermissions-parameters"><code>wallet_requestPermissions</code> Parameters</h4> <p>The <code>wallet_requestPermissions</code> method takes a single parameter, a <code>PermissionRequest</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"> PermissionRequest</span><span> {</span></span> <span class="giallo-l"><span> [</span><span class="z-variable">methodName</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>]</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span> [</span><span class="z-variable">caveatName</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>]</span><span class="z-keyword">:</span><span class="z-support"> any</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>methodName</code> is the name of the method for which the permission is being requested (e.g. <code>eth_accounts</code>). The <code>caveatName</code> is the name of the caveat being applied to the permission (e.g. <code>requiredMethods</code>). The caveat value is the value of the caveat (e.g. <code>["signTypedData_v3"]</code>).</p> <p>Attempted requests to a restricted method must fail with an error, until a <code>wallet_requestPermissions</code> request is made and accepted by the user.</p> <p>If a <code>wallet_requestPermissions</code> request is rejected, it should throw an error with a <code>code</code> value equal to <code>4001</code> as per <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a>.</p> <h4 id="wallet-requestpermissions-returns"><code>wallet_requestPermissions</code> Returns</h4> <p>The <code>wallet_requestPermissions</code> method returns an array of <code>RequestedPermission</code> objects, which are 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"> RequestedPermission</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> parentCapability</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> date</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>parentCapability</code> is the name of the method for which the permission is being requested (e.g. <code>eth_accounts</code>). The <code>date</code> is the timestamp of the request, in Unix time, and is optional.</p> <h2 id="rationale">Rationale</h2> <p>While the current model of getting user consent on a per-action basis has high security, there are huge usability gains to be had bo getting more general user consent which can cover broad categories of usage, which can be expressed in a more human-readable way. This pattern has a variety of benefits to offer different functions within a web3 wallet.</p> <p>The <code>requestPermissions</code> method can be expanded to include other options related to the requested permissions, for example, sites could request accounts with specific abilities. For example, a website like an exchange that requires <code>signTypedData_v3</code> (which is not supported by some hardware wallets), might want to specify that requirement. This would allow wallets to display only compatible accounts, while preserving the user's privacy and choice regarding how they are storing their keys.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="requesting-permissions">Requesting permissions</h3> <p>The following example should prompt the user to approve the <code>eth_accounts</code> permission, and return the permission object if approved.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">provider</span><span>.</span><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">requestPermissions</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> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_accounts</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> requiredMethods</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">signTypedData_v3</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></span></code></pre><h3 id="getting-permissions">Getting permissions</h3> <p>The following example should return the current permissions object.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">provider</span><span>.</span><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">getPermissions</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span>}</span><span>)</span><span>;</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <h3 id="server-side-request-forgery-ssrf">Server-Side Request Forgery (SSRF)</h3> <p>This consideration is applicable if the favicon of a website is to be displayed.</p> <p>Wallets should be careful about making arbitrary requests to URLs. As such, it is recommended for wallets to sanitize the URI by whitelisting specific schemes and ports. A vulnerable wallet could be tricked into, for example, modifying data on a locally-hosted redis database.</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-17T00:00:00+00:00 2026-02-11T14:48:25+00:00 Runchao Hanrunchao.han@monash.edu Haoyu Linchris.haoyul@gmail.com Jiangshan Yujiangshan.yu@monash.edu https://wg-eips.ritovision.com/2266/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard for token contracts providing Atomic Swap-based American Call Option functionalities.</p> <h2 id="abstract">Abstract</h2> <p>This standard provides functionality to make Atomic Swap-based American Call Option payment. The Atomic Swap protocol based on Hashed Time-Locked Contract (HTLC) <sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">1</a></sup> has optionality <sup class="footnote-reference" id="fr-2-1"><a href="#fn-2">2</a></sup>, and such optionality can be utilised to construct American Call Options without trusted third party. This standard defines the common way of implementing this protocol. In particular, this EIP defines technical terms, provides interfaces, and gives reference implementations of this protocol.</p> <h2 id="motivation">Motivation</h2> <p>Atomic Swap allows users to atomically exchange their tokens without trusted third parties while the HTLC is commonly used for the implementation. However, the HTLC-based Atomic Swap has optionality. More specifically, the swap initiator can choose to proceed or abort the swap for several hours, which gives him time for speculating according to the exchange rate. A discussion<sup class="footnote-reference" id="fr-2-2"><a href="#fn-2">2</a></sup> shows that the HTLC-based Atomic Swap is equivalent to an American Call Option in finance. On the other hand,thanks to such optionality, the HTLC-based Atomic Swap can be utilised to construct American Call Options without trusted third party. A paper<sup class="footnote-reference" id="fr-3-1"><a href="#fn-3">3</a></sup> proposes a secure Atomic-Swap-based American Call Option protocol on smart contracts. This protocol not only eliminates the arbitrage opportunity but also prevents any party from locking the other party's money maliciously. This EIP aims at providing the standard of implementing this protocol in existing token standards.</p> <h2 id="specification">Specification</h2> <p>The Atomic Swap-based American Call Option smart contract should follow the syntax and semantics of Ethereum smart contracts.</p> <h3 id="definitions">Definitions</h3> <ul> <li><code>initiator</code>: the party who publishes the advertisement of the swap.</li> <li><code>participant</code>: the party who agrees on the advertisement and participates in the swap with <code>initiator</code>.</li> <li><code>asset</code>: the amount of token(s) to be exchanged.</li> <li><code>premium</code>: the amount of token(s) that <code>initiator</code> pays to <code>participant</code> as the premium.</li> <li><code>redeem</code>: the action to claim the token from the other party.</li> <li><code>refund</code>: the action to claim the token from the party herself/himself, because of timelock expiration.</li> <li><code>secrect</code>: a random string chosen by <code>initiator</code> as the preimage of a hash.</li> <li><code>secrectHash</code>: a string equals to the hash of <code>secrect</code>, used for constructing HTLCs.</li> <li><code>timelock</code>: a timestamp representing the timelimit, before when the asset can be redeemed, and otherwise can only be refunded.</li> </ul> <h3 id="storage-variables">Storage Variables</h3> <h4 id="swap">swap</h4> <p>This mapping stores the metadata of the swap contracts, including the parties and tokens involved. Each contract uses different <code>secretHash</code>, and is distinguished by <code>secretHash</code>.</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">bytes32</span><span class="z-keyword"> =&gt;</span><span> Swap</span><span>)</span><span class="z-storage z-type"> public</span><span> swap</span><span>;</span></span></code></pre><h4 id="initiatorasset">initiatorAsset</h4> <p>This mapping stores the detail of the asset initiators want to sell, including the amount, the timelock and the state. It is associated with the swap contract with the same <code>secretHash</code>.</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">bytes32</span><span class="z-keyword"> =&gt;</span><span> InitiatorAsset</span><span>)</span><span class="z-storage z-type"> public</span><span> initiatorAsset</span><span>;</span></span></code></pre><h4 id="participantasset">participantAsset</h4> <p>This mapping stores the details of the asset participants want to sell, including the amount, the timelock and the state. It is associated with the swap contract with the same <code>secretHash</code>.</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">bytes32</span><span class="z-keyword"> =&gt;</span><span> ParticipantAsset</span><span>)</span><span class="z-storage z-type"> public</span><span> participantAsset</span><span>;</span></span></code></pre><h4 id="premiumasset">premiumAsset</h4> <p>This mapping stores the details of the premium initiators attach in the swap contract, including the amount, the timelock and the state. It is associated with the swap contract with the same <code>secretHash</code>.</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">bytes32</span><span class="z-keyword"> =&gt;</span><span> Premium</span><span>)</span><span class="z-storage z-type"> public</span><span> premium</span><span>;</span></span></code></pre><h3 id="methods">Methods</h3> <h4 id="setup">setup</h4> <p>This function sets up the swap contract, including the both parties involved, the tokens to exchanged, and so on.</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"> setup</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> payable</span><span class="z-variable"> initiator</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> tokenA</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> tokenB</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> initiatorAssetAmount</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> payable</span><span class="z-variable"> participant</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> participantAssetAmount</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> premiumAmount</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> payable</span></span></code></pre><h4 id="initiate">initiate</h4> <p>The initiator invokes this function to fill and lock the token she/he wants to sell and join the 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"> initiate</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> assetRefundTime</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> payable</span></span></code></pre><h4 id="fillpremium">fillPremium</h4> <p>The initiator invokes this function to fill and lock the premium.</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"> fillPremium</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> premiumRefundTime</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> payable</span></span></code></pre><h4 id="participate">participate</h4> <p>The participant invokes this function to fill and lock the token she/he wants to sell and join the 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"> participate</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> assetRefundTime</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> payable</span></span></code></pre><h4 id="redeemasset">redeemAsset</h4> <p>One of the parties invokes this function to get the token from the other party, by providing the preimage of the hash lock <code>secret</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"> redeemAsset</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> secret</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> secretHash</span><span>)</span><span class="z-storage z-type"> public</span></span></code></pre><h4 id="refundasset">refundAsset</h4> <p>One of the parties invokes this function to get the token back after the timelock expires.</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"> refundAsset</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>)</span><span class="z-storage z-type"> public</span></span></code></pre><h4 id="redeempremium">redeemPremium</h4> <p>The participant invokes this function to get the premium. This can be invoked only if the participant has already invoked <code>participate</code> and the participant's token is redeemed or refunded.</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"> redeemPremium</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>)</span><span class="z-storage z-type"> public</span></span></code></pre><h4 id="refundpremium">refundPremium</h4> <p>The initiator invokes this function to get the premium back after the timelock expires.</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"> refundPremium</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>)</span><span class="z-storage z-type"> public</span></span></code></pre><h3 id="events">Events</h3> <h4 id="setup-1">SetUp</h4> <p>This event indicates that one party has set up the contract using the function <code>setup()</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"> SetUp</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>, </span><span class="z-support">address</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">address</span><span class="z-variable"> participant</span><span>, </span><span class="z-support">address</span><span class="z-variable"> tokenA</span><span>, </span><span class="z-support">address</span><span class="z-variable"> tokenB</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> initiatorAssetAmount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> participantAssetAmount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> premiumAmount</span><span>)</span><span>;</span></span></code></pre><h4 id="initiated">Initiated</h4> <p>This event indicates that <code>initiator</code> has filled and locked the token to be exchanged using the function <code>initiate()</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"> Initiated</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> initiateTimestamp</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>, </span><span class="z-support">address</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">address</span><span class="z-variable"> participant</span><span>, </span><span class="z-support">address</span><span class="z-variable"> initiatorAssetToken</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> initiatorAssetAmount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> initiatorAssetRefundTimestamp</span><span>)</span><span>;</span></span></code></pre><h4 id="participated">Participated</h4> <p>This event indicates that <code>participant</code> has filled and locked the token to be exchanged using the function <code>participate()</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"> Participated</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> participateTimestamp</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>, </span><span class="z-support">address</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">address</span><span class="z-variable"> participant</span><span>, </span><span class="z-support">address</span><span class="z-variable"> participantAssetToken</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> participantAssetAmount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> participantAssetRefundTimestamp</span><span>)</span><span>;</span></span></code></pre><h4 id="premiumfilled">PremiumFilled</h4> <p>This event indicates that <code>initiator</code> has filled and locked <code>premium</code> using the function <code>fillPremium()</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"> PremiumFilled</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> fillPremiumTimestamp</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>, </span><span class="z-support">address</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">address</span><span class="z-variable"> participant</span><span>, </span><span class="z-support">address</span><span class="z-variable"> premiumToken</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> premiumAmount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> premiumRefundTimestamp</span><span>)</span><span>;</span></span></code></pre><h4 id="initiatorassetredeemed-participantassetredeemed">InitiatorAssetRedeemed/ParticipantAssetRedeemed</h4> <p>These two events indicate that <code>asset</code> has been redeemed by the other party before the timelock by providing <code>secret</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"> InitiatorAssetRedeemed</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> redeemTimestamp</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> secret</span><span>, </span><span class="z-support">address</span><span class="z-variable"> redeemer</span><span>, </span><span class="z-support">address</span><span class="z-variable"> assetToken</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span><span>;</span></span></code></pre><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"> ParticipantAssetRedeemed</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> redeemTimestamp</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> secret</span><span>, </span><span class="z-support">address</span><span class="z-variable"> redeemer</span><span>, </span><span class="z-support">address</span><span class="z-variable"> assetToken</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span><span>;</span></span></code></pre><h4 id="initiatorassetrefunded-participantassetrefunded">InitiatorAssetRefunded/ParticipantAssetRefunded</h4> <p>These two events indicate that <code>asset</code> has been refunded by the original owner after the timelock expires.</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"> InitiatorAssetRefunded</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> refundTimestamp</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>, </span><span class="z-support">address</span><span class="z-variable"> refunder</span><span>, </span><span class="z-support">address</span><span class="z-variable"> assetToken</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span><span>;</span></span></code></pre><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"> ParticipantAssetRefunded</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> refundTimestamp</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>, </span><span class="z-support">address</span><span class="z-variable"> refunder</span><span>, </span><span class="z-support">address</span><span class="z-variable"> assetToken</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span><span>;</span></span></code></pre><h4 id="premiumredeemed">PremiumRedeemed</h4> <p>This event indicates that <code>premium</code> has been redeemed by <code>participant</code>. This implies that <code>asset</code> is either redeemed by <code>initiator</code> if it can provide the preimage of <code>secrectHash</code> before <code>asset</code> timelock expires; or refunded by <code>participant</code> if <code>asset</code> timelock expires.</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"> PremiumRedeemed</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> redeemTimestamp</span><span>,</span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>,</span><span class="z-support">address</span><span class="z-variable"> redeemer</span><span>,</span><span class="z-support">address</span><span class="z-variable"> token</span><span>,</span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span><span>;</span></span></code></pre><h4 id="premiumrefunded">PremiumRefunded</h4> <p>This event indicates that <code>premium</code> has been refunded back to <code>initiator</code>, because of <code>participant</code> doesn't participate at all, by the time of <code>premium</code> timelock expires.</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"> PremiumRefunded</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> refundTimestamp</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> secretHash</span><span>, </span><span class="z-support">address</span><span class="z-variable"> refunder</span><span>, </span><span class="z-support">address</span><span class="z-variable"> token</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <ul> <li>To achieve the atomicity, HTLC is used.</li> <li>The participant should decide whether to participate after the initiator locks the token and sets up the timelock.</li> <li>The initiator should decide whether to proceed the swap (redeem the tokens from the participant and reveal the preimage of the hash lock), after the participant locks the tokens and sets up the time locks.</li> <li>Premium is redeemable for the participant only if the participant participates in the swap and redeems the initiator's token before premium's timelock expires.</li> <li>Premium is refundable for the initiator only if the initiator initiates but the participant does not participate in the swap at all.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>The <code>initiateTimestamp</code> should cover the whole swap process.</li> <li>The participant should never participate before the premium has been deposited.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backward compatible. Functionalities of existing standards will not be affected by this proposal, as it only provides additional features to them.</p> <h2 id="implementation">Implementation</h2> <p>Please visit <a href="https://wg-eips.ritovision.com/2266/./assets/Example.sol">here</a> to find our example 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> <h2 id="references">References</h2> <section class="footnotes"> <ol class="footnotes-list"> <li id="fn-1"> <p><a rel="external" href="https://en.bitcoin.it/wiki/Hash_Time_Locked_Contracts">Hash Time Locked Contracts</a> <a href="#fr-1-1">↩</a></p> </li> <li id="fn-2"> <p><a rel="external" href="https://lists.linuxfoundation.org/pipermail/lightning-dev/2019-January/001798.html">An Argument For Single-Asset Lightning Network</a> <a href="#fr-2-1">↩</a> <a href="#fr-2-2">↩2</a></p> </li> <li id="fn-3"> <p><a rel="external" href="https://eprint.iacr.org/2019/896">On the optionality and fairness of Atomic Swaps</a> <a href="#fr-3-1">↩</a></p> </li> </ol> </section> 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-18T00:00:00+00:00 2026-02-11T14:49:27+00:00 Wei Tanghttps://github.com/sorpaas https://wg-eips.ritovision.com/2200/ <h2 id="simple-summary">Simple Summary</h2> <p>This is an EIP that implements net gas metering. It's a combined version of <a href="https://wg-eips.ritovision.com/1283/">EIP-1283</a> and <a href="https://wg-eips.ritovision.com/1706/">EIP-1706</a>, with a structured definition so as to make it interoperable with other gas changes such as <a href="https://wg-eips.ritovision.com/1884/">EIP-1884</a>.</p> <h2 id="abstract">Abstract</h2> <p>This EIP provides a structured definition of net gas metering changes for <code>SSTORE</code> opcode, enabling new usages for contract storage, and reducing excessive gas costs where it doesn’t match how most implementation works.</p> <p>This is a combination of <a href="https://wg-eips.ritovision.com/1283/">EIP-1283</a> and <a href="https://wg-eips.ritovision.com/1706/">EIP-1706</a>.</p> <h2 id="motivation">Motivation</h2> <p>This EIP proposes a way for gas metering on <code>SSTORE</code>, using information that is more universally available to most implementations, and require as little change in implementation structures as possible.</p> <ul> <li>Storage slot’s original value.</li> <li>Storage slot’s current value.</li> <li>Refund counter.</li> </ul> <p>Usages that benefits from this EIP’s gas reduction scheme includes:</p> <ul> <li>Subsequent storage write operations within the same call frame. This includes reentry locks, same-contract multi-send, etc.</li> <li>Exchange storage information between sub call frame and parent call frame, where this information does not need to be persistent outside of a transaction. This includes sub-frame error codes and message passing, etc.</li> </ul> <p>The original definition of EIP-1283 created a danger of a new kind of reentrancy attacks on existing contracts as Solidity by default grants a "stipend" of 2300 gas to simple transfer calls. This danger is easily mitigated if <code>SSTORE</code> is not allowed in low gasleft state, without breaking the backward compatibility and the original intention of EIP-1283.</p> <p>This EIP also replaces the original EIP-1283 value definitions of gas by parameters, so that it's more structured, and easier to define changes in the future.</p> <h2 id="specification">Specification</h2> <p>Define variables <code>SLOAD_GAS</code>, <code>SSTORE_SET_GAS</code>, <code>SSTORE_RESET_GAS</code> and <code>SSTORE_CLEARS_SCHEDULE</code>. The old and new values for those variables are:</p> <ul> <li><code>SLOAD_GAS</code>: changed from <code>200</code> to <code>800</code>.</li> <li><code>SSTORE_SET_GAS</code>: <code>20000</code>, not changed.</li> <li><code>SSTORE_RESET_GAS</code>: <code>5000</code>, not changed.</li> <li><code>SSTORE_CLEARS_SCHEDULE</code>: <code>15000</code>, not changed.</li> </ul> <p>Change the definition of EIP-1283 using those variables. The new specification, combining EIP-1283 and EIP-1706, will look like below. The terms <em>original value</em>, <em>current value</em> and <em>new value</em> are defined in EIP-1283.</p> <p>Replace <code>SSTORE</code> opcode gas cost calculation (including refunds) with the following logic:</p> <ul> <li>If <em>gasleft</em> is less than or equal to gas stipend, fail the current call frame with 'out of gas' exception.</li> <li>If <em>current value</em> equals <em>new value</em> (this is a no-op), <code>SLOAD_GAS</code> is deducted.</li> <li>If <em>current value</em> does not equal <em>new value</em> <ul> <li>If <em>original value</em> equals <em>current value</em> (this storage slot has not been changed by the current execution context) <ul> <li>If <em>original value</em> is 0, <code>SSTORE_SET_GAS</code> is deducted.</li> <li>Otherwise, <code>SSTORE_RESET_GAS</code> gas is deducted. If <em>new value</em> is 0, add <code>SSTORE_CLEARS_SCHEDULE</code> gas to refund counter.</li> </ul> </li> <li>If <em>original value</em> does not equal <em>current value</em> (this storage slot is dirty), <code>SLOAD_GAS</code> gas is deducted. Apply both of the following clauses. <ul> <li>If <em>original value</em> is not 0 <ul> <li>If <em>current value</em> is 0 (also means that <em>new value</em> is not 0), remove <code>SSTORE_CLEARS_SCHEDULE</code> gas from refund counter.</li> <li>If <em>new value</em> is 0 (also means that <em>current value</em> is not 0), add <code>SSTORE_CLEARS_SCHEDULE</code> gas to refund counter.</li> </ul> </li> <li>If <em>original value</em> equals <em>new value</em> (this storage slot is reset) <ul> <li>If <em>original value</em> is 0, add <code>SSTORE_SET_GAS - SLOAD_GAS</code> to refund counter.</li> <li>Otherwise, add <code>SSTORE_RESET_GAS - SLOAD_GAS</code> gas to refund counter.</li> </ul> </li> </ul> </li> </ul> </li> </ul> <p>An implementation should also note that with the above definition, if the implementation uses call-frame refund counter, the counter can go negative. If the implementation uses transaction-wise refund counter, the counter always stays positive.</p> <h2 id="rationale">Rationale</h2> <p>This EIP mostly achieves what a transient storage tries to do (<a href="https://wg-eips.ritovision.com/1087/">EIP-1087</a> and <a href="https://wg-eips.ritovision.com/1153/">EIP-1153</a>), but without the complexity of introducing the concept of "dirty maps", or an extra storage struct.</p> <ul> <li>We don't suffer from the optimization limitation of EIP-1087. EIP-1087 requires keeping a dirty map for storage changes, and implicitly makes the assumption that a transaction's storage changes are committed to the storage trie at the end of a transaction. This works well for some implementations, but not for others. After <a href="https://wg-eips.ritovision.com/658/">EIP-658</a>, an efficient storage cache implementation would probably use an in-memory trie (without RLP encoding/decoding) or other immutable data structures to keep track of storage changes, and only commit changes at the end of a block. For them, it is possible to know a storage's original value and current value, but it is not possible to iterate over all storage changes without incurring additional memory or processing costs.</li> <li>It never costs more gas compared with the current scheme.</li> <li>It covers all usages for a transient storage. Clients that are easy to implement EIP-1087 will also be easy to implement this specification. Some other clients might require a little bit extra refactoring on this. Nonetheless, no extra memory or processing cost is needed on runtime.</li> </ul> <p>Regarding <code>SSTORE</code> gas cost and refunds, see Appendix for proofs of properties that this EIP satisfies.</p> <ul> <li>For <em>absolute gas used</em> (that is, actual <em>gas used</em> minus <em>refund</em>), this EIP is equivalent to EIP-1087 for all cases.</li> <li>For one particular case, where a storage slot is changed, reset to its original value, and then changed again, EIP-1283 would move more gases to refund counter compared with EIP-1087.</li> </ul> <p>Examine examples provided in EIP-1087's Motivation (with <code>SLOAD_GAS</code> being <code>200</code>):</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.</li> <li>A contract with empty storage that increments slot 0 5 times will be charged <code>20000 + 5 * 200 = 21000</code> 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, it will cost <code>5000 * 3 + 200 - 4800 = 10400</code> gas.</li> </ul> <p>In order to keep in place the implicit reentrancy protection of existing contracts, transactions should not be allowed to modify state if the remaining gas is lower than the gas stipend given to "transfer"/"send" in Solidity. These are other proposed remediations and objections to implementing them:</p> <ul> <li>Drop EIP-1283 and abstain from modifying <code>SSTORE</code> cost <ul> <li>EIP-1283 is an important update</li> <li>It was accepted and implemented on test networks and in clients.</li> </ul> </li> <li>Add a new call context that permits LOG opcodes but not changes to state. <ul> <li>Adds another call type beyond existing regular/staticcall</li> </ul> </li> <li>Raise the cost of <code>SSTORE</code> to dirty slots to &gt;=2300 gas <ul> <li>Makes net gas metering much less useful.</li> </ul> </li> <li>Reduce the gas stipend <ul> <li>Makes the stipend almost useless.</li> </ul> </li> <li>Increase the cost of writes to dirty slots back to 5000 gas, but add 4800 gas to the refund counter <ul> <li>Still doesn’t make the invariant explicit.</li> <li>Requires callers to supply more gas, just to have it refunded</li> </ul> </li> <li>Add contract metadata specifying per-contract EVM version, and only apply <code>SSTORE</code> changes to contracts deployed with the new version.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a hard fork to implement. No gas cost increase is anticipated, and many contracts will see gas reduction.</p> <p>Performing <code>SSTORE</code> has never been possible with less than 5000 gas, so it does not introduce incompatibility to the Ethereum Mainnet. Gas estimation should account for this requirement.</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>1st</th><th>2nd</th><th>3rd</th></tr></thead><tbody> <tr><td><code>0x60006000556000600055</code></td><td>1612</td><td>0</td><td>0</td><td>0</td><td>0</td><td></td></tr> <tr><td><code>0x60006000556001600055</code></td><td>20812</td><td>0</td><td>0</td><td>0</td><td>1</td><td></td></tr> <tr><td><code>0x60016000556000600055</code></td><td>20812</td><td>19200</td><td>0</td><td>1</td><td>0</td><td></td></tr> <tr><td><code>0x60016000556002600055</code></td><td>20812</td><td>0</td><td>0</td><td>1</td><td>2</td><td></td></tr> <tr><td><code>0x60016000556001600055</code></td><td>20812</td><td>0</td><td>0</td><td>1</td><td>1</td><td></td></tr> <tr><td><code>0x60006000556000600055</code></td><td>5812</td><td>15000</td><td>1</td><td>0</td><td>0</td><td></td></tr> <tr><td><code>0x60006000556001600055</code></td><td>5812</td><td>4200</td><td>1</td><td>0</td><td>1</td><td></td></tr> <tr><td><code>0x60006000556002600055</code></td><td>5812</td><td>0</td><td>1</td><td>0</td><td>2</td><td></td></tr> <tr><td><code>0x60026000556000600055</code></td><td>5812</td><td>15000</td><td>1</td><td>2</td><td>0</td><td></td></tr> <tr><td><code>0x60026000556003600055</code></td><td>5812</td><td>0</td><td>1</td><td>2</td><td>3</td><td></td></tr> <tr><td><code>0x60026000556001600055</code></td><td>5812</td><td>4200</td><td>1</td><td>2</td><td>1</td><td></td></tr> <tr><td><code>0x60026000556002600055</code></td><td>5812</td><td>0</td><td>1</td><td>2</td><td>2</td><td></td></tr> <tr><td><code>0x60016000556000600055</code></td><td>5812</td><td>15000</td><td>1</td><td>1</td><td>0</td><td></td></tr> <tr><td><code>0x60016000556002600055</code></td><td>5812</td><td>0</td><td>1</td><td>1</td><td>2</td><td></td></tr> <tr><td><code>0x60016000556001600055</code></td><td>1612</td><td>0</td><td>1</td><td>1</td><td>1</td><td></td></tr> <tr><td><code>0x600160005560006000556001600055</code></td><td>40818</td><td>19200</td><td>0</td><td>1</td><td>0</td><td>1</td></tr> <tr><td><code>0x600060005560016000556000600055</code></td><td>10818</td><td>19200</td><td>1</td><td>0</td><td>1</td><td>0</td></tr> </tbody></table> <h2 id="implementation">Implementation</h2> <p>To be added.</p> <h2 id="appendix-proof">Appendix: Proof</h2> <p>Because the <em>storage slot's original value</em> is defined as the value when a reversion happens on the <em>current transaction</em>, it's easy to see that call frames won't interfere <code>SSTORE</code> gas calculation. So although the below proof is discussed without call frames, it applies to all situations with call frames. We will discuss the case separately for <em>original value</em> being zero and not zero, and use <em>induction</em> to prove some properties of <code>SSTORE</code> gas cost.</p> <p><em>Final value</em> is the value of a particular storage slot at the end of a transaction. <em>Absolute gas used</em> is the absolute value of <em>gas used</em> minus <em>refund</em>. We use <code>N</code> to represent the total number of <code>SSTORE</code> operations on a storage slot. For states discussed below, refer to <em>State Transition</em> in <em>Explanation</em> section.</p> <p>Below we do the proof under the assumption that all parameters are unchanged, meaning <code>SLOAD_GAS</code> is <code>200</code>. However, note that the proof still applies no matter how <code>SLOAD_GAS</code> is changed.</p> <h3 id="original-value-being-zero">Original Value Being Zero</h3> <p>When <em>original value</em> is 0, we want to prove that:</p> <ul> <li><strong>Case I</strong>: If the <em>final value</em> ends up still being 0, we want to charge <code>200 * N</code> gases, because no disk write is needed.</li> <li><strong>Case II</strong>: If the <em>final value</em> ends up being a non-zero value, we want to charge <code>20000 + 200 * (N-1)</code> gas, because it requires writing this slot to disk.</li> </ul> <h4 id="base-case">Base Case</h4> <p>We always start at state A. The first <code>SSTORE</code> can:</p> <ul> <li>Go to state A: 200 gas is deducted. We satisfy <em>Case I</em> because <code>200 * N == 200 * 1</code>.</li> <li>Go to state B: 20000 gas is deducted. We satisfy <em>Case II</em> because <code>20000 + 200 * (N-1) == 20000 + 200 * 0</code>.</li> </ul> <h4 id="inductive-step">Inductive Step</h4> <ul> <li>From A to A. The previous gas cost is <code>200 * (N-1)</code>. The current gas cost is <code>200 + 200 * (N-1)</code>. It satisfy <em>Case I</em>.</li> <li>From A to B. The previous gas cost is <code>200 * (N-1)</code>. The current gas cost is <code>20000 + 200 * (N-1)</code>. It satisfy <em>Case II</em>.</li> <li>From B to B. The previous gas cost is <code>20000 + 200 * (N-2)</code>. The current gas cost is <code>200 + 20000 + 200 * (N-2)</code>. It satisfy <em>Case II</em>.</li> <li>From B to A. The previous gas cost is <code>20000 + 200 * (N-2)</code>. The current gas cost is <code>200 - 19800 + 20000 + 200 * (N-2)</code>. It satisfy <em>Case I</em>.</li> </ul> <h3 id="original-value-not-being-zero">Original Value Not Being Zero</h3> <p>When <em>original value</em> is not 0, we want to prove that:</p> <ul> <li><strong>Case I</strong>: If the <em>final value</em> ends up unchanged, we want to charge <code>200 * N</code> gases, because no disk write is needed.</li> <li><strong>Case II</strong>: If the <em>final value</em> ends up being zero, we want to charge <code>5000 - 15000 + 200 * (N-1)</code> gas. Note that <code>15000</code> is the refund in actual definition.</li> <li><strong>Case III</strong>: If the <em>final value</em> ends up being a changed non-zero value, we want to charge <code>5000 + 200 * (N-1)</code> gas.</li> </ul> <h4 id="base-case-1">Base Case</h4> <p>We always start at state X. The first <code>SSTORE</code> can:</p> <ul> <li>Go to state X: 200 gas is deducted. We satisfy <em>Case I</em> because <code>200 * N == 200 * 1</code>.</li> <li>Go to state Y: 5000 gas is deducted. We satisfy <em>Case III</em> because <code>5000 + 200 * (N-1) == 5000 + 200 * 0</code>.</li> <li>Go to state Z: The absolute gas used is <code>5000 - 15000</code> where 15000 is the refund. We satisfy <em>Case II</em> because <code>5000 - 15000 + 200 * (N-1) == 5000 - 15000 + 200 * 0</code>.</li> </ul> <h4 id="inductive-step-1">Inductive Step</h4> <ul> <li>From X to X. The previous gas cost is <code>200 * (N-1)</code>. The current gas cost is <code>200 + 200 * (N-1)</code>. It satisfy <em>Case I</em>.</li> <li>From X to Y. The previous gas cost is <code>200 * (N-1)</code>. The current gas cost is <code>5000 + 200 * (N-1)</code>. It satisfy <em>Case III</em>.</li> <li>From X to Z. The previous gas cost is <code>200 * (N-1)</code>. The current absolute gas cost is <code>5000 - 15000 + 200 * (N-1)</code>. It satisfy <em>Case II</em>.</li> <li>From Y to X. The previous gas cost is <code>5000 + 200 * (N-2)</code>. The absolute current gas cost is <code>200 - 4800 + 5000 + 200 * (N-2)</code>. It satisfy <em>Case I</em>.</li> <li>From Y to Y. The previous gas cost is <code>5000 + 200 * (N-2)</code>. The current gas cost is <code>200 + 5000 + 200 * (N-2)</code>. It satisfy <em>Case III</em>.</li> <li>From Y to Z. The previous gas cost is <code>5000 + 200 * (N-2)</code>. The current absolute gas cost is <code>200 - 15000 + 5000 + 200 * (N-2)</code>. It satisfy <em>Case II</em>.</li> <li>From Z to X. The previous gas cost is <code>5000 - 15000 + 200 * (N-2)</code>. The current absolute gas cost is <code>200 + 10200 + 5000 - 15000 + 200 * (N-2)</code>. It satisfy <em>Case I</em>.</li> <li>From Z to Y. The previous gas cost is <code>5000 - 15000 + 200 * (N-2)</code>. The current absolute gas cost is <code>200 + 15000 + 5000 - 15000 + 200 * (N-2)</code>. It satisfy <em>Case III</em>.</li> <li>From Z to Z. The previous gas cost is <code>5000 - 15000 + 200 * (N-2)</code>. The current absolute gas cost is <code>200 + 5000 - 15000 + 200 * (N-2)</code>. It satisfy <em>Case II</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> 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-07-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Adrian Suttonhttps://github.com/ajsutton https://wg-eips.ritovision.com/2159/ <h2 id="simple-summary">Simple Summary</h2> <p>Standardized names of common metrics for Ethereum clients to use with Prometheus, a widely used monitoring and alerting solution.</p> <h2 id="abstract">Abstract</h2> <p>Many Ethereum clients expose a range of metrics in a format compatible with Prometheus to allow operators to monitor the client's behaviour and performance and raise alerts if the chain isn't progressing or there are other indications of errors. While the majority of these metrics are highly client-specific, reporting on internal implementation details of the client, some are applicable to all clients. By standardizing the naming and format of these common metrics, operators are able to monitor the operation of multiple clients in a single dashboard or alerting configuration.</p> <h2 id="motivation">Motivation</h2> <p>Using common names and meanings for metrics which apply to all clients allows node operators to monitor clusters of nodes using heterogeneous clients using a single dashboard and alerting configuration. Currently there are no agreed names or meanings, leaving client developers to invent their own making it difficult to monitor a heterogeneous cluster.</p> <h2 id="specification">Specification</h2> <p>The table below defines metrics which may be captured by Ethereum clients which expose metrics to Prometheus. Clients may expose additional metrics however these should not use the <code>ethereum_</code> prefix.</p> <table><thead><tr><th>Name</th><th>Metric type</th><th>Definition</th><th>JSON-RPC Equivalent</th></tr></thead><tbody> <tr><td>ethereum_blockchain_height</td><td>Gauge</td><td>The current height of the canonical chain</td><td><code>eth_blockNumber</code></td></tr> <tr><td>ethereum_best_known_block_number</td><td>Gauge</td><td>The estimated highest block available</td><td><code>highestBlock</code> of <code>eth_syncing</code> or <code>eth_blockNumber</code> if not syncing</td></tr> <tr><td>ethereum_peer_count</td><td>Gauge</td><td>The current number of peers connected</td><td><code>net_peerCount</code></td></tr> <tr><td>ethereum_peer_limit</td><td>Gauge</td><td>The maximum number of peers this node allows to connect</td><td>No equivalent</td></tr> </tbody></table> <p>Note that <code>ethereum_best_known_block_number</code> always has a value. When the <code>eth_syncing</code> JSON-RPC method would return <code>false</code>, the current chain height is used.</p> <h2 id="rationale">Rationale</h2> <p>The defined metrics are independent of Ethereum client implementation but provide sufficient information to create an overview dashboard to support monitoring a group of Ethereum nodes.</p> <p>There is a similar, though more prescriptive, specification for beacon chain client metrics. The specific details of how to expose the metrics has been omitted as there is variance in existing implementations and standardising this does not provide any significant benefit.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is <em>not</em> a consensus affecting change.</p> <p>Clients may already be publishing these metrics using different names and changing to the new form may break existing alerts or dashboards. Clients that want to avoid this incompatibility can expose the metrics under both the old and new names.</p> <p>Clients may also be publishing metrics with a different meaning using these names. Backwards compatibility cannot be preserved in this case.</p> <h2 id="implementation">Implementation</h2> <p>Pantheon switched to using these standard metric names in its 1.2 release: https://github.com/PegaSysEng/pantheon/pull/1634.</p> <h2 id="references">References</h2> <ol> <li>Prometheus. https://prometheus.io</li> <li>Beacon chain metrics specification. https://github.com/ethereum/eth2.0-metrics/blob/master/metrics.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-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-06-23T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv https://wg-eips.ritovision.com/2135/

An interface extending ERC-721 and ERC-1155 for consumability, supporting use case such as an event ticket.

<h2 id="abstract">Abstract</h2> <p>This EIP defines an interface to mark a digital asset as "consumable" and to react to its "consumption."</p> <h2 id="motivation">Motivation</h2> <p>Digital assets sometimes need to be consumed. One of the most common examples is a concert ticket. It is "consumed" when the ticket-holder enters the concert hall.</p> <p>Having a standard interface enables interoperability for services, clients, UI, and inter-contract functionalities on top of this use-case.</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> <ol> <li>Any compliant contract <strong>MUST</strong> implement the following interface:</li> </ol> <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-comment"> The ERC-165 identifier of this interface is 0xdd691946</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC2135</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"> The consume function consumes a token every time it succeeds.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _consumer</span><span class="z-comment"> the address of consumer of this token. It doesn&#39;t have</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> to be the EOA or contract Account that initiates the TX.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _assetId</span><span class="z-comment"> the NFT asset being consumed</span></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"> extra data passed in for consume for extra message</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> or future extension.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> consume</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _consumer</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _assetId</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-storage z-type"> calldata</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">bool</span><span class="z-variable z-parameter z-function"> _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"> @notice</span><span class="z-comment"> The interface to check whether an asset is consumable.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _consumer</span><span class="z-comment"> the address of consumer of this token. It doesn&#39;t have</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> to be the EOA or contract Account that initiates the TX.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _assetId</span><span class="z-comment"> the NFT asset being consumed.</span></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"> the amount of the asset being consumed.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isConsumableBy</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _consumer</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _assetId</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 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"> _consumable</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 event emitted when there is a successful consumption.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> consumer</span><span class="z-comment"> the address of consumer of this token. It doesn&#39;t have</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> to be the EOA or contract Account that initiates the TX.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> assetId</span><span class="z-comment"> the NFT asset being consumed</span></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"> the amount of the asset being consumed.</span></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"> extra data passed in for consume for extra message</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> or future extension.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> OnConsumption</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"> consumer</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"> assetId</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"> 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> <ol start="2"> <li> <p>If the compliant contract is an <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> or <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> token, in addition to <code>OnConsumption</code>, it <strong>MUST</strong> also emit the <code>Transfer</code> / <code>TransferSingle</code> event (as applicable) as if a token has been transferred from the current holder to the zero address if the call to <code>consume</code> method succeeds.</p> </li> <li> <p><code>supportsInterface(0xdd691946)</code> <strong>MUST</strong> return <code>true</code> for any compliant contract, as per <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>.</p> </li> </ol> <h2 id="rationale">Rationale</h2> <ol> <li>The function <code>consume</code> performs the consume action. This EIP does not assume:</li> </ol> <ul> <li>who has the power to perform consumption</li> <li>under what condition consumption can occur</li> </ul> <p>It does, however, assume the asset can be identified in a <code>uint256</code> asset id as in the parameter. A design convention and compatibility consideration is put in place to follow the ERC-721 pattern.</p> <ol start="2"> <li> <p>The event notifies subscribers whoever are interested to learn an asset is being consumed.</p> </li> <li> <p>To keep it simple, this standard <em>intentionally</em> contains no functions or events related to the creation of a consumable asset. This is because the creation of a consumable asset will need to make assumptions about the nature of an actual use-case. If there are common use-cases for creation, another follow up standard can be created.</p> </li> <li> <p>Metadata associated to the consumables is not included the standard. If necessary, related metadata can be created with a separate metadata extension interface like <code>ERC721Metadata</code> from <a href="https://wg-eips.ritovision.com/721/">ERC-721</a></p> </li> <li> <p>We choose to include an <code>address consumer</code> for <code>consume</code> function and <code>isConsumableBy</code> so that an NFT MAY be consumed for someone other than the transaction initiator.</p> </li> <li> <p>We choose to include an extra <code>_data</code> field for future extension, such as adding crypto endorsements.</p> </li> <li> <p>We explicitly stay opinion-less about whether ERC-721 or ERC-1155 shall be required because while we design this EIP with ERC-721 and ERC-1155 in mind mostly, we don't want to rule out the potential future case someone use a different token standard or use it in different use cases.</p> </li> <li> <p>The boolean view function of <code>isConsumableBy</code> can be used to check whether an asset is consumable by the <code>_consumer</code>.</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This interface is designed to be compatible with ERC-721 and NFT of ERC-1155. It can be tweaked to used for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> and Fungible Token of ERC-1155.</p> <h2 id="test-cases">Test Cases</h2> <pre class="giallo z-code"><code data-lang="typescript"><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">Consumption</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 consume when minted</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"> const</span><span class="z-variable z-other z-constant"> fakeTokenId</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1234</span><span class="z-punctuation z-definition z-string">&quot;</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"> contract</span><span>,</span><span class="z-variable z-other z-constant"> addr1</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> loadFixture</span><span>(</span><span class="z-variable z-other">deployFixture</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">safeMint</span><span>(</span><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"> fakeTokenId</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"> contract</span><span>.</span><span class="z-entity z-name">balanceOf</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><span class="z-variable z-other">to</span><span>.</span><span class="z-entity z-name">equal</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-keyword">await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">ownerOf</span><span>(</span><span class="z-variable z-other">fakeTokenId</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 class="z-entity z-name"> expect</span><span>(</span><span class="z-keyword">await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">isConsumableBy</span><span>(</span><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"> fakeTokenId</span><span>,</span><span class="z-constant"> 1</span><span>)</span><span>)</span><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-variable z-other">true</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> tx</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">consume</span><span>(</span><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"> fakeTokenId</span><span>,</span><span class="z-constant"> 1</span><span>,</span><span> [</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"> receipt</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> tx</span><span>.</span><span class="z-entity z-name">wait</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"> events</span><span class="z-keyword"> =</span><span class="z-variable z-other"> receipt</span><span>.</span><span class="z-variable z-other">events</span><span>.</span><span class="z-entity z-name">filter</span><span>(</span><span>(</span><span class="z-variable">x</span><span class="z-keyword">:</span><span class="z-support"> any</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span> {</span><span class="z-keyword"> return</span><span class="z-variable z-other"> x</span><span>.</span><span class="z-variable z-other">event</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">OnConsumption</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-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">events</span><span>.</span><span class="z-support z-variable">length</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-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">events</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">consumer</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 class="z-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">events</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">assetId</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">fakeTokenId</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">events</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">amount</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-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-keyword">await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">balanceOf</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><span class="z-variable z-other">to</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-constant">0</span><span>)</span><span>;</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">contract</span><span>.</span><span class="z-entity z-name">ownerOf</span><span>(</span><span class="z-variable z-other">fakeTokenId</span><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">&#39;</span><span class="z-string">ERC721: invalid token ID</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>;</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">contract</span><span>.</span><span class="z-entity z-name">isConsumableBy</span><span>(</span><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"> fakeTokenId</span><span>,</span><span class="z-constant"> 1</span><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">&#39;</span><span class="z-string">ERC721: invalid token ID</span><span class="z-punctuation z-definition z-string">&#39;</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 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">EIP-165 Identifier</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 match</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"> const</span><span> {</span><span class="z-variable z-other z-constant"> contract</span><span> }</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> loadFixture</span><span>(</span><span class="z-variable z-other">deployFixture</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"> contract</span><span>.</span><span class="z-entity z-name">get165</span><span>(</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-punctuation z-definition z-string">&quot;</span><span class="z-string">0xdd691946</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"> expect</span><span>(</span><span class="z-keyword">await</span><span class="z-variable z-other"> contract</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0xdd691946</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>)</span><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-variable z-other">true</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> <p>A deployment of version 0x1002 has been deployed onto <code>goerli</code> testnet at address <code>0x3682bcD67b8A5c0257Ab163a226fBe07BF46379B</code>.</p> <p>Find the reference contract verified source code on Etherscan's <code>goerli</code> site for the address above.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Compliant contracts should pay attention to the balance change when a token is consumed. When the contract is being paused, or the user is being restricted from transferring a token, the consumeability should be consistent with the transferral restriction.</p> <p>Compliant contracts should also carefully define access control, particularly whether any EOA or contract account may or may not initiate a <code>consume</code> method in their own use case.</p> <p>Security audits and tests should be used to verify that the access control to the <code>consume</code> function behaves 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> 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-05-03T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alexey Akhunovhttps://github.com/AlexeyAkhunov Eli Ben Sassoneli@starkware.co Tom Brandtom@starkware.co Louis Guthmannlouis@starkware.co Avihu Levyavihu@starkware.co https://wg-eips.ritovision.com/2028/ <h2 id="simple-summary">Simple Summary</h2> <p>We propose to reduce the gas cost of Calldata (<code>GTXDATANONZERO</code>) from its current value of 68 gas per byte to 16 gas per byte, to be backed by mathematical modeling and empirical estimates. The mathematical model is the one used in the works of Sompolinsky and Zohar [1] and Pass, Seeman and Shelat [2], which relates network security to network delay. We shall (1) evaluate the theoretical impact of lower Calldata gas cost on network delay using this model, (2) validate the model empirically, and (3) base the proposed gas cost on our findings.</p> <h2 id="motivation">Motivation</h2> <p>There are a couple of main benefits to accepting this proposal and lowering gas cost of Calldata On-Chain Scalability: Generally speaking, higher bandwidth of Calldata improves scalability, as more data can fit within a single block.</p> <ul> <li>Layer two scalability: Layer two scaling solutions can improve scalability by moving storage and computation off-chain, but often introduce data transmission instead. <ul> <li>Proof systems such as STARKs and SNARKs use a single proof that attests to the computational integrity of a large computation, say, one that processes a large batch of transactions.</li> <li>Some solutions use fraud proofs which requires a transmission of merkle proofs.</li> <li>Moreover, one optional data availability solution to layer two is to place data on the main chain, via Calldata.</li> </ul> </li> <li>Stateless clients: The same model will be used to determine the price of the state access for the stateless client regime, which will be proposed in the State Rent (from version 4). There, it is expected that the gas cost of state accessing operation will increase roughly proportional to the extra bandwidth required to transmit the “block proofs” as well as extra processing required to verify those block proofs.</li> </ul> <h2 id="specification">Specification</h2> <p>The gas per non-zero byte is reduced from 68 to 16. Gas cost of zero bytes is unchanged.</p> <h2 id="rationale">Rationale</h2> <p>Roughly speaking, reducing the gas cost of Calldata leads to potentially larger blocks, which increases the network delay associated with data transmission over the network. This is only part of the full network delay, other factors are block processing time (and storage access, as part of it). Increasing network delay affects security by lowering the cost of attacking the network, because at any given point in time fewer nodes are updated on the latest state of the blockchain.</p> <p>Yonatan Sompolinsky and Aviv Zohar suggested in [1] an elegant model to relate network delay to network security, and this model is also used in the work of Rafael Pass, Lior Seeman and Abhi Shelat [2]. We briefly explain this model below, because we shall study it theoretically and validate it by empirical measurements to reach the suggested lower gas cost for Calldata.</p> <p>The model uses the following natural parameters:</p> <ul> <li><em>lambda</em> denotes the block creation rate [1/s]: We treat the process of finding a PoW solution as a poisson process with rate <em>lambda</em>.</li> <li><em>beta</em> - chain growth rate [1/s]: the rate at which new blocks are added to the heaviest chain.</li> <li><em>D</em> - block delay [s]: The time that elapses between the mining of a new block and its acceptance by all the miners (all miners switched to mining on top of that block).</li> </ul> <h3 id="beta-lower-bound"><em>Beta</em> Lower Bound</h3> <p>Notice that <em>lambda</em> =&gt; <em>beta</em>, because not all blocks that are found will enter the main chain (as is the case with uncles). In [1] it was shown that for a blockchain using the longest chain rule, one may bound <em>beta</em> from below by <em>lambda</em>/ (1+ D * <em>lambda</em>). This lower bound holds in the extremal case where the topology of the network is a clique in which the delay between each pair of nodes is D, the maximal possible delay. Recording both the lower and upper bounds on <em>beta</em> we get</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>_lambda_ &gt;= _beta_ &gt;= _lambda_ / (1 + D * _lambda_) (*)</span></span></code></pre> <p>Notice, as a sanity check, that when there is no delay (D=0) then <em>beta</em> equals <em>lambda</em>, as expected.</p> <h3 id="security-of-the-network">Security of the network</h3> <p>An attacker attempting to reorganize the main chain needs to generate blocks at a rate that is greater than <em>beta</em>. Fixing the difficulty level of the PoW puzzle, the total hash rate in the system is correlated to <em>lambda</em>. Thus, <em>beta</em> / <em>lambda</em> is defined as the <em>efficiency</em> of the system, as it measures the fraction of total hash power that is used to generate the main chain of the network.</p> <p>Rearranging (*) gives the following lower bound on efficiency in terms of delay:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>_beta_ / _lambda_ &gt;= 1 / (1 + D * _lambda_) (**)</span></span></code></pre><h3 id="the-delay-parameter-d">The <em>delay</em> parameter D</h3> <p>The network delay depends on the location of the mining node within the network and on the current network topology (which changes dynamically), and consequently is somewhat difficult to measure directly. Previously, Christian Decker and Roger Wattenhofer [3] showed that propagation time scales with blocksize, and Vitalik Buterin showed that uncle rate, which is tightly related to efficiency (**) measure, also scales with block size [4].</p> <p>However, the delay function can be decomposed into two parts D = <em>D_t</em> + <em>D_p</em>, where <em>D_t</em> is the delay caused by the transmission of the block and <em>D_p</em> is the delay caused by the processing of the block by the node. Our model and tests will examine the effect of Calldata on each of <em>D_t</em> and <em>D_p</em>, postulating that their effect is different. This may be particularly relevant for Layer 2 Scalability and for Stateless Clients (Rationales 2, 3 above) because most of the Calldata associated with these goals are Merkle authentication paths that have a large <em>D_t</em> component but relatively small <em>D_p</em> values.</p> <h2 id="test-cases">Test Cases</h2> <p>To suggest the gas cost of calldata we shall conduct two types of tests:</p> <ol> <li>Network tests, conducted on the Ethereum mainnet, used to estimate the effect on increasing block size on <em>D_p</em> and <em>D_t</em>, on the overall network delay D and the efficiency ratio (**), as well as delays between different mining pools. Those tests will include regression tests on existing data, and stress tests to introduce extreme scenarios.</li> <li>Local tests, conducted on a single node and measuring the processing time as a function of Calldata amount and general computation limits.</li> </ol> <h2 id="reference-implementation">Reference Implementation</h2> <p><a rel="external" href="https://github.com/liorgold2/parity-ethereum/pull/1">Parity</a> <a rel="external" href="https://github.com/liorgold2/go-ethereum/pull/1">Geth</a></p> <h2 id="references">References</h2> <p>[1] Yonatan Sompolinsky, Aviv Zohar: <a rel="external" href="https://eprint.iacr.org/2013/881.pdf">Secure High-Rate Transaction Processing in Bitcoin</a>. Financial Cryptography 2015: 507-527</p> <p>[2] Rafael Pass, Lior Seeman, Abhi Shelat: <a rel="external" href="https://eprint.iacr.org/2016/454.pdf">Analysis of the Blockchain Protocol in Asynchronous Networks</a>, ePrint report 2016/454</p> <p>[3] Christian Decker, Roger Wattenhofer: <a rel="external" href="https://www.gsd.inesc-id.pt/~ler/docencia/rcs1314/papers/P2P2013_041.pdf">Information propagation in the Bitcoin network</a>. P2P 2013: 1-10</p> <p>[4] Vitalik Buterin: <a rel="external" href="https://blog.ethereum.org/2016/10/31/uncle-rate-transaction-fee-analysis/">Uncle Rate and Transaction Fee Analysis</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-03T00:00:00+00:00 2026-02-11T14:49:27+00:00 Péter Szilágyipeterke@gmail.com Felix Langefjl@ethereum.org https://wg-eips.ritovision.com/2124/ <h2 id="simple-summary">Simple Summary</h2> <p>Currently nodes in the Ethereum network try to find each other by establishing random connections to remote machines "looking" like an Ethereum node (public networks, private networks, test networks, etc), hoping that they found a useful peer (same genesis, same forks). This wastes time and resources, especially for smaller networks.</p> <p>To avoid this overhead, Ethereum needs a mechanism that can precisely identify whether a node will be useful, as early as possible. Such a mechanism requires a way to summarize chain configurations, as well as a way to disseminate said summaries in the network.</p> <p>This proposal focuses only on the definition of said summary - a generally useful <em>fork identifier</em> - and it's validation rules, allowing it to be embedded into arbitrary network protocols (e.g. <a href="https://wg-eips.ritovision.com/778/">discovery ENRs</a> or <code>eth/6x</code> handshakes).</p> <h2 id="abstract">Abstract</h2> <p>There are many public and private Ethereum networks, but the discovery protocol doesn't differentiate between them. The only way to check if a peer is good or bad (same chain or not), is to establish a TCP/IP connection, wrap it with RLPx cryptography, then execute an <code>eth</code> handshake. This is an extreme cost to bear if it turns out that the remote peer is on a different network and it's not even precise enough to differentiate Ethereum and Ethereum Classic. This cost is magnified for small networks, where a lot more trial and errors are needed to find good nodes.</p> <p>Even if the peer <strong>is</strong> on the same chain, during non-controversial consensus upgrades, not everybody updates their nodes in time (developer nodes, leftovers, etc). These stale nodes put a meaningless burden on the peer-to-peer network, since they just latch on to good nodes, but don't accept upgraded blocks. This causes valuable peer slots and bandwidth to be lost until the stale nodes finally update. This is a serious issue for test networks, where leftovers can linger for months.</p> <p>This EIP proposes a new identity scheme to both precisely and concisely summarize the chain's current status (genesis and all applied forks). The conciseness is particularly important to make the identity useful across datagram protocols too. The EIP solves a number of issues:</p> <ul> <li>If two nodes are on different networks, they should never even consider connecting.</li> <li>If a hard fork passes, upgraded nodes should reject non-upgraded ones, but <strong>NOT</strong> before.</li> <li>If two chains share the same genesis, but not forks (ETH / ETC), they should reject each other.</li> </ul> <p>This EIP does not attempt to solve the clean separation of 3-way-forks! If at the same future block number, the network splits into three (non-fork, fork-A and fork-B), separating the forkers from each another will need case-by-case special handling. Not handling this keeps the proposal pragmatic, simple and also avoids making it too easy to fork off mainnet.</p> <p>To keep the scope limited, this EIP only defines the identity scheme and validation rules. The same scheme and algorithm can be embedded into various networking protocols, allowing both the <code>eth/6x</code> handshake to be more precise (Ethereum vs. Ethereum Classic); as well as the discovery to be more useful (reject surely peers without ever connecting).</p> <h2 id="motivation">Motivation</h2> <p>Peer-to-peer networking is messy and hard due to firewalls and network address translation (NAT). Generally only a small fraction of nodes have publicly routed addresses and P2P networks rely mainly on these for forwarding data for everyone else. The best way to maximize the utility of the public nodes is to ensure their resources aren't wasted on tasks that are worthless to the network.</p> <p>By aggressively cutting off incompatible nodes from each other we can extract a lot more value from the public nodes, making the entire P2P network much more robust and reliable. Supporting this network partitioning at a discovery layer can further enhance performance as we avoid the costly crypto and latency/bandwidth hit associated with establishing a stream connection in the first place.</p> <h2 id="specification">Specification</h2> <p>Each node maintains the following values:</p> <ul> <li><strong><code>FORK_HASH</code></strong>: IEEE CRC32 checksum (<code>[4]byte</code>) of the genesis hash and fork blocks numbers that already passed. <ul> <li>The fork block numbers are fed into the CRC32 checksum in ascending order.</li> <li>If multiple forks are applied at the same block, the block number is checksummed only once.</li> <li>Block numbers are regarded as <code>uint64</code> integers, encoded in big endian format when checksumming.</li> <li>If a chain is configured to start with a non-Frontier ruleset already in its genesis, that is NOT considered a fork.</li> </ul> </li> <li><strong><code>FORK_NEXT</code></strong>: Block number (<code>uint64</code>) of the next upcoming fork, or <code>0</code> if no next fork is known.</li> </ul> <p>E.g. <code>FORK_HASH</code> for mainnet would be:</p> <ul> <li>forkhash₀ = <code>0xfc64ec04</code> (Genesis) = <code>CRC32(&lt;genesis-hash&gt;)</code></li> <li>forkhash₁ = <code>0x97c2c34c</code> (Homestead) = <code>CRC32(&lt;genesis-hash&gt; || uint64(1150000))</code></li> <li>forkhash₂ = <code>0x91d1f948</code> (DAO fork) = <code>CRC32(&lt;genesis-hash&gt; || uint64(1150000) || uint64(1920000))</code></li> </ul> <p>The <em>fork identifier</em> is defined as <code>RLP([FORK_HASH, FORK_NEXT])</code>. This <code>forkid</code> is cross validated (<strong>NOT</strong> naively compared) to assess a remote chain's compatibility. Irrespective of fork state, both parties must come to the same conclusion to avoid indefinite reconnect attempts from one side.</p> <h4 id="validation-rules">Validation rules</h4> <ul> <li> <ol> <li>If local and remote <code>FORK_HASH</code> matches, compare local head to <code>FORK_NEXT</code>.</li> </ol> <ul> <li>The two nodes are in the same fork state currently. They might know of differing future forks, but that's not relevant until the fork triggers (might be postponed, nodes might be updated to match). <ul> <li>1a) A remotely announced but remotely not passed block is already passed locally, disconnect, since the chains are incompatible.</li> <li>1b) No remotely announced fork; or not yet passed locally, connect.</li> </ul> </li> </ul> </li> <li> <ol start="2"> <li>If the remote <code>FORK_HASH</code> is a subset of the local past forks and the remote <code>FORK_NEXT</code> matches with the locally following fork block number, connect.</li> </ol> <ul> <li>Remote node is currently syncing. It might eventually diverge from us, but at this current point in time we don't have enough information.</li> </ul> </li> <li> <ol start="3"> <li>If the remote <code>FORK_HASH</code> is a superset of the local past forks and can be completed with locally known future forks, connect.</li> </ol> <ul> <li>Local node is currently syncing. It might eventually diverge from the remote, but at this current point in time we don't have enough information.</li> </ul> </li> <li> <ol start="4"> <li>Reject in all other cases.</li> </ol> </li> </ul> <h4 id="stale-software-examples">Stale software examples</h4> <p>The examples below try to exhaust the fork combination possibilities that arise when nodes do not run matching software versions, but otherwise follow the same chain (mainnet nodes, testnet nodes, etc).</p> <table><thead><tr><th style="text-align: center">Past forks</th><th style="text-align: center">Future forks</th><th style="text-align: center">Head</th><th style="text-align: center">Remote <code>FORK_HASH</code></th><th style="text-align: center">Remote <code>FORK_NEXT</code></th><th style="text-align: center">Connect</th><th style="text-align: center">Reason</th></tr></thead><tbody> <tr><td style="text-align: center">A</td><td style="text-align: center"></td><td style="text-align: center"></td><td style="text-align: center">A</td><td style="text-align: center"></td><td style="text-align: center">Yes (1b)</td><td style="text-align: center">Same forks, same sync state.</td></tr> <tr><td style="text-align: center">A</td><td style="text-align: center"></td><td style="text-align: center">&lt; B</td><td style="text-align: center">A</td><td style="text-align: center">B</td><td style="text-align: center">Yes (1b)</td><td style="text-align: center">Remote is advertising a future fork, but that is uncertain.</td></tr> <tr><td style="text-align: center">A</td><td style="text-align: center"></td><td style="text-align: center">&gt;= B</td><td style="text-align: center">A</td><td style="text-align: center">B</td><td style="text-align: center">No (1a)</td><td style="text-align: center">Remote is advertising a future fork that passed locally.</td></tr> <tr><td style="text-align: center">A</td><td style="text-align: center">B</td><td style="text-align: center"></td><td style="text-align: center">A</td><td style="text-align: center"></td><td style="text-align: center">Yes (1b)</td><td style="text-align: center">Local knows about a future fork, but that is uncertain.</td></tr> <tr><td style="text-align: center">A</td><td style="text-align: center">B</td><td style="text-align: center"></td><td style="text-align: center">A</td><td style="text-align: center">B</td><td style="text-align: center">Yes (1b)</td><td style="text-align: center">Both know about a future fork, but that is uncertain.</td></tr> <tr><td style="text-align: center">A</td><td style="text-align: center">B1</td><td style="text-align: center">&lt; B2</td><td style="text-align: center">A</td><td style="text-align: center">B2</td><td style="text-align: center">Yes (1b)</td><td style="text-align: center">Both know about differing future forks, but those are uncertain.</td></tr> <tr><td style="text-align: center">A</td><td style="text-align: center">B1</td><td style="text-align: center">&gt;= B2</td><td style="text-align: center">A</td><td style="text-align: center">B2</td><td style="text-align: center">No (1a)</td><td style="text-align: center">Both know about differing future forks, but the remote one passed locally.</td></tr> <tr><td style="text-align: center">[A,B]</td><td style="text-align: center"></td><td style="text-align: center"></td><td style="text-align: center">A</td><td style="text-align: center">B</td><td style="text-align: center">Yes (2)</td><td style="text-align: center">Remote out of sync.</td></tr> <tr><td style="text-align: center">[A,B,C]</td><td style="text-align: center"></td><td style="text-align: center"></td><td style="text-align: center">A</td><td style="text-align: center">B</td><td style="text-align: center">Yes¹ (2)</td><td style="text-align: center">Remote out of sync. Remote will need a software update, but we don't know it yet.</td></tr> <tr><td style="text-align: center">A</td><td style="text-align: center">B</td><td style="text-align: center"></td><td style="text-align: center">A ⊕ B</td><td style="text-align: center"></td><td style="text-align: center">Yes (3)</td><td style="text-align: center">Local out of sync.</td></tr> <tr><td style="text-align: center">A</td><td style="text-align: center">B,C</td><td style="text-align: center"></td><td style="text-align: center">A ⊕ B</td><td style="text-align: center"></td><td style="text-align: center">Yes (3)</td><td style="text-align: center">Local out of sync. Local also knows about a future fork, but that is uncertain yet.</td></tr> <tr><td style="text-align: center">A</td><td style="text-align: center"></td><td style="text-align: center"></td><td style="text-align: center">A ⊕ B</td><td style="text-align: center"></td><td style="text-align: center">No (4)</td><td style="text-align: center">Local needs software update.</td></tr> <tr><td style="text-align: center">A</td><td style="text-align: center">B</td><td style="text-align: center"></td><td style="text-align: center">A ⊕ B ⊕ C</td><td style="text-align: center"></td><td style="text-align: center">No² (4)</td><td style="text-align: center">Local needs software update.</td></tr> <tr><td style="text-align: center">[A,B]</td><td style="text-align: center"></td><td style="text-align: center"></td><td style="text-align: center">A</td><td style="text-align: center"></td><td style="text-align: center">No (4)</td><td style="text-align: center">Remote needs software update.</td></tr> </tbody></table> <p><em>Note, there's one asymmetry in the table, marked with ¹ and ². Since we don't have access to a remote node's future fork list (just the next one), we can't detect that it's software is stale until it syncs up. This is acceptable as 1) the remote node will disconnect from us anyway, and 2) this is a temporary fluke during sync, not permanent with a leftover node.</em></p> <h2 id="rationale">Rationale</h2> <h5 id="why-flatten-fork-hash-into-4-bytes-why-not-share-the-entire-genesis-and-fork-list">Why flatten <code>FORK_HASH</code> into 4 bytes? Why not share the entire genesis and fork list?</h5> <p>Whilst the <code>eth</code> devp2p protocol permits arbitrarily much data to be transmitted, the discovery protocol's total space allowance for all ENR entries is 300 bytes.</p> <p>Reducing the <code>FORK_HASH</code> into a 4 bytes checksum ensures that we leave ample room in the ENR for future extensions; and 4 bytes is more than enough for arbitrarily many Ethereum networks from a (practical) collision perspective.</p> <h5 id="why-use-ieee-crc32-as-the-checksum-instead-of-keccak256">Why use IEEE CRC32 as the checksum instead of Keccak256?</h5> <p>We need a mechanism that can flatten arbitrary data into 4 bytes, without ignoring any of the input. Any other checksum or hashing algorithm would work, but since nodes can lie at any time, there's no value in cryptographic hash functions.</p> <p>Instead of just taking the first 4 bytes of a Keccak256 hash (seems odd) or XOR-ing all the 4-byte groups (messy), CRC32 is a better alternative, as this is exactly what it was designed for. IEEE CRC32 is also used by ethernet, gzip, zip, png, etc, so every programming language support should not be a problem.</p> <h5 id="we-re-not-using-fork-next-for-much-can-t-we-get-rid-of-it-somehow">We're not using <code>FORK_NEXT</code> for much, can't we get rid of it somehow?</h5> <p>We need to be able to differentiate whether a remote node is out of sync or whether its software is stale. Sharing only the past forks cannot tell us if the node is legitimately behind or stuck.</p> <h5 id="why-advertise-only-one-next-fork-instead-of-hashing-all-known-future-ones-like-the-fork-hash">Why advertise only one next fork, instead of "hashing" all known future ones like the <code>FORK_HASH</code>?</h5> <p>Opposed to past forks that have already passed (for us locally) and can be considered immutable, we don't know anything about future ones. Maybe we're out of sync or maybe the fork didn't pass yet. If it didn't pass yet, it might be postponed, so enforcing it would split the network apart. It could also happen that we're not yet aware of all future forks (haven't updated our software in a while).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP only defines an identity scheme, it does not define functional changes.</p> <h2 id="test-cases">Test Cases</h2> <p>Here's a full suite of tests for all possible fork IDs that Mainnet, Ropsten, Rinkeby and Görli can advertise given the Petersburg fork cap (time of writing).</p> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span class="z-keyword">type</span><span class="z-entity z-name"> testcase</span><span class="z-keyword"> struct</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> head</span><span class="z-storage z-type"> uint64</span></span> <span class="giallo-l"><span class="z-variable z-other"> want</span><span class="z-entity z-name"> ID</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span class="z-variable z-other">tests</span><span class="z-keyword"> :=</span><span> [</span><span>]</span><span class="z-keyword">struct</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> config</span><span class="z-keyword"> *</span><span class="z-entity z-name">params</span><span>.</span><span class="z-entity z-name">ChainConfig</span></span> <span class="giallo-l"><span class="z-variable z-other"> genesis</span><span class="z-entity z-name"> common</span><span>.</span><span class="z-entity z-name">Hash</span></span> <span class="giallo-l"><span class="z-variable z-other"> cases</span><span> [</span><span>]</span><span class="z-entity z-name">testcase</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"> Mainnet test cases</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> params</span><span>.</span><span class="z-variable z-other">MainnetChainConfig</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> params</span><span>.</span><span class="z-variable z-other">MainnetGenesisHash</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>]</span><span class="z-entity z-name">testcase</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">fc64ec04</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1150000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Unsynced</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">1149999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">fc64ec04</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1150000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Frontier block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">1150000</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">97c2c34c</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1920000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Homestead block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">1919999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">97c2c34c</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1920000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Homestead block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">1920000</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">91d1f948</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 2463000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First DAO block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">2462999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">91d1f948</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 2463000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last DAO block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">2463000</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">7a64da13</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 2675000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Tangerine block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">2674999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">7a64da13</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 2675000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Tangerine block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">2675000</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">3edd5b10</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 4370000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Spurious block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">4369999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">3edd5b10</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 4370000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Spurious block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">4370000</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">a00bc324</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 7280000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Byzantium block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7279999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">a00bc324</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 7280000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Byzantium block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7280000</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">668db0af</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First and last Constantinople, first Petersburg block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7987396</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">668db0af</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Today Petersburg block</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"> Ropsten test cases</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> params</span><span>.</span><span class="z-variable z-other">TestnetChainConfig</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> params</span><span>.</span><span class="z-variable z-other">TestnetGenesisHash</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>]</span><span class="z-entity z-name">testcase</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">30c7ddbc</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 10</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Unsynced, last Frontier, Homestead and first Tangerine block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">9</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">30c7ddbc</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 10</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Tangerine block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">10</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">63760190</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1700000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Spurious block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">1699999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">63760190</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1700000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Spurious block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">1700000</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">3ea159c7</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 4230000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Byzantium block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">4229999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">3ea159c7</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 4230000</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Byzantium block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">4230000</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">97b544f3</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 4939394</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Constantinople block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">4939393</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">97b544f3</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 4939394</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Constantinople block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">4939394</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">d6e2149b</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 6485846</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Petersburg block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">6485845</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">d6e2149b</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 6485846</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Petersburg block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">6485846</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">4bc66396</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Istanbul block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7500000</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">4bc66396</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Future Istanbul block</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"> Rinkeby test cases</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> params</span><span>.</span><span class="z-variable z-other">RinkebyChainConfig</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> params</span><span>.</span><span class="z-variable z-other">RinkebyGenesisHash</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>]</span><span class="z-entity z-name">testcase</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">3b8e0691</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Unsynced, last Frontier block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">1</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">60949295</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 2</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First and last Homestead block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">2</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">8bde40dd</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 3</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First and last Tangerine block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">3</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">cb3a64bb</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1035301</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Spurious block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">1035300</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">cb3a64bb</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1035301</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Spurious block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">1035301</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">8d748b57</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 3660663</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Byzantium block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">3660662</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">8d748b57</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 3660663</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Byzantium block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">3660663</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">e49cab14</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 4321234</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Constantinople block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">4321233</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">e49cab14</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 4321234</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Constantinople block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">4321234</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">afec6b27</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 5435345</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Petersburg block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">5435344</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">afec6b27</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 5435345</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Petersburg block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">5435345</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">cbdb8838</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Istanbul block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">6000000</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">cbdb8838</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Future Istanbul block</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"> Goerli test cases</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> params</span><span>.</span><span class="z-variable z-other">GoerliChainConfig</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> params</span><span>.</span><span class="z-variable z-other">GoerliGenesisHash</span><span>,</span></span> <span class="giallo-l"><span> [</span><span>]</span><span class="z-entity z-name">testcase</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">0</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">a3f5ab08</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1561651</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Unsynced, last Frontier, Homestead, Tangerine, Spurious, Byzantium, Constantinople and first Petersburg block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">1561650</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">a3f5ab08</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 1561651</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Last Petersburg block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">1561651</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">c25efa5c</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> First Istanbul block</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">2000000</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">c25efa5c</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Future Istanbul block</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>}</span></span></code></pre> <p>Here's a suite of tests of the different states a Mainnet node might be in and the different remote fork identifiers it might be required to validate and decide to accept or reject:</p> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span class="z-variable z-other">tests</span><span class="z-keyword"> :=</span><span> [</span><span>]</span><span class="z-keyword">struct</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> head</span><span class="z-storage z-type"> uint64</span></span> <span class="giallo-l"><span class="z-variable z-other"> id</span><span class="z-entity z-name"> ID</span></span> <span class="giallo-l"><span class="z-variable z-other"> err</span><span class="z-storage z-type"> error</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"> Local is mainnet Petersburg, remote announces the same. No future fork is announced.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7987396</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">668db0af</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet Petersburg, remote announces the same. Remote also announces a next fork</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> at block 0xffffffff, but that is uncertain.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7987396</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">668db0af</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-variable z-other"> math</span><span>.</span><span class="z-variable z-other">MaxUint64</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet currently in Byzantium only (so it&#39;s aware of Petersburg), remote announces</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> also Byzantium, but it&#39;s not yet aware of Petersburg (e.g. non updated node before the fork).</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> In this case we don&#39;t know if Petersburg passed yet or not.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7279999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">a00bc324</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet currently in Byzantium only (so it&#39;s aware of Petersburg), remote announces</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> also Byzantium, and it&#39;s also aware of Petersburg (e.g. updated node before the fork). We</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> don&#39;t know if Petersburg passed yet (will pass) or not.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7279999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">a00bc324</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 7280000</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet currently in Byzantium only (so it&#39;s aware of Petersburg), remote announces</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> also Byzantium, and it&#39;s also aware of some random fork (e.g. misconfigured Petersburg). As</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> neither forks passed at neither nodes, they may mismatch, but we still connect for now.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7279999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">a00bc324</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-variable z-other"> math</span><span>.</span><span class="z-variable z-other">MaxUint64</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet Petersburg, remote announces Byzantium + knowledge about Petersburg. Remote</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> is simply out of sync, accept.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7987396</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">a00bc324</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 7280000</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet Petersburg, remote announces Spurious + knowledge about Byzantium. Remote</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> is definitely out of sync. It may or may not need the Petersburg update, we don&#39;t know yet.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7987396</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">3edd5b10</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 4370000</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet Byzantium, remote announces Petersburg. Local is out of sync, accept.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7279999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">668db0af</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet Spurious, remote announces Byzantium, but is not aware of Petersburg. Local</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> out of sync. Local also knows about a future fork, but that is uncertain yet.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">4369999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">a00bc324</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-constant"> nil</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"> Local is mainnet Petersburg. remote announces Byzantium but is not aware of further forks.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Remote needs software update.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7987396</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">a00bc324</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-variable z-other"> ErrRemoteStale</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"> Local is mainnet Petersburg, and isn&#39;t aware of more forks. Remote announces Petersburg +</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 0xffffffff. Local needs software update, reject.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7987396</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">5cddc0e1</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-variable z-other"> ErrLocalIncompatibleOrStale</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"> Local is mainnet Byzantium, and is aware of Petersburg. Remote announces Petersburg +</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 0xffffffff. Local needs software update, reject.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7279999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">5cddc0e1</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-variable z-other"> ErrLocalIncompatibleOrStale</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"> Local is mainnet Petersburg, remote is Rinkeby Petersburg.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7987396</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">afec6b27</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span><span class="z-variable z-other"> ErrLocalIncompatibleOrStale</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"> Local is mainnet Petersburg, far in the future. Remote announces Gopherium (non existing fork)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> at some future block 88888888, for itself, but past block for local. Local is incompatible.</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"> This case detects non-upgraded nodes with majority hash power (typical Ropsten mess).</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">88888888</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">668db0af</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 88888888</span><span>}</span><span>,</span><span class="z-variable z-other"> ErrLocalIncompatibleOrStale</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"> Local is mainnet Byzantium. Remote is also in Byzantium, but announces Gopherium (non existing</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> fork) at block 7279999, before Petersburg. Local is incompatible.</span></span> <span class="giallo-l"><span> {</span><span class="z-constant">7279999</span><span>,</span><span class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">a00bc324</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 7279999</span><span>}</span><span>,</span><span class="z-variable z-other"> ErrLocalIncompatibleOrStale</span><span>}</span><span>,</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Here's a couple of tests to verify the proper RLP encoding (since <code>FORK_HASH</code> is a 4 byte binary but <code>FORK_NEXT</code> is an 8 byte quantity):</p> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span class="z-variable z-other">tests</span><span class="z-keyword"> :=</span><span> [</span><span>]</span><span class="z-keyword">struct</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> id</span><span class="z-entity z-name"> ID</span></span> <span class="giallo-l"><span class="z-variable z-other"> want</span><span> [</span><span>]</span><span class="z-storage z-type">byte</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-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-constant"> 0</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-constant"> 0</span><span>}</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> common</span><span>.</span><span class="z-entity z-name">Hex2Bytes</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">c6840000000080</span><span class="z-punctuation z-definition z-string">&quot;</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 class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">deadbeef</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-keyword"> 0x</span><span class="z-constant">BADDCAFE</span><span>}</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> common</span><span>.</span><span class="z-entity z-name">Hex2Bytes</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ca84deadbeef84baddcafe</span><span class="z-punctuation z-definition z-string">&quot;</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 class="z-entity z-name"> ID</span><span>{</span><span class="z-variable z-other">Hash</span><span>:</span><span class="z-variable z-other"> math</span><span>.</span><span class="z-variable z-other">MaxUint32</span><span>,</span><span class="z-variable z-other"> Next</span><span>:</span><span class="z-variable z-other"> math</span><span>.</span><span class="z-variable z-other">MaxUint64</span><span>}</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> common</span><span>.</span><span class="z-entity z-name">Hex2Bytes</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ce84ffffffff88ffffffffffffffff</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="implementation">Implementation</h2> <p>Geth: https://github.com/ethereum/go-ethereum/tree/master/core/forkid</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-24T00:00:00+00:00 2026-02-11T14:48:25+00:00 Santiago Palladinohttps://github.com/spalladino Francisco Giordanohttps://github.com/frangio Hadrien Crouboishttps://github.com/Amxx https://wg-eips.ritovision.com/1967/

A consistent location where proxies store the address of the logic contract they delegate to, as well as other proxy-specific information.

<h2 id="abstract">Abstract</h2> <p>Delegating <strong>proxy contracts</strong> are widely used for both upgradeability and gas savings. These proxies rely on a <strong>logic contract</strong> (also known as implementation contract or master copy) that is called using <code>delegatecall</code>. This allows proxies to keep a persistent state (storage and balance) while the code is delegated to the logic contract.</p> <p>To avoid clashes in storage usage between the proxy and logic contract, the address of the logic contract is typically saved in a specific storage slot (for example <code>0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc</code> in OpenZeppelin contracts) guaranteed to be never allocated by a compiler. This EIP proposes a set of standard slots to store proxy information. This allows clients like block explorers to properly extract and show this information to end users, and logic contracts to optionally act upon it.</p> <h2 id="motivation">Motivation</h2> <p>Delegating proxies are widely in use, as a means to both support upgrades and reduce gas costs of deployments. Examples of these proxies are found in OpenZeppelin Contracts, Gnosis, AragonOS, Melonport, Limechain, WindingTree, Decentraland, and many others.</p> <p>However, the lack of a common interface for obtaining the logic address for a proxy makes it impossible to build common tools that act upon this information.</p> <p>A classic example of this is a block explorer. Here, the end user wants to interact with the underlying logic contract and not the proxy itself. Having a common way to retrieve the logic contract address from a proxy allows a block explorer to show the ABI of the logic contract and not that of the proxy. The explorer checks the storage of the contract at the distinguished slots to determine if it is indeed a proxy, in which case it shows information on both the proxy and the logic contract. As an example, this is how <code>0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48</code> is shown on Etherscan:</p> <p><img src="https://wg-eips.ritovision.com/1967/./assets/Sample-proxy-on-etherscan.png" alt="Sample proxy on Etherscan" /></p> <p>Another example is logic contracts that explicitly act upon the fact that they are being proxied. This allows them to potentially trigger a code update as part of their logic. A common storage slot allows these use cases independently of the specific proxy implementation being used.</p> <h2 id="specification">Specification</h2> <p>Monitoring of proxies is essential to the security of many applications. It is thus essential to have the ability to track changes to the implementation and admin slots. Unfortunately, tracking changes to storage slots is not easy. Consequently, it is recommended that any function that changes any of these slots SHOULD also emit the corresponding event. This includes initialization, from <code>0x0</code> to the first non-zero value.</p> <p>The proposed storage slots for proxy-specific information are the following. More slots for additional information can be added in subsequent ERCs as needed.</p> <h3 id="logic-contract-address">Logic contract address</h3> <p>Storage slot <code>0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc</code> (obtained as <code>bytes32(uint256(keccak256('eip1967.proxy.implementation')) - 1)</code>).</p> <p>Holds the address of the logic contract that this proxy delegates to. SHOULD be empty if a beacon is used instead. Changes to this slot SHOULD be notified by the event:</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"> Upgraded</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> implementation</span><span>)</span><span>;</span></span></code></pre><h3 id="beacon-contract-address">Beacon contract address</h3> <p>Storage slot <code>0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50</code> (obtained as <code>bytes32(uint256(keccak256('eip1967.proxy.beacon')) - 1)</code>).</p> <p>Holds the address of the beacon contract this proxy relies on (fallback). SHOULD be empty if a logic address is used directly instead, and should only be considered if the logic contract slot is empty. Changes to this slot SHOULD be notified by the event:</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"> BeaconUpgraded</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> beacon</span><span>)</span><span>;</span></span></code></pre> <p>Beacons are used for keeping the logic address for multiple proxies in a single location, allowing the upgrade of multiple proxies by modifying a single storage slot. A beacon contract MUST implement the function:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function implementation() returns (address)</span></span></code></pre> <p>Beacon based proxy contracts do not use the logic contract slot. Instead, they use the beacon contract slot to store the address of the beacon they are attached to. In order to know the logic contract used by a beacon proxy, a client SHOULD:</p> <ul> <li>Read the address of the beacon for the beacon logic storage slot;</li> <li>Call the <code>implementation()</code> function on the beacon contract.</li> </ul> <p>The result of the <code>implementation()</code> function on the beacon contract SHOULD NOT depend on the caller (<code>msg.sender</code>).</p> <h3 id="admin-address">Admin address</h3> <p>Storage slot <code>0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103</code> (obtained as <code>bytes32(uint256(keccak256('eip1967.proxy.admin')) - 1)</code>).</p> <p>Holds the address that is allowed to upgrade the logic contract address for this proxy (optional). Changes to this slot SHOULD be notified by the event:</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"> AdminChanged</span><span>(</span><span class="z-support">address</span><span class="z-variable"> previousAdmin</span><span>, </span><span class="z-support">address</span><span class="z-variable"> newAdmin</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This EIP standardises the <strong>storage slot</strong> for the logic contract address, instead of a public method on the proxy contract. The rationale for this is that proxies should never expose functions to end users that could potentially clash with those of the logic contract.</p> <p>Note that a clash may occur even among functions with different names, since the ABI relies on just four bytes for the function selector. This can lead to unexpected errors, or even exploits, where a call to a proxied contract returns a different value than expected, since the proxy intercepts the call and answers with a value of its own.</p> <p>From <em>Malicious backdoors in Ethereum proxies</em> by Nomic Labs:</p> <blockquote> <p>Any function in the Proxy contract whose selector matches with one in the implementation contract will be called directly, completely skipping the implementation code.</p> <p>Because the function selectors use a fixed amount of bytes, there will always be the possibility of a clash. This isn’t an issue for day to day development, given that the Solidity compiler will detect a selector clash within a contract, but this becomes exploitable when selectors are used for cross-contract interaction. Clashes can be abused to create a seemingly well-behaved contract that’s actually concealing a backdoor.</p> </blockquote> <p>The fact that proxy public functions are potentially exploitable makes it necessary to standardise the logic contract address in a different way.</p> <p>The main requirement for the storage slots chosen is that they must never be picked by the compiler to store any contract state variable. Otherwise, a logic contract could inadvertently overwrite this information on the proxy when writing to a variable of its own.</p> <p>Solidity maps variables to storage based on the order in which they were declared, after the contract inheritance chain is linearized: the first variable is assigned the first slot, and so on. The exception is values in dynamic arrays and mappings, which are stored in the hash of the concatenation of the key and the storage slot. The Solidity development team has confirmed that the storage layout is to be preserved among new versions:</p> <blockquote> <p>The layout of state variables in storage is considered to be part of the external interface of Solidity due to the fact that storage pointers can be passed to libraries. This means that any change to the rules outlined in this section is considered a breaking change of the language and due to its critical nature should be considered very carefully before being executed. In the event of such a breaking change, we would want to release a compatibility mode in which the compiler would generate bytecode supporting the old layout.</p> </blockquote> <p>Vyper seems to follow the same strategy as Solidity. Note that contracts written in other languages, or directly in assembly, may incur in clashes.</p> <p>They are chosen in such a way so they are guaranteed to not clash with state variables allocated by the compiler, since they depend on the hash of a string that does not start with a storage index. Furthermore, a <code>-1</code> offset is added so the preimage of the hash cannot be known, further reducing the chances of a possible attack.</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This contract implements an upgradeable proxy. It is upgradeable because calls are delegated to an</span></span> <span class="giallo-l"><span class="z-comment"> * implementation address that can be </span><span class="z-keyword">changed</span><span class="z-comment">. This address is stored in storage in the location specified by</span></span> <span class="giallo-l"><span class="z-comment"> * https://eips.ethereum.org/EIPS/eip-1967[EIP1967], so that it doesn&#39;t conflict with the storage layout of the</span></span> <span class="giallo-l"><span class="z-comment"> * implementation behind the proxy.</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"> ERC1967Proxy</span><span class="z-storage"> is</span><span class="z-entity z-name"> Proxy</span><span>, </span><span class="z-entity z-name">ERC1967Upgrade</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"> Initializes the upgradeable proxy with an initial implementation specified by `_logic`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * If `_data` is nonempty, it&#39;s used as data in a delegate call to `_logic`. This will typically be an encoded</span></span> <span class="giallo-l"><span class="z-comment"> * function call, and allows initializing the storage of the proxy like a Solidity constructor.</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"> _logic</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"> _data</span><span>)</span><span> payable </span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span>_IMPLEMENTATION_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">&quot;eip1967.proxy.implementation&quot;</span><span>)</span><span>)</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-entity z-name"> _upgradeToAndCall</span><span>(</span><span>_logic</span><span>,</span><span> _data</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 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 current implementation 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"> _implementation</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</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 class="z-variable"> impl</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> ERC1967Upgrade</span><span>.</span><span class="z-entity z-name">_getImplementation</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-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 abstract contract provides getters and event emitting update functions for</span></span> <span class="giallo-l"><span class="z-comment"> * https://eips.ethereum.org/EIPS/eip-1967[EIP1967] slots.</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"> ERC1967Upgrade</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> This is the keccak-256 hash of &quot;eip1967.proxy.rollback&quot; subtracted by 1</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> _ROLLBACK_SLOT </span><span class="z-keyword">=</span><span class="z-constant"> 0x4910fdfa16fed3260ed0e7147f7cc6da11a60208b5b9406d12a635614ffd9143</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"> Storage slot with the address of the current implementation.</span></span> <span class="giallo-l"><span class="z-comment"> * This is the keccak-256 hash of &quot;eip1967.proxy.implementation&quot; subtracted by 1, and is</span></span> <span class="giallo-l"><span class="z-comment"> * validated in the constructor.</span></span> <span class="giallo-l"><span class="z-comment"> */</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> _IMPLEMENTATION_SLOT </span><span class="z-keyword">=</span><span class="z-constant"> 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc</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 the implementation is upgraded.</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"> Upgraded</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> implementation</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 current implementation 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"> _getImplementation</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>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> StorageSlot</span><span>.</span><span class="z-entity z-name">getAddressSlot</span><span>(</span><span>_IMPLEMENTATION_SLOT</span><span>)</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Stores a new address in the EIP1967 implementation slot.</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"> _setImplementation</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newImplementation</span><span>)</span><span class="z-storage z-type"> private</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>Address</span><span>.</span><span class="z-entity z-name">isContract</span><span>(</span><span>newImplementation</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC1967: new implementation is not a contract&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> StorageSlot</span><span>.</span><span class="z-entity z-name">getAddressSlot</span><span>(</span><span>_IMPLEMENTATION_SLOT</span><span>)</span><span>.</span><span>value </span><span class="z-keyword">=</span><span> newImplementation</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"> Perform implementation upgrade</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {Upgraded} 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"> _upgradeTo</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newImplementation</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setImplementation</span><span>(</span><span>newImplementation</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>newImplementation</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"> Perform implementation upgrade with additional setup call.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {Upgraded} 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"> _upgradeToAndCall</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> newImplementation</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-support"> bool</span><span class="z-variable"> forceCall</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _upgradeTo</span><span>(</span><span>newImplementation</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>data</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span class="z-keyword"> ||</span><span> forceCall</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> Address</span><span>.</span><span class="z-entity z-name">functionDelegateCall</span><span>(</span><span>newImplementation</span><span>,</span><span> data</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"> Perform implementation upgrade with security checks for UUPS proxies, and additional setup call.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {Upgraded} 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"> _upgradeToAndCallSecure</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> newImplementation</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-support"> bool</span><span class="z-variable"> forceCall</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> oldImplementation </span><span class="z-keyword">=</span><span class="z-entity z-name"> _getImplementation</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"> Initial upgrade and setup call</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setImplementation</span><span>(</span><span>newImplementation</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>data</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span class="z-keyword"> ||</span><span> forceCall</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> Address</span><span>.</span><span class="z-entity z-name">functionDelegateCall</span><span>(</span><span>newImplementation</span><span>,</span><span> 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-comment"> //</span><span class="z-comment"> Perform rollback test if not already in progress</span></span> <span class="giallo-l"><span> StorageSlot</span><span>.</span><span>BooleanSlot </span><span class="z-storage z-type">storage</span><span> rollbackTesting </span><span class="z-keyword">=</span><span> StorageSlot</span><span>.</span><span class="z-entity z-name">getBooleanSlot</span><span>(</span><span>_ROLLBACK_SLOT</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>rollbackTesting</span><span>.</span><span>value</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Trigger rollback using upgradeTo from the new implementation</span></span> <span class="giallo-l"><span> rollbackTesting</span><span>.</span><span>value </span><span class="z-keyword">=</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> Address</span><span>.</span><span class="z-entity z-name">functionDelegateCall</span><span>(</span></span> <span class="giallo-l"><span> newImplementation</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSignature</span><span>(</span><span class="z-string">&quot;upgradeTo(address)&quot;</span><span>,</span><span> oldImplementation</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> rollbackTesting</span><span>.</span><span>value </span><span class="z-keyword">=</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Check rollback was effective</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>oldImplementation </span><span class="z-keyword">==</span><span class="z-entity z-name"> _getImplementation</span><span>(</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC1967Upgrade: upgrade breaks further upgrades&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Finally reset to the new implementation and log the upgrade</span></span> <span class="giallo-l"><span class="z-entity z-name"> _upgradeTo</span><span>(</span><span>newImplementation</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"> Storage slot with the admin of the contract.</span></span> <span class="giallo-l"><span class="z-comment"> * This is the keccak-256 hash of &quot;eip1967.proxy.admin&quot; subtracted by 1, and is</span></span> <span class="giallo-l"><span class="z-comment"> * validated in the constructor.</span></span> <span class="giallo-l"><span class="z-comment"> */</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> _ADMIN_SLOT </span><span class="z-keyword">=</span><span class="z-constant"> 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103</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 the admin account has </span><span class="z-keyword">changed</span><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"> event</span><span class="z-entity z-name"> AdminChanged</span><span>(</span><span class="z-support">address</span><span class="z-variable"> previousAdmin</span><span>, </span><span class="z-support">address</span><span class="z-variable"> newAdmin</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 current admin.</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"> _getAdmin</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>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> StorageSlot</span><span>.</span><span class="z-entity z-name">getAddressSlot</span><span>(</span><span>_ADMIN_SLOT</span><span>)</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Stores a new address in the EIP1967 admin slot.</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"> _setAdmin</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newAdmin</span><span>)</span><span class="z-storage z-type"> private</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>newAdmin </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;ERC1967: new admin is the zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> StorageSlot</span><span>.</span><span class="z-entity z-name">getAddressSlot</span><span>(</span><span>_ADMIN_SLOT</span><span>)</span><span>.</span><span>value </span><span class="z-keyword">=</span><span> newAdmin</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"> Changes the admin of the proxy.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {AdminChanged} 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"> _changeAdmin</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newAdmin</span><span>)</span><span class="z-storage z-type"> internal</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">_getAdmin</span><span>(</span><span>)</span><span>,</span><span> newAdmin</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setAdmin</span><span>(</span><span>newAdmin</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"> The storage slot of the UpgradeableBeacon contract which defines the implementation for this proxy.</span></span> <span class="giallo-l"><span class="z-comment"> * This is bytes32(uint256(keccak256(&#39;eip1967.proxy.beacon&#39;)) - 1)) and is validated in the constructor.</span></span> <span class="giallo-l"><span class="z-comment"> */</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> _BEACON_SLOT </span><span class="z-keyword">=</span><span class="z-constant"> 0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50</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 the beacon is upgraded.</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"> BeaconUpgraded</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> beacon</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 current beacon.</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"> _getBeacon</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>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> StorageSlot</span><span>.</span><span class="z-entity z-name">getAddressSlot</span><span>(</span><span>_BEACON_SLOT</span><span>)</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> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Stores a new beacon in the EIP1967 beacon slot.</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"> _setBeacon</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newBeacon</span><span>)</span><span class="z-storage z-type"> private</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>Address</span><span>.</span><span class="z-entity z-name">isContract</span><span>(</span><span>newBeacon</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC1967: new beacon is not a contract&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> Address</span><span>.</span><span class="z-entity z-name">isContract</span><span>(</span><span class="z-entity z-name">IBeacon</span><span>(</span><span>newBeacon</span><span>)</span><span>.</span><span class="z-entity z-name">implementation</span><span>(</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;ERC1967: beacon implementation is not a contract&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> StorageSlot</span><span>.</span><span class="z-entity z-name">getAddressSlot</span><span>(</span><span>_BEACON_SLOT</span><span>)</span><span>.</span><span>value </span><span class="z-keyword">=</span><span> newBeacon</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"> Perform beacon upgrade with additional setup call. </span><span class="z-keyword">Note</span><span class="z-comment">: This upgrades the address of the beacon, it does</span></span> <span class="giallo-l"><span class="z-comment"> * not upgrade the implementation contained in the beacon (see {UpgradeableBeacon-_setImplementation} for that).</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {BeaconUpgraded} 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"> _upgradeBeaconToAndCall</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> newBeacon</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-support"> bool</span><span class="z-variable"> forceCall</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setBeacon</span><span>(</span><span>newBeacon</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> BeaconUpgraded</span><span>(</span><span>newBeacon</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>data</span><span>.</span><span>length </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span class="z-keyword"> ||</span><span> forceCall</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> Address</span><span>.</span><span class="z-entity z-name">functionDelegateCall</span><span>(</span><span class="z-entity z-name">IBeacon</span><span>(</span><span>newBeacon</span><span>)</span><span>.</span><span class="z-entity z-name">implementation</span><span>(</span><span>)</span><span>,</span><span> data</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-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 abstract contract provides a fallback function that delegates all calls to another contract using the EVM</span></span> <span class="giallo-l"><span class="z-comment"> * instruction `delegatecall`. We refer to the second contract as the _implementation_ behind the proxy, and it has to</span></span> <span class="giallo-l"><span class="z-comment"> * be specified by overriding the virtual {_implementation} function.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Additionally, delegation to the implementation can be triggered manually through the {_fallback} function, or to a</span></span> <span class="giallo-l"><span class="z-comment"> * different contract through the {_delegate} function.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * The success and return data of the delegated call will be returned back to the caller of the proxy.</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"> Proxy</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"> Delegates the current call to `implementation`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * This function does not return to its internal call site, it will return directly to the external caller.</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"> _delegate</span><span>(</span><span class="z-support">address</span><span class="z-variable"> implementation</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"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Copy msg.data. We take full control of memory in this inline assembly</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> block because it will not return to Solidity code. We overwrite the</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Solidity scratch pad at memory position 0.</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> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Call the implementation.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> out and outsize are 0 because we don&#39;t know the size yet.</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> implementation</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> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Copy the returned data.</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> <span class="giallo-l"><span> switch result</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> delegatecall returns 0 on error.</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 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"> This is a virtual function that should be overridden so it returns the address to which the fallback function</span></span> <span class="giallo-l"><span class="z-comment"> * and {_fallback} should delegate.</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"> _implementation</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</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">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">@dev</span><span class="z-comment"> Delegates the current call to the address returned by `_implementation()`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * This function does not return to its internal call site, it will return directly to the external caller.</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"> _fallback</span><span>(</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-entity z-name"> _beforeFallback</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">_implementation</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Fallback function that delegates calls to the address returned by `_implementation()`. Will run if no other</span></span> <span class="giallo-l"><span class="z-comment"> * function in the contract matches the call data.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></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 class="z-storage z-type"> virtual</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Fallback function that delegates calls to the address returned by `_implementation()`. Will run if call data</span></span> <span class="giallo-l"><span class="z-comment"> * is empty.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></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 class="z-storage z-type"> virtual</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Hook that is called before falling back to the implementation. Can happen as part of a manual `_fallback`</span></span> <span class="giallo-l"><span class="z-comment"> * call, or as part of the Solidity `fallback` or `receive` functions.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * If overridden should call `super._beforeFallback()`.</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"> _beforeFallback</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> virtual</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"> Library for reading and writing primitive types to specific storage slots.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Storage slots are often used to avoid storage conflict when dealing with upgradeable contracts.</span></span> <span class="giallo-l"><span class="z-comment"> * This library helps with reading and writing to such slots without the need for inline assembly.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * The functions in this library return Slot structs that contain a `value` member that can be used to read or write.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">library</span><span class="z-entity z-name"> StorageSlot</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> AddressSlot</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</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-storage z-type"> struct</span><span class="z-entity z-name"> BooleanSlot</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bool</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-storage z-type"> struct</span><span class="z-entity z-name"> Bytes32Slot</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</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-storage z-type"> struct</span><span class="z-entity z-name"> Uint256Slot</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> }</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 `AddressSlot` with member `value` located at `slot`.</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"> getAddressSlot</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> slot</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-storage z-type">AddressSlot</span><span class="z-storage z-type"> storage</span><span class="z-variable"> r</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>.</span><span>slot </span><span class="z-keyword">:=</span><span> slot</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"> Returns an `BooleanSlot` with member `value` located at `slot`.</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"> getBooleanSlot</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> slot</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-storage z-type">BooleanSlot</span><span class="z-storage z-type"> storage</span><span class="z-variable"> r</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>.</span><span>slot </span><span class="z-keyword">:=</span><span> slot</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"> Returns an `Bytes32Slot` with member `value` located at `slot`.</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"> getBytes32Slot</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> slot</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-storage z-type">Bytes32Slot</span><span class="z-storage z-type"> storage</span><span class="z-variable"> r</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>.</span><span>slot </span><span class="z-keyword">:=</span><span> slot</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"> Returns an `Uint256Slot` with member `value` located at `slot`.</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"> getUint256Slot</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> slot</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-storage z-type">Uint256Slot</span><span class="z-storage z-type"> storage</span><span class="z-variable"> r</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>.</span><span>slot </span><span class="z-keyword">:=</span><span> slot</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> <p>This ERC relies on the fact that the chosen storage slots are <strong>not</strong> to be allocated by the solidity compiler. This guarantees that an implementation contract will not accidentally overwrite any of the information required for the proxy to operate. As such, locations with a high slot number were chosen to avoid clashes with the slots allocated by the compiler. Also, locations with no known preimage were picked, to ensure that a write to mapping with a maliciously crafted key could not overwrite it.</p> <p>Logic contracts that intend to modify proxy-specific information must do so deliberately (as is the case with UUPS) by writing to the specific storage slot.</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-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-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 James Hancockhttps://github.com/madeoftin https://wg-eips.ritovision.com/2025/ <h2 id="simple-summary">Simple Summary</h2> <p>Add <code>0.0055 ETH</code> per block for 18 months (A total of 17050 ETH) as a developer block reward reserved for funding specific Ethereum1.X working groups. The working groups are State rent (750k), Better sync (360k), Finality gadget (360k), Fee market (360k), Testing infrastructure (360k). Governance of the funds will be through a multisig of trusted individuals from the ecosystem including client teams, the foundation, and the community.</p> <p><a href="https://wg-eips.ritovision.com/1890/">EIP-1890</a> proposes a mechanism to capture a portion of block rewards for sustainably funding ongoing network development. That EIP sets values and addresses to zero and so does not actually collect any rewards. This proposal is to explicitly set those values and begin collecting a portion of block rewards for 18 months in order to fund Ethereum 1.X working groups and organization efforts. This funding will be used to repay an initial loan provided by investors in the community funding this work with a small amount of interest. After 18 months the block reward would again reduce to zero.</p> <h2 id="abstract">Abstract</h2> <p>This EIP extends the mechanism established in EIP-1890 to add <code>0.0055 ETH</code> to the block reward for a specific distribution period of <code>3,100,000 BLOCKS</code>(≈ 18 months). The <code>RECIPIENT_ADDRESS</code> is set to a smart contract with hardcoded denominations that distributes incoming ETH to a set of addresses for the purpose of Eth1.X development. The emission schedule would start at the hard fork block number and continue for <code>3,100,000 BLOCKS</code> (≈ 18 months) at which point the address and amount would again return to 0. Any further distribution would require a future hard fork.</p> <h2 id="motivation">Motivation</h2> <p>The context for this proposal came from attending the <a rel="external" href="https://www.youtube.com/watch?v=Au1Qll-86v0">Core Dev Eth1.X Meeting</a> in Berlin. Development is needed to move Eth1.X forward, and I observed that a lack of funding is the primary barrier to this work. This work can only be effectively conducted by working groups forming around these issues, and these working groups need funding in order to pay dedicated contractors and project managers. This proposal is a plan for funding these groups and supporting their operation.</p> <h2 id="specification">Specification</h2> <p>Two constants will be introduced:</p> <ul> <li><code>REWARD_DURATION_IN_BLOCKS</code>, which specifies the number of blocks after <code>ISTANBUL_BLOCK_HEIGHT</code> when the reward collection will terminate (i.e., at block <code>ISTANBUL_BLOCK_HEIGHT + REWARD_DURATION_IN_BLOCKS</code>)</li> <li><code>BENEFICIARY_ADDRESSES</code>, a list of tuples containing the address and the amount to be transferred to this address per block. These amounts will be determined as the loan is collected from participating organizations and the addresses for repayment will be specified by them. The total of the amounts will sum to 0.0055. At the end of <code>REWARD_DURATION_IN_BLOCKS</code> the loan will be completely repaid.</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"></span> <span class="giallo-l"><span>REWARD_DURATION_IN_BLOCKS = 3100000</span></span> <span class="giallo-l"><span>DEVFUND_BLOCK_REWARD = 0.0055</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>BENEFICIARY_ADDRESSES = [</span></span> <span class="giallo-l"><span> (&lt;address&gt;, &lt;amount_in_eth&gt;),</span></span> <span class="giallo-l"><span> (&lt;address&gt;, &lt;amount_in_eth&gt;)</span></span> <span class="giallo-l"><span>]</span></span></code></pre> <p>Beginning with block <code>ISTANBUL_BLOCK_HEIGHT</code>, the reward is added to the participating addresses within <code>BENEFICIARY_ADDRESSES</code> at each block until the end of the <code>REWARD_DURATION_IN_BLOCKS</code>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>IF (CURRENT_BLOCK - ISTANBUL_BLOCK_HEIGHT &lt;= REWARD_DURATION_IN_BLOCKS)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>FOR BENEFICIARY in BENEFICIARY_ADDRESSES:</span></span> <span class="giallo-l"><span> BENEFICIARY[0].balance += BENEFICIARY[1]</span></span> <span class="giallo-l"></span></code></pre><h2 id="rewards-distribution-rationale">Rewards Distribution Rationale</h2> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> Development loan repayment: 0.005 ETH per block: 15500 ETH total</span></span> <span class="giallo-l"><span> Development loan interest (10% total over the period, simple interest): 0.0005 ETH per block: 1550 ETH total</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> Total Block Reward Increase = `0.0055` ETH per block: 17050 ETH Total</span></span></code></pre> <p><em>With a price of Ethereum at $150.00 this will raise approx USD $2,325,000.00 for developing Eth1.X over the next 18 months.</em></p> <p><img src="https://wg-eips.ritovision.com/2025/./assets/block_rewards_distribution.png" alt="Block Rewards Distribution" /> *Specific Addresses to be determined</p> <ul> <li><a href="https://wg-eips.ritovision.com/2025/#why-hardcoded-values">FAQ - Why hardcoded values?</a></li> </ul> <h2 id="rationale">Rationale</h2> <p>There has been great public debate concerning EIP-1890, and one of the primary concerns is that it is difficult to evaluate the proposal without more complete information on how funds would be raised, how they would be administered, and how they would be used. There is a need for funding Eth1.x development and it is currently unclear where those funds will come from. This proposal is intended to give a more comprehensive proposal for its funding. In the case that ETH1.x is fully funded before the Istanbul upgrade I will withdraw this EIP. Until that point I intend to continue championing this proposal as a valid funding mechanism for this work.</p> <h3 id="why-a-loan">Why a loan?</h3> <p>The Eth1x initiative needs funding now, not in 18 months. A loan is necessary to complete certain stages of work before the funding mechanism begins to provide funds. A loan would provide this necessary funding today, and the investors willing to front this cost can recoup their contribution + a reward of <em>a fixed interest rate</em> for the risk on their loan. This arrangement will make it easier to find investors willing to participate who have sufficient funds.</p> <h3 id="loan-repayment">Loan Repayment</h3> <p><img src="https://wg-eips.ritovision.com/2025/./assets/loan_state.png" alt="Loan State Diagram" /></p> <p>There is a risk that the investors lose part of their contribution in the case that this EIP is rejected by the community between the time the funds have been collected and the beginning of the payout schedule. In this case all remaining funds will be returned to the contributors. The interest on the loan is an incentive for investors to participate in spite of this risk. Their downside is limited to the amount of funds spent before this EIP is accepted or rejected, which should be no more than about 5%, while their upside consists of the 10% simple interest paid over the period.</p> <h3 id="development-loan">Development Loan</h3> <p><code>Development Loan: 0.005</code> over 3.1 Million blocks = 15500 ETH</p> <p><strong>Funding Working Groups on 1.X</strong></p> <ul> <li>Funding Contractors, Coordinators, and project managers</li> <li>Working Groups defined with clear mandates</li> </ul> <p>Budget</p> <p>Working groups</p> <ul> <li>State rent (750k)</li> <li>Better sync (360k)</li> <li>finality gadget (360k)</li> <li>Fee market (360k)</li> <li>testing infrastructure (360k)</li> </ul> <p><strong>ETH1.X Core Dev Gatherings</strong></p> <p>Funding hosting, traveling, and accommodations for necessary in-person gatherings of ETH1.X core developers similar to the Stanford and Berlin ETH1.X Core Dev Meeting held earlier this year.</p> <p>At the end of the 18 Months, the whole process would be torn down to prevent any internal tyranny of structurelessness forming within.</p> <ul> <li><a href="https://wg-eips.ritovision.com/2025/#how-will-funding-the-devs-be-organized">FAQ - How will the funding of the devs be organized?</a></li> </ul> <h2 id="accountability">Accountability</h2> <p>The funds will be transferred into DAI and secured in a multi-sig comprised of members of the community. Representatives from the following groups will receive a key.</p> <ul> <li>EIP Editors</li> <li>Geth</li> <li>Parity</li> <li>ConsenSys/PegaSys (PegaSys)</li> <li>The Ethereum Foundation (Hudson Jameson)</li> <li>Community</li> </ul> <h2 id="personal-notes-and-disclosure">Personal Notes and Disclosure</h2> <p>I want to address any concerns about conflicts of interests directly. My participation with Eth1.X currently has been as a volunteer. I am in talks about a possible funded role helping with testing and coordination. If my work for with Eth1.x is funded, I will accept no additional funding collected by the mechanism proposed in this EIP.</p> <p>Eth1.X is the now of Ethereum and I would like to see it succeed. This is the intent of my proposal.</p> <h3 id="coi">COI</h3> <p>Previously I was PM for Tennagraph, a signalling solution for Ethereum. An Aragon grant funded this project and was distributed through Giveth and an AragonDAO. I have not received any funding from the project beyond this grant. All of this is verifiable on-chain. I am stepping down from any paid role on the project to continue as an advisor. I am also stepping down as a moderator for stances as there is a COI moderating stances for EIPs I am working with directly.</p> <h3 id="disclaimer">Disclaimer</h3> <p>I do not claim to represent the community with my views; any members who wish to join supporting me with this proposal are free to do so. This is as fair of a proposal as I can personally conceive.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP has no impact on backwards compatibility.</p> <h2 id="test-cases">Test Cases</h2> <p>Not Implemented</p> <h2 id="implementation">Implementation</h2> <p>Not Implemented</p> <h2 id="faq">FAQ</h2> <h3 id="why-hardcoded-values">Why Hardcoded Values?</h3> <p>Why not use a smart contract with some governance mechanism to allow changing the distribution of funds? Wouldn’t that be more flexible and effective?</p> <p><em>TLDR: This EIP is not about governance reform</em></p> <p>First, the payment of the loan will be hardcoded. Once agreed, the terms must be kept to give the lenders confidence in the repayment of the loan. As long as blocks are created the debt will be paid back. This is the essence of a trustless smart contract.</p> <p>After the loan, there is the option to allow the amounts (limited to less than .05ETH), and the locations (orgs that receive ecosystem funding) to be changed throughout the emission schedule. It is pretty easy to imagine a smart contract or DAO fulfilling this role. However, there are three classes of options available today we can consider when governing changes.</p> <ul> <li><strong>Give the Keys to the Hands of the Few (Oligarchy)</strong></li> </ul> <p>Create a multisig that allows a group of individuals to update the smart contract. The most likely candidates for this are the Core Devs themselves, but it could also be a trusted few from the community/stakeholders. No matter how you slice it, there is a fundamental issue in deciding who gets to decide. There currently is not a trusted/adopted governance mechanism to make these decisions within the Ethereum ecosystem. Also, preventing changing the contract in self interest is difficult without a well-engineered governance system of checks and balances. This EIP does not claim nor aim to solve these issues.</p> <ul> <li><strong>Give the Keys to the Hands of the Many (Plutarchy)</strong></li> </ul> <p>Allow ethereum holders with coin votes to update the smart contract. Using holographic consensus could overcome the issue of voter turnout as it scales as participation scales, even to the size of the whole network. This has some benefits as the entire network can participate. However, the problem is that some individuals in the network are over represented -- the wealthy. Without a solution to identity that has been agreed to and implemented by the entire Ethereum Network, there is no way around giving more power in votes to the rich. This EIP does not claim, nor aim to solve these issues.</p> <ul> <li><strong>Use Ethereum Governance as it is Today</strong></li> </ul> <p>Criticisms or support aside, there is a system that governs Ethereum today. It is a mix of rough consensus among core devs, miners running nodes, clients implementing changes, and stakeholders adopting those changes. It includes yelling or not yelling on twitter and reddit. It is complicated and I don’t claim to understand it. Even without a clear view of how it works, there is evidence of its existence. This evidence is there are changes that have allowed to be implemented, and changes that have not allowed to be implemented in Ethereum.</p> <p>I do not aim to change Ethereum governance. Because this EIP has hardcoded values, it must go through the existing governance process, whatever that is, before it is implemented. It will then continue to operate until the end of the emission schedule. This is intentional. This makes it uncapturable. No party other then the ecosystem itself can modify the contract once it has been deployed.</p> <p>This EIP is not about governance reform.</p> <h3 id="why-not-allow-current-client-implementors-fund-this-work-ef-consensys-parity-etc">Why not allow current client implementors fund this work? (EF, Consensys, Parity, etc...)</h3> <p>Historically there has been a precedent that the Ethereum Foundation is solely responsible for funding the development of Ethereum. This process has evolved as the development has become more distributed. Aya Miyaguchi observed in a recent <a rel="external" href="https://www.coindesk.com/ethereum-foundation-director-sets-new-vision-for-blockchain-non-profit">Coindesk article</a>, “it really is not only Ethereum Foundation people who are building [Ethereum]”. Yes, we could rely on the Ethereum Foundation to fund Eth1.X. But, why should we? This is a call for the network to come together and fund its own development. Ethereum <em>the network</em> is not owned by any one organization or group of people. We are lucky to have the EF and I consider this EIP in support of their coordination efforts.</p> <h3 id="how-will-funding-the-devs-be-organized">How Will Funding the Devs be Organized</h3> <p>I do not profess to know the best way to organize these funds. There is work already in progress to organize these efforts championed by Alexey Akhunov. The following is a quote from a <a rel="external" href="https://medium.com/@akhounov/ethereum-1x-as-an-attempt-to-change-the-process-783efa23cf60">recent medium article</a>:</p> <blockquote> <p>“Going from funding a few implementation teams continuously and letting them do 'their stuff' to funding more specific and temporary initiatives requires looking at funding through different lenses. How much 'due diligence' and oversight is too much (in terms of overhead), who can decide whether working groups actually deliver, etc. This is also solvable, and also more on this will come later (not in this post)."</p> </blockquote> <p>My suggestion would be to create an Eth1.X core developer DAO using <a rel="external" href="https://daostack.io/">DaoStack</a> to coordinate membership and payment of the Core Devs, but ultimately they are capable of determining the system that works best for them. As long as the system is transparent and mature enough to distribute funds when the time comes, this is sufficient for now.</p> <h3 id="isn-t-a-loan-considered-a-security-or-is-it">Isn't a loan considered a security, or is it?</h3> <p>I am not a lawyer and will seek further guidance from lawyers in the field on this point in particular. From the research I have done and conversations I have had there is a very good argument that a loan of this nature will not be considered a security by the US Supreme Court. As the result of <a rel="external" href="https://casetext.com/case/reves-v-ernst-young">REVES ET AL. v . ERNST YOUNG 1990</a>, the court stated that a home loan, consumer financing, a loan secured by a lien on a small business or some assets of a small business, short term notes, or notes that formalize a debt incurred in the ordinary course of business are not securities. If the note resembles the items listed above (home loans, etc.) then the note will not be deemed a security. The Supreme Court provided four factors to determine if a note sufficiently resembles the types of notes that are not classified as securities. (<a rel="external" href="https://www.invigorlaw.com/loan-subject-securities-regulations/">source</a>)</p> <p><strong>Family Resemblance Test</strong></p> <ol> <li>The intentions of the company and the individual—if the company raised money for general use in a business enterprise, then the note is more likely to be a security; if the individual agreed to the loan primarily for the profit the note was expected to generate, the note is more likely to be a security.</li> <li>The plan of distribution—the more widely the note is offered, the more likely it is to be found a security.</li> <li>The expectations of the investing public—if the investors thought they were investing in a business to make a profit on their investment, the note is more likely to be found a security.</li> <li>Other risk-reducing factor—if the note is collateralized or otherwise less risky than common notes, the note is less likely to be found to be a security.</li> </ol> <p>The loan is for the specific use of supporting Eth1.X research and development. The distribution will not be widely offered and the note will be collateralized by the network itself, provided in ETH and repaid in ETH. In coordinating the collection of these funds recognise I may be legally liable for some of this work and I will do all of the due dilegence I can, seek legal counsel, and accept any legal repercussions resulting from this work.</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-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin Eric Connerhttps://github.com/econoar Rick Dudleyhttps://github.com/AFDudley Matthew Slipperhttps://github.com/mslipper Ian Nordenhttps://github.com/i-norden Abdelhamid Bakhtahttps://github.com/abdelhamidbakhta https://wg-eips.ritovision.com/1559/ <h2 id="simple-summary">Simple Summary</h2> <p>A transaction pricing mechanism that includes fixed-per-block network fee that is burned and dynamically expands/contracts block sizes to deal with transient congestion.</p> <h2 id="abstract">Abstract</h2> <p>We introduce a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction type, with the format <code>0x02 || 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>.</p> <p>There is a base fee per gas in protocol, which can move up or down each block according to a formula which is a function of gas used in parent block and gas target (block gas limit divided by elasticity multiplier) of parent block. The algorithm results in the base fee per gas increasing when blocks are above the gas target, and decreasing when blocks are below the gas target. The base fee per gas is burned. Transactions specify the maximum fee per gas they are willing to give to miners to incentivize them to include their transaction (aka: priority fee). Transactions also specify the maximum fee per gas they are willing to pay total (aka: max fee), which covers both the priority fee and the block's network fee per gas (aka: base fee). Senders will always pay the base fee per gas of the block their transaction was included in, and they will pay the priority fee per gas set in the transaction, as long as the combined amount of the two fees doesn't exceed the transaction's maximum fee per gas.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum historically priced 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>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. It's absurd to suggest that the cost incurred by the network from accepting one more transaction into a block actually is 10x more when the cost per gas is 10 nanoeth compared to when the cost per gas is 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.</li> <li><strong>Instability of blockchains with no block reward</strong>: In the long run, blockchains where there is no issuance (including Bitcoin and Zcash) at present intend to switch to rewarding miners entirely through transaction fees. However, there are known issues with this that likely leads to a lot of instability, incentivizing mining "sister blocks" that steal transaction fees, opening up much stronger selfish mining attack vectors, and more. There is at present no good mitigation for this.</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 priority fee, which compensates miners taking on orphan risk (e.g. 1 nanoeth), will be automatically set. Users can also manually set the transaction max fee to bound their total costs.</p> <p>An important aspect of this fee system is that miners only get to keep the priority fee. The base fee is always burned (i.e. it is destroyed by the protocol). This ensures that only ETH can ever be used to pay for transactions on Ethereum, cementing the economic value of ETH within the Ethereum platform and reducing risks associated with miner extractable value (MEV). Additionally, this burn counterbalances Ethereum inflation while still giving the block reward and priority fee to miners. Finally, ensuring the miner of a block does not receive the base fee is important because it removes miner incentive to manipulate the fee in order to extract more fees from users.</p> <h2 id="specification">Specification</h2> <p>Block validity is defined in the reference implementation below. The <code>GASPRICE</code> (<code>0x3a</code>) opcode <strong>MUST</strong> return the <code>effective_gas_price</code> as defined in the reference implementation below.</p> <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> 2.</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 <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>.</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, 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> <p><em>Note: <code>//</code> is integer division, round down.</em></p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">from</span><span> typing</span><span class="z-keyword"> import</span><span> Union</span><span>,</span><span> Dict</span><span>,</span><span> Sequence</span><span>,</span><span> List</span><span>,</span><span> Tuple</span><span>,</span><span> Literal</span></span> <span class="giallo-l"><span class="z-keyword">from</span><span> dataclasses</span><span class="z-keyword"> import</span><span> dataclass</span><span>,</span><span> field</span></span> <span class="giallo-l"><span class="z-keyword">from</span><span> abc</span><span class="z-keyword"> import</span><span class="z-constant"> ABC</span><span>,</span><span> abstractmethod</span></span> <span class="giallo-l"></span> <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"> TransactionLegacy</span><span>:</span></span> <span class="giallo-l"><span> signer_nonce</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> gas_price</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> gas_limit</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> destination</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> amount</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> payload</span><span>:</span><span class="z-support"> bytes</span><span class="z-keyword"> =</span><span class="z-support"> bytes</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> v</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> r</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> s</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <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"> Transaction2930Payload</span><span>:</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> signer_nonce</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> gas_price</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> gas_limit</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> destination</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> amount</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> payload</span><span>:</span><span class="z-support"> bytes</span><span class="z-keyword"> =</span><span class="z-support"> bytes</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> access_list</span><span>:</span><span> List</span><span>[</span><span>Tuple</span><span>[</span><span class="z-support">int</span><span>,</span><span> List</span><span>[</span><span class="z-support">int</span><span>]</span><span>]</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">list</span><span>)</span></span> <span class="giallo-l"><span> signature_y_parity</span><span>:</span><span class="z-support"> bool</span><span class="z-keyword"> =</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span> signature_r</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> signature_s</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <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"> Transaction2930Envelope</span><span>:</span></span> <span class="giallo-l"><span class="z-support"> type</span><span>:</span><span> Literal</span><span>[</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> payload</span><span>:</span><span> Transaction2930Payload</span><span class="z-keyword"> =</span><span> Transaction2930Payload</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <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"> Transaction1559Payload</span><span>:</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> signer_nonce</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> max_priority_fee_per_gas</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> max_fee_per_gas</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> gas_limit</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> destination</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> amount</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> payload</span><span>:</span><span class="z-support"> bytes</span><span class="z-keyword"> =</span><span class="z-support"> bytes</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> access_list</span><span>:</span><span> List</span><span>[</span><span>Tuple</span><span>[</span><span class="z-support">int</span><span>,</span><span> List</span><span>[</span><span class="z-support">int</span><span>]</span><span>]</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">list</span><span>)</span></span> <span class="giallo-l"><span> signature_y_parity</span><span>:</span><span class="z-support"> bool</span><span class="z-keyword"> =</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span> signature_r</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> signature_s</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <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"> Transaction1559Envelope</span><span>:</span></span> <span class="giallo-l"><span class="z-support"> type</span><span>:</span><span> Literal</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> 2</span></span> <span class="giallo-l"><span> payload</span><span>:</span><span> Transaction1559Payload</span><span class="z-keyword"> =</span><span> Transaction1559Payload</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Transaction2718</span><span class="z-keyword"> =</span><span> Union</span><span>[</span><span>Transaction1559Envelope</span><span>,</span><span> Transaction2930Envelope</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Transaction</span><span class="z-keyword"> =</span><span> Union</span><span>[</span><span>TransactionLegacy</span><span>,</span><span> Transaction2718</span><span>]</span></span> <span class="giallo-l"></span> <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"> NormalizedTransaction</span><span>:</span></span> <span class="giallo-l"><span> signer_address</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> signer_nonce</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> max_priority_fee_per_gas</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> max_fee_per_gas</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> gas_limit</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> destination</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> amount</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> payload</span><span>:</span><span class="z-support"> bytes</span><span class="z-keyword"> =</span><span class="z-support"> bytes</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> access_list</span><span>:</span><span> List</span><span>[</span><span>Tuple</span><span>[</span><span class="z-support">int</span><span>,</span><span> List</span><span>[</span><span class="z-support">int</span><span>]</span><span>]</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">list</span><span>)</span></span> <span class="giallo-l"></span> <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"> Block</span><span>:</span></span> <span class="giallo-l"><span> parent_hash</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> uncle_hashes</span><span>:</span><span> Sequence</span><span>[</span><span class="z-support">int</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">list</span><span>)</span></span> <span class="giallo-l"><span> author</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> state_root</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> transaction_root</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> transaction_receipt_root</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> logs_bloom</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> difficulty</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> number</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> gas_limit</span><span>:</span><span class="z-support"> int</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"> note the gas_limit is the gas_target * ELASTICITY_MULTIPLIER</span></span> <span class="giallo-l"><span> gas_used</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> timestamp</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> extra_data</span><span>:</span><span class="z-support"> bytes</span><span class="z-keyword"> =</span><span class="z-support"> bytes</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> proof_of_work</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> base_fee_per_gas</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <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"> Account</span><span>:</span></span> <span class="giallo-l"><span> address</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> balance</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> storage_root</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> code_hash</span><span>:</span><span class="z-support"> int</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-constant">INITIAL_BASE_FEE</span><span class="z-keyword"> =</span><span class="z-constant"> 1000000000</span></span> <span class="giallo-l"><span class="z-constant">INITIAL_FORK_BLOCK_NUMBER</span><span class="z-keyword"> =</span><span class="z-constant"> 10</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> TBD</span></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">ELASTICITY_MULTIPLIER</span><span class="z-keyword"> =</span><span class="z-constant"> 2</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_target</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 class="z-keyword"> //</span><span class="z-constant"> ELASTICITY_MULTIPLIER</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> on the fork block, don&#39;t account for the ELASTICITY_MULTIPLIER to avoid</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> unduly halving the gas target.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-constant"> INITIAL_FORK_BLOCK_NUMBER</span><span class="z-keyword"> ==</span><span> block</span><span>.</span><span>number</span><span>:</span></span> <span class="giallo-l"><span> parent_gas_target</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_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 class="z-keyword"> *</span><span class="z-constant"> ELASTICITY_MULTIPLIER</span><span> </span></span> <span class="giallo-l"></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> transactions</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>transactions</span><span>(</span><span>block</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 if the block used too much gas</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> block</span><span>.</span><span>gas_used</span><span class="z-keyword"> &lt;=</span><span> block</span><span>.</span><span>gas_limit</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">invalid block: too much gas used</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"> check if the block changed the gas limit too much</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> block</span><span>.</span><span>gas_limit</span><span class="z-keyword"> &lt;</span><span> parent_gas_limit</span><span class="z-keyword"> +</span><span> parent_gas_limit</span><span class="z-keyword"> //</span><span class="z-constant"> 1024</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">invalid block: gas limit increased too much</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> block</span><span>.</span><span>gas_limit</span><span class="z-keyword"> &gt;</span><span> parent_gas_limit</span><span class="z-keyword"> -</span><span> parent_gas_limit</span><span class="z-keyword"> //</span><span class="z-constant"> 1024</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">invalid block: gas limit decreased too much</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"> check if the gas limit is at least the minimum gas limit</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> block</span><span>.</span><span>gas_limit</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> 5000</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 if the base fee is correct</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-constant"> INITIAL_FORK_BLOCK_NUMBER</span><span class="z-keyword"> ==</span><span> block</span><span>.</span><span>number</span><span>:</span></span> <span class="giallo-l"><span> expected_base_fee_per_gas</span><span class="z-keyword"> =</span><span class="z-constant"> INITIAL_BASE_FEE</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> parent_gas_used</span><span class="z-keyword"> ==</span><span> parent_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_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_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_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_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_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 class="z-keyword"> assert</span><span> expected_base_fee_per_gas</span><span class="z-keyword"> ==</span><span> block</span><span>.</span><span>base_fee_per_gas</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">invalid block: base fee not correct</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"> execute transactions and do gas accounting</span></span> <span class="giallo-l"><span> cumulative_transaction_gas_used</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> unnormalized_transaction</span><span class="z-keyword"> in</span><span> transactions</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Note: this validates transaction signature and chain ID which must happen before we normalize below since normalized transactions don&#39;t include signature or chain ID</span></span> <span class="giallo-l"><span> signer_address</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>validate_and_recover_signer_address</span><span>(</span><span>unnormalized_transaction</span><span>)</span></span> <span class="giallo-l"><span> transaction</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>normalize_transaction</span><span>(</span><span>unnormalized_transaction</span><span>,</span><span> signer_address</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> signer</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>account</span><span>(</span><span>signer_address</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> signer</span><span>.</span><span>balance</span><span class="z-keyword"> -=</span><span> transaction</span><span>.</span><span>amount</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> signer</span><span>.</span><span>balance</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> 0</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">invalid transaction: signer does not have enough ETH to cover attached value</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> the signer must be able to afford the transaction</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> signer</span><span>.</span><span>balance</span><span class="z-keyword"> &gt;=</span><span> transaction</span><span>.</span><span>gas_limit</span><span class="z-keyword"> *</span><span> transaction</span><span>.</span><span>max_fee_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"> ensure that the user was willing to at least pay the base fee</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> transaction</span><span>.</span><span>max_fee_per_gas</span><span class="z-keyword"> &gt;=</span><span> block</span><span>.</span><span>base_fee_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"> Prevent impossibly large numbers</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> transaction</span><span>.</span><span>max_fee_per_gas</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">256</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Prevent impossibly large numbers</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> transaction</span><span>.</span><span>max_priority_fee_per_gas</span><span class="z-keyword"> &lt;</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">256</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> The total must be the larger of the two</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> transaction</span><span>.</span><span>max_fee_per_gas</span><span class="z-keyword"> &gt;=</span><span> transaction</span><span>.</span><span>max_priority_fee_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"> priority fee is capped because the base fee is filled first</span></span> <span class="giallo-l"><span> priority_fee_per_gas</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span>transaction</span><span>.</span><span>max_priority_fee_per_gas</span><span>,</span><span> transaction</span><span>.</span><span>max_fee_per_gas</span><span class="z-keyword"> -</span><span> block</span><span>.</span><span>base_fee_per_gas</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> signer pays both the priority fee and the base fee</span></span> <span class="giallo-l"><span> effective_gas_price</span><span class="z-keyword"> =</span><span> priority_fee_per_gas</span><span class="z-keyword"> +</span><span> block</span><span>.</span><span>base_fee_per_gas</span></span> <span class="giallo-l"><span> signer</span><span>.</span><span>balance</span><span class="z-keyword"> -=</span><span> transaction</span><span>.</span><span>gas_limit</span><span class="z-keyword"> *</span><span> effective_gas_price</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> signer</span><span>.</span><span>balance</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> 0</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">invalid transaction: signer does not have enough ETH to cover gas</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span> gas_used</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>execute_transaction</span><span>(</span><span>transaction</span><span>,</span><span> effective_gas_price</span><span>)</span></span> <span class="giallo-l"><span> gas_refund</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>gas_limit</span><span class="z-keyword"> -</span><span> gas_used</span></span> <span class="giallo-l"><span> cumulative_transaction_gas_used</span><span class="z-keyword"> +=</span><span> gas_used</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> signer gets refunded for unused gas</span></span> <span class="giallo-l"><span> signer</span><span>.</span><span>balance</span><span class="z-keyword"> +=</span><span> gas_refund</span><span class="z-keyword"> *</span><span> effective_gas_price</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> miner only receives the priority fee; note that the base fee is not given to anyone (it is burned)</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>account</span><span>(</span><span>block</span><span>.</span><span>author</span><span>)</span><span>.</span><span>balance</span><span class="z-keyword"> +=</span><span> gas_used</span><span class="z-keyword"> *</span><span> priority_fee_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"> check if the block spent too much gas transactions</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> cumulative_transaction_gas_used</span><span class="z-keyword"> ==</span><span> block</span><span>.</span><span>gas_used</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">invalid block: gas_used does not equal total gas used in all transactions</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-keyword"> TODO</span><span class="z-comment">: verify account balances match block&#39;s account balances (via state root comparison)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-keyword"> TODO</span><span class="z-comment">: validate the rest of the block</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"> normalize_transaction</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> transaction</span><span>:</span><span> Transaction</span><span>,</span><span class="z-variable z-parameter z-function"> signer_address</span><span>:</span><span class="z-support"> int</span><span>)</span><span> -&gt;</span><span> NormalizedTransaction</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> legacy transactions</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> isinstance</span><span>(</span><span>transaction</span><span>,</span><span> TransactionLegacy</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> NormalizedTransaction</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> signer_address</span><span class="z-keyword"> =</span><span> signer_address</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> signer_nonce</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>signer_nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> gas_limit</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>gas_limit</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> max_priority_fee_per_gas</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>gas_price</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> max_fee_per_gas</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>gas_price</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> destination</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>destination</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> amount</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>amount</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> payload</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> access_list</span><span class="z-keyword"> =</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"> 2930 transactions</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span class="z-support"> isinstance</span><span>(</span><span>transaction</span><span>,</span><span> Transaction2930Envelope</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> NormalizedTransaction</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> signer_address</span><span class="z-keyword"> =</span><span> signer_address</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> signer_nonce</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>signer_nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> gas_limit</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>gas_limit</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> max_priority_fee_per_gas</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>gas_price</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> max_fee_per_gas</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>gas_price</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> destination</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>destination</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> amount</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>amount</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> payload</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>payload</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> access_list</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>access_list</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"> 1559 transactions</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span class="z-support"> isinstance</span><span>(</span><span>transaction</span><span>,</span><span> Transaction1559Envelope</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> NormalizedTransaction</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> signer_address</span><span class="z-keyword"> =</span><span> signer_address</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> signer_nonce</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>signer_nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> gas_limit</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>gas_limit</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> max_priority_fee_per_gas</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>max_priority_fee_per_gas</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> max_fee_per_gas</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>max_fee_per_gas</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> destination</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>destination</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> amount</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>amount</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> payload</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>payload</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> access_list</span><span class="z-keyword"> =</span><span> transaction</span><span>.</span><span>payload</span><span>.</span><span>access_list</span><span>,</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span class="z-support"> Exception</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">invalid transaction: unexpected number of items</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-entity z-name"> @</span><span class="z-entity z-name">abstractmethod</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> parent</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> Block</span><span>:</span><span class="z-keyword"> pass</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> @</span><span class="z-entity z-name">abstractmethod</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> block_hash</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-support"> int</span><span>:</span><span class="z-keyword"> pass</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> @</span><span class="z-entity z-name">abstractmethod</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> transactions</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> Sequence</span><span>[</span><span>Transaction</span><span>]</span><span>:</span><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"> effective_gas_price is the value returned by the GASPRICE (0x3a) opcode</span></span> <span class="giallo-l"><span class="z-entity z-name"> @</span><span class="z-entity z-name">abstractmethod</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> execute_transaction</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> transaction</span><span>:</span><span> NormalizedTransaction</span><span>,</span><span class="z-variable z-parameter z-function"> effective_gas_price</span><span>:</span><span class="z-support"> int</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span><span class="z-keyword"> pass</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> @</span><span class="z-entity z-name">abstractmethod</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> validate_and_recover_signer_address</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> transaction</span><span>:</span><span> Transaction</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span><span class="z-keyword"> pass</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> @</span><span class="z-entity z-name">abstractmethod</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> account</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> address</span><span>:</span><span class="z-support"> int</span><span>)</span><span> -&gt;</span><span> Account</span><span>:</span><span class="z-keyword"> pass</span></span></code></pre><h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Legacy Ethereum transactions will still work and be included in blocks, but they will not benefit directly from the new pricing system. This is due to the fact that upgrading from legacy transactions to new transactions results in the legacy transaction's <code>gas_price </code> entirely being consumed either by the <code>base_fee_per_gas</code> and the <code>priority_fee_per_gas</code>.</p> <h3 id="block-hash-changing">Block Hash Changing</h3> <p>The datastructure that is passed into keccak256 to calculate the block hash is changing, and all applications that are validating blocks are valid or using the block hash to verify block contents will need to be adapted to support the new datastructure (one additional item). If you only take the block header bytes and hash them you should still correctly get a hash, but if you construct a block header from its constituent elements you will need to add in the new one at the end.</p> <h3 id="gasprice">GASPRICE</h3> <p>Previous to this change, <code>GASPRICE</code> represented both the ETH paid by the signer per gas for a transaction as well as the ETH received by the miner per gas. As of this change, <code>GASPRICE</code> now only represents the amount of ETH paid by the signer per gas, and the amount a miner was paid for the transaction is no longer accessible directly in the EVM.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="increased-max-block-size-complexity">Increased Max Block Size/Complexity</h3> <p>This EIP will increase the maximum block size, which could cause problems if miners are unable to process a block fast enough as it will force them to mine an empty block. Over time, the average block size should remain about the same as without this EIP, so this is only an issue for short term size bursts. It is possible that one or more clients may handle short term size bursts poorly and error (such as out of memory or similar) and client implementations should make sure their clients can appropriately handle individual blocks up to max size.</p> <h3 id="transaction-ordering">Transaction Ordering</h3> <p>With most people not competing on priority fees and instead using a baseline fee to get included, transaction ordering now depends on individual client internal implementation details such as how they store the transactions in memory. It is recommended that transactions with the same priority fee be sorted by time the transaction was received to protect the network from spamming attacks where the attacker throws a bunch of transactions into the pending pool in order to ensure that at least one lands in a favorable position. Miners should still prefer higher gas premium transactions over those with a lower gas premium, purely from a selfish mining perspective.</p> <h3 id="miners-mining-empty-blocks">Miners Mining Empty Blocks</h3> <p>It is possible that miners will mine empty blocks until such time as the base fee is very low and then proceed to mine half full blocks and revert to sorting transactions by the priority fee. While this attack is possible, it is not a particularly stable equilibrium as long as mining is decentralized. Any defector from this strategy will be more profitable than a miner participating in the attack for as long as the attack continues (even after the base fee reached 0). Since any miner can anonymously defect from a cartel, and there is no way to prove that a particular miner defected, the only feasible way to execute this attack would be to control 50% or more of hashing power. If an attacker had exactly 50% of hashing power, they would make no Ether from priority fee while defectors would make double the Ether from priority fees. For an attacker to turn a profit, they need to have some amount over 50% hashing power, which means they can instead execute double spend attacks or simply ignore any other miners which is a far more profitable strategy.</p> <p>Should a miner attempt to execute this attack, we can simply increase the elasticity multiplier (currently 2x) which requires they have even more hashing power available before the attack can even be theoretically profitable against defectors.</p> <h3 id="eth-burn-precludes-fixed-supply">ETH Burn Precludes Fixed Supply</h3> <p>By burning the base fee, we can no longer guarantee a fixed Ether supply. This could result in economic instability as the long term supply of ETH will no longer be constant over time. While a valid concern, it is difficult to quantify how much of an impact this will have. If more is burned on base fee than is generated in mining rewards then ETH will be deflationary and if more is generated in mining rewards than is burned then ETH will be inflationary. Since we cannot control user demand for block space, we cannot assert at the moment whether ETH will end up inflationary or deflationary, so this change causes the core developers to lose some control over Ether's long term quantity.</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-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:49:27+00:00 Charles Cooperhttps://github.com/charles-cooper https://wg-eips.ritovision.com/1898/

Add `blockHash` option to JSON-RPC methods that currently support defaultBlock parameter.

<h2 id="abstract">Abstract</h2> <p>For JSON-RPC methods which currently accept a default block parameter, additionally allow the parameter to be a block hash.</p> <p>This EIP can be considered a generalization of <a href="https://wg-eips.ritovision.com/234/">EIP-234</a>. It would enable clients to unambiguously specify the block they want to query for certain JSON-RPC methods, even if the block is not in the canonical chain. This allows clients to maintain a coherent picture of blockchain state that they are interested in, even in the presence of reorgs, without requiring that the node maintain a persistent connection with the client or store any client-specific state.</p> <h2 id="specification">Specification</h2> <p>The following JSON-RPC methods are affected:</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>The following options, quoted from the Ethereum JSON-RPC spec, are currently possible for the defaultBlock parameter:</p> <blockquote> <ul> <li>HEX String - an integer block number</li> <li>String "earliest" for the earliest/genesis block</li> <li>String "latest" - for the latest canonical block</li> <li>String "pending" - for the pending state/transactions</li> <li>String "safe" - for the most recent safe block</li> <li>String "finalized" - for the most recent finalized block</li> </ul> </blockquote> <p>Since there is no way to clearly distinguish between a DATA parameter and a QUANTITY parameter, this EIP proposes a new scheme for the block parameter. The following option is additionally allowed:</p> <ul> <li>OBJECT <ul> <li><code>blockNumber</code>: QUANTITY - a block number</li> <li><code>blockHash</code>: DATA - a block hash</li> </ul> </li> </ul> <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>).</p> <p>If the tag is <code>blockHash</code>, an additional boolean field may be supplied to the block parameter, <code>requireCanonical</code>, which defaults to <code>false</code> and defines whether the block must be a canonical block according to the callee. If <code>requireCanonical</code> is <code>false</code>, the callee should raise a JSON-RPC error only if the block is not found (as described above). If <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> <p>To maintain backwards compatibility, the block number MAY be specified either as a hex string or using the new block parameter scheme. In other words, the following are equivalent for the default block parameter:</p> <ul> <li><code>"earliest"</code></li> <li><code>"0x0"</code></li> <li><code>{ "blockNumber": "0x0" }</code></li> <li><code>{ "blockHash": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3" }</code> (hash of the genesis block on the Ethereum main chain)</li> <li><code>{ "blockHash": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3", "requireCanonical": true }</code></li> <li><code>{ "blockHash": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3", "requireCanonical": false }</code></li> </ul> <h2 id="rationale">Rationale</h2> <p>Currently, the state-querying JSON-RPC methods specified above have no option to unambiguously specify which block to query the state for. This can cause issues for applications which need to make multiple calls to the RPC. For instance, a wallet which just executed a transfer may want to display the balances of both the sender and recipient. If there is a re-org in between when the balance of the sender is queried via <code>eth_getBalance</code> and when the balance of the recipient is queried, the balances may not reconcile. As a slightly more complicated example, the UI for a decentralized exchange (which hosts orders on-chain) may walk a list of orders by calling <code>eth_call</code> for each of them to get the order data. Another type of use case is where an application needs to make a decision based on multiple pieces of state, e.g. a payout predicated on simultaneous ownership of two NFTs.</p> <p>In order to ensure that the state is coherent (i.e., <code>eth_call</code> was called with exactly the same block for every call), the application may currently use one of several strategies:</p> <ul> <li>Decide on a block number to use (e.g., the latest block number known to the application). After each <code>eth_call</code> using that block number, call <code>eth_getBlockByNumber</code>, also with that block number. If the block hash does not match the known hash for that block number, rollback the current activity and retry from the beginning. This adds <code>O(n)</code> invocations as baseline overhead and another <code>O(n)</code> invocations for every retry needed. Moreover, there is no way to detect the (unlikely but possible) case that the relevant block was reorged out before <code>eth_call</code>, and then reorged back in before <code>eth_getBlockByNumber</code>.</li> <li>Rely on logs, which <em>can</em> be queried unambiguously thanks to the <code>blockHash</code> parameter. However, this requires semantic support from the smart contract; if the smart contract does not emit appropriate events, the client will not be able to reconstruct the specific state it is interested in.</li> <li>Rely on non-standard extensions like <code>parity_subscribe</code>. This requires a persistent connection between the client and node (via IPC or websockets), increases coupling between the client and the node, and cannot handle use cases where there are dependencies between invocations of <code>eth_call</code>, for example, walking a linked list.</li> </ul> <p>Allowing <code>eth_call</code> and friends to unambiguously specify the block to be queried give the application developer a robust and intuitive way to solve these problems. Multiple sequential queries will query the same state, enabling the application developer to not worry about inconsistencies in their view of the blockchain state.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Backwards compatible.</p> <h2 id="test-cases">Test Cases</h2> <ul> <li><code>eth_getStorageAt [ "0x&lt;address&gt;", { "blockNumber": "0x0" }</code> -&gt; return storage at given address in genesis block</li> <li><code>eth_getStorageAt [ "0x&lt;address&gt;", { "blockHash": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3" }</code> -&gt; return storage at given address in genesis block</li> <li><code>eth_getStorageAt [ "0x&lt;address&gt;", { "blockHash": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3", "requireCanonical": false }</code> -&gt; return storage at given address in genesis block</li> <li><code>eth_getStorageAt [ "0x&lt;address&gt;", { "blockHash": "0xd4e56740f876aef8c010b86a40d5f56745a118d0906a34e69aec8c0db1cb8fa3", "requireCanonical": true }</code> -&gt; return storage at given address in genesis block</li> <li><code>eth_getStorageAt [ "0x&lt;address&gt;", { "blockHash": "0x&lt;non-existent-block-hash&gt;" }</code> -&gt; raise block-not-found error</li> <li><code>eth_getStorageAt [ "0x&lt;address&gt;", { "blockHash": "0x&lt;non-existent-block-hash&gt;", "requireCanonical": false }</code> -&gt; raise block-not-found error</li> <li><code>eth_getStorageAt [ "0x&lt;address&gt;", { "blockHash": "0x&lt;non-existent-block-hash&gt;", "requireCanonical": true }</code> -&gt; raise block-not-found error</li> <li><code>eth_getStorageAt [ "0x&lt;address&gt;", { "blockHash": "0x&lt;non-canonical-block-hash&gt;" }</code> -&gt; return storage at given address in specified block</li> <li><code>eth_getStorageAt [ "0x&lt;address&gt;", { "blockHash": "0x&lt;non-canonical-block-hash&gt;", "requireCanonical": false }</code> -&gt; return storage at given address in specified block</li> <li><code>eth_getStorageAt [ "0x&lt;address&gt;", { "blockHash": "0x&lt;non-canonical-block-hash&gt;", "requireCanonical": true }</code> -&gt; raise block-not-canonical error</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> 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-31T00:00:00+00:00 2026-02-11T14:49:27+00:00 Gregory Markougreg@chainsafe.io Kevin Owockikevin@gitcoin.co Lane Rettiglane@ethereum.org https://wg-eips.ritovision.com/1890/ <h1 id="commitment-to-sustainable-ecosystem-funding">Commitment to Sustainable Ecosystem Funding</h1> <h2 id="simple-summary">Simple Summary</h2> <p>Ethereum currently provides a block reward to proof of work miners every block, but it does not capture any block rewards for ecosystem funding. This EIP adds a simple mechanism for capturing a portion of block rewards for ecosystem funding as a credible commitment to doing so in future, but it does not actually capture any such rewards.</p> <h2 id="abstract">Abstract</h2> <p>A mechanism that allows specification of two parameters, a beneficiary address and a per-block reward denominated in wei, that allows a portion of block rewards to be captured for the purpose of ecosystem funding. Both values are set to zero.</p> <h2 id="motivation">Motivation</h2> <p>In order for Ethereum to succeed, it needs talented, motivated researchers and developers to continue to develop and maintain the platform. Those talented researchers and developers deserve to be paid fairly for their work. At present there is no mechanism in the Ethereum ecosystem that rewards R&amp;D teams fairly for their work on the platform.</p> <p>We recognize that, while technically trivial, the real challenge in inflation-based funding is social: how to fairly capture, govern, and distribute block rewards. It will take time to work out the answer to these questions. For this reason, this EIP only seeks to make a credible commitment on the part of core developers to securing the funding they need to keep Ethereum alive and healthy by adding a mechanism to do so, but the actual amount of rewards captured remains at zero, i.e., there is no change at present to Ethereum’s economics. Raising the amount captured above zero would require a future EIP.</p> <h2 id="specification">Specification</h2> <p>Two new constants are introduced: BENEFICIARY_ADDRESS, an Address, and DEVFUND_BLOCK_REWARD, an amount denominated in wei. Both are set to zero.</p> <p>Beginning with block ISTANBUL_BLOCK_HEIGHT, DEVFUND_BLOCK_REWARD wei is added to the balance of BENEFICIARY_ADDRESS at each block.</p> <p>We may optionally add another constant, DECAY_FACTOR, which specifies a linear or exponenential decay factor that reduces the reward at every block &gt; ISTANBUL_BLOCK_HEIGHT until it decays to zero. For simplicity, it has been omitted from this proposal.</p> <h2 id="rationale">Rationale</h2> <p>We believe that the technical design of this EIP is straightforward. The social rationale is explained in <a rel="external" href="https://medium.com/gitcoin/funding-open-source-in-the-blockchain-era-8ded753bf05f">this article</a>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP has no impact on backwards compatibility.</p> <h2 id="test-cases">Test Cases</h2> <p>This EIP makes no changes to existing state transitions. Existing consensus tests should be sufficient.</p> <h2 id="implementation">Implementation</h2> <p>Reference implementations are included for the Trinity, go-ethereum, and parity 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> 2019-03-28T00:00:00+00:00 2026-02-11T14:49:28+00:00 Martin Holst Swendehttps://github.com/holiman https://wg-eips.ritovision.com/1884/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP proposes repricing certain opcodes, to obtain a good balance between gas expenditure and resource consumption.</p> <h2 id="abstract">Abstract</h2> <p>The growth of the Ethereum state has caused certain opcodes to be more resource-intensive at this point than they were previously. This EIP proposes to raise the <code>gasCost</code> for those opcodes.</p> <h2 id="motivation">Motivation</h2> <p>An imbalance between the price of an operation and the resource consumption (CPU time, memory etc) has several drawbacks:</p> <ul> <li>It could be used for attacks, by filling blocks with underpriced operations which causes excessive block processing time.</li> <li>Underpriced opcodes cause a skewed block gas limit, where sometimes blocks finish quickly but other blocks with similar gas use finish slowly.</li> </ul> <p>If operations are well-balanced, we can maximise the block gaslimit and have a more stable processing time.</p> <h2 id="specification">Specification</h2> <p>At block <code>N</code>,</p> <ul> <li>The <code>SLOAD</code> (<code>0x54</code>) operation changes from <code>200</code> to <code>800</code> gas,</li> <li>The <code>BALANCE</code> (<code>0x31</code>) operation changes from <code>400</code> to <code>700</code> gas,</li> <li>The <code>EXTCODEHASH</code> (<code>0x3F</code>) operation changes from <code>400</code> to <code>700</code> gas,</li> <li>A new opcode, <code>SELFBALANCE</code> is introduced at <code>0x47</code>. <ul> <li><code>SELFBALANCE</code> pops <code>0</code> arguments off the stack,</li> <li><code>SELFBALANCE</code> pushes the <code>balance</code> of the current address to the stack,</li> <li><code>SELFBALANCE</code> is priced as <code>GasFastStep</code>, at <code>5</code> gas.</li> </ul> </li> </ul> <h2 id="rationale">Rationale</h2> <p>Here are two charts, taken from a full sync using Geth. The execution time was measured for every opcode, and aggregated for 10K blocks. These bar charts show the top 25 'heavy' opcodes in the ranges 5M to 6M and 6M to 7M:</p> <p><img src="https://wg-eips.ritovision.com/1884/./assets/run3.total-bars-5.png" alt="bars1" /> <img src="https://wg-eips.ritovision.com/1884/./assets/run3.total-bars-6.png" alt="bars2" /></p> <p>Note: It can also be seen that the <code>SLOAD</code> moves towards the top position. The <code>GASPRICE</code> (<code>0x3a</code>) opcode has position one which I believe can be optimized away within the client -- which is not the case with <code>SLOAD</code>/<code>BALANCE</code>.</p> <p>Here is another chart, showing a full sync with Geth. It represents the blocks <code>0</code> to <code>5.7M</code>, and highlights what the block processing time is spent on.</p> <p><img src="https://wg-eips.ritovision.com/1884/./assets/geth_processing.png" alt="geth" /></p> <p>It can be seen that <code>storage_reads</code> and <code>account_reads</code> are the two most significant factors contributing to the block processing time.</p> <h3 id="sload"><code>SLOAD</code></h3> <p><code>SLOAD</code> was repriced at <a href="https://wg-eips.ritovision.com/150/">EIP-150</a>, from <code>50</code> to <code>200</code>. The following graph shows a go-ethereum full sync, where each data point represents 10K blocks. During those 10K blocks, the execution time for the opcode was aggregated.</p> <p><img src="https://wg-eips.ritovision.com/1884/./assets/SLOAD-run3.png" alt="graph" /></p> <p>It can be seen that the repricing at <a href="https://wg-eips.ritovision.com/150/">EIP-150</a> caused a steep drop, from around <code>67</code> to <code>23</code>. Around block <code>5M</code>, it started reaching pre-<a href="https://wg-eips.ritovision.com/150/">EIP-150</a> levels, and at block <code>7M</code> it was averaging on around <code>150</code> - more than double pre-eip-150 levels.</p> <p>Increasing the cost of <code>SLOAD</code> by <code>4</code> would bring it back down to around <code>40</code>. It is to be expected that it will rise again in the future, and may need future repricing, unless state clearing efforts are implemented before that happens.</p> <h3 id="balance"><code>BALANCE</code></h3> <p><code>BALANCE</code> (a.k.a <code>EXTBALANCE</code>) is an operation which fetches data from the state trie. It was repriced at <a href="https://wg-eips.ritovision.com/150/">EIP-150</a> from <code>20</code> to <code>400</code>.</p> <p><img src="https://wg-eips.ritovision.com/1884/./assets/BALANCE-run3.png" alt="graph" /></p> <p>It is comparable to <code>EXTCODESIZE</code> and <code>EXTCODEHASH</code>, which are priced at <code>700</code> already.</p> <p>It has a built-in high variance, since it is often used for checking the balance of <code>this</code>, which is an inherently cheap operation, however, it can be used to lookup the balance of arbitrary account which often require trie (disk) access.</p> <p>In hindsight, it might have been a better choice to have two opcodes: <code>EXTBALANCE(address)</code> and <code>SELFBALANCE</code>, and have two different prices.</p> <ul> <li>This EIP proposes to extend the current opcode set. <ul> <li>Unfortunately, the opcode span <code>0x3X</code> is already full, hence the suggestion to place <code>SELFBALANCE</code> in the <code>0x4X</code> range.</li> <li>As for why it is priced at <code>5</code> (<code>GasFastStep</code>) instead of <code>2</code> (<code>GasQuickStep</code>), like other similar operations: the EVM execution engine still needs a lookup into the (cached) trie, and <code>balance</code>, unlike <code>gasPrice</code> or <code>timeStamp</code>, is not constant during the execution, so it has a bit more inherent overhead.</li> </ul> </li> </ul> <h3 id="extcodehash"><code>EXTCODEHASH</code></h3> <p><code>EXTCODEHASH</code> was introduced in Constantinople, with <a href="https://wg-eips.ritovision.com/1052/">EIP-1052</a>. It was priced at <code>400</code> with the reasoning:</p> <blockquote> <p>The gas cost is the same as the gas cost for the <code>BALANCE</code> opcode because the execution of the <code>EXTCODEHASH</code> requires the same account lookup as in <code>BALANCE</code>.</p> </blockquote> <p>Ergo, if we increase <code>BALANCE</code>, we should also increase <code>EXTCODEHASH</code></p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The changes require a hardfork. The changes have the following consequences:</p> <ul> <li>Certain calls will become more expensive.</li> <li>Default-functions which access the storage and may in some cases require more than<code>2300</code> gas (the minimum gas that is always available in calls).</li> <li>Contracts that assume a certain fixed gas cost for calls (or internal sections) may cease to function. <ul> <li>A fixed gas cost is specified in <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> and implementations of this interface do use the affected opcodes. <ul> <li>The ERC-165 method <code>supportsInterface</code> must return a <code>bool</code> and use at most <code>30,000</code> gas.</li> <li>The two example implementations from the EIP were, at the time of writing <ol> <li><code>586</code> gas for any input, and</li> <li><code>236</code> gas, but increases linearly with a higher number of supported interfaces</li> </ol> </li> </ul> </li> <li>It is unlikely that any ERC-165 <code>supportsInterface</code> implementation will go above <code>30.000</code> gas. That would require that the second variant is used, and thirty:ish interfaces are supported.</li> <li>However, these operations have already been repriced earlier, so there is a historical precedent that 'the gascost for these operations may change', which should have prevented such fixed-gas-cost assumptions from being implemented.</li> </ul> </li> </ul> <p>I expect that certain patterns will be less used, for example the use of multiple modifiers which <code>SLOAD</code>s the same opcode will be merged into one. It may also lead to less <code>log</code> operations containing <code>SLOAD</code>ed values that are not strictly necessary.</p> <h2 id="test-cases">Test Cases</h2> <p>Testcases that should be implemented:</p> <ul> <li>Test that <code>selfbalance == balance(address)</code>,</li> <li>Test that <code>balance(this)</code> costs as before,</li> <li>Test that <code>selfbalance</code> does not pop from stack</li> <li>Gascost verification of <code>SLOAD</code>, <code>EXTCODEHASH</code> and <code>SELFBALANCE</code></li> <li>Verify that <code>SELFBALANCE</code> is invalid before Istanbul</li> </ul> <p>Some testcases have been implemented as statetests at https://github.com/holiman/IstanbulTests/tree/master/GeneralStateTests</p> <h2 id="implementation">Implementation</h2> <p>This EIP has not yet been implemented in any client. Both these opcodes have been repriced before, and the client internals for managing reprices are already in place.</p> <h3 id="selfbalance"><code>SELFBALANCE</code></h3> <p>This is the implementation for the new opcode in go-ethereum:</p> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">func</span><span class="z-entity z-name"> opSelfBalance</span><span>(</span><span class="z-variable">pc</span><span class="z-keyword"> *</span><span class="z-storage z-type">uint64</span><span>,</span><span class="z-variable"> interpreter</span><span class="z-keyword"> *</span><span class="z-entity z-name">EVMInterpreter</span><span>,</span><span class="z-variable"> contract</span><span class="z-keyword"> *</span><span class="z-entity z-name">Contract</span><span>,</span><span class="z-variable"> memory</span><span class="z-keyword"> *</span><span class="z-entity z-name">Memory</span><span>,</span><span class="z-variable"> stack</span><span class="z-keyword"> *</span><span class="z-entity z-name">Stack</span><span>)</span><span> (</span><span>[</span><span>]</span><span class="z-storage z-type">byte</span><span>,</span><span class="z-storage z-type"> error</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> stack</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-variable z-other">interpreter</span><span>.</span><span class="z-variable z-other">intPool</span><span>.</span><span class="z-entity z-name">get</span><span>(</span><span>)</span><span>.</span><span class="z-entity z-name">Set</span><span>(</span><span class="z-variable z-other">interpreter</span><span>.</span><span class="z-variable z-other">evm</span><span>.</span><span class="z-variable z-other">StateDB</span><span>.</span><span class="z-entity z-name">GetBalance</span><span>(</span><span class="z-variable z-other">contract</span><span>.</span><span class="z-entity z-name">Address</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> nil</span><span>,</span><span class="z-constant"> nil</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h2 id="security-considerations">Security considerations</h2> <ul> <li>See backwards compatibility section.</li> <li>There are no special edgecases regarding <code>SELFBALANCE</code>, if we define it as <code>BALANCE</code> with <code>address</code> instead of popping an address from the stack -- since <code>BALANCE</code> is already well-defined.</li> <li>It should be investigated if Solidity contains any hardcoded expectations on the gas cost of these operations.</li> <li>In many cases, a recipient of <code>ether</code> from a <code>CALL</code> will want to issue a <code>LOG</code>. The <code>LOG</code> operation costs <code>375</code> plus <code>375</code> per topic. If the <code>LOG</code> also wants to do an <code>SLOAD</code>, this change may make some such transfers fail.</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-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-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Richard Moorehttps://github.com/ricmoo Nick Johnsonnick@ethereum.org https://wg-eips.ritovision.com/2098/

A compact representation of an Ethereum Signature.

<h2 id="abstract">Abstract</h2> <p>The secp256k1 curve permits the computation of the public key of signed digest when coupled with a signature, which is used implicitly to establish the origin of a transaction from an Externally Owned Account as well as on-chain in EVM contracts for example, in meta-transactions and multi-sig contracts.</p> <p>Currently signatures require 65 bytes to represent, which when aligned to 256-bit words, requires 96 bytes (with 31 zero bytes injected). The yParity in RLP-encoded transactions also require (on average) 1.5 bytes. With compact signatures, this can be reduced to 64 bytes, which remains 64 bytes when word-aligned, and in the case of RLP-encoded transactions saves the 1.5 bytes required for the yParity.</p> <h2 id="motivation">Motivation</h2> <p>The motivations for a compact representation are to simplify handling transactions in client code, reduce gas costs and reduce transaction sizes.</p> <h2 id="specification">Specification</h2> <p>A secp256k1 signature is made up of 3 parameters, <code>r</code>, <code>s</code> and <code>yParity</code>. The <code>r</code> represents the <code>x</code> component on the curve (from which the <code>y</code> can be computed), and the <code>s</code> represents the challenge solution for signing by a private key. Due to the symmetric nature of an elliptic curve, a <code>yParity</code> is required, which indicates which of the 2 possible solutions was intended, by indicating its parity (odd-ness).</p> <p>Two key observations are required to create a compact representation.</p> <p>First, the <code>yParity</code> parameter is always either 0 or 1 (canonically the values used have historically been 27 and 28, as these values didn't collide with other binary prefixes used in Bitcoin).</p> <p>Second, the top bit of the <code>s</code> parameters is <strong>always</strong> 0, due to the use of canonical signatures which flip the solution parity to prevent negative values, which was introduced as <a href="https://wg-eips.ritovision.com/2/">a constraint in Homestead</a>.</p> <p>So, we can hijack the top bit in the <code>s</code> parameter to store the value of <code>yParity</code>, resulting in:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[256-bit r value][1-bit yParity value][255-bit s value]</span></span></code></pre><h3 id="example-implementation-in-python">Example Implementation In Python</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"> Assume yParity is 0 or 1, normalized from the canonical 27 or 28</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> to_compact</span><span>(</span><span class="z-variable z-parameter z-function">r</span><span>,</span><span class="z-variable z-parameter z-function"> s</span><span>,</span><span class="z-variable z-parameter z-function"> yParity</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">r</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> r</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">yParityAndS</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> (</span><span>yParity</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 255</span><span>)</span><span class="z-keyword"> |</span><span> s</span></span> <span class="giallo-l"><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"> to_canonical</span><span>(</span><span class="z-variable z-parameter z-function">r</span><span>,</span><span class="z-variable z-parameter z-function"> yParityAndS</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">r</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> r</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">s</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> yParityAndS</span><span class="z-keyword"> &amp;</span><span> (</span><span>(</span><span class="z-constant">1</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 255</span><span>)</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-string"> &quot;</span><span class="z-string">yParity</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> (</span><span>yParityAndS</span><span class="z-keyword"> &gt;&gt;</span><span class="z-constant"> 255</span><span>)</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The compact representation proposed is simple to both compose and decompose in clients and in Solidity, so that it can be easily (and intuitively) supported, while reducing transaction sizes and gas costs.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The Compact Representation does not collide with canonical signature as it uses 2 parameters (r, yParityAndS) and is 64 bytes long while canonical signatures involve 3 separate parameters (r, s, yParity) and are 65 bytes long.</p> <h2 id="test-cases">Test Cases</h2> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Private Key: 0x1234567890123456789012345678901234567890123456789012345678901234</span></span> <span class="giallo-l"><span>Message: &quot;Hello World&quot;</span></span> <span class="giallo-l"><span>Signature:</span></span> <span class="giallo-l"><span> r: 0x68a020a209d3d56c46f38cc50a33f704f4a9a10a59377f8dd762ac66910e9b90</span></span> <span class="giallo-l"><span> s: 0x7e865ad05c4035ab5792787d4a0297a43617ae897930a6fe4d822b8faea52064</span></span> <span class="giallo-l"><span> v: 27</span></span> <span class="giallo-l"><span>Compact Signature:</span></span> <span class="giallo-l"><span> r: 0x68a020a209d3d56c46f38cc50a33f704f4a9a10a59377f8dd762ac66910e9b90</span></span> <span class="giallo-l"><span> yParityAndS: 0x7e865ad05c4035ab5792787d4a0297a43617ae897930a6fe4d822b8faea52064</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Private Key: 0x1234567890123456789012345678901234567890123456789012345678901234</span></span> <span class="giallo-l"><span>Message: &quot;It&#39;s a small(er) world&quot;</span></span> <span class="giallo-l"><span>Signature:</span></span> <span class="giallo-l"><span> r: 0x9328da16089fcba9bececa81663203989f2df5fe1faa6291a45381c81bd17f76</span></span> <span class="giallo-l"><span> s: 0x139c6d6b623b42da56557e5e734a43dc83345ddfadec52cbe24d0cc64f550793</span></span> <span class="giallo-l"><span> v: 28</span></span> <span class="giallo-l"><span>Compact Signature:</span></span> <span class="giallo-l"><span> r: 0x9328da16089fcba9bececa81663203989f2df5fe1faa6291a45381c81bd17f76</span></span> <span class="giallo-l"><span> yParityAndS: 0x939c6d6b623b42da56557e5e734a43dc83345ddfadec52cbe24d0cc64f550793 </span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>The ethers.js library <a rel="external" href="https://github.com/ethers-io/ethers.js/blob/ethers-v5-beta/packages/bytes/src.ts/index.ts#L323">supports this in v5</a> as an unofficial property of split signatures (i.e. <code>sig._vs</code>), but should be considered an internal property that may change at discretion of the community and any changes to this EIP.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no additional security concerns introduced by 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> 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 Jordi Baylinajordi@baylina.cat Jacques Dafflonmail@0xjac.com https://wg-eips.ritovision.com/1820/ <blockquote> <p>:information_source: <strong><a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> has superseded <a href="https://wg-eips.ritovision.com/820/">ERC-820</a>.</strong> :information_source:<br /> <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> fixes the incompatibility in the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> logic which was introduced by the Solidity 0.5 update.<br /> Have a look at the <a rel="external" href="https://github.com/ethereum/EIPs/issues/820#issuecomment-464109166">official announcement</a>, and the comments about the <a rel="external" href="https://github.com/ethereum/EIPs/issues/820#issuecomment-452465748">bug</a> and the <a rel="external" href="https://github.com/ethereum/EIPs/issues/820#issuecomment-454021564">fix</a>.<br /> Apart from this fix, <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> is functionally equivalent to <a href="https://wg-eips.ritovision.com/820/">ERC-820</a>.</p> <p>:warning: <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> MUST be used in lieu of <a href="https://wg-eips.ritovision.com/820/">ERC-820</a>. :warning:</p> </blockquote> <h2 id="simple-summary">Simple Summary</h2> <p>This standard defines a universal registry smart contract where any address (contract or regular account) can register which interface it supports and which smart contract is responsible for its implementation.</p> <p>This standard keeps backward compatibility with <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>.</p> <h2 id="abstract">Abstract</h2> <p>This standard defines a registry where smart contracts and regular accounts can publish which functionality they implement---either directly or through a proxy contract.</p> <p>Anyone can query this registry to ask if a specific address implements a given interface and which smart contract handles its implementation.</p> <p>This registry MAY be deployed on any chain and shares the same address on all chains.</p> <p>Interfaces with zeroes (<code>0</code>) as the last 28 bytes are considered <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interfaces, and this registry SHALL forward the call to the contract to see if it implements the interface.</p> <p>This contract also acts as an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> cache to reduce gas consumption.</p> <h2 id="motivation">Motivation</h2> <p>There have been different approaches to define pseudo-introspection in Ethereum. The first is <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> which has the limitation that it cannot be used by regular accounts. The second attempt is <a rel="external" href="https://github.com/ethereum/EIPs/issues/672">ERC-672</a> which uses reverse <a rel="external" href="https://ens.domains/">ENS</a>. Using reverse <a rel="external" href="https://ens.domains/">ENS</a> has two issues. First, it is unnecessarily complicated, and second, <a rel="external" href="https://ens.domains/">ENS</a> is still a centralized contract controlled by a multisig. This multisig theoretically would be able to modify the system.</p> <p>This standard is much simpler than <a rel="external" href="https://github.com/ethereum/EIPs/issues/672">ERC-672</a>, and it is <em>fully</em> decentralized.</p> <p>This standard also provides a <em>unique</em> address for all chains. Thus solving the problem of resolving the correct registry address for different chains.</p> <h2 id="specification">Specification</h2> <h3 id="erc-1820-registry-smart-contract"><a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> Registry Smart Contract</h3> <blockquote> <p>This is an exact copy of the code of the <a rel="external" href="https://github.com/0xjac/ERC1820/blob/master/contracts/ERC1820Registry.sol">ERC1820 registry smart contract</a>.</p> </blockquote> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/*</span><span class="z-comment"> ERC1820 Pseudo-introspection Registry Contract</span></span> <span class="giallo-l"><span class="z-comment"> * This standard defines a universal registry smart contract where any address (contract or regular account) can</span></span> <span class="giallo-l"><span class="z-comment"> * register which interface it supports and which smart contract is responsible for its implementation.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Written in 2019 by Jordi Baylina and Jacques Dafflon</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to</span></span> <span class="giallo-l"><span class="z-comment"> * this software to the public domain worldwide. This software is distributed without any warranty.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * You should have received a copy of the CC0 Public Domain Dedication along with this software. If not, see</span></span> <span class="giallo-l"><span class="z-comment"> * &lt;http://creativecommons.org/publicdomain/zero/1.0/&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-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-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-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-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-comment"> */</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.5.3</span><span>;</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> IV is value needed to have a vanity address starting with &#39;0x1820&#39;.</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> IV: 53759</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 interface a contract MUST implement if it is the implementer of</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> some (other) interface for any address other than itself.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC1820ImplementerInterface</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"> Indicates whether the contract implements the interface &#39;interfaceHash&#39; for the address &#39;addr&#39; or not.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> interfaceHash</span><span class="z-comment"> keccak256 hash of the name of the 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"> addr</span><span class="z-comment"> Address for which the contract will implement the interface</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"> ERC1820_ACCEPT_MAGIC</span><span class="z-comment"> only if the contract implements &#39;interfaceHash&#39; for the address &#39;addr&#39;.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canImplementInterfaceForAddress</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> interfaceHash</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-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> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC1820 Pseudo-introspection Registry Contract</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @author</span><span class="z-comment"> Jordi Baylina and Jacques Dafflon</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> This contract is the official implementation of the ERC1820 Registry.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> For more details, see https://eips.ethereum.org/EIPS/eip-1820</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC1820Registry</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"> ERC165 Invalid ID.</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"> internal</span><span> INVALID_ID </span><span class="z-keyword">=</span><span class="z-constant"> 0xffffffff</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"> Method ID for the ERC165 supportsInterface method (= `bytes4(keccak256(&#39;supportsInterface(bytes4)&#39;))`).</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"> internal</span><span> ERC165ID </span><span class="z-keyword">=</span><span class="z-constant"> 0x01ffc9a7</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"> Magic value which is returned if a contract implements an interface on behalf of some other address.</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"> internal</span><span> ERC1820_ACCEPT_MAGIC </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;ERC1820_ACCEPT_MAGIC&quot;</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"> mapping from addresses and interface hashes to their implementers.</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">bytes32</span><span class="z-keyword"> =&gt;</span><span class="z-support"> address</span><span>)</span><span>)</span><span class="z-storage z-type"> internal</span><span> interfaces</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"> mapping from addresses to their manager.</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"> internal</span><span> managers</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"> flag for each address and erc165 interface to indicate if it is cached.</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">bytes4</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bool</span><span>)</span><span>)</span><span class="z-storage z-type"> internal</span><span> erc165Cached</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"> Indicates a contract is the &#39;implementer&#39; of &#39;interfaceHash&#39; for &#39;addr&#39;.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> InterfaceImplementerSet</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> addr</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> interfaceHash</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> implementer</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"> Indicates &#39;newManager&#39; is the address of the new manager for &#39;addr&#39;.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ManagerChanged</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> addr</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> newManager</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 implements an interface and through which 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"> _addr</span><span class="z-comment"> Address being queried for the implementer of an interface.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (If &#39;_addr&#39; is the zero address then &#39;msg.sender&#39; is assumed.)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _interfaceHash</span><span class="z-comment"> Keccak256 hash of the name of the interface as a string.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> E.g., &#39;web3.utils.keccak256(&quot;ERC777TokensRecipient&quot;)&#39; for the &#39;ERC777TokensRecipient&#39; interface.</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 contract which implements the interface &#39;_interfaceHash&#39; for &#39;_addr&#39;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> or &#39;0&#39; if &#39;_addr&#39; did not register an implementer for this interface.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getInterfaceImplementer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addr</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _interfaceHash</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-support"> address</span><span> addr </span><span class="z-keyword">=</span><span> _addr </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> _addr</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-entity z-name">isERC165Interface</span><span>(</span><span>_interfaceHash</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span> erc165InterfaceHash </span><span class="z-keyword">=</span><span class="z-support"> bytes4</span><span>(</span><span>_interfaceHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> implementsERC165Interface</span><span>(</span><span>addr</span><span>,</span><span> erc165InterfaceHash</span><span>)</span><span class="z-keyword"> ?</span><span> addr </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 class="z-keyword"> return</span><span> interfaces</span><span>[</span><span>addr</span><span>]</span><span>[</span><span>_interfaceHash</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"> @notice</span><span class="z-comment"> Sets the contract which implements a specific interface for an address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Only the manager defined for that address can set it.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (Each address is the manager for itself until it sets a new manager.)</span></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"> Address for which to set the interface.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (If &#39;_addr&#39; is the zero address then &#39;msg.sender&#39; is assumed.)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _interfaceHash</span><span class="z-comment"> Keccak256 hash of the name of the interface as a string.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> E.g., &#39;web3.utils.keccak256(&quot;ERC777TokensRecipient&quot;)&#39; for the &#39;ERC777TokensRecipient&#39; 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"> _implementer</span><span class="z-comment"> Contract address implementing &#39;_interfaceHash&#39; for &#39;_addr&#39;.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setInterfaceImplementer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addr</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _interfaceHash</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _implementer</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> addr </span><span class="z-keyword">=</span><span> _addr </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> _addr</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">getManager</span><span>(</span><span>addr</span><span>)</span><span class="z-keyword"> ==</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span class="z-string"> &quot;Not the manager&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-keyword">!</span><span class="z-entity z-name">isERC165Interface</span><span>(</span><span>_interfaceHash</span><span>)</span><span>,</span><span class="z-string"> &quot;Must not be an ERC165 hash&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_implementer </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"> &amp;&amp;</span><span> _implementer </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-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC1820ImplementerInterface</span><span>(</span><span>_implementer</span><span>)</span></span> <span class="giallo-l"><span> .</span><span class="z-entity z-name">canImplementInterfaceForAddress</span><span>(</span><span>_interfaceHash</span><span>,</span><span> addr</span><span>)</span><span class="z-keyword"> ==</span><span> ERC1820_ACCEPT_MAGIC</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Does not implement the interface&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> interfaces</span><span>[</span><span>addr</span><span>]</span><span>[</span><span>_interfaceHash</span><span>]</span><span class="z-keyword"> =</span><span> _implementer</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> InterfaceImplementerSet</span><span>(</span><span>addr</span><span>,</span><span> _interfaceHash</span><span>,</span><span> _implementer</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"> @notice</span><span class="z-comment"> Sets &#39;_newManager&#39; as manager for &#39;_addr&#39;.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The new manager will be able to call &#39;setInterfaceImplementer&#39; for &#39;_addr&#39;.</span></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"> Address for which to set the new manager.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _newManager</span><span class="z-comment"> Address of the new manager for &#39;addr&#39;. (Pass &#39;0x0&#39; to reset the manager to &#39;_addr&#39;.)</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setManager</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addr</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _newManager</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">getManager</span><span>(</span><span>_addr</span><span>)</span><span class="z-keyword"> ==</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span class="z-string"> &quot;Not the manager&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> managers</span><span>[</span><span>_addr</span><span>]</span><span class="z-keyword"> =</span><span> _newManager </span><span class="z-keyword">==</span><span> _addr </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> _newManager</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ManagerChanged</span><span>(</span><span>_addr</span><span>,</span><span> _newManager</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"> @notice</span><span class="z-comment"> Get the manager of an 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"> _addr</span><span class="z-comment"> Address for which to return the manager.</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 manager for a given address.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getManager</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"> 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-comment"> //</span><span class="z-comment"> By default the manager of an address is the same address</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>managers</span><span>[</span><span>_addr</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> _addr</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> managers</span><span>[</span><span>_addr</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Compute the keccak256 hash of an interface given its 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"> _interfaceName</span><span class="z-comment"> Name of the interface.</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"> keccak256 hash of an interface name.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> interfaceHash</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"> _interfaceName</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 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>_interfaceName</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"> --- ERC165 Related Functions --- </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> --- Developed in collaboration with William Entriken. --- </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"> Updates the cache with whether the contract implements an ERC165 interface or not.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _contract</span><span class="z-comment"> Address of the contract for which to update the cache.</span></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"> ERC165 interface for which to update the cache.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateERC165Cache</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</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> {</span></span> <span class="giallo-l"><span> interfaces</span><span>[</span><span>_contract</span><span>]</span><span>[</span><span>_interfaceId</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> implementsERC165InterfaceNoCache</span><span>(</span></span> <span class="giallo-l"><span> _contract</span><span>,</span><span> _interfaceId</span><span>)</span><span class="z-keyword"> ?</span><span> _contract </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> erc165Cached</span><span>[</span><span>_contract</span><span>]</span><span>[</span><span>_interfaceId</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Checks whether a contract implements an ERC165 interface or not.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If the result is not cached a direct lookup on the contract address is performed.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If the result is not cached or the cached value is out-of-date, the cache MUST be updated manually by calling</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> &#39;updateERC165Cache&#39; with the 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"> _contract</span><span class="z-comment"> Address of the contract to check.</span></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"> ERC165 interface to check.</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 &#39;_contract&#39; implements &#39;_interfaceId&#39;, false otherwise.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> implementsERC165Interface</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</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"> 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"> if</span><span> (</span><span class="z-keyword">!</span><span>erc165Cached</span><span>[</span><span>_contract</span><span>]</span><span>[</span><span>_interfaceId</span><span>]</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> implementsERC165InterfaceNoCache</span><span>(</span><span>_contract</span><span>,</span><span> _interfaceId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> interfaces</span><span>[</span><span>_contract</span><span>]</span><span>[</span><span>_interfaceId</span><span>]</span><span class="z-keyword"> ==</span><span> _contract</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"> @notice</span><span class="z-comment"> Checks whether a contract implements an ERC165 interface or not without using nor updating the cache.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _contract</span><span class="z-comment"> Address of the contract to check.</span></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"> ERC165 interface to check.</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 &#39;_contract&#39; implements &#39;_interfaceId&#39;, false otherwise.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> implementsERC165InterfaceNoCache</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</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"> 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> success</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> result</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> (</span><span>success</span><span>,</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> noThrowCall</span><span>(</span><span>_contract</span><span>,</span><span> ERC165ID</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>success </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span class="z-keyword"> ||</span><span> result </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 class="giallo-l"></span> <span class="giallo-l"><span> (</span><span>success</span><span>,</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> noThrowCall</span><span>(</span><span>_contract</span><span>,</span><span> INVALID_ID</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>success </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span class="z-keyword"> ||</span><span> result </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 class="giallo-l"></span> <span class="giallo-l"><span> (</span><span>success</span><span>,</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> noThrowCall</span><span>(</span><span>_contract</span><span>,</span><span> _interfaceId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>success </span><span class="z-keyword">==</span><span class="z-constant"> 1</span><span class="z-keyword"> &amp;&amp;</span><span> result </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 class="z-constant"> true</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Checks whether the hash is a ERC165 interface (ending with 28 zeroes) or not.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _interfaceHash</span><span class="z-comment"> The hash to check.</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 &#39;_interfaceHash&#39; is an ERC165 interface (ending with 28 zeroes), false otherwise.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isERC165Interface</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _interfaceHash</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>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _interfaceHash </span><span class="z-keyword">&amp;</span><span class="z-constant"> 0x00000000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF</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 class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Make a call on a contract without throwing if the function does not exist.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> noThrowCall</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable z-parameter z-function"> _interfaceId</span><span>)</span></span> <span class="giallo-l"><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">uint256</span><span class="z-variable"> success</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> result</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span> erc165ID </span><span class="z-keyword">=</span><span> ERC165ID</span><span>;</span></span> <span class="giallo-l"></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> x </span><span class="z-keyword">:=</span><span class="z-entity z-name"> mload</span><span>(</span><span class="z-constant">0x40</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Find empty storage location using &quot;free memory pointer&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span>x</span><span>,</span><span> erc165ID</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Place signature at beginning of empty storage</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>x</span><span>,</span><span class="z-constant"> 0x04</span><span>)</span><span>,</span><span> _interfaceId</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Place first argument directly next to signature</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> success </span><span class="z-keyword">:=</span><span class="z-entity z-name"> staticcall</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> 30000</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> 30k gas</span></span> <span class="giallo-l"><span> _contract</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> To addr</span></span> <span class="giallo-l"><span> x</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Inputs are stored at location x</span></span> <span class="giallo-l"><span class="z-constant"> 0x24</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Inputs are 36 (4 + 32) bytes long</span></span> <span class="giallo-l"><span> x</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Store output over input (saves space)</span></span> <span class="giallo-l"><span class="z-constant"> 0x20</span><span class="z-comment"> //</span><span class="z-comment"> Outputs are 32 bytes long</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> result </span><span class="z-keyword">:=</span><span class="z-entity z-name"> mload</span><span>(</span><span>x</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Load the result</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="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>0xf90a388085174876e800830c35008080b909e5608060405234801561001057600080fd5b506109c5806100206000396000f3fe608060405234801561001057600080fd5b50600436106100a5576000357c010000000000000000000000000000000000000000000000000000000090048063a41e7d5111610078578063a41e7d51146101d4578063aabbb8ca1461020a578063b705676514610236578063f712f3e814610280576100a5565b806329965a1d146100aa5780633d584063146100e25780635df8122f1461012457806365ba36c114610152575b600080fd5b6100e0600480360360608110156100c057600080fd5b50600160a060020a038135811691602081013591604090910135166102b6565b005b610108600480360360208110156100f857600080fd5b5035600160a060020a0316610570565b60408051600160a060020a039092168252519081900360200190f35b6100e06004803603604081101561013a57600080fd5b50600160a060020a03813581169160200135166105bc565b6101c26004803603602081101561016857600080fd5b81019060208101813564010000000081111561018357600080fd5b82018360208201111561019557600080fd5b803590602001918460018302840111640100000000831117156101b757600080fd5b5090925090506106b3565b60408051918252519081900360200190f35b6100e0600480360360408110156101ea57600080fd5b508035600160a060020a03169060200135600160e060020a0319166106ee565b6101086004803603604081101561022057600080fd5b50600160a060020a038135169060200135610778565b61026c6004803603604081101561024c57600080fd5b508035600160a060020a03169060200135600160e060020a0319166107ef565b604080519115158252519081900360200190f35b61026c6004803603604081101561029657600080fd5b508035600160a060020a03169060200135600160e060020a0319166108aa565b6000600160a060020a038416156102cd57836102cf565b335b9050336102db82610570565b600160a060020a031614610339576040805160e560020a62461bcd02815260206004820152600f60248201527f4e6f7420746865206d616e616765720000000000000000000000000000000000604482015290519081900360640190fd5b6103428361092a565b15610397576040805160e560020a62461bcd02815260206004820152601a60248201527f4d757374206e6f7420626520616e204552433136352068617368000000000000604482015290519081900360640190fd5b600160a060020a038216158015906103b85750600160a060020a0382163314155b156104ff5760405160200180807f455243313832305f4143434550545f4d4147494300000000000000000000000081525060140190506040516020818303038152906040528051906020012082600160a060020a031663249cb3fa85846040518363ffffffff167c01000000000000000000000000000000000000000000000000000000000281526004018083815260200182600160a060020a0316600160a060020a031681526020019250505060206040518083038186803b15801561047e57600080fd5b505afa158015610492573d6000803e3d6000fd5b505050506040513d60208110156104a857600080fd5b5051146104ff576040805160e560020a62461bcd02815260206004820181905260248201527f446f6573206e6f7420696d706c656d656e742074686520696e74657266616365604482015290519081900360640190fd5b600160a060020a03818116600081815260208181526040808320888452909152808220805473ffffffffffffffffffffffffffffffffffffffff19169487169485179055518692917f93baa6efbd2244243bfee6ce4cfdd1d04fc4c0e9a786abd3a41313bd352db15391a450505050565b600160a060020a03818116600090815260016020526040812054909116151561059a5750806105b7565b50600160a060020a03808216600090815260016020526040902054165b919050565b336105c683610570565b600160a060020a031614610624576040805160e560020a62461bcd02815260206004820152600f60248201527f4e6f7420746865206d616e616765720000000000000000000000000000000000604482015290519081900360640190fd5b81600160a060020a031681600160a060020a0316146106435780610646565b60005b600160a060020a03838116600081815260016020526040808220805473ffffffffffffffffffffffffffffffffffffffff19169585169590951790945592519184169290917f605c2dbf762e5f7d60a546d42e7205dcb1b011ebc62a61736a57c9089d3a43509190a35050565b600082826040516020018083838082843780830192505050925050506040516020818303038152906040528051906020012090505b92915050565b6106f882826107ef565b610703576000610705565b815b600160a060020a03928316600081815260208181526040808320600160e060020a031996909616808452958252808320805473ffffffffffffffffffffffffffffffffffffffff19169590971694909417909555908152600284528181209281529190925220805460ff19166001179055565b600080600160a060020a038416156107905783610792565b335b905061079d8361092a565b156107c357826107ad82826108aa565b6107b85760006107ba565b815b925050506106e8565b600160a060020a0390811660009081526020818152604080832086845290915290205416905092915050565b6000808061081d857f01ffc9a70000000000000000000000000000000000000000000000000000000061094c565b909250905081158061082d575080155b1561083d576000925050506106e8565b61084f85600160e060020a031961094c565b909250905081158061086057508015155b15610870576000925050506106e8565b61087a858561094c565b909250905060018214801561088f5750806001145b1561089f576001925050506106e8565b506000949350505050565b600160a060020a0382166000908152600260209081526040808320600160e060020a03198516845290915281205460ff1615156108f2576108eb83836107ef565b90506106e8565b50600160a060020a03808316600081815260208181526040808320600160e060020a0319871684529091529020549091161492915050565b7bffffffffffffffffffffffffffffffffffffffffffffffffffffffff161590565b6040517f01ffc9a7000000000000000000000000000000000000000000000000000000008082526004820183905260009182919060208160248189617530fa90519096909550935050505056fea165627a7a72305820377f4a2d4301ede9949f163f319021a6e9c687c292a5e2b2c4734c126b524e6c00291ba01820182018201820182018201820182018201820182018201820182018201820a01820182018201820182018201820182018201820182018201820182018201820</span></span></code></pre> <p>The strings of <code>1820</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>Set the <code>v</code>, <code>r</code>, <code>s</code> of the transaction signature to the following values:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>v: 27,</span></span> <span class="giallo-l"><span>r: 0x1820182018201820182018201820182018201820182018201820182018201820&#39;</span></span> <span class="giallo-l"><span>s: 0x1820182018201820182018201820182018201820182018201820182018201820&#39;</span></span></code></pre> <p>Those <code>r</code> and <code>s</code> values---made of a repeating pattern of <code>1820</code>'s---are predictable "random numbers" generated deterministically by a human.</p> </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.08 ether to this single-use deployment account.</p> </li> <li> <p>Broadcast the deployment transaction.</p> </li> </ol> <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-registry-deployment-account">Single-use Registry Deployment Account</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0xa990077c3205cbDf861e17Fa532eeB069cE9fF96</span></span></code></pre> <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.08 ether MUST be sent to this account <em>first</em>.</p> </blockquote> <h3 id="registry-contract-address">Registry Contract Address</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x1820a4B7618BdE71Dce8cdc73aAB6C95905faD24</span></span></code></pre> <p>The contract has the address above for every chain on which it is deployed.</p> <details> <summary>Raw metadata of <code>./contracts/ERC1820Registry.sol</code></summary> <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">compiler</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">0.5.3+commit.10d17f24</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">language</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Solidity</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">output</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">abi</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">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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">_addr</span><span class="z-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">_interfaceHash</span><span class="z-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></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">_implementer</span><span class="z-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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">setInterfaceImplementer</span><span class="z-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">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></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 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">_addr</span><span class="z-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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">getManager</span><span class="z-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">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">view</span><span class="z-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></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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">_addr</span><span class="z-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">_newManager</span><span class="z-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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">setManager</span><span class="z-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">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></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 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">_interfaceName</span><span class="z-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">interfaceHash</span><span class="z-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">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">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></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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">_contract</span><span class="z-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">_interfaceId</span><span class="z-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">bytes4</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">updateERC165Cache</span><span class="z-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">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></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 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">_addr</span><span class="z-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">_interfaceHash</span><span class="z-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">getInterfaceImplementer</span><span class="z-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">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">view</span><span class="z-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></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 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">_contract</span><span class="z-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">_interfaceId</span><span class="z-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">bytes4</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">implementsERC165InterfaceNoCache</span><span class="z-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">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></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">view</span><span class="z-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></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 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">_contract</span><span class="z-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">_interfaceId</span><span class="z-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">bytes4</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">implementsERC165Interface</span><span class="z-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">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></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">view</span><span class="z-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></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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">addr</span><span class="z-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"> true</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">interfaceHash</span><span class="z-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></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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">implementer</span><span class="z-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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">InterfaceImplementerSet</span><span class="z-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">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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">addr</span><span class="z-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"> true</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">newManager</span><span class="z-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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ManagerChanged</span><span class="z-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 class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">devdoc</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">author</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Jordi Baylina and Jacques Dafflon</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">methods</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">getInterfaceImplementer(address,bytes32)</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">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">_addr</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address being queried for the implementer of an interface. (If &#39;_addr&#39; is the zero address then &#39;msg.sender&#39; is assumed.)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">_interfaceHash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Keccak256 hash of the name of the interface as a string. E.g., &#39;web3.utils.keccak256(</span><span class="z-constant">\&quot;</span><span class="z-string">ERC777TokensRecipient</span><span class="z-constant">\&quot;</span><span class="z-string">)&#39; for the &#39;ERC777TokensRecipient&#39; interface.</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">return</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The address of the contract which implements the interface &#39;_interfaceHash&#39; for &#39;_addr&#39; or &#39;0&#39; if &#39;_addr&#39; did not register an implementer for this interface.</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">getManager(address)</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">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">_addr</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address for which to return the manager.</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">return</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address of the manager for a given 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 class="z-support"> &quot;</span><span class="z-support">implementsERC165Interface(address,bytes4)</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">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">_contract</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address of the contract to check.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">_interfaceId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC165 interface to check.</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">return</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">True if &#39;_contract&#39; implements &#39;_interfaceId&#39;, false otherwise.</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">implementsERC165InterfaceNoCache(address,bytes4)</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">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">_contract</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address of the contract to check.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">_interfaceId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC165 interface to check.</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">return</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">True if &#39;_contract&#39; implements &#39;_interfaceId&#39;, false otherwise.</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">interfaceHash(string)</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">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">_interfaceName</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 interface.</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">return</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The keccak256 hash of an interface 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 class="z-support"> &quot;</span><span class="z-support">setInterfaceImplementer(address,bytes32,address)</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">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">_addr</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address for which to set the interface. (If &#39;_addr&#39; is the zero address then &#39;msg.sender&#39; is assumed.)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">_implementer</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Contract address implementing &#39;_interfaceHash&#39; for &#39;_addr&#39;.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">_interfaceHash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Keccak256 hash of the name of the interface as a string. E.g., &#39;web3.utils.keccak256(</span><span class="z-constant">\&quot;</span><span class="z-string">ERC777TokensRecipient</span><span class="z-constant">\&quot;</span><span class="z-string">)&#39; for the &#39;ERC777TokensRecipient&#39; interface.</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">setManager(address,address)</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">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">_addr</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address for which to set the new manager.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">_newManager</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address of the new manager for &#39;addr&#39;. (Pass &#39;0x0&#39; to reset the manager to &#39;_addr&#39;.)</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">updateERC165Cache(address,bytes4)</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">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">_contract</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address of the contract for which to update the cache.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">_interfaceId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC165 interface for which to update the cache.</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC1820 Pseudo-introspection Registry Contract</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">userdoc</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">methods</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">getInterfaceImplementer(address,bytes32)</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Query if an address implements an interface and through which contract.</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">getManager(address)</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Get the manager of an 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 class="z-support"> &quot;</span><span class="z-support">implementsERC165InterfaceNoCache(address,bytes4)</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Checks whether a contract implements an ERC165 interface or not without using nor updating the cache.</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">interfaceHash(string)</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Compute the keccak256 hash of an interface given its 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 class="z-support"> &quot;</span><span class="z-support">setInterfaceImplementer(address,bytes32,address)</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Sets the contract which implements a specific interface for an address. Only the manager defined for that address can set it. (Each address is the manager for itself until it sets a new manager.)</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">setManager(address,address)</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Sets &#39;_newManager&#39; as manager for &#39;_addr&#39;. The new manager will be able to call &#39;setInterfaceImplementer&#39; for &#39;_addr&#39;.</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">updateERC165Cache(address,bytes4)</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Updates the cache with whether the contract implements an ERC165 interface or not.</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">This contract is the official implementation of the ERC1820 Registry.For more details, see https://eips.ethereum.org/EIPS/eip-1820</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">settings</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">compilationTarget</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">./contracts/ERC1820Registry.sol</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC1820Registry</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">evmVersion</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">byzantium</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">libraries</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">optimizer</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">enabled</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">runs</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 200</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">remappings</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">sources</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">./contracts/ERC1820Registry.sol</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">content</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">/* ERC1820 Pseudo-introspection Registry Contract</span><span class="z-constant">\n</span><span class="z-string"> * This standard defines a universal registry smart contract where any address (contract or regular account) can</span><span class="z-constant">\n</span><span class="z-string"> * register which interface it supports and which smart contract is responsible for its implementation.</span><span class="z-constant">\n</span><span class="z-string"> *</span><span class="z-constant">\n</span><span class="z-string"> * Written in 2019 by Jordi Baylina and Jacques Dafflon</span><span class="z-constant">\n</span><span class="z-string"> *</span><span class="z-constant">\n</span><span class="z-string"> * To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to</span><span class="z-constant">\n</span><span class="z-string"> * this software to the public domain worldwide. This software is distributed without any warranty.</span><span class="z-constant">\n</span><span class="z-string"> *</span><span class="z-constant">\n</span><span class="z-string"> * You should have received a copy of the CC0 Public Domain Dedication along with this software. If not, see</span><span class="z-constant">\n</span><span class="z-string"> * &lt;http://creativecommons.org/publicdomain/zero/1.0/&gt;.</span><span class="z-constant">\n</span><span class="z-string"> *</span><span class="z-constant">\n</span><span class="z-string"> * ███████╗██████╗ ██████╗ ██╗ █████╗ ██████╗ ██████╗</span><span class="z-constant">\n</span><span class="z-string"> * ██╔════╝██╔══██╗██╔════╝███║██╔══██╗╚════██╗██╔═████╗</span><span class="z-constant">\n</span><span class="z-string"> * █████╗ ██████╔╝██║ ╚██║╚█████╔╝ █████╔╝██║██╔██║</span><span class="z-constant">\n</span><span class="z-string"> * ██╔══╝ ██╔══██╗██║ ██║██╔══██╗██╔═══╝ ████╔╝██║</span><span class="z-constant">\n</span><span class="z-string"> * ███████╗██║ ██║╚██████╗ ██║╚█████╔╝███████╗╚██████╔╝</span><span class="z-constant">\n</span><span class="z-string"> * ╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚════╝ ╚══════╝ ╚═════╝</span><span class="z-constant">\n</span><span class="z-string"> *</span><span class="z-constant">\n</span><span class="z-string"> * ██████╗ ███████╗ ██████╗ ██╗███████╗████████╗██████╗ ██╗ ██╗</span><span class="z-constant">\n</span><span class="z-string"> * ██╔══██╗██╔════╝██╔════╝ ██║██╔════╝╚══██╔══╝██╔══██╗╚██╗ ██╔╝</span><span class="z-constant">\n</span><span class="z-string"> * ██████╔╝█████╗ ██║ ███╗██║███████╗ ██║ ██████╔╝ ╚████╔╝</span><span class="z-constant">\n</span><span class="z-string"> * ██╔══██╗██╔══╝ ██║ ██║██║╚════██║ ██║ ██╔══██╗ ╚██╔╝</span><span class="z-constant">\n</span><span class="z-string"> * ██║ ██║███████╗╚██████╔╝██║███████║ ██║ ██║ ██║ ██║</span><span class="z-constant">\n</span><span class="z-string"> * ╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚═╝╚══════╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝</span><span class="z-constant">\n</span><span class="z-string"> *</span><span class="z-constant">\n</span><span class="z-string"> */</span><span class="z-constant">\n</span><span class="z-string">pragma solidity 0.5.3;</span><span class="z-constant">\n</span><span class="z-string">// IV is value needed to have a vanity address starting with &#39;0x1820&#39;.</span><span class="z-constant">\n</span><span class="z-string">// IV: 53759</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string">/// @dev The interface a contract MUST implement if it is the implementer of</span><span class="z-constant">\n</span><span class="z-string">/// some (other) interface for any address other than itself.</span><span class="z-constant">\n</span><span class="z-string">interface ERC1820ImplementerInterface {</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Indicates whether the contract implements the interface &#39;interfaceHash&#39; for the address &#39;addr&#39; or not.</span><span class="z-constant">\n</span><span class="z-string"> /// @param interfaceHash keccak256 hash of the name of the interface</span><span class="z-constant">\n</span><span class="z-string"> /// @param addr Address for which the contract will implement the interface</span><span class="z-constant">\n</span><span class="z-string"> /// @return ERC1820_ACCEPT_MAGIC only if the contract implements &#39;interfaceHash&#39; for the address &#39;addr&#39;.</span><span class="z-constant">\n</span><span class="z-string"> function canImplementInterfaceForAddress(bytes32 interfaceHash, address addr) external view returns(bytes32);</span><span class="z-constant">\n</span><span class="z-string">}</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string">/// @title ERC1820 Pseudo-introspection Registry Contract</span><span class="z-constant">\n</span><span class="z-string">/// @author Jordi Baylina and Jacques Dafflon</span><span class="z-constant">\n</span><span class="z-string">/// @notice This contract is the official implementation of the ERC1820 Registry.</span><span class="z-constant">\n</span><span class="z-string">/// @notice For more details, see https://eips.ethereum.org/EIPS/eip-1820</span><span class="z-constant">\n</span><span class="z-string">contract ERC1820Registry {</span><span class="z-constant">\n</span><span class="z-string"> /// @notice ERC165 Invalid ID.</span><span class="z-constant">\n</span><span class="z-string"> bytes4 constant internal INVALID_ID = 0xffffffff;</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Method ID for the ERC165 supportsInterface method (= `bytes4(keccak256(&#39;supportsInterface(bytes4)&#39;))`).</span><span class="z-constant">\n</span><span class="z-string"> bytes4 constant internal ERC165ID = 0x01ffc9a7;</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Magic value which is returned if a contract implements an interface on behalf of some other address.</span><span class="z-constant">\n</span><span class="z-string"> bytes32 constant internal ERC1820_ACCEPT_MAGIC = keccak256(abi.encodePacked(</span><span class="z-constant">\&quot;</span><span class="z-string">ERC1820_ACCEPT_MAGIC</span><span class="z-constant">\&quot;</span><span class="z-string">));</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice mapping from addresses and interface hashes to their implementers.</span><span class="z-constant">\n</span><span class="z-string"> mapping(address =&gt; mapping(bytes32 =&gt; address)) internal interfaces;</span><span class="z-constant">\n</span><span class="z-string"> /// @notice mapping from addresses to their manager.</span><span class="z-constant">\n</span><span class="z-string"> mapping(address =&gt; address) internal managers;</span><span class="z-constant">\n</span><span class="z-string"> /// @notice flag for each address and erc165 interface to indicate if it is cached.</span><span class="z-constant">\n</span><span class="z-string"> mapping(address =&gt; mapping(bytes4 =&gt; bool)) internal erc165Cached;</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Indicates a contract is the &#39;implementer&#39; of &#39;interfaceHash&#39; for &#39;addr&#39;.</span><span class="z-constant">\n</span><span class="z-string"> event InterfaceImplementerSet(address indexed addr, bytes32 indexed interfaceHash, address indexed implementer);</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Indicates &#39;newManager&#39; is the address of the new manager for &#39;addr&#39;.</span><span class="z-constant">\n</span><span class="z-string"> event ManagerChanged(address indexed addr, address indexed newManager);</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Query if an address implements an interface and through which contract.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _addr Address being queried for the implementer of an interface.</span><span class="z-constant">\n</span><span class="z-string"> /// (If &#39;_addr&#39; is the zero address then &#39;msg.sender&#39; is assumed.)</span><span class="z-constant">\n</span><span class="z-string"> /// @param _interfaceHash Keccak256 hash of the name of the interface as a string.</span><span class="z-constant">\n</span><span class="z-string"> /// E.g., &#39;web3.utils.keccak256(</span><span class="z-constant">\&quot;</span><span class="z-string">ERC777TokensRecipient</span><span class="z-constant">\&quot;</span><span class="z-string">)&#39; for the &#39;ERC777TokensRecipient&#39; interface.</span><span class="z-constant">\n</span><span class="z-string"> /// @return The address of the contract which implements the interface &#39;_interfaceHash&#39; for &#39;_addr&#39;</span><span class="z-constant">\n</span><span class="z-string"> /// or &#39;0&#39; if &#39;_addr&#39; did not register an implementer for this interface.</span><span class="z-constant">\n</span><span class="z-string"> function getInterfaceImplementer(address _addr, bytes32 _interfaceHash) external view returns (address) {</span><span class="z-constant">\n</span><span class="z-string"> address addr = _addr == address(0) ? msg.sender : _addr;</span><span class="z-constant">\n</span><span class="z-string"> if (isERC165Interface(_interfaceHash)) {</span><span class="z-constant">\n</span><span class="z-string"> bytes4 erc165InterfaceHash = bytes4(_interfaceHash);</span><span class="z-constant">\n</span><span class="z-string"> return implementsERC165Interface(addr, erc165InterfaceHash) ? addr : address(0);</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-string"> return interfaces[addr][_interfaceHash];</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Sets the contract which implements a specific interface for an address.</span><span class="z-constant">\n</span><span class="z-string"> /// Only the manager defined for that address can set it.</span><span class="z-constant">\n</span><span class="z-string"> /// (Each address is the manager for itself until it sets a new manager.)</span><span class="z-constant">\n</span><span class="z-string"> /// @param _addr Address for which to set the interface.</span><span class="z-constant">\n</span><span class="z-string"> /// (If &#39;_addr&#39; is the zero address then &#39;msg.sender&#39; is assumed.)</span><span class="z-constant">\n</span><span class="z-string"> /// @param _interfaceHash Keccak256 hash of the name of the interface as a string.</span><span class="z-constant">\n</span><span class="z-string"> /// E.g., &#39;web3.utils.keccak256(</span><span class="z-constant">\&quot;</span><span class="z-string">ERC777TokensRecipient</span><span class="z-constant">\&quot;</span><span class="z-string">)&#39; for the &#39;ERC777TokensRecipient&#39; interface.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _implementer Contract address implementing &#39;_interfaceHash&#39; for &#39;_addr&#39;.</span><span class="z-constant">\n</span><span class="z-string"> function setInterfaceImplementer(address _addr, bytes32 _interfaceHash, address _implementer) external {</span><span class="z-constant">\n</span><span class="z-string"> address addr = _addr == address(0) ? msg.sender : _addr;</span><span class="z-constant">\n</span><span class="z-string"> require(getManager(addr) == msg.sender, </span><span class="z-constant">\&quot;</span><span class="z-string">Not the manager</span><span class="z-constant">\&quot;</span><span class="z-string">);</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> require(!isERC165Interface(_interfaceHash), </span><span class="z-constant">\&quot;</span><span class="z-string">Must not be an ERC165 hash</span><span class="z-constant">\&quot;</span><span class="z-string">);</span><span class="z-constant">\n</span><span class="z-string"> if (_implementer != address(0) &amp;&amp; _implementer != msg.sender) {</span><span class="z-constant">\n</span><span class="z-string"> require(</span><span class="z-constant">\n</span><span class="z-string"> ERC1820ImplementerInterface(_implementer)</span><span class="z-constant">\n</span><span class="z-string"> .canImplementInterfaceForAddress(_interfaceHash, addr) == ERC1820_ACCEPT_MAGIC,</span><span class="z-constant">\n</span><span class="z-constant"> \&quot;</span><span class="z-string">Does not implement the interface</span><span class="z-constant">\&quot;</span><span class="z-constant">\n</span><span class="z-string"> );</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-string"> interfaces[addr][_interfaceHash] = _implementer;</span><span class="z-constant">\n</span><span class="z-string"> emit InterfaceImplementerSet(addr, _interfaceHash, _implementer);</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Sets &#39;_newManager&#39; as manager for &#39;_addr&#39;.</span><span class="z-constant">\n</span><span class="z-string"> /// The new manager will be able to call &#39;setInterfaceImplementer&#39; for &#39;_addr&#39;.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _addr Address for which to set the new manager.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _newManager Address of the new manager for &#39;addr&#39;. (Pass &#39;0x0&#39; to reset the manager to &#39;_addr&#39;.)</span><span class="z-constant">\n</span><span class="z-string"> function setManager(address _addr, address _newManager) external {</span><span class="z-constant">\n</span><span class="z-string"> require(getManager(_addr) == msg.sender, </span><span class="z-constant">\&quot;</span><span class="z-string">Not the manager</span><span class="z-constant">\&quot;</span><span class="z-string">);</span><span class="z-constant">\n</span><span class="z-string"> managers[_addr] = _newManager == _addr ? address(0) : _newManager;</span><span class="z-constant">\n</span><span class="z-string"> emit ManagerChanged(_addr, _newManager);</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Get the manager of an address.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _addr Address for which to return the manager.</span><span class="z-constant">\n</span><span class="z-string"> /// @return Address of the manager for a given address.</span><span class="z-constant">\n</span><span class="z-string"> function getManager(address _addr) public view returns(address) {</span><span class="z-constant">\n</span><span class="z-string"> // By default the manager of an address is the same address</span><span class="z-constant">\n</span><span class="z-string"> if (managers[_addr] == address(0)) {</span><span class="z-constant">\n</span><span class="z-string"> return _addr;</span><span class="z-constant">\n</span><span class="z-string"> } else {</span><span class="z-constant">\n</span><span class="z-string"> return managers[_addr];</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Compute the keccak256 hash of an interface given its name.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _interfaceName Name of the interface.</span><span class="z-constant">\n</span><span class="z-string"> /// @return The keccak256 hash of an interface name.</span><span class="z-constant">\n</span><span class="z-string"> function interfaceHash(string calldata _interfaceName) external pure returns(bytes32) {</span><span class="z-constant">\n</span><span class="z-string"> return keccak256(abi.encodePacked(_interfaceName));</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /* --- ERC165 Related Functions --- */</span><span class="z-constant">\n</span><span class="z-string"> /* --- Developed in collaboration with William Entriken. --- */</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Updates the cache with whether the contract implements an ERC165 interface or not.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _contract Address of the contract for which to update the cache.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _interfaceId ERC165 interface for which to update the cache.</span><span class="z-constant">\n</span><span class="z-string"> function updateERC165Cache(address _contract, bytes4 _interfaceId) external {</span><span class="z-constant">\n</span><span class="z-string"> interfaces[_contract][_interfaceId] = implementsERC165InterfaceNoCache(</span><span class="z-constant">\n</span><span class="z-string"> _contract, _interfaceId) ? _contract : address(0);</span><span class="z-constant">\n</span><span class="z-string"> erc165Cached[_contract][_interfaceId] = true;</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Checks whether a contract implements an ERC165 interface or not.</span><span class="z-constant">\n</span><span class="z-string"> // If the result is not cached a direct lookup on the contract address is performed.</span><span class="z-constant">\n</span><span class="z-string"> // If the result is not cached or the cached value is out-of-date, the cache MUST be updated manually by calling</span><span class="z-constant">\n</span><span class="z-string"> // &#39;updateERC165Cache&#39; with the contract address.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _contract Address of the contract to check.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _interfaceId ERC165 interface to check.</span><span class="z-constant">\n</span><span class="z-string"> /// @return True if &#39;_contract&#39; implements &#39;_interfaceId&#39;, false otherwise.</span><span class="z-constant">\n</span><span class="z-string"> function implementsERC165Interface(address _contract, bytes4 _interfaceId) public view returns (bool) {</span><span class="z-constant">\n</span><span class="z-string"> if (!erc165Cached[_contract][_interfaceId]) {</span><span class="z-constant">\n</span><span class="z-string"> return implementsERC165InterfaceNoCache(_contract, _interfaceId);</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-string"> return interfaces[_contract][_interfaceId] == _contract;</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Checks whether a contract implements an ERC165 interface or not without using nor updating the cache.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _contract Address of the contract to check.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _interfaceId ERC165 interface to check.</span><span class="z-constant">\n</span><span class="z-string"> /// @return True if &#39;_contract&#39; implements &#39;_interfaceId&#39;, false otherwise.</span><span class="z-constant">\n</span><span class="z-string"> function implementsERC165InterfaceNoCache(address _contract, bytes4 _interfaceId) public view returns (bool) {</span><span class="z-constant">\n</span><span class="z-string"> uint256 success;</span><span class="z-constant">\n</span><span class="z-string"> uint256 result;</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> (success, result) = noThrowCall(_contract, ERC165ID);</span><span class="z-constant">\n</span><span class="z-string"> if (success == 0 || result == 0) {</span><span class="z-constant">\n</span><span class="z-string"> return false;</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> (success, result) = noThrowCall(_contract, INVALID_ID);</span><span class="z-constant">\n</span><span class="z-string"> if (success == 0 || result != 0) {</span><span class="z-constant">\n</span><span class="z-string"> return false;</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> (success, result) = noThrowCall(_contract, _interfaceId);</span><span class="z-constant">\n</span><span class="z-string"> if (success == 1 &amp;&amp; result == 1) {</span><span class="z-constant">\n</span><span class="z-string"> return true;</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-string"> return false;</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Checks whether the hash is a ERC165 interface (ending with 28 zeroes) or not.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _interfaceHash The hash to check.</span><span class="z-constant">\n</span><span class="z-string"> /// @return True if &#39;_interfaceHash&#39; is an ERC165 interface (ending with 28 zeroes), false otherwise.</span><span class="z-constant">\n</span><span class="z-string"> function isERC165Interface(bytes32 _interfaceHash) internal pure returns (bool) {</span><span class="z-constant">\n</span><span class="z-string"> return _interfaceHash &amp; 0x00000000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF == 0;</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @dev Make a call on a contract without throwing if the function does not exist.</span><span class="z-constant">\n</span><span class="z-string"> function noThrowCall(address _contract, bytes4 _interfaceId)</span><span class="z-constant">\n</span><span class="z-string"> internal view returns (uint256 success, uint256 result)</span><span class="z-constant">\n</span><span class="z-string"> {</span><span class="z-constant">\n</span><span class="z-string"> bytes4 erc165ID = ERC165ID;</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> assembly {</span><span class="z-constant">\n</span><span class="z-string"> let x := mload(0x40) // Find empty storage location using </span><span class="z-constant">\&quot;</span><span class="z-string">free memory pointer</span><span class="z-constant">\&quot;</span><span class="z-constant">\n</span><span class="z-string"> mstore(x, erc165ID) // Place signature at beginning of empty storage</span><span class="z-constant">\n</span><span class="z-string"> mstore(add(x, 0x04), _interfaceId) // Place first argument directly next to signature</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> success := staticcall(</span><span class="z-constant">\n</span><span class="z-string"> 30000, // 30k gas</span><span class="z-constant">\n</span><span class="z-string"> _contract, // To addr</span><span class="z-constant">\n</span><span class="z-string"> x, // Inputs are stored at location x</span><span class="z-constant">\n</span><span class="z-string"> 0x24, // Inputs are 36 (4 + 32) bytes long</span><span class="z-constant">\n</span><span class="z-string"> x, // Store output over input (saves space)</span><span class="z-constant">\n</span><span class="z-string"> 0x20 // Outputs are 32 bytes long</span><span class="z-constant">\n</span><span class="z-string"> )</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> result := mload(x) // Load the result</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-string">}</span><span class="z-constant">\n</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">keccak256</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x64025ecebddb6e126a5075c1fd6c01de2840492668e2909cef7157040a9d1945</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">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></details> <h3 id="interface-name">Interface Name</h3> <p>Any interface name is hashed using <code>keccak256</code> and sent to <code>getInterfaceImplementer()</code>.</p> <p>If the interface is part of a standard, it is best practice to explicitly state the interface name and link to this published <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> such that other people don't have to come here to look up these rules.</p> <p>For convenience, the registry provides a function to compute the hash 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"> interfaceHash</span><span>(</span><span class="z-support">string</span><span class="z-variable z-parameter z-function"> _interfaceName</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></code></pre> <p>Compute the keccak256 hash of an interface given its name.</p> <blockquote> <p><small><strong>identifier:</strong> <code>65ba36c1</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_interfaceName</code>: Name of the interface.</small><br /> <small><strong>returns:</strong> The <code>keccak256</code> hash of an interface name.</small></p> </blockquote> <h4 id="approved-ercs"><strong>Approved ERCs</strong></h4> <p>If the interface is part of an approved ERC, it MUST be named <code>ERC###XXXXX</code> where <code>###</code> is the number of the ERC and XXXXX should be the name of the interface in CamelCase. The meaning of this interface SHOULD be defined in the specified ERC.</p> <p>Examples:</p> <ul> <li><code>keccak256("ERC20Token")</code></li> <li><code>keccak256("ERC777Token")</code></li> <li><code>keccak256("ERC777TokensSender")</code></li> <li><code>keccak256("ERC777TokensRecipient")</code></li> </ul> <h4 id="erc-165-compatible-interfaces"><strong><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> Compatible Interfaces</strong></h4> <blockquote> <p>The compatibility with <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>, including the <a href="https://wg-eips.ritovision.com/1820/#erc165-cache">ERC165 Cache</a>, has been designed and developed with <a rel="external" href="https://github.com/fulldecent">William Entriken</a>.</p> </blockquote> <p>Any interface where the last 28 bytes are zeroes (<code>0</code>) SHALL be considered an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface.</p> <p><strong><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> Lookup</strong></p> <p>Anyone can explicitly check if a contract implements an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface using the registry by calling one of the two functions 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"> implementsERC165Interface</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</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"> 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></code></pre> <p>Checks whether a contract implements an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface or not.</p> <p>If the result is not cached a direct lookup on the contract address is performed.</p> <p><em>NOTE</em>: If the result is not cached or the cached value is out-of-date, the cache MUST be updated manually by calling <code>updateERC165Cache</code> with the contract address. (See <a href="https://wg-eips.ritovision.com/1820/#erc165-cache">ERC165 Cache</a> for more details.)</p> <blockquote> <p><small><strong>identifier:</strong> <code>f712f3e8</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_contract</code>: Address of the contract to check.</small><br /> <small><code>_interfaceId</code>: <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface to check.</small><br /> <small><strong>returns:</strong> <code>true</code> if <code>_contract</code> implements <code>_interfaceId</code>, <code>false</code> otherwise.</small></p> </blockquote> <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"> implementsERC165InterfaceNoCache</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</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"> 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></code></pre> <p>Checks whether a contract implements an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface or not without using nor updating the cache.</p> <blockquote> <p><small><strong>identifier:</strong> <code>b7056765</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_contract</code>: Address of the contract to check.</small><br /> <small><code>_interfaceId</code>: <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface to check.</small><br /> <small><strong>returns:</strong> <code>true</code> if <code>_contract</code> implements <code>_interfaceId</code>, false otherwise.</small></p> </blockquote> <p><strong><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> Cache</strong> <a id="erc165-cache"></a></p> <p>Whether a contract implements an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface or not can be cached manually to save gas.</p> <p>If a contract dynamically changes its interface and relies on the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> cache of the <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> registry, the cache MUST be updated manually---there is no automatic cache invalidation or cache update. Ideally the contract SHOULD automatically update the cache when changing its interface. However anyone MAY update the cache on the contract's behalf.</p> <p>The cache update MUST be done using the <code>updateERC165Cache</code> 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"> updateERC165Cache</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</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></code></pre> <blockquote> <p><small><strong>identifier:</strong> <code>a41e7d51</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_contract</code>: Address of the contract for which to update the cache.</small><br /> <small><code>_interfaceId</code>: <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface for which to update the cache.</small></p> </blockquote> <h4 id="private-user-defined-interfaces"><strong>Private User-defined Interfaces</strong></h4> <p>This scheme is extensible. You MAY make up your own interface name and raise awareness to get other people to implement it and then check for those implementations. Have fun but please, you MUST not conflict with the reserved designations above.</p> <h3 id="set-an-interface-for-an-address">Set An Interface For An Address</h3> <p>For any address to set a contract as the interface implementation, it must call the following function of the <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> registry:</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"> setInterfaceImplementer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addr</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _interfaceHash</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _implementer</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>Sets the contract which implements a specific interface for an address.</p> <p>Only the <code>manager</code> defined for that address can set it. (Each address is the manager for itself, see the <a href="https://wg-eips.ritovision.com/1820/#manager">manager</a> section for more details.)</p> <p><em>NOTE</em>: If <code>_addr</code> and <code>_implementer</code> are two different addresses, then:</p> <ul> <li>The <code>_implementer</code> MUST implement the <code>ERC1820ImplementerInterface</code> (detailed below).</li> <li>Calling <code>canImplementInterfaceForAddress</code> on <code>_implementer</code> with the given <code>_addr</code> and <code>_interfaceHash</code> MUST return the <code>ERC1820_ACCEPT_MAGIC</code> value.</li> </ul> <p><em>NOTE</em>: The <code>_interfaceHash</code> MUST NOT be an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface---it MUST NOT end with 28 zeroes (<code>0</code>).</p> <p><em>NOTE</em>: The <code>_addr</code> MAY be <code>0</code>, then <code>msg.sender</code> is assumed. This default value simplifies interactions via multisigs where the data of the transaction to sign is constant regardless of the address of the multisig instance.</p> <blockquote> <p><small><strong>identifier:</strong> <code>29965a1d</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_addr</code>: Address for which to set the interface. (If <code>_addr</code> is the zero address then <code>msg.sender</code> is assumed.)</small><br /> <small><code>_interfaceHash</code>: Keccak256 hash of the name of the interface as a string, for example <code>web3.utils.keccak256('ERC777TokensRecipient')</code> for the ERC777TokensRecipient interface.</small><br /> <small><code>_implementer</code>: Contract implementing <code>_interfaceHash</code> for <code>_addr</code>.</small></p> </blockquote> <h3 id="get-an-implementation-of-an-interface-for-an-address">Get An Implementation Of An Interface For An Address</h3> <p>Anyone MAY query the <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> Registry to obtain the address of a contract implementing an interface on behalf of some address using the <code>getInterfaceImplementer</code> 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"> getInterfaceImplementer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addr</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _interfaceHash</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> <p>Query if an address implements an interface and through which contract.</p> <p><em>NOTE</em>: If the last 28 bytes of the <code>_interfaceHash</code> are zeroes (<code>0</code>), then the first 4 bytes are considered an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface and the registry SHALL forward the call to the contract at <code>_addr</code> to see if it implements the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface (the first 4 bytes of <code>_interfaceHash</code>). The registry SHALL also cache <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> queries to reduce gas consumption. Anyone MAY call the <code>erc165UpdateCache</code> function to update whether a contract implements an interface or not.</p> <p><em>NOTE</em>: The <code>_addr</code> MAY be <code>0</code>, then <code>msg.sender</code> is assumed. This default value is consistent with the behavior of the <code>setInterfaceImplementer</code> function and simplifies interactions via multisigs where the data of the transaction to sign is constant regardless of the address of the multisig instance.</p> <blockquote> <p><small><strong>identifier:</strong> <code>aabbb8ca</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_addr</code>: Address being queried for the implementer of an interface. (If <code>_addr</code> is the zero address then <code>msg.sender</code> is assumed.)</small><br /> <small><code>_interfaceHash</code>: keccak256 hash of the name of the interface as a string. E.g. <code>web3.utils.keccak256('ERC777Token')</code></small><br /> <small><strong>returns:</strong> The address of the contract which implements the interface <code>_interfaceHash</code> for <code>_addr</code> or <code>0</code> if <code>_addr</code> did not register an implementer for this interface.</small></p> </blockquote> <h3 id="interface-implementation-erc1820implementerinterface">Interface Implementation (<code>ERC1820ImplementerInterface</code>)</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"> ERC1820ImplementerInterface</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"> Indicates whether the contract implements the interface `interfaceHash` for the address `addr` or not.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> interfaceHash</span><span class="z-comment"> keccak256 hash of the name of the 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"> addr</span><span class="z-comment"> Address for which the contract will implement the interface</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"> ERC1820_ACCEPT_MAGIC</span><span class="z-comment"> only if the contract implements `interfaceHash` for the address `addr`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canImplementInterfaceForAddress</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> interfaceHash</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-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>Any contract being registered as the implementation of an interface for a given address MUST implement said interface. In addition if it implements an interface on behalf of a different address, the contract MUST implement the <code>ERC1820ImplementerInterface</code> shown above.</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"> canImplementInterfaceForAddress</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> interfaceHash</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-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bytes32</span><span>)</span></span></code></pre> <p>Indicates whether a contract implements an interface (<code>interfaceHash</code>) for a given address (<code>addr</code>).</p> <p>If a contract implements the interface (<code>interfaceHash</code>) for a given address (<code>addr</code>), it MUST return <code>ERC1820_ACCEPT_MAGIC</code> when called with the <code>addr</code> and the <code>interfaceHash</code>. If it does not implement the <code>interfaceHash</code> for a given address (<code>addr</code>), it MUST NOT return <code>ERC1820_ACCEPT_MAGIC</code>.</p> <blockquote> <p><small><strong>identifier:</strong> <code>f0083250</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>interfaceHash</code>: Hash of the interface which is implemented</small><br /> <small><code>addr</code>: Address for which the interface is implemented</small><br /> <small><strong>returns:</strong> <code>ERC1820_ACCEPT_MAGIC</code> only if the contract implements <code>ìnterfaceHash</code> for the address <code>addr</code>.</small></p> </blockquote> <p>The special value <code>ERC1820_ACCEPT_MAGIC</code> is defined as the <code>keccka256</code> hash of the string <code>"ERC1820_ACCEPT_MAGIC"</code>.</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"> constant</span><span class="z-storage z-type"> internal</span><span> ERC1820_ACCEPT_MAGIC </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;ERC1820_ACCEPT_MAGIC&quot;</span><span>)</span><span>)</span><span>;</span></span></code></pre> <blockquote> <p>The reason to return <code>ERC1820_ACCEPT_MAGIC</code> instead of a boolean is to prevent cases where a contract fails to implement the <code>canImplementInterfaceForAddress</code> but implements a fallback function which does not throw. In this case, since <code>canImplementInterfaceForAddress</code> does not exist, the fallback function is called instead, executed without throwing and returns <code>1</code>. Thus making it appear as if <code>canImplementInterfaceForAddress</code> returned <code>true</code>.</p> </blockquote> <h3 id="manager">Manager</h3> <p>The manager of an address (regular account or a contract) is the only entity allowed to register implementations of interfaces for the address. By default, any address is its own manager.</p> <p>The manager can transfer its role to another address by calling <code>setManager</code> on the registry contract with the address for which to transfer the manager and the address of the new manager.</p> <p><strong><code>setManager</code> Function</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"> setManager</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addr</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _newManager</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>Sets <code>_newManager</code> as manager for <code>_addr</code>.</p> <p>The new manager will be able to call <code>setInterfaceImplementer</code> for <code>_addr</code>.</p> <p>If <code>_newManager</code> is <code>0x0</code>, the manager is reset to <code>_addr</code> itself as the manager.</p> <blockquote> <p><small><strong>identifier:</strong> <code>5df8122f</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_addr</code>: Address for which to set the new manager.</small><br /> <small><code>_newManager</code>: The address of the new manager for <code>_addr</code>. (Pass <code>0x0</code> to reset the manager to <code>_addr</code>.)</small></p> </blockquote> <p><strong><code>getManager</code> Function</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"> getManager</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"> 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></code></pre> <p>Get the manager of an address.</p> <blockquote> <p><small><strong>identifier:</strong> <code>3d584063</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_addr</code>: Address for which to return the manager.</small><br /> <small><strong>returns:</strong> Address of the manager for a given address.</small></p> </blockquote> <h2 id="rationale">Rationale</h2> <p>This standards offers a way for any type of address (externally owned and contracts) to implement an interface and potentially delegate the implementation of the interface to a proxy contract. This delegation to a proxy contract is necessary for externally owned accounts and useful to avoid redeploying existing contracts such as multisigs and DAOs.</p> <p>The registry can also act as a <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> cache in order to save gas when looking up if a contract implements a specific <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface. This cache is intentionally kept simple, without automatic cache update or invalidation. Anyone can easily and safely update the cache for any interface and any contract by calling the <code>updateERC165Cache</code> function.</p> <p>The registry is deployed using a keyless deployment method relying on a single-use deployment address to ensure no one controls the registry, thereby ensuring trust.</p> <h2 id="backward-compatibility">Backward Compatibility</h2> <p>This standard is backward compatible with <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>, as both methods MAY be implemented without conflicting with each other.</p> <h2 id="test-cases">Test Cases</h2> <p>Please check the <a rel="external" href="https://github.com/0xjac/ERC1820">0xjac/ERC1820</a> repository for the full test suite.</p> <h2 id="implementation">Implementation</h2> <p>The implementation is available in the repo: <a rel="external" href="https://github.com/0xjac/ERC1820">0xjac/ERC1820</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-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-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Forshtatalex@tabookey.com Yoav Weissyoav@tabookey.com https://wg-eips.ritovision.com/1706/ <h2 id="simple-summary">Simple Summary</h2> <p>The proposal that had been accepted changes security properties of a large portion of an existing contract code base that may be infeasible to update and validate. This proposal will make the old assumptions hold even after a network upgrade.</p> <h2 id="abstract">Abstract</h2> <p><a href="https://wg-eips.ritovision.com/1283/">EIP-1283</a> significantly lowers the gas costs of writing to contract's storage. This created a danger of a new kind of reentrancy attacks on existing contracts as Solidity by default grants a 'stipend' of 2300 gas to simple transfer calls. This danger is easily mitigated if SSTORE is not allowed in low gasleft state, without breaking the backward compatibility and the original intention of this EIP.</p> <h2 id="motivation">Motivation</h2> <p>An attack that is described in <a rel="external" href="https://medium.com/chainsecurity/constantinople-enables-new-reentrancy-attack-ace4088297d9">this article</a>. Explicitly specifying the call stipend as an invariant will have a positive effect on Ethereum protocol security: https://www.reddit.com/r/ethereum/comments/agdqsm/security_alert_ethereum_constantinople/ee5uvjt</p> <h2 id="specification">Specification</h2> <p>Add the following condition to the SSTORE opcode gas cost calculation:</p> <ul> <li>If <em>gasleft</em> is less than or equal to 2300, fail the current call frame with 'out of gas' exception.</li> </ul> <h2 id="rationale">Rationale</h2> <p>In order to keep in place the implicit reentrancy protection of existing contracts, transactions should not be allowed to modify state if the remaining gas is lower then the 2300 stipend given to 'transfer'/'send' in Solidity. These are other proposed remediations and objections to implementing them:</p> <ul> <li>Drop EIP-1283 and abstain from modifying SSTORE cost <ul> <li>EIP-1283 is an important update</li> <li>It was accepted and implemented on test networks and in clients.</li> </ul> </li> <li>Add a new call context that permits LOG opcodes but not changes to state. <ul> <li>Adds another call type beyond existing regular/staticcall</li> </ul> </li> <li>Raise the cost of SSTORE to dirty slots to &gt;=2300 gas <ul> <li>Makes net gas metering much less useful.</li> </ul> </li> <li>Reduce the gas stipend <ul> <li>Makes the stipend almost useless.</li> </ul> </li> <li>Increase the cost of writes to dirty slots back to 5000 gas, but add 4800 gas to the refund counter <ul> <li>Still doesn’t make the invariant explicit.</li> <li>Requires callers to supply more gas, just to have it refunded</li> </ul> </li> <li>Add contract metadata specifying per-contract EVM version, and only apply SSTORE changes to contracts deployed with the new version.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Performing SSTORE has never been possible with less than 5000 gas, so it does not introduce incompatibility to the Ethereum mainnet. Gas estimation should account for this requirement.</p> <h2 id="test-cases">Test Cases</h2> <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. 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-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-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-10T00:00:00+00:00 2026-02-11T14:49:28+00:00 Felix J Langehttps://github.com/fjl Martin Holst Swendehttps://github.com/holiman https://wg-eips.ritovision.com/1682/ <h2 id="abstract">Abstract</h2> <p>This EIP describes a scheme to charge for data in state, and 'archive' data which is no longer being paid for. It also describes how resurrection of 'archived' data happens.</p> <h2 id="motivation">Motivation</h2> <p>The Ethereum blockchain in its current form is not sustainable because it grows indefinitely. This is true of any blockchain, but Ethereum grows faster than most chains. Many implementation strategies to slow down growth exist. A common strategy is 'state pruning' which discards historical state, keeping only the active copy of contract data and a few recent versions to deal with short-range chain reorganizations. Several implementations also employ compression techniques to keep the active copy of the state as small as possible.</p> <p>A full node participating in consensus today requires storing large amounts of data even with advanced storage optimizations applied. Future storage requirements are unbounded because any data stored in a contract must be retained forever as dictated by the protocol. This EIP attempts to correct this by adding new consensus rules that put an upper bound on the size of the Ethereum state.</p> <p>Adding these new rules changes fundamental guarantees of the system and requires a hard fork. Users of Ethereum already pay for the creation and modification of accounts and their storage entries. Under the rules introduced in this EIP, users must also pay to keep accounts accessible. A similar rent scheme was proposed in <a rel="external" href="https://github.com/ethereum/EIPs/issues/35">EIP-103</a> but rejected even back then because the proposal would've upset peoples expectations. As implementers of Ethereum, we still feel that state rent is the right path to long-term sustainability of the Ethereum blockchain and that its undesirable implications can be overcome with off-protocol tooling and careful design.</p> <h2 id="specification">Specification</h2> <p>The cost of storing an account over time is called <code>rent</code>. The amount of <code>rent</code> due depends on the size of the account. The <code>ether</code> that is paid for <code>rent</code> is destroyed. The <code>rent</code> is deducted whenever an account is touched.</p> <p><code>rent</code> can be paid from the account's regular <code>balance</code> or from its 'rent balance'. Accounts can be endowed with <code>rent balance</code> through a new EVM opcode. When <code>rent</code> is charged, it is first taken from the <code>rent balance</code>. When <code>rent balance</code> is zero, it is instead charged from the account's regular <code>balance</code> instead.</p> <p>The reason to separate <code>balance</code> and <code>rent balance</code> is that certain contracts do not accept <code>ether</code> sends, or always send the entire balance off to some other destination. For these cases, a separate<code>rent balance</code> is required.</p> <p>When an account's <code>balance</code> is insufficient to pay rent, the account becomes <code>inactive</code>. Its storage and contract code are removed. Inactive accounts cannot be interacted with, i.e. it behaves as if it has no contract code.</p> <p>Inactive accounts can be restored by re-uploading their storage. To restore an inactive account <code>A</code>, a new account <code>B</code> is created with arbitrary code and its storage modified with <code>SSTORE</code> operations until it matches the storage root of <code>A</code>. Account <code>B</code> can restore <code>A</code> through the <code>RESTORETO</code> opcode. This means the cost of restoring an account is equivalent to recreating it via successive <code>SSTORE</code> operations.</p> <h3 id="changes-to-state">Changes To State</h3> <p>At the top level, a new key <code>size</code> is added to the accounts trie. This key tracks the total number of trie nodes across all accounts, including storage trie nodes. To track rent, the structure of account entries is changed as well.</p> <p>Before processing the block in which this EIP becomes active, clients iterate the whole state once to count the number of trie nodes and to change the representation of all accounts to the new format.</p> <h4 id="account-representation">Account Representation</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>account = [nonce, balance, storageroot, codehash, rentbalance, rentblock, storagesize]</span></span></code></pre> <p>Each account gets three additional properties: <code>rentbalance</code>, <code>rentblock</code> and <code>storagesize</code>.</p> <p>The <code>rentbalace</code> field tracks the amount of <code>rent balance</code> available to the account. Upon self-destruction any remaining <code>rent balance</code> is transferred to the beneficiary. Any modification of the account recomputes its current <code>rent balance</code>.</p> <p>The <code>rentblock</code> field tracks the block number in which the <code>rent balance</code> was last recomputed. Upon creation, this field is initialized with the current block number. <code>rentblock</code> is also updated with the current block number whenever the account is modified.</p> <p>The <code>storagesize</code> field tracks the amount of storage related to the account. It is a number containing the number of storage slots currently set. The <code>storagesize</code> of an inactive account is zero.</p> <h3 id="charging-rent">Charging Rent</h3> <p>There is a new protocol constant <code>MAX_STORAGE_SIZE</code> that specifies the upper bound on the number of state tree nodes:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-constant">MAX_STORAGE_SIZE</span><span class="z-keyword"> =</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">32</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> ~160GB of state</span></span></code></pre> <p>A 'storage fee factor' for each block is derived from this constant such that fees increase as the limit is approached.</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"> storagefee_factor</span><span>(</span><span class="z-variable z-parameter z-function">block</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> ramp</span><span class="z-keyword"> =</span><span class="z-constant"> MAX_STORAGE_SIZE</span><span class="z-keyword"> /</span><span> (</span><span class="z-constant">MAX_STORAGE_SIZE</span><span class="z-keyword"> -</span><span> total_storage_size</span><span>(</span><span>block</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">22</span><span class="z-keyword"> *</span><span> ramp</span></span></code></pre> <p>When a block is processed, <code>rent</code> is deducted from all accounts modified by transactions in the block after the transactions have been processed. The amount due for each account is based on the account's storage size.</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"> rent</span><span>(</span><span class="z-variable z-parameter z-function">prestate</span><span>,</span><span class="z-variable z-parameter z-function"> poststate</span><span>,</span><span class="z-variable z-parameter z-function"> addr</span><span>,</span><span class="z-variable z-parameter z-function"> currentblock</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> fee</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> b</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span>prestate</span><span>[</span><span>addr</span><span>]</span><span>.</span><span>rentblock</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>,</span><span> currentblock</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> fee</span><span class="z-keyword"> +=</span><span> storagefee_factor</span><span>(</span><span>b</span><span>)</span><span class="z-keyword"> *</span><span> prestate</span><span>[</span><span>addr</span><span>]</span><span>.</span><span>storagesize</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> fee</span><span class="z-keyword"> +</span><span> storagefee_factor</span><span>(</span><span>currentblock</span><span>)</span><span class="z-keyword"> *</span><span> poststate</span><span>[</span><span>addr</span><span>]</span><span>.</span><span>storagesize</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"> charge_rent</span><span>(</span><span class="z-variable z-parameter z-function">prestate</span><span>,</span><span class="z-variable z-parameter z-function"> poststate</span><span>,</span><span class="z-variable z-parameter z-function"> addr</span><span>,</span><span class="z-variable z-parameter z-function"> currentblock</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> fee</span><span class="z-keyword"> =</span><span> rent</span><span>(</span><span>prestate</span><span>,</span><span> poststate</span><span>,</span><span> addr</span><span>,</span><span> currentblock</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> fee</span><span class="z-keyword"> &lt;=</span><span> poststate</span><span>[</span><span>addr</span><span>]</span><span>.</span><span>rentbalance</span><span>:</span></span> <span class="giallo-l"><span> poststate</span><span>[</span><span>addr</span><span>]</span><span>.</span><span>rentbalance</span><span class="z-keyword"> -=</span><span> fee</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> fee</span><span class="z-keyword"> -=</span><span> poststate</span><span>[</span><span>addr</span><span>]</span><span>.</span><span>rentbalance</span></span> <span class="giallo-l"><span> poststate</span><span>[</span><span>addr</span><span>]</span><span>.</span><span>rentbalance</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> poststate</span><span>[</span><span>addr</span><span>]</span><span>.</span><span>balance</span><span class="z-keyword"> -=</span><span class="z-support"> min</span><span>(</span><span>poststate</span><span>[</span><span>addr</span><span>]</span><span>.</span><span>balance</span><span>,</span><span> fee</span><span>)</span></span> <span class="giallo-l"><span> poststate</span><span>[</span><span>addr</span><span>]</span><span>.</span><span>rentblock</span><span class="z-keyword"> =</span><span> currentblock</span></span></code></pre><h3 id="new-evm-opcodes">New EVM Opcodes</h3> <h4 id="payrent-amount-addr"><code>PAYRENT &lt;amount&gt; &lt;addr&gt;</code></h4> <p>At any time, the <code>rent balance</code> of an account may be topped up by the <code>PAYRENT</code> opcode. <code>PAYRENT</code> deducts the given amount of <code>ether</code> from the account executing the opcode and adds it to the <code>rent balance</code> of the address specified as beneficiary.</p> <p>Any participant can pay the rent for any other participant.</p> <p>Gas cost: TBD</p> <h4 id="rentbalance-addr"><code>RENTBALANCE &lt;addr&gt;</code></h4> <p>The <code>rent balance</code> of an account may be queried through the <code>RENTBALANCE</code> opcode. It pushes the <code>rentbalance</code> field of the given address to the stack.</p> <p>Gas cost: like <code>EXTCODEHASH</code>.</p> <h4 id="ssize-addr"><code>SSIZE &lt;addr&gt;</code></h4> <p>This opcode pushes the <code>storagesize</code> field of the given account to the stack.</p> <p>Gas cost: like <code>EXTCODEHASH</code>.</p> <h4 id="restoreto-addr-codeaddr"><code>RESTORETO &lt;addr&gt; &lt;codeaddr&gt;</code></h4> <p>This opcode restores the inactive account at the given address. This is a bit like <code>SELFDESTRUCT</code> but has more specific semantics.</p> <p>The account at <code>addr</code> must be <code>inactive</code> (i.e. have <code>storagesize</code> zero) and its <code>storageroot</code> must match the <code>storageroot</code> of the contract executing <code>RESTORETO</code>. The <code>codeaddr</code> specifies the address of a contract from which code is taken. The code of the <code>codeaddr</code> account must match the <code>codehash</code> of <code>addr</code>.</p> <p>If all these preconditions are met, <code>RESTORETO</code> transfers the storage of the account executing the opcode to <code>addr</code> and resets its <code>storagesize</code> to the full size of the storage. The code of <code>addr</code> is restored as well. <code>RESTORETO</code> also transfers any remaining balance and rent balance to <code>addr</code>. The contract executing <code>RESTORETO</code> is deleted.</p> <p>Gas cost: TBD</p> <h2 id="rationale">Rationale</h2> <h3 id="why-do-we-need-a-separate-rent-balance">Why do we need a separate rent balance?</h3> <p>Accounts need a separate rent balance because some contracts are non-payable, i.e. they reject regular value transfers. Such contracts might not be able to keep themselves alive, but users of those contracts can keep them alive by paying rent for them.</p> <p>Having the additional balance also makes things easier for contracts that hold balance on behalf of a user. Consider the canonical crowdfunding example, a contract which changes behavior once a certain balance is reached and which tracks individual user's balances. Deducting rent from the main balance of the contract would mess up the contract's accounting, leaving it unable to pay back users accurately if the threshold balance isn't reached.</p> <h3 id="why-restoration">Why restoration?</h3> <p>One of the fundamental guarantees provided by Ethereum is that changes to contract storage can only be made by the contract itself and storage will persist forever. If you hold a token balance in a contract, you'll have those tokens forever. By adding restoration, we can maintain this guarantee to a certain extent.</p> <h3 id="implementation-impact">Implementation Impact</h3> <p>The proposed changes tries to fit within the existing state transition model. Note that there is no mechanism for deactivating accounts the moment they can't pay rent. Users must touch accounts to ensure their storage is removed because we'd need to track all accounts and their rent requirements in an auxlilary data structure otherwise.</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> 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-31T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Mudgenick@perfectabstractions.com https://wg-eips.ritovision.com/1538/ <p>Replaced by <a href="https://wg-eips.ritovision.com/2535/">EIP-2535 Diamond Standard</a>.</p> <h2 id="simple-summary">Simple Summary</h2> <p>This standard provides a contract architecture that makes upgradeable contracts flexible, unlimited in size, and transparent.</p> <p>A transparent contract publicly documents the full history of all changes made to it.</p> <p>All changes to a transparent contract are reported in a standard format.</p> <h2 id="abstract">Abstract</h2> <p>A transparent contract is a proxy contract design pattern that provides the following:</p> <ol> <li>A way to add, replace and remove multiple functions of a contract atomically (at the same time).</li> <li>Standard events to show what functions are added, replaced and removed from a contract, and why the changes are made.</li> <li>A standard way to query a contract to discover and retrieve information about all functions exposed by it.</li> <li>Solves the 24KB maximum contract size limitation, making the maximum contract size of a transparent contract practically unlimited. This standard makes the worry about contract size a thing of the past.</li> <li>Enables an upgradeable contract to become immutable in the future if desired.</li> </ol> <h2 id="motivation">Motivation</h2> <p>A fundamental benefit of Ethereum contracts is that their code is immutable, thereby acquiring trust by trustlessness. People do not have to trust others if it is not possible for a contract to be changed.</p> <p>However, a fundamental problem with trustless contracts that cannot be changed is that they cannot be changed.</p> <h4 id="bugs">Bugs</h4> <p>Bugs and security vulnerabilities are unwittingly written into immutable contracts that ruin them.</p> <h4 id="improvements">Improvements</h4> <p>Immutable, trustless contracts cannot be improved, resulting in increasingly inferior contracts over time.</p> <p>Contract standards evolve, new ones come out. People, groups and organizations learn over time what people want and what is better and what should be built next. Contracts that cannot be improved not only hold back the authors that create them, but everybody who uses them.</p> <h4 id="upgradeable-contracts-vs-centralized-private-database">Upgradeable Contracts vs. Centralized Private Database</h4> <p>Why have an upgradeable contract instead of a centralized, private, mutable database? Here are some reasons:</p> <ol> <li>Because of the openness of storage data and verified code, it is possible to show a provable history of trustworthiness.</li> <li>Because of the openness, bad behavior can be spotted and reported when it happens.</li> <li>Independent security and domain experts can review the change history of contracts and vouch for their history of trustworthiness.</li> <li>It is possible for an upgradeable contract to become immutable and trustless.</li> <li>An upgradeable contract can have parts of it that are not upgradeable and so are partially immutable and trustless.</li> </ol> <h4 id="immutability">Immutability</h4> <p>In some cases immutable, trustless contracts are the right fit. This is the case when a contract is only needed for a short time or it is known ahead of time that there will never be any reason to change or improve it.</p> <h3 id="middle-ground">Middle Ground</h3> <p>Transparent contracts provide a middle ground between immutable trustless contracts that can't be improved and upgradeable contracts that can't be trusted.</p> <h3 id="purposes">Purposes</h3> <ol> <li>Create upgradeable contracts that earn trust by showing a provable history of trustworthiness.</li> <li>Document the development of contracts so their development and change is provably public and can be understood.</li> <li>Create upgradeable contracts that can become immutable in the future if desired.</li> <li>Create contracts that are not limited by a max size.</li> </ol> <h3 id="benefits-use-cases">Benefits &amp; Use Cases</h3> <p>This standard is for use cases that benefit from the following:</p> <ol> <li>The ability to add, replace or remove multiple functions of a contract atomically (at the same time).</li> <li>Each time a function is added, replaced or removed, it is documented with events.</li> <li>Build trust over time by showing all changes made to a contract.</li> <li>Unlimited contract size.</li> <li>The ability to query information about functions currently supported by the contract.</li> <li>One contract address that provides all needed functionality and never needs to be replaced by another contract address.</li> <li>The ability for a contract to be upgradeable for a time, and then become immutable.</li> <li>Add trustless guarantees to a contract with "unchangeable functions".</li> </ol> <h3 id="new-software-possibilities">New Software Possibilities</h3> <p>This standard enables a form of contract version control software to be written.</p> <p>Software and user interfaces can be written to filter the <code>FunctionUpdate</code> and <code>CommitMessage</code> events of a contract address. Such software can show the full history of changes of any contract that implements this standard.</p> <p>User interfaces and software can also use this standard to assist or automate changes of contracts.</p> <h2 id="specification">Specification</h2> <blockquote> <p><strong>Note:</strong> The solidity <code>delegatecall</code> opcode enables a contract to execute a function from another contract, but it is executed as if the function was from the calling contract. Essentially <code>delegatecall</code> enables a contract to "borrow" another contract's function. Functions executed with <code>delegatecall</code> affect the storage variables of the calling contract, not the contract where the functions are defined.</p> </blockquote> <h3 id="general-summary">General Summary</h3> <p>A transparent contract delegates or forwards function calls to it to other contracts using <code>delegatecode</code>.</p> <p>A transparent contract has an <code>updateContract</code> function that enables multiple functions to be added, replaced or removed.</p> <p>An event is emitted for every function that is added, replaced or removed so that all changes to a contract can be tracked in a standard way.</p> <p>A transparent contract is a contract that implements and complies with the design points below.</p> <h3 id="terms">Terms</h3> <ol> <li>In this standard a <strong>delegate contract</strong> is a contract that a transparent contract fallback function forwards function calls to using <code>delegatecall</code>.</li> <li>In this standard an <strong>unchangeable function</strong> is a function that is defined directly in a transparent contract and so cannot be replaced or removed.</li> </ol> <h3 id="design-points">Design Points</h3> <p>A contract is a transparent contract if it implements the following design points:</p> <ol> <li>A transparent contract is a contract that contains a fallback function, a constructor, and zero or more unchangeable functions that are defined directly within it.</li> <li>The constructor of a transparent contract associates the <code>updateContract</code> function with a contract that implements the ERC1538 interface. The <code>updateContract</code> function can be an "unchangeable function" that is defined directly in the transparent contract or it can be defined in a delegate contract. Other functions can also be associated with contracts in the constructor.</li> <li>After a transparent contract is deployed functions are added, replaced and removed by calling the <code>updateContract</code> function.</li> <li>The <code>updateContract</code> function associates functions with contracts that implement those functions, and emits the <code>CommitMessage</code> and <code>FunctionUpdate</code> events that document function changes.</li> <li>The <code>FunctionUpdate</code> event is emitted for each function that is added, replaced or removed. The <code>CommitMessage</code> event is emitted one time for each time the <code>updateContract</code> function is called and is emitted after any <code>FunctionUpdate</code> events are emitted.</li> <li>The <code>updateContract</code> function can take a list of multiple function signatures in its <code>_functionSignatures</code> parameter and so add/replace/remove multiple functions at the same time.</li> <li>When a function is called on a transparent contract it executes immediately if it is an "unchangeable function". Otherwise the fallback function is executed. The fallback function finds the delegate contract associated with the function and executes the function using <code>delegatecall</code>. If there is no delegate contract for the function then execution reverts.</li> <li>The source code of a transparent contract and all delegate contracts used by it are publicly viewable and verified.</li> </ol> <p>The transparent contract address is the address that users interact with. The transparent contract address never changes. Only delegate addresses can change by using the <code>updateContracts</code> function.</p> <p>Typically some kind of authentication is needed for adding/replacing/removing functions from a transparent contract, <strong>however the scheme for authentication or ownership is not part of this standard</strong>.</p> <h3 id="example">Example</h3> <p>Here is an example of an implementation of a transparent contract. Please note that the example below is an <strong>example only. It is not the standard</strong>. A contract is a transparent contract when it implements and complies with the design points listed above.</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.7</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"> ExampleTransparentContract</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> owner of the contract</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> internal</span><span> contractOwner</span><span>;</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-comment"> maps functions to the delegate contracts that execute the functions</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> funcId =&gt; delegate contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes4</span><span class="z-keyword"> =&gt;</span><span class="z-support"> address</span><span>)</span><span class="z-storage z-type"> internal</span><span> delegates</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> maps each function signature to its position in the funcSignatures array.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> signature =&gt; index+1</span></span> <span class="giallo-l"><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"> uint256</span><span>)</span><span class="z-storage z-type"> internal</span><span> funcSignatureToIndex</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"> CommitMessage</span><span>(</span><span class="z-support">string</span><span class="z-variable"> message</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FunctionUpdate</span><span>(</span><span class="z-support">bytes4</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> functionId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> oldDelegate</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> newDelegate</span><span>, </span><span class="z-support">string</span><span class="z-variable"> functionSignature</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"> this is an example of an &quot;unchangeable function&quot;.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> return the delegate contract address for the supplied function signature</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> delegateAddress</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"> _functionSignature</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"> require</span><span>(</span><span>funcSignatureToIndex</span><span>[</span><span class="z-support">bytes</span><span>(</span><span>_functionSignature</span><span>)</span><span>]</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Function signature not found.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> delegates</span><span>[</span><span class="z-support">bytes4</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-support">bytes</span><span>(</span><span>_functionSignature</span><span>)</span><span>)</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"> add a function using the updateContract function</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> this is an internal helper function</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addFunction</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _erc1538Delegate</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> contractAddress</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"> _functionSignatures</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"> _commitMessage</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 0x03A9BCCF == bytes4(keccak256(&quot;updateContract(address,string,string)&quot;))</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> funcdata </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span><span class="z-constant">0x03A9BCCF</span><span>,</span><span> contractAddress</span><span>,</span><span> _functionSignatures</span><span>,</span><span> _commitMessage</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> success</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> success </span><span class="z-keyword">:=</span><span class="z-entity z-name"> delegatecall</span><span>(</span><span>gas</span><span>,</span><span> _erc1538Delegate</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>funcdata</span><span>,</span><span class="z-constant"> 0x20</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>funcdata</span><span>)</span><span>,</span><span> funcdata</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-keyword"> require</span><span>(</span><span>success</span><span>,</span><span class="z-string"> &quot;Adding a function failed&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 class="z-storage z-type"> constructor</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _erc1538Delegate</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> contractOwner </span><span class="z-keyword">=</span><span class="z-variable z-language"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> OwnershipTransferred</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> adding ERC1538 updateContract function</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> signature </span><span class="z-keyword">=</span><span class="z-string"> &quot;updateContract(address,string,string)&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span> funcId </span><span class="z-keyword">=</span><span class="z-support"> bytes4</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span>signature</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> delegates</span><span>[</span><span>funcId</span><span>]</span><span class="z-keyword"> =</span><span> _erc1538Delegate</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> FunctionUpdate</span><span>(</span><span>funcId</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span> _erc1538Delegate</span><span>,</span><span class="z-support"> string</span><span>(</span><span>signature</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> CommitMessage</span><span>(</span><span class="z-string">&quot;Added ERC1538 updateContract function at contract creation&quot;</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"> associate &quot;unchangeable functions&quot; with this transparent contract address</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> prevents function selector clashes with delegate contract functions</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> uses the updateContract function</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span> functions </span><span class="z-keyword">=</span><span class="z-string"> &quot;delegateAddress(string)&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> addFunction</span><span>(</span><span>_erc1538Delegate</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> functions</span><span>,</span><span class="z-string"> &quot;Associating unchangeable functions&quot;</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"> adding ERC1538Query interface functions</span></span> <span class="giallo-l"><span> functions </span><span class="z-keyword">=</span><span class="z-string"> &quot;functionByIndex(uint256)functionExists(string)delegateAddresses()delegateFunctionSignatures(address)functionById(bytes4)functionBySignature(string)functionSignatures()totalFunctions()&quot;</span><span>;</span><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> &quot;0x01234567891011121314&quot; is an example address of an ERC1538Query delegate contract</span></span> <span class="giallo-l"><span class="z-entity z-name"> addFunction</span><span>(</span><span>_erc1538Delegate</span><span>,</span><span class="z-constant"> 0x01234567891011121314</span><span>,</span><span> functions</span><span>,</span><span class="z-string"> &quot;Adding ERC1538Query functions&quot;</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"> additional functions could be added at this point</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"> Making the fallback function payable makes it work for delegate contract functions </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> that are payable and not payable.</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</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-comment"> //</span><span class="z-comment"> Delegate every function call to a delegate contract</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> delegate </span><span class="z-keyword">=</span><span> delegates</span><span>[</span><span class="z-variable z-language">msg</span><span>.</span><span>sig</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>delegate </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;Function does not exist.&quot;</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-storage z-type"> let</span><span> ptr </span><span class="z-keyword">:=</span><span class="z-entity z-name"> mload</span><span>(</span><span class="z-constant">0x40</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> calldatacopy</span><span>(</span><span>ptr</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span> calldatasize</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>gas</span><span>,</span><span> delegate</span><span>,</span><span> ptr</span><span>,</span><span> 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> size </span><span class="z-keyword">:=</span><span> returndatasize</span></span> <span class="giallo-l"><span class="z-entity z-name"> returndatacopy</span><span>(</span><span>ptr</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span> size</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 class="z-keyword">revert</span><span>(</span><span>ptr</span><span>,</span><span> size</span><span>)</span><span>}</span></span> <span class="giallo-l"><span> default </span><span>{</span><span class="z-keyword">return</span><span> (</span><span>ptr</span><span>,</span><span> size</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> <p>As can be seen in the above example, every function call is delegated to a delegate contract, unless the function is defined directly in the transparent contract (making it an unchangeable function).</p> <p>The constructor function adds the <code>updateContract</code> function to the transparent contract, which is then used to add other functions to the transparent contract.</p> <p>Each time a function is added to a transparent contract the events <code>CommitMessage</code> and <code>FunctionUpdate</code> are emitted to document exactly what functions where added or replaced and why.</p> <p>The delegate contract that implements the <code>updateContract</code> function implements the following interface:</p> <h3 id="erc1538-interface">ERC1538 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"> ^0.5.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"> ERC1538 Transparent Contract Standard</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</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 0x61455567</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC1538</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 one or a set of functions are updated in a transparent contract.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The message string should give a short description of the change and why</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the change was made.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CommitMessage</span><span>(</span><span class="z-support">string</span><span class="z-variable"> message</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 for each function that is updated in a transparent contract.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> functionId is the bytes4 of the keccak256 of the function signature.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> oldDelegate is the delegate contract address of the old delegate contract if</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the function is being replaced or removed.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> oldDelegate is the zero value address(0) if a function is being added for the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> first time.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> newDelegate is the delegate contract address of the new delegate contract if </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the function is being added for the first time or if the function is being </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> replaced.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> newDelegate is the zero value address(0) if the function is being removed.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FunctionUpdate</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"> functionId</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"> oldDelegate</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"> newDelegate</span><span>, </span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> functionSignature</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"> Updates functions in a transparent contract.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> If the value of _delegate is zero then the functions specified </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> in _functionSignatures are removed.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If the value of _delegate is a delegate contract address then the functions </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> specified in _functionSignatures will be delegated to that 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"> _delegate</span><span class="z-comment"> The address of a delegate contract to delegate to or zero</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> to remove functions. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _functionSignatures</span><span class="z-comment"> A list of function signatures listed one after the other</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _commitMessage</span><span class="z-comment"> A short description of the change and why it is made</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This message is passed to the CommitMessage event. </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateContract</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _delegate</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"> _functionSignatures</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"> _commitMessage</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span><span> </span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="function-signatures-string-format">Function Signatures String Format</h3> <p>The text format for the <code>_functionSignatures</code> parameter is simply a string of function signatures. For example: <code>"myFirstFunction()mySecondFunction(string)"</code> This format is easy to parse and is concise.</p> <p>Here is an example of calling the <code>updateContract</code> function that adds the ERC721 standard functions to a transparent contract:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">functionSignatures</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">approve(address,uint256)balanceOf(address)getApproved(uint256)isApprovedForAll(address,address)ownerOf(uint256)safeTransferFrom(address,address,uint256)safeTransferFrom(address,address,uint256,bytes)setApprovalForAll(address,bool)transferFrom(address,address,uint256)</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-variable z-other">tx</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> transparentContract</span><span>.</span><span class="z-entity z-name">updateContract</span><span>(</span><span class="z-variable z-other">erc721Delegate</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-variable z-other"> functionSignatures</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Adding ERC721 functions</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span></code></pre><h3 id="removing-functions">Removing Functions</h3> <p>Functions are removed by passing <code>address(0)</code> as the first argument to the <code>updateContract</code> function. The list of functions that are passed in are removed.</p> <h3 id="source-code-verification">Source Code Verification</h3> <p>The transparent contract source code and the source code for the delegate contracts should be verified in a provable way by a third party source such as etherscan.io.</p> <!-- A transparent contract must implement the [ERC-165 Standard Interface Detection standard](./00165.md) via a delegate contract by adding the `supportsInterface` function using the `updateContract` function. The interfaceID for the ERC1538 standard is `0x61455567`. --> <h3 id="function-selector-clash">Function Selector Clash</h3> <p>A function selector clash occurs when a function is added to a contract that hashes to the same four-byte hash as an existing function. This is unlikely to occur but should be prevented in the implementation of the <code>updateContract</code> function. See the <a rel="external" href="https://github.com/mudgen/transparent-contracts-erc1538">reference implementation of ERC1538</a> to see an example of how function clashes can be prevented.</p> <h3 id="erc1538query">ERC1538Query</h3> <p>Optionally, the function signatures of a transparent contract can be stored in an array in the transparent contract and queried to get what functions the transparent contract supports and what their delegate contract addresses are.</p> <p>The following is an optional interface for querying function information from a transparent 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.5.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"> ERC1538Query</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"> Gets the total number of functions the transparent contract has.</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 functions the transparent contract has,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> not including the fallback function.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalFunctions</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></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Gets information about a specific function</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 `_index` &gt;= `totalFunctions()`</span></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"> The index position of a function signature that is stored in an 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"> function signature, the function selector and the delegate contract address</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> functionByIndex</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _index</span><span>)</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"> 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"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> functionSignature</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-variable"> functionId</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> delegate</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"> @notice</span><span class="z-comment"> Checks to see if a function 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"> The</span><span class="z-comment"> function signature to check</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 function exists, false otherwise</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> functionExists</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"> _functionSignature</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Gets all the function signatures of functions supported by the transparent 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"> A</span><span class="z-comment"> string containing a list of function signatures</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> functionSignatures</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 class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Gets all the function signatures supported by a specific delegate 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"> _delegate</span><span class="z-comment"> The delegate 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"> A</span><span class="z-comment"> string containing a list of function signatures</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> delegateFunctionSignatures</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _delegate</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 class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Gets the delegate contract address that supports the given function 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"> The</span><span class="z-comment"> function signature</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"> delegate contract address</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> delegateAddress</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"> _functionSignature</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Gets information about a function</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 no function is found</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _functionId</span><span class="z-comment"> The id of the function to get information about</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"> function signature and the contract address</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> functionById</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable z-parameter z-function"> _functionId</span><span>)</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"> 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"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> signature</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> delegate</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"> @notice</span><span class="z-comment"> Get all the delegate contract addresses used by the transparent 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"> An</span><span class="z-comment"> array of all delegate contract addresses</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> delegateAddresses</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></span></code></pre> <p>See the <a rel="external" href="https://github.com/mudgen/transparent-contracts-erc1538">reference implementation of ERC1538</a> to see how this is implemented.</p> <p>The text format for the list of function signatures returned from the <code>delegateFunctionSignatures</code> and <code>functionSignatures</code> functions is simply a string of function signatures. Here is an example of such a string: <code>"approve(address,uint256)balanceOf(address)getApproved(uint256)isApprovedForAll(address,address)ownerOf(uint256)safeTransferFrom(address,address,uint256)safeTransferFrom(address,address,uint256,bytes)setApprovalForAll(address,bool)transferFrom(address,address,uint256)"</code></p> <h3 id="how-to-deploy-a-transparent-contract">How To Deploy A Transparent Contract</h3> <ol> <li>Create and deploy to a blockchain a contract that implements the ERC1538 interface. You can skip this step if there is already such a contract deployed to the blockchain.</li> <li>Create your transparent contract with a fallback function as given above. Your transparent contract also needs a constructor that adds the <code>updateContract</code> function.</li> <li>Deploy your transparent contract to a blockchain. Pass in the address of the ERC1538 delegate contract to your constructor if it requires it.</li> </ol> <p>See the <a rel="external" href="https://github.com/mudgen/transparent-contracts-erc1538">reference implementation</a> for examples of these contracts.</p> <h3 id="wrapper-contract-for-delegate-contracts-that-depend-on-other-delegate-contracts">Wrapper Contract for Delegate Contracts that Depend on Other Delegate Contracts</h3> <p>In some cases some delegate contracts may need to call external/public functions that reside in other delegate contracts. A convenient way to solve this problem is to create a contract that contains empty implementations of functions that are needed and import and extend this contract in delegate contracts that call functions from other delegate contracts. This enables delegate contracts to compile without having to provide implementations of the functions that are already given in other delegate contracts. This is a way to save gas, prevent reaching the max contract size limit, and prevent duplication of code. This strategy was given by @amiromayer. <a rel="external" href="https://github.com/ethereum/EIPs/issues/1538#issuecomment-451985155">See his comment for more information.</a> Another way to solve this problem is to use assembly to call functions provided by other delegate contracts.</p> <h3 id="decentralized-authority">Decentralized Authority</h3> <p>It is possible to extend this standard to add consensus functionality such as an approval function that multiple different people call to approve changes before they are submitted with the <code>updateContract</code> function. Changes only go into effect when the changes are fully approved. The <code>CommitMessage</code> and <code> FunctionUpdate</code> events should only be emitted when changes go into effect.</p> <h2 id="security">Security</h2> <blockquote> <p>This standard refers to <strong>owner(s)</strong> as one or more individuals that have the power to add/replace/remove functions of an upgradeable contract.</p> </blockquote> <h3 id="general">General</h3> <p>The owners(s) of an upgradeable contract have the ability to alter, add or remove data from the contract's data storage. Owner(s) of a contract can also execute any arbitrary code in the contract on behalf of any address. Owners(s) can do these things by adding a function to the contract that they call to execute arbitrary code. This is an issue for upgradeable contracts in general and is not specific to transparent contracts.</p> <blockquote> <p><strong>Note:</strong> The design and implementation of contract ownership is <strong>not</strong> part of this standard. The examples given in this standard and in the reference implementation are just <strong>examples</strong> of how it could be done.</p> </blockquote> <h3 id="unchangeable-functions">Unchangeable Functions</h3> <p>"Unchangeable functions" are functions defined in a transparent contract itself and not in a delegate contract. The owner(s) of a transparent contract are not able to replace these functions. The use of unchangeable functions is limited because in some cases they can still be manipulated if they read or write data to the storage of the transparent contract. Data read from the transparent contract's storage could have been altered by the owner(s) of the contract. Data written to the transparent contract's storage can be undone or altered by the owner(s) of the contract.</p> <p>In some cases unchangeble functions add trustless guarantees to a transparent contract.</p> <h3 id="transparency">Transparency</h3> <p>Contracts that implement this standard emit an event every time a function is added, replaced or removed. This enables people and software to monitor the changes to a contract. If any bad acting function is added to a contract then it can be seen. To comply with this standard all source code of a transparent contract and delegate contracts must be publicly available and verified.</p> <p>Security and domain experts can review the history of change of any transparent contract to detect any history of foul play.</p> <h2 id="rationale">Rationale</h2> <h3 id="string-of-function-signatures-instead-of-bytes4-array-of-function-selectors">String of Function Signatures Instead of bytes4[] Array of Function Selectors</h3> <p>The <code>updateContract</code> function takes a <code>string</code> list of functions signatures as an argument instead of a <code>bytes4[]</code> array of function selectors for three reasons:</p> <ol> <li>Passing in function signatures enables the implementation of <code>updateContract</code> to prevent selector clashes.</li> <li>A major part of this standard is to make upgradeable contracts more transparent by making it easier to see what has changed over time and why. When a function is added, replaced or removed its function signature is included in the FunctionUpdate event that is emitted. This makes it relatively easy to write software that filters the events of a contract to display to people what functions have been added/removed and changed over time without needing access to the source code or ABI of the contract. If only four-byte function selectors were provided this would not be possible.</li> <li>By looking at the source code of a transparent contract it is not possible to see all the functions that it supports. This is why the ERC1538Query interface exists, so that people and software have a way to look up and examine or show all functions currently supported by a transparent contract. Function signatures are used so that ERC1538Query functions can show them.</li> </ol> <h3 id="gas-considerations">Gas Considerations</h3> <p>Delegating function calls does have some gas overhead. This is mitigated in two ways:</p> <ol> <li>Delegate contracts can be small, reducing gas costs. Because it costs more gas to call a function in a contract with many functions than a contract with few functions.</li> <li>Because transparent contracts do not have a max size limitation it is possible to add gas optimizing functions for use cases. For example someone could use a transparent contract to implement the ERC721 standard and implement batch transfer functions from the <a rel="external" href="https://github.com/ethereum/EIPs/issues/1412">ERC1412 standard</a> to help reduce gas (and make batch transfers more convenient).</li> </ol> <h3 id="storage">Storage</h3> <p>The standard does not specify how data is stored or organized by a transparent contract. But here are some suggestions:</p> <p><strong>Inherited Storage</strong></p> <ol> <li> <p>The storage variables of a transparent contract consist of the storage variables defined in the transparent contract source code and the source code of delegate contracts that have been added.</p> </li> <li> <p>A delegate contract can use any storage variable that exists in a transparent contract as long as it defines within it all the storage variables that exist, in the order that they exist, up to and including the ones being used.</p> </li> <li> <p>A delegate contract can create new storage variables as long as it has defined, in the same order, all storage variables that exist in the transparent contract.</p> </li> </ol> <p>Here is a simple way inherited storage could be implemented:</p> <ol> <li>Create a storage contract that contains the storage variables that your transparent contract and delegate contracts will use.</li> <li>Make your delegate contracts inherit the storage contract.</li> <li>If you want to add a new delegate contract that adds new storage variables then create a new storage contract that adds the new storage variables and inherits from the old storage contract. Use your new storage contract with your new delegate contract.</li> <li>Repeat steps 2 or 3 for every new delegate contract.</li> </ol> <p><strong>Unstructured Storage</strong></p> <p>Assembly is used to store and read data at specific storage locations. An advantage to this approach is that previously used storage locations don't have to be defined or mentioned in a delegate contract if they aren't used by it.</p> <p><strong>Eternal Storage</strong></p> <p>Data can be stored using a generic API based on the type of data. <a rel="external" href="https://github.com/ethereum/EIPs/issues/930">See ERC930 for more information.</a></p> <h3 id="becoming-immutable">Becoming Immutable</h3> <p>It is possible to make a transparent contract become immutable. This is done by calling the <code>updateContract</code> function to remove the <code>updateContract</code> function. With this gone it is no longer possible to add, replace and remove functions.</p> <h3 id="versions-of-functions">Versions of Functions</h3> <p>Software or a user can verify what version of a function is called by getting the delegate contract address of the function. This can be done by calling the <code>delegateAddress</code> function from the ERC1538Query interface if it is implemented. This function takes a function signature as an argument and returns the delegate contract address where it is implemented.</p> <h3 id="best-practices-tools-and-more-information">Best Practices, Tools and More Information</h3> <blockquote> <p>More information, tools, tutorials and best practices concerning transparent contracts need to be developed and published.</p> </blockquote> <p>Below is a growing list of articles concerning transparent contracts and their use. If you have an article about transparent contracts you would like to share then please submit a comment to this issue about it to get it added.</p> <p><a rel="external" href="https://coinjournal.net/erc1538-future-proofing-smart-contacts-and-tokens/">ERC1538: Future Proofing Smart Contracts and Tokens</a></p> <p><a rel="external" href="https://www.crypto-economy.net/en/ethereum-eth-erc1538-transparent-contract-standard/">The ERC1538 improving towards the “transparent contract” standard</a></p> <h3 id="inspiration">Inspiration</h3> <p>This standard was inspired by ZeppelinOS's implementation of <a rel="external" href="https://github.com/zeppelinos/labs/tree/master/upgradeability_with_vtable">Upgradeability with vtables</a>.</p> <p>This standard was also inspired by the design and implementation of the <a rel="external" href="https://etherscan.io/address/0xc1eab49cf9d2e23e43bcf23b36b2be14fc2f8838#code">Mokens contract</a> from the <a rel="external" href="https://github.com/Mokens/MIPs/blob/master/MIPS/mip-2-Goals-and-Objectives.md">Mokens project</a>. The Mokens contract has been <a rel="external" href="https://etherscan.io/address/0x0ac5637fe62ec14fd9e237a81a9679d4adef701f#code">upgraded to implement this standard</a>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard makes a contract compatible with future standards and functionality because new functions can be added and existing functions can be replaced or removed.</p> <p>This standard future proofs a contract.</p> <h2 id="implementation">Implementation</h2> <p>A reference implementation of this standard is given in the <a rel="external" href="https://github.com/mudgen/transparent-contracts-erc1538">transparent-contracts-erc1538</a> repository.</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-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-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-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 Vittorio Minacorihttps://github.com/vittominacori https://wg-eips.ritovision.com/1363/ <h2 id="simple-summary">Simple Summary</h2> <p>Defines a token interface for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens that supports executing recipient code after <code>transfer</code> or <code>transferFrom</code>, or spender code after <code>approve</code>.</p> <h2 id="abstract">Abstract</h2> <p>Standard functions a token contract and contracts working with tokens can implement to make a token Payable.</p> <p><code>transferAndCall</code> and <code>transferFromAndCall</code> will call an <code>onTransferReceived</code> on a <code>ERC1363Receiver</code> contract.</p> <p><code>approveAndCall</code> will call an <code>onApprovalReceived</code> on a <code>ERC1363Spender</code> contract.</p> <h2 id="motivation">Motivation</h2> <p>There is no way to execute code after a <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> transfer or approval (i.e. making a payment), so to make an action it is required to send another transaction and pay GAS twice.</p> <p>This proposal wants to make token payments easier and working without the use of any other listener. It allows to make a callback after a transfer or approval in a single transaction.</p> <p>There are many proposed uses of Ethereum smart contracts that can accept <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> payments.</p> <p>Examples could be</p> <ul> <li>to create a token payable crowdsale</li> <li>selling services for tokens</li> <li>paying invoices</li> <li>making subscriptions</li> </ul> <p>For these reasons it was named as <strong>"Payable Token"</strong>.</p> <p>Anyway you can use it for specific utilities or for any other purposes who require the execution of a callback after a transfer or approval received.</p> <p>This proposal has been inspired by the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> <code>onERC721Received</code> and <code>ERC721TokenReceiver</code> behaviours.</p> <h2 id="specification">Specification</h2> <p>Implementing contracts <strong>MUST</strong> implement the <a href="https://wg-eips.ritovision.com/1363/">ERC-1363</a> interface as well as the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interfaces.</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"> ERC1363</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 0xb0202a11.</span></span> <span class="giallo-l"><span class="z-comment"> * 0xb0202a11 ===</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;transferAndCall(address,uint256)&#39;)) ^</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;transferAndCall(address,uint256,bytes)&#39;)) ^</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;transferFromAndCall(address,address,uint256)&#39;)) ^</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;transferFromAndCall(address,address,uint256,bytes)&#39;)) ^</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;approveAndCall(address,uint256)&#39;)) ^</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;approveAndCall(address,uint256,bytes)&#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"> Transfer tokens from `msg.sender` to another address and then call `onTransferReceived` on 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"> to</span><span class="z-comment"> address The address which you want to transfer 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"> value</span><span class="z-comment"> uint256 The amount of tokens to be transferred</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"> unless throwing</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"> transferAndCall</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> <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"> Transfer tokens from `msg.sender` to another address and then call `onTransferReceived` on 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"> to</span><span class="z-comment"> address The address which you want to transfer 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"> value</span><span class="z-comment"> uint256 The amount of tokens to be transferred</span></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"> bytes Additional data with no specified format, sent in call to `to`</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"> unless throwing</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"> transferAndCall</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-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 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"> Transfer tokens from one address to another and then call `onTransferReceived` on 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"> from</span><span class="z-comment"> address The address which you want to send tokens from</span></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 The address which you want to transfer 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"> value</span><span class="z-comment"> uint256 The amount of tokens to be transferred</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"> unless throwing</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"> transferFromAndCall</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> <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"> Transfer tokens from one address to another and then call `onTransferReceived` on 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"> from</span><span class="z-comment"> address The address which you want to send tokens from</span></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 The address which you want to transfer 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"> value</span><span class="z-comment"> uint256 The amount of tokens to be transferred</span></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"> bytes Additional data with no specified format, sent in call to `to`</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"> unless throwing</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"> transferFromAndCall</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-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 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"> Approve the passed address to spend the specified amount of tokens on behalf of msg.sender</span></span> <span class="giallo-l"><span class="z-comment"> * and then call `onApprovalReceived` on 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"> spender</span><span class="z-comment"> address The address which will spend 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"> value</span><span class="z-comment"> uint256 The amount of tokens to be spent</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"> unless throwing</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"> approveAndCall</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-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"> Approve the passed address to spend the specified amount of tokens on behalf of msg.sender</span></span> <span class="giallo-l"><span class="z-comment"> * and then call `onApprovalReceived` on 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"> spender</span><span class="z-comment"> address The address which will spend 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"> value</span><span class="z-comment"> uint256 The amount of tokens to be spent</span></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"> bytes Additional data with no specified format, sent in call 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"> true</span><span class="z-comment"> unless throwing</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"> approveAndCall</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-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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</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"> 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"> balanceOf</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"> transfer</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"> 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"> transferFrom</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"> 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"> 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"> 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"> 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"> 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"> 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">interface</span><span class="z-entity z-name"> ERC165</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 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>A contract that wants to accept token payments via <code>transferAndCall</code> or <code>transferFromAndCall</code> <strong>MUST</strong> implement the following interface:</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"> ERC1363Receiver interface</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 any contract that wants to support `transferAndCall` or `transferFromAndCall`</span></span> <span class="giallo-l"><span class="z-comment"> * from ERC1363 token contracts.</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"> ERC1363Receiver</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 0x88a7ca5c.</span></span> <span class="giallo-l"><span class="z-comment"> * 0x88a7ca5c === bytes4(keccak256(&quot;onTransferReceived(address,address,uint256,bytes)&quot;))</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"> Handle the receipt of ERC1363 tokens</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Any ERC1363 smart contract calls this function on the recipient</span></span> <span class="giallo-l"><span class="z-comment"> * after a `transfer` or a `transferFrom`. This function MAY throw to revert and reject the</span></span> <span class="giallo-l"><span class="z-comment"> * transfer. Return of other than the magic value MUST result in the</span></span> <span class="giallo-l"><span class="z-comment"> * transaction being reverted.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">Note</span><span class="z-comment">: the token contract address is always the message 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"> operator</span><span class="z-comment"> address The address which called `transferAndCall` or `transferFromAndCall` function</span></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"> address The address which are token transferred from</span></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"> uint256 The amount of tokens transferred</span></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"> bytes Additional data with no specified format</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-comment"> `bytes4(keccak256(&quot;onTransferReceived(address,address,uint256,bytes)&quot;))`</span></span> <span class="giallo-l"><span class="z-comment"> * unless throwing</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"> onTransferReceived</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"> value</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">bytes4</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>A contract that wants to accept token payments via <code>approveAndCall</code> <strong>MUST</strong> implement the following interface:</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"> ERC1363Spender interface</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 any contract that wants to support `approveAndCall`</span></span> <span class="giallo-l"><span class="z-comment"> * from ERC1363 token contracts.</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"> ERC1363Spender</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 0x7b04a2d0.</span></span> <span class="giallo-l"><span class="z-comment"> * 0x7b04a2d0 === bytes4(keccak256(&quot;onApprovalReceived(address,uint256,bytes)&quot;))</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"> Handle the approval of ERC1363 tokens</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Any ERC1363 smart contract calls this function on the recipient</span></span> <span class="giallo-l"><span class="z-comment"> * after an `approve`. This function MAY throw to revert and reject the</span></span> <span class="giallo-l"><span class="z-comment"> * approval. Return of other than the magic value MUST result in the</span></span> <span class="giallo-l"><span class="z-comment"> * transaction being reverted.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">Note</span><span class="z-comment">: the token contract address is always the message 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"> owner</span><span class="z-comment"> address The address which called `approveAndCall` function</span></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"> uint256 The amount of tokens to be spent</span></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"> bytes Additional data with no specified format</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-comment"> `bytes4(keccak256(&quot;onApprovalReceived(address,uint256,bytes)&quot;))`</span></span> <span class="giallo-l"><span class="z-comment"> * unless throwing</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"> onApprovalReceived</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"> value</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">bytes4</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The choice to use <code>transferAndCall</code>, <code>transferFromAndCall</code> and <code>approveAndCall</code> derives from the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> naming. They want to highlight that they have the same behaviours of <code>transfer</code>, <code>transferFrom</code> and <code>approve</code> with the addition of a callback on receiver or spender.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal has been inspired also by <a rel="external" href="https://github.com/ethereum/EIPs/issues/223">ERC-223</a> and <a rel="external" href="https://github.com/ethereum/EIPs/issues/677">ERC-677</a> but it uses the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> approach, so it doesn't override the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> <code>transfer</code> and <code>transferFrom</code> methods and defines the interfaces IDs to be implemented maintaining the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> backwards compatibility.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The <code>approveAndCall</code> and <code>transferFromAndCall</code> methods can be affected by the same issue of the standard <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> <code>approve</code> and <code>transferFrom</code> method.</p> <p>Changing an allowance with the <code>approveAndCall</code> methods brings the risk that someone may use both the old and the new allowance by unfortunate transaction ordering.</p> <p>One possible solution to mitigate this race condition is to first reduce the spender's allowance to 0 and set the desired value afterwards (<a rel="external" href="https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729">EIP-20#issuecomment-263524729</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-26T00:00:00+00:00 2026-02-11T14:49:27+00:00 Paweł Bylicahttps://github.com/chfast Jean M. Cyrhttps://github.com/jean-m-cyr https://wg-eips.ritovision.com/1355/ <h2 id="motivation">Motivation</h2> <p>Provide minimal set of changes to Ethash algorithm to hinder and delay the adoption of ASIC based mining.</p> <h2 id="specification">Specification</h2> <ol> <li> <p>Define hash function <code>fnv1a()</code> as</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"> fnv1a</span><span>(</span><span class="z-variable z-parameter z-function">v1</span><span>,</span><span class="z-variable z-parameter z-function"> v2</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>(</span><span>v1</span><span class="z-keyword"> ^</span><span> v2</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> FNV1A_PRIME</span><span>)</span><span class="z-keyword"> %</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">32</span></span></code></pre> <p>where <code>FNV1A_PRIME</code> is 16777499 or 16777639.</p> </li> <li> <p>Change the hash function that determines the DAG item index in Ethash algorithm from <code>fnv()</code> to new <code>fnv1a()</code>. In <a rel="external" href="https://github.com/ethereum/eth-wiki/blob/master/concepts/ethash/ethash.md#main-loop">Main Loop</a> change</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>p</span><span class="z-keyword"> =</span><span> fnv</span><span>(</span><span>i</span><span class="z-keyword"> ^</span><span> s</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span> mix</span><span>[</span><span>i</span><span class="z-keyword"> %</span><span> w</span><span>]</span><span>)</span><span class="z-keyword"> %</span><span> (</span><span>n</span><span class="z-keyword"> //</span><span> mixhashes</span><span>)</span><span class="z-keyword"> *</span><span> mixhashes</span></span></code></pre> <p>to</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>p</span><span class="z-keyword"> =</span><span> fnv1a</span><span>(</span><span>i</span><span class="z-keyword"> ^</span><span> s</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span> mix</span><span>[</span><span>i</span><span class="z-keyword"> %</span><span> w</span><span>]</span><span>)</span><span class="z-keyword"> %</span><span> (</span><span>n</span><span class="z-keyword"> //</span><span> mixhashes</span><span>)</span><span class="z-keyword"> *</span><span> mixhashes</span></span></code></pre></li> </ol> <h2 id="rationale">Rationale</h2> <p>The usual argument for decentralization and network security.</p> <p>Unless programmable, an ASIC is hardwired to perform sequential operations in a given order. fnv1a changes the order in which an exclusive-or and a multiply are applied, effectively disabling the current wave of ASICS. A second objective is minimize ethash changes to be the least disruptive, to facilitate rapid development, and to lower the analysis and test requirements. Minimizing changes to ethash reduces risk associated with updating all affected network components, and also reduces the risk of detuning existing GPUs. It's expected that this specific change would have no effect on existing GPU performance.</p> <p>Changing fnv to fnv1a has no cryptographic implications. It is merely an efficient hash function with good dispersion characteristics used to scramble DAG indexing. We remain focused on risk mitigation by reducing the need for rigorous cryptographic analysis.</p> <h3 id="fnv-primes">FNV Primes</h3> <p>The 16777639 satisfies all requirements from <a rel="external" href="https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function#FNV_prime">Wikipedia</a>.</p> <p>The 16777499 is preferred by FNV authors but not used in the reference FNV implementation because of historical reasons. See <a rel="external" href="http://www.isthe.com/chongo/tech/comp/fnv/index.html#fnv-prime">A few remarks on FNV primes</a>.</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-08-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 Richard Meissnerhttps://github.com/rmeissner Bryant Eisenbachhttps://github.com/fubuloubu https://wg-eips.ritovision.com/1344/ <h2 id="abstract">Abstract</h2> <p>This EIP adds an opcode that returns the current chain's EIP-155 unique identifier.</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> <h2 id="specification">Specification</h2> <p>Adds a new opcode <code>CHAINID</code> at 0x46, which uses 0 stack arguments. It pushes the current chain ID onto the stack. Chain ID is a 256-bit value. The operation costs <code>G_base</code> to execute.</p> <p>The value of the current chain ID is obtained from the chain ID configuration, which should match the EIP-155 unique identifier a client will accept from incoming transactions. Please note that per EIP-155, it is not <em>required</em> that a transaction have an EIP-155 unique identifier, but in that scenario this opcode will still return the configured chain ID and not a default.</p> <h2 id="rationale">Rationale</h2> <p>The current approach proposed by EIP-712 is to specify the chain ID at compile time. Using this approach will result in problems after a hardfork, as well as human error that may lead to loss of funds or replay attacks on signed messages. By adding the proposed opcode it will be possible to access the current chain ID and validate signatures based on that.</p> <p>Currently, there is no specification for how chain ID is set for a particular network, relying on choices made manually by the client implementers and the chain community. There is a potential scenario where, during a "contentious split" over a divisive issue, a community using a particular value of chain ID will make a decision to split into two such chains. When this scenario occurs, it will be unsafe to maintain chain ID to the same value on both chains, as chain ID is used for replay protection for in-protocol transactions (per EIP-155), as well as for L2 and "meta-transaction" use cases (per EIP-712 as enabled by this proposal). There are two potential resolutions in this scenario under the current process: 1) one chain decides to modify their value of chain ID (while the other keeps it), or 2) both chains decide to modify their value of chain ID.</p> <p>In order to mitigate this situation, users of the proposed <code>CHAINID</code> opcode <strong>must</strong> ensure that their application can handle a potential update to the value of chain ID during their usage of their application in case this does occur, if required for the continued use of the application. A Trustless Oracle that logs the timestamp when a change is made to chain ID can be implemented either as an application-level feature inside the application contract system, or referenced as a globally standard contract. Failure to provide a mitigation for this scenario could lead to a sudden loss of legitimacy of previously signed off-chain messages, which could be an issue during settlement periods and other longer-term verification events for these types of messages. Not all applications of this opcode may need mitigations to handle this scenario, but developers should provide reasoning on a case-by-case basis.</p> <p>One example of a scenario where it would not make sense to leverage a global oracle is with the Plasma L2 paradigm. In the Plasma paradigm, an operator or group of operators submit blocks from the L2 network to the base chain (in this case Ethereum) summarizing transactions that have occurred on that chain. The submission of these blocks may not perfectly align with major events on the mainchain, such as a split causing an update of chain ID, which may cause a significant insecurity in the protocol if chain ID is utilized in signing messages. If the operators are not allowed to control the update of chain ID they will not be able to perfectly synchronize the update with their block submissions, and certain past transactions may be rejected because they do not align with the update. This is one example of the unintended consequences of trying to specify too much of the behavior of chain ID during a contentious split, and why having a simple opcode for access is most optimal, versus a more complicated precompile or contract.</p> <p>This proposed opcode would be the simplest possible way to implement this functionality, and allows developers the flexibility to implement their own global or local handling of chain ID changes, if required.</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.</p> <h2 id="references">References</h2> <p>This was previously suggested as part of <a rel="external" href="https://github.com/ethereum/EIPs/issues/901">EIP-901</a>.</p> <h2 id="test-cases">Test Cases</h2> <p>Test Cases added to <a rel="external" href="https://github.com/ethereum/tests/pull/627">ethereum/tests</a></p> <h2 id="implementation">Implementation</h2> <p>A reference implementation for the Trinity Python client is <a rel="external" href="https://github.com/ethereum/py-evm/pull/1803">here</a>.</p> <p>An example implementation of a trustless chain ID oracle was implemented <a rel="external" href="https://github.com/fubuloubu/chain-id-oracle/blob/master/ChainIdOracle.vy">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-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 ligihttps://github.com/ligi Pedro Gomeshttps://github.com/pedrouid https://wg-eips.ritovision.com/1328/

Define URI format for initiating connections between applications and wallets

<h2 id="abstract">Abstract</h2> <p>This standard defines how the data to connect some application and a wallet can be encoded with a URI. This URI can then be shown either as a QR code or as a link.</p> <h2 id="specification">Specification</h2> <h3 id="syntax">Syntax</h3> <p>WalletConnect request URI with the following parameters:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>request = &quot;wc&quot; &quot;:&quot; topic [ &quot;@&quot; version ][ &quot;?&quot; parameters ]</span></span> <span class="giallo-l"><span>topic = STRING</span></span> <span class="giallo-l"><span>version = 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 = STRING</span></span> <span class="giallo-l"><span>value = STRING</span></span></code></pre><h3 id="semantics">Semantics</h3> <p>Required parameters are dependent on the WalletConnect protocol version:</p> <p>For WalletConnect v1.0 protocol (<code>version</code>=<code>1</code>) the parameters are:</p> <ul> <li><code>key</code> - symmetric key used for encryption</li> <li><code>bridge</code> - url of the bridge server for relaying messages</li> </ul> <p>For WalletConnect v2.0 protocol (<code>version</code>=<code>2</code>) the parameters are:</p> <ul> <li><code>symKey</code> - symmetric key used for encrypting messages over relay</li> <li><code>methods</code> - jsonrpc methods supported for pairing topic</li> <li><code>relay-protocol</code> - transport protocol for relaying messages</li> <li><code>relay-data</code> - (optional) transport data for relaying messages</li> <li><code>expiryTimestamp</code> - (optional) unix epoch in seconds when pairing expires</li> </ul> <h3 id="example">Example</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span># 1.0</span></span> <span class="giallo-l"><span>wc:8a5e5bdc-a0e4-4702-ba63-8f1a5655744f@1?bridge=https%3A%2F%2Fbridge.walletconnect.org&amp;key=41791102999c339c844880b23950704cc43aa840f3739e365323cda4dfa89e7a</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># 2.0</span></span> <span class="giallo-l"><span>wc:7f6e504bfad60b485450578e05678ed3e8e8c4751d3c6160be17160d63ec90f9@2?relay-protocol=irn&amp;symKey=587d5484ce2a2a6ee3ba1962fdd7e8588e06200c46823bd18fbd67def96ad303&amp;methods=[wc_sessionPropose],[wc_authRequest,wc_authBatchRequest]&quot;&amp;expiryTimestamp=1705934757</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This proposal moves away from the JSON format used in the alpha version of the WalletConnect protocol because it suffered from very inefficient parsing of the intent of the QR code, thereby making it easier to create better QR code parsers APIs for wallets to implement. Also by using a URI instead of JSON inside the QR-Code the Android Intent system can be leveraged.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Versioning is required as part of the syntax for this URI specification to allow the WalletConnect protocol to evolve and allow backwards-compatibility whenever a new version is introduced.</p> <h2 id="security-considerations">Security Considerations</h2> <p>URIs should be shared between user devices or applications and no sensitive data is shared within the URI that could compromise the communication or would allow control of the user's private keys.</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-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Dan Finlayhttps://github.com/danfinlay Esteban Minohttps://github.com/estebanmino Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/747/

Adds a new RPC method that allows websites to prompt users to watch an asset

<h2 id="abstract">Abstract</h2> <p>This EIP standardizes a new wallet-scoped RPC method, <code>wallet_watchAsset</code>, to allow a client to suggest a token for the user's wallet to track.</p> <h2 id="motivation">Motivation</h2> <p>Today, one of the major uses of Ethereum wallets is to track users' assets. Without this EIP, each wallet either needs to pre-load a list of approved assets, or users must manually add assets to their wallet. In the first case, wallets are burdened with both the security of managing this list, as well as the bandwidth of mass polling for known assets on their wallet. In the second case, the user experience is terrible.</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 RPC method, <code>wallet_watchAsset</code> is added. <code>wallet_watchAsset</code> requests that a specified asset be listed to the user's wallet. It MUST immediately (i.e. before prompting the user) return <code>true</code> if the request was valid, or error if it was not. The meaning of "listed to the user's wallet" is dependent on the wallet implementation. A successful call to <code>wallet_watchAsset</code> MUST indicate that the wallet recognized the request and that it contained no issues, but doesn't indicate whether the user was prompted or whether the asset was actually added to the wallet.</p> <h3 id="wallet-watchasset-parameters"><code>wallet_watchAsset</code> Parameters</h3> <p>The <code>wallet_watchAsset</code> method takes a single parameter, a <code>WatchAssetParameters</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"> WatchAssetParameters</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> The asset&#39;s interface, e.g. &#39;ERC1046&#39;</span></span> <span class="giallo-l"><span class="z-variable"> options</span><span class="z-keyword">:</span><span class="z-support"> any</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>type</code> string SHOULD be the commonly accepted name of the interface implemented by the asset's contract, e.g. <code>ERC1046</code>. Defining the global identifiers for different asset types is beyond the scope of this EIP.</p> <p>This interface SHOULD be extended or modified depending on the asset <code>type</code>. These changes MUST be specified in separate EIPs.</p> <h3 id="wallet-watchasset-returns"><code>wallet_watchAsset</code> Returns</h3> <p><code>wallet_watchAsset</code> immediately (i.e. without waiting for user interaction) returns the boolean value <code>true</code> to indicate that the request was recognized (regardless of whether the user was prompted), or errors if the request is invalid. An error might occur in the following circumstances (not comprehensive):</p> <ul> <li>The asset type is unrecognized/unsupported</li> <li>The asset was blocked due to an allowlist or denylist (this makes the request 'invalid' since the root cause requires developer action)</li> <li>Downloading the image failed to load <ul> <li>The wallet didn't load some of the metadata required to display the asset, in order to protect against a potential SSRF attack</li> </ul> </li> </ul> <h3 id="erc1046-type"><code>ERC1046</code> type</h3> <p>The format of the options field is:</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"> ERC1046WatchAssetOptions</span><span> {</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> address</span><span>:</span><span class="z-variable z-other"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> The hexadecimal address of the token contract</span></span> <span class="giallo-l"><span class="z-variable z-other"> chainId</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-variable z-other"> number</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> The chain ID of the asset. If empty, defaults to the current chain ID.</span></span> <span class="giallo-l"><span> }</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>address</code> is required, and the other fields are optional. <code>address</code> MUST be the <code>0x</code>-prefixed checksummed hexadecimal address of the token contract. <code>chainId</code> MUST be the chain ID to which the asset belongs.</p> <p>If the checksum fails, the request MUST be considered invalid.</p> <p>If the wallet does not recognize the <code>chainId</code>, or the <code>chainId</code> is blank and the wallet does not have a concept of "active" chain, the call MUST fail.</p> <p><code>wallet_watchAsset</code> MUST fetch the <a href="https://wg-eips.ritovision.com/1046/">ERC-1046</a> <code>tokenURI</code> and check the <code>interop</code> field to determine the type of the token. If the parsing fails, or the type is unknown, the RPC call MUST error.</p> <p><code>wallet_watchAsset</code> SHOULD check the <code>name</code> and <code>symbol</code> fields, and the contract <code>address</code> and <code>chainId</code> against a list of well-known tokens. If the name and/or symbol are similar to ones on the list but the <code>chainId</code>/<code>address</code> don't match, a warning SHOULD be presented to the user.</p> <p>The wallet SHOULD whitelist and/or blacklist specific ports and schemes to avoid SSRF attacks.</p> <h3 id="legacy-erc20-type">Legacy <code>ERC20</code> type</h3> <p>The format of the options field is:</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"> ERC20WatchAssetOptions</span><span> {</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> address</span><span>:</span><span class="z-variable z-other"> string</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> The hexadecimal address of the token contract</span></span> <span class="giallo-l"><span class="z-variable z-other"> chainId</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-variable z-other"> number</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> The chain ID of the asset. If empty, defaults to the current chain ID.</span></span> <span class="giallo-l"><span> }</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>address</code> is required, and the other fields are optional. <code>address</code> MUST be the <code>0x</code>-prefixed checksummed hexadecimal address of the token contract. <code>chainId</code> MUST be the chain ID to which the asset belongs.</p> <p>If the checksum fails, the request MUST be considered invalid.</p> <p>If the wallet does not recognize the <code>chainId</code>, or the <code>chainId</code> is blank and the wallet does not have a concept of "active" chain, the call MUST fail.</p> <p><code>wallet_watchAsset</code> SHOULD check the <code>name</code> and <code>symbol</code> fields, and the contract <code>address</code> and <code>chainId</code> against a list of well-known tokens. If the name and/or symbol are similar to ones on the list but the <code>chainId</code>/<code>address</code> don't match, a warning SHOULD be presented to the user.</p> <p>If possible, it is RECOMMENDED to instead use the <code>ERC1046</code> type, which supports images and custom metadata.</p> <h2 id="rationale">Rationale</h2> <p>Displaying a user's assets is a basic feature that every modern DApp user expects. Most wallets currently either manage their own asset lists, which they store client-side, or they query a centralized API for balances, which reduces decentralization and allows correlating account holders with IP addresses. Additionally, refreshing/polling an asset list from the network can be costly, especially on bandwidth-constrained devices. Also, maintaining an asset list becomes a political act, provoking harassment and inducing pressure to list obscure assets.</p> <p>Automatically listing assets makes assets into a sort of spam mail: Users suddenly see new assets that they don't care about in their wallet. This can be used to send unsolicited information, or even to conduct phishing scams. This phenomenon is already common with airdropped tokens, a major cause of network congestion, because spamming people with new tokens has, so far, been rewarded with increased user attention.</p> <p>When a user is manually adding an asset, they had likely previously learned about it from a website. At that moment, there was a natural alignment of interests, where both parties wanted the user to track the token. This is a natural point to introduce an API to easily allow these parties to collaborate.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="server-side-request-forgery">Server-Side Request Forgery</h3> <p>Wallets should be careful about making arbitrary requests to URLs. As such, it is recommended for wallets to sanitize the URI by whitelisting specific schemes and ports. A vulnerable wallet could be tricked into, for example, modifying data on a locally-hosted redis database.</p> <h3 id="validation">Validation</h3> <p>Wallets should warn users if the symbol or name matches or is similar to another token, to avoid phishing scams.</p> <h3 id="fingerprinting">Fingerprinting</h3> <p>To avoid fingerprinting based on wallet behavior and/or listed assets, the RPC call must return as soon as the user is prompted or an error occurs, without waiting for the user to accept or deny the prompt.</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 Wei Tanghttps://github.com/sorpaas https://wg-eips.ritovision.com/1283/ <h2 id="abstract">Abstract</h2> <p>This EIP proposes net gas metering changes for <code>SSTORE</code> opcode, enabling new usages for contract storage, and reducing excessive gas costs where it doesn't match how most implementations work.</p> <p>This acts as an alternative for EIP-1087, where it tries to be friendlier to implementations that use different optimization strategies for storage change caches.</p> <h2 id="motivation">Motivation</h2> <p>This EIP proposes a way for gas metering on SSTORE (as an alternative for EIP-1087 and EIP-1153), using information that is more universally available to most implementations, and requires as little change in implementation structures as possible.</p> <ul> <li><em>Storage slot's original value</em>.</li> <li><em>Storage slot's current value</em>.</li> <li>Refund counter.</li> </ul> <p>Usages that benefits from this EIP's gas reduction scheme includes:</p> <ul> <li>Subsequent storage write operations within the same call frame. This includes reentry locks, same-contract multi-send, etc.</li> <li>Exchange storage information between sub call frame and parent call frame, where this information does not need to be persistent outside of a transaction. This includes sub-frame error codes and message passing, etc.</li> </ul> <h2 id="specification">Specification</h2> <p>Definitions of terms are as below:</p> <ul> <li><em>Storage slot's original value</em>: This is the value of the storage if a reversion happens on the <em>current transaction</em>.</li> <li><em>Storage slot's current value</em>: This is the value of the storage before SSTORE operation happens.</li> <li><em>Storage slot's new value</em>: This is the value of the storage after SSTORE operation happens.</li> </ul> <p>Replace <code>SSTORE</code> opcode gas cost calculation (including refunds) with the following logic:</p> <ul> <li>If <em>current value</em> equals <em>new value</em> (this is a no-op), 200 gas is deducted.</li> <li>If <em>current value</em> does not equal <em>new value</em> <ul> <li>If <em>original value</em> equals <em>current value</em> (this storage slot has not been changed by the current execution context) <ul> <li>If <em>original value</em> is 0, 20000 gas is deducted.</li> <li>Otherwise, 5000 gas is deducted. If <em>new value</em> is 0, add 15000 gas to refund counter.</li> </ul> </li> <li>If <em>original value</em> does not equal <em>current value</em> (this storage slot is dirty), 200 gas is deducted. Apply both of the following clauses. <ul> <li>If <em>original value</em> is not 0 <ul> <li>If <em>current value</em> is 0 (also means that <em>new value</em> is not 0), remove 15000 gas from refund counter. We can prove that refund counter will never go below 0.</li> <li>If <em>new value</em> is 0 (also means that <em>current value</em> is not 0), add 15000 gas to refund counter.</li> </ul> </li> <li>If <em>original value</em> equals <em>new value</em> (this storage slot is reset) <ul> <li>If <em>original value</em> is 0, add 19800 gas to refund counter.</li> <li>Otherwise, add 4800 gas to refund counter.</li> </ul> </li> </ul> </li> </ul> </li> </ul> <p>Refund counter works as before -- it is limited to half of the gas consumed. On a transaction level, refund counter will never go below zero. However, there are some important notes depending on the implementation details:</p> <ul> <li>If an implementation uses "transaction level" refund counter (refund is checkpointed at each call frame), then the refund counter continues to be unsigned.</li> <li>If an implementation uses "execution-frame level" refund counter (a new refund counter is created at each call frame, and then merged back to parent when the call frame finishes), then the refund counter needs to be changed to signed -- at internal calls, a child refund can go below zero.</li> </ul> <h2 id="explanation">Explanation</h2> <p>The new gas cost scheme for <code>SSTORE</code> is divided into three different types:</p> <ul> <li><strong>No-op</strong>: the virtual machine does not need to do anything. This is the case if <em>current value</em> equals <em>new value</em>.</li> <li><strong>Fresh</strong>: this storage slot has not been changed, or has been reset to its original value. This is the case if <em>current value</em> does not equal <em>new value</em>, and <em>original value</em> equals <em>current value</em>.</li> <li><strong>Dirty</strong>: this storage slot has already been changed. This is the case if <em>current value</em> does not equal <em>new value</em>, and <em>original value</em> does not equal <em>current value</em>.</li> </ul> <p>We can see that the above three types cover all possible variations of <em>original value</em>, <em>current value</em>, and <em>new value</em>.</p> <p><strong>No-op</strong> is a trivial operation. Below we only consider cases for <strong>Fresh</strong> and <strong>Dirty</strong>.</p> <p>All initial (not-<strong>No-op</strong>) <code>SSTORE</code> on a particular storage slot starts with <strong>Fresh</strong>. After that, it will become <strong>Dirty</strong> if the value has been changed. When going from <strong>Fresh</strong> to <strong>Dirty</strong>, we charge the gas cost the same as current scheme. A <strong>Dirty</strong> storage slot can be reset back to <strong>Fresh</strong> via a <code>SSTORE</code> opcode. This will trigger a refund.</p> <p>When a storage slot remains at <strong>Dirty</strong>, we charge 200 gas. In this case, we would also need to keep track of <code>R_SCLEAR</code> refunds -- if we already issued the refund but it no longer applies (<em>current value</em> is 0), then removes this refund from the refund counter. If we didn't issue the refund but it applies now (<em>new value</em> is 0), then adds this refund to the refund counter. It is not possible where a refund is not issued but we remove the refund in the above case, because all storage slot starts with <strong>Fresh</strong> state.</p> <h3 id="state-transition">State Transition</h3> <p>Below is a graph (<a rel="external" href="https://github.com/ethereum/EIPs/pull/1283#issuecomment-410229053">by @Arachnid</a>) showing possible state transition of gas costs. We ignore <strong>No-op</strong> state because that is trivial:</p> <p><img src="https://wg-eips.ritovision.com/1283/./assets/state.png" alt="State Transition" /></p> <p>Below is table version of the above diagram. Vertical shows the <em>new value</em> being set, and horizontal shows the state of <em>original value</em> and <em>current value</em>.</p> <p>When <em>original value</em> is 0:</p> <table><thead><tr><th></th><th>A (<code>current=orig=0</code>)</th><th>B (<code>current!=orig</code>)</th></tr></thead><tbody> <tr><td>~0</td><td>B; 20k gas</td><td>B; 200 gas</td></tr> <tr><td>0</td><td>A; 200 gas</td><td>A; 200 gas, 19.8k refund</td></tr> </tbody></table> <p>When <em>original value</em> is not 0:</p> <table><thead><tr><th></th><th>X (<code>current=orig!=0</code>)</th><th>Y (<code>current!=orig</code>)</th><th>Z (<code>current=0</code>)</th></tr></thead><tbody> <tr><td><code>orig</code></td><td>X; 200 gas</td><td>X; 200 gas, 4.8k refund</td><td>X; 200 gas, -10.2k refund</td></tr> <tr><td><code>~orig, ~0</code></td><td>Y; 5k gas</td><td>Y; 200 gas</td><td>Y; 200 gas, -15k refund</td></tr> <tr><td>0</td><td>Z; 5k gas, 15k refund</td><td>Z; 200 gas, 15k refund</td><td>Z; 200 gas</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <p>This EIP mostly achieves what a transient storage tries to do (EIP-1087 and EIP-1153), but without the complexity of introducing the concept of "dirty maps", or an extra storage struct.</p> <ul> <li>We don't suffer from the optimization limitation of EIP-1087. EIP-1087 requires keeping a dirty map for storage changes, and implicitly makes the assumption that a transaction's storage changes are committed to the storage trie at the end of a transaction. This works well for some implementations, but not for others. After EIP-658, an efficient storage cache implementation would probably use an in-memory trie (without RLP encoding/decoding) or other immutable data structures to keep track of storage changes, and only commit changes at the end of a block. For them, it is possible to know a storage's original value and current value, but it is not possible to iterate over all storage changes without incurring additional memory or processing costs.</li> <li>It never costs more gas compared with the current scheme.</li> <li>It covers all usages for a transient storage. Clients that are easy to implement EIP-1087 will also be easy to implement this specification. Some other clients might require a little bit extra refactoring on this. Nonetheless, no extra memory or processing cost is needed on runtime.</li> </ul> <p>Regarding <code>SSTORE</code> gas cost and refunds, see Appendix for proofs of properties that this EIP satisfies.</p> <ul> <li>For <em>absolute gas used</em> (that is, actual <em>gas used</em> minus <em>refund</em>), this EIP is equivalent to EIP-1087 for all cases.</li> <li>For one particular case, where a storage slot is changed, reset to its original value, and then changed again, EIP-1283 would move more gases to refund counter compared with EIP-1087.</li> </ul> <p>Examine examples provided in EIP-1087's Motivation:</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.</li> <li>A contract with empty storage that increments slot 0 5 times will be charged <code>20000 + 5 * 200 = 21000</code> 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, it will cost <code>5000 * 3 + 200 - 4800 = 10400</code> gas.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a hard fork to implement. No gas cost increase is anticipated, and many contracts will see gas reduction.</p> <h2 id="test-cases">Test Cases</h2> <p>Below we provide 17 test cases. 15 of them covering consecutive two <code>SSTORE</code> operations are based on work <a rel="external" href="https://github.com/ethereum/tests/issues/483">by @chfast</a>. Two additional cases with three <code>SSTORE</code> operations is used to test the case when a slot is reset and then set again.</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></tr></thead><tbody> <tr><td><code>0x60006000556000600055</code></td><td>412</td><td>0</td><td>0</td><td>0</td><td>0</td><td></td></tr> <tr><td><code>0x60006000556001600055</code></td><td>20212</td><td>0</td><td>0</td><td>0</td><td>1</td><td></td></tr> <tr><td><code>0x60016000556000600055</code></td><td>20212</td><td>19800</td><td>0</td><td>1</td><td>0</td><td></td></tr> <tr><td><code>0x60016000556002600055</code></td><td>20212</td><td>0</td><td>0</td><td>1</td><td>2</td><td></td></tr> <tr><td><code>0x60016000556001600055</code></td><td>20212</td><td>0</td><td>0</td><td>1</td><td>1</td><td></td></tr> <tr><td><code>0x60006000556000600055</code></td><td>5212</td><td>15000</td><td>1</td><td>0</td><td>0</td><td></td></tr> <tr><td><code>0x60006000556001600055</code></td><td>5212</td><td>4800</td><td>1</td><td>0</td><td>1</td><td></td></tr> <tr><td><code>0x60006000556002600055</code></td><td>5212</td><td>0</td><td>1</td><td>0</td><td>2</td><td></td></tr> <tr><td><code>0x60026000556000600055</code></td><td>5212</td><td>15000</td><td>1</td><td>2</td><td>0</td><td></td></tr> <tr><td><code>0x60026000556003600055</code></td><td>5212</td><td>0</td><td>1</td><td>2</td><td>3</td><td></td></tr> <tr><td><code>0x60026000556001600055</code></td><td>5212</td><td>4800</td><td>1</td><td>2</td><td>1</td><td></td></tr> <tr><td><code>0x60026000556002600055</code></td><td>5212</td><td>0</td><td>1</td><td>2</td><td>2</td><td></td></tr> <tr><td><code>0x60016000556000600055</code></td><td>5212</td><td>15000</td><td>1</td><td>1</td><td>0</td><td></td></tr> <tr><td><code>0x60016000556002600055</code></td><td>5212</td><td>0</td><td>1</td><td>1</td><td>2</td><td></td></tr> <tr><td><code>0x60016000556001600055</code></td><td>412</td><td>0</td><td>1</td><td>1</td><td>1</td><td></td></tr> <tr><td><code>0x600160005560006000556001600055</code></td><td>40218</td><td>19800</td><td>0</td><td>1</td><td>0</td><td>1</td></tr> <tr><td><code>0x600060005560016000556000600055</code></td><td>10218</td><td>19800</td><td>1</td><td>0</td><td>1</td><td>0</td></tr> </tbody></table> <h2 id="appendix-proof">Appendix: Proof</h2> <p>Because the <em>storage slot's original value</em> is defined as the value when a reversion happens on the <em>current transaction</em>, it's easy to see that call frames won't interfere SSTORE gas calculation. So although the below proof is discussed without call frames, it applies to all situations with call frames. We will discuss the case separately for <em>original value</em> being zero and not zero, and use <em>induction</em> to prove some properties of SSTORE gas cost.</p> <p><em>Final value</em> is the value of a particular storage slot at the end of a transaction. <em>Absolute gas used</em> is the absolute value of <em>gas used</em> minus <em>refund</em>. We use <code>N</code> to represent the total number of SSTORE operations on a storage slot. For states discussed below, refer to <em>State Transition</em> in <em>Explanation</em> section.</p> <h3 id="original-value-being-zero">Original Value Being Zero</h3> <p>When <em>original value</em> is 0, we want to prove that:</p> <ul> <li><strong>Case I</strong>: If the <em>final value</em> ends up still being 0, we want to charge <code>200 * N</code> gases, because no disk write is needed.</li> <li><strong>Case II</strong>: If the <em>final value</em> ends up being a non-zero value, we want to charge <code>20000 + 200 * (N-1)</code> gas, because it requires writing this slot to disk.</li> </ul> <h4 id="base-case">Base Case</h4> <p>We always start at state A. The first SSTORE can:</p> <ul> <li>Go to state A: 200 gas is deducted. We satisfy <em>Case I</em> because <code>200 * N == 200 * 1</code>.</li> <li>Go to state B: 20000 gas is deducted. We satisfy <em>Case II</em> because <code>20000 + 200 * (N-1) == 20000 + 200 * 0</code>.</li> </ul> <h4 id="inductive-step">Inductive Step</h4> <ul> <li>From A to A. The previous gas cost is <code>200 * (N-1)</code>. The current gas cost is <code>200 + 200 * (N-1)</code>. It satisfy <em>Case I</em>.</li> <li>From A to B. The previous gas cost is <code>200 * (N-1)</code>. The current gas cost is <code>20000 + 200 * (N-1)</code>. It satisfy <em>Case II</em>.</li> <li>From B to B. The previous gas cost is <code>20000 + 200 * (N-2)</code>. The current gas cost is <code>200 + 20000 + 200 * (N-2)</code>. It satisfy <em>Case II</em>.</li> <li>From B to A. The previous gas cost is <code>20000 + 200 * (N-2)</code>. The current gas cost is <code>200 - 19800 + 20000 + 200 * (N-2)</code>. It satisfy <em>Case I</em>.</li> </ul> <h3 id="original-value-not-being-zero">Original Value Not Being Zero</h3> <p>When <em>original value</em> is not 0, we want to prove that:</p> <ul> <li><strong>Case I</strong>: If the <em>final value</em> ends up unchanged, we want to charge <code>200 * N</code> gases, because no disk write is needed.</li> <li><strong>Case II</strong>: If the <em>final value</em> ends up being zero, we want to charge <code>5000 - 15000 + 200 * (N-1)</code> gas. Note that <code>15000</code> is the refund in actual definition.</li> <li><strong>Case III</strong>: If the <em>final value</em> ends up being a changed non-zero value, we want to charge <code>5000 + 200 * (N-1)</code> gas.</li> </ul> <h4 id="base-case-1">Base Case</h4> <p>We always start at state X. The first SSTORE can:</p> <ul> <li>Go to state X: 200 gas is deducted. We satisfy <em>Case I</em> because <code>200 * N == 200 * 1</code>.</li> <li>Go to state Y: 5000 gas is deducted. We satisfy <em>Case III</em> because <code>5000 + 200 * (N-1) == 5000 + 200 * 0</code>.</li> <li>Go to state Z: The absolute gas used is <code>5000 - 15000</code> where 15000 is the refund. We satisfy <em>Case II</em> because <code>5000 - 15000 + 200 * (N-1) == 5000 - 15000 + 200 * 0</code>.</li> </ul> <h4 id="inductive-step-1">Inductive Step</h4> <ul> <li>From X to X. The previous gas cost is <code>200 * (N-1)</code>. The current gas cost is <code>200 + 200 * (N-1)</code>. It satisfy <em>Case I</em>.</li> <li>From X to Y. The previous gas cost is <code>200 * (N-1)</code>. The current gas cost is <code>5000 + 200 * (N-1)</code>. It satisfy <em>Case III</em>.</li> <li>From X to Z. The previous gas cost is <code>200 * (N-1)</code>. The current absolute gas cost is <code>5000 - 15000 + 200 * (N-1)</code>. It satisfy <em>Case II</em>.</li> <li>From Y to X. The previous gas cost is <code>5000 + 200 * (N-2)</code>. The absolute current gas cost is <code>200 - 4800 + 5000 + 200 * (N-2)</code>. It satisfy <em>Case I</em>.</li> <li>From Y to Y. The previous gas cost is <code>5000 + 200 * (N-2)</code>. The current gas cost is <code>200 + 5000 + 200 * (N-2)</code>. It satisfy <em>Case III</em>.</li> <li>From Y to Z. The previous gas cost is <code>5000 + 200 * (N-2)</code>. The current absolute gas cost is <code>200 - 15000 + 5000 + 200 * (N-2)</code>. It satisfy <em>Case II</em>.</li> <li>From Z to X. The previous gas cost is <code>5000 - 15000 + 200 * (N-2)</code>. The current absolute gas cost is <code>200 + 10200 + 5000 - 15000 + 200 * (N-2)</code>. It satisfy <em>Case I</em>.</li> <li>From Z to Y. The previous gas cost is <code>5000 - 15000 + 200 * (N-2)</code>. The current absolute gas cost is <code>200 + 15000 + 5000 - 15000 + 200 * (N-2)</code>. It satisfy <em>Case III</em>.</li> <li>From Z to Z. The previous gas cost is <code>5000 - 15000 + 200 * (N-2)</code>. The current absolute gas cost is <code>200 + 5000 - 15000 + 200 * (N-2)</code>. It satisfy <em>Case II</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> 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>_c ∈ 𝔹₂₀ 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-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Francisco Giordanohttps://github.com/frangio Matt Condonhttps://github.com/shrugs Philippe Castonguayhttps://github.com/PhABC Amir Bandealihttps://github.com/abandeali1 Jorge Izquierdohttps://github.com/izqui Bertrand Masiushttps://github.com/catageek https://wg-eips.ritovision.com/1271/

Standard way to verify a signature when the account is a smart contract

<h2 id="abstract">Abstract</h2> <p>Externally Owned Accounts (EOA) can sign messages with their associated private keys, but currently contracts cannot. We propose a standard way for any contracts to verify whether a signature on a behalf of a given contract is valid. This is possible via the implementation of a <code>isValidSignature(hash, signature)</code> function on the signing contract, which can be called to validate a signature.</p> <h2 id="motivation">Motivation</h2> <p>There are and will be many contracts that want to utilize signed messages for validation of rights-to-move assets or other purposes. In order for these contracts to be able to support non Externally Owned Accounts (i.e., contract owners), we need a standard mechanism by which a contract can indicate whether a given signature is valid or not on its behalf.</p> <p>One example of an application that requires signatures to be provided would be decentralized exchanges with off-chain orderbook, where buy/sell orders are signed messages. In these applications, EOAs sign orders, signaling their desire to buy/sell a given asset and giving explicit permissions to the exchange smart contracts to conclude a trade via a signature. When it comes to contracts however, regular signatures are not possible since contracts do not possess a private key, hence this proposal.</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> <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">0</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 z-constant"> ERC1271</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"> bytes4(keccak256(&quot;isValidSignature(bytes32,bytes)&quot;)</span></span> <span class="giallo-l"><span class="z-variable z-other"> bytes4</span><span class="z-variable z-other"> constant</span><span class="z-variable z-other"> internal</span><span class="z-variable z-other z-constant"> MAGICVALUE</span><span class="z-keyword"> =</span><span class="z-constant"> 0x1626ba7e</span><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">dev</span><span class="z-comment"> Should return whether the signature provided is valid for the provided hash</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"> _hash</span><span class="z-comment"> Hash of the data to be signed</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"> Signature byte array associated with _hash</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * MUST return the bytes4 magic value 0x1626ba7e when function passes.</span></span> <span class="giallo-l"><span class="z-comment"> * MUST NOT modify state (using STATICCALL for solc &lt; 0.5, view modifier for solc &gt; 0.5)</span></span> <span class="giallo-l"><span class="z-comment"> * MUST allow external calls</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isValidSignature</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> bytes32</span><span class="z-variable"> _hash</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable"> bytes</span><span class="z-variable"> memory</span><span class="z-variable"> _signature</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> public</span></span> <span class="giallo-l"><span class="z-entity z-name"> view</span><span> </span></span> <span class="giallo-l"><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bytes4</span><span class="z-variable"> magicValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>isValidSignature</code> can call arbitrary methods to validate a given signature, which could be context dependent (e.g. time based or state based), EOA dependent (e.g. signers authorization level within smart wallet), signature scheme Dependent (e.g. ECDSA, multisig, BLS), etc.</p> <p>This function should be implemented by contracts which desire to sign messages (e.g. smart contract wallets, DAOs, multisignature wallets, etc.) Applications wanting to support contract signatures should call this method if the signer is a contract.</p> <h2 id="rationale">Rationale</h2> <p>We believe the name of the proposed function to be appropriate considering that an <em>authorized</em> signers providing proper signatures for a given data would see their signature as "valid" by the signing contract. Hence, a signed action message is only valid when the signer is authorized to perform a given action on the behalf of a smart wallet.</p> <p>Two arguments are provided for simplicity of separating the hash signed from the signature. A bytes32 hash is used instead of the unhashed message for simplicity, since contracts could expect a certain hashing function that is not standard, such as with <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>.</p> <p><code>isValidSignature()</code> should not be able to modify states in order to prevent <code>GasToken</code> minting or similar attack vectors. Again, this is to simplify the implementation surface of the function for better standardization and to allow off-chain contract queries.</p> <p>The specific return value is expected to be returned instead of a boolean in order to have stricter and simpler verification of a signature.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is backward compatible with previous work on signature validation since this method is specific to contract based signatures and not EOA signatures.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Example implementation of a signing contract:</p> <pre class="giallo z-code"><code data-lang="solidity"><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"> Verifies that the signer is the owner of the signing 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"> isValidSignature</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _hash</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 z-parameter z-function"> _signature</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-storage z-type"> view</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-comment"> //</span><span class="z-comment"> Validate signatures</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-entity z-name">recoverSigner</span><span>(</span><span>_hash</span><span>,</span><span> _signature</span><span>)</span><span class="z-keyword"> ==</span><span> owner</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 0x1626ba7e</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"> 0xffffffff</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"> Recover the signer of hash, assuming it&#39;s an EOA account</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Only for EthSign signatures</span></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"> Hash of message that was signed</span></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 encoded as (bytes32 r, bytes32 s, uint8 v)</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"> recoverSigner</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _hash</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 z-parameter z-function"> _signature</span></span> <span class="giallo-l"><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 class="z-variable"> signer</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_signature</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 65</span><span>,</span><span class="z-string"> &quot;SignatureValidator#recoverSigner: invalid signature length&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"> Variables are not scoped in Solidity.</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> v </span><span class="z-keyword">=</span><span class="z-support"> uint8</span><span>(</span><span>_signature</span><span>[</span><span class="z-constant">64</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> r </span><span class="z-keyword">=</span><span> _signature</span><span>.</span><span class="z-entity z-name">readBytes32</span><span>(</span><span class="z-constant">0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> s </span><span class="z-keyword">=</span><span> _signature</span><span>.</span><span class="z-entity z-name">readBytes32</span><span>(</span><span class="z-constant">32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> EIP-2 still allows signature malleability for ecrecover(). Remove this possibility and make the signature</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> unique. Appendix F in the Ethereum Yellow paper (https://ethereum.github.io/yellowpaper/paper.pdf), defines</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> the valid range for s in (281): 0 &lt; s &lt; secp256k1n ÷ 2 + 1, and for v in (282): v ∈ {27, 28}. Most</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> signatures from current libraries generate a unique signature with an s-value in the lower half order.</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"> If your library generates malleable signatures, such as s-values in the upper range, calculate a new s-value</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> with 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141 - s1 and flip v from 27 to 28 or</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> vice versa. If your library also generates signatures with 0/1 for v instead 27/28, add 27 to v to accept</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> these malleable signatures as well.</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"> Source OpenZeppelin</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/cryptography/ECDSA.sol</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-support">uint256</span><span>(</span><span>s</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span class="z-string">&quot;SignatureValidator#recoverSigner: invalid signature &#39;s&#39; value&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-keyword"> if</span><span> (</span><span>v </span><span class="z-keyword">!=</span><span class="z-constant"> 27</span><span class="z-keyword"> &amp;&amp;</span><span> v </span><span class="z-keyword">!=</span><span class="z-constant"> 28</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span class="z-string">&quot;SignatureValidator#recoverSigner: invalid signature &#39;v&#39; value&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-comment"> //</span><span class="z-comment"> Recover ECDSA signer</span></span> <span class="giallo-l"><span> signer </span><span class="z-keyword">=</span><span class="z-support"> ecrecover</span><span>(</span><span>_hash</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 class="z-comment"> //</span><span class="z-comment"> Prevent signer from being 0x0</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> signer </span><span class="z-keyword">!=</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0x0</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;SignatureValidator#recoverSigner: INVALID_SIGNER&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> signer</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <p>Example implementation of a contract calling the isValidSignature() function on an external signing 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"> callERC1271isValidSignature</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _addr</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _hash</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 z-parameter z-function"> _signature</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> {</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span> result </span><span class="z-keyword">=</span><span class="z-entity z-name"> IERC1271Wallet</span><span>(</span><span>_addr</span><span>)</span><span>.</span><span class="z-entity z-name">isValidSignature</span><span>(</span><span>_hash</span><span>,</span><span> _signature</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>result </span><span class="z-keyword">==</span><span class="z-constant"> 0x1626ba7e</span><span>,</span><span class="z-string"> &quot;INVALID_SIGNATURE&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Since there are no gas-limit expected for calling the isValidSignature() function, it is possible that some implementation will consume a large amount of gas. It is therefore important to not hardcode an amount of gas sent when calling this method on an external contract as it could prevent the validation of certain signatures.</p> <p>Note also that each contract implementing this method is responsible to ensure that the signature passed is indeed valid, otherwise catastrophic outcomes are to be 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> 2018-07-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Micah Zoltuhttps://github.com/MicahZoltu https://wg-eips.ritovision.com/1240/ <h2 id="simple-summary">Simple Summary</h2> <p>The average block times are increasing due to the difficulty bomb (also known as the "<em>ice age</em>") slowly accelerating. This EIP proposes to remove the difficulty increase over time and replace it with a fixed difficulty targeting 15 second blocks.</p> <h2 id="abstract">Abstract</h2> <p>Starting with <code>FORK_BLOCK_NUMBER</code> the client will calculate the difficulty without considering the current block number.</p> <h2 id="motivation">Motivation</h2> <p>The difficulty bomb operates under the assumption that miners decide what code economic participants are running, rather than economic participants deciding for themselves. In reality, miners will mine whatever chain is most profitable and the most profitable chain is the one that economic participants use. If 99% of miners mine a chain that no economic participants use then that chain will have no value and the miners will cease mining of it in favor of some other chain that does have economic participants. Another way to put this is that miners will follow economic participants, not the other way around.</p> <h2 id="specification">Specification</h2> <h4 id="remove-difficulty">Remove Difficulty</h4> <p>For the purposes of <code>calc_difficulty</code>, if <code>block.number &gt;= FORK_BLOCK_NUMBER</code> then change the epsilon component to <code>0</code> rather than having it be a function of block number.</p> <h2 id="rationale">Rationale</h2> <p>With the difficulty bomb removed, when Casper is released it will be up to economic participants to decide whether they want the features that Casper enables or not. If they do not want Casper, they are free to continue running unpatched clients and participating in the Ethereum network as it exists today. This freedom of choice is the cornerstone of DLTs and making it hard for people to make that choice (by creating an artificial pressure) does not work towards that goal of freedom of choice. If the development team is not confident that economic participants will want Casper, then they should re-evaluate their priorities rather than trying to force Casper onto users.</p> <p>Author Personal Note: I think we will see almost all economic participants in Ethereum switch to PoS/Sharding without any extra pressure beyond client defaults.</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.</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="implementations">Implementations</h2> <p>The yellow paper implements this change in https://github.com/ethereum/yellowpaper/pull/710</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-19T00:00:00+00:00 2026-02-11T14:49:27+00:00 Afri Schoedonhttps://github.com/5chdn https://wg-eips.ritovision.com/1234/ <h2 id="simple-summary">Simple Summary</h2> <p>The average block times are increasing due to the difficulty bomb (also known as the "<em>ice age</em>") slowly accelerating. This EIP proposes to delay the difficulty bomb for approximately 12 months 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 based on a fake block number suggesting the client that the difficulty bomb is adjusting around 5 million blocks later than previously specified with the Homestead fork. 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>The Casper development and switch to proof-of-stake is delayed, the Ethash proof-of-work should be feasible for miners and allow sealing new blocks every 15 seconds on average for another 12 months. With the delay of the ice age, there is a desire to not suddenly also increase miner rewards. The difficulty bomb has been known about for a long time and now it's going to stop from happening. In order to maintain stability of the system, a block reward reduction that offsets the ice age delay would leave the system in the same general state as before. 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="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 - 5_000_000) if block.number &gt;= CNSTNTNPL_FORK_BLKNUM else block.number</span></span></code></pre><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 delay the ice age by 29 million seconds (approximately 12 months), so the chain would be back at 30 second block times in winter 2019. An alternate proposal was to add special rules to the difficulty calculation to effectively <em>pause</em> the difficulty between different blocks. This would lead to similar results.</p> <p>This was previously discussed at All Core Devs Meeting <a rel="external" href="https://github.com/ethereum/pm/blob/6dbd82303bfcb697eaf9a76de37f5fa570e6379d/AllCoreDevs-EL-Meetings/Meeting%2042.md">#42</a> and subsequent meetings; and accepted in the Constantinople Session <a rel="external" href="https://github.com/ethereum/pm/issues/55">#1</a>.</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 in it's logic does not differ from <a href="https://wg-eips.ritovision.com/649/">EIP-649</a>; an implementation for Parity-Ethereum is available in <a rel="external" href="https://github.com/paritytech/parity-ethereum/pull/9187">parity-ethereum#9187</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-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv ERC-1202 Working Grouperc1202@googlegroups.com https://wg-eips.ritovision.com/1202/

A general interface for voting on-chain

<h2 id="abstract">Abstract</h2> <p>This EIP is an API for implementing voting with smart contract. This standard provides functionalities to voting as well as to view the vote result and set voting status.</p> <h2 id="motivation">Motivation</h2> <p>Voting is one of the earliest example of EVM programming, and also a key to DAO/organizational governance process. We foresee many DAOs will ultimately need to leverage voting as one of the important part of their governance. By creating a voting standard for smart contract / token, we can have the following benefits</p> <h3 id="benefits-of-having-a-standard">Benefits of having a standard</h3> <ol> <li>Allow general UI and applications to be built on top of a standardized voting to allow more general user to participate, and encourage more DApp and DAO to think about their governance</li> <li>Allow delegate voting / smart contract voting, automatic voting</li> <li>Allow voting results to be recorded on-chain, in a standard way, and allow DAOs and DApps to honor the voting result programmatically.</li> <li>Allow the compatibility with token standard such as <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> or other new standards(<a href="https://wg-eips.ritovision.com/777/">ERC-777</a>) and item standard such as <a href="https://wg-eips.ritovision.com/721/">ERC-721</a></li> <li>Create massive potential for interoperability within Ethereum echo systems and other system.</li> <li>Allow setting voting deadline, allow determine on single or multiple options. Allow requiring voting orders. (trade-off is interface complexity, we might need <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> approach and later a <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> for advanced voting)</li> <li>Recording the voting with weights with token amount.</li> <li>Possibly allow trust-worthy privacy-safe voting and anonymous voting (with either voter address being un-associated with the vote they cast, given a list of randomized/obfuscated voting options).</li> <li>Possibly allow result in reward by voting participation or voting result.</li> </ol> <h3 id="non-goal-out-of-scope">Non-Goal / Out of Scope</h3> <ol> <li><strong>Delegation</strong>: We intentionally leave delegation out of scope. A separate EIP could be proposed to address this particular use case.</li> <li><strong>Eligibility or Weights</strong>: Some of the implementing want to have weights or eligibility to vote to be configurable. Such as OpenZeppelin's implementation of GovernorBravo uses snapshot. Aslo weights calculation such as quadratic voting is not within the scope of this EIP. This EIP is intend to be flexible for any current and new voting weights calculation.</li> <li><strong>Proposal</strong>: We intentionally leave Proposal out of scope. Proposals are going to be identified by <code>proposalId</code> but what information of the proposal includes, whether they are on-chain or off-chain and whether they are exeutable, is leaved out from this proposal. A separate EIP could be proposed to address this particular use case. See one of such proposals <a href="https://wg-eips.ritovision.com/5247/">ERC-5247</a></li> <li><strong>Signature Aggregations / Endorsement</strong>: When implementing contracts want to allow user to submit their vote or approval of vote offline and have some other account to generate the transaction, the signature aggregations or endorsements are not in scope of this EIP. A separate EIP could be proposed to address this particular use case. See one of such proposals here <a href="https://wg-eips.ritovision.com/5453/">ERC-5453</a>.</li> </ol> <h3 id="use-cases">Use-cases</h3> <ol> <li>Determine on issuing new token, issuing more token or issuing sub-token</li> <li>Determine on creating new item under <a href="https://wg-eips.ritovision.com/721/">ERC-721</a></li> <li>Determine on election on certain person or smart contract to be delegated leader for project or subproject</li> <li>Determine on auditing result ownership allowing migration of smart contract proxy address</li> </ol> <h2 id="specification">Specification</h2> <ol> <li>Compliant contracts MUST implement the <code>IERC1202Core</code> below</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"> IERC1202Core</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> VoteCast</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"> voter</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"> proposalId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> support</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> weight</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> reason</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> extraParams</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"> castVote</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> proposalId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> support</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> weight</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"> reasonUri</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"> extraParams</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 class="z-keyword"> returns</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function castVoteFrom(</span></span> <span class="giallo-l"><span> address from,</span></span> <span class="giallo-l"><span> uint256 proposalId,</span></span> <span class="giallo-l"><span> uint8 support,</span></span> <span class="giallo-l"><span> uint256 weight,</span></span> <span class="giallo-l"><span> string calldata reasonUri,</span></span> <span class="giallo-l"><span> bytes calldata extraParams</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 class="z-keyword"> returns</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function execute(uint256 proposalId, bytes memory extraParams</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="2"> <li>Compliant contracts MAY implement the <code>IERC1202MultiVote</code> Interface. If the intention is for multi-options to be supported, e.g. for ranked-choices or variant weights voting, Compliant contracts MUST implement <code>IERC1202MultiVote</code> 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"> IERC1202MultiVote</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MultiVoteCast</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"> voter</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"> proposalId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span>[</span><span>]</span><span class="z-variable"> support</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> weight</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> reason</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> extraParams</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"> castMultiVote</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> proposalId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span>[</span><span>]</span><span class="z-variable"> support</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> weight</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"> reasonUri</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"> extraParams</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></span></code></pre> <ol start="3"> <li>the compliant contract SHOULD implement <a href="https://wg-eips.ritovision.com/5269/">ERC-5269</a> interface.</li> </ol> <h3 id="getting-info-voting-period-eligibility-weight">Getting Info: Voting Period, Eligibility, Weight</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"> IERC1202Info</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> votingPeriodFor</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> 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">uint256</span><span class="z-variable"> startPointOfTime</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> endPointOfTime</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> eligibleVotingWeight</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> proposalId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> voter</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> <p>We made the following design decisions and here are the rationales.</p> <h3 id="granularity-and-anonymity">Granularity and Anonymity</h3> <p>We created a <code>view</code> function <code>ballotOf</code> primarily making it easier for people to check the vote from certain address. This has the following assumptions:</p> <ul> <li> <p>It's possible to check someone's vote directly given an address. If implementor don't want to make it so easily, they can simply reject all calls to this function. We want to make sure that we support both anonymous voting an non-anonymous voting. However since all calls to a smart contract is logged in block history, there is really no secrecy unless done with cryptography tricks. I am not cryptography-savvy enough to comment on the possibility. Please see "Second Feedback Questions 2018" for related topic.</p> </li> <li> <p>It's assumes for each individual address, they can only vote for one decision. They can distribute their available voting power into more granular level. If implementor wants allow this, they ask the user to create another wallet address and grant the new address certain power. For example, a token based voting where voting weight is determined by the amount of token held by a voter, a voter who wants to distribute its voting power in two different option(option set) can transfer some of the tokens to the new account and cast the votes from both accounts.</p> </li> </ul> <h3 id="weights">Weights</h3> <p>We assume there are <code>weight</code> of votes and can be checked by calling <code>eligibleVotingWeight(proposalId, address voter)</code>, and the weight distribution is either internally determined or determined by constructor.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <ol> <li>The <code>support</code> options are chosen to be <code>uint8</code> for the purpose to be backward compatible for GovernorBravo. It can be increased in the future</li> </ol> <h2 id="security-considerations">Security Considerations</h2> <p>We expect the voting standard to be used in connection with other contracts such as token distributions, conducting actions in consensus or on behalf of an entity, multi-signature wallets, etc.</p> <p>The major security consideration is to ensure only using the standard interface for performing downstream actions or receiving upstream input (vote casting). We expect future audit tool to be based on standard interfaces.</p> <p>It's also important to note as discussed in this standard that for the sake of simplicity, this EIP is kept in the very basic form. It can be extended to support many different implementation variations. Such variations might contain different assumptions of the behavior and interpretation of actions. One example would be: What does it mean if someone votes multiple times through <code>vote</code>?</p> <ul> <li>Would that mean the voter is increasing their weight, or</li> <li>vote multiple options in the meanwhile, or</li> <li>Does the latter vote override the previous vote?</li> </ul> <p>Because of the flexible nature of voting, we expect many subsequent standards need to be created as an extension of this EIP. We suggest any extension or implementations of this standard be thoroughly audited before included in large scale or high asset volume applications.</p> <p>The third consideration is non-triviality. Some voting applications assume <em><strong>anonymity</strong></em>, <em><strong>randomness</strong></em>, <em><strong>time-based deadline</strong></em>, <em><strong>ordering</strong></em>, etc, these requirements in Ethereum are known to be non-trivial to achieve. We suggest any applications or organizations rely on audited and time-proven shared libraries when these requirements need to be enforced in their applications.</p> <p>The fourth consideration is potential abuse. When voting is standardized and put on contract, it is possible to write another contract that rewards a voter to vote in a certain way. It creates potential issues of bribery and conflict of interest abuse that is previously hard to implement.</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-07T00:00:00+00:00 2026-02-11T14:48:25+00:00 Matt Lockyermattdlockyer@gmail.com Nick Mudgenick@perfectabstractions.com Jordan Schalmjordan.schalm@gmail.com sebastian echeverrysebastian.echeverry@robotouniverse.com Zainan Victor Zhouhttps://github.com/xinbenlv https://wg-eips.ritovision.com/998/

Extends a ERC-721 to own other ERC-721 and ERC-20 tokens.

<h2 id="abstract">Abstract</h2> <p>An extension of the <a href="https://wg-eips.ritovision.com/721/">ERC-721 standard</a> to enable ERC-721 tokens to own other ERC-721 tokens and <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens.</p> <p>An extension of the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <code>ERC-223 https://github.com/ethereum/EIPs/issues/223</code> standards to enable ERC-20 and <code>ERC-223</code> tokens to be owned by ERC-721 tokens.</p> <p>This specification covers four different kinds of composable tokens:</p> <ol> <li><a href="https://wg-eips.ritovision.com/998/#erc-721-top-down-composable"><code>ERC998ERC721</code> top-down composable tokens that receive, hold and transfer ERC-721 tokens</a></li> <li><a href="https://wg-eips.ritovision.com/998/#erc-20-top-down-composable"><code>ERC998ERC20</code> top-down composable tokens that receive, hold and transfer ERC-20 tokens</a></li> <li><a href="https://wg-eips.ritovision.com/998/#erc-721-bottom-up-composable"><code>ERC998ERC721</code> bottom-up composable tokens that attach themselves to other ERC-721 tokens.</a></li> <li><a href="https://wg-eips.ritovision.com/998/#erc-20-bottom-up-composable"><code>ERC998ERC20</code> bottom-up composable tokens that attach themselves to ERC-721 tokens.</a></li> </ol> <p>which map to</p> <ol> <li>An <code>ERC998ERC721</code> top-down composable is an ERC-721 token with additional functionality for owning other ERC-721 tokens.</li> <li>An <code>ERC998ERC20</code> top-down composable is an ERC-721 token with additional functionality for owning ERC-20 tokens.</li> <li>An <code>ERC998ERC721</code> bottom-up composable is an ERC-721 token with additional functionality for being owned by an ERC-721 token.</li> <li>An <code>ERC998ERC20</code> bottom-up composable is an ERC-20 token with additional functionality for being owned by an ERC-721 token.</li> </ol> <p>A top-down composable contract stores and keeps track of child tokens for each of its tokens.</p> <p>A bottom-up composable contract stores and keeps track of a parent token for each its tokens.</p> <p>With composable tokens it is possible to compose lists or trees of ERC-721 and ERC-20 tokens connected by ownership. Any such structure will have a single owner address at the root of the structure that is the owner of the entire composition. The entire composition can be transferred with one transaction by changing the root owner.</p> <p>Different composables, top-down and bottom-up, have their advantages and disadvantages which are explained in the <a href="https://wg-eips.ritovision.com/998/#rationale">Rational section</a>. It is possible for a token to be one or more kinds of composable token.</p> <p>A non-fungible token is compliant and Composable of this EIP if it implements one or more of the following interfaces:</p> <ul> <li><code>ERC998ERC721TopDown</code></li> <li><code>ERC998ERC20TopDown</code></li> <li><code>ERC998ERC721BottomUp</code></li> <li><code>ERC998ERC20BottomUp</code></li> </ul> <h2 id="specification">Specification</h2> <h3 id="erc-721">ERC-721</h3> <p><code>ERC998ERC721</code> top-down, <code>ERC998ERC20</code> top-down, and <code>ERC998ERC721</code> bottom-up composable contracts must implement the <a href="https://wg-eips.ritovision.com/721/">ERC-721 interface</a>.</p> <h3 id="erc-20">ERC-20</h3> <p><code>ERC998ERC20</code> bottom-up composable contracts must implement the <a href="https://wg-eips.ritovision.com/20/">ERC-20 interface</a>.</p> <h3 id="erc-165"><a href="https://wg-eips.ritovision.com/165/">ERC-165</a></h3> <p>The <a href="https://wg-eips.ritovision.com/165/">ERC-165 standard</a> must be applied to each <a href="https://wg-eips.ritovision.com/998/">ERC-998</a> interface that is used.</p> <h3 id="authentication">Authentication</h3> <p>Authenticating whether a user or contract can execute some action works the same for both <code>ERC998ERC721</code> top-down and <code>ERC998ERC721</code> bottom-up composables.</p> <p>A <code>rootOwner</code> refers to the owner address at the top of a tree of composables and ERC-721 tokens.</p> <p>Authentication within any composable is done by finding the rootOwner and comparing it to <code>msg.sender</code>, the return result of <code>getApproved(tokenId)</code> and the return result of <code>isApprovedForAll(rootOwner, msg.sender)</code>. If a match is found then authentication passes, otherwise authentication fails and the contract throws.</p> <p>Here is an example of authentication code:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">address</span><span> rootOwner </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span class="z-entity z-name">rootOwnerOf</span><span>(</span><span>_tokenId</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">require</span><span>(</span><span>rootOwner </span><span class="z-keyword">==</span><span class="z-variable z-language"> msg.sender</span><span class="z-keyword"> ||</span><span> </span></span> <span class="giallo-l"><span class="z-entity z-name"> isApprovedForAll</span><span>(</span><span>rootOwner</span><span>,</span><span class="z-variable z-language">msg.sender</span><span>)</span><span class="z-keyword"> ||</span></span> <span class="giallo-l"><span class="z-entity z-name"> getApproved</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></code></pre> <p>The <code>approve(address _approved, uint256 _tokenId)</code> and <code>getApproved(uint256 _tokenId)</code> ERC-721 functions are implemented specifically for the rootOwner. This enables a tree of composables to be transferred to a new rootOwner without worrying about which addresses have been approved in child composables, because any prior approves can only be used by the prior rootOwner.</p> <p>Here are example implementations:</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"> _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> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> rootOwner </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span class="z-entity z-name">rootOwnerOf</span><span>(</span><span>_tokenId</span><span>)</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>rootOwner </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"> isApprovedForAll</span><span>(</span><span>rootOwner</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> rootOwnerAndTokenIdToApprovedAddress</span><span>[</span><span>rootOwner</span><span>]</span><span>[</span><span>_tokenId</span><span>]</span><span class="z-keyword"> =</span><span> _approved</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Approval</span><span>(</span><span>rootOwner</span><span>,</span><span> _approved</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"> getApproved</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"> 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> rootOwner </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span class="z-entity z-name">rootOwnerOf</span><span>(</span><span>_tokenId</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> rootOwnerAndTokenIdToApprovedAddress</span><span>[</span><span>rootOwner</span><span>]</span><span>[</span><span>_tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="traversal">Traversal</h3> <p>The rootOwner of a composable is gotten by calling <code>rootOwnerOf(uint256 _tokenId)</code> or <code>rootOwnerOfChild(address _childContract, uint256 _childTokenId)</code>. These functions are used by top-down and bottom-up composables to traverse up the tree of composables and ERC-721 tokens to find the rootOwner.</p> <p><code>ERC998ERC721</code> top-down and bottom-up composables are interoperable with each other. It is possible for a top-down composable to own a bottom-up composable or for a top-down composable to own an ERC-721 token that owns a bottom-up token. In any configuration calling <code>rootOwnerOf(uint256 _tokenID)</code> on a composable will return the root owner address at the top of the ownership tree.</p> <p>It is important to get the traversal logic of <code>rootOwnerOf</code> right. The logic for <code>rootOwnerOf</code> is the same whether or not a composable is bottom-up or top-down or both. Here is the logic:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Logic for rootOwnerOf(uint256 _tokenId)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>If the token is a bottom-up composable and has a parent token then call rootOwnerOf for the parent token.</span></span> <span class="giallo-l"><span> If the call was successful then the returned address is the rootOwner.</span></span> <span class="giallo-l"><span> Otherwise call rootOwnerOfChild for the parent token.</span></span> <span class="giallo-l"><span> If the call was successful then the returned address is the rootOwner.</span></span> <span class="giallo-l"><span> Otherwise get the owner address of the token and that is the rootOwner.</span></span> <span class="giallo-l"><span>Otherwise call rootOwnerOfChild for the token</span></span> <span class="giallo-l"><span> If the call was successful then the returned address is the rootOwner.</span></span> <span class="giallo-l"><span> Otherwise get the owner address of the token and that is the rootOwner.</span></span></code></pre> <p>Calling <code>rootOwnerOfChild</code> for a token means the following logic:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Logic for calling rootOwnerOfChild for a tokenId</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>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support">address</span><span> childContract </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-support">bytes32</span><span> rootOwner </span><span class="z-keyword">=</span><span class="z-entity z-name"> ERC998ERC721</span><span>(</span><span>tokenOwner</span><span>)</span><span>.</span><span class="z-entity z-name">rootOwnerOfChild</span><span>(</span><span>childContract</span><span>,</span><span> tokenId</span><span>)</span><span>;</span></span></code></pre> <p>But understand that the real call to <code>rootOwnerOfChild</code> should be made with assembly so that the code can check if the call failed and so that the <code>staticcall</code> opcode is used to ensure that no state is modified.</p> <p>Tokens/contracts that implement the above authentication and traversal functionality are "composable aware".</p> <h3 id="composable-transfer-function-parameter-format">Composable Transfer Function Parameter Format</h3> <p>Composable functions that make transfers follow the same parameter format: <strong>from:to:what</strong>.</p> <p>For example the <code>getChild(address _from, uint256 _tokenId, address _childContract, uint256 _childTokenId)</code> composable function transfers an ERC-721 token from an address to a top-down composable. The <code>_from</code> parameter is the <strong>from</strong>, the <code>_tokenId</code> parameter is the <strong>to</strong> and the <code>address _childContract, uint256 _childTokenId</code> parameters are the <strong>what</strong>.</p> <p>Another example is the <code>safeTransferChild(uint256 _fromTokenId, address _to, address _childContract, uint256 _childTokenId)</code> function. The <code>_fromTokenId</code> is the <strong>from</strong>, the <code>_to</code> is the <strong>to</strong> and the <code>address _childContract, address _childTokenId</code> parameters are the <strong>what</strong>.</p> <h3 id="transferfrom-safetransferfrom-functions-do-not-transfer-tokens-owned-by-tokens">transferFrom/safeTransferFrom Functions Do Not Transfer Tokens Owned By Tokens</h3> <p>In bottom-up and top-down composable contracts the <code>transferFrom</code> and <code>safeTransferFrom</code> functions must throw if they are called directly to transfer a token that is owned by another token.</p> <p>The reason for this is that these functions do not explicitly specify which token owns a token to be transferred. <a href="https://wg-eips.ritovision.com/998/#explicit-transfer-parameters">See the rational section for more information about this.</a></p> <p><code>transferFrom/safeTransferFrom</code> functions must be used to transfer tokens that are owned by an address.</p> <h3 id="erc-721-top-down-composable">ERC-721 Top-Down Composable</h3> <p>ERC-721 top-down composables act as containers for ERC-721 tokens.</p> <p>ERC-721 top-down composables are ERC-721 tokens that can receive, hold and transfer ERC-721 tokens.</p> <p>There are two ways to transfer a ERC-721 token to a top-down composable:</p> <ol> <li>Use the <code>function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes data)</code> function. The <code>_to</code> argument is the top-down composable contract address. The <code>bytes data</code> argument holds the integer value of the top-down composable tokenId that the ERC-721 token is transferred to.</li> <li>Call <code>approve</code> in the ERC-721 token contract for the top-down composable contract. Then call <code>getChild</code> in the composable contract.</li> </ol> <p>The first ways is for ERC-721 contracts that have a <code>safeTransferFrom</code> function. The second way is for contracts that do not have this function such as cryptokitties.</p> <p>Here is an example of transferring ERC-721 token 3 from an address to top-down composable token 6:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">uint256</span><span> tokenId </span><span class="z-keyword">=</span><span class="z-constant"> 6</span><span>;</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span> tokenIdBytes </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> bytes</span><span>(</span><span class="z-constant">32</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">assembly</span><span> {</span><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-entity z-name">add</span><span>(</span><span>tokenIdBytes</span><span>,</span><span class="z-constant"> 32</span><span>)</span><span>,</span><span> tokenId</span><span>)</span><span> }</span></span> <span class="giallo-l"><span class="z-entity z-name">ERC721</span><span>(</span><span>contractAddress</span><span>)</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span><span>userAddress</span><span>,</span><span> composableAddress</span><span>,</span><span class="z-constant"> 3</span><span>,</span><span> tokenIdBytes</span><span>)</span><span>;</span></span></code></pre> <p>Every ERC-721 top-down composable compliant contract must implement the <code>ERC998ERC721TopDown</code> interface.</p> <p>The <code>ERC998ERC721TopDownEnumerable</code> and <code>ERC998ERC20TopDownEnumerable</code> interfaces are optional.</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.24</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"> `ERC998ERC721` Top-Down Composable Non-Fungible 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/./00998.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 0xcde244d9</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC998ERC721TopDown</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 token receives a child 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"> _from</span><span class="z-comment"> The prior owner of 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"> _toTokenId</span><span class="z-comment"> The token that receives the child token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ReceivedChild</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-storage z-type"> indexed</span><span class="z-variable"> _toTokenId</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"> _childContract</span><span>, </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _childTokenId</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 child token is transferred from a token to an 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"> _fromTokenId</span><span class="z-comment"> The parent token that the child token is being transferred from.</span></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 new owner address of the child token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferChild</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"> _fromTokenId</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"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _childContract</span><span>, </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _childTokenId</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"> Get the root owner of 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"> _tokenId</span><span class="z-comment"> The token to query for a root owner 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"> rootOwner</span><span class="z-comment"> The root owner at the top of tree of tokens and ERC-998 magic value.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> rootOwnerOf</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"> 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"> rootOwner</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"> Get the root owner of a child 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"> _childContract</span><span class="z-comment"> The contract address of the child 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"> _childTokenId</span><span class="z-comment"> The tokenId of the child.</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"> rootOwner</span><span class="z-comment"> The root owner at the top of tree of tokens and ERC-998 magic value.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> rootOwnerOfChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</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 class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> rootOwner</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"> Get the parent tokenId of a child 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"> _childContract</span><span class="z-comment"> The contract address of the child 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"> _childTokenId</span><span class="z-comment"> The tokenId of the child.</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"> parentTokenOwner</span><span class="z-comment"> The parent address of the parent token and ERC-998 magic value</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"> parentTokenId</span><span class="z-comment"> The parent tokenId of _tokenId</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> ownerOfChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</span></span> <span class="giallo-l"><span> )</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"> 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"> bytes32</span><span class="z-variable"> parentTokenOwner</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> parentTokenId</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"> @notice</span><span class="z-comment"> A token receives a child 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"> _operator</span><span class="z-comment"> The address that caused the 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"> _from</span><span class="z-comment"> The owner of the child 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"> _childTokenId</span><span class="z-comment"> The token that is being transferred to the parent.</span></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"> Up to the first 32 bytes contains an integer which is the receiving parent tokenId. </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 z-parameter z-function"> _operator</span><span>,</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></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</span><span>,</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> </span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span> </span></span> <span class="giallo-l"><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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer child token from top-down composable 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"> _fromTokenId</span><span class="z-comment"> The owning token to transfer from.</span></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 receives the child 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"> _childContract</span><span class="z-comment"> The ERC-721 contract of the child 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"> _childTokenId</span><span class="z-comment"> The tokenId of the token that is being transferred.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</span></span> <span class="giallo-l"><span> )</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></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer child token from top-down composable 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"> _fromTokenId</span><span class="z-comment"> The owning token to transfer from.</span></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 receives the child 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"> _childContract</span><span class="z-comment"> The ERC-721 contract of the child 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"> _childTokenId</span><span class="z-comment"> The tokenId of the token that is being transferred.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeTransferChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</span></span> <span class="giallo-l"><span> )</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></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer child token from top-down composable 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"> _fromTokenId</span><span class="z-comment"> The owning token to transfer from.</span></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 receives the child 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"> _childContract</span><span class="z-comment"> The ERC-721 contract of the child 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"> _childTokenId</span><span class="z-comment"> The tokenId of the token that is being transferred.</span></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"> function</span><span class="z-entity z-name"> safeTransferChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</span><span>,</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> </span></span> <span class="giallo-l"><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 bottom-up composable child token from top-down composable to other ERC-721 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"> _fromTokenId</span><span class="z-comment"> The owning token to transfer from.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _toContract</span><span class="z-comment"> The ERC-721 contract of the receiving 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"> _toTokenId</span><span class="z-comment"> The receiving 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"> _childContract</span><span class="z-comment"> The bottom-up composable contract of the child 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"> _childTokenId</span><span class="z-comment"> The token that is being transferred.</span></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"> function</span><span class="z-entity z-name"> transferChildToParent</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _toContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _toTokenId</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</span><span>,</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> </span></span> <span class="giallo-l"><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"> Get a child token from an ERC-721 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"> _from</span><span class="z-comment"> The address that owns the child 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"> The token that becomes the parent 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"> _childContract</span><span class="z-comment"> The ERC-721 contract of the child 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"> _childTokenId</span><span class="z-comment"> The tokenId of the child token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getChild</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></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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</span></span> <span class="giallo-l"><span> )</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></span></code></pre><h4 id="rootownerof-1"><code>rootOwnerOf</code> 1</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the root owner of 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"> _tokenId</span><span class="z-comment"> The token to query for a root owner 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"> rootOwner</span><span class="z-comment"> The root owner at the top of tree of tokens and ERC-998 magic value.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> rootOwnerOf</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"> 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"> rootOwner</span><span>)</span><span>;</span></span></code></pre> <p>This function traverses token owners until the root owner address of <code>_tokenId</code> is found.</p> <p>The first 4 bytes of rootOwner contain the ERC-998 magic value <code>0xcd740db5</code>. The last 20 bytes contain the root owner address.</p> <p>The magic value is returned because this function may be called on contracts when it is unknown if the contracts have a <code>rootOwnerOf</code> function. The magic value is used in such calls to ensure a valid return value is received.</p> <p>If it is unknown whether a contract has the <code>rootOwnerOf</code> function then the first four bytes of the <code>rootOwner</code> return value must be compared to <code>0xcd740db5</code>.</p> <p><code>0xcd740db5</code> is equal to:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-variable z-language">this</span><span>.</span><span>rootOwnerOf</span><span>.</span><span>selector </span><span class="z-keyword">^</span><span class="z-variable z-language"> this</span><span>.</span><span>rootOwnerOfChild</span><span>.</span><span>selector </span><span class="z-keyword">^</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-language">this</span><span>.</span><span>tokenOwnerOf</span><span>.</span><span>selector </span><span class="z-keyword">^</span><span class="z-variable z-language"> this</span><span>.</span><span>ownerOfChild</span><span>.</span><span>selector</span><span>;</span></span></code></pre> <p>Here is an example of a value returned by <code>rootOwnerOf</code>. <code>0xcd740db50000000000000000e5240103e1ff986a2c8ae6b6728ffe0d9a395c59</code></p> <h4 id="rootownerofchild">rootOwnerOfChild</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the root owner of a child 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"> _childContract</span><span class="z-comment"> The contract address of the child 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"> _childTokenId</span><span class="z-comment"> The tokenId of the child.</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"> rootOwner</span><span class="z-comment"> The root owner at the top of tree of tokens and ERC-998 magic value.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> rootOwnerOfChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</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 class="z-support">bytes32</span><span class="z-variable"> rootOwner</span><span>)</span><span>;</span></span></code></pre> <p>This function traverses token owners until the root owner address of the supplied child token is found.</p> <p>The first 4 bytes of rootOwner contain the ERC-998 magic value <code>0xcd740db5</code>. The last 20 bytes contain the root owner address.</p> <p>The magic value is returned because this function may be called on contracts when it is unknown if the contracts have a <code>rootOwnerOf</code> function. The magic value is used in such calls to ensure a valid return value is received.</p> <p>If it is unknown whether a contract has the <code>rootOwnerOfChild</code> function then the first four bytes of the <code>rootOwner</code> return value must be compared to <code>0xcd740db5</code>.</p> <h4 id="ownerofchild">ownerOfChild</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the parent tokenId of a child 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"> _childContract</span><span class="z-comment"> The contract address of the child 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"> _childTokenId</span><span class="z-comment"> The tokenId of the child.</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"> parentTokenOwner</span><span class="z-comment"> The parent address of the parent token and ERC-998 magic value</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"> parentTokenId</span><span class="z-comment"> The parent tokenId of _tokenId</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> ownerOfChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</span></span> <span class="giallo-l"><span>)</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"> 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"> address</span><span class="z-variable"> parentTokenOwner</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> parentTokenId</span></span> <span class="giallo-l"><span> )</span><span>;</span></span></code></pre> <p>This function is used to get the parent tokenId of a child token and get the owner address of the parent token.</p> <p>The first 4 bytes of parentTokenOwner contain the ERC-998 magic value <code>0xcd740db5</code>. The last 20 bytes contain the parent token owner address.</p> <p>The magic value is returned because this function may be called on contracts when it is unknown if the contracts have a <code>ownerOfChild</code> function. The magic value is used in such calls to ensure a valid return value is received.</p> <p>If it is unknown whether a contract has the <code>ownerOfChild</code> function then the first four bytes of the <code>parentTokenOwner</code> return value must be compared to <code>0xcd740db5</code>.</p> <h4 id="onerc721received"><code>onERC721Received</code></h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> A token receives a child 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"> _operator</span><span class="z-comment"> The address that caused the 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"> _from</span><span class="z-comment"> The prior owner of the child 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"> _childTokenId</span><span class="z-comment"> The token that is being transferred to the parent.</span></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"> Up to the first 32 bytes contains an integer which is the receiving parent tokenId. </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 z-parameter z-function"> _operator</span><span>,</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></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</span><span>,</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> </span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bytes4</span><span>)</span><span>;</span></span></code></pre> <p>This is a function defined in the ERC-721 standard. This function is called in an ERC-721 contract when <code>safeTransferFrom</code> is called. The <code>bytes _data</code> argument contains an integer value from 1 to 32 bytes long that is the parent tokenId that an ERC-721 token is transferred to.</p> <p>The <code>onERC721Received</code> function is how a top-down composable contract is notified that an ERC-721 token has been transferred to it and what tokenId in the top-down composable is the parent tokenId.</p> <p>The return value for <code>onERC721Received</code> is the magic value <code>0x150b7a02</code> which is equal to <code>bytes4(keccak256(abi.encodePacked("onERC721Received(address,address,uint256,bytes)")))</code>.</p> <h4 id="transferchild">transferChild</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer child token from top-down composable 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"> _fromTokenId</span><span class="z-comment"> The owning token to transfer from.</span></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 receives the child 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"> _childContract</span><span class="z-comment"> The ERC-721 contract of the child 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"> _childTokenId</span><span class="z-comment"> The tokenId of the token that is being transferred.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> transferChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</span></span> <span class="giallo-l"><span>)</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>This function authenticates <code>msg.sender</code> and transfers a child token from a top-down composable to a different address.</p> <p>This function makes this call within it:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name">ERC721</span><span>(</span><span>_childContract</span><span>)</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span> _to</span><span>,</span><span> _childTokenId</span><span>)</span><span>;</span></span></code></pre><h4 id="safetransferchild-1">safeTransferChild 1</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer child token from top-down composable 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"> _fromTokenId</span><span class="z-comment"> The owning token to transfer from.</span></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 receives the child 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"> _childContract</span><span class="z-comment"> The ERC-721 contract of the child 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"> _childTokenId</span><span class="z-comment"> The tokenId of the token that is being transferred.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> safeTransferChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</span></span> <span class="giallo-l"><span>)</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>This function authenticates <code>msg.sender</code> and transfers a child token from a top-down composable to a different address.</p> <p>This function makes this call within it:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name">ERC721</span><span>(</span><span>_childContract</span><span>)</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span> _to</span><span>,</span><span> _childTokenId</span><span>)</span><span>;</span></span></code></pre><h4 id="safetransferchild-2">safeTransferChild 2</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer child token from top-down composable to address or other top-down composable.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _fromTokenId</span><span class="z-comment"> The owning token to transfer from.</span></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 receives the child 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"> _childContract</span><span class="z-comment"> The ERC721 contract of the child 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"> _childTokenId</span><span class="z-comment"> The tokenId of the token that is being transferred.</span></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, can be used to specify tokenId to transfer to</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> safeTransferChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</span><span>,</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> </span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>This function authenticates <code>msg.sender</code> and transfers a child token from a top-down composable to a different address or to a different top-down composable.</p> <p>A child token is transferred to a different top-down composable if the <code>_to</code> address is a top-down composable contract and <code>bytes _data</code> is supplied an integer representing the parent tokenId.</p> <p>This function makes this call within it:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name">ERC721</span><span>(</span><span>_childContract</span><span>)</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span> _to</span><span>,</span><span> _childTokenId</span><span>,</span><span> _data</span><span>)</span><span>;</span></span></code></pre><h4 id="transferchildtoparent">transferChildToParent</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer bottom-up composable child token from top-down composable to other ERC-721 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"> _fromTokenId</span><span class="z-comment"> The owning token to transfer from.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _toContract</span><span class="z-comment"> The ERC-721 contract of the receiving 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"> _toToken</span><span class="z-comment"> The receiving 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"> _childContract</span><span class="z-comment"> The bottom-up composable contract of the child 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"> _childTokenId</span><span class="z-comment"> The token that is being transferred.</span></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">function</span><span class="z-entity z-name"> transferChildToParent</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _toContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _toTokenId</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</span><span>,</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> </span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span></code></pre> <p>This function authenticates <code>msg.sender</code> and transfers a child bottom-up composable token from a top-down composable to a different ERC-721 token. This function can only be used when the child token is a bottom-up composable token. It is designed to transfer a bottom-up composable token from a top-down composable to an ERC-721 token (bottom-up style) in one transaction.</p> <p>This function makes this call within it:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name">ERC998ERC721BottomUp</span><span>(</span><span>_childContract</span><span>)</span><span>.</span><span class="z-entity z-name">transferToParent</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></span> <span class="giallo-l"><span> _toContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span> _toTokenId</span><span>,</span><span> </span></span> <span class="giallo-l"><span> _childTokenId</span><span>,</span><span> </span></span> <span class="giallo-l"><span> _data</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h4 id="getchild">getChild</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get a child token from an ERC-721 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"> _from</span><span class="z-comment"> The address that owns the child 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"> The token that becomes the parent 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"> _childContract</span><span class="z-comment"> The ERC-721 contract of the child 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"> _childTokenId</span><span class="z-comment"> The tokenId of the child token</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getChild</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></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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _childTokenId</span></span> <span class="giallo-l"><span>)</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>This function is used to transfer an ERC-721 token when its contract does not have a <code>safeTransferChild(uint256 _fromTokenId, address _to, address _childContract, uint256 _childTokenId, bytes _data)</code> function.</p> <p>A transfer with this function is done in two steps:</p> <ol> <li>The owner of the ERC-721 token calls <code>approve</code> or <code>setApprovalForAll</code> in the ERC-721 contract for the top-down composable contract.</li> <li>The owner of the ERC-721 token calls <code>getChild</code> in the top-down composable contract for the ERC-721 token.</li> </ol> <p>The <code>getChild</code> function must authenticate that <code>msg.sender</code> is the owner of the ERC-721 token in the ERC-721 contract or is approved or an operator of the ERC-721 token in the ERC-721 contract.</p> <h4 id="erc-721-top-down-composable-enumeration">ERC-721 Top-Down Composable Enumeration</h4> <p>Optional interface for top-down composable enumeration:</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 ERC-165 identifier for this interface is 0xa344afe4</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC998ERC721TopDownEnumerable</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 total number of child contracts with tokens that are owned by 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"> _tokenId</span><span class="z-comment"> The parent token of child tokens in child contracts</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 total number of child contracts with tokens owned by tokenId.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalChildContracts</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"> Get child contract by tokenId and 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"> _tokenId</span><span class="z-comment"> The parent token of child tokens in child 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"> _index</span><span class="z-comment"> The index position of the child 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"> childContract</span><span class="z-comment"> The contract found at the tokenId and index.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> childContractByIndex</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></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _index</span></span> <span class="giallo-l"><span> )</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"> view</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> childContract</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"> Get the total number of child tokens owned by tokenId that exist in a child 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"> _tokenId</span><span class="z-comment"> The parent token of child 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"> _childContract</span><span class="z-comment"> The child contract containing the child 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 total number of child tokens found in child contract that are owned by tokenId.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalChildTokens</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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span></span> <span class="giallo-l"><span> )</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"> view</span><span> </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 class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get child token owned by tokenId, in child contract, at index position</span></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 parent token of the child 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"> _childContract</span><span class="z-comment"> The child contract of the child 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"> The index position of the child 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"> childTokenId</span><span class="z-comment"> The child tokenId for the parent token, child token and index</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> childTokenByIndex</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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _childContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _index</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"> view</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> childTokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="erc-20-top-down-composable">ERC-20 Top-Down Composable</h3> <p>ERC-20 top-down composables act as containers for ERC-20 tokens.</p> <p>ERC-20 top-down composables are ERC-721 tokens that can receive, hold and transfer ERC-20 tokens.</p> <p>There are two ways to transfer ERC-20 tokens to an ERC-20 Top-Down Composable:</p> <ol> <li>Use the <code>transfer(address _to, uint256 _value, bytes _data);</code> function from the <code>ERC-223</code> contract. The <code>_to</code> argument is the ERC-20 top-down composable contract address. The <code>_value</code> argument is how many ERC-20 tokens to transfer. The <code>bytes</code> argument holds the integer value of the top-down composable tokenId that receives the ERC-20 tokens.</li> <li>Call <code>approve</code> in the ERC-20 contract for the ERC-20 top-down composable contract. Then call <code>getERC20(address _from, uint256 _tokenId, address _erc20Contract, uint256 _value)</code> from the ERC-20 top-down composable contract.</li> </ol> <p>The first way is for ERC-20 contracts that support the <code>ERC-223</code> standard. The second way is for contracts that do not.</p> <p>ERC-20 top-down composables 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-storage z-type"> @title</span><span class="z-comment"> `ERC998ERC20` Top-Down Composable Non-Fungible 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/./00998.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 0x7294ffed</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC998ERC20TopDown</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 token receives ERC-20 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"> _from</span><span class="z-comment"> The prior owner of 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"> _toTokenId</span><span class="z-comment"> The token that receives the ERC-20 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"> _erc20Contract</span><span class="z-comment"> The ERC-20 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"> _value</span><span class="z-comment"> The number of ERC-20 tokens received.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ReceivedERC20</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-storage z-type"> indexed</span><span class="z-variable"> _toTokenId</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"> _erc20Contract</span><span>, </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _value</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 token transfers ERC-20 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 that owned the ERC-20 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 receives the ERC-20 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"> _erc20Contract</span><span class="z-comment"> The ERC-20 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"> _value</span><span class="z-comment"> The number of ERC-20 tokens transferred.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferERC20</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"> _fromTokenId</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"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _erc20Contract</span><span>, </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _value</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"> A token receives ERC-20 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"> _from</span><span class="z-comment"> The prior owner of the ERC-20 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"> _value</span><span class="z-comment"> The number of ERC-20 tokens received</span></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"> Up to the first 32 bytes contains an integer which is the receiving tokenId. </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenFallback</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"> _value</span><span>,</span><span class="z-support"> bytes</span><span class="z-variable z-parameter z-function"> _data</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"> Look up the balance of ERC-20 tokens for a specific token and ERC-20 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"> _tokenId</span><span class="z-comment"> The token that owns the ERC-20 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"> _erc20Contract</span><span class="z-comment"> The ERC-20 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"> The</span><span class="z-comment"> number of ERC-20 tokens owned by a token from an ERC-20 contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOfERC20</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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _erc20Contract</span></span> <span class="giallo-l"><span> )</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"> view</span><span> </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 class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer ERC-20 tokens 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"> _tokenId</span><span class="z-comment"> The token to transfer from</span></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 address to send the ERC-20 tokens 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"> _erc20Contract</span><span class="z-comment"> The ERC-20 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"> _value</span><span class="z-comment"> The number of ERC-20 tokens to transfer</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferERC20</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></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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _erc20Contract</span><span>,</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 class="giallo-l"><span> )</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></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer ERC-20 tokens to address or ERC-20 top-down composable</span></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 transfer from</span></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 address to send the ERC-20 tokens 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"> _erc223Contract</span><span class="z-comment"> The `ERC-223` token 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"> _value</span><span class="z-comment"> The number of ERC-20 tokens 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"> _data</span><span class="z-comment"> Additional data with no specified format, can be used to specify tokenId to transfer to</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferERC223</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></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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _erc223Contract</span><span>,</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></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> <span class="giallo-l"><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"> Get ERC-20 tokens from ERC-20 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"> _from</span><span class="z-comment"> The current owner address of the ERC-20 tokens that are being transferred.</span></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 transfer the ERC-20 tokens 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"> _erc20Contract</span><span class="z-comment"> The ERC-20 token 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"> _value</span><span class="z-comment"> The number of ERC-20 tokens to transfer </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getERC20</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></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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _erc20Contract</span><span>,</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 class="giallo-l"><span> )</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></span></code></pre><h4 id="tokenfallback">tokenFallback</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> A token receives ERC-20 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"> _from</span><span class="z-comment"> The prior owner of the ERC-20 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"> _value</span><span class="z-comment"> The number of ERC-20 tokens received</span></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"> Up to the first 32 bytes contains an integer which is the receiving tokenId. </span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> tokenFallback</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"> _value</span><span>,</span><span class="z-support"> bytes</span><span class="z-variable z-parameter z-function"> _data</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span><span> </span></span></code></pre> <p>This function comes from the <code>ERC-223</code> which is an extension of the ERC-20 standard. This function is called on the receiving contract from the sending contract when ERC-20 tokens are transferred. This function is how the ERC-20 top-down composable contract gets notified that one of its tokens received ERC-20 tokens. Which token received ERC-20 tokens is specified in the <code>_data</code> parameter.</p> <h4 id="balanceoferc20"><code>balanceOfERC20</code></h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Look up the balance of ERC-20 tokens for a specific token and ERC-20 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"> _tokenId</span><span class="z-comment"> The token that owns the ERC-20 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"> _erc20Contract</span><span class="z-comment"> The ERC-20 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"> The</span><span class="z-comment"> number of ERC-20 tokens owned by a token from an ERC-20 contract</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> balanceOfERC20</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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _erc20Contract</span></span> <span class="giallo-l"><span>)</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"> view</span><span> </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></code></pre> <p>Gets the balance of ERC-20 tokens owned by a token from a specific ERC-20 contract.</p> <h4 id="transfererc20"><code>transferERC20</code></h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer ERC-20 tokens 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"> _tokenId</span><span class="z-comment"> The token to transfer from</span></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 address to send the ERC-20 tokens 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"> _erc20Contract</span><span class="z-comment"> The ERC-20 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"> _value</span><span class="z-comment"> The number of ERC-20 tokens to transfer</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> transferERC20</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></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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _erc20Contract</span><span>,</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 class="giallo-l"><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>This is used to transfer ERC-20 tokens from a token to an address. This function calls <code>ERC20(_erc20Contract).transfer(_to, _value)</code>;</p> <p>This function must authenticate <code>msg.sender</code>.</p> <h4 id="transfererc223"><code>transferERC223</code></h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer ERC-20 tokens to address or ERC-20 top-down composable</span></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 transfer from</span></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 address to send the ERC-20 tokens 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"> _erc223Contract</span><span class="z-comment"> The `ERC-223` token 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"> _value</span><span class="z-comment"> The number of ERC-20 tokens 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"> _data</span><span class="z-comment"> Additional data with no specified format, can be used to specify tokenId to transfer to</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferERC223</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></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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _erc223Contract</span><span>,</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></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> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>This function is from the <code>ERC-223</code>. It is used to transfer ERC-20 tokens from a token to an address or to another token by putting an integer token value in the <code>_data</code> argument.</p> <p>This function must authenticate <code>msg.sender</code>.</p> <h4 id="geterc20"><code>getERC20</code></h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get ERC-20 tokens from ERC-20 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"> _from</span><span class="z-comment"> The current owner address of the ERC-20 tokens that are being transferred.</span></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 transfer the ERC-20 tokens 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"> _erc20Contract</span><span class="z-comment"> The ERC-20 token 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"> _value</span><span class="z-comment"> The number of ERC-20 tokens to transfer </span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getERC20</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></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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _erc20Contract</span><span>,</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 class="giallo-l"><span>)</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>This function is used to transfer ERC-20 tokens to an ERC-20 top-down composable when an ERC-20 contract does not have a <code>transferERC223(uint256 _tokenId, address _to, address _erc223Contract, uint256 _value, bytes _data)</code> function.</p> <p>Before this function can be used the ERC-20 top-down composable contract address must be approved in the ERC-20 contract to transfer the ERC-20 tokens.</p> <p>This function must authenticate that <code>msg.sender</code> equals <code>_from</code> or has been approved in the ERC-20 contract.</p> <h4 id="erc-20-top-down-composable-enumeration">ERC-20 Top-Down Composable Enumeration</h4> <p>Optional interface for top-down composable enumeration:</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 ERC-165 identifier for this interface is 0xc5fd96cd</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC998ERC20TopDownEnumerable</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"> Get the number of ERC-20 contracts that token owns ERC-20 tokens from</span></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 owns ERC-20 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 number of ERC-20 contracts</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalERC20Contracts</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"> Get an ERC-20 contract that token owns ERC-20 tokens from by 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"> _tokenId</span><span class="z-comment"> The token that owns ERC-20 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"> _index</span><span class="z-comment"> The index position of the ERC-20 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"> address</span><span class="z-comment"> The ERC-20 contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> erc20ContractByIndex</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></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _index</span></span> <span class="giallo-l"><span> )</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"> view</span><span> </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></code></pre><h3 id="erc-721-bottom-up-composable">ERC-721 Bottom-Up Composable</h3> <p>ERC-721 bottom-up composables are ERC-721 tokens that attach themselves to other ERC-721 tokens.</p> <p>ERC-721 bottom-up composable contracts store the owning address of a token and the parent tokenId if any.</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"> `ERC998ERC721` Bottom-Up Composable Non-Fungible 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/./00998.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 0xa1b23002</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC998ERC721BottomUp</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 token is transferred to an ERC-721 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"> _toContract</span><span class="z-comment"> The contract the token is transferred 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"> _toTokenId</span><span class="z-comment"> The token the token is transferred 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"> _tokenId</span><span class="z-comment"> The token that is transferred </span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferToParent</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"> _toContract</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"> _toTokenId</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>;</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 token is transferred from an ERC-721 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"> _fromContract</span><span class="z-comment"> The contract the token is transferred from</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _fromTokenId</span><span class="z-comment"> The token the token is transferred from</span></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 transferred </span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferFromParent</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-storage z-type"> indexed</span><span class="z-variable"> _fromTokenId</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>;</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 root owner of 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"> _tokenId</span><span class="z-comment"> The token to query for a root owner 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"> rootOwner</span><span class="z-comment"> The root owner at the top of tree of tokens and ERC-998 magic value.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> rootOwnerOf</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">bytes32</span><span class="z-variable"> rootOwner</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 owner address and parent token (if there is one) 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"> The tokenId 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"> tokenOwner</span><span class="z-comment"> The owner address 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"> parentTokenId</span><span class="z-comment"> The parent owner of the token and ERC-998 magic value</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"> isParent</span><span class="z-comment"> True if parentTokenId is a valid parent tokenId and false if there is no parent tokenId</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenOwnerOf</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></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"> tokenOwner</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> parentTokenId</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> isParent</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"> @notice</span><span class="z-comment"> Transfer token from owner address to 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"> _from</span><span class="z-comment"> The 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"> _toContract</span><span class="z-comment"> The ERC-721 contract of the receiving 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"> _toToken</span><span class="z-comment"> The receiving 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"> _data</span><span class="z-comment"> Additional data with no specified format</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferToParent</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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _toContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _toTokenId</span><span>,</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></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> <span class="giallo-l"><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 token from a token to an 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"> _fromContract</span><span class="z-comment"> The address of the owning 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"> _fromTokenId</span><span class="z-comment"> The owning 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"> _to</span><span class="z-comment"> The address the token is transferred 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"> _tokenId</span><span class="z-comment"> The token that is transferred</span></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"> function</span><span class="z-entity z-name"> transferFromParent</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _fromContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</span><span>,</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></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></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> <span class="giallo-l"><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 token from a token to another 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"> _fromContract</span><span class="z-comment"> The address of the owning 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"> _fromTokenId</span><span class="z-comment"> The owning 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"> _toContract</span><span class="z-comment"> The ERC-721 contract of the receiving 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"> _toToken</span><span class="z-comment"> The receiving 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"> The token that is transferred</span></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"> function</span><span class="z-entity z-name"> transferAsChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _fromContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _toContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _toTokenId</span><span>,</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></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> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="rootownerof"><code>rootOwnerOf</code></h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the root owner of 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"> _tokenId</span><span class="z-comment"> The token to query for a root owner 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"> rootOwner</span><span class="z-comment"> The root owner at the top of tree of tokens and ERC-998 magic value.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> rootOwnerOf</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"> 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"> rootOwner</span><span>)</span><span>;</span></span></code></pre> <p>This function traverses token owners until the root owner address of <code>_tokenId</code> is found.</p> <p>The first 4 bytes of rootOwner contain the ERC-998 magic value <code>0xcd740db5</code>. The last 20 bytes contain the root owner address.</p> <p>The magic value is returned because this function may be called on contracts when it is unknown if the contracts have a <code>rootOwnerOf</code> function. The magic value is used in such calls to ensure a valid return value is received.</p> <p>If it is unknown whether a contract has the <code>rootOwnerOf</code> function then the first four bytes of the <code>rootOwner</code> return value must be compared to <code>0xcd740db5</code>.</p> <p><code>0xcd740db5</code> is equal to:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-variable z-language">this</span><span>.</span><span>rootOwnerOf</span><span>.</span><span>selector </span><span class="z-keyword">^</span><span class="z-variable z-language"> this</span><span>.</span><span>rootOwnerOfChild</span><span>.</span><span>selector </span><span class="z-keyword">^</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-language">this</span><span>.</span><span>tokenOwnerOf</span><span>.</span><span>selector </span><span class="z-keyword">^</span><span class="z-variable z-language"> this</span><span>.</span><span>ownerOfChild</span><span>.</span><span>selector</span><span>;</span></span></code></pre> <p>Here is an example of a value returned by <code>rootOwnerOf</code>. <code>0xcd740db50000000000000000e5240103e1ff986a2c8ae6b6728ffe0d9a395c59</code></p> <h4 id="tokenownerof">tokenOwnerOf</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the owner address and parent token (if there is one) 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"> The tokenId 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"> tokenOwner</span><span class="z-comment"> The owner address of the token and ERC-998 magic value.</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"> parentTokenId</span><span class="z-comment"> The parent owner 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"> isParent</span><span class="z-comment"> True if parentTokenId is a valid parent tokenId and false if there is no parent tokenId</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> tokenOwnerOf</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></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"> bytes32</span><span class="z-variable"> tokenOwner</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> parentTokenId</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> isParent</span></span> <span class="giallo-l"><span> )</span><span>;</span></span></code></pre> <p>This function is used to get the owning address and parent tokenId of a token if there is one stored in the contract.</p> <p>If <code>isParent</code> is true then <code>tokenOwner</code> is the owning ERC-721 contract address and <code>parentTokenId</code> is a valid parent tokenId. If <code>isParent</code> is false then <code>tokenOwner</code> is a user address and <code>parentTokenId</code> does not contain a valid parent tokenId and must be ignored.</p> <p>The first 4 bytes of <code>tokenOwner</code> contain the ERC-998 magic value <code>0xcd740db5</code>. The last 20 bytes contain the token owner address.</p> <p>The magic value is returned because this function may be called on contracts when it is unknown if the contracts have a <code>tokenOwnerOf</code> function. The magic value is used in such calls to ensure a valid return value is received.</p> <p>If it is unknown whether a contract has the <code>rootOwnerOf</code> function then the first four bytes of the <code>tokenOwner</code> return value must be compared to <code>0xcd740db5</code>.</p> <h4 id="transfertoparent">transferToParent</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer token from owner address to 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"> _from</span><span class="z-comment"> The 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"> _toContract</span><span class="z-comment"> The ERC-721 contract of the receiving 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"> _toToken</span><span class="z-comment"> The receiving 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"> _data</span><span class="z-comment"> Additional data with no specified format</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> transferToParent</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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _toContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _toTokenId</span><span>,</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></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> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>This function is used to transfer a token from an address to a token. <code>msg.sender</code> must be authenticated.</p> <p>This function must check that <code>_toToken</code> exists in <code>_toContract</code> and throw if not.</p> <h4 id="transferfromparent">transferFromParent</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer token from a token to an 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"> _fromContract</span><span class="z-comment"> The address of the owning 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"> _fromTokenId</span><span class="z-comment"> The owning 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"> _to</span><span class="z-comment"> The address the token is transferred 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"> _tokenId</span><span class="z-comment"> The token that is transferred</span></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">function</span><span class="z-entity z-name"> transferFromParent</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _fromContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</span><span>,</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></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></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> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>This function is used to transfer a token from a token to an address. <code>msg.sender</code> must be authenticated.</p> <p>This function must check that <code>_fromContract</code> and <code>_fromTokenId</code> own <code>_tokenId</code> and throw not.</p> <h4 id="transferaschild">transferAsChild</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer a token from a token to another 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"> _fromContract</span><span class="z-comment"> The address of the owning 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"> _fromTokenId</span><span class="z-comment"> The owning 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"> _toContract</span><span class="z-comment"> The ERC-721 contract of the receiving 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"> _toToken</span><span class="z-comment"> The receiving 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"> The token that is transferred</span></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">function</span><span class="z-entity z-name"> transferAsChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _fromContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _toContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _toTokenId</span><span>,</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></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> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>This function is used to transfer a token from a token to another token. <code>msg.sender</code> must be authenticated.</p> <p>This function must check that <code>_toToken</code> exists in <code>_toContract</code> and throw if not.</p> <p>This function must check that <code>_fromContract</code> and <code>_fromTokenId</code> own <code>_tokenId</code> and throw if not.</p> <h4 id="erc-721-bottom-up-composable-enumeration">ERC-721 Bottom-Up Composable Enumeration</h4> <p>Optional interface for bottom-up composable enumeration:</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 ERC-165 identifier for this interface is 0x8318b539</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC998ERC721BottomUpEnumerable</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"> Get the number of ERC-721 tokens owned by parent 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"> _parentContract</span><span class="z-comment"> The contract the parent ERC-721 token is from.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _parentTokenId</span><span class="z-comment"> The parent tokenId that owns tokens</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @return uint256 The number of ERC-721 tokens owned by parent token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalChildTokens</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _parentContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _parentTokenId</span></span> <span class="giallo-l"><span> )</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"> view</span><span> </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 class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get a child token by 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"> _parentContract</span><span class="z-comment"> The contract the parent ERC-721 token is from.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _parentTokenId</span><span class="z-comment"> The parent tokenId that owns 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"> The index position of the child 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"> The child tokenId owned by the parent token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> childTokenByIndex</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _parentContract</span><span>,</span><span> </span></span> <span class="giallo-l"><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 class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _index</span></span> <span class="giallo-l"><span> )</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"> view</span><span> </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><h3 id="erc-20-bottom-up-composable">ERC-20 Bottom-Up Composable</h3> <p>ERC-20 bottom-up composables are ERC-20 tokens that attach themselves to ERC-721 tokens, or are owned by a user address like standard ERC-20 tokens.</p> <p>When owned by an ERC-721 token, ERC-20 bottom-up composable contracts store the owning address of a token and the parent tokenId. ERC-20 bottom-up composables add several methods to the ERC-20 and <code>ERC-223</code> interfaces allowing for querying the balance of parent tokens, and transferring tokens to, from, and between parent tokens.</p> <p>This functionality can be implemented by adding one additional mapping to track balances of tokens, in addition to the standard mapping for tracking user address balances.</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"> This mapping tracks standard ERC20/`ERC-223` ownership, where an address owns</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> a particular amount of tokens.</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> userBalances</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 additional mapping tracks ERC-998 ownership, where an ERC-721 token owns</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> a particular amount of tokens. This tracks contractAddres =&gt; tokenId =&gt; 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-storage z-type"> mapping</span><span>(</span><span class="z-support">uint</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint</span><span>)</span><span>)</span><span> nftBalances</span><span>;</span></span></code></pre> <p>The complete interface is 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"> `ERC998ERC20` Bottom-Up Composable Fungible 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/./00998.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 0xffafa991</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC998ERC20BottomUp</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 token is transferred to an ERC-721 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"> _toContract</span><span class="z-comment"> The contract the token is transferred 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"> _toTokenId</span><span class="z-comment"> The token the token is transferred 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"> _amount</span><span class="z-comment"> The amount of tokens transferred</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferToParent</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"> _toContract</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"> _toTokenId</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 class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a token is transferred from an ERC-721 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"> _fromContract</span><span class="z-comment"> The contract the token is transferred from</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _fromTokenId</span><span class="z-comment"> The token the token is transferred from</span></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"> The amount of tokens transferred</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferFromParent</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-storage z-type"> indexed</span><span class="z-variable"> _fromTokenId</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Get the balance of a non-fungible parent 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"> _tokenContract</span><span class="z-comment"> The contract tracking the parent 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"> The ID of the parent 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"> The balance of the token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOfToken</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _tokenContract</span><span>,</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-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>;</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"> Transfer tokens from owner address to 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"> _from</span><span class="z-comment"> The 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"> _toContract</span><span class="z-comment"> The ERC-721 contract of the receiving 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"> _toToken</span><span class="z-comment"> The receiving 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"> The amount of tokens to transfer</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferToParent</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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _toContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _toTokenId</span><span>,</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> <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"> Transfer token from a token to an 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"> _fromContract</span><span class="z-comment"> The address of the owning 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"> _fromTokenId</span><span class="z-comment"> The owning 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"> _to</span><span class="z-comment"> The address the token is transferred 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"> _amount</span><span class="z-comment"> The amount of tokens to transfer</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferFromParent</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _fromContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</span><span>,</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></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> <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"> Transfer token from a token to an address, using `ERC-223` semantics</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _fromContract</span><span class="z-comment"> The address of the owning 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"> _fromTokenId</span><span class="z-comment"> The owning 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"> _to</span><span class="z-comment"> The address the token is transferred 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"> _amount</span><span class="z-comment"> The amount of tokens 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"> _data</span><span class="z-comment"> Additional data with no specified format, can be used to specify the sender tokenId</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferFromParentERC223</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _fromContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</span><span>,</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></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></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> <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"> Transfer a token from a token to another 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"> _fromContract</span><span class="z-comment"> The address of the owning 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"> _fromTokenId</span><span class="z-comment"> The owning 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"> _toContract</span><span class="z-comment"> The ERC-721 contract of the receiving 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"> _toToken</span><span class="z-comment"> The receiving 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"> The amount tokens to transfer</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferAsChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _fromContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _toContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _toTokenId</span><span>,</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> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="balanceoftoken">balanceOfToken</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the balance of a non-fungible parent 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"> _tokenContract</span><span class="z-comment"> The contract tracking the parent 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"> The ID of the parent 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"> The balance of the token</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> balanceOfToken</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _tokenContract</span><span>,</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-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>;</span></span></code></pre> <p>This function returns the balance of a non-fungible token. It mirrors the standard ERC-20 method <code>balanceOf</code>, but accepts the address of the parent token's contract, and the parent token's ID. This method behaves identically to <code>balanceOf</code>, but checks for ownership by ERC-721 tokens rather than user addresses.</p> <h4 id="transfertoparent-1"><code>transferToParent</code></h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer tokens from owner address to 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"> _from</span><span class="z-comment"> The 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"> _toContract</span><span class="z-comment"> The ERC-721 contract of the receiving 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"> _toToken</span><span class="z-comment"> The receiving 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"> The amount of tokens to transfer</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> transferToParent</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></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _toContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _toTokenId</span><span>,</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> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>This function transfers an amount of tokens from a user address to an ERC-721 token. This function MUST ensure that the recipient contract implements ERC-721 using the ERC-165 <code>supportsInterface</code> function. This function SHOULD ensure that the recipient token actually exists, by calling <code>ownerOf</code> on the recipient token's contract, and ensuring it neither throws nor returns the zero address. This function MUST emit the <code>TransferToParent</code> event upon a successful transfer (in addition to the standard ERC-20 <code>Transfer</code> event!). This function MUST throw if the <code>_from</code> account balance does not have enough tokens to spend.</p> <h4 id="transferfromparent-1"><code>transferFromParent</code></h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer token from a token to an 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"> _fromContract</span><span class="z-comment"> The address of the owning 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"> _fromTokenId</span><span class="z-comment"> The owning 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"> _to</span><span class="z-comment"> The address the token is transferred 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"> _amount</span><span class="z-comment"> The amount of tokens to transfer</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> transferFromParent</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _fromContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</span><span>,</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></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> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>This function transfers an amount of tokens from an ERC-721 token to an address. This function MUST emit the <code>TransferFromParent</code> event upon a successful transfer (in addition to the standard ERC-20 <code>Transfer</code> event!). This function MUST throw if the balance of the sender ERC-721 token is less than the <code>_amount</code> specified. This function MUST verify that the <code>msg.sender</code> owns the sender ERC-721 token, and MUST throw otherwise.</p> <h4 id="transferfromparenterc223"><code>transferFromParentERC223</code></h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer token from a token to an address, using `ERC-223` semantics</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _fromContract</span><span class="z-comment"> The address of the owning 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"> _fromTokenId</span><span class="z-comment"> The owning 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"> _to</span><span class="z-comment"> The address the token is transferred 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"> _amount</span><span class="z-comment"> The amount of tokens 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"> _data</span><span class="z-comment"> Additional data with no specified format, can be used to specify the sender tokenId</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> transferFromParentERC223</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _fromContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</span><span>,</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></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></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> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>This function transfers an amount of tokens from an ERC-721 token to an address. This function has identical requirements to <code>transferFromParent</code>, except that it additionally MUST invoke <code>tokenFallback</code> on the recipient address, if the address is a contract, as specified by <code>ERC-223</code>.</p> <h4 id="transferaschild-1">transferAsChild 1</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer a token from a token to another 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"> _fromContract</span><span class="z-comment"> The address of the owning 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"> _fromTokenId</span><span class="z-comment"> The owning 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"> _toContract</span><span class="z-comment"> The ERC-721 contract of the receiving 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"> _toToken</span><span class="z-comment"> The receiving 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"> The amount tokens to transfer</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> transferAsChild</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _fromContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _fromTokenId</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _toContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _toTokenId</span><span>,</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> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>This function transfers an amount of tokens from an ERC-721 token to another ERC-721 token. This function MUST emit BOTH the <code>TransferFromParent</code> and <code>TransferToParent</code> events (in addition to the standard ERC-20 <code>Transfer</code> event!). This function MUST throw if the balance of the sender ERC-721 token is less than the <code>_amount</code> specified. This function MUST verify that the <code>msg.sender</code> owns the sender ERC-721 token, and MUST throw otherwise. This function MUST ensure that the recipient contract implements ERC-721 using the ERC-165 <code>supportsInterface</code> function. This function SHOULD ensure that the recipient token actually exists, by calling <code>ownerOf</code> on the recipient token's contract, and ensuring it neither throws nor returns the zero address.</p> <h3 id="notes">Notes</h3> <p>For backwards-compatibility, implementations MUST emit the standard ERC-20 <code>Transfer</code> event when a transfer occurs, regardless of whether the sender and recipient are addresses or ERC-721 tokens. In the case that either sender or recipient are tokens, the corresponding parameter in the <code>Transfer</code> event SHOULD be the contract address of the token.</p> <p>Implementations MUST implement all ERC-20 and <code>ERC-223</code> functions in addition to the functions specified in this interface.</p> <h2 id="rationale">Rationale</h2> <p>Two different kinds of composable (top-down and bottom-up) exist to handle different use cases. A regular ERC-721 token cannot own a top-down composable, but it can own a bottom-up composable. A bottom-up composable cannot own a regular ERC-721 but a top-down composable can own a regular ERC-721 token. Having multiple kinds of composables enable different token ownership possibilities.</p> <h3 id="which-kind-of-composable-to-use">Which Kind of Composable To Use?</h3> <p>If you want to transfer regular ERC-721 tokens to non-fungible tokens, then use top-down composables.</p> <p>If you want to transfer non-fungible tokens to regular ERC-721 tokens then use bottom-up composables.</p> <h3 id="explicit-transfer-parameters">Explicit Transfer Parameters</h3> <p>Every ERC-998 transfer function includes explicit parameters to specify the prior owner and the new owner of a token. Explicitly providing <strong>from</strong> and <strong>to</strong> is done intentionally to avoid situations where tokens are transferred in unintended ways.</p> <p>Here is an example of what could occur if <strong>from</strong> was not explicitly provided in transfer functions:</p> <blockquote> <p>An exchange contract is an approved operator in a specific composable contract for user A, user B and user C.</p> <p>User A transfers token 1 to user B. At the same time the exchange contract transfers token 1 to user C (with the implicit intention to transfer from user A). User B gets token 1 for a minute before it gets incorrectly transferred to user C. The second transfer should have failed but it didn't because no explicit <strong>from</strong> was provided to ensure that token 1 came from user A.</p> </blockquote> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Composables are designed to work with ERC-721, <code>ERC-223</code> and ERC-20 tokens.</p> <p>Some older ERC-721 contracts do not have a <code>safeTransferFrom</code> function. The <code>getChild</code> function can still be used to transfer a token to an ERC-721 top-down composable.</p> <p>If an ERC-20 contract does not have the <code>ERC-223</code> function <code>transfer(address _to, uint _value, bytes _data)</code> then the <code>getERC20</code> function can still be used to transfer ERC-20 tokens to an ERC-20 top-down composable.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>An implementation can be found here: <code>https://github.com/mattlockyer/composables-998</code></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> 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-30T00:00:00+00:00 2026-02-11T14:49:27+00:00 Fabian Vogelstellerhttps://github.com/frozeman Ryan Ghodshttps://github.com/ryanio Victor Maiahttps://github.com/MaiaVictor Marc Garreauhttps://github.com/wolovim Erik Markshttps://github.com/rekmarks https://wg-eips.ritovision.com/1193/ <h2 id="summary">Summary</h2> <p>A JavaScript Ethereum Provider API for consistency across clients and applications.</p> <h2 id="abstract">Abstract</h2> <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> <p>Historically, Provider implementations have exhibited conflicting interfaces and behaviors between wallets. This EIP formalizes an Ethereum Provider API to promote wallet interoperability. The API is designed to be minimal, event-driven, and agnostic of transport and RPC protocols. Its functionality is easily extended by defining new RPC methods and <code>message</code> event types.</p> <p>Historically, Providers have been made available as <code>window.ethereum</code> in web browsers, but this convention is not part of the specification.</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> <blockquote> <p>Comments like this are non-normative.</p> </blockquote> <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>Client <ul> <li>An endpoint that receives Remote Procedure Call (RPC) requests from the Provider, and returns their results.</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>Remote Procedure Call (RPC) <ul> <li>A Remote Procedure Call (RPC), is any request submitted to a Provider for some procedure that is to be processed by a Provider, its Wallet, or its Client.</li> </ul> </li> </ul> <h3 id="connectivity">Connectivity</h3> <p>The Provider is said to be "connected" when it can service RPC requests to at least one chain.</p> <p>The Provider is said to be "disconnected" when it cannot service RPC requests to any chain at all.</p> <blockquote> <p>To service an RPC request, the Provider must successfully submit the request to the remote location, and receive a response. In other words, if the Provider is unable to communicate with its Client, for example due to network issues, the Provider is disconnected.</p> </blockquote> <h3 id="api">API</h3> <blockquote> <p>The Provider API is specified using TypeScript. The authors encourage implementers to declare their own types and interfaces, using the ones in this section as a basis.</p> <p>For consumer-facing API documentation, see <a href="https://wg-eips.ritovision.com/1193/#appendix-i-consumer-facing-api-documentation">Appendix I</a></p> </blockquote> <p>The Provider <strong>MUST</strong> implement and expose the API defined in this section. All API entities <strong>MUST</strong> adhere to the types and interfaces defined in this section.</p> <h4 id="request">request</h4> <blockquote> <p>The <code>request</code> method is intended as a transport- and protocol-agnostic wrapper function for Remote Procedure Calls (RPCs).</p> </blockquote> <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"> RequestArguments</span><span> {</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> method</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"> params</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-storage"> readonly</span><span class="z-support"> unknown</span><span>[</span><span>]</span><span class="z-keyword"> |</span><span class="z-support"> object</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">request</span><span>(</span><span class="z-variable z-other">args</span><span>: </span><span class="z-variable z-other">RequestArguments</span><span>)</span><span>: </span><span class="z-support">Promise</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">unknown</span><span class="z-keyword">&gt;</span><span>;</span></span></code></pre> <p>The Provider <strong>MUST</strong> identify the requested RPC method by the value of <code>RequestArguments.method</code>.</p> <p>If the requested RPC method takes any parameters, the Provider <strong>MUST</strong> accept them as the value of <code>RequestArguments.params</code>.</p> <p>RPC requests <strong>MUST</strong> be handled such that the returned Promise either resolves with a value per the requested RPC method's specification, or rejects with an error.</p> <p>If resolved, the Promise <strong>MUST</strong> resolve with a result per the RPC method's specification. The Promise <strong>MUST NOT</strong> resolve with any RPC protocol-specific response objects, unless the RPC method's return type is so defined.</p> <p>If the returned Promise rejects, it <strong>MUST</strong> reject with a <code>ProviderRpcError</code> as specified in the <a href="https://wg-eips.ritovision.com/1193/#rpc-errors">RPC Errors</a> section below.</p> <p>The returned Promise <strong>MUST</strong> reject if any of the following conditions are met:</p> <ul> <li>An error is returned for the RPC request. <ul> <li>If the returned error is compatible with the <code>ProviderRpcError</code> interface, the Promise <strong>MAY</strong> reject with that error directly.</li> </ul> </li> <li>The Provider encounters an error or fails to process the request for any reason.</li> </ul> <blockquote> <p>If the Provider implements any kind of authorization logic, the authors recommend rejecting with a <code>4100</code> error in case of authorization failures.</p> </blockquote> <p>The returned Promise <strong>SHOULD</strong> reject if any of the following conditions are met:</p> <ul> <li>The Provider is disconnected. <ul> <li>If rejecting for this reason, the Promise rejection error <code>code</code> <strong>MUST</strong> be <code>4900</code>.</li> </ul> </li> <li>The RPC request is directed at a specific chain, and the Provider is not connected to that chain, but is connected to at least one other chain. <ul> <li>If rejecting for this reason, the Promise rejection error <code>code</code> <strong>MUST</strong> be <code>4901</code>.</li> </ul> </li> </ul> <p>See the section <a href="https://wg-eips.ritovision.com/1193/#connectivity">Connectivity</a> for the definitions of "connected" and "disconnected".</p> <h3 id="supported-rpc-methods">Supported RPC Methods</h3> <p>A "supported RPC method" is any RPC method that may be called via the Provider.</p> <p>All supported RPC methods <strong>MUST</strong> be identified by unique strings.</p> <p>Providers <strong>MAY</strong> support whatever RPC methods required to fulfill their purpose, standardized or otherwise.</p> <p>If an RPC method defined in a finalized EIP is not supported, it <strong>SHOULD</strong> be rejected with a <code>4200</code> error per the <a href="https://wg-eips.ritovision.com/1193/#provider-errors">Provider Errors</a> section below, or an appropriate error per the RPC method's specification.</p> <h4 id="rpc-errors">RPC Errors</h4> <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"> ProviderRpcError</span><span class="z-storage"> extends</span><span class="z-entity"> Error</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> code</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> data</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>}</span></span></code></pre> <ul> <li><code>message</code> <ul> <li><strong>MUST</strong> be a human-readable string</li> <li><strong>SHOULD</strong> adhere to the specifications in the <a href="https://wg-eips.ritovision.com/1193/#error-standards">Error Standards</a> section below</li> </ul> </li> <li><code>code</code> <ul> <li><strong>MUST</strong> be an integer number</li> <li><strong>SHOULD</strong> adhere to the specifications in the <a href="https://wg-eips.ritovision.com/1193/#error-standards">Error Standards</a> section below</li> </ul> </li> <li><code>data</code> <ul> <li><strong>SHOULD</strong> contain any other useful information about the error</li> </ul> </li> </ul> <h5 id="error-standards">Error Standards</h5> <p><code>ProviderRpcError</code> codes and messages <strong>SHOULD</strong> follow these conventions, in order of priority:</p> <ol> <li> <p>The errors in the <a href="https://wg-eips.ritovision.com/1193/#provider-errors">Provider Errors</a> section below</p> </li> <li> <p>Any errors mandated by the erroring RPC method's specification</p> </li> <li> <p>The <a rel="external" href="https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent#Status_codes"><code>CloseEvent</code> status codes</a></p> </li> </ol> <h4 id="provider-errors">Provider Errors</h4> <table><thead><tr><th>Status code</th><th>Name</th><th>Description</th></tr></thead><tbody> <tr><td>4001</td><td>User Rejected Request</td><td>The user rejected the request.</td></tr> <tr><td>4100</td><td>Unauthorized</td><td>The requested method and/or account has not been authorized by the user.</td></tr> <tr><td>4200</td><td>Unsupported Method</td><td>The Provider does not support the requested method.</td></tr> <tr><td>4900</td><td>Disconnected</td><td>The Provider is disconnected from all chains.</td></tr> <tr><td>4901</td><td>Chain Disconnected</td><td>The Provider is not connected to the requested chain.</td></tr> </tbody></table> <blockquote> <p><code>4900</code> is intended to indicate that the Provider is disconnected from all chains, while <code>4901</code> is intended to indicate that the Provider is disconnected from a specific chain only. In other words, <code>4901</code> implies that the Provider is connected to other chains, just not the requested one.</p> </blockquote> <h3 id="events">Events</h3> <p>The Provider <strong>MUST</strong> implement the following event handling methods:</p> <ul> <li><code>on</code></li> <li><code>removeListener</code></li> </ul> <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> <blockquote> <p>To satisfy these requirements, Provider implementers should consider simply extending the Node.js <code>EventEmitter</code> class and bundling it for the target environment.</p> </blockquote> <h4 id="message">message</h4> <blockquote> <p>The <code>message</code> event is intended for arbitrary notifications not covered by other events.</p> </blockquote> <p>When emitted, the <code>message</code> event <strong>MUST</strong> be emitted with an object argument of the following form:</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"> ProviderMessage</span><span> {</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> type</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"> data</span><span class="z-keyword">:</span><span class="z-support"> unknown</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="subscriptions">Subscriptions</h5> <p>If the Provider supports Ethereum RPC subscriptions, e.g. <a rel="external" href="https://geth.ethereum.org/docs/rpc/pubsub"><code>eth_subscribe</code></a>, the Provider <strong>MUST</strong> emit the <code>message</code> event when it receives a subscription notification.</p> <p>If the Provider receives a subscription message from e.g. an <code>eth_subscribe</code> subscription, the Provider <strong>MUST</strong> emit a <code>message</code> event with a <code>ProviderMessage</code> object of the following form:</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"> EthSubscription</span><span class="z-storage"> extends</span><span class="z-entity"> ProviderMessage</span><span> {</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> type</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_subscription</span><span class="z-punctuation z-definition z-string">&#39;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> data</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> subscription</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"> result</span><span class="z-keyword">:</span><span class="z-support"> unknown</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="connect">connect</h4> <p>See the section <a href="https://wg-eips.ritovision.com/1193/#connectivity">Connectivity</a> for the definition of "connected".</p> <p>If the Provider becomes connected, the Provider <strong>MUST</strong> emit the event named <code>connect</code>.</p> <p>This includes when:</p> <ul> <li>The Provider first connects to a chain after initialization.</li> <li>The Provider connects to a chain after the <code>disconnect</code> event was emitted.</li> </ul> <p>This event <strong>MUST</strong> be emitted with an object of the following form:</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"> ProviderConnectInfo</span><span> {</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><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><code>chainId</code> <strong>MUST</strong> specify the integer ID of the connected chain as a hexadecimal string, per the <a href="https://wg-eips.ritovision.com/695/"><code>eth_chainId</code></a> Ethereum RPC method.</p> <h4 id="disconnect">disconnect</h4> <p>See the section <a href="https://wg-eips.ritovision.com/1193/#connectivity">Connectivity</a> for the definition of "disconnected".</p> <p>If the Provider becomes disconnected from all chains, the Provider <strong>MUST</strong> emit the event named <code>disconnect</code> with value <code>error: ProviderRpcError</code>, per the interfaced defined in the <a href="https://wg-eips.ritovision.com/1193/#rpc-errors">RPC Errors</a> section. The value of the error's <code>code</code> property <strong>MUST</strong> follow the <a rel="external" href="https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent#Status_codes">status codes for <code>CloseEvent</code></a>.</p> <h4 id="chainchanged">chainChanged</h4> <p>If the chain the Provider is connected to changes, the Provider <strong>MUST</strong> emit the event named <code>chainChanged</code> with value <code>chainId: string</code>, specifying the integer ID of the new chain as a hexadecimal string, per the <a href="https://wg-eips.ritovision.com/695/"><code>eth_chainId</code></a> Ethereum RPC method.</p> <h4 id="accountschanged">accountsChanged</h4> <p>If the accounts available to the Provider change, the Provider <strong>MUST</strong> emit the event named <code>accountsChanged</code> with value <code>accounts: string[]</code>, containing the account addresses per the <code>eth_accounts</code> Ethereum RPC method.</p> <p>The "accounts available to the Provider" change when the return value of <code>eth_accounts</code> changes.</p> <h2 id="rationale">Rationale</h2> <p>The purpose of a Provider is to <em>provide</em> a consumer with access to Ethereum. In general, a Provider must enable an Ethereum web application to do two things:</p> <ul> <li>Make Ethereum RPC requests</li> <li>Respond to state changes in the Provider's Ethereum chain, Client, and Wallet</li> </ul> <p>The Provider API specification consists of a single method and five events. The <code>request</code> method and the <code>message</code> event alone, are sufficient to implement a complete Provider. They are designed to make arbitrary RPC requests and communicate arbitrary messages, respectively.</p> <p>The remaining four events can be separated into two categories:</p> <ul> <li>Changes to the Provider's ability to make RPC requests <ul> <li><code>connect</code></li> <li><code>disconnect</code></li> </ul> </li> <li>Common Client and/or Wallet state changes that any non-trivial application must handle <ul> <li><code>chainChanged</code></li> <li><code>accountsChanged</code></li> </ul> </li> </ul> <p>These events are included due to the widespread production usage of related patterns, at the time of writing.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Many Providers adopted a draft version of this specification before it was finalized. The current API is designed to be a strict superset of the legacy version, and this specification is in that sense fully backwards compatible. See <a href="https://wg-eips.ritovision.com/1193/#appendix-iii-legacy-provider-api">Appendix III</a> for the legacy API.</p> <p>Providers that only implement this specification will not be compatible with Ethereum web applications that target the legacy API.</p> <h2 id="implementations">Implementations</h2> <p>At the time of writing, the following projects have working implementations:</p> <ul> <li><a rel="external" href="https://github.com/nomiclabs/buidler/pull/608">buidler.dev</a></li> <li><a rel="external" href="https://github.com/ethers-io/ethers.js/blob/56af4413b1dd1787db68985e0b612b63d86fdf7c/packages/providers/src.ts/web3-provider.ts">ethers.js</a></li> <li><a rel="external" href="https://www.npmjs.com/package/eth-provider">eth-provider</a></li> <li><a rel="external" href="https://github.com/MetaMask/inpage-provider">MetaMask</a></li> <li><a rel="external" href="https://github.com/WalletConnect/walletconnect-monorepo/blob/d33fd2070d7a67f74de50fd10ca4217f4e2f22f3/packages/providers/web3-provider/README.md">WalletConnect</a></li> <li><a rel="external" href="https://web3js.readthedocs.io/">web3.js</a></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>The Provider is intended to pass messages between an Ethereum Client and an Ethereum application. It is <em>not</em> responsible for private key or account management; it merely processes RPC messages and emits events. Consequently, account security and user privacy need to be implemented in middlewares between the Provider and its Ethereum Client. In practice, we call these middleware applications "Wallets," and they usually manage the user's private keys and accounts. The Provider can be thought of as an extension of the Wallet, exposed in an untrusted environment, under the control of some third party (e.g. a website).</p> <h3 id="handling-adversarial-behavior">Handling Adversarial Behavior</h3> <p>Since it is a JavaScript object, consumers can generally perform arbitrary operations on the Provider, and all its properties can be read or overwritten. Therefore, it is best to treat the Provider object as though it is controlled by an adversary. It is paramount that the Provider implementer protects the user, Wallet, and Client by ensuring that:</p> <ul> <li>The Provider does not contain any private user data.</li> <li>The Provider and Wallet programs are isolated from each other.</li> <li>The Wallet and/or Client rate-limit requests from the Provider.</li> <li>The Wallet and/or Client validate all data sent from the Provider.</li> </ul> <h3 id="chain-changes">Chain Changes</h3> <p>Since all Ethereum operations are directed at a particular chain, it's important that the Provider accurately reflects the Client's configured chain, per the <code>eth_chainId</code> Ethereum RPC method (see <a href="https://wg-eips.ritovision.com/695/">EIP-695</a>).</p> <p>This includes ensuring that <code>eth_chainId</code> has the correct return value, and that the <code>chainChanged</code> event is emitted whenever that value changes.</p> <h3 id="user-account-exposure-and-account-changes">User Account Exposure and Account Changes</h3> <p>Many Ethereum write operations (e.g. <code>eth_sendTransaction</code>) require a user account to be specified. Provider consumers access these accounts via the <code>eth_accounts</code> RPC method, and by listening for the <code>accountsChanged</code> event.</p> <p>As with <code>eth_chainId</code>, it is critical that <code>eth_accounts</code> has the correct return value, and that the <code>accountsChanged</code> event is emitted whenever that value changes.</p> <p>The return value of <code>eth_accounts</code> is ultimately controlled by the Wallet or Client. In order to protect user privacy, the authors recommend not exposing any accounts by default. Instead, Providers should support RPC methods for explicitly requesting account access, such as <code>eth_requestAccounts</code> (see <a href="https://wg-eips.ritovision.com/1102/">EIP-1102</a>) or <code>wallet_requestPermissions</code> (see <a href="https://wg-eips.ritovision.com/2255/">EIP-2255</a>).</p> <h2 id="references">References</h2> <ul> <li><a rel="external" href="https://github.com/ethereum/interfaces/issues/16">Initial discussion in <code>ethereum/interfaces</code></a></li> <li><a rel="external" href="https://ethereum-magicians.org/t/eip-1193-ethereum-provider-javascript-api/640">Deprecated Ethereum Magicians thread</a></li> <li><a rel="external" href="https://github.com/ethereum/EIPs/issues/2319">Continuing discussion</a></li> <li>Related EIPs <ul> <li><a href="https://wg-eips.ritovision.com/1102/">EIP-1102: Opt-in Account Exposure</a></li> <li><a href="https://wg-eips.ritovision.com/1474/">EIP-1474: Remote Procedure Call Specification</a></li> <li><a href="https://wg-eips.ritovision.com/1767/">EIP-1767: GraphQL Interface to Ethereum Node Data</a></li> <li><a href="https://wg-eips.ritovision.com/2255/">EIP-2255: Wallet Permissions</a></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> <h2 id="appendix-i-consumer-facing-api-documentation">Appendix I: Consumer-Facing API Documentation</h2> <h3 id="request-1">request</h3> <p>Makes an Ethereum RPC method call.</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"> RequestArguments</span><span> {</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> method</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"> params</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-storage"> readonly</span><span class="z-support"> unknown</span><span>[</span><span>]</span><span class="z-keyword"> |</span><span class="z-support"> object</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">request</span><span>(</span><span class="z-variable z-other">args</span><span>: </span><span class="z-variable z-other">RequestArguments</span><span>)</span><span>: </span><span class="z-support">Promise</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">unknown</span><span class="z-keyword">&gt;</span><span>;</span></span></code></pre> <p>The returned Promise resolves with the method's result or rejects with a <a href="https://wg-eips.ritovision.com/1193/#errors"><code>ProviderRpcError</code></a>. For example:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">Provider</span><span>.</span><span class="z-entity z-name">request</span><span>(</span><span>{</span><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_accounts</span><span class="z-punctuation z-definition z-string">&#39;</span><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">accounts</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span class="z-variable z-other"> console</span><span>.</span><span class="z-entity z-name">log</span><span>(</span><span class="z-variable z-other">accounts</span><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 class="z-variable z-other"> console</span><span>.</span><span class="z-entity z-name">error</span><span>(</span><span class="z-variable z-other">error</span><span>)</span><span>)</span><span>;</span></span></code></pre> <p>Consult each Ethereum RPC method's documentation for its <code>params</code> and return type. You can find a list of common methods <a href="https://wg-eips.ritovision.com/1474/">here</a>.</p> <h4 id="rpc-protocols">RPC Protocols</h4> <p>Multiple RPC protocols may be available. For examples, see:</p> <ul> <li><a href="https://wg-eips.ritovision.com/1474/">EIP-1474</a>, the Ethereum JSON-RPC API</li> <li><a href="https://wg-eips.ritovision.com/1767/">EIP-1767</a>, the Ethereum GraphQL schema</li> </ul> <h3 id="events-1">Events</h3> <p>Events follow the conventions of the Node.js <a rel="external" href="https://nodejs.org/api/events.html"><code>EventEmitter</code> API</a>.</p> <h4 id="connect-1">connect</h4> <p>The Provider emits <code>connect</code> when it:</p> <ul> <li>first connects to a chain after being initialized.</li> <li>first connects to a chain, after the <code>disconnect</code> event was emitted.</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"> ProviderConnectInfo</span><span> {</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><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> <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">connect</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">connectInfo</span><span class="z-keyword">:</span><span class="z-entity z-name"> ProviderConnectInfo</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>The event emits an object with a hexadecimal string <code>chainId</code> per the <code>eth_chainId</code> Ethereum RPC method, and other properties as determined by the Provider.</p> <h4 id="disconnect-1">disconnect</h4> <p>The Provider emits <code>disconnect</code> when it becomes disconnected from all chains.</p> <pre class="giallo z-code"><code data-lang="typescript"><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">disconnect</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">error</span><span class="z-keyword">:</span><span class="z-entity z-name"> ProviderRpcError</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 a <a href="https://wg-eips.ritovision.com/1193/#errors"><code>ProviderRpcError</code></a>. The error <code>code</code> follows the table of <a rel="external" href="https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent#Status_codes"><code>CloseEvent</code> status codes</a>.</p> <h4 id="chainchanged-1">chainChanged</h4> <p>The Provider emits <code>chainChanged</code> when connecting to a new chain.</p> <pre class="giallo z-code"><code data-lang="typescript"><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">chainChanged</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">chainId</span><span class="z-keyword">:</span><span class="z-support"> string</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>The event emits a hexadecimal string <code>chainId</code> per the <code>eth_chainId</code> Ethereum RPC method.</p> <h4 id="accountschanged-1">accountsChanged</h4> <p>The Provider emits <code>accountsChanged</code> if the accounts returned from the Provider (<code>eth_accounts</code>) change.</p> <pre class="giallo z-code"><code data-lang="typescript"><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">accountsChanged</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">accounts</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>[</span><span>]</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>The event emits with <code>accounts</code>, an array of account addresses, per the <code>eth_accounts</code> Ethereum RPC method.</p> <h4 id="message-1">message</h4> <p>The Provider emits <code>message</code> to communicate arbitrary messages to the consumer. Messages may include JSON-RPC notifications, GraphQL subscriptions, and/or any other event as defined by the Provider.</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"> ProviderMessage</span><span> {</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> type</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"> data</span><span class="z-keyword">:</span><span class="z-support"> unknown</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">message</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">message</span><span class="z-keyword">:</span><span class="z-entity z-name"> ProviderMessage</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><h5 id="subscriptions-1">Subscriptions</h5> <p><a rel="external" href="https://geth.ethereum.org/docs/rpc/pubsub"><code>eth_</code> subscription methods</a> and <a rel="external" href="https://github.com/ethereum/go-ethereum/wiki/Whisper-v6-RPC-API#shh_subscribe"><code>shh_</code> subscription methods</a> rely on this event to emit subscription updates.</p> <p>For e.g. <code>eth_subscribe</code> subscription updates, <code>ProviderMessage.type</code> will equal the string <code>'eth_subscription'</code>, and the subscription data will be the value of <code>ProviderMessage.data</code>.</p> <h3 id="errors">Errors</h3> <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"> ProviderRpcError</span><span class="z-storage"> extends</span><span class="z-entity"> Error</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> message</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> code</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> data</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>}</span></span></code></pre><h2 id="appendix-ii-examples">Appendix II: 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-punctuation z-definition z-comment">//</span><span class="z-comment"> Example 1: Log chainId</span></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> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_chainId</span><span class="z-punctuation z-definition z-string">&#39;</span><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">chainId</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">log</span><span>(</span><span class="z-punctuation z-definition z-string">`</span><span class="z-string">hexadecimal string: </span><span class="z-string">${</span><span class="z-variable z-other">chainId</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 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">decimal number: </span><span class="z-string">${</span><span class="z-entity z-name">parseInt</span><span class="z-string">(</span><span class="z-variable z-other">chainId</span><span class="z-string">,</span><span class="z-constant"> 16</span><span class="z-string">)</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 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 fetching chainId: </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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Example 2: Log last block</span></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 class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_getBlockByNumber</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-punctuation z-definition z-string">&#39;</span><span class="z-string">latest</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-constant"> true</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">block</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">log</span><span>(</span><span class="z-punctuation z-definition z-string">`</span><span class="z-string">Block </span><span class="z-string">${</span><span class="z-variable z-other">block</span><span class="z-string">.</span><span class="z-variable z-other">number</span><span class="z-string">}</span><span class="z-string">:</span><span class="z-punctuation z-definition z-string">`</span><span>,</span><span class="z-variable z-other"> block</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">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> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> `</span><span class="z-string">Error fetching last block: </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-string">.</span></span> <span class="giallo-l"><span class="z-string"> Code: </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">. Data: </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">data</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">`</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 class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Example 3: Log available accounts</span></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> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_accounts</span><span class="z-punctuation z-definition z-string">&#39;</span><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">accounts</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">log</span><span>(</span><span class="z-punctuation z-definition z-string">`</span><span class="z-string">Accounts:</span><span class="z-constant">\n</span><span class="z-string">${</span><span class="z-variable z-other">accounts</span><span class="z-string">.</span><span class="z-entity z-name">join</span><span class="z-string">(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-constant">\n</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">)</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 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> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> `</span><span class="z-string">Error fetching accounts: </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-string">.</span></span> <span class="giallo-l"><span class="z-string"> Code: </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">. Data: </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">data</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">`</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 class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Example 4: Log new blocks</span></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 class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_subscribe</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-punctuation z-definition z-string">&#39;</span><span class="z-string">newHeads</span><span class="z-punctuation z-definition z-string">&#39;</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">subscriptionId</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">message</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> (</span><span class="z-variable">message</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-other">message</span><span>.</span><span class="z-variable z-other">type</span><span class="z-keyword"> ===</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_subscription</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> {</span><span class="z-variable z-other z-constant"> data</span><span> }</span><span class="z-keyword"> =</span><span class="z-variable z-other"> message</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">subscription</span><span class="z-keyword"> ===</span><span class="z-variable z-other"> subscriptionId</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">result</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> in</span><span class="z-variable z-other"> data</span><span class="z-keyword"> &amp;&amp;</span><span class="z-keyword"> typeof</span><span class="z-variable z-other"> data</span><span>.</span><span class="z-variable z-other">result</span><span class="z-keyword"> ===</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-storage z-type"> const</span><span class="z-variable z-other z-constant"> block</span><span class="z-keyword"> =</span><span class="z-variable z-other"> data</span><span>.</span><span class="z-variable z-other">result</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">New block </span><span class="z-string">${</span><span class="z-variable z-other">block</span><span class="z-string">.</span><span class="z-variable z-other">number</span><span class="z-string">}</span><span class="z-string">:</span><span class="z-punctuation z-definition z-string">`</span><span>,</span><span class="z-variable z-other"> block</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"> 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">Something went wrong: </span><span class="z-string">${</span><span class="z-variable z-other">data</span><span class="z-string">.</span><span class="z-variable z-other">result</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 class="giallo-l"><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></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> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> `</span><span class="z-string">Error making newHeads subscription: </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-string">.</span></span> <span class="giallo-l"><span class="z-string"> Code: </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">. Data: </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">data</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">`</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 class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Example 5: Log when accounts change</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-entity z-name"> logAccounts</span><span class="z-keyword"> =</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-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">Accounts:</span><span class="z-constant">\n</span><span class="z-string">${</span><span class="z-variable z-other">accounts</span><span class="z-string">.</span><span class="z-entity z-name">join</span><span class="z-string">(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-constant">\n</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">)</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 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">accountsChanged</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-variable z-other"> logAccounts</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> to unsubscribe</span></span> <span class="giallo-l"><span class="z-variable z-other">ethereum</span><span>.</span><span class="z-entity z-name">removeListener</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">accountsChanged</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-variable z-other"> logAccounts</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"> Example 6: Log if connection ends</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">disconnect</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> (</span><span class="z-variable">code</span><span>,</span><span class="z-variable"> reason</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">log</span><span>(</span><span class="z-punctuation z-definition z-string">`</span><span class="z-string">Ethereum Provider connection closed: </span><span class="z-string">${</span><span class="z-variable z-other">reason</span><span class="z-string">}</span><span class="z-string">. Code: </span><span class="z-string">${</span><span class="z-variable z-other">code</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></code></pre><h2 id="appendix-iii-legacy-provider-api">Appendix III: Legacy Provider API</h2> <p>This section documents the legacy Provider API, which is extensively used in production at the time of writing. As it was never fully standardized, significant deviations occur in practice. The authors recommend against implementing it except to support legacy Ethereum applications.</p> <h3 id="sendasync-deprecated">sendAsync (DEPRECATED)</h3> <p>This method is superseded by <a href="https://wg-eips.ritovision.com/1193/#request"><code>request</code></a>.</p> <p><code>sendAsync</code> is like <code>request</code>, but with JSON-RPC objects and a callback.</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-variable z-other">Provider</span><span>.</span><span class="z-entity z-name">sendAsync</span><span>(</span><span class="z-variable z-other">request</span><span>: </span><span class="z-variable z-other">Object</span><span>,</span><span class="z-variable z-other"> callback</span><span>: </span><span class="z-variable z-other">Function</span><span>)</span><span>: </span><span class="z-keyword">void</span><span>;</span></span></code></pre> <p>Historically, the request and response object interfaces have followed the <a href="https://wg-eips.ritovision.com/1474/">Ethereum JSON-RPC specification</a>.</p> <h3 id="send-deprecated">send (DEPRECATED)</h3> <p>This method is superseded by <a href="https://wg-eips.ritovision.com/1193/#request"><code>request</code></a>.</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-variable z-other">Provider</span><span>.</span><span class="z-entity z-name">send</span><span>(</span><span class="z-keyword">...</span><span class="z-variable z-other">args</span><span>: </span><span class="z-variable z-other">unknown</span><span>[</span><span>]</span><span>)</span><span>: </span><span class="z-variable z-other">unknown</span><span>;</span></span></code></pre><h3 id="legacy-events">Legacy Events</h3> <h4 id="close-deprecated">close (DEPRECATED)</h4> <p>This event is superseded by <a href="https://wg-eips.ritovision.com/1193/#disconnect"><code>disconnect</code></a>.</p> <h4 id="networkchanged-deprecated">networkChanged (DEPRECATED)</h4> <p>The event <code>networkChanged</code> is superseded by <a href="https://wg-eips.ritovision.com/1193/#chainchanged"><code>chainChanged</code></a>.</p> <p>For details, see <a href="https://wg-eips.ritovision.com/155/">EIP-155: Simple replay attack protection</a> and <a href="https://wg-eips.ritovision.com/695/">EIP-695: Create eth_chainId method for JSON-RPC</a>.</p> <h4 id="notification-deprecated">notification (DEPRECATED)</h4> <p>This event is superseded by <a href="https://wg-eips.ritovision.com/1193/#message"><code>message</code></a>.</p> <p>Historically, this event has been emitted with e.g. <code>eth_subscribe</code> subscription updates of the form <code>{ subscription: string, result: unknown }</code>.</p> 2018-06-26T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jim McDonaldhttps://github.com/mcdee https://wg-eips.ritovision.com/1185/

A system to store and retrieve DNS records within the ENS contract.

<h2 id="abstract">Abstract</h2> <p>This EIP defines a resolver profile for ENS that provides features for storage and lookup of DNS records. This allows ENS to be used as a store of authoritative DNS information.</p> <h2 id="motivation">Motivation</h2> <p>ENS is a highly desirable store for DNS information. It provides the distributed authority of DNS without conflating ownership and authoritative serving of information. With ENS, the owner of a domain has full control over their own DNS records. Also, ENS has the ability (through smart contracts) for a domain's subdomains to be irrevocably assigned to another entity.</p> <h2 id="specification">Specification</h2> <p>The resolver profile to support DNS on ENS follows the resolver specification as defined in <a href="https://wg-eips.ritovision.com/137/">ERC-137</a>.</p> <p>Traditionally, DNS is a zone-based system in that all of the records for a zone are kept together in the same file. This has the benefit of simplicity and atomicity of zone updates, but when transposed to ENS can result in significant gas costs for simple changes. As a result, the resolver works on the basis of record sets. A record set is uniquely defined by the tuple <code>(domain, name, resource record type)</code>, for example the tuple <code>(example.com, www.example.com, A)</code> defines the record set of <code>A</code> records for the name <code>www.example.com</code> in the domain <code>example.com</code>. A record set can contain 0 or more values, for example if <code>www.example.com</code> has <code>A</code> records <code>1.2.3.4</code> and <code>5.6.7.8</code> then the aforementioned tuple will have two values.</p> <p>The choice to work at the level of record sets rather than zones means that this specification cannot completely support some features of DNS, such as zone transfers and DNSSEC. It would be possible to build a different resolver profile that works at the zone level, however it would be very expensive to carry out updates and so is not considered further for this EIP.</p> <p>The DNS resolver interface consists of two functions to set DNS information and two functions to query DNS information.</p> <h3 id="setdnsrecords-bytes32-node-bytes-data">setDNSRecords(bytes32 node, bytes data)</h3> <p><code>setDNSRecords()</code> sets, updates or clears 1 or more DNS records for a given node. It has function signature <code>0x0af179d7</code>.</p> <p>The arguments for the function are as follows:</p> <ul> <li>node: the namehash of the fully-qualified domain in ENS for which to set the records. Namehashes are defined in <a href="https://wg-eips.ritovision.com/137/">ERC-137</a></li> <li>data: 1 or more DNS records in DNS wire format. Any record that is supplied without a value will be cleared. Note that all records in the same RRset should be contiguous within the data; if not then the later RRsets will overwrite the earlier one(s)</li> </ul> <h3 id="cleardnszone-bytes32-node">clearDNSZone(bytes32 node)</h3> <p><code>clearDNSZone()</code> removes all DNS records for the domain. It has function signature <code>0xad5780af</code>.</p> <p>Although it is possible to clear records individually with <code>setDNSRecords()</code> as described above this requires the owner to know all of the records that have been set (as the resolver has no methods to iterate over the records for a given domain), and might require multiple transactions. <code>clearDNSZone()</code> removes all zone information in a single operation.</p> <p>The arguments for the function is as follows:</p> <ul> <li>node: the namehash of the fully-qualified domain in ENS for which to clear the records. Namehashes are defined in <a href="https://wg-eips.ritovision.com/137/">ERC-137</a></li> </ul> <h3 id="dnsrecords-bytes32-node-bytes32-name-uint16-resource-view-returns-bytes">dnsRecords(bytes32 node, bytes32 name, uint16 resource) view returns (bytes)</h3> <p><code>dnsRecords()</code> obtains the DNS records for a given node, name and resource. It has function signature <code>0x2461e851</code>.</p> <p>The arguments for the function are as follows:</p> <ul> <li>node: the namehash of the fully-qualified domain in ENS for which to set the records. Namehashes are defined in <a href="https://wg-eips.ritovision.com/137/">ERC-137</a></li> <li>name: the <code>keccak256()</code> hash of the name of the record in DNS wire format.</li> <li>resource: the resource record ID. Resource record IDs are defined in RFC1035 and subsequent RFCs.</li> </ul> <p>The function returns all matching records in DNS wire format. If there are no records present the function will return nothing.</p> <h3 id="hasdnsrecords-bytes32-node-bytes32-name-view-returns-bool">hasDNSRecords(bytes32 node, bytes32 name) view returns (bool)</h3> <p><code>hasDNSRecords()</code> reports if there are any records for the provided name in the domain. It has function signature <code>0x4cbf6ba4</code>.</p> <p>This function is needed by DNS resolvers when working with wildcard resources as defined in RFC4592.</p> <p>The arguments for the function are as follows:</p> <ul> <li>node: the namehash of the fully-qualified domain in ENS for which to set the records. Namehashes are defined in <a href="https://wg-eips.ritovision.com/137/">ERC-137</a></li> <li>name: the <code>keccak256()</code> hash of the name of the record in DNS wire format.</li> </ul> <p>The function returns <code>true</code> if there are any records for the provided node and name, otherwise <code>false</code>.</p> <h2 id="rationale">Rationale</h2> <p>DNS is a federated system of naming, and the higher-level entities control availability of everything beneath them (<em>e.g.</em> <code>.org</code> controls the availability of <code>ethereum.org</code>). A decentralized version of DNS would not have this constraint, and allow lookups directly for any domain with relevant records within ENS.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Not applicable.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation of the DNS resolver is as follows:</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.7.4</span><span>;</span></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 class="z-keyword">import</span><span class="z-string"> &quot;@ensdomains/dnssec-oracle/contracts/RRUtils.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"> DNSResolver</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-keyword"> using</span><span> RRUtils </span><span class="z-keyword">for</span><span class="z-keyword"> *</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> BytesUtils</span><span class="z-keyword"> for</span><span class="z-entity z-name"> bytes</span><span>;</span></span> <span class="giallo-l"></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> DNS_RECORD_INTERFACE_ID </span><span class="z-keyword">=</span><span class="z-constant"> 0xa8fa5682</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> DNS_ZONE_INTERFACE_ID </span><span class="z-keyword">=</span><span class="z-constant"> 0x5c47637c</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> DNSRecordChanged is emitted whenever a given node/name/resource&#39;s RRSET is updated.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DNSRecordChanged</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">bytes</span><span class="z-variable"> name</span><span>, </span><span class="z-support">uint16</span><span class="z-variable"> resource</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> record</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> DNSRecordDeleted is emitted whenever a given node/name/resource&#39;s RRSET is deleted.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DNSRecordDeleted</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">bytes</span><span class="z-variable"> name</span><span>, </span><span class="z-support">uint16</span><span class="z-variable"> resource</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> DNSZoneCleared is emitted whenever a given node&#39;s zone information is cleared.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DNSZoneCleared</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>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> DNSZonehashChanged is emitted whenever a given node&#39;s zone hash is updated.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DNSZonehashChanged</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">bytes</span><span class="z-variable"> lastzonehash</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> zonehash</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Zone hashes for the domains.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> A zone hash is an ERC-1577 content hash in binary format that should point to a</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> resource containing a single zonefile.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> node =&gt; contenthash</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">bytes</span><span>)</span><span class="z-storage z-type"> private</span><span> zonehashes</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Version the mapping for each zone. This allows users who have lost</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> track of their entries to effectively delete an entire zone by bumping</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> the version number.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> node =&gt; version</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">uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> versions</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The records themselves. Stored as binary RRSETs</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> node =&gt; version =&gt; name =&gt; resource =&gt; data</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">uint256</span><span class="z-keyword">=&gt;</span><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">uint16</span><span class="z-keyword">=&gt;</span><span class="z-support">bytes</span><span>)</span><span>)</span><span>)</span><span>)</span><span class="z-storage z-type"> private</span><span> records</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Count of number of entries for a given name. Required for DNS resolvers</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> when resolving wildcards.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> node =&gt; version =&gt; name =&gt; number of records</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">uint256</span><span class="z-keyword">=&gt;</span><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">uint16</span><span>)</span><span>)</span><span>)</span><span class="z-storage z-type"> private</span><span> nameEntriesCount</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"> * Set one or more DNS records. Records are supplied in wire-format.</span></span> <span class="giallo-l"><span class="z-comment"> * Records with the same node/name/resource must be supplied one after the</span></span> <span class="giallo-l"><span class="z-comment"> * other to ensure the data is updated correctly. For example, if the data</span></span> <span class="giallo-l"><span class="z-comment"> * was supplied:</span></span> <span class="giallo-l"><span class="z-comment"> * a.example.com IN A 1.2.3.4</span></span> <span class="giallo-l"><span class="z-comment"> * a.example.com IN A 5.6.7.8</span></span> <span class="giallo-l"><span class="z-comment"> * www.example.com IN CNAME a.example.com.</span></span> <span class="giallo-l"><span class="z-comment"> * then this would store the two A records for a.example.com correctly as a</span></span> <span class="giallo-l"><span class="z-comment"> * single RRSET, however if the data was supplied:</span></span> <span class="giallo-l"><span class="z-comment"> * a.example.com IN A 1.2.3.4</span></span> <span class="giallo-l"><span class="z-comment"> * www.example.com IN CNAME a.example.com.</span></span> <span class="giallo-l"><span class="z-comment"> * a.example.com IN A 5.6.7.8</span></span> <span class="giallo-l"><span class="z-comment"> * then this would store the first A record, the CNAME, then the second A</span></span> <span class="giallo-l"><span class="z-comment"> * record which would overwrite the first.</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"> node</span><span class="z-comment"> the namehash of the node for which to set the records</span></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 DNS wire format records 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"> setDNSRecords</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"> data</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"> uint16</span><span> resource </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> offset </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> name</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> value</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> nameHash</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Iterate over the data to add the resource records</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span>RRUtils</span><span>.</span><span>RRIterator </span><span class="z-storage z-type">memory</span><span> iter </span><span class="z-keyword">=</span><span> data</span><span>.</span><span class="z-entity z-name">iterateRRs</span><span>(</span><span class="z-constant">0</span><span>)</span><span>;</span><span class="z-keyword"> !</span><span>iter</span><span>.</span><span class="z-entity z-name">done</span><span>(</span><span>)</span><span>;</span><span> iter</span><span>.</span><span class="z-entity z-name">next</span><span>(</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>resource </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> resource </span><span class="z-keyword">=</span><span> iter</span><span>.</span><span>dnstype</span><span>;</span></span> <span class="giallo-l"><span> name </span><span class="z-keyword">=</span><span> iter</span><span>.</span><span class="z-entity z-name">name</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> nameHash </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>name</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> value </span><span class="z-keyword">=</span><span class="z-support"> bytes</span><span>(</span><span>iter</span><span>.</span><span class="z-entity z-name">rdata</span><span>(</span><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-support"> bytes</span><span class="z-storage z-type"> memory</span><span> newName </span><span class="z-keyword">=</span><span> iter</span><span>.</span><span class="z-entity z-name">name</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>resource </span><span class="z-keyword">!=</span><span> iter</span><span>.</span><span>dnstype </span><span class="z-keyword">||</span><span class="z-keyword"> !</span><span>name</span><span>.</span><span class="z-entity z-name">equals</span><span>(</span><span>newName</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> setDNSRRSet</span><span>(</span><span>node</span><span>,</span><span> name</span><span>,</span><span> resource</span><span>,</span><span> data</span><span>,</span><span> offset</span><span>,</span><span> iter</span><span>.</span><span>offset </span><span class="z-keyword">-</span><span> offset</span><span>,</span><span> value</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> resource </span><span class="z-keyword">=</span><span> iter</span><span>.</span><span>dnstype</span><span>;</span></span> <span class="giallo-l"><span> offset </span><span class="z-keyword">=</span><span> iter</span><span>.</span><span>offset</span><span>;</span></span> <span class="giallo-l"><span> name </span><span class="z-keyword">=</span><span> newName</span><span>;</span></span> <span class="giallo-l"><span> nameHash </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span>name</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> value </span><span class="z-keyword">=</span><span class="z-support"> bytes</span><span>(</span><span>iter</span><span>.</span><span class="z-entity z-name">rdata</span><span>(</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 class="z-keyword"> if</span><span> (</span><span>name</span><span>.</span><span>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"> setDNSRRSet</span><span>(</span><span>node</span><span>,</span><span> name</span><span>,</span><span> resource</span><span>,</span><span> data</span><span>,</span><span> offset</span><span>,</span><span> data</span><span>.</span><span>length </span><span class="z-keyword">-</span><span> offset</span><span>,</span><span> value</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> }</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"> * Obtain a DNS 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"> node</span><span class="z-comment"> the namehash of the node for which to fetch the 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"> name</span><span class="z-comment"> the keccak-256 hash of the fully-qualified name for which to fetch the 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"> resource</span><span class="z-comment"> the ID of the resource as per https://en.wikipedia.org/wiki/List_of_DNS_record_types</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"> DNS record in wire format if present, otherwise 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"> dnsRecord</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> name</span><span>,</span><span class="z-support"> uint16</span><span class="z-variable"> resource</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> records</span><span>[</span><span>node</span><span>]</span><span>[</span><span>versions</span><span>[</span><span>node</span><span>]</span><span>]</span><span>[</span><span>name</span><span>]</span><span>[</span><span>resource</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"> * Check if a given node has records.</span></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 namehash of the node for which to check the records</span></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 namehash of the node for which to check the records</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"> hasDNSRecords</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> name</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> (</span><span>nameEntriesCount</span><span>[</span><span>node</span><span>]</span><span>[</span><span>versions</span><span>[</span><span>node</span><span>]</span><span>]</span><span>[</span><span>name</span><span>]</span><span class="z-keyword"> !=</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"> * Clear all information for a DNS zone.</span></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 namehash of the node for which to clear the zone</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"> clearDNSZone</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-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> versions</span><span>[</span><span>node</span><span>]</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> DNSZoneCleared</span><span>(</span><span>node</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"> * setZonehash sets the hash for the zone.</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"> hash</span><span class="z-comment"> The zonehash 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"> setZonehash</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"> 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> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> oldhash </span><span class="z-keyword">=</span><span> zonehashes</span><span>[</span><span>node</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> zonehashes</span><span>[</span><span>node</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"> DNSZonehashChanged</span><span>(</span><span>node</span><span>,</span><span> oldhash</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-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * zonehash obtains the hash for the zone.</span></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 contenthash.</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"> zonehash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</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> zonehashes</span><span>[</span><span>node</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"> virtual</span><span class="z-storage z-type"> override</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> DNS_RECORD_INTERFACE_ID </span><span class="z-keyword">||</span></span> <span class="giallo-l"><span> interfaceID </span><span class="z-keyword">==</span><span> DNS_ZONE_INTERFACE_ID </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"> setDNSRRSet</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> node</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"> name</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint16</span><span class="z-variable"> resource</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-support"> uint256</span><span class="z-variable"> offset</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> size</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> deleteRecord</span><span>)</span><span class="z-storage z-type"> private</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> version </span><span class="z-keyword">=</span><span> versions</span><span>[</span><span>node</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> nameHash </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span>name</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> rrData </span><span class="z-keyword">=</span><span> data</span><span>.</span><span class="z-entity z-name">substring</span><span>(</span><span>offset</span><span>,</span><span> size</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>deleteRecord</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>records</span><span>[</span><span>node</span><span>]</span><span>[</span><span>version</span><span>]</span><span>[</span><span>nameHash</span><span>]</span><span>[</span><span>resource</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> nameEntriesCount</span><span>[</span><span>node</span><span>]</span><span>[</span><span>version</span><span>]</span><span>[</span><span>nameHash</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 class="z-keyword"> delete</span><span>(</span><span>records</span><span>[</span><span>node</span><span>]</span><span>[</span><span>version</span><span>]</span><span>[</span><span>nameHash</span><span>]</span><span>[</span><span>resource</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> DNSRecordDeleted</span><span>(</span><span>node</span><span>,</span><span> name</span><span>,</span><span> resource</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"> if</span><span> (</span><span>records</span><span>[</span><span>node</span><span>]</span><span>[</span><span>version</span><span>]</span><span>[</span><span>nameHash</span><span>]</span><span>[</span><span>resource</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> nameEntriesCount</span><span>[</span><span>node</span><span>]</span><span>[</span><span>version</span><span>]</span><span>[</span><span>nameHash</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> records</span><span>[</span><span>node</span><span>]</span><span>[</span><span>version</span><span>]</span><span>[</span><span>nameHash</span><span>]</span><span>[</span><span>resource</span><span>]</span><span class="z-keyword"> =</span><span> rrData</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> DNSRecordChanged</span><span>(</span><span>node</span><span>,</span><span> name</span><span>,</span><span> resource</span><span>,</span><span> rrData</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> <p>Security of this solution would be dependent on security of the records within the ENS domain. This degenenrates to the security of the key(s) which have authority over that domain.</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-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 Peter Murrayhttps://github.com/yarrumretep Nate Welchhttps://github.com/flygoing Joe Messermanhttps://github.com/JAMesserman https://wg-eips.ritovision.com/1167/ <h2 id="simple-summary">Simple Summary</h2> <p>To simply and cheaply clone contract functionality in an immutable way, this standard specifies a minimal bytecode implementation that delegates all calls to a known, fixed address.</p> <h2 id="abstract">Abstract</h2> <p>By standardizing on a known minimal bytecode redirect implementation, this standard allows users and third party tools (e.g. Etherscan) to (a) simply discover that a contract will always redirect in a known manner and (b) depend on the behavior of the code at the destination contract as the behavior of the redirecting contract. Specifically, tooling can interrogate the bytecode at a redirecting address to determine the location of the code that will run - and can depend on representations about that code (verified source, third-party audits, etc). This implementation forwards all calls and 100% of the gas to the implementation contract and then relays the return value back to the caller. In the case where the implementation reverts, the revert is passed back along with the payload data (for revert with message).</p> <h2 id="motivation">Motivation</h2> <p>This standard supports use-cases wherein it is desirable to clone exact contract functionality with a minimum of side effects (e.g. memory slot stomping) and with low gas cost deployment of duplicate proxies.</p> <h2 id="specification">Specification</h2> <p>The exact bytecode of the standard clone contract is this: <code>363d3d373d3d3d363d73bebebebebebebebebebebebebebebebebebebebe5af43d82803e903d91602b57fd5bf3</code> wherein the bytes at indices 10 - 29 (inclusive) are replaced with the 20 byte address of the master functionality contract.</p> <p>A reference implementation of this can be found at the <a rel="external" href="https://github.com/optionality/clone-factory">optionality/clone-factory</a> github repo.</p> <h2 id="rationale">Rationale</h2> <p>The goals of this effort have been the following:</p> <ul> <li>inexpensive deployment (low gas to deploy clones)</li> <li>support clone initialization in creation transaction (through factory contract model)</li> <li>simple clone bytecode to encourage directly bytecode interrogation (see CloneProbe.sol in the clone-factory project)</li> <li>dependable, locked-down behavior - this is not designed to handle upgradability, nor should it as the representation we are seeking is stronger.</li> <li>small operational overhead - adds a single call cost to each call</li> <li>handles error return bubbling for revert messages</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no backwards compatibility issues. There may be some systems that are using earlier versions of the proxy contract bytecode. They will not be compliant with this standard.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases include:</p> <ul> <li>invocation with no arguments</li> <li>invocation with arguments</li> <li>invocation with fixed length return values</li> <li>invocation with variable length return values</li> <li>invocation with revert (confirming reverted payload is transferred)</li> </ul> <p>Tests for these cases are included in the reference implementation project.</p> <h2 id="implementation">Implementation</h2> <p>Deployment bytecode is not included in this specification. One approach is defined in the proxy-contract reference implementation.</p> <h3 id="standard-proxy">Standard Proxy</h3> <p>The disassembly of the standard deployed proxy contract code (from r2 and edited to include stack visualization)</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>| 0x00000000 36 calldatasize cds</span></span> <span class="giallo-l"><span>| 0x00000001 3d returndatasize 0 cds</span></span> <span class="giallo-l"><span>| 0x00000002 3d returndatasize 0 0 cds</span></span> <span class="giallo-l"><span>| 0x00000003 37 calldatacopy </span></span> <span class="giallo-l"><span>| 0x00000004 3d returndatasize 0</span></span> <span class="giallo-l"><span>| 0x00000005 3d returndatasize 0 0 </span></span> <span class="giallo-l"><span>| 0x00000006 3d returndatasize 0 0 0</span></span> <span class="giallo-l"><span>| 0x00000007 36 calldatasize cds 0 0 0</span></span> <span class="giallo-l"><span>| 0x00000008 3d returndatasize 0 cds 0 0 0</span></span> <span class="giallo-l"><span>| 0x00000009 73bebebebebe. push20 0xbebebebe 0xbebe 0 cds 0 0 0</span></span> <span class="giallo-l"><span>| 0x0000001e 5a gas gas 0xbebe 0 cds 0 0 0</span></span> <span class="giallo-l"><span>| 0x0000001f f4 delegatecall suc 0</span></span> <span class="giallo-l"><span>| 0x00000020 3d returndatasize rds suc 0</span></span> <span class="giallo-l"><span>| 0x00000021 82 dup3 0 rds suc 0</span></span> <span class="giallo-l"><span>| 0x00000022 80 dup1 0 0 rds suc 0</span></span> <span class="giallo-l"><span>| 0x00000023 3e returndatacopy suc 0</span></span> <span class="giallo-l"><span>| 0x00000024 90 swap1 0 suc</span></span> <span class="giallo-l"><span>| 0x00000025 3d returndatasize rds 0 suc</span></span> <span class="giallo-l"><span>| 0x00000026 91 swap2 suc 0 rds</span></span> <span class="giallo-l"><span>| 0x00000027 602b push1 0x2b 0x2b suc 0 rds</span></span> <span class="giallo-l"><span>| ,=&lt; 0x00000029 57 jumpi 0 rds</span></span> <span class="giallo-l"><span>| | 0x0000002a fd revert</span></span> <span class="giallo-l"><span>| `-&gt; 0x0000002b 5b jumpdest 0 rds</span></span> <span class="giallo-l"><span>\ 0x0000002c f3 return</span></span> <span class="giallo-l"></span></code></pre> <p>NOTE: as an effort to reduce gas costs as much as possible, the above bytecode depends on EIP-211 specification that <code>returndatasize</code> returns zero prior to any calls within the call-frame. <code>returndatasize</code> uses 1 less gas than <code>dup*</code>.</p> <h3 id="vanity-address-optimization">Vanity Address Optimization</h3> <p>Proxy deployment can be further optimized by installing the master contract at a vanity contract deployment address with leading zero-bytes. By generating a master contract vanity address that includes Z leading 0 bytes in its address, you can shorten the proxy bytecode by replacing the <code>push20</code> opcode with <code>pushN</code> (where N is 20 - Z) followed by the N non-zero address bytes. The revert jump address is decremented by Z in this case. Here is an example where Z = 4:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>| 0x00000000 36 calldatasize cds</span></span> <span class="giallo-l"><span>| 0x00000001 3d returndatasize 0 cds</span></span> <span class="giallo-l"><span>| 0x00000002 3d returndatasize 0 0 cds</span></span> <span class="giallo-l"><span>| 0x00000003 37 calldatacopy </span></span> <span class="giallo-l"><span>| 0x00000004 3d returndatasize 0</span></span> <span class="giallo-l"><span>| 0x00000005 3d returndatasize 0 0 </span></span> <span class="giallo-l"><span>| 0x00000006 3d returndatasize 0 0 0</span></span> <span class="giallo-l"><span>| 0x00000007 36 calldatasize cds 0 0 0</span></span> <span class="giallo-l"><span>| 0x00000008 3d returndatasize 0 cds 0 0 0</span></span> <span class="giallo-l"><span>| 0x00000009 6fbebebebebe. push16 0xbebebebe 0xbebe 0 cds 0 0 0</span></span> <span class="giallo-l"><span>| 0x0000001a 5a gas gas 0xbebe 0 cds 0 0 0</span></span> <span class="giallo-l"><span>| 0x0000001b f4 delegatecall suc 0</span></span> <span class="giallo-l"><span>| 0x0000001c 3d returndatasize rds suc 0</span></span> <span class="giallo-l"><span>| 0x0000001d 82 dup3 0 rds suc 0</span></span> <span class="giallo-l"><span>| 0x0000001e 80 dup1 0 0 rds suc 0</span></span> <span class="giallo-l"><span>| 0x0000001f 3e returndatacopy suc 0</span></span> <span class="giallo-l"><span>| 0x00000020 90 swap1 0 suc</span></span> <span class="giallo-l"><span>| 0x00000021 3d returndatasize rds 0 suc</span></span> <span class="giallo-l"><span>| 0x00000022 91 swap2 suc 0 rds</span></span> <span class="giallo-l"><span>| 0x00000023 6027 push1 0x27 0x27 suc 0 rds</span></span> <span class="giallo-l"><span>| ,=&lt; 0x00000025 57 jumpi 0 rds</span></span> <span class="giallo-l"><span>| | 0x00000026 fd revert</span></span> <span class="giallo-l"><span>| `-&gt; 0x00000027 5b jumpdest 0 rds</span></span> <span class="giallo-l"><span>\ 0x00000028 f3 return</span></span></code></pre> <p>This saves 4 bytes of proxy contract size (savings on each deployment) and has zero impact on runtime gas costs.</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-17T00:00:00+00:00 2026-02-11T14:48:25+00:00 Witek Radomskiwitek@enjin.io Andrew Cookeac0dem0nk3y@gmail.com Philippe Castonguayhttps://github.com/phabcpc@horizongames.net James Therienjames@turing-complete.com Eric Bineteric@enjin.io Ronan Sandfordhttps://github.com/wighawagwighawag@gmail.com https://wg-eips.ritovision.com/1155/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for contracts that manage multiple token types. A single deployed contract may include any combination of fungible tokens, non-fungible tokens or other configurations (e.g. semi-fungible tokens).</p> <h2 id="abstract">Abstract</h2> <p>This standard outlines a smart contract interface that can represent any number of fungible and non-fungible token types. Existing standards such as ERC-20 require deployment of separate contracts per token type. The ERC-721 standard's token ID is a single non-fungible index and the group of these non-fungibles is deployed as a single contract with settings for the entire collection. In contrast, the ERC-1155 Multi Token Standard allows for each token ID to represent a new configurable token type, which may have its own metadata, supply and other attributes.</p> <p>The <code>_id</code> argument contained in each function's argument set indicates a specific token or token type in a transaction.</p> <h2 id="motivation">Motivation</h2> <p>Tokens standards like ERC-20 and ERC-721 require a separate contract to be deployed for each token type or collection. This places a lot of redundant bytecode on the Ethereum blockchain and limits certain functionality by the nature of separating each token contract into its own permissioned address. With the rise of blockchain games and platforms like Enjin Coin, game developers may be creating thousands of token types, and a new type of token standard is needed to support them. However, ERC-1155 is not specific to games and many other applications can benefit from this flexibility.</p> <p>New functionality is possible with this design such as transferring multiple token types at once, saving on transaction costs. Trading (escrow / atomic swaps) of multiple tokens can be built on top of this standard and it removes the need to "approve" individual token contracts separately. It is also easy to describe and mix multiple fungible or non-fungible token types in a single contract.</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>Smart contracts implementing the ERC-1155 standard MUST implement all of the functions in the <code>ERC1155</code> interface.</strong></p> <p><strong>Smart contracts implementing the ERC-1155 standard MUST implement the ERC-165 <code>supportsInterface</code> function and MUST return the constant value <code>true</code> if <code>0xd9b67a26</code> is passed through the <code>interfaceID</code> argument.</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.5.9</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-1155 Multi Token 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-1155</span></span> <span class="giallo-l"><span class="z-keyword"> Note</span><span class="z-comment">: The ERC-165 identifier for this interface is 0xd9b67a26.</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"> ERC1155</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-storage z-type"> @dev</span><span class="z-comment"> Either `TransferSingle` or `TransferBatch` MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see &quot;Safe Transfer Rules&quot; section of the standard).</span></span> <span class="giallo-l"><span class="z-comment"> The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).</span></span> <span class="giallo-l"><span class="z-comment"> The `_from` argument MUST be the address of the holder whose balance is decreased.</span></span> <span class="giallo-l"><span class="z-comment"> The `_to` argument MUST be the address of the recipient whose balance is increased.</span></span> <span class="giallo-l"><span class="z-comment"> The `_id` argument MUST be the token type being transferred.</span></span> <span class="giallo-l"><span class="z-comment"> The `_value` argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by.</span></span> <span class="giallo-l"><span class="z-comment"> When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address).</span></span> <span class="giallo-l"><span class="z-comment"> When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). </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"> TransferSingle</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">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"> _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"> Either `TransferSingle` or `TransferBatch` MUST emit when tokens are transferred, including zero value transfers as well as minting or burning (see &quot;Safe Transfer Rules&quot; section of the standard). </span></span> <span class="giallo-l"><span class="z-comment"> The `_operator` argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).</span></span> <span class="giallo-l"><span class="z-comment"> The `_from` argument MUST be the address of the holder whose balance is decreased.</span></span> <span class="giallo-l"><span class="z-comment"> The `_to` argument MUST be the address of the recipient whose balance is increased.</span></span> <span class="giallo-l"><span class="z-comment"> The `_ids` argument MUST be the list of tokens being transferred.</span></span> <span class="giallo-l"><span class="z-comment"> The `_values` argument MUST be the list of number of tokens (matching the list and order of tokens specified in _ids) the holder balance is decreased by and match what the recipient balance is increased by.</span></span> <span class="giallo-l"><span class="z-comment"> When minting/creating tokens, the `_from` argument MUST be set to `0x0` (i.e. zero address).</span></span> <span class="giallo-l"><span class="z-comment"> When burning/destroying tokens, the `_to` argument MUST be set to `0x0` (i.e. zero address). </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"> TransferBatch</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">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"> _values</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 approval for a second party/operator address to manage all tokens for an owner address is enabled or disabled (absence of an event assumes disabled). </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"> 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> <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 URI is updated for a token ID.</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 to a JSON file that conforms to the &quot;ERC-1155 Metadata URI 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"> URI</span><span>(</span><span class="z-support">string</span><span class="z-variable"> _value</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-storage z-type"> @notice</span><span class="z-comment"> Transfers `_value` amount of an `_id` from the `_from` address to the `_to` address specified (with safety call).</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 (see &quot;Approval&quot; section of the standard).</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 the `TransferSingle` event to reflect the balance change (see &quot;Safe Transfer Rules&quot; section of the standard).</span></span> <span class="giallo-l"><span class="z-comment"> After the above conditions are met, this function MUST check if `_to` is a smart contract (e.g. code size &gt; 0). If so, it MUST call `onERC1155Received` on `_to` and act appropriately (see &quot;Safe Transfer Rules&quot; section of the standard). </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"> @param</span><span class="z-variable z-other"> _data</span><span class="z-comment"> Additional data with no specified format, MUST be sent unaltered in call to `onERC1155Received` on `_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"> safeTransferFrom</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-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>;</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 `_values` amount(s) of `_ids` from the `_from` address to the `_to` address specified (with safety call).</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 (see &quot;Approval&quot; section of the standard).</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 length of `_ids` is not the same as length of `_values`.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if any of the balance(s) of the holder(s) for token(s) in `_ids` is lower than the respective amount(s) in `_values` sent to the recipient.</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 `TransferSingle` or `TransferBatch` event(s) such that all the balance changes are reflected (see &quot;Safe Transfer Rules&quot; section of the standard).</span></span> <span class="giallo-l"><span class="z-comment"> Balance changes and events MUST follow the ordering of the arrays (_ids[0]/_values[0] before _ids[1]/_values[1], etc).</span></span> <span class="giallo-l"><span class="z-comment"> After the above conditions for the transfer(s) in the batch are met, this function MUST check if `_to` is a smart contract (e.g. code size &gt; 0). If so, it MUST call the relevant `ERC1155TokenReceiver` hook(s) on `_to` and act appropriately (see &quot;Safe Transfer Rules&quot; section of the standard). </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"> _ids</span><span class="z-comment"> IDs of each token type (order and length must match _values array)</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _values</span><span class="z-comment"> Transfer amounts per token type (order and length must match _ids array)</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, MUST be sent unaltered in call to the `ERC1155TokenReceiver` hook(s) on `_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"> safeBatchTransferFrom</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>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _ids</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"> _values</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>;</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 balance of multiple account/token pairs</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _owners</span><span class="z-comment"> The addresses of the token holders</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"> ID of the tokens</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 types requested (i.e. balance for each (owner, id) pair)</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"> balanceOfBatch</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"> _owners</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"> _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">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-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 all of the caller&#39;s tokens.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST emit the ApprovalForAll 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"> _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"> setApprovalForAll</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 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.</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"> @return</span><span class="z-variable z-other"> True</span><span class="z-comment"> if the operator is approved, 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"> isApprovedForAll</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></span></code></pre><h3 id="erc-1155-token-receiver">ERC-1155 Token Receiver</h3> <p><strong>Smart contracts MUST implement all of the functions in the <code>ERC1155TokenReceiver</code> interface to accept transfers. See "Safe Transfer Rules" for further detail.</strong></p> <p><strong>Smart contracts MUST implement the ERC-165 <code>supportsInterface</code> function and signify support for the <code>ERC1155TokenReceiver</code> interface to accept transfers. See "ERC1155TokenReceiver ERC-165 rules" for further detail.</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.5.9</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 0x4e2312e0.</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"> ERC1155TokenReceiver</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"> Handle the receipt of a single ERC1155 token type.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeTransferFrom` after the balance has been updated. </span></span> <span class="giallo-l"><span class="z-comment"> This function MUST return `bytes4(keccak256(&quot;onERC1155Received(address,address,uint256,uint256,bytes)&quot;))` (i.e. 0xf23a6e61) if it accepts the transfer.</span></span> <span class="giallo-l"><span class="z-comment"> This function MUST revert if it rejects the transfer.</span></span> <span class="giallo-l"><span class="z-comment"> Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller.</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 initiated the transfer (i.e. msg.sender)</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"> _id</span><span class="z-comment"> The ID of the token being transferred</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"> The amount of tokens 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;onERC1155Received(address,address,uint256,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"> onERC1155Received</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"> _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-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-keyword"> returns</span><span>(</span><span class="z-support">bytes4</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"> Handle the receipt of multiple ERC1155 token types.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> An ERC1155-compliant smart contract MUST call this function on the token recipient contract, at the end of a `safeBatchTransferFrom` after the balances have been updated. </span></span> <span class="giallo-l"><span class="z-comment"> This function MUST return `bytes4(keccak256(&quot;onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)&quot;))` (i.e. 0xbc197c81) if it accepts the transfer(s).</span></span> <span class="giallo-l"><span class="z-comment"> This function MUST revert if it rejects the transfer(s).</span></span> <span class="giallo-l"><span class="z-comment"> Return of any other value than the prescribed keccak256 generated value MUST result in the transaction being reverted by the caller.</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 initiated the batch transfer (i.e. msg.sender)</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"> _ids</span><span class="z-comment"> An array containing ids of each token being transferred (order and length must match _values array)</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _values</span><span class="z-comment"> An array containing amounts of each token being transferred (order and length must match _ids array)</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;onERC1155BatchReceived(address,address,uint256[],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"> onERC1155BatchReceived</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>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _ids</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"> _values</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-keyword"> returns</span><span>(</span><span class="z-support">bytes4</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="safe-transfer-rules">Safe Transfer Rules</h3> <p>To be more explicit about how the standard <code>safeTransferFrom</code> and <code>safeBatchTransferFrom</code> functions MUST operate with respect to the <code>ERC1155TokenReceiver</code> hook functions, a list of scenarios and rules follows.</p> <h4 id="scenarios">Scenarios</h4> <p><em><strong>Scenario#1 :</strong></em> The recipient is not a contract.</p> <ul> <li><code>onERC1155Received</code> and <code>onERC1155BatchReceived</code> MUST NOT be called on an EOA (Externally Owned Account).</li> </ul> <p><em><strong>Scenario#2 :</strong></em> The transaction is not a mint/transfer of a token.</p> <ul> <li><code>onERC1155Received</code> and <code>onERC1155BatchReceived</code> MUST NOT be called outside of a mint or transfer process.</li> </ul> <p><em><strong>Scenario#3 :</strong></em> The receiver does not implement the necessary <code>ERC1155TokenReceiver</code> interface function(s).</p> <ul> <li>The transfer MUST be reverted with the one caveat below. <ul> <li>If the token(s) being sent are part of a hybrid implementation of another standard, that particular standard's rules on sending to a contract MAY now be followed instead. See "Backwards Compatibility" section.</li> </ul> </li> </ul> <p><em><strong>Scenario#4 :</strong></em> The receiver implements the necessary <code>ERC1155TokenReceiver</code> interface function(s) but returns an unknown value.</p> <ul> <li>The transfer MUST be reverted.</li> </ul> <p><em><strong>Scenario#5 :</strong></em> The receiver implements the necessary <code>ERC1155TokenReceiver</code> interface function(s) but throws an error.</p> <ul> <li>The transfer MUST be reverted.</li> </ul> <p><em><strong>Scenario#6 :</strong></em> The receiver implements the <code>ERC1155TokenReceiver</code> interface and is the recipient of one and only one balance change (e.g. <code>safeTransferFrom</code> called).</p> <ul> <li>The balances for the transfer MUST have been updated before the <code>ERC1155TokenReceiver</code> hook is called on a recipient contract.</li> <li>The transfer event MUST have been emitted to reflect the balance changes before the <code>ERC1155TokenReceiver</code> hook is called on the recipient contract.</li> <li>One of <code>onERC1155Received</code> or <code>onERC1155BatchReceived</code> MUST be called on the recipient contract.</li> <li>The <code>onERC1155Received</code> hook SHOULD be called on the recipient contract and its rules followed. <ul> <li>See "onERC1155Received rules" for further rules that MUST be followed.</li> </ul> </li> <li>The <code>onERC1155BatchReceived</code> hook MAY be called on the recipient contract and its rules followed. <ul> <li>See "onERC1155BatchReceived rules" for further rules that MUST be followed.</li> </ul> </li> </ul> <p><em><strong>Scenario#7 :</strong></em> The receiver implements the <code>ERC1155TokenReceiver</code> interface and is the recipient of more than one balance change (e.g. <code>safeBatchTransferFrom</code> called).</p> <ul> <li>All balance transfers that are referenced in a call to an <code>ERC1155TokenReceiver</code> hook MUST be updated before the <code>ERC1155TokenReceiver</code> hook is called on the recipient contract.</li> <li>All transfer events MUST have been emitted to reflect current balance changes before an <code>ERC1155TokenReceiver</code> hook is called on the recipient contract.</li> <li><code>onERC1155Received</code> or <code>onERC1155BatchReceived</code> MUST be called on the recipient as many times as necessary such that every balance change for the recipient in the scenario is accounted for. <ul> <li>The return magic value for every hook call MUST be checked and acted upon as per "onERC1155Received rules" and "onERC1155BatchReceived rules".</li> </ul> </li> <li>The <code>onERC1155BatchReceived</code> hook SHOULD be called on the recipient contract and its rules followed. <ul> <li>See "onERC1155BatchReceived rules" for further rules that MUST be followed.</li> </ul> </li> <li>The <code>onERC1155Received</code> hook MAY be called on the recipient contract and its rules followed. <ul> <li>See "onERC1155Received rules" for further rules that MUST be followed.</li> </ul> </li> </ul> <p><em><strong>Scenario#8 :</strong></em> You are the creator of a contract that implements the <code>ERC1155TokenReceiver</code> interface and you forward the token(s) onto another address in one or both of <code>onERC1155Received</code> and <code>onERC1155BatchReceived</code>.</p> <ul> <li>Forwarding should be considered acceptance and then initiating a new <code>safeTransferFrom</code> or <code>safeBatchTransferFrom</code> in a new context. <ul> <li>The prescribed keccak256 acceptance value magic for the receiver hook being called MUST be returned after forwarding is successful.</li> </ul> </li> <li>The <code>_data</code> argument MAY be re-purposed for the new context.</li> <li>If forwarding fails the transaction MAY be reverted. <ul> <li>If the contract logic wishes to keep the ownership of the token(s) itself in this case it MAY do so.</li> </ul> </li> </ul> <p><em><strong>Scenario#9 :</strong></em> You are transferring tokens via a non-standard API call i.e. an implementation specific API and NOT <code>safeTransferFrom</code> or <code>safeBatchTransferFrom</code>.</p> <ul> <li>In this scenario all balance updates and events output rules are the same as if a standard transfer function had been called. <ul> <li>i.e. an external viewer MUST still be able to query the balance via a standard function and it MUST be identical to the balance as determined by <code>TransferSingle</code> and <code>TransferBatch</code> events alone.</li> </ul> </li> <li>If the receiver is a contract the <code>ERC1155TokenReceiver</code> hooks still need to be called on it and the return values respected the same as if a standard transfer function had been called. <ul> <li>However while the <code>safeTransferFrom</code> or <code>safeBatchTransferFrom</code> functions MUST revert if a receiving contract does not implement the <code>ERC1155TokenReceiver</code> interface, a non-standard function MAY proceed with the transfer.</li> <li>See "Implementation specific transfer API rules".</li> </ul> </li> </ul> <h4 id="rules">Rules</h4> <p><em><strong>safeTransferFrom rules:</strong></em></p> <ul> <li>Caller must be approved to manage the tokens being transferred out of the <code>_from</code> account (see "Approval" section).</li> <li>MUST revert if <code>_to</code> is the zero address.</li> <li>MUST revert if balance of holder for token <code>_id</code> is lower than the <code>_value</code> sent to the recipient.</li> <li>MUST revert on any other error.</li> <li>MUST emit the <code>TransferSingle</code> event to reflect the balance change (see "TransferSingle and TransferBatch event rules" section).</li> <li>After the above conditions are met, this function MUST check if <code>_to</code> is a smart contract (e.g. code size &gt; 0). If so, it MUST call <code>onERC1155Received</code> on <code>_to</code> and act appropriately (see "onERC1155Received rules" section). <ul> <li>The <code>_data</code> argument provided by the sender for the transfer MUST be passed with its contents unaltered to the <code>onERC1155Received</code> hook function via its <code>_data</code> argument.</li> </ul> </li> </ul> <p><em><strong>safeBatchTransferFrom rules:</strong></em></p> <ul> <li>Caller must be approved to manage all the tokens being transferred out of the <code>_from</code> account (see "Approval" section).</li> <li>MUST revert if <code>_to</code> is the zero address.</li> <li>MUST revert if length of <code>_ids</code> is not the same as length of <code>_values</code>.</li> <li>MUST revert if any of the balance(s) of the holder(s) for token(s) in <code>_ids</code> is lower than the respective amount(s) in <code>_values</code> sent to the recipient.</li> <li>MUST revert on any other error.</li> <li>MUST emit <code>TransferSingle</code> or <code>TransferBatch</code> event(s) such that all the balance changes are reflected (see "TransferSingle and TransferBatch event rules" section).</li> <li>The balance changes and events MUST occur in the array order they were submitted (_ids[0]/_values[0] before _ids[1]/_values[1], etc).</li> <li>After the above conditions are met, this function MUST check if <code>_to</code> is a smart contract (e.g. code size &gt; 0). If so, it MUST call <code>onERC1155Received</code> or <code>onERC1155BatchReceived</code> on <code>_to</code> and act appropriately (see "onERC1155Received and onERC1155BatchReceived rules" section). <ul> <li>The <code>_data</code> argument provided by the sender for the transfer MUST be passed with its contents unaltered to the <code>ERC1155TokenReceiver</code> hook function(s) via their <code>_data</code> argument.</li> </ul> </li> </ul> <p><em><strong>TransferSingle and TransferBatch event rules:</strong></em></p> <ul> <li><code>TransferSingle</code> SHOULD be used to indicate a single balance transfer has occurred between a <code>_from</code> and <code>_to</code> pair. <ul> <li>It MAY be emitted multiple times to indicate multiple balance changes in the transaction, but note that <code>TransferBatch</code> is designed for this to reduce gas consumption.</li> <li>The <code>_operator</code> argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).</li> <li>The <code>_from</code> argument MUST be the address of the holder whose balance is decreased.</li> <li>The <code>_to</code> argument MUST be the address of the recipient whose balance is increased.</li> <li>The <code>_id</code> argument MUST be the token type being transferred.</li> <li>The <code>_value</code> argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by.</li> <li>When minting/creating tokens, the <code>_from</code> argument MUST be set to <code>0x0</code> (i.e. zero address). See "Minting/creating and burning/destroying rules".</li> <li>When burning/destroying tokens, the <code>_to</code> argument MUST be set to <code>0x0</code> (i.e. zero address). See "Minting/creating and burning/destroying rules".</li> </ul> </li> <li><code>TransferBatch</code> SHOULD be used to indicate multiple balance transfers have occurred between a <code>_from</code> and <code>_to</code> pair. <ul> <li>It MAY be emitted with a single element in the list to indicate a singular balance change in the transaction, but note that <code>TransferSingle</code> is designed for this to reduce gas consumption.</li> <li>The <code>_operator</code> argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).</li> <li>The <code>_from</code> argument MUST be the address of the holder whose balance is decreased for each entry pair in <code>_ids</code> and <code>_values</code>.</li> <li>The <code>_to</code> argument MUST be the address of the recipient whose balance is increased for each entry pair in <code>_ids</code> and <code>_values</code>.</li> <li>The <code>_ids</code> array argument MUST contain the ids of the tokens being transferred.</li> <li>The <code>_values</code> array argument MUST contain the number of token to be transferred for each corresponding entry in <code>_ids</code>.</li> <li><code>_ids</code> and <code>_values</code> MUST have the same length.</li> <li>When minting/creating tokens, the <code>_from</code> argument MUST be set to <code>0x0</code> (i.e. zero address). See "Minting/creating and burning/destroying rules".</li> <li>When burning/destroying tokens, the <code>_to</code> argument MUST be set to <code>0x0</code> (i.e. zero address). See "Minting/creating and burning/destroying rules".</li> </ul> </li> <li>The total value transferred from address <code>0x0</code> minus the total value transferred to <code>0x0</code> observed via the <code>TransferSingle</code> and <code>TransferBatch</code> events MAY be used by clients and exchanges to determine the "circulating supply" for a given token ID.</li> <li>To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the <code>TransferSingle</code> event from <code>0x0</code> to <code>0x0</code>, with the token creator as <code>_operator</code>, and a <code>_value</code> of 0.</li> <li>All <code>TransferSingle</code> and <code>TransferBatch</code> events MUST be emitted to reflect all the balance changes that have occurred before any call(s) to <code>onERC1155Received</code> or <code>onERC1155BatchReceived</code>. <ul> <li>To make sure event order is correct in the case of valid re-entry (e.g. if a receiver contract forwards tokens on receipt) state balance and events balance MUST match before calling an external contract.</li> </ul> </li> </ul> <p><em><strong>onERC1155Received rules:</strong></em></p> <ul> <li> <p>The <code>_operator</code> argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).</p> </li> <li> <p>The <code>_from</code> argument MUST be the address of the holder whose balance is decreased.</p> <ul> <li><code>_from</code> MUST be 0x0 for a mint.</li> </ul> </li> <li> <p>The <code>_id</code> argument MUST be the token type being transferred.</p> </li> <li> <p>The <code>_value</code> argument MUST be the number of tokens the holder balance is decreased by and match what the recipient balance is increased by.</p> </li> <li> <p>The <code>_data</code> argument MUST contain the information provided by the sender for the transfer with its contents unaltered.</p> <ul> <li>i.e. it MUST pass on the unaltered <code>_data</code> argument sent via the <code>safeTransferFrom</code> or <code>safeBatchTransferFrom</code> call for this transfer.</li> </ul> </li> <li> <p>The recipient contract MAY accept an increase of its balance by returning the acceptance magic value <code>bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))</code></p> <ul> <li>If the return value is <code>bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))</code> the transfer MUST be completed or MUST revert if any other conditions are not met for success.</li> </ul> </li> <li> <p>The recipient contract MAY reject an increase of its balance by calling revert.</p> <ul> <li>If the recipient contract throws/reverts the transaction MUST be reverted.</li> </ul> </li> <li> <p>If the return value is anything other than <code>bytes4(keccak256("onERC1155Received(address,address,uint256,uint256,bytes)"))</code> the transaction MUST be reverted.</p> </li> <li> <p><code>onERC1155Received</code> (and/or <code>onERC1155BatchReceived</code>) MAY be called multiple times in a single transaction and the following requirements must be met:</p> <ul> <li>All callbacks represent mutually exclusive balance changes.</li> <li>The set of all calls to <code>onERC1155Received</code> and <code>onERC1155BatchReceived</code> describes all balance changes that occurred during the transaction in the order submitted.</li> </ul> </li> <li> <p>A contract MAY skip calling the <code>onERC1155Received</code> hook function if the transfer operation is transferring the token to itself.</p> </li> </ul> <p><em><strong>onERC1155BatchReceived rules:</strong></em></p> <ul> <li> <p>The <code>_operator</code> argument MUST be the address of an account/contract that is approved to make the transfer (SHOULD be msg.sender).</p> </li> <li> <p>The <code>_from</code> argument MUST be the address of the holder whose balance is decreased.</p> <ul> <li><code>_from</code> MUST be 0x0 for a mint.</li> </ul> </li> <li> <p>The <code>_ids</code> argument MUST be the list of tokens being transferred.</p> </li> <li> <p>The <code>_values</code> argument MUST be the list of number of tokens (matching the list and order of tokens specified in <code>_ids</code>) the holder balance is decreased by and match what the recipient balance is increased by.</p> </li> <li> <p>The <code>_data</code> argument MUST contain the information provided by the sender for the transfer with its contents unaltered.</p> <ul> <li>i.e. it MUST pass on the unaltered <code>_data</code> argument sent via the <code>safeBatchTransferFrom</code> call for this transfer.</li> </ul> </li> <li> <p>The recipient contract MAY accept an increase of its balance by returning the acceptance magic value <code>bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))</code></p> <ul> <li>If the return value is <code>bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))</code> the transfer MUST be completed or MUST revert if any other conditions are not met for success.</li> </ul> </li> <li> <p>The recipient contract MAY reject an increase of its balance by calling revert.</p> <ul> <li>If the recipient contract throws/reverts the transaction MUST be reverted.</li> </ul> </li> <li> <p>If the return value is anything other than <code>bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))</code> the transaction MUST be reverted.</p> </li> <li> <p><code>onERC1155BatchReceived</code> (and/or <code>onERC1155Received</code>) MAY be called multiple times in a single transaction and the following requirements must be met:</p> <ul> <li>All callbacks represent mutually exclusive balance changes.</li> <li>The set of all calls to <code>onERC1155Received</code> and <code>onERC1155BatchReceived</code> describes all balance changes that occurred during the transaction in the order submitted.</li> </ul> </li> <li> <p>A contract MAY skip calling the <code>onERC1155BatchReceived</code> hook function if the transfer operation is transferring the token(s) to itself.</p> </li> </ul> <p><em><strong>ERC1155TokenReceiver ERC-165 rules:</strong></em></p> <ul> <li> <p>The implementation of the ERC-165 <code>supportsInterface</code> function SHOULD be 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"> 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> interfaceID </span><span class="z-keyword">==</span><span class="z-constant"> 0x01ffc9a7</span><span class="z-keyword"> ||</span><span class="z-comment"> //</span><span class="z-comment"> ERC-165 support (i.e. `bytes4(keccak256(&#39;supportsInterface(bytes4)&#39;))`).</span></span> <span class="giallo-l"><span> interfaceID </span><span class="z-keyword">==</span><span class="z-constant"> 0x4e2312e0</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> ERC-1155 `ERC1155TokenReceiver` support (i.e. `bytes4(keccak256(&quot;onERC1155Received(address,address,uint256,uint256,bytes)&quot;)) ^ bytes4(keccak256(&quot;onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)&quot;))`).</span></span> <span class="giallo-l"><span>}</span></span></code></pre></li> <li> <p>The implementation MAY differ from the above but:</p> <ul> <li>It MUST return the constant value <code>true</code> if <code>0x01ffc9a7</code> is passed through the <code>interfaceID</code> argument. This signifies ERC-165 support.</li> <li>It MUST return the constant value <code>true</code> if <code>0x4e2312e0</code> is passed through the <code>interfaceID</code> argument. This signifies ERC-1155 <code>ERC1155TokenReceiver</code> support.</li> <li>It MUST NOT consume more than 10,000 gas. <ul> <li>This keeps it below the ERC-165 requirement of 30,000 gas, reduces the gas reserve needs and minimises possible side-effects of gas exhaustion during the call.</li> </ul> </li> </ul> </li> </ul> <p><em><strong>Implementation specific transfer API rules:</strong></em></p> <ul> <li>If an implementation specific API function is used to transfer ERC-1155 token(s) to a contract, the <code>safeTransferFrom</code> or <code>safeBatchTransferFrom</code> (as appropriate) rules MUST still be followed if the receiver implements the <code>ERC1155TokenReceiver</code> interface. If it does not the non-standard implementation SHOULD revert but MAY proceed.</li> <li>An example: <ol> <li>An approved user calls a function such as <code>function myTransferFrom(address _from, address _to, uint256[] calldata _ids, uint256[] calldata _values);</code>.</li> <li><code>myTransferFrom</code> updates the balances for <code>_from</code> and <code>_to</code> addresses for all <code>_ids</code> and <code>_values</code>.</li> <li><code>myTransferFrom</code> emits <code>TransferBatch</code> with the details of what was transferred from address <code>_from</code> to address <code>_to</code>.</li> <li><code>myTransferFrom</code> checks if <code>_to</code> is a contract address and determines that it is so (if not, then the transfer can be considered successful).</li> <li><code>myTransferFrom</code> calls <code>onERC1155BatchReceived</code> on <code>_to</code> and it reverts or returns an unknown value (if it had returned <code>bytes4(keccak256("onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)"))</code> the transfer can be considered successful).</li> <li>At this point <code>myTransferFrom</code> SHOULD revert the transaction immediately as receipt of the token(s) was not explicitly accepted by the <code>onERC1155BatchReceived</code> function.</li> <li>If however <code>myTransferFrom</code> wishes to continue it MUST call <code>supportsInterface(0x4e2312e0)</code> on <code>_to</code> and if it returns the constant value <code>true</code> the transaction MUST be reverted, as it is now known to be a valid receiver and the previous acceptance step failed. <ul> <li>NOTE: You could have called <code>supportsInterface(0x4e2312e0)</code> at a previous step if you wanted to gather and act upon that information earlier, such as in a hybrid standards scenario.</li> </ul> </li> <li>If the above call to <code>supportsInterface(0x4e2312e0)</code> on <code>_to</code> reverts or returns a value other than the constant value <code>true</code> the <code>myTransferFrom</code> function MAY consider this transfer successful. <ul> <li><strong>NOTE</strong>: this MAY result in unrecoverable tokens if sent to an address that does not expect to receive ERC-1155 tokens.</li> </ul> </li> </ol> </li> <li>The above example is not exhaustive but illustrates the major points (and shows that most are shared with <code>safeTransferFrom</code> and <code>safeBatchTransferFrom</code>): <ul> <li>Balances that are updated MUST have equivalent transfer events emitted.</li> <li>A receiver address has to be checked if it is a contract and if so relevant <code>ERC1155TokenReceiver</code> hook function(s) have to be called on it.</li> <li>Balances (and events associated) that are referenced in a call to an <code>ERC1155TokenReceiver</code> hook MUST be updated (and emitted) before the <code>ERC1155TokenReceiver</code> hook is called.</li> <li>The return values of the <code>ERC1155TokenReceiver</code> hook functions that are called MUST be respected if they are implemented.</li> <li>Only non-standard transfer functions MAY allow tokens to be sent to a recipient contract that does NOT implement the necessary <code>ERC1155TokenReceiver</code> hook functions. <code>safeTransferFrom</code> and <code>safeBatchTransferFrom</code> MUST revert in that case (unless it is a hybrid standards implementation see "Backwards Compatibility").</li> </ul> </li> </ul> <p><em><strong>Minting/creating and burning/destroying rules:</strong></em></p> <ul> <li>A mint/create operation is essentially a specialized transfer and MUST follow these rules: <ul> <li>To broadcast the existence of a token ID with no initial balance, the contract SHOULD emit the <code>TransferSingle</code> event from <code>0x0</code> to <code>0x0</code>, with the token creator as <code>_operator</code>, and a <code>_value</code> of 0.</li> <li>The "TransferSingle and TransferBatch event rules" MUST be followed as appropriate for the mint(s) (i.e. singles or batches) however the <code>_from</code> argument MUST be set to <code>0x0</code> (i.e. zero address) to flag the transfer as a mint to contract observers. <ul> <li><strong>NOTE:</strong> This includes tokens that are given an initial balance in the contract. The balance of the contract MUST also be able to be determined by events alone meaning initial contract balances (for eg. in construction) MUST emit events to reflect those balances too.</li> </ul> </li> </ul> </li> <li>A burn/destroy operation is essentially a specialized transfer and MUST follow these rules: <ul> <li>The "TransferSingle and TransferBatch event rules" MUST be followed as appropriate for the burn(s) (i.e. singles or batches) however the <code>_to</code> argument MUST be set to <code>0x0</code> (i.e. zero address) to flag the transfer as a burn to contract observers.</li> <li>When burning/destroying you do not have to actually transfer to <code>0x0</code> (that is impl specific), only the <code>_to</code> argument in the event MUST be set to <code>0x0</code> as above.</li> </ul> </li> <li>The total value transferred from address <code>0x0</code> minus the total value transferred to <code>0x0</code> observed via the <code>TransferSingle</code> and <code>TransferBatch</code> events MAY be used by clients and exchanges to determine the "circulating supply" for a given token ID.</li> <li>As mentioned above mint/create and burn/destroy operations are specialized transfers and so will likely be accomplished with custom transfer functions rather than <code>safeTransferFrom</code> or <code>safeBatchTransferFrom</code>. If so the "Implementation specific transfer API rules" section would be appropriate. <ul> <li>Even in a non-safe API and/or hybrid standards case the above event rules MUST still be adhered to when minting/creating or burning/destroying.</li> </ul> </li> <li>A contract MAY skip calling the <code>ERC1155TokenReceiver</code> hook function(s) if the mint operation is transferring the token(s) to itself. In all other cases the <code>ERC1155TokenReceiver</code> rules MUST be followed as appropriate for the implementation (i.e. safe, custom and/or hybrid).</li> </ul> <h5 id="a-solidity-example-of-the-keccak256-generated-constants-for-the-various-magic-values-these-may-be-used-by-implementation">A solidity example of the keccak256 generated constants for the various magic values (these MAY be used by implementation):</h5> <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"> constant</span><span class="z-storage z-type"> public</span><span> ERC1155_ERC165 </span><span class="z-keyword">=</span><span class="z-constant"> 0xd9b67a26</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> ERC-165 identifier for the main token standard.</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"> public</span><span> ERC1155_ERC165_TOKENRECEIVER </span><span class="z-keyword">=</span><span class="z-constant"> 0x4e2312e0</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> ERC-165 identifier for the `ERC1155TokenReceiver` support (i.e. `bytes4(keccak256(&quot;onERC1155Received(address,address,uint256,uint256,bytes)&quot;)) ^ bytes4(keccak256(&quot;onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)&quot;))`).</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"> public</span><span> ERC1155_ACCEPTED </span><span class="z-keyword">=</span><span class="z-constant"> 0xf23a6e61</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Return value from `onERC1155Received` call if a contract accepts receipt (i.e `bytes4(keccak256(&quot;onERC1155Received(address,address,uint256,uint256,bytes)&quot;))`).</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"> public</span><span> ERC1155_BATCH_ACCEPTED </span><span class="z-keyword">=</span><span class="z-constant"> 0xbc197c81</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Return value from `onERC1155BatchReceived` call if a contract accepts receipt (i.e `bytes4(keccak256(&quot;onERC1155BatchReceived(address,address,uint256[],uint256[],bytes)&quot;))`).</span></span></code></pre><h3 id="metadata">Metadata</h3> <p>The URI value allows for ID substitution by clients. If the string <code>{id}</code> exists in any URI, clients MUST replace this with the actual token ID in hexadecimal form. This allows for a large number of tokens to use the same on-chain string by defining a URI once, for that large number of tokens.</p> <ul> <li>The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: <code>[0-9a-f]</code> with no 0x prefix.</li> <li>The string format of the substituted hexadecimal ID MUST be leading zero padded to 64 hex characters length if necessary.</li> </ul> <p>Example of such a URI: <code>https://token-cdn-domain/{id}.json</code> would be replaced with <code>https://token-cdn-domain/000000000000000000000000000000000000000000000000000000000004cce0.json</code> if the client is referring to token ID 314592/0x4CCE0.</p> <h4 id="metadata-extensions">Metadata Extensions</h4> <p>The optional <code>ERC1155Metadata_URI</code> extension can be identified with the <a href="https://wg-eips.ritovision.com/165/">ERC-165 Standard Interface Detection</a>.</p> <p>If the optional <code>ERC1155Metadata_URI</code> extension is included:</p> <ul> <li>The ERC-165 <code>supportsInterface</code> function MUST return the constant value <code>true</code> if <code>0x0e89341c</code> is passed through the <code>interfaceID</code> argument.</li> <li><em>Changes</em> to the URI MUST emit the <code>URI</code> event if the change can be expressed with an event (i.e. it isn't dynamic/programmatic). <ul> <li>An implementation MAY emit the <code>URI</code> event during a mint operation but it is NOT mandatory. An observer MAY fetch the metadata uri at mint time from the <code>uri</code> function if it was not emitted.</li> </ul> </li> <li>The <code>uri</code> function SHOULD be used to retrieve values if no event was emitted.</li> <li>The <code>uri</code> function MUST return the same value as the latest event for an <code>_id</code> if it was emitted.</li> <li>The <code>uri</code> function MUST NOT be used to check for the existence of a token as it is possible for an implementation to return a valid string even if the token does not exist.</li> </ul> <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.9</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 0x0e89341c.</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"> ERC1155Metadata_URI</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"> A distinct Uniform Resource Identifier (URI) for a given token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> URIs are defined in RFC 3986.</span></span> <span class="giallo-l"><span class="z-comment"> The URI MUST point to a JSON file that conforms to the &quot;ERC-1155 Metadata URI JSON Schema&quot;. </span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> URI</span><span class="z-comment"> string</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"> uri</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">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="erc-1155-metadata-uri-json-schema">ERC-1155 Metadata URI JSON Schema</h4> <p>This JSON schema is loosely based on the "ERC721 Metadata JSON Schema", but includes optional formatting to allow for ID substitution by clients. If the string <code>{id}</code> exists in any JSON value, it MUST be replaced with the actual token ID, by all client software that follows this standard.</p> <ul> <li>The string format of the substituted hexadecimal ID MUST be lowercase alphanumeric: <code>[0-9a-f]</code> with no 0x prefix.</li> <li>The string format of the substituted hexadecimal ID MUST be leading zero padded to 64 hex characters length if necessary.</li> </ul> <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">Token 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 token 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">decimals</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">The number of decimal places that the token amount should display - e.g. 18, means to divide the token amount by 1000000000000000000 to get its user representation.</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 token 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 token 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">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">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">Arbitrary properties. Values may be strings, numbers, object or arrays.</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>An example of an ERC-1155 Metadata JSON file follows. The properties array proposes some SUGGESTED formatting for token-specific display properties and metadata.</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">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:</span><span class="z-constant">\/</span><span class="z-constant">\/</span><span class="z-string">s3.amazonaws.com</span><span class="z-constant">\/</span><span class="z-string">your-bucket</span><span class="z-constant">\/</span><span class="z-string">images</span><span class="z-constant">\/</span><span class="z-string">{id}.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">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">simple_property</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">example 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">rich_property</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">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">value</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">123</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">display_value</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">123 Example 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">class</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">emphasis</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">css</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">color</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#ffffff</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">font-weight</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">bold</span><span class="z-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-decoration</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">underline</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">array_property</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">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">value</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-constant">1</span><span>,</span><span class="z-constant">2</span><span>,</span><span class="z-constant">3</span><span>,</span><span class="z-constant">4</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">class</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">emphasis</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><h5 id="localization">Localization</h5> <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> <h5 id="json-schema">JSON 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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Token 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 token 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">decimals</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">The number of decimal places that the token amount should display - e.g. 18, means to divide the token amount by 1000000000000000000 to get its user representation.</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 token 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 token 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">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">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">Arbitrary properties. Values may be strings, numbers, object or arrays.</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><h5 id="localized-sample">Localized Sample</h5> <p>Base URI:</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">Advertising Space</span><span class="z-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">Each token represents a unique Ad space in the city.</span><span class="z-punctuation z-definition z-string">&quot;</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">uri</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ipfs://QmWS1VAdMD353A6SDk9wNyvkT14kyCiZrNDYAad4w1tKqT/{locale}.json</span><span class="z-punctuation z-definition z-string">&quot;</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 class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">en</span><span class="z-punctuation z-definition z-string">&quot;</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 class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">en</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">es</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">fr</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> <p>es.json:</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">Espacio Publicitario</span><span class="z-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">Cada token representa un espacio publicitario único en la ciudad.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>fr.json:</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">Espace Publicitaire</span><span class="z-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">Chaque jeton représente un espace publicitaire unique dans la ville.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="approval">Approval</h3> <p>The function <code>setApprovalForAll</code> allows an operator to manage one's entire set of tokens on behalf of the approver. To permit approval of a subset of token IDs, an interface such as <a href="https://wg-eips.ritovision.com/1761/">ERC-1761 Scoped Approval Interface</a> is suggested. The counterpart <code>isApprovedForAll</code> provides introspection into any status set by <code>setApprovalForAll</code>.</p> <p>An owner SHOULD be assumed to always be able to operate on their own tokens regardless of approval status, so should SHOULD NOT have to call <code>setApprovalForAll</code> to approve themselves as an operator before they can operate on them.</p> <h2 id="rationale">Rationale</h2> <h3 id="metadata-choices">Metadata Choices</h3> <p>The <code>symbol</code> function (found in the ERC-20 and ERC-721 standards) was not included as we do not believe this is a globally useful piece of data to identify a generic virtual item / asset and are also prone to collisions. Short-hand symbols are used in tickers and currency trading, but they aren't as useful outside of that space.</p> <p>The <code>name</code> function (for human-readable asset names, on-chain) was removed from the standard to allow the Metadata JSON to be the definitive asset name and reduce duplication of data. This also allows localization for names, which would otherwise be prohibitively expensive if each language string was stored on-chain, not to mention bloating the standard interface. While this decision may add a small burden on implementers to host a JSON file containing metadata, we believe any serious implementation of ERC-1155 will already utilize JSON Metadata.</p> <h3 id="upgrades">Upgrades</h3> <p>The requirement to emit <code>TransferSingle</code> or <code>TransferBatch</code> on balance change implies that a valid implementation of ERC-1155 redeploying to a new contract address MUST emit events from the new contract address to replicate the deprecated contract final state. It is valid to only emit a minimal number of events to reflect only the final balance and omit all the transactions that led to that state. The event emit requirement is to ensure that the current state of the contract can always be traced only through events. To alleviate the need to emit events when changing contract address, consider using the proxy pattern, such as described in <a href="https://wg-eips.ritovision.com/2535/">EIP-2535</a>. This will also have the added benefit of providing a stable contract address for users.</p> <h3 id="design-decision-supporting-non-batch">Design decision: Supporting non-batch</h3> <p>The standard supports <code>safeTransferFrom</code> and <code>onERC1155Received</code> functions because they are significantly cheaper for single token-type transfers, which is arguably a common use case.</p> <h3 id="design-decision-safe-transfers-only">Design decision: Safe transfers only</h3> <p>The standard only supports safe-style transfers, making it possible for receiver contracts to depend on <code>onERC1155Received</code> or <code>onERC1155BatchReceived</code> function to be always called at the end of a transfer.</p> <h3 id="guaranteed-log-trace">Guaranteed log trace</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. The ERC-1155 standard guarantees that event logs emitted by the smart contract will provide enough data to create an accurate record of all current token balances. A database or explorer may listen to events and be able to provide indexed and categorized searches of every ERC-1155 token in the contract.</p> <h3 id="approval-1">Approval</h3> <p>The function <code>setApprovalForAll</code> allows an operator to manage one's entire set of tokens on behalf of the approver. It enables frictionless interaction with exchange and trade contracts.</p> <p>Restricting approval to a certain set of token IDs, quantities or other rules MAY be done with an additional interface or an external contract. The rationale is to keep the ERC-1155 standard as generic as possible for all use-cases without imposing a specific approval scheme on implementations that may not need it. Standard token approval interfaces can be used, such as the suggested <a href="https://wg-eips.ritovision.com/1761/">ERC-1761 Scoped Approval Interface</a> which is compatible with ERC-1155.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There have been requirements during the design discussions to have this standard be compatible with existing standards when sending to contract addresses, specifically ERC-721 at time of writing. To cater for this scenario, there is some leeway with the revert logic should a contract not implement the <code>ERC1155TokenReceiver</code> as per "Safe Transfer Rules" section above, specifically "Scenario#3 : The receiver does not implement the necessary <code>ERC1155TokenReceiver</code> interface function(s)".</p> <p>Hence in a hybrid ERC-1155 contract implementation an extra call MUST be made on the recipient contract and checked before any hook calls to <code>onERC1155Received</code> or <code>onERC1155BatchReceived</code> are made. Order of operation MUST therefore be:</p> <ol> <li>The implementation MUST call the function <code>supportsInterface(0x4e2312e0)</code> on the recipient contract, providing at least 10,000 gas.</li> <li>If the function call succeeds and the return value is the constant value <code>true</code> the implementation proceeds as a regular ERC-1155 implementation, with the call(s) to the <code>onERC1155Received</code> or <code>onERC1155BatchReceived</code> hooks and rules associated.</li> <li>If the function call fails or the return value is NOT the constant value <code>true</code> the implementation can assume the recipient contract is not an <code>ERC1155TokenReceiver</code> and follow its other standard's rules for transfers.</li> </ol> <p><em><strong>Note that a pure implementation of a single standard is recommended</strong></em> rather than a hybrid solution, but an example of a hybrid ERC-1155/ERC-721 contract is linked in the references section under implementations.</p> <p>An important consideration is that even if the tokens are sent with another standard's rules the <em><strong>ERC-1155 transfer events MUST still be emitted.</strong></em> This is so the balances can still be determined via events alone as per ERC-1155 standard rules.</p> <h2 id="usage">Usage</h2> <p>This standard can be used to represent multiple token types for an entire domain. Both fungible and non-fungible tokens can be stored in the same smart-contract.</p> <h3 id="batch-transfers">Batch Transfers</h3> <p>The <code>safeBatchTransferFrom</code> function allows for batch transfers of multiple token IDs and values. The design of ERC-1155 makes batch transfers possible without the need for a wrapper contract, as with existing token standards. This reduces gas costs when more than one token type is included in a batch transfer, as compared to single transfers with multiple transactions.</p> <p>Another advantage of standardized batch transfers is the ability for a smart contract to respond to the batch transfer in a single operation using <code>onERC1155BatchReceived</code>.</p> <p>It is RECOMMENDED that clients and wallets sort the token IDs and associated values (in ascending order) when posting a batch transfer, as some ERC-1155 implementations offer significant gas cost savings when IDs are sorted. See <a rel="external" href="https://github.com/horizon-games/multi-token-standard">Horizon Games - Multi-Token Standard</a> "packed balance" implementation for an example of this.</p> <h3 id="batch-balance">Batch Balance</h3> <p>The <code>balanceOfBatch</code> function allows clients to retrieve balances of multiple owners and token IDs with a single call.</p> <h3 id="enumerating-from-events">Enumerating from events</h3> <p>In order to keep storage requirements light for contracts implementing ERC-1155, enumeration (discovering the IDs and values of tokens) must be done using event logs. It is RECOMMENDED that clients such as exchanges and blockchain explorers maintain a local database containing the token ID, Supply, and URI at the minimum. This can be built from each TransferSingle, TransferBatch, and URI event, starting from the block the smart contract was deployed until the latest block.</p> <p>ERC-1155 contracts must therefore carefully emit <code>TransferSingle</code> or <code>TransferBatch</code> events in any instance where tokens are created, minted, transferred or destroyed.</p> <h3 id="non-fungible-tokens">Non-Fungible Tokens</h3> <p>The following strategies are examples of how you MAY mix fungible and non-fungible tokens together in the same contract. The standard does NOT mandate how an implementation must do this.</p> <h5 id="split-id-bits">Split ID bits</h5> <p>The top 128 bits of the uint256 <code>_id</code> parameter in any ERC-1155 function MAY represent the base token ID, while the bottom 128 bits MAY represent the index of the non-fungible to make it unique.</p> <p>Non-fungible tokens can be interacted with using an index based accessor into the contract/token data set. Therefore to access a particular token set within a mixed data contract and a particular non-fungible within that set, <code>_id</code> could be passed as <code>&lt;uint128: base token id&gt;&lt;uint128: index of non-fungible&gt;</code>.</p> <p>To identify a non-fungible set/category as a whole (or a fungible) you COULD just pass in the base id via the <code>_id</code> argument as <code>&lt;uint128: base token id&gt;&lt;uint128: zero&gt;</code>. If your implementation uses this technique this naturally means the index of a non-fungible SHOULD be 1-based.</p> <p>Inside the contract code the two pieces of data needed to access the individual non-fungible can be extracted with uint128(~0) and the same mask shifted by 128.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">uint256</span><span> baseTokenNFT </span><span class="z-keyword">=</span><span class="z-constant"> 12345</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 128</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint128</span><span> indexNFT </span><span class="z-keyword">=</span><span class="z-constant"> 50</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support">uint256</span><span> baseTokenFT </span><span class="z-keyword">=</span><span class="z-constant"> 54321</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 128</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name">balanceOf</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> baseTokenNFT</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Get balance of the base token for non-fungible set 12345 (this MAY be used to get balance of the user for all of this token set if the implementation wishes as a convenience).</span></span> <span class="giallo-l"><span class="z-entity z-name">balanceOf</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> baseTokenNFT </span><span class="z-keyword">+</span><span> indexNFT</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Get balance of the token at index 50 for non-fungible set 12345 (should be 1 if user owns the individual non-fungible token or 0 if they do not).</span></span> <span class="giallo-l"><span class="z-entity z-name">balanceOf</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> baseTokenFT</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Get balance of the fungible base token 54321.</span></span></code></pre> <p>Note that 128 is an arbitrary number, an implementation MAY choose how they would like this split to occur as suitable for their use case. An observer of the contract would simply see events showing balance transfers and mints happening and MAY track the balances using that information alone. For an observer to be able to determine type (non-fungible or fungible) from an ID alone they would have to know the split ID bits format on a implementation by implementation basis.</p> <p>The <a rel="external" href="https://github.com/enjin/erc-1155">ERC-1155 Reference Implementation</a> is an example of the split ID bits strategy.</p> <h5 id="natural-non-fungible-tokens">Natural Non-Fungible tokens</h5> <p>Another simple way to represent non-fungibles is to allow a maximum value of 1 for each non-fungible token. This would naturally mirror the real world, where unique items have a quantity of 1 and fungible items have a quantity greater than 1.</p> <h2 id="references">References</h2> <p><strong>Standards</strong></p> <ul> <li><a href="https://wg-eips.ritovision.com/721/">ERC-721 Non-Fungible Token Standard</a></li> <li><a href="https://wg-eips.ritovision.com/165/">ERC-165 Standard Interface Detection</a></li> <li><a href="https://wg-eips.ritovision.com/1538/">ERC-1538 Transparent Contract Standard</a></li> <li><a rel="external" href="https://json-schema.org/">JSON Schema</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>Implementations</strong></p> <ul> <li><a rel="external" href="https://github.com/enjin/erc-1155">ERC-1155 Reference Implementation</a></li> <li><a rel="external" href="https://github.com/horizon-games/multi-token-standard">Horizon Games - Multi-Token Standard</a></li> <li><a rel="external" href="https://enjincoin.io">Enjin Coin</a> (<a rel="external" href="https://github.com/enjin">GitHub</a>)</li> <li><a rel="external" href="https://github.com/pixowl/thesandbox-contracts/tree/master/src/Asset">The Sandbox - Dual ERC-1155/721 Contract</a></li> </ul> <p><strong>Articles &amp; Discussions</strong></p> <ul> <li><a rel="external" href="https://github.com/ethereum/EIPs/issues/1155">GitHub - Original Discussion Thread</a></li> <li><a rel="external" href="https://blog.enjincoin.io/erc-1155-the-crypto-item-standard-ac9cf1c5a226">ERC-1155 - The Crypto Item Standard</a></li> <li><a rel="external" href="https://medium.com/horizongames/going-beyond-erc20-and-erc721-9acebd4ff6ef">Here Be Dragons - Going Beyond ERC-20 and ERC-721 To Reduce Gas Cost by ~80%</a></li> <li><a rel="external" href="https://blockonomi.com/erc1155-gaming-token/">Blockonomi - Ethereum ERC-1155 Token Perfect for Online Games, Possibly More</a></li> <li><a rel="external" href="https://blockgeeks.com/erc-1155-token/">Beyond Gaming - Exploring the Utility of ERC-1155 Token Standard!</a></li> <li><a rel="external" href="https://medium.com/sandbox-game/erc-1155-a-new-standard-for-the-sandbox-c95ee1e45072">ERC-1155: A new standard for The Sandbox</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-06-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alexey Akhunovhttps://github.com/AlexeyAkhunov Moody Salemhttps://github.com/moodysalem https://wg-eips.ritovision.com/1153/

Add opcodes for manipulating state that behaves almost identically to storage but is discarded after every transaction

<h2 id="abstract">Abstract</h2> <p>This proposal introduces transient storage opcodes, which manipulate state that behaves identically to storage, except that transient storage is discarded after every transaction, and <code>TSTORE</code> is not subject to the gas stipend check as defined in <a href="https://wg-eips.ritovision.com/2200/">EIP-2200</a>. In other words, the values of transient storage are never deserialized from storage or serialized to storage. Thus transient storage is cheaper since it never requires disk access. Transient storage is accessible to smart contracts via 2 new opcodes, <code>TLOAD</code> and <code>TSTORE</code>, where “T” stands for "transient:"</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>TLOAD (0x5c)</span></span> <span class="giallo-l"><span>TSTORE (0x5d)</span></span></code></pre><h2 id="motivation">Motivation</h2> <p>Running a transaction in Ethereum can generate multiple nested frames of execution, each created by <code>CALL</code> (or similar) instructions. Contracts can be re-entered during the same transaction, in which case there are more than one frame belonging to one contract. Currently, these frames can communicate in two ways: via inputs/outputs passed via <code>CALL</code> instructions, and via storage updates. If there is an intermediate frame belonging to another untrusted contract, communication via inputs/outputs is not secure. Notable example is a reentrancy lock which cannot rely on the intermediate frame to pass through the state of the lock. Communication via storage (<code>SSTORE</code>/<code>SLOAD</code>) is costly. Transient storage is a dedicated and gas efficient solution to the problem of inter frame communication.</p> <p>Storage refunds accumulated due to inter frame communication are also limited to 20% of gas spent by a transaction due to <a href="https://wg-eips.ritovision.com/3529/">EIP-3529</a> (introduced in the London hard fork). This greatly reduces the refunds for transiently-set storage slots in otherwise low-cost transactions. For example, in order to receive the full refund of one re-entrancy lock, the transaction must spend ~80k gas on other operations.</p> <p>Language support could be added in relatively easy way. For example, in Solidity, a qualifier <code>transient</code> can be introduced (similar to the existing qualifiers <code>memory</code> and <code>storage</code>, and Java's own <code>transient</code> keyword with a similar meaning). Since the addressing scheme of <code>TSTORE</code> and <code>TLOAD</code> is the same as for <code>SSTORE</code> and <code>SLOAD</code>, code generation routines that exist for storage variables, can be easily generalised to also support transient storage.</p> <p>Potential use cases enabled or improved by this EIP include:</p> <ol> <li>Reentrancy locks</li> <li>On-chain computable CREATE2 addresses: constructor arguments are read from the factory contract instead of passed as part of init code hash</li> <li>Single transaction <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> approvals, e.g. <code>#temporaryApprove(address spender, uint256 amount)</code></li> <li>Fee-on-transfer contracts: pay a fee to a token contract to unlock transfers for the duration of a transaction</li> <li>"Till" pattern: allowing users to perform all actions as part of a callback, and checking the "till" is balanced at the end</li> <li>Proxy call metadata: pass additional metadata to an implementation contract without using calldata, e.g. values of immutable proxy constructor arguments</li> </ol> <p>These opcodes are more efficient to execute than the <code>SSTORE</code> and <code>SLOAD</code> opcodes because the original value never needs to be loaded from storage (i.e. is always 0). The gas accounting rules are also simpler, since no refunds are required.</p> <h2 id="specification">Specification</h2> <p>Two new opcodes are added to EVM, <code>TLOAD</code> (<code>0x5c</code>) and <code>TSTORE</code> (<code>0x5d</code>). (Note that previous drafts of this EIP specified the values <code>0xb3</code> and <code>0xb4</code> for <code>TLOAD</code> and <code>TSTORE</code> respectively to avoid conflict with other EIPs. The conflict has since been removed.)</p> <p>They use the same arguments on stack as <code>SLOAD</code> (<code>0x54</code>) and <code>SSTORE</code> (<code>0x55</code>).</p> <p><code>TLOAD</code> pops one 32-byte word from the top of the stack, treats this value as the address, fetches 32-byte word from the transient storage at that address, and pushes the value on top of the stack.</p> <p><code>TSTORE</code> pops two 32-byte words from the top of the stack. The word on the top is the address, and the next is the value. <code>TSTORE</code> saves the value at the given address in the transient storage.</p> <p>Addressing is the same as <code>SLOAD</code> and <code>SSTORE</code>. i.e. each 32-byte address points to a unique 32-byte word.</p> <p>Gas cost for <code>TSTORE</code> is the same as a warm <code>SSTORE</code> of a dirty slot (i.e. original value is not new value and is not current value, currently 100 gas), and gas cost of <code>TLOAD</code> is the same as a hot <code>SLOAD</code> (value has been read before, currently 100 gas). Gas cost cannot be on par with memory access due to transient storage's interactions with reverts.</p> <p>All values in transient storage are discarded at the end of the transaction.</p> <p>Transient storage is private to the contract that owns it, in the same way as persistent storage. Only owning contract frames may access their transient storage. And when they do, all the frames access the same transient store, in the same way as persistent storage, but unlike memory.</p> <p>When transient storage is used in the context of <code>DELEGATECALL</code> or <code>CALLCODE</code>, then the owning contract of the transient storage is the contract that issued <code>DELEGATECALL</code> or <code>CALLCODE</code> instruction (the caller) as with persistent storage. When transient storage is used in the context of <code>CALL</code> or <code>STATICCALL</code>, then the owning contract of the transient storage is the contract that is the target of the <code>CALL</code> or <code>STATICCALL</code> instruction (the callee).</p> <p>If a frame reverts, all writes to transient storage that took place between entry to the frame and the return are reverted, including those that took place in inner calls. This mimics the behavior of persistent storage.</p> <p>If the <code>TSTORE</code> opcode is called within the context of a <code>STATICCALL</code>, it will result in an exception instead of performing the modification. <code>TLOAD</code> is allowed within the context of a <code>STATICCALL</code>.</p> <p>The behavior of the opcodes for transient storage differs from the opcodes for storage in that <code>TSTORE</code> does not require <em>gasleft</em>, as defined in <a href="https://wg-eips.ritovision.com/2200/">EIP-2200</a>, to be less than or equal to the gas stipend (currently 2,300).</p> <h2 id="rationale">Rationale</h2> <p>Another option to solve the problem of inter-frame communication is repricing the <code>SSTORE</code> and <code>SLOAD</code> opcodes to be cheaper for the transient storage use case. This has already been done as of <a href="https://wg-eips.ritovision.com/2200/">EIP-2200</a>. However, <a href="https://wg-eips.ritovision.com/3529/">EIP-3529</a> reduced the maximum refund to only 20% of the transaction gas cost, which means the use of transient storage is severely limited.</p> <p>Another approach is to keep the refund counter for transient storage separate from the refund counter for other storage uses, and remove the refund cap for transient storage. However, that approach is more complex to implement and understand. For example, the 20% refund cap must be applied to the gas used <em>after</em> subtracting the uncapped gas refund. Otherwise, the refund amount available subject to the 20% refund cap could be increased by executing transient storage writes. Thus it is preferable to have a separate mechanism that does not interact with the refund counter. Future hard forks can remove the complex refund behavior meant to support the transient storage use case, encouraging migration to contracts that are more efficient for the Ethereum clients to execute.</p> <p>There is a known objection to the word-addressed storage-like interface of the <code>TSTORE</code> and <code>TLOAD</code> opcodes since transient storage is more akin to memory than storage in lifecycle. A byte-addressed memory-like interface is another option. The storage-like word-addressed interface is preferred due to the usefulness of mappings in combination with the transaction-scoped memory region. Often times, you will need to keep transient state with arbitrary keys, such as in the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> temporary approval use case which uses a mapping of <code>(owner, spender)</code> to <code>allowance</code>. Mappings are difficult to implement using linear memory, and linear memory must also have dynamic gas costs. It is also more complicated to handle reverts with a linear memory. It is possible to have a memory-like interface while the underlying implementation uses a map to allow for storage in arbitrary offsets, but this would result in a third memory-storage hybrid interface that would require new code paths in compilers.</p> <p>Some think that a unique transaction identifier may obviate the need for transient storage as described in this EIP. This is a misconception: a transaction identifier used in combination with regular storage has all the same issues that motivate this EIP. The two features are orthogonal.</p> <p>Relative cons of this transient storage EIP:</p> <ul> <li>Does not address transient usages of storage in existing contracts</li> <li>New code in the clients</li> <li>New concept for the yellow paper (more to update)</li> </ul> <p>Relative pros of this transient storage EIP:</p> <ul> <li>Transient storage opcodes are considered separately in protocol upgrades and not inadvertently broken (e.g. <a href="https://wg-eips.ritovision.com/3529/">EIP-3529</a>)</li> <li>Clients do not need to load the original value</li> <li>No upfront gas cost to account for non-transient writes</li> <li>Does not change the semantics of the existing operations</li> <li>No need to clear storage slots after usage</li> <li>Simpler gas accounting rules</li> <li>Future storage designs (e.g. Verkle tree) do not need to account for transient storage refunds</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a hard fork to implement.</p> <p>Since this EIP does not change behavior of any existing opcodes, it is backwards compatible with all existing smart contracts.</p> <h2 id="test-cases">Test Cases</h2> <p>A test suite for this EIP can be found <a rel="external" href="https://github.com/ethereum/execution-spec-tests/tree/1983444bbe1a471886ef7c0e82253ffe2a4053e1/tests/cancun/eip1153_tstore">here</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Because the transient storage must behave almost identically to storage within the context of a single transaction with regards to revert behavior, it is necessary to be able to revert to a previous state of transient storage within a transaction. At the same time reverts are exceptional cases and loads, stores and returns should be cheap.</p> <p>A map of current state plus a journal of all changes and a list of checkpoints is recommended. This has the following time complexities:</p> <ul> <li>On entry to a call frame, a call marker is added to the list - <code>O(1)</code></li> <li>New values are written to the current state, and the previous value is written to the journal - <code>O(1)</code></li> <li>When a call exits successfully, the marker to the journal index of when that call was entered is discarded - <code>O(1)</code></li> <li>On revert all entries are reverted up to the last checkpoint, in reverse - <code>O(N)</code> where <code>N</code> = number of journal entries since last checkpoint</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"> JournalEntry</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> addr</span><span class="z-keyword">:</span><span class="z-support"> string</span></span> <span class="giallo-l"><span class="z-variable"> key</span><span class="z-keyword">:</span><span class="z-support"> string</span></span> <span class="giallo-l"><span class="z-variable"> prevValue</span><span class="z-keyword">:</span><span class="z-support"> string</span></span> <span class="giallo-l"><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"> Journal</span><span class="z-keyword"> =</span><span class="z-entity z-name"> JournalEntry</span><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"> Checkpoints</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Journal</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">length</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-storage z-type">interface</span><span class="z-entity z-name"> Current</span><span> {</span></span> <span class="giallo-l"><span> [</span><span class="z-variable">addr</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>]</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span> [</span><span class="z-variable">key</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>]</span><span class="z-keyword">:</span><span class="z-support"> string</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">const</span><span class="z-variable z-other z-constant"> EMPTY_VALUE</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 class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> TransientStorage</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"> * The current state of transient storage.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage"> private</span><span class="z-variable"> current</span><span class="z-keyword">:</span><span class="z-entity z-name"> Current</span><span class="z-keyword"> =</span><span> {</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"> * All changes are written to the journal. On revert, we apply the changes in reverse to the last checkpoint.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage"> private</span><span class="z-variable"> journal</span><span class="z-keyword">:</span><span class="z-entity z-name"> Journal</span><span class="z-keyword"> =</span><span> [</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"> * The length of the journal at the time of each checkpoint</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage"> private</span><span class="z-variable"> checkpoints</span><span class="z-keyword">:</span><span class="z-entity z-name"> Checkpoints</span><span class="z-keyword"> =</span><span> [</span><span class="z-constant">0</span><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"> * Returns the current value of the given contract address and key</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"> addr</span><span class="z-comment"> The address of the contract</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"> key</span><span class="z-comment"> The key of transient storage for the address</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage"> public</span><span class="z-entity z-name"> get</span><span>(</span><span class="z-variable">addr</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>,</span><span class="z-variable"> key</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>)</span><span class="z-keyword">:</span><span class="z-support"> string</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">current</span><span>[</span><span class="z-variable z-other">addr</span><span>]</span><span>?.</span><span>[</span><span class="z-variable z-other">key</span><span>]</span><span class="z-keyword"> ??</span><span class="z-variable z-other z-constant"> EMPTY_VALUE</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"> * Set the current value in the map</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"> addr</span><span class="z-comment"> the address of the contract for which the key is being set</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"> key</span><span class="z-comment"> the slot to set for the address</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"> value</span><span class="z-comment"> the new value of the slot to set</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage"> public</span><span class="z-entity z-name"> put</span><span>(</span><span class="z-variable">addr</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>,</span><span class="z-variable"> key</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>,</span><span class="z-variable"> value</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">journal</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> addr</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> key</span><span>,</span></span> <span class="giallo-l"><span> prevValue</span><span>:</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">get</span><span>(</span><span class="z-variable z-other">addr</span><span>,</span><span class="z-variable z-other"> key</span><span>)</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-variable z-language"> this</span><span>.</span><span class="z-variable z-other">current</span><span>[</span><span class="z-variable z-other">addr</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">current</span><span>[</span><span class="z-variable z-other">addr</span><span>]</span><span class="z-keyword"> ??</span><span> {</span><span>}</span></span> <span class="giallo-l"><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">current</span><span>[</span><span class="z-variable z-other">addr</span><span>]</span><span>[</span><span class="z-variable z-other">key</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-other"> value</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"> * Commit all the changes since the last checkpoint</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage"> public</span><span class="z-entity z-name"> commit</span><span>(</span><span>)</span><span class="z-keyword">:</span><span class="z-support"> void</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">checkpoints</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-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">Nothing to commit</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">checkpoints</span><span>.</span><span class="z-entity z-name">pop</span><span>(</span><span>)</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> The last checkpoint is discarded.</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"> * To be called whenever entering a new context. If revert is called after checkpoint, all changes made after the latest checkpoint are reverted.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage"> public</span><span class="z-entity z-name"> checkpoint</span><span>(</span><span>)</span><span class="z-keyword">:</span><span class="z-support"> void</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">checkpoints</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">journal</span><span>.</span><span class="z-support z-variable">length</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"> * Revert transient storage to the state from the last call to checkpoint</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage"> public</span><span class="z-entity z-name"> revert</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"> lastCheckpoint</span><span class="z-keyword"> =</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">checkpoints</span><span>.</span><span class="z-entity z-name">pop</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">typeof</span><span class="z-variable z-other"> lastCheckpoint</span><span class="z-keyword"> ===</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">undefined</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><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">Nothing to revert</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"> 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-variable z-language"> this</span><span>.</span><span class="z-variable z-other">journal</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"> i</span><span class="z-keyword"> &gt;=</span><span class="z-variable z-other"> lastCheckpoint</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> {</span><span class="z-variable z-other z-constant">addr</span><span>,</span><span class="z-variable z-other z-constant"> key</span><span>,</span><span class="z-variable z-other z-constant"> prevValue</span><span>}</span><span class="z-keyword"> =</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">journal</span><span>[</span><span class="z-variable z-other">i</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> we can assume it exists, since it was written in the journal</span></span> <span class="giallo-l"><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">current</span><span>[</span><span class="z-variable z-other">addr</span><span>]</span><span>[</span><span class="z-variable z-other">key</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-other"> prevValue</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">journal</span><span>.</span><span class="z-entity z-name">splice</span><span>(</span><span class="z-variable z-other">lastCheckpoint</span><span>,</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">journal</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword"> -</span><span class="z-variable z-other"> lastCheckpoint</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The worst case time complexity can be produced by writing the maximum number of keys that can fit in one block, and then reverting. In this case, the client is required to do twice as many writes to apply all the entries in the journal. However, the same case applies to the state journaling implementation of existing clients, and cannot be DOS'd 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.8.13</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"> TryDOS</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> slot</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> {</span></span> <span class="giallo-l"><span> slot </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"> tryDOS</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> i </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> (</span><span class="z-variable z-language">gasleft</span><span>(</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 5000</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> unchecked</span><span> {</span></span> <span class="giallo-l"><span> slot </span><span class="z-keyword">=</span><span> i</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"> revert</span><span>(</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><code>TSTORE</code> presents a new way to allocate memory on a node with linear cost. In other words, each TSTORE allows the developer to store 32 bytes for 100 gas, excluding any other required operations to prepare the stack. Given 30 million gas, the maximum amount of memory that can be allocated using TSTORE is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>30M gas * 1 TSTORE / 100 gas * 32 bytes / 1 TSTORE * 1MB / 2^20 bytes ~= 9.15MB</span></span></code></pre> <p>Given the same amount of gas, the maximum amount of memory that can be allocated in a single context by <code>MSTORE</code> is ~3.75MB:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>30M gas = 3x + x^2 / 512 =&gt; x = ~123,169 32-byte words</span></span> <span class="giallo-l"><span>~123,169 words * 32 bytes/word * 1MB / 2^20 bytes = 3.75MB</span></span></code></pre> <p>However, if you only spend 1M gas allocating memory in each context, and make calls to reset the memory expansion cost, you can allocate ~700KB per million gas, for a total of ~20MB of memory allocated:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>1M gas = 3x + x^2 / 512 =&gt; x = ~21,872 32-byte words</span></span> <span class="giallo-l"><span>30M gas * ~21,872 words / 1M gas * 32 bytes/word * 1MB / 2^20 bytes = ~20MB</span></span></code></pre> <p>Smart contract developers should understand the lifetime of transient storage variables before use. Because transient storage is automatically cleared at the end of the transaction, smart contract developers may be tempted to avoid clearing slots as part of a call in order to save gas. However, this could prevent further interactions with the contract in the same transaction (e.g. in the case of re-entrancy locks) or cause other bugs, so smart contract developers should be careful to <em>only</em> leave transient storage slots with nonzero values when those slots are intended to be used by future calls within the same transaction. Otherwise, these opcodes behave exactly the same as <code>SSTORE</code> and <code>SLOAD</code>, so all the usual security considerations apply especially in regard to reentrancy risk.</p> <p>Smart contract developers may also be tempted to use transient storage as an alternative to in-memory mappings. They should be aware that transient storage is not discarded when a call returns or reverts, as is memory, and should prefer memory for these use cases so as not to create unexpected behavior on reentrancy in the same transaction. The necessarily high cost of transient storage over memory should already discourage this usage pattern. Most usages of in-memory mappings can be better implemented with key-sorted lists of entries, and in-memory mappings are rarely required in smart contracts (i.e. the author knows of no known use cases in production).</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-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Alan Luhttps://github.com/cag https://wg-eips.ritovision.com/1154/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for oracles.</p> <h2 id="abstract">Abstract</h2> <p>In order for ethereum smart contracts to interact with off-chain systems, oracles must be used. These oracles report values which are normally off-chain, allowing smart contracts to react to the state of off-chain systems. A distinction and a choice is made between push and pull based oracle systems. Furthermore, a standard interface for oracles is described here, allowing different oracle implementations to be interchangeable.</p> <h2 id="motivation">Motivation</h2> <p>The Ethereum ecosystem currently has many different oracle implementations available, but they do not provide a unified interface. Smart contract systems would be locked into a single set of oracle implementations, or they would require developers to write adapters/ports specific to the oracle system chosen in a given project.</p> <p>Beyond naming differences, there is also the issue of whether or not an oracle report-resolving transaction <em>pushes</em> state changes by calling affected contracts, or changes the oracle state allowing dependent contracts to <em>pull</em> the updated value from the oracle. These differing system semantics could introduce inefficiencies when adapting between them.</p> <p>Ultimately, the value in different oracle systems comes from their underlying resolution mechanics, and points where these systems are virtually identical should be standardized.</p> <p>These oracles may be used for answering questions about "real-world events", where each ID can be correlated with a specification of a question and its answers (so most likely for prediction markets, basically).</p> <p>Another use case could be for decision-making processes, where the results given by the oracle represent decisions made by the oracle (e.g. futarchies). DAOs may require their use in decision making processes.</p> <p>Both the ID and the results are intentionally unstructured so that things like time series data (via splitting the ID) and different sorts of results (like one of a few, any subset of up to 256, or some value in a range with up to 256 bits of granularity) can be represented.</p> <h2 id="specification">Specification</h2> <dl> <dt>Oracle</dt> <dd>An entity which reports data to the blockchain.</dd> <dt>Oracle consumer</dt> <dd>A smart contract which receives data from an oracle.</dd> <dt>ID</dt> <dd>A way of indexing the data which an oracle reports. May be derived from or tied to a question for which the data provides the answer.</dd> <dt>Result</dt> <dd>Data associated with an id which is reported by an oracle. This data oftentimes will be the answer to a question tied to the id. Other equivalent terms that have been used include: answer, data, outcome.</dd> <dt>Report</dt> <dd>A pair (ID, result) which an oracle sends to an oracle consumer.</dd> </dl> <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"> OracleConsumer</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> receiveResult</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> id</span><span>,</span><span class="z-support"> bytes</span><span class="z-variable"> result</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>receiveResult</code> MUST revert if the <code>msg.sender</code> is not an oracle authorized to provide the <code>result</code> for that <code>id</code>.</p> <p><code>receiveResult</code> MUST revert if <code>receiveResult</code> has been called with the same <code>id</code> before.</p> <p><code>receiveResult</code> MAY revert if the <code>id</code> or <code>result</code> cannot be handled by the consumer.</p> <p>Consumers MUST coordinate with oracles to determine how to encode/decode results to and from <code>bytes</code>. For example, <code>abi.encode</code> and <code>abi.decode</code> may be used to implement a codec for results in Solidity. <code>receiveResult</code> SHOULD revert if the consumer receives a unexpected result format from the oracle.</p> <p>The oracle can be any Ethereum account.</p> <h2 id="rationale">Rationale</h2> <p>The specs are currently very similar to what is implemented by ChainLink (which can use any arbitrarily-named callback) and Oraclize (which uses <code>__callback</code>).</p> <p>With this spec, the oracle <em>pushes</em> state to the consumer, which must react accordingly to the updated state. An alternate <em>pull</em>-based interface can be prescribed, as follows:</p> <h3 id="alternate-pull-based-interface">Alternate Pull-based Interface</h3> <p>Here are alternate specs loosely based on Gnosis prediction market contracts v1. Reality Check also exposes a similar endpoint (<code>getFinalAnswer</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"> Oracle</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> resultFor</span><span>(</span><span class="z-support">bytes32</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">bytes</span><span class="z-variable"> result</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>resultFor</code> MUST revert if the result for an <code>id</code> is not available yet.</p> <p><code>resultFor</code> MUST return the same result for an <code>id</code> after that result is available.</p> <h3 id="push-vs-pull">Push vs Pull</h3> <p>Note that push-based interfaces may be adapted into pull-based interfaces. Simply deploy an oracle consumer which stores the result received and implements <code>resultFor</code> accordingly.</p> <p>Similarly, every pull-based system can be adapted into a push-based system: just add a method on the oracle smart contract which takes an oracle consumer address and calls <code>receiveResult</code> on that address.</p> <p>In both cases, an additional transaction would have to be performed, so the choice to go with push or pull should be based on the dominant use case for these oracles.</p> <p>In the simple case where a single account has the authority to decide the outcome of an oracle question, there is no need to deploy an oracle contract and store the outcome on that oracle contract. Similarly, in the case where the outcome comes down to a vote, existing multisignature wallets can be used as the authorized oracle.</p> <h4 id="multiple-oracle-consumers">Multiple Oracle Consumers</h4> <p>In the case that many oracle consumers depend on a single oracle result and all these consumers expect the result to be pushed to them, the push and pull adaptations mentioned before may be combined if the pushing oracle cannot be trusted to send the same result to every consumer (in a sense, this forwards the trust to the oracle adaptor implementation).</p> <p>In a pull-based system, each of the consumers would have to be called to pull the result from the oracle contract, but in the proposed push-based system, the adapted oracle would have to be called to push the results to each of the consumers.</p> <p>Transaction-wise, both systems are roughly equivalent in efficiency in this scenario, but in the push-based system, there's a need for the oracle consumers to store the results again, whereas in the pull-based system, the consumers may continue to refer to the oracle for the results. Although this may be somewhat less efficient, requiring the consumers to store the results can also provide security guarantees, especially with regards to result immutability.</p> <h4 id="result-immutability">Result Immutability</h4> <p>In both the proposed specification and the alternate specification, results are immutable once they are determined. This is due to the expectation that typical consumers will require results to be immutable in order to determine a resulting state consistently. With the proposed push-based system, the consumer enforces the result immutability requirement, whereas in the alternate pull-based system, either the oracle would have to be trusted to implement the spec correctly and enforce the immutability requirement, or the consumer would also have to handle result immutability.</p> <p>For data which mutates over time, the <code>id</code> field may be structured to specify "what" and "when" for the data (using 128 bits to specify "when" is still safe for many millennia).</p> <h2 id="implementation">Implementation</h2> <ul> <li><a rel="external" href="https://github.com/levelkdev/tidbit">Tidbit</a> tracks this EIP.</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-07T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Mudgehttps://github.com/mudgen Dan Finlaydan@danfinlay.com https://wg-eips.ritovision.com/173/

A standard interface for ownership of contracts

<h2 id="abstract">Abstract</h2> <p>This specification defines standard functions for owning or controlling a contract.</p> <p>An implementation allows reading the current owner (<code>owner() returns (address)</code>) and transferring ownership (<code>transferOwnership(address newOwner)</code>) along with a standardized event for when ownership is changed (<code>OwnershipTransferred(address indexed previousOwner, address indexed newOwner)</code>).</p> <h2 id="motivation">Motivation</h2> <p>Many smart contracts require that they be owned or controlled in some way. For example to withdraw funds or perform administrative actions. It is so common that the contract interface used to handle contract ownership should be standardized to allow compatibility with user interfaces and contracts that manage contracts.</p> <p>Here are some examples of kinds of contracts and applications that can benefit from this standard:</p> <ol> <li>Exchanges that buy/sell/auction ethereum contracts. This is only widely possible if there is a standard for getting the owner of a contract and transferring ownership.</li> <li>Contract wallets that hold the ownership of contracts and that can transfer the ownership of contracts.</li> <li>Contract registries. It makes sense for some registries to only allow the owners of contracts to add/remove their contracts. A standard must exist for these contract registries to verify that a contract is being submitted by the owner of it before accepting it.</li> <li>User interfaces that show and transfer ownership of contracts.</li> </ol> <h2 id="specification">Specification</h2> <p>Every ERC-173 compliant contract must implement the <code>ERC173</code> interface. Contracts should also implement <code>ERC165</code> for the ERC-173 interface.</p> <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"> @title</span><span class="z-comment"> ERC-173 Contract Ownership 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 0x7f5828d0</span></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"> 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></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"> @dev</span><span class="z-comment"> Set _newOwner to address(0) to renounce any ownership.</span></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></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. </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 <code>owner()</code> function may be implemented as <code>pure</code> or <code>view</code>.</p> <p>The <code>transferOwnership(address _newOwner)</code> function may be implemented as <code>public</code> or <code>external</code>.</p> <p>To renounce any ownership of a contract set <code>_newOwner</code> to the zero address: <code>transferOwnership(address(0))</code>. If this is done then a contract is no longer owned by anybody.</p> <p>The OwnershipTransferred event should be emitted when a contract is created.</p> <h2 id="rationale">Rationale</h2> <p>Key factors influencing the standard:</p> <ul> <li>Keeping the number of functions in the interface to a minimum to prevent contract bloat.</li> <li>Backwards compatibility with existing contracts.</li> <li>Simplicity</li> <li>Gas efficient</li> </ul> <p>Several ownership schemes were considered. The scheme chosen in this standard was chosen because of its simplicity, low gas cost and backwards compatibility with existing contracts.</p> <p>Here are other schemes that were considered:</p> <ol> <li><strong>Associating an Ethereum Name Service (ENS) domain name with a contract.</strong> A contract's <code>owner()</code> function could look up the owner address of a particular ENS name and use that as the owning address of the contract. Using this scheme a contract could be transferred by transferring the ownership of the ENS domain name to a different address. Short comings to this approach are that it is not backwards compatible with existing contracts and requires gas to make external calls to ENS related contracts to get the owner address.</li> <li><strong>Associating an ERC721-based non-fungible token (NFT) with a contract.</strong> Ownership of a contract could be tied to the ownership of an NFT. The benefit of this approach is that the existing ERC721-based infrastructure could be used to sell/buy/auction contracts. Short comings to this approach are additional complexity and infrastructure required. A contract could be associated with a particular NFT but the NFT would not track that it had ownership of a contract unless it was programmed to track contracts. In addition handling ownership of contracts this way is not backwards compatible.</li> </ol> <p>This standard does not exclude the above ownership schemes or other schemes from also being implemented in the same contract. For example a contract could implement this standard and also implement the other schemes so that ownership could be managed and transferred in multiple ways. This standard does provide a simple ownership scheme that is backwards compatible, is light-weight and simple to implement, and can be widely adopted and depended on.</p> <p>This standard can be (and has been) extended by other standards to add additional ownership functionality.</p> <h2 id="security-considerations">Security Considerations</h2> <p>If the address returned by <code>owner()</code> is an externally owned account then its private key must not be lost or compromised.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Many existing contracts already implement 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> 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-06-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 g. nicholas d’andreahttps://github.com/gnidan Piper Merriamhttps://github.com/pipermerriam Nick Gheorghitahttps://github.com/njgheorghita Danny Ryanhttps://github.com/djrtwo https://wg-eips.ritovision.com/1123/ <p>This ERC has been abandoned in favor of the EthPM V3 smart contract packaging standard defined in <a href="https://wg-eips.ritovision.com/2678/">ERC-2678</a></p> <h1 id="simple-summary">Simple Summary</h1> <p>A data format describing a smart contract software package.</p> <h1 id="abstract">Abstract</h1> <p>This EIP defines a data format for <em>package manifest</em> documents, representing a package of one or more smart contracts, optionally including source code and any/all deployed instances across multiple networks. Package manifests are minified JSON objects, to be distributed via content addressable storage networks, such as IPFS.</p> <p>This document presents a natural language description of a formal specification for version <strong>2</strong> of this format.</p> <h1 id="motivation">Motivation</h1> <p>This standard aims to encourage the Ethereum development ecosystem towards software best practices around code reuse. By defining an open, community-driven package data format standard, this effort seeks to provide support for package management tools development by offering a general-purpose solution that has been designed with observed common practices in mind.</p> <p>As version 2 of this specification, this standard seeks to address a number of areas of improvement found for the previous version (defined in <a href="https://wg-eips.ritovision.com/190/">EIP-190</a>). This version:</p> <ul> <li> <p>Generalizes storage URIs to represent any content addressable URI scheme, not only IPFS.</p> </li> <li> <p>Renames <em>release lockfile</em> to <em>package manifest</em>.</p> </li> <li> <p>Adds support for languages other than Solidity by generalizing the compiler information format.</p> </li> <li> <p>Redefines link references to be more flexible, to represent arbitrary gaps in bytecode (besides only addresses), in a more straightforward way.</p> </li> <li> <p>Forces format strictness, requiring that package manifests contain no extraneous whitespace, and sort object keys in alphabetical order, to prevent hash mismatches.</p> </li> </ul> <div id="package-specification"></div> <h1 id="specification">Specification</h1> <p>This document defines the specification for an EthPM package manifest. A package manifest provides metadata about a <a href="https://wg-eips.ritovision.com/1123/#term-package">Package</a>, and in most cases should provide sufficient information about the packaged contracts and its dependencies to do bytecode verification of its contracts.</p> <blockquote> <p><strong>Note</strong></p> <p>A <a rel="external" href="https://ethpm.github.io/ethpm-spec">hosted version</a> of this specification is available via GitHub Pages. This EIP and the hosted HTML document were both autogenerated from the same documentation source.</p> </blockquote> <h2 id="guiding-principles">Guiding Principles</h2> <p>This specification makes the following assumptions about the document lifecycle.</p> <ol> <li> <p>Package manifests are intended to be generated programmatically by package management software as part of the release process.</p> </li> <li> <p>Package manifests will be consumed by package managers during tasks like installing package dependencies or building and deploying new releases.</p> </li> <li> <p>Package manifests will typically <strong>not</strong> be stored alongside the source, but rather by package registries <em>or</em> referenced by package registries and stored in something akin to IPFS.</p> </li> </ol> <h2 id="conventions">Conventions</h2> <h3 id="rfc2119">RFC2119</h3> <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> <ul> <li><a rel="external" href="https://www.ietf.org/rfc/rfc2119.txt">https://www.ietf.org/rfc/rfc2119.txt</a></li> </ul> <h3 id="prefixed-vs-unprefixed">Prefixed vs Unprefixed</h3> <p>A <a href="https://wg-eips.ritovision.com/1123/#term-prefixed">prefixed</a> hexadecimal value begins with <code>0x</code>. <a href="https://wg-eips.ritovision.com/1123/#term-unprefixed">Unprefixed</a> values have no prefix. Unless otherwise specified, all hexadecimal values <strong>should</strong> be represented with the <code>0x</code> prefix.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Prefixed</p></td> <td><p><code>0xdeadbeef</code></p></td> </tr> <tr class="even"> <td><p>Unprefixed</p></td> <td><p><code>deadbeef</code></p></td> </tr> </tbody> </table> <h2 id="document-format">Document Format</h2> <p>The canonical format is a single JSON object. Packages <strong>must</strong> conform to the following serialization rules.</p> <ul> <li> <p>The document <strong>must</strong> be tightly packed, meaning no linebreaks or extra whitespace.</p> </li> <li> <p>The keys in all objects must be sorted alphabetically.</p> </li> <li> <p>Duplicate keys in the same object are invalid.</p> </li> <li> <p>The document <strong>must</strong> use <a rel="external" href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a> encoding.</p> </li> <li> <p>The document <strong>must</strong> not have a trailing newline.</p> </li> </ul> <h2 id="document-specification">Document Specification</h2> <p>The following fields are defined for the package. Custom fields <strong>may</strong> be included. Custom fields <strong>should</strong> be prefixed with <code>x-</code> to prevent name collisions with future versions of the specification.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>See Also</p></td> <td><p>Formalized (<a href="https://json-schema.org">JSON-Schema</a>) version of this specification: <a href="https://github.com/ethpm/ethpm-spec/tree/v2.0.0/spec/package.spec.json">package.spec.json</a></p></td> </tr> <tr class="even"> <td><p>Jump To</p></td> <td><p><a href="#definitions">Definitions</a></p></td> </tr> </tbody> </table> <div id="manifest-version"></div> <h3 id="ethpm-manifest-version-manifest-version">EthPM Manifest Version: <code>manifest_version</code></h3> <p>The <code>manifest_version</code> field defines the specification version that this document conforms to. Packages <strong>must</strong> include this field.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>Yes</p></td> </tr> <tr class="even"> <td><p>Key</p></td> <td><p><code>manifest_version</code></p></td> </tr> <tr class="odd"> <td><p>Type</p></td> <td><p>String</p></td> </tr> <tr class="even"> <td><p>Allowed Values</p></td> <td><p><code>2</code></p></td> </tr> </tbody> </table> <div id="package-names"></div> <h3 id="package-name-package-name">Package Name: <code>package_name</code></h3> <p>The <code>package_name</code> field defines a human readable name for this package. Packages <strong>must</strong> include this field. Package names <strong>must</strong> begin with a lowercase letter and be comprised of only lowercase letters, numeric characters, and the dash character <code>-</code>. Package names <strong>must</strong> not exceed 214 characters in length.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>Yes</p></td> </tr> <tr class="even"> <td><p>Key</p></td> <td><p><code>package_name</code></p></td> </tr> <tr class="odd"> <td><p>Type</p></td> <td><p>String</p></td> </tr> <tr class="even"> <td><p>Format</p></td> <td><p><strong>must</strong> match the regular expression <code>^[a-zA-Z][a-zA-Z0-9_]{0,255}$</code></p></td> </tr> </tbody> </table> <h3 id="package-meta-meta">Package Meta: <code>meta</code></h3> <p>The <code>meta</code> field defines a location for metadata about the package which is not integral in nature for package installation, but may be important or convenient to have on-hand for other reasons. This field <strong>should</strong> be included in all Packages.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Key</p></td> <td><p><code>meta</code></p></td> </tr> <tr class="odd"> <td><p>Type</p></td> <td><p><a href="#package-meta-object">Package Meta Object</a></p></td> </tr> </tbody> </table> <h3 id="version-version">Version: <code>version</code></h3> <p>The <code>version</code> field declares the version number of this release. This value <strong>must</strong> be included in all Packages. This value <strong>should</strong> conform to the <a rel="external" href="https://semver.org/">semver</a> version numbering specification.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>Yes</p></td> </tr> <tr class="even"> <td><p>Key</p></td> <td><p><code>version</code></p></td> </tr> <tr class="odd"> <td><p>Type</p></td> <td><p>String</p></td> </tr> </tbody> </table> <h3 id="sources-sources">Sources: <code>sources</code></h3> <p>The <code>sources</code> field defines a source tree that <strong>should</strong> comprise the full source tree necessary to recompile the contracts contained in this release. Sources are declared in a key/value mapping.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Key</p></td> <td><p><code>sources</code></p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>Object (String: String)</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p>See Below.</p></td> </tr> </tbody> </table> <h4 id="format">Format</h4> <p>Keys <strong>must</strong> be relative filesystem paths beginning with a <code>./</code>.</p> <p>Paths <strong>must</strong> resolve to a path that is within the current working directory.</p> <p>Values <strong>must</strong> conform to <em>one of</em> the following formats.</p> <ul> <li> <p>Source string.</p> </li> <li> <p><a href="https://wg-eips.ritovision.com/1123/#term-content-addressable-uri">Content Addressable URI</a>.</p> </li> </ul> <p>When the value is a source string the key should be interpreted as a file path.</p> <ul> <li> <p>If the resulting document is a directory the key should be interpreted as a directory path.</p> </li> <li> <p>If the resulting document is a file the key should be interpreted as a file path.</p> </li> </ul> <h3 id="contract-types-contract-types">Contract Types: <code>contract_types</code></h3> <p>The <code>contract_types</code> field holds the <a href="https://wg-eips.ritovision.com/1123/#term-contract-type">Contract Types</a> which have been included in this release. <a href="https://wg-eips.ritovision.com/1123/#term-package">Packages</a> <strong>should</strong> only include contract types that can be found in the source files for this package. Packages <strong>should not</strong> include contract types from dependencies. Packages <strong>should not</strong> include abstract contracts in the contract types section of a release.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Key</p></td> <td><p><code>contract_types</code></p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>Object (String: <a href="#contract-type-object">Contract Type Object</a>)</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p>Keys <strong>must</strong> be valid <a href="#term-contract-alias">Contract Aliases</a>.</p> <p>Values <strong>must</strong> conform to the <a href="#contract-type-object">Contract Type Object</a> definition.</p></td> </tr> </tbody> </table> <h3 id="deployments-deployments">Deployments: <code>deployments</code></h3> <p>The <code>deployments</code> field holds the information for the chains on which this release has <a href="https://wg-eips.ritovision.com/1123/#term-contract-instance">Contract Instances</a> as well as the <a href="https://wg-eips.ritovision.com/1123/#term-contract-type">Contract Types</a> and other deployment details for those deployed contract instances. The set of chains defined by the <code>*BIP122 URI &lt;#bip122-uris&gt;*</code> keys for this object <strong>must</strong> be unique.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Key</p></td> <td><p><code>deployments</code></p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>Object (String: Object(String: <a href="#contract-instance-object">Contract Instance Object</a>))</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p>See Below.</p></td> </tr> </tbody> </table> <h4 id="format-1">Format</h4> <p>Keys <strong>must</strong> be a valid BIP122 URI chain definition.</p> <p>Values <strong>must</strong> be objects which conform to the following format.</p> <ul> <li> <p>Keys <strong>must</strong> be valid <a href="https://wg-eips.ritovision.com/1123/#term-contract-instance-name">Contract Instance Names</a>.</p> </li> <li> <p>Values <strong>must</strong> be a valid <a href="https://wg-eips.ritovision.com/1123/#contract-instance-object">Contract Instance Object</a>.</p> </li> </ul> <h3 id="build-dependencies-build-dependencies">Build Dependencies: <code>build_dependencies</code></h3> <p>The <code>build_dependencies</code> field defines a key/value mapping of Ethereum <a href="https://wg-eips.ritovision.com/1123/#term-package">Packages</a> that this project depends on.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Key</p></td> <td><p><code>build_dependencies</code></p></td> </tr> <tr class="odd"> <td><p>Type</p></td> <td><p>Object (String: String)</p></td> </tr> <tr class="even"> <td><p>Format</p></td> <td><p>Keys <strong>must</strong> be valid <a href="#package-names">package names</a> matching the regular expression <code>[a-z][-a-z0-9]{0,213}</code>.</p> <p>Values <strong>must</strong> be valid IPFS URIs which resolve to a valid package.</p></td> </tr> </tbody> </table> <h2 id="definitions">Definitions</h2> <p>Definitions for different objects used within the Package. All objects allow custom fields to be included. Custom fields <strong>should</strong> be prefixed with <code>x-</code> to prevent name collisions with future versions of the specification.</p> <div id="link-reference-object"></div> <h3 id="the-link-reference-object">The <em>Link Reference</em> Object</h3> <p>A <a href="https://wg-eips.ritovision.com/1123/#term-link-reference">Link Reference</a> object has the following key/value pairs. All link references are assumed to be associated with some corresponding <a href="https://wg-eips.ritovision.com/1123/#term-bytecode">Bytecode</a>.</p> <h4 id="offsets-offsets">Offsets: <code>offsets</code></h4> <p>The <code>offsets</code> field is an array of integers, corresponding to each of the start positions where the link reference appears in the bytecode. Locations are 0-indexed from the beginning of the bytes representation of the corresponding bytecode. This field is invalid if it references a position that is beyond the end of the bytecode.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>Yes</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>Array</p></td> </tr> </tbody> </table> <h4 id="length-length">Length: <code>length</code></h4> <p>The <code>length</code> field is an integer which defines the length in bytes of the link reference. This field is invalid if the end of the defined link reference exceeds the end of the bytecode.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>Yes</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>Integer</p></td> </tr> </tbody> </table> <h4 id="name-name">Name: <code>name</code></h4> <p>The <code>name</code> field is a string which <strong>must</strong> be a valid <a href="https://wg-eips.ritovision.com/1123/#term-identifier">Identifier</a>. Any link references which <strong>should</strong> be linked with the same link value <strong>should</strong> be given the same name.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>String</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p><strong>must</strong> conform to the <a href="#term-identifier">Identifier</a> format.</p></td> </tr> </tbody> </table> <div id="link-value-object"></div> <h3 id="the-link-value-object">The <em>Link Value</em> Object</h3> <p>Describes a single <a href="https://wg-eips.ritovision.com/1123/#term-link-value">Link Value</a>.</p> <p>A <strong>Link Value object</strong> is defined to have the following key/value pairs.</p> <div id="offset-offset-1"></div> <h4 id="offsets-offsets-1">Offsets: <code>offsets</code></h4> <p>The <code>offsets</code> field defines the locations within the corresponding bytecode where the <code>value</code> for this link value was written. These locations are 0-indexed from the beginning of the bytes representation of the corresponding bytecode.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>Yes</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>Integer</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p>See Below.</p></td> </tr> </tbody> </table> <p><strong>Format</strong></p> <p>Array of integers, where each integer <strong>must</strong> conform to all of the following.</p> <ul> <li> <p>greater than or equal to zero</p> </li> <li> <p>strictly less than the length of the unprefixed hexadecimal representation of the corresponding bytecode.</p> </li> </ul> <h4 id="type-type">Type: <code>type</code></h4> <p>The <code>type</code> field defines the <code>value</code> type for determining what is encoded when <a href="https://wg-eips.ritovision.com/1123/#term-linking">linking</a> the corresponding bytecode.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>Yes</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>String</p></td> </tr> <tr class="odd"> <td><p>Allowed Values</p></td> <td><p><code>&quot;literal&quot;</code> for bytecode literals</p> <p><code>&quot;reference&quot;</code> for named references to a particular <a href="#term-contract-instance">Contract Instance</a></p></td> </tr> </tbody> </table> <h4 id="value-value">Value: <code>value</code></h4> <p>The <code>value</code> field defines the value which should be written when <a href="https://wg-eips.ritovision.com/1123/#term-linking">linking</a> the corresponding bytecode.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>Yes</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>String</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p>Determined based on <code>type</code>, see below.</p></td> </tr> </tbody> </table> <p><strong>Format</strong></p> <p>For static value <em>literals</em> (e.g. address), value <strong>must</strong> be a <em>byte string</em></p> <p>To reference the address of a <a href="https://wg-eips.ritovision.com/1123/#term-contract-instance">Contract Instance</a> from the current package the value should be the name of that contract instance.</p> <ul> <li> <p>This value <strong>must</strong> be a valid contract instance name.</p> </li> <li> <p>The chain definition under which the contract instance that this link value belongs to must contain this value within its keys.</p> </li> <li> <p>This value <strong>may not</strong> reference the same contract instance that this link value belongs to.</p> </li> </ul> <p>To reference a contract instance from a <a href="https://wg-eips.ritovision.com/1123/#term-package">Package</a> from somewhere within the dependency tree the value is constructed as follows.</p> <ul> <li> <p>Let <code>[p1, p2, .. pn]</code> define a path down the dependency tree.</p> </li> <li> <p>Each of <code>p1, p2, pn</code> <strong>must</strong> be valid package names.</p> </li> <li> <p><code>p1</code> <strong>must</strong> be present in keys of the <code>build_dependencies</code> for the current package.</p> </li> <li> <p>For every <code>pn</code> where <code>n &gt; 1</code>, <code>pn</code> <strong>must</strong> be present in the keys of the <code>build_dependencies</code> of the package for <code>pn-1</code>.</p> </li> <li> <p>The value is represented by the string <code>&lt;p1&gt;:&lt;p2&gt;:&lt;...&gt;:&lt;pn&gt;:&lt;contract-instance&gt;</code> where all of <code>&lt;p1&gt;</code>, <code>&lt;p2&gt;</code>, <code>&lt;pn&gt;</code> are valid package names and <code>&lt;contract-instance&gt;</code> is a valid <a href="https://wg-eips.ritovision.com/1123/#term-contract-name">Contract Name</a>.</p> </li> <li> <p>The <code>&lt;contract-instance&gt;</code> value <strong>must</strong> be a valid <a href="https://wg-eips.ritovision.com/1123/#term-contract-instance-name">Contract Instance Name</a>.</p> </li> <li> <p>Within the package of the dependency defined by <code>&lt;pn&gt;</code>, all of the following must be satisfiable:</p> <ul> <li> <p>There <strong>must</strong> be <em>exactly</em> one chain defined under the <code>deployments</code> key which matches the chain definition that this link value is nested under.</p> </li> <li> <p>The <code>&lt;contract-instance&gt;</code> value <strong>must</strong> be present in the keys of the matching chain.</p> </li> </ul> </li> </ul> <h3 id="the-bytecode-object">The <em>Bytecode</em> Object</h3> <p>A bytecode object has the following key/value pairs.</p> <h4 id="bytecode-bytecode">Bytecode: <code>bytecode</code></h4> <p>The <code>bytecode</code> field is a string containing the <code>0x</code> prefixed hexadecimal representation of the bytecode.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>Yes</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>String</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p><code>0x</code> prefixed hexadecimal.</p></td> </tr> </tbody> </table> <h4 id="link-references-link-references">Link References: <code>link_references</code></h4> <p>The <code>link_references</code> field defines the locations in the corresponding bytecode which require <a href="https://wg-eips.ritovision.com/1123/#term-linking">linking</a>.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>Array</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p>All values <strong>must</strong> be valid <a href="#link-reference-object">Link Reference objects</a>. See also below.</p></td> </tr> </tbody> </table> <p><strong>Format</strong></p> <p>This field is considered invalid if <em>any</em> of the <a href="https://wg-eips.ritovision.com/1123/#term-link-reference">Link References</a> are invalid when applied to the corresponding <code>bytecode</code> field, <em>or</em> if any of the link references intersect.</p> <p>Intersection is defined as two link references which overlap.</p> <h4 id="link-dependencies-link-dependencies">Link Dependencies: <code>link_dependencies</code></h4> <p>The <code>link_dependencies</code> defines the <a href="https://wg-eips.ritovision.com/1123/#term-link-value">Link Values</a> that have been used to link the corresponding bytecode.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>Array</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p>All values <strong>must</strong> be valid <a href="#link-value-object">Link Value objects</a>. See also below.</p></td> </tr> </tbody> </table> <p><strong>Format</strong></p> <p>Validation of this field includes the following:</p> <ul> <li> <p>Two link value objects <strong>must not</strong> contain any of the same values for <code>offsets</code>.</p> </li> <li> <p>Each <a href="https://wg-eips.ritovision.com/1123/#link-value-object">link value object</a> <strong>must</strong> have a corresponding <a href="https://wg-eips.ritovision.com/1123/#link-reference-object">link reference object</a> under the <code>link_references</code> field.</p> </li> <li> <p>The length of the resolved <code>value</code> <strong>must</strong> be equal to the <code>length</code> of the corresponding <a href="https://wg-eips.ritovision.com/1123/#term-link-reference">Link Reference</a>.</p> </li> </ul> <div id="package-meta-object"></div> <h3 id="the-package-meta-object">The <em>Package Meta</em> Object</h3> <p>The <em>Package Meta</em> object is defined to have the following key/value pairs.</p> <h4 id="authors-authors">Authors: <code>authors</code></h4> <p>The <code>authors</code> field defines a list of human readable names for the authors of this package. Packages <strong>may</strong> include this field.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Key</p></td> <td><p><code>authors</code></p></td> </tr> <tr class="odd"> <td><p>Type</p></td> <td><p>Array (String)</p></td> </tr> </tbody> </table> <h4 id="license-license">License: <code>license</code></h4> <p>The <code>license</code> field declares the license under which this package is released. This value <strong>should</strong> conform to the <a rel="external" href="https://en.wikipedia.org/wiki/Software_Package_Data_Exchange">SPDX</a> format. Packages <strong>should</strong> include this field.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Key</p></td> <td><p><code>license</code></p></td> </tr> <tr class="odd"> <td><p>Type</p></td> <td><p>String</p></td> </tr> </tbody> </table> <h4 id="description-description">Description: <code>description</code></h4> <p>The <code>description</code> field provides additional detail that may be relevant for the package. Packages <strong>may</strong> include this field.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Key</p></td> <td><p><code>description</code></p></td> </tr> <tr class="odd"> <td><p>Type</p></td> <td><p>String</p></td> </tr> </tbody> </table> <h4 id="keywords-keywords">Keywords: <code>keywords</code></h4> <p>The <code>keywords</code> field provides relevant keywords related to this package.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Key</p></td> <td><p><code>keywords</code></p></td> </tr> <tr class="odd"> <td><p>Type</p></td> <td><p>List of Strings</p></td> </tr> </tbody> </table> <h4 id="links-links">Links: <code>links</code></h4> <p>The <code>links</code> field provides URIs to relevant resources associated with this package. When possible, authors <strong>should</strong> use the following keys for the following common resources.</p> <ul> <li> <p><code>website</code>: Primary website for the package.</p> </li> <li> <p><code>documentation</code>: Package Documentation</p> </li> <li> <p><code>repository</code>: Location of the project source code.</p> </li> </ul> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Key</p></td> <td><p><code>links</code></p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>Object (String: String)</p></td> </tr> </tbody> </table> <div id="contract-type-object"></div> <h3 id="the-contract-type-object">The <em>Contract Type</em> Object</h3> <p>A <em>Contract Type</em> object is defined to have the following key/value pairs.</p> <h4 id="contract-name-contract-name">Contract Name: <code>contract_name</code></h4> <p>The <code>contract_name</code> field defines the <a href="https://wg-eips.ritovision.com/1123/#term-contract-name">Contract Name</a> for this <a href="https://wg-eips.ritovision.com/1123/#term-contract-type">Contract Type</a>.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>If the <a href="#term-contract-name">Contract Name</a> and <a href="#term-contract-alias">Contract Alias</a> are not the same.</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>String</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p><strong>must</strong> be a valid <a href="#term-contract-name">Contract Name</a>.</p></td> </tr> </tbody> </table> <h4 id="deployment-bytecode-deployment-bytecode">Deployment Bytecode: <code>deployment_bytecode</code></h4> <p>The <code>deployment_bytecode</code> field defines the bytecode for this <a href="https://wg-eips.ritovision.com/1123/#term-contract-type">Contract Type</a>.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>Object</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p><strong>must</strong> conform to <a href="#the-bytecode-object">the Bytecode Object</a> format.</p></td> </tr> </tbody> </table> <h4 id="runtime-bytecode-runtime-bytecode">Runtime Bytecode: <code>runtime_bytecode</code></h4> <p>The <code>runtime_bytecode</code> field defines the unlinked <code>0x</code>-prefixed runtime portion of <a href="https://wg-eips.ritovision.com/1123/#term-bytecode">Bytecode</a> for this <a href="https://wg-eips.ritovision.com/1123/#term-contract-type">Contract Type</a>.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>Object</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p><strong>must</strong> conform to <a href="#the-bytecode-object">the Bytecode Object</a> format.</p></td> </tr> </tbody> </table> <h4 id="abi-abi">ABI: <code>abi</code></h4> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>List</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p><strong>must</strong> conform to the <a href="https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI#json">Ethereum Contract ABI JSON format</a>.</p></td> </tr> </tbody> </table> <h4 id="natspec-natspec">Natspec: <code>natspec</code></h4> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>Object</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p>The union of the <a href="https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format#user-documentation">UserDoc</a> and <a href="https://github.com/ethereum/wiki/wiki/Ethereum-Natural-Specification-Format#developer-documentation">DevDoc</a> formats.</p></td> </tr> </tbody> </table> <h4 id="compiler-compiler">Compiler: <code>compiler</code></h4> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>Object</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p><strong>must</strong> conform to <a href="#the-compiler-information-object">the Compiler Information object</a> format.</p></td> </tr> </tbody> </table> <div id="contract-instance-object"></div> <h3 id="the-contract-instance-object">The <em>Contract Instance</em> Object</h3> <p>A <strong>Contract Instance Object</strong> represents a single deployed <a href="https://wg-eips.ritovision.com/1123/#term-contract-instance">Contract Instance</a> and is defined to have the following key/value pairs.</p> <h4 id="contract-type-contract-type">Contract Type: <code>contract_type</code></h4> <p>The <code>contract_type</code> field defines the <a href="https://wg-eips.ritovision.com/1123/#term-contract-type">Contract Type</a> for this <a href="https://wg-eips.ritovision.com/1123/#term-contract-instance">Contract Instance</a>. This can reference any of the contract types included in this <a href="https://wg-eips.ritovision.com/1123/#term-package">Package</a> <em>or</em> any of the contract types found in any of the package dependencies from the <code>build_dependencies</code> section of the <a href="https://wg-eips.ritovision.com/1123/#term-package-manifest">Package Manifest</a>.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>Yes</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>String</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p>See Below.</p></td> </tr> </tbody> </table> <p><strong>Format</strong></p> <p>Values for this field <strong>must</strong> conform to <em>one of</em> the two formats herein.</p> <p>To reference a contract type from this Package, use the format <code>&lt;contract-alias&gt;</code>.</p> <ul> <li> <p>The <code>&lt;contract-alias&gt;</code> value <strong>must</strong> be a valid <a href="https://wg-eips.ritovision.com/1123/#term-contract-alias">Contract Alias</a>.</p> </li> <li> <p>The value <strong>must</strong> be present in the keys of the <code>contract_types</code> section of this Package.</p> </li> </ul> <p>To reference a contract type from a dependency, use the format <code>&lt;package-name&gt;:&lt;contract-alias&gt;</code>.</p> <ul> <li> <p>The <code>&lt;package-name&gt;</code> value <strong>must</strong> be present in the keys of the <code>build_dependencies</code> of this Package.</p> </li> <li> <p>The <code>&lt;contract-alias&gt;</code> value <strong>must</strong> be a valid <a href="https://wg-eips.ritovision.com/1123/#term-contract-alias">Contract Alias</a>.</p> </li> <li> <p>The resolved package for <code>&lt;package-name&gt;</code> must contain the <code>&lt;contract-alias&gt;</code> value in the keys of the <code>contract_types</code> section.</p> </li> </ul> <h4 id="address-address">Address: <code>address</code></h4> <p>The <code>address</code> field defines the <a href="https://wg-eips.ritovision.com/1123/#term-address">Address</a> of the <a href="https://wg-eips.ritovision.com/1123/#term-contract-instance">Contract Instance</a>.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>Yes</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>String</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p>Hex encoded <code>0x</code> prefixed Ethereum address matching the regular expression <code>0x[0-9a-fA-F]{40}</code>.</p></td> </tr> </tbody> </table> <h4 id="transaction-transaction">Transaction: <code>transaction</code></h4> <p>The <code>transaction</code> field defines the transaction hash in which this <a href="https://wg-eips.ritovision.com/1123/#term-contract-instance">Contract Instance</a> was created.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>String</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p><code>0x</code> prefixed hex encoded transaction hash.</p></td> </tr> </tbody> </table> <h4 id="block-block">Block: <code>block</code></h4> <p>The <code>block</code> field defines the block hash in which this the transaction which created this <em>contract instance</em> was mined.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>String</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p><code>0x</code> prefixed hex encoded block hash.</p></td> </tr> </tbody> </table> <div id="runtime-bytecode-runtime-bytecode-1"></div> <h4 id="runtime-bytecode-runtime-bytecode-1">Runtime Bytecode: <code>runtime_bytecode</code></h4> <p>The <code>runtime_bytecode</code> field defines the runtime portion of bytecode for this <a href="https://wg-eips.ritovision.com/1123/#term-contract-instance">Contract Instance</a>. When present, the value from this field supersedes the <code>runtime_bytecode</code> from the <a href="https://wg-eips.ritovision.com/1123/#term-contract-type">Contract Type</a> for this <a href="https://wg-eips.ritovision.com/1123/#term-contract-instance">Contract Instance</a>.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>Object</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p><strong>must</strong> conform to <a href="#the-bytecode-object">the Bytecode Object</a> format.</p></td> </tr> </tbody> </table> <p>Every entry in the <code>link_references</code> for this bytecode <strong>must</strong> have a corresponding entry in the <code>link_dependencies</code> section.</p> <h4 id="compiler-compiler-1">Compiler: <code>compiler</code></h4> <p>The <code>compiler</code> field defines the compiler information that was used during compilation of this <a href="https://wg-eips.ritovision.com/1123/#term-contract-instance">Contract Instance</a>. This field <strong>should</strong> be present in all <a href="https://wg-eips.ritovision.com/1123/#term-contract-type">Contract Types</a> which include <code>bytecode</code> or <code>runtime_bytecode</code>.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Type</p></td> <td><p>Object</p></td> </tr> <tr class="odd"> <td><p>Format</p></td> <td><p><strong>must</strong> conform to the <a href="#compiler-information-object">Compiler Information Object</a> format.</p></td> </tr> </tbody> </table> <div id="compiler-information-object"></div> <h3 id="the-compiler-information-object">The <em>Compiler Information</em> Object</h3> <p>The <code>compiler</code> field defines the compiler information that was used during compilation of this <a href="https://wg-eips.ritovision.com/1123/#term-contract-instance">Contract Instance</a>. This field <strong>should</strong> be present in all contract instances that locally declare <code>runtime_bytecode</code>.</p> <p>A <em>Compiler Information</em> object is defined to have the following key/value pairs.</p> <h4 id="name-name-1">Name <code>name</code></h4> <p>The <code>name</code> field defines which compiler was used in compilation.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>Yes</p></td> </tr> <tr class="even"> <td><p>Key</p></td> <td><p><code>name</code></p></td> </tr> <tr class="odd"> <td><p>Type</p></td> <td><p>String</p></td> </tr> </tbody> </table> <h4 id="version-version-1">Version: <code>version</code></h4> <p>The <code>version</code> field defines the version of the compiler. The field <strong>should</strong> be OS agnostic (OS not included in the string) and take the form of either the stable version in <a rel="external" href="https://semver.org/">semver</a> format or if built on a nightly should be denoted in the form of <code>&lt;semver&gt;-&lt;commit-hash&gt;</code> ex: <code>0.4.8-commit.60cc1668</code>.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>Yes</p></td> </tr> <tr class="even"> <td><p>Key</p></td> <td><p><code>version</code></p></td> </tr> <tr class="odd"> <td><p>Type</p></td> <td><p>String</p></td> </tr> </tbody> </table> <h4 id="settings-settings">Settings: <code>settings</code></h4> <p>The <code>settings</code> field defines any settings or configuration that was used in compilation. For the <code>"solc"</code> compiler, this <strong>should</strong> conform to the <a rel="external" href="https://solidity.readthedocs.io/en/latest/using-the-compiler.html#compiler-input-and-output-json-description">Compiler Input and Output Description</a>.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Required</p></td> <td><p>No</p></td> </tr> <tr class="even"> <td><p>Key</p></td> <td><p><code>settings</code></p></td> </tr> <tr class="odd"> <td><p>Type</p></td> <td><p>Object</p></td> </tr> </tbody> </table> <h3 id="bip122-uris">BIP122 URIs</h3> <p>BIP122 URIs are used to define a blockchain via a subset of the <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0122.mediawiki">BIP-122</a> spec.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>blockchain://&lt;genesis_hash&gt;/block/&lt;latest confirmed block hash&gt;</span></span></code></pre> <p>The <code>&lt;genesis hash&gt;</code> represents the blockhash of the first block on the chain, and <code>&lt;latest confirmed block hash&gt;</code> represents the hash of the latest block that’s been reliably confirmed (package managers should be free to choose their desired level of confirmations).</p> <h1 id="rationale">Rationale</h1> <p>The following use cases were considered during the creation of this specification.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>owned</p></td> <td><p>A package which contains contracts which are not meant to be used by themselves but rather as base contracts to provide functionality to other contracts through inheritance.</p></td> </tr> <tr class="even"> <td><p>transferable</p></td> <td><p>A package which has a single dependency.</p></td> </tr> <tr class="odd"> <td><p>standard-token</p></td> <td><p>A package which contains a reusable contract.</p></td> </tr> <tr class="even"> <td><p>safe-math-lib</p></td> <td><p>A package which contains deployed instance of one of the package contracts.</p></td> </tr> <tr class="odd"> <td><p>piper-coin</p></td> <td><p>A package which contains a deployed instance of a reusable contract from a dependency.</p></td> </tr> <tr class="even"> <td><p>escrow</p></td> <td><p>A package which contains a deployed instance of a local contract which is linked against a deployed instance of a local library.</p></td> </tr> <tr class="odd"> <td><p>wallet</p></td> <td><p>A package with a deployed instance of a local contract which is linked against a deployed instance of a library from a dependency.</p></td> </tr> <tr class="even"> <td><p>wallet-with-send</p></td> <td><p>A package with a deployed instance which links against a deep dependency.</p></td> </tr> </tbody> </table> <p>Each use case builds incrementally on the previous one.</p> <p>A full listing of <a rel="external" href="https://ethpm.github.io/ethpm-spec/use-cases.html">Use Cases</a> can be found on the hosted version of this specification.</p> <h1 id="glossary">Glossary</h1> <div id="term-abi"></div> <h2 id="abi">ABI</h2> <p>The JSON representation of the application binary interface. See the official <a rel="external" href="https://solidity.readthedocs.io/en/develop/abi-spec.html">specification</a> for more information.</p> <div id="term-address"></div> <h2 id="address">Address</h2> <p>A public identifier for an account on a particular chain</p> <div id="term-bytecode"></div> <h2 id="bytecode">Bytecode</h2> <p>The set of EVM instructions as produced by a compiler. Unless otherwise specified this should be assumed to be hexadecimal encoded, representing a whole number of bytes, and <a href="https://wg-eips.ritovision.com/1123/#term-prefixed">prefixed</a> with <code>0x</code>.</p> <p>Bytecode can either be linked or unlinked. (see <a href="https://wg-eips.ritovision.com/1123/#term-linking">Linking</a>)</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Unlinked Bytecode</p></td> <td><p>The hexadecimal representation of a contract’s EVM instructions that contains sections of code that requires <a href="#term-linking">linking</a> for the contract to be functional.</p> <p>The sections of code which are unlinked <strong>must</strong> be filled in with zero bytes.</p> <p><strong>Example</strong>: <code>0x606060405260e06000730000000000000000000000000000000000000000634d536f</code></p></td> </tr> <tr class="even"> <td><p>Linked Bytecode</p></td> <td><p>The hexadecimal representation of a contract’s EVM instructions which has had all <a href="#term-link-reference">Link References</a> replaced with the desired <a href="#term-link-value">Link Values</a>.</p> <p><strong>Example</strong>: <code>0x606060405260e06000736fe36000604051602001526040518160e060020a634d536f</code></p></td> </tr> </tbody> </table> <div id="term-chain-definition"></div> <h2 id="chain-definition">Chain Definition</h2> <p>This definition originates from <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0122.mediawiki">BIP122 URI</a>.</p> <p>A URI in the format <code>blockchain://&lt;chain_id&gt;/block/&lt;block_hash&gt;</code></p> <ul> <li> <p><code>chain_id</code> is the unprefixed hexadecimal representation of the genesis hash for the chain.</p> </li> <li> <p><code>block_hash</code> is the unprefixed hexadecimal representation of the hash of a block on the chain.</p> </li> </ul> <p>A chain is considered to match a chain definition if the genesis block hash matches the <code>chain_id</code> and the block defined by <code>block_hash</code> can be found on that chain. It is possible for multiple chains to match a single URI, in which case all chains are considered valid matches</p> <div id="term-content-addressable-uri"></div> <h2 id="content-addressable-uri">Content Addressable URI</h2> <p>Any URI which contains a cryptographic hash which can be used to verify the integrity of the content found at the URI.</p> <p>The URI format is defined in RFC3986</p> <p>It is <strong>recommended</strong> that tools support IPFS and Swarm.</p> <div id="term-contract-alias"></div> <h2 id="contract-alias">Contract Alias</h2> <p>This is a name used to reference a specific <a href="https://wg-eips.ritovision.com/1123/#term-contract-type">Contract Type</a>. Contract aliases <strong>must</strong> be unique within a single <a href="https://wg-eips.ritovision.com/1123/#term-package">Package</a>.</p> <p>The contract alias <strong>must</strong> use <em>one of</em> the following naming schemes:</p> <ul> <li> <p><code>&lt;contract-name&gt;</code></p> </li> <li> <p><code>&lt;contract-name&gt;[&lt;identifier&gt;]</code></p> </li> </ul> <p>The <code>&lt;contract-name&gt;</code> portion <strong>must</strong> be the same as the <a href="https://wg-eips.ritovision.com/1123/#term-contract-name">Contract Name</a> for this contract type.</p> <p>The <code>[&lt;identifier&gt;]</code> portion <strong>must</strong> match the regular expression <code>\[[-a-zA-Z0-9]{1,256}]</code>.</p> <div id="term-contract-instance"></div> <h2 id="contract-instance">Contract Instance</h2> <p>A contract instance a specific deployed version of a <a href="https://wg-eips.ritovision.com/1123/#term-contract-type">Contract Type</a>.</p> <p>All contract instances have an <a href="https://wg-eips.ritovision.com/1123/#term-address">Address</a> on some specific chain.</p> <div id="term-contract-instance-name"></div> <h2 id="contract-instance-name">Contract Instance Name</h2> <p>A name which refers to a specific <a href="https://wg-eips.ritovision.com/1123/#term-contract-instance">Contract Instance</a> on a specific chain from the deployments of a single <a href="https://wg-eips.ritovision.com/1123/#term-package">Package</a>. This name <strong>must</strong> be unique across all other contract instances for the given chain. The name must conform to the regular expression <code>[a-zA-Z][a-zA-Z0-9_]{0,255}</code></p> <p>In cases where there is a single deployed instance of a given <a href="https://wg-eips.ritovision.com/1123/#term-contract-type">Contract Type</a>, package managers <strong>should</strong> use the <a href="https://wg-eips.ritovision.com/1123/#term-contract-alias">Contract Alias</a> for that contract type for this name.</p> <p>In cases where there are multiple deployed instances of a given contract type, package managers <strong>should</strong> use a name which provides some added semantic information as to help differentiate the two deployed instances in a meaningful way.</p> <div id="term-contract-name"></div> <h2 id="contract-name">Contract Name</h2> <p>The name found in the source code that defines a specific <a href="https://wg-eips.ritovision.com/1123/#term-contract-type">Contract Type</a>. These names <strong>must</strong> conform to the regular expression <code>[a-zA-Z][-a-zA-Z0-9_]{0,255}</code>.</p> <p>There can be multiple contracts with the same contract name in a projects source files.</p> <div id="term-contract-type"></div> <h2 id="contract-type">Contract Type</h2> <p>Refers to a specific contract in the package source. This term can be used to refer to an abstract contract, a normal contract, or a library. Two contracts are of the same contract type if they have the same bytecode.</p> <p>Example:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>contract Wallet {</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>A deployed instance of the <code>Wallet</code> contract would be of type <code>Wallet</code>.</p> <div id="term-identifier"></div> <h2 id="identifier">Identifier</h2> <p>Refers generally to a named entity in the <a href="https://wg-eips.ritovision.com/1123/#term-package">Package</a>.</p> <p>A string matching the regular expression <code>[a-zA-Z][-_a-zA-Z0-9]{0,255}</code></p> <div id="term-link-reference"></div> <h2 id="link-reference">Link Reference</h2> <p>A location within a contract’s bytecode which needs to be linked. A link reference has the following properties.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p><code>offset</code></p></td> <td><p>Defines the location within the bytecode where the link reference begins.</p></td> </tr> <tr class="even"> <td><p><code>length</code></p></td> <td><p>Defines the length of the reference.</p></td> </tr> <tr class="odd"> <td><p><code>name</code></p></td> <td><p>(optional.) A string to identify the reference</p></td> </tr> </tbody> </table> <div id="term-link-value"></div> <h2 id="link-value">Link Value</h2> <p>A link value is the value which can be inserted in place of a <a href="https://wg-eips.ritovision.com/1123/#term-link-reference">Link Reference</a></p> <div id="term-linking"></div> <h2 id="linking">Linking</h2> <p>The act of replacing <a href="https://wg-eips.ritovision.com/1123/#term-link-reference">Link References</a> with <a href="https://wg-eips.ritovision.com/1123/#term-link-value">Link Values</a> within some <a href="https://wg-eips.ritovision.com/1123/#term-bytecode">Bytecode</a>.</p> <div id="term-package"></div> <h2 id="package">Package</h2> <p>Distribution of an application’s source or compiled bytecode along with metadata related to authorship, license, versioning, et al.</p> <p>For brevity, the term <strong>Package</strong> is often used metonymously to mean <a href="https://wg-eips.ritovision.com/1123/#term-package-manifest">Package Manifest</a>.</p> <div id="term-package-manifest"></div> <h2 id="package-manifest">Package Manifest</h2> <p>A machine-readable description of a package (See <a href="https://wg-eips.ritovision.com/1123/#package-specification">Specification</a> for information about the format for package manifests.)</p> <div id="term-prefixed"></div> <h2 id="prefixed">Prefixed</h2> <p><a href="https://wg-eips.ritovision.com/1123/#term-bytecode">Bytecode</a> string with leading <code>0x</code>.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Example</p></td> <td><p><code>0xdeadbeef</code></p></td> </tr> </tbody> </table> <div id="term-unprefixed"></div> <h2 id="unprefixed">Unprefixed</h2> <p>Not <a href="https://wg-eips.ritovision.com/1123/#term-prefixed">Prefixed</a>.</p> <table> <colgroup> <col style="width: 50%" /> <col style="width: 50%" /> </colgroup> <tbody> <tr class="odd"> <td><p>Example</p></td> <td><p><code>deadbeef</code></p></td> </tr> </tbody> </table> <h1 id="backwards-compatibility">Backwards Compatibility</h1> <p>This specification supports backwards compatibility by use of the <a href="https://wg-eips.ritovision.com/1123/#manifest-version">manifest_version</a> property. This specification corresponds to version <code>2</code> as the value for that field.</p> <h1 id="implementations">Implementations</h1> <p>This submission aims to coincide with development efforts towards widespread implementation in commonly-used development tools.</p> <p>The following tools are known to have begun or are nearing completion of a supporting implementation.</p> <ul> <li> <p><a rel="external" href="https://trufflesuite.com/">Truffle</a></p> </li> <li> <p><a rel="external" href="https://populus.readthedocs.io/en/latest/">Populus</a></p> </li> <li> <p><a rel="external" href="https://embark.status.im/">Embark</a></p> </li> </ul> <p>Full support in implementation <strong>may</strong> require <a href="https://wg-eips.ritovision.com/1123/#further-work">Further Work</a>, specified below.</p> <h1 id="further-work">Further Work</h1> <p>This EIP addresses only the data format for package descriptions. Excluded from the scope of this specification are:</p> <ul> <li> <p>Package registry interface definition</p> </li> <li> <p>Tooling integration, or how packages are stored on disk.</p> </li> </ul> <p>These efforts <strong>should</strong> be considered separate, warranting future dependent EIP submssions.</p> <h1 id="acknowledgements">Acknowledgements</h1> <p>The authors of this document would like to thank the original authors of <a href="https://wg-eips.ritovision.com/190/">EIP-190</a>, <a rel="external" href="http://ethprize.io/">ETHPrize</a> for their funding support, all community <a rel="external" href="https://github.com/ethpm/ethpm-spec/graphs/contributors">contributors</a>, and the Ethereum community at large.</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-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-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Antonio Salazar Cardozohttps://github.com/shadowfiend Zachary Williamsonhttps://github.com/zac-williamson https://wg-eips.ritovision.com/1108/ <h2 id="simple-summary">Simple Summary</h2> <p>The elliptic curve arithmetic precompiles are currently overpriced. Re-pricing the precompiles would greatly assist a number of privacy solutions and scaling solutions on Ethereum.</p> <h2 id="abstract">Abstract</h2> <p>Changes in 2018 to the underlying library used by the official Go reference implementation led to significant performance gains for the <code>ECADD</code>, <code>ECMUL</code>, and pairing check precompiled contracts on the <code>alt_bn128</code> elliptic curve.</p> <p>In the Parity client, field operations used by the precompile algorithms were optimized in 2018, and recent changes to the pairing algorithm used by the <code>bn</code> crate have brought considerable speedups.</p> <p>Faster operations on Ethereum clients should be reflected in reduced gas costs.</p> <h2 id="motivation">Motivation</h2> <p>Recently, the underlying library used by the <a rel="external" href="https://github.com/ethereum/go-ethereum">official Go reference implementation</a> to implement the <code>ECADD</code> (at address <code>0x06</code>), <code>ECMUL</code> (at address <code>0x07</code>), and pairing check (at address <code>0x08</code>) precompiled contracts was shifted to <a rel="external" href="https://github.com/cloudflare/bn256">Cloudflare's bn256 library</a>. Based on the <a rel="external" href="https://github.com/ethereum/go-ethereum/pull/16203">initial PR that introduced this change</a>, and corroborated in <a rel="external" href="https://github.com/ethereum/go-ethereum/pull/16301#issuecomment-372687543">a later note</a>, the computational cost of <code>ECADD</code>, <code>ECMUL</code>, and pairing checks (excepting the constant) has dropped roughly an order of magnitude across the board.</p> <p>Also, optimizations in the bn library <a rel="external" href="https://github.com/paritytech/bn/pull/9">in 2018</a> and <a rel="external" href="https://github.com/paritytech/bn/pull/14">2019</a> used by the <a rel="external" href="https://github.com/paritytech/parity-ethereum">Parity client</a> led to a significant performance boost we <a rel="external" href="https://gist.github.com/zac-williamson/838410a3da179d47d31b25b586c15e53">benchmarked</a> and compared against the <a rel="external" href="https://gist.github.com/pdyraga/4649b74436940a01e8221d85e80bfeef">previous results</a>.</p> <h2 id="specification">Specification</h2> <p>Following is a table with the current gas cost and new gas cost:</p> <table><thead><tr><th>Contract</th><th>Address</th><th>Current Gas Cost</th><th>Updated Gas Cost</th></tr></thead><tbody> <tr><td><code>ECADD</code></td><td><code>0x06</code></td><td>500^[1]</td><td>150</td></tr> <tr><td><code>ECMUL</code></td><td><code>0x07</code></td><td>40 000^[1]</td><td>6 000</td></tr> <tr><td>Pairing check</td><td><code>0x08</code></td><td>80 000 * k + 100 000^[2]</td><td>34 000 * k + 45 000</td></tr> </tbody></table> <p>The gas costs for <code>ECADD</code> and <code>ECMUL</code> are updates to the costs listed in EIP-196, while the gas costs for the pairing check are updates to the cost listed in EIP-197. Updated gas costs have been adjusted to the less performant client which is Parity, according to benchmarks^[3].</p> <p>To come up with these updates gas costs, the performance of the <code>ecrecover</code> precompile was measured at 116 microseconds per <code>ecrecover</code> invocation. Assuming the <code>ecrecover</code> gas price is fair at 3,000 gas, we get a price of 25.86 gas per microsecond of a precompile algorithm's runtime. With this in mind, the pairing precompile took 3,037 microseconds to compute 1 pairing, and 14,663 microseconds to compute 10 pairings. From this, the pairing algorithm has a fixed 'base' run-time of 1,745 microseconds, plus 1,292 microseconds per pairing. We can split the run-time into 'fixed cost' and 'linear cost per pairing' components because of the structure of the algorithm.</p> <p>Thus using a 'fair' price of 25.86 gas per microsecond, we get a gas formula of ~<code>35,000 * k + 45,000</code> gas, where <code>k</code> is the number of pairings being computed. [4]</p> <p>[1]- Per <a href="https://wg-eips.ritovision.com/196/">EIP-196</a>.</p> <p>[2]- Per <a href="https://wg-eips.ritovision.com/197/">EIP-197</a>.</p> <p>[3]- <a rel="external" href="https://gist.github.com/zac-williamson/838410a3da179d47d31b25b586c15e53">Parity benchmarks.</a></p> <p>[4]- <a rel="external" href="https://github.com/ethereum/EIPs/pull/1987#discussion_r280977066">PR comment clarifying gas cost math</a>.</p> <h2 id="rationale">Rationale</h2> <h3 id="existing-protocols-would-benefit-immensely-from-cheaper-elliptic-curve-cryptography">Existing protocols would benefit immensely from cheaper elliptic curve cryptography</h3> <p>Fast elliptic curve cryptography is a keystone of a growing number of protocols built on top of Ethereum. To list a few:</p> <ul> <li><a rel="external" href="https://github.com/AztecProtocol/AZTEC">The AZTEC protocol</a> utilizes the elliptic curve precompiles to construct private tokens, with zero-knowledge transaction logic, via the <a rel="external" href="https://github.com/ethereum/EIPs/issues/1723">ERC-1723</a> and <a rel="external" href="https://github.com/ethereum/EIPs/issues/1724">ERC-1724</a> standard.</li> <li><a rel="external" href="https://github.com/matter-labs/matter-network">Matter Labs</a> utilizes the precompiles to implement Ignis, a scaling solution with a throughput of 500txns per second</li> <li><a rel="external" href="https://github.com/rollup/rollup">Rollup</a> utilizes the precompiles to create L2 scaling solutions, where the correctness of transactions is guaranteed by main-net, without an additional consensus layer</li> <li>ZEther<sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">1</a></sup> uses precompiles <code>ECADD</code> and <code>ECMUL</code> to construct confidential transactions</li> </ul> <p>To give a concrete example, it currently costs <code>820,000</code> gas to validate the cryptography in a typical AZTEC confidential transaction. If the gas schedule for the precompiles correctly reflected their load on the Ethereum network, this cost would be <code>197,000</code> gas. This significantly increases the potential use cases for private assets on Ethereum. AZTEC is planning to deploy several cryptographic protocols Ethereum, but these are at the limits of what is practical given the current precompile costs:</p> <ul> <li>Confidential weighted voting</li> <li>Partial-order filling over encrypted orders, for private decentralized exchanges</li> <li>Anonymous identity sharing proofs (e.g. proving you are on a whitelist, without revealing who you are)</li> <li>Many-to-one payments and one-to-many confidential payments, as encrypted communication channels between main-net and L2 applications</li> </ul> <p>For zk-SNARK based protocols on Ethereum, EIP-1108 will not only reduce the gas costs of verifying zk-SNARKs substantially, but can also aid in <a rel="external" href="https://github.com/matter-labs/Groth16BatchVerifier">batching together multiple zk-SNARK proofs</a>. This is also a technique that can be used to split up monolithic zk-SNARK circuits into a batch of zk-SNARKs with smaller individual circuit sizes, which makes zk-SNARKs both easier to construct and deploy.</p> <p>ZEther transactions currently cost ~<code>6,000,000</code> gas. This EIP would reduce this to ~<code>1,000,000</code> gas, which makes the protocol more practical.</p> <p>To summarise, there are several protocols that currently exist on main-net, that would benefit immensely from this EIP. Elliptic curve cryptography can provide valuable solutions for Ethereum, such as scaling and privacy, and the scope and scale of these solutions can be increased if the gas costs for the <code>bn128</code> precompiles accurately reflects their computational load on the network.</p> <h3 id="cheaper-elliptic-curve-cryptography-can-be-used-to-trade-storage-for-computation">Cheaper elliptic curve cryptography can be used to trade storage for computation</h3> <p>Solutions such as Rollup and Ignis can be used to batch groups of individual transactions into a zk-SNARK proof, with the on-chain state being represented by a small Merkle root, instead of multiple account balances.</p> <p>If zk-SNARK verification costs are decreased, these solutions can be deployed for a wider range of use cases and more Rollup-style transactions can be processed per block.</p> <h3 id="parity-and-geth-already-have-fast-algorithms-that-justify-reduced-gas-costs">Parity and Geth already have fast algorithms that justify reduced gas costs</h3> <p>This EIP does not require Parity or Geth to deploy new cryptographic libraries, as fast bn128 algorithms have already been integrated into these clients. This goal of proposing this EIP for Istanbul, is to supplement <a href="https://wg-eips.ritovision.com/1829/">EIP-1829</a> (arithmetic over generic elliptic curves), providing an immediate solution to the pressing problem of expensive cryptography, while more advanced solutions are developed, defined and deployed.</p> <h2 id="test-cases">Test Cases</h2> <p>As no underlying algorithms are being changed, there are no additional test cases to specify.</p> <h2 id="implementation">Implementation</h2> <p>Both the Parity and Geth clients have already implemented cryptographic libraries that are fast enough to justify reducing the precompile gas costs. As a reference, here are a list of elliptic curve libraries, in <code>C++</code>, <code>golang</code> and <code>rust</code>, that support the <code>bn128</code> curve, and have run-times that are equal to or faster than the Parity benchmarks.</p> <ul> <li><a rel="external" href="https://github.com/paritytech/bn">Parity bn crate (rust)</a></li> <li><a rel="external" href="https://github.com/ethereum/go-ethereum/tree/master/crypto/bn256/cloudflare">Geth bn256 library (golang)</a></li> <li><a rel="external" href="https://github.com/herumi/mcl">MCL, a portable C++ pairing library</a></li> <li><a rel="external" href="https://github.com/scipr-lab/libff">Libff, a C++ pairing library used in many zk-SNARK libraries</a></li> </ul> <h2 id="additional-references">Additional References</h2> <p>@vbuterin independently proposed a similar reduction after this EIP was originally created, with similar rationale, as <a rel="external" href="https://github.com/ethereum/EIPs/issues/1187">ethereum/EIPs#1187</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> <section class="footnotes"> <ol class="footnotes-list"> <li id="fn-1"> <p>Bünz, B., Agrawal, S., Zamani, M., &amp; Boneh, D. (2020). Zether: Towards Privacy in a Smart Contract World. In J. Bonneau &amp; N. Heninger (Eds.), <span style="font-style: italic;">Financial Cryptography and Data Security</span>. https://doi.org/<a href="https://doi.org/10.1007/978-3-030-51280-4_23">10.1007/978-3-030-51280-4_23</a>These are all technologies that have been, or are in the process of being, deployed to main-net. These protocols would all benefit from reducing the gas cost of the precompiles. <a href="#fr-1-1">↩</a></p> </li> </ol> </section> 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⁴ (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:27+00:00 Nick Johnsonarachnid@notdot.net Paweł Bylicapawel@ethereum.org https://wg-eips.ritovision.com/1052/ <h2 id="abstract">Abstract</h2> <p>This EIP specifies a new opcode, which returns the keccak256 hash of a contract's code.</p> <h2 id="motivation">Motivation</h2> <p>Many contracts need to perform checks on a contract's bytecode, but do not necessarily need the bytecode itself. For instance, a contract may want to check if another contract's bytecode is one of a set of permitted implementations, or it may perform analyses on code and whitelist any contract with matching bytecode if the analysis passes.</p> <p>Contracts can presently do this using the <code>EXTCODECOPY</code> (<code>0x3c</code>) opcode, but this is expensive, especially for large contracts, in cases where only the hash is required. As a result, we propose a new opcode, <code>EXTCODEHASH</code>, which returns the keccak256 hash of a contract's bytecode.</p> <h2 id="specification">Specification</h2> <p>A new opcode, <code>EXTCODEHASH</code>, is introduced, with number <code>0x3f</code>. The <code>EXTCODEHASH</code> takes one argument from the stack, zeros the first 96 bits and pushes to the stack the keccak256 hash of the code of the account at the address being the remaining 160 bits.</p> <p>In case the account does not exist or is empty (as defined by <a href="https://wg-eips.ritovision.com/161/">EIP-161</a>) <code>0</code> is pushed to the stack.</p> <p>In case the account does not have code the keccak256 hash of empty data (i.e. <code>c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470</code>) is pushed to the stack.</p> <p>The gas cost of the <code>EXTCODEHASH</code> is 400.</p> <h2 id="rationale">Rationale</h2> <p>As described in the motivation section, this opcode is widely useful, and saves on wasted gas in many cases.</p> <p>The gas cost is the same as the gas cost for the <code>BALANCE</code> opcode because the execution of the <code>EXTCODEHASH</code> requires the same account lookup as in <code>BALANCE</code>.</p> <p>Only the 20 last bytes of the argument are significant (the first 12 bytes are ignored) similarly to the semantics of the <code>BALANCE</code> (<code>0x31</code>), <code>EXTCODESIZE</code> (<code>0x3b</code>) and <code>EXTCODECOPY</code> (<code>0x3c</code>).</p> <p>The <code>EXTCODEHASH</code> distinguishes accounts without code and non-existing accounts. This is consistent with the way accounts are represented in the state trie. This also allows smart contracts to check whether an account exists.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no backwards compatibility concerns.</p> <h2 id="test-cases">Test Cases</h2> <ol> <li>The <code>EXTCODEHASH</code> of the account without code is <code>c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470</code> what is the keccak256 hash of empty data.</li> <li>The <code>EXTCODEHASH</code> of non-existent account is <code>0</code>.</li> <li>The <code>EXTCODEHASH</code> of a precompiled contract is either <code>c5d246...</code> or <code>0</code>.</li> <li>If <code>EXTCODEHASH</code> of <code>A</code> is <code>X</code>, then <code>EXTCODEHASH</code> of <code>A + 2**160</code> is <code>X</code>.</li> <li>The <code>EXTCODEHASH</code> of an account that selfdestructed in the current transaction.</li> <li>The <code>EXTCODEHASH</code> of an account that selfdestructed and later the selfdestruct has been reverted.</li> <li>The <code>EXTCODEHASH</code> of an account created in the current transaction.</li> <li>The <code>EXTCODEHASH</code> of an account that has been newly created and later the creation has been reverted.</li> <li>The <code>EXTCODEHASH</code> of an account that firstly does not exist and later is empty.</li> <li>The <code>EXTCODEHASH</code> of an empty account that is going to be cleared by the state clearing rule.</li> </ol> <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 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/1014/ <h3 id="specification">Specification</h3> <p>Adds a new opcode (<code>CREATE2</code>) at <code>0xf5</code>, which takes 4 stack arguments: endowment, memory_start, memory_length, salt. Behaves identically to <code>CREATE</code> (<code>0xf0</code>), except using <code>keccak256( 0xff ++ address ++ salt ++ keccak256(init_code))[12:]</code> instead of the usual sender-and-nonce-hash as the address where the contract is initialized at.</p> <p>The <code>CREATE2</code> has the same <code>gas</code> schema as <code>CREATE</code>, but also an extra <code>hashcost</code> of <code>GSHA3WORD * ceil(len(init_code) / 32)</code>, to account for the hashing that must be performed. The <code>hashcost</code> is deducted at the same time as memory-expansion gas and <code>CreateGas</code> is deducted: <em>before</em> evaluation of the resulting address and the execution of <code>init_code</code>.</p> <ul> <li><code>0xff</code> is a single byte,</li> <li><code>address</code> is always <code>20</code> bytes,</li> <li><code>salt</code> is always <code>32</code> bytes (a stack item).</li> </ul> <p>The preimage for the final hashing round is thus always exactly <code>85</code> bytes long.</p> <p>The coredev-call at 2018-08-10 decided to use the formula above.</p> <h3 id="motivation">Motivation</h3> <p>Allows interactions to (actually or counterfactually in channels) be made with addresses that do not exist yet on-chain but can be relied on to only possibly eventually contain code that has been created by a particular piece of init code. Important for state-channel use cases that involve counterfactual interactions with contracts.</p> <h3 id="rationale">Rationale</h3> <h4 id="address-formula">Address formula</h4> <ul> <li>Ensures that addresses created with this scheme cannot collide with addresses created using the traditional <code>keccak256(rlp([sender, nonce]))</code> formula, as <code>0xff</code> can only be a starting byte for RLP for data many petabytes long.</li> <li>Ensures that the hash preimage has a fixed size,</li> </ul> <h4 id="gas-cost">Gas cost</h4> <p>Since address calculation depends on hashing the <code>init_code</code>, it would leave clients open to DoS attacks if executions could repeatedly cause hashing of large pieces of <code>init_code</code>, since expansion of memory is paid for only once. This EIP uses the same cost-per-word as the <code>SHA3</code> opcode.</p> <h3 id="clarifications">Clarifications</h3> <p>The <code>init_code</code> is the code that, when executed, produces the runtime bytecode that will be placed into the state, and which typically is used by high level languages to implement a 'constructor'.</p> <p>This EIP makes collisions possible. The behaviour at collisions is specified by <a rel="external" href="https://github.com/ethereum/EIPs/issues/684">EIP-684</a>:</p> <blockquote> <p>If a contract creation is attempted, due to either a creation transaction or the <code>CREATE</code> (or future <code>CREATE2</code>) opcode, and the destination address already has either nonzero nonce, or nonempty code, then the creation throws immediately, with exactly the same behavior as would arise if the first byte in the init code were an invalid opcode. This applies retroactively starting from genesis.</p> </blockquote> <p>Specifically, if <code>nonce</code> or <code>code</code> is nonzero, then the create-operation fails.</p> <p>With <a href="https://wg-eips.ritovision.com/161/">EIP-161</a></p> <blockquote> <p>Account creation transactions and the <code>CREATE</code> operation SHALL, prior to the execution of the initialisation code, increment the nonce over and above its normal starting value by one</p> </blockquote> <p>This means that if a contract is created in a transaction, the <code>nonce</code> is immediately non-zero, with the side-effect that a collision within the same transaction will always fail -- even if it's carried out from the <code>init_code</code> itself.</p> <p>It should also be noted that <code>SELFDESTRUCT</code> (<code>0xff</code>) has no immediate effect on <code>nonce</code> or <code>code</code>, thus a contract cannot be destroyed and recreated within one transaction.</p> <h3 id="examples">Examples</h3> <p>Example 0</p> <ul> <li>address <code>0x0000000000000000000000000000000000000000</code></li> <li>salt <code>0x0000000000000000000000000000000000000000000000000000000000000000</code></li> <li>init_code <code>0x00</code></li> <li>gas (assuming no mem expansion): <code>32006</code></li> <li>result: <code>0x4D1A2e2bB4F88F0250f26Ffff098B0b30B26BF38</code></li> </ul> <p>Example 1</p> <ul> <li>address <code>0xdeadbeef00000000000000000000000000000000</code></li> <li>salt <code>0x0000000000000000000000000000000000000000000000000000000000000000</code></li> <li>init_code <code>0x00</code></li> <li>gas (assuming no mem expansion): <code>32006</code></li> <li>result: <code>0xB928f69Bb1D91Cd65274e3c79d8986362984fDA3</code></li> </ul> <p>Example 2</p> <ul> <li>address <code>0xdeadbeef00000000000000000000000000000000</code></li> <li>salt <code>0x000000000000000000000000feed000000000000000000000000000000000000</code></li> <li>init_code <code>0x00</code></li> <li>gas (assuming no mem expansion): <code>32006</code></li> <li>result: <code>0xD04116cDd17beBE565EB2422F2497E06cC1C9833</code></li> </ul> <p>Example 3</p> <ul> <li>address <code>0x0000000000000000000000000000000000000000</code></li> <li>salt <code>0x0000000000000000000000000000000000000000000000000000000000000000</code></li> <li>init_code <code>0xdeadbeef</code></li> <li>gas (assuming no mem expansion): <code>32006</code></li> <li>result: <code>0x70f2b2914A2a4b783FaEFb75f459A580616Fcb5e</code></li> </ul> <p>Example 4</p> <ul> <li>address <code>0x00000000000000000000000000000000deadbeef</code></li> <li>salt <code>0x00000000000000000000000000000000000000000000000000000000cafebabe</code></li> <li>init_code <code>0xdeadbeef</code></li> <li>gas (assuming no mem expansion): <code>32006</code></li> <li>result: <code>0x60f3f640a8508fC6a86d45DF051962668E1e8AC7</code></li> </ul> <p>Example 5</p> <ul> <li>address <code>0x00000000000000000000000000000000deadbeef</code></li> <li>salt <code>0x00000000000000000000000000000000000000000000000000000000cafebabe</code></li> <li>init_code <code>0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef</code></li> <li>gas (assuming no mem expansion): <code>32012</code></li> <li>result: <code>0x1d8bfDC5D46DC4f61D6b6115972536eBE6A8854C</code></li> </ul> <p>Example 6</p> <ul> <li>address <code>0x0000000000000000000000000000000000000000</code></li> <li>salt <code>0x0000000000000000000000000000000000000000000000000000000000000000</code></li> <li>init_code <code>0x</code></li> <li>gas (assuming no mem expansion): <code>32000</code></li> <li>result: <code>0xE33C0C7F7df4809055C3ebA6c09CFe4BaF1BD9e0</code></li> </ul> 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-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Tommy Nicholashttps://github.com/tomasienrbc Matt Russohttps://github.com/mateosu John Zettlerhttps://github.com/JohnZettler Matt Condonhttps://github.com/shrugs Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/1046/

Extends ERC-20 with an ERC-721-like tokenURI, and extends ERC-721 and ERC-1155 with interoperability

<h2 id="abstract">Abstract</h2> <p><a href="https://wg-eips.ritovision.com/721/">ERC-721</a> introduced a <code>tokenURI</code> function for non-fungible tokens to handle miscellaneous metadata such as:</p> <ul> <li>thumbnail image</li> <li>title</li> <li>description</li> <li>special asset properties</li> <li>etc.</li> </ul> <p>This ERC adds a <code>tokenURI</code> function to <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, and extends <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> to enable interoperability between all three types of token URI.</p> <h2 id="motivation">Motivation</h2> <p>See the note about the metadata extension in <a href="https://wg-eips.ritovision.com/721/#rationale">ERC-721</a>. The same arguments apply to ERC-20.</p> <p>Being able to use similar mechanisms to extract metadata for ERC-20, ERC-721, ERC-1155, and future standards is useful for determining:</p> <ul> <li>What type of token a contract is (if any);</li> <li>How to display a token to a user, either in an asset listing page or on a dedicated token page; and</li> <li>Determining the capabilities of the token</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> <h3 id="interoperability-metadata">Interoperability Metadata</h3> <p>The following TypeScript interface is used in later sections:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * Interoperability metadata.</span></span> <span class="giallo-l"><span class="z-comment"> * This can be extended by other proposals.</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * All fields MUST be optional.</span></span> <span class="giallo-l"><span class="z-comment"> * **Not every field has to be a boolean.** Any optional JSON-serializable object can be used by extensions.</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">interface</span><span class="z-entity z-name"> InteroperabilityMetadata</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"> * This MUST be true if this is ERC-1046 Token Metadata, otherwise, this MUST be omitted.</span></span> <span class="giallo-l"><span class="z-comment"> * Setting this to true indicates to wallets that the address should be treated as an ERC-20 token.</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-variable"> erc1046</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span class="z-keyword"> |</span><span class="z-support"> undefined</span><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"> * This MUST be true if this is ERC-721 Token Metadata, otherwise, this MUST be omitted.</span></span> <span class="giallo-l"><span class="z-comment"> * Setting this to true indicates to wallets that the address should be treated as an ERC-721 token.</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-variable"> erc721</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span class="z-keyword"> |</span><span class="z-support"> undefined</span><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"> * This MUST be true if this is ERC-1155 Token Metadata, otherwise, this MUST be omitted.</span></span> <span class="giallo-l"><span class="z-comment"> * Setting this to true indicates to wallets that the address should be treated as an ERC-1155 token.</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-variable"> erc1155</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span class="z-keyword"> |</span><span class="z-support"> undefined</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="erc-20-extension">ERC-20 Extension</h3> <h4 id="erc-20-interface-extension">ERC-20 Interface Extension</h4> <p>Compliant contracts MUST implement the following Solidity 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-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-20 Metadata Extension</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC20TokenMetadata</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC20 </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"> Gets an ERC-721-like token URI</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The resolved data MUST be in JSON format and support ERC-1046&#39;s ERC-20 Token Metadata Schema</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>)</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="erc-20-token-metadata-schema">ERC-20 Token Metadata Schema</h4> <p>The resolved JSON of the <code>tokenURI</code> described in the ERC-20 Interface Extension section MUST conform to the following TypeScript interface:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * Asset Metadata</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">interface</span><span class="z-entity z-name"> ERC20TokenMetadata</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"> * Interoperability, to differentiate between different types of tokens and their corresponding URIs.</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-variable"> interop</span><span class="z-keyword">:</span><span class="z-entity z-name"> InteroperabilityMetadata</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> <span class="giallo-l"><span class="z-comment"> * The name of the ERC-20 token. </span></span> <span class="giallo-l"><span class="z-comment"> * If the `name()` function is present in the ERC-20 token and returns a nonempty string, these MUST be the same value.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-variable"> name</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * The symbol of the ERC-20 token. </span></span> <span class="giallo-l"><span class="z-comment"> * If the `symbol()` function is present in the ERC-20 token and returns a nonempty string, these MUST be the same value.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-variable"> symbol</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * The decimals of the ERC-20 token. </span></span> <span class="giallo-l"><span class="z-comment"> * If the `decimals()` function is present in the ERC-20 token, these MUST be the same value.</span></span> <span class="giallo-l"><span class="z-comment"> * Defaults to 18 if neither this parameter nor the ERC-20 `decimals()` function are present.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-variable"> decimals</span><span class="z-keyword">?</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 class="z-punctuation z-definition z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * Provides a short one-paragraph description of the ERC-20 token, without any markup or newlines.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-variable"> description</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * A URI pointing to a resource with mime type `image/*` that represents this token.</span></span> <span class="giallo-l"><span class="z-comment"> * If the image is a bitmap, it SHOULD have a width between 320 and 1080 pixels</span></span> <span class="giallo-l"><span class="z-comment"> * The image SHOULD have an aspect ratio between 1.91:1 and 4:5 inclusive.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-variable"> image</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * One or more URIs each pointing to a resource with mime type `image/*` that represents this token.</span></span> <span class="giallo-l"><span class="z-comment"> * If an image is a bitmap, it SHOULD have a width between 320 and 1080 pixels</span></span> <span class="giallo-l"><span class="z-comment"> * Images SHOULD have an aspect ratio between 1.91:1 and 4:5 inclusive.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-variable"> images</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> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * One or more URIs each pointing to a resource with mime type `image/*` that represent an icon for this token.</span></span> <span class="giallo-l"><span class="z-comment"> * If an image is a bitmap, it SHOULD have a width between 320 and 1080 pixels, and MUST have a height equal to its width</span></span> <span class="giallo-l"><span class="z-comment"> * Images MUST have an aspect ratio of 1:1, and use a transparent background</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-variable"> icons</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><h3 id="erc-721-extension">ERC-721 Extension</h3> <h4 id="extension-to-the-erc-721-metadata-schema">Extension to the ERC-721 Metadata Schema</h4> <p>Contracts that implement ERC-721 and use its token metadata URI SHOULD to use the following TypeScript extension to the metadata URI:</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"> ERC721TokenMetadataInterop</span><span class="z-storage"> extends</span><span class="z-entity"> ERC721TokenMetadata</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"> * Interoperability, to avoid confusion between different token URIs</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-variable"> interop</span><span class="z-keyword">:</span><span class="z-entity z-name"> InteroperabilityMetadata</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="erc-1155-extension">ERC-1155 Extension</h3> <h4 id="erc-1155-interface-extension">ERC-1155 Interface Extension</h4> <p><a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>-compliant contracts using the metadata extension SHOULD implement the following Solidity 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-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-1155 Metadata URI Interoperability Extension</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC1155TokenMetadataInterop</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC1155 </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"> Gets an ERC-1046-compliant ERC-1155 token URI</span></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 get the URI of</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The resolved data MUST be in JSON format and support ERC-1046&#39;s Extension to the ERC-1155 Token Metadata Schema</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This MUST be the same URI as the `uri(tokenId)` function, if present.</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>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="extension-to-the-erc-1155-metadata-schema">Extension to the ERC-1155 Metadata Schema</h4> <p>Contracts that implement ERC-1155 and use its token metadata URI are RECOMMENDED to use the following extension to the metadata URI. Contracts that implement the interface described in the ERC-1155 Interface Extension section MUST use the following TypeScript extension:</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"> ERC1155TokenMetadataInterop</span><span class="z-storage"> extends</span><span class="z-entity"> ERC1155TokenMetadata</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"> * Interoperability, to avoid confusion between different token URIs</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-variable"> interop</span><span class="z-keyword">:</span><span class="z-entity z-name"> InteroperabilityMetadata</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="miscellaneous-recommendations">Miscellaneous Recommendations</h3> <p>To save gas, it is RECOMMENDED for compliant contracts not to implement the <code>name()</code>, <code>symbol()</code>, or <code>decimals()</code> functions, and instead to only include them in the metadata URI. Additionally, for ERC-20 tokens, if the decimals is <code>18</code>, then it is NOT RECOMMENDED to include the <code>decimals</code> field in the metadata.</p> <h2 id="rationale">Rationale</h2> <p>This ERC makes adding metadata to ERC-20 tokens more straightforward for developers, with minimal to no disruption to the overall ecosystem. Using the same parameter name makes it easier to reuse code.</p> <p>Additionally, the recommendations not to use ERC-20's <code>name</code>, <code>symbol</code>, and <code>decimals</code> functions save gas.</p> <p>Built-in interoperability is useful as otherwise it might not be easy to differentiate the type of the token. Interoperability could be done using <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>, but static calls are time-inefficient for wallets and websites, and is generally inflexible. Instead, including interoperability data in the token URI increases flexibility while also giving a performance increase.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible as its implementation simply extends the functionality of ERC-20 tokens and is optional. Additionally, it makes backward compatible recommendations for ERC-721 and ERC-1155 tokens.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="server-side-request-forgery-ssrf">Server-Side Request Forgery (SSRF)</h3> <p>Wallets should be careful about making arbitrary requests to URLs. As such, it is recommended for wallets to sanitize the URI by whitelisting specific schemes and ports. A vulnerable wallet could be tricked into, for example, modifying data on a locally-hosted redis database.</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-04T00:00:00+00:00 2026-02-11T14:49:27+00:00 Afri Schoedonhttps://github.com/5chdn https://wg-eips.ritovision.com/999/ <h2 id="simple-summary">Simple Summary</h2> <p>This document proposes to restore the contract code of the <code>WalletLibrary</code> contract at <code>0x863DF6BFa4469f3ead0bE8f9F2AAE51c91A907b4</code> with a patched version. The contract was accidentally self-destructed and renders a significant amount of Ether inaccessible.</p> <h2 id="abstract">Abstract</h2> <p>The <code>WalletLibrary</code> contract was used by the <a rel="external" href="https://www.parity.io/">Parity Wallet</a> to reduce gas costs for users deploying multi-signature wallets on the Ethereum blockchain. It contained basic functionality such as confirming or revoking multi-signature transactions for any wallet deployed that depends on this library. The <a rel="external" href="https://github.com/paritytech/parity/issues/6995">accidental self-destruction</a> of the library contract caused significant amounts of Ether and other assets owned by many different parties to be inaccessible. This proposal suggests restoring the <code>WalletLibrary</code> by a <a rel="external" href="https://github.com/parity-contracts/0x863df6bfa4">patched</a> version to allow the owners of the dependent multi-signature wallets regain access to their assets.</p> <h2 id="motivation">Motivation</h2> <p>This proposal is necessary because the Ethereum protocol does not allow the restoration of self-destructed contracts and there is no other simple way to enable the affected users and companies regaining access to their tokens and Ether. In opposite to previously discussed proposals, this will not change any EVM semantics and tries to achieve the goal of unfreezing the funds by a single state transition as specified in the next section.</p> <h2 id="specification">Specification</h2> <p>The self-destructed contract code at <a rel="external" href="https://etherscan.io/address/0x863df6bfa4469f3ead0be8f9f2aae51c91a907b4#code"><code>0x863DF6BFa4469f3ead0bE8f9F2AAE51c91A907b4</code></a> shall be replaced with a patched version of the <a rel="external" href="https://github.com/parity-contracts/0x863df6bfa4/blob/master/contracts/walletLibrary.sol"><code>walletLibrary.sol</code></a> as reviewed, tested, and approved in <a rel="external" href="https://github.com/parity-contracts/0x863df6bfa4">parity-contracts/0x863df6bfa4</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">object</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">606060405234156200000d57fe5b5b6000808054806001018281620000259190620002d9565b916000526020600020900160005b6000909190916101000a81548173ffffffffffffffffffffffffffffffffffffffff021916908373ffffffffffffffffffffffffffffffffffffffff160217905550506200012081805480602002602001604051908101604052809291908181526020018280548015620000fd57602002820191906000526020600020905b8160009054906101000a900473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020019060010190808311620000b2575b505050505060016000620001286401000000000262001d46176401000000009004565b5b5062000330565b600060015411156200013a5760006000fd5b6200015981620001806401000000000262001d71176401000000009004565b620001798383620001c26401000000000262001d9c176401000000009004565b5b5b505050565b60006001541115620001925760006000fd5b80600281905550620001b7620002c16401000000000262001bcf176401000000009004565b6004819055505b5b50565b600060006001541115620001d65760006000fd5b600082111515620001e75760006000fd5b81835110151515620001f95760006000fd5b8251600181905550600090505b8251811015620002b35782818151811015156200021f57fe5b9060200190602002015173ffffffffffffffffffffffffffffffffffffffff16600582600101610100811015156200025357fe5b0160005b508190555080600101610105600085848151811015156200027457fe5b9060200190602002015173ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020819055505b80600101905062000206565b816000819055505b5b505050565b60006201518042811515620002d257fe5b0490505b90565b815481835581811511620003035781836000526020600020918201910162000302919062000308565b5b505050565b6200032d91905b80821115620003295760008160009055506001016200030f565b5090565b90565b611ebf80620003406000396000f300606060405236156100ef576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff168063173825d91461016d5780632f54bf6e146101a35780634123cb6b146101f157806352375093146102175780635c52c2f51461023d578063659010e71461024f5780637065cb4814610275578063746c9171146102ab578063797af627146102d1578063b20d30a91461030d578063b61d27f61461032d578063b75c7dc61461039c578063ba51a6df146103c0578063c2cf7326146103e0578063c41a360a1461043b578063f00d4b5d1461049b578063f1736d86146104f0575b61016b5b6000341115610168577fe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d3c460751c2402c5c5cc9109c3334604051808373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020018281526020019250505060405180910390a15b5b565b005b341561017557fe5b6101a1600480803573ffffffffffffffffffffffffffffffffffffffff16906020019091905050610516565b005b34156101ab57fe5b6101d7600480803573ffffffffffffffffffffffffffffffffffffffff16906020019091905050610659565b604051808215151515815260200191505060405180910390f35b34156101f957fe5b610201610691565b6040518082815260200191505060405180910390f35b341561021f57fe5b610227610697565b6040518082815260200191505060405180910390f35b341561024557fe5b61024d61069d565b005b341561025757fe5b61025f6106d7565b6040518082815260200191505060405180910390f35b341561027d57fe5b6102a9600480803573ffffffffffffffffffffffffffffffffffffffff169060200190919050506106dd565b005b34156102b357fe5b6102bb610829565b6040518082815260200191505060405180910390f35b34156102d957fe5b6102f360048080356000191690602001909190505061082f565b604051808215151515815260200191505060405180910390f35b341561031557fe5b61032b6004808035906020019091905050610dcc565b005b341561033557fe5b61037e600480803573ffffffffffffffffffffffffffffffffffffffff169060200190919080359060200190919080359060200190820180359060200191909192905050610e06565b60405180826000191660001916815260200191505060405180910390f35b34156103a457fe5b6103be60048080356000191690602001909190505061127d565b005b34156103c857fe5b6103de6004808035906020019091905050611392565b005b34156103e857fe5b61042160048080356000191690602001909190803573ffffffffffffffffffffffffffffffffffffffff1690602001909190505061141a565b604051808215151515815260200191505060405180910390f35b341561044357fe5b610459600480803590602001909190505061149c565b604051808273ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200191505060405180910390f35b34156104a357fe5b6104ee600480803573ffffffffffffffffffffffffffffffffffffffff1690602001909190803573ffffffffffffffffffffffffffffffffffffffff169060200190919050506114bf565b005b34156104f857fe5b610500611672565b6040518082815260200191505060405180910390f35b600060003660405180838380828437820191505092505050604051809103902061053f81611678565b156106535761010560008473ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020549150600082141561057f57610652565b600160015403600054111561059357610652565b6000600583610100811015156105a557fe5b0160005b5081905550600061010560008573ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020819055506105e6611890565b6105ee6119d0565b7f58619076adf5bb0943d100ef88d52d7c3fd691b19d3a9071b555b651fbf418da83604051808273ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200191505060405180910390a15b5b5b505050565b6000600061010560008473ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020541190505b919050565b60015481565b60045481565b6000366040518083838082843782019150509250505060405180910390206106c481611678565b156106d35760006003819055505b5b5b50565b60035481565b60003660405180838380828437820191505092505050604051809103902061070481611678565b156108245761071282610659565b1561071c57610823565b610724611890565b60fa600154101515610739576107386119d0565b5b60fa60015410151561074a57610823565b6001600081548092919060010191905055508173ffffffffffffffffffffffffffffffffffffffff1660056001546101008110151561078557fe5b0160005b508190555060015461010560008473ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020819055507f994a936646fe87ffe4f1e469d3d6aa417d6b855598397f323de5b449f765f0c382604051808273ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200191505060405180910390a15b5b5b5050565b60005481565b600060008261083d81611678565b15610dc45760006101086000866000191660001916815260200190815260200160002060000160009054906101000a900473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff161415806108c757506000610108600086600019166000191681526020019081526020016000206001015414155b80610906575060006101086000866000191660001916815260200190815260200160002060020180546001816001161561010002031660029004905014155b15610dc25760006101086000866000191660001916815260200190815260200160002060000160009054906101000a900473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff161415610a5057610a496101086000866000191660001916815260200190815260200160002060010154610108600087600019166000191681526020019081526020016000206002018054600181600116156101000203166002900480601f016020809104026020016040519081016040528092919081815260200182805460018160011615610100020316600290048015610a3f5780601f10610a1457610100808354040283529160200191610a3f565b820191906000526020600020905b815481529060010190602001808311610a2257829003601f168201915b5050505050611b37565b9150610b71565b6101086000856000191660001916815260200190815260200160002060000160009054906101000a900473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff166101086000866000191660001916815260200190815260200160002060010154610108600087600019166000191681526020019081526020016000206002016040518082805460018160011615610100020316600290048015610b4a5780601f10610b1f57610100808354040283529160200191610b4a565b820191906000526020600020905b815481529060010190602001808311610b2d57829003601f168201915b505091505060006040518083038185876185025a03f1925050501515610b705760006000fd5b5b7fe3a3a4111a84df27d76b68dc721e65c7711605ea5eee4afd3a9c58195217365c338561010860008860001916600019168152602001908152602001600020600101546101086000896000191660001916815260200190815260200160002060000160009054906101000a900473ffffffffffffffffffffffffffffffffffffffff1661010860008a6000191660001916815260200190815260200160002060020187604051808773ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200186600019166000191681526020018581526020018473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff168152602001806020018373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff168152602001828103825284818154600181600116156101000203166002900481526020019150805460018160011615610100020316600290048015610d475780601f10610d1c57610100808354040283529160200191610d47565b820191906000526020600020905b815481529060010190602001808311610d2a57829003601f168201915b505097505050505050505060405180910390a16101086000856000191660001916815260200190815260200160002060006000820160006101000a81549073ffffffffffffffffffffffffffffffffffffffff02191690556001820160009055600282016000610db79190611be6565b505060019250610dc3565b5b5b5b5050919050565b600036604051808383808284378201915050925050506040518091039020610df381611678565b15610e0157816002819055505b5b5b5050565b60006000610e1333610659565b1561127357600084849050148015610e305750610e2f85611b51565b5b80610e3d57506001600054145b15610fed5760008673ffffffffffffffffffffffffffffffffffffffff161415610ea457610e9d8585858080601f016020809104026020016040519081016040528093929190818152602001838380828437820191505050505050611b37565b9050610ef3565b8573ffffffffffffffffffffffffffffffffffffffff168585856040518083838082843782019150509250505060006040518083038185876185025a03f1925050501515610ef25760006000fd5b5b7f9738cd1a8777c86b011f7b01d87d484217dc6ab5154a9d41eda5d14af8caf292338688878786604051808773ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020018681526020018573ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff168152602001806020018373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020018281038252858582818152602001925080828437820191505097505050505050505060405180910390a1611271565b6000364360405180848480828437820191505082815260200193505050506040518091039020915060006101086000846000191660001916815260200190815260200160002060000160009054906101000a900473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16148015611099575060006101086000846000191660001916815260200190815260200160002060010154145b80156110d85750600061010860008460001916600019168152602001908152602001600020600201805460018160011615610100020316600290049050145b1561118f57856101086000846000191660001916815260200190815260200160002060000160006101000a81548173ffffffffffffffffffffffffffffffffffffffff021916908373ffffffffffffffffffffffffffffffffffffffff160217905550846101086000846000191660001916815260200190815260200160002060010181905550838361010860008560001916600019168152602001908152602001600020600201919061118d929190611c2e565b505b6111988261082f565b1515611270577f1733cbb53659d713b79580f79f3f9ff215f78a7c7aa45890f3b89fc5cddfbf328233878988886040518087600019166000191681526020018673ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020018581526020018473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff168152602001806020018281038252848482818152602001925080828437820191505097505050505050505060405180910390a15b5b5b5b5b50949350505050565b60006000600061010560003373ffffffffffffffffffffffffffffffffffffffff16815260200190815260200160002054925060008314156112be5761138c565b8260020a9150610106600085600019166000191681526020019081526020016000209050600082826001015416111561138b5780600001600081548092919060010191905055508181600101600082825403925050819055507fc7fb647e59b18047309aa15aad418e5d7ca96d173ad704f1031a2c3d7591734b3385604051808373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200182600019166000191681526020019250505060405180910390a15b5b50505050565b6000366040518083838082843782019150509250505060405180910390206113b981611678565b15611415576001548211156113cd57611414565b816000819055506113dc611890565b7facbdb084c721332ac59f9b8e392196c9eb0e4932862da8eb9beaf0dad4f550da826040518082815260200191505060405180910390a15b5b5b5050565b600060006000600061010660008760001916600019168152602001908152602001600020925061010560008673ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020549150600082141561147f5760009350611493565b8160020a9050600081846001015416141593505b50505092915050565b6000600560018301610100811015156114b157fe5b0160005b505490505b919050565b60006000366040518083838082843782019150509250505060405180910390206114e881611678565b1561166b576114f683610659565b156115005761166a565b61010560008573ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020549150600082141561153b5761166a565b611543611890565b8273ffffffffffffffffffffffffffffffffffffffff166005836101008110151561156a57fe5b0160005b5081905550600061010560008673ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020819055508161010560008573ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020819055507fb532073b38c83145e3e5135377a08bf9aab55bc0fd7c1179cd4fb995d2a5159c8484604051808373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020018273ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020019250505060405180910390a15b5b5b50505050565b60025481565b600060006000600061010560003373ffffffffffffffffffffffffffffffffffffffff16815260200190815260200160002054925060008314156116bb57611888565b6101066000866000191660001916815260200190815260200160002091506000826000015414156117455760005482600001819055506000826001018190555061010780548091906001016117109190611cae565b826002018190555084610107836002015481548110151561172d57fe5b906000526020600020900160005b5081600019169055505b8260020a90506000818360010154161415611887577fe1c52dc63b719ade82e8bea94cc41a0d5d28e4aaf536adb5e9cccc9ff8c1aeda3386604051808373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200182600019166000191681526020019250505060405180910390a16001826000015411151561185e57610107610106600087600019166000191681526020019081526020016000206002015481548110151561180a57fe5b906000526020600020900160005b5060009055610106600086600019166000191681526020019081526020016000206000600082016000905560018201600090556002820160009055505060019350611888565b8160000160008154809291906001900391905055508082600101600082825417925050819055505b5b5b505050919050565b60006000610107805490509150600090505b818110156119bc576101086000610107838154811015156118bf57fe5b906000526020600020900160005b50546000191660001916815260200190815260200160002060006000820160006101000a81549073ffffffffffffffffffffffffffffffffffffffff021916905560018201600090556002820160006119269190611be6565b505060006001026101078281548110151561193d57fe5b906000526020600020900160005b5054600019161415156119b05761010660006101078381548110151561196d57fe5b906000526020600020900160005b505460001916600019168152602001908152602001600020600060008201600090556001820160009055600282016000905550505b5b8060010190506118a2565b61010760006119cb9190611cda565b5b5050565b6000600190505b600154811015611b33575b60015481108015611a095750600060058261010081101515611a0057fe5b0160005b505414155b15611a1b5780806001019150506119e2565b5b6001600154118015611a4557506000600560015461010081101515611a3d57fe5b0160005b5054145b15611a625760016000815480929190600190039190505550611a1c565b60015481108015611a8b57506000600560015461010081101515611a8257fe5b0160005b505414155b8015611aac5750600060058261010081101515611aa457fe5b0160005b5054145b15611b2e57600560015461010081101515611ac357fe5b0160005b505460058261010081101515611ad957fe5b0160005b508190555080610105600060058461010081101515611af857fe5b0160005b50548152602001908152602001600020819055506000600560015461010081101515611b2457fe5b0160005b50819055505b6119d7565b5b50565b600081516020830184f09050803b15610000575b92915050565b6000611b5c33610659565b15611bc957600454611b6c611bcf565b1115611b89576000600381905550611b82611bcf565b6004819055505b600354826003540110158015611ba55750600254826003540111155b15611bc3578160036000828254019250508190555060019050611bc8565b600090505b5b5b919050565b60006201518042811515611bdf57fe5b0490505b90565b50805460018160011615610100020316600290046000825580601f10611c0c5750611c2b565b601f016020900490600052602060002090810190611c2a9190611cfc565b5b50565b828054600181600116156101000203166002900490600052602060002090601f016020900481019282601f10611c6f57803560ff1916838001178555611c9d565b82800160010185558215611c9d579182015b82811115611c9c578235825591602001919060010190611c81565b5b509050611caa9190611cfc565b5090565b815481835581811511611cd557818360005260206000209182019101611cd49190611d21565b5b505050565b5080546000825590600052602060002090810190611cf89190611d21565b5b50565b611d1e91905b80821115611d1a576000816000905550600101611d02565b5090565b90565b611d4391905b80821115611d3f576000816000905550600101611d27565b5090565b90565b60006001541115611d575760006000fd5b611d6081611d71565b611d6a8383611d9c565b5b5b505050565b60006001541115611d825760006000fd5b80600281905550611d91611bcf565b6004819055505b5b50565b600060006001541115611daf5760006000fd5b600082111515611dbf5760006000fd5b81835110151515611dd05760006000fd5b8251600181905550600090505b8251811015611e85578281815181101515611df457fe5b9060200190602002015173ffffffffffffffffffffffffffffffffffffffff1660058260010161010081101515611e2757fe5b0160005b50819055508060010161010560008584815181101515611e4757fe5b9060200190602002015173ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020819055505b806001019050611ddd565b816000819055505b5b5050505600a165627a7a7230582016889f0740f073d397f9d00b0d19900fb050b957e3e2942f861085beb9baab180029</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">opcodes</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">PUSH1 0x60 PUSH1 0x40 MSTORE CALLVALUE ISZERO PUSH3 0xD JUMPI INVALID JUMPDEST JUMPDEST PUSH1 0x0 DUP1 DUP1 SLOAD DUP1 PUSH1 0x1 ADD DUP3 DUP2 PUSH3 0x25 SWAP2 SWAP1 PUSH3 0x2D9 JUMP JUMPDEST SWAP2 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 SHA3 SWAP1 ADD PUSH1 0x0 JUMPDEST PUSH1 0x0 SWAP1 SWAP2 SWAP1 SWAP2 PUSH2 0x100 EXP DUP2 SLOAD DUP2 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF MUL NOT AND SWAP1 DUP4 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND MUL OR SWAP1 SSTORE POP POP PUSH3 0x120 DUP2 DUP1 SLOAD DUP1 PUSH1 0x20 MUL PUSH1 0x20 ADD PUSH1 0x40 MLOAD SWAP1 DUP2 ADD PUSH1 0x40 MSTORE DUP1 SWAP3 SWAP2 SWAP1 DUP2 DUP2 MSTORE PUSH1 0x20 ADD DUP3 DUP1 SLOAD DUP1 ISZERO PUSH3 0xFD JUMPI PUSH1 0x20 MUL DUP3 ADD SWAP2 SWAP1 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 SHA3 SWAP1 JUMPDEST DUP2 PUSH1 0x0 SWAP1 SLOAD SWAP1 PUSH2 0x100 EXP SWAP1 DIV PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 PUSH1 0x1 ADD SWAP1 DUP1 DUP4 GT PUSH3 0xB2 JUMPI JUMPDEST POP POP POP POP POP PUSH1 0x1 PUSH1 0x0 PUSH3 0x128 PUSH5 0x100000000 MUL PUSH3 0x1D46 OR PUSH5 0x100000000 SWAP1 DIV JUMP JUMPDEST JUMPDEST POP PUSH3 0x330 JUMP JUMPDEST PUSH1 0x0 PUSH1 0x1 SLOAD GT ISZERO PUSH3 0x13A JUMPI PUSH1 0x0 PUSH1 0x0 REVERT JUMPDEST PUSH3 0x159 DUP2 PUSH3 0x180 PUSH5 0x100000000 MUL PUSH3 0x1D71 OR PUSH5 0x100000000 SWAP1 DIV JUMP JUMPDEST PUSH3 0x179 DUP4 DUP4 PUSH3 0x1C2 PUSH5 0x100000000 MUL PUSH3 0x1D9C OR PUSH5 0x100000000 SWAP1 DIV JUMP JUMPDEST JUMPDEST JUMPDEST POP POP POP JUMP JUMPDEST PUSH1 0x0 PUSH1 0x1 SLOAD GT ISZERO PUSH3 0x192 JUMPI PUSH1 0x0 PUSH1 0x0 REVERT JUMPDEST DUP1 PUSH1 0x2 DUP2 SWAP1 SSTORE POP PUSH3 0x1B7 PUSH3 0x2C1 PUSH5 0x100000000 MUL PUSH3 0x1BCF OR PUSH5 0x100000000 SWAP1 DIV JUMP JUMPDEST PUSH1 0x4 DUP2 SWAP1 SSTORE POP JUMPDEST JUMPDEST POP JUMP JUMPDEST PUSH1 0x0 PUSH1 0x0 PUSH1 0x1 SLOAD GT ISZERO PUSH3 0x1D6 JUMPI PUSH1 0x0 PUSH1 0x0 REVERT JUMPDEST PUSH1 0x0 DUP3 GT ISZERO ISZERO PUSH3 0x1E7 JUMPI PUSH1 0x0 PUSH1 0x0 REVERT JUMPDEST DUP2 DUP4 MLOAD LT ISZERO ISZERO ISZERO PUSH3 0x1F9 JUMPI PUSH1 0x0 PUSH1 0x0 REVERT JUMPDEST DUP3 MLOAD PUSH1 0x1 DUP2 SWAP1 SSTORE POP PUSH1 0x0 SWAP1 POP JUMPDEST DUP3 MLOAD DUP2 LT ISZERO PUSH3 0x2B3 JUMPI DUP3 DUP2 DUP2 MLOAD DUP2 LT ISZERO ISZERO PUSH3 0x21F JUMPI INVALID JUMPDEST SWAP1 PUSH1 0x20 ADD SWAP1 PUSH1 0x20 MUL ADD MLOAD PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH1 0x5 DUP3 PUSH1 0x1 ADD PUSH2 0x100 DUP2 LT ISZERO ISZERO PUSH3 0x253 JUMPI INVALID JUMPDEST ADD PUSH1 0x0 JUMPDEST POP DUP2 SWAP1 SSTORE POP DUP1 PUSH1 0x1 ADD PUSH2 0x105 PUSH1 0x0 DUP6 DUP5 DUP2 MLOAD DUP2 LT ISZERO ISZERO PUSH3 0x274 JUMPI INVALID JUMPDEST SWAP1 PUSH1 0x20 ADD SWAP1 PUSH1 0x20 MUL ADD MLOAD PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 DUP2 SWAP1 SSTORE POP JUMPDEST DUP1 PUSH1 0x1 ADD SWAP1 POP PUSH3 0x206 JUMP JUMPDEST DUP2 PUSH1 0x0 DUP2 SWAP1 SSTORE POP JUMPDEST JUMPDEST POP POP POP JUMP JUMPDEST PUSH1 0x0 PUSH3 0x15180 TIMESTAMP DUP2 ISZERO ISZERO PUSH3 0x2D2 JUMPI INVALID JUMPDEST DIV SWAP1 POP JUMPDEST SWAP1 JUMP JUMPDEST DUP2 SLOAD DUP2 DUP4 SSTORE DUP2 DUP2 ISZERO GT PUSH3 0x303 JUMPI DUP2 DUP4 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 SHA3 SWAP2 DUP3 ADD SWAP2 ADD PUSH3 0x302 SWAP2 SWAP1 PUSH3 0x308 JUMP JUMPDEST JUMPDEST POP POP POP JUMP JUMPDEST PUSH3 0x32D SWAP2 SWAP1 JUMPDEST DUP1 DUP3 GT ISZERO PUSH3 0x329 JUMPI PUSH1 0x0 DUP2 PUSH1 0x0 SWAP1 SSTORE POP PUSH1 0x1 ADD PUSH3 0x30F JUMP JUMPDEST POP SWAP1 JUMP JUMPDEST SWAP1 JUMP JUMPDEST PUSH2 0x1EBF DUP1 PUSH3 0x340 PUSH1 0x0 CODECOPY PUSH1 0x0 RETURN STOP PUSH1 0x60 PUSH1 0x40 MSTORE CALLDATASIZE ISZERO PUSH2 0xEF JUMPI PUSH1 0x0 CALLDATALOAD PUSH29 0x100000000000000000000000000000000000000000000000000000000 SWAP1 DIV PUSH4 0xFFFFFFFF AND DUP1 PUSH4 0x173825D9 EQ PUSH2 0x16D JUMPI DUP1 PUSH4 0x2F54BF6E EQ PUSH2 0x1A3 JUMPI DUP1 PUSH4 0x4123CB6B EQ PUSH2 0x1F1 JUMPI DUP1 PUSH4 0x52375093 EQ PUSH2 0x217 JUMPI DUP1 PUSH4 0x5C52C2F5 EQ PUSH2 0x23D JUMPI DUP1 PUSH4 0x659010E7 EQ PUSH2 0x24F JUMPI DUP1 PUSH4 0x7065CB48 EQ PUSH2 0x275 JUMPI DUP1 PUSH4 0x746C9171 EQ PUSH2 0x2AB JUMPI DUP1 PUSH4 0x797AF627 EQ PUSH2 0x2D1 JUMPI DUP1 PUSH4 0xB20D30A9 EQ PUSH2 0x30D JUMPI DUP1 PUSH4 0xB61D27F6 EQ PUSH2 0x32D JUMPI DUP1 PUSH4 0xB75C7DC6 EQ PUSH2 0x39C JUMPI DUP1 PUSH4 0xBA51A6DF EQ PUSH2 0x3C0 JUMPI DUP1 PUSH4 0xC2CF7326 EQ PUSH2 0x3E0 JUMPI DUP1 PUSH4 0xC41A360A EQ PUSH2 0x43B JUMPI DUP1 PUSH4 0xF00D4B5D EQ PUSH2 0x49B JUMPI DUP1 PUSH4 0xF1736D86 EQ PUSH2 0x4F0 JUMPI JUMPDEST PUSH2 0x16B JUMPDEST PUSH1 0x0 CALLVALUE GT ISZERO PUSH2 0x168 JUMPI PUSH32 0xE1FFFCC4923D04B559F4D29A8BFC6CDA04EB5B0D3C460751C2402C5C5CC9109C CALLER CALLVALUE PUSH1 0x40 MLOAD DUP1 DUP4 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD DUP3 DUP2 MSTORE PUSH1 0x20 ADD SWAP3 POP POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 LOG1 JUMPDEST JUMPDEST JUMP JUMPDEST STOP JUMPDEST CALLVALUE ISZERO PUSH2 0x175 JUMPI INVALID JUMPDEST PUSH2 0x1A1 PUSH1 0x4 DUP1 DUP1 CALLDATALOAD PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND SWAP1 PUSH1 0x20 ADD SWAP1 SWAP2 SWAP1 POP POP PUSH2 0x516 JUMP JUMPDEST STOP JUMPDEST CALLVALUE ISZERO PUSH2 0x1AB JUMPI INVALID JUMPDEST PUSH2 0x1D7 PUSH1 0x4 DUP1 DUP1 CALLDATALOAD PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND SWAP1 PUSH1 0x20 ADD SWAP1 SWAP2 SWAP1 POP POP PUSH2 0x659 JUMP JUMPDEST PUSH1 0x40 MLOAD DUP1 DUP3 ISZERO ISZERO ISZERO ISZERO DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 RETURN JUMPDEST CALLVALUE ISZERO PUSH2 0x1F9 JUMPI INVALID JUMPDEST PUSH2 0x201 PUSH2 0x691 JUMP JUMPDEST PUSH1 0x40 MLOAD DUP1 DUP3 DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 RETURN JUMPDEST CALLVALUE ISZERO PUSH2 0x21F JUMPI INVALID JUMPDEST PUSH2 0x227 PUSH2 0x697 JUMP JUMPDEST PUSH1 0x40 MLOAD DUP1 DUP3 DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 RETURN JUMPDEST CALLVALUE ISZERO PUSH2 0x245 JUMPI INVALID JUMPDEST PUSH2 0x24D PUSH2 0x69D JUMP JUMPDEST STOP JUMPDEST CALLVALUE ISZERO PUSH2 0x257 JUMPI INVALID JUMPDEST PUSH2 0x25F PUSH2 0x6D7 JUMP JUMPDEST PUSH1 0x40 MLOAD DUP1 DUP3 DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 RETURN JUMPDEST CALLVALUE ISZERO PUSH2 0x27D JUMPI INVALID JUMPDEST PUSH2 0x2A9 PUSH1 0x4 DUP1 DUP1 CALLDATALOAD PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND SWAP1 PUSH1 0x20 ADD SWAP1 SWAP2 SWAP1 POP POP PUSH2 0x6DD JUMP JUMPDEST STOP JUMPDEST CALLVALUE ISZERO PUSH2 0x2B3 JUMPI INVALID JUMPDEST PUSH2 0x2BB PUSH2 0x829 JUMP JUMPDEST PUSH1 0x40 MLOAD DUP1 DUP3 DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 RETURN JUMPDEST CALLVALUE ISZERO PUSH2 0x2D9 JUMPI INVALID JUMPDEST PUSH2 0x2F3 PUSH1 0x4 DUP1 DUP1 CALLDATALOAD PUSH1 0x0 NOT AND SWAP1 PUSH1 0x20 ADD SWAP1 SWAP2 SWAP1 POP POP PUSH2 0x82F JUMP JUMPDEST PUSH1 0x40 MLOAD DUP1 DUP3 ISZERO ISZERO ISZERO ISZERO DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 RETURN JUMPDEST CALLVALUE ISZERO PUSH2 0x315 JUMPI INVALID JUMPDEST PUSH2 0x32B PUSH1 0x4 DUP1 DUP1 CALLDATALOAD SWAP1 PUSH1 0x20 ADD SWAP1 SWAP2 SWAP1 POP POP PUSH2 0xDCC JUMP JUMPDEST STOP JUMPDEST CALLVALUE ISZERO PUSH2 0x335 JUMPI INVALID JUMPDEST PUSH2 0x37E PUSH1 0x4 DUP1 DUP1 CALLDATALOAD PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND SWAP1 PUSH1 0x20 ADD SWAP1 SWAP2 SWAP1 DUP1 CALLDATALOAD SWAP1 PUSH1 0x20 ADD SWAP1 SWAP2 SWAP1 DUP1 CALLDATALOAD SWAP1 PUSH1 0x20 ADD SWAP1 DUP3 ADD DUP1 CALLDATALOAD SWAP1 PUSH1 0x20 ADD SWAP2 SWAP1 SWAP2 SWAP3 SWAP1 POP POP PUSH2 0xE06 JUMP JUMPDEST PUSH1 0x40 MLOAD DUP1 DUP3 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 RETURN JUMPDEST CALLVALUE ISZERO PUSH2 0x3A4 JUMPI INVALID JUMPDEST PUSH2 0x3BE PUSH1 0x4 DUP1 DUP1 CALLDATALOAD PUSH1 0x0 NOT AND SWAP1 PUSH1 0x20 ADD SWAP1 SWAP2 SWAP1 POP POP PUSH2 0x127D JUMP JUMPDEST STOP JUMPDEST CALLVALUE ISZERO PUSH2 0x3C8 JUMPI INVALID JUMPDEST PUSH2 0x3DE PUSH1 0x4 DUP1 DUP1 CALLDATALOAD SWAP1 PUSH1 0x20 ADD SWAP1 SWAP2 SWAP1 POP POP PUSH2 0x1392 JUMP JUMPDEST STOP JUMPDEST CALLVALUE ISZERO PUSH2 0x3E8 JUMPI INVALID JUMPDEST PUSH2 0x421 PUSH1 0x4 DUP1 DUP1 CALLDATALOAD PUSH1 0x0 NOT AND SWAP1 PUSH1 0x20 ADD SWAP1 SWAP2 SWAP1 DUP1 CALLDATALOAD PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND SWAP1 PUSH1 0x20 ADD SWAP1 SWAP2 SWAP1 POP POP PUSH2 0x141A JUMP JUMPDEST PUSH1 0x40 MLOAD DUP1 DUP3 ISZERO ISZERO ISZERO ISZERO DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 RETURN JUMPDEST CALLVALUE ISZERO PUSH2 0x443 JUMPI INVALID JUMPDEST PUSH2 0x459 PUSH1 0x4 DUP1 DUP1 CALLDATALOAD SWAP1 PUSH1 0x20 ADD SWAP1 SWAP2 SWAP1 POP POP PUSH2 0x149C JUMP JUMPDEST PUSH1 0x40 MLOAD DUP1 DUP3 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 RETURN JUMPDEST CALLVALUE ISZERO PUSH2 0x4A3 JUMPI INVALID JUMPDEST PUSH2 0x4EE PUSH1 0x4 DUP1 DUP1 CALLDATALOAD PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND SWAP1 PUSH1 0x20 ADD SWAP1 SWAP2 SWAP1 DUP1 CALLDATALOAD PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND SWAP1 PUSH1 0x20 ADD SWAP1 SWAP2 SWAP1 POP POP PUSH2 0x14BF JUMP JUMPDEST STOP JUMPDEST CALLVALUE ISZERO PUSH2 0x4F8 JUMPI INVALID JUMPDEST PUSH2 0x500 PUSH2 0x1672 JUMP JUMPDEST PUSH1 0x40 MLOAD DUP1 DUP3 DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 RETURN JUMPDEST PUSH1 0x0 PUSH1 0x0 CALLDATASIZE PUSH1 0x40 MLOAD DUP1 DUP4 DUP4 DUP1 DUP3 DUP5 CALLDATACOPY DUP3 ADD SWAP2 POP POP SWAP3 POP POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 SHA3 PUSH2 0x53F DUP2 PUSH2 0x1678 JUMP JUMPDEST ISZERO PUSH2 0x653 JUMPI PUSH2 0x105 PUSH1 0x0 DUP5 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 SLOAD SWAP2 POP PUSH1 0x0 DUP3 EQ ISZERO PUSH2 0x57F JUMPI PUSH2 0x652 JUMP JUMPDEST PUSH1 0x1 PUSH1 0x1 SLOAD SUB PUSH1 0x0 SLOAD GT ISZERO PUSH2 0x593 JUMPI PUSH2 0x652 JUMP JUMPDEST PUSH1 0x0 PUSH1 0x5 DUP4 PUSH2 0x100 DUP2 LT ISZERO ISZERO PUSH2 0x5A5 JUMPI INVALID JUMPDEST ADD PUSH1 0x0 JUMPDEST POP DUP2 SWAP1 SSTORE POP PUSH1 0x0 PUSH2 0x105 PUSH1 0x0 DUP6 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 DUP2 SWAP1 SSTORE POP PUSH2 0x5E6 PUSH2 0x1890 JUMP JUMPDEST PUSH2 0x5EE PUSH2 0x19D0 JUMP JUMPDEST PUSH32 0x58619076ADF5BB0943D100EF88D52D7C3FD691B19D3A9071B555B651FBF418DA DUP4 PUSH1 0x40 MLOAD DUP1 DUP3 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 LOG1 JUMPDEST JUMPDEST JUMPDEST POP POP POP JUMP JUMPDEST PUSH1 0x0 PUSH1 0x0 PUSH2 0x105 PUSH1 0x0 DUP5 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 SLOAD GT SWAP1 POP JUMPDEST SWAP2 SWAP1 POP JUMP JUMPDEST PUSH1 0x1 SLOAD DUP2 JUMP JUMPDEST PUSH1 0x4 SLOAD DUP2 JUMP JUMPDEST PUSH1 0x0 CALLDATASIZE PUSH1 0x40 MLOAD DUP1 DUP4 DUP4 DUP1 DUP3 DUP5 CALLDATACOPY DUP3 ADD SWAP2 POP POP SWAP3 POP POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 SHA3 PUSH2 0x6C4 DUP2 PUSH2 0x1678 JUMP JUMPDEST ISZERO PUSH2 0x6D3 JUMPI PUSH1 0x0 PUSH1 0x3 DUP2 SWAP1 SSTORE POP JUMPDEST JUMPDEST JUMPDEST POP JUMP JUMPDEST PUSH1 0x3 SLOAD DUP2 JUMP JUMPDEST PUSH1 0x0 CALLDATASIZE PUSH1 0x40 MLOAD DUP1 DUP4 DUP4 DUP1 DUP3 DUP5 CALLDATACOPY DUP3 ADD SWAP2 POP POP SWAP3 POP POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 SHA3 PUSH2 0x704 DUP2 PUSH2 0x1678 JUMP JUMPDEST ISZERO PUSH2 0x824 JUMPI PUSH2 0x712 DUP3 PUSH2 0x659 JUMP JUMPDEST ISZERO PUSH2 0x71C JUMPI PUSH2 0x823 JUMP JUMPDEST PUSH2 0x724 PUSH2 0x1890 JUMP JUMPDEST PUSH1 0xFA PUSH1 0x1 SLOAD LT ISZERO ISZERO PUSH2 0x739 JUMPI PUSH2 0x738 PUSH2 0x19D0 JUMP JUMPDEST JUMPDEST PUSH1 0xFA PUSH1 0x1 SLOAD LT ISZERO ISZERO PUSH2 0x74A JUMPI PUSH2 0x823 JUMP JUMPDEST PUSH1 0x1 PUSH1 0x0 DUP2 SLOAD DUP1 SWAP3 SWAP2 SWAP1 PUSH1 0x1 ADD SWAP2 SWAP1 POP SSTORE POP DUP2 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH1 0x5 PUSH1 0x1 SLOAD PUSH2 0x100 DUP2 LT ISZERO ISZERO PUSH2 0x785 JUMPI INVALID JUMPDEST ADD PUSH1 0x0 JUMPDEST POP DUP2 SWAP1 SSTORE POP PUSH1 0x1 SLOAD PUSH2 0x105 PUSH1 0x0 DUP5 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 DUP2 SWAP1 SSTORE POP PUSH32 0x994A936646FE87FFE4F1E469D3D6AA417D6B855598397F323DE5B449F765F0C3 DUP3 PUSH1 0x40 MLOAD DUP1 DUP3 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 LOG1 JUMPDEST JUMPDEST JUMPDEST POP POP JUMP JUMPDEST PUSH1 0x0 SLOAD DUP2 JUMP JUMPDEST PUSH1 0x0 PUSH1 0x0 DUP3 PUSH2 0x83D DUP2 PUSH2 0x1678 JUMP JUMPDEST ISZERO PUSH2 0xDC4 JUMPI PUSH1 0x0 PUSH2 0x108 PUSH1 0x0 DUP7 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x0 ADD PUSH1 0x0 SWAP1 SLOAD SWAP1 PUSH2 0x100 EXP SWAP1 DIV PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND EQ ISZERO DUP1 PUSH2 0x8C7 JUMPI POP PUSH1 0x0 PUSH2 0x108 PUSH1 0x0 DUP7 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x1 ADD SLOAD EQ ISZERO JUMPDEST DUP1 PUSH2 0x906 JUMPI POP PUSH1 0x0 PUSH2 0x108 PUSH1 0x0 DUP7 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x2 ADD DUP1 SLOAD PUSH1 0x1 DUP2 PUSH1 0x1 AND ISZERO PUSH2 0x100 MUL SUB AND PUSH1 0x2 SWAP1 DIV SWAP1 POP EQ ISZERO JUMPDEST ISZERO PUSH2 0xDC2 JUMPI PUSH1 0x0 PUSH2 0x108 PUSH1 0x0 DUP7 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x0 ADD PUSH1 0x0 SWAP1 SLOAD SWAP1 PUSH2 0x100 EXP SWAP1 DIV PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND EQ ISZERO PUSH2 0xA50 JUMPI PUSH2 0xA49 PUSH2 0x108 PUSH1 0x0 DUP7 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x1 ADD SLOAD PUSH2 0x108 PUSH1 0x0 DUP8 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x2 ADD DUP1 SLOAD PUSH1 0x1 DUP2 PUSH1 0x1 AND ISZERO PUSH2 0x100 MUL SUB AND PUSH1 0x2 SWAP1 DIV DUP1 PUSH1 0x1F ADD PUSH1 0x20 DUP1 SWAP2 DIV MUL PUSH1 0x20 ADD PUSH1 0x40 MLOAD SWAP1 DUP2 ADD PUSH1 0x40 MSTORE DUP1 SWAP3 SWAP2 SWAP1 DUP2 DUP2 MSTORE PUSH1 0x20 ADD DUP3 DUP1 SLOAD PUSH1 0x1 DUP2 PUSH1 0x1 AND ISZERO PUSH2 0x100 MUL SUB AND PUSH1 0x2 SWAP1 DIV DUP1 ISZERO PUSH2 0xA3F JUMPI DUP1 PUSH1 0x1F LT PUSH2 0xA14 JUMPI PUSH2 0x100 DUP1 DUP4 SLOAD DIV MUL DUP4 MSTORE SWAP2 PUSH1 0x20 ADD SWAP2 PUSH2 0xA3F JUMP JUMPDEST DUP3 ADD SWAP2 SWAP1 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 SHA3 SWAP1 JUMPDEST DUP2 SLOAD DUP2 MSTORE SWAP1 PUSH1 0x1 ADD SWAP1 PUSH1 0x20 ADD DUP1 DUP4 GT PUSH2 0xA22 JUMPI DUP3 SWAP1 SUB PUSH1 0x1F AND DUP3 ADD SWAP2 JUMPDEST POP POP POP POP POP PUSH2 0x1B37 JUMP JUMPDEST SWAP2 POP PUSH2 0xB71 JUMP JUMPDEST PUSH2 0x108 PUSH1 0x0 DUP6 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x0 ADD PUSH1 0x0 SWAP1 SLOAD SWAP1 PUSH2 0x100 EXP SWAP1 DIV PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH2 0x108 PUSH1 0x0 DUP7 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x1 ADD SLOAD PUSH2 0x108 PUSH1 0x0 DUP8 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x2 ADD PUSH1 0x40 MLOAD DUP1 DUP3 DUP1 SLOAD PUSH1 0x1 DUP2 PUSH1 0x1 AND ISZERO PUSH2 0x100 MUL SUB AND PUSH1 0x2 SWAP1 DIV DUP1 ISZERO PUSH2 0xB4A JUMPI DUP1 PUSH1 0x1F LT PUSH2 0xB1F JUMPI PUSH2 0x100 DUP1 DUP4 SLOAD DIV MUL DUP4 MSTORE SWAP2 PUSH1 0x20 ADD SWAP2 PUSH2 0xB4A JUMP JUMPDEST DUP3 ADD SWAP2 SWAP1 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 SHA3 SWAP1 JUMPDEST DUP2 SLOAD DUP2 MSTORE SWAP1 PUSH1 0x1 ADD SWAP1 PUSH1 0x20 ADD DUP1 DUP4 GT PUSH2 0xB2D JUMPI DUP3 SWAP1 SUB PUSH1 0x1F AND DUP3 ADD SWAP2 JUMPDEST POP POP SWAP2 POP POP PUSH1 0x0 PUSH1 0x40 MLOAD DUP1 DUP4 SUB DUP2 DUP6 DUP8 PUSH2 0x8502 GAS SUB CALL SWAP3 POP POP POP ISZERO ISZERO PUSH2 0xB70 JUMPI PUSH1 0x0 PUSH1 0x0 REVERT JUMPDEST JUMPDEST PUSH32 0xE3A3A4111A84DF27D76B68DC721E65C7711605EA5EEE4AFD3A9C58195217365C CALLER DUP6 PUSH2 0x108 PUSH1 0x0 DUP9 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x1 ADD SLOAD PUSH2 0x108 PUSH1 0x0 DUP10 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x0 ADD PUSH1 0x0 SWAP1 SLOAD SWAP1 PUSH2 0x100 EXP SWAP1 DIV PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH2 0x108 PUSH1 0x0 DUP11 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x2 ADD DUP8 PUSH1 0x40 MLOAD DUP1 DUP8 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD DUP7 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD DUP6 DUP2 MSTORE PUSH1 0x20 ADD DUP5 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD DUP1 PUSH1 0x20 ADD DUP4 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD DUP3 DUP2 SUB DUP3 MSTORE DUP5 DUP2 DUP2 SLOAD PUSH1 0x1 DUP2 PUSH1 0x1 AND ISZERO PUSH2 0x100 MUL SUB AND PUSH1 0x2 SWAP1 DIV DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP DUP1 SLOAD PUSH1 0x1 DUP2 PUSH1 0x1 AND ISZERO PUSH2 0x100 MUL SUB AND PUSH1 0x2 SWAP1 DIV DUP1 ISZERO PUSH2 0xD47 JUMPI DUP1 PUSH1 0x1F LT PUSH2 0xD1C JUMPI PUSH2 0x100 DUP1 DUP4 SLOAD DIV MUL DUP4 MSTORE SWAP2 PUSH1 0x20 ADD SWAP2 PUSH2 0xD47 JUMP JUMPDEST DUP3 ADD SWAP2 SWAP1 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 SHA3 SWAP1 JUMPDEST DUP2 SLOAD DUP2 MSTORE SWAP1 PUSH1 0x1 ADD SWAP1 PUSH1 0x20 ADD DUP1 DUP4 GT PUSH2 0xD2A JUMPI DUP3 SWAP1 SUB PUSH1 0x1F AND DUP3 ADD SWAP2 JUMPDEST POP POP SWAP8 POP POP POP POP POP POP POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 LOG1 PUSH2 0x108 PUSH1 0x0 DUP6 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x0 PUSH1 0x0 DUP3 ADD PUSH1 0x0 PUSH2 0x100 EXP DUP2 SLOAD SWAP1 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF MUL NOT AND SWAP1 SSTORE PUSH1 0x1 DUP3 ADD PUSH1 0x0 SWAP1 SSTORE PUSH1 0x2 DUP3 ADD PUSH1 0x0 PUSH2 0xDB7 SWAP2 SWAP1 PUSH2 0x1BE6 JUMP JUMPDEST POP POP PUSH1 0x1 SWAP3 POP PUSH2 0xDC3 JUMP JUMPDEST JUMPDEST JUMPDEST JUMPDEST POP POP SWAP2 SWAP1 POP JUMP JUMPDEST PUSH1 0x0 CALLDATASIZE PUSH1 0x40 MLOAD DUP1 DUP4 DUP4 DUP1 DUP3 DUP5 CALLDATACOPY DUP3 ADD SWAP2 POP POP SWAP3 POP POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 SHA3 PUSH2 0xDF3 DUP2 PUSH2 0x1678 JUMP JUMPDEST ISZERO PUSH2 0xE01 JUMPI DUP2 PUSH1 0x2 DUP2 SWAP1 SSTORE POP JUMPDEST JUMPDEST JUMPDEST POP POP JUMP JUMPDEST PUSH1 0x0 PUSH1 0x0 PUSH2 0xE13 CALLER PUSH2 0x659 JUMP JUMPDEST ISZERO PUSH2 0x1273 JUMPI PUSH1 0x0 DUP5 DUP5 SWAP1 POP EQ DUP1 ISZERO PUSH2 0xE30 JUMPI POP PUSH2 0xE2F DUP6 PUSH2 0x1B51 JUMP JUMPDEST JUMPDEST DUP1 PUSH2 0xE3D JUMPI POP PUSH1 0x1 PUSH1 0x0 SLOAD EQ JUMPDEST ISZERO PUSH2 0xFED JUMPI PUSH1 0x0 DUP7 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND EQ ISZERO PUSH2 0xEA4 JUMPI PUSH2 0xE9D DUP6 DUP6 DUP6 DUP1 DUP1 PUSH1 0x1F ADD PUSH1 0x20 DUP1 SWAP2 DIV MUL PUSH1 0x20 ADD PUSH1 0x40 MLOAD SWAP1 DUP2 ADD PUSH1 0x40 MSTORE DUP1 SWAP4 SWAP3 SWAP2 SWAP1 DUP2 DUP2 MSTORE PUSH1 0x20 ADD DUP4 DUP4 DUP1 DUP3 DUP5 CALLDATACOPY DUP3 ADD SWAP2 POP POP POP POP POP POP PUSH2 0x1B37 JUMP JUMPDEST SWAP1 POP PUSH2 0xEF3 JUMP JUMPDEST DUP6 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP6 DUP6 DUP6 PUSH1 0x40 MLOAD DUP1 DUP4 DUP4 DUP1 DUP3 DUP5 CALLDATACOPY DUP3 ADD SWAP2 POP POP SWAP3 POP POP POP PUSH1 0x0 PUSH1 0x40 MLOAD DUP1 DUP4 SUB DUP2 DUP6 DUP8 PUSH2 0x8502 GAS SUB CALL SWAP3 POP POP POP ISZERO ISZERO PUSH2 0xEF2 JUMPI PUSH1 0x0 PUSH1 0x0 REVERT JUMPDEST JUMPDEST PUSH32 0x9738CD1A8777C86B011F7B01D87D484217DC6AB5154A9D41EDA5D14AF8CAF292 CALLER DUP7 DUP9 DUP8 DUP8 DUP7 PUSH1 0x40 MLOAD DUP1 DUP8 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD DUP7 DUP2 MSTORE PUSH1 0x20 ADD DUP6 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD DUP1 PUSH1 0x20 ADD DUP4 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD DUP3 DUP2 SUB DUP3 MSTORE DUP6 DUP6 DUP3 DUP2 DUP2 MSTORE PUSH1 0x20 ADD SWAP3 POP DUP1 DUP3 DUP5 CALLDATACOPY DUP3 ADD SWAP2 POP POP SWAP8 POP POP POP POP POP POP POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 LOG1 PUSH2 0x1271 JUMP JUMPDEST PUSH1 0x0 CALLDATASIZE NUMBER PUSH1 0x40 MLOAD DUP1 DUP5 DUP5 DUP1 DUP3 DUP5 CALLDATACOPY DUP3 ADD SWAP2 POP POP DUP3 DUP2 MSTORE PUSH1 0x20 ADD SWAP4 POP POP POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 SHA3 SWAP2 POP PUSH1 0x0 PUSH2 0x108 PUSH1 0x0 DUP5 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x0 ADD PUSH1 0x0 SWAP1 SLOAD SWAP1 PUSH2 0x100 EXP SWAP1 DIV PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND EQ DUP1 ISZERO PUSH2 0x1099 JUMPI POP PUSH1 0x0 PUSH2 0x108 PUSH1 0x0 DUP5 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x1 ADD SLOAD EQ JUMPDEST DUP1 ISZERO PUSH2 0x10D8 JUMPI POP PUSH1 0x0 PUSH2 0x108 PUSH1 0x0 DUP5 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x2 ADD DUP1 SLOAD PUSH1 0x1 DUP2 PUSH1 0x1 AND ISZERO PUSH2 0x100 MUL SUB AND PUSH1 0x2 SWAP1 DIV SWAP1 POP EQ JUMPDEST ISZERO PUSH2 0x118F JUMPI DUP6 PUSH2 0x108 PUSH1 0x0 DUP5 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x0 ADD PUSH1 0x0 PUSH2 0x100 EXP DUP2 SLOAD DUP2 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF MUL NOT AND SWAP1 DUP4 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND MUL OR SWAP1 SSTORE POP DUP5 PUSH2 0x108 PUSH1 0x0 DUP5 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x1 ADD DUP2 SWAP1 SSTORE POP DUP4 DUP4 PUSH2 0x108 PUSH1 0x0 DUP6 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x2 ADD SWAP2 SWAP1 PUSH2 0x118D SWAP3 SWAP2 SWAP1 PUSH2 0x1C2E JUMP JUMPDEST POP JUMPDEST PUSH2 0x1198 DUP3 PUSH2 0x82F JUMP JUMPDEST ISZERO ISZERO PUSH2 0x1270 JUMPI PUSH32 0x1733CBB53659D713B79580F79F3F9FF215F78A7C7AA45890F3B89FC5CDDFBF32 DUP3 CALLER DUP8 DUP10 DUP9 DUP9 PUSH1 0x40 MLOAD DUP1 DUP8 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD DUP7 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD DUP6 DUP2 MSTORE PUSH1 0x20 ADD DUP5 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD DUP1 PUSH1 0x20 ADD DUP3 DUP2 SUB DUP3 MSTORE DUP5 DUP5 DUP3 DUP2 DUP2 MSTORE PUSH1 0x20 ADD SWAP3 POP DUP1 DUP3 DUP5 CALLDATACOPY DUP3 ADD SWAP2 POP POP SWAP8 POP POP POP POP POP POP POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 LOG1 JUMPDEST JUMPDEST JUMPDEST JUMPDEST JUMPDEST POP SWAP5 SWAP4 POP POP POP POP JUMP JUMPDEST PUSH1 0x0 PUSH1 0x0 PUSH1 0x0 PUSH2 0x105 PUSH1 0x0 CALLER PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 SLOAD SWAP3 POP PUSH1 0x0 DUP4 EQ ISZERO PUSH2 0x12BE JUMPI PUSH2 0x138C JUMP JUMPDEST DUP3 PUSH1 0x2 EXP SWAP2 POP PUSH2 0x106 PUSH1 0x0 DUP6 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 SWAP1 POP PUSH1 0x0 DUP3 DUP3 PUSH1 0x1 ADD SLOAD AND GT ISZERO PUSH2 0x138B JUMPI DUP1 PUSH1 0x0 ADD PUSH1 0x0 DUP2 SLOAD DUP1 SWAP3 SWAP2 SWAP1 PUSH1 0x1 ADD SWAP2 SWAP1 POP SSTORE POP DUP2 DUP2 PUSH1 0x1 ADD PUSH1 0x0 DUP3 DUP3 SLOAD SUB SWAP3 POP POP DUP2 SWAP1 SSTORE POP PUSH32 0xC7FB647E59B18047309AA15AAD418E5D7CA96D173AD704F1031A2C3D7591734B CALLER DUP6 PUSH1 0x40 MLOAD DUP1 DUP4 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD DUP3 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP3 POP POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 LOG1 JUMPDEST JUMPDEST POP POP POP POP JUMP JUMPDEST PUSH1 0x0 CALLDATASIZE PUSH1 0x40 MLOAD DUP1 DUP4 DUP4 DUP1 DUP3 DUP5 CALLDATACOPY DUP3 ADD SWAP2 POP POP SWAP3 POP POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 SHA3 PUSH2 0x13B9 DUP2 PUSH2 0x1678 JUMP JUMPDEST ISZERO PUSH2 0x1415 JUMPI PUSH1 0x1 SLOAD DUP3 GT ISZERO PUSH2 0x13CD JUMPI PUSH2 0x1414 JUMP JUMPDEST DUP2 PUSH1 0x0 DUP2 SWAP1 SSTORE POP PUSH2 0x13DC PUSH2 0x1890 JUMP JUMPDEST PUSH32 0xACBDB084C721332AC59F9B8E392196C9EB0E4932862DA8EB9BEAF0DAD4F550DA DUP3 PUSH1 0x40 MLOAD DUP1 DUP3 DUP2 MSTORE PUSH1 0x20 ADD SWAP2 POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 LOG1 JUMPDEST JUMPDEST JUMPDEST POP POP JUMP JUMPDEST PUSH1 0x0 PUSH1 0x0 PUSH1 0x0 PUSH1 0x0 PUSH2 0x106 PUSH1 0x0 DUP8 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 SWAP3 POP PUSH2 0x105 PUSH1 0x0 DUP7 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 SLOAD SWAP2 POP PUSH1 0x0 DUP3 EQ ISZERO PUSH2 0x147F JUMPI PUSH1 0x0 SWAP4 POP PUSH2 0x1493 JUMP JUMPDEST DUP2 PUSH1 0x2 EXP SWAP1 POP PUSH1 0x0 DUP2 DUP5 PUSH1 0x1 ADD SLOAD AND EQ ISZERO SWAP4 POP JUMPDEST POP POP POP SWAP3 SWAP2 POP POP JUMP JUMPDEST PUSH1 0x0 PUSH1 0x5 PUSH1 0x1 DUP4 ADD PUSH2 0x100 DUP2 LT ISZERO ISZERO PUSH2 0x14B1 JUMPI INVALID JUMPDEST ADD PUSH1 0x0 JUMPDEST POP SLOAD SWAP1 POP JUMPDEST SWAP2 SWAP1 POP JUMP JUMPDEST PUSH1 0x0 PUSH1 0x0 CALLDATASIZE PUSH1 0x40 MLOAD DUP1 DUP4 DUP4 DUP1 DUP3 DUP5 CALLDATACOPY DUP3 ADD SWAP2 POP POP SWAP3 POP POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 SHA3 PUSH2 0x14E8 DUP2 PUSH2 0x1678 JUMP JUMPDEST ISZERO PUSH2 0x166B JUMPI PUSH2 0x14F6 DUP4 PUSH2 0x659 JUMP JUMPDEST ISZERO PUSH2 0x1500 JUMPI PUSH2 0x166A JUMP JUMPDEST PUSH2 0x105 PUSH1 0x0 DUP6 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 SLOAD SWAP2 POP PUSH1 0x0 DUP3 EQ ISZERO PUSH2 0x153B JUMPI PUSH2 0x166A JUMP JUMPDEST PUSH2 0x1543 PUSH2 0x1890 JUMP JUMPDEST DUP3 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH1 0x5 DUP4 PUSH2 0x100 DUP2 LT ISZERO ISZERO PUSH2 0x156A JUMPI INVALID JUMPDEST ADD PUSH1 0x0 JUMPDEST POP DUP2 SWAP1 SSTORE POP PUSH1 0x0 PUSH2 0x105 PUSH1 0x0 DUP7 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 DUP2 SWAP1 SSTORE POP DUP2 PUSH2 0x105 PUSH1 0x0 DUP6 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 DUP2 SWAP1 SSTORE POP PUSH32 0xB532073B38C83145E3E5135377A08BF9AAB55BC0FD7C1179CD4FB995D2A5159C DUP5 DUP5 PUSH1 0x40 MLOAD DUP1 DUP4 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD DUP3 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP3 POP POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 LOG1 JUMPDEST JUMPDEST JUMPDEST POP POP POP POP JUMP JUMPDEST PUSH1 0x2 SLOAD DUP2 JUMP JUMPDEST PUSH1 0x0 PUSH1 0x0 PUSH1 0x0 PUSH1 0x0 PUSH2 0x105 PUSH1 0x0 CALLER PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 SLOAD SWAP3 POP PUSH1 0x0 DUP4 EQ ISZERO PUSH2 0x16BB JUMPI PUSH2 0x1888 JUMP JUMPDEST PUSH2 0x106 PUSH1 0x0 DUP7 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 SWAP2 POP PUSH1 0x0 DUP3 PUSH1 0x0 ADD SLOAD EQ ISZERO PUSH2 0x1745 JUMPI PUSH1 0x0 SLOAD DUP3 PUSH1 0x0 ADD DUP2 SWAP1 SSTORE POP PUSH1 0x0 DUP3 PUSH1 0x1 ADD DUP2 SWAP1 SSTORE POP PUSH2 0x107 DUP1 SLOAD DUP1 SWAP2 SWAP1 PUSH1 0x1 ADD PUSH2 0x1710 SWAP2 SWAP1 PUSH2 0x1CAE JUMP JUMPDEST DUP3 PUSH1 0x2 ADD DUP2 SWAP1 SSTORE POP DUP5 PUSH2 0x107 DUP4 PUSH1 0x2 ADD SLOAD DUP2 SLOAD DUP2 LT ISZERO ISZERO PUSH2 0x172D JUMPI INVALID JUMPDEST SWAP1 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 SHA3 SWAP1 ADD PUSH1 0x0 JUMPDEST POP DUP2 PUSH1 0x0 NOT AND SWAP1 SSTORE POP JUMPDEST DUP3 PUSH1 0x2 EXP SWAP1 POP PUSH1 0x0 DUP2 DUP4 PUSH1 0x1 ADD SLOAD AND EQ ISZERO PUSH2 0x1887 JUMPI PUSH32 0xE1C52DC63B719ADE82E8BEA94CC41A0D5D28E4AAF536ADB5E9CCCC9FF8C1AEDA CALLER DUP7 PUSH1 0x40 MLOAD DUP1 DUP4 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD DUP3 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP3 POP POP POP PUSH1 0x40 MLOAD DUP1 SWAP2 SUB SWAP1 LOG1 PUSH1 0x1 DUP3 PUSH1 0x0 ADD SLOAD GT ISZERO ISZERO PUSH2 0x185E JUMPI PUSH2 0x107 PUSH2 0x106 PUSH1 0x0 DUP8 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x2 ADD SLOAD DUP2 SLOAD DUP2 LT ISZERO ISZERO PUSH2 0x180A JUMPI INVALID JUMPDEST SWAP1 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 SHA3 SWAP1 ADD PUSH1 0x0 JUMPDEST POP PUSH1 0x0 SWAP1 SSTORE PUSH2 0x106 PUSH1 0x0 DUP7 PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x0 PUSH1 0x0 DUP3 ADD PUSH1 0x0 SWAP1 SSTORE PUSH1 0x1 DUP3 ADD PUSH1 0x0 SWAP1 SSTORE PUSH1 0x2 DUP3 ADD PUSH1 0x0 SWAP1 SSTORE POP POP PUSH1 0x1 SWAP4 POP PUSH2 0x1888 JUMP JUMPDEST DUP2 PUSH1 0x0 ADD PUSH1 0x0 DUP2 SLOAD DUP1 SWAP3 SWAP2 SWAP1 PUSH1 0x1 SWAP1 SUB SWAP2 SWAP1 POP SSTORE POP DUP1 DUP3 PUSH1 0x1 ADD PUSH1 0x0 DUP3 DUP3 SLOAD OR SWAP3 POP POP DUP2 SWAP1 SSTORE POP JUMPDEST JUMPDEST JUMPDEST POP POP POP SWAP2 SWAP1 POP JUMP JUMPDEST PUSH1 0x0 PUSH1 0x0 PUSH2 0x107 DUP1 SLOAD SWAP1 POP SWAP2 POP PUSH1 0x0 SWAP1 POP JUMPDEST DUP2 DUP2 LT ISZERO PUSH2 0x19BC JUMPI PUSH2 0x108 PUSH1 0x0 PUSH2 0x107 DUP4 DUP2 SLOAD DUP2 LT ISZERO ISZERO PUSH2 0x18BF JUMPI INVALID JUMPDEST SWAP1 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 SHA3 SWAP1 ADD PUSH1 0x0 JUMPDEST POP SLOAD PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x0 PUSH1 0x0 DUP3 ADD PUSH1 0x0 PUSH2 0x100 EXP DUP2 SLOAD SWAP1 PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF MUL NOT AND SWAP1 SSTORE PUSH1 0x1 DUP3 ADD PUSH1 0x0 SWAP1 SSTORE PUSH1 0x2 DUP3 ADD PUSH1 0x0 PUSH2 0x1926 SWAP2 SWAP1 PUSH2 0x1BE6 JUMP JUMPDEST POP POP PUSH1 0x0 PUSH1 0x1 MUL PUSH2 0x107 DUP3 DUP2 SLOAD DUP2 LT ISZERO ISZERO PUSH2 0x193D JUMPI INVALID JUMPDEST SWAP1 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 SHA3 SWAP1 ADD PUSH1 0x0 JUMPDEST POP SLOAD PUSH1 0x0 NOT AND EQ ISZERO ISZERO PUSH2 0x19B0 JUMPI PUSH2 0x106 PUSH1 0x0 PUSH2 0x107 DUP4 DUP2 SLOAD DUP2 LT ISZERO ISZERO PUSH2 0x196D JUMPI INVALID JUMPDEST SWAP1 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 SHA3 SWAP1 ADD PUSH1 0x0 JUMPDEST POP SLOAD PUSH1 0x0 NOT AND PUSH1 0x0 NOT AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 PUSH1 0x0 PUSH1 0x0 DUP3 ADD PUSH1 0x0 SWAP1 SSTORE PUSH1 0x1 DUP3 ADD PUSH1 0x0 SWAP1 SSTORE PUSH1 0x2 DUP3 ADD PUSH1 0x0 SWAP1 SSTORE POP POP JUMPDEST JUMPDEST DUP1 PUSH1 0x1 ADD SWAP1 POP PUSH2 0x18A2 JUMP JUMPDEST PUSH2 0x107 PUSH1 0x0 PUSH2 0x19CB SWAP2 SWAP1 PUSH2 0x1CDA JUMP JUMPDEST JUMPDEST POP POP JUMP JUMPDEST PUSH1 0x0 PUSH1 0x1 SWAP1 POP JUMPDEST PUSH1 0x1 SLOAD DUP2 LT ISZERO PUSH2 0x1B33 JUMPI JUMPDEST PUSH1 0x1 SLOAD DUP2 LT DUP1 ISZERO PUSH2 0x1A09 JUMPI POP PUSH1 0x0 PUSH1 0x5 DUP3 PUSH2 0x100 DUP2 LT ISZERO ISZERO PUSH2 0x1A00 JUMPI INVALID JUMPDEST ADD PUSH1 0x0 JUMPDEST POP SLOAD EQ ISZERO JUMPDEST ISZERO PUSH2 0x1A1B JUMPI DUP1 DUP1 PUSH1 0x1 ADD SWAP2 POP POP PUSH2 0x19E2 JUMP JUMPDEST JUMPDEST PUSH1 0x1 PUSH1 0x1 SLOAD GT DUP1 ISZERO PUSH2 0x1A45 JUMPI POP PUSH1 0x0 PUSH1 0x5 PUSH1 0x1 SLOAD PUSH2 0x100 DUP2 LT ISZERO ISZERO PUSH2 0x1A3D JUMPI INVALID JUMPDEST ADD PUSH1 0x0 JUMPDEST POP SLOAD EQ JUMPDEST ISZERO PUSH2 0x1A62 JUMPI PUSH1 0x1 PUSH1 0x0 DUP2 SLOAD DUP1 SWAP3 SWAP2 SWAP1 PUSH1 0x1 SWAP1 SUB SWAP2 SWAP1 POP SSTORE POP PUSH2 0x1A1C JUMP JUMPDEST PUSH1 0x1 SLOAD DUP2 LT DUP1 ISZERO PUSH2 0x1A8B JUMPI POP PUSH1 0x0 PUSH1 0x5 PUSH1 0x1 SLOAD PUSH2 0x100 DUP2 LT ISZERO ISZERO PUSH2 0x1A82 JUMPI INVALID JUMPDEST ADD PUSH1 0x0 JUMPDEST POP SLOAD EQ ISZERO JUMPDEST DUP1 ISZERO PUSH2 0x1AAC JUMPI POP PUSH1 0x0 PUSH1 0x5 DUP3 PUSH2 0x100 DUP2 LT ISZERO ISZERO PUSH2 0x1AA4 JUMPI INVALID JUMPDEST ADD PUSH1 0x0 JUMPDEST POP SLOAD EQ JUMPDEST ISZERO PUSH2 0x1B2E JUMPI PUSH1 0x5 PUSH1 0x1 SLOAD PUSH2 0x100 DUP2 LT ISZERO ISZERO PUSH2 0x1AC3 JUMPI INVALID JUMPDEST ADD PUSH1 0x0 JUMPDEST POP SLOAD PUSH1 0x5 DUP3 PUSH2 0x100 DUP2 LT ISZERO ISZERO PUSH2 0x1AD9 JUMPI INVALID JUMPDEST ADD PUSH1 0x0 JUMPDEST POP DUP2 SWAP1 SSTORE POP DUP1 PUSH2 0x105 PUSH1 0x0 PUSH1 0x5 DUP5 PUSH2 0x100 DUP2 LT ISZERO ISZERO PUSH2 0x1AF8 JUMPI INVALID JUMPDEST ADD PUSH1 0x0 JUMPDEST POP SLOAD DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 DUP2 SWAP1 SSTORE POP PUSH1 0x0 PUSH1 0x5 PUSH1 0x1 SLOAD PUSH2 0x100 DUP2 LT ISZERO ISZERO PUSH2 0x1B24 JUMPI INVALID JUMPDEST ADD PUSH1 0x0 JUMPDEST POP DUP2 SWAP1 SSTORE POP JUMPDEST PUSH2 0x19D7 JUMP JUMPDEST JUMPDEST POP JUMP JUMPDEST PUSH1 0x0 DUP2 MLOAD PUSH1 0x20 DUP4 ADD DUP5 CREATE SWAP1 POP DUP1 EXTCODESIZE ISZERO PUSH2 0x0 JUMPI JUMPDEST SWAP3 SWAP2 POP POP JUMP JUMPDEST PUSH1 0x0 PUSH2 0x1B5C CALLER PUSH2 0x659 JUMP JUMPDEST ISZERO PUSH2 0x1BC9 JUMPI PUSH1 0x4 SLOAD PUSH2 0x1B6C PUSH2 0x1BCF JUMP JUMPDEST GT ISZERO PUSH2 0x1B89 JUMPI PUSH1 0x0 PUSH1 0x3 DUP2 SWAP1 SSTORE POP PUSH2 0x1B82 PUSH2 0x1BCF JUMP JUMPDEST PUSH1 0x4 DUP2 SWAP1 SSTORE POP JUMPDEST PUSH1 0x3 SLOAD DUP3 PUSH1 0x3 SLOAD ADD LT ISZERO DUP1 ISZERO PUSH2 0x1BA5 JUMPI POP PUSH1 0x2 SLOAD DUP3 PUSH1 0x3 SLOAD ADD GT ISZERO JUMPDEST ISZERO PUSH2 0x1BC3 JUMPI DUP2 PUSH1 0x3 PUSH1 0x0 DUP3 DUP3 SLOAD ADD SWAP3 POP POP DUP2 SWAP1 SSTORE POP PUSH1 0x1 SWAP1 POP PUSH2 0x1BC8 JUMP JUMPDEST PUSH1 0x0 SWAP1 POP JUMPDEST JUMPDEST JUMPDEST SWAP2 SWAP1 POP JUMP JUMPDEST PUSH1 0x0 PUSH3 0x15180 TIMESTAMP DUP2 ISZERO ISZERO PUSH2 0x1BDF JUMPI INVALID JUMPDEST DIV SWAP1 POP JUMPDEST SWAP1 JUMP JUMPDEST POP DUP1 SLOAD PUSH1 0x1 DUP2 PUSH1 0x1 AND ISZERO PUSH2 0x100 MUL SUB AND PUSH1 0x2 SWAP1 DIV PUSH1 0x0 DUP3 SSTORE DUP1 PUSH1 0x1F LT PUSH2 0x1C0C JUMPI POP PUSH2 0x1C2B JUMP JUMPDEST PUSH1 0x1F ADD PUSH1 0x20 SWAP1 DIV SWAP1 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 SHA3 SWAP1 DUP2 ADD SWAP1 PUSH2 0x1C2A SWAP2 SWAP1 PUSH2 0x1CFC JUMP JUMPDEST JUMPDEST POP JUMP JUMPDEST DUP3 DUP1 SLOAD PUSH1 0x1 DUP2 PUSH1 0x1 AND ISZERO PUSH2 0x100 MUL SUB AND PUSH1 0x2 SWAP1 DIV SWAP1 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 SHA3 SWAP1 PUSH1 0x1F ADD PUSH1 0x20 SWAP1 DIV DUP2 ADD SWAP3 DUP3 PUSH1 0x1F LT PUSH2 0x1C6F JUMPI DUP1 CALLDATALOAD PUSH1 0xFF NOT AND DUP4 DUP1 ADD OR DUP6 SSTORE PUSH2 0x1C9D JUMP JUMPDEST DUP3 DUP1 ADD PUSH1 0x1 ADD DUP6 SSTORE DUP3 ISZERO PUSH2 0x1C9D JUMPI SWAP2 DUP3 ADD JUMPDEST DUP3 DUP2 GT ISZERO PUSH2 0x1C9C JUMPI DUP3 CALLDATALOAD DUP3 SSTORE SWAP2 PUSH1 0x20 ADD SWAP2 SWAP1 PUSH1 0x1 ADD SWAP1 PUSH2 0x1C81 JUMP JUMPDEST JUMPDEST POP SWAP1 POP PUSH2 0x1CAA SWAP2 SWAP1 PUSH2 0x1CFC JUMP JUMPDEST POP SWAP1 JUMP JUMPDEST DUP2 SLOAD DUP2 DUP4 SSTORE DUP2 DUP2 ISZERO GT PUSH2 0x1CD5 JUMPI DUP2 DUP4 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 SHA3 SWAP2 DUP3 ADD SWAP2 ADD PUSH2 0x1CD4 SWAP2 SWAP1 PUSH2 0x1D21 JUMP JUMPDEST JUMPDEST POP POP POP JUMP JUMPDEST POP DUP1 SLOAD PUSH1 0x0 DUP3 SSTORE SWAP1 PUSH1 0x0 MSTORE PUSH1 0x20 PUSH1 0x0 SHA3 SWAP1 DUP2 ADD SWAP1 PUSH2 0x1CF8 SWAP2 SWAP1 PUSH2 0x1D21 JUMP JUMPDEST JUMPDEST POP JUMP JUMPDEST PUSH2 0x1D1E SWAP2 SWAP1 JUMPDEST DUP1 DUP3 GT ISZERO PUSH2 0x1D1A JUMPI PUSH1 0x0 DUP2 PUSH1 0x0 SWAP1 SSTORE POP PUSH1 0x1 ADD PUSH2 0x1D02 JUMP JUMPDEST POP SWAP1 JUMP JUMPDEST SWAP1 JUMP JUMPDEST PUSH2 0x1D43 SWAP2 SWAP1 JUMPDEST DUP1 DUP3 GT ISZERO PUSH2 0x1D3F JUMPI PUSH1 0x0 DUP2 PUSH1 0x0 SWAP1 SSTORE POP PUSH1 0x1 ADD PUSH2 0x1D27 JUMP JUMPDEST POP SWAP1 JUMP JUMPDEST SWAP1 JUMP JUMPDEST PUSH1 0x0 PUSH1 0x1 SLOAD GT ISZERO PUSH2 0x1D57 JUMPI PUSH1 0x0 PUSH1 0x0 REVERT JUMPDEST PUSH2 0x1D60 DUP2 PUSH2 0x1D71 JUMP JUMPDEST PUSH2 0x1D6A DUP4 DUP4 PUSH2 0x1D9C JUMP JUMPDEST JUMPDEST JUMPDEST POP POP POP JUMP JUMPDEST PUSH1 0x0 PUSH1 0x1 SLOAD GT ISZERO PUSH2 0x1D82 JUMPI PUSH1 0x0 PUSH1 0x0 REVERT JUMPDEST DUP1 PUSH1 0x2 DUP2 SWAP1 SSTORE POP PUSH2 0x1D91 PUSH2 0x1BCF JUMP JUMPDEST PUSH1 0x4 DUP2 SWAP1 SSTORE POP JUMPDEST JUMPDEST POP JUMP JUMPDEST PUSH1 0x0 PUSH1 0x0 PUSH1 0x1 SLOAD GT ISZERO PUSH2 0x1DAF JUMPI PUSH1 0x0 PUSH1 0x0 REVERT JUMPDEST PUSH1 0x0 DUP3 GT ISZERO ISZERO PUSH2 0x1DBF JUMPI PUSH1 0x0 PUSH1 0x0 REVERT JUMPDEST DUP2 DUP4 MLOAD LT ISZERO ISZERO ISZERO PUSH2 0x1DD0 JUMPI PUSH1 0x0 PUSH1 0x0 REVERT JUMPDEST DUP3 MLOAD PUSH1 0x1 DUP2 SWAP1 SSTORE POP PUSH1 0x0 SWAP1 POP JUMPDEST DUP3 MLOAD DUP2 LT ISZERO PUSH2 0x1E85 JUMPI DUP3 DUP2 DUP2 MLOAD DUP2 LT ISZERO ISZERO PUSH2 0x1DF4 JUMPI INVALID JUMPDEST SWAP1 PUSH1 0x20 ADD SWAP1 PUSH1 0x20 MUL ADD MLOAD PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND PUSH1 0x5 DUP3 PUSH1 0x1 ADD PUSH2 0x100 DUP2 LT ISZERO ISZERO PUSH2 0x1E27 JUMPI INVALID JUMPDEST ADD PUSH1 0x0 JUMPDEST POP DUP2 SWAP1 SSTORE POP DUP1 PUSH1 0x1 ADD PUSH2 0x105 PUSH1 0x0 DUP6 DUP5 DUP2 MLOAD DUP2 LT ISZERO ISZERO PUSH2 0x1E47 JUMPI INVALID JUMPDEST SWAP1 PUSH1 0x20 ADD SWAP1 PUSH1 0x20 MUL ADD MLOAD PUSH20 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF AND DUP2 MSTORE PUSH1 0x20 ADD SWAP1 DUP2 MSTORE PUSH1 0x20 ADD PUSH1 0x0 SHA3 DUP2 SWAP1 SSTORE POP JUMPDEST DUP1 PUSH1 0x1 ADD SWAP1 POP PUSH2 0x1DDD JUMP JUMPDEST DUP2 PUSH1 0x0 DUP2 SWAP1 SSTORE POP JUMPDEST JUMPDEST POP POP POP JUMP STOP LOG1 PUSH6 0x627A7A723058 SHA3 AND DUP9 SWAP16 SMOD BLOCKHASH CREATE PUSH20 0xD397F9D00B0D19900FB050B957E3E2942F861085 0xbe 0xb9 0xba 0xab XOR STOP 0x29 </span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sourceMap</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2715:10853:0:-;;;3523:112;;;;;;;3552:18;3574:8;:27;;;;;;;;;;;:::i;:::-;;;;;;;;;;;3596:3;3574:27;;;;;;;;;;;;;;;;;;;;;;;3605:26;3616:8;3605:26;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;3626:1;3629;3605:10;;;;;:26;;;:::i;:::-;3523:112;;2715:10853;;7697:168;7585:1;7571:11;;:15;7567:26;;;7588:5;;;7567:26;7800:23;7813:9;7800:12;;;;;:23;;;:::i;:::-;7827:34;7842:7;7851:9;7827:14;;;;;:34;;;:::i;:::-;7595:1;7697:168;;;;:::o;6966:115::-;7585:1;7571:11;;:15;7567:26;;;7588:5;;;7567:26;7048:6;7033:12;:21;;;;7070:7;:5;;;;;:7;;;:::i;:::-;7058:9;:19;;;;7595:1;6966:115;;:::o;3977:349::-;4171:6;7585:1;7571:11;;:15;7567:26;;;7588:5;;;7567:26;4088:1;4076:9;:13;4068:22;;;;;;;;4120:9;4102:7;:14;:27;;4094:36;;;;;;;;4148:7;:14;4134:11;:28;;;;4180:1;4171:10;;4166:131;4187:7;:14;4183:1;:18;4166:131;;;4238:7;4246:1;4238:10;;;;;;;;;;;;;;;;;;4233:16;;4215:8;4228:1;4224;:5;4215:15;;;;;;;;;;;;:34;;;;;4291:1;4287;:5;4254:12;:30;4272:7;4280:1;4272:10;;;;;;;;;;;;;;;;;;4267:16;;4254:30;;;;;;;;;;;:38;;;;4166:131;4203:3;;;;;4166:131;;;4313:9;4300:10;:22;;;;7595:1;3977:349;;;;:::o;12529:73::-;12572:4;12593:6;12587:3;:12;;;;;;;;12580:19;;12529:73;;:::o;2715:10853::-;;;;;;;;;;;;;;;;;;;;;;;;;;;;:::i;:::-;;;;;:::o;:::-;;;;;;;;;;;;;;;;;;;;;;;;;;;:::o;:::-;;;;;;;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">linkReferences</span><span class="z-support">&quot;</span><span>:</span><span> {</span><span>}</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>To verify the byte-code above, a patched version is deployed at <a rel="external" href="https://etherscan.io/address/0x21C9E434c669c4d73f55215A6F2130A185E127AC#code"><code>0x21C9E434c669c4d73f55215A6F2130A185E127AC</code></a> to be reviewed. The compiler settings used can be extracted from the following meta-data:</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">compiler</span><span class="z-support">&quot;</span><span>:</span><span>{</span><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">0.4.10+commit.f0d539ae</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">language</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Solidity</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">output</span><span class="z-support">&quot;</span><span>:</span><span>{</span><span class="z-support">&quot;</span><span class="z-support">abi</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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">_owner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">removeOwner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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 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><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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">_addr</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">isOwner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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 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><span>]</span><span>,</span><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 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><span>{</span><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 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 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">m_numOwners</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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 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><span>]</span><span>,</span><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 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><span>{</span><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 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 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">m_lastDay</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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 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><span>]</span><span>,</span><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 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><span>{</span><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 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 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">resetSpentToday</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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 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><span>{</span><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 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 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">m_spentToday</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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 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><span>]</span><span>,</span><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 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><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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">_owner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">addOwner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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 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><span>{</span><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 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 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">m_required</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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 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><span>]</span><span>,</span><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 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><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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">_h</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">confirm</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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">o_success</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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 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><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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">_newLimit</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">setDailyLimit</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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 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><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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 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><span>,</span><span>{</span><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 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><span>,</span><span>{</span><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">_data</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">execute</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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">o_hash</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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 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><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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">_operation</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">revoke</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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 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><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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">_newRequired</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">changeRequirement</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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 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><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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">_operation</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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">_owner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">hasConfirmed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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 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><span>]</span><span>,</span><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 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><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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">ownerIndex</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">getOwner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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 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><span>]</span><span>,</span><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 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><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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">_from</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 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><span>]</span><span>,</span><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">changeOwner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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 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><span>{</span><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 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 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">m_dailyLimit</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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 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 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><span>]</span><span>,</span><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 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><span>{</span><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 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 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">constructor</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span><span>{</span><span class="z-support">&quot;</span><span class="z-support">payable</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">true</span><span>,</span><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">fallback</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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 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">owner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 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">operation</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">Confirmation</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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 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">owner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 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">operation</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">Revoke</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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 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">oldOwner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 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">newOwner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">OwnerChanged</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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 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">newOwner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">OwnerAdded</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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 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">oldOwner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">OwnerRemoved</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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 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">newRequirement</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">RequirementChanged</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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 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">_from</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 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 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><span>]</span><span>,</span><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">Deposit</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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 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">owner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 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 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><span>,</span><span>{</span><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 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 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><span>,</span><span>{</span><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 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">data</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 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">created</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">SingleTransact</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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 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">owner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 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">operation</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 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 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><span>,</span><span>{</span><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 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 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><span>,</span><span>{</span><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 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">data</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 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">created</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">MultiTransact</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 class="z-support">&quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>{</span><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 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">operation</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 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">initiator</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>,</span><span>{</span><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 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 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><span>,</span><span>{</span><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 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 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><span>,</span><span>{</span><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 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">data</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><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">ConfirmationNeeded</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><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><span>]</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">devdoc</span><span class="z-support">&quot;</span><span>:</span><span>{</span><span class="z-support">&quot;</span><span class="z-support">methods</span><span class="z-support">&quot;</span><span>:</span><span>{</span><span>}</span><span>}</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">userdoc</span><span class="z-support">&quot;</span><span>:</span><span>{</span><span class="z-support">&quot;</span><span class="z-support">methods</span><span class="z-support">&quot;</span><span>:</span><span>{</span><span>}</span><span>}</span><span>}</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">settings</span><span class="z-support">&quot;</span><span>:</span><span>{</span><span class="z-support">&quot;</span><span class="z-support">compilationTarget</span><span class="z-support">&quot;</span><span>:</span><span>{</span><span class="z-support">&quot;</span><span class="z-support">browser/WalletLibrary.sol</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">WalletLibrary</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">libraries</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">optimizer</span><span class="z-support">&quot;</span><span>:</span><span>{</span><span class="z-support">&quot;</span><span class="z-support">enabled</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">false</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">runs</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">200</span><span>}</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">remappings</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>]</span><span>}</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">sources</span><span class="z-support">&quot;</span><span>:</span><span>{</span><span class="z-support">&quot;</span><span class="z-support">browser/WalletLibrary.sol</span><span class="z-support">&quot;</span><span>:</span><span>{</span><span class="z-support">&quot;</span><span class="z-support">keccak256</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0xf72fcdc85e15f93172878ca6a61fb81604d1052e9e724bc3896d65b3b4ab1bb0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">urls</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">bzzr://009bd59bd78f59804eaffb6111d341caea58888f8e5b5f75aebdf009fc6136c0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>}</span><span>}</span><span>,</span><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></span></code></pre> <p>The differences to the originally deployed contract code can be reviewed at:</p> <ul> <li><a rel="external" href="https://github.com/parity-contracts/0x863df6bfa4/pull/2">parity-contracts/0x863df6bfa4#2</a>: Remove the <code>selfdestruct()</code></li> <li><a rel="external" href="https://github.com/parity-contracts/0x863df6bfa4/pull/3">parity-contracts/0x863df6bfa4#3</a>: Initialize the library owner to <code>0x0</code></li> </ul> <p>The following sections propose two equivalent specifications, 999a and 999b, which technically achieve the same results. To implement this proposal only one of them has to be applied.</p> <h3 id="direct-state-transition-via-bytecode-999a">Direct State Transition via Bytecode (999a)</h3> <p>At <code>CNSTNTNPL_FORK_BLKNUM</code>, directly recreate the account <code>0x863DF6BFa4469f3ead0bE8f9F2AAE51c91A907b4</code> with the following parameters:</p> <ul> <li>Nonce: <code>0x1</code></li> <li>Code:</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x606060405236156100ef576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff168063173825d91461016d5780632f54bf6e146101a35780634123cb6b146101f157806352375093146102175780635c52c2f51461023d578063659010e71461024f5780637065cb4814610275578063746c9171146102ab578063797af627146102d1578063b20d30a91461030d578063b61d27f61461032d578063b75c7dc61461039c578063ba51a6df146103c0578063c2cf7326146103e0578063c41a360a1461043b578063f00d4b5d1461049b578063f1736d86146104f0575b61016b5b6000341115610168577fe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d3c460751c2402c5c5cc9109c3334604051808373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020018281526020019250505060405180910390a15b5b565b005b341561017557fe5b6101a1600480803573ffffffffffffffffffffffffffffffffffffffff16906020019091905050610516565b005b34156101ab57fe5b6101d7600480803573ffffffffffffffffffffffffffffffffffffffff16906020019091905050610659565b604051808215151515815260200191505060405180910390f35b34156101f957fe5b610201610691565b6040518082815260200191505060405180910390f35b341561021f57fe5b610227610697565b6040518082815260200191505060405180910390f35b341561024557fe5b61024d61069d565b005b341561025757fe5b61025f6106d7565b6040518082815260200191505060405180910390f35b341561027d57fe5b6102a9600480803573ffffffffffffffffffffffffffffffffffffffff169060200190919050506106dd565b005b34156102b357fe5b6102bb610829565b6040518082815260200191505060405180910390f35b34156102d957fe5b6102f360048080356000191690602001909190505061082f565b604051808215151515815260200191505060405180910390f35b341561031557fe5b61032b6004808035906020019091905050610dcc565b005b341561033557fe5b61037e600480803573ffffffffffffffffffffffffffffffffffffffff169060200190919080359060200190919080359060200190820180359060200191909192905050610e06565b60405180826000191660001916815260200191505060405180910390f35b34156103a457fe5b6103be60048080356000191690602001909190505061127d565b005b34156103c857fe5b6103de6004808035906020019091905050611392565b005b34156103e857fe5b61042160048080356000191690602001909190803573ffffffffffffffffffffffffffffffffffffffff1690602001909190505061141a565b604051808215151515815260200191505060405180910390f35b341561044357fe5b610459600480803590602001909190505061149c565b604051808273ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200191505060405180910390f35b34156104a357fe5b6104ee600480803573ffffffffffffffffffffffffffffffffffffffff1690602001909190803573ffffffffffffffffffffffffffffffffffffffff169060200190919050506114bf565b005b34156104f857fe5b610500611672565b6040518082815260200191505060405180910390f35b600060003660405180838380828437820191505092505050604051809103902061053f81611678565b156106535761010560008473ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020549150600082141561057f57610652565b600160015403600054111561059357610652565b6000600583610100811015156105a557fe5b0160005b5081905550600061010560008573ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020819055506105e6611890565b6105ee6119d0565b7f58619076adf5bb0943d100ef88d52d7c3fd691b19d3a9071b555b651fbf418da83604051808273ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200191505060405180910390a15b5b5b505050565b6000600061010560008473ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020541190505b919050565b60015481565b60045481565b6000366040518083838082843782019150509250505060405180910390206106c481611678565b156106d35760006003819055505b5b5b50565b60035481565b60003660405180838380828437820191505092505050604051809103902061070481611678565b156108245761071282610659565b1561071c57610823565b610724611890565b60fa600154101515610739576107386119d0565b5b60fa60015410151561074a57610823565b6001600081548092919060010191905055508173ffffffffffffffffffffffffffffffffffffffff1660056001546101008110151561078557fe5b0160005b508190555060015461010560008473ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020819055507f994a936646fe87ffe4f1e469d3d6aa417d6b855598397f323de5b449f765f0c382604051808273ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200191505060405180910390a15b5b5b5050565b60005481565b600060008261083d81611678565b15610dc45760006101086000866000191660001916815260200190815260200160002060000160009054906101000a900473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff161415806108c757506000610108600086600019166000191681526020019081526020016000206001015414155b80610906575060006101086000866000191660001916815260200190815260200160002060020180546001816001161561010002031660029004905014155b15610dc25760006101086000866000191660001916815260200190815260200160002060000160009054906101000a900473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff161415610a5057610a496101086000866000191660001916815260200190815260200160002060010154610108600087600019166000191681526020019081526020016000206002018054600181600116156101000203166002900480601f016020809104026020016040519081016040528092919081815260200182805460018160011615610100020316600290048015610a3f5780601f10610a1457610100808354040283529160200191610a3f565b820191906000526020600020905b815481529060010190602001808311610a2257829003601f168201915b5050505050611b37565b9150610b71565b6101086000856000191660001916815260200190815260200160002060000160009054906101000a900473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff166101086000866000191660001916815260200190815260200160002060010154610108600087600019166000191681526020019081526020016000206002016040518082805460018160011615610100020316600290048015610b4a5780601f10610b1f57610100808354040283529160200191610b4a565b820191906000526020600020905b815481529060010190602001808311610b2d57829003601f168201915b505091505060006040518083038185876185025a03f1925050501515610b705760006000fd5b5b7fe3a3a4111a84df27d76b68dc721e65c7711605ea5eee4afd3a9c58195217365c338561010860008860001916600019168152602001908152602001600020600101546101086000896000191660001916815260200190815260200160002060000160009054906101000a900473ffffffffffffffffffffffffffffffffffffffff1661010860008a6000191660001916815260200190815260200160002060020187604051808773ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200186600019166000191681526020018581526020018473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff168152602001806020018373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff168152602001828103825284818154600181600116156101000203166002900481526020019150805460018160011615610100020316600290048015610d475780601f10610d1c57610100808354040283529160200191610d47565b820191906000526020600020905b815481529060010190602001808311610d2a57829003601f168201915b505097505050505050505060405180910390a16101086000856000191660001916815260200190815260200160002060006000820160006101000a81549073ffffffffffffffffffffffffffffffffffffffff02191690556001820160009055600282016000610db79190611be6565b505060019250610dc3565b5b5b5b5050919050565b600036604051808383808284378201915050925050506040518091039020610df381611678565b15610e0157816002819055505b5b5b5050565b60006000610e1333610659565b1561127357600084849050148015610e305750610e2f85611b51565b5b80610e3d57506001600054145b15610fed5760008673ffffffffffffffffffffffffffffffffffffffff161415610ea457610e9d8585858080601f016020809104026020016040519081016040528093929190818152602001838380828437820191505050505050611b37565b9050610ef3565b8573ffffffffffffffffffffffffffffffffffffffff168585856040518083838082843782019150509250505060006040518083038185876185025a03f1925050501515610ef25760006000fd5b5b7f9738cd1a8777c86b011f7b01d87d484217dc6ab5154a9d41eda5d14af8caf292338688878786604051808773ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020018681526020018573ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff168152602001806020018373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020018281038252858582818152602001925080828437820191505097505050505050505060405180910390a1611271565b6000364360405180848480828437820191505082815260200193505050506040518091039020915060006101086000846000191660001916815260200190815260200160002060000160009054906101000a900473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16148015611099575060006101086000846000191660001916815260200190815260200160002060010154145b80156110d85750600061010860008460001916600019168152602001908152602001600020600201805460018160011615610100020316600290049050145b1561118f57856101086000846000191660001916815260200190815260200160002060000160006101000a81548173ffffffffffffffffffffffffffffffffffffffff021916908373ffffffffffffffffffffffffffffffffffffffff160217905550846101086000846000191660001916815260200190815260200160002060010181905550838361010860008560001916600019168152602001908152602001600020600201919061118d929190611c2e565b505b6111988261082f565b1515611270577f1733cbb53659d713b79580f79f3f9ff215f78a7c7aa45890f3b89fc5cddfbf328233878988886040518087600019166000191681526020018673ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020018581526020018473ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff168152602001806020018281038252848482818152602001925080828437820191505097505050505050505060405180910390a15b5b5b5b5b50949350505050565b60006000600061010560003373ffffffffffffffffffffffffffffffffffffffff16815260200190815260200160002054925060008314156112be5761138c565b8260020a9150610106600085600019166000191681526020019081526020016000209050600082826001015416111561138b5780600001600081548092919060010191905055508181600101600082825403925050819055507fc7fb647e59b18047309aa15aad418e5d7ca96d173ad704f1031a2c3d7591734b3385604051808373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200182600019166000191681526020019250505060405180910390a15b5b50505050565b6000366040518083838082843782019150509250505060405180910390206113b981611678565b15611415576001548211156113cd57611414565b816000819055506113dc611890565b7facbdb084c721332ac59f9b8e392196c9eb0e4932862da8eb9beaf0dad4f550da826040518082815260200191505060405180910390a15b5b5b5050565b600060006000600061010660008760001916600019168152602001908152602001600020925061010560008673ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020549150600082141561147f5760009350611493565b8160020a9050600081846001015416141593505b50505092915050565b6000600560018301610100811015156114b157fe5b0160005b505490505b919050565b60006000366040518083838082843782019150509250505060405180910390206114e881611678565b1561166b576114f683610659565b156115005761166a565b61010560008573ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020549150600082141561153b5761166a565b611543611890565b8273ffffffffffffffffffffffffffffffffffffffff166005836101008110151561156a57fe5b0160005b5081905550600061010560008673ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020819055508161010560008573ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020819055507fb532073b38c83145e3e5135377a08bf9aab55bc0fd7c1179cd4fb995d2a5159c8484604051808373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020018273ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff1681526020019250505060405180910390a15b5b5b50505050565b60025481565b600060006000600061010560003373ffffffffffffffffffffffffffffffffffffffff16815260200190815260200160002054925060008314156116bb57611888565b6101066000866000191660001916815260200190815260200160002091506000826000015414156117455760005482600001819055506000826001018190555061010780548091906001016117109190611cae565b826002018190555084610107836002015481548110151561172d57fe5b906000526020600020900160005b5081600019169055505b8260020a90506000818360010154161415611887577fe1c52dc63b719ade82e8bea94cc41a0d5d28e4aaf536adb5e9cccc9ff8c1aeda3386604051808373ffffffffffffffffffffffffffffffffffffffff1673ffffffffffffffffffffffffffffffffffffffff16815260200182600019166000191681526020019250505060405180910390a16001826000015411151561185e57610107610106600087600019166000191681526020019081526020016000206002015481548110151561180a57fe5b906000526020600020900160005b5060009055610106600086600019166000191681526020019081526020016000206000600082016000905560018201600090556002820160009055505060019350611888565b8160000160008154809291906001900391905055508082600101600082825417925050819055505b5b5b505050919050565b60006000610107805490509150600090505b818110156119bc576101086000610107838154811015156118bf57fe5b906000526020600020900160005b50546000191660001916815260200190815260200160002060006000820160006101000a81549073ffffffffffffffffffffffffffffffffffffffff021916905560018201600090556002820160006119269190611be6565b505060006001026101078281548110151561193d57fe5b906000526020600020900160005b5054600019161415156119b05761010660006101078381548110151561196d57fe5b906000526020600020900160005b505460001916600019168152602001908152602001600020600060008201600090556001820160009055600282016000905550505b5b8060010190506118a2565b61010760006119cb9190611cda565b5b5050565b6000600190505b600154811015611b33575b60015481108015611a095750600060058261010081101515611a0057fe5b0160005b505414155b15611a1b5780806001019150506119e2565b5b6001600154118015611a4557506000600560015461010081101515611a3d57fe5b0160005b5054145b15611a625760016000815480929190600190039190505550611a1c565b60015481108015611a8b57506000600560015461010081101515611a8257fe5b0160005b505414155b8015611aac5750600060058261010081101515611aa457fe5b0160005b5054145b15611b2e57600560015461010081101515611ac357fe5b0160005b505460058261010081101515611ad957fe5b0160005b508190555080610105600060058461010081101515611af857fe5b0160005b50548152602001908152602001600020819055506000600560015461010081101515611b2457fe5b0160005b50819055505b6119d7565b5b50565b600081516020830184f09050803b15610000575b92915050565b6000611b5c33610659565b15611bc957600454611b6c611bcf565b1115611b89576000600381905550611b82611bcf565b6004819055505b600354826003540110158015611ba55750600254826003540111155b15611bc3578160036000828254019250508190555060019050611bc8565b600090505b5b5b919050565b60006201518042811515611bdf57fe5b0490505b90565b50805460018160011615610100020316600290046000825580601f10611c0c5750611c2b565b601f016020900490600052602060002090810190611c2a9190611cfc565b5b50565b828054600181600116156101000203166002900490600052602060002090601f016020900481019282601f10611c6f57803560ff1916838001178555611c9d565b82800160010185558215611c9d579182015b82811115611c9c578235825591602001919060010190611c81565b5b509050611caa9190611cfc565b5090565b815481835581811511611cd557818360005260206000209182019101611cd49190611d21565b5b505050565b5080546000825590600052602060002090810190611cf89190611d21565b5b50565b611d1e91905b80821115611d1a576000816000905550600101611d02565b5090565b90565b611d4391905b80821115611d3f576000816000905550600101611d27565b5090565b90565b60006001541115611d575760006000fd5b611d6081611d71565b611d6a8383611d9c565b5b5b505050565b60006001541115611d825760006000fd5b80600281905550611d91611bcf565b6004819055505b5b50565b600060006001541115611daf5760006000fd5b600082111515611dbf5760006000fd5b81835110151515611dd05760006000fd5b8251600181905550600090505b8251811015611e85578281815181101515611df457fe5b9060200190602002015173ffffffffffffffffffffffffffffffffffffffff1660058260010161010081101515611e2757fe5b0160005b50819055508060010161010560008584815181101515611e4757fe5b9060200190602002015173ffffffffffffffffffffffffffffffffffffffff168152602001908152602001600020819055505b806001019050611ddd565b816000819055505b5b5050505600a165627a7a7230582084feb3505964efa62a6ffa78d913a175fe7bc168dd50067d25b1d5ddb6d10a1e0029</span></span></code></pre> <ul> <li>Storage: <ul> <li><code>0x0000000000000000000000000000000000000000000000000000000000000000</code>: <code>0x0000000000000000000000000000000000000000000000000000000000000001</code></li> <li><code>0x0000000000000000000000000000000000000000000000000000000000000001</code>: <code>0x0000000000000000000000000000000000000000000000000000000000000001</code></li> <li><code>0x0000000000000000000000000000000000000000000000000000000000000004</code>: <code>0x00000000000000000000000000000000000000000000000000000000000044e1</code></li> <li><code>0xa5baec7d73105a3c7298203bb205bbc41b63fa384ae73a6016b890a7ca29ae2d</code>: <code>0x0000000000000000000000000000000000000000000000000000000000000001</code></li> </ul> </li> </ul> <p>The balance of the account shall be left unchanged.</p> <h3 id="alternate-specification-via-codehash-999b">Alternate Specification via Codehash (999b)</h3> <p>At <code>CNSTNTNPL_FORK_BLKNUM</code>, directly recreate the account <code>0x863DF6BFa4469f3ead0bE8f9F2AAE51c91A907b4</code> with the following parameters:</p> <ul> <li>Nonce: <code>0x1</code></li> <li>Storage: <ul> <li><code>0x0000000000000000000000000000000000000000000000000000000000000000</code>: <code>0x0000000000000000000000000000000000000000000000000000000000000001</code></li> <li><code>0x0000000000000000000000000000000000000000000000000000000000000001</code>: <code>0x0000000000000000000000000000000000000000000000000000000000000001</code></li> <li><code>0x0000000000000000000000000000000000000000000000000000000000000004</code>: <code>0x00000000000000000000000000000000000000000000000000000000000044e1</code></li> <li><code>0xa5baec7d73105a3c7298203bb205bbc41b63fa384ae73a6016b890a7ca29ae2d</code>: <code>0x0000000000000000000000000000000000000000000000000000000000000001</code></li> </ul> </li> </ul> <p>In addition, the codehash at that address shall be replaced by the codehash at address <code>0x21C9E434c669c4d73f55215A6F2130A185E127AC</code>. The codehash is <code>0x6209d55547da7b035d54ef8d73275e863d3072b91da6ace1614fa6381f4e2c09</code>. The balance of the account shall be left unchanged.</p> <h2 id="rationale">Rationale</h2> <p>The design decision to restore the <code>WalletLibrary</code> contract code in a single state transition was made after lengthy discussions of <a rel="external" href="https://gist.github.com/5chdn/a9bb8617cc8523a030126a3d1c60baf3">alternate proposals</a> that explored different ways to improve the Ethereum protocol to allow contract revivals by adding different built-in contracts. It was eventually concluded that all of these proposals changing the EVM semantics around self-destructed contracts were introducing unwanted side-effects and <a rel="external" href="https://medium.com/@weka/on-paritys-proposed-changes-to-selfdestruct-behaviour-c3f0e5bc0f49">potential risks</a> to the existing smart-contract ecosystem on the Ethereum platform.</p> <p>The total supply of Ether is neither changed nor does this proposal require the transfer of any tokens or assets including Ether. It is assumed that this change is aligned with the interests both of (A) Parity Technologies that intended to provide a smart-contracts library for multi-signature wallets to last forever for its users and (B) the users of the multi-signature wallets that meant to safely store their assets in a contract accessible any time they desire. Lastly, the client-side implementation cost of this proposal is estimated to be low. A sample implementation will be attached and linked in the following sections.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal introduces backwards incompatibilities in the state of the contract at <code>0x863DF6BFa4469f3ead0bE8f9F2AAE51c91A907b4</code>. The Ethereum protocol does not allow the restoration of self-destructed contracts. To implement this on the Ethereum blockchain, it is recommended to add the necessary state transition in a future hard-fork at a well-defined block number, e.g., <code>CNSTNTNPL_FORK_BLKNUM</code> for the Constantinople milestone which is supposed to be the next scheduled hard-fork on the Ethereum road-map.</p> <h2 id="implementation">Implementation</h2> <p>A proof-of-concept implementation is available for the Parity client on branch <a rel="external" href="https://github.com/paritytech/parity/compare/a5-eip999-poc"><code>a5-eip999-poc</code></a> (<a rel="external" href="https://github.com/paritytech/parity/pull/8406">#8406</a>). A sample chain configuration for Parity can be found at the same branch in <a rel="external" href="https://github.com/paritytech/parity/blob/891e633021eec78dd62104bf5a99af50f66b06c7/ethcore/res/ethereum/multisig_test.json#L38-L51"><code>multisig_test.json</code></a> describing the state change as specified 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-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 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-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Juliano Rizzohttps://github.com/juli https://wg-eips.ritovision.com/1191/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP extends <a href="https://wg-eips.ritovision.com/55/">EIP-55</a> by optionally adding a chain id defined by <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> to the checksum calculation.</p> <h2 id="abstract">Abstract</h2> <p>The <a href="https://wg-eips.ritovision.com/55/">EIP-55</a> was created to prevent users from losing funds by sending them to invalid addresses. This EIP extends <a href="https://wg-eips.ritovision.com/55/">EIP-55</a> to protect users from losing funds by sending them to addresses that are valid but that where obtained from a client of another network.For example, if this EIP is implemented, a wallet can alert the user that is trying to send funds to an Ethereum Testnet address from an Ethereum Mainnet wallet.</p> <h2 id="motivation">Motivation</h2> <p>The motivation of this proposal is to provide a mechanism to allow software to distinguish addresses from different Ethereum based networks. This proposal is necessary because Ethereum addresses are hashes of public keys and do not include any metadata. By extending the <a href="https://wg-eips.ritovision.com/55/">EIP-55</a> checksum algorithm it is possible to achieve this objective.</p> <h2 id="specification">Specification</h2> <p>Convert the address using the same algorithm defined by <a href="https://wg-eips.ritovision.com/55/">EIP-55</a> but if a registered chain id is provided, add it to the input of the hash function. If the chain id passed to the function belongs to a network that opted for using this checksum variant, prefix the address with the chain id and the <code>0x</code> separator before calculating the hash. Then convert the address to hexadecimal, but if the ith digit is a letter (ie. it's one of <code>abcdef</code>) print it in uppercase if the 4*ith bit of the calculated hash is 1 otherwise print it in lowercase.</p> <h2 id="rationale">Rationale</h2> <p>Benefits:</p> <ul> <li>By means of a minimal code change on existing libraries, users are protected from losing funds by mixing addresses of different Ethereum based networks.</li> </ul> <h2 id="implementation">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">!/usr/bin/python3</span></span> <span class="giallo-l"><span class="z-keyword">from</span><span> sha3</span><span class="z-keyword"> import</span><span> keccak_256</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> random</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"> addr (str): Hexadecimal address, 40 characters long with 2 characters prefix</span></span> <span class="giallo-l"><span class="z-string"> chainid (int): chain id from EIP-155 </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-entity z-name"> eth_checksum_encode</span><span>(</span><span class="z-variable z-parameter z-function">addr</span><span>,</span><span class="z-variable z-parameter z-function"> chainid</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> adopted_eip1191</span><span class="z-keyword"> =</span><span> [</span><span class="z-constant">30</span><span>,</span><span class="z-constant"> 31</span><span>]</span></span> <span class="giallo-l"><span> hash_input</span><span class="z-keyword"> =</span><span class="z-support"> str</span><span>(</span><span>chainid</span><span>)</span><span class="z-keyword"> +</span><span> addr</span><span>.</span><span>lower</span><span>(</span><span>)</span><span class="z-keyword"> if</span><span> chainid</span><span class="z-keyword"> in</span><span> adopted_eip1191</span><span class="z-keyword"> else</span><span> addr</span><span>[</span><span class="z-constant">2</span><span>:</span><span>]</span><span>.</span><span>lower</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> hash_output</span><span class="z-keyword"> =</span><span> keccak_256</span><span>(</span><span>hash_input</span><span>.</span><span>encode</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">utf8</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>)</span><span>.</span><span>hexdigest</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> aggregate</span><span class="z-keyword"> =</span><span class="z-support"> zip</span><span>(</span><span>addr</span><span>[</span><span class="z-constant">2</span><span>:</span><span>]</span><span>.</span><span>lower</span><span>(</span><span>)</span><span>,</span><span>hash_output</span><span>)</span></span> <span class="giallo-l"><span> out</span><span class="z-keyword"> =</span><span> addr</span><span>[</span><span>:</span><span class="z-constant">2</span><span>]</span><span class="z-keyword"> +</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-punctuation z-definition z-string">&#39;</span><span>.</span><span>join</span><span>(</span><span>[</span><span>c</span><span>.</span><span>upper</span><span>(</span><span>)</span><span class="z-keyword"> if</span><span class="z-support"> int</span><span>(</span><span>a</span><span>,</span><span class="z-constant">16</span><span>)</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> 8</span><span class="z-keyword"> else</span><span> c</span><span class="z-keyword"> for</span><span> c</span><span>,</span><span>a</span><span class="z-keyword"> in</span><span> aggregate</span><span>]</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> out</span></span></code></pre><h2 id="test-cases">Test Cases</h2> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>eth_mainnet</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">0x27b1fdb04752bbc536007a920d24acb045561c26</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">0x3599689E6292b81B2d85451025146515070129Bb</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">0x42712D45473476b98452f434e72461577D686318</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">0x52908400098527886E0F7030069857D2E4169EE7</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">0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed</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">0x6549f4939460DE12611948b3f82b88C3C8975323</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">0x66f9664f97F2b50F62D13eA064982f936dE76657</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">0x8617E340B3D01FA5F11F306F4090FD50E238070D</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">0x88021160C5C792225E4E5452585947470010289D</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">0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb</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">0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB</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">0xde709f2102306220921060314715629080e2fb77</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">0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359</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>rsk_mainnet</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">0x27b1FdB04752BBc536007A920D24ACB045561c26</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">0x3599689E6292B81B2D85451025146515070129Bb</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">0x42712D45473476B98452f434E72461577d686318</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">0x52908400098527886E0F7030069857D2E4169ee7</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">0x5aaEB6053f3e94c9b9a09f33669435E7ef1bEAeD</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">0x6549F4939460DE12611948B3F82B88C3C8975323</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">0x66F9664f97f2B50F62d13EA064982F936de76657</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">0x8617E340b3D01Fa5f11f306f4090fd50E238070D</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">0x88021160c5C792225E4E5452585947470010289d</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">0xD1220A0Cf47c7B9BE7a2e6ba89F429762E7B9adB</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">0xDBF03B407c01E7CD3cBea99509D93F8Dddc8C6FB</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">0xDe709F2102306220921060314715629080e2FB77</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">0xFb6916095cA1Df60bb79ce92cE3EA74c37c5d359</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>rsk_testnet</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">0x27B1FdB04752BbC536007a920D24acB045561C26</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">0x3599689e6292b81b2D85451025146515070129Bb</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">0x42712D45473476B98452F434E72461577D686318</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">0x52908400098527886E0F7030069857D2e4169EE7</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">0x5aAeb6053F3e94c9b9A09F33669435E7EF1BEaEd</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">0x6549f4939460dE12611948b3f82b88C3c8975323</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">0x66f9664F97F2b50f62d13eA064982F936DE76657</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">0x8617e340b3D01fa5F11f306F4090Fd50e238070d</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">0x88021160c5C792225E4E5452585947470010289d</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">0xd1220a0CF47c7B9Be7A2E6Ba89f429762E7b9adB</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">0xdbF03B407C01E7cd3cbEa99509D93f8dDDc8C6fB</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">0xDE709F2102306220921060314715629080e2Fb77</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">0xFb6916095CA1dF60bb79CE92ce3Ea74C37c5D359</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>test_cases</span><span class="z-keyword"> =</span><span> {</span><span class="z-constant">30</span><span> :</span><span> rsk_mainnet</span><span>,</span><span class="z-constant"> 31</span><span> :</span><span> rsk_testnet</span><span>,</span><span class="z-constant"> 1</span><span> :</span><span> eth_mainnet</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">for</span><span> chainid</span><span>,</span><span> cases</span><span class="z-keyword"> in</span><span> test_cases</span><span>.</span><span>items</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> addr</span><span class="z-keyword"> in</span><span> cases</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> (</span><span> addr</span><span class="z-keyword"> ==</span><span> eth_checksum_encode</span><span>(</span><span>addr</span><span>,</span><span>chainid</span><span>)</span><span> )</span></span></code></pre><h2 id="usage">Usage</h2> <h3 id="usage-table">Usage Table</h3> <table><thead><tr><th>Network</th><th>Chain id</th><th>Supports this EIP</th></tr></thead><tbody> <tr><td>RSK Mainnet</td><td>30</td><td>Yes</td></tr> <tr><td>RSK Testnet</td><td>31</td><td>Yes</td></tr> </tbody></table> <h3 id="implementation-table">Implementation Table</h3> <table><thead><tr><th>Project</th><th>EIP Usage</th><th>Implementation</th></tr></thead><tbody> <tr><td>MyCrypto</td><td>Yes</td><td><a rel="external" href="https://github.com/MyCryptoHQ/MyCrypto/blob/develop/common/utils/formatters.ts#L126">JavaScript</a></td></tr> <tr><td>MyEtherWallet</td><td>Yes</td><td><a rel="external" href="https://github.com/MyEtherWallet/MyEtherWallet/blob/73c4a24f8f67c655749ac990c5b62efd92a2b11a/src/helpers/addressUtils.js#L22">JavaScript</a></td></tr> <tr><td>Ledger</td><td>Yes</td><td><a rel="external" href="https://github.com/LedgerHQ/ledger-app-eth/blob/master/src_common/ethUtils.c#L203">C</a></td></tr> <tr><td>Trezor</td><td>Yes</td><td><a rel="external" href="https://github.com/trezor/trezor-core/blob/270bf732121d004a4cd1ab129adaccf7346ff1db/src/apps/ethereum/get_address.py#L32">Python</a> and <a rel="external" href="https://github.com/trezor/trezor-crypto/blob/4153e662b60a0d83c1be15150f18483a37e9092c/address.c#L62">C</a></td></tr> <tr><td>Web3.js</td><td>Yes</td><td><a rel="external" href="https://github.com/ethereum/web3.js/blob/aaf26c8806bc9fb60cf6dcb6658104963c6c7fc7/packages/web3-utils/src/Utils.js#L140">JavaScript</a></td></tr> <tr><td>EthereumJS-util</td><td>Yes</td><td><a rel="external" href="https://github.com/ethereumjs/ethereumjs-util/pull/204/commits/cdf0b3c996b05ac5b1f758f17ea9f9ed1847c1eb">JavaScript</a></td></tr> <tr><td>ENS address-encoder</td><td>Yes</td><td><a rel="external" href="https://github.com/ensdomains/address-encoder/commit/5bf53b13fa014646ea28c9e5f937361dc9b40590">TypeScript</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-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-03-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 James Rayhttps://github.com/jamesray1 Micah Zoltuhttps://github.com/MicahZoltu https://wg-eips.ritovision.com/908/ <h2 id="a-reward-for-running-a-full-node-is-deprecated-but-the-proposal-for-a-reward-for-clients-remains">A reward for running a full node is deprecated, but the proposal for a reward for clients remains</h2> <p>While Casper validators are incentivized to validate transactions, there are still no incentives for relaying blocks and storing data (which includes state). This paper is more a high-level analysis and discussion rather than attempting to provide a concrete solution. <a rel="external" href="https://www.pokt.network/">Pocket Network</a> is a separate blockchain being designed as of Sept 2018 that incentivises relaying transactions, that is intended to be compatible with other blockchains. Note also that <a rel="external" href="https://github.com/rocket-pool/rocketpool">Rocket Pool</a> is under development and is planned to be a pool for Casper, which will help to incentivise running a full node. Another alternative is <a rel="external" href="https://github.com/vipnode/vipnode.org">VIPnode</a> which charges fees to light clients for full nodes that serve them. In light of these solutions being developed, perhaps a more appropriate approach to generally rewarding clients would be to incentivize bandwidth (relaying and downloading), storage and I/O (while computation is already incentivized with gas for miners and will be for proposers under sharding and Casper). Note also that notaries will be incentivized to download collations under sharding. Outdated (Casper FFG will be implemented with Ethereum 2.0 with sharding: <a rel="external" href="https://notes.ethereum.org/SCIg8AH5SA-O4C1G1LYZHQ#">shasper</a>): given that it looks like Casper FFG will be implemented soon, to minimize undue complexity to the protocol, incentivizing validation in the mean time may be considered not worthwhile. For a previous version of the proposal containing a proposal for rewarding a full node, refer to <a rel="external" href="https://github.com/ethereum/EIPs/commit/97e235d0ba4a88b4ce29834aa2b94107b8d91e12#diff-9a43a8739b5a9e1dec427324cb264921">here</a>.</p> <h2 id="simple-summary">Simple Summary</h2> <p>When each transaction is validated, give a reward to clients for developing the client.</p> <h2 id="abstract">Abstract</h2> <p>The tragedy of the commons is a phenomenon that is well known in many sectors, most notably in regard to sustainability. It involves the over-utilization of shared finite resources, which detriments all participants and stakeholders involved (which in the case of a global public good can be everyone, including future generations). Without proper management of public resources, a tragedy of the commons can occur. Internalizing externalities (where externalities can be broadly defined as effects that are not accounted for in the intrinsic price of a good, service or resource) is one way of incentivizing the proper management of resources, although other methods that actually properly manage them are necessary. This EIP proposes to make a change to the protocol to provide a reward to clients for providing the software that enables Ethereum to function, where the reward can include a proportion of transaction fees (reducing the full proportion that the miner currently receives), and some newly minted ETH. Thus, clients are incentivized to maintain and improve the security and health of the Ethereum protocol and ecosystem. To summarize the mechanism in the proposal, a user agent is attached to a transaction, where this user agent contains a vector with the index of a client address in an access list. The client address could be inserted by the client and verified that it is the same as a read-only constant in the client's storage.</p> <p>Reward mechanisms that are external to being built in to the protocol are beyond the scope of this EIP. Such extra-protocol reward methods include state channel payments for extra services such as light client servers providing faster information such as receipts; state channel payments for buying state reads from full nodes; archival services (which is only applicable to future proposed versions of Ethereum with stateless clients); and tokens for the client and running full nodes.</p> <h2 id="motivation">Motivation</h2> <p>Currently there is a lack of incentives for anyone to run a full node, while joining a mining pool is not really economical if one has to purchase a mining rig (several GPUs) now, since there is unlikely to be a return on investment by the time that Ethereum transitions to hybrid Proof-of-Work/Proof-of-Stake with <a href="https://wg-eips.ritovision.com/1011/">Casper FFG</a>, then full PoS with <a rel="external" href="https://github.com/ethereum/research/blob/master/papers/CasperTFG/CasperTFG.pdf">CBC Casper</a>.</p> <p>Additionally, providing a reward for clients gives a revenue stream that is independent of state channels or other layer 2 mechanisms, which are less secure, although this insecurity can be offset by mechanisms such as insurance, bonded payments and time locks. Rationalising that investors may invest in a client because it is an enabler for the Ethereum ecosystem (and thus opening up investment opportunities) may not scale very well, and it seems that it is more sustainable to monetize the client as part of the service(s) that it provides.</p> <p>While it may be argued that the funds raised by the Ethereum pre-mine (the pre-ICO and the ICO) can be used to fund client development, that argument is questionable, since Parity is VC-funded, and other clients such as Prysmatic Labs <a rel="external" href="https://medium.com/@XYOracleNetwork?source=search_post">1</a>, <a rel="external" href="https://twitter.com/prylabs/status/996391036753666050">2</a>, <a rel="external" href="https://medium.com/prysmatic-labs/biweekly-development-update-2-d29d0c91e7d0">3</a> and <a rel="external" href="https://medium.com/compound-finance/introducing-exthereum-the-newest-ethereum-client-7a5e30d4d6aa">exthereum</a> have received funding from other parties, whereas perhaps they would not have needed to do so if there was sufficient funding from the Ethereum pre-mine funds. <a rel="external" href="https://github.com/Drops-of-Diamond/diamond_drops">Drops of Diamond</a> is yet to receive any funding.</p> <p>Incentivizing client development would more directly incentivize resource provision in the protocol, preventing a tragedy of the commons, where there is an extreme lack of supply and excess demand, leading to the protocol being unusable.</p> <p>See <a rel="external" href="https://eprint.iacr.org/2014/452.pdf#subsection.2.1">here</a> for an analysis in the context of Bitcoin, PoW, and a hybrid PoW/PoS protocol. While Ethereum has a gas limit, the section points out that this is not enough as the market cap increases and the incentive to attack the network increases, while the ratio of security costs to transaction fees does not, while PoS will further alleviate the problem. However, the section points out that PoS is not enough, since the costs of propagating, verifying and storing transactions are not incentivised. Note that the "Proof of Activity: Extending Bitcoin’s Proof of Work via Proof of Stake" paper also contains a scheme for incentivizing a target participation level.</p> <blockquote> <p>The word “activity” in the phrase Proof of Activity emphasizes the point that only active stakeholders who maintain a full online node get rewarded, in exchange for the vital services that they provide for the network. This stands in contrast to earlier Proof of Stake schemes in which offline stake can accumulate weight over time, and may ultimately be utilized in double-spending attacks.</p> </blockquote> <p>We can also incentivize full nodes to propagate transactions and to store transactions or state, in addition to verifying them. While these first two incentivizations are outside the scope of this EIP, there are proposals <a rel="external" href="https://ethresear.ch/t/incentivizing-a-robust-p2p-network-relay-layer/1438">here</a> and <a rel="external" href="https://ethresear.ch/t/incentivizing-full-state-nodes/1640">here</a>, respectively.</p> <p>Implementing this as a layer 2 solution may not ensure the sustainability of the protocol, since not everyone would use it; if the protocol doesn't have any cost for full nodes to validate transactions, then people will take advantage of that and not use the layer 2 solution. It seems that you should at least have the part where the reward is provided in protocol, but then that and the user agent signature doesn't really add anything else to the protocol, so doing some part in-protocol and some part e.g. the verification or a verification-game off-protocol could be done, but it's already done in protocol. Note also that some computationally expensive tasks are too challenging to feasibly do in protocol, e.g. due to not fitting in the gas limit, could be done with Truebit, where verifiers have an incentive.</p> <p>Not providing incentives for clients is an issue now as there is less incentive to build a client that aligns with the needs of users, funds need to be raised externally to the protocol to fund client development, which is not as decentralized. If only a smaller subset is able to fund client development, such as VCs, angel investors and institutional investors, that may not align well with the interests of all current and potential stakeholders of Ethereum (which includes future stakeholders). Ostensibly, one of the goals of Ethereum is to decentralize everything, including wealth, or in other words, to improve wealth equality. Not providing incentives for full nodes validating transactions may not seem like as much of an issue now, but not doing so could hinder the growth of the protocol. Of course, incentives aren't enough, it also needs to be technically decentralized so that it is ideally possible for a low-end mainstream computer or perhaps even a mobile or embedded IoT device to be a verifying full node, or at least to be able to help with securing the network if it is deemed impractical for them to be a full node.</p> <p>Note that with a supply cap (as in <a rel="external" href="https://github.com/ethereum/EIPs/issues/960">EIP-960</a>, the issuance can be prevented from increasing indefinitely. Alternatively, it could at least be reduced (still potentially but not necessarily to zero, or to the same rate at which Ether is burnt when slashing participants, such as validators under a Casper PoS scheme or notaries under a sharding scheme), e.g. by hard forks, or as per <a href="https://wg-eips.ritovision.com/1015/">EIP-1015</a>, an on-chain contract governed by a decision assembly that gets signalling from other contracts that represent some set of stakeholders.</p> <h2 id="specification">Specification</h2> <p>Add a new field to each block called <code>PrevBlockVerifications</code>, which is an arbitrary, unlimited size byte array. When a client verifies that a previous block is <a rel="external" href="https://ethereum.github.io/yellowpaper/paper.pdf#subsubsection.4.3.2">valid</a>, the client appends a user agent to PrevBlockVerifications via an opcode in a transaction, PREV_BLOCK_VERIF. The user agent is a vector with the immutable fields: the blockhash of the block that is validated, and the index of a client address in an access list (details are below). A miner validates a transaction before including it in a block, however they are not able to change these fields of the vector because they're immutable.</p> <p>Send 0.15 ETH to the client (see the rationale below), when the block is processed. The amounts could include a proportion of transaction fees (while the miner would then receive less), which would reduce newly issued ETH. These amounts are specified in new <code>ClientReward</code> fields in the block.</p> <p>In order to only incentivize verifying recent blocks, assert that the block number corresponding to a blockhash is less than 400 blocks ago.</p> <h3 id="attacks-and-added-specifications-to-prevent-them">Attacks and added specifications to prevent them</h3> <p>A miner could create a client and fill their block with transactions that only contain the PREV_BLOCK_VERIF opcode (or alternatively, arbitrarily complex transactions, still with the opcode), with previous blockhashes that they have validated and the address of their client. To prevent this, state would have to store a list containing lists, with each sublist listing the blockhashes up to 400 blocks ago that correspond to a miner, then a miner (or a proposer under Casper CBC) could have to put down a deposit, and be slashed if the proposer inserts such a transaction (that contains a blockhash which they have already proposed, not just in a block but at any time previously). Updating the state to remove blockhashes more than 400 blocks ago would add additional overhead, although you could add an extra window for older blocks, say 120,000 blocks (roughly every 3 weeks), still ignore blocks that are older than 400 blocks ago, and remove these older 120,000 blocks every 120,000 blocks. An attacker could bribe a miner/proposer to include transactions like above that contain an address of a client in the access list which they own. However, the above slashing condition should disincentivize this.</p> <h3 id="more-details-on-the-access-list">More details on the access list</h3> <p>The access list prevents anyone inserting any address to the first element of the vector, where there may be a way to prevent censorship and centralization of authority of who decides to register new addresses in the list, e.g. on-chain governance with signalling (possibly similar to <a href="https://wg-eips.ritovision.com/1015/">EIP-1015</a>, which also specifies an alternative way of sending funds) or a layer 2 proof of authority network where new addresses can be added via a smart contract. Note that there may be serious drawbacks to implementing either of these listed examples. There is a refutation of <a rel="external" href="https://medium.com/@Vlad_Zamfir/against-on-chain-governance-a4ceacd040ca">on-chain governance</a> as well as of <a rel="external" href="https://vitalik.ca/general/2018/03/28/plutocracy.html">plutocracy</a>. <a rel="external" href="https://en.wikipedia.org/wiki/Proof-of-authority">Proof of Authority</a> isn't suitable for a public network since it doesn't distribute trust well. However, using signalling in layer 2 contracts is more acceptable, but Vlad Zamfir argues that using that to influence outcomes in the protocol can disenfranchise miners from being necessary participants in the governance process. Thus, in light of these counterpoints, having an access list may not be suitable until a decentralized, trustless way of maintaining it is implemented and ideally accepted by the majority of a random sample that represents the population of Ethereum users.</p> <p>However, another alternative to managing the access list would be to have decentralized verification that the address produced from querying an index in the access list does correspond to that of a "legitimate" client. Part of this verification would involve checking that there is a client that claims that this address is owned by them, that they are happy to receive funds in this manner and agree or arranged to putting the address in the access list, and that the client passes all tests in the <a rel="external" href="https://github.com/ethereum/tests">Ethereum test suite</a>. However, this last proviso would then preclude new clients being funded from the start of development, although such would-be clients would not be able to receive funds in-protocol until they implement the client anyway (as an aside, they could raise funds in various ways—a DAII, pronounced die-yee, is recommended, while a platform for DAIIs is under development by <a rel="external" href="https://dogezer.com/">Dogezer</a>). All of this could be done off-chain, and if anyone found that some address in the access list was not legitimate, then they could challenge that address with a proof of illegitimacy, and the participant that submitted the address to the access list could be slashed (while they must hold a deposit in order to register and keep an address in the access list).</p> <p>Additionally, it should help with being only able to read the client's address from the client, and the whole transaction could revert if the address is not in the access list. You could provide the index of the address in the access list, and then you could <code>assert</code> that the address found at that index matches that which can be read by the client (where the latter would be a read-only address).</p> <h2 id="rationale">Rationale</h2> <h3 id="a-rough-qualitative-analysis-of-fees">A rough qualitative analysis of fees</h3> <p>As of May 4 2018, there are <a rel="external" href="https://web.archive.org/web/20180504051128/https://ethernodes.org/network/1">16428 nodes</a>. Assume that an annual cost for an average client developer organisation is $1 million per annum. Projecting forward (and noting that the number of nodes should increase substantially if this EIP was implemented, thus aiding Ethereum's goal of decentralizing everything) assume that there are 10 clients. Thus let us assume that the number of nodes doubles to 30000 nodes within 5 years (this assumption is probably conservative, even if it is forward looking). Assume for simplicity that the costs of a client are entirely covered by this block reward.</p> <p>Average cost per client = number of nodes * Block reward per client / number of clients</p> <p>Block reward per client (worse case for ETH price) = Average revenue per client * number of clients / (ETH exchange rate * number of nodes)</p> <p>= $2,000,000 * 10 / (500 * 30,000)</p> <p>= 1.333333333 ETH</p> <p>Block reward per client (better case) = $1,000,000 * 10 / (2000 * 30,000) = 0.166666667 ETH</p> <p>Suppose that we use a block reward of 0.15 ETH for clients.</p> <!--There are more than 5552465 blocks and counting. With a reward of 0.001 ETH for each block, a full state node that verified every block would receive 5552.465 ETH. However, the difficulty of verifying blocks increases over time, so--> <h3 id="more-rationale-outdated-by-above">More rationale (outdated by above)</h3> <p>The amount of computation to validate a transaction will be the same as a miner, since the transaction will need to be executed. Thus, if there would be transaction fees for validating full nodes and clients, and transactions need to be executed by validators just like miners have to, it makes sense to have them calculated in the same way as gas fees for miners. This would controversially increase the amount of transaction fees a lot, since there can be many validators for a transaction. In other words, it is controversial whether to provide the same amount of transaction fee for a full node validator as for a miner (which in one respect is fair, since the validator has to do the same amount of computation), or prevent transaction fees from rising much higher, and have a transaction fee for a full node as, say, the transaction fee for a miner, divided by the average number of full nodes validating a transaction. The latter option seems even more controversial (but is still better than the status quo), since while there would be more of an incentive to run a full node than there is now with no incentive, validators would be paid less for performing the same amount of computation.</p> <p>And as for the absolute amounts, this will require data analysis, but clearly a full node should receive much less than a miner for processing a transaction in a block, since there are many transactions in a block, and there are many confirmations of a block. Data analysis could involve calculating the average number of full nodes verifying transactions in a block. Macroeconomic analysis could entail the economic security benefit that full nodes provide to the network.</p> <p>Now, as to the ratio of rewards to the client vs the full node, as an initial guess I would suggest something like 99:1. Why such a big difference? Well, I would guess that clients spend roughly 99 times more time on developing and maintaining the client than a full node user spends running and maintaining a full node. During a week there might be several full-time people working on the client, but a full node might only spend half an hour (or less) initially setting it up, plus running it, plus electricity and internet costs. Full node operators probably don't need to upgrade their computer (and buying a mining rig isn't worth it with Casper PoS planning on being implemented soon).</p> <p>However, on further analysis, clients would also get the benefit of a large volume of rewards from every full node running the client, so to incentivise full node operation further, the ratio could change to say, 4:1, or even 1:1, and of course could be adjusted with even further actual data analysis, rather than speculation.</p> <p>Providing rewards to full node validators and to clients would increase the issuance. In order to maintain the issuance at current levels, this EIP could also reduce the mining reward (despite being reduced previously with the Byzantium release in October 2017 from 5 ETH to 3 ETH), but that would generate more controversy and discussion.</p> <p>Another potential point of controversy with rewarding clients and full nodes is that the work previously done by them has not been paid for until now (except of course by the Ethereum Foundation or Parity VCs funding the work), so existing clients may say that this EIP gives an advantage to new entrants. However, this doesn't hold up well, because existing clients have the first mover advantage, with much development to create useful and well-used products.</p> <p>There is a tradeoff. Higher fees means you may cut out poor people and people who just don't want to pay fees. But if a laptop can run a full node and get paid for it then that would offset the fees through usage. Full nodes do provide a security benefit, so the total fees given could at least be some fraction of this benefit. Fees that go towards client development incentivise a higher quality client. To me, I think it makes more sense to internalize costs as much as possible: for computation, storage, bandwidth, I/O, client development, running full nodes, mining/validating, etc. You avoid a tragedy of the commons through externalizing costs. The more you internalize costs, the more sustainable it is, and the less you rely on rich people being generous, etc. (Although, getting philosophical, ultimately you can't force rich people to be generous, they have to do so out of the kindness of their hearts.)</p> <p>Regarding rewards for full nodes, in the <a rel="external" href="https://ethresear.ch/t/sharding-phase-1-spec/1407">draft phase 1 sharding spec</a> proposers acting as full nodes have rewards for proposing blobs (without execution) or later in phase 3 transactions (with execution) to be included into collations/blocks. So that would help. However, full nodes that do not act as proposers and just verify transactions, or <a rel="external" href="https://ethresear.ch/t/incentivizing-full-state-nodes/1640">full state nodes</a>, are still not incentivized.</p> <p>Note that while further quantitative analysis to specify fees should be done, some level of experimentation after implementing this method on-chain may be necessary.</p> <h3 id="security">Security</h3> <p>All of the below struck out information should be prevented via using an access list and verifying that the read-only address provided by the client matches with an address in the access list, as well as using a layer 2 solution such as a PoA network for censorship resistance and minimization of centralization in the access list.</p> <p>Further discussion is at https://ethresear.ch/t/incentives-for-running-full-ethereum-nodes/1239.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Introducing in-protocol fees is a backwards-incompatible change, so would be introduced in 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> 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-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/875/ <h2 id="summary">Summary</h2> <p>A simple non fungible token standard that allows batching tokens into lots and settling p2p atomic transfers in one transaction. You can test out an example implementation on rinkeby here: https://rinkeby.etherscan.io/address/0xffab5ce7c012bc942f5ca0cd42c3c2e1ae5f0005 and view the repo here: https://github.com/alpha-wallet/ERC-Example</p> <h2 id="purpose">Purpose</h2> <p>While other standards allow the user to transfer a non-fungible token, they require one transaction per token, this is heavy on gas and partially responsible for clogging the ethereum network. There are also few definitions for how to do a simple atomic swap.</p> <h2 id="rinkeby-example">Rinkeby example</h2> <p>This standard has been implemented in an example contract on rinkeby: https://rinkeby.etherscan.io/address/0xffab5ce7c012bc942f5ca0cd42c3c2e1ae5f0005</p> <h2 id="specification">Specification</h2> <h3 id="function-name-constant-returns-string-name">function name() constant returns (string name)</h3> <p>returns the name of the contract e.g. CarLotContract</p> <h3 id="function-symbol-constant-returns-string-symbol">function symbol() constant returns (string symbol)</h3> <p>Returns a short string of the symbol of the in-fungible token, this should be short and generic as each token is non-fungible.</p> <h3 id="function-balanceof-address-owner-public-view-returns-uint256-balance">function balanceOf(address _owner) public view returns (uint256[] balance)</h3> <p>Returns an array of the users balance.</p> <h3 id="function-transfer-address-to-uint256-tokens-public">function transfer(address _to, uint256[] _tokens) public;</h3> <p>Transfer your unique tokens to an address by adding an array of the token indices. This compares favourable to ERC721 as you can transfer a bulk of tokens in one go rather than one at a time. This has a big gas saving as well as being more convenient.</p> <h3 id="function-transferfrom-address-from-address-to-uint256-tokens-public">function transferFrom(address _from, address _to, uint256[] _tokens) public;</h3> <p>Transfer a variable amount of tokens from one user to another. This can be done from an authorised party with a specified key e.g. contract owner.</p> <h2 id="optional-functions">Optional functions</h2> <h3 id="function-totalsupply-constant-returns-uint256-totalsupply">function totalSupply() constant returns (uint256 totalSupply);</h3> <p>Returns the total amount of tokens in the given contract, this should be optional as assets might be allocated and issued on the fly. This means that supply is not always fixed.</p> <h3 id="function-ownerof-uint256-tokenid-public-view-returns-address-owner">function ownerOf(uint256 _tokenId) public view returns (address _owner);</h3> <p>Returns the owner of a particular token, I think this should be optional as not every token contract will need to track the owner of a unique token and it costs gas to loop and map the token id owners each time the balances change.</p> <h3 id="function-trade-uint256-expirytimestamp-uint256-tokenindices-uint8-v-bytes32-r-bytes32-s-public-payable">function trade(uint256 expiryTimeStamp, uint256[] tokenIndices, uint8 v, bytes32 r, bytes32 s) public payable</h3> <p>A function which allows a user to sell a batch of non-fungible tokens without paying for the gas fee (only the buyer has to) in a p2p atomic swap. This is achieved by signing an attestation containing the amount of tokens to sell, the contract address, an expiry timestamp, the price and a prefix containing the ERC spec name and chain id. A buyer can then pay for the deal in one transaction by attaching the appropriate ether to satisfy the deal.</p> <p>This design is also more efficient as it allows orders to be done offline until settlement as opposed to creating orders in a smart contract and updating them. The expiry timestamp protects the seller against people using old orders.</p> <p>This opens up the gates for a p2p atomic swap but should be optional to this standard as some may not have use for it.</p> <p>Some protections need to be added to the message such as encoding the chain id, contract address and the ERC spec name to prevent replays and spoofing people into signing message that allow a trade.</p> <h2 id="interface">Interface</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"> ERC165</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"> 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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC875</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC165 </span><span class="z-comment">*/</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"> 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>[</span><span>]</span><span class="z-variable"> tokenIndices</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"> name</span><span>(</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-variable"> name</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-entity z-name"> constant</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-variable"> symbol</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 class="z-variable z-parameter z-function"> _balances</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>[</span><span>]</span><span class="z-variable z-parameter z-function"> _tokens</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"> 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>[</span><span>]</span><span class="z-variable z-parameter z-function"> _tokens</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> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment">If you want the standard functions with atomic swap trading added</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC875WithAtomicSwapTrading</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC875</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> trade</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> expiryTimeStamp</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> tokenIndices</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> s</span></span> <span class="giallo-l"><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>}</span></span></code></pre><h2 id="example-implementation">Example implementation</h2> <p>Please visit this <a rel="external" href="https://github.com/alpha-wallet/ERC875">repo</a> to see an example 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> 2018-02-02T00:00:00+00:00 2026-02-11T14:49:28+00:00 Felix Langefjl@ethereum.org https://wg-eips.ritovision.com/868/ <h1 id="abstract">Abstract</h1> <p>This EIP defines an extension to Node Discovery Protocol v4 to enable authoritative resolution of <a href="https://wg-eips.ritovision.com/778/">Ethereum Node Records (ENR)</a>.</p> <h1 id="motivation">Motivation</h1> <p>To bridge current and future discovery networks and to aid the implementation of other relay mechanisms for ENR such as DNS, we need a way to request the most up-to-date version of a node record. This EIP provides a way to request it using the existing discovery protocol.</p> <h1 id="specification">Specification</h1> <p>Implementations of Node Discovery Protocol v4 should support two new packet types, a request and reply of the node record. The existing ping and pong packets are extended with a new field containing the sequence number of the ENR.</p> <h3 id="ping-packet-0x01">Ping Packet (0x01)</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>packet-data = [version, from, to, expiration, enr-seq]</span></span></code></pre> <p><code>enr-seq</code> is the current sequence number of the sending node's record. All other fields retain their existing meaning.</p> <h3 id="pong-packet-0x02">Pong Packet (0x02)</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>packet-data = [to, ping-hash, expiration, enr-seq]</span></span></code></pre> <p><code>enr-seq</code> is the current sequence number of the sending node's record. All other fields retain their existing meaning.</p> <h3 id="enrrequest-packet-0x05">ENRRequest Packet (0x05)</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>packet-data = [ expiration ]</span></span></code></pre> <p>When a packet of this type is received, the node should reply with an ENRResponse packet containing the current version of its record.</p> <p>To guard against amplification attacks, the sender of ENRRequest should have replied to a ping packet recently (just like for FindNode). The <code>expiration</code> field, a UNIX timestamp, should be handled as for all other existing packets i.e. no reply should be sent if it refers to a time in the past.</p> <h3 id="enrresponse-packet-0x06">ENRResponse Packet (0x06)</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>packet-data = [ request-hash, ENR ]</span></span></code></pre> <p>This packet is the response to ENRRequest.</p> <ul> <li><code>request-hash</code> is the hash of the entire ENRRequest packet being replied to.</li> <li><code>ENR</code> is the node record.</li> </ul> <p>The recipient of the packet should verify that the node record is signed by node who sent ENRResponse.</p> <h2 id="resolving-records">Resolving Records</h2> <p>To resolve the current record of a node public key, perform a recursive Kademlia lookup using the FindNode, Neighbors packets. When the node is found, send ENRRequest to it and return the record from the response.</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-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-24T00:00:00+00:00 2026-02-11T14:48:25+00:00 William Entrikenhttps://github.com/fulldecent Dieter Shirleydete@axiomzen.co Jacob Evansjacob@dekz.net Nastassia Sachsnastassia.sachs@protonmail.com https://wg-eips.ritovision.com/721/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for non-fungible tokens, also known as deeds.</p> <h2 id="abstract">Abstract</h2> <p>The following standard allows for the implementation of a standard API for NFTs within smart contracts. This standard provides basic functionality to track and transfer NFTs.</p> <p>We considered use cases of NFTs being owned and transacted by individuals as well as consignment to third party brokers/wallets/auctioneers ("operators"). NFTs can represent ownership over digital or physical assets. We considered a diverse universe of assets, and we know you will dream up many more:</p> <ul> <li>Physical property — houses, unique artwork</li> <li>Virtual collectibles — unique pictures of kittens, collectible cards</li> <li>"Negative value" assets — loans, burdens and other responsibilities</li> </ul> <p>In general, all houses are distinct and no two kittens are alike. NFTs are <em>distinguishable</em> and you must track the ownership of each one separately.</p> <h2 id="motivation">Motivation</h2> <p>A standard interface allows wallet/broker/auction applications to work with any NFT on Ethereum. We provide for simple ERC-721 smart contracts as well as contracts that track an <em>arbitrarily large</em> number of NFTs. Additional applications are discussed below.</p> <p>This standard is inspired by the ERC-20 token standard and builds on two years of experience since EIP-20 was created. EIP-20 is insufficient for tracking NFTs because each asset is distinct (non-fungible) whereas each of a quantity of tokens is identical (fungible).</p> <p>Differences between this standard and EIP-20 are examined below.</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-721 compliant contract must implement the <code>ERC721</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.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"> @title</span><span class="z-comment"> ERC-721 Non-Fungible Token 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-721</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 0x80ac58cd.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC721</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 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 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"> _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"> @dev</span><span class="z-comment"> This emits when the approved address for an NFT is </span><span class="z-keyword">changed</span><span class="z-comment"> or</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> reaffirmed. The zero address indicates there is no approved address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> When a Transfer event emits, this also indicates that the approved</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 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"> 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-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 class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when an operator is enabled or disabled for an owner.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The operator can manage all NFTs of the owner.</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> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Count all NFTs assigned to an owner</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 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"> _owner</span><span class="z-comment"> An 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"> The</span><span class="z-comment"> number of NFTs owned by `_owner`, possibly zero</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"> 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"> 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 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"> _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 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 class="z-storage z-type"> @notice</span><span class="z-comment"> Transfers the ownership of an NFT from one 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 unless `msg.sender` is the current owner, an authorized</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> operator, or the approved address for this NFT. Throws if `_from` is</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> not the current owner. Throws if `_to` is the zero address. Throws if</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `_tokenId` is not a valid NFT. When transfer is complete, this function</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> checks if `_to` is a smart contract (code size &gt; 0). If so, it calls</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `onERC721Received` on `_to` and throws if the return value is not</span></span> <span class="giallo-l"><span class="z-comment"> ///</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 class="z-storage z-type"> @param</span><span class="z-variable z-other"> _from</span><span class="z-comment"> The current owner 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"> _to</span><span class="z-comment"> The new 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"> The NFT 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"> data</span><span class="z-comment"> Additional data with no specified format, sent in call to `_to`</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 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"> _tokenId</span><span>,</span><span class="z-support"> bytes</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>;</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"> Transfers the ownership of an NFT from one 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"> This works identically to the other function with an extra data parameter,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> except this function just sets data to &quot;&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"> _from</span><span class="z-comment"> The current owner 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"> _to</span><span class="z-comment"> The new 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"> The NFT to transfer</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 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"> _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"> Transfer ownership of an NFT -- THE CALLER IS RESPONSIBLE</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> TO CONFIRM THAT `_to` IS CAPABLE OF RECEIVING NFTS OR ELSE</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> THEY MAY BE PERMANENTLY LOST</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 `msg.sender` is the current owner, an authorized</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> operator, or the approved address for this NFT. Throws if `_from` is</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> not the current owner. Throws if `_to` is the zero address. Throws if</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `_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"> _from</span><span class="z-comment"> The current owner 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"> _to</span><span class="z-comment"> The new 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"> The NFT to transfer</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"> _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"> Change or reaffirm the approved address for 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 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 current NFT owner, or an authorized</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> operator of the current 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"> _approved</span><span class="z-comment"> The new approved NFT controller</span></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 approve</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"> _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> <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 manage</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> all of `msg.sender`&#39;s assets</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"> multiple 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"> setApprovalForAll</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 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 a single 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 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 NFT, or the zero address if there is none</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 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 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"> _owner</span><span class="z-comment"> The address that owns the NFTs</span></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 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"> True</span><span class="z-comment"> if `_operator` is an approved operator for `_owner`, false otherwise</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 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></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>A wallet/broker/auction application MUST implement the <strong>wallet interface</strong> if it will accept safe transfers.</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-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0x150b7a02.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC721TokenReceiver</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 the receipt 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 ERC721 smart contract calls this function on the recipient</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> after a `transfer`. This function MAY throw to revert and reject the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> transfer. Return of other than the magic value MUST result in the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> transaction being reverted.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-keyword"> Note</span><span class="z-comment">: the contract address is always the message 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"> _operator</span><span class="z-comment"> The address which called `safeTransferFrom` function</span></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 which previously owned 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"> _tokenId</span><span class="z-comment"> The NFT identifier which is being transferred</span></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-comment"> ///</span><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 class="z-comment"> unless throwing</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-variable z-parameter z-function"> _data</span><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> <p>The <strong>metadata extension</strong> is OPTIONAL for ERC-721 smart contracts (see "caveats", below). This allows your smart contract to be interrogated for its name and for details about the assets which your NFTs 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-721 Non-Fungible 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://eips.ethereum.org/EIPS/eip-721</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 0x5b5e139f.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC721Metadata</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC721 </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 NFTs 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 NFTs 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 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 given asset.</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. URIs are defined in RFC</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> 3986. The URI may point to a JSON file that conforms to the &quot;ERC721</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Metadata JSON Schema&quot;.</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 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">string</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This is the "ERC721 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">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 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>The <strong>enumeration extension</strong> is OPTIONAL for ERC-721 smart contracts (see "caveats", below). This allows your contract to publish its full list of NFTs and make them discoverable.</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 Non-Fungible Token Standard, optional enumeration 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 class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0x780e9d63.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC721Enumerable</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC721 </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"> Count NFTs tracked by this 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"> A</span><span class="z-comment"> count of valid NFTs tracked by this contract, where each one of</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> them has an assigned and queryable owner not equal to the zero address</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"> 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"> Enumerate valid NFTs</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 `_index` &gt;= `totalSupply()`.</span></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"> A counter less than `totalSupply()`</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 for the `_index`th NFT,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (sort order not specified)</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 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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Enumerate NFTs assigned to an 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 `_index` &gt;= `balanceOf(_owner)` or if</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `_owner` is the zero address, representing invalid NFTs.</span></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"> An address where we are interested in NFTs owned by them</span></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"> A counter less than `balanceOf(_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"> token identifier for the `_index`th NFT assigned to `_owner`,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (sort order not specified)</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 z-parameter z-function"> _owner</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><h3 id="caveats">Caveats</h3> <p>The 0.4.20 Solidity interface grammar is not expressive enough to document the ERC-721 standard. A contract which complies with ERC-721 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 nonpayable (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.20 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>ERC721Metadata</code> or <code>ERC721Enumerable</code> SHALL also implement <code>ERC721</code>. ERC-721 implements the requirements of interface ERC-165.</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.20, 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 proposed uses of Ethereum smart contracts that depend on tracking distinguishable assets. Examples of existing or planned NFTs are LAND in Decentraland, the eponymous punks in CryptoPunks, and in-game items using systems like DMarket or EnjinCoin. Future uses include tracking real-world assets, like real-estate (as envisioned by companies like Ubitquity or Propy). It is critical in each of these cases that these items are not "lumped together" as numbers in a ledger, but instead each asset must have its ownership individually and atomically tracked. Regardless of the nature of these assets, the ecosystem will be stronger if we have a standardized interface that allows for cross-functional asset management and sales platforms.</p> <p><strong>"NFT" Word Choice</strong></p> <p>"NFT" was satisfactory to nearly everyone surveyed and is widely applicable to a broad universe of distinguishable digital assets. We recognize that "deed" is very descriptive for certain applications of this standard (notably, physical property).</p> <p><em>Alternatives considered: distinguishable asset, title, token, asset, equity, ticket</em></p> <p><strong>NFT Identifiers</strong></p> <p>Every NFT is identified by a unique <code>uint256</code> ID inside the ERC-721 smart contract. This identifying number SHALL NOT change for the life of the contract. The pair <code>(contract address, uint256 tokenId)</code> will then be a globally unique and fully-qualified identifier for a specific asset on an Ethereum chain. While some ERC-721 smart contracts may find it convenient to start with ID 0 and simply increment by one for each new NFT, callers SHALL NOT assume that ID numbers have any specific pattern to them, and MUST treat the ID as a "black box". Also note that NFTs MAY become invalid (be destroyed). Please see the enumeration functions for a supported enumeration interface.</p> <p>The choice of <code>uint256</code> allows a wide variety of applications because UUIDs and sha3 hashes are directly convertible to <code>uint256</code>.</p> <p><strong>Transfer Mechanism</strong></p> <p>ERC-721 standardizes a safe transfer function <code>safeTransferFrom</code> (overloaded with and without a <code>bytes</code> parameter) and an unsafe function <code>transferFrom</code>. Transfers may be initiated by:</p> <ul> <li>The owner of an NFT</li> <li>The approved address of an NFT</li> <li>An authorized operator of the current owner of an NFT</li> </ul> <p>Additionally, an authorized operator may set the approved address for an NFT. This provides a powerful set of tools for wallet, broker and auction applications to quickly use a <em>large</em> number of NFTs.</p> <p>The transfer and accept 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 transfers if the contract is paused</strong> — prior art, CryptoKitties deployed contract, line 611</li> <li><strong>Blocklist certain address from receiving NFTs</strong> — prior art, CryptoKitties deployed contract, lines 565, 566</li> <li><strong>Disallow unsafe transfers</strong> — <code>transferFrom</code> throws unless <code>_to</code> equals <code>msg.sender</code> or <code>countOf(_to)</code> is non-zero or was non-zero previously (because such cases are safe)</li> <li><strong>Charge a fee to both parties of a transaction</strong> — require payment when calling <code>approve</code> with a non-zero <code>_approved</code> if it was previously the zero address, refund payment if calling <code>approve</code> with the zero address if it was previously a non-zero address, require payment when calling any transfer function, require transfer parameter <code>_to</code> to equal <code>msg.sender</code>, require transfer parameter <code>_to</code> to be the approved address for the NFT</li> <li><strong>Read only NFT registry</strong> — always throw from <code>safeTransferFrom</code>, <code>transferFrom</code>, <code>approve</code> and <code>setApprovalForAll</code></li> </ul> <p>Failed transactions will throw, a best practice identified in ERC-223, ERC-677, ERC-827 and OpenZeppelin's implementation of SafeERC20.sol. ERC-20 defined an <code>allowance</code> feature, this caused a problem when called and then later modified to a different amount, as on OpenZeppelin issue #438. In ERC-721, there is no allowance because every NFT is unique, the quantity is none or one. Therefore we receive the benefits of ERC-20's original design without problems that have been later discovered.</p> <p>Creation of NFTs ("minting") and destruction of NFTs ("burning") is not included in the specification. Your contract may implement these by other means. Please see the <code>event</code> documentation for your responsibilities when creating or destroying NFTs.</p> <p>We questioned if the <code>operator</code> parameter on <code>onERC721Received</code> was necessary. In all cases we could imagine, if the operator was important then that operator could transfer the token to themself and then send it -- then they would be the <code>from</code> address. This seems contrived because we consider the operator to be a temporary owner of the token (and transferring to themself is redundant). When the operator sends the token, it is the operator acting on their own accord, NOT the operator acting on behalf of the token holder. This is why the operator and the previous token owner are both significant to the token recipient.</p> <p><em>Alternatives considered: only allow two-step ERC-20 style transaction, require that transfer functions never throw, require all functions to return a boolean indicating the success of the operation.</em></p> <p><strong>ERC-165 Interface</strong></p> <p>We chose Standard Interface Detection (ERC-165) to expose the interfaces that a ERC-721 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-721 implementation to implement <code>ERC721Enumerable</code>, <code>ERC721Metadata</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 NFTs. If your application is able to grow then avoid using for/while loops in your code (see CryptoKitties bounty issue #4). These indicate your contract may be unable to scale and gas costs will rise over time without bound.</p> <p>We have deployed a contract, XXXXERC721, to Testnet which instantiates and tracks 340282366920938463463374607431768211456 different deeds (2^128). That's enough to assign every IPV6 address to an Ethereum account owner, or to track ownership of nanobots a few micron in size and in aggregate totalling half the size of Earth. You can query it from the blockchain. And every function takes less gas than querying the ENS.</p> <p>This illustration makes clear: the ERC-721 standard scales.</p> <p><em>Alternatives considered: remove the asset enumeration function if it requires a for-loop, return a Solidity array type from enumeration functions.</em></p> <p><strong>Privacy</strong></p> <p>Wallets/brokers/auctioneers identified in the motivation section have a strong need to identify which NFTs an owner owns.</p> <p>It may be interesting to consider a use case where NFTs are not enumerable, such as a private registry of property ownership, or a partially-private registry. However, privacy cannot be attained because an attacker can simply (!) call <code>ownerOf</code> for every possible <code>tokenId</code>.</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-721 smart contracts are well-known (canonical) is outside the scope of this standard.</p> <p>A mechanism is provided to associate NFTs with URIs. We expect that many implementations will take advantage of this to provide metadata for each NFT. The image size recommendation is taken from Instagram, they probably know much about image usability. The URI MAY be mutable (i.e. it changes from time to time). We considered an NFT representing ownership of a house, in this case metadata about the house (image, occupants, etc.) 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>A significant amount of discussion occurred on the original ERC-721 issue, additionally we held a first live meeting on Gitter that had good representation and well advertised (on Reddit, in the Gitter #ERC channel, and the original ERC-721 issue). Thank you to the participants:</p> <ul> <li><a rel="external" href="https://github.com/imallinnow">@ImAllInNow</a> Rob from DEC Gaming / Presenting Michigan Ethereum Meetup Feb 7</li> <li><a rel="external" href="https://github.com/arachnid">@Arachnid</a> Nick Johnson</li> <li><a rel="external" href="https://github.com/jadhavajay">@jadhavajay</a> Ajay Jadhav from AyanWorks</li> <li><a rel="external" href="https://github.com/superphly">@superphly</a> Cody Marx Bailey - XRAM Capital / Sharing at hackathon Jan 20 / UN Future of Finance Hackathon.</li> <li><a rel="external" href="https://github.com/fulldecent">@fulldecent</a> William Entriken</li> </ul> <p>A second event was held at ETHDenver 2018 to discuss distinguishable asset standards (notes to be published).</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>balanceOf</code>, <code>totalSupply</code>, <code>name</code> and <code>symbol</code> semantics from the ERC-20 specification. An implementation may also include a function <code>decimals</code> that returns <code>uint8(0)</code> if its goal is to be more compatible with ERC-20 while supporting this standard. However, we find it contrived to require all ERC-721 implementations to support the <code>decimals</code> function.</p> <p>Example NFT implementations as of February 2018:</p> <ul> <li>CryptoKitties -- Compatible with an earlier version of this standard.</li> <li>CryptoPunks -- Partially ERC-20 compatible, but not easily generalizable because it includes auction functionality directly in the contract and uses function names that explicitly refer to the assets as "punks".</li> <li>Auctionhouse Asset Interface -- The author needed a generic interface for the Auctionhouse ÐApp (currently ice-boxed). His "Asset" contract is very simple, but is missing ERC-20 compatibility, <code>approve()</code> functionality, and metadata. This effort is referenced in the discussion for EIP-173.</li> </ul> <p>Note: "Limited edition, collectible tokens" like Curio Cards and Rare Pepe are <em>not</em> distinguishable assets. They're actually a collection of individual fungible tokens, each of which is tracked by its own smart contract with its own total supply (which may be <code>1</code> in extreme cases).</p> <p>The <code>onERC721Received</code> function specifically works around old deployed contracts which may inadvertently return 1 (<code>true</code>) in certain circumstances even if they don't implement a function (see Solidity DelegateCallReturnValue bug). By returning and checking for a magic value, we are able to distinguish actual affirmative responses versus these vacuous <code>true</code>s.</p> <h2 id="test-cases">Test Cases</h2> <p>0xcert ERC-721 Token includes test cases written using Truffle.</p> <h2 id="implementations">Implementations</h2> <p>0xcert ERC721 -- a reference implementation</p> <ul> <li>MIT licensed, so you can freely use it for your projects</li> <li>Includes test cases</li> <li>Active bug bounty, you will be paid if you find errors</li> </ul> <p>Su Squares -- an advertising platform where you can rent space and place images</p> <ul> <li>Complete the Su Squares Bug Bounty Program to seek problems with this standard or its implementation</li> <li>Implements the complete standard and all optional interfaces</li> </ul> <p>ERC721ExampleDeed -- an example implementation</p> <ul> <li>Implements using the OpenZeppelin project format</li> </ul> <p>XXXXERC721, by William Entriken -- a scalable example implementation</p> <ul> <li>Deployed on testnet with 1 billion assets and supporting all lookups with the metadata extension. This demonstrates that scaling is NOT a problem.</li> </ul> <h2 id="references">References</h2> <p><strong>Standards</strong></p> <ol> <li><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> Token Standard.</li> <li><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> Standard Interface Detection.</li> <li><a href="https://wg-eips.ritovision.com/173/">ERC-173</a> Owned Standard.</li> <li><a rel="external" href="https://github.com/ethereum/EIPs/issues/223">ERC-223</a> Token Standard.</li> <li><a rel="external" href="https://github.com/ethereum/EIPs/issues/677">ERC-677</a> <code>transferAndCall</code> Token Standard.</li> <li><a rel="external" href="https://github.com/ethereum/EIPs/issues/827">ERC-827</a> Token Standard.</li> <li>Ethereum Name Service (ENS). https://ens.domains</li> <li>Instagram -- What's the Image Resolution? https://help.instagram.com/1631821640426723</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-721 Issue. https://github.com/ethereum/eips/issues/721</li> <li>Solidity Issue #2330 -- Interface Functions are External. 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> <li>Solidity Issue #3494 -- Compiler Incorrectly Reasons About the <code>selector</code> Function. https://github.com/ethereum/solidity/issues/3494</li> <li>Solidity Issue #3544 -- Cannot Calculate Selector of Function Named <code>transfer</code>. https://github.com/ethereum/solidity/issues/3544</li> <li>CryptoKitties Bounty Issue #4 -- Listing all Kitties Owned by a User is <code>O(n^2)</code>. https://github.com/axiomzen/cryptokitties-bounty/issues/4</li> <li>OpenZeppelin Issue #438 -- Implementation of <code>approve</code> method violates ERC20 standard. https://github.com/OpenZeppelin/zeppelin-solidity/issues/438</li> <li>Solidity DelegateCallReturnValue Bug. https://solidity.readthedocs.io/en/develop/bugs.html#DelegateCallReturnValue</li> </ol> <p><strong>Discussions</strong></p> <ol> <li>Reddit (announcement of first live discussion). https://www.reddit.com/r/ethereum/comments/7r2ena/friday_119_live_discussion_on_erc_nonfungible/</li> <li>Gitter #EIPs (announcement of first live discussion). https://gitter.im/ethereum/EIPs?at=5a5f823fb48e8c3566f0a5e7</li> <li>ERC-721 (announcement of first live discussion). https://github.com/ethereum/eips/issues/721#issuecomment-358369377</li> <li>ETHDenver 2018. https://ethdenver.com</li> </ol> <p><strong>NFT Implementations and Other Projects</strong></p> <ol> <li>CryptoKitties. https://www.cryptokitties.co</li> <li>0xcert ERC-721 Token. https://github.com/0xcert/ethereum-erc721</li> <li>Su Squares. https://tenthousandsu.com</li> <li>Decentraland. https://decentraland.org</li> <li>CryptoPunks. https://www.larvalabs.com/cryptopunks</li> <li>DMarket. https://www.dmarket.io</li> <li>Enjin Coin. https://enjincoin.io</li> <li>Ubitquity. https://www.ubitquity.io</li> <li>Propy. https://tokensale.propy.com</li> <li>CryptoKitties Deployed Contract. https://etherscan.io/address/0x06012c8cf97bead5deae237070f9587f8e7a266d#code</li> <li>Su Squares Bug Bounty Program. https://github.com/fulldecent/su-squares-bounty</li> <li>XXXXERC721. https://github.com/fulldecent/erc721-example</li> <li>ERC721ExampleDeed. https://github.com/nastassiasachs/ERC721ExampleDeed</li> <li>Curio Cards. https://mycuriocards.com</li> <li>Rare Pepe. https://rarepepewallet.com</li> <li>Auctionhouse Asset Interface. https://github.com/dob/auctionhouse/blob/master/contracts/Asset.sol</li> <li><a href="https://wg-eips.ritovision.com/721/./assets/SafeERC20.sol">OpenZeppelin <code>SafeERC20.sol</code> Implementation</a>.</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-01-23T00:00:00+00:00 2026-02-11T14:48:25+00:00 Christian Reitwießnerchris@ethereum.org Nick Johnsonnick@ethereum.org Fabian Vogelstellerfabian@lukso.network Jordi Baylinajordi@baylina.cat Konrad Feldmeierkonrad.feldmeier@brainbot.com William Entrikengithub.com@phor.net https://wg-eips.ritovision.com/165/ <h2 id="simple-summary">Simple Summary</h2> <p>Creates a standard method to publish and detect what interfaces a smart contract implements.</p> <h2 id="abstract">Abstract</h2> <p>Herein, we standardize the following:</p> <ol> <li>How interfaces are identified</li> <li>How a contract will publish the interfaces it implements</li> <li>How to detect if a contract implements ERC-165</li> <li>How to detect if a contract implements any given interface</li> </ol> <h2 id="motivation">Motivation</h2> <p>For some "standard interfaces" like <a href="https://wg-eips.ritovision.com/20/">the ERC-20 token interface</a>, it is sometimes useful to query whether a contract supports the interface and if yes, which version of the interface, in order to adapt the way in which the contract is to be interacted with. Specifically for ERC-20, a version identifier has already been proposed. This proposal standardizes the concept of interfaces and standardizes the identification (naming) of interfaces.</p> <h2 id="specification">Specification</h2> <h3 id="how-interfaces-are-identified">How Interfaces are Identified</h3> <p>For this standard, an <em>interface</em> is a set of <a rel="external" href="https://solidity.readthedocs.io/en/develop/abi-spec.html#function-selector">function selectors as defined by the Ethereum ABI</a>. This a subset of <a rel="external" href="https://solidity.readthedocs.io/en/develop/abi-spec.html">Solidity's concept of interfaces</a> and the <code>interface</code> keyword definition which also defines return types, mutability and events.</p> <p>We define the interface identifier as the XOR of all function selectors in the interface. This code example shows how to calculate an interface identifier:</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-storage z-type">interface</span><span class="z-entity z-name"> Solidity101</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hello</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> world</span><span>(</span><span class="z-support">int</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</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"> Selector</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> calculateSelector</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> Solidity101 i</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> i</span><span>.</span><span>hello</span><span>.</span><span>selector </span><span class="z-keyword">^</span><span> i</span><span>.</span><span>world</span><span>.</span><span>selector</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Note: interfaces do not permit optional functions, therefore, the interface identity will not include them.</p> <h3 id="how-a-contract-will-publish-the-interfaces-it-implements">How a Contract will Publish the Interfaces it Implements</h3> <p>A contract that is compliant with ERC-165 shall implement the following interface (referred as <code>ERC165.sol</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-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 interface identifier for this interface is <code>0x01ffc9a7</code>. You can calculate this by running <code>bytes4(keccak256('supportsInterface(bytes4)'));</code> or using the <code>Selector</code> contract above.</p> <p>Therefore the implementing contract will have a <code>supportsInterface</code> function that returns:</p> <ul> <li><code>true</code> when <code>interfaceID</code> is <code>0x01ffc9a7</code> (EIP165 interface)</li> <li><code>false</code> when <code>interfaceID</code> is <code>0xffffffff</code></li> <li><code>true</code> for any other <code>interfaceID</code> this contract implements</li> <li><code>false</code> for any other <code>interfaceID</code></li> </ul> <p>This function must return a bool and use at most 30,000 gas.</p> <p>Implementation note, there are several logical ways to implement this function. Please see the example implementations and the discussion on gas usage.</p> <h3 id="how-to-detect-if-a-contract-implements-erc-165">How to Detect if a Contract Implements ERC-165</h3> <ol> <li>The source contract makes a <code>STATICCALL</code> to the destination address with input data: <code>0x01ffc9a701ffc9a700000000000000000000000000000000000000000000000000000000</code> and gas 30,000. This corresponds to <code>contract.supportsInterface(0x01ffc9a7)</code>.</li> <li>If the call fails or return false, the destination contract does not implement ERC-165.</li> <li>If the call returns true, a second call is made with input data <code>0x01ffc9a7ffffffff00000000000000000000000000000000000000000000000000000000</code>.</li> <li>If the second call fails or returns true, the destination contract does not implement ERC-165.</li> <li>Otherwise it implements ERC-165.</li> </ol> <h3 id="how-to-detect-if-a-contract-implements-any-given-interface">How to Detect if a Contract Implements any Given Interface</h3> <ol> <li>If you are not sure if the contract implements ERC-165, use the above procedure to confirm.</li> <li>If it does not implement ERC-165, then you will have to see what methods it uses the old-fashioned way.</li> <li>If it implements ERC-165 then just call <code>supportsInterface(interfaceID)</code> to determine if it implements an interface you can use.</li> </ol> <h2 id="rationale">Rationale</h2> <p>We tried to keep this specification as simple as possible. This implementation is also compatible with the current Solidity version.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The mechanism described above (with <code>0xffffffff</code>) should work with most of the contracts previous to this standard to determine that they do not implement ERC-165.</p> <p>Also <a href="https://wg-eips.ritovision.com/137/">the ENS</a> already implements this EIP.</p> <h2 id="test-cases">Test Cases</h2> <p>Following is a contract that detects which interfaces other contracts implement. From @fulldecent and @jbaylina.</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-storage z-type">contract</span><span class="z-entity z-name"> ERC165Query</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> constant</span><span> InvalidID </span><span class="z-keyword">=</span><span class="z-constant"> 0xffffffff</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> constant</span><span> ERC165ID </span><span class="z-keyword">=</span><span class="z-constant"> 0x01ffc9a7</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"> doesContractImplementInterface</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</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 class="z-support"> uint256</span><span> success</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> result</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> (</span><span>success</span><span>,</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> noThrowCall</span><span>(</span><span>_contract</span><span>,</span><span> ERC165ID</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>(</span><span>success</span><span class="z-keyword">==</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">||</span><span>(</span><span>result</span><span class="z-keyword">==</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-constant"> false</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> (</span><span>success</span><span>,</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> noThrowCall</span><span>(</span><span>_contract</span><span>,</span><span> InvalidID</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>(</span><span>success</span><span class="z-keyword">==</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">||</span><span>(</span><span>result</span><span class="z-keyword">!=</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-constant"> false</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> (</span><span>success</span><span>,</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> noThrowCall</span><span>(</span><span>_contract</span><span>,</span><span> _interfaceId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>(</span><span>success</span><span class="z-keyword">==</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span>result</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-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-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-storage z-type"> function</span><span class="z-entity z-name"> noThrowCall</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable z-parameter z-function"> _interfaceId</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> success</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> result</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span> erc165ID </span><span class="z-keyword">=</span><span> ERC165ID</span><span>;</span></span> <span class="giallo-l"></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> x </span><span class="z-keyword">:=</span><span class="z-entity z-name"> mload</span><span>(</span><span class="z-constant">0x40</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Find empty storage location using &quot;free memory pointer&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span>x</span><span>,</span><span> erc165ID</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Place signature at beginning of empty storage</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>x</span><span>,</span><span class="z-constant"> 0x04</span><span>)</span><span>,</span><span> _interfaceId</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Place first argument directly next to signature</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> success </span><span class="z-keyword">:=</span><span class="z-entity z-name"> staticcall</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> 30000</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> 30k gas</span></span> <span class="giallo-l"><span> _contract</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> To addr</span></span> <span class="giallo-l"><span> x</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Inputs are stored at location x</span></span> <span class="giallo-l"><span class="z-constant"> 0x24</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Inputs are 36 bytes long</span></span> <span class="giallo-l"><span> x</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Store output over input (saves space)</span></span> <span class="giallo-l"><span class="z-constant"> 0x20</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Outputs are 32 bytes long</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> result </span><span class="z-keyword">:=</span><span class="z-entity z-name"> mload</span><span>(</span><span>x</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Load the result</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="implementation">Implementation</h2> <p>This approach uses a <code>view</code> function implementation of <code>supportsInterface</code>. The execution cost is 586 gas for any input. But contract initialization requires storing each interface (<code>SSTORE</code> is 20,000 gas). The <code>ERC165MappingImplementation</code> contract is generic and reusable.</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;./ERC165.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"> ERC165MappingImplementation</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"> @dev</span><span class="z-comment"> You must not set element 0xffffffff to true</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes4</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bool</span><span>)</span><span class="z-storage z-type"> internal</span><span> supportedInterfaces</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"> ERC165MappingImplementation</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span> supportedInterfaces</span><span>[</span><span class="z-variable z-language">this</span><span>.</span><span>supportsInterface</span><span>.</span><span>selector</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 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> supportedInterfaces</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> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> Simpson</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> is2D</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 class="z-storage z-type"> function</span><span class="z-entity z-name"> skinColor</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">string</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"> Lisa</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC165MappingImplementation</span><span>, </span><span class="z-entity z-name">Simpson</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> Lisa</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> supportedInterfaces</span><span>[</span><span class="z-variable z-language">this</span><span>.</span><span>is2D</span><span>.</span><span>selector </span><span class="z-keyword">^</span><span class="z-variable z-language"> this</span><span>.</span><span>skinColor</span><span>.</span><span>selector</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 class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> is2D</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></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> skinColor</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">string</span><span>)</span><span>{</span><span>}</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Following is a <code>pure</code> function implementation of <code>supportsInterface</code>. The worst-case execution cost is 236 gas, but increases linearly with a higher number of supported interfaces.</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;./ERC165.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"> Simpson</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> is2D</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 class="z-storage z-type"> function</span><span class="z-entity z-name"> skinColor</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">string</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"> Homer</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC165</span><span>, </span><span class="z-entity z-name">Simpson</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 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>is2D</span><span>.</span><span>selector</span></span> <span class="giallo-l"><span class="z-keyword"> ^</span><span class="z-variable z-language"> this</span><span>.</span><span>skinColor</span><span>.</span><span>selector</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Simpson</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"> is2D</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></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> skinColor</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">string</span><span>)</span><span>{</span><span>}</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>With three or more supported interfaces (including ERC165 itself as a required supported interface), the mapping approach (in every case) costs less gas than the pure approach (at worst case).</p> <h2 id="version-history">Version history</h2> <ul> <li> <p>PR 1640, finalized 2019-01-23 -- This corrects the noThrowCall test case to use 36 bytes rather than the previous 32 bytes. The previous code was an error that still silently worked in Solidity 0.4.x but which was broken by new behavior introduced in Solidity 0.5.0. This change was discussed at <a rel="external" href="https://github.com/ethereum/EIPs/pull/1640">#1640</a>.</p> </li> <li> <p>EIP 165, finalized 2018-04-20 -- Original published version.</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-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> 2018-01-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jordi Baylinajordi@baylina.cat Jacques Dafflonjacques@dafflon.tech https://wg-eips.ritovision.com/820/ <blockquote> <p>:information_source: <strong><a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> has superseded <a href="https://wg-eips.ritovision.com/820/">ERC-820</a>.</strong> :information_source:<br /> <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> fixes the incompatibility in the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> logic which was introduced by the Solidty 0.5 update.<br /> Have a look at the <a rel="external" href="https://github.com/ethereum/EIPs/issues/820#issuecomment-464109166">official announcement</a>, and the comments about the <a rel="external" href="https://github.com/ethereum/EIPs/issues/820#issuecomment-452465748">bug</a> and the <a rel="external" href="https://github.com/ethereum/EIPs/issues/820#issuecomment-454021564">fix</a>.<br /> Apart from this fix, <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> is functionally equivalent to <a href="https://wg-eips.ritovision.com/820/">ERC-820</a>.</p> <p>:warning: <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> MUST be used in lieu of <a href="https://wg-eips.ritovision.com/820/">ERC-820</a>. :warning:</p> </blockquote> <h2 id="simple-summary">Simple Summary</h2> <p>This standard defines a universal registry smart contract where any address (contract or regular account) can register which interface it supports and which smart contract is responsible for its implementation.</p> <p>This standard keeps backward compatibility with <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>.</p> <h2 id="abstract">Abstract</h2> <p>This standard defines a registry where smart contracts and regular accounts can publish which functionalities they implement---either directly or through a proxy contract.</p> <p>Anyone can query this registry to ask if a specific address implements a given interface and which smart contract handles its implementation.</p> <p>This registry MAY be deployed on any chain and shares the same address on all chains.</p> <p>Interfaces with zeroes (<code>0</code>) as the last 28 bytes are considered <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interfaces, and this registry SHALL forward the call to the contract to see if it implements the interface.</p> <p>This contract also acts as an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> cache to reduce gas consumption.</p> <h2 id="motivation">Motivation</h2> <p>There have been different approaches to define pseudo-introspection in Ethereum. The first is <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> which has the limitation that it cannot be used by regular accounts. The second attempt is <a rel="external" href="https://github.com/ethereum/EIPs/issues/672">ERC-672</a> which uses reverse <a rel="external" href="https://ens.domains/">ENS</a>. Using reverse <a rel="external" href="https://ens.domains/">ENS</a> has two issues. First, it is unnecessarily complicated, and second, <a rel="external" href="https://ens.domains/">ENS</a> is still a centralized contract controlled by a multisig. This multisig theoretically would be able to modify the system.</p> <p>This standard is much simpler than <a rel="external" href="https://github.com/ethereum/EIPs/issues/672">ERC-672</a>, and it is <em>fully</em> decentralized.</p> <p>This standard also provides a <em>unique</em> address for all chains. Thus solving the problem of resolving the correct registry address for different chains.</p> <h2 id="specification">Specification</h2> <h3 id="erc-820-registry-smart-contract"><a href="https://wg-eips.ritovision.com/820/">ERC-820</a> Registry Smart Contract</h3> <blockquote> <p>This is an exact copy of the code of the <a rel="external" href="https://github.com/jbaylina/ERC820/blob/master/contracts/ERC820Registry.sol">ERC820 registry smart contract</a>.</p> </blockquote> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/*</span><span class="z-comment"> ERC820 Pseudo-introspection Registry Contract</span></span> <span class="giallo-l"><span class="z-comment"> * This standard defines a universal registry smart contract where any address</span></span> <span class="giallo-l"><span class="z-comment"> * (contract or regular account) can register which interface it supports and</span></span> <span class="giallo-l"><span class="z-comment"> * which smart contract is responsible for its implementation.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Written in 2018 by Jordi Baylina and Jacques Dafflon</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * To the extent possible under law, the author(s) have dedicated all copyright</span></span> <span class="giallo-l"><span class="z-comment"> * and related and neighboring rights to this software to the public domain</span></span> <span class="giallo-l"><span class="z-comment"> * worldwide. This software is distributed without any warranty.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * You should have received a copy of the CC0 Public Domain Dedication along</span></span> <span class="giallo-l"><span class="z-comment"> * with this software. If not, see</span></span> <span class="giallo-l"><span class="z-comment"> * &lt;https://creativecommons.org/publicdomain/zero/1.0/&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-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-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-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-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-comment"> */</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.4.24</span><span>;</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> IV is value needed to have a vanity address starting with `0x820`.</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> IV: 9513</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 interface a contract MUST implement if it is the implementer of</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> some (other) interface for any address other than itself.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC820ImplementerInterface</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"> Indicates whether the contract implements the interface `interfaceHash` for the address `addr` or not.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> interfaceHash</span><span class="z-comment"> keccak256 hash of the name of the 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"> addr</span><span class="z-comment"> Address for which the contract will implement the interface</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"> ERC820_ACCEPT_MAGIC</span><span class="z-comment"> only if the contract implements `interfaceHash` for the address `addr`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canImplementInterfaceForAddress</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> interfaceHash</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-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> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC820 Pseudo-introspection Registry Contract</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @author</span><span class="z-comment"> Jordi Baylina and Jacques Dafflon</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> This contract is the official implementation of the ERC820 Registry.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> For more details, see https://eips.ethereum.org/EIPS/eip-820</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC820Registry</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"> ERC165 Invalid ID.</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> constant</span><span> INVALID_ID </span><span class="z-keyword">=</span><span class="z-constant"> 0xffffffff</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"> Method ID for the ERC165 supportsInterface method (= `bytes4(keccak256(&#39;supportsInterface(bytes4)&#39;))`).</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> constant</span><span> ERC165ID </span><span class="z-keyword">=</span><span class="z-constant"> 0x01ffc9a7</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"> Magic value which is returned if a contract implements an interface on behalf of some other address.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span> ERC820_ACCEPT_MAGIC </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;ERC820_ACCEPT_MAGIC&quot;</span><span>)</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">address</span><span class="z-keyword"> =&gt;</span><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"> address</span><span>)</span><span>)</span><span> interfaces</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> managers</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-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes4</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bool</span><span>)</span><span>)</span><span> erc165Cached</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"> Indicates a contract is the `implementer` of `interfaceHash` for `addr`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> InterfaceImplementerSet</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> addr</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> interfaceHash</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> implementer</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"> Indicates `newManager` is the address of the new manager for `addr`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ManagerChanged</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> addr</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> newManager</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 implements an interface and through which 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"> _addr</span><span class="z-comment"> Address being queried for the implementer of an interface.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (If `_addr == 0` then `msg.sender` is assumed.)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _interfaceHash</span><span class="z-comment"> keccak256 hash of the name of the interface as a string.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> E.g., `web3.utils.keccak256(&#39;ERC777Token&#39;)`.</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 contract which implements the interface `_interfaceHash` for `_addr`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> or `0x0` if `_addr` did not register an implementer for this interface.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getInterfaceImplementer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addr</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _interfaceHash</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-support"> address</span><span> addr </span><span class="z-keyword">=</span><span> _addr </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span class="z-keyword"> ?</span><span class="z-variable z-language"> msg.sender</span><span class="z-keyword"> :</span><span> _addr</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-entity z-name">isERC165Interface</span><span>(</span><span>_interfaceHash</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span> erc165InterfaceHash </span><span class="z-keyword">=</span><span class="z-support"> bytes4</span><span>(</span><span>_interfaceHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> implementsERC165Interface</span><span>(</span><span>addr</span><span>,</span><span> erc165InterfaceHash</span><span>)</span><span class="z-keyword"> ?</span><span> addr </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-keyword"> return</span><span> interfaces</span><span>[</span><span>addr</span><span>]</span><span>[</span><span>_interfaceHash</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"> @notice</span><span class="z-comment"> Sets the contract which implements a specific interface for an address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Only the manager defined for that address can set it.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (Each address is the manager for itself until it sets a new manager.)</span></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"> Address to define the interface for. (If `_addr == 0` then `msg.sender` is assumed.)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _interfaceHash</span><span class="z-comment"> keccak256 hash of the name of the interface as a string.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> For example, `web3.utils.keccak256(&#39;ERC777TokensRecipient&#39;)` for the `ERC777TokensRecipient` 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"> _implementer</span><span class="z-comment"> Contract address implementing _interfaceHash for _addr.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setInterfaceImplementer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addr</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _interfaceHash</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _implementer</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> addr </span><span class="z-keyword">=</span><span> _addr </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span class="z-keyword"> ?</span><span class="z-variable z-language"> msg.sender</span><span class="z-keyword"> :</span><span> _addr</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">getManager</span><span>(</span><span>addr</span><span>)</span><span class="z-keyword"> ==</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span class="z-string"> &quot;Not the manager&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-keyword">!</span><span class="z-entity z-name">isERC165Interface</span><span>(</span><span>_interfaceHash</span><span>)</span><span>,</span><span class="z-string"> &quot;Must not be a ERC165 hash&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_implementer </span><span class="z-keyword">!=</span><span class="z-constant"> 0</span><span class="z-keyword"> &amp;&amp;</span><span> _implementer </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-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC820ImplementerInterface</span><span>(</span><span>_implementer</span><span>)</span></span> <span class="giallo-l"><span> .</span><span class="z-entity z-name">canImplementInterfaceForAddress</span><span>(</span><span>_interfaceHash</span><span>,</span><span> addr</span><span>)</span><span class="z-keyword"> ==</span><span> ERC820_ACCEPT_MAGIC</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Does not implement the interface&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> interfaces</span><span>[</span><span>addr</span><span>]</span><span>[</span><span>_interfaceHash</span><span>]</span><span class="z-keyword"> =</span><span> _implementer</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> InterfaceImplementerSet</span><span>(</span><span>addr</span><span>,</span><span> _interfaceHash</span><span>,</span><span> _implementer</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"> @notice</span><span class="z-comment"> Sets the `_newManager` as manager for the `_addr` address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The new manager will be able to call `setInterfaceImplementer` for `_addr`.</span></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"> Address for which to set the new manager.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _newManager</span><span class="z-comment"> Address of the new manager for `addr`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setManager</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addr</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _newManager</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">getManager</span><span>(</span><span>_addr</span><span>)</span><span class="z-keyword"> ==</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span class="z-string"> &quot;Not the manager&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> managers</span><span>[</span><span>_addr</span><span>]</span><span class="z-keyword"> =</span><span> _newManager </span><span class="z-keyword">==</span><span> _addr </span><span class="z-keyword">?</span><span class="z-constant"> 0</span><span class="z-keyword"> :</span><span> _newManager</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ManagerChanged</span><span>(</span><span>_addr</span><span>,</span><span> _newManager</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"> @notice</span><span class="z-comment"> Get the manager of an 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"> _addr</span><span class="z-comment"> Address for which to return the manager.</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 manager for a given address.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getManager</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"> 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-comment"> //</span><span class="z-comment"> By default the manager of an address is the same address</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>managers</span><span>[</span><span>_addr</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> _addr</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> managers</span><span>[</span><span>_addr</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 class="z-storage z-type"> @notice</span><span class="z-comment"> Compute the keccak256 hash of an interface given its 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"> _interfaceName</span><span class="z-comment"> Name of the interface.</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"> keccak256 hash of an interface name.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> interfaceHash</span><span>(</span><span class="z-support">string</span><span class="z-variable z-parameter z-function"> _interfaceName</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 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>_interfaceName</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"> --- ERC165 Related Functions --- </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> --- Developed in collaboration with William Entriken. --- </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"> Updates the cache with whether the contract implements an ERC165 interface or not.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _contract</span><span class="z-comment"> Address of the contract for which to update the cache.</span></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"> ERC165 interface for which to update the cache.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateERC165Cache</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</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> {</span></span> <span class="giallo-l"><span> interfaces</span><span>[</span><span>_contract</span><span>]</span><span>[</span><span>_interfaceId</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> implementsERC165InterfaceNoCache</span><span>(</span><span>_contract</span><span>,</span><span> _interfaceId</span><span>)</span><span class="z-keyword"> ?</span><span> _contract </span><span class="z-keyword">:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span> erc165Cached</span><span>[</span><span>_contract</span><span>]</span><span>[</span><span>_interfaceId</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 class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Checks whether a contract implements an ERC165 interface or not.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The result may be cached, if not a direct lookup is 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"> _contract</span><span class="z-comment"> Address of the contract to check.</span></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"> ERC165 interface to check.</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 `_contract` implements `_interfaceId`, false otherwise.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> implementsERC165Interface</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</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"> 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"> if</span><span> (</span><span class="z-keyword">!</span><span>erc165Cached</span><span>[</span><span>_contract</span><span>]</span><span>[</span><span>_interfaceId</span><span>]</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> implementsERC165InterfaceNoCache</span><span>(</span><span>_contract</span><span>,</span><span> _interfaceId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> interfaces</span><span>[</span><span>_contract</span><span>]</span><span>[</span><span>_interfaceId</span><span>]</span><span class="z-keyword"> ==</span><span> _contract</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"> @notice</span><span class="z-comment"> Checks whether a contract implements an ERC165 interface or not without using nor updating the cache.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _contract</span><span class="z-comment"> Address of the contract to check.</span></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"> ERC165 interface to check.</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 `_contract` implements `_interfaceId`, false otherwise.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> implementsERC165InterfaceNoCache</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</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"> 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> success</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> result</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> (</span><span>success</span><span>,</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> noThrowCall</span><span>(</span><span>_contract</span><span>,</span><span> ERC165ID</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>success </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span class="z-keyword"> ||</span><span> result </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 class="giallo-l"></span> <span class="giallo-l"><span> (</span><span>success</span><span>,</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> noThrowCall</span><span>(</span><span>_contract</span><span>,</span><span> INVALID_ID</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>success </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span class="z-keyword"> ||</span><span> result </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 class="giallo-l"></span> <span class="giallo-l"><span> (</span><span>success</span><span>,</span><span> result</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> noThrowCall</span><span>(</span><span>_contract</span><span>,</span><span> _interfaceId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>success </span><span class="z-keyword">==</span><span class="z-constant"> 1</span><span class="z-keyword"> &amp;&amp;</span><span> result </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 class="z-constant"> true</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-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Checks whether the hash is a ERC165 interface (ending with 28 zeroes) or not.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _interfaceHash</span><span class="z-comment"> The hash to check.</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 hash is a ERC165 interface (ending with 28 zeroes), `false` otherwise.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isERC165Interface</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _interfaceHash</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>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _interfaceHash </span><span class="z-keyword">&amp;</span><span class="z-constant"> 0x00000000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF</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 class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Make a call on a contract without throwing if the function does not exist.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> noThrowCall</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable z-parameter z-function"> _interfaceId</span><span>)</span></span> <span class="giallo-l"><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">uint256</span><span class="z-variable"> success</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> result</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span> erc165ID </span><span class="z-keyword">=</span><span> ERC165ID</span><span>;</span></span> <span class="giallo-l"></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> x </span><span class="z-keyword">:=</span><span class="z-entity z-name"> mload</span><span>(</span><span class="z-constant">0x40</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Find empty storage location using &quot;free memory pointer&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span>x</span><span>,</span><span> erc165ID</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Place signature at beginning of empty storage</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>x</span><span>,</span><span class="z-constant"> 0x04</span><span>)</span><span>,</span><span> _interfaceId</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Place first argument directly next to signature</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> success </span><span class="z-keyword">:=</span><span class="z-entity z-name"> staticcall</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> 30000</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> 30k gas</span></span> <span class="giallo-l"><span> _contract</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> To addr</span></span> <span class="giallo-l"><span> x</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Inputs are stored at location x</span></span> <span class="giallo-l"><span class="z-constant"> 0x08</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Inputs are 8 bytes long</span></span> <span class="giallo-l"><span> x</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> Store output over input (saves space)</span></span> <span class="giallo-l"><span class="z-constant"> 0x20</span><span class="z-comment"> //</span><span class="z-comment"> Outputs are 32 bytes long</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> result </span><span class="z-keyword">:=</span><span class="z-entity z-name"> mload</span><span>(</span><span>x</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> Load the result</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="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>0xf90a2a8085174876e800830c35008080b909d7608060405234801561001057600080fd5b506109b7806100206000396000f30060806040526004361061008d5763ffffffff7c010000000000000000000000000000000000000000000000000000000060003504166329965a1d81146100925780633d584063146100bf5780635df8122f146100fc57806365ba36c114610123578063a41e7d5114610155578063aabbb8ca14610183578063b7056765146101a7578063f712f3e8146101e9575b600080fd5b34801561009e57600080fd5b506100bd600160a060020a036004358116906024359060443516610217565b005b3480156100cb57600080fd5b506100e0600160a060020a0360043516610512565b60408051600160a060020a039092168252519081900360200190f35b34801561010857600080fd5b506100bd600160a060020a036004358116906024351661055e565b34801561012f57600080fd5b506101436004803560248101910135610655565b60408051918252519081900360200190f35b34801561016157600080fd5b506100bd600160a060020a0360043516600160e060020a0319602435166106e3565b34801561018f57600080fd5b506100e0600160a060020a036004351660243561076d565b3480156101b357600080fd5b506101d5600160a060020a0360043516600160e060020a0319602435166107e7565b604080519115158252519081900360200190f35b3480156101f557600080fd5b506101d5600160a060020a0360043516600160e060020a03196024351661089c565b6000600160a060020a0384161561022e5783610230565b335b90503361023c82610512565b600160a060020a03161461029a576040805160e560020a62461bcd02815260206004820152600f60248201527f4e6f7420746865206d616e616765720000000000000000000000000000000000604482015290519081900360640190fd5b6102a38361091c565b156102f8576040805160e560020a62461bcd02815260206004820152601960248201527f4d757374206e6f74206265206120455243313635206861736800000000000000604482015290519081900360640190fd5b600160a060020a038216158015906103195750600160a060020a0382163314155b156104a15760405160200180807f4552433832305f4143434550545f4d414749430000000000000000000000000081525060130190506040516020818303038152906040526040518082805190602001908083835b6020831061038d5780518252601f19909201916020918201910161036e565b51815160209384036101000a6000190180199092169116179052604080519290940182900382207f249cb3fa000000000000000000000000000000000000000000000000000000008352600483018a9052600160a060020a0388811660248501529451909650938816945063249cb3fa936044808401945091929091908290030181600087803b15801561042057600080fd5b505af1158015610434573d6000803e3d6000fd5b505050506040513d602081101561044a57600080fd5b5051146104a1576040805160e560020a62461bcd02815260206004820181905260248201527f446f6573206e6f7420696d706c656d656e742074686520696e74657266616365604482015290519081900360640190fd5b600160a060020a03818116600081815260208181526040808320888452909152808220805473ffffffffffffffffffffffffffffffffffffffff19169487169485179055518692917f93baa6efbd2244243bfee6ce4cfdd1d04fc4c0e9a786abd3a41313bd352db15391a450505050565b600160a060020a03808216600090815260016020526040812054909116151561053c575080610559565b50600160a060020a03808216600090815260016020526040902054165b919050565b3361056883610512565b600160a060020a0316146105c6576040805160e560020a62461bcd02815260206004820152600f60248201527f4e6f7420746865206d616e616765720000000000000000000000000000000000604482015290519081900360640190fd5b81600160a060020a031681600160a060020a0316146105e557806105e8565b60005b600160a060020a03838116600081815260016020526040808220805473ffffffffffffffffffffffffffffffffffffffff19169585169590951790945592519184169290917f605c2dbf762e5f7d60a546d42e7205dcb1b011ebc62a61736a57c9089d3a43509190a35050565b60008282604051602001808383808284378201915050925050506040516020818303038152906040526040518082805190602001908083835b602083106106ad5780518252601f19909201916020918201910161068e565b6001836020036101000a038019825116818451168082178552505050505050905001915050604051809103902090505b92915050565b6106ed82826107e7565b6106f85760006106fa565b815b600160a060020a03928316600081815260208181526040808320600160e060020a031996909616808452958252808320805473ffffffffffffffffffffffffffffffffffffffff19169590971694909417909555908152600284528181209281529190925220805460ff19166001179055565b60008080600160a060020a038516156107865784610788565b335b91506107938461091c565b156107b85750826107a4828261089c565b6107af5760006107b1565b815b92506107df565b600160a060020a038083166000908152602081815260408083208884529091529020541692505b505092915050565b60008080610815857f01ffc9a70000000000000000000000000000000000000000000000000000000061093e565b9092509050811580610825575080155b1561083357600092506107df565b61084585600160e060020a031961093e565b909250905081158061085657508015155b1561086457600092506107df565b61086e858561093e565b90925090506001821480156108835750806001145b1561089157600192506107df565b506000949350505050565b600160a060020a0382166000908152600260209081526040808320600160e060020a03198516845290915281205460ff1615156108e4576108dd83836107e7565b90506106dd565b50600160a060020a03808316600081815260208181526040808320600160e060020a0319871684529091529020549091161492915050565b7bffffffffffffffffffffffffffffffffffffffffffffffffffffffff161590565b6040517f01ffc9a7000000000000000000000000000000000000000000000000000000008082526004820183905260009182919060208160088189617530fa9051909690955093505050505600a165627a7a723058204fc4461c9d5a247b0eafe0f9c508057bc0ad72bc24668cb2a35ea65850e10d3100291ba08208208208208208208208208208208208208208208208208208208208208200a00820820820820820820820820820820820820820820820820820820820820820</span></span></code></pre> <p>The strings of <code>820</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>Set the <code>v</code>, <code>r</code>, <code>s</code> of the transaction signature to the following values:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>v: 27</span></span> <span class="giallo-l"><span>r: 0x8208208208208208208208208208208208208208208208208208208208208200</span></span> <span class="giallo-l"><span>s: 0x0820820820820820820820820820820820820820820820820820820820820820</span></span></code></pre> <p>Those <code>r</code> and <code>s</code> values---made of a repeating pattern of <code>820</code>'s---are predictable "random numbers" generated deterministically by a human.</p> <blockquote> <p>The values of <code>r</code> and <code>s</code> must be 32 bytes long each---or 64 characters in hexadecimal. Since <code>820</code> is 3 characters long and 3 is not a divisor of 64, but it is a divisor of 63, the <code>r</code> and <code>s</code> values are padded with one extra character.<br /> The <code>s</code> value is prefixed with a single zero (<code>0</code>). The <code>0</code> prefix also guarantees that <code>s &lt; secp256k1n ÷ 2 + 1</code>.<br /> The <code>r</code> value, cannot be prefixed with a zero, as the transaction becomes invalid. Instead it is suffixed with a zero (<code>0</code>) which still respects the condition <code>s &lt; secp256k1n</code>.</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.08 ethers to this single-use deployment account.</p> </li> <li> <p>Broadcast the deployment transaction.</p> </li> </ol> <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-registry-deployment-account">Single-use Registry Deployment Account</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0xE6C244a1C10Aa0085b0cf92f04cdaD947C2988b8</span></span></code></pre> <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.08 ethers MUST be sent to this account <em>first</em>.</p> </blockquote> <h3 id="registry-contract-address">Registry Contract Address</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x820b586C8C28125366C998641B09DCbE7d4cBF06</span></span></code></pre> <p>The contract has the address above for every chain on which it is deployed.</p> <details> <summary>Raw metadata of <code>./contracts/ERC820Registry.sol</code></summary> <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">compiler</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">0.4.24+commit.e67f0147</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">language</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Solidity</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">output</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">abi</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">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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">_addr</span><span class="z-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">_interfaceHash</span><span class="z-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></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">_implementer</span><span class="z-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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">setInterfaceImplementer</span><span class="z-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">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></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 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">_addr</span><span class="z-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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">getManager</span><span class="z-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">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">view</span><span class="z-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></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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">_addr</span><span class="z-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">_newManager</span><span class="z-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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">setManager</span><span class="z-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">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></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 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">_interfaceName</span><span class="z-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">interfaceHash</span><span class="z-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">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">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></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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">_contract</span><span class="z-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">_interfaceId</span><span class="z-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">bytes4</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">updateERC165Cache</span><span class="z-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">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></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 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">_addr</span><span class="z-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">_interfaceHash</span><span class="z-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">getInterfaceImplementer</span><span class="z-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">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">view</span><span class="z-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></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 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">_contract</span><span class="z-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">_interfaceId</span><span class="z-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">bytes4</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">implementsERC165InterfaceNoCache</span><span class="z-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">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></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">view</span><span class="z-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></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 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">_contract</span><span class="z-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">_interfaceId</span><span class="z-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">bytes4</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">implementsERC165Interface</span><span class="z-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">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></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">view</span><span class="z-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></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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">addr</span><span class="z-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"> true</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">interfaceHash</span><span class="z-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></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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">implementer</span><span class="z-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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">InterfaceImplementerSet</span><span class="z-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">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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">addr</span><span class="z-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"> true</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">newManager</span><span class="z-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">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ManagerChanged</span><span class="z-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 class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">devdoc</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">author</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Jordi Baylina and Jacques Dafflon</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">methods</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">getInterfaceImplementer(address,bytes32)</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">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">_addr</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address being queried for the implementer of an interface. (If `_addr == 0` then `msg.sender` is assumed.)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">_interfaceHash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">keccak256 hash of the name of the interface as a string. E.g., `web3.utils.keccak256(&#39;ERC777Token&#39;)`.</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">return</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The address of the contract which implements the interface `_interfaceHash` for `_addr` or `0x0` if `_addr` did not register an implementer for this interface.</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">getManager(address)</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">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">_addr</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address for which to return the manager.</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">return</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address of the manager for a given 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 class="z-support"> &quot;</span><span class="z-support">implementsERC165Interface(address,bytes4)</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">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">_contract</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address of the contract to check.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">_interfaceId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC165 interface to check.</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">return</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">`true` if `_contract` implements `_interfaceId`, false otherwise.</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">implementsERC165InterfaceNoCache(address,bytes4)</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">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">_contract</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address of the contract to check.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">_interfaceId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC165 interface to check.</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">return</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">`true` if `_contract` implements `_interfaceId`, false otherwise.</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">interfaceHash(string)</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">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">_interfaceName</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 interface.</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">return</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The keccak256 hash of an interface 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 class="z-support"> &quot;</span><span class="z-support">setInterfaceImplementer(address,bytes32,address)</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">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">_addr</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address to define the interface for. (If `_addr == 0` then `msg.sender` is assumed.)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">_implementer</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Contract address implementing _interfaceHash for _addr.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">_interfaceHash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">keccak256 hash of the name of the interface as a string. For example, `web3.utils.keccak256(&#39;ERC777TokensRecipient&#39;)` for the `ERC777TokensRecipient` interface.</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">setManager(address,address)</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">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">_addr</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address for which to set the new manager.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">_newManager</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address of the new manager for `addr`.</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">updateERC165Cache(address,bytes4)</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">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">_contract</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Address of the contract for which to update the cache.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">_interfaceId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC165 interface for which to update the cache.</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">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC820 Pseudo-introspection Registry Contract</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">userdoc</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">methods</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">getInterfaceImplementer(address,bytes32)</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Query if an address implements an interface and through which contract.</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">getManager(address)</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Get the manager of an 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 class="z-support"> &quot;</span><span class="z-support">implementsERC165Interface(address,bytes4)</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Checks whether a contract implements an ERC165 interface or not. The result may be cached, if not a direct lookup is performed.</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">implementsERC165InterfaceNoCache(address,bytes4)</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Checks whether a contract implements an ERC165 interface or not without using nor updating the cache.</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">interfaceHash(string)</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Compute the keccak256 hash of an interface given its 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 class="z-support"> &quot;</span><span class="z-support">setInterfaceImplementer(address,bytes32,address)</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Sets the contract which implements a specific interface for an address. Only the manager defined for that address can set it. (Each address is the manager for itself until it sets a new manager.)</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">setManager(address,address)</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Sets the `_newManager` as manager for the `_addr` address. The new manager will be able to call `setInterfaceImplementer` for `_addr`.</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">updateERC165Cache(address,bytes4)</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">notice</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Updates the cache with whether the contract implements an ERC165 interface or not.</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">settings</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">compilationTarget</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">./contracts/ERC820Registry.sol</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC820Registry</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">evmVersion</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">byzantium</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">libraries</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">optimizer</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">enabled</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">runs</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 200</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">remappings</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">sources</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">./contracts/ERC820Registry.sol</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">content</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">/* ERC820 Pseudo-introspection Registry Contract</span><span class="z-constant">\n</span><span class="z-string"> * This standard defines a universal registry smart contract where any address</span><span class="z-constant">\n</span><span class="z-string"> * (contract or regular account) can register which interface it supports and</span><span class="z-constant">\n</span><span class="z-string"> * which smart contract is responsible for its implementation.</span><span class="z-constant">\n</span><span class="z-string"> *</span><span class="z-constant">\n</span><span class="z-string"> * Written in 2018 by Jordi Baylina and Jacques Dafflon</span><span class="z-constant">\n</span><span class="z-string"> *</span><span class="z-constant">\n</span><span class="z-string"> * To the extent possible under law, the author(s) have dedicated all copyright</span><span class="z-constant">\n</span><span class="z-string"> * and related and neighboring rights to this software to the public domain</span><span class="z-constant">\n</span><span class="z-string"> * worldwide. This software is distributed without any warranty.</span><span class="z-constant">\n</span><span class="z-string"> *</span><span class="z-constant">\n</span><span class="z-string"> * You should have received a copy of the CC0 Public Domain Dedication along</span><span class="z-constant">\n</span><span class="z-string"> * with this software. If not, see</span><span class="z-constant">\n</span><span class="z-string"> * &lt;https://creativecommons.org/publicdomain/zero/1.0/&gt;.</span><span class="z-constant">\n</span><span class="z-string"> *</span><span class="z-constant">\n</span><span class="z-string"> * ███████╗██████╗ ██████╗ █████╗ ██████╗ ██████╗</span><span class="z-constant">\n</span><span class="z-string"> * ██╔════╝██╔══██╗██╔════╝██╔══██╗╚════██╗██╔═████╗</span><span class="z-constant">\n</span><span class="z-string"> * █████╗ ██████╔╝██║ ╚█████╔╝ █████╔╝██║██╔██║</span><span class="z-constant">\n</span><span class="z-string"> * ██╔══╝ ██╔══██╗██║ ██╔══██╗██╔═══╝ ████╔╝██║</span><span class="z-constant">\n</span><span class="z-string"> * ███████╗██║ ██║╚██████╗╚█████╔╝███████╗╚██████╔╝</span><span class="z-constant">\n</span><span class="z-string"> * ╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚════╝ ╚══════╝ ╚═════╝</span><span class="z-constant">\n</span><span class="z-string"> *</span><span class="z-constant">\n</span><span class="z-string"> * ██████╗ ███████╗ ██████╗ ██╗███████╗████████╗██████╗ ██╗ ██╗</span><span class="z-constant">\n</span><span class="z-string"> * ██╔══██╗██╔════╝██╔════╝ ██║██╔════╝╚══██╔══╝██╔══██╗╚██╗ ██╔╝</span><span class="z-constant">\n</span><span class="z-string"> * ██████╔╝█████╗ ██║ ███╗██║███████╗ ██║ ██████╔╝ ╚████╔╝</span><span class="z-constant">\n</span><span class="z-string"> * ██╔══██╗██╔══╝ ██║ ██║██║╚════██║ ██║ ██╔══██╗ ╚██╔╝</span><span class="z-constant">\n</span><span class="z-string"> * ██║ ██║███████╗╚██████╔╝██║███████║ ██║ ██║ ██║ ██║</span><span class="z-constant">\n</span><span class="z-string"> * ╚═╝ ╚═╝╚══════╝ ╚═════╝ ╚═╝╚══════╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝</span><span class="z-constant">\n</span><span class="z-string"> *</span><span class="z-constant">\n</span><span class="z-string"> */</span><span class="z-constant">\n</span><span class="z-string">pragma solidity 0.4.24;</span><span class="z-constant">\n</span><span class="z-string">// IV is value needed to have a vanity address starting with `0x820`.</span><span class="z-constant">\n</span><span class="z-string">// IV: 9513</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string">/// @dev The interface a contract MUST implement if it is the implementer of</span><span class="z-constant">\n</span><span class="z-string">/// some (other) interface for any address other than itself.</span><span class="z-constant">\n</span><span class="z-string">interface ERC820ImplementerInterface {</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Indicates whether the contract implements the interface `interfaceHash` for the address `addr` or not.</span><span class="z-constant">\n</span><span class="z-string"> /// @param interfaceHash keccak256 hash of the name of the interface</span><span class="z-constant">\n</span><span class="z-string"> /// @param addr Address for which the contract will implement the interface</span><span class="z-constant">\n</span><span class="z-string"> /// @return ERC820_ACCEPT_MAGIC only if the contract implements `interfaceHash` for the address `addr`.</span><span class="z-constant">\n</span><span class="z-string"> function canImplementInterfaceForAddress(bytes32 interfaceHash, address addr) external view returns(bytes32);</span><span class="z-constant">\n</span><span class="z-string">}</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string">/// @title ERC820 Pseudo-introspection Registry Contract</span><span class="z-constant">\n</span><span class="z-string">/// @author Jordi Baylina and Jacques Dafflon</span><span class="z-constant">\n</span><span class="z-string">/// @notice This contract is the official implementation of the ERC820 Registry.</span><span class="z-constant">\n</span><span class="z-string">/// @notice For more details, see https://eips.ethereum.org/EIPS/eip-820</span><span class="z-constant">\n</span><span class="z-string">contract ERC820Registry {</span><span class="z-constant">\n</span><span class="z-string"> /// @notice ERC165 Invalid ID.</span><span class="z-constant">\n</span><span class="z-string"> bytes4 constant INVALID_ID = 0xffffffff;</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Method ID for the ERC165 supportsInterface method (= `bytes4(keccak256(&#39;supportsInterface(bytes4)&#39;))`).</span><span class="z-constant">\n</span><span class="z-string"> bytes4 constant ERC165ID = 0x01ffc9a7;</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Magic value which is returned if a contract implements an interface on behalf of some other address.</span><span class="z-constant">\n</span><span class="z-string"> bytes32 constant ERC820_ACCEPT_MAGIC = keccak256(abi.encodePacked(</span><span class="z-constant">\&quot;</span><span class="z-string">ERC820_ACCEPT_MAGIC</span><span class="z-constant">\&quot;</span><span class="z-string">));</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> mapping (address =&gt; mapping(bytes32 =&gt; address)) interfaces;</span><span class="z-constant">\n</span><span class="z-string"> mapping (address =&gt; address) managers;</span><span class="z-constant">\n</span><span class="z-string"> mapping (address =&gt; mapping(bytes4 =&gt; bool)) erc165Cached;</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Indicates a contract is the `implementer` of `interfaceHash` for `addr`.</span><span class="z-constant">\n</span><span class="z-string"> event InterfaceImplementerSet(address indexed addr, bytes32 indexed interfaceHash, address indexed implementer);</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Indicates `newManager` is the address of the new manager for `addr`.</span><span class="z-constant">\n</span><span class="z-string"> event ManagerChanged(address indexed addr, address indexed newManager);</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Query if an address implements an interface and through which contract.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _addr Address being queried for the implementer of an interface.</span><span class="z-constant">\n</span><span class="z-string"> /// (If `_addr == 0` then `msg.sender` is assumed.)</span><span class="z-constant">\n</span><span class="z-string"> /// @param _interfaceHash keccak256 hash of the name of the interface as a string.</span><span class="z-constant">\n</span><span class="z-string"> /// E.g., `web3.utils.keccak256(&#39;ERC777Token&#39;)`.</span><span class="z-constant">\n</span><span class="z-string"> /// @return The address of the contract which implements the interface `_interfaceHash` for `_addr`</span><span class="z-constant">\n</span><span class="z-string"> /// or `0x0` if `_addr` did not register an implementer for this interface.</span><span class="z-constant">\n</span><span class="z-string"> function getInterfaceImplementer(address _addr, bytes32 _interfaceHash) external view returns (address) {</span><span class="z-constant">\n</span><span class="z-string"> address addr = _addr == 0 ? msg.sender : _addr;</span><span class="z-constant">\n</span><span class="z-string"> if (isERC165Interface(_interfaceHash)) {</span><span class="z-constant">\n</span><span class="z-string"> bytes4 erc165InterfaceHash = bytes4(_interfaceHash);</span><span class="z-constant">\n</span><span class="z-string"> return implementsERC165Interface(addr, erc165InterfaceHash) ? addr : 0;</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-string"> return interfaces[addr][_interfaceHash];</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Sets the contract which implements a specific interface for an address.</span><span class="z-constant">\n</span><span class="z-string"> /// Only the manager defined for that address can set it.</span><span class="z-constant">\n</span><span class="z-string"> /// (Each address is the manager for itself until it sets a new manager.)</span><span class="z-constant">\n</span><span class="z-string"> /// @param _addr Address to define the interface for. (If `_addr == 0` then `msg.sender` is assumed.)</span><span class="z-constant">\n</span><span class="z-string"> /// @param _interfaceHash keccak256 hash of the name of the interface as a string.</span><span class="z-constant">\n</span><span class="z-string"> /// For example, `web3.utils.keccak256(&#39;ERC777TokensRecipient&#39;)` for the `ERC777TokensRecipient` interface.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _implementer Contract address implementing _interfaceHash for _addr.</span><span class="z-constant">\n</span><span class="z-string"> function setInterfaceImplementer(address _addr, bytes32 _interfaceHash, address _implementer) external {</span><span class="z-constant">\n</span><span class="z-string"> address addr = _addr == 0 ? msg.sender : _addr;</span><span class="z-constant">\n</span><span class="z-string"> require(getManager(addr) == msg.sender, </span><span class="z-constant">\&quot;</span><span class="z-string">Not the manager</span><span class="z-constant">\&quot;</span><span class="z-string">);</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> require(!isERC165Interface(_interfaceHash), </span><span class="z-constant">\&quot;</span><span class="z-string">Must not be a ERC165 hash</span><span class="z-constant">\&quot;</span><span class="z-string">);</span><span class="z-constant">\n</span><span class="z-string"> if (_implementer != 0 &amp;&amp; _implementer != msg.sender) {</span><span class="z-constant">\n</span><span class="z-string"> require(</span><span class="z-constant">\n</span><span class="z-string"> ERC820ImplementerInterface(_implementer)</span><span class="z-constant">\n</span><span class="z-string"> .canImplementInterfaceForAddress(_interfaceHash, addr) == ERC820_ACCEPT_MAGIC,</span><span class="z-constant">\n</span><span class="z-constant"> \&quot;</span><span class="z-string">Does not implement the interface</span><span class="z-constant">\&quot;</span><span class="z-constant">\n</span><span class="z-string"> );</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-string"> interfaces[addr][_interfaceHash] = _implementer;</span><span class="z-constant">\n</span><span class="z-string"> emit InterfaceImplementerSet(addr, _interfaceHash, _implementer);</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Sets the `_newManager` as manager for the `_addr` address.</span><span class="z-constant">\n</span><span class="z-string"> /// The new manager will be able to call `setInterfaceImplementer` for `_addr`.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _addr Address for which to set the new manager.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _newManager Address of the new manager for `addr`.</span><span class="z-constant">\n</span><span class="z-string"> function setManager(address _addr, address _newManager) external {</span><span class="z-constant">\n</span><span class="z-string"> require(getManager(_addr) == msg.sender, </span><span class="z-constant">\&quot;</span><span class="z-string">Not the manager</span><span class="z-constant">\&quot;</span><span class="z-string">);</span><span class="z-constant">\n</span><span class="z-string"> managers[_addr] = _newManager == _addr ? 0 : _newManager;</span><span class="z-constant">\n</span><span class="z-string"> emit ManagerChanged(_addr, _newManager);</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Get the manager of an address.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _addr Address for which to return the manager.</span><span class="z-constant">\n</span><span class="z-string"> /// @return Address of the manager for a given address.</span><span class="z-constant">\n</span><span class="z-string"> function getManager(address _addr) public view returns(address) {</span><span class="z-constant">\n</span><span class="z-string"> // By default the manager of an address is the same address</span><span class="z-constant">\n</span><span class="z-string"> if (managers[_addr] == 0) {</span><span class="z-constant">\n</span><span class="z-string"> return _addr;</span><span class="z-constant">\n</span><span class="z-string"> } else {</span><span class="z-constant">\n</span><span class="z-string"> return managers[_addr];</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Compute the keccak256 hash of an interface given its name.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _interfaceName Name of the interface.</span><span class="z-constant">\n</span><span class="z-string"> /// @return The keccak256 hash of an interface name.</span><span class="z-constant">\n</span><span class="z-string"> function interfaceHash(string _interfaceName) external pure returns(bytes32) {</span><span class="z-constant">\n</span><span class="z-string"> return keccak256(abi.encodePacked(_interfaceName));</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /* --- ERC165 Related Functions --- */</span><span class="z-constant">\n</span><span class="z-string"> /* --- Developed in collaboration with William Entriken. --- */</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Updates the cache with whether the contract implements an ERC165 interface or not.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _contract Address of the contract for which to update the cache.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _interfaceId ERC165 interface for which to update the cache.</span><span class="z-constant">\n</span><span class="z-string"> function updateERC165Cache(address _contract, bytes4 _interfaceId) external {</span><span class="z-constant">\n</span><span class="z-string"> interfaces[_contract][_interfaceId] = implementsERC165InterfaceNoCache(_contract, _interfaceId) ? _contract : 0;</span><span class="z-constant">\n</span><span class="z-string"> erc165Cached[_contract][_interfaceId] = true;</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Checks whether a contract implements an ERC165 interface or not.</span><span class="z-constant">\n</span><span class="z-string"> /// The result may be cached, if not a direct lookup is performed.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _contract Address of the contract to check.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _interfaceId ERC165 interface to check.</span><span class="z-constant">\n</span><span class="z-string"> /// @return `true` if `_contract` implements `_interfaceId`, false otherwise.</span><span class="z-constant">\n</span><span class="z-string"> function implementsERC165Interface(address _contract, bytes4 _interfaceId) public view returns (bool) {</span><span class="z-constant">\n</span><span class="z-string"> if (!erc165Cached[_contract][_interfaceId]) {</span><span class="z-constant">\n</span><span class="z-string"> return implementsERC165InterfaceNoCache(_contract, _interfaceId);</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-string"> return interfaces[_contract][_interfaceId] == _contract;</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Checks whether a contract implements an ERC165 interface or not without using nor updating the cache.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _contract Address of the contract to check.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _interfaceId ERC165 interface to check.</span><span class="z-constant">\n</span><span class="z-string"> /// @return `true` if `_contract` implements `_interfaceId`, false otherwise.</span><span class="z-constant">\n</span><span class="z-string"> function implementsERC165InterfaceNoCache(address _contract, bytes4 _interfaceId) public view returns (bool) {</span><span class="z-constant">\n</span><span class="z-string"> uint256 success;</span><span class="z-constant">\n</span><span class="z-string"> uint256 result;</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> (success, result) = noThrowCall(_contract, ERC165ID);</span><span class="z-constant">\n</span><span class="z-string"> if (success == 0 || result == 0) {</span><span class="z-constant">\n</span><span class="z-string"> return false;</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> (success, result) = noThrowCall(_contract, INVALID_ID);</span><span class="z-constant">\n</span><span class="z-string"> if (success == 0 || result != 0) {</span><span class="z-constant">\n</span><span class="z-string"> return false;</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> (success, result) = noThrowCall(_contract, _interfaceId);</span><span class="z-constant">\n</span><span class="z-string"> if (success == 1 &amp;&amp; result == 1) {</span><span class="z-constant">\n</span><span class="z-string"> return true;</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-string"> return false;</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @notice Checks whether the hash is a ERC165 interface (ending with 28 zeroes) or not.</span><span class="z-constant">\n</span><span class="z-string"> /// @param _interfaceHash The hash to check.</span><span class="z-constant">\n</span><span class="z-string"> /// @return `true` if the hash is a ERC165 interface (ending with 28 zeroes), `false` otherwise.</span><span class="z-constant">\n</span><span class="z-string"> function isERC165Interface(bytes32 _interfaceHash) internal pure returns (bool) {</span><span class="z-constant">\n</span><span class="z-string"> return _interfaceHash &amp; 0x00000000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF == 0;</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> /// @dev Make a call on a contract without throwing if the function does not exist.</span><span class="z-constant">\n</span><span class="z-string"> function noThrowCall(address _contract, bytes4 _interfaceId)</span><span class="z-constant">\n</span><span class="z-string"> internal view returns (uint256 success, uint256 result)</span><span class="z-constant">\n</span><span class="z-string"> {</span><span class="z-constant">\n</span><span class="z-string"> bytes4 erc165ID = ERC165ID;</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> assembly {</span><span class="z-constant">\n</span><span class="z-string"> let x := mload(0x40) // Find empty storage location using </span><span class="z-constant">\&quot;</span><span class="z-string">free memory pointer</span><span class="z-constant">\&quot;</span><span class="z-constant">\n</span><span class="z-string"> mstore(x, erc165ID) // Place signature at beginning of empty storage</span><span class="z-constant">\n</span><span class="z-string"> mstore(add(x, 0x04), _interfaceId) // Place first argument directly next to signature</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> success := staticcall(</span><span class="z-constant">\n</span><span class="z-string"> 30000, // 30k gas</span><span class="z-constant">\n</span><span class="z-string"> _contract, // To addr</span><span class="z-constant">\n</span><span class="z-string"> x, // Inputs are stored at location x</span><span class="z-constant">\n</span><span class="z-string"> 0x08, // Inputs are 8 bytes long</span><span class="z-constant">\n</span><span class="z-string"> x, // Store output over input (saves space)</span><span class="z-constant">\n</span><span class="z-string"> 0x20 // Outputs are 32 bytes long</span><span class="z-constant">\n</span><span class="z-string"> )</span><span class="z-constant">\n</span><span class="z-constant">\n</span><span class="z-string"> result := mload(x) // Load the result</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-string"> }</span><span class="z-constant">\n</span><span class="z-string">}</span><span class="z-constant">\n</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">keccak256</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x8eecce3912a15087b3f5845d5a74af7712c93d0a8fcd6f2d40f07ed5032022ab</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">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></details> <h3 id="interface-name">Interface Name</h3> <p>Any interface name is hashed using <code>keccak256</code> and sent to <code>getInterfaceImplementer()</code>.</p> <p>If the interface is part of a standard, it is best practice to explicitly state the interface name and link to this published <a href="https://wg-eips.ritovision.com/820/">ERC-820</a> such that other people don't have to come here to look up these rules.</p> <p>For convenience, the registry provides a function to compute the hash 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"> interfaceHash</span><span>(</span><span class="z-support">string</span><span class="z-variable z-parameter z-function"> _interfaceName</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></code></pre> <p>Compute the keccak256 hash of an interface given its name.</p> <blockquote> <p><small><strong>identifier:</strong> <code>65ba36c1</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_interfaceName</code>: Name of the interface.</small><br /> <small><strong>returns:</strong> The <code>keccak256</code> hash of an interface name.</small></p> </blockquote> <h4 id="approved-ercs"><strong>Approved ERCs</strong></h4> <p>If the interface is part of an approved ERC, it MUST be named <code>ERC###XXXXX</code> where <code>###</code> is the number of the ERC and XXXXX should be the name of the interface in CamelCase. The meaning of this interface SHOULD be defined in the specified ERC.</p> <p>Examples:</p> <ul> <li><code>keccak256("ERC20Token")</code></li> <li><code>keccak256("ERC777Token")</code></li> <li><code>keccak256("ERC777TokensSender")</code></li> <li><code>keccak256("ERC777TokensRecipient")</code></li> </ul> <h4 id="erc-165-compatible-interfaces"><strong><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> Compatible Interfaces</strong></h4> <blockquote> <p>The compatibility with <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>, including the <a href="https://wg-eips.ritovision.com/820/#erc165-cache">ERC165 Cache</a>, has been designed and developed with <a rel="external" href="https://github.com/fulldecent">William Entriken</a>.</p> </blockquote> <p>Any interface where the last 28 bytes are zeroes (<code>0</code>) SHALL be considered an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface.</p> <p><strong><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> Lookup</strong></p> <p>Anyone can explicitly check if a contract implements an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface using the registry by calling one of the two functions 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"> implementsERC165Interface</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</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"> 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></code></pre> <p>Checks whether a contract implements an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface or not.</p> <p><em>NOTE</em>: The result is cached. If the cache is out of date, it MUST be updated by calling <code>updateERC165Cache</code>. (See <a href="https://wg-eips.ritovision.com/820/#erc165-cache">ERC165 Cache</a> for more details.)</p> <blockquote> <p><small><strong>identifier:</strong> <code>f712f3e8</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_contract</code>: Address of the contract to check.</small><br /> <small><code>_interfaceId</code>: <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface to check.</small><br /> <small><strong>returns:</strong> <code>true</code> if <code>_contract</code> implements <code>_interfaceId</code>, false otherwise.</small></p> </blockquote> <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"> implementsERC165InterfaceNoCache</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</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"> 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></code></pre> <p>Checks whether a contract implements an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface or not without using nor updating the cache.</p> <blockquote> <p><small><strong>identifier:</strong> <code>b7056765</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_contract</code>: Address of the contract to check.</small><br /> <small><code>_interfaceId</code>: <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface to check.</small><br /> <small><strong>returns:</strong> <code>true</code> if <code>_contract</code> implements <code>_interfaceId</code>, false otherwise.</small></p> </blockquote> <p><strong><a href="https://wg-eips.ritovision.com/165/">ERC-165</a> Cache</strong> <a id="erc165-cache"></a></p> <p>Whether a contract implements an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface or not can be cached manually to save gas.</p> <p>If a contract dynamically changes its interface and relies on the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> cache of the <a href="https://wg-eips.ritovision.com/820/">ERC-820</a> registry, the cache MUST be updated manually---there is no automatic cache invalidation or cache update. Ideally the contract SHOULD automatically update the cache when changing its interface. However anyone MAY update the cache on the contract's behalf.</p> <p>The cache update MUST be done using the <code>updateERC165Cache</code> 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"> updateERC165Cache</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</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"> public</span></span></code></pre> <blockquote> <p><small><strong>identifier:</strong> <code>a41e7d51</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_contract</code>: Address of the contract for which to update the cache.</small><br /> <small><code>_interfaceId</code>: <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface for which to update the cache.</small></p> </blockquote> <h4 id="private-user-defined-interfaces"><strong>Private User-defined Interfaces</strong></h4> <p>This scheme is extensible. You MAY make up your own interface name and raise awareness to get other people to implement it and then check for those implementations. Have fun but please, you MUST not conflict with the reserved designations above.</p> <h3 id="set-an-interface-for-an-address">Set An Interface For An Address</h3> <p>For any address to set a contract as the interface implementation, it must call the following function of the <a href="https://wg-eips.ritovision.com/820/">ERC-820</a> registry:</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"> setInterfaceImplementer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addr</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _interfaceHash</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _implementer</span><span>)</span><span class="z-storage z-type"> public</span></span></code></pre> <p>Sets the contract which implements a specific interface for an address.</p> <p>Only the <code>manager</code> defined for that address can set it. (Each address is the manager for itself, see the <a href="https://wg-eips.ritovision.com/820/#manager">manager</a> section for more details.)</p> <p><em>NOTE</em>: If <code>_addr</code> and <code>_implementer</code> are two different addresses, then:</p> <ul> <li>The <code>_implementer</code> MUST implement the <code>ERC820ImplementerInterface</code> (detailed below).</li> <li>Calling <code>canImplementInterfaceForAddress</code> on <code>_implementer</code> with the given <code>_addr</code> and <code>_interfaceHash</code> MUST return the <code>ERC820_ACCEPT_MAGIC</code> value.</li> </ul> <p><em>NOTE</em>: The <code>_interfaceHash</code> MUST NOT be an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface---it MUST NOT end with 28 zeroes (<code>0</code>).</p> <p><em>NOTE</em>: The <code>_addr</code> MAY be <code>0</code>, then <code>msg.sender</code> is assumed. This default value simplifies interactions via multisigs where the data of the transaction to sign is constant regardless of the address of the multisig instance.</p> <blockquote> <p><small><strong>identifier:</strong> <code>29965a1d</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_addr</code>: Address to define the interface for (if <code>_addr == 0</code> them <code>msg.sender</code>: is assumed)</small><br /> <small><code>_interfaceHash</code>: <code>keccak256</code> hash of the name of the interface as a string, for example <code>web3.utils.keccak256('ERC777TokensRecipient')</code> for the ERC777TokensRecipient interface.</small><br /> <small><code>_implementer</code>: Contract implementing <code>_interfaceHash</code> for <code>_addr</code>.</small></p> </blockquote> <h3 id="get-an-implementation-of-an-interface-for-an-address">Get An Implementation Of An Interface For An Address</h3> <p>Anyone MAY query the <a href="https://wg-eips.ritovision.com/820/">ERC-820</a> Registry to obtain the address of a contract implementing an interface on behalf of some address using the <code>getInterfaceImplementer</code> 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"> getInterfaceImplementer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addr</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _interfaceHash</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></code></pre> <p>Query if an address implements an interface and through which contract.</p> <p><em>NOTE</em>: If the last 28 bytes of the <code>_interfaceHash</code> are zeroes (<code>0</code>), then the first 4 bytes are considered an <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface and the registry SHALL forward the call to the contract at <code>_addr</code> to see if it implements the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface (the first 4 bytes of <code>_interfaceHash</code>). The registry SHALL also cache <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> queries to reduce gas consumption. Anyone MAY call the <code>erc165UpdateCache</code> function to update whether a contract implements an interface or not.</p> <p><em>NOTE</em>: The <code>_addr</code> MAY be <code>0</code>, then <code>msg.sender</code> is assumed. This default value is consistent with the behavior of the <code>setInterfaceImplementer</code> function and simplifies interactions via multisigs where the data of the transaction to sign is constant regardless of the address of the multisig instance.</p> <blockquote> <p><small><strong>identifier:</strong> <code>aabbb8ca</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_addr</code>: Address being queried for the implementer of an interface. (If <code>_addr == 0</code> them <code>msg.sender</code> is assumed.)</small><br /> <small><code>_interfaceHash</code>: keccak256 hash of the name of the interface as a string. E.g. <code>web3.utils.keccak256('ERC777Token')</code></small><br /> <small><strong>returns:</strong> The address of the contract which implements the interface <code>_interfaceHash</code> for <code>_addr</code> or <code>0x0</code> if <code>_addr</code> did not register an implementer for this interface.</small></p> </blockquote> <h3 id="interface-implementation-erc820implementerinterface">Interface Implementation (<code>ERC820ImplementerInterface</code>)</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"> ERC820ImplementerInterface</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"> Indicates whether the contract implements the interface `interfaceHash` for the address `addr`.</span></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"> Address for which the contract will implement the 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"> interfaceHash</span><span class="z-comment"> keccak256 hash of the name of the interface</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"> ERC820_ACCEPT_MAGIC</span><span class="z-comment"> only if the contract implements `ìnterfaceHash` for the address `addr`.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canImplementInterfaceForAddress</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> interfaceHash</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">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Any contract being registered as the implementation of an interface for a given address MUST implement said interface. In addition if it implements an interface on behalf of a different address, the contract MUST implement the <code>ERC820ImplementerInterface</code> shown above.</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"> canImplementInterfaceForAddress</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> interfaceHash</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> addr</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>)</span><span>;</span></span></code></pre> <p>Indicates whether a contract implements an interface (<code>interfaceHash</code>) for a given address (<code>addr</code>).</p> <p>If a contract implements the interface (<code>interfaceHash</code>) for a given address (<code>addr</code>), it MUST return <code>ERC820_ACCEPT_MAGIC</code> when called with the <code>addr</code> and the <code>interfaceHash</code>. If it does not implement the <code>interfaceHash</code> for a given address (<code>addr</code>), it MUST NOT return <code>ERC820_ACCEPT_MAGIC</code>.</p> <blockquote> <p><small><strong>identifier:</strong> <code>f0083250</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>interfaceHash</code>: Hash of the interface which is implemented</small><br /> <small><code>addr</code>: Address for which the interface is implemented</small><br /> <small><strong>returns:</strong> <code>ERC820_ACCEPT_MAGIC</code> only if the contract implements <code>ìnterfaceHash</code> for the address <code>addr</code>.</small></p> </blockquote> <p>The special value <code>ERC820_ACCEPT_MAGIC</code> is defined as the <code>keccka256</code> hash of the string <code>"ERC820_ACCEPT_MAGIC"</code>.</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"> constant</span><span> ERC820_ACCEPT_MAGIC </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;ERC820_ACCEPT_MAGIC&quot;</span><span>)</span><span>;</span></span></code></pre> <blockquote> <p>The reason to return <code>ERC820_ACCEPT_MAGIC</code> instead of a boolean is to prevent cases where a contract fails to implement the <code>canImplementInterfaceForAddress</code> but implements a fallback function which does not throw. In this case, since <code>canImplementInterfaceForAddress</code> does not exist, the fallback function is called instead, executed without throwing and returns <code>1</code>. Thus making it appear as if <code>canImplementInterfaceForAddress</code> returned <code>true</code>.</p> </blockquote> <h3 id="manager">Manager</h3> <p>The manager of an address (regular account or a contract) is the only entity allowed to register implementations of interfaces for the address. By default, any address is its own manager.</p> <p>The manager can transfer its role to another address by calling <code>setManager</code> on the registry contract with the address for which to transfer the manager and the address of the new manager.</p> <p><strong><code>setManager</code> Function</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"> setManager</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addr</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _newManager</span><span>)</span><span class="z-storage z-type"> public</span></span></code></pre> <p>Sets the <code>_newManager</code> as manager for the <code>_addr</code> address.</p> <p>The new manager will be able to call <code>setInterfaceImplementer</code> for <code>_addr</code>.</p> <p>If <code>_newManager</code> is <code>0x0</code>, the manager is reset to <code>_addr</code> itself as the manager.</p> <blockquote> <p><small><strong>identifier:</strong> <code>5df8122f</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_addr</code>: Address for which to set the new manager.</small><br /> <small><code>_newManager</code>: The address of the new manager for <code>_addr</code>. (Pass <code>0x0</code> to reset the manager to <code>_addr</code>.)</small></p> </blockquote> <p><strong><code>getManager</code> Function</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"> getManager</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"> 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></code></pre> <p>Get the manager of an address.</p> <blockquote> <p><small><strong>identifier:</strong> <code>3d584063</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>_addr</code>: Address for which to return the manager.</small><br /> <small><strong>returns:</strong> Address of the manager for a given address.</small></p> </blockquote> <h2 id="rationale">Rationale</h2> <p>This standards offers a way for any type of address (externally owned and contracts) to implement an interface and potentially delegate the implementation of the interface to a proxy contract. This delegation to a proxy contract is necessary for externally owned accounts and useful to avoid redeploying existing contracts such as multisigs and DAOs.</p> <p>The registry can also act as a <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> cache in order to save gas when looking up if a contract implements a specific <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> interface. This cache is intentionally kept simple, without automatic cache update or invalidation. Anyone can easily and safely update the cache for any interface and any contract by calling the <code>updateERC165Cache</code> function.</p> <p>The registry is deployed using a keyless deployment method relying on a single-use deployment address to ensure no one controls the registry, thereby ensuring trust.</p> <h2 id="backward-compatibility">Backward Compatibility</h2> <p>This standard is backward compatible with <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>, as both methods MAY be implemented without conflicting with each other.</p> <h2 id="test-cases">Test Cases</h2> <p>Please check the <a rel="external" href="https://github.com/jbaylina/ERC820">jbaylina/ERC820</a> repository for the full test suite.</p> <h2 id="implementation">Implementation</h2> <p>The implementation is available in the repo: <a rel="external" href="https://github.com/jbaylina/ERC820">jbaylina/ERC820</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-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-23T00:00:00+00:00 2026-02-11T14:49:28+00:00 Felix Langefjl@ethereum.org https://wg-eips.ritovision.com/778/ <h1 id="abstract">Abstract</h1> <p>This EIP defines Ethereum Node Records, an open format for p2p connectivity information.</p> <h1 id="motivation">Motivation</h1> <p>Ethereum nodes discover each other through the node discovery protocol. The purpose of that protocol is relaying node identity public keys (on the secp256k1 curve), their IP address and two port numbers. No other information can be relayed.</p> <p>This specification seeks to lift the restrictions of the discovery v4 protocol by defining a flexible format, the <em>node record</em>, for connectivity-related information. Node records can be relayed through a future version of the node discovery protocol. They can also be relayed through arbitrary other mechanisms such as DNS, ENS, a devp2p subprotocol, etc.</p> <p>Node records improve cryptographic agility and handling of protocol upgrades. A record can contain information about arbitrary transport protocols and public key material associated with them.</p> <p>Another goal of the new format is to provide authoritative updates of connectivity information. If a node changes its endpoint and publishes a new record, other nodes should be able to determine which record is newer.</p> <h1 id="specification">Specification</h1> <p>The components of a node record are:</p> <ul> <li><code>signature</code>: cryptographic signature of record contents</li> <li><code>seq</code>: The sequence number, a 64-bit unsigned integer. Nodes should increase the number whenever the record changes and republish the record.</li> <li>The remainder of the record consists of arbitrary key/value pairs</li> </ul> <p>A record's signature is made and validated according to an <em>identity scheme</em>. The identity scheme is also responsible for deriving a node's address in the DHT.</p> <p>The key/value pairs must be sorted by key and must be unique, i.e. any key may be present only once. The keys can technically be any byte sequence, but ASCII text is preferred. Key names in the table below have pre-defined meaning.</p> <table><thead><tr><th style="text-align: left">Key</th><th style="text-align: left">Value</th></tr></thead><tbody> <tr><td style="text-align: left"><code>id</code></td><td style="text-align: left">name of identity scheme, e.g. "v4"</td></tr> <tr><td style="text-align: left"><code>secp256k1</code></td><td style="text-align: left">compressed secp256k1 public key, 33 bytes</td></tr> <tr><td style="text-align: left"><code>ip</code></td><td style="text-align: left">IPv4 address, 4 bytes</td></tr> <tr><td style="text-align: left"><code>tcp</code></td><td style="text-align: left">TCP port, big endian integer</td></tr> <tr><td style="text-align: left"><code>udp</code></td><td style="text-align: left">UDP port, big endian integer</td></tr> <tr><td style="text-align: left"><code>ip6</code></td><td style="text-align: left">IPv6 address, 16 bytes</td></tr> <tr><td style="text-align: left"><code>tcp6</code></td><td style="text-align: left">IPv6-specific TCP port, big endian integer</td></tr> <tr><td style="text-align: left"><code>udp6</code></td><td style="text-align: left">IPv6-specific UDP port, big endian integer</td></tr> </tbody></table> <p>All keys except <code>id</code> are optional, including IP addresses and ports. A record without endpoint information is still valid as long as its signature is valid. If no <code>tcp6</code> / <code>udp6</code> port is provided, the <code>tcp</code> / <code>udp</code> port applies to both IP addresses. Declaring the same port number in both <code>tcp</code>, <code>tcp6</code> or <code>udp</code>, <code>udp6</code> should be avoided but doesn't render the record invalid.</p> <h3 id="rlp-encoding">RLP Encoding</h3> <p>The canonical encoding of a node record is an RLP list of <code>[signature, seq, k, v, ...]</code>. The maximum encoded size of a node record is 300 bytes. Implementations should reject records larger than this size.</p> <p>Records are signed and encoded as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>content = [seq, k, v, ...]</span></span> <span class="giallo-l"><span>signature = sign(content)</span></span> <span class="giallo-l"><span>record = [signature, seq, k, v, ...]</span></span></code></pre><h3 id="text-encoding">Text Encoding</h3> <p>The textual form of a node record is the base64 encoding of its RLP representation, prefixed by <code>enr:</code>. Implementations should use the <a rel="external" href="https://tools.ietf.org/html/rfc4648#section-5">URL-safe base64 alphabet</a> and omit padding characters.</p> <h3 id="v4-identity-scheme">"v4" Identity Scheme</h3> <p>This specification defines a single identity scheme to be used as the default until other schemes are defined by further EIPs. The "v4" scheme is backwards-compatible with the cryptosystem used by Node Discovery v4.</p> <ul> <li>To sign record <code>content</code> with this scheme, apply the keccak256 hash function (as used by the EVM) to <code>content</code>, then create a signature of the hash. The resulting 64-byte signature is encoded as the concatenation of the <code>r</code> and <code>s</code> signature values (the recovery ID <code>v</code> is omitted).</li> <li>To verify a record, check that the signature was made by the public key in the "secp256k1" key/value pair of the record.</li> <li>To derive a node address, take the keccak256 hash of the uncompressed public key.</li> </ul> <h1 id="rationale">Rationale</h1> <p>The format is meant to suit future needs in two ways:</p> <ul> <li>Adding new key/value pairs: This is always possible and doesn't require implementation consensus. Existing clients will accept any key/value pairs regardless of whether they can interpret their content.</li> <li>Adding identity schemes: these need implementation consensus because the network won't accept the signature otherwise. To introduce a new identity scheme, propose an EIP and get it implemented. The scheme can be used as soon as most clients accept it.</li> </ul> <p>The size of a record is limited because records are relayed frequently and may be included in size-constrained protocols such as DNS. A record containing a IPv4 address, when signed using the "v4" scheme occupies roughly 120 bytes, leaving plenty of room for additional metadata.</p> <p>You might wonder about the need for so many pre-defined keys related to IP addresses and ports. This need arises because residential and mobile network setups often put IPv4 behind NAT while IPv6 traffic—if supported—is directly routed to the same host. Declaring both address types ensures a node is reachable from IPv4-only locations and those supporting both protocols.</p> <h1 id="test-vectors">Test Vectors</h1> <p>This is an example record containing the IPv4 address <code>127.0.0.1</code> and UDP port <code>30303</code>. The node ID is <code>a448f24c6d18e575453db13171562b71999873db5b286df957af199ec94617f7</code>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>enr:-IS4QHCYrYZbAKWCBRlAy5zzaDZXJBGkcnh4MHcBFZntXNFrdvJjX04jRzjzCBOonrkTfj499SZuOh8R33Ls8RRcy5wBgmlkgnY0gmlwhH8AAAGJc2VjcDI1NmsxoQPKY0yuDUmstAHYpMa2_oxVtw0RW_QAdpzBQA8yWM0xOIN1ZHCCdl8</span></span></code></pre> <p>The record is signed using the "v4" identity scheme using sequence number <code>1</code> and this private key:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>b71c71a67e1177ad4e901695e1b4b9ee17ae16c6668d313eac2f96dbcda3f291</span></span></code></pre> <p>The RLP structure of the record is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[</span></span> <span class="giallo-l"><span> 7098ad865b00a582051940cb9cf36836572411a47278783077011599ed5cd16b76f2635f4e234738f30813a89eb9137e3e3df5266e3a1f11df72ecf1145ccb9c,</span></span> <span class="giallo-l"><span> 01,</span></span> <span class="giallo-l"><span> &quot;id&quot;,</span></span> <span class="giallo-l"><span> &quot;v4&quot;,</span></span> <span class="giallo-l"><span> &quot;ip&quot;,</span></span> <span class="giallo-l"><span> 7f000001,</span></span> <span class="giallo-l"><span> &quot;secp256k1&quot;,</span></span> <span class="giallo-l"><span> 03ca634cae0d49acb401d8a4c6b6fe8c55b70d115bf400769cc1400f3258cd3138,</span></span> <span class="giallo-l"><span> &quot;udp&quot;,</span></span> <span class="giallo-l"><span> 765f,</span></span> <span class="giallo-l"><span>]</span></span></code></pre><h1 id="copyright">Copyright</h1> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2017-11-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jacques Dafflonmail@0xjac.com Jordi Baylinajordi@baylina.cat Thomas Shababitom@truelevel.io https://wg-eips.ritovision.com/777/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP defines standard interfaces and behaviors for token contracts.</p> <h2 id="abstract">Abstract</h2> <p>This standard defines a new way to interact with a token contract while remaining backward compatible with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>.</p> <p>It defines advanced features to interact with tokens. Namely, <em>operators</em> to send tokens on behalf of another address—contract or regular account—and send/receive <em>hooks</em> to offer token holders more control over their tokens.</p> <p>It takes advantage of <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> to find out whether and where to notify contracts and regular addresses when they receive tokens as well as to allow compatibility with already-deployed contracts.</p> <h2 id="motivation">Motivation</h2> <p>This standard tries to improve upon the widely used <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token standard. The main advantages of this standard are:</p> <ol> <li> <p>Uses the same philosophy as Ether in that tokens are sent with <code>send(dest, value, data)</code>.</p> </li> <li> <p>Both contracts and regular addresses can control and reject which token they send by registering a <code>tokensToSend</code> hook. (Rejection is done by <code>revert</code>ing in the hook function.)</p> </li> <li> <p>Both contracts and regular addresses can control and reject which token they receive by registering a <code>tokensReceived</code> hook. (Rejection is done by <code>revert</code>ing in the hook function.)</p> </li> <li> <p>The <code>tokensReceived</code> hook allows to send tokens to a contract and notify it in a single transaction, unlike <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> which requires a double call (<code>approve</code>/<code>transferFrom</code>) to achieve this.</p> </li> <li> <p>The holder can "authorize" and "revoke" operators which can send tokens on their behalf. These operators are intended to be verified contracts such as an exchange, a cheque processor or an automatic charging system.</p> </li> <li> <p>Every token transaction contains <code>data</code> and <code>operatorData</code> bytes fields to be used freely to pass data from the holder and the operator, respectively.</p> </li> <li> <p>It is backward compatible with wallets that do not contain the <code>tokensReceived</code> hook function by deploying a proxy contract implementing the <code>tokensReceived</code> hook for the wallet.</p> </li> </ol> <h2 id="specification">Specification</h2> <h3 id="erc777token-token-contract">ERC777Token (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"> ERC777Token</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> <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"> 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"> balanceOf</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 class="z-storage z-type"> function</span><span class="z-entity z-name"> granularity</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"> defaultOperators</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-storage z-type"> function</span><span class="z-entity z-name"> isOperatorFor</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-variable"> holder</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-storage z-type"> function</span><span class="z-entity z-name"> authorizeOperator</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>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeOperator</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>;</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"> send</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"> calldata</span><span class="z-variable"> data</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"> operatorSend</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></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></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operatorData</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"> burn</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"> calldata</span><span class="z-variable"> data</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"> operatorBurn</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"> amount</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></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operatorData</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"> event</span><span class="z-entity z-name"> Sent</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"> 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-support"> bytes</span><span class="z-variable"> data</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> operatorData</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"> 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"> 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-support"> bytes</span><span class="z-variable"> data</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> operatorData</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"> Burned</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"> 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></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-support"> bytes</span><span class="z-variable"> operatorData</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"> AuthorizedOperator</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"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> holder</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"> RevokedOperator</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"> holder</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The token contract MUST implement the above interface. The implementation MUST follow the specifications described below.</p> <p>The token contract MUST register the <code>ERC777Token</code> interface with its own address via <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a>.</p> <blockquote> <p>This is done by calling the <code>setInterfaceImplementer</code> function on the <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> registry with the token contract address as both the address and the implementer and the <code>keccak256</code> hash of <code>ERC777Token</code> (<code>0xac7fbab5f54a3ca8194167523c6753bfeb96a445279294b6125b68cce2177054</code>) as the interface hash.</p> </blockquote> <p>If the contract has a switch to enable or disable ERC-777 functions, every time the switch is triggered, the token MUST register or unregister the <code>ERC777Token</code> interface for its own address accordingly via ERC1820. Unregistering implies calling the <code>setInterfaceImplementer</code> with the token contract address as the address, the <code>keccak256</code> hash of <code>ERC777Token</code> as the interface hash and <code>0x0</code> as the implementer. (See <a href="https://wg-eips.ritovision.com/1820/#set-an-interface-for-an-address">Set An Interface For An Address</a> in <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> for more details.)</p> <p>When interacting with the token contract, all amounts and balances MUST be unsigned integers. I.e. internally, all values are stored as a denomination of 1E-18 of a token. The display denomination—to display any amount to the end user—MUST be 10¹⁸ of the internal denomination.</p> <p>In other words, the internal denomination is similar to a wei and the display denomination is similar to an ether. It is equivalent to an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>'s <code>decimals</code> function returning <code>18</code>. E.g. if a token contract returns a balance of <code>500,000,000,000,000,000</code> (0.5×10¹⁸) for a user, the user interface MUST show <code>0.5</code> tokens to the user. If the user wishes to send <code>0.3</code> tokens, the contract MUST be called with an amount of <code>300,000,000,000,000,000</code> (0.3×10¹⁸).</p> <p>User Interfaces which are generated programmatically from the ABI of the token contract MAY use and display the internal denomination. But this MUST be made clear, for example by displaying the <code>uint256</code> type.</p> <h4 id="view-functions"><strong>View Functions</strong></h4> <p>The <code>view</code> functions detailed below MUST be implemented.</p> <p><strong><code>name</code> function</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-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></code></pre> <p>Get the name of the token, e.g., <code>"MyToken"</code>.</p> <blockquote> <p><small><strong>identifier:</strong> <code>06fdde03</code></small><br /> <small><strong>returns:</strong> Name of the token.</small></p> </blockquote> <p><strong><code>symbol</code> function</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-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></code></pre> <p>Get the symbol of the token, e.g., <code>"MYT"</code>.</p> <blockquote> <p><small><strong>identifier:</strong> <code>95d89b41</code></small><br /> <small><strong>returns:</strong> Symbol of the token.</small></p> </blockquote> <p><strong><code>totalSupply</code> function</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-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>Get the total number of minted tokens.</p> <p><em>NOTE</em>: The total supply MUST be equal to the sum of the balances of all addresses—as returned by the <code>balanceOf</code> function.</p> <p><em>NOTE</em>: The total supply MUST be equal to the sum of all the minted tokens as defined in all the <code>Minted</code> events minus the sum of all the burned tokens as defined in all the <code>Burned</code> events.</p> <blockquote> <p><small><strong>identifier:</strong> <code>18160ddd</code></small><br /> <small><strong>returns:</strong> Total supply of tokens currently in circulation.</small></p> </blockquote> <p><strong><code>balanceOf</code> function</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"> 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></code></pre> <p>Get the balance of the account with address <code>holder</code>.</p> <p>The balance MUST be zero (<code>0</code>) or higher.</p> <blockquote> <p><small><strong>identifier:</strong> <code>70a08231</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>holder</code>: Address for which the balance is returned.</small></p> <p><small><strong>returns:</strong> Amount of tokens held by <code>holder</code> in the token contract.</small></p> </blockquote> <p><strong><code>granularity</code> function</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"> granularity</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>Get the smallest part of the token that's not divisible.</p> <p>In other words, the granularity is the smallest amount of tokens (in the internal denomination) which MAY be minted, sent or burned at any time.</p> <p>The following rules MUST be applied regarding the <em>granularity</em>:</p> <ul> <li> <p>The <em>granularity</em> value MUST be set at creation time.</p> </li> <li> <p>The <em>granularity</em> value MUST NOT be changed, ever.</p> </li> <li> <p>The <em>granularity</em> value MUST be greater than or equal to <code>1</code>.</p> </li> <li> <p>All balances MUST be a multiple of the granularity.</p> </li> <li> <p>Any amount of tokens (in the internal denomination) minted, sent or burned MUST be a multiple of the <em>granularity</em> value.</p> </li> <li> <p>Any operation that would result in a balance that's not a multiple of the <em>granularity</em> value MUST be considered invalid, and the transaction MUST <code>revert</code>.</p> </li> </ul> <p><em>NOTE</em>: Most tokens SHOULD be fully partition-able. I.e., this function SHOULD return <code>1</code> unless there is a good reason for not allowing any fraction of the token.</p> <blockquote> <p><small><strong>identifier:</strong> <code>556f0dc7</code></small><br /> <small><strong>returns:</strong> The smallest non-divisible part of the token.</small></p> </blockquote> <p><em>NOTE</em>: <a href="https://wg-eips.ritovision.com/777/#defaultOperators"><code>defaultOperators</code></a> and <a href="https://wg-eips.ritovision.com/777/#isOperatorFor"><code>isOperatorFor</code></a> are also <code>view</code> functions, defined under the <a href="https://wg-eips.ritovision.com/777/#operators">operators</a> for consistency.</p> <p><em><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> compatibility requirement</em>:<br /> The decimals of the token MUST always be <code>18</code>. For a <em>pure</em> ERC-777 token the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> <code>decimals</code> function is OPTIONAL, and its existence SHALL NOT be relied upon when interacting with the token contract. (The decimal value of <code>18</code> is implied.) For an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> compatible token, the <code>decimals</code> function is REQUIRED and MUST return <code>18</code>. (In <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, the <code>decimals</code> function is OPTIONAL. If the function is not present, the <code>decimals</code> value is not clearly defined and may be assumed to be <code>0</code>. Hence for compatibility reasons, <code>decimals</code> MUST be implemented for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> compatible tokens.)</p> <h4 id="operators"><strong>Operators</strong></h4> <p>An <code>operator</code> is an address which is allowed to send and burn tokens on behalf of some <em>holder</em>.</p> <p>When an address becomes an <em>operator</em> for a <em>holder</em>, an <code>AuthorizedOperator</code> event MUST be emitted. The <code>AuthorizedOperator</code>'s <code>operator</code> (topic 1) and <code>holder</code> (topic 2) MUST be the addresses of the <em>operator</em> and the <em>holder</em> respectively.</p> <p>When a <em>holder</em> revokes an <em>operator</em>, a <code>RevokedOperator</code> event MUST be emitted. The <code>RevokedOperator</code>'s <code>operator</code> (topic 1) and <code>holder</code> (topic 2) MUST be the addresses of the <em>operator</em> and the <em>holder</em> respectively.</p> <p><em>NOTE</em>: A <em>holder</em> MAY have multiple <em>operators</em> at the same time.</p> <p>The token MAY define <em>default operators</em>. A <em>default operator</em> is an implicitly authorized <em>operator</em> for all <em>holders</em>. <code>AuthorizedOperator</code> events MUST NOT be emitted when defining the <em>default operators</em>. The rules below apply to <em>default operators</em>:</p> <ul> <li> <p>The token contract MUST define <em>default operators</em> at creation time.</p> </li> <li> <p>The <em>default operators</em> MUST be invariants. I.e., the token contract MUST NOT add or remove <em>default operators</em> ever.</p> </li> <li> <p><code>AuthorizedOperator</code> events MUST NOT be emitted when defining <em>default operators</em>.</p> </li> <li> <p>A <em>holder</em> MUST be allowed to revoke a <em>default operator</em> (unless the <em>holder</em> is the <em>default operator</em> in question).</p> </li> <li> <p>A <em>holder</em> MUST be allowed to re-authorize a previously revoked <em>default operator</em>.</p> </li> <li> <p>When a <em>default operator</em> is explicitly authorized or revoked for a specific <em>holder</em>, an <code>AuthorizedOperator</code> or <code>RevokedOperator</code> event (respectively) MUST be emitted.</p> </li> </ul> <p>The following rules apply to any <em>operator</em>:</p> <ul> <li> <p>An address MUST always be an <em>operator</em> for itself. Hence an address MUST NOT ever be revoked as its own <em>operator</em>.</p> </li> <li> <p>If an address is an <em>operator</em> for a <em>holder</em>, <code>isOperatorFor</code> MUST return <code>true</code>.</p> </li> <li> <p>If an address is not an <em>operator</em> for a <em>holder</em>, <code>isOperatorFor</code> MUST return <code>false</code>.</p> </li> <li> <p>The token contract MUST emit an <code>AuthorizedOperator</code> event with the correct values when a <em>holder</em> authorizes an address as its <em>operator</em> as defined in the <a href="https://wg-eips.ritovision.com/777/#authorizedoperator"><code>AuthorizedOperator</code> Event</a>.</p> </li> <li> <p>The token contract MUST emit a <code>RevokedOperator</code> event with the correct values when a <em>holder</em> revokes an address as its <em>operator</em> as defined in the <a href="https://wg-eips.ritovision.com/777/#revokedoperator"><code>RevokedOperator</code> Event</a>.</p> </li> </ul> <p><em>NOTE</em>: A <em>holder</em> MAY authorize an already authorized <em>operator</em>. An <code>AuthorizedOperator</code> MUST be emitted each time.</p> <p><em>NOTE</em>: A <em>holder</em> MAY revoke an already revoked <em>operator</em>. A <code>RevokedOperator</code> MUST be emitted each time.</p> <p><strong><code>AuthorizedOperator</code> event</strong> <a id="authorizedoperator"></a></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"> AuthorizedOperator</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"> holder</span><span>)</span></span></code></pre> <p>Indicates the authorization of <code>operator</code> as an <em>operator</em> for <code>holder</code>.</p> <p><em>NOTE</em>: This event MUST NOT be emitted outside of an <em>operator</em> authorization process.</p> <blockquote> <p><small><strong>parameters</strong></small><br /> <small><code>operator</code>: Address which became an <em>operator</em> of <code>holder</code>.</small><br /> <small><code>holder</code>: Address of a <em>holder</em> which authorized the <code>operator</code> address as an <em>operator</em>.</small></p> </blockquote> <p><strong><code>RevokedOperator</code> event</strong> <a id="revokedoperator"></a></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"> RevokedOperator</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"> holder</span><span>)</span></span></code></pre> <p>Indicates the revocation of <code>operator</code> as an <em>operator</em> for <code>holder</code>.</p> <p><em>NOTE</em>: This event MUST NOT be emitted outside of an <em>operator</em> revocation process.</p> <blockquote> <p><small><strong>parameters</strong></small><br /> <small><code>operator</code>: Address which was revoked as an <em>operator</em> of <code>holder</code>.</small><br /> <small><code>holder</code>: Address of a <em>holder</em> which revoked the <code>operator</code> address as an <em>operator</em>.</small></p> </blockquote> <p>The <code>defaultOperators</code>, <code>authorizeOperator</code>, <code>revokeOperator</code> and <code>isOperatorFor</code> functions described below MUST be implemented to manage <em>operators</em>. Token contracts MAY implement other functions to manage <em>operators</em>.</p> <p><strong><code>defaultOperators</code> function</strong> <a id="defaultOperators"></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"> defaultOperators</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></code></pre> <p>Get the list of <em>default operators</em> as defined by the token contract.</p> <p><em>NOTE</em>: If the token contract does not have any <em>default operators</em>, this function MUST return an empty list.</p> <blockquote> <p><small><strong>identifier:</strong> <code>06e48538</code></small><br /> <small><strong>returns:</strong> List of addresses of all the <em>default operators</em>.</small></p> </blockquote> <p><strong><code>authorizeOperator</code> function</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"> authorizeOperator</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></code></pre> <p>Set a third party <code>operator</code> address as an <em>operator</em> of <code>msg.sender</code> to send and burn tokens on its behalf.</p> <p><em>NOTE</em>: The <em>holder</em> (<code>msg.sender</code>) is always an <em>operator</em> for itself. This right SHALL NOT be revoked. Hence this function MUST <code>revert</code> if it is called to authorize the holder (<code>msg.sender</code>) as an <em>operator</em> for itself (i.e. if <code>operator</code> is equal to <code>msg.sender</code>).</p> <blockquote> <p><small><strong>identifier:</strong> <code>959b8c3f</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>operator</code>: Address to set as an <em>operator</em> for <code>msg.sender</code>.</small></p> </blockquote> <p><strong><code>revokeOperator</code> function</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"> revokeOperator</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></code></pre> <p>Remove the right of the <code>operator</code> address to be an <em>operator</em> for <code>msg.sender</code> and to send and burn tokens on its behalf.</p> <p><em>NOTE</em>: The <em>holder</em> (<code>msg.sender</code>) is always an <em>operator</em> for itself. This right SHALL NOT be revoked. Hence this function MUST <code>revert</code> if it is called to revoke the holder (<code>msg.sender</code>) as an <em>operator</em> for itself (i.e., if <code>operator</code> is equal to <code>msg.sender</code>).</p> <blockquote> <p><small><strong>identifier:</strong> <code>fad8b32a</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>operator</code>: Address to rescind as an <em>operator</em> for <code>msg.sender</code>.</small></p> </blockquote> <p><strong><code>isOperatorFor</code> function</strong> <a id="isOperatorFor"></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"> isOperatorFor</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-variable"> holder</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></code></pre> <p>Indicate whether the <code>operator</code> address is an <em>operator</em> of the <code>holder</code> address.</p> <blockquote> <p><small><strong>identifier:</strong> <code>d95b6371</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>operator</code>: Address which may be an <em>operator</em> of <code>holder</code>.</small><br /> <small><code>holder</code>: Address of a <em>holder</em> which may have the <code>operator</code> address as an <em>operator</em>.</small></p> <p><small><strong>returns:</strong> <code>true</code> if <code>operator</code> is an <em>operator</em> of <code>holder</code> and <code>false</code> otherwise.</small></p> </blockquote> <p><em>NOTE</em>: To know which addresses are <em>operators</em> for a given <em>holder</em>, one MUST call <code>isOperatorFor</code> with the <em>holder</em> for each <em>default operator</em> and parse the <code>AuthorizedOperator</code>, and <code>RevokedOperator</code> events for the <em>holder</em> in question.</p> <h4 id="sending-tokens"><strong>Sending Tokens</strong></h4> <p>When an <em>operator</em> sends an <code>amount</code> of tokens from a <em>holder</em> to a <em>recipient</em> with the associated <code>data</code> and <code>operatorData</code>, the token contract MUST apply the following rules:</p> <ul> <li> <p>Any authorized <em>operator</em> MAY send tokens to any <em>recipient</em> (except to <code>0x0</code>).</p> </li> <li> <p>The balance of the <em>holder</em> MUST be decreased by the <code>amount</code>.</p> </li> <li> <p>The balance of the <em>recipient</em> MUST be increased by the <code>amount</code>.</p> </li> <li> <p>The balance of the <em>holder</em> MUST be greater or equal to the <code>amount</code>—such that its resulting balance is greater or equal to zero (<code>0</code>) after the send.</p> </li> <li> <p>The token contract MUST emit a <code>Sent</code> event with the correct values as defined in the <a href="https://wg-eips.ritovision.com/777/#sent"><code>Sent</code> Event</a>.</p> </li> <li> <p>The <em>operator</em> MAY include information in the <code>operatorData</code>.</p> </li> <li> <p>The token contract MUST call the <code>tokensToSend</code> hook of the <em>holder</em> if the <em>holder</em> registers an <code>ERC777TokensSender</code> implementation via <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a>.</p> </li> <li> <p>The token contract MUST call the <code>tokensReceived</code> hook of the <em>recipient</em> if the <em>recipient</em> registers an <code>ERC777TokensRecipient</code> implementation via <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a>.</p> </li> <li> <p>The <code>data</code> and <code>operatorData</code> MUST be immutable during the entire send process—hence the same <code>data</code> and <code>operatorData</code> MUST be used to call both hooks and emit the <code>Sent</code> event.</p> </li> </ul> <p>The token contract MUST <code>revert</code> when sending in any of the following cases:</p> <ul> <li> <p>The <em>operator</em> address is not an authorized operator for the <em>holder</em>.</p> </li> <li> <p>The resulting <em>holder</em> balance or <em>recipient</em> balance after the send is not a multiple of the <em>granularity</em> defined by the token contract.</p> </li> <li> <p>The <em>recipient</em> is a contract, and it does not implement the <code>ERC777TokensRecipient</code> interface via <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a>.</p> </li> <li> <p>The address of the <em>holder</em> or the <em>recipient</em> is <code>0x0</code>.</p> </li> <li> <p>Any of the resulting balances becomes negative, i.e. becomes less than zero (<code>0</code>).</p> </li> <li> <p>The <code>tokensToSend</code> hook of the <em>holder</em> <code>revert</code>s.</p> </li> <li> <p>The <code>tokensReceived</code> hook of the <em>recipient</em> <code>revert</code>s.</p> </li> </ul> <p>The token contract MAY send tokens from many <em>holders</em>, to many <em>recipients</em>, or both. In this case:</p> <ul> <li>The previous send rules MUST apply to all the <em>holders</em> and all the <em>recipients</em>.</li> <li>The sum of all the balances incremented MUST be equal to the total sent <code>amount</code>.</li> <li>The sum of all the balances decremented MUST be equal to the total sent <code>amount</code>.</li> <li>A <code>Sent</code> event MUST be emitted for every <em>holder</em> and <em>recipient</em> pair with the corresponding amount for each pair.</li> <li>The sum of all the amounts from the <code>Sent</code> event MUST be equal to the total sent <code>amount</code>.</li> </ul> <p><em>NOTE</em>: Mechanisms such as applying a fee on a send is considered as a send to multiple <em>recipients</em>: the intended <em>recipient</em> and the fee <em>recipient</em>.</p> <p><em>NOTE</em>: Movements of tokens MAY be chained. For example, if a contract upon receiving tokens sends them further to another address. In this case, the previous send rules apply to each send, in order.</p> <p><em>NOTE</em>: Sending an amount of zero (<code>0</code>) tokens is valid and MUST be treated as a regular send.</p> <p><em>Implementation Requirement</em>:</p> <ul> <li>The token contract MUST call the <code>tokensToSend</code> hook <em>before</em> updating the state.</li> <li>The token contract MUST call the <code>tokensReceived</code> hook <em>after</em> updating the state.<br /> I.e., <code>tokensToSend</code> MUST be called first, then the balances MUST be updated to reflect the send, and finally <code>tokensReceived</code> MUST be called <em>afterward</em>. Thus a <code>balanceOf</code> call within <code>tokensToSend</code> returns the balance of the address <em>before</em> the send and a <code>balanceOf</code> call within <code>tokensReceived</code> returns the balance of the address <em>after</em> the send.</li> </ul> <p><em>NOTE</em>: The <code>data</code> field contains information provided by the <em>holder</em>—similar to the data field in a regular ether send transaction. The <code>tokensToSend()</code> hook, the <code>tokensReceived()</code>, or both MAY use the information to decide if they wish to reject the transaction.</p> <p><em>NOTE</em>: The <code>operatorData</code> field is analogous to the <code>data</code> field except it SHALL be provided by the <em>operator</em>.</p> <p>The <code>operatorData</code> MUST only be provided by the <em>operator</em>. It is intended more for logging purposes and particular cases. (Examples include payment references, cheque numbers, countersignatures and more.) In most of the cases the recipient would ignore the <code>operatorData</code>, or at most, it would log the <code>operatorData</code>.</p> <p><strong><code>Sent</code> event</strong> <a id="sent"></a></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"> Sent</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"> 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-support"> bytes</span><span class="z-variable"> data</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> operatorData</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>Indicate a send of <code>amount</code> of tokens from the <code>from</code> address to the <code>to</code> address by the <code>operator</code> address.</p> <p><em>NOTE</em>: This event MUST NOT be emitted outside of a send or an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> transfer process.</p> <blockquote> <p><small><strong>parameters</strong></small><br /> <small><code>operator</code>: Address which triggered the send.</small><br /> <small><code>from</code>: <em>Holder</em> whose tokens were sent.</small><br /> <small><code>to</code>: Recipient of the tokens.</small><br /> <small><code>amount</code>: Number of tokens sent.</small><br /> <small><code>data</code>: Information provided by the <em>holder</em>.</small><br /> <small><code>operatorData</code>: Information provided by the <em>operator</em>.</small></p> </blockquote> <p>The <code>send</code> and <code>operatorSend</code> functions described below MUST be implemented to send tokens. Token contracts MAY implement other functions to send tokens.</p> <p><strong><code>send</code> function</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"> send</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"> calldata</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>Send the <code>amount</code> of tokens from the address <code>msg.sender</code> to the address <code>to</code>.</p> <p>The <em>operator</em> and the <em>holder</em> MUST both be the <code>msg.sender</code>.</p> <blockquote> <p><small><strong>identifier:</strong> <code>9bd9bbc6</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>to</code>: Recipient of the tokens.</small><br /> <small><code>amount</code>: Number of tokens to send.</small><br /> <small><code>data</code>: Information provided by the <em>holder</em>.</small></p> </blockquote> <p><strong><code>operatorSend</code> function</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"> operatorSend</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></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></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operatorData</span></span> <span class="giallo-l"><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>Send the <code>amount</code> of tokens on behalf of the address <code>from</code> to the address <code>to</code>.</p> <p><em>Reminder</em>: If the <em>operator</em> address is not an authorized operator of the <code>from</code> address, then the send process MUST <code>revert</code>.</p> <p><em>NOTE</em>: <code>from</code> and <code>msg.sender</code> MAY be the same address. I.e., an address MAY call <code>operatorSend</code> for itself. This call MUST be equivalent to <code>send</code> with the addition that the <em>operator</em> MAY specify an explicit value for <code>operatorData</code> (which cannot be done with the <code>send</code> function).</p> <blockquote> <p><small><strong>identifier:</strong> <code>62ad1b83</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>from</code>: <em>Holder</em> whose tokens are being sent.</small><br /> <small><code>to</code>: Recipient of the tokens.</small><br /> <small><code>amount</code>: Number of tokens to send.</small><br /> <small><code>data</code>: Information provided by the <em>holder</em>.</small><br /> <small><code>operatorData</code>: Information provided by the <em>operator</em>.</small></p> </blockquote> <h4 id="minting-tokens"><strong>Minting Tokens</strong></h4> <p>Minting tokens is the act of producing new tokens. <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> intentionally does not define specific functions to mint tokens. This intent comes from the wish not to limit the use of the <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> standard as the minting process is generally specific for every token.</p> <p>Nonetheless, the rules below MUST be respected when minting for a <em>recipient</em>:</p> <ul> <li> <p>Tokens MAY be minted for any <em>recipient</em> address (except <code>0x0</code>).</p> </li> <li> <p>The total supply MUST be increased by the amount of tokens minted.</p> </li> <li> <p>The balance of <code>0x0</code> MUST NOT be decreased.</p> </li> <li> <p>The balance of the <em>recipient</em> MUST be increased by the amount of tokens minted.</p> </li> <li> <p>The token contract MUST emit a <code>Minted</code> event with the correct values as defined in the <a href="https://wg-eips.ritovision.com/777/#minted"><code>Minted</code> Event</a>.</p> </li> <li> <p>The token contract MUST call the <code>tokensReceived</code> hook of the <em>recipient</em> if the <em>recipient</em> registers an <code>ERC777TokensRecipient</code> implementation via <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a>.</p> </li> <li> <p>The <code>data</code> and <code>operatorData</code> MUST be immutable during the entire mint process—hence the same <code>data</code> and <code>operatorData</code> MUST be used to call the <code>tokensReceived</code> hook and emit the <code>Minted</code> event.</p> </li> </ul> <p>The token contract MUST <code>revert</code> when minting in any of the following cases:</p> <ul> <li>The resulting <em>recipient</em> balance after the mint is not a multiple of the <em>granularity</em> defined by the token contract.</li> <li>The <em>recipient</em> is a contract, and it does not implement the <code>ERC777TokensRecipient</code> interface via <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a>.</li> <li>The address of the <em>recipient</em> is <code>0x0</code>.</li> <li>The <code>tokensReceived</code> hook of the <em>recipient</em> <code>revert</code>s.</li> </ul> <p><em>NOTE</em>: The initial token supply at the creation of the token contract MUST be considered as minting for the amount of the initial supply to the address(es) receiving the initial supply. This means one or more <code>Minted</code> events must be emitted and the <code>tokensReceived</code> hook of the recipient(s) MUST be called.</p> <p><em><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> compatibility requirement</em>:<br /> While a <code>Sent</code> event MUST NOT be emitted when minting, if the token contract is <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> backward compatible, a <code>Transfer</code> event with the <code>from</code> parameter set to <code>0x0</code> SHOULD be emitted as defined in the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard.</p> <p>The token contract MAY mint tokens for multiple <em>recipients</em> at once. In this case:</p> <ul> <li>The previous mint rules MUST apply to all the <em>recipients</em>.</li> <li>The sum of all the balances incremented MUST be equal to the total minted amount.</li> <li>A <code>Minted</code> event MUST be emitted for every <em>recipient</em> with the corresponding amount for each <em>recipient</em>.</li> <li>The sum of all the amounts from the <code>Minted</code> event MUST be equal to the total minted <code>amount</code>.</li> </ul> <p><em>NOTE</em>: Minting an amount of zero (<code>0</code>) tokens is valid and MUST be treated as a regular mint.</p> <p><em>NOTE</em>: While during a send or a burn, the data is provided by the <em>holder</em>, it is inapplicable for a mint. In this case the data MAY be provided by the token contract or the <em>operator</em>, for example to ensure a successful minting to a <em>holder</em> expecting specific data.</p> <p><em>NOTE</em>: The <code>operatorData</code> field contains information provided by the <em>operator</em>—similar to the data field in a regular ether send transaction. The <code>tokensReceived()</code> hooks MAY use the information to decide if it wish to reject the transaction.</p> <p><strong><code>Minted</code> event</strong> <a id="minted"></a></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"> Minted</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"> 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-support"> bytes</span><span class="z-variable"> data</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> operatorData</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>Indicate the minting of <code>amount</code> of tokens to the <code>to</code> address by the <code>operator</code> address.</p> <p><em>NOTE</em>: This event MUST NOT be emitted outside of a mint process.</p> <blockquote> <p><small><strong>parameters</strong></small><br /> <small><code>operator</code>: Address which triggered the mint.</small><br /> <small><code>to</code>: Recipient of the tokens.</small><br /> <small><code>amount</code>: Number of tokens minted.</small><br /> <small><code>data</code>: Information provided for the <em>recipient</em>.</small><br /> <small><code>operatorData</code>: Information provided by the <em>operator</em>.</small></p> </blockquote> <h4 id="burning-tokens"><strong>Burning Tokens</strong></h4> <p>Burning tokens is the act of destroying existing tokens. <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> explicitly defines two functions to burn tokens (<code>burn</code> and <code>operatorBurn</code>). These functions facilitate the integration of the burning process in wallets and dapps. However, the token contract MAY prevent some or all <em>holders</em> from burning tokens for any reason. The token contract MAY also define other functions to burn tokens.</p> <p>The rules below MUST be respected when burning the tokens of a <em>holder</em>:</p> <ul> <li> <p>Tokens MAY be burned from any <em>holder</em> address (except <code>0x0</code>).</p> </li> <li> <p>The total supply MUST be decreased by the amount of tokens burned.</p> </li> <li> <p>The balance of <code>0x0</code> MUST NOT be increased.</p> </li> <li> <p>The balance of the <em>holder</em> MUST be decreased by amount of tokens burned.</p> </li> <li> <p>The token contract MUST emit a <code>Burned</code> event with the correct values as defined in the <a href="https://wg-eips.ritovision.com/777/#burned"><code>Burned</code> Event</a>.</p> </li> <li> <p>The token contract MUST call the <code>tokensToSend</code> hook of the <em>holder</em> if the <em>holder</em> registers an <code>ERC777TokensSender</code> implementation via <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a>.</p> </li> <li> <p>The <code>operatorData</code> MUST be immutable during the entire burn process—hence the same <code>operatorData</code> MUST be used to call the <code>tokensToSend</code> hook and emit the <code>Burned</code> event.</p> </li> </ul> <p>The token contract MUST <code>revert</code> when burning in any of the following cases:</p> <ul> <li> <p>The <em>operator</em> address is not an authorized operator for the <em>holder</em>.</p> </li> <li> <p>The resulting <em>holder</em> balance after the burn is not a multiple of the <em>granularity</em> defined by the token contract.</p> </li> <li> <p>The balance of <em>holder</em> is inferior to the amount of tokens to burn (i.e., resulting in a negative balance for the <em>holder</em>).</p> </li> <li> <p>The address of the <em>holder</em> is <code>0x0</code>.</p> </li> <li> <p>The <code>tokensToSend</code> hook of the <em>holder</em> <code>revert</code>s.</p> </li> </ul> <p><em><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> compatibility requirement</em>:<br /> While a <code>Sent</code> event MUST NOT be emitted when burning; if the token contract is <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> enabled, a <code>Transfer</code> event with the <code>to</code> parameter set to <code>0x0</code> SHOULD be emitted. The <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard does not define the concept of burning tokens, but this is a commonly accepted practice.</p> <p>The token contract MAY burn tokens for multiple <em>holders</em> at once. In this case:</p> <ul> <li>The previous burn rules MUST apply to each <em>holders</em>.</li> <li>The sum of all the balances decremented MUST be equal to the total burned amount.</li> <li>A <code>Burned</code> event MUST be emitted for every <em>holder</em> with the corresponding amount for each <em>holder</em>.</li> <li>The sum of all the amounts from the <code>Burned</code> event MUST be equal to the total burned <code>amount</code>.</li> </ul> <p><em>NOTE</em>: Burning an amount of zero (<code>0</code>) tokens is valid and MUST be treated as a regular burn.</p> <p><em>NOTE</em>: The <code>data</code> field contains information provided by the holder—similar to the data field in a regular ether send transaction. The <code>tokensToSend()</code> hook, the <code>tokensReceived()</code>, or both MAY use the information to decide if they wish to reject the transaction.</p> <p><em>NOTE</em>: The <code>operatorData</code> field is analogous to the <code>data</code> field except it SHALL be provided by the <em>operator</em>.</p> <p><strong><code>Burned</code> event</strong> <a id="burned"></a></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"> Burned</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"> 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></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-support"> bytes</span><span class="z-variable"> operatorData</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre> <p>Indicate the burning of <code>amount</code> of tokens from the <code>from</code> address by the <code>operator</code> address.</p> <p><em>NOTE</em>: This event MUST NOT be emitted outside of a burn process.</p> <blockquote> <p><small><strong>parameters</strong></small><br /> <small><code>operator</code>: Address which triggered the burn.</small><br /> <small><code>from</code>: <em>Holder</em> whose tokens were burned.</small><br /> <small><code>amount</code>: Number of tokens burned.</small><br /> <small><code>data</code>: Information provided by the <em>holder</em>.</small><br /> <small><code>operatorData</code>: Information provided by the <em>operator</em>.</small></p> </blockquote> <p>The <code>burn</code> and <code>operatorBurn</code> functions described below MUST be implemented to burn tokens. Token contracts MAY implement other functions to burn tokens.</p> <p><strong><code>burn</code> function</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"> burn</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"> calldata</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>Burn the <code>amount</code> of tokens from the address <code>msg.sender</code>.</p> <p>The <em>operator</em> and the <em>holder</em> MUST both be the <code>msg.sender</code>.</p> <blockquote> <p><small><strong>identifier:</strong> <code>fe9d9303</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>amount</code>: Number of tokens to burn.</small><br /> <small><code>data</code>: Information provided by the <em>holder</em>.</small></p> </blockquote> <p><strong><code>operatorBurn</code> function</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"> operatorBurn</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"> amount</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></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operatorData</span></span> <span class="giallo-l"><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>Burn the <code>amount</code> of tokens on behalf of the address <code>from</code>.</p> <p><em>Reminder</em>: If the <em>operator</em> address is not an authorized operator of the <code>from</code> address, then the burn process MUST <code>revert</code>.</p> <blockquote> <p><small><strong>identifier:</strong> <code>fc673c4f</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>from</code>: <em>Holder</em> whose tokens will be burned.</small><br /> <small><code>amount</code>: Number of tokens to burn.</small><br /> <small><code>data</code>: Information provided by the <em>holder</em>.</small><br /> <small><code>operatorData</code>: Information provided by the <em>operator</em>.</small></p> </blockquote> <p><em>NOTE</em>: The <em>operator</em> MAY pass any information via <code>operatorData</code>. The <code>operatorData</code> MUST only be provided by the <em>operator</em>.</p> <p><em>NOTE</em>: <code>from</code> and <code>msg.sender</code> MAY be the same address. I.e., an address MAY call <code>operatorBurn</code> for itself. This call MUST be equivalent to <code>burn</code> with the addition that the <em>operator</em> MAY specify an explicit value for <code>operatorData</code> (which cannot be done with the <code>burn</code> function).</p> <h4 id="erc777tokenssender-and-the-tokenstosend-hook"><strong><code>ERC777TokensSender</code> And The <code>tokensToSend</code> Hook</strong></h4> <p>The <code>tokensToSend</code> hook notifies of any request to decrement the balance (send and burn) for a given <em>holder</em>. Any address (regular or contract) wishing to be notified of token debits from their address MAY register the address of a contract implementing the <code>ERC777TokensSender</code> interface described below via <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a>.</p> <blockquote> <p>This is done by calling the <code>setInterfaceImplementer</code> function on the <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> registry with the <em>holder</em> address as the address, the <code>keccak256</code> hash of <code>ERC777TokensSender</code> (<code>0x29ddb589b1fb5fc7cf394961c1adf5f8c6454761adf795e67fe149f658abe895</code>) as the interface hash, and the address of the contract implementing the <code>ERC777TokensSender</code> as the implementer.</p> </blockquote> <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"> ERC777TokensSender</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokensToSend</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-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></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> userData</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"> operatorData</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> <p><em>NOTE</em>: A regular address MAY register a different address—the address of a contract—implementing the interface on its behalf. A contract MAY register either its address or the address of another contract but said address MUST implement the interface on its behalf.</p> <p><strong><code>tokensToSend</code></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"> tokensToSend</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-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></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> userData</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"> operatorData</span></span> <span class="giallo-l"><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>Notify a request to send or burn (if <code>to</code> is <code>0x0</code>) an <code>amount</code> tokens from the <code>from</code> address to the <code>to</code> address by the <code>operator</code> address.</p> <p><em>NOTE</em>: This function MUST NOT be called outside of a burn, send or <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> transfer process.</p> <blockquote> <p><small><strong>identifier:</strong> <code>75ab9782</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>operator</code>: Address which triggered the balance decrease (through sending or burning).</small><br /> <small><code>from</code>: <em>Holder</em> whose tokens were sent.</small><br /> <small><code>to</code>: Recipient of the tokens for a send (or <code>0x0</code> for a burn).</small><br /> <small><code>amount</code>: Number of tokens the <em>holder</em> balance is decreased by.</small><br /> <small><code>data</code>: Information provided by the <em>holder</em>.</small><br /> <small><code>operatorData</code>: Information provided by the <em>operator</em>.</small></p> </blockquote> <p>The following rules apply when calling the <code>tokensToSend</code> hook:</p> <ul> <li> <p>The <code>tokensToSend</code> hook MUST be called for every send and burn processes.</p> </li> <li> <p>The <code>tokensToSend</code> hook MUST be called <em>before</em> the state is updated—i.e. <em>before</em> the balance is decremented.</p> </li> <li> <p><code>operator</code> MUST be the address which triggered the send or burn process.</p> </li> <li> <p><code>from</code> MUST be the address of the <em>holder</em> whose tokens are sent or burned.</p> </li> <li> <p><code>to</code> MUST be the address of the <em>recipient</em> which receives the tokens for a send.</p> </li> <li> <p><code>to</code> MUST be <code>0x0</code> for a burn.</p> </li> <li> <p><code>amount</code> MUST be the number of tokens the <em>holder</em> sent or burned.</p> </li> <li> <p><code>data</code> MUST contain the extra information (if any) provided to the send or the burn process.</p> </li> <li> <p><code>operatorData</code> MUST contain the extra information provided by the address which triggered the decrease of the balance (if any).</p> </li> <li> <p>The <em>holder</em> MAY block a send or burn process by <code>revert</code>ing. (I.e., reject the withdrawal of tokens from its account.)</p> </li> </ul> <p><em>NOTE</em>: Multiple <em>holders</em> MAY use the same implementation of <code>ERC777TokensSender</code>.</p> <p><em>NOTE</em>: An address can register at most one implementation at any given time for all <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> tokens. Hence the <code>ERC777TokensSender</code> MUST expect to be called by different token contracts. The <code>msg.sender</code> of the <code>tokensToSend</code> call is expected to be the address of the token contract.</p> <p><em><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> compatibility requirement</em>:<br /> This hook takes precedence over <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and MUST be called (if registered) when calling <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>'s <code>transfer</code> and <code>transferFrom</code> event. When called from a <code>transfer</code>, <code>operator</code> MUST be the same value as the <code>from</code>. When called from a <code>transferFrom</code>, <code>operator</code> MUST be the address which issued the <code>transferFrom</code> call.</p> <h4 id="erc777tokensrecipient-and-the-tokensreceived-hook"><strong><code>ERC777TokensRecipient</code> And The <code>tokensReceived</code> Hook</strong></h4> <p>The <code>tokensReceived</code> hook notifies of any increment of the balance (send and mint) for a given <em>recipient</em>. Any address (regular or contract) wishing to be notified of token credits to their address MAY register the address of a contract implementing the <code>ERC777TokensRecipient</code> interface described below via <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a>.</p> <blockquote> <p>This is done by calling the <code>setInterfaceImplementer</code> function on the <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> registry with the <em>recipient</em> address as the address, the <code>keccak256</code> hash of <code>ERC777TokensRecipient</code> (<code>0xb281fc8c12954d22544db45de3159a39272895b169a852b314f9cc762e44c53b</code>) as the interface hash, and the address of the contract implementing the <code>ERC777TokensRecipient</code> as the implementer.</p> </blockquote> <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"> ERC777TokensRecipient</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokensReceived</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-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></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></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operatorData</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> <p>If the <em>recipient</em> is a contract, which has not registered an <code>ERC777TokensRecipient</code> implementation; then the token contract:</p> <ul> <li> <p>MUST <code>revert</code> if the <code>tokensReceived</code> hook is called from a mint or send call.</p> </li> <li> <p>SHOULD continue processing the transaction if the <code>tokensReceived</code> hook is called from an ERC-20 <code>transfer</code> or <code>transferFrom</code> call.</p> </li> </ul> <p><em>NOTE</em>: A regular address MAY register a different address—the address of a contract—implementing the interface on its behalf. A contract MUST register either its address or the address of another contract but said address MUST implement the interface on its behalf.</p> <p><strong><code>tokensReceived</code></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"> tokensReceived</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-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></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></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operatorData</span></span> <span class="giallo-l"><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>Notify a send or mint (if <code>from</code> is <code>0x0</code>) of <code>amount</code> tokens from the <code>from</code> address to the <code>to</code> address by the <code>operator</code> address.</p> <p><em>NOTE</em>: This function MUST NOT be called outside of a mint, send or <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> transfer process.</p> <blockquote> <p><small><strong>identifier:</strong> <code>0023de29</code></small><br /> <small><strong>parameters</strong></small><br /> <small><code>operator</code>: Address which triggered the balance increase (through sending or minting).</small><br /> <small><code>from</code>: <em>Holder</em> whose tokens were sent (or <code>0x0</code> for a mint).</small><br /> <small><code>to</code>: Recipient of the tokens.</small><br /> <small><code>amount</code>: Number of tokens the <em>recipient</em> balance is increased by.</small><br /> <small><code>data</code>: Information provided by the <em>holder</em>.</small><br /> <small><code>operatorData</code>: Information provided by the <em>operator</em>.</small></p> </blockquote> <p>The following rules apply when calling the <code>tokensReceived</code> hook:</p> <ul> <li> <p>The <code>tokensReceived</code> hook MUST be called for every send and mint processes.</p> </li> <li> <p>The <code>tokensReceived</code> hook MUST be called <em>after</em> the state is updated—i.e. <em>after</em> the balance is incremented.</p> </li> <li> <p><code>operator</code> MUST be the address which triggered the send or mint process.</p> </li> <li> <p><code>from</code> MUST be the address of the <em>holder</em> whose tokens are sent for a send.</p> </li> <li> <p><code>from</code> MUST be <code>0x0</code> for a mint.</p> </li> <li> <p><code>to</code> MUST be the address of the <em>recipient</em> which receives the tokens.</p> </li> <li> <p><code>amount</code> MUST be the number of tokens the <em>recipient</em> sent or minted.</p> </li> <li> <p><code>data</code> MUST contain the extra information (if any) provided to the send or the mint process.</p> </li> <li> <p><code>operatorData</code> MUST contain the extra information provided by the address which triggered the increase of the balance (if any).</p> </li> <li> <p>The <em>holder</em> MAY block a send or mint process by <code>revert</code>ing. (I.e., reject the reception of tokens.)</p> </li> </ul> <p><em>NOTE</em>: Multiple <em>holders</em> MAY use the same implementation of <code>ERC777TokensRecipient</code>.</p> <p><em>NOTE</em>: An address can register at most one implementation at any given time for all <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> tokens. Hence the <code>ERC777TokensRecipient</code> MUST expect to be called by different token contracts. The <code>msg.sender</code> of the <code>tokensReceived</code> call is expected to be the address of the token contract.</p> <p><em><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> compatibility requirement</em>:<br /> This hook takes precedence over <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and MUST be called (if registered) when calling <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>'s <code>transfer</code> and <code>transferFrom</code> event. When called from a <code>transfer</code>, <code>operator</code> MUST be the same value as the <code>from</code>. When called from a <code>transferFrom</code>, <code>operator</code> MUST be the address which issued the <code>transferFrom</code> call.</p> <h4 id="note-on-gas-consumption"><strong>Note On Gas Consumption</strong></h4> <p>Dapps and wallets SHOULD first estimate the gas required when sending, minting, or burning tokens—using <a rel="external" href="https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_estimategas"><code>eth_estimateGas</code></a>—to avoid running out of gas during the transaction.</p> <h3 id="logo">Logo</h3> <table><thead><tr><th style="text-align: right"><strong>Image</strong></th><th style="text-align: center"><img src="https://wg-eips.ritovision.com/777/./assets/logo/png/ERC-777-logo-beige-48px.png" alt="beige logo" /></th><th style="text-align: center"><img src="https://wg-eips.ritovision.com/777/./assets/logo/png/ERC-777-logo-white-48px.png" alt="white logo" /></th><th style="text-align: center"><img src="https://wg-eips.ritovision.com/777/./assets/logo/png/ERC-777-logo-light_grey-48px.png" alt="light grey logo" /></th><th style="text-align: center"><img src="https://wg-eips.ritovision.com/777/./assets/logo/png/ERC-777-logo-dark_grey-48px.png" alt="dark grey logo" /></th><th style="text-align: center"><img src="https://wg-eips.ritovision.com/777/./assets/logo/png/ERC-777-logo-black-48px.png" alt="black logo" /></th></tr></thead><tbody> <tr><td style="text-align: right"><strong>Color</strong></td><td style="text-align: center">beige</td><td style="text-align: center">white</td><td style="text-align: center">light grey</td><td style="text-align: center">dark grey</td><td style="text-align: center">black</td></tr> <tr><td style="text-align: right"><strong>Hex</strong></td><td style="text-align: center"><code>#C99D66</code></td><td style="text-align: center"><code>#FFFFFF</code></td><td style="text-align: center"><code>#EBEFF0</code></td><td style="text-align: center"><code>#3C3C3D</code></td><td style="text-align: center"><code>#000000</code></td></tr> </tbody></table> <p>The logo MAY be used, modified and adapted to promote valid <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> token implementations and <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> compliant technologies such as wallets and dapps.</p> <p><a href="https://wg-eips.ritovision.com/777/">ERC-777</a> token contract authors MAY create a specific logo for their token based on this logo.</p> <p>The logo MUST NOT be used to advertise, promote or associate in any way technology—such as tokens—which is not <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> compliant.</p> <p>The logo for the standard can be found in the <a rel="external" href="https://github.com/ethereum/EIPs/tree/master/assets/eip-777/logo"><code>/assets/eip-777/logo</code></a> folder in <code>SVG</code> and <code>PNG</code> formats. The <code>PNG</code> version of the logo offers a few sizes in pixels. If needed, other sizes MAY be created by converting from <code>SVG</code> into <code>PNG</code>.</p> <h2 id="rationale">Rationale</h2> <p>The principal intent for this standard is to solve some of the shortcomings of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> while maintaining backward compatibility with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, and avoiding the problems and vulnerabilities of <a rel="external" href="https://github.com/ethereum/EIPs/issues/223">EIP-223</a>.</p> <p>Below are the rationales for the decisions regarding the main aspects of the standards.</p> <p><em>NOTE</em>: Jacques Dafflon (<a rel="external" href="https://github.com/0xjac">0xjac</a>), one of the authors of the standard, conjointly wrote his <a rel="external" href="https://github.com/0xjac/master-thesis">master thesis</a> on the standard, which goes in more details than could reasonably fit directly within the standard, and can provide further clarifications regarding certain aspects or decisions.</p> <h3 id="lifecycle">Lifecycle</h3> <p>More than just sending tokens, <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> defines the entire lifecycle of a token, starting with the minting process, followed by the sending process and terminating with the burn process.</p> <p>Having a lifecycle clearly defined is important for consistency and accuracy, especially when value is derived from scarcity. In contrast when looking at some <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens, a discrepancy can be observed between the value returned by the <code>totalSupply</code> and the actual circulating supply, as the standard does not clearly define a process to create and destroy tokens.</p> <h3 id="data">Data</h3> <p>The mint, send and burn processes can all make use of a <code>data</code> and <code>operatorData</code> fields which are passed to any movement (mint, send or burn). Those fields may be empty for simple use cases, or they may contain valuable information related to the movement of tokens, similar to information attached to a bank transfer by the sender or the bank itself.</p> <p>The use of a <code>data</code> field is equally present in other standard proposals such as <a rel="external" href="https://github.com/ethereum/EIPs/issues/223">EIP-223</a>, and was requested by multiple members of the community who reviewed this standard.</p> <h3 id="hooks">Hooks</h3> <p>In most cases, <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> requires two calls to safely transfer tokens to a contract without locking them. A call from the sender, using the <code>approve</code> function and a call from the recipient using <code>transferFrom</code>. Furthermore, this requires extra communication between the parties which is not clearly defined. Finally, holders can get confused between <code>transfer</code> and <code>approve</code>/<code>transferFrom</code>. Using the former to transfer tokens to a contract will most likely result in locked tokens.</p> <p>Hooks allow streamlining of the sending process and offer a single way to send tokens to any recipient. Thanks to the <code>tokensReceived</code> hook, contracts are able to react and prevent locking tokens upon reception.</p> <h4 id="greater-control-for-holders"><strong>Greater Control For Holders</strong></h4> <p>The <code>tokensReceived</code> hook also allows holders to reject the reception of some tokens. This gives greater control to holders who can accept or reject incoming tokens based on some parameters, for example located in the <code>data</code> or <code>operatorData</code> fields.</p> <p>Following the same intentions and based on suggestions from the community, the <code>tokensToSend</code> hook was added to give control over and prevent the movement of outgoing tokens.</p> <h4 id="erc-1820-registry"><strong><a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> Registry</strong></h4> <p>The <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> Registry allows holders to register their hooks. Other alternatives were examined beforehand to link hooks and holders.</p> <p>The first was for hooks to be defined at the sender's or recipient's address. This approach is similar to <a rel="external" href="https://github.com/ethereum/EIPs/issues/223">EIP-223</a> which proposes a <code>tokenFallback</code> function on recipient contracts to be called when receiving tokens, but improves on it by relying on <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> for interface detection. While straightforward to implement, this approach imposes several limitations. In particular, the sender and recipient must be contracts in order to provide their implementation of the hooks. Preventing externally owned addresses to benefit from hooks. Existing contracts have a strong probability not to be compatible, as they undoubtedly were unaware and do not define the new hooks. Consequently existing smart contract infrastructure such as multisig wallets which potentially hold large amounts of ether and tokens would need to be migrated to new updated contracts.</p> <p>The second approach considered was to use <a rel="external" href="https://github.com/ethereum/EIPs/issues/672">ERC-672</a> which offered pseudo-introspection for addresses using reverse-ENS. However, this approach relied heavily on ENS, on top of which reverse lookup would need to be implemented. Analysis of this approach promptly revealed a certain degree of complexity and security concerns which would transcend the benefits of approach.</p> <p>The third solution—used in this standard—is to rely on a unique registry where any address can register the addresses of contracts implementing the hooks on its behalf. This approach has the advantage that externally owned accounts and contracts can benefit from hooks, including existing contracts which can rely on hooks deployed on proxy contracts.</p> <p>The decision was made to keep this registry in a separate EIP, as to not over complicate this standard. More importantly, the registry is designed in a flexible fashion, such that other EIPs and smart contract infrastructures can benefit from it for their own use cases, outside the realm of <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> and tokens. The first proposal for this registry was <a href="https://wg-eips.ritovision.com/820/">ERC-820</a>. Unfortunately, issues emanating from upgrades in the Solidity language to versions 0.5 and above resulted in a bug in a separated part of the registry, which required changes. This was discovered right after the last call period. Attempts made to avoid creating a separate EIP, such as <a rel="external" href="https://github.com/ethereum/EIPs/pull/1758">ERC-820a</a>, were rejected. Hence the standard for the registry used for <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> became <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a>. <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> and <a href="https://wg-eips.ritovision.com/820/">ERC-820</a> are functionally equivalent. <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> simply contains the fix for newer versions of Solidity.</p> <h3 id="operators-1">Operators</h3> <p>The standard defines the concept of operators as any address which moves tokens. While intuitively every address moves its own tokens, separating the concepts of holder and operator allows for greater flexibility. Primarily, this originates from the fact that the standard defines a mechanism for holders to let other addresses become their operators. Moreover, unlike the approve calls in <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> where the role of an approved address is not clearly defined, <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> details the intent of and interactions with operators, including an obligation for operators to be approved, and an irrevocable right for any holder to revoke operators.</p> <h4 id="default-operators"><strong>Default Operators</strong></h4> <p>Default operators were added based on community demand for pre-approved operators. That is operators which are approved for all holders by default. For obvious security reasons, the list of default operators is defined at the token contract creation time, and cannot be changed. Any holder still has the right to revoke default operators. One of the obvious advantages of default operators is to allow ether-less movements of tokens. Default operators offer other usability advantages, such as allowing token providers to offer functionality in a modular way, and to reduce the complexity for holders to use features provided through operators.</p> <h2 id="backward-compatibility">Backward Compatibility</h2> <p>This EIP does not introduce backward incompatibilities and is backward compatible with the older <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token standard.</p> <p>This EIP does not use <code>transfer</code> and <code>transferFrom</code> and uses <code>send</code> and <code>operatorSend</code> to avoid confusion and mistakes when deciphering which token standard is being used.</p> <p>This standard allows the implementation of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> functions <code>transfer</code>, <code>transferFrom</code>, <code>approve</code> and <code>allowance</code> alongside to make a token fully compatible with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>.</p> <p>The token MAY implement <code>decimals()</code> for backward compatibility with <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. If implemented, it MUST always return <code>18</code>.</p> <p>Therefore a token contract MAY implement both <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> in parallel. The specification of the <code>view</code> functions (such as <code>name</code>, <code>symbol</code>, <code>balanceOf</code>, <code>totalSupply</code>) and internal data (such as the mapping of balances) overlap without problems. Note however that the following functions are mandatory in <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> and MUST be implemented: <code>name</code>, <code>symbol</code> <code>balanceOf</code> and <code>totalSupply</code> (<code>decimals</code> is not part of the <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> standard).</p> <p>The state-modifying functions from both standards are decoupled and can operate independently from each other. Note that <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> functions SHOULD be limited to only being called from old contracts.</p> <p>If the token implements <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, it MUST register the <code>ERC20Token</code> interface with its own address via <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a>. This is done by calling the <code>setInterfaceImplementer</code> function on the ERC-1820 registry with the token contract address as both the address and the implementer and the <code>keccak256</code> hash of <code>ERC20Token</code> (<code>0xaea199e31a596269b42cdafd93407f14436db6e4cad65417994c2eb37381e05a</code>) as the interface hash.</p> <p>If the contract has a switch to enable or disable ERC-20 functions, every time the switch is triggered, the token MUST register or unregister the <code>ERC20Token</code> interface for its own address accordingly via ERC1820. Unregistering implies calling the <code>setInterfaceImplementer</code> with the token contract address as the address, the <code>keccak256</code> hash of <code>ERC20Token</code> as the interface hash and <code>0x0</code> as the implementer. (See <a href="https://wg-eips.ritovision.com/1820/#set-an-interface-for-an-address">Set An Interface For An Address</a> in <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> for more details.)</p> <p>The difference for new contracts implementing <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> is that <code>tokensToSend</code> and <code>tokensReceived</code> hooks take precedence over <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. Even with an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> <code>transfer</code> and <code>transferFrom</code> call, the token contract MUST check via <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> if the <code>from</code> and the <code>to</code> address implement <code>tokensToSend</code> and <code>tokensReceived</code> hook respectively. If any hook is implemented, it MUST be called. Note that when calling <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> <code>transfer</code> on a contract, if the contract does not implement <code>tokensReceived</code>, the <code>transfer</code> call SHOULD still be accepted even if this means the tokens will probably be locked.</p> <p>The table below summarizes the different actions the token contract MUST take when sending, minting and transferring token via <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> and <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>:</p> <table> <tr> <th align="right">ERC1820</th> <th><code>to</code> address</th> <th align="center">ERC777 Sending And Minting</th> <th align="center">ERC20 <code>transfer</code>/<code>transferFrom</code></th> </tr> <tr> <td rowspan="2" align="right"> <code>ERC777TokensRecipient</code><br/>registered </td> <td>regular address</td> <td colspan="2" rowspan="2" align="center"> MUST call <code>tokensReceived</code> </td> </tr> <tr> <td>contract</td> </tr> <tr> <td rowspan="2" align="right"> <code>ERC777TokensRecipient</code><br/>not registered </td> <td>regular address</td> <td colspan="2" align="center">continue</td> </tr> <tr> <td>contract</td> <td align="center">MUST <code>revert</code></td> <td align="center">SHOULD continue^{<a id="continue-footnote-backlink" href="#continue-footnote">1</a>}</td> </tr> </table> <blockquote> <p><a href="#continue-footnote-backlink"><small id="continue-footnote">1.</small></a> <small>The transaction SHOULD continue for clarity as ERC20 is not aware of hooks.</small><br /> <small>However, this can result in accidentally locked tokens.</small> <small>If avoiding accidentally locked tokens is paramount, the transaction MAY <code>revert</code>.</small></p> </blockquote> <p>There is no particular action to take if <code>tokensToSend</code> is not implemented. The movement MUST proceed and only be canceled if another condition is not respected such as lack of funds or a <code>revert</code> in <code>tokensReceived</code> (if present).</p> <p>During a send, mint and burn, the respective <code>Sent</code>, <code>Minted</code> and <code>Burned</code> events MUST be emitted. Furthermore, if the token contract declares that it implements <code>ERC20Token</code> via <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a>, the token contract SHOULD emit a <code>Transfer</code> event for minting and burning and MUST emit a <code>Transfer</code> event for sending (as specified in the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard). During an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>'s <code>transfer</code> or <code>transferFrom</code> functions, a valid <code>Sent</code> event MUST be emitted.</p> <p>Hence for any movement of tokens, two events MAY be emitted: an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> <code>Transfer</code> and an <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> <code>Sent</code>, <code>Minted</code> or <code>Burned</code> (depending on the type of movement). Third-party developers MUST be careful not to consider both events as separate movements. As a general rule, if an application considers the token as an ERC20 token, then only the <code>Transfer</code> event MUST be taken into account. If the application considers the token as an ERC777 token, then only the <code>Sent</code>, <code>Minted</code> and <code>Burned</code> events MUST be considered.</p> <h2 id="test-cases">Test Cases</h2> <p>The <a rel="external" href="https://github.com/0xjac/ERC777">repository with the reference implementation</a> contains all the <a rel="external" href="https://github.com/0xjac/ERC777/blob/master/test/ReferenceToken.test.js">tests</a>.</p> <h2 id="implementation">Implementation</h2> <p>The GitHub repository <a rel="external" href="https://github.com/0xjac/ERC777">0xjac/ERC777</a> contains the <a rel="external" href="https://github.com/0xjac/ERC777/blob/master/contracts/examples/ReferenceToken.sol">reference implementation</a>. The reference implementation is also available via <a rel="external" href="https://www.npmjs.com/package/erc777">npm</a> and can be installed with <code>npm install erc777</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> 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-10-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Fabian Vogelstellerhttps://github.com/frozeman Tyler Yasakahttps://github.com/tyleryasaka https://wg-eips.ritovision.com/725/

An interface for a smart contract based account with attachable data key/value store

<h2 id="abstract">Abstract</h2> <p>The following describes two standards that allow for a generic data storage in a smart contract and a generic execution through a smart contract. These can be used separately or in conjunction and can serve as building blocks for smart contract accounts, upgradable metadata, and other means.</p> <h2 id="motivation">Motivation</h2> <p>The initial motivation came out of the need to create a smart contract account system that's flexible enough to be viable long-term but also defined enough to be standardized. They are a generic set of two standardized building blocks to be used in all forms of smart contracts.</p> <p>This standard consists of two sub-standards, a generic data key/value store (<code>ERC725Y</code>) and a generic execute function (<code>ERC725X</code>). Both of these in combination allow for a very flexible and long-lasting account system. The account version of <code>ERC725</code> is standardized under <code>LSP0-ERC725Account</code>.</p> <p>These standards (<code>ERC725</code> X and Y) can also be used separately as <code>ERC725Y</code> can be used to enhance NFTs and Token metadata or other types of smart contracts. <code>ERC725X</code> allows for a generic execution through a smart contract, functioning as an account or actor.</p> <h2 id="specification">Specification</h2> <h3 id="ownership">Ownership</h3> <p>This contract is controlled by a single owner. The owner can be a smart contract or an external account. This standard requires <a href="https://wg-eips.ritovision.com/173/">ERC-173</a> and SHOULD implement the functions:</p> <ul> <li><code>owner() view</code></li> <li><code>transferOwnership(address newOwner)</code></li> </ul> <p>And the event:</p> <ul> <li><code>OwnershipTransferred(address indexed previousOwner, address indexed newOwner)</code></li> </ul> <hr /> <h3 id="erc725x"><code>ERC725X</code></h3> <p><strong><code>ERC725X</code></strong> interface id according to <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>: <code>0x7545acac</code>.</p> <p>Smart contracts implementing the <code>ERC725X</code> standard MUST implement the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> <code>supportsInterface(..)</code> function and MUST support the <code>ERC165</code> and <code>ERC725X</code> interface ids.</p> <h3 id="erc725x-methods"><code>ERC725X</code> Methods</h3> <p>Smart contracts implementing the <code>ERC725X</code> standard SHOULD implement all of the functions listed below:</p> <h4 id="execute">execute</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"> execute</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> operationType</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> target</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</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-storage z-type"> payable</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></code></pre> <p>Function Selector: <code>0x44c028fe</code></p> <p>Executes a call on any other smart contracts or address, transfers the blockchains native token, or deploys a new smart contract.</p> <p><em>Parameters:</em></p> <ul> <li><code>operationType</code>: the operation type used to execute.</li> <li><code>target</code>: the smart contract or address to call. <code>target</code> will be unused if a contract is created (operation types 1 and 2).</li> <li><code>value</code>: the amount of native tokens to transfer (in Wei).</li> <li><code>data</code>: the call data, or the creation bytecode of the contract to deploy.</li> </ul> <p><em>Requirements:</em></p> <ul> <li>MUST only be called by the current owner of the contract.</li> <li>MUST revert when the execution or the contract creation fails.</li> <li><code>target</code> SHOULD be address(0) in case of contract creation with <code>CREATE</code> and <code>CREATE2</code> (operation types 1 and 2).</li> <li><code>value</code> SHOULD be zero in case of <code>STATICCALL</code> or <code>DELEGATECALL</code> (operation types 3 and 4).</li> </ul> <p><em>Returns:</em> <code>bytes</code> , the returned data of the called function, or the address of the contract deployed (operation types 1 and 2).</p> <p><strong>Triggers Event:</strong> <a href="https://wg-eips.ritovision.com/725/#contractcreated">ContractCreated</a>, <a href="https://wg-eips.ritovision.com/725/#executed">Executed</a></p> <p>The following <code>operationType</code> COULD exist:</p> <ul> <li><code>0</code> for <code>CALL</code></li> <li><code>1</code> for <code>CREATE</code></li> <li><code>2</code> for <code>CREATE2</code></li> <li><code>3</code> for <code>STATICCALL</code></li> <li><code>4</code> for <code>DELEGATECALL</code> - <strong>NOTE</strong> This is a potentially dangerous operation type</li> </ul> <p>Others may be added in the future.</p> <h4 id="data-parameter">data parameter</h4> <ul> <li> <p>For operationType, <code>CALL</code>, <code>STATICCALL</code> and <code>DELEGATECALL</code> the data field can be random bytes or an abi-encoded function call.</p> </li> <li> <p>For operationType, <code>CREATE</code> the <code>data</code> field is the creation bytecode of the contract to deploy appended with the constructor argument(s) abi-encoded.</p> </li> <li> <p>For operationType, <code>CREATE2</code> the <code>data</code> field is the creation bytecode of the contract to deploy appended with:</p> <ol> <li>the constructor argument(s) abi-encoded</li> <li>a <code>bytes32</code> salt.</li> </ol> </li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>data = &lt;contract-creation-code&gt; + &lt;abi-encoded-constructor-arguments&gt; + &lt;bytes32-salt&gt;</span></span></code></pre> <blockquote> <p>See <a href="https://wg-eips.ritovision.com/1014/">EIP-1014: Skinny CREATE2</a> for more information.</p> </blockquote> <h4 id="executebatch">executeBatch</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"> executeBatch</span><span>(</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> operationsType</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"> targets</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> values</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"> datas</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">bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span></span></code></pre> <p>Function Selector: <code>0x31858452</code></p> <p>Executes a batch of calls on any other smart contracts, transfers the blockchain native token, or deploys a new smart contract.</p> <p><em>Parameters:</em></p> <ul> <li><code>operationsType</code>: the list of operations type used to execute.</li> <li><code>targets</code>: the list of addresses to call. <code>targets</code> will be unused if a contract is created (operation types 1 and 2).</li> <li><code>values</code>: the list of native token amounts to transfer (in Wei).</li> <li><code>datas</code>: the list of call data, or the creation bytecode of the contract to deploy.</li> </ul> <p><em>Requirements:</em></p> <ul> <li>Parameters array MUST have the same length.</li> <li>MUST only be called by the current owner of the contract.</li> <li>MUST revert when the execution or the contract creation fails.</li> <li><code>target</code> SHOULD be address(0) in case of contract creation with <code>CREATE</code> and <code>CREATE2</code> (operation types 1 and 2).</li> <li><code>value</code> SHOULD be zero in case of <code>STATICCALL</code> or <code>DELEGATECALL</code> (operation types 3 and 4).</li> </ul> <p><em>Returns:</em> <code>bytes[]</code> , array list of returned data of the called function, or the address(es) of the contract deployed (operation types 1 and 2).</p> <p><strong>Triggers Event:</strong> <a href="https://wg-eips.ritovision.com/725/#contractcreated">ContractCreated</a>, <a href="https://wg-eips.ritovision.com/725/#executed">Executed</a> on each call iteration</p> <h3 id="erc725x-events"><code>ERC725X</code> Events</h3> <h4 id="executed">Executed</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"> Executed</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operationType</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> target</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> value</span><span>, </span><span class="z-support">bytes4</span><span class="z-variable"> data</span><span>)</span><span>;</span></span></code></pre> <p>MUST be triggered when <code>execute</code> creates a new call using the <code>operationType</code> <code>0</code>, <code>3</code>, <code>4</code>.</p> <h4 id="contractcreated">ContractCreated</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"> ContractCreated</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operationType</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 class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> value</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> salt</span><span>)</span><span>;</span></span></code></pre> <p>MUST be triggered when <code>execute</code> creates a new contract using the <code>operationType</code> <code>1</code>, <code>2</code>.</p> <hr /> <h3 id="erc725y"><code>ERC725Y</code></h3> <p><strong><code>ERC725Y</code></strong> interface id according to <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>: <code>0x629aa694</code>.</p> <p>Smart contracts implementing the <code>ERC725Y</code> standard MUST implement the <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> <code>supportsInterface(..)</code> function and MUST support the <code>ERC165</code> and <code>ERC725Y</code> interface ids.</p> <h3 id="erc725y-methods"><code>ERC725Y</code> Methods</h3> <p>Smart contracts implementing the <code>ERC725Y</code> standard MUST implement all of the functions listed below:</p> <h4 id="getdata">getData</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"> getData</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> dataKey</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></code></pre> <p>Function Selector: <code>0x54f6127f</code></p> <p>Gets the data set for the given data key.</p> <p><em>Parameters:</em></p> <ul> <li><code>dataKey</code>: the data key which value to retrieve.</li> </ul> <p><em>Returns:</em> <code>bytes</code> , The data for the requested data key.</p> <h4 id="getdatabatch">getDataBatch</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"> getDataBatch</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"> dataKeys</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>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span></span></code></pre> <p>Function Selector: <code>0xdedff9c6</code></p> <p>Gets array of data at multiple given data keys.</p> <p><em>Parameters:</em></p> <ul> <li><code>dataKeys</code>: the data keys which values to retrieve.</li> </ul> <p><em>Returns:</em> <code>bytes[]</code> , array of data values for the requested data keys.</p> <h4 id="setdata">setData</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"> setData</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> dataKey</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> dataValue</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>Function Selector: <code>0x7f23690c</code></p> <p>Sets data as bytes in the storage for a single data key.</p> <p><em>Parameters:</em></p> <ul> <li><code>dataKey</code>: the data key which value to set.</li> <li><code>dataValue</code>: the data to store.</li> </ul> <p><em>Requirements:</em></p> <ul> <li>MUST only be called by the current owner of the contract.</li> </ul> <p><strong>Triggers Event:</strong> <a href="https://wg-eips.ritovision.com/725/#datachanged">DataChanged</a></p> <h4 id="setdatabatch">setDataBatch</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"> setDataBatch</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"> dataKeys</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"> dataValues</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre> <p>Function Selector: <code>0x97902421</code></p> <p>Sets array of data at multiple data keys. MUST only be called by the current owner of the contract.</p> <p><em>Parameters:</em></p> <ul> <li><code>dataKeys</code>: the data keys which values to set.</li> <li><code>dataValues</code>: the array of bytes to set.</li> </ul> <p><em>Requirements:</em></p> <ul> <li>Array parameters MUST have the same length.</li> <li>MUST only be called by the current owner of the contract.</li> </ul> <p><strong>Triggers Event:</strong> <a href="https://wg-eips.ritovision.com/725/#datachanged">DataChanged</a></p> <h3 id="erc725y-events"><code>ERC725Y</code> Events</h3> <h4 id="datachanged">DataChanged</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"> DataChanged</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> dataKey</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> dataValue</span><span>)</span></span></code></pre> <p>MUST be triggered when a data key was successfully set.</p> <h3 id="erc725y-data-keys"><code>ERC725Y</code> Data keys</h3> <p>Data keys, are the way to retrieve values via <code>getData()</code>. These <code>bytes32</code> values can be freely chosen, or defined by a standard. A common way to define data keys is the hash of a word, e.g. <code>keccak256('ERCXXXMyNewKeyType')</code> which results in: <code>0x6935a24ea384927f250ee0b954ed498cd9203fc5d2bf95c735e52e6ca675e047</code></p> <p>The <code>LSP2-ERC725JSONSchema</code> standard is a more explicit <code>ERC725Y</code> data key standard, that defines key types and value types, and their encoding and decoding.</p> <h2 id="rationale">Rationale</h2> <p>The generic way of storing data keys with values was chosen to allow upgradability over time. Stored data values can be changed over time. Other smart contract protocols can then interpret this data in new ways and react to interactions from a <code>ERC725</code> smart contract differently.</p> <p>The data stored in an <code>ERC725Y</code> smart contract is not only readable/writable by off-chain applications, but also by other smart contracts. Function overloading was used to allow for the retrievable of single and multiple keys, to keep gas costs minimal for both use cases.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>All contracts since <code>ERC725v2</code> from 2018/19 should be compatible with the current version of the standard. Mainly interface ID and Event parameters have changed, while <code>getData(bytes32[])</code> and <code>setData(bytes32[], bytes[])</code> was added as an efficient way to set/get multiple keys at once. The same applies to execution, as <code>execute(..[])</code> was added as an efficient way to batch calls.</p> <p>From 2023 onward, overloading was removed from <code>ERC-725</code> (including <code>ERC725-X</code> and <code>ERC725-Y</code>). This is because, while overloading is accommodated in Solidity, it isn't broadly supported across most blockchain languages. In order to make the standard language-independent, it was decided to shift from overloading to simply attach the term "Batch" to the functions that accept an array as parameters.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Reference implementations can be found in <a href="https://wg-eips.ritovision.com/725/./assets/ERC725.sol"><code>ERC725.sol</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This contract allows generic executions, therefore special care needs to be taken to prevent re-entrancy attacks and other forms of call chain attacks.</p> <p>When using the operation type <code>4</code> for <code>delegatecall</code>, it is important to consider that the called contracts can alter the state of the calling contract and also change owner variables and <code>ERC725Y</code> data storage entries at will. Additionally calls to <code>selfdestruct</code> are possible and other harmful state-changing operations.</p> <h3 id="solidity-interfaces">Solidity Interfaces</h3> <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"> &gt;=0.5.0</span><span class="z-keyword"> &lt;</span><span class="z-constant">0.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-comment">//</span><span class="z-comment"> ERC165 identifier: `0x7545acac`</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC725X</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC165, ERC173 </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"> Executed</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operationType</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> target</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> indexed</span><span class="z-variable"> value</span><span>, </span><span class="z-support">bytes4</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"> ContractCreated</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operationType</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 class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> value</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> salt</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"> execute</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> operationType</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> target</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</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-storage z-type"> payable</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> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> executeBatch</span><span>(</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> operationsType</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"> targets</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> values</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> datas</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">bytes</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 class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ERC165 identifier: `0x629aa694`</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC725Y</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC165, ERC173 </span><span class="z-comment">*/</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"> DataChanged</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> dataKey</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> dataValue</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"> getData</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> dataKey</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-storage z-type"> function</span><span class="z-entity z-name"> getDataBatch</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"> dataKeys</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>[</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"> setData</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> dataKey</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> dataValue</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"> setDataBatch</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"> dataKeys</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"> dataValues</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">interface</span><span class="z-entity z-name"> IERC725</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC725X, IERC725Y </span><span class="z-comment">*/</span><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> 2017-09-12T00:00:00+00:00 2026-02-11T14:49:28+00:00 Remco Bloemenhttps://github.com/Recmo Leonid Logvinovhttps://github.com/LogvinovLeon Jacob Evanshttps://github.com/dekz https://wg-eips.ritovision.com/712/

A procedure for hashing and signing of typed structured data as opposed to just bytestrings.

<h2 id="abstract">Abstract</h2> <p>This is a standard for hashing and signing of typed structured data as opposed to just bytestrings. It includes a</p> <ul> <li>theoretical framework for correctness of encoding functions,</li> <li>specification of structured data similar to and compatible with Solidity structs,</li> <li>safe hashing algorithm for instances of those structures,</li> <li>safe inclusion of those instances in the set of signable messages,</li> <li>an extensible mechanism for domain separation,</li> <li>new RPC call <code>eth_signTypedData</code>, and</li> <li>an optimized implementation of the hashing algorithm in EVM.</li> </ul> <p>It does not include replay protection.</p> <h2 id="motivation">Motivation</h2> <p>Signing data is a solved problem if all we care about are bytestrings. Unfortunately in the real world we care about complex meaningful messages. Hashing structured data is non-trivial and errors result in loss of the security properties of the system.</p> <p>As such, the adage "don't roll your own crypto" applies. Instead, a peer-reviewed well-tested standard method needs to be used. This EIP aims to be that standard.</p> <p>This EIP aims to improve the usability of off-chain message signing for use on-chain. We are seeing growing adoption of off-chain message signing as it saves gas and reduces the number of transactions on the blockchain. Currently signed messages are an opaque hex string displayed to the user with little context about the items that make up the message.</p> <p><img src="https://wg-eips.ritovision.com/712/./assets/eth_sign.png" alt="eth_sign screenshot" /></p> <p>Here we outline a scheme to encode data along with its structure which allows it to be displayed to the user for verification when signing. Below is an example of what a user could be shown when signing a message according to the present proposal.</p> <p><img src="https://wg-eips.ritovision.com/712/./assets/eth_signTypedData.png" alt="eth_signTypedData screenshot" /></p> <h2 id="specification">Specification</h2> <p>The set of signable messages is extended from transactions and bytestrings <code>𝕋 ∪ 𝔹⁸ⁿ</code> to also include structured data <code>𝕊</code>. The new set of signable messages is thus <code>𝕋 ∪ 𝔹⁸ⁿ ∪ 𝕊</code>. They are encoded to bytestrings suitable for hashing and signing as follows:</p> <ul> <li><code>encode(transaction : 𝕋) = RLP_encode(transaction)</code></li> <li><code>encode(message : 𝔹⁸ⁿ) = "\x19Ethereum Signed Message:\n" ‖ len(message) ‖ message</code> where <code>len(message)</code> is the <em>non-zero-padded</em> ascii-decimal encoding of the number of bytes in <code>message</code>.</li> <li><code>encode(domainSeparator : 𝔹²⁵⁶, message : 𝕊) = "\x19\x01" ‖ domainSeparator ‖ hashStruct(message)</code> where <code>domainSeparator</code> and <code>hashStruct(message)</code> are defined below.</li> </ul> <p>This encoding is deterministic because the individual components are. The encoding is injective because the three cases always differ in first byte. (<code>RLP_encode(transaction)</code> does not start with <code>\x19</code>.)</p> <p>The encoding is compliant with <a href="https://wg-eips.ritovision.com/191/">ERC-191</a>. The 'version byte' is fixed to <code>0x01</code>, the 'version specific data' is the 32-byte domain separator <code>domainSeparator</code> and the 'data to sign' is the 32-byte <code>hashStruct(message)</code>.</p> <h3 id="definition-of-typed-structured-data-s">Definition of typed structured data <code>𝕊</code></h3> <p>To define the set of all structured data, we start with defining acceptable types. Like ABIv2 these are closely related to Solidity types. It is illustrative to adopt Solidity notation to explain the definitions. The standard is specific to the Ethereum Virtual Machine, but aims to be agnostic to higher level languages. 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"> Mail</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> from</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"> string</span><span> contents</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>Definition</strong>: A <em>struct type</em> has valid identifier as name and contains zero or more member variables. Member variables have a member type and a name.</p> <p><strong>Definition</strong>: A <em>member type</em> can be either an atomic type, a dynamic type or a reference type.</p> <p><strong>Definition</strong>: The <em>atomic types</em> are <code>bytes1</code> to <code>bytes32</code>, <code>uint8</code> to <code>uint256</code>, <code>int8</code> to <code>int256</code>, <code>bool</code> and <code>address</code>. These correspond to their definition in Solidity. Note that there are no aliases <code>uint</code> and <code>int</code>. Note that contract addresses are always plain <code>address</code>. Fixed point numbers are not supported by the standard. Future versions of this standard may add new atomic types.</p> <p><strong>Definition</strong>: The <em>dynamic types</em> are <code>bytes</code> and <code>string</code>. These are like the atomic types for the purpose of type declaration, but their treatment in encoding is different.</p> <p><strong>Definition</strong>: The <em>reference types</em> are arrays and structs. Arrays are either fixed size or dynamic and denoted by <code>Type[n]</code> or <code>Type[]</code> respectively. Structs are references to other structs by their name. The standard supports recursive struct types.</p> <p><strong>Definition</strong>: The set of structured typed data <code>𝕊</code> contains all the instances of all the struct types.</p> <h3 id="definition-of-hashstruct">Definition of <code>hashStruct</code></h3> <p>The <code>hashStruct</code> function is defined as</p> <ul> <li><code>hashStruct(s : 𝕊) = keccak256(typeHash ‖ encodeData(s))</code> where <code>typeHash = keccak256(encodeType(typeOf(s)))</code></li> </ul> <p><strong>Note</strong>: The <code>typeHash</code> is a constant for a given struct type and does not need to be runtime computed.</p> <h3 id="definition-of-encodetype">Definition of <code>encodeType</code></h3> <p>The type of a struct is encoded as <code>name ‖ "(" ‖ member₁ ‖ "," ‖ member₂ ‖ "," ‖ … ‖ memberₙ ")"</code> where each member is written as <code>type ‖ " " ‖ name</code>. For example, the above <code>Mail</code> struct is encoded as <code>Mail(address from,address to,string contents)</code>.</p> <p>If the struct type references other struct types (and these in turn reference even more struct types), then the set of referenced struct types is collected, sorted by name and appended to the encoding. An example encoding is <code>Transaction(Person from,Person to,Asset tx)Asset(address token,uint256 amount)Person(address wallet,string name)</code>.</p> <h3 id="definition-of-encodedata">Definition of <code>encodeData</code></h3> <p>The encoding of a struct instance is <code>enc(value₁) ‖ enc(value₂) ‖ … ‖ enc(valueₙ)</code>, i.e. the concatenation of the encoded member values in the order that they appear in the type. Each encoded member value is exactly 32-byte long.</p> <p>The atomic values are encoded as follows: Boolean <code>false</code> and <code>true</code> are encoded as <code>uint256</code> values <code>0</code> and <code>1</code> respectively. Addresses are encoded as <code>uint160</code>. Integer values are sign-extended to 256-bit and encoded in big endian order. <code>bytes1</code> to <code>bytes31</code> are arrays with a beginning (index <code>0</code>) and an end (index <code>length - 1</code>), they are zero-padded at the end to <code>bytes32</code> and encoded in beginning to end order. This corresponds to their encoding in ABI v1 and v2.</p> <p>The dynamic values <code>bytes</code> and <code>string</code> are encoded as a <code>keccak256</code> hash of their contents.</p> <p>The array values are encoded as the <code>keccak256</code> hash of the concatenated <code>encodeData</code> of their contents (i.e. the encoding of <code>SomeType[5]</code> is identical to that of a struct containing five members of type <code>SomeType</code>).</p> <p>The struct values are encoded recursively as <code>hashStruct(value)</code>. This is undefined for cyclical data.</p> <h3 id="definition-of-domainseparator">Definition of <code>domainSeparator</code></h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>domainSeparator </span><span class="z-keyword">=</span><span class="z-entity z-name"> hashStruct</span><span>(</span><span>eip712Domain</span><span>)</span></span></code></pre> <p>where the type of <code>eip712Domain</code> is a struct named <code>EIP712Domain</code> with one or more of the below fields. Protocol designers only need to include the fields that make sense for their signing domain. Unused fields are left out of the struct type.</p> <ul> <li><code>string name</code> the user readable name of signing domain, i.e. the name of the DApp or the protocol.</li> <li><code>string version</code> the current major version of the signing domain. Signatures from different versions are not compatible.</li> <li><code>uint256 chainId</code> the <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> chain id. The user-agent <em>should</em> refuse signing if it does not match the currently active chain.</li> <li><code>address verifyingContract</code> the address of the contract that will verify the signature. The user-agent <em>may</em> do contract specific phishing prevention.</li> <li><code>bytes32 salt</code> a disambiguating salt for the protocol. This can be used as a domain separator of last resort.</li> </ul> <p>Future extensions to this standard can add new fields with new user-agent behaviour constraints. User-agents are free to use the provided information to inform/warn users or refuse signing. Dapp implementers should not add private fields, new fields should be proposed through the EIP process.</p> <p>The <code>EIP712Domain</code> fields should be the order as above, skipping any absent fields. Future field additions must be in alphabetical order and come after the above fields. User-agents should accept fields in any order as specified by the <code>EIP712Domain</code> type.</p> <h3 id="specification-of-the-eth-signtypeddata-json-rpc">Specification of the <code>eth_signTypedData</code> JSON RPC</h3> <p>The method <code>eth_signTypedData</code> is added to the Ethereum JSON-RPC. The method parallels <code>eth_sign</code>.</p> <h4 id="eth-signtypeddata">eth_signTypedData</h4> <p>The sign method calculates an Ethereum specific signature with: <code>sign(keccak256("\x19\x01" ‖ domainSeparator ‖ hashStruct(message)))</code>, as defined above.</p> <p><strong>Note</strong>: the address to sign with must be unlocked.</p> <h5 id="parameters">Parameters</h5> <ol> <li><code>Address</code> - 20 Bytes - Address of the account that will sign the messages.</li> <li><code>TypedData</code> - Typed structured data to be signed.</li> </ol> <p>Typed data is a JSON object containing type information, domain separator parameters and the message object. Below is the json-schema definition for <code>TypedData</code> param.</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"> 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"> 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"> properties</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> EIP712Domain</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">array</span><span class="z-punctuation z-definition z-string">&#39;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</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></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">EIP712Domain</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"> 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"> domain</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"> message</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 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">types</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">domain</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">message</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="returns">Returns</h5> <p><code>DATA</code>: Signature. As in <code>eth_sign</code> it is a hex encoded 65 byte array starting with <code>0x</code>. It encodes the <code>r</code>, <code>s</code> and <code>v</code> parameters from appendix F of the yellow paper in big-endian format. Bytes 0...32 contain the <code>r</code> parameter, bytes 32...64 the <code>s</code> parameter and the last byte the <code>v</code> parameter. Note that the <code>v</code> parameter includes the chain id as specified in <a href="https://wg-eips.ritovision.com/155/">EIP-155</a>.</p> <h5 id="example">Example</h5> <p>Request:</p> <pre class="giallo z-code"><code data-lang="shellscript"><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">{&quot;jsonrpc&quot;:&quot;2.0&quot;,&quot;method&quot;:&quot;eth_signTypedData&quot;,&quot;params&quot;:[&quot;0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826&quot;, {&quot;types&quot;:{&quot;EIP712Domain&quot;:[{&quot;name&quot;:&quot;name&quot;,&quot;type&quot;:&quot;string&quot;},{&quot;name&quot;:&quot;version&quot;,&quot;type&quot;:&quot;string&quot;},{&quot;name&quot;:&quot;chainId&quot;,&quot;type&quot;:&quot;uint256&quot;},{&quot;name&quot;:&quot;verifyingContract&quot;,&quot;type&quot;:&quot;address&quot;}],&quot;Person&quot;:[{&quot;name&quot;:&quot;name&quot;,&quot;type&quot;:&quot;string&quot;},{&quot;name&quot;:&quot;wallet&quot;,&quot;type&quot;:&quot;address&quot;}],&quot;Mail&quot;:[{&quot;name&quot;:&quot;from&quot;,&quot;type&quot;:&quot;Person&quot;},{&quot;name&quot;:&quot;to&quot;,&quot;type&quot;:&quot;Person&quot;},{&quot;name&quot;:&quot;contents&quot;,&quot;type&quot;:&quot;string&quot;}]},&quot;primaryType&quot;:&quot;Mail&quot;,&quot;domain&quot;:{&quot;name&quot;:&quot;Ether Mail&quot;,&quot;version&quot;:&quot;1&quot;,&quot;chainId&quot;:1,&quot;verifyingContract&quot;:&quot;0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC&quot;},&quot;message&quot;:{&quot;from&quot;:{&quot;name&quot;:&quot;Cow&quot;,&quot;wallet&quot;:&quot;0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826&quot;},&quot;to&quot;:{&quot;name&quot;:&quot;Bob&quot;,&quot;wallet&quot;:&quot;0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB&quot;},&quot;contents&quot;:&quot;Hello, Bob!&quot;}}],&quot;id&quot;:1}</span><span class="z-punctuation z-definition z-string">&#39;</span></span></code></pre> <p>Result:</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">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">0x4355c47d63924e8a72e509b65029052eb6c299d53a04e167c5775fd466751c9d07299936d304c153f6443dfa05f40ff007d72911b6f72307f996231605b915621c</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>An example how to use Solidity ecrecover to verify the signature calculated with <code>eth_signTypedData</code> can be found in the <a href="https://wg-eips.ritovision.com/712/./assets/Example.js">Example.js</a>. The contract is deployed on the testnet Ropsten and Rinkeby.</p> <h4 id="personal-signtypeddata">personal_signTypedData</h4> <p>There also should be a corresponding <code>personal_signTypedData</code> method which accepts the password for an account as the last argument.</p> <h3 id="specification-of-the-web3-api">Specification of the Web3 API</h3> <p>Two methods are added to Web3.js version 1 that parallel the <code>web3.eth.sign</code> and <code>web3.eth.personal.sign</code> methods.</p> <h4 id="web3-eth-signtypeddata">web3.eth.signTypedData</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><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">signTypedData</span><span>(</span><span class="z-variable z-other">typedData</span><span>,</span><span class="z-variable z-other"> address</span><span> [</span><span>,</span><span class="z-variable z-other"> callback</span><span>]</span><span>)</span></span></code></pre> <p>Signs typed data using a specific account. This account needs to be unlocked.</p> <h5 id="parameters-1">Parameters</h5> <ol> <li><code>Object</code> - Domain separator and typed data to sign. Structured according to the JSON-Schema specified above in the <code>eth_signTypedData</code> JSON RPC call.</li> <li><code>String|Number</code> - Address to sign data with. Or an address or index of a local wallet in :ref:<code>web3.eth.accounts.wallet &lt;eth_accounts_wallet&gt;</code>.</li> <li><code>Function</code> - (optional) Optional callback, returns an error object as first parameter and the result as second.</li> </ol> <p><strong>Note</strong>: The 2. <code>address</code> parameter can also be an address or index from the <code>web3.eth.accounts.wallet &lt;eth_accounts_wallet&gt;</code>. It will then sign locally using the private key of this account.</p> <h5 id="returns-1">Returns</h5> <p><code>Promise</code> returns <code>String</code> - The signature as returned by <code>eth_signTypedData</code>.</p> <h5 id="example-1">Example</h5> <p>See the <code>eth_signTypedData</code> JSON-API example above for the value of <code>typedData</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><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">signTypedData</span><span>(</span><span class="z-variable z-other">typedData</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span>.</span><span class="z-entity z-name">then</span><span>(</span><span class="z-variable z-other">console</span><span>.</span><span class="z-variable z-other">log</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</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></code></pre><h4 id="web3-eth-personal-signtypeddata">web3.eth.personal.signTypedData</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">web3</span><span>.</span><span class="z-variable z-other">eth</span><span>.</span><span class="z-variable z-other">personal</span><span>.</span><span class="z-entity z-name">signTypedData</span><span>(</span><span class="z-variable z-other">typedData</span><span>,</span><span class="z-variable z-other"> address</span><span>,</span><span class="z-variable z-other"> password</span><span> [</span><span>,</span><span class="z-variable z-other"> callback</span><span>]</span><span>)</span></span></code></pre> <p>Identical to <code>web3.eth.signTypedData</code> except for an additional <code>password</code> parameter analogous to <code>web3.eth.personal.sign</code>.</p> <h2 id="rationale">Rationale</h2> <p>The <code>encode</code> function is extended with a new case for the new types. The first byte of the encoding distinguishes the cases. For the same reason it is not safe to start immediately with the domain separator or a <code>typeHash</code>. While hard, it may be possible to construct a <code>typeHash</code> that also happens to be a prefix of a valid RLP encoded transaction.</p> <p>The domain separator prevents collision of otherwise identical structures. It is possible that two DApps come up with an identical structure like <code>Transfer(address from,address to,uint256 amount)</code> that should not be compatible. By introducing a domain separator the DApp developers are guaranteed that there can be no signature collision.</p> <p>The domain separator also allows for multiple distinct signatures use-cases on the same struct instance within a given DApp. In the previous example, perhaps signatures from both <code>from</code> and <code>to</code> are required. By providing two distinct domain separators these signatures can be distinguished from each other.</p> <p><strong>Alternative 1</strong>: Use the target contract address as domain separator. This solves the first problem, contracts coming up with identical types, but does not address the second use-case. The standard does suggest implementors to use the target contract address where this is appropriate.</p> <p>The function <code>hashStruct</code> starts with a <code>typeHash</code> to separate types. By giving different types a different prefix the <code>encodeData</code> function only has to be injective within a given type. It is okay for <code>encodeData(a)</code> to equal <code>encodeData(b)</code> as long as <code>typeOf(a)</code> is not <code>typeOf(b)</code>.</p> <h3 id="rationale-for-typehash">Rationale for <code>typeHash</code></h3> <p>The <code>typeHash</code> is designed to turn into a compile time constant in Solidity. For example:</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"> constant</span><span> MAIL_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;Mail(address from,address to,string contents)&quot;</span><span>)</span><span>;</span></span></code></pre> <p>For the type hash several alternatives were considered and rejected for the reasons:</p> <p><strong>Alternative 2</strong>: Use ABIv2 function signatures. <code>bytes4</code> is not enough to be collision resistant. Unlike function signatures, there is negligible runtime cost incurred by using longer hashes.</p> <p><strong>Alternative 3</strong>: ABIv2 function signatures modified to be 256-bit. While this captures type info, it does not capture any of the semantics other than the function. This is already causing a practical collision between <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>'s and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>'s <code>transfer(address,uint256)</code>, where in the former the <code>uint256</code> refers to an amount and the latter to a unique id. In general ABIv2 favors compatibility where a hashing standard should prefer incompatibility.</p> <p><strong>Alternative 4</strong>: 256-bit ABIv2 signatures extended with parameter names and struct names. The <code>Mail</code> example from above would be encoded as <code>Mail(Person(string name,address wallet) from,Person(string name,address wallet) to,string contents)</code>. This is longer than the proposed solution. And indeed, the length of the string can grow exponentially in the length of the input (consider <code>struct A{B a;B b;}; struct B {C a;C b;}; …</code>). It also does not allow a recursive struct type (consider <code>struct List {uint256 value; List next;}</code>).</p> <p><strong>Alternative 5</strong>: Include natspec documentation. This would include even more semantic information in the schemaHash and further reduces chances of collision. It makes extending and amending documentation a breaking changes, which contradicts common assumptions. It also makes the schemaHash mechanism very verbose.</p> <h3 id="rationale-for-encodedata">Rationale for <code>encodeData</code></h3> <p>The <code>encodeData</code> is designed to allow easy implementation of <code>hashStruct</code> in Solidity:</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"> hashStruct</span><span>(</span><span class="z-storage z-type">Mail</span><span class="z-storage z-type"> memory</span><span class="z-variable"> mail</span><span>)</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> hash</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> <span class="giallo-l"><span> MAIL_TYPEHASH</span><span>,</span></span> <span class="giallo-l"><span> mail</span><span>.</span><span>from</span><span>,</span></span> <span class="giallo-l"><span> mail</span><span>.</span><span>to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span>mail</span><span>.</span><span>contents</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>it also allows for an efficient in-place implementation in EVM</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"> hashStruct</span><span>(</span><span class="z-storage z-type">Mail</span><span class="z-storage z-type"> memory</span><span class="z-variable"> mail</span><span>)</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><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 class="z-comment"> Compute sub-hashes</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> typeHash </span><span class="z-keyword">=</span><span> MAIL_TYPEHASH</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> contentsHash </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span>mail</span><span>.</span><span>contents</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Back up select memory</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> temp1 </span><span class="z-keyword">:=</span><span class="z-entity z-name"> mload</span><span>(</span><span class="z-entity z-name">sub</span><span>(</span><span>mail</span><span>,</span><span class="z-constant"> 32</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> temp2 </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>mail</span><span>,</span><span class="z-constant"> 128</span><span>)</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Write typeHash and sub-hashes</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-entity z-name">sub</span><span>(</span><span>mail</span><span>,</span><span class="z-constant"> 32</span><span>)</span><span>,</span><span> typeHash</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>mail</span><span>,</span><span class="z-constant"> 64</span><span>)</span><span>,</span><span> contentsHash</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Compute hash</span></span> <span class="giallo-l"><span> hash </span><span class="z-keyword">:=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-entity z-name">sub</span><span>(</span><span>mail</span><span>,</span><span class="z-constant"> 32</span><span>)</span><span>,</span><span class="z-constant"> 128</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Restore memory</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-entity z-name">sub</span><span>(</span><span>mail</span><span>,</span><span class="z-constant"> 32</span><span>)</span><span>,</span><span> temp1</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>mail</span><span>,</span><span class="z-constant"> 64</span><span>)</span><span>,</span><span> temp2</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The in-place implementation makes strong but reasonable assumptions on the memory layout of structs in memory. Specifically it assumes structs are not allocated below address 32, that members are stored in order, that all values are padded to 32-byte boundaries, and that dynamic and reference types are stored as a 32-byte pointers.</p> <p><strong>Alternative 6</strong>: Tight packing. This is the default behaviour in Solidity when calling <code>keccak256</code> with multiple arguments. It minimizes the number of bytes to be hashed but requires complicated packing instructions in EVM to do so. It does not allow in-place computation.</p> <p><strong>Alternative 7</strong>: ABIv2 encoding. Especially with the upcoming <code>abi.encode</code> it should be easy to use <code>abi.encode</code> as the <code>encodeData</code> function. The ABIv2 standard by itself fails the determinism security criteria. There are several valid ABIv2 encodings of the same data. ABIv2 does not allow in-place computation.</p> <p><strong>Alternative 8</strong>: Leave <code>typeHash</code> out of <code>hashStruct</code> and instead combine it with the domain separator. This is more efficient, but then the semantics of the Solidity <code>keccak256</code> hash function are not injective.</p> <p><strong>Alternative 9</strong>: Support cyclical data structures. The current standard is optimized for tree-like data structures and undefined for cyclical data structures. To support cyclical data a stack containing the path to the current node needs to be maintained and a stack offset substituted when a cycle is detected. This is prohibitively more complex to specify and implement. It also breaks composability where the hashes of the member values are used to construct the hash of the struct (the hash of the member values would depend on the path). It is possible to extend the standard in a compatible way to define hashes of cyclical data.</p> <p>Similarly, a straightforward implementation is sub-optimal for directed acyclic graphs. A simple recursion through the members can visit the same node twice. Memoization can optimize this.</p> <h3 id="rationale-for-domainseparator">Rationale for <code>domainSeparator</code></h3> <p>Since different domains have different needs, an extensible scheme is used where the DApp specifies a <code>EIP712Domain</code> struct type and an instance <code>eip712Domain</code> which it passes to the user-agent. The user-agent can then apply different verification measures depending on the fields that are there.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The RPC calls, web3 methods and <code>SomeStruct.typeHash</code> parameter are currently undefined. Defining them should not affect the behaviour of existing DApps.</p> <p>The Solidity expression <code>keccak256(someInstance)</code> for an instance <code>someInstance</code> of a struct type <code>SomeStruct</code> is valid syntax. It currently evaluates to the <code>keccak256</code> hash of the memory address of the instance. This behaviour should be considered dangerous. In some scenarios it will appear to work correctly but in others it will fail determinism and/or injectiveness. DApps that depend on the current behaviour should be considered dangerously broken.</p> <h2 id="test-cases">Test Cases</h2> <p>An example contract can be found in <a href="https://wg-eips.ritovision.com/712/./assets/Example.sol">Example.sol</a> and an example implementation of signing in JavaScript in <a href="https://wg-eips.ritovision.com/712/./assets/Example.js">Example.js</a></p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="replay-attacks">Replay attacks</h3> <p>This standard is only about signing messages and verifying signatures. In many practical applications, signed messages are used to authorize an action, for example an exchange of tokens. It is <em>very important</em> that implementers make sure the application behaves correctly when it sees the same signed message twice. For example, the repeated message should be rejected or the authorized action should be idempotent. How this is implemented is specific to the application and out of scope for this standard.</p> <h3 id="frontrunning-attacks">Frontrunning attacks</h3> <p>The mechanism for reliably broadcasting a signature is application-specific and out of scope for this standard. When the signature is broadcast to a blockchain for use in a contract, the application has to be secure against frontrunning attacks. In this kind of attack, an attacker intercepts the signature and submits it to the contract before the original intended use takes place. The application should behave correctly when the signature is submitted first by an attacker, for example by rejecting it or simply producing exactly the same effect as intended by the signer.</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-09-07T00:00:00+00:00 2026-02-11T14:49:27+00:00 Péter Szilágyipeter@ethereum.org https://wg-eips.ritovision.com/706/ <h2 id="abstract">Abstract</h2> <p>The base networking protocol (DEVp2p) used by Ethereum currently does not employ any form of compression. This results in a massive amount of bandwidth wasted in the entire network, making both initial sync as well as normal operation slower and laggier.</p> <p>This EIP proposes a tiny extension to the DEVp2p protocol to enable <a rel="external" href="https://en.wikipedia.org/wiki/Snappy_(compression)">Snappy compression</a> on all message payloads after the initial handshake. After extensive benchmarks, results show that data traffic is decreased by 60-80% for initial sync. You can find exact numbers below.</p> <h2 id="motivation">Motivation</h2> <p>Synchronizing the Ethereum main network (block 4,248,000) in Geth using fast sync currently consumes 1.01GB upload and 33.59GB download bandwidth. On the Rinkeby test network (block 852,000) it's 55.89MB upload and 2.51GB download.</p> <p>However, most of this data (blocks, transactions) are heavily compressible. By enabling compression at the message payload level, we can reduce the previous numbers to 1.01GB upload / 13.46GB download on the main network, and 46.21MB upload / 463.65MB download on the test network.</p> <p>The motivation behind doing this at the DEVp2p level (opposed to eth for example) is that it would enable compression for all sub-protocols (eth, les, bzz) seamlessly, reducing any complexity those protocols might incur in trying to individually optimize for data traffic.</p> <h2 id="specification">Specification</h2> <p>Bump the advertised DEVp2p version number from <code>4</code> to <code>5</code>. If during handshake, the remote side advertises support only for version <code>4</code>, run the exact same protocol as until now.</p> <p>If the remote side advertises a DEVp2p version <code>&gt;= 5</code>, inject a Snappy compression step right before encrypting the DEVp2p message during sending:</p> <ul> <li>A message consists of <code>{Code, Size, Payload}</code></li> <li>Compress the original payload with Snappy and store it in the same field.</li> <li>Update the message size to the length of the compressed payload.</li> <li>Encrypt and send the message as before, oblivious to compression.</li> </ul> <p>Similarly to message sending, when receiving a DEVp2p v5 message from a remote node, insert a Snappy decompression step right after decrypting the DEVp2p message:</p> <ul> <li>A message consists of <code>{Code, Size, Payload}</code></li> <li>Decrypt the message payload as before, oblivious to compression.</li> <li>Decompress the payload with Snappy and store it in the same field.</li> <li>Update the message size to the length of the decompressed payload.</li> </ul> <p>Important caveats:</p> <ul> <li>The handshake message is <strong>never</strong> compressed, since it is needed to negotiate the common version.</li> <li>Snappy framing is <strong>not</strong> used, since the DEVp2p protocol already message oriented.</li> </ul> <p><em>Note: Snappy supports uncompressed binary literals (up to 4GB) too, leaving room for fine-tuned future optimisations for already compressed or encrypted data that would have no gain of compression (Snappy usually detects this case automatically).</em></p> <h3 id="avoiding-dos-attacks">Avoiding DOS attacks</h3> <p>Currently a DEVp2p message length is limited to 24 bits, amounting to a maximum size of 16MB. With the introduction of Snappy compression, care must be taken not to blindly decompress messages, since they may get significantly larger than 16MB.</p> <p>However, Snappy is capable of calculating the decompressed size of an input message without inflating it in memory (<em><a rel="external" href="https://github.com/google/snappy/blob/master/format_description.txt#L20">the stream starts with the uncompressed length up to a maximum of <code>2^32 - 1</code> stored as a little-endian varint</a></em>). This can be used to discard any messages which decompress above some threshold. <strong>The proposal is to use the same limit (16MB) as the threshold for decompressed messages.</strong> This retains the same guarantees that the current DEVp2p protocol does, so there won't be surprises in application level protocols.</p> <h2 id="alternatives-discarded">Alternatives (discarded)</h2> <p><strong>Alternative solutions to data compression that have been brought up and discarded are:</strong></p> <p>Extend protocol <code>xyz</code> to support compressed messages versus doing it at DEVp2p level:</p> <ul> <li><strong>Pro</strong>: Can be better optimized when to compress and when not to.</li> <li><strong>Con</strong>: Mixes in transport layer encoding into application layer logic.</li> <li><strong>Con</strong>: Makes the individual message specs more convoluted with compression details.</li> <li><strong>Con</strong>: Requires cross client coordination on every single protocol, making the effort much harder and repeated (eth, les, shh, bzz).</li> </ul> <p>Introduce seamless variations of protocol such as <code>xyz</code> expanded with <code>xyz-compressed</code>:</p> <ul> <li><strong>Pro</strong>: Can be done (hacked in) without cross client coordination.</li> <li><strong>Con</strong>: Litters the network with client specific protocol announces.</li> <li><strong>Con</strong>: Needs to be specced in an EIP for cross interoperability anyway.</li> </ul> <p><strong>Other ideas that have been discussed and discarded:</strong></p> <p>Don't explicitly limit the decompressed message size, only the compressed one:</p> <ul> <li><strong>Pro</strong>: Allows larger messages to traverse through DEVp2p.</li> <li><strong>Con</strong>: Upper layer protocols need to check and discard large messages.</li> <li><strong>Con</strong>: Needs lazy decompression to allow size limitations without DOS.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backward compatible. Clients upgrading to the proposed DEVp2p protocol version <code>5</code> should still support skipping the compression step for connections that only advertise version <code>4</code> of the DEVp2p protocol.</p> <h2 id="implementation">Implementation</h2> <p>You can find a reference implementation of this EIP in https://github.com/ethereum/go-ethereum/pull/15106.</p> <h2 id="test-vectors">Test vectors</h2> <p>There is more than one valid encoding of any given input, and there is more than one good internal compression algorithm within Snappy when trading off throughput for output size. As such, different implementations might produce slight variations in the compressed form, but all should be cross compatible between each other.</p> <p>As an example, take hex encoded RLP of block #272621 from the Rinkeby test network: <a rel="external" href="https://gist.githubusercontent.com/karalabe/72a1a6c4c1dbe6d4996879e415697f06/raw/195bf0c0050ee9805fcd5db4b5b650c58879a55f/block.rlp">block.rlp (~3MB)</a>.</p> <ul> <li>Encoding the raw RLP via <a rel="external" href="https://github.com/golang/snappy">Go's Snappy library</a> yields: <a rel="external" href="https://gist.githubusercontent.com/karalabe/72a1a6c4c1dbe6d4996879e415697f06/raw/195bf0c0050ee9805fcd5db4b5b650c58879a55f/block.go.snappy">block.go.snappy (~70KB)</a>.</li> <li>Encoding the raw RLP via <a rel="external" href="https://github.com/andrix/python-snappy">Python's Snappy library</a> yields: <a rel="external" href="https://gist.githubusercontent.com/karalabe/72a1a6c4c1dbe6d4996879e415697f06/raw/195bf0c0050ee9805fcd5db4b5b650c58879a55f/block.py.snappy">block.py.snappy (~70KB)</a>.</li> </ul> <p>You can verify that an encoded binary can be decoded into the proper plaintext using the following snippets:</p> <h3 id="go">Go</h3> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> go</span><span class="z-string"> get</span><span class="z-string"> https://github.com/golang/snappy</span></span></code></pre><pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span class="z-keyword">package</span><span class="z-entity z-name"> main</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span> (</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-entity z-name">bytes</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-entity z-name">encoding/hex</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-entity z-name">fmt</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-entity z-name">io/ioutil</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-entity z-name">log</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-entity z-name">os</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-entity z-name">github.com/golang/snappy</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 class="giallo-l"><span class="z-keyword">func</span><span class="z-entity z-name"> main</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"> Read and decode the decompressed file</span></span> <span class="giallo-l"><span class="z-variable z-other"> plainhex</span><span>,</span><span class="z-variable z-other"> err</span><span class="z-keyword"> :=</span><span class="z-variable z-other"> ioutil</span><span>.</span><span class="z-entity z-name">ReadFile</span><span>(</span><span class="z-variable z-other">os</span><span>.</span><span class="z-variable z-other">Args</span><span>[</span><span class="z-constant">1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-variable z-other"> err</span><span class="z-keyword"> !=</span><span class="z-constant"> nil</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> log</span><span>.</span><span class="z-entity z-name">Fatalf</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Failed to read decompressed file </span><span class="z-constant">%s</span><span class="z-string">: </span><span class="z-constant">%v</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> os</span><span>.</span><span class="z-variable z-other">Args</span><span>[</span><span class="z-constant">1</span><span>]</span><span>,</span><span class="z-variable z-other"> err</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-variable z-other"> plain</span><span>,</span><span class="z-variable z-other"> err</span><span class="z-keyword"> :=</span><span class="z-variable z-other"> hex</span><span>.</span><span class="z-entity z-name">DecodeString</span><span>(</span><span class="z-storage z-type">string</span><span>(</span><span class="z-variable z-other">plainhex</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-variable z-other"> err</span><span class="z-keyword"> !=</span><span class="z-constant"> nil</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> log</span><span>.</span><span class="z-entity z-name">Fatalf</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Failed to decode decompressed file: </span><span class="z-constant">%v</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> err</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"> Read and decode the compressed file</span></span> <span class="giallo-l"><span class="z-variable z-other"> comphex</span><span>,</span><span class="z-variable z-other"> err</span><span class="z-keyword"> :=</span><span class="z-variable z-other"> ioutil</span><span>.</span><span class="z-entity z-name">ReadFile</span><span>(</span><span class="z-variable z-other">os</span><span>.</span><span class="z-variable z-other">Args</span><span>[</span><span class="z-constant">2</span><span>]</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-variable z-other"> err</span><span class="z-keyword"> !=</span><span class="z-constant"> nil</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> log</span><span>.</span><span class="z-entity z-name">Fatalf</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Failed to read compressed file </span><span class="z-constant">%s</span><span class="z-string">: </span><span class="z-constant">%v</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> os</span><span>.</span><span class="z-variable z-other">Args</span><span>[</span><span class="z-constant">2</span><span>]</span><span>,</span><span class="z-variable z-other"> err</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-variable z-other"> comp</span><span>,</span><span class="z-variable z-other"> err</span><span class="z-keyword"> :=</span><span class="z-variable z-other"> hex</span><span>.</span><span class="z-entity z-name">DecodeString</span><span>(</span><span class="z-storage z-type">string</span><span>(</span><span class="z-variable z-other">comphex</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-variable z-other"> err</span><span class="z-keyword"> !=</span><span class="z-constant"> nil</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> log</span><span>.</span><span class="z-entity z-name">Fatalf</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Failed to decode compressed file: </span><span class="z-constant">%v</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> err</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"> Make sure they match</span></span> <span class="giallo-l"><span class="z-variable z-other"> decomp</span><span>,</span><span class="z-variable z-other"> err</span><span class="z-keyword"> :=</span><span class="z-variable z-other"> snappy</span><span>.</span><span class="z-entity z-name">Decode</span><span>(</span><span class="z-constant">nil</span><span>,</span><span class="z-variable z-other"> comp</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-variable z-other"> err</span><span class="z-keyword"> !=</span><span class="z-constant"> nil</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> log</span><span>.</span><span class="z-entity z-name">Fatalf</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Failed to decompress compressed file: </span><span class="z-constant">%v</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> err</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"> !</span><span class="z-variable z-other">bytes</span><span>.</span><span class="z-entity z-name">Equal</span><span>(</span><span class="z-variable z-other">plain</span><span>,</span><span class="z-variable z-other"> decomp</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> fmt</span><span>.</span><span class="z-entity z-name">Println</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Booo, decompressed file does not match provided plain text!</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> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-variable z-other"> fmt</span><span>.</span><span class="z-entity z-name">Println</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Yay, decompressed data matched provided plain text!</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span>}</span></span></code></pre><pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> go</span><span class="z-string"> run</span><span class="z-string"> main.go</span><span class="z-string"> block.rlp</span><span class="z-string"> block.go.snappy</span></span> <span class="giallo-l"><span class="z-entity z-name">Yay,</span><span class="z-string"> decompressed</span><span class="z-string"> data</span><span class="z-string"> matched</span><span class="z-string"> provided</span><span class="z-string"> plain</span><span class="z-string"> text!</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> go</span><span class="z-string"> run</span><span class="z-string"> main.go</span><span class="z-string"> block.rlp</span><span class="z-string"> block.py.snappy</span></span> <span class="giallo-l"><span class="z-entity z-name">Yay,</span><span class="z-string"> decompressed</span><span class="z-string"> data</span><span class="z-string"> matched</span><span class="z-string"> provided</span><span class="z-string"> plain</span><span class="z-string"> text!</span></span></code></pre><h3 id="python">Python</h3> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> pip</span><span class="z-string"> install</span><span class="z-string"> python-snappy</span></span></code></pre><pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">import</span><span> snappy</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> sys</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Read and decode the decompressed file</span></span> <span class="giallo-l"><span class="z-keyword">with</span><span class="z-support"> open</span><span>(</span><span>sys</span><span>.</span><span>argv</span><span>[</span><span class="z-constant">1</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">rb</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span class="z-keyword"> as</span><span class="z-variable"> file</span><span>:</span></span> <span class="giallo-l"><span> plainhex</span><span class="z-keyword"> =</span><span class="z-variable"> file</span><span>.</span><span>read</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>plain</span><span class="z-keyword"> =</span><span> plainhex</span><span>.</span><span>decode</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">hex</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"> Read and decode the compressed file</span></span> <span class="giallo-l"><span class="z-keyword">with</span><span class="z-support"> open</span><span>(</span><span>sys</span><span>.</span><span>argv</span><span>[</span><span class="z-constant">2</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">rb</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span class="z-keyword"> as</span><span class="z-variable"> file</span><span>:</span></span> <span class="giallo-l"><span> comphex</span><span class="z-keyword"> =</span><span class="z-variable"> file</span><span>.</span><span>read</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>comp</span><span class="z-keyword"> =</span><span> comphex</span><span>.</span><span>decode</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">hex</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"> Make sure they match</span></span> <span class="giallo-l"><span>decomp</span><span class="z-keyword"> =</span><span> snappy</span><span>.</span><span>uncompress</span><span>(</span><span>comp</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">if</span><span> plain</span><span class="z-keyword"> !=</span><span> decomp</span><span>:</span></span> <span class="giallo-l"><span class="z-support"> print</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Booo, decompressed file does not match provided plain text!</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-support"> print</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Yay, decompressed data matched provided plain text!</span><span class="z-punctuation z-definition z-string">&quot;</span></span></code></pre><pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> python</span><span class="z-string"> main.py</span><span class="z-string"> block.rlp</span><span class="z-string"> block.go.snappy</span></span> <span class="giallo-l"><span class="z-entity z-name">Yay,</span><span class="z-string"> decompressed</span><span class="z-string"> data</span><span class="z-string"> matched</span><span class="z-string"> provided</span><span class="z-string"> plain</span><span class="z-string"> text!</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> python</span><span class="z-string"> main.py</span><span class="z-string"> block.rlp</span><span class="z-string"> block.py.snappy</span></span> <span class="giallo-l"><span class="z-entity z-name">Yay,</span><span class="z-string"> decompressed</span><span class="z-string"> data</span><span class="z-string"> matched</span><span class="z-string"> provided</span><span class="z-string"> plain</span><span class="z-string"> text!</span></span></code></pre><h2 id="references">References</h2> <ul> <li>Snappy website: https://google.github.io/snappy/</li> <li>Snappy specification: https://github.com/google/snappy/blob/master/format_description.txt</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> 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-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Isaac Ardisisaac.ardis@gmail.com Wei Tanghttps://github.com/sorpaas Fan Torchzhttps://github.com/tcz001 Erik Markshttps://github.com/rekmarks https://wg-eips.ritovision.com/695/ <h2 id="simple-summary">Simple Summary</h2> <p>Include <code>eth_chainId</code> method in <code>eth_</code>-namespaced JSON-RPC methods.</p> <h2 id="abstract">Abstract</h2> <p>The <code>eth_chainId</code> method should return a single STRING result for an integer value in hexadecimal format, describing the currently configured <code>CHAIN_ID</code> value used for signing replay-protected transactions, introduced by <a href="https://wg-eips.ritovision.com/155/">EIP-155</a>.</p> <h2 id="motivation">Motivation</h2> <p>Currently although we can use <code>net_version</code> RPC call to get the current network ID, there's no RPC for querying the chain ID. This makes it impossible to determine the current actual blockchain using the RPC.</p> <h2 id="specification">Specification</h2> <h3 id="eth-chainid"><code>eth_chainId</code></h3> <p>Returns the currently configured chain ID, a value used in replay-protected transaction signing as introduced by <a href="https://wg-eips.ritovision.com/155/">EIP-155</a>.</p> <p>The chain ID returned should always correspond to the information in the current known head block. This ensures that caller of this RPC method can always use the retrieved information to sign transactions built on top of the head.</p> <p>If the current known head block does not specify a chain ID, the client should treat any calls to <code>eth_chainId</code> as though the method were not supported, and return a suitable error.</p> <h4 id="parameters">Parameters</h4> <p>None.</p> <h4 id="returns">Returns</h4> <p><code>QUANTITY</code> - integer of the current chain ID.</p> <h4 id="example">Example</h4> <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_chainId&quot;,&quot;params&quot;:[],&quot;id&quot;:83}</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">83</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">0x3d</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 61</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>An ETH/ETC client can accidentally connect to an ETC/ETH RPC endpoint without knowing it unless it tries to sign a transaction or it fetches a transaction that is known to have signed with a chain ID. This has since caused trouble for application developers, such as MetaMask, to add multi-chain support.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Not relevant.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Consumers should prefer <code>eth_chainId</code> over <code>net_version</code>, so that they can reliably identify chain they are communicating with.</p> <p>Implementers should take care to implement <code>eth_chainId</code> correctly and promote its use, since the chain ID is critical in replay attack prevention as described in <a href="https://wg-eips.ritovision.com/155/">EIP-155</a>, and consumers will rely on it to identify the chain they are communicating with.</p> <h2 id="implementation">Implementation</h2> <ul> <li><a rel="external" href="https://github.com/paritytech/parity/pull/6329">Parity PR</a></li> <li><a rel="external" href="https://github.com/ethereum/go-ethereum/pull/17617">Geth PR</a></li> <li><a rel="external" href="https://github.com/ethereumproject/go-ethereum/pull/336">Geth Classic PR</a></li> </ul> <h2 id="reference">Reference</h2> <p>Return value <code>QUANTITY</code> adheres to standard JSON RPC hex value encoding, as documented in the <a rel="external" href="https://ethereum.org/en/developers/docs/apis/json-rpc/#hex-encoding">Ethereum.org documentation</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-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-08-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Daniel A. Nagyhttps://github.com/nagydani https://wg-eips.ritovision.com/681/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard way of representing various transactions, especially payment requests in ether and <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens as URLs.</p> <h2 id="abstract">Abstract</h2> <p>URLs 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 URL format for payment requests allows for instant invocation of the user's preferred wallet application (even if it is a webapp or a swarm đapp), with the correct parameterization of the payment transaction only to be confirmed by the (authenticated) user.</p> <h2 id="motivation">Motivation</h2> <p>The convenience of representing payment requests by standard URLs has been a major factor in the wide adoption of Bitcoin. Bringing a similarly convenient mechanism to Ethereum would speed up its acceptance as a payment platform among end-users. In particular, URLs embedded in broadcast Intents are the preferred way of launching applications on the Android operating system and work across practically all applications. Desktop web browsers have a standardized way of defining protocol handlers for URLs with specific protocol specifications. Other desktop applications typically launch the web browser upon encountering a URL. Thus, payment request URLs could be delivered through a very broad, ever growing selection of channels.</p> <p>This specification supersedes the defunct ERC-67, which is a URL format for representing arbitrary transactions in a low-level fashion. This ERC focuses specifically on the important special case of payment requests, while allowing for other, ABI-specified transactions.</p> <h2 id="specification">Specification</h2> <h3 id="syntax">Syntax</h3> <p>Payment request 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>request = schema_prefix target_address [ &quot;@&quot; chain_id ] [ &quot;/&quot; function_name ] [ &quot;?&quot; parameters ]</span></span> <span class="giallo-l"><span>schema_prefix = &quot;ethereum&quot; &quot;:&quot; [ &quot;pay-&quot; ]</span></span> <span class="giallo-l"><span>target_address = ethereum_address</span></span> <span class="giallo-l"><span>chain_id = 1*DIGIT</span></span> <span class="giallo-l"><span>function_name = STRING</span></span> <span class="giallo-l"><span>ethereum_address = ( &quot;0x&quot; 40*HEXDIG ) / ENS_NAME</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;value&quot; / &quot;gas&quot; / &quot;gasLimit&quot; / &quot;gasPrice&quot; / TYPE</span></span> <span class="giallo-l"><span>value = number / ethereum_address / STRING</span></span> <span class="giallo-l"><span>number = [ &quot;-&quot; / &quot;+&quot; ] *DIGIT [ &quot;.&quot; 1*DIGIT ] [ ( &quot;e&quot; / &quot;E&quot; ) [ 1*DIGIT ] ]</span></span></code></pre> <p>Where <code>TYPE</code> is a standard ABI type name, as defined in <a rel="external" href="https://solidity.readthedocs.io/en/develop/abi-spec.html">Ethereum Contract ABI specification</a>. <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>Note that a <code>number</code> can be expressed in <em>scientific notation</em>, with a multiplier of a power of 10. Only integer numbers are allowed, so the exponent MUST be greater or equal to the number of decimals after the point.</p> <p>If <em>key</em> in the parameter list is <code>value</code>, <code>gasLimit</code>, <code>gasPrice</code> or <code>gas</code> then <em>value</em> MUST be a <code>number</code>. Otherwise, it must correspond to the <code>TYPE</code> string used as <em>key</em>.</p> <p>For the syntax of ENS_NAME, please consult <a href="https://wg-eips.ritovision.com/137/">ERC-137</a> defining Ethereum Name Service.</p> <h3 id="semantics">Semantics</h3> <p><code>target_address</code> is mandatory and denotes either the beneficiary of native token payment (see below) or the contract address with which the user is asked to interact.</p> <p><code>chain_id</code> is optional and contains the decimal chain ID, such that transactions on various test- and private networks can be requested. If no <code>chain_id</code> is present, the client's current network setting remains effective.</p> <p>If <code>function_name</code> is missing, then the URL is requesting payment in the native token of the blockchain, which is ether in our case. The amount is specified in <code>value</code> parameter, in the atomic unit (i.e. wei). The use of scientific notation is strongly encouraged. For example, requesting 2.014 ETH to address <code>0xfb6916095ca1df60bb79Ce92ce3ea74c37c5d359</code> would look as follows: <a href="ethereum:0xfb6916095ca1df60bb79Ce92ce3ea74c37c5d359?value=2.014e18">ethereum:0xfb6916095ca1df60bb79Ce92ce3ea74c37c5d359?value=2.014e18</a></p> <p>Requesting payments in <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens involves a request to call the <code>transfer</code> function of the token contract with an <code>address</code> and a <code>uint256</code> typed parameter, containing the <em>beneficiary address</em> and the <em>amount in atomic units</em>, respectively. For example, requesting a Unicorn to address <code>0x8e23ee67d1332ad560396262c48ffbb01f93d052</code> looks as follows: <a href="ethereum:0x89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7/transfer?address=0x8e23ee67d1332ad560396262c48ffbb01f93d052&amp;uint256=1">ethereum:0x89205a3a3b2a69de6dbf7f01ed13b2108b2c43e7/transfer?address=0x8e23ee67d1332ad560396262c48ffbb01f93d052&amp;uint256=1</a></p> <p>If using ENS names instead of hexadecimal addresses, the resolution is up to the payer, at any time between receiving the URL and sending the transaction. Hexadecimal addresses always take precedence over ENS names, i. e. even if there exists a matching ENS name consisting of <code>0x</code> followed by 40 hexadecimal digits, it should never be resolved. Instead, the hexadecimal address should be used directly.</p> <p>Note that the indicated amount is only a suggestion (as are all the supplied arguments) which the user is free to change. With no indicated amount, the user should be prompted to enter the amount to be paid.</p> <p>Similarly <code>gasLimit</code> and <code>gasPrice</code> are suggested user-editable values for <em>gas limit</em> and <em>gas price</em>, respectively, for the requested transaction. It is acceptable to abbreviate <code>gasLimit</code> as <code>gas</code>, the two are treated synonymously.</p> <h2 id="rationale">Rationale</h2> <p>The proposed format is chosen to resemble <code>bitcoin:</code> URLs as closely as possible, as both users and application programmers are already familiar with that format. In particular, this motivated the omission of the unit, which is often used in Ethereum ecosystem. Handling different orders of magnitude is facilitated by the exponent so that amount values can be expressed in their nominal units, just like in the case of <code>bitcoin:</code>. The use of scientific notation is strongly encouraged when expressing monetary value in ether or <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens. For better human readability, the exponent should be the decimal value of the nominal unit: 18 for ether or the value returned by <code>decimals()</code> of the token contract for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens. Additional parameters may be added, if popular use cases requiring them emerge in practice.</p> <p>The <code>0x</code> prefix before ethereum addresses specified as hexadecimal numbers is following established practice and also unambiguously distinguishes hexadecimal addresses from ENS names consisting of 40 alphanumeric characters.</p> <p>Future upgrades that are partially or fully incompatible with this proposal must use a prefix other than <code>pay-</code> that is separated by a dash (<code>-</code>) character from whatever follows it.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>In the fairly common case of only indicating the recipient address in a request for payment in ether, this specification is compatible with the superseded ERC-67.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Since irreversible transactions can be initiated with parameters from such URLs, the integrity and authenticity of these URLs are of great importance. In particular, changing either the recipient address or the amount transferred can be a profitable attack. Users should only use URLs received from authenticated sources with adequate integrity protection.</p> <p>To prevent malicious redirection of payments using ENS, hexadecimal interpretation of Ethereum addresses must have precedence over ENS lookups. Client software may alert the user if an ENS address is visually similar to a hexadecimal address or even outright reject such addresses as likely phishing attacks.</p> <p>In order to make sure that the amount transacted is the same as the amount intended, the amount communicated to the human user should be easily verifiable by inspection, including the order of magnitude. In case of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token payments, if the payer client has access to the blockchain or some other trusted source of information about the token contract, the interface should display the amount in the units specified in the token contract. Otherwise, it should be displayed as expressed in the URL, possibly alerting the user to the uncertainty of the nominal unit. To facilitate human inspection of the amount, the use of scientific notation with an exponent corresponding to the nominal unit of the transacted token (e.g. 18 in case of ether) is advisable.</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-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-06-30T00:00:00+00:00 2026-02-11T14:49:27+00:00 Nick Johnsonnick@ethereum.org https://wg-eips.ritovision.com/658/ <h2 id="abstract">Abstract</h2> <p>This EIP replaces the intermediate state root field of the receipt with a status code indicating if the top-level call succeeded or failed.</p> <h2 id="motivation">Motivation</h2> <p>With the introduction of the REVERT opcode in EIP140, it is no longer possible for users to assume that a transaction failed iff it consumed all gas. As a result, there is no clear mechanism for callers to determine whether a transaction succeeded and the state changes contained in it were applied.</p> <p>Full nodes can provide RPCs to get a transaction return status and value by replaying the transaction, but fast nodes can only do this for nodes after their pivot point, and light nodes cannot do this at all, making a non-consensus solution impractical.</p> <p>Instead, we propose to replace the intermediate state root, already obsoleted by EIP98, with the return status (1 for success, 0 for failure). This both allows callers to determine success status, and remedies the previous omission of return data from the receipt.</p> <h2 id="specification">Specification</h2> <p>For blocks where block.number &gt;= BYZANTIUM_FORK_BLKNUM, the intermediate state root is replaced by a status code, 0 indicating failure (due to any operation that can cause the transaction or top-level call to revert) and 1 indicating success.</p> <h2 id="rationale">Rationale</h2> <p>This constitutes a minimal possible change that permits fetching the success/failure state of transactions, preserving existing capabilities with minimum disruption or additional work for Metropolis.</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-06-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Afri Schoedonhttps://github.com/5chdn Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/649/ <h2 id="simple-summary">Simple Summary</h2> <p>The average block times are increasing due to the difficulty bomb (also known as the "<em>ice age</em>") slowly accelerating. This EIP proposes to delay the difficulty bomb for approximately one and a half year and to reduce the block rewards with the Byzantium fork, the first part of the Metropolis fork.</p> <h2 id="abstract">Abstract</h2> <p>Starting with <code>BYZANTIUM_FORK_BLKNUM</code> the client will calculate the difficulty based on a fake block number suggesting the client that the difficulty bomb is adjusting around 3 million blocks later than previously specified with the Homestead fork. Furthermore, block rewards will be adjusted to a base of 3 ETH, uncle and nephew rewards will be adjusted accordingly.</p> <h2 id="motivation">Motivation</h2> <p>The Casper development and switch to proof-of-stake is delayed, the Ethash proof-of-work should be feasible for miners and allow sealing new blocks every 15 seconds on average for another one and a half years. With the delay of the ice age, there is a desire to not suddenly also increase miner rewards. The difficulty bomb has been known about for a long time and now it's going to stop from happening. In order to maintain stability of the system, a block reward reduction that offsets the ice age delay would leave the system in the same general state as before. 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="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 - 3_000_000) if block.number &gt;= BYZANTIUM_FORK_BLKNUM else block.number</span></span></code></pre><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 = 3_000_000_000_000_000_000 if block.number &gt;= BYZANTIUM_FORK_BLKNUM else block.reward</span></span></code></pre> <p>(3E18 wei, or 3,000,000,000,000,000,000 wei, or 3 ETH).</p> <p>Analogue, if an uncle is included in a block for <code>block.number &gt;= BYZANTIUM_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-Metropolis formula for uncle rewards, simply adjusted with <code>new_block_reward</code>.</p> <p>The nephew reward for <code>block.number &gt;= BYZANTIUM_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-Metropolis formula for nephew rewards, simply adjusted with <code>new_block_reward</code>.</p> <h2 id="rationale">Rationale</h2> <p>This will delay the ice age by 42 million seconds (approximately 1.4 years), so the chain would be back at 30 second block times at the end of 2018. An alternate proposal was to add special rules to the difficulty calculation to effectively <em>pause</em> the difficulty between different blocks. This would lead to similar results.</p> <p>This was previously discussed at All Core Devs Meeting <a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%209.md#metropolis-timing-and-roadmap-discussion">#09</a>, <a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%2012.md#5-metropolis-update">#12</a>, <a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%2013.md#3-eip-186-reduce-eth-issuance-before-proof-of-stake-hudson">#13</a>, and <a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%2014.md#1-eip-186-reduce-eth-issuance-before-proof-of-stake-core-devs">#14</a>. Consensus on the specification was achieved in All Core Devs Meeting <a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%2019.md">#19</a> and specification drafted in EIP issue <a rel="external" href="https://github.com/ethereum/EIPs/issues/649">#649</a>. It was decided to replace EIP <a rel="external" href="https://github.com/ethereum/EIPs/issues/186">#186</a> and include the block reward reduction along with the difficulty bomb delay in All Core Devs Meeting <a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%2020.md">#20</a> and <a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%2021.md">#21</a>; accepted in <a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%2022.md">#22</a>.</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 first of the two Metropolis hard-forks, the <em>Byzantium</em> fork.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases exist in ethereum/tests <a rel="external" href="https://github.com/ethereum/tests/pull/269">#269</a>.</p> <h2 id="implementation">Implementation</h2> <p>The following clients implemented EIP-649:</p> <ul> <li>Geth <a rel="external" href="https://github.com/ethereum/go-ethereum/pull/15028">#15028</a></li> <li>Parity <a rel="external" href="https://github.com/paritytech/parity/pull/5855">#5855</a></li> <li>EthereumJ <a rel="external" href="https://github.com/ethereum/ethereumj/pull/927">#927</a></li> <li>Cpp-Ethereum <a rel="external" href="https://github.com/ethereum/cpp-ethereum/issues/4050">#4050</a></li> <li>PyEthereum <a rel="external" href="https://github.com/ethereum/pyethereum/pull/383">#383</a></li> </ul> <p>The Yellow Paper implements EIP-649 in <a rel="external" href="https://github.com/ethereum/yellowpaper/pull/333">#333</a>.</p> <p>Other notable implementations:</p> <ul> <li>Eth-Isabelle <a rel="external" href="https://github.com/pirapira/eth-isabelle/issues/459">#459</a></li> <li>Py-EVM <a rel="external" href="https://github.com/ethereum/py-evm/pull/123">#123</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> 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-05-05T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vlad Gluhovskygluk256@gmail.com https://wg-eips.ritovision.com/627/ <h2 id="abstract">Abstract</h2> <p>This EIP describes the format of Whisper messages within the ÐΞVp2p Wire Protocol. This EIP should substitute the <a rel="external" href="https://github.com/ethereum/wiki/wiki/Whisper-Wire-Protocol">existing specification</a>. More detailed documentation on Whisper could be found <a rel="external" href="https://github.com/ethereum/go-ethereum/wiki/Whisper">here</a>.</p> <h2 id="motivation">Motivation</h2> <p>It is necessary to specify the standard for Whisper messages in order to ensure forward compatibility of different Whisper clients.</p> <h2 id="specification">Specification</h2> <p>All Whisper messages sent as ÐΞVp2p Wire Protocol packets should be RLP-encoded arrays of data containing two objects: integer packet code followed by another object (whose type depends on the packet code).</p> <p>If Whisper node does not support a particular packet code, it should just ignore the packet without generating any error.</p> <h3 id="packet-codes">Packet Codes</h3> <p>The message codes reserved for Whisper protocol: 0 - 127. Messages with unknown codes must be ignored, for forward compatibility of future versions.</p> <p>The Whisper sub-protocol should support the following packet codes:</p> <table><thead><tr><th>EIP</th><th>Name</th><th>Int Value</th></tr></thead><tbody> <tr><td></td><td>Status</td><td>0</td></tr> <tr><td></td><td>Messages</td><td>1</td></tr> <tr><td></td><td>PoW Requirement</td><td>2</td></tr> <tr><td></td><td>Bloom Filter</td><td>3</td></tr> <tr><td>-------</td><td>----------------------------</td><td>-----------</td></tr> </tbody></table> <p>The following message codes are optional, but they are reserved for specific purpose.</p> <table><thead><tr><th>EIP</th><th>Name</th><th>Int Value</th></tr></thead><tbody> <tr><td></td><td>P2P Request</td><td>126</td></tr> <tr><td></td><td>P2P Message</td><td>127</td></tr> <tr><td>-------</td><td>----------------------------</td><td>-----------</td></tr> </tbody></table> <h3 id="packet-format-and-usage">Packet Format and Usage</h3> <p><strong>Status</strong> [<code>0</code>]</p> <p>This packet contains two objects: integer message code (0x00) followed by a list of values: integer version, float PoW requirement, and bloom filter, in this order. The bloom filter parameter is optional; if it is missing or nil, the node is considered to be full node (i.e. accepts all messages). The format of PoW and bloom filter please see below (message codes 2 and 3).</p> <p>Status message should be sent after the initial handshake and prior to any other messages.</p> <p><strong>Messages</strong> [<code>1</code>, <code>whisper_envelopes</code>]</p> <p>This packet contains two objects: integer message code (0x01) followed by a list (possibly empty) of Whisper Envelopes.</p> <p>This packet is used for sending the standard Whisper envelopes.</p> <p><strong>PoW Requirement</strong> [<code>2</code>, <code>PoW</code>]</p> <p>This packet contains two objects: integer message code (0x02) followed by a single floating point value of PoW. This value is the IEEE 754 binary representation of 64-bit floating point number. Values of qNAN, sNAN, INF and -INF are not allowed. Negative values are also not allowed.</p> <p>This packet is used by Whisper nodes for dynamic adjustment of their individual PoW requirements. Recipient of this message should no longer deliver the sender messages with PoW lower than specified in this message.</p> <p>PoW is defined as average number of iterations, required to find the current BestBit (the number of leading zero bits in the hash), divided by message size and TTL:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PoW = (2**BestBit) / (size * TTL)</span></span></code></pre> <p>PoW calculation:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>fn short_rlp(envelope) = rlp of envelope, excluding env_nonce field.</span></span> <span class="giallo-l"><span>fn pow_hash(envelope, env_nonce) = sha3(short_rlp(envelope) ++ env_nonce)</span></span> <span class="giallo-l"><span>fn pow(pow_hash, size, ttl) = 2**leading_zeros(pow_hash) / (size * ttl)</span></span></code></pre> <p>where size is the size of the full RLP-encoded envelope.</p> <p><strong>Bloom Filter</strong> [<code>3</code>, <code>bytes</code>]</p> <p>This packet contains two objects: integer message code (0x03) followed by a byte array of arbitrary size.</p> <p>This packet is used by Whisper nodes for sharing their interest in messages with specific topics.</p> <p>The Bloom filter is used to identify a number of topics to a peer without compromising (too much) privacy over precisely what topics are of interest. Precise control over the information content (and thus efficiency of the filter) may be maintained through the addition of bits.</p> <p>Blooms are formed by the bitwise OR operation on a number of bloomed topics. The bloom function takes the topic and projects them onto a 512-bit slice. At most, three bits are marked for each bloomed topic.</p> <p>The projection function is defined as a mapping from a 4-byte slice S to a 512-bit slice D; for ease of explanation, S will dereference to bytes, whereas D will dereference to bits.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>LET D[*] = 0</span></span> <span class="giallo-l"><span>FOREACH i IN { 0, 1, 2 } DO</span></span> <span class="giallo-l"><span>LET n = S[i]</span></span> <span class="giallo-l"><span>IF S[3] &amp; (2 ** i) THEN n += 256</span></span> <span class="giallo-l"><span>D[n] = 1</span></span> <span class="giallo-l"><span>END FOR</span></span></code></pre> <p>OPTIONAL</p> <p><strong>P2P Request</strong> [<code>126</code>, <code>whisper_envelope</code>]</p> <p>This packet contains two objects: integer message code (0x7E) followed by a single Whisper Envelope.</p> <p>This packet is used for sending Dapp-level peer-to-peer requests, e.g. Whisper Mail Client requesting old messages from the Whisper Mail Server.</p> <p><strong>P2P Message</strong> [<code>127</code>, <code>whisper_envelope</code>]</p> <p>This packet contains two objects: integer message code (0x7F) followed by a single Whisper Envelope.</p> <p>This packet is used for sending the peer-to-peer messages, which are not supposed to be forwarded any further. E.g. it might be used by the Whisper Mail Server for delivery of old (expired) messages, which is otherwise not allowed.</p> <h3 id="whisper-envelope">Whisper Envelope</h3> <p>Envelopes are RLP-encoded structures of the following format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[ Expiry, TTL, Topic, Data, Nonce ]</span></span></code></pre> <p><code>Expiry</code>: 4 bytes (UNIX time in seconds).</p> <p><code>TTL</code>: 4 bytes (time-to-live in seconds).</p> <p><code>Topic</code>: 4 bytes of arbitrary data.</p> <p><code>Data</code>: byte array of arbitrary size (contains encrypted message).</p> <p><code>Nonce</code>: 8 bytes of arbitrary data (used for PoW calculation).</p> <h3 id="contents-of-data-field-of-the-message-optional">Contents of Data Field of the Message (Optional)</h3> <p>This section outlines the optional description of Data Field to set up an example. Later it may be moved to a separate EIP.</p> <p>It is only relevant if you want to decrypt the incoming message, but if you only want to send a message, any other format would be perfectly valid and must be forwarded to the peers.</p> <p>Data field contains encrypted message of the Envelope. In case of symmetric encryption, it also contains appended Salt (a.k.a. AES Nonce, 12 bytes). Plaintext (unencrypted) payload consists of the following concatenated fields: flags, auxiliary field, payload, padding and signature (in this sequence).</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>flags: 1 byte; first two bits contain the size of auxiliary field, third bit indicates whether the signature is present.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>auxiliary field: up to 4 bytes; contains the size of payload.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>payload: byte array of arbitrary size (may be zero).</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>padding: byte array of arbitrary size (may be zero).</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>signature: 65 bytes, if present.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>salt: 12 bytes, if present (in case of symmetric encryption).</span></span></code></pre> <p>Those unable to decrypt the message data are also unable to access the signature. The signature, if provided, is the ECDSA signature of the Keccak-256 hash of the unencrypted data using the secret key of the originator identity. The signature is serialised as the concatenation of the <code>R</code>, <code>S</code> and <code>V</code> parameters of the SECP-256k1 ECDSA signature, in that order. <code>R</code> and <code>S</code> are both big-endian encoded, fixed-width 256-bit unsigned. <code>V</code> is an 8-bit big-endian encoded, non-normalised and should be either 27 or 28.</p> <p>The padding field was introduced in order to align the message size, since message size alone might reveal important metainformation. Padding can be arbitrary size. However, it is recommended that the size of Data Field (excluding the Salt) before encryption (i.e. plain text) should be factor of 256 bytes.</p> <h3 id="payload-encryption">Payload Encryption</h3> <p>Asymmetric encryption uses the standard Elliptic Curve Integrated Encryption Scheme with SECP-256k1 public key.</p> <p>Symmetric encryption uses AES GCM algorithm with random 96-bit nonce.</p> <h2 id="rationale">Rationale</h2> <p>Packet codes 0x00 and 0x01 are already used in all Whisper versions.</p> <p>Packet code 0x02 will be necessary for the future development of Whisper. It will provide possibility to adjust the PoW requirement in real time. It is better to allow the network to govern itself, rather than hardcode any specific value for minimal PoW requirement.</p> <p>Packet code 0x03 will be necessary for scalability of the network. In case of too much traffic, the nodes will be able to request and receive only the messages they are interested in.</p> <p>Packet codes 0x7E and 0x7F may be used to implement Whisper Mail Server and Client. Without P2P messages it would be impossible to deliver the old messages, since they will be recognized as expired, and the peer will be disconnected for violating the Whisper protocol. They might be useful for other purposes when it is not possible to spend time on PoW, e.g. if a stock exchange will want to provide live feed about the latest trades.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is compatible with Whisper version 6. Any client which does not implement certain packet codes should gracefully ignore the packets with those codes. This will ensure the forward compatibility.</p> <h2 id="implementation">Implementation</h2> <p>The golang implementation of Whisper (v.6) already uses packet codes 0x00 - 0x03. Parity's implementation of v.6 will also use codes 0x00 - 0x03. Codes 0x7E and 0x7F are reserved, but still unused and left for custom implementation of Whisper Mail Server.</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-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Dexaranhttps://github.com/Dexarandexaran@ethereumclassic.org https://wg-eips.ritovision.com/223/

Token with transaction handling model designed to behave identical to native currency (ether)

<h2 id="abstract">Abstract</h2> <p>The following describes an interface and logic for fungible tokens that supports a <code>tokenReceived</code> callback to notify contract recipients when tokens are received. This makes tokens behave identical to ether.</p> <h2 id="motivation">Motivation</h2> <p>This token introduces a communication model for contracts that can be utilized to straighten the behavior of contracts that interact with such tokens. Specifically, this proposal:</p> <ol> <li>Informs receiving contracts of incoming token transfers, as opposed to <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> where the recipient of a token transfer gets no notification.</li> <li>Is more gas-efficient when depositing tokens to contracts.</li> <li>Allows for <code>_data</code> recording for financial transfers.</li> </ol> <h2 id="specification">Specification</h2> <p>Contracts intending to receive these tokens MUST implement <code>tokenReceived</code>.</p> <p>Token transfers to contracts not implementing <code>tokenReceived</code> as described below MUST revert.</p> <h3 id="token-contract">Token contract</h3> <h4 id="token-methods">Token Methods</h4> <h5 id="totalsupply"><code>totalSupply</code></h5> <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"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span></span></code></pre> <p>Returns the total supply of the token. The functionality of this method is identical to that of ERC-20.</p> <h5 id="name"><code>name</code></h5> <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-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></code></pre> <p>Returns the name of the token. The functionality of this method is identical to that of ERC-20.</p> <p>OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present.</p> <h5 id="symbol"><code>symbol</code></h5> <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-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></code></pre> <p>Returns the symbol of the token. The functionality of this method is identical to that of ERC-20.</p> <p>OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present.</p> <h5 id="decimals"><code>decimals</code></h5> <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"> decimals</span><span>(</span><span>)</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></code></pre> <p>Returns the number of decimals of the token. The functionality of this method is identical to that of ERC-20.</p> <p>OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present.</p> <h5 id="balanceof"><code>balanceOf</code></h5> <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-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>Returns the account balance of another account with address <code>_owner</code>. The functionality of this method is identical to that of ERC-20.</p> <h5 id="transfer-address-uint"><code>transfer(address, uint)</code></h5> <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"> uint</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span></span></code></pre> <p>This function must transfer tokens, and if <code>_to</code> is a contract, it must call the <code>tokenReceived(address, uint256, bytes calldata)</code> function of <code>_to</code>. If the <code>tokenReceived</code> function is not implemented in <code>_to</code> (recipient contract), then the transaction must fail and the transfer of tokens must be reverted. If <code>_to</code> is an externally owned address, then the transaction must be sent without executing <code>tokenReceived</code> in <code>_to</code>. <code>_data</code> can be attached to this token transaction, but it requires more gas. <code>_data</code> can be empty.</p> <p>The <code>tokenReceived</code> function of <code>_to</code> MUST be called after all other operations to avoid re-entrancy attacks.</p> <p>NOTE: If <code>transfer</code> function is <code>payable</code> and ether was deposited then the amount of deposited ether MUST be delivered to <code>_to</code> address alongside tokens. If ether was sent alongside tokens in this way then ether MUST be delivered first, then token balances must be updated, then <code>tokenReceived</code> function MUST be called in <code>_to</code> if it is a contract.</p> <h5 id="transfer-address-uint-bytes"><code>transfer(address, uint, bytes)</code></h5> <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"> uint</span><span class="z-variable z-parameter z-function"> _value</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-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span></span></code></pre> <p>This function must transfer tokens and invoke the function <code>tokenReceived (address, uint256, bytes)</code> in <code>_to</code>, if <code>_to</code> is a contract. If the <code>tokenReceived</code> function is not implemented in <code>_to</code> (recipient contract), then the transaction must fail and the transfer of tokens must not occur. If <code>_to</code> is an externally owned address (determined by the code size being zero), then the transaction must be sent without executing <code>tokenReceived</code> in <code>_to</code>. <code>_data</code> can be attached to this token transaction, but it requires more gas. <code>_data</code> can be empty.</p> <p>NOTE: A possible 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. If <code>transfer</code> function is <code>payable</code> and ether was deposited then the amount of deposited ether MUST be delivered to <code>_to</code> address alongside tokens.</p> <p>The <code>tokenReceived</code> function of <code>_to</code> MUST be called after all other operations to avoid re-entrancy attacks.</p> <h4 id="events">Events</h4> <h5 id="transfer"><code>Transfer</code></h5> <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"> _value</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> _data</span><span>)</span></span></code></pre> <p>Triggered when tokens are transferred. Compatible with and similar to the ERC-20 <code>Transfer</code> event.</p> <h3 id="erc-223-token-receiver"><a href="https://wg-eips.ritovision.com/223/">ERC-223</a> Token Receiver</h3> <h4 id="receiver-methods">Receiver Methods</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"> tokenReceived</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"> uint</span><span class="z-variable z-parameter z-function"> _value</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-keyword"> returns</span><span> (</span><span class="z-support">bytes4</span><span>)</span></span></code></pre> <p>A function for handling token transfers, which is called from the token contract, when a token holder sends tokens. <code>_from</code> is the address of the sender of the token, <code>_value</code> is the amount of incoming tokens, and <code>_data</code> is attached data similar to <code>msg.data</code> of ether transactions. It works by analogy with the fallback function of Ether transactions and returns nothing.</p> <p>NOTE: <code>msg.sender</code> will be a token-contract inside the <code>tokenReceived</code> function. It may be important to filter which tokens were sent (by token-contract address). The token sender (the person who initiated the token transaction) will be <code>_from</code> inside the <code>tokenReceived</code> function. The <code>tokenReceived</code> function must return <code>0x8943ec02</code> after handling an incoming token transfer. The <code>tokenReceived</code> function call can be handled by the fallback function of the recipient contact (and in this case it may not return the magic value 0x8943ec02).</p> <p>IMPORTANT: This function must be named <code>tokenReceived</code> and take parameters <code>address</code>, <code>uint256</code>, <code>bytes</code> to match the function signature <code>0x8943ec02</code>. This function can be manually called by a EOA.</p> <h2 id="rationale">Rationale</h2> <p>This standard introduces a communication model by enforcing the <code>transfer</code> to execute a handler function in the destination address. This is an important security consideration as it is required that the receiver explicitly implements the token handling function. In cases where the receiver does not implements such function the transfer MUST be reverted.</p> <p>This standard sticks to the push transaction model where the transfer of assets is initiated on the senders side and handled on the receivers side. As the result, ERC-223 transfers are more gas-efficient while dealing with depositing to contracts as ERC-223 tokens can be deposited with just one transaction while ERC-20 tokens require at least two calls (one for <code>approve</code> and the second that will invoke <code>transferFrom</code>).</p> <ul> <li> <p><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> deposit: <code>approve</code> ~46 gas, <code>transferFrom</code> ~75K gas</p> </li> <li> <p>ERC-223 deposit: <code>transfer</code> and handling on the receivers side ~54K gas</p> </li> </ul> <p>This standard introduces the ability to correct user errors by allowing to handle ANY transactions on the recipients side and reject incorrect or improper transfers. This tokens utilize ONE transferring method for both types of interactions with contracts and externally owned addresses which can simplify the user experience and allow to avoid possible user mistakes.</p> <p>One downside of the commonly used <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard that ERC-223 is intended to solve is that <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> implements two methods of token transferring: (1) <code>transfer</code> function and (2) <code>approve + transferFrom</code> pattern. Transfer function of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard does not notify the receiver and therefore if any tokens are sent to a contract with the <code>transfer</code> function then the receiver will not recognize this transfer and the tokens can become stuck in the receivers address without any possibility of recovering them. <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard places the burden of determining the transferring method on the user and if the incorrect method is chosen the user can lose the transferred tokens. ERC-223 automatically determines the transferring method, preventing the user from losing tokens due to choosing wrong method.</p> <p>ERC-223 is intended to simplify the interaction with contracts that are intended to work with tokens. ERC-223 utilizes a "deposit" pattern, similar to that of plain Ether. An ERC-223 deposit to a contract is a simple call of the <code>transfer</code> function. This is one transaction as opposed to two step process of <code>approve + transferFrom</code> depositing.</p> <p>This standard allows payloads to be attached to transactions using the <code>bytes calldata _data</code> parameter, which can encode a second function call in the destination address, similar to how <code>msg.data</code> does in an ether transaction, or allow for public logging on chain should it be necessary for financial transactions.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The interface of this token is similar to that of ERC-20 and most functions serve the same purpose as their analogues in ERC-20. <code>transfer(address, uint256, bytes calldata)</code> function is not backwards compatible with ERC-20 interface.</p> <p>ERC-20 tokens can be delivered to a non-contract address with <code>transfer</code> function. ERC-20 tokens can be deposited to a contract address with <code>approve</code> + <code>transferFrom</code> pattern. Depositing ERC-20 tokens to the contract address with <code>transfer</code> function will always result in token deposit not being recognized by the recipient contract.</p> <p>Here is an example of the contract code that handles ERC-20 token deposit. The following contract can accepts <code>tokenA</code> deposits. It is impossible to prevent deposits of non-tokenA to this contract. If tokenA is deposited with <code>transfer</code> function then it will result in a loss of tokens for the depositor because the balance of the user will be decreased in the contract of tokenA but the value of <code>deposits</code> variable in the <code>ERC20Receiver</code> will not be increased i.e. the deposit will not be credited. As of 5/9/2023 <strong>$201M worth of 50 examined ERC-20 tokens are already lost</strong> in this way on Ethereum mainnet.</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"> ERC20Receiver</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> tokenA</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> deposits</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">uint</span><span class="z-variable z-parameter z-function"> _value</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> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_token </span><span class="z-keyword">==</span><span> tokenA</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC20</span><span>(</span><span>_token</span><span>)</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> deposits</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> _value</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>ERC-223 tokens must be delivered to non-contract address or contract address in the same way with <code>transfer</code> function.</p> <p>Here is an example of the contract code that handles ERC-223 token deposit. The following contract can filter tokens and only accepts <code>tokenA</code>. Other ERC-223 tokens would be rejected.</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"> ERC223Receiver</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> tokenA</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> deposits</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenReceived</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"> uint</span><span class="z-variable z-parameter z-function"> _value</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"> _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 class="giallo-l"><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> tokenA</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> deposits</span><span>[</span><span>_from</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> _value</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 0x8943ec02</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 token utilizes the model similar to plain ether behavior. Therefore replay issues must be taken into account.</p> <h3 id="reference-implementation">Reference Implementation</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.19</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"> Address</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"> Returns true if `account` is a contract.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * This test is non-exhaustive, and there may be false-negatives: during the</span></span> <span class="giallo-l"><span class="z-comment"> * execution of a contract&#39;s constructor, its address will be reported as</span></span> <span class="giallo-l"><span class="z-comment"> * not containing a contract.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * &gt; It is unsafe to assume that an address for which this function returns</span></span> <span class="giallo-l"><span class="z-comment"> * false is an externally-owned account (EOA) and not a 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"> isContract</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</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-comment"> //</span><span class="z-comment"> This method relies in extcodesize, which returns 0 for contracts in</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> construction, since the code is only stored at the end of the</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> constructor execution.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> size</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-keyword"> solhint-disable</span><span class="z-comment">-next-line no-inline-assembly</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span><span> size </span><span class="z-keyword">:=</span><span class="z-entity z-name"> extcodesize</span><span>(</span><span>account</span><span>)</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> size </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> <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"> IERC223Recipient</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"> Standard ERC-223 receiving function that will handle incoming token transfers.</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"> _from</span><span class="z-comment"> Token sender 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"> _value</span><span class="z-comment"> Amount of 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"> _data</span><span class="z-comment"> Transaction metadata.</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"> tokenReceived</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"> uint</span><span class="z-variable z-parameter z-function"> _value</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"> _data</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">bytes4</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">@title</span><span class="z-comment"> Reference implementation of the ERC223 standard token.</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"> ERC223Token</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"> Event that is fired on successful transfer.</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">uint</span><span class="z-variable"> value</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-support"> string</span><span class="z-storage z-type"> private</span><span> _name</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> private</span><span> _symbol</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-storage z-type"> private</span><span> _decimals</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> _totalSupply</span><span>;</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">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> balances</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> List of user balances.</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 the values for {name} and {symbol}, initializes {decimals} with</span></span> <span class="giallo-l"><span class="z-comment"> * a default value of 18.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * To select a different value for {decimals}, use {_setupDecimals}.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * All three of these values are immutable: they can only be set once during</span></span> <span class="giallo-l"><span class="z-comment"> * construction.</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-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"> new_name</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> new_symbol</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> new_decimals</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> _name </span><span class="z-keyword">=</span><span> new_name</span><span>;</span></span> <span class="giallo-l"><span> _symbol </span><span class="z-keyword">=</span><span> new_symbol</span><span>;</span></span> <span class="giallo-l"><span> _decimals </span><span class="z-keyword">=</span><span> new_decimals</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 name of 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"> name</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">string</span><span class="z-storage z-type"> memory</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _name</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 symbol of the token, usually a shorter version of the</span></span> <span class="giallo-l"><span class="z-comment"> * name.</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"> 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 class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _symbol</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 number of decimals used to get its user representation.</span></span> <span class="giallo-l"><span class="z-comment"> * For example, if `decimals` equals `2`, a balance of `505` tokens should</span></span> <span class="giallo-l"><span class="z-comment"> * be displayed to a user as `5,05` (`505 / 10 ** 2`).</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Tokens usually opt for a value of 18, imitating the relationship between</span></span> <span class="giallo-l"><span class="z-comment"> * Ether and Wei. This is the value {ERC223} uses, unless {_setupDecimals} is</span></span> <span class="giallo-l"><span class="z-comment"> * called.</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">: This information is only used for _display_ purposes: it in</span></span> <span class="giallo-l"><span class="z-comment"> * no way affects any of the arithmetic of the contract, including</span></span> <span class="giallo-l"><span class="z-comment"> * {IERC223-balanceOf} and {IERC223-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"> 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 class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _decimals</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 {IERC223-totalSupply}.</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>)</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> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _totalSupply</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 {IERC223-standard}.</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"> standard</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">string</span><span class="z-storage z-type"> memory</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-string"> &quot;223&quot;</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"> Returns balance of the `_owner`.</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"> _owner</span><span class="z-comment"> The address whose balance will 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"> balance</span><span class="z-comment"> Balance of the `_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"> 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 class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> balances</span><span>[</span><span>_owner</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"> Transfer the specified amount of tokens to the specified address.</span></span> <span class="giallo-l"><span class="z-comment"> * Invokes the `tokenFallback` function if the recipient is a contract.</span></span> <span class="giallo-l"><span class="z-comment"> * The token transfer fails if the recipient is a contract</span></span> <span class="giallo-l"><span class="z-comment"> * but does not implement the `tokenFallback` function</span></span> <span class="giallo-l"><span class="z-comment"> * or the fallback function to receive funds.</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"> _to</span><span class="z-comment"> Receiver 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"> _value</span><span class="z-comment"> Amount of tokens that will be transferred.</span></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"> Transaction metadata.</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"> uint</span><span class="z-variable z-parameter z-function"> _value</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"> 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 class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Standard function transfer similar to ERC20 transfer with no _data .</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Added due to backwards compatibility reasons .</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 class="z-keyword"> -</span><span> _value</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 class="z-keyword"> +</span><span> _value</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>Address</span><span>.</span><span class="z-entity z-name">isContract</span><span>(</span><span>_to</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC223Recipient</span><span>(</span><span>_to</span><span>)</span><span>.</span><span class="z-entity z-name">tokenReceived</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> _value</span><span>,</span><span> _data</span><span>)</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> _value</span><span>,</span><span> _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> <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"> Transfer the specified amount of tokens to the specified address.</span></span> <span class="giallo-l"><span class="z-comment"> * This function works the same with the previous one</span></span> <span class="giallo-l"><span class="z-comment"> * but doesn&#39;t contain `_data` param.</span></span> <span class="giallo-l"><span class="z-comment"> * Added due to backwards compatibility reasons.</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"> _to</span><span class="z-comment"> Receiver 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"> _value</span><span class="z-comment"> Amount of tokens that will be transferred.</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"> uint</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 class="z-variable"> success</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> _empty </span><span class="z-keyword">=</span><span> hex</span><span class="z-string">&quot;00000000&quot;</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 class="z-keyword"> -</span><span> _value</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 class="z-keyword"> +</span><span> _value</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>Address</span><span>.</span><span class="z-entity z-name">isContract</span><span>(</span><span>_to</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC223Recipient</span><span>(</span><span>_to</span><span>)</span><span>.</span><span class="z-entity z-name">tokenReceived</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> _value</span><span>,</span><span> _empty</span><span>)</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> _value</span><span>,</span><span> _empty</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></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> 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-04-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Johnsonhttps://github.com/arachnid Micah Zoltuhttps://github.com/micahzoltu https://wg-eips.ritovision.com/600/ <h2 id="abstract">Abstract</h2> <p>This EIP defines a logical hierarchy for deterministic wallets based on <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki">BIP32</a>, the purpose scheme defined in <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki">BIP43</a> and <a rel="external" href="https://github.com/bitcoin/bips/pull/523">this proposed change to BIP43</a>.</p> <p>This EIP is a particular application of BIP43.</p> <h2 id="motivation">Motivation</h2> <p>Because Ethereum is based on account balances rather than UTXO, the hierarchy defined by BIP44 is poorly suited. As a result, several competing derivation path strategies have sprung up for deterministic wallets, resulting in inter-client incompatibility. This BIP seeks to provide a path to standardise this in a fashion better suited to Ethereum's unique requirements.</p> <h2 id="specification">Specification</h2> <p>We define the following 2 levels in BIP32 path:</p> <pre> m / purpose' / subpurpose' / EIP' </pre> <p>Apostrophe in the path indicates that BIP32 hardened derivation is used.</p> <p>Each level has a special meaning, described in the chapters below.</p> <h3 id="purpose">Purpose</h3> <p>Purpose is set to 43, as documented in <a rel="external" href="https://github.com/bitcoin/bips/pull/523">this proposed change to BIP43</a>.</p> <p>The purpose field indicates that this path is for a non-bitcoin cryptocurrency.</p> <p>Hardened derivation is used at this level.</p> <h3 id="subpurpose">Subpurpose</h3> <p>Subpurpose is set to 60, the SLIP-44 code for Ethereum.</p> <p>Hardened derivation is used at this level.</p> <h3 id="eip">EIP</h3> <p>EIP is set to the EIP number specifying the remainder of the BIP32 derivation path. This permits new Ethereum-focused applications of deterministic wallets without needing to interface with the BIP process.</p> <p>Hardened derivation is used at this level.</p> <h2 id="rationale">Rationale</h2> <p>The existing convention is to use the 'Ethereum' coin type, leading to paths starting with <code>m/44'/60'/*</code>. Because this still assumes a UTXO-based coin, we contend that this is a poor fit, resulting in standardisation, usability, and security compromises. As a result, we are making the above proposal to define an entirely new hierarchy for Ethereum-based chains.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The introduction of another derivation path requires existing software to add support for this scheme in addition to any existing schemes. Given the already confused nature of wallet derivation paths in Ethereum, we anticipate this will cause relatively little additional disruption, and has the potential to improve matters significantly in the long run.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="implementation">Implementation</h2> <p>None yet.</p> <h2 id="references">References</h2> <p><a rel="external" href="https://github.com/ethereum/EIPs/issues/84">This discussion on derivation paths</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-04-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Johnsonhttps://github.com/arachnid Micah Zoltuhttps://github.com/micahzoltu https://wg-eips.ritovision.com/601/ <h2 id="abstract">Abstract</h2> <p>This EIP defines a logical hierarchy for deterministic wallets based on <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki">BIP32</a>, the purpose scheme defined in <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki">BIP43</a> and eip-draft-ethereum-purpose.</p> <p>This EIP is a particular application of eip-draft-ethereum-purpose.</p> <h2 id="motivation">Motivation</h2> <p>At present, different Ethereum clients and wallets use different derivation paths; a summary of them can be found <a rel="external" href="https://github.com/ethereum/EIPs/issues/84#issuecomment-292324521">here</a>. Some of these paths violate BIP44, the standard defining derivation paths starting with <code>m/44'/</code>. This creates confusion and incompatibility between wallet implementations, in some cases making funds from one wallet inaccessible on another, and in others requiring prompting users manually for a derivation path, which hinders usability.</p> <p>Further, BIP44 was designed with UTXO-based blockchains in mind, and is a poor fit for Ethereum, which uses an accounts abstraction instead.</p> <p>As an alternative, we propose a deterministic wallet hierarchy better tailored to Ethereum's unique requirements.</p> <h2 id="specification">Specification</h2> <p>We define the following 4 levels in BIP32 path:</p> <pre> m / purpose' / subpurpose' / EIP' / wallet' </pre> <p>Apostrophe in the path indicates that BIP32 hardened derivation is used.</p> <p>Each level has a special meaning, described in the chapters below.</p> <h3 id="purpose">Purpose</h3> <p>Purpose is a constant set to 43, indicating the key derivation is for a non-bitcoin cryptocurrency.</p> <p>Hardened derivation is used at this level.</p> <h3 id="subpurpose">Subpurpose</h3> <p>Subpurpose is set to 60, the SLIP-44 code for Ethereum.</p> <p>Hardened derivation is used at this level.</p> <h3 id="eip">EIP</h3> <p>EIP is set to the EIP number specifying the remainder of the BIP32 derivation path. For paths following this EIP specification, the number assigned to this EIP is used.</p> <p>Hardened derivation is used at this level.</p> <h3 id="wallet">Wallet</h3> <p>This component of the path splits the wallet into different user identities, allowing a single wallet to have multiple public identities.</p> <p>Accounts are numbered from index 0 in sequentially increasing manner. This number is used as child index in BIP32 derivation.</p> <p>Hardened derivation is used at this level.</p> <p>Software should prevent a creation of an account if a previous account does not have a transaction history (meaning its address has not been used before).</p> <p>Software needs to discover all used accounts after importing the seed from an external source.</p> <h2 id="rationale">Rationale</h2> <p>The existing convention is to use the 'Ethereum' coin type, leading to paths starting with <code>m/44'/60'/*</code>. Because this still assumes a UTXO-based coin, we contend that this is a poor fit, resulting in standardisation, usability, and security compromises. As a result, we are making the above proposal to define an entirely new hierarchy for Ethereum-based chains.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The introduction of another derivation path requires existing software to add support for this scheme in addition to any existing schemes. Given the already confused nature of wallet derivation paths in Ethereum, we anticipate this will cause relatively little additional disruption, and has the potential to improve matters significantly in the long run.</p> <p>For applications that utilise mnemonics, the authors expect to submit another EIP draft that describes a method for avoiding backwards compatibility concerns when transitioning to this new derivation path.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="implementation">Implementation</h2> <p>None yet.</p> <h2 id="references">References</h2> <p><a rel="external" href="https://github.com/ethereum/EIPs/issues/84">This discussion on derivation paths</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-03-24T00:00:00+00:00 2026-02-11T14:49:27+00:00 Micah Zoltuhttps://github.com/MicahZoltu https://wg-eips.ritovision.com/234/ <h2 id="simple-summary">Simple Summary</h2> <p>Add an option to JSON-RPC filter options (used by <code>eth_newFilter</code> and <code>eth_getLogs</code>) that allows specifying the block hash that should be included in the results. This option would be an alternative to <code>fromBlock</code>/<code>toBlock</code> options.</p> <h2 id="abstract">Abstract</h2> <p>This addition would allow clients to fetch logs for specific blocks, whether those blocks were in the current main chain or not. This resolves some issues that make it difficult/expensive to author robust clients due to the nature of chain reorgs, unreliable network connections and the result set not containing enough details in the empty case.</p> <h2 id="specification">Specification</h2> <p>The filter options used by <code>eth_newFilter</code> would have an additional optional parameter named <code>blockHash</code> whose value is a single block hash. The Ethereum node responding to the request would either send back an error if the block hash was not found or it would return the results matching the filter (per normal operation) constrained to the block provided. Internally, this would function (presumably) similar to the <code>fromBlock</code> and <code>toBlock</code> filter options.</p> <h2 id="rationale">Rationale</h2> <p>A client (dApp) who needs reliable notification of both log additions (on new blocks) and log removals (on chain reorgs) cannot achieve this while relying solely on subscriptions and filters. This is because a combination of a network or remote node failure during a reorg can result in the client getting out of sync with reality. An example of where this can happen with Websockets is when the client opens a web socket connection, sets up a log filter subscription, gets notified of some new logs, then loses the web socket connection, then (while disconnected) a re-org occurs, then the client connects back and establishes a new log filter. In this scenario they will not receive notification of the log removals from the node because they were disconnected when the removals were broadcast and the loss of their connection resulted in the node forgetting about their existence. A similar scenario can be concocted for HTTP clients where between polls for updates, the node goes down and comes back (resulting in loss of filter state) and a re-org also occurs between the same two polls.</p> <p>In order to deal with this while still providing a robust mechanism for internal block/log additional/removal, the client can maintain a blockchain internally (last <code>n</code> blocks) and only subscribe/poll for new blocks. When a new block is received, the client can reconcile their internal model with the new block, potentially back-filling parents or rolling back/removing blocks from their internal model to get in sync with the node. This can account for any type of disconnect/reorg/outage scenario and also allows the client (as an added benefit) to talk to a cluster of Ethereum nodes (e.g., via round-robin) rather than being tightly coupled to a single node.</p> <p>Once the user has a reliable stream of blocks, they can then look at the bloom filter for the new block and if the block <em>may</em> have logs of interest they can fetch the filtered logs for that block from the node. The problem that arises is that a re-org may occur between when the client receives the block and when the client fetches the logs for that block. Given the current set of filter options, the client can only ask for logs by block number. In this scenario, the logs they get back will be for a block that <em>isn't</em> the block they want the logs for and is instead for a block that was re-orged in (and may not be fully reconciled with the internal client state). This can be partially worked around by looking at the resulting logs themselves and identifying whether or not they are for the block hash requested. However, if the result set is an empty array (no logs fetched) then the client is in a situation where they don't know what block the results are for. The results could have been legitimately empty (bloom filter can yield false positives) for the block in question, or they could be receiving empty logs for a block that they don't know about. At this point, there is no decision the client can make that allows them a guarantee of recovery. They can assume the empty logs were for the correct block, but if they weren't then they will never try to fetch again. This creates a problem if the block was only transiently re-orged out because it may come back before the next block poll so the client will never witness the reorg. They can assume the empty logs were for the wrong block, and refetch them, but they may continue to get empty results putting them right back into the same situation.</p> <p>By adding the ability to fetch logs by hash, the client can be guaranteed that if they get a result set, it is for the block in question. If they get an error, then they can take appropriate action (e.g., rollback that block client-side and re-fetch latest).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The only potential issue here is the <code>fromBlock</code> and <code>toBlock</code> fields. It wouldn't make sense to include both the hash and the number so it seems like <code>fromBlock</code>/<code>toBlock</code> should be mutually exclusive with <code>blockHash</code>.</p> <h2 id="test-cases">Test Cases</h2> <p><code>{ "jsonrpc": "2.0", "id": 1, "method": "eth_getLogs", params: [{"blockHash": "0xbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0c"}] }</code> should return all of the logs for the block with hash <code>0xbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0c</code>. If a <code>topics</code> field is added to the filter options then a filtered set of logs for that block should be returned. If no block exists with that hash then an error should be returned with a <code>code</code> of <code>-32000</code>, a <code>message</code> of <code>"Block not found."</code> and a <code>data</code> of <code>"0xbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0cbl0c"</code>.</p> <h2 id="implementation">Implementation</h2> <ul> <li><input disabled="" type="checkbox" checked=""/> <a rel="external" href="https://github.com/ethereum/go-ethereum/pull/16734">Geth</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> 2017-03-06T00:00:00+00:00 2026-02-11T14:49:27+00:00 Péter Szilágyipeterke@gmail.com https://wg-eips.ritovision.com/225/ <h2 id="abstract">Abstract</h2> <p>Clique is a proof-of-authority consensus protocol. It shadows the design of Ethereum mainnet, so it can be added to any client with minimal effort.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum's first official testnet was Morden. It ran from July 2015 to about November 2016, when due to the accumulated junk and some testnet consensus issues between Geth and Parity, it was finally laid to rest in favor of a testnet reboot.</p> <p>Ropsten was thus born, clearing out all the junk and starting with a clean slate. This ran well until the end of February 2017, when malicious actors decided to abuse the low PoW and gradually inflate the block gas limits to 9 billion (from the normal 4.7 million), at which point sending in gigantic transactions crippling the entire network. Even before that, attackers attempted multiple extremely long reorgs, causing network splits between different clients, and even different versions.</p> <p>The root cause of these attacks is that a PoW network is only as secure as the computing capacity placed behind it. Restarting a new testnet from zero wouldn't solve anything, since the attacker can mount the same attack over and over again. The Parity team decided to go with an emergency solution of rolling back a significant number of blocks, and enacting a soft-fork rule that disallows gas limits above a certain threshold.</p> <p>While this solution may work in the short term:</p> <ul> <li>It's not elegant: Ethereum supposed to have dynamic block limits</li> <li>It's not portable: other clients need to implement new fork logic themselves</li> <li>It's not compatible with sync modes: fast and light clients are both out of luck</li> <li>It's just prolonging the attacks: junk can still be steadily pushed in ad infinitum</li> </ul> <p>Parity's solution although not perfect, is nonetheless workable. I'd like to propose a longer term alternative solution, which is more involved, yet should be simple enough to allow rolling out in a reasonable amount of time.</p> <h3 id="standardized-proof-of-authority">Standardized proof-of-authority</h3> <p>As reasoned above, proof-of-work cannot work securely in a network with no value. Ethereum has its long term goal of proof-of-stake based on Casper, but that is heavy research so we cannot rely on that any time soon to fix today's problems. One solution however is easy enough to implement, yet effective enough to fix the testnet properly, namely a proof-of-authority scheme.</p> <p>The main design goals of the PoA protocol described here is that it should be very simple to implement and embed into any existing Ethereum client, while at the same time allow using existing sync technologies (fast, light, warp) without needing client developers to add custom logic to critical software.</p> <h2 id="design-constraints">Design constraints</h2> <p>There are two approaches to syncing a blockchain in general:</p> <ul> <li>The classical approach is to take the genesis block and crunch through all the transactions one by one. This is tried and proven, but in Ethereum complexity networks quickly turns out to be very costly computationally.</li> <li>The other is to only download the chain of block headers and verify their validity, after which point an arbitrary recent state may be downloaded from the network and checked against recent headers.</li> </ul> <p>A PoA scheme is based on the idea that blocks may only be minted by trusted signers. As such, every block (or header) that a client sees can be matched against the list of trusted signers. The challenge here is how to maintain a list of authorized signers that can change in time? The obvious answer (store it in an Ethereum contract) is also the wrong answer: fast, light and warp sync don't have access to the state during syncing.</p> <p><strong>The protocol of maintaining the list of authorized signers must be fully contained in the block headers.</strong></p> <p>The next obvious idea would be to change the structure of the block headers so it drops the notions of PoW, and introduces new fields to cater for voting mechanisms. This is also the wrong answer: changing such a core data structure in multiple implementations would be a nightmare development, maintenance and security wise.</p> <p><strong>The protocol of maintaining the list of authorized signers must fit fully into the current data models.</strong></p> <p>So, according to the above, we can't use the EVM for voting, rather have to resort to headers. And we can't change header fields, rather have to resort to the currently available ones. Not much wiggle room.</p> <h3 id="repurposing-header-fields-for-signing-and-voting">Repurposing header fields for signing and voting</h3> <p>The most obvious field that currently is used solely as <em>fun metadata</em> is the 32 byte <strong>extra-data</strong> section in block headers. Miners usually place their client and version in there, but some fill it with alternative "messages". The protocol would extend this field <del>to</del> with 65 bytes with the purpose of a secp256k1 miner signature. This would allow anyone obtaining a block to verify it against a list of authorized signers. It also makes the <strong>miner</strong> section in block headers obsolete (since the address can be derived from the signature).</p> <p><em>Note, changing the length of a header field is a non invasive operation as all code (such as RLP encoding, hashing) is agnostic to that, so clients wouldn't need custom logic.</em></p> <p>The above is enough to validate a chain, but how can we update a dynamic list of signers. The answer is that we can repurpose the newly obsoleted <strong>miner</strong> field and the PoA obsoleted <strong>nonce</strong> field to create a voting protocol:</p> <ul> <li>During regular blocks, both of these fields would be set to zero.</li> <li>If a signer wishes to enact a change to the list of authorized signers, it will: <ul> <li>Set the <strong>miner</strong> to the signer it wishes to vote about</li> <li>Set the <strong>nonce</strong> to <code>0</code> or <code>0xff...f</code> to vote in favor of adding or kicking out</li> </ul> </li> </ul> <p>Any clients syncing the chain can "tally" up the votes during block processing, and maintain a dynamically changing list of authorized signers by popular vote.</p> <p>To avoid having an infinite window to tally up votes in, and also to allow periodically flushing stale proposals, we can reuse the concept of an epoch from ethash, where every epoch transition flushes all pending votes. Furthermore, these epoch transitions can also act as stateless checkpoints containing the list of current authorized signers within the header extra-data. This permits clients to sync up based only on a checkpoint hash without having to replay all the voting that was done on the chain up to that point. It also allows the genesis header to fully define the chain, containing the list of initial signers.</p> <h3 id="attack-vector-malicious-signer">Attack vector: Malicious signer</h3> <p>It may happen that a malicious user gets added to the list of signers, or that a signer key/machine is compromised. In such a scenario the protocol needs to be able to defend itself against reorganizations and spamming. The proposed solution is that given a list of N authorized signers, any signer may only mint 1 block out of every K. This ensures that damage is limited, and the remainder of the miners can vote out the malicious user.</p> <h3 id="attack-vector-censoring-signer">Attack vector: Censoring signer</h3> <p>Another interesting attack vector is if a signer (or group of signers) attempts to censor out blocks that vote on removing them from the authorization list. To work around this, we restrict the allowed minting frequency of signers to 1 out of N/2. This ensures that malicious signers need to control at least 51% of signing accounts, at which case it's game over anyway.</p> <h3 id="attack-vector-spamming-signer">Attack vector: Spamming signer</h3> <p>A final small attack vector is that of malicious signers injecting new vote proposals inside every block they mint. Since nodes need to tally up all votes to create the actual list of authorized signers, they need to track all votes through time. Without placing a limit on the vote window, this could grow slowly, yet unbounded. The solution is to place a <del>moving</del> window of W blocks after which votes are considered stale. <del>A sane window might be 1-2 epochs.</del> We'll call this an epoch.</p> <h3 id="attack-vector-concurrent-blocks">Attack vector: Concurrent blocks</h3> <p>If the number of authorized signers are N, and we allow each signer to mint 1 block out of K, then at any point in time N-K+1 miners are allowed to mint. To avoid these racing for blocks, every signer would add a small random "offset" to the time it releases a new block. This ensures that small forks are rare, but occasionally still happen (as on the main net). If a signer is caught abusing it's authority and causing chaos, it can be voted out.</p> <h2 id="specification">Specification</h2> <p>We define the following constants:</p> <ul> <li><strong><code>EPOCH_LENGTH</code></strong>: Number of blocks after which to checkpoint and reset the pending votes. <ul> <li>Suggested <code>30000</code> for the testnet to remain analogous to the mainnet <code>ethash</code> epoch.</li> </ul> </li> <li><strong><code>BLOCK_PERIOD</code></strong>: Minimum difference between two consecutive block's timestamps. <ul> <li>Suggested <code>15s</code> for the testnet to remain analogous to the mainnet <code>ethash</code> target.</li> </ul> </li> <li><strong><code>EXTRA_VANITY</code></strong>: Fixed number of extra-data prefix bytes reserved for signer <em>vanity</em>. <ul> <li>Suggested <code>32 bytes</code> to retain the current extra-data allowance and/or use.</li> </ul> </li> <li><strong><code>EXTRA_SEAL</code></strong>: Fixed number of extra-data suffix bytes reserved for signer seal. <ul> <li><code>65 bytes</code> fixed as signatures are based on the standard <code>secp256k1</code> curve.</li> <li>Filled with zeros on genesis block.</li> </ul> </li> <li><strong><code>NONCE_AUTH</code></strong>: Magic nonce number <code>0xffffffffffffffff</code> to vote on adding a new signer.</li> <li><strong><code>NONCE_DROP</code></strong>: Magic nonce number <code>0x0000000000000000</code> to vote on removing a signer.</li> <li><strong><code>UNCLE_HASH</code></strong>: Always <code>Keccak256(RLP([]))</code> as uncles are meaningless outside of PoW.</li> <li><strong><code>DIFF_NOTURN</code></strong>: Block score (difficulty) for blocks containing out-of-turn signatures. <ul> <li>Suggested <code>1</code> since it just needs to be an arbitrary baseline constant.</li> </ul> </li> <li><strong><code>DIFF_INTURN</code></strong>: Block score (difficulty) for blocks containing in-turn signatures. <ul> <li>Suggested <code>2</code> to show a slight preference over out-of-turn signatures.</li> </ul> </li> </ul> <p>We also define the following per-block constants:</p> <ul> <li><strong><code>BLOCK_NUMBER</code></strong>: Block height in the chain, where the height of the genesis is block <code>0</code>.</li> <li><strong><code>SIGNER_COUNT</code></strong>: Number of authorized signers valid at a particular instance in the chain.</li> <li><strong><code>SIGNER_INDEX</code></strong>: Zero-based index of the block signer in the sorted list of current authorized signers.</li> <li><strong><code>SIGNER_LIMIT</code></strong>: Number of consecutive blocks out of which a signer may only sign one. <ul> <li>Must be <code>floor(SIGNER_COUNT / 2) + 1</code> to enforce majority consensus on a chain.</li> </ul> </li> </ul> <p>We repurpose the <code>ethash</code> header fields as follows:</p> <ul> <li><strong><code>beneficiary</code></strong> / <strong><code>miner</code></strong>: Address to propose modifying the list of authorized signers with. <ul> <li>Should be filled with zeroes normally, modified only while voting.</li> <li>Arbitrary values are permitted nonetheless (even meaningless ones such as voting out non signers) to avoid extra complexity in implementations around voting mechanics.</li> <li><strong>Must</strong> be filled with zeroes on checkpoint (i.e. epoch transition) blocks.</li> <li>Transaction execution <strong>must</strong> use the actual block signer (see <code>extraData</code>) for the <code>COINBASE</code> opcode and transaction fees <strong>must</strong> be attributed to the signer account.</li> </ul> </li> <li><strong><code>nonce</code></strong>: Signer proposal regarding the account defined by the <code>beneficiary</code> field. <ul> <li>Should be <strong><code>NONCE_DROP</code></strong> to propose deauthorizing <code>beneficiary</code> as an existing signer.</li> <li>Should be <strong><code>NONCE_AUTH</code></strong> to propose authorizing <code>beneficiary</code> as a new signer.</li> <li><strong>Must</strong> be filled with zeroes on checkpoint (i.e. epoch transition) blocks.</li> <li><strong>Must</strong> not take up any other value apart from the two above (for now).</li> </ul> </li> <li><strong><code>extraData</code></strong>: Combined field for signer vanity, checkpointing and signer signatures. <ul> <li>First <strong><code>EXTRA_VANITY</code></strong> bytes (fixed) may contain arbitrary signer vanity data.</li> <li>Last <strong><code>EXTRA_SEAL</code></strong> bytes (fixed) is the signer's signature sealing the header.</li> <li>Checkpoint blocks <strong>must</strong> contain a list of signers (<code>N*20 bytes</code>) in between, <strong>omitted</strong> otherwise.</li> <li>The list of signers in checkpoint block extra-data sections <strong>must</strong> be sorted in ascending byte order.</li> </ul> </li> <li><strong><code>mixHash</code></strong>: Reserved for fork protection logic, similar to the extra-data during the DAO. <ul> <li><strong>Must</strong> be filled with zeroes during normal operation.</li> </ul> </li> <li><strong><code>ommersHash</code></strong>: <strong>Must</strong> be <strong><code>UNCLE_HASH</code></strong> as uncles are meaningless outside of PoW.</li> <li><strong><code>timestamp</code></strong>: <strong>Must</strong> be at least the parent timestamp + <strong><code>BLOCK_PERIOD</code></strong>.</li> <li><strong><code>difficulty</code></strong>: Contains the standalone score of the block to derive the quality of a chain. <ul> <li><strong>Must</strong> be <strong><code>DIFF_NOTURN</code></strong> if <code>BLOCK_NUMBER % SIGNER_COUNT != SIGNER_INDEX</code></li> <li><strong>Must</strong> be <strong><code>DIFF_INTURN</code></strong> if <code>BLOCK_NUMBER % SIGNER_COUNT == SIGNER_INDEX</code></li> </ul> </li> </ul> <h3 id="authorizing-a-block">Authorizing a block</h3> <p>To authorize a block for the network, the signer needs to sign the block's sighash containing <strong>everything except the signature itself</strong>. This means that this hash contains every field of the header (<code>nonce</code> and <code>mixDigest</code> included), and also the <code>extraData</code> with the exception of the 65 byte signature suffix. The fields are hashed in the order of their definition in the yellow paper. Note that this sighash differs from the final block hash which also includes the signature.</p> <p>The sighash is signed using the standard <code>secp256k1</code> curve, and the resulting 65 byte signature (<code>R</code>, <code>S</code>, <code>V</code>, where <code>V</code> is <code>0</code> or <code>1</code>) is embedded into the <code>extraData</code> as the trailing 65 byte suffix.</p> <p>To ensure malicious signers (loss of signing key) cannot wreck havoc in the network, each signer is allowed to sign <strong>maximum one</strong> out of <strong><code>SIGNER_LIMIT</code></strong> consecutive blocks. The order is not fixed, but in-turn signing weighs more (<strong><code>DIFF_INTURN</code></strong>) than out of turn one (<strong><code>DIFF_NOTURN</code></strong>).</p> <h4 id="authorization-strategies">Authorization strategies</h4> <p>As long as signers conform to the above specs, they can authorize and distribute blocks as they see fit. The following suggested strategy will however reduce network traffic and small forks, so it's a suggested feature:</p> <ul> <li>If a signer is allowed to sign a block (is on the authorized list and didn't sign recently). <ul> <li>Calculate the optimal signing time of the next block (parent + <strong><code>BLOCK_PERIOD</code></strong>).</li> <li>If the signer is in-turn, wait for the exact time to arrive, sign and broadcast immediately.</li> <li>If the signer is out-of-turn, delay signing by <code>rand(SIGNER_COUNT * 500ms)</code>.</li> </ul> </li> </ul> <p>This small strategy will ensure that the in-turn signer (who's block weighs more) has a slight advantage to sign and propagate versus the out-of-turn signers. Also the scheme allows a bit of scale with the increase of the number of signers.</p> <h3 id="voting-on-signers">Voting on signers</h3> <p>Every epoch transition (genesis block included) acts as a stateless checkpoint, from which capable clients should be able to sync without requiring any previous state. This means epoch headers <strong>must not</strong> contain votes, all non settled votes are discarded, and tallying starts from scratch.</p> <p>For all non-epoch transition blocks:</p> <ul> <li>Signers may cast one vote per own block to propose a change to the authorization list.</li> <li>Only the latest proposal per target beneficiary is kept from a single signer.</li> <li>Votes are tallied live as the chain progresses (concurrent proposals allowed).</li> <li>Proposals reaching majority consensus <strong><code>SIGNER_LIMIT</code></strong> come into effect immediately.</li> <li>Invalid proposals are <strong>not</strong> to be penalized for client implementation simplicity.</li> </ul> <p><strong>A proposal coming into effect entails discarding all pending votes for that proposal (both for and against) and starting with a clean slate.</strong></p> <h4 id="cascading-votes">Cascading votes</h4> <p>A complex corner case may arise during signer deauthorization. When a previously authorized signer is dropped, the number of signers required to approve a proposal might decrease by one. This might cause one or more pending proposals to reach majority consensus, the execution of which might further cascade into new proposals passing.</p> <p>Handling this scenario is non obvious when multiple conflicting proposals pass simultaneously (e.g. add a new signer vs. drop an existing one), where the evaluation order might drastically change the outcome of the final authorization list. Since signers may invert their own votes in every block they mint, it's not so obvious which proposal would be "first".</p> <p>To avoid the pitfalls cascading executions would entail, the Clique proposal explicitly forbids cascading effects. In other words: <strong>Only the <code>beneficiary</code> of the current header/vote may be added to/dropped from the authorization list. If that causes other proposals to reach consensus, those will be executed when their respective beneficiaries are "touched" again (given that majority consensus still holds at that point).</strong></p> <h4 id="voting-strategies">Voting strategies</h4> <p>Since the blockchain can have small reorgs, a naive voting mechanism of "cast-and-forget" may not be optimal, since a block containing a singleton vote may not end up on the final chain.</p> <p>A simplistic but working strategy is to allow users to configure "proposals" on the signers (e.g. "add 0x...", "drop 0x..."). The signing code can then pick a random proposal for every block it signs and inject it. This ensures that multiple concurrent proposals as well as reorgs get eventually noted on the chain.</p> <p>This list may be expired after a certain number of blocks / epochs, but it's important to realize that "seeing" a proposal pass doesn't mean it won't get reorged, so it should not be immediately dropped when the proposal passes.</p> <h2 id="test-cases">Test Cases</h2> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> block represents a single block signed by a particular account, where</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> the account may or may not have cast a Clique vote.</span></span> <span class="giallo-l"><span class="z-keyword">type</span><span class="z-entity z-name"> block</span><span class="z-keyword"> struct</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> signer</span><span class="z-storage z-type"> string</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Account that signed this particular block</span></span> <span class="giallo-l"><span class="z-variable z-other"> voted</span><span class="z-storage z-type"> string</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Optional value if the signer voted on adding/removing someone</span></span> <span class="giallo-l"><span class="z-variable z-other"> auth</span><span class="z-storage z-type"> bool</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Whether the vote was to authorize (or deauthorize)</span></span> <span class="giallo-l"><span class="z-variable z-other"> checkpoint</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> List of authorized signers if this is an epoch block</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"> Define the various voting scenarios to test</span></span> <span class="giallo-l"><span class="z-variable z-other">tests</span><span class="z-keyword"> :=</span><span> [</span><span>]</span><span class="z-keyword">struct</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> epoch</span><span class="z-storage z-type"> uint64</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Number of blocks in an epoch (unset = 30000)</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Initial list of authorized signers in the genesis</span></span> <span class="giallo-l"><span class="z-variable z-other"> blocks</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Chain of signed blocks, potentially influencing auths</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Final list of authorized signers after all blocks</span></span> <span class="giallo-l"><span class="z-variable z-other"> failure</span><span class="z-storage z-type"> error</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Failure if some block is invalid according to the rules</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-comment"> //</span><span class="z-comment"> Single signer, no votes cast</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</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-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Single signer, voting to add two others (only accept first, second needs 2 votes)</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</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>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Two signers, voting to add three others (only accept first two, third needs 3 votes already)</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</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">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</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-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</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-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</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">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Single signer, dropping itself (weird, but one less cornercase by explicitly allowing this)</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Two signers, actually needing mutual consent to drop either of them (not fulfilled)</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</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>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Two signers, actually needing mutual consent to drop either of them (fulfilled)</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</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>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</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>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Three signers, two of them deciding to drop the third</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Four signers, consensus of two not being enough to drop anyone</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</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">D</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</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">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Four signers, consensus of three already being enough to drop someone</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</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">D</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Authorizations are counted once per signer per target</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Authorizing multiple accounts concurrently is permitted</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</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">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</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">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</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">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Deauthorizations are counted once per signer per target</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</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>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</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>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</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>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Deauthorizing multiple accounts concurrently is permitted</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</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">D</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</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">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</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">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</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">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</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">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Votes from deauthorized signers are discarded immediately (deauth votes)</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</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>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</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>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Votes from deauthorized signers are discarded immediately (auth votes)</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Cascading changes are not allowed, only the account being voted on may change</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</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">D</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</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">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</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">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</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">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Changes reaching consensus out of bounds (via a deauth) execute on touch</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</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">D</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</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">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</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">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</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">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</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">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Changes reaching consensus out of bounds (via a deauth) may go out of consensus on first touch</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</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">D</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</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">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</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">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</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">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</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">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Ensure that pending votes don&#39;t survive authorization status changes. This</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> corner case can only appear if a signer is quickly added, removed and then</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> readded (or the inverse), while one of the original voters dropped. If a</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> past vote is left cached in the system somewhere, this will interfere with</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> the final signer outcome.</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</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">D</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">E</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">F</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Authorize F, 3 votes needed</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">F</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">F</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">F</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Deauthorize F, 4 votes needed (leave A&#39;s previous vote &quot;unchanged&quot;)</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</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-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">F</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">F</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">F</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">F</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Almost authorize F, 2/3 votes needed</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</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-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">F</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Deauthorize A, 3 votes needed</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">D</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> false</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">F</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Finish authorizing F, 3/3 votes needed</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</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>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</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">D</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">E</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">F</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Epoch transitions reset all votes to allow chain checkpointing</span></span> <span class="giallo-l"><span class="z-variable z-other"> epoch</span><span>:</span><span class="z-constant"> 3</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> checkpoint</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</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-variable z-other">signer</span><span>:</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>,</span><span class="z-variable z-other"> voted</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">C</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> auth</span><span>:</span><span class="z-constant"> true</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> results</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> An unauthorized signer should not be able to sign blocks</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</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>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> failure</span><span>:</span><span class="z-variable z-other"> errUnauthorizedSigner</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> An authorized signer that signed recently should not be able to sign again</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">B</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</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">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> failure</span><span>:</span><span class="z-variable z-other"> errRecentlySigned</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Recent signatures should not reset on checkpoint blocks imported in a batch</span></span> <span class="giallo-l"><span class="z-variable z-other"> epoch</span><span>:</span><span class="z-constant"> 3</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> signers</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</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"> blocks</span><span>:</span><span> [</span><span>]</span><span class="z-entity z-name">block</span><span>{</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</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">signer</span><span>:</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>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> checkpoint</span><span>:</span><span> [</span><span>]</span><span class="z-storage z-type">string</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">A</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">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">C</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-variable z-other">signer</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> failure</span><span>:</span><span class="z-variable z-other"> errRecentlySigned</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="implementation">Implementation</h2> <p>A reference implementation is part of <a rel="external" href="https://github.com/ethereum/go-ethereum/tree/master/consensus/clique">go-ethereum</a> and has been functioning as the consensus engine behind the <a rel="external" href="https://www.rinkeby.io">Rinkeby</a> testnet since April, 2017.</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-13T00: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/145/

To Provide native bitwise shifting with cost on par with other arithmetic operations.

<h2 id="abstract">Abstract</h2> <p>Native bitwise shifting instructions are introduced, which are more efficient processing wise on the host and are cheaper to use by a contract.</p> <h2 id="motivation">Motivation</h2> <p>EVM is lacking bitwise shifting operators, but supports other logical and arithmetic operators. Shift operations can be implemented via arithmetic operators, but that has a higher cost and requires more processing time from the host. Implementing <code>SHL</code> and <code>SHR</code> using arithmetic cost each 35 gas, while the proposed instructions take 3 gas.</p> <h2 id="specification">Specification</h2> <p>The following instructions are introduced:</p> <h3 id="0x1b-shl-shift-left"><code>0x1b</code>: <code>SHL</code> (shift left)</h3> <p>The <code>SHL</code> instruction (shift left) pops 2 values from the stack, first <code>arg1</code> and then <code>arg2</code>, and pushes on the stack <code>arg2</code> shifted to the left by <code>arg1</code> number of bits. The result is equal to</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(arg2 * 2^arg1) mod 2^256</span></span></code></pre> <p>Notes:</p> <ul> <li>The value (<code>arg2</code>) is interpreted as an unsigned number.</li> <li>The shift amount (<code>arg1</code>) is interpreted as an unsigned number.</li> <li>If the shift amount (<code>arg1</code>) is greater or equal 256 the result is 0.</li> <li>This is equivalent to <code>PUSH1 2 EXP MUL</code>.</li> </ul> <h3 id="0x1c-shr-logical-shift-right"><code>0x1c</code>: <code>SHR</code> (logical shift right)</h3> <p>The <code>SHR</code> instruction (logical shift right) pops 2 values from the stack, first <code>arg1</code> and then <code>arg2</code>, and pushes on the stack <code>arg2</code> shifted to the right by <code>arg1</code> number of bits with zero fill. The result is equal to</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>floor(arg2 / 2^arg1)</span></span></code></pre> <p>Notes:</p> <ul> <li>The value (<code>arg2</code>) is interpreted as an unsigned number.</li> <li>The shift amount (<code>arg1</code>) is interpreted as an unsigned number.</li> <li>If the shift amount (<code>arg1</code>) is greater or equal 256 the result is 0.</li> <li>This is equivalent to <code>PUSH1 2 EXP DIV</code>.</li> </ul> <h3 id="0x1d-sar-arithmetic-shift-right"><code>0x1d</code>: <code>SAR</code> (arithmetic shift right)</h3> <p>The <code>SAR</code> instruction (arithmetic shift right) pops 2 values from the stack, first <code>arg1</code> and then <code>arg2</code>, and pushes on the stack <code>arg2</code> shifted to the right by <code>arg1</code> number of bits with sign extension. The result is equal to</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>floor(arg2 / 2^arg1)</span></span></code></pre> <p>Notes:</p> <ul> <li>The value (<code>arg2</code>) is interpreted as a signed number.</li> <li>The shift amount (<code>arg1</code>) is interpreted as an unsigned number.</li> <li>If the shift amount (<code>arg1</code>) is greater or equal 256 the result is 0 if <code>arg2</code> is non-negative or -1 if <code>arg2</code> is negative.</li> <li>This is <strong>not</strong> equivalent to <code>PUSH1 2 EXP SDIV</code>, since it rounds differently. See <code>SDIV(-1, 2) == 0</code>, while <code>SAR(-1, 1) == -1</code>.</li> </ul> <p>The cost of the shift instructions is set at <code>verylow</code> tier (3 gas).</p> <h2 id="rationale">Rationale</h2> <p>Instruction operands were chosen to fit the more natural use case of shifting a value already on the stack. This means the operand order is swapped compared to most arithmetic instructions.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The newly introduced instructions have no effect on bytecode created in the past.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="shl-shift-left"><code>SHL</code> (shift left)</h3> <ol> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x0000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>PUSH 0x00</span></span> <span class="giallo-l"><span>SHL</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000001</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x0000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>PUSH 0x01</span></span> <span class="giallo-l"><span>SHL</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000002</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x0000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>PUSH 0xff</span></span> <span class="giallo-l"><span>SHL</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x8000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x0000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>PUSH 0x0100</span></span> <span class="giallo-l"><span>SHL</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x0000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>PUSH 0x0101</span></span> <span class="giallo-l"><span>SHL</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0x00</span></span> <span class="giallo-l"><span>SHL</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0x01</span></span> <span class="giallo-l"><span>SHL</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0xff</span></span> <span class="giallo-l"><span>SHL</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x8000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0x0100</span></span> <span class="giallo-l"><span>SHL</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x0000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>PUSH 0x01</span></span> <span class="giallo-l"><span>SHL</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0x01</span></span> <span class="giallo-l"><span>SHL</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe</span></span></code></pre></li> </ol> <h3 id="shr-logical-shift-right"><code>SHR</code> (logical shift right)</h3> <ol> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x0000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>PUSH 0x00</span></span> <span class="giallo-l"><span>SHR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000001</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x0000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>PUSH 0x01</span></span> <span class="giallo-l"><span>SHR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x8000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>PUSH 0x01</span></span> <span class="giallo-l"><span>SHR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x4000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x8000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>PUSH 0xff</span></span> <span class="giallo-l"><span>SHR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000001</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x8000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>PUSH 0x0100</span></span> <span class="giallo-l"><span>SHR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x8000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>PUSH 0x0101</span></span> <span class="giallo-l"><span>SHR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0x00</span></span> <span class="giallo-l"><span>SHR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0x01</span></span> <span class="giallo-l"><span>SHR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0xff</span></span> <span class="giallo-l"><span>SHR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000001</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0x0100</span></span> <span class="giallo-l"><span>SHR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x0000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>PUSH 0x01</span></span> <span class="giallo-l"><span>SHR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> </ol> <h3 id="sar-arithmetic-shift-right"><code>SAR</code> (arithmetic shift right)</h3> <ol> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x0000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>PUSH 0x00</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000001</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x0000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>PUSH 0x01</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x8000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>PUSH 0x01</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0xc000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x8000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>PUSH 0xff</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x8000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>PUSH 0x0100</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x8000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>PUSH 0x0101</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0x00</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0x01</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0xff</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0x0100</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x0000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>PUSH 0x01</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x4000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>PUSH 0xfe</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000001</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0xf8</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x000000000000000000000000000000000000000000000000000000000000007f</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0xfe</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000001</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0xff</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> <li><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0x0100</span></span> <span class="giallo-l"><span>SAR</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x0000000000000000000000000000000000000000000000000000000000000000</span></span></code></pre></li> </ol> <h3 id="implementation">Implementation</h3> <p>Client support:</p> <ul> <li>cpp-ethereum: https://github.com/ethereum/cpp-ethereum/pull/4054</li> </ul> <p>Compiler support:</p> <ul> <li>Solidity/LLL: https://github.com/ethereum/solidity/pull/2541</li> </ul> <h3 id="tests">Tests</h3> <p>Sources:</p> <ul> <li>https://github.com/ethereum/tests/tree/develop/src/GeneralStateTestsFiller/stShift</li> </ul> <p>Filled Tests:</p> <ul> <li>https://github.com/ethereum/tests/tree/develop/GeneralStateTests/stShift</li> <li>https://github.com/ethereum/tests/tree/develop/BlockchainTests/GeneralStateTests/stShift</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> 2017-02-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Christian Reitwiessnerchris@ethereum.org https://wg-eips.ritovision.com/211/ <h2 id="simple-summary">Simple Summary</h2> <p>A mechanism to allow returning arbitrary-length data inside the EVM has been requested for quite a while now. Existing proposals always had very intricate problems associated with charging gas. This proposal solves the same problem while at the same time, it has a very simple gas charging mechanism and requires minimal changes to the call opcodes. Its workings are very similar to the way calldata is handled already; after a call, return data is kept inside a virtual buffer from which the caller can copy it (or parts thereof) into memory. At the next call, the buffer is overwritten. This mechanism is 100% backwards compatible.</p> <h2 id="abstract">Abstract</h2> <p>Please see summary.</p> <h2 id="motivation">Motivation</h2> <p>In some situations, it is vital for a function to be able to return data whose length cannot be anticipated before the call. In principle, this can be solved without alterations to the EVM, for example by splitting the call into two calls where the first is used to compute only the size. All of these mechanisms, though, are very expensive in at least some situations. A very useful example of such a worst-case situation is a generic forwarding contract; a contract that takes call data, potentially makes some checks and then forwards it as is to another contract. The return data should of course be transferred in a similar way to the original caller. Since the contract is generic and does not know about the contract it calls, there is no way to determine the size of the output without adapting the called contract accordingly or trying a logarithmic number of calls.</p> <p>Compiler implementors are advised to reserve a zero-length area for return data if the size of the return data is unknown before the call and then use <code>RETURNDATACOPY</code> in conjunction with <code>RETURNDATASIZE</code> to actually retrieve the data.</p> <p>Note that this proposal also makes the EIP that proposes to allow to return data in case of an intentional state reversion (<a href="https://wg-eips.ritovision.com/140/">EIP-140</a>) much more useful. Since the size of the failure data might be larger than the regular return data (or even unknown), it is possible to retrieve the failure data after the CALL opcode has signalled a failure, even if the regular output area is not large enough to hold the data.</p> <h2 id="specification">Specification</h2> <p>If <code>block.number &gt;= BYZANTIUM_FORK_BLKNUM</code>, add two new opcodes and amend the semantics of any opcode that creates a new call frame (like <code>CALL</code>, <code>CREATE</code>, <code>DELEGATECALL</code>, ...) called call-like opcodes in the following. It is assumed that the EVM (to be more specific: an EVM call frame) has a new internal buffer of variable size, called the return data buffer. This buffer is created empty for each new call frame. Upon executing any call-like opcode, the buffer is cleared (its size is set to zero). After executing a call-like opcode, the complete return data (or failure data, see <a href="https://wg-eips.ritovision.com/140/">EIP-140</a>) of the call is stored in the return data buffer (of the caller), and its size changed accordingly. As an exception, <code>CREATE</code> and <code>CREATE2</code> are considered to return the empty buffer in the success case and the failure data in the failure case. If the call-like opcode is executed but does not really instantiate a call frame (for example due to insufficient funds for a value transfer or if the called contract does not exist), the return data buffer is empty.</p> <p>As an optimization, it is possible to share the return data buffer across call frames because at most one will be non-empty at any time.</p> <p><code>RETURNDATASIZE</code>: <code>0x3d</code></p> <p>Pushes the size of the return data buffer onto the stack. Gas costs: 2 (same as <code>CALLDATASIZE</code>)</p> <p><code>RETURNDATACOPY</code>: <code>0x3e</code></p> <p>This opcode has similar semantics to <code>CALLDATACOPY</code>, but instead of copying data from the call data, it copies data from the return data buffer. Furthermore, accessing the return data buffer beyond its size results in a failure; i.e. if <code>start + length</code> overflows or results in a value larger than <code>RETURNDATASIZE</code>, the current call stops in an out-of-gas condition. In particular, reading 0 bytes from the end of the buffer will read 0 bytes; reading 0 bytes from one-byte out of the buffer causes an exception.</p> <p>Gas costs: <code>3 + 3 * ceil(amount / 32)</code> (same as <code>CALLDATACOPY</code>)</p> <h2 id="rationale">Rationale</h2> <p>Other solutions that would allow returning dynamic data were considered, but they all had to deduct the gas from the call opcode and thus were both complicated to implement and specify (<a rel="external" href="https://github.com/ethereum/EIPs/issues/8">5/8</a>). Since this proposal is very similar to the way calldata is handled, it fits nicely into the concept. Furthermore, the eWASM architecture already handles return data in exactly the same way.</p> <p>Note that the EVM implementation needs to keep the return data until the next call or the return from the current call. Since this resource was already paid for as part of the memory of the callee, it should not be a problem. Implementations may either choose to keep the full memory of the callee alive until the next call or copy only the return data to a special memory area.</p> <p>Keeping the memory of the callee until the next call-like opcode does not increase the peak memory usage in the following sense; any memory allocation in the caller's frame that happens after the return from the call can be moved before the call without a change in gas costs, but will add this allocation to the peak allocation.</p> <p>The number values of the opcodes were allocated in the same nibble block that also contains <code>CALLDATASIZE</code> and <code>CALLDATACOPY</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal introduces two new opcodes and stays fully backwards compatible apart from that.</p> <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> 2017-02-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinvitalik@ethereum.org Christian Reitwiessnerchris@ethereum.org https://wg-eips.ritovision.com/214/ <h2 id="simple-summary">Simple Summary</h2> <p>To increase smart contract security, this proposal adds a new opcode that can be used to call another contract (or itself) while disallowing any modifications to the state during the call (and its subcalls, if present).</p> <h2 id="abstract">Abstract</h2> <p>This proposal adds a new opcode that can be used to call another contract (or itself) while disallowing any modifications to the state during the call (and its subcalls, if present). Any opcode that attempts to perform such a modification (see below for details) will result in an exception instead of performing the modification.</p> <h2 id="motivation">Motivation</h2> <p>Currently, there is no restriction about what a called contract can do, as long as the computation can be performed with the amount of gas provided. This poses certain difficulties about smart contract engineers; after a regular call, unless you know the called contract, you cannot make any assumptions about the state of the contracts. Furthermore, because you cannot know the order of transactions before they are confirmed by miners, not even an outside observer can be sure about that in all cases.</p> <p>This EIP adds a way to call other contracts and restrict what they can do in the simplest way. It can be safely assumed that the state of all accounts is the same before and after a static call.</p> <h2 id="specification">Specification</h2> <p>Introduce a new <code>STATIC</code> flag to the virtual machine. This flag is set to <code>false</code> initially. Its value is always copied to sub-calls with an exception for the new opcode below.</p> <p>Opcode: <code>0xfa</code>.</p> <p><code>STATICCALL</code> functions equivalently to a <code>CALL</code>, except it takes only 6 arguments (the "value" argument is not included and taken to be zero), and calls the child with the <code>STATIC</code> flag set to <code>true</code> for the execution of the child. Once this call returns, the flag is reset to its value before the call.</p> <p>Any attempts to make state-changing operations inside an execution instance with <code>STATIC</code> set to <code>true</code> will instead throw an exception. These operations include <code>CREATE</code>, <code>CREATE2</code>, <code>LOG0</code>, <code>LOG1</code>, <code>LOG2</code>, <code>LOG3</code>, <code>LOG4</code>, <code>SSTORE</code>, and <code>SELFDESTRUCT</code>. They also include <code>CALL</code> with a non-zero value. As an exception, <code>CALLCODE</code> is not considered state-changing, even with a non-zero value.</p> <h2 id="rationale">Rationale</h2> <p>This allows contracts to make calls that are clearly non-state-changing, reassuring developers and reviewers that re-entrancy bugs or other problems cannot possibly arise from that particular call; it is a pure function that returns an output and does nothing else. This may also make purely functional HLLs easier to implement.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal adds a new opcode but does not modify the behaviour of other opcodes and thus is backwards compatible for old contracts that do not use the new opcode and are not called via the new opcode.</p> <h2 id="test-cases">Test Cases</h2> <p>To be written.</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-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-09T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/141/ <h2 id="abstract">Abstract</h2> <p>An instruction is designated to remain as an invalid instruction.</p> <h2 id="motivation">Motivation</h2> <p>The invalid instruction can be used as a distinct reason to abort execution.</p> <h2 id="specification">Specification</h2> <p>The opcode <code>0xfe</code> is the <code>INVALID</code> instruction. It can be used to abort the execution (i.e. duplicates as an <code>ABORT</code> instruction).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This instruction was never used and therefore has no effect on past 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> 2017-02-06T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic Nikolai Mushegiannikolai@nexusdev.us https://wg-eips.ritovision.com/140/ <h2 id="simple-summary">Simple Summary</h2> <p>The <code>REVERT</code> instruction provides a way to stop execution and revert state changes, without consuming all provided gas and with the ability to return a reason.</p> <h2 id="abstract">Abstract</h2> <p>The <code>REVERT</code> instruction will stop execution, roll back all state changes done so far and provide a pointer to a memory section, which can be interpreted as an error code or message. While doing so, it will not consume all the remaining gas.</p> <h2 id="motivation">Motivation</h2> <p>Currently this is not possible. There are two practical ways to revert a transaction from within a contract: running out of gas or executing an invalid instruction. Both of these options will consume all remaining gas. Additionally, reverting an EVM execution means that all changes, including LOGs, are lost and there is no way to convey a reason for aborting an EVM execution.</p> <h2 id="specification">Specification</h2> <p>On blocks with <code>block.number &gt;= BYZANTIUM_FORK_BLKNUM</code>, the <code>REVERT</code> instruction is introduced at <code>0xfd</code>. It expects two stack items, the top item is the <code>memory_offset</code> followed by <code>memory_length</code>. It does not produce any stack elements because it stops execution.</p> <p>The semantics of <code>REVERT</code> with respect to memory and memory cost are identical to those of <code>RETURN</code>. The sequence of bytes given by <code>memory_offset</code> and <code>memory_length</code> is called "error message" in the following.</p> <p>The effect of <code>REVERT</code> is that execution is aborted, considered as failed, and state changes are rolled back. The error message will be available to the caller in the returndata buffer and will also be copied to the output area, i.e. it is handled in the same way as the regular return data is handled.</p> <p>The cost of the <code>REVERT</code> instruction equals to that of the <code>RETURN</code> instruction, i.e. the rollback itself does not consume all gas, the contract only has to pay for memory.</p> <p>In case there is not enough gas left to cover the cost of <code>REVERT</code> or there is a stack underflow, the effect of the <code>REVERT</code> instruction will equal to that of a regular out of gas exception, i.e. it will consume all gas.</p> <p>In the same way as all other failures, the calling opcode returns <code>0</code> on the stack following a <code>REVERT</code> opcode in the callee.</p> <p>In case <code>REVERT</code> is used in the context of a <code>CREATE</code> or <code>CREATE2</code> call, no code is deployed, <code>0</code> is put on the stack and the error message is available in the returndata buffer.</p> <p>The content of the optionally provided memory section is not defined by this EIP, but is a candidate for another Informational EIP.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change has no effect on contracts created in the past unless they contain <code>0xfd</code> as an instruction.</p> <h2 id="test-cases">Test Cases</h2> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>6c726576657274656420646174616000557f726576657274206d657373616765000000000000000000000000000000000000600052600e6000fd</span></span></code></pre> <p>should:</p> <ul> <li>return <code>0x726576657274206d657373616765</code> as <code>REVERT</code> data,</li> <li>the storage at key <code>0x0</code> should be left as unset and</li> <li>use 20024 gas in total.</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> 2017-02-06T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinvitalik@ethereum.org Christian Reitwiessnerchris@ethereum.org https://wg-eips.ritovision.com/197/ <h2 id="simple-summary">Simple Summary</h2> <p>Precompiled contracts for elliptic curve pairing operations are required in order to perform zkSNARK verification within the block gas limit.</p> <h2 id="abstract">Abstract</h2> <p>This EIP suggests to add precompiled contracts for a pairing function on a specific pairing-friendly elliptic curve. This can in turn be combined with <a href="https://wg-eips.ritovision.com/196/">EIP-196</a> to verify zkSNARKs in Ethereum smart contracts. The general benefit of zkSNARKs for Ethereum is that it will increase the privacy for users (because of the Zero-Knowledge property) and might also be a scalability solution (because of the succinctness and efficient verifiability property).</p> <h2 id="motivation">Motivation</h2> <p>Current smart contract executions on Ethereum are fully transparent, which makes them unsuitable for several use-cases that involve private information like the location, identity or history of past transactions. The technology of zkSNARKs could be a solution to this problem. While the Ethereum Virtual Machine can make use of zkSNARKs in theory, they are currently too expensive to fit the block gas limit. Because of that, this EIP proposes to specify certain parameters for some elementary primitives that enable zkSNARKs so that they can be implemented more efficiently and the gas cost be reduced.</p> <p>Note that fixing these parameters will in no way limit the use-cases for zkSNARKs, it will even allow for incorporating some advances in zkSNARK research without the need for a further hard fork.</p> <p>Pairing functions can be used to perform a limited form of multiplicatively homomorphic operations, which are necessary for current zkSNARKs. This precompile can be used to run such computations within the block gas limit. This precompiled contract only specifies a certain check, and not an evaluation of a pairing function. The reason is that the codomain of a pairing function is a rather complex field which could provide encoding problems and all known uses of pairing function in zkSNARKs only require the specified check.</p> <h2 id="specification">Specification</h2> <p>For blocks where <code>block.number &gt;= BYZANTIUM_FORK_BLKNUM</code>, add a precompiled contracts for a bilinear function on groups on the elliptic curve "alt_bn128". We will define the precompiled contract in terms of a discrete logarithm. The discrete logarithm is of course assumed to be hard to compute, but we will give an equivalent specification that makes use of elliptic curve pairing functions which can be efficiently computed below.</p> <p>Address: 0x8</p> <p>For a cyclic group <code>G</code> (written additively) of prime order <code>q</code> let <code>log_P: G -&gt; F_q</code> be the discrete logarithm on this group with respect to a generator <code>P</code>, i.e. <code>log_P(x)</code> is the smallest non-negative integer <code>n</code> such that <code>n * P = x</code>.</p> <p>The precompiled contract is defined as follows, where the two groups <code>G_1</code> and <code>G_2</code> are defined by their generators <code>P_1</code> and <code>P_2</code> below. Both generators have the same prime order <code>q</code>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Input: (a1, b1, a2, b2, ..., ak, bk) from (G_1 x G_2)^k</span></span> <span class="giallo-l"><span>Output: If the length of the input is incorrect or any of the inputs are not elements of</span></span> <span class="giallo-l"><span> the respective group or are not encoded correctly, the call fails.</span></span> <span class="giallo-l"><span> Otherwise, return one if</span></span> <span class="giallo-l"><span> log_P1(a1) * log_P2(b1) + ... + log_P1(ak) * log_P2(bk) = 0</span></span> <span class="giallo-l"><span> (in F_q) and zero else.</span></span></code></pre> <p>Note that <code>k</code> is determined from the length of the input. Following the section on the encoding below, <code>k</code> is the length of the input divided by <code>192</code>. If the input length is not a multiple of <code>192</code>, the call fails. Empty input is valid and results in returning one.</p> <p>In order to check that an input is an element of <code>G_1</code>, verifying the encoding of the coordinates and checking that they satisfy the curve equation (or is the encoding of infinity) is sufficient. For <code>G_2</code>, in addition to that, the order of the element has to be checked to be equal to the group order <code>q = 21888242871839275222246405745257275088548364400416034343698204186575808495617</code>.</p> <h3 id="definition-of-the-groups">Definition of the groups</h3> <p>The groups <code>G_1</code> and <code>G_2</code> are cyclic groups of prime order <code>q = 21888242871839275222246405745257275088548364400416034343698204186575808495617</code>.</p> <p>The group <code>G_1</code> is defined on the curve <code>Y^2 = X^3 + 3</code> over the field <code>F_p</code> with <code>p = 21888242871839275222246405745257275088696311157297823662689037894645226208583</code> with generator <code>P1 = (1, 2)</code>.</p> <p>The group <code>G_2</code> is defined on the curve <code>Y^2 = X^3 + 3/(i+9)</code> over a different field <code>F_p^2 = F_p[i] / (i^2 + 1)</code> (p is the same as above) with generator</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>P2 = (</span></span> <span class="giallo-l"><span> 11559732032986387107991004021392285783925812861821192530917403151452391805634 * i +</span></span> <span class="giallo-l"><span> 10857046999023057135944570762232829481370756359578518086990519993285655852781,</span></span> <span class="giallo-l"><span> 4082367875863433681332203403145435568316851327593401208105741076214120093531 * i +</span></span> <span class="giallo-l"><span> 8495653923123431417604973247489272438418190587263600148770280649306958101930</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>Note that <code>G_2</code> is the only group of order <code>q</code> of that elliptic curve over the field <code>F_p^2</code>. Any other generator of order <code>q</code> instead of <code>P2</code> would define the same <code>G_2</code>. However, the concrete value of <code>P2</code> is useful for skeptical readers who doubt the existence of a group of order <code>q</code>. They can be instructed to compare the concrete values of <code>q * P2</code> and <code>P2</code>.</p> <h3 id="encoding">Encoding</h3> <p>Elements of <code>F_p</code> are encoded as 32 byte big-endian numbers. An encoding value of <code>p</code> or larger is invalid.</p> <p>Elements <code>a * i + b</code> of <code>F_p^2</code> are encoded as two elements of <code>F_p</code>, <code>(a, b)</code>.</p> <p>Elliptic curve points are encoded as a Jacobian pair <code>(X, Y)</code> where the point at infinity is encoded as <code>(0, 0)</code>.</p> <p>Note that the number <code>k</code> is derived from the input length.</p> <p>The length of the returned data is always exactly 32 bytes and encoded as a 32 byte big-endian number.</p> <h3 id="gas-costs">Gas costs</h3> <p>The gas costs of the precompiled contract are <code>80 000 * k + 100 000</code>, where <code>k</code> is the number of points or, equivalently, the length of the input divided by 192.</p> <h2 id="rationale">Rationale</h2> <p>The specific curve <code>alt_bn128</code> was chosen because it is particularly well-suited for zkSNARKs, or, more specifically their verification building block of pairing functions. Furthermore, by choosing this curve, we can use synergy effects with ZCash and re-use some of their components and artifacts.</p> <p>The feature of adding curve and field parameters to the inputs was considered but ultimately rejected since it complicates the specification; the gas costs are much harder to determine and it would be possible to call the contracts on something which is not an actual elliptic curve or does not admit an efficient pairing implementation.</p> <p>A non-compact point encoding was chosen since it still allows to perform some operations in the smart contract itself (inclusion of the full y coordinate) and two encoded points can be compared for equality (no third projective coordinate).</p> <p>The encoding of field elements in <code>F_p^2</code> was chosen in this order to be in line with the big endian encoding of the elements themselves.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As with the introduction of any precompiled contract, contracts that already use the given addresses will change their semantics. Because of that, the addresses are taken from the "reserved range" below 256.</p> <h2 id="test-cases">Test Cases</h2> <p>To be written.</p> <h2 id="implementation">Implementation</h2> <p>The precompiled contract can be implemented using elliptic curve pairing functions, more specifically, an optimal ate pairing on the alt_bn128 curve, which can be implemented efficiently. In order to see that, first note that a pairing function <code>e: G_1 x G_2 -&gt; G_T</code> fulfills the following properties (<code>G_1</code> and <code>G_2</code> are written additively, <code>G_T</code> is written multiplicatively):</p> <p>(1) <code>e(m * P1, n * P2) = e(P1, P2)^(m * n)</code> (2) <code>e</code> is non-degenerate</p> <p>Now observe that</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>log_P1(a1) * log_P2(b1) + ... + log_P1(ak) * log_P2(bk) = 0 (in F_q)</span></span></code></pre> <p>if and only if</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>e(P1, P2)^(log_P1(a1) * log_P2(b1) + ... + log_P1(ak) * log_P2(bk)) = 1 (in G_T)</span></span></code></pre> <p>Furthermore, the left hand side of this equation is equal to</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>e(log_P1(a1) * P1, log_P2(b1) * P2) * ... * e(log_P1(ak) * P1, log_P2(bk) * P2)</span></span> <span class="giallo-l"><span>= e(a1, b1) * ... * e(ak, bk)</span></span></code></pre> <p>And thus, the precompiled contract can be implemented by verifying that <code>e(a1, b1) * ... * e(ak, bk) = 1</code></p> <p>Implementations are available here:</p> <ul> <li><a rel="external" href="https://github.com/scipr-lab/libff/blob/master/libff/algebra/curves/alt_bn128/alt_bn128_g1.hpp">libff</a> (C++)</li> <li><a rel="external" href="https://github.com/zcash/bn/blob/master/src/groups/mod.rs">bn</a> (Rust)</li> <li><a rel="external" href="https://github.com/ethereum/py_pairing/blob/master/py_ecc/bn128/bn128_pairing.py">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> 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> 2017-02-02T00:00:00+00:00 2026-02-11T14:49:27+00:00 Christian Reitwiessnerchris@ethereum.org https://wg-eips.ritovision.com/196/ <h2 id="simple-summary">Simple Summary</h2> <p>Precompiled contracts for elliptic curve operations are required in order to perform zkSNARK verification within the block gas limit.</p> <h2 id="abstract">Abstract</h2> <p>This EIP suggests to add precompiled contracts for addition and scalar multiplication on a specific pairing-friendly elliptic curve. This can in turn be combined with <a href="https://wg-eips.ritovision.com/197/">EIP-197</a> to verify zkSNARKs in Ethereum smart contracts. The general benefit of zkSNARKs for Ethereum is that it will increase the privacy for users (because of the Zero-Knowledge property) and might also be a scalability solution (because of the succinctness and efficient verifiability property).</p> <h2 id="motivation">Motivation</h2> <p>Current smart contract executions on Ethereum are fully transparent, which makes them unsuitable for several use-cases that involve private information like the location, identity or history of past transactions. The technology of zkSNARKs could be a solution to this problem. While the Ethereum Virtual Machine can make use of zkSNARKs in theory, they are currently too expensive to fit the block gas limit. Because of that, this EIP proposes to specify certain parameters for some elementary primitives that enable zkSNARKs so that they can be implemented more efficiently and the gas cost be reduced.</p> <p>Note that while fixing these parameters might look like limiting the use-cases for zkSNARKs, the primitives are so basic that they can be combined in ways that are flexible enough so that it should even be possible to allow future advances in zkSNARK research without the need for a further hard fork.</p> <h2 id="specification">Specification</h2> <p>If <code>block.number &gt;= BYZANTIUM_FORK_BLKNUM</code>, add precompiled contracts for point addition (ADD) and scalar multiplication (MUL) on the elliptic curve "alt_bn128".</p> <p>Address of ADD: 0x6 Address for MUL: 0x7</p> <p>The curve is defined by:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Y^2 = X^3 + 3</span></span> <span class="giallo-l"><span>over the field F_p with</span></span> <span class="giallo-l"><span>p = 21888242871839275222246405745257275088696311157297823662689037894645226208583</span></span></code></pre><h3 id="encoding">Encoding</h3> <p>Field elements and scalars are encoded as 32 byte big-endian numbers. Curve points are encoded as two field elements <code>(x, y)</code>, where the point at infinity is encoded as <code>(0, 0)</code>.</p> <p>Tuples of objects are encoded as their concatenation.</p> <p>For both precompiled contracts, if the input is shorter than expected, it is assumed to be virtually padded with zeros at the end (i.e. compatible with the semantics of the <code>CALLDATALOAD</code> opcode). If the input is longer than expected, surplus bytes at the end are ignored.</p> <p>The length of the returned data is always as specified (i.e. it is not "unpadded").</p> <h3 id="exact-semantics">Exact semantics</h3> <p>Invalid input: For both contracts, if any input point does not lie on the curve or any of the field elements (point coordinates) is equal or larger than the field modulus p, the contract fails. The scalar can be any number between <code>0</code> and <code>2**256-1</code>.</p> <h4 id="add">ADD</h4> <p>Input: two curve points <code>(x, y)</code>. Output: curve point <code>x + y</code>, where <code>+</code> is point addition on the elliptic curve <code>alt_bn128</code> specified above. Fails on invalid input and consumes all gas provided.</p> <h4 id="mul">MUL</h4> <p>Input: curve point and scalar <code>(x, s)</code>. Output: curve point <code>s * x</code>, where <code>*</code> is the scalar multiplication on the elliptic curve <code>alt_bn128</code> specified above. Fails on invalid input and consumes all gas.</p> <h3 id="gas-costs">Gas costs</h3> <ul> <li>Gas cost for <code>ECADD</code>: 500</li> <li>Gas cost for <code>ECMUL</code>: 40000</li> </ul> <h2 id="rationale">Rationale</h2> <p>The specific curve <code>alt_bn128</code> was chosen because it is particularly well-suited for zkSNARKs, or, more specifically their verification building block of pairing functions. Furthermore, by choosing this curve, we can use synergy effects with ZCash and re-use some of their components and artifacts.</p> <p>The feature of adding curve and field parameters to the inputs was considered but ultimately rejected since it complicates the specification: The gas costs are much harder to determine and it would be possible to call the contracts on something which is not an actual elliptic curve.</p> <p>A non-compact point encoding was chosen since it still allows to perform some operations in the smart contract itself (inclusion of the full y coordinate) and two encoded points can be compared for equality (no third projective coordinate).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As with the introduction of any precompiled contract, contracts that already use the given addresses will change their semantics. Because of that, the addresses are taken from the "reserved range" below 256.</p> <h2 id="test-cases">Test Cases</h2> <p>Inputs to test:</p> <ul> <li>Curve points which would be valid if the numbers were taken mod p (should fail).</li> <li>Both contracts should succeed on empty input.</li> <li>Truncated input that results in a valid curve point.</li> <li>Points not on curve (but valid otherwise).</li> <li>Multiply point with scalar that lies between the order of the group and the field (should succeed).</li> <li>Multiply point with scalar that is larger than the field order (should succeed).</li> </ul> <h2 id="implementation">Implementation</h2> <p>Implementation of these primitives are available here:</p> <ul> <li><a rel="external" href="https://github.com/scipr-lab/libff/blob/master/libff/algebra/curves/alt_bn128/alt_bn128_g1.cpp">libff</a> (C++)</li> <li><a rel="external" href="https://github.com/zcash/bn/blob/master/src/groups/mod.rs">bn</a> (Rust)</li> </ul> <p>In both codebases, a specific group on the curve alt_bn128 is used and is called G1.</p> <ul> <li><a rel="external" href="https://github.com/ethereum/py_pairing/blob/master/py_ecc/bn128/bn128_curve.py">Python</a> - probably most self-contained and best readable.</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> 2017-01-30T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/198/ <h1 id="parameters">Parameters</h1> <ul> <li><code>GQUADDIVISOR: 20</code></li> </ul> <h1 id="specification">Specification</h1> <p>At address 0x00......05, add a precompile that expects input in the following format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&lt;length_of_BASE&gt; &lt;length_of_EXPONENT&gt; &lt;length_of_MODULUS&gt; &lt;BASE&gt; &lt;EXPONENT&gt; &lt;MODULUS&gt;</span></span></code></pre> <p>Where every length is a 32-byte left-padded integer representing the number of bytes to be taken up by the next value. Call data is assumed to be infinitely right-padded with zero bytes, and excess data is ignored. Consumes <code>floor(mult_complexity(max(length_of_MODULUS, length_of_BASE)) * max(ADJUSTED_EXPONENT_LENGTH, 1) / GQUADDIVISOR)</code> gas, and if there is enough gas, returns an output <code>(BASE**EXPONENT) % MODULUS</code> as a byte array with the same length as the modulus.</p> <p><code>ADJUSTED_EXPONENT_LENGTH</code> is defined as follows.</p> <ul> <li>If <code>length_of_EXPONENT &lt;= 32</code>, and all bits in <code>EXPONENT</code> are 0, return 0</li> <li>If <code>length_of_EXPONENT &lt;= 32</code>, then return the index of the highest bit in <code>EXPONENT</code> (eg. 1 -&gt; 0, 2 -&gt; 1, 3 -&gt; 1, 255 -&gt; 7, 256 -&gt; 8).</li> <li>If <code>length_of_EXPONENT &gt; 32</code>, then return <code>8 * (length_of_EXPONENT - 32)</code> plus the index of the highest bit in the first 32 bytes of <code>EXPONENT</code> (eg. if <code>EXPONENT = \x00\x00\x01\x00.....\x00</code>, with one hundred bytes, then the result is 8 * (100 - 32) + 253 = 797). If all of the first 32 bytes of <code>EXPONENT</code> are zero, return exactly <code>8 * (length_of_EXPONENT - 32)</code>.</li> </ul> <p><code>mult_complexity</code> is a function intended to approximate the difficulty of Karatsuba multiplication (used in all major bigint libraries) and is defined as follows.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def mult_complexity(x):</span></span> <span class="giallo-l"><span> if x &lt;= 64: return x ** 2</span></span> <span class="giallo-l"><span> elif x &lt;= 1024: return x ** 2 // 4 + 96 * x - 3072</span></span> <span class="giallo-l"><span> else: return x ** 2 // 16 + 480 * x - 199680</span></span></code></pre> <p>For example, the input data:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000020</span></span> <span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000020</span></span> <span class="giallo-l"><span>03</span></span> <span class="giallo-l"><span>fffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2e</span></span> <span class="giallo-l"><span>fffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2f</span></span></code></pre> <p>Represents the exponent <code>3**(2**256 - 2**32 - 978) % (2**256 - 2**32 - 977)</code>. By Fermat's little theorem, this equals 1, so the result is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000001</span></span></code></pre> <p>Returned as 32 bytes because the modulus length was 32 bytes. The <code>ADJUSTED_EXPONENT_LENGTH</code> would be 255, and the gas cost would be <code>mult_complexity(32) * 255 / 20 = 13056</code> gas (note that this is ~8 times the cost of using the EXP opcode to compute a 32-byte exponent). A 4096-bit RSA exponentiation would cost <code>mult_complexity(512) * 4095 / 100 = 22853376</code> gas in the worst case, though RSA verification in practice usually uses an exponent of 3 or 65537, which would reduce the gas consumption to 5580 or 89292, respectively.</p> <p>This input data:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000020</span></span> <span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000020</span></span> <span class="giallo-l"><span>fffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2e</span></span> <span class="giallo-l"><span>fffffffffffffffffffffffffffffffffffffffffffffffffffffffefffffc2f</span></span></code></pre> <p>Would be parsed as a base of 0, exponent of <code>2**256 - 2**32 - 978</code> and modulus of <code>2**256 - 2**32 - 977</code>, and so would return 0. Notice how if the length_of_BASE is 0, then it does not interpret <em>any</em> data as the base, instead immediately interpreting the next 32 bytes as EXPONENT.</p> <p>This input data:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000020</span></span> <span class="giallo-l"><span>ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe</span></span> <span class="giallo-l"><span>fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffd</span></span></code></pre> <p>Would parse a base length of 0, an exponent length of 32, and a modulus length of <code>2**256 - 1</code>, where the base is empty, the exponent is <code>2**256 - 2</code> and the modulus is <code>(2**256 - 3) * 256**(2**256 - 33)</code> (yes, that's a really big number). It would then immediately fail, as it's not possible to provide enough gas to make that computation.</p> <p>This input data:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000002</span></span> <span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000020</span></span> <span class="giallo-l"><span>03</span></span> <span class="giallo-l"><span>ffff</span></span> <span class="giallo-l"><span>8000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>07</span></span></code></pre> <p>Would parse as a base of 3, an exponent of 65535, and a modulus of <code>2**255</code>, and it would ignore the remaining 0x07 byte.</p> <p>This input data:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000002</span></span> <span class="giallo-l"><span>0000000000000000000000000000000000000000000000000000000000000020</span></span> <span class="giallo-l"><span>03</span></span> <span class="giallo-l"><span>ffff</span></span> <span class="giallo-l"><span>80</span></span></code></pre> <p>Would also parse as a base of 3, an exponent of 65535 and a modulus of <code>2**255</code>, as it attempts to grab 32 bytes for the modulus starting from 0x80 - but there is no further data, so it right-pads it with 31 zero bytes.</p> <h1 id="rationale">Rationale</h1> <p>This allows for efficient RSA verification inside of the EVM, as well as other forms of number theory-based cryptography. Note that adding precompiles for addition and subtraction is not required, as the in-EVM algorithm is efficient enough, and multiplication can be done through this precompile via <code>a * b = ((a + b)**2 - (a - b)**2) / 4</code>.</p> <p>The bit-based exponent calculation is done specifically to fairly charge for the often-used exponents of 2 (for multiplication) and 3 and 65537 (for RSA verification).</p> <h1 id="copyright">Copyright</h1> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2017-01-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Piper Merriamhttps://github.com/pipermerriam Tim Coulterhttps://github.com/tcoulter Denis Erfurthttps://github.com/mhhf RJ Catalanohttps://github.com/VoR0220 Iuri Matiashttps://github.com/iurimatias https://wg-eips.ritovision.com/190/ <h1 id="abstract">Abstract</h1> <p>This ERC proposes a specification for Ethereum smart contract packages.</p> <p>The specification was collaboratively developed by the following Ethereum development framework maintainers.</p> <ul> <li>Tim Coulter (Truffle)</li> <li>Denis Erfurt (Dapple)</li> <li>Piper Merriam (Populus)</li> <li>RJ Catalano (Eris PM)</li> <li>Iuri Matias (Embark)</li> </ul> <h1 id="motivation">Motivation</h1> <p>Packaging is a core piece of modern software development which is missing from the Ethereum ecosystem. The lack of packaging limits the ability for developers to reuse code which negatively affects productivity and security.</p> <p>A key example of this is the ERC20 standard. There are a few well audited reusable token contracts available but most developers end up writing their own because of the difficulty in finding and reusing existing code.</p> <p>A packaging standard should have the following positive effects on the ecosystem:</p> <ul> <li>Greater overall productivity caused by the ability to reuse existing code.</li> <li>Increased security caused by the ability to reuse existing well audited implementations of common patterns (ERC20, crowdfunding, etc).</li> </ul> <p>Smart contract packaging should also have a direct positive effect on the end user. Wallet software will be able to consume a released package and generate an interface for interacting with any deployed contracts included within that package. With the advent of <a href="https://wg-eips.ritovision.com/137/">ENS</a> all of the pieces will be in place for a wallet to take a human readable name and present the user with an interface for interacting with the underlying application.</p> <h1 id="specification">Specification</h1> <p>The full specification for this standard is maintained separately in the repository <a rel="external" href="https://github.com/ethpm/epm-spec">epm/epm-spec</a>.</p> <p>This EIP refers to the <code>1.0.0</code> version of the specification: <a rel="external" href="https://github.com/ethpm/epm-spec/tree/v1.0.0">https://github.com/ethpm/epm-spec/tree/v1.0.0</a></p> <p>The specification contains details for a single document referred to as a <em>"Release Lockfile"</em>.</p> <ul> <li>Release Lockfile Specification: <a rel="external" href="https://github.com/ethpm/epm-spec/blob/v1.0.0/release-lockfile.spec.md">https://github.com/ethpm/epm-spec/blob/v1.0.0/release-lockfile.spec.md</a>.</li> <li>JSON Schema for Release Lockfile: <a rel="external" href="https://github.com/ethpm/epm-spec/blob/v1.0.0/spec/release-lockfile.spec.json">https://github.com/ethpm/epm-spec/blob/v1.0.0/spec/release-lockfile.spec.json</a></li> </ul> <blockquote> <p>These documents have not been inlined into this ERC to ensure that there is a single source of truth for the specification.</p> </blockquote> <h1 id="use-cases">Use Cases</h1> <p>This specification covers the following types of smart contract packages.</p> <ol> <li>Packages with contracts intended to be used as base contract such as the common <code>owned</code> pattern.</li> <li>Packages with contracts that are ready to use as-is such as an ERC20 token contract.</li> <li>Packages with deployed contracts such as libraries or services.</li> </ol> <p>Full explanations and examples of these use cases can be found in the <a rel="external" href="https://github.com/ethpm/epm-spec/blob/v1.0.0/README.md#use-cases"><code>README.md</code></a> from the <code>epm/epm-spec</code> repository.</p> <h1 id="package-managers">Package Managers</h1> <p>The <em>Release Lockfile</em> is intended for consumption by package management software. Specific care was made to ensure that all of the following functionality can be implemented by package managers.</p> <h2 id="deterministic-builds">Deterministic builds</h2> <p>Ensures that a package will always resolve to the same set of dependencies and source files. Both source files and dependencies are content addressed to ensure that the referenced resources cannot change.</p> <h2 id="bytecode-verification">Bytecode verification</h2> <p>Contains the appropriate information for a package manager to inspect a deployed contract and verify that its bytecode matches the bytecode that results from compilation and linking of the package source code.</p> <h2 id="multi-chain-deploys">Multi-chain deploys</h2> <p>Supports deployments across multiple chains, allowing a package to define addresses on both the public mainnet and testnet.</p> <h2 id="trusted-packages">Trusted packages</h2> <p>Allows for packages which exclude source code or other elements which would be needed for verification of the contract bytecode. This allows for minimalistic packages to be created for special situations where the package manager will not be performing verification.</p> <h1 id="framework-support-and-integration">Framework support and integration</h1> <p>Support for ERC190 is either implemented or in progress for the following:</p> <ul> <li><a rel="external" href="https://truffleframework.com/">Truffle</a></li> <li><a rel="external" href="https://populus.readthedocs.io/en/latest/">Populus</a></li> <li><a rel="external" href="https://dapple.readthedocs.io/en/master/">Dapple</a></li> <li><a rel="external" href="https://github.com/eris-ltd/eris-cli">Eris PM</a></li> <li><a rel="external" href="https://github.com/iurimatias/embark-framework">Embark</a></li> <li><a rel="external" href="https://github.com/ethereum/remix-ide/issues/386">Browser Solidity</a></li> </ul> 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-12-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Johnsonarachnid@notdot.net https://wg-eips.ritovision.com/181/ <h1 id="abstract">Abstract</h1> <p>This EIP specifies a TLD, registrar, and resolver interface for reverse resolution of Ethereum addresses using ENS. This permits associating a human-readable name with any Ethereum blockchain address. Resolvers can be certain that the reverse record was published by the owner of the Ethereum address in question.</p> <h1 id="motivation">Motivation</h1> <p>While name services are mostly used for forward resolution - going from human-readable identifiers to machine-readable ones - there are many use-cases in which reverse resolution is useful as well:</p> <ul> <li>Applications that allow users to monitor accounts benefit from showing the name of an account instead of its address, even if it was originally added by address.</li> <li>Attaching metadata such as descriptive information to an address allows retrieving this information regardless of how the address was originally discovered.</li> <li>Anyone can configure a name to resolve to an address, regardless of ownership of that address. Reverse records allow the owner of an address to claim a name as authoritative for that address.</li> </ul> <h1 id="specification">Specification</h1> <p>Reverse ENS records are stored in the ENS hierarchy in the same fashion as regular records, under a reserved domain, <code>addr.reverse</code>. To generate the ENS name for a given account's reverse records, convert the account to hexadecimal representation in lower-case, and append <code>addr.reverse</code>. For instance, the ENS registry's address at <code>0x112234455c3a32fd11230c42e7bccd4a84e02010</code> has any reverse records stored at <code>112234455c3a32fd11230c42e7bccd4a84e02010.addr.reverse</code>.</p> <p>Note that this means that contracts wanting to do dynamic reverse resolution of addresses will need to perform hex encoding in the contract.</p> <h2 id="registrar">Registrar</h2> <p>The owner of the <code>addr.reverse</code> domain will be a registrar that permits the caller to take ownership of the reverse record for their own address. It provides the following methods:</p> <h3 id="function-claim-address-owner-returns-bytes32-node">function claim(address owner) returns (bytes32 node)</h3> <p>When called by account <code>x</code>, instructs the ENS registry to transfer ownership of the name <code>hex(x) + '.addr.reverse'</code> to the provided address, and return the namehash of the ENS record thus transferred.</p> <p>Allowing the caller to specify an owner other than themselves for the relevant node facilitates contracts that need accurate reverse ENS entries delegating this to their creators with a minimum of code inside their constructor:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>reverseRegistrar.claim(msg.sender)</span></span></code></pre><h3 id="function-claimwithresolver-address-owner-address-resolver-returns-bytes32-node">function claimWithResolver(address owner, address resolver) returns (bytes32 node)</h3> <p>When called by account <code>x</code>, instructs the ENS registry to set the resolver of the name <code>hex(x) + '.addr.reverse'</code> to the specified resolver, then transfer ownership of the name to the provided address, and return the namehash of the ENS record thus transferred. This method facilitates setting up a custom resolver and owner in fewer transactions than would be required if calling <code>claim</code>.</p> <h3 id="function-setname-string-name-returns-bytes32-node">function setName(string name) returns (bytes32 node)</h3> <p>When called by account <code>x</code>, sets the resolver for the name <code>hex(x) + '.addr.reverse'</code> to a default resolver, and sets the name record on that name to the specified name. This method facilitates setting up simple reverse records for users in a single transaction.</p> <h2 id="resolver-interface">Resolver interface</h2> <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 name(bytes32 node) constant returns (string);</span></span></code></pre> <p>Resolvers that implement this interface must return a valid ENS name for the requested node, or the empty string if no name is defined for the requested node.</p> <p>The interface ID of this interface is 0x691f3431.</p> <p>Future EIPs may specify more record types appropriate to reverse ENS records.</p> <h1 id="appendix-1-registrar-implementation">Appendix 1: Registrar implementation</h1> <p>This registrar, written in Solidity, implements the specifications outlined above.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pragma solidity ^0.4.10;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>import &quot;./AbstractENS.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>contract Resolver {</span></span> <span class="giallo-l"><span> function setName(bytes32 node, string name) public;</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> * @dev Provides a default implementation of a resolver for reverse records,</span></span> <span class="giallo-l"><span> * which permits only the owner to update it.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>contract DefaultReverseResolver is Resolver {</span></span> <span class="giallo-l"><span> AbstractENS public ens;</span></span> <span class="giallo-l"><span> mapping(bytes32=&gt;string) public name;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Constructor</span></span> <span class="giallo-l"><span> * @param ensAddr The address of the ENS registry.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function DefaultReverseResolver(AbstractENS ensAddr) {</span></span> <span class="giallo-l"><span> ens = ensAddr;</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> * @dev Only permits calls by the reverse registrar.</span></span> <span class="giallo-l"><span> * @param node The node permission is required for.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> modifier owner_only(bytes32 node) {</span></span> <span class="giallo-l"><span> require(msg.sender == ens.owner(node));</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> <span class="giallo-l"><span> * @dev Sets the name for a node.</span></span> <span class="giallo-l"><span> * @param node The node to update.</span></span> <span class="giallo-l"><span> * @param _name The name to set.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function setName(bytes32 node, string _name) public owner_only(node) {</span></span> <span class="giallo-l"><span> name[node] = _name;</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>contract ReverseRegistrar {</span></span> <span class="giallo-l"><span> // namehash(&#39;addr.reverse&#39;)</span></span> <span class="giallo-l"><span> bytes32 constant ADDR_REVERSE_NODE = 0x91d1777781884d03a6757a803996e38de2a42967fb37eeaca72729271025a9e2;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> AbstractENS public ens;</span></span> <span class="giallo-l"><span> Resolver public defaultResolver;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Constructor</span></span> <span class="giallo-l"><span> * @param ensAddr The address of the ENS registry.</span></span> <span class="giallo-l"><span> * @param resolverAddr The address of the default reverse resolver.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function ReverseRegistrar(AbstractENS ensAddr, Resolver resolverAddr) {</span></span> <span class="giallo-l"><span> ens = ensAddr;</span></span> <span class="giallo-l"><span> defaultResolver = resolverAddr;</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> * @dev Transfers ownership of the reverse ENS record associated with the</span></span> <span class="giallo-l"><span> * calling account.</span></span> <span class="giallo-l"><span> * @param owner The address to set as the owner of the reverse record in ENS.</span></span> <span class="giallo-l"><span> * @return The ENS node hash of the reverse record.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function claim(address owner) returns (bytes32 node) {</span></span> <span class="giallo-l"><span> return claimWithResolver(owner, 0);</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> * @dev Transfers ownership of the reverse ENS record associated with the</span></span> <span class="giallo-l"><span> * calling account.</span></span> <span class="giallo-l"><span> * @param owner The address to set as the owner of the reverse record in ENS.</span></span> <span class="giallo-l"><span> * @param resolver The address of the resolver to set; 0 to leave unchanged.</span></span> <span class="giallo-l"><span> * @return The ENS node hash of the reverse record.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function claimWithResolver(address owner, address resolver) returns (bytes32 node) {</span></span> <span class="giallo-l"><span> var label = sha3HexAddress(msg.sender);</span></span> <span class="giallo-l"><span> node = sha3(ADDR_REVERSE_NODE, label);</span></span> <span class="giallo-l"><span> var currentOwner = ens.owner(node);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Update the resolver if required</span></span> <span class="giallo-l"><span> if(resolver != 0 &amp;&amp; resolver != ens.resolver(node)) {</span></span> <span class="giallo-l"><span> // Transfer the name to us first if it&#39;s not already</span></span> <span class="giallo-l"><span> if(currentOwner != address(this)) {</span></span> <span class="giallo-l"><span> ens.setSubnodeOwner(ADDR_REVERSE_NODE, label, this);</span></span> <span class="giallo-l"><span> currentOwner = address(this);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ens.setResolver(node, resolver);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Update the owner if required</span></span> <span class="giallo-l"><span> if(currentOwner != owner) {</span></span> <span class="giallo-l"><span> ens.setSubnodeOwner(ADDR_REVERSE_NODE, label, owner);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> return node;</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> * @dev Sets the `name()` record for the reverse ENS record associated with</span></span> <span class="giallo-l"><span> * the calling account. First updates the resolver to the default reverse</span></span> <span class="giallo-l"><span> * resolver if necessary.</span></span> <span class="giallo-l"><span> * @param name The name to set for this address.</span></span> <span class="giallo-l"><span> * @return The ENS node hash of the reverse record.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function setName(string name) returns (bytes32 node) {</span></span> <span class="giallo-l"><span> node = claimWithResolver(this, defaultResolver);</span></span> <span class="giallo-l"><span> defaultResolver.setName(node, name);</span></span> <span class="giallo-l"><span> return node;</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> * @dev Returns the node hash for a given account&#39;s reverse records.</span></span> <span class="giallo-l"><span> * @param addr The address to hash</span></span> <span class="giallo-l"><span> * @return The ENS node hash.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function node(address addr) constant returns (bytes32 ret) {</span></span> <span class="giallo-l"><span> return sha3(ADDR_REVERSE_NODE, sha3HexAddress(addr));</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> * @dev An optimised function to compute the sha3 of the lower-case</span></span> <span class="giallo-l"><span> * hexadecimal representation of an Ethereum address.</span></span> <span class="giallo-l"><span> * @param addr The address to hash</span></span> <span class="giallo-l"><span> * @return The SHA3 hash of the lower-case hexadecimal encoding of the</span></span> <span class="giallo-l"><span> * input address.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function sha3HexAddress(address addr) private returns (bytes32 ret) {</span></span> <span class="giallo-l"><span> addr; ret; // Stop warning us about unused variables</span></span> <span class="giallo-l"><span> assembly {</span></span> <span class="giallo-l"><span> let lookup := 0x3031323334353637383961626364656600000000000000000000000000000000</span></span> <span class="giallo-l"><span> let i := 40</span></span> <span class="giallo-l"><span> loop:</span></span> <span class="giallo-l"><span> i := sub(i, 1)</span></span> <span class="giallo-l"><span> mstore8(i, byte(and(addr, 0xf), lookup))</span></span> <span class="giallo-l"><span> addr := div(addr, 0x10)</span></span> <span class="giallo-l"><span> i := sub(i, 1)</span></span> <span class="giallo-l"><span> mstore8(i, byte(and(addr, 0xf), lookup))</span></span> <span class="giallo-l"><span> addr := div(addr, 0x10)</span></span> <span class="giallo-l"><span> jumpi(loop, i)</span></span> <span class="giallo-l"><span> ret := sha3(0, 40)</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> 2016-11-04T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/170/ <h3 id="hard-fork">Hard fork</h3> <p><a href="https://wg-eips.ritovision.com/607/">Spurious Dragon</a></p> <h3 id="parameters">Parameters</h3> <ul> <li><code>MAX_CODE_SIZE</code>: <code>0x6000</code> (<code>2**14 + 2**13</code>)</li> <li><code>FORK_BLKNUM</code>: 2,675,000</li> <li><code>CHAIN_ID</code>: 1 (Mainnet)</li> </ul> <h3 id="specification">Specification</h3> <p>If <code>block.number &gt;= FORK_BLKNUM</code>, then if contract creation initialization returns data with length of <strong>more than</strong> <code>MAX_CODE_SIZE</code> bytes, contract creation fails with an out of gas error.</p> <h3 id="rationale">Rationale</h3> <p>Currently, there remains one slight quadratic vulnerability in Ethereum: when a contract is called, even though the call takes a constant amount of gas, the call can trigger O(n) cost in terms of reading the code from disk, preprocessing the code for VM execution, and also adding O(n) data to the Merkle proof for the block's proof-of-validity. At current gas levels, this is acceptable even if suboptimal. At the higher gas levels that could be triggered in the future, possibly very soon due to dynamic gas limit rules, this would become a greater concern—not nearly as serious as recent denial of service attacks, but still inconvenient especially for future light clients verifying proofs of validity or invalidity. The solution is to put a hard cap on the size of an object that can be saved to the blockchain, and do so non-disruptively by setting the cap at a value slightly higher than what is feasible with current gas limits.</p> <h3 id="references">References</h3> <ol> <li>EIP-170 issue and discussion: https://github.com/ethereum/EIPs/issues/170</li> <li>pyethereum implementation: https://github.com/ethereum/pyethereum/blob/5217294871283d8dc4fb3ca9d8a78c7d416490e8/ethereum/messages.py#L397</li> </ol> 2016-10-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Maurelian Nick Johnson nick@ethereum.org Alex Van de Sandeavsa@ethereum.org https://wg-eips.ritovision.com/162/ <h2 id="contents">Contents</h2> <ul> <li>Abstract</li> <li>Motivations</li> <li>Specification <ul> <li>Initial restrictions</li> <li>Name format for hash registration</li> <li>Auctioning names</li> <li>Deeds</li> <li>Deployment and Upgrade process</li> <li>Registrar Interface</li> </ul> </li> <li>Rationale <ul> <li>Not committing to a permanent registrar at the outset</li> <li>Valid names &gt;= 7 characters</li> <li>Restricting TLD to <code>.eth</code></li> <li>Holding ether as collateral</li> </ul> </li> <li>Prior work</li> </ul> <!-- /MarkdownTOC --> <h2 id="abstract">Abstract</h2> <p>This ERC describes the implementation, as deployed to the main ethereum network on 2017-05-04, of a registrar contract to govern the allocation of names in the Ethereum Name Service (ENS). The corresponding source code is <a rel="external" href="https://github.com/ethereum/ens/blob/mainnet/contracts/HashRegistrarSimplified.sol">here</a>.</p> <p>For more background, refer to <a href="https://wg-eips.ritovision.com/137/">EIP-137</a>.</p> <blockquote> <p>Registrars are responsible for allocating domain names to users of the system, and are the only entities capable of updating the ENS; the owner of a node in the ENS registry is its registrar. Registrars may be contracts or externally owned accounts, though it is expected that the root and top-level registrars, at a minimum, will be implemented as contracts.</p> <ul> <li>EIP 137</li> </ul> </blockquote> <p>A well designed and governed registrar is essential to the success of the ENS described in EIP 137, but is described separately in this document as it is external to the core ENS protocol.</p> <p>In order to maximize utility and adoption of a new namespace, the registrar should mitigate speculation and "name squatting", however the best approach for mitigation is unclear. Thus an "initial" registrar is proposed, which implements a simple approach to name allocation. During the initial period, the available namespace will be significantly restricted to the <code>.eth</code> top level domain, and subdomain shorter than 7 characters in length disallowed. This specification largely describes @alexvandesande and @arachnid's <a rel="external" href="https://github.com/ethereum/ens/blob/mainnet/contracts/HashRegistrarSimplified.sol">hash registrar implementation</a> in order to facilitate discussion.</p> <p>The intent is to replace the Initial Registrar contract with a permanent registrar contract. The Permanent Registrar will increase the available namespace, and incorporate lessons learned from the performance of the Initial Registrar. This upgrade is expected to take place within approximately 2 years of initial deployment.</p> <h2 id="motivations">Motivations</h2> <p>The following factors should be considered in order to optimize for adoption of the ENS, and good governance of the Initial Registrar's namespace.</p> <p><strong>Upgradability:</strong> The Initial Registrar should be safely upgradeable, so that knowledge gained during its deployment can be used to replace it with an improved and permanent registrar.</p> <p><strong>Effective allocation:</strong> Newly released namespaces often create a land grab situation, resulting in many potentially valuable names being purchased but unused, with the hope of re-selling at a profit. This reduces the availability of the most useful names, in turn decreasing the utility of the name service to end users.</p> <p>Achieving an effective allocation may or may not require human intervention for dispute resolution and other forms of curation. The Initial Registrar should not aim to create to most effective possible allocation, but instead limit the cost of misallocation in the long term.</p> <p><strong>Security:</strong> The registrar will hold a balance of ether without an explicit limit. It must be designed securely.</p> <p><strong>Simplicity:</strong> The ENS specification itself emphasizes a separation of concerns, allowing the most essential element, the registry to be as simple as possible. The interim registrar in turn should be as simple as possible while still meeting its other design goals.</p> <p><strong>Adoption:</strong> Successful standards become more successful due to network effects. The registrar should consider what strategies will encourage the adoption of the ENS in general, and the namespace it controls in particular.</p> <h2 id="specification">Specification</h2> <h3 id="initial-restrictions">Initial restrictions</h3> <p>The Initial Registrar is expected to be in service for approximately two years, prior to upgrading. This should be sufficient time to learn, observe, and design an updated system.</p> <p>During the initial two year period, the available name space will be restricted to the <code>.eth</code> TLD.</p> <p>This restriction is enforced by the owner of the ENS root node who should not assign any nodes other than <code>.eth</code> to the Initial Registrar. The ENS's root node should be controlled by multiple parties using a multisig contract.</p> <p>The Initial Registrar will also prohibit registration of names 6 characters or less in length.</p> <h3 id="name-format-for-hash-registration">Name format for hash registration</h3> <p>Names submitted to the initial registrar must be hashed using Ethereum's sha3 function. Note that the hashes submitted to the registrar are the hash of the subdomain label being registered, not the namehash as defined in EIP 137.</p> <p>For example, in order to register <code>abcdefg.eth</code>, one should submit <code>sha3('abcdefg')</code>, not <code>sha3(sha3(0, 'eth'), 'abcdefg')</code>.</p> <h3 id="auctioning-names">Auctioning names</h3> <p>The registrar will allocate the available names through a Vickrey auction:</p> <blockquote> <p>A Vickrey auction is a type of sealed-bid auction. Bidders submit written bids without knowing the bid of the other people in the auction. The highest bidder wins but the price paid is the second-highest bid. This type of auction... gives bidders an incentive to bid their true value.</p> <ul> <li><a rel="external" href="https://en.wikipedia.org/wiki/Vickrey_auction">Vickrey Auction, Wikipedia</a></li> </ul> </blockquote> <p>The auction lifecycle of a name has 5 possible states, or Modes.</p> <ol> <li><strong>Not-yet-available:</strong> The majority of names will be initially unavailable for auction, and will become available some time during the 8 weeks after launch.</li> <li><strong>Open:</strong> The earliest availability for a name is determined by the most significant byte of its sha3 hash. <code>0x00</code> would become available immediately, <code>0xFF</code> would become available after 8 weeks, and the availability of other names is distributed accordingly. Once a name is available, it is possible to start an auction on it.</li> <li><strong>Auction:</strong> Once the auction for a name has begun, there is a 72 hour bidding period. Bidders must submit a payment of ether, along with sealed bids as a hash of <code>sha3(bytes32 hash, address owner, uint value, bytes32 salt)</code>. The bidder may obfuscate the true bid value by sending a greater amount of ether.</li> <li><strong>Reveal:</strong> After the bidding period, a 48 hour reveal period commences. During this time, bidders must reveal the true parameters of their sealed bid. As bids are revealed, ether payments are returned according to the schedule of "refund ratios" outlined in the table below. If no bids are revealed, the name will return to the Open state.</li> <li><strong>Owned:</strong> After the reveal period has finished, the winning bidder must submit a transaction to finalize the auction, which then calls the ENS's <code>setSubnodeOwner</code> function, recording the winning bidder's address as the owner of the hash of the name.</li> </ol> <p>The following table outlines important parameters which define the Registrar's auction mechanism.</p> <h4 id="registrar-parameters">Registrar Parameters</h4> <table><thead><tr><th>Name</th><th>Description</th><th>Value</th></tr></thead><tbody> <tr><td>totalAuctionLength</td><td>The full time period from start of auction to end of the reveal period.</td><td>5 days</td></tr> <tr><td>revealPeriod</td><td>The length of the time period during which bidding is no longer allowed, and bids must be revealed.</td><td>48 hours</td></tr> <tr><td>launchLength</td><td>The time period during which all names will become available for auction.</td><td>8 weeks</td></tr> <tr><td>minPrice</td><td>The minimum amount of ether which must be locked up in exchange for ownership of a name.</td><td>0.01 ether</td></tr> </tbody></table> <h3 id="deeds">Deeds</h3> <p>The Initial Registrar contract does not hold a balance itself. All ether sent to the Registrar will be held in a separate <code>Deed</code> contracts. A deed contract is first created and funded when a sealed bid is submitted. After an auction is completed and a hash is registered, the deed for the winning bid is held in exchange for ownership of the hash. Non-winning bids are refunded.</p> <p>A deed for an owned name may be transferred to another account by its owner, thus transferring ownership and control of the name.</p> <p>After 1 year of registration, the owner of a hash may choose to relinquish ownership and have the value of the deed returned to them.</p> <p>Deeds for non-winning bids can be closed by various methods, at which time any ether held will either be returned to the bidder, burnt, or sent to someone else as a reward for actions which help the registrar.</p> <p>The following table outlines what portion of the balance held in a deed contract will be returned upon closure, and to whom. The remaining balance will be burnt.</p> <h4 id="refund-schedule">Refund schedule</h4> <table><thead><tr><th>Reason for Deed closure</th><th>Refund Recipient</th><th>Refund Percentage</th></tr></thead><tbody> <tr><td>A valid non-winning bid is revealed.</td><td>Bidder</td><td>99.5%</td></tr> <tr><td>A bid submitted after the auction period is revealed.</td><td>Bidder</td><td>99.5%</td></tr> <tr><td>An otherwise valid bid is revealed on an owned name. ¹</td><td>Bidder</td><td>0.5%</td></tr> <tr><td>An expired sealed bid is cancelled. ²</td><td>Canceler</td><td>0.5%</td></tr> <tr><td>A registered hash is reported as invalid. ³</td><td>Reporter</td><td>50%</td></tr> <tr><td>A registered hash is reported as invalid. ³</td><td>Owner</td><td>50%</td></tr> </tbody></table> <h5 id="notes">Notes:</h5> <ol> <li>This incentivizes all bids to be revealed in time. If bids could be revealed late, an extortion attack on the current highest bidder could be made by threatening to reveal a new second highest bid.</li> <li>A bid which remains sealed after more than 2 weeks and 5 days may be cancelled by anyone to collect a small reward.</li> <li>Since names are hashed before auctioning and registration, the Initial Registrar is unable to enforce character length restrictions independently. A reward is therefore provided for reporting invalid names.</li> </ol> <h3 id="deployment-and-upgrade-process">Deployment and Upgrade process</h3> <p>The Initial Registrar requires the ENS's address as a constructor, and should be deployed after the ENS. The multisig account owning the root node in the ENS should then set the Initial Registrar's address as owner of the <code>eth</code> node.</p> <p>The Initial Registrar is expected to be replaced by a Permanent Registrar approximately 2 years after deployment. The following process should be used for the upgrade:</p> <ol> <li>The Permanent Registrar contract will be deployed.</li> <li>The multisig account owning the root node in the ENS will assign ownership of the <code>.eth</code> node to the Permanent Registrar.</li> <li>Owners of hashes in the Initial Registrar will be responsible for registering their deeds to the Permanent Registrar. A couple options are considered here: <ol> <li>Require owners to transfer their ownership prior to a cutoff date in order to maintain ownership and/or continue name resolution services.</li> <li>Have the Permanent Registrar query the Initial Registrar for ownership if it is lacking an entry.</li> </ol> </li> </ol> <h3 id="planned-deactivation">Planned deactivation</h3> <p>In order to limit dependence on the Initial Registrar, new auctions will stop after 4 years, and all ether held in deeds after 8 years will become unreachable.</p> <h3 id="registrar-interface">Registrar Interface</h3> <p><code>function state(bytes32 _hash) constant returns (Mode)</code></p> <ul> <li>Implements a state machine returning the current state of a name</li> </ul> <p><code>function entries(bytes32 _hash) constant returns (Mode, address, uint, uint, uint)</code></p> <ul> <li>Returns the following information regarding a registered name: <ul> <li>state</li> <li>deed address</li> <li>registration date</li> <li>balance of the deed</li> <li>highest value bid at auction</li> </ul> </li> </ul> <p><code>function getAllowedTime(bytes32 _hash) constant returns (uint timestamp)</code></p> <ul> <li>Returns the time at which the hash will no longer be in the initial <code>not-yet-available</code> state.</li> </ul> <p><code>function isAllowed(bytes32 _hash, uint _timestamp) constant returns (bool allowed)</code></p> <ul> <li>Takes a hash and a time, returns true if and only if it has passed the initial <code>not-yet-available</code> state.</li> </ul> <p><code>function startAuction(bytes32 _hash);</code></p> <ul> <li>Moves the state of a hash from Open to Auction. Throws if state is not Open.</li> </ul> <p><code>function startAuctions(bytes32[] _hashes);</code></p> <ul> <li>Starts multiple auctions on an array of hashes. This enables someone to open up an auction for a number of dummy hashes when they are only really interested in bidding for one. This will increase the cost for an attacker to simply bid blindly on all new auctions. Dummy auctions that are open but not bid on are closed after a week.</li> </ul> <p><code>function shaBid(bytes32 hash, address owner, uint value, bytes32 salt) constant returns (bytes32 sealedBid);</code></p> <ul> <li>Takes the parameters of a bid, and returns the sealedBid hash value required to participate in the bidding for an auction. This obfuscates the parameters in order to mimic the mechanics of placing a bid in an envelope.</li> </ul> <p><code>function newBid(bytes32 sealedBid);</code></p> <ul> <li>Bids are sent by sending a message to the main contract with a sealedBid hash and an amount of ether. The hash contains information about the bid, including the bidded name hash, the bid value, and a random salt. Bids are not tied to any one auction until they are revealed. The value of the bid itself can be masqueraded by sending more than the value of your actual bid. This is followed by a 48h reveal period. Bids revealed after this period will be burned and the ether unrecoverable. Since this is an auction, it is expected that most public hashes, like known domains and common dictionary words, will have multiple bidders pushing the price up.</li> </ul> <p><code>function startAuctionsAndBid(bytes32[] hashes, bytes32 sealedBid)</code></p> <ul> <li>A utility function allowing a call to <code>startAuctions</code> followed by <code>newBid</code> in a single transaction.</li> </ul> <p><code>function unsealBid(bytes32 _hash, address _owner, uint _value, bytes32 _salt);</code></p> <ul> <li>Once the bidding period is completed, there is a reveal period during with the properties of a bid are submitted to reveal them. The registrar hashes these properties using the <code>shaBid()</code> function above to verify that they match a pre-existing sealed bid. If the unsealedBid is the new best bid, the old best bid is returned to its bidder.</li> </ul> <p><code>function cancelBid(bytes32 seal);</code></p> <ul> <li>Cancels an unrevealed bid according to the rules described in the notes on the refund schedule above.</li> </ul> <p><code>function finalizeAuction(bytes32 _hash);</code></p> <p>After the registration date has passed, this function can be called to finalize the auction, which then calls the ENS function <code>setSubnodeOwner()</code> updating the ENS record to set the winning bidder as owner of the node.</p> <p><code>function transfer(bytes32 _hash, address newOwner);</code></p> <ul> <li>Update the owner of the ENS node corresponding to the submitted hash to a new owner. This function must be callable only by the current owner.</li> </ul> <p><code>function releaseDeed(bytes32 _hash);</code></p> <ul> <li>After some time, the owner can release the property and get their ether back.</li> </ul> <p><code>function invalidateName(string unhashedName);</code></p> <ul> <li>Since registration is done on the hash of a name, the registrar itself cannot validate names. This function can be used to report a name which is 6 characters long or less. If it has been registered, the submitter will earn 10% of the deed value. We are purposefully handicapping the simplified registrar as a way to force it into being restructured in a few years.</li> </ul> <p><code>function eraseNode(bytes32[] labels)</code></p> <ul> <li>Allows anyone to delete the owner and resolver records for a subdomain of a name that is not currently owned in the registrar. For instance, to zero <code>foo.bar.eth</code> on a registrar that owns <code>.eth</code>, pass an array containing <code>[sha3('foo'), sha3('bar')]</code>.</li> </ul> <p><code>function transferRegistrars(bytes32 _hash) onlyOwner(_hash);</code></p> <ul> <li>Used during the upgrade process to a permanent registrar. If this registrar is no longer the owner of the its root node in the ENS, this function will transfers the deed to the current owner, which should be a new registrar. This function throws if this registrar still owns its root node.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="starting-with-a-temporary-registrar">Starting with a temporary registrar</h3> <p>Anticipating and designing for all the potential issues of name allocation names is unlikely to succeed. This approach chooses not to be concerned with getting it perfect, but allows us to observe and learn with training wheels on, and implement improvements before expanding the available namespace to shorter names or another TLD.</p> <h3 id="valid-names-7-characters">Valid names &gt;= 7 characters</h3> <p>Preserving the shortest, and often most valuable, domain names for the upgraded registrar provides the opportunity to implement processes for dispute resolution (assuming they are found to be necessary).</p> <h3 id="delayed-release-of-names">Delayed release of names</h3> <p>A slower release allows for extra time to identify, and address any issues which may arise after launch.</p> <h3 id="restricting-tld-to-eth">Restricting TLD to <code>.eth</code></h3> <p>Choosing a single TLD helps to maximize network effects by focusing on one namespace.</p> <p>A three letter TLD is a pattern made familiar by it's common usage in internet domain names. This familiarity significantly increases the potential of the ENS to be integrated into pre-existing DNS systems, and reserved as a <a rel="external" href="https://www.iana.org/assignments/special-use-domain-names/special-use-domain-names.xhtml#special-use-domain">special-use domain name</a>. A recent precedent for this is the <a rel="external" href="https://tools.ietf.org/html/rfc7686">reservation of the <code>.onion</code> domain</a>.</p> <h3 id="holding-ether-as-collateral">Holding ether as collateral</h3> <p>This approach is simpler than the familiar model of requiring owners to make recurring payments to retain ownership of a domain name. It also makes the initial registrar a revenue neutral service.</p> <h2 id="prior-work">Prior work</h2> <p>This document borrows heavily from several sources:</p> <ul> <li><a href="https://wg-eips.ritovision.com/137/">EIP-137</a> outlines the initial implementation of the Registry Contract (ENS.sol) and associated Resolver contracts.</li> <li><a rel="external" href="https://github.com/ethereum/EIPs/issues/26">ERC-26</a> was the first ERC to propose a name service at the contract layer</li> <li>@alexvandesande's current implementation of the <a rel="external" href="https://github.com/ethereum/ens/blob/mainnet/contracts/HashRegistrarSimplified.sol">HashRegistrar</a></li> </ul> <h3 id="edits">Edits:</h3> <ul> <li>2016-10-26 Added link Alex's design in abstract</li> <li>2016-11-01 change 'Planned deactivation' to h3'</li> <li>2017-03-13 Update timelines for bidding and reveal periods</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-10-24T00:00:00+00:00 2026-02-11T14:49:27+00:00 Gavin Woodhttps://github.com/gavofyork https://wg-eips.ritovision.com/161/ <h3 id="hard-fork">Hard fork</h3> <p><a href="https://wg-eips.ritovision.com/607/">Spurious Dragon</a></p> <h3 id="parameters">Parameters</h3> <ul> <li><code>FORK_BLKNUM</code>: 2,675,000</li> <li><code>CHAIN_ID</code>: 1 (Mainnet)</li> </ul> <h3 id="specification">Specification</h3> <p>a. Account creation transactions and the <code>CREATE</code> operation SHALL, prior to the execution of the initialisation code, <strong>increment</strong> the <strong>nonce</strong> over and above its normal starting value by <strong>one</strong> (for normal networks, this will be simply 1, however test-nets with non-zero default starting nonces will be different).</p> <p>b. Whereas <code>CALL</code> and <code>SUICIDE</code> would charge 25,000 gas when the destination is non-existent, now the charge SHALL <strong>only</strong> be levied if the operation transfers <strong>more than zero value</strong> and the destination account is <em>dead</em>.</p> <p>c. No account may <em>change state</em> from non-existent to existent-but-<em>empty</em>. If an operation would do this, the account SHALL instead remain non-existent.</p> <p>d. <em>At the end of the transaction</em>, any account <em>touched</em> by the execution of that transaction which is now <em>empty</em> SHALL instead become non-existent (i.e. <strong>deleted</strong>).</p> <p>Where:</p> <p>An account is considered to be <em>touched</em> when it is involved in any potentially <em>state-changing</em> operation. This includes, but is not limited to, being the recipient of a <strong>transfer of zero value</strong>.</p> <p>An account is considered <em>empty</em> when it has <strong>no code</strong> and <strong>zero nonce</strong> and <strong>zero balance</strong>.</p> <p>An account is considered <em>dead</em> when either it is non-existent or it is <em>empty</em>.</p> <p><em>At the end of the transaction</em> is immediately following the execution of the suicide list, prior to the determination of the state trie root for receipt population.</p> <p>An account <em>changes state</em> when:</p> <ul> <li>it is the target or refund of a <code>SUICIDE</code> operation for <strong>zero or more</strong> value;</li> <li>it is the source or destination of a <code>CALL</code> operation or message-call transaction transferring <strong>zero or more</strong> value;</li> <li>it is the source or creation of a <code>CREATE</code> operation or contract-creation transaction endowing <strong>zero or more</strong> value;</li> <li>as the block author ("miner") it is the recipient of block-rewards or transaction-fees of <strong>zero or more</strong> value.</li> </ul> <h4 id="notes">Notes</h4> <p>In the present Ethereum protocol, it should be noted that very few state changes can ultimately result in accounts that are empty following the execution of the transaction. In fact there are only four contexts that current implementations need track:</p> <ul> <li>an empty account has zero value transferred to it through <code>CALL</code>;</li> <li>an empty account has zero value transferred to it through <code>SUICIDE</code>;</li> <li>an empty account has zero value transferred to it through a message-call transaction;</li> <li>an empty account has zero value transferred to it through a zero-gas-price fees transfer.</li> </ul> <h3 id="rationale">Rationale</h3> <p>Same as #158 except that several edge cases are avoided since we do not break invariants:</p> <ul> <li><del>that an account can go from having code and storage to not having code or storage mid-way through the execution of a transaction;</del> [corrected]</li> <li>that a newly created account cannot be deleted prior to being deployed.</li> </ul> <p><code>CREATE</code> avoids zero in the nonce to avoid any suggestion of the oddity of <code>CREATE</code>d accounts being reaped half-way through their creation.</p> <h3 id="addendum-2017-08-15">Addendum (2017-08-15)</h3> <p>On 2016-11-24, a consensus bug occurred due to two implementations having different behavior in the case of state reverts.[3] The specification was amended to clarify that empty account deletions are reverted when the state is reverted.</p> <h3 id="references">References</h3> <ol> <li>EIP-158 issue and discussion: https://github.com/ethereum/EIPs/issues/158</li> <li>EIP-161 issue and discussion: https://github.com/ethereum/EIPs/issues/161</li> <li>https://blog.ethereum.org/2016/11/25/security-alert-11242016-consensus-bug-geth-v1-4-19-v1-5-2/</li> </ol> <blockquote> <p>Details: Geth was failing to revert empty account deletions when the transaction causing the deletions of empty accounts ended with an out-of-gas exception. An additional issue was found in Parity, where the Parity client incorrectly failed to revert empty account deletions in a more limited set of contexts involving out-of-gas calls to precompiled contracts; the new Geth behavior matches Parity’s, and empty accounts will cease to be a source of concern in general in about one week once the state clearing process finishes.</p> </blockquote> 2016-10-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/160/ <h3 id="hard-fork">Hard fork</h3> <p><a href="https://wg-eips.ritovision.com/607/">Spurious Dragon</a></p> <h3 id="parameters">Parameters</h3> <ul> <li><code>FORK_BLKNUM</code>: 2,675,000</li> <li><code>CHAIN_ID</code>: 1</li> </ul> <h3 id="specification">Specification</h3> <p>If <code>block.number &gt;= FORK_BLKNUM</code>, increase the gas cost of EXP from 10 + 10 per byte in the exponent to 10 + 50 per byte in the exponent.</p> <h3 id="rationale">Rationale</h3> <p>Benchmarks suggest that EXP is currently underpriced by a factor of about 4–8.</p> <h3 id="references">References</h3> <ol> <li>EIP-160 issue and discussion: https://github.com/ethereum/EIPs/issues/160</li> </ol> 2016-10-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/158/ <h1 id="specification">Specification</h1> <p>For all blocks where <code>block.number &gt;= FORK_BLKNUM</code> (TBA):</p> <ol> <li>In all cases where a state change is made to an account, and this state change results in the account state being saved with nonce = 0, balance = 0, code empty, storage empty (hereinafter "empty account"), the account is instead deleted.</li> <li>If an address is "touched" and that address contains an empty account, then it is deleted. A "touch" is defined as any situation where if the account at the given address were nonexistent it would be created.</li> <li>Whenever the EVM checks if an account exists, emptiness is treated as equivalent to nonexistence. Particularly, note that this implies that, once this change is enabled, there is no longer a meaningful difference between emptiness and nonexistence from the point of view of EVM execution.</li> <li>Zero-value calls and zero-value suicides no longer consume the 25000 account creation gas cost in any circumstance</li> </ol> <p>The cases where a "touch" takes place can be enumerated as follows:</p> <ul> <li>Zero-value-bearing CALLs</li> <li>CREATEs (if the code that is ultimately saved is empty and there is no ether remaining in the account when it is saved)</li> <li>Zero-value-bearing SUICIDEs</li> <li>Transaction recipients</li> <li>Contracts created in contract creation transactions</li> <li>Miners receiving transaction fees (note the case where the gasprice is zero, and the account does not yet exist because it only receives the block/uncle/nephew rewards <em>after</em> processing every transaction)</li> </ul> <h3 id="specification-1b">Specification (1b)</h3> <p>When the EVM checks for emptiness (for the purpose of possibly applying the 25000 gas cost), emptiness is defined by <code>is_empty(acct): return get_balance(acct) == 0 and get_code(acct) == "" and get_nonce(acct) == 0</code>; emptiness of storage does not matter. This simplifies client implementation because there is no need to add extra complexity to make caches enumerable in the correct way and does not significantly affect the intended result, as the cases where balance/code/nonce are empty but storage is nonempty where this change would lead to an extra 25000 gas being paid are pathological and have no real use value.</p> <h3 id="specification-1c">Specification (1c)</h3> <p>Do not implement point 2 above (ie. no new empty accounts can be created, but existing ones are not automatically destroyed unless their state is actually <em>changed</em>). Instead, during each block starting from (and including) N and ending when there are no null accounts left, select the 1000 null accounts that are left-most in order of sha3(address), and delete them (ordering by hash is necessary so as to allow the accounts to be easily found by iterating the tree).</p> <h1 id="rationale">Rationale</h1> <p>This removes a large number of empty accounts that have been put in the state at very low cost due to flaws in earlier versions of the Ethereum protocol, thereby greatly reducing state size and hence both reducing the hard disk load of a full client and reducing the time for a fast sync. Additionally, it simplifies the protocol in the long term, as once all "empty" objects are cleared out there is no longer any meaningful distinction between an account being empty and being nonexistent, and indeed one can simply view nonexistence as a compact representation of emptiness.</p> <p>Note that this proposal does introduce a <strong>temporary</strong> breaking of existing guarantees, in that by repeatedly zero-value-calling already existing empty accounts one can create a state change at a cost of 700 gas per account instead of the usual 5000 per gas minimum (with SUICIDE refunds this goes down further to 350 gas per account). Allowing such a large number of state writes per block will lead to heightened block processing times and increase uncle rates in the short term while the existing empty accounts are being cleared, and eventually once all empty accounts are cleared this issue will no longer exist.</p> <h1 id="references">References</h1> <ol> <li>EIP-158 issue and discussion: https://github.com/ethereum/EIPs/issues/158</li> <li>EIP-161 issue and discussion: https://github.com/ethereum/EIPs/issues/161</li> </ol> 2016-10-14T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/155/ <h3 id="hard-fork">Hard fork</h3> <p><a href="https://wg-eips.ritovision.com/607/">Spurious Dragon</a></p> <h3 id="parameters">Parameters</h3> <ul> <li><code>FORK_BLKNUM</code>: 2,675,000</li> <li><code>CHAIN_ID</code>: 1 (main net)</li> </ul> <h3 id="specification">Specification</h3> <p>If <code>block.number &gt;= FORK_BLKNUM</code> and <code>CHAIN_ID</code> is available, then when computing the hash of a transaction for the purposes of signing, instead of hashing only six rlp encoded elements <code>(nonce, gasprice, startgas, to, value, data)</code>, you <strong>SHOULD</strong> hash nine rlp encoded elements <code>(nonce, gasprice, startgas, to, value, data, chainid, 0, 0)</code>. If you do, then the <code>v</code> of the signature <strong>MUST</strong> be set to <code>{0,1} + CHAIN_ID * 2 + 35</code> where <code>{0,1}</code> is the parity of the <code>y</code> value of the curve point for which <code>r</code> is the x-value in the secp256k1 signing process. If you choose to only hash 6 values, then <code>v</code> continues to be set to <code>{0,1} + 27</code> as previously.</p> <p>If <code>block.number &gt;= FORK_BLKNUM</code> and <code>v = CHAIN_ID * 2 + 35</code> or <code>v = CHAIN_ID * 2 + 36</code>, then when computing the hash of a transaction for purposes of recovering, instead of hashing six rlp encoded elements <code>(nonce, gasprice, startgas, to, value, data)</code>, hash nine rlp encoded elements <code>(nonce, gasprice, startgas, to, value, data, chainid, 0, 0)</code>. The currently existing signature scheme using <code>v = 27</code> and <code>v = 28</code> remains valid and continues to operate under the same rules as it did previously.</p> <h3 id="example">Example</h3> <p>Consider a transaction with <code>nonce = 9</code>, <code>gasprice = 20 * 10**9</code>, <code>startgas = 21000</code>, <code>to = 0x3535353535353535353535353535353535353535</code>, <code>value = 10**18</code>, <code>data=''</code> (empty).</p> <p>The "signing data" becomes:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0xec098504a817c800825208943535353535353535353535353535353535353535880de0b6b3a764000080018080</span></span></code></pre> <p>The "signing hash" becomes:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0xdaf5a779ae972f972197303d7b574746c7ef83eadac0f2791ad23db92e4c8e53</span></span></code></pre> <p>If the transaction is signed with the private key <code>0x4646464646464646464646464646464646464646464646464646464646464646</code>, then the v,r,s values become:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(37, 18515461264373351373200002665853028612451056578545711640558177340181847433846, 46948507304638947509940763649030358759909902576025900602547168820602576006531)</span></span></code></pre> <p>Notice the use of 37 instead of 27. The signed tx would become:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0xf86c098504a817c800825208943535353535353535353535353535353535353535880de0b6b3a76400008025a028ef61340bd939bc2195fe537567866003e1a15d3c71ff63e1590620aa636276a067cbe9d8997f761aecb703304b3800ccf555c9f3dc64214b297fb1966a3b6d83</span></span></code></pre><h3 id="rationale">Rationale</h3> <p>This would provide a way to send transactions that work on Ethereum without working on ETC or the Morden testnet. ETC is encouraged to adopt this EIP but replacing <code>CHAIN_ID</code> with a different value, and all future testnets, consortium chains and alt-etherea are encouraged to adopt this EIP replacing <code>CHAIN_ID</code> with a unique value.</p> <h3 id="list-of-chain-id-s">List of Chain ID's:</h3> <table><thead><tr><th><code>CHAIN_ID</code></th><th>Chain(s)</th></tr></thead><tbody> <tr><td>1</td><td>Ethereum mainnet</td></tr> <tr><td>2</td><td>Morden (disused), Expanse mainnet</td></tr> <tr><td>3</td><td>Ropsten</td></tr> <tr><td>4</td><td>Rinkeby</td></tr> <tr><td>5</td><td>Goerli</td></tr> <tr><td>42</td><td>Kovan</td></tr> <tr><td>1337</td><td>Geth private chains (default)</td></tr> </tbody></table> <p>Find more chain ID's on <a rel="external" href="https://chainid.network">chainid.network</a> and contribute to <a rel="external" href="https://github.com/ethereum-lists/chains">ethereum-lists/chains</a>.</p> 2016-10-04T00:00:00+00:00 2026-02-11T14:49:27+00:00 Tjaden Hesstah83@cornell.edu Matt Luongohttps://github.com/mhluongo Piotr Dyragahttps://github.com/pdyraga James Hancockhttps://github.com/MadeOfTin https://wg-eips.ritovision.com/152/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP will enable the BLAKE2b hash function and other higher-round 64-bit BLAKE2 variants to run cheaply on the EVM, allowing easier interoperability between Ethereum and Zcash as well as other Equihash-based PoW coins.</p> <h2 id="abstract">Abstract</h2> <p>This EIP introduces a new precompiled contract which implements the compression function <code>F</code> used in the BLAKE2 cryptographic hashing algorithm, for the purpose of allowing interoperability between the EVM and Zcash, as well as introducing more flexible cryptographic hash primitives to the EVM.</p> <h2 id="motivation">Motivation</h2> <p>Besides being a useful cryptographic hash function and SHA3 finalist, BLAKE2 allows for efficient verification of the Equihash PoW used in Zcash, making a BTC Relay - style SPV client possible on Ethereum. A single verification of an Equihash PoW verification requires 512 iterations of the hash function, making verification of Zcash block headers prohibitively expensive if a Solidity implementation of BLAKE2 is used.</p> <p>BLAKE2b, the common 64-bit BLAKE2 variant, is highly optimized and faster than MD5 on modern processors.</p> <p>Interoperability with Zcash could enable contracts like trustless atomic swaps between the chains, which could provide a much needed aspect of privacy to the very public Ethereum blockchain.</p> <h2 id="specification">Specification</h2> <p>We propose adding a precompiled contract at address <code>0x09</code> wrapping the <a rel="external" href="https://tools.ietf.org/html/rfc7693#section-3.2">BLAKE2 <code>F</code> compression function</a>.</p> <p>The precompile requires 6 inputs tightly encoded, taking exactly 213 bytes, as explained below. The encoded inputs are corresponding to the ones specified in the <a rel="external" href="https://tools.ietf.org/html/rfc7693#section-3.2">BLAKE2 RFC Section 3.2</a>:</p> <ul> <li><code>rounds</code> - the number of rounds - 32-bit unsigned big-endian word</li> <li><code>h</code> - the state vector - 8 unsigned 64-bit little-endian words</li> <li><code>m</code> - the message block vector - 16 unsigned 64-bit little-endian words</li> <li><code>t_0, t_1</code> - offset counters - 2 unsigned 64-bit little-endian words</li> <li><code>f</code> - the final block indicator flag - 8-bit word</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[4 bytes for rounds][64 bytes for h][128 bytes for m][8 bytes for t_0][8 bytes for t_1][1 byte for f]</span></span></code></pre> <p>The boolean <code>f</code> parameter is considered as <code>true</code> if set to <code>1</code>. The boolean <code>f</code> parameter is considered as <code>false</code> if set to <code>0</code>. All other values yield an invalid encoding of <code>f</code> error.</p> <p>The precompile should compute the <code>F</code> function as <a rel="external" href="https://tools.ietf.org/html/rfc7693#section-3.2">specified in the RFC</a> and return the updated state vector <code>h</code> with unchanged encoding (little-endian).</p> <h3 id="example-usage-in-solidity">Example Usage in Solidity</h3> <p>The precompile can be wrapped easily in Solidity to provide a more development-friendly interface to <code>F</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"> F</span><span>(</span><span class="z-support">uint32</span><span class="z-variable"> rounds</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"> h</span><span>,</span><span class="z-support"> bytes32</span><span>[</span><span class="z-variable">4</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> m</span><span>,</span><span class="z-support"> bytes8</span><span>[</span><span class="z-variable">2</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> t</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> f</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 class="z-variable">2</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-storage z-type"> memory</span><span> output</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> args </span><span class="z-keyword">=</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>rounds</span><span>,</span><span> h</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span> h</span><span>[</span><span class="z-constant">1</span><span>]</span><span>,</span><span> m</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span> m</span><span>[</span><span class="z-constant">1</span><span>]</span><span>,</span><span> m</span><span>[</span><span class="z-constant">2</span><span>]</span><span>,</span><span> m</span><span>[</span><span class="z-constant">3</span><span>]</span><span>,</span><span> t</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span> t</span><span>[</span><span class="z-constant">1</span><span>]</span><span>,</span><span> f</span><span>)</span><span>;</span></span> <span class="giallo-l"></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-entity z-name">not</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-constant"> 0x09</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>args</span><span>,</span><span class="z-constant"> 32</span><span>)</span><span>,</span><span class="z-constant"> 0xd5</span><span>,</span><span> output</span><span>,</span><span class="z-constant"> 0x40</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 class="giallo-l"><span class="z-keyword"> return</span><span> output</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"> callF</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 class="z-variable">2</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint32</span><span> rounds </span><span class="z-keyword">=</span><span class="z-constant"> 12</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-storage z-type"> memory</span><span> h</span><span>;</span></span> <span class="giallo-l"><span> h</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> =</span><span> hex</span><span class="z-string">&quot;48c9bdf267e6096a3ba7ca8485ae67bb2bf894fe72f36e3cf1361d5f3af54fa5&quot;</span><span>;</span></span> <span class="giallo-l"><span> h</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> =</span><span> hex</span><span class="z-string">&quot;d182e6ad7f520e511f6c3e2b8c68059b6bbd41fbabd9831f79217e1319cde05b&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span class="z-constant">4</span><span>]</span><span class="z-storage z-type"> memory</span><span> m</span><span>;</span></span> <span class="giallo-l"><span> m</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> =</span><span> hex</span><span class="z-string">&quot;6162630000000000000000000000000000000000000000000000000000000000&quot;</span><span>;</span></span> <span class="giallo-l"><span> m</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> =</span><span> hex</span><span class="z-string">&quot;0000000000000000000000000000000000000000000000000000000000000000&quot;</span><span>;</span></span> <span class="giallo-l"><span> m</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-keyword"> =</span><span> hex</span><span class="z-string">&quot;0000000000000000000000000000000000000000000000000000000000000000&quot;</span><span>;</span></span> <span class="giallo-l"><span> m</span><span>[</span><span class="z-constant">3</span><span>]</span><span class="z-keyword"> =</span><span> hex</span><span class="z-string">&quot;0000000000000000000000000000000000000000000000000000000000000000&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes8</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-storage z-type"> memory</span><span> t</span><span>;</span></span> <span class="giallo-l"><span> t</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> =</span><span> hex</span><span class="z-string">&quot;0300000000000000&quot;</span><span>;</span></span> <span class="giallo-l"><span> t</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> =</span><span> hex</span><span class="z-string">&quot;0000000000000000&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bool</span><span> f </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"> Expected output:</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ba80a53f981c4d0d6a2797b69f12f6e94c212f14685ac4b74b12bb6fdbffa2d1</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 7d87c5392aab792dc252d5de4533cc9518d38aa8dbf1925ab92386edd4009923</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> F</span><span>(</span><span>rounds</span><span>,</span><span> h</span><span>,</span><span> m</span><span>,</span><span> t</span><span>,</span><span> f</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="gas-costs-and-benchmarks">Gas costs and benchmarks</h3> <p>Each operation will cost <code>GFROUND * rounds</code> gas, where <code>GFROUND = 1</code>. Detailed benchmarks are presented in the benchmarks appendix section.</p> <h2 id="rationale">Rationale</h2> <p>BLAKE2 is an excellent candidate for precompilation. BLAKE2 is heavily optimized for modern 64-bit CPUs, specifically utilizing 24 and 63-bit rotations to allow parallelism through SIMD instructions and little-endian arithmetic. These characteristics provide exceptional speed on native CPUs: 3.08 cycles per byte, or 1 gibibyte per second on an Intel i5.</p> <p>In contrast, the big-endian 32 byte semantics of the EVM are not conducive to efficient implementation of BLAKE2, and thus the gas cost associated with computing the hash on the EVM is disproportionate to the true cost of computing the function natively.</p> <p>An obvious implementation would be a direct BLAKE2b hash function precompile. At first glance, a BLAKE2b precompile satisfies most hashing and interoperability requirements on the EVM. Once we started digging in, however, it became clear that any BLAKE2b implementation would need specific features and internal modifications based on different projects' requirements and libraries.</p> <p>A <a rel="external" href="https://github.com/ethereum/EIPs/issues/152#issuecomment-499240310">thread with the Zcash team</a> makes the issue clear.</p> <blockquote> <p>The minimal thing that is necessary for a working ZEC-ETH relay is an implementation of BLAKE2b Compression F in a precompile.</p> </blockquote> <blockquote> <p>A BLAKE2b Compression Function F precompile would also suffice for the Filecoin and Handshake interop goals.</p> </blockquote> <blockquote> <p>A full BLAKE2b precompile would suffice for a ZEC-ETH relay, provided that the implementation provided the parts of the BLAKE2 API that we need (personalization, maybe something else—I'm not sure).</p> </blockquote> <blockquote> <p>I'm not 100% certain if a full BLAKE2b precompile would also suffice for the Filecoin and Handshake goals. It almost certainly could, provided that it supports all the API that they need.</p> </blockquote> <blockquote> <p>BLAKE2s — whether the Compression Function F or the full hash — is only a nice-to-have for the purposes of a ZEC-ETH relay.</p> </blockquote> <p>From this and other conversations with teams in the space, we believe we should focus first on the <code>F</code> precompile as a strictly necessary piece for interoperability projects. A BLAKE2b precompile is a nice-to-have, and we support any efforts to add one-- but it's unclear whether complete requirements and a flexible API can be found in time for Istanbul.</p> <p>Implementation of only the core F compression function also allows substantial flexibility and extensibility while keeping changes at the protocol level to a minimum. This will allow functions like tree hashing, incremental hashing, and keyed, salted, and personalized hashing as well as variable length digests, none of which are currently available on the EVM.</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>0x09</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> <h4 id="test-vector-0">Test vector 0</h4> <ul> <li>input: (empty)</li> <li>output: error "input length for BLAKE2 F precompile should be exactly 213 bytes"</li> </ul> <h4 id="test-vector-1">Test vector 1</h4> <ul> <li>input: <code>00000c48c9bdf267e6096a3ba7ca8485ae67bb2bf894fe72f36e3cf1361d5f3af54fa5d182e6ad7f520e511f6c3e2b8c68059b6bbd41fbabd9831f79217e1319cde05b61626300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000001</code></li> <li>output: error "input length for BLAKE2 F precompile should be exactly 213 bytes"</li> </ul> <h4 id="test-vector-2">Test vector 2</h4> <ul> <li>input: <code>000000000c48c9bdf267e6096a3ba7ca8485ae67bb2bf894fe72f36e3cf1361d5f3af54fa5d182e6ad7f520e511f6c3e2b8c68059b6bbd41fbabd9831f79217e1319cde05b61626300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000001</code></li> <li>output: error "input length for BLAKE2 F precompile should be exactly 213 bytes"</li> </ul> <h4 id="test-vector-3">Test vector 3</h4> <ul> <li>input: <code>0000000c48c9bdf267e6096a3ba7ca8485ae67bb2bf894fe72f36e3cf1361d5f3af54fa5d182e6ad7f520e511f6c3e2b8c68059b6bbd41fbabd9831f79217e1319cde05b61626300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000002</code></li> <li>output: error "incorrect final block indicator flag"</li> </ul> <h4 id="test-vector-4">Test vector 4</h4> <ul> <li>input: <code>0000000048c9bdf267e6096a3ba7ca8485ae67bb2bf894fe72f36e3cf1361d5f3af54fa5d182e6ad7f520e511f6c3e2b8c68059b6bbd41fbabd9831f79217e1319cde05b61626300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000001</code></li> <li>output: <code>08c9bcf367e6096a3ba7ca8485ae67bb2bf894fe72f36e3cf1361d5f3af54fa5d282e6ad7f520e511f6c3e2b8c68059b9442be0454267ce079217e1319cde05b</code></li> </ul> <h4 id="test-vector-5">Test vector 5</h4> <ul> <li>input: <code>0000000c48c9bdf267e6096a3ba7ca8485ae67bb2bf894fe72f36e3cf1361d5f3af54fa5d182e6ad7f520e511f6c3e2b8c68059b6bbd41fbabd9831f79217e1319cde05b61626300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000001</code></li> <li>output: <code>ba80a53f981c4d0d6a2797b69f12f6e94c212f14685ac4b74b12bb6fdbffa2d17d87c5392aab792dc252d5de4533cc9518d38aa8dbf1925ab92386edd4009923</code></li> </ul> <h4 id="test-vector-6">Test vector 6</h4> <ul> <li>input: <code>0000000c48c9bdf267e6096a3ba7ca8485ae67bb2bf894fe72f36e3cf1361d5f3af54fa5d182e6ad7f520e511f6c3e2b8c68059b6bbd41fbabd9831f79217e1319cde05b61626300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000000</code></li> <li>output: <code>75ab69d3190a562c51aef8d88f1c2775876944407270c42c9844252c26d2875298743e7f6d5ea2f2d3e8d226039cd31b4e426ac4f2d3d666a610c2116fde4735</code></li> </ul> <h4 id="test-vector-7">Test vector 7</h4> <ul> <li>input: <code>0000000148c9bdf267e6096a3ba7ca8485ae67bb2bf894fe72f36e3cf1361d5f3af54fa5d182e6ad7f520e511f6c3e2b8c68059b6bbd41fbabd9831f79217e1319cde05b61626300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000001</code></li> <li>output: <code>b63a380cb2897d521994a85234ee2c181b5f844d2c624c002677e9703449d2fba551b3a8333bcdf5f2f7e08993d53923de3d64fcc68c034e717b9293fed7a421</code></li> </ul> <h4 id="test-vector-8">Test vector 8</h4> <ul> <li>input: <code>ffffffff48c9bdf267e6096a3ba7ca8485ae67bb2bf894fe72f36e3cf1361d5f3af54fa5d182e6ad7f520e511f6c3e2b8c68059b6bbd41fbabd9831f79217e1319cde05b61626300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000300000000000000000000000000000001</code></li> <li>output: <code>fc59093aafa9ab43daae0e914c57635c5402d8e3d2130eb9b3cc181de7f0ecf9b22bf99a7815ce16419e200e01846e6b5df8cc7703041bbceb571de6631d2615</code></li> </ul> <h2 id="implementation">Implementation</h2> <p>An initial implementation of the <code>F</code> function in Go, adapted from the standard library, can be found in our <a rel="external" href="https://github.com/keep-network/blake2-f">Golang BLAKE2 library fork</a>. There's also an implementation of the precompile in our fork of <a rel="external" href="https://github.com/keep-network/go-ethereum/pull/4">go-ethereum</a>.</p> <h2 id="references">References</h2> <p>For reference, further discussion on this EIP also occurred in the following PRs and issues</p> <ul> <li><a rel="external" href="https://github.com/ethereum/EIPs/issues/152">Original Issue</a></li> <li><a rel="external" href="https://ethereum-magicians.org/t/blake2b-f-precompile/3157">Ethereum Magicians</a></li> <li><a rel="external" href="https://github.com/ethereum/EIPs/pull/2129">PR 2129</a></li> </ul> <h2 id="appendix-benchmarks">Appendix - benchmarks</h2> <p>Assuming ecRecover precompile is perfectly priced, we executed a set of benchmarks comparing Blake2b F compression function precompile with ecRecover precompile. For benchmarks, we used 3.1 GHz Intel Core i7 64-bit machine.</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"> sysctl</span><span class="z-constant"> -</span><span class="z-constant">n</span><span class="z-string"> machdep.cpu.brand_string</span></span> <span class="giallo-l"><span class="z-entity z-name">Intel(R</span><span>) Core(</span><span class="z-entity z-name">TM</span><span>) i7-7920HQ CPU @ 3.10GHz</span></span></code></pre><h3 id="12-rounds">12 rounds</h3> <p>An average gas price of F precompile call with 12 rounds compared to ecRecover should have been <code>6.74153</code> and it gives <code>0.5618</code> gas per round.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Name Gascost Time (ns) MGas/S Gasprice for 10MGas/S Gasprice for ECDSA eq</span></span> <span class="giallo-l"><span>----------------------------------------- --------- ---------------- --------- ----------------------- -----------------------</span></span> <span class="giallo-l"><span>PrecompiledEcrecover/ 3000 152636 19.6546 1526.36 3000</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_0 12 338 35.503 3.38 6.64326</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_3 12 336 35.7143 3.36 6.60395</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_70 12 362 33.1492 3.62 7.11497</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_140 12 339 35.3982 3.39 6.66291</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_230 12 339 35.3982 3.39 6.66291</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_300 12 343 34.9854 3.43 6.74153</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_370 12 336 35.7143 3.36 6.60395</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_440 12 337 35.6083 3.37 6.6236</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_510 12 345 34.7826 3.45 6.78084</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_580 12 355 33.8028 3.55 6.97738</span></span></code></pre> <p>Columns</p> <ul> <li><code>MGas/S</code> - Shows what MGas per second was measured on that machine at that time</li> <li><code>Gasprice for 10MGas/S</code> shows what the gasprice should have been, in order to reach 10 MGas/second</li> <li><code>Gasprice for ECDSA eq</code> shows what the gasprice should have been, in order to have the same cost/cycle as ecRecover</li> </ul> <h3 id="1200-rounds">1200 rounds</h3> <p>An average gas price of F precompile call with 1200 rounds compared to ecRecover should have been <code>436.1288</code> and it gives <code>0.3634</code> gas per round.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Name Gascost Time (ns) MGas/S Gasprice for 10MGas/S Gasprice for ECDSA eq</span></span> <span class="giallo-l"><span>----------------------------------------- --------- ---------------- --------- ----------------------- -----------------------</span></span> <span class="giallo-l"><span>PrecompiledEcrecover/ 3000 156152 19.212 1561.52 3000</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_0 1200 22642 52.9989 226.42 434.999</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_3 1200 22885 52.4361 228.85 439.668</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_70 1200 22737 52.7774 227.37 436.824</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_140 1200 22602 53.0926 226.02 434.231</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_230 1200 22501 53.331 225.01 432.29</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_300 1200 22435 53.4879 224.35 431.022</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_370 1200 22901 52.3995 229.01 439.975</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_440 1200 23134 51.8717 231.34 444.452</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_510 1200 22608 53.0786 226.08 434.346</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_580 1200 22563 53.1844 225.63 433.481</span></span></code></pre><h3 id="1-round">1 round</h3> <p>An average gas price of F precompile call with 1 round compared to ecRecover should have been <code>2.431701</code>. However, in this scenario the call cost would totally overshadow the dynamic cost anyway.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Name Gascost Time (ns) MGas/S Gasprice for 10MGas/S Gasprice for ECDSA eq</span></span> <span class="giallo-l"><span>----------------------------------------- --------- ---------------- ---------- ----------------------- -----------------------</span></span> <span class="giallo-l"><span>PrecompiledEcrecover/ 3000 157544 19.0423 1575.44 3000</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_0 1 126 7.93651 1.26 2.39933</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_3 1 127 7.87402 1.27 2.41837</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_70 1 128 7.8125 1.28 2.43741</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_140 1 125 8 1.25 2.38029</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_230 1 128 7.8125 1.28 2.43741</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_300 1 127 7.87402 1.27 2.41837</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_370 1 131 7.63359 1.31 2.49454</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_440 1 129 7.75194 1.29 2.45646</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_510 1 125 8 1.25 2.38029</span></span> <span class="giallo-l"><span>PrecompiledBlake2F/testVectors2bX_580 1 131 7.63359 1.31 2.49454</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> 2016-09-24T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/150/ <h3 id="meta-reference">Meta reference</h3> <p><a href="https://wg-eips.ritovision.com/608/">Tangerine Whistle</a>.</p> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>FORK_BLKNUM</th><th>CHAIN_ID</th><th>CHAIN_NAME</th></tr></thead><tbody> <tr><td>2,463,000</td><td>1</td><td>Main net</td></tr> </tbody></table> <h3 id="specification">Specification</h3> <p>If <code>block.number &gt;= FORK_BLKNUM</code>, then:</p> <ul> <li>Increase the gas cost of EXTCODESIZE to 700 (from 20).</li> <li>Increase the base gas cost of EXTCODECOPY to 700 (from 20).</li> <li>Increase the gas cost of BALANCE to 400 (from 20).</li> <li>Increase the gas cost of SLOAD to 200 (from 50).</li> <li>Increase the gas cost of CALL, DELEGATECALL, CALLCODE to 700 (from 40).</li> <li>Increase the gas cost of SELFDESTRUCT to 5000 (from 0).</li> <li>If SELFDESTRUCT hits a newly created account, it triggers an additional gas cost of 25000 (similar to CALLs).</li> <li>Increase the recommended gas limit target to 5.5 million.</li> <li>Define "all but one 64th" of <code>N</code> as <code>N - floor(N / 64)</code>.</li> <li>If a call asks for more gas than the maximum allowed amount (i.e. the total amount of gas remaining in the parent after subtracting the gas cost of the call and memory expansion), do not return an OOG error; instead, if a call asks for more gas than all but one 64th of the maximum allowed amount, call with all but one 64th of the maximum allowed amount of gas (this is equivalent to a version of EIP-90^{<a rel="external" href="https://github.com/ethereum/EIPs/issues/90">1</a>} plus EIP-114^{<a rel="external" href="https://github.com/ethereum/EIPs/issues/114">2</a>}). CREATE only provides all but one 64th of the parent gas to the child call.</li> </ul> <p>That is, substitute:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> extra_gas = (not ext.account_exists(to)) * opcodes.GCALLNEWACCOUNT + \</span></span> <span class="giallo-l"><span> (value &gt; 0) * opcodes.GCALLVALUETRANSFER</span></span> <span class="giallo-l"><span> if compustate.gas &lt; gas + extra_gas:</span></span> <span class="giallo-l"><span> return vm_exception(&#39;OUT OF GAS&#39;, needed=gas+extra_gas)</span></span> <span class="giallo-l"><span> submsg_gas = gas + opcodes.GSTIPEND * (value &gt; 0)</span></span></code></pre> <p>With:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> def max_call_gas(gas):</span></span> <span class="giallo-l"><span> return gas - (gas // 64)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> extra_gas = (not ext.account_exists(to)) * opcodes.GCALLNEWACCOUNT + \</span></span> <span class="giallo-l"><span> (value &gt; 0) * opcodes.GCALLVALUETRANSFER</span></span> <span class="giallo-l"><span> if compustate.gas &lt; extra_gas:</span></span> <span class="giallo-l"><span> return vm_exception(&#39;OUT OF GAS&#39;, needed=extra_gas)</span></span> <span class="giallo-l"><span> if compustate.gas &lt; gas + extra_gas:</span></span> <span class="giallo-l"><span> gas = min(gas, max_call_gas(compustate.gas - extra_gas))</span></span> <span class="giallo-l"><span> submsg_gas = gas + opcodes.GSTIPEND * (value &gt; 0)</span></span></code></pre><h3 id="rationale">Rationale</h3> <p>Recent denial-of-service attacks have shown that opcodes that read the state tree are under-priced relative to other opcodes. There are software changes that have been made, are being made and can be made in order to mitigate the situation; however, the fact will remain that such opcodes will be by a substantial margin the easiest known mechanism to degrade network performance via transaction spam. The concern arises because it takes a long time to read from disk, and is additionally a risk to future sharding proposals as the "attack transactions" that have so far been most successful in degrading network performance would also require tens of megabytes to provide Merkle proofs for. This EIP increases the cost of storage reading opcodes to address this concern. The costs have been derived from an updated version of the calculation table used to generate the 1.0 gas costs: https://docs.google.com/spreadsheets/d/15wghZr-Z6sRSMdmRmhls9dVXTOpxKy8Y64oy9MvDZEQ/edit#gid=0; the rules attempt to target a limit of 8 MB of data that needs to be read in order to process a block, and include an estimate of 500 bytes for a Merkle proof for SLOAD and 1000 for an account.</p> <p>This EIP aims to be simple, and adds a flat penalty of 300 gas on top of the costs calculated in this table to account for the cost of loading the code (~17–21 kb in the worst case).</p> <p>The EIP 90 gas mechanic is introduced because without it, all current contracts that make calls would stop working as they use an expression like <code>msg.gas - 40</code> to determine how much gas to make a call with, relying on the gas cost of calls being 40. Additionally, EIP 114 is introduced because, given that we are making the cost of a call higher and less predictable, we have an opportunity to do it at no extra cost to currently available guarantees, and so we also achieve the benefit of replacing the call stack depth limit with a "softer" gas-based restriction, thereby eliminating call stack depth attacks as a class of attack that contract developers have to worry about and hence increasing contract programming safety. Note that with the given parameters, the de-facto maximum call stack depth is limited to ~340 (down from ~1024), mitigating the harm caused by any further potential quadratic-complexity DoS attacks that rely on calls.</p> <p>The gas limit increase is recommended so as to preserve the de-facto transactions-per-second processing capability of the system for average contracts.</p> <h2 id="references">References</h2> <ol> <li>EIP-90, https://github.com/ethereum/EIPs/issues/90</li> <li>EIP-114, https://github.com/ethereum/EIPs/issues/114</li> </ol> 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> 2016-04-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/100/ <h3 id="specification">Specification</h3> <p>Currently, the formula to compute the difficulty of a block includes the following logic:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>adj_factor</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span class="z-constant">1</span><span class="z-keyword"> -</span><span> (</span><span>(</span><span>timestamp</span><span class="z-keyword"> -</span><span> parent</span><span>.</span><span>timestamp</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> 10</span><span>)</span><span>,</span><span class="z-keyword"> -</span><span class="z-constant">99</span><span>)</span></span> <span class="giallo-l"><span>child_diff</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>(</span><span class="z-support">max</span><span>(</span><span>parent</span><span>.</span><span>difficulty</span><span class="z-keyword"> +</span><span> (</span><span>parent</span><span>.</span><span>difficulty</span><span class="z-keyword"> //</span><span class="z-constant"> BLOCK_DIFF_FACTOR</span><span>)</span><span class="z-keyword"> *</span><span> adj_factor</span><span>,</span><span class="z-support"> min</span><span>(</span><span>parent</span><span>.</span><span>difficulty</span><span>,</span><span class="z-constant"> MIN_DIFF</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-constant">...</span></span></code></pre> <p>If <code>block.number &gt;= BYZANTIUM_FORK_BLKNUM</code>, we change the first line to the following:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>adj_factor</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span>(</span><span class="z-constant">2</span><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>parent</span><span>.</span><span>uncles</span><span>)</span><span class="z-keyword"> else</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> -</span><span> (</span><span>(</span><span>timestamp</span><span class="z-keyword"> -</span><span> parent</span><span>.</span><span>timestamp</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> 9</span><span>)</span><span>,</span><span class="z-keyword"> -</span><span class="z-constant">99</span><span>)</span></span></code></pre><h3 id="rationale">Rationale</h3> <p>This new formula ensures that the difficulty adjustment algorithm targets a constant average rate of blocks produced including uncles, and so ensures a highly predictable issuance rate that cannot be manipulated upward by manipulating the uncle rate. A formula that accounts for the exact number of included uncles:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>adj_factor</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span class="z-constant">1</span><span class="z-keyword"> +</span><span class="z-support"> len</span><span>(</span><span>parent</span><span>.</span><span>uncles</span><span>)</span><span class="z-keyword"> -</span><span> (</span><span>(</span><span>timestamp</span><span class="z-keyword"> -</span><span> parent</span><span>.</span><span>timestamp</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> 9</span><span>)</span><span>,</span><span class="z-keyword"> -</span><span class="z-constant">99</span><span>)</span></span></code></pre> <p>can be fairly easily seen to be (to within a tolerance of ~3/4194304) mathematically equivalent to assuming that a block with <code>k</code> uncles is equivalent to a sequence of <code>k+1</code> blocks that all appear with the exact same timestamp, and this is likely the simplest possible way to accomplish the desired effect. But since the exact formula depends on the full block and not just the header, we are instead using an approximate formula that accomplishes almost the same effect but has the benefit that it depends only on the block header (as you can check the uncle hash against the blank hash).</p> <p>Changing the denominator from 10 to 9 ensures that the block time remains roughly the same (in fact, it should decrease by ~3% given the current uncle rate of 7%).</p> <h3 id="references">References</h3> <ol> <li>EIP 100 issue and discussion: https://github.com/ethereum/EIPs/issues/100</li> <li>https://bitslog.wordpress.com/2016/04/28/uncle-mining-an-ethereum-consensus-protocol-flaw/</li> </ol> 2016-04-04T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Johnsonarachnid@notdot.net https://wg-eips.ritovision.com/137/ <h1 id="abstract">Abstract</h1> <p>This draft EIP describes the details of the Ethereum Name Service, a proposed protocol and ABI definition that provides flexible resolution of short, human-readable names to service and resource identifiers. This permits users and developers to refer to human-readable and easy to remember names, and permits those names to be updated as necessary when the underlying resource (contract, content-addressed data, etc) changes.</p> <p>The goal of domain names is to provide stable, human-readable identifiers that can be used to specify network resources. In this way, users can enter a memorable string, such as 'vitalik.wallet' or 'www.mysite.swarm', and be directed to the appropriate resource. The mapping between names and resources may change over time, so a user may change wallets, a website may change hosts, or a swarm document may be updated to a new version, without the domain name changing. Further, a domain need not specify a single resource; different record types allow the same domain to reference different resources. For instance, a browser may resolve 'mysite.swarm' to the IP address of its server by fetching its A (address) record, while a mail client may resolve the same address to a mail server by fetching its MX (mail exchanger) record.</p> <h1 id="motivation">Motivation</h1> <p>Existing <a rel="external" href="https://github.com/ethereum/wiki/wiki/Registrar-ABI">specifications</a> and <a rel="external" href="https://ethereum.gitbooks.io/frontier-guide/content/registrar_services.html">implementations</a> for name resolution in Ethereum provide basic functionality, but suffer several shortcomings that will significantly limit their long-term usefulness:</p> <ul> <li>A single global namespace for all names with a single 'centralised' resolver.</li> <li>Limited or no support for delegation and sub-names/sub-domains.</li> <li>Only one record type, and no support for associating multiple copies of a record with a domain.</li> <li>Due to a single global implementation, no support for multiple different name allocation systems.</li> <li>Conflation of responsibilities: Name resolution, registration, and whois information.</li> </ul> <p>Use-cases that these features would permit include:</p> <ul> <li>Support for subnames/sub-domains - eg, live.mysite.tld and forum.mysite.tld.</li> <li>Multiple services under a single name, such as a DApp hosted in Swarm, a Whisper address, and a mail server.</li> <li>Support for DNS record types, allowing blockchain hosting of 'legacy' names. This would permit an Ethereum client such as Mist to resolve the address of a traditional website, or the mail server for an email address, from a blockchain name.</li> <li>DNS gateways, exposing ENS domains via the Domain Name Service, providing easier means for legacy clients to resolve and connect to blockchain services.</li> </ul> <p>The first two use-cases, in particular, can be observed everywhere on the present-day internet under DNS, and we believe them to be fundamental features of a name service that will continue to be useful as the Ethereum platform develops and matures.</p> <p>The normative parts of this document does not specify an implementation of the proposed system; its purpose is to document a protocol that different resolver implementations can adhere to in order to facilitate consistent name resolution. An appendix provides sample implementations of resolver contracts and libraries, which should be treated as illustrative examples only.</p> <p>Likewise, this document does not attempt to specify how domains should be registered or updated, or how systems can find the owner responsible for a given domain. Registration is the responsibility of registrars, and is a governance matter that will necessarily vary between top-level domains.</p> <p>Updating of domain records can also be handled separately from resolution. Some systems, such as swarm, may require a well defined interface for updating domains, in which event we anticipate the development of a standard for this.</p> <h1 id="specification">Specification</h1> <h2 id="overview">Overview</h2> <p>The ENS system comprises three main parts:</p> <ul> <li>The ENS registry</li> <li>Resolvers</li> <li>Registrars</li> </ul> <p>The registry is a single contract that provides a mapping from any registered name to the resolver responsible for it, and permits the owner of a name to set the resolver address, and to create subdomains, potentially with different owners to the parent domain.</p> <p>Resolvers are responsible for performing resource lookups for a name - for instance, returning a contract address, a content hash, or IP address(es) as appropriate. The resolver specification, defined here and extended in other EIPs, defines what methods a resolver may implement to support resolving different types of records.</p> <p>Registrars are responsible for allocating domain names to users of the system, and are the only entities capable of updating the ENS; the owner of a node in the ENS registry is its registrar. Registrars may be contracts or externally owned accounts, though it is expected that the root and top-level registrars, at a minimum, will be implemented as contracts.</p> <p>Resolving a name in ENS is a two-step process. First, the ENS registry is called with the name to resolve, after hashing it using the procedure described below. If the record exists, the registry returns the address of its resolver. Then, the resolver is called, using the method appropriate to the resource being requested. The resolver then returns the desired result.</p> <p>For example, suppose you wish to find the address of the token contract associated with 'beercoin.eth'. First, get the resolver:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">var</span><span class="z-variable z-other"> node</span><span class="z-keyword"> =</span><span class="z-entity z-name"> namehash</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">beercoin.eth</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"> resolver</span><span class="z-keyword"> =</span><span class="z-variable z-other"> ens</span><span>.</span><span class="z-entity z-name">resolver</span><span>(</span><span class="z-variable z-other">node</span><span>)</span><span>;</span></span></code></pre> <p>Then, ask the resolver for the address for the contract:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">var</span><span class="z-variable z-other"> address</span><span class="z-keyword"> =</span><span class="z-variable z-other"> resolver</span><span>.</span><span class="z-entity z-name">addr</span><span>(</span><span class="z-variable z-other">node</span><span>)</span><span>;</span></span></code></pre> <p>Because the <code>namehash</code> procedure depends only on the name itself, this can be precomputed and inserted into a contract, removing the need for string manipulation, and permitting O(1) lookup of ENS records regardless of the number of components in the raw name.</p> <h2 id="name-syntax">Name Syntax</h2> <p>ENS names must conform to the following syntax:</p> <pre>&lt;domain> ::= &lt;label> | &lt;domain> "." &lt;label> &lt;label> ::= any valid string label per [UTS46](https://unicode.org/reports/tr46/) </pre> <p>In short, names consist of a series of dot-separated labels. Each label must be a valid normalised label as described in <a rel="external" href="https://unicode.org/reports/tr46/">UTS46</a> with the options <code>transitional=false</code> and <code>useSTD3AsciiRules=true</code>. For Javascript implementations, a <a rel="external" href="https://www.npmjs.com/package/idna-uts46">library</a> is available that normalises and checks names.</p> <p>Note that while upper and lower case letters are allowed in names, the UTS46 normalisation process case-folds labels before hashing them, so two names with different case but identical spelling will produce the same namehash.</p> <p>Labels and domains may be of any length, but for compatibility with legacy DNS, it is recommended that labels be restricted to no more than 64 characters each, and complete ENS names to no more than 255 characters. For the same reason, it is recommended that labels do not start or end with hyphens, or start with digits.</p> <h2 id="namehash-algorithm">namehash algorithm</h2> <p>Before being used in ENS, names are hashed using the 'namehash' algorithm. This algorithm recursively hashes components of the name, producing a unique, fixed-length string for any valid input domain. The output of namehash is referred to as a 'node'.</p> <p>Pseudocode for the namehash algorithm is as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def namehash(name):</span></span> <span class="giallo-l"><span> if name == &#39;&#39;:</span></span> <span class="giallo-l"><span> return &#39;\0&#39; * 32</span></span> <span class="giallo-l"><span> else:</span></span> <span class="giallo-l"><span> label, _, remainder = name.partition(&#39;.&#39;)</span></span> <span class="giallo-l"><span> return sha3(namehash(remainder) + sha3(label))</span></span></code></pre> <p>Informally, the name is split into labels, each label is hashed. Then, starting with the last component, the previous output is concatenated with the label hash and hashed again. The first component is concatenated with 32 '0' bytes. Thus, 'mysite.swarm' is processed as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>node = &#39;\0&#39; * 32</span></span> <span class="giallo-l"><span>node = sha3(node + sha3(&#39;swarm&#39;))</span></span> <span class="giallo-l"><span>node = sha3(node + sha3(&#39;mysite&#39;))</span></span></code></pre> <p>Implementations should conform to the following test vectors for namehash:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>namehash(&#39;&#39;) = 0x0000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>namehash(&#39;eth&#39;) = 0x93cdeb708b7545dc668eb9280176169d1c33cfd8ed6f04690a0bcc88a93fc4ae</span></span> <span class="giallo-l"><span>namehash(&#39;foo.eth&#39;) = 0xde9b09fd7c5f901e23a3f19fecc54828e9c848539801e86591bd9801b019f84f</span></span></code></pre><h2 id="registry-specification">Registry specification</h2> <p>The ENS registry contract exposes the following functions:</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"> owner</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span></code></pre> <p>Returns the owner (registrar) of the specified node.</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"> resolver</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span></code></pre> <p>Returns the resolver for the specified node.</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"> ttl</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint64</span><span>)</span><span>;</span></span></code></pre> <p>Returns the time-to-live (TTL) of the node; that is, the maximum duration for which a node's information may be cached.</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"> setOwner</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"> owner</span><span>)</span><span>;</span></span></code></pre> <p>Transfers ownership of a node to another registrar. This function may only be called by the current owner of <code>node</code>. A successful call to this function logs the event <code>Transfer(bytes32 indexed, address)</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"> setSubnodeOwner</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> label</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> owner</span><span>)</span><span>;</span></span></code></pre> <p>Creates a new node, <code>sha3(node, label)</code> and sets its owner to <code>owner</code>, or updates the node with a new owner if it already exists. This function may only be called by the current owner of <code>node</code>. A successful call to this function logs the event <code>NewOwner(bytes32 indexed, bytes32 indexed, address)</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"> setResolver</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"> resolver</span><span>)</span><span>;</span></span></code></pre> <p>Sets the resolver address for <code>node</code>. This function may only be called by the owner of <code>node</code>. A successful call to this function logs the event <code>NewResolver(bytes32 indexed, address)</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"> setTTL</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> ttl</span><span>)</span><span>;</span></span></code></pre> <p>Sets the TTL for a node. A node's TTL applies to the 'owner' and 'resolver' records in the registry, as well as to any information returned by the associated resolver.</p> <h2 id="resolver-specification">Resolver specification</h2> <p>Resolvers may implement any subset of the record types specified here. Where a record types specification requires a resolver to provide multiple functions, the resolver MUST implement either all or none of them. Resolvers MUST specify a fallback function that throws.</p> <p>Resolvers 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 resolver 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 resolver 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>Currently standardised resolver interfaces are specified in the table below.</p> <p>The following interfaces are defined:</p> <table><thead><tr><th>Interface name</th><th>Interface hash</th><th>Specification</th></tr></thead><tbody> <tr><td><code>addr</code></td><td>0x3b3b57de</td><td><a href="https://wg-eips.ritovision.com/137/#addr">Contract address</a></td></tr> <tr><td><code>name</code></td><td>0x691f3431</td><td>#181</td></tr> <tr><td><code>ABI</code></td><td>0x2203ab56</td><td>#205</td></tr> <tr><td><code>pubkey</code></td><td>0xc8690233</td><td>#619</td></tr> </tbody></table> <p>EIPs may define new interfaces to be added to this registry.</p> <h3 id="contract-address-interface"><a name="addr"></a>Contract Address Interface</h3> <p>Resolvers wishing to support contract address resources must provide 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"> addr</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span></code></pre> <p>If the resolver supports <code>addr</code> lookups but the requested node does not have an addr record, the resolver MUST return the zero address.</p> <p>Clients resolving the <code>addr</code> record MUST check for a zero return value, and treat this in the same manner as a name that does not have a resolver specified - that is, refuse to send funds to or interact with the address. Failure to do this can result in users accidentally sending funds to the 0 address.</p> <p>Changes to an address MUST trigger the following event:</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"> 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></code></pre><h1 id="appendix-a-registry-implementation">Appendix A: Registry Implementation</h1> <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"> ENS</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Record</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> owner</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"> uint64</span><span> ttl</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"> mapping</span><span>(</span><span class="z-support">bytes32</span><span class="z-keyword">=&gt;</span><span>Record</span><span>)</span><span> records</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"> NewOwner</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">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> label</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 class="z-storage z-type"> event</span><span class="z-entity z-name"> Transfer</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"> owner</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> NewResolver</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"> resolver</span><span>)</span><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"> only_owner</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>records</span><span>[</span><span>node</span><span>]</span><span>.</span><span>owner </span><span class="z-keyword">!=</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span class="z-keyword"> throw</span><span>;</span></span> <span class="giallo-l"><span class="z-constant"> _</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"> ENS</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> records</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span>owner </span><span class="z-keyword">=</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-storage z-type"> function</span><span class="z-entity z-name"> owner</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>)</span><span class="z-entity z-name"> constant</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> records</span><span>[</span><span>node</span><span>]</span><span>.</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-storage z-type"> function</span><span class="z-entity z-name"> resolver</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>)</span><span class="z-entity z-name"> constant</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> records</span><span>[</span><span>node</span><span>]</span><span>.</span><span>resolver</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"> ttl</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>)</span><span class="z-entity z-name"> constant</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> records</span><span>[</span><span>node</span><span>]</span><span>.</span><span>ttl</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"> setOwner</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"> owner</span><span>)</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> <span class="giallo-l"><span class="z-entity z-name"> Transfer</span><span>(</span><span>node</span><span>,</span><span> owner</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> records</span><span>[</span><span>node</span><span>]</span><span>.</span><span>owner </span><span class="z-keyword">=</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-storage z-type"> function</span><span class="z-entity z-name"> setSubnodeOwner</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> label</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> owner</span><span>)</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> <span class="giallo-l"><span> var subnode </span><span class="z-keyword">=</span><span class="z-support"> sha3</span><span>(</span><span>node</span><span>,</span><span> label</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> NewOwner</span><span>(</span><span>node</span><span>,</span><span> label</span><span>,</span><span> owner</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> records</span><span>[</span><span>subnode</span><span>]</span><span>.</span><span>owner </span><span class="z-keyword">=</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-storage z-type"> function</span><span class="z-entity z-name"> setResolver</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"> resolver</span><span>)</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> <span class="giallo-l"><span class="z-entity z-name"> NewResolver</span><span>(</span><span>node</span><span>,</span><span> resolver</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> records</span><span>[</span><span>node</span><span>]</span><span>.</span><span>resolver </span><span class="z-keyword">=</span><span> resolver</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"> setTTL</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> ttl</span><span>)</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> <span class="giallo-l"><span class="z-entity z-name"> NewTTL</span><span>(</span><span>node</span><span>,</span><span> ttl</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> records</span><span>[</span><span>node</span><span>]</span><span>.</span><span>ttl </span><span class="z-keyword">=</span><span> ttl</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h1 id="appendix-b-sample-resolver-implementations">Appendix B: Sample Resolver Implementations</h1> <h3 id="built-in-resolver">Built-in resolver</h3> <p>The simplest possible resolver is a contract that acts as its own name resolver by implementing the contract address resource profile:</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"> DoSomethingUseful</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Other code</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-entity z-name"> constant</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-variable z-language"> this</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-entity z-name"> constant</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-constant"> 0x3b3b57de</span><span class="z-keyword"> ||</span><span> interfaceID </span><span class="z-keyword">==</span><span class="z-constant"> 0x01ffc9a7</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"> function</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> throw</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Such a contract can be inserted directly into the ENS registry, eliminating the need for a separate resolver contract in simple use-cases. However, the requirement to 'throw' on unknown function calls may interfere with normal operation of some types of contract.</p> <h3 id="standalone-resolver">Standalone resolver</h3> <p>A basic resolver that implements the contract address profile, and allows only its owner to update records:</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"> Resolver</span><span> {</span></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> <span class="giallo-l"><span class="z-support"> address</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">bytes32</span><span class="z-keyword">=&gt;</span><span class="z-support">address</span><span>)</span><span> addresses</span><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"> only_owner</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> owner</span><span>)</span><span class="z-keyword"> throw</span><span>;</span></span> <span class="giallo-l"><span class="z-constant"> _</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"> Resolver</span><span>(</span><span>)</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 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-entity z-name"> constant</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> addresses</span><span>[</span><span>node</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"> 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"> addr</span><span>)</span><span class="z-entity z-name"> only_owner</span><span> {</span></span> <span class="giallo-l"><span> addresses</span><span>[</span><span>node</span><span>]</span><span class="z-keyword"> =</span><span> addr</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> AddrChanged</span><span>(</span><span>node</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-entity z-name"> constant</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-constant"> 0x3b3b57de</span><span class="z-keyword"> ||</span><span> interfaceID </span><span class="z-keyword">==</span><span class="z-constant"> 0x01ffc9a7</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"> function</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> throw</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>After deploying this contract, use it by updating the ENS registry to reference this contract for a name, then calling <code>setAddr()</code> with the same node to set the contract address it will resolve to.</p> <h3 id="public-resolver">Public resolver</h3> <p>Similar to the resolver above, this contract only supports the contract address profile, but uses the ENS registry to determine who should be allowed to update entries:</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"> PublicResolver</span><span> {</span></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"> ContentChanged</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">bytes32</span><span class="z-variable"> hash</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> ENS ens</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">address</span><span>)</span><span> addresses</span><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"> only_owner</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>ens</span><span>.</span><span class="z-entity z-name">owner</span><span>(</span><span>node</span><span>)</span><span class="z-keyword"> !=</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span class="z-keyword"> throw</span><span>;</span></span> <span class="giallo-l"><span class="z-constant"> _</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"> PublicResolver</span><span>(</span><span class="z-support">address</span><span class="z-variable"> ensAddr</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> ens </span><span class="z-keyword">=</span><span class="z-entity z-name"> ENS</span><span>(</span><span>ensAddr</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"> addr</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> ret</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> ret </span><span class="z-keyword">=</span><span> addresses</span><span>[</span><span>node</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"> address</span><span class="z-variable"> addr</span><span>)</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> <span class="giallo-l"><span> addresses</span><span>[</span><span>node</span><span>]</span><span class="z-keyword"> =</span><span> addr</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> AddrChanged</span><span>(</span><span>node</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-entity z-name"> constant</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-constant"> 0x3b3b57de</span><span class="z-keyword"> ||</span><span> interfaceID </span><span class="z-keyword">==</span><span class="z-constant"> 0x01ffc9a7</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"> function</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> throw</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h1 id="appendix-c-sample-registrar-implementation">Appendix C: Sample Registrar Implementation</h1> <p>This registrar allows users to register names at no cost if they are the first to request them.</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"> FIFSRegistrar</span><span> {</span></span> <span class="giallo-l"><span> ENS ens</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> rootNode</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"> FIFSRegistrar</span><span>(</span><span class="z-support">address</span><span class="z-variable"> ensAddr</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> node</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> ens </span><span class="z-keyword">=</span><span class="z-entity z-name"> ENS</span><span>(</span><span>ensAddr</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> rootNode </span><span class="z-keyword">=</span><span> node</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"> register</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> subnode</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> var node </span><span class="z-keyword">=</span><span class="z-support"> sha3</span><span>(</span><span>rootNode</span><span>,</span><span> subnode</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> var currentOwner </span><span class="z-keyword">=</span><span> ens</span><span>.</span><span class="z-entity z-name">owner</span><span>(</span><span>node</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>currentOwner </span><span class="z-keyword">!=</span><span class="z-constant"> 0</span><span class="z-keyword"> &amp;&amp;</span><span> currentOwner </span><span class="z-keyword">!=</span><span class="z-variable z-language"> msg.sender</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> throw</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> ens</span><span>.</span><span class="z-entity z-name">setSubnodeOwner</span><span>(</span><span>rootNode</span><span>,</span><span> subnode</span><span>,</span><span> owner</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> 2016-02-17T00:00:00+00:00 2026-02-11T14:48:25+00:00 Alex Van de Sandehttps://github.com/alexvansande https://wg-eips.ritovision.com/67/

Format for encoding transactions into a URI

<h2 id="abstract">Abstract</h2> <p>This proposal (inspired by BIP 21) defines a format for encoding a transaction into a URI, including a recipient, number of ethers (possibly zero), and optional bytecode.</p> <h2 id="motivation">Motivation</h2> <p>Imagine these scenarios:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>* An exchange or a instant converter like ShapeShift wants to create a single Ethereum address for payments that will be converted into credit in their internal system or output bitcoin to an address.</span></span> <span class="giallo-l"><span>* A store wants to show a QR code to a client that will pop up a payment for exactly 12.34 ethers, which contains metadata on the product being bought.</span></span> <span class="giallo-l"><span>* A betting site wants to provide a link that the user can click on his site and it will open a default Ethereum wallet and execute a specific contract with given parameters.</span></span> <span class="giallo-l"><span>* A dapp in Mist wants to simply ask the user to sign a transaction with a specific ABI in a single call.</span></span></code></pre> <p>In all these scenarios, the provider wants to internally set up a transaction, with a recipient, an associated number of ethers (or none) and optional bytecode, all without requiring any fuss from the end user that is expected simply to choose a sender and authorise the transaction.</p> <p>Currently implementations for this are wonky: ShapeShift creates tons of temporary addresses and uses an internal system to check which one correspond to which metadata, there isn't any standard way for stores that want payment in ether to put specific metadata about price on the call and any app implementing contracts will have to use different solutions depending on the client they are targeting.</p> <p>The proposal goes beyond address, and also includes optional bytecode and value. Of course this would make the link longer, but it should not be something visible to the user. Instead it should be shown as a visual code (QR or otherwise), a link, or some other way to pass the information.</p> <p>If properly implemented in all wallets, this should make execution of contracts directly from wallets much simpler as the wallet client only needs to put the bytecode obtained by reading the QR code.</p> <h2 id="specification">Specification</h2> <p>If we follow the bitcoin standard, the result would be:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> ethereum:&lt;address&gt;[?value=&lt;value&gt;][?gas=&lt;suggestedGas&gt;][?data=&lt;bytecode&gt;]</span></span></code></pre> <p>Other data could be added, but ideally the client should take them from elsewhere in the blockchain, so instead of having a <code>label</code> or a <code>message</code> to be displayed to the users, these should be read from an identity system or metadata on the transaction itself.</p> <h3 id="example-1">Example 1</h3> <p>Clicking this link would open a transaction that would try to send <em>5 unicorns</em> to address <em>deadbeef</em>. The user would then simply approve, based on each wallet UI.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> ethereum:0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7?gas=100000&amp;data=0xa9059cbb00000000000000000000000000000000000000000000000000000000deadbeef0000000000000000000000000000000000000000000000000000000000000005</span></span></code></pre><h4 id="without-bytecode">Without Bytecode</h4> <p>Alternatively, the bytecode could be generated by the client and the request would be in plain text:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> ethereum:&lt;address&gt;[?value=&lt;value&gt;][?gas=&lt;suggestedGas&gt;][?function=nameOfFunction(param)]</span></span></code></pre><h3 id="example-2">Example 2</h3> <p>This is the same function as above, to send 5 unicorns from he sender to <em>deadbeef</em>, but now with a more readable function, which the client converts to bytecode.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> ethereum:0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7?gas=100000&amp;function=transfer(address 0xdeadbeef, uint 5)</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>TODO</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> 2016-01-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Martin Holst Swendehttps://github.com/holiman Nick Johnsonarachnid@notdot.net https://wg-eips.ritovision.com/191/ <h1 id="abstract">Abstract</h1> <p>This ERC proposes a specification about how to handle signed data in Ethereum contracts.</p> <h1 id="motivation">Motivation</h1> <p>Several multisignature wallet implementations have been created which accepts <code>presigned</code> transactions. A <code>presigned</code> transaction is a chunk of binary <code>signed_data</code>, along with signature (<code>r</code>, <code>s</code> and <code>v</code>). The interpretation of the <code>signed_data</code> has not been specified, leading to several problems:</p> <ul> <li>Standard Ethereum transactions can be submitted as <code>signed_data</code>. An Ethereum transaction can be unpacked, into the following components: <code>RLP&lt;nonce, gasPrice, startGas, to, value, data&gt;</code> (hereby called <code>RLPdata</code>), <code>r</code>, <code>s</code> and <code>v</code>. If there are no syntactical constraints on <code>signed_data</code>, this means that <code>RLPdata</code> can be used as a syntactically valid <code>presigned</code> transaction.</li> <li>Multisignature wallets have also had the problem that a <code>presigned</code> transaction has not been tied to a particular <code>validator</code>, i.e a specific wallet. Example: <ol> <li>Users <code>A</code>, <code>B</code> and <code>C</code> have the <code>2/3</code>-wallet <code>X</code></li> <li>Users <code>A</code>, <code>B</code> and <code>D</code> have the <code>2/3</code>-wallet <code>Y</code></li> <li>User <code>A</code> and <code>B</code> submit <code>presigned</code> transactions to <code>X</code>.</li> <li>Attacker can now reuse their presigned transactions to <code>X</code>, and submit to <code>Y</code>.</li> </ol> </li> </ul> <h2 id="specification">Specification</h2> <p>We propose the following format for <code>signed_data</code></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x19 &lt;1 byte version&gt; &lt;version specific data&gt; &lt;data to sign&gt;.</span></span></code></pre> <p>The initial <code>0x19</code> byte is intended to ensure that the <code>signed_data</code> is not valid RLP.</p> <blockquote> <p>For a single byte whose value is in the [0x00, 0x7f] range, that byte is its own RLP encoding.</p> </blockquote> <p>That means that any <code>signed_data</code> cannot be one RLP-structure, but a 1-byte <code>RLP</code> payload followed by something else. Thus, any EIP-191 <code>signed_data</code> can never be an Ethereum transaction.</p> <p>Additionally, <code>0x19</code> has been chosen because since ethereum/go-ethereum#2940 , the following is prepended before hashing in personal_sign:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&quot;\x19Ethereum Signed Message:\n&quot; + len(message).</span></span></code></pre> <p>Using <code>0x19</code> thus makes it possible to extend the scheme by defining a version <code>0x45</code> (<code>E</code>) to handle these kinds of signatures.</p> <h3 id="registry-of-version-bytes">Registry of version bytes</h3> <table><thead><tr><th>Version byte</th><th>EIP</th><th>Description</th></tr></thead><tbody> <tr><td><code>0x00</code></td><td><a href="https://wg-eips.ritovision.com/191/">191</a></td><td>Data with intended validator</td></tr> <tr><td><code>0x01</code></td><td><a href="https://wg-eips.ritovision.com/712/">712</a></td><td>Structured data</td></tr> <tr><td><code>0x45</code></td><td><a href="https://wg-eips.ritovision.com/191/">191</a></td><td><code>personal_sign</code> messages</td></tr> </tbody></table> <h4 id="version-0x00">Version <code>0x00</code></h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x19 &lt;0x00&gt; &lt;intended validator address&gt; &lt;data to sign&gt;</span></span></code></pre> <p>The version <code>0x00</code> has <code>&lt;intended validator address&gt;</code> for the version specific data. In the case of a Multisig wallet that perform an execution based on a passed signature, the validator address is the address of the Multisig itself. The data to sign could be any arbitrary data.</p> <h4 id="version-0x01">Version <code>0x01</code></h4> <p>The version <code>0x01</code> is for structured data as defined in <a href="https://wg-eips.ritovision.com/712/">EIP-712</a></p> <h4 id="version-0x45-e">Version <code>0x45</code> (E)</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x19 &lt;0x45 (E)&gt; &lt;thereum Signed Message:\n&quot; + len(message)&gt; &lt;data to sign&gt;</span></span></code></pre> <p>The version <code>0x45</code> (E) has <code>&lt;thereum Signed Message:\n" + len(message)&gt;</code> for the version-specific data. The data to sign can be any arbitrary data.</p> <blockquote> <p>NB: The <code>E</code> in <code>Ethereum Signed Message</code> refers to the version byte 0x45. The character <code>E</code> is <code>0x45</code> in hexadecimal which makes the remainder, <code>thereum Signed Message:\n + len(message)</code>, the version-specific data.</p> </blockquote> <h3 id="example">Example</h3> <p>The following snippets has been written in Solidity 0.8.0.</p> <h4 id="version-0x00-1">Version <code>0x00</code></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"> signatureBasedExecution</span><span>(</span><span class="z-support">address</span><span class="z-variable"> target</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> nonce</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> payload</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-storage z-type"> payable</span><span> {</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Arguments when calculating hash to validate</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 1: byte(0x19) - the initial 0x19 byte</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 2: byte(0) - the version byte</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 3: address(this) - the validator address</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> 4-6 : Application specific data</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> hash </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-entity z-name">byte</span><span>(</span><span class="z-constant">0x19</span><span>)</span><span>,</span><span class="z-entity z-name"> byte</span><span>(</span><span class="z-constant">0</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</span><span>.</span><span>value</span><span>,</span><span> nonce</span><span>,</span><span> payload</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"> recovering the signer from the hash and the signature</span></span> <span class="giallo-l"><span> addressRecovered </span><span class="z-keyword">=</span><span class="z-support"> ecrecover</span><span>(</span><span>hash</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 class="z-comment"> //</span><span class="z-comment"> logic of the wallet</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> if (addressRecovered == owner) executeOnTarget(target, payload);</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> 2016-01-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Vitalik Buterinvitalik.buterin@ethereum.org Alex Van de Sandeavsa@ethereum.org https://wg-eips.ritovision.com/55/ <h1 id="specification">Specification</h1> <p>Code:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">import</span><span> eth_utils</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"> checksum_encode</span><span>(</span><span class="z-variable z-parameter z-function">addr</span><span>)</span><span>:</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Takes a 20-byte binary address as input</span></span> <span class="giallo-l"><span> hex_addr</span><span class="z-keyword"> =</span><span> addr</span><span>.</span><span>hex</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> checksummed_buffer</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 class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Treat the hex address as ascii/utf-8 for keccak256 hashing</span></span> <span class="giallo-l"><span> hashed_address</span><span class="z-keyword"> =</span><span> eth_utils</span><span>.</span><span>keccak</span><span>(</span><span class="z-variable">text</span><span class="z-keyword">=</span><span>hex_addr</span><span>)</span><span>.</span><span>hex</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"> Iterate over each character in the hex address</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> nibble_index</span><span>,</span><span> character</span><span class="z-keyword"> in</span><span class="z-support"> enumerate</span><span>(</span><span>hex_addr</span><span>)</span><span>:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> character</span><span class="z-keyword"> in</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0123456789</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-comment"> #</span><span class="z-comment"> We can&#39;t upper-case the decimal digits</span></span> <span class="giallo-l"><span> checksummed_buffer</span><span class="z-keyword"> +=</span><span> character</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> character</span><span class="z-keyword"> in</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">abcdef</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-comment"> #</span><span class="z-comment"> Check if the corresponding hex digit (nibble) in the hash is 8 or higher</span></span> <span class="giallo-l"><span> hashed_address_nibble</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>(</span><span>hashed_address</span><span>[</span><span>nibble_index</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> hashed_address_nibble</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 7</span><span>:</span></span> <span class="giallo-l"><span> checksummed_buffer</span><span class="z-keyword"> +=</span><span> character</span><span>.</span><span>upper</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> checksummed_buffer</span><span class="z-keyword"> +=</span><span> character</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> eth_utils</span><span>.</span><span>ValidationError</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> f</span><span class="z-string">&quot;</span><span class="z-string">Unrecognized hex character </span><span class="z-constant">{</span><span>character</span><span class="z-storage z-type">!r</span><span class="z-constant">}</span><span class="z-string"> at position </span><span class="z-constant">{</span><span>nibble_index</span><span class="z-constant">}</span><span class="z-string">&quot;</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 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 class="z-keyword"> +</span><span> checksummed_buffer</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"> test</span><span>(</span><span class="z-variable z-parameter z-function">addr_str</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> addr_bytes</span><span class="z-keyword"> =</span><span> eth_utils</span><span>.</span><span>to_bytes</span><span>(</span><span class="z-variable">hexstr</span><span class="z-keyword">=</span><span>addr_str</span><span>)</span></span> <span class="giallo-l"><span> checksum_encoded</span><span class="z-keyword"> =</span><span> checksum_encode</span><span>(</span><span>addr_bytes</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> checksum_encoded</span><span class="z-keyword"> ==</span><span> addr_str</span><span>,</span><span class="z-storage z-type"> f</span><span class="z-string">&quot;</span><span class="z-constant">{</span><span>checksum_encoded</span><span class="z-constant">}</span><span class="z-string"> != expected </span><span class="z-constant">{</span><span>addr_str</span><span class="z-constant">}</span><span class="z-string">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>test</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span>test</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span>test</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span>test</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"></span></code></pre> <p>In English, convert the address to hex, but if the <code>i</code>th digit is a letter (ie. it's one of <code>abcdef</code>) print it in uppercase if the <code>4*i</code>th bit of the hash of the lowercase hexadecimal address is 1 otherwise print it in lowercase.</p> <h1 id="rationale">Rationale</h1> <p>Benefits:</p> <ul> <li>Backwards compatible with many hex parsers that accept mixed case, allowing it to be easily introduced over time</li> <li>Keeps the length at 40 characters</li> <li>On average there will be 15 check bits per address, and the net probability that a randomly generated address if mistyped will accidentally pass a check is 0.0247%. This is a ~50x improvement over ICAP, but not as good as a 4-byte check code.</li> </ul> <h1 id="implementation">Implementation</h1> <p>In javascript:</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"> createKeccakHash</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">keccak</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-storage z-type">function</span><span class="z-entity z-name"> toChecksumAddress</span><span> (</span><span class="z-variable">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-keyword"> =</span><span class="z-variable z-other"> address</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">&#39;</span><span class="z-string">0x</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-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> hash</span><span class="z-keyword"> =</span><span class="z-entity z-name"> createKeccakHash</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">keccak256</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>.</span><span class="z-entity z-name">update</span><span>(</span><span class="z-variable z-other">address</span><span>)</span><span>.</span><span class="z-entity z-name">digest</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">hex</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> ret</span><span class="z-keyword"> =</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 class="giallo-l"></span> <span class="giallo-l"><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"> i</span><span class="z-keyword"> &lt;</span><span class="z-variable z-other"> address</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-keyword"> if</span><span> (</span><span class="z-entity z-name">parseInt</span><span>(</span><span class="z-variable z-other">hash</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span>,</span><span class="z-constant"> 16</span><span>)</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> 8</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> ret</span><span class="z-keyword"> +=</span><span class="z-variable z-other"> address</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span>.</span><span class="z-entity z-name">toUpperCase</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"> ret</span><span class="z-keyword"> +=</span><span class="z-variable z-other"> address</span><span>[</span><span class="z-variable z-other">i</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 class="z-variable z-other"> ret</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>&gt; toChecksumAddress(&#39;0xfb6916095ca1df60bb79ce92ce3ea74c37c5d359&#39;)</span></span> <span class="giallo-l"><span>&#39;0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359&#39;</span></span></code></pre> <p>Note that the input to the Keccak256 hash is the lowercase hexadecimal string (i.e. the hex address encoded as ASCII):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> var hash = createKeccakHash(&#39;keccak256&#39;).update(Buffer.from(address.toLowerCase(), &#39;ascii&#39;)).digest()</span></span></code></pre><h1 id="test-cases">Test Cases</h1> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span># All caps</span></span> <span class="giallo-l"><span>0x52908400098527886E0F7030069857D2E4169EE7</span></span> <span class="giallo-l"><span>0x8617E340B3D01FA5F11F306F4090FD50E238070D</span></span> <span class="giallo-l"><span># All Lower</span></span> <span class="giallo-l"><span>0xde709f2102306220921060314715629080e2fb77</span></span> <span class="giallo-l"><span>0x27b1fdb04752bbc536007a920d24acb045561c26</span></span> <span class="giallo-l"><span># Normal</span></span> <span class="giallo-l"><span>0x5aAeb6053F3E94C9b9A09f33669435E7Ef1BeAed</span></span> <span class="giallo-l"><span>0xfB6916095ca1df60bB79Ce92cE3Ea74c37c5d359</span></span> <span class="giallo-l"><span>0xdbF03B407c01E7cD3CBea99509d93f8DDDC8C6FB</span></span> <span class="giallo-l"><span>0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb</span></span></code></pre> 2015-12-18T00:00:00+00:00 2026-02-11T14:49:28+00:00 Felix Langefelix@ethdev.com https://wg-eips.ritovision.com/8/ <h3 id="abstract">Abstract</h3> <p>This EIP introduces new forward-compatibility requirements for implementations of the devp2p Wire Protocol, the RLPx Discovery Protocol and the RLPx TCP Transport Protocol. Clients which implement EIP-8 behave according to Postel's Law:</p> <blockquote> <p>Be conservative in what you do, be liberal in what you accept from others.</p> </blockquote> <h3 id="specification">Specification</h3> <p>Implementations of <strong>the devp2p Wire Protocol</strong> should ignore the version number of hello packets. When sending the hello packet, the version element should be set to the highest devp2p version supported. Implementations should also ignore any additional list elements at the end of the hello packet.</p> <p>Similarly, implementations of <strong>the RLPx Discovery Protocol</strong> should not validate the version number of the ping packet, ignore any additional list elements in any packet, and ignore any data after the first RLP value in any packet. Discovery packets with unknown packet type should be discarded silently. The maximum size of any discovery packet is still 1280 bytes.</p> <p>Finally, implementations of <strong>the RLPx TCP Transport protocol</strong> should accept a new encoding for the encrypted key establishment handshake packets. If an EIP-8 style RLPx <code>auth-packet</code> is received, the corresponding <code>ack-packet</code> should be sent using the rules below.</p> <p>Decoding the RLP data in <code>auth-body</code> and <code>ack-body</code> should ignore mismatches of <code>auth-vsn</code> and <code>ack-vsn</code>, any additional list elements and any trailing data after the list. During the transitioning period (i.e. until the old format has been retired), implementations should pad <code>auth-body</code> with at least 100 bytes of junk data. Adding a random amount in range [100, 300] is recommended to vary the size of the packet.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>auth-vsn = 4</span></span> <span class="giallo-l"><span>auth-size = size of enc-auth-body, encoded as a big-endian 16-bit integer</span></span> <span class="giallo-l"><span>auth-body = rlp.list(sig, initiator-pubk, initiator-nonce, auth-vsn)</span></span> <span class="giallo-l"><span>enc-auth-body = ecies.encrypt(recipient-pubk, auth-body, auth-size)</span></span> <span class="giallo-l"><span>auth-packet = auth-size || enc-auth-body</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>ack-vsn = 4</span></span> <span class="giallo-l"><span>ack-size = size of enc-ack-body, encoded as a big-endian 16-bit integer</span></span> <span class="giallo-l"><span>ack-body = rlp.list(recipient-ephemeral-pubk, recipient-nonce, ack-vsn)</span></span> <span class="giallo-l"><span>enc-ack-body = ecies.encrypt(initiator-pubk, ack-body, ack-size)</span></span> <span class="giallo-l"><span>ack-packet = ack-size || enc-ack-body</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>where</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>X || Y</span></span> <span class="giallo-l"><span> denotes concatenation of X and Y.</span></span> <span class="giallo-l"><span>X[:N]</span></span> <span class="giallo-l"><span> denotes an N-byte prefix of X.</span></span> <span class="giallo-l"><span>rlp.list(X, Y, Z, ...)</span></span> <span class="giallo-l"><span> denotes recursive encoding of [X, Y, Z, ...] as an RLP list.</span></span> <span class="giallo-l"><span>sha3(MESSAGE)</span></span> <span class="giallo-l"><span> is the Keccak256 hash function as used by Ethereum.</span></span> <span class="giallo-l"><span>ecies.encrypt(PUBKEY, MESSAGE, AUTHDATA)</span></span> <span class="giallo-l"><span> is the asymmetric authenticated encryption function as used by RLPx.</span></span> <span class="giallo-l"><span> AUTHDATA is authenticated data which is not part of the resulting ciphertext,</span></span> <span class="giallo-l"><span> but written to HMAC-256 before generating the message tag.</span></span></code></pre><h3 id="motivation">Motivation</h3> <p>Changes to the devp2p protocols are hard to deploy because clients running an older version will refuse communication if the version number or structure of the hello (discovery ping, RLPx handshake) packet does not match local expectations.</p> <p>Introducing forward-compatibility requirements as part of the Homestead consensus upgrade will ensure that all client software in use on the Ethereum network can cope with future network protocol upgrades (as long as backwards-compatibility is maintained).</p> <h3 id="rationale">Rationale</h3> <p>The proposed changes address forward compatibility by applying Postel's Law (also known as the Robustness Principle) throughout the protocol stack. The merit and applicability of this approach has been studied repeatedly since its original application in RFC 761. For a recent perspective, see <a rel="external" href="https://queue.acm.org/detail.cfm?id=1999945">"The Robustness Principle Reconsidered" (Eric Allman, 2011)</a>.</p> <h4 id="changes-to-the-devp2p-wire-protocol">Changes to the devp2p Wire Protocol</h4> <p>All clients currently contain statements such as the following:</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"> pydevp2p/p2p_protocol.py</span></span> <span class="giallo-l"><span class="z-keyword">if</span><span> data</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">version</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span class="z-keyword"> !=</span><span> proto</span><span>.</span><span>version</span><span>:</span></span> <span class="giallo-l"><span> log</span><span>.</span><span>debug</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">incompatible network protocols</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-variable"> peer</span><span class="z-keyword">=</span><span>proto</span><span>.</span><span>peer</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> expected</span><span class="z-keyword">=</span><span>proto</span><span>.</span><span>version</span><span>,</span><span class="z-variable"> received</span><span class="z-keyword">=</span><span>data</span><span>[</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">version</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> proto</span><span>.</span><span>send_disconnect</span><span>(</span><span class="z-variable">reason</span><span class="z-keyword">=</span><span>reasons</span><span>.</span><span>incompatible_p2p_version</span><span>)</span></span></code></pre> <p>These checks make it impossible to change the version or structure of the hello packet. Dropping them enables switching to a newer protocol version: Clients implementing a newer version simply send a packet with higher version and possibly additional list elements.</p> <ul> <li>If such a packet is received by a node with lower version, it will blindly assume that the remote end is backwards-compatible and respond with the old handshake.</li> <li>If the packet is received by a node with equal version, new features of the protocol can be used.</li> <li>If the packet is received by a node with higher version, it can enable backwards-compatibility logic or drop the connection.</li> </ul> <h4 id="changes-to-the-rlpx-discovery-protocol">Changes to the RLPx Discovery Protocol</h4> <p>The relaxation of discovery packet decoding rules largely codifies current practice. Most existing implementations do not care about the number of list elements (an exception being go-ethereum) and do not reject nodes with mismatching version. This behaviour is not guaranteed by the spec, though.</p> <p>If adopted, the change makes it possible to deploy protocol changes in a similar manner to the devp2p hello change: simply bump the version and send additional information. Older clients will ignore the additional elements and can continue to operate even when the majority of the network has moved on to a newer protocol.</p> <h4 id="changes-to-the-rlpx-tcp-handshake">Changes to the RLPx TCP Handshake</h4> <p>Discussions of the RLPx v5 changes (chunked packets, change to key derivation) have faltered in part because the v4 handshake encoding provides only one in-band way to add a version number: shortening the random portion of the nonce. Even if the RLPx v5 handshake proposal were accepted, future upgrades are hard because the handshake packet is a fixed size ECIES ciphertext with known layout.</p> <p>I propose the following changes to the handshake packets:</p> <ul> <li>Adding the length of the ciphertext as a plaintext header.</li> <li>Encoding the body of the handshake as RLP.</li> <li>Adding a version number to both packets in place of the token flag (unused).</li> <li>Removing the hash of the ephemeral public key (it is redundant).</li> </ul> <p>These changes make it possible to upgrade the RLPx TCP transport protocol in the same manner as described for the other protocols, i.e. by adding list elements and bumping the version. Since this is the first change to the RLPx handshake packet, we can seize the opportunity to remove all currently unused fields.</p> <p>Additional data is permitted (and in fact required) after the RLP list because the handshake packet needs to grow in order to be distinguishable from the old format. Clients can employ logic such as the following pseudocode to handle both formats simultaneously.</p> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span class="z-variable z-other">packet</span><span class="z-keyword"> =</span><span class="z-entity z-name"> read</span><span>(</span><span class="z-constant">307</span><span>,</span><span class="z-variable z-other"> connection</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">if</span><span class="z-entity z-name"> decrypt</span><span>(</span><span class="z-variable z-other">packet</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> process as old format</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"> size</span><span class="z-keyword"> =</span><span class="z-entity z-name"> unpack_16bit_big_endian</span><span>(</span><span class="z-variable z-other">packet</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> packet</span><span class="z-keyword"> +=</span><span class="z-entity z-name"> read</span><span>(</span><span class="z-variable z-other">size</span><span class="z-keyword"> -</span><span class="z-constant"> 307</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span>,</span><span class="z-variable z-other"> connection</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> !</span><span class="z-entity z-name">decrypt</span><span>(</span><span class="z-variable z-other">packet</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> error</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 as new format</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The plain text size prefix is perhaps the most controversial aspect of this document. It has been argued that the prefix aids adversaries that seek to filter and identify RLPx connections on the network level.</p> <p>This is largely a question of how much effort the adversary is willing to expense. If the recommendation to randomise the lengths is followed, pure pattern-based packet recognition is unlikely to succeed.</p> <ul> <li>For typical firewall operators, blocking all connections whose first two bytes form an integer in range [300,600] is probably too invasive. Port-based blocking would be a more effective measure to filter most RLPx traffic.</li> <li>For an attacker who can afford to correlate many criteria, the size prefix would ease recognition because it adds to the indicator set. However, such an attacker could also be expected to read or participate in RLPx Discovery traffic, which would be sufficient to enable blocking of RLPx TCP connections whatever their format is.</li> </ul> <h3 id="backwards-compatibility">Backwards Compatibility</h3> <p>This EIP is backwards-compatible, all valid version 4 packets are still accepted.</p> <h3 id="implementation">Implementation</h3> <p><a rel="external" href="https://github.com/ethereum/go-ethereum/pull/2091">go-ethereum</a> <a rel="external" href="https://github.com/ethereum/libweb3core/pull/46">libweb3core</a> <a rel="external" href="https://github.com/ethereum/pydevp2p/pull/32">pydevp2p</a></p> <h3 id="test-vectors">Test Vectors</h3> <h4 id="devp2p-base-protocol">devp2p Base Protocol</h4> <p>devp2p hello packet advertising version 22 and containing a few additional list elements:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>f87137916b6e6574682f76302e39312f706c616e39cdc5836574683dc6846d6f726b1682270fb840</span></span> <span class="giallo-l"><span>fda1cff674c90c9a197539fe3dfb53086ace64f83ed7c6eabec741f7f381cc803e52ab2cd55d5569</span></span> <span class="giallo-l"><span>bce4347107a310dfd5f88a010cd2ffd1005ca406f1842877c883666f6f836261720304</span></span></code></pre><h4 id="rlpx-discovery-protocol">RLPx Discovery Protocol</h4> <p>Implementations should accept the following encoded discovery packets as valid. The packets are signed using the secp256k1 node key</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>b71c71a67e1177ad4e901695e1b4b9ee17ae16c6668d313eac2f96dbcda3f291</span></span></code></pre> <p>ping packet with version 4, additional list elements:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>e9614ccfd9fc3e74360018522d30e1419a143407ffcce748de3e22116b7e8dc92ff74788c0b6663a</span></span> <span class="giallo-l"><span>aa3d67d641936511c8f8d6ad8698b820a7cf9e1be7155e9a241f556658c55428ec0563514365799a</span></span> <span class="giallo-l"><span>4be2be5a685a80971ddcfa80cb422cdd0101ec04cb847f000001820cfa8215a8d790000000000000</span></span> <span class="giallo-l"><span>000000000000000000018208ae820d058443b9a3550102</span></span></code></pre> <p>ping packet with version 555, additional list elements and additional random data:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>577be4349c4dd26768081f58de4c6f375a7a22f3f7adda654d1428637412c3d7fe917cadc56d4e5e</span></span> <span class="giallo-l"><span>7ffae1dbe3efffb9849feb71b262de37977e7c7a44e677295680e9e38ab26bee2fcbae207fba3ff3</span></span> <span class="giallo-l"><span>d74069a50b902a82c9903ed37cc993c50001f83e82022bd79020010db83c4d001500000000abcdef</span></span> <span class="giallo-l"><span>12820cfa8215a8d79020010db885a308d313198a2e037073488208ae82823a8443b9a355c5010203</span></span> <span class="giallo-l"><span>040531b9019afde696e582a78fa8d95ea13ce3297d4afb8ba6433e4154caa5ac6431af1b80ba7602</span></span> <span class="giallo-l"><span>3fa4090c408f6b4bc3701562c031041d4702971d102c9ab7fa5eed4cd6bab8f7af956f7d565ee191</span></span> <span class="giallo-l"><span>7084a95398b6a21eac920fe3dd1345ec0a7ef39367ee69ddf092cbfe5b93e5e568ebc491983c09c7</span></span> <span class="giallo-l"><span>6d922dc3</span></span></code></pre> <p>pong packet with additional list elements and additional random data:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>09b2428d83348d27cdf7064ad9024f526cebc19e4958f0fdad87c15eb598dd61d08423e0bf66b206</span></span> <span class="giallo-l"><span>9869e1724125f820d851c136684082774f870e614d95a2855d000f05d1648b2d5945470bc187c2d2</span></span> <span class="giallo-l"><span>216fbe870f43ed0909009882e176a46b0102f846d79020010db885a308d313198a2e037073488208</span></span> <span class="giallo-l"><span>ae82823aa0fbc914b16819237dcd8801d7e53f69e9719adecb3cc0e790c57e91ca4461c9548443b9</span></span> <span class="giallo-l"><span>a355c6010203c2040506a0c969a58f6f9095004c0177a6b47f451530cab38966a25cca5cb58f0555</span></span> <span class="giallo-l"><span>42124e</span></span></code></pre> <p>findnode packet with additional list elements and additional random data:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>c7c44041b9f7c7e41934417ebac9a8e1a4c6298f74553f2fcfdcae6ed6fe53163eb3d2b52e39fe91</span></span> <span class="giallo-l"><span>831b8a927bf4fc222c3902202027e5e9eb812195f95d20061ef5cd31d502e47ecb61183f74a504fe</span></span> <span class="giallo-l"><span>04c51e73df81f25c4d506b26db4517490103f84eb840ca634cae0d49acb401d8a4c6b6fe8c55b70d</span></span> <span class="giallo-l"><span>115bf400769cc1400f3258cd31387574077f301b421bc84df7266c44e9e6d569fc56be0081290476</span></span> <span class="giallo-l"><span>7bf5ccd1fc7f8443b9a35582999983999999280dc62cc8255c73471e0a61da0c89acdc0e035e260a</span></span> <span class="giallo-l"><span>dd7fc0c04ad9ebf3919644c91cb247affc82b69bd2ca235c71eab8e49737c937a2c396</span></span></code></pre> <p>neighbours packet with additional list elements and additional random data:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>c679fc8fe0b8b12f06577f2e802d34f6fa257e6137a995f6f4cbfc9ee50ed3710faf6e66f932c4c8</span></span> <span class="giallo-l"><span>d81d64343f429651328758b47d3dbc02c4042f0fff6946a50f4a49037a72bb550f3a7872363a83e1</span></span> <span class="giallo-l"><span>b9ee6469856c24eb4ef80b7535bcf99c0004f9015bf90150f84d846321163782115c82115db84031</span></span> <span class="giallo-l"><span>55e1427f85f10a5c9a7755877748041af1bcd8d474ec065eb33df57a97babf54bfd2103575fa8291</span></span> <span class="giallo-l"><span>15d224c523596b401065a97f74010610fce76382c0bf32f84984010203040101b840312c55512422</span></span> <span class="giallo-l"><span>cf9b8a4097e9a6ad79402e87a15ae909a4bfefa22398f03d20951933beea1e4dfa6f968212385e82</span></span> <span class="giallo-l"><span>9f04c2d314fc2d4e255e0d3bc08792b069dbf8599020010db83c4d001500000000abcdef12820d05</span></span> <span class="giallo-l"><span>820d05b84038643200b172dcfef857492156971f0e6aa2c538d8b74010f8e140811d53b98c765dd2</span></span> <span class="giallo-l"><span>d96126051913f44582e8c199ad7c6d6819e9a56483f637feaac9448aacf8599020010db885a308d3</span></span> <span class="giallo-l"><span>13198a2e037073488203e78203e8b8408dcab8618c3253b558d459da53bd8fa68935a719aff8b811</span></span> <span class="giallo-l"><span>197101a4b2b47dd2d47295286fc00cc081bb542d760717d1bdd6bec2c37cd72eca367d6dd3b9df73</span></span> <span class="giallo-l"><span>8443b9a355010203b525a138aa34383fec3d2719a0</span></span></code></pre><h4 id="rlpx-handshake">RLPx Handshake</h4> <p>In these test vectors, node A initiates a connection with node B. The values contained in all packets are given below:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Static Key A: 49a7b37aa6f6645917e7b807e9d1c00d4fa71f18343b0d4122a4d2df64dd6fee</span></span> <span class="giallo-l"><span>Static Key B: b71c71a67e1177ad4e901695e1b4b9ee17ae16c6668d313eac2f96dbcda3f291</span></span> <span class="giallo-l"><span>Ephemeral Key A: 869d6ecf5211f1cc60418a13b9d870b22959d0c16f02bec714c960dd2298a32d</span></span> <span class="giallo-l"><span>Ephemeral Key B: e238eb8e04fee6511ab04c6dd3c89ce097b11f25d584863ac2b6d5b35b1847e4</span></span> <span class="giallo-l"><span>Nonce A: 7e968bba13b6c50e2c4cd7f241cc0d64d1ac25c7f5952df231ac6a2bda8ee5d6</span></span> <span class="giallo-l"><span>Nonce B: 559aead08264d5795d3909718cdd05abd49572e84fe55590eef31a88a08fdffd</span></span></code></pre> <p>(Auth₁) RLPx v4 format (sent from A to B):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>048ca79ad18e4b0659fab4853fe5bc58eb83992980f4c9cc147d2aa31532efd29a3d3dc6a3d89eaf</span></span> <span class="giallo-l"><span>913150cfc777ce0ce4af2758bf4810235f6e6ceccfee1acc6b22c005e9e3a49d6448610a58e98744</span></span> <span class="giallo-l"><span>ba3ac0399e82692d67c1f58849050b3024e21a52c9d3b01d871ff5f210817912773e610443a9ef14</span></span> <span class="giallo-l"><span>2e91cdba0bd77b5fdf0769b05671fc35f83d83e4d3b0b000c6b2a1b1bba89e0fc51bf4e460df3105</span></span> <span class="giallo-l"><span>c444f14be226458940d6061c296350937ffd5e3acaceeaaefd3c6f74be8e23e0f45163cc7ebd7622</span></span> <span class="giallo-l"><span>0f0128410fd05250273156d548a414444ae2f7dea4dfca2d43c057adb701a715bf59f6fb66b2d1d2</span></span> <span class="giallo-l"><span>0f2c703f851cbf5ac47396d9ca65b6260bd141ac4d53e2de585a73d1750780db4c9ee4cd4d225173</span></span> <span class="giallo-l"><span>a4592ee77e2bd94d0be3691f3b406f9bba9b591fc63facc016bfa8</span></span></code></pre> <p>(Auth₂) EIP-8 format with version 4 and no additional list elements (sent from A to B):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>01b304ab7578555167be8154d5cc456f567d5ba302662433674222360f08d5f1534499d3678b513b</span></span> <span class="giallo-l"><span>0fca474f3a514b18e75683032eb63fccb16c156dc6eb2c0b1593f0d84ac74f6e475f1b8d56116b84</span></span> <span class="giallo-l"><span>9634a8c458705bf83a626ea0384d4d7341aae591fae42ce6bd5c850bfe0b999a694a49bbbaf3ef6c</span></span> <span class="giallo-l"><span>da61110601d3b4c02ab6c30437257a6e0117792631a4b47c1d52fc0f8f89caadeb7d02770bf999cc</span></span> <span class="giallo-l"><span>147d2df3b62e1ffb2c9d8c125a3984865356266bca11ce7d3a688663a51d82defaa8aad69da39ab6</span></span> <span class="giallo-l"><span>d5470e81ec5f2a7a47fb865ff7cca21516f9299a07b1bc63ba56c7a1a892112841ca44b6e0034dee</span></span> <span class="giallo-l"><span>70c9adabc15d76a54f443593fafdc3b27af8059703f88928e199cb122362a4b35f62386da7caad09</span></span> <span class="giallo-l"><span>c001edaeb5f8a06d2b26fb6cb93c52a9fca51853b68193916982358fe1e5369e249875bb8d0d0ec3</span></span> <span class="giallo-l"><span>6f917bc5e1eafd5896d46bd61ff23f1a863a8a8dcd54c7b109b771c8e61ec9c8908c733c0263440e</span></span> <span class="giallo-l"><span>2aa067241aaa433f0bb053c7b31a838504b148f570c0ad62837129e547678c5190341e4f1693956c</span></span> <span class="giallo-l"><span>3bf7678318e2d5b5340c9e488eefea198576344afbdf66db5f51204a6961a63ce072c8926c</span></span></code></pre> <p>(Auth₃) EIP-8 format with version 56 and 3 additional list elements (sent from A to B):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>01b8044c6c312173685d1edd268aa95e1d495474c6959bcdd10067ba4c9013df9e40ff45f5bfd6f7</span></span> <span class="giallo-l"><span>2471f93a91b493f8e00abc4b80f682973de715d77ba3a005a242eb859f9a211d93a347fa64b597bf</span></span> <span class="giallo-l"><span>280a6b88e26299cf263b01b8dfdb712278464fd1c25840b995e84d367d743f66c0e54a586725b7bb</span></span> <span class="giallo-l"><span>f12acca27170ae3283c1073adda4b6d79f27656993aefccf16e0d0409fe07db2dc398a1b7e8ee93b</span></span> <span class="giallo-l"><span>cd181485fd332f381d6a050fba4c7641a5112ac1b0b61168d20f01b479e19adf7fdbfa0905f63352</span></span> <span class="giallo-l"><span>bfc7e23cf3357657455119d879c78d3cf8c8c06375f3f7d4861aa02a122467e069acaf513025ff19</span></span> <span class="giallo-l"><span>6641f6d2810ce493f51bee9c966b15c5043505350392b57645385a18c78f14669cc4d960446c1757</span></span> <span class="giallo-l"><span>1b7c5d725021babbcd786957f3d17089c084907bda22c2b2675b4378b114c601d858802a55345a15</span></span> <span class="giallo-l"><span>116bc61da4193996187ed70d16730e9ae6b3bb8787ebcaea1871d850997ddc08b4f4ea668fbf3740</span></span> <span class="giallo-l"><span>7ac044b55be0908ecb94d4ed172ece66fd31bfdadf2b97a8bc690163ee11f5b575a4b44e36e2bfb2</span></span> <span class="giallo-l"><span>f0fce91676fd64c7773bac6a003f481fddd0bae0a1f31aa27504e2a533af4cef3b623f4791b2cca6</span></span> <span class="giallo-l"><span>d490</span></span></code></pre> <p>(Ack₁) RLPx v4 format (sent from B to A):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>049f8abcfa9c0dc65b982e98af921bc0ba6e4243169348a236abe9df5f93aa69d99cadddaa387662</span></span> <span class="giallo-l"><span>b0ff2c08e9006d5a11a278b1b3331e5aaabf0a32f01281b6f4ede0e09a2d5f585b26513cb794d963</span></span> <span class="giallo-l"><span>5a57563921c04a9090b4f14ee42be1a5461049af4ea7a7f49bf4c97a352d39c8d02ee4acc416388c</span></span> <span class="giallo-l"><span>1c66cec761d2bc1c72da6ba143477f049c9d2dde846c252c111b904f630ac98e51609b3b1f58168d</span></span> <span class="giallo-l"><span>dca6505b7196532e5f85b259a20c45e1979491683fee108e9660edbf38f3add489ae73e3dda2c71b</span></span> <span class="giallo-l"><span>d1497113d5c755e942d1</span></span></code></pre> <p>(Ack₂) EIP-8 format with version 4 and no additional list elements (sent from B to A):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>01ea0451958701280a56482929d3b0757da8f7fbe5286784beead59d95089c217c9b917788989470</span></span> <span class="giallo-l"><span>b0e330cc6e4fb383c0340ed85fab836ec9fb8a49672712aeabbdfd1e837c1ff4cace34311cd7f4de</span></span> <span class="giallo-l"><span>05d59279e3524ab26ef753a0095637ac88f2b499b9914b5f64e143eae548a1066e14cd2f4bd7f814</span></span> <span class="giallo-l"><span>c4652f11b254f8a2d0191e2f5546fae6055694aed14d906df79ad3b407d94692694e259191cde171</span></span> <span class="giallo-l"><span>ad542fc588fa2b7333313d82a9f887332f1dfc36cea03f831cb9a23fea05b33deb999e85489e645f</span></span> <span class="giallo-l"><span>6aab1872475d488d7bd6c7c120caf28dbfc5d6833888155ed69d34dbdc39c1f299be1057810f34fb</span></span> <span class="giallo-l"><span>e754d021bfca14dc989753d61c413d261934e1a9c67ee060a25eefb54e81a4d14baff922180c395d</span></span> <span class="giallo-l"><span>3f998d70f46f6b58306f969627ae364497e73fc27f6d17ae45a413d322cb8814276be6ddd13b885b</span></span> <span class="giallo-l"><span>201b943213656cde498fa0e9ddc8e0b8f8a53824fbd82254f3e2c17e8eaea009c38b4aa0a3f306e8</span></span> <span class="giallo-l"><span>797db43c25d68e86f262e564086f59a2fc60511c42abfb3057c247a8a8fe4fb3ccbadde17514b7ac</span></span> <span class="giallo-l"><span>8000cdb6a912778426260c47f38919a91f25f4b5ffb455d6aaaf150f7e5529c100ce62d6d92826a7</span></span> <span class="giallo-l"><span>1778d809bdf60232ae21ce8a437eca8223f45ac37f6487452ce626f549b3b5fdee26afd2072e4bc7</span></span> <span class="giallo-l"><span>5833c2464c805246155289f4</span></span></code></pre> <p>(Ack₃) EIP-8 format with version 57 and 3 additional list elements (sent from B to A):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>01f004076e58aae772bb101ab1a8e64e01ee96e64857ce82b1113817c6cdd52c09d26f7b90981cd7</span></span> <span class="giallo-l"><span>ae835aeac72e1573b8a0225dd56d157a010846d888dac7464baf53f2ad4e3d584531fa203658fab0</span></span> <span class="giallo-l"><span>3a06c9fd5e35737e417bc28c1cbf5e5dfc666de7090f69c3b29754725f84f75382891c561040ea1d</span></span> <span class="giallo-l"><span>dc0d8f381ed1b9d0d4ad2a0ec021421d847820d6fa0ba66eaf58175f1b235e851c7e2124069fbc20</span></span> <span class="giallo-l"><span>2888ddb3ac4d56bcbd1b9b7eab59e78f2e2d400905050f4a92dec1c4bdf797b3fc9b2f8e84a482f3</span></span> <span class="giallo-l"><span>d800386186712dae00d5c386ec9387a5e9c9a1aca5a573ca91082c7d68421f388e79127a5177d4f8</span></span> <span class="giallo-l"><span>590237364fd348c9611fa39f78dcdceee3f390f07991b7b47e1daa3ebcb6ccc9607811cb17ce51f1</span></span> <span class="giallo-l"><span>c8c2c5098dbdd28fca547b3f58c01a424ac05f869f49c6a34672ea2cbbc558428aa1fe48bbfd6115</span></span> <span class="giallo-l"><span>8b1b735a65d99f21e70dbc020bfdface9f724a0d1fb5895db971cc81aa7608baa0920abb0a565c9c</span></span> <span class="giallo-l"><span>436e2fd13323428296c86385f2384e408a31e104670df0791d93e743a3a5194ee6b076fb6323ca59</span></span> <span class="giallo-l"><span>3011b7348c16cf58f66b9633906ba54a2ee803187344b394f75dd2e663a57b956cb830dd7a908d4f</span></span> <span class="giallo-l"><span>39a2336a61ef9fda549180d4ccde21514d117b6c6fd07a9102b5efe710a32af4eeacae2cb3b1dec0</span></span> <span class="giallo-l"><span>35b9593b48b9d3ca4c13d245d5f04169b0b1</span></span></code></pre> <p>Node B derives the connection secrets for (Auth₂, Ack₂) as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>aes-secret = 80e8632c05fed6fc2a13b0f8d31a3cf645366239170ea067065aba8e28bac487</span></span> <span class="giallo-l"><span>mac-secret = 2ea74ec5dae199227dff1af715362700e989d889d7a493cb0639691efb8e5f98</span></span></code></pre> <p>Running B's <code>ingress-mac</code> keccak state on the string "foo" yields the hash</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>ingress-mac(&quot;foo&quot;) = 0c7ec6340062cc46f5e9f1e3cf86f8c8c403c5a0964f5df0ebd34a75ddc86db5</span></span></code></pre><h3 id="copyright">Copyright</h3> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2015-11-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 Christian Reitwiessnerc@ethdev.com https://wg-eips.ritovision.com/5/ <h3 id="abstract">Abstract</h3> <p>This EIP makes it possible to call functions that return strings and other dynamically-sized arrays. Currently, when another contract / function is called from inside the Ethereum Virtual Machine, the size of the output has to be specified in advance. It is of course possible to give a larger size, but gas also has to be paid for memory that is not written to, which makes returning dynamically-sized data both costly and inflexible to the extent that it is actually unusable.</p> <p>The solution proposed in this EIP is to charge gas only for memory that is actually written to at the time the <code>CALL</code> returns.</p> <h3 id="specification">Specification</h3> <p>The gas and memory semantics for <code>CALL</code>, <code>CALLCODE</code> and <code>DELEGATECALL</code> (called later as <code>CALL*</code>) are changed in the following way (<code>CREATE</code> does not write to memory and is thus unaffected):</p> <p>Suppose the arguments to <code>CALL*</code> are <code>gas, address, value, input_start, input_size, output_start, output_size</code>, then, at the beginning of the opcode, gas for growing memory is only charged for <code>input_start + input_size</code>, but not for <code>output_start + output_size</code>.</p> <p>If the called contract returns data of size <code>n</code>, the memory of the calling contract is grown to <code>output_start + min(output_size, n)</code> (and the calling contract is charged gas for that) and the output is written to the area <code>[output_start, output_start + min(n, output_size))</code>.</p> <p>The calling contract can run out of gas both at the beginning of the opcode and at the end of the opcode.</p> <p>After the call, the <code>MSIZE</code> opcode should return the size the memory was actually grown to.</p> <h3 id="motivation">Motivation</h3> <p>In general, it is good practice to reserve a certain memory area for the output of a call, because letting a subroutine write to arbitrary areas in memory might be dangerous. On the other hand, it is often hard to know the output size of a call prior to performing the call: The data could be in the storage of another contract which is generally inaccessible and determining its size would require another call to that contract.</p> <p>Furthermore, charging gas for areas of memory that are not actually written to is unnecessary.</p> <p>This proposal tries to solve both problems: A caller can choose to provide a gigantic area of memory at the end of their memory area. The callee can "write" to it by returning and the caller is only charged for the memory area that is actually written.</p> <p>This makes it possible to return dynamic data like strings and dynamically-sized arrays in a very flexible way. It is even possible to determine the size of the returned data: If the caller uses <code>output_start = MSIZE</code> and <code>output_size = 2**256-1</code>, the area of memory that was actually written to is <code>(output_start, MSIZE)</code> (here, <code>MSIZE</code> as evaluated after the call). This is important because it allows "proxy" contracts which call other contracts whose interface they do not know and just return their output, i.e. they both forward the input and the output. For this, it is important that the caller (1) does not need to know the size of the output in advance and (2) can determine the size of the output after the call.</p> <h3 id="rationale">Rationale</h3> <p>This way of dealing with the problem requires a minimal change to the Ethereum Virtual Machine. Other means of achieving a similar goal would have changed the opcodes themselves or the number of their arguments. Another possibility would have been to only change the gas mechanics if <code>output_size</code> is equal to <code>2**256-1</code>. Since the main difficulty in the implementation is that memory has to be enlarged at two points in the code around <code>CALL</code>, this would not have been a simplification.</p> <p>At an earlier stage, it was proposed to also add the size of the returned data on the stack, but the <code>MSIZE</code> mechanism described above should be sufficient and is much better backwards compatible.</p> <p>Some comments are available at https://github.com/ethereum/EIPs/issues/8</p> <h3 id="backwards-compatibility">Backwards Compatibility</h3> <p>This proposal changes the semantics of contracts because contracts can access the gas counter and the size of memory.</p> <p>On the other hand, it is unlikely that existing contracts will suffer from this change due to the following reasons:</p> <p>Gas:</p> <p>The VM will not charge more gas than before. Usually, contracts are written in a way such that their semantics do not change if they use up less gas. If more gas were used, contracts might go out-of-gas if they perform a tight estimation for gas needed by sub-calls. Here, contracts might only return more gas to their callers.</p> <p>Memory size:</p> <p>The <code>MSIZE</code> opcode is typically used to allocate memory at a previously unused spot. The change in semantics affects existing contracts in two ways:</p> <ol> <li> <p>Overlaps in allocated memory. By using <code>CALL</code>, a contract might have wanted to allocate a certain slice of memory, even if that is not written to by the called contract. Subsequent uses of <code>MSIZE</code> to allocate memory might overlap with this slice that is now smaller than before the change. It is, though, unlikely that such contracts exist.</p> </li> <li> <p>Memory addresses change. Rather general, if memory is allocated using <code>MSIZE</code>, the addresses of objects in memory will be different after the change. Contracts should all be written in a way, though, such that objects in memory are <em>relocatable</em>, i.e. their absolute position in memory and their relative position to other objects does not matter. This is of course not the case for arrays, but they are allocated in a single allocation and not with an intermediate <code>CALL</code>.</p> </li> </ol> <h3 id="implementation">Implementation</h3> <p>VM implementers should take care not to grow the memory until the end of the call and after a check that sufficient gas is still available. Typical uses of the EIP include "reserving" <code>2**256-1</code> bytes of memory for the output.</p> <p>Python implementation:</p> <p>old: http://vitalik.ca/files/old.py new: http://vitalik.ca/files/new.py</p> 2015-11-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 Hudson Jamesonhudson@hudsonjameson.com https://wg-eips.ritovision.com/6/ <h3 id="abstract">Abstract</h3> <p>The solution proposed in this EIP is to change the name of the <code>SUICIDE</code> opcode in Ethereum programming languages with <code>SELFDESTRUCT</code>.</p> <h3 id="motivation">Motivation</h3> <p>Mental health is a very real issue for many people and small notions can make a difference. Those dealing with loss or depression would benefit from not seeing the word suicide in our programming languages. By some estimates, 350 million people worldwide suffer from depression. The semantics of Ethereum's programming languages need to be reviewed often if we wish to grow our ecosystem to all types of developers.</p> <p>An Ethereum security audit commissioned by DEVolution, GmbH and <a rel="external" href="https://github.com/LeastAuthority/ethereum-analyses/blob/master/README.md">performed by Least Authority</a> recommended the following:</p> <blockquote> <p>Replace the instruction name "suicide" with a less connotative word like "self-destruct", "destroy", "terminate", or "close", especially since that is a term describing the natural conclusion of a contract.</p> </blockquote> <p>The primary reason for us to change the term suicide is to show that people matter more than code and Ethereum is a mature enough of a project to recognize the need for a change. Suicide is a heavy subject and we should make every effort possible to not affect those in our development community who suffer from depression or who have recently lost someone to suicide. Ethereum is a young platform and it will cause less headaches if we implement this change early on in its life.</p> <h3 id="implementation">Implementation</h3> <p><code>SELFDESTRUCT</code> is added as an alias of <code>SUICIDE</code> opcode (rather than replacing it). https://github.com/ethereum/solidity/commit/a8736b7b271dac117f15164cf4d2dfabcdd2c6fd https://github.com/ethereum/serpent/commit/1106c3bdc8f1bd9ded58a452681788ff2e03ee7c</p> 2015-11-19T00:00:00+00:00 2026-02-11T14:48:25+00:00 Fabian Vogelstellerfabian@ethereum.org Vitalik Buterinvitalik.buterin@ethereum.org https://wg-eips.ritovision.com/20/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for tokens.</p> <h2 id="abstract">Abstract</h2> <p>The following standard allows for the implementation of a standard API for tokens within smart contracts. This standard provides basic functionality to transfer tokens, as well as allow tokens to be approved so they can be spent by another on-chain third party.</p> <h2 id="motivation">Motivation</h2> <p>A standard interface allows any tokens on Ethereum to be re-used by other applications: from wallets to decentralized exchanges.</p> <h2 id="specification">Specification</h2> <h2 id="token">Token</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 token - e.g. <code>"MyToken"</code>.</p> <p>OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present.</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></code></pre><h4 id="symbol">symbol</h4> <p>Returns the symbol of the token. E.g. "HIX".</p> <p>OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present.</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"> symbol</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></code></pre><h4 id="decimals">decimals</h4> <p>Returns the number of decimals the token uses - e.g. <code>8</code>, means to divide the token amount by <code>100000000</code> to get its user representation.</p> <p>OPTIONAL - This method can be used to improve usability, but interfaces and other contracts MUST NOT expect these values to be present.</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"> decimals</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">uint8</span><span>)</span></span></code></pre><h4 id="totalsupply">totalSupply</h4> <p>Returns the total token 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></code></pre><h4 id="balanceof">balanceOf</h4> <p>Returns the account balance of another account with address <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"> balanceOf</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _owner</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 class="z-variable"> balance</span><span>)</span></span></code></pre><h4 id="transfer">transfer</h4> <p>Transfers <code>_value</code> amount of tokens to address <code>_to</code>, and MUST fire the <code>Transfer</code> event. The function SHOULD <code>throw</code> if the message caller's account balance does not have enough tokens to spend.</p> <p><em>Note</em> Transfers of 0 values MUST be treated as normal transfers and fire the <code>Transfer</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"> 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"> _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></code></pre><h4 id="transferfrom">transferFrom</h4> <p>Transfers <code>_value</code> amount of tokens from address <code>_from</code> to address <code>_to</code>, and MUST fire the <code>Transfer</code> event.</p> <p>The <code>transferFrom</code> method is used for a withdraw workflow, allowing contracts to transfer tokens on your behalf. This can be used for example to allow a contract to transfer tokens on your behalf and/or to charge fees in sub-currencies. The function SHOULD <code>throw</code> unless the <code>_from</code> account has deliberately authorized the sender of the message via some mechanism.</p> <p><em>Note</em> Transfers of 0 values MUST be treated as normal transfers and fire the <code>Transfer</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"> 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"> _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></code></pre><h4 id="approve">approve</h4> <p>Allows <code>_spender</code> to withdraw from your account multiple times, up to the <code>_value</code> amount. If this function is called again it overwrites the current allowance with <code>_value</code>.</p> <p><strong>NOTE</strong>: To prevent attack vectors like the one <a rel="external" href="https://docs.google.com/document/d/1YLPtQxZu1UAvO9cZ1O2RPXBbT0mooh4DYKjA_jp-RLM/">described here</a> and discussed <a rel="external" href="https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729">here</a>, clients SHOULD make sure to create user interfaces in such a way that they set the allowance first to <code>0</code> before setting it to another value for the same spender. THOUGH The contract itself shouldn't enforce it, to allow backwards compatibility with contracts deployed before</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></code></pre><h4 id="allowance">allowance</h4> <p>Returns the amount which <code>_spender</code> is still allowed to withdraw from <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"> allowance</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _owner</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"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint256</span><span class="z-variable"> remaining</span><span>)</span></span></code></pre><h3 id="events">Events</h3> <h4 id="transfer-1">Transfer</h4> <p>MUST trigger when tokens are transferred, including zero value transfers.</p> <p>A token contract which creates new tokens SHOULD trigger a Transfer event with the <code>_from</code> address set to <code>0x0</code> when tokens are created.</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"> 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"> uint256</span><span class="z-variable z-other"> _value</span><span>)</span></span></code></pre><h4 id="approval">Approval</h4> <p>MUST trigger on any successful call to <code>approve(address _spender, uint256 _value)</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"> 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"> _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"> _spender</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> _value</span><span>)</span></span></code></pre><h2 id="implementation">Implementation</h2> <p>There are already plenty of ERC20-compliant tokens deployed on the Ethereum network. Different implementations have been written by various teams that have different trade-offs: from gas saving to improved security.</p> <h4 id="example-implementations-are-available-at">Example implementations are available at</h4> <ul> <li><a href="https://wg-eips.ritovision.com/20/./assets/OpenZeppelin-ERC20.sol">OpenZeppelin implementation</a></li> <li><a href="https://wg-eips.ritovision.com/20/./assets/Consensys-EIP20.sol">ConsenSys implementation</a></li> </ul> <h2 id="history">History</h2> <p>Historical links related to this standard:</p> <ul> <li>Original proposal from Vitalik Buterin: https://github.com/ethereum/wiki/wiki/Standardized_Contract_APIs/499c882f3ec123537fc2fccd57eaa29e6032fe4a</li> <li>Reddit discussion: https://www.reddit.com/r/ethereum/comments/3n8fkn/lets_talk_about_the_coin_standard/</li> <li>Original Issue #20: https://github.com/ethereum/EIPs/issues/20</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> 2015-11-19T00:00:00+00:00 2026-02-11T14:49:27+00:00 Martin Holst Swendemartin@swende.se https://wg-eips.ritovision.com/3/ <h1 id="abstract">Abstract</h1> <p>This is a proposal to add a new opcode, <code>CALLDEPTH</code>. The <code>CALLDEPTH</code> opcode would return the remaining available call stack depth.</p> <h1 id="motivation">Motivation</h1> <p>There is a limit specifying how deep contracts can call other contracts; the call stack. The limit is currently <code>256</code>. If a contract invokes another contract (either via <code>CALL</code> or <code>CALLCODE</code>), the operation will fail if the call stack depth limit has been reached.</p> <p>This behaviour makes it possible to subject a contract to a "call stack attack" [1]. In such an attack, an attacker first creates a suitable depth of the stack, e.g. by recursive calls. After this step, the attacker invokes the targeted contract. If the targeted calls another contract, that call will fail. If the return value is not properly checked to see if the call was successful, the consequences could be damaging.</p> <p>Example:</p> <ol> <li>Contract <code>A</code> wants to be invoked regularly, and pays Ether to the invoker in every block.</li> <li>When contract <code>A</code> is invoked, it calls contracts <code>B</code> and <code>C</code>, which consumes a lot of gas. After invocation, contract <code>A</code> pays Ether to the caller.</li> <li>Malicious user <code>X</code> ensures that the stack depth is shallow before invoking A. Both calls to <code>B</code> and <code>C</code> fail, but <code>X</code> can still collect the reward.</li> </ol> <p>It is possible to defend against this in two ways:</p> <ol> <li>Check return value after invocation.</li> <li>Check call stack depth experimentally. A library [2] by Piper Merriam exists for this purpose. This method is quite costly in gas.</li> </ol> <p>[1] a.k.a "shallow stack attack" and "stack attack". However, to be precise, the word ''stack'' has a different meaning within the EVM, and is not to be confused with the ''call stack''.</p> <p>[2] https://github.com/pipermerriam/ethereum-stack-depth-lib</p> <h1 id="specification">Specification</h1> <p>The opcode <code>CALLDEPTH</code> should return the remaining call stack depth. A value of <code>0</code> means that the call stack is exhausted, and no further calls can be made.</p> <h1 id="rationale">Rationale</h1> <p>The actual call stack depth, as well as the call stack depth limit, are present in the EVM during execution, but just not available within the EVM. The implementation should be fairly simple and would provide a cheap and way to protect against call stack attacks.</p> <h1 id="implementation">Implementation</h1> <p>Not implemented.</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> 2015-11-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/2/ <h3 id="meta-reference">Meta reference</h3> <p><a href="https://wg-eips.ritovision.com/606/">Homestead</a>.</p> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>FORK_BLKNUM</th><th>CHAIN_NAME</th></tr></thead><tbody> <tr><td>1,150,000</td><td>Main net</td></tr> <tr><td>494,000</td><td>Morden</td></tr> <tr><td>0</td><td>Future testnets</td></tr> </tbody></table> <h1 id="specification">Specification</h1> <p>If <code>block.number &gt;= HOMESTEAD_FORK_BLKNUM</code>, do the following:</p> <ol> <li>The gas cost <em>for creating contracts via a transaction</em> is increased from 21,000 to 53,000, i.e. if you send a transaction and the to address is the empty string, the initial gas subtracted is 53,000 plus the gas cost of the tx data, rather than 21,000 as is currently the case. Contract creation from a contract using the <code>CREATE</code> opcode is unaffected.</li> <li>All transaction signatures whose s-value is greater than <code>secp256k1n/2</code> are now considered invalid. The ECDSA recover precompiled contract remains unchanged and will keep accepting high s-values; this is useful e.g. if a contract recovers old Bitcoin signatures.</li> <li>If contract creation does not have enough gas to pay for the final gas fee for adding the contract code to the state, the contract creation fails (i.e. goes out-of-gas) rather than leaving an empty contract.</li> <li>Change the difficulty adjustment algorithm from the current formula: <code>block_diff = parent_diff + parent_diff // 2048 * (1 if block_timestamp - parent_timestamp &lt; 13 else -1) + int(2**((block.number // 100000) - 2))</code> (where the <code>int(2**((block.number // 100000) - 2))</code> represents the exponential difficulty adjustment component) to <code>block_diff = parent_diff + parent_diff // 2048 * max(1 - (block_timestamp - parent_timestamp) // 10, -99) + int(2**((block.number // 100000) - 2))</code>, where <code>//</code> is the integer division operator, eg. <code>6 // 2 = 3</code>, <code>7 // 2 = 3</code>, <code>8 // 2 = 4</code>. The <code>minDifficulty</code> still defines the minimum difficulty allowed and no adjustment may take it below this.</li> </ol> <h1 id="rationale">Rationale</h1> <p>Currently, there is an excess incentive to create contracts via transactions, where the cost is 21,000, rather than contracts, where the cost is 32,000. Additionally, with the help of suicide refunds, it is currently possible to make a simple ether value transfer using only 11,664 gas; the code for doing this is as follows:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">from</span><span> ethereum</span><span class="z-keyword"> import</span><span> tester</span><span class="z-keyword"> as</span><span> t</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span class="z-keyword"> from</span><span> ethereum</span><span class="z-keyword"> import</span><span> utils</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> s</span><span class="z-keyword"> =</span><span> t</span><span>.</span><span>state</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> c</span><span class="z-keyword"> =</span><span> s</span><span>.</span><span>abi_contract</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">def init():</span><span class="z-constant">\n</span><span class="z-string"> suicide(0x47e25df8822538a8596b28c637896b4d143c351e)</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-variable"> endowment</span><span class="z-keyword">=</span><span class="z-constant">10</span><span class="z-keyword">**</span><span class="z-constant">15</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> s</span><span>.</span><span>block</span><span>.</span><span>get_receipts</span><span>(</span><span>)</span><span>[</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>]</span><span>.</span><span>gas_used</span></span> <span class="giallo-l"><span class="z-constant">11664</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> s</span><span>.</span><span>block</span><span>.</span><span>get_balance</span><span>(</span><span>utils</span><span>.</span><span>normalize_address</span><span>(</span><span class="z-storage z-type">0x</span><span class="z-constant">47e25df8822538a8596b28c637896b4d143c351e</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-constant">1000000000000000</span></span></code></pre> <p>This is not a particularly serious problem, but it is nevertheless arguably a bug.</p> <p>Allowing transactions with any s value with <code>0 &lt; s &lt; secp256k1n</code>, as is currently the case, opens a transaction malleability concern, as one can take any transaction, flip the s value from <code>s</code> to <code>secp256k1n - s</code>, flip the v value (<code>27 -&gt; 28</code>, <code>28 -&gt; 27</code>), and the resulting signature would still be valid. This is not a serious security flaw, especially since Ethereum uses addresses and not transaction hashes as the input to an ether value transfer or other transaction, but it nevertheless creates a UI inconvenience as an attacker can cause the transaction that gets confirmed in a block to have a different hash from the transaction that any user sends, interfering with user interfaces that use transaction hashes as tracking IDs. Preventing high s values removes this problem.</p> <p>Making contract creation go out-of-gas if there is not enough gas to pay for the final gas fee has the benefits that:</p> <ul> <li>(i) it creates a more intuitive "success or fail" distinction in the result of a contract creation process, rather than the current "success, fail, or empty contract" trichotomy;</li> <li>(ii) makes failures more easily detectable, as unless contract creation fully succeeds then no contract account will be created at all; and</li> <li>(iii) makes contract creation safer in the case where there is an endowment, as there is a guarantee that either the entire initiation process happens or the transaction fails and the endowment is refunded.</li> </ul> <p>The difficulty adjustment change conclusively solves a problem that the Ethereum protocol saw two months ago where an excessive number of miners were mining blocks that contain a timestamp equal to <code>parent_timestamp + 1</code>; this skewed the block time distribution, and so the current block time algorithm, which targets a <em>median</em> of 13 seconds, continued to target the same median but the mean started increasing. If 51% of miners had started mining blocks in this way, the mean would have increased to infinity. The proposed new formula is roughly based on targeting the mean; one can prove that with the formula in use, an average block time longer than 24 seconds is mathematically impossible in the long term.</p> <p>The use of <code>(block_timestamp - parent_timestamp) // 10</code> as the main input variable rather than the time difference directly serves to maintain the coarse-grained nature of the algorithm, preventing an excessive incentive to set the timestamp difference to exactly 1 in order to create a block that has slightly higher difficulty and that will thus be guaranteed to beat out any possible forks. The cap of -99 simply serves to ensure that the difficulty does not fall extremely far if two blocks happen to be very far apart in time due to a client security bug or other black-swan issue.</p> <h1 id="implementation">Implementation</h1> <p>This is implemented in Python here:</p> <ol> <li>https://github.com/ethereum/pyethereum/blob/d117c8f3fd93359fc641fd850fa799436f7c43b5/ethereum/processblock.py#L130</li> <li>https://github.com/ethereum/pyethereum/blob/d117c8f3fd93359fc641fd850fa799436f7c43b5/ethereum/processblock.py#L129</li> <li>https://github.com/ethereum/pyethereum/blob/d117c8f3fd93359fc641fd850fa799436f7c43b5/ethereum/processblock.py#L304</li> <li>https://github.com/ethereum/pyethereum/blob/d117c8f3fd93359fc641fd850fa799436f7c43b5/ethereum/blocks.py#L42</li> </ol> 2015-11-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/7/ <h3 id="hard-fork">Hard Fork</h3> <p><a href="https://wg-eips.ritovision.com/606/">Homestead</a></p> <h3 id="parameters">Parameters</h3> <ul> <li>Activation: <ul> <li>Block &gt;= 1,150,000 on Mainnet</li> <li>Block &gt;= 494,000 on Morden</li> <li>Block &gt;= 0 on future testnets</li> </ul> </li> </ul> <h3 id="overview">Overview</h3> <p>Add a new opcode, <code>DELEGATECALL</code> at <code>0xf4</code>, which is similar in idea to <code>CALLCODE</code>, except that it propagates the sender and value from the parent scope to the child scope, i.e. the call created has the same sender and value as the original call.</p> <h3 id="specification">Specification</h3> <p><code>DELEGATECALL</code>: <code>0xf4</code>, takes 6 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>out_offset</code>: the offset into memory of the output;</li> <li><code>out_size</code>: the size of the scratch pad for the output.</li> </ul> <h4 id="notes-on-gas">Notes on gas</h4> <ul> <li>The basic stipend is not given; <code>gas</code> is the total amount the callee receives.</li> <li>Like <code>CALLCODE</code>, account creation never happens, so the upfront gas cost is always <code>schedule.callGas</code> + <code>gas</code>.</li> <li>Unused gas is refunded as normal.</li> </ul> <h4 id="notes-on-sender">Notes on sender</h4> <ul> <li><code>CALLER</code> and <code>VALUE</code> behave exactly in the callee's environment as they do in the caller's environment.</li> </ul> <h4 id="other-notes">Other notes</h4> <ul> <li>The depth limit of 1024 is still preserved as normal.</li> </ul> <h3 id="rationale">Rationale</h3> <p>Propagating the sender and value from the parent scope to the child scope makes it much easier for a contract to store another address as a mutable source of code and ''pass through'' calls to it, as the child code would execute in essentially the same environment (except for reduced gas and increased callstack depth) as the parent.</p> <p>Use case 1: split code to get around 3m gas barrier</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">~</span><span>calldatacopy</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 0</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-keyword">if</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 class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">253</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> ~</span><span>delegate_call</span><span>(</span><span>msg</span><span>.</span><span>gas</span><span class="z-keyword"> -</span><span class="z-constant"> 10000</span><span>,</span><span class="z-invalid z-illegal"> $</span><span class="z-constant">ADDR1</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-keyword"> ~</span><span>calldatasize</span><span>(</span><span>)</span><span>,</span><span class="z-keyword"> ~</span><span>calldatasize</span><span>(</span><span>)</span><span>,</span><span class="z-constant"> 10000</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> ~</span><span class="z-keyword">return</span><span>(</span><span class="z-keyword">~</span><span>calldatasize</span><span>(</span><span>)</span><span>,</span><span class="z-constant"> 10000</span><span>)</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"> &lt;</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">253</span><span class="z-keyword"> *</span><span class="z-constant"> 2</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> ~</span><span>delegate_call</span><span>(</span><span>msg</span><span>.</span><span>gas</span><span class="z-keyword"> -</span><span class="z-constant"> 10000</span><span>,</span><span class="z-invalid z-illegal"> $</span><span class="z-constant">ADDR2</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-keyword"> ~</span><span>calldatasize</span><span>(</span><span>)</span><span>,</span><span class="z-keyword"> ~</span><span>calldatasize</span><span>(</span><span>)</span><span>,</span><span class="z-constant"> 10000</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> ~</span><span class="z-keyword">return</span><span>(</span><span class="z-keyword">~</span><span>calldatasize</span><span>(</span><span>)</span><span>,</span><span class="z-constant"> 10000</span><span>)</span></span> <span class="giallo-l"><span class="z-constant">...</span></span></code></pre> <p>Use case 2: mutable address for storing the code of a contract:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">if</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword"> /</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">224</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> 0x</span><span class="z-constant">12345678</span><span class="z-keyword"> and</span><span class="z-variable z-language"> self</span><span>.</span><span>owner</span><span class="z-keyword"> ==</span><span> msg</span><span>.</span><span>sender</span><span>:</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>delegate</span><span class="z-keyword"> =</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">4</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"> ~</span><span>delegate_call</span><span>(</span><span>msg</span><span>.</span><span>gas</span><span class="z-keyword"> -</span><span class="z-constant"> 10000</span><span>,</span><span class="z-variable z-language"> self</span><span>.</span><span>delegate</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-keyword"> ~</span><span>calldatasize</span><span>(</span><span>)</span><span>,</span><span class="z-keyword"> ~</span><span>calldatasize</span><span>(</span><span>)</span><span>,</span><span class="z-constant"> 10000</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> ~</span><span class="z-keyword">return</span><span>(</span><span class="z-keyword">~</span><span>calldatasize</span><span>(</span><span>)</span><span>,</span><span class="z-constant"> 10000</span><span>)</span></span></code></pre> <p>The child functions called by these methods can now freely reference <code>msg.sender</code> and <code>msg.value</code>.</p> <h3 id="possible-arguments-against">Possible arguments against</h3> <ul> <li>You can replicate this functionality by just sticking the sender into the first twenty bytes of the call data. However, this would mean that code would need to be specially compiled for delegated contracts, and would not be usable in delegated and raw contexts at the same time.</li> </ul>